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

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # @ontrails/core
 
+## 1.0.0-beta.19
+
+### Major Changes
+
+- 1eb5bdc: Rename first-class trail composition from the `cross` API family to the `compose` family across core contracts, testing helpers, topo projections, Warden rules, CLI scaffolds, and docs. `composes`, `ctx.compose`, `composeInput`, and `Compose*` type names are now the public authoring vocabulary; topo persistence migrates legacy composition rows and graph keys forward.
+
+### Patch Changes
+
+- e41c382: Document beta-channel install guidance in package and adapter README install snippets so consumers use explicit `@beta` (or pinned `1.0.0-beta.N`) tags instead of accidental `latest` resolution during the prerelease line. Adds the policy doc at `docs/releases/beta-channel-policy.md`, prints both `latest` and `beta` dist-tags in `bun run publish:registry-check`, and aligns plugin/skill install snippets.
+- f8d80b9: Refresh current-facing compose vocabulary in package documentation after the composition cutover.
+- 846a597: Reject versioned trail marker schemas that use Zod validation checks or object
+  catchall policies outside the bounded marker subset.
+- 223aaad: Fix `ctx.compose(trail, input)` inference for trails that do not define a
+  `composeInput` schema while preserving authored compose-input requirements.
+- 3125f4d: Add pure revision transpose validation and execution helpers for trail versions.
+- 2494dc6: Infer `resource()` create-context config types from resource config schemas.
+- 2d53717: Add trail-only `version` / `versions` authoring types and TopoGraph projection.
+- 16cb740: Run examples and contract checks across live trail version entries, and project version-entry example coverage into topo and survey reports.
+- 8894ecb: Project content-addressed trail version markers and marker-prefix resolution.
+- fdf7ec9: Resolve trail versions during execution, including live revisions, forks, marker references, and unsupported-version errors.
+- d76be13: Require deprecated trail version entries to carry successor, migration, or note guidance and expose typed lifecycle helpers.
+- 84f56a5: Project live trail-version metadata on CLI, HTTP, and MCP surfaces and thread explicit surface version selection into shared trail execution.
+- 431b04c: Expose archived trail version lifecycle helpers and validate archived status reason metadata.
+- 5d88104: Polish Trails blaze terminology across package docs and Warden guidance.
+- f04a9ef: Tighten trail-versioning API polish by keeping executor cross-validation internals out of public options and improving absent marker diagnostics.
+
 ## 1.0.0-beta.18
 
 ## 1.0.0-beta.17

package/README.md

