95823ad840
Closes Tier 1 #2. Without this, a client can't send any LXMF body larger than LINK_PACKET_MAX_CONTENT ≈ 360 B, can't receive a NomadNet page that doesn't fit in one MTU, and can't transfer files via rncp. SPEC.md §10 (new): full Resource fragmentation protocol with citations to RNS/Resource.py. 13 sub-sections covering preparation pipeline (metadata prefix → optional bz2 → random_hash prefix → SHA-256 over data||random_hash → link.encrypt of the WHOLE blob → part-split into SDU-sized chunks → 4-byte map_hash hashmap with collision guard within COLLISION_GUARD_SIZE = 2*WINDOW_MAX + HASHMAP_MAX_LEN), wire context inventory (RESOURCE_ADV / RESOURCE / RESOURCE_REQ / RESOURCE_HMU / RESOURCE_PRF / RESOURCE_ICL / RESOURCE_RCL), the msgpack dict for the advertisement (t/d/n/h/r/o/i/l/q/f/m), the request payload format with the hashmap_exhausted sentinel, the lazy-hashmap RESOURCE_HMU continuation that lets large hashmaps avoid breaking small-MTU links, the proof body resource_hash(32) || full_proof = SHA256(data||hash) (32) returned in a PROOF-type packet, the sliding window dynamics (WINDOW=4 → WINDOW_MAX_FAST=75 / WINDOW_MAX_VERY_SLOW=4 with rate detection), multi-segment cutover at MAX_EFFICIENT_SIZE = 1 MiB - 1 with the lazy `__prepare_next_segment` pattern, and the encryption-before-split layering that means a missing part can't be decrypted in isolation. flows/send-resource.md: 10-step chronology from RNS.Resource() construction through advertise → req/parts loop → HMU continuation → final RESOURCE_PRF → multi-segment fan-out, with a wire-byte ladder diagram and a per-step source map. Side fixes found while drafting: - SPEC.md §2.5 contexts table was wildly incomplete and had a real bug: KEEPALIVE was listed as 0xFD; upstream is 0xFA per RNS/Packet.py:87. 0xFD is actually LINKPROOF (the regular DATA-receipt context, §6.5). Replaced with the full upstream context inventory: NONE, RESOURCE_*, CACHE_REQUEST, REQUEST, RESPONSE, PATH_RESPONSE, COMMAND, COMMAND_STATUS, CHANNEL, KEEPALIVE, LINKIDENTIFY, LINKCLOSE, LINKPROOF, LRRTT, LRPROOF. - SPEC.md §6.5 reworded: "send back a PROOF packet (no context byte specifics)" → "send back a PROOF-type packet with context = LINKPROOF (0xFD)" for clarity. - The previously-numbered §10 "Test vectors" and §11 "Source map" are renumbered to §11 / §12 so the new Resource section lands in its correct protocol-stack position. agent.md §5 audit table updated accordingly. flows/README.md status table updated; receive-resource.md added as the next pending flow. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
28 lines
2.7 KiB
Markdown
28 lines
2.7 KiB
Markdown
# Flows
|
|
|
|
End-to-end chronological narratives for common Reticulum operations. Where [`SPEC.md`](../SPEC.md) is organized by *layer* (identity, header, token crypto, announce, LXMF, link, transport, framing), the documents here are organized by *operation* and walk through what each layer contributes in order — app-call → wire bytes.
|
|
|
|
The two views are complementary: SPEC.md tells you what each piece looks like; the flows tell you when each piece runs and what calls what. A flow document should not introduce new normative claims — every byte-level detail should be a cross-reference to the relevant SPEC.md section. If you find yourself describing wire bytes here that aren't in SPEC.md, that's a sign the spec has a gap to fill.
|
|
|
|
## Status
|
|
|
|
| Flow | Status |
|
|
|---|---|
|
|
| [`send-opportunistic-lxmf.md`](send-opportunistic-lxmf.md) | ✅ |
|
|
| [`receive-opportunistic-lxmf.md`](receive-opportunistic-lxmf.md) | ✅ |
|
|
| [`send-link-lxmf.md`](send-link-lxmf.md) (DIRECT method, over a Reticulum Link) | ✅ |
|
|
| [`receive-announce.md`](receive-announce.md) | ✅ |
|
|
| [`send-resource.md`](send-resource.md) (Resource fragmentation over a Link) | ✅ |
|
|
| `receive-resource.md` (inverse of send-resource: ADV ingestion, part assembly, proof emission) | ⏳ |
|
|
| `receive-link-lxmf.md` (inverse of send-link-lxmf, including responder side of the handshake) | ⏳ |
|
|
| `send-propagated-lxmf.md` (PROPAGATED method, via a propagation node) | ⏳ |
|
|
| `send-announce.md` (build, sign, transmit, ratchet rotation, periodic re-announce) | ⏳ |
|
|
| `forward-announce.md` (transport-node rebroadcast logic, announce_cap, queue) | ⏳ |
|
|
| `path-discovery.md` (path? request, path-response wire detail, path-table population) | ⏳ |
|
|
|
|
## Conventions
|
|
|
|
- Each flow targets one specific upstream operation. `send-opportunistic-lxmf.md` documents what `LXMRouter.handle_outbound(lxm)` does for an opportunistic message; it does not also cover Link or propagation paths — those get their own docs so the chronology stays linear.
|
|
- Numbered steps are chronological. Each step that produces wire bytes cross-references the SPEC.md section that defines those bytes.
|
|
- Source citations use the standard `pip install rns lxmf` install layout (`RNS/`, `LXMF/`) with file + line. Line numbers are pinned to the RNS / LXMF version named at the top of each flow; out-of-date line numbers should be fixed in a PR.
|
|
- "Verified" claims must be backed by a `tools/` script per [`../agent.md`](../agent.md) §1. Flow docs inherit the verification status of the SPEC.md sections they reference — if a flow step relies on an unverified SPEC.md callout, the flow should mark that step as inheriting the unverified status rather than silently treat it as fact.
|