@event4u/agent-config 14.20.0 → 14.22.0

package/src/scripts/code_graph/build.ts

@@ -16,6 +16,17 @@ import * as path from 'node:path';
 
 import { write_atomic } from '../_lib/fs_atomic.js';
 import { extractFile, type FileExtract, type RawEdge } from './extract.js';
+import {
+    ALIAS_VIA,
+    aliasRulesFrom,
+    EMPTY_RESOLUTION_CONFIG,
+    parseJsonc,
+    PSR4_VIA,
+    psr4RulesFrom,
+    type ResolutionConfig,
+    resolveAlias,
+    resolvePsr4,
+} from './resolution_tiers.js';
 import { emitSqliteTwin } from './sqlite_store.js';
 import {
     type CodeEdge,
@@ -24,6 +35,7 @@ import {
     EXPECTED_GRAMMAR_ABI,
     EXT_LANG,
     type Lang,
+    type ResolvedVia,
     SCHEMA_VERSION,
 } from './types.js';
 
@@ -145,7 +157,9 @@ function satisfies(kind: string | undefined, want: Capability): boolean {
  */
 interface FileScope {
     locals: Map<string, string[]>;
-    imports: Map<string, { target: string; exact: boolean }>;
+    /** `via` records WHICH tier produced the binding, so an edge built from it
+     * reports the mechanism instead of assuming `import-specifier`. */
+    imports: Map<string, { target: string; exact: boolean; via: ResolvedVia }>;
 }
 
 const REL_EXTS = ['.ts', '.tsx', '.mts', '.cts', '.js', '.jsx', '.mjs', '.cjs'];
@@ -199,11 +213,40 @@ function push(map: Map<string, string[]>, k: string, v: string): void {
     } else map.set(k, [v]);
 }
 
+/**
+ * Read the project's declared resolution tiers from `root` (2.3).
+ *
+ * IO lives here rather than in `buildGraph`, which stays pure so identical
+ * source plus identical config yields identical bytes. A missing or
+ * unparseable config is not an error — it degrades to no tiers, which is the
+ * behaviour every build had before this existed.
+ *
+ * `tsconfig.json` is read as JSONC: it is JSONC by convention and this
+ * repository's own carries `//` comments, so `JSON.parse` on it throws.
+ */
+export function readResolutionConfig(root: string): ResolutionConfig {
+    const read = (name: string): unknown | null => {
+        try {
+            return parseJsonc(fs.readFileSync(path.join(root, name), 'utf-8'));
+        } catch {
+            return null;
+        }
+    };
+    return {
+        aliases: aliasRulesFrom(read('tsconfig.json')),
+        psr4: psr4RulesFrom(read('composer.json')),
+    };
+}
+
 /**
  * Pure, deterministic graph build over an in-memory file set. Exposed for
  * tests (no IO). `buildFromRepo` is the IO wrapper.
  */
-export function buildGraph(files: readonly SourceFile[], extracts: readonly FileExtract[]): CodeGraph {
+export function buildGraph(
+    files: readonly SourceFile[],
+    extracts: readonly FileExtract[],
+    resolution: ResolutionConfig = EMPTY_RESOLUTION_CONFIG,
+): CodeGraph {
     const nodes = extracts.flatMap((e) => e.nodes);
     const nodeIds = new Set(nodes.map((n) => n.id));
 
@@ -277,7 +320,7 @@ export function buildGraph(files: readonly SourceFile[], extracts: readonly File
     for (const ex of extracts) {
         const locals = new Map<string, string[]>();
         for (const n of ex.nodes) if (n.kind !== 'file') push(locals, n.label, n.id);
-        const imports = new Map<string, { target: string; exact: boolean }>();
+        const imports = new Map<string, { target: string; exact: boolean; via: ResolvedVia }>();
         for (const r of ex.rawEdges) {
             if (r.relation !== 'imports') continue;
             const local = r.localName ?? r.targetName;
@@ -285,29 +328,58 @@ export function buildGraph(files: readonly SourceFile[], extracts: readonly File
             const spec = r.moduleSpecifier;
             if (spec === undefined) {
                 // PHP `use A\B\C` — a fully-qualified NAME, not a module path.
-                // Resolved by base name without checking the namespace, so the
-                // binding is a lookup, not a syntactic fact: `exact: false`.
+                //
+                // TIER 1 (2.3): composer PSR-4 maps the NAMESPACE to a
+                // directory, so the class file is named outright. That is a
+                // declared mapping, hence `exact: true` — and it is the only
+                // rung that can tell two same-named classes in different
+                // namespaces apart.
+                const fq = r.fqName ?? r.targetName;
+                const psr4File = resolvePsr4(fq, resolution, fileIds);
+                if (psr4File !== null) {
+                    const member = `${psr4File}#${r.targetName}`;
+                    imports.set(local, {
+                        target: nodeKind.has(member) ? member : psr4File,
+                        exact: true,
+                        via: PSR4_VIA,
+                    });
+                    continue;
+                }
+                // TIER 2: base name, namespace discarded. A lookup, not a
+                // syntactic fact: `exact: false`.
                 const hit =
                     sym.classByName.get(k(ex.lang, r.targetName)) ??
                     (sym.byName.get(k(ex.lang, r.targetName)) ?? []).find((id) => id.includes('#') && !id.includes('::'));
-                if (hit) imports.set(local, { target: hit, exact: false });
+                if (hit) imports.set(local, { target: hit, exact: false, via: 'name-lookup' });
                 continue;
             }
-            const file = resolveSpecifier(ex.file, spec, fileIds);
+            // TIER 0: a relative specifier — the file says where it points.
+            // TIER 1 (2.3): tsconfig `paths`. `@shared/x` IS `src/shared/x`
+            // because the project declares it, so this is a fact and not a
+            // guess. Without it the specifier is non-relative, `resolveSpecifier`
+            // returns null, and the import binds to `external:@shared/x` — a
+            // real module, correctly named, and the wrong one.
+            const relFile = resolveSpecifier(ex.file, spec, fileIds);
+            const aliasFile = relFile === null ? resolveAlias(spec, resolution, fileIds) : null;
+            const file = relFile ?? aliasFile;
             if (file === null) {
                 // Bare (`node:path`, `zod`) or relative-but-out-of-root. Either
                 // way the module is real and NAMED, and it is not this
                 // repository's same-named symbol. `import * as path from
                 // 'node:path'` ends here, which is the whole of 1.1.
                 const named = r.importKind === 'named';
-                imports.set(local, { target: named ? `external:${spec}#${r.targetName}` : `external:${spec}`, exact: true });
+                imports.set(local, {
+                    target: named ? `external:${spec}#${r.targetName}` : `external:${spec}`,
+                    exact: true,
+                    via: 'import-specifier',
+                });
                 continue;
             }
             // A namespace or default import binds the MODULE, never a
             // same-named export inside it.
             const member = `${file}#${r.targetName}`;
             const target = r.importKind === 'named' && nodeKind.has(member) ? member : file;
-            imports.set(local, { target, exact: true });
+            imports.set(local, { target, exact: true, via: aliasFile === null ? 'import-specifier' : ALIAS_VIA });
         }
         scopes.set(ex.file, { locals, imports });
     }
@@ -327,13 +399,23 @@ export function buildGraph(files: readonly SourceFile[], extracts: readonly File
         want: Capability,
         lang: Lang,
         scopeOnly = false,
-    ): { target: string; confidence: EdgeConfidence } | null => {
+    ): { target: string; confidence: EdgeConfidence; via: ResolvedVia } | null => {
         const scope = scopes.get(file) ?? emptyScope;
+        // The ladder's rungs ARE the mechanism taxonomy, so `via` is read off
+        // the branch that succeeded rather than inferred afterwards.
         for (const id of scope.locals.get(name) ?? [])
-            if (satisfies(nodeKind.get(id), want)) return { target: id, confidence: 'EXTRACTED' };
+            if (satisfies(nodeKind.get(id), want))
+                return { target: id, confidence: 'EXTRACTED', via: 'same-file' };
         const bound = scope.imports.get(name);
         if (bound && satisfies(nodeKind.get(bound.target), want))
-            return { target: bound.target, confidence: bound.exact ? 'EXTRACTED' : 'INFERRED' };
+            return {
+                target: bound.target,
+                confidence: bound.exact ? 'EXTRACTED' : 'INFERRED',
+                // The binding knows how it was made — a tsconfig alias and a
+                // PSR-4 namespace are not import specifiers and must not be
+                // reported as ones.
+                via: bound.via,
+            };
         if (scopeOnly) return null;
         const wide =
             want === 'constructible'
@@ -344,10 +426,19 @@ export function buildGraph(files: readonly SourceFile[], extracts: readonly File
         // Reached only by matching a name across the whole repository, with no
         // binding in this file to justify it. That is not a syntactic fact and
         // no longer claims to be one.
-        if (wide) return { target: wide, confidence: 'INFERRED' };
+        if (wide) return { target: wide, confidence: 'INFERRED', via: 'name-lookup' };
         return null;
     };
 
+/**
+ * The mechanism for an edge whose target did not resolve.
+ *
+ * A `symbol:` pseudo-target is the residue of a name lookup that found
+ * nothing, so `name-lookup` is what actually happened. `confidence` already
+ * carries whether it resolved; this field carries what was tried.
+ */
+    const UNRESOLVED_VIA: ResolvedVia = 'name-lookup';
+
     // Deduped the same way emitted edges are, so the count is comparable to
     // `edges.length` rather than being a raw call-site tally that reads as a
     // larger loss than the graph actually took.
@@ -372,6 +463,8 @@ export function buildGraph(files: readonly SourceFile[], extracts: readonly File
                 target: hit?.target ?? `symbol:${inh.parentName}`,
                 relation: 'inherits',
                 confidence: hit?.confidence ?? 'EXTRACTED',
+                resolved_via: hit?.via ?? UNRESOLVED_VIA,
+                provider: 'native',
             });
         }
         for (const r of ex.rawEdges) resolveRawEdge(r, ex);
@@ -386,6 +479,11 @@ export function buildGraph(files: readonly SourceFile[], extracts: readonly File
                 target: nodeIds.has(target) ? target : `symbol:${r.targetName}`,
                 relation: 'member',
                 confidence: 'EXTRACTED',
+                // A member id is DERIVED from its own source node's id, so the
+                // declaration is in the same file by construction — no lookup
+                // of any kind happens here.
+                resolved_via: nodeIds.has(target) ? 'same-file' : UNRESOLVED_VIA,
+                provider: 'native',
             });
             return;
         }
@@ -400,6 +498,8 @@ export function buildGraph(files: readonly SourceFile[], extracts: readonly File
                 target: bound?.target ?? `symbol:${r.targetName}`,
                 relation: 'imports',
                 confidence: bound ? (bound.exact ? 'EXTRACTED' : 'INFERRED') : 'EXTRACTED',
+                resolved_via: bound ? bound.via : UNRESOLVED_VIA,
+                provider: 'native',
             });
             return;
         }
