fix(group): a suffix never begins a name (#371)

[derek73]

A name that opens with a spaced Ph. D. stops losing its surname.

Closes #371

The defect

parse("Ph. D. Van Johnson")   given 'Van Johnson'   family ''   suffix 'Ph. D.'
                          →   title 'Ph.'   given 'D.'   family 'Van Johnson'

The rule

A suffix never opens the string: position outranks the vocabulary match. rules.md#S2 states it.

The v1 fix_phd merge — which heals a split Ph./D. into one credential — was applied wherever the pair stood, and that is what made a leading credential possible at all. Every other suffix-shaped word standing first already falls out correctly (Jr., MD, Esq., Sr. as titles; PhD, III as name words), via TITLES membership or H2's abbreviation clause. A reviewer swept all 650 one-word suffix-vocabulary entries at the head of two tails — 8,612 parses — and none yields a suffix. The Ph./D. pair is the only shape that reaches the defect.

Everything else is untouched: the merge still heals a trailing credential, and a family comma still opens a listing rather than a name.

John Smith Ph. D.    suffix 'Ph. D.'          Smith, Ph. D. Jr.    suffix 'Ph. D. Jr.'
Ph. D., John         family 'Ph. D.'          II Van Johnson       family 'Van Johnson'

"The head" means the head of the STRING, and review found both ways to get that wrong

The first draft tested the piece index. extract_delimited removes a quoted or bracketed clause before grouping, so "Bob" Ph. D. John Smith reached the merge with the pair at k == 0 and a word standing before it in the input. v1 merges there — its regex \s(ph\.?\s+d\.?) needed only a preceding space — and declining broke parity on 112 measured names, every one opening with a quote or bracket, and not one of them in any corpus. The test is now the token index, which is v1's boundary exactly.

The other direction cannot be fixed here, and finding out why settled the design. A leading title is a piece, so Sir Ph. D. Van Johnson keeps the credential and the empty family — #371's own symptom one word to the left. That is 1.4.0's reading, and the principled alternative does not exist: "the first piece of the name" is not computable before this merge, because H2's abbreviation test is true of Ph. itself, so a scan stepping over titles would step over the very piece being judged. rules.md#S2 therefore says opens the string, with the title case pinned as an Accepted boundary rather than left as an unmarked counterexample.

Parity with 1.4.0, stated precisely

Three of the four corpus names of this shape return to their v1 reading exactly:

	1.4.0	this branch
Ph. D. Van Johnson	title Ph., first D., last Van Johnson	identical
Ph. D. John Smith	+ middle John, last Smith	identical
Ph. D.	title Ph., last D.	identical
Ph. D., Jr.	title Ph., first D., suffix Jr.	family D. — not restored

The fourth moves the D. from given to family, two roles apart, and its residual diff rides under fix(comma-precomma-family), which predates this change.

So what shipped in 2.0 was a regression from applying the merge unconditionally. expected_since_1.4.0.toml loses its fix(leading-credential) rule; 2.0.0 and 2.1.0 each gain one claiming the same four names, five roles and the same digest.

Read the diagnosis, not the error. The gate reported that rule SHADOWED, not reverted — compare.py separates the two "because they have three different fixes", and #426 is the precedent for dropping a shadowed rule. An earlier draft of this PR generalised EXPLAINED NOTHING into "how a parity restoration announces itself", which would teach the next maintainer to delete a shadowed rule whose behaviour is still diverging.

Review

Four agents; two regressions found, both mine, both above. Nine further findings, all fixed. Three worth naming:

• The guard test this PR narrowed was left vacuous. Removing the Ph. D. witness left II Van Johnson alone — and II is not suffix vocabulary under that file's reduced lexicon, so the test passed under the exact mutation it is named for. PhD is the replacement witness; the mutation is killed again.
• Every characterisation I wrote of v1 was wrong. "Healed the pair only when it TRAILS" is false in both directions, in four files — v1 healed it everywhere except the head, and reading that sentence as the contract would license narrowing the merge and silently changing John Ph. D. Smith.
• Two live references to the rule this PR deletes remained in the same ledger; acting on them takes the gate red, since the (?!\s*ph\.) carve-out is what lets Ph. D., Jr. reach its own rule.

Also added: Case rows for Ph. D. Van Johnson (the issue's subject, whose empty fields are the symptom — test_case asserts the whole dict) and the bare Ph. D., neither of which had a pin outside an out-of-band tool run.

Verification

• 6171 → 6186 passed; mypy, ruff and 232 sphinx doctests clean.
• Gate green at 1.4.0 / 2.0.0 / 2.1.0, unexplained: 0.
• Four mutations verified, including both shipped defects the review found and the repaired guard.

One check is red

build (3.12) fails test_facade_thousand_names_under_a_second at 1.06–1.08s against a fixed 1.0s bound. Measured three ways against this branch's own parent — uninstrumented (~1%, inside the parent's own spread), coverage-instrumented (indistinguishable), and the whole benchmark file under --cov (branch faster) — no method reproduces a slowdown. Tracked as #475, which carries the full evidence including the CI control run that favours master.

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.66%. Comparing base (07b3231) to head (66128d3).

Additional details and impacted files

@@           Coverage Diff           @@
##           master     #474   +/-   ##
=======================================
  Coverage   98.66%   98.66%           
=======================================
  Files          45       45           
  Lines        3214     3214           
=======================================
  Hits         3171     3171           
  Misses         43       43           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.