@ontrails/core 1.0.0-beta.17 → 1.0.0-beta.19

package/src/execute.ts

@@ -8,11 +8,12 @@
 
 import type { z } from 'zod';
 
-import type { AnyTrail } from './trail.js';
+import type { AnyTrail, TrailVersionForkEntry } from './trail.js';
 import type { Layer } from './layer.js';
 import type { ResourceOverrideMap } from './resource.js';
 import type { TraceContext, TraceRecord } from './tracing.js';
 import type { Topo } from './topo.js';
+import type { TrailVersionReference } from './version-resolution.js';
 
 import {
   buildActivationProvenanceTraceAttrs,
@@ -26,8 +27,9 @@ import {
 } from './fire.js';
 import type { BasePermit } from './permits.js';
 import type {
-  CrossBatchOptions,
-  CrossFn,
+  ComposeBatchOptions,
+  ComposeOptions,
+  ComposeFn,
   Detour,
   Implementation,
   TraceFn,
@@ -36,7 +38,7 @@ import type {
 } from './types.js';
 
 import { createTrailContext, passthroughTrace } from './context.js';
-import { buildCrossValidationSchema } from './cross-schema.js';
+import { buildComposeValidationSchema } from './compose-schema.js';
 import {
   CancelledError,
   InternalError,
@@ -47,10 +49,10 @@ import {
   ValidationError,
 } from './errors.js';
 import {
-  claimNextCrossBatchIndex,
-  createCrossBatchValidationResults,
-  normalizeCrossBatchConcurrency,
-} from './cross-batch.js';
+  claimNextComposeBatchIndex,
+  createComposeBatchValidationResults,
+  normalizeComposeBatchConcurrency,
+} from './compose-batch.js';
 import { forkCtx } from './internal/fork-ctx.js';
 import {
   TRACE_CONTEXT_KEY,
@@ -72,11 +74,22 @@ import { createResourceLookup } from './resource.js';
 import { createResources } from './resource-config.js';
 import { LAYER_INPUTS_KEY, SURFACE_KEY } from './types.js';
 import { validateInput, validateOutput } from './validation.js';
+import { executeTrailRevision } from './version-runtime.js';
+import type { TrailVersionCurrentExecutor } from './version-runtime.js';
+import {
+  parseTrailIdVersionReference,
+  resolveTrailVersion,
+} from './version-resolution.js';
 
 type MutableTrailContext = {
   -readonly [K in keyof TrailContext]: TrailContext[K];
 };
 
+type ComposeForwardOptions = Omit<
+  ExecuteTrailInternalOptions,
+  'createContext' | 'composeValidation' | 'validationSchema' | 'version'
+>;
+
 // ---------------------------------------------------------------------------
 // Options
 // ---------------------------------------------------------------------------
@@ -90,7 +103,7 @@ export interface ExecuteTrailOptions {
   /**
    * Typed layers supplied for this execution.
    *
-   * Layers compose around the trail implementation. Layers without `input`
+   * Layers compose around the blaze. Layers without `input`
    * schemas are surface-invisible wrappers for concerns such as tenant guards,
    * rate limiting, circuit breaking, or custom audit logging.
    */
@@ -153,15 +166,41 @@ export interface ExecuteTrailOptions {
    * @see TRL-473 for the CLI projection contract.
    */
   readonly layerInputs?: Readonly<Record<string, unknown>> | undefined;
+  /**
+   * Execute a specific live trail version.
+   *
+   * Omit for the current top-level contract. Number and numeric-string
+   * references select authored versions; marker references select projected
+   * content-addressed markers by unambiguous prefix.
+   */
+  readonly version?: TrailVersionReference | undefined;
+}
+
+/**
+ * Internal executor options used by framework-managed compose and fork dispatch.
+ *
+ * These fields intentionally stay out of the exported public
+ * {@link ExecuteTrailOptions} surface.
+ */
+interface ExecuteTrailInternalOptions extends ExecuteTrailOptions {
+  /**
+   * Marks this invocation as a `ctx.compose()` dispatch so versioned fork
+   * entries validate against their own `composeInput`.
+   *
+   * Used by the compose execution path; not part of the public API.
+   *
+   * @internal
+   */
+  readonly composeValidation?: boolean | undefined;
   /**
    * Override the validation schema used for input validation.
    *
-   * When a trail is invoked via `ctx.cross()` and the target declares
-   * `crossInput`, the cross function merges `trail.input` with
-   * `trail.crossInput` and passes the merged schema here so validation
+   * When a trail is invoked via `ctx.compose()` and the target declares
+   * `composeInput`, the compose function merges `trail.input` with
+   * `trail.composeInput` and passes the merged schema here so validation
    * accepts both public and composition-only fields.
    *
-   * Used by the cross execution path; not part of the public API.
+   * Used by the compose execution path; not part of the public API.
    *
    * @internal
    */
@@ -174,7 +213,7 @@ export interface ExecuteTrailOptions {
 
 const applyContextOverrides = (
   base: TrailContextInit,
-  options?: ExecuteTrailOptions
+  options?: ExecuteTrailInternalOptions
 ): TrailContextInit => {
   const withOverrides = options?.ctx
     ? {
@@ -202,7 +241,7 @@ const applyContextOverrides = (
     return withPermit;
   }
   // Merge per-layer inputs onto any inherited LAYER_INPUTS_KEY slot so
-  // crossed/forked contexts can preserve outer-surface routing.
+  // composed/forked contexts can preserve outer-surface metadata.
   const inheritedExtensions = withPermit.extensions ?? {};
   const inheritedLayerInputs = (inheritedExtensions[LAYER_INPUTS_KEY] ?? {}) as
     | Readonly<Record<string, unknown>>
@@ -221,7 +260,7 @@ const applyContextOverrides = (
 
 const bindResourceLookup = (
   resolved: TrailContextInit,
-  options?: ExecuteTrailOptions
+  options?: ExecuteTrailInternalOptions
 ): TrailContext => {
   if (
     options?.ctx?.extensions === undefined &&
@@ -250,7 +289,7 @@ const bindResourceLookup = (
  *    already carries.
  */
 const resolveContext = async (
-  options?: ExecuteTrailOptions
+  options?: ExecuteTrailInternalOptions
 ): Promise<TrailContext> => {
   const seed = options?.createContext
     ? await options.createContext()
@@ -335,7 +374,7 @@ const enforcePermitRequirement = (
 
 const prepareContext = async (
   trail: AnyTrail,
-  options?: ExecuteTrailOptions
+  options?: ExecuteTrailInternalOptions
 ): Promise<
   Result<
     { readonly ctx: TrailContext; readonly releaseResources: () => void },
@@ -435,8 +474,8 @@ const extractPermit = (
  * The returned function reads the *current* trace context from its captured
  * parent. That means direct nesting (`ctx.trace('a', () => ctx.trace('b',
  * ...))`) produces siblings under `a`'s parent, not children of `a`. For
- * true child nesting, callers should cross into another trail (which gets
- * its own root record parented by this one) — full cross-trail parenting
+ * true child nesting, callers should compose into another trail (which gets
+ * its own root record parented by this one) — full compose-trail parenting
  * is implemented in a later phase. For Phase 1, sibling spans under the
  * trail's root are the supported shape.
  */
@@ -464,7 +503,7 @@ const buildTracedContext = (
   sink: ReturnType<typeof getTraceSink>
 ): { readonly record: TraceRecord; readonly tracedCtx: TrailContext } => {
   // If a parent trace context is present (set by an outer executeTrail when
-  // the current trail was invoked via ctx.cross or ctx.fire), inherit its
+  // the current trail was invoked via ctx.compose or ctx.fire), inherit its
   // traceId/rootId so the trace tree spans trail boundaries. Otherwise this
   // execution becomes a fresh root.
   const parent = ctx.extensions?.[TRACE_CONTEXT_KEY] as
@@ -553,25 +592,35 @@ const runImplWithRootRecord = async (
   }
 };
 
-const resolveCrossTarget = (
+interface ResolvedComposeTarget {
+  readonly trail: AnyTrail;
+  readonly version?: TrailVersionReference | undefined;
+}
+
+const resolveComposeTarget = (
   trailOrId: AnyTrail | string,
   topo: Topo | undefined
-): Result<AnyTrail, Error> => {
+): Result<ResolvedComposeTarget, Error> => {
   if (typeof trailOrId !== 'string') {
-    return Result.ok(trailOrId);
+    return Result.ok({ trail: trailOrId });
+  }
+
+  const parsed = parseTrailIdVersionReference(trailOrId);
+  if (parsed.isErr()) {
+    return parsed;
   }
 
   if (topo === undefined) {
     return Result.err(
       new NotFoundError(
-        `Trail "${trailOrId}" cannot be crossed without topo access`
+        `Trail "${trailOrId}" cannot be composed without topo access`
       )
     );
   }
 
-  const target = topo.get(trailOrId);
+  const target = topo.get(parsed.value.id);
   return target
-    ? Result.ok(target)
+    ? Result.ok({ trail: target, version: parsed.value.version })
     : Result.err(
         new NotFoundError(
           `Trail "${trailOrId}" not found in topo "${topo.name}"`
@@ -613,7 +662,7 @@ const deriveConcurrentBranchObserveMetadata = (
   return {
     ...readObserveLoggerMetadata(ctx),
     branchIndex,
-    crossedTrailId: target.id,
+    composedTrailId: target.id,
   };
 };
 
@@ -645,19 +694,19 @@ const deriveConcurrentBranchLogger = (
 ) =>
   ctx.logger?.child?.({
     branchIndex,
-    crossedTrailId: target.id,
+    composedTrailId: target.id,
   }) ?? ctx.logger;
 
 /**
- * Build a child context for one concurrent crossing branch.
+ * Build a child context for one concurrent composing branch.
  *
- * Concurrent crossings should not inherit already-resolved resource instances
+ * Concurrent compositions should not inherit already-resolved resource instances
  * from the parent execution scope. Stripping resource IDs from extensions
  * forces each branch to resolve its own scope while still carrying forward
  * request-scoped values like tracing, surface identity, permits, and the
  * shared AbortSignal.
  *
- * `cross`, `fire`, and `resource` are cleared so the child execution can
+ * `compose`, `fire`, and `resource` are cleared so the child execution can
  * rebind them to the branch-local context instead of reusing closures that
  * capture the parent scope.
  */
@@ -672,115 +721,131 @@ const buildConcurrentBranchContext = (
     logger: deriveConcurrentBranchLogger(ctx, target, branchIndex),
   });
 
-const executeResolvedCrossTarget = async (
+const executeResolvedComposeTarget = async (
   target: AnyTrail,
   input: unknown,
   ctx: TrailContext,
   topo: Topo | undefined,
-  forwarded: Omit<ExecuteTrailOptions, 'createContext' | 'validationSchema'>
+  forwarded: ComposeForwardOptions,
+  version?: TrailVersionReference | undefined
 ): Promise<Result<unknown, Error>> =>
   await // eslint-disable-next-line no-use-before-define -- executor closure runs only after executeTrail is defined
-  executeTrail(target, input, {
+  executeTrailInternal(target, input, {
     ...forwarded,
+    composeValidation: true,
     ctx,
     topo,
-    validationSchema: buildCrossValidationSchema(target),
+    ...(version === undefined ? {} : { version }),
+    validationSchema: buildComposeValidationSchema(target),
   });
 
-const executeCrossTarget = async (
+const executeComposeTarget = async (
   trailOrId: AnyTrail | string,
   input: unknown,
   ctx: TrailContext,
   topo: Topo | undefined,
-  forwarded: Omit<ExecuteTrailOptions, 'createContext' | 'validationSchema'>
+  forwarded: ComposeForwardOptions,
+  composeOptions?: ComposeOptions | undefined
 ): Promise<Result<unknown, Error>> => {
-  const target = resolveCrossTarget(trailOrId, topo);
+  const target = resolveComposeTarget(trailOrId, topo);
   if (target.isErr()) {
     return target;
   }
+  if (
+    target.value.version !== undefined &&
+    composeOptions?.version !== undefined
+  ) {
+    return Result.err(
+      new ValidationError(
+        `Trail "${target.value.trail.id}" version was provided both in the id reference and ctx.compose() options`
+      )
+    );
+  }
 
-  return await executeResolvedCrossTarget(
-    target.value,
+  return await executeResolvedComposeTarget(
+    target.value.trail,
     input,
     ctx,
     topo,
-    forwarded
+    forwarded,
+    composeOptions?.version ?? target.value.version
   );
 };
 
-type CrossBatchCall = readonly [AnyTrail | string, unknown];
+type ComposeBatchCall = readonly [AnyTrail | string, unknown];
 
-const executeConcurrentCrossBatchCall = async (
-  call: CrossBatchCall,
+const executeConcurrentComposeBatchCall = async (
+  call: ComposeBatchCall,
   branchIndex: number,
   ctx: TrailContext,
   topo: Topo | undefined,
-  forwarded: Omit<ExecuteTrailOptions, 'createContext' | 'validationSchema'>
+  forwarded: ComposeForwardOptions
 ): Promise<Result<unknown, Error>> => {
   const [trailOrId, batchInput] = call;
-  const target = resolveCrossTarget(trailOrId, topo);
+  const target = resolveComposeTarget(trailOrId, topo);
   if (target.isErr()) {
     return target;
   }
 
-  return await executeResolvedCrossTarget(
-    target.value,
+  return await executeResolvedComposeTarget(
+    target.value.trail,
     batchInput,
-    buildConcurrentBranchContext(ctx, target.value, topo, branchIndex),
+    buildConcurrentBranchContext(ctx, target.value.trail, topo, branchIndex),
     topo,
-    forwarded
+    forwarded,
+    target.value.version
   );
 };
 
-const executeUnlimitedCrossBatch = async (
-  calls: readonly CrossBatchCall[],
+const executeUnlimitedComposeBatch = async (
+  calls: readonly ComposeBatchCall[],
   ctx: TrailContext,
   topo: Topo | undefined,
-  forwarded: Omit<ExecuteTrailOptions, 'createContext' | 'validationSchema'>
+  forwarded: ComposeForwardOptions
 ): Promise<Result<unknown, Error>[]> =>
   await Promise.all(
     calls.map((call, branchIndex) =>
-      executeConcurrentCrossBatchCall(call, branchIndex, ctx, topo, forwarded)
+      executeConcurrentComposeBatchCall(call, branchIndex, ctx, topo, forwarded)
     )
   );
 
-const createCrossBatchResults = (
-  calls: readonly CrossBatchCall[]
+const createComposeBatchResults = (
+  calls: readonly ComposeBatchCall[]
 ): Result<unknown, Error>[] =>
   Array.from<Result<unknown, Error>>({ length: calls.length });
 
-const executeLimitedCrossBatch = async (
-  calls: readonly CrossBatchCall[],
+const executeLimitedComposeBatch = async (
+  calls: readonly ComposeBatchCall[],
   ctx: TrailContext,
   topo: Topo | undefined,
-  forwarded: Omit<ExecuteTrailOptions, 'createContext' | 'validationSchema'>,
+  forwarded: ComposeForwardOptions,
   limit: number
 ): Promise<Result<unknown, Error>[]> => {
-  const results = createCrossBatchResults(calls);
+  const results = createComposeBatchResults(calls);
   const nextIndex = { value: 0 };
 
   const runWorker = async () => {
     while (true) {
-      const branchIndex = claimNextCrossBatchIndex(nextIndex, calls);
+      const branchIndex = claimNextComposeBatchIndex(nextIndex, calls);
       if (branchIndex === undefined) {
         return;
       }
 
       const call = calls[branchIndex];
       if (call === undefined) {
-        // Defensive: `claimNextCrossBatchIndex` only returns indices within
+        // Defensive: `claimNextComposeBatchIndex` only returns indices within
         // bounds, so this slot should always be populated. If it ever isn't,
         // surface a clear InternalError in place of the missing slot and keep
         // the worker loop running so sibling branches still get processed.
         results[branchIndex] = Result.err(
           new InternalError(
-            `unreachable: concurrent cross batch call missing at index ${branchIndex}`
+            `unreachable: concurrent compose batch call missing at index ${branchIndex}`
           )
         );
         continue;
       }
 
-      results[branchIndex] = await executeConcurrentCrossBatchCall(
+      results[branchIndex] = await executeConcurrentComposeBatchCall(
         call,
         branchIndex,
         ctx,
@@ -794,81 +859,85 @@ const executeLimitedCrossBatch = async (
   return results;
 };
 
-const executeCrossBatch = async (
-  calls: readonly CrossBatchCall[],
+const executeComposeBatch = async (
+  calls: readonly ComposeBatchCall[],
   ctx: TrailContext,
   topo: Topo | undefined,
-  forwarded: Omit<ExecuteTrailOptions, 'createContext' | 'validationSchema'>,
-  batchOptions?: CrossBatchOptions
+  forwarded: ComposeForwardOptions,
+  batchOptions?: ComposeBatchOptions
 ): Promise<Result<unknown, Error>[]> => {
   if (calls.length === 0) {
     return [];
   }
 
-  const concurrency = normalizeCrossBatchConcurrency(batchOptions);
+  const concurrency = normalizeComposeBatchConcurrency(batchOptions);
   if (concurrency.isErr()) {
-    return createCrossBatchValidationResults(calls, concurrency.error);
+    return createComposeBatchValidationResults(calls, concurrency.error);
   }
 
   const limit = concurrency.value ?? calls.length;
   return limit >= calls.length
-    ? await executeUnlimitedCrossBatch(calls, ctx, topo, forwarded)
-    : await executeLimitedCrossBatch(calls, ctx, topo, forwarded, limit);
+    ? await executeUnlimitedComposeBatch(calls, ctx, topo, forwarded)
+    : await executeLimitedComposeBatch(calls, ctx, topo, forwarded, limit);
 };
 
-const bindCrossToCtx = (
+const bindComposeToCtx = (
   ctx: TrailContext,
   topo: Topo | undefined,
-  options: ExecuteTrailOptions | undefined
+  options: ExecuteTrailInternalOptions | undefined
 ): TrailContext => {
-  if (ctx.cross !== undefined) {
+  if (ctx.compose !== undefined) {
     return ctx;
   }
 
   const {
     createContext: _omit,
+    composeValidation: _omitComposeValidation,
     validationSchema: _omitSchema,
+    version: _omitVersion,
     ...forwarded
   } = options ?? {};
-  const cross = (async (
+  const compose = (async (
     trailOrCalls:
       | AnyTrail
       | string
       | readonly (readonly [AnyTrail | string, unknown])[],
-    inputOrOptions?: CrossBatchOptions | unknown
+    inputOrOptions?: unknown,
+    singleOptions?: ComposeOptions
   ) => {
     if (Array.isArray(trailOrCalls)) {
-      return await executeCrossBatch(
+      return await executeComposeBatch(
         trailOrCalls,
         ctx,
         topo,
         forwarded,
-        inputOrOptions as CrossBatchOptions | undefined
+        inputOrOptions as ComposeBatchOptions | undefined
       );
     }
 
-    return await executeCrossTarget(
+    return await executeComposeTarget(
       trailOrCalls as AnyTrail | string,
       inputOrOptions,
       ctx,
       topo,
-      forwarded
+      forwarded,
+      singleOptions
     );
-  }) as CrossFn;
+  }) as ComposeFn;
 
   return {
     ...ctx,
-    cross,
+    compose,
   };
 };
 
 const bindFireToCtx = (
   ctx: TrailContext,
   topo: Topo | undefined,
-  options: ExecuteTrailOptions | undefined,
+  options: ExecuteTrailInternalOptions | undefined,
   producerTrailId?: string | undefined
 ): TrailContext => {
-  // Symmetric with bindCrossToCtx: a caller-supplied ctx.fire (e.g. test
+  // Symmetric with bindComposeToCtx: a caller-supplied ctx.fire (e.g. test
   // helper, scenario harness, or runtime intercepting signal fan-out) is
   // preserved as-is. Without this guard, passing both `topo: app` and a
   // custom `ctx.fire` would silently clobber the injected mock with the
@@ -886,10 +955,12 @@ const bindFireToCtx = (
   // already-resolved ctx via `consumerCtx`, and re-running the factory would
   // clobber that.
   // Strip createContext (consumers inherit resolved ctx) and validationSchema
-  // (consumers validate against their own schema, not the producer's cross schema).
+  // (consumers validate against their own schema, not the producer's compose schema).
   const {
     createContext: _omit,
+    composeValidation: _omitComposeValidation,
     validationSchema: _omitSchema,
+    version: _omitVersion,
     ...forwarded
   } = options ?? {};
   const trackedCtx = withFireDispatchTracking(ctx);
@@ -898,7 +969,7 @@ const bindFireToCtx = (
     trackedCtx,
     (consumer, input, consumerCtx) =>
       // eslint-disable-next-line no-use-before-define -- executor closure runs only after executeTrail is defined
-      executeTrail(consumer, input, {
+      executeTrailInternal(consumer, input, {
         ...forwarded,
         ctx: consumerCtx,
         topo,
@@ -908,20 +979,20 @@ const bindFireToCtx = (
   return { ...trackedCtx, fire };
 };
 
-const bindCrossAtLayerBoundary =
+const bindComposeAtLayerBoundary =
   <I, O>(
     implementation: Implementation<I, O>,
     topo: Topo | undefined,
-    options: ExecuteTrailOptions | undefined
+    options: ExecuteTrailInternalOptions | undefined
   ): Implementation<I, O> =>
   (input, ctx) =>
-    implementation(input, bindCrossToCtx(ctx, topo, options));
+    implementation(input, bindComposeToCtx(ctx, topo, options));
 
 const bindFireAtLayerBoundary = <I, O>(
   implementation: Implementation<I, O>,
   trail: AnyTrail,
   topo: Topo | undefined,
-  options: ExecuteTrailOptions | undefined
+  options: ExecuteTrailInternalOptions | undefined
 ): Implementation<I, O> => {
   if (topo === undefined) {
     return implementation;
@@ -948,7 +1019,7 @@ const findMatchingDetour = (
 ): Detour<any, any, TrailsError> | undefined =>
   detours.find((d) => error instanceof d.on);
 
-/** Execute a single detour recovery attempt, routing through ctx.trace when available. */
+/** Execute a single detour recovery attempt, tracing through ctx.trace when available. */
 const executeDetourAttempt = async (
   /* oxlint-disable-next-line no-explicit-any -- existential detour from AnyTrail */
   detour: Detour<any, any, TrailsError>,
@@ -1107,13 +1178,13 @@ const prepareRunImpl = (
   ctx: TrailContext,
   layers: readonly Layer[],
   topo: Topo | undefined,
-  options: ExecuteTrailOptions | undefined
+  options: ExecuteTrailInternalOptions | undefined
 ): {
   readonly ctxWithIntrinsics: TrailContext;
   readonly impl: Implementation<unknown, unknown>;
 } => {
   const ctxWithIntrinsics = bindFireToCtx(
-    bindCrossToCtx(ctx, topo, options),
+    bindComposeToCtx(ctx, topo, options),
     topo,
     options,
     trail.id
@@ -1121,7 +1192,7 @@ const prepareRunImpl = (
   // Detour loop wraps the blaze (inside layer stack, closest to blaze)
   let impl = wrapWithDetours(
     bindFireAtLayerBoundary(
-      bindCrossAtLayerBoundary(
+      bindComposeAtLayerBoundary(
         trail.blaze as Implementation<unknown, unknown>,
         topo,
         options
@@ -1137,7 +1208,7 @@ const prepareRunImpl = (
     const layer = layers[i];
     if (layer) {
       impl = bindFireAtLayerBoundary(
-        bindCrossAtLayerBoundary(
+        bindComposeAtLayerBoundary(
           layer.wrap(trail, impl as never) as Implementation<unknown, unknown>,
           topo,
           options
@@ -1161,7 +1232,7 @@ const runImplWithoutTracing = async (
   ctx: TrailContext,
   layers: readonly Layer[],
   topo: Topo | undefined,
-  options: ExecuteTrailOptions | undefined
+  options: ExecuteTrailInternalOptions | undefined
 ): Promise<Result<unknown, Error>> => {
   const prepared = prepareRunImpl(
     trail,
@@ -1183,7 +1254,7 @@ const runTrailWithTracing = async (
   ctx: TrailContext,
   layers: readonly Layer[],
   topo: Topo | undefined,
-  options: ExecuteTrailOptions | undefined,
+  options: ExecuteTrailInternalOptions | undefined,
   sink: ReturnType<typeof getTraceSink>
 ): Promise<Result<unknown, Error>> => {
   const { record, tracedCtx } = buildTracedContext(trail, ctx, sink);
@@ -1216,7 +1287,7 @@ const runTrail = async (
   ctx: TrailContext,
   layers: readonly Layer[],
   topo: Topo | undefined,
-  options: ExecuteTrailOptions | undefined
+  options: ExecuteTrailInternalOptions | undefined
 ): Promise<Result<unknown, Error>> => {
   const sink = topo?.observe?.trace ?? getTraceSink();
   return isTracingDisabled(sink)
@@ -1238,7 +1309,7 @@ const runTrail = async (
  */
 const composeAttachedLayers = (
   trail: AnyTrail,
-  options: ExecuteTrailOptions | undefined
+  options: ExecuteTrailInternalOptions | undefined
 ): readonly Layer[] => [
   ...(options?.topoLayers ?? []),
   ...(options?.surfaceLayers ?? []),
@@ -1246,6 +1317,125 @@ const composeAttachedLayers = (
   ...(options?.layers ?? []),
 ];
 
+const stripVersionOption = (
+  options?: ExecuteTrailInternalOptions
+): Omit<ExecuteTrailInternalOptions, 'version'> | undefined => {
+  if (options === undefined) {
+    return undefined;
+  }
+  const { version: _version, ...forwarded } = options;
+  return forwarded;
+};
+
+const executeRequestedCurrentTrailVersion = async (
+  trail: AnyTrail,
+  rawInput: unknown,
+  options: ExecuteTrailInternalOptions
+): Promise<Result<unknown, Error>> =>
+  // eslint-disable-next-line no-use-before-define -- recursive dispatch strips version before re-entering the current pipeline
+  await executeTrailInternal(trail, rawInput, stripVersionOption(options));
+
+const executeCurrentTrailForRevision: TrailVersionCurrentExecutor<
+  ExecuteTrailInternalOptions
+> = async (trail, input, internalOptions) => {
+  const {
+    validationSchema: _validationSchema,
+    version: _version,
+    ...forwarded
+  } = internalOptions ?? {};
+  // eslint-disable-next-line no-use-before-define -- revision runtime calls back into current execution after options are normalized
+  return await executeTrailInternal(trail, input, forwarded);
+};
+
+const createForkTrailVersion = (
+  trail: AnyTrail,
+  entry: TrailVersionForkEntry
+): AnyTrail => {
+  const {
+    blaze: _blaze,
+    composeInput: _composeInput,
+    composes: _composes,
+    detours: _detours,
+    input: _input,
+    output: _output,
+    resources: _resources,
+    version: _version,
+    versions: _versions,
+    ...base
+  } = trail;
+
+  return Object.freeze({
+    ...base,
+    blaze: entry.blaze,
+    composes: Object.freeze([...(entry.composes ?? [])]),
+    detours: Object.freeze([...(entry.detours ?? [])]),
+    ...(entry.composeInput === undefined
+      ? {}
+      : { composeInput: entry.composeInput }),
+    input: entry.input,
+    output: entry.output,
+    resources: Object.freeze([...(entry.resources ?? [])]),
+  }) as AnyTrail;
+};
+
+const executeRequestedForkTrailVersion = async (
+  trail: AnyTrail,
+  entry: TrailVersionForkEntry,
+  rawInput: unknown,
+  options: ExecuteTrailInternalOptions
+): Promise<Result<unknown, Error>> => {
+  const forkTrail = createForkTrailVersion(trail, entry);
+  const validationSchema = options.composeValidation
+    ? buildComposeValidationSchema(forkTrail)
+    : options.validationSchema;
+
+  // eslint-disable-next-line no-use-before-define -- recursive dispatch strips version before re-entering the fork pipeline
+  return await executeTrailInternal(forkTrail, rawInput, {
+    ...stripVersionOption(options),
+    validationSchema,
+  });
+};
+
+const executeRequestedTrailVersion = async (
+  trail: AnyTrail,
+  rawInput: unknown,
+  options: ExecuteTrailInternalOptions
+): Promise<Result<unknown, Error>> => {
+  const reference = options.version;
+  if (reference === undefined) {
+    return Result.err(
+      new InternalError(
+        'unreachable: executeRequestedTrailVersion without reference'
+      )
+    );
+  }
+
+  const resolved = resolveTrailVersion(trail, reference);
+  if (resolved.isErr()) {
+    return Result.err(resolved.error);
+  }
+
+  if (resolved.value.current) {
+    return await executeRequestedCurrentTrailVersion(trail, rawInput, options);
+  }
+
+  return resolved.value.kind === 'revision'
+    ? await executeTrailRevision(
+        trail,
+        resolved.value.version,
+        resolved.value.entry,
+        rawInput,
+        options,
+        executeCurrentTrailForRevision
+      )
+    : await executeRequestedForkTrailVersion(
+        trail,
+        resolved.value.entry,
+        rawInput,
+        options
+      );
+};
+
 const isLayerInputMap = (
   value: unknown
 ): value is Readonly<Record<string, unknown>> =>
@@ -1330,12 +1520,16 @@ const validateContextLayerInputs = (
  * The function never throws -- unexpected exceptions are caught and
  * returned as `Result.err(InternalError)`.
  */
-export const executeTrail = async (
+const executeTrailInternal = async (
   trail: AnyTrail,
   rawInput: unknown,
-  options?: ExecuteTrailOptions
+  options?: ExecuteTrailInternalOptions
 ): Promise<Result<unknown, Error>> => {
   try {
+    if (options?.version !== undefined) {
+      return await executeRequestedTrailVersion(trail, rawInput, options);
+    }
+
     const validated = validateInput(
       options?.validationSchema ?? trail.input,
       rawInput
@@ -1374,3 +1568,10 @@ export const executeTrail = async (
     return Result.err(new InternalError(message));
   }
 };
+
+export const executeTrail = async (
+  trail: AnyTrail,
+  rawInput: unknown,
+  options?: ExecuteTrailOptions
+): Promise<Result<unknown, Error>> =>
+  await executeTrailInternal(trail, rawInput, options);