Read any of the pipeline's hyphens as a hyphen, and set a maiden name's particles aside (#1264) - #1344

Settles the two gaps #1341 left open as decisions on #1264, both now decided yes. The other three rows of #1264's table were settled earlier (#1289, #1296, #1341), so this closes it.

Read first

• The hyphen claim holds where the parser reads a name alike. The parser itself reads some names differently with another hyphen, and the match compares the fields it is given. This limit was already present at the merge base, and this PR does not change the parser.
  • A credential or generation joined by another hyphen becomes a name word: John Smith MD‐PhD gets family MD‐PhD; John Smith, NP‐C, , OTR‐L and , M.D.‐Ph.D. put the credential in the given name; John Smith Jr.‐III gets family Jr.‐III. No suffix written with a hyphen parses alike under the other hyphens.
  • A trailing title the vocabulary lists with the hyphen-minus becomes a name word too: Hans Meier Priv.‐Doz. gets family Priv.‐Doz..
  • A spaced hyphen between credentials stays inside the suffix: John Smith, MD ‐ PhD keeps suffix MD ‐ PhD, where the hyphen-minus gives MD, PhD.
  • These pairs stay apart. They conflict, except where the family-first order lands the word in the middle name, where it reads one-sided.
  • _PARSER_HYPHEN_LIMITS pins them under all four parsers, so a parser fix will show up. Titles at the head, at the end and after a comma do read alike (Dipl.‐Ing. Hans Meier, Hans Meier Dipl.‐Ing., John Smith Lt.‐Col., Hans Meier, Dr.‐Ing.).
• The maiden name does not get the family chain whole. It asks particles-aside and then part-of-other on its two bases, ahead of the outcomes it read before.
  • Measured cost of the whole chain on the same draw: 126 maiden rows initial → family-initial, 21 initials-agree → part-of-other, 21 hyphenated-part → conflict, and 42 more conflict → part-of-other.
  • In verdicts, that is 81 consistent → inconsistent (e.g. Ana Ruiz (née V.) / Ana Ruiz (née Vega)) and 41 more inconsistent → consistent.
  • As built, no verdict moves to inconsistent under any setting. Overrule here if "the way a family name is" was meant literally.
• Two maiden texts of initials alone skip the new leniencies, following joined's recorded exception. So (née J.-P.) / (née J. P.) stays initials-agree, which is matching.rst's example of it, and (née J. P.) / (née P. J.) stays a conflict.
  • The family name reads J. P., Ann / P. J., Ann as part-of-other, consistent, and did before this PR too. That is now an Open: question in the decisions file.
• The maiden name departs from the family comparison in two more places, both stated in the entry and held by a test:
  • Particles alone. A maiden particle carries no unjoined tag, so the maiden bases are empty and (née de la) / (née de) conflicts (it conflicted at the merge base too). The family pair de la, Ana / de, Ana reads part-of-other.
  • A particle as a hyphen half, present at the merge base. (née al-Rashid) / (née al) reads hyphenated-part, consistent under that opt-in, where the family pair conflicts.
• Changes outside _match.py and its tests: one row in tests/v2/test_layering.py's table (_match → nameparser._pipeline._vocab, for _HYPHEN_CHARS and _HYPHENS), the matching sentence in AGENTS.md's layering bullet, and _match's module docstring.
• The maiden name was measured on test-written names only. No corpus match_diff.py draws from holds maiden names. 12 corpus pairs (jrc-names) hold a hyphen other than the hyphen-minus.

What changes

Any of the pipeline's hyphens is a hyphen, wherever the parser reads the name alike.

• _match._fold is the lexicon's fold, then every character of _pipeline/_vocab._HYPHEN_CHARS written as the hyphen-minus (rules/O6's set: U+2010, U+2011, figure dash, en dash, minus sign, and the small and fullwidth hyphen-minus).
• A written word is cut at any of them in _part_agrees, in _family_words (which the check and the keys share), and in the keys' joined and whole forms of a word.

A maiden name sets its particles aside.

The default keys hold no maiden word and do not move.

Tests

• test_any_hyphen_reads_as_the_hyphen_minus. Runs under the default, FAMILY_FIRST, locales.ES and locales.ZH parsers, under the default setting and with every opt-in and other_readings on.
  • Input: 24 hyphenated names, each read with the seven other hyphens. The hyphens are written out from rules/O6, not read from _HYPHEN_CHARS.
  • The 24 names place a hyphen in a family name before and after a comma, a given name and a maiden name; beside a particle half (Al‐, al‐, Ter‐); in a title at the head, at the end and after a comma; doubled, leading, trailing and stray (- Pierre, "- Boy"); and spaced as a separator (Ann Smith – Jones).
  • Asserts the parse matches field for field.
  • Asserts the keys are equal.
  • Asserts every comparison reads the hyphen-minus pair's outcomes, in both argument orders: against the name itself, against 26 partners, and against every other hyphenated name written with the en dash.
  • Asserts a consistent pair shares a key.
  • Asserts every listed hyphen was read, so the test cannot pass on nothing.
