diff --git a/tools/doc_census_check.py b/tools/doc_census_check.py index cd61f90..3b36362 100644 --- a/tools/doc_census_check.py +++ b/tools/doc_census_check.py @@ -42,14 +42,56 @@ WHAT IT MEASURES (read-only: this tool only writes --json) A claim is ` ` with the unit word ADJACENT, which is the archive's own notation. A bare number is not a claim and is not checked. +TWO ORACLE LEGS, AND WHY THE SECOND ONE EXISTS + Leg 1 is the tool's own run at the block's revision, exactly as above. Leg 2 + is the SAME TOOL'S `--selftest`, added 2026-10-16 after the control plane + returned a docstring claim of `13 cells` against a selftest that prints `18 + cells` -- the defect class this tool exists to catch, sitting inside its own + default scope and still read as NOT_PRINTED, because no leg ever passed + `--selftest` and a cell count is printed by nothing else. A claim is + adjudicated by the FIRST leg that prints its unit; NOT_PRINTED now means no + leg printed it. A tool that takes no `--selftest` simply has one leg -- a fact + about the tool, not a defect in it. + + A leg that exits non-zero having printed nothing is reported RUN_FAILED, never + read as an empty census, and it adjudicates nothing either: the block's claims + are still read off any surviving leg -- leg 2 -- and are left unadjudicated + only when no leg survives, because a failed run is not a reason to stop + looking. A revision that will not materialise fails the same way rather than + producing a census at all: an empty queue is a census of zeros, and reading it + as that revision's census is the phantom this rule refuses (measured + 2026-10-16 against a sha256 prefix read as a revision). + + The run leg is `