flowcraft 2.10.0 → 2.10.1

package/dist/types-BcrXJEPI.d.mts

@@ -0,0 +1,687 @@
+import { t as FlowcraftError } from "./errors-CyyIj3OO.mjs";
+import { t as DIContainer } from "./container-BKdd-9wf.mjs";
+
+//#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/runtime/scheduler.d.ts
+interface AwaitingWorkflow {
+  executionId: string;
+  blueprintId: string;
+  serializedContext: string;
+  awaitingNodeId: string;
+  wakeUpAt: string;
+  functionRegistry?: Map<string, any>;
+}
+declare class WorkflowScheduler {
+  private runtime;
+  private activeWorkflows;
+  private resumeResults;
+  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, functionRegistry?: Map<string, any>): void;
+  unregisterWorkflow(executionId: string): void;
+  private checkAndResumeWorkflows;
+  getActiveWorkflows(): AwaitingWorkflow[];
+  getResumeResult(executionId: string): WorkflowResult | undefined;
+}
+//#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;
+  isLastAttempt?: boolean;
+  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>;
+  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();
+  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;
+  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
+export { FlowRuntime as A, NodeExecutionResult as B, UIGraph as C, WorkflowResult as D, WorkflowError as E, GraphTraverser as F, WorkflowScheduler as G, NodeExecutorConfig as H, ReadyNode as I, BaseNode as K, ClassNodeExecutor as L, IOrchestrator as M, IRuntime as N, WorkflowStatus as O, NodeExecutorFactory as P, ExecutionStrategy as R, SourceLocation as S, WorkflowBlueprintMetadata as T, WorkflowState as U, NodeExecutor as V, AwaitingWorkflow as W, NodeRegistry as _, IEvaluator as a, RuntimeDependencies as b, ISerializer as c, NodeClass as d, NodeConfig as f, NodeImplementation as g, NodeFunction as h, IAsyncContext as i, ExecutionServices as j, ExecutionContext as k, ISyncContext as l, NodeDefinition as m, EdgeDefinition as n, IEventBus as o, NodeContext as p, isNodeClass as q, FlowcraftEvent as r, ILogger as s, ContextImplementation as t, Middleware as u, NodeResult as v, WorkflowBlueprint as w, RuntimeOptions as x, PatchOperation as y, FunctionNodeExecutor as z };

package/dist/types.d.mts

@@ -0,0 +1,2 @@
+import { C as UIGraph, D as WorkflowResult, E as WorkflowError, O as WorkflowStatus, S as SourceLocation, T as WorkflowBlueprintMetadata, _ as NodeRegistry, a as IEvaluator, b as RuntimeDependencies, c as ISerializer, d as NodeClass, f as NodeConfig, g as NodeImplementation, h as NodeFunction, i as IAsyncContext, l as ISyncContext, m as NodeDefinition, n as EdgeDefinition, o as IEventBus, p as NodeContext, r as FlowcraftEvent, s as ILogger, t as ContextImplementation, u as Middleware, v as NodeResult, w as WorkflowBlueprint, x as RuntimeOptions, y as PatchOperation } from "./types-BcrXJEPI.mjs";
+export { ContextImplementation, EdgeDefinition, FlowcraftEvent, IAsyncContext, IEvaluator, IEventBus, ILogger, ISerializer, ISyncContext, Middleware, NodeClass, NodeConfig, NodeContext, NodeDefinition, NodeFunction, NodeImplementation, NodeRegistry, NodeResult, PatchOperation, RuntimeDependencies, RuntimeOptions, SourceLocation, UIGraph, WorkflowBlueprint, WorkflowBlueprintMetadata, WorkflowError, WorkflowResult, WorkflowStatus };

package/dist/types.mjs

@@ -0,0 +1 @@
+export {  };