docs(scripts): rewrite the where-matcher ledger's $comment for its empty steady state

scripts/where-matcher-conformance.baseline.json

@@ -2,28 +2,68 @@
  "$comment": [
  "Measured baseline for scripts/check-where-matcher-conformance.mjs (#8494, from #7620).",
  "",
- "Each entry is ONE test file holding in-memory WHERE matcher(s) that answer a combinator",
- "query SILENTLY WRONG — they neither handle `$or`/`$and` correctly nor refuse them. The",
- "counts are measured by the gate, never asserted by hand; run the gate and it prints the",
- "current number for every file it disagrees with.",
- "",
- "`silent` the matcher answers the combinator battery wrongly without erroring. Every",
- " entry here today is failure shape (b) from #8494: an `Object.entries(where)`",
- " matcher with NO combinator branch, which reads `$or` as an ordinary field",
- " name, compares `row.$or` (undefined) against the array, and drops the row.",
- " Dormant, not harmless — the day a test adds an `$or` to one of these, the",
- " suite asserts on an empty result set with nothing erroring.",
+ "WHAT AN ENTRY IS. One test file holding in-memory WHERE matcher(s) that answer a",
+ "combinator query SILENTLY WRONG — they neither handle `$or`/`$and` correctly nor refuse",
+ "them. An entry is DEBT, never an exemption: the remedy is the matcher, and the entry is",
+ "deleted by the PR that repairs it. The per-file counts are MEASURED by the gate, never",
+ "asserted by hand — run the gate and it prints what it measured for every file it",
+ "disagrees with.",
+ "",
+ "`silent` the matcher answers the combinator battery wrongly without erroring. Dormant,",
+ " not harmless — the day a test hands one of these an `$or`, the suite asserts",
+ " on an empty result set with nothing erroring.",
  "",
  "`unjudged` the matcher could not be lifted out of its file and executed, so the gate has",
  " no verdict on it. Declared rather than skipped: \"could not run\" is a failure,",
  " not a pass (AGENTS.md, \"Absence must be loud\").",
  "",
- "NOTE what is NOT here: failure shape (a), the `$or` early return that discards sibling",
- "keys. That shape has ZERO grandfathered instances on purpose — the five still live on",
- "`main` when this gate was built (four in objectql, one in plugin-security, all missed by",
- "the three correction lanes) were fixed in the gate's own PR rather than baselined. A",
- "ledger that grandfathered the exact defect its gate exists to stop would be worth",
- "nothing. Shape (a) is enforced with an EMPTY ledger; shape (b) is the sweep still owed.",
+ "HOW MANY entries there are is deliberately not written here, and neither is which failure",
+ "shape they carry: both change with every PR that repairs one, and prose asserting either",
+ "goes stale unread. This block said \"every entry here today is failure shape (b)\" and",
+ "\"shape (b) is the sweep still owed\" for as long as the ledger sat empty after the sweep",
+ "finished (#9766). Read the count from `files`; read the shape from the gate's output,",
+ "which attributes it per matcher for the report only.",
+ "",
+ "THE TWO SHAPES ARE STILL THE VOCABULARY (checker header, \"Two failure shapes, one",
+ "criterion\"; the self-test pins the attribution of each). Both are graded by the same",
+ "behavioural battery and land in the same `silent` count, so an entry may be either and",
+ "this file does not record which: (a) EARLY RETURN — a combinator branch that `return`s,",
+ "discarding the sibling keys, so the matcher sees `$or` but answers a narrower query;",
+ "(b) NO COMBINATOR BRANCH — an `Object.entries(where)` matcher that reads `$or` as an",
+ "ordinary field name, compares `row.$or` (undefined) against the array, and drops the row.",
+ "",
+ "PROVENANCE. Seeded by PR #8581, the gate's own PR: the pre-existing combinator-blind",
+ "doubles were grandfathered, while the five LIVE early-return instances that PR found",
+ "(four in objectql, one in plugin-security, all missed by the three correction lanes",
+ "#7846 / #8493 / #7619) were FIXED there rather than baselined — a ledger that",
+ "grandfathered the exact defect its gate exists to stop would be worth nothing. PR #8618,",
+ "the #8582 sweep, then cleared the grandfathered set in three batches, ratcheting this",
+ "ledger to empty; every repair since deletes its own entry the same way.",
+ "",
+ "EMPTY IS THE SUCCESS STATE, NOT A DEAD FILE. `files: {}` means nothing is grandfathered:",
+ "every matcher the gate discovered answers the battery correctly or refuses it loudly. The",
+ "loader asserts nothing about the ledger's size (it reads `baseline.files ?? {}`), so an",
+ "empty ledger is a PASSING run, not a corrupted or half-written one.",
+ "",
+ "⛔ DO NOT DELETE THIS FILE WHEN IT EMPTIES. Measured, not assumed: with the file absent",
+ "the gate prints `check-where-matcher-conformance: missing` followed by this path and exits",
+ "2 BEFORE it scans anything — a hard refusal, never a clean pass, because an absent ledger",
+ "cannot tell settled debt from a new defect. Deleting and later re-adding it also costs the",
+ "MONOTONIC invariant for that run: `monotonicity()` reads this same path out of the merge",
+ "base with origin/main, and a read that fails leaves the run reporting \"NOT verified: could",
+ "not read the baseline at the merge base with main\". The empty file is what keeps the NEXT",
+ "silently-wrong double reportable as NEW, instead of arriving with no ledger for it to be",
+ "absent from.",
+ "",
+ "ABSENCE FROM THIS FILE MEANS GRADED AND CONFORMING — never \"unscanned\", and never that",
+ "the defect is extinct repo-wide. Membership is decided behaviourally: a candidate that",
+ "fails the control probe is dropped OUT_OF_SCOPE, and the known residual is the INVERTED",
+ "survivor filter inside a `delete` double — `(r) => !Object.entries(where).every(…)` —",
+ "which answers the probe `false`/`true` and so is correctly not a row-SELECTING predicate,",
+ "while carrying the no-combinator-branch defect one negation away. Ungraded on purpose",
+ "(teaching the probe to read a negation means guessing at intent), pinned as the",
+ "`FIXTURE_CAPTURED_NEGATED` self-test fixture so it stays a KNOWN limit, and tracked by",
+ "#8662. An empty ledger is a statement about what the gate GRADES, not about what exists.",
  "",
  "TWO ways to clear an entry, and the cheap one is usually right:",
  " 1. make the matcher conjoin `$or`/`$and` with its sibling keys, or",
@@ -39,7 +79,10 @@
  "origin/main, because counts alone cannot see a newly-added file matching its own count —",
  "that would turn this ledger into a general-purpose mute button (the SLOT_LOOKUP_UNSWEPT",
  "precedent, #4251). There is deliberately no --update flag: a generator would let a new",
- "silently-wrong double in by \"just run the update command\"."
+ "silently-wrong double in by \"just run the update command\".",
+ "",
+ "Key is the repo-relative test file path; its value is the measured `silent` / `unjudged`",
+ "counts for that file. Run the gate to see exactly what it measured."
  ],
  "files": {}
 }