Ledger rule order: declare the contest, don't assume narrow-first

[derek73]

Closes #382.

What changes

An order-decided contest between two ledger rules must now be declared. Where
the later rule's fields are a strict subset of the earlier one's, both
name_regexes reach a common corpus name, and their orders are not disjoint,
every diff fitting the narrower set is admitted by both — so classify()
returning the first match means file position alone picks the winner.

Narrow-first is the declaration-free default. A wide-first pair stays legal and
carries a [[change.precedes_narrower]] block naming the later rule and saying
what the earlier one describes that it does not.

Three checks at three homes:

• Shape, in validate_rules (corpus-free, startup): well-formed list of
  tables; issue names a rule present in the ledger and strictly LATER in the
  file; non-blank why; no duplicate targets; no self-reference; and no key but
  issue/why inside an entry.
• Contest, in main() after the corpus loads and before the worker pass,
  so a refusal costs seconds rather than the multi-minute pinned-wheel run.
• Contest again, in tests/v2/test_ledger_guards.py at pytest speed. This
  is the one that matters for Should file order be allowed to separate ledger rules within a tier? (김, 민준씨 is claimed by whichever of two rules comes first) #382's stated purpose — three later v2.3 bundles add
  ledger rules, and gating only on a full differential run would be far too weak.

What the check does not cover, stated plainly. Nesting is sufficient for an
order-decided contest, not necessary: two rules whose fields merely intersect
both admit any diff inside the intersection, so position decides between them too.
Measured, 60 such non-nested overlapping pairs share a corpus name. They are
outside the check by the same reasoning the documents already give for EQUAL
fields — neither rule is narrower, so "narrow-first" has no referent and
_CROSS_RULE_WINNERS stays the instrument — rather than by oversight. Widening to
the general predicate would demand 111 declarations where the real one is eleven,
which is the roster-nobody-reads argument this ledger already makes about the 657
figure. Filed as #498 with a worked contract-tier case.

The premise #382 filed on is false

