@event4u/agent-config 16.4.0 → 17.0.0

package/src/scripts/hooks/design_pass_hook.ts

@@ -48,6 +48,37 @@
  * reason instead of passing silently. `src/rules/design-review-after-ui-write.md`
  * already required that in prose with nothing to read it; this emits it.
  *
+ * SVG ROUTING, AND HOW TO REVERT IT. Step 1.3 of
+ * `road-to-svg-rules-in-the-dispatch-path`. An `.svg` write reaches
+ * `lint_svg_asset`'s rules from here, inside or outside a UI tree, through
+ * `svg_rules_loader` — a CJS chunk beside the dispatch bundle, required only
+ * for a path ending in `.svg`. The review that withdrew the first attempt
+ * named the gap plainly: a statically bundled rule set has no off switch, so
+ * the triggers and the mechanism are written down before they are needed.
+ *
+ *   REVERT WHEN any of these is read:
+ *     · the composition gate exceeds its ceiling attributable to this routing
+ *       (`check_hook_bundle_composition`; measured 2,128 B on 2026-10-11, with
+ *       16,910 B of headroom left);
+ *     · a non-`.svg` hook event is observed failing with a stack that passes
+ *       through the chunk — the containment case
+ *       `design_pass_svg.test.ts > rule-failure-does-not-reach-an-unrelated-event`
+ *       exists to make impossible, so one observation is enough;
+ *     · an operator reports SVG false positives on files they accept, at a rate
+ *       that would make them switch the carrier off — Risk 1 of the parent
+ *       roadmap, and the failure this whole concern is shaped around.
+ *
+ *   THE MECHANISM, in increasing order of blast radius:
+ *     1. Delete `dist/hooks/svg_rules.chunk.cjs`. The loader returns `null`,
+ *        the pass reports `verification: degraded` naming the missing file,
+ *        and every other finding family is unaffected. This is the per-install
+ *        off switch the static import could not have had.
+ *     2. Drop `isSvgAsset` from `isPassSurface` below. An `.svg` outside a UI
+ *        tree stops reaching the pass at all; one inside it reads as it did
+ *        before this step.
+ *     3. Turn the concern off entirely (`hooks.design_pass.enabled: false`),
+ *        which was already the default.
+ *
  * Default-OFF (`hooks.design_pass.enabled`), fail_closed: false.
  *
  * Exit codes (dispatcher contract): 0 allow · 1 block · 2 warn + JSON reason.
@@ -59,9 +90,10 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import { appendDischarge, stamp } from '../_lib/obligations.js';
 import { compareInputs } from '../_lib/probe_inputs.js';
 import { trigger_matches, type Trigger } from '../_lib/router_match.js';
-import { isUiPath, isUiTreePath } from '../_lib/ui_surface.js';
+import { HANDOVER_SHAPES, isUiPath, isUiTreePath } from '../_lib/ui_surface.js';
 import { loadDesignContext, scanFile } from '../lint_design_slop.js';
 import { readHookStdin } from './hook_stdin.js';
+import { CHUNK_BASENAME, loadSvgScan } from './svg_rules_loader.js';
 import { EXIT_ALLOW, EXIT_WARN } from './exit_codes.js';
 
 const SETTINGS_FILE = '.agent-settings.yml';
@@ -129,8 +161,42 @@ export function enabled(root: string, key = 'design_pass'): boolean {
     return false;
 }
 
+/**
+ * True for a path this pass should look at.
+ *
+ * `.svg` is admitted HERE and nowhere else — step 1.2 of
+ * `road-to-svg-rules-in-the-dispatch-path`. The obvious way to reach an `.svg`
+ * from this pass was to add `svg` to `UI_EXTENSIONS`, and that is the thing the
+ * parent roadmap's decision E10 and `design_pass_svg.test.ts` forbid: the same
+ * predicate backs `ui_route_nudge_hook`'s `isUiWrite`, so widening it would
+ * draw a UI routing nudge and its tokens on every icon dropped into `public/`.
+ * A local disjunct reaches the asset without touching the shared predicate, in
+ * either direction.
+ */
+export const isSvgAsset = (p: string): boolean => /\.svg$/i.test(p);
+
+/**
+ * UNCHANGED, and that is the point of the predicate below it.
+ *
+ * Finding 6 of this change's own completion review: widening THIS predicate to
+ * admit every `.svg` would have moved the UI-turn denominator the
+ * consultation-rate measurement is defined against — which the
+ * `HANDOVER_TRIGGERS` note further down reserves, in writing, as a different
+ * decision than any routing change. It was widened and is widened no longer.
+ */
 export const isUiSurface = (p: string): boolean => isUiPath(p) || isUiTreePath(p);
 
