@ontrails/core 1.0.0-beta.0 → 1.0.0-beta.10

package/src/__tests__/execute.test.ts

@@ -0,0 +1,208 @@
+/* oxlint-disable require-await -- trail implementations satisfy async interface without awaiting */
+import { describe, test, expect } from 'bun:test';
+
+import { z } from 'zod';
+
+import { InternalError, ValidationError } from '../errors';
+import { executeTrail } from '../execute';
+import { createTrailContext } from '../context';
+import type { Layer } from '../layer';
+import { Result } from '../result';
+import { trail } from '../trail';
+import type { TrailContext } from '../types';
+
+// ---------------------------------------------------------------------------
+// Fixtures
+// ---------------------------------------------------------------------------
+
+const echoTrail = trail('echo', {
+  input: z.object({ value: z.string() }),
+  output: z.object({ value: z.string() }),
+  run: (input) => Result.ok({ value: input.value }),
+});
+
+const failingTrail = trail('fails', {
+  input: z.object({}),
+  run: () => Result.err(new ValidationError('bad input')),
+});
+
+const throwingTrail = trail('throws', {
+  input: z.object({}),
+  run: () => {
+    throw new Error('kaboom');
+  },
+});
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('executeTrail', () => {
+  describe('happy path', () => {
+    test('validates input and executes trail', async () => {
+      const result = await executeTrail(echoTrail, { value: 'hello' });
+
+      expect(result.isOk()).toBe(true);
+      expect(result.unwrap()).toEqual({ value: 'hello' });
+    });
+  });
+
+  describe('validation', () => {
+    test('returns validation error for invalid input', async () => {
+      const result = await executeTrail(echoTrail, { value: 42 });
+
+      expect(result.isErr()).toBe(true);
+      expect(result.error).toBeInstanceOf(ValidationError);
+    });
+  });
+
+  describe('layers', () => {
+    test('composes layers around execution', async () => {
+      const log: string[] = [];
+      const layer: Layer = {
+        name: 'test-layer',
+        wrap(_trail, impl) {
+          return async (input, ctx) => {
+            log.push('before');
+            const r = await impl(input, ctx);
+            log.push('after');
+            return r;
+          };
+        },
+      };
+
+      const result = await executeTrail(
+        echoTrail,
+        { value: 'x' },
+        { layers: [layer] }
+      );
+
+      expect(result.isOk()).toBe(true);
+      expect(log).toEqual(['before', 'after']);
+    });
+  });
+
+  describe('context', () => {
+    test('accepts context overrides', async () => {
+      let capturedCtx: TrailContext | undefined;
+      const ctxTrail = trail('ctx-test', {
+        input: z.object({}),
+        run: (_input, ctx) => {
+          capturedCtx = ctx;
+          return Result.ok(null);
+        },
+      });
+
+      await executeTrail(ctxTrail, {}, { ctx: { requestId: 'override-id' } });
+
+      expect(capturedCtx?.requestId).toBe('override-id');
+    });
+
+    test('accepts signal override', async () => {
+      let capturedSignal: AbortSignal | undefined;
+      const sigTrail = trail('sig-test', {
+        input: z.object({}),
+        run: (_input, ctx) => {
+          capturedSignal = ctx.signal;
+          return Result.ok(null);
+        },
+      });
+
+      const signal = AbortSignal.timeout(9999);
+      await executeTrail(sigTrail, {}, { signal });
+
+      expect(capturedSignal).toBe(signal);
+    });
+
+    test('accepts context factory', async () => {
+      let capturedCtx: TrailContext | undefined;
+      const ctxTrail = trail('factory-test', {
+        input: z.object({}),
+        run: (_input, ctx) => {
+          capturedCtx = ctx;
+          return Result.ok(null);
+        },
+      });
+
+      const customCtx: TrailContext = {
+        cwd: '/custom',
+        requestId: 'factory-id',
+        signal: new AbortController().signal,
+      };
+
+      await executeTrail(ctxTrail, {}, { createContext: () => customCtx });
+
+      expect(capturedCtx?.requestId).toBe('factory-id');
+      expect(capturedCtx?.cwd).toBe('/custom');
+    });
+
+    test('context factory + ctx overrides merge correctly', async () => {
+      let capturedCtx: TrailContext | undefined;
+      const ctxTrail = trail('merge-test', {
+        input: z.object({}),
+        run: (_input, ctx) => {
+          capturedCtx = ctx;
+          return Result.ok(null);
+        },
+      });
+
+      const baseCtx: TrailContext = {
+        cwd: '/factory',
+        requestId: 'factory-id',
+        signal: new AbortController().signal,
+      };
+
+      await executeTrail(
+        ctxTrail,
+        {},
+        {
+          createContext: () => baseCtx,
+          ctx: { requestId: 'overridden-id' },
+        }
+      );
+
+      expect(capturedCtx?.requestId).toBe('overridden-id');
+      expect(capturedCtx?.cwd).toBe('/factory');
+    });
+
+    test('deep-merges extensions from factory and overrides', async () => {
+      let captured: TrailContext | undefined;
+      const t = trail('ext.test', {
+        input: z.object({}),
+        output: z.object({}),
+        run: (_input, ctx) => {
+          captured = ctx;
+          return Result.ok({});
+        },
+      });
+      await executeTrail(
+        t,
+        {},
+        {
+          createContext: () =>
+            createTrailContext({ extensions: { store: 'db' } }),
+          ctx: { extensions: { userId: '123' } },
+        }
+      );
+      expect(captured?.extensions).toEqual({ store: 'db', userId: '123' });
+    });
+  });
+
+  describe('error handling', () => {
+    test('propagates Result.err from run function', async () => {
+      const result = await executeTrail(failingTrail, {});
+
+      expect(result.isErr()).toBe(true);
+      expect(result.error).toBeInstanceOf(ValidationError);
+      expect(result.error.message).toBe('bad input');
+    });
+
+    test('catches thrown exceptions and returns InternalError', async () => {
+      const result = await executeTrail(throwingTrail, {});
+
+      expect(result.isErr()).toBe(true);
+      expect(result.error).toBeInstanceOf(InternalError);
+      expect(result.error.message).toBe('kaboom');
+    });
+  });
+});

