fix(hl2): declare the modes this radio cannot transmit in — Principle II.

Hl2Backend declared an empty receiveOnlyModes list under a comment that the
host TX chain was WDSP. It is not: Hl2TxDsp is a phasing SSB modulator whose
mode is read only by isLowerSideband(), so AM/SAM/DSB/FM/NFM/WBFM/WFM/DRM
would key as USB. This PR lists those modes (both spellings) so
RadioModel::refuseKeyInReceiveOnlyMode() refuses MOX, CW keying, and TUNE.

SSB and CW stay off the list. TUNE withdrawal is accepted as the existing
capability contract (same as IC-705 WFM); per-activity granularity is left
to a maintainer.

Tests pin bit-identical IQ vs USB, the live capability list, and TUNE
refusal above the seam.

Squashed-from: #5680
Co-authored-by: on8st <258096273+on8st@users.noreply.github.com>
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: on8st

docs/architecture/radio-capabilities-map.md

@@ -77,7 +77,7 @@ RTL declaration check runs only when the RTL backend is built.
 | `tuningMinHz` / `tuningMaxHz` | — (0/0) | 0.1–38.4 MHz | — (0/0) | `MainWindow_Wiring.cpp`, `applyTuningRangeToOverlayMenu` | Refuses band buttons the receiver cannot reach. 0/0 means unconstrained |
 | `declaredBandRanges` | — (empty) | — (empty) | — (empty) | `SpectrumOverlayMenu::setDeclaredBands` | Optional canonical-name + native coverage list used for backend-authoritative band labels. Icom publishes the IC-9700's three discontinuous deck ranges; empty keeps canonical labels and existing Flex/HL2/Sim presentation |
 | `canTransmit` | ✅ | `m_txAllowed` | ❌ | `RadioModel::setTransmit`, MOX/TUNE key guards | **TX safety gate.** Fail-closed: false denies any keying intent |
-| `receiveOnlyModes` | — (empty) | — (empty) | — (empty) | `RadioModel::refuseKeyInReceiveOnlyMode` (MOX / TUNE / CW-key / `setTransmit`) | Modes the radio **demodulates but will not transmit in**, in the neutral vocabulary. Empty = transmits in everything it receives. Refusing here (not in the backend) is what rolls back `TransmitModel`'s optimistic MOX/TUNE state — a backend cannot reach `TransmitModel`, so a refusal made down there leaves the TX indicator lit and TUNE latched. Icom: `["WFM"]` on the IC-705, which receives 76–108 MHz broadcast and does not transmit there (#5040) |
+| `receiveOnlyModes` | — (empty) | AM · SAM · DSB · FM · NFM · WBFM · WFM · DRM | — (empty) | `RadioModel::refuseKeyInReceiveOnlyMode` (MOX / TUNE / CW-key / `setTransmit`) | Modes the radio **demodulates but will not transmit in**, in the neutral vocabulary. Empty = transmits in everything it receives. Refusing here (not in the backend) is what rolls back `TransmitModel`'s optimistic MOX/TUNE state — a backend cannot reach `TransmitModel`, so a refusal made down there leaves the TX indicator lit and TUNE latched. Icom: `["WFM"]` on the IC-705, which receives 76–108 MHz broadcast and does not transmit there (#5040). HL2: `Hl2TxDsp` is a phasing SSB modulator whose stored mode is read only by `isLowerSideband()`, so every mode above takes the USB branch and would go on the air as SSB announcing nothing — both spellings of each alias are listed because the guard compares the string the slice holds. **Note what a non-empty list costs:** `beginLocalTxActivity` runs this guard for EVERY `TxActivity`, so it withdraws TUNE in those modes as well as MOX and CW keying, even where the tune carrier itself would be clean |
 | `hostModulates` | — (❌) | ✅ | — (❌) | `TciServer`, `MainWindow_Session` | Mic source collapses to PC; PC-audio lock. **Not the same question as `takesTxAudioOverSeam`** — see below |
 | `takesTxAudioOverSeam` | ❌ | ✅ | ❌ | `MainWindow_Session` (capture, TX stream, PC-audio lock), `AudioEngine::setHostModulation`, `RadioModel::ensureDaxTxStream` | Whether transmit audio leaves through `submitTxAudio` rather than a DAX/VITA-49 stream. Icom: ✅ |
 | `hasRadioPttReadback` | ❌ | ❌ | ❌ | `RadioModel::publishCommandedBackendTransmitEdge`, `Ax25HfPacketDecodeDialog::beginTransmitWhenReady` | The backend's `transmitChanged` / `keyingStateConfirmed` carry the **radio's own** PTT readback and `setKeying()` is intent only. True suppresses RadioModel's command-edge fallback, and makes AetherModem wait for `radioTransmittingChanged` / `radioTransmitConfirmed` (or an already-keyed radio) before releasing sample zero. Flex: ❌ because its interlock edge is decoded inside RadioModel, not through the seam. Icom: ✅ (decoded CI-V `1C 00`, #5311) |
