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

package/src/trails/index.ts

@@ -0,0 +1,9 @@
+export { deriveTrail } from './derive-trail.js';
+export type {
+  DeriveTrailInput,
+  DeriveTrailOperation,
+  DeriveTrailOutput,
+  DeriveTrailSpec,
+} from './derive-trail.js';
+export { ingest } from './ingest.js';
+export type { IngestOptions, IngestTransform } from './ingest.js';

package/src/trails/ingest.ts

@@ -0,0 +1,146 @@
+import { z } from 'zod';
+
+import { InternalError } from '../errors.js';
+import { composeLayers } from '../layer.js';
+import type { Layer } from '../layer.js';
+import { Result } from '../result.js';
+import type { Signal } from '../signal.js';
+import { trail } from '../trail.js';
+import type { Trail, TrailExample, TrailSpec } from '../trail.js';
+import type { TrailContext } from '../types.js';
+
+type SchemaValue<TSchema extends z.ZodType> = z.output<TSchema>;
+type SignalRef<TSignal> = string | Signal<TSignal>;
+
+type ExampleBearingSchema<TSchema extends z.ZodType> = TSchema & {
+  readonly examples?: readonly Partial<SchemaValue<TSchema>>[] | undefined;
+};
+
+interface IngestBaseOptions<TSchema extends z.ZodType, TSignal> extends Omit<
+  TrailSpec<SchemaValue<TSchema>, void>,
+  'blaze' | 'examples' | 'fires' | 'input' | 'intent' | 'output' | 'pattern'
+> {
+  /** Override the derived trail id. Defaults to `${signal}.ingest`. */
+  readonly id?: string | undefined;
+  /** Validated external payload shape. */
+  readonly schema: TSchema;
+  /** Signal to emit after verification and optional transformation. */
+  readonly signal: SignalRef<TSignal>;
+  /** Optional per-trail verification layer, e.g. HMAC signature checks. */
+  readonly verify?: Layer | undefined;
+}
+
+export type IngestTransform<TInput, TSignal> = (
+  payload: TInput,
+  ctx: TrailContext
+) => TSignal | Promise<TSignal>;
+
+export interface IngestOptions<
+  TSchema extends z.ZodType,
+  TSignal,
+> extends IngestBaseOptions<TSchema, TSignal> {
+  readonly transform?:
+    | IngestTransform<SchemaValue<TSchema>, TSignal>
+    | undefined;
+}
+
+const resolveSignalId = <TSignal>(signalRef: SignalRef<TSignal>): string =>
+  typeof signalRef === 'string' ? signalRef : signalRef.id;
+
+const deriveExampleName = (signalId: string, index: number): string =>
+  `Ingest ${signalId} ${index + 1}`;
+
+const deriveExamples = <TSchema extends z.ZodType>(
+  schema: ExampleBearingSchema<TSchema>,
+  signalId: string
+): readonly TrailExample<SchemaValue<TSchema>, void>[] | undefined => {
+  const { examples } = schema;
+  if (examples === undefined || examples.length === 0) {
+    return undefined;
+  }
+
+  return Object.freeze(
+    examples.map((example, index) => ({
+      input: example,
+      name: deriveExampleName(signalId, index),
+    }))
+  );
+};
+
+const createIngestBlaze =
+  <TSchema extends z.ZodType, TSignal>(
+    signalRef: SignalRef<TSignal>,
+    signalId: string,
+    trailId: string,
+    transform: IngestTransform<SchemaValue<TSchema>, TSignal> | undefined
+  ) =>
+  async (
+    input: SchemaValue<TSchema>,
+    ctx: TrailContext
+  ): Promise<Result<void, Error>> => {
+    if (ctx.fire === undefined) {
+      return Result.err(
+        new InternalError(
+          `ingest("${trailId}") requires topo-backed execution to emit "${signalId}"`
+        )
+      );
+    }
+
+    try {
+      const payload =
+        transform === undefined
+          ? (input as TSignal)
+          : await transform(input, ctx);
+      const fired =
+        typeof signalRef === 'string'
+          ? await ctx.fire(signalRef, payload as unknown)
+          : await ctx.fire(signalRef as Signal<unknown>, payload as unknown);
+
+      return fired.isErr() ? Result.err(fired.error) : Result.ok();
+    } catch (error) {
+      const message = `ingest("${trailId}"): ${error instanceof Error ? error.message : String(error)}`;
+      return Result.err(
+        error instanceof Error
+          ? new InternalError(message, { cause: error })
+          : new InternalError(message)
+      );
+    }
+  };
+
+export const ingest = <
+  TSchema extends z.ZodType,
+  TSignal = SchemaValue<TSchema>,
+>(
+  options: IngestOptions<TSchema, TSignal>
+): Trail<SchemaValue<TSchema>, void> => {
+  const signalId = resolveSignalId(options.signal);
+  const id = options.id ?? `${signalId}.ingest`;
+  const { id: _id, schema, signal, transform, verify, ...trailSpec } = options;
+  const baseBlaze = createIngestBlaze<TSchema, TSignal>(
+    signal,
+    signalId,
+    id,
+    transform
+  );
+  const baseTrail = trail(id, {
+    ...trailSpec,
+    blaze: baseBlaze,
+    examples: deriveExamples(schema as ExampleBearingSchema<TSchema>, signalId),
+    fires: [signal],
+    input: schema as z.ZodType<SchemaValue<TSchema>>,
+    intent: 'write',
+    output: z.void(),
+    pattern: 'ingest',
+  }) as Trail<SchemaValue<TSchema>, void>;
+
+  if (verify === undefined) {
+    return baseTrail;
+  }
+
+  // Verification is a per-factory concern, so compose it locally instead of
+  // mutating runner-wide layer configuration.
+  return Object.freeze({
+    ...baseTrail,
+    blaze: composeLayers([verify], baseTrail, baseTrail.blaze),
+  }) as Trail<SchemaValue<TSchema>, void>;
+};

