graph-indexer 2.0.0 → 2.1.0

package/prompts/languages/RUST.md

@@ -10,7 +10,7 @@
 
     <rules>
         <rule name="hidden-calls">Rust inserts calls the source never spells: `?`→From::from, operators→Add::add etc., Deref coercion→deref, scope end→Drop::drop, `.await`→poll. None appear as edges — never call a trait method unused from an empty call graph.</rule>
-        <rule name="trait-dispatch">Calls through generics (T: Trait) or dyn Trait bind to the method NAME: get_call_graph("execute") mixes every execute. Disambiguate by the impl target in each signature. Enumerate implementors: ONE search_code(query: "impl TraitName for", exact_tokens: "TraitName").</rule>
+        <rule name="trait-dispatch">Calls through generics (T: Trait) or dyn Trait bind to the method NAME: get_call_graph("execute") mixes every execute. Disambiguate by the impl target in each signature. Enumerate implementors: ONE search_code(query: "impl TraitName for", exact_tokens: "TraitName"). If your index was built --resolver scip (rust-analyzer --scip), find_references returns a precise 🎯 SCIP-resolved set that separates same-named methods — trust it over name-only.</rule>
         <rule name="re-exports">`pub use` hubs (crate roots, preludes) produce re_export nodes: internal origin → ONE hop; external crate → stop.</rule>
         <rule name="closures-and-generics">Logic inside closures passed to combinators has no edges — behavioural search. A generic fn is ONE chunk regardless of instantiations; per-type behaviour comes from its trait bounds — resolve the bound trait's method ONCE, per-type copies don't exist.</rule>
         <rule name="query-style">snake_case splits well; pin PascalCase trait/type names with exact_tokens. For error flow, search the error variant name or the thiserror/anyhow message string — far more unique than "error". Trust card file paths over guessed `crate::` paths.</rule>

package/seal.mjs

