[derek73]

Sub-phase 3a of #753's work order: the reading index, the shared compiler, and default = false on name readings. Neutral: _compiled.py is byte-identical and tests/v2/test_snapshot.py passes unchanged.

What lands

• The reading index, nameparser/config/_index.py (generated by tools/vocab/build.py).
  • One line per word, holding a row per reading in every file, on by default or not: (tag, kind, properties).
  • Only the properties the compiler reads are kept: each category's behavioral ones, plus same_as on a given reading. Counts, notes, exclusions and the stated may_be_given stay out.
  • 2,157 readings over 1,798 words; about 95 KB of source.
• The compiler moves into the package, as nameparser/_reading_index.py.
  • It holds compile_readings, plus CATEGORY, BEHAVIORAL and GATED_WORDS, and the accessors for unwritten values, shared with the build's Reading.
  • The build loads it by path, as it loads _lexicon.py, so the build still never imports the package. The build keeps every check. It turns the readings into index rows in memory and writes both generated modules from those rows; it never reads _index.py back.
  • Only the compiler's own CompileError (the acronym-or-word backstop) becomes a vocabulary error (exit 2). Any other exception from it is internal (exit 3).
• The no-choice invariant: tests/v2/test_reading_index.py holds that compile_readings(index()), rendered as the build renders it, is _compiled.py byte for byte. It also checks that the index is not stale against the TOML.
• An anchor outside the index's own path: compiling the build's readings as written must equal compiling them after the index round trip (indexed(), to_row, from_row). This is checked over the shipped pool and over a probe that carries every behavioral property plus a given reading's same_as. Dropping any one of the nine properties from indexed() fails the test.
• The run-time reader, for Reading.languages (added unfilled by 4a, Add Token.reading, the reading the parse took for each word (3.0, 4a) #942, and filled by a follow-up once both merge): readings_of(text) -> tuple[IndexReading, ...].
  • IndexReading(text, tag, kind, props) is frozen and slotted.
  • kind is the vocabulary's kind (credential, preposition), which is finer than ReadingKind. The mapping between them is that follow-up's.
  • The index loads on the first call.
• default = false on given and family readings.
  • Such a reading derives no marker in the default, and counts for none of the checks that guard the default's compile.
  • An agnomen on by default needs a name reading on by default (check 11).
  • A particle whose word's only given readings are off is refused, and that question is left open (below).

Measured

All figures with bytecode cached, as a wheel install has it; Python 3.11.17, medians of fresh processes.

What	Cost
Importing the index	0.56–0.68 ms, about 3% of import nameparser (18–24 ms)
First readings_of call	0.07 ms
Each later lookup	about 2 µs
Compiling the whole index	2.1 ms

The import is a little above the 0.45 ms the RFC measured on a flat draft. Writing the index grouped by word is what keeps the first lookup to a single dict() call: grouping at run time cost about as much as the import itself.

For review: decided here, not settled elsewhere

Each is recorded in decisions/vocabulary-model's 2026-10-29 entry.

1. Decided 2026-10-29: the index loads on the first readings_of call, not inside Lexicon.default(). This replaces the 2026-10-28 wording. The RFC's runtime section and the decisions entry describe the lazy load.
   • Today no parse reads the index, so no caller pays the import.
   • Once the follow-up fills Reading.languages, the first parse will load it. Every parsing caller will then pay once, and only import-only callers are spared.
2. A particle whose word's only given readings are off is refused.
   • The default compiles such a particle never-given; a pack turning the given reading on compiles it possibly given.
   • Which of the two check 11's stated may_be_given describes is left to the first pack that needs it. None in 3.0 does: nl's prepositions wait with strict.
3. Not touched:
   • Pickle layouts: no field is added to Lexicon or any other pickled type, so the open question of ADDED_IN on Lexicon's guard does not arise.
   • Public names: 3a forces none, so the configure-by-reading method names stay open.

Docs

• The RFC's status line.
• A decisions entry and a Standing line.
• AGENTS.md's vocabulary, layering and sub-set notes.
• The vocab README: the default row, name readings, derived markers and where CATEGORY lives.
• mechanisms.md's COMPILED-DATA-COMMITTED entry.

The design-docs review and a code review both ran; their findings are fixed in the last commit.

Tracing the moved compiler

Plain git blame gives all of nameparser/_reading_index.py to this PR. With copy detection, most of it traces back to #737, #744, #890 and #894, where the code was written in tools/vocab/build.py:

git blame -C -C nameparser/_reading_index.py

Checks

All pass:

uv run pytest
uv run pytest -n0 -m serial
uv run mypy
uv run ruff check
uv run python tools/vocab/build.py --check
uv run --python 3.15 pytest -q

Refs #753.

🤖 Generated with Claude Code