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

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

package/src/__tests__/topo.test.ts

@@ -13,22 +13,13 @@ import { topo } from '../topo.js';
 // oxlint-disable-next-line require-await -- satisfies async interface without needing await
 const noop = async () => Result.ok();
 
-const mockTrail = (id: string) => ({
+const mockTrail = (id: string, follow?: readonly string[]) => ({
+  follow: Object.freeze([...(follow ?? [])]),
   id,
-  implementation: noop,
   input: z.object({ x: z.number() }),
   kind: 'trail' as const,
   output: z.object({ y: z.number() }),
-});
-
-const mockHike = (id: string) => ({
-  follows: [] as readonly string[],
-  id,
-  implementation: noop,
-  input: z.object({ q: z.string() }),
-  kind: 'hike' as const,
-  output: z.object({ r: z.string() }),
-  path: `/${id}`,
+  run: noop,
 });
 
 const mockEvent = (id: string) => ({
@@ -42,80 +33,111 @@ const mockEvent = (id: string) => ({
 // ---------------------------------------------------------------------------
 
 describe('topo', () => {
-  test('returns Topo with name', () => {
-    const t = topo('my-app');
-    expect(t.name).toBe('my-app');
-  });
+  describe('collection', () => {
+    test('returns Topo with name', () => {
+      const t = topo('my-app');
+      expect(t.name).toBe('my-app');
+    });
 
-  test('collects trails from modules', () => {
-    const mod = { myTrail: mockTrail('create-user') };
-    const t = topo('app', mod);
+    test('collects trails from modules', () => {
+      const mod = { myTrail: mockTrail('create-user') };
+      const t = topo('app', mod);
 
-    expect(t.trails.size).toBe(1);
-    expect(t.trails.get('create-user')).toBe(mod.myTrail);
-  });
+      expect(t.trails.size).toBe(1);
+      expect(t.trails.get('create-user')).toBe(mod.myTrail);
+    });
 
-  test('auto-scans exports by kind discriminant', () => {
-    const mod = {
-      event1: mockEvent('e1'),
-      hike1: mockHike('r1'),
-      trail1: mockTrail('t1'),
-    };
-    const t = topo('app', mod);
-
-    expect(t.trails.size).toBe(1);
-    expect(t.hikes.size).toBe(1);
-    expect(t.events.size).toBe(1);
-  });
+    test('auto-scans exports by kind discriminant', () => {
+      const mod = {
+        event1: mockEvent('e1'),
+        trail1: mockTrail('t1'),
+        trail2: mockTrail('t2', ['t1']),
+      };
+      const t = topo('app', mod);
+
+      expect(t.trails.size).toBe(2);
+      expect(t.events.size).toBe(1);
+    });
 
-  test('collects from multiple modules', () => {
-    const mod1 = { a: mockTrail('t1') };
-    const mod2 = { b: mockTrail('t2'), c: mockHike('r1') };
-    const t = topo('app', mod1, mod2);
+    test('collects from multiple modules', () => {
+      const mod1 = { a: mockTrail('t1') };
+      const mod2 = { b: mockTrail('t2'), c: mockTrail('t3', ['t1']) };
+      const t = topo('app', mod1, mod2);
 
-    expect(t.trails.size).toBe(2);
-    expect(t.hikes.size).toBe(1);
-  });
+      expect(t.trails.size).toBe(3);
+    });
 
-  test('non-trail exports are silently ignored', () => {
-    const mod = {
-      config: { port: 3000 },
-      helper: () => 'not a trail',
-      name: 'some-string',
-      nothing: null,
-      num: 42,
-      trail1: mockTrail('t1'),
-      undef: undefined,
-    };
-    const t = topo('app', mod);
-
-    expect(t.trails.size).toBe(1);
-    expect(t.hikes.size).toBe(0);
-    expect(t.events.size).toBe(0);
+    test('non-trail exports are silently ignored', () => {
+      const mod = {
+        config: { port: 3000 },
+        helper: () => 'not a trail',
+        name: 'some-string',
+        nothing: null,
+        num: 42,
+        trail1: mockTrail('t1'),
+        undef: undefined,
+      };
+      const t = topo('app', mod);
+
+      expect(t.trails.size).toBe(1);
+      expect(t.events.size).toBe(0);
+    });
+
+    test('trail with follow registers correctly', () => {
+      const mod = { t: mockTrail('trail-1', ['trail-2']) };
+      const t = topo('app', mod);
+
+      expect(t.trails.size).toBe(1);
+      const registered = t.trails.get('trail-1');
+      expect(registered?.follow).toEqual(['trail-2']);
+    });
   });
 
-  test('rejects duplicate trail IDs', () => {
-    const mod1 = { a: mockTrail('dup') };
-    const mod2 = { b: mockTrail('dup') };
+  describe('duplicate rejection', () => {
+    test('rejects duplicate trail IDs', () => {
+      const mod1 = { a: mockTrail('dup') };
+      const mod2 = { b: mockTrail('dup') };
+
+      expect(() => topo('app', mod1, mod2)).toThrow(ValidationError);
+      expect(() => topo('app', mod1, mod2)).toThrow(
+        'Duplicate trail ID: "dup"'
+      );
+    });
+
+    test('rejects duplicate event IDs', () => {
+      const mod1 = { a: mockEvent('dup') };
+      const mod2 = { b: mockEvent('dup') };
 
-    expect(() => topo('app', mod1, mod2)).toThrow(ValidationError);
-    expect(() => topo('app', mod1, mod2)).toThrow('Duplicate trail ID: "dup"');
+      expect(() => topo('app', mod1, mod2)).toThrow(ValidationError);
+      expect(() => topo('app', mod1, mod2)).toThrow(
+        'Duplicate event ID: "dup"'
+      );
+    });
   });
+});
 
-  test('rejects duplicate hike IDs', () => {
-    const mod1 = { a: mockHike('dup') };
-    const mod2 = { b: mockHike('dup') };
+// ---------------------------------------------------------------------------
+// topo accessors
+// ---------------------------------------------------------------------------
 
-    expect(() => topo('app', mod1, mod2)).toThrow(ValidationError);
-    expect(() => topo('app', mod1, mod2)).toThrow('Duplicate hike ID: "dup"');
+describe('topo accessors', () => {
+  test('ids() returns all trail IDs', () => {
+    const a = mockTrail('alpha');
+    const b = mockTrail('beta');
+    const app = topo('test', { a, b });
+    expect(app.ids().toSorted()).toEqual(['alpha', 'beta']);
   });
 
-  test('rejects duplicate event IDs', () => {
-    const mod1 = { a: mockEvent('dup') };
-    const mod2 = { b: mockEvent('dup') };
+  test('count returns number of trails', () => {
+    const a = mockTrail('alpha');
+    const app = topo('test', { a });
+    expect(app.count).toBe(1);
+  });
 
-    expect(() => topo('app', mod1, mod2)).toThrow(ValidationError);
-    expect(() => topo('app', mod1, mod2)).toThrow('Duplicate event ID: "dup"');
+  test('empty topo has zero count and empty ids', () => {
+    const app = topo('empty');
+    expect(app.count).toBe(0);
+    expect(app.ids()).toEqual([]);
   });
 });
 
@@ -126,9 +148,9 @@ describe('topo', () => {
 describe('Topo', () => {
   const mod = {
     e1: mockEvent('event-1'),
-    h1: mockHike('hike-1'),
     t1: mockTrail('trail-1'),
     t2: mockTrail('trail-2'),
+    t3: mockTrail('trail-3', ['trail-1']),
   };
 
   // Build once for the describe block
@@ -139,8 +161,8 @@ describe('Topo', () => {
       expect(app.get('trail-1')).toBe(mod.t1);
     });
 
-    test('retrieves hike by ID', () => {
-      expect(app.get('hike-1')).toBe(mod.h1);
+    test('retrieves trail with follow by ID', () => {
+      expect(app.get('trail-3')).toBe(mod.t3);
     });
 
     test('returns undefined for unknown ID', () => {
@@ -153,26 +175,26 @@ describe('Topo', () => {
       expect(app.has('trail-1')).toBe(true);
     });
 
-    test('returns true for known hike', () => {
-      expect(app.has('hike-1')).toBe(true);
+    test('returns true for trail with follow', () => {
+      expect(app.has('trail-3')).toBe(true);
     });
 
     test('returns false for unknown ID', () => {
       expect(app.has('nope')).toBe(false);
     });
 
-    test('returns false for event ID (events are not trails/hikes)', () => {
+    test('returns false for event ID (events are not trails)', () => {
       expect(app.has('event-1')).toBe(false);
     });
   });
 
   describe('listing', () => {
-    test('list() returns all trails and hikes', () => {
+    test('list() returns all trails (with and without follow)', () => {
       const items = app.list();
       expect(items).toHaveLength(3);
       expect(items).toContain(mod.t1);
       expect(items).toContain(mod.t2);
-      expect(items).toContain(mod.h1);
+      expect(items).toContain(mod.t3);
     });
 
     test('listEvents() returns all events', () => {

package/src/__tests__/trail.test.ts

@@ -17,9 +17,9 @@ describe('trail()', () => {
 
   const greet = trail('greet', {
     description: 'Greet someone',
-    implementation: (input) => Result.ok({ greeting: `Hello, ${input.name}!` }),
     input: inputSchema,
     output: outputSchema,
+    run: (input) => Result.ok({ greeting: `Hello, ${input.name}!` }),
   });
 
   describe('basics', () => {
@@ -41,14 +41,14 @@ describe('trail()', () => {
 
     test('output schema is optional', () => {
       const minimal = trail('noop', {
-        implementation: () => Result.ok(),
         input: z.object({}),
+        run: () => Result.ok(),
       });
       expect(minimal.output).toBeUndefined();
     });
 
     test('implementation is callable', async () => {
-      const result = await greet.implementation({ name: 'World' }, stubCtx);
+      const result = await greet.run({ name: 'World' }, stubCtx);
       expect(result.isOk()).toBe(true);
       expect(result.unwrap()).toEqual({ greeting: 'Hello, World!' });
     });
@@ -61,8 +61,8 @@ describe('trail()', () => {
           { error: 'ValidationError', input: { text: '' }, name: 'error-case' },
           { expected: { text: 'hi' }, input: { text: 'hi' }, name: 'basic' },
         ],
-        implementation: (input) => Result.ok({ text: input.text }),
         input: z.object({ text: z.string() }),
+        run: (input) => Result.ok({ text: input.text }),
       });
       expect(withExamples.examples).toHaveLength(2);
       const first = withExamples.examples?.[0];
@@ -71,13 +71,13 @@ describe('trail()', () => {
       expect(second?.name).toBe('basic');
     });
 
-    test('markers are stored', () => {
-      const withMarkers = trail('tagged', {
-        implementation: () => Result.ok(),
+    test('metadata is stored', () => {
+      const withMetadata = trail('tagged', {
         input: z.object({}),
-        markers: { domain: 'billing', tier: 1 },
+        metadata: { domain: 'billing', tier: 1 },
+        run: () => Result.ok(),
       });
-      expect(withMarkers.markers).toEqual({ domain: 'billing', tier: 1 });
+      expect(withMetadata.metadata).toEqual({ domain: 'billing', tier: 1 });
     });
 
     test('detours are stored', () => {
@@ -86,8 +86,8 @@ describe('trail()', () => {
           onFailure: ['alert'],
           onSuccess: ['notify', 'audit'],
         },
-        implementation: () => Result.ok(),
         input: z.object({}),
+        run: () => Result.ok(),
       });
       expect(withDetours.detours).toEqual({
         onFailure: ['alert'],
@@ -96,28 +96,68 @@ describe('trail()', () => {
     });
   });
 
-  describe('boolean flags', () => {
-    test('boolean flags default to undefined', () => {
+  describe('follow', () => {
+    test('defaults to empty frozen array when omitted', () => {
       const minimal = trail('bare', {
-        implementation: () => Result.ok(),
         input: z.object({}),
+        run: () => Result.ok(),
       });
-      expect(minimal.readOnly).toBeUndefined();
-      expect(minimal.destructive).toBeUndefined();
+      expect(minimal.follow).toEqual([]);
+      expect(Object.isFrozen(minimal.follow)).toBe(true);
+    });
+
+    test('preserves follow array', () => {
+      const withFollow = trail('composed', {
+        follow: ['authenticate', 'validate-session'],
+        input: z.object({}),
+        run: () => Result.ok(),
+      });
+      expect(withFollow.follow).toEqual(['authenticate', 'validate-session']);
+    });
+
+    test('follow array is frozen', () => {
+      const withFollow = trail('composed', {
+        follow: ['authenticate'],
+        input: z.object({}),
+        run: () => Result.ok(),
+      });
+      expect(Object.isFrozen(withFollow.follow)).toBe(true);
+    });
+  });
+
+  describe('intent and idempotent', () => {
+    test('intent defaults to write', () => {
+      const minimal = trail('bare', {
+        input: z.object({}),
+        run: () => Result.ok(),
+      });
+      expect(minimal.intent).toBe('write');
       expect(minimal.idempotent).toBeUndefined();
     });
 
-    test('boolean flags are preserved when set', () => {
-      const withFlags = trail('flagged', {
-        destructive: false,
+    test('intent is preserved when set', () => {
+      const readTrail = trail('reader', {
+        input: z.object({}),
+        intent: 'read',
+        run: () => Result.ok(),
+      });
+      expect(readTrail.intent).toBe('read');
+
+      const destroyTrail = trail('destroyer', {
+        input: z.object({}),
+        intent: 'destroy',
+        run: () => Result.ok(),
+      });
+      expect(destroyTrail.intent).toBe('destroy');
+    });
+
+    test('idempotent is preserved when set', () => {
+      const t = trail('idempotent', {
         idempotent: true,
-        implementation: () => Result.ok(),
         input: z.object({}),
-        readOnly: true,
+        run: () => Result.ok(),
       });
-      expect(withFlags.readOnly).toBe(true);
-      expect(withFlags.destructive).toBe(false);
-      expect(withFlags.idempotent).toBe(true);
+      expect(t.idempotent).toBe(true);
     });
   });
 
@@ -125,9 +165,9 @@ describe('trail()', () => {
     test('accepts spec with id property', () => {
       const t = trail({
         id: 'entity.show',
-        implementation: (input: { name: string }, _ctx: TrailContext) =>
-          Result.ok({ greeting: `Hi, ${input.name}` }),
         input: inputSchema,
+        run: (input: { name: string }, _ctx: TrailContext) =>
+          Result.ok({ greeting: `Hi, ${input.name}` }),
       });
       expect(t.id).toBe('entity.show');
       expect(t.kind).toBe('trail');
@@ -136,39 +176,37 @@ describe('trail()', () => {
     test('preserves all spec fields', () => {
       const t = trail({
         description: 'A full trail',
-        destructive: false,
         examples: [{ input: { name: 'World' }, name: 'test' }],
         id: 'full',
-        implementation: (input: { name: string }, _ctx: TrailContext) =>
-          Result.ok({ greeting: `Hi, ${input.name}` }),
         input: inputSchema,
+        intent: 'read',
         output: outputSchema,
-        readOnly: true,
+        run: (input: { name: string }, _ctx: TrailContext) =>
+          Result.ok({ greeting: `Hi, ${input.name}` }),
       });
       expect(t.description).toBe('A full trail');
-      expect(t.readOnly).toBe(true);
+      expect(t.intent).toBe('read');
       expect(t.examples).toHaveLength(1);
     });
 
     test('implementation is callable', async () => {
       const t = trail({
         id: 'callable',
-        implementation: (input: { x: number }) => Result.ok(input.x * 2),
         input: z.object({ x: z.number() }),
+        run: (input: { x: number }) => Result.ok(input.x * 2),
       });
-      const result = await t.implementation({ x: 5 }, stubCtx);
+      const result = await t.run({ x: 5 }, stubCtx);
       expect(result.isOk()).toBe(true);
       expect(result.unwrap()).toBe(10);
     });
 
     test('sync implementations are normalized to an awaitable runtime function', async () => {
       const t = trail('normalized', {
-        implementation: (input: { value: number }) =>
-          Result.ok(input.value + 1),
         input: z.object({ value: z.number() }),
+        run: (input: { value: number }) => Result.ok(input.value + 1),
       });
 
-      const promise = t.implementation({ value: 2 }, stubCtx);
+      const promise = t.run({ value: 2 }, stubCtx);
       expect(promise).toBeInstanceOf(Promise);
 
       const result = await promise;