Correct five claims the exclusion prose got wrong

A second review round over the corrections themselves. All five are
prose; no behavior changes, and the gate is unmoved at 107/0.

"Silencing all 47 would turn 47 legitimate classifications into
UNEXPLAINED" was the biggest, and the first review round already
raised it -- I rewrote the surrounding block and left the number.
Measured by adding exactly that exclusion and running the gate: three
names, all CJK, and the other 44 do not diff at all. The real cost is
those three plus 44 shapes pre-silenced, which counting names both
overstates and hides.

'Senator "Rick" Edmonds' was cited as a leading pair the entry fails
to protect. It is medial and IS captured -- 'Senator' supplies the
left flank. The corpus holds a separate '"Rick" Edmonds', which is the
genuinely unguarded one; name that instead, and note the trap.

"The 21 it gains are almost entirely that family" read as "credentials"
against its own antecedent. 20 of 21 put the delimiter last, but only 8
are credentials and 6 are trailing NICKNAMES -- the reading this entry
exists to protect. So the medial cut is about position, not about
credentials: at the trailing position a nickname and a credential wear
the same shape, and protection and over-reach arrive together. Whether
`fields` already makes the wider shape safe is now flagged as an open
question rather than answered by assertion.

"Only 9 of those 47 are parenthesised credentials" is 8. Nine is the
count a name_regex-carrying rule reaches -- two measurements conflated.

'Xyz. (Bud) Smith' was the example for a middle initial; it parses
'Xyz.' as a title. 'Cherice J. (Johnson) Williams' is the real one.

Also: the _EXCLUSION_EFFECT preamble claimed in the present tense that
dropping the Ph. D. anchor keeps the suite green -- true before this
pin existed, self-refuting in the tree that contains it. And the
fields-deletion note had the mechanism backwards: absorbed_by GROWS
from () to ('fix(suffix-routing)',), it does not see a reading go
unclaimed. Both now say which era they describe.

Two limits named rather than left implicit: absorbed_by records only
the first rule matching each subset, so a fully shadowed rule does not
move it; and an entry carrying `fields` is asked about only the
subsets those cover, which is where the 387 comes from.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: derek73

AGENTS.md

@@ -125,8 +125,9 @@ uv run sphinx-build -b html docs dist/docs
 #    tests/v2/test_ledger_guards.py records what each one silences --
 #    which rules would claim it with exclusions off, and how much corpus it
 #    captures -- in _EXCLUSION_EFFECT. That IS an enrollment: an entry
-#    added or edited moves the record and must be re-recorded deliberately,
-#    the same forcing function _CORPUS_CLAIMS applies to rules.
+#    added, or its name_regex/fields/examples edited, moves the record and
+#    must be re-recorded deliberately, the same forcing function
+#    _CORPUS_CLAIMS applies to rules. (A `why`-only edit does not move it.)
 # 9. Open the next cycle's VERSION: bump VERSION in nameparser/_version.py to
 #    the minor now being worked, and set PRE_RELEASE = 'dev'. The tree then says
 #    what it is building rather than what it last shipped -- docs/conf.py reads

tests/v2/test_ledger_guards.py

@@ -1149,10 +1149,19 @@ class _Excluded(NamedTuple):
 #: harness cannot report because the exclusion (correctly) hides it.
 #:
 #: `captures` and `digest` cover the opposite direction, which nothing
