5574d3bed3
Documents the outbound retry layer that wraps the existing per-method send-* flows. Pinned to LXMF 0.9.7 / RNS 1.2.4 with literal-quoted upstream source for every claim: - 4-second tick cadence (PROCESSING_INTERVAL × JOB_OUTBOUND_INTERVAL) - All seven retry constants (MAX_DELIVERY_ATTEMPTS, DELIVERY_RETRY_WAIT, PATH_REQUEST_WAIT, MAX_PATHLESS_TRIES, MESSAGE_EXPIRY, LINK_MAX_INACTIVITY, P_LINK_MAX_INACTIVITY) at LXMRouter.py:30-38 - Eight-state machine (GENERATING/OUTBOUND/SENDING/SENT/DELIVERED/ REJECTED/CANCELLED/FAILED) at LXMessage.py:13-22 - The four terminal-state branches at top of process_outbound (lines 2517-2558) and the three per-method retry branches (OPPORTUNISTIC 2566-2592, DIRECT 2596-2673, PROPAGATED 2677-2730) - fail_message semantics at LXMRouter.py:2395-2402 Includes a "what does NOT happen" section calling out common misconceptions: no automatic DIRECT→PROPAGATED fallback, no exponential backoff, no in-router persistence of pending_outbound, MESSAGE_EXPIRY governs the propagation-node store not per-sender retries, SENT is the terminal success state for PROPAGATED (not DELIVERED). No verifier needed per agent.md §1 — all claims are direct upstream source citations. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
30 lines
3 KiB
Markdown
30 lines
3 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`](receive-resource.md) (inverse of send-resource: ADV ingestion, part assembly, proof emission) | ✅ |
|
|
| [`receive-link-lxmf.md`](receive-link-lxmf.md) (inverse of send-link-lxmf, including responder side of the handshake) | ✅ |
|
|
| [`send-announce.md`](send-announce.md) (build, sign, transmit, ratchet rotation, periodic re-announce) | ✅ |
|
|
| [`forward-announce.md`](forward-announce.md) (transport-node rebroadcast logic, announce_cap, queue) | ✅ |
|
|
| [`send-propagated-lxmf.md`](send-propagated-lxmf.md) (PROPAGATED method, via a propagation node) | ✅ |
|
|
| [`receive-propagated-lxmf.md`](receive-propagated-lxmf.md) (recipient pulling messages via `/get`) | ✅ |
|
|
| [`lxmf-outbound-retry.md`](lxmf-outbound-retry.md) (process_outbound retry loop, per-message state machine, fail_message) | ✅ |
|
|
|
|
## 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.
|