@soleri/core 2.10.0 → 2.11.0

package/src/vault/vault-branching.ts

@@ -0,0 +1,264 @@
+/**
+ * Vault Branching — experiment with knowledge changes on named branches
+ * before merging to the main vault.
+ *
+ * Each branch tracks a set of operations (add/modify/remove) against vault entries.
+ * On merge, all operations are applied atomically to the main vault.
+ * Conflict resolution: branch entry wins (explicit user action to merge).
+ *
+ * Improved over Salvador: uses PersistenceProvider abstraction, separate
+ * metadata table (no sentinel markers), and merge logic built-in.
+ */
+
+import type { PersistenceProvider } from '../persistence/types.js';
+import type { IntelligenceEntry } from '../intelligence/types.js';
+import type { Vault } from './vault.js';
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+export type BranchAction = 'add' | 'modify' | 'remove';
+
+export interface BranchEntry {
+  id: number;
+  branchName: string;
+  entryId: string;
+  action: BranchAction;
+  entryData: IntelligenceEntry | null;
+  createdAt: number;
+}
+
+export interface BranchSummary {
+  name: string;
+  entryCount: number;
+  createdAt: number;
+  merged: boolean;
+}
+
+export interface MergeResult {
+  merged: boolean;
+  branchName: string;
+  added: number;
+  modified: number;
+  removed: number;
+  total: number;
+}
+
+// =============================================================================
+// VAULT BRANCHING
+// =============================================================================
+
+export class VaultBranching {
+  private provider: PersistenceProvider;
+  private vault: Vault;
+
+  constructor(vault: Vault) {
+    this.vault = vault;
+    this.provider = vault.getProvider();
+    this.initialize();
+  }
+
+  private initialize(): void {
+    this.provider.execSql(`
+      CREATE TABLE IF NOT EXISTS vault_branch_meta (
+        name TEXT PRIMARY KEY,
+        created_at INTEGER NOT NULL DEFAULT (unixepoch()),
+        merged_at INTEGER
+      );
+      CREATE TABLE IF NOT EXISTS vault_branch_ops (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        branch_name TEXT NOT NULL REFERENCES vault_branch_meta(name),
+        entry_id TEXT NOT NULL,
+        action TEXT NOT NULL CHECK(action IN ('add', 'modify', 'remove')),
+        entry_data TEXT,
+        created_at INTEGER NOT NULL DEFAULT (unixepoch())
+      );
+      CREATE INDEX IF NOT EXISTS idx_branch_ops_name ON vault_branch_ops(branch_name);
+    `);
+  }
+
+  /**
+   * Create a new branch. Name must be unique among active (unmerged) branches.
+   */
+  branch(name: string): boolean {
+    const existing = this.provider.get<{ name: string; merged_at: number | null }>(
+      'SELECT name, merged_at FROM vault_branch_meta WHERE name = @name',
+      { name },
+    );
+    if (existing && existing.merged_at === null) {
+      throw new Error(`Branch '${name}' already exists`);
+    }
+    // Allow reuse of merged branch names — delete old record first
+    if (existing) {
+      this.provider.run('DELETE FROM vault_branch_ops WHERE branch_name = @name', { name });
+      this.provider.run('DELETE FROM vault_branch_meta WHERE name = @name', { name });
+    }
+    this.provider.run('INSERT INTO vault_branch_meta (name) VALUES (@name)', { name });
+    return true;
+  }
+
+  /**
+   * Add an operation to a branch.
+   * For 'add' and 'modify', entryData is required.
+   * For 'remove', entryData is optional.
+   */
+  addOperation(
+    branchName: string,
+    entryId: string,
+    action: BranchAction,
+    entryData?: IntelligenceEntry,
+  ): void {
+    this.assertActiveBranch(branchName);
+    if ((action === 'add' || action === 'modify') && !entryData) {
+      throw new Error(`Entry data required for '${action}' action`);
+    }
+    this.provider.run(
+      `INSERT INTO vault_branch_ops (branch_name, entry_id, action, entry_data)
+       VALUES (@branchName, @entryId, @action, @entryData)`,
+      {
+        branchName,
+        entryId,
+        action,
+        entryData: entryData ? JSON.stringify(entryData) : null,
+      },
+    );
+  }
+
+  /**
+   * List entries on a branch.
+   */
+  listEntries(branchName: string): BranchEntry[] {
+    const rows = this.provider.all<{
+      id: number;
+      branch_name: string;
+      entry_id: string;
+      action: string;
+      entry_data: string | null;
+      created_at: number;
+    }>(
+      `SELECT id, branch_name, entry_id, action, entry_data, created_at
+       FROM vault_branch_ops WHERE branch_name = @branchName
+       ORDER BY created_at ASC`,
+      { branchName },
+    );
+    return rows.map((r) => ({
+      id: r.id,
+      branchName: r.branch_name,
+      entryId: r.entry_id,
+      action: r.action as BranchAction,
+      entryData: r.entry_data ? (JSON.parse(r.entry_data) as IntelligenceEntry) : null,
+      createdAt: r.created_at,
+    }));
+  }
+
+  /**
+   * List all branches with summary info.
+   */
+  listBranches(): BranchSummary[] {
+    const rows = this.provider.all<{
+      name: string;
+      created_at: number;
+      merged_at: number | null;
+      entry_count: number;
+    }>(
+      `SELECT m.name, m.created_at, m.merged_at,
+              COALESCE(COUNT(o.id), 0) as entry_count
+       FROM vault_branch_meta m
+       LEFT JOIN vault_branch_ops o ON o.branch_name = m.name
+       GROUP BY m.name
+       ORDER BY m.created_at DESC`,
+    );
+    return rows.map((r) => ({
+      name: r.name,
+      entryCount: r.entry_count,
+      createdAt: r.created_at,
+      merged: r.merged_at !== null,
+    }));
+  }
+
+  /**
+   * Merge a branch into the main vault. Applies all operations atomically.
+   * Conflict resolution: branch entry wins (the user explicitly chose to merge).
+   */
+  merge(branchName: string): MergeResult {
+    this.assertActiveBranch(branchName);
+    const ops = this.listEntries(branchName);
+
+    // Collapse ops: for each entryId, only the last action matters
+    const collapsed = new Map<string, BranchEntry>();
+    for (const op of ops) {
+      collapsed.set(op.entryId, op);
+    }
+
+    let added = 0;
+    let modified = 0;
+    let removed = 0;
+
+    this.provider.transaction(() => {
+      for (const op of collapsed.values()) {
+        switch (op.action) {
+          case 'add':
+            if (op.entryData) {
+              this.vault.add(op.entryData);
+              added++;
+            }
+            break;
+          case 'modify':
+            if (op.entryData) {
+              // Branch wins: upsert via seed (INSERT OR REPLACE)
+              this.vault.add(op.entryData);
+              modified++;
+            }
+            break;
+          case 'remove':
+            this.vault.remove(op.entryId);
+            removed++;
+            break;
+        }
+      }
+      // Mark branch as merged
+      this.provider.run(
+        'UPDATE vault_branch_meta SET merged_at = unixepoch() WHERE name = @branchName',
+        { branchName },
+      );
+    });
+
+    return {
+      merged: true,
+      branchName,
+      added,
+      modified,
+      removed,
+      total: added + modified + removed,
+    };
+  }
+
+  /**
+   * Delete a branch and all its operations.
+   */
+  deleteBranch(branchName: string): boolean {
+    const existing = this.provider.get<{ name: string }>(
+      'SELECT name FROM vault_branch_meta WHERE name = @branchName',
+      { branchName },
+    );
+    if (!existing) return false;
+
+    this.provider.transaction(() => {
+      this.provider.run('DELETE FROM vault_branch_ops WHERE branch_name = @branchName', {
+        branchName,
+      });
+      this.provider.run('DELETE FROM vault_branch_meta WHERE name = @branchName', { branchName });
+    });
+    return true;
+  }
+
+  private assertActiveBranch(name: string): void {
+    const branch = this.provider.get<{ merged_at: number | null }>(
+      'SELECT merged_at FROM vault_branch_meta WHERE name = @name',
+      { name },
+    );
+    if (!branch) throw new Error(`Branch '${name}' does not exist`);
+    if (branch.merged_at !== null) throw new Error(`Branch '${name}' is already merged`);
+  }
+}

