test: a ledger of which checks have ever been red (#918)

[jdatcmd]

Closes #918 — phase 4 of #858, the last of the three. Stacked on #923; base is feat/917-machine-readable-results, so review in order.

The honest version, and why that is the finding

Nothing recorded whether a check had ever been red. That is the gap that let 39 checks across 35 suites ship unable to fail, three of them inside the suite whose whole purpose is to stop exactly that.

This ledger records that a named check was observed red in a recorded run. It does not claim the check is proven able to fail. That is a stronger statement, it needs a named mutation applied deliberately, and conflating the two would put a claim in the ledger that nothing measured — the defeated: 0 shape from VACUITY_MODES §1, a number that reads as evidence and is not.

So every entry currently reads never. #918 asks "nothing records whether a check has ever been red", and what this ships answers "and now something records that almost nothing has". A ledger of 608 rows, none ever observed red, is a measurement of how much of the corpus has never been attacked — and that measurement is worth having on day one.

What fills it

Not only deliberate mutation runs. Every real CI red fills it, every flake, every bisect — and those arrive whether anyone remembers to run something or not. A mutation run is the deliberate accelerator, not the only source. Worth stating, because "only a mutation run can retire debt" invites someone to build a mutation gate before it is needed.

The format

suite <TAB> check name <TAB> last observed red <TAB> mutation

The mutation column exists from v1 with nothing filling it automatically, because adding a column later means rewriting every entry. If an entry can record which mutation reddened a check, the catalogue a mutation gate would need builds itself out of work people already do by hand.

Two losses that are reported rather than prevented

A rename. The ledger is keyed by check name, and names here are prose that gets rewritten freely — most of why #917 exists. So a rename loses the check's history and reads exactly like a brand-new check that has never been red: the one state this ledger exists to distinguish. It cannot be prevented without a synthetic id someone would have to maintain, and this repository removed a hand-maintained list today for that reason. So a name that appeared while another disappeared is named. Both directions are required — reporting a rename on every added check is noise that gets it ignored.

A duplicated name. Two checks with the same name in one suite share a row, so one going red would mark both as observed red. Reported for the same reason. The corpus carries four today, which is how it was noticed: 612 records reduce to 608 rows.

The debt is two tracked files

Per #858's own constraint. test/check_ledger.tsv and test/check_ledger_budget.txt are in the tree, so a change to either is a diff a reviewer sees. PGC_SKIP_TIMING is the precedent for why this is not an environment variable: set in two workflow files, it suppressed whole suites for months and no diff ever showed it. Both numbers may only go down.

checks_never_observed_red 608
suites_not_covered        250

The second is the one that is easy to forget, and it is a real limit. The ledger can only be seeded from suites whose logs exist, and the matrix does not preserve them — so 250 of 251 suites have no rows at all, and the gate cannot refuse a new check in a suite it has never seen. Counting it separately stops "we ledger 608 checks" reading as "we ledger the corpus". It burns down as suites are seeded.

The gate refuses a check the ledger has never seen, so a new one cannot enter as silent debt — while the existing 608 are grandfathered, because a gate that fails on 3,762 unledgered sites is one somebody disables under deadline, and then we are back at PGC_SKIP_TIMING with extra steps.

Evidence

selftest    exit=0  FAILs=0   612 checks
            ledger: inputs=608 | observed red=0, never=608 | sum=608
gate        rc=0 against the committed files
            rows=608 | never observed red=608, budget=608, new=0
            registered=251 | covered=1, not covered=250, budget=250
pytest      27 passed
shellcheck  rc=0    docs_style  PASSED

What I did not build, deliberately

A harness-driven mutation gate. It needs a mutation catalogue per check to be anything other than random line-deletion, and that catalogue does not exist in machine-readable form yet — it is being hand-written, nine to eleven mutations per change, in the vacuity work happening now. This ledger is the right place for it to start accumulating, which is why the column is here. Building the gate first would be building the machine before the input.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Unuuvh3fRR67SceiGpfeeK

[OffgridwithJD]

Reviewed 671a9460. One finding, in the rename detector, and it defeats the detector in exactly the case it exists for. Everything else I could attack held up, and I am listing what I verified so nobody re-checks it.

The finding: zip pairs by position, so one unrelated appearance hides a genuine rename

cmd_rename_scan builds two sorted lists and pairs them positionally, then discards pairs whose parts differ:

for (s_a, p_a, n_a), (s_v, p_v, n_v) in zip(appeared, vanished):
    if (s_a, p_a) != (s_v, p_v):
        continue

So an appearance in an earlier-sorting part consumes the slot and the rename in a later part is never examined. Measured, with a control:

ARM 1  partB renamed (old-b -> zzz-renamed, history: last red 2026-01-01)
       AND partA gained an unrelated check
         rename scan: appeared=2, vanished=1
         rc=0                                   <- nothing reported

ARM 2  the SAME rename, unrelated appearance removed
         possible rename: old-b -> zzz-renamed (in selftest/partB, history: last red 2026-01-01)
         rename scan: appeared=1, vanished=1
         rc=1                                   <- correctly reported

The rename is detectable; what hides it is an unrelated check appearing in a part that sorts earlier. partB's history then resets to never silently, which is the one state this ledger exists to distinguish — and the more parts move in a single run, the more renames are lost.

Worth saying plainly: your own real-data run reported its rename because both appeared entries happened to be in part 340, so zip's first pair matched. The ordering was lucky, not load-bearing.

The fix is to group before pairing rather than filtering after:

from collections import defaultdict
app, van = defaultdict(list), defaultdict(list)
for s, p_, n in appeared: app[(s, p_)].append(n)
for s, p_, n in vanished: van[(s, p_)].append(n)
for key in sorted(set(app) & set(van)):
    for n_v, n_a in zip(sorted(van[key]), sorted(app[key])):
        ...

And the arm that would have caught it is the one the current tests lack: a fixture where two parts move in the same run. Every existing arm moves one part at a time, which is why ARM 2 passes and ARM 1 does not.

I also confirmed the inherent false positive is still there and still acceptable: an unrelated add and delete in one part reports possible rename: deleted-check -> brand-new-unrelated, carrying the deleted check's last red 2025-12-31. That is unavoidable without a synthetic id, you say "possible rename" rather than "rename", and the alternative is silently resetting — so it is the right trade. It is worth one sentence in the docstring that the pairing is positional within a part and therefore a guess between two movers.

What I verified and found sound

Idempotence. Merging the same run twice leaves the ledger byte-identical. A later date on an already-red check advances it (2026-09-10 → 2026-09-11), and a subsequent GREEN run does not erase the history. Those are the three semantics "last red" needs and all three hold.

The gate has teeth. A record with no ledger row is refused by name — not in the ledger: selftest partA SNEAKY-NEW, rc=1 — with the control at rc=0 when only the known check is present. So "the gate cannot refuse a new check in 250 of 251 suites" is a coverage limit, not an inert gate.

The key. 614 records, 614 distinct keys, zero collisions. Deriving the part from BASH_SOURCE rather than from a declaration is the better half of that fix, because it cannot go stale the way a convention can. And the part derivation adds no fork: five command substitutions inside pgc_record, all five $(( )) arithmetic, at 3,762 call sites.

The 340 rename you took from my finding reads correctly now — 268 is the partition fixture's premise and 894 is the locale sweep's, and they are two different sentences about two different code paths rather than one sentence shared.

Two smaller things

test/selftest/410-a-check-must-have-been-red.sh collides with a part of mine. My sentinel branch already holds 410, gated, and four others hold 420-460. A duplicate numeric prefix breaks nothing — the parts are sourced from a sorted glob of distinct files — so this is tidiness. But moving one file in an unreviewed PR is cheaper than re-gating six branches, so I would rather you took 470 and I kept 410-460. If you would rather not, say so and I will shift mine at rebase; I am not going to argue about a prefix.

The suites_not_covered wording is right now. Stating the operational consequence — the gate cannot refuse a new check in 250 of 251 suites — is what stops "614 checks" reading as "the corpus". Keep the count separate from the row count exactly as it is.

Not approving yet, on the rename finding alone. It is a six-line fix plus the two-parts-move arm, and I will approve as soon as both are in — the rest of this PR is in good shape, and seeding from a green run rather than from a half-built feature's reds was the right call for the reason you gave.

[linuxhikerpm]

Blocking at exact head 671a946059ddaf88b3289d28ee891c20ab8fdb0d: the ledger is not yet an operational or fail-closed gate.

1. pgc_ledger.py is never invoked by the runner or CI. No workflow consumes gate, merge, or rename-scan, and runner logs are deleted. CI reds therefore cannot populate the ledger and the gate cannot reject a new check.

2. Missing/malformed inputs false-green. read_records() ignores unreadable files, short records, and unrecognized content. Reproduced rc=0 for a nonexistent log, an empty log, and a known record missing its verdict. Require nonempty reconciled input and fail closed on read/parse errors.

3. Mutation attribution is invocation-wide. One --mutation value is copied to every failure in every input log; two independent failures merged with MUTATION_A both acquired that mutation. The issue requires per-check attribution derived from the run.

4. Multi-log handling is incorrect. Two ordinary logs containing the same check are reported as a duplicate. A rename detected with the after-log alone disappears when before+after are supplied. Global positional zip(appeared, vanished) also misses a real rename when unrelated movement in other parts shifts ordering; group by (suite, part) before pairing and distinguish runs when checking duplicates.

5. The tracked budgets are not monotonic. Debt=2 passes with budget 2 and still passes after increasing the committed budget to 999. suites_not_covered can also be bypassed by omitting optional --registered. Compare against the prior tracked ceiling and require registry input for coverage claims.

6. git diff --check reports 632 trailing-whitespace errors, including all 614 ledger rows because an empty mutation is encoded as a trailing tab.

The (suite, part, name) key improvement is sound and fixes cross-part collisions, but the paired tests use only valid single logs and do not exercise these failure modes. Please add both shell and pytest red/control arms for each integrity boundary and wire the resulting gate into retained runner/CI artifacts.

[linuxhikerpm]

Two additional exact-head findings from the full adversarial pass:

1. last red can move backward or become unknown. cmd_merge blindly overwrites the prior date for every FAIL. Reproduced by merging observations dated 2026-09-10, then 2026-09-01: the ledger regressed to 2026-09-01; a subsequent merge without --date replaced it with unknown. Validate observation dates and retain the maximum known timestamp.

2. The required shell twin can disappear without detection. Deleting test/selftest/410-a-check-must-have-been-red.sh does not red another gate: harness_selftest.sh sources whatever glob entries remain, while the pytest half is not itself run by current CI. Add a mechanically reconciled manifest/twin check so removing either behavioral half fails.

These supplement the changes-requested review at the same head; the existing six blockers still stand.

[OffgridwithJD]

Adversarial pass on 671a9460. Three findings, in descending order of how much they matter. The rename-pairing defect reported earlier is separate and still stands.

1. The mutation column silently overwrites, so it cannot accumulate a catalogue

That column exists so the mutation catalogue builds itself out of work people already do by hand. It keeps only the last one:

merge --date 2026-09-10 --mutation "M1 first"    ->  selftest partA c1  2026-09-10  M1 first
merge --date 2026-09-11 --mutation "M2 second"   ->  selftest partA c1  2026-09-11  M2 second

No warning, no append, no record that M1 ever existed. A check that two different mutations reddened ends up claiming one of them, and which one depends on run order. That defeats the stated purpose rather than limiting it: six branches of mine carry 55 one-property mutations with their reddened arms named, and merging those runs one at a time would leave a single mutation per check.

The fix is a decision, not code: either the column is a set (append, deduplicated) or it is explicitly "the most recent mutation that reddened this check" and the docstring says so. I would take the set — the value is in the accumulation — but either is honest and the current state is neither.

2. Drift is one-directional: a ledger row whose check no longer exists is kept silently

ledger:  selftest partA still-here        never
         selftest partA DELETED-LONG-AGO  2025-01-01
records: RESULT selftest partA still-here PASS

gate  -> ledger gate: rows=2 | never observed red=1, budget=614, new=0     rc=0
merge -> the DELETED-LONG-AGO row is still there, still carrying 2025-01-01

The gate reports new (records with no row) and refuses them. It never reports the other direction, and merge never prunes, so dead rows accumulate and rows drifts upward from the corpus. That matters because the budget numbers are counted over rows: a dead row that was once red makes checks_never_observed_red look better than the corpus warrants, and a dead row that was never red inflates the debt. Either way the number stops being about the corpus.

rename-scan does compute vanished, so the information exists — it is just not on the gate's path and nothing prunes. Reporting dead rows (rather than failing on them, for the reason you gave about a gate that reddens when someone fixes something) would be consistent with how you handled stale debt.

3. A stale number inside the file whose whole subject is stale numbers

test/check_ledger_budget.txt explains suites_not_covered with: "Counted separately so that 'we ledger 605 checks' cannot read as 'we ledger the corpus'." The file's own value two lines below is checks_never_observed_red 614. The illustrative number is the pre-rename count.

Trivial to fix and worth fixing precisely because of where it is.

On the budget file being typed at all

I went looking for this as a defect and came away agreeing with it, so I will say so. checks_never_observed_red 614 and suites_not_covered 250 are hand-maintained numbers, which is normally the thing #908 spent a day removing — but the file argues its own case and the argument is right: a tracked file makes a change to the debt a diff a reviewer sees, where an environment variable would not, and PGC_SKIP_TIMING suppressing whole suites for months with no diff is the precedent. The "both numbers may only go down" rule is what makes a typed number safe here, because raising one has to read as adding debt. Keep it.

Verified and sound

Merging one run twice is byte-identical. A later date advances last-red; a subsequent green run does not erase it. A mutation supplied on a run where the check stayed green is correctly not recorded. The gate refuses a record with no ledger row by name, with a control at rc=0. 614 records give 614 distinct keys after the 340 rename, and the key's part comes from BASH_SOURCE rather than a convention.

One merge note, recorded here rather than only in messages: test_mutation_ledger.py is database-free, so once #921 is in main this PR needs "test_mutation_ledger.py" in NO_CLUSTER in its own diff.

[OffgridwithJD]

Treated as new, as you asked. I ran the thing the redesign turns on — a real PG 17 matrix on 2289f10d — and the central claim holds. One finding, about the sentence the design is most confident in, and one blocker that is not about the code at all.

The blocker: CI is not running, and will not start

mergeStateStatus=DIRTY, mergeable=CONFLICTING. GitHub does not run workflows on a conflicted PR, so the newest run on this branch is for 671a9460 — the old head. 2289f10d has no run.

The cause is the base. This PR targets feat/917-machine-readable-results, not main, and that branch moved when #923 gained its CHANGELOG entry at dddee7fc. Measured:

merge 2289f10d into main                               CLEAN
merge 2289f10d into feat/917-machine-readable-results  CONFLICT (content): CHANGELOG.md
merge 2289f10d into feat/916-reconcile-accounting      CLEAN

One file, one region: your entry and #923's under the same heading.

It is fed, and I can prove it from a real run

Full test/run_all_versions.sh on /usr/local/pg17a, tree asserted clean at 2289f10d, under the lock, with ci.yml's environment (PGC_SKIP_TIMING=1 PGC_JOBS=4 PGC_REQUIRE_ISOLATION=1):

  ledger census: rows=638 | never observed red=638, ever red=0, new this run=0
  ledger coverage: registered=251 | covered=1, not covered=250, ceiling=250
  suites that ran: 242 of 251 (skipped: 9, incomplete: 0)
ALL VERSIONS PASSED
RUN_ALL_VERSIONS_RC=0

So the gate reached the real logs of a real matrix, and new this run=0 says the committed ledger already covers every check that ran. Note not covered=250 sits exactly on the ceiling of 250, which is the tight place to be: one newly registered suite that nobody seeds reddens it.

And the refusal works. Driven with a record the ledger has never seen, in a covered suite:

    not in the ledger: harness_selftest	030-assertions	a check nobody has ever written
    1 check(s) the ledger has never seen. Regenerate it with: ...
  rc=1

Fail-closed holds where you said it does — a nonexistent log, an empty log, a malformed record, and a missing --registered are all rc=2, distinguishable from the rc=1 refusal. rename-scan groups by (suite, part): two parts each renaming a check in one run produces two correctly paired renames rather than the positional mis-pairing, and a before+after union in one call is refused with rc=2. The ledger is LC_ALL=C sorted, so an added check inserts at a content-decided point — the #554 lesson, and it matters now because every PR that adds a harness_selftest check regenerates this file.

The finding: "the ceiling may only fall" is true of the tool and false of the wiring

check_ledger_budget.txt says "the gate compares this value against the previously committed one and refuses an increase, so widening the debt is an edit a reviewer sees AND a gate refuses." The second half does not happen in any wired invocation.

The monotone block is guarded by if args.against:. run_all_versions.sh:1336-1340 passes --ledger, --budget, --registered and the logs. No --against. Measured, with suites_not_covered edited from 250 to 9999 in the tracked file:

invocation	rc
the runner's exact form, no --against	0	the raise is not refused
--against HEAD, absolute path (what the runner passes)	0	no budget at HEAD, so there is no prior ceiling to compare
--against HEAD, repo-relative path	1	suites_not_covered was raised from 250 to 9999: the ceiling may only fall

So the tool is right, and 410's scratch-repo arms prove it. What nothing does is compare the real committed budget against git.

And adding the flag at that call site does not fix it. _committed_budget runs git show <ref>:<path>, the runner passes "$builddir/test/check_ledger_budget.txt", and git cannot resolve an absolute path as a pathspec — it returns None and the gate prints a line that reads like a pass. That is row two of the table, which is the form the fix would actually take.

The arm that closes it belongs where the repository is rather than where the build copy is: compare the working budget against git show HEAD:test/check_ledger_budget.txt, repo-relative, in the real tree, and redden on an increase. This is the same shape as the finding one level down — a gate nothing invokes — with "nothing invokes it with the argument that makes it a gate" in place of "nothing invokes it".

What I checked and am not relitigating

The runner does invoke the gate, it runs before rm -rf "$builddir", and a refusal sets verfail=1; I read all three and the static arms at 410:231-237 pin them. The committed census matches the committed ledger — 638 rows, 638 never, and 410:251-252 asserts that against the real files, not fixtures. Every row has five fields and none ends in a tab.

On shape, since you asked

The census/ceiling split is right, and the reason is stated correctly: every new check enters as never, so bounding it makes landing a check require raising a number the file says may only fall. That is a deadlock, not a budget. I also think jd's refusal of the half-landing was right, and the restriction of the refusal to covered suites is the meaning of suites_not_covered rather than a softening — your own arm that a new check in a now-covered suite is refused again is what makes that a tightening.

One consequence worth naming out loud: today the ledger covers one suite, so the gate refuses unknown checks in harness_selftest and nowhere else. That is the acknowledged debt, and the ceiling is what forces it down. It also means my #926 will redden your gate the moment both land, because it adds six checks to selftest 080 — intended workflow, reviewable diff, mentioned only so the merge order surprises neither of us.

A main-tree defect this run surfaced, which is not yours to fix here

The same report prints two different "accounted" totals:

  population reconciliation: registered=251 | accounted=237, not dispatched=4, known debt=10, unaccounted=0 | sum=251
  of those, 235 accounted for their checks and 7 did not

237 and 235, differing by exactly 2. The population line uses the wide reader (pgc_log_shows_any_accounting) and the breakdown line derives from the narrow one (pgc_log_shows_accounting), so the same question gets two answers three lines apart and a reader cannot tell which is the claim. The gap of 2 is the two suites that keep their own tally rather than lib.sh's — bench_guards and docs_style — which is the count I measured independently earlier today from the other direction. This came in with #922 and is on main now, so I will raise it there rather than add it to your pile.

[OffgridwithJD]

The CI half of the origin/main finding is now measured rather than argued, from this PR's own run.

suites (PG 17) of run 34502198282, at fb872370, verbatim:

  origin/main does not resolve here, so the ledger ceiling is
  ledger census: rows=675 | never observed red=675, ever red=0, new this run=0
  ledger coverage: registered=251 | covered=1, not covered=250, ceiling=250
    ceiling against HEAD: 250 -> 250, which does not rise

So in CI origin/main did not resolve, the fallback to HEAD fired, and the comparison was 250 -> 250 — a committed file against itself, which catches nothing for any change under review. The ceiling protection was inert in the only place this gate runs for real, with a line above it that reads like enforcement. I had called my local reproduction a construction rather than proof; this is the proof, and it is stronger than the prediction.

Fixed at 3d880f49 (--against auto: GITHUB_BASE_REF in CI, main@{upstream} outside, an error if neither), with the fallback removed and ci.yml fetching the base at depth 1.

One residual on the non-CI path, measured in the clone the new docstring cites:

main@{upstream}    = origin/main
resolves to        = 93a2eda   2026-08-25
branch.main.remote = origin            (my fork)
author/main        = f0f1f40   2026-09-10
origin/main is 446 commits behind author/main

main@{upstream} is origin/main here, because git push -u origin main is what writes that config and origin is the contributor's fork. So auto outside CI resolves to the same stale ref the hardcoded version did — the route changed, the destination did not. It is materially better, because the ref used is now printed and a reader can see origin/main; what a reader cannot see is that it is 446 commits behind, and the direction is still the permissive one.

I am not arguing for a different ref — "the configured upstream of the local main" is the right answer to "which main is mine" and I cannot see a better one that does not guess. I would add the distance:

git rev-list --count <prior>..HEAD

printed beside the ref. "comparing against origin/main (446 commits behind HEAD)" tells the reader what the comparison is worth; "comparing against origin/main" does not. Same move as printing the ref, one step further, and it costs nothing when the number is zero.

Everything else in my earlier review stands as written, including the matrix evidence on 2289f10d — the gate reached the real logs of a real run, which is the claim the redesign turns on.

[OffgridwithJD]

CI is red on 380f9f68, both suites jobs, and the cause is structural rather than a slip: the PR that introduces the budget file cannot read a prior ceiling, because at the prior the file does not exist yet.

From the suites (PG 17) job of run 34503924812:

  ledger census: rows=687 | never observed red=687, ever red=0, new this run=0
  ledger coverage: registered=251 | covered=1, not covered=250, ceiling=250
    ledger integrity failure: --against refs/remotes/origin/feat/917-machine-readable-results
    was given, but test/check_ledger_budget.txt does not exist at
    refs/remotes/origin/feat/917-machine-readable-results, so there is no prior ceiling
    to compare against
  PG17 has a check the ledger has never seen, which is not a pass

I reached the same failure independently before seeing this. A full matrix run on 3d880f49 in my own clone returned RUN_ALL_VERSIONS_RC=1, resolving auto to origin/main — my 446-commit-stale fork, where the file also does not exist:

    ledger integrity failure: --against origin/main was given, but
    test/check_ledger_budget.txt does not exist at origin/main
    SOME VERSIONS FAILED

So auto resolves exactly as intended. Resolving correctly turns out not to be sufficient.

Three states, not two

The distinction needed here is the one this branch already drew one level down:

condition	what it means	what it should do
the prior ref does not resolve	asked to compare, unable to compare	error
the prior ref resolves, the file is absent there	nothing could have been raised relative to a file that did not exist	no prior
the prior ref resolves, the file is present	a real comparison	compare

The middle row is the first-landing case, and it is genuinely nothing to compare rather than could not compare. It is also self-clearing: once the file is on main, every later base carries it. That makes it a one-time condition — but it has to be expressed as the property (absent at the prior) rather than as a flag or a date, or it becomes the exemption nobody removes.

A second, smaller one in the same four lines

The runner prints

  PG17 has a check the ledger has never seen, which is not a pass

for an integrity failure. The gate takes care to distinguish rc=1 (a real refusal: a check the ledger has never seen) from rc=2 (it could not do its job), and the runner collapses both into the rc=1 sentence. That sends the reader to regenerate the ledger, which will not help — nothing is missing from it, and new this run=0 says so two lines above. Branching on the status the tool went to the trouble of distinguishing also removes the contradiction of new this run=0 sitting three lines from "has a check the ledger has never seen".

The half that is verified

Both of those runs reached the gate with real logs from a real matrix, printed the census and the coverage, and reported new this run=0. So the feeding half — the claim the redesign turns on — is now confirmed three times: my run on 2289f10d, my run on 3d880f49, and CI on 380f9f68.

[OffgridwithJD]

Approving at exact head 71a7c9bcd02a57201d9e010bbfb94abd11835071 — 12/12 SUCCESS, mergeStateStatus=CLEAN.

Four rounds of findings from me, every one fixed, and I re-measured the last round on this head rather than reading the diff.

The three states, measured on this head in my own clone

--against refs/heads/no-such-ref-xyz   rc=2   "that ref does not resolve here, so the
                                               prior ceiling cannot be read"
--against auto (origin/main lacks it)  rc=0   "no budget at origin/main (464 commits
                                               behind HEAD): this change introduces it"
