@soleri/core 2.5.0 → 2.6.0

package/src/project/project-registry.ts

@@ -2,11 +2,11 @@
  * Project Registry — SQLite-backed registry for tracking projects,
  * rules, and cross-project links.
  *
- * Uses the Vault's underlying SQLite database via `vault.getDb()`.
+ * Uses the Vault's underlying database via PersistenceProvider.
  * Tables are created lazily on first access.
  */
 
-import type Database from 'better-sqlite3';
+import type { PersistenceProvider } from '../persistence/types.js';
 import type { RegisteredProject, ProjectRule, ProjectLink, LinkType } from './types.js';
 
 /** Row shape for the projects table. */
@@ -82,15 +82,15 @@ function rowToLink(row: LinkRow): ProjectLink {
 }
 
 export class ProjectRegistry {
-  private db: Database.Database;
+  private provider: PersistenceProvider;
 
-  constructor(db: Database.Database) {
-    this.db = db;
+  constructor(provider: PersistenceProvider) {
+    this.provider = provider;
     this.initTables();
   }
 
   private initTables(): void {
-    this.db.exec(`
+    this.provider.execSql(`
       CREATE TABLE IF NOT EXISTS registered_projects (
         id TEXT PRIMARY KEY,
         path TEXT UNIQUE NOT NULL,
@@ -128,19 +128,19 @@ export class ProjectRegistry {
     const id = pathToId(path);
     const now = Date.now();
 
-    const existing = this.db.prepare('SELECT * FROM registered_projects WHERE id = ?').get(id) as
-      | ProjectRow
-      | undefined;
+    const existing = this.provider.get<ProjectRow>(
+      'SELECT * FROM registered_projects WHERE id = ?',
+      [id],
+    );
 
     if (existing) {
       // Update lastAccessedAt, and optionally name/metadata if provided
       const newName = name ?? existing.name;
       const newMetadata = metadata ? JSON.stringify(metadata) : existing.metadata;
-      this.db
-        .prepare(
-          'UPDATE registered_projects SET last_accessed_at = ?, name = ?, metadata = ? WHERE id = ?',
-        )
-        .run(now, newName, newMetadata, id);
+      this.provider.run(
+        'UPDATE registered_projects SET last_accessed_at = ?, name = ?, metadata = ? WHERE id = ?',
+        [now, newName, newMetadata, id],
+      );
       return rowToProject({
         ...existing,
         last_accessed_at: now,
@@ -157,11 +157,10 @@ export class ProjectRegistry {
       last_accessed_at: now,
       metadata: JSON.stringify(metadata ?? {}),
     };
-    this.db
-      .prepare(
-        'INSERT INTO registered_projects (id, path, name, registered_at, last_accessed_at, metadata) VALUES (?, ?, ?, ?, ?, ?)',
-      )
-      .run(row.id, row.path, row.name, row.registered_at, row.last_accessed_at, row.metadata);
+    this.provider.run(
+      'INSERT INTO registered_projects (id, path, name, registered_at, last_accessed_at, metadata) VALUES (?, ?, ?, ?, ?, ?)',
+      [row.id, row.path, row.name, row.registered_at, row.last_accessed_at, row.metadata],
+    );
 
     return rowToProject(row);
   }
@@ -170,9 +169,9 @@ export class ProjectRegistry {
    * Get a project by ID.
    */
   get(projectId: string): RegisteredProject | null {
-    const row = this.db.prepare('SELECT * FROM registered_projects WHERE id = ?').get(projectId) as
-      | ProjectRow
-      | undefined;
+    const row = this.provider.get<ProjectRow>('SELECT * FROM registered_projects WHERE id = ?', [
+      projectId,
+    ]);
     return row ? rowToProject(row) : null;
   }
 
@@ -180,9 +179,9 @@ export class ProjectRegistry {
    * Get a project by its filesystem path.
    */
   getByPath(path: string): RegisteredProject | null {
-    const row = this.db.prepare('SELECT * FROM registered_projects WHERE path = ?').get(path) as
-      | ProjectRow
-      | undefined;
+    const row = this.provider.get<ProjectRow>('SELECT * FROM registered_projects WHERE path = ?', [
+      path,
+    ]);
     return row ? rowToProject(row) : null;
   }
 
@@ -190,9 +189,9 @@ export class ProjectRegistry {
    * List all registered projects.
    */
   list(): RegisteredProject[] {
-    const rows = this.db
-      .prepare('SELECT * FROM registered_projects ORDER BY last_accessed_at DESC')
-      .all() as ProjectRow[];
+    const rows = this.provider.all<ProjectRow>(
+      'SELECT * FROM registered_projects ORDER BY last_accessed_at DESC',
+    );
     return rows.map(rowToProject);
   }
 
@@ -200,25 +199,26 @@ export class ProjectRegistry {
    * Unregister a project by ID. Also removes associated rules and links.
    */
   unregister(projectId: string): boolean {
-    const result = this.db.transaction(() => {
-      this.db.prepare('DELETE FROM project_rules WHERE project_id = ?').run(projectId);
-      this.db
-        .prepare('DELETE FROM project_links WHERE source_project_id = ? OR target_project_id = ?')
-        .run(projectId, projectId);
+    return this.provider.transaction(() => {
+      this.provider.run('DELETE FROM project_rules WHERE project_id = ?', [projectId]);
+      this.provider.run(
+        'DELETE FROM project_links WHERE source_project_id = ? OR target_project_id = ?',
+        [projectId, projectId],
+      );
       return (
-        this.db.prepare('DELETE FROM registered_projects WHERE id = ?').run(projectId).changes > 0
+        this.provider.run('DELETE FROM registered_projects WHERE id = ?', [projectId]).changes > 0
       );
-    })();
-    return result;
+    });
   }
 
   /**
    * Update the lastAccessedAt timestamp for a project.
    */
   touch(projectId: string): void {
-    this.db
-      .prepare('UPDATE registered_projects SET last_accessed_at = ? WHERE id = ?')
-      .run(Date.now(), projectId);
+    this.provider.run('UPDATE registered_projects SET last_accessed_at = ? WHERE id = ?', [
+      Date.now(),
+      projectId,
+    ]);
   }
 
   // ─── Rules ──────────────────────────────────────────────────────────
@@ -232,11 +232,10 @@ export class ProjectRegistry {
   ): ProjectRule {
     const id = `rule-${projectId}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
     const now = Date.now();
-    this.db
-      .prepare(
-        'INSERT INTO project_rules (id, project_id, category, text, priority, created_at) VALUES (?, ?, ?, ?, ?, ?)',
-      )
-      .run(id, projectId, rule.category, rule.text, rule.priority, now);
+    this.provider.run(
+      'INSERT INTO project_rules (id, project_id, category, text, priority, created_at) VALUES (?, ?, ?, ?, ?, ?)',
+      [id, projectId, rule.category, rule.text, rule.priority, now],
+    );
 
     return {
       id,
@@ -252,11 +251,10 @@ export class ProjectRegistry {
    * Get all rules for a project.
    */
   getRules(projectId: string): ProjectRule[] {
-    const rows = this.db
-      .prepare(
-        'SELECT * FROM project_rules WHERE project_id = ? ORDER BY priority DESC, created_at ASC',
-      )
-      .all(projectId) as RuleRow[];
+    const rows = this.provider.all<RuleRow>(
+      'SELECT * FROM project_rules WHERE project_id = ? ORDER BY priority DESC, created_at ASC',
+      [projectId],
+    );
     return rows.map(rowToRule);
   }
 
@@ -264,7 +262,7 @@ export class ProjectRegistry {
    * Remove a rule by ID.
    */
   removeRule(ruleId: string): boolean {
-    return this.db.prepare('DELETE FROM project_rules WHERE id = ?').run(ruleId).changes > 0;
+    return this.provider.run('DELETE FROM project_rules WHERE id = ?', [ruleId]).changes > 0;
   }
 
   /**
@@ -285,20 +283,18 @@ export class ProjectRegistry {
    */
   link(sourceId: string, targetId: string, linkType: LinkType): ProjectLink {
     const now = Date.now();
-    const info = this.db
-      .prepare(
-        'INSERT OR IGNORE INTO project_links (source_project_id, target_project_id, link_type, created_at) VALUES (?, ?, ?, ?)',
-      )
-      .run(sourceId, targetId, linkType, now);
+    const info = this.provider.run(
+      'INSERT OR IGNORE INTO project_links (source_project_id, target_project_id, link_type, created_at) VALUES (?, ?, ?, ?)',
+      [sourceId, targetId, linkType, now],
+    );
 
     // If insert was ignored (duplicate), fetch existing
     if (info.changes === 0) {
-      const existing = this.db
-        .prepare(
-          'SELECT * FROM project_links WHERE source_project_id = ? AND target_project_id = ? AND link_type = ?',
-        )
-        .get(sourceId, targetId, linkType) as LinkRow;
-      return rowToLink(existing);
+      const existing = this.provider.get<LinkRow>(
+        'SELECT * FROM project_links WHERE source_project_id = ? AND target_project_id = ? AND link_type = ?',
+        [sourceId, targetId, linkType],
+      );
+      return rowToLink(existing!);
     }
 
     return {
@@ -316,26 +312,25 @@ export class ProjectRegistry {
    */
   unlink(sourceId: string, targetId: string, linkType?: LinkType): number {
     if (linkType) {
-      return this.db
-        .prepare(
-          'DELETE FROM project_links WHERE source_project_id = ? AND target_project_id = ? AND link_type = ?',
-        )
-        .run(sourceId, targetId, linkType).changes;
+      return this.provider.run(
+        'DELETE FROM project_links WHERE source_project_id = ? AND target_project_id = ? AND link_type = ?',
+        [sourceId, targetId, linkType],
+      ).changes;
     }
-    return this.db
-      .prepare('DELETE FROM project_links WHERE source_project_id = ? AND target_project_id = ?')
-      .run(sourceId, targetId).changes;
+    return this.provider.run(
+      'DELETE FROM project_links WHERE source_project_id = ? AND target_project_id = ?',
+      [sourceId, targetId],
+    ).changes;
   }
 
   /**
    * Get all links for a project (both outgoing and incoming).
    */
   getLinks(projectId: string): ProjectLink[] {
-    const rows = this.db
-      .prepare(
-        'SELECT * FROM project_links WHERE source_project_id = ? OR target_project_id = ? ORDER BY created_at DESC',
-      )
-      .all(projectId, projectId) as LinkRow[];
+    const rows = this.provider.all<LinkRow>(
+      'SELECT * FROM project_links WHERE source_project_id = ? OR target_project_id = ? ORDER BY created_at DESC',
+      [projectId, projectId],
+    );
     return rows.map(rowToLink);
   }
 

package/src/runtime/admin-extra-ops.ts

@@ -1,10 +1,10 @@
 /**
- * Extended admin operations — 23 ops for production readiness.
+ * Extended admin operations — 24 ops for production readiness.
  *
  * Groups: telemetry (3), permissions (1), vault analytics (1),
  *         search insights (1), module status (1), env (1), gc (1), export config (1),
  *         key pool (4), profiles (5), plugins (2), instruction validation (1),
- *         hot reload (1).
+ *         hot reload (1), persistence (1).
  */
 
 import { z } from 'zod';
@@ -33,7 +33,7 @@ interface PluginInfo {
 }
 
 /**
- * Create 23 extended admin operations for production observability.
+ * Create 24 extended admin operations for production observability.
  */
 export function createAdminExtraOps(runtime: AgentRuntime): OpDefinition[] {
   const { vault, brain, cognee, telemetry } = runtime;
@@ -648,5 +648,38 @@ export function createAdminExtraOps(runtime: AgentRuntime): OpDefinition[] {
         }
       },
     },
+
+    // ─── Persistence ────────────────────────────────────────────────
+    {
+      name: 'admin_persistence_info',
+      description: 'Get persistence backend info: type, connection status, and table row counts.',
+      auth: 'read',
+      schema: z.object({}),
+      handler: async () => {
+        const provider = runtime.vault.getProvider();
+        const backend = provider.backend;
+
+        const tables: Record<string, number> = {};
+        const tableNames = [
+          'entries',
+          'entries_archive',
+          'memories',
+          'projects',
+          'brain_vocabulary',
+          'brain_feedback',
+        ];
+
+        for (const table of tableNames) {
+          try {
+            const row = provider.get<{ count: number }>(`SELECT COUNT(*) as count FROM ${table}`);
+            tables[table] = row?.count ?? 0;
+          } catch {
+            tables[table] = -1; // Table doesn't exist
+          }
+        }
+
+        return { backend, tables };
+      },
+    },
   ];
 }

package/src/runtime/core-ops.ts

@@ -1,5 +1,5 @@
 /**
- * Generic core operations factory — 158 ops that every agent gets.
+ * Generic core operations factory — 207 ops that every agent gets.
  *
  * These ops are agent-agnostic (no persona, no activation).
  * The 5 agent-specific ops (health, identity, activate, inject_claude_md, setup)
@@ -30,14 +30,14 @@ import { createCogneeSyncOps } from './cognee-sync-ops.js';
 import { createIntakeOps } from './intake-ops.js';
 
 /**
- * Create the 203 generic core operations for an agent runtime.
+ * Create the 207 generic core operations for an agent runtime.
  *
  * Groups: search/vault (4), memory (4), export (1), planning (5),
  *         brain (8), brain intelligence (11), cognee (5),
  *         llm (2), curator (8), control (8), governance (5),
  *         playbook (5), prompt templates (2),
- *         planning-extra (22), memory-extra (8), vault-extra (20),
- *         admin (8), admin-extra (23), loop (9), orchestrate (5),
+ *         planning-extra (22), memory-extra (8), vault-extra (23),
+ *         admin (8), admin-extra (24), loop (9), orchestrate (5),
  *         grading (5), capture (4), curator-extra (5), project (12),
  *         cognee-sync (3), intake (4).
  */

package/src/runtime/runtime.ts

@@ -94,7 +94,7 @@ export function createAgentRuntime(config: AgentRuntimeConfig): AgentRuntime {
   const telemetry = new Telemetry();
 
   // Project Registry — multi-project tracking with rules and links
-  const projectRegistry = new ProjectRegistry(vault.getDb());
+  const projectRegistry = new ProjectRegistry(vault.getProvider());
 
   // Template Manager — prompt templates with variable substitution
   const templatesDir = config.templatesDir ?? join(agentHome, 'templates');

package/src/runtime/vault-extra-ops.ts

@@ -1,8 +1,9 @@
 /**
- * Extra vault operations — 20 ops that extend the 4 base vault ops in core-ops.ts.
+ * Extra vault operations — 23 ops that extend the 4 base vault ops in core-ops.ts.
  *
  * Groups: single-entry CRUD (3), bulk (2), discovery (3), import/export (3),
- *         analytics (1), seed canonical (1), knowledge lifecycle (4), temporal (3).
+ *         analytics (1), seed canonical (1), knowledge lifecycle (4), temporal (3),
+ *         archival (3).
  */
 
 import { z } from 'zod';
@@ -546,6 +547,45 @@ export function createVaultExtraOps(runtime: AgentRuntime): OpDefinition[] {
         return { entries, count: entries.length };
       },
     },
+
+    // ─── Archival ───────────────────────────────────────────────────
+    {
+      name: 'vault_archive',
+      description:
+        'Archive entries older than N days to entries_archive table. Keeps active table lean.',
+      auth: 'write',
+      schema: z.object({
+        olderThanDays: z.number().describe('Archive entries not updated in this many days'),
+        reason: z.string().optional().describe('Reason for archiving'),
+      }),
+      handler: async (params) => {
+        return vault.archive({
+          olderThanDays: params.olderThanDays as number,
+          reason: params.reason as string | undefined,
+        });
+      },
+    },
+    {
+      name: 'vault_restore',
+      description: 'Restore an archived entry back to the active entries table.',
+      auth: 'write',
+      schema: z.object({
+        id: z.string().describe('ID of the archived entry to restore'),
+      }),
+      handler: async (params) => {
+        const restored = vault.restore(params.id as string);
+        return { restored, id: params.id };
+      },
+    },
+    {
+      name: 'vault_optimize',
+      description: 'Optimize the vault database: VACUUM (SQLite), ANALYZE, and FTS index rebuild.',
+      auth: 'write',
+      schema: z.object({}),
+      handler: async () => {
+        return vault.optimize();
+      },
+    },
   ];
 }
 

package/src/vault/vault.ts

@@ -53,6 +53,7 @@ export class Vault {
       // 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 =
@@ -99,6 +100,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,
@@ -151,6 +169,11 @@ 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();
@@ -863,6 +886,98 @@ export class Vault {
     }
   }
 
+  /**
+   * Archive entries older than N days. Moves them to entries_archive.
+   */
+  archive(options: { olderThanDays: number; reason?: string }): { archived: number } {
+    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<{ id: string }>(
+        '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: string): boolean {
+    return this.provider.transaction(() => {
+      const archived = this.provider.get<Record<string, unknown>>(
+        '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(): { vacuumed: boolean; analyzed: boolean; ftsRebuilt: boolean } {
+    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.
    */
@@ -875,6 +990,9 @@ export class Vault {
    * Throws if the provider is not SQLite.
    */
   getDb(): import('better-sqlite3').Database {
+    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();
     }