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

package/src/fire.ts

@@ -0,0 +1,295 @@
+/**
+ * Signal emission and auto-activation.
+ *
+ * `createFireFn(topo, producerCtx?, executor)` returns a `FireFn` bound to
+ * a topo. Calling `fire(signalId, payload)` looks up the signal, validates
+ * the payload against its schema, finds every trail with the signal in its
+ * `on:` array, and invokes each consumer via the supplied executor.
+ *
+ * The `executor` parameter is an indirection that lets `execute.ts` pass in
+ * `executeTrail` without `fire.ts` importing it directly — keeping the two
+ * modules dependency-cycle-free.
+ *
+ * Consumer contexts inherit the producer's full ctx (logger, extensions,
+ * resources, abortSignal, requestId, env, workspaceRoot, permit) with
+ * `fire` rebound to the same closure so consumers can fan out further.
+ * Each consumer gets its own derived context so sibling fan-out branches do
+ * not share mutable top-level state. The consumer logger is derived from the
+ * producer logger as a child tagged with `signalId` and `consumerId` when
+ * `logger.child` exists.
+ *
+ * Error semantics match the fire-and-forget framing: producers get
+ * `Result.ok(undefined)` unless the signal id is unknown or the payload
+ * fails schema validation. Consumer errors are logged via the producer's
+ * logger but do NOT propagate back to the producer. Consumers that need
+ * transactional coupling should use `crosses:`.
+ */
+
+import { NotFoundError, ValidationError } from './errors.js';
+import { forkCtx } from './internal/fork-ctx.js';
+import { Result } from './result.js';
+import type { Topo } from './topo.js';
+import type { AnyTrail } from './trail.js';
+import type { FireFn, Logger, TrailContextInit } from './types.js';
+
+/** Signature execute.ts passes in to avoid a fire ↔ execute import cycle. */
+export type ConsumerExecutor = (
+  consumer: AnyTrail,
+  input: unknown,
+  ctx: Partial<TrailContextInit>
+) => Promise<Result<unknown, Error>>;
+
+type MutableConsumerContext = {
+  -readonly [K in keyof Partial<TrailContextInit>]: Partial<TrailContextInit>[K];
+};
+
+const FIRE_STACK_KEY = '__trails_fire_stack';
+
+/**
+ * Maximum depth for signal fan-out chains.
+ *
+ * Cycle detection catches re-entrant fires of the same signal ID (A→B→A),
+ * but a chain of distinct signals (A→B→C→D→...) bypasses it. This limit
+ * prevents runaway fan-out in pathological topologies.
+ */
+const MAX_FIRE_DEPTH = 16;
+
+const getFireStack = (
+  ctx: Pick<TrailContextInit, 'extensions'> | undefined
+): readonly string[] => {
+  const value = ctx?.extensions?.[FIRE_STACK_KEY];
+  return Array.isArray(value) ? (value as readonly string[]) : [];
+};
+
+/** Binds a per-consumer `fire` onto a mutable consumer context. */
+type ConsumerFireBinder = (
+  consumerCtx: MutableConsumerContext
+) => MutableConsumerContext;
+
+const deriveConsumerLogger = (
+  producerCtx: TrailContextInit | undefined,
+  signalId: string,
+  consumerId: string
+): Logger | undefined =>
+  producerCtx?.logger?.child?.({ consumerId, signalId }) ?? producerCtx?.logger;
+
+const deriveConsumerEnv = (
+  producerCtx: TrailContextInit | undefined
+): TrailContextInit['env'] =>
+  producerCtx?.env ? { ...producerCtx.env } : undefined;
+
+const deriveConsumerExtensions = (
+  producerCtx: TrailContextInit | undefined,
+  signalId: string
+): TrailContextInit['extensions'] => ({
+  ...producerCtx?.extensions,
+  [FIRE_STACK_KEY]: [...getFireStack(producerCtx), signalId],
+});
+
+const deriveConsumerCtx = (
+  producerCtx: TrailContextInit | undefined,
+  signalId: string,
+  consumerId: string
+): MutableConsumerContext =>
+  producerCtx
+    ? forkCtx(producerCtx as MutableConsumerContext, {
+        env: deriveConsumerEnv(producerCtx),
+        extensions: deriveConsumerExtensions(producerCtx, signalId),
+        logger: deriveConsumerLogger(producerCtx, signalId, consumerId),
+      })
+    : {};
+
+/**
+ * Fan out a validated signal payload to its consumer trails.
+ *
+ * @remarks
+ * Consumers fan out in parallel by design. Signal delivery is fire-and-forget
+ * notification, not ordered orchestration; if one consumer depends on another,
+ * the dependency belongs in `crosses:` instead of sibling signal sequencing.
+ *
+ * `Promise.allSettled` preserves failure isolation and waits for every branch
+ * to settle. Each consumer gets its own derived context so sibling branches do
+ * not share mutable top-level state while they overlap. Re-entrant suppression
+ * elsewhere in this module is still based on signal-id membership in the
+ * current fire stack: it prevents infinite loops, but it can over-suppress
+ * legitimate diamond re-fires. Per-path provenance is a documented future
+ * direction rather than part of the pre-v1 runtime contract.
+ */
+const fanOutToConsumers = async (
+  consumers: readonly AnyTrail[],
+  payload: unknown,
+  signalId: string,
+  producerCtx: TrailContextInit | undefined,
+  bindFire: ConsumerFireBinder,
+  executor: ConsumerExecutor,
+  logger: Logger | undefined
+): Promise<void> => {
+  const settled = await Promise.allSettled(
+    consumers.map(async (consumer) => {
+      const consumerCtx = bindFire(
+        deriveConsumerCtx(producerCtx, signalId, consumer.id)
+      );
+      const consumerResult = await executor(consumer, payload, consumerCtx);
+      if (consumerResult.isErr()) {
+        (consumerCtx.logger ?? logger)?.warn('Signal consumer failed', {
+          consumerId: consumer.id,
+          error: consumerResult.error.message,
+          signalId,
+        });
+      }
+      return consumer.id;
+    })
+  );
+  for (const [index, entry] of settled.entries()) {
+    if (entry.status !== 'rejected') {
+      continue;
+    }
+    // `executeTrail` normalizes throws into `Result.err`, so reaching this
+    // branch means the executor (or the warn call above) rejected
+    // unexpectedly. Log at debug to preserve provenance without propagating
+    // the failure to the producer (fire-and-forget semantics).
+    logger?.debug('Signal consumer rejected unexpectedly', {
+      consumerId: consumers[index]?.id,
+      error:
+        entry.reason instanceof Error
+          ? entry.reason.message
+          : String(entry.reason),
+      signalId,
+    });
+  }
+};
+
+const resolveFireDispatch = (
+  topo: Topo,
+  signalId: string,
+  payload: unknown
+): Result<
+  { readonly consumers: readonly AnyTrail[]; readonly payload: unknown },
+  Error
+> => {
+  const signal = topo.signals.get(signalId);
+  if (signal === undefined) {
+    return Result.err(
+      new NotFoundError(`Signal "${signalId}" not found in topo "${topo.name}"`)
+    );
+  }
+  const parsed = signal.payload.safeParse(payload);
+  if (!parsed.success) {
+    return Result.err(
+      new ValidationError(
+        `Invalid payload for signal "${signalId}": ${parsed.error.message}`
+      )
+    );
+  }
+  return Result.ok({
+    consumers: topo.list().filter((trail) => trail.on.includes(signalId)),
+    payload: parsed.data,
+  });
+};
+
+const resolveSignalId = (signalOrId: unknown): Result<string, Error> => {
+  if (typeof signalOrId === 'string') {
+    return Result.ok(signalOrId);
+  }
+  if (
+    typeof signalOrId === 'object' &&
+    signalOrId !== null &&
+    'id' in signalOrId &&
+    typeof (signalOrId as { id: unknown }).id === 'string'
+  ) {
+    return Result.ok((signalOrId as { id: string }).id);
+  }
+  return Result.err(
+    new ValidationError(
+      'ctx.fire() requires a signal id string or a Signal value'
+    )
+  );
+};
+
+/**
+ * Build a `FireFn` closure bound to a topo.
+ *
+ * When `producerCtx` is provided, consumer trails activated via `on:`
+ * inherit the producer's logger, extensions, resources, abortSignal,
+ * requestId, env, workspaceRoot, and permit. `ctx.fire` on the consumer
+ * is rebound to the same closure so consumers can emit downstream
+ * signals naturally.
+ */
+export const createFireFn = (
+  topo: Topo,
+  producerCtx: TrailContextInit | undefined,
+  executor: ConsumerExecutor
+): FireFn => {
+  const bindConsumerFire: ConsumerFireBinder = (consumerCtx) => ({
+    ...consumerCtx,
+    // Pre-bind fire on the consumer ctx as a safety net for direct
+    // executeTrail calls that skip the topo-aware path. In the normal
+    // fan-out flow below, bindFireToCtx in execute.ts rebinds fire to
+    // the fully-traced ctx before the blaze runs, so this assignment
+    // is superseded — but keeping it makes consumerCtx self-sufficient
+    // for any caller that inspects it pre-execution.
+    fire: createFireFn(topo, consumerCtx as TrailContextInit, executor),
+  });
+
+  const dispatchFire = async (
+    signalId: string,
+    payload: unknown
+  ): Promise<Result<void, Error>> => {
+    const dispatch = resolveFireDispatch(topo, signalId, payload);
+    if (dispatch.isErr()) {
+      return Result.err(dispatch.error);
+    }
+    await fanOutToConsumers(
+      dispatch.value.consumers,
+      dispatch.value.payload,
+      signalId,
+      producerCtx,
+      bindConsumerFire,
+      executor,
+      producerCtx?.logger
+    );
+    return Result.ok();
+  };
+
+  /** Return an early Result if the fire should be suppressed, or null to proceed. */
+  const guardFire = (
+    signalId: string,
+    stack: readonly string[]
+  ): Result<void, Error> | null => {
+    if (stack.length >= MAX_FIRE_DEPTH) {
+      producerCtx?.logger?.warn(
+        'Signal fan-out depth limit reached — skipping fire',
+        { depth: stack.length, signalId }
+      );
+      return Result.ok();
+    }
+    if (stack.includes(signalId)) {
+      producerCtx?.logger?.debug('Signal fan-out suppressed due to cycle', {
+        fireStack: [...stack],
+        signalId,
+      });
+      producerCtx?.logger?.warn(
+        'Signal cycle detected — skipping re-entrant fire',
+        { fireStack: [...stack], signalId }
+      );
+      return Result.ok();
+    }
+    return null;
+  };
+
+  const fireImpl: FireFn = async (
+    signalOrId: unknown,
+    payload: unknown
+  ): Promise<Result<void, Error>> => {
+    const resolved = resolveSignalId(signalOrId);
+    if (resolved.isErr()) {
+      return Result.err(resolved.error);
+    }
+    const suppressed = guardFire(resolved.value, getFireStack(producerCtx));
+    if (suppressed) {
+      return suppressed;
+    }
+    return await dispatchFire(resolved.value, payload);
+  };
+  return fireImpl;
+};

