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

package/src/__tests__/{dispatch.test.ts → run.test.ts}

@@ -3,11 +3,11 @@ import { describe, test, expect } from 'bun:test';
 
 import { z } from 'zod';
 
-import { dispatch } from '../dispatch';
+import { run } from '../run';
 import { InternalError, NotFoundError, ValidationError } from '../errors';
-import type { Layer } from '../layer';
+import type { Gate } from '../gate';
 import { Result } from '../result';
-import { service } from '../service';
+import { provision } from '../provision';
 import { topo } from '../topo';
 import { trail } from '../trail';
 import type { TrailContext, TrailContextInit } from '../types';
@@ -17,16 +17,16 @@ 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 throwingTrail = trail('throws', {
-  input: z.object({}),
-  run: () => {
+  blaze: () => {
     throw new Error('kaboom');
   },
+  input: z.object({}),
 });
 
 const testTopo = topo('test', { echoTrail, throwingTrail });
@@ -35,34 +35,34 @@ const testTopo = topo('test', { echoTrail, throwingTrail });
 // Tests
 // ---------------------------------------------------------------------------
 
-describe('dispatch', () => {
+describe('run', () => {
   describe('happy path', () => {
-    test('dispatches by ID and returns Result.ok with expected value', async () => {
-      const result = await dispatch(testTopo, 'echo', { value: 'hello' });
+    test('executes by ID and returns Result.ok with expected value', async () => {
+      const result = await run(testTopo, 'echo', { value: 'hello' });
 
       expect(result.isOk()).toBe(true);
       expect(result.unwrap()).toEqual({ value: 'hello' });
     });
 
-    test('passes service overrides through to executeTrail', async () => {
-      const id = `dispatch.service.${Bun.randomUUIDv7()}`;
-      const db = service(id, {
+    test('passes provision overrides through to executeTrail', async () => {
+      const id = `run.provision.${Bun.randomUUIDv7()}`;
+      const db = provision(id, {
         create: () => Result.ok({ source: 'factory' }),
       });
       const searchTrail = trail('search', {
+        blaze: (_input, ctx) => Result.ok({ source: db.from(ctx).source }),
         input: z.object({}),
         output: z.object({ source: z.string() }),
-        run: (_input, ctx) => Result.ok({ source: db.from(ctx).source }),
-        services: [db],
+        provisions: [db],
       });
-      const searchTopo = topo('service-test', { searchTrail });
+      const searchTopo = topo('provision-test', { searchTrail });
 
-      const result = await dispatch(
+      const result = await run(
         searchTopo,
         'search',
         {},
         {
-          services: { [id]: { source: 'override' } },
+          provisions: { [id]: { source: 'override' } },
         }
       );
 
@@ -73,7 +73,7 @@ describe('dispatch', () => {
 
   describe('not found', () => {
     test('returns NotFoundError for unknown trail ID', async () => {
-      const result = await dispatch(testTopo, 'nonexistent', {});
+      const result = await run(testTopo, 'nonexistent', {});
 
       expect(result.isErr()).toBe(true);
       expect(result.error).toBeInstanceOf(NotFoundError);
@@ -84,18 +84,18 @@ describe('dispatch', () => {
 
   describe('validation', () => {
     test('returns ValidationError for invalid input', async () => {
-      const result = await dispatch(testTopo, 'echo', { value: 42 });
+      const result = await run(testTopo, 'echo', { value: 42 });
 
       expect(result.isErr()).toBe(true);
       expect(result.error).toBeInstanceOf(ValidationError);
     });
   });
 
-  describe('layers', () => {
-    test('layer composition works through dispatch', async () => {
+  describe('gates', () => {
+    test('gate composition works through run', 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');
@@ -106,11 +106,11 @@ describe('dispatch', () => {
         },
       };
 
-      const result = await dispatch(
+      const result = await run(
         testTopo,
         'echo',
         { value: 'x' },
-        { layers: [layer] }
+        { gates: [gate] }
       );
 
       expect(result.isOk()).toBe(true);
@@ -119,20 +119,20 @@ describe('dispatch', () => {
   });
 
   describe('context', () => {
-    test('context overrides work through dispatch', async () => {
+    test('context overrides work through run', async () => {
       let capturedCtx: TrailContext | undefined;
-      const ctxTrail = trail('ctx-dispatch-test', {
-        input: z.object({}),
-        run: (_input, ctx) => {
+      const ctxTrail = trail('ctx-run-test', {
+        blaze: (_input, ctx) => {
           capturedCtx = ctx;
           return Result.ok(null);
         },
+        input: z.object({}),
       });
 
       const ctxTopo = topo('ctx-test', { ctxTrail });
-      await dispatch(
+      await run(
         ctxTopo,
-        'ctx-dispatch-test',
+        'ctx-run-test',
         {},
         { ctx: { requestId: 'override-id' } }
       );
@@ -140,26 +140,26 @@ describe('dispatch', () => {
       expect(capturedCtx?.requestId).toBe('override-id');
     });
 
-    test('createContext factory works through dispatch', async () => {
+    test('createContext factory works through run', async () => {
       let capturedCtx: TrailContext | undefined;
-      const ctxTrail = trail('factory-dispatch-test', {
-        input: z.object({}),
-        run: (_input, ctx) => {
+      const ctxTrail = trail('factory-run-test', {
+        blaze: (_input, ctx) => {
           capturedCtx = ctx;
           return Result.ok(null);
         },
+        input: z.object({}),
       });
 
       const ctxTopo = topo('factory-test', { ctxTrail });
       const customCtx: TrailContextInit = {
+        abortSignal: new AbortController().signal,
         cwd: '/custom',
         requestId: 'factory-id',
-        signal: new AbortController().signal,
       };
 
-      await dispatch(
+      await run(
         ctxTopo,
-        'factory-dispatch-test',
+        'factory-run-test',
         {},
         { createContext: () => customCtx }
       );
@@ -171,7 +171,7 @@ describe('dispatch', () => {
 
   describe('error handling', () => {
     test('never throws — exceptions become InternalError', async () => {
-      const result = await dispatch(testTopo, 'throws', {});
+      const result = await run(testTopo, 'throws', {});
 
       expect(result.isErr()).toBe(true);
       expect(result.error).toBeInstanceOf(InternalError);

package/src/__tests__/service-config.test.ts

@@ -0,0 +1,228 @@
+/* oxlint-disable require-await -- trail implementations satisfy async interface without awaiting */
+import { describe, expect, test } from 'bun:test';
+
+import { z } from 'zod';
+
+import { executeTrail } from '../execute.js';
+import { Result } from '../result.js';
+import { provision } from '../provision.js';
+import { trail } from '../trail.js';
+import type { ProvisionContext } from '../provision.js';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const nextId = (name: string): string =>
+  `test.svc-config.${name}.${Bun.randomUUIDv7()}`;
+
+const createSingletonConfigTrail = (id: string) => {
+  const captures = { createCalls: 0 };
+  const svc = provision(id, {
+    config: z.object({ key: z.string() }),
+    create: (ctx: ProvisionContext<{ key: string }>) => {
+      captures.createCalls += 1;
+      return Result.ok({
+        createCall: captures.createCalls,
+        key: ctx.config.key,
+      });
+    },
+  });
+
+  return {
+    captures,
+    trail: trail('svc-config.singleton', {
+      blaze: (_input, ctx) =>
+        Result.ok({
+          createCall: svc.from(ctx).createCall,
+          key: svc.from(ctx).key,
+        }),
+      input: z.object({}),
+      output: z.object({ createCall: z.number(), key: z.string() }),
+      provisions: [svc],
+    }),
+  };
+};
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('ProvisionContext.config', () => {
+  test('provision with config schema receives validated config in svc.config', async () => {
+    const id = nextId('typed-config');
+    let capturedConfig: unknown;
+
+    const db = provision(id, {
+      config: z.object({ poolSize: z.number(), url: z.string().url() }),
+      create: (svc: ProvisionContext<{ url: string; poolSize: number }>) => {
+        capturedConfig = svc.config;
+        return Result.ok({ connected: true });
+      },
+    });
+
+    const dbTrail = trail('svc-config.typed', {
+      blaze: (_input, ctx) => Result.ok({ connected: db.from(ctx).connected }),
+      input: z.object({}),
+      output: z.object({ connected: z.boolean() }),
+      provisions: [db],
+    });
+
+    const result = await executeTrail(
+      dbTrail,
+      {},
+      {
+        configValues: {
+          [id]: { poolSize: 5, url: 'https://example.com' },
+        },
+      }
+    );
+
+    expect(result.isOk()).toBe(true);
+    expect(capturedConfig).toEqual({ poolSize: 5, url: 'https://example.com' });
+  });
+
+  test('provision without config still works — svc.config is undefined', async () => {
+    const id = nextId('no-config');
+    let capturedConfig: unknown = 'sentinel';
+
+    const counter = provision(id, {
+      create: (svc) => {
+        capturedConfig = svc.config;
+        return Result.ok(42);
+      },
+    });
+
+    const counterTrail = trail('svc-config.no-config', {
+      blaze: (_input, ctx) => Result.ok({ value: counter.from(ctx) }),
+      input: z.object({}),
+      provisions: [counter],
+    });
+
+    const result = await executeTrail(counterTrail, {});
+
+    expect(result.isOk()).toBe(true);
+    expect(capturedConfig).toBeUndefined();
+  });
+
+  test('config validation failure returns Result.err at provision creation time', async () => {
+    const id = nextId('invalid-config');
+
+    const db = provision(id, {
+      config: z.object({ url: z.string().url() }),
+      create: () => Result.ok({ connected: true }),
+    });
+
+    const dbTrail = trail('svc-config.invalid', {
+      blaze: () => Result.ok(null),
+      input: z.object({}),
+      provisions: [db],
+    });
+
+    const result = await executeTrail(
+      dbTrail,
+      {},
+      {
+        configValues: {
+          [id]: { url: 'not-a-url' },
+        },
+      }
+    );
+
+    expect(result.isErr()).toBe(true);
+    expect(result.error.message).toContain(id);
+  });
+
+  test('missing configValues for a provision with config schema returns Result.err', async () => {
+    const id = nextId('missing-config');
+
+    const db = provision(id, {
+      config: z.object({ url: z.string().url() }),
+      create: () => Result.ok({ connected: true }),
+    });
+
+    const dbTrail = trail('svc-config.missing', {
+      blaze: () => Result.ok(null),
+      input: z.object({}),
+      provisions: [db],
+    });
+
+    const result = await executeTrail(dbTrail, {});
+
+    expect(result.isErr()).toBe(true);
+    expect(result.error.message).toContain(id);
+  });
+
+  test('provision override bypasses config validation', async () => {
+    const id = nextId('override-bypass');
+
+    const db = provision(id, {
+      config: z.object({ url: z.string().url() }),
+      create: () => Result.ok({ connected: true }),
+    });
+
+    const dbTrail = trail('svc-config.override', {
+      blaze: (_input, ctx) => Result.ok({ value: db.from(ctx) as number }),
+      input: z.object({}),
+      output: z.object({ value: z.number() }),
+      provisions: [db],
+    });
+
+    // Provide the provision via overrides without any configValues — should NOT fail
+    const result = await executeTrail(
+      dbTrail,
+      {},
+      { provisions: { [id]: 42 } }
+    );
+
+    expect(result.isOk()).toBe(true);
+    expect(result.unwrap()).toEqual({ value: 42 });
+  });
+  test('config values passed through ExecuteTrailOptions.configValues', async () => {
+    const id = nextId('options-config');
+    const captures: unknown[] = [];
+
+    const svc = provision(id, {
+      config: z.object({ key: z.string() }),
+      create: (ctx: ProvisionContext<{ key: string }>) => {
+        captures.push(ctx.config);
+        return Result.ok({ key: ctx.config.key });
+      },
+    });
+
+    const svcTrail = trail('svc-config.options', {
+      blaze: (_input, ctx) => Result.ok({ key: svc.from(ctx).key }),
+      input: z.object({}),
+      output: z.object({ key: z.string() }),
+      provisions: [svc],
+    });
+
+    const result = await executeTrail(
+      svcTrail,
+      {},
+      {
+        configValues: { [id]: { key: 'hello' } },
+      }
+    );
+
+    expect(result.isOk()).toBe(true);
+    expect(result.unwrap()).toEqual({ key: 'hello' });
+    expect(captures).toEqual([{ key: 'hello' }]);
+  });
+
+  test('config-aware singleton provisions reuse the cached instance', async () => {
+    const id = nextId('singleton-config');
+    const { captures, trail: singletonTrail } = createSingletonConfigTrail(id);
+    const options = {
+      configValues: { [id]: { key: 'hello' } },
+    };
+    const first = await executeTrail(singletonTrail, {}, options);
+    const second = await executeTrail(singletonTrail, {}, options);
+
+    expect(first.isOk()).toBe(true);
+    expect(second.isOk()).toBe(true);
+    expect(first.unwrap()).toEqual({ createCall: 1, key: 'hello' });
+    expect(second.unwrap()).toEqual({ createCall: 1, key: 'hello' });
+    expect(captures.createCalls).toBe(1);
+  });
+});

package/src/__tests__/service.test.ts

@@ -4,18 +4,18 @@ import { z } from 'zod';
 import {
   Result,
   createTrailContext,
-  findDuplicateServiceId,
-  isService,
-  service as defineService,
+  findDuplicateProvisionId,
+  isProvision,
+  provision as defineProvision,
 } from '../index.js';
 import type {
-  Service,
-  ServiceContext,
-  ServiceSpec,
+  Provision,
+  ProvisionContext,
+  ProvisionSpec,
   TrailContext,
 } from '../index.js';
 
-const serviceCtx: ServiceContext = {
+const provisionCtx: ProvisionContext = {
   cwd: '/tmp/trails',
   env: { DATABASE_URL: 'file::memory:' },
   workspaceRoot: '/tmp',
@@ -23,39 +23,39 @@ const serviceCtx: ServiceContext = {
 
 let disposedValue: number | undefined;
 
-const counterServiceSpec: ServiceSpec<number> = {
+const counterProvisionSpec: ProvisionSpec<number> = {
   create: () => Result.ok(3),
-  description: 'Counter service',
-  dispose: (service) => {
-    disposedValue = service;
+  description: 'Counter provision',
+  dispose: (provision) => {
+    disposedValue = provision;
   },
-  health: (service) => Result.ok({ healthy: service > 0 }),
-  metadata: { domain: 'data' },
+  health: (provision) => Result.ok({ healthy: provision > 0 }),
+  meta: { domain: 'data' },
   mock: () => 1,
 };
 
 const resolvedServiceCtx = (id: string, instance: unknown): TrailContext =>
   createTrailContext({
+    abortSignal: new AbortController().signal,
     extensions: { [id]: instance },
     requestId: `${id}-request`,
-    signal: new AbortController().signal,
   });
 
-describe('service types', () => {
-  test('ServiceContext exposes the stable process-scoped fields', () => {
-    expect(serviceCtx.cwd).toBe('/tmp/trails');
-    expect(serviceCtx.env?.DATABASE_URL).toBe('file::memory:');
-    expect(serviceCtx.workspaceRoot).toBe('/tmp');
+describe('provision types', () => {
+  test('ProvisionContext exposes the stable process-scoped fields', () => {
+    expect(provisionCtx.cwd).toBe('/tmp/trails');
+    expect(provisionCtx.env?.DATABASE_URL).toBe('file::memory:');
+    expect(provisionCtx.workspaceRoot).toBe('/tmp');
   });
 
-  test('ServiceSpec stores description and metadata', () => {
-    expect(counterServiceSpec.description).toBe('Counter service');
-    expect(counterServiceSpec.metadata).toEqual({ domain: 'data' });
+  test('ProvisionSpec stores description and meta', () => {
+    expect(counterProvisionSpec.description).toBe('Counter provision');
+    expect(counterProvisionSpec.meta).toEqual({ domain: 'data' });
   });
 
-  test('ServiceSpec can reserve a config schema for future composition', () => {
+  test('ProvisionSpec can reserve a config schema for future composition', () => {
     const config = z.object({ url: z.string().url() });
-    const spec: ServiceSpec<number> = {
+    const spec: ProvisionSpec<number> = {
       config,
       create: () => Result.ok(1),
     };
@@ -63,72 +63,72 @@ describe('service types', () => {
     expect(spec.config).toBe(config);
   });
 
-  test('ServiceSpec create and health callbacks are callable', async () => {
-    const result = await counterServiceSpec.create(serviceCtx);
+  test('ProvisionSpec create and health callbacks are callable', async () => {
+    const result = await counterProvisionSpec.create(provisionCtx);
     expect(result.isOk()).toBe(true);
     expect(result.unwrap()).toBe(3);
 
-    const health = await counterServiceSpec.health?.(result.unwrap());
+    const health = await counterProvisionSpec.health?.(result.unwrap());
     expect(health?.isOk()).toBe(true);
     expect(health?.unwrap()).toEqual({ healthy: true });
   });
 
-  test('ServiceSpec mock and dispose callbacks are callable', async () => {
+  test('ProvisionSpec mock and dispose callbacks are callable', async () => {
     disposedValue = undefined;
-    const result = await counterServiceSpec.create(serviceCtx);
+    const result = await counterProvisionSpec.create(provisionCtx);
     expect(result.isOk()).toBe(true);
 
-    const service = result.unwrap();
-    expect(await counterServiceSpec.mock?.()).toBe(1);
+    const provision = result.unwrap();
+    expect(await counterProvisionSpec.mock?.()).toBe(1);
 
-    await counterServiceSpec.dispose?.(service);
+    await counterProvisionSpec.dispose?.(provision);
     expect(disposedValue).toBe(3);
   });
 
-  test('ServiceSpec create can be async', async () => {
-    const spec: ServiceSpec<number> = {
+  test('ProvisionSpec create can be async', async () => {
+    const spec: ProvisionSpec<number> = {
       create: async () => {
         await Bun.sleep(0);
         return Result.ok(7);
       },
     };
 
-    const result = await spec.create(serviceCtx);
+    const result = await spec.create(provisionCtx);
     expect(result.isOk()).toBe(true);
     expect(result.unwrap()).toBe(7);
   });
 
-  test('Service carries identity alongside the shared spec fields', async () => {
-    const service: Service<number> = {
+  test('Provision carries identity alongside the shared spec fields', async () => {
+    const counterProvision: Provision<number> = {
       from(ctx) {
-        return ctx.service(this);
+        return ctx.provision(this);
       },
       id: 'counter.main',
-      kind: 'service',
-      ...counterServiceSpec,
+      kind: 'provision',
+      ...counterProvisionSpec,
     };
 
-    expect(service.kind).toBe('service');
-    expect(service.id).toBe('counter.main');
+    expect(counterProvision.kind).toBe('provision');
+    expect(counterProvision.id).toBe('counter.main');
 
-    const created = await service.create(serviceCtx);
+    const created = await counterProvision.create(provisionCtx);
     expect(created.isOk()).toBe(true);
     expect(created.unwrap()).toBe(3);
-    expect(await service.mock?.()).toBe(1);
+    expect(await counterProvision.mock?.()).toBe(1);
   });
 });
 
-describe('service()', () => {
-  test('returns a frozen service object with kind and id', () => {
-    const counter = defineService('counter.main', counterServiceSpec);
+describe('provision()', () => {
+  test('returns a frozen provision object with kind and id', () => {
+    const counter = defineProvision('counter.main', counterProvisionSpec);
 
-    expect(counter.kind).toBe('service');
+    expect(counter.kind).toBe('provision');
     expect(counter.id).toBe('counter.main');
     expect(Object.isFrozen(counter)).toBe(true);
   });
 
-  test('infers the service type through from(ctx)', () => {
-    const db = defineService('db.main', {
+  test('infers the provision type through from(ctx)', () => {
+    const db = defineProvision('db.main', {
       create: () =>
         Result.ok({
           query(sql: string) {
@@ -149,48 +149,48 @@ describe('service()', () => {
     expect(resolved.query('select 1')).toBe(8);
   });
 
-  test('from(ctx) throws when the service is missing', () => {
-    const counter = defineService('counter.main', counterServiceSpec);
+  test('from(ctx) throws when the provision is missing', () => {
+    const counter = defineProvision('counter.main', counterProvisionSpec);
     const ctx = createTrailContext({
-      requestId: 'missing-service',
-      signal: new AbortController().signal,
+      abortSignal: new AbortController().signal,
+      requestId: 'missing-provision',
     });
 
     expect(() => counter.from(ctx)).toThrow(
-      'Service "counter.main" not found in trail context'
+      'Provision "counter.main" not found in trail context'
     );
   });
 
-  test('from(ctx) returns undefined when the service key exists with an undefined value', () => {
-    const optional = defineService<undefined>('optional.main', {
+  test('from(ctx) returns undefined when the provision key exists with an undefined value', () => {
+    const optional = defineProvision<undefined>('optional.main', {
       create: () => Result.ok<undefined>(),
     });
     const ctx = createTrailContext({
+      abortSignal: new AbortController().signal,
       extensions: { [optional.id]: undefined },
-      requestId: 'undefined-service',
-      signal: new AbortController().signal,
+      requestId: 'undefined-provision',
     });
 
     expect(optional.from(ctx)).toBeUndefined();
   });
 });
 
-describe('service helpers', () => {
-  test('isService identifies service definitions', () => {
-    const counter = defineService('counter.main', counterServiceSpec);
+describe('provision helpers', () => {
+  test('isProvision identifies provision definitions', () => {
+    const counter = defineProvision('counter.main', counterProvisionSpec);
 
-    expect(isService(counter)).toBe(true);
-    expect(isService({ id: 'counter.main', kind: 'trail' })).toBe(false);
-    expect(isService(null)).toBe(false);
+    expect(isProvision(counter)).toBe(true);
+    expect(isProvision({ id: 'counter.main', kind: 'trail' })).toBe(false);
+    expect(isProvision(null)).toBe(false);
   });
 
-  test('findDuplicateServiceId returns the first repeated ID', () => {
-    const first = defineService('counter.main', counterServiceSpec);
-    const duplicate = defineService('counter.main', counterServiceSpec);
-    const other = defineService('counter.secondary', counterServiceSpec);
+  test('findDuplicateProvisionId returns the first repeated ID', () => {
+    const first = defineProvision('counter.main', counterProvisionSpec);
+    const duplicate = defineProvision('counter.main', counterProvisionSpec);
+    const other = defineProvision('counter.secondary', counterProvisionSpec);
 
-    expect(findDuplicateServiceId([first, other])).toBeUndefined();
-    expect(findDuplicateServiceId([first, other, duplicate])).toBe(
+    expect(findDuplicateProvisionId([first, other])).toBeUndefined();
+    expect(findDuplicateProvisionId([first, other, duplicate])).toBe(
       'counter.main'
     );
   });