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

package/src/type-utils.ts

@@ -3,7 +3,9 @@
  */
 
 import type { Result } from './result.js';
-import type { AnyTrail, Trail } from './trail.js';
+import type { AnyTrail } from './trail.js';
+import type { Implementation } from './types.js';
+import type { z } from 'zod';
 
 // ---------------------------------------------------------------------------
 // Utility types
@@ -12,27 +14,33 @@ import type { AnyTrail, Trail } from './trail.js';
 /* oxlint-disable no-explicit-any -- `any` required for conditional type inference; `unknown` breaks inference */
 
 /** Extract the input type from a Trail. */
-export type TrailInput<T extends AnyTrail> =
-  T extends Trail<infer I, any, any> ? I : never;
+export type TrailInput<T extends AnyTrail> = T extends {
+  readonly input: z.ZodType<infer I>;
+}
+  ? I
+  : never;
 
 /** Extract the output type from a Trail. */
-export type TrailOutput<T extends AnyTrail> =
-  T extends Trail<any, infer O, any> ? O : never;
+export type TrailOutput<T extends AnyTrail> = T extends {
+  readonly blaze: Implementation<any, infer O>;
+}
+  ? O
+  : never;
 
 /**
- * Extract the cross-callable input type from a trail.
+ * Extract the compose-callable input type from a trail.
  *
- * When a trail declares `crossInput`, callers via `ctx.cross()` must pass
+ * When a trail declares `composeInput`, callers via `ctx.compose()` must pass
  * both the public input fields and the composition-only fields. This type
  * merges both schemas so the compiler enforces the full shape at the call
- * site. Falls back to plain `TrailInput<T>` when no `crossInput` exists.
+ * site. Falls back to plain `TrailInput<T>` when no `composeInput` exists.
  */
-export type CrossInput<T extends AnyTrail> =
-  T extends Trail<infer I, any, infer CI>
+export type ComposeInput<T extends AnyTrail> =
+  NonNullable<T['composeInput']> extends z.ZodType<infer CI>
     ? [CI] extends [never]
