docs(mechanisms,cases,customize,differential): the fork criterion, measured

The VOCABULARY-EXERCISES-FORKS entry named four forks for
maiden_markers. Measured, the set has none: it is read at exactly two
sites, both plain whole-token membership after _normalize, and all
sixteen members collapse to one structural class across bare,
bracketed and lone-bracketed shapes with the marker text normalised
out. Two of the four named forks were not parser behavior at all --
the substring split is _carries, a test guard that deliberately asks
wider, and edge-period normalization is _normalize, which discriminates
spellings across every vocabulary rather than members of this one.

That makes the entry's argument stronger, and it now says so: rows on
this set earn their place on clause SHAPE, never on which member
appeared. The unit is the INPUT, matching cases.py's wording rather
than the entry's old "one member and not another"; a row plainly earns
its place with no member fork behind it.

Three repairs beyond that. The delimiter enumeration claimed
exhaustiveness and missed WORD_INTERNAL_DELIMITERS, which splits the
same-character class in two -- 'Jane Smith"' reports
UNBALANCED_DELIMITER and "Jane Smith'" reports nothing -- while
listing ASCII against fullwidth, which is not a fork: swapping the
pair across all 45 corpus names holding a paren changes no field and
no ambiguity kind. The entry blurred the line Derek drew, so it states
it: a delimiter pair the library SHIPS is caller-visible behavior and
deleting one reddens three tests, while vocabulary a caller configures
is data. And a row may earn its place a second way, with no fork
behind it, by pinning a name a release note advertises by name.

Its counts are gone rather than corrected. They were present-tense
prose over a drifting wordlist, which root AGENTS.md forbids, this PR
moved 17 to 16 by removing roz, and the descriptive figure was wrong
anyway -- five members carry rows, so eleven have none.

Two merge blockers. A cases.py note carried "leaves the entire suite
green" beside the correcting sentence that says the suite catches it;
the previous commit appended the truth and left the falsehood
standing. And neither recompute one-liner ran as pasted: both bodies
were indented inside the string handed to python -c, so both raised
IndentationError. I had run them flush-left in my own shell, which is
the inert-measurement shape they exist to prevent. Both are dedented,
carry a note saying why, and were re-run by reconstructing them from
the source and pasting.

