@event4u/agent-config 14.21.0 → 14.22.0

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

package/src/scripts/code_graph/query.ts

@@ -9,22 +9,114 @@ import * as fs from 'node:fs';
 
 import { LexicalIndex, tokenize } from '../_lib/lexical_index.js';
 import { sanitizeLabel } from './sanitize.js';
-import { emitSqliteTwin, loadSerializedFromTwin } from './sqlite_store.js';
-import type { CodeEdge, CodeGraph } from './types.js';
+import {
+    emitSqliteTwin,
+    type GraphIndex,
+    INDEXED_READ_MIN_EDGES,
+    loadSerializedFromTwin,
+    openGraphIndex,
+} from './sqlite_store.js';
+import type { CodeEdge, CodeGraph, CodeNode } from './types.js';
 import { validateGraph } from './validate.js';
 
 const APPROX_CHARS_PER_TOKEN = 4;
 
+/**
+ * The node/adjacency reads every verb performs.
+ *
+ * Declared as interfaces rather than `Map` so one set of verbs runs over two
+ * stores. `Map` satisfies both structurally, so the in-memory path is unchanged
+ * and needed no edits; the SQLite path supplies objects with the same two
+ * methods that hit an index instead of a heap.
+ */
+export interface NodeLookup {
+    get(id: string): CodeNode | undefined;
+    has(id: string): boolean;
+}
+export interface AdjacencyLookup {
+    get(id: string): CodeEdge[] | undefined;
+}
+
 export interface LoadedGraph {
-    graph: CodeGraph;
+    /**
+     * The whole deserialized graph — `null` on the indexed path, where not
+     * materializing it is the entire point. Nothing in this module reads it;
+     * the two callers that used to (`resolveSeedsTiered`, the CLI's
+     * changed-file seeds) go through `idsByLabel` / `idsInFiles` instead, which
+     * answer the same questions from an index.
+     */
+    graph: CodeGraph | null;
     source: string; // attribution path
-    byId: Map<string, CodeGraph['nodes'][number]>;
-    out: Map<string, CodeEdge[]>;
-    in: Map<string, CodeEdge[]>;
-    lex: LexicalIndex;
+    byId: NodeLookup;
+    out: AdjacencyLookup;
+    in: AdjacencyLookup;
+    /** Exact-label resolution. */
+    idsByLabel(label: string, limit: number): string[];
+    /** Non-file nodes declared in any of `files`. */
+    idsInFiles(files: readonly string[]): string[];
+    /**
+     * BM25 fallback corpus, LAZY.
+     *
+     * A function rather than a field because on the indexed path building it
+     * reads every node — the one whole-table scan left — and a seed that
+     * resolves by exact id or exact label must never pay for it. On the
+     * in-memory path the corpus is already in hand and this just returns it.
+     */
+    lex(): LexicalIndex;
+    /** Release any handle the store holds. No-op for the in-memory path. */
+    close(): void;
+}
+
+/**
+ * A `LoadedGraph` backed by the SQLite index — no `JSON.parse`, no whole-graph
+ * `Map`.
+ *
+ * The adjacency lookups are per-call SQL against `edges_source` / `edges_target`
+ * rather than a materialized map, which is the difference the threshold buys: a
+ * 2-hop `affected` touches the rows for its frontier, not every edge in the
+ * repository. Node reads are memoized per handle because a BFS asks for the
+ * same label repeatedly while rendering edge lines, and that repetition is
+ * cheap to remove and expensive to leave.
+ */
+function indexBackedGraph(index: GraphIndex, source: string): LoadedGraph {
+    const nodeCache = new Map<string, CodeNode | undefined>();
+    const readNode = (id: string): CodeNode | undefined => {
+        if (nodeCache.has(id)) return nodeCache.get(id);
+        const n = index.getNode(id);
+        nodeCache.set(id, n);
+        return n;
+    };
+    let lexical: LexicalIndex | null = null;
+    return {
+        graph: null,
+        source,
+        byId: { get: readNode, has: (id) => readNode(id) !== undefined },
+        out: { get: (id) => index.edgesFrom(id) },
+        in: { get: (id) => index.edgesTo(id) },
+        idsByLabel: (labelText, limit) => index.idsByLabel(labelText, limit),
+        idsInFiles: (files) => index.idsInFiles(files),
+        lex: () => {
+            lexical ??= new LexicalIndex(index.lexicalCorpus());
+            return lexical;
+        },
+        close: () => index.close(),
+    };
 }
 
 export function loadGraph(graphPath: string, source = graphPath): LoadedGraph {
+    // Above the threshold, read through the INDEX: the twin's rows answer
+    // per-node and per-edge questions directly, so neither `JSON.parse` nor the
+    // two whole-graph `Map`s below ever run. This is the D6 repair — the twin
+    // used to be preferred and still returned the entire serialization, which
+    // made it a cheaper blob transport rather than an index.
+    const index = openGraphIndex(graphPath);
+    if (index) {
+        if (index.edgeCount >= INDEXED_READ_MIN_EDGES) return indexBackedGraph(index, source);
+        // Small graph: the in-memory path is cheaper. Release the handle rather
+        // than leaking a database for the life of the process.
+        index.close();
+    }
+
     // Prefer the derived SQLite twin (ADR-129): checksum/stat-verified against
     // the canonical JSON, byte-identical content, ~1/90 the load cost at
     // consumer scale. Fallback = parse the JSON — and best-effort re-emit the
@@ -51,7 +143,23 @@ export function loadGraph(graphPath: string, source = graphPath): LoadedGraph {
         add(inM, e.target, e);
     }
     const lex = new LexicalIndex(graph.nodes.map((n) => ({ id: n.id, text: `${n.label} ${n.id}` })));
-    return { graph, source, byId, out: outM, in: inM, lex };
+    return {
+        graph,
+        source,
+        byId,
+        out: outM,
+        in: inM,
+        idsByLabel: (labelText, limit) =>
+            graph.nodes.filter((n) => n.label === labelText).slice(0, limit).map((n) => n.id),
+        idsInFiles: (files) => {
+            const set = new Set(files);
+            return graph.nodes.filter((n) => set.has(n.source_file) && n.kind !== 'file').map((n) => n.id);
+        },
+        lex: () => lex,
+        close: () => {
+            /* nothing held */
+        },
+    };
 }
 
 interface SeedResolution {
@@ -64,9 +172,11 @@ interface SeedResolution {
 /** Resolve a free-text seed to node ids: exact id → exact label → BM25. */
 function resolveSeedsTiered(g: LoadedGraph, seed: string, limit = 5): SeedResolution {
     if (g.byId.has(seed)) return { ids: [seed], weak: false };
-    const exactLabel = g.graph.nodes.filter((n) => n.label === seed).map((n) => n.id);
-    if (exactLabel.length) return { ids: exactLabel.slice(0, limit), weak: false };
-    const ranked = g.lex.rank(tokenize(seed)).filter((r) => r.score > 0);
+    const exactLabel = g.idsByLabel(seed, limit);
+    if (exactLabel.length) return { ids: exactLabel, weak: false };
+    // Only here does the BM25 corpus get built — the one whole-table read on
+    // the indexed path, and unreachable when the seed resolved exactly.
+    const ranked = g.lex().rank(tokenize(seed)).filter((r) => r.score > 0);
     return { ids: ranked.slice(0, limit).map((r) => r.id), weak: true };
 }