@soleri/core 8.0.0 → 8.1.0

package/src/vault/vault.ts

@@ -76,6 +76,32 @@ export class Vault {
         providerOrPath instanceof SQLitePersistenceProvider ? providerOrPath : null;
     }
     this.initialize();
+    this.checkFormatVersion();
+  }
+
+  /**
+   * Vault format version — tracks schema changes for migration safety.
+   * Increment when schema changes in a way that requires migration.
+   *
+   * History:
+   *   1 — Initial schema (v8.0.0): entries, memories, brain_feedback, FTS5
+   */
+  static readonly FORMAT_VERSION = 1;
+
+  private checkFormatVersion(): void {
+    const row = this.provider.get<{ user_version: number }>('PRAGMA user_version');
+    const current = row?.user_version ?? 0;
+
+    if (current === 0) {
+      // Fresh database — stamp with current version
+      this.provider.run(`PRAGMA user_version = ${Vault.FORMAT_VERSION}`);
+    } else if (current > Vault.FORMAT_VERSION) {
+      throw new Error(
+        `Vault format version ${current} is newer than engine supports (${Vault.FORMAT_VERSION}). ` +
+          `Upgrade @soleri/core to a compatible version.`,
+      );
+    }
+    // current < FORMAT_VERSION → future: run migration scripts here
   }
 
   setSyncManager(mgr: import('../cognee/sync-manager.js').CogneeSyncManager): void {

package/src/__tests__/postgres-provider.test.ts

@@ -1,116 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import { translateSql, PostgresPersistenceProvider } from '../persistence/postgres-provider.js';
-
-describe('translateSql', () => {
-  it('converts positional ? to $N', () => {
-    const result = translateSql('SELECT * FROM t WHERE a = ? AND b = ?', ['x', 'y']);
-    expect(result.sql).toBe('SELECT * FROM t WHERE a = $1 AND b = $2');
-    expect(result.values).toEqual(['x', 'y']);
-  });
-
-  it('converts named @params to $N', () => {
-    const result = translateSql('INSERT INTO t (a, b) VALUES (@name, @age)', {
-      name: 'Alice',
-      age: 30,
-    });
-    expect(result.sql).toBe('INSERT INTO t (a, b) VALUES ($1, $2)');
-    expect(result.values).toEqual(['Alice', 30]);
-  });
-
-  it('deduplicates repeated named params', () => {
-    const result = translateSql('SELECT * FROM t WHERE a = @x OR b = @x', { x: 42 });
-    expect(result.sql).toBe('SELECT * FROM t WHERE a = $1 OR b = $1');
-    expect(result.values).toEqual([42]);
-  });
-
-  it('replaces unixepoch()', () => {
-    const result = translateSql('INSERT INTO t (ts) VALUES (unixepoch())');
-    expect(result.sql).toBe('INSERT INTO t (ts) VALUES (EXTRACT(EPOCH FROM NOW())::integer)');
-    expect(result.values).toEqual([]);
-  });
-
-  it('handles no params', () => {
-    const result = translateSql('SELECT 1');
-    expect(result.sql).toBe('SELECT 1');
-    expect(result.values).toEqual([]);
-  });
-
-  it('handles mixed: ? params + unixepoch()', () => {
-    const result = translateSql('UPDATE t SET name = ?, updated_at = unixepoch() WHERE id = ?', [
-      'Bob',
-      'id-1',
-    ]);
-    expect(result.sql).toBe(
-      'UPDATE t SET name = $1, updated_at = EXTRACT(EPOCH FROM NOW())::integer WHERE id = $2',
-    );
-    expect(result.values).toEqual(['Bob', 'id-1']);
-  });
-
-  it('replaces INTEGER PRIMARY KEY AUTOINCREMENT with SERIAL PRIMARY KEY', () => {
-    const result = translateSql('CREATE TABLE t (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT)');
-    expect(result.sql).toBe('CREATE TABLE t (id SERIAL PRIMARY KEY, name TEXT)');
-  });
-
-  it('strips PRAGMA statements', () => {
-    const result = translateSql('PRAGMA journal_mode = WAL');
-    expect(result.sql).toBe('-- pragma removed');
-  });
-
-  it('replaces INSERT OR IGNORE with INSERT', () => {
-    const result = translateSql('INSERT OR IGNORE INTO t (a) VALUES (?)', ['x']);
-    expect(result.sql).toBe('INSERT INTO t (a) VALUES ($1)');
-    expect(result.values).toEqual(['x']);
-  });
-
-  it('replaces INSERT OR REPLACE with INSERT', () => {
-    const result = translateSql('INSERT OR REPLACE INTO t (a) VALUES (?)', ['x']);
-    expect(result.sql).toBe('INSERT INTO t (a) VALUES ($1)');
-    expect(result.values).toEqual(['x']);
-  });
-
-  it('handles complex vault-style query with multiple named params', () => {
-    const result = translateSql(
-      'SELECT e.* FROM entries e WHERE e.domain = @domain AND e.type = @type ORDER BY e.title LIMIT @limit OFFSET @offset',
-      { domain: 'design', type: 'pattern', limit: 10, offset: 0 },
-    );
-    expect(result.sql).toBe(
-      'SELECT e.* FROM entries e WHERE e.domain = $1 AND e.type = $2 ORDER BY e.title LIMIT $3 OFFSET $4',
-    );
-    expect(result.values).toEqual(['design', 'pattern', 10, 0]);
-  });
-
-  it('handles vault seed query with many named params', () => {
-    const result = translateSql(
-      'INSERT INTO entries (id, type, domain) VALUES (@id, @type, @domain) ON CONFLICT(id) DO UPDATE SET type=excluded.type',
-      { id: 'e1', type: 'pattern', domain: 'general' },
-    );
-    expect(result.sql).toContain('VALUES ($1, $2, $3)');
-    expect(result.values).toEqual(['e1', 'pattern', 'general']);
-  });
-});
-
-describe('PostgresPersistenceProvider', () => {
-  it('class exists with correct backend', () => {
-    expect(PostgresPersistenceProvider).toBeDefined();
-    expect(typeof PostgresPersistenceProvider.create).toBe('function');
-    expect(typeof PostgresPersistenceProvider.createSync).toBe('function');
-  });
-
-  it('createSync returns a provider instance', () => {
-    const provider = PostgresPersistenceProvider.createSync('postgresql://localhost/test');
-    expect(provider.backend).toBe('postgres');
-    expect(provider.getConnectionString()).toBe('postgresql://localhost/test');
-  });
-
-  it('ftsRebuild is a no-op (PostgreSQL GIN auto-maintains)', () => {
-    const provider = PostgresPersistenceProvider.createSync('postgresql://localhost/test');
-    // Should not throw
-    provider.ftsRebuild('entries');
-  });
-
-  it('close is safe to call multiple times', () => {
-    const provider = PostgresPersistenceProvider.createSync('postgresql://localhost/test');
-    provider.close();
-    provider.close(); // should not throw
-  });
-});

package/src/health/doctor-checks.ts

@@ -1,115 +0,0 @@
-/**
- * Doctor Checks — 8 specialized health checks for comprehensive diagnostics.
- *
- * Each check validates a subsystem and reports pass/warn/fail.
- */
-
-import type { HealthRegistry } from './health-registry.js';
-import type { AgentRuntime } from '../runtime/types.js';
-
-export interface DoctorCheckResult {
-  check: string;
-  status: 'pass' | 'warn' | 'fail';
-  message: string;
-}
-
-export function runDoctorChecks(runtime: AgentRuntime): DoctorCheckResult[] {
-  const results: DoctorCheckResult[] = [];
-
-  // 1. Config
-  try {
-    const id = runtime.config.agentId;
-    results.push({
-      check: 'config',
-      status: id ? 'pass' : 'fail',
-      message: id ? `Agent "${id}" configured` : 'No agent ID',
-    });
-  } catch (e) {
-    results.push({ check: 'config', status: 'fail', message: (e as Error).message });
-  }
-
-  // 2. Database
-  try {
-    runtime.vault.getProvider().get<{ v: number }>('PRAGMA user_version');
-    results.push({ check: 'database', status: 'pass', message: 'SQLite healthy' });
-  } catch (e) {
-    results.push({ check: 'database', status: 'fail', message: (e as Error).message });
-  }
-
-  // 3. Vault
-  try {
-    const stats = runtime.vault.stats();
-    results.push({
-      check: 'vault',
-      status: stats.totalEntries > 0 ? 'pass' : 'warn',
-      message: stats.totalEntries > 0 ? `${stats.totalEntries} entries` : 'Vault empty',
-    });
-  } catch (e) {
-    results.push({ check: 'vault', status: 'fail', message: (e as Error).message });
-  }
-
-  // 4. LLM
-  try {
-    const pool = runtime.keyPool;
-    const total = (pool.openai?.getActiveKey() ? 1 : 0) + (pool.anthropic?.getActiveKey() ? 1 : 0);
-    results.push({
-      check: 'llm',
-      status: total > 0 ? 'pass' : 'warn',
-      message: total > 0 ? `${total} provider(s) available` : 'No API keys — LLM features disabled',
-    });
-  } catch {
-    results.push({ check: 'llm', status: 'warn', message: 'LLM check failed' });
-  }
-
-  // 5. Auth
-  results.push({
-    check: 'auth',
-    status: 'pass',
-    message: `Mode: ${runtime.authPolicy.mode}`,
-  });
-
-  // 6. Plugins
-  try {
-    const count = runtime.pluginRegistry.list().length;
-    results.push({ check: 'plugins', status: 'pass', message: `${count} plugin(s)` });
-  } catch {
-    results.push({ check: 'plugins', status: 'warn', message: 'Plugin check failed' });
-  }
-
-  // 7. Embeddings (Cognee)
-  try {
-    const available = runtime.cognee?.isAvailable ?? false;
-    results.push({
-      check: 'embeddings',
-      status: available ? 'pass' : 'warn',
-      message: available ? 'Cognee available' : 'Cognee not available — vector search disabled',
-    });
-  } catch {
-    results.push({ check: 'embeddings', status: 'warn', message: 'Embedding check failed' });
-  }
-
-  // 8. Security
-  results.push({
-    check: 'security',
-    status: runtime.authPolicy.mode === 'permissive' ? 'warn' : 'pass',
-    message:
-      runtime.authPolicy.mode === 'permissive'
-        ? 'Permissive mode — all ops allowed'
-        : `Enforcement: ${runtime.authPolicy.mode}`,
-  });
-
-  return results;
-}
-
-export function registerDoctorChecks(health: HealthRegistry, runtime: AgentRuntime): void {
-  const results = runDoctorChecks(runtime);
-  for (const r of results) {
-    health.register(
-      r.check,
-      r.status === 'pass' ? 'healthy' : r.status === 'warn' ? 'degraded' : 'down',
-    );
-    if (r.status !== 'pass') {
-      health.update(r.check, r.status === 'warn' ? 'degraded' : 'down', r.message);
-    }
-  }
-}

package/src/persistence/postgres-provider.ts

@@ -1,310 +0,0 @@
-/**
- * PostgreSQL persistence provider.
- *
- * Implements PersistenceProvider with pg.Pool. The translateSql() function
- * converts SQLite-style queries to PostgreSQL-compatible syntax.
- *
- * Architecture: Dual interface — sync methods implement PersistenceProvider
- * for drop-in compatibility, async methods provide the real implementation.
- *
- * Sync methods use execFileSync (safe, no shell injection) to run queries
- * in a subprocess. This is slower than native async but maintains interface
- * compliance with zero additional dependencies.
- *
- * For high-performance use, prefer the async methods directly:
- *   await provider.queryAsync(sql, params)
- *   await provider.runAsync(sql, params)
- */
-
-import { execFileSync } from 'node:child_process';
-import type {
-  PersistenceProvider,
-  PersistenceParams,
-  RunResult,
-  FtsSearchOptions,
-} from './types.js';
-
-// =============================================================================
-// SQL TRANSLATION
-// =============================================================================
-
-/**
- * Translate SQLite-style SQL to PostgreSQL-compatible SQL.
- *
- * - Converts positional `?` params to `$1, $2, ...`
- * - Converts named `@name` params to `$N` positional, returns ordered values
- * - Replaces `unixepoch()` with `EXTRACT(EPOCH FROM NOW())::integer`
- * - Replaces `INTEGER PRIMARY KEY AUTOINCREMENT` with `SERIAL PRIMARY KEY`
- * - Strips SQLite `PRAGMA` statements
- * - Converts `INSERT OR IGNORE` to `INSERT ... ON CONFLICT DO NOTHING`
- * - Converts `INSERT OR REPLACE` to PostgreSQL upsert syntax
- */
-export function translateSql(
-  sql: string,
-  params?: PersistenceParams,
-): { sql: string; values: unknown[] } {
-  let translated = sql
-    .replace(/unixepoch\(\)/gi, 'EXTRACT(EPOCH FROM NOW())::integer')
-    .replace(/INTEGER\s+PRIMARY\s+KEY\s+AUTOINCREMENT/gi, 'SERIAL PRIMARY KEY')
-    .replace(/PRAGMA\s+[^;]+;?/gi, '-- pragma removed')
-    .replace(/INSERT\s+OR\s+IGNORE/gi, 'INSERT')
-    .replace(/INSERT\s+OR\s+REPLACE/gi, 'INSERT');
-
-  if (!params) return { sql: translated, values: [] };
-
-  if (Array.isArray(params)) {
-    let idx = 0;
-    translated = translated.replace(/\?/g, () => `$${++idx}`);
-    return { sql: translated, values: params };
-  }
-
-  // Named params: @name -> $N
-  const values: unknown[] = [];
-  const nameMap = new Map<string, number>();
-  translated = translated.replace(/@(\w+)/g, (_match, name: string) => {
-    if (!nameMap.has(name)) {
-      nameMap.set(name, values.length + 1);
-      values.push(params[name]);
-    }
-    return `$${nameMap.get(name)}`;
-  });
-  return { sql: translated, values };
-}
-
-// =============================================================================
-// POSTGRESQL PROVIDER
-// =============================================================================
-
-/**
- * PostgreSQL persistence provider.
- *
- * Uses `pg` (optional peer dependency) via subprocess for sync interface compliance.
- * Created via async factory `PostgresPersistenceProvider.create()`.
- *
- * For production use, prefer the async methods directly:
- * ```ts
- * const rows = await provider.queryAsync('SELECT * FROM entries WHERE domain = $1', ['design']);
- * ```
- */
-export class PostgresPersistenceProvider implements PersistenceProvider {
-  readonly backend = 'postgres' as const;
-  private connectionString: string;
-  private pool: unknown = null;
-  private inTransaction = false;
-
-  private constructor(connectionString: string) {
-    this.connectionString = connectionString;
-  }
-
-  /**
-   * Async factory. Dynamically imports `pg` (optional dependency).
-   * Verifies connection before returning.
-   */
-  static async create(
-    connectionString: string,
-    poolSize = 10,
-  ): Promise<PostgresPersistenceProvider> {
-    const provider = new PostgresPersistenceProvider(connectionString);
-
-    // Dynamically import pg and create pool
-    const { default: pg } = await import('pg');
-    provider.pool = new pg.Pool({
-      connectionString,
-      max: poolSize,
-      idleTimeoutMillis: 30_000,
-    });
-
-    // Verify connection
-    const client = await (
-      provider.pool as {
-        connect(): Promise<{ release(): void; query(s: string): Promise<unknown> }>;
-      }
-    ).connect();
-    await client.query('SELECT 1');
-    client.release();
-
-    return provider;
-  }
-
-  /**
-   * Create a provider for sync-only use (no pg pool needed).
-   * Uses subprocess execution for all queries.
-   */
-  static createSync(connectionString: string): PostgresPersistenceProvider {
-    return new PostgresPersistenceProvider(connectionString);
-  }
-
-  // ─── Async methods (preferred for performance) ─────────
-
-  /**
-   * Execute a query asynchronously. Returns rows.
-   */
-  async queryAsync<T = Record<string, unknown>>(sql: string, values?: unknown[]): Promise<T[]> {
-    if (!this.pool)
-      throw new Error('Pool not initialized. Use PostgresPersistenceProvider.create()');
-    const result = await (
-      this.pool as { query(s: string, v?: unknown[]): Promise<{ rows: T[] }> }
-    ).query(sql, values);
-    return result.rows;
-  }
-
-  /**
-   * Execute a command asynchronously. Returns row count.
-   */
-  async runAsync(sql: string, values?: unknown[]): Promise<number> {
-    if (!this.pool)
-      throw new Error('Pool not initialized. Use PostgresPersistenceProvider.create()');
-    const result = await (
-      this.pool as { query(s: string, v?: unknown[]): Promise<{ rowCount: number }> }
-    ).query(sql, values);
-    return result.rowCount ?? 0;
-  }
-
-  // ─── Sync PersistenceProvider interface ─────────────────
-  // Uses execFileSync subprocess bridge for sync compliance.
-  // Safe: execFileSync does not use shell (no injection risk).
-
-  execSql(sql: string): void {
-    const statements = sql
-      .split(';')
-      .map((s) => s.trim())
-      .filter((s) => s.length > 0 && !s.startsWith('--'));
-
-    for (const stmt of statements) {
-      const { sql: pgSql } = translateSql(stmt);
-      if (pgSql.includes('CREATE VIRTUAL TABLE') || pgSql.includes('CREATE TRIGGER')) continue;
-      if (pgSql.trim().startsWith('--')) continue;
-      this.execSyncQuery(pgSql);
-    }
-  }
-
-  run(sql: string, params?: PersistenceParams): RunResult {
-    const { sql: pgSql, values } = translateSql(sql, params);
-    const result = this.execSyncQuery(pgSql, values);
-    return {
-      changes: result.rowCount ?? 0,
-      lastInsertRowid: 0,
-    };
-  }
-
-  get<T = Record<string, unknown>>(sql: string, params?: PersistenceParams): T | undefined {
-    const { sql: pgSql, values } = translateSql(sql, params);
-    const result = this.execSyncQuery(pgSql, values);
-    return result.rows?.[0] as T | undefined;
-  }
-
-  all<T = Record<string, unknown>>(sql: string, params?: PersistenceParams): T[] {
-    const { sql: pgSql, values } = translateSql(sql, params);
-    const result = this.execSyncQuery(pgSql, values);
-    return (result.rows ?? []) as T[];
-  }
-
-  transaction<T>(fn: () => T): T {
-    this.execSyncQuery('BEGIN');
-    this.inTransaction = true;
-    try {
-      const result = fn();
-      this.execSyncQuery('COMMIT');
-      this.inTransaction = false;
-      return result;
-    } catch (err) {
-      this.execSyncQuery('ROLLBACK');
-      this.inTransaction = false;
-      throw err;
-    }
-  }
-
-  ftsSearch<T = Record<string, unknown>>(
-    table: string,
-    query: string,
-    options?: FtsSearchOptions,
-  ): T[] {
-    const limit = options?.limit ?? 50;
-    const offset = options?.offset ?? 0;
-    const filters = options?.filters ?? {};
-    const values: unknown[] = [query];
-    let paramIdx = 2;
-
-    const filterClauses: string[] = [];
-    for (const [key, value] of Object.entries(filters)) {
-      filterClauses.push(`${key} = $${paramIdx}`);
-      values.push(value);
-      paramIdx++;
-    }
-
-    const whereExtra = filterClauses.length > 0 ? `AND ${filterClauses.join(' AND ')}` : '';
-    const orderClause =
-      options?.orderByRank !== false
-        ? "ORDER BY ts_rank(to_tsvector('english', COALESCE(title,'') || ' ' || COALESCE(description,'')), plainto_tsquery('english', $1)) DESC"
-        : '';
-
-    const sql = `SELECT * FROM ${table} WHERE to_tsvector('english', COALESCE(title,'') || ' ' || COALESCE(description,'')) @@ plainto_tsquery('english', $1) ${whereExtra} ${orderClause} LIMIT $${paramIdx} OFFSET $${paramIdx + 1}`;
-    values.push(limit, offset);
-
-    const result = this.execSyncQuery(sql, values);
-    return (result.rows ?? []) as T[];
-  }
-
-  ftsRebuild(_table: string): void {
-    // PostgreSQL GIN indexes are maintained automatically
-  }
-
-  close(): void {
-    if (this.pool) {
-      void (this.pool as { end(): Promise<void> }).end();
-      this.pool = null;
-    }
-  }
-
-  /** Get the connection string (for diagnostics). */
-  getConnectionString(): string {
-    return this.connectionString;
-  }
-
-  // ─── Sync subprocess bridge ────────────────────────────
-  // Uses execFileSync (no shell, safe from injection).
-  // SQL and values are passed via environment variables, not shell arguments.
-
-  private execSyncQuery(sql: string, values?: unknown[]): { rows: unknown[]; rowCount: number } {
-    // Build a Node.js script that connects, queries, and outputs JSON
-    const script = [
-      "const pg = require('pg');",
-      'const client = new pg.Client({ connectionString: process.env.PG_CONN });',
-      '(async () => {',
-      '  await client.connect();',
-      '  try {',
-      '    const result = await client.query(',
-      `      ${JSON.stringify(sql)},`,
-      "      JSON.parse(process.env.PG_VALUES || '[]')",
-      '    );',
-      '    process.stdout.write(JSON.stringify({',
-      '      rows: result.rows || [],',
-      '      rowCount: result.rowCount || 0',
-      '    }));',
-      '  } finally {',
-      '    await client.end();',
-      '  }',
-      '})().catch(err => {',
-      '  process.stderr.write(err.message);',
-      '  process.exit(1);',
-      '});',
-    ].join('\n');
-
-    try {
-      // execFileSync with array args — no shell, safe from injection
-      const output = execFileSync('node', ['-e', script], {
-        encoding: 'utf-8',
-        timeout: 30_000,
-        env: {
-          ...process.env,
-          PG_CONN: this.connectionString,
-          PG_VALUES: JSON.stringify(values ?? []),
-        },
-      });
-      return JSON.parse(output || '{"rows":[],"rowCount":0}');
-    } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err);
-      throw new Error(`PostgreSQL query failed: ${msg}`, { cause: err });
-    }
-  }
-}