Enforce the bound-given/never-given-particle invariant on Lexicon

nameparser/config/prefixes.py asserts two invariants on its own data:
NON_FIRST_NAME_PREFIXES stays a subset of PREFIXES, and stays disjoint
from BOUND_FIRST_NAMES. Only the first had a 2.0 counterpart --
particles_ambiguous <= particles is checked on every Lexicon, while the
disjointness rule guarded nameparser's shipped vocabulary and nothing a
caller supplied.

In 2.0's complement model the second reads as

    bound_given_names & particles <= particles_ambiguous

"a bound given name that is also a particle must be one that may start a
given name". A particle declared never-to-start-a-given-name cannot also
bind one; before this, the contradiction resolved by discarding the
never-given declaration at leading position, with no signal.

Note the import-time assert only protects the shipped data, and vanishes
under python -O. This check runs on every Lexicon.

v1 compatibility, as with given_name_titles: v1 has no runtime guard, so
a caller can add a never-given prefix to bound_first_names, and 1.4 then
lets the bound rule win -- "dos Santos Silva" parses first="dos Santos".
The shim reproduces that by promoting such a word to may-be-given rather
than raising on a config v1 accepted. Verified byte-identical to a live
1.4.0 for both the leading and non-leading positions, and pinned by
test_snapshot_keeps_a_bound_never_given_prefix_parseable -- the hole had
no coverage, since no existing test built that combination.

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

Author: derek73

nameparser/_config_shim.py

@@ -934,6 +934,8 @@ def _build_snapshot(self) -> tuple[Lexicon, Policy, _RenderDefaults]:
         from nameparser.config.maiden_markers import MAIDEN_MARKERS
         acronyms = frozenset(self.suffix_acronyms)
         titles = frozenset(self.titles)
+        particles = frozenset(self.prefixes)
+        bound = frozenset(self.bound_first_names)
         # keep in sync with _lexicon._default_lexicon() (pinned by the
         # default-Constants equality test in tests/v2/test_config_shim.py)
         lexicon = Lexicon(
@@ -953,13 +955,20 @@ def _build_snapshot(self) -> tuple[Lexicon, Policy, _RenderDefaults]:
             # ambiguous entry lingers (the entry simply stops mattering)
             suffix_acronyms_ambiguous=frozenset(
                 self.suffix_acronyms_ambiguous) & acronyms,
-            particles=frozenset(self.prefixes),
+            particles=particles,
             # complement translation: v1 marks the never-given subset;
-            # v2 marks the may-be-given subset
-            particles_ambiguous=frozenset(self.prefixes)
-            - frozenset(self.non_first_name_prefixes),
+            # v2 marks the may-be-given subset. The trailing union keeps
+            # a config v1 accepted: prefixes.py asserts its own data has
+            # no word in both non_first_name_prefixes and
+            # bound_first_names, but nothing stops a caller adding one at
+            # runtime, and v1 then lets the bound rule win (leading "dos
+            # Santos Silva" parses first="dos Santos"). Treating such a
+            # word as may-be-given reproduces that instead of raising.
+            particles_ambiguous=(
+                particles - frozenset(self.non_first_name_prefixes))
+            | (bound & particles),
             conjunctions=frozenset(self.conjunctions),
-            bound_given_names=frozenset(self.bound_first_names),
+            bound_given_names=bound,
             # v1 Constants has no manager for these (#274 is 2.0
             # behavior); the data module is the only source
             maiden_markers=frozenset(MAIDEN_MARKERS),

nameparser/_lexicon.py

@@ -236,6 +236,19 @@ def __post_init__(self) -> None:
                     f"Add them to {base} as well — "
                     f"add({base}={{...}}, {marker}={{...}})"
                 )
