@ontrails/core 1.0.0-beta.2 → 1.0.0-beta.3

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

@@ -42,80 +42,116 @@ 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'),
+        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('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: mockHike('r1') };
+      const t = topo('app', mod1, mod2);
 
-    expect(t.trails.size).toBe(2);
-    expect(t.hikes.size).toBe(1);
-  });
+      expect(t.trails.size).toBe(2);
+      expect(t.hikes.size).toBe(1);
+    });
 
-  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.hikes.size).toBe(0);
+      expect(t.events.size).toBe(0);
+    });
 
-  test('rejects duplicate trail IDs', () => {
-    const mod1 = { a: mockTrail('dup') };
-    const mod2 = { b: mockTrail('dup') };
+    test('allows different IDs across trails and hikes', () => {
+      const mod = { h: mockHike('hike-1'), t: mockTrail('trail-1') };
+      const t = topo('app', mod);
 
-    expect(() => topo('app', mod1, mod2)).toThrow(ValidationError);
-    expect(() => topo('app', mod1, mod2)).toThrow('Duplicate trail ID: "dup"');
+      expect(t.trails.size).toBe(1);
+      expect(t.hikes.size).toBe(1);
+    });
   });
 
-  test('rejects duplicate hike IDs', () => {
-    const mod1 = { a: mockHike('dup') };
-    const mod2 = { b: mockHike('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 hike ID: "dup"');
-  });
+      expect(() => topo('app', mod1, mod2)).toThrow(ValidationError);
+      expect(() => topo('app', mod1, mod2)).toThrow(
+        'Duplicate trail ID: "dup"'
+      );
+    });
+
+    test('rejects duplicate hike IDs', () => {
+      const mod1 = { a: mockHike('dup') };
+      const mod2 = { b: mockHike('dup') };
+
+      expect(() => topo('app', mod1, mod2)).toThrow(ValidationError);
+      expect(() => topo('app', mod1, mod2)).toThrow('Duplicate hike ID: "dup"');
+    });
+
+    test('rejects duplicate event IDs', () => {
+      const mod1 = { a: mockEvent('dup') };
+      const mod2 = { b: mockEvent('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 event ID: "dup"'
+      );
+    });
 
-    expect(() => topo('app', mod1, mod2)).toThrow(ValidationError);
-    expect(() => topo('app', mod1, mod2)).toThrow('Duplicate event ID: "dup"');
+    test('rejects a hike whose ID collides with an existing trail', () => {
+      const modTrail = { a: mockTrail('shared-id') };
+      const modHike = { b: mockHike('shared-id') };
+
+      expect(() => topo('app', modTrail, modHike)).toThrow(ValidationError);
+      expect(() => topo('app', modTrail, modHike)).toThrow(
+        /ID collision.*hike "shared-id".*trail/
+      );
+    });
+
+    test('rejects a trail whose ID collides with an existing hike', () => {
+      const modHike = { a: mockHike('shared-id') };
+      const modTrail = { b: mockTrail('shared-id') };
+
+      expect(() => topo('app', modHike, modTrail)).toThrow(ValidationError);
+      expect(() => topo('app', modHike, modTrail)).toThrow(
+        /ID collision.*trail "shared-id".*hike/
+      );
+    });
   });
 });
 

package/src/__tests__/validate-topo.test.ts

@@ -97,8 +97,49 @@ describe('validateTopo', () => {
       expect(result.isErr()).toBe(true);
 
       const issues = extractIssues(result);
-      expect(issues).toHaveLength(1);
-      expect(issues[0]?.rule).toBe('no-self-follow');
+      expect(issues.some((i) => i.rule === 'no-self-follow')).toBe(true);
+    });
+
+    test('two-node cycle (a→b→a) is detected', () => {
+      const app = topo('app', {
+        a: mockHike('a', ['b']),
+        b: mockHike('b', ['a']),
+      });
+
+      const result = validateTopo(app);
+      expect(result.isErr()).toBe(true);
+
+      const issues = extractIssues(result);
+      const cycleIssues = issues.filter((i) => i.rule === 'follow-cycle');
+      expect(cycleIssues.length).toBeGreaterThanOrEqual(1);
+      expect(cycleIssues[0]?.message).toContain('Cycle detected');
+    });
+
+    test('three-node cycle (a→b→c→a) is detected', () => {
+      const app = topo('app', {
+        a: mockHike('a', ['b']),
+        b: mockHike('b', ['c']),
+        c: mockHike('c', ['a']),
+      });
+
+      const result = validateTopo(app);
+      expect(result.isErr()).toBe(true);
+
+      const issues = extractIssues(result);
+      const cycleIssues = issues.filter((i) => i.rule === 'follow-cycle');
+      expect(cycleIssues.length).toBeGreaterThanOrEqual(1);
+      expect(cycleIssues[0]?.message).toContain('Cycle detected');
+    });
+
+    test('valid DAG with shared targets is not flagged', () => {
+      const app = topo('app', {
+        a: mockHike('a', ['c']),
+        b: mockHike('b', ['c']),
+        c: mockHike('c', []),
+      });
+
+      const result = validateTopo(app);
+      expect(result.isOk()).toBe(true);
     });
   });
 