Its option 3 proposed a mechanical narrow-first check. 马丁·路德·金씨 falsifies
it: fix(#272/#308) (nakaguro division and glued hangul honorific) and
fix(cjk-glued-honorific-peel) (the peel alone) both admit it, and the wider rule
wins by position — correctly, because it describes what happens to the name.
Narrow-first would reattribute it to a rule describing half of that, which is
#372's defect reintroduced by a check. The name is contract tier
(corpus_rules.jsonl) and absent from _CROSS_RULE_WINNERS, so it is precisely
the crux the issue was filed over.

So fields-subset is a proxy for specificity and the wrong one where a wider rule
describes a compound. The escape hatch is argued rather than deferred, which is
what #452's entry asked of the first rule that genuinely needed one: there, 0 of
179 rules had the banned shape and all fourteen over-declarations were narrowed
before the check landed. Here eleven pairs are correct as written.

Measurement (2026-09-02)

11 wide-first contested pairs in expected_since_1.4.0.toml; 0 in each 2.x
ledger. Six are contested over contract-tier names, five only over radar (#488's
demotion; see #495).

Without the corpus-reach condition the same scan reports 657 wide-first pairs
— of 1350 nested either way under fields-subset alone, 1348 with the orders
test kept. An exemption roster in the hundreds is one nobody writes and nobody
reads, so fields-subset alone is not a usable predicate.

Nine of the eleven pairs are latent, not live. Measured against the 1.4.0
wheel, the real diff needs a field the narrower rule does not declare, so that
rule is ineligible wherever it sits. Only two are decided by position today. That
is the honest cost of a static predicate — it over-reports relative to measured
diffs, and the price is a why someone had to write — and it is also why the
exemptions are worth having: most document a hazard that would activate if a
rule's fields widened.

The two checks are not symmetric under --corpus. A smaller name set removes
contests, which makes the undeclared check strictly more lenient and makes the
vacancy check false-alarm. So vacancy refuses only on a full run and NOTEs under
--corpus, joining the corpus-floor skip and over_declared_rules as a third
check reading the flag at a third strength.

Corrections this arc surfaced

• _CROSS_RULE_WINNERS recorded 田中さん II as diffing ("given","suffix");
  measured, it is {family, given, suffix}. Four sites carried the wrong shape.
  The winner is unchanged under both. test_the_recorded_rule_still_wins_each_contested_name
  structurally cannot catch this — it feeds classify() the recorded shape — which
  is filed as Measured claims in the differential comments go stale unnoticed (a reviewer read "751 names" as fact; the corpus holds 1116) #497.
• fix(comma-precomma-family) opened its comment naming two names it no longer
  explains; repointed, with the measured inventory of the seven it does.
• The expected_since_1.4.0.toml and expected_since_2.1.0.toml headers still
  stated "write the narrower rule first" as law, in the file holding all eleven
  declared pairs. A contributor reading only that would reorder — the one repair
  the gate and the guard forbid.

Verification

Rule ORDER is identical in all four ledgers and no rule's name_regex, fields
or orders changed (TOML-parsed against c1a98a9, not grepped). No name changed
hands: _CROSS_RULE_WINNERS differs only in the corrected shape above, and the
_ORDER_EXEMPTION_EFFECT negative control — which ignores exemptions by design —
records the same 11 contests before and after.

Every exemption is load-bearing: dropping any one reports exactly its own pair as
undeclared, 11 for 11.

Gate at every baseline, all exit 0:

baseline	names	intentional	unexplained	radar unclassified
1.4.0	1113	352	0	0
2.0.0	1120	247	0	0
2.1.0	1120	155	0	0
2.2.0	1120	14	0	0

Full suite 6462 passed, 156 skipped, 5 xfailed; ruff clean; mypy clean on 111
source files.

design-docs-reviewer ran the eleven axes over the docs commits and returned three
confirmed findings, all fixed in 7fcd531: a false "never less" claim about the
predicate's error direction (finding above, now #498), an over-generalization that
the narrower rule's prose would be FALSE of the co-matched names when most
exemptions say merely partial, and a mechanisms.md sentence closing #382's open
question — which asked about its option 1, a regex predicate — with an answer about
option 3. Option 1 now has a Declined: bullet carrying the evidence that killed
it: narrowing the earlier rule's own regex cannot shrink the later rule's reach, so
its stated effect is unreachable, measured by implementing it.

Follow-ups filed

• Do the CJK comma ledger rules still earn their place now that nothing demands them? (fix(cjk-comma-compound) reaches 23 radar names and 0 contract) #495 — do the CJK comma ledger rules still earn their place after CJK names join the shape inventory pure, and the comma zoo goes tolerated #488's
  demotion? Three of the five radar-only pairs involve rules with zero
  contract-tier regex reach.
• Measured claims in the differential comments go stale unnoticed (a reviewer read "751 names" as fact; the corpus holds 1116) #497 — measured claims in the differential's comments go stale unnoticed,
  and no guard checks a recorded diff shape against a real run.
• Should file order decide between rules whose fields overlap without nesting? (マイケル・ジャクソン goes to whichever of two rules comes first, and the contest check never sees the pair) #498 — should file order decide between rules whose fields overlap without
  nesting? マイケル・ジャクソン, 威廉・莎士比亚 and 高橋・一郎 are contract-tier
  and a pure reorder of two rules reattributes all three, with nothing in the suite
  failing.

Also closed #496 (not planned) — a family-side twin for the pre-comma glued
honorific was weighed and declined: all three affected names are radar tier since
#488, so no gate can demand the rule, and #495 asks whether the radar-only rules
already here still earn their place. The finding survives the decline: pair 9's
exemption still says the holding rule's label is wider than those names are.

Also closed: #470 (not planned) — the Accepted: clause already carries what
it asked for, and its own example had been removed by #467.

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.66%. Comparing base (c1a98a9) to head (b821043).

Additional details and impacted files

@@           Coverage Diff           @@
##           master     #499   +/-   ##
=======================================
  Coverage   98.66%   98.66%           
=======================================
  Files          45       45           
  Lines        3219     3219           
=======================================
  Hits         3176     3176           
  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.