Replace the differential ledgers with a committed snapshot (#664)

[derek73]

Closes #664.

The differential ledgers were built to show that 2.0 changed nothing against 1.4 except listed fixes. They did that job. As a standing check, every parser change had to be classified once per ledger, and the guards policing the ledgers grew longer than the ledgers. This PR replaces them with a committed snapshot of how the tree reads every corpus name.

What changes

The snapshot. tools/differential/snapshot.py writes snapshot.jsonl: one line per (name, order) across every corpus*.jsonl. Each line holds the seven role fields, ambiguity kinds and initials(), plus the facade's reading where it differs (3 names today). tests/v2/test_snapshot.py fails on drift and prints the moved names grouped by changed field. A change that moves readings re-records the file, and its diff in the PR is the list of names it moved.

• --since <ref> compares against the snapshot at a tag, for release notes.
• --tree PATH reads with another checkout.

compare.py stays, unclassified. It is down from 3,732 lines to about 400.

• Kept: the PyPI-wheel runner and its checks against comparing the tree with itself (version tell, source-package check, stripped PYTHONPATH).
• Changed: it prints the same grouped report as the snapshot, plus the population: entries compared, order-bearing entries skipped below 2.0.0, how many moved names are Latin-only, and how many only corpus_cldr.jsonl holds. It always exits 0, and --corpus PATH still compares a file of your own names.

Deleted:

• the six expected_since_*.toml ledgers
• tests/v2/test_ledger_guards.py
• the contract/radar tiers and the roster tables

With the tiers gone, two simplifications followed. Neither changes the snapshot:

• corpus_cjk_tolerated.jsonl folds back into corpus_cjk.jsonl (same 153 names).
• build_rules_corpus.py stops skipping tolerated rules' examples (8 W3 texts, which the CJK corpus already held).

Kept, unchanged: the CLDR agreement ratchet.

Tests that guarded surviving code moved:

• The corpus-generation pins and the four issue-harvester tests are now in tests/v2/test_corpora.py.
• The phrase-entry storage test is now in test_lexicon.py.

Docs:

• tools/differential/README.md drops from 995 lines to about 400.
• AGENTS.md: the Release-log claims paragraph and release checklist steps 1 and 8 now use snapshot.py --since (or compare.py for a tag older than the snapshot).
• decisions.md: a new dated entry records the retirement, the measurements, the accepted costs and what was declined.
• mechanisms.md: three ledger-only entries are marked retired. Their headings stay because decisions.md cites them.
• rules.md: the tolerated-marker paragraph and the S2, S3, C1, C2 and W3 passages no longer argue from an enforced corpus.

Measurements

These replace the figures in the issue description, which were partly wrong; the correction is posted on #664.

• Overall upkeep: over the 40 first-parent commits ending at 04cc081, 5,236 of 25,226 changed lines (21%) were harness edits, and 21 of the 40 commits touched them.
• Per-PR spread: across the 29 of those commits that touch nameparser/, the share runs from 0% to 82%, median 11%, above 30% on 11.
• Keep a comma inside a delimited nickname or maiden clause (#653) #655: the snapshot reports five moved names, where Keep a comma inside a delimited nickname or maiden clause (#653) #655 spent 236 lines on ledger and guard edits.
• Read a decomposed (NFD) accented abbreviation as the same word (#652) #663: after merging master, the snapshot reported Read a decomposed (NFD) accented abbreviation as the same word (#652) #663's one new corpus name. Read a decomposed (NFD) accented abbreviation as the same word (#652) #663 had added ten lines to each of six ledgers.

Accepted costs

• No forced explanation per moved name. A large snapshot diff can be approved unread; the grouping by changed field is the mitigation.
• The 1.4 compatibility promise becomes a question you ask when needed (compare.py --baseline 1.4.0, 808 of 2,635 compared entries move today), not a gate at every release.

Review

• Code review (first round): found that snapshot.py didn't check which nameparser it imported, that --tree used a weak path check, that compare.py skipped entries without saying how many, and that four harvester tests had been deleted. All fixed.
• Docs/design review: found wrong figures, a deleted exemplar still cited, and stale tier arguments in rules.md. All fixed.
• Second-round review of the fix commits: found two counts that no test asserted and a misleading error message. All fixed.
• Mutation checks: each new guard was mutated out and fails its test.

Test plan

• uv run pytest passes: 16,624 passed, 110 skipped, 3 xfailed
• uv run ruff check and uv run mypy are clean
• sphinx-build -b html and -b doctest are clean
• compare.py runs against the real 1.4.0, 2.0.0 and 2.4.0 wheels
• snapshot.py --tree against Keep a comma inside a delimited nickname or maiden clause (#653) #655's parent and Keep a comma inside a delimited nickname or maiden clause (#653) #655 reports the five moved names

Follow-up: cut 2.4.1 after this merges, so a release tag carries the first snapshot.

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.02%. Comparing base (1f0b374) to head (767b49a).

Additional details and impacted files

@@           Coverage Diff           @@
##           master     #666   +/-   ##
=======================================
  Coverage   99.02%   99.02%           
=======================================
  Files          46       46           
  Lines        4534     4534           
=======================================
  Hits         4490     4490           
  Misses         44       44           

☔ 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.