md-semantic-search 1.0.3 → 2.0.0

package/dist/rag.d.ts

@@ -1,11 +1,5 @@
-/**
- * Offline QA & Local RAG Answer Synthesis (issue #101).
- *
- * Implements grounded question answering with strict provenance citations ([file#heading]),
- * supporting local LLM bridges (Ollama / LocalAI / OpenAI-compatible endpoint) and a
- * fast built-in zero-dependency extractive synthesis fallback.
- */
 import { LoadedIndex, SearchResultHit } from './search.js';
+import { ChatProviderId, ResolvedChat } from './providers.js';
 export interface Citation {
     file: string;
     heading?: string;
@@ -14,7 +8,52 @@ export interface Citation {
 export interface SynthesisResult {
     answer: string;
     citations: Citation[];
+    /**
+     * issue #199 follow-up: citations the answer actually mentions (bracket
+     * formats `[file#heading]` / `[file › heading]` / `[file]`), in order of
+     * first mention. Deterministic post-processing of the LLM text — a subset
+     * of `citations`, which stays the full retrieval manifest for compatibility.
+     */
+    citationsUsed?: Citation[];
     passages: SearchResultHit[];
+    /** Which synthesis stage produced the answer (issue #197 observability). */
+    mode?: 'llm' | 'endpoint' | 'extractive';
+}
+/**
+ * System/user split for transports that keep the two apart on the wire —
+ * MCP `sampling/createMessage` (issue #197) carries a `systemPrompt` field
+ * and a message list, unlike the single-string local LLM bridge.
+ */
+export interface LlmStructuredRequest {
+    system: string;
+    user: string;
+}
+export interface ChatSourceManifestItem {
+    file: string;
+    heading?: string;
+    headingPath?: string[];
+    startLine?: number;
+    endLine?: number;
+    chunkHash?: string;
+    score: number;
+}
+export interface ChatTurn {
+    id: string;
+    timestamp: string;
+    query: string;
+    answer: string;
+    citations: Citation[];
+    manifest: ChatSourceManifestItem[];
+    /** Which synthesis stage produced the answer (issue #199; optional in persisted sessions). */
+    mode?: SynthesisResult['mode'];
+}
+export interface ChatSession {
+    id: string;
+    createdAt: string;
+    updatedAt: string;
+    db?: string;
+    model?: string;
+    turns: ChatTurn[];
 }
 export interface AskOptions {
     query: string;
@@ -23,27 +62,113 @@ export interface AskOptions {
     cacheDir?: string;
     db?: string;
     k?: number;
+    offline?: boolean;
     llmEndpoint?: string;
     llmModel?: string;
+    /** issue #199: chat wire format for llmEndpoint — 'openai' (default) or 'ollama'. */
+    llmProvider?: ChatProviderId;
     llmFn?: (prompt: string) => Promise<string>;
+    llmRequestFn?: (req: LlmStructuredRequest) => Promise<string>;
+    /** issue #199: incremental render hook — fires per token chunk while the LLM streams. */
+    onDelta?: (delta: string) => void;
+    /** issue #199: injection seam for tests/serve; built from llmEndpoint when absent. */
+    llmChat?: ResolvedChat;
     systemPrompt?: string;
     embedFn?: any;
 }
+export interface ChatTurnOptions {
+    session?: ChatSession;
+    query: string;
+    loaded?: LoadedIndex;
+    indexDir?: string;
+    cacheDir?: string;
+    db?: string;
+    k?: number;
+    offline?: boolean;
+    llmEndpoint?: string;
+    llmModel?: string;
+    /** issue #199: chat wire format for llmEndpoint — 'openai' (default) or 'ollama'. */
+    llmProvider?: ChatProviderId;
+    llmFn?: (prompt: string) => Promise<string>;
+    llmRequestFn?: (req: LlmStructuredRequest) => Promise<string>;
+    /** issue #199: incremental render hook — fires per token chunk while the LLM streams. */
+    onDelta?: (delta: string) => void;
+    /** issue #199: injection seam for tests/serve; built from llmEndpoint when absent. */
+    llmChat?: ResolvedChat;
+    systemPrompt?: string;
+    embedFn?: any;
+    log?: (msg: string) => void;
+}
 export declare const DEFAULT_RAG_SYSTEM_PROMPT: string;
+/**
+ * Returns the directory where chat sessions are persisted.
+ */
+export declare function getSessionsDir(indexDir: string): string;
+/**
+ * Validates a session id before it is used as a filesystem path component.
+ */
+export declare function assertSafeSessionId(id: string): string;
+/**
+ * Atomically saves a ChatSession to disk (<indexDir>/sessions/<id>.json).
+ */
+export declare function saveChatSession(indexDir: string, session: ChatSession): string;
+/**
+ * Loads a ChatSession by id or creates a new one. Degrades safely if corrupt.
+ */
+export declare function loadChatSession(indexDir: string, id: string, log?: (msg: string) => void): ChatSession;
+/**
+ * Lists all existing ChatSessions in the indexDir, sorted by updatedAt descending.
+ */
+export declare function listChatSessions(indexDir: string): Array<{
+    id: string;
+    createdAt: string;
+    updatedAt: string;
+    turnsCount: number;
+}>;
 /**
  * Built-in extractive answer synthesizer for fully offline, zero-dependency QA.
  */
 export declare function extractAnswerFallback(query: string, passages: SearchResultHit[]): string;
+/**
+ * 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 declare function extractUsedCitations(answer: string, citations: Citation[]): Citation[];
 /**
  * Synthesizes an answer from retrieved passages using an LLM or fallback.
  */
 export declare function synthesizeAnswer(query: string, passages: SearchResultHit[], options?: {
     llmFn?: (prompt: string) => Promise<string>;
+    llmRequestFn?: (req: LlmStructuredRequest) => Promise<string>;
     llmEndpoint?: string;
     llmModel?: string;
+    /** issue #199: chat wire format for llmEndpoint — 'openai' (default) or 'ollama'. */
+    llmProvider?: ChatProviderId;
+    llmChat?: ResolvedChat;
+    /** issue #199: incremental render hook — fires per token chunk while the LLM streams. */
+    onDelta?: (delta: string) => void;
+    /** Cooperative cancel (serve /ask: client disconnected mid-stream). */
+    signal?: AbortSignal;
     systemPrompt?: string;
+    conversationHistory?: string;
 }): Promise<SynthesisResult>;
 /**
  * End-to-end question answering against a Markdown index.
  */
 export declare function askQuestion(opts: AskOptions): Promise<SynthesisResult>;
+/**
+ * Executes a single conversational turn in a ChatSession with context carry-over and source manifest.
+ */
+export declare function chatTurn(opts: ChatTurnOptions): Promise<{
+    session: ChatSession;
+    turn: ChatTurn;
+    answer: string;
+    citations: Citation[];
+    manifest: ChatSourceManifestItem[];
+    /** Which synthesis stage produced the answer ('llm'/'endpoint'/'extractive'). */
+    mode: SynthesisResult['mode'];
+    /** Citations the answer text actually mentions (issue #199 follow-up). */
+    citationsUsed: Citation[];
+}>;

package/dist/rag.js

@@ -1,15 +1,103 @@
-/**
- * Offline QA & Local RAG Answer Synthesis (issue #101).
- *
- * Implements grounded question answering with strict provenance citations ([file#heading]),
- * supporting local LLM bridges (Ollama / LocalAI / OpenAI-compatible endpoint) and a
- * fast built-in zero-dependency extractive synthesis fallback.
- */
+import fs from 'node:fs';
+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.';
+/**
+ * Returns the directory where chat sessions are persisted.
+ */
+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`);
+    const tmpPath = path.join(dir, `${session.id}.${Date.now()}.tmp`);
+    fs.writeFileSync(tmpPath, JSON.stringify(session, null, 2), 'utf8');
+    fs.renameSync(tmpPath, targetPath);
+    return targetPath;
+}
+/**
+ * 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 {
+            const raw = fs.readFileSync(sessionPath, 'utf8');
+            const parsed = JSON.parse(raw);
+            if (parsed && typeof parsed.id === 'string' && Array.isArray(parsed.turns)) {
+                return parsed;
+            }
+            log(`warning: session ${id} is malformed; starting a fresh session.`);
+        }
+        catch (e) {
+            log(`warning: failed to parse session ${id} (${e.message}); starting fresh.`);
+        }
+    }
+    const now = new Date().toISOString();
+    return {
+        id,
+        createdAt: now,
+        updatedAt: now,
+        turns: [],
+    };
+}
+/**
+ * Lists all existing ChatSessions in the indexDir, sorted by updatedAt descending.
+ */
+export function listChatSessions(indexDir) {
+    const dir = getSessionsDir(indexDir);
+    if (!fs.existsSync(dir))
+        return [];
+    const out = [];
+    let entries;
+    try {
+        entries = fs.readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    for (const file of entries) {
+        if (!file.endsWith('.json'))
+            continue;
+        const p = path.join(dir, file);
+        try {
+            const raw = fs.readFileSync(p, 'utf8');
+            const s = JSON.parse(raw);
+            if (s && typeof s.id === 'string' && Array.isArray(s.turns)) {
+                out.push({
+                    id: s.id,
+                    createdAt: s.createdAt || s.updatedAt || '',
+                    updatedAt: s.updatedAt || s.createdAt || '',
+                    turnsCount: s.turns.length,
+                });
+            }
+        }
+        catch { }
+    }
+    return out.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+}
 /**
  * Built-in extractive answer synthesizer for fully offline, zero-dependency QA.
  */
@@ -53,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.
  */
@@ -62,50 +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}\n\nContext:\n${contextBlocks}\n\nQuestion: ${query}\n\nAnswer:`;
-        const answer = await options.llmFn(prompt);
-        return { answer, citations, passages };
-    }
-    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}\n\nContext:\n${contextBlocks}\n\nQuestion: ${query}\n\nAnswer:`;
+        const answer = await options.llmFn(system + user);
+        return finish(answer, 'llm');
+    }
+    // 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)
@@ -118,11 +283,122 @@ export async function askQuestion(opts) {
         query,
         k,
         embedFn,
+        offline: opts.offline,
     });
     return synthesizeAnswer(query, passages, {
         llmFn,
+        llmRequestFn,
+        llmEndpoint,
+        llmModel,
+        llmProvider,
+        llmChat,
+        onDelta,
+        systemPrompt,
+    });
+}
+/**
+ * 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, llmRequestFn, llmEndpoint, llmModel, llmProvider, llmChat, onDelta, systemPrompt, embedFn, log = () => { }, } = opts;
+    let loaded = inputLoaded;
+    if (!loaded) {
+        if (!indexDir)
+            throw new Error('chatTurn requires either loaded index or indexDir');
+        loaded = loadIndex(indexDir);
+    }
+    let session = opts.session;
+    if (!session) {
+        const newId = crypto.randomUUID().slice(0, 8);
+        session = indexDir ? loadChatSession(indexDir, newId, log) : {
+            id: newId,
+            createdAt: new Date().toISOString(),
+            updatedAt: new Date().toISOString(),
+            turns: [],
+        };
+    }
+    // 1. Build contextual retrieval query for follow-up questions
+    let retrievalQuery = query;
+    if (session.turns.length > 0) {
+        const prevTurn = session.turns[session.turns.length - 1];
+        const prevTokens = tokenize(prevTurn.query).filter((t) => t.length > 3).slice(0, 4);
+        if (prevTokens.length > 0) {
+            retrievalQuery = `${query} ${prevTokens.join(' ')}`.trim();
+        }
+    }
+    // 2. Search index
+    const passages = await searchIndex({
+        loaded,
+        cacheDir,
+        query: retrievalQuery,
+        k,
+        embedFn,
+        offline: opts.offline,
+    });
+    // 3. Construct source manifest from retrieved chunks
+    const manifest = passages.map((p) => {
+        const chunk = loaded.index?.chunks?.find((c) => c.file === p.file && (c.heading === p.heading || (!c.heading && !p.heading)));
+        return {
+            file: p.file,
+            heading: p.heading,
+            headingPath: chunk?.headingPath,
+            startLine: chunk?.startLine,
+            endLine: chunk?.endLine,
+            chunkHash: chunk?.chunkHash,
+            score: p.score,
+        };
+    });
+    // 4. Conversation history string for LLM prompt
+    let conversationHistory = '';
+    if (session.turns.length > 0) {
+        conversationHistory = session.turns
+            .slice(-3)
+            .map((t) => `User: ${t.query}\nAssistant: ${t.answer}`)
+            .join('\n\n');
+    }
+    // 5. Synthesize answer
+    const synth = await synthesizeAnswer(query, passages, {
+        llmFn,
+        llmRequestFn,
         llmEndpoint,
         llmModel,
+        llmProvider,
+        llmChat,
+        onDelta,
         systemPrompt,
+        conversationHistory,
     });
+    // 6. Append turn to session
+    const turn = {
+        id: crypto.randomUUID(),
+        timestamp: new Date().toISOString(),
+        query,
+        answer: synth.answer,
+        citations: synth.citations,
+        manifest,
+        mode: synth.mode,
+    };
+    session.turns.push(turn);
+    session.updatedAt = turn.timestamp;
+    if (loaded.index?.db)
+        session.db = loaded.index.db;
+    if (loaded.model?.id)
+        session.model = loaded.model.id;
+    if (indexDir) {
+        try {
+            saveChatSession(indexDir, session);
+        }
+        catch (e) {
+            log(`warning: failed to save chat session ${session.id}: ${e.message}`);
+        }
+    }
+    return {
+        session,
+        turn,
+        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));