@soleri/core 9.0.4 → 9.2.0

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

@@ -0,0 +1,246 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { createVaultExtraOps } from './vault-extra-ops.js';
+import type { AgentRuntime } from './types.js';
+import type { OpDefinition } from '../facades/types.js';
+
+// ─── Mock content-hash module ─────────────────────────────────────────
+
+vi.mock('../vault/content-hash.js', () => ({
+  computeContentHash: vi.fn(() => 'abc123hash'),
+}));
+
+// ─── Mock Runtime Factory ──────────────────────────────────────────────
+
+function makeEntry(overrides: Record<string, unknown> = {}) {
+  return {
+    id: 'entry-1',
+    type: 'pattern',
+    domain: 'testing',
+    title: 'Test Pattern',
+    severity: 'suggestion',
+    description: 'A test pattern',
+    tags: ['test'],
+    context: undefined,
+    example: undefined,
+    counterExample: undefined,
+    why: undefined,
+    appliesTo: undefined,
+    ...overrides,
+  };
+}
+
+function createMockRuntime(): AgentRuntime {
+  return {
+    vault: {
+      get: vi.fn((id: string) => (id === 'entry-1' ? makeEntry() : null)),
+      add: vi.fn(),
+      update: vi.fn((id: string) => (id === 'entry-1' ? makeEntry() : null)),
+      remove: vi.fn(() => true),
+      list: vi.fn(() => [makeEntry()]),
+      seed: vi.fn((entries: unknown[]) => entries.length),
+      bulkRemove: vi.fn((ids: string[]) => ids.length),
+      stats: vi.fn(() => ({ totalEntries: 10, byDomain: { testing: 5 } })),
+      getTags: vi.fn(() => [
+        { tag: 'test', count: 5 },
+        { tag: 'design', count: 3 },
+      ]),
+      getDomains: vi.fn(() => [
+        { domain: 'testing', count: 5 },
+        { domain: 'design', count: 3 },
+      ]),
+      getRecent: vi.fn((_limit: number) => [makeEntry()]),
+      exportAll: vi.fn(() => ({ entries: [makeEntry()], exportedAt: Date.now() })),
+      findByContentHash: vi.fn(() => null),
+      contentHashStats: vi.fn(() => ({
+        total: 10,
+        hashed: 9,
+        uniqueHashes: 8,
+      })),
+    },
+  } as unknown as AgentRuntime;
+}
+
+function findOp(ops: OpDefinition[], name: string): OpDefinition {
+  const op = ops.find((o) => o.name === name);
+  if (!op) throw new Error(`Op not found: ${name}`);
+  return op;
+}
+
+// ─── Tests ─────────────────────────────────────────────────────────────
+
+describe('createVaultExtraOps', () => {
+  let runtime: AgentRuntime;
+  let ops: OpDefinition[];
+
+  beforeEach(() => {
+    runtime = createMockRuntime();
+    ops = createVaultExtraOps(runtime);
+  });
+
+  it('returns 13 ops', () => {
+    expect(ops).toHaveLength(13);
+  });
+
+  it('all ops have required fields', () => {
+    for (const op of ops) {
+      expect(op.name).toBeTruthy();
+      expect(op.handler).toBeDefined();
+      expect(['read', 'write', 'admin']).toContain(op.auth);
+    }
+  });
+
+  describe('vault_get', () => {
+    it('returns entry by ID', async () => {
+      const result = (await findOp(ops, 'vault_get').handler({ id: 'entry-1' })) as Record<string, unknown>;
+      expect(result.id).toBe('entry-1');
+    });
+
+    it('returns error for missing entry', async () => {
+      const result = (await findOp(ops, 'vault_get').handler({ id: 'missing' })) as Record<string, unknown>;
+      expect(result.error).toContain('not found');
+    });
+  });
+
+  describe('vault_update', () => {
+    it('updates entry fields', async () => {
+      const result = (await findOp(ops, 'vault_update').handler({
+        id: 'entry-1',
+        title: 'Updated Title',
+      })) as Record<string, unknown>;
+      expect(result.updated).toBe(true);
+      expect(runtime.vault.update).toHaveBeenCalledWith('entry-1', { title: 'Updated Title' });
+    });
+
+    it('returns error when no fields provided', async () => {
+      const result = (await findOp(ops, 'vault_update').handler({ id: 'entry-1' })) as Record<string, unknown>;
+      expect(result.error).toBe('No fields to update');
+    });
+
+    it('returns error for missing entry', async () => {
+      vi.mocked(runtime.vault.update).mockReturnValue(null as unknown);
+      const result = (await findOp(ops, 'vault_update').handler({
+        id: 'missing',
+        title: 'X',
+      })) as Record<string, unknown>;
+      expect(result.error).toContain('not found');
+    });
+  });
+
+  describe('vault_remove', () => {
+    it('removes entry by ID', async () => {
+      const result = (await findOp(ops, 'vault_remove').handler({ id: 'entry-1' })) as Record<string, unknown>;
+      expect(result.removed).toBe(true);
+      expect(result.id).toBe('entry-1');
+    });
+  });
+
+  describe('vault_bulk_add', () => {
+    it('seeds multiple entries', async () => {
+      const entries = [makeEntry({ id: 'a' }), makeEntry({ id: 'b' })];
+      const result = (await findOp(ops, 'vault_bulk_add').handler({ entries })) as Record<string, unknown>;
+      expect(result.added).toBe(2);
+      expect(result.total).toBe(10);
+    });
+  });
+
+  describe('vault_bulk_remove', () => {
+    it('removes multiple entries', async () => {
+      const result = (await findOp(ops, 'vault_bulk_remove').handler({
+        ids: ['a', 'b', 'c'],
+      })) as Record<string, unknown>;
+      expect(result.removed).toBe(3);
+      expect(result.requested).toBe(3);
+    });
+  });
+
+  describe('vault_tags', () => {
+    it('returns all tags with counts', async () => {
+      const result = (await findOp(ops, 'vault_tags').handler({})) as Record<string, unknown>;
+      expect(result.count).toBe(2);
+    });
+  });
+
+  describe('vault_domains', () => {
+    it('returns all domains with counts', async () => {
+      const result = (await findOp(ops, 'vault_domains').handler({})) as Record<string, unknown>;
+      expect(result.count).toBe(2);
+    });
+  });
+
+  describe('vault_recent', () => {
+    it('returns recent entries with default limit', async () => {
+      const result = (await findOp(ops, 'vault_recent').handler({})) as Record<string, unknown>;
+      expect(runtime.vault.getRecent).toHaveBeenCalledWith(20);
+      expect(result.count).toBe(1);
+    });
+
+    it('respects custom limit', async () => {
+      await findOp(ops, 'vault_recent').handler({ limit: 5 });
+      expect(runtime.vault.getRecent).toHaveBeenCalledWith(5);
+    });
+  });
+
+  describe('vault_import', () => {
+    it('imports entries and reports new vs updated', async () => {
+      vi.mocked(runtime.vault.stats)
+        .mockReturnValueOnce({ totalEntries: 10 } as unknown)
+        .mockReturnValueOnce({ totalEntries: 12 } as unknown);
+      const entries = [makeEntry({ id: 'x' }), makeEntry({ id: 'y' })];
+      const result = (await findOp(ops, 'vault_import').handler({ entries })) as Record<string, unknown>;
+      expect(result.imported).toBe(2);
+      expect(result.newEntries).toBe(2);
+      expect(result.total).toBe(12);
+    });
+  });
+
+  describe('vault_seed', () => {
+    it('seeds entries idempotently', async () => {
+      const entries = [makeEntry()];
+      const result = (await findOp(ops, 'vault_seed').handler({ entries })) as Record<string, unknown>;
+      expect(result.seeded).toBe(1);
+    });
+  });
+
+  describe('vault_seed_canonical', () => {
+    it('returns error for non-existent directory', async () => {
+      const result = (await findOp(ops, 'vault_seed_canonical').handler({
+        directory: '/tmp/nonexistent_dir_xyz',
+      })) as Record<string, unknown>;
+      expect(result.error).toContain('not found');
+    });
+  });
+
+  describe('vault_content_hash', () => {
+    it('computes content hash and checks for duplicates', async () => {
+      const result = (await findOp(ops, 'vault_content_hash').handler({
+        type: 'pattern',
+        domain: 'test',
+        title: 'Test',
+        description: 'A test',
+      })) as Record<string, unknown>;
+      expect(result.hash).toBe('abc123hash');
+      expect(result.duplicate).toBe(false);
+    });
+
+    it('detects duplicate when hash exists', async () => {
+      vi.mocked(runtime.vault.findByContentHash).mockReturnValue('existing-id' as unknown);
+      const result = (await findOp(ops, 'vault_content_hash').handler({
+        type: 'pattern',
+        domain: 'test',
+        title: 'Test',
+        description: 'A test',
+      })) as Record<string, unknown>;
+      expect(result.duplicate).toBe(true);
+      expect(result.existingId).toBe('existing-id');
+    });
+  });
+
+  describe('vault_dedup_status', () => {
+    it('reports dedup statistics with coverage', async () => {
+      const result = (await findOp(ops, 'vault_dedup_status').handler({})) as Record<string, unknown>;
+      expect(result.total).toBe(10);
+      expect(result.duplicates).toBe(2);
+      expect(result.coverage).toBe(90);
+    });
+  });
+});

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

