← RFC

Loomwave — Design Decision (Checkpoint B)

Status: Stage 2 complete. Checkpoint B PASSED (human sign-off 2026-06-09) — cleared for Stage 3 (protocol spec). Next gate: Checkpoint C (review specs before any firmware). Date: 2026-06-08 (decision), signed off 2026-06-09.

This is the document CLAUDE.md requires before firmware: it cites specific simulation results to justify the chosen MAC and routing, and sketches the packet format with byte-level detail. It supersedes the model-derived stage1-synthesis-and-sim-plan.md as the decision of record — every headline number below is now measured, not projected. Per-experiment detail lives in the analysis/*-result.md docs; reproduce any of it from the tagged sim-result-v<n> commits.

---

1. Decision, in one paragraph

Build Loomwave as a hybrid CSMA-discovery + TDMA-data MAC with an INFRA node as time / slot / modulation / channel authority, an INFRA-aggregated distance-vector routing control plane, an epoch-hash-slotted coordinator-free fallback, per-cell adaptive modulation + spatial reuse for scale, and per-packet AEAD security. The simulation confirms this design is never worse than a Meshtastic-grade flood network and strictly better wherever a coordinator — or even a shared clock — exists. The two rejected alternatives (pure-CSMA-smarter-flood; source-routing-without-TDMA) fail on the measured numbers below.

2. The evidence (Stage-2 simulation)

Every Stage-1 claim, now measured. Sim is a SimPy discrete-event model with a LoRa PHY whose airtime is cross-checked against the Semtech/Meshtastic formula (65 passing tests).

Tag	Claim under test	Measured result	Doc
v1	Flooding collapses; hidden node is dominant	Flood knee at N≈11 (LongFast); hidden-node loss 15/27/55/77% at K=10/20/50/100, matching ALOHA	meshtastic-routing-analysis, baseline
v2	Model reproduces reality	Qualified pass: channel-util median 3.7% vs real 5.7% (within ~1.5×); tails under-predicted by isolated-cluster scope — licenses relative comparisons	north-georgia-validation.md
v3	TDMA removes hidden-node loss	99.8/99.6/99.2/96.5% delivery vs CSMA's 88/74/50/23% at K=10/20/50/100; <5 collisions vs thousands; 98–99% efficient	tdma-data-plane-result.md
v4	Adaptive modulation beats the ceiling	×16 capacity (50 nodes); 500-node 1 msg/4 min → 8 msg/min (×34); spatial reuse robust via capture	adaptive-modulation-result.md
v5	INFRA-aggregated DV control is O(N)	Flooded link-state 1441% (collapsed) vs INFRA-DV ~62%→tunable to ~12% at N=100; ~23× cheaper	routing-control-result.md
v6	Graceful coordinator-free fallback	epoch-hash > CSMA at every K; static-hash collapses; TDMA ceiling; degradation curve never below the CSMA floor	fallback-result.md
v7	All 3 scenario classes, 2 MAC variants (delivery / latency-CDF / channel-util)	TDMA wins at scale (dense 0.96 vs flood 0.35; nbhd 0.98 vs 0.88) at ⅛ the channel; flood fine below the knee (sparse) — closes "done" criteria #2/#3	scenario-suite-result.md
v8	Propagation calibrated vs real per-gateway SNR/RSSI (public Malla API)	exponent n≈2.5 confirms the assumed 2.7; gate mean channel-util now matches real (7.4% vs 7.0%); residual tail confirmed structural	propagation-calibration-result.md

The validation caveat that governs all of it (v2, now refined by v8): the propagation model is now calibrated against real per-gateway SNR/RSSI (public Malla API) — exponent confirmed, and the gate's mean channel-util matches the real network (7.4% vs 7.0%). The real distribution's upper tail is still not reproduced, now confirmed structural (co-channel / gateway / diurnal effects an isolated, steady-state single-cluster sim excludes). Every decision below rests on relative comparisons on identical topology + traffic, where that residual cancels.

Comparison-methodology rule (red-team F15) — governs every number above and the RFC paper. The production case studies (case-study-meshtastic.md) establish that ~3–5× capacity is available to Meshtastic by configuration alone (cadence cuts, hop-limit discipline, router-role hygiene). Therefore a meaningful share of any "Loomwave vs flood" delta is our sensible defaults vs their reckless defaults, not architecture. To keep the comparison honest:

1. Every Loomwave-vs-incumbent figure MUST compare against a tuned incumbent (sane beacon cadence, disciplined hop limit, enforced roles), not its out-of-box defaults.
2. Each reported delta MUST attribute how much is architecture (scheduled access, adaptive modulation, registered membership — unreachable by any incumbent config) versus defaults (recoverable by tuning). The architectural wins are the load-bearing claims; the default wins are not Loomwave's to claim.
3. The v3/v7 flood baselines above are sim-default floods; before the RFC paper they MUST be re-run against a tuned flood so the architectural margin is reported separately from the defaults margin. Until then, treat the headline multipliers as upper bounds on the architectural win.

The cleanest architecture-only result — the one no incumbent config can touch — is v4 adaptive modulation (×16–34), because it requires a coordinator role Meshtastic/MeshCore cannot express. That is the result to lead with; the flood-vs-TDMA deltas need the tuned-baseline split before they carry the same weight.

The problem these decisions answer (v1):

And it isn't hypothetical — it's observed live. Subscribing to the Nano Newt relay atop Stone Mountain shows the exact v1/v3 topology in the wild: 12+ positioned nodes heard directly, ~92% of their pairs too far apart to hear each other, median link SNR right at the decode margin (stone-mountain-hidden-node-hub.md). The hidden-node hub the MAC is built to solve is a real high site, not a thought experiment.

3. MAC — hybrid CSMA-discovery + TDMA-data ✅ decided

• Data plane: TDMA, INFRA beacon as slot/time authority. v3 shows it eliminates the hidden-node loss that crushes CSMA (the project's central challenge) and runs at 98–99% efficiency — collision-free by construction, GPS-free (~3 ms guard).
• Discovery plane + no-coordinator fallback: epoch-hash-slotted ALOHA, not CSMA flood. v6: epoch-hash beats CSMA for hidden nodes at every K because it needs no carrier sense. Static-hash is rejected (collapses below CSMA at scale).
• One frame structure (TDMA schedule + reserved contention window) spans both modes; switching is the fail-safe degradation path (mode-and-handoff-note.md).
• Rejected — pure CSMA / smarter flood: v1 shows it collapses by N≈11 and cannot fix hidden node in principle.

4. Routing — INFRA-aggregated distance-vector ✅ decided

• Self-certifying addresses (Reticulum-style), scheduled unicast client registration, small next-hop forwarding table, link-state only among the few INFRA nodes, rate-capped flood discovery.
• v5: mesh-wide flooded link-state is unusable (1441% of channel, collapsed, by N=100), while INFRA-DV stays O(N) and tunes to the ~12–20% budget via registration cadence. ~23× cheaper.
• Rejected — mesh-wide link-state (O(N²) collapse) and source-routing-without-TDMA (inherits the hidden-node loss v3 removes).
• INFRA-absent ⇒ AODV-style on-demand over the epoch-hash fallback.
• Coordinator membership is by measured vantage + link budget, not by config role. Real node-DB data shows the role field is an unreliable signal for who is actually a high site: of 8 real elevated relays, 4 are role-missed (labeled CLIENT_MUTE or unset) yet sit 96–330 m above their neighbors (elevated-nodes.md). So "the few INFRA nodes" that carry the link-state backbone must be selected by elevation/link budget, with role as at most a hint — the mechanism is a Stage-3 item (§8). Encouragingly, those 8 high sites already cross-reference into a single connected backbone — 15 candidate elevated-to-elevated links, region spanned in 2–3 hops (high-site-backbone.md) — confirming this section's premise that link-state runs among a small, connected INFRA set. That analysis also exposes a structural risk the fallback (§3) answers: a keystone site (BSRG) is a north–south cut vertex, so backbone partition is a real failure mode, not a hypothetical.

5. Scale — adaptive modulation + spatial reuse (Q3) ✅ decided

• INFRA is the modulation + channel authority: each cell runs the fastest SF its clients' link budgets allow; multi-radio runs reach + capacity planes (hardware deferred to Stage 4, capability modeled).
• v4: ×16 capacity at 50 nodes; the 500-node single-domain ceiling (1 msg/4 min) dissolves to 8 msg/min (×34). Capture makes spatial reuse robust to imperfect separation; clean by ~1.5× the SF range. Open: boundary-client cost + measured-link-budget SF selection (Stage 3).
• The multi-radio INFRA node this section assumes is already real in the wild: the backbone analysis found Rky/RFM1 co-located (0 km apart) at a central keystone — one tower carrying two radios on reach + capacity planes (high-site-backbone.md).
• Backhaul→air injection is coordinator-governed, never raw re-broadcast (Stage-3 rule). Because INFRA is the airtime/slot authority, any backhaul-sourced (e.g. MQTT) packet bound for RF is admission-controlled into the TDMA schedule (collision-free even at a hidden-terminal hub), budget-capped (a fraction of channel airtime — can't starve local traffic), traffic-classed (§7 — bridged telemetry behind local interactive/emergency), and locality-filtered. This structurally prevents the real Meshtastic failure where misconfigured downlink_enabled dumps an internet-scale source onto shared airtime — worst at an elevated relay, the largest hidden-terminal domain (the live Stone Mountain case, stone-mountain-hidden-node-hub.md). Exact governance parameters (cap fraction, filter policy) are Stage 3.

6. Security — per-packet AEAD ✅ decided (analysis-backed; not a sim variable)

Static X25519 identities, implicit ECDH (no wire handshake), per-message AEAD with derived nonce (0 wire bytes) + 8-byte truncated tag, sequence + sliding-window replay (no clock sync), Ed25519-signed adverts only. ~16 B/packet, ~0% beyond the MAC budget (security-options.md). Tag length (8 vs 6 B) is a Stage-3 call.

7. Packet format sketch (byte-level — the Checkpoint-B deliverable)

255 B LoRa frame. Data packet (the common case), 16 B overhead → 239 B payload:

 byte  field                        bits/notes
 0     VER_FLAGS                     [7:5] version  [4:2] traffic_class (6 classes)
                                     [1] plane (0=contention,1=scheduled)  [0] ack_req
 1     HOPS                          [7:4] hop_limit  [3:0] hops_used
 2..4  SRC_ADDR (24-bit)            truncated self-certifying address (collision-checked)
 5..7  DST_ADDR (24-bit)            0x000000 = broadcast/channel
 8     SEQ                           sequence no. (sliding-window replay; nonce-derived)
 9..N  PAYLOAD                       up to 239 B (AEAD-encrypted)
 N+1.. AEAD_TAG (8 B)               truncated Poly1305/GCM tag; nonce = H(SRC||SEQ||epoch), 0 wire B

• Header = 9 B, tag = 8 B → 16 B overhead, matching the analysis (239 B payload in 255 B). The 3-bit traffic_class (emergency/control/interactive/telemetry/bulk/discovery) costs 0 extra airtime (traffic-prioritization-note.md).
• Schedule beacon (INFRA → clients): VER_FLAGS, frame epoch, (sf,bw,freq) cell descriptor, slot map / next-slot pointer, Ed25519 signature (amortized, rate-capped). Small + periodic → measured v3 control < 15%.
• Registration (client → INFRA, unicast along next-hop): SRC, claimed slot/capability, link SNRs for the modulation-authority decision. ~16 B; v5 cost is O(N), cadence-tunable.

This is a sketch for review, not the frozen wire format — that is Stage 3 (packet-format.md), written in RFC-normative style so it doubles as the paper's protocol section.

8. What is validated vs. still open

Validated (relative, measured): flood collapse + hidden-node dominance; TDMA hidden-node elimination + efficiency; INFRA-DV O(N) control; adaptive-modulation ×16/×34 capacity; epoch-hash fallback ordering; all three scenario classes under ≥2 MAC variants with delivery/latency-CDF/ channel-util (v7 — closes the CLAUDE.md Stage-2 "done" criteria). Open before/at Stage 3: absolute calibration to the real network (DB export — v2); boundary-client SF/cell association; live TDMA↔fallback switching MAC; coordinator selection/election by measured vantage + link budget (role is unreliable — elevated-nodes.md); security tag length + per-role replay/reboot; final traffic-class set + weights.

9. Checkpoint B ask

Confirm the design of record (§§3–6) and the packet-format direction (§7) so Stage 3 (protocol spec, RFC-normative) can begin. No firmware until this is signed off (CLAUDE.md: the cost of rebuilding firmware on a wrong protocol dwarfs a review pause). The RFC paper (incl. the Meshtastic/MeshCore differentiation section) assembles from these results + the Stage-3 spec.