From f84489f86c201037c192f2e75971196cd640eeed Mon Sep 17 00:00:00 2001 From: "Joshua D. Drake" Date: Wed, 16 Sep 2026 08:57:56 -0600 Subject: [PATCH] docs: orphan-scan names the precondition it cannot check (#983, #1015) A stale log and a genuinely deleted check are INDISTINGUISHABLE to orphan-scan. Both present as "the ledger has a row and the log has no record for it", and nothing in a RESULT record -- suite, part, name, verdict, major -- dates it against a tree. So this is not a gap the subcommand can close; it is a correctness condition belonging to the caller, and the docstring described neither. MET RATHER THAN IMAGINED. Replaying a log from #1070's tree against the ledger one commit later reported `orphans=2`, and both were the part-400 checks that tree had just gained. I was one step from reporting a defect in the tool I had merged an hour earlier. Re-running against a log from the same tree gives 0. WORTH WRITING DOWN BECAUSE THE RUNNER ALREADY SATISFIES IT AND THE NEXT CALLER MAY NOT. `run_all_versions.sh` passes the logs from the run it has just finished, so freshness is structural there -- nobody chose it, the shape of the call guarantees it. A human invoking the subcommand by hand, which is what I did, has no such guarantee. Those are different safety properties and only the first is free. Wording proposed by @OffgridwithJD, who also made the point that this is a precondition rather than a caveat: a stale log produces exactly the signal the subcommand exists to find. NOT FIXED HERE, deliberately. Making it checkable means a log carrying something that identifies the tree -- the `.so` fingerprint the harness already computes would do -- and orphan-scan refusing a log whose fingerprint does not match. That is a larger change than this one and belongs to whoever needs a second caller. No CHANGELOG entry and no ledger regeneration: this adds no check and changes no behaviour. Verified no arm asserts on this docstring -- the one hit in part 410 is a comment. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01NhwXKAgSmYDUjteWkfajHK --- test/pgc_ledger.py | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/test/pgc_ledger.py b/test/pgc_ledger.py index ab50f1ea..21654f7d 100755 --- a/test/pgc_ledger.py +++ b/test/pgc_ledger.py @@ -567,6 +567,23 @@ def cmd_orphan_scan(args): list and ignores the second manufactures the confidence that the thing is handled. + SCANNED AGAINST A LOG OF THE SAME TREE, which this cannot check and the caller + must. A row whose check was ADDED after the log was written has no record in it + and is reported as an orphan -- the same signal as a check that was DELETED, and + nothing in a RESULT record (suite, part, name, verdict, major) dates it against a + tree, so the two are indistinguishable here. + + `run_all_versions.sh` satisfies this STRUCTURALLY: it passes the logs from the run + it has just finished, so nobody chooses freshness and the shape of the call + guarantees it. A caller supplying a log by hand has no such guarantee and must + check it themselves. Those are different safety properties and only the first is + free. + + Measured: a log from #1070's tree replayed against the ledger one commit later + reported `orphans=2`, and both were the part-400 checks that tree had just gained. + A stale log produces exactly the signal this subcommand exists to find, which is + why it is a precondition and not a caveat. + SCOPED TO THE PARTS THE RUN CONTAINS, and the scope is REPORTED, not assumed. A one-suite log has nothing to say about another suite's rows. Counting those as present would make a single-suite run certify the whole ledger, so they are