Tell the caller how to fix a subset violation

The message stated the constraint and left the remedy to be inferred:
"given_name_titles must be a subset of titles; not in titles: سيد".
Since adding to both fields is the only thing the caller can have
meant, the error should say so.

    given_name_titles marks a subset of titles; not in titles: سيد.
    Add them to titles as well — add(titles={...}, given_name_titles={...})

Considered auto-adding to the base field instead, and rejected it for
2.0: a typo in a marker field would silently mint new vocabulary
(add(given_name_titles={"profesor"}) inventing a title), the same
inference would have to extend to the other two marker pairs and to
remove()'s cascade, and the direction is one-way -- strict now can
relax in 2.1, loose now can never tighten. The message carries most of
the ergonomic benefit at none of that cost.

Parametrized over all three marker pairs, via constructor lambdas
rather than **kwargs: Lexicon's signature is heterogeneous
(capitalization_exceptions is pair-valued), so dynamic kwargs fail
mypy, and tests/ is type-checked here.

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

Author: derek73

nameparser/_lexicon.py

@@ -231,8 +231,10 @@ def __post_init__(self) -> None:
             orphans = getattr(self, marker) - getattr(self, base)
             if orphans:
                 raise ValueError(
-                    f"{marker} must be a subset of {base}; "
-                    f"not in {base}: {', '.join(sorted(orphans))}"
+                    f"{marker} marks a subset of {base}; "
+                    f"not in {base}: {', '.join(sorted(orphans))}. "
+                    f"Add them to {base} as well — "
+                    f"add({base}={{...}}, {marker}={{...}})"
                 )
 
     # -- constructors ----------------------------------------------------

tests/v2/test_lexicon.py

@@ -1,4 +1,5 @@
 import dataclasses
+from collections.abc import Callable
 
 import pytest
 
@@ -238,6 +239,21 @@ def test_given_name_titles_must_be_subset_of_titles() -> None:
         Lexicon(given_name_titles=frozenset({"sheikh"}))
 
 
+@pytest.mark.parametrize(("make", "base"), [
+    (lambda w: Lexicon(given_name_titles=w), "titles"),
+    (lambda w: Lexicon(particles_ambiguous=w), "particles"),
+    (lambda w: Lexicon(suffix_acronyms_ambiguous=w), "suffix_acronyms"),
+], ids=["given_name_titles", "particles_ambiguous", "suffix_acronyms_ambiguous"])
+def test_subset_error_names_the_fix(
+    make: Callable[[frozenset[str]], Lexicon], base: str
+) -> None:
+    # the constraint alone leaves the reader to infer the remedy; every
+    # marker field's error should name the base field to add to, since
+    # adding to both is the only thing the caller can have meant
+    with pytest.raises(ValueError, match=f"Add them to {base} as well"):
+        make(frozenset({"zzqnovel"}))
+
+
 def test_remove_orphaning_given_name_titles_raises() -> None:
     lex = Lexicon(titles=frozenset({"sheikh"}),
                   given_name_titles=frozenset({"sheikh"}))