+/**
+ * What this PASS looks at — a UI surface, or any `.svg`.
+ *
+ * The routing step 1.2 of `road-to-svg-rules-in-the-dispatch-path` asked for,
+ * in the one place it belongs: the pass's own entry gate. Keeping it out of
+ * `isUiSurface` leaves every other reading that predicate feeds — the
+ * conformance verdict's noteworthy test, the denominator above — reading
+ * exactly what it read before.
+ */
+export const isPassSurface = (p: string): boolean => isUiSurface(p) || isSvgAsset(p);
+
 /**
  * The shadow read of `ui-conformance.json` — Phase 5 of
  * `road-to-behaviour-evidence-over-pixels`.
@@ -173,7 +239,7 @@ export interface ConformanceOptions {
  * The file-based half of `src/rules/design-fidelity.md`'s `triggers:` set — the
  * shipped answer to "is this file a provided design handover?".
  *
- * COPIED AS A CONSTANT, MATCHED BY THE SHIPPED MATCHER. Reading and parsing the
+ * A CONSTANT (the shared `HANDOVER_SHAPES`), MATCHED BY THE SHIPPED MATCHER. Reading and parsing the
  * rule's frontmatter here would put a YAML load on `post_tool_use`, the hottest
  * slot this concern binds, and would depend on a rule path that differs between
  * this repository and an installed consumer. The drift that a constant invites
@@ -182,18 +248,14 @@ export interface ConformanceOptions {
  * and not here fails CI.
  *
  * THE HONEST REACH. Only the two HTML patterns are reachable through this
- * carrier. `.claude/design-system/` names JSON and token files, which
+ * carrier. Both path prefixes name JSON and token files, which
  * `isUiSurface` does not admit, so `main` returns before the verdict is
  * computed. Widening `isUiSurface` to admit them would change the UI-turn
  * denominator that the consultation-rate measurement is defined against, which
- * is a different decision than this one. The prefix stays for parity with the
- * rule and is stated as unreachable rather than quietly dropped.
+ * is a different decision than this one. The prefixes stay for parity with the
+ * rule and are stated as unreachable rather than quietly dropped.
  */
-export const HANDOVER_TRIGGERS: readonly Trigger[] = [
-    { file_pattern: '*design.html' },
-    { file_pattern: '*.dc.html' },
-    { path_prefix: '.claude/design-system/' },
-];
+export const HANDOVER_TRIGGERS: readonly Trigger[] = HANDOVER_SHAPES;
 
 /** True when any of the paths this turn wrote is a provided design handover. */
 export function handoverTouched(paths: readonly string[]): boolean {
@@ -221,6 +283,16 @@ export function conformanceVerdict(root: string, opts: ConformanceOptions = {}):
             inputs?: unknown;
             dimensions?: { dimension: string; status: string; findings: number | null; reason?: string }[];
             findings?: { dimension?: string; probe_id?: string; expected?: string; observed?: string }[];
+            page_signature?: {
+                status?: string;
+                reason?: string;
+                widths?: {
+                    width?: string;
+                    leaves?: unknown[];
+                    arrangement?: unknown[];
+                    overflow?: { reference?: boolean; target?: boolean };
+                }[];
+            };
         };
 
         // Before anything is counted. A finding count measured against inputs
@@ -270,6 +342,32 @@ export function conformanceVerdict(root: string, opts: ConformanceOptions = {}):
                     `${addedElements.map((f) => f.probe_id ?? '?').join(', ')} — added, not ported`,
             );
         }
+        // ONE LINE, BELOW THE LINES THIS ALREADY PRINTS, and present only when
+        // the artefact carries the field — which is only when the reference
+        // collected no handle at all. The headline and the shadow-verdict trailer
+        // are byte-identical to what the same artefact without the field
+        // produces: this adds a line, it does not change one.
+        //
+        // The counts are per width and the overflow is a PAIR, never a change
+        // flag. A reader who is told "overflow changed" has to go and find out
+        // which way; a reader who is told `false/true` already knows.
+        const sig = a.page_signature;
+        if (sig) {
+            if (sig.status === 'read') {
+                const perWidth = (sig.widths ?? [])
+                    .map((w) => {
+                        const changed = (w.leaves?.length ?? 0) + (w.arrangement?.length ?? 0);
+                        return `${w.width}: ${changed} changed, overflow ${w.overflow?.reference}/${w.overflow?.target}`;
+                    })
+                    .join('; ');
+                parts.push(
+                    `  · page signature (the reference carried no handle, so the five rows above could ask ` +
+                        `nothing): ${perWidth} — kinds of leaf and of container, never nodes; not a finding`,
+                );
+            } else {
+                parts.push(`  · page signature: not available — ${sig.reason ?? 'no reason given'}`);
+            }
+        }
         parts.push(
             inputs.verdict === 'unchanged'
                 ? '  · inputs: unchanged since the probe ran'
@@ -441,6 +539,53 @@ function renderAvailable(root: string): boolean {
     }
 }
 