@@ -0,0 +1,400 @@
+/**
+ * @file seal.mjs
+ * @description Sealed mode (F1): turn "air-gapped by default" from a behaviour you trust into a
+ *              guarantee you can verify and enforce. Two opt-in tiers:
+ *                • strict — zero network egress; lexical-only (the default path).
+ *                • local  — loopback only; local LLM/embedders on this box are allowed, nothing
+ *                           leaves it.
+ *
+ *              Three mechanisms:
+ *                1. assertSealCompatible(config) — FAIL-CLOSED validation: refuse to start if any
+ *                   enabled feature would egress beyond the tier, naming the feature + remedy.
+ *                2. installEgressGuard({allow}) — a deny-by-default runtime hook on the in-process
+ *                   network paths (net/tls sockets, http(s), fetch) so an *accidental* call is
+ *                   caught, not just the known ones. A best-effort child_process denylist covers
+ *                   the obvious out-of-process egress tools (documented limitation: a child
+ *                   process has its own socket layer the parent cannot hook).
+ *                3. sealManifest(config) — a deterministic attestation document (tier, providers,
+ *                   egress posture) an auditor/CI can diff against policy.
+ *
+ *              Sealed mode is itself opt-in and can only REMOVE capability (fail-closed); it never
+ *              changes ranking, the store, or parity. The default path is already strict-compatible.
+ *
+ *              Language grammars (parse/languages.mjs) are a separate, asset-availability form of
+ *              fail-closed: they are not bundled dependencies (installed on demand into
+ *              .graph-indexer/node_modules), so under sealed mode auto-install is disabled and
+ *              indexer.mjs throws SealViolation if a configured language's grammar isn't already
+ *              resolvable — pre-install before sealing rather than silently shipping a partial index.
+ * @author MaquinaTech <https://github.com/MaquinaTech>
+ * @copyright (c) 2026 MaquinaTech. All rights reserved.
+ * @license MIT
+ */
+import http from 'node:http';
+import https from 'node:https';
+import net from 'node:net';
+import cp from 'node:child_process';
+import crypto from 'node:crypto';
+
+/** Thrown by the fail-closed validation and by the runtime guard. */
+export class SealViolation extends Error {
+    constructor(message) { super(message); this.name = 'SealViolation'; }
+}
+
+const LOOPBACK_RE = /^(localhost|127\.\d{1,3}\.\d{1,3}\.\d{1,3}|::1|0:0:0:0:0:0:0:1)$/i;
+
+/** Is a bare host string a loopback address? (IPv6 brackets tolerated.) */
+export function isLoopbackHost(host) {
+    if (!host) return false;
+    const h = String(host).replace(/^\[|\]$/g, '').trim().toLowerCase();
+    return LOOPBACK_RE.test(h);
+}
+
+/** Is a URL string loopback-bound? Unparseable → false (treated as non-loopback). */
+export function isLoopbackUrl(url) {
+    if (!url) return false;
+    try { return isLoopbackHost(new URL(String(url)).hostname); } catch { return false; }
+}
+
+/** The LLM endpoint a feature would hit, given the active provider. */
+function llmHost(config) {
+    return config.llmProvider === 'mlx' ? config.mlxLmHost : config.ollamaHost;
+}
+
+/**
+ * Enumerate the enabled features that make network calls, each tagged with its reach
+ * ('loopback' = this box only, 'remote' = off-box) and a remedy. The default config (every
+ * optional feature off) returns [].
+ *
+ * @param {object} config  Resolved config.
+ * @returns {Array<{feature:string,reach:'loopback'|'remote',target:string,remedy:string}>}
+ */
+export function egressingFeatures(config) {
+    const out = [];
+    const reachOf = (host) => (isLoopbackHost(host) || isLoopbackUrl(host) ? 'loopback' : 'remote');
+
+    if (config.embeddingsEnabled) {
+        const p = config.embedProvider;
+        if (p === 'ollama' || p === 'auto') {
+            out.push({
+                feature: `embeddings (${p === 'auto' ? 'auto→ollama' : 'ollama'})`,
+                reach: reachOf(config.ollamaHost), target: config.ollamaHost,
+                remedy: 'drop --embeddings, or point OLLAMA_HOST at loopback under --sealed local',
+            });
+        } else if (p === 'local') {
+            out.push({
+                feature: 'embeddings (local MiniLM)', reach: 'remote',
+                target: 'model CDN (first-run download)',
+                remedy: 'pre-warm the model cache offline, or drop --embeddings under sealed mode',
+            });
+        } else if (p === 'code-local') {
+            // Same in-process @huggingface/transformers path as 'local' — the code model is
+            // fetched from the model CDN on the FIRST run (air-gapped only once cached).
+            out.push({
+                feature: 'embeddings (code-local code-specialized)', reach: 'remote',
+                target: 'model CDN (first-run download)',
+                remedy: 'pre-warm the code model cache offline, or drop --embeddings under sealed mode',
+            });
+        } else if (p === 'mlx') {
+            out.push({
+                feature: 'embeddings (mlx subprocess)', reach: 'loopback',
+                target: 'local mlx subprocess',
+                remedy: 'drop --embeddings under --sealed strict (local compute only under --sealed local)',
+            });
+        }
+    }
+    if (config.enrichment?.enabled) {
+        out.push({
+            feature: 'enrichment (LLM)', reach: reachOf(llmHost(config)), target: llmHost(config),
+            remedy: 'drop --enrichment under sealed mode',
+        });
+    }
+    if (config.rerank?.enabled) {
+        if (config.rerank.provider === 'cross-encoder') {
+            out.push({
+                feature: 'rerank (cross-encoder)', reach: 'remote',
+                target: 'model CDN (first-run download)',
+                remedy: 'pre-warm the model cache offline, or drop --rerank under sealed mode',
+            });
+        } else {
+            out.push({
+                feature: 'rerank (generative LLM)', reach: reachOf(llmHost(config)), target: llmHost(config),
+                remedy: 'drop --rerank under sealed mode',
+            });
+        }
+    }
+    if (config.hyde?.enabled) {
+        out.push({
+            feature: 'hyde (LLM)', reach: reachOf(llmHost(config)), target: llmHost(config),
+            remedy: 'disable hyde under sealed mode',
+        });
+    }
+    return out;
+}
+
+/**
+ * FAIL-CLOSED validation. Throws SealViolation (listing every offending feature) if the config
+ * would egress beyond its tier. No-op when sealed is 'off'. Called from resolveConfig so a
+ * sealed-incompatible config can never be constructed.
+ *
+ * @param {object} config  Resolved config (reads config.sealed ∈ {'off','local','strict'}).
+ */
+export function assertSealCompatible(config) {
+    const tier = config.sealed || 'off';
+    if (tier === 'off') return;
+    const feats = egressingFeatures(config);
+    // strict forbids ANY egress; local forbids only off-box ('remote') reach.
+    const violations = tier === 'strict' ? feats : feats.filter(f => f.reach === 'remote');
+    if (violations.length === 0) return;
+    const detail = violations.map(v => `  • ${v.feature} → ${v.reach} (${v.target}); ${v.remedy}`).join('\n');
+    throw new SealViolation(
+        `--sealed ${tier} refuses to start — ${violations.length} enabled feature(s) would egress`
+        + (tier === 'strict' ? ' (strict = lexical-only, zero network):\n' : ' beyond loopback:\n')
+        + detail);
+}
+
+// ── Runtime egress guard ─────────────────────────────────────────────────────────────────────
+
+function hostFromHttpArgs(args) {
+    const a = args[0];
+    if (typeof a === 'string') { try { return new URL(a).hostname; } catch { return 'localhost'; } }
+    if (a && typeof a === 'object') {
+        if (typeof a.href === 'string') { try { return new URL(a.href).hostname; } catch { /* fall through */ } }
+        const h = a.hostname || a.host || 'localhost';
+        return String(h).replace(/:\d+$/, '');
+    }
+    return 'localhost';
+}
+
+function hostFromNetArgs(args) {
+    const a = args[0];
+    if (a && typeof a === 'object') {
+        if (a.path) return null;                 // IPC / unix socket — local, not network
+        return a.host || 'localhost';
+    }
+    if (typeof a === 'number') return typeof args[1] === 'string' ? args[1] : 'localhost';
+    if (typeof a === 'string') return null;      // IPC path
+    return 'localhost';
+}
+
+function hostFromFetch(input) {
+    if (typeof input === 'string') { try { return new URL(input).hostname; } catch { return null; } }
+    if (input && typeof input === 'object') {
+        if (typeof input.url === 'string') { try { return new URL(input.url).hostname; } catch { return null; } }
+        try { return new URL(String(input)).hostname; } catch { return null; }
+    }
+    return null;
+}
+
+const EGRESS_BINS = /^(curl|wget|nc|ncat|telnet|ssh|scp|sftp|rsync)$/i;
+const GIT_NET = /^(fetch|pull|push|clone|remote|ls-remote|submodule)$/i;
+const PKG_MGRS = /^(npm|pnpm|yarn|pip|pip3|gem|cargo|go)$/i;
+const PKG_NET = /\b(install|add|update|upgrade|ci|fetch|download|get)\b/i;
+
+/** Best-effort: would this child process reach the network? (documented as not airtight.) */
+export function commandWouldEgress(cmd, args = []) {
+    const base = String(cmd || '').split(/[\\/]/).pop();
+    if (EGRESS_BINS.test(base)) return true;
+    if (/^git$/i.test(base) && args[0] && GIT_NET.test(String(args[0]))) return true;
+    if (PKG_MGRS.test(base) && args.some(a => PKG_NET.test(String(a)))) return true;
+    // shell strings (exec/execSync) arrive as the whole command in `cmd`.
+    if (!args.length && /\b(curl|wget|nc|ncat|ssh|scp|rsync)\b/i.test(String(cmd))) return true;
+    if (!args.length && /\bgit\s+(fetch|pull|push|clone|remote|ls-remote)\b/i.test(String(cmd))) return true;
+    return false;
+}
+
+let _installed = null;
+
+/**
+ * Install the deny-by-default egress guard. Idempotent. The in-process socket/http/fetch hooks are
+ * airtight for THIS process; the child_process denylist is best-effort (a child has its own socket
+ * layer). Returns a handle with restore() (used by tests + an orderly shutdown).
+ *
+ * @param {object} [opts]
+ * @param {Array<'loopback'>} [opts.allow]  [] (strict) → block all; ['loopback'] (local) → permit loopback.
+ */
+export function installEgressGuard({ allow = [] } = {}) {
+    if (_installed) return _installed;
+    const allowLoopback = allow.includes('loopback');
+    const permit = (host) => host !== null && allowLoopback && isLoopbackHost(host);
+    const block = (host, api) => {
+        throw new SealViolation(`sealed mode blocked a network connection to ${host || '(unparseable host)'} via ${api}`);
+    };
+    // A null host from net means IPC/unix socket (local) → allow; from fetch means unparseable → block.
+    const guardNet = (host, api, orig, ctx, args) => {
+        if (host === null || permit(host)) return orig.apply(ctx, args);
+        return block(host, api);
+    };
+
+    const orig = {
+        httpRequest: http.request, httpGet: http.get,
+        httpsRequest: https.request, httpsGet: https.get,
+        netConnect: net.Socket.prototype.connect,
+        fetch: globalThis.fetch,
+        spawn: cp.spawn, spawnSync: cp.spawnSync,
+        exec: cp.exec, execSync: cp.execSync,
+        execFile: cp.execFile, execFileSync: cp.execFileSync,
+    };
+
+    http.request = function (...args) { const h = hostFromHttpArgs(args); return permit(h) ? orig.httpRequest.apply(this, args) : block(h, 'http.request'); };
+    http.get = function (...args) { const h = hostFromHttpArgs(args); return permit(h) ? orig.httpGet.apply(this, args) : block(h, 'http.get'); };
+    https.request = function (...args) { const h = hostFromHttpArgs(args); return permit(h) ? orig.httpsRequest.apply(this, args) : block(h, 'https.request'); };
+    https.get = function (...args) { const h = hostFromHttpArgs(args); return permit(h) ? orig.httpsGet.apply(this, args) : block(h, 'https.get'); };
+    net.Socket.prototype.connect = function (...args) { return guardNet(hostFromNetArgs(args), 'net.connect', orig.netConnect, this, args); };
+    if (orig.fetch) globalThis.fetch = function (input, init) { const h = hostFromFetch(input); return permit(h) ? orig.fetch.call(this, input, init) : block(h, 'fetch'); };
+
+    const guardChild = (name, origFn) => function (cmd, args, ...rest) {
+        const argv = Array.isArray(args) ? args : [];
+        if (commandWouldEgress(cmd, argv)) throw new SealViolation(`sealed mode blocked a network-reaching child process via ${name}: ${cmd}`);
+        return origFn.call(this, cmd, args, ...rest);
+    };
+    cp.spawn = guardChild('spawn', orig.spawn);
+    cp.spawnSync = guardChild('spawnSync', orig.spawnSync);
+    cp.exec = guardChild('exec', orig.exec);
+    cp.execSync = guardChild('execSync', orig.execSync);
+    cp.execFile = guardChild('execFile', orig.execFile);
+    cp.execFileSync = guardChild('execFileSync', orig.execFileSync);
+
+    _installed = {
+        allow,
+        restore() {
+            http.request = orig.httpRequest; http.get = orig.httpGet;
+            https.request = orig.httpsRequest; https.get = orig.httpsGet;
+            net.Socket.prototype.connect = orig.netConnect;
+            if (orig.fetch) globalThis.fetch = orig.fetch;
+            cp.spawn = orig.spawn; cp.spawnSync = orig.spawnSync;
+            cp.exec = orig.exec; cp.execSync = orig.execSync;
+            cp.execFile = orig.execFile; cp.execFileSync = orig.execFileSync;
+            _installed = null;
+        },
+    };
+    return _installed;
+}
+
+/** Whether the guard is currently installed (for stats / idempotency checks). */
+export function egressGuardActive() { return _installed != null; }
+
+/**
+ * Deterministic attestation document — the effective sealed posture an auditor/CI can diff against
+ * policy. No timestamps in the body (stamp outside if needed) so it is reproducible.
+ *
+ * @param {object} config  Resolved config.
+ */
+export function sealManifest(config) {
+    const tier = config.sealed || 'off';
+    return {
+        sealed: tier,
+        egress: tier === 'strict' ? 'none' : tier === 'local' ? 'loopback-only' : 'unrestricted',
+        providers: {
+            embeddings: config.embeddingsEnabled ? config.embedProvider : 'off',
+            enrichment: config.enrichment?.enabled ? config.llmProvider : 'off',
+            rerank: config.rerank?.enabled ? config.rerank.provider : 'off',
+            llm: config.llmProvider || 'ollama',
+        },
+        egressing_features: egressingFeatures(config).map(f => ({ feature: f.feature, reach: f.reach, target: f.target })),
+    };
+}
+
+// ── Attestation signing (F1 hardening) ───────────────────────────────────────────────────────
+// Turn the manifest from a document you trust into one you can VERIFY: a detached signature over
+// its canonical bytes, so an auditor/CI proves the attested posture is authentic and untampered.
+// Pure local crypto (node:crypto) — no dependency, no network; works under --sealed strict.
+
+/**
+ * Deterministic JSON: object keys sorted recursively → stable bytes for signing/verifying. (The
+ * manifest is already emitted in a fixed order, but signing over a canonical form makes the
+ * signature robust to any future key-order change and to a round-trip through a file.)
+ */
+export function canonicalJson(value) {
+    const norm = (v) => {
+        if (Array.isArray(v)) return v.map(norm);
+        if (v && typeof v === 'object') {
+            const out = {};
+            for (const k of Object.keys(v).sort()) out[k] = norm(v[k]);
+            return out;
+        }
+        return v;
+    };
+    return JSON.stringify(norm(value));
+}
+
+/** Map an asymmetric key type to its (node digest, label) signing spec. Ed25519 uses a null digest. */
+function signSpec(keyType) {
+    switch (keyType) {
+        case 'ed25519': return { digest: null, alg: 'ed25519' };
+        case 'ed448': return { digest: null, alg: 'ed448' };
+        case 'rsa':
+        case 'rsa-pss': return { digest: 'sha256', alg: 'rsa-sha256' };
+        case 'ec': return { digest: 'sha256', alg: 'ecdsa-sha256' };
+        default: throw new Error(`unsupported attestation key type: ${keyType}`);
+    }
+}
+
+/** SHA-256 fingerprint (first 16 bytes, hex) of a public key's SPKI/DER encoding — a stable key id. */
+export function publicKeyFingerprint(publicKey) {
+    const der = publicKey.export({ type: 'spki', format: 'der' });
+    return crypto.createHash('sha256').update(der).digest('hex').slice(0, 32);
+}
+
+/**
+ * Sign a seal manifest with a PEM private key (Ed25519 / RSA / EC). Returns a signed envelope
+ * `{ manifest, signature: { alg, keyType, publicKeyFingerprint, value } }`. The signature covers the
+ * CANONICAL JSON of the manifest, so it is reproducible and tamper-evident.
+ *
+ * @param {object} manifest  Output of sealManifest(config).
+ * @param {string|Buffer} privateKeyPem  A PEM-encoded private key.
+ */
+export function signManifest(manifest, privateKeyPem) {
+    const privateKey = crypto.createPrivateKey(privateKeyPem);
+    const spec = signSpec(privateKey.asymmetricKeyType);
+    const data = Buffer.from(canonicalJson(manifest), 'utf8');
+    const value = crypto.sign(spec.digest, data, privateKey).toString('base64');
+    const publicKey = crypto.createPublicKey(privateKey);
+    return {
+        manifest,
+        signature: {
+            alg: spec.alg,
+            keyType: privateKey.asymmetricKeyType,
+            publicKeyFingerprint: publicKeyFingerprint(publicKey),
+            value,
+        },
+    };
+}
+
+/**
+ * Verify a signed manifest envelope against a PEM public key. Returns `{ valid, reason }` (never
+ * throws — a malformed envelope/key is a clean `valid:false`). `valid` is true only if the signature
+ * matches the canonical JSON of `envelope.manifest` under the declared algorithm and key.
+ *
+ * @param {object} envelope  Output of signManifest().
+ * @param {string|Buffer} publicKeyPem  A PEM-encoded public key.
+ */
+export function verifySignedManifest(envelope, publicKeyPem) {
+    try {
+        if (!envelope || !envelope.manifest || !envelope.signature || !envelope.signature.value) {
+            return { valid: false, reason: 'not a signed manifest envelope (missing manifest/signature)' };
+        }
+        const publicKey = crypto.createPublicKey(publicKeyPem);
+        const spec = signSpec(publicKey.asymmetricKeyType);
+        if (spec.alg !== envelope.signature.alg) {
+            return { valid: false, reason: `algorithm mismatch: envelope=${envelope.signature.alg}, key=${spec.alg}` };
+        }
+        const data = Buffer.from(canonicalJson(envelope.manifest), 'utf8');
+        const ok = crypto.verify(spec.digest, data, publicKey, Buffer.from(envelope.signature.value, 'base64'));
+        if (!ok) return { valid: false, reason: 'signature does not match (tampered manifest or wrong key)' };
+        const fp = publicKeyFingerprint(publicKey);
+        if (envelope.signature.publicKeyFingerprint && envelope.signature.publicKeyFingerprint !== fp) {
+            return { valid: false, reason: 'public-key fingerprint mismatch' };
+        }
+        return { valid: true, reason: 'signature valid', publicKeyFingerprint: fp };
+    } catch (e) {
+        return { valid: false, reason: `verification error: ${e.message}` };
+    }
+}
+
+/** Generate an Ed25519 attestation keypair as PEM strings (`idx-index --gen-attestation-key`). */
+export function generateAttestationKeyPair() {
+    return crypto.generateKeyPairSync('ed25519', {
+        publicKeyEncoding: { type: 'spki', format: 'pem' },
+        privateKeyEncoding: { type: 'pkcs8', format: 'pem' },
+    });
+}

