@ontrails/core 1.0.0-beta.39 → 1.0.0-beta.41

package/src/trail.ts

@@ -11,7 +11,7 @@ import {
   isActivationEntrySpec,
   isActivationSource,
 } from './activation-source.js';
-import type { AnyContour } from './contour.js';
+import type { AnyEntity } from './entity.js';
 import type {
   FieldOverride,
   CliCommandPathInput,
@@ -24,6 +24,7 @@ import type { AnySignal } from './signal.js';
 import {
   createLateBoundSignalMarker,
   getLateBoundSignalRef,
+  isBoundLateBoundSignal,
 } from './signal-ref.js';
 import type { TrailsError } from './errors.js';
 import type {
@@ -75,18 +76,18 @@ export interface TrailExample<I, O> {
 }
 
 // ---------------------------------------------------------------------------
-// Blaze input — merges composeInput when declared
+// Implementation input — merges composeInput when declared
 // ---------------------------------------------------------------------------
 
 /**
- * The input type received by a trail's blaze function.
+ * 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 blaze. This type makes the compiler aware
+ * 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 BlazeInput<I, CI> = [CI] extends [never] ? I : I & CI;
+export type ImplementationInput<I, CI> = [CI] extends [never] ? I : I & CI;
 
 type TrailRef = string | { readonly id: string };
 
@@ -105,13 +106,18 @@ type SchemaOwnedTrailSpec<
     ComposeSchemaOutput<TComposeInputSchema>,
     C
   >,
-  'blaze' | 'composeInput' | 'detours' | 'examples' | 'input' | 'versions'
+  | 'implementation'
+  | 'composeInput'
+  | 'detours'
+  | 'examples'
+  | 'input'
+  | 'versions'
 > & {
-  /** Zod schema for validating caller input and materializing blaze input. */
+  /** Zod schema for validating caller input and materializing implementation input. */
   readonly input: TInputSchema;
   /** The pure function receives schema-materialized input after validation/defaults. */
-  readonly blaze: Implementation<
-    BlazeInput<
+  readonly implementation: Implementation<
+    ImplementationInput<
       z.output<TInputSchema>,
       ComposeSchemaOutput<TComposeInputSchema>
     >,
@@ -122,7 +128,7 @@ type SchemaOwnedTrailSpec<
   readonly examples?:
     | readonly TrailExample<z.input<TInputSchema>, O>[]
     | undefined;
-  /** Recovery paths see the same materialized input as the blaze. */
+  /** Recovery paths see the same materialized input as the implementation. */
   readonly detours?:
     | readonly Detour<z.output<TInputSchema>, O, TrailsError>[]
     | undefined;
@@ -167,9 +173,9 @@ type LegacyOutputTrailSpec<
   O,
   CI,
   C extends readonly TrailRef[] | undefined,
-> = Omit<TrailSpec<I, O, CI, C>, 'blaze' | 'output'> & {
-  readonly blaze: Implementation<
-    BlazeInput<I, CI>,
+> = Omit<TrailSpec<I, O, CI, C>, 'implementation' | 'output'> & {
+  readonly implementation: Implementation<
+    ImplementationInput<I, CI>,
     NoInfer<O>,
     ComposeContextFor<C>
   >;
@@ -181,8 +187,12 @@ type LegacyOutputlessTrailSpec<
   O,
   CI,
   C extends readonly TrailRef[] | undefined,
-> = Omit<TrailSpec<I, O, CI, C>, 'blaze' | 'output'> & {
-  readonly blaze: Implementation<BlazeInput<I, CI>, O, ComposeContextFor<C>>;
+> = Omit<TrailSpec<I, O, CI, C>, 'implementation' | 'output'> & {
+  readonly implementation: Implementation<
+    ImplementationInput<I, CI>,
+    O,
+    ComposeContextFor<C>
+  >;
   readonly output?: undefined;
 };
 
@@ -253,7 +263,7 @@ export interface TrailVersionRevisionEntry<
   CurrentInput = unknown,
   CurrentOutput = unknown,
 > extends VersionEntry<VersionContract<VersionInput, VersionOutput>> {
-  readonly blaze?: never;
+  readonly implementation?: never;
   readonly composeInput?: never;
   readonly composes?: never;
   readonly detours?: never;
@@ -274,8 +284,8 @@ export interface TrailVersionForkEntry<
   VersionOutput = unknown,
   ComposeInput = never,
 > extends VersionEntry<VersionContract<VersionInput, VersionOutput>> {
-  readonly blaze: Implementation<
-    BlazeInput<VersionInput, ComposeInput>,
+  readonly implementation: Implementation<
+    ImplementationInput<VersionInput, ComposeInput>,
     VersionOutput
   >;
   readonly composes?: readonly (string | AnyTrail)[] | undefined;
@@ -316,7 +326,7 @@ export type TrailVersions<
 >;
 
 /**
- * Spec for {@link forkVersion}: a fork entry whose blaze signature is owned
+ * 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<
@@ -324,9 +334,9 @@ export interface TrailVersionForkSpec<
   TOutputSchema extends z.ZodType,
   TComposeInputSchema extends z.ZodType | undefined = undefined,
 > {
-  /** The historical blaze, typed by this entry's schemas. */
-  readonly blaze: Implementation<
-    BlazeInput<
+  /** The historical implementation, typed by this entry's schemas. */
+  readonly implementation: Implementation<
+    ImplementationInput<
       z.output<TInputSchema>,
       ComposeSchemaOutput<TComposeInputSchema>
     >,
@@ -351,15 +361,15 @@ export interface TrailVersionForkSpec<
 }
 
 /**
- * Author a fork version entry with a blaze typed by the entry's own schemas.
+ * 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 blaze
+ * `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 blaze signature and erases the generics
+ * `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 blaze (see `createForkTrailVersion` in execute.ts).
+ * the entry implementation (see `createForkTrailVersion` in execute.ts).
  *
  * @example
  * ```ts
@@ -371,7 +381,7 @@ export interface TrailVersionForkSpec<
  *   version: 2,
  *   versions: {
  *     1: forkVersion({
- *       blaze: (input) =>
+ *       implementation: (input) =>
  *         // input is { name: string; weightOz: number } — no re-parse
  *         Result.ok({ id: input.name, weightOz: input.weightOz }),
  *       input: gearV1Input,
@@ -390,14 +400,14 @@ export const forkVersion = <
 ): 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 blaze runs.
+  // 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['blaze'] === 'function' ? 'fork' : 'revision';
+  return typeof raw['implementation'] === 'function' ? 'fork' : 'revision';
 };
 
 export const isArchivedTrailVersionEntry = (
@@ -455,7 +465,11 @@ export interface TrailSpec<
   /** Zod schema for validating output (optional — some trails are fire-and-forget) */
   readonly output?: z.ZodType<O> | undefined;
   /** The pure function that does the work (sync or async authoring) */
-  readonly blaze: Implementation<BlazeInput<I, CI>, O, ComposeContextFor<C>>;
+  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. */
@@ -478,16 +492,16 @@ export interface TrailSpec<
   readonly visibility?: TrailVisibility | undefined;
   /** Arbitrary meta for tooling and filtering */
   readonly meta?: Readonly<Record<string, unknown>> | undefined;
-  /** Recovery paths activated when blaze fails with a matching error class. */
+  /** 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 blaze than surface-scope
+   * trail-scope layers innermost — closer to the implementation than surface-scope
    * or topo-scope layers — so the final order is
-   * `topo → surface → trail → blaze` (outermost-first).
+   * `topo → surface → trail → implementation` (outermost-first).
    *
    * Layers are typed and inspectable. Omit `input` for surface-invisible
    * wrappers that do not project any fields.
@@ -497,15 +511,15 @@ export interface TrailSpec<
   readonly fields?: Readonly<Record<string, FieldOverride>> | undefined;
   /** CLI projection metadata for canonical command path overrides and aliases. */
   readonly cli?: CliCommandPathInput | TrailCliProjection | undefined;
-  /** Contours this trail operates on. */
-  readonly contours?: readonly AnyContour[] | 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 blaze but are not derived into CLI flags,
+   * 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`).
    */
@@ -564,8 +578,8 @@ export type TrailVisibility = 'public' | 'internal';
 export interface Trail<I, O, CI = never> extends Omit<
   TrailSpec<I, O, CI, readonly TrailRef[] | undefined>,
   | 'args'
-  | 'blaze'
-  | 'contours'
+  | 'implementation'
+  | 'entities'
   | 'composes'
   | 'composeInput'
   | 'detours'
@@ -577,20 +591,20 @@ export interface Trail<I, O, CI = never> extends Omit<
 > {
   readonly kind: 'trail';
   readonly id: string;
-  readonly blaze: Implementation<BlazeInput<I, CI>, O>;
-  /** Contours this trail operates on (always present, default []). */
-  readonly contours: readonly AnyContour[];
+  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 blaze fails with a matching error (always present, default []). */
+  /** 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 blaze. The final
-   * composition order is `topo → surface → trail → blaze` (outermost-first).
+   * 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 []) */
@@ -616,18 +630,6 @@ export interface Trail<I, O, CI = never> extends Omit<
 // Factory
 // ---------------------------------------------------------------------------
 
-/**
- * Canonical scoped-signal id shape: `<scope>:<table>.<event>`.
- *
- * Matches exactly one `:` separating a non-empty scope from a non-empty
- * dotted tail of at least two segments (e.g. `identity:users.created`).
- * The scope forbids only `:` and whitespace so resource ids may contain
- * dots for namespacing (e.g. `demo.store:gists.created`). Tail segments
- * forbid both `:` and `.` so strings like `foo:bar` (no dot) or
- * `a:b.c.d` stay unambiguous.
- */
-const SCOPED_SIGNAL_ID = /^[^:\s]+:[^:.\s]+(?:\.[^:.\s]+)+$/;
-
 const normalizeSignalRef = (entry: string | AnySignal): string => {
   if (typeof entry === 'string') {
     return entry;
@@ -638,19 +640,10 @@ const normalizeSignalRef = (entry: string | AnySignal): string => {
     return entry.id;
   }
 
-  // Already-scoped canonical ids (e.g. "identity:users.created") must pass
-  // through unchanged. Rewriting them to a bare marker token collapses
-  // multi-binding cases where the same store definition is bound under two
-  // separate resources: both bindings share the late-bound token, so the
-  // caller's explicit choice of scope would be lost and topo resolution
-  // would throw an ambiguity error.
-  //
-  // Use a strict predicate that matches the canonical scoped shape
-  // `<scope>:<table>.<event>` (exactly one `:` separating a non-empty scope
-  // from a non-empty dotted tail of at least two segments). A looser
-  // `includes(':')` check would let unscoped ids that happen to contain `:`
-  // slip past markerization and then fail to resolve at topo finalization.
-  if (SCOPED_SIGNAL_ID.test(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;
   }
 
@@ -992,11 +985,11 @@ const normalizeVersionEntry = <CurrentInput, CurrentOutput>(
     );
   }
 
-  const hasBlaze = typeof raw['blaze'] === 'function';
+  const hasImplementation = typeof raw['implementation'] === 'function';
   const hasTranspose = raw['transpose'] !== undefined;
-  if (hasBlaze && hasTranspose) {
+  if (hasImplementation && hasTranspose) {
     throw new ValidationError(
-      `Trail "${trailId}" version ${version} cannot declare both blaze and transpose`
+      `Trail "${trailId}" version ${version} cannot declare both implementation and transpose`
     );
   }
 
@@ -1013,11 +1006,14 @@ const normalizeVersionEntry = <CurrentInput, CurrentOutput>(
       : { status: normalizeVersionStatus(trailId, version, raw['status']) }),
   };
 
-  if (hasBlaze) {
+  if (hasImplementation) {
     return Object.freeze({
       ...base,
-      blaze: async (input: unknown, ctx: TrailContext) =>
-        await (raw['blaze'] as Implementation<unknown, unknown>)(input, ctx),
+      implementation: async (input: unknown, ctx: TrailContext) =>
+        await (raw['implementation'] as Implementation<unknown, unknown>)(
+          input,
+          ctx
+        ),
       ...(raw['composeInput'] === undefined
         ? {}
         : { composeInput: raw['composeInput'] }),
@@ -1153,7 +1149,7 @@ const normalizeCollections = <
 ): {
   readonly args: readonly string[] | false | undefined;
   readonly activationSources: readonly ActivationEntry[];
-  readonly contours: readonly AnyContour[];
+  readonly entities: readonly AnyEntity[];
   readonly detours: readonly Detour<I, O, TrailsError>[];
   readonly fires: readonly string[];
   readonly layers: readonly Layer[];
@@ -1164,8 +1160,8 @@ const normalizeCollections = <
   return {
     activationSources,
     args: Array.isArray(spec.args) ? Object.freeze([...spec.args]) : spec.args,
-    contours: Object.freeze([...(spec.contours ?? [])]),
     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),
@@ -1184,14 +1180,14 @@ const normalizeCollections = <
  * // ID as first argument (recommended for human authoring)
  * const show = trail("entity.show", {
  *   input: z.object({ name: z.string() }),
- *   blaze: (input) => Result.ok(entity),
+ *   implementation: (input) => Result.ok(entity),
  * });
  *
  * // Full spec object (for programmatic generation)
  * const show = trail({
  *   id: "entity.show",
  *   input: z.object({ name: z.string() }),
- *   blaze: (input) => Result.ok(entity),
+ *   implementation: (input) => Result.ok(entity),
  * });
  * ```
  */
@@ -1281,21 +1277,28 @@ export function trail<
   if (!resolved.spec) {
     throw new TypeError('trail() requires a spec when an id is provided');
   }
-  if (hasOwn(resolved.spec as unknown as Record<string, unknown>, 'marker')) {
+  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 projected`
     );
   }
 
   const {
-    blaze,
+    implementation,
     composeInput,
     composes: rawComposes,
     intent: rawIntent,
     visibility: rawVisibility,
     // Destructure away fields handled by normalizeCollections
     args: _a,
-    contours: _c,
+    entities: _c,
     detours: _d,
     fires: _f,
     layers: _l,
@@ -1317,11 +1320,13 @@ export function trail<
   return Object.freeze({
     ...spec,
     ...collections,
-    blaze: async (input: BlazeInput<I, CI>, ctx: TrailContext) =>
-      await blaze(input, ctx as ComposeContextFor<C>),
     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 }),
@@ -1331,14 +1336,14 @@ export function trail<
 }
 
 // Re-export types that callers of trail() will need
-// The Omit+override avoids a TypeScript limitation where BlazeInput's conditional type
+// 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>,
-  'blaze' | 'composeInput'
+  'implementation' | 'composeInput'
 > & {
-  readonly blaze: Implementation<any, any>;
+  readonly implementation: Implementation<any, any>;
   readonly composeInput?: z.ZodType<any> | undefined;
 };
 /* oxlint-enable no-explicit-any */