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

package/src/trail.ts

@@ -1,5 +1,6 @@
 import type { z } from 'zod';
 
+import { ValidationError } from './errors.js';
 import type {
   ActivationEntry,
   ActivationEntrySpec,
@@ -22,11 +23,13 @@ import {
 } from './signal-ref.js';
 import type { TrailsError } from './errors.js';
 import type {
+  ComposeTrailContext,
   Detour,
   Implementation,
   PermitRequirement,
   TrailContext,
 } from './types.js';
+import { zodToJsonSchema } from './validation.js';
 
 // ---------------------------------------------------------------------------
 // Trail example
@@ -68,31 +71,213 @@ export interface TrailExample<I, O> {
 }
 
 // ---------------------------------------------------------------------------
-// Blaze input — merges crossInput when declared
+// Blaze input — merges composeInput when declared
 // ---------------------------------------------------------------------------
 
 /**
  * The input type received by a trail's blaze function.
  *
- * When a trail declares `crossInput`, the runtime merges those fields into
+ * When a trail declares `composeInput`, the runtime merges those fields into
  * the input object before calling blaze. This type makes the compiler aware
- * of the merged shape so developers can access crossInput fields without a
+ * of the merged shape so developers can access composeInput fields without a
  * cast. Falls back to plain `I` when `CI` is `never` (the default).
  */
 export type BlazeInput<I, CI> = [CI] extends [never] ? I : I & CI;
 
+type TrailRef = string | { readonly id: string };
+
+// ---------------------------------------------------------------------------
+// Trail versioning
+// ---------------------------------------------------------------------------
+
+/** Contract pair represented by a version entry. */
+export interface VersionContract<I = unknown, O = unknown> {
+  readonly input: I;
+  readonly output: O;
+}
+
+export interface TrailVersionDeprecatedStatus {
+  readonly migration?: readonly string[] | undefined;
+  readonly note?: string | undefined;
+  readonly state: 'deprecated';
+  readonly successor?: number | undefined;
+  readonly [key: string]: unknown;
+}
+
+export interface TrailVersionArchivedStatus {
+  readonly reason?: string | undefined;
+  readonly state: 'archived';
+  readonly [key: string]: unknown;
+}
+
+/** Shared lifecycle metadata for historical version entries. */
+export type TrailVersionStatus =
+  | TrailVersionArchivedStatus
+  | TrailVersionDeprecatedStatus;
+
+/** Shared base for version entries. Historical entries never inherit schemas. */
+export interface VersionEntry<
+  TContract extends VersionContract = VersionContract,
+> {
+  readonly examples?:
+    | readonly TrailExample<TContract['input'], TContract['output']>[]
+    | undefined;
+  readonly input: z.ZodType<TContract['input']>;
+  readonly marker?: never;
+  readonly output: z.ZodType<TContract['output']>;
+  readonly status?: TrailVersionStatus | undefined;
+}
+
+export type TrailVersionTransposeInput<VersionInput, CurrentInput> = (value: {
+  readonly input: VersionInput;
+}) => CurrentInput | Promise<CurrentInput>;
+
+export type TrailVersionTransposeOutput<CurrentOutput, VersionOutput> =
+  (value: {
+    readonly output: CurrentOutput;
+  }) => VersionOutput | Promise<VersionOutput>;
+
+export interface TrailVersionTranspose<
+  VersionInput,
+  VersionOutput,
+  CurrentInput,
+  CurrentOutput,
+> {
+  readonly input: TrailVersionTransposeInput<VersionInput, CurrentInput>;
+  readonly output: TrailVersionTransposeOutput<CurrentOutput, VersionOutput>;
+}
+
+export interface TrailVersionRevisionEntry<
+  VersionInput = unknown,
+  VersionOutput = unknown,
+  CurrentInput = unknown,
+  CurrentOutput = unknown,
+> extends VersionEntry<VersionContract<VersionInput, VersionOutput>> {
+  readonly blaze?: never;
+  readonly composeInput?: never;
+  readonly composes?: never;
+  readonly detours?: never;
+  readonly kind?: never;
+  readonly resources?: never;
+  readonly transpose?:
+    | TrailVersionTranspose<
+        VersionInput,
+        VersionOutput,
+        CurrentInput,
+        CurrentOutput
+      >
+    | undefined;
+}
+
+export interface TrailVersionForkEntry<
+  VersionInput = unknown,
+  VersionOutput = unknown,
+  ComposeInput = never,
+> extends VersionEntry<VersionContract<VersionInput, VersionOutput>> {
+  readonly blaze: Implementation<
+    BlazeInput<VersionInput, ComposeInput>,
+    VersionOutput
+  >;
+  readonly composes?: readonly (string | AnyTrail)[] | undefined;
+  readonly composeInput?: z.ZodType<ComposeInput> | undefined;
+  readonly detours?:
+    | readonly Detour<VersionInput, VersionOutput, TrailsError>[]
+    | undefined;
+  readonly kind?: never;
+  readonly resources?: readonly AnyResource[] | undefined;
+  readonly transpose?: never;
+}
+
+export type TrailVersionEntry<
+  VersionInput = unknown,
+  VersionOutput = unknown,
+  CurrentInput = unknown,
+  CurrentOutput = unknown,
+  ComposeInput = never,
+> =
+  | TrailVersionRevisionEntry<
+      VersionInput,
+      VersionOutput,
+      CurrentInput,
+      CurrentOutput
+    >
+  | TrailVersionForkEntry<VersionInput, VersionOutput, ComposeInput>;
+
+export type TrailVersionEntryKind = 'revision' | 'fork';
+
+export type TrailVersions<
+  CurrentInput = unknown,
+  CurrentOutput = unknown,
+> = Readonly<
+  Record<
+    number,
+    TrailVersionEntry<unknown, unknown, CurrentInput, CurrentOutput>
+  >
+>;
+
+export const getTrailVersionEntryKind = (
+  entry: TrailVersionEntry
+): TrailVersionEntryKind => {
+  const raw = entry as unknown as Record<string, unknown>;
+  return typeof raw['blaze'] === 'function' ? 'fork' : 'revision';
+};
+
+export const isArchivedTrailVersionEntry = (
+  entry: Pick<TrailVersionEntry, 'status'>
+): boolean => entry.status?.state === 'archived';
+
+export const isDeprecatedTrailVersionEntry = (
+  entry: Pick<TrailVersionEntry, 'status'>
+): boolean => entry.status?.state === 'deprecated';
+
+export const isLiveTrailVersionEntry = (
+  entry: Pick<TrailVersionEntry, 'status'>
+): boolean => entry.status === undefined || entry.status.state === 'deprecated';
+
+export const hasDeprecatedTrailVersionGuidance = (
+  status: Pick<TrailVersionDeprecatedStatus, 'migration' | 'note' | 'successor'>
+): boolean =>
+  status.successor !== undefined ||
+  (Array.isArray(status.migration) && status.migration.length > 0) ||
+  (typeof status.note === 'string' && status.note.trim().length > 0);
+
+export const deriveSupportedTrailVersions = (
+  trail: Pick<AnyTrail, 'version' | 'versions'>
+): readonly number[] => {
+  if (trail.version === undefined) {
+    return [];
+  }
+
+  const supported = new Set<number>([trail.version]);
+  for (const [rawVersion, entry] of Object.entries(trail.versions ?? {})) {
+    if (isLiveTrailVersionEntry(entry)) {
+      supported.add(Number(rawVersion));
+    }
+  }
+
+  return Object.freeze([...supported].toSorted((a, b) => a - b));
+};
+
 // ---------------------------------------------------------------------------
 // Trail spec
 // ---------------------------------------------------------------------------
 
 /** Everything needed to define a trail (minus the id) */
-export interface TrailSpec<I, O, CI = never> {
+type ComposeContextFor<C extends readonly TrailRef[] | undefined> =
+  C extends undefined ? TrailContext : ComposeTrailContext;
+
+export interface TrailSpec<
+  I,
+  O,
+  CI = never,
+  C extends readonly TrailRef[] | undefined = undefined,
+> {
   /** Zod schema for validating input */
   readonly input: z.ZodType<I>;
   /** Zod schema for validating output (optional — some trails are fire-and-forget) */
   readonly output?: z.ZodType<O> | undefined;
   /** The pure function that does the work (sync or async authoring) */
-  readonly blaze: Implementation<BlazeInput<I, CI>, O>;
+  readonly blaze: Implementation<BlazeInput<I, CI>, O, ComposeContextFor<C>>;
   /** Human-readable description */
   readonly description?: string | undefined;
   /** Declared operational shape for governance, derivation, and agent guidance. */
@@ -134,17 +319,17 @@ export interface TrailSpec<I, O, CI = never> {
   readonly fields?: Readonly<Record<string, FieldOverride>> | undefined;
   /** Contours this trail operates on. */
   readonly contours?: readonly AnyContour[] | undefined;
-  /** IDs or trail objects of downstream trails this trail may invoke via ctx.cross() */
-  readonly crosses?: readonly (string | AnyTrail)[] | undefined;
+  /** IDs or trail objects of downstream trails this trail may invoke via ctx.compose() */
+  readonly composes?: C;
   /**
-   * Composition-only input schema — merged with `input` for `ctx.cross()` calls,
+   * Composition-only input schema — merged with `input` for `ctx.compose()` calls,
    * invisible to public surfaces (CLI, MCP, HTTP).
    *
    * Fields here are available in the blaze but are not derived into CLI flags,
    * MCP tool parameters, or HTTP request bodies. Use for data that only makes
-   * sense when one trail crosses another (e.g. `forkedFrom`).
+   * sense when one trail composes another (e.g. `forkedFrom`).
    */
-  readonly crossInput?: z.ZodType<CI> | undefined;
+  readonly composeInput?: z.ZodType<CI> | undefined;
   /** Resources this trail may access via resource.from(ctx) */
   readonly resources?: readonly AnyResource[] | undefined;
   /**
@@ -154,7 +339,7 @@ export interface TrailSpec<I, O, CI = never> {
    * normalized to the signal's id at trail definition time, so
    * `trail.fires` is always `readonly string[]`.
    *
-   * Note: `crosses` also accepts trail objects (normalized to IDs),
+   * Note: `composes` also accepts trail objects (normalized to IDs),
    * following the same pattern as signal references here.
    */
   readonly fires?: readonly (string | AnySignal)[] | undefined;
@@ -171,6 +356,12 @@ export interface TrailSpec<I, O, CI = never> {
   readonly permit?: PermitRequirement | undefined;
   /** Primary input fields and their order. CLI projects as positional args. */
   readonly args?: readonly string[] | false | undefined;
+  /** Current trail version number. Omit for current-only unversioned trails. */
+  readonly version?: number | undefined;
+  /** Explicit historical trail versions. Current stays top-level. */
+  readonly versions?: TrailVersions<I, O> | undefined;
+  /** Version markers are projected into the resolved graph, not authored. */
+  readonly marker?: never;
 }
 
 // ---------------------------------------------------------------------------
@@ -191,12 +382,12 @@ export type TrailVisibility = 'public' | 'internal';
 
 /** A fully-defined trail — the unit of work in the Trails system */
 export interface Trail<I, O, CI = never> extends Omit<
-  TrailSpec<I, O, CI>,
+  TrailSpec<I, O, CI, readonly TrailRef[] | undefined>,
   | 'args'
   | 'blaze'
   | 'contours'
-  | 'crosses'
-  | 'crossInput'
+  | 'composes'
+  | 'composeInput'
   | 'detours'
   | 'fires'
   | 'intent'
@@ -209,10 +400,10 @@ export interface Trail<I, O, CI = never> extends Omit<
   readonly blaze: Implementation<BlazeInput<I, CI>, O>;
   /** Contours this trail operates on (always present, default []). */
   readonly contours: readonly AnyContour[];
-  /** IDs of downstream trails this trail may invoke via ctx.cross() (always present, default []) */
-  readonly crosses: readonly string[];
-  /** Composition-only input schema, merged with `input` for ctx.cross() calls (optional) */
-  readonly crossInput?: z.ZodType<CI> | undefined;
+  /** IDs of downstream trails this trail may invoke via ctx.compose() (always present, default []) */
+  readonly composes: readonly string[];
+  /** Composition-only input schema, merged with `input` for ctx.compose() calls (optional) */
+  readonly composeInput?: z.ZodType<CI> | undefined;
   /** Recovery paths activated when blaze fails with a matching error (always present, default []). */
   readonly detours: readonly Detour<I, O, TrailsError>[];
   /**
@@ -358,13 +549,427 @@ const extractSignalActivationIds = (
       .map((entry) => entry.source.id)
   );
 
-/** Normalize a crosses entry — trail objects are reduced to their id. */
-const normalizeCrossRef = (entry: string | AnyTrail): string =>
+/** Normalize a composes entry — trail objects are reduced to their id. */
+const normalizeComposeRef = (entry: TrailRef): string =>
   typeof entry === 'string' ? entry : entry.id;
 
+const assertVersionNumber = (
+  trailId: string,
+  label: string,
+  version: number
+): void => {
+  if (!Number.isSafeInteger(version) || version <= 0) {
+    throw new ValidationError(
+      `Trail "${trailId}" ${label} must be a positive integer`
+    );
+  }
+};
+
+const hasOwn = (value: Record<string, unknown>, key: string): boolean =>
+  Object.hasOwn(value, key);
+
+const ORDER_INSENSITIVE_SCHEMA_ARRAY_KEYS = new Set([
+  'allOf',
+  'anyOf',
+  'enum',
+  'oneOf',
+  'required',
+  'type',
+]);
+
+const canonicalizeVersionSchema = (
+  value: unknown,
+  parentKey?: string
+): unknown => {
+  if (Array.isArray(value)) {
+    const items = value.map((item) => canonicalizeVersionSchema(item));
+    return parentKey !== undefined &&
+      ORDER_INSENSITIVE_SCHEMA_ARRAY_KEYS.has(parentKey)
+      ? items.toSorted((left, right) =>
+          JSON.stringify(left).localeCompare(JSON.stringify(right))
+        )
+      : items;
+  }
+  if (value !== null && typeof value === 'object') {
+    const sorted: Record<string, unknown> = {};
+    for (const key of Object.keys(value).toSorted()) {
+      sorted[key] = canonicalizeVersionSchema(
+        (value as Record<string, unknown>)[key],
+        key
+      );
+    }
+    return sorted;
+  }
+  return value;
+};
+
+const schemasMatch = (left: z.ZodType, right: z.ZodType): boolean =>
+  JSON.stringify(canonicalizeVersionSchema(zodToJsonSchema(left))) ===
+  JSON.stringify(canonicalizeVersionSchema(zodToJsonSchema(right)));
+
+const assertZodSchema = (
+  trailId: string,
+  version: number,
+  entry: Record<string, unknown>,
+  field: 'input' | 'output'
+): void => {
+  if (!hasOwn(entry, field) || entry[field] === undefined) {
+    throw new ValidationError(
+      `Trail "${trailId}" version ${version} must declare explicit ${field}`
+    );
+  }
+};
+
+const normalizeVersionStatusMigration = (
+  trailId: string,
+  version: number,
+  migration: unknown
+): readonly string[] | undefined => {
+  if (migration === undefined) {
+    return undefined;
+  }
+  if (!Array.isArray(migration)) {
+    throw new ValidationError(
+      `Trail "${trailId}" version ${version} status.migration must be an array`
+    );
+  }
+
+  return Object.freeze(
+    migration.map((step, index) => {
+      if (typeof step !== 'string' || step.trim().length === 0) {
+        throw new ValidationError(
+          `Trail "${trailId}" version ${version} status.migration[${index}] must be a non-empty string`
+        );
+      }
+      return step;
+    })
+  );
+};
+
+const normalizeVersionStatus = (
+  trailId: string,
+  version: number,
+  status: unknown
+): TrailVersionStatus | undefined => {
+  if (status === undefined) {
+    return undefined;
+  }
+  if (typeof status !== 'object' || status === null || Array.isArray(status)) {
+    throw new ValidationError(
+      `Trail "${trailId}" version ${version} status must be an object`
+    );
+  }
+
+  const raw = status as Record<string, unknown>;
+  if (raw['state'] !== 'deprecated' && raw['state'] !== 'archived') {
+    throw new ValidationError(
+      `Trail "${trailId}" version ${version} status.state must be "deprecated" or "archived"`
+    );
+  }
+  if (raw['state'] === 'deprecated') {
+    if (raw['successor'] !== undefined) {
+      assertVersionNumber(
+        trailId,
+        `version ${version} status.successor`,
+        raw['successor'] as number
+      );
+    }
+    if (raw['note'] !== undefined) {
+      if (typeof raw['note'] !== 'string') {
+        throw new ValidationError(
+          `Trail "${trailId}" version ${version} status.note must be a string`
+        );
+      }
+      if (raw['note'].trim().length === 0) {
+        throw new ValidationError(
+          `Trail "${trailId}" version ${version} status.note must be a non-empty string`
+        );
+      }
+    }
+    const migration = normalizeVersionStatusMigration(
+      trailId,
+      version,
+      raw['migration']
+    );
+    const normalized = Object.freeze({
+      ...raw,
+      ...(migration === undefined ? {} : { migration }),
+      state: 'deprecated',
+    }) as TrailVersionDeprecatedStatus;
+    if (!hasDeprecatedTrailVersionGuidance(normalized)) {
+      throw new ValidationError(
+        `Trail "${trailId}" version ${version} deprecated status must declare successor, migration, or note guidance`
+      );
+    }
+    return normalized;
+  }
+
+  if (
+    raw['reason'] !== undefined &&
+    (typeof raw['reason'] !== 'string' || raw['reason'].trim().length === 0)
+  ) {
+    throw new ValidationError(
+      `Trail "${trailId}" version ${version} status.reason must be a non-empty string`
+    );
+  }
+
+  return Object.freeze({ ...raw, state: 'archived' }) as TrailVersionStatus;
+};
+
+const normalizeVersionExamples = (
+  trailId: string,
+  version: number,
+  examples: unknown
+): readonly TrailExample<unknown, unknown>[] | undefined => {
+  if (examples === undefined) {
+    return undefined;
+  }
+  if (!Array.isArray(examples)) {
+    throw new ValidationError(
+      `Trail "${trailId}" version ${version} examples must be an array`
+    );
+  }
+
+  return Object.freeze([...examples]) as readonly TrailExample<
+    unknown,
+    unknown
+  >[];
+};
+
+const normalizeTranspose = (
+  trailId: string,
+  version: number,
+  transpose: unknown
+): TrailVersionTranspose<unknown, unknown, unknown, unknown> | undefined => {
+  if (transpose === undefined) {
+    return undefined;
+  }
+  if (
+    typeof transpose !== 'object' ||
+    transpose === null ||
+    Array.isArray(transpose)
+  ) {
+    throw new ValidationError(
+      `Trail "${trailId}" version ${version} transpose must be an object`
+    );
+  }
+
+  const raw = transpose as Record<string, unknown>;
+  if (
+    typeof raw['input'] !== 'function' ||
+    typeof raw['output'] !== 'function'
+  ) {
+    throw new ValidationError(
+      `Trail "${trailId}" version ${version} transpose must define input and output functions`
+    );
+  }
+
+  return Object.freeze({
+    input: raw['input'],
+    output: raw['output'],
+  }) as TrailVersionTranspose<unknown, unknown, unknown, unknown>;
+};
+
+const assertRevisionOwnsNoRuntimeFields = (
+  trailId: string,
+  version: number,
+  entry: Record<string, unknown>
+): void => {
+  const forbidden = ['composeInput', 'composes', 'resources', 'detours'];
+  const declared = forbidden.filter((field) => hasOwn(entry, field));
+  if (declared.length > 0) {
+    throw new ValidationError(
+      `Trail "${trailId}" version ${version} is a revision and cannot declare ${declared.join(', ')}`
+    );
+  }
+};
+
+const normalizeVersionEntry = <CurrentInput, CurrentOutput>(
+  trailId: string,
+  version: number,
+  currentInput: z.ZodType<CurrentInput>,
+  currentOutput: z.ZodType<CurrentOutput> | undefined,
+  entry: TrailVersionEntry<unknown, unknown, CurrentInput, CurrentOutput>
+): TrailVersionEntry<unknown, unknown, CurrentInput, CurrentOutput> => {
+  if (typeof entry !== 'object' || entry === null || Array.isArray(entry)) {
+    throw new ValidationError(
+      `Trail "${trailId}" version ${version} must be an object`
+    );
+  }
+
+  const raw = entry as unknown as Record<string, unknown>;
+  assertZodSchema(trailId, version, raw, 'input');
+  assertZodSchema(trailId, version, raw, 'output');
+
+  if (hasOwn(raw, 'kind')) {
+    throw new ValidationError(
+      `Trail "${trailId}" version ${version} must not author kind; it is projected`
+    );
+  }
+  if (hasOwn(raw, 'marker')) {
+    throw new ValidationError(
+      `Trail "${trailId}" version ${version} must not author marker; it is projected`
+    );
+  }
+
+  const hasBlaze = typeof raw['blaze'] === 'function';
+  const hasTranspose = raw['transpose'] !== undefined;
+  if (hasBlaze && hasTranspose) {
+    throw new ValidationError(
+      `Trail "${trailId}" version ${version} cannot declare both blaze and transpose`
+    );
+  }
+
+  const base = {
+    ...(raw['examples'] === undefined
+      ? {}
+      : {
+          examples: normalizeVersionExamples(trailId, version, raw['examples']),
+        }),
+    input: raw['input'],
+    output: raw['output'],
+    ...(raw['status'] === undefined
+      ? {}
+      : { status: normalizeVersionStatus(trailId, version, raw['status']) }),
+  };
+
+  if (hasBlaze) {
+    return Object.freeze({
+      ...base,
+      blaze: async (input: unknown, ctx: TrailContext) =>
+        await (raw['blaze'] as Implementation<unknown, unknown>)(input, ctx),
+      ...(raw['composeInput'] === undefined
+        ? {}
+        : { composeInput: raw['composeInput'] }),
+      composes: Object.freeze(
+        (
+          (raw['composes'] as readonly (string | AnyTrail)[] | undefined) ?? []
+        ).map(normalizeComposeRef)
+      ),
+      detours: Object.freeze([
+        ...(((raw['detours'] as readonly Detour<
+          unknown,
+          unknown,
+          TrailsError
+        >[]) ?? []) as readonly Detour<unknown, unknown, TrailsError>[]),
+      ]),
+      resources: Object.freeze([
+        ...(((raw['resources'] as readonly AnyResource[]) ??
+          []) as readonly AnyResource[]),
+      ]),
+    }) as TrailVersionEntry<unknown, unknown, CurrentInput, CurrentOutput>;
+  }
+
+  assertRevisionOwnsNoRuntimeFields(trailId, version, raw);
+  const inputMatchesCurrent = schemasMatch(
+    raw['input'] as z.ZodType,
+    currentInput
+  );
+  const outputMatchesCurrent =
+    currentOutput === undefined ||
+    schemasMatch(raw['output'] as z.ZodType, currentOutput);
+  if (!hasTranspose && (!inputMatchesCurrent || !outputMatchesCurrent)) {
+    throw new ValidationError(
+      `Trail "${trailId}" version ${version} changes schema and must declare transpose`
+    );
+  }
+
+  return Object.freeze({
+    ...base,
+    ...(hasTranspose
+      ? { transpose: normalizeTranspose(trailId, version, raw['transpose']) }
+      : {}),
+  }) as TrailVersionEntry<unknown, unknown, CurrentInput, CurrentOutput>;
+};
+
+const normalizeTrailVersions = <CurrentInput, CurrentOutput>(
+  trailId: string,
+  currentInput: z.ZodType<CurrentInput>,
+  currentOutput: z.ZodType<CurrentOutput> | undefined,
+  currentVersion: number | undefined,
+  versions: TrailVersions<CurrentInput, CurrentOutput> | undefined
+): TrailVersions<CurrentInput, CurrentOutput> | undefined => {
+  if (currentVersion === undefined) {
+    if (versions !== undefined) {
+      throw new ValidationError(
+        `Trail "${trailId}" declares versions without a current version`
+      );
+    }
+    return undefined;
+  }
+
+  assertVersionNumber(trailId, 'version', currentVersion);
+
+  if (versions === undefined) {
+    return undefined;
+  }
+  if (
+    typeof versions !== 'object' ||
+    versions === null ||
+    Array.isArray(versions)
+  ) {
+    throw new ValidationError(`Trail "${trailId}" versions must be an object`);
+  }
+
+  const normalized: Record<
+    number,
+    TrailVersionEntry<unknown, unknown, CurrentInput, CurrentOutput>
+  > = {};
+  for (const [rawVersion, entry] of Object.entries(versions)) {
+    const historicalVersion = Number(rawVersion);
+    if (`${historicalVersion}` !== rawVersion) {
+      throw new ValidationError(
+        `Trail "${trailId}" versions key "${rawVersion}" must be a positive integer`
+      );
+    }
+    assertVersionNumber(trailId, `versions.${rawVersion}`, historicalVersion);
+    if (historicalVersion === currentVersion) {
+      throw new ValidationError(
+        `Trail "${trailId}" version ${historicalVersion} is current and must stay top-level`
+      );
+    }
+    if (historicalVersion > currentVersion) {
+      throw new ValidationError(
+        `Trail "${trailId}" version ${historicalVersion} must be less than the current version (${currentVersion})`
+      );
+    }
+    normalized[historicalVersion] = normalizeVersionEntry(
+      trailId,
+      historicalVersion,
+      currentInput,
+      currentOutput,
+      entry
+    );
+  }
+
+  const knownVersions = new Set([
+    currentVersion,
+    ...Object.keys(normalized).map(Number),
+  ]);
+  for (const [rawVersion, entry] of Object.entries(normalized)) {
+    if (
+      entry.status?.state === 'deprecated' &&
+      entry.status.successor !== undefined &&
+      (!knownVersions.has(entry.status.successor) ||
+        entry.status.successor === Number(rawVersion))
+    ) {
+      throw new ValidationError(
+        `Trail "${trailId}" version ${rawVersion} status.successor must reference the current version or another known historical version`
+      );
+    }
+  }
+
+  return Object.freeze(normalized);
+};
+
 /** Freeze and normalize all collection fields from a trail spec. */
-const normalizeCollections = <I, O, CI>(
-  spec: TrailSpec<I, O, CI>
+const normalizeCollections = <
+  I,
+  O,
+  CI,
+  C extends readonly TrailRef[] | undefined,
+>(
+  spec: TrailSpec<I, O, CI, C>
 ): {
   readonly args: readonly string[] | false | undefined;
   readonly activationSources: readonly ActivationEntry[];
@@ -410,16 +1015,26 @@ const normalizeCollections = <I, O, CI>(
  * });
  * ```
  */
-export function trail<I, O, CI = never>(
-  id: string,
-  spec: TrailSpec<I, O, CI>
-): Trail<I, O, CI>;
-export function trail<I, O, CI = never>(
-  spec: TrailSpec<I, O, CI> & { readonly id: string }
-): Trail<I, O, CI>;
-export function trail<I, O, CI = never>(
-  idOrSpec: string | (TrailSpec<I, O, CI> & { readonly id: string }),
-  maybeSpec?: TrailSpec<I, O, CI>
+export function trail<
+  I,
+  O,
+  CI = never,
+  const C extends readonly TrailRef[] | undefined = undefined,
+>(id: string, spec: TrailSpec<I, O, CI, C>): Trail<I, O, CI>;
+export function trail<
+  I,
+  O,
+  CI = never,
+  const C extends readonly TrailRef[] | undefined = undefined,
+>(spec: TrailSpec<I, O, CI, C> & { readonly id: string }): Trail<I, O, CI>;
+export function trail<
+  I,
+  O,
+  CI = never,
+  const C extends readonly TrailRef[] | undefined = undefined,
+>(
+  idOrSpec: string | (TrailSpec<I, O, CI, C> & { readonly id: string }),
+  maybeSpec?: TrailSpec<I, O, CI, C>
 ): Trail<I, O, CI> {
   const resolved =
     typeof idOrSpec === 'string'
@@ -429,11 +1044,16 @@ export function trail<I, O, CI = never>(
   if (!resolved.spec) {
     throw new TypeError('trail() requires a spec when an id is provided');
   }
+  if (hasOwn(resolved.spec as unknown as Record<string, unknown>, 'marker')) {
+    throw new ValidationError(
+      `Trail "${resolved.id}" must not author marker; it is projected`
+    );
+  }
 
   const {
     blaze,
-    crossInput,
-    crosses: rawCrosses,
+    composeInput,
+    composes: rawComposes,
     intent: rawIntent,
     visibility: rawVisibility,
     // Destructure away fields handled by normalizeCollections
@@ -444,20 +1064,31 @@ export function trail<I, O, CI = never>(
     layers: _l,
     on: _o,
     resources: _r,
+    version: rawVersion,
+    versions: rawVersions,
     ...spec
   } = resolved.spec;
   const collections = normalizeCollections(resolved.spec);
+  const versions = normalizeTrailVersions<I, O>(
+    resolved.id,
+    resolved.spec.input,
+    resolved.spec.output,
+    rawVersion,
+    rawVersions
+  );
 
   return Object.freeze({
     ...spec,
     ...collections,
     blaze: async (input: BlazeInput<I, CI>, ctx: TrailContext) =>
-      await blaze(input, ctx),
-    crossInput,
-    crosses: Object.freeze((rawCrosses ?? []).map(normalizeCrossRef)),
+      await blaze(input, ctx as ComposeContextFor<C>),
+    composeInput,
+    composes: Object.freeze((rawComposes ?? []).map(normalizeComposeRef)),
     id: resolved.id,
     intent: rawIntent ?? 'write',
     kind: 'trail' as const,
+    ...(rawVersion === undefined ? {} : { version: rawVersion }),
+    ...(versions === undefined ? {} : { versions }),
     visibility: rawVisibility ?? 'public',
   });
 }
@@ -466,8 +1097,12 @@ export function trail<I, O, CI = never>(
 // The Omit+override avoids a TypeScript limitation where BlazeInput's conditional type
 // makes Trail<any, any, any> structurally incompatible with Trail<I, O, never>.
 /* oxlint-disable no-explicit-any -- existential type for heterogeneous collections */
-export type AnyTrail = Omit<Trail<any, any, any>, 'blaze'> & {
+export type AnyTrail = Omit<
+  Trail<any, any, never>,
+  'blaze' | 'composeInput'
+> & {
   readonly blaze: Implementation<any, any>;
+  readonly composeInput?: z.ZodType<any> | undefined;
 };
 /* oxlint-enable no-explicit-any */