@soleri/core 9.0.4 → 9.2.0

package/src/runtime/claude-md-helpers.test.ts

@@ -0,0 +1,191 @@
+/**
+ * Colocated unit tests for claude-md-helpers.ts — pure functions, no mocks needed.
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  hasSections,
+  removeSections,
+  injectAtPosition,
+  wrapInMarkers,
+  composeAgentModeSection,
+  composeIntegrationSection,
+  buildInjectionContent,
+  injectEngineRulesBlock,
+} from './claude-md-helpers.js';
+import type { AgentRuntimeConfig } from './types.js';
+
+const AGENT_ID = 'mybot';
+const CONFIG = { agentId: AGENT_ID } as AgentRuntimeConfig;
+
+describe('hasSections', () => {
+  it('detects both start and end markers', () => {
+    const content = `before\n<!-- agent:${AGENT_ID}:mode -->\nstuff\n<!-- /agent:${AGENT_ID}:mode -->\nafter`;
+    expect(hasSections(content, AGENT_ID)).toBe(true);
+  });
+
+  it('returns false if only start marker present', () => {
+    expect(hasSections(`<!-- agent:${AGENT_ID}:mode -->`, AGENT_ID)).toBe(false);
+  });
+
+  it('returns false for empty string', () => {
+    expect(hasSections('', AGENT_ID)).toBe(false);
+  });
+});
+
+describe('removeSections', () => {
+  it('removes section and trims surrounding whitespace', () => {
+    const content = `# Title\n\n<!-- agent:${AGENT_ID}:mode -->\nINJECTED\n<!-- /agent:${AGENT_ID}:mode -->\n\n## Footer`;
+    const result = removeSections(content, AGENT_ID);
+    expect(result).not.toContain('INJECTED');
+    expect(result).toContain('# Title');
+    expect(result).toContain('## Footer');
+  });
+
+  it('handles section at end of file', () => {
+    const content = `# Title\n\n<!-- agent:${AGENT_ID}:mode -->\ncontent\n<!-- /agent:${AGENT_ID}:mode -->`;
+    const result = removeSections(content, AGENT_ID);
+    expect(result).toContain('# Title');
+    expect(result).not.toContain('content');
+    expect(result.endsWith('\n')).toBe(true);
+  });
+
+  it('returns content unchanged when markers for different agent', () => {
+    const content = '<!-- agent:other:mode -->\nstuff\n<!-- /agent:other:mode -->';
+    expect(removeSections(content, AGENT_ID)).toBe(content);
+  });
+});
+
+describe('injectAtPosition', () => {
+  it('start: prepends section', () => {
+    const result = injectAtPosition('existing', 'NEW', 'start');
+    expect(result).toBe('NEW\n\nexisting');
+  });
+
+  it('end: appends section with trailing newline', () => {
+    const result = injectAtPosition('existing', 'NEW', 'end');
+    expect(result).toBe('existing\n\nNEW\n');
+  });
+
+  it('after-title: places section after first heading and blank lines', () => {
+    const content = '# Title\n\nParagraph';
+    const result = injectAtPosition(content, 'SECTION', 'after-title');
+    const idx = result.indexOf('SECTION');
+    expect(idx).toBeGreaterThan(result.indexOf('# Title'));
+    expect(idx).toBeLessThan(result.indexOf('Paragraph'));
+  });
+
+  it('after-title: handles multiple headings (picks first #)', () => {
+    const content = '# First\n## Second\nText';
+    const result = injectAtPosition(content, 'INJECTED', 'after-title');
+    expect(result.indexOf('INJECTED')).toBeGreaterThan(result.indexOf('# First'));
+  });
+
+  it('after-title: falls back to start when no heading exists', () => {
+    const result = injectAtPosition('just text', 'SECTION', 'after-title');
+    expect(result.startsWith('SECTION')).toBe(true);
+  });
+});
+
+describe('wrapInMarkers', () => {
+  it('wraps content between start and end markers', () => {
+    const result = wrapInMarkers(AGENT_ID, 'hello');
+    expect(result).toBe(`<!-- agent:${AGENT_ID}:mode -->\nhello\n<!-- /agent:${AGENT_ID}:mode -->`);
+  });
+
+  it('handles multi-line content', () => {
+    const result = wrapInMarkers(AGENT_ID, 'line1\nline2');
+    expect(result).toContain('line1\nline2');
+  });
+});
+
+describe('composeAgentModeSection', () => {
+  it('capitalizes agent name in heading', () => {
+    const result = composeAgentModeSection(CONFIG);
+    expect(result).toContain('## Mybot Mode');
+  });
+
+  it('includes activate and deactivate commands', () => {
+    const result = composeAgentModeSection(CONFIG);
+    expect(result).toContain('mybot_core op:activate params:{ projectPath: "." }');
+    expect(result).toContain('deactivate: true');
+  });
+});
+
+describe('composeIntegrationSection', () => {
+  it('renders default facades when none provided', () => {
+    const result = composeIntegrationSection(CONFIG);
+    expect(result).toContain('mybot_vault');
+    expect(result).toContain('mybot_plan');
+    expect(result).toContain('mybot_brain');
+    expect(result).toContain('mybot_memory');
+    expect(result).toContain('mybot_admin');
+    expect(result).toContain('mybot_curator');
+  });
+
+  it('renders provided facades with up to 5 ops', () => {
+    const facades = [
+      { name: 'mybot_custom', ops: ['a', 'b', 'c', 'd', 'e', 'f'] },
+    ];
+    const result = composeIntegrationSection(CONFIG, facades);
+    expect(result).toContain('`mybot_custom`');
+    expect(result).toContain('`a`');
+    expect(result).toContain('`e`');
+    expect(result).toContain(', ...');
+    expect(result).not.toContain('`f`');
+  });
+
+  it('renders session start command', () => {
+    const result = composeIntegrationSection(CONFIG);
+    expect(result).toContain('mybot_core op:session_start');
+  });
+});
+
+describe('buildInjectionContent', () => {
+  it('includes both mode and integration by default', () => {
+    const result = buildInjectionContent(CONFIG);
+    expect(result).toContain('Mode');
+    expect(result).toContain('Integration');
+    expect(result).toContain(`<!-- agent:${AGENT_ID}:mode -->`);
+  });
+
+  it('excludes integration when option disabled', () => {
+    const result = buildInjectionContent(CONFIG, { includeIntegration: false });
+    expect(result).toContain('Mode');
+    expect(result).not.toContain('Integration');
+  });
+
+  it('passes facades to integration section', () => {
+    const result = buildInjectionContent(CONFIG, {
+      facades: [{ name: 'mybot_x', ops: ['op1'] }],
+    });
+    expect(result).toContain('mybot_x');
+  });
+});
+
+describe('injectEngineRulesBlock', () => {
+  const RULES_START = '<!-- soleri:engine-rules -->';
+  const RULES_END = '<!-- /soleri:engine-rules -->';
+
+  it('appends engine rules when none exist', () => {
+    const result = injectEngineRulesBlock('# Agent\n\nContent', 'NEW_RULES');
+    expect(result).toContain('NEW_RULES');
+    expect(result.indexOf('Content')).toBeLessThan(result.indexOf('NEW_RULES'));
+  });
+
+  it('replaces existing engine rules block', () => {
+    const existing = `# Agent\n\n${RULES_START}\nOLD\n${RULES_END}\n\nFooter`;
+    const result = injectEngineRulesBlock(existing, 'UPDATED');
+    expect(result).toContain('UPDATED');
+    expect(result).not.toContain('OLD');
+    expect(result).toContain('Footer');
+  });
+
+  it('preserves content before and after when replacing', () => {
+    const existing = `BEFORE\n${RULES_START}\nMIDDLE\n${RULES_END}\nAFTER`;
+    const result = injectEngineRulesBlock(existing, 'REPLACED');
+    expect(result).toContain('BEFORE');
+    expect(result).toContain('AFTER');
+    expect(result).toContain('REPLACED');
+  });
+});

package/src/runtime/claude-md-helpers.ts

@@ -132,7 +132,7 @@ export function composeIntegrationSection(
   const lines: string[] = [
     `## ${name} Integration`,
     '',
-    `On session start: \`${agentId}_core op:register params:{ projectPath: "." }\``,
+    `On session start: \`${agentId}_core op:session_start params:{ projectPath: "." }\``,
     '',
     '### Essential Tools',
     '',

package/src/runtime/context-health.test.ts

@@ -0,0 +1,78 @@
+import { describe, it, expect } from 'vitest';
+import { ContextHealthMonitor } from './context-health.js';
+
+describe('ContextHealthMonitor', () => {
+  it('should return green status when fresh', () => {
+    const monitor = new ContextHealthMonitor();
+    const status = monitor.check();
+
+    expect(status.level).toBe('green');
+    expect(status.estimatedFill).toBe(0);
+    expect(status.toolCallCount).toBe(0);
+    expect(status.estimatedTokens).toBe(0);
+    expect(status.recommendation).toBe('Context usage is healthy. No action needed.');
+  });
+
+  it('should return yellow after ~80K tokens worth of events', () => {
+    const monitor = new ContextHealthMonitor();
+
+    // 80K tokens / 1.5 overhead = ~53333 payload bytes needed
+    // Use 100 calls with ~534 bytes each
+    for (let i = 0; i < 100; i++) {
+      monitor.track({ type: 'tool_call', payloadSize: 534 });
+    }
+
+    const status = monitor.check();
+    expect(status.level).toBe('yellow');
+    expect(status.estimatedFill).toBeGreaterThanOrEqual(0.4);
+    expect(status.estimatedFill).toBeLessThan(0.6);
+    expect(status.toolCallCount).toBe(100);
+    expect(status.recommendation).toBe('Consider compacting context soon.');
+  });
+
+  it('should return red after ~120K tokens worth of events', () => {
+    const monitor = new ContextHealthMonitor();
+
+    // 120K tokens / 1.5 overhead = 80000 payload bytes needed
+    // Use 200 calls with 400 bytes each = 80000 total
+    for (let i = 0; i < 200; i++) {
+      monitor.track({ type: 'tool_call', payloadSize: 400 });
+    }
+
+    const status = monitor.check();
+    expect(status.level).toBe('red');
+    expect(status.estimatedFill).toBeGreaterThanOrEqual(0.6);
+    expect(status.toolCallCount).toBe(200);
+    expect(status.recommendation).toBe(
+      'Session capture recommended before context degradation.',
+    );
+  });
+
+  it('should reset all tracking', () => {
+    const monitor = new ContextHealthMonitor();
+
+    for (let i = 0; i < 200; i++) {
+      monitor.track({ type: 'tool_call', payloadSize: 400 });
+    }
+    expect(monitor.check().level).toBe('red');
+
+    monitor.reset();
+    const status = monitor.check();
+
+    expect(status.level).toBe('green');
+    expect(status.toolCallCount).toBe(0);
+    expect(status.estimatedTokens).toBe(0);
+    expect(status.estimatedFill).toBe(0);
+  });
+
+  it('should cap estimatedFill at 1.0', () => {
+    const monitor = new ContextHealthMonitor();
+
+    // Way over the limit: 500K payload * 1.5 = 750K tokens
+    monitor.track({ type: 'huge_call', payloadSize: 500_000 });
+
+    const status = monitor.check();
+    expect(status.level).toBe('red');
+    expect(status.estimatedFill).toBe(1.0);
+  });
+});

package/src/runtime/context-health.ts

@@ -0,0 +1,85 @@
+/**
+ * Context Health Monitor — tracks tool call volume and estimates
+ * context window fill to recommend proactive session captures.
+ *
+ * Heuristic: tool calls x average payload size x 1.5 overhead factor.
+ * Assumes ~200K token context window for fill estimation.
+ */
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+export type HealthLevel = 'green' | 'yellow' | 'red';
+
+export interface ContextHealthStatus {
+  level: HealthLevel;
+  estimatedFill: number; // 0.0 - 1.0
+  toolCallCount: number;
+  estimatedTokens: number;
+  recommendation: string;
+}
+
+export interface TrackEvent {
+  type: string;
+  payloadSize: number;
+}
+
+// =============================================================================
+// CONSTANTS
+// =============================================================================
+
+const CONTEXT_WINDOW = 200_000;
+const OVERHEAD_FACTOR = 1.5;
+const YELLOW_THRESHOLD = 0.4;
+const RED_THRESHOLD = 0.6;
+
+const RECOMMENDATIONS: Record<HealthLevel, string> = {
+  green: 'Context usage is healthy. No action needed.',
+  yellow: 'Consider compacting context soon.',
+  red: 'Session capture recommended before context degradation.',
+};
+
+// =============================================================================
+// CONTEXT HEALTH MONITOR
+// =============================================================================
+
+export class ContextHealthMonitor {
+  private toolCallCount = 0;
+  private totalPayloadSize = 0;
+
+  /** Track a tool call event. */
+  track(event: TrackEvent): void {
+    this.toolCallCount += 1;
+    this.totalPayloadSize += event.payloadSize;
+  }
+
+  /** Check current context health status. */
+  check(): ContextHealthStatus {
+    const estimatedTokens = Math.round(
+      this.totalPayloadSize * OVERHEAD_FACTOR,
+    );
+    const estimatedFill = Math.min(estimatedTokens / CONTEXT_WINDOW, 1.0);
+    const level = this.classifyLevel(estimatedFill);
+
+    return {
+      level,
+      estimatedFill: Math.round(estimatedFill * 1000) / 1000,
+      toolCallCount: this.toolCallCount,
+      estimatedTokens,
+      recommendation: RECOMMENDATIONS[level],
+    };
+  }
+
+  /** Reset all tracking (on session clear). */
+  reset(): void {
+    this.toolCallCount = 0;
+    this.totalPayloadSize = 0;
+  }
+
+  private classifyLevel(fill: number): HealthLevel {
+    if (fill >= RED_THRESHOLD) return 'red';
+    if (fill >= YELLOW_THRESHOLD) return 'yellow';
+    return 'green';
+  }
+}

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

