fix(spectrum): defer, never drop, profile-owned pan writes (#4142)

[Ozy311]

Summary

RadioModel::sendCmd() drops any command that isProfileOwnedRadioStateWrite() classifies as profile-owned while the profile-load hold is armed — it return 0s before a TCP sequence number is allocated, so the command never reaches the wire. Every display pan set <id> center=… is classified that way.

Direct frequency entry emits an atomic pair:

1. slice tune <id> <freq> → not classified → sent, ACKed
2. display pan set <panId> center=<freq> → classified → silently dropped

The slice retunes. The radio never retunes the waterfall tile stream.

This PR makes those writes deferred, never dropped — without letting one extra byte onto the wire during the hold.

Why the waterfall goes black — and why it drives the design

The renderer is not at fault. PanadapterStream decodes each VITA-49 tile's own FrameLowFreq / BinBandwidth, and remapHistoryRowInto() projects every row using that row's own span. Tiles are honest.

The liar is the optimistic local update. The client set its pan center to the typed frequency while the radio stayed put. Honest tiles were projected into a view that falsely claimed the new center — so the non-overlapping region was correctly black, and those rows entered history permanently.

Corollary that drives the whole design: removing the optimistic update alone eliminates the black. Leave the pan where the radio actually has it and every tile lines up. The pan simply doesn't jump until the deferred command flushes.

What the hold protects — and why this does not weaken it

The hold comes from #3563 (Harden profile load recovery). Its body enumerates every suppression target: early pan dimension writes, FPS/line-duration reconciliation, bandstack autosave, active-slice/TX-slice reasserts, min/max dBm defaults, noise-floor auto-positioning. Every one is a model-echo / reconcile writer. Not one is a user action. And it explicitly promises:

"Normal user-driven active-slice selection still works."

The corruption it guards is documented on requestPanDimensionsForRadio(): writes during profile teardown "dirty the GUIClient restore snapshot with an intermediate topology. That was the root cause of profile-loaded sessions later restarting with missing slices." Severe, server-side, persistent — and not reproducible on demand.

So this is not a request to relax your guard. It closes the gap between what #3563 promised and what it does — the low-level sendCmd() backstop breaks that promise for the pan half of a typed retune.

The non-regression proof

Every write this patch introduces lands after hold expiry — a window in which the current code already permits arbitrary pan writes, and in which it already schedules one (the hold + 1000 ms dimension backstop). Inside the hold, this patch puts zero additional bytes on the wire.

That is enforced in one branch, not by argument: flushPendingProfileLoadPanCenters() early-returns while the hold is armed. No deferred center can escape early even if the call site moved. The patch is therefore structurally incapable of reintroducing the missing-slices corruption — verifiable mechanically, in one function, without a judgment call.

The design — defer-and-coalesce

Mirrors this codebase's own idiom (requestPanDimensionsForRadio() / flushPendingProfileLoadPanDimensions()). sendCmd()'s signature and guard are untouched.

• RadioModel::requestPanCenter(panId, center, bandwidth = -1) is now the only supported way to write a pan center. While the hold is armed it coalesces per pan and returns false without advancing local model state.
• It gates on exactly the predicate sendCmd() guards on, so "if sendCmd would drop it, we queue it" is an identity rather than an approximation — two separate clocks could skew and silently re-open the same hole.
• The queue carries the requested value. Once the optimistic update is gone the model still holds the old center at flush time; re-deriving from the model would send the old value.
• Coalescing is field-wise: a later center-only request must not erase a bandwidth an earlier zoom asked for — that bandwidth is the very thing we set out to stop dropping.
• flushPendingProfileLoadPanCenters() re-resolves against the live pan topology, so a pan the profile removed (or replaced under a new id) never matches and never gets a stale center.
• One ordered flush, hooked into the existing pass after dimensions (bin size = bandwidth ÷ xpixels). No fourth timer.
• Invariant: local state may only advance when a command actually reaches the wire. Sites that also move the view directly now gate that on the return value.

Fixes the class, not the instance

All ten pan-center writers route through it — typed-frequency reveal (the reported bug), pan-follow, centerActiveSliceInPanadapter, applyPanRangeRequest (zoom/drag — also silently dropped today), snapCenterLockForSlice, the channel-strip applet, edge-pan drag, DigitalModes, ATU pre-tune, and automation.

requestPanCenter() lives on RadioModel rather than MainWindow for one decisive reason: AtuPreTuneDialog and the automation path hold only a RadioModel*. A MainWindow-owned queue could not reach them, and those writers are dropped today too.

Observability

The sendCmd() suppression log is escalated qCDebug → qCWarning. The backstop stays as defense-in-depth; we simply stop relying on it to silently eat user commands. Anything still reaching it is now a bug we want to see.

Residual behaviour (stated honestly)

Worst case — profile load, then a typed frequency within the hold: the pan trails the slice by a few seconds, showing truthful spectrum for its real span the entire time, with zero permanent artifacts, then recenters. Today: permanent black scars and a pan that never moves.

Gesture paths (zoom / drag / edge-pan) are more nuanced and I want to be precise rather than overclaim: SpectrumWidget owns its own view during a gesture (it mutates m_centerMhz and reprojects before emitting the request), so the view still tracks the cursor. During the hold the radio lags behind it, and the newly-exposed span has no data until the deferred command flushes — at which point it fills. The divergence is temporary and self-healing. Today it is permanent, because the command is dropped and the radio never catches up. I deliberately did not suppress the widget's self-move: that is the gesture's own affordance, and freezing it would trade one bug for a worse one.

A question I'd rather ask than guess at

The wire capture shows the radio ACKs and retunes tile streams in 79–142 ms, and the deferred-dimension path already attempts a flush at 1.5 s — yet kProfileLoadStateWriteHoldMs = 10000, which reads like padding rather than a measurement.

Is there a wire-observable profile-load-completion event (or is the per-pan settling deadline a real bound on radio-side rebuild)? If so the deferral collapses to sub-second and the residual lag disappears. I'm happy to follow up with that patch — but I didn't want to guess at the settle condition inside a mechanism that guards a corruption I can't reproduce, and I wasn't willing to trade away the zero-bytes-on-the-wire proof above to make it look event-driven.

Constitution principle honored

Principle II — The Radio Is Authoritative On Live State. "A user action is a request to the radio… the client never writes its remembered value back over the radio's."

Today the client does the worst possible pair of things: it applies the optimistic update and discards the request. The result is permanent client/radio divergence with no reconcile path — the radio never echoes a center it was never asked to take. This patch restores the principle exactly: local state advances only when the request actually reaches the radio.

Also Principle XI — Fixes Are Demonstrated: isProfileOwnedRadioStateWrite() is moved out of RadioModel.cpp's anonymous namespace into header-only ProfileLoadCommand.h (pure move, no behaviour change) so the classification contract is finally reachable from a test.

Scope

• 8 files, +366 / −112.
• No protocol change. No persistence change. No UX change on the normal (non-profile-load) path — outside the hold, every routed site emits the identical command it does today.
• sendCmd()'s signature and guard: unchanged.

Test plan

• Clean incremental ninja -C build -j 16 on Linux (Nobara, Qt 6.10.3, gcc 15.2.1) — AetherSDR links clean.
• profile_load_command_test — extended with the classification contract: pan center= and coupled center=+bandwidth= are profile-owned (the dropped writes); xpixels/ypixels are the sole exemption; a single non-pixel field re-arms the guard so center can never ride in on a dimension write's coat-tails; slice tune survives the hold (the surviving half of the broken pair).
• Regression sweep (mirrors [codex] Harden profile load recovery #3563's own validation set): profile_transfer_test, radio_status_ownership_test, slice_recreate_policy_test, transmit_model_test — all pass.
• Full ctest run diffed against clean upstream/main: byte-identical failure sets — this branch introduces zero new build or test failures. (The pre-existing crdv_cleanroom_test sanitizer link failure and its dependents reproduce identically on unmodified main on this box.)
• A/B on a live FLEX-6700 — -stable (has bug) vs this branch, with a tcpdump capture on tcp/4992 confirming zero additional bytes inside the hold window and the center command present after expiry. Repro: store a Global profile with a wide view → activate → within 10 s type a frequency + Enter.

Checklist

• Commits are signed (docs/COMMIT-SIGNING.md)
• No new flat-key AppSettings calls (Principle V)
• All meter UI uses MeterSmoother (Principle II) — n/a, no meter UI touched

Closes #4142

---

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

[Ozy311]

Superseded by #4224 — a rewrite of this patch on the current main (v26.7.2). Adversarial re-review of this branch found the center-only queue, the frozen-model dedupe, and the null-check pan guard each defective (the cross-band variant of the reported bug still fired here); #4224 replaces the mechanism with a field-keyed queue, effective-state dedupe with corrective-cancel, success-gated wire-before-model dispatch, and removal-time voids. Closing in favor of #4224.

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