[derek73]

The third of three PRs implementing the #1254 decision: #1345 and #1347 are merged, and master is merged into this branch, so the diff against master is the report alone.

What it does

Under the given-first order, one name word followed by nothing but initials now reports the fork as an order ambiguity. It names no alternative: the other reading lays out the whole name (the word in front as the family, the letters as given and middle initials), which no one word's other role names. The detail says so in words, with name_order=FAMILY_FIRST, the setting that reads it. The reading itself does not change.

Input	Default reading	Report
Armitage J. O.	given Armitage	order
Gomes A.R.S.	given Gomes	order, suffix-or-name (as before)
Kavitha S	given Kavitha	order
Lakshmi R S	given Lakshmi	order

The report is emitted at its decision site, _assign_main's positional layout, under the given-first order. It is inline and nested, so a plain name exits at its second piece. The serial frame band holds.

What counts as initials: letters in rules/T5's shape, spaced, or joined by full stops (A.R.S., measured on the composed spelling so NFD reads alike), ending the name words. A Cyrillic byline reports, spaced or joined (Иванов И. И., Иванов И.И.).

What it does not report (each is pinned by a test):

• John Smith
• Zhi LI, Armitage JO: capitals written as one word with no full stops (see the first decision below)
• Smith, J.O. and , R S: a family comma names the family
• a declared family-first order (both orders)
• initials_as_family=True
• Ram Bahadur B K: a second name word in front
• J R S, J.A. K.D.: a run of initials in front (rules/T7)
• Van R S: a particle in front, whose own particle-or-given fork reports it
• Kavitha s: a lower-case letter among capitals (rules/T4)
• Dupont J.-P., Smith J-P: hyphenated initials, which carry no initial tag
• 김 v: a word in a script that writes no initials

Decisions for the maintainer

1. Bare capitals (Armitage JO) are not reported, though Should Armitage JO read family 'Armitage'? A surname followed by initials, with no comma, reads the initials as the family name #1137 names that very example. Nothing in the parse tells JO from Zhi LI: both are untagged capitals read as the family. On the 3.1 study populations:

   • leaving them out leaves 592 of 2,311 ORCID credit names confirmed as bylines unreported;
   • counting them would also report 92 of the 592 names of Turkey's parliament (Erkan BAŞ) and 276 of a 60,000-name ClinicalTrials.gov sample (Antoine BEDU), all surnames written in capitals.

   This is why the PR says Refs Should Armitage JO read family 'Armitage'? A surname followed by initials, with no comma, reads the initials as the family name #1137 rather than Closes. Keep the choice, or report capitals too and accept the surname reports.

2. The reserved order kind, not a new one. AmbiguityKind.ORDER has been reserved since 2.0 for "the name's field order itself is uncertain", which this is. A new kind would be new public API; this adds none, but it is the first time order is emitted.

3. Only one-word heads report, as the decision worded it. Two name words before initials (Rincón Durán S. A., Ram Bahadur B K) do not.

4. A one-letter numeral read as the family reports both forks. John V, Malcolm X and GND's regnal Heinrich I. (which T5 already reads as an initial) report order beside their suffix-or-name.

5. 22 case rows gain order; their classifications are unchanged. The classification records how fields compare with 1.4.0, which had no reports, and no field moved. Two rows were renamed from ..._is_silent to ..._reports_no_link.

Measurements

These were taken against a checkout of #1347's head (29e86c7); the committed corpora and the match were re-taken against master (e9c74d2) once it held #1347.

Committed corpora, against master: 63 names gain the report, and only their ambiguities move (the report carries no alternative). That is 61 at the reviewed commit plus two rules/O8 examples #1347's review added (Lakshmi R S V, Ram R S). The rule examples added here are new to the corpus.

Local corpora, with snapshot.py --local <source> --base <that checkout> at this head; only ambiguities moved:

source	names gaining the report
orcid-researchers	4,939
nepal-candidates	1,580
tse-donors	1,402
patentsview-inventors	437
ctgov-officials	392
jrc-names	133
psc-individuals	13
fec-individuals, cz-candidates, dof-signatures, govuk-people, tw-donors, uit-vinames, ukec-individuals, vn-assembly	0

opensanctions-parliaments was not read: its cache predates six of the datasets the tool reads.

Hand read:

• PSC's 13: Nepali K C/B C, South Indian G M, and given names with a family initial (Alyssa X., Camilla P).
• A seeded sample of 40 of ctgov's: about 28 bylines the default reads wrong (Jabs D, Smith C), about 5 South Indian (Prathik B H), and about 5 given names with middle and family initials (Nancy K M). A reader would hesitate over nearly all of them.

