graph-indexer 1.2.0 → 2.1.0

package/enrichment.mjs

@@ -58,32 +58,67 @@ export function attachEnrichment(chunk, entry) {
     return Boolean(chunk.summary || chunk.concepts.length);
 }
 
-// Two-line output format optimised for small (1.5B–3B) models:
-//  • SUMMARY  — declarative sentence in developer vocabulary; goes into the vector
-//               embedding as the leading field, aligned with nomic-embed-text's
-//               search_document: training objective.
-//  • TAGS     — comma-separated domain keywords; joined into chunk.hyde so BM25
-//               receives high-IDF concept terms instead of question stopword noise.
-//
-// One-shot example is mandatory for 1.5B models to reliably follow the format.
+// Single-line SUMMARY keeps parseEnrichResponse trivial regardless of model capability.
+// One-shot example is mandatory for small (1.5B) models to follow the format.
+// TAGS → chunk.hyde gives BM25 high-IDF domain terms instead of question stopword noise.
 export const buildEnrichPrompt = (chunk) => {
-    const code = (chunk.code_snippet || '').slice(0, 700);
+    const code = (chunk.code_snippet || '').slice(0, 1000);
     const base = path.basename(chunk.file_path);
-    const ctx = chunk.class_context ? ` (method of class ${chunk.class_context})` : '';
-    const doc = chunk.docstring ? `Doc: ${chunk.docstring.slice(0, 200)}\n` : '';
+    const ctx = chunk.class_context ? ` (member of ${chunk.class_context})` : '';
+    const doc = chunk.docstring ? `Doc: ${chunk.docstring.slice(0, 240)}\n` : '';
     return (
-        `Output exactly two lines for this ${chunk.node_type} "${chunk.name}"${ctx} in ${base}:\n`
-        + `SUMMARY: one sentence describing what it DOES in plain developer vocabulary (the behavior, not the syntax)\n`
-        + `TAGS: 5-8 comma-separated search keywords a developer would type to find this\n\n`
+        `You are indexing source code for semantic search. A developer will search by INTENT\n`
+        + `("where is the code that …", "how does it …") in plain words — NOT by the symbol name.\n\n`
+        + `Describe this ${chunk.node_type} "${chunk.name}"${ctx} in ${base} as exactly two lines:\n`
+        + `SUMMARY: one or two sentences on a SINGLE line, in the vocabulary a developer would\n`
+        + `  search with, covering: WHAT IT DOES and the DOMAIN it acts on; the PROBLEM it solves;\n`
+        + `  its key INPUTS and OUTPUTS; and any notable SIDE EFFECTS (I/O, state mutation, network\n`
+        + `  calls, errors thrown). Use concrete domain nouns and action verbs. Do NOT restate the\n`
+        + `  symbol name and do NOT use filler words like "function", "method", "class", "handles",\n`
+        + `  "manages", or "responsible for".\n`
+        + `TAGS: 5-8 comma-separated domain keywords a developer would type to find this code.\n\n`
         + `Example:\n`
-        + `SUMMARY: validates JWT tokens and refreshes expired authentication sessions\n`
-        + `TAGS: authentication, JWT, token validation, session refresh, middleware\n\n`
+        + `SUMMARY: validates JWT bearer tokens against the signing key and refreshes expired sessions, taking the incoming request's Authorization header and returning the decoded principal, rejecting tampered or expired tokens with a 401 so downstream handlers only ever see authenticated requests\n`
+        + `TAGS: authentication, JWT, token validation, session refresh, middleware, authorization\n\n`
         + doc
         + `Code:\n${code}\n`
         + `Output:`
     );
 };
 
