From 6b1c8229926e91545cd5eea0569096f0d3bc68d5 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 18 Aug 2026 23:58:59 +0000 Subject: [PATCH] docs(scripts): rewrite the where-matcher ledger's $comment for its empty steady state The `$comment` still described the ledger as a populated worklist -- "every entry here today is failure shape (b)" and "shape (b) is the sweep still owed" -- while `files` has been `{}` since PR #8618 emptied it (the #8582 sweep, three batches, the day after PR #8581 seeded it). The prose was never reconciled with the sweep that finished, so a reader reconciling it against the file learns that a sweep is outstanding and that this file records what is left of it. Neither is true. Rewritten to state the CONTRACT rather than a state: - what an entry MEANS (debt, deleted by the PR that repairs it), and that the count and the failure shape are deliberately not written here because both change with every repair -- the drift this commit fixes was exactly a state claim outliving its state; - both failure shapes stay named, since the vocabulary is live in the checker (its header, the per-matcher `shapes` attribution, and the self-test that pins each), but as what an entry MAY be, not what every entry IS; - EMPTY IS THE SUCCESS STATE: `files: {}` means nothing is grandfathered, and the loader asserts nothing about the ledger's size, so it is a passing run; - why the file must still exist, which nothing had written down: with it absent the gate prints `check-where-matcher-conformance: missing ` and exits 2 before scanning anything -- a hard refusal, never a clean pass -- and `monotonicity()` reads this same path out of the merge base, so a delete-and-re-add also drops the MONOTONIC invariant for that run; - what an empty ledger does NOT claim: absence means graded-and-conforming, not extinct. The inverted survivor filter inside a `delete` double answers the control probe inverted, is dropped OUT_OF_SCOPE by the gate's own definition, and carries the no-combinator-branch defect one negation away (#8662, pinned as FIXTURE_CAPTURED_NEGATED). No baseline ENTRY is added, removed or edited: `files: {}` is byte-identical. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01XqDQYVU5smx29ts9pAErja --- .../where-matcher-conformance.baseline.json | 79 ++++++++++++++----- 1 file changed, 61 insertions(+), 18 deletions(-) diff --git a/scripts/where-matcher-conformance.baseline.json b/scripts/where-matcher-conformance.baseline.json index 87400a9da6..0092f07a91 100644 --- a/scripts/where-matcher-conformance.baseline.json +++ b/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": {} }