fix(ledger): a canon may hold a class and the to_dict beside it (#4220)

The review surface shipped yesterday reported two canons on its first live
day and both were sound. Coherence was "do all judged rows share a form",
which #2844 failed at 37/62 = 0.597 for containing a model class and the
to_dict the canon's own text says the class must carry, and #2849 failed at
4/7 for pairing sync loop-starters with the async ticks they schedule. A
review surface whose whole output is noise is one that stops being read.

The obvious repair is a trap, and there is now a test standing in front of
it. Grouping by family and keeping a majority test makes the check BLIND:
before #2844 was cleaned by hand it held 37 classes and 56 callables, which
as families is 56/93 = 0.602 — a clean pass, and the 31 rows that had no
business being there (Vue functions, route handlers, a dozen tests) would
never have been reported at all. A looser bar in the same shape is worse
than the bug.

So the verdict is inverted. Instead of asking whether most rows agree, it
asks how many rows the canon CANNOT ACCOUNT FOR: a row in the majority
family is accounted for; a callable defined in a file that also holds a
majority-family `type` row is a method of a member, not a foreign body; and
strangers above a fifth of the readable rows make the canon incoherent. The
majority vote abstains those methods, so a class's own serialisers cannot
outvote the classes and turn the members into the strangers.

Measured on the real ledger before it was written, which is why it is this
rule and not a nudge to the share: clean #2844 has 0 strangers in 62,
#2849 has 0 in 7, and polluted #2844 had 31 in 93 — the same 31 withdrawn
by hand this morning, named exactly.

The entry now carries `families`, the majority `family`, `attached`,
`stranger_count`, `unattended`, and `strangers` — THE ROWS THAT DO NOT FIT,
replacing a sample of the first twelve members. The reader's question is
which rows are wrong, and a sample of the agreeing majority cannot answer
it. `unattended` is the discriminator between a check that is too strict and
a ledger full of junk: both canons flagged on day one were entirely
audit-judged, and nothing showed that without opening each one.

Scoped to the review surface. `canon_form` still answers at the precise form
level for stamping and divergence, where a sync helper beside an async canon
is a fair question; nothing here changes what the ledger writes.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01821k5B3Ysecp9fNYs92Kuy

tests/test_stamps_to_review.py

@@ -25,7 +25,8 @@ hook's own history is made of.
 import pytest
 
 from scribe.services.shape_ledger import (
-    _RESEMBLE_MIN, _RESEMBLE_REASON, stamp_score, stamps_to_review,
+    _RESEMBLE_MIN, _RESEMBLE_REASON, _REVIEW_ROWS_SHOWN, canon_coherence,
+    stamp_score, stamps_to_review,
 )
 
 
@@ -135,17 +136,26 @@ def test_a_canon_whose_members_agree_is_not_listed() -> None:
 
 def test_a_canon_whose_members_are_all_different_things_is_listed() -> None:
     """Portal's #3283, in miniature: a class, a getter, a test and a binding
-    recorded as instances of one pattern."""
-    rows = [_member("class SessionAbsent(RuntimeError):"),
-            _member("def build_channel() -> str:"),
-            _member("async def attach(self) -> None:"),
-            _member("MAX = 10")]
+    recorded as instances of one pattern — and in four different files, as
+    they really were. The paths matter now: a callable sharing a file with a
+    class is read as that class's method (#4220), so putting them all in one
+    file would test the excuse rather than the disagreement."""
+    rows = [_member("class SessionAbsent(RuntimeError):", path="src/errors.py",
+                    symbol="SessionAbsent"),
+            _member("def build_channel() -> str:", path="src/channel.py",
+                    symbol="build_channel"),
+            _member("async def attach(self) -> None:", path="src/attach.py",
+                    symbol="attach"),
+            _member("MAX = 10", path="src/limits.py", symbol="MAX")]
     out = stamps_to_review(rows)
     assert out["incoherent_count"] == 1
     entry = out["incoherent"][0]
     assert entry["snippet_id"] == 7 and entry["judged"] == 4
     assert set(entry["forms"]) == {"type", "fn", "async-fn", "binding"}
-    assert len(entry["sample"]) == 4
+    # The two callables carry the vote; the class and the binding are what
+    # the canon cannot account for, and they are what the reader is shown.
+    assert entry["family"] == "callable"
+    assert {s["symbol"] for s in entry["strangers"]} == {"SessionAbsent", "MAX"}
 
 
 def test_too_few_readable_members_says_nothing_either_way() -> None:
@@ -197,3 +207,146 @@ def test_the_service_carries_no_machinery_for_bulk_withdrawal() -> None:
     body = open(ledger.__file__).read()
     for banned in ("def retire_weak", "def auto_unclassify", "def bulk_withdraw"):
         assert banned not in body, banned
+
+
+# ── coherence is about what a canon CANNOT account for (#4220) ────────────
+#
+# The first version of this check asked whether every member shared a form.
+# On its first live day the only two canons it reported were both sound,
+# while the genuinely polluted one had already been cleaned by hand — a
+# surface whose whole output is noise is one that stops being read.
+#
+# The obvious repair — group by family, keep the majority test — is a trap,
+# and `test_family_grouping_alone_would_have_gone_blind` is the guard that
+# stops anyone walking back into it.
+
+def _model(sym, path):
+    """A SQLAlchemy model class, as #2844 holds one."""
+    return _member(f"class {sym}(Base, TimestampMixin):", path=path)
+
+
+def _to_dict(path):
+    """The serialiser that model is required to carry, beside it."""
+    return _member("def to_dict(self) -> dict:", path=path, symbol="to_dict")
+
+
+def test_a_class_and_the_to_dict_beside_it_are_one_shape() -> None:
+    """#2844 exactly: the SQLAlchemy model convention, whose own text is
+    about the class AND the to_dict it must carry. Live it scored
+    37/62 = 0.597 and was called incoherent for containing precisely what it
+    says it contains."""
+    rows = []
+    for i in range(6):
+        rows += [_model(f"M{i}", f"src/scribe/models/m{i}.py"),
+                 _to_dict(f"src/scribe/models/m{i}.py")]
+    out = stamps_to_review(rows)
+    assert out["incoherent_count"] == 0
+
+
+def test_a_sync_starter_and_the_async_tick_it_schedules_are_one_shape() -> None:
+    """#2849: four loop-starters and three ticks. `shape_family` already
+    collapses fn and async-fn for the divergence gate; this surface was the
+    one place still asking at form level."""
+    rows = [_member("def start_notification_loop() -> None:", path="src/n.py"),
+            _member("def start_log_retention_loop() -> None:", path="src/l.py"),
+            _member("def start_auth_token_retention_loop() -> None:", path="src/a.py"),
+            _member("async def _notification_tick() -> None:", path="src/n.py"),
+            _member("async def _retention_tick() -> None:", path="src/l.py"),
+            _member("async def _auth_token_retention_tick() -> None:", path="src/a.py")]
+    assert stamps_to_review(rows)["incoherent_count"] == 0
+
+
+def test_family_grouping_alone_would_have_gone_blind() -> None:
+    """THE REGRESSION GUARD. Polluted #2844 as it stood this morning: 37
+    model classes, 25 to_dict methods beside them, and 31 rows that had no
+    business being there. Counted as families that is 56 callables to 37
+    types — 0.602, a clean pass under any majority test. Those 31 rows are
+    the ones the surface exists to find, so a change that lets this canon
+    read as coherent has broken the feature while keeping every other test
+    in this file green."""
+    rows = []
+    for i in range(37):
+        rows.append(_model(f"M{i}", f"src/scribe/models/m{i}.py"))
+    for i in range(25):
+        rows.append(_to_dict(f"src/scribe/models/m{i % 37}.py"))
+    strangers = (["src/scribe/routes/rulebooks.py"] * 2
+                 + ["src/scribe/services/embeddings.py"] * 7
+                 + ["frontend/src/stores/rulebooks.ts"] * 3
+                 + ["tests/test_services_rulebooks.py"] * 19)
+    for i, path in enumerate(strangers):
+        rows.append(_member(f"async def f{i}():", path=path, symbol=f"f{i}"))
+
+    out = stamps_to_review(rows)
+    assert out["incoherent_count"] == 1, "the polluted canon must still be caught"
+    entry = out["incoherent"][0]
+    assert entry["families"]["callable"] > entry["families"]["type"]
+    assert entry["family"] == "type", "methods must not outvote their classes"
+    assert entry["attached"] == 25
+    assert entry["stranger_count"] == len(strangers) == 31
+    # The listing is capped, the count is not — a reader must be able to
+    # tell twelve strangers from thirty-one.
+    assert len(entry["strangers"]) == _REVIEW_ROWS_SHOWN
+    assert all(not s["path"].startswith("src/scribe/models")
+               for s in entry["strangers"])
+
+
+def test_a_callable_in_a_file_with_no_class_is_a_stranger() -> None:
+    """The excuse is "method of a member", not "callable anywhere". Without
+    this, any function in the repo would be excused by the existence of a
+    class somewhere else in the canon."""
+    rows = [_model("A", "src/models/a.py"), _to_dict("src/models/a.py"),
+            _model("B", "src/models/b.py"), _to_dict("src/models/b.py"),
+            _member("def helper():", path="src/services/free.py", symbol="helper"),
+            _member("def other():", path="src/services/free.py", symbol="other")]
+    out = stamps_to_review(rows)
+    assert out["incoherent_count"] == 1
+    assert {s["symbol"] for s in out["incoherent"][0]["strangers"]} == {"helper", "other"}
+
+
+def test_the_strangers_are_named_not_a_sample_of_the_majority() -> None:
+    """The reader's question is which rows are wrong. A sample of the
+    agreeing majority cannot answer it, which is what the first version
+    returned."""
+    # Seven and two: 2 of 9 is over `_STRANGER_SHARE`, 2 of 11 is under it.
+    # The tolerance is real and the counts here sit deliberately on the far
+    # side of it — see the test below for the near side.
+    rows = [_member("async def a():", path=f"src/ok{i}.py", symbol=f"a{i}")
+            for i in range(7)]
+    rows.append(_member("class Odd:", path="src/odd.py", symbol="Odd"))
+    rows.append(_member("class Odder:", path="src/odder.py", symbol="Odder"))
+    out = stamps_to_review(rows)
+    assert out["incoherent_count"] == 1
+    assert {s["symbol"] for s in out["incoherent"][0]["strangers"]} == {"Odd", "Odder"}
+
+
+def test_a_single_odd_row_in_a_large_canon_is_tolerated() -> None:
+    """One stranger in twenty is a row to fix, not a canon that has stopped
+    meaning anything. The surface is for the second thing."""
+    rows = [_member("async def a():", path=f"src/ok{i}.py", symbol=f"a{i}")
+            for i in range(19)]
+    rows.append(_member("class Odd:", path="src/odd.py", symbol="Odd"))
+    assert stamps_to_review(rows)["incoherent_count"] == 0
+
+
+def test_an_incoherence_made_of_judged_rows_says_so() -> None:
+    """The discriminator that tells a too-strict check from a bad ledger.
+    Both canons flagged on the first live day were entirely audit-judged,
+    and a reader could not see that without opening each one."""
+    judged = [_member("async def a():", path=f"src/j{i}.py", symbol=f"a{i}")
+              for i in range(4)]
+    judged += [_member("class J:", path="src/jc.py", symbol="J"),
+               _member("class J2:", path="src/jc2.py", symbol="J2")]
+    out = stamps_to_review(judged)
+    assert out["incoherent_count"] == 1
+    assert out["incoherent"][0]["unattended"] == 0
+    assert out["incoherent"][0]["weak_rows"] == 0
+
+
+def test_the_coherence_verdict_reads_rows_and_writes_nothing() -> None:
+    """`canon_coherence` is called on live ORM rows; it must not touch them."""
+    rows = [_model("A", "src/models/a.py"), _to_dict("src/models/a.py"),
+            _member("def loose():", path="src/x.py", symbol="loose")]
+    before = [(r.path, r.symbol, r.status, r.snippet_id, r.signature) for r in rows]
+    canon_coherence(rows)
+    assert [(r.path, r.symbol, r.status, r.snippet_id, r.signature)
+            for r in rows] == before