-#: else watches: an exclusion widened by name_regex silences real
-#: classifications, and CI stays green while the release gate breaks.
-#: Measured: dropping the Ph. D. entry's ASCII anchor keeps the whole
-#: suite passing and takes a bare run to unexplained: 1.
+#: else watched: an exclusion widened by name_regex silences real
+#: classifications, and BEFORE this record CI stayed green while the
+#: release gate broke. Measured then: dropping the Ph. D. entry's
+#: Latin anchor left the whole suite passing and took a bare run to
+#: unexplained: 1. Measured now: the same edit fails this pin -- the
+#: record is keyed by name_regex, so editing one is exactly what it
+#: catches -- while the gate still goes to unexplained: 1.
+#:
+#: One limit worth naming: `absorbed_by` records only the FIRST rule
+#: matching each subset, so a rule appended behind one that already
+#: answers those subsets is invisible here. A rule reaching a
+#: protected READING is caught; a rule shadowed by an existing one on
+#: every subset it claims is not.
 _EXCLUSION_EFFECT: dict[str, _Excluded] = {
     "(?i)^[\\u0000-\\u024f]*\\bph\\.\\s*d\\.\\s*$":
         _Excluded(3, "5a12a8117651",
@@ -1255,7 +1264,10 @@ def test_a_fields_narrowing_actually_narrows_something() -> None:
     a deleted key drops the entry from the loop entirely. That works
     only while one entry carries `fields`. A second one would leave the
     deletion green here -- caught instead by `absorbed_by` in the
-    recorded pin, which sees the reading go unclaimed.
+    recorded pin, which is then asked about every reading rather than
+    the three the key covers, and sees rules claim them. Measured:
+    deleting this entry's `fields` grows its `absorbed_by` from () to
+    ('fix(suffix-routing)',).
 
     Measured: deleting `fields = ["nickname", "middle"]` from the
     ASCII-pairs entry passes every other check in this tree. The entry

tools/differential/README.md

@@ -325,7 +325,10 @@ before the rules are reached, so the answer is `None` however the rules
 change. The pin therefore asks with exclusions switched OFF and records
 which rules WOULD claim each protected reading. A rule widened to reach
 one changes that record and fails in CI, rather than being invisible
-until someone reasons about it. The same record carries the number and
+until someone reasons about it. It records the FIRST rule matching each
+subset, so a rule shadowed on every subset it claims by one already
+sitting ahead of it does not move the record; a rule reaching a
+protected reading does. The same record carries the number and
 digest of the corpus names an entry captures, which is the opposite
 drift: an over-wide exclusion silences real classifications, and that
 is loud at release but otherwise silent on a push.

tools/differential/expected_since_1.4.0.toml

@@ -424,9 +424,17 @@ fields = ["title", "given", "middle", "suffix"]
 # Shapes that must never be explained. A [[change]] rule says "this
 # diff is intended, and here is what changed"; there was no rule
 # meaning "whatever happens here is a regression", so the two promises
-# below could only be written as prose -- and both were false from the
-# day they were written (the first shipped with the harness itself,
-# the second three days later) until #328 found them.
+# below could only be written as prose -- and both were false as
+# written from the day they were written (the first shipped with the
+# harness itself, the second three days later) until #328 found them.
+#
+# The two are not false alike, and the difference matters now that
+# this file scopes the second promise to one reading. Both said
+# "unclassified", unqualified, and both were claimed on SOME reading
+# from day one. But only the Ph. D. promise was claimed on the reading
+# it now protects; no rule has ever claimed the ASCII pairs' NICKNAME
+# reading, then or today. That entry is a tripwire under no present
+# tension, which is the point of setting it before the tension exists.
 #
 # classify() consults these before any rule, so a matching name
 # reports UNEXPLAINED however many rules would claim it.
@@ -435,7 +443,10 @@ fields = ["title", "given", "middle", "suffix"]
 # any corpus -- 'John "Jack" Kennedy' does not -- so the entry carries
 # its own test data, which tests/v2/test_ledger_guards.py runs against
 # every non-empty subset of the fields a rule may name: the seven
-# roles and the `_ambiguities` pseudo-field.
+# roles and the `_ambiguities` pseudo-field. An entry carrying
+# `fields` is asked only about the subsets those cover -- 3 for the
+# ASCII pairs, not 255 -- which is where the 387 in that file comes
+# from.
 
 [[never]]
 why = "trailing 'Ph. D.' split-token healing is PARITY, not a 2.0 change: v1 healed the adjacent pair too, so a diff here is a regression"
@@ -461,8 +472,8 @@ why = "trailing 'Ph. D.' split-token healing is PARITY, not a 2.0 change: v1 hea
 # '田中さん, Ph. D.', whose diff is a real fix(cjk-comma-compound)
 # classification -- measured, it took the gate to unexplained: 1. The
 # cut is at U+0250, the same threshold _is_latin_only uses in
-# compare.py, so it covers Latin-1 and Latin Extended-A rather than
-# bare ASCII: the split-token healing is script-independent, and
+# compare.py, so it covers Latin-1 and Latin Extended-A and -B rather
+# than bare ASCII: the split-token healing is script-independent, and
 # 'José Smith, Ph. D.' is as much the protected shape as 'Jose Smith,
 # Ph. D.' is. An ASCII-only class protected one and not the other.
 name_regex = "(?i)^[\\u0000-\\u024f]*\\bph\\.\\s*d\\.\\s*$"
@@ -473,26 +484,39 @@ why = "feat(#273) recognizes TYPOGRAPHIC nickname delimiters; the ASCII pairs we
 # Narrowed twice, and both narrowings are load-bearing.
 #
 # By shape: a delimited run MEDIAL to the name -- flanked on the left
-# by a word character or a period (so a middle initial counts: 'Xyz.
-# (Bud) Smith') and on the right by a word character. A bare [("']
-# class reaches 47 corpus names, all of them claimed by a rule today,
-# so silencing them would turn 47 legitimate classifications into
-# UNEXPLAINED. Only 9 of those 47 are parenthesised credentials;
-# 11 match on a bare apostrophe -- "Brian O'connor",
-# "Harietta Keopuolani Nahi'ena'ena" -- which no delimiter regex can
-# tell from a quote.
+# by a word character or a period (so a middle initial counts:
+# 'Cherice J. (Johnson) Williams') and on the right by a word
+# character. A bare [("'] class reaches 47 corpus names. Measured by
+# adding exactly that exclusion and running the gate, silencing all 47
+# costs THREE classifications -- '山田 太郎 (マイケル・ジャクソン)',
+# '김, 민준씨 (Jimmy)', '김민준씨 (Jimmy)' -- because only those three
+# diff against 1.4.0 at all. The other 44 would be pre-silenced: no
+# diff today, and no way to report one tomorrow. Counting names
+# overstates the first cost and hides the second.
+#
+# Of the 47, 8 are parenthesised credentials and 11 match on a bare
+# apostrophe -- "Brian O'connor", "Harietta Keopuolani Nahi'ena'ena" --
+# which no delimiter regex can tell from a quote.
 #
-# The medial cut is what keeps the credentials out: 'Andrew Perkins
-# (JD)' and its kin put the parens LAST. Measured, widening the shape
-# to leading and trailing runs takes it from 13 corpus names to 34,
-# and the 21 it gains are almost entirely that family.
+# The medial cut is about POSITION, not about credentials. Widening to
+# leading and trailing runs takes the shape from 13 corpus names to
+# 34, and 20 of the 21 it gains put the delimited run last. Only 8 of
+# those are credentials; 6 are trailing NICKNAMES -- 'Franklin,
+# Benjamin (Ben)', 'Rev John A. Kenneth Doe III (Kenny)',
+# '김민준씨 (Jimmy)' -- which is the reading this entry exists to
+# protect. The rest are trailing maiden names and junk
+# ('Bridge (1.4)', 'John Jones (Google Docs)').
 #
-# So the promise is kept for medial pairs only. A leading or trailing
-# ASCII pair -- 'Senator "Rick" Edmonds' reads as protected and is
-# not, 'Jenny Baker (Johnson)' likewise -- is still unguarded prose,
-# for want of a regex that separates a trailing nickname from a
-# trailing credential. Narrowing a rule would be the way in, not
-# widening this entry.
+# So the trailing position is where protection and over-reach arrive
+# TOGETHER: a nickname and a credential wear the identical shape
+# there, and the delimiter alone cannot separate them. The promise is
+# kept for medial pairs only, and a leading or trailing ASCII pair --
+# '"Rick" Edmonds' reads as protected and is not, 'Jenny Baker
+# (Johnson)' likewise -- is still unguarded prose. (The corpus also
+# holds 'Senator "Rick" Edmonds', which IS medial and IS captured;
+# the two are easy to confuse.) Whether the `fields` narrowing already
+# makes the wider shape safe is an open question, unmeasured here;
+# narrowing a rule is the other way in.
 #
 # By role: ASCII parens mark nicknames, maiden names, suffixes and
 # credentials alike, and no regex tells them apart. The shape reaches