package/src/transport-error-map.ts

@@ -0,0 +1,56 @@
+import type { ErrorCategory, TrailsError } from './errors.js';
+import { exitCodeMap, jsonRpcCodeMap, statusCodeMap } from './errors.js';
+
+export const transportNames = ['cli', 'http', 'mcp'] as const;
+
+export type TransportName = (typeof transportNames)[number];
+
+export type TransportErrorMapper<T> = (error: TrailsError) => T;
+
+export type TransportErrorMappings<T> = Record<ErrorCategory, T>;
+
+/**
+ * Union of every transport-specific error code emitted by {@link transportErrorMap}.
+ *
+ * @remarks
+ * Previously parameterised by transport (`TransportErrorCode<'cli'>` etc.), but
+ * the generic collapsed to `number` because the underlying maps were typed as
+ * `Record<ErrorCategory, number>`. With `as const satisfies` on the maps the
+ * per-transport literals are now observable, but TypeScript cannot narrow
+ * `transportErrorMap[transport][error.category]` through a generic
+ * `TTransport` without an unsound cast. The non-generic union honestly reflects
+ * what `mapTransportError` returns at the call site.
+ */
+export type TransportErrorCode =
+  (typeof transportErrorMap)[TransportName][ErrorCategory];
+
+export const createTransportErrorMapper =
+  <T>(mappings: TransportErrorMappings<T>): TransportErrorMapper<T> =>
+  (error) =>
+    mappings[error.category];
+
+export const transportErrorMap = {
+  cli: exitCodeMap,
+  http: statusCodeMap,
+  mcp: jsonRpcCodeMap,
+} as const satisfies Record<TransportName, TransportErrorMappings<number>>;
+
+export const transportErrorRegistry = {
+  cli: {
+    map: createTransportErrorMapper(transportErrorMap.cli),
+    values: transportErrorMap.cli,
+  },
+  http: {
+    map: createTransportErrorMapper(transportErrorMap.http),
+    values: transportErrorMap.http,
+  },
+  mcp: {
+    map: createTransportErrorMapper(transportErrorMap.mcp),
+    values: transportErrorMap.mcp,
+  },
+} as const;
+
+export const mapTransportError = (
+  transport: TransportName,
+  error: TrailsError
+): TransportErrorCode => transportErrorMap[transport][error.category];

package/src/type-checks.test-d.ts