-      ? I
-      : I & CI
-    : never;
+      ? TrailInput<T>
+      : TrailInput<T> & CI
+    : TrailInput<T>;
 
 /**
  * Extracts the full `Result<Output, Error>` type from a trail definition.

package/src/types.ts

@@ -3,8 +3,9 @@ import type { BasePermit } from './permits.js';
 import type { Result } from './result.js';
 import type { Signal } from './signal.js';
 import type { AnyTrail } from './trail.js';
-import type { CrossInput, TrailOutput } from './type-utils.js';
+import type { ComposeInput, TrailOutput } from './type-utils.js';
 import type { ActivationProvenance } from './activation-provenance.js';
+import type { TrailVersionReference } from './version-resolution.js';
 
 // ---------------------------------------------------------------------------
 // Detour
@@ -31,29 +32,29 @@ export interface DetourAttempt<Input, TErr extends TrailsError = TrailsError> {
   readonly input: Input;
 }
 
-type CrossBatchCall<TTarget extends AnyTrail | string = AnyTrail | string> =
+type ComposeBatchCall<TTarget extends AnyTrail | string = AnyTrail | string> =
   TTarget extends AnyTrail
-    ? readonly [trail: TTarget, input: CrossInput<TTarget>]
+    ? readonly [trail: TTarget, input: ComposeInput<TTarget>]
     : readonly [id: string, input: unknown];
 
-type CrossBatchResult<TTarget extends AnyTrail | string> =
+type ComposeBatchResult<TTarget extends AnyTrail | string> =
   TTarget extends AnyTrail
     ? Result<TrailOutput<TTarget>, Error>
     : Result<unknown, Error>;
 
-type CrossBatchResults<TCalls extends readonly CrossBatchCall[]> = {
+type ComposeBatchResults<TCalls extends readonly ComposeBatchCall[]> = {
   readonly [K in keyof TCalls]: TCalls[K] extends readonly [
     infer TTarget,
     unknown,
   ]
     ? TTarget extends AnyTrail | string
-      ? CrossBatchResult<TTarget>
+      ? ComposeBatchResult<TTarget>
       : never
     : never;
 };
 
-/** Runtime options for batch `ctx.cross([...])` calls. */
-export interface CrossBatchOptions {
+/** Runtime options for batch `ctx.compose([...])` calls. */
+export interface ComposeBatchOptions {
   /**
    * Maximum number of branches to execute concurrently.
    *
@@ -62,15 +63,26 @@ export interface CrossBatchOptions {
   readonly concurrency?: number | undefined;
 }
 
+/** Runtime options for a single `ctx.compose(trail, input, options)` call. */
+export interface ComposeOptions {
+  /**
+   * Execute a specific live version of the composed trail.
+   *
+   * Omit to keep composition current by default. Historical revision entries
+   * transpose through the current trail; fork entries run their own blaze.
+   */
+  readonly version?: TrailVersionReference | undefined;
+}
+
 /**
  * Trail implementation — sync or async.
  *
  * Authors can return `Result` directly or wrap it in a `Promise`. The framework
  * normalizes with `await` at every call site, so both forms work transparently.
  */
-export type Implementation<I, O> = (
+export type Implementation<I, O, Ctx extends TrailContext = TrailContext> = (
   input: I,
-  ctx: TrailContext
+  ctx: Ctx
 ) => Result<O, Error> | Promise<Result<O, Error>>;
 
 /**
@@ -78,26 +90,31 @@ export type Implementation<I, O> = (
  *
  * Two call shapes:
  *
- * - **By trail object** (typed): `ctx.cross(showGist, { id })` — the compiler
+ * - **By trail object** (typed): `ctx.compose(showGist, { id })` — the compiler
  *   infers `I` and `O` from the trail's schemas, so the result is fully typed.
- * - **By string id** (untyped escape hatch): `ctx.cross('gist.show', { id })`
+ * - **By string id** (untyped escape hatch): `ctx.compose('gist.show', { id })`
  *   — returns `Result<O, Error>` where `O` defaults to `unknown`.
- * - **By batch**: `ctx.cross([[showGist, { id }], ['audit.log', payload]])`
- *   — executes every crossing concurrently and resolves once all results are
+ * - **By batch**: `ctx.compose([[showGist, { id }], ['audit.log', payload]])`
+ *   — executes every composing concurrently and resolves once all results are
  *   available. Result ordering always matches the input tuple ordering. Pass
  *   `{ concurrency: N }` as the second argument to limit how many branches
  *   run at once.
  */
-export interface CrossFn {
-  <const TCalls extends readonly CrossBatchCall[]>(
+export interface ComposeFn {
+  <const TCalls extends readonly ComposeBatchCall[]>(
     calls: TCalls,
-    options?: CrossBatchOptions
-  ): Promise<CrossBatchResults<TCalls>>;
+    options?: ComposeBatchOptions
+  ): Promise<ComposeBatchResults<TCalls>>;
   <T extends AnyTrail>(
     trail: T,
-    input: CrossInput<T>
+    input: ComposeInput<T>,
+    options?: ComposeOptions
   ): Promise<Result<TrailOutput<T>, Error>>;
-  <O = unknown>(id: string, input: unknown): Promise<Result<O, Error>>;
+  <O = unknown>(
+    id: string,
+    input: unknown,
+    options?: ComposeOptions
+  ): Promise<Result<O, Error>>;
 }
 
 /**
@@ -213,7 +230,7 @@ export interface TrailContext {
   readonly activation?: ActivationProvenance | undefined;
   readonly requestId: string;
   readonly abortSignal: AbortSignal;
-  readonly cross?: CrossFn | undefined;
+  readonly compose?: ComposeFn | undefined;
   /**
    * Emit a typed signal. Fans out to every trail with the signal in its
    * `on:` declaration. Bound by the runner that holds the topo (typically
@@ -260,6 +277,11 @@ export interface TrailContext {
   readonly trace?: TraceFn | undefined;
 }
 
+/** Trail context for blazes that declare trail composition. */
+export interface ComposeTrailContext extends TrailContext {
+  readonly compose: ComposeFn;
+}
+
 /**
  * Permit requirement declared on a trail spec.
  *

package/src/validate-established-topo.ts

@@ -6,9 +6,9 @@ import type { TopoIssue } from './validate-topo.js';
 import { validateTopo } from './validate-topo.js';
 
 const PROJECTION_BLOCKING_RULES = new Set([
-  'cross-cycle',
-  'cross-exists',
-  'no-self-cross',
+  'compose-cycle',
+  'compose-exists',
+  'no-self-compose',
   'activation-source-definition-unique',
   'activation-source-edge-unique',
   'activation-source-kind-known',

package/src/validate-topo.ts

@@ -1,7 +1,7 @@
 /**
  * Structural validation for a Topo graph.
  *
- * Checks trail crossing references, example input validity, signal origin
+ * Checks trail composing references, example input validity, signal origin
  * references, activation source kinds, and output schema completeness. Returns
  * a Result with all issues collected into a single ValidationError.
  */
@@ -22,7 +22,11 @@ import type { AnySignal } from './signal.js';
 import { validateScheduleSource } from './schedule.js';
 import { Result } from './result.js';
 import type { Topo } from './topo.js';
-import type { AnyTrail } from './trail.js';
+import type { AnyTrail, TrailVersionForkEntry } from './trail.js';
+import {
+  getTrailVersionEntryKind,
+  isArchivedTrailVersionEntry,
+} from './trail.js';
 import { validateInput } from './validation.js';
 import { validateWebhookSource } from './webhook.js';
 
@@ -50,17 +54,32 @@ const WHITE = 0;
 const GRAY = 1;
 const BLACK = 2;
 
-/** Build an adjacency list and initial color map from trails with crossings. */
-const buildCrossGraph = (
+/** Build an adjacency list and initial color map from trails with compositions. */
+const buildComposeGraph = (
   trails: ReadonlyMap<string, AnyTrail>
 ): {
   graph: Map<string, readonly string[]>;
   color: Map<string, number>;
 } => {
   const graph = new Map<string, readonly string[]>();
-  for (const [id, t] of trails) {
-    if (t.crosses.length > 0) {
-      graph.set(id, t.crosses);
+  for (const [id, trail] of trails) {
+    const composedIds = new Set<string>(trail.composes);
+    for (const entry of Object.values(trail.versions ?? {})) {
+      if (
+        isArchivedTrailVersionEntry(entry) ||
+        getTrailVersionEntryKind(entry) !== 'fork'
+      ) {
+        continue;
+      }
+
+      const fork = entry as TrailVersionForkEntry;
+      for (const composed of fork.composes ?? []) {
+        composedIds.add(typeof composed === 'string' ? composed : composed.id);
+      }
+    }
+
+    if (composedIds.size > 0) {
+      graph.set(id, [...composedIds]);
     }
   }
   const color = new Map<string, number>();
@@ -70,12 +89,12 @@ const buildCrossGraph = (
   return { color, graph };
 };
 
-/** Detect multi-node cycles in the trail crossing graph via DFS. */
-const detectCrossCycles = (
+/** Detect multi-node cycles in the trail composing graph via DFS. */
+const detectComposeCycles = (
   trails: ReadonlyMap<string, AnyTrail>
 ): TopoIssue[] => {
   const issues: TopoIssue[] = [];
-  const { color, graph } = buildCrossGraph(trails);
+  const { color, graph } = buildComposeGraph(trails);
 
   const dfs = (node: string, path: string[]): void => {
     color.set(node, GRAY);
@@ -88,7 +107,7 @@ const detectCrossCycles = (
         const cycle = [...path.slice(path.indexOf(next)), next];
         issues.push({
           message: `Cycle detected: ${cycle.join(' → ')}`,
-          rule: 'cross-cycle',
+          rule: 'compose-cycle',
           trailId: next,
         });
       } else if (c === WHITE) {
@@ -106,29 +125,57 @@ const detectCrossCycles = (
   return issues;
 };
 
-const checkCrosses = (
+const checkComposes = (
   trails: ReadonlyMap<string, AnyTrail>,
   topo: Topo
 ): TopoIssue[] => {
   const issues: TopoIssue[] = [];
   for (const [id, trail] of trails) {
-    for (const crossedId of trail.crosses) {
-      if (crossedId === id) {
+    for (const composedId of trail.composes) {
+      if (composedId === id) {
         issues.push({
-          message: `Trail crosses itself`,
-          rule: 'no-self-cross',
+          message: `Trail composes itself`,
+          rule: 'no-self-compose',
           trailId: id,
         });
-      } else if (!topo.has(crossedId) && !isDraftId(crossedId)) {
+      } else if (!topo.has(composedId) && !isDraftId(composedId)) {
         issues.push({
-          message: `Crosses "${crossedId}" which is not in the topo`,
-          rule: 'cross-exists',
+          message: `Composes "${composedId}" which is not in the topo`,
+          rule: 'compose-exists',
           trailId: id,
         });
       }
     }
+    for (const [rawVersion, entry] of Object.entries(trail.versions ?? {})) {
+      if (
+        isArchivedTrailVersionEntry(entry) ||
+        getTrailVersionEntryKind(entry) !== 'fork'
+      ) {
+        continue;
+      }
+
+      const version = Number(rawVersion);
+      const fork = entry as TrailVersionForkEntry;
+      for (const composed of fork.composes ?? []) {
+        const composedId =
+          typeof composed === 'string' ? composed : composed.id;
+        if (composedId === id) {
+          issues.push({
+            message: `Trail version ${version} composes itself`,
+            rule: 'no-self-compose',
+            trailId: id,
+          });
+        } else if (!topo.has(composedId) && !isDraftId(composedId)) {
+          issues.push({
+            message: `Version ${version} composes "${composedId}" which is not in the topo`,
+            rule: 'compose-exists',
+            trailId: id,
+          });
+        }
+      }
+    }
   }
-  issues.push(...detectCrossCycles(trails));
+  issues.push(...detectComposeCycles(trails));
   return issues;
 };
 
@@ -151,6 +198,29 @@ const checkResources = (
         });
       }
     }
+    for (const [rawVersion, entry] of Object.entries(trail.versions ?? {})) {
+      if (
+        isArchivedTrailVersionEntry(entry) ||
+        getTrailVersionEntryKind(entry) !== 'fork'
+      ) {
+        continue;
+      }
+
+      const version = Number(rawVersion);
+      const fork = entry as TrailVersionForkEntry;
+      for (const declaredResource of fork.resources ?? []) {
+        if (
+          !topo.hasResource(declaredResource.id) &&
+          !isDraftId(declaredResource.id)
+        ) {
+          issues.push({
+            message: `Version ${version} resource "${declaredResource.id}" is not in the topo`,
+            rule: 'resource-exists',
+            trailId: id,
+          });
+        }
+      }
+    }
   }
 
   return issues;
@@ -165,20 +235,21 @@ const checkOneExample = (
     error?: string | undefined;
   },
   inputSchema: { safeParse: (data: unknown) => { success: boolean } },
-  hasOutput: boolean
+  hasOutput: boolean,
+  label = `Example "${example.name}"`
 ): TopoIssue[] => {
   const issues: TopoIssue[] = [];
   const result = validateInput(inputSchema as AnyTrail['input'], example.input);
   if (result.isErr() && example.error !== 'ValidationError') {
     issues.push({
-      message: `Example "${example.name}" input does not parse against schema`,
+      message: `${label} input does not parse against schema`,
       rule: 'example-input-valid',
       trailId: id,
     });
   }
   if (example.expected !== undefined && !hasOutput) {
     issues.push({
-      message: `Example "${example.name}" has expected output but trail has no output schema`,
+      message: `${label} has expected output but trail has no output schema`,
       rule: 'output-schema-present',
       trailId: id,
     });
@@ -186,15 +257,34 @@ const checkOneExample = (
   return issues;
 };
 
+const checkVersionExamples = (id: string, trail: AnyTrail): TopoIssue[] =>
+  Object.entries(trail.versions ?? {}).flatMap(([version, entry]) => {
+    if (isArchivedTrailVersionEntry(entry)) {
+      return [];
+    }
+
+    return (entry.examples ?? []).flatMap((example) =>
+      checkOneExample(
+        id,
+        example,
+        entry.input,
+        true,
+        `Example "${example.name}" on version ${version}`
+      )
+    );
+  });
+
 const checkExamples = (trails: ReadonlyMap<string, AnyTrail>): TopoIssue[] => {
   const issues: TopoIssue[] = [];
   for (const [id, trail] of trails) {
-    if (!trail.examples) {
-      continue;
-    }
-    for (const example of trail.examples) {
-      issues.push(...checkOneExample(id, example, trail.input, !!trail.output));
+    if (trail.examples) {
+      for (const example of trail.examples) {
+        issues.push(
+          ...checkOneExample(id, example, trail.input, !!trail.output)
+        );
+      }
     }
+    issues.push(...checkVersionExamples(id, trail));
   }
   return issues;
 };
@@ -436,14 +526,14 @@ const checkContourReferences = (
 /**
  * Validate the structural integrity of a Topo graph.
  *
- * Checks crossing references, example inputs, signal origins, activation
+ * Checks composing references, example inputs, signal origins, activation
  * source kinds, and output schema presence. Returns `Result.ok()` when no
  * issues are found, or
  * `Result.err(ValidationError)` with all issues in the error context.
  */
 export const validateTopo = (topo: Topo): Result<void, ValidationError> => {
   const issues = [
-    ...checkCrosses(topo.trails, topo),
+    ...checkComposes(topo.trails, topo),
     ...checkResources(topo.trails, topo),
     ...checkContourReferences(topo.contours, topo),
     ...checkExamples(topo.trails),

package/src/validation.ts

@@ -83,6 +83,15 @@ const getSchemaJsonSchemaOverride = (
   return undefined;
 };
 
+/**
+ * Whether a schema has a deterministic JSON-schema override projection (for
+ * example `blobRefSchema`, a `z.custom(...)` carrying the descriptor metadata).
+ * Such schemas project to a canonical descriptor regardless of their underlying
+ * Zod internals, so marker derivation can treat them as supported.
+ */
+export const schemaHasJsonSchemaOverride = (schema: z.ZodType): boolean =>
+  getSchemaJsonSchemaOverride(schema) !== undefined;
+
 // ---------------------------------------------------------------------------
 // Issue formatting
 // ---------------------------------------------------------------------------
@@ -152,24 +161,76 @@ export const validateOutput = <T>(
 const DYNAMIC_DEFAULT = Symbol('DYNAMIC_DEFAULT');
 const defaultValueCache = new WeakMap<object, unknown>();
 
-/** Read a Zod v4 default getter twice and decide if it's stable.
- *  Uses Object.is for primitives and JSON.stringify for objects/arrays. */
+const defaultsMatch = (left: unknown, right: unknown): boolean => {
+  if (Object.is(left, right)) {
+    return true;
+  }
+  try {
+    return JSON.stringify(left) === JSON.stringify(right);
+  } catch {
+    return false;
+  }
+};
+
+const waitForClockAdvance = (): void => {
+  const wallStart = Date.now();
+  const monotonicStart = performance.now();
+  while (Date.now() === wallStart && performance.now() - monotonicStart < 4) {
+    // Zod hides default factories behind a getter. A bounded sync wait lets
+    // Date.now()-style factories reveal themselves without making the API async.
+  }
+};
+
+const readDefaultWithDateNowOffset = (
+  def: Record<string, unknown>
+): unknown => {
+  const originalDateNow = Date.now;
+  try {
+    Date.now = () => originalDateNow() + 86_400_000;
+    return def['defaultValue'];
+  } finally {
+    Date.now = originalDateNow;
+  }
+};
+
+/**
+ * Read a Zod v4 default getter and decide if it is stable.
+ *
+ * Uses Object.is for primitives and JSON.stringify for objects/arrays. A delayed
+ * third read catches default factories such as `() => Date.now()` that can return
+ * equal values for immediate back-to-back reads. A Date.now() probe catches
+ * coarser clock factories without requiring marker derivation to wait for the
+ * next second/day boundary.
+ */
 const resolveDefault = (def: Record<string, unknown>): unknown => {
   try {
     const a = def['defaultValue'];
     const b = def['defaultValue'];
-    if (Object.is(a, b)) {
-      return a;
+    if (!defaultsMatch(a, b)) {
+      return DYNAMIC_DEFAULT;
+    }
+    waitForClockAdvance();
+    const c = def['defaultValue'];
+    if (!defaultsMatch(a, c)) {
+      return DYNAMIC_DEFAULT;
     }
-    // Object/array defaults produce new references each call but may
-    // still be structurally identical (e.g. `() => ({ key: 'val' })`).
-    return JSON.stringify(a) === JSON.stringify(b) ? a : DYNAMIC_DEFAULT;
+    const d = readDefaultWithDateNowOffset(def);
+    return defaultsMatch(a, d) ? a : DYNAMIC_DEFAULT;
   } catch {
     // BigInt, circular refs, or other non-serializable defaults
     return DYNAMIC_DEFAULT;
   }
 };
 
+export const zodDefaultValueIsDynamic = (
+  def: Record<string, unknown>
+): boolean => {
+  if (!defaultValueCache.has(def)) {
+    defaultValueCache.set(def, resolveDefault(def));
+  }
+  return defaultValueCache.get(def) === DYNAMIC_DEFAULT;
+};
+
 /**
  * Convert common Zod types to a JSON Schema object.
  *
@@ -223,9 +284,7 @@ export const zodToJsonSchema: JsonSchemaConverter = (
     default: (value) => {
       const inner = value._zod.def['innerType'] as unknown as z.ZodType;
       const innerSchema = zodToJsonSchema(inner);
-      if (!defaultValueCache.has(value._zod.def)) {
-        defaultValueCache.set(value._zod.def, resolveDefault(value._zod.def));
-      }
+      zodDefaultValueIsDynamic(value._zod.def);
       const cached = defaultValueCache.get(value._zod.def);
       if (cached !== DYNAMIC_DEFAULT) {
         innerSchema['default'] = cached;