package/src/__tests__/layer.test.ts

@@ -1,17 +1,8 @@
-/* oxlint-disable require-await -- adapter mocks and layer wrappers satisfy async interfaces without awaiting */
+/* oxlint-disable require-await -- layer wrappers satisfy async interfaces without awaiting */
 import { describe, test, expect } from 'bun:test';
 
 import { z } from 'zod';
 
-import type {
-  IndexAdapter,
-  StorageAdapter,
-  CacheAdapter,
-  SearchOptions,
-  SearchResult,
-  StorageOptions,
-} from '../adapters';
-import type { HealthStatus, HealthResult, HealthCheck } from '../health';
 import { composeLayers } from '../layer';
 import type { Layer } from '../layer';
 import { Result } from '../result';
@@ -24,10 +15,10 @@ const stubCtx: TrailContext = {
 };
 
 const echoTrail = trail('echo', {
-  implementation: (input) => Result.ok({ value: input.value }),
   input: z.object({ value: z.string() }),
-  markers: { domain: 'test' },
+  metadata: { domain: 'test' },
   output: z.object({ value: z.string() }),
+  run: (input) => Result.ok({ value: input.value }),
 });
 
 // ---------------------------------------------------------------------------
@@ -49,11 +40,7 @@ describe('Layer', () => {
       },
     };
 
-    const wrapped = composeLayers(
-      [prefixLayer],
-      echoTrail,
-      echoTrail.implementation
-    );
+    const wrapped = composeLayers([prefixLayer], echoTrail, echoTrail.run);
     const result = await wrapped({ value: 'hello' }, stubCtx);
 
     expect(result.isOk()).toBe(true);
