@event4u/agent-config 16.2.0 → 16.4.0

package/src/scripts/check_hook_bundle_composition.ts

@@ -0,0 +1,477 @@
+#!/usr/bin/env tsx
+/**
+ * Composition gate for the self-hosted hook bundle: ONE YAML reader, and a
+ * byte ceiling.
+ *
+ * WHY THIS EXISTS — measured, not hypothetical.
+ *
+ * Every concern is inlined into one `dist/hooks/dispatch.js` that every hook
+ * event loads, so a dependency added for ONE concern is paid by all of them on
+ * every dispatch. On 2026-10-01 the bundle carried two YAML parsers: `yaml`,
+ * pulled by six modules including the dispatcher itself, and `js-yaml`, pulled
+ * by one call site in `block_config_weakening.ts` — 95,846 bytes, 6.13 % of a
+ * 1,564,211-byte bundle. Beside it, `host_lowering.ts`'s own header said the
+ * `yaml` reader was "the ONLY remaining YAML reader on that path".
+ *
+ * Nothing in this tree could see either fact. The freshness gate compares
+ * mtimes, the content gate compares digests, and neither has an opinion about
+ * what is INSIDE the bundle. So the second parser reached a release and was
+ * found by an external rescore counting bytes — a review finding where it
+ * should have been a red check. This gate is that red check.
+ *
+ * WHAT IT CHECKS
+ *
+ *   1. At most `max_yaml_packages` YAML packages contribute bytes to the
+ *      bundle. The package set is {@link YAML_PACKAGES} — a closed list, so a
+ *      third parser arriving under a name nobody listed is NOT caught here, and
+ *      that limit is stated rather than implied.
+ *   2. The bundle's byte count is at or under `max_bytes`.
+ *
+ * Both bounds live in `src/config/hook-bundle-budget.json`, never in this file:
+ * a number a reviewer has to read a script to find is a number nobody reviews.
+ *
+ * WHY IT BUILDS RATHER THAN READS. `dist/hooks/` is untracked, so a gate that
+ * read the bundle on disk would be local-only like `check_hook_bundle_content`
+ * — and the thing being bounded is what the SOURCE produces, which is a
+ * property of the commit rather than of a machine. So this builds its own
+ * bundle with `--metafile` and measures that. It runs identically in CI and
+ * locally, and it never touches the live bundle.
+ *
+ * The esbuild invocation is NOT duplicated here: it is read from
+ * `package.json`'s `build:hooks` script with only `--outfile=` rewritten, via
+ * the same `rewriteOutfile` helper `rebuild_hook_bundle` and
+ * `check_hook_bundle_content` use, so the flag set has exactly one home. The
+ * trailing `&& node src/scripts/write_bundle_digest.mjs` is stripped — this
+ * gate must not write a sidecar for a probe bundle nobody executes.
+ *
+ * WHAT IT DOES NOT DO. It says nothing about LATENCY. A smaller bundle is not
+ * a measured speed-up; `src/config/hook-latency-budget.json` owns that axis and
+ * no number here is derived from it. It says nothing about the install or MCP
+ * bundles, which carry their own module graphs.
+ *
+ * Usage:
+ *     ./scripts-run src/scripts/check_hook_bundle_composition
+ *     ./scripts-run src/scripts/check_hook_bundle_composition --metafile <path>
+ *     ./scripts-run src/scripts/check_hook_bundle_composition --self-test
+ *
+ * Exit codes: 0 = within budget · 1 = over the ceiling or a second reader ·
+ * 2 = the build or the budget file failed.
+ */
+// ledger-exempt: single-artefact transaction — one bundle build yielding one
+// aggregate verdict. The per-source accounting lives in
+// check_hook_bundle_freshness, which carries the ledger.
+import { spawnSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { runGateCli, runSelfTest } from './_lib/gate_self_test.js';
+import { reportScanned } from './_lib/scan_scope.js';
+import { buildScript } from './check_hook_bundle_content.js';
+import { rewriteOutfile } from './rebuild_hook_bundle.js';
+
+const _HERE = path.dirname(fileURLToPath(import.meta.url));
+export const REPO_ROOT = path.resolve(_HERE, '..', '..');
+export const SELF_REL = path.join('src', 'scripts', 'check_hook_bundle_composition.ts');
+export const BUDGET_REL = path.join('src', 'config', 'hook-bundle-budget.json');
+const LIVE_REL = path.join('dist', 'hooks', 'dispatch.js');
+
+/**
+ * The YAML readers this tree has ever carried, by package name.
+ *
+ * A CLOSED LIST, and the consequence is worth stating: a fourth parser arriving
+ * under a name not listed here contributes bytes the ceiling catches and the
+ * parser cap does not. The alternative — treating any package whose name
+ * contains "yaml" as a reader — would match a YAML-adjacent utility that is not
+ * a parser, and a cap that fires on the wrong package is worse than one that
+ * misses an unlisted one, because the first teaches people to raise the cap.
+ */
+export const YAML_PACKAGES: readonly string[] = ['yaml', 'js-yaml', 'yaml-js', 'yamljs'];
+
+export interface Budget {
+    readonly maxBytes: number;
+    readonly maxYamlPackages: number;
+}
+
+export interface Analysis {
+    /** Bytes of the bundle esbuild produced. */
+    readonly bytes: number;
+    /** Modules that contributed to it — the unit `scanned:` reports. */
+    readonly modules: number;
+    /** Bytes in the output, summed per owning npm package. */
+    readonly packageBytes: ReadonlyMap<string, number>;
+    /** Listed YAML packages contributing more than zero bytes, sorted. */
+    readonly yamlPackages: readonly string[];
+}
+
+/**
+ * The npm package a bundled module path belongs to, or `null` for this tree's
+ * own sources.
+ *
+ * Reads the INNERMOST `node_modules/` segment: a transitively nested copy
+ * (`node_modules/a/node_modules/yaml/…`) is still `yaml`'s bytes, and
+ * attributing it to `a` would let a second parser hide one level down.
+ */
+export function owningPackage(modulePath: string): string | null {
+    const marker = 'node_modules/';
+    const at = modulePath.lastIndexOf(marker);
+    if (at < 0) return null;
+    const parts = modulePath.slice(at + marker.length).split('/');
+    const head = parts[0] ?? '';
+    if (head === '') return null;
+    return head.startsWith('@') ? `${head}/${parts[1] ?? ''}` : head;
+}
+
+/** Parse an esbuild metafile and attribute its one entry-point output. */
+export function analyzeMetafile(json: string): Analysis {
+    const meta = JSON.parse(json) as {
+        outputs?: Record<string, { entryPoint?: string; bytes?: number; inputs?: Record<string, { bytesInOutput?: number }> }>;
+    };
+    const outputs = Object.values(meta.outputs ?? {});
+    const out = outputs.find((o) => typeof o.entryPoint === 'string');
+    if (out === undefined) {
+        throw new Error(
+            'metafile carries no entry-point output — refusing to report a composition for a build that produced nothing',
+        );
+    }
+    const packageBytes = new Map<string, number>();
+    const inputs = out.inputs ?? {};
+    for (const [p, v] of Object.entries(inputs)) {
+        const pkg = owningPackage(p);
+        if (pkg === null) continue;
+        packageBytes.set(pkg, (packageBytes.get(pkg) ?? 0) + (v.bytesInOutput ?? 0));
+    }
+    const yamlPackages = YAML_PACKAGES.filter((p) => (packageBytes.get(p) ?? 0) > 0).sort();
+    return {
+        bytes: out.bytes ?? 0,
+        modules: Object.keys(inputs).length,
+        packageBytes,
+        yamlPackages,
+    };
+}
+
+/** Read the committed budget. Throws rather than defaulting — a guessed ceiling bounds nothing. */
+export function readBudget(root: string): Budget {
+    const abs = path.join(root, BUDGET_REL);
+    const raw = JSON.parse(fs.readFileSync(abs, 'utf-8')) as Record<string, unknown>;
+    const maxBytes = raw['max_bytes'];
+    const maxYaml = raw['max_yaml_packages'];
+    if (typeof maxBytes !== 'number' || !Number.isInteger(maxBytes) || maxBytes <= 0) {
+        throw new Error(`${BUDGET_REL}: max_bytes must be a positive integer, got ${JSON.stringify(maxBytes)}`);
+    }
+    if (typeof maxYaml !== 'number' || !Number.isInteger(maxYaml) || maxYaml < 1) {
+        throw new Error(
+            `${BUDGET_REL}: max_yaml_packages must be an integer >= 1, got ${JSON.stringify(maxYaml)}`,
+        );
+    }
+    return { maxBytes, maxYamlPackages: maxYaml };
+}
+
+/** Findings, one line each. Empty means within budget. */
+export function verdict(a: Analysis, budget: Budget): string[] {
+    const findings: string[] = [];
+    if (a.yamlPackages.length > budget.maxYamlPackages) {
+        const detail = a.yamlPackages
+            .map((p) => `${p} (${String(a.packageBytes.get(p) ?? 0)} B)`)
+            .join(', ');
+        findings.push(
+            `${String(a.yamlPackages.length)} YAML readers in the bundle, cap is ` +
+                `${String(budget.maxYamlPackages)}: ${detail}. Every dispatch loads all of them. ` +
+                'Move the odd caller onto the reader the dispatcher already uses.',
+        );
+    }
+    if (a.bytes > budget.maxBytes) {
+        findings.push(
+            `bundle is ${String(a.bytes)} bytes, ceiling is ${String(budget.maxBytes)} ` +
+                `(over by ${String(a.bytes - budget.maxBytes)}). Shrink the bundle, or raise ` +
+                `max_bytes in ${BUDGET_REL} WITH an entry in its raise_log naming what was added.`,
+        );
+    }
+    return findings;
+}
+
+/**
+ * The raise rule, enforced against the base revision.
+ *
+ * `road-to-a-ratification-fence-that-follows-its-imports` 3.2. The budget's
+ * `shrink_only_note` used to say a raise needs a `raise_log` entry and that
+ * "the gate prints the rule but cannot enforce it, because a raise and a
+ * lowering are the same edit to a number". Against the base revision they are
+ * not: a working `max_bytes` above the base's is a raise, and it passes only if
+ * `raise_log` gained an entry — one absent from the base's log — whose `to`
+ * equals the new ceiling. A lowering needs nothing. The comparison is the
+ * merged value against the base, because that is what ships; a ceiling raised
+ * and lowered inside one branch is judged by where it ends.
+ *
+ * `baseRaw` is the base revision's budget file, or `null` when it has none
+ * (the registration diff), which is not a raise.
+ */
+export function raiseFindings(baseRaw: string | null, workingRaw: string): string[] {
+    if (baseRaw === null) {
+        return [];
+    }
+    const base = JSON.parse(baseRaw) as Record<string, unknown>;
+    const working = JSON.parse(workingRaw) as Record<string, unknown>;
+    const baseMax = base['max_bytes'];
+    const workingMax = working['max_bytes'];
+    if (typeof baseMax !== 'number' || typeof workingMax !== 'number' || workingMax <= baseMax) {
+        return [];
+    }
+    const baseLog = Array.isArray(base['raise_log']) ? (base['raise_log'] as unknown[]) : [];
+    const workingLog = Array.isArray(working['raise_log']) ? (working['raise_log'] as unknown[]) : [];
+    const seen = new Set(baseLog.map((e) => JSON.stringify(e)));
+    const gained = workingLog.filter((e) => !seen.has(JSON.stringify(e)));
+    const matching = gained.find((e) => isRecord(e) && e['to'] === workingMax);
+    if (matching === undefined) {
+        return [
+            `max_bytes raised from ${String(baseMax)} to ${String(workingMax)} against the base revision ` +
+                `with no new raise_log entry whose \`to\` is ${String(workingMax)}. A raise needs a recorded ` +
+                `reason in ${BUDGET_REL}'s raise_log naming what was added and why it could not be avoided.`,
+        ];
+    }
+    const problems = raiseEntryProblems(matching as Record<string, unknown>, baseMax);
+    return problems.length === 0
+        ? []
+        : [`the raise_log entry for ${String(workingMax)} is incomplete: ${problems.join('; ')}.`];
+}
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+/** The prose fields an entry must carry, matching the entry the log already holds. */
+const RAISE_REASON_FIELDS = ['what_was_added', 'why_it_could_not_be_avoided'] as const;
+
+/**
+ * What a raise entry must say. A bare `{ "to": N }` matched the first version
+ * of this rule, which a ratification reviewer refused on: a log entry with no
+ * reason is the empty log the rule exists to refuse, wearing a key.
+ */
+export function raiseEntryProblems(entry: Record<string, unknown>, baseMax: number): string[] {
+    const problems: string[] = [];
+    if (entry['from'] !== baseMax) {
+        problems.push(`\`from\` must be the base ceiling ${String(baseMax)}`);
+    }
+    if (typeof entry['date'] !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(entry['date'])) {
+        problems.push('`date` must be YYYY-MM-DD');
+    }
+    for (const field of RAISE_REASON_FIELDS) {
+        const v = entry[field];
+        if (typeof v !== 'string' || v.trim().length < 20) {
+            problems.push(`\`${field}\` must say what happened, in at least a sentence`);
+        }
+    }
+    return problems;
+}
+
+/** The base revision's budget file, `null` when absent there, `undefined` when no base resolves. */
+function readBaseBudget(root: string, explicit: string | undefined): string | null | undefined {
+    const candidates = explicit !== undefined ? [explicit] : ['origin/main', 'main'];
+    for (const ref of candidates) {
+        const ok = spawnSync('git', ['rev-parse', '--verify', '--quiet', ref], {
+            cwd: root,
+            stdio: ['ignore', 'ignore', 'ignore'],
+        });
+        if (ok.status !== 0) continue;
+        const shown = spawnSync('git', ['show', `${ref}:${BUDGET_REL}`], { cwd: root, encoding: 'utf-8' });
+        return shown.status === 0 ? shown.stdout : null;
+    }
+    return undefined;
+}
+
+/**
+ * Build the hook bundle to a throwaway path and return its metafile JSON.
+ *
+ * Throws on any failure rather than returning a sentinel: a composition read off
+ * a build that did not happen is the silent-green this gate exists to replace.
+ */
+export function buildMetafile(root: string): string {
+    const script = buildScript(root);
+    if (script === null) {
+        throw new Error('package.json has no `build:hooks` script — refusing to guess the flag set');
+    }
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'hook-bundle-composition-'));
+    const outFile = path.join(dir, 'dispatch.js');
+    const metaFile = path.join(dir, 'meta.json');
+    try {
+        const rewritten = rewriteOutfile(script, outFile);
+        if (rewritten === null) {
+            throw new Error(`\`build:hooks\` no longer writes ${LIVE_REL} — refusing to build to a guessed path`);
+        }
+        // Strip the digest sidecar step: it would write `dispatch.sha256` beside
+        // a probe bundle nobody executes, and on failure it would mask the build
+        // error with a file-not-found.
+        const esbuildOnly = rewritten.split('&& node ')[0] ?? rewritten;
+        const built = spawnSync('sh', ['-c', `${esbuildOnly.trim()} --metafile=${metaFile}`], {
+            cwd: root,
+            encoding: 'utf-8',
+            maxBuffer: 64 * 1024 * 1024,
+            env: {
+                ...process.env,
+                PATH: `${path.join(root, 'node_modules', '.bin')}:${process.env['PATH'] ?? ''}`,
+            },
+        });
+        if (built.status !== 0 || !fs.existsSync(metaFile)) {
+            throw new Error(`esbuild failed (exit ${String(built.status)})\n${built.stderr ?? ''}`);
+        }
+        return fs.readFileSync(metaFile, 'utf-8');
+    } finally {
+        fs.rmSync(dir, { recursive: true, force: true });
+    }
+}
+
+function selfTest(): number {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'hook-bundle-composition-selftest-'));
+    const write = (name: string, body: unknown): string => {
+        const p = path.join(dir, name);
+        fs.writeFileSync(p, JSON.stringify(body));
+        return p;
+    };
+    const meta = (bytes: number, inputs: Record<string, number>): unknown => ({
+        inputs: {},
+        outputs: {
+            'dist/hooks/dispatch.js': {
+                entryPoint: 'src/scripts/hooks/dispatch_entry.ts',
+                bytes,
+                inputs: Object.fromEntries(
+                    Object.entries(inputs).map(([k, v]) => [k, { bytesInOutput: v }]),
+                ),
+            },
+        },
+    });
+    const budget = readBudget(REPO_ROOT);
+    const clean = write('clean.json', meta(budget.maxBytes, { 'node_modules/yaml/dist/index.js': 10 }));
+    const twoReaders = write(
+        'two-readers.json',
+        meta(1000, {
+            'node_modules/yaml/dist/index.js': 600,
+            'node_modules/js-yaml/dist/js-yaml.mjs': 400,
+        }),
+    );
+    const oneOver = write('one-over.json', meta(budget.maxBytes + 1, { 'src/x.ts': 1 }));
+    const empty = write('empty.json', { inputs: {}, outputs: {} });
+
+    const drive = (fixture: string): number =>
+        runGateCli(REPO_ROOT, SELF_REL, ['--metafile', fixture], REPO_ROOT);
+
+    try {
+        return runSelfTest({
+            gate: 'check_hook_bundle_composition',
+            minCases: 4,
+            minRejectCases: 3,
+            cases: [
+                {
+                    name: 'one YAML reader, exactly at the ceiling → accepted',
+                    expect: 'accept',
+                    run: () => drive(clean),
+                },
+                {
+                    name: 'a second YAML reader → rejected',
+                    expect: 'reject',
+                    run: () => drive(twoReaders),
+                },
+                {
+                    name: 'one byte over the ceiling → rejected',
+                    expect: 'reject',
+                    run: () => drive(oneOver),
+                },
+                {
+                    name: 'a metafile with no entry-point output → rejected, never reported as 0 bytes',
+                    expect: 'reject',
+                    run: () => drive(empty),
+                },
+            ],
+        });
+    } finally {
+        fs.rmSync(dir, { recursive: true, force: true });
+    }
+}
+
+export function main(argv: readonly string[] = process.argv.slice(2), root: string = REPO_ROOT): number {
+    if (argv.includes('--self-test')) {
+        return selfTest();
+    }
+    const at = argv.indexOf('--metafile');
+    const fixture = at >= 0 ? argv[at + 1] : undefined;
+
+    let budget: Budget;
+    try {
+        budget = readBudget(root);
+    } catch (e) {
+        process.stderr.write(`check_hook_bundle_composition: ${String(e instanceof Error ? e.message : e)}\n`);
+        return 2;
+    }
+
+    let json: string;
+    try {
+        json = fixture === undefined ? buildMetafile(root) : fs.readFileSync(fixture, 'utf-8');
+    } catch (e) {
+        process.stderr.write(`check_hook_bundle_composition: ${String(e instanceof Error ? e.message : e)}\n`);
+        return 2;
+    }
+
+    let analysis: Analysis;
+    try {
+        analysis = analyzeMetafile(json);
+    } catch (e) {
+        process.stderr.write(`check_hook_bundle_composition: ${String(e instanceof Error ? e.message : e)}\n`);
+        return 1;
+    }
+
+    const findings = verdict(analysis, budget);
+    const baseAt = argv.indexOf('--base-ref');
+    const baseBudget = readBaseBudget(root, baseAt >= 0 ? argv[baseAt + 1] : undefined);
+    if (baseBudget === undefined) {
+        // In CI an unresolvable base is a broken checkout, not a registration
+        // diff: refusing there is the difference between a rule and a notice.
+        // Locally a missing base is ordinary (a fresh clone without origin), so
+        // it is said rather than failed.
+        if (process.env['GITHUB_ACTIONS'] === 'true') {
+            process.stderr.write(
+                'check_hook_bundle_composition: no base revision resolved in CI — the max_bytes raise ' +
+                    'rule cannot be evaluated, and this gate fails closed rather than skip it\n',
+            );
+            return 2;
+        }
+        process.stdout.write('raise rule: no base revision resolved — the max_bytes raise check was not evaluated\n');
+    } else {
+        findings.push(...raiseFindings(baseBudget, fs.readFileSync(path.join(root, BUDGET_REL), 'utf-8')));
+    }
+    // Reported on BOTH paths, red included: a census that goes quiet exactly
+    // when the gate fires is the shape `reportScanned` exists to prevent.
+    reportScanned({
+        gate: 'check_hook_bundle_composition',
+        scanned: analysis.modules,
+        units: 'bundled module(s)',
+        roots: [LIVE_REL],
+    });
+
+    if (findings.length === 0) {
+        process.stdout.write(
+            `✅  hook bundle: ${String(analysis.bytes)} B / ${String(budget.maxBytes)} B ceiling, ` +
+                `${String(analysis.yamlPackages.length)} YAML reader(s) ` +
+                `[${analysis.yamlPackages.join(', ')}], ${String(analysis.modules)} modules\n`,
+        );
+        return 0;
+    }
+    process.stderr.write('❌  hook bundle composition is out of budget\n');
+    for (const f of findings) process.stderr.write(`    - ${f}\n`);
+    process.stderr.write(`    Budget: ${BUDGET_REL}\n`);
+    return 1;
+}
+
+function _isCliEntry(): boolean {
+    const argv1 = process.argv[1];
+    if (argv1 === undefined) return false;
+    if (import.meta.url === pathToFileURL(path.resolve(argv1)).href) return true;
+    try {
+        return fs.realpathSync(fileURLToPath(import.meta.url)) === fs.realpathSync(path.resolve(argv1));
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry()) {
+    process.exit(main());
+}

package/src/scripts/check_kernel_edit_ratified.ts

@@ -30,12 +30,16 @@
  *
  * Gated: a diff touching a kernel rule under `src/rules/` (the nine of
  * `_lib/kernel_rules.ts`), a governance hook (`src/scripts/hooks/block_*.ts`),
- * a hook-plumbing SOURCE (`hook_manifest.yaml`, `host_lowering.yaml`, a
- * `*-dispatcher.sh`, either hook budget file — see `PLUMBING_SOURCE_RE`),
- * or this gate itself — so it cannot be weakened without its own record. Such
- * a diff must carry a ratification artifact under
- * the ratifications directory with `verdict: ratified`, valid per the
- * ratification-artifact contract.
+ * hook plumbing — the YAML sources `hook_manifest.yaml` and
+ * `host_lowering.yaml`, their compiled siblings `hook_manifest.json` and
+ * `host_lowering.json`, the dispatcher `hooks/dispatch_hook.ts`, the
+ * kernel-rule list `_lib/kernel_rules.ts`, a `*-dispatcher.sh`, the token,
+ * latency and bundle budget files (see `PLUMBING_SOURCE_RE`), and every module
+ * the dispatcher imports that decides an exit code (derived at run time, see
+ * `derivedPlumbing`) — or this gate itself, so it cannot
+ * be weakened without its own record. Such a diff must carry a ratification
+ * artifact under the ratifications directory with `verdict: ratified`, valid
+ * per the ratification-artifact contract.
  *
  * Every kernel diff is gated, not only the authority-EXPANDING ones.
  * ADR-268 § 4 makes the artifact required for authority-expanding edits. Which
@@ -71,6 +75,7 @@ import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { GateLedger } from './_lib/gate_ledger.js';
+import { dispatchImportClosure, verdictModules } from './_lib/dispatch_import_closure.js';
 import { is_kernel_rule } from './_lib/kernel_rules.js';
 import { reportScanned } from './_lib/scan_scope.js';
 import {
@@ -90,6 +95,13 @@ export const SELF_PATH = 'src/scripts/check_kernel_edit_ratified.ts';
 /** The reader this gate shares with the artifact contract, also self-watched. */
 export const READER_PATH = 'src/scripts/_lib/ratification_artifact.ts';
 
+/**
+ * The reader that derives the dispatcher's verdict-deciding imports. It decides
+ * part of this gate's reach, so narrowing it is narrowing the gate — watched as
+ * part of the mechanism for the reason `READER_PATH` is.
+ */
+export const CLOSURE_READER_PATH = 'src/scripts/_lib/dispatch_import_closure.ts';
+
 /** The in-repo quorum policy. Present on every runner; absent means refuse. */
 export const POLICY_PATH = 'src/config/ratification-policy.json';
 
@@ -141,13 +153,109 @@ const GOVERNANCE_HOOK_RE = /^src\/scripts\/hooks\/block_[a-z0-9_]+\.ts$/;
  * and every property the gate already had — base-revision code, in-repo quorum
  * policy, the whole diff as its unit — carries over unchanged.
  *
- * Sources only. `dist/hooks/dispatch.js` and `hooks/hooks.json` are BUILD
- * OUTPUTS with no legitimate hand edit at all, so they are refused at tool-call
- * time by `block_plumbing_writes.ts` rather than ratified here — a record for a
- * file whose every hand edit is illegitimate would be a record of a mistake.
+ * `dist/hooks/dispatch.js` and `hooks/hooks.json` are BUILD OUTPUTS that no
+ * reader in this repository opens — they exist only inside an installed
+ * consumer tree — and they have no legitimate hand edit at all, so they are
+ * refused at tool-call time by `block_plumbing_writes.ts` rather than ratified
+ * here: a record for a file whose every hand edit is illegitimate would be a
+ * record of a mistake.
+ *
+ * road-to-blocking-severities 2.1 WIDENS this from "sources only" to
+ * "everything the dispatcher serves at runtime", and the distinction above is
+ * why the two compiled tables land here while the two build outputs do not.
+ * `src/scripts/hook_manifest.json` and `src/scripts/hooks/host_lowering.json`
+ * are committed in THIS tree and are READ IN PREFERENCE to the YAML they were
+ * compiled from — `dispatch_hook._load_yaml` and `host_lowering.resolveTable`
+ * both serve the compiled body whenever its fingerprint matches. A diff that
+ * edits only the JSON therefore changes what every host is told about which
+ * concern runs and which slot can refuse, while the gated YAML beside it is
+ * untouched. That is the same authority change as editing the source, reached
+ * one file later, and before this step it carried no record.
+ *
+ * Two further files join for the same reason rather than by analogy:
+ *
+ *   - `src/scripts/hooks/dispatch_hook.ts` is the dispatcher itself. Every
+ *     concern's verdict passes through it, so an edit here can suppress a
+ *     refusal without touching the manifest that declares it.
+ *   - `src/scripts/_lib/kernel_rules.ts` is the list of the nine kernel rules.
+ *     THIS GATE resolves `is_kernel_rule` through it, so a diff removing a name
+ *     from that list removes a rule from this gate's own reach — the one edit
+ *     that could quietly narrow the gate while every other path kept working.
+ *
+ * Both are also denied at tool-call time, `dispatch_hook.ts` through the
+ * plumbing guard's source set and `kernel_rules.ts` through the kernel-rule
+ * write guard, so the pairing of deny-plus-record matches what the YAML sources
+ * already had.
+ *
+ * The compiled tables are REGENERATED, not hand-edited, by
+ * `./scripts-run src/scripts/compile_hook_manifest --table manifest|host-lowering`,
+ * which runs as a script rather than as an edit tool call and so is not what
+ * either mechanism refuses. A regeneration lands in the same diff as the YAML
+ * change that caused it, which already requires a record; the case this closes
+ * is the diff where only the JSON moves.
  */
 const PLUMBING_SOURCE_RE =
-    /^(?:src\/scripts\/hook_manifest\.yaml|src\/scripts\/hooks\/host_lowering\.yaml|src\/scripts\/hooks\/[a-z0-9-]+-dispatcher\.sh|src\/config\/hook-(?:token|latency)-budget\.json)$/;
+    /^(?:src\/scripts\/hook_manifest\.(?:yaml|json)|src\/scripts\/hooks\/host_lowering\.(?:yaml|json)|src\/scripts\/hooks\/dispatch_hook\.ts|src\/scripts\/_lib\/kernel_rules\.ts|src\/scripts\/hooks\/[a-z0-9-]+-dispatcher\.sh|src\/config\/hook-(?:token|latency|bundle)-budget\.json)$/;
+
+/**
+ * The derived half of the plumbing set: every module in the static import
+ * closure of `dispatch_hook.ts` that decides an exit code or a refusal, read by
+ * `_lib/dispatch_import_closure.ts`.
+ *
+ * `road-to-a-ratification-fence-that-follows-its-imports` 2.2. The pattern
+ * above stayed correct until `_resolve_execution_failure` moved from the
+ * dispatcher into `concern_failure_policy.ts` — release finding `21900086c1a0`:
+ * a diff deciding whether a crashed blocking concern refuses then carried no
+ * record. A hand list fails the same way the next time a function moves, so
+ * this half is computed from the import graph at run time, and a module the
+ * dispatcher newly imports that names an exit code joins it with no edit here.
+ * Concerns stay outside: the walk stops at the concern table, and a governance
+ * concern is already gated by `GOVERNANCE_HOOK_RE`.
+ *
+ * `hook-bundle-budget.json` joins the pattern for D3: its ceiling was raised on
+ * its own registration day, and a raised ceiling is a looser budget reached one
+ * file earlier than the bundle it bounds.
+ */
+let _repoDerived: readonly string[] | null = null;
+export function derivedPlumbing(root: string = REPO): readonly string[] {
+    if (root === REPO) {
+        _repoDerived ??= verdictModules(REPO);
+        return _repoDerived;
+    }
+    return verdictModules(root);
+}
+
+/**
+ * Modules that ARRIVE in the dispatcher's closure: non-concern modules present
+ * in the closure under `root` and absent from the closure under `baseRoot`.
+ *
+ * The classifier reads names, so a verdict-deciding module with neutral names
+ * (`acceptsExecution(): boolean`, no exit constant) reads as `payload` or
+ * `neither` — the gap the first ratification round of this change refused it
+ * on. A name-based classifier cannot close that gap; what can is watching the
+ * one moment such a module becomes reachable. So any module newly reachable
+ * from the dispatcher is gated on the diff that makes it reachable, whatever
+ * its class, and a reviewer reads it once. Modules already in the base closure
+ * are judged by class, so routine edits to a payload helper stay record-free.
+ *
+ * The other direction needs no extra rule: a module the base classes as
+ * `verdict` stays watched through the union in `evaluate` even when the head
+ * strips the names that classed it, so declassifying one is itself a gated
+ * edit of it.
+ *
+ * Meaningful only where the two trees differ — in CI, where the gate's code is
+ * the base revision's and `root` is the head. A local run with `root` equal to
+ * the gate's own tree sees no arrivals, and says nothing it cannot measure.
+ */
+export function closureArrivals(root: string, baseRoot: string = REPO): string[] {
+    if (path.resolve(root) === path.resolve(baseRoot)) {
+        return [];
+    }
+    const base = new Set(dispatchImportClosure(baseRoot).map((e) => e.path));
+    return dispatchImportClosure(root)
+        .filter((e) => e.class !== 'concern' && !base.has(e.path))
+        .map((e) => e.path);
+}
 
 /**
  * A kernel rule, in the source tree or in any projection.
@@ -174,7 +282,11 @@ export interface GatedPaths {
 }
 
 /** Partition a changed-file list into the surfaces this gate watches. */
-export function classifyPaths(files: readonly string[]): GatedPaths {
+export function classifyPaths(
+    files: readonly string[],
+    derived: readonly string[] = derivedPlumbing(),
+): GatedPaths {
+    const derivedSet = new Set(derived);
     const kernelRules: string[] = [];
     const governanceHooks: string[] = [];
     const plumbing: string[] = [];
@@ -187,6 +299,7 @@ export function classifyPaths(files: readonly string[]): GatedPaths {
         if (
             p === SELF_PATH ||
             p === READER_PATH ||
+            p === CLOSURE_READER_PATH ||
             p === POLICY_PATH ||
             p === WORKFLOW_PATH ||
             ANCHOR_PATHS.includes(p)
@@ -203,7 +316,7 @@ export function classifyPaths(files: readonly string[]): GatedPaths {
             governanceHooks.push(p);
             continue;
         }
-        if (PLUMBING_SOURCE_RE.test(p)) {
+        if (PLUMBING_SOURCE_RE.test(p) || derivedSet.has(p)) {
             plumbing.push(p);
         }
     }
@@ -281,7 +394,12 @@ export function evaluate(
     providerCount: number | null,
 ): GateResult {
     const lines: string[] = [];
-    const gated = classifyPaths(files);
+    // The union of the closure read from the tree under review and from this
+    // script's own tree: under CI the gate code is the base revision's and
+    // `root` is the head, so a module present on either side is watched.
+    const gated = classifyPaths(files, [
+        ...new Set([...derivedPlumbing(), ...derivedPlumbing(root), ...closureArrivals(root)]),
+    ]);
     const scanned = files.length;
 
     // Every changed path is a planned target: the gate's denominator is the