0bf03d924d
Closes Tier 1 #5. The previous §7.2 was four bullet points naming the "answer with an announce" rule but missing every wire detail — implementation-time the SF mobile client got steps 4 (dedup) and 5 (local-destination check) wrong on its first cut and the bug only surfaced as "I can message my own destination but no one else can reply". §7.2 is now six sub-sections: §7.2.1 Path-request packet parse rules. The handler's slice recipe with branching on payload length (32B = leaf form target||tag; 48B+ = transport form target||transport_id|| tag); tag cap at 16B; tagless-request rejection. §7.2.2 Tag-based dedup via Transport.discovery_pr_tags. The unique_tag = dest_hash || tag construction, the 32000- entry cap, why missing this turns a leaf into a broadcast- storm amplifier on retransmits. §7.2.3 The five-way dispatch in Transport.path_request: local-destination / transit-knows-path / local-client- forward / discovery-recursive / drop. Branches 1 and 5 are the only ones a leaf needs. §7.2.4 Path-response announce wire format. Body byte-identical to a regular announce (§4.1); only the outer packet context byte differs (NONE → PATH_RESPONSE 0x0B). PR_TAG_WINDOW=30s body-cache that serves identical wire bytes to racing relays so transit dedup converges. §7.2.5 Timing constants: PATH_REQUEST_GRACE = 0.4s, + PATH_REQUEST_RG = 1.5s for roaming-mode interfaces. Local-destination and local-client originator branches bypass the grace. §7.2.6 Minimum responsibility for a non-transport leaf — the six-step protocol-level recipe. flows/path-discovery.md: 9-step chronology covering both single-hop leaf-owns-target and two-hop transit-relay-knows-path cases. Wire-byte ladder diagrams for both. Notes the ingress-limit bypass for path-responses (Transport.py:1632-1639), the receive_path_responses opt-in for handler dispatch (Transport.py:1989-1991), and the timeout/escalation path through LXMRouter.process_outbound's MAX_PATHLESS_TRIES retry counter. flows/README.md status table updated. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2.7 KiB
2.7 KiB
Flows
End-to-end chronological narratives for common Reticulum operations. Where 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 |
✅ |
receive-opportunistic-lxmf.md |
✅ |
send-link-lxmf.md (DIRECT method, over a Reticulum Link) |
✅ |
receive-announce.md |
✅ |
send-resource.md (Resource fragmentation over a Link) |
✅ |
path-discovery.md (path? request, path-response wire detail, path-table population) |
✅ |
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) |
⏳ |
Conventions
- Each flow targets one specific upstream operation.
send-opportunistic-lxmf.mddocuments whatLXMRouter.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 lxmfinstall 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§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.