fix(spectrum): field-keyed deferred pan writes — never lie, never silently drop (#4142)

[Ozy311]

Summary

Fixes #4142.

During the 10 s profile-load hold, sendCmd() suppresses every profile-owned radio-state
write — silently. A typed frequency entry emits an atomic pair: the slice tune half
passes, the display pan set … center= half is destroyed before a sequence number is
allocated, and the client's optimistic model advance then projects honest VITA-49 tiles
into a view claiming a center the radio never took: the non-overlap renders black,
permanently, into waterfall history. The cross-band variant also loses its band= write,
so the slice lands outside the pan entirely.

This PR makes the tune/zoom/band class of user writes (center=, bandwidth=, band=)
defer instead of drop, with three properties the previous behavior lacked:

• Never lie. sendCommand() now reports whether a command was actually dispatched
  (the Stale MultiFlex session keeps auto-floor-adjusting a reclaimed pan; foreign dBm-range echoes bypass smoothing and bounce the trace (#3951 root cause) #3977 foreign-owner gate, the hold backstop, and a dead WAN session all return
  false), and the pan model advances only after a successful wire write — wire-before-
  model makes a re-entrant request converge instead of diverge. Dispatch re-clamps the
  center against the pan geometry current at flush time, not the geometry the request
  was made against.
• Never silently drop. User writes made during the hold coalesce field-wise per pan
  in a dedicated store (ProfileLoadPanWriteQueue, unit-tested) and replay when the hold
  lifts — band first, then center+bandwidth merged, mirroring the live cross-band order.
  Every write that cannot be replayed (pan removed, ownership lost, disconnect) is voided
  loudly, naming the pan and the destroyed fields; the flush logs a sent/voided
  account unconditionally.
• Respect corrections. Dedupe runs against effective state — the pending value if
  one is queued, else the model, which keeps tracking radio status through the hold. A
  request equal to the radio's state that supersedes a different pending value is a user
  correction: the pending entry is cancelled, never replayed over the user.

Replay scheduling is owned by the defer path (a single member QTimer, hold-relative,
self-re-arming) — not by the profile-load ACK. That matters because a large topology
can stall the radio past the ping timeout into a force-disconnect before the ACK ever
arrives (measured 5/5 on an 8-pan profile on a 6700 — full timing data in #4222), and
MainWindow's ACK-gated recovery pass — including its previous deferred-center flush call —
never runs on such a load. The
pan-removal paths void a dead pan's queued writes at removal time, because the radio
re-uses pan ids across a load (observed live): a queued write must never replay onto a
same-id newcomer and override the state the profile just restored.

The non-regression proof, in one branch: flushPendingProfileLoadPanWrites()
early-returns while the hold is armed, so a deferred write can never put a byte on the
wire inside the hold window. Nothing in this PR can reintroduce the missing-slices
corruption the #3563 hold exists to prevent. kProfileLoadStateWriteHoldMs is untouched.

Honest scope

• Routed in this PR: center=, bandwidth=, band= — every path in the reported
  issue, including the cross-band typed tune. Echo/reconcile writers (active-slice/TX
  reasserts, dBm auto-floor, fps/average reconciles, auto-black) are deliberately NOT
  routed: [codex] Harden profile load recovery #3563 suppresses them by design, and routing discipline at the call site is
  the user-intent boundary — no wire-protocol flag.
• Still suppressed during the hold (mechanism is ready; enumerated for follow-up):
  rxant, wnb/wnb_level, rfgain, loopa/loopb, min_dbm/max_dbm,
  band_zoom/segment_zoom, fps, average, weighted_average, daxiq_channel,
  plus the wholesale-suppressed slice set / display panafall set /
  display waterfall set families, and one genuinely mixed site
  (dbmRangeChangeRequested: user drag and auto-floor share a wire path). Tracked
  with the full census in profile-load hold: remaining user-intent writes still silently suppressed (census follow-up to #4201) #4223.
• Gesture paths self-heal rather than never diverging: SpectrumWidget applies its
  own view on zoom/drag/edge-pan before emitting the request, so on those paths the view
  can lead the radio for the duration of the hold — a temporary, self-correcting
  divergence (each VITA-49 tile carries its own geometry), not a permanent scar. Typed
  entry — the reported bug — is model-driven and fully covered.
• The WFM/Doppler escape branch no longer zeroes the demod NCO when its recenter was
  deferred; it keeps best-effort audio at the clamped IQ-window edge until the flush
  self-heals.

Constitution principle honored

Principle II — the radio is authoritative. The client's model no longer advances for a
command that never reached the wire, deferred writes re-validate against the live pan
topology and current geometry before dispatch, and the radio's own state (tracked through
the hold) is the dedupe baseline.

Test plan

• Local build passes (cmake --build build)
• profile_load_command_test extended: classifier contract + full
  ProfileLoadPanWriteQueue semantics (field-wise coalescing, field-precise
  supersede, cancel-with-receipt, drain)
• Full ctest failure set diffed against clean upstream/main on the same box —
  byte-identical (no new failures)
• Behavior verified on a real radio (FLEX-6700, RX-only, 2026-07-13: the black-waterfall scenarios no longer reproduce on the fix build and do on the baseline; runbook: typed tune in the hold
  dead-zone, cross-band typed tune, corrective zoom/retype, worst-case multi-pan
  load with force-disconnect, pan close with a pending write, untouched-load
  missing-slices regression guard)
• Reproduction steps documented in Profile-load state-write hold silently drops user-initiated pan recenter; waterfall stays black after direct frequency entry #4142

Checklist

• Commits are signed (docs/COMMIT-SIGNING.md)
• No new flat-key AppSettings calls
• Code is clean-room (Principle IV)
• All meter UI uses MeterSmoother (n/a — no meter changes)
• Documentation updated if user-visible behavior changed (n/a — behavior change is
  the fix itself; log lines document the defer/void/flush lifecycle)
• Security-sensitive changes reference a GHSA (n/a)

---

73, Ozy K6OZY
AI compute partnership: cloaked.agency — (model: claude-fable-5)

[aethersdr-agent]

Really solid work, @Ozy311 — this is a careful, well-reasoned fix. The wire-before-model discipline, the field-wise coalescing queue with its own unit test, defer-scheduling owned by the defer path (not the ACK that may never come), and voiding a dead pan's writes at removal time because the radio re-uses pan ids all hang together coherently. I traced the "never lie" contract end-to-end and it holds: both m_seqCounters start at 1, so sendCommand()'s seq != 0 == dispatched is exact; the corrective-cancel true return is truthful; snapCenterLockForSlice null-checks pan; the effective-geometry helpers return NaN safely for unknown pans; and the WFM std::clamp is all-float. All 7 CI checks are green.

Nothing blocking. Two non-blocking observations below.

Polish

• setPanBandwidth() (RadioModel.cpp:2720) is the one pan-field writer that was not rerouted — it still calls raw sendCmd("display pan set … bandwidth=…") while its sibling setPanCenter() now goes through requestPanCenter(). It has no callers today so it's latent, but if it's ever wired up it would both silently drop during the hold and trip your new loud "DROPPED a routed pan field write" warning. See inline note.

Non-blocking notes

• sendCommand()'s new bool contract returns false only for the WAN-disconnected case; the LAN path allocates a seq unconditionally, so a write queued onto a dead LAN socket reads as "dispatched." This matches the pre-existing optimistic behavior and disconnect-during-hold is separately handled by onDisconnected() voiding the queue, so it's fine — just noting the doc comment's "dead session" wording is WAN-only in practice.

---

_{🤖 aethersdr-agent · cost: $9.0354 · model: claude-opus-4-8}

[jensenpat]

Holding for next week's release since it changes the shared pan-centering and band-selection paths used during normal operation.

[ten9876]

First-pass triage review (not exhaustive — surfacing blockers to keep this moving):

Read the full diff and traced the core deferred-write mechanism (RadioModel::requestPan* → dispatchPan* → flushPendingProfileLoadPanWrites), the ProfileLoadPanWriteQueue coalescing/supersede/cancel semantics, and the sendCmd/sendCommand return-value plumbing.

Blockers

None spotted in a first pass. The load-bearing correctness properties hold up:

• The "was it dispatched?" contract is real: m_seqCounter{1} (RadioModel.h:846) so sendCmd() never returns 0 for a live send, while both drop paths return 0 — the hold-suppression (RadioModel.cpp:5306) and WAN-disconnected (WanConnection.cpp:192). sendCommand() mapping seq != 0 → dispatched is sound, and dispatchPanCenterBandwidth() advances PanadapterModel only after a successful send (wire-before-model), so the optimistic-lie / black-waterfall class can't reappear.
• Field-wise coalescing (never whole-struct replace) is the right call and is unit-tested; supersede/cancel are field-precise, and the immediate path supersedes-before-dispatch, closing the hold-expiry→flush window.
• Every teardown voids deferred writes: pan-removed, ownership-lost/reassigned, and disconnect (with the reused-pan-id hazard handled at removal time, not deferred to flush). flushPendingProfileLoadPanWrites() early-returns while the hold is armed, preserving the [codex] Harden profile load recovery #3563 non-regression invariant.
• Classifier move to ProfileLoadCommand.h is include-clean (<QLatin1Char> is a valid Qt6 forwarding header; RadioModel.cpp:18 includes the moved header).

Secondary notes (non-blocking)

• The correction-cancel logic (requestPanCenter equalsModel branch, RadioModel.cpp ~808) is load-bearing on the assumption that the model keeps tracking radio status through the hold (only writes are suppressed by [codex] Harden profile load recovery #3563, not status application). Worth a one-line confirmation that no status-apply path is gated by the same hold — if it were, a stale equalsModel could cancel a still-needed deferred write.
• Gesture paths (zoom/drag/edge-pan) still let SpectrumWidget's view lead the radio during the hold; the PR argues this self-heals because each VITA-49 tile carries its own geometry. Reasonable, and typed entry (the reported bug) is fully model-gated — but a second reviewer eye on the "self-correcting, not a scar" claim for a drag held open across a long multi-pan load would be worthwhile.
• Cosmetic: the flush sent/voided account counts a pan carrying both band= and center= as two, so the totals are per-dispatch, not per-pan — fine for a log line, just not a pan count.

Solid, well-scoped change with a genuinely useful unit test. No first-pass blockers; the two questions above are for the deeper review, not gating.