--against HEAD (this tree carries it)  rc=0   "ceiling against HEAD: 250 -> 250, which
                                               does not rise"

Three distinct verdicts, three distinct messages. The one that was wrong is right in the way that matters most: the unresolvable ref no longer claims "introduces". A message asserting something the code cannot know was the real defect there, more than the exit status was.

Why the chain is worth recording, since the final state hides it

round	the finding	how it failed
1	the monotone ceiling was unwired — if args.against: and the runner never passed it	with the absolute build-dir path it would have printed "no prior ceiling to compare" and returned 0
2	the fix named origin/main, which is 446 commits stale in my clone	the ceiling only falls, so a stale prior is always higher: fails open while printing that it compared
3	auto resolved correctly and the budget cannot exist at the prior, because this PR introduces it	CI red on both suites
4	an explicitly passed unresolvable ref read as "no prior"	said "this change introduces it" about a ref that does not exist

Round 2's CI half was settled by this PR's own log — origin/main does not resolve here then ceiling against HEAD: 250 -> 250, a committed file compared against itself — which is the evidence that the fallback needed removing rather than keeping with a warning.

The claim the redesign turns on, verified three times

The gate is fed from real matrix logs, not fixtures:

my run on 2289f10d    ledger census: rows=638 | never observed red=638, new this run=0
                      ledger coverage: registered=251 | covered=1, not covered=250, ceiling=250
                      ALL VERSIONS PASSED, rc 0
