@soleri/core 9.2.0 → 9.3.0

package/src/runtime/facades/links-facade.test.ts

@@ -0,0 +1,203 @@
+/**
+ * Colocated contract tests for links-facade.ts.
+ * Verifies the facade delegates to createVaultLinkingOps and
+ * exposes all 9 linking ops with correct auth levels.
+ */
+
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { createLinksFacadeOps } from './links-facade.js';
+import { captureOps, executeOp } from '../../engine/test-helpers.js';
+import type { CapturedOp } from '../../engine/test-helpers.js';
+import type { AgentRuntime } from '../types.js';
+
+// ─── Mock runtime ────────────────────────────────────────────────────
+
+function makeRuntime(): AgentRuntime {
+  return {
+    vault: {
+      getProvider: vi.fn().mockReturnValue({
+        get: vi.fn().mockReturnValue({ id: 'x' }),
+        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;
+}
+
+// ─── Tests ───────────────────────────────────────────────────────────
+
+describe('links-facade', () => {
+  let runtime: AgentRuntime;
+  let ops: Map<string, CapturedOp>;
+
+  beforeEach(() => {
+    runtime = makeRuntime();
+    ops = captureOps(createLinksFacadeOps(runtime));
+  });
+
+  // ─── Registration ──────────────────────────────────────────────────
+
+  it('registers exactly 9 ops', () => {
+    expect(ops.size).toBe(9);
+  });
+
+  it('includes all expected op names', () => {
+    const expected = [
+      'link_entries',
+      'unlink_entries',
+      'get_links',
+      'traverse',
+      'suggest_links',
+      'get_orphans',
+      'relink_vault',
+      'backfill_links',
+      'link_stats',
+    ];
+    for (const name of expected) {
+      expect(ops.has(name), `missing op: ${name}`).toBe(true);
+    }
+  });
+
+  // ─── Auth levels ───────────────────────────────────────────────────
+
+  it('has correct auth levels', () => {
+    expect(ops.get('link_entries')!.auth).toBe('write');
+    expect(ops.get('unlink_entries')!.auth).toBe('write');
+    expect(ops.get('get_links')!.auth).toBe('read');
+    expect(ops.get('traverse')!.auth).toBe('read');
+    expect(ops.get('suggest_links')!.auth).toBe('read');
+    expect(ops.get('get_orphans')!.auth).toBe('read');
+    expect(ops.get('relink_vault')!.auth).toBe('write');
+    expect(ops.get('backfill_links')!.auth).toBe('write');
+    expect(ops.get('link_stats')!.auth).toBe('read');
+  });
+
+  // ─── Handler delegation ───────────────────────────────────────────
+
+  describe('link_entries', () => {
+    it('creates a link via linkManager', async () => {
+      const result = await executeOp(ops, 'link_entries', {
+        sourceId: 'a',
+        targetId: 'b',
+        linkType: 'extends',
+        note: 'test',
+      });
+      expect(result.success).toBe(true);
+      const data = result.data as { success: boolean };
+      expect(data.success).toBe(true);
+      const lm = runtime.linkManager as { addLink: ReturnType<typeof vi.fn> };
+      expect(lm.addLink).toHaveBeenCalledWith('a', 'b', 'extends', 'test');
+    });
+  });
+
+  describe('unlink_entries', () => {
+    it('removes a link', async () => {
+      const result = await executeOp(ops, 'unlink_entries', {
+        sourceId: 'a',
+        targetId: 'b',
+      });
+      expect(result.success).toBe(true);
+      const lm = runtime.linkManager as { removeLink: ReturnType<typeof vi.fn> };
+      expect(lm.removeLink).toHaveBeenCalledWith('a', 'b');
+    });
+  });
+
+  describe('get_links', () => {
+    it('returns outgoing and incoming links', async () => {
+      const result = await executeOp(ops, 'get_links', { entryId: 'a' });
+      expect(result.success).toBe(true);
+      const data = result.data as { totalLinks: number };
+      expect(data.totalLinks).toBe(0);
+    });
+  });
+
+  describe('traverse', () => {
+    it('traverses with default depth', async () => {
+      const result = await executeOp(ops, 'traverse', { entryId: 'a' });
+      expect(result.success).toBe(true);
+      const lm = runtime.linkManager as { traverse: ReturnType<typeof vi.fn> };
+      expect(lm.traverse).toHaveBeenCalledWith('a', 2);
+    });
+  });
+
+  describe('suggest_links', () => {
+    it('returns suggestions', async () => {
+      const result = await executeOp(ops, 'suggest_links', { entryId: 'a' });
+      expect(result.success).toBe(true);
+      const data = result.data as { totalSuggestions: number };
+      expect(data.totalSuggestions).toBe(0);
+    });
+  });
+
+  describe('get_orphans', () => {
+    it('returns orphaned entries', async () => {
+      const result = await executeOp(ops, 'get_orphans', {});
+      expect(result.success).toBe(true);
+      const data = result.data as { totalOrphans: number };
+      expect(data.totalOrphans).toBe(0);
+    });
+  });
+
+  describe('backfill_links', () => {
+    it('delegates to linkManager', async () => {
+      const result = await executeOp(ops, 'backfill_links', {
+        threshold: 0.7,
+        maxLinks: 3,
+        dryRun: false,
+        batchSize: 50,
+      });
+      expect(result.success).toBe(true);
+      const data = result.data as { created: number };
+      expect(data.created).toBe(0);
+    });
+  });
+
+  describe('link_stats', () => {
+    it('returns graph statistics', async () => {
+      const provider = (runtime.vault as { getProvider: ReturnType<typeof vi.fn> }).getProvider();
+      vi.mocked(provider.get)
+        .mockReturnValueOnce({ c: 10 }) // totalLinks
+        .mockReturnValueOnce({ c: 50 }) // totalEntries
+        .mockReturnValueOnce({ c: 3 }) // orphans
+        .mockReturnValueOnce({ c: 5 }); // withNotes
+      vi.mocked(provider.all)
+        .mockReturnValueOnce([{ link_type: 'extends', c: 7 }])
+        .mockReturnValueOnce([{ title: 'Top', links: 5 }]);
+
+      const result = await executeOp(ops, 'link_stats', {});
+      expect(result.success).toBe(true);
+      const data = result.data as { totalLinks: number; totalEntries: number };
+      expect(data.totalLinks).toBe(10);
+      expect(data.totalEntries).toBe(50);
+    });
+  });
+
+  describe('relink_vault', () => {
+    it('returns error when no LLM available', async () => {
+      const result = await executeOp(ops, 'relink_vault', {
+        batchSize: 10,
+        limit: 0,
+        dryRun: false,
+      });
+      expect(result.success).toBe(true);
+      const data = result.data as { success: boolean; error: string };
+      expect(data.success).toBe(false);
+      expect(data.error).toContain('No LLM');
+    });
+  });
+});

package/src/runtime/facades/links-facade.ts

@@ -0,0 +1,13 @@
+/**
+ * Links facade — Zettelkasten entry linking ops.
+ * link_entries, unlink_entries, get_links, traverse, suggest_links,
+ * get_orphans, relink_vault, backfill_links, link_stats.
+ */
+
+import type { OpDefinition } from '../../facades/types.js';
+import type { AgentRuntime } from '../types.js';
+import { createVaultLinkingOps } from '../vault-linking-ops.js';
+
+export function createLinksFacadeOps(runtime: AgentRuntime): OpDefinition[] {
+  return createVaultLinkingOps(runtime);
+}

package/src/runtime/facades/loop-facade.test.ts

@@ -7,7 +7,14 @@ import type { AgentRuntime } from '../types.js';
 // ─── Mock LoopManager ──────────────────────────────────────────────
 
 function makeMockLoop() {
-  const activeLoop: { id: string; config: Record<string, unknown>; iterations: unknown[]; status: string; startedAt: string; completedAt?: string } = {
+  const activeLoop: {
+    id: string;
+    config: Record<string, unknown>;
+    iterations: unknown[];
+    status: string;
+    startedAt: string;
+    completedAt?: string;
+  } = {
     id: 'loop-1',
     config: { mode: 'custom', prompt: 'test task', maxIterations: 20 },
     iterations: [],
@@ -16,7 +23,7 @@ function makeMockLoop() {
   };
 
   let isActive = false;
-  const history: typeof activeLoop[] = [];
+  const history: (typeof activeLoop)[] = [];
 
   return {
     startLoop: vi.fn().mockImplementation((config: Record<string, unknown>) => {
@@ -118,7 +125,10 @@ describe('loop-facade', () => {
   });
 
   it('loop_start uses mode-specific defaults for token-migration', async () => {
-    const result = await executeOp(ops, 'loop_start', { mode: 'token-migration', prompt: 'migrate tokens' });
+    const result = await executeOp(ops, 'loop_start', {
+      mode: 'token-migration',
+      prompt: 'migrate tokens',
+    });
     expect(result.success).toBe(true);
     const data = result.data as Record<string, unknown>;
     expect(data.maxIterations).toBe(20);
@@ -126,7 +136,11 @@ describe('loop-facade', () => {
   });
 
   it('loop_start respects custom maxIterations', async () => {
-    const result = await executeOp(ops, 'loop_start', { mode: 'custom', prompt: 'test', maxIterations: 5 });
+    const result = await executeOp(ops, 'loop_start', {
+      mode: 'custom',
+      prompt: 'test',
+      maxIterations: 5,
+    });
     expect(result.success).toBe(true);
     expect((result.data as Record<string, unknown>).maxIterations).toBe(5);
   });
@@ -144,7 +158,10 @@ describe('loop-facade', () => {
 
   it('loop_iterate records a failing iteration', async () => {
     await executeOp(ops, 'loop_start', { mode: 'custom', prompt: 'test' });
-    const result = await executeOp(ops, 'loop_iterate', { passed: false, validationResult: 'score too low' });
+    const result = await executeOp(ops, 'loop_iterate', {
+      passed: false,
+      validationResult: 'score too low',
+    });
     expect(result.success).toBe(true);
     expect((result.data as Record<string, unknown>).passed).toBe(false);
   });

package/src/runtime/facades/memory-facade.test.ts

@@ -127,10 +127,16 @@ describe('memory-facade', () => {
 
   it('memory_list filters by type', async () => {
     await executeOp(ops, 'memory_capture', {
-      projectPath: '/test', type: 'lesson', context: 'c', summary: 'lesson',
+      projectPath: '/test',
+      type: 'lesson',
+      context: 'c',
+      summary: 'lesson',
     });
     await executeOp(ops, 'memory_capture', {
-      projectPath: '/test', type: 'preference', context: 'c', summary: 'pref',
+      projectPath: '/test',
+      type: 'preference',
+      context: 'c',
+      summary: 'pref',
     });
     const result = await executeOp(ops, 'memory_list', { type: 'lesson' });
     expect(result.success).toBe(true);
@@ -140,7 +146,10 @@ describe('memory-facade', () => {
 
   it('memory_list verbose returns full objects', async () => {
     await executeOp(ops, 'memory_capture', {
-      projectPath: '/test', type: 'lesson', context: 'c', summary: 'verbose list',
+      projectPath: '/test',
+      type: 'lesson',
+      context: 'c',
+      summary: 'verbose list',
     });
     const result = await executeOp(ops, 'memory_list', { verbose: true });
     expect(result.success).toBe(true);
@@ -192,9 +201,14 @@ describe('memory-facade', () => {
 
   it('memory_delete removes a memory', async () => {
     const captureResult = await executeOp(ops, 'memory_capture', {
-      projectPath: '/test', type: 'lesson', context: 'c', summary: 'to delete',
+      projectPath: '/test',
+      type: 'lesson',
+      context: 'c',
+      summary: 'to delete',
     });
-    const memoryId = ((captureResult.data as Record<string, unknown>).memory as Record<string, unknown>).id as string;
+    const memoryId = (
+      (captureResult.data as Record<string, unknown>).memory as Record<string, unknown>
+    ).id as string;
     const result = await executeOp(ops, 'memory_delete', { memoryId });
     expect(result.success).toBe(true);
     expect((result.data as Record<string, unknown>).deleted).toBe(true);

package/src/runtime/facades/operator-facade.test.ts

@@ -45,9 +45,16 @@ describe('operator-facade (colocated)', () => {
     expect(ops.size).toBe(10);
     expect([...ops.keys()]).toEqual(
       expect.arrayContaining([
-        'profile_get', 'profile_update_section', 'profile_correct',
-        'profile_delete', 'profile_export', 'signal_accumulate',
-        'signal_list', 'signal_stats', 'synthesis_check', 'profile_snapshot',
+        'profile_get',
+        'profile_update_section',
+        'profile_correct',
+        'profile_delete',
+        'profile_export',
+        'signal_accumulate',
+        'signal_list',
+        'signal_stats',
+        'synthesis_check',
+        'profile_snapshot',
       ]),
     );
   });
@@ -85,7 +92,13 @@ describe('operator-facade (colocated)', () => {
   it('profile_update_section updates section', async () => {
     const result = await executeOp(ops, 'profile_update_section', {
       section: 'communication',
-      data: { style: 'concise', signalWords: ['yo'], formality: 0.3, patience: 0.9, adaptationRules: [] },
+      data: {
+        style: 'concise',
+        signalWords: ['yo'],
+        formality: 0.3,
+        patience: 0.9,
+        adaptationRules: [],
+      },
     });
     expect(result.success).toBe(true);
     expect((result.data as Record<string, unknown>).updated).toBe(true);

package/src/runtime/facades/operator-facade.ts

@@ -67,7 +67,8 @@ function profileToMarkdown(profile: Record<string, unknown>): string {
     if (evidence.length > 0) {
       lines.push(`**Evidence (${evidence.length}):**`, '');
       for (const e of evidence.slice(0, 10)) {
-        const label = e.source === 'observed' ? '[observed]' : e.source === 'reported' ? '[reported]' : '';
+        const label =
+          e.source === 'observed' ? '[observed]' : e.source === 'reported' ? '[reported]' : '';
         lines.push(`- ${label} ${e.summary} (confidence: ${e.confidence}, ${e.timestamp})`);
       }
       lines.push('');
@@ -77,10 +78,17 @@ function profileToMarkdown(profile: Record<string, unknown>): string {
   return lines.join('\n');
 }
 
-function extractEvidence(obj: Record<string, unknown>): Array<{ summary: string; confidence: number; timestamp: string; source?: string }> {
+function extractEvidence(
+  obj: Record<string, unknown>,
+): Array<{ summary: string; confidence: number; timestamp: string; source?: string }> {
   const evidence = obj.evidence;
   if (!Array.isArray(evidence)) return [];
-  return evidence.filter((e) => e && typeof e === 'object' && 'summary' in e) as Array<{ summary: string; confidence: number; timestamp: string; source?: string }>;
+  return evidence.filter((e) => e && typeof e === 'object' && 'summary' in e) as Array<{
+    summary: string;
+    confidence: number;
+    timestamp: string;
+    source?: string;
+  }>;
 }
 
 // ─── Facade Creator ─────────────────────────────────────────────────

package/src/runtime/facades/orchestrate-facade.test.ts

@@ -25,7 +25,13 @@ function makeRuntime(vault: Vault): AgentRuntime {
   const playbookExecutor = new PlaybookExecutor();
   const contextHealth = {
     track: vi.fn(),
-    check: vi.fn().mockReturnValue({ level: 'green', estimatedFill: 0.1, toolCallCount: 5, estimatedTokens: 1000, recommendation: '' }),
+    check: vi.fn().mockReturnValue({
+      level: 'green',
+      estimatedFill: 0.1,
+      toolCallCount: 5,
+      estimatedTokens: 1000,
+      recommendation: '',
+    }),
   };
 
   return {

package/src/runtime/facades/plan-facade.test.ts

@@ -23,7 +23,13 @@ function makeRuntime(vault: Vault): AgentRuntime {
   const linkManager = null;
   const chainRunner = new ChainRunner(vault.getProvider());
   return {
-    vault, planner, brain, brainIntelligence, curator, linkManager, chainRunner,
+    vault,
+    planner,
+    brain,
+    brainIntelligence,
+    curator,
+    linkManager,
+    chainRunner,
   } as unknown as AgentRuntime;
 }
 
@@ -92,9 +98,11 @@ describe('plan-facade', () => {
 
   it('get_plan returns plan by ID', async () => {
     const createResult = await executeOp(ops, 'create_plan', {
-      objective: 'Test', scope: 'test',
+      objective: 'Test',
+      scope: 'test',
     });
-    const planId = ((createResult.data as Record<string, unknown>).plan as Record<string, unknown>).id as string;
+    const planId = ((createResult.data as Record<string, unknown>).plan as Record<string, unknown>)
+      .id as string;
     const result = await executeOp(ops, 'get_plan', { planId });
     expect(result.success).toBe(true);
     expect((result.data as Record<string, unknown>).objective).toBe('Test');
@@ -126,7 +134,8 @@ describe('plan-facade', () => {
         { title: 'Task 2', description: 'desc 2' },
       ],
     });
-    const planId = ((createResult.data as Record<string, unknown>).plan as Record<string, unknown>).id as string;
+    const planId = ((createResult.data as Record<string, unknown>).plan as Record<string, unknown>)
+      .id as string;
 
     const result = await executeOp(ops, 'approve_plan', { planId });
     expect(result.success).toBe(true);
@@ -150,7 +159,8 @@ describe('plan-facade', () => {
         { approach: 'Alt B', pros: ['safe'], cons: ['slow'], rejected_reason: 'Too slow' },
       ],
     });
-    const planId = ((createResult.data as Record<string, unknown>).plan as Record<string, unknown>).id as string;
+    const planId = ((createResult.data as Record<string, unknown>).plan as Record<string, unknown>)
+      .id as string;
 
     const result = await executeOp(ops, 'approve_plan', { planId, startExecution: true });
     expect(result.success).toBe(true);
@@ -171,13 +181,15 @@ describe('plan-facade', () => {
     });
     const plan = (createResult.data as Record<string, unknown>).plan as Record<string, unknown>;
     const planId = plan.id as string;
-    const taskId = ((plan.tasks as Array<Record<string, unknown>>)[0]).id as string;
+    const taskId = (plan.tasks as Array<Record<string, unknown>>)[0].id as string;
 
     // Approve and start execution first
     await executeOp(ops, 'approve_plan', { planId, startExecution: true });
 
     const result = await executeOp(ops, 'update_task', {
-      planId, taskId, status: 'completed',
+      planId,
+      taskId,
+      status: 'completed',
     });
     expect(result.success).toBe(true);
     const data = result.data as { updated: boolean };
@@ -197,7 +209,8 @@ describe('plan-facade', () => {
         { approach: 'B', pros: ['a'], cons: ['b'], rejected_reason: 'c' },
       ],
     });
-    const planId = ((createResult.data as Record<string, unknown>).plan as Record<string, unknown>).id as string;
+    const planId = ((createResult.data as Record<string, unknown>).plan as Record<string, unknown>)
+      .id as string;
     await executeOp(ops, 'approve_plan', { planId, startExecution: true });
 
     const result = await executeOp(ops, 'complete_plan', { planId });
@@ -211,12 +224,15 @@ describe('plan-facade', () => {
 
   it('plan_iterate revises a draft plan', async () => {
     const createResult = await executeOp(ops, 'create_plan', {
-      objective: 'Initial', scope: 'test',
+      objective: 'Initial',
+      scope: 'test',
     });
-    const planId = ((createResult.data as Record<string, unknown>).plan as Record<string, unknown>).id as string;
+    const planId = ((createResult.data as Record<string, unknown>).plan as Record<string, unknown>)
+      .id as string;
 
     const result = await executeOp(ops, 'plan_iterate', {
-      planId, objective: 'Revised objective',
+      planId,
+      objective: 'Revised objective',
     });
     expect(result.success).toBe(true);
     const data = result.data as { iterated?: boolean; error?: string };
@@ -240,7 +256,8 @@ describe('plan-facade', () => {
       decisions: ['Use pattern X'],
       tasks: [{ title: 'Task 1', description: 'desc' }],
     });
-    const planId = ((createResult.data as Record<string, unknown>).plan as Record<string, unknown>).id as string;
+    const planId = ((createResult.data as Record<string, unknown>).plan as Record<string, unknown>)
+      .id as string;
 
     const result = await executeOp(ops, 'plan_grade', { planId });
     expect(result.success).toBe(true);

package/src/runtime/facades/plan-facade.ts

@@ -24,7 +24,10 @@ export function createPlanFacadeOps(runtime: AgentRuntime): OpDefinition[] {
       schema: z.object({
         objective: z.string().describe('What the plan aims to achieve'),
         scope: z.string().describe('Which parts of the codebase are affected'),
-        decisions: z.array(z.union([z.string(), z.object({ decision: z.string(), rationale: z.string() })])).optional().default([]),
+        decisions: z
+          .array(z.union([z.string(), z.object({ decision: z.string(), rationale: z.string() })]))
+          .optional()
+          .default([]),
         tasks: z
           .array(z.object({ title: z.string(), description: z.string() }))
           .optional()
@@ -47,7 +50,9 @@ export function createPlanFacadeOps(runtime: AgentRuntime): OpDefinition[] {
           scope: params.scope as string,
           decisions: (params.decisions as string[]) ?? [],
           tasks: (params.tasks as Array<{ title: string; description: string }>) ?? [],
-          alternatives: params.alternatives as Array<{ approach: string; pros: string[]; cons: string[]; rejected_reason: string }> | undefined,
+          alternatives: params.alternatives as
+            | Array<{ approach: string; pros: string[]; cons: string[]; rejected_reason: string }>
+            | undefined,
         });
         return { created: true, plan };
       },

package/src/runtime/facades/tier-facade.test.ts

@@ -0,0 +1,47 @@
+/**
+ * Colocated contract tests for tier-facade.ts.
+ * Verifies the facade wrapper delegates to tier-ops.
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import { createTierFacadeOps } from './tier-facade.js';
+import type { AgentRuntime } from '../types.js';
+
+function makeRuntime(): AgentRuntime {
+  return {
+    vaultManager: {
+      open: vi.fn(),
+      disconnect: vi.fn().mockReturnValue(true),
+      listTiers: vi.fn().mockReturnValue([]),
+      search: vi.fn().mockReturnValue([]),
+      connect: vi.fn(),
+      disconnectNamed: vi.fn().mockReturnValue(true),
+      listConnected: vi.fn().mockReturnValue([]),
+    },
+    config: { agentId: 'test-agent' },
+  } as unknown as AgentRuntime;
+}
+
+describe('tier-facade', () => {
+  it('returns all 7 tier/source ops', () => {
+    const ops = createTierFacadeOps(makeRuntime());
+    expect(ops).toHaveLength(7);
+    const names = ops.map((o) => o.name);
+    expect(names).toContain('vault_connect');
+    expect(names).toContain('vault_disconnect');
+    expect(names).toContain('vault_tiers');
+    expect(names).toContain('vault_search_all');
+    expect(names).toContain('vault_connect_source');
+    expect(names).toContain('vault_disconnect_source');
+    expect(names).toContain('vault_list_sources');
+  });
+
+  it('every op has name, handler, and auth', () => {
+    const ops = createTierFacadeOps(makeRuntime());
+    for (const op of ops) {
+      expect(typeof op.name).toBe('string');
+      expect(typeof op.handler).toBe('function');
+      expect(typeof op.auth).toBe('string');
+    }
+  });
+});

package/src/runtime/facades/tier-facade.ts

@@ -0,0 +1,11 @@
+/**
+ * Tier facade — multi-vault tier and named source operations.
+ */
+
+import type { OpDefinition } from '../../facades/types.js';
+import type { AgentRuntime } from '../types.js';
+import { createTierOps } from '../tier-ops.js';
+
+export function createTierFacadeOps(runtime: AgentRuntime): OpDefinition[] {
+  return [...createTierOps(runtime)];
+}