[derek73]

Follow-up to #737: the type-design refactors and low-severity silent-failure findings its review deferred, plus what this PR's own two review rounds found. Scope: tools/vocab/build.py, tools/vocab/query.py, tests/v2/test_vocab.py, and one AGENTS.md line.

No compiled set moves. nameparser/config/_compiled.py is byte-identical to master, build.py --check reports current, and snapshot.py reports "matches the snapshot". No shipped TOML entry hits any new check; I measured that over every file before writing the checks.

Type design

• query.Row stores the exclusion's structure (excluded, prop) and asserts that a reading refuses no property. label is display-only, and select() no longer parses it back.
• Compiled TypedDict. compile_pool/compile_files return one instead of dict[str, Any]. One assert at load ties it to the CONSTANTS roster, and the old runtime roster check and MAPPINGS are gone.
• One definition per default. Reading.acronym, Reading.addresses and Reading.flag() (the may_be_* flags) are the only places the defaults are written. _behavior, compile_pool, _refused_by and the checks all read them.
• Exclusion. reason is a property over props, and __post_init__ refuses a missing or empty reason, so the invariant is enforced rather than documented. Reading and Exclusion are frozen.

New refusals

Each has a MUTATIONS row.

Build check 2:

• A comma or nakaguro. The tokenizer divides the main stream at both. Inside a clause a comma is kept, but rules/M3 (a marker followed by a comma is no marker) relies on the vocabulary holding none.
• An emoji. The tokenizer strips it by default.
• An interpunct between two East Asian characters. The tokenizer divides the name there (rules/T3).
• An invisible character other than ZWNJ/ZWJ: a format or control character. ZWNJ/ZWJ are allowed because they are spelling in Persian and the Indic scripts.
• A phrase word with an edge period. z. domu would actually match, since Lexicon folds each word, so this is a one-spelling-per-key rule, not a never-match one.

Other new refusals:

• cased on a phrase. Capitalization is looked up one word at a time, so a phrase's cased is never read.
• A file with no [[word]] entries.
• A same_as naming its own word.
• A date-time where decided or as_of expects a date. tomllib's datetime passes isinstance(..., date).
• An as_of with no count.

Guards and controls:

• The hand copies (DIVIDERS, EMOJI_RANGES, EAST_ASIAN_RANGES, INTERPUNCT) are pinned to their pipeline sources.
• test_every_character_the_tokenizer_ignores_is_refused sweeps every codepoint that _tokenize._ignorable drops under the default Policy, plus the commas. It requires each one to be refused by check 2 itself.
• Negative controls: with any new check stubbed out in memory, its rows' inputs compiled. Hiding the emoji check behind its pinned constant fails the sweep.

Already in place, unchanged: a .toml in a subfolder is refused by read_dir ("no subfolders"), pinned by test_the_folder_is_read_whole.

Review

Five agents reviewed (code, silent failures, types, tests, comments), and a further pass reviewed the fix commit alone. Fixed from those rounds:

• the emoji, CJK interpunct and control-character gaps;
• a vacuous divider test, twice: first it pinned only two constants, then the sweep accepted any refusal;
• a wrong never-match claim about phrase words, plus overclaims in the comments about commas and bidi marks;
• the Exclusion and Row invariants;
• a test for a table-form exclusion reason.

Not changed: the reviewer noted that a decomposed (NFD) hangul input is not divided at an interpunct, because the flank guard reads raw text. An entry refused by the interpunct rule could match such input. This is a nit, recorded here.

Checks

• uv run python tools/vocab/build.py --check: current
• uv run python tools/differential/snapshot.py: matches the snapshot
• uv run pytest: 21708 passed, 123 skipped, 3 xfailed
• uv run ruff check, uv run mypy, uv run mypy --strict tools/vocab/: clean

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.05%. Comparing base (ef03011) to head (82efc03).

Additional details and impacted files

@@           Coverage Diff           @@
##           master     #744   +/-   ##
=======================================
  Coverage   99.05%   99.05%           
=======================================
  Files          47       47           
  Lines        4642     4642           
=======================================
  Hits         4598     4598           
  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.