+/**
+ * SVG severity → this pass's severity.
+ *
+ * `error` and `warning` become P1 and P2; `inert` is dropped. Deliberately NOT
+ * P0: the P0 set above is a closed list of objective floors and it is the only
+ * thing that computes a block at stop. Routing a new rule family into it would
+ * change the block surface, which is a different decision than making the
+ * findings visible — and the one Risk 1 of the parent roadmap warns about.
+ */
+export function svgSeverity(s: 'error' | 'warning' | 'inert'): Finding['severity'] | null {
+    if (s === 'error') return 'P1';
+    if (s === 'warning') return 'P2';
+    return null;
+}
+
+export interface SvgRuleFinding {
+    rule: string;
+    file: string;
+    line: number;
+    snippet: string;
+    severity: 'error' | 'warning' | 'inert';
+}
+
+/**
+ * Map the SVG rule set's findings onto this pass's shape.
+ *
+ * Pure, and exported, so the routing can be proven without building a bundle:
+ * the half that is expensive to exercise end-to-end is the chunk load, and that
+ * has its own test in `svg_rules_loader`.
+ */
+export function svgFindings(raw: readonly SvgRuleFinding[], rel: string): Finding[] {
+    const out: Finding[] = [];
+    for (const f of raw) {
+        const severity = svgSeverity(f.severity);
+        if (severity === null) continue;
+        out.push({
+            file: rel,
+            severity,
+            catalogId: 'SVG',
+            rule: f.rule,
+            line: f.line,
+            message: `${f.rule}${f.snippet ? ` — ${f.snippet}` : ''}`,
+        });
+    }
+    return out;
+}
+
 /** Extracts the written path from a tool payload, whichever key the host uses. */
 export function targetPath(payload: unknown): string | null {
     if (typeof payload !== 'object' || payload === null) return null;
@@ -499,7 +644,7 @@ function main(): number {
         targets = state.touched;
     } else {
         const t = targetPath(payload);
-        if (!t || !isUiSurface(t)) return EXIT_ALLOW;
+        if (!t || !isPassSurface(t)) return EXIT_ALLOW;
         targets = [t];
         if (!state.touched.includes(t)) state.touched.push(t);
     }
@@ -508,6 +653,7 @@ function main(): number {
     // Findings come from the shipped registry, via the same entrypoint CI uses.
     const findings: Finding[] = [];
     let scanFailed: string | null = null;
+    let svgRulesUnavailable = false;
     try {
         const ctx = loadDesignContext(root);
         for (const rel of targets) {
@@ -517,6 +663,17 @@ function main(): number {
             // itself rather than handing over a path, which is also what lets a
             // post-write pass see the bytes that were just written.
             const content = fs.readFileSync(abs, 'utf-8');
+            if (isSvgAsset(rel)) {
+                // The conditional chunk. Loaded only here, so a hook event that
+                // never touched an `.svg` pays none of its bytes and runs none
+                // of its code — the containment `design_pass_svg.test.ts` pins.
+                // A null load is reported through `svgRulesUnavailable`, never
+                // thrown: a consumer whose install is missing the chunk must
+                // lose the SVG findings, not the whole dispatch.
+                const scan = loadSvgScan();
+                if (scan === null) svgRulesUnavailable = true;
+                else findings.push(...svgFindings(scan(content, rel) as SvgRuleFinding[], rel));
+            }
             for (const f of scanFile(content, rel, ctx)) {
                 findings.push({
                     file: rel,
@@ -532,11 +689,40 @@ function main(): number {
         scanFailed = String(err);
     }
 
-    const auditMissing = targets.filter((t) => !auditIsFresh(root, t));
-    recordAuditDischarge(root, targets, auditMissing);
+    // The audit question is asked of UI SURFACES, never of the pass surface.
+    // Findings 1 and 2 of the third completion review, both reproduced by
+    // running the hook: round one split the entry gate from the UI predicate,
+    // and `targets` carried the `.svg` past the split anyway. So a clean
+    // conformant icon write exited WARN with "no ui-audit.json newer than
+    // public/icon.svg" — an asset has no component inventory to be audited
+    // against — and, worse, `recordAuditDischarge` returns early on a non-empty
+    // `auditMissing`, so writing ONE `.svg` in a turn silently suppressed the
+    // ui-audit discharge row for every real UI file in that same turn.
+    const auditTargets = targets.filter((t) => isUiSurface(t));
+    const auditMissing = auditTargets.filter((t) => !auditIsFresh(root, t));
+    recordAuditDischarge(root, auditTargets, auditMissing);
     let result = decide(slot, findings, auditMissing, new Set(state.surfaced), renderAvailable(root));
     if (scanFailed) {
         result = { ...result, verification: 'unverified', degradation_reason: `detector unavailable: ${scanFailed}` };
+    } else if (svgRulesUnavailable) {
+        // Degraded, not unverified: the rest of the pass ran. An absent chunk
+        // is reported rather than silently producing a clean SVG verdict —
+        // "absent is not clean" is the same rule the conformance verdict keeps.
+        // APPENDED, never overwritten. Finding 6 of the fourth completion
+        // review: `decide` may already have set a reason — the renderer being
+        // absent is the one it sets — and assigning here threw it away, so a
+        // turn where both degradations held reported only the newer one. Two
+        // degradations are two facts; the operator needs both or they fix one
+        // and are surprised by the other.
+        const svgReason = `the SVG rule set could not be loaded (expected dist/hooks/${CHUNK_BASENAME} beside the dispatch bundle) — the .svg files in this turn were not checked`;
+        result = {
+            ...result,
+            verification: 'degraded',
+            degradation_reason:
+                result.degradation_reason === undefined || result.degradation_reason === ''
+                    ? svgReason
+                    : `${result.degradation_reason}; ${svgReason}`,
+        };
     }
 
     for (const f of result.findings) state.surfaced.push(`${f.file}::${f.rule}::${f.line}`);

package/src/scripts/hooks/dispatch_hook.ts

@@ -47,7 +47,7 @@ import {
 } from "./state_io.js";
 import { log_dispatch_issue, fix_hint } from "./dispatch_issues.js";
 import { shapeAndRecord, type ConcernMessage } from "./injection_budget.js";
-import { CONCERN_REGISTRY, type ConcernMain } from "./concern_registry.js";
+import { resolveConcernMain, type ConcernMain } from "./concern_registry.js";
 import {
   setHookStdinOverride,
   clearHookStdinOverride,
@@ -56,6 +56,7 @@ import { emitFor, type PermissionDecision, type Severity } from "./host_semantic
 import { _concern_permission_verdict, _payload_tool_name, _permission_for } from "./permission_gate.js";
 export { _concern_permission_verdict, _payload_tool_input, _payload_tool_name, _permission_for, _working_tree_root } from "./permission_gate.js";
 import { _concern_body_classes, planPayloadShapes } from "./payload_stub.js";
+import { attributeRefusal, egressInjection, egressViewFor, runEgressStage } from "./egress_stage.js";
 import { resolveSessionRole, type SessionRole } from "../_lib/session_role.js";
 import { stdinReadFailure, denyOnStdinFailure } from './stdin_failure_policy.js';
 export { stdinReadFailure, denyOnStdinFailure, _is_fail_closed_blocking } from './stdin_failure_policy.js';
@@ -678,8 +679,8 @@ function _run_concern(concern: ConcernDef, envelope: JsonObject): RunResult {
   // In-process fast path — the default whenever the concern is in the
   // static registry (all manifest concerns; parity is CI-enforced).
   if (process.env["AGENT_CONFIG_HOOKS_ISOLATED"] !== "1") {
-    const inproc = CONCERN_REGISTRY[String(concern["script"])];
-    if (inproc !== undefined) {
+    const inproc = resolveConcernMain(String(concern["script"]));
+    if (inproc !== null) {
       return _run_concern_inproc(inproc, concern, envelope);
     }
   }
@@ -1276,12 +1277,11 @@ export function main(argv?: string[]): number {
   // Per-concern `tools:` filter (see _concern_matches_tool). Applied here so it
   // is one place, after the envelope exists and before any concern is spawned.
   const tool_name = _payload_tool_name(envelope);
-  // Payload opt-in (step 2.1). There are at most FOUR distinct envelope shapes
-  // per dispatch (keep neither / input / result / both), so they are memoised
-  // by keep-set: concerns sharing a declaration share one clone, and building
-  // one per concern would re-pay the allocation the stub exists to avoid.
-  // `present` is the set of body classes this event actually carries — empty on
-  // every non-tool event, which is why those pay nothing at all.
+  // The egress stage (ADR-285) builds the placeholder view before any concern
+  // runs; `egressViewFor` decides which concern gets which view.
+  const egress = runEgressStage(envelope);
+  // What the concerns inject back into the session passes the engine too (3.5).
+  const injected = egressInjection(String(envelope["workspace_root"] || process.cwd()));
   // Payload opt-in (step 2.1). One planner owns the whole decision — which
   // classes are present, which any concern loses, the single measurement pass,
   // and the at-most-four envelope shapes — so the loop below reads a shape
@@ -1293,12 +1293,13 @@ export function main(argv?: string[]): number {
   const shapes = planPayloadShapes(
     envelope,
     keep_by_concern.map(([, keep]) => keep),
+    egress.placeholder,
   );
   for (const [concern, keep_classes] of keep_by_concern) {
     if (!_concern_matches_tool(concern, tool_name)) {
       continue;
     }
-    const concern_envelope = shapes.shapeFor(keep_classes);
+    const concern_envelope = shapes.shapeFor(keep_classes, egressViewFor(concern));
     const stubs_served = shapes.stubsFor(keep_classes);
     // What was actually SERVED, not what was declared. Recording the
     // declaration made the record wrong in both directions on a body-less
@@ -1365,7 +1366,7 @@ export function main(argv?: string[]): number {
         : "";
     const message = [stated, extra].filter(Boolean).join("\n\n");
     if (message) {
-      concern_messages.push({ rc, text: message, def: concern });
+      concern_messages.push({ rc, text: attributeRefusal(String(concern["name"]), rc === EXIT_BLOCK, injected(message)), def: concern });
     }
     if (
       args.event === "session_start" &&
@@ -1373,7 +1374,7 @@ export function main(argv?: string[]): number {
       typeof reply["context"] === "string" &&
       (reply["context"] as string).trim()
     ) {
-      context_blocks.push((reply["context"] as string).trim());
+      context_blocks.push(injected((reply["context"] as string).trim()));
     }
     feedback_entries.push({
       concern: String(concern["name"]),

package/src/scripts/hooks/egress_engine_loader.ts

@@ -0,0 +1,125 @@
+/**
+ * Loads the egress engine (`_lib/egress_engine.ts`) on demand.
+ *
+ * WHY A CHUNK. The engine is about 19 KB of `dist/hooks/dispatch.js`, the one
+ * bundle every hook event loads, while the egress stage's shipped mode is `off`
+ * and never touches it. With 3 KB of headroom under the bundle ceiling and
+ * 12–15 KB of engine growth queued, an AI council of two providers chose on
+ * 2026-10-18 to emit the engine as `egress_engine.chunk.cjs` beside the bundle
+ * rather than raise the ceiling — the shape `svg_rules_loader.ts` set.
+ *
+ * WHY THIS ONE IS STRICTER THAN THE SVG LOADER. A missing SVG rule set costs a
+ * lint finding; a missing egress engine would let content through unscanned.
+ * So a chunk is refused when its digest does not match its sidecar, when there
+ * is no sidecar to match, and when its `ENGINE_SCHEMA` is not the one this
+ * loader was built against — a correctly digested chunk of another release is
+ * a load failure, never stale rules. Every failure is a value, never a throw,
+ * and each caller decides what an unavailable engine means for it: the stage
+ * withholds bodies in `protect` and `strict` and records the miss in
+ * `observe`; the subagent capsule rejects the envelope.
+ *
+ * WHY `require` AND THE COMPUTED SPECIFIER — see `svg_rules_loader.ts`: a
+ * concern is synchronous, and a literal specifier would be inlined by esbuild,
+ * which is the cost this exists to avoid.
+ */
+import * as fs from 'node:fs';
+import { createRequire } from 'node:module';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import type * as Engine from '../_lib/egress_engine.js';
+import { verifyBundle } from './bundle_integrity.js';
+
+/** The engine's exports. Type-only, so no engine byte reaches the bundle. */
+export type EgressEngine = typeof Engine;
+
+/** The schema this loader accepts. Must equal `ENGINE_SCHEMA` in the engine. */
+export const EXPECTED_ENGINE_SCHEMA = 2;
+
+export const ENGINE_CHUNK_BASENAME = 'egress_engine.chunk.cjs';
+
+export type EngineLoad =
+    | { readonly ok: true; readonly engine: EgressEngine }
+    | { readonly ok: false; readonly reason: 'missing' | 'digest' | 'schema' | 'invalid' };
+
+declare const __AGENT_CONFIG_BUNDLE__: boolean | undefined;
+
+function isBundled(): boolean {
+    return typeof __AGENT_CONFIG_BUNDLE__ !== 'undefined' && __AGENT_CONFIG_BUNDLE__;
+}
+
+/** Where the engine loads from: the sibling chunk when bundled, the source module otherwise. */
+export function engineSpecifier(selfUrl: string, bundled: boolean): string {
+    const selfPath = fileURLToPath(selfUrl);
+    const dir = path.dirname(selfPath);
+    if (bundled) return path.join(dir, ENGINE_CHUNK_BASENAME);
+    const ext = selfPath.endsWith('.ts') ? '.ts' : '.js';
+    return path.join(dir, '..', '_lib', `egress_engine${ext}`);
+}
+
+/**
+ * From source the engine is TypeScript whose imports name `.js` siblings, which
+ * a plain `require` cannot resolve outside a `tsx` process (a test runner, for
+ * one). `tsx`'s own require resolves them; the specifier is computed so esbuild
+ * never pulls `tsx` into the bundle, where this branch is not taken. Without
+ * `tsx` the plain require fails on such a module, which is `invalid`: the
+ * source path is a development path, and it fails closed like every other.
+ */
+function sourceRequire(req: NodeJS.Require): (id: string, from: string) => unknown {
+    try {
+        const api = req(['tsx', 'cjs', 'api'].join('/')) as { require?: (id: string, from: string) => unknown };
+        if (typeof api.require === 'function') return api.require;
+    } catch {
+        // tsx absent: a plain require is the only reader left.
+    }
+    return (id: string) => req(id);
+}
+
+/**
+ * The uncached load; `bundled` is a test seam, the hook path never passes it.
+ *
+ * Every step — resolving the specifier, the existence check, the digest, the
+ * load, the export check — runs inside one conversion boundary, so the function
+ * returns a value on every path. `missing` means the chunk file itself is
+ * absent; once it exists, anything its load throws (a dependency it cannot
+ * resolve included) is `invalid`.
+ */
+export function loadEgressEngineUncached(selfUrl: string = import.meta.url, bundled: boolean = isBundled()): EngineLoad {
+    try {
+        const specifier = engineSpecifier(selfUrl, bundled);
+        if (!fs.existsSync(specifier)) return { ok: false, reason: 'missing' };
+        // No sidecar, a malformed one or a mismatch: the chunk is not the one built.
+        if (bundled && verifyBundle(specifier).state !== 'ok') return { ok: false, reason: 'digest' };
+        let mod: Record<string, unknown>;
+        try {
+            const req = createRequire(selfUrl);
+            mod = (bundled ? req(specifier) : sourceRequire(req)(specifier, fileURLToPath(selfUrl))) as Record<string, unknown>;
+        } catch {
+            return { ok: false, reason: 'invalid' };
+        }
+        if (mod['ENGINE_SCHEMA'] !== EXPECTED_ENGINE_SCHEMA) return { ok: false, reason: 'schema' };
+        for (const name of ['detect', 'replaceValues', 'scanText', 'TokenScope', 'EgressRefusedError', 'tallyText', 'injectText', 'replaceJson']) {
+            if (typeof mod[name] !== 'function') return { ok: false, reason: 'invalid' };
+        }
+        if (!Array.isArray(mod['EGRESS_RULES'])) return { ok: false, reason: 'invalid' };
+        return { ok: true, engine: mod as unknown as EgressEngine };
+    } catch {
+        return { ok: false, reason: 'invalid' };
+    }
+}
+
+const cache = new Map<string, EngineLoad>();
+
+/** The engine or why it is unavailable; cached per process, failures included. */
+export function loadEgressEngine(selfUrl: string = import.meta.url): EngineLoad {
+    const hit = cache.get(selfUrl);
+    if (hit !== undefined) return hit;
+    const load = loadEgressEngineUncached(selfUrl);
+    cache.set(selfUrl, load);
+    return load;
+}
+
+/** Test seam: forget every cached load. Never called by the hook path. */
+export function _resetEgressEngineCache(): void {
+    cache.clear();
+}