flowcraft 1.0.0 → 2.1.0

package/dist/chunk-5ZWYSKMH.js

@@ -0,0 +1,147 @@
+import { isNodeClass } from './chunk-5QMPFUKA.js';
+
+// src/flow.ts
+function _hashFunction(fn) {
+  const source = fn.toString();
+  let hash = 0;
+  for (let i = 0; i < source.length; i++) {
+    const char = source.charCodeAt(i);
+    hash = (hash << 5) - hash + char;
+    hash = hash & hash;
+  }
+  return Math.abs(hash).toString(16);
+}
+var Flow = class {
+  blueprint;
+  functionRegistry;
+  loopControllerIds;
+  loopDefinitions;
+  constructor(id) {
+    this.blueprint = { id, nodes: [], edges: [] };
+    this.functionRegistry = /* @__PURE__ */ new Map();
+    this.loopControllerIds = /* @__PURE__ */ new Map();
+    this.loopDefinitions = [];
+  }
+  node(id, implementation, options) {
+    let usesKey;
+    if (isNodeClass(implementation)) {
+      usesKey = implementation.name && implementation.name !== "BaseNode" ? implementation.name : `class_${_hashFunction(implementation)}`;
+      this.functionRegistry.set(usesKey, implementation);
+    } else {
+      usesKey = `fn_${_hashFunction(implementation)}`;
+      this.functionRegistry.set(usesKey, implementation);
+    }
+    const nodeDef = { id, uses: usesKey, ...options };
+    this.blueprint.nodes?.push(nodeDef);
+    return this;
+  }
+  edge(source, target, options) {
+    const edgeDef = { source, target, ...options };
+    this.blueprint.edges?.push(edgeDef);
+    return this;
+  }
+  /**
+   * Creates a batch processing pattern.
+   * It takes an input array, runs a worker node on each item in parallel, and gathers the results.
+   * @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.
+   * @param options.inputKey The key in the context that holds the input array for the batch.
+   * @param options.outputKey The key in the context where the array of results will be stored.
+   * @returns The Flow instance for chaining.
+   */
+  batch(id, worker, options) {
+    const { inputKey, outputKey } = options;
+    const scatterId = `${id}_scatter`;
+    const gatherId = `${id}_gather`;
+    let workerUsesKey;
+    if (isNodeClass(worker)) {
+      workerUsesKey = worker.name && worker.name !== "BaseNode" ? worker.name : `class_batch_worker_${_hashFunction(worker)}`;
+      this.functionRegistry.set(workerUsesKey, worker);
+    } else {
+      workerUsesKey = `fn_batch_worker_${_hashFunction(worker)}`;
+      this.functionRegistry.set(workerUsesKey, worker);
+    }
+    this.blueprint.nodes?.push({
+      id: scatterId,
+      uses: "batch-scatter",
+      // built-in
+      inputs: inputKey,
+      params: { workerUsesKey, outputKey, gatherNodeId: gatherId }
+    });
+    this.blueprint.nodes?.push({
+      id: gatherId,
+      uses: "batch-gather",
+      // built-in
+      params: { outputKey },
+      config: { joinStrategy: "all" }
+      // important: must wait for all scattered jobs
+    });
+    this.edge(scatterId, gatherId);
+    return 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, options) {
+    const { startNodeId, endNodeId, condition } = options;
+    const controllerId = `${id}-loop`;
+    this.loopControllerIds.set(id, controllerId);
+    this.loopDefinitions.push({ id, startNodeId, endNodeId });
+    this.blueprint.nodes?.push({
+      id: controllerId,
+      uses: "loop-controller",
+      // built-in
+      params: { condition },
+      config: { joinStrategy: "any" }
+      // to allow re-execution on each loop iteration
+    });
+    this.edge(endNodeId, controllerId);
+    this.edge(controllerId, startNodeId, {
+      action: "continue",
+      transform: `context.${endNodeId}`
+      // pass the end node's value to the start node
+    });
+    return this;
+  }
+  getLoopControllerId(id) {
+    const controllerId = this.loopControllerIds.get(id);
+    if (!controllerId) {
+      throw new Error(`Loop with id '${id}' not found. Ensure you have defined it using the .loop() method.`);
+    }
+    return controllerId;
+  }
+  toBlueprint() {
+    if (!this.blueprint.nodes || this.blueprint.nodes.length === 0) {
+      throw new Error("Cannot build a blueprint with no nodes.");
+    }
+    for (const loopDef of this.loopDefinitions) {
+      const startNode = this.blueprint.nodes?.find((n) => n.id === loopDef.startNodeId);
+      const endNode = this.blueprint.nodes?.find((n) => n.id === loopDef.endNodeId);
+      if (!startNode) {
+        throw new Error(`Loop '${loopDef.id}' references non-existent start node '${loopDef.startNodeId}'.`);
+      }
+      if (!endNode) {
+        throw new Error(`Loop '${loopDef.id}' references non-existent end node '${loopDef.endNodeId}'.`);
+      }
+      startNode.config = { ...startNode.config, joinStrategy: "any" };
+      endNode.config = { ...endNode.config, joinStrategy: "any" };
+    }
+    return this.blueprint;
+  }
+  getFunctionRegistry() {
+    return this.functionRegistry;
+  }
+};
+function createFlow(id) {
+  return new Flow(id);
+}
+
+export { Flow, createFlow };
+//# sourceMappingURL=chunk-5ZWYSKMH.js.map
+//# sourceMappingURL=chunk-5ZWYSKMH.js.map

