feat(hl2): drive the automatic RF gain on measured wideband headroom (RFC #5535)

[on8st]

This implements the design in #5535 and waits on that ruling

Draft on purpose. GOVERNANCE.md says "Do not open a PR until the RFC issue is approved." The RFC this belongs to is #5535, and it is open — ON8ST posted his design answer there on 2026-09-12 (automatic by default, a manual override, and a visible clipping indicator modelled on the HL2's own LEDs) and it has not been ruled on. A draft shows the code in the review interface without claiming it is ready to merge, which seemed the honest way to respect that rule rather than route around it. It does not ask to be merged before #5535 is decided.

Off by default. No installation's behaviour changes until an operator switches the control on. #5535 asks for automatic-by-default; that default flips if and when the design is ratified. Shipping it opt-in is the first increment of that design, not a contradiction of it — the switch, the bound and the law are all here, and the default is one line.

---

What the regulator drives on now, and what it used to

It used to drive on the ADC clip counter, and that premise is retracted.

The control law was sized against response address 0's DATA[24] read as "the converter railed". It is not that. The bit is (&clip_cnt) — the reduction AND of a two-bit saturating counter cleared on every resp_rqst — so it is true only when that counter saturated, and it means "at least three clip events in one reporting interval". At idle nothing clears it and it is an uncleared latch of unknown age. (Correction recorded on #5354.)

Two consequences, both now written into Hl2AutoGainPolicy.h and MetisProtocol.h beside the fields they invalidate:

• Clean does not mean "not clipping." It means "fewer than three clip events per reporting interval", which at 76.8 MSPS is a great deal of clipping. No amount of tuning the thresholds recovers what the bit never carried.
• The rate is coarser than it looks. It is a rate of threshold crossings of a three-event counter. It stays ordinal — which is why three coarse states survive the correction and a proportional law still would not — but it is not a magnitude and never was.

It now drives on the wideband bandscope (endpoint 0x04).

The bandscope samples rx_data — the AD9866's output register, pre-DDC, pre-decimation, pre-NCO — so it sees the whole 0–38.4 MHz the converter sees. That is the property that matters and neither existing level reading has it: the S-meter and WDSP's RXA_ADC_PK are both post-DDC and describe one slice. A broadcast station 20 MHz away can saturate the converter while the operator's slice sits 40 dB below full scale, and nothing they can currently see says so.

Because it comes off the same register rxclip and rxgoodlvl are derived from, it is commensurable with the clip flag by construction rather than by measurement — unlike the WDSP pairing, which #5626 correctly says is not.

What that changes in the law. Hl2AutoGainPolicy.h's own comment used to read: "NOTHING ON THIS RADIO MEASURES HEADROOM … so the only way to find out whether the gain can come back is TO TRY IT AND SEE." That is why a release had to be a deliberate probe costing a clipped window when it failed. Now a release is licensed by a measurement: the clip flag still establishes only that the loop is allowed to try, and the reading establishes that the room exists.

Where the old input survives, and why. The clip flag is still the attack trigger and still the veto. It inspects every sample; the gated bandscope inspects 2048 out of every 76 800 000 (0.0027 %). One is a veto with total coverage and no magnitude; the other is a magnitude with almost no coverage. Wiring them as veto-and-magnitude is the design, and it is failure-safe in the right direction: a transient the bandscope missed cannot cause a release, because a release also requires the flag to have stayed clear.

---

The one number that is not decoration

A gated peak systematically understates the true peak — the maximum of a sample is a function of how many samples you took — and the error is in the dangerous direction, because it makes the band look quieter than it is. Under a stated Gaussian model the bound at the shipped 1 Hz gate is 3.77 dB, and a release must clear step + bias + margin.

It is budgeted as margin, never subtracted as a correction: the bound is an upper bound, the true error on a real band lies somewhere between it and zero, and nobody has measured where. The figure is computed from MetisClient::bandscopeSamplePeriodMs() rather than written as a literal, so changing the gate cannot silently invalidate it. A test pins that deleting the bias term would have licensed a step the reading could not support.

gatedPeakBiasDb is checked against the study's own independently-computed table at five duty cycles.

---

What is deliberately NOT decided here

Three things are left alone on purpose, because deciding them in code is what the RFC exists to prevent.

1. The probe interval is not shortened. probingReleaseConfig() justifies its 30 s base interval by the cost of a failed probe ("one failed probe per interval is 100 ms of clipping"). A measurement-licensed release is not expected to fail, so that justification genuinely weakens and a shorter interval would reclaim gain faster after a band goes quiet. How fast an automatic control may give gain back is a control decision with an operator-visible consequence; the evidence that would size it is a live-antenna measurement nobody has taken. The loop is strictly more cautious than probing was, and the number is one line to change once there is a ruling.

2. maxOffsetDb is probably larger than the hardware has, and is not changed. The 24 dB was sized when the LNA axis was believed to span 31 dB. ON8ST retracted that on [RFC] Automatic RF-gain protection for the Hermes-Lite 2 #5535: the gain folds & 0x1F above code 31 (Hermes-Lite2 Profile Manager Save #177, design intent per softerhardware), codes 28–31 sit within 0.07 dB, leaving about 17.8 dB usable — one board, measured once, confirmed by nobody else. Picking a new ceiling from a single unreplicated measurement would be deciding the RFC's question. Meanwhile the behaviour is safe rather than silent: Hl2GainSplit.h clamps to the register floor and reports the offset actually applied, and the AtFloor branch lights the "the front end needs attenuation ahead of the radio" warning rather than attacking into a fold forever.

3. The visible clipping indicator is not in this PR. [RFC] Automatic RF-gain protection for the Hermes-Lite 2 #5535 asks for one on the HL2's LED model and takes it as a condition rather than a nicety. That is display, it belongs to the bandscope study's phase D, and it wants its own RFC. What this PR does is make sure the source exists: out-of-slice clipping is precisely the case an operator cannot otherwise diagnose, and Hl2BandscopeHeadroom.h already classifies it (AtRail / NearRail / Measured / Absent, plus the ClippedBetweenBlocks pairing the indicator would have to render honestly). It is display-only today and nothing reads it back.

One part of #5535's answer is already satisfied: "the regulator's own action has to be visible too." pushEffectiveLnaGain() echoes the effective gain to every pan, so the RF Gain slider moves when the loop moves it — the operator is shown what the radio is actually doing, and the stored baseline is what is preserved.

---

Localization

docs/HERMES.md — "For coding agents — keep bring-up inside the family backend", written by @jensenpat in f6f56458 — is the rule this branch is measured against, and this is the branch with the most shared surface we have filed. Stating the hits rather than letting a reviewer find them.

The pre-PR grep returns 4 hits across 2 classes, down from 5 files; src/gui/MainWindow_Session.cpp now returns to origin/main exactly.

hit	what remains	why it is explained
src/models/RadioModel.h	one accessor declaration, autoRfGain()	The seam verb. It was four forwarders (hasAutoRfGain / setAutoRfGain / setAutoRfGainFloorDb / setAutoRfGainMode); it is now a single borrowed IAutoRfGainControl*, so adding a law or a bound to any future family's loop touches this header not at all. Names no family.
src/models/RadioModel.cpp	one 8-line function	Returns nullptr when there is no backend or it is disconnected — the non-permissive rule, in one place. Names no family, does no cast, knows nothing about what a law is.
src/gui/MainWindow.cpp	two lines inside the existing applyRadioSideDspToPanDisplay()	Rides a capability fanout that already exists and already does exactly this for setDaxStreamsAvailable. The family-suffixed settings-key helper that used to live here is gone, and with it the only place above the seam that touched a family string.
src/gui/MainWindow_Wiring.cpp	one connect lambda	Commands the control and reflects what actually happened. It owns no storage any more. A signal from a widget has to be connected somewhere, and this is where every other overlay-menu signal is connected.

Not grep-block hits, but shared surface, so named anyway: src/gui/SpectrumOverlayMenu.{h,cpp} (the Auto checkbox and the read-only-while-armed slider), src/core/AutomationServer.cpp (the pan autorfgain bench verb — the GUI control lives in a popup and doInvoke() refuses a non-visible widget, so without it the loop cannot be disarmed headlessly), and src/core/RadioCertification.cpp (suspends the loop across the gain-sweep exercise, or the loop moves gain mid-exercise and the stage's one hard finding fires as a permanent false positive).

Two things the rule caught that were genuine defects

A capability bool could not land at all. #5619 froze the RadioCapabilities boolean population at 71, shrink-only, enforced by tools/check_capability_records.py --strict in the Static checks job that #5633 made required. hasAutoRfGain made it 72 — this branch as written would have failed CI on a check that did not exist when it was written. RadioCapabilities now gains nothing (back to 71) and the three IRadioBackend virtuals collapse into one handle, the shape #5642 used for IOfflineHealthSource. The rule's own reasoning applies on the merits too: a bool would have fissioned immediately, because the first GUI to draw this control needed the floor bound and the law list as well — which in practice meant reading an untyped health row by string key, in two places. Both now ask isArmed().

The switch was persisted in a flat AppSettings key, which the same HERMES section names as a prohibition: a value the radio cannot store belongs in that family's OperatingState path, "never in a flat AppSettings key". DisplayAutoRfGain_<family> was exactly that. It now rides Hl2Backend::currentOperatingState()'s existing rfGain object as autoEnabled. The switch only — the offset the loop is holding is still deliberately not persisted, because an automatic transient that outlived its session would be indistinguishable next launch from a gain the operator chose.

Arming is deferred to the connect edge rather than done in restoreOperatingState, because the control refuses to arm from a baseline it does not trust and the restored baseline does not reach m_lnaGainDb until pushInitialState(). So restore records the wish and the connect edge acts on it — which also makes a refusal survivable: the preference stays recorded, the control stays off, and the next connect from a trusted baseline honours it without the operator asking twice.

---

Tests

Everything decidable is a pure function, for Hl2OverloadPolicy.h's reason and harder: these branches are otherwise reachable only by driving a real converter into overload with a real out-of-slice signal, which a test suite cannot arrange.

• hl2_bandscope_headroom_test — new. The dB scale against the gateware's own thresholds (rxclip at 2048 → 0.00 dB, rxgoodlvl at 1536 → 2.50 dB), which would catch the kFullScale copy-paste that makes every block ~66 dB quiet; the bias model against the study's published table; and the pairing, including the trap — a clean block while the flag says clipped is the gate's blind interval, not evidence against the flag.
• hl2_auto_gain_policy_test — 19 new checks. The requirement in both directions, absent-is-not-zero, that the licence is checked against the step actually taken, that a refusal is not a failed probe and earns no backoff, and that a railed block only ever escalates. Plus the equivalence that makes this safe to ship off: with the requirement off, the headroom reading changes nothing at any offset or window verdict, so ramp, probe and binary are exactly the laws that existed before this sensor did.

This stacks on #5650 and its first four commits ARE #5650. Phases 1–4 of the bandscope — the parser, the ingest, the duty-cycle gate and the uncalibrated health rows — are that PR. It targets main from the same fork, so GitHub cannot express the dependency as a base branch and the commits appear here too. Review #5650 first, and read only the six commits after 9feee1ab as this PR's own work. If #5650 merges, this rebases to nothing but those six.

---

What is not proven

No radio ran. The study's Procedure C — does a bandscope reading mean on a live antenna what the arithmetic says it means — needs an antenna, has not been run, and is not scheduled. Every level this PR surfaces is labelled uncalibrated and pre-DDC for that reason, and the labels say "below the converter's clip point" rather than a bare "dBFS", because the second invites being read as an absolute. What is exact is the relationship to the converter's own clip threshold, and that is exact by construction rather than by measurement.

[aethersdr-agent]

Thanks for this — and thanks for filing it as a draft with the #5535 dependency stated up front. Two Static checks steps failed on ef4f5be8 (run 34718815992), and both are real, both are in this PR's own six commits (not inherited from #5650), and both are small. The three compile jobs (build, check-macos, check-windows) were still in progress when I looked, so nothing below says anything about whether the code compiles.

I reproduced both locally against merge-base(pr, main) = 85c9413b, and verified each fix clears its gate.

---

1. aetherd touchpoint manifest — the new seam header has no semantic tag

::error::aetherd touchpoints require a valid semantic tag: core/backends/AutoRfGainControl.h

tools/gen_touchpoint_manifest.py scans src/gui/ + src/main.cpp for includes that reach into src/core/ or src/models/. Your new header is included by two UI files —

• src/gui/MainWindow.cpp:12
• src/gui/MainWindow_Wiring.cpp:21

— so core/backends/AutoRfGainControl.h becomes touchpoint 217, and every live touchpoint must carry a tag matching TAG_RE in docs/architecture/aetherd-touchpoint-tags.json. There is no entry for it, so --check fails before it even gets to the staleness comparison. The regenerated manifest row currently reads | core/backends/AutoRfGainControl.h | 2 | — | unconverted | — the — is the missing tag.

Fix — two files:

1. Add an entry to docs/architecture/aetherd-touchpoint-tags.json. universal is the right tag by the legend's own wording, and by the argument you already make in the Localization table: the header names no family and does no cast. Something like:

  "core/backends/AutoRfGainControl.h": {
    "tag": "universal",
    "note": "Backend-neutral handle for an automatic RF-gain loop consumed above the radio seam; names no family. Family implementations own the law.",
    "split": "",
    "confidence": "high"
  }

2. Run python tools/gen_touchpoint_manifest.py and commit docs/architecture/aetherd-touchpoints.md. It is generated — do not hand-edit the table; the totals line also moves (216 → 217, 184 → 185 core). Missing this second step is its own failure even once the tag is added, because --check compares the committed manifest byte-for-byte.

With both done, --check prints manifest up to date and exits 0 — confirmed on your head.

---

2. Hardcoded-colour ratchet — one new setStyleSheet() call site

OK   unique_colours       613  (base 613, +0)
OK   total_references    2724  (base 2724, +0)
OVER setstylesheet       1082  (base 1081, +1)

You added no colours at all — the +1 is the call site, and there is exactly one new one in the whole diff:

src/gui/SpectrumOverlayMenu.cpp:760 (from e9240294)

m_autoRfGainCheck->setStyleSheet(kLabelStyle);

The ratchet (tools/audit_colours.py, #4569 / RFC #3076) counts call sites, not colours, so migrating a colour to a token cannot clear this one — the tool's own hint says as much.

The good news: that line is a no-op. kLabelStyle (line 252) is a single QLabel { … } rule. m_autoRfGainCheck is a QCheckBox, which is not a QLabel and has no QLabel child, so the selector matches nothing and the checkbox renders identically without it. Deleting line 760 is the fix, and it costs no appearance:

OK   setstylesheet       1081  (base 1081, +0)

— verified by deleting exactly that line on your head and re-running the gate.

If you do want the "Auto" text to match the RF Gain: / 0 dB labels beside it (it currently won't — it inherits the popup's default text colour, not #8aa8c0), then adding a QCheckBox { … } rule to the popup's own existing setStyleSheet() site and letting it cascade keeps the count flat, whereas a fresh per-widget call will fail the ratchet again. That is a visual-polish call, not a CI one.

---

Neither of these touches the substance of the PR — the veto-and-magnitude wiring, the gated-peak bias budgeted as margin rather than subtracted as a correction, and the Clean-does-not-mean-not-clipping retraction written next to the fields it invalidates are the parts worth a reviewer's time, and they're all intact. Nice work on catching the frozen-71 capability-bool problem before CI did, too.

One thing I'd flag rather than fix: the ratchet resolves its base as git merge-base HEAD origin/<base_ref>, so if you rebase onto a newer main the base moves with you and neither of these two counts should shift. No need to rebase to clear them.

---

_{🤖 aethersdr-agent · cost: $3.5573 · model: claude-opus-5}

[on8st]

Re-stacked on the rebased #5650 at 406a4a44; the base is hl2/bandscope-ep4 at 63b67305, which is itself on 87b80c65. Two conflicts, both resolved by keeping both sides: tests/tests.cmake (main's five stream-free telemetry targets alongside our hl2_gain_split_test), and Hl2Backend.cpp's Converter section — where our LNA baseline/effective split now reads t.adcOverload rather than m_telemetry.adcOverload, so it honours main's telemetryLinkState() staleness gate instead of stepping around it. Full ctest 428/429, the one failure vkamp_connection_test, unrelated and reproducible on an untouched tree.

GitHub will keep reporting this CONFLICTING while its baseRefName is main rather than the parent branch — it computes mergeability against main regardless of the stack. Merging #5650 first resolves it.

[on8st]

Re-stacked at c518a49c on #5650's e8260c93, which is on d9e8b986.

Six conflicts. Two are worth naming because the resolution is not mechanical:

• healthSnapshot()'s Converter section. feat(hl2): pair WDSP RXA_ADC_PK with the pre-DDC clip flag (§13 item 16) #5626 merged into main while this was building, so main now carries the whole ADC-pairing block. Kept it in full and appended this PR's LNA baseline/effective/offset rows after it, rather than the other way round — the pairing's own adcOverload row (which reads t.adcOverload) stands, and the duplicate this branch carried is gone.
• pushEffectiveLnaGain(). Main gained the AGC-ceiling lockstep loop with feat(hl2): refer the AGC ceiling to the dB reference (§13 item 12) #5625 after this branch forked, so our side of the conflict simply did not have it. Taking our side wholesale would have silently dropped it. Kept both: the wire now takes effective, and the ceiling loop stays — it reads m_dbRef, which setLnaGainDb(effective) two lines above has already re-referred, so the ceiling follows the effective gain rather than the baseline. That is the behaviour feat(hl2): refer the AGC ceiling to the dB reference (§13 item 12) #5625 landed, preserved through an automatic offset.

Also merged rather than chosen: the ADC clip-rate counters now sit inside the non-ACK branch of the EP6 parse. An ACK's raddr is a command address, so 0x00 there is a C&C bank and not the status response — counting it would put our own echoes in the denominator.

Full ctest 433/433, zero failures.