fix(snr): LTS glitch guard — skip meter update when same-frame noise >= signal (synced frame at sub-0 dB = measurement fault; rig F237 meter collapse to -9.2 at dial 20)

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,26 @@ This log tracks all bug fixes and behavioral changes to prevent re-doing work du
 
 ---
 
+## 2026-07-13 — fix(snr): LTS glitch guard — a synced frame at sub-0 dB is a measurement fault, not channel state (rig F237: meter collapsed to −9.2 at a 20 dB channel)
+
+The 07-10 estimation-noise debias floored at 0.01× when a glitched LTS pair
+(rig timing jitter on fading) pushed the noise estimate above the signal —
+one glitch frame injected a −19.5 dB reading into the meter EMA; two or three
+collapsed it to −9.2 at MPG@20 → authority demote churn, ACK-staircase
+flapping, ring spread ±13.5 (the pre-fix guard-biased code had masked the same
+glitches as spikes UP). Physics: a frame that achieved LTS sync has
+processing-gain-proven signal presence — same-frame noise ≥ signal is a fault;
+SKIP the meter update (both estimator paths). A genuine deep fade never syncs
+and thus never lies either way. Sim gates passed pre-fix because sim timing is
+clean — the rig is the glitch amplifier (fidelity lesson: single-seed sim
+gates under-sample LTS-glitch behavior).
+
+Verified: OFDMSnrCalibration full matrix unchanged; good@20 PASS 1650 bps with
+ZERO negative lts readings; ctest 85/85 (one TNC straggler artifact, clean on
+rerun). Forensics: ~/Documents/ultra_forensics/F237_{mac,pi5}.log.
+
+---
+
 ## 2026-07-10 — fix(snr): review findings 3/5 — getStats() live overlay (meters no longer freeze during bursts) + session-teardown SNR clear; finding 2 script removed; finding 7 filed
 
 **Finding 3:** the LoopbackStats cache is refreshed only by the per-frame

src/ofdm/channel_equalizer_lts.cpp

@@ -103,9 +103,21 @@ void OFDMDemodulator::Impl::updateLastSNREstimate(float signal_power,
         //     fades finite (-20 dB per-carrier) instead of log(<=0).
         //     This term (+10log10(1+1/SNR_c)) GREW under fading — the
         //     "reads 16.4 while the link can't hold QPSK R1/2" optimism.
-        const float debiased_signal_power = std::max(
-            signal_power - corrected_noise_power,
-            0.01f * corrected_noise_power);
+        // GLITCH GUARD (rig F237, 2026-07-13): a frame that achieved LTS sync
+        // has processing-gain-proven signal presence — a same-frame noise
+        // estimate at/above the signal power is a MEASUREMENT FAULT (timing
+        // slip / CFO glitch corrupting the LTS pair), not channel state.
+        // Without this, the debias floors at 0.01x and one glitch frame
+        // injects a -19.5 dB reading into the EMA (rig meter collapsed to
+        // -9.2 at a 20 dB channel -> authority demote churn + ACK-staircase
+        // flapping). Skip the update; the EMA holds and the next clean frame
+        // measures honestly. A GENUINE deep fade produces no LTS sync and
+        // therefore no reading — same outcome, no lie either way.
+        if (signal_power <= 2.0f * corrected_noise_power) {
+            return;
+        }
+        const float debiased_signal_power =
+            signal_power - corrected_noise_power;
         const float snr_per_carrier_db = 10.0f * std::log10(
             debiased_signal_power / std::max(corrected_noise_power, 1.0e-12f));
         // (b) GEOMETRIC per-carrier -> in-band conversion. The old
@@ -165,9 +177,11 @@ void OFDMDemodulator::Impl::updateLastSNREstimate(float signal_power,
         dof_corrected_noise *= static_cast<float>(independent_bins) /
                                static_cast<float>(independent_bins - 1);
     }
-    const float debiased_signal_power =
-        std::max(signal_power - dof_corrected_noise,
-                 0.01f * dof_corrected_noise);
+    // Same glitch guard as the noise_reference_only path above.
+    if (signal_power <= 2.0f * dof_corrected_noise) {
+        return;
+    }
+    const float debiased_signal_power = signal_power - dof_corrected_noise;
     const float snr_per_carrier_db =
         10.0f * std::log10(debiased_signal_power / dof_corrected_noise);
     const float broadband_snr_db =

src/protocol/connection.cpp

@@ -196,8 +196,8 @@ Connection::Connection(const ConnectionConfig& config)
     }
 
     // RX-RATE-CMD Phase 2 (design §5.2, knob ULTRA_RX_RATE_CMD, read once per
