md-semantic-search 1.1.0 → 2.0.0

package/dist/rag.js

@@ -3,6 +3,7 @@ import path from 'node:path';
 import crypto from 'node:crypto';
 import { searchIndex, loadIndex } from './search.js';
 import { tokenize } from './lexical.js';
+import { resolveChatProvider } from './providers.js';
 export const DEFAULT_RAG_SYSTEM_PROMPT = 'You are a helpful assistant answering questions using only the provided Markdown notes. ' +
     'Always cite your sources using [file#heading] format. ' +
     'If the context does not contain the answer, say that the notes do not have enough information.';
@@ -12,10 +13,21 @@ export const DEFAULT_RAG_SYSTEM_PROMPT = 'You are a helpful assistant answering
 export function getSessionsDir(indexDir) {
     return path.join(indexDir, 'sessions');
 }
+const SESSION_ID_PATTERN = /^[a-zA-Z0-9_-]{1,64}$/;
+/**
+ * Validates a session id before it is used as a filesystem path component.
+ */
+export function assertSafeSessionId(id) {
+    if (!SESSION_ID_PATTERN.test(id)) {
+        throw new Error('Invalid session ID: expected 1-64 letters, numbers, hyphens, or underscores');
+    }
+    return id;
+}
 /**
  * Atomically saves a ChatSession to disk (<indexDir>/sessions/<id>.json).
  */
 export function saveChatSession(indexDir, session) {
+    assertSafeSessionId(session.id);
     const dir = getSessionsDir(indexDir);
     fs.mkdirSync(dir, { recursive: true });
     const targetPath = path.join(dir, `${session.id}.json`);
@@ -28,6 +40,7 @@ export function saveChatSession(indexDir, session) {
  * Loads a ChatSession by id or creates a new one. Degrades safely if corrupt.
  */
 export function loadChatSession(indexDir, id, log = () => { }) {
+    assertSafeSessionId(id);
     const sessionPath = path.join(getSessionsDir(indexDir), `${id}.json`);
     if (fs.existsSync(sessionPath)) {
         try {
@@ -128,6 +141,56 @@ export function extractAnswerFallback(query, passages) {
     const body = selected.map((s) => `${s.sentence} ${s.citation}`).join('\n\n');
     return `Based on your notes:\n\n${body}`;
 }
+const CITATION_MENTION_RE = /\[([^\]\n]{1,200})\]/g;
+/** `[file]` | `[file#heading]` | `[file › heading]` → {file, heading?}; null for non-citations. */
+function parseCitationMention(text) {
+    const t = text.trim();
+    if (!t)
+        return null;
+    let file;
+    let heading;
+    const hash = t.indexOf('#');
+    const sep = t.indexOf('›');
+    if (hash > 0) {
+        file = t.slice(0, hash).trim();
+        heading = t.slice(hash + 1).trim();
+    }
+    else if (sep > 0) {
+        file = t.slice(0, sep).trim();
+        heading = t.slice(sep + 1).trim();
+    }
+    else {
+        file = t;
+    }
+    // markdown links, footnote refs, and empty brackets are not citations
+    if (!file || /https?:\/\//i.test(file))
+        return null;
+    return { file, heading: heading || undefined };
+}
+/**
+ * issue #199 follow-up: which of the retrieved citations the answer text
+ * actually cites. Bracket-only scan (the exact formats the system prompt and
+ * the extractive fallback emit), exact file/heading match against the
+ * retrieval manifest, order of first mention. No mention → [].
+ */
+export function extractUsedCitations(answer, citations) {
+    const used = [];
+    const seen = new Set();
+    for (const m of answer.matchAll(CITATION_MENTION_RE)) {
+        const mention = parseCitationMention(m[1]);
+        if (!mention)
+            continue;
+        const hit = citations.find((c) => c.file === mention.file && (mention.heading === undefined || c.heading === mention.heading));
+        if (!hit)
+            continue;
+        const key = `${hit.file}\u0000${hit.heading ?? ''}`;
+        if (!seen.has(key)) {
+            seen.add(key);
+            used.push(hit);
+        }
+    }
+    return used;
+}
 /**
  * Synthesizes an answer from retrieved passages using an LLM or fallback.
  */
@@ -137,55 +200,77 @@ export async function synthesizeAnswer(query, passages, options = {}) {
         heading: p.heading,
         score: p.score,
     }));
+    // One prompt assembly for every stage: `system + user` reproduces the
+    // historical single-string prompt byte-for-byte; the split serves the
+    // structured transports (MCP sampling, issue #197).
+    const system = options.systemPrompt || DEFAULT_RAG_SYSTEM_PROMPT;
     const historyHeader = options.conversationHistory ? `\nConversation History:\n${options.conversationHistory}\n` : '';
+    const contextBlocks = passages
+        .map((p, i) => {
+        const header = p.heading ? `${p.file} › ${p.heading}` : p.file;
+        return `[Source ${i + 1}: ${header}]\n${p.snippet}`;
+    })
+        .join('\n\n---\n\n');
+    const user = `${historyHeader}\n\nContext:\n${contextBlocks}\n\nQuestion: ${query}\n\nAnswer:`;
+    // every stage returns through one shape so citationsUsed stays consistent
+    const finish = (answer, mode) => ({
+        answer,
+        citations,
+        citationsUsed: extractUsedCitations(answer, citations),
+        passages,
+        mode,
+    });
+    // issue #197: structured hook (MCP sampling). Best-effort like the endpoint
+    // path — a refusal or timeout falls through to the extractive answer.
+    if (options.llmRequestFn) {
+        try {
+            const answer = await options.llmRequestFn({ system, user });
+            if (answer)
+                return finish(answer, 'llm');
+        }
+        catch {
+            // Fall through to extractive.
+        }
+    }
     if (options.llmFn) {
-        const contextBlocks = passages
-            .map((p, i) => {
-            const header = p.heading ? `${p.file} › ${p.heading}` : p.file;
-            return `[Source ${i + 1}: ${header}]\n${p.snippet}`;
-        })
-            .join('\n\n---\n\n');
-        const prompt = `${options.systemPrompt || DEFAULT_RAG_SYSTEM_PROMPT}${historyHeader}\n\nContext:\n${contextBlocks}\n\nQuestion: ${query}\n\nAnswer:`;
-        const answer = await options.llmFn(prompt);
-        return { answer, citations, passages };
+        const answer = await options.llmFn(system + user);
+        return finish(answer, 'llm');
     }
-    if (options.llmEndpoint) {
-        const contextBlocks = passages
-            .map((p, i) => {
-            const header = p.heading ? `${p.file} › ${p.heading}` : p.file;
-            return `[Source ${i + 1}: ${header}]\n${p.snippet}`;
-        })
-            .join('\n\n---\n\n');
-        const prompt = `${options.systemPrompt || DEFAULT_RAG_SYSTEM_PROMPT}${historyHeader}\n\nContext:\n${contextBlocks}\n\nQuestion: ${query}\n\nAnswer:`;
+    // issue #199: unified chat provider path. `/chat/completions` by default
+    // (same wire format HyDE uses — llama.cpp, LM Studio, vLLM, Ollama /v1 all
+    // speak it), Ollama-native `/api/generate` under `--llm-provider ollama`.
+    // Streaming deltas flow to onDelta; the full text is assembled for the
+    // returned result. Best-effort like the old endpoint path — a refusal or
+    // idle timeout falls through to the extractive answer.
+    if (options.llmChat || options.llmEndpoint) {
+        const chat = options.llmChat ??
+            resolveChatProvider({
+                provider: options.llmProvider ?? 'openai',
+                model: options.llmModel,
+                baseUrl: options.llmEndpoint,
+            });
         try {
-            const resp = await fetch(`${options.llmEndpoint}/api/generate`, {
-                method: 'POST',
-                headers: { 'Content-Type': 'application/json' },
-                body: JSON.stringify({
-                    model: options.llmModel || 'llama3',
-                    prompt,
-                    stream: false,
-                }),
+            const answer = await chat.complete({
+                system,
+                user,
+                ...(options.onDelta ? { onDelta: options.onDelta } : {}),
+                ...(options.signal ? { signal: options.signal } : {}),
             });
-            if (resp.ok) {
-                const data = await resp.json();
-                const answer = data.response || data.text || '';
-                if (answer)
-                    return { answer, citations, passages };
-            }
+            if (answer)
+                return finish(answer, 'endpoint');
         }
         catch {
-            // Fallback to extractive
+            // Fall through to extractive.
         }
     }
     const answer = extractAnswerFallback(query, passages);
-    return { answer, citations, passages };
+    return finish(answer, 'extractive');
 }
 /**
  * End-to-end question answering against a Markdown index.
  */
 export async function askQuestion(opts) {
-    const { query, loaded: inputLoaded, indexDir, cacheDir = '', k = 5, llmFn, llmEndpoint, llmModel, systemPrompt, embedFn, } = opts;
+    const { query, loaded: inputLoaded, indexDir, cacheDir = '', k = 5, llmFn, llmRequestFn, llmEndpoint, llmModel, llmProvider, llmChat, onDelta, systemPrompt, embedFn, } = opts;
     let loaded = inputLoaded;
     if (!loaded) {
         if (!indexDir)
@@ -198,11 +283,16 @@ export async function askQuestion(opts) {
         query,
         k,
         embedFn,
+        offline: opts.offline,
     });
     return synthesizeAnswer(query, passages, {
         llmFn,
+        llmRequestFn,
         llmEndpoint,
         llmModel,
+        llmProvider,
+        llmChat,
+        onDelta,
         systemPrompt,
     });
 }
@@ -210,7 +300,7 @@ export async function askQuestion(opts) {
  * Executes a single conversational turn in a ChatSession with context carry-over and source manifest.
  */
 export async function chatTurn(opts) {
-    const { query, loaded: inputLoaded, indexDir, cacheDir = '', k = 5, llmFn, llmEndpoint, llmModel, systemPrompt, embedFn, log = () => { }, } = opts;
+    const { query, loaded: inputLoaded, indexDir, cacheDir = '', k = 5, llmFn, llmRequestFn, llmEndpoint, llmModel, llmProvider, llmChat, onDelta, systemPrompt, embedFn, log = () => { }, } = opts;
     let loaded = inputLoaded;
     if (!loaded) {
         if (!indexDir)
@@ -243,6 +333,7 @@ export async function chatTurn(opts) {
         query: retrievalQuery,
         k,
         embedFn,
+        offline: opts.offline,
     });
     // 3. Construct source manifest from retrieved chunks
     const manifest = passages.map((p) => {
@@ -268,8 +359,12 @@ export async function chatTurn(opts) {
     // 5. Synthesize answer
     const synth = await synthesizeAnswer(query, passages, {
         llmFn,
+        llmRequestFn,
         llmEndpoint,
         llmModel,
+        llmProvider,
+        llmChat,
+        onDelta,
         systemPrompt,
         conversationHistory,
     });
@@ -281,6 +376,7 @@ export async function chatTurn(opts) {
         answer: synth.answer,
         citations: synth.citations,
         manifest,
+        mode: synth.mode,
     };
     session.turns.push(turn);
     session.updatedAt = turn.timestamp;
@@ -302,5 +398,7 @@ export async function chatTurn(opts) {
         answer: turn.answer,
         citations: turn.citations,
         manifest: turn.manifest,
+        mode: turn.mode ?? 'extractive',
+        citationsUsed: extractUsedCitations(turn.answer, turn.citations),
     };
 }

package/dist/repair.d.ts

@@ -1,5 +1,5 @@
 export interface RepairAction {
-    action: 'remove-stale-lock' | 'remove-broken-vectors-bin' | 'remove-corrupt-ivf' | 'rebuild-index' | 'rewrite-hashes';
+    action: 'remove-stale-lock' | 'remove-broken-vectors-bin' | 'remove-corrupt-ivf' | 'remove-corrupt-hnsw' | 'rebuild-index' | 'rewrite-hashes';
     detail: string;
 }
 export interface RepairPlan {

package/dist/repair.js

@@ -108,7 +108,7 @@ export function planRepairs(indexDir, opts = {}) {
             });
         }
     }
-    // --- 3. corrupt ivf.json (optional ANN sidecar; loader silently ignores it) ---
+    // --- 3. corrupt ANN sidecars (optional; loader silently ignores them) ---
     const ivfPath = path.join(indexDir, 'ivf.json');
     const ivfRaw = readJsonIfParsable(ivfPath);
     if (ivfRaw.ok === false) {
@@ -117,9 +117,19 @@ export function planRepairs(indexDir, opts = {}) {
             detail: 'ivf.json is not valid JSON — removing it re-enables brute-force ANN fallback',
         });
     }
+    // issue #201: hnsw.json gets the same corrupt-sidecar treatment
+    const hnswPath = path.join(indexDir, 'hnsw.json');
+    const hnswRaw = readJsonIfParsable(hnswPath);
+    if (hnswRaw.ok === false) {
+        plan.actions.push({
+            action: 'remove-corrupt-hnsw',
+            detail: 'hnsw.json is not valid JSON — removing it re-enables brute-force ANN fallback',
+        });
+    }
     // --- 4. corrupt vectors.json ---
     const liveWriter = plan.skipped.some((s) => s.action === 'remove-stale-lock' && /live writer/.test(s.detail));
-    const vectorsRaw = readJsonIfParsable(path.join(indexDir, 'vectors.json'));
+    const vectorsPath = path.join(indexDir, 'vectors.json');
+    const vectorsRaw = readJsonIfParsable(vectorsPath);
     if (vectorsRaw.ok === false) {
         if (db && !liveWriter) {
             plan.actions.push({ action: 'rebuild-index', detail: `vectors.json is not valid JSON — rebuild from ${db}` });
@@ -137,6 +147,44 @@ export function planRepairs(indexDir, opts = {}) {
             });
         }
     }
+    // --- 4b. vectors.json SHA-256 sidecar mismatch (issue #166) ---
+    // `mdss check` reports this as an integrity failure; without a planned
+    // repair `check --fix` printed "nothing to repair" and left the index
+    // broken. Mirror the check's hashing (raw bytes vs first sidecar token)
+    // and plan the same rebuild as the corrupt-JSON path — rewriting the
+    // sidecar would bless whatever tampered content is on disk.
+    if (vectorsRaw.ok === true) {
+        const vectorsShaPath = `${vectorsPath}.sha256`;
+        if (fs.existsSync(vectorsShaPath)) {
+            let mismatch = null;
+            try {
+                const actual = crypto.createHash('sha256').update(fs.readFileSync(vectorsPath)).digest('hex');
+                const expected = fs.readFileSync(vectorsShaPath, 'utf8').trim().split(/\s+/)[0];
+                if (expected && expected !== actual)
+                    mismatch = 'SHA-256 mismatch';
+            }
+            catch (e) {
+                mismatch = e.message;
+            }
+            if (mismatch) {
+                if (db && !liveWriter) {
+                    plan.actions.push({ action: 'rebuild-index', detail: `vectors.json integrity check failed (${mismatch}) — rebuild from ${db}` });
+                }
+                else if (liveWriter) {
+                    plan.skipped.push({
+                        action: 'rebuild-index',
+                        detail: `vectors.json integrity check failed (${mismatch}), but a live writer holds the lock — retry after it finishes`,
+                    });
+                }
+                else {
+                    plan.skipped.push({
+                        action: 'rebuild-index',
+                        detail: `vectors.json integrity check failed (${mismatch}) — pass --db so --fix can rebuild it`,
+                    });
+                }
+            }
+        }
+    }
     // --- 5. damaged .hashes.json ---
     const hashesRaw = readJsonIfParsable(path.join(indexDir, '.hashes.json'));
     if (hashesRaw.ok === false) {
@@ -175,6 +223,9 @@ export function applyRepairs(indexDir, plan, opts = {}) {
                     case 'remove-corrupt-ivf':
                         fs.rmSync(path.join(indexDir, 'ivf.json'), { force: true });
                         break;
+                    case 'remove-corrupt-hnsw':
+                        fs.rmSync(path.join(indexDir, 'hnsw.json'), { force: true });
+                        break;
                     case 'rewrite-hashes': {
                         const hashes = recomputeHashes(opts.db);
                         fs.writeFileSync(path.join(indexDir, '.hashes.json'), JSON.stringify(hashes, null, 2));

package/dist/rerank.d.ts

@@ -17,10 +17,39 @@ export interface LoadedReranker {
     tokenizer: RerankerTokenizer;
     model: RerankerModel;
 }
-export declare const RERANK_MODEL = "Xenova/bge-reranker-base";
+/**
+ * Reranker registry (issue #203) — the cross-encoder counterpart of the
+ * embedder MODELS registry. Each entry is an explicit adapter: repo id,
+ * pinned revision, runtime dtype, and the tokenizer context budget the
+ * pair-truncation relies on. The loaded model must be a single-logit
+ * sequence classifier (logits[0] = relevance score) — the extraction in
+ * rerankScores is shared by every entry.
+ */
+export interface RerankerAdapter {
+    id: string;
+    revision?: string;
+    dtype: string;
+    maxTokens: number;
+    family?: string;
+    note?: string;
+}
+export declare const RERANKERS: Record<string, RerankerAdapter>;
+export declare const DEFAULT_RERANKER = "gte-reranker-modernbert";
+/** Legacy export — the default adapter's repo id (kept for back-compat). */
+export declare const RERANK_MODEL: string;
+/**
+ * Resolve a reranker alias / raw repo id (optionally `id@revision`) to an
+ * adapter. Unknown ids are rejected — unlike embedders there is no
+ * "unknown adapter" escape hatch, because the single-logit contract cannot
+ * be guessed safely.
+ */
+export declare function resolveReranker(name?: string | null): {
+    alias: string;
+    adapter: RerankerAdapter;
+};
 export declare function getReranker(cacheDir: string, offline?: boolean, retryOpts?: {
     maxRetries?: number;
     delays?: number[];
     log?: (msg: string) => void;
-}): Promise<LoadedReranker>;
-export declare function rerankScores(query: string, passages: string[], cacheDir: string, offline?: boolean): Promise<number[]>;
+}, rerankerName?: string | null): Promise<LoadedReranker>;
+export declare function rerankScores(query: string, passages: string[], cacheDir: string, offline?: boolean, rerankerName?: string | null): Promise<number[]>;

package/dist/rerank.js

@@ -3,11 +3,57 @@
  */
 import { resolveSessionOptions, retryWithBackoff, emitDownloadEvent } from './core.js';
 const _rerankers = new Map();
-export const RERANK_MODEL = 'Xenova/bge-reranker-base';
-export async function getReranker(cacheDir, offline = false, retryOpts = {}) {
+export const RERANKERS = {
+    'gte-reranker-modernbert': {
+        id: 'Alibaba-NLP/gte-reranker-modernbert-base',
+        revision: 'f7481e6055501a30fb19d090657df9ec1f79ab2c',
+        dtype: 'q8',
+        maxTokens: 8192,
+        family: 'gte',
+        note: 'Default since issue #203 — ~144 MB q8, Apache-2.0, ModernBERT 8k context. Golden set: nDCG@10 0.9318 vs bge-reranker-base 0.8839.',
+    },
+    'bge-reranker-base': {
+        id: 'Xenova/bge-reranker-base',
+        dtype: 'q8',
+        maxTokens: 512,
+        family: 'bge',
+        note: '~278 MB q8. The pre-#203 default; kept for reproducibility (pin via --rerank-model bge-reranker-base).',
+    },
+};
+export const DEFAULT_RERANKER = 'gte-reranker-modernbert';
+/** Legacy export — the default adapter's repo id (kept for back-compat). */
+export const RERANK_MODEL = RERANKERS[DEFAULT_RERANKER].id;
+/**
+ * Resolve a reranker alias / raw repo id (optionally `id@revision`) to an
+ * adapter. Unknown ids are rejected — unlike embedders there is no
+ * "unknown adapter" escape hatch, because the single-logit contract cannot
+ * be guessed safely.
+ */
+export function resolveReranker(name) {
+    if (!name || name === DEFAULT_RERANKER) {
+        return { alias: DEFAULT_RERANKER, adapter: RERANKERS[DEFAULT_RERANKER] };
+    }
+    if (RERANKERS[name])
+        return { alias: name, adapter: RERANKERS[name] };
+    let id = name;
+    let revision;
+    const at = name.indexOf('@');
+    if (at > 0) {
+        id = name.slice(0, at);
+        revision = name.slice(at + 1) || undefined;
+    }
+    for (const [alias, adapter] of Object.entries(RERANKERS)) {
+        if (adapter.id === id) {
+            return { alias, adapter: revision ? { ...adapter, revision } : adapter };
+        }
+    }
+    throw new Error(`unknown reranker "${name}" — available: ${Object.keys(RERANKERS).join(', ')} (or register it in RERANKERS, issue #203)`);
+}
+export async function getReranker(cacheDir, offline = false, retryOpts = {}, rerankerName) {
+    const { adapter } = resolveReranker(rerankerName);
     const sessionOptions = resolveSessionOptions();
     const sessionKey = sessionOptions ? JSON.stringify(sessionOptions) : 'default';
-    const key = `${RERANK_MODEL}|${offline ? 'off' : 'on'}|${sessionKey}`;
+    const key = `${adapter.id}@${adapter.revision || 'main'}|${adapter.dtype}|${offline ? 'off' : 'on'}|${sessionKey}`;
     if (_rerankers.has(key))
         return _rerankers.get(key);
     const loadPipeline = async () => {
@@ -15,13 +61,17 @@ export async function getReranker(cacheDir, offline = false, retryOpts = {}) {
         if (cacheDir)
             env.cacheDir = cacheDir;
         env.allowRemoteModels = !offline;
-        const tokenizer = await AutoTokenizer.from_pretrained(RERANK_MODEL, { progress_callback: emitDownloadEvent });
+        const tokenizer = await AutoTokenizer.from_pretrained(adapter.id, {
+            ...(adapter.revision ? { revision: adapter.revision } : {}),
+            progress_callback: emitDownloadEvent,
+        });
         const loadOpts = {
-            dtype: 'q8',
+            dtype: adapter.dtype,
             progress_callback: emitDownloadEvent,
+            ...(adapter.revision ? { revision: adapter.revision } : {}),
             ...(sessionOptions ? { session_options: sessionOptions } : {}),
         };
-        const model = await AutoModelForSequenceClassification.from_pretrained(RERANK_MODEL, loadOpts);
+        const model = await AutoModelForSequenceClassification.from_pretrained(adapter.id, loadOpts);
         const r = { tokenizer, model };
         _rerankers.set(key, r);
         return r;
@@ -31,10 +81,10 @@ export async function getReranker(cacheDir, offline = false, retryOpts = {}) {
     }
     return await retryWithBackoff(loadPipeline, retryOpts);
 }
-export async function rerankScores(query, passages, cacheDir, offline = false) {
+export async function rerankScores(query, passages, cacheDir, offline = false, rerankerName) {
     if (passages.length === 0)
         return [];
-    const { tokenizer, model } = await getReranker(cacheDir, offline);
+    const { tokenizer, model } = await getReranker(cacheDir, offline, {}, rerankerName);
     const queries = new Array(passages.length).fill(query);
     const inputs = tokenizer(queries, { text_pair: passages, padding: true, truncation: true });
     const outputs = await model(inputs);

package/dist/search.d.ts

@@ -2,6 +2,7 @@ import { ModelDescriptor } from './core.js';
 import { LexicalIndex } from './lexical.js';
 import { DocumentMetadata } from './frontmatter.js';
 import { IVFIndex } from './ivf.js';
+import { HnswIndex } from './hnsw.js';
 import { RelationshipGraph } from './wikilinks.js';
 import { FilterNode } from './filter.js';
 export { tokenize } from './lexical.js';
@@ -13,6 +14,17 @@ export declare function rrf(rankings: Array<Array<{
     idx: number;
     score: number;
 }>>, k?: number, weights?: number[]): Map<number, number>;
+/**
+ * issue #191: bounded top-k selection over a dense sweep — a capped min-heap
+ * instead of materializing one object per chunk and fully sorting. Ties break
+ * toward the smaller idx, which is exactly what a stable sort by
+ * (score desc) over idx-ordered input produces, so the selected pool and its
+ * order are identical to `[...items].sort((a, b) => b.score - a.score).slice(0, k)`.
+ */
+export declare function topKByScore(n: number, scoreAt: (i: number) => number, k: number): Array<{
+    idx: number;
+    score: number;
+}>;
 export interface IndexChunk {
     file: string;
     title: string;
@@ -74,9 +86,18 @@ export interface RuntimeIndexState {
     model: ModelDescriptor;
     queryCache: QueryEmbeddingCache;
     ivf?: IVFIndex;
+    /** issue #201: optional HNSW graph sidecar (hnsw.json), parallel to ivf. */
+    hnsw?: HnswIndex;
     graph?: RelationshipGraph;
     pageRank?: Map<string, number>;
+    /**
+     * issue #190: precomputed sqrt(sum(c^2)) for int8 vectors (zero-copy binary
+     * load only) — lets the dense sweep compute the dot product alone.
+     */
+    chunkNorms?: Float32Array;
 }
+/** issue #190 tool/test seam: the cached int8 sweep norms, when present. */
+export declare function getRuntimeChunkNorms(index: IndexFile): Float32Array | undefined;
 export declare function getRuntimeGraph(runtime: RuntimeIndexState): {
     graph: RelationshipGraph;
     pageRank: Map<string, number>;
@@ -84,7 +105,9 @@ export declare function getRuntimeGraph(runtime: RuntimeIndexState): {
 /**
  * Issue #127 pure helpers — exported for deterministic unit tests.
  */
-/** Frontmatter `created` → `updated` → file mtime; null when nothing parses. */
+/** Frontmatter `updated` → `created` → file mtime; null when nothing parses.
+ *  Issue #164: `updated` wins — long-lived notes that were recently revised
+ *  must not be penalized by their original creation date. */
 export declare function resolvePassageAgeMs(meta: {
     created?: unknown;
     updated?: unknown;
@@ -97,13 +120,23 @@ export declare function recencyBoost(ageMs: number | null, halfLifeDays: number,
  * Injectable fetch for tests.
  */
 export declare function hydePassage(endpoint: string, query: string, model?: string, fetchImpl?: typeof fetch): Promise<string | null>;
+/**
+ * issue #203: LLM paraphrases for multi-query expansion. ONE OpenAI-compatible
+ * chat completion asking for N alternative phrasings; returns clean, deduped,
+ * non-empty variants (the original query excluded). Returns [] on ANY failure —
+ * multi-query must degrade to the single-query baseline silently, exactly like
+ * HyDE. Injectable fetch for tests.
+ */
+export declare function paraphraseQueries(endpoint: string, query: string, count: number, model?: string, fetchImpl?: typeof fetch): Promise<string[]>;
 /**
  * Salient-term extraction for PRF (issue #125): tokens that appear in the
  * top-m feedback passages, are not query terms or stopwords, and are ranked
  * by (tf-in-feedback × distinct-passage coverage). Pure + deterministic.
  */
 export declare function extractExpansionTerms(topTexts: string[], queryTerms: string[], maxTerms: number): string[];
-export declare function loadIndex(indexDir: string): {
+export declare function loadIndex(indexDir: string, opts?: {
+    checkStale?: boolean;
+}): {
     index: IndexFile;
     model: ModelDescriptor;
 };
@@ -147,8 +180,20 @@ export interface SearchOptions {
     llmEndpoint?: string;
     /** issue #125: model name for the HyDE chat call. */
     llmModel?: string;
-    ann?: boolean;
+    /**
+     * issue #203: multi-query expansion — N total query variants (original +
+     * N-1 LLM paraphrases), each embedded, rankings fused with union-RRF.
+     * Requires `llmEndpoint`; without one (or on any LLM failure) it degrades
+     * to the single-query baseline. 0/1/undefined = off.
+     */
+    multiQuery?: number;
+    /** issue #203: reranker registry alias (`bge-reranker-base` default, `gte-reranker-modernbert`, ...). */
+    rerankModel?: string;
+    /** issue #201: ANN engine — `true` = default engine, or explicit 'ivf' | 'hnsw'. */
+    ann?: boolean | 'ivf' | 'hnsw';
     nprobe?: number;
+    /** issue #201: HNSW ef-search breadth (default 64). */
+    ef?: number;
     graphBoost?: number;
     filter?: string | FilterNode;
     dimensions?: number;