md-semantic-search 1.0.2 → 1.0.3

package/src/download-progress.ts

@@ -0,0 +1,146 @@
+/**
+ * Aggregated model-download progress (issue #108).
+ *
+ * transformers.js emits per-file events (`initiate`/`download`/`progress`/`done`)
+ * while a model directory streams in. A model is many files, so a per-file bar
+ * flickers uselessly — this aggregator folds them into ONE view: percent across
+ * every tracked file, smoothed MB/s, and an ETA over the bytes still missing.
+ *
+ * The "sawPartial" gate implements the warm-cache acceptance criterion: cached
+ * loads surface only instant complete-file events, so unless a real partial
+ * transfer was observed the aggregator stays silent.
+ */
+
+export interface DownloadProgressEvent {
+  status?: string;
+  name?: string;
+  file?: string;
+  loaded?: number;
+  total?: number;
+  progress?: number;
+}
+
+export interface DownloadSnapshot {
+  /** True once a partial transfer was observed — gates ALL output. */
+  reportable: boolean;
+  /** True when every file with a known total has fully arrived. */
+  complete: boolean;
+  doneFiles: number;
+  activeFiles: number;
+  loadedBytes: number;
+  totalBytes: number;
+  /** 0..100 across files with known totals; null while no total is known yet. */
+  percent: number | null;
+  mbps: number | null;
+  etaSec: number | null;
+  currentFile: string | null;
+}
+
+interface FileProgress {
+  loaded: number;
+  total: number; // 0 = unknown
+}
+
+const SPEED_SMOOTHING = 0.3; // EMA weight of the newest instantaneous sample
+
+export class DownloadProgressAggregator {
+  private files = new Map<string, FileProgress>();
+  private sawPartial = false;
+  private lastSampleAt = 0;
+  private lastSampleBytes = 0;
+  private mbpsEma: number | null = null;
+  private lastRenderAt = 0;
+
+  update(e: DownloadProgressEvent, nowMs: number = Date.now()): void {
+    if (!e || typeof e.file !== 'string' || e.file.length === 0) return;
+    let f = this.files.get(e.file);
+    if (!f) {
+      f = { loaded: 0, total: 0 };
+      this.files.set(e.file, f);
+    }
+    if (typeof e.total === 'number' && Number.isFinite(e.total) && e.total > f.total) {
+      f.total = e.total;
+    }
+    if (typeof e.loaded === 'number' && Number.isFinite(e.loaded) && e.loaded >= 0) {
+      // clamp against the known total so a stray event can't overshoot to >100%
+      f.loaded = f.total > 0 ? Math.min(e.loaded, f.total) : e.loaded;
+    }
+
+    const midTransfer =
+      (e.status === 'download' || e.status === 'progress') && f.total > 0 && f.loaded < f.total;
+    if (midTransfer) this.sawPartial = true;
+
+    // speed sampling on cumulative byte growth
+    const sum = this.sumLoaded();
+    if (this.lastSampleAt === 0) {
+      this.lastSampleAt = nowMs;
+      this.lastSampleBytes = sum;
+    } else if (sum > this.lastSampleBytes) {
+      const dtSec = (nowMs - this.lastSampleAt) / 1000;
+      if (dtSec > 0.05) {
+        const inst = (sum - this.lastSampleBytes) / dtSec / (1024 * 1024);
+        this.mbpsEma = this.mbpsEma === null ? inst : this.mbpsEma * (1 - SPEED_SMOOTHING) + inst * SPEED_SMOOTHING;
+        this.lastSampleAt = nowMs;
+        this.lastSampleBytes = sum;
+      }
+    }
+  }
+
+  private sumLoaded(): number {
+    let sum = 0;
+    for (const f of this.files.values()) sum += f.loaded;
+    return sum;
+  }
+
+  snapshot(): DownloadSnapshot {
+    let loadedBytes = 0;
+    let totalBytes = 0;
+    let doneFiles = 0;
+    let activeFiles = 0;
+    for (const f of this.files.values()) {
+      loadedBytes += f.loaded;
+      if (f.total > 0) {
+        totalBytes += f.total;
+        if (f.loaded >= f.total) doneFiles += 1;
+        else activeFiles += 1;
+      }
+    }
+    const percent = totalBytes > 0 ? Math.min(100, (loadedBytes / totalBytes) * 100) : null;
+    const remaining = totalBytes - loadedBytes;
+    const etaSec =
+      this.mbpsEma !== null && this.mbpsEma > 0 && remaining > 0 ? remaining / (1024 * 1024) / this.mbpsEma : null;
+    return {
+      reportable: this.sawPartial,
+      complete: totalBytes > 0 && activeFiles === 0,
+      doneFiles,
+      activeFiles,
+      loadedBytes,
+      totalBytes,
+      percent,
+      mbps: this.sawPartial ? this.mbpsEma : null,
+      etaSec: this.sawPartial ? etaSec : null,
+      currentFile: [...this.files.entries()].find(([, f]) => f.total === 0 || f.loaded < f.total)?.[0] ?? null,
+    };
+  }
+
+  /**
+   * Render throttle for live views: pass through at most one line per
+   * interval, plus ALWAYS the transition into `complete`.
+   */
+  shouldRender(nowMs: number, minIntervalMs = 400): boolean {
+    if (!this.sawPartial) return false;
+    const justCompleted = this.snapshot().complete && !this.renderedComplete;
+    if (justCompleted) {
+      this.renderedComplete = true;
+      this.lastRenderAt = nowMs;
+      return true;
+    }
+    if (nowMs - this.lastRenderAt >= minIntervalMs) {
+      this.lastRenderAt = nowMs;
+      return true;
+    }
+    return false;
+  }
+
+  private renderedComplete = false;
+}

