@event4u/agent-config 14.21.0 → 14.23.0

package/src/scripts/code_graph/cli.ts

@@ -28,6 +28,20 @@
  * `agents/runtime/state/code-graph-v1.json`) is local-only and disposable —
  * gitignored, rebuildable from source at any time; never a source of truth.
  *
+ *   impact    --diff <rev> [--depth N]      callers/dependents/test files
+ *                                             reachable from the changed
+ *                                             symbols over ACCEPTED edges
+ *   tests-for <symbol>                        test files importing the symbol
+ *   untested  --diff <rev>                    changed symbols no test imports
+ *   dead      [--entry-points F]              zero accepted in-edges, minus
+ *             [--accept-missing-exports]      declared entry points; REFUSES
+ *                                             when a source is unavailable
+ *
+ * The four gate verbs (3.1–3.3) each print the `resolved_via` histogram of the
+ * edges they accepted AND of the edges they refused to walk, plus the graph's
+ * three-state staleness — so a caller can tell "no callers" from "no callers I
+ * would trust", and "dead" from "dead as of a graph 40 commits behind".
+ *
  * Query subcommands (query/path/explain/affected) are added by the Phase-3
  * query tier. Deterministic, LLM-free, no network. Exit codes:
  * 0 ok · 1 not-found / validation-failed / refresh-budget-exceeded ·
@@ -49,8 +63,8 @@ import process from 'node:process';
 import { fileURLToPath } from 'node:url';
 
 import { hardenedSpawnEnv } from '../_lib/spawn_env.js';
-import { buildFromRepo, sidecarPath } from './build.js';
-import { computeVerdict, detectSources, pickSource } from './detect.js';
+import { buildFromRepo, isTestFile, sidecarPath } from './build.js';
+import { computeVerdict, detectSources, type GraphState, graphState, pickSource } from './detect.js';
 import { suggestVerb } from './intent.js';
 import {
     affected,
@@ -62,7 +76,21 @@ import {
     query,
     type QueryResult,
 } from './query.js';
+import { openGraphIndex, sqliteTwinPath } from './sqlite_store.js';
+import type { CodeGraph } from './types.js';
 import { validateGraph } from './validate.js';
+import {
+    dead,
+    type DeadResult,
+    entryPointsFromFile,
+    impact,
+    type ImpactResult,
+    repoEntryPoints,
+    testsFor,
+    type TestsForResult,
+    untested,
+    type UntestedResult,
+} from './verbs.js';
 
 const _HERE = fileURLToPath(import.meta.url);
 export const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..', '..');
@@ -130,12 +158,33 @@ async function cmdBuild(argv: string[]): Promise<number> {
         `✅  code-graph ${update ? 'updated' : 'built'} — ${fileCount} files · ${graph.nodes.length} nodes · ${graph.edges.length} edges\n` +
             `    languages: ${graph.languages.join(', ') || '(none)'} · grammar ABI ${graph.grammar_abi}\n` +
             `    edges: EXTRACTED ${c.EXTRACTED} · INFERRED ${c.INFERRED} · AMBIGUOUS ${c.AMBIGUOUS}\n` +
+            `    resolved_via: ${resolvedViaHistogram(graph)}\n` +
             (update ? `    incremental: ${reExtracted} re-extracted · ${reused} reused\n` : '') +
             (out ? `    cache: ${path.relative(REPO_ROOT, out)}\n` : ''),
     );
     return 0;
 }
 