package/src/index.ts

@@ -17,92 +17,208 @@ export {
   InternalError,
   AuthError,
   CancelledError,
+  DerivationError,
+  errorCategories,
   exitCodeMap,
   statusCodeMap,
   jsonRpcCodeMap,
   retryableMap,
+  RetryExhaustedError,
   isRetryable,
   isTrailsError,
 } from './errors.js';
 export type { ErrorCategory } from './errors.js';
+export {
+  createTransportErrorMapper,
+  mapTransportError,
+  transportErrorMap,
+  transportErrorRegistry,
+  transportNames,
+} from './transport-error-map.js';
+export type {
+  TransportErrorCode,
+  TransportErrorMapper,
+  TransportErrorMappings,
+  TransportName,
+} from './transport-error-map.js';
 
 // Types
 export type {
+  Detour,
+  DetourAttempt,
   Implementation,
   TrailContext,
   TrailContextInit,
+  CrossBatchOptions,
   CrossFn,
+  FireFn,
   BasePermit,
   PermitRequirement,
   ProgressCallback,
   ProgressEvent,
   Logger,
-  ProvisionLookup,
+  ResourceLookup,
 } from './types.js';
 export { TRAILHEAD_KEY } from './types.js';
 
 // Context factory
-export { createTrailContext } from './context.js';
+export { createTrailContext, passthroughTrace } from './context.js';
 
