@drewpayment/mink 0.11.0-beta.4 → 0.12.0-beta.1

package/package.json

@@ -1,13 +1,17 @@
 {
   "name": "@drewpayment/mink",
-  "version": "0.11.0-beta.4",
+  "version": "0.12.0-beta.1",
   "description": "A hidden presence that moves alongside the developer — token efficiency and cross-project wiki for AI coding assistants",
   "type": "module",
   "bin": {
-    "mink": "./dist/cli.js"
+    "mink": "./dist/cli.node.js",
+    "mink-bun": "./dist/cli.bun.js"
+  },
+  "engines": {
+    "node": ">=22.5.0"
   },
   "scripts": {
-    "build": "bun build src/cli.ts --outfile dist/cli.js --target node --format esm && node -e \"const f=require('fs');let c=f.readFileSync('dist/cli.js','utf8');c=c.replace(/^#!.*\\n/,'');f.writeFileSync('dist/cli.js','#!/usr/bin/env node\\n'+c);f.chmodSync('dist/cli.js',0o755)\"",
+    "build": "node scripts/build.mjs",
     "postinstall": "bun run build 2>/dev/null || true",
     "typecheck": "bunx tsc --noEmit",
     "test": "bun test",
@@ -17,7 +21,9 @@
   },
   "files": [
     "src/**/*.ts",
-    "dist/cli.js",
+    "dist/cli.node.js",
+    "dist/cli.bun.js",
+    "scripts/build.mjs",
     "skills/**/*",
     "agents/**/*",
     "dashboard/out"
@@ -25,6 +31,10 @@
   "publishConfig": {
     "access": "public"
   },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/drewpayment/mink.git"
+  },
   "license": "MIT",
   "dependencies": {
     "puppeteer-core": "^24.0.0"

package/scripts/build.mjs

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+// Build both runtime bundles. Each invocation feeds `bun build` a
+// `--define MINK_RUNTIME=...` value that the storage driver dispatcher in
+// `src/storage/driver.ts` constant-folds, so the unused branch's
+// `require("bun:sqlite")` / `require("node:sqlite")` is never executed at
+// runtime — even though both strings are present in the bundle source.
+//
+// Outputs:
+//   dist/cli.bun.js   — #!/usr/bin/env bun  (faster startup, recommended)
+//   dist/cli.node.js  — #!/usr/bin/env node (works wherever Node ≥22.5 is)
+//
+// `package.json:bin` maps the user-visible `mink` command to the Node
+// bundle (broadest compat) and `mink-bun` to the Bun bundle.
+
+import { execFileSync } from "node:child_process";
+import { chmodSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+
+const SRC = "src/cli.ts";
+
+const TARGETS = [
+  { runtime: "bun",  outfile: "dist/cli.bun.js",  target: "bun",  shebang: "#!/usr/bin/env bun" },
+  { runtime: "node", outfile: "dist/cli.node.js", target: "node", shebang: "#!/usr/bin/env node" },
+];
+
+function run(cmd, args) {
+  execFileSync(cmd, args, { stdio: "inherit" });
+}
+
+for (const t of TARGETS) {
+  mkdirSync(dirname(t.outfile), { recursive: true });
+  run("bun", [
+    "build", SRC,
+    "--outfile", t.outfile,
+    "--target", t.target,
+    "--format", "esm",
+    "--define", `MINK_RUNTIME="${t.runtime}"`,
+  ]);
+
+  // `bun build` may emit its own shebang depending on the target. Strip any
+  // existing line beginning with `#!` and prepend the canonical one.
+  let body = readFileSync(t.outfile, "utf-8");
+  body = body.replace(/^#!.*\n/, "");
+  writeFileSync(t.outfile, `${t.shebang}\n${body}`);
+  chmodSync(t.outfile, 0o755);
+  console.log(`built ${t.outfile} (${t.runtime})`);
+}

package/src/commands/bug-search.ts

@@ -1,5 +1,4 @@
-import { searchBugs } from "../core/bug-memory";
-import { aggregateBugMemory } from "../core/state-aggregator";
+import { BugMemoryRepo } from "../repositories/bug-memory-repo";
 
 export function bugSearch(cwd: string, query: string): void {
   if (!query) {
@@ -7,8 +6,7 @@ export function bugSearch(cwd: string, query: string): void {
     process.exit(1);
   }
 
-  const memory = aggregateBugMemory(cwd);
-  const results = searchBugs(memory, query);
+  const results = BugMemoryRepo.for(cwd).searchBugs(query);
 
   if (results.length === 0) {
     console.log("No matching bugs found.");

package/src/commands/detect-waste.ts

@@ -1,24 +1,18 @@
 import { statSync } from "fs";
-import {
-  tokenLedgerShardPath,
-  fileIndexPath,
-  learningMemoryPath,
-} from "../core/paths";
-import { loadLedger, saveLedger } from "../core/token-ledger";
-import { isFileIndex, createEmptyIndex } from "../core/index-store";
+import { learningMemoryPath } from "../core/paths";
+import { FileIndexRepo } from "../repositories/file-index-repo";
+import { TokenLedgerRepo } from "../repositories/token-ledger-repo";
 import {
   aggregateTokenLedger,
   aggregateActionLog,
 } from "../core/state-aggregator";
 import { loadCounters } from "../core/state-counters";
-import { safeReadJson } from "../core/fs-utils";
 import { runDetection } from "../core/waste-detection";
 import { getOrCreateDeviceId } from "../core/device";
 import type { TokenLedger } from "../types/token-ledger";
-import type { FileIndex } from "../types/file-index";
+import type { FileIndexEntry } from "../types/file-index";
 
 export function detectWaste(cwd: string): void {
-  const idxPath = fileIndexPath(cwd);
   const lmPath = learningMemoryPath(cwd);
 
   // Aggregated ledger (across all device shards + legacy). Aggregator returns
@@ -27,14 +21,14 @@ export function detectWaste(cwd: string): void {
   // already logged by loadLedger.
   const ledger: TokenLedger = aggregateTokenLedger(cwd);
 
-  // Load file index
-  const rawIndex = safeReadJson(idxPath);
-  let fileIndex: FileIndex;
-  if (rawIndex !== null && isFileIndex(rawIndex)) {
-    fileIndex = rawIndex;
-  } else {
-    fileIndex = createEmptyIndex();
-  }
+  // Load file index — read every entry into the map shape the waste
+  // detector expects. listAll() walks the table once; under 20k rows it
+  // returns in single-digit ms.
+  const repo = FileIndexRepo.for(cwd);
+  const entries: Record<string, FileIndexEntry> = {};
+  for (const e of repo.listAll()) entries[e.filePath] = e;
+  const totalFiles = repo.totalFiles();
+  const lastScanTimestamp = repo.getLastScanTimestamp();
 
   // Aggregated action log content (across all device shards + legacy)
   const actionLogContent = aggregateActionLog(cwd);
@@ -47,32 +41,30 @@ export function detectWaste(cwd: string): void {
     // File missing — will be flagged as stale
   }
 
-  // Pull hit/miss telemetry from the per-device counter file, falling back to
-  // the legacy header counters when unmigrated. We feed runDetection a synthetic
-  // header so it works without knowing about the split.
+  // Pull hit/miss telemetry from the SQLite counters table. We synthesize
+  // the header shape the detector expects (lifetimeHits/Misses lived in
+  // the JSON header pre-migration).
   const counters = loadCounters(cwd);
   const headerForDetection = {
-    ...fileIndex.header,
-    lifetimeHits: counters.fileIndexHits || fileIndex.header.lifetimeHits,
-    lifetimeMisses: counters.fileIndexMisses || fileIndex.header.lifetimeMisses,
+    lastScanTimestamp,
+    totalFiles,
+    lifetimeHits: counters.fileIndexHits,
+    lifetimeMisses: counters.fileIndexMisses,
   };
 
   // Run detection on the aggregated cross-device view
   const flags = runDetection(
     ledger,
-    fileIndex.entries,
+    entries,
     headerForDetection,
     actionLogContent,
     learningMemoryMtimeMs
   );
 
-  // Persist flags in THIS device's shard ledger so it's the only writer for
-  // that file. The aggregator unions wasteFlags across shards on read, so
-  // every device's view stays current without merge conflicts.
-  const shardLedgerPath = tokenLedgerShardPath(cwd, getOrCreateDeviceId());
-  const shardLedger = loadLedger(shardLedgerPath);
-  shardLedger.wasteFlags = flags;
-  saveLedger(shardLedgerPath, shardLedger);
+  // Persist flags in THIS device's waste_flags rows. The merge driver
+  // unions across devices on sync; replaceWasteFlagsForDevice clears
+  // and rewrites this device's set on every detection run.
+  TokenLedgerRepo.for(cwd).replaceWasteFlagsForDevice(getOrCreateDeviceId(), flags);
 
   // Output summary
   if (flags.length === 0) {

package/src/commands/post-read.ts

@@ -1,14 +1,14 @@
 import { relative } from "path";
 import { readStdinJson } from "../core/stdin";
-import { sessionPath, fileIndexPath, actionLogShardPath } from "../core/paths";
+import { sessionPath, actionLogShardPath } from "../core/paths";
 import { safeReadJson, atomicWriteJson } from "../core/fs-utils";
 import { createSessionState, isSessionState, recordRead } from "../core/session";
-import { isFileIndex, lookupEntry } from "../core/index-store";
+import { FileIndexRepo } from "../repositories/file-index-repo";
 import { estimateTokens, isBinaryFile } from "../core/token-estimate";
 import { createActionLogWriter } from "../core/action-log";
 import { getOrCreateDeviceId } from "../core/device";
 import type { SessionState } from "../types/session";
-import type { FileIndex } from "../types/file-index";
+import type { IndexLookup } from "../types/file-index";
 import type { PostToolUseInput } from "../types/hook-input";
 
 export interface PostReadResult {
@@ -20,17 +20,17 @@ export interface PostReadResult {
 export function analyzePostRead(
   filePath: string,
   content: string | null,
-  index: FileIndex | null
+  index: IndexLookup | null
 ): PostReadResult {
   // Binary file — skip token estimation
   if (isBinaryFile(filePath, content ?? undefined)) {
-    const entry = index ? lookupEntry(index, filePath) : null;
+    const entry = index ? index.lookupEntry(filePath) : null;
     return { estimatedTokens: 0, indexHit: !!entry, source: "none" };
   }
 
   // Content available — estimate from actual content
   if (content !== null && content.length > 0) {
-    const entry = index ? lookupEntry(index, filePath) : null;
+    const entry = index ? index.lookupEntry(filePath) : null;
     return {
       estimatedTokens: estimateTokens(content, filePath),
       indexHit: !!entry,
@@ -40,7 +40,7 @@ export function analyzePostRead(
 
   // No content — try file index fallback
   if (index) {
-    const entry = lookupEntry(index, filePath);
+    const entry = index.lookupEntry(filePath);
     if (entry) {
       return {
         estimatedTokens: entry.estimatedTokens,
@@ -89,14 +89,13 @@ export async function postRead(cwd: string): Promise<void> {
       ? rawState
       : createSessionState();
 
-    // Load file index for token fallback and indexHit determination
-    const rawIndex = safeReadJson(fileIndexPath(cwd));
-    const index: FileIndex | null = isFileIndex(rawIndex) ? rawIndex : null;
+    // File index repository — one-key lookup, no whole-index load.
+    const repo = FileIndexRepo.for(cwd);
 
     // Extract content from tool output
     const content = extractContent(input);
 
-    const result = analyzePostRead(filePath, content, index);
+    const result = analyzePostRead(filePath, content, repo);
 
     // Record the read in session state
     recordRead(state, filePath, result.estimatedTokens, result.indexHit);

package/src/commands/post-write.ts

@@ -1,22 +1,17 @@
 import { relative } from "path";
 import { readFileSync } from "fs";
 import { readStdinJson } from "../core/stdin";
-import { sessionPath, fileIndexPath, actionLogShardPath } from "../core/paths";
+import { sessionPath, actionLogShardPath } from "../core/paths";
 import { getOrCreateDeviceId } from "../core/device";
 import { safeReadJson, atomicWriteJson } from "../core/fs-utils";
 import { createSessionState, isSessionState, recordWrite } from "../core/session";
-import {
-  isFileIndex,
-  lookupEntry,
-  upsertEntry,
-  createEmptyIndex,
-} from "../core/index-store";
+import { FileIndexRepo } from "../repositories/file-index-repo";
 import { extractDescription } from "../core/description";
 import { estimateTokens, isBinaryFile } from "../core/token-estimate";
 import { isWriteExcluded } from "../core/write-exclusions";
 import { createActionLogWriter } from "../core/action-log";
 import type { SessionState } from "../types/session";
-import type { FileIndex, FileIndexEntry } from "../types/file-index";
+import type { FileIndexEntry, IndexLookup } from "../types/file-index";
 import type { PostToolUseInput } from "../types/hook-input";
 
 export interface PostWriteResult {
@@ -30,7 +25,7 @@ export interface PostWriteResult {
 export function analyzePostWrite(
   filePath: string,
   fileContent: string | null,
-  index: FileIndex | null
+  index: IndexLookup | null
 ): PostWriteResult {
   // Check exclusions
   if (isWriteExcluded(filePath)) {
@@ -43,8 +38,9 @@ export function analyzePostWrite(
     };
   }
 
-  // Determine action from index presence
-  const existingEntry = index ? lookupEntry(index, filePath) : null;
+  // Determine action from index presence (one-key lookup; never loads the
+  // whole index — important for 20k-file projects).
+  const existingEntry = index ? index.lookupEntry(filePath) : null;
   const action: "create" | "edit" = existingEntry ? "edit" : "create";
 
   // Handle binary or unreadable content
@@ -117,17 +113,16 @@ export async function postWrite(cwd: string): Promise<void> {
       ? rawState
       : createSessionState();
 
-    // Load file index
-    const rawIndex = safeReadJson(fileIndexPath(cwd));
-    const index: FileIndex = isFileIndex(rawIndex) ? rawIndex : createEmptyIndex();
+    // File index repository — one-key lookup, no whole-index load.
+    const repo = FileIndexRepo.for(cwd);
 
-    const result = analyzePostWrite(filePath, fileContent, index);
+    const result = analyzePostWrite(filePath, fileContent, repo);
 
     if (result.excluded) return;
 
-    // 1. File index update
+    // 1. File index update — single-row upsert.
     if (result.indexEntry) {
-      upsertEntry(index, result.indexEntry);
+      repo.upsert(result.indexEntry);
     }
 
     // 2. Action log entry — write to this device's shard
@@ -149,9 +144,8 @@ export async function postWrite(cwd: string): Promise<void> {
     // 3. Session state update
     recordWrite(state, filePath, result.action, result.estimatedTokens);
 
-    // Persist state changes
+    // Persist session — file index already committed via repo.upsert.
     atomicWriteJson(sessionPath(cwd), state);
-    atomicWriteJson(fileIndexPath(cwd), index);
   } catch {
     // Never crash — exit silently
   } finally {

package/src/commands/pre-read.ts

@@ -1,15 +1,12 @@
 import { relative } from "path";
 import { readStdinJson } from "../core/stdin";
-import { sessionPath, fileIndexPath } from "../core/paths";
+import { sessionPath } from "../core/paths";
 import { safeReadJson, atomicWriteJson } from "../core/fs-utils";
 import { createSessionState, isSessionState } from "../core/session";
-import { isFileIndex, lookupEntry } from "../core/index-store";
-import {
-  incrementFileIndexHit,
-  incrementFileIndexMiss,
-} from "../core/state-counters";
+import { FileIndexRepo } from "../repositories/file-index-repo";
+import { CountersRepo } from "../repositories/counters-repo";
 import type { SessionState } from "../types/session";
-import type { FileIndex, FileIndexEntry } from "../types/file-index";
+import type { FileIndexEntry, IndexLookup } from "../types/file-index";
 import type { PreToolUseInput } from "../types/hook-input";
 
 export interface PreReadResult {
@@ -22,7 +19,7 @@ export interface PreReadResult {
 export function analyzePreRead(
   filePath: string,
   state: SessionState,
-  index: FileIndex | null
+  index: IndexLookup | null
 ): PreReadResult {
   const warnings: string[] = [];
   let repeatedRead = false;
@@ -39,12 +36,12 @@ export function analyzePreRead(
     state.counters.repeatedReadWarnings++;
   }
 
-  // File index lookup. Hit/miss telemetry is persisted by the caller via
-  // increment{Hit,Miss}, not by mutating the shared index — keeping the
-  // file-index.json content-addressed by filePath so a JSON union merge driver
-  // can resolve cross-device updates without conflict.
+  // File index lookup. Hit/miss telemetry is persisted by the caller into
+  // the counters table, not by mutating the index — keeps the file_index
+  // row's last_modified stable so the sync merge driver doesn't churn it
+  // on every read.
   if (index) {
-    entry = lookupEntry(index, filePath);
+    entry = index.lookupEntry(filePath);
     if (entry) {
       indexHit = true;
       warnings.push(
@@ -84,11 +81,10 @@ export async function preRead(cwd: string): Promise<void> {
       ? rawState
       : createSessionState();
 
-    // Load file index (null if missing/corrupt)
-    const rawIndex = safeReadJson(fileIndexPath(cwd));
-    const index: FileIndex | null = isFileIndex(rawIndex) ? rawIndex : null;
+    // File index repository — one-key lookup per hook.
+    const repo = FileIndexRepo.for(cwd);
 
-    const result = analyzePreRead(filePath, state, index);
+    const result = analyzePreRead(filePath, state, repo);
 
     // Emit warnings to stderr
     for (const warning of result.warnings) {
@@ -97,13 +93,12 @@ export async function preRead(cwd: string): Promise<void> {
 
     // Persist state changes
     atomicWriteJson(sessionPath(cwd), state);
-    if (index) {
-      try {
-        if (result.indexHit) incrementFileIndexHit(cwd);
-        else incrementFileIndexMiss(cwd);
-      } catch {
-        // Counter file is best-effort telemetry — never block the read hook
-      }
+    try {
+      const counters = CountersRepo.for(cwd);
+      if (result.indexHit) counters.incrementHit();
+      else counters.incrementMiss();
+    } catch {
+      // Counter table is best-effort telemetry — never block the read hook
     }
   } catch {
     // Never crash — exit silently

package/src/commands/scan.ts

@@ -1,7 +1,7 @@
 import { readFileSync } from "fs";
+import { createHash } from "crypto";
 import { join, relative } from "path";
-import { fileIndexPath, configPath } from "../core/paths";
-import { atomicWriteJson, safeReadJson } from "../core/fs-utils";
+import { configPath } from "../core/paths";
 import {
   scanProject,
   scanProjectWithStats,
@@ -10,45 +10,39 @@ import {
 } from "../core/scanner";
 import { extractDescription } from "../core/description";
 import { estimateTokens } from "../core/token-estimate";
-import {
-  createEmptyIndex,
-  isFileIndex,
-  upsertEntry,
-  checkStaleness,
-} from "../core/index-store";
-import type { FileIndex, FileIndexEntry } from "../types/file-index";
+import { FileIndexRepo } from "../repositories/file-index-repo";
+import type { FileIndexEntry } from "../types/file-index";
 
 function configRelativePath(cfgPath: string, cwd: string): string {
   const rel = relative(cwd, cfgPath);
   return rel.startsWith("..") ? cfgPath : rel;
 }
 
-function loadExistingIndex(indexPath: string): FileIndex {
-  const raw = safeReadJson(indexPath);
-  if (isFileIndex(raw)) return raw;
-  if (raw !== null) {
-    console.error("[mink] file-index.json is corrupt — starting fresh");
-  }
-  return createEmptyIndex();
+// Truncated SHA-1 — 16 hex chars is plenty to distinguish content
+// versions of the same file. Cheaper than cryptographic strength;
+// we only use it for change detection, never as a security boundary.
+function contentHashOf(content: string): string {
+  return createHash("sha1").update(content).digest("hex").slice(0, 16);
 }
 
 export function scan(cwd: string, options: { check: boolean }): void {
-  const idxPath = fileIndexPath(cwd);
   const cfgPath = configPath(cwd);
   const config = loadConfig(cfgPath);
   const excludes = getExcludes(config);
-  const maxFiles = config.maxFiles ?? 500;
+  // No default cap as of Phase 5 — per-row write cost is flat in SQLite.
+  // Users who still want a cap set `maxFiles` in config.json.
+  const maxFiles = config.maxFiles;
+  const repo = FileIndexRepo.for(cwd);
 
   if (options.check) {
-    const existing = safeReadJson(idxPath);
-    if (!isFileIndex(existing)) {
+    if (repo.totalFiles() === 0) {
       console.error("[mink] no index found — run mink scan first");
       process.exit(1);
     }
 
     const scanned = scanProject(cwd, excludes, maxFiles);
     const scannedPaths = scanned.map((f) => f.relativePath);
-    const report = checkStaleness(existing, scannedPaths);
+    const report = repo.checkStaleness(scannedPaths);
 
     if (!report.isStale) {
       console.log("[mink] index is up to date");
@@ -70,45 +64,103 @@ export function scan(cwd: string, options: { check: boolean }): void {
     process.exit(1);
   }
 
-  // Full scan
+  // Incremental scan — the actual 20k-file win.
+  //   1. Walk the tree (cheap; just stat + readdir).
+  //   2. Repo.staleSet(scanned) returns only paths whose mtime differs
+  //      from what's stored (or never indexed at all). Everything else
+  //      gets skipped — no readFileSync, no description extract, no
+  //      token estimate.
+  //   3. For stale paths, read content + compute a content hash. If the
+  //      stored content_hash matches, the file was just touched
+  //      without an edit — skip the description/tokens re-extract and
+  //      only refresh mtime/last_indexed. Otherwise do the full
+  //      re-extract.
+  //   4. Bulk upsert in a single transaction, then prune orphans.
   const start = Date.now();
-  const index = loadExistingIndex(idxPath);
 
   const stats = scanProjectWithStats(cwd, excludes, maxFiles);
   const scanned = stats.files;
 
-  // Build new entries, preserving lifetime counters
-  const newIndex = createEmptyIndex();
-  newIndex.header.lifetimeHits = index.header.lifetimeHits;
-  newIndex.header.lifetimeMisses = index.header.lifetimeMisses;
+  const stalePaths = new Set(repo.staleSet(scanned));
+  const batch: Array<{
+    entry: FileIndexEntry;
+    opts: { mtimeMs: number; contentHash: string | null; sizeBytes: number };
+  }> = [];
+  let touchOnlyCount = 0;
+  let extractedCount = 0;
 
   for (const file of scanned) {
+    if (!stalePaths.has(file.relativePath)) {
+      // mtime matches what we have — nothing to do for this file.
+      continue;
+    }
+
     const fullPath = join(cwd, file.relativePath);
     let content: string;
     try {
       content = readFileSync(fullPath, "utf-8");
     } catch {
-      continue; // Skip unreadable files
+      continue; // Skip unreadable files (permissions, race condition)
+    }
+
+    const hash = contentHashOf(content);
+    const existing = repo.lookupEntry(file.relativePath);
+    const existingHash = existing ? repo.contentHashFor(file.relativePath) : null;
+
+    if (existing && existingHash === hash) {
+      // Touched but unchanged — bump mtime/last_indexed only, keep the
+      // stored description + token estimate.
+      batch.push({
+        entry: {
+          filePath: file.relativePath,
+          description: existing.description,
+          estimatedTokens: existing.estimatedTokens,
+          lastModified: new Date(file.mtimeMs).toISOString(),
+          lastIndexed: new Date().toISOString(),
+        },
+        opts: {
+          mtimeMs: Math.floor(file.mtimeMs),
+          contentHash: hash,
+          sizeBytes: content.length,
+        },
+      });
+      touchOnlyCount++;
+      continue;
     }
 
-    const entry: FileIndexEntry = {
-      filePath: file.relativePath,
-      description: extractDescription(file.relativePath, content),
-      estimatedTokens: estimateTokens(content, file.relativePath),
-      lastModified: new Date(file.mtimeMs).toISOString(),
-      lastIndexed: new Date().toISOString(),
-    };
-    upsertEntry(newIndex, entry);
+    // Full re-extract.
+    batch.push({
+      entry: {
+        filePath: file.relativePath,
+        description: extractDescription(file.relativePath, content),
+        estimatedTokens: estimateTokens(content, file.relativePath),
+        lastModified: new Date(file.mtimeMs).toISOString(),
+        lastIndexed: new Date().toISOString(),
+      },
+      opts: {
+        mtimeMs: Math.floor(file.mtimeMs),
+        contentHash: hash,
+        sizeBytes: content.length,
+      },
+    });
+    extractedCount++;
   }
 
-  newIndex.header.lastScanTimestamp = new Date().toISOString();
+  // Single transaction — ~50x faster than per-file commits at 20k files.
+  if (batch.length > 0) repo.upsertMany(batch);
+
+  // Prune orphans: every entry whose file is no longer on disk.
+  const removed = repo.retainOnly(scanned.map((f) => f.relativePath));
 
-  atomicWriteJson(idxPath, newIndex);
+  repo.setLastScanTimestamp(new Date().toISOString());
 
   const elapsed = Date.now() - start;
+  const indexed = repo.totalFiles();
+  const skipped = scanned.length - stalePaths.size;
+
   if (stats.truncated > 0) {
     console.log(
-      `[mink] scanned ${stats.totalScanned} files; indexed ${newIndex.header.totalFiles} most recent in ${elapsed}ms`
+      `[mink] scanned ${stats.totalScanned} files; indexed ${indexed} most recent in ${elapsed}ms`
     );
     console.log(
       `  ${stats.truncated} files past maxFiles=${maxFiles} were not indexed`
@@ -116,9 +168,20 @@ export function scan(cwd: string, options: { check: boolean }): void {
     console.log(
       `  raise the cap by setting "maxFiles" in ${configRelativePath(cfgPath, cwd)}`
     );
+    return;
+  }
+
+  if (skipped === scanned.length && extractedCount === 0 && touchOnlyCount === 0 && removed === 0) {
+    console.log(`[mink] indexed ${indexed} files in ${elapsed}ms (no changes)`);
   } else {
+    const parts: string[] = [];
+    if (extractedCount > 0) parts.push(`${extractedCount} re-indexed`);
+    if (touchOnlyCount > 0) parts.push(`${touchOnlyCount} touch-only`);
+    if (removed > 0) parts.push(`${removed} pruned`);
+    if (skipped > 0)  parts.push(`${skipped} unchanged`);
     console.log(
-      `[mink] indexed ${newIndex.header.totalFiles} files in ${elapsed}ms`
+      `[mink] indexed ${indexed} files in ${elapsed}ms (${parts.join(", ")})`
     );
   }
 }
+