fix(render): initials() honors the folded-word order the family field applies (#408)

[derek73]

initials() read a name in a different order than the fields of the same name.

Closes #408

The defect

Two rules fold words into the family and render them before it — O3's middle_as_family, and P6's tussenvoegsel attachment after a family comma. _types._text_for honors that: it collects FOLDED_TAG carriers and returns folded + parts. _render.initials() walked tokens_for(role) in written order and never applied the reorder, so the two views disagreed about one parse:

parse("der, y van")     family 'van der'    initials 'y. d. v.'    facade 'y. v. d.'

mechanisms.md#RENDER-HONORS-THE-PARSE already named this as an instance of its second shape — a view and a field disagreeing about the same parse — so the design was settled before implementation and is not re-argued here.

It restores v1 parity rather than deviating from it

This is the opposite of what the issue assumed, and it is the finding that made the change cheap.

v1 had this feature as CONSTANTS.middle_name_as_last, which _config_shim maps to middle_as_family. Measured on the released 1.4.0 wheel, at the default order:

	movers	come into exact 1.4.0 agreement	move away from it
default order	1	0	0
middle_as_family	71	54	0

Of the 17 that match neither, 14 differ only in v1's per-*_list-element initials granularity (V G. against V. G.) and all 14 come into 1.4.0's letter order after the change, none before. Two differ because the 2.x parse itself differs — Smith, John V. is #432 and 남궁민수 지훈 is W1. The fifteenth is der, y van, where 1.4.0 contributes nothing for an all-particle family, which is R3's own decided clause.

v1 has no general name_order, so the family-first orders have no v1 reference in either direction.

Reach

660 of 6564 parses move — 1094 corpus names × three name_order values × middle_as_family off/on:

default order           1 / 71
FAMILY_FIRST            1 / 294
FAMILY_FIRST_GIVEN_LAST 1 / 292

The population matters more than the count. The shape an order change can be observed in is a contributing folded token standing after a contributing unfolded one of the same role. At the default order the corpus holds exactly 1 such name without the option and 72 with it — so the movers are 1 of 1 and 71 of 72, a near-total hit rate over a corpus carrying one instance of P6's half, not a reach near zero.

The differential gate cannot see any of this. compare.py compares the seven role fields plus _ambiguities; initials appears nowhere in it. Gate output is byte-identical before and after, including all 67 / 58 / 51 per-heading counts. No ledger rule was added and none was needed — the same blindness decisions.md#R4 records for capitalized().

Review

Four agents. Nine Important findings, no Critical, all fixed. Three are worth naming because they are the same failure shape at three depths.

Fixture arity, three times over. A partition over a group with fewer than two elements is the identity, so an under-populated fixture asserts the behavior and pins nothing.

1. Draft 1 gave MIDDLE one token — skipping the partition for MIDDLE passed the entire suite.
2. Draft 2 gave FAMILY zero, in a test named for every role — skipping it for FAMILY passed that test.
3. Draft 3 fixed the roles, but the folded sub-group the partition builds was Ahmad Ali — two elements that both initial to A., so reversing the folded half alone passed all 428 relevant tests.

Recorded as mechanisms.md#TWO-ELEMENT-GROUPS: count the elements, and count the ones the assertion can distinguish.

A recompute recipe that measured nothing. decisions.md#R3 said to compare initials() "against a folded-first partition of tokens_for(role)" — which is what initials() now is. On the shipped tree that yields 0 differing parses; the 660 comes from comparing against the pre-change written-order rendering. The inert-measurement shape inside the sentence written to prevent it, on a count the gate cannot check. The recipe now names the comparator and reproduces 660.

A claim asserted in three places and tested nowhere. _render.initials, its sibling test and mechanisms.md#FOLDED_TAG all say the pipeline puts FOLDED_TAG on FAMILY tokens alone — the entire justification for the GIVEN and MIDDLE arms being uniformity rather than reachable behavior. True (0 of 1094 names carry it elsewhere) and unguarded, so a rule that ever folded into another part would falsify all three silently. Now pinned, and verified by mutating a producer to fold into MIDDLE.

Also fixed: a 2.2.0 - Unreleased bullet six lines above this one still told readers the two APIs order initials differently and that #408 was open, with values false as shipped.

Verification

• 6125 → 6129 passed; mypy, ruff, sphinx doctests and README doctest clean.
• Gate green at all three baselines, byte-identical to master's output.
• corpus_rules.jsonl unchanged at 241 — R3's new example line reuses an input already present.
• Completeness checked by an independent invariant rather than a reimplementation: each group's initials letter sequence must be a subsequence of that group's field word initials. 660 violations before, 0 after.
• Every mutation named in decisions.md#R3 reproduces, each failing at its own role's assertion.

The rule this needed, amended

AGENTS.md admitted two provenance sources for a quantified release bullet — the gate's classified summary, or verification against a rules.md example. Neither can reach a render view: the gate's output is byte-identical across this change, and an example line witnesses an output without counting anything. This bullet named a third source in prose with no rule admitting one, so the rule now admits it — a recompute recipe kept with the design entry the bullet cites — and carries the failure that recipe hit, since naming the comparator and running the recipe as written are what stop it recurring. Cross-version numbers stay dated snapshots under Counting claims.

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.65%. Comparing base (805bcf8) to head (ab5af8e).

Additional details and impacted files

@@           Coverage Diff           @@
##           master     #465   +/-   ##
=======================================
  Coverage   98.65%   98.65%           
=======================================
  Files          45       45           
  Lines        3193     3194    +1     
=======================================
+ Hits         3150     3151    +1     
  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.