+// Preference ladder for `enrichment.model: "auto"` — pick the strongest code-aware
+// model the local Ollama actually has pulled, falling back to the fast 1.5B floor.
+// Enrichment is offline and cached, so a heavier model here costs nothing at query
+// time; "auto" means "use the best you have" without the user naming it.
+const ENRICH_MODEL_FLOOR = 'qwen2.5-coder:1.5b';
+const ENRICH_MODEL_PREFERENCE = [
+    'qwen2.5-coder:7b', 'qwen2.5-coder:3b', 'deepseek-coder-v2', 'qwen2.5-coder:1.5b',
+    'codellama:13b', 'codellama:7b',
+];
+
+/**
+ * Resolve the enrichment model. A concrete name is returned as-is; "auto" probes
+ * the Ollama model list and returns the strongest available code model (then any
+ * coder/code model, then the 1.5B floor). Best-effort and non-throwing — an
+ * unreachable Ollama yields the floor (enrichment then no-ops gracefully anyway).
+ *
+ * @param {string} model        Configured model, or "auto".
+ * @param {string} ollamaHost
+ * @param {{timeoutMs?:number, fetchImpl?:typeof fetch}} [opts]  fetchImpl injectable for tests.
+ */
+export async function resolveEnrichModel(model, ollamaHost, { timeoutMs = 2000, fetchImpl = fetch } = {}) {
+    if (model && model !== 'auto') return model;
+    try {
+        const res = await fetchImpl(`${ollamaHost}/api/tags`, { signal: AbortSignal.timeout(timeoutMs) });
+        if (!res.ok) return ENRICH_MODEL_FLOOR;
+        const names = ((await res.json()).models || []).map(m => m.name);
+        const has = (p) => names.some(n => n === p || n === `${p}:latest` || n.startsWith(`${p}:`) || n.split(':')[0] === p);
+        for (const pref of ENRICH_MODEL_PREFERENCE) if (has(pref)) return pref;
+        const coder = names.find(n => /coder|code/i.test(n));
+        return coder || ENRICH_MODEL_FLOOR;
+    } catch { return ENRICH_MODEL_FLOOR; }
+}
+
 /**
  * Default generator: a single non-streaming Ollama /api/generate call. Returns the
  * response text, or null on any failure (enrichment is best-effort and never fatal).
@@ -107,11 +142,31 @@ export async function ollamaGenerate(prompt, { model, ollamaHost, timeoutMs = 30
     }
 }
 
+/**
+ * MLX-LM generator: calls a local mlx_lm.server (OpenAI-compatible /v1/completions).
+ * Start the server with: mlx_lm.server --model <model-name> [--port 8080]
+ * Returns the completion text, or null on any failure.
+ */
+export async function mlxLmGenerate(prompt, { mlxLmHost = 'http://localhost:8080', timeoutMs = 60000 } = {}) {
+    try {
+        const res = await fetch(`${mlxLmHost}/v1/completions`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ prompt, max_tokens: 150, temperature: 0.1 }),
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        if (!res.ok) throw new Error(`HTTP ${res.status}`);
+        const data = await res.json();
+        return (data.choices?.[0]?.text || '').trim() || null;
+    } catch {
+        return null;
+    }
+}
+
 /**
  * Parse the SUMMARY + TAGS response into { summary, concepts, hyde }.
  *
- * hyde = concepts.join(' ') — a space-separated keyword string fed to BM25.
- * Concepts are domain terms only (stopwords scrubbed), so every token has
+ * Concepts are domain terms only (stopwords scrubbed) so every token has
  * meaningful IDF weight. Falls back to extracting non-stopword keywords from
  * the summary when the model omits the TAGS line (graceful degradation).
  */
