Fail the gate when a ledger rule declares a role it never explains

[derek73]

Closes the explained-reach half of #452. The reach ceiling stays open on that issue.

classify() returns the first rule whose declared fields are a SUPERSET of the observed diff. So a rule keeps matching when the diff beneath it shrinks — and shrinking is the common direction, since most parser fixes move fewer roles rather than more. decisions.md#H1 records the case that already happened: #410 narrowed Freiherr von Richthofen V from {given, family, suffix} to {family, suffix} while the fix(#424) rule declaring all three kept claiming it — "a shrinking diff kept matching and no run ever named it. A real movement behind a green gate." That rule was narrowed by hand. Nothing would have said so.

This adds the check that does.

The check

compare.py now asserts, at the end of every run, that each rule's declared fields equal the union of the diffs it explained, and fails the run like an unexplained diff.

The statement is exact rather than heuristic, and that is what makes it cheap. classify() already requires declared ⊇ union for a rule to match the names it matches — declaring less would stop it matching one it explains. So the only possible error is the other direction, and declared == union is the whole check. The union is simultaneously the check and the repair, and narrowing to it cannot orphan a name, because every name a rule explains contributed to it.

No recorded number, so no corpus harvest can make it stale.

The migration

Measured before landing, then re-measured after:

ledger	rules explaining ≥1	over-declared before	after
1.4.0	67	3	0
2.0.0	58	5	0
2.1.0	51	6	0

All fourteen were narrowed before the check landed, so it is silent the day it arrives and every commit leaves the gate green.

Over-declaration is baseline-relative, which is why each ledger was measured on its own run rather than copied. fix(#296) a lone post-comma credential is a suffix declares {family, given, suffix, title}: exactly exercised at 1.4.0, where v1 reads the pre-comma word as first and all four roles move, and over-declared at both 2.x baselines, where the same behaviour moves only {suffix, title}. A reader diffing the three files sees one rule with two different field lists and should read that as correct.

No escape hatch

Decided, not deferred. dormant already covers explains-nothing in both directions; a rule with no fields has nothing to over-declare; and the ledger's own doctrine — "a rule that pre-claims shapes it has never seen is the #372 failure mode" — makes strictness the existing principle. Accepted cost, written down so it is not rediscovered as a surprise: the first rule that genuinely needs a wider declaration has to argue for a key the way dormant was argued for in #373.

Proved able to fail

Two ways, neither touching a tracked file:

• the pure function on a widened rule — restoring middle to one fix(#367) rule reports it;
• main() end to end — with tomllib.loads and _run_worker monkeypatched in memory over a one-name corpus, the gate prints OVER-DECLARED and returns 1.

A guard that cannot fail is worthless, and this branch found one of those inside its own new tests — see below.

Two commits that came out of review, not the plan

626e2a8 — test_over_declared_rules_skips_a_dormant_rule could not fail. It passed roles_by_issue={}, which the if not moved guard catches whether or not the dormant clause exists; mutation-tested, the test was green with that clause deleted. A test that cannot fail, inside the check built to catch rules that cannot be seen to drift. It now uses the only separating input — a dormant rule that did explain a diff, which is also the only interesting one, being exactly the NO LONGER DORMANT state.

Same commit: _CORPUS_CLAIMS' own docstring said "Twenty of these moved at once when corpus_rules.jsonl landed (#414)". Parsing the roster out of 7a10689^ and 7a10689 with ast and diffing per entry: 30 before, 44 after, 17 changed and 14 added — the same three ways (that commit, all of PR #415, the backtick-harvest commit after it). The comment carries 17 and the recipe now.

13e432a — the design-docs review found three claims in the already-merged #451 bullets that are false. All three were mine:

• the section's reusable-lesson bullet named the wrong cause: the 2.x "should arrive UNEXPLAINED" idiom holds because no rule above claims that diff shape, not because those ledgers have no fields-only rule. Measured — a maiden diff on fix(#367)'s own probe goes to fix(#274) in the 1.4.0 ledger, which has no fields-only rule at all. That is the bullet a future arc copies, so the wrong cause would have propagated.
• the emoji bullet asserted equality where the guard checks a subset, and said two blocks where _EMOJI_RANGES has four. Read as equality it instructs the next author to pre-claim the BMP half — the Ledger rules classify diffs they do not describe, and a rule that stops explaining anything is invisible #372 shape the same section leans on.
• "FORCED rather than chosen … none of them taste" overstated by one: _LatinCopy.vocabulary is a hand-supplied frozenset, so a SUFFIX_WORDS | SUFFIX_ACRONYMS declaration would let (jr\.?|v|mp|mc) pass. Two of the three splits are forced; the third is a judgement, recorded as one now.

Not in scope

• The reach ceiling, A ledger rule's explained set is printed but never checked, so a diff can shrink underneath it and every run stays green #452's other half — bounds what a rule reaches rather than what it explains, and stays on the issue with its measurements (today's maximum is 25.6%).
• explains = N per rule, this issue's own first sketch — declined on maintenance cost, not merit: 179 numbers across three ledgers, every one liable to move when a corpus does. Recorded as the design to revisit if a name-count shrink ever bites.
• _CROSS_RULE_WINNERS has no expected_since_2.0.0.toml section at all, so no 2.0.0 contest is pinned. Pre-existing and wider than this issue.

Verification

Gates unmoved throughout: 1.4.0 229/0, 2.0.0 194/0, 2.1.0 102/0, no OVER-DECLARED and no EXPLAINED NOTHING. tests/v2/ 5347 passed, 156 skipped, 1 xfailed.

Not the verification: a green gate. It was green through every instance this issue is about.

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.64%. Comparing base (a5de5d2) to head (ee6aaa6).

Additional details and impacted files

@@           Coverage Diff           @@
##           master     #455   +/-   ##
=======================================
  Coverage   98.64%   98.64%           
=======================================
  Files          45       45           
  Lines        3177     3177           
=======================================
  Hits         3134     3134           
  Misses         43       43           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.