[derek73]

Sub-phase 4d of #754, the last of the views lane (4a–4d).

What it does

Where two_family_names (rules/O6) reads a family as two name units, ParsedName.surname2 holds the one written second. family keeps both, as before.

>>> two = Parser(policy=Policy(two_family_names=True))
>>> two.parse("Gabriel García Márquez").surname2
'Márquez'
>>> two.parse("García Márquez Gabriel")  # under FAMILY_FIRST: 'Márquez'

Every other name has an empty view:

• the default policy;
• a family comma (Lloyd Webber, Andrew, García López, Ana);
• a hyphenated family, or one joined by a connective or a particle chain (García-López, Ortega y Gasset, de la Vega Rodríguez);
• a name unpickled from 2.x, or one whose family was rewritten by replace() or revise(). Rewriting any other field keeps the view.

surname2 is a render() key. It stays out of as_dict(), --json, comparison_key() and the repr. surnames is unchanged.

A decision the spec left open: where the mark lives

The RFC planned a new stable tag in STABLE_TAGS. Token compares its tags, so a published tag would make an O6 parse unequal to its own 2.8.0 pickle. This PR does what 4b and 4c did with their kind tags instead:

• O6 writes a private vocab:second-surname tag on each word of the second unit.
• Assemble drops the tag and sets Reading.second_surname on that word's reading. The field is new, carries ADDED_IN 3.0.0 and has compare=False, like Reading.languages.
• The repr shows it: Reading('name' as 'family', 'position', second surname).
• A 2.8.0-wheel pickle of an O6 parse (tests/v2/data/parsedname_v28_two_family_names.pickle) loads equal to the 3.0 parse.

The RFC's freeze table and a new dated Standing line plus a Log entry in decisions/vocabulary-model record this amendment. The decided 2026-10-28 Standing line is left as written. decisions/R10 lists the alternatives weighed:

• a ParsedName field holding the unit's start;
• a new ReadingKind, which would overwrite a particle's or patronymic's reading.

Every word of the unit is marked, not only its first. Two consequences:

• O3's folded middles and a particle P6 attached to the first unit simply stay unmarked.
• A patronymic in the second unit keeps its reading and shows in both views (Ali Hassan bin Ahmad → surname2 and patronymic bin Ahmad).

Recorded as Open (decisions/R10)

• A view for the first unit, and its name (surname sits next to surnames). The first-unit view would also carry each unit's own particles and base.
• Whether a family joined by a connective or a hyphen should read as two units, given that O6 counts it as holding two already.

Measurements (on 8a1e6f5f)

Field readings. Over 1,296 parses of 36 names, tokens, tags and readings are identical to the base apart from the new field. The grid covered every order, middle_as_family on and off, two_family_names on and off, and the default, RU and TR_AZ packs.

Snapshot. 6,601 → 6,603 readings:

• no row moves, and none gains the key, because the snapshot parses the default policy;
• the header names surname2;
• R10's examples add two names.

Agreement records. They gain only surname2 entries, each a stated second surname that the default does not read:

Record	New entries
CLDR	117
CLDR locale record	22 lines
Wikidata	330 (es 150, mx 100, co 80)
Conventions	2

With two_family_names on, the view agrees on:

• 263 of Wikidata's 330 (es 97, mx 91, co 75);
• 7 of CLDR's 117 (its foreignFull second surnames are two words, González Domingo);
• 0 of the 2 conventions rows.

Where no second surname is stated, the switch fills one in:

• CLDR: 700 of 2,523 renderings. 102 of these are among the 252 renderings that leave out a second surname CLDR states for the name.
• Wikidata: 160 of 338.
• GND: 107 of 801.
• The native-script source: 39 of 1,027.
• Conventions: 15 of 28.

decisions/R10 has the recipe.

Frames per parse (warm, sys.setprofile call events):

Name	Policy	Base	This PR
reference row	default	310.1	310.1
Gabriel García Márquez	default	258	258
Gabriel García Márquez	O6	284	286
Juan Pérez de la Vega	O6	330	334
García Márquez Gabriel	O6, FAMILY_FIRST	291	291

A first draft cost +13 and +35 on the two O6 rows. It rebuilt each marked token at the end of assemble.

Sweeps

Each shape ran under two_family_names on and off, under each name_order, and with and without middle_as_family:

• each comma shape: none, a full name before the comma, one word before it, nothing before it, a nickname-only head;
• particles in either unit, the connective y, titles, suffixes and nicknames;
• P6's attached particle;
• RU and TR_AZ patronymics, including a Turkic father in the second unit (Ali Vali oglu under family-first). Without the fix in assemble, these rows fail.

The table in tests/v2/test_types.py keeps a row for every shape O6 declines, so a widening of what fills the view shows up there.

The rule-example grammar now accepts a digit in a field name, for surname2. Tests cover:

• an unknown field with a digit (given2) is still refused;
• a field name that opens with a digit is refused;
• an unquoted surname2= assertion outside a fence is still caught (this row fails against the old pattern).

Docs

• New: rules/R10 and decisions/R10.
• O6 rule: a Then bullet pointing at the view. O6 decisions: a Standing line and a log entry.
• decisions/vocabulary-model: a 4d entry and its Standing line.
• RFC: status, freeze table, 4d row, and Left open.
• mechanisms.md, AGENTS.md, and the tools README.
• User docs: usage.rst, plus customize.rst's two-family-names section with doctests.
• A release-log bullet.

Checks

These pass on 3.11:

• uv run pytest
• uv run pytest -n0 -m serial
• uv run mypy
• uv run ruff check
• tools/vocab/build.py --check
• Sphinx html and doctest builds
• the README doctest

uv run --python 3.15 pytest -q also passes.

🤖 Generated with Claude Code