graph-indexer 1.2.0 → 2.0.0

package/{sqlite-store.mjs → engine/sqlite.mjs}

@@ -1,5 +1,5 @@
 /**
- * @file sqlite-store.mjs
+ * @file engine/sqlite.mjs
  * @description Disk-backed graph store for enterprise-scale monorepos. Implements
  *              the same read contract as MemoryGraphIndex (see storage.mjs) over
  *              `node:sqlite` — built into Node, so this adds ZERO dependencies.
@@ -28,19 +28,20 @@
 import fs from 'fs';
 import {
     tokenize, okapiIdf, bm25Score, fuseAndRank, buildLexicalDocument, embeddingKeyFor,
-    SUMMARY_VEC_SUFFIX, LEXICAL_FUSION_CAP, VECTOR_SCAN_RAW_N, finalizeVectorCandidates,
-} from './search-core.mjs';
+    LEXICAL_FUSION_CAP, VECTOR_SCAN_RAW_N, finalizeVectorCandidates,
+    isNaturalLanguageQuery, baseEmbeddingKey,
+} from '../search-core.mjs';
 import {
     writeEmbeddingBinary, appendEmbeddingBinary, scanEmbeddingBinary,
-    updateVectorSketch, searchVectorSketch,
-} from './core-engine.mjs';
+    updateVectorSketch, searchVectorSketch, SKETCH_THRESHOLD,
+} from './binary.mjs';
 
 // node:sqlite is loaded lazily so the default in-memory path never requires it.
 let DatabaseSync = null;
 try { ({ DatabaseSync } = await import('node:sqlite')); } catch { /* reported in ctor */ }
 
-const SKETCH_THRESHOLD   = 10000; // build the binary sketch above this many vectors.
-                                  // Below it the exact streaming scan stays under ~20 ms
+// SKETCH_THRESHOLD (shared with the memory store via binary.mjs) — build the binary
+// sketch above this many vectors. Below it the exact streaming scan stays under ~20 ms
                                   // AND both backends rank identically (the sketch is
                                   // approximate in the candidate tail); above it the
                                   // sketch caps latency at ~5–15 ms regardless of size.
@@ -53,12 +54,23 @@ CREATE TABLE IF NOT EXISTS chunks (
   start_line INTEGER, end_line INTEGER,
   calls TEXT, params TEXT, return_type TEXT, class_context TEXT,
   type_refs TEXT, decorators TEXT, extends_ TEXT, hyde TEXT, summary TEXT, concepts TEXT,
-  doc_len INTEGER, path_tokens TEXT, vec_key TEXT, vec_offset INTEGER, vec_dim INTEGER
+  doc_len INTEGER, path_tokens TEXT, vec_key TEXT, vec_offset INTEGER, vec_dim INTEGER,
+  call_sites TEXT
 );
 CREATE TABLE IF NOT EXISTS postings (term TEXT, chunk_id TEXT, tf INTEGER);
 CREATE TABLE IF NOT EXISTS terms (term TEXT PRIMARY KEY, df INTEGER);
 CREATE TABLE IF NOT EXISTS call_edges (callee TEXT, chunk_id TEXT);
 CREATE TABLE IF NOT EXISTS deps (file TEXT, dep TEXT);
+CREATE TABLE IF NOT EXISTS routes (
+  id INTEGER PRIMARY KEY,
+  method TEXT NOT NULL,
+  path TEXT NOT NULL,
+  handler_name TEXT,
+  handler_chunk_id TEXT,
+  file_path TEXT NOT NULL,
+  line INTEGER,
+  framework TEXT
+);
 `;
 
 const SCHEMA_INDEXES = `
@@ -71,13 +83,16 @@ CREATE INDEX IF NOT EXISTS idx_postings_chunk ON postings(chunk_id);
 CREATE INDEX IF NOT EXISTS idx_calledges_callee ON call_edges(callee);
 CREATE INDEX IF NOT EXISTS idx_deps_file ON deps(file);
 CREATE INDEX IF NOT EXISTS idx_deps_dep ON deps(dep);
