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

package/src/__tests__/{event.test.ts → signal.test.ts}

@@ -1,24 +1,24 @@
-import { describe, test, expect } from 'bun:test';
+import { describe, expect, test } from 'bun:test';
 
 import { z } from 'zod';
 
-import { event } from '../event';
+import { signal } from '../signal.js';
 
 const payloadSchema = z.object({
   action: z.string(),
   userId: z.string(),
 });
 
-const userAction = event('user.action', {
+const userAction = signal('user.action', {
   description: 'A user performed an action',
   from: ['auth.login', 'auth.signup'],
-  metadata: { domain: 'auth', priority: 1 },
+  meta: { domain: 'auth', priority: 1 },
   payload: payloadSchema,
 });
 
-describe('event() basics', () => {
-  test("returns kind 'event'", () => {
-    expect(userAction.kind).toBe('event');
+describe('signal() basics', () => {
+  test("returns kind 'signal'", () => {
+    expect(userAction.kind).toBe('signal');
   });
 
   test('returns correct id', () => {
@@ -45,7 +45,7 @@ describe('event() basics', () => {
   });
 });
 
-describe('event() from and metadata', () => {
+describe('signal() from and meta', () => {
   test('preserves from', () => {
     expect(userAction.from).toEqual(['auth.login', 'auth.signup']);
   });
@@ -54,29 +54,29 @@ describe('event() from and metadata', () => {
     expect(Object.isFrozen(userAction.from)).toBe(true);
   });
 
-  test('preserves metadata', () => {
-    expect(userAction.metadata).toEqual({ domain: 'auth', priority: 1 });
+  test('preserves meta', () => {
+    expect(userAction.meta).toEqual({ domain: 'auth', priority: 1 });
   });
 
   test('optional fields default to undefined', () => {
-    const minimal = event('minimal', {
+    const minimal = signal('minimal', {
       payload: z.string(),
     });
     expect(minimal.description).toBeUndefined();
     expect(minimal.from).toBeUndefined();
-    expect(minimal.metadata).toBeUndefined();
+    expect(minimal.meta).toBeUndefined();
   });
 });
 
-describe('event() single-object overload', () => {
+describe('signal() single-object overload', () => {
   test('accepts spec with id property', () => {
-    const e = event({
+    const e = signal({
       from: ['entity.add', 'entity.delete'],
       id: 'entity.updated',
       payload: z.object({ entityId: z.string() }),
     });
     expect(e.id).toBe('entity.updated');
-    expect(e.kind).toBe('event');
+    expect(e.kind).toBe('signal');
     expect(e.from).toEqual(['entity.add', 'entity.delete']);
   });
 });

package/src/__tests__/topo.test.ts

@@ -3,8 +3,8 @@ import { describe, test, expect } from 'bun:test';
 import { z } from 'zod';
 
 import { ValidationError } from '../errors.js';
+import { provision } from '../provision.js';
 import { Result } from '../result.js';
-import { service } from '../service.js';
 import { topo } from '../topo.js';
 
 // ---------------------------------------------------------------------------
@@ -14,25 +14,25 @@ import { topo } from '../topo.js';
 // oxlint-disable-next-line require-await -- satisfies async interface without needing await
 const noop = async () => Result.ok();
 
-const mockTrail = (id: string, follow?: readonly string[]) => ({
-  follow: Object.freeze([...(follow ?? [])]),
+const mockTrail = (id: string, crosses?: readonly string[]) => ({
+  blaze: noop,
+  crosses: Object.freeze([...(crosses ?? [])]),
   id,
   input: z.object({ x: z.number() }),
   kind: 'trail' as const,
   output: z.object({ y: z.number() }),
-  run: noop,
 });
 
 const mockEvent = (id: string) => ({
   id,
-  kind: 'event' as const,
+  kind: 'signal' as const,
   payload: z.object({ payload: z.string() }),
 });
 
-const mockService = (id: string) =>
-  service(id, {
+const mockProvision = (id: string) =>
+  provision(id, {
     create: () => Result.ok({ id }),
-    description: `${id} service`,
+    description: `${id} provision`,
   });
 
 // ---------------------------------------------------------------------------
@@ -57,15 +57,15 @@ describe('topo', () => {
     test('auto-scans exports by kind discriminant', () => {
       const mod = {
         event1: mockEvent('e1'),
-        service1: mockService('s1'),
+        provision1: mockProvision('s1'),
         trail1: mockTrail('t1'),
         trail2: mockTrail('t2', ['t1']),
       };
       const t = topo('app', mod);
 
       expect(t.trails.size).toBe(2);
-      expect(t.events.size).toBe(1);
-      expect(t.services.size).toBe(1);
+      expect(t.signals.size).toBe(1);
+      expect(t.provisions.size).toBe(1);
     });
 
     test('collects from multiple modules', () => {
@@ -89,25 +89,25 @@ describe('topo', () => {
       const t = topo('app', mod);
 
       expect(t.trails.size).toBe(1);
-      expect(t.events.size).toBe(0);
-      expect(t.services.size).toBe(0);
+      expect(t.signals.size).toBe(0);
+      expect(t.provisions.size).toBe(0);
     });
 
-    test('trail with follow registers correctly', () => {
+    test('trail with crossings registers correctly', () => {
       const mod = { t: mockTrail('trail-1', ['trail-2']) };
       const t = topo('app', mod);
 
       expect(t.trails.size).toBe(1);
       const registered = t.trails.get('trail-1');
-      expect(registered?.follow).toEqual(['trail-2']);
+      expect(registered?.crosses).toEqual(['trail-2']);
     });
 
-    test('collects services from modules', () => {
-      const mod = { db: mockService('db.main') };
+    test('collects provisions from modules', () => {
+      const mod = { db: mockProvision('db.main') };
       const t = topo('app', mod);
 
-      expect(t.services.size).toBe(1);
-      expect(t.services.get('db.main')).toBe(mod.db);
+      expect(t.provisions.size).toBe(1);
+      expect(t.provisions.get('db.main')).toBe(mod.db);
     });
   });
 
@@ -128,17 +128,17 @@ describe('topo', () => {
 
       expect(() => topo('app', mod1, mod2)).toThrow(ValidationError);
       expect(() => topo('app', mod1, mod2)).toThrow(
-        'Duplicate event ID: "dup"'
+        'Duplicate signal ID: "dup"'
       );
     });
 
-    test('rejects duplicate service IDs', () => {
-      const mod1 = { a: mockService('dup') };
-      const mod2 = { b: mockService('dup') };
+    test('rejects duplicate provision IDs', () => {
+      const mod1 = { a: mockProvision('dup') };
+      const mod2 = { b: mockProvision('dup') };
 
       expect(() => topo('app', mod1, mod2)).toThrow(ValidationError);
       expect(() => topo('app', mod1, mod2)).toThrow(
-        'Duplicate service ID: "dup"'
+        'Duplicate provision ID: "dup"'
       );
     });
   });
@@ -162,26 +162,26 @@ describe('topo accessors', () => {
     expect(app.count).toBe(1);
   });
 
-  test('serviceCount returns number of services', () => {
-    const db = mockService('db.main');
-    const cache = mockService('cache.main');
+  test('provisionCount returns number of provisions', () => {
+    const db = mockProvision('db.main');
+    const cache = mockProvision('cache.main');
     const app = topo('test', { cache, db });
-    expect(app.serviceCount).toBe(2);
+    expect(app.provisionCount).toBe(2);
   });
 
   test('empty topo has zero count and empty ids', () => {
     const app = topo('empty');
     expect(app.count).toBe(0);
     expect(app.ids()).toEqual([]);
-    expect(app.serviceCount).toBe(0);
-    expect(app.serviceIds()).toEqual([]);
+    expect(app.provisionCount).toBe(0);
+    expect(app.provisionIds()).toEqual([]);
   });
 
-  test('serviceIds() returns all service IDs', () => {
-    const db = mockService('db.main');
-    const cache = mockService('cache.main');
+  test('provisionIds() returns all provision IDs', () => {
+    const db = mockProvision('db.main');
+    const cache = mockProvision('cache.main');
     const app = topo('test', { cache, db });
-    expect(app.serviceIds().toSorted()).toEqual(['cache.main', 'db.main']);
+    expect(app.provisionIds().toSorted()).toEqual(['cache.main', 'db.main']);
   });
 });
 
@@ -192,7 +192,7 @@ describe('topo accessors', () => {
 describe('Topo', () => {
   const mod = {
     e1: mockEvent('event-1'),
-    s1: mockService('service-1'),
+    p1: mockProvision('provision-1'),
     t1: mockTrail('trail-1'),
     t2: mockTrail('trail-2'),
     t3: mockTrail('trail-3', ['trail-1']),
@@ -206,7 +206,7 @@ describe('Topo', () => {
       expect(app.get('trail-1')).toBe(mod.t1);
     });
 
-    test('retrieves trail with follow by ID', () => {
+    test('retrieves trail with crossings by ID', () => {
       expect(app.get('trail-3')).toBe(mod.t3);
     });
 
@@ -220,7 +220,7 @@ describe('Topo', () => {
       expect(app.has('trail-1')).toBe(true);
     });
 
-    test('returns true for trail with follow', () => {
+    test('returns true for trail with crossings', () => {
       expect(app.has('trail-3')).toBe(true);
     });
 
@@ -228,33 +228,33 @@ describe('Topo', () => {
       expect(app.has('nope')).toBe(false);
     });
 
-    test('returns false for event ID (events are not trails)', () => {
+    test('returns false for event ID (signals are not trails)', () => {
       expect(app.has('event-1')).toBe(false);
     });
   });
 
-  describe('getService()', () => {
-    test('retrieves service by ID', () => {
-      expect(app.getService('service-1')).toBe(mod.s1);
+  describe('getProvision()', () => {
+    test('retrieves provision by ID', () => {
+      expect(app.getProvision('provision-1')).toBe(mod.p1);
     });
 
-    test('returns undefined for unknown service ID', () => {
-      expect(app.getService('missing-service')).toBeUndefined();
+    test('returns undefined for unknown provision ID', () => {
+      expect(app.getProvision('missing-provision')).toBeUndefined();
     });
   });
 
-  describe('hasService()', () => {
-    test('returns true for known service', () => {
-      expect(app.hasService('service-1')).toBe(true);
+  describe('hasProvision()', () => {
+    test('returns true for known provision', () => {
+      expect(app.hasProvision('provision-1')).toBe(true);
     });
 
-    test('returns false for unknown service', () => {
-      expect(app.hasService('missing-service')).toBe(false);
+    test('returns false for unknown provision', () => {
+      expect(app.hasProvision('missing-provision')).toBe(false);
     });
   });
 
   describe('listing', () => {
-    test('list() returns all trails (with and without follow)', () => {
+    test('list() returns all trails (with and without crossings)', () => {
       const items = app.list();
       expect(items).toHaveLength(3);
       expect(items).toContain(mod.t1);
@@ -262,16 +262,16 @@ describe('Topo', () => {
       expect(items).toContain(mod.t3);
     });
 
-    test('listEvents() returns all events', () => {
-      const items = app.listEvents();
+    test('listEvents() returns all signals', () => {
+      const items = app.listSignals();
       expect(items).toHaveLength(1);
       expect(items).toContain(mod.e1);
     });
 
-    test('listServices() returns all services', () => {
-      const items = app.listServices();
+    test('listProvisions() returns all provisions', () => {
+      const items = app.listProvisions();
       expect(items).toHaveLength(1);
-      expect(items).toContain(mod.s1);
+      expect(items).toContain(mod.p1);
     });
   });
 });

package/src/__tests__/trail-permit.test.ts

@@ -21,38 +21,38 @@ describe('PermitRequirement type', () => {
 describe('trail() with permit field', () => {
   test('accepts permit with scopes', () => {
     const t = trail('user.delete', {
+      blaze: (input) => Result.ok({ deleted: input.id }),
       input: z.object({ id: z.string() }),
       intent: 'destroy',
       permit: { scopes: ['user:write'] },
-      run: (input) => Result.ok({ deleted: input.id }),
     });
     expect(t.permit).toEqual({ scopes: ['user:write'] });
   });
 
   test('accepts permit: public', () => {
     const t = trail('health.check', {
+      blaze: () => Result.ok({ status: 'ok' }),
       input: z.object({}),
       intent: 'read',
       permit: 'public',
-      run: () => Result.ok({ status: 'ok' }),
     });
     expect(t.permit).toBe('public');
   });
 
   test('permit is undefined when omitted (backward compatible)', () => {
     const t = trail('legacy.trail', {
+      blaze: () => Result.ok(),
       input: z.object({}),
-      run: () => Result.ok(),
     });
     expect(t.permit).toBeUndefined();
   });
 
   test('preserves permit on the frozen Trail object', () => {
     const t = trail('user.list', {
+      blaze: () => Result.ok([]),
       input: z.object({}),
       intent: 'read',
       permit: { scopes: ['user:read'] },
-      run: () => Result.ok([]),
     });
     expect(Object.isFrozen(t)).toBe(true);
     expect(t.permit).toEqual({ scopes: ['user:read'] });

package/src/__tests__/trail.test.ts

@@ -4,23 +4,23 @@ import { z } from 'zod';
 
 import { createTrailContext } from '../context';
 import { Result } from '../result';
-import { service } from '../service';
+import { provision } from '../provision';
 import { trail } from '../trail';
 import type { TrailContext } from '../types';
 
 const stubCtx: TrailContext = createTrailContext({
+  abortSignal: AbortSignal.timeout(5000),
   requestId: 'test-123',
-  signal: AbortSignal.timeout(5000),
 });
 
-const dbService = service('db.main', {
+const dbProvision = provision('db.main', {
   create: () =>
     Result.ok({
       query(sql: string) {
         return sql.length;
       },
     }),
-  description: 'Primary database service',
+  description: 'Primary database provision',
 });
 
 describe('trail()', () => {
@@ -28,10 +28,10 @@ describe('trail()', () => {
   const outputSchema = z.object({ greeting: z.string() });
 
   const greet = trail('greet', {
+    blaze: (input) => Result.ok({ greeting: `Hello, ${input.name}!` }),
     description: 'Greet someone',
     input: inputSchema,
     output: outputSchema,
-    run: (input) => Result.ok({ greeting: `Hello, ${input.name}!` }),
   });
 
   describe('basics', () => {
@@ -53,28 +53,28 @@ describe('trail()', () => {
 
     test('output schema is optional', () => {
       const minimal = trail('noop', {
+        blaze: () => Result.ok(),
         input: z.object({}),
-        run: () => Result.ok(),
       });
       expect(minimal.output).toBeUndefined();
     });
 
     test('implementation is callable', async () => {
-      const result = await greet.run({ name: 'World' }, stubCtx);
+      const result = await greet.blaze({ name: 'World' }, stubCtx);
       expect(result.isOk()).toBe(true);
       expect(result.unwrap()).toEqual({ greeting: 'Hello, World!' });
     });
   });
 
-  describe('metadata', () => {
+  describe('meta', () => {
     test('examples are stored', () => {
       const withExamples = trail('echo', {
+        blaze: (input) => Result.ok({ text: input.text }),
         examples: [
           { error: 'ValidationError', input: { text: '' }, name: 'error-case' },
           { expected: { text: 'hi' }, input: { text: 'hi' }, name: 'basic' },
         ],
         input: z.object({ text: z.string() }),
-        run: (input) => Result.ok({ text: input.text }),
       });
       expect(withExamples.examples).toHaveLength(2);
       const first = withExamples.examples?.[0];
@@ -83,23 +83,23 @@ describe('trail()', () => {
       expect(second?.name).toBe('basic');
     });
 
-    test('metadata is stored', () => {
-      const withMetadata = trail('tagged', {
+    test('meta is stored', () => {
+      const withMeta = trail('tagged', {
+        blaze: () => Result.ok(),
         input: z.object({}),
-        metadata: { domain: 'billing', tier: 1 },
-        run: () => Result.ok(),
+        meta: { domain: 'billing', tier: 1 },
       });
-      expect(withMetadata.metadata).toEqual({ domain: 'billing', tier: 1 });
+      expect(withMeta.meta).toEqual({ domain: 'billing', tier: 1 });
     });
 
     test('detours are stored', () => {
       const withDetours = trail('orchestrator', {
+        blaze: () => Result.ok(),
         detours: {
           onFailure: ['alert'],
           onSuccess: ['notify', 'audit'],
         },
         input: z.object({}),
-        run: () => Result.ok(),
       });
       expect(withDetours.detours).toEqual({
         onFailure: ['alert'],
@@ -108,70 +108,70 @@ describe('trail()', () => {
     });
   });
 
-  describe('follow', () => {
+  describe('crosses', () => {
     test('defaults to empty frozen array when omitted', () => {
       const minimal = trail('bare', {
+        blaze: () => Result.ok(),
         input: z.object({}),
-        run: () => Result.ok(),
       });
-      expect(minimal.follow).toEqual([]);
-      expect(Object.isFrozen(minimal.follow)).toBe(true);
+      expect(minimal.crosses).toEqual([]);
+      expect(Object.isFrozen(minimal.crosses)).toBe(true);
     });
 
-    test('preserves follow array', () => {
-      const withFollow = trail('composed', {
-        follow: ['authenticate', 'validate-session'],
+    test('preserves crosses array', () => {
+      const withCrosses = trail('composed', {
+        blaze: () => Result.ok(),
+        crosses: ['authenticate', 'validate-session'],
         input: z.object({}),
-        run: () => Result.ok(),
       });
-      expect(withFollow.follow).toEqual(['authenticate', 'validate-session']);
+      expect(withCrosses.crosses).toEqual(['authenticate', 'validate-session']);
     });
 
-    test('follow array is frozen', () => {
-      const withFollow = trail('composed', {
-        follow: ['authenticate'],
+    test('crosses array is frozen', () => {
+      const withCrosses = trail('composed', {
+        blaze: () => Result.ok(),
+        crosses: ['authenticate'],
         input: z.object({}),
-        run: () => Result.ok(),
       });
-      expect(Object.isFrozen(withFollow.follow)).toBe(true);
+      expect(Object.isFrozen(withCrosses.crosses)).toBe(true);
     });
   });
 
-  describe('services', () => {
+  describe('provisions', () => {
     test('defaults to empty frozen array when omitted', () => {
       const minimal = trail('bare', {
+        blaze: () => Result.ok(),
         input: z.object({}),
-        run: () => Result.ok(),
       });
-      expect(minimal.services).toEqual([]);
-      expect(Object.isFrozen(minimal.services)).toBe(true);
+      expect(minimal.provisions).toEqual([]);
+      expect(Object.isFrozen(minimal.provisions)).toBe(true);
     });
 
-    test('preserves declared service objects', () => {
-      const withServices = trail('search', {
+    test('preserves declared provision objects', () => {
+      const withProvisions = trail('search', {
+        blaze: () => Result.ok(),
         input: z.object({}),
-        run: () => Result.ok(),
-        services: [dbService],
+        provisions: [dbProvision],
       });
-      expect(withServices.services).toEqual([dbService]);
-      expect(withServices.services[0]).toBe(dbService);
+      expect(withProvisions.provisions).toEqual([dbProvision]);
+      expect(withProvisions.provisions[0]).toBe(dbProvision);
     });
 
-    test('services array is frozen', () => {
-      const withServices = trail('search', {
+    test('provisions array is frozen', () => {
+      const withProvisions = trail('search', {
+        blaze: () => Result.ok(),
         input: z.object({}),
-        run: () => Result.ok(),
-        services: [dbService],
+        provisions: [dbProvision],
       });
-      expect(Object.isFrozen(withServices.services)).toBe(true);
+      expect(Object.isFrozen(withProvisions.provisions)).toBe(true);
     });
   });
 
   describe('intent and idempotent', () => {
     test('intent defaults to write', () => {
       const minimal = trail('bare', {
+        blaze: () => Result.ok(),
         input: z.object({}),
-        run: () => Result.ok(),
       });
       expect(minimal.intent).toBe('write');
       expect(minimal.idempotent).toBeUndefined();
@@ -179,25 +179,25 @@ describe('trail()', () => {
 
     test('intent is preserved when set', () => {
       const readTrail = trail('reader', {
+        blaze: () => Result.ok(),
         input: z.object({}),
         intent: 'read',
-        run: () => Result.ok(),
       });
       expect(readTrail.intent).toBe('read');
 
       const destroyTrail = trail('destroyer', {
+        blaze: () => Result.ok(),
         input: z.object({}),
         intent: 'destroy',
-        run: () => Result.ok(),
       });
       expect(destroyTrail.intent).toBe('destroy');
     });
 
     test('idempotent is preserved when set', () => {
       const t = trail('idempotent', {
+        blaze: () => Result.ok(),
         idempotent: true,
         input: z.object({}),
-        run: () => Result.ok(),
       });
       expect(t.idempotent).toBe(true);
     });
@@ -206,10 +206,10 @@ describe('trail()', () => {
   describe('single-object overload', () => {
     test('accepts spec with id property', () => {
       const t = trail({
+        blaze: (input: { name: string }, _ctx: TrailContext) =>
+          Result.ok({ greeting: `Hi, ${input.name}` }),
         id: 'entity.show',
         input: inputSchema,
-        run: (input: { name: string }, _ctx: TrailContext) =>
-          Result.ok({ greeting: `Hi, ${input.name}` }),
       });
       expect(t.id).toBe('entity.show');
       expect(t.kind).toBe('trail');
@@ -217,40 +217,40 @@ describe('trail()', () => {
 
     test('preserves all spec fields', () => {
       const t = trail({
+        blaze: (input: { name: string }, _ctx: TrailContext) =>
+          Result.ok({ greeting: `Hi, ${input.name}` }),
         description: 'A full trail',
         examples: [{ input: { name: 'World' }, name: 'test' }],
         id: 'full',
         input: inputSchema,
         intent: 'read',
         output: outputSchema,
-        run: (input: { name: string }, _ctx: TrailContext) =>
-          Result.ok({ greeting: `Hi, ${input.name}` }),
-        services: [dbService],
+        provisions: [dbProvision],
       });
       expect(t.description).toBe('A full trail');
       expect(t.intent).toBe('read');
       expect(t.examples).toHaveLength(1);
-      expect(t.services).toEqual([dbService]);
+      expect(t.provisions).toEqual([dbProvision]);
     });
 
     test('implementation is callable', async () => {
       const t = trail({
+        blaze: (input: { x: number }) => Result.ok(input.x * 2),
         id: 'callable',
         input: z.object({ x: z.number() }),
-        run: (input: { x: number }) => Result.ok(input.x * 2),
       });
-      const result = await t.run({ x: 5 }, stubCtx);
+      const result = await t.blaze({ x: 5 }, stubCtx);
       expect(result.isOk()).toBe(true);
       expect(result.unwrap()).toBe(10);
     });
 
     test('sync implementations are normalized to an awaitable runtime function', async () => {
       const t = trail('normalized', {
+        blaze: (input: { value: number }) => Result.ok(input.value + 1),
         input: z.object({ value: z.number() }),
-        run: (input: { value: number }) => Result.ok(input.value + 1),
       });
 
-      const promise = t.run({ value: 2 }, stubCtx);
+      const promise = t.blaze({ value: 2 }, stubCtx);
       expect(promise).toBeInstanceOf(Promise);
 
       const result = await promise;