Close the review's findings on the gate and the 2.0 ledger

The spaced-honorific rule matched a LEADING 양/군, which are ordinary
surnames in that position. Nothing is misclassified today, but a future
change routing the leading 양 to suffix would have fallen through to
that rule and been reported as an intended honorific -- the regression
class the gate exists to catch. Head match dropped; all 89 still
classify.

UNEXPLAINED kept only the facade's before/after while the diff set
unions both surfaces, so an _ambiguities-only diff -- the case
_surfaces_for names as the whole reason to compare v2 -- would have
printed a name with no field lines under it.

Also: pin classify's subset check and V2_FIELDS against Role, both
untested and both silent when wrong; drop an unreachable middle from
the #298 rule; and correct a claim that this ledger's hand copies are
pinned by test_regex_sync, which pins the 1.4 file by name.

Author: derek73

tests/v2/test_differential.py

@@ -220,3 +220,26 @@ def test_malformed_rule_error_names_the_ledger_it_came_from() -> None:
         compare.validate_rules(bad, "expected_since_2.0.0.toml")
     with pytest.raises(SystemExit, match="expected_since_1.4.0.toml"):
         compare.validate_rules([{}], "expected_since_1.4.0.toml")
+
+
+def test_classify_declines_a_diff_touching_a_field_the_rule_omits() -> None:
+    """The subset check is the tightness mechanism of every `fields`
+    rule -- a rule claims a diff only when EVERY changed field is one it
+    listed. Nothing else pinned it: a rule and a diff that name the same
+    single field satisfy `<=`, `>=`, `==` and `&` alike, so the existing
+    tests pass with the comparison flipped, and every deliberate field
+    omission in both ledgers would quietly stop meaning anything."""
+    rules = [{"issue": "given-only", "fields": ["given"]}]
+    assert compare.classify("x", {"given"}, rules) == "given-only"
+    assert compare.classify("x", {"given", "suffix"}, rules) is None
+
+
+def test_v2_fields_matches_the_Role_enum() -> None:
+    """AGENTS.md: the seven roles are 'defined once and derived
+    everywhere'. compare.py cannot import Role into the WORKER (that
+    runs under the old wheel), but this copy reads the working tree's
+    ParsedName and must track Role. If a role were added and this tuple
+    not updated, getattr never asks for it and every change in that role
+    is invisible on the v2 surface -- silent under-coverage, exit 0."""
+    from nameparser import Role
+    assert compare.V2_FIELDS == tuple(str(r) for r in Role)

tools/differential/compare.py

@@ -35,6 +35,13 @@
 #: The facade's vocabulary is the one that expires, at 3.0.
 _V1_TO_ROLE = {"first": "given", "last": "family"}
 