package/dist/chunk-5ZWYSKMH.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/flow.ts"],"names":[],"mappings":"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","file":"chunk-5ZWYSKMH.js","sourcesContent":["import { isNodeClass } from './node'\nimport type { EdgeDefinition, NodeClass, NodeDefinition, NodeFunction, WorkflowBlueprint } from './types'\n\n/**\n * Generates a deterministic hash for a function based on its source code.\n */\nfunction _hashFunction(fn: NodeFunction<any, any, any, any, any> | NodeClass<any, any, any, any, any>): string {\n\tconst source = fn.toString()\n\tlet hash = 0\n\tfor (let i = 0; i < source.length; i++) {\n\t\tconst char = source.charCodeAt(i)\n\t\thash = (hash << 5) - hash + char\n\t\thash = hash & hash // Convert to 32-bit integer\n\t}\n\treturn Math.abs(hash).toString(16)\n}\n\n/**\n * A fluent API for programmatically constructing a WorkflowBlueprint.\n */\nexport class Flow<\n\tTContext extends Record<string, any> = Record<string, any>,\n\tTDependencies extends Record<string, any> = Record<string, any>,\n> {\n\tprivate blueprint: Partial<WorkflowBlueprint>\n\tprivate functionRegistry: Map<string, NodeFunction | NodeClass>\n\tprivate loopControllerIds: Map<string, string>\n\tprivate loopDefinitions: Array<{\n\t\tid: string\n\t\tstartNodeId: string\n\t\tendNodeId: string\n\t}>\n\n\tconstructor(id: string) {\n\t\tthis.blueprint = { id, nodes: [], edges: [] }\n\t\tthis.functionRegistry = new Map()\n\t\tthis.loopControllerIds = new Map()\n\t\tthis.loopDefinitions = []\n\t}\n\n\tnode<TInput = any, TOutput = any, TAction extends string = string>(\n\t\tid: string,\n\t\timplementation:\n\t\t\t| NodeFunction<TContext, TDependencies, TInput, TOutput, TAction>\n\t\t\t| NodeClass<TContext, TDependencies, TInput, TOutput, TAction>,\n\t\toptions?: Omit<NodeDefinition, 'id' | 'uses'>,\n\t): this {\n\t\tlet usesKey: string\n\n\t\tif (isNodeClass(implementation)) {\n\t\t\tusesKey =\n\t\t\t\timplementation.name && implementation.name !== 'BaseNode'\n\t\t\t\t\t? implementation.name\n\t\t\t\t\t: `class_${_hashFunction(implementation)}`\n\t\t\tthis.functionRegistry.set(usesKey, implementation)\n\t\t} else {\n\t\t\tusesKey = `fn_${_hashFunction(implementation)}`\n\t\t\tthis.functionRegistry.set(usesKey, implementation as unknown as NodeFunction)\n\t\t}\n\n\t\tconst nodeDef: NodeDefinition = { id, uses: usesKey, ...options }\n\t\tthis.blueprint.nodes?.push(nodeDef)\n\t\treturn this\n\t}\n\n\tedge(source: string, target: string, options?: Omit<EdgeDefinition, 'source' | 'target'>): this {\n\t\tconst edgeDef: EdgeDefinition = { source, target, ...options }\n\t\tthis.blueprint.edges?.push(edgeDef)\n\t\treturn this\n\t}\n\n\t/**\n\t * Creates a batch processing pattern.\n\t * It takes an input array, runs a worker node on each item in parallel, and gathers the results.\n\t * @param id The base ID for this batch operation.\n\t * @param worker The node implementation to run on each item.\n\t * @param options Configuration for the batch operation.\n\t * @param options.inputKey The key in the context that holds the input array for the batch.\n\t * @param options.outputKey The key in the context where the array of results will be stored.\n\t * @returns The Flow instance for chaining.\n\t */\n\tbatch<TInput = any, TOutput = any, TAction extends string = string>(\n\t\tid: string,\n\t\tworker:\n\t\t\t| NodeFunction<TContext, TDependencies, TInput, TOutput, TAction>\n\t\t\t| NodeClass<TContext, TDependencies, TInput, TOutput, TAction>,\n\t\toptions: {\n\t\t\t/** The key in the context that holds the input array for the batch. */\n\t\t\tinputKey: string\n\t\t\t/** The key in the context where the array of results will be stored. */\n\t\t\toutputKey: string\n\t\t},\n\t): this {\n\t\tconst { inputKey, outputKey } = options\n\t\tconst scatterId = `${id}_scatter`\n\t\tconst gatherId = `${id}_gather`\n\n\t\t// register worker implementation under a unique key.\n\t\tlet workerUsesKey: string\n\t\tif (isNodeClass(worker)) {\n\t\t\tworkerUsesKey =\n\t\t\t\tworker.name && worker.name !== 'BaseNode' ? worker.name : `class_batch_worker_${_hashFunction(worker)}`\n\t\t\tthis.functionRegistry.set(workerUsesKey, worker)\n\t\t} else {\n\t\t\tworkerUsesKey = `fn_batch_worker_${_hashFunction(worker)}`\n\t\t\tthis.functionRegistry.set(workerUsesKey, worker as unknown as NodeFunction)\n\t\t}\n\n\t\t// scatter node: takes an array and dynamically schedules worker nodes\n\t\tthis.blueprint.nodes?.push({\n\t\t\tid: scatterId,\n\t\t\tuses: 'batch-scatter', // built-in\n\t\t\tinputs: inputKey,\n\t\t\tparams: { workerUsesKey, outputKey, gatherNodeId: gatherId },\n\t\t})\n\n\t\t// gather node: waits for all workers to finish and collects the results\n\t\tthis.blueprint.nodes?.push({\n\t\t\tid: gatherId,\n\t\t\tuses: 'batch-gather', // built-in\n\t\t\tparams: { outputKey },\n\t\t\tconfig: { joinStrategy: 'all' }, // important: must wait for all scattered jobs\n\t\t})\n\n\t\t// edge to connect scatter and gather nodes. orchestrator will manage dynamic workers\n\t\tthis.edge(scatterId, gatherId)\n\n\t\treturn this\n\t}\n\n\t/**\n\t * Creates a loop pattern in the workflow graph.\n\t * @param id A unique identifier for the loop construct.\n\t * @param options Defines the start, end, and continuation condition of the loop.\n\t * @param options.startNodeId The ID of the first node inside the loop body.\n\t * @param options.endNodeId The ID of the last node inside the loop body.\n\t * @param options.condition An expression that, if true, causes the loop to run again.\n\t */\n\tloop(\n\t\tid: string,\n\t\toptions: {\n\t\t\t/** The ID of the first node inside the loop body. */\n\t\t\tstartNodeId: string\n\t\t\t/** The ID of the last node inside the loop body. */\n\t\t\tendNodeId: string\n\t\t\t/** An expression that, if true, causes the loop to run again. */\n\t\t\tcondition: string\n\t\t},\n\t): this {\n\t\tconst { startNodeId, endNodeId, condition } = options\n\t\tconst controllerId = `${id}-loop`\n\n\t\tthis.loopControllerIds.set(id, controllerId)\n\n\t\tthis.loopDefinitions.push({ id, startNodeId, endNodeId })\n\n\t\t// controller node: evaluates the loop condition\n\t\tthis.blueprint.nodes?.push({\n\t\t\tid: controllerId,\n\t\t\tuses: 'loop-controller', // built-in\n\t\t\tparams: { condition },\n\t\t\tconfig: { joinStrategy: 'any' }, // to allow re-execution on each loop iteration\n\t\t})\n\n\t\tthis.edge(endNodeId, controllerId)\n\n\t\tthis.edge(controllerId, startNodeId, {\n\t\t\taction: 'continue',\n\t\t\ttransform: `context.${endNodeId}`, // pass the end node's value to the start node\n\t\t})\n\n\t\treturn this\n\t}\n\n\tgetLoopControllerId(id: string): string {\n\t\tconst controllerId = this.loopControllerIds.get(id)\n\t\tif (!controllerId) {\n\t\t\tthrow new Error(`Loop with id '${id}' not found. Ensure you have defined it using the .loop() method.`)\n\t\t}\n\t\treturn controllerId\n\t}\n\n\ttoBlueprint(): WorkflowBlueprint {\n\t\tif (!this.blueprint.nodes || this.blueprint.nodes.length === 0) {\n\t\t\tthrow new Error('Cannot build a blueprint with no nodes.')\n\t\t}\n\n\t\tfor (const loopDef of this.loopDefinitions) {\n\t\t\tconst startNode = this.blueprint.nodes?.find((n) => n.id === loopDef.startNodeId)\n\t\t\tconst endNode = this.blueprint.nodes?.find((n) => n.id === loopDef.endNodeId)\n\n\t\t\tif (!startNode) {\n\t\t\t\tthrow new Error(`Loop '${loopDef.id}' references non-existent start node '${loopDef.startNodeId}'.`)\n\t\t\t}\n\t\t\tif (!endNode) {\n\t\t\t\tthrow new Error(`Loop '${loopDef.id}' references non-existent end node '${loopDef.endNodeId}'.`)\n\t\t\t}\n\n\t\t\tstartNode.config = { ...startNode.config, joinStrategy: 'any' }\n\t\t\tendNode.config = { ...endNode.config, joinStrategy: 'any' }\n\t\t}\n\n\t\treturn this.blueprint as WorkflowBlueprint\n\t}\n\n\tgetFunctionRegistry() {\n\t\treturn this.functionRegistry\n\t}\n}\n\n/**\n * Helper function to create a new Flow builder instance.\n */\nexport function createFlow<\n\tTContext extends Record<string, any> = Record<string, any>,\n\tTDependencies extends Record<string, any> = Record<string, any>,\n>(id: string): Flow<TContext, TDependencies> {\n\treturn new Flow(id)\n}\n"]}

package/dist/chunk-5ZXV3R5D.js

@@ -0,0 +1,28 @@
+// src/errors.ts
+var NodeExecutionError = class extends Error {
+  constructor(message, nodeId, blueprintId, originalError, executionId) {
+    super(message);
+    this.nodeId = nodeId;
+    this.blueprintId = blueprintId;
+    this.originalError = originalError;
+    this.executionId = executionId;
+    this.name = "NodeExecutionError";
+  }
+};
+var CancelledWorkflowError = class extends Error {
+  constructor(message = "Workflow execution was cancelled.", executionId) {
+    super(message);
+    this.executionId = executionId;
+    this.name = "CancelledWorkflowError";
+  }
+};
+var FatalNodeExecutionError = class extends NodeExecutionError {
+  constructor(message, nodeId, blueprintId, originalError, executionId) {
+    super(message, nodeId, blueprintId, originalError, executionId);
+    this.name = "FatalNodeExecutionError";
+  }
+};
+
+export { CancelledWorkflowError, FatalNodeExecutionError, NodeExecutionError };
+//# sourceMappingURL=chunk-5ZXV3R5D.js.map
+//# sourceMappingURL=chunk-5ZXV3R5D.js.map

package/dist/chunk-5ZXV3R5D.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/errors.ts"],"names":[],"mappings":";AACO,IAAM,kBAAA,GAAN,cAAiC,KAAA,CAAM;AAAA,EAC7C,WAAA,CACC,OAAA,EACgB,MAAA,EACA,WAAA,EACA,eACA,WAAA,EACf;AACD,IAAA,KAAA,CAAM,OAAO,CAAA;AALG,IAAA,IAAA,CAAA,MAAA,GAAA,MAAA;AACA,IAAA,IAAA,CAAA,WAAA,GAAA,WAAA;AACA,IAAA,IAAA,CAAA,aAAA,GAAA,aAAA;AACA,IAAA,IAAA,CAAA,WAAA,GAAA,WAAA;AAGhB,IAAA,IAAA,CAAK,IAAA,GAAO,oBAAA;AAAA,EACb;AACD;AAGO,IAAM,sBAAA,GAAN,cAAqC,KAAA,CAAM;AAAA,EACjD,WAAA,CACC,OAAA,GAAU,mCAAA,EACM,WAAA,EACf;AACD,IAAA,KAAA,CAAM,OAAO,CAAA;AAFG,IAAA,IAAA,CAAA,WAAA,GAAA,WAAA;AAGhB,IAAA,IAAA,CAAK,IAAA,GAAO,wBAAA;AAAA,EACb;AACD;AAGO,IAAM,uBAAA,GAAN,cAAsC,kBAAA,CAAmB;AAAA,EAC/D,WAAA,CAAY,OAAA,EAAiB,MAAA,EAAgB,WAAA,EAAqB,eAAuB,WAAA,EAAsB;AAC9G,IAAA,KAAA,CAAM,OAAA,EAAS,MAAA,EAAQ,WAAA,EAAa,aAAA,EAAe,WAAW,CAAA;AAC9D,IAAA,IAAA,CAAK,IAAA,GAAO,yBAAA;AAAA,EACb;AACD","file":"chunk-5ZXV3R5D.js","sourcesContent":["/** Error thrown when a node fails during execution. */\nexport class NodeExecutionError extends Error {\n\tconstructor(\n\t\tmessage: string,\n\t\tpublic readonly nodeId: string,\n\t\tpublic readonly blueprintId: string,\n\t\tpublic readonly originalError?: Error,\n\t\tpublic readonly executionId?: string,\n\t) {\n\t\tsuper(message)\n\t\tthis.name = 'NodeExecutionError'\n\t}\n}\n\n/** Error thrown when a workflow is gracefully aborted. */\nexport class CancelledWorkflowError extends Error {\n\tconstructor(\n\t\tmessage = 'Workflow execution was cancelled.',\n\t\tpublic readonly executionId?: string,\n\t) {\n\t\tsuper(message)\n\t\tthis.name = 'CancelledWorkflowError'\n\t}\n}\n\n/** Error thrown for a non-recoverable failure that should halt the workflow immediately. */\nexport class FatalNodeExecutionError extends NodeExecutionError {\n\tconstructor(message: string, nodeId: string, blueprintId: string, originalError?: Error, executionId?: string) {\n\t\tsuper(message, nodeId, blueprintId, originalError, executionId)\n\t\tthis.name = 'FatalNodeExecutionError'\n\t}\n}\n"]}

package/dist/chunk-CO5BTPKI.js

@@ -0,0 +1,410 @@
+import { WorkflowState } from './chunk-CSZ6EOWG.js';
+import { GraphTraverser } from './chunk-UMXW3TCY.js';
+import { sanitizeBlueprint } from './chunk-DSYAC4WB.js';
+import { JsonSerializer } from './chunk-CYHZ2YVH.js';
+import { BuiltInNodeExecutor, ClassNodeExecutor, FunctionNodeExecutor } from './chunk-QRMUKDSP.js';
+import { AsyncContextView } from './chunk-KWQHFT7E.js';
+import { CancelledWorkflowError, NodeExecutionError, FatalNodeExecutionError } from './chunk-5ZXV3R5D.js';
+import { PropertyEvaluator } from './chunk-PH2IYZHV.js';
+import { isNodeClass } from './chunk-5QMPFUKA.js';
+import { analyzeBlueprint } from './chunk-HN72TZY5.js';
+import { NullLogger } from './chunk-4PELJWF7.js';
+
+// src/runtime/runtime.ts
+var FlowRuntime = class {
+  registry;
+  blueprints;
+  dependencies;
+  logger;
+  eventBus;
+  serializer;
+  middleware;
+  evaluator;
+  options;
+  constructor(options) {
+    this.registry = options.registry || {};
+    this.blueprints = options.blueprints || {};
+    this.dependencies = options.dependencies || {};
+    this.logger = options.logger || new NullLogger();
+    this.eventBus = options.eventBus || { emit: () => {
+    } };
+    this.serializer = options.serializer || new JsonSerializer();
+    this.middleware = options.middleware || [];
+    this.evaluator = options.evaluator || new PropertyEvaluator();
+    this.options = options;
+  }
+  async run(blueprint, initialState = {}, options) {
+    const executionId = globalThis.crypto?.randomUUID();
+    const startTime = Date.now();
+    const contextData = typeof initialState === "string" ? this.serializer.deserialize(initialState) : initialState;
+    blueprint = sanitizeBlueprint(blueprint);
+    const state = new WorkflowState(contextData);
+    this.logger.info(`Starting workflow execution`, {
+      blueprintId: blueprint.id,
+      executionId
+    });
+    try {
+      await this.eventBus.emit("workflow:start", {
+        blueprintId: blueprint.id,
+        executionId
+      });
+      const analysis = analyzeBlueprint(blueprint);
+      if (options?.strict && !analysis.isDag) {
+        throw new Error(`Workflow '${blueprint.id}' failed strictness check: Cycles are not allowed.`);
+      }
+      if (!analysis.isDag) {
+        this.logger.warn(`Workflow contains cycles`, {
+          blueprintId: blueprint.id
+        });
+      }
+      const traverser = new GraphTraverser(
+        blueprint,
+        this,
+        state,
+        options?.functionRegistry,
+        executionId,
+        options?.signal,
+        options?.concurrency
+      );
+      await traverser.traverse();
+      const status = state.getStatus(traverser.getAllNodeIds(), traverser.getFallbackNodeIds());
+      const result = state.toResult(this.serializer);
+      result.status = status;
+      const duration = Date.now() - startTime;
+      if (status === "stalled") {
+        await this.eventBus.emit("workflow:stall", {
+          blueprintId: blueprint.id,
+          executionId,
+          remainingNodes: traverser.getAllNodeIds().size - state.getCompletedNodes().size
+        });
+      }
+      this.logger.info(`Workflow execution completed`, {
+        blueprintId: blueprint.id,
+        executionId,
+        status,
+        duration,
+        errors: result.errors?.length || 0
+      });
+      await this.eventBus.emit("workflow:finish", {
+        blueprintId: blueprint.id,
+        executionId,
+        status,
+        errors: result.errors
+      });
+      return result;
+    } catch (error) {
+      const duration = Date.now() - startTime;
+      if (error instanceof DOMException ? error.name === "AbortError" : error instanceof CancelledWorkflowError) {
+        this.logger.info(`Workflow execution cancelled`, {
+          blueprintId: blueprint.id,
+          executionId,
+          duration
+        });
+        await this.eventBus.emit("workflow:finish", {
+          blueprintId: blueprint.id,
+          executionId,
+          status: "cancelled",
+          error
+        });
+        return {
+          context: {},
+          serializedContext: "{}",
+          status: "cancelled"
+        };
+      }
+      this.logger.error(`Workflow execution failed`, {
+        blueprintId: blueprint.id,
+        executionId,
+        duration,
+        error: error instanceof Error ? error.message : String(error)
+      });
+      throw error;
+    }
+  }
+  async executeNode(blueprint, nodeId, state, allPredecessors, functionRegistry, executionId, signal) {
+    const nodeDef = blueprint.nodes.find((n) => n.id === nodeId);
+    if (!nodeDef) {
+      throw new NodeExecutionError(
+        `Node '${nodeId}' not found in blueprint.`,
+        nodeId,
+        blueprint.id,
+        void 0,
+        executionId
+      );
+    }
+    const contextImpl = state.getContext();
+    const asyncContext = contextImpl.type === "sync" ? new AsyncContextView(contextImpl) : contextImpl;
+    const nodeContext = {
+      context: asyncContext,
+      input: await this._resolveNodeInput(nodeDef, asyncContext, allPredecessors),
+      params: nodeDef.params || {},
+      dependencies: { ...this.dependencies, logger: this.logger },
+      signal
+    };
+    const beforeHooks = this.middleware.map((m) => m.beforeNode).filter((hook) => !!hook);
+    const afterHooks = this.middleware.map((m) => m.afterNode).filter((hook) => !!hook);
+    const aroundHooks = this.middleware.map((m) => m.aroundNode).filter((hook) => !!hook);
+    const executor = this.getExecutor(nodeDef, functionRegistry);
+    const coreExecution = async () => {
+      let result;
+      let error;
+      try {
+        for (const hook of beforeHooks) await hook(nodeContext.context, nodeId);
+        result = await this.executeWithFallback(
+          blueprint,
+          nodeDef,
+          nodeContext,
+          executor,
+          executionId,
+          signal,
+          state,
+          functionRegistry
+        );
+        return result;
+      } catch (e) {
+        error = e;
+        throw e;
+      } finally {
+        for (const hook of afterHooks) await hook(nodeContext.context, nodeId, result, error);
+      }
+    };
+    let executionChain = coreExecution;
+    for (let i = aroundHooks.length - 1; i >= 0; i--) {
+      const hook = aroundHooks[i];
+      const next = executionChain;
+      executionChain = () => hook(nodeContext.context, nodeId, next);
+    }
+    try {
+      await this.eventBus.emit("node:start", {
+        blueprintId: blueprint.id,
+        nodeId,
+        executionId
+      });
+      const result = await executionChain();
+      await this.eventBus.emit("node:finish", {
+        blueprintId: blueprint.id,
+        nodeId,
+        result,
+        executionId
+      });
+      return result;
+    } catch (error) {
+      await this.eventBus.emit("node:error", {
+        blueprintId: blueprint.id,
+        nodeId,
+        error,
+        executionId
+      });
+      if (error instanceof DOMException && error.name === "AbortError") {
+        throw new CancelledWorkflowError("Workflow cancelled");
+      }
+      throw error instanceof NodeExecutionError ? error : new NodeExecutionError(`Node '${nodeId}' failed execution.`, nodeId, blueprint.id, error, executionId);
+    }
+  }
+  getExecutor(nodeDef, functionRegistry) {
+    if (nodeDef.uses.startsWith("batch-") || nodeDef.uses.startsWith("loop-") || nodeDef.uses === "subflow") {
+      return new BuiltInNodeExecutor((nodeDef2, context) => this._executeBuiltInNode(nodeDef2, context));
+    }
+    const implementation = functionRegistry?.get(nodeDef.uses) || this.registry[nodeDef.uses];
+    if (!implementation) {
+      throw new FatalNodeExecutionError(
+        `Implementation for '${nodeDef.uses}' not found for node '${nodeDef.id}'.`,
+        nodeDef.id,
+        ""
+      );
+    }
+    const maxRetries = nodeDef.config?.maxRetries ?? 1;
+    return isNodeClass(implementation) ? new ClassNodeExecutor(implementation, maxRetries, this.eventBus) : new FunctionNodeExecutor(implementation, maxRetries, this.eventBus);
+  }
+  async executeWithFallback(blueprint, nodeDef, context, executor, executionId, signal, state, functionRegistry) {
+    try {
+      return await executor.execute(nodeDef, context, executionId, signal);
+    } catch (error) {
+      const isFatal = error instanceof FatalNodeExecutionError || error instanceof NodeExecutionError && error.originalError instanceof FatalNodeExecutionError;
+      if (isFatal) throw error;
+      const fallbackNodeId = nodeDef.config?.fallback;
+      if (fallbackNodeId && state) {
+        context.dependencies.logger.warn(`Executing fallback for node`, {
+          nodeId: nodeDef.id,
+          fallbackNodeId,
+          error: error instanceof Error ? error.message : String(error),
+          executionId
+        });
+        await this.eventBus.emit("node:fallback", {
+          blueprintId: blueprint.id,
+          nodeId: nodeDef.id,
+          executionId,
+          fallback: fallbackNodeId
+        });
+        const fallbackNode = blueprint.nodes.find((n) => n.id === fallbackNodeId);
+        if (!fallbackNode) {
+          throw new NodeExecutionError(
+            `Fallback node '${fallbackNodeId}' not found in blueprint.`,
+            nodeDef.id,
+            blueprint.id,
+            void 0,
+            executionId
+          );
+        }
+        const fallbackExecutor = this.getExecutor(fallbackNode, functionRegistry);
+        const fallbackResult = await fallbackExecutor.execute(fallbackNode, context, executionId, signal);
+        state.markFallbackExecuted();
+        state.addCompletedNode(fallbackNodeId, fallbackResult.output);
+        context.dependencies.logger.info(`Fallback execution completed`, {
+          nodeId: nodeDef.id,
+          fallbackNodeId,
+          executionId
+        });
+        return { ...fallbackResult, _fallbackExecuted: true };
+      }
+      throw error;
+    }
+  }
+  async determineNextNodes(blueprint, nodeId, result, context) {
+    const outgoingEdges = blueprint.edges.filter((edge) => edge.source === nodeId);
+    const matched = [];
+    const evaluateEdge = async (edge) => {
+      if (!edge.condition) return true;
+      const contextData = context.type === "sync" ? context.toJSON() : await context.toJSON();
+      return !!this.evaluator.evaluate(edge.condition, {
+        ...contextData,
+        result
+      });
+    };
+    if (result.action) {
+      const actionEdges = outgoingEdges.filter((edge) => edge.action === result.action);
+      for (const edge of actionEdges) {
+        if (await evaluateEdge(edge)) {
+          const targetNode = blueprint.nodes.find((n) => n.id === edge.target);
+          if (targetNode) matched.push({ node: targetNode, edge });
+        }
+      }
+    }
+    if (matched.length === 0) {
+      const defaultEdges = outgoingEdges.filter((edge) => !edge.action);
+      for (const edge of defaultEdges) {
+        if (await evaluateEdge(edge)) {
+          const targetNode = blueprint.nodes.find((n) => n.id === edge.target);
+          if (targetNode) matched.push({ node: targetNode, edge });
+        }
+      }
+    }
+    this.logger.debug(`Determined next nodes for ${nodeId}`, {
+      matchedNodes: matched.map((m) => m.node.id),
+      action: result.action
+    });
+    return matched;
+  }
+  async applyEdgeTransform(edge, sourceResult, targetNode, context, allPredecessors) {
+    const asyncContext = context.type === "sync" ? new AsyncContextView(context) : context;
+    const finalInput = edge.transform ? this.evaluator.evaluate(edge.transform, {
+      input: sourceResult.output,
+      context: await asyncContext.toJSON()
+    }) : sourceResult.output;
+    const inputKey = `${targetNode.id}_input`;
+    await asyncContext.set(inputKey, finalInput);
+    if (targetNode.config?.joinStrategy === "any") {
+      targetNode.inputs = inputKey;
+    } else if (!targetNode.inputs) {
+      const predecessors = allPredecessors?.get(targetNode.id);
+      if (!predecessors || predecessors.size === 1) {
+        targetNode.inputs = inputKey;
+      }
+    }
+  }
+  async _resolveNodeInput(nodeDef, context, allPredecessors) {
+    if (nodeDef.inputs) {
+      if (typeof nodeDef.inputs === "string") return await context.get(nodeDef.inputs);
+      if (typeof nodeDef.inputs === "object") {
+        const input = {};
+        for (const key in nodeDef.inputs) {
+          const contextKey = nodeDef.inputs[key];
+          input[key] = await context.get(contextKey);
+        }
+        return input;
+      }
+    }
+    if (allPredecessors) {
+      const predecessors = allPredecessors.get(nodeDef.id);
+      if (predecessors && predecessors.size === 1) {
+        const singlePredecessorId = predecessors.values().next().value;
+        return await context.get(singlePredecessorId);
+      }
+    }
+    return void 0;
+  }
+  async _executeBuiltInNode(nodeDef, contextImpl) {
+    const context = contextImpl.type === "sync" ? new AsyncContextView(contextImpl) : contextImpl;
+    const { params = {}, id, inputs } = nodeDef;
+    switch (nodeDef.uses) {
+      case "batch-scatter": {
+        const inputArray = await context.get(inputs) || [];
+        if (!Array.isArray(inputArray)) throw new Error(`Input for batch-scatter node '${id}' must be an array.`);
+        const batchId = globalThis.crypto.randomUUID();
+        const dynamicNodes = [];
+        for (let i = 0; i < inputArray.length; i++) {
+          const item = inputArray[i];
+          const itemInputKey = `${id}_${batchId}_item_${i}`;
+          await context.set(itemInputKey, item);
+          dynamicNodes.push({
+            id: `${params.workerUsesKey}_${batchId}_${i}`,
+            uses: params.workerUsesKey,
+            inputs: itemInputKey
+          });
+        }
+        const gatherNodeId = params.gatherNodeId;
+        return { dynamicNodes, output: { gatherNodeId } };
+      }
+      case "batch-gather": {
+        return { output: {} };
+      }
+      case "loop-controller": {
+        const contextData = await context.toJSON();
+        const shouldContinue = !!this.evaluator.evaluate(params.condition, contextData);
+        return { action: shouldContinue ? "continue" : "break" };
+      }
+      case "subflow": {
+        const { blueprintId, inputs: inputMapping, outputs: outputMapping } = params;
+        if (!blueprintId)
+          throw new FatalNodeExecutionError(`Subflow node '${id}' is missing the 'blueprintId' parameter.`, id, "");
+        const subBlueprint = this.blueprints[blueprintId];
+        if (!subBlueprint)
+          throw new FatalNodeExecutionError(
+            `Sub-blueprint with ID '${blueprintId}' not found in runtime registry.`,
+            id,
+            ""
+          );
+        const subflowInitialContext = {};
+        if (inputMapping) {
+          for (const [targetKey, sourceKey] of Object.entries(inputMapping)) {
+            if (await context.has(sourceKey)) {
+              subflowInitialContext[targetKey] = await context.get(sourceKey);
+            }
+          }
+        }
+        const subflowResult = await this.run(subBlueprint, subflowInitialContext);
+        if (subflowResult.status !== "completed")
+          throw new NodeExecutionError(
+            `Sub-workflow '${blueprintId}' did not complete successfully. Status: ${subflowResult.status}`,
+            id,
+            subBlueprint.id
+          );
+        if (outputMapping) {
+          for (const [parentKey, subKey] of Object.entries(outputMapping)) {
+            const subflowFinalContext = subflowResult.context;
+            if (Object.hasOwn(subflowFinalContext, subKey)) {
+              await context.set(parentKey, subflowFinalContext[subKey]);
+            }
+          }
+        }
+        return { output: subflowResult.context };
+      }
+      default:
+        throw new FatalNodeExecutionError(`Unknown built-in node type: '${nodeDef.uses}'`, id, "");
+    }
+  }
+};
+
+export { FlowRuntime };
+//# sourceMappingURL=chunk-CO5BTPKI.js.map
+//# sourceMappingURL=chunk-CO5BTPKI.js.map