fix(revise): a suffix value derives its entries from its own commas (#511)

[derek73]

Closes #511.

Problem

Parser.revise(name, suffix=value) classified the value by a full sub-parse and then forced every harvested token to SUFFIX — after the sub-parse had already run the #436 entry pass, which keys on Role.SUFFIX. A bare "MD PhD" reads in that sub-parse as a title plus a family name, so the pass joined nothing, and the suffix view comma-joined two unjoined tokens. Feeding a name's own suffix back was not the identity:

input	p.suffix	revise(p, suffix=p.suffix).suffix before
John Smith MD PhD	MD PhD	MD, PhD
John Smith, Ph. D.	Ph. D.	Ph., D.
Doe, John, MD PhD - FACS Fellow	MD PhD - FACS Fellow	MD, PhD, -, FACS, Fellow

Measured 2026-09-06 over the 1117 distinct names in tools/differential/corpus*.jsonl (368 carry a suffix): 38 did not round-trip.

Fix

Three commits, one concern each, bisectable in order.

1. refactor(post_rules) — the entry pass at the tail of post_rules becomes _mark_suffix_entries (in place over the stage's token list, as every other post rule writes) plus the wrapper suffix_entries(state). Pure move; the predicate is unedited. A first draft had post_rules call the state wrapper and cost three more calls per parse against the benchmark band (py3.11: 450 → 454 calls/name; the band tops at 455.9), so the worker spelling was chosen (451). Four stage tests exercise the wrapper over forced-role states.
2. fix(revise) — revise sub-parses each value to a state, forces the named role on every non-dropped token, runs suffix_entries over the forced state, assembles and harvests. So a comma in the value parts two credentials and a space joins them: the rule a whole name uses (rules.md#R1, which gains an Accepted: clause and _parser.py in implemented:). parse() is untouched; a draft _run helper shared with parse cost a frame on the hot path and was dropped.
3. docs — decisions.md Should Parser.revise(name, suffix=name.suffix) be the identity? (John Smith MD PhD gives MD PhD, and revising with that string gives MD, PhD back) #511 bullet under C1 (R1's history pointer) with the measurement and recipe, the phd-merge acceptance of Ph., D. marked superseded with its head-position reasoning left standing, the ONE-PREDICATE-PER-QUESTION instance, and the 2.3.0 release bullet.

Behavior

• revise(n, suffix="MD PhD") → MD PhD (was MD, PhD); "MD, PhD" stays two entries.
• revise(n, suffix="Ph. D.") → Ph. D. (was Ph., D., the 2026-08-31 ACCEPTED outcome). The Ph. D. merge is still a head-position rule and still does not fire in a value; the entry pass joins the pair because they share a comma bucket. Superseded, not reversed in reasoning.
• Round-trip: 38 → 1 of 1117. The one left is 김민준씨, J.씨: the whole-name parse keeps J.씨 one glued suffix token while the bare value's sub-parse peels the honorific off the initial, so the revised field renders 씨, J. 씨 (was 씨, J., 씨) — right entries, a word read differently on its own. That is the "classified ON ITS OWN" limit the docstring records; CJK honorific peeling is a W-rule question, not moved. Pinned.
• Limit, pinned: in a value with no comma of its own, a delimiter named through extra_suffix_delimiters is a word of the run rather than a separator (the drop that parts entries happens only on a segment after a comma). The round-trip is unaffected: the whole-name view already renders that boundary as a comma.
• The sub-parse's tags are kept minus FOLDED_TAG, as before. A draft that cleared the sub-parse's own "joined" was measured and backed out: it destroyed within-piece merge marks on non-suffix values, and no view reads the tag off a non-suffix token.

Verification

• Differential gate byte-identical at all four baselines (360 / 254 / 166 / 28 intentional): revise is not on the compare path.
• pytest: 6584 passed (6576 at master; one test replaced, eight added). mypy and ruff clean. Sphinx build clean.
• tools/perf/call_count.py --against 330ee55: parse 414 / facade 451 vs 413 / 450.
• RECOMPUTE the round-trip figure: parse each corpus name, skip an empty suffix, revise the parse with its own suffix, count the names whose suffix moved (script in the Should Parser.revise(name, suffix=name.suffix) be the identity? (John Smith MD PhD gives MD PhD, and revising with that string gives MD, PhD back) #511 issue body).

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.66%. Comparing base (330ee55) to head (9900f05).

Additional details and impacted files

@@           Coverage Diff           @@
##           master     #512   +/-   ##
=======================================
  Coverage   98.66%   98.66%           
=======================================
  Files          45       45           
  Lines        3219     3232   +13     
=======================================
+ Hits         3176     3189   +13     
  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.