Matching, tools/differential/match_diff.py --base <checkout of master e9c74d23>: 0 of 655,473 rows moved, and no consistent pair shares no key, and no consistent pair shares no key. The report carries no alternative, so the match tries nothing for it and _match.py is unchanged. Whether the match should re-read such a name under the other order is #1303's question, which this report now gives a trigger for (decisions/name-matching says so).

Recorded controls re-taken, each with its reason:

• the field sweep: 1,860 → 1,882 claims
• the alternative sweep's skips: unchanged at 366 (the report carries no alternative)
• the one-case grid's unguarded count: 414 → 507
• the multi-report grid: 3,744 → 3,780, verified to be all order

Review round 1 (1c30154)

1. No alternative (the review found every tried reading was a hybrid the parser never produces: Mr. Smith / Smith E.T. matched through family 'Smith E.T.', while Smith J. / John Smith stayed inconsistent). The order report now carries none. A fill loop in _assign was giving it a name reading, so the report is appended after that loop. _check_alternatives asserts None for order. rules/A1, rules/O4, decisions/O4, A1, D2 and name-matching, AmbiguityKind.ORDER's docstring, docs/policy.rst and the release bullet are corrected.
2. The detail text said "followed only by initials" where a post-nominal follows (PHUOC T DO, Sigve N Aas, PhD, Felicio S Neto). By the rule's own terms a post-nominal is no name word, so these keep the report, and the text now says "the only name word before initials". Rows pin it. The counts are unchanged: ctgov 392 (30 with a suffix after), tse-donors 1,402 (457).
3. Silences stated as limits, with rows, not extended: Devanagari letters with a vowel sign (राम बि.क., What does an initial look like in Devanagari, Bengali and the scripts like them? (एम. एस. वर्मा gives initials() 'ए. ए. व.') #1273), transliteration digraphs (Ivanov Yu. A.), and a one-case Y (SILVA Y, silva y). rules/P8's sentence now holds only for the marked letters.
4. rules/O4:
   • The leads say "no order" (a declared given-first order reports, and the given-first order reports default or declared).
   • The rows show each silence (12 S., 王 J) and a hyphenated initial (Dupont J.-P.).
   • New Precedence bullet against a particle in front (Van J. S.). The Signal: line names the shape.
   • decisions/O4 says it narrows After a name with no comma, are initials the family name or the given name's initials? (Armitage JO vs Lakshmi R S) #1254's decision on glued initials, with both costs; it marks the session-notes counts as dated snapshots, and says why opensanctions-parliaments was not read.
   • O4 should become a rule of its own, as O5 did: it reads a word count and a shape, not position. The size test does not ask for it, so it is not split here.
5. Mutation survivors:
   • NFC on the head and the head's letter test now have rows (NFD É S; ?? S, 12 S., -- J O).
   • Removed as unreachable by construction:
     • the comma and segment tests: _assign_main runs only on segment 0, under no comma or a suffix comma;
     • by_script: a script's order needs a wholly Han, Hangul or kana name, which holds no initial;
     • the head's initial tag: one letter, refused by the chunk test;
     • chunk.isalpha(): the dotted shape tag passes period_joined_vocab's alphabetic gate.
   • A _PREFIXED_SHAPES benchmark row for the per-piece walk. Re-taken on the row's own harness at load average ~5: 4.00–4.05 clean, 7.5 with one list scan planted per piece (failing three runs of three, 1.25x over the 6.0 bound), 12.0–12.1 with two scans. The first figure quoted here (11.47–12.23) was the two-scan plant.

Review round 2 (b4593a0)

• order is added to the lists of reports that carry no alternative: Ambiguity.alternative's docstring, docs/usage.rst, and nameparser/_pipeline/AGENTS.md's "every emitter names the reading it did not take".
• The benchmark margin is re-taken (above).

Docs

• rules/O4: a Then bullet, three Except bullets and an Accepted bullet. The rules/P8 and S10 examples and their bullets now name the order report beside theirs.
• decisions/O4: a dated entry and a Standing line.
• decisions/A1: a dated note that order is now emitted.
• AmbiguityKind.ORDER's docstring, no longer "reserved".
• docs/policy.rst: one paragraph and a doctest in the initials-as-family section.
• The release log: one bullet, its "2.0.0 through 3.0.1" range checked on the wheels.

Checks

• uv run pytest: 45,933 passed (on master).
• uv run pytest -n0 -m serial: 63 passed (the new benchmark row among them), so the frame band holds.
• uv run mypy, uv run ruff check, uv run sphinx-build -b doctest docs, uv run sphinx-build -W -b html docs and uv run python tools/vocab/build.py --check: clean.
• CI on Gate the suggester's trailing-initial vote on the group's share; fix a title-only name's crash #1345 and Add Policy.initials_as_family, reading letters ending a name as its family (#1254) #1347: green.

Refs #1137
Refs #1254

🤖 Generated with Claude Code