From 37795e29c687064a9436359a9896e71d3027e4d9 Mon Sep 17 00:00:00 2001 From: "Joshua D. Drake" Date: Sat, 12 Sep 2026 08:39:25 -0600 Subject: [PATCH] docs: the census derivation was wrong in prose, and it was an instruction (#752) #1002's changelog entry said "the census is `grep -c` over the ledger". It is not. The gate compares the budget against the count of rows whose LAST-RED is `never`: never = sum(1 for v in rows.values() if v[0] == NEVER) ... elif stated != never: awk -F'\t' '$4=="never"' test/check_ledger.tsv | wc -l A plain row count agrees with that only while nothing has ever been seen red. On this tree today: 1155 rows, 1155 never, 0 ever red -- so the NUMBER I committed was right and the METHOD was wrong, in an entry whose whole subject is derive rather than carry. Reported by @OffgridwithJD. DRIVEN, because the two derivations are indistinguishable on today's tree and the claim is about a tree that does not exist yet. Three rows, one of them observed red: grep -c 3 awk $4=="never" 2 budget 3, from grep -c gate rc=1 "the budget states checks_never_observed_red 3, the ledger holds 2: these describe the same file and disagree" budget 2, from awk gate rc=0 AND THAT REFINES THE REPORTED CONSEQUENCE. The report was that the wrong method would agree with a budget written the same wrong way and pass. It does not: the gate compares the budget against the ledger, not against whatever command produced it, so a wrongly-derived budget FAILS CLOSED. The harm is not an undetected lie, it is an unexplainable red on a correct tree the first time a check is attacked -- which is still worth removing, because a guard that reddens for a reason nobody can find is a guard somebody turns off. The derivation now sits in check_ledger_budget.txt beside the number it governs, which is where someone looking for it will be, rather than in a changelog entry they would have to know to search. Same principle as #1003: a summary worth reading is worth defining where it prints. The wrong sentence is left visible in the entry rather than silently replaced, because it was an instruction and somebody may already have followed it. Verified: budget still parses ({'suites_not_covered': 249, 'checks_never_observed_red': 1155}), documented command returns 1155, gate rc=0. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01EbyGSaU93XYQr8aH4NrUiw --- CHANGELOG.md | 21 ++++++++++++++++++--- test/check_ledger_budget.txt | 11 +++++++++++ 2 files changed, 29 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 6c11bb48..b541e2a6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -28,9 +28,24 @@ true until the next version shipped. change is its own argument for that rule. Written against an earlier base the same seed produced `913 -> 1117`; #983 then landed forty rows and pruned two, and the census became 1155. Carrying 1117 forward would have been arithmetic that was true - when it was written and false when it shipped. The census is `grep -c` over the - ledger, re-run after the rebase; the ceiling is the registered list minus the - ledger's own suites. + when it was written and false when it shipped. + + CORRECTION, and the wrong version is left visible because the sentence was an + INSTRUCTION. This entry first said the census is `grep -c` over the ledger. It is + not. The gate compares the budget against the count of rows whose last-red is + `never`: + + awk -F'\t' '$4=="never"' test/check_ledger.tsv | wc -l + + A plain row count agrees with that only while nothing has ever been seen red, which + is true of this tree today (1155 rows, 1155 never, 0 ever red) and stops being true + the first time a check is attacked -- the event the ledger exists to record. So the + number here was right by luck and the method was wrong, in an entry whose whole + subject is derive rather than carry. Reported by @OffgridwithJD. The correct + derivation now sits in `check_ledger_budget.txt` beside the number it governs, so + the next person does not have to find it in a changelog. + + The ceiling is the registered list minus the ledger's own suites. WHY THIS SUITE, measured rather than chosen by taste. It is the heap-versus-columnar differential correctness suite, so a check that cannot fail there is a wrong answer diff --git a/test/check_ledger_budget.txt b/test/check_ledger_budget.txt index 9847dd7f..00efd917 100644 --- a/test/check_ledger_budget.txt +++ b/test/check_ledger_budget.txt @@ -34,4 +34,15 @@ suites_not_covered 249 # Without that it is a hand-maintained count that drifts, which is the failure # this repository has spent a day proving. It is not a ceiling; it is a # measurement that must be true. +# +# HOW TO RE-DERIVE IT, written here because a changelog entry got it wrong and a +# derivation is only useful where the number is: +# +# awk -F'\t' '$4=="never"' test/check_ledger.tsv | wc -l +# +# Rows whose LAST-RED is `never`, not the row count. The two agree only while +# nothing has ever been observed red, so a plain `grep -c` overcounts by exactly +# the number of attacked checks -- and it overcounts from the first moment this +# ledger does the job it exists for. The gate prints both quantities side by side +# (`rows=N | never observed red=M`) because they are different questions. checks_never_observed_red 1155