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>
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) | ✅ |
|
|
| [`path-discovery.md`](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.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.
|