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

package/src/__tests__/fork-ctx.test.ts

@@ -0,0 +1,83 @@
+import { describe, expect, test } from 'bun:test';
+
+import { forkCtx } from '../internal/fork-ctx';
+import type { CrossFn, FireFn, TrailContext } from '../types';
+
+// Sentinel values — the helper never invokes these, so their shapes are
+// irrelevant. What matters is identity: a forked ctx must either clear
+// them or preserve the exact reference.
+const noopCross = {} as unknown as CrossFn;
+const noopFire = {} as unknown as FireFn;
+const noopResource = {} as unknown as TrailContext['resource'];
+
+describe('forkCtx', () => {
+  test('clears cross, fire, and resource by default', () => {
+    const parent = {
+      cross: noopCross,
+      env: { NODE_ENV: 'test' },
+      extensions: { trailhead: 'cli' },
+      fire: noopFire,
+      logger: undefined,
+      resource: noopResource,
+    };
+
+    const forked = forkCtx(parent, {});
+
+    expect(forked.cross).toBeUndefined();
+    expect(forked.fire).toBeUndefined();
+    expect(forked.resource).toBeUndefined();
+    // Non-reset keys are preserved.
+    expect(forked.env).toEqual({ NODE_ENV: 'test' });
+    expect(forked.extensions).toEqual({ trailhead: 'cli' });
+  });
+
+  test('applies overrides after reset so overrides win', () => {
+    const parent = {
+      cross: noopCross,
+      env: { NODE_ENV: 'test' },
+      extensions: { a: 1 },
+      fire: noopFire,
+      resource: noopResource,
+    };
+
+    const forked = forkCtx(parent, {
+      env: { NODE_ENV: 'prod' },
+      extensions: { b: 2 },
+    });
+
+    expect(forked.env).toEqual({ NODE_ENV: 'prod' });
+    expect(forked.extensions).toEqual({ b: 2 });
+    expect(forked.cross).toBeUndefined();
+    expect(forked.fire).toBeUndefined();
+    expect(forked.resource).toBeUndefined();
+  });
+
+  test('does not mutate the parent context', () => {
+    const parent = {
+      cross: noopCross,
+      fire: noopFire,
+      resource: noopResource,
+    };
+
+    forkCtx(parent, {});
+
+    expect(parent.cross).toBe(noopCross);
+    expect(parent.fire).toBe(noopFire);
+    expect(parent.resource).toBe(noopResource);
+  });
+
+  test('honours a caller-supplied reset list', () => {
+    const parent = {
+      cross: noopCross,
+      fire: noopFire,
+      resource: noopResource,
+    };
+
+    const forked = forkCtx(parent, {}, ['fire']);
+
+    expect(forked.fire).toBeUndefined();
+    // Only `fire` is reset when caller overrides the list.
+    expect(forked.cross).toBe(noopCross);
+    expect(forked.resource).toBe(noopResource);
+  });
+});

package/src/__tests__/ingest.test.ts

