graph-indexer 2.0.0 → 2.1.0

package/enrichment.mjs

@@ -280,6 +280,101 @@ export async function rerankResults(queryText, results, { generate, topM = 8 } =
     return [...picked, ...rest, ...results.slice(topM)];
 }
 
+// ─── Cross-encoder reranker (local, air-gapped, deterministic) ───────────────
+// A second, opt-in reranker provider (rerank.provider === 'cross-encoder'). Unlike the
+// generative judge — which prompts an LLM for a permutation — a cross-encoder SCORES each
+// (query, candidate) PAIR with a small sequence-classification model and sorts by score.
+// It is local (runs through the optional @huggingface/transformers package, the same dep as
+// the in-process 'local' embedder), needs no Ollama/daemon, is deterministic, and is fast
+// (~tens of ms for a top-12 pool on CPU). It sees only a candidate's signature/summary line,
+// not full code — so it sharpens lexical-vs-semantic near-ties rather than reasoning about
+// behaviour the way a 7B judge can. The generative judge stays as the higher-reasoning tier.
+
+/**
+ * One-line textual representation of a chunk to pair against the query. Mirrors the
+ * generative judge's candidate line (name + class + summary→docstring→snippet) so both
+ * rerankers judge comparable evidence.
+ */
+export function crossEncoderCandidateText(chunk) {
+    const ctx = chunk.class_context ? `${chunk.class_context}.` : '';
+    const desc = chunk.summary
+        || (chunk.docstring || '').split('\n')[0]
+        || (chunk.code_snippet || '').split('\n').slice(0, 3).join(' ');
+    return `${ctx}${chunk.name || ''} — ${(desc || '').slice(0, 300)}`;
+}
+
+// Lazy, module-level singleton model+tokenizer (mirrors embeddings.mjs:_localPipeline). The
+// import is inside the function so the default path never loads @huggingface/transformers.
+let _xenc = null, _xencModel = null;
+async function _crossEncoderPipeline(model) {
+    if (_xenc && _xencModel === model) return _xenc;
+    let mod;
+    try { mod = await import('@huggingface/transformers'); }
+    catch {
+        throw new Error(
+            "Cross-encoder rerank needs the optional '@huggingface/transformers' package. "
+            + "Install it (`npm run embed:setup:local`, or `npm i @huggingface/transformers`) "
+            + "or set rerank.provider to 'generative'."
+        );
+    }
+    const m = await mod.AutoModelForSequenceClassification.from_pretrained(model, { quantized: true });
+    const t = await mod.AutoTokenizer.from_pretrained(model);
+    _xenc = { model: m, tokenizer: t };
+    _xencModel = model;
+    return _xenc;
+}
+
+/** Reset the cached cross-encoder pipeline (tests). */
+export function _resetCrossEncoderPipeline() { _xenc = null; _xencModel = null; }
+
+/**
+ * Score each candidate text against the query with the cross-encoder. Returns one
+ * relevance float per text, in input order (higher = more relevant).
+ *
+ * @param {string} query
+ * @param {string[]} texts
+ * @param {object} [opts]
+ * @param {string} [opts.model]  HF model id (default a MS-MARCO MiniLM cross-encoder).
+ * @returns {Promise<number[]>}
+ */
+export async function crossEncoderScore(query, texts, { model = 'Xenova/ms-marco-MiniLM-L-6-v2' } = {}) {
+    if (!texts || texts.length === 0) return [];
+    const { model: m, tokenizer: t } = await _crossEncoderPipeline(model);
+    const inputs = t(Array(texts.length).fill(query), { text_pair: texts, padding: true, truncation: true });
+    const { logits } = await m(inputs);
+    return logits.tolist().map(row => row[0]);
+}
+
+/**
+ * Cross-encoder rerank: score the leading topM candidates as (query, text) pairs, sort
+ * DESC by score with ties broken on chunk id (so the reorder is deterministic and both
+ * backends rank identically), and preserve the unscored tail. Best-effort — any scorer
+ * failure or malformed output returns the original order untouched. Never mutates the
+ * fused `score` on a result (the git-boost branch downstream relies on that).
+ *
+ * @param {string} queryText
+ * @param {Array<{score:number, chunk:object}>} results  Fused results (copy returned).
+ * @param {object} opts
+ * @param {(query:string, texts:string[])=>Promise<number[]>} opts.scorer  Injectable (tests).
+ * @param {number} [opts.topM]  How many leading results to rerank (default 12).
+ * @returns {Promise<Array<{score:number, chunk:object}>>}
+ */
+export async function rerankCrossEncoder(queryText, results, { scorer, topM = 12 } = {}) {
+    const head = results.slice(0, topM);
+    if (head.length < 2) return results;
+    let scores;
+    try { scores = await scorer(queryText, head.map(r => crossEncoderCandidateText(r.chunk))); }
+    catch { return results; }
+    if (!Array.isArray(scores) || scores.length !== head.length || scores.some(s => !Number.isFinite(s))) {
+        return results;
+    }
+    const order = head
+        .map((r, i) => ({ i, s: scores[i], id: r.chunk.id }))
+        .sort((a, b) => (b.s - a.s) || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0))
+        .map(x => x.i);
+    return [...order.map(i => head[i]), ...results.slice(topM)];
+}
+
 /**
  * Select the chunks worth enriching.
  *

package/indexer.mjs

@@ -13,19 +13,99 @@
 import fs from 'fs';
 import path from 'path';
 import { MAX_FILE_SIZE_BYTES, buildIgnoreFilter, extractImportsFromAST, extractSemanticChunks } from './parse/extractor.mjs';
-import { EXTENSIONS, getParserForFile } from './parse/languages.mjs';
+import { EXTENSIONS, getParserForFile, ensureLanguagesReady } from './parse/languages.mjs';
 import { extractRoutes } from './parse/routes.mjs';
 import { resolveLocalImports, buildEmbeddingPayload, fullBodyForEmbedding } from './parse/imports.mjs';
 import { readEmbeddingBinary, writeEmbeddingBinary } from './engine/binary.mjs';
 import { embeddingKeyFor, summaryEmbeddingText, SUMMARY_VEC_SUFFIX, WINDOW_VEC_SUFFIX, embeddingWindows } from './search-core.mjs';
-import { createEmbedder, describeEmbedder, readEmbedMeta, writeEmbedMeta, _resetSubprocesses } from './embeddings.mjs';
+import { createEmbedder, describeEmbedder, readEmbedMeta, writeEmbedMeta, embedModelChanged, _resetSubprocesses } from './embeddings.mjs';
 import { resolveConfig, describeConfig, configNotices } from './config.mjs';
 import { AUTO_SQLITE_CHUNK_THRESHOLD } from './storage.mjs';
 import { ensureDataDir, migrateLegacyLayout } from './layout.mjs';
 import { enrichCoreChunks } from './enrichment.mjs';
 import { collectGitSignals, writeGitSignals } from './git-signals.mjs';
+import {
+    installEgressGuard, sealManifest, signManifest, verifySignedManifest,
+    generateAttestationKeyPair, canonicalJson, SealViolation,
+} from './seal.mjs';
+
+/** Value following `--flag` in argv, or undefined. */
+function argVal(flag) {
+    const i = process.argv.indexOf(flag);
+    return i >= 0 && i + 1 < process.argv.length ? process.argv[i + 1] : undefined;
+}
+
+// resolveConfig fail-closes on a sealed-incompatible config (throws SealViolation); surface it
+// as a clean exit rather than an unhandled rejection.
+let config;
+try {
+    config = resolveConfig();
+} catch (err) {
+    if (err && err.name === 'SealViolation') { console.error(`🔒 ${err.message}`); process.exit(2); }
+    throw err;
+}
+
+// `idx-index --gen-attestation-key <prefix>`: write an Ed25519 keypair (<prefix>.key / <prefix>.pub)
+// and exit. The private key is the signing key (keep safe); the public key is shared for verification.
+{
+    const prefix = argVal('--gen-attestation-key');
+    if (prefix) {
+        const { publicKey, privateKey } = generateAttestationKeyPair();
+        fs.writeFileSync(`${prefix}.key`, privateKey, { mode: 0o600 });
+        fs.writeFileSync(`${prefix}.pub`, publicKey);
+        console.log(`🔑 Attestation keypair written: ${prefix}.key (private — keep safe) + ${prefix}.pub (share to verify).`);
+        process.exit(0);
+    }
+}
+
+// `idx-index --verify-attestation <file> --pub-key <path>`: verify a signed manifest's signature and,
+// if authentic, report whether it MATCHES the current effective config. Exit 0 = valid + matching.
+{
+    const verifyFile = argVal('--verify-attestation');
+    if (verifyFile) {
+        let envelope;
+        try { envelope = JSON.parse(fs.readFileSync(verifyFile, 'utf8')); }
+        catch (e) { console.error(`❌ cannot read attestation ${verifyFile}: ${e.message}`); process.exit(3); }
+        const pubPath = argVal('--pub-key');
+        if (!pubPath) { console.error('❌ --verify-attestation requires --pub-key <path>'); process.exit(3); }
+        let pubPem;
+        try { pubPem = fs.readFileSync(pubPath, 'utf8'); }
+        catch (e) { console.error(`❌ cannot read public key ${pubPath}: ${e.message}`); process.exit(3); }
+        const res = verifySignedManifest(envelope, pubPem);
+        if (!res.valid) { console.error(`❌ attestation INVALID: ${res.reason}`); process.exit(3); }
+        console.log(`✅ attestation signature VALID (key ${res.publicKeyFingerprint}).`);
+        const matches = canonicalJson(sealManifest(config)) === canonicalJson(envelope.manifest);
+        if (matches) { console.log('✅ attested manifest MATCHES the current effective config.'); process.exit(0); }
+        console.log('⚠️  attested manifest DIFFERS from the current effective config (policy drift):');
+        console.log(`   attested: ${canonicalJson(envelope.manifest)}`);
+        console.log(`   current : ${canonicalJson(sealManifest(config))}`);
+        process.exit(3);
+    }
+}
+
+// `idx-index --attest [--sign-key <path>]`: print the deterministic seal manifest (signed if a key
+// is given) and exit (no indexing).
+if (process.argv.includes('--attest')) {
+    const manifest = sealManifest(config);
+    const signKey = argVal('--sign-key');
+    if (signKey) {
+        let keyPem;
+        try { keyPem = fs.readFileSync(signKey, 'utf8'); }
+        catch (e) { console.error(`❌ cannot read signing key ${signKey}: ${e.message}`); process.exit(2); }
+        try { console.log(JSON.stringify(signManifest(manifest, keyPem), null, 2)); }
+        catch (e) { console.error(`❌ signing failed: ${e.message}`); process.exit(2); }
+    } else {
+        console.log(JSON.stringify(manifest, null, 2));
+    }
+    process.exit(0);
+}
+
+// F1: install the deny-by-default egress guard BEFORE any provider (embedder/enricher) loads, so
+// even provider initialisation cannot reach the network under a sealed tier.
+if (config.sealed !== 'off') {
+    installEgressGuard({ allow: config.sealed === 'local' ? ['loopback'] : [] });
+}
 