@@ -140,7 +181,7 @@ describe('validateTopo', () => {
       expect(issues[0]?.rule).toBe('output-schema-present');
     });
 
-    test('error example with invalid input is allowed', () => {
+    test('ValidationError example with invalid input is allowed', () => {
       const app = topo('app', {
         show: mockTrail('entity.show', {
           examples: [
@@ -156,6 +197,44 @@ describe('validateTopo', () => {
       const result = validateTopo(app);
       expect(result.isOk()).toBe(true);
     });
+
+    test('NotFoundError example with invalid input fails', () => {
+      const app = topo('app', {
+        show: mockTrail('entity.show', {
+          examples: [
+            {
+              error: 'NotFoundError',
+              input: { name: 123 },
+              name: 'Not found case',
+            },
+          ],
+        }),
+      });
+
+      const result = validateTopo(app);
+      expect(result.isErr()).toBe(true);
+
+      const issues = extractIssues(result);
+      expect(issues).toHaveLength(1);
+      expect(issues[0]?.rule).toBe('example-input-valid');
+    });
+
+    test('NotFoundError example with valid input passes', () => {
+      const app = topo('app', {
+        show: mockTrail('entity.show', {
+          examples: [
+            {
+              error: 'NotFoundError',
+              input: { name: 'test' },
+              name: 'Not found case',
+            },
+          ],
+        }),
+      });
+
+      const result = validateTopo(app);
+      expect(result.isOk()).toBe(true);
+    });
   });
 
   describe('event origins', () => {

package/src/derive.ts

@@ -14,7 +14,14 @@ import type { z } from 'zod';
 /** A surface-agnostic field descriptor derived from a Zod schema. */
 export interface Field {
   readonly name: string;
-  readonly type: 'string' | 'number' | 'boolean' | 'enum' | 'multiselect';
+  readonly type:
+    | 'string'
+    | 'number'
+    | 'boolean'
+    | 'enum'
+    | 'multiselect'
+    | 'string[]'
+    | 'number[]';
   readonly label: string;
   readonly required: boolean;
   readonly default?: unknown | undefined;
@@ -141,7 +148,10 @@ const fieldTypeByDef: Record<string, (s: ZodInternals) => DerivedFieldType> = {
       const entries = element._zod.def['entries'] as Record<string, string>;
       return { options: Object.values(entries), type: 'multiselect' };
     }
-    return { options: undefined, type: 'string' };
+    return {
+      options: undefined,
+      type: elementType === 'number' ? 'number[]' : 'string[]',
+    };
   },
   boolean: () => ({ options: undefined, type: 'boolean' }),
   enum: (s) => {

package/src/index.ts

@@ -133,6 +133,10 @@ export {
   getRelativePath,
 } from './workspace.js';
 
+// Blob
+export { createBlobRef, isBlobRef } from './blob-ref.js';
+export type { BlobRef } from './blob-ref.js';
+
 // Guards
 export {
   isDefined,

package/src/result.ts

@@ -151,16 +151,30 @@ export const Result = {
    */
   toJson(value: unknown): Result<string, InternalError> {
     try {
-      const seen = new WeakSet();
-      const json = JSON.stringify(value, (_key, val: unknown) => {
+      // Track the current ancestor chain, not every object ever visited.
+      // This allows shared references in a DAG while still detecting cycles.
+      const stack: unknown[] = [];
+      const keys: string[] = [];
+
+      const json = JSON.stringify(value, function json(key, val: unknown) {
+        if (stack.length > 0) {
+          // `this` is the object that contains `key`. Trim the stack back
+          // to `this` so we only track the current ancestor path.
+          const thisIndex = stack.lastIndexOf(this as unknown);
+          stack.splice(thisIndex + 1);
+          keys.splice(thisIndex);
+        }
+
         if (typeof val === 'object' && val !== null) {
-          if (seen.has(val)) {
+          if (stack.includes(val)) {
             return '[Circular]';
           }
-          seen.add(val);
+          stack.push(val);
+          keys.push(key);
         }
         return val;
       });
+
       if (json === undefined) {
         return new Err(
           new InternalError('Value is not JSON-serializable', {

package/src/serialization.ts

@@ -8,7 +8,10 @@
 import type { ErrorCategory, TrailsError } from './errors.js';
 import {
   ValidationError,
+  AmbiguousError,
+  AssertionError,
   NotFoundError,
+  AlreadyExistsError,
   ConflictError,
   PermissionError,
   TimeoutError,
@@ -89,6 +92,31 @@ const createErrorByCategory = (
   return factory(message, opts, retryAfter);
 };
 
+/** Map error class names to their constructors for precise round-tripping. */
+const errorConstructorsByName: Record<string, ErrorFactory> = {
+  AlreadyExistsError: (msg, opts) => new AlreadyExistsError(msg, opts),
+  AmbiguousError: (msg, opts) => new AmbiguousError(msg, opts),
+  AssertionError: (msg, opts) => new AssertionError(msg, opts),
+  AuthError: (msg, opts) => new AuthError(msg, opts),
+  CancelledError: (msg, opts) => new CancelledError(msg, opts),
+  ConflictError: (msg, opts) => new ConflictError(msg, opts),
+  InternalError: (msg, opts) => new InternalError(msg, opts),
+  NetworkError: (msg, opts) => new NetworkError(msg, opts),
+  NotFoundError: (msg, opts) => new NotFoundError(msg, opts),
+  PermissionError: (msg, opts) => new PermissionError(msg, opts),
+  RateLimitError: (msg, opts, retryAfter) => {
+    const rlOpts: { context?: Record<string, unknown>; retryAfter?: number } = {
+      ...opts,
+    };
+    if (retryAfter !== undefined) {
+      rlOpts.retryAfter = retryAfter;
+    }
+    return new RateLimitError(msg, rlOpts);
+  },
+  TimeoutError: (msg, opts) => new TimeoutError(msg, opts),
+  ValidationError: (msg, opts) => new ValidationError(msg, opts),
+};
+
 // ---------------------------------------------------------------------------
 // Error serialization
 // ---------------------------------------------------------------------------
@@ -117,13 +145,17 @@ export const serializeError = (error: Error): SerializedError => {
 
 /** Reconstruct a TrailsError from serialized data. */
 export const deserializeError = (data: SerializedError): TrailsError => {
-  const category = data.category ?? 'internal';
-  const error = createErrorByCategory(
-    category,
-    data.message,
-    data.context,
-    data.retryAfter
-  );
+  const opts = buildOpts(data.context);
+  const nameFactory = errorConstructorsByName[data.name];
+
+  const error = nameFactory
+    ? nameFactory(data.message, opts, data.retryAfter)
+    : createErrorByCategory(
+        data.category ?? 'internal',
+        data.message,
+        data.context,
+        data.retryAfter
+      );
 
   if (data.stack) {
     error.stack = data.stack;
@@ -155,13 +187,26 @@ export const safeStringify = (
   value: unknown
 ): Result<string, InternalError> => {
   try {
-    const seen = new WeakSet();
-    const json = JSON.stringify(value, (_key, val: unknown) => {
+    // Track the current ancestor chain, not every object ever visited.
+    // This allows shared references in a DAG while still detecting cycles.
+    const stack: unknown[] = [];
+    const keys: string[] = [];
+
+    const json = JSON.stringify(value, function json(key, val: unknown) {
+      if (stack.length > 0) {
+        // `this` is the object that contains `key`. Trim the stack back
+        // to `this` so we only track the current ancestor path.
+        const thisIndex = stack.lastIndexOf(this as unknown);
+        stack.splice(thisIndex + 1);
+        keys.splice(thisIndex);
+      }
+
       if (typeof val === 'object' && val !== null) {
-        if (seen.has(val)) {
+        if (stack.includes(val)) {
           return '[Circular]';
         }
-        seen.add(val);
+        stack.push(val);
+        keys.push(key);
       }
       return val;
     });

package/src/topo.ts

@@ -91,12 +91,22 @@ const register = (
       if (hikes.has(id)) {
         throw new ValidationError(`Duplicate hike ID: "${id}"`);
       }
+      if (trails.has(id)) {
+        throw new ValidationError(
+          `ID collision: hike "${id}" conflicts with an existing trail of the same ID`
+        );
+      }
       hikes.set(id, value as AnyHike);
     },
     trail: () => {
       if (trails.has(id)) {
         throw new ValidationError(`Duplicate trail ID: "${id}"`);
       }
+      if (hikes.has(id)) {
+        throw new ValidationError(
+          `ID collision: trail "${id}" conflicts with an existing hike of the same ID`
+        );
+      }
       trails.set(id, value as AnyTrail);
     },
   };