@kb-labs/mind-core 2.93.0 → 2.96.0

package/dist/index.js

@@ -1,579 +1,1404 @@
-export * from '@kb-labs/mind-types';
-import { createHash } from 'crypto';
-import path, { dirname } from 'path';
-import { existsSync, promises } from 'fs';
+import { AgentResponseSchema, resolveScope, effectiveIndexConfig, MIND_NAMESPACE_PREFIX } from '@kb-labs/mind-contracts';
 import { readFile } from 'fs/promises';
+import path, { join } from 'path';
+import globby from 'globby';
+import { statSync, openSync, readSync, closeSync } from 'fs';
 
-// src/index.ts
+// src/mind.ts
 
-// src/error/mind-error.ts
-var MindError = class extends Error {
-  constructor(code, message, hint, meta) {
-    super(message);
-    this.code = code;
-    this.hint = hint;
-    this.meta = meta;
-    this.name = "MindError";
+// src/types.ts
+function chunkId(path2, startLine, endLine) {
+  return `${path2}#${startLine}-${endLine}`;
+}
+function hashContent(text) {
+  let h = 2166136261;
+  for (let i = 0; i < text.length; i++) {
+    h ^= text.charCodeAt(i);
+    h = Math.imul(h, 16777619);
   }
-  code;
-  hint;
-  meta;
-};
-function getExitCode(err) {
-  if (err.code === "MIND_FORBIDDEN") {
-    return 3;
+  return (h >>> 0).toString(16);
+}
+function kindFromPath(path2) {
+  const lower = path2.toLowerCase();
+  if (lower.includes("/adr/") || /adr-\d+/.test(lower)) {
+    return "adr";
   }
-  if (err.code === "MIND_NO_GIT") {
-    return 2;
+  if (lower.endsWith(".md") || lower.endsWith(".mdx") || lower.endsWith(".txt")) {
+    return "doc";
   }
-  if (err.code === "MIND_FS_TIMEOUT") {
-    return 2;
+  if (lower.endsWith(".json") || lower.endsWith(".yaml") || lower.endsWith(".yml") || lower.endsWith(".toml")) {
+    return "config";
   }
-  if (err.code === "MIND_PARSE_ERROR") {
-    return 1;
+  return "code";
+}
+var IGNORE = [
+  "**/node_modules/**",
+  "**/dist/**",
+  "**/build/**",
+  "**/out/**",
+  "**/coverage/**",
+  "**/.git/**",
+  "**/.kb/**",
+  "**/bin/**",
+  "**/obj/**",
+  "**/.next/**",
+  "**/.nuxt/**",
+  "**/vendor/**",
+  "**/__pycache__/**"
+];
+var DENY_EXT = /* @__PURE__ */ new Set([
+  "png",
+  "jpg",
+  "jpeg",
+  "gif",
+  "svg",
+  "ico",
+  "webp",
+  "bmp",
+  "tif",
+  "tiff",
+  "avif",
+  "mp4",
+  "mov",
+  "avi",
+  "webm",
+  "mp3",
+  "wav",
+  "ogg",
+  "flac",
+  "pdf",
+  "woff",
+  "woff2",
+  "ttf",
+  "eot",
+  "otf",
+  "zip",
+  "gz",
+  "tgz",
+  "bz2",
+  "xz",
+  "tar",
+  "rar",
+  "7z",
+  "exe",
+  "dll",
+  "so",
+  "dylib",
+  "bin",
+  "wasm",
+  "class",
+  "node",
+  "pdb",
+  "xlsx",
+  "xls",
+  "docx",
+  "doc",
+  "pptx",
+  "ppt",
+  "parquet",
+  "db",
+  "sqlite",
+  "map",
+  "min.js",
+  "min.css",
+  "snap",
+  // Bulk data / logs / dumps — text, but no semantic value and they bloat the
+  // index + embedding cost (the old extension allowlist excluded these by omission).
+  "csv",
+  "tsv",
+  "ndjson",
+  "jsonl",
+  "log",
+  "sql",
+  "dump",
+  "out"
+]);
+var DENY_FILE = /* @__PURE__ */ new Set([
+  "package-lock.json",
+  "pnpm-lock.yaml",
+  "yarn.lock",
+  "go.sum",
+  "Cargo.lock",
+  "composer.lock"
+]);
+var MAX_BYTES = 512 * 1024;
+function extOf(file) {
+  const name = file.slice(file.lastIndexOf("/") + 1).toLowerCase();
+  if (name.endsWith(".min.js")) {
+    return "min.js";
   }
-  if (err.code === "MIND_PACK_BUDGET_EXCEEDED") {
-    return 1;
+  if (name.endsWith(".min.css")) {
+    return "min.css";
   }
-  if (err.code.startsWith("MIND_")) {
-    return 1;
+  const dot = name.lastIndexOf(".");
+  return dot === -1 ? "" : name.slice(dot + 1);
+}
+function isBinary(abs) {
+  let fd;
+  try {
+    fd = openSync(abs, "r");
+    const buf = Buffer.alloc(4096);
+    const n = readSync(fd, buf, 0, buf.length, 0);
+    for (let i = 0; i < n; i++) {
+      if (buf[i] === 0) {
+        return true;
+      }
+    }
+    return false;
+  } catch {
+    return true;
+  } finally {
+    if (fd !== void 0) {
+      closeSync(fd);
+    }
   }
-  return 1;
-}
-var ERROR_HINTS = {
-  MIND_NO_GIT: "Initialize git repository or run from a git repository",
-  MIND_FS_TIMEOUT: "File system operation timed out - try increasing time budget",
-  MIND_PARSE_ERROR: "Failed to parse file - check syntax and try again",
-  MIND_PACK_BUDGET_EXCEEDED: "Context pack exceeds token budget - reduce content or increase budget",
-  MIND_FORBIDDEN: "Operation not permitted - check file permissions",
-  MIND_TIME_BUDGET: "Time budget exceeded - operation completed partially",
-  MIND_BAD_FLAGS: "Invalid command line flags - check values and try again",
-  MIND_INVALID_FLAG: "Invalid flag value - check format and try again",
-  MIND_BUNDLE_TIMEOUT: "Bundle operation timed out - skipped bundle information",
-  MIND_FEED_ERROR: "Mind feed operation failed - check logs for details",
-  MIND_INIT_ERROR: "Mind initialization failed - check permissions and try again",
-  MIND_UPDATE_ERROR: "Mind update operation failed - check logs for details",
-  MIND_PACK_ERROR: "Mind pack operation failed - check logs for details",
-  MIND_GIT_ERROR: "Git operation failed - check git repository status",
-  MIND_INDEX_NOT_FOUND: 'Mind indexes not found - run "kb mind init" first',
-  MIND_INVALID_PATH: "Invalid file or directory path - check path exists and is accessible",
-  MIND_DEPENDENCY_ERROR: "Dependency resolution failed - check package configuration",
-  MIND_BUILD_ERROR: "Build operation failed - check configuration and try again"
-};
-function createMindError(code, message, meta) {
-  return new MindError(code, message, ERROR_HINTS[code], meta);
-}
-function wrapError(error, code = "MIND_FEED_ERROR") {
-  if (error instanceof MindError) {
-    return error;
-  }
-  const message = error instanceof Error ? error.message : String(error);
-  return createMindError(code, message, { originalError: error });
-}
-function isMindError(error) {
-  return error instanceof MindError;
-}
-
-// src/utils/token.ts
-var DefaultTokenEstimator = class {
-  charsPerToken = 4;
-  codeBonus = 0.1;
-  // 10% bonus for code-like content
-  punctuationWeight = 0.8;
-  estimate(text) {
-    if (!text || text.length === 0) {
-      return 0;
-    }
-    const words = text.match(/\b\w+\b/g) || [];
-    const punctuation = text.match(/[^\w\s]/g) || [];
-    const whitespace = text.match(/\s/g) || [];
-    let tokens = words.length;
-    tokens += punctuation.length * this.punctuationWeight;
-    tokens += whitespace.length * 0.3;
-    const codeIndicators = text.match(/[{}();=<>]/g) || [];
-    if (codeIndicators.length > words.length * 0.1) {
-      tokens *= 1 + this.codeBonus;
-    }
-    const charBasedEstimate = text.length / this.charsPerToken;
-    return Math.ceil(Math.max(tokens, charBasedEstimate));
-  }
-  truncate(text, maxTokens, mode) {
-    if (this.estimate(text) <= maxTokens) {
-      return text;
-    }
-    const lines = text.split("\n");
-    const estimatedTokens = this.estimate(text);
-    const ratio = maxTokens / estimatedTokens;
-    const targetLines = Math.max(1, Math.floor(lines.length * ratio));
-    if (targetLines >= lines.length) {
-      return text;
-    }
-    switch (mode) {
-      case "start":
-        return lines.slice(0, targetLines).join("\n");
-      case "end":
-        return lines.slice(-targetLines).join("\n");
-      case "middle":
-      default: {
-        const startLines = Math.max(1, Math.floor(targetLines / 2));
-        const endLines = Math.max(1, targetLines - startLines);
-        const start = lines.slice(0, startLines);
-        const end = lines.slice(-endLines);
-        return [...start, "...", ...end].join("\n");
+}
+function trimTrailingSlashes(s) {
+  let end = s.length;
+  while (end > 0 && s.charCodeAt(end - 1) === 47) {
+    end--;
+  }
+  return s.slice(0, end);
+}
+async function discover(cwd, scope) {
+  const include = scope?.include && scope.include.length > 0 ? scope.include : ["."];
+  const exclude = scope?.exclude ?? [];
+  const patterns = include.map((p) => {
+    const base = p && p !== "." ? trimTrailingSlashes(p) : "";
+    return base ? `${base}/**/*` : "**/*";
+  });
+  const candidates = await globby(patterns, {
+    cwd,
+    ignore: [...IGNORE, ...exclude],
+    dot: false,
+    followSymbolicLinks: false,
+    gitignore: false,
+    onlyFiles: true
+  });
+  return candidates.filter((rel) => {
+    if (DENY_FILE.has(rel.slice(rel.lastIndexOf("/") + 1))) {
+      return false;
+    }
+    if (DENY_EXT.has(extOf(rel))) {
+      return false;
+    }
+    const abs = path.join(cwd, rel);
+    try {
+      const st = statSync(abs);
+      if (st.size === 0 || st.size > MAX_BYTES) {
+        return false;
       }
+    } catch {
+      return false;
     }
+    return !isBinary(abs);
+  });
+}
+
+// src/ingest/chunk.ts
+function approxTokens(line) {
+  const t = line.trim();
+  if (t === "") {
+    return 0;
   }
-};
-var defaultTokenEstimator = new DefaultTokenEstimator();
-function estimateTokens(text) {
-  return defaultTokenEstimator.estimate(text);
-}
-function truncateToTokens(text, maxTokens, mode = "middle") {
-  return defaultTokenEstimator.truncate(text, maxTokens, mode);
-}
-function sha256(content) {
-  return createHash("sha256").update(content, "utf8").digest("hex");
-}
-function sha256Buffer(buffer) {
-  return createHash("sha256").update(buffer).digest("hex");
-}
-async function sha256File(filePath) {
-  const { readFile: readFile2 } = await import('fs/promises');
-  const content = await readFile2(filePath);
-  return sha256Buffer(content);
-}
-function toPosix(filePath) {
-  return filePath.replace(/\\/g, "/");
-}
-function fromPosix(posixPath) {
-  return posixPath.split("/").join(path.sep);
-}
-async function findWorkspaceRoot(cwd) {
-  let current = path.resolve(cwd);
-  const root = path.parse(current).root;
-  while (current !== root) {
-    if (existsSync(path.join(current, ".git"))) {
-      return toPosix(current);
-    }
-    const packageJsonPath = path.join(current, "package.json");
-    if (existsSync(packageJsonPath)) {
-      try {
-        const packageJsonContent = await readFile(packageJsonPath, "utf8");
-        const packageJson = JSON.parse(packageJsonContent);
-        if (packageJson.workspaces || packageJson.pnpm?.workspace) {
-          return toPosix(current);
-        }
-      } catch {
+  return t.split(/\s+/).length;
+}
+function slidingWindowChunks(path2, content, opts) {
+  const lines = content.split("\n");
+  const kind = kindFromPath(path2);
+  const chunks = [];
+  const maxTokens = Math.max(1, opts.maxTokens);
+  const overlapTokens = Math.max(0, Math.min(opts.overlapTokens, maxTokens - 1));
+  let startIdx = 0;
+  while (startIdx < lines.length) {
+    let tokens = 0;
+    let endIdx = startIdx;
+    while (endIdx < lines.length && tokens < maxTokens) {
+      tokens += approxTokens(lines[endIdx] ?? "");
+      endIdx++;
+    }
+    const startLine = startIdx + 1;
+    const endLine = endIdx;
+    const text = lines.slice(startIdx, endIdx).join("\n");
+    if (text.trim() !== "") {
+      chunks.push({ id: chunkId(path2, startLine, endLine), path: path2, startLine, endLine, text, kind });
+    }
+    if (endIdx >= lines.length) {
+      break;
+    }
+    let overlap = 0;
+    let stepBack = 0;
+    let i = endIdx - 1;
+    while (i > startIdx && overlap < overlapTokens) {
+      overlap += approxTokens(lines[i] ?? "");
+      stepBack++;
+      i--;
+    }
+    startIdx = Math.max(startIdx + 1, endIdx - stepBack);
+  }
+  return chunks;
+}
+
+// src/ingest/structural.ts
+var DECL_KEYWORDS = /* @__PURE__ */ new Set([
+  "function",
+  "class",
+  "interface",
+  "type",
+  "enum",
+  "const",
+  "let",
+  "var",
+  "namespace",
+  "module",
+  "def",
+  "func",
+  "fn",
+  "impl",
+  "struct",
+  "trait",
+  "public",
+  "private"
+]);
+var MODIFIERS = /* @__PURE__ */ new Set([
+  "export",
+  "default",
+  "declare",
+  "public",
+  "private",
+  "protected",
+  "static",
+  "abstract",
+  "async"
+]);
+function isBoundaryLine(line) {
+  if (line.length === 0 || line.charCodeAt(0) === 32 || line.charCodeAt(0) === 9) {
+    return false;
+  }
+  for (const word of line.split(/\s+/)) {
+    if (DECL_KEYWORDS.has(word)) {
+      return true;
+    }
+    if (!MODIFIERS.has(word)) {
+      return false;
+    }
+  }
+  return false;
+}
+function approxTokens2(text) {
+  const t = text.trim();
+  return t === "" ? 0 : t.split(/\s+/).length;
+}
+function structuralChunks(path2, content, opts) {
+  const lines = content.split("\n");
+  const kind = kindFromPath(path2);
+  const boundaries = [];
+  lines.forEach((line, i) => {
+    if (isBoundaryLine(line)) {
+      boundaries.push(i);
+    }
+  });
+  if (boundaries.length === 0) {
+    return slidingWindowChunks(path2, content, opts);
+  }
+  const starts = [.../* @__PURE__ */ new Set([0, ...boundaries])].sort((a, b) => a - b);
+  const chunks = [];
+  for (let b = 0; b < starts.length; b++) {
+    const from = starts[b];
+    const to = b + 1 < starts.length ? starts[b + 1] : lines.length;
+    const blockLines = lines.slice(from, to);
+    const blockText = blockLines.join("\n");
+    if (blockText.trim() === "") {
+      continue;
+    }
+    if (approxTokens2(blockText) > opts.maxTokens) {
+      for (const sub of slidingWindowChunks(path2, blockText, opts)) {
+        const startLine = from + sub.startLine;
+        const endLine = from + sub.endLine;
+        chunks.push({ id: chunkId(path2, startLine, endLine), path: path2, startLine, endLine, text: sub.text, kind });
       }
+    } else {
+      const startLine = from + 1;
+      const endLine = to;
+      chunks.push({ id: chunkId(path2, startLine, endLine), path: path2, startLine, endLine, text: blockText, kind });
     }
-    if (existsSync(path.join(current, "pnpm-workspace.yaml"))) {
-      return toPosix(current);
-    }
-    current = path.dirname(current);
-  }
-  return toPosix(cwd);
-}
-function makeRelativeToRoot(absolutePath, root) {
-  const relative = path.relative(root, absolutePath);
-  return toPosix(relative);
-}
-function shouldIgnorePath(filePath) {
-  const posixPath = toPosix(filePath);
-  const ignorePatterns = [
-    "node_modules/**",
-    ".git/**",
-    ".kb/**",
-    // except .kb/mind/**
-    "dist/**",
-    "coverage/**",
-    ".turbo/**",
-    ".vite/**",
-    "**/*.log",
-    "**/*.tmp",
-    "**/*.temp"
-  ];
-  const extensionPatterns = [".log", ".tmp", ".temp"];
-  if (posixPath.startsWith(".kb/") && !posixPath.startsWith(".kb/mind/")) {
-    return true;
   }
-  if (posixPath.startsWith(".kb/mind/")) {
+  return chunks;
+}
+function chunkFile(path2, content, opts, ast) {
+  if (ast && kindFromPath(path2) === "code") {
+    return structuralChunks(path2, content, opts);
+  }
+  return slidingWindowChunks(path2, content, opts);
+}
+
+// src/ingest/embed.ts
+var MAX_BATCH_CHUNKS = 96;
+var MAX_BATCH_TOKENS = 2e5;
+var MAX_INPUT_CHARS = 12e3;
+var CHARS_PER_TOKEN = 4;
+var approxTokens3 = (text) => Math.ceil(text.length / CHARS_PER_TOKEN);
+function toRecord(chunk, vector, text) {
+  const meta = {
+    path: chunk.path,
+    startLine: chunk.startLine,
+    endLine: chunk.endLine,
+    text,
+    kind: chunk.kind
+  };
+  return { id: chunk.id, vector, metadata: meta };
+}
+function planBatches(chunks) {
+  const items = chunks.map((c) => ({
+    chunk: c,
+    text: c.text.length > MAX_INPUT_CHARS ? c.text.slice(0, MAX_INPUT_CHARS) : c.text
+  }));
+  const batches = [];
+  let cur = [];
+  let curTokens = 0;
+  for (const item of items) {
+    const t = approxTokens3(item.text);
+    if (cur.length > 0 && (cur.length >= MAX_BATCH_CHUNKS || curTokens + t > MAX_BATCH_TOKENS)) {
+      batches.push(cur);
+      cur = [];
+      curTokens = 0;
+    }
+    cur.push(item);
+    curTokens += t;
+  }
+  if (cur.length > 0) {
+    batches.push(cur);
+  }
+  return batches;
+}
+async function embedChunks(chunks, embeddings, onProgress) {
+  if (chunks.length === 0) {
+    return [];
+  }
+  const records = [];
+  for (const batch of planBatches(chunks)) {
+    const vectors = await embeddings.embedBatch(batch.map((b) => b.text));
+    batch.forEach((b, j) => records.push(toRecord(b.chunk, vectors[j] ?? [], b.chunk.text)));
+    onProgress?.(records.length, chunks.length);
+  }
+  return records;
+}
+function manifestPath(indexId) {
+  return `mind/${indexId}/manifest.json`;
+}
+async function isStale(manifest, file, cwd) {
+  const entry = manifest.files[file];
+  if (!entry) {
     return false;
   }
-  if (extensionPatterns.some((ext) => posixPath.endsWith(ext))) {
+  try {
+    const content = await readFile(join(cwd, file), "utf8");
+    return hashContent(content) !== entry.hash;
+  } catch {
     return true;
   }
-  return ignorePatterns.some((pattern) => {
-    if (pattern.endsWith("/**")) {
-      const prefix = pattern.slice(0, -3);
-      return posixPath.startsWith(prefix + "/") || posixPath === prefix;
+}
+async function staleMap(manifest, files, cwd) {
+  const out = /* @__PURE__ */ new Map();
+  await Promise.all(
+    [...new Set(files)].map(async (f) => {
+      out.set(f, await isStale(manifest, f, cwd));
+    })
+  );
+  return out;
+}
+async function staleCount(manifest, cwd) {
+  const flags = await staleMap(manifest, Object.keys(manifest.files), cwd);
+  return [...flags.values()].filter(Boolean).length;
+}
+async function manifestExists(storage, indexId) {
+  return Boolean(await storage.read(manifestPath(indexId)));
+}
+async function loadManifest(storage, indexId) {
+  const buf = await storage.read(manifestPath(indexId));
+  if (!buf) {
+    return { indexId, chunks: [], files: {}, updatedAt: null };
+  }
+  try {
+    const parsed = JSON.parse(buf.toString("utf8"));
+    return { indexId, chunks: parsed.chunks ?? [], files: parsed.files ?? {}, updatedAt: parsed.updatedAt ?? null };
+  } catch {
+    return { indexId, chunks: [], files: {}, updatedAt: null };
+  }
+}
+async function saveManifest(storage, manifest) {
+  const buf = Buffer.from(JSON.stringify(manifest), "utf8");
+  await storage.write(manifestPath(manifest.indexId), buf);
+}
+async function deleteManifest(storage, indexId) {
+  await storage.delete(manifestPath(indexId));
+}
+
+// src/ingest/ingest.ts
+async function readAndHash(cwd, paths, logger) {
+  const contentByPath = /* @__PURE__ */ new Map();
+  const hashByPath = /* @__PURE__ */ new Map();
+  for (const path2 of paths) {
+    let content;
+    try {
+      content = await readFile(join(cwd, path2), "utf8");
+    } catch (err) {
+      logger?.warn("mind: skipped unreadable file", { path: path2, reason: err instanceof Error ? err.message : String(err) });
+      continue;
     }
-    if (pattern.endsWith("**")) {
-      const prefix = pattern.slice(0, -2);
-      return posixPath.startsWith(prefix);
+    contentByPath.set(path2, content);
+    hashByPath.set(path2, hashContent(content));
+  }
+  return { contentByPath, hashByPath };
+}
+function classify(contentByPath, hashByPath, prevFiles) {
+  const toIndex = [];
+  const unchanged = [];
+  let added = 0;
+  let updated = 0;
+  for (const path2 of contentByPath.keys()) {
+    const prevEntry = prevFiles[path2];
+    if (prevEntry && prevEntry.hash === hashByPath.get(path2)) {
+      unchanged.push(path2);
+    } else {
+      toIndex.push(path2);
+      if (prevEntry) {
+        updated++;
+      } else {
+        added++;
+      }
     }
-    if (pattern.startsWith("**/")) {
-      const suffix = pattern.slice(3);
-      return posixPath.endsWith(suffix);
+  }
+  const removedPaths = Object.keys(prevFiles).filter((p) => !contentByPath.has(p));
+  return { toIndex, unchanged, removedPaths, added, updated };
+}
+async function ingest(input, services) {
+  const { storage, embeddings, vectorStore } = services;
+  const prev = await loadManifest(storage, input.indexId);
+  const prevFiles = input.full ? {} : prev.files;
+  const emit = input.onProgress ?? (() => {
+  });
+  const paths = await discover(input.cwd, input.scope);
+  emit({ stage: "discover", files: paths.length });
+  const { contentByPath, hashByPath } = await readAndHash(input.cwd, paths, services.logger);
+  const { toIndex, unchanged, removedPaths, added, updated } = classify(contentByPath, hashByPath, prevFiles);
+  emit({ stage: "delta", toIndex: toIndex.length, unchanged: unchanged.length, removed: removedPaths.length });
+  const stalePaths = new Set(input.full ? Object.keys(prev.files) : [...toIndex, ...removedPaths]);
+  const staleIds = (input.full ? prev.chunks : prev.chunks.filter((c) => stalePaths.has(c.path))).map((c) => c.id);
+  if (staleIds.length > 0) {
+    await vectorStore.delete(staleIds, input.indexId);
+  }
+  const unchangedSet = new Set(unchanged);
+  const keptChunks = input.full ? [] : prev.chunks.filter((c) => unchangedSet.has(c.path));
+  const files = {};
+  for (const path2 of unchanged) {
+    files[path2] = prevFiles[path2];
+  }
+  const newChunks = [];
+  for (const path2 of toIndex) {
+    const chunks = chunkFile(path2, contentByPath.get(path2), input.chunk, input.ast);
+    if (chunks.length === 0) {
+      continue;
+    }
+    newChunks.push(...chunks);
+    files[path2] = { chunks: chunks.length, indexedAt: input.now, hash: hashByPath.get(path2) };
+  }
+  emit({ stage: "chunk", chunks: newChunks.length });
+  const records = await embedChunks(
+    newChunks,
+    embeddings,
+    (done, total) => emit({ stage: "embed", done, total })
+  );
+  if (records.length > 0) {
+    emit({ stage: "upsert", count: records.length });
+    await vectorStore.upsert(records, input.indexId);
+  }
+  emit({ stage: "save" });
+  const manifest = {
+    indexId: input.indexId,
+    chunks: [...keptChunks, ...newChunks],
+    files,
+    updatedAt: input.now
+  };
+  await saveManifest(storage, manifest);
+  return {
+    filesIndexed: Object.keys(files).length,
+    chunks: manifest.chunks.length,
+    added,
+    updated,
+    removed: removedPaths.length,
+    unchanged: unchanged.length
+  };
+}
+async function removePaths(manifest, paths, services, indexId) {
+  const removedIds = manifest.chunks.filter((c) => paths.has(c.path)).map((c) => c.id);
+  if (removedIds.length > 0) {
+    await services.vectorStore.delete(removedIds, indexId);
+  }
+  manifest.chunks = manifest.chunks.filter((c) => !paths.has(c.path));
+  for (const p of paths) {
+    delete manifest.files[p];
+  }
+  return removedIds.length;
+}
+async function addPaths(manifest, paths, services, opts) {
+  const newChunks = [];
+  for (const path2 of paths) {
+    let content;
+    try {
+      content = await readFile(join(opts.cwd, path2), "utf8");
+    } catch {
+      continue;
     }
-    if (pattern.includes("*")) {
-      let regexPattern = pattern.replace(/\*\*/g, ".*").replace(/\*/g, "[^/]*");
-      if (pattern.startsWith("**/")) {
-        regexPattern = ".*" + regexPattern.slice(3);
+    const chunks = chunkFile(path2, content, opts.chunk, opts.ast);
+    if (chunks.length === 0) {
+      continue;
+    }
+    newChunks.push(...chunks);
+    manifest.files[path2] = { chunks: chunks.length, indexedAt: opts.now, hash: hashContent(content) };
+  }
+  if (newChunks.length > 0) {
+    const records = await embedChunks(newChunks, services.embeddings);
+    await services.vectorStore.upsert(records, opts.indexId);
+    manifest.chunks.push(...newChunks);
+  }
+  return newChunks.length;
+}
+async function syncAdd(paths, services, opts) {
+  const manifest = await loadManifest(services.storage, opts.indexId);
+  const existing = new Set(paths.filter((p) => manifest.files[p]));
+  await removePaths(manifest, existing, services, opts.indexId);
+  await addPaths(manifest, paths, services, opts);
+  manifest.updatedAt = opts.now;
+  await saveManifest(services.storage, manifest);
+  return { added: paths.length - existing.size, updated: existing.size, deleted: 0 };
+}
+async function syncUpdate(paths, services, opts) {
+  const manifest = await loadManifest(services.storage, opts.indexId);
+  await removePaths(manifest, new Set(paths), services, opts.indexId);
+  await addPaths(manifest, paths, services, opts);
+  manifest.updatedAt = opts.now;
+  await saveManifest(services.storage, manifest);
+  return { added: 0, updated: paths.length, deleted: 0 };
+}
+async function syncDelete(paths, services, opts) {
+  const manifest = await loadManifest(services.storage, opts.indexId);
+  const deleted = await removePaths(manifest, new Set(paths), services, opts.indexId);
+  manifest.updatedAt = opts.now;
+  await saveManifest(services.storage, manifest);
+  return { added: 0, updated: 0, deleted };
+}
+
+// src/retrieval/bm25.ts
+var K1 = 1.5;
+var B = 0.75;
+function tokenize(text) {
+  return text.replace(/([a-z0-9])([A-Z])/g, "$1 $2").toLowerCase().split(/[^a-z0-9]+/).filter((t) => t.length > 1);
+}
+function bm25Search(chunks, query, limit) {
+  if (chunks.length === 0) {
+    return [];
+  }
+  const docs = chunks.map((c) => tokenize(c.text));
+  const docLens = docs.map((d) => d.length);
+  const avgDocLen = docLens.reduce((a, b) => a + b, 0) / docs.length || 1;
+  const df = /* @__PURE__ */ new Map();
+  for (const doc of docs) {
+    for (const term of new Set(doc)) {
+      df.set(term, (df.get(term) ?? 0) + 1);
+    }
+  }
+  const queryTerms = [...new Set(tokenize(query))];
+  const N = docs.length;
+  const scored = chunks.map((chunk, i) => {
+    const doc = docs[i] ?? [];
+    const len = docLens[i] ?? 0;
+    const tf = /* @__PURE__ */ new Map();
+    for (const term of doc) {
+      tf.set(term, (tf.get(term) ?? 0) + 1);
+    }
+    let score = 0;
+    for (const term of queryTerms) {
+      const termTf = tf.get(term);
+      if (!termTf) {
+        continue;
       }
-      const regex = new RegExp("^" + regexPattern + "$");
-      return regex.test(posixPath);
+      const docFreq = df.get(term) ?? 0;
+      const idf = Math.log(1 + (N - docFreq + 0.5) / (docFreq + 0.5));
+      const denom = termTf + K1 * (1 - B + B * len / avgDocLen);
+      score += idf * (termTf * (K1 + 1) / denom);
     }
-    return posixPath.includes(pattern);
+    return { id: chunk.id, score };
   });
+  return scored.filter((r) => r.score > 0).sort((a, b) => b.score - a.score).slice(0, limit);
 }
 
-// src/utils/math.ts
-function cosineSimilarity(a, b) {
-  if (a.length !== b.length) {
-    return 0;
+// src/retrieval/vector.ts
+async function vectorSearch(queryText, vectorStore, embed, indexId, limit) {
+  let vector;
+  try {
+    vector = await embed(queryText);
+  } catch (err) {
+    throw new Error(`mind: query embedding failed \u2014 ${err instanceof Error ? err.message : String(err)}`);
   }
-  let dotProduct2 = 0;
-  let normA = 0;
-  let normB = 0;
-  for (let i = 0; i < a.length; i++) {
-    const av = a[i] ?? 0;
-    const bv = b[i] ?? 0;
-    dotProduct2 += av * bv;
-    normA += av * av;
-    normB += bv * bv;
-  }
-  if (normA === 0 || normB === 0) {
-    return 0;
+  try {
+    const hits = await vectorStore.search(vector, limit, void 0, indexId);
+    return hits.map((h) => ({ id: h.id, score: h.score }));
+  } catch (err) {
+    throw new Error(
+      `mind: vector search failed (indexId="${indexId}", dims=${vector.length}) \u2014 ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+}
+
+// src/retrieval/fuse.ts
+function intentWeights(intent) {
+  switch (intent) {
+    case "lookup":
+      return { vector: 0.4, bm25: 0.6 };
+    // exact symbol lookups lean keyword
+    case "architecture":
+      return { vector: 0.6, bm25: 0.4 };
+    case "concept":
+    default:
+      return { vector: 0.7, bm25: 0.3 };
+  }
+}
+function rrfFuse(lists, k) {
+  const scores = /* @__PURE__ */ new Map();
+  const labels = /* @__PURE__ */ new Map();
+  for (const { ranked, weight, label } of lists) {
+    ranked.forEach((item, idx) => {
+      const rank = idx + 1;
+      scores.set(item.id, (scores.get(item.id) ?? 0) + weight * (1 / (k + rank)));
+      if (label) {
+        const set = labels.get(item.id) ?? /* @__PURE__ */ new Set();
+        set.add(label);
+        labels.set(item.id, set);
+      }
+    });
+  }
+  return [...scores.entries()].map(([id, score]) => ({ id, score, matchedBy: resolveMatchedBy(labels.get(id)) })).sort((a, b) => b.score - a.score);
+}
+function resolveMatchedBy(set) {
+  if (!set || set.size === 0 || set.size === 2) {
+    return "both";
+  }
+  return set.has("semantic") ? "semantic" : "lexical";
+}
+
+// src/retrieval/hyde.ts
+var HYDE_PROMPT = (query) => `Write a short, realistic code or documentation snippet that would directly answer the question below. Output only the snippet \u2014 no preamble, no explanation, no fences.
+
+Question: ${query}`;
+async function hypotheticalDocument(query, llm) {
+  try {
+    const { content } = await llm.complete(HYDE_PROMPT(query), { temperature: 0, maxTokens: 256 });
+    const text = (content ?? "").trim();
+    return text === "" ? query : `${text}
+
+${query}`;
+  } catch {
+    return query;
+  }
+}
+
+// src/retrieval/expand.ts
+var EXPAND_PROMPT = (query) => `List code identifiers, function/type names, and close synonyms that would likely appear in source code or documentation relevant to the query below. Output a single space-separated line of terms only \u2014 no explanation, no punctuation, no fences.
+
+Query: ${query}`;
+async function expandQuery(query, llm) {
+  try {
+    const { content } = await llm.complete(EXPAND_PROMPT(query), { temperature: 0, maxTokens: 64 });
+    const extra = (content ?? "").trim();
+    return extra === "" ? query : `${query} ${extra}`;
+  } catch {
+    return query;
   }
-  return dotProduct2 / Math.sqrt(normA * normB);
 }
-function dotProduct(a, b) {
-  if (a.length !== b.length) {
+
+// src/retrieval/retrieve.ts
+async function retrieve(input, services) {
+  const manifest = await loadManifest(services.storage, input.indexId);
+  const byId = new Map(manifest.chunks.map((c) => [c.id, c]));
+  const candidateLimit = Math.max(input.limit * 3, 30);
+  const vectorText = input.hyde ? await hypotheticalDocument(input.text, services.llm) : input.text;
+  const lexicalText = input.expand ? await expandQuery(input.text, services.llm) : input.text;
+  const bm25 = bm25Search(manifest.chunks, lexicalText, candidateLimit);
+  const vector = await vectorSearch(
+    vectorText,
+    services.vectorStore,
+    (t) => services.embeddings.embed(t),
+    input.indexId,
+    candidateLimit
+  );
+  const weights = intentWeights(input.intent);
+  const fused = rrfFuse(
+    [
+      { ranked: vector, weight: weights.vector, label: "semantic" },
+      { ranked: bm25, weight: weights.bm25, label: "lexical" }
+    ],
+    input.rrfK
+  );
+  const ranked = fused.map((r) => {
+    const chunk = byId.get(r.id);
+    return chunk ? { chunk, score: r.score, matchedBy: r.matchedBy } : void 0;
+  }).filter((r) => r !== void 0).slice(0, input.limit);
+  const semanticWinRate = ranked.length === 0 ? 0 : ranked.filter((r) => r.matchedBy === "semantic").length / ranked.length;
+  return { ranked, confidence: confidenceFrom(vector), semanticWinRate };
+}
+function confidenceFrom(vector) {
+  if (vector.length === 0) {
     return 0;
   }
-  let result = 0;
-  for (let i = 0; i < a.length; i++) {
-    result += (a[i] ?? 0) * (b[i] ?? 0);
-  }
-  return result;
-}
-function magnitude(vec) {
-  let sum = 0;
-  for (let i = 0; i < vec.length; i++) {
-    const v = vec[i] ?? 0;
-    sum += v * v;
-  }
-  return Math.sqrt(sum);
-}
-function normalize(vec) {
-  const mag = magnitude(vec);
-  if (mag === 0) {
-    return vec;
-  }
-  return vec.map((v) => (v ?? 0) / mag);
-}
-var FileRotationStore = class {
-  constructor(storage, options = {}) {
-    this.storage = storage;
-    this.basePath = options.basePath ? this.ensureTrailingSlash(options.basePath) : ".kb/mind/store/";
-    this.filePrefix = options.filePrefix ?? "store-";
-    this.maxRecordsPerFile = options.maxRecordsPerFile ?? 1e3;
-    this.maxFiles = options.maxFiles ?? 30;
-  }
-  storage;
-  basePath;
-  filePrefix;
-  maxRecordsPerFile;
-  maxFiles;
-  /**
-   * Append a record to the current writable file
-   *
-   * Automatically handles:
-   * - File rotation when maxRecordsPerFile exceeded
-   * - Cleanup when maxFiles exceeded
-   * - JSONL formatting
-   *
-   * @param record - Record to append
-   */
-  async appendRecord(record) {
-    const target = await this.getWritableFile();
-    const line = JSON.stringify({ v: 1, record }) + "\n";
-    const existing = await this.storage.read(target);
-    const buffer = existing ? Buffer.concat([existing, Buffer.from(line, "utf8")]) : Buffer.from(line, "utf8");
-    await this.storage.write(target, buffer);
-    await this.enforceRotation();
-  }
-  /**
-   * Read records from all files, optionally filtering
-   *
-   * @param filter - Optional filter function
-   * @param limit - Maximum number of records to return
-   * @returns Array of records matching filter
-   */
-  async readRecords(filter, limit) {
-    const files = await this.getFilesSorted();
-    const results = [];
-    for (const file of files) {
-      if (limit && results.length >= limit) {
-        break;
+  const top = vector.slice(0, 3);
+  const avg = top.reduce((a, r) => a + r.score, 0) / top.length;
+  return Math.max(0, Math.min(1, avg));
+}
+
+// src/retrieval/rerank.ts
+function rerank(ranked, query) {
+  const qTokens = new Set(tokenize(query));
+  if (qTokens.size === 0) {
+    return ranked;
+  }
+  const boosted = ranked.map((item) => {
+    const docTokens = tokenize(item.chunk.text);
+    const docSet = new Set(docTokens);
+    let covered = 0;
+    for (const q of qTokens) {
+      if (docSet.has(q)) {
+        covered++;
       }
-      const buf = await this.storage.read(file);
-      if (!buf) {
-        continue;
+    }
+    const coverage = covered / qTokens.size;
+    const lowerText = item.chunk.text.toLowerCase();
+    const verbatim = [...qTokens].some((q) => q.length >= 3 && lowerText.includes(q)) ? 1 : 0;
+    const boost = 1 + 0.5 * coverage + 0.25 * verbatim;
+    return { ...item, score: item.score * boost };
+  });
+  return boosted.sort((a, b) => b.score - a.score);
+}
+
+// src/retrieval/dedup.ts
+function jaccard(a, b) {
+  if (a.size === 0 && b.size === 0) {
+    return 1;
+  }
+  let inter = 0;
+  for (const t of a) {
+    if (b.has(t)) {
+      inter++;
+    }
+  }
+  const union = a.size + b.size - inter;
+  return union === 0 ? 0 : inter / union;
+}
+function dedupRanked(ranked, threshold = 0.85) {
+  const kept = [];
+  const keptTokens = [];
+  for (const item of ranked) {
+    const tokens = new Set(tokenize(item.chunk.text));
+    const isDup = keptTokens.some((k) => jaccard(tokens, k) >= threshold);
+    if (!isDup) {
+      kept.push(item);
+      keptTokens.push(tokens);
+    }
+  }
+  return kept;
+}
+
+// src/answer/verify.ts
+var FILE_WEIGHT = 0.7;
+var SNIPPET_WEIGHT = 0.3;
+async function verifySources(ranked, storage) {
+  if (ranked.length === 0) {
+    return { rate: 1, perChunk: [] };
+  }
+  const perChunk = [];
+  for (const { chunk } of ranked) {
+    const exists = await storage.exists(chunk.path);
+    let score = exists ? FILE_WEIGHT : 0;
+    if (exists) {
+      const buf = await storage.read(chunk.path);
+      const content = buf?.toString("utf8") ?? "";
+      const probe = chunk.text.split("\n").find((l) => l.trim().length > 8)?.trim();
+      if (probe && content.includes(probe)) {
+        score += SNIPPET_WEIGHT;
       }
-      const lines = buf.toString("utf8").split("\n").filter(Boolean);
-      for (const line of lines) {
-        if (limit && results.length >= limit) {
-          break;
-        }
-        try {
-          const parsed = JSON.parse(line);
-          const rec = parsed.record;
-          if (!filter || filter(rec)) {
-            results.push(rec);
-          }
-        } catch {
-          continue;
-        }
+    }
+    perChunk.push(score);
+  }
+  const rate = perChunk.reduce((a, b) => a + b, 0) / perChunk.length;
+  return { rate, perChunk };
+}
+function computeConfidence(retrievalConfidence, verificationRate, floor) {
+  const confidence = Math.max(0, Math.min(1, retrievalConfidence * verificationRate));
+  const warnings = [];
+  if (confidence < floor) {
+    warnings.push({
+      code: "LOW_CONFIDENCE",
+      message: `Confidence ${confidence.toFixed(2)} is below the floor ${floor.toFixed(2)}; the answer may be unreliable.`
+    });
+  }
+  return { confidence, warnings };
+}
+
+// src/answer/field-check.ts
+function isCodeSymbol(t) {
+  if (t.length < 3 || t.length > 80) {
+    return false;
+  }
+  if (/\.(ts|tsx|js|jsx|json|md|go|py|rs)$/.test(t)) {
+    return true;
+  }
+  if (t.includes(".") && /[a-zA-Z]/.test(t)) {
+    return true;
+  }
+  if (/_/.test(t) && /[a-zA-Z]/.test(t)) {
+    return true;
+  }
+  if (/[a-z][A-Z]/.test(t)) {
+    return true;
+  }
+  return false;
+}
+function extractSymbols(answer) {
+  const out = /* @__PURE__ */ new Set();
+  for (const m of answer.matchAll(/`([^`\n]{2,80})`/g)) {
+    for (const tok of m[1].trim().split(/[\s(),;:[\]{}'"]+/)) {
+      if (isCodeSymbol(tok)) {
+        out.add(tok);
       }
     }
-    return limit ? results.slice(0, limit) : results;
-  }
-  /**
-   * Get the current writable file path
-   *
-   * Creates a new segment if:
-   * - No files exist
-   * - Latest file has >= maxRecordsPerFile records
-   *
-   * @returns Path to writable file
-   */
-  async getWritableFile() {
-    const files = await this.getFilesSorted();
-    if (files.length === 0) {
-      return this.segmentPath(Date.now());
-    }
-    const latest = files[files.length - 1];
-    const buf = await this.storage.read(latest);
-    if (!buf) {
-      return latest;
-    }
-    const count = buf.toString("utf8").split("\n").filter(Boolean).length;
-    if (count >= this.maxRecordsPerFile) {
-      return this.segmentPath(Date.now());
-    }
-    return latest;
-  }
-  /**
-   * Get all store files sorted by timestamp (oldest to newest)
-   *
-   * @returns Sorted array of file paths
-   */
-  async getFilesSorted() {
-    const files = await this.storage.list(this.basePath);
-    return files.filter((f) => f.startsWith(this.basePath + this.filePrefix) && f.endsWith(".jsonl")).sort();
-  }
-  /**
-   * Generate a segment file path from timestamp
-   *
-   * Format: {filePrefix}YYYYMMDD-{timestamp}.jsonl
-   * Example: history-20251209-1733769000123.jsonl
-   *
-   * @param ts - Unix timestamp in milliseconds
-   * @returns Full file path
-   */
-  segmentPath(ts) {
-    const date = new Date(ts);
-    const day = String(date.getDate()).padStart(2, "0");
-    const month = String(date.getMonth() + 1).padStart(2, "0");
-    const year = date.getFullYear();
-    const filename = `${this.filePrefix}${year}${month}${day}-${ts}.jsonl`;
-    return path.posix.join(this.basePath, filename);
-  }
-  /**
-   * Enforce file rotation by deleting oldest files if maxFiles exceeded
-   */
-  async enforceRotation() {
-    const files = await this.getFilesSorted();
-    if (files.length <= this.maxFiles) {
-      return;
-    }
-    const excess = files.length - this.maxFiles;
-    const toDelete = files.slice(0, excess);
-    await Promise.all(toDelete.map((f) => this.storage.delete(f)));
-  }
-  /**
-   * Ensure path ends with trailing slash
-   */
-  ensureTrailingSlash(p) {
-    return p.endsWith("/") ? p : `${p}/`;
   }
-};
-function sortKeysRecursively(obj) {
-  if (obj === null || typeof obj !== "object") {
-    return obj;
+  for (const m of answer.matchAll(/[A-Za-z_$][A-Za-z0-9_$-]*(?:[./][A-Za-z0-9_$.-]+)*/g)) {
+    if (isCodeSymbol(m[0])) {
+      out.add(m[0]);
+    }
+  }
+  return [...out];
+}
+function checkFields(answer, ranked) {
+  const symbols = extractSymbols(answer);
+  if (symbols.length === 0) {
+    return { rate: 1, ungrounded: [], checked: 0 };
   }
-  if (Array.isArray(obj)) {
-    return obj.map(sortKeysRecursively);
+  const corpus = ranked.map((r) => `${r.chunk.path}
+${r.chunk.text}`).join("\n").toLowerCase();
+  const grounded = (sym) => {
+    const s = sym.toLowerCase();
+    if (corpus.includes(s)) {
+      return true;
+    }
+    const head = s.split(".")[0];
+    return head.length >= 3 && corpus.includes(head);
+  };
+  const ungrounded = symbols.filter((s) => !grounded(s));
+  return { rate: (symbols.length - ungrounded.length) / symbols.length, ungrounded, checked: symbols.length };
+}
+function applyFieldCheck(answer, ranked, confidence, warnings, floor) {
+  const fc = checkFields(answer, ranked);
+  if (fc.checked === 0 || fc.rate === 1) {
+    return { confidence, warnings };
+  }
+  const adjusted = Math.max(0, confidence * (0.5 + 0.5 * fc.rate));
+  const next = [...warnings];
+  if (fc.ungrounded.length > 0) {
+    next.push({
+      code: "UNGROUNDED_TERMS",
+      message: `Answer mentions ${fc.ungrounded.length} term(s) not found in sources: ${fc.ungrounded.slice(0, 5).join(", ")}`,
+      details: { ungrounded: fc.ungrounded, rate: Math.round(fc.rate * 1e3) / 1e3 }
+    });
   }
-  const sorted = {};
-  const record = obj;
-  const keys = Object.keys(record).sort();
-  for (const key of keys) {
-    sorted[key] = sortKeysRecursively(record[key]);
+  if (adjusted < floor && !next.some((w) => w.code === "LOW_CONFIDENCE")) {
+    next.push({
+      code: "LOW_CONFIDENCE",
+      message: `Confidence ${adjusted.toFixed(2)} is below the floor ${floor.toFixed(2)}; the answer may be unreliable.`
+    });
   }
-  return sorted;
+  return { confidence: adjusted, warnings: next };
 }
-async function readJson(filePath) {
+
+// src/answer/decompose.ts
+async function decompose(query, llm, maxSubqueries) {
+  if (maxSubqueries <= 0) {
+    return [query];
+  }
+  const prompt = `Break the following question into at most ${maxSubqueries} focused, self-contained sub-questions that together cover it. Return one sub-question per line, no numbering.
+
+Question: ${query}`;
   try {
-    const content = await promises.readFile(filePath, "utf8");
-    return JSON.parse(content);
-  } catch (error) {
-    if (error.code === "ENOENT") {
-      return null;
-    }
-    throw error;
-  }
-}
-async function writeJson(filePath, data) {
-  const tmp = `${filePath}.tmp`;
-  const sorted = sortKeysRecursively(data);
-  const content = JSON.stringify(sorted, null, 2) + "\n";
-  await promises.mkdir(dirname(filePath), { recursive: true });
-  await promises.writeFile(tmp, content, "utf8");
-  if (process.platform === "win32") {
-    try {
-      await promises.unlink(filePath);
-    } catch (err) {
-      if (err.code !== "ENOENT") {
-        throw err;
-      }
+    const { content } = await llm.complete(prompt, { temperature: 0.2, maxTokens: 256 });
+    const subs = (content ?? "").split("\n").map((l) => l.replace(/^[-*\d.)\s]+/, "").trim()).filter((l) => l.length > 0).slice(0, maxSubqueries);
+    return subs.length > 0 ? [query, ...subs] : [query];
+  } catch {
+    return [query];
+  }
+}
+
+// src/answer/synthesize.ts
+var MAX_SNIPPET_CHARS = 600;
+function snippetFrom(text, mode) {
+  if (mode === "none") {
+    return void 0;
+  }
+  if (mode === "full") {
+    return text.length > MAX_SNIPPET_CHARS ? `${text.slice(0, MAX_SNIPPET_CHARS)}\u2026` : text;
+  }
+  const line = text.split("\n").find((l) => l.trim().length > 8)?.trim() ?? text.trim().slice(0, 120);
+  return line.length > 200 ? `${line.slice(0, 200)}\u2026` : line;
+}
+function toSearchResults(ranked, opts) {
+  return ranked.map(({ chunk, matchedBy }) => ({
+    file: chunk.path,
+    lines: [chunk.startLine, chunk.endLine],
+    kind: chunk.kind,
+    matchedBy,
+    stale: opts.staleByFile.get(chunk.path) ?? false,
+    snippet: snippetFrom(chunk.text, opts.snippet)
+  }));
+}
+
+// src/answer/answer.ts
+var MAX_SNIPPET_CHARS2 = 600;
+function truncate(text) {
+  return text.length > MAX_SNIPPET_CHARS2 ? `${text.slice(0, MAX_SNIPPET_CHARS2)}\u2026` : text;
+}
+function extractiveAnswer(query, ranked) {
+  if (ranked.length === 0) {
+    return `No indexed content matched the query: "${query}".`;
+  }
+  const top = ranked[0].chunk;
+  return `Most relevant source: ${top.path} (lines ${top.startLine}-${top.endLine}).
+
+${truncate(top.text)}`;
+}
+async function synthesizeAnswer(query, ranked, llm, useLLM) {
+  if (!useLLM || ranked.length === 0) {
+    return extractiveAnswer(query, ranked);
+  }
+  const context = ranked.map((r, i) => `[${i + 1}] ${r.chunk.path}:${r.chunk.startLine}-${r.chunk.endLine}
+${r.chunk.text}`).join("\n\n");
+  const prompt = `Answer the question using ONLY the provided context. Be concise and cite the relevant files by path. If the context does not contain the answer, say so.
+
+Question: ${query}
+
+Context:
+${context}`;
+  try {
+    const { content } = await llm.complete(prompt, { temperature: 0.2, maxTokens: 800 });
+    const trimmed = (content ?? "").trim();
+    return trimmed.length > 0 ? trimmed : extractiveAnswer(query, ranked);
+  } catch {
+    return extractiveAnswer(query, ranked);
+  }
+}
+function toSources(ranked, opts) {
+  return ranked.map(({ chunk, matchedBy }) => ({
+    file: chunk.path,
+    lines: [chunk.startLine, chunk.endLine],
+    kind: chunk.kind,
+    matchedBy,
+    stale: opts.staleByFile.get(chunk.path) ?? false,
+    snippet: snippetFrom(chunk.text, opts.snippet)
+  }));
+}
+function buildAgentResponse(input) {
+  const sources = toSources(input.ranked, { snippet: input.snippet, staleByFile: input.staleByFile });
+  const abstained = input.confidence < input.floor || sources.length === 0;
+  const response = {
+    answer: input.answer,
+    confidence: input.confidence,
+    abstained,
+    sources,
+    warnings: input.warnings && input.warnings.length > 0 ? input.warnings : void 0,
+    meta: {
+      requestId: input.requestId,
+      mode: input.mode,
+      timingMs: input.timingMs,
+      indexId: input.indexId
+    }
+  };
+  return AgentResponseSchema.parse(response);
+}
+
+// src/answer/explore.ts
+function toExploreEntries(ranked, staleByFile) {
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const r of ranked) {
+    if (seen.has(r.chunk.path)) {
+      continue;
     }
+    seen.add(r.chunk.path);
+    const line = snippetFrom(r.chunk.text, "line");
+    out.push({
+      file: r.chunk.path,
+      lines: [r.chunk.startLine, r.chunk.endLine],
+      why: line && line.length > 0 ? line : `${r.chunk.kind} file`,
+      matchedBy: r.matchedBy,
+      stale: staleByFile.get(r.chunk.path) ?? false
+    });
   }
-  await promises.rename(tmp, filePath);
+  return out;
 }
-function computeJsonHash(data) {
-  const content = JSON.stringify(sortKeysRecursively(data));
-  return sha256(content);
+function spreadOf(files) {
+  return new Set(
+    files.map((f) => {
+      const i = f.lastIndexOf("/");
+      return i < 0 ? "." : f.slice(0, i);
+    })
+  ).size;
 }
-async function verifyIndexes(cwd) {
-  const inconsistencies = [];
+async function orientationSummary(task, entries, llm, useLLM) {
+  if (!useLLM || entries.length === 0) {
+    return "";
+  }
+  const list = entries.map((e, i) => `[${i + 1}] ${e.file}:${e.lines[0]}-${e.lines[1]} \u2014 ${e.why}`).join("\n");
+  const prompt = `A developer must approach the task below in an unfamiliar codebase. Using ONLY the relevant files listed, briefly explain WHERE to start, the KEY files and their role, and HOW involved the task looks. Be concise; cite files by path.
+
+Task: ${task}
+
+Relevant files:
+${list}`;
   try {
-    const index = await readJson(`${cwd}/.kb/mind/index.json`);
-    if (!index) {
+    const { content } = await llm.complete(prompt, { temperature: 0.2, maxTokens: 400 });
+    return (content ?? "").trim();
+  } catch {
+    return "";
+  }
+}
+function historyKey(indexId) {
+  return `${MIND_NAMESPACE_PREFIX}history:${indexId}`;
+}
+async function recordQuery(cache, indexId, query, at) {
+  try {
+    await cache.zadd(historyKey(indexId), at, query);
+  } catch {
+  }
+}
+async function recentQueries(cache, indexId, sinceMs = 0) {
+  try {
+    return await cache.zrangebyscore(historyKey(indexId), sinceMs, Number.MAX_SAFE_INTEGER);
+  } catch {
+    return [];
+  }
+}
+
+// src/mind.ts
+function createMind(services, config, options = {}) {
+  const now = options.now ?? (() => Date.now());
+  const isoNow = options.isoNow ?? (() => new Date(now()).toISOString());
+  const cwd = options.cwd ?? process.cwd();
+  function resolveIndexId(indexId) {
+    return indexId && indexId.trim() !== "" ? indexId : config.defaultIndex;
+  }
+  function syncOpts(indexId) {
+    const eff = effectiveIndexConfig(config, indexId);
+    return {
+      indexId,
+      cwd,
+      chunk: { maxTokens: eff.chunk.maxTokens, overlapTokens: eff.chunk.overlapTokens },
+      ast: eff.chunk.ast,
+      now: isoNow()
+    };
+  }
+  return {
+    async index(req, onProgress) {
+      const indexId = resolveIndexId(req.indexId);
+      const eff = effectiveIndexConfig(config, indexId);
+      const start = now();
+      const result = await ingest(
+        {
+          indexId,
+          cwd,
+          // CLI `--scope` overrides the include set (keeping configured excludes);
+          // otherwise use the index's configured include/exclude scope.
+          scope: req.scope ? { include: [req.scope], exclude: eff.scope.exclude } : eff.scope,
+          full: req.full,
+          chunk: { maxTokens: eff.chunk.maxTokens, overlapTokens: eff.chunk.overlapTokens },
+          ast: eff.chunk.ast,
+          now: isoNow(),
+          onProgress
+        },
+        services
+      );
+      const durationMs = now() - start;
+      services.logger?.info("mind: index", {
+        indexId,
+        filesIndexed: result.filesIndexed,
+        chunks: result.chunks,
+        added: result.added,
+        updated: result.updated,
+        removed: result.removed,
+        unchanged: result.unchanged,
+        durationMs
+      });
+      return { indexId, filesIndexed: result.filesIndexed, chunks: result.chunks, durationMs };
+    },
+    async search(req) {
+      const indexId = resolveIndexId(req.indexId);
+      const retrieval = effectiveIndexConfig(config, indexId).retrieval;
+      const limit = req.limit ?? retrieval.limit;
+      const snippet = req.snippet ?? "line";
+      const t0 = now();
+      const retrieved = await retrieve(
+        { text: req.text, indexId, limit: limit * 3, intent: req.intent, rrfK: retrieval.rrfK, hyde: retrieval.hyde, expand: retrieval.expand },
+        services
+      );
+      let ranked = retrieval.rerank ? rerank(retrieved.ranked, req.text) : retrieved.ranked;
+      if (retrieval.dedup) {
+        ranked = dedupRanked(ranked);
+      }
+      ranked = ranked.slice(0, limit);
+      const manifest = await loadManifest(services.storage, indexId);
+      const stales = await staleMap(manifest, ranked.map((r) => r.chunk.path), cwd);
+      const results = toSearchResults(ranked, { snippet, staleByFile: stales });
+      const staleCount2 = [...stales.values()].filter(Boolean).length;
+      const timingMs = now() - t0;
+      services.logger?.info("mind: search", {
+        indexId,
+        results: results.length,
+        semanticWinRate: retrieved.semanticWinRate,
+        staleCount: staleCount2,
+        timingMs
+      });
       return {
-        ok: false,
-        code: "MIND_NO_INDEX",
-        inconsistencies: ["Main index file not found"],
-        hint: 'Run "kb mind rag-index" to initialize indexes'
+        results,
+        confidence: retrieved.confidence,
+        indexId,
+        meta: { requestId: `mind:${t0}`, timingMs, semanticWinRate: retrieved.semanticWinRate, staleCount: staleCount2 }
       };
-    }
-    const [apiIndex, depsGraph, recentDiff, meta, docs] = await Promise.all([
-      readJson(`${cwd}/.kb/mind/api-index.json`),
-      readJson(`${cwd}/.kb/mind/deps.json`),
-      readJson(`${cwd}/.kb/mind/recent-diff.json`),
-      readJson(`${cwd}/.kb/mind/meta.json`),
-      readJson(`${cwd}/.kb/mind/docs.json`)
-    ]);
-    if (apiIndex) {
-      const computedHash = computeJsonHash(apiIndex);
-      if (computedHash !== index.apiIndexHash) {
-        inconsistencies.push(
-          `API index hash mismatch: expected ${index.apiIndexHash}, got ${computedHash}`
-        );
-      }
-    } else if (index.apiIndexHash) {
-      inconsistencies.push("API index file missing but hash is present");
-    }
-    if (depsGraph) {
-      const computedHash = computeJsonHash(depsGraph);
-      if (computedHash !== index.depsHash) {
-        inconsistencies.push(
-          `Dependencies hash mismatch: expected ${index.depsHash}, got ${computedHash}`
+    },
+    async ask(req) {
+      const indexId = resolveIndexId(req.indexId);
+      const retrieval = effectiveIndexConfig(config, indexId).retrieval;
+      const mode = req.mode ?? "auto";
+      const budget = config.modes[mode];
+      const t0 = now();
+      await recordQuery(services.cache, indexId, req.text, t0);
+      const queries = budget.useLLM ? await decompose(req.text, services.llm, budget.maxSubqueries) : [req.text];
+      const merged = /* @__PURE__ */ new Map();
+      let retrievalConfidence = 0;
+      for (const q of queries) {
+        const r = await retrieve(
+          { text: q, indexId, limit: budget.maxChunks, intent: void 0, rrfK: retrieval.rrfK, hyde: retrieval.hyde, expand: retrieval.expand },
+          services
         );
+        retrievalConfidence = Math.max(retrievalConfidence, r.confidence);
+        for (const rc of r.ranked) {
+          const prev = merged.get(rc.chunk.id);
+          if (!prev || rc.score > prev.score) {
+            merged.set(rc.chunk.id, rc);
+          }
+        }
       }
-    } else if (index.depsHash) {
-      inconsistencies.push("Dependencies file missing but hash is present");
-    }
-    if (recentDiff) {
-      const computedHash = computeJsonHash(recentDiff);
-      if (computedHash !== index.recentDiffHash) {
-        inconsistencies.push(
-          `Recent diff hash mismatch: expected ${index.recentDiffHash}, got ${computedHash}`
-        );
+      let ranked = retrieval.rerank ? rerank([...merged.values()], req.text) : [...merged.values()].sort((a, b) => b.score - a.score);
+      if (retrieval.dedup) {
+        ranked = dedupRanked(ranked);
       }
-    } else if (index.recentDiffHash) {
-      inconsistencies.push("Recent diff file missing but hash is present");
-    }
-    const combinedContent = JSON.stringify({
-      apiIndex: apiIndex || {},
-      deps: depsGraph || {},
-      recentDiff: recentDiff || {},
-      meta: meta || {},
-      docs: docs || {}
-    });
-    const computedChecksum = sha256(combinedContent);
-    if (computedChecksum !== index.indexChecksum) {
-      inconsistencies.push(
-        `Index checksum mismatch: expected ${index.indexChecksum}, got ${computedChecksum}`
+      ranked = ranked.slice(0, budget.maxChunks);
+      const verification = await verifySources(ranked, services.storage);
+      const base = computeConfidence(retrievalConfidence, verification.rate, config.confidence.floor);
+      const answer = await synthesizeAnswer(req.text, ranked, services.llm, budget.useLLM);
+      const { confidence, warnings } = budget.useLLM ? applyFieldCheck(answer, ranked, base.confidence, base.warnings, config.confidence.floor) : base;
+      const manifest = await loadManifest(services.storage, indexId);
+      const staleByFile = await staleMap(manifest, ranked.map((r) => r.chunk.path), cwd);
+      const timingMs = now() - t0;
+      services.logger?.info("mind: ask", {
+        indexId,
+        mode,
+        subqueries: queries.length,
+        chunks: ranked.length,
+        confidence: Math.round(confidence * 1e3) / 1e3,
+        timingMs
+      });
+      return buildAgentResponse({
+        answer,
+        ranked,
+        confidence,
+        mode,
+        requestId: `mind:${t0}`,
+        timingMs,
+        indexId,
+        floor: config.confidence.floor,
+        snippet: req.snippet ?? "line",
+        staleByFile,
+        warnings
+      });
+    },
+    async explore(req) {
+      const indexId = resolveIndexId(req.indexId);
+      const retrieval = effectiveIndexConfig(config, indexId).retrieval;
+      const budget = config.modes.auto;
+      const limit = req.limit ?? retrieval.limit;
+      const t0 = now();
+      const retrieved = await retrieve(
+        { text: req.task, indexId, limit: limit * 3, intent: "architecture", rrfK: retrieval.rrfK, hyde: retrieval.hyde, expand: retrieval.expand },
+        services
       );
-    }
-    const expectedFiles = ["api-index.json", "deps.json", "recent-diff.json"];
-    for (const file of expectedFiles) {
-      try {
-        await promises.access(`${cwd}/.kb/mind/${file}`);
-      } catch {
-        inconsistencies.push(`Required index file missing: ${file}`);
+      let ranked = retrieval.rerank ? rerank(retrieved.ranked, req.task) : retrieved.ranked;
+      if (retrieval.dedup) {
+        ranked = dedupRanked(ranked);
+      }
+      ranked = ranked.slice(0, limit);
+      const manifest = await loadManifest(services.storage, indexId);
+      const stales = await staleMap(manifest, ranked.map((r) => r.chunk.path), cwd);
+      const files = toExploreEntries(ranked, stales);
+      const spread = spreadOf(files.map((f) => f.file));
+      const summary = await orientationSummary(req.task, files, services.llm, budget.useLLM);
+      const timingMs = now() - t0;
+      services.logger?.info("mind: explore", {
+        indexId,
+        filesTouched: files.length,
+        spread,
+        timingMs
+      });
+      return {
+        task: req.task,
+        indexId,
+        confidence: retrieved.confidence,
+        summary,
+        files,
+        meta: { requestId: `mind:${t0}`, timingMs, filesTouched: files.length, spread }
+      };
+    },
+    async reindex(req) {
+      return this.index({ indexId: req.indexId, full: true });
+    },
+    async drop(req) {
+      const indexId = resolveIndexId(req.indexId);
+      if (!await manifestExists(services.storage, indexId)) {
+        throw new Error(`No such index "${indexId}" \u2014 nothing to drop (run \`kb mind status\` to list indexes).`);
+      }
+      const manifest = await loadManifest(services.storage, indexId);
+      const ids = manifest.chunks.map((c) => c.id);
+      const droppedFiles = Object.keys(manifest.files).length;
+      const BATCH = 500;
+      for (let i = 0; i < ids.length; i += BATCH) {
+        await services.vectorStore.delete(ids.slice(i, i + BATCH), indexId);
+      }
+      await deleteManifest(services.storage, indexId);
+      services.logger?.info("mind: drop", { indexId, droppedChunks: ids.length, droppedFiles });
+      return { indexId, droppedChunks: ids.length, droppedFiles };
+    },
+    async syncAdd(paths, indexId) {
+      const id = resolveIndexId(indexId);
+      const counts = await syncAdd(paths, services, syncOpts(id));
+      return { indexId: id, ...counts };
+    },
+    async syncUpdate(paths, indexId) {
+      const id = resolveIndexId(indexId);
+      const counts = await syncUpdate(paths, services, syncOpts(id));
+      return { indexId: id, ...counts };
+    },
+    async syncDelete(paths, indexId) {
+      const id = resolveIndexId(indexId);
+      const counts = await syncDelete(paths, services, syncOpts(id));
+      return { indexId: id, ...counts };
+    },
+    async syncList(indexId) {
+      const id = resolveIndexId(indexId);
+      const manifest = await loadManifest(services.storage, id);
+      return {
+        indexId: id,
+        documents: Object.entries(manifest.files).map(([path2, info]) => ({
+          path: path2,
+          chunks: info.chunks,
+          indexedAt: info.indexedAt
+        }))
+      };
+    },
+    async syncStatus(indexId) {
+      const id = resolveIndexId(indexId);
+      const manifest = await loadManifest(services.storage, id);
+      return {
+        indexId: id,
+        documents: Object.keys(manifest.files).length,
+        chunks: manifest.chunks.length,
+        lastIndexedAt: manifest.updatedAt,
+        stale: false
+      };
+    },
+    async status(indexId) {
+      const ids = indexId ? [indexId] : [.../* @__PURE__ */ new Set([...Object.keys(config.indexes), ...await listIndexIds(services)])];
+      const indexes = [];
+      for (const id of ids) {
+        const manifest = await loadManifest(services.storage, id);
+        const declared = config.indexes[id];
+        const sc = resolveScope(declared?.scope);
+        const coverage = sc.include.join(", ") + (sc.exclude.length ? ` \xB7 excl ${sc.exclude.join(", ")}` : "");
+        indexes.push({
+          indexId: id,
+          label: declared?.label,
+          coverage,
+          documents: Object.keys(manifest.files).length,
+          chunks: manifest.chunks.length,
+          lastIndexedAt: manifest.updatedAt,
+          staleCount: await staleCount(manifest, cwd)
+        });
       }
+      return { indexes, healthy: true };
+    },
+    async health() {
+      return {
+        ok: true,
+        vectorStore: Boolean(services.vectorStore),
+        embeddings: Boolean(services.embeddings),
+        llm: Boolean(services.llm)
+      };
+    }
+  };
+}
+async function listIndexIds(services) {
+  const paths = await services.storage.list("mind/");
+  const ids = /* @__PURE__ */ new Set();
+  for (const p of paths) {
+    const match = /^mind\/([^/]+)\/manifest\.json$/.exec(p);
+    if (match) {
+      ids.add(match[1]);
     }
-    const ok = inconsistencies.length === 0;
-    const code = ok ? null : "MIND_INDEX_INCONSISTENT";
-    const hint = ok ? "All indexes are consistent and up to date" : 'Run "kb mind rag-index" to rebuild indexes';
-    return { ok, code, inconsistencies, hint };
-  } catch (error) {
-    return {
-      ok: false,
-      code: "MIND_VERIFY_ERROR",
-      inconsistencies: [`Verification failed: ${error instanceof Error ? error.message : String(error)}`],
-      hint: "Check file permissions and workspace structure"
-    };
   }
+  return [...ids];
 }
 
-// src/defaults.ts
-var DEFAULT_BUDGET = {
-  totalTokens: 9e3,
-  caps: {
-    intent_summary: 300,
-    product_overview: 600,
-    project_meta: 500,
-    api_signatures: 2200,
-    recent_diffs: 1200,
-    docs_overview: 600,
-    impl_snippets: 3e3,
-    configs_profiles: 700
-  },
-  truncation: "middle"
-};
-var DEFAULT_PRESET = {
-  name: "balanced",
-  weight: {
-    overview: 1,
-    api: 1.2,
-    diffs: 1,
-    snippets: 1.4,
-    configs: 0.6,
-    meta: 0.8,
-    docs: 0.9
+// src/pipeline.ts
+var defaultClock = () => Date.now();
+var Tracer = class {
+  constructor(requestId, mode, clock = defaultClock) {
+    this.requestId = requestId;
+    this.mode = mode;
+    this.clock = clock;
+  }
+  requestId;
+  mode;
+  clock;
+  stages = [];
+  async run(stage, input, services, fn) {
+    const start = this.clock();
+    const output = await fn(input, services);
+    this.stages.push({
+      stage,
+      durationMs: this.clock() - start,
+      outputCount: Array.isArray(output) ? output.length : void 0
+    });
+    return output;
+  }
+  /** Record a stage trace manually (for stages not wrapped by `run`). */
+  record(trace) {
+    this.stages.push(trace);
+  }
+  build(totalMs) {
+    return {
+      requestId: this.requestId,
+      mode: this.mode,
+      totalMs,
+      stages: [...this.stages]
+    };
   }
 };
-var DEFAULT_TIME_BUDGET_MS = 800;
-var MAX_FILE_SIZE_BYTES = 1.5 * 1024 * 1024;
-var MAX_SNIPPET_LINES = 60;
-function getGenerator() {
-  return "kb-labs-mind@0.1.0";
-}
 
-export { DEFAULT_BUDGET, DEFAULT_PRESET, DEFAULT_TIME_BUDGET_MS, DefaultTokenEstimator, ERROR_HINTS, FileRotationStore, MAX_FILE_SIZE_BYTES, MAX_SNIPPET_LINES, MindError, computeJsonHash, cosineSimilarity, createMindError, defaultTokenEstimator, dotProduct, estimateTokens, findWorkspaceRoot, fromPosix, getExitCode, getGenerator, isMindError, magnitude, makeRelativeToRoot, normalize, readJson, sha256, sha256Buffer, sha256File, shouldIgnorePath, toPosix, truncateToTokens, verifyIndexes, wrapError, writeJson };
+export { Tracer, bm25Search, buildAgentResponse, checkFields, chunkFile, chunkId, computeConfidence, createMind, decompose, dedupRanked, extractSymbols, ingest, intentWeights, kindFromPath, loadManifest, recentQueries, recordQuery, rerank, retrieve, rrfFuse, saveManifest, slidingWindowChunks, structuralChunks, syncAdd, syncDelete, syncUpdate, synthesizeAnswer, toSearchResults, toSources, tokenize, verifySources };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map