Make the calculator roster a checkable contract: declare which tables each calculator writes, then verify it produces rows

[WilfordGrimley]

The gap, stated precisely

check_calculator_roster_tether() (PR #562) asserts exactly one thing:

if re.search(r"(?<![\w-])" + re.escape(identity) + r"(?![\w-])", prose):
    continue
findings.append("...calculator roster drift: identity `X` is declared in code but has no entry...")

It searches docs/pipeline-fidelity-gate.md for the identity string. That is the whole check. It verifies the calculator is mentioned in a document — not that the mention is true, and not that the calculator produces anything.

Its own error message asks the author to state dormant or casts no votes. Nothing verifies that claim against reality.

Consequence, live today: the tether passes for local-name-frequency-v1, a calculator that has cast nothing in its entire existence — 0 rows in every vote table, 0 of 994 PilotRunLedger rows, never called by anything. It is documented, so it is clean. That is the exact failure mode the tether was built to catch, surviving inside the tether.

We made the mention mandatory and left the accuracy unchecked.

Why this matters — three channels, zero read as "fine" every time

channel	what happened	how long undetected
stage-d-illustration-v1	3 votes ever — its eligibility gate read ImageEvidence.layout_class believing it carried faced-ness, when that column holds a border colour (non-blank on 99.34% of rows)	since it was written
local-name-frequency-v1	never called, never run — 0 of 994 ledger rows	13 days, across two review passes
local-fallback-v1 chips	53,966 CardTagVote rows (border / frame-style / bleed-edge) destroyed by an identity-scoped purge that was meant to be channel-scoped	caught immediately, but only by luck

A dormant channel generates no divergence to explain, so a coverage-based audit reads it as clean by being invisible.

The design: one declaration, two checks

Rather than bolt a second, parallel check alongside the tether, extend the roster entry itself into a machine-readable contract.

Each entry in docs/pipeline-fidelity-gate.md declares which tables that calculator writes — a structured field, not prose. Then:

• Check A (existing, code -> doc): every declared *_ANONYMOUS_ID has a roster entry. Unchanged.
• Check B (new, doc -> reality): for every table an entry declares, that (identity, table) pair has rows in production. Zero is a failure, not a quiet outcome.

The (identity, table) distinction then lives in the roster, next to everything else about that calculator, rather than in a separate list that can disagree with it.

Why the pair, not the identity alone

This is the distinction the purge incident turned on. local-fallback-v1 writes CardTagVote and (formerly) CardPrintingTag. Asserting on the identity alone would have seen "this identity has rows somewhere" and passed, while the chips were gone. Under the pair:

• stage-d-slow-path-v1 declares CardScanLog only -> its 0 votes and 135,362 routing markers are correct by declaration, and no allowlist entry is needed to explain it.
• local-fallback-v1 declares CardTagVote -> 0 rows would have failed the build.

Note the direction is new

The two existing tethers are code -> doc: derive a roster from source, check the doc mentions it. This adds a doc -> reality direction: the doc states a contract, and production is checked against it. Which tables a calculator writes cannot be reliably derived statically (writes go through shared helpers like purge_and_write_votes), so the declaration is human-authored — but it stops being unfalsifiable prose the moment something checks it.

Design constraints

• Legitimately-zero cases need an explicit, per-entry-justified allowlist, exactly like CALCULATOR_ROSTER_ALLOWLIST — a retired calculator, or one not yet run. "Expected zero" must be a visible decision, never a silent gap. Note local-ocr-v1 is retiring and local-name-frequency-v1 may be, so both will need one.
• Assert a floor, not a count. "Produced something" is durable; a hardcoded N rots — see docs/features/catalog-stats.md and catalog_stats.py, which both claimed "~11 distinct reasons" against ~30 in code until PR Adopt a *_SKIP_REASON declaration convention; tether the roster to a doc #567 removed the number entirely.
• Where does it run? Check A is a lint and runs in CI. Check B needs a database, so it is a post-run report or an ops command, not a CI job. A 7-hour pass should probably report loudly rather than exit non-zero at the end; a pass finding a channel silent in its first batch could fail fast. Decide deliberately.

Immediate concrete use

After the first monolith run, the three destroyed chip channels — cast_border_attribute_vote, cast_frame_style_vote, cast_bleed_edge_vote in local_fallback.py — must be non-zero again. If they are not, the re-derivation did not happen and a recoverable loss became permanent. Right now nothing would tell us.

Related

• PR docs-lint: tether the calculator roster to code; document the general rule #562 — the roster tether this extends
• PR Adopt a *_SKIP_REASON declaration convention; tether the roster to a doc #567 — the skip-reason roster; same derive-never-restate discipline
• OPS-CORR-0008 (orchestration repo) — the purge that made this urgent
• Issue Retention janitor: sweep the oldest runs of CardScanLog abstention history #575 — CardScanLog retention janitor

[WilfordGrimley]

A read-only audit for self-referential reasoning (2026-07-29, code at origin/master 6bc3e16, production 85d88bfe) independently re-derived this issue's core finding and turned up four extensions to it. Filing them here rather than as a duplicate issue, since the fix proposed above — make the roster entry a machine-readable contract and add a doc-to-reality direction — is the right shape for all of them.

Confirming the headline first: the calculator tether is green for local-name-frequency-v1, which has cast zero votes ever, has zero CardScanLog rows, and has never appeared in PilotRunLedger. Exactly as described above.

1. The skip-reason tether has the same shape as the calculator tether

check_skip_reason_roster_tether() in .github/scripts/docs_lint.py is the same re.search(identity, prose) construction as check_calculator_roster_tether(). It verifies a string appears in a document, never that the document's claim about that string is true.

Whatever contract mechanism this issue lands for calculators should cover skip reasons too, or the roster this repo just invested PR #567 in making enumerable inherits the same unfalsifiable-prose problem.

2. The skip-reason roster's completeness claim is false — three literals bypass the derivation

_declared_skip_reasons() scans for the *_SKIP_REASON constant convention. Three bare inline string literals never became constants and are therefore invisible to it, all in MPCAutofill/cardpicker/local_fallback.py:

• "no-evidence"
• "eliminated"
• "ambiguous"

These are written to CardScanLog.skip_reason at runtime and are absent from the derived set, so the tether cannot flag them and docs/reference/skip-reasons.md is not required to mention them. This is the "derive, never restate" discipline being defeated by a code path that opted out of the convention the derivation depends on.

Worth noting because PRs #574 and #584 are already declaring local_phash's and local_fallback's skip reasons at source as authorised protected-core exceptions — these three look like the same job, not yet done.

3. Two soft checks are mention-only in the same way

check_supersession() and check_proposal_crossrefs() both succeed on substring presence. check_proposal_crossrefs() additionally does not strip fenced code blocks, so a filename appearing inside a code fence satisfies a cross-reference requirement. If the contract idea generalises, these are the same class.

4. The tether's own tests cannot fail

MPCAutofill/cardpicker/tests/test_skip_reason_roster.py parametrises over the hand-written EXPECTED_SKIP_REASONS dict declared 40 lines above it — not over _declared() — and asserts those literals are non-empty and stripped. No implementation change can redden it. A second case is strictly subsumed by a third (dict equality implies key-set equality) yet counts as separate coverage.

So the roster has three layers, and the accuracy of the claim is unchecked at every one: the tether checks a string appears, the tether's tests check a literal against itself, and the derivation the tether depends on misses three live values.

Cross-reference

Full write-up of this finding (as C9) and of the general shape — "a doc tether that checks a string APPEARS rather than that the claim is TRUE" — is in docs/reference/self-referential-reasoning.md, published in the PR that accompanies this comment. It records this issue as the owner of the fix rather than proposing a competing one.

Related in flight: PR #588 (roster tethers scanning recursively) fixes a different hole in the same two functions — the non-recursive src_dir.glob("*.py") that never sees management/commands/. Worth landing the contract on top of that rather than beside it.