@ontrails/testing 1.0.0-beta.18 → 1.0.0-beta.19

package/src/{crosses.ts → composes.ts}

@@ -1,20 +1,21 @@
 /**
- * testCrosses — crossing-aware scenario testing for trails with crossings.
+ * testComposes — composing-aware scenario testing for trails with compositions.
  *
- * Tests the crossing graph: which trails were crossed, in what order,
- * and supports failure injection from crossed trail examples.
+ * Tests the composing graph: which trails were composed, in what order,
+ * and supports failure injection from composed trail examples.
  */
 
 import { describe, expect, test } from 'bun:test';
 
 import type {
   AnyTrail,
-  CrossFn,
+  ComposeFn,
+  ExecuteTrailOptions,
   ResourceOverrideMap,
   TrailContext,
 } from '@ontrails/core';
 import {
-  buildCrossValidationSchema,
+  buildComposeValidationSchema,
   executeTrail,
   InternalError,
   Result,
@@ -28,13 +29,18 @@ import {
   assertSchemaMatch,
 } from './assertions.js';
 import { mergeResourceOverrides, mergeTestContext } from './context.js';
-import type { CrossScenario } from './types.js';
+import { createErrorFromName } from './errors.js';
+import type { ComposeScenario } from './types.js';
+
+type TestingExecuteTrailOptions = ExecuteTrailOptions & {
+  readonly validationSchema?: ReturnType<typeof buildComposeValidationSchema>;
+};
 
 // ---------------------------------------------------------------------------
-// Cross trace
+// Compose trace
 // ---------------------------------------------------------------------------
 
-interface CrossRecord {
+interface ComposeRecord {
   readonly id: string;
   readonly input: unknown;
 }
@@ -63,10 +69,10 @@ const collectDeclaredResources = (
     }
     seenTrailIds.add(candidate.id);
     collect(candidate);
-    for (const crossedId of candidate.crosses) {
-      const crossedTrail = trailsMap?.get(crossedId);
-      if (crossedTrail) {
-        visit(crossedTrail);
+    for (const composedId of candidate.composes) {
+      const composedTrail = trailsMap?.get(composedId);
+      if (composedTrail) {
+        visit(composedTrail);
       }
     }
   };
@@ -75,7 +81,7 @@ const collectDeclaredResources = (
   return resources;
 };
 
-const resolveCrossMockResources = async (
+const resolveComposeMockResources = async (
   trailDef: AnyTrail,
   trailsMap: ReadonlyMap<string, AnyTrail> | undefined
 ): Promise<ResourceOverrideMap> => {
@@ -114,12 +120,12 @@ const findErrorExample = (
 };
 
 /**
- * Try to inject an error from a crossed trail's example.
+ * Try to inject an error from a composed trail's example.
  * Returns undefined when no injection is configured for this trail ID.
  */
 const tryInjectError = (
   id: string,
-  scenario: CrossScenario,
+  scenario: ComposeScenario,
   trailsMap: ReadonlyMap<string, AnyTrail> | undefined
 ): Result<unknown, Error> | undefined => {
   const injection = scenario.injectFromExample?.[id];
@@ -141,7 +147,7 @@ const tryInjectError = (
       )
     );
   }
-  return Result.err(new Error(errorName));
+  return Result.err(createErrorFromName(errorName));
 };
 
 const executeFromMap = (
@@ -150,65 +156,67 @@ const executeFromMap = (
   trailsMap: ReadonlyMap<string, AnyTrail> | undefined,
   ctx: TrailContext,
   resources: ResourceOverrideMap | undefined,
-  cross?: CrossFn
+  compose?: ComposeFn
 ): Result<unknown, Error> | Promise<Result<unknown, Error>> | undefined => {
   const trailDef = trailsMap?.get(id);
   if (trailDef === undefined) {
     return undefined;
   }
 
-  const nestedCtx = cross ? { ...ctx, cross } : ctx;
-  return executeTrail(trailDef, input, {
+  const nestedCtx = compose ? { ...ctx, compose } : ctx;
+  const options: TestingExecuteTrailOptions = {
     ctx: nestedCtx,
     resources,
-    validationSchema: buildCrossValidationSchema(trailDef),
-  });
+    validationSchema: buildComposeValidationSchema(trailDef),
+  };
+  return executeTrail(trailDef, input, options);
 };
 
 /** Extract trail ID from either a trail object or a string. */
-const resolveCrossId = (idOrTrail: string | { readonly id: string }): string =>
-  typeof idOrTrail === 'string' ? idOrTrail : idOrTrail.id;
+const resolveComposeId = (
+  idOrTrail: string | { readonly id: string }
+): string => (typeof idOrTrail === 'string' ? idOrTrail : idOrTrail.id);
 
 // ---------------------------------------------------------------------------
-// Cross factory
+// Compose factory
 // ---------------------------------------------------------------------------
 
-/** Delegate to baseCross, executeFromMap, or fall back to Result.ok(). */
-const delegateCross = (
+/** Delegate to baseCompose, executeFromMap, or fall back to Result.ok(). */
+const delegateCompose = (
   id: string,
   input: unknown,
-  baseCross: CrossFn | undefined,
+  baseCompose: ComposeFn | undefined,
   trailsMap: ReadonlyMap<string, AnyTrail> | undefined,
   ctx: TrailContext,
   resources: ResourceOverrideMap | undefined,
-  self: CrossFn
+  self: ComposeFn
 ): Promise<Result<unknown, Error>> => {
-  if (baseCross !== undefined) {
-    return baseCross(id, input);
+  if (baseCompose !== undefined) {
+    return baseCompose(id, input);
   }
   const executed = executeFromMap(id, input, trailsMap, ctx, resources, self);
   return Promise.resolve(executed ?? Result.ok());
 };
 
 /**
- * Build a recording cross function that optionally injects errors.
+ * Build a recording compose function that optionally injects errors.
  */
-const createRecordingCross = (
-  trace: CrossRecord[],
-  scenario: CrossScenario,
+const createRecordingCompose = (
+  trace: ComposeRecord[],
+  scenario: ComposeScenario,
   trailsMap: ReadonlyMap<string, AnyTrail> | undefined,
-  baseCross: CrossFn | undefined,
+  baseCompose: ComposeFn | undefined,
   ctx: TrailContext,
   resources: ResourceOverrideMap | undefined
-): CrossFn => {
-  // The generic O on CrossFn is erased at runtime; the cast is safe
+): ComposeFn => {
+  // The generic O on ComposeFn is erased at runtime; the cast is safe
   // because callers narrow via isOk/isErr before accessing the value.
-  const invokeCross = async (
+  const invokeCompose = async (
     idOrTrail: string | { readonly id: string },
     input: unknown,
-    self: CrossFn
+    self: ComposeFn
   ) => {
-    const id = resolveCrossId(idOrTrail);
+    const id = resolveComposeId(idOrTrail);
     trace.push({ id, input });
 
     const injected = tryInjectError(id, scenario, trailsMap);
@@ -216,10 +224,10 @@ const createRecordingCross = (
       return injected;
     }
 
-    return await delegateCross(
+    return await delegateCompose(
       id,
       input,
-      baseCross,
+      baseCompose,
       trailsMap,
       ctx,
       resources,
@@ -227,9 +235,9 @@ const createRecordingCross = (
     );
   };
 
-  // Accepts either a trail object (typed cross), a string id (untyped),
+  // Accepts either a trail object (typed compose), a string id (untyped),
   // or a batch of `[target, input]` tuples.
-  const cross = async function cross(
+  const compose = async function compose(
     idOrTrail:
       | string
       | { readonly id: string }
@@ -239,19 +247,19 @@ const createRecordingCross = (
     if (Array.isArray(idOrTrail)) {
       return await Promise.all(
         idOrTrail.map(([target, batchInput]) =>
-          invokeCross(target, batchInput, cross as CrossFn)
+          invokeCompose(target, batchInput, compose as ComposeFn)
         )
       );
     }
 
-    return await invokeCross(
+    return await invokeCompose(
       idOrTrail as string | { readonly id: string },
       input,
-      cross as CrossFn
+      compose as ComposeFn
     );
-  } as CrossFn;
+  } as ComposeFn;
 
-  return cross;
+  return compose;
 };
 
 // ---------------------------------------------------------------------------
@@ -260,7 +268,7 @@ const createRecordingCross = (
 
 const assertScenarioResult = (
   result: Result<unknown, Error>,
-  scenario: CrossScenario,
+  scenario: ComposeScenario,
   trailDef: AnyTrail
 ): void => {
   if (scenario.expectValue !== undefined) {
@@ -278,26 +286,26 @@ const assertScenarioResult = (
   }
 };
 
-const assertCrossTrace = (
-  trace: readonly CrossRecord[],
-  scenario: CrossScenario
+const assertComposeTrace = (
+  trace: readonly ComposeRecord[],
+  scenario: ComposeScenario
 ): void => {
-  if (scenario.expectCrossed !== undefined) {
-    const crossedIds = trace.map((r) => r.id);
-    expect(crossedIds).toEqual([...scenario.expectCrossed]);
+  if (scenario.expectComposed !== undefined) {
+    const composedIds = trace.map((r) => r.id);
+    expect(composedIds).toEqual([...scenario.expectComposed]);
   }
-  if (scenario.expectCrossedCount !== undefined) {
+  if (scenario.expectComposedCount !== undefined) {
     const counts: Record<string, number> = {};
     for (const record of trace) {
       counts[record.id] = (counts[record.id] ?? 0) + 1;
     }
-    expect(counts).toEqual({ ...scenario.expectCrossedCount });
+    expect(counts).toEqual({ ...scenario.expectComposedCount });
   }
 };
 
 const handleValidationError = (
   validated: Result<unknown, Error>,
-  scenario: CrossScenario
+  scenario: ComposeScenario
 ): boolean => {
   if (!validated.isErr()) {
     return false;
@@ -319,27 +327,27 @@ const handleValidationError = (
 // ---------------------------------------------------------------------------
 
 const buildTestContext = (
-  scenario: CrossScenario,
+  scenario: ComposeScenario,
   ctx: Partial<TrailContext> | undefined,
   trailsMap: ReadonlyMap<string, AnyTrail> | undefined,
   resources: ResourceOverrideMap | undefined
-): { trace: CrossRecord[]; testCtx: TrailContext } => {
-  const trace: CrossRecord[] = [];
+): { trace: ComposeRecord[]; testCtx: TrailContext } => {
+  const trace: ComposeRecord[] = [];
   const baseCtx = mergeTestContext(ctx);
-  const cross = createRecordingCross(
+  const compose = createRecordingCompose(
     trace,
     scenario,
     trailsMap,
-    baseCtx.cross,
+    baseCtx.compose,
     baseCtx,
     resources
   );
-  return { testCtx: { ...baseCtx, cross }, trace };
+  return { testCtx: { ...baseCtx, compose }, trace };
 };
 
 const runScenario = async (
   trailDef: AnyTrail,
-  scenario: CrossScenario,
+  scenario: ComposeScenario,
   ctx: Partial<TrailContext> | undefined,
   trailsMap: ReadonlyMap<string, AnyTrail> | undefined,
   resources: ResourceOverrideMap | undefined
@@ -359,16 +367,16 @@ const runScenario = async (
     ctx: testCtx,
     resources,
   });
-  assertCrossTrace(trace, scenario);
+  assertComposeTrace(trace, scenario);
   assertScenarioResult(result, scenario, trailDef);
 };
 
 // ---------------------------------------------------------------------------
-// testCrosses
+// testComposes
 // ---------------------------------------------------------------------------
 
-/** Options for testCrosses that provide trail definitions for injection. */
-export interface TestCrossOptions {
+/** Options for testComposes that provide trail definitions for injection. */
+export interface TestComposeOptions {
   /** Partial context overrides. */
   readonly ctx?: Partial<TrailContext> | undefined;
   /**
@@ -382,33 +390,33 @@ export interface TestCrossOptions {
 }
 
 /**
- * Generate a describe block for a trail with crossings with one test per scenario.
+ * Generate a describe block for a trail with compositions with one test per scenario.
  *
  * @example
  * ```ts
- * testCrosses(onboardTrail, [
+ * testComposes(onboardTrail, [
  *   {
- *     description: "crosses add then relate",
+ *     description: "composes add then relate",
  *     input: { name: "Alpha" },
  *     expectOk: true,
- *     expectCrossed: ["entity.add", "entity.relate"],
+ *     expectComposed: ["entity.add", "entity.relate"],
  *   },
  * ]);
  * ```
  */
-export const testCrosses = (
+export const testComposes = (
   trailDef: AnyTrail,
-  scenarios: readonly CrossScenario[],
-  options?: TestCrossOptions
+  scenarios: readonly ComposeScenario[],
+  options?: TestComposeOptions
 ): void => {
   const explicitResources = options?.resources;
 
   describe(trailDef.id, () => {
     test.each([...scenarios])(
       '$description',
-      async (scenario: CrossScenario) => {
+      async (scenario: ComposeScenario) => {
         const resources = mergeResourceOverrides(
-          await resolveCrossMockResources(trailDef, options?.trails),
+          await resolveComposeMockResources(trailDef, options?.trails),
           options?.ctx,
           explicitResources
         );

package/src/context.ts

@@ -3,14 +3,14 @@
  */
 
 import type {
-  CrossFn,
+  ComposeFn,
   ResourceOverrideMap,
   Topo,
   TrailContext,
 } from '@ontrails/core';
 import {
   Result,
-  buildCrossValidationSchema,
+  buildComposeValidationSchema,
   createResourceLookup,
   passthroughTrace,
 } from '@ontrails/core';
@@ -53,10 +53,10 @@ export const createTestContext = (
 };
 
 // ---------------------------------------------------------------------------
-// createCrossContext
+// createComposeContext
 // ---------------------------------------------------------------------------
 
-export interface CreateCrossContextOptions {
+export interface CreateComposeContextOptions {
   readonly responses?: Record<string, Result<unknown, Error>> | undefined;
 }
 
@@ -94,39 +94,38 @@ export interface TestExecutionOptions {
 }
 
 /**
- * Create a mock `CrossFn` for testing composite trails.
+ * Create a mock `ComposeFn` for testing composite trails.
  *
  * Returns preconfigured `Result` values keyed by trail ID. Calls to
  * unregistered IDs return `Result.err` with a descriptive message.
  *
  * @example
  * ```ts
- * const cross = createCrossContext({
+ * const compose = createComposeContext({
  *   responses: { 'entity.add': Result.ok({ id: '1', name: 'Alpha' }) },
  * });
- * const ctx = { ...createTestContext(), cross };
+ * const ctx = { ...createTestContext(), compose };
  * ```
  */
-export const createCrossContext = (
-  options?: CreateCrossContextOptions
-): CrossFn => {
+export const createComposeContext = (
+  options?: CreateComposeContextOptions
+): ComposeFn => {
   const responses = options?.responses ?? {};
-  const respondToCross = <O>(
+  const respondToCompose = <O>(
     idOrTrail: string | { readonly id: string }
   ): Promise<Result<O, Error>> => {
     const id = typeof idOrTrail === 'string' ? idOrTrail : idOrTrail.id;
     const response = responses[id];
     if (response === undefined) {
       return Promise.resolve(
-        Result.err(new Error(`No mock response for cross("${id}")`)) as Result<
-          O,
-          Error
-        >
+        Result.err(
+          new Error(`No mock response for compose("${id}")`)
+        ) as Result<O, Error>
       );
     }
     return Promise.resolve(response as Result<O, Error>);
   };
-  const cross = (async (
+  const compose = (async (
     idOrTrail:
       | string
       | { readonly id: string }
@@ -135,13 +134,15 @@ export const createCrossContext = (
   ) => {
     if (Array.isArray(idOrTrail)) {
       return await Promise.all(
-        idOrTrail.map(([target]) => respondToCross(target))
+        idOrTrail.map(([target]) => respondToCompose(target))
       );
     }
 
-    return await respondToCross(idOrTrail as string | { readonly id: string });
-  }) as CrossFn;
-  return cross;
+    return await respondToCompose(
+      idOrTrail as string | { readonly id: string }
+    );
+  }) as ComposeFn;
+  return compose;
 };
 
 /**
@@ -200,7 +201,7 @@ export const createMockResources = async (
 ): Promise<ResourceOverrideMap> => await buildMockResources(app);
 
 // Re-export from core so existing consumers of this module continue to work.
-export { buildCrossValidationSchema };
+export { buildComposeValidationSchema };
 
 /**
  * Merge a Partial<TrailContext> into a test context.

package/src/contracts.ts

@@ -2,7 +2,7 @@
  * testContracts — output schema verification.
  *
  * For every trail that has both examples and an output schema,
- * run each example and validate the implementation output against
+ * run each example and validate the Result.ok value against
  * the declared schema.
  */
 
@@ -20,7 +20,8 @@ import {
   createMockResources,
 } from './context.js';
 import type { TestExecutionOptions } from './context.js';
-import { deriveTrailExamples } from './effective-examples.js';
+import type { TrailExampleTarget } from './effective-examples.js';
+import { deriveTrailExampleTargets } from './effective-examples.js';
 
 // ---------------------------------------------------------------------------
 // Helpers
@@ -41,13 +42,22 @@ const validateOutputSchema = (
   }
 };
 
+type ContractExampleTarget = TrailExampleTarget & {
+  readonly output: z.ZodType;
+};
+
+const hasContractExamples = (
+  target: TrailExampleTarget
+): target is ContractExampleTarget =>
+  target.output !== undefined && target.examples.length > 0;
+
 // ---------------------------------------------------------------------------
 // testContracts
 // ---------------------------------------------------------------------------
 
 /**
- * Verify that every trail implementation output matches its declared
- * output schema. Catches implementation-schema drift.
+ * Verify that every successful trail result matches its declared
+ * output schema. Catches output-schema drift.
  *
  * Trails without output schemas or examples are skipped.
  */
@@ -60,21 +70,12 @@ export const testContracts = (
 ): void => {
   const resolveInput =
     typeof ctxOrFactory === 'function' ? ctxOrFactory : () => ctxOrFactory;
-  const allEntries = (app.list() as Trail<unknown, unknown, unknown>[]).map(
-    (trailDef) => ({
-      ...trailDef,
-      examples: deriveTrailExamples(trailDef),
-    })
-  );
+  const allEntries = (app.list() as Trail<unknown, unknown, unknown>[])
+    .flatMap(deriveTrailExampleTargets)
+    .filter(hasContractExamples);
 
   describe('contracts', () => {
     describe.each(allEntries)('$id', (t) => {
-      if (t.output === undefined) {
-        return;
-      }
-      if (t.examples.length === 0) {
-        return;
-      }
       const { examples, output: outputSchema } = t;
       const successExamples = examples.filter((e) => e.error === undefined);
 
@@ -92,10 +93,11 @@ export const testContracts = (
           const validated = validateInput(t.input, example.input);
           expectOk(validated);
 
-          const result = await executeTrail(t, example.input, {
+          const result = await executeTrail(t.trail, example.input, {
             ctx: testCtx,
             resources,
             topo: app,
+            ...(t.version === undefined ? {} : { version: t.version }),
           });
           const resultValue = expectOk(result);
 

package/src/effective-examples.ts

@@ -1,16 +1,34 @@
 import type { AnyContour, Trail, TrailExample } from '@ontrails/core';
-import { getContourReferences } from '@ontrails/core';
+import {
+  getContourReferences,
+  getTrailVersionEntryKind,
+  isArchivedTrailVersionEntry,
+} from '@ontrails/core';
 import { z } from 'zod';
 
 type ExampleRecord = Readonly<Record<string, unknown>>;
 
+export interface TrailExampleTarget {
+  readonly composes: readonly string[];
+  readonly current: boolean;
+  readonly examples: readonly TrailExample<unknown, unknown>[];
+  readonly id: string;
+  readonly input: Trail<unknown, unknown, unknown>['input'];
+  readonly output: Trail<unknown, unknown, unknown>['output'];
+  readonly trail: Trail<unknown, unknown, unknown>;
+  readonly version?: number | undefined;
+}
+
+const normalizeComposeRef = (value: string | { readonly id: string }): string =>
+  typeof value === 'string' ? value : value.id;
+
 /**
  * Tracks examples that `deriveTrailExamples` synthesizes from contour
  * fixtures. Authored examples are passed through untouched and never
  * appear here, so consumers can distinguish the two by identity.
  *
  * Exposed via `isDerivedExample` so downstream testing helpers (e.g.
- * `testExamples` crossing coverage) can relax invariants that only make
+ * `testExamples` composing coverage) can relax invariants that only make
  * sense for authored inputs.
  */
 const derivedExamples = new WeakSet<TrailExample<unknown, unknown>>();
@@ -288,7 +306,7 @@ const formatFixtureName = (
  * Examples returned by this helper come from one of two provenances:
  * - **Authored.** When `trail.examples` is non-empty, its entries are
  *   returned verbatim. These are the developer's stated intent and carry
- *   full invariants — including crossing-coverage assertions in
+ *   full invariants — including composing-coverage assertions in
  *   `testExamples`.
  * - **Derived.** When there are no authored examples but the trail has
  *   contours with examples, candidate inputs are synthesized from contour
@@ -348,3 +366,49 @@ export const deriveTrailExamples = (
     return [derived];
   });
 };
+
+export const deriveTrailExampleTargets = (
+  trail: Trail<unknown, unknown, unknown>
+): readonly TrailExampleTarget[] => {
+  const targets: TrailExampleTarget[] = [];
+  const currentExamples = deriveTrailExamples(trail);
+  if (currentExamples.length > 0) {
+    targets.push({
+      composes: trail.composes,
+      current: true,
+      examples: currentExamples,
+      id: trail.id,
+      input: trail.input,
+      output: trail.output,
+      trail,
+    });
+  }
+
+  for (const [rawVersion, entry] of Object.entries(
+    trail.versions ?? {}
+  ).toSorted(([left], [right]) => Number(left) - Number(right))) {
+    if (isArchivedTrailVersionEntry(entry)) {
+      continue;
+    }
+    const examples = entry.examples ?? [];
+    if (examples.length === 0) {
+      continue;
+    }
+    const kind = getTrailVersionEntryKind(entry);
+    targets.push({
+      composes:
+        kind === 'fork'
+          ? (entry.composes ?? []).map(normalizeComposeRef)
+          : trail.composes,
+      current: false,
+      examples,
+      id: `${trail.id}@${rawVersion}`,
+      input: entry.input,
+      output: entry.output,
+      trail,
+      version: Number(rawVersion),
+    });
+  }
+
+  return targets;
+};