package/src/vault/vault-manager.ts

@@ -0,0 +1,237 @@
+/**
+ * VaultManager — orchestrates multiple vault instances across tiers.
+ *
+ * Each tier (agent, project, team) is a separate SQLite database with its own
+ * FTS5 index. Search cascades across all connected tiers with priority weighting.
+ *
+ * Usage:
+ *   const mgr = new VaultManager({ agentId: 'my-agent' });
+ *   mgr.open('agent', '~/.my-agent/vault.db');
+ *   mgr.open('project', '.soleri/vault.db');
+ *   const results = mgr.search('pattern name');
+ *   mgr.close();
+ */
+
+import { Vault, type SearchResult } from './vault.js';
+import {
+  TIER_WEIGHTS,
+  type VaultTier,
+  type VaultTierInfo,
+  type VaultManagerConfig,
+} from './vault-types.js';
+
+// =============================================================================
+// VAULT MANAGER
+// =============================================================================
+
+/** A dynamically connected vault source with a name and priority. */
+export interface ConnectedVault {
+  name: string;
+  path: string;
+  priority: number;
+  vault: Vault;
+}
+
+export class VaultManager {
+  private vaults = new Map<VaultTier, { vault: Vault; path: string }>();
+  private connected = new Map<string, ConnectedVault>();
+  private weights: Record<VaultTier, number>;
+  private config: VaultManagerConfig;
+
+  constructor(config: VaultManagerConfig) {
+    this.config = config;
+    this.weights = {
+      ...TIER_WEIGHTS,
+      ...config.weights,
+    };
+  }
+
+  /**
+   * Open a vault for the given tier.
+   * If a vault is already open for this tier, it is closed first.
+   */
+  open(tier: VaultTier, path: string): Vault {
+    // Close existing if re-opening
+    const existing = this.vaults.get(tier);
+    if (existing) {
+      existing.vault.close();
+    }
+
+    const vault = new Vault(path);
+    this.vaults.set(tier, { vault, path });
+    return vault;
+  }
+
+  /**
+   * Get the vault for a specific tier.
+   * Throws if not connected.
+   */
+  getTier(tier: VaultTier): Vault {
+    const entry = this.vaults.get(tier);
+    if (!entry) {
+      throw new Error(`Vault tier '${tier}' is not connected`);
+    }
+    return entry.vault;
+  }
+
+  /**
+   * Check if a tier is connected.
+   */
+  hasTier(tier: VaultTier): boolean {
+    return this.vaults.has(tier);
+  }
+
+  /**
+   * Disconnect a specific tier.
+   */
+  disconnect(tier: VaultTier): boolean {
+    const entry = this.vaults.get(tier);
+    if (!entry) return false;
+    entry.vault.close();
+    this.vaults.delete(tier);
+    return true;
+  }
+
+  // ─── Dynamic Named Connections ──────────────────────────────────────
+
+  /**
+   * Connect a named vault source with a configurable priority.
+   * Throws if a vault with this name is already connected.
+   */
+  connect(name: string, path: string, priority = 0.5): ConnectedVault {
+    if (this.connected.has(name)) {
+      throw new Error(`Vault '${name}' is already connected`);
+    }
+    const vault = new Vault(path);
+    const entry: ConnectedVault = { name, path, priority, vault };
+    this.connected.set(name, entry);
+    return entry;
+  }
+
+  /**
+   * Disconnect a named vault source.
+   * Throws if not connected.
+   */
+  disconnectNamed(name: string): boolean {
+    const entry = this.connected.get(name);
+    if (!entry) return false;
+    entry.vault.close();
+    this.connected.delete(name);
+    return true;
+  }
+
+  /**
+   * List all dynamically connected vaults, sorted by priority descending.
+   */
+  listConnected(): Array<{ name: string; path: string; priority: number }> {
+    return Array.from(this.connected.values())
+      .sort((a, b) => b.priority - a.priority)
+      .map(({ name, path, priority }) => ({ name, path, priority }));
+  }
+
+  /**
+   * Get a named connected vault.
+   */
+  getConnected(name: string): ConnectedVault | undefined {
+    return this.connected.get(name);
+  }
+
+  // ─── Search ────────────────────────────────────────────────────────
+
+  /**
+   * Search across all connected tiers AND named vaults with priority weighting.
+   *
+   * Results from each source are weighted by priority,
+   * then merged and deduplicated (highest-priority entry wins).
+   */
+  search(query: string, limit = 20): SearchResult[] {
+    const allResults: Array<SearchResult & { source: string; weightedScore: number }> = [];
+
+    // Tier vaults
+    for (const [tier, { vault }] of this.vaults) {
+      const weight = this.weights[tier];
+      const results = vault.search(query);
+      for (const r of results) {
+        allResults.push({
+          ...r,
+          source: tier,
+          weightedScore: r.score * weight,
+        });
+      }
+    }
+
+    // Named connected vaults
+    for (const { name, priority, vault } of this.connected.values()) {
+      const results = vault.search(query);
+      for (const r of results) {
+        allResults.push({
+          ...r,
+          source: name,
+          weightedScore: r.score * priority,
+        });
+      }
+    }
+
+    // Deduplicate: keep highest-weighted version of each entry
+    const seen = new Map<string, (typeof allResults)[number]>();
+    for (const r of allResults) {
+      const existing = seen.get(r.entry.id);
+      if (!existing || r.weightedScore > existing.weightedScore) {
+        seen.set(r.entry.id, r);
+      }
+    }
+
+    // Sort by weighted score descending, take top N
+    const merged = Array.from(seen.values());
+    merged.sort((a, b) => b.weightedScore - a.weightedScore);
+
+    return merged.slice(0, limit).map((r) => ({
+      entry: r.entry,
+      score: r.weightedScore,
+    }));
+  }
+
+  /**
+   * Get info about all tiers (connected or not).
+   */
+  listTiers(): VaultTierInfo[] {
+    const allTiers: VaultTier[] = ['agent', 'project', 'team'];
+    return allTiers.map((tier) => {
+      const entry = this.vaults.get(tier);
+      if (!entry) {
+        return { tier, path: '', connected: false, entryCount: 0 };
+      }
+      const stats = entry.vault.stats();
+      return {
+        tier,
+        path: entry.path,
+        connected: true,
+        entryCount: stats.totalEntries,
+      };
+    });
+  }
+
+  /** Number of connected tiers. */
+  get size(): number {
+    return this.vaults.size;
+  }
+
+  /** Get the underlying config. */
+  getConfig(): VaultManagerConfig {
+    return this.config;
+  }
+
+  /**
+   * Close all connected vaults.
+   */
+  close(): void {
+    for (const { vault } of this.vaults.values()) {
+      vault.close();
+    }
+    this.vaults.clear();
+    for (const { vault } of this.connected.values()) {
+      vault.close();
+    }
+    this.connected.clear();
+  }
+}