@@ -21,14 +21,14 @@ const greet = trail('greet', {
 const graph = topo('myapp', { greet });
 ```
 
-Trails compose other trails through `crosses` and `ctx.cross()`:
+Trails compose other trails through `composes` and `ctx.compose()`:
 
 ```typescript
 const onboard = trail('entity.onboard', {
-  crosses: ['entity.add', 'entity.relate'],
+  composes: ['entity.add', 'entity.relate'],
   input: z.object({ name: z.string(), type: z.string() }),
   blaze: async (input, ctx) => {
-    const added = await ctx.cross('entity.add', input);
+    const added = await ctx.compose('entity.add', input);
     if (added.isErr()) return added;
     return Result.ok({ entity: added.value });
   },
@@ -41,20 +41,20 @@ const onboard = trail('entity.onboard', {
 
 | Export | What it does |
 | --- | --- |
-| `trail(id, spec)` | Define a unit of work with typed input and `Result` output; use `crosses` for composition |
+| `trail(id, spec)` | Define a unit of work with typed input and `Result` output; use `composes` for composition |
 | `signal(id, spec)` | Define a server-originated notification with a typed data schema |
 | `resource(id, spec)` | Define an infrastructure dependency with `create`, `dispose`, and optional `mock` |
 | `drainResources(resources, ctx, configValues?)` | Evict and dispose cached resource singletons for surface/test shutdown |
 | `blobRefSchema` / `createBlobRef(...)` | Declare and create binary output references with a shared descriptor contract |
 | `topo(name, ...modules, options?)` | Collect trail modules into a queryable topology with optional `observe:` sinks |
 | `deriveTrail(contour, operation, spec)` | Derive CRUD-shaped trail contracts from a contour on the `@ontrails/core/trails` subpath |
-| `validateTopo(topo)` | Structural validation: cross targets exist, no cycles, examples parse, output schemas present |
+| `validateTopo(topo)` | Structural validation: compose targets exist, no cycles, examples parse, output schemas present |
 
 ### Execution
 
 | Export | What it does |
 | --- | --- |
-| `executeTrail(trail, rawInput, options?)` | Centralized execution pipeline: validates input, builds context, composes layers, runs the implementation. Never throws -- exceptions become `Result.err(InternalError)`. |
+| `executeTrail(trail, rawInput, options?)` | Centralized execution pipeline: validates input, builds context, composes layers, runs the blazed trail. Never throws -- exceptions become `Result.err(InternalError)`. |
 | `run(topo, id, input, options?)` | Headless trail execution by ID. Looks up the trail in the topo, then delegates to `executeTrail`. Returns `Result.err(NotFoundError)` if the ID is not registered. |
 
 ```typescript
@@ -115,8 +115,7 @@ result.unwrapOr(fallback);   // Value or fallback
 
 ### Error taxonomy
 
-The current taxonomy is generated from the `errorClasses` owner registry and
-category code maps in `@ontrails/core`.
+The current taxonomy is generated from the `errorClasses` owner registry and category code maps in `@ontrails/core`.
 
 <!-- error-taxonomy:start -->
 <!-- GENERATED: run `bun run error-taxonomy:sync`; check with `bun run error-taxonomy:check`. Variant: category. -->
@@ -124,7 +123,7 @@ category code maps in `@ontrails/core`.
 | Category | CLI Exit | HTTP | JSON-RPC | Retryable | Fixed Classes |
 | --- | --- | --- | --- | --- | --- |
 | `validation` | 1 | 400 | -32602 | No | `ValidationError`, `AmbiguousError` |
-| `not_found` | 2 | 404 | -32601 | No | `NotFoundError` |
+| `not_found` | 2 | 404 | -32601 | No | `NotFoundError`, `VersionNotSupportedError` |
 | `conflict` | 3 | 409 | -32603 | No | `AlreadyExistsError`, `ConflictError` |
 | `permission` | 4 | 403 | -32600 | No | `PermissionError`, `PermitError` |
 | `timeout` | 5 | 504 | -32603 | Yes | `TimeoutError` |
@@ -139,11 +138,7 @@ Dynamic classes:
 - `RetryExhaustedError` inherits category and surface codes from its wrapped `TrailsError`; retryable is always No.
 <!-- error-taxonomy:end -->
 
-Public surface projections redact sensitive substrings before exposing a
-non-internal `TrailsError` message. Internal-category `TrailsError` instances and
-unknown native errors project with the generic message `Internal server error`;
-diagnostics and serialized payloads keep their useful structure while redacting
-messages, context, and stack strings.
+Public surface projections redact sensitive substrings before exposing a non-internal `TrailsError` message. Internal-category `TrailsError` instances and unknown native errors project with the generic message `Internal server error`; diagnostics and serialized payloads keep their useful structure while redacting messages, context, and stack strings.
 
 The developer returns `Result.err(new NotFoundError(...))`. The framework maps it to the right code on every surface.
 
@@ -163,19 +158,11 @@ The developer returns `Result.err(new NotFoundError(...))`. The framework maps i
 
 ### Public helper boundaries
 
-The root package also exposes a few low-level contracts that other framework
-packages build on:
+The root package also exposes a few low-level contracts that other framework packages build on:
 
-- **Intrinsic tracing** -- `TraceRecord`, `TraceSink`, `TraceContext`, and the
-  sink registry helpers are the core-owned execution record shape shared by
-  `@ontrails/observe`, `@ontrails/tracing`, and adapters.
-- **Trails DB** -- `deriveTrailsDbPath`, `deriveTrailsDir`,
-  `ensureSubsystemSchema`, `openReadTrailsDb`, and `openWriteTrailsDb` are the
-  generic database primitive used by framework subsystems.
-- **Surface projection helpers** -- safe error projection, layer field
-  projection, cross-batch validation, late-bound signal references, and Zod
-  default-wrapper stripping are stable root exports for first-party surfaces,
-  store helpers, and tests.
+- **Intrinsic tracing** -- `TraceRecord`, `TraceSink`, `TraceContext`, and the sink registry helpers are the core-owned execution record shape shared by `@ontrails/observe`, `@ontrails/tracing`, and adapters.
+- **Trails DB** -- `deriveTrailsDbPath`, `deriveTrailsDir`, `ensureSubsystemSchema`, `openReadTrailsDb`, and `openWriteTrailsDb` are the generic database primitive used by framework subsystems.
+- **Surface projection helpers** -- safe error projection, layer field projection, compose-batch validation, late-bound signal references, and Zod default-wrapper stripping are stable root exports for first-party surfaces, store helpers, and tests.
 
 See the [API Reference](../../docs/api-reference.md) for the full list.
 
@@ -196,5 +183,5 @@ Types `ReadOnlyTopoStore`, `MockTopoStoreSeed`, `TopoSnapshot`, `TopoStoreRef`,
 ## Installation
 
 ```bash
-bun add @ontrails/core zod
+bun add @ontrails/core@beta zod
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ontrails/core",
-  "version": "1.0.0-beta.18",
+  "version": "1.0.0-beta.19",
   "files": [
     "src/**/*.ts",
     "!src/**/__tests__/**",

package/src/{cross-batch.ts → compose-batch.ts}

@@ -1,5 +1,5 @@
 /**
- * Shared helpers for `ctx.cross([...])` batch execution.
+ * Shared helpers for `ctx.compose([...])` batch execution.
  *
  * These helpers normalize batch options, produce validation results, and
  * implement the unlimited/limited worker-pool execution strategies used by
@@ -11,18 +11,18 @@
 
 import { ValidationError } from './errors.js';
 import { Result } from './result.js';
-import type { CrossBatchOptions } from './types.js';
+import type { ComposeBatchOptions } from './types.js';
 
 /**
- * Validate the `concurrency` option on a batch `ctx.cross()` call.
+ * Validate the `concurrency` option on a batch `ctx.compose()` call.
  *
  * Returns `Ok(undefined)` when no limit is requested, `Ok(n)` when a
  * positive integer is supplied, and `Err(ValidationError)` for any other
  * value. The error message is load-bearing: callers and tests depend on
  * the exact string.
  */
-export const normalizeCrossBatchConcurrency = (
-  options: CrossBatchOptions | undefined
+export const normalizeComposeBatchConcurrency = (
+  options: ComposeBatchOptions | undefined
 ): Result<number | undefined, Error> => {
   const concurrency = options?.concurrency;
   if (concurrency === undefined) {
@@ -32,7 +32,7 @@ export const normalizeCrossBatchConcurrency = (
   if (!Number.isInteger(concurrency) || concurrency < 1) {
     return Result.err(
       new ValidationError(
-        'ctx.cross() batch concurrency must be a positive integer'
+        'ctx.compose() batch concurrency must be a positive integer'
       )
     );
   }
@@ -42,10 +42,10 @@ export const normalizeCrossBatchConcurrency = (
 
 /**
  * Produce one validation-error result per call, preserving the original
- * call order. Used when `normalizeCrossBatchConcurrency` fails so the caller
- * can surface a uniform batch shape to the trail implementation.
+ * call order. Used when `normalizeComposeBatchConcurrency` fails so the caller
+ * can surface a uniform batch shape to the blaze.
  */
-export const createCrossBatchValidationResults = <TCall>(
+export const createComposeBatchValidationResults = <TCall>(
   calls: readonly TCall[],
   error: Error
 ): Result<unknown, Error>[] => calls.map(() => Result.err(error));
@@ -55,7 +55,7 @@ export const createCrossBatchValidationResults = <TCall>(
  * multiple worker coroutines because JavaScript is single-threaded between
  * awaits — the read/increment pair runs without interleaving.
  */
-export const claimNextCrossBatchIndex = <TCall>(
+export const claimNextComposeBatchIndex = <TCall>(
   nextIndex: { value: number },
   calls: readonly TCall[]
 ): number | undefined => {

package/src/compose-schema.ts

@@ -0,0 +1,36 @@
+/**
+ * Compose-invocation schema merging for trails with `composeInput`.
+ *
+ * When a trail declares `composeInput`, callers via `ctx.compose()` pass both
+ * public input and composition-only fields. The merged schema validates the
+ * combined shape so `executeTrail` doesn't reject the extra fields.
+ */
+
+import { z } from 'zod';
+
+import type { AnyTrail } from './trail.js';
+
+/**
+ * Build the validation schema for a compose-invoked trail.
+ *
+ * When the target trail declares `composeInput`, returns the intersection of
+ * `trail.input` and `trail.composeInput`. Returns `undefined` when no
+ * `composeInput` is declared, signaling that normal input validation suffices.
+ */
+export const buildComposeValidationSchema = (
+  trailDef: AnyTrail
+): z.ZodType | undefined => {
+  if (!trailDef.composeInput) {
+    return undefined;
+  }
+  // Prefer .merge() for ZodObject pairs — produces a proper merged object
+  // schema that strips unknown keys and exposes .shape. Fall back to
+  // z.intersection for non-object schemas.
+  if (
+    trailDef.input instanceof z.ZodObject &&
+    trailDef.composeInput instanceof z.ZodObject
+  ) {
+    return trailDef.input.merge(trailDef.composeInput);
+  }
+  return z.intersection(trailDef.input, trailDef.composeInput);
+};

package/src/contour.ts

@@ -13,6 +13,8 @@ export interface ContourOptions<
   readonly identity: TIdentity;
   /** Example instances validated against the contour schema at declaration time. */
   readonly examples?: readonly z.output<z.ZodObject<TShape>>[] | undefined;
+  /** Reserved for future contour-specific design; trail versioning is trail-only. */
+  readonly version?: never;
 }
 
 /** Type-level brand name applied to a contour's identity schema. */

package/src/draft.ts

@@ -10,7 +10,7 @@ import type { AnyTrail } from './trail.js';
 export const DRAFT_ID_PREFIX = '_draft.';
 
 export type DraftDependencyKind =
-  | 'cross'
+  | 'compose'
   | 'contour'
   | 'resource'
   | 'replaced-by'
@@ -88,7 +88,7 @@ const trailDependencies = (trail: AnyTrail): DraftDependency[] => [
     (trail.contours ?? []).map((contour) => contour.name),
     'contour'
   ),
-  ...dependenciesFromIds(trail.id, trail.crosses, 'cross'),
+  ...dependenciesFromIds(trail.id, trail.composes, 'compose'),
   ...dependenciesFromIds(
     trail.id,
     trail.resources.map(({ id }) => id),

package/src/errors.ts

@@ -68,6 +68,64 @@ export class NotFoundError extends TrailsError {
   readonly retryable = false as const;
 }
 
+export class VersionNotSupportedError extends NotFoundError {
+  readonly reason?: string | undefined;
+  readonly requested?: number | string | undefined;
+  readonly supported?: readonly number[] | undefined;
+  readonly trailId?: string | undefined;
+
+  constructor(
+    message: string,
+    options?: { cause?: Error; context?: Record<string, unknown> }
+  );
+  constructor(
+    trailId: string,
+    requested: number | string,
+    supported: readonly number[],
+    reason?: string | undefined
+  );
+  constructor(
+    messageOrTrailId: string,
+    optionsOrRequested?:
+      | { cause?: Error; context?: Record<string, unknown> }
+      | number
+      | string,
+    supported?: readonly number[],
+    reason?: string | undefined
+  ) {
+    if (supported === undefined) {
+      super(
+        messageOrTrailId,
+        optionsOrRequested as
+          | { cause?: Error; context?: Record<string, unknown> }
+          | undefined
+      );
+      this.name = 'VersionNotSupportedError';
+      return;
+    }
+
+    const requested = optionsOrRequested as number | string;
+    const supportedLabel =
+      supported.length === 0 ? 'none' : supported.join(', ');
+    super(
+      `Trail "${messageOrTrailId}" version ${String(requested)} is not supported (supported: ${supportedLabel})`,
+      {
+        context: {
+          ...(reason === undefined ? {} : { reason }),
+          requested,
+          supported,
+          trailId: messageOrTrailId,
+        },
+      }
+    );
+    this.name = 'VersionNotSupportedError';
+    this.reason = reason;
+    this.requested = requested;
+    this.supported = supported;
+    this.trailId = messageOrTrailId;
+  }
+}
+
 export class AlreadyExistsError extends TrailsError {
   readonly category = 'conflict' as const;
   readonly retryable = false as const;
@@ -148,7 +206,7 @@ export class CancelledError extends TrailsError {
  *
  * Inherits the wrapped error's category for surface mapping (e.g. a
  * `RetryExhaustedError<ConflictError>` maps to HTTP 409), but always
- * sets `retryable = false` to prevent amplification across `ctx.cross()`
+ * sets `retryable = false` to prevent amplification across `ctx.compose()`
  * boundaries or stacked layers.
  */
 export class RetryExhaustedError<
@@ -238,6 +296,12 @@ export const errorClasses = [
     name: 'NotFoundError',
     retryable: false,
   },
+  {
+    category: 'not_found',
+    ctor: VersionNotSupportedError,
+    name: 'VersionNotSupportedError',
+    retryable: false,
+  },
   {
     category: 'conflict',
     ctor: AlreadyExistsError,