Mark 33 credential readings ambiguous where a surname reading is substantial (#796)

* Mark 33 credential readings ambiguous where a surname reading is substantial

Audit of credential readings borne as surnames (C-i). Keeps words with
US Census 2010 bearers >=200 or Wikidata family bearers >=20; holds am,
sa, pla, edd, ra and mba; drops 17 with weak surname evidence.

Measured: 2 corpus names move, 0 agreement regressions. Pinned test
for 'John Om Ma' updated for the ambiguous om reading.

Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>

* Drop pa-c from the ambiguous batch: its census count is the surname PAC

The census lookup folds a spelling to its letters, so the 535 census
bearers counted for pa-c are PAC's, not Pa-c's. No Pa-c surname is
measured (Wikidata 0), so the surname evidence does not apply.

Batch: 33 -> 32 words. Snapshot re-recorded (2 names move).

Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>

* Drop cap and aas from the batch: NPPES counts show the credential dominates

US healthcare providers writing the word (NPPES, August 2026): cap 759
against 865 census bearers, aas 528 against 238. The credential reading
is at least as large as the surname reading, so marking it ambiguous
costs more than it gains. Batch 32 -> 30 words; snapshot re-recorded.

Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>

* Re-add ei, capa and ams to the batch under the revised NPPES rule

Revised rule (decisions/suffix-acronym-collisions, 2026-10-21): where both
the census surname count and the NPPES provider count are small, mark
where the surname reading is the larger. capa (175 census / 11 NPPES)
and ams (135 / 5) qualify. ei rests on C-i's default under uncertainty:
EI is not a healthcare credential, so NPPES's 12 says nothing about it.

Adds Robert Capa (family Capa) and John Smith CAPA (suffix CAPA) case
rows to pin the fork, and bumps the field-sweep count 1302 -> 1308.
Batch 30 -> 33 words.

Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>

* Per-word evidence, query pointer, order measurements and release-log bullet for #796

- Each of the 33 credential readings carries a dated family reading (Census,
  Wikidata) and given reading where measured (SSA summed over sexes, noted),
  and a note with the NPPES healthcare-only count, issue = 796.
  om and se lose their stale 'NOT may_be_name' notes.
- decisions entry: points at tools/vocab/query.py --issue 796 instead of the
  working audit, and records the order-dependence recipe over the 33 words
  (GIVEN_FIRST 1,122 moves; family-first orders 1,056; credential inside a
  multi-word family only under GIVEN_FIRST, the John de Smith Caro class).
- release_log: one bullet merging #791's and #796's, Luo Si and Robert Capa
  before/after, the all-caps limit sentence.

Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>

* Fix the #796 dropped list (14) and NPPES count-1 grammar

The dropped list named capa, ams and ei, which the same entry re-adds;
remove them and make the count 14. Count-1 NPPES notes now read
'provider writes it'; the count-0 wording is already correct.
Compiled module unchanged (notes compile to nothing).

Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Haiku 5.5 <noreply@anthropic.com>

Author: derek73

docs/design/decisions/suffix-acronym-collisions.md

@@ -23,6 +23,9 @@ Closes #342 (a wordlist question) and #454 (a rules.md question) together, becau
 
 - **2026-10-18 — cva[22], gaee[14] and np[18] left SUFFIX_ACRONYMS: Wikipedia footnote marks, not credentials.** All three arrived with the `af5bdab` bulk import (2019-12-11), the bracketed number being the source page's reference mark copied along with the acronym; the 3.0 vocabulary spec's migration spike found them. They matched only a token written with the mark itself, so `John Smith NP[18]` read suffix `NP[18]` and now reads family `NP[18]`, and nothing else moves: `np` and `cva` have clean entries of their own, and `gaee` never had one (`John Smith GAEE` reads family `GAEE` before and after). Whether GAEE should be added as a clean entry is a separate vetting question, not taken here. A bulk import from a wiki page carries its reference marks: check a new list for brackets before it lands. Recompute that no vocabulary entry holds one: `uv run python -c "from nameparser import Lexicon; L = Lexicon.default(); print(sorted(w for f in ('titles', 'suffix_acronyms', 'suffix_words', 'particles', 'conjunctions', 'bound_given_names', 'maiden_markers') for w in getattr(L, f) if set(w) & set('[]')))"`.
 
+- **2026-10-21 — 33 credential readings marked ambiguous (C-i's default), not removed.** The 33 readings are listed by `uv run python tools/vocab/query.py --issue 796`; each carries its Census, Wikidata and SSA counts with an `as_of` date, and an NPPES note. The candidate screen found 58 unflagged credentials with census or Wikidata surname evidence. The batch keeps the words whose surname reading is substantial (US Census 2010 bearers ≥200, or Wikidata family bearers ≥20). That threshold stood in for the credential half of C-i while no provider count existed. Since #798 the NPPES count (US healthcare providers writing the word, August 2026 file) measures that half, with one direction only: a count is evidence a credential is live, while a zero says nothing about a non-healthcare credential. Revised rule, dated 2026-10-21: when both counts are small, compare them and mark where the surname reading is the larger. Words that the rule re-adds: `capa` (surname 175 census / 7 Wikidata family, NPPES 11) and `ams` (135 / 2, NPPES 5). `ei` (127 / 3, NPPES 12; also a Korean given name in nam_dict) rests on C-i's default under uncertainty alone, because EI (usually Engineer Intern) is not a healthcare credential, so NPPES says nothing about it. Pinned by the `robert_capa_is_a_surname` and `all_caps_capa_is_still_a_credential` case rows. The census lookup folds a spelling to its letters (`name_usage.py`), so `pa-c` was counted as the surname `PAC`; it is dropped, since no `Pa-c` surname is measured. The threshold is a judgement, not a rule the data sets, and the held-out words below are the ones it cannot place. Dropped for weak surname evidence (14): `abd`, `ceh`, `fala`, `ches`, `cas`, `cia`, `res`, `obe`, `facha`, `ame`, `usa`, `aia`, `iso`, `rid`. Several of these are recognizable designations, which the threshold does not itself test. Dropped after the NPPES check (US healthcare providers, a live-credential count): `cap` (759 providers against 865 census bearers) and `aas` (528 against 238), where the credential reading is at least as large as the surname reading. Held out: `am`, `sa`, `pla` (CLDR regressions: Gaelic `am post`, Burmese `Khun Sa`, Spanish `Hernández Pla`); `edd` (`John Smith EdD` reads `EdD` as family under either option); `ra` (also a title: `John Smith Ra.` reads title `Ra.` with no flag); `mba` (its credential reading is the dominant one). `pe` is kept on surname evidence (582 census, 305 Wikidata family) although it is also a designation. Removal, measured on the 53-word set, is the worse answer on real designations: `john smith mba` reads `mba` as family, and `John Smith, MBA` reads `MBA` as a given name, where the flag keeps the suffix and reports the fork. Measured on the tree (30 words): the corpus names that move are re-recorded in `snapshot.jsonl`, with the agreement check unchanged (`Maheen Farooqi, ACA`, `Pèrs, Ciro di`), with 0 agreement regression lines across the CLDR, GND, Wikidata, native and conventions corpora. Every batch member moves bracketed, double-quoted and single-quoted credentials to nickname (rules/S1 is silent on that coupling; decisions/ma-do records it for ma and do). A single trailing period (`John Smith Caro.`) reads family under the flag too. The written case decides: UPPER moves nothing, per S6 before S4.
+- **Order dependence (measured 2026-10-21, #796).** Recipe as in the #791 entry above, over the 33 words: 9 templates × 2 name pairs × 3 casings (Title, UPPER, lower) = 1,782 cells per order, marked tree (`Lexicon.default()`) against the comparator `Lexicon.default().remove(suffix_acronyms_ambiguous=…33 words…)`. Moves: `GIVEN_FIRST` 1,122 (Title 594, UPPER 66, lower 462); `FAMILY_FIRST` 1,056 (Title 594, lower 462, UPPER 0); `FAMILY_FIRST_GIVEN_LAST` 1,056 (the same split as `FAMILY_FIRST`). The family-first orders move nothing in UPPER, the case signal (rules/S6) deciding there. Credential inside a multi-word family name (the `John de Smith Chi` class, which these templates do not contain), probed separately with `John de Smith W`, `John de W` and `John van der Smith W` in Title and lower casing, 198 cells: `GIVEN_FIRST` 99 moves, every one reading the credential inside the family (`John de Smith Caro` reads family `de Smith Caro`, with no suffix); `FAMILY_FIRST` and `FAMILY_FIRST_GIVEN_LAST` 99 moves with no credential inside a multi-word family. This is the surname reading the marking is for, and it is the accepted cost of a particle before the word under `GIVEN_FIRST`; it is not checked against 1.4.0 here.
+
 - **2026-10-21 (#791) — si and chi joined SUFFIX_ACRONYMS_AMBIGUOUS, the ba/meng answer.** Both entries arrived in the 2019-12-11 bulk import (af5bdab, #93) with no expansion, and neither was checked against a surname. C-i's criterion, asked of the trailing position: Si is a common surname (`tools/name_usage.py Si`, measured 2026-10-21: US Census 2010 1,166 family-name bearers, rank 22,158; Wikidata 275+ family, 124+ given) and a Vietnamese and Chinese given name; Chi is more common still (Census 2010 7,273, rank 4,843; Wikidata 219+ family, 123+ given) and a Vietnamese given name. No credential expansion is recorded for either, so the surname side is the only one measured. The marking is C-i's default under uncertainty, and it does not destroy a surname on a guess: with a full name in front, the credential reading survives by the words-to-spare count (`John Smith SI` reads suffix `SI`, flagged), and a bare or comma-form one reads the surname or the given name with the fork reported. Removal, the rai/cha answer, was the alternative and was not taken. The criterion weighs name frequency against credential frequency, and no credential expansion is recorded for either word, so the measurement that would reverse this is an expansion for SI or CHI showing a credential reading as common as the surname; until then C-i's default under uncertainty decides. The case rows are `bare_si_is_a_surname`, `bare_chi_is_a_surname`, `comma_si_is_a_given_name`, `comma_chi_is_a_given_name`, `capital_si_is_a_suffix_when_a_family_name_remains`, `comma_capital_si_is_a_suffix`, `dotted_si_is_a_suffix_without_a_flag`, `title_case_si_is_a_surname_with_words_to_spare`, `period_si_after_a_full_name_is_a_surname` and `credential_run_led_by_a_declined_chi`, and the review's `empty_head_si_is_a_given_name`, `empty_head_caps_si_is_a_given_name`, `nickname_head_si_is_a_given_name`, `capital_si_after_a_surname_is_a_suffix`, `comma_capital_si_is_a_suffix`, `family_first_bare_si_is_a_given_name` and `family_first_comma_si_is_a_given_name` (`tests/v2/cases.py`, #791 block), which pin the fork, not the wordlist.
 
   **Precedence, stated because the words-to-spare count is not the only guard.** In a name written in more than one case, a Title-case member is the name even with words to spare: S6 (the case signal at the suffix slot) decides before S4 (the count), so `John Smith Si` reads family `Si` and only the all-capital `John Smith SI` keeps the credential. The same holds for a trailing period: one period is the abbreviation shape any word wears (rules/S3), so `John Smith Si.` reads family `Si.`, the way `John Smith Ma.` does, and the dotted `John Smith S.I.` (one period per letter) stays a suffix with no flag.

docs/release_log.rst

@@ -10,7 +10,7 @@ Release Log
 
     **Behavior Changes**
 
-    - **Fix a surname spelled Si or Chi reading as a credential.** ``Luo Si`` gives family ``Si``, given ``Luo``, where 2.0.0 through 2.5.0 gave suffix ``Si`` with no family name. A Title-case ``Si`` after a full name takes the family name, as ``Ma`` does, and a capitalized ``SI`` is still a credential. :issue:`791`
+    - **Fix credentials that are also surnames reading as credentials.** ``Luo Si`` and ``Robert Capa`` give a family name, where 2.0.0 through 2.5.0 gave suffix ``Si`` or ``Capa`` with no family name. A Title-case word after a full name takes the family name, as ``Ma`` does; the all-caps form stays a credential (``John Smith CAPA`` keeps suffix ``CAPA``). :issue:`791`, :issue:`796`
 
 * 2.5.0 - October 19, 2026
 

nameparser/config/_compiled.py

@@ -1315,14 +1315,47 @@
 })
 
 SUFFIX_ACRONYMS_AMBIGUOUS: frozenset[str] = frozenset({
+    'aba',
+    'aca',
+    'ace',
+    'acha',
+    'ala',
+    'alp',
+    'ams',
+    'arm',
+    'asa',
+    'asp',
     'ba',
+    'bem',
+    'caha',
+    'capa',
+    'capp',
+    'caro',
+    'cea',
+    'cela',
+    'cera',
+    'che',
     'chi',
+    'ciro',
+    'csi',
+    'cua',
     'do',
+    'ea',
     'ed',
+    'ei',
+    'els',
+    'erd',
+    'faia',
+    'fic',
     'jd',
     'lac',
     'ma',
     'meng',
+    'obi',
+    'oca',
+    'om',
+    'pe',
+    'se',
     'si',
 })