Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 7 additions & 2 deletions docs/design/decisions/H9-title-phrase.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,12 +6,12 @@
- The fork is reported `title-or-name` where the word is the first name word after any titles and no comma has marked the given name: `Dean Smith` and `Dean Smith, MD` report, `SMITH, DEAN MR.` does not — 2026-10-26 #752, phase 2i (Derek). Only where a phrase the vocabulary lists holds the word: `Grace Smith` reports nothing, `Marshal Yanda` does — 2026-10-26 #752, phase 2i, the report's reach (Derek).
- `grace` (a style) and `marshal` (a rank) are titles that may be given names, `sergeant` attaches to the word `major` and `major` to `general` (`attaches` naming a word where a kind would reach too far): `His Grace John Smith`, `Field Marshal Bernard Montgomery` and `Sergeant Major John Smith` read the title; `Mr Justice Smith` keeps given 'Justice', no exception behind a salutation — 2026-10-26 #752, phase 2i (Derek).
- Its partner is a modifier or a style before it, a title before it that attaches to it or a title after it that it attaches to (`attaches`), or `of` after it; a salutation is never one, nor any other title before it (#853's `Mr Dean Smith`), nor a title after it it does not attach to (`SMITH, DEAN MR.`) — 2026-10-25 #752.
- A modifier in the leading run of titles before the first comma is a title only with a head title after it in that run, `of` after it, or in the object of `of` or `the` there; outside that run (ending the name, H5's, or after a comma) it reads as any title does, the given part after a family comma included (`Lau, Wing` → title 'Wing') — 2026-10-25 #752.
- A modifier in the leading run of titles before the first comma is a title only with a head title after it in that run, `of` after it, or in the object of `of` or `the` there; outside that run (ending the name, H5's, or after a comma) it reads as any title does, the given part after a family comma included — 2026-10-25 #752; save a modifier that may be a given name, which the run's test reads in every part (`Lau, Wing Kai` → given 'Wing', `John Smith Wing.` → family 'Wing.') — 2026-10-26 #752, phase 2j, `wing`.
- A title that may be a given name which a caller lists in `titles` is a title wherever it stands, which keeps the 1.4 recipe `c.titles.add("dean")`; a v1 caller who empties `titles` turns the phrase reading off with them, while one who replaces the list keeps it (`c.titles.clear(); c.titles.add('dr')` still reads `Dean of Students` as the title), v1 holding no knob for the set — 2026-10-25 #752.

## Log

- **2026-10-25 #752, phase 2i (its report in a family comma's given part, and its costs `His Grace John Smith` and `Field Marshal Bernard Montgomery`, superseded by 2026-10-26 #752, phase 2i (Derek)) — A TITLE THAT MAY BE A GIVEN NAME IS A TITLE ONLY INSIDE A TITLE PHRASE, AND A MODIFIER AT THE HEAD OF THE NAME ONLY WITH A HEAD BESIDE IT.** Carries out items 10, 11 and 12 of decisions/vocabulary-model's 2026-10-23 #752 entry (decision 10 at the head of the name only; the phrase partner; #853's word after a title), measured here on the rule as built rather than on the spike those items were decided on.
- **2026-10-25 #752, phase 2i (its report in a family comma's given part, and its costs `His Grace John Smith` and `Field Marshal Bernard Montgomery`, superseded by 2026-10-26 #752, phase 2i (Derek); its cost `Lau, Wing`, by 2026-10-26 #752, phase 2j, `wing`) — A TITLE THAT MAY BE A GIVEN NAME IS A TITLE ONLY INSIDE A TITLE PHRASE, AND A MODIFIER AT THE HEAD OF THE NAME ONLY WITH A HEAD BESIDE IT.** Carries out items 10, 11 and 12 of decisions/vocabulary-model's 2026-10-23 #752 entry (decision 10 at the head of the name only; the phrase partner; #853's word after a title), measured here on the rule as built rather than on the spike those items were decided on.
THE WORDS IT READS TODAY. `dean`, `justice` and `major` gain a title reading beside a given one (`justice` until now excluded as a given name, #606, its cost `Chief Justice John Roberts` read as given 'Justice'), so the rule's reach is exactly what master read as name words, now reading the title only in a phrase. Declaring given readings on the titles decisions/vocabulary-model's 2026-10-24 entry ordered (`wing` first) is 2j's, one measured PR per batch. The words leave `titles` for `titles_ambiguous` rather than staying in both, and that is a compat decision, not a convenience: `Constants().titles.add("dean")` is the documented 1.4 recipe for a title the default leaves out, and a word in both sets would be read by the phrase test whatever the caller listed, so `Dean Smith` would lose the title the caller asked for. Measured: with dean in both, `test_the_documented_replacements_for_an_in_place_edit_work` and four shim controls failed, `Dean Smith` reading given 'Dean' with dean added to the titles.
THE PARTNER (item 11). A modifier or a style before the word, `of` after it, a title before it that attaches to it, or a title after it that it attaches to: `attaches`, a title property naming title kinds, compiles into two-word phrases (`chief` attaching to office and military words, `major` to military ones; count them with `uv run python -c "from nameparser import Lexicon; print(len(Lexicon.default().title_phrases))"`). A connective other than `of` is no partner: `Dean and Mary Smith` is two given names, as master read it.
OUTSIDE A PHRASE THE WORD IS UNLISTED, EVERYWHERE. Classify tags it no title, and the two vocabulary rosters that ask whether a word is listed at all, the capitals credential's "unlisted" (rules/C6) and the comma contrast's "claimed as non-name text", leave the set out. The first draft left them in, and the grid below found `John Smith, DEAN`, read suffix 'DEAN' by C6 on master, reversed to given 'DEAN', family 'John Smith'. Keeping the word unlisted outside its phrase is also what the design's spike measured for the 2j words, which it took out of `titles` altogether.
Expand All @@ -34,3 +34,8 @@
- THE RULE. A contested word some phrase in `title_phrases` holds can head a title of itself, so a reader of `Dean Smith` can hesitate; a word no listed phrase holds is a title only behind a style or a modifier (`His Grace`), so standing alone it is no title anyone hesitates over, the test AGENTS.md sets for a reportable fork. The question is asked of the phrases `attaches` compiles (`_vocab.in_a_title_phrase`), so no property was added, and only of the phrases classify can read, two words each a title or a title that may be a given name: a caller's `your grace`, whose `your` is no title, makes `Grace Smith` report nothing (the review of this change). The review also measured the first version splitting every phrase per call, 175 frames more on each name opening with `Grace` (344 against 169); the words are now cached per vocabulary.
- WHICH WORDS FALL WHERE (the default vocabulary, 2026-10-26). Report: `dean`, `justice` and `marshal`, each held by a phrase only because `chief` attaches to their kinds (office, military: `chief dean`, `chief justice`, `chief marshal`), and `major`, which attaches to `general` and which `sergeant`, `sgt` and `chief` attach to. Silent: `grace`, a style, held by none, since no title attaches to the style kind. The partners the rule reads but `title_phrases` does not hold — a modifier or style before the word, `of` after it — are the same for every contested word, so they cannot tell one word from another, and the derivation does not read them. Its consequence: a word reports only while a phrase holds it, so narrowing `chief` to a list of words, or a caller's `Lexicon` with no phrases, silences the report for the words it drops.
- MEASURED (2026-10-26, against master `a46b3a6e`, every local check with `--base`). ctgov-officials 195 moved, 117 for the report alone (`dean` 115); tse-donors 25, 16 for the report alone (`dean` 14, `marshal` 2); fec-individuals 53, as before. The difference from the entry above is exactly the `grace` names (123 and 69). The committed corpora: `Grace Dean Smith` drops its report, the one move.
- **2026-10-26 #752, phase 2j, `wing` — A MODIFIER THAT MAY BE A GIVEN NAME IS READ BY ITS RUN'S TEST IN EVERY PART.** SUPERSEDES: in 2026-10-25 #752, phase 2i, the Accepted cost `Lau, Wing` → title 'Wing'. The first batch of the title words decisions/vocabulary-model's 2026-10-24 #752 (Derek) entry ordered. Phase 2i's decision 10 had already taken `wing`'s head-of-the-name fixes (`Wing Lau`, `Mr Wing Lau`: PSC's 25 fixed of that entry's ranking), so what a `given` reading on `wing` reaches is the two sites decision 10 left as listed: after a comma, and ending the name (H5's). A word in both `title_modifiers` and `titles_ambiguous` takes the modifier test in every part (`_vocab.title_readings`, written so in phase 2i): a title only with a head title after it in its run, `of` after it, or in the object of `of` or `the`. After a comma `Lau, Wing Kai` reads given 'Wing', middle 'Kai', where 1.4.0 through 2.6.0 read title 'Wing', given 'Kai', and `Lau, Wing Commander` keeps the title; ending the name `John Smith Wing.` reads family 'Wing.', where 2.6.0 read title 'Wing.' (1.4.0 read the family too). Alone after a comma `wing` now reads as `dean` has since phase 2i: `John Smith, Wing` reverses to given 'Wing', family 'John Smith', as `John Smith, Dean` does, the cost decision 10 measured for a role word and accepted here because the listing form is what writes the word there (of FEC's 22 names writing `WING` after a comma, the 14 that open the part with it are all `FAMILY, WING …`, the other 8 holding it behind another given word; ctgov writes none); and past a second comma C2 reads it as the suffix with a `comma-structure` report (`Smith, John, Wing`), as `Smith, John, Dean`. Elsewhere the two take different tests, so `wing` is no template for the contested titles: the review's twin grid, `Dean` in `Wing`'s place, read different roles for 1,854 of its 8,820 texts under the default order (`Vice Wing Kai` given 'Vice', `Vice Dean Kai` title 'Vice Dean'). The modifier test, not a contested word's partners, decides it beside a style: `Hon. Wing Lau` keeps given 'Wing' where `Hon. Dean Smith` reads title 'Hon. Dean', and `The Hon. Wing Lau` reads the title through the object of `the`, both as master read them. Ending the name the run's test counts H2's shape as a head, so a period-marked suffix behind keeps the title (`John Smith Wing. Jr.` → title 'Wing.', as master read it) where an unmarked one does not (`John Smith Wing. MD`); both are recorded in rules/H9's Accepted clause. No listed phrase holds `wing`, so `Wing Lau` still reports nothing (the report's reach, above).
- THE COUNTS, recorded on the word (`uv run python tools/name_usage.py Wing`, 2026-10-26): given US SSA 188 births, Wikidata 17 (a lower bound), nam_dict band 1 in China; family Census 12,614, Wikidata 218. PSC's filers put `Wing` in the forename box 158 times as its first word (#853's table) and never in the title box.
- MEASURED (2026-10-26, against master `12384fae`, py3.11, every local check with `--base`; the shape grid, 26,460 parses, by the design-docs review). No corpus holds a trailing `Wing.` or a full name before `, Wing`. fec-individuals 14 moved, every one a `FAMILY, WING …` donor now read with given 'WING' (`AA, WING` 7, `AA, WING AA…` 6, `AA, WING A. MR.` 1). The committed corpora move one name, this rule's former Accepted example `Lau, Wing` (`snapshot.py`); CLDR and GND agreement unchanged (`cldr_agreement.py`). PSC (1,039,174 scored, the fetch dated 2026-10-22), ctgov-officials and tse-donors do not move: PSC scores its names in spoken order, which decision 10 already reads. Spelling consistency (mechanisms.md#PAIRED-SPELLINGS-PER-CHANGE, per person, against master): jrc-names 0 now alike, 0 apart, of 218,822 persons with two or more spellings; nepal-candidates 0 and 0 of 126,981 pairs. No spelling in either writes `Wing` after a comma.
- THE BOUNDARY LEFT. The modifier test takes any title after the word as its head, a salutation too, so `LAU, WING MR` keeps title 'WING MR' where `LAU, DEAN MR` reads given 'DEAN'. No FEC donor writes it: the one with a salutation writes an initial between (`AA, WING A. MR.`), which breaks the run, and reads right. Pinned as a case row rather than narrowed.
Recompute: `uv run python tools/differential/snapshot.py --local fec-individuals --base <checkout of this commit's parent>` (and `ctgov-officials`, `tse-donors`), `uv run python tools/differential/local_agreement.py psc-individuals --base <the same checkout>`.
3 changes: 2 additions & 1 deletion docs/design/decisions/vocabulary-model.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ The vocabulary was a set of base sets plus marker subsets (`particles` and `part
- `e`, `y` and `i` stay in the default; choosing a language is to settle their one-case fork, which no shipped pack does yet — 2026-10-15/16.
- A patronymic field is to come in 3.0, and the particle kinds already draw the `clan`/`patronymic` line for it: a patronymic is followed by a parent's name, a clan prefix by a family name the lineage shares — 2026-10-15/16; 2026-10-19 #749.
- Gender is recorded only where a word gives a definitive clue: a feminine form or one half of a fixed pair, never an unmarked noun — 2026-10-15/16; 2026-10-19 #750, title kinds.
- Title-phrase modifiers count as titles only beside a head title, at the head of the name only and never in a comma part (`Wing Lau` → given 'Wing', `John Smith, Vice` → title 'Vice'), rules/H9 — 2026-10-15/16; 2026-10-19 #750, title kinds; 2026-10-23 #752; 2026-10-25 #752, phase 2i.
- Title-phrase modifiers count as titles only beside a head title, at the head of the name only and never in a comma part (`Wing Lau` → given 'Wing', `John Smith, Vice` → title 'Vice'), save a modifier that may be a given name, which the head's test reads in every part (`Lau, Wing Kai` → given 'Wing'), rules/H9 — 2026-10-15/16; 2026-10-19 #750, title kinds; 2026-10-23 #752; 2026-10-25 #752, phase 2i; 2026-10-26 #752, phase 2j, `wing`.
- Name readings are hand-declared, and only on a word some language file claims as vocabulary or refuses, so the vocabulary carries no surname list (the segmentation lists, Korean and the ZH pack's, are outside the per-word model) — 2026-10-15/16; 2026-10-19.
- Bearer counts are structured provenance (source and count), never used to compute a reading — 2026-10-15/16.
- Phase 2 is to put vocabulary, declared name and shape readings in one pool, derive `may_be_given` and `may_be_name` from declared name readings (a count-free one carrying a `note`, `ld` left ungated, `may_be_initial` kept), and decide every clash by one gate of four steps, floor, form, structure and count, asked at the sites that decide today; the reading not taken is to surface as `Ambiguity.alternative` in 2.x and the reading taken as `Token.reading` in 3.0 — 2026-10-23 #752.
Expand Down Expand Up @@ -216,4 +216,5 @@ Open: #752 (phase 2, derived ambiguity; its sub-phases 2a to 2m, each its own PR
- `dean`, `justice` and `major` gain an office or military reading beside a dated `given` one; `justice`'s exclusion (#606) is replaced by the reading. The batches of 2j declare the rest.
Adding the four fields changes `Lexicon`'s pickle layout, as phase 2h did.
- **2026-10-26 #752, phase 2i (Derek) — `attaches` MAY NAME A TITLE WORD AS WELL AS A KIND, AND `grace` AND `marshal` JOIN THE CONTESTED TITLES.** Amends the `attaches` bullet of the 2026-10-25 #752, phase 2i entry: a kind reaches every word that later joins it, and once `marshal` became a contested military word the military kind made `Sgt Marshal Smith` a title phrase. A list entry that is no kind must be a word with a title reading (a build check, its mutation in tests/v2/test_vocab.py). `major` attaches to `general` and `sergeant` and `sgt` to `major`. `grace` (style) and `marshal` (military, its #606 exclusion replaced) carry dated `given` readings. The measurement and Derek's answers are decisions/H9's entry of this date.
- **2026-10-26 #752, phase 2j, `wing` — THE FIRST TITLE BATCH: `wing` HAS A DATED `given` READING.** The order is the 2026-10-24 #752 (Derek) entry's. Decision 10 had already read `wing` as a name at the head of the name, so the reading reaches the parts decision 10 left as listed, after a comma and ending the name: `Lau, Wing Kai` reads given 'Wing', and `John Smith Wing.` family 'Wing.'. The rule and the measurement are decisions/H9's entry of this date.
- **2026-10-26 (Derek), #785 — PHASE 2g NARROWED: a capitals member with a name word behind it, and no family comma, does not start the credential's run**, the name word being evidence of initials; `Maria Ana MA Silva`, `Jean Pierre MA DUPONT` and `Mary Jane MA King` keep the readings 1.4.0 through 2.6.0 gave, and `John Smith MA Jones` keeping family 'Jones' is the cost. The record is decisions/S6's entry of this date.
Loading
Loading