@@ -0,0 +1,191 @@
+/* oxlint-disable require-await -- layer wrappers satisfy async interfaces without awaiting */
+import { describe, expect, test } from 'bun:test';
+
+import { z } from 'zod';
+
+import { ValidationError } from '../errors.js';
+import type { Layer } from '../layer.js';
+import { Result } from '../result.js';
+import { run } from '../run.js';
+import { signal } from '../signal.js';
+import { topo } from '../topo.js';
+import { trail } from '../trail.js';
+import { ingest } from '../trails/index.js';
+
+const withExamples = <TSchema extends z.ZodType>(
+  schema: TSchema,
+  examples: readonly z.input<TSchema>[]
+): TSchema & { readonly examples: readonly z.input<TSchema>[] } =>
+  Object.assign(schema, { examples });
+
+const paymentCompleted = signal('payment.completed', {
+  payload: z.object({
+    amount: z.number(),
+    paymentId: z.string(),
+  }),
+});
+
+const rawPaymentEvent = z.object({
+  amount: z.number(),
+  paymentId: z.string(),
+});
+
+const stripeEvent = z.object({
+  data: z.object({
+    object: z.object({
+      amount: z.number(),
+      id: z.string(),
+    }),
+  }),
+});
+
+const createConsumer = (
+  id: string,
+  capture: { payloads: unknown[] },
+  source = paymentCompleted
+) =>
+  trail(id, {
+    blaze: (input) => {
+      capture.payloads.push(input);
+      return Result.ok({ ok: true });
+    },
+    input: source.payload,
+    on: [source],
+  });
+
+describe('ingest()', () => {
+  test('derives id, intent, fires, output schema, and examples from schema examples', () => {
+    const schema = withExamples(rawPaymentEvent, [
+      { amount: 42, paymentId: 'pay_1' },
+      { amount: 7, paymentId: 'pay_2' },
+    ]);
+
+    const paymentIngest = ingest({
+      schema,
+      signal: paymentCompleted,
+    });
+
+    expect(paymentIngest.id).toBe('payment.completed.ingest');
+    expect(paymentIngest.intent).toBe('write');
+    expect(paymentIngest.pattern).toBe('ingest');
+    expect(paymentIngest.fires).toEqual(['payment.completed']);
+    expect(paymentIngest.output?.safeParse().success).toBe(true);
+    expect(paymentIngest.examples).toEqual([
+      {
+        input: { amount: 42, paymentId: 'pay_1' },
+        name: 'Ingest payment.completed 1',
+      },
+      {
+        input: { amount: 7, paymentId: 'pay_2' },
+        name: 'Ingest payment.completed 2',
+      },
+    ]);
+  });
+
+  test('validates input before attempting to emit the signal', async () => {
+    const capture = { payloads: [] as unknown[] };
+    const paymentIngest = ingest({
+      schema: rawPaymentEvent,
+      signal: paymentCompleted,
+    });
+
+    const app = topo('ingest-validation', {
+      consumer: createConsumer('payments.capture', capture),
+      paymentCompleted,
+      paymentIngest,
+    });
+
+    const result = await run(app, paymentIngest.id, {
+      amount: '42',
+      paymentId: 'pay_1',
+    });
+
+    expect(result.isErr()).toBe(true);
+    expect(result.error).toBeInstanceOf(ValidationError);
+    expect(capture.payloads).toEqual([]);
+  });
+
+  test('applies the verification layer when provided', async () => {
+    const wrapped: string[] = [];
+    const verify: Layer = {
+      name: 'verify',
+      wrap: (trailDef, implementation) => async (input, ctx) => {
+        wrapped.push(trailDef.id);
+        return await implementation(input, ctx);
+      },
+    };
+    const capture = { payloads: [] as unknown[] };
+    const paymentIngest = ingest({
+      schema: rawPaymentEvent,
+      signal: paymentCompleted,
+      verify,
+    });
+
+    const app = topo('ingest-verify', {
+      consumer: createConsumer('payments.capture', capture),
+      paymentCompleted,
+      paymentIngest,
+    });
+
+    const result = await run(app, paymentIngest.id, {
+      amount: 42,
+      paymentId: 'pay_1',
+    });
+
+    expect(result.isOk()).toBe(true);
+    expect(wrapped).toEqual(['payment.completed.ingest']);
+    expect(capture.payloads).toEqual([{ amount: 42, paymentId: 'pay_1' }]);
+  });
+
+  test('emits the declared signal after successful ingestion', async () => {
+    const capture = { payloads: [] as unknown[] };
+    const paymentIngest = ingest({
+      schema: rawPaymentEvent,
+      signal: paymentCompleted,
+    });
+
+    const app = topo('ingest-fire', {
+      consumer: createConsumer('payments.capture', capture),
+      paymentCompleted,
+      paymentIngest,
+    });
+
+    const result = await run(app, paymentIngest.id, {
+      amount: 42,
+      paymentId: 'pay_1',
+    });
+
+    expect(result.isOk()).toBe(true);
+    expect(capture.payloads).toEqual([{ amount: 42, paymentId: 'pay_1' }]);
+  });
+
+  test('applies the transform before emitting the signal payload', async () => {
+    const capture = { payloads: [] as unknown[] };
+    const paymentIngest = ingest({
+      schema: stripeEvent,
+      signal: paymentCompleted,
+      transform: (payload) => ({
+        amount: payload.data.object.amount,
+        paymentId: payload.data.object.id,
+      }),
+    });
+
+    const app = topo('ingest-transform', {
+      consumer: createConsumer('payments.capture', capture),
+      paymentCompleted,
+      paymentIngest,
+    });
+
+    const result = await run(app, paymentIngest.id, {
+      data: {
+        object: {
+          amount: 99,
+          id: 'pay_99',
+        },
+      },
+    });
+
+    expect(result.isOk()).toBe(true);
+    expect(capture.payloads).toEqual([{ amount: 99, paymentId: 'pay_99' }]);
+  });
+});

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

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

