Adaptive channel migration for fixed-channel video links

[josephnef]

Slow, evidence-driven whole-link channel migration for a fixed-channel FPV video link — the deliberate complement to per-slot FHSS. The link normally sits on one channel and moves rarely, only when a second radio has proven a better home exists. Five composable, independently useful layers, all pure caller-side logic under src/chanmig/ (header-mostly, each ctest-covered; the library reads no environment — the demos map it).

What it adds

• Passive dual-radio spectrum scout (chanscout). A second adapter continuously surveys a candidate-channel plan while the primary receiver stays parked on the live video channel. Measures and records only — it retunes nothing but its own adapter and issues no channel-change command. A discard barrier makes each versioned survey record's FA/CCA counters (which are delta-on-read) span exactly its observation window on one bin, and decoded airtime is split into recognized-own-video vs foreign so wanted airtime is never read as interference. Grid-legality validation only — no regulatory database; the caller owns compliance.
• Advisory recommendation engine (ChannelScore). A pure two-leg policy: the primary receiver's delivery is authoritative on the active channel (scout energy there is confounded by wanted video), the scout's occupancy on candidates. A move needs persistent channel-attributable impairment AND a materially cleaner, sufficiently observed candidate — never a single threshold; weak-signal and near-field saturation are held as non-channel faults. Every decision cites an evidence generation + plan/policy hash and is explainable from the logs (a stdlib dashboard and a shadow-mode confusion-matrix replay render purely from them).
• Authenticated coordinated migration protocol. Ground proposes; the drone video transmitter validates and is the final schedule authority. A SipHash-MAC'd byte-packed wire codec, random per-boot epochs (no persisted in-flight state), and pure proposer/responder state machines. Two rules make every failure case converge without split-brain: the drone arms activation only after the ground echoes its nonce, and the ground follows the drone's authoritative status rather than declaring success unilaterally. Control frames are their own canonical-SA 802.11 frames — video payload bytes are never touched.
• Conservative autonomous policy (MigGate). Modes off / advisory / manual / automatic (default advisory); a pure deterministic gate that proposes only under a conservative conjunction and hedges every move with cooldown, residency, per-channel exponential backoff, a session move cap, probation, and an operator kill switch. Fault-domain classification keeps migration from being used to "fix" a weak signal, broad interference, saturation, or a USB/scout fault.
• Optional drone-side target validation. Legality/caps checks (the product default) reject an unsupported target before commit at zero cost; an opt-in abort-safe single-radio pre-commit probe is retained as research (it costs a real, measured video outage), and a post-switch probation window covers the after-the-fact case. The drone's result is reporting-only.

Validation

• Headless (exhaustive): a failure matrix that drops, duplicates, reorders, replays, and restarts every message and endpoint and proves both ends converge to a shared channel with no lasting split-brain; known-answer wire vectors with a byte-flip tamper sweep; the scoring and gate scenario matrices with a determinism guarantee. All selftests green.
• On hardware: the scout's ≥10,000-retune stress runs wedge-free (post-run adapter graded healthy), and the control wire codec decodes and authenticates end-to-end. The RX frame's trailing FCS and the demo's multi-thread state-machine access were the two bring-up bugs found and fixed, now pinned by tests.
• Bench note: the on-air whole-link migration endurance needs a decoupled adapter pair — a near-field pair saturates the RX front end and the reverse control path is intermittent, and the in-tree rtw88/rtw89 modules must be unbound (they auto-probe on every enumeration).

Docs

docs/adaptive-channel-migration.md, docs/channel-migration-protocol.md, docs/channel-migration-validation.md, the event registry in docs/logging.md, and a CLAUDE.md capability section.

🤖 Generated with Claude Code