@@ -538,7 +538,11 @@ predicates the readouts ask before printing. See [`HERMES.md`](../HERMES.md)
   (Principle I). That is derived-from-name truth being used to *seed*
   reported-by-backend truth; the two remain distinct concepts.
 - **Hl2Backend** reports `canTransmit` from its own TX gate (`m_txAllowed`) so a
-  build with transmit disabled looks RX-only from above the seam.
+  build with transmit disabled looks RX-only from above the seam. Its
+  `receiveOnlyModes` is hand-listed rather than derived, and the evidence for the
+  list is a test, not the list: `tests/hl2_txdsp_test.cpp` asserts each declared
+  mode produces IQ **bit-identical** to USB, and `tests/hl2_family_transition_test.cpp`
+  asserts the live backend still declares every one of them.
 - **IcomCivBackend** derives `receiveOnlyModes` from `modeListFor()` filtered by
   `modeIsReceiveOnly()` rather than listing it a third time, so a mode cannot be
   offered in the combo without a consistent transmit answer for it. It also

src/core/backends/hl2/Hl2Backend.cpp

@@ -1681,11 +1681,71 @@ RadioCapabilities Hl2Backend::capabilities() const
     // Reported from the gate, not hardcoded: the engine's TX guard keys off this,
     // so a build with transmit disabled must look RX-only from above the seam.
     c.canTransmit = m_txAllowed;
