@event4u/agent-config 14.20.0 → 14.22.0

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

package/src/scripts/code_graph/resolution_tiers.ts

@@ -0,0 +1,238 @@
+/**
+ * Resolution tiers that run BEFORE the repo-wide name lookup
+ * (road-to-a-graph-that-is-shipped 2.3).
+ *
+ * The extractor's ladder ends in a same-name table across the whole
+ * repository. That rung is a guess and is labelled one — `INFERRED`, via
+ * `name-lookup`. Two configuration files in a normal project state the answer
+ * outright, and reading them turns a guess into a fact:
+ *
+ * · `tsconfig.json` `compilerOptions.paths` — `@shared/x` IS `src/shared/x`,
+ *   because the project says so. Without this tier the specifier is non-relative,
+ *   so `resolveSpecifier` returns null and the import binds to `external:@shared/x`
+ *   — a real module, correctly named, and the wrong one.
+ * · `composer.json` `autoload.psr-4` — `App\Services\Mailer` IS
+ *   `app/Services/Mailer.php`. Without this tier a PHP `use` is matched by BASE
+ *   NAME with the namespace discarded, so two classes called `Mailer` in
+ *   different namespaces are indistinguishable.
+ *
+ * Both are DECLARED mappings, so an edge resolved through one is EXTRACTED, not
+ * INFERRED: the project's own config is as much a syntactic fact as an import
+ * specifier is.
+ *
+ * Deterministic and IO-free at resolution time — the configs are read once by
+ * the caller and passed in, so `buildGraph` stays pure and identical source
+ * plus identical config yields identical bytes.
+ */
+import type { ResolvedVia } from './types.js';
+
+/** Extensions a TS/JS alias target may carry, in resolution order. */
+const ALIAS_EXTS = ['.ts', '.tsx', '.mts', '.cts', '.js', '.jsx', '.mjs', '.cjs'] as const;
+
+export interface AliasRule {
+    /** The pattern's literal prefix, e.g. `@shared/` for `@shared/*`. */
+    prefix: string;
+    /** Whether the pattern ended in `*` (a prefix rule) or was exact. */
+    wildcard: boolean;
+    /** Repo-relative substitution targets, already joined with `baseUrl`. */
+    targets: string[];
+}
+
+export interface Psr4Rule {
+    /** Namespace prefix WITH its trailing separator, e.g. `App\\`. */
+    prefix: string;
+    /** Repo-relative directories, with a trailing slash. */
+    dirs: string[];
+}
+
+export interface ResolutionConfig {
+    aliases: AliasRule[];
+    psr4: Psr4Rule[];
+}
+
+export const EMPTY_RESOLUTION_CONFIG: ResolutionConfig = { aliases: [], psr4: [] };
+
+/**
+ * Parse JSON that may carry comments and trailing commas.
+ *
+ * `tsconfig.json` is JSONC by convention and this repository's own uses `//`
+ * comments, so `JSON.parse` on it throws. Returning null rather than throwing
+ * is deliberate: an unparseable config must degrade to "no tiers", never break
+ * a build. Strings are walked rather than regex-stripped so a `//` inside a
+ * path value survives.
+ */
+export function parseJsonc(text: string): unknown | null {
+    let out = '';
+    let inString = false;
+    let escaped = false;
+    let i = 0;
+    while (i < text.length) {
+        const ch = text[i] as string;
+        if (inString) {
+            out += ch;
+            if (escaped) escaped = false;
+            else if (ch === '\\') escaped = true;
+            else if (ch === '"') inString = false;
+            i += 1;
+            continue;
+        }
+        if (ch === '"') {
+            inString = true;
+            out += ch;
+            i += 1;
+            continue;
+        }
+        if (ch === '/' && text[i + 1] === '/') {
+            while (i < text.length && text[i] !== '\n') i += 1;
+            continue;
+        }
+        if (ch === '/' && text[i + 1] === '*') {
+            i += 2;
+            while (i < text.length && !(text[i] === '*' && text[i + 1] === '/')) i += 1;
+            i += 2;
+            continue;
+        }
+        out += ch;
+        i += 1;
+    }
+    // Trailing commas before a closing brace/bracket.
+    out = out.replace(/,(\s*[}\]])/g, '$1');
+    try {
+        return JSON.parse(out) as unknown;
+    } catch {
+        return null;
+    }
+}
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+/** Normalise a repo-relative path fragment: no leading `./`, no trailing `/`. */
+function normalizeFragment(p: string): string {
+    return p.replace(/^\.\//, '').replace(/\/+$/, '');
+}
+
+/**
+ * Build the alias tier from a parsed `tsconfig.json`.
+ *
+ * `baseUrl` is resolved relative to the tsconfig's own directory, which for a
+ * root tsconfig is the repo root — so `baseUrl: "./src"` plus `"@shared/*":
+ * ["shared/*"]` yields the repo-relative prefix `src/shared/`.
+ */
+export function aliasRulesFrom(tsconfig: unknown): AliasRule[] {
+    if (!isRecord(tsconfig)) return [];
+    const co = tsconfig['compilerOptions'];
+    if (!isRecord(co)) return [];
+    const paths = co['paths'];
+    if (!isRecord(paths)) return [];
+    const baseUrl = typeof co['baseUrl'] === 'string' ? normalizeFragment(co['baseUrl']) : '';
+    const rules: AliasRule[] = [];
+    for (const [pattern, valueRaw] of Object.entries(paths)) {
+        if (!Array.isArray(valueRaw)) continue;
+        const wildcard = pattern.endsWith('*');
+        const prefix = wildcard ? pattern.slice(0, -1) : pattern;
+        const targets: string[] = [];
+        for (const v of valueRaw) {
+            if (typeof v !== 'string') continue;
+            const tgt = wildcard ? (v.endsWith('*') ? v.slice(0, -1) : v) : v;
+            const joined = baseUrl ? `${baseUrl}/${normalizeFragment(tgt)}` : normalizeFragment(tgt);
+            targets.push(joined.replace(/\/+$/, ''));
+        }
+        if (targets.length) rules.push({ prefix, wildcard, targets });
+    }
+    // Longest prefix first: `@shared/deep/` must beat `@shared/` when both are
+    // declared, which is TypeScript's own rule and not a preference.
+    rules.sort((a, b) => b.prefix.length - a.prefix.length);
+    return rules;
+}
+
+/** Build the PSR-4 tier from a parsed `composer.json`. */
+export function psr4RulesFrom(composer: unknown): Psr4Rule[] {
+    if (!isRecord(composer)) return [];
+    const rules: Psr4Rule[] = [];
+    for (const key of ['autoload', 'autoload-dev']) {
+        const block = composer[key];
+        if (!isRecord(block)) continue;
+        const psr4 = block['psr-4'];
+        if (!isRecord(psr4)) continue;
+        for (const [ns, valueRaw] of Object.entries(psr4)) {
+            const dirsRaw = Array.isArray(valueRaw) ? valueRaw : [valueRaw];
+            const dirs = dirsRaw
+                .filter((d): d is string => typeof d === 'string')
+                .map((d) => {
+                    const n = normalizeFragment(d);
+                    return n === '' ? '' : `${n}/`;
+                });
+            if (dirs.length) rules.push({ prefix: ns, dirs });
+        }
+    }
+    // Longest namespace first — PSR-4's own most-specific-wins rule.
+    rules.sort((a, b) => b.prefix.length - a.prefix.length);
+    return rules;
+}
+
+function firstExisting(candidate: string, fileIds: ReadonlySet<string>): string | null {
+    if (fileIds.has(candidate)) return candidate;
+    // TS source imports `@shared/mailer.js` and the file on disk is
+    // `mailer.ts`, so the RUNTIME extension is stripped before the candidate
+    // list is tried — the same normalisation `resolveSpecifier` does for a
+    // relative specifier. Without it every alias in an ESM-style codebase
+    // misses, which is most of them.
+    const stem = candidate.replace(/\.(js|jsx|mjs|cjs)$/, '');
+    for (const e of ALIAS_EXTS) if (fileIds.has(stem + e)) return stem + e;
+    for (const e of ALIAS_EXTS) if (fileIds.has(`${candidate}/index${e}`)) return `${candidate}/index${e}`;
+    return null;
+}
+
+/**
+ * Resolve a non-relative TS/JS specifier through the alias tier.
+ *
+ * Returns null when no rule matches or the mapped file is not in the graph —
+ * an alias pointing outside the built root is not a hit, and claiming it as one
+ * would be worse than the `external:` binding it replaces.
+ */
+export function resolveAlias(spec: string, config: ResolutionConfig, fileIds: ReadonlySet<string>): string | null {
+    for (const rule of config.aliases) {
+        if (rule.wildcard) {
+            if (!spec.startsWith(rule.prefix)) continue;
+            const rest = spec.slice(rule.prefix.length);
+            for (const t of rule.targets) {
+                const hit = firstExisting(rest ? `${t}/${rest}` : t, fileIds);
+                if (hit) return hit;
+            }
+        } else {
+            if (spec !== rule.prefix) continue;
+            for (const t of rule.targets) {
+                const hit = firstExisting(t, fileIds);
+                if (hit) return hit;
+            }
+        }
+    }
+    return null;
+}
+
+/**
+ * Resolve a fully-qualified PHP class name through the PSR-4 tier.
+ *
+ * `App\Services\Mailer` under `{"App\\": "app/"}` becomes
+ * `app/Services/Mailer.php`. A leading backslash is tolerated because `use
+ * \App\X` is legal and means the same thing.
+ */
+export function resolvePsr4(fqcn: string, config: ResolutionConfig, fileIds: ReadonlySet<string>): string | null {
+    const name = fqcn.replace(/^\\+/, '');
+    for (const rule of config.psr4) {
+        if (!name.startsWith(rule.prefix)) continue;
+        const rest = name.slice(rule.prefix.length).replace(/\\/g, '/');
+        if (!rest) continue;
+        for (const d of rule.dirs) {
+            const candidate = `${d}${rest}.php`;
+            if (fileIds.has(candidate)) return candidate;
+        }
+    }
+    return null;
+}
+
+/** The `resolved_via` value each tier stamps on the edges it produces. */
+export const ALIAS_VIA: ResolvedVia = 'path-alias';
+export const PSR4_VIA: ResolvedVia = 'psr4';

package/src/scripts/code_graph/sqlite_store.ts

@@ -32,8 +32,32 @@ import {
 } from '../_lib/sqlite_guard.js';
 import type { CodeEdge, CodeGraph, CodeNode } from './types.js';
 
-/** Bump on ANY table/column change — a mismatch sends readers to the JSON. */
-export const GRAPH_STORE_VERSION = 1;
+/**
+ * Bump on ANY table/column change — a mismatch sends readers to the JSON.
+ *
+ * 1 → 2 (2.1): `edges` gained `resolved_via` and `provider`; `nodes` gained
+ * indexes on `label` and `source_file`; `meta` gained `node_count` /
+ * `edge_count`. A v1 twin has none of them, and the indexed read path below
+ * would silently answer from missing columns.
+ *
+ * 2 → 3 (2.2): those two columns are now REQUIRED on every edge. A v2 twin has
+ * the columns but may have written them NULL, from a graph built before the
+ * fields existed — which reads back as a valid edge carrying a fabricated
+ * mechanism. Refusing it costs nothing, because the twin is derived and the
+ * next build re-emits it.
+ */
+export const GRAPH_STORE_VERSION = 3;
+
+/**
+ * Edge count at or above which the indexed read path replaces the blob path.
+ *
+ * A DECLARED threshold, not a measured crossover — nothing establishes that
+ * 50k is where the two paths actually cross. Below it, building the in-memory
+ * Maps is cheap enough that the extra SQL round-trips per hop are not worth
+ * paying; above it, `JSON.parse` plus two `Map`s over every edge is the
+ * dominant cost and it is paid before the first question is answered.
+ */
+export const INDEXED_READ_MIN_EDGES = 50_000;
 
 /** Derived twin path for a JSON cache path.
  * cache-invalidation: versioned via PRAGMA user_version (GRAPH_STORE_VERSION), not the filename. */
@@ -70,15 +94,25 @@ export function emitSqliteTwin(graph: CodeGraph, serialized: string, jsonPath: s
             db.exec(
                 'CREATE TABLE meta (key TEXT PRIMARY KEY, value TEXT NOT NULL);' +
                     'CREATE TABLE nodes (id TEXT PRIMARY KEY, label TEXT NOT NULL, kind TEXT, source_file TEXT, l0 INTEGER, l1 INTEGER, l2 INTEGER, l3 INTEGER);' +
-                    'CREATE TABLE edges (source TEXT NOT NULL, target TEXT NOT NULL, relation TEXT NOT NULL, confidence TEXT NOT NULL, candidates TEXT);' +
+                    'CREATE TABLE edges (source TEXT NOT NULL, target TEXT NOT NULL, relation TEXT NOT NULL, confidence TEXT NOT NULL, candidates TEXT, ambiguity_reason TEXT, resolved_via TEXT, provider TEXT);' +
                     'CREATE INDEX edges_source ON edges(source);' +
-                    'CREATE INDEX edges_target ON edges(target);',
+                    'CREATE INDEX edges_target ON edges(target);' +
+                    // Seed resolution and the changed-file seed set are the two
+                    // reads that would otherwise scan every node. `id` needs no
+                    // index — it is the PRIMARY KEY.
+                    'CREATE INDEX nodes_label ON nodes(label);' +
+                    'CREATE INDEX nodes_source_file ON nodes(source_file);',
             );
             const meta = db.prepare('INSERT INTO meta (key, value) VALUES (?, ?)');
             meta.run('source_checksum', graph.source_checksum);
             meta.run('json_size', String(stat.size));
             meta.run('json_mtime_ms', String(stat.mtimeMs));
             meta.run('graph_json', serialized);
+            // Counts live in meta so a reader can pick its path from one row
+            // instead of a COUNT(*) over the table it is deciding whether to
+            // read at all.
+            meta.run('node_count', String(graph.nodes.length));
+            meta.run('edge_count', String(graph.edges.length));
             const insNode = db.prepare(
                 'INSERT INTO nodes (id, label, kind, source_file, l0, l1, l2, l3) VALUES (?, ?, ?, ?, ?, ?, ?, ?)',
             );
@@ -96,10 +130,20 @@ export function emitSqliteTwin(graph: CodeGraph, serialized: string, jsonPath: s
                 );
             }
             const insEdge = db.prepare(
-                'INSERT INTO edges (source, target, relation, confidence, candidates) VALUES (?, ?, ?, ?, ?)',
+                'INSERT INTO edges (source, target, relation, confidence, candidates, ambiguity_reason, resolved_via, provider) ' +
+                    'VALUES (?, ?, ?, ?, ?, ?, ?, ?)',
             );
             for (const e of graph.edges) {
-                insEdge.run(e.source, e.target, e.relation, e.confidence, e.candidates ? JSON.stringify(e.candidates) : null);
+                insEdge.run(
+                    e.source,
+                    e.target,
+                    e.relation,
+                    e.confidence,
+                    e.candidates ? JSON.stringify(e.candidates) : null,
+                    e.ambiguity_reason ?? null,
+                    e.resolved_via,
+                    e.provider,
+                );
             }
             stampUserVersion(db, GRAPH_STORE_VERSION);
         } finally {
@@ -150,6 +194,203 @@ export function loadSerializedFromTwin(jsonPath: string): string | null {
     }
 }
 
