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

package/src/fire.ts

@@ -23,7 +23,7 @@
  * `ctx.fire()` resolves after dispatch is initiated and without a value.
  * Unknown signals, invalid payloads, guard suppression, and consumer errors
  * are logged/diagnosed but do NOT propagate back to the producer. Consumers
- * that need transactional coupling should use `crosses:`.
+ * that need transactional coupling should use `composes:`.
  */
 
 import type { z } from 'zod';
@@ -617,7 +617,7 @@ const shouldInvokeConsumer = async (
  *
  * @remarks
  * Signal delivery is fire-and-forget notification, not ordered orchestration;
- * if one consumer depends on another, the dependency belongs in `crosses:`
+ * if one consumer depends on another, the dependency belongs in `composes:`
  * instead of sibling signal sequencing.
  *
  * `Promise.allSettled` preserves failure isolation for the background

package/src/index.ts

@@ -9,6 +9,7 @@ export {
   AmbiguousError,
   AssertionError,
   NotFoundError,
+  VersionNotSupportedError,
   AlreadyExistsError,
   ConflictError,
   PermissionError,
@@ -74,8 +75,9 @@ export type {
   Implementation,
   TrailContext,
   TrailContextInit,
-  CrossBatchOptions,
-  CrossFn,
+  ComposeBatchOptions,
+  ComposeOptions,
+  ComposeFn,
   FireFn,
   LogLevel,
   LogFormatter,
@@ -157,23 +159,77 @@ export {
   projectActivationSourceDeclaration,
 } from './activation-source-projection.js';
 export type { ActivationSourceProjection } from './activation-source-projection.js';
-export { intentValues, trail } from './trail.js';
+export {
+  deriveSupportedTrailVersions,
+  getTrailVersionEntryKind,
+  hasDeprecatedTrailVersionGuidance,
+  intentValues,
+  isArchivedTrailVersionEntry,
+  isDeprecatedTrailVersionEntry,
+  isLiveTrailVersionEntry,
+  trail,
+} from './trail.js';
+export {
+  TRAIL_VERSION_MARKER_LENGTH,
+  TRAIL_VERSION_MARKER_MIN_PREFIX_LENGTH,
+  assertTrailVersionMarker,
+  assertUniqueTrailVersionMarkers,
+  canonicalizeTrailVersionMarkerContent,
+  deriveCurrentTrailVersionMarker,
+  deriveCurrentTrailVersionMarkerContent,
+  deriveShortestUnambiguousTrailVersionMarkerPrefix,
+  deriveTrailVersionEntryMarker,
+  deriveTrailVersionEntryMarkerContent,
+  deriveTrailVersionMarker,
+  deriveTrailVersionMarkers,
+  normalizeTrailVersionMarkerPrefix,
+  resolveTrailVersionMarkerPrefix,
+} from './version-marker.js';
+export {
+  parseTrailIdVersionReference,
+  resolveTrailVersion,
+} from './version-resolution.js';
 export type {
   AnyTrail,
   BlazeInput,
   Intent,
   Trail,
+  TrailVersionEntry,
+  TrailVersionEntryKind,
+  TrailVersionArchivedStatus,
+  TrailVersionDeprecatedStatus,
+  TrailVersionForkEntry,
+  TrailVersionRevisionEntry,
+  TrailVersions,
+  TrailVersionStatus,
+  TrailVersionTranspose,
+  TrailVersionTransposeInput,
+  TrailVersionTransposeOutput,
   TrailSpec,
   TrailExample,
   TrailExampleSignalAssertion,
   TrailVisibility,
+  VersionContract,
+  VersionEntry,
 } from './trail.js';
+export type {
+  TrailVersionMarkerBinding,
+  TrailVersionMarkerRecord,
+  TrailVersionMarkerResolution,
+} from './version-marker.js';
+export type {
+  ParsedTrailVersionReference,
+  ResolvedTrailVersion,
+  TrailVersionReference,
+} from './version-resolution.js';
 export {
   filterSurfaceTrails,
   matchesTrailPattern,
   shouldIncludeTrailForSurface,
 } from './surface-filter.js';
 export type { SurfaceFilterOptions } from './surface-filter.js';
+export { deriveSurfaceTrailVersionProjections } from './surface-versioning.js';
+export type { SurfaceTrailVersionProjection } from './surface-versioning.js';
 export {
   shouldValidateSurfaceTopo,
   validateSurfaceTopo,
@@ -202,7 +258,7 @@ export type {
 
 // Type utilities
 export type {
-  CrossInput,
+  ComposeInput,
   TrailInput,
   TrailOutput,
   TrailResult,
@@ -388,13 +444,13 @@ export type {
 export { deriveCliPath, deriveFields } from './derive.js';
 export type { Field, FieldOverride } from './derive.js';
 
-// Cross schema
-export { buildCrossValidationSchema } from './cross-schema.js';
+// Compose schema
+export { buildComposeValidationSchema } from './compose-schema.js';
 export {
-  claimNextCrossBatchIndex,
-  createCrossBatchValidationResults,
-  normalizeCrossBatchConcurrency,
-} from './cross-batch.js';
+  claimNextComposeBatchIndex,
+  createComposeBatchValidationResults,
+  normalizeComposeBatchConcurrency,
+} from './compose-batch.js';
 
 // Execute
 export { DETOUR_MAX_ATTEMPTS_CAP } from './detours.js';

package/src/internal/fork-ctx.ts

@@ -2,7 +2,7 @@
  * Internal helper for "forking" a trail context.
  *
  * Several execution sites need to derive a child context from a parent
- * context while **resetting** a well-known set of bound closures (`cross`,
+ * context while **resetting** a well-known set of bound closures (`compose`,
  * `fire`, `resource`). Those closures capture the parent scope, so reusing
  * them on the child would re-enter execution with the wrong attribution,
  * the wrong resource scope, or the wrong fan-out identity. The reset list
@@ -24,7 +24,7 @@
 import type { TrailContext, TrailContextInit } from '../types.js';
 
 /** Keys cleared by default when forking a context. */
-export type ForkCtxResetKey = 'cross' | 'fire' | 'resource';
+export type ForkCtxResetKey = 'compose' | 'fire' | 'resource';
 
 /** Override fields callers are allowed to apply when forking a context. */
 export type ForkCtxOverrides = Readonly<
@@ -32,7 +32,7 @@ export type ForkCtxOverrides = Readonly<
 >;
 
 const DEFAULT_RESET_KEYS: readonly ForkCtxResetKey[] = [
-  'cross',
+  'compose',
   'fire',
   'resource',
 ];
@@ -53,7 +53,7 @@ export const forkCtx = <
   TCtx extends Partial<
     Pick<
       TrailContextInit,
-      'cross' | 'env' | 'extensions' | 'fire' | 'logger' | 'resource'
+      'compose' | 'env' | 'extensions' | 'fire' | 'logger' | 'resource'
     >
   >,
 >(

package/src/layer-projection.ts

@@ -38,6 +38,7 @@ export const LAYER_FIELD_RESERVED_NAMES: ReadonlySet<string> = new Set([
   'permit',
   'quiet',
   'token',
+  'trailVersion',
   'trace',
   'watch',
 ]);

package/src/layer.ts

@@ -8,7 +8,7 @@ import type { Implementation } from './types.js';
 // ---------------------------------------------------------------------------
 
 /**
- * A composable, named layer that wraps trail implementations.
+ * A composable, named layer that wraps blazes.
  *
  * Layers attach at trail, surface, or topo scope and may declare an object
  * `input` schema describing the configuration they need from the surrounding

package/src/observe.ts

@@ -128,7 +128,7 @@ export const isObserveInput = (
   }
   if (isTraceSink(value) && !isLogSink(value)) {
     // A bare TraceSink (no `name`) is unambiguous — `normalizeObserve`
-    // routes it via the `isTraceSink` fallthrough. A LogSink shape is
+    // accepts it via the `isTraceSink` fallthrough. A LogSink shape is
     // ambiguous (matches both guards) and would be rejected by
     // `normalizeObserve`, so the guard rejects it here too.
     return true;
@@ -148,7 +148,7 @@ export const hasObserveCapabilities = (value: unknown): boolean =>
 /**
  * Returns true when `value` is shaped like the explicit `{ log?, trace? }`
  * `ObserveConfig` payload. Exposed for the topo classifier so a config-style
- * trailing argument is unambiguously routed to options.
+ * trailing argument is unambiguously classified as options.
  */
 export const isObserveConfig = (value: unknown): value is ObserveConfig =>
   isObserveConfigShape(value);
@@ -212,15 +212,15 @@ const stringifyDefaultConsoleRecord = (record: LogRecord): string => {
 /**
  * In-core mirror of `@ontrails/observe`'s `createConsoleSink` shape, kept
  * minimal and private to avoid a reverse dependency from `@ontrails/core`
- * onto `@ontrails/observe`. It mirrors the console level routing in
+ * onto `@ontrails/observe`. It mirrors the console level mapping in
  * `packages/observe/src/sinks.ts:50` and emits each record as a single-line
- * JSON object routed to the matching `console.{debug|info|warn|error}` method.
+ * JSON object written to the matching `console.{debug|info|warn|error}` method.
  *
  * @remarks
  * Used as the default `observe.log` target when `topo()` is called without an
  * explicit `observe` option, so every app gets a non-null `ctx.logger` with
  * structured stdout output and zero configuration. Apps that want richer
- * formatting, file destinations, or custom routing should pass an explicit
+ * formatting, file destinations, or custom sink behavior should pass an explicit
  * `observe` option, which fully replaces this default.
  */
 const createDefaultConsoleSink = (): LogSink => ({

package/src/resource.ts

@@ -54,10 +54,19 @@ export interface ResourceSpec<T, C = unknown> {
   readonly meta?: Readonly<Record<string, unknown>> | undefined;
   /** Signals projected or owned by this resource. */
   readonly signals?: readonly AnySignal[] | undefined;
+  /** Reserved for future resource-specific design; trail versioning is trail-only. */
+  readonly version?: never;
 }
 
+type ResourceSpecWithConfig<T, S extends z.ZodTypeAny> = Omit<
+  ResourceSpec<T, z.infer<S>>,
+  'config'
+> & {
+  readonly config: S;
+};
+
 /** A typed resource definition. */
-export interface Resource<T> extends ResourceSpec<T> {
+export interface Resource<T, C = unknown> extends ResourceSpec<T, C> {
   readonly kind: 'resource';
   readonly id: string;
   /** Read the resolved resource instance from a trail context. */
@@ -72,7 +81,7 @@ export interface Resource<T> extends ResourceSpec<T> {
  * existential here.
  */
 // oxlint-disable-next-line no-explicit-any -- existential type for heterogeneous resource collections
-export type AnyResource = Resource<any>;
+export type AnyResource = Resource<any, any>;
 
 /** Explicit runtime overrides keyed by resource ID. */
 export type ResourceOverrideMap = Readonly<Record<string, unknown>>;
@@ -114,37 +123,47 @@ export const createResourceLookup = (
  * The resource object is inert until a later execution branch resolves concrete
  * instances into TrailContext extensions.
  */
-export const resource = <T>(id: string, spec: ResourceSpec<T>): Resource<T> =>
-  (() => {
-    if (id.includes(':')) {
-      throw new InternalError(
-        `Resource "${id}" is invalid because resource ids may not contain ":"`
-      );
-    }
-    if (spec.mock !== undefined && spec.unmockable !== undefined) {
-      throw new InternalError(
-        `Resource "${id}" cannot define both mock and unmockable`
-      );
-    }
-    if (
-      spec.unmockable !== undefined &&
-      spec.unmockable.reason.trim().length === 0
-    ) {
-      throw new InternalError(
-        `Resource "${id}" is invalid because unmockable.reason must not be empty`
-      );
-    }
+export function resource<T, S extends z.ZodTypeAny>(
+  id: string,
+  spec: ResourceSpecWithConfig<T, S>
+): Resource<T, z.infer<S>>;
+export function resource<T, C = unknown>(
+  id: string,
+  spec: ResourceSpec<T, C>
+): Resource<T, C>;
+export function resource<T, C = unknown>(
+  id: string,
+  spec: ResourceSpec<T, C>
+): Resource<T, C> {
+  if (id.includes(':')) {
+    throw new InternalError(
+      `Resource "${id}" is invalid because resource ids may not contain ":"`
+    );
+  }
+  if (spec.mock !== undefined && spec.unmockable !== undefined) {
+    throw new InternalError(
+      `Resource "${id}" cannot define both mock and unmockable`
+    );
+  }
+  if (
+    spec.unmockable !== undefined &&
+    spec.unmockable.reason.trim().length === 0
+  ) {
+    throw new InternalError(
+      `Resource "${id}" is invalid because unmockable.reason must not be empty`
+    );
+  }
 
-    return Object.freeze({
-      ...spec,
-      from(ctx: TrailContext): T {
-        const lookup = ctx.resource ?? createResourceLookup(() => ctx);
-        return lookup(this);
-      },
-      id,
-      kind: 'resource' as const,
-    });
-  })();
+  return Object.freeze({
+    ...spec,
+    from(ctx: TrailContext): T {
+      const lookup = ctx.resource ?? createResourceLookup(() => ctx);
+      return lookup(this);
+    },
+    id,
+    kind: 'resource' as const,
+  });
+}
 
 /** Narrow unknown values to resource definitions during topo discovery. */
 export const isResource = (value: unknown): value is AnyResource => {

package/src/run.ts

@@ -8,7 +8,8 @@
 import type { Topo } from './topo.js';
 import { executeTrail } from './execute.js';
 import type { ExecuteTrailOptions } from './execute.js';
-import { NotFoundError } from './errors.js';
+import { parseTrailIdVersionReference } from './version-resolution.js';
+import { NotFoundError, ValidationError } from './errors.js';
 import { Result } from './result.js';
 
 // ---------------------------------------------------------------------------
@@ -43,7 +44,21 @@ export const run = (
   input: unknown,
   options?: RunOptions
 ): Promise<Result<unknown, Error>> => {
-  const trail = topo.get(id);
+  const parsed = parseTrailIdVersionReference(id);
+  if (parsed.isErr()) {
+    return Promise.resolve(Result.err(parsed.error));
+  }
+  if (parsed.value.version !== undefined && options?.version !== undefined) {
+    return Promise.resolve(
+      Result.err(
+        new ValidationError(
+          `Trail "${parsed.value.id}" cannot combine an @version suffix with options.version`
+        )
+      )
+    );
+  }
+
+  const trail = topo.get(parsed.value.id);
   if (trail === undefined) {
     return Promise.resolve(
       Result.err(
@@ -51,5 +66,11 @@ export const run = (
       )
     );
   }
-  return executeTrail(trail, input, { ...options, topo });
+  return executeTrail(trail, input, {
+    ...options,
+    ...(parsed.value.version === undefined
+      ? {}
+      : { version: parsed.value.version }),
+    topo,
+  });
 };

package/src/schedule.ts

@@ -11,6 +11,8 @@ export interface ScheduleSpec<TInput = unknown> {
   readonly input?: TInput | undefined;
   readonly meta?: ActivationSourceMeta | undefined;
   readonly timezone?: string | undefined;
+  /** Reserved for future schedule-specific design; trail versioning is trail-only. */
+  readonly version?: never;
 }
 
 export interface ScheduleSource<TInput = unknown> extends ActivationSource {

package/src/signal.ts

@@ -39,6 +39,8 @@ export interface SignalSpec<T> {
   readonly meta?: Readonly<Record<string, unknown>> | undefined;
   /** Trail IDs that produce this signal (e.g. the trails it originates from). */
   readonly from?: readonly string[] | undefined;
+  /** Reserved for future signal-specific design; trail versioning is trail-only. */
+  readonly version?: never;
 }
 
 // ---------------------------------------------------------------------------

package/src/structured-examples.ts

@@ -1,7 +1,7 @@
 import type { TrailExample, TrailExampleSignalAssertion } from './trail.js';
 
 export interface StructuredTrailExampleProvenance {
-  readonly source: 'trail.examples';
+  readonly source: 'trail.examples' | 'trail.versions.examples';
 }
 
 export interface StructuredSignalExampleProvenance {
@@ -152,7 +152,8 @@ const projectSignalAssertions = (
 };
 
 const projectExample = (
-  example: TrailExample<unknown, unknown>
+  example: TrailExample<unknown, unknown>,
+  provenance: StructuredTrailExampleProvenance
 ): StructuredTrailExample | undefined => {
   const input = toJsonSerializable(example.input);
   if (input === undefined) {
@@ -163,7 +164,7 @@ const projectExample = (
     input,
     kind: example.error === undefined ? 'success' : 'error',
     name: example.name,
-    provenance: { source: 'trail.examples' },
+    provenance,
   };
 
   if (example.description !== undefined) {
@@ -213,14 +214,16 @@ const projectSignalExample = (
 };
 
 export const deriveStructuredTrailExamples = (
-  examples: readonly TrailExample<unknown, unknown>[] | undefined
+  examples: readonly TrailExample<unknown, unknown>[] | undefined,
+  options?: { readonly provenance?: StructuredTrailExampleProvenance }
 ): readonly StructuredTrailExample[] | undefined => {
   if (examples === undefined || examples.length === 0) {
     return undefined;
   }
 
+  const provenance = options?.provenance ?? { source: 'trail.examples' };
   const projected = examples
-    .map(projectExample)
+    .map((example) => projectExample(example, provenance))
     .filter(
       (example): example is StructuredTrailExample => example !== undefined
     );

package/src/surface-versioning.ts

@@ -0,0 +1,42 @@
+import type { AnyTrail, TrailVersionStatus } from './trail.js';
+import {
+  deriveSupportedTrailVersions,
+  isDeprecatedTrailVersionEntry,
+} from './trail.js';
+import { deriveTrailVersionMarkers } from './version-marker.js';
+
+export interface SurfaceTrailVersionProjection {
+  readonly current: boolean;
+  readonly deprecated: boolean;
+  readonly marker?: string | undefined;
+  readonly status?: TrailVersionStatus | undefined;
+  readonly version: number;
+}
+
+export const deriveSurfaceTrailVersionProjections = (
+  trail: AnyTrail
+): readonly SurfaceTrailVersionProjection[] | undefined => {
+  if (trail.version === undefined) {
+    return undefined;
+  }
+
+  const markers = new Map(
+    deriveTrailVersionMarkers(trail).map((record) => [
+      record.version,
+      record.marker,
+    ])
+  );
+
+  return deriveSupportedTrailVersions(trail).map((version) => {
+    const entry = trail.versions?.[version];
+    const marker = markers.get(version);
+    return {
+      current: version === trail.version,
+      deprecated:
+        entry === undefined ? false : isDeprecatedTrailVersionEntry(entry),
+      ...(marker === undefined ? {} : { marker }),
+      ...(entry?.status === undefined ? {} : { status: entry.status }),
+      version,
+    };
+  });
+};

package/src/topo.ts

@@ -578,7 +578,7 @@ const disambiguateBrandedObserve = (options: TopoOptions): TopoOptions => {
  *   1. Branded via `topo.options()` → always options. Unknown option
  *      keys throw, and downstream `normalizeObserve` rejects malformed
  *      values. A bare `LogSink` (`{ name, write }`) in the `observe`
- *      slot is auto-routed to `{ log: sink }` so the brand is the
+ *      slot is auto-wrapped as `{ log: sink }` so the brand is the
  *      complete escape hatch the docs promise.
  *   2. The shape does not look like `TopoOptions` (mixed keys or no
  *      keys) → module.
@@ -621,11 +621,11 @@ const classifyTrailingArgument = (
       };
     }
     // Branding via `topo.options()` is the documented escape hatch for
-    // disambiguating bare-sink shorthand. Route a bare `LogSink` into the
+    // disambiguating bare-sink shorthand. Wrap a bare `LogSink` in the
     // explicit `{ log: sink }` slot before handing off to `normalizeObserve`,
     // which would otherwise reject it as ambiguous (a LogSink shape matches
     // both `isLogSink` and `isTraceSink`). A bare TraceSink (no `name`) does
-    // not need rewriting because `normalizeObserve` already routes it via
+    // not need rewriting because `normalizeObserve` already accepts it via
     // the `isTraceSink` fallthrough.
     return {
       kind: 'options',