Give each SUFFIX_OR_NAME branch its own detail, and stop over-claiming

Two findings from the review.

The kind has one name and two causes, and they were sharing one
template. The acronym branch turns on whether periods are written; the
numeral branch turns on the letter being a numeral at all. Sharing the
first produced:

    'V' written without periods is both a post-nominal and an ordinary
    name; read as a suffix rather than a name part

"written without periods" is the MA/M.A. distinction, which does not
exist for V, and the flattened "a name part" hid that the declined
reading is specifically a middle initial. The kind's own docstring says
detail names what was declined; it could not even tell you which branch
fired. Each branch now writes its own.

And the documented claim is narrowed, for the second time. The review
found a THIRD silent site for the roman-numeral fork -- the
SUFFIX_COMMA tail, decided in _segment by is_suffix_lenient and stamped
in _assign's blanket tail loop, so it is neither of the two comma
exceptions already documented. "John Smith, V" reports nothing.

Rather than chase coverage a third time, the claim no longer depends on
it. It said an empty tuple means "none of the forks listed here came
up", which is only true if every listed kind is emitted everywhere its
fork occurs -- a property I cannot verify and have now been wrong about
twice. It now says reporting is deliberately partial, names the comma
paths as the known quiet ones, and states the only thing that holds
regardless: a non-empty tuple is a signal, an empty one is not a
guarantee.

Verified: corpus 486 names, 2 intentional diffs, 0 unexplained.

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

Author: derek73

docs/concepts.rst

@@ -163,13 +163,13 @@ before it arises, too: ``"Ma, Jack"`` fixes the family name, so the
 credential reading never comes up, while ``"John Smith MA"`` has to
 call it and says so.
 
-So an empty ``ambiguities`` does not mean every word was unambiguous —
-it means none of the forks the parser *reports on* came up. The kinds
-it reports are listed in :class:`~nameparser.AmbiguityKind`, and they
-are the ones where both readings are genuinely common in real names.
-Coverage grows over releases; a name that reports nothing today may
-report something later, so treat a non-empty ``ambiguities`` as a
-signal worth acting on rather than an empty one as a guarantee.
+An empty ``ambiguities`` is therefore not a certificate of certainty.
+Reporting is deliberately partial: :class:`~nameparser.AmbiguityKind`
+lists the forks worth flagging, and even those are not reported
+everywhere they occur — the comma paths stay quiet on purpose, since a
+comma usually settles the structure before the question arises.
+Coverage grows over releases. Treat a non-empty ``ambiguities`` as a
+signal to act on; do not read an empty one as a guarantee.
 
 :class:`Tokens <nameparser.Token>` also carry tags — a second, independent label alongside their
 role, recording how a token was classified rather than what part of

nameparser/_pipeline/_assign.py

