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

package/src/__tests__/execute.test.ts

@@ -6,9 +6,9 @@ import { z } from 'zod';
 import { InternalError, ValidationError } from '../errors';
 import { executeTrail } from '../execute';
 import { createTrailContext } from '../context';
-import type { Layer } from '../layer';
+import type { Gate } from '../gate';
 import { Result } from '../result';
-import { service } from '../service';
+import { provision } from '../provision';
 import { trail } from '../trail';
 import type { TrailContext, TrailContextInit } from '../types';
 
@@ -17,84 +17,84 @@ import type { TrailContext, TrailContextInit } from '../types';
 // ---------------------------------------------------------------------------
 
 const echoTrail = trail('echo', {
+  blaze: (input) => Result.ok({ value: input.value }),
   input: z.object({ value: z.string() }),
   output: z.object({ value: z.string() }),
-  run: (input) => Result.ok({ value: input.value }),
 });
 
 const failingTrail = trail('fails', {
+  blaze: () => Result.err(new ValidationError('bad input')),
   input: z.object({}),
-  run: () => Result.err(new ValidationError('bad input')),
 });
 
 const throwingTrail = trail('throws', {
-  input: z.object({}),
-  run: () => {
+  blaze: () => {
     throw new Error('kaboom');
   },
+  input: z.object({}),
 });
 
-const nextServiceId = (name: string): string =>
-  `test.service.${name}.${Bun.randomUUIDv7()}`;
+const nextProvisionId = (name: string): string =>
+  `test.provision.${name}.${Bun.randomUUIDv7()}`;
 
-const createResolvedValueService = (
+const createResolvedValueProvision = (
   id: string,
   onCreate: () => void,
   value: number
 ) =>
-  service(id, {
+  provision(id, {
     create: () => {
       onCreate();
       return Result.ok({ value });
     },
   });
 
-const createEagerServiceTrail = (
+const createEagerProvisionTrail = (
   id: string,
-  counter: ReturnType<typeof createResolvedValueService>,
+  counter: ReturnType<typeof createResolvedValueProvision>,
   onRun: (value: number) => void
 ) =>
-  trail('service.eager', {
-    input: z.object({}),
-    output: z.object({ total: z.number() }),
-    run: (_input, ctx) => {
-      const fromAccessor = ctx.service<{ value: number }>(id);
+  trail('provision.eager', {
+    blaze: (_input, ctx) => {
+      const fromAccessor = ctx.provision<{ value: number }>(id);
       const fromDefinition = counter.from(ctx);
       onRun(fromDefinition.value);
       return Result.ok({ total: fromAccessor.value + 1 });
     },
-    services: [counter],
+    input: z.object({}),
+    output: z.object({ total: z.number() }),
+    provisions: [counter],
   });
 
-const createServiceProbeLayer = (
-  counter: ReturnType<typeof createResolvedValueService>,
+const createProvisionProbeGate = (
+  counter: ReturnType<typeof createResolvedValueProvision>,
   onResolve: (value: number) => void
-): Layer => ({
-  name: 'uses-service',
+): Gate => ({
+  name: 'uses-provision',
   wrap(_trail, impl) {
     return async (input, ctx) => {
-      onResolve(ctx.service<{ value: number }>(counter).value);
+      onResolve(ctx.provision<{ value: number }>(counter).value);
       return await impl(input, ctx);
     };
   },
 });
 
-const createSingletonService = (id: string, onCreate: () => number) =>
-  service(id, {
+const createSingletonProvision = (id: string, onCreate: () => number) =>
+  provision(id, {
     create: () => Result.ok({ createdAtCall: onCreate() }),
   });
 
 const createSingletonTrail = (
-  singleton: ReturnType<typeof createSingletonService>
+  singleton: ReturnType<typeof createSingletonProvision>
 ) =>
-  trail('service.singleton', {
-    input: z.object({}),
-    output: z.object({ createdAtCall: z.number() }),
-    run: (_input, ctx) =>
+  trail('provision.singleton', {
+    blaze: (_input, ctx) =>
       Result.ok({
         createdAtCall: singleton.from(ctx).createdAtCall,
       }),
-    services: [singleton],
+    input: z.object({}),
+    output: z.object({ createdAtCall: z.number() }),
+    provisions: [singleton],
   });
 
 const unwrapExecution = async (
@@ -117,60 +117,60 @@ describe('executeTrail', () => {
       expect(result.unwrap()).toEqual({ value: 'hello' });
     });
 
-    test('eagerly resolves declared services before layers and implementation run', async () => {
-      const id = nextServiceId('eager');
+    test('eagerly resolves declared provisions before gates and implementation run', async () => {
+      const id = nextProvisionId('eager');
       const captures = {
         createCalls: 0,
-        layerResolved: undefined as number | undefined,
+        gateResolved: undefined as number | undefined,
         runResolved: undefined as number | undefined,
       };
-      const counter = createResolvedValueService(
+      const counter = createResolvedValueProvision(
         id,
         () => {
           captures.createCalls += 1;
         },
         41
       );
-      const layeredTrail = createEagerServiceTrail(id, counter, (value) => {
+      const layeredTrail = createEagerProvisionTrail(id, counter, (value) => {
         captures.runResolved = value;
       });
-      const layer = createServiceProbeLayer(counter, (value) => {
-        captures.layerResolved = value;
+      const gate = createProvisionProbeGate(counter, (value) => {
+        captures.gateResolved = value;
       });
 
-      const result = await executeTrail(layeredTrail, {}, { layers: [layer] });
+      const result = await executeTrail(layeredTrail, {}, { gates: [gate] });
 
       expect(result.unwrap()).toEqual({ total: 42 });
       expect(captures.createCalls).toBe(1);
-      expect(captures.layerResolved).toBe(41);
+      expect(captures.gateResolved).toBe(41);
       expect(captures.runResolved).toBe(41);
     });
 
-    test('awaits async service factories before running the trail', async () => {
-      const db = service(nextServiceId('async-factory'), {
+    test('awaits async provision factories before running the trail', async () => {
+      const db = provision(nextProvisionId('async-factory'), {
         create: async () => {
           await Bun.sleep(0);
           return Result.ok({ source: 'async-factory' });
         },
       });
-      const serviceTrail = trail('service.async-factory', {
+      const provisionTrail = trail('provision.async-factory', {
+        blaze: (_input, ctx) =>
+          Result.ok({ source: db.from(ctx).source as string }),
         input: z.object({}),
         output: z.object({ source: z.string() }),
-        run: (_input, ctx) =>
-          Result.ok({ source: db.from(ctx).source as string }),
-        services: [db],
+        provisions: [db],
       });
 
-      const result = await executeTrail(serviceTrail, {});
+      const result = await executeTrail(provisionTrail, {});
 
       expect(result.isOk()).toBe(true);
       expect(result.unwrap()).toEqual({ source: 'async-factory' });
     });
 
-    test('reuses cached singleton services across executions', async () => {
-      const id = nextServiceId('singleton');
+    test('reuses cached singleton provisions across executions', async () => {
+      const id = nextProvisionId('singleton');
       const captures = { createCalls: 0 };
-      const singleton = createSingletonService(id, () => {
+      const singleton = createSingletonProvision(id, () => {
         captures.createCalls += 1;
         return captures.createCalls;
       });
@@ -185,17 +185,17 @@ describe('executeTrail', () => {
       expect(captures.createCalls).toBe(1);
     });
 
-    test('scopes cached singleton services to compatible service contexts', async () => {
-      const id = nextServiceId('singleton-context');
-      const envAwareService = service(id, {
+    test('scopes cached singleton provisions to compatible provision contexts', async () => {
+      const id = nextProvisionId('singleton-context');
+      const envAwareProvision = provision(id, {
         create: (ctx) => Result.ok({ value: String(ctx.env?.VAL) }),
       });
-      const envAwareTrail = trail('service.singleton-context', {
+      const envAwareTrail = trail('provision.singleton-context', {
+        blaze: (_input, ctx) =>
+          Result.ok({ value: envAwareProvision.from(ctx).value }),
         input: z.object({}),
         output: z.object({ value: z.string() }),
-        run: (_input, ctx) =>
-          Result.ok({ value: envAwareService.from(ctx).value }),
-        services: [envAwareService],
+        provisions: [envAwareProvision],
       });
 
       const first = await executeTrail(
@@ -233,11 +233,11 @@ describe('executeTrail', () => {
     });
   });
 
-  describe('layers', () => {
-    test('composes layers around execution', async () => {
+  describe('gates', () => {
+    test('composes gates around execution', async () => {
       const log: string[] = [];
-      const layer: Layer = {
-        name: 'test-layer',
+      const gate: Gate = {
+        name: 'test-gate',
         wrap(_trail, impl) {
           return async (input, ctx) => {
             log.push('before');
@@ -251,7 +251,7 @@ describe('executeTrail', () => {
       const result = await executeTrail(
         echoTrail,
         { value: 'x' },
-        { layers: [layer] }
+        { gates: [gate] }
       );
 
       expect(result.isOk()).toBe(true);
@@ -263,11 +263,11 @@ describe('executeTrail', () => {
     test('accepts context overrides', async () => {
       let capturedCtx: TrailContext | undefined;
       const ctxTrail = trail('ctx-test', {
-        input: z.object({}),
-        run: (_input, ctx) => {
+        blaze: (_input, ctx) => {
           capturedCtx = ctx;
           return Result.ok(null);
         },
+        input: z.object({}),
       });
 
       await executeTrail(ctxTrail, {}, { ctx: { requestId: 'override-id' } });
@@ -275,36 +275,36 @@ describe('executeTrail', () => {
       expect(capturedCtx?.requestId).toBe('override-id');
     });
 
-    test('accepts signal override', async () => {
+    test('accepts abortSignal override', async () => {
       let capturedSignal: AbortSignal | undefined;
       const sigTrail = trail('sig-test', {
-        input: z.object({}),
-        run: (_input, ctx) => {
-          capturedSignal = ctx.signal;
+        blaze: (_input, ctx) => {
+          capturedSignal = ctx.abortSignal;
           return Result.ok(null);
         },
+        input: z.object({}),
       });
 
-      const signal = AbortSignal.timeout(9999);
-      await executeTrail(sigTrail, {}, { signal });
+      const abortSignal = AbortSignal.timeout(9999);
+      await executeTrail(sigTrail, {}, { abortSignal });
 
-      expect(capturedSignal).toBe(signal);
+      expect(capturedSignal).toBe(abortSignal);
     });
 
     test('accepts context factory', async () => {
       let capturedCtx: TrailContext | undefined;
       const ctxTrail = trail('factory-test', {
-        input: z.object({}),
-        run: (_input, ctx) => {
+        blaze: (_input, ctx) => {
           capturedCtx = ctx;
           return Result.ok(null);
         },
+        input: z.object({}),
       });
 
       const customCtx: TrailContextInit = {
+        abortSignal: new AbortController().signal,
         cwd: '/custom',
         requestId: 'factory-id',
-        signal: new AbortController().signal,
       };
 
       await executeTrail(ctxTrail, {}, { createContext: () => customCtx });
@@ -316,17 +316,17 @@ describe('executeTrail', () => {
     test('context factory + ctx overrides merge correctly', async () => {
       let capturedCtx: TrailContext | undefined;
       const ctxTrail = trail('merge-test', {
-        input: z.object({}),
-        run: (_input, ctx) => {
+        blaze: (_input, ctx) => {
           capturedCtx = ctx;
           return Result.ok(null);
         },
+        input: z.object({}),
       });
 
       const baseCtx: TrailContextInit = {
+        abortSignal: new AbortController().signal,
         cwd: '/factory',
         requestId: 'factory-id',
-        signal: new AbortController().signal,
       };
 
       await executeTrail(
@@ -345,12 +345,12 @@ describe('executeTrail', () => {
     test('deep-merges extensions from factory and overrides', async () => {
       let captured: TrailContext | undefined;
       const t = trail('ext.test', {
-        input: z.object({}),
-        output: z.object({}),
-        run: (_input, ctx) => {
+        blaze: (_input, ctx) => {
           captured = ctx;
           return Result.ok({});
         },
+        input: z.object({}),
+        output: z.object({}),
       });
       await executeTrail(
         t,
@@ -364,23 +364,23 @@ describe('executeTrail', () => {
       expect(captured?.extensions).toEqual({ store: 'db', userId: '123' });
     });
 
-    test('rebinds ctx.service after merging extension overrides from createContext', async () => {
+    test('rebinds ctx.provision after merging extension overrides from createContext', async () => {
       let resolvedSource: string | undefined;
-      const db = service(nextServiceId('context-override'), {
+      const db = provision(nextProvisionId('context-override'), {
         create: () => Result.ok({ source: 'factory' }),
       });
-      const serviceTrail = trail('ctx.service.override', {
-        input: z.object({}),
-        output: z.object({ source: z.string() }),
-        run: (_input, ctx) => {
-          resolvedSource = ctx.service<{ source: string }>(db).source;
+      const provisionTrail = trail('ctx.provision.override', {
+        blaze: (_input, ctx) => {
+          resolvedSource = ctx.provision<{ source: string }>(db).source;
           return Result.ok({ source: resolvedSource });
         },
-        services: [db],
+        input: z.object({}),
+        output: z.object({ source: z.string() }),
+        provisions: [db],
       });
 
       const result = await executeTrail(
-        serviceTrail,
+        provisionTrail,
         {},
         {
           createContext: () =>
@@ -401,17 +401,17 @@ describe('executeTrail', () => {
       expect(resolvedSource).toBe('override-context');
     });
 
-    test('context factory seeds the service accessor when omitted', async () => {
+    test('context factory seeds the provision accessor when omitted', async () => {
       let capturedCtx: TrailContext | undefined;
-      const id = nextServiceId('factory-seed');
+      const id = nextProvisionId('factory-seed');
       const widget = { id: 'widget-1' };
-      const widgetTrail = trail('service.factory-seed', {
-        input: z.object({}),
-        run: (_input, ctx) => {
+      const widgetTrail = trail('provision.factory-seed', {
+        blaze: (_input, ctx) => {
           capturedCtx = ctx;
           return Result.ok(null);
         },
-        services: [],
+        input: z.object({}),
+        provisions: [],
       });
 
       await executeTrail(
@@ -419,14 +419,14 @@ describe('executeTrail', () => {
         {},
         {
           createContext: () => ({
+            abortSignal: new AbortController().signal,
             extensions: { [id]: widget },
-            requestId: 'seeded-service',
-            signal: new AbortController().signal,
+            requestId: 'seeded-provision',
           }),
         }
       );
 
-      expect(capturedCtx?.service(id)).toBe(widget);
+      expect(capturedCtx?.provision(id)).toBe(widget);
     });
   });
 
@@ -447,22 +447,22 @@ describe('executeTrail', () => {
       expect(result.error.message).toBe('kaboom');
     });
 
-    test('short-circuits when a service factory returns Result.err', async () => {
-      const failingService = service(nextServiceId('factory-error'), {
+    test('short-circuits when a provision factory returns Result.err', async () => {
+      const failingProvision = provision(nextProvisionId('factory-error'), {
         create: () =>
           Result.err(new ValidationError('DATABASE_URL is required')),
       });
       let ran = false;
-      const serviceTrail = trail('service.factory-error', {
-        input: z.object({}),
-        run: () => {
+      const provisionTrail = trail('provision.factory-error', {
+        blaze: () => {
           ran = true;
           return Result.ok(null);
         },
-        services: [failingService],
+        input: z.object({}),
+        provisions: [failingProvision],
       });
 
-      const result = await executeTrail(serviceTrail, {});
+      const result = await executeTrail(provisionTrail, {});
 
       expect(result.isErr()).toBe(true);
       expect(result.error).toBeInstanceOf(ValidationError);
@@ -470,48 +470,50 @@ describe('executeTrail', () => {
       expect(ran).toBe(false);
     });
 
-    test('wraps thrown service factory exceptions with the service ID in context', async () => {
-      const explodingService = service(nextServiceId('factory-throw'), {
+    test('wraps thrown provision factory exceptions with the provision ID in context', async () => {
+      const explodingProvision = provision(nextProvisionId('factory-throw'), {
         create: () => {
           throw new Error('boom');
         },
       });
-      const serviceTrail = trail('service.factory-throw', {
+      const provisionTrail = trail('provision.factory-throw', {
+        blaze: () => Result.ok(null),
         input: z.object({}),
-        run: () => Result.ok(null),
-        services: [explodingService],
+        provisions: [explodingProvision],
       });
 
-      const result = await executeTrail(serviceTrail, {});
+      const result = await executeTrail(provisionTrail, {});
 
       expect(result.isErr()).toBe(true);
       expect(result.error).toBeInstanceOf(InternalError);
-      expect(result.error.message).toContain(explodingService.id);
-      expect(result.error.context).toEqual({ serviceId: explodingService.id });
+      expect(result.error.message).toContain(explodingProvision.id);
+      expect(result.error.context).toEqual({
+        provisionId: explodingProvision.id,
+      });
     });
 
-    test('prefers explicit service overrides over cached or created instances', async () => {
-      const id = nextServiceId('override');
+    test('prefers explicit provision overrides over cached or created instances', async () => {
+      const id = nextProvisionId('override');
       let createCalls = 0;
-      const db = service(id, {
+      const db = provision(id, {
         create: () => {
           createCalls += 1;
           return Result.ok({ source: 'factory' });
         },
       });
-      const serviceTrail = trail('service.override', {
+      const provisionTrail = trail('provision.override', {
+        blaze: (_input, ctx) =>
+          Result.ok({ source: db.from(ctx).source as string }),
         input: z.object({}),
         output: z.object({ source: z.string() }),
-        run: (_input, ctx) =>
-          Result.ok({ source: db.from(ctx).source as string }),
-        services: [db],
+        provisions: [db],
       });
 
       const result = await executeTrail(
-        serviceTrail,
+        provisionTrail,
         {},
         {
-          services: { [id]: { source: 'override' } },
+          provisions: { [id]: { source: 'override' } },
         }
       );
 

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

@@ -1,34 +1,34 @@
-/* oxlint-disable require-await -- layer wrappers satisfy async interfaces without awaiting */
+/* oxlint-disable require-await -- gate wrappers satisfy async interfaces without awaiting */
 import { describe, test, expect } from 'bun:test';
 
 import { z } from 'zod';
 
 import { createTrailContext } from '../context';
-import { composeLayers } from '../layer';
-import type { Layer } from '../layer';
+import { composeGates } from '../gate';
+import type { Gate } from '../gate';
 import { Result } from '../result';
 import { trail } from '../trail';
 import type { TrailContext } from '../types';
 
 const stubCtx: TrailContext = createTrailContext({
-  requestId: 'test-layer',
-  signal: AbortSignal.timeout(5000),
+  abortSignal: AbortSignal.timeout(5000),
+  requestId: 'test-gate',
 });
 
 const echoTrail = trail('echo', {
+  blaze: (input) => Result.ok({ value: input.value }),
   input: z.object({ value: z.string() }),
-  metadata: { domain: 'test' },
+  meta: { domain: 'test' },
   output: z.object({ value: z.string() }),
-  run: (input) => Result.ok({ value: input.value }),
 });
 
 // ---------------------------------------------------------------------------
-// Layer tests
+// Gate tests
 // ---------------------------------------------------------------------------
 
-describe('Layer', () => {
-  test('single layer wraps implementation', async () => {
-    const prefixLayer: Layer = {
+describe('Gate', () => {
+  test('single gate wraps implementation', async () => {
+    const prefixGate: Gate = {
       name: 'prefix',
       wrap(_trail, impl) {
         return async (input, ctx) => {
@@ -41,17 +41,17 @@ describe('Layer', () => {
       },
     };
 
-    const wrapped = composeLayers([prefixLayer], echoTrail, echoTrail.run);
+    const wrapped = composeGates([prefixGate], echoTrail, echoTrail.blaze);
     const result = await wrapped({ value: 'hello' }, stubCtx);
 
     expect(result.isOk()).toBe(true);
     expect(result.unwrap()).toEqual({ value: 'prefixed:hello' });
   });
 
-  test('multiple layers compose in outermost-first order', async () => {
+  test('multiple gates compose in outermost-first order', async () => {
     const log: string[] = [];
 
-    const outer: Layer = {
+    const outer: Gate = {
       name: 'outer',
       wrap(_trail, impl) {
         return async (input, ctx) => {
@@ -63,7 +63,7 @@ describe('Layer', () => {
       },
     };
 
-    const inner: Layer = {
+    const inner: Gate = {
       name: 'inner',
       wrap(_trail, impl) {
         return async (input, ctx) => {
@@ -75,7 +75,7 @@ describe('Layer', () => {
       },
     };
 
-    const wrapped = composeLayers([outer, inner], echoTrail, echoTrail.run);
+    const wrapped = composeGates([outer, inner], echoTrail, echoTrail.blaze);
     await wrapped({ value: 'x' }, stubCtx);
 
     expect(log).toEqual([
@@ -86,15 +86,15 @@ describe('Layer', () => {
     ]);
   });
 
-  test('layer can short-circuit without calling inner implementation', async () => {
-    const shortCircuit: Layer = {
+  test('gate can short-circuit without calling inner implementation', async () => {
+    const shortCircuit: Gate = {
       name: 'short-circuit',
       wrap() {
         return async () => Result.err(new Error('blocked'));
       },
     };
 
-    const wrapped = composeLayers([shortCircuit], echoTrail, echoTrail.run);
+    const wrapped = composeGates([shortCircuit], echoTrail, echoTrail.blaze);
     const result = await wrapped({ value: 'hello' }, stubCtx);
 
     expect(result.isErr()).toBe(true);
@@ -102,24 +102,24 @@ describe('Layer', () => {
     expect(err.error.message).toBe('blocked');
   });
 
-  test('layer can inspect trail metadata', () => {
+  test('gate can inspect trail meta', () => {
     let capturedDomain: unknown;
 
-    const inspectLayer: Layer = {
+    const inspectGate: Gate = {
       name: 'inspect',
       wrap(t, impl) {
-        capturedDomain = t.metadata?.['domain'];
+        capturedDomain = t.meta?.['domain'];
         return impl;
       },
     };
 
-    composeLayers([inspectLayer], echoTrail, echoTrail.run);
+    composeGates([inspectGate], echoTrail, echoTrail.blaze);
 
     expect(capturedDomain).toBe('test');
   });
 
-  test('empty layers array returns implementation unchanged', () => {
-    const wrapped = composeLayers([], echoTrail, echoTrail.run);
-    expect(wrapped).toBe(echoTrail.run);
+  test('empty gates array returns implementation unchanged', () => {
+    const wrapped = composeGates([], echoTrail, echoTrail.blaze);
+    expect(wrapped).toBe(echoTrail.blaze);
   });
 });