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

package/src/__tests__/type-utils.test.ts

@@ -0,0 +1,90 @@
+import { describe, expect, test } from 'bun:test';
+
+import { z } from 'zod';
+
+import { Result } from '../result';
+import { trail } from '../trail';
+import type { TrailInput, TrailOutput, TrailResult } from '../type-utils';
+import { inputOf, outputOf } from '../type-utils';
+
+const greetTrail = trail('greet', {
+  input: z.object({ name: z.string() }),
+  output: z.object({ message: z.string() }),
+  run: (input) => Result.ok({ message: `Hello, ${input.name}!` }),
+});
+
+const noOutputTrail = trail('ping', {
+  input: z.object({}),
+  run: () => Result.ok(),
+});
+
+describe('type-utils', () => {
+  describe('inputOf', () => {
+    test('returns the Zod input schema and can parse valid input', () => {
+      const schema = inputOf(greetTrail);
+      const result = schema.safeParse({ name: 'Alice' });
+      expect(result.success).toBe(true);
+      expect(
+        (result as { success: true; data: { name: string } }).data
+      ).toEqual({
+        name: 'Alice',
+      });
+    });
+
+    test('preserves specific schema type so .shape is accessible', () => {
+      const schema = inputOf(greetTrail);
+      // .shape is only available on z.ZodObject, not the broader z.ZodType
+      expect(schema.shape).toBeDefined();
+      expect(schema.shape.name).toBeDefined();
+    });
+  });
+
+  describe('outputOf', () => {
+    test('returns the Zod output schema when defined', () => {
+      const schema = outputOf(greetTrail);
+      expect(schema).toBeDefined();
+      // oxlint-disable-next-line no-non-null-assertion -- guarded by toBeDefined() above
+      const result = schema!.safeParse({ message: 'hello' });
+      expect(result.success).toBe(true);
+    });
+
+    test('returns undefined when no output schema', () => {
+      const schema = outputOf(noOutputTrail);
+      expect(schema).toBeUndefined();
+    });
+  });
+
+  describe('type-level checks', () => {
+    test('TrailInput matches expected shape', () => {
+      // If this compiles, the type is correct
+      const _input: TrailInput<typeof greetTrail> = { name: 'test' };
+      expect(_input.name).toBe('test');
+    });
+
+    test('TrailOutput matches expected shape', () => {
+      // If this compiles, the type is correct
+      const _output: TrailOutput<typeof greetTrail> = { message: 'hello' };
+      expect(_output.message).toBe('hello');
+    });
+  });
+
+  describe('TrailResult', () => {
+    test('extracts Result<Output, Error> from a trail', () => {
+      const t = trail('test.result', {
+        input: z.object({ q: z.string() }),
+        output: z.object({ answer: z.string() }),
+        run: (input) => Result.ok({ answer: input.q }),
+      });
+
+      type Expected = Result<{ answer: string }, Error>;
+      type Actual = TrailResult<typeof t>;
+
+      // Compile-time check: assignment works in both directions
+      const _check1: Expected = {} as Actual;
+      const _check2: Actual = {} as Expected;
+
+      // Runtime: type exists and is usable
+      expect(true).toBe(true);
+    });
+  });
+});

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

@@ -3,6 +3,7 @@ import { describe, expect, test } from 'bun:test';
 import { z } from 'zod';
 
 import { Result } from '../result.js';
+import { service } from '../service.js';
 import { topo } from '../topo.js';
 import type { TopoIssue } from '../validate-topo.js';
 import { validateTopo } from '../validate-topo.js';
