@soleri/core 9.0.4 → 9.3.0

package/src/engine/register-engine.test.ts

@@ -0,0 +1,235 @@
+/**
+ * Colocated tests for register-engine.ts
+ *
+ * Validates registerEngine() registration mechanics:
+ * - Module tool naming convention
+ * - Engine module ordering and completeness
+ * - Core ops registration
+ * - Domain and domain pack registration
+ * - Hot ops as standalone tools
+ * - Auth policy enforcement
+ * - Error handling for unknown ops
+ * - Dynamic tool registration (registerTool)
+ */
+
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { createAgentRuntime } from '../runtime/runtime.js';
+import { registerEngine, ENGINE_MODULES } from './register-engine.js';
+import { ENGINE_MODULE_MANIFEST } from './module-manifest.js';
+import type { AgentRuntime } from '../runtime/types.js';
+import type { OpDefinition } from '../facades/types.js';
+
+let runtime: AgentRuntime;
+
+beforeAll(() => {
+  runtime = createAgentRuntime({
+    agentId: 'reg-test',
+    vaultPath: ':memory:',
+  });
+});
+
+afterAll(() => {
+  runtime.close();
+});
+
+function makeServer(): McpServer {
+  return new McpServer({ name: 'test-server', version: '1.0.0' });
+}
+
+describe('registerEngine — tool naming', () => {
+  it('prefixes all tools with agentId', () => {
+    const server = makeServer();
+    const result = registerEngine(server, runtime, { agentId: 'mybot' });
+    for (const tool of result.tools) {
+      expect(tool.startsWith('mybot_')).toBe(true);
+    }
+  });
+
+  it('creates {agentId}_{suffix} for each engine module', () => {
+    const server = makeServer();
+    const result = registerEngine(server, runtime, { agentId: 'alfa' });
+    const expectedSuffixes = ENGINE_MODULES.map((m) => m.suffix);
+    for (const suffix of expectedSuffixes) {
+      expect(result.tools).toContain(`alfa_${suffix}`);
+    }
+  });
+});
+
+describe('registerEngine — module completeness', () => {
+  it('ENGINE_MODULES matches ENGINE_MODULE_MANIFEST suffixes', () => {
+    const moduleSuffixes = ENGINE_MODULES.map((m) => m.suffix);
+    const manifestSuffixes = ENGINE_MODULE_MANIFEST.map((m) => m.suffix);
+    expect(moduleSuffixes).toEqual(manifestSuffixes);
+  });
+
+  it('ENGINE_MODULES and manifest have same count', () => {
+    expect(ENGINE_MODULES.length).toBe(ENGINE_MODULE_MANIFEST.length);
+  });
+
+  it('registers all unconditional modules', () => {
+    const server = makeServer();
+    const result = registerEngine(server, runtime, { agentId: 'check' });
+    const unconditional = ENGINE_MODULES.filter((m) => !m.condition);
+    for (const mod of unconditional) {
+      expect(result.tools).toContain(`check_${mod.suffix}`);
+    }
+  });
+});
+
+describe('registerEngine — module ordering', () => {
+  it('registers vault before brain (dependency order)', () => {
+    const server = makeServer();
+    const result = registerEngine(server, runtime, { agentId: 'ord' });
+    const vaultIdx = result.tools.indexOf('ord_vault');
+    const brainIdx = result.tools.indexOf('ord_brain');
+    expect(vaultIdx).toBeLessThan(brainIdx);
+  });
+
+  it('registers vault as the first engine module tool', () => {
+    const server = makeServer();
+    const result = registerEngine(server, runtime, { agentId: 'first' });
+    expect(result.tools[0]).toBe('first_vault');
+  });
+});
+
+describe('registerEngine — core ops', () => {
+  it('registers core facade when coreOps provided', () => {
+    const server = makeServer();
+    const coreOps: OpDefinition[] = [
+      {
+        name: 'health',
+        description: 'Health check',
+        auth: 'read',
+        handler: async () => ({ ok: true }),
+      },
+    ];
+    const result = registerEngine(server, runtime, { agentId: 'core', coreOps });
+    expect(result.tools).toContain('core_core');
+    expect(result.totalOps).toBeGreaterThan(ENGINE_MODULES.length); // at least 1 per module + 1 core
+  });
+
+  it('does not register core facade when coreOps is empty', () => {
+    const server = makeServer();
+    const result = registerEngine(server, runtime, { agentId: 'nocore', coreOps: [] });
+    expect(result.tools).not.toContain('nocore_core');
+  });
+
+  it('does not register core facade when coreOps is undefined', () => {
+    const server = makeServer();
+    const result = registerEngine(server, runtime, { agentId: 'nocore2' });
+    expect(result.tools).not.toContain('nocore2_core');
+  });
+});
+
+describe('registerEngine — hot ops', () => {
+  it('registers hot ops as standalone tools', () => {
+    const server = makeServer();
+    const result = registerEngine(server, runtime, {
+      agentId: 'hot',
+      hotOps: ['search_intelligent', 'capture_knowledge'],
+    });
+    expect(result.tools).toContain('hot_search_intelligent');
+    expect(result.tools).toContain('hot_capture_knowledge');
+  });
+
+  it('counts hot ops in totalOps', () => {
+    const server = makeServer();
+    const baseResult = registerEngine(server, runtime, { agentId: 'base' });
+
+    const server2 = makeServer();
+    const hotResult = registerEngine(server2, runtime, {
+      agentId: 'hotcount',
+      hotOps: ['search_intelligent'],
+    });
+    // Hot ops don't add to totalOps (they mirror existing ops)
+    // But they do add to tools array
+    expect(hotResult.tools.length).toBeGreaterThan(baseResult.tools.length);
+  });
+});
+
+describe('registerEngine — domains', () => {
+  it('registers domain facades with correct naming', () => {
+    const server = makeServer();
+    const result = registerEngine(server, runtime, {
+      agentId: 'dom',
+      domains: ['testing', 'architecture'],
+    });
+    expect(result.tools).toContain('dom_testing');
+    expect(result.tools).toContain('dom_architecture');
+  });
+
+  it('increments totalOps for domain facade ops', () => {
+    const server1 = makeServer();
+    const noDomains = registerEngine(server1, runtime, { agentId: 'nod' });
+
+    const server2 = makeServer();
+    const withDomains = registerEngine(server2, runtime, {
+      agentId: 'wd',
+      domains: ['testing'],
+    });
+    expect(withDomains.totalOps).toBeGreaterThan(noDomains.totalOps);
+  });
+});
+
+describe('registerEngine — domain packs', () => {
+  it('registers domain pack facades with agentId prefix', () => {
+    const server = makeServer();
+    const packOp: OpDefinition = {
+      name: 'custom_search',
+      description: 'Custom search',
+      auth: 'read',
+      handler: async () => [],
+    };
+    const result = registerEngine(server, runtime, {
+      agentId: 'pk',
+      domainPacks: [{ name: 'my-pack', facades: [{ name: 'custom', ops: [packOp] }] }],
+    });
+    expect(result.tools).toContain('pk_custom');
+  });
+
+  it('skips packs without facades', () => {
+    const server = makeServer();
+    const result = registerEngine(server, runtime, {
+      agentId: 'skip',
+      domainPacks: [{ name: 'empty-pack' }],
+    });
+    // Should still register normally without errors
+    expect(result.tools.length).toBeGreaterThan(0);
+  });
+});
+
+describe('registerEngine — return value', () => {
+  it('returns tools array, totalOps count, and registerTool function', () => {
+    const server = makeServer();
+    const result = registerEngine(server, runtime, { agentId: 'ret' });
+    expect(Array.isArray(result.tools)).toBe(true);
+    expect(typeof result.totalOps).toBe('number');
+    expect(typeof result.registerTool).toBe('function');
+    expect(result.totalOps).toBeGreaterThan(0);
+  });
+
+  it('registerTool adds a new tool at runtime', () => {
+    const server = makeServer();
+    const result = registerEngine(server, runtime, { agentId: 'dyn' });
+    const initialCount = result.tools.length;
+
+    result.registerTool('dyn_extra', 'Extra tool', [
+      { name: 'ping', description: 'Ping', auth: 'read', handler: async () => 'pong' },
+    ]);
+
+    expect(result.tools.length).toBe(initialCount + 1);
+    expect(result.tools).toContain('dyn_extra');
+  });
+});
+
+describe('ENGINE_MODULES descriptions match manifest', () => {
+  it('each module description aligns with manifest', () => {
+    for (let i = 0; i < ENGINE_MODULES.length; i++) {
+      const mod = ENGINE_MODULES[i];
+      const manifest = ENGINE_MODULE_MANIFEST[i];
+      expect(mod.suffix).toBe(manifest.suffix);
+      // Descriptions may diverge slightly but suffix must match
+    }
+  });
+});