• test_no_other_character_reads_as_a_hyphen. The em dash, U+2015, the slash and the tilde each move some name's parse, under every parser, so the parity check discriminates.
• _PARSER_HYPHEN_LIMITS and the spaced-credential test pin the parser's limit.
• Shared grids. U+2010 and the en dash joined NAMES (3) and _SHAPE_NAMES (3), with maiden-particle names (4 and 2).
• Maiden rows, both orders.
  • particles-aside, part-of-other, a hyphen half and a particle hyphen half.
  • A listed spelling inside a compound maiden name.
  • joined, folded, initial, initials-agree and one-side.
  • Particles alone, (née) with no name, and 旧姓.
  • Both departures from the family comparison.
  • The cells that held at the merge base (test_a_maiden_outcome_accepted_at_the_merge_base_stays_accepted, narrowed in review), and the cross-role non-match.
  • Default keys with no maiden word.
• Every row reading a new outcome fails at the merge base.

Negative controls

Taken at the final code, each mutation applied and reverted.

• _RECORDED_CONTROLS and _SHAPE_CONTROLS. Every earlier pair stands. The new keys-only mutation (the keys cutting a family word at the hyphen-minus alone) fails the main grid's guarantee under 6 settings and 24 of the 32 shape-grid runs.

Measurement

uv run python tools/differential/match_diff.py --base <fresh detached worktree at the merge base 62bbdeb1>, run after the last test edit (its pairs come from this branch's tests).

• 3,254 of 655,473 rows moved (31,213 pairs × 21 settings): 312 under each of the four settings that accept across-roles, and 118 under each of the other seventeen.
• Key guarantee: 0 consistent pairs share no key.
• Keys: 2,718 rows moved, every one a pair holding a hyphen other than the hyphen-minus. No maiden name moved a key.
• Verdicts: only inconsistent → consistent, 501 (205 hyphen pairs, 296 maiden pairs). None moved to inconsistent.

• What the draw can see: 294 pairs with another hyphen (12 from jrc-names) and 236 with a maiden name on both sides.
• Harness control: the whole-chain run above (3,464 rows) reports 81 verdicts moving to inconsistent, so the zero here is real.
• The first round's figure (3,717 of 655,347) was taken on the earlier draw.

Docs

docs/design/decisions/name-matching.md:

• A dated 2026-11-11 entry. It carries the hyphen limit with its examples, the maiden departures stated as they are (mechanism, and whether each is new or was there at the merge base), and the whole-chain control in full.
• Head notes on the Should SmithJones match Smith-Jones, and LaRussa match La Russa? (both conflict today) #1261 entry (its Accepted bullet superseded in part), on the repr entry (its two Open bullets decided), and on the Should one table hold each role's matching rules? (six places decide how the family role compares today) #1260 entry (its "a family with bases" mutant superseded in part).
• Standing lines: the fold (scoped), part-of-other, a maiden line (with its departures), and joined.
• Open: names the family-name-of-initials question; no issue has been filed.

docs/matching.rst, the outcome table:

• folded: "...are folded away" → "...are folded away, and each hyphen the parser joins two names with (U+2010, the en dash and others) read as the hyphen-minus wherever the parser reads the name alike, which it does not for a credential joined by one (MD‐PhD)"
• joined: "stripped of spaces and hyphen-minus signs" → "stripped of spaces and hyphens"
• particles-aside: "the family names agree without their particles" → "the family names, or the maiden names, agree without their particles"
• part-of-other: "one family name's words are among the other's" → "one family or maiden name's words are among the other's"

No release-log bullet. Parser.matching() has not shipped.

Checks (head 4af97b2)

• uv run pytest: 45,436 passed, 38 skipped, 4 xfailed.
• uv run mypy, uv run ruff check: clean.
• sphinx-build -b doctest: 0 failures.
• sphinx-build -W -b html: no warnings.
• uv run pytest -n0 -m serial: not clean on this machine. The clock-timed scaling tests in test_benchmark.py fail at load averages of 27 to 53 from other sessions. They fail on the merge base too in the same minutes (a different set each run), and this PR touches no parser code. The frame-count guard passed. CI's runners are the judge here.

Timings, measured alternately with the merge base under load on 2026-11-11 and dated in the tests:

• The code-point fold test: 10–16 s against the merge base's 6–10 s.
• The shape grid: 17 s against 12 s.
• The hyphen test: about 3.3 s per parser.

Closes #1264

🤖 Generated with Claude Code