-    // The HL2 modulates on this host, so it transmits in whatever mode WDSP is
-    // told to build — there is no mode it receives and cannot send. The transmit
-    // gate (m_txAllowed) is the only thing that stops it, and that is
-    // canTransmit above.
-    c.receiveOnlyModes = {};
+    // THE MODES THIS RADIO DEMODULATES AND CANNOT MODULATE.
+    //
+    // The comment that stood here said the HL2 "transmits in whatever mode WDSP
+    // is told to build — there is no mode it receives and cannot send", and left
+    // the list empty on that basis. **The transmit chain is not WDSP.**
+    // Hl2TxDsp is a hand-written phasing SSB modulator: setMode() stores the
+    // mode and the only reader is isLowerSideband(), which returns true for Lsb,
+    // Cwl and Digl and false for everything else. So AM, SAM, DSB, FM, NFM, WBFM
+    // and DRM all take the upper-sideband branch and go on the air as SSB,
+    // announcing nothing.
+    //
+    // WHAT STAYS OFF THE LIST, deliberately:
+    //
+    //   * USB / LSB / DIGU / DIGL are the SSB family and modulate correctly.
+    //   * CW / CWU / CWL keys a carrier the GATEWARE shapes at the TX NCO
+    //     (MetisClient::setCwKeyDown). That path never reaches Hl2TxDsp, so the
+    //     sideband switch above does not apply to it and CW transmits correctly.
+    //
+    // These strings are the neutral vocabulary SliceModel carries, and both
+    // spellings of each mode appear because modeFromString() accepts both:
+    // refuseKeyInReceiveOnlyMode() compares what the slice holds, not what this
+    // backend would have mapped it to, so listing only one spelling would leave
+    // the other keying.
+    //
+    // THIS DECLARATION ALSO WITHDRAWS TUNE IN THESE MODES. Say so here rather
+    // than let an operator discover it.
+    //
+    // refuseKeyInReceiveOnlyMode() is not a MOX-and-CW guard.
+    // RadioModel::beginLocalTxActivity() runs it for EVERY TxActivity, ahead of
+    // the per-activity capability checks, so TxActivity::Tune is refused too —
+    // and that one is a real loss, not a theoretical one. setTune() below raises
+    // the carrier from the GATEWARE test-tone generator at zero offset
+    // (MetisClient::setTxTestTone), a path that never reaches Hl2TxDsp, exactly
+    // like the CW keyer exempted above. This radio could put a clean tune
+    // carrier on the air with the TX slice in AM or FM; after this list it will
+    // not, and the operator is told "Choose a transmit mode first" and has to
+    // move the slice to a mode that transmits. (TxActivity::Atu was already
+    // refused here for want of hasTuner, so the plain TUNE button is the only
+    // behaviour this changes.)
+    //
+    // ACCEPTED, deliberately, on two grounds:
+    //
+    //   * It is what this capability already MEANS. The IC-705 declares WFM
+    //     receive-only (#5040) and is refused on this same guard, with a second
+    //     wire backstop in IcomCivBackend::refuseKeyingInReceiveOnlyMode() that
+    //     its setTune() converges on through setKeying() — "shared by every path
+    //     here that can start an emission", in its own words. HL2 is inheriting
+    //     a settled contract, not inventing one.
+    //   * receiveOnlyModes is ONE list of mode names with no per-activity
+    //     granularity, so exempting tune is not expressible from a backend at
+    //     all: it would mean changing RadioModel above the family seam, for
+    //     every family at once. That is a maintainer's call.
+    //
+    // The CW/tune asymmetry is in the SHAPE of the list, not in the reasoning
+    // behind it: CW stays off because CW is a MODE this radio transmits
+    // correctly, and tune is an ACTIVITY, which a list of mode names has no
+    // vocabulary for.
+    //
+    // What the list itself reports is only what the modulator does today. When a
+    // mode genuinely transmits — the WDSP TXA chain carries all of these — its
+    // entry comes back off this list and the tune refusal lifts with it.
+    c.receiveOnlyModes = {QStringLiteral("AM"),   QStringLiteral("SAM"),
+                          QStringLiteral("DSB"),  QStringLiteral("FM"),
+                          QStringLiteral("NFM"),  QStringLiteral("WBFM"),
+                          QStringLiteral("WFM"),  QStringLiteral("DRM")};
     c.hostModulates = true;
     // Same tap, same seam — see RadioCapabilities::takesTxAudioOverSeam.
     c.takesTxAudioOverSeam = true;             // PC runs the modulator; no on-radio mic jacks

tests/atu_seam_gate_test.cpp

@@ -135,6 +135,37 @@ static void receiveOnlyModeBlocksStart()
     check(f.backend->atuStarts == 1, "transmit mode: start dispatches once");
 }
 
