@ontrails/core 1.0.0-beta.11 → 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';