jlpoole/reticiulum-specification
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
reticiulum-specification/flows
History
Rob 95823ad840 Add §10 Resource fragmentation + send-resource flow 
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>
2026-05-03 11:08:40 -04:00
..
README.md Add §10 Resource fragmentation + send-resource flow 2026-05-03 11:08:40 -04:00
receive-announce.md Add receive-announce flow + SPEC §4.5 validation rules 2026-05-03 10:56:11 -04:00
receive-opportunistic-lxmf.md Add flows/ docs: receive-opportunistic and send-link 2026-05-03 10:24:24 -04:00
send-link-lxmf.md Add flows/ docs: receive-opportunistic and send-link 2026-05-03 10:24:24 -04:00
send-opportunistic-lxmf.md Add flows/ directory with opportunistic-LXMF send sequence 2026-05-03 10:15:03 -04:00
send-resource.md Add §10 Resource fragmentation + send-resource flow 2026-05-03 11:08:40 -04:00

README.md

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) ✅
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 §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.