gnosys 5.11.4 → 5.12.2

package/dist/lib/db.js

@@ -8,7 +8,6 @@
  * + projects table (v3.0) for project identity registry.
  */
 // Dynamic import — gracefully handles missing native module
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
 let Database = null;
 try {
     Database = (await import("better-sqlite3")).default;
@@ -24,7 +23,7 @@ import { readMachineConfig } from "./machineConfig.js";
 import { logError } from "./log.js";
 import { ulid } from "ulidx";
 // ─── Schema ─────────────────────────────────────────────────────────────
-const SCHEMA_VERSION = 4;
+const SCHEMA_VERSION = 5;
 const SCHEMA_SQL = `
 CREATE TABLE IF NOT EXISTS memories (
   id                  TEXT PRIMARY KEY,
@@ -51,6 +50,9 @@ CREATE TABLE IF NOT EXISTS memories (
   source_file         TEXT,
   source_page         TEXT,
   source_timerange    TEXT,
+  attachment_data     BLOB,
+  attachment_mime     TEXT,
+  attachment_name     TEXT,
   project_id          TEXT,
   scope               TEXT DEFAULT 'project' CHECK(scope IN ('project','user','global'))
 );
@@ -171,6 +173,51 @@ CREATE TABLE IF NOT EXISTS sync_conflicts (
 );
 
 CREATE INDEX IF NOT EXISTS idx_sync_conflicts_status ON sync_conflicts(status);
+
+-- v13 multi-machine sync (master DB)
+
+CREATE TABLE IF NOT EXISTS sync_staging_ledger (
+  staging_key       TEXT PRIMARY KEY,
+  machine_id        TEXT NOT NULL,
+  memory_ulid       TEXT,
+  first_seen_at     TEXT NOT NULL,
+  ingest_epoch      INTEGER,
+  status            TEXT NOT NULL DEFAULT 'pending'
+);
+
+CREATE INDEX IF NOT EXISTS idx_sync_staging_status ON sync_staging_ledger(status);
+CREATE INDEX IF NOT EXISTS idx_sync_staging_first_seen ON sync_staging_ledger(first_seen_at);
+
+CREATE TABLE IF NOT EXISTS sync_processed_ulids (
+  ulid              TEXT PRIMARY KEY,
+  ingested_at       TEXT NOT NULL,
+  ingest_epoch      INTEGER
+);
+
+CREATE TABLE IF NOT EXISTS sync_pending_adds (
+  id                TEXT PRIMARY KEY,
+  title             TEXT NOT NULL,
+  category          TEXT NOT NULL,
+  content           TEXT NOT NULL,
+  tags              TEXT DEFAULT '',
+  project_id        TEXT,
+  scope             TEXT DEFAULT 'project',
+  created           TEXT NOT NULL,
+  cleared_at        TEXT
+);
+
+CREATE INDEX IF NOT EXISTS idx_sync_pending_adds_cleared ON sync_pending_adds(cleared_at);
+
+CREATE TABLE IF NOT EXISTS sync_snapshot_manifest (
+  singleton_id      INTEGER PRIMARY KEY CHECK (singleton_id = 1),
+  epoch             INTEGER NOT NULL,
+  seq               INTEGER NOT NULL,
+  snapshot_path     TEXT NOT NULL,
+  published_at      TEXT NOT NULL,
+  checksum          TEXT,
+  size_bytes        INTEGER,
+  heartbeat_at      TEXT
+);
 `;
 // FTS5 sync triggers — created separately (can't use IF NOT EXISTS on triggers)
 const FTS_TRIGGERS_SQL = `
@@ -198,12 +245,27 @@ const MEMORY_COLUMNS = new Set([
     "status", "tier", "supersedes", "superseded_by", "last_reinforced",
     "created", "modified", "embedding", "source_path",
     "source_file", "source_page", "source_timerange",
+    "attachment_data", "attachment_mime", "attachment_name",
     "project_id", "scope",
 ]);
 const PROJECT_COLUMNS = new Set([
     "name", "working_directory", "root_id", "rel_path", "user",
     "agent_rules_target", "obsidian_vault", "created", "modified",
 ]);
+/**
+ * v5.12.x perf: full DbMemory shape with the two BLOB columns projected as
+ * NULL. List-style reads (recall, federation, list) never consume embedding
+ * or attachment bytes. Measured win on embedding-only rows is modest (~4%
+ * plus avoided Buffer churn), but attachments are the real reason: a single
+ * ~10MB gnosys_attach blob would otherwise be hydrated on EVERY list call.
+ * Blob consumers use getAllEmbeddings/getEmbedding/getMemoryAttachment, and
+ * getAllMemories/getMemoriesByProject still return full rows (remote sync
+ * and project export push them verbatim).
+ */
+const LEAN_MEMORY_PROJECTION = [
+    "id", ...[...MEMORY_COLUMNS].filter((c) => c !== "embedding" && c !== "attachment_data"),
+    "NULL AS embedding", "NULL AS attachment_data",
+].join(", ");
 // ─── FNV-1a hash (same as embeddings.ts) ────────────────────────────────
 function fnv1a(str) {
     let hash = 0x811c9dc5;
@@ -215,8 +277,10 @@ function fnv1a(str) {
 }
 // ─── GnosysDB Class ─────────────────────────────────────────────────────
 export class GnosysDB {
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     db = null;
+    /** v5.12.x perf: prepared-statement cache, keyed by SQL. Invalidated on
+     *  reopen()/close() — statements are bound to their connection handle. */
+    stmtCache = new Map();
     storePath;
     available = false;
     dbFilePath;
@@ -336,7 +400,8 @@ export class GnosysDB {
             try {
                 fs.mkdirSync(storePath, { recursive: true, mode: 0o700 });
                 this.db = new Database(this.dbFilePath);
-                enableWAL(this.db);
+                // Longer busy timeout for network shares (10s)
+                enableWAL(this.db, 10000);
                 try {
                     fs.chmodSync(storePath, 0o700);
                     fs.chmodSync(this.dbFilePath, 0o600);
@@ -351,13 +416,11 @@ export class GnosysDB {
                     // best-effort (Windows / network FS)
                 }
                 this.db.pragma("foreign_keys = ON");
-                // Longer busy timeout for network shares (10s)
-                this.db.pragma("busy_timeout = 10000");
                 this.applySchema();
                 this.available = true;
                 return; // Success
             }
-            catch (err) {
+            catch (_err) {
                 this.db = null;
                 if (attempt < maxRetries) {
                     // Synchronous delay for constructor (network share retry)
@@ -426,6 +489,7 @@ export class GnosysDB {
      * file handles after a WAL checkpoint or remount.
      */
     reopen() {
+        this.stmtCache.clear();
         try {
             this.db?.close();
         }
@@ -438,9 +502,19 @@ export class GnosysDB {
             return;
         try {
             this.db = new Database(this.dbFilePath);
-            enableWAL(this.db);
+            // Longer busy timeout for network shares (10s)
+            enableWAL(this.db, 10000);
             this.db.pragma("foreign_keys = ON");
-            this.db.pragma("busy_timeout = 10000");
+            // v5.12.1: heal FTS triggers on recovery. updateMemory/deleteMemory may
+            // drop a trigger in their inconsistency fallback; recreating here
+            // (idempotent CREATE TRIGGER IF NOT EXISTS) means recovery restores
+            // them instead of waiting for the next process start.
+            try {
+                this.db.exec(FTS_TRIGGERS_SQL);
+            }
+            catch {
+                // non-fatal — applySchema() heals at next open
+            }
             this.available = true;
         }
         catch {
@@ -463,15 +537,28 @@ export class GnosysDB {
      * Read methods are also wrapped because reads against stale pages can
      * surface the same error.
      */
+    /**
+     * Prepare-with-cache for fixed-SQL hot paths. Dynamic SQL (e.g. the
+     * field-built UPDATE in updateMemory) must keep using db.prepare directly
+     * so the cache stays bounded. Cache is invalidated on reopen()/close().
+     */
+    prep(sql) {
+        let stmt = this.stmtCache.get(sql);
+        if (!stmt) {
+            stmt = this.db.prepare(sql);
+            this.stmtCache.set(sql, stmt);
+        }
+        return stmt;
+    }
     withRecovery(fn) {
         try {
             return fn();
         }
         catch (err) {
-            const errAny = err;
-            const isCorrupt = errAny?.code === "SQLITE_CORRUPT" ||
-                /database disk image is malformed/i.test(errAny?.message ?? "");
-            if (!isCorrupt)
+            // v5.12.1: use the shared corruption detector — it also matches
+            // SQLITE_NOTADB ("file is not a database"), which surfaces on network
+            // shares when a sync layer swaps the file under a live handle.
+            if (!GnosysDB.isCorruptionError(err))
                 throw err;
             // One-shot recovery: reopen and retry. If the reopen itself fails or
             // the retry surfaces the same error, that's a real corruption case —
@@ -641,6 +728,78 @@ export class GnosysDB {
                 // Table may already exist
             }
         }
+        if (fromVersion < 5) {
+            // v4 → v5 (v5.12): inline binary attachments carried in the memory row.
+            // Additive columns only — existing rows get NULLs. These ride the same
+            // row-copy sync path as `embedding`, so attachments travel machine to
+            // machine for free.
+            try {
+                this.db.exec("ALTER TABLE memories ADD COLUMN attachment_data BLOB");
+            }
+            catch {
+                // Column already exists — fine
+            }
+            try {
+                this.db.exec("ALTER TABLE memories ADD COLUMN attachment_mime TEXT");
+            }
+            catch {
+                // Column already exists — fine
+            }
+            try {
+                this.db.exec("ALTER TABLE memories ADD COLUMN attachment_name TEXT");
+            }
+            catch {
+                // Column already exists — fine
+            }
+            // Sync staging / multi-machine ledger tables (from network-mcp work on feat).
+            try {
+                this.db.exec(`
+        CREATE TABLE IF NOT EXISTS sync_staging_ledger (
+          staging_key       TEXT PRIMARY KEY,
+          machine_id        TEXT NOT NULL,
+          memory_ulid       TEXT,
+          first_seen_at     TEXT NOT NULL,
+          ingest_epoch      INTEGER,
+          status            TEXT NOT NULL DEFAULT 'pending'
+        );
+        CREATE INDEX IF NOT EXISTS idx_sync_staging_status ON sync_staging_ledger(status);
+        CREATE INDEX IF NOT EXISTS idx_sync_staging_first_seen ON sync_staging_ledger(first_seen_at);
+
+        CREATE TABLE IF NOT EXISTS sync_processed_ulids (
+          ulid              TEXT PRIMARY KEY,
+          ingested_at       TEXT NOT NULL,
+          ingest_epoch      INTEGER
+        );
+
+        CREATE TABLE IF NOT EXISTS sync_pending_adds (
+          id                TEXT PRIMARY KEY,
+          title             TEXT NOT NULL,
+          category          TEXT NOT NULL,
+          content           TEXT NOT NULL,
+          tags              TEXT DEFAULT '',
+          project_id        TEXT,
+          scope             TEXT DEFAULT 'project',
+          created           TEXT NOT NULL,
+          cleared_at        TEXT
+        );
+        CREATE INDEX IF NOT EXISTS idx_sync_pending_adds_cleared ON sync_pending_adds(cleared_at);
+
+        CREATE TABLE IF NOT EXISTS sync_snapshot_manifest (
+          singleton_id      INTEGER PRIMARY KEY CHECK (singleton_id = 1),
+          epoch             INTEGER NOT NULL,
+          seq               INTEGER NOT NULL,
+          snapshot_path     TEXT NOT NULL,
+          published_at      TEXT NOT NULL,
+          checksum          TEXT,
+          size_bytes        INTEGER,
+          heartbeat_at      TEXT
+        );
+      `);
+            }
+            catch {
+                // Sync tables/indexes may already exist — fine
+            }
+        }
         this.db.pragma(`user_version = ${SCHEMA_VERSION}`);
     }
     isAvailable() {
@@ -655,23 +814,26 @@ export class GnosysDB {
     // ─── Memory CRUD ────────────────────────────────────────────────────
     insertMemory(mem) {
         return this.withRecovery(() => {
-            const stmt = this.db.prepare(`
+            const stmt = this.prep(`
         INSERT OR REPLACE INTO memories
           (id, title, category, content, summary, tags, relevance, author, authority,
            confidence, reinforcement_count, content_hash, status, tier, supersedes,
            superseded_by, last_reinforced, created, modified, embedding, source_path,
            source_file, source_page, source_timerange,
+           attachment_data, attachment_mime, attachment_name,
            project_id, scope)
-        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
       `);
-            stmt.run(mem.id, mem.title, mem.category, mem.content, mem.summary || null, mem.tags, mem.relevance, mem.author, mem.authority, mem.confidence, mem.reinforcement_count, mem.content_hash, mem.status, mem.tier, mem.supersedes || null, mem.superseded_by || null, mem.last_reinforced || null, mem.created, mem.modified, mem.embedding || null, mem.source_path || null, mem.source_file || null, mem.source_page || null, mem.source_timerange || null, mem.project_id || null, mem.scope || "project");
+            stmt.run(mem.id, mem.title, mem.category, mem.content, mem.summary || null, mem.tags, mem.relevance, mem.author, mem.authority, mem.confidence, mem.reinforcement_count, mem.content_hash, mem.status, mem.tier, mem.supersedes || null, mem.superseded_by || null, mem.last_reinforced || null, mem.created, mem.modified, mem.embedding || null, mem.source_path || null, mem.source_file || null, mem.source_page || null, mem.source_timerange || null, mem.attachment_data || null, mem.attachment_mime || null, mem.attachment_name || null, mem.project_id || null, mem.scope || "project");
         });
     }
     getMemory(id) {
-        return this.withRecovery(() => this.db.prepare("SELECT * FROM memories WHERE id = ?").get(id) || null);
+        return this.withRecovery(() => this.prep("SELECT * FROM memories WHERE id = ?").get(id) || null);
     }
     getActiveMemories() {
-        return this.withRecovery(() => this.db.prepare("SELECT * FROM memories WHERE tier = 'active' AND status = 'active'").all());
+        // v5.12.x perf: project NULL for the two BLOB columns — see
+        // LEAN_MEMORY_PROJECTION for the rationale and measured numbers.
+        return this.withRecovery(() => this.prep(`SELECT ${LEAN_MEMORY_PROJECTION} FROM memories WHERE tier = 'active' AND status = 'active'`).all());
     }
     getAllMemories() {
         return this.withRecovery(() => this.db.prepare("SELECT * FROM memories").all());
@@ -701,20 +863,20 @@ export class GnosysDB {
         this.db.pragma(`busy_timeout = ${Math.max(0, Math.floor(ms))}`);
     }
     getMemoriesByCategory(category) {
-        return this.db.prepare("SELECT * FROM memories WHERE category = ? AND tier = 'active'").all(category);
+        return this.withRecovery(() => this.prep("SELECT * FROM memories WHERE category = ? AND tier = 'active'").all(category));
     }
     getRelationshipsForMemoryIds(ids) {
         if (ids.length === 0)
             return [];
         const placeholders = ids.map(() => "?").join(",");
-        return this.db
+        return this.withRecovery(() => this.db
             .prepare(`SELECT * FROM relationships WHERE source_id IN (${placeholders}) OR target_id IN (${placeholders})`)
-            .all(...ids, ...ids);
+            .all(...ids, ...ids));
     }
     getAuditEntriesByProject(projectId) {
-        return this.db
+        return this.withRecovery(() => this.db
             .prepare("SELECT * FROM audit_log WHERE memory_id IN (SELECT id FROM memories WHERE project_id = ?) ORDER BY id")
-            .all(projectId);
+            .all(projectId));
     }
     updateMemory(id, updates) {
         const fields = [];
@@ -731,17 +893,18 @@ export class GnosysDB {
             return;
         values.push(id);
         const sql = `UPDATE memories SET ${fields.join(", ")} WHERE id = ?`;
-        try {
-            this.db.prepare(sql).run(...values);
-        }
-        catch {
-            // FTS5 update trigger may fail if INSERT OR REPLACE left FTS inconsistent.
-            // Workaround: drop the trigger, update manually, rebuild FTS entry.
-            this.db.exec("DROP TRIGGER IF EXISTS memories_fts_au");
-            this.db.prepare(sql).run(...values);
-            // Recreate trigger
+        return this.withRecovery(() => {
             try {
-                this.db.exec(`
+                this.db.prepare(sql).run(...values);
+            }
+            catch {
+                // FTS5 update trigger may fail if INSERT OR REPLACE left FTS inconsistent.
+                // Workaround: drop the trigger, update manually, rebuild FTS entry.
+                this.db.exec("DROP TRIGGER IF EXISTS memories_fts_au");
+                this.db.prepare(sql).run(...values);
+                // Recreate trigger
+                try {
+                    this.db.exec(`
           CREATE TRIGGER IF NOT EXISTS memories_fts_au AFTER UPDATE ON memories BEGIN
             INSERT INTO memories_fts(memories_fts, id, title, category, tags, relevance, content, summary)
             VALUES ('delete', old.id, old.title, old.category, old.tags, old.relevance, old.content, old.summary);
@@ -749,66 +912,73 @@ export class GnosysDB {
             VALUES (new.id, new.title, new.category, new.tags, new.relevance, new.content, new.summary);
           END;
         `);
+                }
+                catch {
+                    // Trigger recreation failed — not critical
+                }
             }
-            catch {
-                // Trigger recreation failed — not critical
-            }
-        }
-        // Manually sync FTS: remove old entry, insert updated entry (reliable for standalone FTS5)
-        try {
-            this.db.prepare("DELETE FROM memories_fts WHERE id = ?").run(id);
-        }
-        catch {
-            // Old FTS entry may not exist — that's OK
-        }
-        const newMem = this.db.prepare("SELECT * FROM memories WHERE id = ?").get(id);
-        if (newMem) {
+            // Manually sync FTS: remove old entry, insert updated entry (reliable for standalone FTS5)
             try {
-                this.db.prepare("INSERT INTO memories_fts(id, title, category, tags, relevance, content, summary) VALUES (?, ?, ?, ?, ?, ?, ?)").run(newMem.id, newMem.title, newMem.category, newMem.tags, newMem.relevance, newMem.content, newMem.summary);
+                this.db.prepare("DELETE FROM memories_fts WHERE id = ?").run(id);
             }
             catch {
-                // FTS insert may fail — not critical
+                // Old FTS entry may not exist — that's OK
             }
-        }
+            const newMem = this.db.prepare("SELECT * FROM memories WHERE id = ?").get(id);
+            if (newMem) {
+                try {
+                    this.db.prepare("INSERT INTO memories_fts(id, title, category, tags, relevance, content, summary) VALUES (?, ?, ?, ?, ?, ?, ?)").run(newMem.id, newMem.title, newMem.category, newMem.tags, newMem.relevance, newMem.content, newMem.summary);
+                }
+                catch {
+                    // FTS insert may fail — not critical
+                }
+            }
+        });
     }
     deleteMemory(id) {
-        // FTS5 delete trigger may fail if INSERT OR REPLACE left FTS inconsistent.
-        try {
-            this.db.prepare("DELETE FROM memories WHERE id = ?").run(id);
-        }
-        catch {
-            // FTS trigger failed — drop trigger, delete without it
-            this.db.exec("DROP TRIGGER IF EXISTS memories_fts_ad");
-            this.db.prepare("DELETE FROM memories WHERE id = ?").run(id);
-            // Recreate trigger
+        return this.withRecovery(() => {
+            // FTS5 delete trigger may fail if INSERT OR REPLACE left FTS inconsistent.
             try {
-                this.db.exec(`
+                this.db.prepare("DELETE FROM memories WHERE id = ?").run(id);
+            }
+            catch {
+                // FTS trigger failed — drop trigger, delete without it
+                this.db.exec("DROP TRIGGER IF EXISTS memories_fts_ad");
+                this.db.prepare("DELETE FROM memories WHERE id = ?").run(id);
+                // Recreate trigger
+                try {
+                    this.db.exec(`
           CREATE TRIGGER IF NOT EXISTS memories_fts_ad AFTER DELETE ON memories BEGIN
             INSERT INTO memories_fts(memories_fts, id, title, category, tags, relevance, content, summary)
             VALUES ('delete', old.id, old.title, old.category, old.tags, old.relevance, old.content, old.summary);
           END;
         `);
+                }
+                catch {
+                    // Trigger recreation failed — not critical
+                }
+            }
+            // Ensure FTS entry is also removed (direct DELETE is reliable for standalone FTS5)
+            try {
+                this.db.prepare("DELETE FROM memories_fts WHERE id = ?").run(id);
             }
             catch {
-                // Trigger recreation failed — not critical
+                // FTS entry may not exist — that's OK
             }
-        }
-        // Ensure FTS entry is also removed (direct DELETE is reliable for standalone FTS5)
-        try {
-            this.db.prepare("DELETE FROM memories_fts WHERE id = ?").run(id);
-        }
-        catch {
-            // FTS entry may not exist — that's OK
-        }
+        });
     }
     getMemoryCount() {
-        const active = this.db.prepare("SELECT COUNT(*) as cnt FROM memories WHERE tier = 'active'").get().cnt;
-        const archived = this.db.prepare("SELECT COUNT(*) as cnt FROM memories WHERE tier = 'archive'").get().cnt;
-        return { active, archived, total: active + archived };
+        return this.withRecovery(() => {
+            const active = this.db.prepare("SELECT COUNT(*) as cnt FROM memories WHERE tier = 'active'").get().cnt;
+            const archived = this.db.prepare("SELECT COUNT(*) as cnt FROM memories WHERE tier = 'archive'").get().cnt;
+            return { active, archived, total: active + archived };
+        });
     }
     getCategories() {
-        const rows = this.db.prepare("SELECT DISTINCT category FROM memories WHERE tier = 'active' ORDER BY category").all();
-        return rows.map((r) => r.category);
+        return this.withRecovery(() => {
+            const rows = this.db.prepare("SELECT DISTINCT category FROM memories WHERE tier = 'active' ORDER BY category").all();
+            return rows.map((r) => r.category);
+        });
     }
     // ─── Scoped Queries (v3.0) ──────────────────────────────────────────
     /**
@@ -818,13 +988,13 @@ export class GnosysDB {
         const sql = includeArchived
             ? "SELECT * FROM memories WHERE project_id = ?"
             : "SELECT * FROM memories WHERE project_id = ? AND tier = 'active' AND status = 'active'";
-        return this.db.prepare(sql).all(projectId);
+        return this.withRecovery(() => this.prep(sql).all(projectId));
     }
     /**
      * Get memories by scope (project, user, global).
      */
     getMemoriesByScope(scope) {
-        return this.db.prepare("SELECT * FROM memories WHERE scope = ? AND tier = 'active' AND status = 'active'").all(scope);
+        return this.withRecovery(() => this.prep("SELECT * FROM memories WHERE scope = ? AND tier = 'active' AND status = 'active'").all(scope));
     }
     // ─── Project Identity (v3.0) ──────────────────────────────────────
     insertProject(project) {
@@ -888,10 +1058,14 @@ export class GnosysDB {
         if (fields.length === 0)
             return;
         values.push(id);
-        this.db.prepare(`UPDATE projects SET ${fields.join(", ")} WHERE id = ?`).run(...values);
+        this.withRecovery(() => {
+            this.db.prepare(`UPDATE projects SET ${fields.join(", ")} WHERE id = ?`).run(...values);
+        });
     }
     deleteProject(id) {
-        this.db.prepare("DELETE FROM projects WHERE id = ?").run(id);
+        this.withRecovery(() => {
+            this.db.prepare("DELETE FROM projects WHERE id = ?").run(id);
+        });
     }
     /**
      * Generate the next sequential ID for a category.
@@ -908,7 +1082,6 @@ export class GnosysDB {
      * The `projectId` parameter is accepted for API compatibility but no longer
      * used for ID generation (ULIDs don't need project scoping for uniqueness).
      */
-    // eslint-disable-next-line @typescript-eslint/no-unused-vars
     getNextId(category, projectId) {
         const prefix = category.substring(0, 4);
         return `${prefix}-${ulid()}`;
@@ -919,8 +1092,9 @@ export class GnosysDB {
         if (!safeQuery)
             return [];
         // v5.8.0 (#7): join memories so callers can render project-prefixed IDs.
-        try {
-            return this.db.prepare(`
+        return this.withRecovery(() => {
+            try {
+                return this.prep(`
         SELECT m.id AS id, m.title AS title,
                snippet(memories_fts, 5, '>>>', '<<<', '...', 40) as snippet,
                fts.rank AS rank,
@@ -931,16 +1105,17 @@ export class GnosysDB {
         ORDER BY fts.rank
         LIMIT ?
       `).all(safeQuery, limit);
-        }
-        catch {
-            // FTS5 syntax error — fallback to LIKE
-            const pattern = `%${safeQuery}%`;
-            return this.db.prepare(`
+            }
+            catch {
+                // FTS5 syntax error — fallback to LIKE
+                const pattern = `%${safeQuery}%`;
+                return this.prep(`
         SELECT id, title, substr(content, 1, 200) as snippet, 0 as rank, project_id
         FROM memories WHERE content LIKE ? OR title LIKE ? OR tags LIKE ?
         LIMIT ?
       `).all(pattern, pattern, pattern, limit);
-        }
+            }
+        });
     }
     discoverFts(query, limit = 20) {
         const safeQuery = query.replace(/['"]/g, "").trim();
@@ -955,51 +1130,61 @@ export class GnosysDB {
       ORDER BY fts.rank
       LIMIT ?
     `;
-        try {
-            const colQuery = `{relevance title tags} : ${safeQuery}`;
-            const results = this.db.prepare(select).all(colQuery, limit);
-            if (results.length > 0)
-                return results;
-            return this.db.prepare(select).all(safeQuery, limit);
-        }
-        catch {
+        return this.withRecovery(() => {
             try {
-                return this.db.prepare(select).all(safeQuery, limit);
+                const colQuery = `{relevance title tags} : ${safeQuery}`;
+                const results = this.prep(select).all(colQuery, limit);
+                if (results.length > 0)
+                    return results;
+                return this.prep(select).all(safeQuery, limit);
             }
             catch {
-                return [];
+                try {
+                    return this.prep(select).all(safeQuery, limit);
+                }
+                catch (err) {
+                    // Let corruption escape to withRecovery (reopen + retry); plain FTS
+                    // syntax failures still degrade gracefully to "no results".
+                    if (GnosysDB.isCorruptionError(err))
+                        throw err;
+                    return [];
+                }
             }
-        }
+        });
     }
     // ─── Relationships ──────────────────────────────────────────────────
     insertRelationship(rel) {
-        this.db.prepare(`
-      INSERT OR IGNORE INTO relationships (source_id, target_id, rel_type, label, confidence, created)
-      VALUES (?, ?, ?, ?, ?, ?)
-    `).run(rel.source_id, rel.target_id, rel.rel_type, rel.label, rel.confidence, rel.created);
+        this.withRecovery(() => {
+            this.db.prepare(`
+        INSERT OR IGNORE INTO relationships (source_id, target_id, rel_type, label, confidence, created)
+        VALUES (?, ?, ?, ?, ?, ?)
+      `).run(rel.source_id, rel.target_id, rel.rel_type, rel.label, rel.confidence, rel.created);
+        });
     }
     getRelationshipsFrom(id) {
-        return this.db.prepare("SELECT * FROM relationships WHERE source_id = ?").all(id);
+        return this.withRecovery(() => this.db.prepare("SELECT * FROM relationships WHERE source_id = ?").all(id));
     }
     getRelationshipsTo(id) {
-        return this.db.prepare("SELECT * FROM relationships WHERE target_id = ?").all(id);
+        return this.withRecovery(() => this.db.prepare("SELECT * FROM relationships WHERE target_id = ?").all(id));
     }
     // ─── Summaries ──────────────────────────────────────────────────────
     upsertSummary(summary) {
-        this.db.prepare(`
-      INSERT INTO summaries (id, scope, scope_key, content, source_ids, created, modified)
-      VALUES (?, ?, ?, ?, ?, ?, ?)
-      ON CONFLICT(scope, scope_key) DO UPDATE SET
-        content = excluded.content,
-        source_ids = excluded.source_ids,
-        modified = excluded.modified
-    `).run(summary.id, summary.scope, summary.scope_key, summary.content, summary.source_ids, summary.created, summary.modified);
+        this.withRecovery(() => {
+            this.db.prepare(`
+        INSERT INTO summaries (id, scope, scope_key, content, source_ids, created, modified)
+        VALUES (?, ?, ?, ?, ?, ?, ?)
+        ON CONFLICT(scope, scope_key) DO UPDATE SET
+          content = excluded.content,
+          source_ids = excluded.source_ids,
+          modified = excluded.modified
+      `).run(summary.id, summary.scope, summary.scope_key, summary.content, summary.source_ids, summary.created, summary.modified);
+        });
     }
     getSummary(scope, scopeKey) {
-        return this.db.prepare("SELECT * FROM summaries WHERE scope = ? AND scope_key = ?").get(scope, scopeKey) || null;
+        return this.withRecovery(() => this.db.prepare("SELECT * FROM summaries WHERE scope = ? AND scope_key = ?").get(scope, scopeKey) || null);
     }
     getAllSummaries() {
-        return this.db.prepare("SELECT * FROM summaries").all();
+        return this.withRecovery(() => this.db.prepare("SELECT * FROM summaries").all());
     }
     // ─── Audit ──────────────────────────────────────────────────────────
     logAudit(entry) {
@@ -1051,21 +1236,26 @@ export class GnosysDB {
     }
     // ─── Embeddings ─────────────────────────────────────────────────────
     updateEmbedding(id, embedding) {
-        this.db.prepare("UPDATE memories SET embedding = ? WHERE id = ?").run(embedding, id);
+        this.withRecovery(() => {
+            this.db.prepare("UPDATE memories SET embedding = ? WHERE id = ?").run(embedding, id);
+        });
     }
     getEmbedding(id) {
-        const row = this.db.prepare("SELECT embedding FROM memories WHERE id = ?").get(id);
-        return row?.embedding || null;
+        return this.withRecovery(() => {
+            const row = this.db.prepare("SELECT embedding FROM memories WHERE id = ?").get(id);
+            return row?.embedding || null;
+        });
     }
     getAllEmbeddings() {
-        return this.db.prepare("SELECT id, embedding FROM memories WHERE embedding IS NOT NULL").all();
+        return this.withRecovery(() => this.db.prepare("SELECT id, embedding FROM memories WHERE embedding IS NOT NULL").all());
     }
     getEmbeddingCount() {
-        const row = this.db.prepare("SELECT COUNT(*) as cnt FROM memories WHERE embedding IS NOT NULL").get();
-        return row.cnt;
+        return this.withRecovery(() => {
+            const row = this.db.prepare("SELECT COUNT(*) as cnt FROM memories WHERE embedding IS NOT NULL").get();
+            return row.cnt;
+        });
     }
     // ─── Transactions ───────────────────────────────────────────────────
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     transaction(fn) {
         return this.db.transaction(fn)();
     }
@@ -1233,8 +1423,83 @@ export class GnosysDB {
     resolveConflict(memoryId) {
         this.db.prepare("UPDATE sync_conflicts SET status = 'resolved' WHERE memory_id = ?").run(memoryId);
     }
+    // ─── v13 multi-machine sync (master + client local overlay) ───────────
+    recordStagingLedgerEntry(entry) {
+        if (entry.status === undefined) {
+            this.db.prepare(`
+        INSERT INTO sync_staging_ledger (staging_key, machine_id, memory_ulid, first_seen_at, ingest_epoch, status)
+        VALUES (?, ?, ?, ?, ?, 'pending')
+        ON CONFLICT(staging_key) DO UPDATE SET
+          memory_ulid = COALESCE(excluded.memory_ulid, sync_staging_ledger.memory_ulid),
+          ingest_epoch = COALESCE(excluded.ingest_epoch, sync_staging_ledger.ingest_epoch)
+      `).run(entry.stagingKey, entry.machineId, entry.memoryUlid ?? null, entry.firstSeenAt, entry.ingestEpoch ?? null);
+            return;
+        }
+        this.db.prepare(`
+      INSERT INTO sync_staging_ledger (staging_key, machine_id, memory_ulid, first_seen_at, ingest_epoch, status)
+      VALUES (?, ?, ?, ?, ?, ?)
+      ON CONFLICT(staging_key) DO UPDATE SET
+        memory_ulid = COALESCE(excluded.memory_ulid, sync_staging_ledger.memory_ulid),
+        ingest_epoch = COALESCE(excluded.ingest_epoch, sync_staging_ledger.ingest_epoch),
+        status = excluded.status
+    `).run(entry.stagingKey, entry.machineId, entry.memoryUlid ?? null, entry.firstSeenAt, entry.ingestEpoch ?? null, entry.status);
+    }
+    isUlidProcessed(ulid) {
+        const row = this.db.prepare("SELECT 1 FROM sync_processed_ulids WHERE ulid = ?").get(ulid);
+        return Boolean(row);
+    }
+    markUlidProcessed(ulid, ingestEpoch) {
+        this.db.prepare(`
+      INSERT OR IGNORE INTO sync_processed_ulids (ulid, ingested_at, ingest_epoch)
+      VALUES (?, ?, ?)
+    `).run(ulid, new Date().toISOString(), ingestEpoch ?? null);
+    }
+    countPendingStagingLedger() {
+        const row = this.db.prepare("SELECT COUNT(*) as cnt FROM sync_staging_ledger WHERE status = 'pending'").get();
+        return row.cnt;
+    }
+    getStagingLedgerFirstSeenAt(stagingKey) {
+        const row = this.db.prepare("SELECT first_seen_at FROM sync_staging_ledger WHERE staging_key = ?").get(stagingKey);
+        return row?.first_seen_at ?? null;
+    }
+    insertPendingAdd(row) {
+        this.db.prepare(`
+      INSERT OR REPLACE INTO sync_pending_adds
+        (id, title, category, content, tags, project_id, scope, created, cleared_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, NULL)
+    `).run(row.id, row.title, row.category, row.content, row.tags ?? "", row.project_id ?? null, row.scope ?? "project", row.created);
+    }
+    listActivePendingAdds() {
+        return this.db.prepare("SELECT id, title, category, content, tags, project_id, scope, created FROM sync_pending_adds WHERE cleared_at IS NULL ORDER BY created ASC").all();
+    }
+    clearPendingAdd(id) {
+        this.db.prepare("UPDATE sync_pending_adds SET cleared_at = ? WHERE id = ? AND cleared_at IS NULL").run(new Date().toISOString(), id);
+    }
+    getSnapshotManifest() {
+        const row = this.db.prepare("SELECT epoch, seq, snapshot_path, published_at, checksum, size_bytes, heartbeat_at FROM sync_snapshot_manifest WHERE singleton_id = 1").get();
+        return row ?? null;
+    }
+    publishSnapshotManifest(manifest) {
+        this.db.prepare(`
+      INSERT INTO sync_snapshot_manifest
+        (singleton_id, epoch, seq, snapshot_path, published_at, checksum, size_bytes, heartbeat_at)
+      VALUES (1, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(singleton_id) DO UPDATE SET
+        epoch = excluded.epoch,
+        seq = excluded.seq,
+        snapshot_path = excluded.snapshot_path,
+        published_at = excluded.published_at,
+        checksum = excluded.checksum,
+        size_bytes = excluded.size_bytes,
+        heartbeat_at = excluded.heartbeat_at
+    `).run(manifest.epoch, manifest.seq, manifest.snapshotPath, manifest.publishedAt, manifest.checksum ?? null, manifest.sizeBytes ?? null, manifest.heartbeatAt ?? null);
+    }
+    touchSnapshotHeartbeat(at) {
+        this.db.prepare("UPDATE sync_snapshot_manifest SET heartbeat_at = ? WHERE singleton_id = 1").run(at);
+    }
     // ─── Lifecycle ──────────────────────────────────────────────────────
     close() {
+        this.stmtCache.clear();
         this.db?.close();
     }
     // ─── Migration Status ───────────────────────────────────────────────