Document that an ambiguity records a decision, not a word

The constraint that shaped the two new emitters is not obvious from
either side, and ORDER is still reserved -- whoever wires it next needs
the rule, and users need to know why a name containing an ambiguous
word can report nothing.

Three places, each for its own audience:

- concepts.rst, in the Honest ambiguity essay: an empty ambiguities
  means the parse faced no fork, not that every word was unambiguous.
  Uses the two cases that surprised me -- 'do' mid-name in "Joao da
  Silva do Amaral de Souza", where nothing chooses, and "Ma, Jack",
  where the comma settles it before the question arises.
- AmbiguityKind's docstring, which is what modules.rst renders into the
  API reference: the same point in two sentences, for a reader who
  never opens the concepts page.
- AGENTS.md: the implementer rule. Emit at the decision site, never by
  scanning for a vocab:*-ambiguous tag; report both directions of a
  two-way fork; register a trigger in _AMBIGUITY_TRIGGERS and pin the
  kinds in the case table. Notes that the decision site already holds
  the token index and detail text a tag scan would have to rebuild.

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

Author: derek73

AGENTS.md

@@ -119,6 +119,7 @@ The 2.0 rewrite lands as underscore-private modules alongside the v1 code. These
 - **Canonical field order** — the seven roles in `Role` enum declaration order, defined once and derived everywhere (properties, `as_dict`, reprs, `comparison_key`). Never restate the order literally.
 - **Method organization**, fixed section order in every class: fields + `__post_init__` validation → alternative constructors → dunders (construction/equality → protocol → operators) → properties → public methods by concern (access → editing → comparison → rendering delegates) → private helpers last, except a helper serving exactly one section may sit at that section's head. Sanctioned deviation, facade layer only: `HumanName` and the shim `Constants` organize by v1 concern groups (`# -- render defaults --`, `# -- config / parsing --`, `# -- fields --`, ..., dunders and pickle last) — the classes mirror v1's own surface and die in 3.0; the canonical order still binds every core type.
 - **Validation is eager and fail-loud**: every `raise` states the offending value, the expected form, and the fix. Exception taxonomy: wrong type — including wrong element type inside a collection, bare `str` where an iterable of strings is expected, or a `Mapping` where a plain iterable is expected — raises `TypeError`; well-typed but unacceptable values raise `ValueError`; failed enum lookups stay `ValueError` for any input (stdlib `EnumType` precedent).
+- **Ambiguities are emitted at the DECISION site**: an `Ambiguity` records a fork the parse had to call, not a token that sits in an ambiguous vocabulary. Emit where the branch is taken — the trailing-suffix peel in `_assign`, the delimiter escape's follow-up in `classify` — never by scanning for a `vocab:*-ambiguous` tag. The same tagged token is a genuine fork in one position and unremarkable in another (`do` mid-name in "Joao da Silva do Amaral de Souza" chooses nothing), and structure often settles the question before it arises, which is why `PARTICLE_OR_GIVEN` is deliberately not emitted on the `FAMILY_COMMA` path and `SUFFIX_OR_FAMILY` is not emitted for "Ma, Jack". The decision site also has the token index and the detail text in hand, which the tag scan would have to reconstruct. Report BOTH directions of a two-way fork — "John Smith MA" (read as a suffix) and "Jack MA" (read as the family name) are equally guesses. Every kind needs a trigger in `tests/v2/test_contracts.py::_AMBIGUITY_TRIGGERS` (an explicit `None`, strict-xfail, while reserved), and case-table rows pin expected kinds exactly, so a new emitter shows up in both immediately.
 - **Invariants guard harm, not no-ops**: add a constructor check when violating it produces a *wrong parse*, not when it produces *nothing*. A false positive costs a working configuration; a true positive on an inert condition costs the user nothing, so that trade is never worth taking. `suffix_acronyms_ambiguous ∩ suffix_words` is guarded because the overlap loses a family name; `given_name_titles` is not, because an unreachable entry is simply never consulted (see Gotchas). Before adding one, construct the config it forbids and check what actually breaks.
 - **The shim TRANSLATES; it never raises on a config v1 accepted, and never silently changes the parse**: `Constants._snapshot()` is a translation boundary between v1's model and v2's invariants, and every transformation there carries its v1-reachability argument in a comment. Four exist today — `first_name_titles` re-folded per word (v1 joins-then-`lc`, v2 normalizes-then-joins), `suffix_acronyms_ambiguous ∩ acronyms` (a provable no-op), `suffix_words − ambiguous` (v1 already accepts the word via the acronym branch, so the addition is inert there), and `particles_ambiguous ∪ (bound ∩ particles)` (a pinned deviation, `test_bound_never_given_prefix_deviates_on_two_pieces`). When a v1 config cannot satisfy a v2 invariant, work out what v1 actually *does* with it — usually nothing — and reproduce that; weakening the invariant or letting the raise through are both wrong. **Test the case the translation decides**, not one where both branches agree: a test using an input v1 parses identically with and without the config pins nothing.
 - **Reprs are bounded**: render which fields deviate from a named baseline and by how much, never contents (`Lexicon(default + titles: +2)`).

docs/concepts.rst

@@ -154,6 +154,16 @@ other names, so the parse records a ``particle-or-given`` ambiguity
 alongside its answer. You can inspect ``ambiguities`` to decide, case
 by case, whether your data needs a second look.
 
+An ambiguity records a *decision*, not a word. The same token in a
+different position may present no fork at all: ``do`` is in the
+ambiguous post-nominal vocabulary, but in ``"Joao da Silva do Amaral
+de Souza"`` it sits mid-name, where nothing has to choose between
+readings — so nothing is recorded. A comma can settle the question
+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. An empty ``ambiguities`` means the parse faced no
+fork, not that every word in it was unambiguous.
+
 :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
 the name it belongs to — but only a handful of them are part of the

nameparser/_types.py

@@ -225,7 +225,13 @@ class AmbiguityKind(StrEnum):
     """The stable vocabulary of :class:`Ambiguity` kinds. A StrEnum:
     members ARE their string values, so ``kind == "particle-or-given"``
     compares directly. New kinds may be added in minor releases;
-    existing values never change meaning."""
+    existing values never change meaning.
+
+    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`` means the parse faced no fork, not that every word
+    was unambiguous."""
 
     #: Reserved: the name's field order itself is uncertain (e.g. a
     #: two-word name under a non-default name_order). Not yet emitted;