Adaptive channel migration 3/5: authenticated manual proposal, commit, verify, and rollback

[josephnef]

Summary

Implement a reliable, authenticated operator-triggered coordinated channel migration between the ground receiver and drone video transmitter. The recommendation from #277 is displayed to the operator, but only explicit approval starts the protocol. No autonomous switching in this stage.

Experiment 3 of 5; depends on trustworthy sensing/scoring from #276 and #277. Reuse the epoch/authentication/future-activation principles from #263 where appropriate, but this is a rare whole-link move, not a changing FHSS hopset.

Terminology

Devourer raw monitor/injection endpoints are not ordinary associated stations whose kernel MLME automatically follows an 802.11 CSA. Implement a private versioned control protocol; optionally mirror the target/countdown in a standard CSA IE for sniffers/interoperability experiments. Do not claim standard CSA behavior unless an associated-client test proves it.

Authority and state machine

Ground proposes; the drone TX validates and becomes final schedule authority by committing an activation point.

STABLE(old)
  -> PROPOSED(epoch,target,evidence)
  -> COMMITTED(epoch,target,activate_at,fallback)
  -> SWITCHING
  -> VERIFYING(new)
  -> CONFIRMED(new)
  or ROLLBACK(old) / RECOVERY

Neither endpoint may retune on PROPOSAL. Both act only on an authenticated matching COMMIT.

Wire protocol

Define canonical encodings and authentication for:

• SwitchProposal: protocol version, link/base identity, boot epoch, monotonic generation, source and full target ChannelDef, evidence generation/digest, earliest/latest activation, fallback policy, nonce, MAC.
• SwitchCommit: accepted generation/target, absolute activation round/time, confirmation window, rollback deadline/channel, nonce binding, MAC.
• SwitchStatus: current epoch/generation/channel/state and last rejection reason.
• SwitchConfirm: generation, observed destination delivery/marker evidence, MAC.
• SwitchAbort/Rollback: generation, reason, effective activation, MAC.

Derive a control key separately from any schedule/link key. Pin encodings and tags with known-answer tests. Reject replay, stale epoch/generation, mismatched source channel, unknown channel definitions, unsupported width/offset, illegal/no-IR/DFS-unavailable targets, and activation outside bounds.

Step-by-step implementation

• Select and document the initial command transport: Devourer duplex reserved control opportunities, or an explicitly pluggable external RC/control transport. Do not bury migration commands in caller-owned video/FEC payload bytes.
• Add pure encode/decode/MAC/state-machine code and exhaustive loss/duplicate/reorder/replay tests.
• Add an operator command that references exactly one current channel.recommend evidence generation; display target, confidence, observation age, and fallback before approval.
• Repeat proposal/commit/status messages until the activation point. Bound retries and expose delivery/ACK/TxReport evidence without treating a host write as peer receipt.
• Choose activation against a shared observable clock/round. Measure clock uncertainty and set the guard from p99, not a fixed guess. If no sufficiently shared time exists, use an acknowledged countdown protocol with a larger outage budget.
• At activation, drain or deterministically drop pending TX, retune through the safe FastRetune/full-set gate, reapply channel-reset state, and emit robust low-MCS acquisition markers on the destination.
• Ground retunes the primary RX, verifies generation-tagged markers plus video delivery, and sends confirmation if the transport permits.
• Implement bounded rollback/recovery: drone returns to the old/rescue channel without confirmation by deadline; ground alternates an explicit old/new/rescue scan schedule and rejects stale video generations.
• Persist only safe static configuration, not an in-flight state that could strand the next process start. Boot epoch must invalidate old commits.

Failure-injection matrix

• Drop every individual message type and the last commit before activation.
• Duplicate/reorder proposal, commit, confirmation, rollback, and old-epoch traffic.
• Restart ground controller, scout, primary RX, or drone before/after activation.
• Introduce clock error beyond guard.
• Make target silent, heavily interfered, unsupported, or illegal after recommendation.
• Stall TX drain/USB completion and force retune failure.
• Lose the return/control path while downlink video succeeds.
• Receive old-channel frames delayed in USB after switching.

For each case, specify the endpoint states over time and prove eventual convergence to new, old, or rescue channel—never permanent split-brain.

Bench/field progression

1. Cable/attenuated two-node test with manual trigger.
2. Clean on-air old→new→old cycles, ≥1,000 migrations.
3. Interfered old channel and clean destination.
4. Bad destination forcing rollback.
5. Control-path loss at each protocol phase.
6. Power-cycle one endpoint during recovery.

Measure video outage, last-old to first-new frame, first stable FEC decode, control airtime, rollback time, wrong-channel frames, and unrecovered runs.

Acceptance criteria

• Protocol/state-machine/KAT tests cover authentication, replay and all failure cases.
• ≥1,000 clean manual migrations complete with zero persistent split-brain and documented p50/p90/p99 video outage.
• A deliberately bad destination rolls both endpoints back within a bounded documented time.
• Host/API success alone is never treated as peer commit or on-air verification.
• Automatic policy cannot initiate migration in this stage.

[josephnef]

Implemented and merged to master in 7962d16 (PR #311) as part of the adaptive channel migration stack.