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
4 changes: 2 additions & 2 deletions AGENTS.md

Large diffs are not rendered by default.

4 changes: 2 additions & 2 deletions docs/design/decisions/H3-title-runs-floor.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,9 @@

## Standing

- The leading title run gives back its last word where everything behind the run is suffix pieces and that word is not suffix vocabulary: `Dr King Jr` → title 'Dr', family 'King', suffix 'Jr' — 2026-09-08 #316.
- The leading title run gives back its last word where everything behind the run is suffix pieces and that word is not suffix vocabulary: `Dr Pope Jr` → title 'Dr', family 'Pope', suffix 'Jr' — 2026-09-08 #316.
- It gives back one word only: a joined title unit stays the title (`Prince of Wales Jr` → family 'Jr'), and where the word given back is the whole name it reads as the given name (`Dr Jr` → given 'Dr', suffix 'Jr', reporting `title-or-name`) — 2026-09-08 #316.
- The floor asks about the run's last word and nothing else: a run ending in suffix vocabulary keeps it (`Dr King RA PhD` → title 'Dr King RA'), and a bare numeral behind the run is the numeral fork's, not this floor's (`Dr King V` → title 'Dr King', given 'V') — 2026-09-08 #316.
- The floor asks about the run's last word and nothing else: a run ending in suffix vocabulary keeps it (`Dr Pope RA PhD` → title 'Dr Pope RA'), and a bare numeral behind the run is the numeral fork's, not this floor's (`Dr Pope V` → title 'Dr Pope', given 'V') — 2026-09-08 #316.

Open: none in this file.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -2,15 +2,15 @@

## Standing