@@ -0,0 +1,106 @@
+/**
+ * Compile-time type assertions for type-utils.
+ *
+ * This file lives in src/ (not __tests__/) so it is included in the
+ * typecheck pass. It contains no runtime code — only type-level
+ * assertions that fail the build when type inference regresses.
+ *
+ * Assertion types are exported to satisfy `noUnusedLocals` but are not
+ * re-exported from the package index.
+ */
+
+import type { Trail } from './trail.js';
+import type { CrossInput, TrailInput } from './type-utils.js';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** A trail with crossInput declared. */
+type CrossTrail = Trail<
+  { name: string },
+  { id: string },
+  { forkedFrom: string }
+>;
+
+/** A trail without crossInput. */
+type PlainTrail = Trail<{ name: string }, { id: string }>;
+
+// ---------------------------------------------------------------------------
+// CrossInput<T> must include crossInput fields
+// ---------------------------------------------------------------------------
+
+type WithCrossInput = CrossInput<CrossTrail>;
+
+// Must require both `name` AND `forkedFrom`.
+// Before the fix, `forkedFrom` was erased.
+type AssertMerged = WithCrossInput extends { name: string; forkedFrom: string }
+  ? true
+  : false;
+export type Merged = [AssertMerged] extends [true] ? 'pass' : never;
+
+// ---------------------------------------------------------------------------
+// CrossInput<T> falls back to TrailInput<T> when no crossInput
+// ---------------------------------------------------------------------------
+
+type WithoutCrossInput = CrossInput<PlainTrail>;
+type BaseInput = TrailInput<PlainTrail>;
+
+// These should be mutually assignable (identical).
+type AssertFallback1 = WithoutCrossInput extends BaseInput ? true : false;
+type AssertFallback2 = BaseInput extends WithoutCrossInput ? true : false;
+export type Fallback = [AssertFallback1, AssertFallback2] extends [true, true]
+  ? 'pass'
+  : never;
+
+// ---------------------------------------------------------------------------
+// BlazeInput: blaze receives crossInput fields when declared
+// ---------------------------------------------------------------------------
+
+/**
+ * When a trail has crossInput, the blaze's first parameter must include
+ * both the public input fields AND the crossInput fields. Before the fix,
+ * blaze was typed as Implementation<I, O>, losing the CI fields.
+ */
+type CrossBlazeParam = Parameters<CrossTrail['blaze']>[0];
+
+type AssertBlazeHasCrossFields = CrossBlazeParam extends {
+  name: string;
+  forkedFrom: string;
+}
+  ? true
+  : false;
+export type BlazeWithCross = [AssertBlazeHasCrossFields] extends [true]
+  ? 'pass'
+  : never;
+
+// Plain trail blaze should only receive the public input type.
+type PlainBlazeParam = Parameters<PlainTrail['blaze']>[0];
+
+type AssertPlainBlazeIsInput = PlainBlazeParam extends { name: string }
+  ? true
+  : false;
+type AssertPlainBlazeNoExtra = { name: string } extends PlainBlazeParam
+  ? true
+  : false;
+export type BlazeWithoutCross = [
+  AssertPlainBlazeIsInput,
+  AssertPlainBlazeNoExtra,
+] extends [true, true]
+  ? 'pass'
+  : never;
+
+// ---------------------------------------------------------------------------
+// CI = never default preserves backward compat
+// ---------------------------------------------------------------------------
+
+// Trail<I, O> (two generics) should be assignable to Trail<I, O, never>
+type AssertDefault =
+  Trail<{ x: number }, { y: number }> extends Trail<
+    { x: number },
+    { y: number },
+    never
+  >
+    ? true
+    : false;
+export type Default = [AssertDefault] extends [true] ? 'pass' : never;

package/src/type-utils.ts

@@ -13,11 +13,26 @@ import type { AnyTrail, Trail } from './trail.js';
 
 /** Extract the input type from a Trail. */
 export type TrailInput<T extends AnyTrail> =
-  T extends Trail<infer I, any> ? I : never;
+  T extends Trail<infer I, any, any> ? I : never;
 
 /** Extract the output type from a Trail. */
 export type TrailOutput<T extends AnyTrail> =
