[derek73]

Docs-only. This PR records the decided API for 3.0's Lexicon surface, the part the 2026-10-28 decision ("a caller configures vocabulary by reading, and the compiled sets become internal") left open. Decided on 2026-11-02 as recommended; the title warning was decided on 2026-11-01. Nothing is built.

• docs/design/vocabulary-model-rfc.md:
  • a new Phase 4 section, "The Lexicon surface: configuring by reading", with seven items and the options weighed for each;
  • the 4i work-order row;
  • pointers to it from phase 3's provenance and API sections.
• docs/design/decisions/vocabulary-model.md:
  • the 2026-11-01 proposal entry, with its measurements and recipes and the revisions each review round made;
  • the 2026-11-01 title-warning entry;
  • the 2026-11-02 decision entry, with its Declined line;
  • the chained-choices entry marked superseded, and 3j's dropped-listing clause too, both effective with 4i-c;
  • Standing and Open lines updated.

Decided

1. Configuring:
   • Lexicon.add(*words, kind, **properties) and Lexicon.remove(*words, kind=None), with kinds and properties spelled as the language files spell them.
   • Derived markers come through compile_readings.
   • The generation, credentials and patronymic views read the kind from the lexicon; rules/R8 and rules/R9 are amended when 4i-b builds it.
   • Title warning (decided 2026-11-01): an add warns when a given reading makes the title reading it adds phrase-only, naming remove(w, kind="given"). A property-only update is exempt.
2. Queries: Lexicon.readings_of(word) returns a public LexiconReading, and the repr counts readings by kind.
3. State: five parts — a base, an ordered edit log, the choice, the lists and the masks.
   • Equality is structural, with each edit stored frozen.
   • The base, log and choice are underscore constructor parameters, validated as parser_for validates a choice.
   • | is later-wins. parser_for joins fragments in pack order, with the caller's lexicon last.
   • An edit that clashes with a reading a later choice turns on raises at parser_for, naming the choice.
4. The choice:
   • The Lexicon records its languages and strictness, set publicly only by parser_for.
   • Chained choices union.
   • Caller edits apply after the choice.
   • The default's base stays lazy, keeping the 2026-10-29 lazy-load decision.
5. Pickle: a 2.x state translates onto the nearer named base plus a per-word log. It is refused only where the compile does not give its sets back.
6. Migration: the old spellings fail loudly with a per-word translation.
7. Work order: 4i is built in four PRs, none moving a default parse:
   • 4i-a: the internal sets object
   • 4i-b: the break
   • 4i-c: the recorded choice
   • 4i-d (optional): Reading.languages follows the choice

Declined:

• the caller's reading winning at parser_for;
• an eager default base;
• refusing every 2.x pickle (option a);
• the alternatives weighed for the other items: a positional add, a reading object, new method names, a public IndexReading, per-category predicates, recording no choice, a Parser field, and a pickled base by reference.

Review

• The design-docs reviewer ran on every fix commit.
• Three independent reviews of the proposal ran, and their findings were fixed before the decision:
  • the off-by-default base readings;
  • the dean pickle round trip;
  • log ordering and equality;
  • replace dropping state;
  • the lazy load;
  • the views ignoring a stated kind;
  • the warning's scope;
  • the | and pack order;
  • the 3j quote.

The doc tests pass (2,186).

🤖 Generated with Claude Code