parse("Maria Kowalska z domu Nowak") cannot reach the Polish maiden marker — markers do not compose the way suffixes do

[derek73]

The Polish maiden marker "z domu" (lit. "of the house [of]") is two tokens, and unlike multi-word post-nominals it cannot be reached by adding its component words to the vocabulary.

parse("Maria Kowalska z domu Nowak")
# stock                          -> given='Maria', middle='Kowalska z domu', family='Nowak'
# + 'z','domu' in maiden_markers -> given='Maria', family='Kowalska', maiden='domu Nowak'

The first marker word is consumed as the marker and the second leaks into the maiden name.

Why this is not the same as multi-word suffixes

Adjacent suffix tokens are reassembled by a run predicate (is_wholly_suffix, nameparser/_pipeline/_vocab.py:246), which is why parse("John Smith, MD PhD").suffix is 'MD PhD' and why a two-word credential is reachable as its component words. Maiden markers have no equivalent — a marker matches one word and the extraction begins immediately after it.

So the multi-token question that #291 was carrying for markers does not dissolve the way it did for suffixes. It needs its own answer: either a marker run predicate, or an explicit decision that markers stay single-word and "z domu" stays out.

Provenance

Descoped from 2.0 (#274) and folded into #291 on 2026-07-27 as "pending the multi-token matching decision". #291 is closed as working-as-designed, so this carries the question forward. Recorded in docs/design/decisions.md under Excluded (MAIDEN_MARKERS), which should point here once this is decided.

Currently noted only in nameparser/config/maiden_markers.py's docstring.

[derek73]

Resolved as phrase entries, not a marker run predicate. Recording why, since this issue frames it as an open choice between the two.

The run predicate is the library's own former advice, and it is the defect. Until #448 the constructor warned multi-word entry 'z domu' can never match. Split it into separate entries. Measured on 2.2 before the change:

# z and domu added as separate entries — what the warning recommended
parse("Maria Kowalska z domu Nowak")   # maiden 'domu Nowak'      the leak this issue reports
parse("Anna z Nowak")                  # family '', maiden 'Nowak'

The second is the one that settles it. z is an ordinary Polish preposition and domu an ordinary noun; a mechanism that lets either claim anything alone loses the family name of any Pole whose name happens to contain one. That is the same collision criterion (decisions.md#vocabulary-collisions C-i) that took roz out of this very vocabulary a week earlier — asked at the phrase level instead of the word level, because a phrase changes the unit that claims rather than passing the old test with the old unit.

Two things found while implementing, both worth having here.

given_name_titles is the storage precedent — space-joined, per-word normalized — but not the matching one. Its run is identified per word first, because lt and col are each title vocabulary. Nothing can be identified first for z domu, so markers needed genuine multi-token lookahead rather than a reuse of the title mechanism.

And z domu is the first multi-word entry any shipped vocabulary set holds — given_name_titles included. That exception has existed since 2026-07-19 with no shipped member, exercised only through caller-configured vocabulary.

One caution for anyone adding a phrase of their own. Review found that a run could form across a bracket, quote or comma — classify walks the token stream while the piece walk sees a segment, which excludes tokens already claimed by an extracted clause. Jane Smith z (domu) Nowak lost its family name. Fixed in #448 by refusing to tag a run whose tokens are not structurally contiguous, so a phrase marker really is recognized only whole. The natural Spanish entry de soltera would have hit the same shape on a particle.

Fixed in #448.