@@ -1,9 +1,10 @@
 /**
- * Extra vault operations — 25 ops that extend the 4 base vault ops in core-ops.ts.
+ * Extra vault operations — 13 ops for CRUD, bulk, discovery, import/export, seed, and content hashing.
  *
- * Groups: single-entry CRUD (3), bulk (2), discovery (3), import/export (3),
- *         analytics (1), seed canonical (1), knowledge lifecycle (4), temporal (3),
- *         archival (3), content hashing (2).
+ * Archival, lifecycle, temporal, and knowledge maintenance ops are in archive-ops.ts.
+ *
+ * Groups: single-entry CRUD (3), bulk (2), discovery (3), import/export/seed (3),
+ *         seed canonical (1), content hashing (2).
  */
 
 import { z } from 'zod';
@@ -205,26 +206,6 @@ export function createVaultExtraOps(runtime: AgentRuntime): OpDefinition[] {
         return { seeded: count, total: vault.stats().totalEntries };
       },
     },
-    {
-      name: 'vault_backup',
-      description:
-        'Export the full vault as a JSON bundle suitable for backup or transfer to another agent.',
-      auth: 'read',
-      handler: async () => {
-        return vault.exportAll();
-      },
-    },
-
-    // ─── Analytics ──────────────────────────────────────────────────
-    {
-      name: 'vault_age_report',
-      description:
-        'Show vault entry age distribution — how many entries are from today, this week, this month, this quarter, or older.',
-      auth: 'read',
-      handler: async () => {
-        return vault.getAgeReport();
-      },
-    },
 
     // ─── Seed Canonical (#153) ───────────────────────────────────
     {
@@ -279,314 +260,6 @@ export function createVaultExtraOps(runtime: AgentRuntime): OpDefinition[] {
       },
     },
 