-// Provision
+// Resource
 export {
-  createProvisionLookup,
-  findDuplicateProvisionId,
-  isProvision,
-  provision,
-} from './provision.js';
+  createResourceLookup,
+  findDuplicateResourceId,
+  isResource,
+  resource,
+} from './resource.js';
 export type {
-  AnyProvision,
-  Provision,
-  ProvisionContext,
-  ProvisionOverrideMap,
-  ProvisionSpec,
-} from './provision.js';
+  AnyResource,
+  Resource,
+  ResourceContext,
+  ResourceOverrideMap,
+  ResourceSpec,
+} from './resource.js';
 
 // Trail
 export { trail } from './trail.js';
 export type {
   AnyTrail,
+  BlazeInput,
   Intent,
   Trail,
   TrailSpec,
   TrailExample,
+  TrailVisibility,
 } from './trail.js';
+export {
+  filterSurfaceTrails,
+  matchesTrailPattern,
+  shouldIncludeTrailForSurface,
+} from './surface-filter.js';
+export type { SurfaceFilterOptions } from './surface-filter.js';
 
 // Type utilities
-export type { TrailInput, TrailOutput, TrailResult } from './type-utils.js';
+export type {
+  CrossInput,
+  TrailInput,
+  TrailOutput,
+  TrailResult,
+} from './type-utils.js';
 export { inputOf, outputOf } from './type-utils.js';
 
 // Signal
 export { signal } from './signal.js';
 export type { AnySignal, Signal, SignalSpec } from './signal.js';