@@ -87,11 +74,7 @@ describe('Layer', () => {
       },
     };
 
-    const wrapped = composeLayers(
-      [outer, inner],
-      echoTrail,
-      echoTrail.implementation
-    );
+    const wrapped = composeLayers([outer, inner], echoTrail, echoTrail.run);
     await wrapped({ value: 'x' }, stubCtx);
 
     expect(log).toEqual([
@@ -110,11 +93,7 @@ describe('Layer', () => {
       },
     };
 
-    const wrapped = composeLayers(
-      [shortCircuit],
-      echoTrail,
-      echoTrail.implementation
-    );
+    const wrapped = composeLayers([shortCircuit], echoTrail, echoTrail.run);
     const result = await wrapped({ value: 'hello' }, stubCtx);
 
     expect(result.isErr()).toBe(true);
@@ -122,103 +101,24 @@ describe('Layer', () => {
     expect(err.error.message).toBe('blocked');
   });
 
-  test('layer can inspect trail markers', () => {
+  test('layer can inspect trail metadata', () => {
     let capturedDomain: unknown;
 
     const inspectLayer: Layer = {
       name: 'inspect',
       wrap(t, impl) {
-        capturedDomain = t.markers?.['domain'];
+        capturedDomain = t.metadata?.['domain'];
         return impl;
       },
     };
 
-    composeLayers([inspectLayer], echoTrail, echoTrail.implementation);
+    composeLayers([inspectLayer], echoTrail, echoTrail.run);
 
     expect(capturedDomain).toBe('test');
   });
 
   test('empty layers array returns implementation unchanged', () => {
-    const wrapped = composeLayers([], echoTrail, echoTrail.implementation);
-    expect(wrapped).toBe(echoTrail.implementation);
-  });
-});
-
-// ---------------------------------------------------------------------------
-// Health types (compile-time verification)
-// ---------------------------------------------------------------------------
-
-describe('health types', () => {
-  test('HealthResult satisfies the interface', () => {
-    const check: HealthCheck = {
-      latency: 12,
-      message: 'ok',
-      status: 'healthy',
-    };
-    const result: HealthResult = {
-      checks: { db: check },
-      status: 'healthy',
-      uptime: 3600,
-      version: '1.0.0',
-    };
-
-    expect(result.status).toBe('healthy');
-    expect(result.checks['db']?.status).toBe('healthy');
-  });
-
-  test('HealthStatus union is exhaustive', () => {
-    const statuses: HealthStatus[] = ['healthy', 'degraded', 'unhealthy'];
-    expect(statuses).toHaveLength(3);
-  });
-});
-
-// ---------------------------------------------------------------------------
-// Adapter types (compile-time verification)
-// ---------------------------------------------------------------------------
-
-describe('adapter types', () => {
-  test('IndexAdapter mock satisfies the interface', () => {
-    const mock: IndexAdapter = {
-      index: async () => Result.ok(),
-      remove: async () => Result.ok(),
-      search: async () => Result.ok([]),
-    };
-    expect(mock.index).toBeDefined();
-    expect(mock.search).toBeDefined();
-    expect(mock.remove).toBeDefined();
-  });
-
-  test('StorageAdapter mock satisfies the interface', () => {
-    const mock: StorageAdapter = {
-      delete: async () => Result.ok(),
-      get: async () => Result.ok('value'),
-      has: async () => Result.ok(true),
-      set: async () => Result.ok(),
-    };
-    expect(mock.has).toBeDefined();
-  });
-
-  test('CacheAdapter mock satisfies the interface', () => {
-    const mock: CacheAdapter = {
-      clear: async () => Result.ok(),
-      delete: async () => Result.ok(),
-      get: async () => Result.ok(),
-      set: async () => Result.ok(),
-    };
-    expect(mock.clear).toBeDefined();
-  });
-
-  test('SearchOptions and SearchResult satisfy their shapes', () => {
-    const opts: SearchOptions = { filters: { tag: 'a' }, limit: 10, offset: 0 };
-    const hit: SearchResult = {
-      document: { title: 'x' },
-      id: '1',
-      score: 0.95,
-    };
-    const sopts: StorageOptions = { ttl: 5000 };
-
-    expect(opts.limit).toBe(10);
-    expect(hit.score).toBe(0.95);
-    expect(sopts.ttl).toBe(5000);
+    const wrapped = composeLayers([], echoTrail, echoTrail.run);
+    expect(wrapped).toBe(echoTrail.run);
   });
 });

package/src/__tests__/serialization.test.ts

@@ -2,13 +2,24 @@ import { describe, test, expect } from 'bun:test';
 
 import {
   ValidationError,
+  AmbiguousError,
+  AssertionError,
   NetworkError,
   RateLimitError,
   InternalError,
   TimeoutError,
   NotFoundError,
+  AlreadyExistsError,
+  ConflictError,
+  PermissionError,
+  AuthError,
+  CancelledError,
 } from '../errors.js';
-import { serializeError, deserializeError } from '../serialization.js';
+import {
+  serializeError,
+  deserializeError,
+  safeStringify,
+} from '../serialization.js';
 import { Result } from '../result.js';
 import type { SerializedError } from '../serialization.js';
 
@@ -156,6 +167,66 @@ describe('deserializeError', () => {
       expect(err.category).toBe(category);
     }
   });
+
+  describe('round-trips all subclasses by name', () => {
+    const subclasses = [
+      { Ctor: ValidationError, category: 'validation' },
+      { Ctor: AmbiguousError, category: 'validation' },
+      { Ctor: AssertionError, category: 'internal' },
+      { Ctor: NotFoundError, category: 'not_found' },
+      { Ctor: AlreadyExistsError, category: 'conflict' },
+      { Ctor: ConflictError, category: 'conflict' },
+      { Ctor: PermissionError, category: 'permission' },
+      { Ctor: TimeoutError, category: 'timeout' },
+      { Ctor: NetworkError, category: 'network' },
+      { Ctor: InternalError, category: 'internal' },
+      { Ctor: AuthError, category: 'auth' },
+      { Ctor: CancelledError, category: 'cancelled' },
+    ] as const;
+
+    test.each(subclasses)(
+      '$Ctor.name round-trips with correct identity',
+      ({ Ctor, category }) => {
+        const original = new Ctor(`test ${Ctor.name}`, {
+          context: { key: 'value' },
+        });
+        const serialized = serializeError(original);
+        const restored = deserializeError(serialized);
+
+        expect(restored).toBeInstanceOf(Ctor);
+        expect(restored.constructor.name).toBe(Ctor.name);
+        expect(restored.name).toBe(Ctor.name);
+        expect(restored.category).toBe(category);
+        expect(restored.message).toBe(`test ${Ctor.name}`);
+        expect(restored.context).toEqual({ key: 'value' });
+      }
+    );
+
+    test('RateLimitError round-trips with retryAfter', () => {
+      const original = new RateLimitError('slow down', {
+        context: { endpoint: '/api' },
+        retryAfter: 42,
+      });
+      const serialized = serializeError(original);
+      const restored = deserializeError(serialized);
+
+      expect(restored).toBeInstanceOf(RateLimitError);
+      expect(restored.constructor.name).toBe('RateLimitError');
+      expect((restored as RateLimitError).retryAfter).toBe(42);
+      expect(restored.context).toEqual({ endpoint: '/api' });
+    });
+
+    test('falls back to category when name is unknown', () => {
+      const data: SerializedError = {
+        category: 'conflict',
+        message: 'custom error',
+        name: 'CustomConflictError',
+      };
+      const err = deserializeError(data);
+      expect(err).toBeInstanceOf(ConflictError);
+      expect(err.category).toBe('conflict');
+    });
+  });
 });
 
 // ---------------------------------------------------------------------------
