@ontrails/core 0.2.0

package/src/trail.ts

@@ -0,0 +1,1351 @@
+import type { z } from 'zod';
+
+import { ValidationError } from './errors.js';
+import type {
+  ActivationEntry,
+  ActivationEntrySpec,
+  ActivationSource,
+  ActivationSourceRef,
+} from './activation-source.js';
+import {
+  isActivationEntrySpec,
+  isActivationSource,
+} from './activation-source.js';
+import type { AnyEntity } from './entity.js';
+import type {
+  FieldOverride,
+  CliCommandPathInput,
+  TrailCliRendering,
+} from './derive.js';
+import type { Layer } from './layer.js';
+import type { Result } from './result.js';
+import type { AnyResource } from './resource.js';
+import type { AnySignal } from './signal.js';
+import {
+  createLateBoundSignalMarker,
+  getLateBoundSignalRef,
+  isBoundLateBoundSignal,
+} 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
+// ---------------------------------------------------------------------------
+
+export interface TrailExampleSignalAssertion {
+  /** Signal contract object or stable signal ID expected during the example. */
+  readonly signal: AnySignal | string;
+  /** Exact payload assertion for the fired signal. */
+  readonly payload?: unknown | undefined;
+  /** Partial payload assertion; declared fields must match, extras ignored. */
+  readonly payloadMatch?: unknown | undefined;
+  /** Number of matching fired signals expected. Defaults to one. */
+  readonly times?: number | undefined;
+}
+
+/**
+ * A named example for documentation and testing.
+ *
+ * The `input` field accepts `Partial<I>` so that fields with schema defaults
+ * (e.g. `z.number().default(20)`) can be omitted from examples. The schema
+ * fills in defaults at validation time.
+ */
+export interface TrailExample<I, O> {
+  /** Human-readable name */
+  readonly name: string;
+  /** Optional description of what this example demonstrates */
+  readonly description?: string | undefined;
+  /** The input value — fields with schema defaults may be omitted */
+  readonly input: Partial<I>;
+  /** Expected output for success-path examples (deep equality) */
+  readonly expected?: O | undefined;
+  /** Partial output assertion — declared fields must match, others ignored */
+  readonly expectedMatch?: Partial<O> | undefined;
+  /** Error class name for error-path examples */
+  readonly error?: string | undefined;
+  /** Signal fires expected while executing this example. */
+  readonly signals?: readonly TrailExampleSignalAssertion[] | undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Implementation input — merges composeInput when declared
+// ---------------------------------------------------------------------------
+
+/**
+ * The input type received by a trail's implementation function.
+ *
+ * When a trail declares `composeInput`, the runtime merges those fields into
+ * the input object before calling implementation. This type makes the compiler aware
+ * 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 ImplementationInput<I, CI> = [CI] extends [never] ? I : I & CI;
+
+type TrailRef = string | { readonly id: string };
+
+type ComposeSchemaOutput<TSchema extends z.ZodType | undefined> =
+  TSchema extends z.ZodType ? z.output<TSchema> : never;
+
+type SchemaOwnedTrailSpec<
+  TInputSchema extends z.ZodType,
+  O,
+  TComposeInputSchema extends z.ZodType | undefined = undefined,
+  C extends readonly TrailRef[] | undefined = undefined,
+> = Omit<
+  TrailSpec<
+    z.output<TInputSchema>,
+    O,
+    ComposeSchemaOutput<TComposeInputSchema>,
+    C
+  >,
+  | 'implementation'
+  | 'composeInput'
+  | 'detours'
+  | 'examples'
+  | 'input'
+  | 'versions'
+> & {
+  /** Zod schema for validating caller input and materializing implementation input. */
+  readonly input: TInputSchema;
+  /** The pure function receives schema-materialized input after validation/defaults. */
+  readonly implementation: Implementation<
+    ImplementationInput<
+      z.output<TInputSchema>,
+      ComposeSchemaOutput<TComposeInputSchema>
+    >,
+    O,
+    ComposeContextFor<C>
+  >;
+  /** Named examples use caller-side input; schema defaults may be omitted. */
+  readonly examples?:
+    | readonly TrailExample<z.input<TInputSchema>, O>[]
+    | undefined;
+  /** Recovery paths see the same materialized input as the implementation. */
+  readonly detours?:
+    | readonly Detour<z.output<TInputSchema>, O, TrailsError>[]
+    | undefined;
+  /** Composition-only schema, merged internally for ctx.compose() calls. */
+  readonly composeInput?: TComposeInputSchema | undefined;
+  /** Explicit historical trail versions. Current stays top-level. */
+  readonly versions?: TrailVersions<z.output<TInputSchema>, O> | undefined;
+};
+
+type SchemaOwnedOutputTrailSpec<
+  TInputSchema extends z.ZodType,
+  TOutputSchema extends z.ZodType,
+  TComposeInputSchema extends z.ZodType | undefined = undefined,
+  C extends readonly TrailRef[] | undefined = undefined,
+> = Omit<
+  SchemaOwnedTrailSpec<
+    TInputSchema,
+    z.output<TOutputSchema>,
+    TComposeInputSchema,
+    C
+  >,
+  'output'
+> & {
+  readonly output: TOutputSchema;
+};
+
+type SchemaOwnedTrail<
+  TInputSchema extends z.ZodType,
+  O,
+  TComposeInputSchema extends z.ZodType | undefined,
+> = Trail<
+  z.output<TInputSchema>,
+  O,
+  ComposeSchemaOutput<TComposeInputSchema>
+> & {
+  readonly input: TInputSchema;
+  readonly composeInput?: TComposeInputSchema | undefined;
+};
+
+type LegacyOutputTrailSpec<
+  I,
+  O,
+  CI,
+  C extends readonly TrailRef[] | undefined,
+> = Omit<TrailSpec<I, O, CI, C>, 'implementation' | 'output'> & {
+  readonly implementation: Implementation<
+    ImplementationInput<I, CI>,
+    NoInfer<O>,
+    ComposeContextFor<C>
+  >;
+  readonly output: z.ZodType<O>;
+};
+
+type LegacyOutputlessTrailSpec<
+  I,
+  O,
+  CI,
+  C extends readonly TrailRef[] | undefined,
+> = Omit<TrailSpec<I, O, CI, C>, 'implementation' | 'output'> & {
+  readonly implementation: Implementation<
+    ImplementationInput<I, CI>,
+    O,
+    ComposeContextFor<C>
+  >;
+  readonly output?: undefined;
+};
+
+// ---------------------------------------------------------------------------
+// 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 implementation?: 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 implementation: Implementation<
+    ImplementationInput<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>
+  >
+>;
+
+/**
+ * Spec for {@link forkVersion}: a fork entry whose implementation signature is owned
+ * by the entry's own schemas instead of falling back to `unknown`.
+ */
+export interface TrailVersionForkSpec<
+  TInputSchema extends z.ZodType,
+  TOutputSchema extends z.ZodType,
+  TComposeInputSchema extends z.ZodType | undefined = undefined,
+> {
+  /** The historical implementation, typed by this entry's schemas. */
+  readonly implementation: Implementation<
+    ImplementationInput<
+      z.output<TInputSchema>,
+      ComposeSchemaOutput<TComposeInputSchema>
+    >,
+    z.output<TOutputSchema>
+  >;
+  readonly composeInput?: TComposeInputSchema | undefined;
+  readonly composes?: readonly (string | AnyTrail)[] | undefined;
+  readonly detours?:
+    | readonly Detour<
+        z.output<TInputSchema>,
+        z.output<TOutputSchema>,
+        TrailsError
+      >[]
+    | undefined;
+  readonly examples?:
+    | readonly TrailExample<z.input<TInputSchema>, z.output<TOutputSchema>>[]
+    | undefined;
+  readonly input: TInputSchema;
+  readonly output: TOutputSchema;
+  readonly resources?: readonly AnyResource[] | undefined;
+  readonly status?: TrailVersionStatus | undefined;
+}
+
+/**
+ * Author a fork version entry with a implementation typed by the entry's own schemas.
+ *
+ * `TrailVersions` fixes every entry's generics to `unknown`, so a fork implementation
+ * written inline receives `unknown` input and authors end up re-parsing the
+ * already-validated value just to narrow it. This helper threads the entry's
+ * `input`/`output` schemas into the implementation signature and erases the generics
+ * on the way out. The erasure is sound because the fork pipeline validates
+ * raw input against this entry's own `input` schema before dispatching to
+ * the entry implementation (see `createForkTrailVersion` in execute.ts).
+ *
+ * @example
+ * ```ts
+ * const gearV1Input = z.object({ name: z.string(), weightOz: z.number() });
+ * const gearV1Output = z.object({ id: z.string(), weightOz: z.number() });
+ *
+ * const gearCreate = trail('gear.create', {
+ *   // ... current v2 contract ...
+ *   version: 2,
+ *   versions: {
+ *     1: forkVersion({
+ *       implementation: (input) =>
+ *         // input is { name: string; weightOz: number } — no re-parse
+ *         Result.ok({ id: input.name, weightOz: input.weightOz }),
+ *       input: gearV1Input,
+ *       output: gearV1Output,
+ *     }),
+ *   },
+ * });
+ * ```
+ */
+export const forkVersion = <
+  TInputSchema extends z.ZodType,
+  TOutputSchema extends z.ZodType,
+  TComposeInputSchema extends z.ZodType | undefined = undefined,
+>(
+  spec: TrailVersionForkSpec<TInputSchema, TOutputSchema, TComposeInputSchema>
+): TrailVersionForkEntry =>
+  // Erasing the per-entry generics narrows function parameters, which TS
+  // cannot express without a conversion. Safe: the fork pipeline re-validates
+  // input against `spec.input` before the implementation runs.
+  spec as unknown as TrailVersionForkEntry;
+
+export const getTrailVersionEntryKind = (
+  entry: TrailVersionEntry
+): TrailVersionEntryKind => {
+  const raw = entry as unknown as Record<string, unknown>;
+  return typeof raw['implementation'] === '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) */
+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 implementation: Implementation<
+    ImplementationInput<I, CI>,
+    O,
+    ComposeContextFor<C>
+  >;
+  /** Human-readable description */
+  readonly description?: string | undefined;
+  /** Declared operational shape for governance, derivation, and agent guidance. */
+  readonly pattern?: string | undefined;
+  /** Named examples for docs and testing */
+  readonly examples?: readonly TrailExample<I, O>[] | undefined;
+  /** What this trail does to the world: read, write (default), or destroy */
+  readonly intent?: 'read' | 'write' | 'destroy' | undefined;
+  /** Trail is idempotent (safe to retry) */
+  readonly idempotent?: boolean | undefined;
+  /**
+   * Trail explicitly supports dry-run execution semantics.
+   *
+   * This is a declaration for governance, derivation, and surface tooling. It
+   * does not change runtime behavior by itself; the active invocation signal is
+   * `TrailContext.dryRun`.
+   */
+  readonly dryRun?: boolean | undefined;
+  /** Whether surfaces expose this trail by default. */
+  readonly visibility?: TrailVisibility | undefined;
+  /** Arbitrary meta for tooling and filtering */
+  readonly meta?: Readonly<Record<string, unknown>> | undefined;
+  /** Recovery paths activated when implementation fails with a matching error class. */
+  readonly detours?: readonly Detour<I, O, TrailsError>[] | undefined;
+  /**
+   * Typed layers attached at trail scope.
+   *
+   * Layers declared here wrap this trail's implementation on every execution,
+   * regardless of which surface invokes it. The execution pipeline composes
+   * trail-scope layers innermost — closer to the implementation than surface-scope
+   * or topo-scope layers — so the final order is
+   * `topo → surface → trail → implementation` (outermost-first).
+   *
+   * Layers are typed and inspectable. Omit `input` for surface-invisible
+   * wrappers that do not render any fields.
+   */
+  readonly layers?: readonly Layer[] | undefined;
+  /** Per-field overrides for deriveFields() (labels, hints, options) */
+  readonly fields?: Readonly<Record<string, FieldOverride>> | undefined;
+  /** CLI rendering metadata for canonical command path overrides and aliases. */
+  readonly cli?: CliCommandPathInput | TrailCliRendering | undefined;
+  /** Entities this trail operates on. */
+  readonly entities?: readonly AnyEntity[] | 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.compose()` calls,
+   * invisible to public surfaces (CLI, MCP, HTTP).
+   *
+   * Fields here are available in the implementation but are not derived into CLI flags,
+   * MCP tool parameters, or HTTP request bodies. Use for data that only makes
+   * sense when one trail composes another (e.g. `forkedFrom`).
+   */
+  readonly composeInput?: z.ZodType<CI> | undefined;
+  /** Resources this trail may access via resource.from(ctx) */
+  readonly resources?: readonly AnyResource[] | undefined;
+  /**
+   * Signals this trail fires via `ctx.fire()`.
+   *
+   * Accepts either a string id or a `Signal` value. Both forms are
+   * normalized to the signal's id at trail definition time, so
+   * `trail.fires` is always `readonly string[]`.
+   *
+   * Note: `composes` also accepts trail objects (normalized to IDs),
+   * following the same pattern as signal references here.
+   */
+  readonly fires?: readonly (string | AnySignal)[] | undefined;
+  /**
+   * Activation sources that can invoke this trail.
+   *
+   * Bare strings and `Signal` values are signal-source shorthand. Object form
+   * preserves the source kind and per-source metadata for the activation graph.
+   */
+  readonly on?:
+    | readonly (ActivationEntrySpec | ActivationSourceRef)[]
+    | undefined;
+  /** Auth requirement: scopes object, 'public', or omitted (undeclared) */
+  readonly permit?: PermitRequirement | undefined;
+  /** Primary input fields and their order. CLI derives 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 derived into the resolved graph, not authored. */
+  readonly marker?: never;
+}
+
+// ---------------------------------------------------------------------------
+// Trail (the frozen runtime object)
+// ---------------------------------------------------------------------------
+
+/** Intent describes what a trail does to the world. */
+export const intentValues = Object.freeze([
+  'read',
+  'write',
+  'destroy',
+] as const);
+
+export type Intent = (typeof intentValues)[number];
+
+/** Whether surfaces expose a trail by default. */
+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, readonly TrailRef[] | undefined>,
+  | 'args'
+  | 'implementation'
+  | 'entities'
+  | 'composes'
+  | 'composeInput'
+  | 'detours'
+  | 'fires'
+  | 'intent'
+  | 'layers'
+  | 'on'
+  | 'resources'
+> {
+  readonly kind: 'trail';
+  readonly id: string;
+  readonly implementation: Implementation<ImplementationInput<I, CI>, O>;
+  /** Entities this trail operates on (always present, default []). */
+  readonly entities: readonly AnyEntity[];
+  /** 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 implementation fails with a matching error (always present, default []). */
+  readonly detours: readonly Detour<I, O, TrailsError>[];
+  /**
+   * Typed layers attached at trail scope (always present, default []).
+   *
+   * Composed innermost in the layer chain — closest to the implementation. The final
+   * composition order is `topo → surface → trail → implementation` (outermost-first).
+   */
+  readonly layers: readonly Layer[];
+  /** Resources this trail may access via resource.from(ctx) (always present, default []) */
+  readonly resources: readonly AnyResource[];
+  /** IDs of signals this trail fires via ctx.fire() (always present, default []) */
+  readonly fires: readonly string[];
+  /**
+   * IDs of signal sources that activate this trail (always present, default []).
+   * Non-signal activation sources live in `activationSources`.
+   */
+  readonly on: readonly string[];
+  /** Normalized activation source entries declared through `on` (always present, default []). */
+  readonly activationSources: readonly ActivationEntry[];
+  /** What this trail does to the world (always present, default 'write') */
+  readonly intent: Intent;
+  /** Whether surfaces expose this trail by default (always present, default 'public'). */
+  readonly visibility: TrailVisibility;
+  /** Primary input fields and their order (always present, default undefined) */
+  readonly args?: readonly string[] | false | undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+const normalizeSignalRef = (entry: string | AnySignal): string => {
+  if (typeof entry === 'string') {
+    return entry;
+  }
+
+  const ref = getLateBoundSignalRef(entry);
+  if (!ref) {
+    return entry.id;
+  }
+
+  // Bound refs preserve an explicit resource choice. Authored refs always
+  // become markers, even when a table name contains the scope separator.
+  // Ownership is a contract fact; do not infer it from signal ID grammar.
+  if (isBoundLateBoundSignal(entry)) {
+    return entry.id;
+  }
+
+  return createLateBoundSignalMarker(ref, entry.id);
+};
+
+const freezeActivationSource = (source: ActivationSource): ActivationSource =>
+  Object.freeze({
+    ...source,
+    ...(source.meta === undefined
+      ? {}
+      : { meta: Object.freeze({ ...source.meta }) }),
+  });
+
+const shouldPreserveSignalSource = (source: ActivationSource): boolean =>
+  source.kind === 'signal' &&
+  (!('payload' in source) ||
+    'input' in source ||
+    'parse' in source ||
+    'cron' in source ||
+    'timezone' in source);
+
+const normalizeActivationSource = (
+  source: ActivationSourceRef
+): ActivationSource => {
+  if (typeof source === 'string') {
+    return freezeActivationSource({ id: source, kind: 'signal' });
+  }
+
+  if (isActivationSource(source) && shouldPreserveSignalSource(source)) {
+    return freezeActivationSource({
+      ...source,
+      id: normalizeSignalRef(source.id),
+      kind: 'signal',
+    });
+  }
+
+  if (isActivationSource(source) && source.kind !== 'signal') {
+    return freezeActivationSource(source);
+  }
+
+  return freezeActivationSource({
+    id: normalizeSignalRef(source as string | AnySignal),
+    kind: 'signal',
+  });
+};
+
+const normalizeActivationEntry = (
+  entry: ActivationEntrySpec | ActivationSourceRef
+): ActivationEntry => {
+  const source = isActivationEntrySpec(entry) ? entry.source : entry;
+  const normalized: ActivationEntry = {
+    source: normalizeActivationSource(source),
+    ...(isActivationEntrySpec(entry) && entry.meta !== undefined
+      ? { meta: Object.freeze({ ...entry.meta }) }
+      : {}),
+    ...(isActivationEntrySpec(entry) && entry.where !== undefined
+      ? { where: entry.where }
+      : {}),
+  };
+
+  return Object.freeze(normalized);
+};
+
+const normalizeActivationSources = (
+  entries: readonly (ActivationEntrySpec | ActivationSourceRef)[]
+): readonly ActivationEntry[] =>
+  Object.freeze(entries.map((entry) => normalizeActivationEntry(entry)));
+
+const extractSignalActivationIds = (
+  activations: readonly ActivationEntry[]
+): readonly string[] =>
+  Object.freeze(
+    activations
+      .filter((entry) => entry.source.kind === 'signal')
+      .map((entry) => entry.source.id)
+  );
+
+/** 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 derived`
+    );
+  }
+  if (hasOwn(raw, 'marker')) {
+    throw new ValidationError(
+      `Trail "${trailId}" version ${version} must not author marker; it is derived`
+    );
+  }
+
+  const hasImplementation = typeof raw['implementation'] === 'function';
+  const hasTranspose = raw['transpose'] !== undefined;
+  if (hasImplementation && hasTranspose) {
+    throw new ValidationError(
+      `Trail "${trailId}" version ${version} cannot declare both implementation 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 (hasImplementation) {
+    return Object.freeze({
+      ...base,
+      implementation: async (input: unknown, ctx: TrailContext) =>
+        await (raw['implementation'] 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,
+  C extends readonly TrailRef[] | undefined,
+>(
+  spec: TrailSpec<I, O, CI, C>
+): {
+  readonly args: readonly string[] | false | undefined;
+  readonly activationSources: readonly ActivationEntry[];
+  readonly entities: readonly AnyEntity[];
+  readonly detours: readonly Detour<I, O, TrailsError>[];
+  readonly fires: readonly string[];
+  readonly layers: readonly Layer[];
+  readonly on: readonly string[];
+  readonly resources: readonly AnyResource[];
+} => {
+  const activationSources = normalizeActivationSources(spec.on ?? []);
+  return {
+    activationSources,
+    args: Array.isArray(spec.args) ? Object.freeze([...spec.args]) : spec.args,
+    detours: Object.freeze([...(spec.detours ?? [])]),
+    entities: Object.freeze([...(spec.entities ?? [])]),
+    fires: Object.freeze((spec.fires ?? []).map(normalizeSignalRef)),
+    layers: Object.freeze([...(spec.layers ?? [])]),
+    on: extractSignalActivationIds(activationSources),
+    resources: Object.freeze([...(spec.resources ?? [])]),
+  };
+};
+
+/**
+ * Create a trail definition.
+ *
+ * Returns a frozen object with `kind: "trail"` and all spec fields.
+ * The trail is inert until handed to a runner.
+ *
+ * @example
+ * ```typescript
+ * // ID as first argument (recommended for human authoring)
+ * const show = trail("entity.show", {
+ *   input: z.object({ name: z.string() }),
+ *   implementation: (input) => Result.ok(entity),
+ * });
+ *
+ * // Full spec object (for programmatic generation)
+ * const show = trail({
+ *   id: "entity.show",
+ *   input: z.object({ name: z.string() }),
+ *   implementation: (input) => Result.ok(entity),
+ * });
+ * ```
+ */
+export function trail<
+  const TInputSchema extends z.ZodType,
+  const TOutputSchema extends z.ZodType,
+  const TComposeInputSchema extends z.ZodType | undefined = undefined,
+  const C extends readonly TrailRef[] | undefined = undefined,
+>(
+  id: string,
+  spec: SchemaOwnedOutputTrailSpec<
+    TInputSchema,
+    TOutputSchema,
+    TComposeInputSchema,
+    C
+  >
+): SchemaOwnedTrail<TInputSchema, z.output<TOutputSchema>, TComposeInputSchema>;
+export function trail<
+  const TInputSchema extends z.ZodType,
+  const TOutputSchema extends z.ZodType,
+  const TComposeInputSchema extends z.ZodType | undefined = undefined,
+  const C extends readonly TrailRef[] | undefined = undefined,
+>(
+  spec: SchemaOwnedOutputTrailSpec<
+    TInputSchema,
+    TOutputSchema,
+    TComposeInputSchema,
+    C
+  > & {
+    readonly id: string;
+  }
+): SchemaOwnedTrail<TInputSchema, z.output<TOutputSchema>, TComposeInputSchema>;
+export function trail<
+  const TInputSchema extends z.ZodType,
+  O,
+  const TComposeInputSchema extends z.ZodType | undefined = undefined,
+  const C extends readonly TrailRef[] | undefined = undefined,
+>(
+  id: string,
+  spec: SchemaOwnedTrailSpec<TInputSchema, O, TComposeInputSchema, C>
+): SchemaOwnedTrail<TInputSchema, O, TComposeInputSchema>;
+export function trail<
+  const TInputSchema extends z.ZodType,
+  O,
+  const TComposeInputSchema extends z.ZodType | undefined = undefined,
+  const C extends readonly TrailRef[] | undefined = undefined,
+>(
+  spec: SchemaOwnedTrailSpec<TInputSchema, O, TComposeInputSchema, C> & {
+    readonly id: string;
+  }
+): SchemaOwnedTrail<TInputSchema, O, TComposeInputSchema>;
+export function trail<
+  I,
+  O,
+  CI = never,
+  const C extends readonly TrailRef[] | undefined = undefined,
+>(
+  id: string,
+  spec:
+    | LegacyOutputTrailSpec<I, O, CI, C>
+    | LegacyOutputlessTrailSpec<I, O, CI, C>
+): Trail<I, O, CI>;
+export function trail<
+  I,
+  O,
+  CI = never,
+  const C extends readonly TrailRef[] | undefined = undefined,
+>(
+  spec:
+    | (LegacyOutputTrailSpec<I, O, CI, C> & { readonly id: string })
+    | (LegacyOutputlessTrailSpec<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'
+      ? { id: idOrSpec, spec: maybeSpec }
+      : { id: idOrSpec.id, spec: idOrSpec };
+
+  if (!resolved.spec) {
+    throw new TypeError('trail() requires a spec when an id is provided');
+  }
+  const rawSpec = resolved.spec as unknown as Record<string, unknown>;
+  if (hasOwn(rawSpec, 'contours')) {
+    throw new ValidationError(
+      `Trail "${resolved.id}" uses retired "contours"; use "entities" instead`
+    );
+  }
+
+  if (hasOwn(rawSpec, 'marker')) {
+    throw new ValidationError(
+      `Trail "${resolved.id}" must not author marker; it is derived`
+    );
+  }
+
+  const {
+    implementation,
+    composeInput,
+    composes: rawComposes,
+    intent: rawIntent,
+    visibility: rawVisibility,
+    // Destructure away fields handled by normalizeCollections
+    args: _a,
+    entities: _c,
+    detours: _d,
+    fires: _f,
+    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,
+    composeInput,
+    composes: Object.freeze((rawComposes ?? []).map(normalizeComposeRef)),
+    id: resolved.id,
+    implementation: async (
+      input: ImplementationInput<I, CI>,
+      ctx: TrailContext
+    ) => await implementation(input, ctx as ComposeContextFor<C>),
+    intent: rawIntent ?? 'write',
+    kind: 'trail' as const,
+    ...(rawVersion === undefined ? {} : { version: rawVersion }),
+    ...(versions === undefined ? {} : { versions }),
+    visibility: rawVisibility ?? 'public',
+  });
+}
+
+// Re-export types that callers of trail() will need
+// The Omit+override avoids a TypeScript limitation where ImplementationInput'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, never>,
+  'implementation' | 'composeInput'
+> & {
+  readonly implementation: Implementation<any, any>;
+  readonly composeInput?: z.ZodType<any> | undefined;
+};
+/* oxlint-enable no-explicit-any */
+
+export type { Implementation, TrailContext, Result };