@@ -0,0 +1,202 @@
+/**
+ * Colocated unit tests for curator-extra-ops.ts — mock-based, no real DB.
+ */
+
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { createCuratorExtraOps } from './curator-extra-ops.js';
+import type { AgentRuntime } from './types.js';
+import { captureOps } from '../engine/test-helpers.js';
+
+function mockRuntime() {
+  return {
+    curator: {
+      getVersionHistory: vi.fn().mockReturnValue([]),
+      recordSnapshot: vi.fn().mockReturnValue({ recorded: true, historyId: 42 }),
+      getQueueStats: vi.fn().mockReturnValue({ totalEntries: 5, groomedEntries: 3 }),
+      enrichMetadata: vi.fn().mockReturnValue({ enriched: false, changes: [] }),
+      detectContradictionsHybrid: vi.fn().mockResolvedValue({ contradictions: [], method: 'tfidf-only' }),
+      consolidate: vi.fn(),
+    },
+    jobQueue: {
+      enqueue: vi.fn().mockImplementation((type) => `job-${type}`),
+      getStats: vi.fn().mockReturnValue({ pending: 0, running: 0 }),
+    },
+    pipelineRunner: {
+      getStatus: vi.fn().mockReturnValue({ running: false, tickCount: 0 }),
+      start: vi.fn(),
+      stop: vi.fn(),
+    },
+  } as unknown as AgentRuntime;
+}
+
+describe('createCuratorExtraOps', () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('returns 9 ops with correct names', () => {
+    const ops = createCuratorExtraOps(mockRuntime());
+    expect(ops).toHaveLength(9);
+    expect(ops.map((o) => o.name)).toEqual([
+      'curator_entry_history',
+      'curator_record_snapshot',
+      'curator_queue_stats',
+      'curator_enrich',
+      'curator_hybrid_contradictions',
+      'curator_pipeline_status',
+      'curator_enqueue_pipeline',
+      'curator_schedule_start',
+      'curator_schedule_stop',
+    ]);
+  });
+
+  describe('curator_entry_history', () => {
+    it('returns history with count', async () => {
+      const rt = mockRuntime();
+      const history = [{ historyId: 1 }, { historyId: 2 }];
+      (rt.curator.getVersionHistory as ReturnType<typeof vi.fn>).mockReturnValue(history);
+      const ops = captureOps(createCuratorExtraOps(rt));
+      const result = (await ops.get('curator_entry_history')!.handler({ entryId: 'e1' })) as {
+        entryId: string;
+        history: unknown[];
+        count: number;
+      };
+      expect(result.entryId).toBe('e1');
+      expect(result.count).toBe(2);
+      expect(result.history).toBe(history);
+    });
+  });
+
+  describe('curator_record_snapshot', () => {
+    it('passes changedBy and changeReason to curator', async () => {
+      const rt = mockRuntime();
+      const ops = captureOps(createCuratorExtraOps(rt));
+      await ops.get('curator_record_snapshot')!.handler({
+        entryId: 'e1',
+        changedBy: 'user',
+        changeReason: 'manual',
+      });
+      expect(rt.curator.recordSnapshot).toHaveBeenCalledWith('e1', 'user', 'manual');
+    });
+
+    it('passes undefined for optional params', async () => {
+      const rt = mockRuntime();
+      const ops = captureOps(createCuratorExtraOps(rt));
+      await ops.get('curator_record_snapshot')!.handler({ entryId: 'e1' });
+      expect(rt.curator.recordSnapshot).toHaveBeenCalledWith('e1', undefined, undefined);
+    });
+  });
+
+  describe('curator_queue_stats', () => {
+    it('delegates to curator.getQueueStats', async () => {
+      const rt = mockRuntime();
+      const ops = captureOps(createCuratorExtraOps(rt));
+      const result = await ops.get('curator_queue_stats')!.handler({});
+      expect(result).toEqual({ totalEntries: 5, groomedEntries: 3 });
+    });
+  });
+
+  describe('curator_enrich', () => {
+    it('passes entryId to curator.enrichMetadata', async () => {
+      const rt = mockRuntime();
+      const ops = captureOps(createCuratorExtraOps(rt));
+      await ops.get('curator_enrich')!.handler({ entryId: 'e1' });
+      expect(rt.curator.enrichMetadata).toHaveBeenCalledWith('e1');
+    });
+  });
+
+  describe('curator_hybrid_contradictions', () => {
+    it('passes optional threshold', async () => {
+      const rt = mockRuntime();
+      const ops = captureOps(createCuratorExtraOps(rt));
+      await ops.get('curator_hybrid_contradictions')!.handler({ threshold: 0.6 });
+      expect(rt.curator.detectContradictionsHybrid).toHaveBeenCalledWith(0.6);
+    });
+
+    it('passes undefined when no threshold', async () => {
+      const rt = mockRuntime();
+      const ops = captureOps(createCuratorExtraOps(rt));
+      await ops.get('curator_hybrid_contradictions')!.handler({});
+      expect(rt.curator.detectContradictionsHybrid).toHaveBeenCalledWith(undefined);
+    });
+  });
+
+  describe('curator_pipeline_status', () => {
+    it('combines jobQueue and pipelineRunner status', async () => {
+      const rt = mockRuntime();
+      const ops = captureOps(createCuratorExtraOps(rt));
+      const result = (await ops.get('curator_pipeline_status')!.handler({})) as {
+        queue: unknown;
+        runner: unknown;
+      };
+      expect(result.queue).toEqual({ pending: 0, running: 0 });
+      expect(result.runner).toEqual({ running: false, tickCount: 0 });
+    });
+  });
+
+  describe('curator_enqueue_pipeline', () => {
+    it('enqueues 3 jobs in DAG order', async () => {
+      const rt = mockRuntime();
+      const ops = captureOps(createCuratorExtraOps(rt));
+      const result = (await ops.get('curator_enqueue_pipeline')!.handler({ entryId: 'e1' })) as {
+        pipelineId: string;
+        jobs: string[];
+      };
+      expect(result.pipelineId).toMatch(/^pipe-/);
+      expect(result.jobs).toHaveLength(3);
+      expect(result.jobs).toEqual(['job-tag-normalize', 'job-dedup-check', 'job-auto-link']);
+      // Verify dependency chain
+      const calls = (rt.jobQueue.enqueue as ReturnType<typeof vi.fn>).mock.calls;
+      expect(calls[0][0]).toBe('tag-normalize');
+      expect(calls[1][1].dependsOn).toEqual(['job-tag-normalize']);
+      expect(calls[2][1].dependsOn).toEqual(['job-dedup-check']);
+    });
+  });
+
+  describe('curator_schedule_start', () => {
+    it('starts pipeline runner and sets interval', async () => {
+      const rt = mockRuntime();
+      (rt.pipelineRunner.getStatus as ReturnType<typeof vi.fn>).mockReturnValue({ running: true });
+      const ops = captureOps(createCuratorExtraOps(rt));
+      const result = (await ops.get('curator_schedule_start')!.handler({
+        intervalMinutes: 30,
+      })) as { started: boolean; consolidationIntervalMs: number };
+
+      expect(result.started).toBe(true);
+      expect(result.consolidationIntervalMs).toBe(30 * 60 * 1000);
+      expect(rt.pipelineRunner.start).toHaveBeenCalledOnce();
+
+      // Stop to clean up the interval
+      await ops.get('curator_schedule_stop')!.handler({});
+    });
+  });
+
+  describe('curator_schedule_stop', () => {
+    it('stops pipeline runner', async () => {
+      const rt = mockRuntime();
+      const ops = captureOps(createCuratorExtraOps(rt));
+      const result = (await ops.get('curator_schedule_stop')!.handler({})) as { stopped: boolean };
+      expect(result.stopped).toBe(true);
+      expect(rt.pipelineRunner.stop).toHaveBeenCalledOnce();
+    });
+  });
+
+  describe('auth levels', () => {
+    it('read ops have read auth', () => {
+      const ops = captureOps(createCuratorExtraOps(mockRuntime()));
+      expect(ops.get('curator_entry_history')!.auth).toBe('read');
+      expect(ops.get('curator_queue_stats')!.auth).toBe('read');
+      expect(ops.get('curator_hybrid_contradictions')!.auth).toBe('read');
+      expect(ops.get('curator_pipeline_status')!.auth).toBe('read');
+    });
+
+    it('write ops have write auth', () => {
+      const ops = captureOps(createCuratorExtraOps(mockRuntime()));
+      expect(ops.get('curator_record_snapshot')!.auth).toBe('write');
+      expect(ops.get('curator_enrich')!.auth).toBe('write');
+      expect(ops.get('curator_enqueue_pipeline')!.auth).toBe('write');
+      expect(ops.get('curator_schedule_start')!.auth).toBe('write');
+      expect(ops.get('curator_schedule_stop')!.auth).toBe('write');
+    });
+  });
+});

