flowcraft 2.7.1 → 2.8.1

package/dist/index-D3dyjW2G.d.mts

@@ -0,0 +1,1269 @@
+//#region src/errors.d.ts
+/**
+ * A single, comprehensive error class for the framework.
+ * Use this for all errors to ensure consistent structure and easy debugging.
+ */
+declare class FlowcraftError extends Error {
+  readonly message: string;
+  readonly nodeId?: string;
+  readonly blueprintId?: string;
+  readonly executionId?: string;
+  readonly isFatal: boolean;
+  constructor(message: string, options?: {
+    cause?: Error;
+    nodeId?: string;
+    blueprintId?: string;
+    executionId?: string;
+    isFatal?: boolean;
+  });
+}
+//#endregion
+//#region src/node.d.ts
+/** A type guard to reliably distinguish a NodeClass from a NodeFunction. */
+declare function isNodeClass(impl: any): impl is NodeClass;
+/**
+ * A structured, class-based node for complex logic with a safe, granular lifecycle.
+ * This class is generic, allowing implementations to specify the exact context
+ * and dependency types they expect.
+ */
+declare abstract class BaseNode<TContext extends Record<string, any> = Record<string, any>, TDependencies extends RuntimeDependencies = RuntimeDependencies, TInput = any, TOutput = any, TAction extends string = string> {
+  protected params?: Record<string, any> | undefined;
+  protected nodeId?: string | undefined;
+  /**
+   * @param params Static parameters for this node instance, passed from the blueprint.
+   * @param nodeId The ID of the node in the blueprint.
+   */
+  constructor(params?: Record<string, any> | undefined, nodeId?: string | undefined);
+  /**
+   * Phase 1: Gathers and prepares data for execution. This phase is NOT retried on failure.
+   * @param context The node's execution context.
+   * @returns The data needed for the `exec` phase.
+   */
+  prep(context: NodeContext<TContext, TDependencies, TInput>): Promise<any>;
+  /**
+   * Phase 2: Performs the core, isolated logic. This is the ONLY phase that is retried.
+   * @param prepResult The data returned from the `prep` phase.
+   * @param context The node's execution context.
+   */
+  abstract exec(prepResult: any, context: NodeContext<TContext, TDependencies, TInput>): Promise<Omit<NodeResult<TOutput, TAction>, 'error'>>;
+  /**
+   * Phase 3: Processes the result and saves state. This phase is NOT retried.
+   * @param execResult The successful result from the `exec` or `fallback` phase.
+   * @param _context The node's execution context.
+   */
+  post(execResult: Omit<NodeResult<TOutput, TAction>, 'error'>, _context: NodeContext<TContext, TDependencies, TInput>): Promise<NodeResult<TOutput, TAction>>;
+  /**
+   * An optional safety net that runs if all `exec` retries fail.
+   * @param error The final error from the last `exec` attempt.
+   * @param _context The node's execution context.
+   */
+  fallback(error: Error, _context: NodeContext<TContext, TDependencies, TInput>): Promise<Omit<NodeResult<TOutput, TAction>, 'error'>>;
+  /**
+   * An optional cleanup phase for non-retriable errors that occur outside the main `exec` method.
+   * This method is invoked in a `finally` block or equivalent construct if a fatal, unhandled exception occurs in the `prep`, `exec`, or `post` phases.
+   * Allows nodes to perform crucial cleanup, such as closing database connections or releasing locks.
+   * @param _error The error that caused the failure.
+   * @param _context The node's execution context.
+   */
+  recover(_error: Error, _context: NodeContext<TContext, TDependencies, TInput>): Promise<void>;
+}
+//#endregion
+//#region src/container.d.ts
+type ServiceToken<_T = any> = string | symbol;
+declare class DIContainer {
+  private services;
+  private factories;
+  register<T>(token: ServiceToken<T>, implementation: T): void;
+  registerFactory<T>(token: ServiceToken<T>, factory: (container: DIContainer) => T): void;
+  resolve<T>(token: ServiceToken<T>): T;
+  has(token: ServiceToken): boolean;
+  createChild(): DIContainer;
+}
+declare const ServiceTokens: {
+  readonly Logger: symbol;
+  readonly Serializer: symbol;
+  readonly Evaluator: symbol;
+  readonly EventBus: symbol;
+  readonly Orchestrator: symbol;
+  readonly Middleware: symbol;
+  readonly NodeRegistry: symbol;
+  readonly BlueprintRegistry: symbol;
+  readonly Dependencies: symbol;
+};
+//#endregion
+//#region src/runtime/scheduler.d.ts
+interface AwaitingWorkflow {
+  executionId: string;
+  blueprintId: string;
+  serializedContext: string;
+  awaitingNodeId: string;
+  wakeUpAt: string;
+}
+declare class WorkflowScheduler {
+  private runtime;
+  private activeWorkflows;
+  private intervalId?;
+  private checkIntervalMs;
+  constructor(runtime: FlowRuntime<any, any>, checkIntervalMs?: number);
+  start(): void;
+  stop(): void;
+  registerAwaitingWorkflow(executionId: string, blueprintId: string, serializedContext: string, awaitingNodeId: string, wakeUpAt: string): void;
+  unregisterWorkflow(executionId: string): void;
+  private checkAndResumeWorkflows;
+  getActiveWorkflows(): AwaitingWorkflow[];
+}
+//#endregion
+//#region src/runtime/state.d.ts
+declare class WorkflowState<TContext extends Record<string, any>> {
+  private _completedNodes;
+  private errors;
+  private anyFallbackExecuted;
+  private context;
+  private _isAwaiting;
+  private _awaitingNodeIds;
+  private _awaitingDetails;
+  constructor(initialData: Partial<TContext>, context?: IAsyncContext<TContext>);
+  /**
+   * Configure the context to emit events when modified.
+   * This is called after the ExecutionContext is created.
+   */
+  setEventEmitter(eventBus: any, executionId: string, sourceNode?: string): void;
+  addCompletedNode(nodeId: string, output: any): Promise<void>;
+  addError(nodeId: string, error: Error): void;
+  clearError(nodeId: string): void;
+  markFallbackExecuted(): void;
+  getContext(): IAsyncContext<TContext>;
+  getCompletedNodes(): Set<string>;
+  getErrors(): WorkflowError[];
+  getAnyFallbackExecuted(): boolean;
+  markAsAwaiting(nodeId: string, details?: any): Promise<void>;
+  isAwaiting(): boolean;
+  getAwaitingNodeIds(): string[];
+  getAwaitingDetails(nodeId: string): any;
+  clearAwaiting(nodeId?: string): void;
+  getStatus(isTraversalComplete?: boolean): WorkflowResult['status'];
+  toResult(serializer: ISerializer, executionId?: string): Promise<WorkflowResult<TContext>>;
+}
+//#endregion
+//#region src/runtime/executors.d.ts
+interface ExecutionStrategy {
+  execute: (nodeDef: NodeDefinition, context: NodeContext<any, any, any>, executionId?: string, signal?: AbortSignal) => Promise<NodeResult<any, any>>;
+}
+declare class FunctionNodeExecutor implements ExecutionStrategy {
+  private implementation;
+  private maxRetries;
+  private eventBus;
+  constructor(implementation: NodeFunction, maxRetries: number, eventBus: IEventBus);
+  execute(nodeDef: NodeDefinition, context: NodeContext<any, any, any>, executionId?: string, signal?: AbortSignal): Promise<NodeResult<any, any>>;
+}
+declare class ClassNodeExecutor implements ExecutionStrategy {
+  private implementation;
+  private maxRetries;
+  private eventBus;
+  constructor(implementation: NodeClass, maxRetries: number, eventBus: IEventBus);
+  execute(nodeDef: NodeDefinition, context: NodeContext<any, any, any>, executionId?: string, signal?: AbortSignal): Promise<NodeResult<any, any>>;
+}
+type NodeExecutionResult = {
+  status: 'success';
+  result: NodeResult<any, any>;
+} | {
+  status: 'failed_with_fallback';
+  fallbackNodeId: string;
+  error: FlowcraftError;
+} | {
+  status: 'failed';
+  error: FlowcraftError;
+};
+interface NodeExecutorConfig<TContext extends Record<string, any>, TDependencies extends Record<string, any>> {
+  context: ExecutionContext<TContext, TDependencies>;
+  nodeDef: NodeDefinition;
+  strategy: ExecutionStrategy;
+}
+declare class NodeExecutor<TContext extends Record<string, any>, TDependencies extends Record<string, any>> {
+  private context;
+  private nodeDef;
+  private strategy;
+  constructor(config: NodeExecutorConfig<TContext, TDependencies>);
+  execute(input: any): Promise<NodeExecutionResult>;
+}
+//#endregion
+//#region src/runtime/traverser.d.ts
+interface ReadyNode {
+  nodeId: string;
+  nodeDef: NodeDefinition;
+}
+declare class GraphTraverser {
+  private frontier;
+  private allPredecessors;
+  private allSuccessors;
+  private dynamicBlueprint;
+  private completedNodes;
+  private nodesInLoops;
+  constructor(blueprint: WorkflowBlueprint, isStrictMode?: boolean);
+  /**
+   * Clears all nodes from the execution frontier.
+   */
+  clearFrontier(): void;
+  /**
+   * Creates and initializes a GraphTraverser from a saved workflow state.
+   * This is the correct way to prepare a traverser for a `resume` operation.
+   * @param blueprint The workflow blueprint.
+   * @param state The workflow state being resumed.
+   * @returns A configured GraphTraverser instance.
+   */
+  static fromState(blueprint: WorkflowBlueprint, state: WorkflowState<any>): GraphTraverser;
+  private isFallbackNode;
+  private getJoinStrategy;
+  private filterNodesInLoops;
+  private getAllLoopSuccessors;
+  getReadyNodes(): ReadyNode[];
+  hasMoreWork(): boolean;
+  markNodeCompleted(nodeId: string, result: NodeResult<any, any>, nextNodes: NodeDefinition[]): void;
+  getAllNodeIds(): Set<string>;
+  getFallbackNodeIds(): Set<string>;
+  getCompletedNodes(): Set<string>;
+  getDynamicBlueprint(): WorkflowBlueprint;
+  getAllPredecessors(): Map<string, Set<string>>;
+  getAllSuccessors(): Map<string, Set<string>>;
+  getPredecessors(nodeId: string): Set<string>;
+  getSuccessors(nodeId: string): Set<string>;
+  getNodesInLoop(id: string): Set<string>;
+  resetNodeCompletion(nodeId: string): void;
+  getNode(nodeId: string, blueprint: WorkflowBlueprint): NodeDefinition | undefined;
+  addDynamicNode(_nodeId: string, dynamicNode: NodeDefinition, predecessorId: string, gatherNodeId?: string): void;
+  /**
+   * Manually adds a node ID back to the execution frontier.
+   * Used by orchestrators that need fine-grained control over steps.
+   * @param nodeId The ID of the node to add to the frontier.
+   */
+  addToFrontier(nodeId: string): void;
+}
+//#endregion
+//#region src/runtime/types.d.ts
+type NodeExecutorFactory = (context: ExecutionContext<any, any>) => (nodeId: string) => NodeExecutor<any, any>;
+interface ExecutionServices {
+  determineNextNodes: (blueprint: WorkflowBlueprint, nodeId: string, result: NodeResult<any, any>, context: ContextImplementation<any>, executionId?: string) => Promise<{
+    node: NodeDefinition;
+    edge: EdgeDefinition;
+  }[]>;
+  applyEdgeTransform: (edge: EdgeDefinition, sourceResult: NodeResult<any, any>, targetNode: NodeDefinition, context: ContextImplementation<any>, allPredecessors?: Map<string, Set<string>>, executionId?: string) => Promise<void>;
+  resolveNodeInput: (nodeId: string, blueprint: WorkflowBlueprint, context: any) => Promise<any>;
+}
+interface IOrchestrator {
+  run(context: ExecutionContext<any, any>, traverser: GraphTraverser): Promise<WorkflowResult<any>>;
+}
+interface IRuntime<TContext extends Record<string, any> = Record<string, any>, TDependencies extends RuntimeDependencies = RuntimeDependencies> {
+  options: RuntimeOptions<TDependencies>;
+  registry: Map<string, NodeFunction | NodeClass>;
+  executeNode: (blueprint: WorkflowBlueprint, nodeId: string, state: WorkflowState<TContext>, allPredecessors?: Map<string, Set<string>>, functionRegistry?: Map<string, any>, executionId?: string, signal?: AbortSignal) => Promise<NodeResult>;
+  determineNextNodes: (blueprint: WorkflowBlueprint, nodeId: string, result: NodeResult, context: ContextImplementation<TContext>, executionId?: string) => Promise<{
+    node: NodeDefinition;
+    edge: EdgeDefinition;
+  }[]>;
+  applyEdgeTransform: (edge: EdgeDefinition, sourceResult: NodeResult, targetNode: NodeDefinition, context: ContextImplementation<TContext>, allPredecessors?: Map<string, Set<string>>, executionId?: string) => Promise<void>;
+  createForSubflow: (subBlueprint: WorkflowBlueprint, initialSubState: Partial<TContext>, executionId: string, signal?: AbortSignal) => ExecutionContext<TContext, TDependencies>;
+  getExecutorForNode: (nodeId: string, context: ExecutionContext<TContext, TDependencies>) => NodeExecutor<TContext, TDependencies>;
+}
+//#endregion
+//#region src/runtime/runtime.d.ts
+declare class FlowRuntime<TContext extends Record<string, any>, TDependencies extends Record<string, any>> implements IRuntime<TContext, TDependencies> {
+  private container;
+  registry: Map<string, NodeFunction | NodeClass>;
+  private blueprints;
+  dependencies: TDependencies;
+  logger: ILogger;
+  eventBus: IEventBus;
+  serializer: ISerializer;
+  middleware: Middleware[];
+  evaluator: IEvaluator;
+  private analysisCache;
+  orchestrator: IOrchestrator;
+  options: RuntimeOptions<TDependencies>;
+  private readonly logicHandler;
+  private readonly executorFactory;
+  scheduler: WorkflowScheduler;
+  getBlueprint(id: string): WorkflowBlueprint | undefined;
+  constructor(container: DIContainer, options?: RuntimeOptions<TDependencies>);
+  constructor(options: RuntimeOptions<TDependencies>);
+  private _setupExecutionContext;
+  run(blueprint: WorkflowBlueprint, initialState?: Partial<TContext> | string, options?: {
+    functionRegistry?: Map<string, any>;
+    strict?: boolean;
+    signal?: AbortSignal;
+    concurrency?: number;
+  }): Promise<WorkflowResult<TContext>>;
+  startScheduler(checkIntervalMs?: number): void;
+  stopScheduler(): void;
+  private _setupResumedExecutionContext;
+  resume(blueprint: WorkflowBlueprint, serializedContext: string, resumeData: {
+    output?: any;
+    action?: string;
+  }, nodeId?: string, options?: {
+    functionRegistry?: Map<string, any>;
+    strict?: boolean;
+    signal?: AbortSignal;
+    concurrency?: number;
+  }): Promise<WorkflowResult<TContext>>;
+  _createExecutionRegistry(dynamicRegistry?: Map<string, any>): Map<string, NodeFunction | NodeClass>;
+  executeNode(blueprint: WorkflowBlueprint, nodeId: string, state: WorkflowState<TContext>, _allPredecessors?: Map<string, Set<string>>, functionRegistry?: Map<string, any>, executionId?: string, signal?: AbortSignal): Promise<NodeResult<any, any>>;
+  getExecutorForNode(nodeId: string, context: ExecutionContext<TContext, TDependencies>): any;
+  createForSubflow(subBlueprint: WorkflowBlueprint, initialSubState: Partial<TContext>, executionId: string, signal?: AbortSignal): ExecutionContext<TContext, TDependencies>;
+  determineNextNodes(blueprint: WorkflowBlueprint, nodeId: string, result: NodeResult<any, any>, context: ContextImplementation<TContext>, executionId?: string): Promise<{
+    node: NodeDefinition;
+    edge: EdgeDefinition;
+  }[]>;
+  applyEdgeTransform(edge: EdgeDefinition, sourceResult: NodeResult<any, any>, targetNode: NodeDefinition, context: ContextImplementation<TContext>, allPredecessors?: Map<string, Set<string>>, executionId?: string): Promise<void>;
+  resolveNodeInput(nodeId: string, blueprint: WorkflowBlueprint, context: ContextImplementation<TContext>): Promise<any>;
+  /**
+   * Replay a workflow execution from a pre-recorded event history.
+   * This reconstructs the final workflow state without executing any node logic,
+   * enabling time-travel debugging and post-mortem analysis.
+   *
+   * @param blueprint The workflow blueprint
+   * @param events The recorded event history for the execution
+   * @param executionId Optional execution ID to filter events (if events contain multiple executions)
+   * @returns The reconstructed workflow result
+   */
+  replay(blueprint: WorkflowBlueprint, events: FlowcraftEvent[], executionId?: string): Promise<WorkflowResult<TContext>>;
+}
+//#endregion
+//#region src/runtime/execution-context.d.ts
+/**
+ * A container for all state and dependencies of a single workflow execution.
+ * This object is created once per `run` and passed through the execution stack.
+ */
+declare class ExecutionContext<TContext extends Record<string, any>, TDependencies extends RuntimeDependencies> {
+  readonly blueprint: WorkflowBlueprint;
+  readonly state: WorkflowState<TContext>;
+  readonly nodeRegistry: Map<string, NodeFunction | NodeClass>;
+  readonly executionId: string;
+  readonly runtime: FlowRuntime<TContext, TDependencies>;
+  readonly services: {
+    logger: ILogger;
+    eventBus: IEventBus;
+    serializer: ISerializer;
+    evaluator: IEvaluator;
+    middleware: Middleware[];
+    dependencies: TDependencies;
+  };
+  readonly signal?: AbortSignal | undefined;
+  readonly concurrency?: number | undefined;
+  constructor(blueprint: WorkflowBlueprint, state: WorkflowState<TContext>, nodeRegistry: Map<string, NodeFunction | NodeClass>, executionId: string, runtime: FlowRuntime<TContext, TDependencies>, // A reference back to the runtime for orchestrating subflows
+  services: {
+    logger: ILogger;
+    eventBus: IEventBus;
+    serializer: ISerializer;
+    evaluator: IEvaluator;
+    middleware: Middleware[];
+    dependencies: TDependencies;
+  }, signal?: AbortSignal | undefined, concurrency?: number | undefined);
+  createForSubflow(subBlueprint: WorkflowBlueprint, initialSubState: Partial<TContext>): ExecutionContext<TContext, TDependencies>;
+}
+//#endregion
+//#region src/types.d.ts
+/** Source location information for debugging and visualization. */
+interface SourceLocation {
+  file: string;
+  line: number;
+  column: number;
+}
+/** Metadata associated with a workflow blueprint. */
+interface WorkflowBlueprintMetadata {
+  /** Optional version identifier for the blueprint. Used in distributed systems to ensure version compatibility. */
+  version?: string;
+  /** Entry points for cycles in the workflow graph. */
+  cycleEntryPoints?: string[];
+  [key: string]: any;
+}
+/** The central, serializable representation of a workflow. */
+interface WorkflowBlueprint {
+  id: string;
+  nodes: NodeDefinition[];
+  edges: EdgeDefinition[];
+  metadata?: WorkflowBlueprintMetadata;
+}
+/** Defines a single step in the workflow. */
+interface NodeDefinition {
+  id: string;
+  /** A key that resolves to an implementation in a registry. */
+  uses: string;
+  /** Static parameters for the node. */
+  params?: Record<string, any>;
+  /** Maps context data to this node's `input`. */
+  inputs?: string | Record<string, string>;
+  /** Configuration for retries, timeouts, etc. */
+  config?: NodeConfig;
+  /** Source location for debugging and visualization. */
+  _sourceLocation?: SourceLocation;
+}
+/** Defines the connection and data flow between two nodes. */
+interface EdgeDefinition {
+  source: string;
+  target: string;
+  /** An 'action' from the source node that triggers this edge. */
+  action?: string;
+  /** A condition that must be met for this edge to be taken. */
+  condition?: string;
+  /** A string expression to transform the data before passing it to the target node. */
+  transform?: string;
+  /** Source location for debugging and visualization. */
+  _sourceLocation?: SourceLocation;
+}
+/** Configuration for a node's resiliency and behavior. */
+interface NodeConfig {
+  maxRetries?: number;
+  retryDelay?: number;
+  timeout?: number;
+  /** The `uses` key of another node implementation for fallback. */
+  fallback?: string;
+  /** Determines how a node with multiple incoming edges should be triggered. */
+  joinStrategy?: 'all' | 'any';
+}
+/** The required return type for any node implementation. */
+interface NodeResult<TOutput = any, TAction extends string = string> {
+  output?: TOutput;
+  action?: TAction;
+  error?: {
+    message: string;
+    [key: string]: any;
+  };
+  /** Allows a node to dynamically schedule new nodes for the orchestrator to execute. */
+  dynamicNodes?: NodeDefinition[];
+  /** Internal flag: Indicates that this result came from a fallback execution. */
+  _fallbackExecuted?: boolean;
+}
+/** The context object passed to every node's execution logic. */
+interface NodeContext<TContext extends Record<string, any> = Record<string, any>, TDependencies extends RuntimeDependencies = RuntimeDependencies, TInput = any> {
+  /** The async-only interface for interacting with the workflow's state. */
+  context: IAsyncContext<TContext>;
+  /** The primary input data for this node, typically from its predecessor. */
+  input?: TInput;
+  /** Static parameters defined in the blueprint. */
+  params: Record<string, any>;
+  /** Shared, runtime-level dependencies (e.g., database clients, loggers). */
+  dependencies: TDependencies & {
+    runtime: ExecutionContext<TContext, TDependencies>;
+    workflowState: WorkflowState<TContext>;
+  };
+  /** A signal to gracefully cancel long-running node operations. */
+  signal?: AbortSignal;
+}
+/** A simple function-based node implementation. */
+type NodeFunction<TContext extends Record<string, any> = Record<string, any>, TDependencies extends RuntimeDependencies = RuntimeDependencies, TInput = any, TOutput = any, TAction extends string = string> = (context: NodeContext<TContext, TDependencies, TInput>) => Promise<NodeResult<TOutput, TAction>>;
+/** Represents a constructor for any concrete class that extends the abstract BaseNode. */
+type NodeClass<TContext extends Record<string, any> = Record<string, any>, TDependencies extends RuntimeDependencies = RuntimeDependencies, TInput = any, TOutput = any, TAction extends string = string> = new (params?: Record<string, any>, nodeId?: string) => BaseNode<TContext, TDependencies, TInput, TOutput, TAction>;
+/** A union of all possible node implementation types. */
+type NodeImplementation = NodeFunction | NodeClass;
+/** A registry mapping node types to their implementations. */
+type NodeRegistry = Record<string, NodeImplementation>;
+/** A discriminated union for all possible context implementations. */
+type ContextImplementation<T extends Record<string, any>> = ISyncContext<T> | IAsyncContext<T>;
+/** The synchronous context interface for high-performance, in-memory state. */
+interface ISyncContext<TContext extends Record<string, any> = Record<string, any>> {
+  readonly type: 'sync';
+  get<K extends keyof TContext>(key: K): TContext[K] | undefined;
+  get(key: string): any | undefined;
+  set<K extends keyof TContext>(key: K, value: TContext[K]): void;
+  set(key: string, value: any): void;
+  has<K extends keyof TContext>(key: K): boolean;
+  has(key: string): boolean;
+  delete<K extends keyof TContext>(key: K): boolean;
+  delete(key: string): boolean;
+  toJSON: () => Record<string, any>;
+}
+/** The asynchronous context interface for remote or distributed state. */
+interface IAsyncContext<TContext extends Record<string, any> = Record<string, any>> {
+  readonly type: 'async';
+  get<K extends keyof TContext>(key: K): Promise<TContext[K] | undefined>;
+  get(key: string): Promise<any | undefined>;
+  set<K extends keyof TContext>(key: K, value: TContext[K]): Promise<void>;
+  set(key: string, value: any): Promise<void>;
+  has<K extends keyof TContext>(key: K): Promise<boolean>;
+  has(key: string): Promise<boolean>;
+  delete<K extends keyof TContext>(key: K): Promise<boolean>;
+  delete(key: string): Promise<boolean>;
+  toJSON: () => Promise<Record<string, any>>;
+  /**
+   * Applies a batch of patch operations atomically.
+   * More efficient than individual set/delete calls for bulk updates.
+   */
+  patch(operations: PatchOperation[]): Promise<void>;
+}
+/** Represents a single patch operation for delta-based state updates. */
+type PatchOperation = {
+  op: 'set';
+  key: string;
+  value: any;
+} | {
+  op: 'delete';
+  key: string;
+};
+/** Generic for any set of dependencies. */
+interface RuntimeDependencies {
+  [key: string]: any;
+}
+/** Configuration options for the FlowRuntime. */
+interface RuntimeOptions<TDependencies extends RuntimeDependencies = RuntimeDependencies> {
+  /** A registry of globally available node implementations. */
+  registry?: Record<string, NodeFunction | NodeClass | typeof BaseNode>;
+  /** A registry of all available workflow blueprints for subflow execution. */
+  blueprints?: Record<string, WorkflowBlueprint>;
+  /** Shared dependencies to be injected into every node. */
+  dependencies?: TDependencies;
+  /** A pluggable logger for consistent output. */
+  logger?: ILogger;
+  /** A pluggable event bus for observability. */
+  eventBus?: IEventBus;
+  /**
+   * A pluggable evaluator for edge conditions and transforms.
+   * @default new PropertyEvaluator() - A safe evaluator for simple property access.
+   * For complex logic, provide a custom implementation or use the `UnsafeEvaluator`
+   * (not recommended for production).
+   */
+  evaluator?: IEvaluator;
+  /** An array of middleware to wrap node execution. */
+  middleware?: Middleware[];
+  /** A pluggable serializer for handling complex data types in the context. */
+  serializer?: ISerializer;
+  /** A flag to enforce strictness in the workflow. */
+  strict?: boolean;
+}
+/** Interface for a pluggable expression evaluator for conditions and transforms. */
+interface IEvaluator {
+  evaluate: (expression: string, context: Record<string, any>) => any;
+}
+/** Interface for a pluggable logger. */
+interface ILogger {
+  debug: (message: string, meta?: Record<string, any>) => void;
+  info: (message: string, meta?: Record<string, any>) => void;
+  warn: (message: string, meta?: Record<string, any>) => void;
+  error: (message: string, meta?: Record<string, any>) => void;
+}
+/** Structured event types for detailed execution tracing. */
+type FlowcraftEvent = {
+  type: 'workflow:start';
+  payload: {
+    blueprintId: string;
+    executionId: string;
+  };
+} | {
+  type: 'workflow:resume';
+  payload: {
+    blueprintId: string;
+    executionId: string;
+  };
+} | {
+  type: 'workflow:stall';
+  payload: {
+    blueprintId: string;
+    executionId: string;
+    remainingNodes: number;
+  };
+} | {
+  type: 'workflow:pause';
+  payload: {
+    blueprintId: string;
+    executionId: string;
+  };
+} | {
+  type: 'workflow:finish';
+  payload: {
+    blueprintId: string;
+    executionId: string;
+    status: string;
+    errors?: WorkflowError[];
+  };
+} | {
+  type: 'node:start';
+  payload: {
+    nodeId: string;
+    executionId: string;
+    input: any;
+    blueprintId: string;
+  };
+} | {
+  type: 'node:finish';
+  payload: {
+    nodeId: string;
+    result: NodeResult;
+    executionId: string;
+    blueprintId: string;
+  };
+} | {
+  type: 'node:error';
+  payload: {
+    nodeId: string;
+    error: FlowcraftError;
+    executionId: string;
+    blueprintId: string;
+  };
+} | {
+  type: 'node:fallback';
+  payload: {
+    nodeId: string;
+    executionId: string;
+    fallback: string;
+    blueprintId: string;
+  };
+} | {
+  type: 'node:retry';
+  payload: {
+    nodeId: string;
+    attempt: number;
+    executionId: string;
+    blueprintId: string;
+  };
+} | {
+  type: 'node:skipped';
+  payload: {
+    nodeId: string;
+    edge: EdgeDefinition;
+    executionId: string;
+    blueprintId: string;
+  };
+} | {
+  type: 'edge:evaluate';
+  payload: {
+    source: string;
+    target: string;
+    condition?: string;
+    result: boolean;
+  };
+} | {
+  type: 'context:change';
+  payload: {
+    sourceNode: string;
+    key: string;
+    op: 'set' | 'delete';
+    value?: any;
+    executionId: string;
+  };
+} | {
+  type: 'job:enqueued';
+  payload: {
+    runId: string;
+    blueprintId: string;
+    nodeId: string;
+    queueName?: string;
+  };
+} | {
+  type: 'job:processed';
+  payload: {
+    runId: string;
+    blueprintId: string;
+    nodeId: string;
+    duration: number;
+    success: boolean;
+  };
+} | {
+  type: 'job:failed';
+  payload: {
+    runId: string;
+    blueprintId: string;
+    nodeId: string;
+    error: FlowcraftError;
+  };
+} | {
+  type: 'batch:start';
+  payload: {
+    batchId: string;
+    scatterNodeId: string;
+    workerNodeIds: string[];
+  };
+} | {
+  type: 'batch:finish';
+  payload: {
+    batchId: string;
+    gatherNodeId: string;
+    results: any[];
+  };
+};
+/** Interface for a pluggable event bus. */
+interface IEventBus {
+  emit: (event: FlowcraftEvent) => void | Promise<void>;
+}
+/** Interface for a pluggable serializer. */
+interface ISerializer {
+  serialize: (data: Record<string, any>) => string;
+  deserialize: (text: string) => Record<string, any>;
+}
+/** Interface for middleware to handle cross-cutting concerns. */
+interface Middleware<TContext extends Record<string, any> = Record<string, any>> {
+  beforeNode?: (ctx: ContextImplementation<TContext>, nodeId: string) => void | Promise<void>;
+  afterNode?: (ctx: ContextImplementation<TContext>, nodeId: string, result: NodeResult | undefined, error: Error | undefined) => void | Promise<void>;
+  aroundNode?: (ctx: ContextImplementation<TContext>, nodeId: string, next: () => Promise<NodeResult>) => Promise<NodeResult>;
+}
+/** A structured error object returned from a failed workflow execution. */
+interface WorkflowError extends FlowcraftError {
+  timestamp: string;
+  originalError?: any;
+}
+/** The status of a workflow execution. */
+type WorkflowStatus = 'completed' | 'failed' | 'stalled' | 'cancelled' | 'awaiting';
+/** The final result of a workflow execution. */
+interface WorkflowResult<TContext = Record<string, any>> {
+  context: TContext;
+  serializedContext: string;
+  status: WorkflowStatus;
+  errors?: WorkflowError[];
+}
+/** A graph representation of a workflow blueprint. */
+interface UIGraph {
+  nodes: Array<Partial<NodeDefinition> & {
+    id: string;
+    data?: Record<string, any>;
+    type?: string;
+  }>;
+  edges: Array<Partial<EdgeDefinition> & {
+    source: string;
+    target: string;
+    data?: Record<string, any>;
+  }>;
+}
+//#endregion
+//#region src/adapters/persistent-event-bus.d.ts
+/**
+ * Interface for a persistent storage mechanism for events.
+ * Implementations can store events in databases, log streams, files, etc.
+ */
+interface IEventStore {
+  /**
+   * Store an event persistently.
+   * @param event The event to store
+   * @param executionId The execution ID for grouping events
+   */
+  store(event: FlowcraftEvent, executionId: string): Promise<void>;
+  /**
+   * Retrieve all events for a specific execution.
+   * @param executionId The execution ID
+   * @returns Array of events in chronological order
+   */
+  retrieve(executionId: string): Promise<FlowcraftEvent[]>;
+  /**
+   * Retrieve events for multiple executions.
+   * @param executionIds Array of execution IDs
+   * @returns Map of execution ID to array of events
+   */
+  retrieveMultiple(executionIds: string[]): Promise<Map<string, FlowcraftEvent[]>>;
+}
+/**
+ * A pluggable event bus adapter that persists all workflow events
+ * to a configurable storage backend, enabling time-travel debugging and replay.
+ *
+ * @example
+ * ```typescript
+ * // Using a database-backed store
+ * const eventStore = new DatabaseEventStore(dbConnection)
+ * const eventBus = new PersistentEventBusAdapter(eventStore)
+ * const runtime = new FlowRuntime({ eventBus })
+ *
+ * // Later, replay the execution
+ * const events = await eventStore.retrieve(executionId)
+ * const finalState = await runtime.replay(blueprint, events)
+ * ```
+ */
+declare class PersistentEventBusAdapter implements IEventBus {
+  private store;
+  constructor(store: IEventStore);
+  /**
+   * Emit an event by storing it persistently.
+   * Also emits to console for debugging (can be made configurable).
+   */
+  emit(event: FlowcraftEvent): Promise<void>;
+}
+/**
+ * Simple in-memory event store for testing and development.
+ * Not suitable for production use.
+ */
+declare class InMemoryEventStore implements IEventStore {
+  private events;
+  store(event: FlowcraftEvent, executionId: string): Promise<void>;
+  retrieve(executionId: string): Promise<FlowcraftEvent[]>;
+  retrieveMultiple(executionIds: string[]): Promise<Map<string, FlowcraftEvent[]>>;
+  /**
+   * Clear all stored events (useful for testing).
+   */
+  clear(): void;
+}
+//#endregion
+//#region src/analysis.d.ts
+/**
+ * A list of cycles found in the graph. Each cycle is an array of node IDs.
+ */
+type Cycles = string[][];
+/**
+ * Analysis result for a workflow blueprint
+ */
+interface BlueprintAnalysis {
+  /** Cycles found in the graph */
+  cycles: Cycles;
+  /** Node IDs that have no incoming edges (start nodes) */
+  startNodeIds: string[];
+  /** Node IDs that have no outgoing edges (terminal nodes) */
+  terminalNodeIds: string[];
+  /** Total number of nodes */
+  nodeCount: number;
+  /** Total number of edges */
+  edgeCount: number;
+  /** Whether the graph is a valid DAG (no cycles) */
+  isDag: boolean;
+}
+/**
+ * Analyzes a workflow blueprint to detect cycles using an iterative DFS algorithm.
+ * This avoids stack overflow issues for deep graphs compared to the recursive version.
+ * @param blueprint The WorkflowBlueprint object containing nodes and edges.
+ * @returns An array of cycles found. Each cycle is represented as an array of node IDs.
+ */
+declare function checkForCycles(blueprint: WorkflowBlueprint): Cycles;
+/**
+ * Generates Mermaid diagram syntax from a WorkflowBlueprint
+ * @param blueprint The WorkflowBlueprint object containing nodes and edges
+ * @returns Mermaid syntax string for the flowchart
+ */
+declare function generateMermaid(blueprint: WorkflowBlueprint): string;
+/**
+ * Generates Mermaid diagram syntax from a WorkflowBlueprint with execution history styling
+ * @param blueprint The WorkflowBlueprint object containing nodes and edges
+ * @param events Array of FlowcraftEvent objects from the workflow execution
+ * @returns Mermaid syntax string for the flowchart with execution path highlighting
+ */
+declare function generateMermaidForRun(blueprint: WorkflowBlueprint, events: FlowcraftEvent[]): string;
+/**
+ * Analyzes a workflow blueprint and returns comprehensive analysis
+ * @param blueprint The WorkflowBlueprint object containing nodes and edges
+ * @returns Analysis result with cycles, start nodes, terminal nodes, and other metrics
+ */
+declare function analyzeBlueprint(blueprint: WorkflowBlueprint): BlueprintAnalysis;
+//#endregion
+//#region src/container-factory.d.ts
+interface ContainerOptions<TDependencies extends RuntimeDependencies = RuntimeDependencies> {
+  logger?: ILogger;
+  serializer?: ISerializer;
+  evaluator?: IEvaluator;
+  eventBus?: IEventBus;
+  middleware?: Middleware[];
+  registry?: Record<string, NodeFunction | NodeClass>;
+  blueprints?: Record<string, WorkflowBlueprint>;
+  dependencies?: TDependencies;
+}
+declare function createDefaultContainer<TDependencies extends RuntimeDependencies = RuntimeDependencies>(options?: ContainerOptions<TDependencies>): DIContainer;
+//#endregion
+//#region src/context.d.ts
+/**
+ * A default, high-performance, in-memory implementation of ISyncContext using a Map.
+ */
+declare class Context<TContext extends Record<string, any>> implements ISyncContext<TContext> {
+  readonly type: "sync";
+  private data;
+  constructor(initialData?: Partial<TContext>);
+  get<K extends keyof TContext>(key: K): TContext[K] | undefined;
+  set<K extends keyof TContext>(key: K, value: TContext[K]): void;
+  has<K extends keyof TContext>(key: K): boolean;
+  delete<K extends keyof TContext>(key: K): boolean;
+  toJSON(): Record<string, any>;
+}
+/**
+ * An adapter that provides a consistent, Promise-based view of a synchronous context.
+ * This is created by the runtime and is transparent to the node author.
+ */
+declare class AsyncContextView<TContext extends Record<string, any>> implements IAsyncContext<TContext> {
+  private syncContext;
+  readonly type: "async";
+  constructor(syncContext: ISyncContext<TContext>);
+  get<K extends keyof TContext>(key: K): Promise<TContext[K] | undefined>;
+  set<K extends keyof TContext>(key: K, value: TContext[K]): Promise<void>;
+  has<K extends keyof TContext>(key: K): Promise<boolean>;
+  delete<K extends keyof TContext>(key: K): Promise<boolean>;
+  toJSON(): Promise<Record<string, any>>;
+  patch(_operations: PatchOperation[]): Promise<void>;
+}
+/**
+ * A proxy wrapper that tracks changes to an async context for delta-based persistence.
+ * Records all mutations (set/delete operations) to enable efficient partial updates.
+ */
+declare class TrackedAsyncContext<TContext extends Record<string, any>> implements IAsyncContext<TContext> {
+  readonly type: "async";
+  private deltas;
+  private innerContext;
+  private eventBus?;
+  private executionId?;
+  private sourceNode?;
+  constructor(innerContext: IAsyncContext<TContext>, eventBus?: any, executionId?: string, sourceNode?: string);
+  get<K extends keyof TContext>(key: K): Promise<TContext[K] | undefined>;
+  set<K extends keyof TContext>(key: K, value: TContext[K]): Promise<void>;
+  has<K extends keyof TContext>(key: K): Promise<boolean>;
+  delete<K extends keyof TContext>(key: K): Promise<boolean>;
+  toJSON(): Promise<Record<string, any>>;
+  patch(operations: PatchOperation[]): Promise<void>;
+  getDeltas(): PatchOperation[];
+  clearDeltas(): void;
+  /**
+   * Configures the event emitter for tracking context changes.
+   * This enables the context to emit events when set/delete operations occur,
+   * allowing for external monitoring and persistence of context mutations.
+   *
+   * @param eventBus - The event bus instance to emit context change events
+   * @param executionId - The unique identifier for the current workflow execution
+   * @param sourceNode - Optional identifier for the node that triggered the context change
+   */
+  configureEventEmitter(eventBus: any, executionId: string, sourceNode?: string): void;
+}
+//#endregion
+//#region src/error-mapper.d.ts
+/**
+ * Creates an error mapper function that enhances runtime errors with source location information.
+ * The mapper looks up node IDs in the provided manifest blueprints and returns enhanced errors
+ * that point to the original TypeScript source code.
+ *
+ * @param manifestBlueprints - The compiled blueprint manifest containing source location data
+ * @returns A function that maps errors to enhanced errors with source location information
+ */
+declare function createErrorMapper(manifestBlueprints: Record<string, WorkflowBlueprint>): (error: Error) => Error;
+//#endregion
+//#region src/evaluator.d.ts
+/**
+ * A safe evaluator that only allows simple property access.
+ * It cannot execute arbitrary code and is secure for untrusted inputs.
+ *
+ * Example expressions:
+ * - "result.output.status"
+ * - "context.user.isAdmin"
+ * - "input.value"
+ */
+declare class PropertyEvaluator implements IEvaluator {
+  evaluate(expression: string, context: Record<string, any>): any;
+}
+/**
+ * @warning This evaluator uses `new Function()` and can execute arbitrary
+ * JavaScript code. It poses a significant security risk if the expressions
+ * are not from a trusted source (e.g., user input).
+ *
+ * It should only be used in controlled environments where all workflow
+ * definitions are static and authored by trusted developers.
+ *
+ * For safer evaluation, use the default `PropertyEvaluator` or install a
+ * sandboxed library like `jsep` to create a custom, secure evaluator.
+ */
+declare class UnsafeEvaluator implements IEvaluator {
+  evaluate(expression: string, context: Record<string, any>): any;
+}
+//#endregion
+//#region src/flow.d.ts
+/**
+ * A fluent API for programmatically constructing a WorkflowBlueprint.
+ */
+declare class FlowBuilder<TContext extends Record<string, any> = Record<string, any>, TDependencies extends Record<string, any> = Record<string, any>> {
+  private blueprint;
+  private functionRegistry;
+  private loopDefinitions;
+  private batchDefinitions;
+  private cycleEntryPoints;
+  constructor(id: string);
+  node<TInput = any, TOutput = any, TAction extends string = string>(id: string, implementation: NodeFunction<TContext, TDependencies, TInput, TOutput, TAction> | NodeClass<TContext, TDependencies, TInput, TOutput, TAction>, options?: Omit<NodeDefinition, 'id' | 'uses'>): this;
+  edge(source: string, target: string, options?: Omit<EdgeDefinition, 'source' | 'target'>): this;
+  /**
+   * Creates a batch processing pattern.
+   * It takes an input array, runs a worker node on each item in parallel, and gathers the results.
+   * This method augments the Flow's TContext with a new key for the output array.
+   *
+   * @param id The base ID for this batch operation.
+   * @param worker The node implementation to run on each item.
+   * @param options Configuration for the batch operation.
+   * @returns The Flow instance with an updated context type for chaining.
+   */
+  batch<TWorkerInput, TWorkerOutput, TWorkerAction extends string, TOutputKey extends string>(id: string, worker: NodeFunction<TContext, TDependencies, TWorkerInput, TWorkerOutput, TWorkerAction> | NodeClass<TContext, TDependencies, TWorkerInput, TWorkerOutput, TWorkerAction>, options: {
+    /** The key in the context that holds the input array for the batch. */inputKey: keyof TContext; /** The key in the context where the array of results will be stored. */
+    outputKey: TOutputKey; /** The number of items to process in each chunk to limit memory usage. */
+    chunkSize?: number;
+  }): FlowBuilder<TContext & { [K in TOutputKey]: TWorkerOutput[] }, TDependencies>;
+  /**
+   * Creates a sleep node that pauses workflow execution for a specified duration.
+   * @param id A unique identifier for the sleep node.
+   * @param options Configuration for the sleep duration.
+   */
+  sleep(id: string, options: {
+    /** The duration to sleep in milliseconds or a string like '5s', '1m', '2h', '1d'. */duration: number | string;
+  }): this;
+  /**
+   * Creates a wait node that pauses workflow execution for external input.
+   * @param id A unique identifier for the wait node.
+   * @param options Optional configuration for the wait node.
+   */
+  wait(id: string, options?: Omit<NodeDefinition, 'id' | 'uses'>): this;
+  /**
+   * Creates a loop pattern in the workflow graph.
+   * @param id A unique identifier for the loop construct.
+   * @param options Defines the start, end, and continuation condition of the loop.
+   * @param options.startNodeId The ID of the first node inside the loop body.
+   * @param options.endNodeId The ID of the last node inside the loop body.
+   * @param options.condition An expression that, if true, causes the loop to run again.
+   */
+  loop(id: string, options: {
+    /** The ID of the first node inside the loop body. */startNodeId: string; /** The ID of the last node inside the loop body. */
+    endNodeId: string; /** An expression that, if true, causes the loop to run again. */
+    condition: string;
+  }): this;
+  /**
+   * Sets the preferred entry point for a cycle in non-DAG workflows.
+   * This helps remove ambiguity when the runtime needs to choose a starting node for cycles.
+   * @param nodeId The ID of the node to use as the entry point for cycles containing this node.
+   */
+  setCycleEntryPoint(nodeId: string): this;
+  toBlueprint(): WorkflowBlueprint;
+  getFunctionRegistry(): Map<string, NodeFunction | NodeClass>;
+  toGraphRepresentation(): UIGraph;
+}
+/**
+ * Helper function to create a new Flow builder instance.
+ */
+declare function createFlow<TContext extends Record<string, any> = Record<string, any>, TDependencies extends Record<string, any> = Record<string, any>>(id: string): FlowBuilder<TContext, TDependencies>;
+//#endregion
+//#region src/linter.d.ts
+type LinterIssueCode = 'INVALID_EDGE_SOURCE' | 'INVALID_EDGE_TARGET' | 'MISSING_NODE_IMPLEMENTATION' | 'ORPHAN_NODE' | 'INVALID_BATCH_WORKER_KEY' | 'INVALID_SUBFLOW_BLUEPRINT_ID';
+interface LinterIssue {
+  code: LinterIssueCode;
+  message: string;
+  nodeId?: string;
+  relatedId?: string;
+}
+interface LinterResult {
+  isValid: boolean;
+  issues: LinterIssue[];
+}
+/**
+ * Statically analyzes a workflow blueprint against a registry of implementations
+ * to find common errors before runtime.
+ *
+ * @param blueprint The WorkflowBlueprint to analyze.
+ * @param registry A map of node implementations (functions or classes) to check against.
+ * @returns A LinterResult object containing any issues found.
+ */
+declare function lintBlueprint(blueprint: WorkflowBlueprint, registry: Map<string, NodeFunction | NodeClass> | Record<string, NodeFunction | NodeClass>, blueprints?: Record<string, WorkflowBlueprint>): LinterResult;
+//#endregion
+//#region src/logger.d.ts
+/** A logger implementation that outputs to the console. */
+declare class ConsoleLogger implements ILogger {
+  debug(message: string, meta?: Record<string, any>): void;
+  info(message: string, meta?: Record<string, any>): void;
+  warn(message: string, meta?: Record<string, any>): void;
+  error(message: string, meta?: Record<string, any>): void;
+}
+/** A logger implementation that does nothing (no-op). */
+declare class NullLogger implements ILogger {
+  debug(_message: string, _meta?: Record<string, any>): void;
+  info(_message: string, _meta?: Record<string, any>): void;
+  warn(_message: string, _meta?: Record<string, any>): void;
+  error(_message: string, _meta?: Record<string, any>): void;
+}
+//#endregion
+//#region src/runtime/adapter.d.ts
+/**
+ * Defines the contract for an atomic, distributed key-value store required by
+ * the adapter for coordination tasks like fan-in joins and locking.
+ */
+interface ICoordinationStore {
+  /** Atomically increments a key and returns the new value. Ideal for 'all' joins. */
+  increment: (key: string, ttlSeconds: number) => Promise<number>;
+  /** Sets a key only if it does not already exist. Ideal for 'any' joins (locking). */
+  setIfNotExist: (key: string, value: string, ttlSeconds: number) => Promise<boolean>;
+  /** Extends the TTL of an existing key. Used for heartbeat mechanism in long-running jobs. */
+  extendTTL: (key: string, ttlSeconds: number) => Promise<boolean>;
+  /** Deletes a key. Used for cleanup. */
+  delete: (key: string) => Promise<void>;
+  /** Gets the value of a key. */
+  get: (key: string) => Promise<string | undefined>;
+}
+/** Configuration options for constructing a BaseDistributedAdapter. */
+interface AdapterOptions {
+  runtimeOptions: RuntimeOptions<any>;
+  coordinationStore: ICoordinationStore;
+  eventBus?: IEventBus;
+}
+/** The data payload expected for a job in the queue. */
+interface JobPayload {
+  runId: string;
+  blueprintId: string;
+  nodeId: string;
+}
+/**
+ * The base class for all distributed adapters. It handles the technology-agnostic
+ * orchestration logic and leaves queue-specific implementation to subclasses.
+ */
+declare abstract class BaseDistributedAdapter {
+  protected readonly runtime: FlowRuntime<any, any>;
+  protected readonly store: ICoordinationStore;
+  protected readonly serializer: ISerializer;
+  protected readonly logger: ILogger;
+  protected readonly eventBus?: IEventBus;
+  constructor(options: AdapterOptions);
+  /**
+   * Starts the worker, which begins listening for and processing jobs from the queue.
+   */
+  start(): void;
+  /**
+   * Creates a technology-specific distributed context for a given workflow run.
+   * @param runId The unique ID for the workflow execution.
+   */
+  protected abstract createContext(runId: string): IAsyncContext<Record<string, any>>;
+  /**
+   * Sets up the listener for the message queue. The implementation should call the
+   * provided `handler` function for each new job received.
+   * @param handler The core logic to execute for each job.
+   */
+  protected abstract processJobs(handler: (job: JobPayload) => Promise<void>): void;
+  /**
+   * Enqueues a new job onto the message queue.
+   * @param job The payload for the job to be enqueued.
+   */
+  protected abstract enqueueJob(job: JobPayload): Promise<void>;
+  /**
+   * Publishes the final result of a completed or failed workflow run.
+   * @param runId The unique ID of the workflow run.
+   * @param result The final status and payload of the workflow.
+   */
+  protected abstract publishFinalResult(runId: string, result: {
+    status: 'completed' | 'failed';
+    payload?: WorkflowResult;
+    reason?: string;
+  }): Promise<void>;
+  /**
+   * Registers a webhook endpoint for a specific node in a workflow run.
+   * @param runId The unique ID of the workflow run.
+   * @param nodeId The ID of the node that will wait for the webhook.
+   * @returns The URL and event name for the webhook.
+   */
+  abstract registerWebhookEndpoint(runId: string, nodeId: string): Promise<{
+    url: string;
+    event: string;
+  }>;
+  /**
+   * Hook called at the start of job processing. Subclasses can override this
+   * to perform additional setup (e.g., timestamp tracking for reconciliation).
+   */
+  protected onJobStart(_runId: string, _blueprintId: string, _nodeId: string): Promise<void>;
+  /**
+   * The main handler for processing a single job from the queue.
+   */
+  protected handleJob(job: JobPayload): Promise<void>;
+  /**
+   * Encapsulates the fan-in join logic using the coordination store.
+   */
+  protected isReadyForFanIn(runId: string, blueprint: WorkflowBlueprint, targetNodeId: string): Promise<boolean>;
+  /**
+   * Reconciles the state of a workflow run. It inspects the persisted
+   * context to find completed nodes, determines the next set of executable
+   * nodes (the frontier), and enqueues jobs for them if they aren't
+   * already running. This is the core of the resume functionality.
+   *
+   * @param runId The unique ID of the workflow execution to reconcile.
+   * @returns The set of node IDs that were enqueued for execution.
+   */
+  reconcile(runId: string): Promise<Set<string>>;
+  private calculateResumedFrontier;
+  /**
+   * Writes a poison pill for 'all' join successors and a cancellation pill for 'any' join successors of a failed node to prevent stalling or ambiguous states.
+   */
+  private writePoisonPillForSuccessors;
+}
+//#endregion
+//#region src/runtime/orchestrator.d.ts
+declare class DefaultOrchestrator implements IOrchestrator {
+  run(context: ExecutionContext<any, any>, traverser: GraphTraverser): Promise<WorkflowResult<any>>;
+}
+//#endregion
+//#region src/runtime/orchestrators/replay.d.ts
+/**
+ * An orchestrator that replays a pre-recorded sequence of workflow events
+ * to reconstruct the workflow state without executing any node logic.
+ *
+ * This enables time-travel debugging by allowing developers to inspect
+ * the exact state of a workflow at any point in its execution history.
+ */
+declare class ReplayOrchestrator implements IOrchestrator {
+  private events;
+  /**
+   * Creates a new ReplayOrchestrator with a sequence of recorded workflow events.
+   *
+   * @param events - Array of FlowcraftEvent objects representing the recorded workflow execution
+   */
+  constructor(events: FlowcraftEvent[]);
+  /**
+   * Replays the recorded workflow events to reconstruct the workflow state.
+   *
+   * This method filters events for the specific execution, applies each event in sequence
+   * to rebuild the context state, and returns the final reconstructed workflow result.
+   * Replayed executions always have a "completed" status since they reconstruct the final state.
+   *
+   * @param context - The execution context containing state and services
+   * @param _traverser - Graph traverser (unused in replay mode)
+   * @returns Promise resolving to the reconstructed workflow result
+   */
+  run(context: ExecutionContext<any, any>, _traverser: GraphTraverser): Promise<WorkflowResult<any>>;
+  /**
+   * Applies a single workflow event to reconstruct the execution state.
+   *
+   * This method handles different event types by updating the workflow state accordingly,
+   * including node completions, context changes, errors, fallbacks, and workflow control events.
+   *
+   * @param event - The workflow event to apply
+   * @param context - The execution context to update
+   * @param fallbackMap - Map tracking fallback node relationships (fallbackNodeId -> originalNodeId)
+   */
+  private applyEvent;
+}
+//#endregion
+//#region src/runtime/orchestrators/utils.d.ts
+declare function executeBatch(readyNodes: Array<{
+  nodeId: string;
+  nodeDef: any;
+}>, blueprint: WorkflowBlueprint, state: WorkflowState<any>, executorFactory: (nodeId: string) => any, runtime: any, maxConcurrency?: number): Promise<Array<{
+  status: 'fulfilled';
+  value: {
+    nodeId: string;
+    executionResult: NodeExecutionResult;
+  };
+} | {
+  status: 'rejected';
+  reason: {
+    nodeId: string;
+    error: unknown;
+  };
+}>>;
+declare function processResults(settledResults: Array<{
+  status: 'fulfilled';
+  value: {
+    nodeId: string;
+    executionResult: NodeExecutionResult;
+  };
+} | {
+  status: 'rejected';
+  reason: {
+    nodeId: string;
+    error: unknown;
+  };
+}>, traverser: GraphTraverser, state: WorkflowState<any>, runtime: any, _blueprint: WorkflowBlueprint, executionId?: string): Promise<void>;
+//#endregion
+//#region src/sanitizer.d.ts
+/**
+ * Sanitizes a raw workflow blueprint by removing extra properties
+ * added by UI tools (e.g., position, style) and keeping only the
+ * properties defined in NodeDefinition and EdgeDefinition.
+ */
+declare function sanitizeBlueprint(raw: any): WorkflowBlueprint;
+//#endregion
+//#region src/serializer.d.ts
+/**
+ * A default serializer using standard JSON.
+ *
+ * @warning This implementation is lossy and does not handle complex data types
+ * like `Date`, `Map`, `Set`, `undefined`, etc. It is recommended to provide a robust
+ * serializer like `superjson` if working with complex data types.
+ */
+declare class JsonSerializer implements ISerializer {
+  private hasWarned;
+  serialize(data: Record<string, any>): string;
+  deserialize(text: string): Record<string, any>;
+}
+//#endregion
+export { NodeResult as $, checkForCycles as A, IEvaluator as B, Context as C, WorkflowState as Ct, BlueprintAnalysis as D, BaseNode as Dt, createDefaultContainer as E, ServiceTokens as Et, PersistentEventBusAdapter as F, Middleware as G, ILogger as H, ContextImplementation as I, NodeContext as J, NodeClass as K, EdgeDefinition as L, generateMermaidForRun as M, IEventStore as N, Cycles as O, isNodeClass as Ot, InMemoryEventStore as P, NodeRegistry as Q, FlowcraftEvent as R, AsyncContextView as S, NodeExecutorConfig as St, ContainerOptions as T, ServiceToken as Tt, ISerializer as U, IEventBus as V, ISyncContext as W, NodeFunction as X, NodeDefinition as Y, NodeImplementation as Z, FlowBuilder as _, ClassNodeExecutor as _t, ReplayOrchestrator as a, WorkflowBlueprint as at, UnsafeEvaluator as b, NodeExecutionResult as bt, BaseDistributedAdapter as c, WorkflowResult as ct, ConsoleLogger as d, ExecutionServices as dt, PatchOperation as et, NullLogger as f, IOrchestrator as ft, lintBlueprint as g, ReadyNode as gt, LinterResult as h, GraphTraverser as ht, processResults as i, UIGraph as it, generateMermaid as j, analyzeBlueprint as k, FlowcraftError as kt, ICoordinationStore as l, WorkflowStatus as lt, LinterIssueCode as m, NodeExecutorFactory as mt, sanitizeBlueprint as n, RuntimeOptions as nt, DefaultOrchestrator as o, WorkflowBlueprintMetadata as ot, LinterIssue as p, IRuntime as pt, NodeConfig as q, executeBatch as r, SourceLocation as rt, AdapterOptions as s, WorkflowError as st, JsonSerializer as t, RuntimeDependencies as tt, JobPayload as u, FlowRuntime as ut, createFlow as v, ExecutionStrategy as vt, TrackedAsyncContext as w, DIContainer as wt, createErrorMapper as x, NodeExecutor as xt, PropertyEvaluator as y, FunctionNodeExecutor as yt, IAsyncContext as z };
+//# sourceMappingURL=index-D3dyjW2G.d.mts.map