+CREATE INDEX IF NOT EXISTS idx_routes_method ON routes(method);
+CREATE INDEX IF NOT EXISTS idx_routes_path ON routes(path);
+CREATE INDEX IF NOT EXISTS idx_routes_handler ON routes(handler_chunk_id);
 `;
 
 const CHUNK_COLS = [
     'id', 'file_path', 'node_type', 'name', 'name_lower', 'docstring', 'code_snippet',
     'content_hash', 'start_line', 'end_line', 'calls', 'params', 'return_type',
     'class_context', 'type_refs', 'decorators', 'extends_', 'hyde', 'summary', 'concepts',
-    'doc_len', 'path_tokens', 'vec_key', 'vec_offset', 'vec_dim',
+    'doc_len', 'path_tokens', 'vec_key', 'vec_offset', 'vec_dim', 'call_sites',
 ];
 
 function jsonArr(v) { return JSON.stringify(Array.isArray(v) ? v : []); }
@@ -145,9 +160,19 @@ export class SqliteGraphStore {
                 // Pre-enrichment-key indexes stored vectors under the plain content hash.
                 this.db.exec('UPDATE chunks SET vec_key = content_hash WHERE vec_key IS NULL');
             } catch { /* exists */ }
+            // Receiver-aware call graph (precise get_call_graph) landed later; older
+            // indexes lack the column. NULL → callers fall back to name-only grouping.
+            try { this.db.exec('ALTER TABLE chunks ADD COLUMN call_sites TEXT DEFAULT NULL'); } catch { /* exists */ }
         }
         this.db.exec(SCHEMA_INDEXES);
         this._reloadMeta();
+        // Does this corpus carry LLM enrichment? One cheap probe → drives the NL
+        // vector-channel weight in fuseAndRank (parity with the in-memory engine).
+        try {
+            this._corpusEnriched = Boolean(
+                this.db.prepare("SELECT 1 FROM chunks WHERE summary IS NOT NULL AND summary != '' LIMIT 1").get()
+            );
+        } catch { this._corpusEnriched = false; }
         this._loadGraph();
         this._openVecFd();
         this._refreshSketch();
@@ -259,6 +284,12 @@ export class SqliteGraphStore {
         this._stmtCallers   = this.db.prepare(
             'SELECT c.* FROM chunks c JOIN call_edges e ON e.chunk_id = c.id WHERE e.callee = ?'
         );
+        // type_refs / extends_ are JSON arrays of names. LIKE is a cheap prefilter
+        // (ASCII case-insensitive in SQLite); findReferers() verifies exact, quoted
+        // membership in JS so e.g. "User" never matches "UserProfile".
+        this._stmtReferers  = this.db.prepare(
+            'SELECT * FROM chunks WHERE type_refs LIKE ? ESCAPE \'\\\' OR extends_ LIKE ? ESCAPE \'\\\''
+        );
         this._stmtPosting   = this.db.prepare(
             'SELECT p.chunk_id AS id, p.tf AS tf, c.doc_len AS doc_len '
             + 'FROM postings p JOIN chunks c ON c.id = p.chunk_id WHERE p.term = ?'
@@ -269,6 +300,12 @@ export class SqliteGraphStore {
         // ids in a deterministic order keeps both backends rank-identical on ties.
         this._stmtIdsByKey  = this.db.prepare('SELECT id FROM chunks WHERE vec_key = ? ORDER BY id');
         this._stmtIdsByHash = this.db.prepare('SELECT id FROM chunks WHERE content_hash = ? ORDER BY id');
+        // ORDER BY id (rowid = insertion order) keeps routes in index-build order,
+        // matching the in-memory graph.routes array order for cross-backend parity.
+        this._stmtRoutes    = this.db.prepare(
+            'SELECT method, path, handler_name, handler_chunk_id, file_path, line, framework '
+            + 'FROM routes ORDER BY id'
+        );
     }
 
     _prepareWrite() {
@@ -312,7 +349,7 @@ export class SqliteGraphStore {
             return_type: row.return_type || '', class_context: row.class_context || '',
             type_refs: parseArr(row.type_refs), decorators: parseArr(row.decorators),
             extends: parseArr(row.extends_), hyde: row.hyde || '', summary: row.summary || '',
-            concepts: parseArr(row.concepts),
+            concepts: parseArr(row.concepts), call_sites: parseArr(row.call_sites),
         };
     }
 
@@ -330,6 +367,52 @@ export class SqliteGraphStore {
 
     findCallers(funcName) { return this._stmtCallers.all(funcName).map(r => this._rowToChunk(r)); }
 
+    findReferers(symbol) {
+        const key = String(symbol).toLowerCase().trim();
+        if (!key) return [];
+        // Escape LIKE metacharacters in the symbol, then bracket with JSON quotes so
+        // the prefilter only fires on a whole array element.
+        const esc = key.replace(/[\\%_]/g, m => '\\' + m);
+        const pat = `%"${esc}"%`;
+        const out = [];
+        for (const row of this._stmtReferers.all(pat, pat)) {
+            const c = this._rowToChunk(row);
+            // A class/type lists its own name in type_refs — that self-mention is a
+            // definition, not a reference; skip it.
+            if (c.name && c.name.toLowerCase() === key) continue;
+            const hit = c.type_refs.some(t => t.toLowerCase() === key)
+                || c.extends.some(t => t.toLowerCase() === key);
+            if (hit) out.push(c);
+        }
+        return out;
+    }
+
+    /**
+     * HTTP routes filtered by method and/or path prefix, each augmented with its
+     * resolved handler chunk (`chunk`, or null). Filtering logic is byte-identical
+     * to MemoryGraphIndex.findRoutes; rows arrive in index-build order (ORDER BY id)
+     * so both backends return identical records. An index built before this feature
+     * (empty routes table) yields [].
+     * @returns {object[]}
+     */
+    findRoutes({ method = null, pathPrefix = null } = {}) {
+        this._maybeRefresh();
+        const m = method ? String(method).toUpperCase().trim() : null;
+        const p = pathPrefix ? String(pathPrefix).toLowerCase() : null;
+        const out = [];
+        for (const r of this._stmtRoutes.all()) {
+            if (m && String(r.method || '').toUpperCase() !== m) continue;
+            if (p && !String(r.path || '').toLowerCase().startsWith(p)) continue;
+            const chunk = r.handler_chunk_id ? this.getChunk(r.handler_chunk_id) : null;
+            out.push({
+                method: r.method, path: r.path, handler_name: r.handler_name,
+                handler_chunk_id: r.handler_chunk_id, file_path: r.file_path,
+                line: r.line, framework: r.framework, chunk,
+            });
+        }
+        return out;
+    }
+
     *iterateChunks() {
         // Stream rows via a cursor so repo-map / call-graph passes never materialise
         // the whole table. Falls back to paging if .iterate() is unavailable.
@@ -408,8 +491,9 @@ export class SqliteGraphStore {
     searchHybrid(queryText, queryVector, topK = 5, minScore = 0.3, exactBoostName = null) {
         this._maybeRefresh();
 
-        // 1. Lexical BM25 over posting lists (one indexed lookup per query term).
-        const qTokens = tokenize(queryText);
+        // Asymmetric stemming: stem only for natural-language queries so symbolic
+        // lookups stay exact — mirrors the in-memory engine for parity.
+        const qTokens = tokenize(queryText, isNaturalLanguageQuery(queryText));
         const occ = new Map();
         for (const t of qTokens) occ.set(t, (occ.get(t) || 0) + 1);
 
@@ -429,10 +513,9 @@ export class SqliteGraphStore {
             .slice(0, LEXICAL_FUSION_CAP)
             .map(([id, score], i) => ({ id, score, rank: i + 1 }));
 
-        // 2. Vector channel: stream the FULL embeddings bin (bounded buffers) so a
-        //    conceptual query that shares no tokens with the code can still match.
-        //    The old design scored only lexical candidates, which silently turned
-        //    semantic search off exactly where it was needed.
+        // Stream the FULL embeddings bin (bounded buffers) so conceptual queries
+        // that share no tokens with the code can still match — scoring only lexical
+        // candidates silently disabled semantic search where it mattered most.
         let vectorResults = [];
         if (queryVector && this._vecFd >= 0) {
             // Binary sketch above SKETCH_THRESHOLD (Hamming prefilter + exact
@@ -446,9 +529,9 @@ export class SqliteGraphStore {
                 });
             const entries = [];
             for (const { key, score } of hits) {
-                // Summary-only vectors live under `<key>|s` — fold onto the chunk.
-                const baseKey = key.endsWith(SUMMARY_VEC_SUFFIX)
-                    ? key.slice(0, -SUMMARY_VEC_SUFFIX.length) : key;
+                // Summary-only (`<key>|s`) and per-window (`<key>|wN`) vectors fold onto
+                // the chunk; finalizeVectorCandidates keeps the max-sim score per chunk.
+                const baseKey = baseEmbeddingKey(key);
                 let rows = this._stmtIdsByKey.all(baseKey);
                 if (rows.length === 0) rows = this._stmtIdsByHash.all(baseKey); // legacy bins
                 for (const { id } of rows) entries.push({ id, score });
@@ -456,9 +539,6 @@ export class SqliteGraphStore {
             vectorResults = finalizeVectorCandidates(entries);
         }
 
-        // 3. Fetch candidate rows ONCE (transient, bounded by the caps above), then
-        //    fuse + boost with the shared ranker. getChunk lazy-fetches stragglers
-        //    (e.g. exact-boost ids) and caches them for the duration of the call.
         const rowCache = new Map();
         const fetchRow = (id) => {
             if (rowCache.has(id)) return rowCache.get(id);
@@ -496,6 +576,7 @@ export class SqliteGraphStore {
         return fuseAndRank({
             lexicalResults, vectorResults, getChunk, getPathTokens, getDf,
             docCount: this._docCount, rrfK: this.rrfK, topK, queryText, exactBoostName,
+            corpusEnriched: this._corpusEnriched,
             resolveExact: (term) => this._stmtIdByName.all(term).map(r => r.id),
         });
     }
@@ -509,8 +590,9 @@ export class SqliteGraphStore {
 
     /** Internal: index one chunk's lexical document + row + call edges. */
     _insertChunk(chunk, imports, vecEntry) {
-        const tokens = tokenize(buildLexicalDocument(chunk, imports));
-        const docLen = tokens.length;
+        const doc = buildLexicalDocument(chunk, imports);
+        const tokens = tokenize(doc);                       // raw + additive stems
+        const docLen = tokenize(doc, false).length;          // raw-only length for BM25 avgdl (parity w/ memory engine)
 
         const termCounts = new Map();
         for (const t of tokens) termCounts.set(t, (termCounts.get(t) || 0) + 1);
@@ -519,7 +601,7 @@ export class SqliteGraphStore {
             this._stmtInsPost.run(term, chunk.id, cnt);
         }
 
-        const pathTokens = Array.from(new Set(tokenize(chunk.file_path.replace(/[/\-_.]/g, ' '))));
+        const pathTokens = Array.from(new Set(tokenize(chunk.file_path.replace(/[/\-_.]/g, ' '), false)));
         this._stmtInsChunk.run(
             chunk.id, chunk.file_path, chunk.node_type ?? null, chunk.name ?? null,
             nameLowerOf(chunk.name), chunk.docstring ?? '', chunk.code_snippet ?? '',
@@ -529,7 +611,8 @@ export class SqliteGraphStore {
             jsonArr(chunk.extends), chunk.hyde ?? null, chunk.summary ?? null, jsonArr(chunk.concepts),
             docLen, JSON.stringify(pathTokens),
             chunk.content_hash ? embeddingKeyFor(chunk) : null,
-            vecEntry ? vecEntry.offset : -1, vecEntry ? vecEntry.dim : 0
+            vecEntry ? vecEntry.offset : -1, vecEntry ? vecEntry.dim : 0,
+            jsonArr(chunk.call_sites)
         );
         for (const callee of (chunk.calls || [])) this._stmtInsEdge.run(callee, chunk.id);
         return docLen;
@@ -557,8 +640,8 @@ export class SqliteGraphStore {
         this._prepareWrite();
         this._maybeRefresh();
 
-        // 1. Append new vectors first — orphan bytes on a failed commit are
-        //    harmless and compacted away by the next full index run.
+        // Append new vectors first — orphan bytes on a failed commit are harmless
+        // and compacted away by the next full index run.
         let appended = new Map();
         const embCount = embeddings ? (embeddings instanceof Map ? embeddings.size : Object.keys(embeddings).length) : 0;
         if (embCount > 0) {
@@ -574,8 +657,8 @@ export class SqliteGraphStore {
 
         this.db.exec('BEGIN');
         try {
-            // 2. Capture reusable vector offsets for incoming chunks BEFORE the
-            //    file's old rows (which may hold those offsets) are deleted.
+            // Capture reusable vector offsets BEFORE deleting old rows, which may
+            // be the only rows that hold those offsets.
             const reuse = new Map();
             for (const chunk of chunks) {
                 if (!chunk.content_hash) continue;
@@ -585,7 +668,6 @@ export class SqliteGraphStore {
                 if (row) reuse.set(key, { offset: row.vec_offset, dim: row.vec_dim });
             }
 
-            // 3. Remove the file's old rows with exact BM25 bookkeeping.
             let docCount = this._docCount;
             let totalDocLen = this._totalDocLen;
             for (const row of this._stmtByFile.all(filePath)) {
@@ -599,7 +681,6 @@ export class SqliteGraphStore {
                 docCount--;
             }
 
-            // 4. Insert the new chunks.
             for (const chunk of chunks) {
                 const key = chunk.content_hash ? embeddingKeyFor(chunk) : null;
                 const vecEntry = key ? (appended.get(key) ?? reuse.get(key) ?? null) : null;
@@ -608,7 +689,6 @@ export class SqliteGraphStore {
             }
             this._stmtPruneTerms.run();
 
-            // 5. Dependency edges + meta.
             this._stmtDelDeps.run(filePath);
             if (!imports || imports.length === 0) this._stmtInsDep.run(filePath, null);
             else for (const d of imports) this._stmtInsDep.run(filePath, d);
@@ -629,7 +709,6 @@ export class SqliteGraphStore {
             throw err;
         }
 
-        // 6. Mirror the in-RAM dependency graph (same shape as updateFileGraph).
         const oldDeps = this._graph.dependencies[filePath] || [];
         for (const oldDep of oldDeps) {
             if (this._graph.importedBy[oldDep]) {
@@ -672,9 +751,8 @@ export class SqliteGraphStore {
      */
     buildFrom({ chunks, graph, embeddingCache }) {
         this._open();
-        this.db.exec('PRAGMA synchronous = OFF;'); // fast bulk load; rebuilt artifact
+        this.db.exec('PRAGMA synchronous = OFF;'); // safe only for a full rebuild; not used for incremental writes
 
-        // Write the embedding binary and derive each key's float offset.
         const offsets = new Map();
         let dim = 0;
         const cacheSize = embeddingCache instanceof Map ? embeddingCache.size : Object.keys(embeddingCache || {}).length;
@@ -697,12 +775,13 @@ export class SqliteGraphStore {
         let totalDocLen = 0, docCount = 0;
 
         this.db.exec('BEGIN');
-        // Fresh build — drop any prior content (inside the txn: readers keep the
-        // old index until COMMIT, instead of briefly seeing empty tables).
+        // Drop inside the transaction so concurrent readers see the old index
+        // until COMMIT, never briefly-empty tables.
         this.db.exec(`
             DROP TABLE IF EXISTS chunks; DROP TABLE IF EXISTS postings;
             DROP TABLE IF EXISTS terms;  DROP TABLE IF EXISTS call_edges;
             DROP TABLE IF EXISTS deps;   DROP TABLE IF EXISTS meta;
