fix(snippets): an annotated record is not a diverged one — a standing verdict vouches at its commit (#2782)

Pull-time freshness confirms a cached body by containment: normalised cached
code must appear inside the fetched file. That is right for a record kept
verbatim and permanently wrong for a deliberately annotated one. A record
whose job is to say WHY the shape is what it is carries commentary the source
does not, so containment fails on every pull, forever — #2508 was reading
`diverged` although its declarations match the source exactly, and always
would. Annotation is a sanctioned record style, so this was two deliberate
designs colliding, and it was quietly poisoning the one honest drift signal:
decision #2707's scoreboard watches body_freshness for `diverged` and was
accruing false positives it could never age out.

The escape hatch is the verdict itself. verify_snippet is exactly where a
human or agent already judged this body a faithful rendering of that source,
and `verification.commit_sha` records the repo commit they judged it at — a
field whose own docstring (#2688) anticipated this: "makes 'the REPO moved on
since the check' computable, once the forge integration can compare it against
the current head." This is that comparison. When containment fails, a standing
verdict can still vouch, on four conditions and no fewer:

  - the verdict says `ok`;
  - it has not EXPIRED — verification_view recomputes code_sha against the
    record's current body, so editing the record retires the verdict;
  - it was not INVALIDATED by a push touching the location (#2691);
  - the file just fetched is at the very commit the verdict was stamped at.

That last one is what keeps it honest: the hatch vouches for a body against
ONE known commit, never against whatever the source became since. The moment
the file moves, containment resumes as the authority and the record reads
`diverged` until someone re-verifies — correct, because at that point nobody
has looked. The first three are checked by reusing verification_view rather
than restating its rule, so "expired" keeps meaning one thing.

Nothing is rewritten and no new freshness value is minted; `verification`
already travels in the same payload, so a reader can see the basis rather
than take "current" on faith. Verdicts predating commit stamping carry no
commit to compare and therefore do not vouch — they fall through to
containment rather than passing on age alone.

Tests pin the fix and, more usefully, every condition that switches it back
off: moved commit, expired verdict, push-invalidated verdict, non-ok verdict,
no verdict, and a pre-#2688 verdict with no commit_sha. Plus a regression
that a verbatim record still takes the containment path untouched.

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

tests/test_snippet_live_body.py

@@ -272,3 +272,89 @@ async def test_forge_failure_inside_lookup_never_breaks_the_pull():
         data = _data()
         await svc.attach_live_body(_note(), data)
     assert "body_source" not in data
+
+
+# --- #2782: an annotated record is not a diverged one ------------------------
+# Containment is right for a verbatim record and wrong for a deliberately
+# annotated one: the commentary that makes the record worth reading is exactly
+# what makes `cached in fetched` false, forever. These pin the escape hatch —
+# a standing `ok` verdict stamped at the commit we just fetched — and, just as
+# importantly, every condition that must switch it back off.
+
+ANNOTATED = "# Membership is the contract — this record says WHY, the source can't.\n" + CODE
+
+
+def _ok_verdict(code=ANNOTATED, commit=SHA, **extra):
+    verdict = svc.compose_verification(
+        status=svc.VERIFY_OK, checked_code_sha=svc.code_sha(code), commit_sha=commit
+    )
+    verdict.update(extra)
+    return verdict
+
+
+async def _freshness(data, *, file_commit=SHA, content=CODE):
+    forge = _forge_with(lambda r: _file_response(content, commit_sha=file_commit))
+    with _patched(forge), patch.object(svc.notes_svc, "update_note", AsyncMock()):
+        await svc.attach_live_body(_note(), data)
+        await background.drain()
+    return data["body_source"], data["body_freshness"]
+
+
+async def test_annotated_record_with_a_standing_verdict_reads_current():
+    """The bug: the record's commentary is absent from the source, so
+    containment fails and every pull said `diverged`. A verdict that already
+    judged this body faithful, at this very commit, outranks the substring."""
+    data = _data(code=ANNOTATED, verification=_ok_verdict())
+    assert await _freshness(data) == ("forge", "current")
+    assert data["snippet"]["code"] == ANNOTATED     # still never rewritten
+
+
+async def test_the_verdict_vouches_for_one_commit_only():
+    """The guard that keeps the hatch honest. The file has moved past the
+    commit the verdict was stamped at, so nobody has judged what is there
+    now — containment resumes as the authority and the record reads diverged
+    until someone re-verifies."""
+    data = _data(code=ANNOTATED, verification=_ok_verdict(commit="a" * 40))
+    assert await _freshness(data) == ("cache", "diverged")
+
+
+async def test_an_expired_verdict_does_not_vouch():
+    """The record was edited after the check, so `code_sha` no longer matches
+    and the verdict describes a body that is not this one."""
+    data = _data(code=ANNOTATED, verification=_ok_verdict(code="def other(): pass"))
+    assert await _freshness(data) == ("cache", "diverged")
+
+
+async def test_a_push_invalidated_verdict_does_not_vouch():
+    """A push touched the recorded location since the check (#2691) — the repo
+    moved under the verdict even though the record didn't."""
+    data = _data(code=ANNOTATED, verification=_ok_verdict(invalidated_by="c" * 40))
+    assert await _freshness(data) == ("cache", "diverged")
+
+
+async def test_only_an_ok_verdict_vouches():
+    """A drifted verdict is evidence AGAINST the body, not for it."""
+    verdict = svc.compose_verification(
+        status=svc.VERIFY_CHANGED, checked_code_sha=svc.code_sha(ANNOTATED), commit_sha=SHA
+    )
+    data = _data(code=ANNOTATED, verification=verdict)
+    assert await _freshness(data) == ("cache", "diverged")
+
+
+async def test_a_verbatim_record_still_takes_the_containment_path():
+    """No regression: the happy path does not route through the hatch, and an
+    unverified verbatim record is still confirmed by containment alone."""
+    data = _data(code=CODE)
+    assert await _freshness(data) == ("forge", "current")
+
+
+async def test_a_verdict_predating_commit_stamping_does_not_vouch():
+    """Verdicts recorded before `commit_sha` existed (#2688) carry no commit to
+    compare, so they cannot tie the body to a known state of the source. They
+    fall through to containment rather than vouching on age alone."""
+    verdict = svc.compose_verification(
+        status=svc.VERIFY_OK, checked_code_sha=svc.code_sha(ANNOTATED)
+    )
+    assert "commit_sha" not in verdict
+    data = _data(code=ANNOTATED, verification=verdict)
+    assert await _freshness(data) == ("cache", "diverged")