The #445 marker went on the bracketed rules only. The bare spelling is
claimed at 1.4.0 by fix(#274), which also declares `family`, so a
"keep the family" fix would land inside it with the gate green -- the
same absorption on the same field at the same baseline. Marked there
too, with the names to re-measure listed.

Also: three ledger regexes gained (?i) in the previous commit without
being mentioned, a real widening (the class now matches NEE and NÉE)
bounded by _Claim's digest; customize.rst said suffix-shaped content
"is read as a suffix" when S1 drops the brackets and parses the
content as if written bare; _policy.py's autodoc'd docstring never got
that clarification; and a 63/9 count is replaced by its recompute
command, since 9 does not reproduce under its own definition.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: derek73

docs/customize.rst

@@ -298,11 +298,14 @@ listed below.
        no configuration since 2.2 is a clause that opens with a marker
        word AND has a word after it: ``"Jane Smith (née Jones)"`` reads
        maiden ``Jones`` whatever pair encloses it, unless the content is
-       suffix-shaped, which is read as a suffix ahead of both. A marker
-       word opening the enclosed content is dropped from the value
-       either way, but only where that content holds more than one
-       *token* — the same reason a lone ``"(Nee)"`` is a maiden name
-       rather than a marker. Tokens, not words: a marker written
+       suffix-shaped, which is taken ahead of both: the brackets are
+       dropped and the content parses as if written bare, so
+       ``"Jane Smith (née Jr.)"`` gives family ``née``, suffix ``Jr.``
+       rather than a suffix of the whole clause. A marker word opening
+       the enclosed content is dropped from the value either way, but
+       only where that content holds more than one *token* — the same
+       reason a lone ``"(Nee)"`` listed here keeps ``Nee`` as the
+       maiden value rather than reading it as a marker. Tokens, not words: a marker written
        against the name it marks is one token with them, so
        ``"山田花子（旧姓佐藤）"`` keeps its ``旧姓``. Defaults to empty —
        see the routing example below.
@@ -506,8 +509,11 @@ Nicknames, maiden names, and brackets
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 A delimiter pair carries no meaning of its own, so what a clause reads
-as is settled in steps. Suffix-shaped content is taken first and reads
-as a suffix. Then the content is asked whether it announces itself: a
+as is settled in steps. Suffix-shaped content is taken first: the
+brackets are dropped and what was inside parses as if it had been
+written bare, which is not the same as the clause becoming the suffix
+(``"Jane Smith (née Jr.)"`` gives family ``née``, suffix ``Jr.``).
+Then the content is asked whether it announces itself: a
 clause opening with a recognized maiden marker and carrying a word
 after it is a maiden name whatever encloses it, and needs nothing
 configured. Only for what is left — markerless content, and a lone

docs/design/mechanisms.md

@@ -141,7 +141,21 @@ Contract statement. A user-supplied pattern is rejected as over-matching by prob
 
 ### VOCABULARY-EXERCISES-FORKS — pin the branch, not the wordlist
 
-Contract statement. A vocabulary set is data; the code that reads it is what has behavior, so a case row earns its place by exercising a FORK — a branch the parser takes for one member and not another — never by covering a member. Sixteen maiden markers are not sixteen behaviors: født, fødd and född are one class, and a row for each pins nothing the first does not. It follows that "N of M entries have no test" is not a finding; it reads as one because it carries a number. The finding is "this fork has no test", and the forks are findable by reading the code that consults the set and enumerating the branches it takes — for maiden markers, the substring-versus-token split (ASCII against not), the edge-period normalization that makes geb. and geb one word, the native-script whole-token case that cannot collide with Latin text, and a member borne as an ordinary name (decisions.md#vocabulary-collisions). Four classes, four rows; the other twelve entries are data. The same reduction applies to the delimiter pairs, where the forks are same-character against distinct-character open and close (N2) and ASCII against fullwidth, not eleven pairs. Coverage measured against a wordlist grows with every entry added and narrows nothing, which is the tell: a criterion that inflates with the data is measuring the data.
+Contract statement. A vocabulary set a caller configures is data; the code that reads it is what has behavior, so a case row earns its place by exercising a FORK — a branch the parser takes for one INPUT and not another — never by covering one more member. The unit is the input, not the member, because most forks are keyed on the shape of the surrounding name rather than on which word appeared. Find them by reading the sites that consult the set and enumerating the branches they take, and expect that enumeration to come back empty: `maiden_markers` is read at exactly two sites (`_classify.py`'s tagging and `_extract.py`'s `_maiden_marked`), both plain whole-token membership after `_normalize`, and every shipped member parses to one structural class in bare, bracketed and lone-bracketed shapes with the marker text normalised out — zero member forks. What earns the maiden rows is clause SHAPE: marker first against marker later, a word after the marker against none, a marker a separator divides from the name against one glued to it. Two adjacent things are NOT forks of this set and do not want rows: the substring-versus-token split is `_carries` in test_ledger_guards.py, a test guard deliberately asking a wider question than the parser (tools/differential/README.md says so), and edge-period normalization lives in `_lexicon._normalize`, applying to every token of every vocabulary, so it discriminates spellings rather than members. Only "a member borne as an ordinary name" is member-keyed (decisions.md#vocabulary-collisions), and it has its own rows. The reduction does NOT carry across to delimiter pairs, and the difference is the line to hold: a pair the library SHIPS is caller-visible behavior, and vocabulary a caller configures is data — deleting `("«", "»")` from the defaults reddens three tests, so cases.py's one-row-per-shipped-pair convention is load-bearing and this criterion is not permission to delete those rows. Within the pairs the code does fork, on whether open and close are the same character (N2) and again inside that class, where `WORD_INTERNAL_DELIMITERS` carves the apostrophe out: `Jane Smith"` reports UNBALANCED_DELIMITER and `Jane Smith'` reports nothing. ASCII against fullwidth is not one of them — swapping `( )` for `（ ）` across every corpus name holding a paren changes no field and no ambiguity kind. A row may also earn its place a second way, with no fork behind it: pinning a name a release note advertises BY NAME, which is a promise to a reader rather than a branch in the parser. It follows that "N of M entries have no test" is not a finding; it reads as one because it carries a number, and it inflates with every entry added, which is the tell that it measures the data. The finding is "this fork has no test". State the argument without present-tense counts over a drifting wordlist — see docs/design/AGENTS.md — and where a count is genuinely wanted, ship the one-liner instead:
+
+```
+uv run python -c "
+from nameparser import parse
+from nameparser.config.maiden_markers import MAIDEN_MARKERS
+shapes = ['Jane Smith {m} Jones', 'Jane Smith ({m} Jones)', 'Jane Smith ({m})']
+cls = {}
+for m in sorted(MAIDEN_MARKERS):
+    sig = tuple(tuple((f, (getattr(parse(s.format(m=m)), f) or '').replace(m, '<M>'))
+                      for f in ('given', 'middle', 'family', 'suffix', 'nickname', 'maiden'))
+                for s in shapes)
+    cls.setdefault(sig, []).append(m)
+print(len(MAIDEN_MARKERS), 'members ->', len(cls), 'structural classes')"
+```
 
 ### FORCE-A-DECISION-TABLE — no silent defaults on growth
 

nameparser/_pipeline/_extract.py

@@ -234,10 +234,10 @@ def extract_delimited(state: ParseState) -> ParseState:
                 # role that is not NICKNAME is already MAIDEN and the
                 # assignment would be a no-op either way. It is kept
                 # for the day `order` gains a third bucket, when it
-                # becomes the
-                # difference between M3 claiming that bucket's clauses
-                # and leaving them. Measured 2026-08-26: dropping it
-                # leaves the suite and all three gates green.
+                # becomes the difference between M3 claiming that
+                # bucket's clauses and leaving them. Measured
+                # 2026-08-26: dropping it leaves the suite and all
+                # three gates green.
                 if (role is Role.NICKNAME and _maiden_marked(
                         text[inner.start:inner.end], state.lexicon)):
                     role = Role.MAIDEN

nameparser/_policy.py

@@ -623,9 +623,17 @@ class Policy:
     #: field instead; a pair listed here is dropped from the effective
     #: nickname set (maiden wins, see __post_init__), so
     #: maiden_delimiters=frozenset({("(", ")")}) is the whole recipe (#274).
-    #: A maiden_markers word opening the enclosed content is dropped
-    #: from the value, but only where that content holds more than one
-    #: token: a lone "(Nee)" is a maiden NAME, not a marker (#329).
+    #: Set this for a clause that says nothing about itself, which is
+    #: two kinds and not one: content with no marker word in it, and a
+    #: LONE marker word. Since #335 a clause that opens with a marker
+    #: word AND has a word after it reads as the maiden name whatever
+    #: pair encloses it, so "Jane Smith (née Jones)" needs no
+    #: configuration -- unless the content is suffix-shaped, which is
+    #: taken first, the brackets dropped and the content read as if
+    #: written bare. A maiden_markers word opening the enclosed
+    #: content is dropped from the value, but only where that content
+    #: holds more than one token: a lone "(Nee)" is a maiden NAME,
+    #: not a marker (#329).
     maiden_delimiters: frozenset[tuple[str, str]] = frozenset()
     #: Additional separators that split suffix groups (e.g. " - " for
     #: "Jane Smith, RN - CRNA"). Additive only: the comma always

tests/v2/cases.py

@@ -24,7 +24,11 @@
 a policy that changes the answer. A row demonstrating one more member
 of a vocabulary set pins nothing its other members do not, and one row
 per entry grows this table without narrowing what can break
-(mechanisms.md#VOCABULARY-EXERCISES-FORKS).
+(mechanisms.md#VOCABULARY-EXERCISES-FORKS -- a restatement, and
+nothing checks it against the entry: test_doc_citations verifies an
+excerpt only where the reference is followed by a colon and a quoted
+span, which running prose like this one is not. Read the entry, not
+this paragraph, if the two ever disagree).
 """
 from __future__ import annotations
 
@@ -1383,10 +1387,14 @@ def __post_init__(self) -> None:
                "The empty family is the bare path's, not this "
                "change's: 'Smith née Jones' reads given 'Smith', "
                "family '' on 2.1.0 too, and 1.4.0 read first 'Smith' / "
-               "middle 'née' / last 'Jones' -- the marker as a middle "
-               "name, which is why the sibling fix(#410) rule at 1.4.0 "
-               "declares `middle`. The given side has agreed since "
-               "1.4.0, "
+               "middle 'née' / last 'Jones' -- the marker as a "
+               "middle name. The parallel evidence at 1.4.0 is not "
+               "the fix(#410) maiden-flavor rule, which is keyed on "
+               "the TITLED 'Dr. Smith née Jones', but fix(#274), "
+               "which claims the bare one-word names 'Janey née "
+               "Jones' and 'abd née Jones' and declares `family` for "
+               "exactly the reason this row records. The given side "
+               "has agreed since 1.4.0, "
                "the emptying is 2.x's and is tracked separately as the "
                "#410 analogue. What #335 moves is only the bracketed "
                "spelling: 1.4.0, 2.0.0 and 2.1.0 all read it family "
@@ -1405,11 +1413,16 @@ def __post_init__(self) -> None:
                "the parenthesis, and the fullwidth pair below -- and "
                "the other EIGHT have no row. Measured 2026-08-26 by "
                "disabling the swap one pair at a time: those three "
-               "redden and the eight do not. So this row and the "
-               "fullwidth one fence two ends of the set rather than "
-               "the whole of it; a set-level roster is what would "
-               "cover the rest. 1.4.0 and 2.1.0 both read nickname "
-               "'née Jones'"),
+               "redden and the eight do not. That is a count over a "
+               "wordlist, so read it the way "
+               "mechanisms.md#VOCABULARY-EXERCISES-FORKS says to: the "
+               "eight are not eight gaps, since the pairs fork on "
+               "whether open and close are the same character and on "
+               "the apostrophe carve-out inside that, not on which "
+               "pair. This row is here because a quote pair is the "
+               "same-character branch, and because the release note "
+               "advertises the spelling. 1.4.0 and 2.1.0 both read "
+               "nickname 'née Jones'"),
     Case("maiden_marked_clause_takes_the_suffix_reading_from_s1",
          "Jane Smith (née Jr.)",
          {"given": "Jane", "middle": "Smith", "family": "née",
@@ -1678,15 +1691,14 @@ def __post_init__(self) -> None:
          classification="feat(#273) + fix(#271) + fix(#335)",
          notes="the row above without its policy, and the one "
                "that fences M3 across the delimiter SET rather "
-               "than at the parenthesis: gating the swap to '(' "
-               "and the double quote leaves the entire suite "
-               "green and even the 2.1.0 gate green, its "
-               "fix(#335) rule quietly falling from six names to "
-               "five, and the 1.4.0 and 2.0.0 gates going red while "
-               "2.1.0 stays green (measured 2026-08-26; the 2.0.0 "
-               "ledger gives this name a four-field rule of its own, "
-               "which is what catches it there). The suite catches it "
-               "too, at this row. The fullwidth pair is the "
+               "than at the parenthesis. Measured 2026-08-26 by "
+               "gating the swap to '(' and the double quote: this row "
+               "and its facade twin are the only two failures in the "
+               "suite, and of the gates only 1.4.0 and 2.0.0 redden "
+               "-- 2.1.0 stays green with its fix(#335) rule quietly "
+               "falling from six names to five, while the 2.0.0 "
+               "ledger catches it on the four-field rule it gives "
+               "this name. The fullwidth pair is the "
                "one the maiden_markers docstring and the 2.2 "
                "release note both advertise as newly working "
                "without configuration, so it is the one that "

tests/v2/test_ledger_guards.py

@@ -1124,19 +1124,19 @@ def _carries(name: str, vocabulary: frozenset[str]) -> bool:
     does not rest on a substring. Both figures quantify over the
     corpus and go stale on any row added to it, so recount rather than
     adjust:
-        uv run python -c "
-        import glob, json
-        from nameparser import DEFAULT_NICKNAME_DELIMITERS as D
-        from nameparser.config.maiden_markers import MAIDEN_MARKERS as V
-        from nameparser._lexicon import _normalize
-        names = {json.loads(l) for f in glob.glob('tools/differential/corpus*.jsonl')
-                 for l in open(f, encoding='utf-8') if l.strip()}
-        strip = ''.join({c for p in D for c in p})
-        sub = lambda n: any(e in n for e in V if not e.isascii())
-        print(sum(not {_normalize(t.strip(strip)) for t in n.split()} & V
-                  and sub(n) for n in names),
-              sum(not {_normalize(t) for t in n.split()} & V
-                  and sub(n) for n in names))"
+    The body must sit flush left: `python -c` compiles it as a module,
+    so an indented first line raises IndentationError on paste.
+
+uv run python -c "
+import glob, json
+from nameparser import DEFAULT_NICKNAME_DELIMITERS as D
+from nameparser.config.maiden_markers import MAIDEN_MARKERS as V
+from nameparser._lexicon import _normalize
+names = {json.loads(l) for f in glob.glob('tools/differential/corpus*.jsonl') for l in open(f, encoding='utf-8') if l.strip()}
+strip = ''.join({c for p in D for c in p})
+sub = lambda n: any(e in n for e in V if not e.isascii())
+print(sum(not {_normalize(t.strip(strip)) for t in n.split()} & V and sub(n) for n in names),
+      sum(not {_normalize(t) for t in n.split()} & V and sub(n) for n in names))"
     Tighten this before admitting a vocabulary whose short non-ASCII
     entries occur inside ordinary names.
 

tests/v2/test_parser.py

@@ -1330,19 +1330,19 @@ def _clause_free_latin_corpus_names() -> list[str]:
     # Every count in this comment quantifies over the corpus, so one
     # added corpus row falsifies it silently. Recount rather than
     # adjust:
-    #     uv run python -c "
-    #     import re, sys; sys.path.insert(0, 'tests')
-    #     from nameparser import DEFAULT_NICKNAME_DELIMITERS as D
-    #     from nameparser.config.maiden_markers import MAIDEN_MARKERS as M
-    #     from v2._differential_fixtures import _CORPUS_NAMES
-    #     base = [n for n in _CORPUS_NAMES
-    #             if re.match(r'^[\x00-\u024f]*$', n) and ',' not in n]
-    #     strip = ''.join({c for p in D for c in p}) + '.'
-    #     keep = lambda f: [n for n in base
-    #                       if not any(f(w) in M for w in n.split())]
-    #     old = keep(lambda w: w.lower().rstrip('.'))
-    #     new = keep(lambda w: w.lower().strip(strip))
-    #     print(len(old), len(new), sorted(set(old) - set(new)))"
+    # The body must sit flush left: `python -c` compiles it as a module,
+    # so an indented first line raises IndentationError on paste.
+    # uv run python -c "
+    # import re, sys; sys.path.insert(0, 'tests')
+    # from nameparser import DEFAULT_NICKNAME_DELIMITERS as D
+    # from nameparser.config.maiden_markers import MAIDEN_MARKERS as M
+    # from v2._differential_fixtures import _CORPUS_NAMES
+    # base = [n for n in _CORPUS_NAMES if re.match(r'^[\x00-\u024f]*$', n) and ',' not in n]
+    # strip = ''.join({c for p in D for c in p}) + '.'
+    # keep = lambda f: [n for n in base if not any(f(w) in M for w in n.split())]
+    # old = keep(lambda w: w.lower().rstrip('.'))
+    # new = keep(lambda w: w.lower().strip(strip))
+    # print(len(old), len(new), sorted(set(old) - set(new)))"
     #
     # Delimiter characters come from the shipped set rather than a
     # literal, so a pair added there cannot quietly reopen this.

tools/differential/README.md

@@ -424,9 +424,9 @@ Those two numbers count WHOLE TOKENS, delimiters stripped. The strip
 is what earns exactly one of the four: `nee`, which appears in the
 corpora only inside brackets -- `Jane Smith (Nee)` and
 `Jane Smith (Nee) (Jones)` -- where the token carries them until they
-come off. `née` needs no strip, appearing
-bare in thirty-odd names, and `né` is not counted at all -- it occurs
-only as a substring of `née`, never as a token. The convention matters because the neighbouring guard
+come off. `née` needs no strip, appearing bare in many names, and `né`
+is not counted at all: it occurs only as a substring of `née`, never
+as a token. The convention matters because the neighbouring guard
 `tests/v2/test_ledger_guards.py::_carries` deliberately asks a wider
 question -- it also matches a non-ASCII entry anywhere inside a name,
 since 旧姓 is written flush against the name it marks -- and under that