@ontrails/core 1.0.0-beta.12 → 1.0.0-beta.13

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

@@ -8,14 +8,14 @@ import type { TrailInput, TrailOutput, TrailResult } from '../type-utils';
 import { inputOf, outputOf } from '../type-utils';
 
 const greetTrail = trail('greet', {
+  blaze: (input) => Result.ok({ message: `Hello, ${input.name}!` }),
   input: z.object({ name: z.string() }),
   output: z.object({ message: z.string() }),
-  run: (input) => Result.ok({ message: `Hello, ${input.name}!` }),
 });
 
 const noOutputTrail = trail('ping', {
+  blaze: () => Result.ok(),
   input: z.object({}),
-  run: () => Result.ok(),
 });
 
 describe('type-utils', () => {
@@ -71,9 +71,9 @@ describe('type-utils', () => {
   describe('TrailResult', () => {
     test('extracts Result<Output, Error> from a trail', () => {
       const t = trail('test.result', {
+        blaze: (input) => Result.ok({ answer: input.q }),
         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>;

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

@@ -2,8 +2,8 @@ import { describe, expect, test } from 'bun:test';
 
 import { z } from 'zod';
 
+import { provision } from '../provision.js';
 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';
@@ -18,7 +18,7 @@ const noop = async () => Result.ok();
 const mockTrail = (
   id: string,
   overrides?: {
-    follow?: readonly string[];
+    crosses?: readonly string[];
     examples?: readonly {
       name: string;
       input: unknown;
@@ -26,27 +26,27 @@ const mockTrail = (
       error?: string;
     }[];
     output?: z.ZodType;
-    services?: readonly ReturnType<typeof service>[];
+    provisions?: readonly ReturnType<typeof provision>[];
   }
 ) => ({
-  follow: Object.freeze([...(overrides?.follow ?? [])]),
+  blaze: noop,
+  crosses: Object.freeze([...(overrides?.crosses ?? [])]),
   id,
   input: z.object({ name: z.string() }),
   kind: 'trail' as const,
-  run: noop,
-  services: Object.freeze([...(overrides?.services ?? [])]),
+  provisions: Object.freeze([...(overrides?.provisions ?? [])]),
   ...overrides,
 });
 
-const mockService = (id: string) =>
-  service(id, {
+const mockProvision = (id: string) =>
+  provision(id, {
     create: () => Result.ok({ id }),
   });
 
 const mockEvent = (id: string, from?: readonly string[]) => ({
   from,
   id,
-  kind: 'event' as const,
+  kind: 'signal' as const,
   payload: z.object({ data: z.string() }),
 });
 
@@ -68,7 +68,7 @@ describe('validateTopo', () => {
     const app = topo('app', {
       add: mockTrail('entity.add'),
       onboard: mockTrail('entity.onboard', {
-        follow: ['entity.add'],
+        crosses: ['entity.add'],
       }),
       updated: mockEvent('entity.updated', ['entity.add']),
     });
@@ -77,11 +77,11 @@ describe('validateTopo', () => {
     expect(result.isOk()).toBe(true);
   });
 
-  describe('trail follow', () => {
-    test('trail following non-existent trail fails', () => {
+  describe('trail crossing', () => {
+    test('trail crossing a non-existent trail fails', () => {
       const app = topo('app', {
         onboard: mockTrail('entity.onboard', {
-          follow: ['entity.missing'],
+          crosses: ['entity.missing'],
         }),
       });
 
@@ -90,57 +90,57 @@ describe('validateTopo', () => {
 
       const issues = extractIssues(result);
       expect(issues).toHaveLength(1);
-      expect(issues[0]?.rule).toBe('follow-exists');
+      expect(issues[0]?.rule).toBe('cross-exists');
       expect(issues[0]?.message).toContain('entity.missing');
     });
 
-    test('trail following itself fails', () => {
+    test('trail crossing itself fails', () => {
       const app = topo('app', {
-        loop: mockTrail('entity.loop', { follow: ['entity.loop'] }),
+        loop: mockTrail('entity.loop', { crosses: ['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);
+      expect(issues.some((i) => i.rule === 'no-self-cross')).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'] }),
+        a: mockTrail('a', { crosses: ['b'] }),
+        b: mockTrail('b', { crosses: ['a'] }),
       });
 
       const result = validateTopo(app);
       expect(result.isErr()).toBe(true);
 
       const issues = extractIssues(result);
-      const cycleIssues = issues.filter((i) => i.rule === 'follow-cycle');
+      const cycleIssues = issues.filter((i) => i.rule === 'cross-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'] }),
+        a: mockTrail('a', { crosses: ['b'] }),
+        b: mockTrail('b', { crosses: ['c'] }),
+        c: mockTrail('c', { crosses: ['a'] }),
       });
 
       const result = validateTopo(app);
       expect(result.isErr()).toBe(true);
 
       const issues = extractIssues(result);
-      const cycleIssues = issues.filter((i) => i.rule === 'follow-cycle');
+      const cycleIssues = issues.filter((i) => i.rule === 'cross-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'] }),
+        a: mockTrail('a', { crosses: ['c'] }),
+        b: mockTrail('b', { crosses: ['c'] }),
         c: mockTrail('c'),
       });
 
@@ -149,13 +149,13 @@ describe('validateTopo', () => {
     });
   });
 
-  describe('service declarations', () => {
-    test('trail declaring a registered service passes', () => {
-      const db = mockService('db.main');
+  describe('provision declarations', () => {
+    test('trail declaring a registered provision passes', () => {
+      const db = mockProvision('db.main');
       const app = topo('app', {
         db,
         show: mockTrail('entity.show', {
-          services: [db],
+          provisions: [db],
         }),
       });
 
@@ -163,11 +163,11 @@ describe('validateTopo', () => {
       expect(result.isOk()).toBe(true);
     });
 
-    test('trail declaring a missing service fails', () => {
-      const db = mockService('db.main');
+    test('trail declaring a missing provision fails', () => {
+      const db = mockProvision('db.main');
       const app = topo('app', {
         show: mockTrail('entity.show', {
-          services: [db],
+          provisions: [db],
         }),
       });
 
@@ -176,7 +176,7 @@ describe('validateTopo', () => {
 
       const issues = extractIssues(result);
       expect(issues).toHaveLength(1);
-      expect(issues[0]?.rule).toBe('service-exists');
+      expect(issues[0]?.rule).toBe('provision-exists');
       expect(issues[0]?.message).toContain('db.main');
     });
   });
@@ -286,7 +286,7 @@ describe('validateTopo', () => {
 
       const issues = extractIssues(result);
       expect(issues).toHaveLength(1);
-      expect(issues[0]?.rule).toBe('event-origin-exists');
+      expect(issues[0]?.rule).toBe('signal-origin-exists');
       expect(issues[0]?.message).toContain('entity.ghost');
     });
 
@@ -301,11 +301,11 @@ describe('validateTopo', () => {
   });
 
   test('collects multiple issues', () => {
-    const db = mockService('db.main');
+    const db = mockProvision('db.main');
     const app = topo('app', {
-      broken: mockTrail('entity.broken', { follow: ['entity.missing'] }),
+      broken: mockTrail('entity.broken', { crosses: ['entity.missing'] }),
       missingService: mockTrail('entity.missing-service', {
-        services: [db],
+        provisions: [db],
       }),
       show: mockTrail('entity.show', {
         examples: [{ input: { name: 123 }, name: 'Bad' }],

package/src/context.ts

@@ -1,4 +1,4 @@
-import { createServiceLookup } from './service.js';
+import { createProvisionLookup } from './provision.js';
 import type { TrailContext, TrailContextInit } from './types.js';
 
 type MutableTrailContext = {
@@ -9,19 +9,20 @@ type MutableTrailContext = {
  * Create a TrailContext with sensible defaults.
  *
  * - `requestId` defaults to `Bun.randomUUIDv7()` (sortable v7 UUID)
- * - `signal` defaults to a fresh, non-aborted `AbortSignal`
+ * - `abortSignal` defaults to a fresh, non-aborted `AbortSignal`
  * - All other fields come from `overrides`
  */
 export const createTrailContext = (
   overrides?: Partial<TrailContextInit>
 ): TrailContext => {
   const ctx = {
+    abortSignal: new AbortController().signal,
     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);
+  const lookup = overrides?.provision ?? createProvisionLookup(() => ctx);
+  ctx.provision = lookup;
   return ctx;
 };

package/src/derive.ts

@@ -1,8 +1,8 @@
 /**
  * Schema-driven field derivation for @ontrails/core
  *
- * Introspects Zod v4 schemas to produce a surface-agnostic Field[] descriptor
- * that UI layers (CLI prompts, web forms, etc.) can consume.
+ * Introspects Zod v4 schemas to produce a runtime-agnostic Field[] descriptor
+ * that UI consumers (CLI prompts, web forms, etc.) can consume.
  */
 
 import type { z } from 'zod';
@@ -11,7 +11,7 @@ import type { z } from 'zod';
 // Public types
 // ---------------------------------------------------------------------------
 
-/** A surface-agnostic field descriptor derived from a Zod schema. */
+/** A runtime-agnostic field descriptor derived from a Zod schema. */
 export interface Field {
   readonly name: string;
   readonly type:
@@ -193,11 +193,6 @@ const buildOptions = (
 // Public API
 // ---------------------------------------------------------------------------
 
-/**
- * Derive a surface-agnostic Field[] from a Zod object schema.
- *
- * Uses Zod v4's `_zod.def` for introspection. Returns fields sorted by name.
- */
 /** Derive a single field from a shape entry. */
 const deriveField = (
   key: string,
@@ -212,6 +207,11 @@ const deriveField = (
   return { default: defaultValue, label, name: key, options, required, type };
 };
 
+/**
+ * Derive a runtime-agnostic Field[] from a Zod object schema.
+ *
+ * Uses Zod v4's `_zod.def` for introspection. Returns fields sorted by name.
+ */
 export const deriveFields = (
   schema: z.ZodType,
   overrides?: Record<string, FieldOverride>

package/src/event.ts

@@ -1,77 +1,15 @@
 /**
- * Event — a named payload schema with optional provenance metadata.
- */
-
-import type { z } from 'zod';
-
-// ---------------------------------------------------------------------------
-// Spec (input to the factory)
-// ---------------------------------------------------------------------------
-
-export interface EventSpec<T> {
-  readonly payload: z.ZodType<T>;
-  readonly description?: string | 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;
-}
-
-// ---------------------------------------------------------------------------
-// Shape (output of the factory)
-// ---------------------------------------------------------------------------
-
-export interface Event<T> {
-  readonly id: string;
-  readonly kind: 'event';
-  readonly payload: z.ZodType<T>;
-  readonly description?: string | 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;
-}
-
-// ---------------------------------------------------------------------------
-// Factory
-// ---------------------------------------------------------------------------
-
-/**
- * Create an event definition.
- *
- * An event is a named payload schema describing something that happened.
- * Returns a frozen object with `kind: "event"` and all spec fields.
- *
- * @example
- * ```typescript
- * // ID as first argument
- * const updated = event("entity.updated", {
- *   payload: EntityUpdatedSchema,
- *   from: ["entity.add", "entity.update"],
- * });
+ * Legacy event aliases for the signal model.
  *
- * // Full spec object (programmatic)
- * const updated = event({ id: "entity.updated", payload: ..., from: [...] });
- * ```
+ * Keep this file as a compatibility seam while the repo-wide cutover lands.
  */
-export function event<T>(id: string, spec: EventSpec<T>): Event<T>;
-export function event<T>(
-  spec: EventSpec<T> & { readonly id: string }
-): Event<T>;
-export function event<T>(
-  idOrSpec: string | (EventSpec<T> & { readonly id: string }),
-  maybeSpec?: EventSpec<T>
-): Event<T> {
-  const resolvedId = typeof idOrSpec === 'string' ? idOrSpec : idOrSpec.id;
-  // oxlint-disable-next-line no-non-null-assertion -- overload guarantees maybeSpec when idOrSpec is string
-  const resolvedSpec = typeof idOrSpec === 'string' ? maybeSpec! : idOrSpec;
-  return Object.freeze({
-    description: resolvedSpec.description,
-    from: resolvedSpec.from ? Object.freeze([...resolvedSpec.from]) : undefined,
-    id: resolvedId,
-    kind: 'event' as const,
-    metadata: resolvedSpec.metadata,
-    payload: resolvedSpec.payload,
-  });
-}
 
-/** Existential type for heterogeneous event collections */
-export type AnyEvent = Event<unknown>;
+export { signal as event } from './signal.js';
+export type {
+  AnySignal,
+  AnySignal as AnyEvent,
+  Signal,
+  Signal as Event,
+  SignalSpec,
+  SignalSpec as EventSpec,
+} from './signal.js';

package/src/execute.ts

@@ -1,22 +1,22 @@
 /**
  * Centralized trail execution pipeline.
  *
- * Validates input, builds context, composes layers, and runs the
+ * Validates input, builds context, composes gates, 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 { ServiceOverrideMap } from './service.js';
+import type { Gate } from './gate.js';
+import type { ProvisionOverrideMap } from './provision.js';
 import type { TrailContext, TrailContextInit } from './types.js';
 
-import { composeLayers } from './layer.js';
+import { composeGates } from './gate.js';
 import { createTrailContext } from './context.js';
 import { InternalError } from './errors.js';
 import { Result } from './result.js';
-import { createServiceLookup } from './service.js';
-import { resolveServices } from './service-config.js';
+import { createProvisionLookup } from './provision.js';
+import { resolveProvisions } from './provision-config.js';
 import { validateInput } from './validation.js';
 
 type MutableTrailContext = {
@@ -32,16 +32,16 @@ export interface ExecuteTrailOptions {
   /** Partial context overrides merged on top of the base context. */
   readonly ctx?: Partial<TrailContextInit> | 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;
+  readonly abortSignal?: AbortSignal | undefined;
+  /** Gates to compose around the implementation. */
+  readonly gates?: readonly Gate[] | undefined;
   /** Factory that produces a base TrailContext (takes precedence over defaults). */
   readonly createContext?:
     | (() => TrailContextInit | Promise<TrailContextInit>)
     | undefined;
-  /** Explicit service instance overrides keyed by service ID. */
-  readonly services?: ServiceOverrideMap | undefined;
-  /** Config values for services that declare a `config` schema, keyed by service ID. */
+  /** Explicit provision instance overrides keyed by provision ID. */
+  readonly provisions?: ProvisionOverrideMap | undefined;
+  /** Config values for provisions that declare a `config` schema, keyed by provision ID. */
   readonly configValues?:
     | Readonly<Record<string, Record<string, unknown>>>
     | undefined;
@@ -51,21 +51,10 @@ export interface ExecuteTrailOptions {
 // 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 (
+const applyContextOverrides = (
+  base: TrailContextInit,
   options?: ExecuteTrailOptions
-): Promise<TrailContext> => {
-  const seed = options?.createContext
-    ? await options.createContext()
-    : createTrailContext();
-  const base = seed.service ? seed : createTrailContext(seed);
+): TrailContextInit => {
   const withOverrides = options?.ctx
     ? {
         ...base,
@@ -73,19 +62,46 @@ const resolveContext = async (
         extensions: { ...base.extensions, ...options.ctx.extensions },
       }
     : base;
-  const resolved = options?.signal
-    ? { ...withOverrides, signal: options.signal }
+
+  return options?.abortSignal
+    ? { ...withOverrides, abortSignal: options.abortSignal }
     : withOverrides;
+};
+
+const bindProvisionLookup = (
+  resolved: TrailContextInit,
+  options?: ExecuteTrailOptions
+): TrailContext => {
   if (
-    options?.ctx?.extensions !== undefined ||
-    resolved.service === undefined
+    options?.ctx?.extensions === undefined &&
+    resolved.provision !== undefined
   ) {
-    const bound = { ...resolved } as MutableTrailContext;
-    bound.service = createServiceLookup(() => bound);
-    return bound;
+    return resolved as TrailContext;
   }
 
-  return resolved as TrailContext;
+  const bound = { ...resolved } as MutableTrailContext;
+  const lookup = createProvisionLookup(() => bound);
+  bound.provision = lookup;
+  return bound;
+};
+
+/**
+ * Build a TrailContext from options.
+ *
+ * Resolution order:
+ * 1. Factory (`createContext`) or `createTrailContext()` defaults.
+ * 2. Partial `ctx` overrides merged on top.
+ * 3. `abortSignal` override takes final precedence.
+ */
+const resolveContext = async (
+  options?: ExecuteTrailOptions
+): Promise<TrailContext> => {
+  const seed = options?.createContext
+    ? await options.createContext()
+    : createTrailContext();
+  const base = seed.provision ? seed : createTrailContext(seed);
+  const resolved = applyContextOverrides(base, options);
+  return bindProvisionLookup(resolved, options);
 };
 
 const prepareContext = async (
@@ -93,10 +109,10 @@ const prepareContext = async (
   options?: ExecuteTrailOptions
 ): Promise<Result<TrailContext, Error>> => {
   const baseCtx = await resolveContext(options);
-  return await resolveServices(
+  return await resolveProvisions(
     trail,
     baseCtx,
-    options?.services,
+    options?.provisions,
     options?.configValues
   );
 };
@@ -105,9 +121,9 @@ const runTrail = async (
   trail: AnyTrail,
   input: unknown,
   ctx: TrailContext,
-  layers: readonly Layer[]
+  gates: readonly Gate[]
 ): Promise<Result<unknown, Error>> => {
-  const impl = composeLayers([...layers], trail, trail.run);
+  const impl = composeGates([...gates], trail, trail.blaze);
   return await impl(input, ctx);
 };
 
@@ -116,7 +132,7 @@ const runTrail = async (
 // ---------------------------------------------------------------------------
 
 /**
- * Execute a trail through the standard validate-context-layers-run pipeline.
+ * Execute a trail through the standard validate-context-gates-run pipeline.
  *
  * The function never throws -- unexpected exceptions are caught and
  * returned as `Result.err(InternalError)`.
@@ -141,7 +157,7 @@ export const executeTrail = async (
       trail,
       validated.value,
       resolvedCtx.value,
-      options?.layers ?? []
+      options?.gates ?? []
     );
   } catch (error: unknown) {
     const message = error instanceof Error ? error.message : String(error);

package/src/{layer.ts → gate.ts}

@@ -2,15 +2,15 @@ import type { Trail } from './trail.js';
 import type { Implementation } from './types.js';
 
 // ---------------------------------------------------------------------------
-// Layer interface
+// Gate interface
 // ---------------------------------------------------------------------------
 
-/** A composable middleware that wraps trail implementations */
-export interface Layer {
+/** A composable gate that wraps trail implementations. */
+export interface Gate {
   readonly name: string;
   readonly description?: string | undefined;
 
-  /** Wrap a trail's implementation, returning a new implementation */
+  /** Wrap a trail's implementation, returning a new implementation. */
   wrap<I, O>(
     trail: Trail<I, O>,
     implementation: Implementation<I, O>
@@ -22,22 +22,22 @@ export interface Layer {
 // ---------------------------------------------------------------------------
 
 /**
- * Apply layers outermost-first: layers[0] wraps layers[1] wraps ... wraps
+ * Apply gates outermost-first: gates[0] wraps gates[1] wraps ... wraps
  * the base implementation.
  *
- * An empty layers array returns the implementation unchanged.
+ * An empty gates array returns the implementation unchanged.
  */
-export const composeLayers = <I, O>(
-  layers: readonly Layer[],
+export const composeGates = <I, O>(
+  gates: readonly Gate[],
   trail: Trail<I, O>,
   implementation: Implementation<I, O>
 ): Implementation<I, O> => {
-  // Fold right so layers[0] is the outermost wrapper
+  // Fold right so gates[0] is the outermost wrapper.
   let result = implementation;
-  for (let i = layers.length - 1; i >= 0; i -= 1) {
-    const layer = layers[i];
-    if (layer) {
-      result = layer.wrap(trail, result);
+  for (let i = gates.length - 1; i >= 0; i -= 1) {
+    const gate = gates[i];
+    if (gate) {
+      result = gate.wrap(trail, result);
     }
   }
   return result;