refactor(pipeline): piece-level predicates get their own module (#439) - #441

Closes #439.

Ten objects leave _group.py for a new nameparser/_pipeline/_pieces.py. No behavior change — the differential is byte-identical at every baseline, because no parse moves.

Why a new module rather than _vocab.py

The issue offered both. _vocab.py rules itself out in its own docstring:

Text-level tests used by more than one stage; token/piece-level predicates live with their stage. All take normalized-or-raw text explicitly — no state.

That contract is deliberate — is_wholly_suffix documents two explicit departures from it — so the piece layer gets its own module rather than bending the text layer's. The split is by what the question takes, which is what mechanisms.md#ONE-PREDICATE-PER-QUESTION states: _vocab answers how a word reads, _pieces how a piece reads.

What moved, and what didn't

Moved (10): _is_title_piece, _PERIOD_ABBREV, _is_leading_title, _leading_titles, _is_suffix_piece, _segment_holds_no_name, Peel, _peel_walk, _trailing_start, _peel_trailing — verbatim, comment blocks included, because the rules.md citations live in those comments and have to travel with the code they cite.

Stayed (group's own): _is_prefix_piece, _is_conj_piece, _is_rootname, _is_maiden_marker_piece.

_trailing_start travels with the peel even though only _peel_walk and _peel_trailing cross a stage boundary: decisions.md describes the S2 peel as those three together, and splitting a documented unit across modules to satisfy a usage rule would be worse than carrying one group-only function along.

_group imports back what it still uses. Nothing imports _pieces from below, so there is no cycle.

Three couplings the move had to carry

None of these are findable by grepping the function names, and each would have failed CI on its own:

1. rules.md H2, H3 and S2 name the module their citation sits in, and test_doc_citations asserts set equality against citing modules — so their implemented: lines move to _pieces.py.
2. test_regex_sync tracks _PERIOD_ABBREV by module path in three places: the import, the assertion, and the declared-copy roster.
3. test_layering iterates ALLOWED.items(), so a module absent from that dict is never checked at all. A new pipeline module escapes the layering contract silently.

On (3), _pieces.py is registered with a tighter contract than the generic stage allowance — _state and _vocab only — which makes the module docstring's claim executable rather than merely asserted. Verified non-vacuous: the entry rejects an added nameparser._render import on a scratch copy. (The first probe used _assign and only produced a circular-import error at collection, which proves the cycle but not the assertion; the acyclic probe is the one that shows the guard firing.)

And the gap itself is now closed, not just stepped around. Registering _pieces.py fixed one module and left the mechanism intact for the next, so test_every_pipeline_module_is_keyed_in_allowed asserts that every _pipeline/*.py is keyed. Scoped there because that is what the contract governs — package-wide, 16 of 45 modules are unkeyed (config/ vocabulary data, util.py, _version.py) and were never in scope.

It was latent rather than active: all 13 pipeline modules were keyed, so _pieces.py would have been the first to slip through. That measurement lives in the docstring rather than an assertion, because asserting the count is the constant-content pattern AGENTS.md forbids — it would fail on every legitimate new module.

Verified by unregistering _pieces.py on a scratch copy: the new test fails and test_layering_contract still passes — the silent gap, demonstrated.

Docs the move falsified

The same-PR amendment rule landing on text merged yesterday in #440. Both statements were true when written:

• _group's docstring said it houses the shared piece predicates and explained why.
• mechanisms.md#ONE-PREDICATE-PER-QUESTION said a piece-and-tag predicate goes to _group.

It goes to _pieces now; _group is where they collected before the module existed, which is the accumulation the entry describes rather than the destination it should recommend. The entry's Lives in also gains the layering test, since that is now where each module's contract is written down.

Deliberately not done

No renames. The moved names keep their leading underscore, though _vocab's convention would drop it for a shared module's public surface. That would touch ~60 call sites across three files and dilute a diff whose value is being a verifiable pure move — a follow-up if you want it.

Verification

_group.py goes from 1052 to 843 lines.

🤖 Generated with Claude Code