-    // ─── Knowledge Audit (#155) ──────────────────────────────────
-    {
-      name: 'knowledge_audit',
-      description:
-        'Audit vault quality — coverage gaps, stale entries, tag health, and recommendations.',
-      auth: 'read',
-      handler: async () => {
-        try {
-          const stats = vault.stats();
-          const tags = vault.getTags();
-          const domains = vault.getDomains();
-          const ageReport = vault.getAgeReport();
-
-          // Check coverage
-          const entriesWithoutTags = tags.length === 0 ? stats.totalEntries : 0;
-          const singletonTags = tags.filter((t) => t.count === 1).length;
-
-          // Staleness: entries older than 90 days
-          const staleCount = ageReport.buckets.find((b) => b.label === 'older')?.count ?? 0;
-
-          const recommendations: string[] = [];
-          if (stats.totalEntries < 10)
-            recommendations.push('Vault has few entries — capture more knowledge');
-          if (singletonTags > tags.length * 0.5)
-            recommendations.push('Many singleton tags — consolidate tagging');
-          if (staleCount > stats.totalEntries * 0.3)
-            recommendations.push('>30% entries are stale — review and update');
-          if (domains.length === 1)
-            recommendations.push('Only one domain — consider categorizing by domain');
-
-          return {
-            totalEntries: stats.totalEntries,
-            domainCount: domains.length,
-            tagCount: tags.length,
-            singletonTags,
-            staleEntries: staleCount,
-            entriesWithoutTags,
-            recommendations,
-          };
-        } catch (err) {
-          return { error: (err as Error).message };
-        }
-      },
-    },
-
-    // ─── Knowledge Health (#155) ─────────────────────────────────
-    {
-      name: 'knowledge_health',
-      description:
-        'Knowledge base health metrics — entry counts, freshness, staleness, contradiction signals.',
-      auth: 'read',
-      handler: async () => {
-        try {
-          const stats = vault.stats();
-          const ageReport = vault.getAgeReport();
-          const domains = vault.getDomains();
-          const tags = vault.getTags();
-
-          // Detect potential contradictions: entries with same tags but different types (pattern vs anti-pattern)
-          const db = vault.getDb();
-          const contradictionSignals = db
-            .prepare(
-              `SELECT t.value as tag, COUNT(DISTINCT e.type) as type_count
-               FROM entries e, json_each(e.tags) t
-               GROUP BY t.value HAVING type_count > 1 LIMIT 10`,
-            )
-            .all() as Array<{ tag: string; type_count: number }>;
-
-          return {
-            totalEntries: stats.totalEntries,
-            freshEntries:
-              (ageReport.buckets.find((b) => b.label === 'today')?.count ?? 0) +
-              (ageReport.buckets.find((b) => b.label === 'this_week')?.count ?? 0),
-            staleEntries: ageReport.buckets.find((b) => b.label === 'older')?.count ?? 0,
-            domainCount: domains.length,
-            tagCount: tags.length,
-            contradictionSignals: contradictionSignals.length,
-            contradictionTags: contradictionSignals.map((c) => c.tag),
-            oldestTimestamp: ageReport.oldestTimestamp,
-            newestTimestamp: ageReport.newestTimestamp,
-          };
-        } catch (err) {
-          return { error: (err as Error).message };
-        }
-      },
-    },
-
-    // ─── Merge Patterns (#155) ───────────────────────────────────
-    {
-      name: 'knowledge_merge',
-      description:
-        'Merge two similar patterns into one — keeps the best metadata from both, removes the duplicate.',
-      auth: 'write',
-      schema: z.object({
-        keepId: z.string().describe('ID of the entry to keep (will receive merged data)'),
-        removeId: z.string().describe('ID of the duplicate entry to remove after merge'),
-      }),
-      handler: async (params) => {
-        try {
-          const keep = vault.get(params.keepId as string);
-          const remove = vault.get(params.removeId as string);
-          if (!keep) return { error: `Entry not found: ${params.keepId}` };
-          if (!remove) return { error: `Entry not found: ${params.removeId}` };
-
-          // Merge tags (deduplicated union)
-          const mergedTags = [...new Set([...(keep.tags ?? []), ...(remove.tags ?? [])])];
-
-          // Merge fields — prefer non-empty from either side
-          const updates: Partial<IntelligenceEntry> = {
-            tags: mergedTags,
-            description: keep.description || remove.description,
-            context: keep.context || remove.context,
-            example: keep.example || remove.example,
-            counterExample: keep.counterExample || remove.counterExample,
-            why: keep.why || remove.why,
-            appliesTo: keep.appliesTo?.length ? keep.appliesTo : remove.appliesTo,
-          };
-
-          vault.update(keep.id, updates);
-          vault.remove(remove.id);
-
-          return {
-            merged: true,
-            keptId: keep.id,
-            removedId: remove.id,
-            mergedTags,
-          };
-        } catch (err) {
-          return { error: (err as Error).message };
-        }
-      },
-    },
-
-    // ─── Knowledge Reorganize (#155) ─────────────────────────────
-    {
-      name: 'knowledge_reorganize',
-      description:
-        'Re-categorize vault entries — reassign domains, clean up tags, deduplicate. Dry-run by default.',
-      auth: 'write',
-      schema: z.object({
-        dryRun: z
-          .boolean()
-          .optional()
-          .describe('If true, only report what would change (default true)'),
-        retagRules: z
-          .array(
-            z.object({
-              from: z.string().describe('Tag to rename/remove'),
-              to: z.string().optional().describe('New tag (omit to remove the tag)'),
-            }),
-          )
-          .optional()
-          .describe('Tag rename/removal rules'),
-        domainRules: z
-          .array(
-            z.object({
-              from: z.string().describe('Old domain name'),
-              to: z.string().describe('New domain name'),
-            }),
-          )
-          .optional()
-          .describe('Domain rename rules'),
-      }),
-      handler: async (params) => {
-        try {
-          const dryRun = (params.dryRun as boolean | undefined) ?? true;
-          const retagRules = (params.retagRules as Array<{ from: string; to?: string }>) ?? [];
-          const domainRules = (params.domainRules as Array<{ from: string; to: string }>) ?? [];
-          const changes: Array<{ id: string; field: string; from: string; to: string }> = [];
-
-          const allEntries = vault.list({});
-
-          for (const entry of allEntries) {
-            // Apply domain rules
-            for (const rule of domainRules) {
-              if (entry.domain === rule.from) {
-                changes.push({ id: entry.id, field: 'domain', from: rule.from, to: rule.to });
-                if (!dryRun) vault.update(entry.id, { domain: rule.to });
-              }
-            }
-
-            // Apply retag rules
-            if (entry.tags) {
-              let tagsChanged = false;
-              const newTags = [...entry.tags];
-              for (const rule of retagRules) {
-                const idx = newTags.indexOf(rule.from);
-                if (idx !== -1) {
-                  if (rule.to) {
-                    changes.push({ id: entry.id, field: 'tag', from: rule.from, to: rule.to });
-                    newTags[idx] = rule.to;
-                  } else {
-                    changes.push({ id: entry.id, field: 'tag', from: rule.from, to: '(removed)' });
-                    newTags.splice(idx, 1);
-                  }
-                  tagsChanged = true;
-                }
-              }
-              if (tagsChanged && !dryRun) {
-                vault.update(entry.id, { tags: [...new Set(newTags)] });
-              }
-            }
-          }
-
-          return {
-            dryRun,
-            changesFound: changes.length,
-            changes: changes.slice(0, 100), // cap output
-            entriesScanned: allEntries.length,
-          };
-        } catch (err) {
-          return { error: (err as Error).message };
-        }
-      },
-    },
-
-    // ─── Temporal (#89) ──────────────────────────────────────────────
-    {
-      name: 'vault_set_temporal',
-      description:
-        'Set valid_from and/or valid_until timestamps on a vault entry for bi-temporal validity windows.',
-      auth: 'write',
-      schema: z.object({
-        id: z.string().describe('Entry ID'),
-        validFrom: z.number().optional().describe('Unix epoch — when entry becomes active'),
-        validUntil: z.number().optional().describe('Unix epoch — when entry expires'),
-      }),
-      handler: async (params) => {
-        const updated = vault.setTemporal(
-          params.id as string,
-          params.validFrom as number | undefined,
-          params.validUntil as number | undefined,
-        );
-        if (!updated) return { error: 'Entry not found or no fields to update' };
-        const entry = vault.get(params.id as string);
-        return {
-          updated: true,
-          id: params.id,
-          validFrom: entry?.validFrom ?? null,
-          validUntil: entry?.validUntil ?? null,
-        };
-      },
-    },
-    {
-      name: 'vault_find_expiring',
-      description:
-        'Find vault entries expiring within a given number of days. Useful for proactive knowledge maintenance.',
-      auth: 'read',
-      schema: z.object({
-        withinDays: z.number().describe('Number of days to look ahead'),
-      }),
-      handler: async (params) => {
-        const entries = vault.findExpiring(params.withinDays as number);
-        return { entries, count: entries.length };
-      },
-    },
-    {
-      name: 'vault_find_expired',
-      description: 'List expired vault entries (valid_until in the past). Useful for cleanup.',
-      auth: 'read',
-      schema: z.object({
-        limit: z.number().optional().describe('Max results (default 50)'),
-      }),
-      handler: async (params) => {
-        const entries = vault.findExpired((params.limit as number | undefined) ?? 50);
-        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();
-      },
-    },
-
     // ── Content hashing (#166) ────────────────────────────────────────
     {
       name: 'vault_content_hash',