@@ -142,7 +197,7 @@ export function parseEnrichResponse(text) {
 
     if (!summary && lines.length) summary = lines[0].replace(/^SUMMARY:\s*/i, '').trim();
 
-    // Fallback: derive concepts from the summary when TAGS line is absent or empty.
+
     if (concepts.length === 0 && summary) {
         const words = summary.toLowerCase().match(/\b[a-z][a-z-]{2,}\b/g) || [];
         concepts.push(...words.filter(w => !_stop.has(w)).slice(0, 8));
@@ -196,11 +251,19 @@ export function parseRerankResponse(text, n) {
 }
 
 /**
- * Rerank the fused top-M results with a local LLM. Best-effort: any failure
- * (model unreachable, unparseable output) returns the original order.
+ * Rerank the fused top-M results with a local LLM: the judge's order wins outright
+ * for the head, the unjudged tail is preserved. Best-effort — any failure (model
+ * unreachable, unparseable output) returns the original order untouched.
+ *
+ * A reciprocal-rank BLEND of judge-order with retrieval-order was A/B-tested (to
+ * anchor strongly-retrieved hits against judge mistakes) and measured WORSE on
+ * both rank-1 and MRR while not recovering recall@k — so the straight reorder is
+ * what ships. Recall@k is protected upstream instead, by over-fetching a deep pool
+ * before reranking (see mcp/tools.mjs search_code) so the judge reorders real
+ * candidates rather than a thin top_k.
  *
  * @param {string} queryText
- * @param {Array<{score:number, chunk:object}>} results  Fused results (mutated copy returned).
+ * @param {Array<{score:number, chunk:object}>} results  Fused results (copy returned).
  * @param {object} opts
  * @param {(prompt:string)=>Promise<string|null>} opts.generate
  * @param {number} [opts.topM]  How many leading results to rerank (default 8).
@@ -217,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.
  *
@@ -270,9 +428,24 @@ export function selectCoreChunks(chunks, graph, { coreRatio = 1.0, maxChunks = 5
  * @returns {Promise<{enriched:number, attempted:number, cached:number}>}
  */
 export async function enrichCoreChunks(chunks, graph, config, { generate, concurrency, cachePath } = {}) {
-    const { model, coreRatio, maxChunks } = config.enrichment;
+    const { coreRatio, maxChunks } = config.enrichment;
     const ollamaHost = config.ollamaHost;
-    const gen = generate || ((prompt) => ollamaGenerate(prompt, { model, ollamaHost, timeoutMs: 20000 }));
+    const mlxLmHost = config.mlxLmHost;
+    const useMlx = config.llmProvider === 'mlx';
+    // Resolve "auto" → the strongest code model the local Ollama has (1.5B floor).
+    // A pinned generate (tests) skips the network probe — model is only used to
+    // build the default generator and to stamp cache provenance.
+    const model = generate ? config.enrichment.model
+        : (useMlx ? config.enrichment.model : await resolveEnrichModel(config.enrichment.model, ollamaHost));
+    // 60 s timeout: a larger judge model on a busy/CPU-bound local Ollama can take
+    // 10–25 s per generation; the old 20 s cap made every call fail there and aborted
+    // enrichment entirely. Concurrency defaults low for the same reason — parallel
+    // requests to one local model thrash and slow each other (set higher only when
+    // OLLAMA_NUM_PARALLEL and the hardware support it).
+    const gen = generate
+        || (useMlx
+            ? (prompt) => mlxLmGenerate(prompt, { mlxLmHost, timeoutMs: 60000 })
+            : (prompt) => ollamaGenerate(prompt, { model, ollamaHost, timeoutMs: 60000 }));
     const slots = concurrency ?? config.enrichment.concurrency ?? 12;
     const cacheFile = cachePath === false ? null : (cachePath || config.enrichmentCachePath || null);
     const cache = cacheFile ? loadEnrichmentCache(cacheFile) : new Map();
@@ -292,22 +465,21 @@ export async function enrichCoreChunks(chunks, graph, config, { generate, concur
 
     const core = selectCoreChunks(chunks, graph, { coreRatio, maxChunks });
     if (core.length === 0 && cached === 0) {
-        console.log('🧠 LLM enrichment: no core chunks selected (empty graph) — skipping.');
+        console.log('\n   🧠 LLM enrichment: no core chunks selected (empty graph) — skipping.');
         return { enriched: 0, attempted: 0, cached: 0 };
     }
     const pending = core.filter(c => !c.summary && !(c.concepts?.length > 0));
 
     if (pending.length === 0) {
-        console.log(`🧠 LLM enrichment: all ${cached} core chunks served from cache.`);
+        console.log(`\n   🧠 LLM enrichment: all ${cached} core chunks served from cache.`);
         return { enriched: cached, attempted: 0, cached };
     }
 
-    console.log(`🧠 LLM enrichment: ${pending.length} chunks via ${model} (${cached} from cache, concurrency: ${slots}) …`);
+    console.log(`\n   🧠 LLM enrichment: ${pending.length} chunks via ${model} (${cached} from cache, concurrency: ${slots}) …`);
     let enriched = 0, attempted = 0, failures = 0;
     let aborted = false;
 
-    // Sliding-window pool: `slots` workers each drain the queue independently.
-    // No batch boundaries — a worker immediately takes the next item when done.
+
     let cursor = 0;
     async function runWorker() {
         while (cursor < pending.length && !aborted) {
@@ -318,7 +490,7 @@ export async function enrichCoreChunks(chunks, graph, config, { generate, concur
             if (parsed) {
                 chunk.summary = parsed.summary;
                 chunk.concepts = parsed.concepts;
-                chunk.hyde = parsed.hyde;  // = concepts.join(' ') — domain keywords for BM25
+                chunk.hyde = parsed.hyde;
                 if (chunk.content_hash) {
                     cache.set(chunk.content_hash, { summary: parsed.summary, concepts: parsed.concepts, model });
                 }
@@ -327,8 +499,10 @@ export async function enrichCoreChunks(chunks, graph, config, { generate, concur
                 failures++;
             }
             process.stdout.write(`\r   enriched ${enriched}/${pending.length} (failures: ${failures})        `);
-            // Bail early if the model is clearly unreachable.
-            if (attempted >= slots * 2 && enriched === 0) {
+            // Bail early if the model is clearly unreachable. Require a real minimum
+            // of attempts (not just slots×2) so a slow first generation at low
+            // concurrency doesn't abort a perfectly healthy run.
+            if (attempted >= Math.max(8, slots * 2) && enriched === 0) {
                 aborted = true;
                 console.log(`\n⚠️  LLM enrichment: generator unreachable (${failures} failures) — continuing without enrichment.`);
             }

package/git-signals.mjs

@@ -0,0 +1,248 @@
+/**
+ * @file git-signals.mjs
+ * @description Lightweight, air-gapped git-history signals for ranking and
+ *              blast-radius hints. Reads ONLY the local repository's commit log
+ *              (no network, no remote, no code sent anywhere) and derives three
+ *              cheap per-file signals competitors mostly ignore:
+ *
+ *                • churn      — how often a file changes (commit count);
+ *                • recency    — how recently it last changed (last-commit time);
+ *                • co-change  — which files historically change *together* (the
+ *                               "if you touch A you usually touch B" hint that
+ *                               sharpens the refactoring/blast-radius story).
+ *
+ *              Computed once at index time into a sidecar (code-index.git.json),
+ *              kept out of the storage contract and the ranking math: the
+ *              co-change hint is surfaced by the blast-radius tools, and the
+ *              recency/churn boost is applied opt-in in the tool layer (default
+ *              off), so the measured retrieval ranking is unchanged by default.
+ * @author MaquinaTech <https://github.com/MaquinaTech>
+ * @copyright (c) 2026 MaquinaTech. All rights reserved.
+ * @license MIT
+ */
+import { execFileSync } from 'child_process';
+import fs from 'fs';
+import path from 'path';
+
+// Record/field separators chosen to never collide with file paths.
+const REC = '\x01';
+const FS_ = '\x1f';
+
+/**
+ * Collect git signals for a repository from its local commit log.
+ *
+ * Strictly local: shells out to `git log` on `repoRoot` and parses stdout. No
+ * remote is contacted. Returns `null` (a no-op) when the directory is not a git
+ * repo, git is unavailable, or there is no history — callers degrade silently.
+ *
+ * @param {string} repoRoot
+ * @param {object} [opts]
+ * @param {number} [opts.maxCommits=500]       History depth (bounds cost + size).
+ * @param {number} [opts.topCoChange=8]        Co-changed files kept per file.
+ * @param {number} [opts.maxFilesPerCommit=50] Skip sweeping commits (mass renames,
+ *                                              formatting) whose co-change is noise.
+ * @returns {null | {generated:number, commits:number, maxChurn:number,
+ *                    churn:Object<string,number>, lastCommit:Object<string,number>,
+ *                    coChange:Object<string,Array<[string,number]>>}}
+ */
+export function collectGitSignals(repoRoot, { maxCommits = 500, topCoChange = 8, maxFilesPerCommit = 50 } = {}) {
+    // Resolve the actual repo root. If `repoRoot` is a SUBDIRECTORY of a larger
+    // repo (e.g. indexing one package, or a fixture nested in this repo), a bare
+    // `git -C <dir> log` walks UP and returns the PARENT repo's history with
+    // parent-root-relative paths that never match this index's file paths. So we
+    // find the toplevel, scope the log to this subtree, and strip the prefix so
+    // emitted paths are relative to `repoRoot` (matching chunk.file_path).
+    let prefix = '';
+    try {
+        const toplevel = execFileSync('git', ['-C', repoRoot, 'rev-parse', '--show-toplevel'],
+            { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+        if (!toplevel) return null;
+        // Compare REAL paths: git returns the physical toplevel, while repoRoot may
+        // contain symlinks (e.g. macOS /var → /private/var), which would otherwise
+        // produce a bogus prefix.
+        const realTop = (() => { try { return fs.realpathSync(toplevel); } catch { return toplevel; } })();
+        const realRoot = (() => { try { return fs.realpathSync(path.resolve(repoRoot)); } catch { return path.resolve(repoRoot); } })();
+        const rel = path.relative(realTop, realRoot).replace(/\\/g, '/');
+        prefix = rel && rel !== '.' ? rel : '';
+    } catch {
+        return null; // not a git repo / git missing — air-gapped no-op
+    }
+
+    let raw;
+    try {
+        const args = ['-C', repoRoot, 'log', '--no-merges', `-n${maxCommits}`,
+            `--pretty=format:${REC}%H${FS_}%ct`, '--name-only'];
+        if (prefix) args.push('--', '.'); // limit to this subtree (paths stay toplevel-relative)
+        raw = execFileSync('git', args,
+            { encoding: 'utf-8', maxBuffer: 128 * 1024 * 1024, stdio: ['ignore', 'pipe', 'ignore'] });
+    } catch {
+        return null;
+    }
+    if (!raw || !raw.includes(REC)) return null;
+    const stripPrefix = prefix ? prefix + '/' : '';
+
+    const churn = Object.create(null);
+    const lastCommit = Object.create(null);
+    const pairCounts = new Map(); // file → Map<coFile, count>
+    let commits = 0;
+
+    const bump = (f, ts) => {
+        churn[f] = (churn[f] || 0) + 1;
+        if (ts > (lastCommit[f] || 0)) lastCommit[f] = ts;
+    };
+
+    for (const block of raw.split(REC)) {
+        if (!block) continue;
+        const nl = block.indexOf('\n');
+        const header = nl === -1 ? block : block.slice(0, nl);
+        const ts = parseInt(header.split(FS_)[1], 10);
+        if (!Number.isFinite(ts)) continue;
+        commits++;
+
+        const files = [];
+        if (nl !== -1) {
+            for (const line of block.slice(nl + 1).split('\n')) {
+                let f = line.trim();
+                if (!f) continue;
+                // git quotes paths with unusual chars: "src/é.ts" — unwrap.
+                if (f.startsWith('"') && f.endsWith('"')) f = f.slice(1, -1);
+                if (stripPrefix) {
+                    if (!f.startsWith(stripPrefix)) continue; // outside the indexed subtree
+                    f = f.slice(stripPrefix.length);
+                }
+                files.push(f);
+            }
+        }
+        for (const f of files) bump(f, ts);
+
+        // Co-change: only for focused commits — a 400-file sweep links nothing useful.
+        if (files.length >= 2 && files.length <= maxFilesPerCommit) {
+            for (let i = 0; i < files.length; i++) {
+                const a = files[i];
+                let row = pairCounts.get(a);
+                if (!row) { row = new Map(); pairCounts.set(a, row); }
+                for (let j = 0; j < files.length; j++) {
+                    if (i === j) continue;
+                    const b = files[j];
+                    row.set(b, (row.get(b) || 0) + 1);
+                }
+            }
+        }
+    }
+
+    if (commits === 0) return null;
+
+    // Stamp HEAD so clients can report "indexed at commit X" and detect drift
+    // (the freshness contract). Best-effort — absence just omits the commit.
+    let head = null;
+    try {
+        head = execFileSync('git', ['-C', repoRoot, 'rev-parse', '--short', 'HEAD'],
+            { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] }).trim() || null;
+    } catch { /* detached/empty — no stamp */ }
+
+    const coChange = Object.create(null);
+    for (const [file, row] of pairCounts) {
+        const top = [...row.entries()]
+            .sort((x, y) => y[1] - x[1] || x[0].localeCompare(y[0]))
+            .slice(0, topCoChange);
+        if (top.length) coChange[file] = top;
+    }
+
+    let maxChurn = 1;
+    for (const k in churn) if (churn[k] > maxChurn) maxChurn = churn[k];
+
+    return { generated: Math.floor(Date.now() / 1000), head, commits, maxChurn, churn, lastCommit, coChange };
+}
+
+/** Persist signals next to the index (best-effort). */
+export function writeGitSignals(filePath, signals) {
+    try { fs.writeFileSync(filePath, JSON.stringify(signals)); return true; }
+    catch { return false; }
+}
+
+/** Load a signals sidecar, or null if absent/corrupt. */
+export function loadGitSignals(filePath) {
+    try { return JSON.parse(fs.readFileSync(filePath, 'utf-8')); }
+    catch { return null; }
+}
+
+/** Files that historically change together with `file`, strongest first. */
+export function coChangesFor(signals, file, limit = 5) {
+    if (!signals || !signals.coChange) return [];
+    const row = signals.coChange[file];
+    if (!row) return [];
+    return row.slice(0, limit).map(([f, count]) => ({ file: f, count }));
+}
+
+// ─── Index freshness (query-time drift detection) ────────────────────────────
+// The blast-radius tools are only trustworthy if the index reflects the working
+// tree. We surface a compact freshness signal on tool responses: index age, the
+// commit it was built at (stamped above), and whether the tree has drifted since.
+// The git read is cheap and cached briefly so a burst of tool calls costs one
+// `git status`; it degrades silently (null) outside a git repo.
+
+const _SRC_RE = /\.(js|jsx|mjs|cjs|ts|tsx|py|go|rs|java|kt|cs|rb|php|swift|c|h|cc|cpp|hpp|scss|css|sh|bash)$/i;
+let _gitStateCache = null; // { at, root, head, dirtyCount }
+
+/** Reset the cached working-tree state (tests). */
+export function _resetGitStateCache() { _gitStateCache = null; }
+
+/**
+ * Cheap, cached working-tree state: current short HEAD + count of changed SOURCE
+ * files (uncommitted). Cached `ttlMs` per root so a burst of tool calls shells out
+ * at most once. `exec`/`nowMs` injectable for tests. Returns {head:null,dirtyCount:null}
+ * outside a git repo.
+ */
+export function currentGitState(repoRoot, { ttlMs = 5000, nowMs = Date.now(), exec = execFileSync } = {}) {
+    if (_gitStateCache && _gitStateCache.root === repoRoot && (nowMs - _gitStateCache.at) < ttlMs) return _gitStateCache;
+    let head = null, dirtyCount = null;
+    try {
+        head = exec('git', ['-C', repoRoot, 'rev-parse', '--short', 'HEAD'],
+            { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] }).trim() || null;
+        const status = exec('git', ['-C', repoRoot, 'status', '--porcelain'],
+            { encoding: 'utf-8', maxBuffer: 16 * 1024 * 1024, stdio: ['ignore', 'pipe', 'ignore'] });
+        dirtyCount = status.split('\n').filter(l => l.trim() && _SRC_RE.test(l)).length;
+    } catch { /* not a git repo / git missing → unknown */ }
+    _gitStateCache = { at: nowMs, root: repoRoot, head, dirtyCount };
+    return _gitStateCache;
+}
+
+/**
+ * Derive the freshness verdict from index age + the stamped index commit + the
+ * current working-tree state + whether the watch daemon is live. Pure (no I/O) so
+ * it is trivially testable.
+ *
+ * @returns {{ageSeconds:number|null, ageLabel:string, indexedCommit:string|null,
+ *            currentCommit:string|null, pendingChanges:number|null, commitMoved:boolean,
+ *            daemonRunning:boolean, stale:boolean, syncing:boolean}}
+ */
+export function computeFreshness({ ageSeconds = null, indexedCommit = null, current = null, daemonRunning = false } = {}) {
+    const ageLabel = ageSeconds == null ? 'unknown'
+        : ageSeconds < 60 ? `${ageSeconds}s` : ageSeconds < 3600 ? `${Math.floor(ageSeconds / 60)}m` : `${Math.floor(ageSeconds / 3600)}h`;
+    const currentCommit = current?.head ?? null;
+    const pendingChanges = current?.dirtyCount ?? null;
+    const commitMoved = Boolean(indexedCommit && currentCommit && indexedCommit !== currentCommit);
+    const hasPending = (pendingChanges != null && pendingChanges > 0) || commitMoved;
+    // A live daemon syncs changes incrementally, so pending work is "syncing", not
+    // "stale". Only when no daemon is keeping the index fresh is drift truly stale.
+    return {
+        ageSeconds, ageLabel, indexedCommit, currentCommit, pendingChanges, commitMoved,
+        daemonRunning, stale: hasPending && !daemonRunning, syncing: hasPending && daemonRunning,
+    };
+}
+
+/**
+ * A bounded 0..1 "this file is hot" score combining recency and churn, for the
+ * OPT-IN ranking boost only. Returns 0 when there is no signal for the file, so a
+ * disabled or signal-less repo never perturbs ranking.
+ */
+export function gitBoostScore(signals, file, nowSec = Date.now() / 1000) {
+    if (!signals) return 0;
+    const churn = (signals.churn && signals.churn[file]) || 0;
+    const last = (signals.lastCommit && signals.lastCommit[file]) || 0;
+    if (!churn && !last) return 0;
+    const ageDays = last ? Math.max(0, (nowSec - last) / 86400) : 3650;
+    const recency = Math.exp(-ageDays / 90);                                   // ~quarter half-life
+    const churnScore = Math.log1p(churn) / Math.log1p(signals.maxChurn || 1);  // 0..1
+    return 0.5 * recency + 0.5 * churnScore;
+}