@ontrails/core 1.0.0-beta.13 → 1.0.0-beta.15

package/src/trail.ts

@@ -1,9 +1,17 @@
 import type { z } from 'zod';
 
+import type { AnyContour } from './contour.js';
 import type { FieldOverride } from './derive.js';
 import type { Result } from './result.js';
-import type { AnyProvision } from './provision.js';
+import type { AnyResource } from './resource.js';
+import type { AnySignal } from './signal.js';
+import {
+  createLateBoundSignalMarker,
+  getLateBoundSignalRef,
+} from './internal/signal-ref.js';
+import type { TrailsError } from './errors.js';
 import type {
+  Detour,
   Implementation,
   PermitRequirement,
   TrailContext,
@@ -27,44 +35,95 @@ export interface TrailExample<I, O> {
   readonly description?: string | undefined;
   /** The input value — fields with schema defaults may be omitted */
   readonly input: Partial<I>;
-  /** Expected output for success-path examples */
+  /** 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;
 }
 
+// ---------------------------------------------------------------------------
+// Blaze input — merges crossInput when declared
+// ---------------------------------------------------------------------------
+
+/**
+ * The input type received by a trail's blaze function.
+ *
+ * When a trail declares `crossInput`, the runtime merges those fields into
+ * the input object before calling blaze. This type makes the compiler aware
+ * of the merged shape so developers can access crossInput 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;
+
 // ---------------------------------------------------------------------------
 // Trail spec
 // ---------------------------------------------------------------------------
 
 /** Everything needed to define a trail (minus the id) */
-export interface TrailSpec<I, O> {
+export interface TrailSpec<I, O, CI = never> {
   /** 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 blaze: Implementation<I, O>;
+  readonly blaze: Implementation<BlazeInput<I, CI>, O>;
   /** 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;
+  /** Whether trailheads expose this trail by default. */
+  readonly visibility?: TrailVisibility | undefined;
   /** Arbitrary meta for tooling and filtering */
   readonly meta?: Readonly<Record<string, unknown>> | undefined;
-  /** Named sets of downstream trail IDs that may be invoked */
-  readonly detours?: Readonly<Record<string, readonly string[]>> | undefined;
+  /** Recovery paths activated when blaze fails with a matching error class. */
+  readonly detours?: readonly Detour<I, O, TrailsError>[] | undefined;
   /** Per-field overrides for deriveFields() (labels, hints, options) */
   readonly fields?: Readonly<Record<string, FieldOverride>> | undefined;
-  /** IDs of downstream trails this trail may invoke via ctx.cross() */
-  readonly crosses?: readonly string[] | undefined;
-  /** Provisions this trail may access via provision.from(ctx) */
-  readonly provisions?: readonly AnyProvision[] | undefined;
+  /** Contours this trail operates on. */
+  readonly contours?: readonly AnyContour[] | undefined;
+  /** IDs or trail objects of downstream trails this trail may invoke via ctx.cross() */
+  readonly crosses?: readonly (string | AnyTrail)[] | undefined;
+  /**
+   * Composition-only input schema — merged with `input` for `ctx.cross()` calls,
+   * invisible to public trailheads (CLI, MCP, HTTP).
+   *
+   * Fields here are available in the blaze but are not derived into CLI flags,
+   * MCP tool parameters, or HTTP request bodies. Use for data that only makes
+   * sense when one trail crosses another (e.g. `forkedFrom`).
+   */
+  readonly crossInput?: z.ZodType<CI> | undefined;
+  /** Resources this trail may access via resource.from(ctx) */
+  readonly resources?: readonly AnyResource[] | undefined;
+  /**
+   * Signals this trail emits 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: `crosses` also accepts trail objects (normalized to IDs),
+   * following the same pattern as signal references here.
+   */
+  readonly fires?: readonly (string | AnySignal)[] | undefined;
+  /**
+   * Signals that activate this trail (framework auto-subscribes).
+   *
+   * Accepts either a string id or a `Signal` value. Both forms are
+   * normalized to the signal's id at trail definition time.
+   */
+  readonly on?: readonly (string | AnySignal)[] | undefined;
   /** Auth requirement: scopes object, 'public', or omitted (undeclared) */
   readonly permit?: PermitRequirement | undefined;
+  /** Primary input fields and their order. CLI projects as positional args. */
+  readonly args?: readonly string[] | false | undefined;
 }
 
 // ---------------------------------------------------------------------------
@@ -74,26 +133,116 @@ export interface TrailSpec<I, O> {
 /** Intent describes what a trail does to the world */
 export type Intent = 'read' | 'write' | 'destroy';
 
+/** Whether trailheads 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> extends Omit<
-  TrailSpec<I, O>,
-  'blaze' | 'crosses' | 'intent' | 'provisions'
+export interface Trail<I, O, CI = never> extends Omit<
+  TrailSpec<I, O, CI>,
+  | 'args'
+  | 'blaze'
+  | 'contours'
+  | 'crosses'
+  | 'crossInput'
+  | 'detours'
+  | 'fires'
+  | 'intent'
+  | 'on'
+  | 'resources'
 > {
   readonly kind: 'trail';
   readonly id: string;
-  readonly blaze: Implementation<I, O>;
+  readonly blaze: Implementation<BlazeInput<I, CI>, O>;
+  /** Contours this trail operates on (always present, default []). */
+  readonly contours: readonly AnyContour[];
   /** IDs of downstream trails this trail may invoke via ctx.cross() (always present, default []) */
   readonly crosses: readonly string[];
-  /** Provisions this trail may access via provision.from(ctx) (always present, default []) */
-  readonly provisions: readonly AnyProvision[];
+  /** Composition-only input schema, merged with `input` for ctx.cross() calls (optional) */
+  readonly crossInput?: z.ZodType<CI> | undefined;
+  /** Recovery paths activated when blaze fails with a matching error (always present, default []). */
+  readonly detours: readonly Detour<I, O, TrailsError>[];
+  /** Resources this trail may access via resource.from(ctx) (always present, default []) */
+  readonly resources: readonly AnyResource[];
+  /** IDs of signals this trail emits via ctx.fire() (always present, default []) */
+  readonly fires: readonly string[];
+  /** IDs of signals that activate this trail (always present, default []) */
+  readonly on: readonly string[];
   /** What this trail does to the world (always present, default 'write') */
   readonly intent: Intent;
+  /** Whether trailheads 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
 // ---------------------------------------------------------------------------
 
+/**
+ * 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;
+  }
+
+  const ref = getLateBoundSignalRef(entry);
+  if (!ref) {
+    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)) {
+    return entry.id;
+  }
+
+  return createLateBoundSignalMarker(ref, entry.id);
+};
+
+/** Normalize a crosses entry — trail objects are reduced to their id. */
+const normalizeCrossRef = (entry: string | AnyTrail): string =>
+  typeof entry === 'string' ? entry : entry.id;
+
+/** Freeze and normalize all collection fields from a trail spec. */
+const normalizeCollections = <I, O, CI>(
+  spec: TrailSpec<I, O, CI>
+): {
+  readonly args: readonly string[] | false | undefined;
+  readonly contours: readonly AnyContour[];
+  readonly detours: readonly Detour<I, O, TrailsError>[];
+  readonly fires: readonly string[];
+  readonly on: readonly string[];
+  readonly resources: readonly AnyResource[];
+} => ({
+  args: Array.isArray(spec.args) ? Object.freeze([...spec.args]) : spec.args,
+  contours: Object.freeze([...(spec.contours ?? [])]),
+  detours: Object.freeze([...(spec.detours ?? [])]),
+  fires: Object.freeze((spec.fires ?? []).map(normalizeSignalRef)),
+  on: Object.freeze((spec.on ?? []).map(normalizeSignalRef)),
+  resources: Object.freeze([...(spec.resources ?? [])]),
+});
+
 /**
  * Create a trail definition.
  *
@@ -116,14 +265,17 @@ export interface Trail<I, O> extends Omit<
  * });
  * ```
  */
-export function trail<I, O>(id: string, spec: TrailSpec<I, O>): Trail<I, O>;
-export function trail<I, O>(
-  spec: TrailSpec<I, O> & { readonly id: string }
-): Trail<I, O>;
-export function trail<I, O>(
-  idOrSpec: string | (TrailSpec<I, O> & { readonly id: string }),
-  maybeSpec?: TrailSpec<I, O>
-): Trail<I, O> {
+export function trail<I, O, CI = never>(
+  id: string,
+  spec: TrailSpec<I, O, CI>
+): Trail<I, O, CI>;
+export function trail<I, O, CI = never>(
+  spec: TrailSpec<I, O, CI> & { readonly id: string }
+): Trail<I, O, CI>;
+export function trail<I, O, CI = never>(
+  idOrSpec: string | (TrailSpec<I, O, CI> & { readonly id: string }),
+  maybeSpec?: TrailSpec<I, O, CI>
+): Trail<I, O, CI> {
   const resolved =
     typeof idOrSpec === 'string'
       ? { id: idOrSpec, spec: maybeSpec }
@@ -135,26 +287,42 @@ export function trail<I, O>(
 
   const {
     blaze,
+    crossInput,
     crosses: rawCrosses,
     intent: rawIntent,
-    provisions: rawProvisions,
+    visibility: rawVisibility,
+    // Destructure away fields handled by normalizeCollections
+    args: _a,
+    contours: _c,
+    detours: _d,
+    fires: _f,
+    on: _o,
+    resources: _r,
     ...spec
   } = resolved.spec;
-  const provisions = Object.freeze([...(rawProvisions ?? [])]);
+  const collections = normalizeCollections(resolved.spec);
 
   return Object.freeze({
     ...spec,
-    blaze: async (input: I, ctx: TrailContext) => await blaze(input, ctx),
-    crosses: Object.freeze([...(rawCrosses ?? [])]),
+    ...collections,
+    blaze: async (input: BlazeInput<I, CI>, ctx: TrailContext) =>
+      await blaze(input, ctx),
+    crossInput,
+    crosses: Object.freeze((rawCrosses ?? []).map(normalizeCrossRef)),
     id: resolved.id,
     intent: rawIntent ?? 'write',
     kind: 'trail' as const,
-    provisions,
+    visibility: rawVisibility ?? 'public',
   });
 }
 
 // Re-export types that callers of trail() will need
-// oxlint-disable-next-line no-explicit-any -- existential type for heterogeneous collections; `any` is correct here because Implementation is contravariant in I
-export type AnyTrail = Trail<any, any>;
+// The Omit+override avoids a TypeScript limitation where BlazeInput'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, any>, 'blaze'> & {
+  readonly blaze: Implementation<any, any>;
+};
+/* oxlint-enable no-explicit-any */
 
 export type { Implementation, TrailContext, Result };