@ontrails/core 0.2.0

package/src/execute.ts

@@ -0,0 +1,1577 @@
+/**
+ * Centralized trail execution pipeline.
+ *
+ * Validates input, builds context, composes layers, and runs the
+ * implementation. Surfaces (CLI, MCP, HTTP) delegate here instead
+ * of reimplementing the pipeline.
+ */
+
+import type { z } from 'zod';
+
+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,
+  getActivationProvenance,
+} from './activation-provenance.js';
+import {
+  createFireFn,
+  isFrameworkFireFn,
+  waitForPendingFireDispatches,
+  withFireDispatchTracking,
+} from './fire.js';
+import type { BasePermit } from './permits.js';
+import type {
+  ComposeBatchOptions,
+  ComposeOptions,
+  ComposeFn,
+  Detour,
+  Implementation,
+  TraceFn,
+  TrailContext,
+  TrailContextInit,
+} from './types.js';
+
+import { createTrailContext, passthroughTrace } from './context.js';
+import { buildComposeValidationSchema } from './compose-schema.js';
+import {
+  CancelledError,
+  InternalError,
+  NotFoundError,
+  PermitError,
+  RetryExhaustedError,
+  TrailsError,
+  ValidationError,
+} from './errors.js';
+import {
+  claimNextComposeBatchIndex,
+  createComposeBatchValidationResults,
+  normalizeComposeBatchConcurrency,
+} from './compose-batch.js';
+import { forkCtx } from './internal/fork-ctx.js';
+import {
+  TRACE_CONTEXT_KEY,
+  completeRecord,
+  createSpanRecord,
+  createTraceRecord,
+  getTraceSink,
+  isTracingDisabled,
+  writeToSink,
+} from './tracing.js';
+import {
+  OBSERVE_LOGGER_CONTEXT_KEY,
+  OBSERVE_LOGGER_METADATA_KEY,
+  createObserveLogger,
+} from './observe.js';
+import { Result } from './result.js';
+import { DETOUR_MAX_ATTEMPTS_CAP } from './detours.js';
+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
+// ---------------------------------------------------------------------------
+
+/** Options for executeTrail. */
+export interface ExecuteTrailOptions {
+  /** Partial context overrides merged on top of the base context. */
+  readonly ctx?: Partial<TrailContextInit> | undefined;
+  /** AbortSignal override (takes final precedence over ctx and factory). */
+  readonly abortSignal?: AbortSignal | undefined;
+  /**
+   * Typed layers supplied for this execution.
+   *
+   * Layers compose around the implementation. Layers without `input`
+   * schemas are surface-invisible wrappers for concerns such as tenant guards,
+   * rate limiting, circuit breaking, or custom audit logging.
+   */
+  readonly layers?: readonly Layer[] | undefined;
+  /**
+   * Typed layers attached at surface scope.
+   *
+   * Surfaces (CLI, MCP, HTTP) forward their `layers` option here so they
+   * compose around every trail dispatched through that surface. The final
+   * composition order is `topo → surface → trail → implementation` (outermost-first).
+   */
+  readonly surfaceLayers?: readonly Layer[] | undefined;
+  /**
+   * Typed layers attached at topo scope.
+   *
+   * The CLI/MCP/HTTP surfaces typically forward `topo.layers` here so the
+   * topo's declared layers wrap every trail invocation. The final
+   * composition order is `topo → surface → trail → implementation` (outermost-first).
+   */
+  readonly topoLayers?: readonly Layer[] | undefined;
+  /** Factory that produces a base TrailContext (takes precedence over defaults). */
+  readonly createContext?:
+    | (() => TrailContextInit | Promise<TrailContextInit>)
+    | undefined;
+  /** Explicit resource instance overrides keyed by resource ID. */
+  readonly resources?: ResourceOverrideMap | undefined;
+  /** Config values for resources that declare a `config` schema, keyed by resource ID. */
+  readonly configValues?:
+    | Readonly<Record<string, Record<string, unknown>>>
+    | undefined;
+  /** Topo used for signal-driven activation; required for `ctx.fire()` to work. */
+  readonly topo?: Topo | undefined;
+  /**
+   * Whether this invocation is a dry run.
+   *
+   * Sets `ctx.dryRun` for the trail. Defaults to `false`. The framework
+   * never short-circuits execution on this field — it only carries the
+   * flag through. Trails that read `ctx.dryRun` decide what dry-run means.
+   */
+  readonly dryRun?: boolean | undefined;
+  /**
+   * Permit to overlay onto `ctx.permit` for this invocation.
+   *
+   * When provided, this overrides any permit supplied via `ctx.permit` on
+   * the partial context overrides or via the `createContext` factory. Leave
+   * unset to inherit the permit from the resolved context (typically
+   * `undefined`). Surfaces parse and validate the permit at their boundary
+   * (e.g. CLI `--permit '<json>'`) before passing it here.
+   */
+  readonly permit?: BasePermit | undefined;
+  /**
+   * Per-layer runtime input keyed by `Layer.name`.
+   *
+   * Surfaces (CLI, MCP, HTTP) parse their native idiom into a per-layer
+   * input object — usually derived from each layer's `input` schema —
+   * and pass it here. The executor merges these into
+   * `ctx.extensions[LAYER_INPUTS_KEY]` so layers can read their own slot
+   * via `ctx.extensions?.[LAYER_INPUTS_KEY]?.[layer.name]`.
+   *
+   * @see TRL-473 for the CLI rendering 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 derived
+   * 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.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 compose execution path; not part of the public API.
+   *
+   * @internal
+   */
+  readonly validationSchema?: z.ZodType | undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Context resolution
+// ---------------------------------------------------------------------------
+
+const applyContextOverrides = (
+  base: TrailContextInit,
+  options?: ExecuteTrailInternalOptions
+): TrailContextInit => {
+  const withOverrides = options?.ctx
+    ? {
+        ...base,
+        ...options.ctx,
+        extensions: { ...base.extensions, ...options.ctx.extensions },
+      }
+    : base;
+
+  const withAbort = options?.abortSignal
+    ? { ...withOverrides, abortSignal: options.abortSignal }
+    : withOverrides;
+
+  const withDryRun =
+    options?.dryRun === undefined
+      ? withAbort
+      : { ...withAbort, dryRun: options.dryRun };
+
+  const withPermit =
+    options?.permit === undefined
+      ? withDryRun
+      : { ...withDryRun, permit: options.permit };
+
+  if (options?.layerInputs === undefined) {
+    return withPermit;
+  }
+  // Merge per-layer inputs onto any inherited LAYER_INPUTS_KEY slot so
+  // composed/forked contexts can preserve outer-surface metadata.
+  const inheritedExtensions = withPermit.extensions ?? {};
+  const inheritedLayerInputs = (inheritedExtensions[LAYER_INPUTS_KEY] ?? {}) as
+    | Readonly<Record<string, unknown>>
+    | Record<string, unknown>;
+  return {
+    ...withPermit,
+    extensions: {
+      ...inheritedExtensions,
+      [LAYER_INPUTS_KEY]: {
+        ...inheritedLayerInputs,
+        ...options.layerInputs,
+      },
+    },
+  };
+};
+
+const bindResourceLookup = (
+  resolved: TrailContextInit,
+  options?: ExecuteTrailInternalOptions
+): TrailContext => {
+  if (
+    options?.ctx?.extensions === undefined &&
+    resolved.resource !== undefined
+  ) {
+    return resolved as TrailContext;
+  }
+
+  const bound = { ...resolved } as MutableTrailContext;
+  const lookup = createResourceLookup(() => bound);
+  bound.resource = lookup;
+  return bound;
+};
+
+/**
+ * Build a TrailContext from options.
+ *
+ * Resolution order:
+ * 1. Factory (`createContext`) or `createTrailContext()` defaults.
+ * 2. Partial `ctx` overrides merged on top.
+ * 3. `abortSignal` override takes final precedence.
+ * 4. `dryRun` option takes final precedence (defaults to `false` via
+ *    `createTrailContext` when neither option nor `ctx.dryRun` is provided).
+ * 5. `permit` option takes final precedence over any inherited permit when
+ *    provided; leaving it unset preserves whatever the resolved context
+ *    already carries.
+ */
+const resolveContext = async (
+  options?: ExecuteTrailInternalOptions
+): Promise<TrailContext> => {
+  const seed = options?.createContext
+    ? await options.createContext()
+    : undefined;
+  const base = createTrailContext(seed);
+  const resolved = applyContextOverrides(base, options);
+  return bindResourceLookup(resolved, options);
+};
+
+const readObserveLoggerMetadata = (
+  ctx: TrailContext
+): Record<string, unknown> => {
+  const value = ctx.extensions?.[OBSERVE_LOGGER_METADATA_KEY];
+  return value !== null && typeof value === 'object'
+    ? (value as Record<string, unknown>)
+    : {};
+};
+
+const applyTopoObserveContext = (
+  trail: AnyTrail,
+  ctx: TrailContext,
+  topo: Topo | undefined
+): TrailContext => {
+  if (topo?.observe?.log === undefined) {
+    return ctx;
+  }
+  const hasTopoObserveLogger =
+    ctx.extensions?.[OBSERVE_LOGGER_CONTEXT_KEY] === true;
+  if (ctx.logger !== undefined && !hasTopoObserveLogger) {
+    return ctx;
+  }
+  const { log } = topo.observe;
+  // Accumulated metadata (e.g. signal fan-out fields) takes precedence over
+  // the previous observe logger's `topo`/`trailId` values, but the new trail's
+  // identity wins so log records keep pointing at the trail currently running.
+  const accumulated = readObserveLoggerMetadata(ctx);
+  return {
+    ...ctx,
+    extensions: {
+      ...ctx.extensions,
+      [OBSERVE_LOGGER_CONTEXT_KEY]: true,
+    },
+    logger: createObserveLogger(log, trail.id, {
+      ...accumulated,
+      topo: topo.name,
+      trailId: trail.id,
+    }),
+  };
+};
+
+const findMissingScopes = (
+  required: readonly string[],
+  held: readonly string[]
+): readonly string[] => required.filter((scope) => !held.includes(scope));
+
+const enforcePermitRequirement = (
+  trail: AnyTrail,
+  ctx: TrailContext
+): Result<TrailContext, Error> => {
+  const requirement = trail.permit;
+  if (requirement === undefined || requirement === 'public') {
+    return Result.ok(ctx);
+  }
+
+  if (ctx.permit === undefined) {
+    return Result.err(
+      new PermitError('No permit provided', {
+        context: { required: requirement.scopes, trailId: trail.id },
+      })
+    );
+  }
+
+  const missing = findMissingScopes(requirement.scopes, ctx.permit.scopes);
+  return missing.length === 0
+    ? Result.ok(ctx)
+    : Result.err(
+        new PermitError(`Missing scopes: ${missing.join(', ')}`, {
+          context: { missing, required: requirement.scopes, trailId: trail.id },
+        })
+      );
+};
+
+const prepareContext = async (
+  trail: AnyTrail,
+  options?: ExecuteTrailInternalOptions
+): Promise<
+  Result<
+    { readonly ctx: TrailContext; readonly releaseResources: () => void },
+    Error
+  >
+> => {
+  const baseCtx = applyTopoObserveContext(
+    trail,
+    await resolveContext(options),
+    options?.topo
+  );
+  const permitted = enforcePermitRequirement(trail, baseCtx);
+  if (permitted.isErr()) {
+    return permitted;
+  }
+
+  const resources = await createResources(
+    trail,
+    permitted.value,
+    options?.resources,
+    options?.configValues
+  );
+  return resources.isErr()
+    ? Result.err(resources.error)
+    : Result.ok({
+        ctx: resources.value.ctx,
+        releaseResources: resources.value.release,
+      });
+};
+
+// ---------------------------------------------------------------------------
+// Intrinsic tracing
+// ---------------------------------------------------------------------------
+
+/** Derive the status + error category fields from a trail result. */
+const deriveResultErrorCategory = (error: Error): string => {
+  if (error instanceof TrailsError) {
+    return error.category;
+  }
+  return 'internal';
+};
+
+const deriveOutcome = (
+  result: Result<unknown, Error>
+): {
+  readonly status: TraceRecord['status'];
+  readonly errorCategory: string | undefined;
+} =>
+  result.match<{
+    readonly status: TraceRecord['status'];
+    readonly errorCategory: string | undefined;
+  }>({
+    err: (error) => ({
+      errorCategory: deriveResultErrorCategory(error),
+      status: error instanceof CancelledError ? 'cancelled' : 'err',
+    }),
+    ok: () => ({ errorCategory: undefined, status: 'ok' }),
+  });
+
+/**
+ * Best-effort error category for a thrown (not Result.err) value.
+ *
+ * Unknown/non-Error throws normalize to `'internal'` so the trace record
+ * always carries a category when the trail unexpectedly throws.
+ */
+const categorizeSpanError = (error: unknown): string => {
+  if (error instanceof TrailsError) {
+    return error.category;
+  }
+  return 'internal';
+};
+
+/** Extract the permit identity fields for the trace record. */
+const extractPermit = (
+  ctx: TrailContext
+): { readonly id: string; readonly tenantId?: string } | undefined => {
+  if (ctx.permit === undefined) {
+    return undefined;
+  }
+  const tenantId =
+    'tenantId' in ctx.permit
+      ? (ctx.permit as { tenantId?: string }).tenantId
+      : undefined;
+  return tenantId === undefined
+    ? { id: ctx.permit.id }
+    : { id: ctx.permit.id, tenantId };
+};
+
+/**
+ * Build a `ctx.trace` function bound to a parent trace context.
+ *
+ * Each call creates a child span under the parent, times the callback,
+ * records success/failure with the appropriate error category, writes the
+ * completed span to the sink, and returns the callback result. Errors
+ * thrown by the callback are recorded and then rethrown.
+ *
+ * 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 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.
+ */
+const buildTraceFn =
+  (parent: TraceContext, sink: ReturnType<typeof getTraceSink>): TraceFn =>
+  async <T>(label: string, fn: () => T | Promise<T>): Promise<T> => {
+    const record = createSpanRecord(parent, label);
+    try {
+      const value = await fn();
+      await writeToSink(sink, completeRecord(record, 'ok'));
+      return value;
+    } catch (error: unknown) {
+      const errorCategory = categorizeSpanError(error);
+      const status: TraceRecord['status'] =
+        error instanceof CancelledError ? 'cancelled' : 'err';
+      await writeToSink(sink, completeRecord(record, status, errorCategory));
+      throw error;
+    }
+  };
+
+/** Build the root trace record + trace-enriched context for a trail run. */
+const buildTracedContext = (
+  trail: AnyTrail,
+  ctx: TrailContext,
+  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.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
+    | TraceContext
+    | undefined;
+
+  const record = createTraceRecord({
+    intent: trail.intent,
+    parentId: parent?.spanId,
+    permit: extractPermit(ctx),
+    rootId: parent?.rootId,
+    sampled: parent?.sampled ?? true,
+    surface: ctx.extensions?.[SURFACE_KEY] as TraceRecord['surface'],
+    traceId: parent?.traceId,
+    trailId: trail.id,
+  });
+  const activation = getActivationProvenance(ctx);
+  const recordWithAttrs: TraceRecord =
+    activation === undefined
+      ? record
+      : {
+          ...record,
+          attrs: buildActivationProvenanceTraceAttrs(activation),
+        };
+
+  // Root trace context for this trail's span. When inheriting a parent, the
+  // traceId/rootId carry forward and only spanId advances to the new record.
+  const rootTrace: TraceContext = {
+    rootId: parent?.rootId ?? record.id,
+    sampled: recordWithAttrs.sampled ?? true,
+    spanId: recordWithAttrs.id,
+    traceId: recordWithAttrs.traceId,
+  };
+
+  const tracedCtx: TrailContext = {
+    ...ctx,
+    extensions: {
+      ...ctx.extensions,
+      [TRACE_CONTEXT_KEY]: rootTrace,
+    },
+    trace: buildTraceFn(rootTrace, sink),
+  };
+
+  return { record: recordWithAttrs, tracedCtx };
+};
+
+const buildUntracedContext = (ctx: TrailContext): TrailContext => {
+  const { [TRACE_CONTEXT_KEY]: _traceContext, ...extensions } =
+    ctx.extensions ?? {};
+  const hasExtensions = Object.keys(extensions).length > 0;
+
+  return {
+    ...ctx,
+    extensions: hasExtensions ? extensions : undefined,
+    trace: passthroughTrace,
+  };
+};
+
+/** Run the composed implementation and write the root record on any outcome. */
+const runImplWithRootRecord = async (
+  impl: Implementation<unknown, unknown>,
+  input: unknown,
+  tracedCtx: TrailContext,
+  record: TraceRecord,
+  sink: ReturnType<typeof getTraceSink>
+): Promise<Result<unknown, Error>> => {
+  try {
+    const result = await impl(input, tracedCtx);
+    await waitForPendingFireDispatches(tracedCtx);
+    const outcome = deriveOutcome(result);
+    await writeToSink(
+      sink,
+      completeRecord(record, outcome.status, outcome.errorCategory)
+    );
+    return result;
+  } catch (error: unknown) {
+    await waitForPendingFireDispatches(tracedCtx);
+    // Normalize unexpected throws so the root record still reflects the error
+    // outcome. The outer executeTrail try/catch converts the thrown value into
+    // a Result.err(InternalError) for the caller.
+    const status: TraceRecord['status'] =
+      error instanceof CancelledError ? 'cancelled' : 'err';
+    const errorCategory = categorizeSpanError(error);
+    await writeToSink(sink, completeRecord(record, status, errorCategory));
+    throw error;
+  }
+};
+
+interface ResolvedComposeTarget {
+  readonly trail: AnyTrail;
+  readonly version?: TrailVersionReference | undefined;
+}
+
+const resolveComposeTarget = (
+  trailOrId: AnyTrail | string,
+  topo: Topo | undefined
+): Result<ResolvedComposeTarget, Error> => {
+  if (typeof trailOrId !== 'string') {
+    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 composed without topo access`
+      )
+    );
+  }
+
+  const target = topo.get(parsed.value.id);
+  return target
+    ? Result.ok({ trail: target, version: parsed.value.version })
+    : Result.err(
+        new NotFoundError(
+          `Trail "${trailOrId}" not found in topo "${topo.name}"`
+        )
+      );
+};
+
+const collectConcurrentBranchResourceIds = (
+  target: AnyTrail,
+  topo: Topo | undefined
+): Set<string> =>
+  new Set(
+    topo?.resourceIds() ?? target.resources.map((resource) => resource.id)
+  );
+
+const stripInheritedResourceExtensions = (
+  ctx: TrailContext,
+  target: AnyTrail,
+  topo: Topo | undefined
+): Record<string, unknown> => {
+  const resourceIds = collectConcurrentBranchResourceIds(target, topo);
+  const entries = Object.entries(ctx.extensions ?? {}).filter(
+    ([key]) => !resourceIds.has(key)
+  );
+  return Object.fromEntries(entries);
+};
+
+const deriveConcurrentBranchObserveMetadata = (
+  ctx: TrailContext,
+  target: AnyTrail,
+  branchIndex: number
+): Record<string, unknown> | undefined => {
+  // Only carry observe metadata forward when the parent ctx is using a
+  // topo-managed observe logger. Otherwise we'd attach branch fields to
+  // caller-supplied loggers that didn't opt into the structured contract.
+  if (ctx.extensions?.[OBSERVE_LOGGER_CONTEXT_KEY] !== true) {
+    return;
+  }
+  return {
+    ...readObserveLoggerMetadata(ctx),
+    branchIndex,
+    composedTrailId: target.id,
+  };
+};
+
+const buildConcurrentBranchExtensions = (
+  ctx: TrailContext,
+  target: AnyTrail,
+  topo: Topo | undefined,
+  branchIndex: number
+): Record<string, unknown> => {
+  const stripped = stripInheritedResourceExtensions(ctx, target, topo);
+  const observeMetadata = deriveConcurrentBranchObserveMetadata(
+    ctx,
+    target,
+    branchIndex
+  );
+  if (observeMetadata === undefined) {
+    return stripped;
+  }
+  return {
+    ...stripped,
+    [OBSERVE_LOGGER_METADATA_KEY]: observeMetadata,
+  };
+};
+
+const deriveConcurrentBranchLogger = (
+  ctx: TrailContext,
+  target: AnyTrail,
+  branchIndex: number
+) =>
+  ctx.logger?.child?.({
+    branchIndex,
+    composedTrailId: target.id,
+  }) ?? ctx.logger;
+
+/**
+ * Build a child context for one concurrent composing branch.
+ *
+ * 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.
+ *
+ * `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.
+ */
+const buildConcurrentBranchContext = (
+  ctx: TrailContext,
+  target: AnyTrail,
+  topo: Topo | undefined,
+  branchIndex: number
+): TrailContext =>
+  forkCtx(ctx, {
+    extensions: buildConcurrentBranchExtensions(ctx, target, topo, branchIndex),
+    logger: deriveConcurrentBranchLogger(ctx, target, branchIndex),
+  });
+
+const executeResolvedComposeTarget = async (
+  target: AnyTrail,
+  input: unknown,
+  ctx: TrailContext,
+  topo: Topo | undefined,
+  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
+  executeTrailInternal(target, input, {
+    ...forwarded,
+    composeValidation: true,
+    ctx,
+    topo,
+    ...(version === undefined ? {} : { version }),
+    validationSchema: buildComposeValidationSchema(target),
+  });
+
+const executeComposeTarget = async (
+  trailOrId: AnyTrail | string,
+  input: unknown,
+  ctx: TrailContext,
+  topo: Topo | undefined,
+  forwarded: ComposeForwardOptions,
+  composeOptions?: ComposeOptions | undefined
+): Promise<Result<unknown, Error>> => {
+  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 executeResolvedComposeTarget(
+    target.value.trail,
+    input,
+    ctx,
+    topo,
+    forwarded,
+    composeOptions?.version ?? target.value.version
+  );
+};
+
+type ComposeBatchCall = readonly [AnyTrail | string, unknown];
+
+const executeConcurrentComposeBatchCall = async (
+  call: ComposeBatchCall,
+  branchIndex: number,
+  ctx: TrailContext,
+  topo: Topo | undefined,
+  forwarded: ComposeForwardOptions
+): Promise<Result<unknown, Error>> => {
+  const [trailOrId, batchInput] = call;
+  const target = resolveComposeTarget(trailOrId, topo);
+  if (target.isErr()) {
+    return target;
+  }
+
+  return await executeResolvedComposeTarget(
+    target.value.trail,
+    batchInput,
+    buildConcurrentBranchContext(ctx, target.value.trail, topo, branchIndex),
+    topo,
+    forwarded,
+    target.value.version
+  );
+};
+
+const executeUnlimitedComposeBatch = async (
+  calls: readonly ComposeBatchCall[],
+  ctx: TrailContext,
+  topo: Topo | undefined,
+  forwarded: ComposeForwardOptions
+): Promise<Result<unknown, Error>[]> =>
+  await Promise.all(
+    calls.map((call, branchIndex) =>
+      executeConcurrentComposeBatchCall(call, branchIndex, ctx, topo, forwarded)
+    )
+  );
+
+const createComposeBatchResults = (
+  calls: readonly ComposeBatchCall[]
+): Result<unknown, Error>[] =>
+  Array.from<Result<unknown, Error>>({ length: calls.length });
+
+const executeLimitedComposeBatch = async (
+  calls: readonly ComposeBatchCall[],
+  ctx: TrailContext,
+  topo: Topo | undefined,
+  forwarded: ComposeForwardOptions,
+  limit: number
+): Promise<Result<unknown, Error>[]> => {
+  const results = createComposeBatchResults(calls);
+  const nextIndex = { value: 0 };
+
+  const runWorker = async () => {
+    while (true) {
+      const branchIndex = claimNextComposeBatchIndex(nextIndex, calls);
+      if (branchIndex === undefined) {
+        return;
+      }
+
+      const call = calls[branchIndex];
+      if (call === undefined) {
+        // 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 compose batch call missing at index ${branchIndex}`
+          )
+        );
+        continue;
+      }
+
+      results[branchIndex] = await executeConcurrentComposeBatchCall(
+        call,
+        branchIndex,
+        ctx,
+        topo,
+        forwarded
+      );
+    }
+  };
+
+  await Promise.all(Array.from({ length: limit }, runWorker));
+  return results;
+};
+
+const executeComposeBatch = async (
+  calls: readonly ComposeBatchCall[],
+  ctx: TrailContext,
+  topo: Topo | undefined,
+  forwarded: ComposeForwardOptions,
+  batchOptions?: ComposeBatchOptions
+): Promise<Result<unknown, Error>[]> => {
+  if (calls.length === 0) {
+    return [];
+  }
+
+  const concurrency = normalizeComposeBatchConcurrency(batchOptions);
+  if (concurrency.isErr()) {
+    return createComposeBatchValidationResults(calls, concurrency.error);
+  }
+
+  const limit = concurrency.value ?? calls.length;
+  return limit >= calls.length
+    ? await executeUnlimitedComposeBatch(calls, ctx, topo, forwarded)
+    : await executeLimitedComposeBatch(calls, ctx, topo, forwarded, limit);
+};
+
+const bindComposeToCtx = (
+  ctx: TrailContext,
+  topo: Topo | undefined,
+  options: ExecuteTrailInternalOptions | undefined
+): TrailContext => {
+  if (ctx.compose !== undefined) {
+    return ctx;
+  }
+
+  const {
+    createContext: _omit,
+    composeValidation: _omitComposeValidation,
+    validationSchema: _omitSchema,
+    version: _omitVersion,
+    ...forwarded
+  } = options ?? {};
+  const compose = (async (
+    trailOrCalls:
+      | AnyTrail
+      | string
+      | readonly (readonly [AnyTrail | string, unknown])[],
+    inputOrOptions?: unknown,
+    singleOptions?: ComposeOptions
+  ) => {
+    if (Array.isArray(trailOrCalls)) {
+      return await executeComposeBatch(
+        trailOrCalls,
+        ctx,
+        topo,
+        forwarded,
+        inputOrOptions as ComposeBatchOptions | undefined
+      );
+    }
+
+    return await executeComposeTarget(
+      trailOrCalls as AnyTrail | string,
+      inputOrOptions,
+      ctx,
+      topo,
+      forwarded,
+      singleOptions
+    );
+  }) as ComposeFn;
+
+  return {
+    ...ctx,
+    compose,
+  };
+};
+
+const bindFireToCtx = (
+  ctx: TrailContext,
+  topo: Topo | undefined,
+  options: ExecuteTrailInternalOptions | undefined,
+  producerTrailId?: string | undefined
+): TrailContext => {
+  // 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
+  // topo-backed dispatcher. Framework-created fire functions are replaced
+  // because consumer fan-out seeds them before the consumer trace span exists.
+  if (ctx.fire !== undefined && !isFrameworkFireFn(ctx.fire)) {
+    return ctx;
+  }
+  if (topo === undefined) {
+    return ctx;
+  }
+  // Forward the producer's execution options to consumers so resources,
+  // layers, configValues, and abortSignal propagate through signal fan-out.
+  // `createContext` is intentionally stripped — consumers inherit the
+  // 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 compose schema).
+  const {
+    createContext: _omit,
+    composeValidation: _omitComposeValidation,
+    validationSchema: _omitSchema,
+    version: _omitVersion,
+    ...forwarded
+  } = options ?? {};
+  const trackedCtx = withFireDispatchTracking(ctx);
+  const fire = createFireFn(
+    topo,
+    trackedCtx,
+    (consumer, input, consumerCtx) =>
+      // eslint-disable-next-line no-use-before-define -- executor closure runs only after executeTrail is defined
+      executeTrailInternal(consumer, input, {
+        ...forwarded,
+        ctx: consumerCtx,
+        topo,
+      }),
+    producerTrailId
+  );
+  return { ...trackedCtx, fire };
+};
+
+const bindComposeAtLayerBoundary =
+  <I, O>(
+    implementation: Implementation<I, O>,
+    topo: Topo | undefined,
+    options: ExecuteTrailInternalOptions | undefined
+  ): Implementation<I, O> =>
+  (input, ctx) =>
+    implementation(input, bindComposeToCtx(ctx, topo, options));
+
+const bindFireAtLayerBoundary = <I, O>(
+  implementation: Implementation<I, O>,
+  trail: AnyTrail,
+  topo: Topo | undefined,
+  options: ExecuteTrailInternalOptions | undefined
+): Implementation<I, O> => {
+  if (topo === undefined) {
+    return implementation;
+  }
+
+  return (input, ctx) =>
+    implementation(input, bindFireToCtx(ctx, topo, options, trail.id));
+};
+
+// ---------------------------------------------------------------------------
+// Detour loop
+// ---------------------------------------------------------------------------
+
+/**
+ * Find the first detour whose `on` class matches the error via `instanceof`.
+ *
+ * Declaration order wins — no most-specific-first hierarchy walking.
+ */
+const findMatchingDetour = (
+  /* oxlint-disable-next-line no-explicit-any -- existential detour array from AnyTrail */
+  detours: readonly Detour<any, any, TrailsError>[],
+  error: TrailsError
+  /* oxlint-disable-next-line no-explicit-any -- matched detour carries runtime generics */
+): Detour<any, any, TrailsError> | undefined =>
+  detours.find((d) => error instanceof d.on);
+
+/** 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>,
+  attempt: number,
+  lastError: TrailsError,
+  input: unknown,
+  ctx: TrailContext
+): Promise<Result<unknown, Error>> => {
+  const run = async () =>
+    await detour.recover({ attempt, error: lastError, input }, ctx);
+
+  return ctx.trace
+    ? await ctx.trace(`detour:${detour.on.name}:${attempt}`, run)
+    : await run();
+};
+
+/** Classify a detour attempt result: continue the loop, or return early. */
+const classifyDetourResult = (
+  result: Result<unknown, Error>,
+  /* oxlint-disable-next-line no-explicit-any -- existential detour from AnyTrail */
+  detour: Detour<any, any, TrailsError>
+):
+  | { readonly done: true; readonly result: Result<unknown, Error> }
+  | { readonly done: false; readonly nextError: TrailsError } => {
+  if (result.isOk()) {
+    return { done: true, result };
+  }
+  const recoverError = result.error;
+  if (
+    !(recoverError instanceof TrailsError) ||
+    !(recoverError instanceof detour.on)
+  ) {
+    return { done: true, result };
+  }
+  return { done: false, nextError: recoverError };
+};
+
+/** Resolve effective maxAttempts, warning if the declared value exceeds the hard cap. */
+const resolveMaxAttempts = (
+  /* oxlint-disable-next-line no-explicit-any -- existential detour from AnyTrail */
+  detour: Detour<any, any, TrailsError>,
+  ctx: TrailContext
+): number => {
+  const declared = detour.maxAttempts ?? 1;
+  const clamped = Math.max(1, Math.min(declared, DETOUR_MAX_ATTEMPTS_CAP));
+  if (clamped === declared) {
+    return clamped;
+  }
+  ctx.logger?.warn('detour maxAttempts clamped', {
+    declared,
+    detour: detour.on.name,
+    effective: clamped,
+  });
+  return clamped;
+};
+
+/** Run the detour recovery loop for a single matched detour. */
+const runDetourRecovery = async (
+  /* oxlint-disable-next-line no-explicit-any -- existential detour from AnyTrail */
+  detour: Detour<any, any, TrailsError>,
+  error: TrailsError,
+  input: unknown,
+  ctx: TrailContext
+): Promise<Result<unknown, Error>> => {
+  const maxAttempts = resolveMaxAttempts(detour, ctx);
+  let lastError: TrailsError = error;
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+    ctx.logger?.debug('detour recovery attempt', {
+      attempt,
+      errorClass: lastError.name,
+      matchedDetour: detour.on.name,
+      maxAttempts,
+    });
+    const result = await executeDetourAttempt(
+      detour,
+      attempt,
+      lastError,
+      input,
+      ctx
+    );
+    const classification = classifyDetourResult(result, detour);
+    if (classification.done) {
+      return classification.result;
+    }
+    lastError = classification.nextError;
+  }
+
+  return Result.err(
+    new RetryExhaustedError(lastError, {
+      attempts: maxAttempts,
+      detour: detour.on.name,
+    })
+  );
+};
+
+/**
+ * Wrap an implementation with the detour recovery loop.
+ *
+ * If the trail has no detours, returns the implementation unchanged (no wrapper overhead).
+ * The detour loop runs inside the layer stack, closest to the implementation.
+ */
+const wrapWithDetours = (
+  implementation: Implementation<unknown, unknown>,
+  /* oxlint-disable-next-line no-explicit-any -- existential detour array from AnyTrail */
+  detours: readonly Detour<any, any, TrailsError>[]
+): Implementation<unknown, unknown> => {
+  if (detours.length === 0) {
+    return implementation;
+  }
+
+  return async (input, ctx) => {
+    const result = await implementation(input, ctx);
+    if (result.isOk()) {
+      return result;
+    }
+
+    const { error } = result;
+    if (!(error instanceof TrailsError)) {
+      return result;
+    }
+
+    const matched = findMatchingDetour(detours, error);
+    if (matched === undefined) {
+      return result;
+    }
+
+    return await runDetourRecovery(matched, error, input, ctx);
+  };
+};
+
+const wrapWithOutputValidation = (
+  trail: AnyTrail,
+  implementation: Implementation<unknown, unknown>
+): Implementation<unknown, unknown> => {
+  const { output } = trail;
+  if (output === undefined) {
+    return implementation;
+  }
+
+  return async (input, ctx) => {
+    const result = await implementation(input, ctx);
+    if (result.isErr()) {
+      return result;
+    }
+
+    const validated = validateOutput(output, result.value);
+    return validated.isErr()
+      ? Result.err(validated.error)
+      : Result.ok(validated.value);
+  };
+};
+
+const prepareRunImpl = (
+  trail: AnyTrail,
+  ctx: TrailContext,
+  layers: readonly Layer[],
+  topo: Topo | undefined,
+  options: ExecuteTrailInternalOptions | undefined
+): {
+  readonly ctxWithIntrinsics: TrailContext;
+  readonly impl: Implementation<unknown, unknown>;
+} => {
+  const ctxWithIntrinsics = bindFireToCtx(
+    bindComposeToCtx(ctx, topo, options),
+    topo,
+    options,
+    trail.id
+  );
+  // Detour loop wraps the implementation (inside layer stack, closest to implementation)
+  let impl = wrapWithDetours(
+    bindFireAtLayerBoundary(
+      bindComposeAtLayerBoundary(
+        trail.implementation as Implementation<unknown, unknown>,
+        topo,
+        options
+      ),
+      trail,
+      topo,
+      options
+    ),
+    trail.detours
+  );
+
+  for (let i = layers.length - 1; i >= 0; i -= 1) {
+    const layer = layers[i];
+    if (layer) {
+      impl = bindFireAtLayerBoundary(
+        bindComposeAtLayerBoundary(
+          layer.wrap(trail, impl as never) as Implementation<unknown, unknown>,
+          topo,
+          options
+        ),
+        trail,
+        topo,
+        options
+      );
+    }
+  }
+
+  return {
+    ctxWithIntrinsics,
+    impl: wrapWithOutputValidation(trail, impl),
+  };
+};
+
+const runImplWithoutTracing = async (
+  trail: AnyTrail,
+  input: unknown,
+  ctx: TrailContext,
+  layers: readonly Layer[],
+  topo: Topo | undefined,
+  options: ExecuteTrailInternalOptions | undefined
+): Promise<Result<unknown, Error>> => {
+  const prepared = prepareRunImpl(
+    trail,
+    buildUntracedContext(ctx),
+    layers,
+    topo,
+    options
+  );
+  try {
+    return await prepared.impl(input, prepared.ctxWithIntrinsics);
+  } finally {
+    await waitForPendingFireDispatches(prepared.ctxWithIntrinsics);
+  }
+};
+
+const runTrailWithTracing = async (
+  trail: AnyTrail,
+  input: unknown,
+  ctx: TrailContext,
+  layers: readonly Layer[],
+  topo: Topo | undefined,
+  options: ExecuteTrailInternalOptions | undefined,
+  sink: ReturnType<typeof getTraceSink>
+): Promise<Result<unknown, Error>> => {
+  const { record, tracedCtx } = buildTracedContext(trail, ctx, sink);
+  let prepared: ReturnType<typeof prepareRunImpl>;
+
+  try {
+    prepared = prepareRunImpl(trail, tracedCtx, layers, topo, options);
+  } catch (error: unknown) {
+    const status: TraceRecord['status'] =
+      error instanceof CancelledError ? 'cancelled' : 'err';
+    await writeToSink(
+      sink,
+      completeRecord(record, status, categorizeSpanError(error))
+    );
+    throw error;
+  }
+
+  return await runImplWithRootRecord(
+    prepared.impl,
+    input,
+    prepared.ctxWithIntrinsics,
+    record,
+    sink
+  );
+};
+
+const runTrail = async (
+  trail: AnyTrail,
+  input: unknown,
+  ctx: TrailContext,
+  layers: readonly Layer[],
+  topo: Topo | undefined,
+  options: ExecuteTrailInternalOptions | undefined
+): Promise<Result<unknown, Error>> => {
+  const sink = topo?.observe?.trace ?? getTraceSink();
+  return isTracingDisabled(sink)
+    ? await runImplWithoutTracing(trail, input, ctx, layers, topo, options)
+    : await runTrailWithTracing(trail, input, ctx, layers, topo, options, sink);
+};
+
+// ---------------------------------------------------------------------------
+// Pipeline
+// ---------------------------------------------------------------------------
+
+/**
+ * Compose the typed layers attached at topo, surface, and trail scope.
+ *
+ * Composition order is topo → surface → trail → execution-supplied → implementation
+ * (outermost-first): trail-scope layers run inside surface/topo layers, and
+ * `executeTrail({ layers })` layers wrap closest to the implementation for per-call
+ * behavior.
+ */
+const composeAttachedLayers = (
+  trail: AnyTrail,
+  options: ExecuteTrailInternalOptions | undefined
+): readonly Layer[] => [
+  ...(options?.topoLayers ?? []),
+  ...(options?.surfaceLayers ?? []),
+  ...trail.layers,
+  ...(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 {
+    implementation: _implementation,
+    composeInput: _composeInput,
+    composes: _composes,
+    detours: _detours,
+    input: _input,
+    output: _output,
+    resources: _resources,
+    version: _version,
+    versions: _versions,
+    ...base
+  } = trail;
+
+  return Object.freeze({
+    ...base,
+    composes: Object.freeze([...(entry.composes ?? [])]),
+    detours: Object.freeze([...(entry.detours ?? [])]),
+    ...(entry.composeInput === undefined
+      ? {}
+      : { composeInput: entry.composeInput }),
+    implementation: entry.implementation,
+    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 resolved;
+  }
+
+  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>> =>
+  value !== null && typeof value === 'object' && !Array.isArray(value);
+
+const readContextLayerInputs = (
+  ctx: TrailContext
+): Result<Readonly<Record<string, unknown>> | undefined, ValidationError> => {
+  const value = ctx.extensions?.[LAYER_INPUTS_KEY];
+  if (value === undefined) {
+    return Result.ok();
+  }
+  return isLayerInputMap(value)
+    ? Result.ok(value)
+    : Result.err(
+        new ValidationError(
+          'Layer inputs must be an object keyed by layer name',
+          {
+            context: { extensionKey: LAYER_INPUTS_KEY },
+          }
+        )
+      );
+};
+
+const validateLayerInputs = (
+  layers: readonly Layer[],
+  layerInputs: Readonly<Record<string, unknown>>
+): Result<Readonly<Record<string, unknown>>, ValidationError> => {
+  const validated: Record<string, unknown> = { ...layerInputs };
+  for (const layer of layers) {
+    if (layer.input === undefined) {
+      continue;
+    }
+    const slot = layerInputs[layer.name];
+    if (slot === undefined) {
+      continue;
+    }
+    const parsed = layer.input.safeParse(slot);
+    if (!parsed.success) {
+      return Result.err(
+        new ValidationError(
+          `Invalid input for layer '${layer.name}': ${parsed.error.message}`,
+          {
+            cause: parsed.error,
+            context: { issues: parsed.error.issues, layerName: layer.name },
+          }
+        )
+      );
+    }
+    validated[layer.name] = parsed.data;
+  }
+  return Result.ok(validated);
+};
+
+const validateContextLayerInputs = (
+  ctx: TrailContext,
+  layers: readonly Layer[]
+): Result<TrailContext, ValidationError> => {
+  const layerInputs = readContextLayerInputs(ctx);
+  if (layerInputs.isErr()) {
+    return layerInputs;
+  }
+  if (layerInputs.value === undefined) {
+    return Result.ok(ctx);
+  }
+  const validated = validateLayerInputs(layers, layerInputs.value);
+  if (validated.isErr()) {
+    return validated;
+  }
+  return Result.ok({
+    ...ctx,
+    extensions: {
+      ...ctx.extensions,
+      [LAYER_INPUTS_KEY]: validated.value,
+    },
+  });
+};
+
+/**
+ * Execute a trail through the standard validate-context-layers-run pipeline.
+ *
+ * The function never throws -- unexpected exceptions are caught and
+ * returned as `Result.err(InternalError)`.
+ */
+const executeTrailInternal = async (
+  trail: AnyTrail,
+  rawInput: unknown,
+  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
+    );
+    if (validated.isErr()) {
+      return validated;
+    }
+
+    const resolvedCtx = await prepareContext(trail, options);
+    if (resolvedCtx.isErr()) {
+      return resolvedCtx;
+    }
+
+    const layers = composeAttachedLayers(trail, options);
+    try {
+      const layerCtx = validateContextLayerInputs(
+        resolvedCtx.value.ctx,
+        layers
+      );
+      if (layerCtx.isErr()) {
+        return layerCtx;
+      }
+      return await runTrail(
+        trail,
+        validated.value,
+        layerCtx.value,
+        layers,
+        options?.topo,
+        options
+      );
+    } finally {
+      resolvedCtx.value.releaseResources();
+    }
+  } catch (error: unknown) {
+    const message = error instanceof Error ? error.message : String(error);
+    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);