@drewpayment/mink 0.11.0 → 0.12.0-beta.1

package/src/core/sync-merge-drivers.ts

@@ -1,7 +1,9 @@
-import { readFileSync, writeFileSync, appendFileSync } from "fs";
+import { readFileSync, writeFileSync, appendFileSync, copyFileSync, unlinkSync } from "fs";
 import { join } from "path";
 import { minkRoot } from "./paths";
 import { parseLearningMemory, serializeLearningMemory } from "./learning-memory";
+import { openDriver } from "../storage/driver";
+import { applySchema } from "../storage/schema";
 import type { LearningMemory, SectionName } from "../types/learning-memory";
 import type { FileIndex, FileIndexEntry } from "../types/file-index";
 import type { DeviceInfo, DeviceRegistry } from "../types/config";
@@ -220,6 +222,161 @@ export function mergeDevicesDriver(args: DriverArgs): void {
   }
 }
 
+// ── mink-db-merge: projects/*/mink.db ──────────────────────────────────────
+// Two-DB reconciliation: open `ours.db` for read/write, ATTACH `theirs.db`
+// as a read-only schema, replay rows via INSERT OR ... ON CONFLICT using
+// the same per-store conflict rules the JSON aggregator uses today.
+// Sessions / counters / ledger_lifetime are append-merge keyed by device.
+// Falls back to "keep ours" on any failure so a merge driver never blocks
+// the rebase.
+
+interface DbHandle {
+  exec(sql: string): void;
+  prepare(sql: string): { run(...args: unknown[]): unknown };
+  close(): void;
+}
+
+function attachAndReplay(ours: DbHandle, theirsPath: string): void {
+  // ATTACH requires the path to be a literal string parameter; bind it
+  // with the prepare binding to avoid SQL injection from a weird filename.
+  ours.prepare("ATTACH DATABASE ? AS theirs").run(theirsPath);
+  try {
+    ours.exec(`
+      -- file_index: keep the side with the newer last_modified.
+      INSERT INTO file_index
+        (file_path, description, estimated_tokens, last_modified, last_indexed,
+         mtime_ms, content_hash, size_bytes, device_id)
+      SELECT file_path, description, estimated_tokens, last_modified, last_indexed,
+             mtime_ms, content_hash, size_bytes, device_id
+      FROM theirs.file_index
+      WHERE TRUE
+      ON CONFLICT(file_path) DO UPDATE SET
+        description       = CASE WHEN excluded.last_modified > file_index.last_modified THEN excluded.description       ELSE file_index.description       END,
+        estimated_tokens  = CASE WHEN excluded.last_modified > file_index.last_modified THEN excluded.estimated_tokens  ELSE file_index.estimated_tokens  END,
+        last_indexed      = CASE WHEN excluded.last_modified > file_index.last_modified THEN excluded.last_indexed      ELSE file_index.last_indexed      END,
+        last_modified     = CASE WHEN excluded.last_modified > file_index.last_modified THEN excluded.last_modified     ELSE file_index.last_modified     END,
+        mtime_ms          = CASE WHEN excluded.last_modified > file_index.last_modified THEN excluded.mtime_ms          ELSE file_index.mtime_ms          END,
+        content_hash      = COALESCE(excluded.content_hash, file_index.content_hash),
+        size_bytes        = COALESCE(excluded.size_bytes,   file_index.size_bytes),
+        device_id         = CASE WHEN excluded.last_modified > file_index.last_modified THEN excluded.device_id         ELSE file_index.device_id         END;
+
+      -- bug_memory: oldest createdAt + latest lastSeenAt + max occurrence_count.
+      INSERT INTO bug_memory
+        (id, created_at, last_seen_at, error_message, file_path, line_number,
+         root_cause, fix_description, occurrence_count, device_id)
+      SELECT id, created_at, last_seen_at, error_message, file_path, line_number,
+             root_cause, fix_description, occurrence_count, device_id
+      FROM theirs.bug_memory
+      WHERE TRUE
+      ON CONFLICT(id) DO UPDATE SET
+        created_at       = CASE WHEN excluded.created_at < bug_memory.created_at THEN excluded.created_at ELSE bug_memory.created_at END,
+        last_seen_at     = CASE WHEN excluded.last_seen_at > bug_memory.last_seen_at THEN excluded.last_seen_at ELSE bug_memory.last_seen_at END,
+        occurrence_count = MAX(bug_memory.occurrence_count, excluded.occurrence_count);
+
+      INSERT OR IGNORE INTO bug_tags    (bug_id, tag)             SELECT bug_id, tag             FROM theirs.bug_tags;
+      INSERT OR IGNORE INTO bug_related (bug_id, related_bug_id)  SELECT bug_id, related_bug_id  FROM theirs.bug_related;
+
+      -- Ledger sessions are insert-only and device-isolated, so first writer
+      -- wins is correct (shards never overlap session_id in production).
+      INSERT OR IGNORE INTO ledger_sessions
+        (session_id, device_id, start_timestamp, end_timestamp, read_count,
+         write_count, estimated_tokens, repeated_reads, file_index_hits,
+         file_index_misses, estimated_savings, archived)
+      SELECT session_id, device_id, start_timestamp, end_timestamp, read_count,
+             write_count, estimated_tokens, repeated_reads, file_index_hits,
+             file_index_misses, estimated_savings, archived
+      FROM theirs.ledger_sessions;
+
+      INSERT INTO ledger_reads  (session_id, file_path, estimated_tokens, read_count)
+        SELECT session_id, file_path, estimated_tokens, read_count
+        FROM theirs.ledger_reads
+        WHERE session_id IN (SELECT session_id FROM theirs.ledger_sessions
+                             WHERE session_id NOT IN (SELECT session_id FROM ledger_reads));
+
+      INSERT INTO ledger_writes (session_id, file_path, estimated_tokens, action)
+        SELECT session_id, file_path, estimated_tokens, action
+        FROM theirs.ledger_writes
+        WHERE session_id IN (SELECT session_id FROM theirs.ledger_sessions
+                             WHERE session_id NOT IN (SELECT session_id FROM ledger_writes));
+
+      -- Per-device lifetime sums and counters: take the MAX so concurrent
+      -- increments on different devices don't double-count when the same
+      -- device's row is shared (it shouldn't be, but MAX is a safe upper
+      -- bound under concurrent shard mutation).
+      INSERT INTO ledger_lifetime
+        (device_id, total_tokens, total_reads, total_writes, total_sessions,
+         total_file_index_hits, total_file_index_misses, total_repeated_reads,
+         total_estimated_savings)
+      SELECT device_id, total_tokens, total_reads, total_writes, total_sessions,
+             total_file_index_hits, total_file_index_misses, total_repeated_reads,
+             total_estimated_savings
+      FROM theirs.ledger_lifetime
+      WHERE TRUE
+      ON CONFLICT(device_id) DO UPDATE SET
+        total_tokens             = MAX(ledger_lifetime.total_tokens,             excluded.total_tokens),
+        total_reads              = MAX(ledger_lifetime.total_reads,              excluded.total_reads),
+        total_writes             = MAX(ledger_lifetime.total_writes,             excluded.total_writes),
+        total_sessions           = MAX(ledger_lifetime.total_sessions,           excluded.total_sessions),
+        total_file_index_hits    = MAX(ledger_lifetime.total_file_index_hits,    excluded.total_file_index_hits),
+        total_file_index_misses  = MAX(ledger_lifetime.total_file_index_misses,  excluded.total_file_index_misses),
+        total_repeated_reads     = MAX(ledger_lifetime.total_repeated_reads,     excluded.total_repeated_reads),
+        total_estimated_savings  = MAX(ledger_lifetime.total_estimated_savings,  excluded.total_estimated_savings);
+
+      INSERT INTO counters (device_id, file_index_hits, file_index_misses)
+      SELECT device_id, file_index_hits, file_index_misses
+      FROM theirs.counters
+      WHERE TRUE
+      ON CONFLICT(device_id) DO UPDATE SET
+        file_index_hits   = MAX(counters.file_index_hits,   excluded.file_index_hits),
+        file_index_misses = MAX(counters.file_index_misses, excluded.file_index_misses);
+
+      INSERT OR IGNORE INTO waste_flags (pattern, detected_at, details, device_id)
+        SELECT pattern, detected_at, details, device_id FROM theirs.waste_flags;
+    `);
+  } finally {
+    ours.exec("DETACH DATABASE theirs");
+  }
+}
+
+export function mergeDbDriver(args: DriverArgs): void {
+  // Run the merge in a side-DB so a crash mid-replay never leaves ours in
+  // a half-merged state. We copy ours -> a temp file, replay theirs into
+  // the copy, then atomically replace ours via rename. Sidecar WAL/SHM
+  // files in the temp location are cleaned up before rename.
+  const tmp = `${args.oursPath}.merge-${process.pid}-${Date.now()}.tmp`;
+  let ours: ReturnType<typeof openDriver> | null = null;
+  try {
+    copyFileSync(args.oursPath, tmp);
+    ours = openDriver(tmp);
+    ours.exec("PRAGMA journal_mode = WAL");
+    ours.exec("PRAGMA foreign_keys = ON");
+    applySchema(ours); // tolerate `theirs` carrying tables we don't yet have
+
+    attachAndReplay(ours, args.theirsPath);
+
+    ours.exec("PRAGMA wal_checkpoint(TRUNCATE)");
+    ours.close();
+    ours = null;
+
+    // Clean up WAL/SHM sidecars left by the temp DB so the rename target
+    // is a single self-contained file. SQLite truncates the WAL above; we
+    // remove the empty sidecar entries explicitly.
+    for (const suffix of ["-wal", "-shm", "-journal"]) {
+      try { unlinkSync(`${tmp}${suffix}`); } catch { /* not present */ }
+    }
+
+    // Atomic replace.
+    copyFileSync(tmp, args.oursPath);
+    try { unlinkSync(tmp); } catch { /* best effort */ }
+  } catch (err) {
+    logWarning("mink-db-merge", args, err);
+    try { if (ours) ours.close(); } catch { /* ignore */ }
+    try { unlinkSync(tmp); } catch { /* ignore */ }
+    // Fall back to ours by doing nothing — the original args.oursPath is
+    // untouched.
+  }
+}
+
 // ── Dispatcher ─────────────────────────────────────────────────────────────
 
 export function runMergeDriver(
@@ -232,8 +389,14 @@ export function runMergeDriver(
   const args: DriverArgs = { basePath, oursPath, theirsPath, filePath };
   switch (name) {
     case "mink-json-union":
+      // Legacy driver — still registered for projects pre-Phase 2 of the
+      // SQLite migration where file-index.json may resurface during sync
+      // of legacy-backup contents. New projects don't use it.
       mergeJsonUnion(args);
       return 0;
+    case "mink-db-merge":
+      mergeDbDriver(args);
+      return 0;
     case "mink-learning-memory":
       mergeLearningMemoryDriver(args);
       return 0;

package/src/core/sync.ts

@@ -65,6 +65,12 @@ projects/*/scheduler-manifest.json
 projects/*/design-captures/
 projects/*/.mink-state-counters.json
 
+# SQLite write-ahead log + shared-memory sidecars — local-only, must not
+# travel with the main mink.db (WAL is checkpointed before push).
+projects/*/mink.db-wal
+projects/*/mink.db-shm
+projects/*/mink.db-journal
+
 # Wiki derived/regenerable pages — each device rebuilds locally
 wiki/_index.md
 wiki/.mink-index.json
@@ -74,6 +80,8 @@ wiki/projects/*/architecture.md
 
 const GITATTRIBUTES_CONTENTS = `# Sync v2 — merge drivers eliminate conflicts on shared files.
 # Drivers are registered in .git/config by ensureMergeDriversRegistered().
+projects/*/mink.db merge=mink-db-merge
+projects/*/mink.db binary
 projects/*/file-index.json merge=mink-json-union
 projects/*/learning-memory.*.md merge=union
 projects/*/learning-memory.md merge=mink-learning-memory
@@ -120,6 +128,7 @@ export function ensureGitAttributes(): void {
 
 const MERGE_DRIVERS = [
   "mink-json-union",
+  "mink-db-merge",
   "mink-learning-memory",
   "mink-devices",
 ] as const;

package/src/core/token-ledger.ts

@@ -1,3 +1,4 @@
+import { existsSync } from "fs";
 import { join } from "path";
 import type { TokenLedger, LedgerSession, LifetimeCounters } from "../types/token-ledger";
 import type { SessionFinalizer, SessionSummary } from "../types/session";
@@ -158,15 +159,60 @@ export function saveArchive(archivePath: string, newlyArchived: LedgerSession[])
 
 // ── Task 6: Ledger Finalizer Factory ─────────────────────────────────────────
 
+// Phase 4 of the SQLite migration: every projectDir that has a mink.db
+// uses TokenLedgerRepo. Legacy JSON paths still get a finalizer for
+// pre-migration projects (and for unit tests that don't open a DB).
 export function createLedgerFinalizer(
   projectDir: string,
   deviceIdOrThreshold?: string | number,
   archiveThreshold: number = 1000
 ): SessionFinalizer {
-  // Backward compat: callers that pass `(projectDir)` or
-  // `(projectDir, threshold)` still work and write to the legacy path. New
-  // callers pass `(projectDir, deviceId, threshold?)` to write into the
-  // per-device shard at projectDir/state/<deviceId>/...
+  const dbPath = join(projectDir, "mink.db");
+
+  if (existsSync(dbPath)) {
+    // Route through the SQLite repo. We open a fresh handle so this
+    // module doesn't depend on the per-process cache used by hooks.
+    const { openDriver } = require("../storage/driver") as typeof import("../storage/driver");
+    const { applySchema } = require("../storage/schema") as typeof import("../storage/schema");
+    const { TokenLedgerRepo } = require("../repositories/token-ledger-repo") as typeof import("../repositories/token-ledger-repo");
+
+    const deviceId = typeof deviceIdOrThreshold === "string" ? deviceIdOrThreshold : undefined;
+    const threshold = typeof deviceIdOrThreshold === "number"
+      ? deviceIdOrThreshold
+      : archiveThreshold;
+
+    return {
+      appendSession(summary: SessionSummary): void {
+        const db = openDriver(dbPath);
+        try {
+          db.exec("PRAGMA journal_mode = WAL");
+          db.exec("PRAGMA foreign_keys = ON");
+          applySchema(db);
+          const repo = new TokenLedgerRepo(db);
+          repo.appendSession(summary, deviceId);
+          repo.archive(threshold);
+        } finally {
+          db.close();
+        }
+      },
+
+      updateSession(summary: SessionSummary): void {
+        const db = openDriver(dbPath);
+        try {
+          db.exec("PRAGMA journal_mode = WAL");
+          db.exec("PRAGMA foreign_keys = ON");
+          applySchema(db);
+          new TokenLedgerRepo(db).updateSession(summary, deviceId);
+        } finally {
+          db.close();
+        }
+      },
+    };
+  }
+
+  // ── Legacy JSON fallback ────────────────────────────────────────────
+  // Tests + pre-migration projects continue to write to disk. The
+  // `(projectDir)` and `(projectDir, threshold)` signatures still work.
   let ledgerPath: string;
   let archivePath: string;
   let threshold: number;

package/src/repositories/bug-memory-repo.ts

@@ -0,0 +1,268 @@
+// Bug-memory repository. Wraps the bug_memory + bug_tags + bug_related +
+// bug_memory_fts tables in mink.db. The CLI surface (loadBugMemory,
+// findDuplicate, lookupBugsForFile, searchBugs, hasBugForFileInSession)
+// is preserved by the thin wrapper in src/core/bug-memory.ts; this file
+// is where the SQLite queries live.
+//
+// Search uses FTS5 (porter+unicode61 tokenization) so the per-query cost
+// stays sublinear in bug count. The score-vs-false-positive guards from
+// the v1 Jaccard implementation are preserved: a 0.3 score threshold,
+// file-path or tag-overlap match required when score is borderline,
+// same-file matches get a 0.2 boost.
+
+import { randomUUID } from "crypto";
+import type { DbDriver } from "../storage/driver";
+import type { BugEntry, BugMemory, SimilarityMatch } from "../types/bug-memory";
+import { openProjectDb } from "../storage/db";
+import { getOrCreateDeviceId } from "../core/device";
+
+interface BugRow {
+  id: string;
+  created_at: string;
+  last_seen_at: string;
+  error_message: string;
+  file_path: string;
+  line_number: number | null;
+  root_cause: string;
+  fix_description: string;
+  occurrence_count: number;
+}
+
+function tokenize(text: string): Set<string> {
+  return new Set(
+    text.toLowerCase().split(/\W+/).filter((w) => w.length > 0)
+  );
+}
+
+export class BugMemoryRepo {
+  constructor(private readonly db: DbDriver) {}
+
+  static for(cwd: string): BugMemoryRepo {
+    return new BugMemoryRepo(openProjectDb(cwd));
+  }
+
+  // ── Insert / upsert ────────────────────────────────────────────────────
+
+  // Detect an exact-text duplicate of (errorMessage, filePath). Mirrors
+  // the v1 `findDuplicate` semantics — same (errorMessage, filePath)
+  // pair counts as a re-occurrence of the same bug.
+  findDuplicate(errorMessage: string, filePath: string): BugEntry | null {
+    const row = this.db
+      .prepare(
+        "SELECT * FROM bug_memory WHERE error_message = ? AND file_path = ? LIMIT 1"
+      )
+      .get(errorMessage, filePath);
+    if (!row) return null;
+    return this.hydrate(row as unknown as BugRow);
+  }
+
+  add(
+    fields: Omit<BugEntry, "id" | "createdAt" | "lastSeenAt" | "occurrenceCount">
+  ): BugEntry {
+    const existing = this.findDuplicate(fields.errorMessage, fields.filePath);
+    if (existing) {
+      this.incrementOccurrence(existing.id);
+      return this.lookup(existing.id) ?? existing;
+    }
+
+    const id = `bug-${randomUUID().slice(0, 8)}`;
+    const now = new Date().toISOString();
+    const deviceId = getOrCreateDeviceId();
+
+    this.db.transaction(() => {
+      this.db.prepare(`
+        INSERT INTO bug_memory
+          (id, created_at, last_seen_at, error_message, file_path, line_number,
+           root_cause, fix_description, occurrence_count, device_id)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, 1, ?)
+      `).run(
+        id, now, now,
+        fields.errorMessage, fields.filePath, fields.lineNumber ?? null,
+        fields.rootCause, fields.fixDescription, deviceId
+      );
+      const insertTag = this.db.prepare(
+        "INSERT OR IGNORE INTO bug_tags (bug_id, tag) VALUES (?, ?)"
+      );
+      for (const tag of fields.tags ?? []) insertTag.run(id, tag);
+      const insertRelated = this.db.prepare(
+        "INSERT OR IGNORE INTO bug_related (bug_id, related_bug_id) VALUES (?, ?)"
+      );
+      for (const rel of fields.relatedBugIds ?? []) insertRelated.run(id, rel);
+    });
+
+    return this.lookup(id)!;
+  }
+
+  incrementOccurrence(id: string): void {
+    const now = new Date().toISOString();
+    this.db.prepare(
+      "UPDATE bug_memory SET occurrence_count = occurrence_count + 1, last_seen_at = ? WHERE id = ?"
+    ).run(now, id);
+  }
+
+  // ── Read ───────────────────────────────────────────────────────────────
+
+  lookup(id: string): BugEntry | null {
+    const row = this.db
+      .prepare("SELECT * FROM bug_memory WHERE id = ?")
+      .get(id);
+    if (!row) return null;
+    return this.hydrate(row as unknown as BugRow);
+  }
+
+  lookupForFile(filePath: string): BugEntry[] {
+    const rows = this.db
+      .prepare(
+        "SELECT * FROM bug_memory WHERE file_path = ? ORDER BY last_seen_at DESC"
+      )
+      .all(filePath);
+    return (rows as unknown as BugRow[]).map((r) => this.hydrate(r));
+  }
+
+  listAll(): BugEntry[] {
+    const rows = this.db
+      .prepare("SELECT * FROM bug_memory ORDER BY last_seen_at DESC")
+      .all();
+    return (rows as unknown as BugRow[]).map((r) => this.hydrate(r));
+  }
+
+  count(): number {
+    const row = this.db.prepare("SELECT COUNT(*) AS n FROM bug_memory").get();
+    return Number((row as { n: number }).n);
+  }
+
+  hasBugForFileInSession(filePath: string, sessionStartIso: string): boolean {
+    const row = this.db
+      .prepare(
+        "SELECT 1 FROM bug_memory WHERE file_path = ? AND created_at >= ? LIMIT 1"
+      )
+      .get(filePath, sessionStartIso);
+    return row !== undefined;
+  }
+
+  // ── Search (FTS5) ──────────────────────────────────────────────────────
+
+  // Preserves the v1 contract: scores in (0, 1+) range, 0.3 threshold,
+  // file-path/tag boost. FTS5's bm25 returns negative scores (lower =
+  // better), so we normalize via `1 / (1 + abs(bm25))` to land in (0, 1].
+  // The boost for same-file matches stays at +0.2 and the same false-
+  // positive guards (require file-path or tag overlap when borderline)
+  // apply.
+  searchBugs(
+    query: string,
+    options?: { filePath?: string }
+  ): SimilarityMatch[] {
+    if (query.trim().length === 0) return [];
+
+    // FTS5 MATCH requires escaped phrase quoting for queries with
+    // punctuation. Build a phrase query if the input has anything
+    // weirder than alphanum + spaces.
+    const ftsQuery = buildFtsQuery(query);
+    if (ftsQuery === null) return [];
+
+    type FtsRow = { bug_id: string; bm25: number };
+    let ftsRows: FtsRow[] = [];
+    try {
+      ftsRows = this.db
+        .prepare(
+          "SELECT bug_id, bm25(bug_memory_fts) AS bm25 FROM bug_memory_fts WHERE bug_memory_fts MATCH ? ORDER BY bm25"
+        )
+        .all(ftsQuery) as unknown as FtsRow[];
+    } catch {
+      // FTS query parse error — fall back silently to no matches.
+      return [];
+    }
+
+    const queryTokens = tokenize(query);
+    const results: SimilarityMatch[] = [];
+
+    for (const row of ftsRows) {
+      const entry = this.lookup(row.bug_id);
+      if (!entry) continue;
+
+      // bm25 is negative; smaller magnitude == better match.
+      const ftsScore = 1 / (1 + Math.abs(row.bm25));
+      const matchReasons: string[] = ["fts"];
+
+      // Exact substring boost (matches v1 behavior).
+      let score = ftsScore;
+      if (entry.errorMessage.length > 0 && entry.errorMessage.includes(query)) {
+        score += 1.0;
+        matchReasons.unshift("exact_error_match");
+      }
+
+      const fileMatch = options?.filePath ? entry.filePath === options.filePath : false;
+      const tagMatch = entry.tags.some((tag) => queryTokens.has(tag.toLowerCase()));
+
+      // Same false-positive guard as v1: when the score is borderline
+      // (<= 0.3), only keep matches that also satisfy file-path or
+      // tag-overlap.
+      if (score <= 0.3 && !fileMatch && !tagMatch) continue;
+
+      if (fileMatch) {
+        score += 0.2;
+        matchReasons.push("file_path");
+      }
+      if (tagMatch) matchReasons.push("tags");
+
+      if (score > 0.3) {
+        results.push({ entry, score, matchReasons });
+      }
+    }
+
+    return results.sort((a, b) => b.score - a.score);
+  }
+
+  // ── Helpers ────────────────────────────────────────────────────────────
+
+  private hydrate(row: BugRow): BugEntry {
+    const tags = this.db
+      .prepare("SELECT tag FROM bug_tags WHERE bug_id = ? ORDER BY tag")
+      .all(row.id)
+      .map((r) => (r as { tag: string }).tag);
+    const relatedBugIds = this.db
+      .prepare(
+        "SELECT related_bug_id FROM bug_related WHERE bug_id = ? ORDER BY related_bug_id"
+      )
+      .all(row.id)
+      .map((r) => (r as { related_bug_id: string }).related_bug_id);
+    return {
+      id: row.id,
+      createdAt: row.created_at,
+      lastSeenAt: row.last_seen_at,
+      errorMessage: row.error_message,
+      filePath: row.file_path,
+      lineNumber: row.line_number ?? undefined,
+      rootCause: row.root_cause,
+      fixDescription: row.fix_description,
+      tags,
+      occurrenceCount: row.occurrence_count,
+      relatedBugIds,
+    };
+  }
+
+  // Convert the entire repo to the legacy BugMemory snapshot shape. Used
+  // by callers (dashboard, status) that still expect `{ entries, nextId }`.
+  snapshot(): BugMemory {
+    return {
+      entries: this.listAll(),
+      // nextId was only used by the in-memory generator; new ids come
+      // from randomUUID, so any value > current count is safe.
+      nextId: this.count() + 1,
+    };
+  }
+}
+
+// Build an FTS5 query string from arbitrary user input. FTS5's grammar
+// treats colons, parens, quotes, etc. as operators — we phrase-quote the
+// whole query to avoid syntax errors. Returns null for inputs that have
+// no searchable tokens.
+function buildFtsQuery(raw: string): string | null {
+  const trimmed = raw.trim();
+  if (trimmed.length === 0) return null;
+  // Drop characters that can't appear inside FTS5 phrase quotes.
+  const safe = trimmed.replace(/"/g, " ").trim();
+  if (safe.length === 0) return null;
+  // Quote so punctuation/colons/parens don't become operators.
+  return `"${safe}"`;
+}

package/src/repositories/counters-repo.ts

@@ -0,0 +1,88 @@
+// Per-device hit/miss counters for the file index. Replaces the legacy
+// `.mink-state-counters.json` file (read by the dashboard and by
+// `mink status`) with a SQLite-backed table that's queryable per device
+// or aggregated across all devices in a single SQL statement.
+
+import type { DbDriver } from "../storage/driver";
+import { openProjectDb } from "../storage/db";
+import { getOrCreateDeviceId } from "../core/device";
+
+const INCREMENT_HIT = `
+  INSERT INTO counters (device_id, file_index_hits, file_index_misses)
+  VALUES (?, 1, 0)
+  ON CONFLICT(device_id) DO UPDATE SET
+    file_index_hits = counters.file_index_hits + 1
+`;
+
+const INCREMENT_MISS = `
+  INSERT INTO counters (device_id, file_index_hits, file_index_misses)
+  VALUES (?, 0, 1)
+  ON CONFLICT(device_id) DO UPDATE SET
+    file_index_misses = counters.file_index_misses + 1
+`;
+
+export class CountersRepo {
+  constructor(private readonly db: DbDriver) {}
+
+  static for(cwd: string): CountersRepo {
+    return new CountersRepo(openProjectDb(cwd));
+  }
+
+  incrementHit(deviceId: string = getOrCreateDeviceId()): void {
+    this.db.prepare(INCREMENT_HIT).run(deviceId);
+  }
+
+  incrementMiss(deviceId: string = getOrCreateDeviceId()): void {
+    this.db.prepare(INCREMENT_MISS).run(deviceId);
+  }
+
+  // Returns this device's hit + miss counts (zero for either if no row
+  // exists yet). The dashboard and `mink status` show per-device totals,
+  // but callers that want a project-wide view use totals().
+  forDevice(deviceId: string = getOrCreateDeviceId()): { hits: number; misses: number } {
+    const row = this.db
+      .prepare(
+        "SELECT file_index_hits, file_index_misses FROM counters WHERE device_id = ?"
+      )
+      .get(deviceId);
+    if (!row) return { hits: 0, misses: 0 };
+    return {
+      hits: Number((row as { file_index_hits: number }).file_index_hits),
+      misses: Number((row as { file_index_misses: number }).file_index_misses),
+    };
+  }
+
+  totals(): { hits: number; misses: number } {
+    const row = this.db
+      .prepare(
+        "SELECT COALESCE(SUM(file_index_hits), 0) AS h, COALESCE(SUM(file_index_misses), 0) AS m FROM counters"
+      )
+      .get();
+    if (!row) return { hits: 0, misses: 0 };
+    return {
+      hits: Number((row as { h: number }).h),
+      misses: Number((row as { m: number }).m),
+    };
+  }
+
+  perDevice(): Record<string, { hits: number; misses: number }> {
+    const rows = this.db
+      .prepare(
+        "SELECT device_id, file_index_hits, file_index_misses FROM counters"
+      )
+      .all();
+    const out: Record<string, { hits: number; misses: number }> = {};
+    for (const r of rows) {
+      const row = r as {
+        device_id: string;
+        file_index_hits: number;
+        file_index_misses: number;
+      };
+      out[row.device_id] = {
+        hits: Number(row.file_index_hits),
+        misses: Number(row.file_index_misses),
+      };
+    }
+    return out;
+  }
+}