Routing Redesign — Next-Pass Task List

Research — non-normative

This page is synced from the repo’s docs/research/ tree: exploratory design work, forward-looking plans, or historical analysis. It may describe behavior that is not built or that shipped differently. The normative spec lives in the other docs sections.

Status of the design: CONSOLIDATED (design/security reconciliation, pass 2) — see CONSOLIDATED_ROUTING_PLAN.md. This is not RF sign-off. The RF-touching parts (ERB wire layout, RACK frame, TX/contention timing) still require the /lrc-wire-change checklist and human RF sign-off (AGENTS.md rule 5) before implementation.

Tasks are tagged [HOST] (host-testable, an agent can do it), [WIRE] (golden-byte / /lrc-wire-change event — deliberate, documented), or [RF] (needs physical radios + human sign-off — not closeable by CI or an agent). Do the phases in order; within a phase, follow the dependency notes.

Phase 1 — Pure decision layer first [HOST]

The project’s idiomatic move: build host-tested decision logic before any RF actuation (cf. backbone_best_link, LaneSchedule::promote_client, GossipFanoutPolicy). All of these take caller-provided inputs and need no wire change — they can land and be fully covered by lrc_tests today.

• 1.1 Contention-window delay function — pure f(snr_local, rprog_in, rdist_self, CWsize) → delay_ms, implementing DESIGN §3.2 (SNR term + progress term). Host tests: monotonicity, bounds, the BACKSTOP/CW_BASE floor. Uses locally measured SNR only (threat R3 / Rule D).
• 1.2 Tiered suppression (Rule A) — registered-relay path (verify RACK Tag8 → cancel) vs. keyless path (shorten-only + must-fire-within-T). Host test the load-bearing invariant R1: an honest node always fires within T if it hears no authenticated forward-progress (suppression can delay, never cancel). CONSOLIDATED §Rule A. Implemented as the portable host seam in core/include/lrc/routing_policy.h: routing_contention_window() / routing_contention_delay_ms() for 1.1, and routing_suppression_start() / routing_suppression_apply() for 1.2.
• 1.3 Return Descriptor state machine — modes BROADCAST / RELAY_VIA / LANE_SCHED / UNKNOWN with the observed-delivery gate, the first-contact rule (router-measured BROADCAST or UNKNOWN, never TRAIL-seeded RELAY_VIA), and ttl_quart decay to UNKNOWN. Host tests: TRAIL can propose/order but never admit/pin a candidate; first-contact never RELAY_VIA; poisoned TRAIL decays out (self-heal, R14). DESIGN §4, Issues 1+3. Landed as host-only state in core/include/lrc/return_path.h, covered by tests/test_return_path.cpp; no LPP wire/canonical-image, RF/TX, daemon, or firmware changes.
• 1.4 Self-prune (Rule B) + return-candidate ring — self-only, overheard-real-frame-driven, hard-timer-bounded; pruned relay retained in the return ring under the same observed-delivery gate. Host tests: never prunes another node (R4); pruned-then-needed hop recovers (DESIGN §7.2). Depends on 1.3 (shares the gate). Landed in the same host-only module and tests above.

Phase 2 — Wire specification [WIRE] (/lrc-wire-change)

Greenfield breaking change is acceptable, but it must be a deliberate, documented version event: run the lrc-wire-change skill, update docs/PROTOCOL.md, and add/refresh golden-byte tests. The ERB stays in kMutableMask (unsigned) — justified because no ERB field feeds a trust decision (CONSOLIDATED §6.1). Before implementation, use PHASE2_WIRE_SPEC_PLAN.md as the approval checklist and touch-set map; it is documentation-only prep, not an implemented wire compatibility event.

• 2.1 Edge Routing Block layout (landed in the LPP v2 wire batch, 2026-07-01 — layout confirmed frozen, v2 goldens pin it) — field offsets/sizes for rprog(4b), HINT(1B), RACK_RTR1(1B), TRAIL_LEN+TRAIL[]; retire FLAGS.PATH, reuse the bit as FLAGS.ERB in an LPP v2 layout; update layout() + canonical_image() to cover only that slot; new golden bytes. DESIGN §6.2.
• 2.2 RACK control frame (landed in the LPP v2 wire batch: type 0x2B, host-side auth/classification + goldens; the suppression SCHEDULER remains Phase-4/RF-gated) — group C, PRIO, TTL=1, SK-Tag8 + src-check (Rule C), and a covered target_dedup_key + boot_id/counter payload so the freshness and same-logical-frame proof is explicit. PROTOCOL.md + golden bytes.
• 2.3 “Observed successful delivery” frame/flag (landed with the v2 batch — see PROTOCOL.md for the pinned mechanism) — pin the exact mechanism (relay-sourced delivery confirmation or router overhearing the relay forward its downlink). CONSOLIDATED follow-up #1 — under-specified at design altitude on purpose; choose one and spec it. Planning recommendation: start with router-overhearing as the trust-producing event, and defer any relay-sourced confirmation frame until its authentication/freshness story is separately approved. Depends on 2.1/2.2.

