feat(ui): handoff §5 — channel SNR as distribution (linear-mean ± dB-spread over last 8 readings; MC-DPSK physical + recalibrated OFDM broadband feed one ring; per-session reset)

good@10 shows 'channel 8.5±4.0 dB', good@20 '20.6±2.5' — mean tracks dial,
spread IS the fading. ctest 85/85; both gates PASS.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019btwFxDt7D19SZSqPYvZnk

Author: secup

docs/CHANGELOG.md

@@ -10,6 +10,21 @@ This log tracks all bug fixes and behavioral changes to prevent re-doing work du
 
 ---
 
+## 2026-07-08 — feat(ui): handoff §5 — fading channel SNR displayed as a DISTRIBUTION (mean±spread), not snapshot flicker
+
+On fading there is no single SNR — each reading samples one fade state (the
+F230 confusion: 2/6.6/12.6 flashed at the operator for the same dial-10
+channel). The decoder now keeps a ring of the last 8 channel-SNR readings
+(MC-DPSK physical measurements at the handshake; the truth-calibrated OFDM
+broadband per frame during transfers), reports the LINEAR-domain mean (the
+honest fade average — dB-averaging under-reads by the Jensen penalty) and the
+dB spread. MODE lines now read `channel 8.5±4.0 dB` (good@10) /
+`channel 20.6±2.5 dB` (good@20) — the mean tracks the dial, the ± IS the
+fading. Ring resets per session (a new QSO never averages the old channel).
+Verified: ctest 85/85; good@10 PASS + good@20 PASS 1440 bps.
+
+---
+
 ## 2026-07-08 — feat(snr): handoff §4 — the usable≤channel invariant enforced in code (SNR-SANITY)
 
 Physics forbids demod-usable SNR exceeding the channel's physical S:N. When a

src/gui/app.cpp

