Record what the in-place merge requires, and a second empty-tokens case

Two documentation defects from the aliasing review, which otherwise
cleared the merge rewrite: ~1.1M instrumented parses with no assertion
firing, and byte-identical output against the pre-fix spelling over
8,036 names x 16 configs (all three name orders, middle_as_family,
both patronymic rules, custom delimiters, both locale packs, the
HumanName facade and the Constants shim) plus 120,375 names x 8
policies of targeted chain fuzz.

merge() now REQUIRES lo < hi, where the old spelling did not. Every
call site passes it, but with lo >= hi the slice assignment would
insert rather than replace, putting a second reference to pieces[lo]
into the array so the next merge extends the same list twice. Stated
at the call boundary rather than guarded: a silent no-op return would
hide a caller bug, and the constraint only matters to someone adding
a call site.

AmbiguityKind.UNBALANCED_DELIMITER called an empty token tuple a "rare
exception" for a character inside a masked region. Since content-free
input started keeping its diagnostics there is a second source, and it
covers the canonical example -- parse("(") reports with tokens=()
because no token survived. The docstring now admits both.

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

Author: derek73

nameparser/_pipeline/_group.py

@@ -129,6 +129,13 @@ def merge(lo: int, hi: int, add: Set[str] = frozenset(),
         # pieces[k] before a merge), so mutating is safe; verified
         # identical token/role/tag/span/ambiguity output over 54,877
         # names. tests/v2/test_benchmark.py's "and " shape is the guard.
+        #
+        # Every call site passes lo < hi, and this REQUIRES it: with
+        # lo >= hi the slice assignment would insert rather than
+        # replace, putting a second reference to pieces[lo] into the
+        # array, and the next merge to touch either index would extend
+        # the same list twice. The old rebuild-a-fresh-list spelling
+        # was harmless there. Keep the bound if you add a caller.
         combined = pieces[lo]
         for piece in pieces[lo + 1:hi]:
             combined.extend(piece)

nameparser/_types.py

@@ -259,9 +259,13 @@ class AmbiguityKind(StrEnum):
     PARTICLE_OR_GIVEN = "particle-or-given"
     #: A nickname/maiden delimiter opened without closing (or closed
     #: without opening); the text was kept as literal name content, so
-    #: the tokens are the one the stray character ended up inside. Rare
-    #: exception: a character that lands in no token at all (inside a
-    #: masked region) leaves the tuple empty.
+    #: the tokens are the one the stray character ended up inside.
+    #: Two cases leave that tuple empty: a character that lands in no
+    #: token at all (inside a masked region), and an input with no
+    #: alphanumeric content anywhere, which parses to an empty name --
+    #: the report survives because "was this malformed?" is the only
+    #: question left, but there is no token for it to point at.
+    #: ``parse("(")`` is the second case, not an exotic one.
     UNBALANCED_DELIMITER = "unbalanced-delimiter"
     #: More comma-separated segments than any recognized name shape;
     #: the parse is best-effort over the extra segments.