package/src/vault/vault-types.ts

@@ -0,0 +1,50 @@
+/**
+ * Vault Types — tier definitions and multi-vault configuration.
+ */
+
+// =============================================================================
+// VAULT TIERS
+// =============================================================================
+
+/** Vault tier — determines search priority and default path. */
+export type VaultTier = 'agent' | 'project' | 'team';
+
+/** Priority weights for search result merging (higher = ranked first). */
+export const TIER_WEIGHTS: Record<VaultTier, number> = {
+  agent: 1.0,
+  project: 0.8,
+  team: 0.6,
+};
+
+// =============================================================================
+// VAULT MANAGER CONFIG
+// =============================================================================
+
+/** Configuration for a single vault tier. */
+export interface VaultTierConfig {
+  tier: VaultTier;
+  /** Path to the SQLite database file. */
+  path: string;
+}
+
+/** Configuration for VaultManager. */
+export interface VaultManagerConfig {
+  /** Agent identifier (used for default path: ~/.{agentId}/vault.db) */
+  agentId: string;
+  /** Override default paths per tier. */
+  tiers?: VaultTierConfig[];
+  /** Custom priority weights (overrides TIER_WEIGHTS). */
+  weights?: Partial<Record<VaultTier, number>>;
+}
+
+// =============================================================================
+// VAULT TIER INFO
+// =============================================================================
+
+/** Runtime info about a connected vault tier. */
+export interface VaultTierInfo {
+  tier: VaultTier;
+  path: string;
+  connected: boolean;
+  entryCount: number;
+}