package/search-core.mjs

@@ -295,6 +295,43 @@ export function bm25Score(idf, tf, docLen, avgdl, k1 = BM25_K1, b = BM25_B) {
     return idf * (tf * (k1 + 1)) / (tf + k1 * (1 - b + b * docLen / avgdl));
 }
 
+/**
+ * B3 — score the learned-sparse expansion channel: a weighted-term retrieval over the EXISTING BM25
+ * postings, used identically by both backends so the channel is parity-by-construction.
+ *
+ * PARITY INVARIANT (do not break): each chunk receives EXACTLY ONE addend per associate term, so a
+ * chunk's final float sum is the cross-term accumulation in `termWeights`' iteration order — which is
+ * deterministic and identical across backends (expandSparseQuery rebuilds the Map sorted: weight desc,
+ * term asc). The INNER getPostings(term) order legitimately differs between backends (memory Map vs
+ * SQL rows) and is parity-IRRELEVANT precisely because the keys within one term are distinct (one
+ * scores.set per chunk per term). Never accumulate within a term, or emit a chunk twice for one term.
+ *
+ * The backends differ only in HOW postings are reached (in-memory Map vs SQL), injected as accessors:
+ *   getDf(term)            → document frequency (0 ⇒ skip the term)
+ *   getPostings(term)      → iterable of [chunkId, tf]
+ *   getDocLen(chunkId)     → that chunk's BM25 doc length (falls back to avgdl)
+ *
+ * @param {Iterable<[string, number]>} termWeights  associate term → fusion weight (ordered)
+ * @param {{docCount:number, avgdl:number, getDf:Function, getPostings:Function, getDocLen:Function}} acc
+ * @returns {Array<{id:string, score:number, rank:number}>}  ranked, capped, id-tie-broken
+ */
+export function scoreSparseExpanded(termWeights, { docCount, avgdl, getDf, getPostings, getDocLen }) {
+    const scores = new Map();
+    for (const [term, weight] of termWeights) {
+        const dfreq = getDf(term);
+        if (!dfreq) continue;
+        const idf = okapiIdf(docCount, dfreq);
+        for (const [chunkId, tf] of getPostings(term)) {
+            const dl = getDocLen(chunkId) ?? avgdl;
+            scores.set(chunkId, (scores.get(chunkId) || 0) + weight * bm25Score(idf, tf, dl, avgdl));
+        }
+    }
+    return Array.from(scores.entries())
+        .sort((a, b) => (b[1] - a[1]) || (a[0] < b[0] ? -1 : 1))   // id tie-break: backend parity
+        .slice(0, LEXICAL_FUSION_CAP)
+        .map(([id, score], rank) => ({ id, score, rank: rank + 1 }));
+}
+
 // ─── Hybrid fusion (RRF + boost ladder) ────────────────────────────────────────
 
 // Lexical candidates handed to fusion — shared by BOTH backends. An asymmetric