+// The ATU cycle is not the only thing a receive-only mode withdraws.
+//
+// beginLocalTxActivity() runs refuseKeyInReceiveOnlyMode() for EVERY
+// TxActivity, ahead of the per-activity capability checks, so the plain TUNE
+// carrier goes with it — on every family, including one whose tune carrier is
+// raised in gateware and would have been perfectly clean (HL2's built-in test
+// tone at zero offset, PR #5680). Asserted rather than reasoned about: it is
+// the consequence an operator actually meets, and it needs its own fixture
+// because emitInterlockNotification() deduplicates an identical key for 5 s,
+// so a second refusal in the same fixture would be silent.
+//
+// The interlock key is what makes this discriminating: a TUNE stopped by the
+// PTT preflight or the CW-keyed tune admission raises pttBlocked and no
+// interlock at all, and would fail this rather than pass it.
+static void receiveOnlyModeBlocksTune()
+{
+    Fixture f(QStringLiteral("icom"), /*canTransmit=*/true, {QStringLiteral("WFM")});
+    f.setMode(QStringLiteral("WFM"));
+    f.radio.transmitModel().startTune();
+    check(!f.radio.transmitModel().isTuning(),
+          "receive-only mode: TUNE does not latch");
+    check(f.interlocks.contains(QStringLiteral("rx-only-mode:WFM")),
+          "receive-only mode: the TUNE refusal names the mode");
+    // Leaving the mode gives the carrier back.
+    f.setMode(QStringLiteral("USB"));
+    f.radio.transmitModel().startTune();
+    check(f.radio.transmitModel().isTuning(),
+          "transmit mode: TUNE latches again");
+    f.radio.transmitModel().stopTune();
+}
+
 static void panInhibitBlocksStart()
 {
     Fixture f(QStringLiteral("icom"), /*canTransmit=*/true);
@@ -178,6 +209,7 @@ int main(int argc, char** argv)
     permittedStartDispatchesOnce();
     receiveOnlyBackendBlocksStart();
     receiveOnlyModeBlocksStart();
+    receiveOnlyModeBlocksTune();
     panInhibitBlocksStart();
     flexUsesTheSameTypedPath();
     std::printf("%d failure(s)\n", failures);

tests/hl2_family_transition_test.cpp

@@ -88,6 +88,51 @@ int main(int argc, char** argv)
     check(model.panStream() == nullptr,
           "HL2 owns no PanadapterStream");
 
+    // ---- The modes the LIVE HL2 backend declares it will not transmit in ----
+    //
+    // hl2_txdsp_test proves the modulator half: AM/SAM/DSB/FM/WBFM/DRM each
+    // produce IQ bit-identical to USB, so none of them is a distinct
+    // modulation. What that test cannot see is the DECLARATION — delete a
+    // string from Hl2Backend::capabilities()'s receiveOnlyModes and it still
+    // passes. This is the live target that reads it, so the list and the
+    // evidence cannot part company unnoticed.
+    //
+    // EIGHT strings, SIX enumerators: modeFromString() maps NFM onto Mode::Fm
+    // and WFM onto Mode::Wbfm, and refuseKeyInReceiveOnlyMode() compares the
+    // string the SLICE holds rather than the enumerator this backend would have
+    // mapped it to — so dropping either alias leaves that spelling keying while
+    // its twin is refused. That is the load-bearing claim, and nothing asserted
+    // it before this block.
+    {
+        const RadioCapabilities caps = model.backendCapabilities();
+        const QStringList declared = {
+            QStringLiteral("AM"),   QStringLiteral("SAM"),
+            QStringLiteral("DSB"),  QStringLiteral("FM"),
+            QStringLiteral("NFM"),  QStringLiteral("WBFM"),
+            QStringLiteral("WFM"),  QStringLiteral("DRM"),
+        };
+        for (const QString& m : declared) {
+            check(modeIsReceiveOnly(caps, m),
+                  qPrintable(QStringLiteral("HL2 declares %1 receive-only").arg(m)));
+        }
+        // Exactly these. An ADDITION is a mode in which the operator silently
+        // loses MOX, CW keying and TUNE, so it must not arrive without the
+        // bit-identity evidence landing beside it.
+        check(caps.receiveOnlyModes.size() == declared.size(),
+              "HL2 declares exactly the modes hl2_txdsp_test carries evidence for");
+        // The deliberate exclusions: SSB modulates correctly, and CW keys the
+        // gateware NCO through MetisClient::setCwKeyDown without ever reaching
+        // Hl2TxDsp. If one of these ever appears on the list it takes an
+        // operator's transmit mode away.
+        for (const QString& m : {QStringLiteral("USB"),  QStringLiteral("LSB"),
+                                 QStringLiteral("DIGU"), QStringLiteral("DIGL"),
+                                 QStringLiteral("CW"),   QStringLiteral("CWU"),
+                                 QStringLiteral("CWL")}) {
+            check(!modeIsReceiveOnly(caps, m),
+                  qPrintable(QStringLiteral("HL2 still transmits in %1").arg(m)));
+        }
+    }
+
     // ── The normalized RX-audio bus ────────────────────────────────────────
     //
     // The CW decoder, the RTTY decoder and the QSO recorder's RX tap all ride

tests/hl2_txdsp_test.cpp

@@ -215,6 +215,69 @@ int main(int argc, char** argv)
         }
     }
 