@@ -129,7 +129,10 @@ def _assign_main(seg_idx: int, state: ParseState,
     # overwrites. The role each ends up with is read back after
     # assignment, since which role "not peeled" means depends on
     # name_order.
-    ambiguous_picks: list[tuple[int, ...]] = []
+    # (piece, cause) -- one kind, two causes, and they need different
+    # wording: the acronym branch turns on whether periods are written,
+    # the numeral branch on the letter being a numeral at all
+    ambiguous_picks: list[tuple[tuple[int, ...], str]] = []
     k = len(rest)
     while k > 0:
         piece = pieces[rest[k - 1]]
@@ -143,7 +146,7 @@ def _assign_main(seg_idx: int, state: ParseState,
             # a trailing single letter is a name part unless it happens
             # to be a roman numeral -- and V/X/I are ordinary middle
             # initials, so taking it as a suffix is a call, not a fact
-            ambiguous_picks.append(piece)
+            ambiguous_picks.append((piece, "numeral"))
             k -= 1
             continue
         # A bare ambiguous acronym ("MA", not "M.A.") is a credential
@@ -158,15 +161,15 @@ def _assign_main(seg_idx: int, state: ParseState,
         bare_ambiguous = (len(piece) == 1
                           and "vocab:suffix-ambiguous" in tokens[piece[0]].tags)
         if bare_ambiguous and k - 1 >= 2:
-            ambiguous_picks.append(piece)
+            ambiguous_picks.append((piece, "acronym"))
             k -= 1
             continue
         if bare_ambiguous and k >= 2:
             # not peeled, so it stays the last NAME piece -- which role
             # that is depends on name_order, so the detail reads it back
             # below. (k < 2 means it is the only piece left, which is
             # not the fork this reports.)
-            ambiguous_picks.append(piece)
+            ambiguous_picks.append((piece, "acronym"))
         break
     name_pieces, suffix_pieces = rest[:k], rest[k:]
     if not name_pieces and suffix_pieces:
@@ -177,20 +180,26 @@ def _assign_main(seg_idx: int, state: ParseState,
         _set_roles(tokens, pieces[piece_idx], roles[pos])
     for piece_idx in suffix_pieces:
         _set_roles(tokens, pieces[piece_idx], Role.SUFFIX)
-    for piece in ambiguous_picks:
+    for piece, cause in ambiguous_picks:
         token = tokens[piece[0]]
         # every pick was assigned a role just above; the fallback only
         # keeps the wording sane if a future path reports before then
         role = token.role.value if token.role is not None else "name"
-        taken, declined = (
-            ("a suffix", "a name part") if token.role is Role.SUFFIX
-            else (f"a {role} name", "a post-nominal"))
+        if cause == "numeral":
+            detail = (
+                f"{token.text!r} is a roman numeral, so it reads as a "
+                f"generational suffix; any other single letter there "
+                f"would be a middle initial")
+        else:
+            taken, declined = (
+                ("a suffix", "a name part") if token.role is Role.SUFFIX
+                else (f"a {role} name", "a post-nominal"))
+            detail = (
+                f"{token.text!r} written without periods is both a "
+                f"post-nominal and an ordinary name; read as {taken} "
+                f"rather than {declined}")
         ambiguities.append(PendingAmbiguity(
-            AmbiguityKind.SUFFIX_OR_NAME,
-            f"{token.text!r} written without periods is both a "
-            f"post-nominal and an ordinary name; read as {taken} "
-            f"rather than {declined}",
-            tuple(piece)))
+            AmbiguityKind.SUFFIX_OR_NAME, detail, tuple(piece)))
     # leading ambiguous particle read as a name (#121 surfaced)
     if name_pieces:
         head = pieces[name_pieces[0]]

nameparser/_types.py

@@ -229,11 +229,11 @@ class AmbiguityKind(StrEnum):
 
     A kind names a FORK THE PARSE HAD TO CALL, not a word that could be
     read two ways: the same token elsewhere in a name may present no
-    choice at all and is then reported by nothing. An empty
-    ``ambiguities`` therefore means none of the forks listed here came
-    up -- not that the parse was certain of everything. Coverage grows
-    over releases, so a non-empty tuple is a signal to act on; an empty
-    one is not a guarantee."""
+    choice at all and is then reported by nothing. Reporting is also
+    partial -- a kind listed here is not necessarily emitted everywhere
+    its fork occurs (the comma paths stay quiet by design), and coverage
+    grows over releases. A non-empty tuple is a signal to act on; an
+    empty one is not a guarantee of certainty."""
 
     #: Reserved: the name's field order itself is uncertain (e.g. a
     #: two-word name under a non-default name_order). Not yet emitted;

tests/v2/test_parser.py

@@ -298,3 +298,16 @@ def test_chained_particle_detail_does_not_claim_a_role() -> None:
     assert n.given == "Van Johnson"
     (amb,) = n.ambiguities
     assert "family name" not in amb.detail
+
+
+def test_each_suffix_or_name_branch_describes_itself() -> None:
+    # one kind, two causes: the acronym branch turns on periods, the
+    # roman-numeral branch turns on the letter being a numeral. Sharing
+    # one template made "V written without periods" -- a distinction
+    # that does not exist for V -- and hid which branch fired.
+    acronym = parse("John Smith MA").ambiguities[0].detail
+    assert "periods" in acronym and "post-nominal" in acronym
+
+    numeral = parse("John Smith V").ambiguities[0].detail
+    assert "periods" not in numeral
+    assert "numeral" in numeral and "initial" in numeral