@ontrails/core 1.0.0-beta.14 → 1.0.0-beta.16

package/src/trail.ts

@@ -1,9 +1,28 @@
 import type { z } from 'zod';
 
+import type {
+  ActivationEntry,
+  ActivationEntrySpec,
+  ActivationSource,
+  ActivationSourceRef,
+} from './activation-source.js';
+import {
+  isActivationEntrySpec,
+  isActivationSource,
+} from './activation-source.js';
+import type { AnyContour } from './contour.js';
 import type { FieldOverride } from './derive.js';
+import type { Layer } from './layer.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 './signal-ref.js';
+import type { TrailsError } from './errors.js';
 import type {
+  Detour,
   Implementation,
   PermitRequirement,
   TrailContext,
@@ -13,6 +32,17 @@ import type {
 // Trail example
 // ---------------------------------------------------------------------------
 
+export interface TrailExampleSignalAssertion {
+  /** Signal contract object or stable signal ID expected during the example. */
+  readonly signal: AnySignal | string;
+  /** Exact payload assertion for the fired signal. */
+  readonly payload?: unknown | undefined;
+  /** Partial payload assertion; declared fields must match, extras ignored. */
+  readonly payloadMatch?: unknown | undefined;
+  /** Number of matching fired signals expected. Defaults to one. */
+  readonly times?: number | undefined;
+}
+
 /**
  * A named example for documentation and testing.
  *
@@ -27,73 +57,337 @@ 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;
+  /** Signal fires expected while executing this example. */
+  readonly signals?: readonly TrailExampleSignalAssertion[] | 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;
+  /**
+   * Trail explicitly supports dry-run execution semantics.
+   *
+   * This is a declaration for governance, derivation, and surface tooling. It
+   * does not change runtime behavior by itself; the active invocation signal is
+   * `TrailContext.dryRun`.
+   */
+  readonly dryRun?: boolean | undefined;
+  /** Whether surfaces 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;
+  /**
+   * 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
+   * or topo-scope layers — so the final order is
+   * `topo → surface → trail → blaze` (outermost-first).
+   *
+   * Layers are typed and inspectable. Omit `input` for surface-invisible
+   * wrappers that do not project any fields.
+   */
+  readonly layers?: readonly Layer[] | 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 surfaces (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 fires 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;
+  /**
+   * Activation sources that can invoke this trail.
+   *
+   * Bare strings and `Signal` values are signal-source shorthand. Object form
+   * preserves the source kind and per-source metadata for the activation graph.
+   */
+  readonly on?:
+    | readonly (ActivationEntrySpec | ActivationSourceRef)[]
+    | 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;
 }
 
 // ---------------------------------------------------------------------------
 // Trail (the frozen runtime object)
 // ---------------------------------------------------------------------------
 
-/** Intent describes what a trail does to the world */
-export type Intent = 'read' | 'write' | 'destroy';
+/** Intent describes what a trail does to the world. */
+export const intentValues = Object.freeze([
+  'read',
+  'write',
+  'destroy',
+] as const);
+
+export type Intent = (typeof intentValues)[number];
+
+/** Whether surfaces 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'
+  | 'layers'
+  | '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>[];
+  /**
+   * 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).
+   */
+  readonly layers: readonly Layer[];
+  /** Resources this trail may access via resource.from(ctx) (always present, default []) */
+  readonly resources: readonly AnyResource[];
+  /** IDs of signals this trail fires via ctx.fire() (always present, default []) */
+  readonly fires: readonly string[];
+  /**
+   * IDs of signal sources that activate this trail (always present, default []).
+   * Non-signal activation sources live in `activationSources`.
+   */
+  readonly on: readonly string[];
+  /** Normalized activation source entries declared through `on` (always present, default []). */
+  readonly activationSources: readonly ActivationEntry[];
   /** What this trail does to the world (always present, default 'write') */
   readonly intent: Intent;
+  /** Whether surfaces 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);
+};
+
+const freezeActivationSource = (source: ActivationSource): ActivationSource =>
+  Object.freeze({
+    ...source,
+    ...(source.meta === undefined
+      ? {}
+      : { meta: Object.freeze({ ...source.meta }) }),
+  });
+
+const shouldPreserveSignalSource = (source: ActivationSource): boolean =>
+  source.kind === 'signal' &&
+  (!('payload' in source) ||
+    'input' in source ||
+    'parse' in source ||
+    'cron' in source ||
+    'timezone' in source);
+
+const normalizeActivationSource = (
+  source: ActivationSourceRef
+): ActivationSource => {
+  if (typeof source === 'string') {
+    return freezeActivationSource({ id: source, kind: 'signal' });
+  }
+
+  if (isActivationSource(source) && shouldPreserveSignalSource(source)) {
+    return freezeActivationSource({
+      ...source,
+      id: normalizeSignalRef(source.id),
+      kind: 'signal',
+    });
+  }
+
+  if (isActivationSource(source) && source.kind !== 'signal') {
+    return freezeActivationSource(source);
+  }
+
+  return freezeActivationSource({
+    id: normalizeSignalRef(source as string | AnySignal),
+    kind: 'signal',
+  });
+};
+
+const normalizeActivationEntry = (
+  entry: ActivationEntrySpec | ActivationSourceRef
+): ActivationEntry => {
+  const source = isActivationEntrySpec(entry) ? entry.source : entry;
+  const normalized: ActivationEntry = {
+    source: normalizeActivationSource(source),
+    ...(isActivationEntrySpec(entry) && entry.meta !== undefined
+      ? { meta: Object.freeze({ ...entry.meta }) }
+      : {}),
+    ...(isActivationEntrySpec(entry) && entry.where !== undefined
+      ? { where: entry.where }
+      : {}),
+  };
+
+  return Object.freeze(normalized);
+};
+
+const normalizeActivationSources = (
+  entries: readonly (ActivationEntrySpec | ActivationSourceRef)[]
+): readonly ActivationEntry[] =>
+  Object.freeze(entries.map((entry) => normalizeActivationEntry(entry)));
+
+const extractSignalActivationIds = (
+  activations: readonly ActivationEntry[]
+): readonly string[] =>
+  Object.freeze(
+    activations
+      .filter((entry) => entry.source.kind === 'signal')
+      .map((entry) => entry.source.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 activationSources: readonly ActivationEntry[];
+  readonly contours: readonly AnyContour[];
+  readonly detours: readonly Detour<I, O, TrailsError>[];
+  readonly fires: readonly string[];
+  readonly layers: readonly Layer[];
+  readonly on: readonly string[];
+  readonly resources: readonly AnyResource[];
+} => {
+  const activationSources = normalizeActivationSources(spec.on ?? []);
+  return {
+    activationSources,
+    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)),
+    layers: Object.freeze([...(spec.layers ?? [])]),
+    on: extractSignalActivationIds(activationSources),
+    resources: Object.freeze([...(spec.resources ?? [])]),
+  };
+};
+
 /**
  * Create a trail definition.
  *
@@ -116,14 +410,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 +432,43 @@ 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,
+    layers: _l,
+    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 };