@soleri/core 9.0.3 → 9.2.0

package/src/vault/vault-branching.test.ts

@@ -0,0 +1,250 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { VaultBranching } from './vault-branching.js';
+import type { PersistenceProvider, RunResult } from '../persistence/types.js';
+import type { IntelligenceEntry } from '../intelligence/types.js';
+
+// ─── In-memory mock persistence ──────────────────────────────────────
+
+function makeEntry(id: string): IntelligenceEntry {
+  return {
+    id,
+    type: 'pattern',
+    domain: 'test',
+    title: `Entry ${id}`,
+    severity: 'suggestion',
+    description: `Description for ${id}`,
+    tags: ['test'],
+  };
+}
+
+class BranchingMockDB implements PersistenceProvider {
+  readonly backend = 'sqlite' as const;
+  private meta: Array<{ name: string; created_at: number; merged_at: number | null }> = [];
+  private ops: Array<{
+    id: number;
+    branch_name: string;
+    entry_id: string;
+    action: string;
+    entry_data: string | null;
+    created_at: number;
+  }> = [];
+  private nextId = 1;
+
+  execSql(): void {}
+
+  run(sql: string, params?: Record<string, unknown> | unknown[]): RunResult {
+    const p = this.norm(params);
+
+    if (sql.includes('INSERT INTO vault_branch_meta')) {
+      this.meta.push({ name: p.name as string, created_at: Date.now(), merged_at: null });
+      return { changes: 1, lastInsertRowid: this.meta.length };
+    }
+    if (sql.includes('INSERT INTO vault_branch_ops')) {
+      this.ops.push({
+        id: this.nextId++,
+        branch_name: p.branchName as string,
+        entry_id: p.entryId as string,
+        action: p.action as string,
+        entry_data: (p.entryData as string) ?? null,
+        created_at: Date.now(),
+      });
+      return { changes: 1, lastInsertRowid: this.nextId - 1 };
+    }
+    if (sql.includes('UPDATE vault_branch_meta SET merged_at')) {
+      const m = this.meta.find((r) => r.name === p.branchName);
+      if (m) m.merged_at = Date.now();
+      return { changes: 1, lastInsertRowid: 0 };
+    }
+    if (sql.includes('DELETE FROM vault_branch_ops')) {
+      const name = (p.branchName ?? p.name) as string;
+      const before = this.ops.length;
+      this.ops = this.ops.filter((o) => o.branch_name !== name);
+      return { changes: before - this.ops.length, lastInsertRowid: 0 };
+    }
+    if (sql.includes('DELETE FROM vault_branch_meta')) {
+      const name = (p.branchName ?? p.name) as string;
+      const before = this.meta.length;
+      this.meta = this.meta.filter((m) => m.name !== name);
+      return { changes: before - this.meta.length, lastInsertRowid: 0 };
+    }
+    return { changes: 0, lastInsertRowid: 0 };
+  }
+
+  get<T>(sql: string, params?: Record<string, unknown> | unknown[]): T | undefined {
+    const p = this.norm(params);
+    const name = (p.name ?? p.branchName) as string;
+    if (sql.includes('vault_branch_meta')) {
+      const m = this.meta.find((r) => r.name === name);
+      return m as T | undefined;
+    }
+    return undefined;
+  }
+
+  all<T>(sql: string, params?: Record<string, unknown> | unknown[]): T[] {
+    const p = this.norm(params);
+    if (sql.includes('vault_branch_ops') && p.branchName) {
+      return this.ops.filter((o) => o.branch_name === p.branchName) as T[];
+    }
+    if (sql.includes('vault_branch_meta')) {
+      return this.meta.map((m) => ({
+        ...m,
+        entry_count: this.ops.filter((o) => o.branch_name === m.name).length,
+      })) as T[];
+    }
+    return [];
+  }
+
+  transaction<T>(fn: () => T): T {
+    return fn();
+  }
+
+  ftsSearch<T>(): T[] { return []; }
+  ftsRebuild(): void {}
+  close(): void {}
+
+  private norm(params?: Record<string, unknown> | unknown[]): Record<string, unknown> {
+    if (!params || Array.isArray(params)) return {};
+    return params;
+  }
+}
+
+// ─── Mock Vault facade ───────────────────────────────────────────────
+
+function makeMockVault(provider: BranchingMockDB) {
+  return {
+    getProvider: () => provider,
+    add: vi.fn(),
+    remove: vi.fn(),
+  } as unknown;
+}
+
+describe('VaultBranching', () => {
+  let db: BranchingMockDB;
+  let branching: VaultBranching;
+
+  beforeEach(() => {
+    db = new BranchingMockDB();
+    branching = new VaultBranching(makeMockVault(db));
+  });
+
+  // ── branch ──────────────────────────────────────────────────────────
+
+  it('creates a new branch', () => {
+    expect(branching.branch('feature-x')).toBe(true);
+  });
+
+  it('throws when creating duplicate active branch', () => {
+    branching.branch('feature-x');
+    expect(() => branching.branch('feature-x')).toThrow("already exists");
+  });
+
+  // ── addOperation ────────────────────────────────────────────────────
+
+  it('adds an add operation with entry data', () => {
+    branching.branch('b1');
+    branching.addOperation('b1', 'e1', 'add', makeEntry('e1'));
+    const ops = branching.listEntries('b1');
+    expect(ops).toHaveLength(1);
+    expect(ops[0].action).toBe('add');
+    expect(ops[0].entryId).toBe('e1');
+  });
+
+  it('adds a remove operation without entry data', () => {
+    branching.branch('b1');
+    branching.addOperation('b1', 'e1', 'remove');
+    const ops = branching.listEntries('b1');
+    expect(ops).toHaveLength(1);
+    expect(ops[0].action).toBe('remove');
+  });
+
+  it('throws when adding to non-existent branch', () => {
+    expect(() => branching.addOperation('missing', 'e1', 'add', makeEntry('e1'))).toThrow(
+      "does not exist",
+    );
+  });
+
+  it('throws when add/modify has no entry data', () => {
+    branching.branch('b1');
+    expect(() => branching.addOperation('b1', 'e1', 'add')).toThrow("Entry data required");
+    expect(() => branching.addOperation('b1', 'e1', 'modify')).toThrow("Entry data required");
+  });
+
+  // ── listEntries ─────────────────────────────────────────────────────
+
+  it('returns empty list for branch with no ops', () => {
+    branching.branch('b1');
+    expect(branching.listEntries('b1')).toEqual([]);
+  });
+
+  // ── listBranches ────────────────────────────────────────────────────
+
+  it('lists all branches with summary info', () => {
+    branching.branch('b1');
+    branching.branch('b2');
+    branching.addOperation('b1', 'e1', 'add', makeEntry('e1'));
+    const branches = branching.listBranches();
+    expect(branches).toHaveLength(2);
+    const b1 = branches.find((b) => b.name === 'b1');
+    expect(b1!.entryCount).toBe(1);
+    expect(b1!.merged).toBe(false);
+  });
+
+  // ── merge ───────────────────────────────────────────────────────────
+
+  it('merges a branch applying add operations', () => {
+    const mockVault = makeMockVault(db);
+    branching = new VaultBranching(mockVault);
+    branching.branch('b1');
+    branching.addOperation('b1', 'e1', 'add', makeEntry('e1'));
+    const result = branching.merge('b1');
+    expect(result.merged).toBe(true);
+    expect(result.added).toBe(1);
+    expect(result.total).toBe(1);
+    expect(mockVault.add).toHaveBeenCalled();
+  });
+
+  it('merges with remove operations', () => {
+    const mockVault = makeMockVault(db);
+    branching = new VaultBranching(mockVault);
+    branching.branch('b1');
+    branching.addOperation('b1', 'e1', 'remove');
+    const result = branching.merge('b1');
+    expect(result.removed).toBe(1);
+    expect(mockVault.remove).toHaveBeenCalledWith('e1');
+  });
+
+  it('collapses multiple ops for same entry (last wins)', () => {
+    const mockVault = makeMockVault(db);
+    branching = new VaultBranching(mockVault);
+    branching.branch('b1');
+    branching.addOperation('b1', 'e1', 'add', makeEntry('e1'));
+    branching.addOperation('b1', 'e1', 'remove');
+    const result = branching.merge('b1');
+    // Last op is remove, so add shouldn't happen on this entry
+    expect(result.removed).toBe(1);
+    expect(result.added).toBe(0);
+  });
+
+  it('throws when merging non-existent branch', () => {
+    expect(() => branching.merge('missing')).toThrow("does not exist");
+  });
+
+  it('throws when merging already-merged branch', () => {
+    branching.branch('b1');
+    branching.merge('b1');
+    expect(() => branching.merge('b1')).toThrow("already merged");
+  });
+
+  // ── deleteBranch ────────────────────────────────────────────────────
+
+  it('deletes an existing branch', () => {
+    branching.branch('b1');
+    branching.addOperation('b1', 'e1', 'add', makeEntry('e1'));
+    expect(branching.deleteBranch('b1')).toBe(true);
+    expect(branching.listBranches()).toHaveLength(0);
+  });
+
+  it('returns false when deleting non-existent branch', () => {
+    expect(branching.deleteBranch('nonexistent')).toBe(false);
+  });
+});

