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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ontrails/core",
-  "version": "1.0.0-beta.1",
+  "version": "1.0.0-beta.10",
   "type": "module",
   "exports": {
     ".": "./src/index.ts",
@@ -16,6 +16,6 @@
     "clean": "rm -rf dist *.tsbuildinfo"
   },
   "peerDependencies": {
-    "zod": "catalog:"
+    "zod": "^4.3.5"
   }
 }

package/src/__tests__/context.test.ts

@@ -48,14 +48,13 @@ describe('createTrailContext', () => {
     expect(ctx.workspaceRoot).toBe('/tmp');
   });
 
-  test('TrailContext is extensible with custom fields', () => {
+  test('TrailContext supports extensions for custom fields', () => {
     const ctx: TrailContext = createTrailContext({
-      customField: 42,
-      nested: { key: 'value' },
+      extensions: { customField: 42, nested: { key: 'value' } },
     });
 
-    expect(ctx['customField']).toBe(42);
-    expect(ctx['nested']).toEqual({ key: 'value' });
+    expect(ctx.extensions?.['customField']).toBe(42);
+    expect(ctx.extensions?.['nested']).toEqual({ key: 'value' });
   });
 
   test('each call generates a unique requestId', () => {

package/src/__tests__/derive.test.ts

@@ -77,6 +77,50 @@ describe('derive', () => {
     });
   });
 
+  describe('array types', () => {
+    test('z.array(z.string()) derives string[] field', () => {
+      const schema = z.object({ names: z.array(z.string()) });
+      const fields = deriveFields(schema);
+      expect(fields[0]).toMatchObject({
+        name: 'names',
+        options: undefined,
+        required: true,
+        type: 'string[]',
+      });
+    });
+
+    test('z.array(z.number()) derives number[] field', () => {
+      const schema = z.object({ scores: z.array(z.number()) });
+      const fields = deriveFields(schema);
+      expect(fields[0]).toMatchObject({
+        name: 'scores',
+        options: undefined,
+        required: true,
+        type: 'number[]',
+      });
+    });
+
+    test('optional z.array(z.string()) marks not required', () => {
+      const schema = z.object({ tags: z.array(z.string()).optional() });
+      const fields = deriveFields(schema);
+      expect(fields[0]).toMatchObject({
+        name: 'tags',
+        required: false,
+        type: 'string[]',
+      });
+    });
+
+    test('z.array(z.string()) with default sets default value', () => {
+      const schema = z.object({
+        items: z.array(z.string()).default(['a', 'b']),
+      });
+      const fields = deriveFields(schema);
+      expect(fields[0]?.required).toBe(false);
+      expect(fields[0]?.type).toBe('string[]');
+      expect(fields[0]?.default).toEqual(['a', 'b']);
+    });
+  });
+
   describe('modifiers', () => {
     test('.describe() sets label', () => {
       const schema = z.object({

package/src/__tests__/dispatch.test.ts

@@ -0,0 +1,154 @@
+/* oxlint-disable require-await -- trail implementations satisfy async interface without awaiting */
+import { describe, test, expect } from 'bun:test';
+
+import { z } from 'zod';
+
+import { dispatch } from '../dispatch';
+import { InternalError, NotFoundError, ValidationError } from '../errors';
+import type { Layer } from '../layer';
+import { Result } from '../result';
+import { topo } from '../topo';
+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 throwingTrail = trail('throws', {
+  input: z.object({}),
+  run: () => {
+    throw new Error('kaboom');
+  },
+});
+
+const testTopo = topo('test', { echoTrail, throwingTrail });
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('dispatch', () => {
+  describe('happy path', () => {
+    test('dispatches by ID and returns Result.ok with expected value', async () => {
+      const result = await dispatch(testTopo, 'echo', { value: 'hello' });
+
+      expect(result.isOk()).toBe(true);
+      expect(result.unwrap()).toEqual({ value: 'hello' });
+    });
+  });
+
+  describe('not found', () => {
+    test('returns NotFoundError for unknown trail ID', async () => {
+      const result = await dispatch(testTopo, 'nonexistent', {});
+
+      expect(result.isErr()).toBe(true);
+      expect(result.error).toBeInstanceOf(NotFoundError);
+      expect(result.error.message).toContain('nonexistent');
+      expect(result.error.message).toContain('test');
+    });
+  });
+
+  describe('validation', () => {
+    test('returns ValidationError for invalid input', async () => {
+      const result = await dispatch(testTopo, 'echo', { value: 42 });
+
+      expect(result.isErr()).toBe(true);
+      expect(result.error).toBeInstanceOf(ValidationError);
+    });
+  });
+
+  describe('layers', () => {
+    test('layer composition works through dispatch', 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 dispatch(
+        testTopo,
+        'echo',
+        { value: 'x' },
+        { layers: [layer] }
+      );
+
+      expect(result.isOk()).toBe(true);
+      expect(log).toEqual(['before', 'after']);
+    });
+  });
+
+  describe('context', () => {
+    test('context overrides work through dispatch', async () => {
+      let capturedCtx: TrailContext | undefined;
+      const ctxTrail = trail('ctx-dispatch-test', {
+        input: z.object({}),
+        run: (_input, ctx) => {
+          capturedCtx = ctx;
+          return Result.ok(null);
+        },
+      });
+
+      const ctxTopo = topo('ctx-test', { ctxTrail });
+      await dispatch(
+        ctxTopo,
+        'ctx-dispatch-test',
+        {},
+        { ctx: { requestId: 'override-id' } }
+      );
+
+      expect(capturedCtx?.requestId).toBe('override-id');
+    });
+
+    test('createContext factory works through dispatch', async () => {
+      let capturedCtx: TrailContext | undefined;
+      const ctxTrail = trail('factory-dispatch-test', {
+        input: z.object({}),
+        run: (_input, ctx) => {
+          capturedCtx = ctx;
+          return Result.ok(null);
+        },
+      });
+
+      const ctxTopo = topo('factory-test', { ctxTrail });
+      const customCtx: TrailContext = {
+        cwd: '/custom',
+        requestId: 'factory-id',
+        signal: new AbortController().signal,
+      };
+
+      await dispatch(
+        ctxTopo,
+        'factory-dispatch-test',
+        {},
+        { createContext: () => customCtx }
+      );
+
+      expect(capturedCtx?.requestId).toBe('factory-id');
+      expect(capturedCtx?.cwd).toBe('/custom');
+    });
+  });
+
+  describe('error handling', () => {
+    test('never throws — exceptions become InternalError', async () => {
+      const result = await dispatch(testTopo, 'throws', {});
+
+      expect(result.isErr()).toBe(true);
+      expect(result.error).toBeInstanceOf(InternalError);
+      expect(result.error.message).toBe('kaboom');
+    });
+  });
+});

package/src/__tests__/event.test.ts

@@ -12,7 +12,7 @@ const payloadSchema = z.object({
 const userAction = event('user.action', {
   description: 'A user performed an action',
   from: ['auth.login', 'auth.signup'],
-  markers: { domain: 'auth', priority: 1 },
+  metadata: { domain: 'auth', priority: 1 },
   payload: payloadSchema,
 });
 
@@ -45,7 +45,7 @@ describe('event() basics', () => {
   });
 });
 
-describe('event() from and markers', () => {
+describe('event() from and metadata', () => {
   test('preserves from', () => {
     expect(userAction.from).toEqual(['auth.login', 'auth.signup']);
   });
@@ -54,8 +54,8 @@ describe('event() from and markers', () => {
     expect(Object.isFrozen(userAction.from)).toBe(true);
   });
 
-  test('preserves markers', () => {
-    expect(userAction.markers).toEqual({ domain: 'auth', priority: 1 });
+  test('preserves metadata', () => {
+    expect(userAction.metadata).toEqual({ domain: 'auth', priority: 1 });
   });
 
   test('optional fields default to undefined', () => {
@@ -64,7 +64,7 @@ describe('event() from and markers', () => {
     });
     expect(minimal.description).toBeUndefined();
     expect(minimal.from).toBeUndefined();
-    expect(minimal.markers).toBeUndefined();
+    expect(minimal.metadata).toBeUndefined();
   });
 });
 

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);
   });
 });