+/**
+ * A per-node / per-edge read API over the twin — the thing this module did not
+ * export before (road-to-a-graph-that-is-shipped D7).
+ *
+ * Every export it had took a PATH and returned the whole graph: the serialized
+ * blob, or a pair of counts. So "the query path prefers SQLite" was true and
+ * bought nothing — `loadSerializedFromTwin` hands back the entire
+ * serialization, and the caller then parses it and builds a `Map` over every
+ * node and every edge. The twin was a cheaper blob transport, never an index.
+ *
+ * These reads take an id, a label, or a file, and touch only the rows that
+ * answer. Statements are prepared once per handle because a BFS calls
+ * `edgesTo` once per frontier node, and re-preparing per hop would hand back
+ * the constant factor the index just removed.
+ *
+ * The handle owns an open database and MUST be closed. Every method is safe
+ * after `close()` only in the sense that it will throw — callers hold it for
+ * the duration of one query and release it.
+ */
+export interface GraphIndex {
+    readonly nodeCount: number;
+    readonly edgeCount: number;
+    readonly sourceChecksum: string;
+    getNode(id: string): CodeNode | undefined;
+    hasNode(id: string): boolean;
+    /** Out-edges: everything `id` points at. */
+    edgesFrom(id: string): CodeEdge[];
+    /** In-edges: everything pointing at `id` — the reverse-BFS direction. */
+    edgesTo(id: string): CodeEdge[];
+    /** Exact-label resolution, served by `nodes_label`. */
+    idsByLabel(label: string, limit: number): string[];
+    /** Non-file nodes declared in any of `files` — the changed-seed lookup. */
+    idsInFiles(files: readonly string[]): string[];
+    /** Every node's id + searchable text. The ONLY whole-table read, and it
+     * exists because a BM25 fallback genuinely needs the corpus. Callers reach
+     * it only after an exact id AND an exact label both missed. */
+    lexicalCorpus(): { id: string; text: string }[];
+    close(): void;
+}
+
+interface NodeRow {
+    id: string;
+    label: string;
+    kind: string | null;
+    source_file: string | null;
+    l0: number | null;
+    l1: number | null;
+    l2: number | null;
+    l3: number | null;
+}
+
+interface EdgeRow {
+    source: string;
+    target: string;
+    relation: string;
+    confidence: string;
+    candidates: string | null;
+    ambiguity_reason: string | null;
+    resolved_via: string | null;
+    provider: string | null;
+}
+
+function toNode(r: NodeRow): CodeNode {
+    const loc = [r.l0, r.l1, r.l2, r.l3].filter((v): v is number => typeof v === 'number');
+    return {
+        id: r.id,
+        label: r.label,
+        kind: (r.kind ?? 'file') as CodeNode['kind'],
+        source_file: r.source_file ?? '',
+        source_location: loc,
+    };
+}
+
+function toEdge(r: EdgeRow): CodeEdge {
+    const e: CodeEdge = {
+        source: r.source,
+        target: r.target,
+        relation: r.relation as CodeEdge['relation'],
+        confidence: r.confidence as CodeEdge['confidence'],
+        // The SQL columns are nullable, the TypeScript fields are not. A null
+        // can only come from a twin emitted before these fields existed, which
+        // GRAPH_STORE_VERSION already refuses — so this coalesce is unreachable
+        // in a healthy tree and is written to fail READABLE rather than to
+        // fabricate: `name-lookup` is the weakest mechanism, so a mislabelled
+        // edge is under-trusted rather than over-trusted by Phase 3's filter.
+        resolved_via: (r.resolved_via ?? 'name-lookup') as CodeEdge['resolved_via'],
+        provider: (r.provider ?? 'native') as CodeEdge['provider'],
+    };
+    if (r.candidates) e.candidates = JSON.parse(r.candidates) as string[];
+    if (r.ambiguity_reason === 'receiver-unknown' || r.ambiguity_reason === 'hierarchy-unresolved') {
+        e.ambiguity_reason = r.ambiguity_reason;
+    }
+    return e;
+}
+
+/**
+ * Open the twin for INDEXED reads, or null when it cannot serve them.
+ *
+ * Null on exactly the conditions `loadSerializedFromTwin` already refuses on —
+ * absent, stale against the JSON's size/mtime, corrupt, version-mismatched, no
+ * `node:sqlite` — so the two paths agree about when the twin is trustworthy
+ * and a caller never has to ask twice.
+ */
+export function openGraphIndex(jsonPath: string): GraphIndex | null {
+    if (!isSqliteAvailableSync()) return null;
+    const twin = sqliteTwinPath(jsonPath);
+    if (!fs.existsSync(twin)) return null;
+    let stat: fs.Stats;
+    try {
+        stat = fs.statSync(jsonPath);
+    } catch {
+        return null;
+    }
+    try {
+        const { DatabaseSync } = loadSqliteSync('code_graph.sqlite_store');
+        const db = new DatabaseSync(twin, { readOnly: true });
+        try {
+            if (readUserVersion(db) !== GRAPH_STORE_VERSION) {
+                db.close();
+                return null;
+            }
+            const rows = db.prepare('SELECT key, value FROM meta').all() as { key: string; value: string }[];
+            const meta = new Map(rows.map((r) => [r.key, r.value]));
+            if (meta.get('json_size') !== String(stat.size) || meta.get('json_mtime_ms') !== String(stat.mtimeMs)) {
+                db.close();
+                return null;
+            }
+            const nodeCount = Number(meta.get('node_count') ?? NaN);
+            const edgeCount = Number(meta.get('edge_count') ?? NaN);
+            if (!Number.isFinite(nodeCount) || !Number.isFinite(edgeCount)) {
+                // A v2 twin always carries both. Missing means something wrote
+                // this file that is not this module, and guessing the counts
+                // would be worse than declining.
+                db.close();
+                return null;
+            }
+
+            const qNode = db.prepare('SELECT * FROM nodes WHERE id = ?');
+            const qFrom = db.prepare('SELECT * FROM edges WHERE source = ?');
+            const qTo = db.prepare('SELECT * FROM edges WHERE target = ?');
+            const qLabel = db.prepare('SELECT id FROM nodes WHERE label = ? LIMIT ?');
+
+            return {
+                nodeCount,
+                edgeCount,
+                sourceChecksum: meta.get('source_checksum') ?? '',
+                getNode(id) {
+                    const r = qNode.get(id) as unknown as NodeRow | undefined;
+                    return r ? toNode(r) : undefined;
+                },
+                hasNode(id) {
+                    return (qNode.get(id) as unknown as NodeRow | undefined) !== undefined;
+                },
+                edgesFrom(id) {
+                    return (qFrom.all(id) as unknown as EdgeRow[]).map(toEdge);
+                },
+                edgesTo(id) {
+                    return (qTo.all(id) as unknown as EdgeRow[]).map(toEdge);
+                },
+                idsByLabel(labelText, limit) {
+                    return (qLabel.all(labelText, limit) as { id: string }[]).map((r) => r.id);
+                },
+                idsInFiles(files) {
+                    if (files.length === 0) return [];
+                    // Chunked because SQLite caps bound parameters (999 on the
+                    // conservative default build) and a changed-file set from a
+                    // wide diff can exceed it.
+                    const out: string[] = [];
+                    const CHUNK = 400;
+                    for (let i = 0; i < files.length; i += CHUNK) {
+                        const slice = files.slice(i, i + CHUNK);
+                        const marks = slice.map(() => '?').join(',');
+                        const stmt = db.prepare(
+                            `SELECT id FROM nodes WHERE kind != 'file' AND source_file IN (${marks})`,
+                        );
+                        for (const r of stmt.all(...slice) as { id: string }[]) out.push(r.id);
+                    }
+                    return out;
+                },
+                lexicalCorpus() {
+                    return (db.prepare('SELECT id, label FROM nodes').all() as { id: string; label: string }[]).map(
+                        (r) => ({ id: r.id, text: `${r.label} ${r.id}` }),
+                    );
+                },
+                close() {
+                    db.close();
+                },
+            };
+        } catch (err) {
+            db.close();
+            throw err;
+        }
+    } catch {
+        return null;
+    }
+}
+
 /** Structured node/edge access for future in-process consumers (kept minimal:
  * the loader above guarantees byte-identical answers; these are for tooling). */
 export function twinCounts(jsonPath: string): { nodes: number; edges: number } | null {