@soleri/core 9.0.4 → 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

@@ -0,0 +1,262 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { createLoopFacadeOps } from './loop-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 LoopManager ──────────────────────────────────────────────
+
+function makeMockLoop() {
+  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: [],
+    status: 'active',
+    startedAt: new Date().toISOString(),
+  };
+
+  let isActive = false;
+  const history: (typeof activeLoop)[] = [];
+
+  return {
+    startLoop: vi.fn().mockImplementation((config: Record<string, unknown>) => {
+      isActive = true;
+      activeLoop.config = config;
+      activeLoop.iterations = [];
+      activeLoop.status = 'active';
+      return activeLoop;
+    }),
+    iterate: vi.fn().mockImplementation((params: Record<string, unknown>) => {
+      const iter = {
+        iteration: activeLoop.iterations.length + 1,
+        passed: params.passed,
+        validationScore: params.validationScore ?? null,
+        validationResult: params.validationResult ?? null,
+        timestamp: new Date().toISOString(),
+      };
+      activeLoop.iterations.push(iter);
+      return iter;
+    }),
+    iterateWithGate: vi.fn().mockReturnValue({
+      decision: 'block',
+      reason: 'Loop continues',
+      iteration: 1,
+      prompt: 'Continue iterating',
+    }),
+    getStatus: vi.fn().mockImplementation(() => {
+      return isActive ? activeLoop : null;
+    }),
+    cancelLoop: vi.fn().mockImplementation(() => {
+      isActive = false;
+      activeLoop.status = 'cancelled';
+      activeLoop.completedAt = new Date().toISOString();
+      history.push({ ...activeLoop });
+      return activeLoop;
+    }),
+    getHistory: vi.fn().mockImplementation(() => history),
+    isActive: vi.fn().mockImplementation(() => isActive),
+    completeLoop: vi.fn().mockImplementation(() => {
+      isActive = false;
+      activeLoop.status = 'completed';
+      activeLoop.completedAt = new Date().toISOString();
+      history.push({ ...activeLoop });
+      return activeLoop;
+    }),
+  };
+}
+
+function makeRuntime(loop = makeMockLoop()): AgentRuntime {
+  return { loop } as unknown as AgentRuntime;
+}
+
+// ─── Tests ──────────────────────────────────────────────────────────
+
+describe('loop-facade', () => {
+  let ops: Map<string, CapturedOp>;
+  let mockLoop: ReturnType<typeof makeMockLoop>;
+
+  beforeEach(() => {
+    mockLoop = makeMockLoop();
+    ops = captureOps(createLoopFacadeOps(makeRuntime(mockLoop)));
+  });
+
+  it('registers all 9 ops', () => {
+    expect(ops.size).toBe(9);
+    const names = [...ops.keys()];
+    expect(names).toContain('loop_start');
+    expect(names).toContain('loop_iterate');
+    expect(names).toContain('loop_iterate_gate');
+    expect(names).toContain('loop_status');
+    expect(names).toContain('loop_cancel');
+    expect(names).toContain('loop_history');
+    expect(names).toContain('loop_is_active');
+    expect(names).toContain('loop_complete');
+    expect(names).toContain('loop_anomaly_check');
+  });
+
+  it('has correct auth levels', () => {
+    expect(ops.get('loop_start')!.auth).toBe('write');
+    expect(ops.get('loop_iterate')!.auth).toBe('write');
+    expect(ops.get('loop_iterate_gate')!.auth).toBe('write');
+    expect(ops.get('loop_status')!.auth).toBe('read');
+    expect(ops.get('loop_cancel')!.auth).toBe('write');
+    expect(ops.get('loop_history')!.auth).toBe('read');
+    expect(ops.get('loop_is_active')!.auth).toBe('read');
+    expect(ops.get('loop_complete')!.auth).toBe('write');
+    expect(ops.get('loop_anomaly_check')!.auth).toBe('read');
+  });
+
+  // ─── loop_start ────────────────────────────────────────────────
+
+  it('loop_start creates a loop with defaults', async () => {
+    const result = await executeOp(ops, 'loop_start', { mode: 'custom', prompt: 'build button' });
+    expect(result.success).toBe(true);
+    const data = result.data as Record<string, unknown>;
+    expect(data.started).toBe(true);
+    expect(data.mode).toBe('custom');
+    expect(data.maxIterations).toBe(20);
+  });
+
+  it('loop_start uses mode-specific defaults for token-migration', async () => {
+    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);
+    expect(data.targetScore).toBe(95);
+  });
+
+  it('loop_start respects custom maxIterations', async () => {
+    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);
+  });
+
+  // ─── loop_iterate ──────────────────────────────────────────────
+
+  it('loop_iterate records a passing iteration', async () => {
+    await executeOp(ops, 'loop_start', { mode: 'custom', prompt: 'test' });
+    const result = await executeOp(ops, 'loop_iterate', { passed: true, validationScore: 95 });
+    expect(result.success).toBe(true);
+    const data = result.data as Record<string, unknown>;
+    expect(data.passed).toBe(true);
+    expect(data.validationScore).toBe(95);
+  });
+
+  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',
+    });
+    expect(result.success).toBe(true);
+    expect((result.data as Record<string, unknown>).passed).toBe(false);
+  });
+
+  // ─── loop_iterate_gate ─────────────────────────────────────────
+
+  it('loop_iterate_gate returns gate decision', async () => {
+    await executeOp(ops, 'loop_start', { mode: 'custom', prompt: 'test' });
+    const result = await executeOp(ops, 'loop_iterate_gate', { lastOutput: 'some LLM output' });
+    expect(result.success).toBe(true);
+    expect((result.data as Record<string, unknown>).decision).toBe('block');
+  });
+
+  it('loop_iterate_gate passes knowledge param', async () => {
+    await executeOp(ops, 'loop_start', { mode: 'custom', prompt: 'test' });
+    const knowledge = { items: ['learned X'], patternsApplied: ['P1'] };
+    await executeOp(ops, 'loop_iterate_gate', { lastOutput: 'output', knowledge });
+    expect(mockLoop.iterateWithGate).toHaveBeenCalledWith('output', knowledge, undefined);
+  });
+
+  // ─── loop_status ───────────────────────────────────────────────
+
+  it('loop_status returns null when no active loop', async () => {
+    const result = await executeOp(ops, 'loop_status', {});
+    expect(result.success).toBe(true);
+    expect((result.data as Record<string, unknown>).active).toBe(false);
+  });
+
+  it('loop_status returns active loop info', async () => {
+    await executeOp(ops, 'loop_start', { mode: 'custom', prompt: 'test' });
+    const result = await executeOp(ops, 'loop_status', {});
+    expect(result.success).toBe(true);
+    expect((result.data as Record<string, unknown>).active).toBe(true);
+  });
+
+  // ─── loop_cancel ───────────────────────────────────────────────
+
+  it('loop_cancel cancels active loop', async () => {
+    await executeOp(ops, 'loop_start', { mode: 'custom', prompt: 'test' });
+    const result = await executeOp(ops, 'loop_cancel', {});
+    expect(result.success).toBe(true);
+    const data = result.data as Record<string, unknown>;
+    expect(data.cancelled).toBe(true);
+    expect(data.status).toBe('cancelled');
+  });
+
+  // ─── loop_history ──────────────────────────────────────────────
+
+  it('loop_history returns empty initially', async () => {
+    const result = await executeOp(ops, 'loop_history', {});
+    expect(result.success).toBe(true);
+    expect((result.data as Record<string, unknown>).count).toBe(0);
+  });
+
+  it('loop_history includes cancelled loops', async () => {
+    await executeOp(ops, 'loop_start', { mode: 'custom', prompt: 'test' });
+    await executeOp(ops, 'loop_cancel', {});
+    const result = await executeOp(ops, 'loop_history', {});
+    expect(result.success).toBe(true);
+    expect((result.data as Record<string, unknown>).count).toBe(1);
+  });
+
+  // ─── loop_is_active ────────────────────────────────────────────
+
+  it('loop_is_active returns false when idle', async () => {
+    const result = await executeOp(ops, 'loop_is_active', {});
+    expect(result.success).toBe(true);
+    expect((result.data as Record<string, unknown>).active).toBe(false);
+  });
+
+  it('loop_is_active returns true after start', async () => {
+    await executeOp(ops, 'loop_start', { mode: 'custom', prompt: 'test' });
+    const result = await executeOp(ops, 'loop_is_active', {});
+    expect(result.success).toBe(true);
+    expect((result.data as Record<string, unknown>).active).toBe(true);
+  });
+
+  // ─── loop_complete ─────────────────────────────────────────────
+
+  it('loop_complete marks loop as completed', async () => {
+    await executeOp(ops, 'loop_start', { mode: 'custom', prompt: 'test' });
+    const result = await executeOp(ops, 'loop_complete', {});
+    expect(result.success).toBe(true);
+    const data = result.data as Record<string, unknown>;
+    expect(data.completed).toBe(true);
+    expect(data.status).toBe('completed');
+  });
+
+  // ─── loop_anomaly_check ────────────────────────────────────────
+
+  it('loop_anomaly_check reports no active loop', async () => {
+    const result = await executeOp(ops, 'loop_anomaly_check', {});
+    expect(result.success).toBe(true);
+    const data = result.data as Record<string, unknown>;
+    expect(data.active).toBe(false);
+    expect(data.summary).toBe('No active loop');
+  });
+});