package/src/{__tests__ → vault}/vault-connect.test.ts

@@ -3,7 +3,7 @@
  */
 
 import { describe, test, expect, afterEach } from 'vitest';
-import { VaultManager } from '../vault/vault-manager.js';
+import { VaultManager } from './vault-manager.js';
 import type { IntelligenceEntry } from '../intelligence/types.js';
 
 function makeEntry(id: string, title: string, domain = 'general'): IntelligenceEntry {

package/src/vault/vault-entries.ts

@@ -0,0 +1,282 @@
+/**
+ * Vault entry CRUD operations — search, seed, get, update, delete, tags, etc.
+ * Extracted from vault.ts as part of Wave 0C decomposition.
+ */
+import type { PersistenceProvider } from '../persistence/types.js';
+import type { IntelligenceEntry } from '../intelligence/types.js';
+import type { LinkManager } from './linking.js';
+import { computeContentHash } from './content-hash.js';
+import type { SearchResult, VaultStats } from './vault.js';
+
+export interface AutoLinkConfig {
+  linkManager: LinkManager | null;
+  enabled: boolean;
+  maxLinks: number;
+}
+
+/** Updatable fields on an entry. */
+export type EntryUpdateFields = Partial<Pick<IntelligenceEntry,
+  'title' | 'description' | 'context' | 'example' | 'counterExample' | 'why' |
+  'tags' | 'appliesTo' | 'severity' | 'type' | 'domain' | 'validFrom' | 'validUntil'>>;
+
+/** Search/list filter options. */
+export interface EntryFilterOptions {
+  domain?: string; type?: string; severity?: string;
+  origin?: 'agent' | 'pack' | 'user'; limit?: number; includeExpired?: boolean;
+}
+
+export function autoLink(entryId: string, config: AutoLinkConfig): void {
+  if (!config.linkManager || !config.enabled) return;
+  try {
+    const suggestions = config.linkManager.suggestLinks(entryId, config.maxLinks);
+    for (const s of suggestions) {
+      config.linkManager.addLink(entryId, s.entryId, s.suggestedType, `auto: ${s.reason}`);
+    }
+  } catch { /* best-effort */ }
+}
+
+export function seed(provider: PersistenceProvider, entries: IntelligenceEntry[], alc: AutoLinkConfig): 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,tier,origin)
+    VALUES (@id,@type,@domain,@title,@severity,@description,@context,@example,@counterExample,@why,@tags,@appliesTo,@validFrom,@validUntil,@contentHash,@tier,@origin)
+    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,tier=excluded.tier,origin=excluded.origin,updated_at=unixepoch()
+  `;
+  return provider.transaction(() => {
+    let count = 0;
+    for (const entry of entries) {
+      provider.run(sql, {
+        id: entry.id, type: entry.type, domain: entry.domain, title: entry.title,
+        severity: entry.severity, description: entry.description,
+        context: entry.context ?? null, example: entry.example ?? null,
+        counterExample: entry.counterExample ?? null, why: entry.why ?? null,
+        tags: JSON.stringify(entry.tags), appliesTo: JSON.stringify(entry.appliesTo ?? []),
+        validFrom: entry.validFrom ?? null, validUntil: entry.validUntil ?? null,
+        contentHash: computeContentHash(entry), tier: entry.tier ?? 'agent', origin: entry.origin ?? 'agent',
+      });
+      count++;
+    }
+    // Auto-link after insert; skip large batches (>100) — use relink_vault for bulk imports.
+    if (entries.length <= 100) {
+      for (const entry of entries) autoLink(entry.id, alc);
+    }
+    return count;
+  });
+}
+
+export function seedDedup(
+  provider: PersistenceProvider, entries: IntelligenceEntry[], alc: AutoLinkConfig,
+): Array<{ id: string; action: 'inserted' | 'duplicate'; existingId?: string }> {
+  return provider.transaction(() => {
+    const results: Array<{ id: string; action: 'inserted' | 'duplicate'; existingId?: string }> = [];
+    for (const entry of entries) {
+      const hash = computeContentHash(entry);
+      const existing = findByContentHash(provider, hash);
+      if (existing && existing !== entry.id) {
+        results.push({ id: entry.id, action: 'duplicate', existingId: existing });
+      } else {
+        seed(provider, [entry], alc);
+        results.push({ id: entry.id, action: 'inserted' });
+      }
+    }
+    return results;
+  });
+}
+
+export function installPack(
+  provider: PersistenceProvider, entries: IntelligenceEntry[], alc: AutoLinkConfig,
+): { installed: number; skipped: number } {
+  let installed = 0, skipped = 0;
+  const tagged = entries.map((e) => ({ ...e, origin: 'pack' as const }));
+  for (const r of seedDedup(provider, tagged, alc)) {
+    if (r.action === 'inserted') installed++; else skipped++;
+  }
+  return { installed, skipped };
+}
+
+export function search(provider: PersistenceProvider, query: string, options?: EntryFilterOptions): SearchResult[] {
+  const limit = options?.limit ?? 10;
+  const filters: string[] = [];
+  const fp: Record<string, unknown> = {};
+  if (options?.domain) { filters.push('e.domain = @domain'); fp.domain = options.domain; }
+  if (options?.type) { filters.push('e.type = @type'); fp.type = options.type; }
+  if (options?.severity) { filters.push('e.severity = @severity'); fp.severity = options.severity; }
+  if (options?.origin) { filters.push('e.origin = @origin'); fp.origin = options.origin; }
+  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 ')}` : '';
+  const ftsQuery = buildFtsQuery(query);
+  try {
+    const rows = provider.all<Record<string, unknown>>(
+      `SELECT e.*, bm25(entries_fts, 5.0, 10.0, 3.0, 1.0, 2.0) as score FROM entries_fts fts JOIN entries e ON e.rowid = fts.rowid WHERE entries_fts MATCH @query ${wc} ORDER BY score ASC LIMIT @limit`,
+      { query: ftsQuery, limit, ...fp },
+    );
+    return rows.map(rowToSearchResult);
+  } catch {
+    try {
+      const rows = provider.all<Record<string, unknown>>(
+        `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 { return []; }
+  }
+}
+
+export function get(provider: PersistenceProvider, id: string): IntelligenceEntry | null {
+  const row = provider.get<Record<string, unknown>>('SELECT * FROM entries WHERE id = ?', [id]);
+  return row ? rowToEntry(row) : null;
+}
+
+export function list(
+  provider: PersistenceProvider,
+  options?: EntryFilterOptions & { tags?: string[]; offset?: number },
+): IntelligenceEntry[] {
+  const filters: string[] = [];
+  const params: Record<string, unknown> = {};
+  if (options?.domain) { filters.push('domain = @domain'); params.domain = options.domain; }
+  if (options?.type) { filters.push('type = @type'); params.type = options.type; }
+  if (options?.severity) { filters.push('severity = @severity'); params.severity = options.severity; }
+  if (options?.origin) { filters.push('origin = @origin'); params.origin = options.origin; }
+  if (options?.tags?.length) {
+    const c = options.tags.map((t, i) => { params[`tag${i}`] = `%"${t}"%`; return `tags LIKE @tag${i}`; });
+    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 = provider.all<Record<string, unknown>>(
+    `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);
+}
+
+export function stats(provider: PersistenceProvider): VaultStats {
+  const total = provider.get<{ count: number }>('SELECT COUNT(*) as count FROM entries')!.count;
+  return { totalEntries: total, byType: gc(provider, 'type'), byDomain: gc(provider, 'domain'), bySeverity: gc(provider, 'severity') };
+}
+
+export function add(provider: PersistenceProvider, entry: IntelligenceEntry, alc: AutoLinkConfig): void {
+  seed(provider, [entry], alc);
+}
+
+export function remove(provider: PersistenceProvider, id: string): boolean {
+  return provider.run('DELETE FROM entries WHERE id = ?', [id]).changes > 0;
+}
+
+export function update(provider: PersistenceProvider, id: string, fields: EntryUpdateFields, alc: AutoLinkConfig): IntelligenceEntry | null {
+  const existing = get(provider, id);
+  if (!existing) return null;
+  seed(provider, [{ ...existing, ...fields }], alc);
+  return get(provider, id);
+}
+
+export function setTemporal(provider: PersistenceProvider, id: string, validFrom?: number, validUntil?: number): boolean {
+  const sets: string[] = [];
+  const params: Record<string, unknown> = { 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 provider.run(`UPDATE entries SET ${sets.join(', ')} WHERE id = @id`, params).changes > 0;
+}
+
+export function findExpiring(provider: PersistenceProvider, withinDays: number): IntelligenceEntry[] {
+  const now = Math.floor(Date.now() / 1000);
+  const cutoff = now + withinDays * 86400;
+  return provider.all<Record<string, unknown>>(
+    'SELECT * FROM entries WHERE valid_until IS NOT NULL AND valid_until > @now AND valid_until <= @cutoff ORDER BY valid_until ASC',
+    { now, cutoff },
+  ).map(rowToEntry);
+}
+
+export function findExpired(provider: PersistenceProvider, limit: number = 50): IntelligenceEntry[] {
+  const now = Math.floor(Date.now() / 1000);
+  return provider.all<Record<string, unknown>>(
+    'SELECT * FROM entries WHERE valid_until IS NOT NULL AND valid_until <= @now ORDER BY valid_until DESC LIMIT @limit',
+    { now, limit },
+  ).map(rowToEntry);
+}
+
+export function bulkRemove(provider: PersistenceProvider, ids: string[]): number {
+  return provider.transaction(() => {
+    let count = 0;
+    for (const id of ids) count += provider.run('DELETE FROM entries WHERE id = ?', [id]).changes;
+    return count;
+  });
+}
+
+export function getTags(provider: PersistenceProvider): Array<{ tag: string; count: number }> {
+  const rows = provider.all<{ tags: string }>('SELECT tags FROM entries');
+  const counts = new Map<string, number>();
+  for (const row of rows) {
+    for (const tag of JSON.parse(row.tags || '[]') as string[]) {
+      counts.set(tag, (counts.get(tag) ?? 0) + 1);
+    }
+  }
+  return Array.from(counts.entries()).map(([tag, count]) => ({ tag, count })).sort((a, b) => b.count - a.count);
+}
+
+export function getDomains(provider: PersistenceProvider): Array<{ domain: string; count: number }> {
+  return provider.all('SELECT domain, COUNT(*) as count FROM entries GROUP BY domain ORDER BY count DESC');
+}
+
+export function getRecent(provider: PersistenceProvider, limit: number = 20): IntelligenceEntry[] {
+  return provider.all<Record<string, unknown>>('SELECT * FROM entries ORDER BY updated_at DESC LIMIT ?', [limit]).map(rowToEntry);
+}
+
+export function findByContentHash(provider: PersistenceProvider, hash: string): string | null {
+  return provider.get<{ id: string }>('SELECT id FROM entries WHERE content_hash = @hash', { hash })?.id ?? null;
+}
+
+export function contentHashStats(provider: PersistenceProvider): { total: number; hashed: number; uniqueHashes: number } {
+  const total = provider.get<{ c: number }>('SELECT COUNT(*) as c FROM entries')?.c ?? 0;
+  const hashed = provider.get<{ c: number }>('SELECT COUNT(*) as c FROM entries WHERE content_hash IS NOT NULL')?.c ?? 0;
+  const uniqueHashes = provider.get<{ c: number }>('SELECT COUNT(DISTINCT content_hash) as c FROM entries WHERE content_hash IS NOT NULL')?.c ?? 0;
+  return { total, hashed, uniqueHashes };
+}
+
+// ── Helpers ──────────────────────────────────────────────────────────────
+
+function gc(provider: PersistenceProvider, col: string): Record<string, number> {
+  const rows = provider.all<{ key: string; count: number }>(`SELECT ${col} as key, COUNT(*) as count FROM entries GROUP BY ${col}`);
+  return Object.fromEntries(rows.map((r) => [r.key, r.count]));
+}
+
+export function rowToEntry(row: Record<string, unknown>): IntelligenceEntry {
+  return {
+    id: row.id as string, type: row.type as IntelligenceEntry['type'],
+    domain: row.domain as IntelligenceEntry['domain'], title: row.title as string,
+    severity: row.severity as IntelligenceEntry['severity'], description: row.description as string,
+    context: (row.context as string) ?? undefined, example: (row.example as string) ?? undefined,
+    counterExample: (row.counter_example as string) ?? undefined, 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, origin: (row.origin as IntelligenceEntry['origin']) ?? undefined,
+    validFrom: (row.valid_from as number) ?? undefined, validUntil: (row.valid_until as number) ?? undefined,
+  };
+}
+
+export function rowToSearchResult(row: Record<string, unknown>): SearchResult {
+  const rawScore = row.score as number;
+  return { entry: rowToEntry(row), score: rawScore < 0 ? -rawScore : rawScore };
+}
+
+/** Build FTS5 query from natural language: terms joined with OR for broad matching. */
+export function buildFtsQuery(query: string): string {
+  const terms = query.toLowerCase().split(/\s+/)
+    .filter((t) => t.length >= 2).map((t) => t.replace(/[^a-z0-9]/g, '')).filter(Boolean);
+  if (terms.length === 0) return query;
+  if (terms.length === 1) return terms[0];
+  return terms.join(' OR ');
+}

package/src/vault/vault-interfaces.ts

@@ -0,0 +1,56 @@
+/**
+ * ISP interfaces for Vault decomposition.
+ */
+import type { IntelligenceEntry } from '../intelligence/types.js';
+import type { SearchResult, VaultStats, Memory, MemoryStats } from './vault.js';
+
+export interface VaultReader {
+  get(id: string): IntelligenceEntry | null;
+  search(query: string, options?: { domain?: string; type?: string; severity?: string; origin?: 'agent' | 'pack' | 'user'; limit?: number; includeExpired?: boolean }): SearchResult[];
+  list(options?: { domain?: string; type?: string; severity?: string; origin?: 'agent' | 'pack' | 'user'; tags?: string[]; limit?: number; offset?: number; includeExpired?: boolean }): IntelligenceEntry[];
+  stats(): VaultStats;
+  getTags(): Array<{ tag: string; count: number }>;
+  getDomains(): Array<{ domain: string; count: number }>;
+  getRecent(limit?: number): IntelligenceEntry[];
+  findExpiring(withinDays: number): IntelligenceEntry[];
+  findExpired(limit?: number): IntelligenceEntry[];
+  findByContentHash(hash: string): string | null;
+  contentHashStats(): { total: number; hashed: number; uniqueHashes: number };
+}
+
+export interface VaultWriter {
+  seed(entries: IntelligenceEntry[]): number;
+  seedDedup(entries: IntelligenceEntry[]): Array<{ id: string; action: 'inserted' | 'duplicate'; existingId?: string }>;
+  installPack(entries: IntelligenceEntry[]): { installed: number; skipped: number };
+  add(entry: IntelligenceEntry): void;
+  remove(id: string): boolean;
+  bulkRemove(ids: string[]): number;
+  update(id: string, fields: Partial<Pick<IntelligenceEntry, 'title' | 'description' | 'context' | 'example' | 'counterExample' | 'why' | 'tags' | 'appliesTo' | 'severity' | 'type' | 'domain' | 'validFrom' | 'validUntil'>>): IntelligenceEntry | null;
+  setTemporal(id: string, validFrom?: number, validUntil?: number): boolean;
+  archive(options: { olderThanDays: number; reason?: string }): { archived: number };
+  restore(id: string): boolean;
+}
+
+export interface VaultMemory {
+  captureMemory(memory: Omit<Memory, 'id' | 'createdAt' | 'archivedAt'>): Memory;
+  getMemory(id: string): Memory | null;
+  deleteMemory(id: string): boolean;
+  searchMemories(query: string, options?: { type?: string; projectPath?: string; intent?: string; limit?: number }): Memory[];
+  listMemories(options?: { type?: string; projectPath?: string; limit?: number; offset?: number }): Memory[];
+  memoryStats(): MemoryStats;
+  memoryStatsDetailed(options?: { projectPath?: string; fromDate?: number; toDate?: number }): MemoryStats & { oldest: number | null; newest: number | null; archivedCount: number };
+  exportMemories(options?: { projectPath?: string; type?: string; includeArchived?: boolean }): Memory[];
+  importMemories(memories: Memory[]): { imported: number; skipped: number };
+  pruneMemories(olderThanDays: number): { pruned: number };
+  deduplicateMemories(): { removed: number; groups: Array<{ kept: string; removed: string[] }> };
+  memoryTopics(): Array<{ topic: string; count: number }>;
+  memoriesByProject(): Array<{ project: string; count: number; memories: Memory[] }>;
+}
+
+export interface VaultMaintenance {
+  optimize(): { vacuumed: boolean; analyzed: boolean; ftsRebuilt: boolean };
+  rebuildFtsIndex(): void;
+  exportAll(): { entries: IntelligenceEntry[]; exportedAt: number; count: number };
+  getAgeReport(): { total: number; buckets: Array<{ label: string; count: number; minDays: number; maxDays: number }>; oldestTimestamp: number | null; newestTimestamp: number | null };
+  contentHashStats(): { total: number; hashed: number; uniqueHashes: number };
+}