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

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

@@ -17,6 +17,7 @@ const noop = async () => Result.ok();
 const mockTrail = (
   id: string,
   overrides?: {
+    follow?: readonly string[];
     examples?: readonly {
       name: string;
       input: unknown;
@@ -26,21 +27,14 @@ const mockTrail = (
     output?: z.ZodType;
   }
 ) => ({
+  follow: Object.freeze([...(overrides?.follow ?? [])]),
   id,
-  implementation: noop,
   input: z.object({ name: z.string() }),
   kind: 'trail' as const,
+  run: noop,
   ...overrides,
 });
 
-const mockHike = (id: string, follows: readonly string[]) => ({
-  follows,
-  id,
-  implementation: noop,
-  input: z.object({ q: z.string() }),
-  kind: 'hike' as const,
-});
-
 const mockEvent = (id: string, from?: readonly string[]) => ({
   from,
   id,
@@ -65,7 +59,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 +69,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,21 +82,62 @@ 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: mockHike('entity.loop', ['entity.loop']),
+        loop: mockTrail('entity.loop', { follow: ['entity.loop'] }),
       });
 
       const result = validateTopo(app);
       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: 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);
     });
   });
 
@@ -140,7 +179,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 +195,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', () => {
@@ -185,7 +262,7 @@ describe('validateTopo', () => {
 
   test('collects multiple issues', () => {
     const app = topo('app', {
-      broken: mockHike('entity.broken', ['entity.missing']),
+      broken: mockTrail('entity.broken', { follow: ['entity.missing'] }),
       show: mockTrail('entity.show', {
         examples: [{ input: { name: 123 }, name: 'Bad' }],
       }),

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

package/src/execute.ts

@@ -0,0 +1,96 @@
+/**
+ * Centralized trail execution pipeline.
+ *
+ * Validates input, builds context, composes layers, and runs the
+ * implementation. Surfaces (CLI, MCP, HTTP) delegate here instead
+ * of reimplementing the pipeline.
+ */
+
+import type { AnyTrail } from './trail.js';
+import type { Layer } from './layer.js';
+import type { TrailContext } from './types.js';
+
+import { composeLayers } from './layer.js';
+import { createTrailContext } from './context.js';
+import { InternalError } from './errors.js';
+import { Result } from './result.js';
+import { validateInput } from './validation.js';
+
+// ---------------------------------------------------------------------------
+// Options
+// ---------------------------------------------------------------------------
+
+/** Options for executeTrail. */
+export interface ExecuteTrailOptions {
+  /** Partial context overrides merged on top of the base context. */
+  readonly ctx?: Partial<TrailContext> | undefined;
+  /** AbortSignal override (takes final precedence over ctx and factory). */
+  readonly signal?: AbortSignal | undefined;
+  /** Layers to compose around the implementation. */
+  readonly layers?: readonly Layer[] | undefined;
+  /** Factory that produces a base TrailContext (takes precedence over defaults). */
+  readonly createContext?:
+    | (() => TrailContext | Promise<TrailContext>)
+    | undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Context resolution
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a TrailContext from options.
+ *
+ * Resolution order:
+ * 1. Factory (`createContext`) or `createTrailContext()` defaults.
+ * 2. Partial `ctx` overrides merged on top.
+ * 3. `signal` override takes final precedence.
+ */
+const resolveContext = async (
+  options?: ExecuteTrailOptions
+): Promise<TrailContext> => {
+  const base = options?.createContext
+    ? await options.createContext()
+    : createTrailContext();
+  const withOverrides = options?.ctx
+    ? {
+        ...base,
+        ...options.ctx,
+        extensions: { ...base.extensions, ...options.ctx.extensions },
+      }
+    : base;
+  return options?.signal
+    ? { ...withOverrides, signal: options.signal }
+    : withOverrides;
+};
+
+// ---------------------------------------------------------------------------
+// Pipeline
+// ---------------------------------------------------------------------------
+
+/**
+ * Execute a trail through the standard validate-context-layers-run pipeline.
+ *
+ * The function never throws -- unexpected exceptions are caught and
+ * returned as `Result.err(InternalError)`.
+ */
+export const executeTrail = async (
+  trail: AnyTrail,
+  rawInput: unknown,
+  options?: ExecuteTrailOptions
+): Promise<Result<unknown, Error>> => {
+  try {
+    const validated = validateInput(trail.input, rawInput);
+    if (validated.isErr()) {
+      return validated;
+    }
+
+    const ctx = await resolveContext(options);
+    const layers = options?.layers ?? [];
+    const impl = composeLayers([...layers], trail, trail.run);
+    return await impl(validated.value, ctx);
+  } catch (error: unknown) {
+    const message = error instanceof Error ? error.message : String(error);
+    return Result.err(new InternalError(message));
+  }
+};

package/src/index.ts

@@ -34,7 +34,6 @@ export type {
   ProgressCallback,
   ProgressEvent,
   Logger,
-  Surface,
 } from './types.js';
 
 // Context factory
@@ -42,11 +41,17 @@ export { createTrailContext } from './context.js';
 
 // Trail
 export { trail } from './trail.js';
-export type { AnyTrail, Trail, TrailSpec, TrailExample } from './trail.js';
+export type {
+  AnyTrail,
+  Intent,
+  Trail,
+  TrailSpec,
+  TrailExample,
+} from './trail.js';
 
-// Hike
-export { hike } from './hike.js';
-export type { AnyHike, Hike, HikeSpec } from './hike.js';
+// Type utilities
+export type { TrailInput, TrailOutput, TrailResult } from './type-utils.js';
+export { inputOf, outputOf } from './type-utils.js';
 
 // Event
 export { event } from './event.js';
@@ -64,23 +69,18 @@ export type { TopoIssue } from './validate-topo.js';
 export { composeLayers } from './layer.js';
 export type { Layer } from './layer.js';
 
-// Health
-export type { HealthStatus, HealthResult } from './health.js';
-
-// Adapters
-export type {
-  IndexAdapter,
-  StorageAdapter,
-  CacheAdapter,
-  SearchOptions,
-  SearchResult,
-  StorageOptions,
-} from './adapters.js';
-
 // Derive
 export { deriveFields } from './derive.js';
 export type { Field, FieldOverride } from './derive.js';
 
+// Execute
+export { executeTrail } from './execute.js';
+export type { ExecuteTrailOptions } from './execute.js';
+
+// Dispatch
+export { dispatch } from './dispatch.js';
+export type { DispatchOptions } from './dispatch.js';
+
 // Validation
 export {
   validateInput,
@@ -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

@@ -17,7 +17,7 @@ class Ok<T, E> {
   }
 
   // oxlint-disable-next-line class-methods-use-this -- type guard for Result discriminated union
-  isErr(): this is Err<T, E> {
+  isErr(): this is Err<E> {
     return false;
   }
 
@@ -47,7 +47,7 @@ class Ok<T, E> {
 }
 
 // oxlint-disable-next-line max-classes-per-file -- Result monad requires paired Ok/Err classes
-class Err<T, E> {
+class Err<E> {
   readonly error: E;
 
   constructor(error: E) {
@@ -55,28 +55,28 @@ class Err<T, E> {
   }
 
   // oxlint-disable-next-line class-methods-use-this -- type guard for Result discriminated union
-  isOk(): this is Ok<T, E> {
+  isOk(): this is Ok<never, E> {
     return false;
   }
 
   // oxlint-disable-next-line class-methods-use-this -- type guard for Result discriminated union
-  isErr(): this is Err<T, E> {
+  isErr(): this is Err<E> {
     return true;
   }
 
-  map<U>(_fn: (value: T) => U): Result<U, E> {
+  map<U>(_fn: (value: never) => U): Result<U, E> {
     return new Err(this.error);
   }
 
-  flatMap<U, F = E>(_fn: (value: T) => Result<U, F>): Result<U, E | F> {
+  flatMap<U, F = E>(_fn: (value: never) => Result<U, F>): Result<U, E | F> {
     return new Err(this.error);
   }
 
-  mapErr<F>(fn: (error: E) => F): Result<T, F> {
+  mapErr<F>(fn: (error: E) => F): Result<never, F> {
     return new Err(fn(this.error));
   }
 
-  match<U>(handlers: { ok: (value: T) => U; err: (error: E) => U }): U {
+  match<U>(handlers: { ok: (value: never) => U; err: (error: E) => U }): U {
     return handlers.err(this.error);
   }
 
@@ -87,12 +87,12 @@ class Err<T, E> {
   }
 
   // oxlint-disable-next-line class-methods-use-this -- symmetric API with Ok.unwrapOr
-  unwrapOr(fallback: T): T {
+  unwrapOr<T>(fallback: T): T {
     return fallback;
   }
 }
 
-export type Result<T, E = Error> = Ok<T, E> | Err<T, E>;
+export type Result<T, E = Error> = Ok<T, E> | Err<E>;
 
 // eslint-disable-next-line @typescript-eslint/no-namespace
 export const Result = {
@@ -107,7 +107,7 @@ export const Result = {
     return new Ok(values);
   },
 
-  err<E>(error: E): Result<never, E> {
+  err<E>(error: E): Err<E> {
     return new Err(error);
   },
 
@@ -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;
     });