@@ -17,6 +18,7 @@ const noop = async () => Result.ok();
 const mockTrail = (
   id: string,
   overrides?: {
+    follow?: readonly string[];
     examples?: readonly {
       name: string;
       input: unknown;
@@ -24,22 +26,22 @@ const mockTrail = (
       error?: string;
     }[];
     output?: z.ZodType;
+    services?: readonly ReturnType<typeof service>[];
   }
 ) => ({
+  follow: Object.freeze([...(overrides?.follow ?? [])]),
   id,
-  implementation: noop,
   input: z.object({ name: z.string() }),
   kind: 'trail' as const,
+  run: noop,
+  services: Object.freeze([...(overrides?.services ?? [])]),
   ...overrides,
 });
 
-const mockHike = (id: string, follows: readonly string[]) => ({
-  follows,
-  id,
-  implementation: noop,
-  input: z.object({ q: z.string() }),
-  kind: 'hike' as const,
-});
+const mockService = (id: string) =>
+  service(id, {
+    create: () => Result.ok({ id }),
+  });
 
 const mockEvent = (id: string, from?: readonly string[]) => ({
   from,
@@ -65,7 +67,9 @@ describe('validateTopo', () => {
   test('valid topo passes', () => {
     const app = topo('app', {
       add: mockTrail('entity.add'),
-      onboard: mockHike('entity.onboard', ['entity.add']),
+      onboard: mockTrail('entity.onboard', {
+        follow: ['entity.add'],
+      }),
       updated: mockEvent('entity.updated', ['entity.add']),
     });
 
@@ -73,10 +77,12 @@ describe('validateTopo', () => {
     expect(result.isOk()).toBe(true);
   });
 
-  describe('hike follows', () => {
-    test('hike following non-existent trail fails', () => {
+  describe('trail follow', () => {
+    test('trail following non-existent trail fails', () => {
       const app = topo('app', {
-        onboard: mockHike('entity.onboard', ['entity.missing']),
+        onboard: mockTrail('entity.onboard', {
+          follow: ['entity.missing'],
+        }),
       });
 
       const result = validateTopo(app);
@@ -84,13 +90,85 @@ describe('validateTopo', () => {
 
       const issues = extractIssues(result);
       expect(issues).toHaveLength(1);
-      expect(issues[0]?.rule).toBe('follows-exist');
+      expect(issues[0]?.rule).toBe('follow-exists');
       expect(issues[0]?.message).toContain('entity.missing');
     });
 
-    test('hike following itself fails', () => {
+    test('trail following itself fails', () => {
+      const app = topo('app', {
+        loop: mockTrail('entity.loop', { follow: ['entity.loop'] }),
+      });
+
+      const result = validateTopo(app);
+      expect(result.isErr()).toBe(true);
+
+      const issues = extractIssues(result);
+      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: mockTrail('a', { follow: ['b'] }),
+        b: mockTrail('b', { follow: ['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: mockTrail('a', { follow: ['b'] }),
+        b: mockTrail('b', { follow: ['c'] }),
+        c: mockTrail('c', { follow: ['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: mockTrail('a', { follow: ['c'] }),
+        b: mockTrail('b', { follow: ['c'] }),
+        c: mockTrail('c'),
+      });
+
+      const result = validateTopo(app);
+      expect(result.isOk()).toBe(true);
+    });
+  });
+
+  describe('service declarations', () => {
+    test('trail declaring a registered service passes', () => {
+      const db = mockService('db.main');
+      const app = topo('app', {
+        db,
+        show: mockTrail('entity.show', {
+          services: [db],
+        }),
+      });
+
+      const result = validateTopo(app);
+      expect(result.isOk()).toBe(true);
+    });
+
+    test('trail declaring a missing service fails', () => {
+      const db = mockService('db.main');
       const app = topo('app', {
-        loop: mockHike('entity.loop', ['entity.loop']),
+        show: mockTrail('entity.show', {
+          services: [db],
+        }),
       });
 
       const result = validateTopo(app);
@@ -98,7 +176,8 @@ describe('validateTopo', () => {
 
       const issues = extractIssues(result);
       expect(issues).toHaveLength(1);
-      expect(issues[0]?.rule).toBe('no-self-follow');
+      expect(issues[0]?.rule).toBe('service-exists');
+      expect(issues[0]?.message).toContain('db.main');
     });
   });
 
@@ -140,7 +219,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 +235,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', () => {
@@ -184,8 +301,12 @@ describe('validateTopo', () => {
   });
 
   test('collects multiple issues', () => {
+    const db = mockService('db.main');
     const app = topo('app', {
-      broken: mockHike('entity.broken', ['entity.missing']),
+      broken: mockTrail('entity.broken', { follow: ['entity.missing'] }),
+      missingService: mockTrail('entity.missing-service', {
+        services: [db],
+      }),
       show: mockTrail('entity.show', {
         examples: [{ input: { name: 123 }, name: 'Bad' }],
       }),
@@ -196,6 +317,6 @@ describe('validateTopo', () => {
     expect(result.isErr()).toBe(true);
 
     const issues = extractIssues(result);
-    expect(issues).toHaveLength(3);
+    expect(issues).toHaveLength(4);
   });
 });

package/src/__tests__/validation.test.ts

@@ -280,4 +280,57 @@ describe('zodToJsonSchema', () => {
       expect(zodToJsonSchema(z.any())).toEqual({});
     });
   });
+
+  describe('default values', () => {
+    test('preserves static defaults as-is', () => {
+      const schema = z.string().default('hello');
+      expect(zodToJsonSchema(schema)).toEqual({
+        default: 'hello',
+        type: 'string',
+      });
+    });
+
+    test('omits dynamic defaults that produce different values', () => {
+      let counter = 0;
+      const schema = z.string().default(() => {
+        counter += 1;
+        return `id-${counter}`;
+      });
+      const result = zodToJsonSchema(schema);
+      expect(result).toEqual({ type: 'string' });
+      expect(result['default']).toBeUndefined();
+    });
+
+    test('preserves stable functional defaults that return constant values', () => {
+      const schema = z.string().default(() => 'constant');
+      const result = zodToJsonSchema(schema);
+      expect(result).toEqual({ default: 'constant', type: 'string' });
+    });
+
+    test('preserves stable functional defaults that return equivalent objects', () => {
+      const schema = z
+        .object({ key: z.string() })
+        .default(() => ({ key: 'val' }));
+      const result = zodToJsonSchema(schema);
+      expect(result['default']).toEqual({ key: 'val' });
+    });
+
+    test('preserves stable functional defaults that return equivalent arrays', () => {
+      const schema = z.array(z.string()).default(() => ['a', 'b']);
+      const result = zodToJsonSchema(schema);
+      expect(result['default']).toEqual(['a', 'b']);
+    });
+
+    test('produces identical output across repeated calls', () => {
+      let counter = 0;
+      const schema = z.string().default(() => {
+        counter += 1;
+        return `id-${counter}`;
+      });
+      const first = zodToJsonSchema(schema);
+      const second = zodToJsonSchema(schema);
+      // Key invariant: repeated calls always produce the same schema
+      expect(first).toEqual(second);
+    });
+  });
 });

package/src/context.ts

@@ -1,4 +1,9 @@
-import type { TrailContext } from './types.js';
+import { createServiceLookup } from './service.js';
+import type { TrailContext, TrailContextInit } from './types.js';
+
+type MutableTrailContext = {
+  -readonly [K in keyof TrailContext]: TrailContext[K];
+};
 
 /**
  * Create a TrailContext with sensible defaults.
@@ -8,11 +13,15 @@ import type { TrailContext } from './types.js';
  * - All other fields come from `overrides`
  */
 export const createTrailContext = (
-  overrides?: Partial<TrailContext>
-): TrailContext => ({
-  cwd: process.cwd(),
-  env: process.env as Record<string, string | undefined>,
-  requestId: Bun.randomUUIDv7(),
-  signal: new AbortController().signal,
-  ...overrides,
-});
+  overrides?: Partial<TrailContextInit>
+): TrailContext => {
+  const ctx = {
+    cwd: process.cwd(),
+    env: process.env as Record<string, string | undefined>,
+    requestId: Bun.randomUUIDv7(),
+    signal: new AbortController().signal,
+    ...overrides,
+  } as MutableTrailContext;
+  ctx.service = overrides?.service ?? createServiceLookup(() => ctx);
+  return ctx;
+};

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/dispatch.ts

@@ -0,0 +1,54 @@
+/**
+ * Headless trail execution — the "no-surface" surface.
+ *
+ * Looks up a trail by ID in a topo, then delegates to `executeTrail`.
+ * Returns a `Result` and never throws.
+ */
+
+import type { Topo } from './topo.js';
+import { executeTrail } from './execute.js';
+import type { ExecuteTrailOptions } from './execute.js';
+import { NotFoundError } from './errors.js';
+import { Result } from './result.js';
+
+// ---------------------------------------------------------------------------
+// Options
+// ---------------------------------------------------------------------------
+
+/** Options forwarded to `executeTrail` from `dispatch`. */
+export type DispatchOptions = ExecuteTrailOptions;
+
+// ---------------------------------------------------------------------------
+// dispatch()
+// ---------------------------------------------------------------------------
+
+/**
+ * Execute a trail by ID from a topo without mounting a surface.
+ *
+ * Resolves the trail from the topo, then runs it through the standard
+ * `executeTrail` pipeline. Returns `Result.err(NotFoundError)` if the
+ * trail ID is not registered. Never throws — unexpected exceptions are
+ * returned as `Result.err(InternalError)`.
+ *
+ * @example
+ * ```typescript
+ * const result = await dispatch(myTopo, 'greet', { name: 'Alice' });
+ * if (result.isOk()) console.log(result.value);
+ * ```
+ */
+export const dispatch = (
+  topo: Topo,
+  id: string,
+  input: unknown,
+  options?: DispatchOptions
+): Promise<Result<unknown, Error>> => {
+  const trail = topo.get(id);
+  if (trail === undefined) {
+    return Promise.resolve(
+      Result.err(
+        new NotFoundError(`Trail "${id}" not found in topo "${topo.name}"`)
+      )
+    );
+  }
+  return executeTrail(trail, input, options);
+};

package/src/event.ts

@@ -11,7 +11,7 @@ import type { z } from 'zod';
 export interface EventSpec<T> {
   readonly payload: z.ZodType<T>;
   readonly description?: string | undefined;
-  readonly markers?: Readonly<Record<string, unknown>> | undefined;
+  readonly metadata?: Readonly<Record<string, unknown>> | undefined;
   /** Trail IDs that produce this event (e.g. the trails it originates from). */
   readonly from?: readonly string[] | undefined;
 }
@@ -25,7 +25,7 @@ export interface Event<T> {
   readonly kind: 'event';
   readonly payload: z.ZodType<T>;
   readonly description?: string | undefined;
-  readonly markers?: Readonly<Record<string, unknown>> | undefined;
+  readonly metadata?: Readonly<Record<string, unknown>> | undefined;
   /** Trail IDs that produce this event (e.g. the trails it originates from). */
   readonly from?: readonly string[] | undefined;
 }
@@ -68,7 +68,7 @@ export function event<T>(
     from: resolvedSpec.from ? Object.freeze([...resolvedSpec.from]) : undefined,
     id: resolvedId,
     kind: 'event' as const,
-    markers: resolvedSpec.markers,
+    metadata: resolvedSpec.metadata,
     payload: resolvedSpec.payload,
   });
 }