-export { event } from './event.js';
-export type { AnyEvent, Event, EventSpec } from './event.js';
+
+// Contour
+export { contour } from './contour.js';
+export {
+  CONTOUR_ID_METADATA,
+  getContourIdMetadata,
+  getContourReferences,
+} from './contour.js';
+export type {
+  AnyContour,
+  Contour,
+  ContourIdBrand,
+  ContourIdMetadata,
+  ContourIdSchema,
+  ContourIdValue,
+  ContourOptions,
+  ContourReference,
+} from './contour.js';
 
 // Topo
 export { topo } from './topo.js';
-export type { Topo } from './topo.js';
+export type { Topo, TopoIdentity } from './topo.js';
+export {
+  createTopoSnapshot,
+  createMockTopoStore,
+  createTopoStore,
+  listTopoSnapshots,
+  pinTopoSnapshot,
+  topoStore,
+  unpinTopoSnapshot,
+} from './topo-store.js';
+export type {
+  CreateTopoSnapshotInput,
+  ListTopoSnapshotsOptions,
+  MockTopoStoreSeed,
+  ReadOnlyTopoStore,
+  TopoSnapshot,
+  TopoStoreExportRecord,
+  TopoStoreResourceRecord,
+  TopoStoreRef,
+  TopoStoreTrailDetailRecord,
+  TopoStoreTrailRecord,
+} from './topo-store.js';
+
+// Draft state
+export {
+  DRAFT_ID_PREFIX,
+  deriveDraftReport,
+  isDraftId,
+  validateDraftFreeTopo,
+} from './draft.js';
+export type {
+  DraftDependency,
+  DraftDependencyKind,
+  DraftFinding,
+  DraftReport,
+} from './draft.js';
 
 // Topo validation
 export { validateTopo } from './validate-topo.js';
 export type { TopoIssue } from './validate-topo.js';
