Count a listed surname spelling inside a compound surname (Smyth-Jones / Smith) - #1285

Closes #1262

A surname spelling listed in a lexicon now counts inside a compound surname, as it does for the whole word. With smyth added as a spelling of smith:

>>> lex = Lexicon.default().add("smyth", kind="family", same_as="smith")
>>> m = Parser(lexicon=lex).matching()
>>> m.check("Ann Smyth-Jones", "Ann Smith")["family"].outcome.value
'part-of-other'      # was 'conflict'
>>> m.check("Ann de Smyth", "Ann Smith")["family"].outcome.value
'particles-aside'    # was 'conflict'

Both outcomes are in the default accept set.

What changed in _match.py

The two family leniencies used to compare words by fold alone. Each now also accepts a listed spelling, read in the family group:

• particles-aside holds where the bases are equal once folded, or have as many words and each pair is equal or listed as one spelling.
• part-of-other holds where every word of one base (a hyphenated word by its halves) is among the other's, equal or listed. Covering just one word is not enough: Ann Smyth-Jones / Ann Smith-Brown still conflicts.

Each word's spelling set is built once per family comparison (_SpellingSets). That keeps the check near master's cost.

Two things are unchanged:

• Keys: they already cut every family word's and every hyphen half's spellings, so a pair this makes consistent shares a key.
• Group scoping: a given name's spelling still never counts inside a surname (Jack Wm-Lee / Jack William conflicts).

What moves under the shipped vocabulary

All 37 shipped surname spellings are particle spellings (el-→al-, mc→mac, ua→ó, binte→binti). A joined particle is set aside before either leniency compares, but an unjoined one stays in its base. So a family made only of particles now reads its listed spellings: Ann Mac / Ann de Mc goes from conflict to part-of-other.

Otherwise the change reaches only a caller's own surname spellings. Two tests hold it:

• test_a_listed_surname_spelling_counts_inside_a_compound_surname: its six leniency rows fail on master, and its conflict rows (two compound surnames sharing one word, two family-comma bases differing in one word, a surname listed as a particle) pass on both trees.
• test_listed_compound_surnames_keep_the_key_guarantee_and_symmetry: a grid of compound surnames under such a lexicon, checked under every setting.

Also

• test_match_diff.py's mutation test now finds the particles-aside step by its return line rather than by its condition's text, which this PR reworded twice.
• Docs: the decisions entry (2026-11-09 Should a listed surname spelling count inside a hyphenated or particle-led surname? (Smyth-Jones / Smith conflicts even with Smyth listed as Smith) #1262) and an amended Standing line in docs/design/decisions/name-matching.md, plus a sentence and a table row in docs/usage.rst.

Review

Four aspects ran on the first commit:

• code-reviewer: fuzzed 67k caller-lexicon pairs for symmetry and the key guarantee;
• pr-test-analyzer: 13 mutants, which found the subset rule, the multi-word base and the given-group test unguarded;
• comment-analyzer;
• design-docs-reviewer: found the particle-only family moves.

silent-failure-hunter and type-design-analyzer were skipped, since no validation, fallback or public type changed. The fix commits were re-reviewed. One problem predating this change came up: under across-roles, a particle-only family can match a maiden name and share no key. It reproduces on master and is drafted as a separate issue.

🤖 Generated with Claude Code