package/src/runtime/deprecation.test.ts

@@ -0,0 +1,98 @@
+/**
+ * Colocated unit tests for deprecation.ts — pure functions + console.warn spy.
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import {
+  deprecationWarning,
+  wrapDeprecated,
+  resetDeprecationWarnings,
+  type DeprecationInfo,
+} from './deprecation.js';
+
+describe('deprecationWarning', () => {
+  beforeEach(() => {
+    resetDeprecationWarnings();
+    vi.restoreAllMocks();
+  });
+
+  it('logs once per unique op name', () => {
+    const spy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    deprecationWarning({ name: 'x', since: '1.0.0' });
+    deprecationWarning({ name: 'x', since: '1.0.0' });
+    expect(spy).toHaveBeenCalledOnce();
+  });
+
+  it('includes all provided fields in the message', () => {
+    const spy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const info: DeprecationInfo = {
+      name: 'old_op',
+      since: '2.0.0',
+      removeIn: '3.0.0',
+      replacement: 'new_op',
+      message: 'Migrate now.',
+    };
+    deprecationWarning(info);
+    const msg = spy.mock.calls[0][0] as string;
+    expect(msg).toContain('"old_op"');
+    expect(msg).toContain('v2.0.0');
+    expect(msg).toContain('v3.0.0');
+    expect(msg).toContain('"new_op"');
+    expect(msg).toContain('Migrate now.');
+  });
+
+  it('omits optional fields gracefully', () => {
+    const spy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    deprecationWarning({ name: 'minimal', since: '1.0.0' });
+    const msg = spy.mock.calls[0][0] as string;
+    expect(msg).toContain('"minimal"');
+    expect(msg).not.toContain('Use');
+    expect(msg).not.toContain('Will be removed');
+  });
+});
+
+describe('wrapDeprecated', () => {
+  beforeEach(() => {
+    resetDeprecationWarnings();
+    vi.restoreAllMocks();
+  });
+
+  it('preserves original function return value', () => {
+    vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const fn = (a: number, b: number) => a + b;
+    const wrapped = wrapDeprecated(fn, { name: 'add', since: '1.0.0' });
+    expect(wrapped(3, 4)).toBe(7);
+  });
+
+  it('emits warning on first call only', () => {
+    const spy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const wrapped = wrapDeprecated(() => 0, { name: 'noop', since: '1.0.0' });
+    wrapped();
+    wrapped();
+    wrapped();
+    expect(spy).toHaveBeenCalledOnce();
+  });
+
+  it('passes through all arguments', () => {
+    vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const fn = vi.fn();
+    const wrapped = wrapDeprecated(fn, { name: 'multi', since: '1.0.0' });
+    wrapped('a', 'b', 'c');
+    expect(fn).toHaveBeenCalledWith('a', 'b', 'c');
+  });
+});
+
+describe('resetDeprecationWarnings', () => {
+  beforeEach(() => {
+    resetDeprecationWarnings();
+    vi.restoreAllMocks();
+  });
+
+  it('allows the same op to warn again after reset', () => {
+    const spy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    deprecationWarning({ name: 'test_op', since: '1.0.0' });
+    resetDeprecationWarnings();
+    deprecationWarning({ name: 'test_op', since: '1.0.0' });
+    expect(spy).toHaveBeenCalledTimes(2);
+  });
+});