@soleri/core 9.0.4 → 9.3.0

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',

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

@@ -0,0 +1,237 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { createVaultLinkingOps } from './vault-linking-ops.js';
+import type { AgentRuntime } from './types.js';
+
+// ---------------------------------------------------------------------------
+// Mock runtime
+// ---------------------------------------------------------------------------
+
+function mockRuntime(): AgentRuntime {
+  return {
+    vault: {
+      getProvider: vi.fn().mockReturnValue({
+        get: vi.fn(),
+        all: vi.fn().mockReturnValue([]),
+        run: vi.fn(),
+      }),
+    },
+    linkManager: {
+      addLink: vi.fn(),
+      removeLink: vi.fn(),
+      getLinks: vi.fn().mockReturnValue([]),
+      getBacklinks: vi.fn().mockReturnValue([]),
+      getLinkCount: vi.fn().mockReturnValue(1),
+      traverse: vi.fn().mockReturnValue([]),
+      suggestLinks: vi.fn().mockReturnValue([]),
+      getOrphans: vi.fn().mockReturnValue([]),
+      backfillLinks: vi.fn().mockReturnValue({ created: 0, preview: [] }),
+    },
+    llmClient: {
+      isAvailable: vi.fn().mockReturnValue({ anthropic: false, openai: false }),
+      complete: vi.fn(),
+    },
+  } as unknown as AgentRuntime;
+}
+
+function findOp(ops: ReturnType<typeof createVaultLinkingOps>, name: string) {
+  const op = ops.find((o) => o.name === name);
+  if (!op) throw new Error(`Op "${name}" not found`);
+  return op;
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('createVaultLinkingOps', () => {
+  let rt: AgentRuntime;
+  let ops: ReturnType<typeof createVaultLinkingOps>;
+
+  beforeEach(() => {
+    rt = mockRuntime();
+    ops = createVaultLinkingOps(rt);
+  });
+
+  it('returns 9 ops', () => {
+    expect(ops.length).toBe(9);
+  });
+
+  // ─── link_entries ─────────────────────────────────────────────
+
+  describe('link_entries', () => {
+    it('throws when source entry does not exist', async () => {
+      const op = findOp(ops, 'link_entries');
+      const provider = rt.vault.getProvider();
+      vi.mocked(provider.get).mockReturnValue(undefined);
+      await expect(
+        op.handler({ sourceId: 'missing', targetId: 'b', linkType: 'supports' }),
+      ).rejects.toThrow('Entry not found');
+    });
+
+    it('creates link when both entries exist', async () => {
+      const op = findOp(ops, 'link_entries');
+      const provider = rt.vault.getProvider();
+      vi.mocked(provider.get).mockReturnValue({ id: 'x' });
+      const result = (await op.handler({
+        sourceId: 'a',
+        targetId: 'b',
+        linkType: 'extends',
+        note: 'test note',
+      })) as Record<string, unknown>;
+      expect(result.success).toBe(true);
+      expect(rt.linkManager.addLink).toHaveBeenCalledWith('a', 'b', 'extends', 'test note');
+    });
+  });
+
+  // ─── unlink_entries ───────────────────────────────────────────
+
+  describe('unlink_entries', () => {
+    it('removes a link and returns success', async () => {
+      const op = findOp(ops, 'unlink_entries');
+      const result = (await op.handler({
+        sourceId: 'a',
+        targetId: 'b',
+      })) as Record<string, unknown>;
+      expect(result.success).toBe(true);
+      expect(rt.linkManager.removeLink).toHaveBeenCalledWith('a', 'b');
+    });
+  });
+
+  // ─── get_links ────────────────────────────────────────────────
+
+  describe('get_links', () => {
+    it('returns outgoing and incoming links', async () => {
+      const op = findOp(ops, 'get_links');
+      vi.mocked(rt.linkManager.getLinks).mockReturnValue([
+        { sourceId: 'a', targetId: 'b', linkType: 'supports' },
+      ] as never);
+      vi.mocked(rt.linkManager.getBacklinks).mockReturnValue([
+        { sourceId: 'c', targetId: 'a', linkType: 'extends' },
+      ] as never);
+      const result = (await op.handler({ entryId: 'a' })) as Record<string, unknown>;
+      expect(result.totalLinks).toBe(2);
+      expect(result.entryId).toBe('a');
+    });
+  });
+
+  // ─── traverse ─────────────────────────────────────────────────
+
+  describe('traverse', () => {
+    it('walks graph from entry with default depth', async () => {
+      const op = findOp(ops, 'traverse');
+      vi.mocked(rt.linkManager.traverse).mockReturnValue([{ id: 'b' }] as never);
+      const result = (await op.handler({ entryId: 'a' })) as Record<string, unknown>;
+      expect(result.totalConnected).toBe(1);
+      expect(rt.linkManager.traverse).toHaveBeenCalledWith('a', 2);
+    });
+
+    it('uses provided depth', async () => {
+      const op = findOp(ops, 'traverse');
+      vi.mocked(rt.linkManager.traverse).mockReturnValue([] as never);
+      await op.handler({ entryId: 'a', depth: 4 });
+      expect(rt.linkManager.traverse).toHaveBeenCalledWith('a', 4);
+    });
+  });
+
+  // ─── suggest_links ────────────────────────────────────────────
+
+  describe('suggest_links', () => {
+    it('returns suggestions from linkManager', async () => {
+      const op = findOp(ops, 'suggest_links');
+      vi.mocked(rt.linkManager.suggestLinks).mockReturnValue([
+        { entryId: 'b', score: 0.9, reason: 'similar tags' },
+      ] as never);
+      const result = (await op.handler({ entryId: 'a', limit: 5 })) as Record<string, unknown>;
+      expect(result.totalSuggestions).toBe(1);
+    });
+  });
+
+  // ─── get_orphans ──────────────────────────────────────────────
+
+  describe('get_orphans', () => {
+    it('returns orphaned entries', async () => {
+      const op = findOp(ops, 'get_orphans');
+      vi.mocked(rt.linkManager.getOrphans).mockReturnValue([{ id: 'orphan1' }] as never);
+      const result = (await op.handler({ limit: 20 })) as Record<string, unknown>;
+      expect(result.totalOrphans).toBe(1);
+    });
+  });
+
+  // ─── relink_vault ─────────────────────────────────────────────
+
+  describe('relink_vault', () => {
+    it('returns error when no LLM provider available', async () => {
+      const op = findOp(ops, 'relink_vault');
+      const result = (await op.handler({ batchSize: 10, limit: 0, dryRun: false })) as Record<
+        string,
+        unknown
+      >;
+      expect(result.success).toBe(false);
+      expect(result.error).toContain('No LLM');
+    });
+
+    it('returns dry run preview without modifying links', async () => {
+      const op = findOp(ops, 'relink_vault');
+      vi.mocked(rt.llmClient.isAvailable).mockReturnValue({ anthropic: true, openai: false });
+      const provider = rt.vault.getProvider();
+      vi.mocked(provider.get).mockReturnValue({ c: 0 });
+      vi.mocked(provider.all).mockReturnValue([]);
+      const result = (await op.handler({ batchSize: 10, limit: 0, dryRun: true })) as Record<
+        string,
+        unknown
+      >;
+      expect(result.dryRun).toBe(true);
+      expect(provider.run).not.toHaveBeenCalled();
+    });
+  });
+
+  // ─── backfill_links ───────────────────────────────────────────
+
+  describe('backfill_links', () => {
+    it('delegates to linkManager.backfillLinks', async () => {
+      const op = findOp(ops, 'backfill_links');
+      vi.mocked(rt.linkManager.backfillLinks).mockReturnValue({
+        created: 5,
+        preview: [{ sourceId: 'a', targetId: 'b' }],
+      } as never);
+      const result = (await op.handler({
+        threshold: 0.7,
+        maxLinks: 3,
+        dryRun: false,
+        batchSize: 50,
+      })) as Record<string, unknown>;
+      expect(result.created).toBe(5);
+    });
+  });
+
+  // ─── link_stats ───────────────────────────────────────────────
+
+  describe('link_stats', () => {
+    it('returns graph statistics from vault', async () => {
+      const op = findOp(ops, 'link_stats');
+      const provider = rt.vault.getProvider();
+      vi.mocked(provider.get)
+        .mockReturnValueOnce({ c: 42 }) // totalLinks
+        .mockReturnValueOnce({ c: 100 }) // totalEntries
+        .mockReturnValueOnce({ c: 5 }) // orphans
+        .mockReturnValueOnce({ c: 30 }); // withNotes
+      vi.mocked(provider.all)
+        .mockReturnValueOnce([{ link_type: 'extends', c: 20 }]) // byType
+        .mockReturnValueOnce([{ title: 'Top Entry', links: 10 }]); // mostConnected
+      const result = (await op.handler({})) as Record<string, unknown>;
+      expect(result.totalLinks).toBe(42);
+      expect(result.totalEntries).toBe(100);
+      expect(result.orphans).toBe(5);
+    });
+
+    it('returns zeros on provider error', async () => {
+      const op = findOp(ops, 'link_stats');
+      const provider = rt.vault.getProvider();
+      vi.mocked(provider.get).mockImplementation(() => {
+        throw new Error('DB error');
+      });
+      const result = (await op.handler({})) as Record<string, unknown>;
+      expect(result.totalLinks).toBe(0);
+    });
+  });
+});