-const config = resolveConfig();
 const PROJECT_ROOT = config.projectRoot;
 const INDEX_PATH = config.indexPath;
 const EMBEDDINGS_PATH = config.embeddingPath;
@@ -57,6 +137,30 @@ async function main() {
     for (const notice of configNotices(config)) console.log(`⚠️  ${notice}`);
     console.log('');
 
+    // Grammar packages are installed on demand (not bundled) — resolve/install
+    // whatever the configured languages need BEFORE walking the repo. Sealed mode
+    // never reaches the network for this: installEgressGuard can't stop a child
+    // `npm install` process, so autoInstall is explicitly off rather than relying
+    // on the guard — and, matching the fail-closed egress checks elsewhere in
+    // sealed mode, an unresolvable grammar refuses the run instead of silently
+    // shipping a partial index.
+    const { missing: missingGrammars } = await ensureLanguagesReady({
+        projectRoot: PROJECT_ROOT,
+        enabledLangs: config.languages,
+        autoInstall: config.sealed === 'off',
+        log: (msg) => console.log(msg),
+    });
+    if (config.sealed !== 'off' && missingGrammars.length > 0) {
+        const detail = missingGrammars.map(m => `  • ${m.key} (${m.pkg}@${m.version})`).join('\n');
+        throw new SealViolation(
+            `--sealed ${config.sealed} refuses to start — ${missingGrammars.length} language grammar(s) `
+            + `are not installed and sealed mode won't fetch them:\n${detail}\n`
+            + `  remedy: pre-install before sealing, e.g. npm install --prefix ${path.join(PROJECT_ROOT, '.graph-indexer')} `
+            + `${missingGrammars.map(m => `${m.pkg}@${m.version}`).join(' ')}`
+            + ` — or drop the language from your .graph-indexer.json "languages" selection`
+        );
+    }
+
     const ig = buildIgnoreFilter(PROJECT_ROOT);
     const files = walkRepo(PROJECT_ROOT, PROJECT_ROOT, ig);
     console.log(`Found ${files.length} files to analyse.\n`);
@@ -70,16 +174,17 @@ async function main() {
         if (embedder.provider === 'local') {
             console.log(`   ↪ Ollama not reachable at ${config.ollamaHost}; using the bundled in-process model (no daemon required).`);
         } else if (embedder.provider === 'off') {
-            console.log(`   ↪ No Ollama and no in-process model installed (\`npm i @huggingface/transformers\`) — indexing lexical-only.`);
+            console.log(`   ↪ No Ollama and no in-process model installed (\`npm run embed:setup:local\`) — indexing lexical-only.`);
         }
     }
     console.log('');
 
     let existingCache = readEmbeddingBinary(EMBEDDINGS_PATH);
     // A model switch invalidates the cached vectors — vectors of different models
-    // (and dims) must never be mixed in one bin. Re-embed from scratch.
+    // (and dims) must never be mixed in one bin. Re-embed from scratch. (e.g. switching
+    // `--embed-provider local` → `code-local`: 384-dim MiniLM → 768-dim jina-code.)
     const prevMeta = readEmbedMeta(EMBEDDINGS_PATH);
-    if (prevMeta?.model && embedder.model && prevMeta.model !== embedder.model) {
+    if (embedModelChanged(prevMeta, embedder.model)) {
         console.log(`⚠️  Embedding model changed (${prevMeta.model} → ${embedder.model}); re-embedding from scratch.`);
         existingCache = new Map();
     }
@@ -116,7 +221,7 @@ async function main() {
             const imports = resolveLocalImports(rawImports, relPath, PROJECT_ROOT);
             indexData.graph.dependencies[relPath] = imports;
 
-                    const fileChunks = extractSemanticChunks(tree.rootNode, relPath, content, ext);
+                    const fileChunks = extractSemanticChunks(tree.rootNode, relPath, content, ext, { interprocedural: config.interprocedural });
             for (const chunk of fileChunks) {
                 const fullBody = fullBodyForEmbedding(chunk, content);
                 if (fullBody) fullBodies.set(chunk.id, fullBody);
@@ -131,6 +236,17 @@ async function main() {
         }
     }
 
+    // Opt-in inter-procedural receiver-type fixpoint (--interprocedural): propagate return
+    // types along factory call chains so multi-hop receivers resolve. Runs ONCE over the whole
+    // program here, while every chunk's return_via / call_sites are known, and writes
+    // recv_resolved_type into call_sites (serialized identically by both backends). Strips the
+    // transient _return_via. Off by default → chunks/index byte-identical.
+    if (config.interprocedural) {
+        const { applyInterprocedural } = await import('./parse/interprocedural.mjs');
+        applyInterprocedural(pendingChunks);
+        console.log('🔗 Inter-procedural receiver types resolved (factory return-type propagation).');
+    }
+
     // Enrichment runs before embedding so hypothetical questions share the same vector space.
     if (config.enrichment.enabled) {
         await enrichCoreChunks(pendingChunks, indexData.graph, config);
@@ -231,6 +347,122 @@ async function main() {
         }
     }
 
+    // Opt-in resolved symbol graph (--symbol-graph): build the chunk→chunk edge set ONCE
+    // over the finalized chunks (reusing the query-time resolvers, so confidence matches
+    // get_call_graph). Serialized into the index for both backends → getEdges. Built via a
+    // throwaway in-memory store so it sees the same resolution the MCP server will.
+    let symbolEdges = null;
+    let centrality = null;
+    let scipReferers = null;     // A2 v2: SCIP precise cross-file references for find_references
+    if (config.symbolGraph) {
+        const tmpSg = path.join(config.dataDir, '_symbolgraph-build.json');
+        try {
+            fs.writeFileSync(tmpSg, JSON.stringify({ chunks: indexData.chunks, graph: indexData.graph }));
+            const { MemoryGraphIndex } = await import('./engine/memory.mjs');
+            const { buildSymbolGraph } = await import('./mcp/symbolgraph.mjs');
+            const { getResolver, createScipResolver } = await import('./mcp/resolver.mjs');
+            const { computeSymbolCentrality } = await import('./mcp/centrality.mjs');
+            const sgIdx = new MemoryGraphIndex(tmpSg, { cacheEmbeddings: false });
+            sgIdx.load();
+            // A2: a 'scip' resolver ingests a locally-generated SCIP index and resolves edges by
+            // real cross-file bindings (promote confirmed → `resolved`, suppress wrong-target
+            // fan-out). Missing/unreadable index → fall back to heuristic (never worse, loud).
+            let resolver = getResolver(config.resolver);
+            let scipStats = null;
+            if (config.resolver === 'scip') {
+                if (!config.scipIndex) {
+                    console.warn('⚠️  --resolver scip without --scip-index — no SCIP index to read; '
+                        + 'falling back to heuristic resolver.');
+                    resolver = getResolver('heuristic');
+                } else {
+                    try {
+                        const { loadScip, buildScipBindings, buildScipReferers } = await import('./parse/scip.mjs');
+                        const aligned = buildScipBindings(sgIdx, loadScip(config.scipIndex));
+                        scipStats = aligned.stats;
+                        resolver = createScipResolver(aligned.bindings, aligned.definedChunks);
+                        // A2 v2: invert the same bindings into the precise cross-file "referenced-by"
+                        // map find_references consumes (kind-agnostic, sound, isolated artifact).
+                        const refs = buildScipReferers(aligned.bindings);
+                        if (Object.keys(refs).length) scipReferers = refs;
+                        if (scipStats.matchedDocs === 0) {
+                            console.warn(`⚠️  SCIP index matched 0 of ${scipStats.docs} document(s) to indexed `
+                                + `files (${config.scipIndex}) — check the path / project_root. Resolver is `
+                                + 'effectively inert (edges stay heuristic { high, name_only }).');
+                        }
+                    } catch (e) {
+                        console.warn(`⚠️  SCIP load failed (${e.message}); falling back to heuristic resolver.`);
+                        resolver = getResolver('heuristic');
+                    }
+                }
+            }
+            const res = buildSymbolGraph(sgIdx, { resolver });
+            symbolEdges = res.edges;
+            sgIdx.close?.();
+            const isPreciseTier = config.resolver === 'precise' || (config.resolver === 'scip' && scipStats);
+            const resolvedCount = isPreciseTier
+                ? symbolEdges.filter(e => e.confidence === 'resolved').length : 0;
+            console.log(`🕸  Symbol graph: ${symbolEdges.length} resolved edges`
+                + `${config.resolver === 'precise' ? ` · resolver=precise (${resolvedCount} resolved-tier)` : ''}`
+                + `${(config.resolver === 'scip' && scipStats) ? ` · resolver=scip (${resolvedCount} resolved-tier; `
+                    + `${scipStats.matchedDocs}/${scipStats.docs} docs matched, ${scipStats.bindingPairs} bindings)` : ''}`
+                + `${res.cappedNames.length ? ` (⚠️ ${res.cappedNames.length} high-degree name(s) capped: ${res.cappedNames.slice(0, 5).join(', ')})` : ''}.`);
+            // A5: confidence-weighted PageRank over those edges (computed once → serialized →
+            // parity-free). Surfaced by explain_symbol / get_repo_map; does not touch ranking.
+            const cen = computeSymbolCentrality(symbolEdges);
+            centrality = cen.total ? cen.centrality : null;
+            if (centrality) console.log(`📊 Centrality: ranked ${cen.total} connected symbols (PageRank, ${cen.iters} iters).`);
+            // A2 v2: precise cross-file references (find_references `resolved` tier), serialized
+            // as an isolated artifact alongside the graph.
+            if (scipReferers) {
+                const pairs = Object.values(scipReferers).reduce((s, a) => s + a.length, 0);
+                console.log(`🎯 SCIP references: ${Object.keys(scipReferers).length} definitions referenced (${pairs} precise referer pairs).`);
+            }
+        } finally {
+            try { fs.unlinkSync(tmpSg); } catch { /* none */ }
+        }
+    }
+
+    // C2: opt-in index-time taint serialization. Compute the full flow set once — against the
+    // symbol-graph edges when present (cross-function precision), else chunk.calls — and serialize
+    // it so trace_taint / find_tainted_sinks answer instantly. Like edges/centrality: computed once
+    // → both backends serve byte-identical flows (parity-free).
+    let taintPayload = null;
+    if (config.taint) {
+        const tmpT = path.join(config.dataDir, '_taint-build.json');
+        try {
+            fs.writeFileSync(tmpT, JSON.stringify({
+                chunks: indexData.chunks, graph: indexData.graph,
+                ...(symbolEdges ? { edges: symbolEdges } : {}),
+            }));
+            const { MemoryGraphIndex } = await import('./engine/memory.mjs');
+            const { computeTaintCache } = await import('./mcp/taint.mjs');
+            const tIdx = new MemoryGraphIndex(tmpT, { cacheEmbeddings: false });
+            tIdx.load();
+            taintPayload = computeTaintCache(tIdx, { maxDepth: 4 });
+            tIdx.close?.();
+            console.log(`🧪 Taint: ${taintPayload.flows.length} flows precomputed `
+                + `(${taintPayload.meta.sources} sources, ${taintPayload.meta.sinks} sinks, depth ${taintPayload.meta.maxDepth}).`);
+        } finally {
+            try { fs.unlinkSync(tmpT); } catch { /* none */ }
+        }
+    }
+
+    // B3: opt-in learned-sparse model. Learn the corpus co-occurrence (PMI) association model once
+    // and serialize it (isolated artifact, like centrality/taint); searchHybrid then adds an NL-only
+    // vocabulary-expansion channel. Zero new dependency, fully air-gapped; default index
+    // byte-identical (no model unless --learned-sparse).
+    let sparseModel = null;
+    if (config.learnedSparse) {
+        const { buildSparseModel } = await import('./search-sparse.mjs');
+        sparseModel = buildSparseModel(indexData.chunks);
+        if (sparseModel) {
+            console.log(`🧩 Learned-sparse: ${sparseModel.meta.terms} terms · ${sparseModel.meta.pairs} associations `
+                + `(PMI over ${sparseModel.meta.docs} chunks).`);
+        } else {
+            console.log('🧩 Learned-sparse: no association signal in this corpus — model omitted (channel inert).');
+        }
+    }
+
     // Resolve 'auto' now that the true chunk count is known — the threshold is only
     // meaningful after all chunks have been extracted.
     const backend = config.storage === 'auto'
@@ -245,6 +477,8 @@ async function main() {
         const store = new SqliteGraphStore(config.sqlitePath, { embeddingPath: EMBEDDINGS_PATH });
         const res = store.buildFrom({
             chunks: indexData.chunks, graph: indexData.graph, embeddingCache: indexData.embeddingCache,
+            edges: symbolEdges, centrality, taint: taintPayload, scipRefs: scipReferers,
+            sparseModel,
         });
         store.close?.();
         for (const p of [INDEX_PATH, `${INDEX_PATH}.tmp`]) { try { fs.unlinkSync(p); } catch { /* none */ } }
@@ -254,7 +488,14 @@ async function main() {
         const tmpPath = `${INDEX_PATH}.tmp`;
         const tmpBinPath = `${EMBEDDINGS_PATH}.tmp`;
         await Promise.all([
-            fs.promises.writeFile(tmpPath, JSON.stringify({ chunks: indexData.chunks, graph: indexData.graph })),
+            fs.promises.writeFile(tmpPath, JSON.stringify({
+                chunks: indexData.chunks, graph: indexData.graph,
+                ...(symbolEdges ? { edges: symbolEdges } : {}),
+                ...(centrality ? { centrality } : {}),
+                ...(taintPayload ? { taint: taintPayload } : {}),
+                ...(scipReferers ? { scip_refs: scipReferers } : {}),
+                ...(sparseModel ? { sparse_model: sparseModel } : {}),
+            })),
             fs.promises.writeFile(tmpBinPath, writeEmbeddingBinary(indexData.embeddingCache)),
         ]);
         await Promise.all([
@@ -298,4 +539,8 @@ async function main() {
     _resetSubprocesses();
 }
 
-main().catch(console.error);
+main().catch((err) => {
+    if (err && err.name === 'SealViolation') { console.error(`🔒 ${err.message}`); process.exit(2); }
+    console.error(err);
+    process.exit(1);
+});

package/init.mjs

@@ -33,6 +33,7 @@ import {
 } from './layout.mjs';
 import { readPid, isAlive } from './daemon-lock.mjs';
 import { ensureMlxEnv, mlxEnvReady, mlxVenvPython, mlxVenvDir } from './embedders/setup-mlx.mjs';
+import { localEmbedAvailable } from './embeddings.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
@@ -1359,6 +1360,7 @@ runMigration();
 
 
 stepHeader(1, 'Languages to index');
+log(c.dim('  Each language\'s Tree-sitter grammar installs on first index build (not bundled — keeps a fresh install small); already-installed grammars are reused.'));
 
 let selectedLanguages = null;
 if (isInteractive) {
@@ -1375,6 +1377,7 @@ if (selectedLanguages) {
 } else {
     line(glyph.ok, 'Languages', 'all supported (default)');
     if (detectedLanguages.size > 0) log(c.dim(`      detected: ${Array.from(detectedLanguages).join(', ')}`));
+    log(c.dim('      selecting a subset above installs only those grammars — narrower is faster/smaller'));
 }
 
 
@@ -1448,9 +1451,9 @@ let mlxServerReady = null;
 
         const engineItems = [
             { key: 'off', label: 'Lexical only', desc: c.dim('default · keyword/symbol + stemming · no vectors, no dependencies') },
-            { key: 'auto', label: 'Auto', desc: c.dim('Ollama if running, else a bundled local model — no setup') },
+            { key: 'auto', label: 'Auto', desc: c.dim('Ollama if running, else offers to install a bundled local model') },
             { key: 'ollama', label: 'Ollama', desc: c.dim('highest quality · needs the Ollama app + a pulled model') },
-            { key: 'local', label: 'Local (in-process)', desc: c.dim('no daemon · downloads a ~25 MB model on first index') },
+            { key: 'local', label: 'Local (in-process)', desc: c.dim('no daemon · installs @huggingface/transformers (~50 MB) once + a ~25 MB model on first index') },
         ];
         // MLX runs on the Apple Metal GPU and is macOS-only; only offer it there.
         if (process.platform === 'darwin') {
@@ -1503,6 +1506,26 @@ let mlxServerReady = null;
             }
         }
 
+        // Local (in-process) embeddings: the @huggingface/transformers + ONNX runtime
+        // stack (100s of MB) is a devDependency, NOT shipped to end users by default
+        // (npm's `optionalDependencies` installs eagerly regardless of "optional" in
+        // its name — the opposite of what we want here), so it has to be installed on
+        // demand. Same "provision now" pattern as MLX above. `auto` only needs this
+        // when Ollama actually isn't reachable, so its "no setup" promise stays true
+        // for anyone who already has Ollama running.
+        if (embedProvider === 'local' || (embedProvider === 'auto' && ollamaProbed && !models)) {
+            if (await localEmbedAvailable()) {
+                line(glyph.ok, 'Local embeddings', '@huggingface/transformers installed');
+            } else if (localDep && await confirm({ label: 'Install the local embedding package now?  (npm i @huggingface/transformers, ~50 MB)', def: true })) {
+                log(c.dim('      installing @huggingface/transformers…'));
+                const res = spawnSync(NPM_BIN, ['install', '@huggingface/transformers'], { cwd: PROJECT_ROOT, stdio: 'inherit' });
+                if (res.status === 0) line(glyph.ok, 'Local embeddings', 'installed');
+                else line(glyph.warn, 'Local embeddings', `install failed — run ${c.cyan('npm i @huggingface/transformers')} manually`);
+            } else {
+                line(glyph.skip, 'Local embeddings', `install later with ${c.cyan('npm i @huggingface/transformers')}${localDep ? '' : ' in your project'}`);
+            }
+        }
+
         const enrichEnabled = await confirm({ label: 'Enable LLM enrichment?  (richer semantics, slower indexing)', def: Boolean(exEnrich.enabled) });
 
         // Show a data-driven warning before the reranker question when the detected

package/mcp/centrality.mjs

@@ -0,0 +1,117 @@
+/**
+ * @file mcp/centrality.mjs
+ * @description Symbol-level centrality (A5): confidence-weighted PageRank over the A4
+ *              resolved chunk→chunk symbol graph. A definition referenced (called / extended /
+ *              used as a type) by many *other central* symbols scores high — it is a hub the
+ *              rest of the program leans on.
+ *
+ *              This is DISTINCT from `computePageRank` in search-core.mjs, which ranks FILES
+ *              over the import graph (and drives enrichment selection + get_repo_map file
+ *              ordering). A5 is symbol-granular and call/type-aware, not import-aware.
+ *
+ *              Like the edges themselves, it is computed ONCE at index time and serialized into
+ *              the index, so both backends serve byte-identical scores/ranks — parity is free,
+ *              and it never touches search ranking. Opt-in: only built when --symbol-graph is on.
+ * @author MaquinaTech <https://github.com/MaquinaTech>
+ * @copyright (c) 2026 MaquinaTech. All rights reserved.
+ * @license MIT
+ */
+
+/**
+ * Per-confidence edge weight. A `name_only` edge is a heuristic name match (no receiver type
+ * / no import evidence) and is noisier than a `high` edge, so it contributes half the flow.
+ * The A1 `resolved` tier is a *precision* refinement of `high` (a provably-unambiguous binding),
+ * so it carries the SAME weight — enabling the precise resolver does not perturb centrality.
+ * All deterministic constants — no tuning knob, no config surface.
+ */
+const CONFIDENCE_WEIGHT = { resolved: 1.0, high: 1.0, name_only: 0.5 };
+
+const DAMPING = 0.85;
+const MAX_ITERS = 100;          // hard safety net; sparse symbol graphs converge in ~20–40
+const TOLERANCE = 1e-12;        // L1 delta convergence
+const SCORE_DECIMALS = 8;       // round before serialization → identical bytes both backends
+
+/**
+ * Confidence-weighted PageRank over the resolved symbol graph.
+ *
+ * Deterministic: nodes are the sorted set of edge endpoints, multi-edges between the same
+ * (from→to) pair sum their confidence weights, iteration walks nodes/adjacency in fixed order,
+ * and scores are rounded to a fixed precision. Ranks are a dense ordering by score DESC, then
+ * chunk-id ASC (the same tie-break the rest of the engine uses). The result is serialized, so
+ * cross-backend parity is by construction — both engines read these exact numbers.
+ *
+ * @param {Array<{from_chunk_id:string,to_chunk_id:string,kind:string,confidence:string}>} edges
+ * @param {object} [opts]
+ * @param {number} [opts.damping]
+ * @param {number} [opts.maxIters]
+ * @param {number} [opts.tolerance]
+ * @returns {{ centrality: Record<string,{score:number,rank:number}>, total:number, iters:number }}
+ *          `centrality` is keyed by chunk id; `total` is the number of ranked (connected) chunks.
+ */
+export function computeSymbolCentrality(edges, {
+    damping = DAMPING, maxIters = MAX_ITERS, tolerance = TOLERANCE,
+} = {}) {
+    // ── Node set = every chunk that appears in ANY edge (the connected sub-graph). Isolated
+    //    chunks are not ranked — "rank N of M connected symbols" stays meaningful. ──────────
+    const nodeSet = new Set();
+    for (const e of (edges || [])) { nodeSet.add(e.from_chunk_id); nodeSet.add(e.to_chunk_id); }
+    const nodes = [...nodeSet].sort();
+    const N = nodes.length;
+    if (N === 0) return { centrality: {}, total: 0, iters: 0 };
+
+    const index = new Map();
+    nodes.forEach((id, i) => index.set(id, i));
+
+    // ── Aggregate edge weights by (from → to), summing confidence weights for multi-edges
+    //    (a chunk that both calls AND extends a target flows more) → adjacency sorted by `to`
+    //    index for deterministic float accumulation. ────────────────────────────────────────
+    const outMaps = nodes.map(() => new Map());     // i → Map(j → summed weight)
+    for (const e of (edges || [])) {
+        const i = index.get(e.from_chunk_id);
+        const j = index.get(e.to_chunk_id);
+        const w = CONFIDENCE_WEIGHT[e.confidence] ?? CONFIDENCE_WEIGHT.name_only;
+        outMaps[i].set(j, (outMaps[i].get(j) || 0) + w);
+    }
+    const adj = new Array(N);                        // i → [[j, weight], …] sorted by j
+    const outWeight = new Float64Array(N);
+    for (let i = 0; i < N; i++) {
+        const arr = [...outMaps[i].entries()].sort((a, b) => a[0] - b[0]);
+        let tot = 0;
+        for (const [, w] of arr) tot += w;
+        adj[i] = arr;
+        outWeight[i] = tot;
+    }
+
+    // ── Power iteration. Dangling nodes (no out-edges) redistribute their mass uniformly so
+    //    the rank vector stays a probability distribution. ────────────────────────────────────
+    let rank = new Float64Array(N).fill(1 / N);
+    const teleport = (1 - damping) / N;
+    let iters = 0;
+    for (; iters < maxIters; iters++) {
+        let dangling = 0;
+        for (let i = 0; i < N; i++) if (outWeight[i] === 0) dangling += rank[i];
+        const danglingShare = damping * dangling / N;
+
+        const next = new Float64Array(N);
+        for (let i = 0; i < N; i++) next[i] = teleport + danglingShare;
+        for (let i = 0; i < N; i++) {
+            if (outWeight[i] === 0) continue;
+            const share = damping * rank[i] / outWeight[i];
+            for (const [j, w] of adj[i]) next[j] += share * w;
+        }
+
+        let delta = 0;
+        for (let i = 0; i < N; i++) delta += Math.abs(next[i] - rank[i]);
+        rank = next;
+        if (delta < tolerance) { iters++; break; }
+    }
+
+    // ── Round, then assign dense ranks by score DESC / id ASC. ───────────────────────────────
+    const round = 10 ** SCORE_DECIMALS;
+    const scored = nodes.map((id, i) => ({ id, score: Math.round(rank[i] * round) / round }));
+    scored.sort((a, b) => (b.score - a.score) || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+
+    const centrality = {};
+    scored.forEach((s, i) => { centrality[s.id] = { score: s.score, rank: i + 1 }; });
+    return { centrality, total: N, iters };
+}