Nothing runs orphan-scan, so the deleted-check half of the ledger comparison cannot fire -- and the blocker its docstring names was removed by #994/#998

[OffgridwithJD]

pgc_ledger.py orphan-scan reports a ledger row that no record in its own part matches. It
is the half of the comparison that answers "has this check been deleted", and the gate
answers only the other half.

Nothing in the tree runs it. Not run_all_versions.sh, not ci.yml, not
nightly.yml. Its only callers are the selftest arms that test the tool itself. So the
guard exists, is tested, and cannot fire on anybody's change.

The reason it was not armed is gone

Its docstring names one measured blocker, and names it as present tense:

Measured, not assumed: part 340 records ONE skip under a DIFFERENT name ("the
unreadable-source refusal") when the box has no non-root user to read as, rather than
skipping its two named arms. On such a box two committed rows have no matching record and
are not removed checks, so a gate refusing on absence would redden a correct run. Arming
this needs those branches to record a SKIP under the names they stand in for.

That conversion landed in #994 and #998. On main today, part 340 does:

for _fp_n in "premise: the unprivileged reader can source the staged harness" \
             "premise: the tree fingerprints to something when it is readable" \
             "premise: the unprivileged read agrees while everything is readable"; do
    check_skip "$_fp_n" ...
done

and the unreadable-source refusal survives only in a comment saying what it used to do --
one occurrence in the file, on a comment line.

So the stated precondition is satisfied. I have corrected the docstring in #1010 step 2 to
say so, and deliberately did not arm it there: "the one blocker I measured is gone" is a
different claim from "no blocker remains", and the second needs a run across every part that
skips.

What arming needs, and why it is worth doing

The work is a measurement, not a design:

1. Run the matrix and collect, for every part that emits a SKIP, whether each skipped arm
   records under its own name. The unprunable classification already protects a part that
   skipped anything, so the question is narrower than it looks: it is only about a part
   that skips under a name no row matches, which is the One skip stands in for 28 named arms across six suites, so a skipped arm and a deleted one are indistinguishable #994 defect at branch granularity.
2. Decide the exit code the runner acts on. orphan-scan returns 1 for an orphan or a
   skipped part's rows and 2 for an integrity failure or a refused prune, and not checked
   deliberately returns 0 -- a run observes one major, so on a multi-major ledger most rows
   are rows it cannot speak for.
3. Wire it beside the gate in run_all_versions.sh, where every suite's log is already in
   one place and the build directory has not been removed yet.

The value is concrete and already paid for once: two rows sat in the committed ledger
naming checks that no longer existed (#983). The census counted both. Every run returned 0
while the note scrolled past, because vanished=N was printed and refused nothing. That is
the defect this subcommand was written for, and it can recur tomorrow with nothing to catch
it.

Related: #1010 step 2 fixes the direction where a row for another major reads as a deleted
check. That fix is latent until this is armed, which is the honest reason to arm it rather
than an argument that it is urgent.

[OffgridwithJD]

Step 1 is done: I ran the measurement this issue asks for, and arming is safe today.

A full five-major matrix on author/main at 03c6c9c8, with every suite's log captured before
the runner removes its build directory, then orphan-scan run against the committed ledger
once per suite log:

major  logs    rc=0   rc=1   rc=2   orphans  unprunable
pg15   246      246      0      0         0           0
pg16   246      246      0      0         0           0
pg17   246      246      0      0         0           0
pg18   247      247      0      0         0           0
pg19   247      247      0      0         0           0

All five majors PASSED the matrix itself (RC=0, ALL VERSIONS PASSED). 1232 scans, every one
clean.

And the four suites the ledger actually covers emit no SKIP at all, on any major:

suite                        pg15 pg16 pg17 pg18 pg19
harness_selftest                0    0    0    0    0
differential                    0    0    0    0    0
native_join_runtime_filter      0    0    0    0    0
native_join_vector_agg          0    0    0    0    0

So the precondition this issue was waiting on is satisfied, measured rather than argued.

Most of those 1232 scans are trivially clean, and that is worth saying

With the ledger covering four suites of 253, a log from an uncovered suite has no rows in its
part, so orphan-scan returns 0 without deciding anything. On pg16: 239 of 243 logs were
that case, and 4 were logs the scan could actually speak about. The table above is
therefore a strong statement about the four covered suites and a weak one about the rest. It
tightens as suites are seeded, which is the same direction everything else in this family moves.

Step 2 is a DESIGN decision, not just a choice of number

The issue calls the work "a measurement, not a design". The measurement part was; this part is
not. orphan-scan documents:

0   no orphan and nothing unprunable
1   something is still there -- an orphan, OR a row in a part that SKIPPED
2   an integrity failure, or a prune refused because history would be lost

1 conflates a real finding with a benign one, so a runner acting on rc != 0 cannot tell
them apart. Proven on fixtures rather than read off the docstring:

arm B absent, part skipped something else   rc=1  unprunable=1  orphans=0   benign
arm B absent, nothing skipped                rc=1  unprunable=0  orphans=1   a real finding

My first fixture failed, and that narrowed the conclusion in your favour. I planted a part
that skipped one of its own arms and expected unprunable=1; I got rc=0. A skipped arm that
records under its OWN name is not absent at all — which is exactly what #994 and #998 changed.
So unprunable now needs a genuinely deleted check plus a skip elsewhere in the same part,
which is much rarer than "any part that skips". The eight SKIP-emitting suites
(native_index_projection 11 on every major, plus analyze_differential, analyze_function,
audit, native_groupagg, native_repack, pg19_vacuum_options, unique_conc with one each,
varying by major) are therefore a smaller hazard than a plain reading suggests. None is covered
today.

Three ways to wire it, and I would not pick for you

1. Parse orphans=N from the output. No tool change, and the runner already reads tool
   output elsewhere. But it makes a print format load-bearing, which is the thing this
   repository keeps paying for.
2. A new flag, --fail-on-orphan, returning non-zero only for orphans. Additive: the
   documented codes keep their meaning, and the runner asks for exactly what it intends to
   enforce. unprunable stays reported and stops being a gate verdict.
3. A distinct code for unprunable-only, say 3. Cheapest diff, but it changes published
   semantics that the selftest arms and the docstring both pin.

I lean to 2, and it is your tool's contract rather than mine to set.

Sequencing

The tool-side half touches pgc_ledger.py, which #1035 also touches, so it should land after
that merges or the two conflict in the same function. The runner-side half is
run_all_versions.sh only and is independent.

How I measured it, including a correction

The runner removes its build directory when a major finishes, so the per-suite logs must be
copied during the run. My first snapshotter used cp -n, which keeps the first partial copy
— 150 of 253 pg15 logs had no checks run: line. read_records' own integrity check caught it
immediately (23 record(s) but no 'checks run:' line, so the log never reached its summary and cannot be reconciled), which is how I know the table above is over complete logs: the scan
refuses a truncated one outright rather than scanning it. The figures here are from a re-run
with the copy repeated each poll, and pg15 re-run separately.

I also withdrew a number on #1035 that came from the broken version of the same instrument.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Uf6UoeBRZYLQZa4KxNiw8a

[OffgridwithJD]

A second measurement off the same five-major run, because it answers a question the seeding
design will ask. Not a new finding — it is an instance of the suites_not_covered 249 debt
already tracked in check_ledger_budget.txt. What is new is the number.

238 of 247 suites emit the same check count on every major

suites with records on all five majors and the SAME count    238
suites whose count varies, or that are absent on a major       9

The nine, with their per-major record counts:

suite                                 15   16   17   18   19  spread
analyze_differential                   1    1    1   26   26   25
analyze_function                       1    1    1   54   54   53
native_repack                          1    1    1    1   19   18
pg19_vacuum_options                    1    1    1    1   12   11
generated_columns                      5    5    5   11   11    6
audit                                 28   28   31   31   31    3
native_sort_by                        16   16   16   18   18    2
fk_referencing                        25   25   26   26   26    1
temporal                               -    -    -    5    8   absent on 15-17

Every one of them is a deliberate, readable version gate

I checked each rather than assuming, because "a suite that quietly runs fewer arms on one
major" is the shape worth worrying about:

analyze_function.sh:47   "Writing statistics uses pg_restore_attribute_stats, which core added in 18"
audit.sh:293             server_version_num >= 170000
fk_referencing.sh:287    PGC_MAJOR >= 17
generated_columns.sh:58  major >= 18
native_sort_by.sh:114    PGV >= 18
temporal.sh:39,78        major < 18 skips, major >= 19 adds

The four with a spread of 11 or more emit ONE record on the majors they do not support, via the
deliberate exit-66 path rather than pgc_skip — analyze_differential.sh:51 says so: "SKIP
with no checks (exit 66) rather than pgc_skip, which fails by default and must be waived
deliberately." So nothing here is accidental, which is the honest answer and the one I
expected least.

Why the number matters for seeding

The thing that would pin this is already built: check_ledger.tsv's set-valued majors field,
which is what #1010 made it for. It covers 4 suites of 253, so for the other 249 nothing
asserts that a suite's per-major shape is the shape it is supposed to have. A tenth suite
joining that table — an arm accidentally wrapped in if [ "$major" -ge 19 ] — reports PASS on
every major and is invisible, because the matrix's N ran, M skipped does not move for a suite
that ran with fewer arms.

That is the suites_not_covered debt restated, not a separate problem. But it bounds the work:

(check, major) pairs a full seed would record   6651 records x the majors each appears on
suites whose majors field would be anything     9
   other than all five

So seeding does not have to solve "240 suites might each vary by major". It has to represent
nine that do, eight of them on a clean >= N boundary. That is a much smaller design than the
row count suggests, and worth knowing before the row count is used to argue the cost.

Method, since the last figure I posted here needed withdrawing: these counts come from
per-suite logs snapshotted during the run and then filtered to those carrying a checks run:
line, so a truncated copy is excluded rather than counted. 1232 logs across five majors.
read_records refuses a log without that line, which is what made the earlier truncation
visible in the first place.