[derek73]

Phase 1 of the per-word vocabulary redesign: the word lists in nameparser/config/*.py are now written per word in nameparser/vocab/*.toml and compiled into a committed module. No parse, render or public name moves.

What changed

• nameparser/vocab/<tag>.toml: one file per BCP 47 tag (und = no language assigned yet, mul = shared on purpose). Each [[word]] has a text and readings keyed by kind, each a table. Every category is converted mechanically into und.toml with generic kinds (title, particle, conjunction) or their one kind (bound_given, birth_marker) and today's flags. The suffix category is fully classified: kinds generation, credential, honorific, professional_honorific, status and courtesy; languages taken from the # xx comments; excluded refusals with reasons. The files ship as package data.
• tools/vocab/build.py compiles the TOML into nameparser/config/_compiled.py (one sorted entry per line) and runs the build checks that replace the import-time asserts. Its docstring numbers the checks. tools/vocab/query.py answers --issue, --kind, --excluded and --word.
• config/*.py keep their public constants as NAME = _compiled.NAME with their autodoc docstrings and the deprecated-alias bridge. The vetting comments moved with their words. In the suffix pilot they became fields (note, issue, same_as, expands, excluded). In the mechanically converted categories they are TOML comments above the same entries, in source order, and inline comments became reading notes.
• tests/v2/test_vocab.py: the committed module must byte-equal a fresh compile, and the failure names the refresh command. The shipped files must pass every check with warnings as errors. Every build check has a mutation it must refuse, beside a control showing the unmutated shapes compile.
• Docs: new decisions/vocabulary-model (Decisions 1–20 plus phase 1); the README's sanctioned exception (a moved per-word fact becomes a query pointer); the narrowed Excluded: convention; query pointers in generational-words, vocabulary-exclusions and salutation-titles; a W2 entry for the class-level half of the Spaced CJK honorifics parse as name parts (王小明 先生 → given 先生) #307/Glued CJK honorifics are absorbed into the name (山田太郎様 → family 山田太郎様) #308 note; mechanisms COMPILED-DATA-COMMITTED; the AGENTS.md config-layer section, extension patterns and the disjointness gotcha rewritten; a CONTRIBUTING section; a release-log bullet.

Two things found while converting (please look)

1. may_be_given is required on every particle. The old encoding stored the NEVER-GIVEN particles, so a new particle was ambiguous unless argued otherwise (Rename the vocabulary data modules to the 2.0 terminology (prefixes.py → particles.py), with a 2.x deprecation bridge #293's safe-by-default, C-i's "under uncertainty, ambiguous"). A defaulted flag would pick one side silently, and particle = {} reading as never-given is the unsafe side. So the build refuses a particle reading without the flag. The spec did not cover this.
2. PARTICLES was missing from the rendered API reference on master. A plain comment between its #: lines and the assignment split the run. That comment moved into und.toml, so the docstring now renders, with its stale "static union" sentence corrected.

Beyond the spec's 22 exclusions: the rest of the #679 named refusals (hy ավագ, km ជូនៀ, fa پدر/پسر, …) also moved to data, so the decisions sentence could become one query. The Latin ml/st refusals are recorded in all four languages the decision names (cs, sk, sl, hr). The 41 #606 titles carry issue = 606, which turns salutation-titles' recompute recipe into a query.

Gate (measured 2026-10-18, Python 3.11.17)

• Lexicon.default() and all 13 raw constants equal the pre-change tree's (pickled from master at 6803a26).
• uv run python tools/differential/snapshot.py: matches the snapshot.
• Negative controls:
  • dropping may_be_name from ma: 120 snapshot entries move and Lexicon.default() becomes unequal;
  • a TOML edit without a rebuild: the staleness test fails with the refresh command.
• import nameparser: 48.5–48.8 ms median vs master's 49.4 ms (25 fresh processes each).
• Full suite: 21,567 passed. ruff check and mypy are clean, and mypy --strict tools/vocab/ is clean.
• The wheel carries all the TOML files and _compiled.py.
• Reviews, each fixed in its own commit:
  • docs-review (design-docs-reviewer): three stale pointers, one query mismatch and one missing dated note. It also confirmed every number.
  • The PR review toolkit (code, tests, comments, silent failures, types):
    • The build now refuses an acronym written with a period, which the parser could never match.
    • An excluded kind now refuses every kind that compiles to the same set, so suffix = {} can no longer put back a refused generation reading.
    • The build loads _lexicon.py by path, so a broken _compiled.py cannot stop it from regenerating.
    • A refused property is refused any value other than its default, and broken or unreadable data exits 2 (an internal error exits 3).
    • A third round closed the build tool's edges. An empty or misnamed vocab folder is now refused, no error path exits 1, cased and property exclusions hold across the word or category, and a refusal names the refused value. The 13 new or changed tests all fail against the second fix commit: 11 on behavior, 2 on the message wording.
    • A targeted review of that round found the cross-kind property check comparing against the wrong baseline, so a credential's acronym exclusion misreported. It is fixed, and its four new tests fail against the earlier commit.
    • The fix commit itself was reviewed too. Its two regressions in the exclusion check are fixed: the excluded kind with acronym flipped got through, and the name kinds refused each other. Four of its five new test rows fail against the earlier commit; the fifth pins behavior that was already right.
    • query.py validates its arguments, normalizes --word, and lets --kind narrow --excluded.
    • New mutation rows and query tests cover each change, and stale comments are fixed.
    • The other type-design refactors are left for a follow-up.

Out of scope, and rejected by the compiler with a message naming the phase: derived ambiguity, pack semantics, addresses = full|any, other attached sides.

🤖 Generated with Claude Code

[codecov]

Codecov Report

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

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #737      +/-   ##
==========================================
- Coverage   99.05%   99.05%   -0.01%     
==========================================
  Files          46       47       +1     
  Lines        4647     4642       -5     
==========================================
- Hits         4603     4598       -5     
  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.