[derek73]

Closes #1022.

Where rules/O6 (two_family_names) reads the family as two surnames, the new views read the first one:

input (two_family_names)	family_base (unchanged)	surname1	surname1_particles	surname1_base	surname2
Juan Pérez de la Vega	Pérez Vega	Pérez	''	Pérez	de la Vega
Juan de la Vega del Valle	Vega Valle	de la Vega	de la	Vega	del Valle
Gabriel García Márquez	García Márquez	García	''	García	Márquez

A family read as one unit is its own first surname, so for the default parse the views equal family, family_particles and family_base. CLDR patterns fill surname-prefix / surname-core / surname2 from surname1_particles / surname1_base / surname2.

Decided (four questions plus one follow-up, recorded in decisions/R11)

1. Shape. Three new views, named to pair with surname2. family_particles and family_base keep reading the whole family, so rules/R2 is unchanged. Rejected alternatives: the name surname, which sits next to the unrelated surnames, and narrowing the family views.
2. What the first unit is. It is the first unit O6 read. A middle name O3 (middle_as_family) folds in is in neither unit, whether O6 read one unit or two. A particle P6 attached is in the first unit.
   • Measured on Wikidata's second-surname strata (330 names): the first surname is right in 264 with middle_as_family on, against 227 for "family minus surname2".
   • On CLDR 48, surname-core is right in 9 against 0.
   • Every source that fields two surnames puts middle names outside the first one.
3. initials() is unchanged. It still initials the whole family's base; a monogram is a render pattern's job.
4. Where the views appear: as render() keys and in rule examples. Like surname2, they stay out of as_dict(), --json, comparison_key() and the repr. Unlike surname2, they stay out of the snapshot too, since under the default policy they always equal the family views.

Mechanism

• O6 now marks the first unit's words as it already marks the second's.
• Where O6 marks nothing, O3 marks the family before folding middles into it.
• The marks reach the published token as Reading.first_surname (ADDED_IN 3.0.0, not compared, so 2.8 pickles load).
• The views needed this because a finished parse cannot tell O3's fold from P6's attachment: both carry FOLDED_TAG, and P6's own tag is dropped at assemble.

Docs and tools

• New rules/R11 and decisions/R11, plus edits to rules/O6, decisions/R10, the RFC's render-pattern table and API table, and mechanisms.md.
• User docs: usage.rst and customize.rst. Release-log bullet added.
• cldr_agreement.py scores CLDR's prefix and core against the first unit's views as roles of their own, only where a surname2 is stated. The merged base keeps the second surname in, so the default parse, which reads one unit, isn't counted twice.

Accepted costs (rules/R11)

• A first unit that is a lone particle has an empty base. This happens where O6 itself splits a family-first van Gogh Vincent; reading the particle as the base was tried and backed out, because it broke the partition.
• A fold into an empty family: for , John Paul, nothing is marked.

Review

Three passes: code and design docs on the first commit, then one on the fix commit. Fixed:

• untested patronymic paths;
• the one-unit O3 case (decided as a follow-up);
• missing summary lines;
• stale RFC prose;
• a recipe that first reproduced 262 instead of 264;
• the lone-particle base, backed out.

Checks:

• uv run pytest: 36,092 passed. Ruff and mypy clean. Sphinx doctests pass.
• The clock-timed scaling rows failed on unrelated shapes at load average ~40; the frame guards pass.

🤖 Generated with Claude Code