+    // ---- THE MODES Hl2Backend DECLARES RECEIVE-ONLY ARE BIT-IDENTICAL TO USB ----
+    //
+    // This is the evidence behind `Hl2Backend::capabilities`'s
+    // `receiveOnlyModes` list, and it is deliberately stronger than asserting
+    // that a list contains some strings. A list can drift from the modulator;
+    // this cannot.
+    //
+    // Hl2TxDsp::setMode() stores the mode and the ONLY reader is
+    // isLowerSideband(), which returns true for Lsb/Cwl/Digl and false for
+    // everything else. So AM, SAM, DSB, FM, WBFM and DRM do not take some
+    // degraded AM or FM path -- they take the USB path exactly, and what goes on
+    // the air is single-sideband suppressed carrier while the mode indicator
+    // says otherwise.
+    //
+    // If someone later teaches this chain a real AM or FM modulator, this block
+    // FAILS, which is the point: the failure is the reminder to take that mode
+    // back off the receive-only list.
+    //
+    // SIX enumerators here cover EIGHT declared strings: Hl2Backend's
+    // modeFromString() maps NFM onto Mode::Fm and WFM onto Mode::Wbfm, so those
+    // two spellings have no enumerator of their own to modulate. That the
+    // DECLARATION still carries both — the guard compares the string the slice
+    // holds, not the enumerator — is asserted in hl2_family_transition_test,
+    // which reads capabilities() off a live backend. This file cannot see it.
+    {
+        const double usbBand[2] = {300.0, 2700.0};
+        const auto reference = modulate(WdspChannel::Mode::Usb, kTone, 0.25,
+                                        1.0, 1.0, nullptr, false, usbBand);
+        check(!reference.empty(), "USB reference modulation produced IQ");
+
+        struct DeclaredReceiveOnly { const char* name; WdspChannel::Mode mode; };
+        const DeclaredReceiveOnly declared[] = {
+            {"AM",   WdspChannel::Mode::Am},
+            {"SAM",  WdspChannel::Mode::Sam},
+            {"DSB",  WdspChannel::Mode::Dsb},
+            {"FM",   WdspChannel::Mode::Fm},
+            {"WBFM", WdspChannel::Mode::Wbfm},
+            {"DRM",  WdspChannel::Mode::Drm},
+        };
+
+        for (const DeclaredReceiveOnly& d : declared) {
+            const auto iq = modulate(d.mode, kTone, 0.25, 1.0, 1.0,
+                                     nullptr, false, usbBand);
+            check(iq.size() == reference.size(),
+                  "declared receive-only mode produced the same sample count as USB");
+            bool identical = (iq.size() == reference.size());
+            std::size_t firstDiff = 0;
+            for (std::size_t k = 0; identical && k < iq.size(); ++k) {
+                if (iq[k] != reference[k]) { identical = false; firstDiff = k; }
+            }
+            std::fprintf(stderr,
+                         "%-4s vs USB: %s\n", d.name,
+                         identical ? "bit-identical (no distinct modulation)"
+                                   : "DIFFERS -- a real modulator now exists");
+            if (!identical) {
+                std::fprintf(stderr, "  first difference at sample %zu\n", firstDiff);
+            }
+            check(identical,
+                  "this mode is indistinguishable from USB, which is why "
+                  "Hl2Backend declares it receive-only");
+        }
+    }
+
     // ---- audio outside the passband does not get transmitted ----
     {
         // 5 kHz is well above the 2700 Hz TX filter.