@@ -119,6 +119,65 @@ const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
119119const DRIVERS_DIR = join ( ROOT , 'packages' , 'drivers' ) ;
120120const CASE_SETS_DIR = join ( ROOT , 'packages' , 'spec' , 'src' , 'data' ) ;
121121
122+ /**
123+ * The half of this gate's two scan roots that `scripts/pm/dispatch-gates.mjs`
124+ * cannot see, written in the syntax that derivation CAN read. Provenance ONLY:
125+ * nothing in this gate reads this array, and both walks behave exactly as they
126+ * did without it.
127+ *
128+ * ## The defect this repairs (#10840's worklist, the #10114 / #10314 idiom)
129+ *
130+ * The dispatch derivation scans a gate's module body for the path literals it
131+ * operates on, and "looks like a path" there means "carries a separator". Both
132+ * roots above are assembled by `join()` from separate single-segment arguments,
133+ * so the only literals this file offers the extractor are the bare words
134+ * `packages`, `drivers`, `spec`, `src` and `data` — every one of which
135+ * `extractWatchHints` drops BEFORE `hintCovers` is ever consulted. They are not
136+ * dead hints; they are nothing at all, which is why no residue line ever named
137+ * them. Measured on this tree, a derivation for
138+ * `packages/drivers/postgres/src/index.ts` named six gates and this was not one
139+ * of them — a driver card, and the driver-conformance matrix is invisible to it.
140+ *
141+ * ## Why `packages/drivers/**` and NOT `packages/**`
142+ *
143+ * `hintCovers` refuses a bare single-segment literal as too generic BY DESIGN,
144+ * and the refusal is measured: accepting bare top-level directory words was
145+ * priced at +139084 fabricated (gate, file) pairs, precisely because `packages`
146+ * is a path COMPONENT in dozens of gates that never read that root — this gate
147+ * among them. The literal `'packages'` here is such a component and nothing
148+ * more. Declaring the top-level root would be the fabrication one level up:
149+ *
150+ * packages/** 259 files this gate reads, of 4903 tracked — 5.3%,
151+ * pasted into every packages/** prompt in the repo.
152+ * packages/drivers/** 259 of 291 — 89%, over a subtree 17x smaller.
153+ *
154+ * The remaining 32 files under `packages/drivers/` are the per-package
155+ * manifests, licences and changelogs; adding or removing a driver package moves
156+ * `discoverDrivers` through exactly those, so 89% is a floor rather than an
157+ * estimate.
158+ *
159+ * ## Why CASE_SETS_DIR is deliberately NOT declared
160+ *
161+ * The instrument can only express a SUBTREE — `collapseHint` strips globs, so
162+ * `packages/spec/src/data/*-conformance.ts` collapses to a path that names
163+ * nothing, and the only spellable claim is the whole directory. That directory
164+ * holds 143 tracked files of which this gate reads 7 (4.9%): a subtree
165+ * declaration there would name this gate for every Zod schema and unit test
166+ * beside the case sets. A missing lead costs one card one CI round; a
167+ * fabricated one is pasted into every prompt whose surface brushes it. So the
168+ * case-set side stays undeclared, and the refusal is pinned in the self-test
169+ * rather than left in this paragraph.
170+ *
171+ * ## Provenance, never a lookup key
172+ *
173+ * `assertRootsResolvable([DRIVERS_DIR, CASE_SETS_DIR])` stats both roots and
174+ * throws DeadRootError when one is missing, so the glob form appearing in either
175+ * constant would turn this gate red on a directory that never existed. The
176+ * self-test pins that apart, and derives both halves of the coupling from
177+ * DRIVERS_DIR rather than re-spelling it.
178+ */
179+ const ROOT_DIR_WATCH_HINTS = [ 'packages/drivers/**' ] ;
180+
122181// ── The case-sets ───────────────────────────────────────────────────────────
123182//
124183// `marker` is the export a suite cannot run the case-set without naming, so its
@@ -1074,6 +1133,39 @@ function selfTest() {
10741133 }
10751134 }
10761135
1136+ // -- The dispatch-gates declaration (#10840) --------------------------------
1137+ //
1138+ // Enforcement cannot hold any of these: the declaration is read by another
1139+ // tool entirely, so a wrong or stale one runs green here forever and pays
1140+ // itself out as a dev dispatched on a driver card with this gate missing from
1141+ // the brief. Both halves are DERIVED from DRIVERS_DIR rather than re-spelled,
1142+ // so moving the driver tree cannot leave the declaration describing the old
1143+ // location -- the failure mode a hand-kept copy has.
1144+ const driversRel = DRIVERS_DIR . slice ( ROOT . length + 1 ) ;
1145+ expect ( 'the declaration names the driver subtree this gate actually walks, derived from '
1146+ + 'DRIVERS_DIR rather than re-spelled beside it' ,
1147+ ROOT_DIR_WATCH_HINTS . includes ( `${ driversRel } /**` ) ) ;
1148+ expect ( 'and declares nothing else (a declaration that can drift from the scan is worse than '
1149+ + 'none -- it replaces a silent gate with a lying one)' ,
1150+ ROOT_DIR_WATCH_HINTS . every ( ( h ) => h . replace ( / \/ \* + $ / , '' ) === driversRel ) ) ;
1151+ // The non-vacuity half, and the reason this file needs a declaration at all:
1152+ // every literal it offers the extractor is a bare `join()` argument, so the
1153+ // real population reaches the derivation as nothing whatever.
1154+ expect ( 'the population really is unseeable as spelled -- DRIVERS_DIR is built from bare '
1155+ + 'single-segment join() arguments, none of which the extractor keeps' ,
1156+ driversRel . includes ( '/' ) && ! ROOT_DIR_WATCH_HINTS . includes ( driversRel ) ) ;
1157+ // The REFUSALS, pinned. Neither is an oversight to be tidied up later.
1158+ expect ( 'the bare top-level root is deliberately NOT declared -- `packages` is a path COMPONENT '
1159+ + 'here, and a subtree hint on it would name this gate for 4903 files to reach 259' ,
1160+ ! ROOT_DIR_WATCH_HINTS . some ( ( h ) => h . replace ( / \/ \* + $ / , '' ) === 'packages' ) ) ;
1161+ expect ( 'CASE_SETS_DIR is deliberately NOT declared -- its population is a FILENAME pattern '
1162+ + '(*-conformance.ts, 7 of 143 files) and a subtree hint cannot express one' ,
1163+ ! ROOT_DIR_WATCH_HINTS . some ( ( h ) => CASE_SETS_DIR . slice ( ROOT . length + 1 ) . startsWith ( h . replace ( / \/ \* + $ / , '' ) ) ) ) ;
1164+ // Provenance, never a lookup key: assertRootsResolvable stats both roots, so
1165+ // the glob form appearing in either constant is a hard red on a dead root.
1166+ expect ( 'the declared form is NOT a scan-root value' ,
1167+ ! ROOT_DIR_WATCH_HINTS . some ( ( h ) => h === driversRel || h === DRIVERS_DIR ) ) ;
1168+
10771169 if ( failures . length ) {
10781170 for ( const f of failures ) console . error ( ` x self-test: ${ f } ` ) ;
10791171 console . error ( `\ncheck-driver-conformance --self-test: ${ failures . length } failure(s).\n` ) ;
@@ -1083,7 +1175,8 @@ function selfTest() {
10831175 'OK self-test: detects driven / unused / re-declared fixtures, discovers both axes, accounts for '
10841176 + 'every entry under DRIVERS_DIR (a dropped or manifestless row is red, not a smaller matrix), '
10851177 + 'holds the dead-root hard error (red when a scan root is renamed, green when restored), and '
1086- + 'keeps CONSUMED\'s ledger offer marked maintainer-only (#8435).' ,
1178+ + 'keeps CONSUMED\'s ledger offer marked maintainer-only (#8435). It also declares the driver '
1179+ + 'subtree dispatch-gates derives from, refusing the bare root and the case-set dir by name.' ,
10871180 ) ;
10881181}
10891182
0 commit comments