@@ -1143,10 +1143,20 @@ App::App(const Options& opts) : options_(opts), simulation_enabled_(opts.enable_
         // the locally measured physical channel SNR beside it when available.
         // BETA readout (BUG-PHYSICAL-SNR-RIG-REF): power ratio of the connect
         // sequence's training span vs the frame's own inter-chirp noise.
-        char channel_snr_text[40] = "";
-        if (modem_.hasLastPhysicalSnr()) {
-            snprintf(channel_snr_text, sizeof(channel_snr_text),
-                     ", local channel~%.1f dB (beta)", modem_.lastPhysicalSnrDb());
+        char channel_snr_text[48] = "";
+        {
+            float mean_db = 0.0f, spread_db = 0.0f;
+            const size_t n = modem_.physicalSnrStats(mean_db, spread_db);
+            if (n >= 3) {
+                // §5: on fading, the channel is a distribution — report the
+                // linear-domain (fade-averaged) mean and the dB spread across
+                // the recent frames instead of a single-snapshot flicker.
+                snprintf(channel_snr_text, sizeof(channel_snr_text),
+                         ", channel %.1f±%.1f dB", mean_db, spread_db);
+            } else if (modem_.hasLastPhysicalSnr()) {
+                snprintf(channel_snr_text, sizeof(channel_snr_text),
+                         ", channel~%.1f dB (1 frame)", modem_.lastPhysicalSnrDb());
+            }
         }
         char buf[300];
         if (waveform == protocol::WaveformMode::MC_DPSK) {

src/gui/modem/modem_engine.cpp

@@ -995,6 +995,11 @@ float ModemEngine::lastPhysicalSnrDb() const {
     return streaming_decoder_ ? streaming_decoder_->lastPhysicalSnrDb() : 0.0f;
 }
 
+size_t ModemEngine::physicalSnrStats(float& mean_db, float& spread_db) const {
+    if (!streaming_decoder_) { mean_db = 0.0f; spread_db = 0.0f; return 0; }
+    return streaming_decoder_->physicalSnrStats(mean_db, spread_db);
+}
+
 int64_t ModemEngine::lastRxSubstantiveMs() const {
     return streaming_decoder_ ? streaming_decoder_->lastRxSubstantiveMs() : -1000000;
 }

src/gui/modem/modem_engine.hpp

@@ -157,6 +157,7 @@ class ModemEngine {
     // BUG-PHYSICAL-SNR-RIG-REF. Valid=false until first data-bearing frame.
     bool hasLastPhysicalSnr() const;
     float lastPhysicalSnrDb() const;
+    size_t physicalSnrStats(float& mean_db, float& spread_db) const;
     ChannelQuality getChannelQuality() const;
     // Live OFDM in-band (broadband) SNR from the decoder's lock-free last-estimate
     // atomics — updated per logical frame on BOTH delivery paths (incl. burst-as-unit,

src/gui/modem/streaming_decoder.cpp

@@ -1346,6 +1346,14 @@ void StreamingDecoder::reset(bool reset_doppler_coherence) {
     std::fill(sync_controller_.ring_.buffer_.begin(), sync_controller_.ring_.buffer_.end(), 0.0f);
     if (waveform_) waveform_->reset();
     idle_noise_snr_estimator_.reset();
+    // §5: the physical-SNR distribution is per-session — a new QSO (or channel
+    // change) must not average against the previous channel's samples.
+    last_physical_snr_valid_.store(false);
+    last_physical_snr_db_.store(0.0f);
+    {
+        std::lock_guard<std::mutex> lk(physical_ring_mutex_);
+        physical_ring_count_ = 0;
+    }
 
     {
         std::lock_guard<std::mutex> qlock(queue_mutex_);

src/gui/modem/streaming_decoder.hpp

@@ -455,6 +455,33 @@ class StreamingDecoder {
     int64_t lastRxSubstantiveMs() const { return last_rx_substantive_ms_.load(); }
     bool hasLastPhysicalSnr() const { return last_physical_snr_valid_.load(); }
     float lastPhysicalSnrDb() const { return last_physical_snr_db_.load(); }
+    // Handoff §5: distribution over the recent physical readings.
+    // Returns readings-count; mean is linear-domain (fade-averaged), spread
+    // is the dB standard deviation of the samples.
+    size_t physicalSnrStats(float& mean_db, float& spread_db) const {
+        std::lock_guard<std::mutex> lk(physical_ring_mutex_);
+        const size_t n = std::min(physical_ring_count_, kPhysicalSnrRing);
+        if (n == 0) { mean_db = 0.0f; spread_db = 0.0f; return 0; }
+        double lin_sum = 0.0, db_sum = 0.0;
+        for (size_t i = 0; i < n; ++i) {
+            lin_sum += std::pow(10.0, physical_ring_db_[i] / 10.0);
+            db_sum += physical_ring_db_[i];
+        }
+        mean_db = static_cast<float>(10.0 * std::log10(lin_sum / n));
+        const double db_mean = db_sum / n;
+        double var = 0.0;
+        for (size_t i = 0; i < n; ++i) {
+            const double d = physical_ring_db_[i] - db_mean;
+            var += d * d;
+        }
+        spread_db = static_cast<float>(std::sqrt(var / n));
+        return n;
+    }
+    void notePhysicalSnrSample(float db) const {
+        std::lock_guard<std::mutex> lk(physical_ring_mutex_);
+        physical_ring_db_[physical_ring_count_ % kPhysicalSnrRing] = db;
+        ++physical_ring_count_;
+    }
     uint64_t burstAirSamplesRemaining() {
         const uint64_t end = burst_air_end_abs_.load(std::memory_order_relaxed);
         if (end == 0) return 0;
@@ -775,6 +802,16 @@ class StreamingDecoder {
     // rate selection stays on effective (#74 — the demod lives there).
     mutable std::atomic<float> last_physical_snr_db_{0.0f};
     mutable std::atomic<bool> last_physical_snr_valid_{false};
+    // Handoff §5: fading channel SNR is a DISTRIBUTION, not a number — each
+    // per-frame physical reading samples one fade state. Keep a short ring
+    // and report mean ± spread: mean in the LINEAR power domain (the honest
+    // fade average — dB-averaging under-reads by the Jensen penalty), spread
+    // as the dB standard deviation. ~8 readings ≈ 15-40 s of frames ≈ several
+    // coherence times on Good.
+    static constexpr size_t kPhysicalSnrRing = 8;
+    mutable std::mutex physical_ring_mutex_;
+    mutable std::array<float, kPhysicalSnrRing> physical_ring_db_{};
+    mutable size_t physical_ring_count_ = 0;
     float sync_gap_error_samples_ = 0.0f; // Dual-chirp timing error for current frame
     size_t last_decoded_sync_pos_ = SIZE_MAX;  // Last successfully decoded sync position (to prevent duplicates)
     bool sync_from_warm_timed_window_ = false;

src/gui/modem/streaming_sync_acquisition.cpp

@@ -117,8 +117,10 @@ void StreamingDecoder::populateDecodeMetrics(DecodeResult& result, bool is_ofdm,
     // ratio over the exact training span vs THIS frame's burst-time noise
     // ref) — replaces the old handshake-latched decoder-side computation.
     if (!is_ofdm && waveform_ && waveform_->hasPhysicalSNR()) {
-        last_physical_snr_db_.store(waveform_->getPhysicalSNRdB());
+        const float phys = waveform_->getPhysicalSNRdB();
+        last_physical_snr_db_.store(phys);
         last_physical_snr_valid_.store(true);
+        notePhysicalSnrSample(phys);  // §5: distribution ring
     }
     result.sync_correlation = sync_correlation_;
     result.sync_quality_db = result.snr_db;
@@ -205,6 +207,11 @@ void StreamingDecoder::populateDecodeMetrics(DecodeResult& result, bool is_ofdm,
         }
         result.snr_source = SNRSource::SYNC_QUALITY;
         if (result.has_ofdm_broadband_snr_db) {
+            // §5: the recalibrated OFDM broadband reading is truth-calibrated
+            // (OFDMSnrCalibration ±1.5 dB) — feed the channel-SNR distribution
+            // ring so the mean±spread display keeps updating through OFDM
+            // transfers (MC-DPSK frames stop at the handshake).
+            notePhysicalSnrSample(result.ofdm_broadband_snr_db);
             result.snr_db = result.ofdm_broadband_snr_db;
             result.snr_source = SNRSource::OFDM_BROADBAND;
             last_ofdm_broadband_snr_db_valid_.store(true);