Phase 3 — Simulation, tuning & attack coverage [HOST]

• 3.1 Edge-mesh chaos scenarios — extend tests/test_chaos.cpp: assert no permanent black-hole under the suppression rule, asymmetric-return correctness, prune-then-need recovery, and the threat catalogue bounded as claimed (suppression-abuse grayhole bounded by R1; SNR-spoof inert by R3; TRAIL-poison decays by R14; Sybil airtime bounded by TTL+dedup). Initial host-policy threat scenarios now exercise core/include/lrc/routing_policy.h and core/include/lrc/return_path.h, but this remains unchecked until the chaos harness covers the integrated multi-node ERB/RD behavior after the Phase 2 wire event.
• 3.2 Calibrate CWsize constants — k_snr, k_prog, CW_BASE, prog_gain clamp are currently set by analogy to Meshtastic’s 2..7 range, not measured. Sweep in sim to avoid oscillation / mid-distance-relay starvation. DESIGN §11 open Q2. Depends on 1.1, 3.1. Host-policy guard landed as routing_contention_sweep() / routing_contention_sweep_ok(), which sweeps SNR rung and raw progress gain to pin CW_BASE, k_snr, k_prog, and the prog_gain clamp while flagging inert terms, adjacent-CW oscillation, and mid-distance starvation risk. Covered by tests/test_routing_policy.cpp and tests/test_chaos.cpp. This is not RF field calibration.
• 3.3 RD mode-flap hysteresis — establish the run-length + SNR margin that stops BROADCAST↔RELAY_VIA flapping under mobility (analogous to the promotion lifecycle demote-run, but for return; likely region/preset dependent). DESIGN §11 open Q3. Depends on 1.3. Host-policy state landed as ReturnModeHysteresisPolicy / ReturnModeHysteresisState plus rd_apply_mode_hysteresis(), requiring same-relay run length and SNR margin for BROADCAST→RELAY_VIA, and direct run length plus SNR margin for RELAY_VIA→BROADCAST. Covered by tests/test_return_path.cpp and tests/test_chaos.cpp.

Phase 4 — RF hardware validation + human sign-off [RF]

Gated by AGENTS.md rule 5. An agent cannot close these. Use PHASE4_RF_VALIDATION_PLAN.md for the bench/field checklist and evidence template. Leave these unchecked until measured radio evidence and human RF sign-off are recorded in the PR and committed on main.

• 4.1 Foreign-relay collapse-cost measurement — measure on real radios how much “instant collapse” is lost when keyless relays fall back to shorten-only suppression (the residual of DESIGN §11 open Q1, now reconciled by Rule A). Record equipment, topology, physical TX counts, airtime deltas, delivery latency, CAD/duty counters, raw logs, and the decision on whether registered-relay incentives are worth adding.
• 4.2 Bench/field TX-timing validation — ERB/RACK on-air behavior, the contention window vs. CAD/duty-cycle interaction, and asymmetric return on a multi-radio bench. Record independent on-air timing, computed-vs-observed fire times, CAD/backoff and duty-cycle evidence, observed-delivery gate behavior, receive-only/retune safety checks, and human RF sign-off per rule 5.

Tracked accepted residuals (not tasks — monitor, do not “fix”)

From THREAT §6, charter-consistent: confidentiality/traffic-flow out of scope (R-residual-1); wormhole/rushing contained not prevented (R-2); Sybil at the unauthenticated relay layer is free (R-3); short per-hop tags are tripwire-grade (R-4); a rogue/compromised router is inside the trust boundary (R-5); suppression honoring R1 costs some latency (R-6).

Suggested critical path

1.1 → 1.2 → 1.3 → 1.4 (host primitives, immediately startable) ‖ 2.1 → 2.2 → 2.3 (wire spec, parallelizable with Phase 1) → 3.1 → {3.2, 3.3} (sim + tuning) → 4.1, 4.2 (RF, human-gated, last). Phase 1 is the highest-value next pass: it converts the reconciled design into host-tested intent with zero RF risk, exactly as the rest of chIRpChat’s decision layers were built.