@event4u/agent-config 16.4.0 → 17.0.0

package/src/scripts/_lib/design_system_claude_design.ts

@@ -0,0 +1,323 @@
+/**
+ * The `claude-design` import lane, snapshot input (road-to-a-canvas-the-code-owns
+ * step 3.2).
+ *
+ * Reads a directory the USER exported from the host's design canvas and maps it
+ * into the same `design-system.json` shape the other three lanes produce. The
+ * local-bundle input the host's own `/design-sync` writes is a separate half
+ * (step 3.2b) and waits on an observed listing of that layout; nothing here
+ * guesses it.
+ *
+ * What a snapshot directory may hold, and where each part goes:
+ *
+ *   source.json         provenance (`{"source": {kind, ref, captured_at}}`) and an
+ *                       optional `maturity`; without it the caller must supply one
+ *   *.tokens.json       W3C DTCG tokens, mapped by the `dtcg` lane unchanged
+ *   *.css               the custom-property closure: every `--x: value` declared,
+ *                       every `var(--x)` resolved through it, every reference with
+ *                       no declaration listed in `_meta.unresolved_custom_properties`
+ *   *.d.ts              component contracts — an exported capitalised component
+ *                       and the keys of its `<Name>Props` type
+ *   *.md                guidelines, kept verbatim under `_meta.guidelines`
+ *   anything else       listed in `_meta.unmapped`, never dropped
+ *
+ * **A snapshot is data (step 3.4).** The lane only ever reads bytes as text: it
+ * imports no snapshot file, evaluates nothing, follows no symlink and fetches no
+ * `@import`. A visual look at snapshot markup goes through the isolated asset
+ * renderer, never through this module.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import {
+    type ComponentObservation,
+    type DesignSystem,
+    type ImportOutcome,
+    type ProvenanceOverride,
+    type SourceBlock,
+    importDesignSystem,
+} from './design_system_import.js';
+
+/** Files above this size are listed, not read — a snapshot is not a dump. */
+const MAX_FILE_BYTES = 1_048_576;
+const MAX_DEPTH = 8;
+
+const COLOR_VALUE = /^(#[0-9a-f]{3,8}|(rgb|rgba|hsl|hsla|oklch|oklab|lab|lch|color)\(.*\))$/i;
+
+interface Walked {
+    rel: string;
+    abs: string;
+}
+
+/** Every regular file under `root`, relative and sorted; symlinks are reported, not followed. */
+function walk(root: string): { files: Walked[]; skipped: string[] } {
+    const files: Walked[] = [];
+    const skipped: string[] = [];
+    const visit = (dir: string, depth: number): void => {
+        for (const name of fs.readdirSync(dir).sort()) {
+            const abs = path.join(dir, name);
+            const rel = path.relative(root, abs).split(path.sep).join('/');
+            const st = fs.lstatSync(abs);
+            if (st.isSymbolicLink()) skipped.push(`${rel} (symlink, not followed)`);
+            else if (st.isDirectory()) {
+                if (depth >= MAX_DEPTH) skipped.push(`${rel}/ (deeper than ${MAX_DEPTH})`);
+                else visit(abs, depth + 1);
+            } else if (st.isFile()) {
+                if (st.size > MAX_FILE_BYTES) skipped.push(`${rel} (over ${MAX_FILE_BYTES} bytes, not read)`);
+                else files.push({ rel, abs });
+            }
+        }
+    };
+    visit(root, 0);
+    return { files, skipped };
+}
+
+interface CssClosure {
+    light: Map<string, string>;
+    dark: Map<string, string>;
+    references: Set<string>;
+}
+
+/** Collect custom-property declarations, split by the dark-theme context they sit in. */
+export function readCustomProperties(css: string, into: CssClosure): void {
+    const text = css.replace(/\/\*[\s\S]*?\*\//g, '');
+    const stack: boolean[] = [];
+    let selector = '';
+    let i = 0;
+    while (i < text.length) {
+        const ch = text[i] as string;
+        if (ch === '{') {
+            const parentDark = stack.length > 0 && stack[stack.length - 1] === true;
+            stack.push(parentDark || /dark/i.test(selector));
+            selector = '';
+        } else if (ch === '}') {
+            stack.pop();
+            selector = '';
+        } else if (ch === ';') {
+            selector = '';
+        } else {
+            selector += ch;
+            // Tested only at a declaration's end: per character, an undelimited
+            // run in untrusted CSS made this quadratic.
+            const next = text[i + 1];
+            const m = next === ';' || next === '}' ? /^\s*(--[A-Za-z0-9_-]+)\s*:\s*([^;{}]*)$/.exec(selector) : null;
+            if (m !== null) {
+                const dark = stack.length > 0 && stack[stack.length - 1] === true;
+                (dark ? into.dark : into.light).set(m[1] as string, (m[2] as string).trim());
+            }
+        }
+        i += 1;
+    }
+    for (const m of text.matchAll(/var\(\s*(--[A-Za-z0-9_-]+)/g)) into.references.add(m[1] as string);
+}
+
+/** Resolve `var()` chains; a cycle or a missing declaration is reported, never invented. */
+function resolveVar(
+    value: string,
+    defs: Map<string, string>,
+    seen: Set<string>,
+): { value: string; cyclic: boolean; missing: boolean } {
+    const m = /^var\(\s*(--[A-Za-z0-9_-]+)\s*(?:,\s*(.*))?\)$/.exec(value.trim());
+    if (m === null) return { value, cyclic: false, missing: false };
+    const ref = m[1] as string;
+    if (seen.has(ref)) return { value, cyclic: true, missing: false };
+    const target = defs.get(ref);
+    if (target === undefined) {
+        return m[2] !== undefined ? { value: m[2].trim(), cyclic: false, missing: true } : { value, cyclic: false, missing: true };
+    }
+    return resolveVar(target, defs, new Set([...seen, ref]));
+}
+
+type Bucket = 'color' | 'radius' | 'shadow' | 'spacing' | 'font' | 'duration' | 'easing';
+
+function bucketOf(name: string, value: string): { bucket: Bucket; role: string } | null {
+    const bare = name.replace(/^--/, '');
+    const rules: Array<[RegExp, Bucket]> = [
+        [/^(color|colour)-/, 'color'],
+        [/^radius-|^rounded-/, 'radius'],
+        [/^shadow-|^elevation-/, 'shadow'],
+        [/^(space|spacing)-/, 'spacing'],
+        [/^font-(family-)?/, 'font'],
+        [/^duration-/, 'duration'],
+        [/^(ease|easing)-/, 'easing'],
+    ];
+    for (const [re, bucket] of rules) {
+        if (re.test(bare)) return { bucket, role: bare.replace(re, '') || bare };
+    }
+    if (COLOR_VALUE.test(value)) return { bucket: 'color', role: bare };
+    return null;
+}
+
+/** Component contracts from a `.d.ts`: capitalised exports and their `<Name>Props` keys. */
+export function readComponentContracts(dts: string): ComponentObservation[] {
+    const names = new Set<string>();
+    for (const m of dts.matchAll(/export\s+(?:declare\s+)?(?:function|const|class)\s+([A-Z][A-Za-z0-9_]*)/g)) {
+        names.add(m[1] as string);
+    }
+    const out: ComponentObservation[] = [];
+    for (const name of [...names].sort()) {
+        const body = new RegExp(`(?:interface|type)\\s+${name}Props\\b[^{]*\\{([\\s\\S]*?)\\n\\}`).exec(dts);
+        const props =
+            body === null
+                ? []
+                : [...(body[1] as string).matchAll(/^\s*(?:readonly\s+)?([A-Za-z_$][\w$]*)\??\s*:/gm)].map((p) => p[1] as string);
+        out.push({ name, observed: { props: [...new Set(props)].sort() } });
+    }
+    return out;
+}
+
+function readSourceJson(raw: string): { source?: SourceBlock; maturity?: string } {
+    try {
+        const parsed = JSON.parse(raw) as Record<string, unknown>;
+        const s = parsed['source'] as Record<string, unknown> | undefined;
+        const out: { source?: SourceBlock; maturity?: string } = {};
+        if (s && typeof s['ref'] === 'string' && typeof s['kind'] === 'string' && ['url', 'repo', 'dir'].includes(s['kind'])) {
+            out.source = {
+                kind: s['kind'] as SourceBlock['kind'],
+                ref: s['ref'],
+                captured_at: typeof s['captured_at'] === 'string' ? s['captured_at'] : 'unknown',
+                _meta: { provenance_origin: 'input' },
+            };
+        }
+        if (typeof parsed['maturity'] === 'string') out.maturity = parsed['maturity'];
+        return out;
+    } catch {
+        return {};
+    }
+}
+
+/** Import a user-exported canvas snapshot directory. Offline; reads text only. */
+export function importClaudeDesignSnapshot(dir: string, provenance?: ProvenanceOverride): ImportOutcome {
+    let st: fs.Stats;
+    try {
+        st = fs.statSync(dir);
+    } catch {
+        return { ok: false, lane: 'claude-design', reason: `claude-design lane rejected — ${dir} does not exist` };
+    }
+    if (!st.isDirectory()) {
+        return { ok: false, lane: 'claude-design', reason: 'claude-design lane rejected — the snapshot input is a directory, not a file' };
+    }
+    const { files, skipped } = walk(dir);
+    const notes: string[] = [];
+    const unmapped: string[] = [...skipped];
+    const closure: CssClosure = { light: new Map(), dark: new Map(), references: new Set() };
+    const components: ComponentObservation[] = [];
+    const componentPaths: Record<string, string> = {};
+    const guidelines: Array<{ path: string; text: string }> = [];
+    let sourceFile: { source?: SourceBlock; maturity?: string } = {};
+    let tokens: DesignSystem | null = null;
+
+    for (const f of files) {
+        const text = fs.readFileSync(f.abs, 'utf-8');
+        if (f.rel === 'source.json') sourceFile = readSourceJson(text);
+        else if (f.rel.endsWith('.tokens.json') || path.basename(f.rel) === 'tokens.json') {
+            let parsed: unknown = null;
+            try {
+                parsed = JSON.parse(text);
+            } catch {
+                unmapped.push(`${f.rel} (not valid JSON)`);
+                continue;
+            }
+            const stub: ProvenanceOverride = { kind: 'dir', ref: dir };
+            const r = importDesignSystem(parsed, stub, 'dtcg');
+            if (r.ok) tokens = r.design_system;
+            else unmapped.push(`${f.rel} (${r.reason})`);
+        } else if (f.rel.endsWith('.css')) readCustomProperties(text, closure);
+        else if (f.rel.endsWith('.d.ts')) {
+            for (const c of readComponentContracts(text)) {
+                if (componentPaths[c.name] !== undefined) continue;
+                components.push(c);
+                componentPaths[c.name] = f.rel;
+            }
+        } else if (f.rel.endsWith('.md')) guidelines.push({ path: f.rel, text });
+        else unmapped.push(f.rel);
+    }
+
+    const source: SourceBlock | undefined =
+        sourceFile.source ??
+        (provenance === undefined
+            ? undefined
+            : {
+                  kind: provenance.kind,
+                  ref: provenance.ref,
+                  captured_at: provenance.captured_at ?? 'unknown',
+                  _meta: { provenance_origin: 'caller' },
+              });
+    if (source === undefined) {
+        return {
+            ok: false,
+            lane: 'claude-design',
+            reason:
+                'claude-design lane rejected — no provenance. Add a source.json with {"source": {kind, ref, captured_at}} to the snapshot, or pass --source-kind and --source-ref',
+        };
+    }
+
+    const out: DesignSystem = { ...(tokens ?? {}), source };
+    const meta: Record<string, unknown> = { ...((tokens?._meta as Record<string, unknown> | undefined) ?? {}) };
+    if (meta['unmapped'] !== undefined) {
+        meta['unmapped_tokens'] = meta['unmapped'];
+        delete meta['unmapped'];
+    }
+    const aliasOf: Record<string, string> = { ...((meta['alias_of'] as Record<string, string> | undefined) ?? {}) };
+    const cycles: string[] = [];
+    const unresolved = new Set<string>();
+    const unmappedProps: Record<string, string> = {};
+    const allDefs = new Map([...closure.light, ...closure.dark]);
+    for (const ref of closure.references) if (!allDefs.has(ref)) unresolved.add(ref);
+
+    for (const [theme, defs] of [['light', closure.light], ['dark', closure.dark]] as const) {
+        const scope = theme === 'dark' ? new Map([...closure.light, ...closure.dark]) : closure.light;
+        for (const [name, rawValue] of [...defs].sort(([a], [b]) => a.localeCompare(b))) {
+            const r = resolveVar(rawValue, scope, new Set([name]));
+            const ref = /^var\(\s*(--[A-Za-z0-9_-]+)/.exec(rawValue.trim());
+            if (ref !== null) aliasOf[`css:${name}`] = ref[1] as string;
+            if (r.cyclic) cycles.push(`css:${name}`);
+            const b = bucketOf(name, r.value);
+            if (b === null || r.cyclic || (r.missing && r.value === rawValue)) {
+                unmappedProps[name] = rawValue;
+                continue;
+            }
+            const v = r.value;
+            if (b.bucket === 'color') {
+                out.colors = out.colors ?? {};
+                const target = (out.colors[theme] = out.colors[theme] ?? {});
+                target[b.role] = v;
+            } else if (theme === 'dark') unmappedProps[name] = rawValue;
+            else if (b.bucket === 'radius') (out.radius = out.radius ?? {})[b.role] = v;
+            else if (b.bucket === 'shadow') (out.shadow = out.shadow ?? {})[b.role] = v;
+            else if (b.bucket === 'spacing') (out.spacing = out.spacing ?? { scale: [] }).scale?.push(v);
+            else if (b.bucket === 'font') {
+                const typography = (out.typography = out.typography ?? {});
+                const name0 = (v.split(',')[0] ?? v).trim().replace(/^["']|["']$/g, '');
+                (typography.families = typography.families ?? []).push({ role: b.role, name: name0, bundled_local: false });
+            } else {
+                const motion = (out.motion = out.motion ?? {});
+                if (b.bucket === 'duration') (motion.durations = motion.durations ?? {})[b.role] = v;
+                else (motion.easings = motion.easings ?? {})[b.role] = v;
+            }
+        }
+    }
+
+    if (components.length > 0) {
+        out.components = [...(tokens?.components ?? []), ...components];
+        meta['component_paths'] = componentPaths;
+    }
+    if (Object.keys(aliasOf).length > 0) meta['alias_of'] = aliasOf;
+    if (cycles.length > 0) meta['alias_cycles'] = [...new Set([...((meta['alias_cycles'] as string[]) ?? []), ...cycles])].sort();
+    if (unresolved.size > 0) {
+        meta['unresolved_custom_properties'] = [...unresolved].sort();
+        notes.push(
+            `${unresolved.size} var() reference(s) name a custom property the snapshot's stylesheets never declare — listed under _meta.unresolved_custom_properties, which fails token fidelity until each is declared or dispositioned`,
+        );
+    }
+    if (Object.keys(unmappedProps).length > 0) meta['unmapped_custom_properties'] = unmappedProps;
+    if (guidelines.length > 0) meta['guidelines'] = guidelines;
+    if (unmapped.length > 0) {
+        meta['unmapped'] = unmapped.sort();
+        notes.push(`${unmapped.length} snapshot file(s) are not a token, contract or guideline file — listed under _meta.unmapped, not read as anything`);
+    }
+    if (sourceFile.maturity !== undefined) meta['maturity'] = sourceFile.maturity;
+    if (Object.keys(meta).length > 0) out._meta = meta;
+    return { ok: true, lane: 'claude-design', design_system: out, notes };
+}

package/src/scripts/_lib/design_system_import.ts

@@ -48,8 +48,8 @@
  * confirmation; it never writes `DESIGN.md` and never resolves a brand conflict.
  */
 
-/** The three documented input lanes. */
-export type Lane = 'native' | 'dtcg' | 'dembrandt';
+/** The three documented file lanes, plus the snapshot-directory lane (`design_system_claude_design.ts`). */
+export type Lane = 'native' | 'dtcg' | 'dembrandt' | 'claude-design';
 
 /** Provenance block — mandatory, per the contract's `source` rule. */
 export interface SourceBlock {
@@ -498,9 +498,61 @@ export function resolveAlias(raw: string, root: Record<string, unknown>, depth =
     return resolveAlias(value, root, depth + 1);
 }
 
+/** The path a whole-value DTCG alias points at, or null for a literal. */
+function aliasRef(raw: string): string | null {
+    const match = /^\{([^}]+)\}$/.exec(raw.trim());
+    return match === null ? null : (match[1] as string);
+}
+
+/**
+ * True when following `ref` revisits a token. Separates a defined-but-looping
+ * reference from one whose target does not exist, which `resolveAlias` cannot:
+ * both come back verbatim from it.
+ */
+function reachesCycle(ref: string, root: Record<string, unknown>): boolean {
+    const seen = new Set<string>();
+    let current: string | null = ref;
+    while (current !== null) {
+        if (seen.has(current)) return true;
+        seen.add(current);
+        let node: unknown = root;
+        for (const segment of current.split('.')) {
+            if (!isPlainObject(node)) return false;
+            node = node[segment];
+        }
+        if (!isTokenLeaf(node)) return false;
+        const value = leafValue(node);
+        if (value === null) return false;
+        current = aliasRef(value);
+    }
+    return false;
+}
+
+/**
+ * True when `ref` names a token leaf this file actually defines, whatever its
+ * `$value` turns out to be. `resolveAlias` cannot answer this and `reachesCycle`
+ * only answers the loop case: an alias onto a stable-DTCG object colour comes
+ * back verbatim from both, exactly like a pointer at nothing. The two need
+ * opposite actions — a missing token is an authoring error in the source file, an
+ * unmappable one is a value this adapter does not carry yet — so they are
+ * counted and reported apart.
+ */
+function aliasTargetDefined(ref: string, root: Record<string, unknown>): boolean {
+    let node: unknown = root;
+    for (const segment of ref.split('.')) {
+        if (!isPlainObject(node)) return false;
+        node = node[segment];
+    }
+    return isTokenLeaf(node);
+}
+
 function mapDtcg(input: Record<string, unknown>, source: SourceBlock): ImportOutcome {
     const notes: string[] = [];
     let unresolvedAliases = 0;
+    let unmappableAliases = 0;
+    // Token path → the path its alias names (one hop; a chain is the hops).
+    const aliasOf: Record<string, string> = {};
+    const aliasCycles: string[] = [];
     const colorsLight: Record<string, string> = {};
     const colorsDark: Record<string, string> = {};
     const radius: Record<string, string> = {};
@@ -524,9 +576,18 @@ function mapDtcg(input: Record<string, unknown>, source: SourceBlock): ImportOut
                     unmapped[next.join('.')] = '<non-scalar $value>';
                     continue;
                 }
-                const raw = resolveAlias(literal, input);
-                if (raw === literal && /^\{[^}]+\}$/.test(literal.trim())) {
-                    unresolvedAliases += 1;
+                const ref = aliasRef(literal);
+                // Decided before resolving: `resolveAlias`'s depth bound stops a
+                // two-token loop on whichever brace string it reached, not on this one.
+                const cyclic = ref !== null && reachesCycle(ref, input);
+                const raw = cyclic ? literal : resolveAlias(literal, input);
+                if (ref !== null) {
+                    aliasOf[next.join('.')] = ref;
+                    if (cyclic) aliasCycles.push(next.join('.'));
+                    else if (raw === literal) {
+                        if (aliasTargetDefined(ref, input)) unmappableAliases += 1;
+                        else unresolvedAliases += 1;
+                    }
                 }
                 const bucket = dtcgBucket(leafType(value), next);
                 const role = roleName(next);
@@ -594,12 +655,21 @@ function mapDtcg(input: Record<string, unknown>, source: SourceBlock): ImportOut
         if (Object.keys(durations).length > 0) out.motion.durations = durations;
         if (Object.keys(easings).length > 0) out.motion.easings = easings;
     }
+    const meta: Record<string, unknown> = {};
     if (Object.keys(unmapped).length > 0) {
-        out._meta = { unmapped };
+        meta['unmapped'] = unmapped;
         notes.push(
             `${Object.keys(unmapped).length} DTCG token(s) had no contract bucket — kept as observation under _meta.unmapped`,
         );
     }
+    if (Object.keys(aliasOf).length > 0) meta['alias_of'] = aliasOf;
+    if (aliasCycles.length > 0) {
+        meta['alias_cycles'] = [...aliasCycles].sort();
+        notes.push(
+            `${aliasCycles.length} DTCG alias reference(s) form a cycle — the reference is kept verbatim and listed under _meta.alias_cycles`,
+        );
+    }
+    if (Object.keys(meta).length > 0) out._meta = meta;
     if (darkByPath > 0) {
         notes.push(
             `${darkByPath} colour(s) were filed under the dark theme because a path segment is named "dark" — the format states no colour scheme, so verify these are theme values and not shades named dark`,
@@ -610,6 +680,11 @@ function mapDtcg(input: Record<string, unknown>, source: SourceBlock): ImportOut
             `${unresolvedAliases} DTCG alias reference(s) point at a token this file does not define — the reference is kept verbatim so the broken pointer is visible, not blanked`,
         );
     }
+    if (unmappableAliases > 0) {
+        notes.push(
+            `${unmappableAliases} DTCG alias reference(s) point at a token this file DOES define whose $value this adapter cannot map — the target is listed under _meta.unmapped and the reference is kept verbatim`,
+        );
+    }
     // `bundled_local: false` is a reading, not a claim about the source site:
     // DTCG carries no font-hosting information at all, so the flag records
     // "not stated" and the note says so rather than letting a default pass
@@ -977,6 +1052,9 @@ export function importDesignSystem(
                 'no lane matched — expected a native artifact (with a `source` block), a DTCG token file ({$value,$type} leaves), or an extraction output carrying at least one documented key (colors, typography, spacing, borders, shadows, motion, components, breakpoints, wcag)',
         };
     }
+    if (lane === 'claude-design') {
+        return { ok: false, lane, reason: 'claude-design lane rejected — it reads a snapshot directory, not a JSON file' };
+    }
     if (lane === 'native') return mapNative(input);
 
     const inputSource = isPlainObject(input['source']) ? readSource(input['source']) : null;

package/src/scripts/_lib/dispatch_import_closure.ts

@@ -80,13 +80,31 @@ export function relativeSpecifiers(source: string): string[] {
     return out;
 }
 
-/** Resolve a `.js` specifier from `fromRel` to the `.ts` source on disk. */
-function resolveSpecifier(root: string, fromRel: string, spec: string): string | null {
+/**
+ * Where a walk reads module sources: a checkout on disk, or a commit's objects.
+ * `read` returns `null` when no regular file sits at the repo-relative path.
+ */
+export interface ClosureTree {
+    read(rel: string): string | null;
+}
+
+/** The checkout under `root`, read through the filesystem. */
+export function checkoutTree(root: string): ClosureTree {
+    return {
+        read(rel: string): string | null {
+            const abs = path.join(root, rel);
+            return fs.existsSync(abs) && fs.statSync(abs).isFile() ? fs.readFileSync(abs, 'utf8') : null;
+        },
+    };
+}
+
+/** Resolve a `.js` specifier from `fromRel` to the `.ts` source in `tree`. */
+function resolveSpecifier(tree: ClosureTree, fromRel: string, spec: string): string | null {
     const base = path.posix.join(path.posix.dirname(fromRel), spec);
     const candidates = [base.replace(/\.js$/, '.ts'), base, `${base}.ts`, `${base}/index.ts`];
     for (const c of candidates) {
         const norm = path.posix.normalize(c);
-        if (fs.existsSync(path.join(root, norm)) && fs.statSync(path.join(root, norm)).isFile()) {
+        if (tree.read(norm) !== null) {
             return norm;
         }
     }
@@ -110,13 +128,26 @@ export function classifySource(source: string): Exclude<ModuleClass, 'concern'>
 }
 
 /**
- * Walk the closure from the dispatcher under `root`. Returns `[]` when the
- * dispatcher is absent, so a fixture tree without one yields an empty set
- * rather than an error. The dispatcher itself is not in the result — it is
- * already watched by name.
+ * Walk the closure from the dispatcher under `root`, a checkout path or a
+ * {@link ClosureTree}. Returns `[]` when the dispatcher is absent, so a fixture
+ * tree without one yields an empty set rather than an error. The dispatcher
+ * itself is not in the result — it is already watched by name.
  */
-export function dispatchImportClosure(root: string, entry: string = DISPATCHER_PATH): ClosureEntry[] {
-    if (!fs.existsSync(path.join(root, entry))) {
+export function dispatchImportClosure(
+    root: string | ClosureTree,
+    entry: string = DISPATCHER_PATH,
+): ClosureEntry[] {
+    // Each path is read at most once per walk, so the source a module was
+    // resolved by is the source it is classified and walked from.
+    const backing = typeof root === 'string' ? checkoutTree(root) : root;
+    const memo = new Map<string, string | null>();
+    const tree: ClosureTree = {
+        read(rel: string): string | null {
+            if (!memo.has(rel)) memo.set(rel, backing.read(rel));
+            return memo.get(rel) ?? null;
+        },
+    };
+    if (tree.read(entry) === null) {
         return [];
     }
     const seen = new Map<string, ModuleClass>();
@@ -128,13 +159,13 @@ export function dispatchImportClosure(root: string, entry: string = DISPATCHER_P
             continue;
         }
         visited.add(rel);
-        const source = fs.readFileSync(path.join(root, rel), 'utf8');
+        const source = tree.read(rel) ?? '';
         if (rel !== entry) {
             seen.set(rel, classifySource(source));
         }
         const isRegistry = rel === CONCERN_REGISTRY_PATH;
         for (const spec of relativeSpecifiers(source)) {
-            const target = resolveSpecifier(root, rel, spec);
+            const target = resolveSpecifier(tree, rel, spec);
             if (target === null || target === entry) {
                 continue;
             }

package/src/scripts/_lib/egress_credential_env.ts

@@ -0,0 +1,35 @@
+/**
+ * Every credential environment variable a shipped adapter or council client
+ * reads, joined to the egress rule that masks its bare value — or to
+ * `no-stable-prefix` where the value has no vendor prefix and only the
+ * assignment and entropy rows can see it. A variable missing here is a key the
+ * egress table was never asked about. Kept out of `egress_rules.ts` so the
+ * bundled engine chunk does not carry it.
+ */
+export const CREDENTIAL_ENV_ROWS: readonly { readonly env: string; readonly rule: string | 'no-stable-prefix' }[] = [
+    { env: 'ANTHROPIC_API_KEY', rule: 'anthropic-api-key' },
+    { env: 'OPENAI_API_KEY', rule: 'openai-api-key' },
+    { env: 'GEMINI_API_KEY', rule: 'google-api-key' },
+    { env: 'XAI_API_KEY', rule: 'xai-api-key' },
+    { env: 'PERPLEXITY_API_KEY', rule: 'perplexity-api-key' },
+    { env: 'GROQ_API_KEY', rule: 'groq-api-key' },
+    { env: 'HF_TOKEN', rule: 'huggingface-token' },
+    { env: 'NVIDIA_API_KEY', rule: 'nvidia-api-key' },
+    { env: 'REPLICATE_API_TOKEN', rule: 'replicate-api-token' },
+    { env: 'AIV_ACCESS_KEY', rule: 'no-stable-prefix' },
+    { env: 'AIV_SECRET_KEY', rule: 'no-stable-prefix' },
+];
+
+const CREDENTIAL_ENV_NAME = /(?:\$\{?|process\.env(?:\.|\[['"])|['"])([A-Z][A-Z0-9_]*(?:_API_KEY|_API_TOKEN|_TOKEN|_ACCESS_KEY|_SECRET_KEY|_SECRET))\b/g;
+
+/** Credential-shaped environment variable names a source reads or names as a string. */
+export function credentialEnvNames(source: string): string[] {
+    return [...new Set([...source.matchAll(CREDENTIAL_ENV_NAME)].map((m) => m[1]!))].sort();
+}
+
+/** The names with no row in {@link CREDENTIAL_ENV_ROWS}. */
+export function unmappedCredentialEnv(names: readonly string[]): string[] {
+    const known = new Set(CREDENTIAL_ENV_ROWS.map((r) => r.env));
+    return names.filter((n) => !known.has(n));
+}
+

package/src/scripts/_lib/egress_engine.ts

@@ -0,0 +1,22 @@
+/**
+ * The egress engine as one loadable unit: the rule table, the token grammar and
+ * the commit scanner's reading of the table.
+ *
+ * The dispatcher does not import this statically. `build:hook-chunks` emits it
+ * as `dist/hooks/egress_engine.chunk.cjs` beside the dispatch bundle, and
+ * `hooks/egress_engine_loader.ts` loads it only when a caller needs detection —
+ * the egress stage when its mode is not `off`, the subagent capsule when it
+ * validates an envelope. An AI council of two providers chose that shape on
+ * 2026-10-18 over a ceiling raise, as it had for the SVG rule set.
+ *
+ * `ENGINE_SCHEMA` is the handshake. A chunk whose digest matches its sidecar
+ * can still be the chunk of another release; the loader refuses one whose
+ * schema is not the one it was built against, so a stale chunk is a load
+ * failure, never stale rules. Bump it whenever an export below changes shape.
+ */
+export const ENGINE_SCHEMA = 2;
+
+export { detect, EGRESS_RULES } from './egress_rules.js';
+export { EgressRefusedError, replaceValues, TokenScope } from './egress_token.js';
+export { injectText, replaceJson, tallyText } from './egress_text.js';
+export { scanText } from './secret_detector.js';