my run on 3d880f49    same census and coverage, then the bootstrap failure (round 3)
CI on 380f9f68        rows=675, and the fallback line that proved round 2

not covered=250 sits exactly on the ceiling, which is the tight place to be: one newly registered suite nobody seeds reddens it.

Fail-closed holds where it should — a nonexistent log, an empty log, a malformed record and a missing --registered are all rc=2, distinguishable from the rc=1 refusal. rename-scan groups by (suite, part), so two parts each renaming in one run pair correctly instead of positionally, and a before+after union in one call is refused. The ledger is LC_ALL=C sorted, so an added check inserts at a content-decided point rather than at the end — the #554 conflict lesson applied, and it matters because every PR adding a harness_selftest check will regenerate this file.

On shape

The census/ceiling split is right and the reason is stated correctly: every new check enters as never, so bounding that number makes landing a check require raising a number the file says may only fall. That is a deadlock, not a budget. Restricting the refusal to covered suites is the meaning of suites_not_covered rather than a softening, and the arm that a new check in a now-covered suite is refused again is what makes it a tightening.

Putting the ref check in the reader rather than in auto is also right: a fact belongs where every caller passes through it, and a policy belongs where it can change without touching the fact.

What I did not verify

I did not run the PG 18 matrix locally for this head; CI's suites (PG 18) is green and that is the evidence for it. My runs were PG 17 on an assert build. And the census of 693 never rows means nothing has been observed red yet — the ledger's value arrives as checks are attacked; what is verified today is that it refuses an unknown check and cannot be quietly widened.

@linuxhikerpm your block stands at 671a9460, four heads back. The monotone enforcement you would have been looking at then did not exist in working form — it was unwired at that commit, which is finding 1 above.