+export { validateEstablishedTopo } from './validate-established-topo.js';
 
-// Gate
-export { composeGates } from './gate.js';
-export type { Gate } from './gate.js';
+// Layer
+export { composeLayers } from './layer.js';
+export type { Layer } from './layer.js';
 
 // Derive
-export { deriveFields } from './derive.js';
+export { deriveCliPath, deriveFields } from './derive.js';
 export type { Field, FieldOverride } from './derive.js';
 
+// Cross schema
+export { buildCrossValidationSchema } from './cross-schema.js';
+
 // Execute
 export { executeTrail } from './execute.js';
 export type { ExecuteTrailOptions } from './execute.js';
 
+// Intrinsic tracing
+export {
+  clearTraceSink,
+  createTraceRecord,
+  getTraceContext,
+  getTraceSink,
+  NOOP_SINK,
+  registerTraceSink,
+  TRACE_CONTEXT_KEY,
+} from './internal/tracing.js';
+export type {
+  TraceContext,
+  TraceRecord,
+  TraceSink,
+} from './internal/tracing.js';
+export type { TraceFn } from './types.js';
+
 // Run
 export { run } from './run.js';
 export type { RunOptions } from './run.js';
 
+// Trail factories
+export { deriveTrail, ingest } from './trails/index.js';
+export type {
+  DeriveTrailInput,
+  DeriveTrailOperation,
+  DeriveTrailOutput,
+  DeriveTrailSpec,
+  IngestOptions,
+  IngestTransform,
+} from './trails/index.js';
+
 // Validation
 export {
   validateInput,
@@ -120,7 +236,7 @@ export {
   retry,
   withTimeout,
   shouldRetry,
-  getBackoffDelay,
+  deriveBackoffDelay,
 } from './resilience.js';
 export type { RetryOptions } from './resilience.js';
 
@@ -135,7 +251,7 @@ export {
   nonEmptyString,
   positiveInt,
   shortId,
-  hashId,
+  deriveIdHash,
 } from './branded.js';
 export type {
   Branded,
@@ -146,13 +262,13 @@ export type {
 } from './branded.js';
 
 // Path Security
-export { securePath, isPathSafe, resolveSafePath } from './path-security.js';
+export { securePath, isPathSafe, deriveSafePath } from './path-security.js';
 
 // Workspace
 export {
   findWorkspaceRoot,
   isInsideWorkspace,
-  getRelativePath,
+  deriveRelativePath,
 } from './workspace.js';
 
 // Blob

package/src/internal/cross-batch.ts

@@ -0,0 +1,77 @@
+/**
+ * Shared helpers for `ctx.cross([...])` batch execution.
+ *
+ * These helpers normalize batch options, produce validation results, and
+ * implement the unlimited/limited worker-pool execution strategies used by
+ * both the real executor (`packages/core/src/execute.ts`) and the scenario
+ * runner in `@ontrails/testing`. Extracting them here keeps the validation
+ * rule, error message, and worker-pool semantics authored in one place so
+ * the two call sites cannot drift.
+ *
+ * @internal
+ */
+
+import { ValidationError } from '../errors.js';
+import { Result } from '../result.js';
+import type { CrossBatchOptions } from '../types.js';
+
+/**
+ * Validate the `concurrency` option on a batch `ctx.cross()` 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.
+ *
+ * @internal
+ */
+export const normalizeCrossBatchConcurrency = (
+  options: CrossBatchOptions | undefined
+): Result<number | undefined, Error> => {
+  const concurrency = options?.concurrency;
+  if (concurrency === undefined) {
+    return Result.ok();
+  }
+
+  if (!Number.isInteger(concurrency) || concurrency < 1) {
+    return Result.err(
+      new ValidationError(
+        'ctx.cross() batch concurrency must be a positive integer'
+      )
+    );
+  }
+
+  return Result.ok(concurrency);
+};
+
+/**
+ * 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.
+ *
+ * @internal
+ */
+export const createCrossBatchValidationResults = <TCall>(
+  calls: readonly TCall[],
+  error: Error
+): Result<unknown, Error>[] => calls.map(() => Result.err(error));
+
+/**
+ * Claim the next branch index from a shared counter. Safe to call from
+ * multiple worker coroutines because JavaScript is single-threaded between
+ * awaits — the read/increment pair runs without interleaving.
+ *
+ * @internal
+ */
+export const claimNextCrossBatchIndex = <TCall>(
+  nextIndex: { value: number },
+  calls: readonly TCall[]
+): number | undefined => {
+  if (nextIndex.value >= calls.length) {
+    return undefined;
+  }
+
+  const branchIndex = nextIndex.value;
+  nextIndex.value += 1;
+  return branchIndex;
+};

package/src/internal/fork-ctx.ts

@@ -0,0 +1,69 @@
+/**
+ * Internal helper for "forking" a trail context.
+ *
+ * Several execution sites need to derive a child context from a parent
+ * context while **resetting** a well-known set of bound closures (`cross`,
+ * `fire`, `resource`). Those closures capture the parent scope, so reusing
+ * them on the child would re-enter execution with the wrong attribution,
+ * the wrong resource scope, or the wrong fan-out identity. The reset list
+ * is the same at every fork site.
+ *
+ * Codifying the reset list in one helper keeps that contract in a single
+ * place. Callers supply the overrides they need (typically `env`,
+ * `extensions`, and `logger`) and let the helper handle the reset.
+ *
+ * This module is internal — do not export it from the package entry point.
+ *
+ * @remarks
+ * The helper is intentionally generic over the concrete context shape. Some
+ * callers work with the fully-resolved `TrailContext` produced inside the
+ * executor; others work with `Partial<TrailContextInit>` during consumer
+ * context derivation in `fire.ts`. Both shapes share the same reset keys.
+ */
+
+import type { TrailContext, TrailContextInit } from '../types.js';
+
+/** Keys cleared by default when forking a context. */
+export type ForkCtxResetKey = 'cross' | 'fire' | 'resource';
+
+/** Override fields callers are allowed to apply when forking a context. */
+export type ForkCtxOverrides = Readonly<
+  Partial<Pick<TrailContext, 'env' | 'extensions' | 'logger'>>
+>;
+
+const DEFAULT_RESET_KEYS: readonly ForkCtxResetKey[] = [
+  'cross',
+  'fire',
+  'resource',
+];
+
+/**
+ * Fork a parent context into a child context.
+ *
+ * Spreads the parent, clears each reset key to `undefined`, and applies the
+ * supplied overrides last so callers may replace logger, env, and extensions
+ * with branch-local values.
+ *
+ * The generic parameter is constrained to the minimal shape the helper
+ * reads and writes. This lets the helper serve both `TrailContext`
+ * (executor scope) and `Partial<TrailContextInit>` (fire-consumer scope)
+ * without widening the public surface of either type.
+ */
+export const forkCtx = <
+  TCtx extends Partial<
+    Pick<
+      TrailContextInit,
+      'cross' | 'env' | 'extensions' | 'fire' | 'logger' | 'resource'
+    >
+  >,
+>(
+  parentCtx: TCtx,
+  overrides: ForkCtxOverrides = {},
+  reset: readonly ForkCtxResetKey[] = DEFAULT_RESET_KEYS
+): TCtx => {
+  const forked: TCtx = { ...parentCtx };
+  for (const key of reset) {
+    forked[key as keyof TCtx] = undefined as TCtx[keyof TCtx];
+  }
+  return { ...forked, ...overrides };
+};