- An input the title peel eats down to one last word that is itself title vocabulary reads that word as the name and reports `title-or-name`, the `detail` naming the word: `Lord Chancellor` → family 'Chancellor', `Dr. King` reports — 2026-09-07 #491.
- An input the title peel eats down to one last word that is itself title vocabulary reads that word as the name and reports `title-or-name`, the `detail` naming the word: `Lord Chancellor` → family 'Chancellor', `Dr. Pope` reports — 2026-09-07 #491.
- `title-or-name` is emitted at assign's lone-name-word site, not at H1's retag, so it is reported under every name order, and so is the suffix half's `suffix-or-name`; the peel half's `detail` names no field — 2026-09-07 #491.
- Nothing is reported where no word was chosen or where the word left standing is no title word: a title alone or a title run with nothing behind it (`Dr.`, `Prince of Wales`), and a title before an ordinary word (`Dr. Smith`) — 2026-09-07 #491.
- An input whose every word is post-nominal vocabulary reads its first word as the name and reports `suffix-or-name` (`Rinpoche`, `QC MP` → given 'QC', `PhD`), reached only where no title was peeled (`RA DDS` reports nothing) and not with a maiden name beside it (`abd née Jones`) or for a lone CJK honorific a script order placed (`さん`); `Jr.` alone is H2's title — 2026-09-07 #491.
- `MA` alone reports `given-or-family` where `PhD` alone reports `suffix-or-name`, an asymmetry between this rule and O5 recorded and not fixed — 2026-09-07 #491.
- A lone name unit that is a join carrying title vocabulary reports `title-or-name` too (`John of Prince`, `Smith and Prince`), stated since 2026-10-20 as rules/H7 — 2026-09-07 #491.
- The join clause (rules/H7's, recorded here) stands beside the peel clause, so a peeled title, a maiden name or a claimed word does not silence it (`Dr. Smith and Prince`, `van and Prince`, `Attorney General of Minnesota` report) — 2026-09-08 #518.

Elsewhere: the title run's floor that leaves `King` standing in `Dr King Jr` and `Dr. King MD`, both reporting here, is decisions/H3's 2026-09-08 entry; the suffix and join halves' `detail` naming the field the word lands in, which moves with the order (`Rinpoche` 'a given name' by default, 'a family name' family-first), is decisions/A1's 2026-10-08 #626 entry; the join clause's move into a rule of its own is decisions/H7's 2026-10-20 #761 entry.
Elsewhere: the title run's floor that leaves `Pope` standing in `Dr Pope Jr` and `Dr. Pope MD`, both reporting here, is decisions/H3's 2026-09-08 entry; the suffix and join halves' `detail` naming the field the word lands in, which moves with the order (`Rinpoche` 'a given name' by default, 'a family name' family-first), is decisions/A1's 2026-10-08 #626 entry; the join clause's move into a rule of its own is decisions/H7's 2026-10-20 #761 entry.

Open: none in this file.

Expand Down
2 changes: 1 addition & 1 deletion docs/design/decisions/H5-trailing-title-run.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
## Standing

- After the trailing suffix run, successive period-marked words the title vocabulary lists chain into the title from the end, leaving one name word standing, and join the title field in input order: `John Smith Prof.` → title 'Prof.', family 'Smith'; `John Smith Prof. Dr.` → title 'Prof. Dr.'; `Dr. John Smith Prof.` → title 'Dr. Prof.' — 2026-09-08 #316.
- The back is claimed by vocabulary and the front by shape, so an unlisted abbreviation (`John Smith Xyz.` → family 'Xyz.') and a bare title word (`John Smith Sir`, `Mary Jane King`) are name words there, the walk asking `is_title_piece` and never `is_leading_title` — 2026-09-08 #316. A listed salutation ending the given part after a family comma is the exception, read as the title bare (decisions/H8).
- The back is claimed by vocabulary and the front by shape, so an unlisted abbreviation (`John Smith Xyz.` → family 'Xyz.') and a bare title word (`John Smith Sir`, `Mary Jane Pope`) are name words there, the walk asking `is_title_piece` and never `is_leading_title` — 2026-09-08 #316. A listed salutation ending the given part after a family comma is the exception, read as the title bare (decisions/H8).
- No fork is reported; where the doubt is real, the word left standing carries it (H4) — 2026-09-08 #316.
- The given part after a family comma gets the walk: `Smith, John Prof.` → title 'Prof.', given 'John' — 2026-09-08 #316.
- The trailing peel and the title chain are one reading run to a fixed point (`_pieces.tail_reading`), so a trailing title is transparent to the suffix reading (`John Smith Jr. Prof.` → suffix 'Jr.'; `abdul rahman MA Prof.` reads as `abdul rahman MA` does, plus the title), and the bound join takes no piece the chain takes (`Sir abdul Prof.` → given 'abdul') — 2026-09-09 (the /simplify round on the bundle's PR).
Expand Down
2 changes: 1 addition & 1 deletion docs/design/decisions/H6-title-before-a-family-comma.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
- A run of title words opening the part before a family comma is the title, joining the title field in input order with any title after the comma, and the comma decision is untouched, so the reading is the same under every name order: `Dr. Smith, John` → title 'Dr.', family 'Smith'; `Prof. Dr. Brühl, Ada Cornelia` → title 'Prof. Dr.' — 2026-10-17 #701.
- The run admits a word by vocabulary only, never by H2's shape, since the slot is a surname's slot too and a surname can open with an abbreviated word: `Xyz. Smith, John` → family 'Xyz. Smith', `Sta. Maria, Juan` → family 'Sta. Maria' — 2026-10-17 #701; 2026-10-18 #710.
- The run leaves the family its last piece (`Dr., John` → family 'Dr.'), stops at a word that is a particle too (`St Pierre, Ed` and `Freiherr von Berg, Ed` keep their families, while `Dr. Freiherr von Berg, Ed` peels 'Dr.'), and stops where nothing but post-nominals stands behind a title (`RA PhD Jr., John` → family 'RA'), so a title/suffix dual with a name word behind it peels (`Rev. Sr. Smith, Mary` → title 'Rev. Sr.') — 2026-10-17 #701.
- A surname-like title opening a two-word surname is the title (`King Smith, John` → title 'King'), an accepted cost — 2026-10-17 #701.
- A surname-like title opening a two-word surname is the title (`Pope Smith, John` → title 'Pope'), an accepted cost — 2026-10-17 #701.
- `gov` is a title (`Lt. Gov. Smith, John` → title 'Lt. Gov.'), the first piece the run leaves is the family whatever it is (`Dr. PhD Smith, John` → family 'PhD Smith'), and the particle stop is all that keeps a rank in the family, so `Graf Lambsdorff, Otto` reads title 'Graf' — 2026-10-17 #701.
- The comma-less writing of an abbreviated surname is not this rule's and still splits it (`Juan Sta. Maria` → middle 'Sta.', family 'Maria'); listing `sta` and `sto` as particles is weighed and not decided — 2026-10-18 #710.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@

- A salutation ending the given part after a family comma, written bare or with a stop at its edge that H5's abbreviation shape does not take (`Mr..`), is the title, read as its period-marked spelling reads in every comma shape and under every name order: `Doe, Jane Mrs` → title 'Mrs', given 'Jane'; `DOE, JOHN Q MR` → title 'MR', middle 'Q' — 2026-10-24 #835.
- Only the salutations marked `after_given` in the vocabulary qualify, and a salutation borne as a given name or a surname is left out by an exclusion carrying its counts, since a middle name may be either (`Doe, John Goodman` keeps middle 'Goodman') — 2026-10-24 #835.
- No other title kind qualifies (`Doe, John King` and `Doe, Jane Dr` keep their middle names), a title/suffix dual stays a suffix (`Doe, Jane Ms`), and the comma-less writing is H5's (`Jane Doe Mrs` keeps family 'Mrs') — 2026-10-24 #835.
- No other title kind qualifies (`Doe, John Pope` and `Doe, Jane Dr` keep their middle names), a title/suffix dual stays a suffix (`Doe, Jane Ms`), and the comma-less writing is H5's (`Jane Doe Mrs` keeps family 'Mrs') — 2026-10-24 #835.
- A salutation that is someone's middle name reads as the title after a family comma, an accepted cost (`Doe, Jane Miss`); so does the empty head's one given word moving to the family as the period-marked spelling moves it (`, Jane Mrs` → family 'Jane') — 2026-10-24 #835.
- The rule reads the comma, not a declared order: `Doe Jane Mrs` under FAMILY_FIRST keeps middle 'Mrs', so the family-comma invariant of decisions/two-input-invariants does not hold for a trailing salutation — 2026-10-24 #835.

Expand Down
6 changes: 6 additions & 0 deletions docs/design/decisions/H9-title-phrase.md
Original file line number Diff line number Diff line change
Expand Up @@ -50,3 +50,9 @@
- THE COSTS, in rules/H9's Accepted clause, none written by any name the corpora hold (0 matches in the eight local corpora and the committed ones, 2026-10-26): the Sikh title in the spelling `Gyani` before a name reads as the given name (`Gyani Zail Singh`; its usual spelling `giani` has no given reading and keeps the title); a title before the word that is no style, modifier or attaching title is no partner (`Lord Buddha Tamang` → given 'Buddha'; `His Holiness Buddha Ram` and `Grand Buddha Ram` keep the title); and the epithet with its article reads as the `mahdi` entry's does, after a comma and before a name (`Ram Tamang, the Buddha` → given 'the Buddha', `The Buddha Ram` → given 'The Buddha').
- MEASURED (2026-10-26, against master `021028b2`, py3.11, every local check with `--base`). nepal-candidates: 121 romanized names moved (`snapshot.py --local nepal-candidates`), 117 the word read out of the title alone and 4 gaining or losing a report: 2 lose H4's `title-or-name`, the name having been nothing but vocabulary (`Gyani Lama`, `lama` a title too, as `Lord Buddha` and `Lord Mahdi` lose it), and 2 gain the `suffix-or-name` any name with a trailing credential word and words to spare gets (`Buddha Lama ma` reads as `Ram Lama ma`). Spelling consistency (mechanisms.md#PAIRED-SPELLINGS-PER-CHANGE, romanized against Devanagari, by structure): 128 pairs now alike, none apart. ctgov-officials 4 moved, all fixes, 2 of them one official written twice whose credential master read as the given name (`Buddha Aa, CAPS, Aa, CAPS` → given 'Buddha', the credentials suffixes, `suffix-or-name` on the name word between them). PSC (1,039,174 scored), fec-individuals, tse-donors, jrc-names, the committed corpora and CLDR and GND agreement do not move.
Recompute: `uv run python tools/differential/snapshot.py --local nepal-candidates --base <checkout of this commit's parent>` (and `ctgov-officials`); the pairs compare `local_corpora._read`'s structure of each record's `name` and `devanagari` in each tree, run from that tree's checkout.
- **2026-10-26 #752, phase 2j, `king` (Derek) — THE FOURTH TITLE BATCH: A MONARCH'S BARE TITLE READS AS THE GIVEN NAME.** The batch decisions/vocabulary-model's 2026-10-24 #752 (Derek) entry put fourth. `king` gains a dated `given` reading and is a title only inside a title phrase; no listed phrase holds it, so nothing is reported. `King Curtis`, `Mr King Smith` and `SMITH, KING MR` read given 'King', where 1.4.0 through 2.6.0 read title 'King' and `Mr King` (`SMITH, KING MR`: title 'KING', given 'MR' in 1.4.0 through 2.1.0, title 'KING MR' from 2.2.0). A style keeps the title (`His Majesty King Charles` → title 'His Majesty King', given 'Charles', the title still addressing by the given name), as does `of` (`King of England`). The other sites read as for `mahdi` and `buddha` (the entries above): before a family comma (`King Smith, John` → family 'King Smith', 1.4.0's reading, where 2.5.0 through 2.6.0 peeled `King`), ending the name (`Mary Smith King.` → family 'King.'), alone after a full name and a comma, past a second comma, and under a family-first order the word before a name is the family.
- THE COUNTS, recorded on the word (`uv run python tools/name_usage.py King`, 2026-10-26): given US SSA 37,890 births, Wikidata 178 (a lower bound; United States 92), nam_dict band 1 in the U.S.A. and China; family Census 465,422 (rank 34), Wikidata 4,554.
- THE COST, measured and decided. A monarch written with the bare title in front reads `King` as the given name: `King Henry` → given 'King', family 'Henry', where 1.4.0 through 2.6.0 read title 'King', given 'Henry'; so do `King Charles III`, `King John V.` and `King and Queen Smith` (given 'King and Queen'). `queen` is in no batch, so `Queen Elizabeth II` keeps its title. In the committed corpora the cost is three rows (`King Henry`, `King John V.`, `King John Alexander V`). Of the local corpora only jrc-names, drawn from news text, writes monarchs: 20 persons (39 spellings) open with `King`, by a reading of each about half monarchs or legendary kings and half people whose given name, stage name or nickname is King; PSC, FEC, ctgov and ukec write none. Shown these figures, Derek decided on 2026-10-26: "Accept the royal cost for king". Recorded in rules/H9's Accepted clause.
- `king` WAS THE WORKED EXAMPLE OF A TITLE THAT IS ALSO A SURNAME, in rules H1, H3 to H8, M2, S2 and S8, their decisions Standing lines, AGENTS.md, docs/usage.rst, two code comments and eleven case rows and tests. Each now uses `pope`, chosen because it reads as `king` read on master in every one of those examples (19 inputs checked against `queen`, `bishop`, `pope`, `baron`, `judge`, `sheriff`, `mayor` and `emperor`; only `pope` and `queen` matched all, `pope` being the commoner surname). decisions/v1-xfail-triage's "`king` stays in TITLES" is superseded there.
- MEASURED (2026-10-26, against master `957509d1`, py3.11, every local check with `--base`). PSC (1,039,174 scored): 58 records fixed, none broken, 5 changed. fec-individuals 73 moved, all fixes: `AA, KING …` given names (51) and `KING AA, AA` family parts that H6 had peeled (22). ctgov-officials 12, all fixes: officials whose given name is King (`King A. Aa`), and one whose credential master read as the given name (`Aa King, AA Aa` → given 'Aa', family 'King', the credentials suffixes). tse-donors, ukec-individuals, jrc-names and nepal-candidates pairs (0 now alike, 0 apart: both spellings of a person move together), CLDR and GND agreement do not move. The committed corpora move 11 names before the rules examples were rewritten: the three royal rows, `King Curtis` (#348's example, fixed), `King Smith, John` and `Mary Jane King.` (1.4.0's readings), a maiden clause, and four that only lose H4's `title-or-name`, the word no longer being title vocabulary (`Dr. King`, `Dr King Jr`, `Dr. King MD`; `Smith and King` reports `given-or-family` instead).
Recompute: `uv run python tools/differential/local_agreement.py psc-individuals --base <checkout of this commit's parent>`, and `uv run python tools/differential/snapshot.py --local fec-individuals --base <the same checkout>` (and `ctgov-officials`).
4 changes: 2 additions & 2 deletions docs/design/decisions/M2-maiden-marker-rule.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,8 +11,8 @@
- A shape-only roman numeral ends the clause where the clause-free name reads it as the suffix, a title or the merged `Ph. D.` behind it included: `John née Jones Smith VI` → maiden 'Jones Smith', suffix 'VI'; `Jane Doe nee Smith VI Prof.` → suffix 'VI', title 'Prof.' — 2026-10-04 #610.
- The take reads its clause-free view over `_pieces.trailing_candidates`, written beside the peel, a superset of what `tail_reading` takes with no exception and no case fact — 2026-10-04 #610; 2026-10-18 (Derek), #731 reverted.
- Where a trailing rule reads the part, a trailing title ends the clause, and a credential or numeral in front of it gets the stop it gets with the title absent: `Jane Doe nee Smith Prof.` → title 'Prof.', maiden 'Smith'; `Jane Doe nee Smith MA Prof.` and `… Prof. MA` both → maiden 'Smith', suffix 'MA'; `Jane Doe nee Smith V Prof.` → suffix 'V' — 2026-09-26 #535.
- The title chain never takes the first word after the marker: `Jane Doe nee King.` keeps maiden 'King.', `Jane Doe nee Prof. Dr.` reads maiden 'Prof.', title 'Dr.', and a first word in the title vocabulary counts as a word, so `Jane Doe nee King. ba` gives up 'ba' as `Jane Doe nee Smith ba` does — 2026-09-26 #535.
- Accepted, the transparency boundary: where the clause keeps the credential the two spellings differ, a title inside the kept text unable to leave without the words behind it (`Doe nee Smith ba Prof.` → title 'Prof.', maiden 'Smith ba'; `Doe nee Smith Prof. ba` → maiden 'Smith Prof. ba'), and H5's `King.` cost reaches a birth name (`Jane Doe nee Smith King.` → title 'King.', maiden 'Smith') — 2026-09-26 #535.
- The title chain never takes the first word after the marker: `Jane Doe nee Pope.` keeps maiden 'Pope.', `Jane Doe nee Prof. Dr.` reads maiden 'Prof.', title 'Dr.', and a first word in the title vocabulary counts as a word, so `Jane Doe nee Pope. ba` gives up 'ba' as `Jane Doe nee Smith ba` does — 2026-09-26 #535.
- Accepted, the transparency boundary: where the clause keeps the credential the two spellings differ, a title inside the kept text unable to leave without the words behind it (`Doe nee Smith ba Prof.` → title 'Prof.', maiden 'Smith ba'; `Doe nee Smith Prof. ba` → maiden 'Smith Prof. ba'), and H5's `Pope.` cost reaches a birth name (`Jane Doe nee Smith Pope.` → title 'Pope.', maiden 'Smith', the example `King.` until `king` left the titles on 2026-10-26) — 2026-09-26 #535.
- Where a trailing rule reads the part, a member of the ambiguous class ending the maiden name is kept by the clause and reported, nobody writing a credential straight after the marker as its floor: `Jane Doe nee MA` → maiden 'MA', `Jane Doe nee Smith Ma` → maiden 'Smith Ma', and `Jane Doe nee Smith MA` → suffix 'MA', each reporting `suffix-or-name` but the last, whose capitals settle it in silence since 2026-10-25 #785 (decisions/S6) — 2026-09-19 (Derek), #533.
- Accepted with it: `JANE DOE NEE YO-YO MA` → maiden 'YO-YO', suffix 'MA', the one-case reading's cost; `Jane Doe nee Smith X.Y.Z.` → suffix 'X.Y.Z.', as `John Doe X.Y.Z.` reads; `Jane Smith nee Jones and MA` → maiden 'Jones and', suffix 'MA', the take running before the joins — 2026-09-19 (Derek), #533.
- A word the clause gives up reads as a post-nominal or title or the clause keeps it, so where a trailing rule reads the part every word written after a taken marker is roled maiden, title or suffix (before a family comma it is not, as above); held since #601 by binding the clause-free reading as roles — 2026-09-19 (Derek), #533 review, A WORD; 2026-10-04 (Derek), #601.
Expand Down
Loading
Loading