@@ -233,4 +304,98 @@ describe('Result.toJson (safeStringify)', () => {
     expect(parsed['a']).toBe(1);
     expect(parsed['self']).toBe('[Circular]');
   });
+
+  test('serializes shared references in a DAG without marking as circular', () => {
+    const shared = { x: 1 };
+    const obj = { a: shared, b: shared };
+    const result = Result.toJson(obj);
+    expect(result.isOk()).toBe(true);
+    const parsed = JSON.parse(result.unwrap()) as Record<string, unknown>;
+    expect(parsed['a']).toEqual({ x: 1 });
+    expect(parsed['b']).toEqual({ x: 1 });
+  });
+
+  test('detects deep circular references', () => {
+    const inner: Record<string, unknown> = { value: 'deep' };
+    const obj: Record<string, unknown> = { child: { nested: inner } };
+    inner['back'] = obj;
+    const result = Result.toJson(obj);
+    expect(result.isOk()).toBe(true);
+    const parsed = JSON.parse(result.unwrap()) as Record<string, unknown>;
+    const child = parsed['child'] as Record<string, unknown>;
+    const nested = child['nested'] as Record<string, unknown>;
+    expect(nested['value']).toBe('deep');
+    expect(nested['back']).toBe('[Circular]');
+  });
+
+  test('handles shared ref used in sibling subtrees of a DAG', () => {
+    const shared = { id: 42 };
+    const obj = {
+      left: { extra: 'l', ref: shared },
+      right: { extra: 'r', ref: shared },
+    };
+    const result = Result.toJson(obj);
+    expect(result.isOk()).toBe(true);
+    const parsed = JSON.parse(result.unwrap()) as Record<
+      string,
+      Record<string, unknown>
+    >;
+    expect(parsed['left']?.['ref']).toEqual({ id: 42 });
+    expect(parsed['right']?.['ref']).toEqual({ id: 42 });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// safeStringify (shared DAG / circular detection)
+// ---------------------------------------------------------------------------
+
+describe('safeStringify', () => {
+  test('serializes shared references in a DAG without marking as circular', () => {
+    const shared = { x: 1 };
+    const obj = { a: shared, b: shared };
+    const result = safeStringify(obj);
+    expect(result.isOk()).toBe(true);
+    const parsed = JSON.parse(result.unwrap()) as Record<string, unknown>;
+    expect(parsed['a']).toEqual({ x: 1 });
+    expect(parsed['b']).toEqual({ x: 1 });
+  });
+
+  test('detects true circular references', () => {
+    const obj: Record<string, unknown> = { a: 1 };
+    obj['self'] = obj;
+    const result = safeStringify(obj);
+    expect(result.isOk()).toBe(true);
+    const parsed = JSON.parse(result.unwrap()) as Record<string, unknown>;
+    expect(parsed['a']).toBe(1);
+    expect(parsed['self']).toBe('[Circular]');
+  });
+
+  test('detects deep circular references', () => {
+    const inner: Record<string, unknown> = { value: 'deep' };
+    const obj: Record<string, unknown> = { child: { nested: inner } };
+    inner['back'] = obj;
+    const result = safeStringify(obj);
+    expect(result.isOk()).toBe(true);
+    const parsed = JSON.parse(result.unwrap()) as Record<string, unknown>;
+    const child = parsed['child'] as Record<string, unknown>;
+    const nested = child['nested'] as Record<string, unknown>;
+    expect(nested['value']).toBe('deep');
+    expect(nested['back']).toBe('[Circular]');
+  });
+
+  test('handles shared ref used in sibling subtrees of a DAG', () => {
+    const shared = { id: 42 };
+    const obj = {
+      left: { extra: 'l', ref: shared },
+      right: { extra: 'r', ref: shared },
+    };
+    const result = safeStringify(obj);
+    expect(result.isOk()).toBe(true);
+    const parsed = JSON.parse(result.unwrap()) as Record<
+      string,
+      Record<string, unknown>
+    >;
+    expect(parsed['left']?.['ref']).toEqual({ id: 42 });
+    expect(parsed['right']?.['ref']).toEqual({ id: 42 });
+  });
 });