Phase 4: order and shapes, the rules a pack can choose, and the output model

Part of #747. Mostly independent of phases 2 and 3.

Order versus shape (decided): a language supplies only a default order. The shapes each order accepts (where titles, suffixes, particles and commas sit) belong to that order, in the core.

The work:

An inventory of the shapes each order accepts, extending tools/differential/shapes.py (Should docs/ document input shapes for the family-first name orders, and does a trailing particle belong in the notation? #469's inventory).
The rules a pack can choose and parameterize in its TOML ([rules], ending rules such as -ovich), with implementations in the core.
The output model: align with CLDR's fields, add surname2, a patronymic or neutral parent-names field (a matronymic fits it too), family allowed to be empty, an alternate or reading view, and what middle means.

Related questions are linked here as sub-issues.

Status (2026-11-03). Shipped in 3.0's cycle:

4a, Token.reading: Add Token.reading, the reading the parse took for each word (3.0, 4a) #942, with Reading.languages in Fill Reading.languages from the reading index (3.0, 4a's follow-up) #944;
4b, the generation and credentials views: Add generation and credentials views over suffix (3.0, 4b) #947;
4c, patronymic: Add ParsedName.patronymic, the words naming the bearer's parent (3.0, 4c) #948;
4d, surname2: Add ParsedName.surname2, the second of two family names (3.0, 4d) #951;
4e, render order: Render a name in the order it was read in, keeping its separators (4e, #754) #943;
4f, [rules] in a pack's policy patch: Compile a language file's [rules] into its pack's policy patch (3.0, 4f) #953;
4g, two_given_names (rules/O7): Add Policy.two_given_names, the compound given name as a rule kind (3.0, 4g) #954;
4h, the shape inventory per order: List the shape inventory per name order (3.0, 4h) #974;
the O6 given-name veto: Leave a listed given name out of two_family_names' family (rules/O6, #959) #961;
4i, the Lexicon surface, configured by reading: design Design: the 3.0 Lexicon surface, configuring by reading (#754, 4i decided) #988, then Read the vocabulary sets through Lexicon._sets (#754, 4i-a) #989 (the pipeline reads Lexicon._sets), Configure a Lexicon by reading; its set fields are internal (#754, 4i-b) #991 (add/remove by reading), Record the choice of languages on the Lexicon (#754, 4i-c) #992 (the choice of languages recorded on the Lexicon) and Reading.languages names the files on in the parse's own Lexicon (#754, 4i-d) #997 (Reading.languages names the files on in the parse's own lexicon). Simplify the 4i choice compile and reading-files code (#754) #1001 simplified the code. Deprecate the 2.x Lexicon translation: a 2.x pickle load warns (#754) #1002 deprecated the 2.x translation, and 3.1: delete the 2.x Lexicon translation — refuse 2.x pickles, shorten the old-spelling errors #1003 deletes it in 3.1. Lexicon.words(kind=...) and the whole-kind remove(kind=..., every=True): Add Lexicon.words(kind=...) and remove(kind=...) with no words (#1007) #1009. The vocabulary modules in nameparser.config (Should from nameparser.config.titles import TITLES still work in 3.0, now that Lexicon.readings_of() answers what a word is? #1007) and config.regexes (Remove nameparser.config.regexes in 3.0? The parser has not read REGEXES since 2.0 #1008) are removed by Remove the vocabulary modules in nameparser.config (#1007) #1012 and Remove nameparser.config.regexes, which the parser has not read since 2.0 (#1008) #1010; 2.8.1 warned of both (2.8.1: deprecation warnings for the Lexicon set fields and the config modules 3.0 removes #1011).

Still open:

which particle phrases complete a given name (Should a two-word given name like María José or Min Ho fill given, instead of given + middle? #704);
render patterns: the shape of a pack's CLDR display and sorting patterns is agreed, but not yet how a call reaches one (decisions/vocabulary-model's 2026-10-28 render-patterns entry). The RFC says 3.0 if time allows, 3.x otherwise.

Standing block for decisions/vocabulary-model (#762) (#800)

A ranking for the surname-span rule, from an unselected population

The RFC's surname-span measurement (315 of 390 given-first double surnames disagreeing, GND and Wikidata) "was taken over corpora built to hold second surnames, so it shows that the gap exists, not how it ranks against the others". The local corpus psc-individuals (#849) can rank it. It holds Companies House's people with significant control, 1 in 8 of the snapshot dated 2026-10-22: 1,040,708 filed names, nobody chose them, and each filer typed the forename, middle name and surname into separate boxes.

Size. 29,023 names (2.8%) have a two-word filed surname. 22,168 of them read with the surname's first word as a middle name (Ana García López → middle García, family López). It is the largest disagreement shape in the score.

Who. Only 28% of the 22,168 (6,225) are Spanish, Portuguese or Latin American nationals. The rest are not:

nationality	records	two-word surname	read with a middle	share of records
British	680,873	10,236	7,688	1.1%
Spanish	6,101	3,940	3,820	62.6%
Indian	21,132	1,206	1,151	5.4%
Portuguese	5,343	1,204	932	17.4%
Italian	11,790	1,046	571	4.8%
Moroccan	3,577	550	541	15.1%
Pakistani	16,532	523	481	2.9%
French	9,249	609	433	4.7%
Brazilian	1,927	560	389	20.2%
Sri Lankan	1,974	392	360	18.2%
Mexican	405	271	262	64.7%
Colombian	379	264	258	68.1%

What it means for this phase.

Where an es pack would help: in Spanish, Mexican and Colombian names, nearly two in three names are misread. That is the strongest case in the data for an es pack's surname-span rule.
Where it would not: a rule chosen by a language pack reaches only callers who know the language, and most of these names come from nationalities no es/pt pack would be chosen for. Nationality is not a naming convention, so the British, Indian, Moroccan and Sri Lankan counts mix several conventions (South Asian two-word surnames are Tariq Abdul Aziz: should a two-word surname like Abdul Aziz stay whole after the given name? #694's question). Even so, they say the shape is not only Iberian.
What that leaves the default: the only general signal is the comma, and the RFC's own figure shows that index form disagrees on 0 of 60.

Recompute. uv run python tools/differential/local_agreement.py psc-individuals reports the shape as middle 0->1, family 2->1 and middle 1->2, family 2->1. The per-nationality rows count the records in agreement.jsonl whose filed surname has two words and whose parsed family is its second word. The names stay in the cache; this comment prints counts only.