@@ -368,6 +405,20 @@ const NL_LEXICAL_WEIGHT = 1.5;
 const NL_VECTOR_WEIGHT_PLAIN = 0.4;
 const NL_VECTOR_WEIGHT_ENRICHED = 0.6;
 
+// B3 learned-sparse channel weight. The sparse channel is the corpus-learned vocabulary EXPANSION
+// view (associate terms the literal query never mentions); it only fires for NL queries on a
+// --learned-sparse index, so it never touches symbolic lookups or the default path.
+//
+// HONEST MEASUREMENT (strict test:eval, 5 core suites, in-process A/B — see the weight sweep in
+// IMPROVEMENT_LEARNED_SPARSE.md): the channel does NOT beat the lexical baseline at any weight.
+// Higher weights (0.5/0.3) REGRESS semantic s@5 (the co-occurrence associates add noise that buries
+// correct hits); the best case is ≈neutral at 0.2 (semantic + symbolic rank-1 both unchanged,
+// overall s@5 −0.5). Like BM25F / AST / the code-embedding NL weight before it, this measured
+// net-neutral-to-negative, so the DEFAULT stays lexical (B3 ships opt-in via --learned-sparse only).
+// 0.2 is the measured least-harmful active setting for users who opt in / whose corpus has the
+// vocabulary mismatch the benchmark fixtures lack.
+const NL_SPARSE_WEIGHT = 0.2;
+
 const QUERY_STOPWORDS = new Set([
     'the', 'a', 'an', 'and', 'or', 'of', 'to', 'in', 'for', 'on', 'with', 'at',
     'by', 'from', 'that', 'this', 'is', 'are', 'was', 'were', 'be', 'how', 'what',
@@ -424,7 +475,7 @@ export const EXAMPLE_DIR_RE = /^(?:[^/\\]+[/\\])?(?:examples?|samples?|demos?|tu
 export function fuseAndRank({
     lexicalResults, vectorResults, getChunk, getPathTokens, getDf,
     docCount, rrfK, topK, queryText, exactBoostName = null, resolveExact = null,
-    corpusEnriched = false,
+    corpusEnriched = false, sparseResults = [],
 }) {
     const rrfScores = new Map();
     const K = rrfK;
@@ -501,9 +552,12 @@ export function fuseAndRank({
     const queryIsStyle = exactBoostName != null ||
         /[.#]|css|scss|stylesheet|selector|\bstyle\b|\bclass\b|color|margin|padding|font|border|background|hover|keyframe|animation|mixin|breakpoint|responsive|\bwidth\b|\bheight\b/.test(queryLower);
 
+    // B3 learned-sparse channel (opt-in, presence + NL gated by the caller). When the caller passes
+    // no sparse candidates the spread contributes nothing → byte-identical to the default path.
     const allResults = [
         ...vectorResults.map(r => ({ ...r, _w: wVec })),
         ...lexicalResults.map(r => ({ ...r, _w: wLex })),
+        ...sparseResults.map(r => ({ ...r, _w: NL_SPARSE_WEIGHT })),
     ];
 
     for (const { id, rank, _w } of allResults) {
@@ -593,6 +647,102 @@ export function fuseAndRank({
         .filter(r => r.chunk !== undefined);
 }
 
+// ─── D3: learned re-ranker (opt-in, post-fusion) ─────────────────────────────────
+//
+// A learned linear model that RE-ORDERS the fused top-N using features the engine
+// already computes — the RRF fused score plus PROGRAM-STRUCTURE signals A4/A5/A1 added
+// (symbol centrality, resolved-edge in-degree, SCIP-resolved in-degree) and git recency.
+// It is a *post-fusion* re-rank (like the LLM reranker / git boost — tool layer, never
+// inside fuseAndRank), so the default RRF ordering is byte-identical: this runs ONLY when
+// the caller opts in (config.ranker === 'learned'). Inference is a dot product — zero
+// runtime dependency, no model server, deterministic (ties broken on id) → parity-safe.
+//
+// Honest scope: the discriminating features (centrality / in-degree / resolved-in) are
+// ZERO without --symbol-graph, so on a default index the model degrades to the RRF score
+// + git + node-type and is ≈neutral; its lift is on symbol-graph indexes. Trained offline
+// (bench/train-ranker.mjs) on the benchmark's labelled query→chunk pairs; RRF stays the
+// default. See docs/internals/IMPROVEMENT_LEARNED_RANKER.md for the measured deltas.
+
+/** Feature order — the model's weight vector is keyed by these names. */
+export const RANKER_FEATURES = ['rrf', 'rank', 'centrality', 'in_degree', 'resolved_in', 'git', 'is_def', 'is_test'];
+
+// Node types that are NOT a definition (a re-export / bare expression / import is a weaker hit).
+const NON_DEF_NODE_RE = /expression|call_expression|re_export|_export_statement|import|comment/;
+
+/**
+ * Default shipped model — CONSERVATIVE and RRF-DOMINANT by design. The offline trainer
+ * (bench/train-ranker.mjs) measured that the program-structure features (centrality / resolved
+ * in-degree) carry ~no signal for symbol retrieval on the benchmark — the correct symbol is usually
+ * NOT the most central one (the fit assigns them near-zero weight) — and a fully data-fit model only
+ * TIES RRF on the held-out split (rank-1 0.579 vs 0.579). So the shipped default keeps RRF in charge
+ * (it already
+ * encodes lexical+vector+boosts), adds only a whisper of structure as a tie-breaker, and an is_test
+ * penalty that aligns with the existing demotion. RRF remains the engine default (config.ranker);
+ * this model only runs under the opt-in `--ranker learned`, where it is ≈neutral on the generic
+ * benchmark and exists for users to RETRAIN on their own symbol-graph-rich repo. See
+ * docs/internals/IMPROVEMENT_LEARNED_RANKER.md for the full measured story.
+ */
+export const DEFAULT_RANKER_MODEL = Object.freeze({
+    bias: 0,
+    weights: Object.freeze({
+        rrf: 1.0, rank: 0.30, centrality: 0.04, in_degree: 0.04,
+        resolved_in: 0.04, git: 0.03, is_def: 0.0, is_test: -0.20,
+    }),
+});
+
+/**
+ * Extract the feature vector for one fused candidate. Pure; all backend data arrives through
+ * accessors so memory and SQLite produce identical features (parity).
+ *
+ * @param {{score:number, chunk:object}} result
+ * @param {number} idx  0-based position in the fused pool.
+ * @param {object} ctx  { maxScore, getCentrality?, getInEdges?, gitScoreFor? }
+ */
+export function extractRankerFeatures(result, idx, ctx) {
+    const c = result.chunk || {};
+    const cen = ctx.getCentrality ? ctx.getCentrality(c.id) : null;
+    const inEdges = ctx.getInEdges ? (ctx.getInEdges(c.id) || []) : [];
+    let resolvedIn = 0;
+    for (const e of inEdges) if (e.confidence === 'resolved') resolvedIn++;
+    const nodeType = String(c.node_type || '');
+    return {
+        rrf: ctx.maxScore > 0 ? (result.score || 0) / ctx.maxScore : 0,
+        rank: 1 / (1 + idx),
+        centrality: cen ? cen.score : 0,
+        in_degree: Math.min(inEdges.length / 10, 1),     // squashed into [0,1]
+        resolved_in: Math.min(resolvedIn / 5, 1),
+        git: ctx.gitScoreFor ? (ctx.gitScoreFor(c.file_path) || 0) : 0,
+        is_def: nodeType && !NON_DEF_NODE_RE.test(nodeType) ? 1 : 0,
+        is_test: c.file_path && TEST_FILE_RE.test(c.file_path) ? 1 : 0,
+    };
+}
+
+/** Linear score of a feature vector under a model. */
+export function scoreLearned(features, model = DEFAULT_RANKER_MODEL) {
+    let s = model.bias || 0;
+    const w = model.weights || {};
+    for (const f of RANKER_FEATURES) s += (w[f] || 0) * (features[f] || 0);
+    return s;
+}
+
+/**
+ * Re-rank fused results with the learned model. Returns a NEW array (score replaced by the learned
+ * score), ordered by learned score desc with id tie-break. ≤1 result is returned unchanged.
+ * Deterministic → both backends re-rank identically (parity-safe).
+ *
+ * @param {Array<{score:number, chunk:object}>} results  The fused (RRF) pool, over-fetched.
+ * @param {object} ctx  Accessors: { getCentrality?, getInEdges?, gitScoreFor? }.
+ * @param {object} [model]
+ */
+export function learnedRerank(results, ctx = {}, model = DEFAULT_RANKER_MODEL) {
+    if (!Array.isArray(results) || results.length <= 1) return results;
+    const maxScore = results.reduce((m, r) => Math.max(m, r.score || 0), 0);
+    const fctx = { ...ctx, maxScore };
+    const scored = results.map((r, i) => ({ r, s: scoreLearned(extractRankerFeatures(r, i, fctx), model) }));
+    scored.sort((a, b) => (b.s - a.s) || ((a.r.chunk?.id ?? '') < (b.r.chunk?.id ?? '') ? -1 : 1));
+    return scored.map(({ r, s }) => ({ ...r, score: s }));
+}
+
 // ─── Graph centrality ──────────────────────────────────────────────────────────
 
 /**