package/src/engine/register-engine.ts

@@ -35,6 +35,14 @@ import { createControlFacadeOps } from '../runtime/facades/control-facade.js';
 import { createContextFacadeOps } from '../runtime/facades/context-facade.js';
 import { createAgencyFacadeOps } from '../runtime/facades/agency-facade.js';
 import { createChatFacadeOps } from '../runtime/facades/chat-facade.js';
+import { createOperatorFacadeOps } from '../runtime/facades/operator-facade.js';
+import { createArchiveFacadeOps } from '../runtime/facades/archive-facade.js';
+import { createSyncFacadeOps } from '../runtime/facades/sync-facade.js';
+import { createReviewFacadeOps } from '../runtime/facades/review-facade.js';
+import { createIntakeFacadeOps } from '../runtime/facades/intake-facade.js';
+import { createLinksFacadeOps } from '../runtime/facades/links-facade.js';
+import { createBranchingFacadeOps } from '../runtime/facades/branching-facade.js';
+import { createTierFacadeOps } from '../runtime/facades/tier-facade.js';
 import { createDomainFacade } from '../runtime/domain-ops.js';
 
 // ─── Types ────────────────────────────────────────────────────────────
@@ -84,7 +92,7 @@ interface ModuleDef {
 export const ENGINE_MODULES: ModuleDef[] = [
   {
     suffix: 'vault',
-    description: 'Knowledge management — search, CRUD, import/export, intake, archival.',
+    description: 'Knowledge management — search, CRUD, capture, sharing scope.',
     createOps: createVaultFacadeOps,
   },
   {
@@ -119,8 +127,7 @@ export const ENGINE_MODULES: ModuleDef[] = [
   },
   {
     suffix: 'orchestrate',
-    description:
-      'Execution orchestration — project registration, playbooks, plan/execute/complete.',
+    description: 'Execution orchestration — session start, playbooks, plan/execute/complete.',
     createOps: createOrchestrateFacadeOps,
   },
   {
@@ -143,6 +150,46 @@ export const ENGINE_MODULES: ModuleDef[] = [
     description: 'Chat transport — session management, response chunking, authentication.',
     createOps: createChatFacadeOps,
   },
+  {
+    suffix: 'operator',
+    description: 'Operator profile — personality learning, signals, adaptation.',
+    createOps: createOperatorFacadeOps,
+  },
+  {
+    suffix: 'archive',
+    description: 'Archival, lifecycle, and knowledge maintenance.',
+    createOps: createArchiveFacadeOps,
+  },
+  {
+    suffix: 'sync',
+    description: 'Git, Obsidian, and pack sync operations.',
+    createOps: createSyncFacadeOps,
+  },
+  {
+    suffix: 'review',
+    description: 'Knowledge review workflow.',
+    createOps: createReviewFacadeOps,
+  },
+  {
+    suffix: 'intake',
+    description: 'Content ingestion — books, URLs, text, batch import.',
+    createOps: createIntakeFacadeOps,
+  },
+  {
+    suffix: 'links',
+    description: 'Entry linking — create, traverse, suggest, orphan detection.',
+    createOps: createLinksFacadeOps,
+  },
+  {
+    suffix: 'branching',
+    description: 'Vault branching — create, list, merge, delete branches.',
+    createOps: createBranchingFacadeOps,
+  },
+  {
+    suffix: 'tier',
+    description: 'Multi-vault tiers — connect, disconnect, search across sources.',
+    createOps: createTierFacadeOps,
+  },
 ];
 
 // ─── Core Registration ────────────────────────────────────────────────

package/src/errors/classify.test.ts

@@ -0,0 +1,203 @@
+import { describe, it, expect } from 'vitest';
+import { classifyError } from './classify.js';
+import { SoleriError, SoleriErrorCode } from './types.js';
+
+describe('classifyError', () => {
+  describe('passthrough', () => {
+    it('should return a SoleriError as-is', () => {
+      const original = new SoleriError('already classified', SoleriErrorCode.TIMEOUT);
+      const result = classifyError(original);
+      expect(result).toBe(original);
+    });
+  });
+
+  describe('HTTP status classification', () => {
+    it('should classify 401 as AUTH', () => {
+      const result = classifyError({ status: 401, message: 'Unauthorized' });
+      expect(result.code).toBe(SoleriErrorCode.AUTH);
+      expect(result.context).toEqual({ httpStatus: 401 });
+    });
+
+    it('should classify 403 as AUTH', () => {
+      const result = classifyError({ status: 403, message: 'Forbidden' });
+      expect(result.code).toBe(SoleriErrorCode.AUTH);
+    });
+
+    it('should classify 404 as RESOURCE_NOT_FOUND', () => {
+      const result = classifyError({ statusCode: 404, message: 'Not found' });
+      expect(result.code).toBe(SoleriErrorCode.RESOURCE_NOT_FOUND);
+    });
+
+    it('should classify 408 as TIMEOUT', () => {
+      const result = classifyError({ status: 408, message: 'Request Timeout' });
+      expect(result.code).toBe(SoleriErrorCode.TIMEOUT);
+    });
+
+    it('should classify 429 as RATE_LIMIT', () => {
+      const result = classifyError({ status: 429, message: 'Too Many Requests' });
+      expect(result.code).toBe(SoleriErrorCode.RATE_LIMIT);
+    });
+
+    it('should classify 422 as VALIDATION', () => {
+      const result = classifyError({ status: 422, message: 'Unprocessable' });
+      expect(result.code).toBe(SoleriErrorCode.VALIDATION);
+    });
+
+    it('should classify 500 as INTERNAL', () => {
+      const result = classifyError({ status: 500, message: 'Server Error' });
+      expect(result.code).toBe(SoleriErrorCode.INTERNAL);
+    });
+
+    it('should classify 503 as INTERNAL', () => {
+      const result = classifyError({ status: 503, message: 'Service Unavailable' });
+      expect(result.code).toBe(SoleriErrorCode.INTERNAL);
+    });
+
+    it('should prefer statusCode when status is absent', () => {
+      const result = classifyError({ statusCode: 429, message: 'throttled' });
+      expect(result.code).toBe(SoleriErrorCode.RATE_LIMIT);
+    });
+  });
+
+  describe('Node.js error code classification', () => {
+    it('should classify ECONNREFUSED as NETWORK', () => {
+      const err = Object.assign(new Error('connect failed'), { code: 'ECONNREFUSED' });
+      const result = classifyError(err);
+      expect(result.code).toBe(SoleriErrorCode.NETWORK);
+      expect(result.context).toEqual({ errorCode: 'ECONNREFUSED' });
+    });
+
+    it('should classify ENOTFOUND as NETWORK', () => {
+      const err = Object.assign(new Error('dns fail'), { code: 'ENOTFOUND' });
+      expect(classifyError(err).code).toBe(SoleriErrorCode.NETWORK);
+    });
+
+    it('should classify ECONNRESET as NETWORK', () => {
+      const err = Object.assign(new Error('reset'), { code: 'ECONNRESET' });
+      expect(classifyError(err).code).toBe(SoleriErrorCode.NETWORK);
+    });
+
+    it('should classify ETIMEDOUT as TIMEOUT', () => {
+      const err = Object.assign(new Error('timed out'), { code: 'ETIMEDOUT' });
+      expect(classifyError(err).code).toBe(SoleriErrorCode.TIMEOUT);
+    });
+
+    it('should classify ESOCKETTIMEDOUT as TIMEOUT', () => {
+      const err = Object.assign(new Error('socket'), { code: 'ESOCKETTIMEDOUT' });
+      expect(classifyError(err).code).toBe(SoleriErrorCode.TIMEOUT);
+    });
+
+    it('should classify UND_ERR_CONNECT_TIMEOUT as TIMEOUT', () => {
+      const err = Object.assign(new Error('undici'), { code: 'UND_ERR_CONNECT_TIMEOUT' });
+      expect(classifyError(err).code).toBe(SoleriErrorCode.TIMEOUT);
+    });
+  });
+
+  describe('message pattern classification', () => {
+    it('should classify "overloaded" as LLM_OVERLOAD', () => {
+      expect(classifyError(new Error('server is overloaded')).code).toBe(
+        SoleriErrorCode.LLM_OVERLOAD,
+      );
+    });
+
+    it('should classify "model busy" as LLM_OVERLOAD', () => {
+      expect(classifyError(new Error('model is busy')).code).toBe(SoleriErrorCode.LLM_OVERLOAD);
+    });
+
+    it('should classify "timeout" message as TIMEOUT', () => {
+      expect(classifyError(new Error('operation timed out')).code).toBe(SoleriErrorCode.TIMEOUT);
+    });
+
+    it('should classify "sqlite" as VAULT_UNREACHABLE', () => {
+      expect(classifyError(new Error('sqlite error')).code).toBe(SoleriErrorCode.VAULT_UNREACHABLE);
+    });
+
+    it('should classify "validation" as VALIDATION', () => {
+      expect(classifyError(new Error('validation failed')).code).toBe(SoleriErrorCode.VALIDATION);
+    });
+
+    it('should classify "missing key" as CONFIG_ERROR', () => {
+      expect(classifyError(new Error('missing key FOO')).code).toBe(SoleriErrorCode.CONFIG_ERROR);
+    });
+
+    it('should classify "unauthorized" as AUTH', () => {
+      expect(classifyError(new Error('unauthorized access')).code).toBe(SoleriErrorCode.AUTH);
+    });
+
+    it('should classify "not found" as RESOURCE_NOT_FOUND', () => {
+      expect(classifyError(new Error('resource not found')).code).toBe(
+        SoleriErrorCode.RESOURCE_NOT_FOUND,
+      );
+    });
+
+    it('should classify "rate limit" as RATE_LIMIT', () => {
+      expect(classifyError(new Error('rate limit exceeded')).code).toBe(SoleriErrorCode.RATE_LIMIT);
+    });
+
+    it('should classify "network" as NETWORK', () => {
+      expect(classifyError(new Error('network failure')).code).toBe(SoleriErrorCode.NETWORK);
+    });
+  });
+
+  describe('fallback classification', () => {
+    it('should default to INTERNAL for unknown errors', () => {
+      const result = classifyError(new Error('something weird'));
+      expect(result.code).toBe(SoleriErrorCode.INTERNAL);
+    });
+
+    it('should handle string thrown values', () => {
+      const result = classifyError('a string error');
+      expect(result).toBeInstanceOf(SoleriError);
+      expect(result.message).toBe('a string error');
+    });
+
+    it('should handle number thrown values', () => {
+      const result = classifyError(42);
+      expect(result).toBeInstanceOf(SoleriError);
+      expect(result.message).toBe('42');
+    });
+
+    it('should handle null thrown values', () => {
+      const result = classifyError(null);
+      expect(result).toBeInstanceOf(SoleriError);
+    });
+
+    it('should handle undefined thrown values', () => {
+      const result = classifyError(undefined);
+      expect(result).toBeInstanceOf(SoleriError);
+    });
+
+    it('should handle plain objects with no message', () => {
+      const result = classifyError({});
+      expect(result).toBeInstanceOf(SoleriError);
+      expect(result.message).toBe('Unknown error');
+      expect(result.code).toBe(SoleriErrorCode.INTERNAL);
+    });
+  });
+
+  describe('priority order', () => {
+    it('should prefer HTTP status over message pattern', () => {
+      const result = classifyError({ status: 404, message: 'network error not found' });
+      expect(result.code).toBe(SoleriErrorCode.RESOURCE_NOT_FOUND);
+    });
+
+    it('should prefer error code over message pattern', () => {
+      const err = Object.assign(new Error('timeout in database'), { code: 'ECONNREFUSED' });
+      const result = classifyError(err);
+      expect(result.code).toBe(SoleriErrorCode.NETWORK);
+    });
+  });
+
+  describe('cause preservation', () => {
+    it('should preserve original Error as cause', () => {
+      const original = new Error('root');
+      const result = classifyError(original);
+      expect(result.cause).toBe(original);
+    });
+
+    it('should not set cause for non-Error values', () => {
+      const result = classifyError('string error');
+      expect(result.cause).toBeUndefined();
+    });
+  });
+});

package/src/errors/retry.test.ts

@@ -0,0 +1,153 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { shouldRetry, getRetryDelay, retryWithPreset, RETRY_PRESETS } from './retry.js';
+import { SoleriError, SoleriErrorCode } from './types.js';
+
+describe('RETRY_PRESETS', () => {
+  it('should define fast, normal, and patient presets', () => {
+    expect(RETRY_PRESETS.fast.maxAttempts).toBe(3);
+    expect(RETRY_PRESETS.normal.maxAttempts).toBe(10);
+    expect(RETRY_PRESETS.patient.maxAttempts).toBe(25);
+  });
+});
+
+describe('shouldRetry', () => {
+  it('should return true for retryable error below max attempts', () => {
+    const error = new SoleriError('timeout', SoleriErrorCode.TIMEOUT);
+    expect(shouldRetry(error, 1, 'fast')).toBe(true);
+  });
+
+  it('should return false for retryable error at max attempts', () => {
+    const error = new SoleriError('timeout', SoleriErrorCode.TIMEOUT);
+    expect(shouldRetry(error, 3, 'fast')).toBe(false);
+  });
+
+  it('should return false for non-retryable error', () => {
+    const error = new SoleriError('bad auth', SoleriErrorCode.AUTH);
+    expect(shouldRetry(error, 1, 'fast')).toBe(false);
+  });
+
+  it('should return false for fixable error', () => {
+    const error = new SoleriError('invalid', SoleriErrorCode.VALIDATION);
+    expect(shouldRetry(error, 1, 'normal')).toBe(false);
+  });
+});
+
+describe('getRetryDelay', () => {
+  it('should return a positive number', () => {
+    const delay = getRetryDelay(0, 'fast');
+    expect(delay).toBeGreaterThanOrEqual(0);
+  });
+
+  it('should increase with attempt number', () => {
+    const delays = Array.from({ length: 5 }, (_, i) => {
+      // Average over multiple samples to reduce jitter impact
+      const samples = Array.from({ length: 100 }, () => getRetryDelay(i, 'normal'));
+      return samples.reduce((a, b) => a + b, 0) / samples.length;
+    });
+    // Each averaged delay should generally be >= the previous
+    for (let i = 1; i < delays.length - 1; i++) {
+      expect(delays[i]).toBeGreaterThanOrEqual(delays[i - 1] * 0.5);
+    }
+  });
+
+  it('should not exceed maxIntervalMs plus jitter', () => {
+    const config = RETRY_PRESETS.fast;
+    const maxWithJitter = config.maxIntervalMs * 1.25;
+    for (let i = 0; i < 20; i++) {
+      expect(getRetryDelay(10, 'fast')).toBeLessThanOrEqual(maxWithJitter);
+    }
+  });
+
+  it('should never return a negative value', () => {
+    for (let i = 0; i < 50; i++) {
+      expect(getRetryDelay(0, 'fast')).toBeGreaterThanOrEqual(0);
+    }
+  });
+});
+
+describe('retryWithPreset', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it('should return ok on first success', async () => {
+    const fn = vi.fn().mockResolvedValue('done');
+    const resultPromise = retryWithPreset(fn, 'fast');
+    const result = await resultPromise;
+    expect(result).toEqual({ ok: true, value: 'done' });
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+
+  it('should retry retryable errors and succeed', async () => {
+    const fn = vi
+      .fn()
+      .mockRejectedValueOnce(new Error('network error'))
+      .mockResolvedValue('recovered');
+
+    const resultPromise = retryWithPreset(fn, 'fast');
+    // Advance past the sleep delay
+    await vi.advanceTimersByTimeAsync(20_000);
+    const result = await resultPromise;
+    expect(result).toEqual({ ok: true, value: 'recovered' });
+    expect(fn).toHaveBeenCalledTimes(2);
+  });
+
+  it('should return err immediately for permanent errors', async () => {
+    const fn = vi.fn().mockRejectedValue(new SoleriError('denied', SoleriErrorCode.AUTH));
+    const result = await retryWithPreset(fn, 'fast');
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.code).toBe(SoleriErrorCode.AUTH);
+    }
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+
+  it('should return err after exhausting all attempts', async () => {
+    const fn = vi.fn().mockRejectedValue(new SoleriError('down', SoleriErrorCode.NETWORK));
+    const resultPromise = retryWithPreset(fn, 'fast');
+    // Advance enough time for all retries
+    await vi.advanceTimersByTimeAsync(100_000);
+    const result = await resultPromise;
+    expect(result.ok).toBe(false);
+    expect(fn).toHaveBeenCalledTimes(3);
+  });
+
+  it('should call onRetry callback on each retry', async () => {
+    const onRetry = vi.fn();
+    const fn = vi.fn().mockRejectedValueOnce(new Error('network fail')).mockResolvedValue('ok');
+
+    const resultPromise = retryWithPreset(fn, 'fast', { onRetry });
+    await vi.advanceTimersByTimeAsync(20_000);
+    await resultPromise;
+    expect(onRetry).toHaveBeenCalledTimes(1);
+    expect(onRetry).toHaveBeenCalledWith(expect.any(SoleriError), 1, expect.any(Number));
+  });
+
+  it('should abort when signal is aborted during sleep', async () => {
+    const controller = new AbortController();
+    const fn = vi.fn().mockRejectedValue(new Error('network error'));
+
+    const resultPromise = retryWithPreset(fn, 'fast', { signal: controller.signal });
+    // Let the first attempt fail and enter sleep
+    await vi.advanceTimersByTimeAsync(0);
+    // Abort during sleep
+    controller.abort(new Error('cancelled'));
+    await vi.advanceTimersByTimeAsync(0);
+    const result = await resultPromise;
+    expect(result.ok).toBe(false);
+  });
+
+  it('should return err for fixable errors without retrying', async () => {
+    const fn = vi.fn().mockRejectedValue(new SoleriError('bad', SoleriErrorCode.VALIDATION));
+    const result = await retryWithPreset(fn, 'fast');
+    expect(result.ok).toBe(false);
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+});
+
+// Need to import afterEach at top level
+import { afterEach } from 'vitest';

package/src/errors/retry.ts

@@ -104,6 +104,7 @@ export async function retryWithPreset<T>(
 
   for (let attempt = 0; attempt < RETRY_PRESETS[preset].maxAttempts; attempt++) {
     try {
+      // oxlint-disable-next-line eslint(no-await-in-loop)
       const value = await fn();
       return ok(value);
     } catch (thrown: unknown) {
@@ -117,6 +118,7 @@ export async function retryWithPreset<T>(
       options?.onRetry?.(lastError, attempt + 1, delay);
 
       try {
+        // oxlint-disable-next-line eslint(no-await-in-loop)
         await sleep(delay, options?.signal);
       } catch {
         // Aborted during sleep