@@ -416,6 +516,8 @@ export function buildGraph(files: readonly SourceFile[], extracts: readonly File
                 target: hit?.target ?? `symbol:${r.targetName}`,
                 relation: 'uses',
                 confidence: hit?.confidence ?? 'EXTRACTED',
+                resolved_via: hit?.via ?? UNRESOLVED_VIA,
+                provider: 'native',
             });
             return;
         }
@@ -433,13 +535,25 @@ export function buildGraph(files: readonly SourceFile[], extracts: readonly File
                 // EXTRACTED is a claim about a SPECIFIC in-repo node reached by
                 // name alone.
                 confidence: hit?.confidence ?? 'EXTRACTED',
+                resolved_via: hit?.via ?? UNRESOLVED_VIA,
+                provider: 'native',
             });
             return;
         }
         if (r.callStyle === 'this' || r.callStyle === 'self' || r.callStyle === 'static' || r.callStyle === 'parent') {
             const hit = r.enclosingClassId ? resolveHierMethod(r.enclosingClassId, r.targetName) : null;
             if (hit) {
-                emit({ source: r.sourceId, target: hit, relation: 'calls', confidence: 'INFERRED' });
+                emit({
+                    source: r.sourceId,
+                    target: hit,
+                    relation: 'calls',
+                    confidence: 'INFERRED',
+                    // Walked the class hierarchy, which is same-file only when
+                    // the declaring class is; the honest mechanism for a
+                    // hierarchy walk is the repo-wide method table.
+                    resolved_via: 'name-lookup',
+                    provider: 'native',
+                });
             } else {
                 // enclosing class extends an out-of-repo base → honest AMBIGUOUS
                 const cands = methodCandidates(r.targetName, ex.lang);
@@ -448,6 +562,8 @@ export function buildGraph(files: readonly SourceFile[], extracts: readonly File
                     target: ambiguousTarget(cands, r.targetName),
                     relation: 'calls',
                     confidence: 'AMBIGUOUS',
+                    resolved_via: 'dynamic',
+                    provider: 'native',
                     // The enclosing class extends a base outside this
                     // repository, so the method is not findable HERE — a
                     // different cause from a call whose receiver is unknown,
@@ -486,6 +602,8 @@ export function buildGraph(files: readonly SourceFile[], extracts: readonly File
             target: ambiguousTarget(cands, r.targetName),
             relation: 'calls',
             confidence: 'AMBIGUOUS',
+            resolved_via: 'dynamic',
+            provider: 'native',
             // Receiver type unknown: `$obj->m()` or an unresolved `C::m()`.
             // Resolving this needs type inference the extractor does not do,
             // which is exactly what 1.2 has to decide about rather than assume.
@@ -583,6 +701,11 @@ export function serializeGraph(g: CodeGraph): string {
             target: e.target,
             relation: e.relation,
             confidence: e.confidence,
+            // Unconditional, unlike the two optional fields below: these are
+            // required on every edge, so emitting them conditionally would make
+            // an absent field mean "not set" instead of being impossible.
+            resolved_via: e.resolved_via,
+            provider: e.provider,
         };
         // Ordered before `candidates` deliberately: the reason is the coarser
         // axis and a reader scanning the serialized graph sees WHY before HOW
@@ -684,7 +807,7 @@ export async function buildFromRepo(
         nextSidecar.files[f.path] = { hash, extract };
     }
 
-    const graph = buildGraph(files, extracts);
+    const graph = buildGraph(files, extracts, readResolutionConfig(root));
     const json = serializeGraph(graph);
     if (cachePath) {
         write_atomic(cachePath, json);

package/src/scripts/code_graph/cli.ts

@@ -62,6 +62,8 @@ 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';
 
 const _HERE = fileURLToPath(import.meta.url);
@@ -130,12 +132,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 +173,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 } {
@@ -205,8 +272,9 @@ function changedNodeSeeds(g: LoadedGraph, root: string, ref: string): string[] {
     } catch {
         return [];
     }
-    const set = new Set(files);
-    return g.graph.nodes.filter((n) => set.has(n.source_file) && n.kind !== 'file').map((n) => n.id);
+    // 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 {

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 };
+}