package/src/index.ts

@@ -89,5 +89,9 @@ export {
 } from './summarize.js';
 
 export { runTui, TuiOptions } from './tui.js';
+export {
+  generateCompletion, FLAGS, COMMANDS, COMPLETION_SHELLS,
+} from './completions.js';
+export type { FlagSpec, CompletionShell } from './completions.js';
 
 

package/src/mcp.ts

@@ -12,6 +12,14 @@ import { searchFederated } from './federation.js';
 import { askQuestion } from './rag.js';
 import { globToRegExp } from './core.js';
 
+/**
+ * Package version reported via MCP initialize → serverInfo.
+ * Single source of truth: package.json (resolved relative to dist/mcp.js).
+ */
+const MCP_VERSION: string = JSON.parse(
+  fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8'),
+).version;
+
 export const MCP_TOOLS = [
   {
     name: 'search_markdown',
@@ -74,8 +82,7 @@ export const MCP_TOOLS = [
   },
 ];
 
-export async function handleMcpRequest(req: any, state: { loaded: any; cacheDir: string; offline: boolean; embedFn?: any }): Promise<any | null> {
-  if (!req || typeof req !== 'object') return null;
+export async function handleMcpRequest(req: any, state: { loaded: any; cacheDir: string; offline: boolean; embedFn?: any }): Promise<any | null> {  if (!req || typeof req !== 'object') return null;
   const { id, method, params } = req;
 
   if (id === undefined || id === null) {
@@ -93,7 +100,7 @@ export async function handleMcpRequest(req: any, state: { loaded: any; cacheDir:
         },
         serverInfo: {
           name: 'md-semantic-search',
-          version: '1.0.0',
+          version: MCP_VERSION,
         },
       },
     };

package/src/open.ts

@@ -0,0 +1,119 @@
+/**
+ * Editor jump for search hits (issue #110): open a hit's file at its exact
+ * `startLine` in $MDSS_EDITOR / $VISUAL / $EDITOR, with smart argument styles
+ * for known editor families and a platform GUI opener as the last resort.
+ *
+ * Resolution is PURE (unit-testable); launching goes through an injected
+ * runner so tests never spawn real processes.
+ */
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+
+export interface OpenTarget {
+  file: string;
+  line?: number;
+}
+
+export interface OpenCommand {
+  command: string;
+  args: string[];
+  /** Human-readable source of the decision, e.g. "$EDITOR=vim" or "GUI opener". */
+  via: string;
+}
+
+export interface ResolveOptions {
+  /** $MDSS_EDITOR / $VISUAL / $EDITOR value, if any. */
+  editor?: string | null;
+  platform?: NodeJS.Platform;
+}
+
+export interface RunOptions extends ResolveOptions {
+  runner?: OpenRunner;
+}
+
+export type OpenRunner = (
+  command: string,
+  args: string[],
+  opts: { detached: boolean; stdio: 'ignore' }
+) => unknown;
+
+const VSCODE_FAMILY = /^(code|code-insiders|codium|cursor|windsurf)$/i;
+/** Terminal editors taking a "+<line>" positional before the file. */
+const PLUS_LINE_EDITORS = /^(vim|vi|nvim|nano|ne|emacs|emacsclient|micro|hx)$/i;
+
+function baseName(cmd: string): string {
+  // handle BOTH separators so a Windows full path resolves its family even
+  // when mdss runs on POSIX CI (issue #110)
+  const last = cmd.split(/[\\/]/).pop() ?? cmd;
+  return last.replace(/\.(exe|cmd|bat)$/i, '');
+}
+
+function splitEditorCommand(editor: string): string[] {
+  // A value containing a path separator is ONE binary path (Windows installs
+  // live under "C:\Program Files\..."); only bare names may carry extra flags.
+  if (/[/\\]/.test(editor)) return [editor];
+  return editor.trim().split(/\s+/);
+}
+
+/**
+ * Decide HOW to open `target`.
+ * - editor given: first token is the binary, remaining tokens are forwarded
+ *   verbatim. VS Code family gets `--goto file:line`, plus-line editors get
+ *   `+<line> file`, anything else just gets the file.
+ * - No editor configured → platform GUI opener (win32 `cmd /c start ""`,
+ *   darwin `open`, else `xdg-open`); a line cannot be passed there.
+ * Returns null only on an unsupported platform without an editor.
+ */
+export function resolveOpenCommand(target: OpenTarget, opts: ResolveOptions = {}): OpenCommand | null {
+  const { editor, platform = process.platform } = opts;
+  const line = Number.isInteger(target.line) && (target.line as number) > 0 ? target.line : undefined;
+
+  if (editor && editor.trim()) {
+    const parts = splitEditorCommand(editor.trim());
+    const command = parts[0];
+    const extra = parts.slice(1);
+    const name = baseName(command);
+    if (VSCODE_FAMILY.test(name)) {
+      return {
+        command,
+        args: [...extra, '--goto', `${target.file}${line ? `:${line}` : ''}`],
+        via: `$EDITOR=${editor}`,
+      };
+    }
+    if (PLUS_LINE_EDITORS.test(name)) {
+      return { command, args: [...extra, ...(line ? [`+${line}`] : []), target.file], via: `$EDITOR=${editor}` };
+    }
+    return { command, args: [...extra, target.file], via: `$EDITOR=${editor}` };
+  }
+
+  if (platform === 'win32') {
+    // empty title arg prevents `start` from mangling quoted paths
+    return { command: 'cmd', args: ['/c', 'start', '', target.file], via: 'GUI opener' };
+  }
+  if (platform === 'darwin') {
+    return { command: 'open', args: [target.file], via: 'GUI opener' };
+  }
+  if (platform === 'linux' || platform === 'freebsd' || platform === 'openbsd') {
+    return { command: 'xdg-open', args: [target.file], via: 'GUI opener' };
+  }
+  return null;
+}
+
+/** Launch via the default detached spawn; inject a fake in tests. */
+export function defaultOpenRunner(command: string, args: string[], opts: { detached: boolean; stdio: 'ignore' }): void {
+  const child = spawn(command, args, { detached: true, stdio: 'ignore' });
+  child.unref();
+}
+
+/**
+ * Resolve + run. Returns the OpenCommand used (or null when nothing could be
+ * resolved). Throws when the runner reports a launch failure — callers turn
+ * that into a friendly die().
+ */
+export function openHit(target: OpenTarget, opts: RunOptions = {}): OpenCommand | null {
+  const { runner = defaultOpenRunner, ...resolveOpts } = opts;
+  const resolved = resolveOpenCommand(target, resolveOpts);
+  if (!resolved) return null;
+  runner(resolved.command, resolved.args, { detached: true, stdio: 'ignore' });
+  return resolved;
+}

package/src/providers.ts

@@ -0,0 +1,134 @@
+/**
+ * Pluggable embedding providers (issue #124): Ollama and OpenAI-compatible
+ * endpoints beside the built-in local transformers.js path.
+ *
+ * Design: a provider produces (a) an async embedFn with the SAME signature as
+ * core.embed(texts, role, model, cacheDir, offline) and (b) a synthetic
+ * ModelAdapter descriptor. The descriptor flows through the EXISTING machinery
+ * (adapter fingerprint, dim validation, index metadata) so switching providers
+ * invalidates vectors exactly like switching local models — no special cases.
+ *
+ * Local transformers.js stays the zero-config default and the only fully
+ * offline path; providers are opt-in via explicit flags.
+ */
+import { loadApiKeyFile } from './serve.js';
+import { ModelAdapter } from './models.js';
+
+export type EmbedderRole = 'query' | 'passage';
+export type ExternalEmbedFn = (
+  texts: string[],
+  role: EmbedderRole,
+  model: ModelAdapter,
+  cacheDir: string,
+  offline: boolean,
+) => Promise<number[][]>;
+
+export interface ProviderConfig {
+  embedder: 'ollama' | 'openai';
+  /** Provider-side model name, e.g. `nomic-embed-text` or `text-embedding-3-small`. */
+  model: string;
+  baseUrl?: string;
+  keyFile?: string;
+  /** Injected fetch for tests; defaults to globalThis.fetch. */
+  fetchImpl?: typeof fetch;
+}
+
+export interface ResolvedEmbedder {
+  id: string;
+  model: string;
+  embedFn: ExternalEmbedFn;
+  /** Synthetic adapter (probes the endpoint once for dim). Await before indexing. */
+  descriptor(): Promise<ModelAdapter>;
+}
+
+function baseOf(cfg: ProviderConfig): string {
+  const raw =
+    cfg.baseUrl ||
+    (cfg.embedder === 'ollama' ? process.env.OLLAMA_HOST || 'http://127.0.0.1:11434' : 'https://api.openai.com/v1');
+  return raw.replace(/\/$/, '');
+}
+
+function bearerKey(cfg: ProviderConfig): string | undefined {
+  if (cfg.embedder !== 'openai') return undefined;
+  if (cfg.keyFile) return loadApiKeyFile(cfg.keyFile);
+  return process.env.OPENAI_API_KEY || undefined;
+}
+
+async function postJson(fetchImpl: typeof fetch, url: string, headers: Record<string, string>, body: unknown): Promise<any> {
+  const res = await fetchImpl(url, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', ...headers },
+    body: JSON.stringify(body),
+  });
+  if (!res.ok) {
+    const text = await res.text().catch(() => '');
+    throw new Error(`embedder ${url} -> HTTP ${res.status}${text ? `: ${text.slice(0, 200)}` : ''}`);
+  }
+  return res.json();
+}
+
+/** Build an external embedder; dim is probed once on first use and cached. */
+export function resolveExternalEmbedder(cfg: ProviderConfig): ResolvedEmbedder {
+  const fetchImpl = cfg.fetchImpl ?? globalThis.fetch;
+  if (typeof fetchImpl !== 'function') throw new Error('embedder: no fetch implementation available');
+  let cachedDim = 0;
+
+  const embedOneBatch = async (texts: string[]): Promise<number[][]> => {
+    if (cfg.embedder === 'ollama') {
+      const data = await postJson(fetchImpl, `${baseOf(cfg)}/api/embed`, {}, { model: cfg.model, input: texts });
+      const embs = data?.embeddings;
+      if (!Array.isArray(embs) || embs.length !== texts.length) {
+        throw new Error('ollama /api/embed returned unexpected shape');
+      }
+      return embs;
+    }
+    // OpenAI-compatible
+    const headers: Record<string, string> = {};
+    const key = bearerKey(cfg);
+    if (key) headers.authorization = `Bearer ${key}`;
+    const data = await postJson(fetchImpl, `${baseOf(cfg)}/embeddings`, headers, {
+      model: cfg.model,
+      input: texts,
+    });
+    const rows = data?.data;
+    if (!Array.isArray(rows) || rows.length !== texts.length) {
+      throw new Error('openai /embeddings returned unexpected shape');
+    }
+    return rows
+      .slice()
+      .sort((a: any, b: any) => a.index - b.index)
+      .map((r: any) => r.embedding);
+  };
+
+  const embedFn: ExternalEmbedFn = async (texts, _role) => {
+    if (texts.length === 0) return [];
+    const out = await embedOneBatch(texts);
+    if (cachedDim === 0 && out[0]?.length) cachedDim = out[0].length;
+    return out;
+  };
+
+  // Dim probing: one tiny request at resolve time keeps index metadata honest
+  // without hardcoding per-model tables.
+  const descriptorPromise = (async (): Promise<ModelAdapter> => {
+    const probe = await embedOneBatch(['dim probe']);
+    cachedDim = probe[0]?.length ?? 0;
+    if (!cachedDim) throw new Error(`embedder ${cfg.embedder}:${cfg.model} returned an empty embedding`);
+    return {
+      id: `${cfg.embedder}/${cfg.model}`,
+      nativeDim: cachedDim,
+      dim: cachedDim,
+      queryPrefix: '',
+      passagePrefix: '',
+      pooling: 'mean',
+      normalize: false, // never assume; cosine still works on unnormalized vectors
+      family: cfg.embedder,
+    };
+  })();
+
+  return {
+    id: cfg.embedder,
+    model: cfg.model,
+    embedFn,
+    descriptor: () => descriptorPromise,
+  };
+}

package/src/query-cache-disk.ts

@@ -0,0 +1,191 @@
+/**
+ * Disk-backed persistent query-embedding cache (issue #114).
+ *
+ * The in-memory QueryEmbeddingCache only helps long-lived processes; every
+ * fresh `mdss search` paid full embedding latency. This module adds an L2
+ * layer under it: an LRU (512 entries) persisted to `<cacheDir>/query-cache.json`
+ * keyed by model@revision|dim|sha256(query) — the same identity the memory
+ * cache uses, hashed for compactness.
+ *
+ * Integrity mirrors vectors.bin: atomic tmp+rename write plus a `.sha256`
+ * sidecar. A missing/corrupt pair is silently ignored and rebuilt — a broken
+ * cache must never fail a search.
+ */
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const QUERY_CACHE_FILE = 'query-cache.json';
+export const QUERY_CACHE_MAX_ENTRIES = 512;
+
+export function buildDiskKey(modelId: string, revision: string, dim: number | undefined, query: string): string {
+  const norm = query.trim().toLowerCase();
+  return `${modelId}@${revision || 'main'}|${dim ?? 0}|${crypto.createHash('sha256').update(norm).digest('hex')}`;
+}
+
+interface StoredEntry {
+  /** base64 little-endian Float32 payload (encodeVec format). */
+  vec: string;
+  dim: number;
+  ts: number;
+}
+
+interface CacheFile {
+  version: 1;
+  entries: Record<string, StoredEntry>;
+}
+
+/** Per-directory in-process state: loaded entries + dirty flag. */
+const states = new Map<string, { entries: Map<string, StoredEntry>; dirty: boolean; timer?: NodeJS.Timeout }>();
+
+function stateFor(cacheDir: string) {
+  let st = states.get(cacheDir);
+  if (!st) {
+    st = { entries: loadFromDisk(cacheDir), dirty: false };
+    states.set(cacheDir, st);
+  }
+  return st;
+}
+
+function filePaths(cacheDir: string) {
+  const file = path.join(cacheDir, QUERY_CACHE_FILE);
+  return { file, sha: `${file}.sha256`, tmp: `${file}.tmp-${process.pid}` };
+}
+
+function loadFromDisk(cacheDir: string): Map<string, StoredEntry> {
+  const out = new Map<string, StoredEntry>();
+  const { file, sha } = filePaths(cacheDir);
+  let raw: Buffer;
+  try {
+    raw = fs.readFileSync(file);
+  } catch {
+    return out;
+  }
+  try {
+    if (fs.existsSync(sha)) {
+      const expected = fs.readFileSync(sha, 'utf8').trim().split(/\s+/)[0];
+      const actual = crypto.createHash('sha256').update(raw).digest('hex');
+      if (!expected || expected !== actual) return out; // corrupt → silent rebuild
+    }
+    const parsed = JSON.parse(raw.toString('utf8')) as CacheFile;
+    if (parsed.version !== 1 || typeof parsed.entries !== 'object') return out;
+    for (const [key, e] of Object.entries(parsed.entries)) {
+      if (
+        typeof key === 'string' &&
+        typeof e?.vec === 'string' &&
+        Number.isInteger(e?.dim) &&
+        (e.dim as number) > 0 &&
+        Number.isFinite(e?.ts)
+      ) {
+        out.set(key, { vec: e.vec, dim: e.dim, ts: e.ts });
+      }
+    }
+  } catch {
+    return new Map(); // any corruption → treat as empty; next flush overwrites
+  }
+  return out;
+}
+
+function flushSync(cacheDir: string): void {
+  const st = states.get(cacheDir);
+  if (!st || !st.dirty) return;
+  // LRU trim before writing
+  const sorted = [...st.entries.entries()].sort((a, b) => b[1].ts - a[1].ts);
+  st.entries = new Map(sorted.slice(0, QUERY_CACHE_MAX_ENTRIES));
+  const payload: CacheFile = {
+    version: 1,
+    entries: Object.fromEntries(st.entries),
+  };
+  const body = Buffer.from(JSON.stringify(payload));
+  const digest = crypto.createHash('sha256').update(body).digest('hex');
+  const { file, sha, tmp } = filePaths(cacheDir);
+  try {
+    fs.mkdirSync(cacheDir, { recursive: true });
+    fs.writeFileSync(tmp, body);
+    fs.renameSync(tmp, file);
+    fs.writeFileSync(`${sha}.tmp`, `${digest}  ${QUERY_CACHE_FILE}\n`);
+    fs.renameSync(`${sha}.tmp`, sha);
+    st.dirty = false;
+  } catch {
+    /* unwritable cacheDir is non-fatal by design */
+  }
+}
+
+function scheduleFlush(cacheDir: string): void {
+  const st = stateFor(cacheDir);
+  if (st.timer) return;
+  st.timer = setTimeout(() => {
+    st.timer = undefined;
+    flushSync(cacheDir);
+  }, 400);
+  st.timer.unref?.();
+}
+
+// best-effort flush on process exit so one-shot CLI runs persist their queries
+let exitHookInstalled = false;
+function ensureExitHook(): void {
+  if (exitHookInstalled) return;
+  exitHookInstalled = true;
+  process.on('exit', () => {
+    for (const dir of states.keys()) flushSync(dir);
+  });
+}
+
+/**
+ * Look up a query vector on disk. Returns null on any miss/corruption —
+ * callers fall through to embedding without ceremony.
+ */
+export function diskQueryGet(
+  cacheDir: string | undefined,
+  key: string,
+  expectedDim: number | undefined,
+): Float32Array | null {
+  if (!cacheDir) return null;
+  const st = stateFor(cacheDir);
+  const e = st.entries.get(key);
+  if (!e) return null;
+  try {
+    const buf = Buffer.from(e.vec, 'base64');
+    if (buf.byteLength !== e.dim * 4) return null;
+    const arr = new Float32Array(buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength));
+    if (expectedDim !== undefined && arr.length !== expectedDim) return null;
+    for (const x of arr) if (!Number.isFinite(x)) return null;
+    e.ts = Date.now(); // LRU touch
+    st.dirty = true;
+    scheduleFlush(cacheDir);
+    return arr;
+  } catch {
+    st.entries.delete(key);
+    return null;
+  }
+}
+
+/** Store a computed query vector (fire-and-forget, debounced flush). */
+export function diskQueryPut(
+  cacheDir: string | undefined,
+  key: string,
+  vec: number[] | Float32Array,
+): void {
+  if (!cacheDir) return;
+  const f32 = vec instanceof Float32Array ? vec : Float32Array.from(vec);
+  const st = stateFor(cacheDir);
+  st.entries.set(key, {
+    vec: Buffer.from(f32.buffer, f32.byteOffset, f32.byteLength).toString('base64'),
+    dim: f32.length,
+    ts: Date.now(),
+  });
+  st.dirty = true;
+  ensureExitHook();
+  scheduleFlush(cacheDir);
+}
+
+/** Test helper: force-write now. */
+export function flushQueryCacheNow(cacheDir: string): void {
+  flushSync(cacheDir);
+}
+
+/** Test helper: forget in-process state so the next get/put reloads from disk. */
+export function resetQueryCacheForTest(cacheDir?: string): void {
+  if (cacheDir) states.delete(cacheDir);
+  else states.clear();
+}