+/**
+ * The `resolved_via` histogram, descending by count.
+ *
+ * Printed on every build because it is the number that says whether the graph
+ * is getting BETTER, and the confidence split does not: 2.3's whole target is
+ * moving edges off `name-lookup` onto a real binding, and a reader who cannot
+ * see the starting distribution cannot tell whether it moved. Only non-zero
+ * buckets appear — a row of zeroes for the four mechanisms nothing emits yet
+ * would be noise on every build.
+ */
+function resolvedViaHistogram(graph: CodeGraph): string {
+    const counts = new Map<string, number>();
+    for (const e of graph.edges) counts.set(e.resolved_via, (counts.get(e.resolved_via) ?? 0) + 1);
+    if (counts.size === 0) return '(no edges)';
+    return [...counts.entries()]
+        .sort((a, b) => b[1] - a[1] || (a[0] < b[0] ? -1 : 1))
+        .map(([via, n]) => `${via} ${n}`)
+        .join(' · ');
+}
+
 function cmdValidate(argv: string[]): number {
     const p = flag(argv, '--graph') ?? DEFAULT_CACHE;
     if (!fs.existsSync(p)) {
@@ -150,13 +199,57 @@ function cmdValidate(argv: string[]): number {
         return 1;
     }
     const r = validateGraph(parsed);
-    if (r.ok) {
-        process.stdout.write(`✅  graph schema valid: ${path.relative(REPO_ROOT, p)}\n`);
-        return 0;
+    if (!r.ok) {
+        process.stderr.write(`❌  graph schema invalid (${r.errors.length}):\n`);
+        for (const e of r.errors) process.stderr.write(`  ${e}\n`);
+        return 1;
+    }
+
+    // Twin ⇔ JSON, by checksum (road-to-a-graph-that-is-shipped 2.1).
+    //
+    // The schema check above says the JSON is well-formed. It says nothing
+    // about the derived store that now ANSWERS most queries, and since 2.1 the
+    // twin is read as an index rather than replayed as a blob — so a twin that
+    // disagreed with the JSON would produce different answers rather than a
+    // parse error. The comparison is `source_checksum`, which is the JSON's own
+    // content-addressed cache key, so agreement here means the twin was emitted
+    // from THIS graph and not merely from a graph.
+    const twinState = twinChecksumState(p, (parsed as CodeGraph).source_checksum);
+    const rel = path.relative(REPO_ROOT, p);
+    if (twinState.kind === 'mismatch') {
+        process.stderr.write(
+            `❌  SQLite twin disagrees with the canonical JSON: twin ${twinState.twin} ≠ json ${twinState.json}\n` +
+                '    The twin is derived and disposable — delete it and re-run `code-graph build`.\n' +
+                `    ${path.relative(REPO_ROOT, sqliteTwinPath(p))}\n`,
+        );
+        return 1;
+    }
+    process.stdout.write(`✅  graph schema valid: ${rel}  ·  twin: ${twinState.kind}\n`);
+    return 0;
+}
+
+/**
+ * Compare the twin's stored `source_checksum` against the canonical JSON's.
+ *
+ * `absent` covers every state in which there is nothing to disagree WITH — no
+ * twin, no `node:sqlite`, a stale or corrupt twin the reader would refuse
+ * anyway. Those are not validation failures: the JSON is canonical and a
+ * missing accelerator changes no answer. Only a twin that is present, fresh,
+ * readable AND carrying a different checksum is a real contradiction.
+ */
+function twinChecksumState(
+    jsonPath: string,
+    jsonChecksum: string,
+): { kind: 'absent' | 'match' } | { kind: 'mismatch'; twin: string; json: string } {
+    const index = openGraphIndex(jsonPath);
+    if (!index) return { kind: 'absent' };
+    try {
+        const twin = index.sourceChecksum;
+        if (twin && twin !== jsonChecksum) return { kind: 'mismatch', twin, json: jsonChecksum };
+        return { kind: 'match' };
+    } finally {
+        index.close();
     }
-    process.stderr.write(`❌  graph schema invalid (${r.errors.length}):\n`);
-    for (const e of r.errors) process.stderr.write(`  ${e}\n`);
-    return 1;
 }
 
 function resolveGraph(argv: string[]): { g: LoadedGraph; note: string } | { err: string } {
@@ -191,10 +284,18 @@ function budgetOf(argv: string[]): number {
     return Number.isFinite(b) && b > 0 ? b : 1500;
 }
 
-function changedNodeSeeds(g: LoadedGraph, root: string, ref: string): string[] {
-    let files: string[];
+/**
+ * Files changed between `ref` and `HEAD`, repo-relative.
+ *
+ * Extracted from `changedNodeSeeds` so the Phase-3 verbs seed from the same
+ * diff reading as `affected --since`. `null` distinguishes "git refused" (a bad
+ * rev, not a repository) from "nothing changed" — a verb that reports an empty
+ * impact set for a rev git could not resolve is asserting something it never
+ * measured.
+ */
+export function changedFiles(root: string, ref: string): string[] | null {
     try {
-        files = execFileSync('git', ['-C', root, 'diff', '--name-only', `${ref}..HEAD`], {
+        return execFileSync('git', ['-C', root, 'diff', '--name-only', `${ref}..HEAD`], {
             env: hardenedSpawnEnv(),
             encoding: 'utf-8',
             stdio: ['ignore', 'pipe', 'ignore'],
@@ -203,10 +304,16 @@ function changedNodeSeeds(g: LoadedGraph, root: string, ref: string): string[] {
             .map((s) => s.trim())
             .filter(Boolean);
     } catch {
-        return [];
+        return null;
     }
-    const set = new Set(files);
-    return g.graph.nodes.filter((n) => set.has(n.source_file) && n.kind !== 'file').map((n) => n.id);
+}
+
+function changedNodeSeeds(g: LoadedGraph, root: string, ref: string): string[] {
+    const files = changedFiles(root, ref);
+    if (files === null) return [];
+    // Served by the `nodes_source_file` index on the SQLite path, so a wide
+    // diff does not force the whole node table into memory to answer it.
+    return g.idsInFiles(files);
 }
 
 function cmdQuery(kind: 'query' | 'explain' | 'affected' | 'path', argv: string[]): number {
@@ -254,6 +361,213 @@ function isFlagValue(argv: string[], token: string): boolean {
     return i > 0 && (argv[i - 1] as string).startsWith('--');
 }
 
+// Phase-3 gate verbs (3.1-3.3).
+
+/** The staleness token every gate verb prints, per step 3.1–3.3's shared
+ * verify: "each prints `resolved_via` counts and the staleness state". */
+/**
+ * The staleness of the graph the verb is ACTUALLY reading.
+ *
+ * `answeredBy` is `resolveGraph`'s own picked path when it has one. Without it
+ * the two disagreed on the case `resolveRoot`'s docstring exists for: with
+ * `--root <other repo>` the verb answers from `DEFAULT_CACHE` (anchored to the
+ * package tree) while `graphState` looked under the OTHER root, so the printed
+ * staleness described a cache the answer never came from. An independent review
+ * found the `--graph` half fixed and this half open.
+ */
+function stateOf(argv: string[], answeredBy?: string): GraphState {
+    const explicit = flag(argv, '--graph');
+    return graphState(resolveRoot(argv), explicit ?? answeredBy);
+}
+
+/** The two histogram lines + the staleness line, in one place so the four
+ * verbs cannot drift apart in how they report their own filtering. */
+function renderEnvelope(r: { source: string; state: GraphState; accepted_via: string; rejected_via: string }): void {
+    process.stdout.write(`source: ${r.source}\nstaleness: ${r.state}\n`);
+    process.stdout.write(`accepted resolved_via: ${r.accepted_via}\n`);
+    process.stdout.write(`rejected resolved_via: ${r.rejected_via}\n`);
+}
+
+function renderReads(reads: readonly { path: string; lines: [number, number] | null }[]): void {
+    if (!reads.length) return;
+    process.stdout.write('minimal read set:\n');
+    for (const r of reads) process.stdout.write(`  ${r.path}${r.lines ? `:${r.lines[0]}-${r.lines[1]}` : ''}\n`);
+}
+
+/**
+ * `impact --diff <rev>` (3.1) — callers, dependents and test files reachable
+ * from the changed symbols over ACCEPTED edges, plus the producing edges and a
+ * minimal read set.
+ */
+function cmdImpact(argv: string[]): number {
+    const ref = flag(argv, '--diff');
+    if (ref === null) {
+        process.stderr.write('usage: code_graph/cli.ts impact --diff <rev> [--graph P] [--depth N]\n');
+        return 2;
+    }
+    const root = resolveRoot(argv);
+    const files = changedFiles(root, ref);
+    if (files === null) {
+        process.stderr.write(`code-graph: cannot resolve rev '${ref}' in ${root}\n`);
+        return 1;
+    }
+    const r = resolveGraph(argv);
+    if ('err' in r) {
+        process.stderr.write(`code-graph: ${r.err}\n`);
+        return 1;
+    }
+    try {
+        const depth = Number(flag(argv, '--depth'));
+        const res: ImpactResult = impact(
+            r.g,
+            files,
+            stateOf(argv, r.g.answeredBy),
+            Number.isFinite(depth) && depth > 0 ? depth : 2,
+            isTestFile,
+        );
+        renderEnvelope(res);
+        process.stdout.write(`changed files: ${files.length} · seeds: ${res.seeds.length}\n`);
+        if (res.unresolved_files.length)
+            process.stdout.write(`unresolved changed files (no node in the graph): ${res.unresolved_files.join(', ')}\n`);
+        process.stdout.write(`dependents (${res.dependents.length}):\n`);
+        for (const d of res.dependents) process.stdout.write(`  ${d}\n`);
+        process.stdout.write(`test files (${res.test_files.length}):\n`);
+        for (const t of res.test_files) process.stdout.write(`  ${t}\n`);
+        process.stdout.write(`producing edges (${res.producing_edges.length}):\n`);
+        for (const e of res.producing_edges) process.stdout.write(`  ${e}\n`);
+        renderReads(res.recommended_reads);
+        return 0;
+    } finally {
+        r.g.close();
+    }
+}
+
+/** `tests-for <symbol>` (3.2) — the test files that import the symbol. */
+function cmdTestsFor(argv: string[]): number {
+    const positional = argv.filter((a) => !a.startsWith('--') && !isFlagValue(argv, a));
+    const symbol = positional[0];
+    if (!symbol) {
+        process.stderr.write('usage: code_graph/cli.ts tests-for <symbol> [--graph P]\n');
+        return 2;
+    }
+    const r = resolveGraph(argv);
+    if ('err' in r) {
+        process.stderr.write(`code-graph: ${r.err}\n`);
+        return 1;
+    }
+    try {
+        const res: TestsForResult = testsFor(r.g, symbol, stateOf(argv, r.g.answeredBy));
+        renderEnvelope(res);
+        process.stdout.write(`seeds: ${res.seeds.join(', ') || '(none)'}\n`);
+        process.stdout.write(`tests (${res.tests.length}):\n`);
+        for (const t of res.tests) process.stdout.write(`  ${t}\n`);
+        renderReads(res.recommended_reads);
+        return 0;
+    } finally {
+        r.g.close();
+    }
+}
+
+/** `untested --diff <rev>` (3.2) — changed symbols no test file imports. */
+function cmdUntested(argv: string[]): number {
+    const ref = flag(argv, '--diff');
+    if (ref === null) {
+        process.stderr.write('usage: code_graph/cli.ts untested --diff <rev> [--graph P]\n');
+        return 2;
+    }
+    const root = resolveRoot(argv);
+    const files = changedFiles(root, ref);
+    if (files === null) {
+        process.stderr.write(`code-graph: cannot resolve rev '${ref}' in ${root}\n`);
+        return 1;
+    }
+    const r = resolveGraph(argv);
+    if ('err' in r) {
+        process.stderr.write(`code-graph: ${r.err}\n`);
+        return 1;
+    }
+    try {
+        const res: UntestedResult = untested(r.g, files, stateOf(argv, r.g.answeredBy));
+        renderEnvelope(res);
+        process.stdout.write(`changed files: ${files.length} · changed symbols: ${res.tested.length + res.untested.length}\n`);
+        if (res.unresolved_files.length)
+            process.stdout.write(`unresolved changed files (no node in the graph): ${res.unresolved_files.join(', ')}\n`);
+        process.stdout.write(`tested (${res.tested.length}) · untested (${res.untested.length}):\n`);
+        for (const u of res.untested) process.stdout.write(`  ${u}\n`);
+        renderReads(res.recommended_reads);
+        return 0;
+    } finally {
+        r.g.close();
+    }
+}
+
+/**
+ * `dead` (3.3) — symbols with zero accepted in-edges that no declared entry
+ * point names. REFUSES by default when an entry-point source is unavailable;
+ * see `verbs.ts::dead` for why that refusal is not relaxable by an options bag.
+ */
+function cmdDead(argv: string[]): number {
+    const r = resolveGraph(argv);
+    if ('err' in r) {
+        process.stderr.write(`code-graph: ${r.err}\n`);
+        return 1;
+    }
+    try {
+        const root = resolveRoot(argv);
+        const sources = repoEntryPoints(root);
+        const listFile = flag(argv, '--entry-points');
+        if (listFile !== null) {
+            if (!fs.existsSync(listFile)) {
+                process.stderr.write(`code-graph: entry-point list not found: ${listFile}\n`);
+                return 1;
+            }
+            // An operator-supplied list SUPPLIES the missing source, so the
+            // `exports` row stops being a gap rather than being ignored: the
+            // caller has stated the entry points the graph could not.
+            const supplied = entryPointsFromFile(listFile);
+            const patched = sources.map((srcRow) =>
+                srcRow.name === 'exports'
+                    ? { ...srcRow, status: 'read' as const, detail: `supplied by ${listFile}`, entries: [] }
+                    : srcRow,
+            );
+            patched.push(supplied);
+            const res: DeadResult = dead(r.g, patched, stateOf(argv, r.g.answeredBy));
+            return renderDead(res);
+        }
+        const res: DeadResult = dead(r.g, sources, stateOf(argv, r.g.answeredBy), {
+            acceptMissingExports: argv.includes('--accept-missing-exports'),
+        });
+        return renderDead(res);
+    } finally {
+        r.g.close();
+    }
+}
+
+function renderDead(res: DeadResult): number {
+    // The envelope FIRST, on both branches. It used to print only after the
+    // refusal check, so the default invocation in this repository — where
+    // `exports` is always unavailable — printed neither histogram nor the
+    // staleness line, and 3.1-3.3's shared verify ("each prints `resolved_via`
+    // counts and the staleness state") held only on the branch that answers.
+    // A reader of a refusal wants the staleness most of all: it says whether
+    // re-running after a rebuild could change anything.
+    renderEnvelope(res);
+    process.stdout.write('entry-point sources consulted:\n');
+    for (const srcRow of res.sources)
+        process.stdout.write(
+            `  ${srcRow.name.padEnd(13)} ${srcRow.status}${srcRow.detail ? ` — ${srcRow.detail}` : ''} · ${srcRow.entries.length} entr${srcRow.entries.length === 1 ? 'y' : 'ies'}\n`,
+        );
+    if (res.refusal !== null) {
+        process.stderr.write(`❌  dead refused: ${res.refusal}\n`);
+        return 1;
+    }
+    process.stdout.write(`excluded as declared entry points: ${res.excluded.length}\n`);
+    process.stdout.write(`dead (${res.dead.length}):\n`);
+    for (const d of res.dead) process.stdout.write(`  ${d}\n`);
+    renderReads(res.recommended_reads);
+    return 0;
+}
+
 function cmdDetect(argv: string[]): number {
     const root = resolveRoot(argv);
     if (flag(argv, '--format') === 'json') {
@@ -394,9 +708,14 @@ export async function main(argv: string[] = process.argv.slice(2)): Promise<numb
         if (sub === 'refresh') return cmdRefresh(argv.slice(1));
         if (sub === 'query' || sub === 'explain' || sub === 'affected' || sub === 'path')
             return cmdQuery(sub, argv.slice(1));
+        if (sub === 'impact') return cmdImpact(argv.slice(1));
+        if (sub === 'tests-for') return cmdTestsFor(argv.slice(1));
+        if (sub === 'untested') return cmdUntested(argv.slice(1));
+        if (sub === 'dead') return cmdDead(argv.slice(1));
         if (sub === 'suggest-verb') return cmdSuggestVerb(argv.slice(1));
         process.stderr.write(
-            'usage: code_graph/cli.ts <build|validate|detect|refresh|query|explain|affected|path|suggest-verb> [options]\n',
+            'usage: code_graph/cli.ts <build|validate|detect|refresh|query|explain|affected|path|' +
+                'impact|tests-for|untested|dead|suggest-verb> [options]\n',
         );
         return 2;
     } catch (e) {

package/src/scripts/code_graph/detect.ts

@@ -184,3 +184,41 @@ export function computeVerdict(root: string, nativeCache: string): VerdictJSON {
         sources,
     };
 }
+
+/** Cache path a repository root's native graph lives at, repo-relative. */
+export const NATIVE_CACHE_REL = path.join('agents', 'runtime', 'state', 'code-graph-v1.json');
+
+/**
+ * The three-state staleness token every consumer of the graph reports.
+ *
+ * Lives HERE rather than in the PreToolUse hook that first needed it
+ * (`hooks/code_graph_context_hook.ts`, step 1.2). Phase 3's verbs must each
+ * print the staleness state, and an engine module importing a hook module to
+ * learn it would invert the dependency direction D9 measures — the hook imports
+ * the engine, never the other way round. The hook re-exports this so its own
+ * consumers are unaffected.
+ */
+export type GraphState = 'absent' | 'fresh' | `behind:${number}`;
+
+/**
+ * Resolve the graph's state for `root`.
+ *
+ * `absent` means no source at all — the silent case. A picked source whose
+ * staleness is UNKNOWN reads as `fresh`, mirroring {@link computeVerdict}'s own
+ * `picked.stale ? STALE : FRESH`: unknown is not treated as stale, because
+ * inventing a commit count would be worse than reporting none.
+ *
+ * `nativeCache` overrides where the native graph is looked for. It exists
+ * because a verb invoked with an explicit `--graph <path>` would otherwise
+ * report `absent` while answering from that very file — the state of a cache
+ * nobody asked about. Passing the graph the verb is actually reading makes the
+ * printed staleness a statement about the answer rather than about a
+ * convention.
+ */
+export function graphState(root: string, nativeCache?: string): GraphState {
+    const picked = pickSource(detectSources(root, nativeCache ?? path.join(root, NATIVE_CACHE_REL)));
+    if (!picked) return 'absent';
+    if (picked.stale !== true) return 'fresh';
+    const behind = picked.commits_behind;
+    return `behind:${typeof behind === 'number' ? behind : 0}`;
+}

package/src/scripts/code_graph/extract.ts

@@ -67,6 +67,16 @@ export interface RawEdge {
      * searched for the remote one.
      */
     localName?: string;
+    /**
+     * `imports` only, PHP: the FULLY-QUALIFIED name as written (`App\\Svc\\Mailer`).
+     *
+     * `targetName` carries only the base name, because that is all the
+     * repo-wide lookup could use. Composer PSR-4 maps the NAMESPACE to a
+     * directory, so it needs the part `baseName()` discards — the same shape as
+     * `moduleSpecifier` for TS: the one piece of evidence that says where the
+     * name comes from, and it is right there in the source text.
+     */
+    fqName?: string;
 }
 
 export interface FileExtract {
@@ -137,6 +147,7 @@ function extractPhp(root: TsNode, file: string, out: FileExtract): void {
                             relation: 'imports',
                             targetName: baseName(nameNode.text),
                             confidenceHint: 'EXTRACTED',
+                            fqName: nameNode.text,
                         });
                     }
                 }

package/src/scripts/code_graph/grammar_probe.ts

@@ -0,0 +1,43 @@
+#!/usr/bin/env tsx
+/**
+ * Report what the PRODUCTION loader makes of each grammar file given as an
+ * argument, as one line of JSON on stdout.
+ *
+ * A separate process because `check_pack_size.main` is synchronous while
+ * `Language.load` is not, and because keeping the probe out of the gate's own
+ * process means the gate cannot accidentally hold a loaded grammar's emscripten
+ * heap for the rest of its run.
+ *
+ * Never throws for a bad file: an unreadable or invalid grammar comes back as
+ * `{ ok: false, error }`, because "the loader refused this" is the ANSWER the
+ * eligibility predicate needs, not a crash it has to interpret.
+ */
+import process from 'node:process';
+
+import { probeGrammarFile } from './loader.js';
+
+interface ProbeRow {
+    path: string;
+    ok: boolean;
+    abi?: number;
+    grammar_id?: string;
+    error?: string;
+}
+
+async function main(): Promise<number> {
+    const rows: ProbeRow[] = [];
+    for (const p of process.argv.slice(2)) {
+        try {
+            const r = await probeGrammarFile(p);
+            rows.push({ path: p, ok: true, abi: r.abi, grammar_id: r.grammar_id });
+        } catch (e) {
+            rows.push({ path: p, ok: false, error: (e as Error).message });
+        }
+    }
+    process.stdout.write(`${JSON.stringify(rows)}\n`);
+    return 0;
+}
+
+void main().then((c) => {
+    process.exitCode = c;
+});

package/src/scripts/code_graph/loader.ts

@@ -2,19 +2,29 @@
  * WASM tree-sitter loader for the code-graph engine.
  *
  * Pinned pair (ABI-verified 2026-07-23): `web-tree-sitter@0.24.7` +
- * `tree-sitter-wasms@0.1.13` → grammar ABI 14. The ABI smoke test lives in
- * `tests/scripts/code_graph.test.ts`; it runs in this repo because the pair is
- * a devDependency. Consumers install neither (see `INSTALL_HINT` below). No
- * network, no node-gyp — grammars load from `node_modules` via the resolved
- * path.
+ * grammar ABI 14. The ABI smoke test lives in
+ * `tests/scripts/code_graph.test.ts`.
+ *
+ * SHIPPED TO CONSUMERS (ADR-259, amended 2026-09-07). `web-tree-sitter` is a
+ * runtime `dependency`, and the three loadable grammars are vendored at
+ * `src/vendor/grammars/` and listed in `package.json` `files`. So a consumer
+ * install resolves both halves with no manual step. `tree-sitter-wasms` stays a
+ * devDependency — it is the source the vendored copies are refreshed from, and
+ * the fallback below keeps this repo's own dev flow (and any consumer holding
+ * the full 36-grammar pack) working unchanged.
+ *
+ * No network, no node-gyp, and no runtime grammar download — Kill register K1:
+ * both lookups below are filesystem reads of already-installed bytes.
  *
  * web-tree-sitter 0.24.x is CJS with a single default export (the Parser
  * class) and the classic `Parser.Language.load()` API; we reach it through
  * `createRequire` so this ESM module stays portable under the repo's tsx
  * runner.
  */
+import * as fs from 'node:fs';
 import { createRequire } from 'node:module';
 import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
 
 import { EXPECTED_GRAMMAR_ABI, GRAMMAR_WASM, type Lang } from './types.js';
 
@@ -53,22 +63,35 @@ interface ParserStatic {
 }
 
 /**
- * The parser pair is a devDependency, not a runtime one: this repo's tests still
- * exercise the loader, while a consumer install resolves neither. The engine is
- * permanently `enabled: false` (measured recall 0.365 vs grep 0.797), so
- * shipping ~51 MB of WASM to every consumer for a path none of them can reach
- * was pure install cost. A consumer re-enabling the engine installs the
- * ABI-locked pair themselves — this message carries the pin, because
- * `check_dependency_floors` only scans the `dependencies` block.
+ * Reached only when BOTH grammar sources are missing — the vendored set that
+ * ships in the tarball and the devDependency pack. That is a broken or
+ * partially-extracted install, not the ordinary consumer state, so the message
+ * says how to repair rather than how to opt in.
+ *
+ * It still carries the exact pin because the pair is ABI-coupled and
+ * `check_dependency_floors` reads only version ranges, never this string.
  */
 const INSTALL_HINT =
-    'the code-graph engine needs its parser pair, which this package no longer ships to consumers ' +
-    '(the engine is disabled by a recorded null result). Install the ABI-locked pair:\n' +
+    'the code-graph engine could not find its grammars. They ship with this package at ' +
+    '`src/vendor/grammars/`, so this usually means an incomplete install — reinstall the ' +
+    'package first. To supply them manually, install the ABI-locked pack:\n' +
     '  npm i web-tree-sitter@0.24.7 tree-sitter-wasms@0.1.13\n' +
     'Both versions are exact on purpose — the pair is ABI-coupled (grammar ABI 14) ' +
     'and must move together.';
 
+/**
+ * Directory holding the grammars that ship inside the package.
+ *
+ * `../../..` from `src/scripts/code_graph/` is the package root — the same
+ * walk `_lib/agent_settings.ts` uses from `src/scripts/_lib/`. A wrong answer
+ * here is not a failure: `grammarWasmPath` only uses this path when the file is
+ * actually present, and otherwise falls through to the devDependency pack,
+ * which is exactly today's behaviour.
+ */
+const VENDORED_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', 'vendor', 'grammars');
+
 let _wasmDir: string | null = null;
+/** The devDependency grammar pack — the fallback source, and this repo's own. */
 function wasmDir(): string {
     if (_wasmDir === null) {
         let pkgJson: string;
@@ -86,7 +109,18 @@ let _initialized = false;
 const _langCache = new Map<Lang, TsLanguage>();
 const _parserCache = new Map<Lang, TsParser>();
 
+/**
+ * Absolute path to a grammar, vendored set first.
+ *
+ * Order is load-bearing: the vendored set is what a consumer actually has, and
+ * it is ABI-pinned by the same change that wrote it. The devDependency pack is
+ * second so this repo keeps working when `src/vendor/grammars/` has not been
+ * refreshed, and so a consumer holding the full 36-grammar pack can reach a
+ * grammar the vendored three do not cover.
+ */
 export function grammarWasmPath(lang: Lang): string {
+    const vendored = path.join(VENDORED_DIR, GRAMMAR_WASM[lang]);
+    if (fs.existsSync(vendored)) return vendored;
     return path.join(wasmDir(), GRAMMAR_WASM[lang]);
 }
 
@@ -150,3 +184,43 @@ export async function getParser(lang: Lang): Promise<TsParser> {
 export function nodeHasError(n: TsNode): boolean {
     return typeof n.hasError === 'function' ? n.hasError() : n.hasError;
 }
+
+/**
+ * Load an ARBITRARY grammar file through the production loader and report what
+ * it actually is.
+ *
+ * Exists for `check_pack_size`'s binary-eligibility predicate, and the "through
+ * the production loader" part is the whole point: the gate must not re-implement
+ * grammar loading, because a second implementation could accept bytes the engine
+ * rejects — which is precisely the gap that would let a broken grammar ship
+ * while the gate reported it valid. Same `_Parser()` instance, same
+ * `Language.load`, same ABI reading as `loadLanguage`.
+ *
+ * `grammar_id` comes from the module's exported `tree_sitter_<id>` symbol rather
+ * than from the `Language` object, because web-tree-sitter 0.24's `Language`
+ * exposes `version` and no name. `WebAssembly.Module.exports` is the runtime's
+ * own parser, so the id is read rather than guessed.
+ *
+ * Throws on anything it cannot establish — a caller that wants a verdict rather
+ * than an exception should catch. Never silently returns a partial answer.
+ */
+export async function probeGrammarFile(wasmPath: string): Promise<{ abi: number; grammar_id: string }> {
+    const bytes = fs.readFileSync(wasmPath);
+    const mod = new WebAssembly.Module(bytes);
+    // A grammar module exports `tree_sitter_<id>` plus, usually, a family of
+    // `tree_sitter_<id>_external_scanner_*` helpers — measured: 6 such exports
+    // on php, 7 on typescript and javascript. The language id is the one
+    // WITHOUT the scanner suffix, and filtering for it leaves exactly one.
+    const ids = WebAssembly.Module.exports(mod)
+        .map((e) => e.name)
+        .filter((n) => n.startsWith('tree_sitter_') && !n.includes('_external_scanner_'))
+        .map((n) => n.slice('tree_sitter_'.length));
+    if (ids.length !== 1) {
+        throw new Error(
+            `grammar probe: expected exactly one tree_sitter_* export in ${wasmPath}, found ${String(ids.length)}`,
+        );
+    }
+    await _init();
+    const language = await _Parser().Language.load(wasmPath);
+    return { abi: language.version, grammar_id: ids[0] as string };
+}