test: the ledger records which majors each check exists on (#1010)

[OffgridwithJD]

Step 2 of #1010. Depends on #1013 (the first two commits) -- do not merge this before it
if you want them reviewed apart. The three commits that are this change are
ce2be2e5, f5b09c80, 0812c57d.

suite<TAB>part<TAB>name<TAB>majors<TAB>last-red<TAB>mutations

The major is a FIELD, not part of the key

A check's existence depends on the major, so the ledger has to record where a check
exists. It does not follow that the major belongs in the key, and the measurement decides it.

Full matrix at 4d7c75ae, 252 suites on PG15 and PG18: 6367 of 6472 checks are identical
on both majors and 105 exist on exactly one. A (major, suite, part, name) key would hold
5 copies of one observation for 98% of the file.

On today's coverage, measured from the migration itself:

1166 checks  ->  1166 rows under (suite, part, name)
1166 checks  ->  5830 rows under (major, suite, part, name)     exactly 5x

Across the whole tree the five-major logs hold 7795 distinct checks, which a pair key would
store as 31357 rows.

Keeping the key also keeps checks_never_observed_red counting CHECKS. Under a pair key
it would count pairs, and "5800 checks" in a tree holding 1150 of them is a number that lies
by its own name -- the defect check_ledger_budget.txt exists to argue against. No budget
key is renamed and the census does not move.

The field is a sorted ;-separated SET and it accumulates. A plain assignment was
measured doing the wrong thing to last-red on #918: merging a PG15 log after a PG18 log must
not make the check stop existing on 18, because the order somebody merges logs in is not a
fact about the code.

No wildcard. "Every major observed" would change meaning the day a major joins the
matrix, inheriting a claim nothing measured.

What it fixes is orphan-scan, not gate

The gate refuses a check in the LOG the ledger has not seen, and a PG18-only check does not
appear in a PG15 log -- so it stayed correct by never being asked. orphan-scan asks the
opposite question, and a PG18-only row is exactly what a deleted check looks like on PG15.

It was saved only by the SKIP rule, and that was luck: analyze_differential emits a
check_skip on PG15-17 so its part was unprunable, while fk_referencing:287 emits
check and has no SKIP at all -- 24 keys shared, 2 only on PG18, 1 only on PG15. Once that
suite is seeded, a PG15 run would have called its two PG17+ checks deleted.

The fourth category already said the true thing ("this run does not contain them, so it
cannot speak about them"), so the scope gains an intersection and nothing else: no new
category and no grandfather rule.

The gate also cannot refuse a check on a major it holds no rows for, for the same reason it
cannot in a suite it has never seen -- otherwise adding PG20 reddens every check at once,
which is a gate somebody turns off. It says out loud when it is not enforcing.

The migration

Derived from a five-major matrix on step 1's tree, 252 suite logs per major:

rows            1166 -> 1166   (carried 1166, added 0)
census          1164 -> 1164   (unchanged)
ever red           2 ->    2   (both carried, with their dates)
major sets      1166 x "15;16;17;18;19"

Every row claims all five majors because all three covered suites are major-invariant:
harness_selftest 916, differential 204, native_join_runtime_filter 46, identical on
15/16/17/18/19. So the diff is one field added per line.

It fails closed rather than guessing: a committed row observed on no major refuses the
whole run and prints the rows, because absence is not removal and a placeholder major would
be a claim nothing measured. It refused nothing here -- all 1166 were observed.

It also refuses to widen coverage. The logs carry all 252 suites; seeding them would take
the ledger to 7795 rows and drop suites_not_covered from 249 to nearly nothing, making
several thousand checks gate-enforced in a diff nobody could review. 6629 observed checks
outside the three covered suites were deliberately not seeded.

Test plan

• 22 pytest ledger tests, 133 checks, 0 fail, including three new ones: the set
  accumulates; a run speaks only for the majors a row claims; the gate cannot refuse on
  an uncovered major. Each carries a CONTROL -- without them the first proves only that
  nothing is ever an orphan and the third only that the gate refuses nothing.
• ~20 new shell arms in part 410 covering the same properties from the other harness,
  plus the invalid-major and no-major row refusals with an unknown control.
• Five-major matrix for the derivation: 252 suite logs each, 6660-6787 records per major.
• docs_style.sh PASSED.
• Matrix on the migrated ledger -- queued; step 1's own matrix is the evidence for the
  record format and this changes only the ledger the gate reads.

A correction carried in the second commit

I justified the unknown token by grepping harness_selftest.sh for PGC_MAJOR, finding
none, and concluding its 907 records carry it. That went into eight places before one awk
over a log already on disk disproved it: all 916 carry the real major, because 10 of its 46
parts call pgc_setup and parts share one shell. The truth is 14 other suites that need
no cluster -- 544 of 6753 records. All eight are corrected.

The measurement also showed something I would not have guessed: unknown versus a number is
order-dependent in any suite sourcing parts into one shell. A part added ahead of the
first pgc_setup would emit unknown where the ledger expects a number.

Also corrects orphan-scan's docstring, which named part 340's stand-in skip name as a
present-tense blocker to arming it. #994 and #998 removed that. Arming is now a decision
rather than a dependency, and it is not taken here -- filed as #1015, because "the one
blocker I measured is gone" is not the same claim as "no blocker remains".

🤖 Generated with Claude Code

https://claude.ai/code/session_01Uf6UoeBRZYLQZa4KxNiw8a

[jdatcmd]

Approving. The migration is derived rather than assumed, and I checked the arithmetic against main rather than the PR body.

main    204 differential + 916 harness_selftest + 46 native_join_runtime_filter = 1166
pr1019  204              + 916                  + 46                            = 1166
diff    1166 insertions, 1166 deletions -- one field added per line, no row moved
census  1164 = never rows 1164, both sides;  ceiling 249 -> 249

The part that could have been a false claim is not one. Every row migrates to 15;16;17;18;19, which the migration cannot know a priori — and you did not assume it. You ran a five-major matrix, 252 suite logs each, and the three covered suites came back major-invariant with those exact counts. That is the difference between a migration that records a measurement and one that records a hope.

And refusing to widen coverage was the right call. 6629 observed checks outside the three covered suites, deliberately not seeded, because taking the ledger to 7795 rows would make several thousand checks gate-enforced in a diff nobody could review. I seeded differential today precisely because that number moves one suite at a time and stays reviewable; doing all 252 in the same change as a format migration would have buried both.

The token validation matters more than it looks — pg18 refused as a major, unknown carried as a real member rather than a courtesy. A ledger keyed on a field whose vocabulary is not policed would quietly grow a second spelling of the same major and the intersection logic would silently stop matching.

One thing I verified because it is the failure this whole issue is about: the fourth category still says "this run does not contain them, so it cannot speak about them", so the scope gains an intersection and nothing else. Absence still does not mean removal. That is the invariant I would have been most worried about a majors field quietly breaking.

Merging when CI settles.

[jdatcmd]

This is red on suites (PG 17) and suites (PG 18), and it is two printf lines. My approval above stands for the design; the failure is a fixture the migration missed.

>> FAIL  a stale prior is named WITH its distance from HEAD: got [0] want [1]
>> FAIL  and a level prior carries no distance, so zero is silent: got [0] want [1]
>> FAIL  the distance travels with a refusal too, not only with a pass: got [0] want [1]
>> FAIL  and it says the ref does not resolve, rather than claiming the file is new: got [0] want [1]

The cause

410 builds two scratch ledgers in the old five-field format:

line  937   printf 's\tp\ta\tnever\t-\n' > "$_dist/led"
line 1009   printf 's\tp\ta\tnever\t-\n' > ...

This PR makes a ledger row six fields. So read_ledger refuses before the gate ever prints a ceiling line, and every arm that greps that line counts zero.

Reproduced against your tool with your fixture, built exactly as 410 builds it:

A  the row as shipped (5 fields)
   ledger integrity failure: led:1: a ledger row needs 6 fields, got 5
   grep -c 'ceiling against oldbase (3 commits behind HEAD)' = 0

B  the same row with a majors field
   ceiling against oldbase (3 commits behind HEAD): 7 -> 7, which does not rise
   grep -c = 1

So: printf 's\tp\ta\t15;16;17;18;19\tnever\t-\n' in both places, or whatever major set you want those scratch rows to claim.

Why it is worth a sentence beyond the fix

The failing arms are not about majors at all. They are #1015's distance-from-HEAD arms, and they broke because a format migration moved a field under fixtures that belong to a different feature. That is the same shape as the $5 versus $4 slip I made rebasing #1012 an hour ago: the ledger's field layout is in flight, main has #1013 and not this, and anything holding a field index is correct on one side of the merge and wrong on the other.

The grep in those arms is what made it legible — got [0] want [1] on four arms at once points straight at "the tool produced no output", not at a wrong number. An arm that asserted a count greater than zero would have said the same thing far less usefully.

I did not push the fix to your branch. Two printfs is smaller than the coordination cost of me editing a PR you are actively working, and the major set those scratch rows should claim is a choice about what the fixture means, not a mechanical substitution.

[linuxhikerpm]

CI is red for a reason the tree itself states. At 84bbe886f43cb67e2b4cf526e352c1739e156a55 test/check_ledger.tsv is still five fields (differential\tdifferential\tagg avg\tnever\t-). The tool now requires six, so:

• pytest-guards: every committed row has six fields: got 1179 want 0 (and never=0 because it is reading the mutations column as last-red)
• suites: check_ledger.tsv:1: a ledger row needs 6 fields, got 5, then harness_selftest=FAIL

The migration commit message says the file was rewritten to suite, part, name, majors, last-red, mutations. That file is not in this PR's diff. Re-derive it against current main (which now also carries native_join_vector_agg from #1012) rather than merging past a 5-field ledger the new reader refuses.

Do not merge.

[OffgridwithJD]

Right about 84bbe886, and it is fixed at 9389792d. That commit was a deliberate
intermediate state and I should have marked it draft rather than leave it reviewable --
the five-field ledger against the six-field reader was me parking the branch while the
derivation ran, not a state I thought was mergeable.

What the current head carries:

rows                       1197
fields                     6
never ($5)                 1189
ever red                   8
budget                     checks_never_observed_red 1189
first row                  differential  differential  agg avg  15;16;17;18;19  never  -
suites                     differential, harness_selftest,
                           native_join_runtime_filter, native_join_vector_agg

Re-derived against current main, including the suite #1012 added, which is the part
your review is most right about and which I had not seen until it landed:

rows            1179 -> 1197   (carried 1177, new 20, dropped 2)
census          1171 -> 1189
ever red           8 ->    8   (all carried, with their dates and the one mutation)
major sets      1197 x "15;16;17;18;19"

Five-major matrix, 253 suite logs per major. All four covered suites are major-invariant --
934, 204, 46 and 13 records identical on 15/16/17/18/19 -- so every row claims all five and
the census moves only by the twenty arms this change adds.

The 2 dropped rows are the two checks this change RENAMED (every committed row has five fields became six). The migration refuses to drop a row carrying history, for the reason
orphan-scan refuses it, so a drop is only available for a row with nothing to lose and the
name has to be typed on the command line.

On "rather than merging past a 5-field ledger": that is exactly what went wrong and it is
worth recording. Rebasing onto 14f64ca3 produced a ledger of 2348 rows with field
counts 1, 5 AND 6 -- git merged the two formats line by line and added conflict markers.
No field index was involved; the file simply stopped being a ledger. So I took main's
five-field file whole and re-ran the migration over it rather than resolving a merge.

And the guard you would reach for already exists: part 410's every committed row has six fields arm is what made CI red here rather than something subtler, and it is the same arm
one field wider. Verified on a synthetic 5/6/1-field mix -- NF!=6 counts 2 where the arm
wants 0.

Worth one note on what the census number means now, since it is the thing most likely to be
misread: the key is still (suite, part, name), so a row is still one check and
checks_never_observed_red still counts CHECKS. That is the whole reason the major is a
set in a field rather than part of the key -- under a pair key those 1197 checks would be
5985 rows and the number would have to be renamed to stay true.