Apply type-design review fixes to the pipeline state contract

The ParseState ownership map said roles belong to assign/post_rules
exclusively, but group writes maiden roles -- an ownership contract
wrong in one place teaches readers to distrust it everywhere. Fixed
the map, noted post-group segments staleness and the sole-producer
text invariant on WorkToken, documented PendingAmbiguity's dangling-
index tolerance and Parser's None-default resolution, made assemble's
role fallback say what it means, and pinned the whole ownership map
mechanically: a new test folds the case corpus stage by stage and
asserts each stage changes only the fields it owns.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: derek73

nameparser/_parser.py

@@ -26,7 +26,10 @@
 class Parser:
     """Immutable, thread-safe, picklable by construction (spec §4): all
     validity checking happens at construction; a Parser that constructs
-    successfully cannot fail at parse time on any str content."""
+    successfully cannot fail at parse time on any str content. The None
+    field defaults resolve in __post_init__; after construction both
+    fields are always non-None (the annotations state the steady-state
+    truth, hence the assignment ignores on the defaults)."""
 
     lexicon: Lexicon = None  # type: ignore[assignment]  # None -> default()
     policy: Policy = None  # type: ignore[assignment]    # None -> Policy()

nameparser/_pipeline/_assemble.py

@@ -23,7 +23,8 @@ def assemble(state: ParseState) -> ParsedName:
     for i, t in enumerate(state.tokens):
         if i in dropped:
             continue
-        final[i] = Token(t.text, t.span, t.role or Role.GIVEN, t.tags)
+        role = t.role if t.role is not None else Role.GIVEN
+        final[i] = Token(t.text, t.span, role, t.tags)
     ambiguities = tuple(
         Ambiguity(p.kind, p.detail,
                   tuple(final[i] for i in p.indices if i in final))

nameparser/_pipeline/_state.py

@@ -21,7 +21,9 @@
 @dataclass(frozen=True, slots=True)
 class WorkToken:
     """One tokenized word. role stays None until assign; extracted
-    nickname/maiden tokens arrive with their role pre-set."""
+    nickname/maiden tokens arrive with their role pre-set. text is
+    always the exact original slice (tokenize is the sole producer;
+    the anti-#100 invariant depends on it)."""
 
     text: str
     span: Span
@@ -53,8 +55,11 @@ class ParseState:
     dataclasses.replace. Fields are filled progressively:
     extract_delimited -> extracted/masked; tokenize -> tokens (span-
     sorted)/comma_offsets; segment -> segments/structure; classify ->
-    token tags; group -> pieces/dropped; assign/post_rules -> token
-    roles; ambiguities accumulate anywhere."""
+    token tags; group -> pieces/piece_tags/dropped AND maiden token
+    roles; assign/post_rules -> the remaining token roles; ambiguities
+    accumulate anywhere. Post-group, segments may retain indices of
+    dropped tokens -- assign iterates pieces, never segments. This
+    ownership map is pinned by tests/v2/pipeline/test_state.py."""
 
     original: str
     lexicon: Lexicon

tests/v2/pipeline/test_state.py

@@ -29,3 +29,39 @@ def test_state_is_frozen_and_replace_works() -> None:
 def test_worktoken_carries_optional_role() -> None:
     t = WorkToken("Jack", Span(6, 10), role=Role.NICKNAME)
     assert t.role is Role.NICKNAME
+
+
+def test_stage_field_ownership() -> None:
+    # The ParseState docstring's ownership map, pinned mechanically: run
+    # the whole case corpus through the fold stage by stage and assert
+    # each stage only changes the fields it owns. Converts the prose
+    # contract into a test (a future stage clobbering another stage's
+    # field fails here, not in a distant assertion).
+    import dataclasses as _dc
+
+    from nameparser import Lexicon as _Lexicon
+    from nameparser._pipeline import STAGES
+
+    from ..cases import CASES
+
+    ownership = {
+        "extract_delimited": {"extracted", "masked", "ambiguities"},
+        "tokenize": {"tokens", "comma_offsets"},
+        "segment": {"segments", "structure", "ambiguities"},
+        "classify": {"tokens"},
+        "group": {"tokens", "pieces", "piece_tags", "dropped"},
+        "assign": {"tokens", "ambiguities"},
+        "post_rules": {"tokens"},
+    }
+    assert {s.__name__ for s in STAGES} == set(ownership)
+    for case in CASES:
+        state = ParseState(original=case.text, lexicon=_Lexicon.default(),
+                           policy=case.policy or Policy())
+        for stage in STAGES:
+            before = {f.name: getattr(state, f.name)
+                      for f in _dc.fields(state)}
+            state = stage(state)
+            changed = {name for name, value in before.items()
+                       if getattr(state, name) != value}
+            assert changed <= ownership[stage.__name__], (
+                f"{case.id}: {stage.__name__} changed {changed - ownership[stage.__name__]}")