package/src/__tests__/path-security.test.ts

@@ -2,7 +2,7 @@ import { describe, test, expect } from 'bun:test';
 import { resolve, join } from 'node:path';
 
 import { PermissionError } from '../errors.js';
-import { securePath, isPathSafe, resolveSafePath } from '../path-security.js';
+import { securePath, isPathSafe, deriveSafePath } from '../path-security.js';
 
 // ---------------------------------------------------------------------------
 // securePath
@@ -81,33 +81,33 @@ describe('isPathSafe', () => {
 });
 
 // ---------------------------------------------------------------------------
-// resolveSafePath
+// deriveSafePath
 // ---------------------------------------------------------------------------
 
-describe('resolveSafePath', () => {
+describe('deriveSafePath', () => {
   const base = '/project/workspace';
 
   test('joins multiple segments safely', () => {
-    const result = resolveSafePath(base, 'src', 'lib', 'utils.ts');
+    const result = deriveSafePath(base, 'src', 'lib', 'utils.ts');
     expect(result.isOk()).toBe(true);
     expect(result.unwrap()).toBe(join(resolve(base), 'src', 'lib', 'utils.ts'));
   });
 
   test('rejects when segments escape the base', () => {
-    const result = resolveSafePath(base, 'src', '../../../etc');
+    const result = deriveSafePath(base, 'src', '../../../etc');
     expect(result.isErr()).toBe(true);
     const err = result as unknown as { error: PermissionError };
     expect(err.error).toBeInstanceOf(PermissionError);
   });
 
   test('handles single segment', () => {
-    const result = resolveSafePath(base, 'file.txt');
+    const result = deriveSafePath(base, 'file.txt');
     expect(result.isOk()).toBe(true);
     expect(result.unwrap()).toBe(resolve(base, 'file.txt'));
   });
 
   test('handles empty segments', () => {
-    const result = resolveSafePath(base);
+    const result = deriveSafePath(base);
     expect(result.isOk()).toBe(true);
     expect(result.unwrap()).toBe(resolve(base));
   });

package/src/__tests__/resilience.test.ts

@@ -11,7 +11,7 @@ import {
   retry,
   withTimeout,
   shouldRetry,
-  getBackoffDelay,
+  deriveBackoffDelay,
 } from '../resilience.js';
 import { Result } from '../result.js';
 
@@ -37,20 +37,20 @@ describe('shouldRetry', () => {
 });
 
 // ---------------------------------------------------------------------------
-// getBackoffDelay
+// deriveBackoffDelay
 // ---------------------------------------------------------------------------
 
-describe('getBackoffDelay', () => {
+describe('deriveBackoffDelay', () => {
   test('returns a number >= 0', () => {
     for (let i = 0; i < 20; i += 1) {
-      const delay = getBackoffDelay(0);
+      const delay = deriveBackoffDelay(0);
       expect(delay).toBeGreaterThanOrEqual(0);
     }
   });
 
   test('respects maxDelay cap', () => {
     for (let i = 0; i < 20; i += 1) {
-      const delay = getBackoffDelay(10, { maxDelay: 100 });
+      const delay = deriveBackoffDelay(10, { maxDelay: 100 });
       expect(delay).toBeLessThanOrEqual(100);
     }
   });
@@ -59,7 +59,7 @@ describe('getBackoffDelay', () => {
     // With attempt=0, exponential = base * factor^0 = base
     // Jitter is [0, base], so delay <= base
     for (let i = 0; i < 20; i += 1) {
-      const delay = getBackoffDelay(0, { backoffFactor: 3, baseDelay: 500 });
+      const delay = deriveBackoffDelay(0, { backoffFactor: 3, baseDelay: 500 });
       expect(delay).toBeLessThanOrEqual(500);
     }
   });
@@ -67,10 +67,10 @@ describe('getBackoffDelay', () => {
   test('scales with attempt number', () => {
     // Higher attempts should have higher caps (on average)
     const samples0 = Array.from({ length: 100 }, () =>
-      getBackoffDelay(0, { baseDelay: 100 })
+      deriveBackoffDelay(0, { baseDelay: 100 })
     );
     const samples3 = Array.from({ length: 100 }, () =>
-      getBackoffDelay(3, { baseDelay: 100 })
+      deriveBackoffDelay(3, { baseDelay: 100 })
     );
     const avg0 = samples0.reduce((a, b) => a + b, 0) / samples0.length;
     const avg3 = samples3.reduce((a, b) => a + b, 0) / samples3.length;