package/src/vault/vault.ts

@@ -179,6 +179,18 @@ export class Vault {
     this.migrateBrainSchema();
     this.migrateTemporalSchema();
     this.migrateContentHash();
+    this.migrateTierColumn();
+  }
+
+  private migrateTierColumn(): void {
+    try {
+      this.provider.run("ALTER TABLE entries ADD COLUMN tier TEXT DEFAULT 'agent'");
+    } catch {
+      // Column already exists
+    }
+    this.provider.execSql(
+      'CREATE INDEX IF NOT EXISTS idx_entries_tier ON entries(tier) WHERE tier IS NOT NULL',
+    );
   }
 
   private migrateTemporalSchema(): void {
@@ -281,12 +293,12 @@ export class Vault {
 
   seed(entries: IntelligenceEntry[]): number {
     const sql = `
-      INSERT INTO entries (id,type,domain,title,severity,description,context,example,counter_example,why,tags,applies_to,valid_from,valid_until,content_hash)
-      VALUES (@id,@type,@domain,@title,@severity,@description,@context,@example,@counterExample,@why,@tags,@appliesTo,@validFrom,@validUntil,@contentHash)
+      INSERT INTO entries (id,type,domain,title,severity,description,context,example,counter_example,why,tags,applies_to,valid_from,valid_until,content_hash,tier)
+      VALUES (@id,@type,@domain,@title,@severity,@description,@context,@example,@counterExample,@why,@tags,@appliesTo,@validFrom,@validUntil,@contentHash,@tier)
       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,valid_from=excluded.valid_from,valid_until=excluded.valid_until,
-        content_hash=excluded.content_hash,updated_at=unixepoch()
+        content_hash=excluded.content_hash,tier=excluded.tier,updated_at=unixepoch()
     `;
     return this.provider.transaction(() => {
       let count = 0;
@@ -307,6 +319,7 @@ export class Vault {
           validFrom: entry.validFrom ?? null,
           validUntil: entry.validUntil ?? null,
           contentHash: computeContentHash(entry),
+          tier: entry.tier ?? 'agent',
         });
         count++;
         if (this.syncManager) {
@@ -317,6 +330,30 @@ export class Vault {
     });
   }
 
+  /**
+   * Seed entries with content-hash dedup. Returns per-entry results.
+   * Unlike seed(), skips entries whose content already exists in the vault.
+   */
+  seedDedup(
+    entries: IntelligenceEntry[],
+  ): Array<{ id: string; action: 'inserted' | 'duplicate'; existingId?: string }> {
+    return this.provider.transaction(() => {
+      const results: Array<{ id: string; action: 'inserted' | 'duplicate'; existingId?: string }> =
+        [];
+      for (const entry of entries) {
+        const hash = computeContentHash(entry);
+        const existing = this.findByContentHash(hash);
+        if (existing && existing !== entry.id) {
+          results.push({ id: entry.id, action: 'duplicate', existingId: existing });
+        } else {
+          this.seed([entry]);
+          results.push({ id: entry.id, action: 'inserted' });
+        }
+      }
+      return results;
+    });
+  }
+
   search(
     query: string,
     options?: {
@@ -1095,6 +1132,7 @@ function rowToEntry(row: Record<string, unknown>): IntelligenceEntry {
     why: (row.why as string) ?? undefined,
     tags: JSON.parse((row.tags as string) || '[]'),
     appliesTo: JSON.parse((row.applies_to as string) || '[]'),
+    tier: (row.tier as IntelligenceEntry['tier']) ?? undefined,
     validFrom: (row.valid_from as number) ?? undefined,
     validUntil: (row.valid_until as number) ?? undefined,
   };

package/src/governance/index.ts

@@ -1,18 +0,0 @@
-export { Governance } from './governance.js';
-export type {
-  PolicyType,
-  PolicyPreset,
-  PolicyAction,
-  QuotaPolicy,
-  RetentionPolicy,
-  AutoCapturePolicy,
-  VaultPolicy,
-  QuotaStatus,
-  PolicyDecision,
-  BatchDecision,
-  PolicyAuditEntry,
-  ProposalStatus,
-  Proposal,
-  ProposalStats,
-  GovernanceDashboard,
-} from './types.js';