graph-indexer 2.0.0 → 2.1.0

package/engine/memory.mjs

@@ -10,7 +10,9 @@ import {
     tokenize, okapiIdf, bm25Score, fuseAndRank, buildLexicalDocument, embeddingKeyFor,
     SUMMARY_VEC_SUFFIX, LEXICAL_FUSION_CAP, VECTOR_SCAN_RAW_N, finalizeVectorCandidates,
     isNaturalLanguageQuery, WINDOW_VEC_SUFFIX, EMBEDDING_MAX_WINDOWS, baseEmbeddingKey,
+    scoreSparseExpanded,
 } from '../search-core.mjs';
+import { expandSparseQuery } from '../search-sparse.mjs';
 import {
     HierarchicalNSW, HNSW_THRESHOLD, LAZY_VEC_THRESHOLD, SKETCH_THRESHOLD,
     writeEmbeddingBinary, scanEmbeddingBinary, updateVectorSketch, searchVectorSketch,
@@ -70,6 +72,72 @@ export class MemoryGraphIndex {
 
         this.rrfK = rrfK;
         this._saveTimer = null;
+
+        // ── A4: persistent resolved symbol graph (opt-in; null when not built) ──
+        // _edges is the serialized edge list; the two maps index it by endpoint for
+        // O(1) getEdges and edge-backed findCallers/findReferers. Cleared on any
+        // incremental update (daemon) so a stale graph never serves wrong callers.
+        this._edges       = null;
+        this._edgesByTo   = new Map();   // to_chunk_id   → edge[]
+        this._edgesByFrom = new Map();   // from_chunk_id → edge[]
+
+        // ── A5: symbol centrality (PageRank over the edges; built with the graph) ──
+        // _centrality maps chunk id → { score, rank }; precomputed at index time and
+        // serialized, so both backends serve identical numbers. Cleared with the edges.
+        this._centrality      = null;
+        this._centralityTotal = 0;
+        this._centralRanked   = null;    // lazy id-by-rank cache for topCentral
+
+        // ── C2: serialized taint flows ({ flows, meta }); precomputed at index time with --taint,
+        //    so the taint tools serve instantly and both backends serve identical flows. Cleared
+        //    on any incremental file update (a code change invalidates the flow set).
+        this._taint = null;
+
+        // ── A2 v2: SCIP precise references — `{ defChunkId: [refererChunkId, …] }`, built at index
+        //    time from a locally-generated SCIP index (--resolver scip) and serialized as an
+        //    isolated artifact so it cannot perturb A4 edges / A5 centrality. find_references reads
+        //    it for a binding-precise, cross-file `resolved` reference tier. Cleared with the graph.
+        this._scipRefs = null;
+
+        // ── B3: learned-sparse association model — `{ assoc: { term: [[assocTerm, weight], …] } }`,
+        //    learned from corpus co-occurrence at index time with --learned-sparse and serialized as
+        //    an isolated artifact. searchHybrid uses it to add an NL-only vocabulary-EXPANSION
+        //    channel; absent on default indexes → channel inert → byte-identical. Whole-program →
+        //    cleared on any incremental file update.
+        this._sparseModel = null;
+    }
+
+    /** Index the (already deterministically-ordered) edge list by endpoint. */
+    _indexEdges(edges) {
+        this._edges = edges;
+        this._edgesByTo = new Map();
+        this._edgesByFrom = new Map();
+        for (const e of edges) {
+            if (!this._edgesByTo.has(e.to_chunk_id)) this._edgesByTo.set(e.to_chunk_id, []);
+            this._edgesByTo.get(e.to_chunk_id).push(e);
+            if (!this._edgesByFrom.has(e.from_chunk_id)) this._edgesByFrom.set(e.from_chunk_id, []);
+            this._edgesByFrom.get(e.from_chunk_id).push(e);
+        }
+    }
+
+    /** Load the precomputed symbol-centrality map (A5). */
+    _indexCentrality(centrality) {
+        this._centrality = new Map(Object.entries(centrality));
+        this._centralityTotal = this._centrality.size;
+        this._centralRanked = null;
+    }
+
+    /** Drop the symbol graph + its centrality + serialized taint + SCIP references (an incremental update makes them stale). */
+    _clearEdges() {
+        this._edges = null;
+        this._edgesByTo = new Map();
+        this._edgesByFrom = new Map();
+        this._centrality = null;
+        this._centralityTotal = 0;
+        this._centralRanked = null;
+        this._taint = null;
+        this._scipRefs = null;
+        this._sparseModel = null;
     }
 
     // ─── Load ─────────────────────────────────────────────────────────────────
@@ -78,6 +146,16 @@ export class MemoryGraphIndex {
         if (!fs.existsSync(this.indexPath)) return;
         const data = JSON.parse(fs.readFileSync(this.indexPath, 'utf-8'));
         this.graph = data.graph || { dependencies: {}, importedBy: {} };
+        // A4 resolved symbol graph (opt-in; absent on default indexes → no-op).
+        if (Array.isArray(data.edges)) this._indexEdges(data.edges);
+        // A5 symbol centrality (built with the graph; absent on default indexes → no-op).
+        if (data.centrality && typeof data.centrality === 'object') this._indexCentrality(data.centrality);
+        // C2 serialized taint flows (opt-in --taint; absent on default indexes → no-op).
+        if (data.taint && typeof data.taint === 'object') this._taint = data.taint;
+        // A2 v2 SCIP precise references (opt-in --resolver scip; absent on default indexes → no-op).
+        if (data.scip_refs && typeof data.scip_refs === 'object') this._scipRefs = data.scip_refs;
+        // B3 learned-sparse model (opt-in --learned-sparse; absent on default indexes → no-op).
+        if (data.sparse_model && typeof data.sparse_model === 'object') this._sparseModel = data.sparse_model;
         // Does this corpus carry LLM enrichment? Drives the NL vector-channel weight
         // in fuseAndRank (strong summary vectors earn full weight; plain code vectors
         // stay a low-weight rescue). Set during the chunk load loop below.
@@ -492,9 +570,14 @@ export class MemoryGraphIndex {
             vectorResults = [];
         }
 
+        // B3 learned-sparse channel: opt-in (model present) + NL-asymmetric (symbolic queries skip
+        // it → byte-identical). expandSparseQuery returns null when nothing fires → no channel.
+        const sparseResults = this._searchSparseExpanded(queryText);
+
         return fuseAndRank({
             lexicalResults,
             vectorResults,
+            sparseResults,
             getChunk:      (id) => this.chunks.get(id),
             getPathTokens: (id) => this.pathTokens.get(id),
             getDf:         (t)  => this.df.get(t) || 0,
@@ -509,6 +592,31 @@ export class MemoryGraphIndex {
         });
     }
 
+    /**
+     * B3 — the learned-sparse expansion channel: NL queries only, model present only. Returns the
+     * ranked sparse candidates, or [] when the channel is inert (no model / symbolic query / no
+     * association fired) so fusion is byte-identical to the default path.
+     */
+    _searchSparseExpanded(queryText) {
+        if (!this._sparseModel || !isNaturalLanguageQuery(queryText)) return [];
+        const termWeights = expandSparseQuery(queryText, this._sparseModel);
+        if (!termWeights) return [];
+        const avgdl = this.docCount > 0 ? this.totalDocLen / this.docCount : 1;
+        return scoreSparseExpanded(termWeights, {
+            docCount:   this.docCount,
+            avgdl,
+            getDf:      (t) => this.df.get(t) || 0,
+            getPostings:(t) => this.invertedIndex.get(t) || [],
+            getDocLen:  (id) => this.docLens.get(id),
+        });
+    }
+
+    /** Whether opt-in learned-sparse associations (B3 --learned-sparse) are loaded. */
+    hasSparseModel() { return this._sparseModel != null; }
+
+    /** Path to the shared `.embeddings.bin` (B4 late-interaction reranker reads candidate vectors from it). */
+    embeddingBinPath() { return this._embeddingPath; }
+
     // ─── Persistence ───────────────────────────────────────────────────────────
 
     async save() {
@@ -522,7 +630,14 @@ export class MemoryGraphIndex {
             extends: c.extends || [],
             hyde: c.hyde || '', summary: c.summary || '', concepts: c.concepts || [],
         }));
-        const payload  = JSON.stringify({ chunks: chunksData, graph: this.graph });
+        const payload  = JSON.stringify({
+            chunks: chunksData, graph: this.graph,
+            ...(this._edges ? { edges: this._edges } : {}),
+            ...(this._centrality ? { centrality: Object.fromEntries(this._centrality) } : {}),
+            ...(this._taint ? { taint: this._taint } : {}),
+            ...(this._scipRefs ? { scip_refs: this._scipRefs } : {}),
+            ...(this._sparseModel ? { sparse_model: this._sparseModel } : {}),
+        });
         const tmpPath    = `${this.indexPath}.tmp`;
         const tmpBinPath = `${this._embeddingPath}.tmp`;
         await Promise.all([
@@ -571,6 +686,10 @@ export class MemoryGraphIndex {
      * @param {Map<string, Float32Array|number[]>} [p.embeddings] New vectors keyed by embeddingKeyFor(chunk).
      */
     applyFileUpdate(filePath, { chunks = [], imports = [], embeddings = null } = {}) {
+        // A per-file edit makes the whole-program symbol graph + its centrality stale; drop
+        // both so findCallers/findReferers fall back to the always-correct scan until the next
+        // full `idx-index` rebuilds them (the daemon never rebuilds the graph).
+        if (this._edges || this._centrality || this._taint || this._scipRefs || this._sparseModel) this._clearEdges();
         this.updateFileGraph(filePath, imports);
 
         for (const [id, chunk] of Array.from(this.chunks.entries())) {
@@ -680,13 +799,103 @@ export class MemoryGraphIndex {
         return out;
     }
 
+    /**
+     * Resolved symbol-graph edges incident to a chunk (A4). Returns [] unless the
+     * opt-in graph was built. Deterministically ordered (the edge list is pre-sorted).
+     * @param {string} chunkId
+     * @param {object} [opts]
+     * @param {string|null} [opts.kind]      Filter to 'calls' | 'extends' | 'type'.
+     * @param {'in'|'out'} [opts.direction]  'in' = referrers of chunkId (default), 'out' = its referents.
+     * @returns {Array<{from_chunk_id:string,to_chunk_id:string,kind:string,confidence:string,chunk:object|null}>}
+     */
+    /** Whether the opt-in resolved symbol graph (A4) is loaded. */
+    hasSymbolGraph() { return this._edges != null; }
+
+    getEdges(chunkId, { kind = null, direction = 'in' } = {}) {
+        if (!this._edges) return [];
+        const src = direction === 'out' ? this._edgesByFrom : this._edgesByTo;
+        const list = src.get(chunkId) || [];
+        const out = [];
+        for (const e of list) {
+            if (kind && e.kind !== kind) continue;
+            const otherId = direction === 'out' ? e.to_chunk_id : e.from_chunk_id;
+            out.push({ ...e, chunk: this.chunks.get(otherId) ?? null });
+        }
+        return out;
+    }
+
+    /** Whether opt-in symbol centrality (A5) is loaded. */
+    hasCentrality() { return this._centrality != null; }
+
+    /** Whether opt-in serialized taint flows (C2 --taint) are loaded. */
+    hasTaint() { return this._taint != null; }
+
+    /** The serialized taint payload `{ flows, meta }` (C2), or null. */
+    getTaintFlows() { return this._taint; }
+
+    /** Whether opt-in SCIP precise references (A2 v2 --resolver scip) are loaded. */
+    hasScipRefs() { return this._scipRefs != null; }
+
+    /** SCIP-confirmed referer chunk ids for a definition chunk (A2 v2), or [] when none / not loaded. */
+    getScipReferers(defChunkId) {
+        const refs = this._scipRefs && this._scipRefs[defChunkId];
+        return Array.isArray(refs) ? refs : [];
+    }
+
+    /** How many definitions carry SCIP precise references (A2 v2). 0 when not loaded. */
+    scipRefCount() { return this._scipRefs ? Object.keys(this._scipRefs).length : 0; }
+
+    /**
+     * Symbol centrality (A5) for one chunk: its PageRank score, dense rank (1 = most central),
+     * and the total number of ranked (connected) chunks. Null when the chunk is unranked
+     * (isolated) or centrality was not built. @returns {{score:number,rank:number,total:number}|null}
+     */
+    getCentrality(chunkId) {
+        if (!this._centrality) return null;
+        const e = this._centrality.get(chunkId);
+        return e ? { score: e.score, rank: e.rank, total: this._centralityTotal } : null;
+    }
+
+    /** The most central symbols (A5), rank-ascending. @returns {Array<{chunk,score,rank}>} */
+    topCentral(limit = 20) {
+        if (!this._centrality) return [];
+        if (!this._centralRanked) {
+            this._centralRanked = [...this._centrality.entries()]
+                .map(([id, v]) => ({ id, score: v.score, rank: v.rank }))
+                .sort((a, b) => a.rank - b.rank || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+        }
+        const out = [];
+        for (const { id, score, rank } of this._centralRanked) {
+            const chunk = this.chunks.get(id);
+            if (!chunk) continue;
+            out.push({ chunk, score, rank });
+            if (out.length >= limit) break;
+        }
+        return out;
+    }
+
     /** Chunks that call the given function name. @returns {object[]} */
     findCallers(funcName) {
+        // Edge-backed (A4) when the resolved graph is present and the name is defined —
+        // returns the SAME set as the scan below (every name-match caller → each def).
+        if (this._edges) {
+            const defs = this.resolveSymbol(funcName);
+            if (defs.length > 0) return this._referrersByEdge(defs, e => e.kind === 'calls');
+        }
         const out = [];
         for (const c of this.chunks.values()) if (c.calls?.includes(funcName)) out.push(c);
         return out;
     }
 
+    /** From-chunks of edges of a given kind that point at any of `defs`, id-sorted. */
+    _referrersByEdge(defs, keep) {
+        const ids = new Set();
+        for (const def of defs) for (const e of (this._edgesByTo.get(def.id) || [])) if (keep(e)) ids.add(e.from_chunk_id);
+        const out = [];
+        for (const id of [...ids].sort()) { const c = this.chunks.get(id); if (c) out.push(c); }
+        return out;
+    }
+
     /**
      * Chunks that reference a symbol *by name* as a type (`type_refs`) or as a
      * base class/interface (`extends`) — the non-call half of symbol-level
@@ -697,6 +906,10 @@ export class MemoryGraphIndex {
     findReferers(symbol) {
         const key = String(symbol).toLowerCase().trim();
         if (!key) return [];
+        if (this._edges) {
+            const defs = this.resolveSymbol(symbol);
+            if (defs.length > 0) return this._referrersByEdge(defs, e => e.kind === 'extends' || e.kind === 'type');
+        }
         const out = [];
         for (const c of this.chunks.values()) {
             // A class/type lists its own name in type_refs (the name node is a

package/engine/sqlite.mjs

@@ -29,8 +29,9 @@ import fs from 'fs';
 import {
     tokenize, okapiIdf, bm25Score, fuseAndRank, buildLexicalDocument, embeddingKeyFor,
     LEXICAL_FUSION_CAP, VECTOR_SCAN_RAW_N, finalizeVectorCandidates,
-    isNaturalLanguageQuery, baseEmbeddingKey,
+    isNaturalLanguageQuery, baseEmbeddingKey, scoreSparseExpanded,
 } from '../search-core.mjs';
+import { expandSparseQuery } from '../search-sparse.mjs';
 import {
     writeEmbeddingBinary, appendEmbeddingBinary, scanEmbeddingBinary,
     updateVectorSketch, searchVectorSketch, SKETCH_THRESHOLD,
@@ -60,6 +61,11 @@ CREATE TABLE IF NOT EXISTS chunks (
 CREATE TABLE IF NOT EXISTS postings (term TEXT, chunk_id TEXT, tf INTEGER);
 CREATE TABLE IF NOT EXISTS terms (term TEXT PRIMARY KEY, df INTEGER);
 CREATE TABLE IF NOT EXISTS call_edges (callee TEXT, chunk_id TEXT);
+CREATE TABLE IF NOT EXISTS edges (from_chunk_id TEXT, to_chunk_id TEXT, kind TEXT, confidence TEXT);
+CREATE TABLE IF NOT EXISTS centrality (chunk_id TEXT, score REAL, rank INTEGER);
+CREATE TABLE IF NOT EXISTS taint (id INTEGER PRIMARY KEY, payload TEXT);
+CREATE TABLE IF NOT EXISTS scip_refs (id INTEGER PRIMARY KEY, payload TEXT);
+CREATE TABLE IF NOT EXISTS sparse_model (id INTEGER PRIMARY KEY, payload TEXT);
 CREATE TABLE IF NOT EXISTS deps (file TEXT, dep TEXT);
 CREATE TABLE IF NOT EXISTS routes (
   id INTEGER PRIMARY KEY,
@@ -81,6 +87,10 @@ CREATE INDEX IF NOT EXISTS idx_chunks_hash ON chunks(content_hash);
 CREATE INDEX IF NOT EXISTS idx_postings_term ON postings(term);
 CREATE INDEX IF NOT EXISTS idx_postings_chunk ON postings(chunk_id);
 CREATE INDEX IF NOT EXISTS idx_calledges_callee ON call_edges(callee);
+CREATE INDEX IF NOT EXISTS idx_edges_to ON edges(to_chunk_id);
+CREATE INDEX IF NOT EXISTS idx_edges_from ON edges(from_chunk_id);
+CREATE INDEX IF NOT EXISTS idx_centrality_chunk ON centrality(chunk_id);
+CREATE INDEX IF NOT EXISTS idx_centrality_rank ON centrality(rank);
 CREATE INDEX IF NOT EXISTS idx_deps_file ON deps(file);
 CREATE INDEX IF NOT EXISTS idx_deps_dep ON deps(dep);
 CREATE INDEX IF NOT EXISTS idx_routes_method ON routes(method);
@@ -129,6 +139,14 @@ export class SqliteGraphStore {
         this._dataVersion = -1;
         this._writeReady = false;
         this._sketch = null; // binary-quantized vector sketch (built above SKETCH_THRESHOLD)
+        this._hasEdges = false; // A4: resolved symbol graph present (opt-in)
+        this._hasCentrality = false; // A5: symbol centrality present (opt-in, built with the graph)
+        this._centralityTotal = 0;
+        this._hasTaint = false; // C2: serialized taint flows present (opt-in --taint)
+        this._hasScipRefs = false; // A2 v2: SCIP precise references present (opt-in --resolver scip)
+        this._scipRefsObj = null;  // lazily-parsed `{ defId: [refId,…] }` payload (memoized)
+        this._hasSparseModel = false; // B3: learned-sparse model present (opt-in --learned-sparse)
+        this._sparseModelObj = null;  // lazily-parsed `{ assoc: {…} }` payload (memoized)
     }
 
     get backend() { return 'sqlite'; }
@@ -177,10 +195,56 @@ export class SqliteGraphStore {
         this._openVecFd();
         this._refreshSketch();
         this._prepare();
+        this._refreshHasEdges();
+        this._refreshHasCentrality();
+        this._refreshHasTaint();
+        this._refreshHasScipRefs();
+        this._refreshHasSparseModel();
         this._dataVersion = this._readDataVersion();
         return this;
     }
 
+    /** Whether the opt-in resolved symbol graph (A4) has any edges. */
+    _refreshHasEdges() {
+        try { this._hasEdges = Boolean(this.db.prepare('SELECT 1 FROM edges LIMIT 1').get()); }
+        catch { this._hasEdges = false; }
+    }
+
+    /** Whether opt-in symbol centrality (A5) is present, and how many chunks are ranked. */
+    _refreshHasCentrality() {
+        try {
+            const row = this.db.prepare('SELECT COUNT(*) AS n FROM centrality').get();
+            this._centralityTotal = row ? row.n : 0;
+            this._hasCentrality = this._centralityTotal > 0;
+        } catch { this._hasCentrality = false; this._centralityTotal = 0; }
+    }
+
+    /** Whether opt-in serialized taint flows (C2 --taint) are present. */
+    _refreshHasTaint() {
+        try {
+            const row = this.db.prepare('SELECT COUNT(*) AS n FROM taint').get();
+            this._hasTaint = Boolean(row && row.n > 0);
+        } catch { this._hasTaint = false; }
+    }
+
+    /** Whether opt-in SCIP precise references (A2 v2 --resolver scip) are present. */
+    _refreshHasScipRefs() {
+        try {
+            const row = this.db.prepare('SELECT COUNT(*) AS n FROM scip_refs').get();
+            this._hasScipRefs = Boolean(row && row.n > 0);
+        } catch { this._hasScipRefs = false; }
+        this._scipRefsObj = null;   // drop any memoized payload — the row may have changed
+    }
+
+    /** Whether opt-in learned-sparse associations (B3 --learned-sparse) are present. */
+    _refreshHasSparseModel() {
+        try {
+            const row = this.db.prepare('SELECT COUNT(*) AS n FROM sparse_model').get();
+            this._hasSparseModel = Boolean(row && row.n > 0);
+        } catch { this._hasSparseModel = false; }
+        this._sparseModelObj = null;   // drop any memoized payload — the row may have changed
+    }
+
     _openVecFd() {
         if (this._vecFd >= 0) { try { fs.closeSync(this._vecFd); } catch {} this._vecFd = -1; }
         if (fs.existsSync(this._embeddingPath)) {
@@ -306,6 +370,27 @@ export class SqliteGraphStore {
             'SELECT method, path, handler_name, handler_chunk_id, file_path, line, framework '
             + 'FROM routes ORDER BY id'
         );
+        // A4 symbol graph. ORDER mirrors the in-memory engine's per-endpoint slice of the
+        // globally-sorted edge list (fixed `to` → sort by from,kind,confidence; fixed `from`
+        // → sort by to,kind,confidence) so getEdges is byte-identical cross-backend.
+        this._stmtEdgesIn   = this.db.prepare(
+            'SELECT from_chunk_id, to_chunk_id, kind, confidence FROM edges WHERE to_chunk_id = ? '
+            + 'ORDER BY from_chunk_id, kind, confidence'
+        );
+        this._stmtEdgesOut  = this.db.prepare(
+            'SELECT from_chunk_id, to_chunk_id, kind, confidence FROM edges WHERE from_chunk_id = ? '
+            + 'ORDER BY to_chunk_id, kind, confidence'
+        );
+        // A5 symbol centrality. rank/score are precomputed at index time; topCentral orders by
+        // the stored rank (chunk_id tie-break mirrors the in-memory ranked cache).
+        this._stmtCentrality = this.db.prepare('SELECT score, rank FROM centrality WHERE chunk_id = ?');
+        this._stmtTopCentral = this.db.prepare(
+            'SELECT chunk_id, score, rank FROM centrality ORDER BY rank ASC, chunk_id ASC LIMIT ?'
+        );
+        // C2 serialized taint flows — a single JSON payload row (id = 0).
+        this._stmtTaint = this.db.prepare('SELECT payload FROM taint WHERE id = 0');
+        this._stmtScipRefs = this.db.prepare('SELECT payload FROM scip_refs WHERE id = 0');
+        this._stmtSparseModel = this.db.prepare('SELECT payload FROM sparse_model WHERE id = 0');
     }
 
     _prepareWrite() {
@@ -365,11 +450,124 @@ export class SqliteGraphStore {
         return this._stmtByName.all(key).map(r => this._rowToChunk(r));
     }
 
-    findCallers(funcName) { return this._stmtCallers.all(funcName).map(r => this._rowToChunk(r)); }
+    /**
+     * Resolved symbol-graph edges incident to a chunk (A4). Mirrors MemoryGraphIndex.getEdges,
+     * including deterministic order. Returns [] unless the opt-in graph was built.
+     */
+    /** Whether the opt-in resolved symbol graph (A4) is loaded. */
+    hasSymbolGraph() { return this._hasEdges; }
+
+    getEdges(chunkId, { kind = null, direction = 'in' } = {}) {
+        if (!this._hasEdges) return [];
+        const rows = direction === 'out' ? this._stmtEdgesOut.all(chunkId) : this._stmtEdgesIn.all(chunkId);
+        const out = [];
+        for (const e of rows) {
+            if (kind && e.kind !== kind) continue;
+            const otherId = direction === 'out' ? e.to_chunk_id : e.from_chunk_id;
+            out.push({ from_chunk_id: e.from_chunk_id, to_chunk_id: e.to_chunk_id, kind: e.kind, confidence: e.confidence, chunk: this.getChunk(otherId) });
+        }
+        return out;
+    }
+
+    /** Whether opt-in symbol centrality (A5) is loaded. */
+    hasCentrality() { return this._hasCentrality; }
+
+    /** Whether opt-in serialized taint flows (C2 --taint) are loaded. */
+    hasTaint() { return this._hasTaint; }
+
+    /** The serialized taint payload `{ flows, meta }` (C2), or null. Mirrors MemoryGraphIndex. */
+    getTaintFlows() {
+        if (!this._hasTaint) return null;
+        const row = this._stmtTaint.get();
+        if (!row || !row.payload) return null;
+        try { return JSON.parse(row.payload); } catch { return null; }
+    }
+
+    /** Whether opt-in SCIP precise references (A2 v2 --resolver scip) are loaded. */
+    hasScipRefs() { return this._hasScipRefs; }
+
+    /** Parse the single JSON payload `{ defId: [refId,…] }` once, then memoize. */
+    _loadScipRefs() {
+        if (!this._hasScipRefs) return {};
+        if (!this._scipRefsObj) {
+            const row = this._stmtScipRefs.get();
+            try { this._scipRefsObj = row && row.payload ? JSON.parse(row.payload) : {}; }
+            catch { this._scipRefsObj = {}; }
+        }
+        return this._scipRefsObj;
+    }
+
+    /** SCIP-confirmed referer chunk ids for a definition chunk (A2 v2), or []. Mirrors MemoryGraphIndex. */
+    getScipReferers(defChunkId) {
+        const refs = this._loadScipRefs()[defChunkId];
+        return Array.isArray(refs) ? refs : [];
+    }
+
+    /** How many definitions carry SCIP precise references (A2 v2). 0 when not loaded. */
+    scipRefCount() { return this._hasScipRefs ? Object.keys(this._loadScipRefs()).length : 0; }
+
+    /** Whether opt-in learned-sparse associations (B3 --learned-sparse) are loaded. */
+    hasSparseModel() { return this._hasSparseModel; }
+
+    /** Path to the shared `.embeddings.bin` (B4 late-interaction reranker reads candidate vectors from it). */
+    embeddingBinPath() { return this._embeddingPath; }
+
+    /** Parse the single learned-sparse payload once, then memoize. Mirrors MemoryGraphIndex._sparseModel. */
+    _loadSparseModel() {
+        if (!this._hasSparseModel) return null;
+        if (!this._sparseModelObj) {
+            const row = this._stmtSparseModel.get();
+            try { this._sparseModelObj = row && row.payload ? JSON.parse(row.payload) : null; }
+            catch { this._sparseModelObj = null; }
+        }
+        return this._sparseModelObj;
+    }
+
+    /**
+     * Symbol centrality (A5) for one chunk. Mirrors MemoryGraphIndex.getCentrality — same
+     * { score, rank, total } shape; null when unranked or centrality was not built.
+     */
+    getCentrality(chunkId) {
+        if (!this._hasCentrality) return null;
+        const row = this._stmtCentrality.get(chunkId);
+        return row ? { score: row.score, rank: row.rank, total: this._centralityTotal } : null;
+    }
+
+    /** The most central symbols (A5), rank-ascending. @returns {Array<{chunk,score,rank}>} */
+    topCentral(limit = 20) {
+        if (!this._hasCentrality) return [];
+        const out = [];
+        for (const row of this._stmtTopCentral.all(limit)) {
+            const chunk = this.getChunk(row.chunk_id);
+            if (chunk) out.push({ chunk, score: row.score, rank: row.rank });
+        }
+        return out;
+    }
+
+    /** From-chunks of edges of a kept kind pointing at any of `defs`, id-sorted. */
+    _referrersByEdge(defs, keepKind) {
+        const ids = new Set();
+        for (const def of defs) for (const e of this._stmtEdgesIn.all(def.id)) if (keepKind(e.kind)) ids.add(e.from_chunk_id);
+        const out = [];
+        for (const id of [...ids].sort()) { const c = this.getChunk(id); if (c) out.push(c); }
+        return out;
+    }
+
+    findCallers(funcName) {
+        if (this._hasEdges) {
+            const defs = this.resolveSymbol(funcName);
+            if (defs.length > 0) return this._referrersByEdge(defs, k => k === 'calls');
+        }
+        return this._stmtCallers.all(funcName).map(r => this._rowToChunk(r));
+    }
 
     findReferers(symbol) {
         const key = String(symbol).toLowerCase().trim();
         if (!key) return [];
+        if (this._hasEdges) {
+            const defs = this.resolveSymbol(symbol);
+            if (defs.length > 0) return this._referrersByEdge(defs, k => k === 'extends' || k === 'type');
+        }
         // Escape LIKE metacharacters in the symbol, then bracket with JSON quotes so
         // the prefilter only fires on a whole array element.
         const esc = key.replace(/[\\%_]/g, m => '\\' + m);
@@ -513,6 +711,11 @@ export class SqliteGraphStore {
             .slice(0, LEXICAL_FUSION_CAP)
             .map(([id, score], i) => ({ id, score, rank: i + 1 }));
 
+        // B3 learned-sparse channel: opt-in (model present) + NL-asymmetric. Shares scoreSparseExpanded
+        // with the in-memory engine over identically-ordered terms → byte-identical to memory. [] when
+        // inert (no model / symbolic query / no association) → fusion byte-identical to the default path.
+        const sparseResults = this._searchSparseExpanded(queryText);
+
         // Stream the FULL embeddings bin (bounded buffers) so conceptual queries
         // that share no tokens with the code can still match — scoring only lexical
         // candidates silently disabled semantic search where it mattered most.
@@ -574,13 +777,36 @@ export class SqliteGraphStore {
         };
 
         return fuseAndRank({
-            lexicalResults, vectorResults, getChunk, getPathTokens, getDf,
+            lexicalResults, vectorResults, sparseResults, getChunk, getPathTokens, getDf,
             docCount: this._docCount, rrfK: this.rrfK, topK, queryText, exactBoostName,
             corpusEnriched: this._corpusEnriched,
             resolveExact: (term) => this._stmtIdByName.all(term).map(r => r.id),
         });
     }
 
+    /**
+     * B3 — the learned-sparse expansion channel (NL queries, model present). Mirrors
+     * MemoryGraphIndex._searchSparseExpanded: identical expansion + the shared scoreSparseExpanded
+     * scorer over identically-ordered terms → byte-identical to memory. Returns [] when inert.
+     */
+    _searchSparseExpanded(queryText) {
+        if (!this._hasSparseModel || !isNaturalLanguageQuery(queryText)) return [];
+        const model = this._loadSparseModel();
+        const termWeights = model && expandSparseQuery(queryText, model);
+        if (!termWeights) return [];
+        const avgdl = this._avgdl;
+        const docLenCache = new Map();
+        return scoreSparseExpanded(termWeights, {
+            docCount: this._docCount,
+            avgdl,
+            getDf: (t) => { const r = this._stmtDf.get(t); return r ? r.df : 0; },
+            // .map() materialises the postings AND populates the doc-len cache before scoring iterates,
+            // so getDocLen always resolves without a second query.
+            getPostings: (t) => this._stmtPosting.all(t).map(r => { docLenCache.set(r.id, r.doc_len); return [r.id, r.tf]; }),
+            getDocLen: (id) => docLenCache.get(id) ?? avgdl,
+        });
+    }
+
     close() {
         if (this._vecFd >= 0) { try { fs.closeSync(this._vecFd); } catch {} this._vecFd = -1; }
         if (this.db) { try { this.db.close(); } catch {} this.db = null; }
@@ -657,6 +883,15 @@ export class SqliteGraphStore {
 
         this.db.exec('BEGIN');
         try {
+            // A per-file edit makes the whole-program symbol graph (A4) stale; clear it so
+            // findCallers/findReferers fall back to the always-correct scan until the next
+            // full `idx-index` rebuilds it (the daemon never rebuilds the graph).
+            if (this._hasEdges) { this.db.exec('DELETE FROM edges'); this._hasEdges = false; }
+            if (this._hasCentrality) { this.db.exec('DELETE FROM centrality'); this._hasCentrality = false; this._centralityTotal = 0; }
+            if (this._hasTaint) { this.db.exec('DELETE FROM taint'); this._hasTaint = false; }
+            if (this._hasScipRefs) { this.db.exec('DELETE FROM scip_refs'); this._hasScipRefs = false; this._scipRefsObj = null; }
+            if (this._hasSparseModel) { this.db.exec('DELETE FROM sparse_model'); this._hasSparseModel = false; this._sparseModelObj = null; }
+
             // Capture reusable vector offsets BEFORE deleting old rows, which may
             // be the only rows that hold those offsets.
             const reuse = new Map();
@@ -749,7 +984,7 @@ export class SqliteGraphStore {
      * @param {{dependencies:Object<string,string[]>}} payload.graph
      * @param {Map<string,Float32Array>|object} [payload.embeddingCache]  Keyed by embeddingKeyFor(chunk).
      */
-    buildFrom({ chunks, graph, embeddingCache }) {
+    buildFrom({ chunks, graph, embeddingCache, edges = null, centrality = null, taint = null, scipRefs = null, sparseModel = null }) {
         this._open();
         this.db.exec('PRAGMA synchronous = OFF;'); // safe only for a full rebuild; not used for incremental writes
 
@@ -781,7 +1016,9 @@ export class SqliteGraphStore {
             DROP TABLE IF EXISTS chunks; DROP TABLE IF EXISTS postings;
             DROP TABLE IF EXISTS terms;  DROP TABLE IF EXISTS call_edges;
             DROP TABLE IF EXISTS deps;   DROP TABLE IF EXISTS meta;
-            DROP TABLE IF EXISTS routes;
+            DROP TABLE IF EXISTS routes; DROP TABLE IF EXISTS edges;
+            DROP TABLE IF EXISTS centrality; DROP TABLE IF EXISTS taint;
+            DROP TABLE IF EXISTS scip_refs; DROP TABLE IF EXISTS sparse_model;
         `);
         this.db.exec(SCHEMA_TABLES);
         this.db.exec(SCHEMA_INDEXES);
@@ -848,6 +1085,42 @@ export class SqliteGraphStore {
             );
         }
 
+        // A4 resolved symbol graph (opt-in). Inserted in the deterministic order produced
+        // by buildSymbolGraph so the table mirrors the in-memory edge list.
+        if (Array.isArray(edges) && edges.length) {
+            const insEdge = this.db.prepare(
+                'INSERT INTO edges (from_chunk_id, to_chunk_id, kind, confidence) VALUES (?, ?, ?, ?)'
+            );
+            for (const e of edges) insEdge.run(e.from_chunk_id, e.to_chunk_id, e.kind, e.confidence);
+        }
+
+        // A5 symbol centrality (opt-in). Precomputed score/rank per chunk id; both backends
+        // read these exact numbers → parity-free. Inserted in rank order for tidy storage.
+        if (centrality && typeof centrality === 'object') {
+            const insCen = this.db.prepare('INSERT INTO centrality (chunk_id, score, rank) VALUES (?, ?, ?)');
+            const rows = Object.entries(centrality).sort((a, b) => a[1].rank - b[1].rank);
+            for (const [id, v] of rows) insCen.run(id, v.score, v.rank);
+        }
+
+        // C2 serialized taint flows (opt-in). A single JSON payload (id = 0); both backends parse
+        // the identical bytes → parity-free, exactly like edges/centrality.
+        if (taint && typeof taint === 'object') {
+            this.db.prepare('INSERT INTO taint (id, payload) VALUES (0, ?)').run(JSON.stringify(taint));
+        }
+
+        // A2 v2 SCIP precise references (opt-in --resolver scip). A single JSON payload (id = 0) of
+        // `{ defChunkId: [refererChunkId, …] }`; both backends parse identical bytes → parity-free,
+        // exactly like taint. find_references reads it for the cross-file `resolved` reference tier.
+        if (scipRefs && typeof scipRefs === 'object' && Object.keys(scipRefs).length) {
+            this.db.prepare('INSERT INTO scip_refs (id, payload) VALUES (0, ?)').run(JSON.stringify(scipRefs));
+        }
+
+        // B3 learned-sparse model (opt-in --learned-sparse). A single JSON payload (id = 0); both
+        // backends parse identical bytes → parity-free, exactly like taint/scip_refs.
+        if (sparseModel && typeof sparseModel === 'object' && sparseModel.assoc) {
+            this.db.prepare('INSERT INTO sparse_model (id, payload) VALUES (0, ?)').run(JSON.stringify(sparseModel));
+        }
+
         const insMeta = this.db.prepare('INSERT OR REPLACE INTO meta (key, value) VALUES (?, ?)');
         insMeta.run('doc_count', String(docCount));
         insMeta.run('total_doc_len', String(totalDocLen));