+#: An unclassified diff, carrying BOTH surfaces' before/after:
+#: (name, old_facade, new_facade, old_v2, new_v2). Both halves are kept
+#: because a diff can exist on the v2 surface alone, and a report that
+#: named such a diff without showing it would be unactionable.
+_Unexplained = tuple[str, dict[str, str], dict[str, str],
+                     dict[str, object], dict[str, object]]
+
 
 def _parse_version(text: str) -> tuple[int, int, int]:
     """The numeric release tuple, padded to three parts. Every version
@@ -345,14 +352,21 @@ def main() -> int:
     if want_v2:
         from nameparser import parse
     by_issue: dict[str, list[str]] = {}
-    unexplained: list[tuple[str, dict[str, str], dict[str, str]]] = []
+    # BOTH surfaces' old/new are retained, not just the facade's. A diff
+    # can exist on the v2 surface alone -- an _ambiguities-only change is
+    # facade-identical by construction, and is the case _surfaces_for
+    # names as the whole reason to compare v2 -- and keeping only the
+    # facade dicts would print such a name under UNEXPLAINED with no
+    # field lines under it at all: a failure nobody can act on.
+    unexplained: list[_Unexplained] = []
     for name, old in zip(corpus, old_rows):
         new = {k: v or "" for k, v in HumanName(name).as_dict().items()
                if k in FIELDS}
         # canonicalized on the way in: the ledger speaks Role's names,
         # and the facade is the surface whose vocabulary differs
         diff = {_canonical_field(f) for f in FIELDS
                 if old["facade"].get(f, "") != new.get(f, "")}
+        new_v2: dict[str, object] = {}
         if want_v2:
             p = parse(name)
             new_v2 = {f: (getattr(p, f, "") or "") for f in V2_FIELDS}
@@ -365,12 +379,13 @@ def main() -> int:
             continue
         issue = classify(name, diff, rules)
         if issue is None:
-            unexplained.append((name, old["facade"], new))
+            unexplained.append(
+                (name, old["facade"], new, old.get("v2", {}), new_v2))
         else:
             by_issue.setdefault(issue, []).append(name)
 
     changed = [n for names in by_issue.values() for n in names] \
-        + [n for n, _, _ in unexplained]
+        + [row[0] for row in unexplained]
     latin = sum(1 for n in changed if _is_latin_only(n))
     print(f"corpus: {len(corpus)} names; "
           f"intentional diffs: {sum(map(len, by_issue.values()))}; "
@@ -384,16 +399,25 @@ def main() -> int:
     if unexplained:
         print("Field names below are Role's, matching what a ledger "
               "`fields` rule must say.\n")
-    for name, old_facade, new in unexplained:
+    for name, old_facade, new, old_v2, new_v2 in unexplained:
         print(f"UNEXPLAINED {name!r}")
+        # Role's names, not the facade's: this block exists to be turned
+        # into a ledger rule, and a rule naming the facade's `first`
+        # would parse, validate, and never match -- with nothing to say
+        # so. Both surfaces are walked, and a field is reported once
+        # even when both moved, since one rule entry covers it.
+        seen: set[str] = set()
         for f in FIELDS:
             if old_facade.get(f, "") != new.get(f, ""):
-                # Role's name, not the facade's: this block exists to
-                # be turned into a ledger rule, and a rule naming the
-                # facade's `first` would parse, validate, and never
-                # match -- with nothing to say so.
+                seen.add(_canonical_field(f))
                 print(f"    {_canonical_field(f)}: "
                       f"{old_facade.get(f, '')!r} -> {new.get(f, '')!r}")
+        for f in (*V2_FIELDS, "_ambiguities"):
+            if old_v2.get(f, "") != new_v2.get(f, "") \
+                    and _canonical_field(f) not in seen:
+                print(f"    {_canonical_field(f)}: "
+                      f"{old_v2.get(f, '')!r} -> {new_v2.get(f, '')!r}"
+                      f"   [v2 surface only]")
     return 1 if unexplained else 0
 
 

tools/differential/expected_since_2.0.0.toml

@@ -49,8 +49,19 @@ issue = "fix(#271/#272/#298) native-script CJK: family-first order, hangul segme
 # are absent for the same reason against the compound rules further
 # down. The class is copied verbatim from the same rule in
 # expected_since_1.4.0.toml rather than rewritten in literal
-# characters: tests/v2/test_regex_sync.py pins that spelling against
-# the script table, and a hand-rewritten twin drifts silently.
+# characters, so the two ledgers spell the same class the same way.
+#
+# Be aware of what does NOT hold here: tests/v2/test_regex_sync.py pins
+# the 1.4 ledger's copy against _policy._SCRIPT_RANGES by hardcoded
+# filename, so THIS copy is unpinned. A span removed from the script
+# table forces the 1.4 rule to narrow, test-driven, while this twin
+# stays wide and starts classifying real regressions as intended. The
+# same gap covers the honorific alternations below, hand-copied from
+# SUFFIX_NOT_ACRONYMS and GLUED_HONORIFICS (both verified equal to
+# their sources 2026-08-05). Parametrizing those pins over every
+# expected_since_*.toml is the fix; it needs the #271/#272 selector
+# reworked first, since it asserts uniqueness and this file has two
+# such rules.
 name_regex = "[\\u3005-\\u3006\\u3040-\\u309F\\u30A0-\\u30FF\\u3400-\\u4DBF\\u4E00-\\u9FFF\\uF900-\\uFAFF\\uAC00-\\uD7A3\\uFF65-\\uFF65]"
 fields = ["given", "middle", "family", "_ambiguities"]
 
@@ -115,7 +126,7 @@ issue = "fix(#307/#308/#320) spaced CJK postnominal honorific routed to suffix"
 # ('田中 さん', '김민준 박사님') move here too, and #320 lets a trailing
 # ASCII period through ('김민준 씨.', '김민준 양.').
 #
-# Whole-token on the name STRING -- preceded by start, space or comma,
+# Whole-token on the name STRING -- preceded by a space or comma,
 # followed by end, space or comma, with #320's optional period between.
 # That anchor is what the 1.4 ledger's honorific rule exists to
 # explain: unanchored, any name ENDING in 양 or 군 would match, and a
@@ -124,11 +135,26 @@ issue = "fix(#307/#308/#320) spaced CJK postnominal honorific routed to suffix"
 # SUFFIX_NOT_ACRONYMS, written longest-first so '김민준 박사님' matches
 # 박사님 rather than stalling on 박사.
 #
+# The leading `^` alternative this rule used to carry has been REMOVED,
+# because it reopened at the head exactly the hole the tail anchor
+# closes. 양 and 군 are honorifics in trailing position and ordinary
+# SURNAMES in leading position -- Yang and Gun -- so '양 미선' matched
+# on its own surname. Today that name's diff is {given, family} and the
+# CJK order rule above claims it first, so nothing was misclassified;
+# but a future change routing the leading 양 to `suffix` would give
+# {given, family, suffix}, which is no longer a subset of that rule's
+# fields, and it would fall through to THIS rule -- whose fields do
+# include suffix -- and be reported as an intended honorific. A surname
+# silently reclassified as a suffix is the regression class this gate
+# exists to catch. A postnominal honorific is by definition not at the
+# start of the name, so nothing legitimate needs the head match:
+# dropping it leaves all 89 diffs classified (measured 2026-08-05).
+#
 # `middle` is in `fields` here where the glued rule omits it, and the
 # reason is measured: a three-token spaced name loses its middle to the
 # order flip while the honorific leaves ('田中 太郎 様' -> given 太郎,
 # family 田中, suffix 様; '김민준 박사 씨' likewise).
-name_regex = "(?:^|[ ,])(?:박사님|선생님|교수님|박사|씨|님|군|양|先生|女士|小姐|博士|教授|様|氏|殿|さん|さま|くん|ちゃん)\\.?(?=$|[ ,])"
+name_regex = "[ ,](?:박사님|선생님|교수님|박사|씨|님|군|양|先生|女士|小姐|博士|教授|様|氏|殿|さん|さま|くん|ちゃん)\\.?(?=$|[ ,])"
 fields = ["given", "middle", "family", "suffix"]
 
 [[change]]
@@ -196,4 +222,4 @@ issue = "fix(#298) 间隔号 division changes the comma reading, sending the cre
 # different rules in 2.1, and they are indistinguishable enough on
 # screen that a literal here would be unreviewable.
 name_regex = "(?s)(?=.*,)(?=.*\\u00B7)(?=.*[\\u3005-\\u3006\\u3040-\\u309F\\u30A0-\\u30FF\\u3400-\\u4DBF\\u4E00-\\u9FFF\\uF900-\\uFAFF\\uAC00-\\uD7A3\\uFF65-\\uFF65])"
-fields = ["given", "middle", "family", "title", "suffix"]
+fields = ["given", "family", "title", "suffix"]