+            DROP TABLE IF EXISTS routes;
         `);
         this.db.exec(SCHEMA_TABLES);
         this.db.exec(SCHEMA_INDEXES);
@@ -716,8 +795,9 @@ export class SqliteGraphStore {
 
         for (const chunk of chunks) {
             const deps = (graph?.dependencies?.[chunk.file_path]) || [];
-            const tokens = tokenize(buildLexicalDocument(chunk, deps));
-            const docLen = tokens.length;
+            const doc = buildLexicalDocument(chunk, deps);
+            const tokens = tokenize(doc);                       // raw + additive stems
+            const docLen = tokenize(doc, false).length;          // raw-only length for BM25 avgdl (parity w/ memory engine)
             totalDocLen += docLen; docCount++;
 
             const termCounts = new Map();
@@ -727,7 +807,7 @@ export class SqliteGraphStore {
                 insPost.run(term, chunk.id, cnt);
             }
 
-            const pathTokens = Array.from(new Set(tokenize(chunk.file_path.replace(/[/\-_.]/g, ' '))));
+            const pathTokens = Array.from(new Set(tokenize(chunk.file_path.replace(/[/\-_.]/g, ' '), false)));
             const vecKey = chunk.content_hash ? embeddingKeyFor(chunk) : null;
             const vec = vecKey ? (offsets.get(vecKey) ?? offsets.get(chunk.content_hash)) : null;
 
@@ -739,7 +819,8 @@ export class SqliteGraphStore {
                 chunk.class_context ?? '', jsonArr(chunk.type_refs), jsonArr(chunk.decorators),
                 jsonArr(chunk.extends), chunk.hyde ?? null, chunk.summary ?? null, jsonArr(chunk.concepts),
                 docLen, JSON.stringify(pathTokens), vecKey,
-                vec ? vec.offset : -1, vec ? vec.dim : 0
+                vec ? vec.offset : -1, vec ? vec.dim : 0,
+                jsonArr(chunk.call_sites)
             );
             for (const callee of (chunk.calls || [])) insEdge.run(callee, chunk.id);
         }
@@ -753,6 +834,20 @@ export class SqliteGraphStore {
             else for (const d of list) insDep.run(file, d);
         }
 
+        // Inserted in array order so the autoincrement id mirrors the in-memory
+        // graph.routes order, keeping both backends rank-identical.
+        const insRoute = this.db.prepare(
+            'INSERT INTO routes (method, path, handler_name, handler_chunk_id, file_path, line, framework) '
+            + 'VALUES (?, ?, ?, ?, ?, ?, ?)'
+        );
+        for (const r of (graph?.routes || [])) {
+            insRoute.run(
+                String(r.method || ''), String(r.path ?? ''), r.handler_name ?? null,
+                r.handler_chunk_id ?? null, String(r.file_path || ''),
+                r.line ?? null, r.framework ?? null
+            );
+        }
+
         const insMeta = this.db.prepare('INSERT OR REPLACE INTO meta (key, value) VALUES (?, ?)');
         insMeta.run('doc_count', String(docCount));
         insMeta.run('total_doc_len', String(totalDocLen));

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).
@@ -270,9 +333,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 +370,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 +395,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 +404,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.`);
             }