@selesai/code 0.13.13 → 0.13.14

package/dist/extensions/pi-hermes-memory/src/store/db.ts

@@ -0,0 +1,1180 @@
+import path from 'node:path';
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+import { SCHEMA_SQL } from './schema.js';
+import { AtomicLockCoordinator } from './atomic-lock-coordinator.js';
+import { canonicalStoragePathSync } from './canonical-storage-path.js';
+import { isBunRuntime, loadBetterSqlite3 } from './sqlite-native.js';
+import { measureLifecycleSync } from '../lifecycle-timing.js';
+
+type StatementLike = {
+  run: (...args: any[]) => any;
+  get: (...args: any[]) => any;
+  all: (...args: any[]) => any;
+  iterate?: (...args: any[]) => Iterable<Record<string, unknown>>;
+};
+
+type DatabaseLike = {
+  prepare: (sql: string) => StatementLike;
+  exec: (sql: string) => void;
+  close: () => void;
+  pragma?: (query: string, options?: any) => any;
+  transaction?: (fn: any) => any;
+};
+
+type DatabaseCtor = new (dbPath: string) => DatabaseLike;
+type BunDatabaseInstance = {
+  prepare: (sql: string) => StatementLike;
+  exec: (sql: string) => void;
+  close: (throwOnError?: boolean) => void;
+  transaction?: (fn: any) => any;
+};
+
+type DatabaseFileSuffix = '' | '-wal' | '-shm';
+
+type MovedDatabaseFile = {
+  original: string;
+  backup: string;
+};
+
+export interface DatabaseRecoveryResult {
+  strategy: 'rebuilt' | 'recreated-empty' | 'reused';
+  backupPaths: string[];
+  recoveredRows?: Record<string, number>;
+  error?: string;
+}
+
+export interface DatabaseRecoveryOptions {
+  recoveryLockWaitMs?: number;
+  recoveryLockPollMs?: number;
+  recoveryLockStaleMs?: number;
+  recoveryCircuitLimit?: number;
+  recoveryCircuitWindowMs?: number;
+  recoveryBackupRetention?: number;
+}
+
+interface ResolvedDatabaseRecoveryOptions {
+  recoveryLockWaitMs: number;
+  recoveryLockPollMs: number;
+  recoveryLockStaleMs: number;
+  recoveryCircuitLimit: number;
+  recoveryCircuitWindowMs: number;
+  recoveryBackupRetention: number;
+}
+
+class DatabaseCorruptionError extends Error {
+  code = 'SQLITE_CORRUPT';
+
+  constructor(message: string) {
+    super(message);
+    this.name = 'DatabaseCorruptionError';
+  }
+}
+
+export const SQLITE_BUSY_TIMEOUT_MS = 5000;
+export const SQLITE_WAL_AUTOCHECKPOINT_PAGES = 1000;
+export const FTS5_MIGRATION_MAX_LOCK_ATTEMPTS = 3;
+
+const FTS5_TOKENIZER_VERSION_KEY = 'fts5_tokenizer_version';
+const FTS5_TOKENIZER_VERSION = 'trigram-v1';
+const FTS5_TRIGRAM_TABLES = {
+  message: `CREATE VIRTUAL TABLE message_fts USING fts5(
+    content,
+    content='messages',
+    content_rowid='rowid',
+    tokenize='trigram'
+  )`,
+  memory: `CREATE VIRTUAL TABLE memory_fts USING fts5(
+    content,
+    content='memories',
+    content_rowid='id',
+    tokenize='trigram'
+  )`,
+} as const;
+
+const DATABASE_FILE_SUFFIXES: readonly DatabaseFileSuffix[] = ['', '-wal', '-shm'];
+const MEMORY_TARGETS = new Set(['memory', 'user', 'failure']);
+const MEMORY_CATEGORIES = new Set(['failure', 'correction', 'insight', 'preference', 'convention', 'tool-quirk']);
+const DEFAULT_RECOVERY_OPTIONS: ResolvedDatabaseRecoveryOptions = {
+  recoveryLockWaitMs: 5000,
+  recoveryLockPollMs: 50,
+  recoveryLockStaleMs: 300000,
+  recoveryCircuitLimit: 3,
+  recoveryCircuitWindowMs: 300000,
+  recoveryBackupRetention: 3,
+};
+
+function quoteIdentifier(identifier: string): string {
+  return `"${identifier.replace(/"/g, '""')}"`;
+}
+
+function createBunCompatDatabaseCtor(require: NodeRequire): DatabaseCtor {
+  const bunSqlite = require('bun:sqlite') as { Database: new (dbPath: string) => BunDatabaseInstance };
+
+  return class BunCompatDatabase implements DatabaseLike {
+    private readonly db: BunDatabaseInstance;
+
+    constructor(dbPath: string) {
+      this.db = new bunSqlite.Database(dbPath);
+    }
+
+    prepare(sql: string): StatementLike {
+      return this.db.prepare(sql);
+    }
+
+    exec(sql: string): void {
+      this.db.exec(sql);
+    }
+
+    close(): void {
+      this.db.close();
+    }
+
+    transaction(fn: any): any {
+      if (!this.db.transaction) {
+        return undefined;
+      }
+      return this.db.transaction(fn);
+    }
+  };
+}
+
+let cachedDatabaseCtor: DatabaseCtor | null = null;
+
+/**
+ * Resolved on first use, never at import time. A module-scope native load turns
+ * any SQLite resolve/ABI failure into "Failed to load extension", which hides
+ * the actionable rebuild message and bricks the whole extension (issue #117).
+ */
+function getDatabaseCtor(): DatabaseCtor {
+  if (!cachedDatabaseCtor) {
+    const require = createRequire(import.meta.url);
+    cachedDatabaseCtor = isBunRuntime()
+      ? createBunCompatDatabaseCtor(require)
+      : (loadBetterSqlite3({ requireImpl: require }) as DatabaseCtor);
+  }
+  return cachedDatabaseCtor;
+}
+
+export class DatabaseManager {
+  private db: DatabaseLike | null = null;
+  private readonly displayDbPath: string;
+  private canonicalDbPath: string | null = null;
+  private readonly recoveryOptions: ResolvedDatabaseRecoveryOptions;
+  private lastRecovery: DatabaseRecoveryResult | null = null;
+  private openGuard: (() => void) | null = null;
+  private pendingOpenIntegrityScan: Promise<void> | null = null;
+  private activeRecoveryLease: { coordinator: AtomicLockCoordinator; key: string; token: string } | null = null;
+
+  constructor(memoryDir: string, recoveryOptions: DatabaseRecoveryOptions = {}) {
+    this.displayDbPath = path.join(memoryDir, 'sessions.db');
+    this.recoveryOptions = { ...DEFAULT_RECOVERY_OPTIONS, ...recoveryOptions };
+  }
+
+  private get dbPath(): string {
+    if (!this.canonicalDbPath) {
+      this.canonicalDbPath = canonicalStoragePathSync(this.displayDbPath);
+    }
+    return this.canonicalDbPath;
+  }
+
+  setOpenGuard(guard: (() => void) | null): void {
+    this.openGuard = guard;
+  }
+
+  /**
+   * True when an error indicates SQLite file/page corruption rather than a
+   * normal constraint, migration, or query failure.
+   */
+  static isCorruptionError(err: unknown): boolean {
+    if (!err) return false;
+
+    const code = typeof err === 'object' && 'code' in err ? String((err as { code?: unknown }).code) : '';
+    if (code === 'SQLITE_CORRUPT' || code === 'SQLITE_NOTADB') return true;
+
+    const message = DatabaseManager.errorMessage(err).toLowerCase();
+    return message.includes('database disk image is malformed')
+      || message.includes('file is not a database')
+      || message.includes('database schema is corrupt')
+      || message.includes('malformed database schema')
+      || message.includes('btreeinitpage')
+      || message.includes('sqlite_corrupt')
+      || message.includes('sqlite_notadb');
+  }
+
+  private static errorMessage(err: unknown): string {
+    if (err instanceof Error) return err.message;
+    return String(err);
+  }
+
+  /**
+   * Get the database instance. Creates/opens on first call.
+   */
+  getDb(): DatabaseLike {
+    if (!this.db) {
+      this.openGuard?.();
+      this.db = this.open();
+    }
+    return this.db;
+  }
+
+  /**
+   * Last self-heal performed by this manager, if any. Exposed for diagnostics
+   * and tests; normal callers do not need it.
+   */
+  getLastRecovery(): DatabaseRecoveryResult | null {
+    return this.lastRecovery;
+  }
+
+  /**
+   * Retry a DB operation once after quarantining/rebuilding a corrupt DB.
+   */
+  withCorruptionRecovery<T>(operation: () => T): T {
+    try {
+      return operation();
+    } catch (err) {
+      if (!DatabaseManager.isCorruptionError(err)) {
+        throw err;
+      }
+      this.recoverFromCorruption(err);
+      return operation();
+    }
+  }
+
+  /**
+   * Close any open handle, rebuild/quarantine the DB file set, and let the next
+   * getDb() reopen a clean database.
+   */
+  recoverFromCorruption(cause?: unknown): DatabaseRecoveryResult {
+    this.close();
+    let verifiedDb: DatabaseLike | null = null;
+    let recovery: DatabaseRecoveryResult;
+    try {
+      recovery = this.recoverDatabaseFile(cause, () => {
+        verifiedDb = this.openUnchecked();
+      });
+    } finally {
+      if (verifiedDb) this.safeClose(verifiedDb);
+    }
+    this.lastRecovery = recovery;
+    return recovery;
+  }
+
+  /**
+   * Open the database and initialize schema.
+   */
+  private open(): DatabaseLike {
+    return measureLifecycleSync('database.open', () => {
+      const dir = path.dirname(this.dbPath);
+      if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+      }
+
+      let opened: DatabaseLike;
+      try {
+        opened = this.openUnchecked();
+      } catch (err) {
+        if (!DatabaseManager.isCorruptionError(err)) {
+          throw err;
+        }
+
+        let recoveredDb: DatabaseLike | null = null;
+        let recovery: DatabaseRecoveryResult;
+        try {
+          recovery = this.recoverDatabaseFile(err, () => {
+            recoveredDb = this.openUnchecked();
+          });
+        } catch (error) {
+          if (recoveredDb) this.safeClose(recoveredDb);
+          throw error;
+        }
+        this.lastRecovery = recovery;
+        if (!recoveredDb) throw new Error(`SQLite recovery verification did not open ${this.displayDbPath}`);
+        return recoveredDb;
+      }
+
+      this.scheduleOpenIntegrityScan(opened);
+      return opened;
+    });
+  }
+
+  /**
+   * quick_check walks the whole DB, so open() never pays that cost: the scan
+   * runs after open returns and failures go through the same recovery used
+   * at operation time.
+   */
+  private scheduleOpenIntegrityScan(db: DatabaseLike): void {
+    if (this.pendingOpenIntegrityScan) return;
+    const scan = new Promise<void>((resolve) => {
+      setTimeout(() => {
+        try {
+          if (this.db !== db) {
+            // Manager closed or reopened; the newest open schedules its own
+            // scan, so skip to avoid a stale-handle recovery.
+            return;
+          }
+          measureLifecycleSync('database.quick-check', () => {
+            try {
+              this.assertIntegrityOk(db, 'quick_check', 'after open');
+            } catch (err) {
+              try {
+                this.recoverFromCorruption(err);
+              } catch {
+                // Best-effort here; at-operation withCorruptionRecovery still
+                // quarantines and rebuilds if a later statement hits the corruption.
+              }
+            }
+          });
+        } finally {
+          if (this.pendingOpenIntegrityScan === scan) {
+            this.pendingOpenIntegrityScan = null;
+          }
+          resolve();
+        }
+      }, 0);
+    });
+    this.pendingOpenIntegrityScan = scan;
+  }
+
+  /** Test aid. */
+  async waitForStartupIntegrityScan(): Promise<void> {
+    await this.pendingOpenIntegrityScan;
+  }
+
+  private openUnchecked(): DatabaseLike {
+    const db = new (getDatabaseCtor())(this.dbPath);
+    let ok = false;
+
+    try {
+      this.configureConnection(db);
+      this.initializeSchema(db);
+      ok = true;
+      return db;
+    } finally {
+      if (!ok) {
+        this.safeClose(db);
+      }
+    }
+  }
+
+  private configureConnection(db: DatabaseLike): void {
+    // Wait briefly for concurrent writers across Pi processes instead of failing
+    // immediately with SQLITE_BUSY. Connection-local; applies before WAL/schema.
+    db.exec(`PRAGMA busy_timeout = ${SQLITE_BUSY_TIMEOUT_MS}`);
+    // Enable WAL mode + FK enforcement for each connection. Keep SQLite's
+    // default WAL autocheckpoint size; a very aggressive checkpoint cadence
+    // increases the chance that abrupt VM/host shutdown catches a checkpoint.
+    db.exec('PRAGMA journal_mode = WAL');
+    db.exec(`PRAGMA wal_autocheckpoint = ${SQLITE_WAL_AUTOCHECKPOINT_PAGES}`);
+    db.exec('PRAGMA journal_size_limit = 5242880');
+    db.exec('PRAGMA foreign_keys = ON');
+  }
+
+  private initializeSchema(db: DatabaseLike): void {
+    // Create tables and triggers
+    try {
+      db.exec(SCHEMA_SQL);
+    } catch (err) {
+      if (!this.isLegacySchemaError(err)) {
+        throw err;
+      }
+
+      // Legacy DBs can be missing v0.6 failure-memory columns and/or the project
+      // column on sessions/memories. Add missing columns, then retry schema.
+      this.ensureLegacySchemaColumns(db);
+      db.exec(SCHEMA_SQL);
+    }
+
+    // Extra safety: always ensure legacy columns exist, then migrate legacy
+    // CHECK(target IN ('memory','user')) constraints to include 'failure'.
+    this.ensureLegacySchemaColumns(db);
+    this.migrateLegacyMemoriesTargetConstraint(db);
+    // Recreate indexes after any legacy table replacement. `DROP TABLE`
+    // removes indexes attached to the old memories table.
+    this.ensureMemoryIndexes(db);
+    this.migrateFtsTokenizer(db);
+  }
+
+  private hasExistingMainDatabaseFile(): boolean {
+    try {
+      return fs.existsSync(this.dbPath) && fs.statSync(this.dbPath).size > 0;
+    } catch {
+      return false;
+    }
+  }
+
+  private databaseFileSetExists(): boolean {
+    return DATABASE_FILE_SUFFIXES.some((suffix) => fs.existsSync(`${this.dbPath}${suffix}`));
+  }
+
+  private assertIntegrityOk(
+    db: DatabaseLike,
+    check: 'quick_check' | 'integrity_check' = 'quick_check',
+    context = '',
+  ): void {
+    const rows = db.prepare(`PRAGMA ${check}`).all() as Record<string, unknown>[];
+    const messages = rows.map((row) => String(Object.values(row)[0] ?? ''));
+    const failures = messages.filter((message) => message.toLowerCase() !== 'ok');
+
+    if (rows.length === 0 || failures.length > 0) {
+      const detail = failures.length > 0 ? failures.slice(0, 5).join('\n') : 'no result rows';
+      const suffix = context ? ` ${context}` : '';
+      throw new DatabaseCorruptionError(`SQLite ${check} failed${suffix}: ${detail}`);
+    }
+  }
+
+  private assertForeignKeysOk(db: DatabaseLike): void {
+    const rows = db.prepare('PRAGMA foreign_key_check').all() as Record<string, unknown>[];
+    if (rows.length > 0) {
+      throw new Error(`SQLite foreign_key_check failed after rebuild (${rows.length} violation${rows.length === 1 ? '' : 's'})`);
+    }
+  }
+
+  private recoverDatabaseFile(cause: unknown, verify: () => void): DatabaseRecoveryResult {
+    const coordinator = AtomicLockCoordinator.shared(path.join(path.dirname(this.dbPath), '.pi-hermes-locks.sqlite'));
+    const lockKey = `recovery:${this.dbPath}`;
+    const deadline = Date.now() + Math.max(0, this.recoveryOptions.recoveryLockWaitMs);
+
+    while (true) {
+      const lease = coordinator.tryAcquire(lockKey, { staleMs: this.recoveryOptions.recoveryLockStaleMs });
+      if (!lease) {
+        if (Date.now() >= deadline) {
+          throw new Error(`SQLite recovery already in progress for ${this.displayDbPath}; timed out after ${this.recoveryOptions.recoveryLockWaitMs}ms`);
+        }
+        DatabaseManager.sleepSync(Math.min(
+          this.recoveryOptions.recoveryLockPollMs,
+          Math.max(1, deadline - Date.now()),
+        ));
+        continue;
+      }
+
+      this.activeRecoveryLease = { coordinator, key: lockKey, token: lease.token };
+      try {
+        if (this.currentDatabaseIsHealthy()) {
+          try {
+            verify();
+            this.clearRecoveryFailuresBestEffort();
+            return { strategy: 'reused', backupPaths: [] };
+          } catch (error) {
+            this.recordRecoveryFailure();
+            throw error;
+          }
+        }
+
+        this.assertRecoveryCircuitClosed();
+        try {
+          this.cleanupRecoveryArtifactsBestEffort();
+          const result = this.recoverDatabaseFileUnlocked(cause);
+          verify();
+          this.cleanupRecoveryArtifactsBestEffort();
+          this.clearRecoveryFailuresBestEffort();
+          return result;
+        } catch (error) {
+          this.recordRecoveryFailure();
+          throw error;
+        }
+      } finally {
+        this.activeRecoveryLease = null;
+        lease.release();
+      }
+    }
+  }
+
+  private recoverDatabaseFileUnlocked(cause?: unknown): DatabaseRecoveryResult {
+    const backupBase = this.corruptBackupBase();
+    let rebuildError: unknown;
+
+    if (this.databaseFileSetExists()) {
+      try {
+        return this.rebuildDatabaseFromReadableRows(backupBase);
+      } catch (err) {
+        rebuildError = err;
+      }
+    }
+
+    const moved = this.moveDatabaseFilesToBackup(backupBase);
+    return {
+      strategy: 'recreated-empty',
+      backupPaths: moved.map((file) => file.backup),
+      error: DatabaseManager.errorMessage(rebuildError ?? cause ?? 'unknown corruption'),
+    };
+  }
+
+  private currentDatabaseIsHealthy(): boolean {
+    if (!this.hasExistingMainDatabaseFile()) return false;
+    let db: DatabaseLike | null = null;
+    try {
+      db = new (getDatabaseCtor())(this.dbPath);
+      this.assertIntegrityOk(db, 'quick_check', 'while joining corruption recovery');
+      return true;
+    } catch {
+      return false;
+    } finally {
+      if (db) this.safeClose(db);
+    }
+  }
+
+  private recoveryCircuitPath(): string {
+    return `${this.dbPath}.recovery-state.json`;
+  }
+
+  private recentRecoveryFailures(): number[] {
+    try {
+      const parsed = JSON.parse(fs.readFileSync(this.recoveryCircuitPath(), 'utf-8')) as { failures?: unknown };
+      if (!Array.isArray(parsed.failures)) return [];
+      const cutoff = Date.now() - Math.max(0, this.recoveryOptions.recoveryCircuitWindowMs);
+      return parsed.failures.filter((value): value is number => typeof value === 'number' && value >= cutoff);
+    } catch {
+      return [];
+    }
+  }
+
+  private assertRecoveryCircuitClosed(): void {
+    if (this.recentRecoveryFailures().length >= Math.max(1, this.recoveryOptions.recoveryCircuitLimit)) {
+      throw new Error(
+        `SQLite recovery circuit is open for ${this.displayDbPath}: too many failed recovery attempts within ${this.recoveryOptions.recoveryCircuitWindowMs}ms`,
+      );
+    }
+  }
+
+  private recordRecoveryFailure(): void {
+    const statePath = this.recoveryCircuitPath();
+    const tempPath = `${statePath}.tmp-${process.pid}-${Math.random().toString(16).slice(2, 8)}`;
+    const failures = [...this.recentRecoveryFailures(), Date.now()];
+    try {
+      fs.writeFileSync(tempPath, JSON.stringify({ failures }), { encoding: 'utf-8', mode: 0o600 });
+      fs.renameSync(tempPath, statePath);
+    } finally {
+      fs.rmSync(tempPath, { force: true });
+    }
+  }
+
+  private clearRecoveryFailures(): void {
+    fs.rmSync(this.recoveryCircuitPath(), { force: true });
+  }
+
+  private clearRecoveryFailuresBestEffort(): void {
+    try { this.clearRecoveryFailures(); } catch {}
+  }
+
+  private cleanupRecoveryArtifactsBestEffort(): void {
+    try { this.cleanupRecoveryArtifacts(); } catch {}
+  }
+
+  private cleanupRecoveryArtifacts(): void {
+    const dir = path.dirname(this.dbPath);
+    const databaseName = path.basename(this.dbPath);
+    let names: string[];
+    try {
+      names = fs.readdirSync(dir);
+    } catch {
+      return;
+    }
+
+    for (const name of names) {
+      if (name.startsWith(`${databaseName}.rebuild-`)) {
+        fs.rmSync(path.join(dir, name), { recursive: true, force: true });
+      }
+    }
+
+    const backupGroups = new Map<string, number>();
+    for (const name of names) {
+      if (!name.startsWith(`${databaseName}.corrupt-`)) continue;
+      const group = name.replace(/-(?:wal|shm)$/, '');
+      try {
+        const mtimeMs = fs.statSync(path.join(dir, name)).mtimeMs;
+        backupGroups.set(group, Math.max(backupGroups.get(group) ?? 0, mtimeMs));
+      } catch {
+        // Artifact disappeared while scanning.
+      }
+    }
+
+    const retained = Math.max(0, this.recoveryOptions.recoveryBackupRetention);
+    const expired = [...backupGroups.entries()]
+      .sort((left, right) => right[1] - left[1])
+      .slice(retained);
+    for (const [group] of expired) {
+      for (const suffix of DATABASE_FILE_SUFFIXES) {
+        fs.rmSync(path.join(dir, `${group}${suffix}`), { force: true });
+      }
+    }
+  }
+
+  private static sleepSync(milliseconds: number): void {
+    if (milliseconds <= 0) return;
+    const signal = new Int32Array(new SharedArrayBuffer(4));
+    Atomics.wait(signal, 0, 0, milliseconds);
+  }
+
+  private rebuildDatabaseFromReadableRows(backupBase: string): DatabaseRecoveryResult {
+    const tempPath = this.rebuildTempPath();
+    this.removeDatabaseFileSet(tempPath);
+
+    let source: DatabaseLike | null = null;
+    let target: DatabaseLike | null = null;
+    let recoveredRows: Record<string, number> | undefined;
+    let rebuildOk = false;
+
+    try {
+      const Database = getDatabaseCtor();
+      source = new Database(this.dbPath);
+      target = new Database(tempPath);
+      target.exec('PRAGMA journal_mode = DELETE');
+      target.exec('PRAGMA foreign_keys = OFF');
+      target.exec(SCHEMA_SQL);
+
+      recoveredRows = this.copyRecoverableRows(source, target);
+      this.rebuildFtsTables(target);
+      this.assertForeignKeysOk(target);
+      this.assertIntegrityOk(target, 'quick_check', 'after corruption rebuild');
+      rebuildOk = true;
+    } finally {
+      if (source) this.safeClose(source);
+      if (target) this.safeClose(target);
+      if (!rebuildOk) this.removeDatabaseFileSet(tempPath);
+    }
+
+    const moved = this.swapRebuiltDatabase(tempPath, backupBase);
+    this.removeDatabaseFileSet(tempPath);
+
+    return {
+      strategy: 'rebuilt',
+      backupPaths: moved.map((file) => file.backup),
+      recoveredRows,
+    };
+  }
+
+  private copyRecoverableRows(source: DatabaseLike, target: DatabaseLike): Record<string, number> {
+    return {
+      extension_metadata: this.copyExtensionMetadata(source, target),
+      sessions: this.copySessions(source, target),
+      messages: this.copyMessages(source, target),
+      session_files: this.copySessionFiles(source, target),
+      memories: this.copyMemories(source, target),
+    };
+  }
+
+  private copyExtensionMetadata(source: DatabaseLike, target: DatabaseLike): number {
+    const insert = target.prepare('INSERT OR REPLACE INTO extension_metadata (key, value) VALUES (?, ?)');
+    let copied = 0;
+
+    for (const row of this.readTableRows(source, 'extension_metadata', ['key', 'value'])) {
+      if (typeof row.key !== 'string' || typeof row.value !== 'string') continue;
+      insert.run(row.key, row.value);
+      copied++;
+    }
+
+    return copied;
+  }
+
+  private copySessions(source: DatabaseLike, target: DatabaseLike): number {
+    const insert = target.prepare(`
+      INSERT OR IGNORE INTO sessions (id, project, cwd, started_at, ended_at, message_count)
+      VALUES (?, ?, ?, ?, ?, ?)
+    `);
+    let copied = 0;
+
+    for (const row of this.readTableRows(source, 'sessions', ['id', 'project', 'cwd', 'started_at', 'ended_at', 'message_count'])) {
+      if (typeof row.id !== 'string' || typeof row.cwd !== 'string' || typeof row.started_at !== 'string') continue;
+      const project = typeof row.project === 'string' && row.project ? row.project : (path.basename(row.cwd) || 'unknown');
+      insert.run(
+        row.id,
+        project,
+        row.cwd,
+        row.started_at,
+        this.nullableString(row.ended_at),
+        this.integerOr(row.message_count, 0),
+      );
+      copied++;
+    }
+
+    return copied;
+  }
+
+  private copyMessages(source: DatabaseLike, target: DatabaseLike): number {
+    const insert = target.prepare(`
+      INSERT OR IGNORE INTO messages (id, session_id, role, content, timestamp, tool_calls)
+      VALUES (?, ?, ?, ?, ?, ?)
+    `);
+    let copied = 0;
+
+    for (const row of this.readTableRows(source, 'messages', ['id', 'session_id', 'role', 'content', 'timestamp', 'tool_calls'])) {
+      if (
+        typeof row.id !== 'string'
+        || typeof row.session_id !== 'string'
+        || (row.role !== 'user' && row.role !== 'assistant' && row.role !== 'system')
+        || typeof row.content !== 'string'
+        || typeof row.timestamp !== 'string'
+      ) {
+        continue;
+      }
+
+      insert.run(row.id, row.session_id, row.role, row.content, row.timestamp, this.nullableString(row.tool_calls));
+      copied++;
+    }
+
+    return copied;
+  }
+
+  private copySessionFiles(source: DatabaseLike, target: DatabaseLike): number {
+    const insert = target.prepare(`
+      INSERT OR IGNORE INTO session_files (path, session_id, size, mtime_ms, indexed_at)
+      VALUES (?, ?, ?, ?, ?)
+    `);
+    let copied = 0;
+
+    for (const row of this.readTableRows(source, 'session_files', ['path', 'session_id', 'size', 'mtime_ms', 'indexed_at'])) {
+      if (typeof row.path !== 'string' || typeof row.session_id !== 'string') continue;
+      insert.run(
+        row.path,
+        row.session_id,
+        this.integerOr(row.size, 0),
+        this.integerOr(row.mtime_ms, 0),
+        typeof row.indexed_at === 'string' ? row.indexed_at : new Date(0).toISOString(),
+      );
+      copied++;
+    }
+
+    return copied;
+  }
+
+  private copyMemories(source: DatabaseLike, target: DatabaseLike): number {
+    const insert = target.prepare(`
+      INSERT OR IGNORE INTO memories (id, project, target, category, content, failure_reason, tool_state, corrected_to, created, last_referenced)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `);
+    let copied = 0;
+
+    for (const row of this.readTableRows(source, 'memories', [
+      'id',
+      'project',
+      'target',
+      'category',
+      'content',
+      'failure_reason',
+      'tool_state',
+      'corrected_to',
+      'created',
+      'last_referenced',
+    ])) {
+      const id = this.integerOr(row.id, NaN);
+      if (!Number.isFinite(id) || typeof row.content !== 'string') continue;
+
+      const targetName = typeof row.target === 'string' && MEMORY_TARGETS.has(row.target) ? row.target : 'memory';
+      const category = typeof row.category === 'string' && MEMORY_CATEGORIES.has(row.category) ? row.category : null;
+      const created = typeof row.created === 'string' ? row.created : new Date(0).toISOString();
+      const lastReferenced = typeof row.last_referenced === 'string' ? row.last_referenced : created;
+
+      insert.run(
+        id,
+        this.nullableString(row.project),
+        targetName,
+        category,
+        row.content,
+        this.nullableString(row.failure_reason),
+        this.nullableString(row.tool_state),
+        this.nullableString(row.corrected_to),
+        created,
+        lastReferenced,
+      );
+      copied++;
+    }
+
+    return copied;
+  }
+
+  private readTableRows(source: DatabaseLike, table: string, desiredColumns: string[]): Iterable<Record<string, unknown>> {
+    const columns = this.getColumnNames(source, table);
+    const selected = desiredColumns.filter((column) => columns.has(column));
+    if (selected.length === 0) return [];
+
+    const sql = `SELECT ${selected.map(quoteIdentifier).join(', ')} FROM ${quoteIdentifier(table)} NOT INDEXED`;
+    const statement = source.prepare(sql);
+    if (statement.iterate) {
+      return statement.iterate() as Iterable<Record<string, unknown>>;
+    }
+    return statement.all() as Record<string, unknown>[];
+  }
+
+  private getColumnNames(db: DatabaseLike, table: string): Set<string> {
+    const rows = db.prepare(`PRAGMA table_info(${quoteIdentifier(table)})`).all() as { name?: unknown }[];
+    return new Set(rows.map((row) => row.name).filter((name): name is string => typeof name === 'string'));
+  }
+
+  private nullableString(value: unknown): string | null {
+    return typeof value === 'string' ? value : null;
+  }
+
+  private integerOr(value: unknown, fallback: number): number {
+    if (typeof value === 'number' && Number.isFinite(value)) return Math.trunc(value);
+    if (typeof value === 'bigint') return Number(value);
+    if (typeof value === 'string' && value.trim()) {
+      const parsed = Number.parseInt(value, 10);
+      if (Number.isFinite(parsed)) return parsed;
+    }
+    return fallback;
+  }
+
+  private rebuildFtsTables(db: DatabaseLike): void {
+    db.exec("INSERT INTO message_fts(message_fts) VALUES('rebuild')");
+    db.exec("INSERT INTO memory_fts(memory_fts) VALUES('rebuild')");
+  }
+
+  private corruptBackupBase(): string {
+    const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const nonce = Math.random().toString(16).slice(2, 8);
+    return `${this.dbPath}.corrupt-${stamp}-${process.pid}-${nonce}`;
+  }
+
+  private rebuildTempPath(): string {
+    const stamp = Date.now();
+    const nonce = Math.random().toString(16).slice(2, 8);
+    return `${this.dbPath}.rebuild-${process.pid}-${stamp}-${nonce}.tmp`;
+  }
+
+  private swapRebuiltDatabase(tempPath: string, backupBase: string): MovedDatabaseFile[] {
+    const moved = this.moveDatabaseFilesToBackup(backupBase);
+    try {
+      fs.renameSync(tempPath, this.dbPath);
+      return moved;
+    } catch (err) {
+      this.restoreMovedDatabaseFiles(moved);
+      this.removeDatabaseFileSet(tempPath);
+      throw err;
+    }
+  }
+
+  private moveDatabaseFilesToBackup(backupBase: string): MovedDatabaseFile[] {
+    this.assertStillRecoveryOwner();
+    const moved: MovedDatabaseFile[] = [];
+    for (const suffix of DATABASE_FILE_SUFFIXES) {
+      const original = `${this.dbPath}${suffix}`;
+      if (!fs.existsSync(original)) continue;
+
+      const backup = `${backupBase}${suffix}`;
+      fs.rmSync(backup, { force: true });
+      fs.renameSync(original, backup);
+      moved.push({ original, backup });
+    }
+    return moved;
+  }
+
+  /**
+   * Verifies this instance still holds the recovery lease immediately before
+   * a destructive rename that has no independent compare-and-swap of its
+   * own (unlike the Markdown mutation path, which re-checks a content
+   * fingerprint at publish time). If the lease was reclaimed as stale while
+   * this call was in flight, abort rather than race the new owner.
+   */
+  private assertStillRecoveryOwner(): void {
+    const active = this.activeRecoveryLease;
+    if (!active) return;
+    if (!active.coordinator.isCurrentOwner(active.key, active.token)) {
+      throw new Error(`SQLite recovery lease lost for ${this.displayDbPath}; another process took over`);
+    }
+  }
+
+  private restoreMovedDatabaseFiles(moved: MovedDatabaseFile[]): void {
+    for (const file of [...moved].reverse()) {
+      try {
+        if (!fs.existsSync(file.backup)) continue;
+        fs.rmSync(file.original, { force: true });
+        fs.renameSync(file.backup, file.original);
+      } catch {
+        // Best effort. The backup path remains available if restoration fails.
+      }
+    }
+  }
+
+  private removeDatabaseFileSet(basePath: string): void {
+    for (const suffix of DATABASE_FILE_SUFFIXES) {
+      fs.rmSync(`${basePath}${suffix}`, { force: true });
+    }
+  }
+
+  private safeClose(db: DatabaseLike): void {
+    try { db.close(); } catch { /* best effort */ }
+  }
+
+  private isLegacySchemaError(err: unknown): boolean {
+    if (!(err instanceof Error)) return false;
+    const msg = err.message.toLowerCase();
+    return msg.includes('no such column: category')
+      || msg.includes('memories(category)')
+      || msg.includes('no such column: project')
+      || msg.includes('sessions(project)')
+      || msg.includes('memories(project)');
+  }
+
+  private ensureLegacySchemaColumns(db: DatabaseLike): void {
+    this.ensureMemoriesColumns(db);
+    this.ensureSessionsColumns(db);
+  }
+
+  private ensureMemoriesColumns(db: DatabaseLike): void {
+    const tableExists = db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='memories'").get() as { name: string } | undefined;
+    if (!tableExists) return;
+
+    const names = this.getColumnNames(db, 'memories');
+
+    if (!names.has('project')) {
+      db.exec('ALTER TABLE memories ADD COLUMN project TEXT');
+    }
+    if (!names.has('category')) {
+      db.exec('ALTER TABLE memories ADD COLUMN category TEXT');
+    }
+    if (!names.has('failure_reason')) {
+      db.exec('ALTER TABLE memories ADD COLUMN failure_reason TEXT');
+    }
+    if (!names.has('tool_state')) {
+      db.exec('ALTER TABLE memories ADD COLUMN tool_state TEXT');
+    }
+    if (!names.has('corrected_to')) {
+      db.exec('ALTER TABLE memories ADD COLUMN corrected_to TEXT');
+    }
+  }
+
+  private ensureSessionsColumns(db: DatabaseLike): void {
+    const tableExists = db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='sessions'").get() as { name: string } | undefined;
+    if (!tableExists) return;
+
+    const names = this.getColumnNames(db, 'sessions');
+    if (!names.has('project')) {
+      db.exec('ALTER TABLE sessions ADD COLUMN project TEXT');
+    }
+
+    this.backfillSessionsProject(db);
+  }
+
+  private backfillSessionsProject(db: DatabaseLike): void {
+    const names = this.getColumnNames(db, 'sessions');
+    if (!names.has('project') || !names.has('cwd') || !names.has('id')) return;
+
+    const rows = db.prepare('SELECT id, cwd, project FROM sessions').all() as Array<{
+      id?: unknown;
+      cwd?: unknown;
+      project?: unknown;
+    }>;
+    const update = db.prepare('UPDATE sessions SET project = ? WHERE id = ?');
+
+    for (const row of rows) {
+      if (typeof row.id !== 'string') continue;
+      if (typeof row.project === 'string' && row.project.trim()) continue;
+
+      const project = typeof row.cwd === 'string' && row.cwd.trim()
+        ? (path.basename(row.cwd) || 'unknown')
+        : 'unknown';
+      update.run(project, row.id);
+    }
+  }
+  private ensureMemoryIndexes(db: DatabaseLike): void {
+    db.exec(`
+      CREATE INDEX IF NOT EXISTS idx_memories_project ON memories(project);
+      CREATE INDEX IF NOT EXISTS idx_memories_target ON memories(target);
+      CREATE INDEX IF NOT EXISTS idx_memories_category ON memories(category);
+    `);
+  }
+
+
+  private migrateLegacyMemoriesTargetConstraint(db: DatabaseLike): void {
+    const tableSqlRow = db.prepare("SELECT sql FROM sqlite_master WHERE type='table' AND name='memories'").get() as { sql?: string } | undefined;
+    const tableSql = tableSqlRow?.sql ?? '';
+    if (!tableSql) return;
+
+    // Legacy schema allowed only memory/user. New schema must allow failure too.
+    const hasLegacyTargetCheck = /target\s+TEXT\s+NOT\s+NULL\s+CHECK\s*\(\s*target\s+IN\s*\(\s*'memory'\s*,\s*'user'\s*\)\s*\)/i.test(tableSql);
+    if (!hasLegacyTargetCheck) return;
+
+    if (!db.transaction) {
+      db.exec('PRAGMA foreign_keys = OFF');
+      try {
+        db.exec('BEGIN IMMEDIATE');
+        db.exec(`
+          CREATE TABLE memories_new (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            project TEXT,
+            target TEXT NOT NULL CHECK (target IN ('memory', 'user', 'failure')),
+            category TEXT CHECK (category IN ('failure', 'correction', 'insight', 'preference', 'convention', 'tool-quirk')),
+            content TEXT NOT NULL,
+            failure_reason TEXT,
+            tool_state TEXT,
+            corrected_to TEXT,
+            created DATE NOT NULL,
+            last_referenced DATE NOT NULL
+          );
+        `);
+
+        db.exec(`
+          INSERT INTO memories_new (id, project, target, category, content, failure_reason, tool_state, corrected_to, created, last_referenced)
+          SELECT id, project, target, category, content, failure_reason, tool_state, corrected_to, created, last_referenced
+          FROM memories;
+        `);
+
+        db.exec('DROP TABLE memories');
+        db.exec('ALTER TABLE memories_new RENAME TO memories');
+        db.exec('COMMIT');
+      } catch (err) {
+        db.exec('ROLLBACK');
+        throw err;
+      } finally {
+        db.exec('PRAGMA foreign_keys = ON');
+      }
+      return;
+    }
+
+    const tx = db.transaction(() => {
+      db.exec(`
+        CREATE TABLE memories_new (
+          id INTEGER PRIMARY KEY AUTOINCREMENT,
+          project TEXT,
+          target TEXT NOT NULL CHECK (target IN ('memory', 'user', 'failure')),
+          category TEXT CHECK (category IN ('failure', 'correction', 'insight', 'preference', 'convention', 'tool-quirk')),
+          content TEXT NOT NULL,
+          failure_reason TEXT,
+          tool_state TEXT,
+          corrected_to TEXT,
+          created DATE NOT NULL,
+          last_referenced DATE NOT NULL
+        );
+      `);
+
+      db.exec(`
+          INSERT INTO memories_new (id, project, target, category, content, failure_reason, tool_state, corrected_to, created, last_referenced)
+          SELECT id, project, target, category, content, failure_reason, tool_state, corrected_to, created, last_referenced
+          FROM memories;
+        `);
+
+      db.exec('DROP TABLE memories');
+      db.exec('ALTER TABLE memories_new RENAME TO memories');
+    });
+
+    db.exec('PRAGMA foreign_keys = OFF');
+    try {
+      tx();
+    } finally {
+      db.exec('PRAGMA foreign_keys = ON');
+    }
+  }
+
+  /**
+   * Upgrade existing unicode61 FTS tables to the trigram tokenizer.
+   *
+   * `CREATE VIRTUAL TABLE IF NOT EXISTS` cannot change an existing FTS
+   * tokenizer, so this migration drops and recreates both external-content
+   * indexes, then repopulates them from their source tables. The metadata
+   * marker makes the migration versioned and idempotent.
+   */
+  private migrateFtsTokenizer(db: DatabaseLike): void {
+    const usesTrigram = (tableName: string): boolean => {
+      const row = db.prepare(
+        "SELECT sql FROM sqlite_master WHERE type = 'table' AND name = ?",
+      ).get(tableName) as { sql?: string } | undefined;
+      return typeof row?.sql === 'string'
+        && /\btokenize\s*=\s*['"]trigram['"]/i.test(row.sql);
+    };
+    const migrationComplete = (): boolean => {
+      const versionRow = db.prepare(
+        'SELECT value FROM extension_metadata WHERE key = ?',
+      ).get(FTS5_TOKENIZER_VERSION_KEY) as { value?: string } | undefined;
+      return versionRow?.value === FTS5_TOKENIZER_VERSION
+        && usesTrigram('message_fts')
+        && usesTrigram('memory_fts');
+    };
+    const isBusy = (error: unknown): boolean => {
+      const code = error && typeof error === 'object' && 'code' in error
+        ? String(error.code)
+        : '';
+      return code.startsWith('SQLITE_BUSY') || code.startsWith('SQLITE_LOCKED');
+    };
+
+    let lockAttempts = 0;
+    while (!migrationComplete()) {
+      try {
+        db.exec('BEGIN IMMEDIATE');
+      } catch (error) {
+        // Each attempt waits up to busy_timeout. Cap the total attempts so a
+        // permanently held writer cannot hang extension startup forever.
+        if (isBusy(error) && ++lockAttempts < FTS5_MIGRATION_MAX_LOCK_ATTEMPTS) continue;
+        if (isBusy(error)) {
+          throw new Error(
+            `Timed out waiting for the FTS tokenizer migration lock after ${lockAttempts} attempts. `
+              + "Close the other Pi process and retry.",
+            { cause: error },
+          );
+        }
+        throw error;
+      }
+
+      try {
+        // Another Pi process may have completed the migration while this
+        // connection waited for the write lock.
+        if (migrationComplete()) {
+          db.exec('COMMIT');
+          return;
+        }
+        db.exec(`
+          DROP TABLE IF EXISTS message_fts;
+          DROP TABLE IF EXISTS memory_fts;
+          ${FTS5_TRIGRAM_TABLES.message};
+          ${FTS5_TRIGRAM_TABLES.memory};
+          INSERT INTO message_fts(message_fts) VALUES ('rebuild');
+          INSERT INTO memory_fts(memory_fts) VALUES ('rebuild');
+        `);
+        db.prepare(`
+          INSERT INTO extension_metadata (key, value)
+          VALUES (?, ?)
+          ON CONFLICT(key) DO UPDATE SET value = excluded.value
+        `).run(FTS5_TOKENIZER_VERSION_KEY, FTS5_TOKENIZER_VERSION);
+        db.exec('COMMIT');
+        return;
+      } catch (error) {
+        try { db.exec('ROLLBACK'); } catch { /* preserve migration error */ }
+        throw error;
+      }
+    }
+  }
+
+  /**
+   * Close the database connection.
+   */
+  close(): void {
+    const db = this.db;
+    if (db) {
+      try {
+        measureLifecycleSync('database.checkpoint', () => db.exec('PRAGMA wal_checkpoint(TRUNCATE)'));
+      } catch { /* best effort */ }
+      try { db.close(); } catch { /* best effort — close may throw on a corrupt handle */ }
+      this.db = null;
+    }
+    this.pendingOpenIntegrityScan = null;
+  }
+
+  /**
+   * Get the database file path.
+   */
+  getPath(): string {
+    return this.displayDbPath;
+  }
+
+  /**
+   * Check if the database file exists.
+   */
+  exists(): boolean {
+    return fs.existsSync(this.dbPath);
+  }
+
+  /**
+   * Get stats about the database.
+   */
+  getStats(): { sessions: number; messages: number; memories: number } {
+    const db = this.getDb();
+    const sessions = db.prepare('SELECT COUNT(*) as count FROM sessions').get() as { count: number };
+    const messages = db.prepare('SELECT COUNT(*) as count FROM messages').get() as { count: number };
+    const memories = db.prepare('SELECT COUNT(*) as count FROM memories').get() as { count: number };
+    return {
+      sessions: sessions.count,
+      messages: messages.count,
+      memories: memories.count,
+    };
+  }
+}