-  T extends Trail<any, infer O> ? O : never;
+  T extends Trail<any, infer O, any> ? O : never;
+
+/**
+ * Extract the cross-callable input type from a trail.
+ *
+ * When a trail declares `crossInput`, callers via `ctx.cross()` 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.
+ */
+export type CrossInput<T extends AnyTrail> =
+  T extends Trail<infer I, any, infer CI>
+    ? [CI] extends [never]
+      ? I
+      : I & CI
+    : never;
 
 /**
  * Extracts the full `Result<Output, Error>` type from a trail definition.

package/src/types.ts

@@ -1,4 +1,64 @@
+import type { TrailsError } from './errors.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';
+
+// ---------------------------------------------------------------------------
+// Detour
+// ---------------------------------------------------------------------------
+
+/** A recovery path that activates when a trail's blaze fails with a matching error. */
+export interface Detour<Input, Output, TErr extends TrailsError = TrailsError> {
+  /* oxlint-disable-next-line no-explicit-any -- standard pattern for matching abstract+concrete class constructors */
+  readonly on: abstract new (...args: any[]) => TErr;
+  readonly maxAttempts?: number | undefined;
+  readonly recover: (
+    attempt: DetourAttempt<Input, TErr>,
+    ctx: TrailContext
+  ) => Promise<Result<Output, TrailsError>>;
+}
+
+/** Context passed to a detour's recover function on each attempt. */
+export interface DetourAttempt<Input, TErr extends TrailsError = TrailsError> {
+  /** 1-indexed attempt number */
+  readonly attempt: number;
+  /** The matched error */
+  readonly error: TErr;
+  /** Original trail input */
+  readonly input: Input;
+}
+
+type CrossBatchCall<TTarget extends AnyTrail | string = AnyTrail | string> =
+  TTarget extends AnyTrail
+    ? readonly [trail: TTarget, input: CrossInput<TTarget>]
+    : readonly [id: string, input: unknown];
+
+type CrossBatchResult<TTarget extends AnyTrail | string> =
+  TTarget extends AnyTrail
+    ? Result<TrailOutput<TTarget>, Error>
+    : Result<unknown, Error>;
+
+type CrossBatchResults<TCalls extends readonly CrossBatchCall[]> = {
+  readonly [K in keyof TCalls]: TCalls[K] extends readonly [
+    infer TTarget,
+    unknown,
+  ]
+    ? TTarget extends AnyTrail | string
+      ? CrossBatchResult<TTarget>
+      : never
+    : never;
+};
+
+/** Runtime options for batch `ctx.cross([...])` calls. */
+export interface CrossBatchOptions {
+  /**
+   * Maximum number of branches to execute concurrently.
+   *
+   * Omit for unbounded concurrency. `1` is equivalent to sequential execution.
+   */
+  readonly concurrency?: number | undefined;
+}
 
 /**
  * Trail implementation — sync or async.
@@ -11,17 +71,78 @@ export type Implementation<I, O> = (
   ctx: TrailContext
 ) => Result<O, Error> | Promise<Result<O, Error>>;
 
-/** Invoke another trail by id — used for trail composition */
-export type CrossFn = <O>(
-  id: string,
-  input: unknown
-) => Promise<Result<O, Error>>;
+/**
+ * Invoke another trail — used for trail composition.
+ *
+ * Two call shapes:
+ *
+ * - **By trail object** (typed): `ctx.cross(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 })`
+ *   — 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
+ *   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[]>(
+    calls: TCalls,
+    options?: CrossBatchOptions
+  ): Promise<CrossBatchResults<TCalls>>;
+  <T extends AnyTrail>(
+    trail: T,
+    input: CrossInput<T>
+  ): Promise<Result<TrailOutput<T>, Error>>;
+  <O = unknown>(id: string, input: unknown): Promise<Result<O, Error>>;
+}
 
-/** Resolve a provision instance from the current trail context. */
-export type ProvisionLookup = <T = unknown>(
-  provisionOrId: { readonly id: string } | string
+/**
+ * Emit a signal — used for signal-driven activation.
+ *
+ * Fan-out to consumer trails (those with the signal in their `on:` array) is
+ * the framework's responsibility. Producers get `Result.ok(undefined)` unless
+ * the signal id is unknown or the payload fails schema validation. Consumer
+ * errors are logged but do not propagate back to the producer. Consumers fan
+ * out in parallel, each with its own derived context. Runtime cycle
+ * suppression is still signal-id-based against the current fire stack: it
+ * prevents re-entrant loops but can over-suppress legitimate diamond
+ * re-fires, with a debug breadcrumb and a warn emitted when suppression happens.
+ *
+ * Two call shapes are supported:
+ *
+ * - **By id** (base shape): `ctx.fire('order.placed', { ... })`. Matches
+ *   the shape of `ctx.cross`; payload is typed as `unknown` and validated
+ *   against the signal's schema at the fire boundary.
+ * - **By signal value** (progressive disclosure): `ctx.fire(orderPlaced, payload)`
+ *   where `orderPlaced` is a `Signal<T>`. The compiler enforces that
+ *   `payload` matches the signal's declared schema type at the call site,
+ *   on top of the runtime validation.
+ */
+export interface FireFn {
+  <T>(signal: Signal<T>, payload: T): Promise<Result<void, Error>>;
+  (signalId: string, payload: unknown): Promise<Result<void, Error>>;
+}
+
+/** Resolve a resource instance from the current trail context. */
+export type ResourceLookup = <T = unknown>(
+  resourceOrId: { readonly id: string } | string
 ) => T;
 
+/**
+ * Wrap the execution of `fn` in a child trace span.
+ *
+ * Creates a nested span under the current trail's root trace record, times
+ * the callback, records success or failure (including error category), and
+ * writes the completed span to the registered sink. Errors thrown by `fn`
+ * are recorded on the span and then rethrown — tracing never swallows them.
+ */
+export type TraceFn = <T>(
+  label: string,
+  fn: () => T | Promise<T>
+) => Promise<T>;
+
 /** Callback for reporting progress from long-running trails */
 export type ProgressCallback = (event: ProgressEvent) => void;
 
@@ -60,6 +181,12 @@ export interface TrailContext {
   readonly requestId: string;
   readonly abortSignal: AbortSignal;
   readonly cross?: CrossFn | undefined;
+  /**
+   * Emit a signal by id. Fans out to every trail with the signal in its
+   * `on:` declaration. Bound by the runner that holds the topo (typically
+   * `run()`); undefined when a context is constructed without topo access.
+   */
+  readonly fire?: FireFn | undefined;
   readonly permit?: BasePermit;
   readonly workspaceRoot?: string | undefined;
   readonly logger?: Logger | undefined;
@@ -67,7 +194,16 @@ export interface TrailContext {
   readonly cwd?: string | undefined;
   readonly env?: Record<string, string | undefined> | undefined;
   readonly extensions?: Readonly<Record<string, unknown>> | undefined;
-  readonly provision?: ProvisionLookup | undefined;
+  readonly resource?: ResourceLookup | undefined;
+  /**
+   * Wrap a callback in a child trace span.
+   *
+   * Always present on contexts produced by `executeTrail` or
+   * `createTrailContext`. Optional on the interface so manually constructed
+   * contexts (tests, ad-hoc compositions) don't have to supply one — call
+   * sites tolerate `undefined` by falling back to a no-op passthrough.
+   */
+  readonly trace?: TraceFn | undefined;
 }
 
 /**
@@ -82,6 +218,7 @@ export type PermitRequirement =
   | 'public';
 
 /** Input shape used to seed a runtime TrailContext before resolution. */
-export type TrailContextInit = Omit<TrailContext, 'provision'> & {
-  readonly provision?: ProvisionLookup | undefined;
+export type TrailContextInit = Omit<TrailContext, 'resource' | 'trace'> & {
+  readonly resource?: ResourceLookup | undefined;
+  readonly trace?: TraceFn | undefined;
 };

package/src/validate-established-topo.ts

@@ -0,0 +1,63 @@
+import { ValidationError } from './errors.js';
+import { Result } from './result.js';
+import type { Topo } from './topo.js';
+import { validateDraftFreeTopo } from './draft.js';
+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',
+  'resource-exists',
+  'signal-origin-exists',
+]);
+
+const keepProjectionBlockingIssues = (
+  result: ReturnType<typeof validateTopo>
+) => {
+  if (result.isOk()) {
+    return result;
+  }
+
+  const issues = (
+    result.error.context as { issues?: readonly TopoIssue[] } | undefined
+  )?.issues;
+  const remainingIssues = issues?.filter((issue) =>
+    PROJECTION_BLOCKING_RULES.has(issue.rule)
+  );
+
+  if (remainingIssues === undefined || remainingIssues.length === 0) {
+    return Result.ok();
+  }
+
+  return Result.err(
+    new ValidationError(
+      `Topo validation failed with ${remainingIssues.length} issue(s)`,
+      {
+        cause: result.error,
+        context: { issues: remainingIssues },
+      }
+    )
+  );
+};
+
+/**
+ * Validate that a topo is ready for established outputs.
+ *
+ * Established surfaces still require the authored graph to be structurally
+ * valid, and they must also reject any remaining draft state.
+ */
+export const validateEstablishedTopo = (topo: Topo) => {
+  const structural = keepProjectionBlockingIssues(validateTopo(topo));
+  if (structural.isErr()) {
+    return structural;
+  }
+
+  const established = validateDraftFreeTopo(topo);
+  if (established.isErr()) {
+    return established;
+  }
+
+  return Result.ok();
+};