+        # The v2 form of prefixes.py's NON_FIRST_NAME_PREFIXES-disjoint-
+        # from-BOUND_FIRST_NAMES assertion. That module guards its own
+        # data at import; this guards vocabulary a caller supplies.
+        contradictory = (
+            self.bound_given_names & self.particles) - self.particles_ambiguous
+        if contradictory:
+            raise ValueError(
+                f"bound_given_names entries that are also particles must be "
+                f"in particles_ambiguous; not in particles_ambiguous: "
+                f"{', '.join(sorted(contradictory))}. A particle that never "
+                f"starts a given name cannot also bind one — add them to "
+                f"particles_ambiguous, or drop them from bound_given_names"
+            )
 
     # -- constructors ----------------------------------------------------
 

tests/v2/test_config_shim.py

@@ -6,7 +6,7 @@
 
 import pytest
 
-from nameparser import GIVEN_FIRST, Lexicon, PatronymicRule, Policy
+from nameparser import GIVEN_FIRST, HumanName, Lexicon, PatronymicRule, Policy
 from nameparser._config_shim import (
     CONSTANTS, Constants, SetManager, TupleManager, _DelimiterManager,
     _RegexesProxy, _cached_parser,
@@ -335,6 +335,22 @@ def test_v14_constants_blob_unpickles_into_shim() -> None:
     assert loaded.string_format == "{title} {first} {middle} {last} {suffix} ({nickname})"
 
 
+def test_snapshot_keeps_a_bound_never_given_prefix_parseable() -> None:
+    # prefixes.py asserts its own data keeps non_first_name_prefixes
+    # disjoint from bound_first_names, but nothing stops a v1 caller
+    # adding one at runtime, and 1.4 accepts it -- letting the bound
+    # rule win, so "dos Santos Silva" parses first="dos Santos".
+    # Lexicon rejects that combination, so the shim promotes such a word
+    # to may-be-given rather than raising on config v1 allowed.
+    c = Constants()
+    assert "dos" in c.non_first_name_prefixes      # baseline: never-given
+    c.bound_first_names.add("dos")
+    lexicon, _, _ = c._snapshot()                  # must not raise
+    assert "dos" in lexicon.particles_ambiguous
+    name = HumanName("dos Santos Silva", constants=c)
+    assert (name.first, name.last) == ("dos Santos", "Silva")
+
+
 def test_snapshot_field_translation() -> None:
     c = Constants()
     lexicon, policy, defaults = c._snapshot()

tests/v2/test_lexicon.py

@@ -254,6 +254,35 @@ def test_subset_error_names_the_fix(
         make(frozenset({"zzqnovel"}))
 
 
+def test_bound_given_name_that_is_a_particle_must_be_ambiguous() -> None:
+    # nameparser/config/prefixes.py asserts this on its own data:
+    # NON_FIRST_NAME_PREFIXES stays disjoint from BOUND_FIRST_NAMES. In
+    # 2.0's complement model that reads as bound_given_names & particles
+    # <= particles_ambiguous. A particle declared never-to-start-a-given-
+    # name cannot simultaneously bind one; without the check, one of the
+    # two contradictory declarations is silently discarded.
+    with pytest.raises(ValueError, match="particles_ambiguous"):
+        Lexicon(particles=frozenset({"dos"}),
+                particles_ambiguous=frozenset(),
+                bound_given_names=frozenset({"dos"}))
+
+
+def test_bound_given_name_may_overlap_an_ambiguous_particle() -> None:
+    # the shipped case: "abu" is both, and legitimately so
+    lex = Lexicon(particles=frozenset({"abu"}),
+                  particles_ambiguous=frozenset({"abu"}),
+                  bound_given_names=frozenset({"abu"}))
+    assert "abu" in lex.bound_given_names
+    # and a bound name that is not a particle at all is unconstrained
+    assert "abdul" in Lexicon(bound_given_names=frozenset({"abdul"})
+                              ).bound_given_names
+
+
+def test_default_lexicon_satisfies_the_bound_particle_invariant() -> None:
+    d = Lexicon.default()
+    assert not (d.bound_given_names & d.particles) - d.particles_ambiguous
+
+
 def test_remove_orphaning_given_name_titles_raises() -> None:
     lex = Lexicon(titles=frozenset({"sheikh"}),
                   given_name_titles=frozenset({"sheikh"}))