@soleri/core 2.4.0 → 2.6.0

package/dist/vault/vault.js

@@ -1,21 +1,40 @@
-import Database from 'better-sqlite3';
-import { mkdirSync } from 'node:fs';
-import { dirname } from 'node:path';
+import { SQLitePersistenceProvider } from '../persistence/sqlite-provider.js';
 export class Vault {
-    db;
-    constructor(dbPath = ':memory:') {
-        if (dbPath !== ':memory:')
-            mkdirSync(dirname(dbPath), { recursive: true });
-        this.db = new Database(dbPath);
-        this.db.pragma('journal_mode = WAL');
-        this.db.pragma('foreign_keys = ON');
+    provider;
+    sqliteProvider;
+    syncManager = null;
+    /**
+     * Create a Vault with a PersistenceProvider or a SQLite path (backward compat).
+     */
+    constructor(providerOrPath = ':memory:') {
+        if (typeof providerOrPath === 'string') {
+            const sqlite = new SQLitePersistenceProvider(providerOrPath);
+            this.provider = sqlite;
+            this.sqliteProvider = sqlite;
+            // SQLite-specific pragmas
+            this.provider.run('PRAGMA journal_mode = WAL');
+            this.provider.run('PRAGMA foreign_keys = ON');
+            this.provider.run('PRAGMA synchronous = NORMAL');
+        }
+        else {
+            this.provider = providerOrPath;
+            this.sqliteProvider =
+                providerOrPath instanceof SQLitePersistenceProvider ? providerOrPath : null;
+        }
         this.initialize();
     }
+    setSyncManager(mgr) {
+        this.syncManager = mgr;
+    }
+    /** Backward-compatible factory. */
+    static createWithSQLite(dbPath = ':memory:') {
+        return new Vault(dbPath);
+    }
     initialize() {
-        this.db.exec(`
+        this.provider.execSql(`
       CREATE TABLE IF NOT EXISTS entries (
         id TEXT PRIMARY KEY,
-        type TEXT NOT NULL CHECK(type IN ('pattern', 'anti-pattern', 'rule')),
+        type TEXT NOT NULL CHECK(type IN ('pattern', 'anti-pattern', 'rule', 'playbook')),
         domain TEXT NOT NULL,
         title TEXT NOT NULL,
         severity TEXT NOT NULL CHECK(severity IN ('critical', 'warning', 'suggestion')),
@@ -40,6 +59,23 @@ export class Vault {
         INSERT INTO entries_fts(entries_fts,rowid,id,title,description,context,tags) VALUES('delete',old.rowid,old.id,old.title,old.description,old.context,old.tags);
         INSERT INTO entries_fts(rowid,id,title,description,context,tags) VALUES(new.rowid,new.id,new.title,new.description,new.context,new.tags);
       END;
+      CREATE TABLE IF NOT EXISTS entries_archive (
+        id TEXT PRIMARY KEY,
+        type TEXT NOT NULL,
+        domain TEXT NOT NULL,
+        title TEXT NOT NULL,
+        severity TEXT NOT NULL,
+        description TEXT NOT NULL,
+        context TEXT, example TEXT, counter_example TEXT, why TEXT,
+        tags TEXT NOT NULL DEFAULT '[]',
+        applies_to TEXT DEFAULT '[]',
+        created_at INTEGER NOT NULL,
+        updated_at INTEGER NOT NULL,
+        valid_from INTEGER,
+        valid_until INTEGER,
+        archived_at INTEGER NOT NULL DEFAULT (unixepoch()),
+        archive_reason TEXT
+      );
       CREATE TABLE IF NOT EXISTS projects (
         path TEXT PRIMARY KEY,
         name TEXT NOT NULL,
@@ -92,23 +128,35 @@ export class Vault {
         created_at INTEGER NOT NULL DEFAULT (unixepoch())
       );
       CREATE INDEX IF NOT EXISTS idx_brain_feedback_query ON brain_feedback(query);
+      CREATE INDEX IF NOT EXISTS idx_entries_domain ON entries(domain);
+      CREATE INDEX IF NOT EXISTS idx_entries_type ON entries(type);
+      CREATE INDEX IF NOT EXISTS idx_entries_severity ON entries(severity);
+      CREATE INDEX IF NOT EXISTS idx_memories_project ON memories(project_path);
+      CREATE INDEX IF NOT EXISTS idx_memories_type ON memories(type);
     `);
         this.migrateBrainSchema();
+        this.migrateTemporalSchema();
+    }
+    migrateTemporalSchema() {
+        try {
+            this.provider.run('ALTER TABLE entries ADD COLUMN valid_from INTEGER');
+        }
+        catch {
+            // Column already exists
+        }
+        try {
+            this.provider.run('ALTER TABLE entries ADD COLUMN valid_until INTEGER');
+        }
+        catch {
+            // Column already exists
+        }
     }
-    /**
-     * Migrate brain_feedback table from old schema (accepted/dismissed only)
-     * to new schema with source, confidence, duration, context, reason columns.
-     * Also adds extracted_at to brain_sessions if it exists.
-     */
     migrateBrainSchema() {
-        // Check if brain_feedback needs migration (old schema lacks 'source' column)
-        const columns = this.db.prepare('PRAGMA table_info(brain_feedback)').all();
+        const columns = this.provider.all('PRAGMA table_info(brain_feedback)');
         const hasSource = columns.some((c) => c.name === 'source');
         if (!hasSource && columns.length > 0) {
-            // Old table exists without new columns — rebuild with expanded schema
-            this.db.transaction(() => {
-                this.db
-                    .prepare(`
+            this.provider.transaction(() => {
+                this.provider.run(`
           CREATE TABLE brain_feedback_new (
             id INTEGER PRIMARY KEY AUTOINCREMENT,
             query TEXT NOT NULL,
@@ -121,26 +169,20 @@ export class Vault {
             reason TEXT,
             created_at INTEGER NOT NULL DEFAULT (unixepoch())
           )
-        `)
-                    .run();
-                this.db
-                    .prepare(`
+        `);
+                this.provider.run(`
           INSERT INTO brain_feedback_new (id, query, entry_id, action, created_at)
             SELECT id, query, entry_id, action, created_at FROM brain_feedback
-        `)
-                    .run();
-                this.db.prepare('DROP TABLE brain_feedback').run();
-                this.db.prepare('ALTER TABLE brain_feedback_new RENAME TO brain_feedback').run();
-                this.db
-                    .prepare('CREATE INDEX IF NOT EXISTS idx_brain_feedback_query ON brain_feedback(query)')
-                    .run();
-            })();
-        }
-        // Add extracted_at to brain_sessions if it exists but lacks the column
+        `);
+                this.provider.run('DROP TABLE brain_feedback');
+                this.provider.run('ALTER TABLE brain_feedback_new RENAME TO brain_feedback');
+                this.provider.run('CREATE INDEX IF NOT EXISTS idx_brain_feedback_query ON brain_feedback(query)');
+            });
+        }
         try {
-            const sessionCols = this.db.prepare('PRAGMA table_info(brain_sessions)').all();
+            const sessionCols = this.provider.all('PRAGMA table_info(brain_sessions)');
             if (sessionCols.length > 0 && !sessionCols.some((c) => c.name === 'extracted_at')) {
-                this.db.prepare('ALTER TABLE brain_sessions ADD COLUMN extracted_at TEXT').run();
+                this.provider.run('ALTER TABLE brain_sessions ADD COLUMN extracted_at TEXT');
             }
         }
         catch {
@@ -148,17 +190,17 @@ export class Vault {
         }
     }
     seed(entries) {
-        const upsert = this.db.prepare(`
-      INSERT INTO entries (id,type,domain,title,severity,description,context,example,counter_example,why,tags,applies_to)
-      VALUES (@id,@type,@domain,@title,@severity,@description,@context,@example,@counterExample,@why,@tags,@appliesTo)
+        const sql = `
+      INSERT INTO entries (id,type,domain,title,severity,description,context,example,counter_example,why,tags,applies_to,valid_from,valid_until)
+      VALUES (@id,@type,@domain,@title,@severity,@description,@context,@example,@counterExample,@why,@tags,@appliesTo,@validFrom,@validUntil)
       ON CONFLICT(id) DO UPDATE SET type=excluded.type,domain=excluded.domain,title=excluded.title,severity=excluded.severity,
         description=excluded.description,context=excluded.context,example=excluded.example,counter_example=excluded.counter_example,
-        why=excluded.why,tags=excluded.tags,applies_to=excluded.applies_to,updated_at=unixepoch()
-    `);
-        const tx = this.db.transaction((items) => {
+        why=excluded.why,tags=excluded.tags,applies_to=excluded.applies_to,valid_from=excluded.valid_from,valid_until=excluded.valid_until,updated_at=unixepoch()
+    `;
+        return this.provider.transaction(() => {
             let count = 0;
-            for (const entry of items) {
-                upsert.run({
+            for (const entry of entries) {
+                this.provider.run(sql, {
                     id: entry.id,
                     type: entry.type,
                     domain: entry.domain,
@@ -171,12 +213,16 @@ export class Vault {
                     why: entry.why ?? null,
                     tags: JSON.stringify(entry.tags),
                     appliesTo: JSON.stringify(entry.appliesTo ?? []),
+                    validFrom: entry.validFrom ?? null,
+                    validUntil: entry.validUntil ?? null,
                 });
                 count++;
+                if (this.syncManager) {
+                    this.syncManager.enqueue('ingest', entry.id, entry);
+                }
             }
             return count;
         });
-        return tx(entries);
     }
     search(query, options) {
         const limit = options?.limit ?? 10;
@@ -194,11 +240,15 @@ export class Vault {
             filters.push('e.severity = @severity');
             fp.severity = options.severity;
         }
+        if (!options?.includeExpired) {
+            const now = Math.floor(Date.now() / 1000);
+            filters.push('(e.valid_until IS NULL OR e.valid_until > @now)');
+            filters.push('(e.valid_from IS NULL OR e.valid_from <= @now)');
+            fp.now = now;
+        }
         const wc = filters.length > 0 ? `AND ${filters.join(' AND ')}` : '';
         try {
-            const rows = this.db
-                .prepare(`SELECT e.*, -rank as score FROM entries_fts fts JOIN entries e ON e.rowid = fts.rowid WHERE entries_fts MATCH @query ${wc} ORDER BY score DESC LIMIT @limit`)
-                .all({ query, limit, ...fp });
+            const rows = this.provider.all(`SELECT e.*, -rank as score FROM entries_fts fts JOIN entries e ON e.rowid = fts.rowid WHERE entries_fts MATCH @query ${wc} ORDER BY score DESC LIMIT @limit`, { query, limit, ...fp });
             return rows.map(rowToSearchResult);
         }
         catch {
@@ -206,7 +256,9 @@ export class Vault {
         }
     }
     get(id) {
-        const row = this.db.prepare('SELECT * FROM entries WHERE id = ?').get(id);
+        const row = this.provider.get('SELECT * FROM entries WHERE id = ?', [
+            id,
+        ]);
         return row ? rowToEntry(row) : null;
     }
     list(options) {
@@ -231,31 +283,35 @@ export class Vault {
             });
             filters.push(`(${c.join(' OR ')})`);
         }
+        if (!options?.includeExpired) {
+            const now = Math.floor(Date.now() / 1000);
+            filters.push('(valid_until IS NULL OR valid_until > @now)');
+            filters.push('(valid_from IS NULL OR valid_from <= @now)');
+            params.now = now;
+        }
         const wc = filters.length > 0 ? `WHERE ${filters.join(' AND ')}` : '';
-        const rows = this.db
-            .prepare(`SELECT * FROM entries ${wc} ORDER BY severity, domain, title LIMIT @limit OFFSET @offset`)
-            .all({ ...params, limit: options?.limit ?? 50, offset: options?.offset ?? 0 });
+        const rows = this.provider.all(`SELECT * FROM entries ${wc} ORDER BY severity, domain, title LIMIT @limit OFFSET @offset`, { ...params, limit: options?.limit ?? 50, offset: options?.offset ?? 0 });
         return rows.map(rowToEntry);
     }
     stats() {
-        const total = this.db.prepare('SELECT COUNT(*) as count FROM entries').get().count;
+        const total = this.provider.get('SELECT COUNT(*) as count FROM entries').count;
         return {
             totalEntries: total,
-            byType: gc(this.db, 'type'),
-            byDomain: gc(this.db, 'domain'),
-            bySeverity: gc(this.db, 'severity'),
+            byType: gc(this.provider, 'type'),
+            byDomain: gc(this.provider, 'domain'),
+            bySeverity: gc(this.provider, 'severity'),
         };
     }
     add(entry) {
         this.seed([entry]);
     }
     remove(id) {
-        return this.db.prepare('DELETE FROM entries WHERE id = ?').run(id).changes > 0;
+        const deleted = this.provider.run('DELETE FROM entries WHERE id = ?', [id]).changes > 0;
+        if (deleted && this.syncManager) {
+            this.syncManager.enqueue('delete', id);
+        }
+        return deleted;
     }
-    /**
-     * Partial update of an existing entry's mutable fields.
-     * Returns the updated entry or null if not found.
-     */
     update(id, fields) {
         const existing = this.get(id);
         if (!existing)
@@ -264,26 +320,47 @@ export class Vault {
         this.seed([merged]);
         return this.get(id);
     }
-    /**
-     * Remove multiple entries by IDs in a single transaction.
-     * Returns the number of entries actually removed.
-     */
+    setTemporal(id, validFrom, validUntil) {
+        const sets = [];
+        const params = { id };
+        if (validFrom !== undefined) {
+            sets.push('valid_from = @validFrom');
+            params.validFrom = validFrom;
+        }
+        if (validUntil !== undefined) {
+            sets.push('valid_until = @validUntil');
+            params.validUntil = validUntil;
+        }
+        if (sets.length === 0)
+            return false;
+        sets.push('updated_at = unixepoch()');
+        return (this.provider.run(`UPDATE entries SET ${sets.join(', ')} WHERE id = @id`, params).changes > 0);
+    }
+    findExpiring(withinDays) {
+        const now = Math.floor(Date.now() / 1000);
+        const cutoff = now + withinDays * 86400;
+        const rows = this.provider.all('SELECT * FROM entries WHERE valid_until IS NOT NULL AND valid_until > @now AND valid_until <= @cutoff ORDER BY valid_until ASC', { now, cutoff });
+        return rows.map(rowToEntry);
+    }
+    findExpired(limit = 50) {
+        const now = Math.floor(Date.now() / 1000);
+        const rows = this.provider.all('SELECT * FROM entries WHERE valid_until IS NOT NULL AND valid_until <= @now ORDER BY valid_until DESC LIMIT @limit', { now, limit });
+        return rows.map(rowToEntry);
+    }
     bulkRemove(ids) {
-        const stmt = this.db.prepare('DELETE FROM entries WHERE id = ?');
-        const tx = this.db.transaction((idList) => {
+        return this.provider.transaction(() => {
             let count = 0;
-            for (const id of idList) {
-                count += stmt.run(id).changes;
+            for (const id of ids) {
+                count += this.provider.run('DELETE FROM entries WHERE id = ?', [id]).changes;
+                if (this.syncManager) {
+                    this.syncManager.enqueue('delete', id);
+                }
             }
             return count;
         });
-        return tx(ids);
     }
-    /**
-     * List all unique tags with their occurrence counts.
-     */
     getTags() {
-        const rows = this.db.prepare('SELECT tags FROM entries').all();
+        const rows = this.provider.all('SELECT tags FROM entries');
         const counts = new Map();
         for (const row of rows) {
             const tags = JSON.parse(row.tags || '[]');
@@ -295,41 +372,20 @@ export class Vault {
             .map(([tag, count]) => ({ tag, count }))
             .sort((a, b) => b.count - a.count);
     }
-    /**
-     * List all domains with their entry counts.
-     */
     getDomains() {
-        const rows = this.db
-            .prepare('SELECT domain, COUNT(*) as count FROM entries GROUP BY domain ORDER BY count DESC')
-            .all();
-        return rows;
+        return this.provider.all('SELECT domain, COUNT(*) as count FROM entries GROUP BY domain ORDER BY count DESC');
     }
-    /**
-     * Get recently added or updated entries, ordered by updated_at DESC.
-     */
     getRecent(limit = 20) {
-        const rows = this.db
-            .prepare('SELECT * FROM entries ORDER BY updated_at DESC LIMIT ?')
-            .all(limit);
+        const rows = this.provider.all('SELECT * FROM entries ORDER BY updated_at DESC LIMIT ?', [limit]);
         return rows.map(rowToEntry);
     }
-    /**
-     * Export the entire vault as a JSON-serializable bundle.
-     */
     exportAll() {
-        const rows = this.db
-            .prepare('SELECT * FROM entries ORDER BY domain, title')
-            .all();
+        const rows = this.provider.all('SELECT * FROM entries ORDER BY domain, title');
         const entries = rows.map(rowToEntry);
         return { entries, exportedAt: Math.floor(Date.now() / 1000), count: entries.length };
     }
-    /**
-     * Get entry age distribution — how old entries are, bucketed.
-     */
     getAgeReport() {
-        const rows = this.db
-            .prepare('SELECT created_at, updated_at FROM entries')
-            .all();
+        const rows = this.provider.all('SELECT created_at, updated_at FROM entries');
         const now = Math.floor(Date.now() / 1000);
         const bucketDefs = [
             { label: 'today', minDays: 0, maxDays: 1 },
@@ -366,16 +422,14 @@ export class Vault {
         const projectName = name ?? path.replace(/\/$/, '').split('/').pop() ?? path;
         const existing = this.getProject(path);
         if (existing) {
-            this.db
-                .prepare('UPDATE projects SET last_seen_at = unixepoch(), session_count = session_count + 1 WHERE path = ?')
-                .run(path);
+            this.provider.run('UPDATE projects SET last_seen_at = unixepoch(), session_count = session_count + 1 WHERE path = ?', [path]);
             return this.getProject(path);
         }
-        this.db.prepare('INSERT INTO projects (path, name) VALUES (?, ?)').run(path, projectName);
+        this.provider.run('INSERT INTO projects (path, name) VALUES (?, ?)', [path, projectName]);
         return this.getProject(path);
     }
     getProject(path) {
-        const row = this.db.prepare('SELECT * FROM projects WHERE path = ?').get(path);
+        const row = this.provider.get('SELECT * FROM projects WHERE path = ?', [path]);
         if (!row)
             return null;
         return {
@@ -387,9 +441,7 @@ export class Vault {
         };
     }
     listProjects() {
-        const rows = this.db
-            .prepare('SELECT * FROM projects ORDER BY last_seen_at DESC')
-            .all();
+        const rows = this.provider.all('SELECT * FROM projects ORDER BY last_seen_at DESC');
         return rows.map((row) => ({
             path: row.path,
             name: row.name,
@@ -400,9 +452,7 @@ export class Vault {
     }
     captureMemory(memory) {
         const id = `mem-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
-        this.db
-            .prepare(`INSERT INTO memories (id, project_path, type, context, summary, topics, files_modified, tools_used) VALUES (@id, @projectPath, @type, @context, @summary, @topics, @filesModified, @toolsUsed)`)
-            .run({
+        this.provider.run(`INSERT INTO memories (id, project_path, type, context, summary, topics, files_modified, tools_used) VALUES (@id, @projectPath, @type, @context, @summary, @topics, @filesModified, @toolsUsed)`, {
             id,
             projectPath: memory.projectPath,
             type: memory.type,
@@ -428,9 +478,7 @@ export class Vault {
         }
         const wc = filters.length > 0 ? `AND ${filters.join(' AND ')}` : '';
         try {
-            const rows = this.db
-                .prepare(`SELECT m.* FROM memories_fts fts JOIN memories m ON m.rowid = fts.rowid WHERE memories_fts MATCH @query ${wc} ORDER BY rank LIMIT @limit`)
-                .all({ query, limit, ...fp });
+            const rows = this.provider.all(`SELECT m.* FROM memories_fts fts JOIN memories m ON m.rowid = fts.rowid WHERE memories_fts MATCH @query ${wc} ORDER BY rank LIMIT @limit`, { query, limit, ...fp });
             return rows.map(rowToMemory);
         }
         catch {
@@ -449,19 +497,13 @@ export class Vault {
             params.projectPath = options.projectPath;
         }
         const wc = `WHERE ${filters.join(' AND ')}`;
-        const rows = this.db
-            .prepare(`SELECT * FROM memories ${wc} ORDER BY created_at DESC LIMIT @limit OFFSET @offset`)
-            .all({ ...params, limit: options?.limit ?? 50, offset: options?.offset ?? 0 });
+        const rows = this.provider.all(`SELECT * FROM memories ${wc} ORDER BY created_at DESC LIMIT @limit OFFSET @offset`, { ...params, limit: options?.limit ?? 50, offset: options?.offset ?? 0 });
         return rows.map(rowToMemory);
     }
     memoryStats() {
-        const total = this.db.prepare('SELECT COUNT(*) as count FROM memories WHERE archived_at IS NULL').get().count;
-        const byTypeRows = this.db
-            .prepare('SELECT type as key, COUNT(*) as count FROM memories WHERE archived_at IS NULL GROUP BY type')
-            .all();
-        const byProjectRows = this.db
-            .prepare('SELECT project_path as key, COUNT(*) as count FROM memories WHERE archived_at IS NULL GROUP BY project_path')
-            .all();
+        const total = this.provider.get('SELECT COUNT(*) as count FROM memories WHERE archived_at IS NULL').count;
+        const byTypeRows = this.provider.all('SELECT type as key, COUNT(*) as count FROM memories WHERE archived_at IS NULL GROUP BY type');
+        const byProjectRows = this.provider.all('SELECT project_path as key, COUNT(*) as count FROM memories WHERE archived_at IS NULL GROUP BY project_path');
         return {
             total,
             byType: Object.fromEntries(byTypeRows.map((r) => [r.key, r.count])),
@@ -469,11 +511,13 @@ export class Vault {
         };
     }
     getMemory(id) {
-        const row = this.db.prepare('SELECT * FROM memories WHERE id = ?').get(id);
+        const row = this.provider.get('SELECT * FROM memories WHERE id = ?', [
+            id,
+        ]);
         return row ? rowToMemory(row) : null;
     }
     deleteMemory(id) {
-        return this.db.prepare('DELETE FROM memories WHERE id = ?').run(id).changes > 0;
+        return this.provider.run('DELETE FROM memories WHERE id = ?', [id]).changes > 0;
     }
     memoryStatsDetailed(options) {
         const filters = [];
@@ -491,21 +535,11 @@ export class Vault {
             params.toDate = options.toDate;
         }
         const wc = filters.length > 0 ? `WHERE ${filters.join(' AND ')}` : '';
-        const total = this.db
-            .prepare(`SELECT COUNT(*) as count FROM memories ${wc}${wc ? ' AND' : ' WHERE'} archived_at IS NULL`)
-            .get(params).count;
-        const archivedCount = this.db
-            .prepare(`SELECT COUNT(*) as count FROM memories ${wc}${wc ? ' AND' : ' WHERE'} archived_at IS NOT NULL`)
-            .get(params).count;
-        const byTypeRows = this.db
-            .prepare(`SELECT type as key, COUNT(*) as count FROM memories ${wc}${wc ? ' AND' : ' WHERE'} archived_at IS NULL GROUP BY type`)
-            .all(params);
-        const byProjectRows = this.db
-            .prepare(`SELECT project_path as key, COUNT(*) as count FROM memories ${wc}${wc ? ' AND' : ' WHERE'} archived_at IS NULL GROUP BY project_path`)
-            .all(params);
-        const dateRange = this.db
-            .prepare(`SELECT MIN(created_at) as oldest, MAX(created_at) as newest FROM memories ${wc}${wc ? ' AND' : ' WHERE'} archived_at IS NULL`)
-            .get(params);
+        const total = this.provider.get(`SELECT COUNT(*) as count FROM memories ${wc}${wc ? ' AND' : ' WHERE'} archived_at IS NULL`, params).count;
+        const archivedCount = this.provider.get(`SELECT COUNT(*) as count FROM memories ${wc}${wc ? ' AND' : ' WHERE'} archived_at IS NOT NULL`, params).count;
+        const byTypeRows = this.provider.all(`SELECT type as key, COUNT(*) as count FROM memories ${wc}${wc ? ' AND' : ' WHERE'} archived_at IS NULL GROUP BY type`, params);
+        const byProjectRows = this.provider.all(`SELECT project_path as key, COUNT(*) as count FROM memories ${wc}${wc ? ' AND' : ' WHERE'} archived_at IS NULL GROUP BY project_path`, params);
+        const dateRange = this.provider.get(`SELECT MIN(created_at) as oldest, MAX(created_at) as newest FROM memories ${wc}${wc ? ' AND' : ' WHERE'} archived_at IS NULL`, params);
         return {
             total,
             byType: Object.fromEntries(byTypeRows.map((r) => [r.key, r.count])),
@@ -530,21 +564,19 @@ export class Vault {
             params.type = options.type;
         }
         const wc = filters.length > 0 ? `WHERE ${filters.join(' AND ')}` : '';
-        const rows = this.db
-            .prepare(`SELECT * FROM memories ${wc} ORDER BY created_at ASC`)
-            .all(params);
+        const rows = this.provider.all(`SELECT * FROM memories ${wc} ORDER BY created_at ASC`, Object.keys(params).length > 0 ? params : undefined);
         return rows.map(rowToMemory);
     }
     importMemories(memories) {
-        const upsert = this.db.prepare(`
+        const sql = `
       INSERT OR IGNORE INTO memories (id, project_path, type, context, summary, topics, files_modified, tools_used, created_at, archived_at)
       VALUES (@id, @projectPath, @type, @context, @summary, @topics, @filesModified, @toolsUsed, @createdAt, @archivedAt)
-    `);
+    `;
         let imported = 0;
         let skipped = 0;
-        const tx = this.db.transaction((items) => {
-            for (const m of items) {
-                const result = upsert.run({
+        this.provider.transaction(() => {
+            for (const m of memories) {
+                const result = this.provider.run(sql, {
                     id: m.id,
                     projectPath: m.projectPath,
                     type: m.type,
@@ -562,20 +594,15 @@ export class Vault {
                     skipped++;
             }
         });
-        tx(memories);
         return { imported, skipped };
     }
     pruneMemories(olderThanDays) {
         const cutoff = Math.floor(Date.now() / 1000) - olderThanDays * 86400;
-        const result = this.db
-            .prepare('DELETE FROM memories WHERE created_at < ? AND archived_at IS NULL')
-            .run(cutoff);
+        const result = this.provider.run('DELETE FROM memories WHERE created_at < ? AND archived_at IS NULL', [cutoff]);
         return { pruned: result.changes };
     }
     deduplicateMemories() {
-        // Find duplicates by matching summary + project_path + type
-        const dupeRows = this.db
-            .prepare(`
+        const dupeRows = this.provider.all(`
         SELECT m1.id as id1, m2.id as id2
         FROM memories m1
         JOIN memories m2 ON m1.summary = m2.summary
@@ -584,9 +611,7 @@ export class Vault {
           AND m1.id < m2.id
           AND m1.archived_at IS NULL
           AND m2.archived_at IS NULL
-      `)
-            .all();
-        // Group: keep the earliest (id1), remove all later duplicates
+      `);
         const groupMap = new Map();
         for (const row of dupeRows) {
             if (!groupMap.has(row.id1))
@@ -604,19 +629,16 @@ export class Vault {
             }
         }
         if (toRemove.size > 0) {
-            const del = this.db.prepare('DELETE FROM memories WHERE id = ?');
-            const tx = this.db.transaction((ids) => {
-                for (const id of ids)
-                    del.run(id);
+            this.provider.transaction(() => {
+                for (const id of toRemove) {
+                    this.provider.run('DELETE FROM memories WHERE id = ?', [id]);
+                }
             });
-            tx([...toRemove]);
         }
         return { removed: toRemove.size, groups };
     }
     memoryTopics() {
-        const rows = this.db
-            .prepare('SELECT topics FROM memories WHERE archived_at IS NULL')
-            .all();
+        const rows = this.provider.all('SELECT topics FROM memories WHERE archived_at IS NULL');
         const topicCounts = new Map();
         for (const row of rows) {
             const topics = JSON.parse(row.topics || '[]');
@@ -629,13 +651,9 @@ export class Vault {
             .sort((a, b) => b.count - a.count);
     }
     memoriesByProject() {
-        const rows = this.db
-            .prepare('SELECT project_path as project, COUNT(*) as count FROM memories WHERE archived_at IS NULL GROUP BY project_path ORDER BY count DESC')
-            .all();
+        const rows = this.provider.all('SELECT project_path as project, COUNT(*) as count FROM memories WHERE archived_at IS NULL GROUP BY project_path ORDER BY count DESC');
         return rows.map((row) => {
-            const memories = this.db
-                .prepare('SELECT * FROM memories WHERE project_path = ? AND archived_at IS NULL ORDER BY created_at DESC')
-                .all(row.project);
+            const memories = this.provider.all('SELECT * FROM memories WHERE project_path = ? AND archived_at IS NULL ORDER BY created_at DESC', [row.project]);
             return {
                 project: row.project,
                 count: row.count,
@@ -643,17 +661,116 @@ export class Vault {
             };
         });
     }
+    /**
+     * Rebuild the FTS5 index for the entries table.
+     * Useful after bulk operations or if the index gets out of sync.
+     */
+    rebuildFtsIndex() {
+        try {
+            this.provider.run("INSERT INTO entries_fts(entries_fts) VALUES('rebuild')");
+        }
+        catch {
+            // Graceful degradation — FTS rebuild failed (e.g. table doesn't exist yet)
+        }
+    }
+    /**
+     * Archive entries older than N days. Moves them to entries_archive.
+     */
+    archive(options) {
+        const cutoff = Math.floor(Date.now() / 1000) - options.olderThanDays * 86400;
+        const reason = options.reason ?? `Archived: older than ${options.olderThanDays} days`;
+        return this.provider.transaction(() => {
+            // Find candidates
+            const candidates = this.provider.all('SELECT id FROM entries WHERE updated_at < ?', [cutoff]);
+            if (candidates.length === 0)
+                return { archived: 0 };
+            let archived = 0;
+            for (const { id } of candidates) {
+                // Copy to archive
+                this.provider.run(`INSERT OR IGNORE INTO entries_archive (id, type, domain, title, severity, description, context, example, counter_example, why, tags, applies_to, created_at, updated_at, valid_from, valid_until, archive_reason)
+           SELECT id, type, domain, title, severity, description, context, example, counter_example, why, tags, applies_to, created_at, updated_at, valid_from, valid_until, ?
+           FROM entries WHERE id = ?`, [reason, id]);
+                // Delete from active
+                const result = this.provider.run('DELETE FROM entries WHERE id = ?', [id]);
+                archived += result.changes;
+            }
+            return { archived };
+        });
+    }
+    /**
+     * Restore an archived entry back to the active table.
+     */
+    restore(id) {
+        return this.provider.transaction(() => {
+            const archived = this.provider.get('SELECT * FROM entries_archive WHERE id = ?', [id]);
+            if (!archived)
+                return false;
+            this.provider.run(`INSERT OR REPLACE INTO entries (id, type, domain, title, severity, description, context, example, counter_example, why, tags, applies_to, created_at, updated_at, valid_from, valid_until)
+         SELECT id, type, domain, title, severity, description, context, example, counter_example, why, tags, applies_to, created_at, updated_at, valid_from, valid_until
+         FROM entries_archive WHERE id = ?`, [id]);
+            this.provider.run('DELETE FROM entries_archive WHERE id = ?', [id]);
+            return true;
+        });
+    }
+    /**
+     * Optimize the database: VACUUM (SQLite only), ANALYZE, and FTS rebuild.
+     */
+    optimize() {
+        let vacuumed = false;
+        let analyzed = false;
+        let ftsRebuilt = false;
+        // VACUUM only for SQLite
+        if (this.provider.backend === 'sqlite') {
+            try {
+                this.provider.execSql('VACUUM');
+                vacuumed = true;
+            }
+            catch {
+                // VACUUM may fail inside a transaction
+            }
+        }
+        try {
+            this.provider.execSql('ANALYZE');
+            analyzed = true;
+        }
+        catch {
+            // Non-critical
+        }
+        try {
+            this.provider.ftsRebuild('entries');
+            this.provider.ftsRebuild('memories');
+            ftsRebuilt = true;
+        }
+        catch {
+            // Non-critical
+        }
+        return { vacuumed, analyzed, ftsRebuilt };
+    }
+    /**
+     * Get the underlying persistence provider.
+     */
+    getProvider() {
+        return this.provider;
+    }
+    /**
+     * Get the raw better-sqlite3 Database (backward compat).
+     * Throws if the provider is not SQLite.
+     */
     getDb() {
-        return this.db;
+        if (process.env.NODE_ENV !== 'test' && process.env.VITEST !== 'true') {
+            console.warn('Vault.getDb() is deprecated. Use vault.getProvider() instead.');
+        }
+        if (this.sqliteProvider) {
+            return this.sqliteProvider.getDatabase();
+        }
+        throw new Error('getDb() is only available with SQLite provider');
     }
     close() {
-        this.db.close();
+        this.provider.close();
     }
 }
-function gc(db, col) {
-    const rows = db
-        .prepare(`SELECT ${col} as key, COUNT(*) as count FROM entries GROUP BY ${col}`)
-        .all();
+function gc(provider, col) {
+    const rows = provider.all(`SELECT ${col} as key, COUNT(*) as count FROM entries GROUP BY ${col}`);
     return Object.fromEntries(rows.map((r) => [r.key, r.count]));
 }
 function rowToEntry(row) {
@@ -670,6 +787,8 @@ function rowToEntry(row) {
         why: row.why ?? undefined,
         tags: JSON.parse(row.tags || '[]'),
         appliesTo: JSON.parse(row.applies_to || '[]'),
+        validFrom: row.valid_from ?? undefined,
+        validUntil: row.valid_until ?? undefined,
     };
 }
 function rowToSearchResult(row) {