Skip to content

refactor(gate): decide the tripwire-accessor collision, and retire two convenience methods (#1271) - #1280

Merged
dc0sk merged 2 commits into
mainfrom
fix/1271-tripwire-labels
Sep 5, 2026
Merged

refactor(gate): decide the tripwire-accessor collision, and retire two convenience methods (#1271)#1280
dc0sk merged 2 commits into
mainfrom
fix/1271-tripwire-labels

Conversation

@dc0sk

@dc0sk dc0sk commented Sep 5, 2026

Copy link
Copy Markdown
Owner

Closes #1271.

The collision, and why it had never been decided

CLAUDE.md's cross-cutting checklist requires a runtime tripwire asserted from the production
path. The standing rule forbids exporting API for an instrument. Seven ModemEngine accessors
sat in the reachability baseline because of that — four of them with no rationale at all until
#1272 — so the contradiction had gone quiet rather than been decided.

The proposal was reviewed before implementing, and rejected

I proposed wiring the notch/AGC state into the control plane via GetConfig, on the reasoning that
it would make the accessors production-reachable and retire the baseline entries.

It would not have. GetConfig is handled on the client task, whose ClientCtx holds
Arc<Mutex> mirrors and no engine. That change would have added a daemon-side shadow of engine
state — correct for the panel, but is_notch_enabled() would still have zero production callers and
stay in the baseline. It would have paid none of the debt it claimed to. The only seam that reads the
engine for clients is the main loop's MetricsSnapshot. Correctly scoped as #1276.

Three claims in my own issue text were wrong

  1. "The asserting test lives in another crate, so it must be pub." The other crate is Cargo's
    integration-test model
    , not the daemon. The collision is a placement fact, not a principle.
  2. "The daemon assertion proves the production path." No such assertion exists — nothing in the
    tree asserts a tripwire through server::run.
  3. agc_gain_db is not a tripwire. Its own docstring calls it "a readout of the active-span loop
    state" where the counters' say "tripwire", and the tests calling it assert behaviour (gain > 6 dB
    on a quiet input) while using agc_blocks_processed as the tripwire in the same test.

What this PR does

  • Deletes a redundant assertion. notch_blocks_processed() > 0 in the daemon cannot fail when
    the in_band_interferers() assertion two lines above passes: the counter increments on the line
    immediately before apply_rx_notch is called, and notch_in_band_interferers is populated only
    inside that function. Verified by reading both sites; the surviving assertion's message now says
    what it subsumes.
  • Separates four TRIPWIRE counters from three READOUT items in the baseline, the latter bound to
    Five front-end toggles are write-only, and two of them make a default install display the opposite of the truth #1276 rather than mislabelled as instruments they are not.
  • Retires add_trusted/add_revoked rather than baselining them — add_entry(.., Full) and
    (.., Revoked) verbatim, 17 call sites. A permanent baseline label for a ten-minute change
    contradicts that file's own "shrink this list" header.
  • Keeps the four counters pub under the TRIPWIRE label. That is a legitimate end state: the
    checklist requires the export, and the ratchet exists to catch new gold-plating, not a labelled
    category.

One correction that came from doing it, not from review

Deleting the two methods produced error: enum PublicKeyTrustLevel is private, and I briefly
concluded the enum really was private, that the two methods were a deliberate façade over it, and
that the deletion should be reverted. It was my import path — the type lives in
openpulse_core::trust, not ::handshake, which the convenience methods had hidden from every call
site. A misleading compiler message nearly reversed a correct decision; what settled it was checking
how other crates name the type, not re-reading the declaration.

Results

suites=324 tests_passed=2456 tests_failed=0
GATE: PASS 6101927ae9f3d18da0716fdc473c061d39d6f275 clean 20260905T153757Z
REACH: PASS  2301 public items, 1794 production-reachable, 507 unreferenced (0 new)

The baseline lost four entries: the two retired, plus decode_signed/encode_signed, which left
by the better route — #1252 gave them a real production caller.

Split out

Review: docs/dev/reviews/2026-09-05-1271-tripwire-accessors.md

🤖 Generated with Claude Code

https://claude.ai/code/session_0188ATCj6DZ9aRVQ2vSirua6

dc0sk and others added 2 commits September 5, 2026 10:50
…o convenience methods (#1271)

CLAUDE.md's cross-cutting checklist REQUIRES a runtime tripwire asserted from the production path;
the standing rule forbids exporting API for an instrument. Seven ModemEngine accessors sat in the
reachability baseline because of that collision — four with no rationale at all until #1272 — so
the contradiction had never been decided, only gone quiet.

Reviewed before implementing, and the review overturned the proposal. I had proposed wiring the
notch/AGC state into the control plane via GetConfig so the accessors became production-reachable.
It would not have: GetConfig is handled on the client task, whose ClientCtx holds Arc<Mutex>
mirrors and no engine, so it would have added a daemon-side shadow and paid none of the debt. Only
the main loop's MetricsSnapshot seam reads the engine. That is now #1276.

Three claims in the issue were wrong: the "other crate" forcing `pub` is Cargo's integration-test
model, not the daemon, so the collision is a placement fact; no test asserts any tripwire through
`server::run`, so the daemon assertion it was justified by does not exist; and `agc_gain_db` is a
readout, not a tripwire, by its own docstring and by what the tests calling it assert.

Changes:
- delete the redundant `notch_blocks_processed() > 0` daemon assertion. Verified redundant by
  reading both sites: the counter increments on the line immediately before `apply_rx_notch` is
  called, and `notch_in_band_interferers` is populated only inside it, so a non-empty list strictly
  implies the counter moved.
- separate four TRIPWIRE counters from three READOUT items in the baseline, the latter bound to
  #1276 rather than labelled as instruments they are not.
- retire `add_trusted`/`add_revoked` rather than baseline them: `add_entry(.., Full)` and
  `(.., Revoked)` verbatim, 17 call sites. A baseline label for a ten-minute change contradicts
  that file's own "shrink this list" header.

One correction from doing it: `PublicKeyTrustLevel` lives in `openpulse_core::trust`, not
`::handshake`, which the convenience methods had hidden from every call site. The resulting build
error read "enum PublicKeyTrustLevel is private" and nearly convinced me the two methods were a
deliberate facade over a private type and the deletion should be reverted. It was my import path.

Results: core 355+9+5+6+20+7+2+6 pass, daemon lib 134 pass, workspace clippy clean, REACH: PASS
(2301 items, 507 unreferenced, 0 new). The baseline lost four entries: the two retired, plus
decode_signed/encode_signed, which left by the better route — #1252 gave them a production caller.

Refactors: CAP-77

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0188ATCj6DZ9aRVQ2vSirua6
…oposal

Refactors: CAP-77

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0188ATCj6DZ9aRVQ2vSirua6
@dc0sk
dc0sk merged commit 4387a84 into main Sep 5, 2026
5 of 6 checks passed
@dc0sk
dc0sk deleted the fix/1271-tripwire-labels branch September 5, 2026 16:23
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Decide the tripwire-accessor collision (a rule requires the export, a rule forbids it) and retire add_trusted/add_revoked

1 participant