-    // Connection; default OFF = byte-identical — rung_cmd bits stay 0 AND the tone-ACK
-    // CRC span stays 28 bits, see tone_burst_payload.cpp rungCmdCrcSpanEnabled()).
+    // Connection; default ON since 2026-07-05). The tone-ACK codec must use the
+    // widened CRC span whenever this command path or RX authority is enabled.
     // SEMANTICS-BREAKING lockstep when ON; the descriptor-committed consume path
     // additionally needs ULTRA_DESCRIPTOR_MODE_SWITCH (+ ULTRA_ARQ_MOVE_EPOCH for
     // mid-window) — it falls back to the legacy MODE_CHANGE exchange without them.
@@ -2649,6 +2649,10 @@ void Connection::maybeObeyAuthorityCommand(uint8_t cmd_idx) {
     if (cmd_idx == kRungIdxNone || cmd_idx >= kRungIdxCount) return;
     if (state_ != ConnectionState::CONNECTED ||
         negotiated_mode_ != WaveformMode::OFDM_CHIRP) return;
+    // The operator pin is the final authority. Receiver authority replaces the
+    // adaptive controller, but it must not bypass ULTRA_LOCK_RATE or an explicit
+    // ULTRA_RATE_ADAPT=0 fixed-rung measurement.
+    if (!rateAdaptationActive()) return;
     if (mode_change_pending_) return;  // a move is already in flight — obey later copies
     CoherentPick pick = coherentRungFromIndex(cmd_idx);
     Modulation mod = pick.mod;

src/protocol/waveform_selection.hpp

@@ -422,7 +422,7 @@ inline uint8_t snapRungIndexDownToEnabled(uint8_t idx) {
     return kRungIdxNone;
 }
 
-// ULTRA_RX_RATE_AUTHORITY (2026-07-05, default OFF): receiver-commanded absolute
+// ULTRA_RX_RATE_AUTHORITY (2026-07-05, default ON): receiver-commanded absolute
 // rung selection — the receiver maps ITS fresh per-group channel measurements
 // through selectCoherentOFDM and commands the sender's next rung on every group
 // ACK; the sender OBEYS (descriptor commit) and its own mid-transfer rate drivers

src/waveform/tone_burst_ack/tone_burst_payload.cpp

@@ -96,20 +96,25 @@ inline uint32_t crcMessageBits(bool cover_rung_cmd) {
 
 }  // namespace
 
-// ULTRA_RX_RATE_CMD process-wide binding for the parameter-less overloads.
+// ULTRA_RX_RATE_CMD / ULTRA_RX_RATE_AUTHORITY process-wide binding for the
+// parameter-less overloads.
 // Read ONCE (static; same pattern as ULTRA_ARQ_MOVE_EPOCH's ctor read) — the
 // codec functions themselves stay stateless via the explicit-span overloads.
 bool rungCmdCrcSpanEnabled() {
     static const bool v = [] {
         const char* e = std::getenv("ULTRA_RX_RATE_CMD");
-        if (e != nullptr && e[0] == '1') return true;
+        const bool rx_rate_cmd = !(e && e[0] == '0');
         // RX-AUTHORITY (2026-07-05) reinterprets [rate_hint|rung_cmd] as a 5-bit
         // absolute rung command — all five bits must sit inside the CRC span (a
         // corrupted command = a wrong-rate burst). Same lockstep semantics as
         // ULTRA_RX_RATE_CMD: a knob-OFF peer CRC-rejects these ACKs (fails safe
         // as ack loss).
         const char* a = std::getenv("ULTRA_RX_RATE_AUTHORITY");
-        return a != nullptr && std::atoi(a) != 0;
+        // Keep this default exactly aligned with rxRateAuthorityEnabled(). Both
+        // command paths are default-on; the legacy span is valid only when both
+        // have been explicitly disabled.
+        const bool rx_authority = a == nullptr || std::atoi(a) != 0;
+        return rungCmdCrcSpanRequired(rx_rate_cmd, rx_authority);
     }();
     return v;
 }

src/waveform/tone_burst_ack/tone_burst_payload.hpp

@@ -112,17 +112,23 @@ struct ToneBurstAckPayload {
 //
 // STATELESSNESS: the CRC span is a PARAMETER of every pack/verify/codec entry
 // point (`cover_rung_cmd`). The parameter-less overloads bind it once from the
-// ULTRA_RX_RATE_CMD env (read a single time, process-wide — the production
-// encoder/detector path); tests pass it explicitly, so no env ordering can
-// change a test's meaning.
+// ULTRA_RX_RATE_CMD / ULTRA_RX_RATE_AUTHORITY env (read a single time,
+// process-wide — the production encoder/detector path); tests pass it
+// explicitly, so no env ordering can change a test's meaning.
 //
 // We use a 12-bit CRC (rather than 16) to keep the packet small: 12 bits at
 // ~1 bit/symbol after 4-FSK + (15,11) Hamming means ~3-4 fewer symbols on
 // air. CRC-12 still catches all 1-3 bit bursts and >99.9% of random errors
 // for our 26-bit message — overkill for ACK semantics.
 
 // Process-wide CRC-span binding for the parameter-less overloads below:
-// true iff ULTRA_RX_RATE_CMD=1 (read once on first use).
+// true when either default-on receiver command path is enabled (read once on
+// first use). The pure predicate is exposed so all four feature states can be
+// tested without depending on the process-wide environment latch.
+inline constexpr bool rungCmdCrcSpanRequired(bool rx_rate_cmd_enabled,
+                                             bool rx_authority_enabled) {
+    return rx_rate_cmd_enabled || rx_authority_enabled;
+}
 bool rungCmdCrcSpanEnabled();
 
 // Pack the kPayloadBits (44) raw payload bits (excluding Hamming) into a

tests/test_rx_authority.cpp

@@ -383,6 +383,39 @@ static bool test_sender_ignores_none_and_garbage() {
     return true;
 }
 
+// A fixed-rung probe is an operator command, not an advisory. Receiver authority
+// must not move the sender while ULTRA_LOCK_RATE is active.
+static bool test_operator_lock_overrides_authority() {
+    TEST("operator adaptation controls override receiver authority");
+
+    {
+        Connection c;
+        TA::makeConnectedOFDM(c, CodeRate::R3_4, 20.0f, 0.05f, Modulation::QPSK);
+        setenv("ULTRA_LOCK_RATE", "1", 1);
+        TA::obey(c, kRungIdxQam8R23);
+        unsetenv("ULTRA_LOCK_RATE");
+        if (TA::modeChangePending(c)) FAIL("authority bypassed ULTRA_LOCK_RATE");
+    }
+    {
+        Connection c;
+        TA::makeConnectedOFDM(c, CodeRate::R3_4, 20.0f, 0.05f, Modulation::QPSK);
+        setenv("ULTRA_RATE_ADAPT", "0", 1);
+        TA::obey(c, kRungIdxQam8R23);
+        unsetenv("ULTRA_RATE_ADAPT");
+        if (TA::modeChangePending(c)) FAIL("authority bypassed ULTRA_RATE_ADAPT=0");
+    }
+    {
+        setenv("ULTRA_ADAPTIVE_RATE", "0", 1);
+        Connection c;
+        unsetenv("ULTRA_ADAPTIVE_RATE");
+        TA::makeConnectedOFDM(c, CodeRate::R3_4, 20.0f, 0.05f, Modulation::QPSK);
+        TA::obey(c, kRungIdxQam8R23);
+        if (TA::modeChangePending(c)) FAIL("authority bypassed ULTRA_ADAPTIVE_RATE=0");
+    }
+    PASS();
+    return true;
+}
+
 int main() {
     // MUST precede any Connection construction (env-latched statics).
     setenv("ULTRA_RX_RATE_AUTHORITY", "1", 1);
@@ -403,6 +436,7 @@ int main() {
     ok &= test_no_observation_no_command();
     ok &= test_sender_obeys_and_dedups();
     ok &= test_sender_ignores_none_and_garbage();
+    ok &= test_operator_lock_overrides_authority();
     std::cout << tests_passed << "/" << tests_run << " passed\n";
     return (ok && tests_passed == tests_run) ? 0 : 1;
 }

tests/test_tone_burst_ack_payload.cpp

@@ -5,6 +5,7 @@
 #include "waveform/tone_burst_ack/tone_burst_payload.hpp"
 
 #include <cassert>
+#include <cstdlib>
 #include <cstdint>
 #include <cstdio>
 #include <random>
@@ -559,6 +560,17 @@ void test_symbol_ms_staircase() {
 }  // namespace
 
 int main() {
+    EXPECT(!rungCmdCrcSpanRequired(false, false));
+    EXPECT(rungCmdCrcSpanRequired(true, false));
+    EXPECT(rungCmdCrcSpanRequired(false, true));
+    EXPECT(rungCmdCrcSpanRequired(true, true));
+
+    // Receiver authority is default-on, so the parameter-less production codec
+    // must cover its command bits even when no environment knob is present.
+    unsetenv("ULTRA_RX_RATE_CMD");
+    unsetenv("ULTRA_RX_RATE_AUTHORITY");
+    EXPECT(rungCmdCrcSpanEnabled());
+
     test_constants_sanity();
     test_pack_unpack_round_trip();
     test_pack_clamps_out_of_range_fields();

tools/gui_qso_scenario.sh

@@ -195,6 +195,16 @@ sum_cw_fail() {
 count_deinterleave_fail() { count_pattern 'Frame deinterleave decode FAILED' "$1"; }
 count_deinterleave_ok()   { count_pattern 'Frame deinterleave decode SUCCESS' "$1"; }
 
+count_unexpected_rate() {
+  local file="$1"
+  awk -v expected="$EXPECT_RATE" '
+    /Data mode set to:/ {
+      if (index($0, " " expected " ") == 0) ++n
+    }
+    END { print n + 0 }
+  ' "$file" 2>/dev/null
+}
+
 sum_tx_samples() {
   local file="$1"
   { grep -E 'TX(:| Burst:).* -> [0-9]+ samples' "$file" 2>/dev/null || true; } |
@@ -249,11 +259,11 @@ collect_metrics() {
   [[ -z "$actual_data_mode" ]] && actual_data_mode="unknown"
   alpha_unexpected_modes="$(count_pattern "$unexpected_mode_pattern" "$ALPHA_LOG")"
   bravo_unexpected_modes="$(count_pattern "$unexpected_mode_pattern" "$BRAVO_LOG")"
-  # Forced-rung floor probes (ULTRA_FORCE_DATA_MOD / ULTRA_FORCE_WAVEFORM) PIN the
-  # mod/waveform — the modem cannot adapt away, so the "unexpected data mode" watchdog is
-  # meaningless. Worse, the per-EXPECT_MOD pattern's catch-all (e.g. DQPSK -> the '*' case)
-  # false-matches the NORMAL "Data mode set to:" / "MODE_CHANGE: OFDM" lines, so the live
-  # poll loop kills the run ~2 s after handshake before any data flows. Disable when forced.
+  alpha_unexpected_rates="$(count_unexpected_rate "$ALPHA_LOG")"
+  bravo_unexpected_rates="$(count_unexpected_rate "$BRAVO_LOG")"
+  # Force knobs select the entry profile; ULTRA_LOCK_RATE is what pins it after
+  # handshake. Keep the unexpected-mode watchdog active for locked probes so a
+  # force/authority configuration error cannot be reported as a fixed-rung PASS.
   #
   # --expect-mod any|coherent (2026-06-12, Phase 1): the adaptive ladder is ALLOWED to
   # vary/promote the modulation (e.g. QPSK -> 16QAM under ULTRA_ENABLE_QAM16_LADDER), so a
@@ -264,11 +274,12 @@ collect_metrics() {
   # 2026-07-02: with the fade-riding ladder default-ON (ULTRA_LOCK_RATE=0), mid-transfer
   # rate/modulation moves are the MECHANISM, not a failure — the pinning watchdog only
   # applies when the operator pinned the rate (ULTRA_LOCK_RATE=1).
-  if [[ -n "${ULTRA_FORCE_DATA_MOD:-}" || -n "${ULTRA_FORCE_WAVEFORM:-}" \
-        || "$EXPECT_MOD" == "any" || "$EXPECT_MOD" == "coherent" \
+  if [[ "$EXPECT_MOD" == "any" || "$EXPECT_MOD" == "coherent" \
         || "${ULTRA_LOCK_RATE:-0}" == "0" ]]; then
     alpha_unexpected_modes=0
     bravo_unexpected_modes=0
+    alpha_unexpected_rates=0
+    bravo_unexpected_rates=0
   fi
   file_crc_ok="$(count_pattern "\\[FILE\\] Received .*\\(${FILE_BYTES} bytes, CRC ok|FileTransfer: Received OK \\(${FILE_BYTES} bytes|Received OK .*${FILE_BYTES} bytes.*CRC" "$BRAVO_LOG")"
   alpha_file_done="$(count_pattern '\[FILE\] Transfer complete|FileTransfer: Transfer complete' "$ALPHA_LOG")"
@@ -317,19 +328,20 @@ scenario_passed() {
   # PASS = the file delivered CRC-clean (BRAVO verified the file + ALPHA finalized the
   # transfer). DELIVERY is the verdict.
   #
-  # We do NOT require the run to have hit the EXACT expected (mod, rate). The old gate
+  # Adaptive runs do not have to hit the exact expected (mod, rate). The old gate
   # `alpha_mode_count>0 && bravo_mode_count>0` counted the literal string
   # "configured for <EXPECT_MOD> <EXPECT_RATE>" and so FALSE-FAILED any delivered transfer
   # whose negotiated rate differed from --expect-rate. That is common and correct on a
   # fading channel: at `good --snr-db 16` the MEASURED fading varies seed-to-seed and many
   # seeds land in the Moderate class (>=0.65), where the ladder rightly picks QPSK R1/4 —
   # not the R2/3 a caller guessed. Those runs delivered CRC-clean but were stamped FAIL
   # (REASON=process_exit_before_pass), corrupting reliability sweeps. The actual negotiated
-  # mode is recorded as ACTUAL_DATA_MODE in summary.env for diagnostics; EXPECT_RATE is
-  # only used to size the timeout budget, not to gate PASS.
+  # mode is recorded as ACTUAL_DATA_MODE in summary.env for diagnostics. Locked probes
+  # are different: every reported data-mode rate must match EXPECT_RATE, and the
+  # modulation watchdog below enforces EXPECT_MOD.
   #
-  # We still reject drift to an UNEXPECTED MODULATION (e.g. QAM16 when probing QPSK) — that
-  # is a real "wrong rung" signal, distinct from a benign rate change within the same mod.
+  # We reject drift to an unexpected modulation on locked probes (e.g. QAM16 when
+  # probing QPSK); rate changes are rejected by the unexpected-rate counters.
   #
   # We intentionally do NOT gate on disconnect bookkeeping: the disconnect INITIATOR (ALPHA,
   # on the payload-drained auto-disconnect) quits during teardown and never logs a
@@ -338,13 +350,16 @@ scenario_passed() {
   # verdict; close cleanliness is tracked separately.)
   [[ "$alpha_unexpected_modes" -eq 0 ]] &&
   [[ "$bravo_unexpected_modes" -eq 0 ]] &&
+  [[ "$alpha_unexpected_rates" -eq 0 ]] &&
+  [[ "$bravo_unexpected_rates" -eq 0 ]] &&
   [[ "$file_crc_ok" -gt 0 ]] &&
   [[ "$alpha_file_done" -gt 0 ]]
 }
 
 hard_failure_reason() {
   local pattern='max retries exceeded|maximum retries exceeded|transfer failed|Transfer failed|FileTransfer: .*failed|FILE.*failed|SR-ARQ:.*retries exhausted|Connection: Connect failed|Connect failed after|giving up'
-  if [[ "${alpha_unexpected_modes:-0}" -gt 0 || "${bravo_unexpected_modes:-0}" -gt 0 ]]; then
+  if [[ "${alpha_unexpected_modes:-0}" -gt 0 || "${bravo_unexpected_modes:-0}" -gt 0 \
+        || "${alpha_unexpected_rates:-0}" -gt 0 || "${bravo_unexpected_rates:-0}" -gt 0 ]]; then
     echo "unexpected_data_mode"
     return
   fi
@@ -388,6 +403,8 @@ write_summary() {
     echo "BRAVO_MODE_COUNT=$bravo_mode_count"
     echo "ALPHA_UNEXPECTED_MODE_COUNT=$alpha_unexpected_modes"
     echo "BRAVO_UNEXPECTED_MODE_COUNT=$bravo_unexpected_modes"
+    echo "ALPHA_UNEXPECTED_RATE_COUNT=$alpha_unexpected_rates"
+    echo "BRAVO_UNEXPECTED_RATE_COUNT=$bravo_unexpected_rates"
     echo "FILE_CRC_OK_COUNT=$file_crc_ok"
     echo "ALPHA_FILE_DONE_COUNT=$alpha_file_done"
     echo "ALPHA_DISCONNECTED_COUNT=$alpha_disconnected"

tools/qso_sweep.sh

@@ -65,6 +65,11 @@ while read -r ch snr mod rate fkb _rest || [[ -n "${ch:-}" ]]; do
     dir="$OUT_ROOT/$tag"
     echo ">>> [$i] $ch @ ${snr} dB  $mod $rate  ${fkb} KB  (seed $sd)" >&2
 
+    ULTRA_RX_RATE_AUTHORITY=0 \
+    ULTRA_RX_RATE_CMD=0 \
+    ULTRA_ADAPTIVE_RATE=0 \
+    ULTRA_RATE_ADAPT=0 \
+    ULTRA_LOCK_RATE=1 \
     ULTRA_FORCE_WAVEFORM=OFDM_CHIRP \
     ULTRA_FORCE_DATA_MOD="$mod" \
     ULTRA_FORCE_DATA_RATE="$rate_us" \