flowcraft 2.10.0 → 2.10.1

package/dist/runtime/adapter.mjs

@@ -0,0 +1,349 @@
+import { analyzeBlueprint } from "../analysis.mjs";
+import { ConsoleLogger } from "../logger.mjs";
+import { TrackedAsyncContext } from "../context.mjs";
+import { WorkflowState } from "./state.mjs";
+import { JsonSerializer } from "../serializer.mjs";
+import { FlowRuntime } from "./runtime.mjs";
+
+//#region src/runtime/adapter.ts
+/**
+* The base class for all distributed adapters. It handles the technology-agnostic
+* orchestration logic and leaves queue-specific implementation to subclasses.
+*/
+var BaseDistributedAdapter = class {
+	runtime;
+	store;
+	serializer;
+	logger;
+	eventBus;
+	constructor(options) {
+		this.runtime = new FlowRuntime({
+			...options.runtimeOptions,
+			dependencies: {
+				...options.runtimeOptions.dependencies,
+				adapter: this
+			}
+		});
+		this.store = options.coordinationStore;
+		this.serializer = options.runtimeOptions.serializer || new JsonSerializer();
+		this.logger = options.runtimeOptions.logger || new ConsoleLogger();
+		this.eventBus = options.eventBus;
+		this.logger.info("[Adapter] BaseDistributedAdapter initialized.");
+	}
+	/**
+	* Starts the worker, which begins listening for and processing jobs from the queue.
+	*/
+	start() {
+		this.logger.info("[Adapter] Starting worker...");
+		this.processJobs(this.handleJob.bind(this));
+	}
+	/**
+	* Hook called by the execution factory to determine if a node's automatic
+	* retries should be executed synchronously in-process (true) or delegated
+	* to the Queue backoff behavior configured by the adapter (false).
+	*/
+	shouldRetryInProcess(_nodeDef) {
+		return true;
+	}
+	/**
+	* Returns queue-level retry options for enqueuing successor jobs.
+	* Only used when shouldRetryInProcess() returns false.
+	*/
+	getQueueRetryOptions(_nodeDef) {}
+	/**
+	* Hook called at the start of job processing. Subclasses can override this
+	* to perform additional setup (e.g., timestamp tracking for reconciliation).
+	*/
+	async onJobStart(_runId, _blueprintId, _nodeId) {}
+	/**
+	* The main handler for processing a single job from the queue.
+	*/
+	async handleJob(job) {
+		const { runId, blueprintId, nodeId } = job;
+		const startTime = Date.now();
+		await this.onJobStart(runId, blueprintId, nodeId);
+		const blueprint = this.runtime.options.blueprints?.[blueprintId];
+		if (!blueprint) {
+			const reason = `Blueprint with ID '${blueprintId}' not found in the worker's runtime registry.`;
+			this.logger.error(`[Adapter] FATAL: ${reason}`);
+			await this.publishFinalResult(runId, {
+				status: "failed",
+				reason
+			});
+			return;
+		}
+		const context = this.createContext(runId);
+		const storedVersion = await context.get("blueprintVersion");
+		const currentVersion = blueprint.metadata?.version || null;
+		if (storedVersion !== currentVersion) {
+			const reason = `Blueprint version mismatch: stored version '${storedVersion}', current version '${currentVersion}'. Rejecting job to prevent state corruption.`;
+			this.logger.warn(`[Adapter] Version mismatch for run ${runId}, node ${nodeId}: ${reason}`);
+			return;
+		}
+		if (!await context.has("blueprintId")) {
+			await context.set("blueprintId", blueprintId);
+			await context.set("blueprintVersion", blueprint.metadata?.version || null);
+			const blueprintKey = `flowcraft:blueprint:${runId}`;
+			await this.store.setIfNotExist(blueprintKey, blueprintId, 3600);
+		}
+		const joinLockKey = `flowcraft:joinlock:${runId}:${nodeId}`;
+		const fanInKey = `flowcraft:fanin:${runId}:${nodeId}`;
+		const blueprintKey = `flowcraft:blueprint:${runId}`;
+		const heartbeatInterval = setInterval(async () => {
+			await this.store.extendTTL(joinLockKey, 3600);
+			await this.store.extendTTL(fanInKey, 3600);
+			await this.store.extendTTL(blueprintKey, 3600);
+			this.logger.debug(`[Adapter] Extended TTLs for run ${runId}, node ${nodeId}`);
+		}, 18e5);
+		try {
+			const state = new WorkflowState(await context.toJSON(), context);
+			state.isLastAttempt = job.isLastAttempt !== false;
+			let result;
+			if (await context.has(`_outputs.${nodeId}`)) {
+				this.logger.info(`[Adapter] Node '${nodeId}' already completed, skipping re-execution.`);
+				result = { output: await context.get(`_outputs.${nodeId}`) };
+			} else {
+				const nodeDef = blueprint.nodes.find((n) => n.id === nodeId);
+				if (nodeDef && !this.shouldRetryInProcess(nodeDef)) {
+					if (nodeDef.config?.maxRetries && nodeDef.config.maxRetries > 1) nodeDef.config.maxRetries = 1;
+				}
+				result = await this.runtime.executeNode(blueprint, nodeId, state);
+				await context.set(`_outputs.${nodeId}`, result.output);
+				const stateContext = state.getContext();
+				if (stateContext instanceof TrackedAsyncContext) {
+					const deltas = stateContext.getDeltas();
+					if (deltas.length > 0) {
+						await stateContext.patch(deltas);
+						stateContext.clearDeltas();
+					}
+				}
+			}
+			await this.handleNodeCompletion({
+				runId,
+				blueprintId,
+				nodeId,
+				blueprint,
+				result,
+				context,
+				startTime,
+				heartbeatInterval
+			});
+		} catch (error) {
+			const reason = error.message || "Unknown execution error";
+			this.logger.error(`[Adapter] FATAL: Job for node '${nodeId}' failed for Run ID '${runId}': ${reason}`);
+			if (this.eventBus) await this.eventBus.emit({
+				type: "job:failed",
+				payload: {
+					runId,
+					blueprintId,
+					nodeId,
+					error
+				}
+			});
+			if (job.isLastAttempt === false) {
+				this.logger.warn(`[Adapter] Job for node '${nodeId}' failed (queue attempt ${job.attempt || 1}), delegating retry to queue.`);
+				return;
+			}
+			await this.publishFinalResult(runId, {
+				status: "failed",
+				reason
+			});
+			await this.writePoisonPillForSuccessors(runId, blueprint, nodeId);
+		} finally {
+			clearInterval(heartbeatInterval);
+		}
+	}
+	/**
+	* Handles post-execution logic: terminal node checks, successor determination,
+	* and enqueueing of ready nodes. Extracted to support the idempotency guard.
+	*/
+	async handleNodeCompletion(params) {
+		const { runId, blueprintId, nodeId, blueprint, result, context, startTime, heartbeatInterval } = params;
+		const analysis = analyzeBlueprint(blueprint);
+		const isTerminalNode = analysis.terminalNodeIds.includes(nodeId);
+		if (isTerminalNode) {
+			const allContextKeys = Object.keys(await context.toJSON());
+			const completedNodes = /* @__PURE__ */ new Set();
+			for (const key of allContextKeys) if (key.startsWith("_outputs.")) completedNodes.add(key.substring(9));
+			if (analysis.terminalNodeIds.every((terminalId) => completedNodes.has(terminalId))) {
+				this.logger.info(`[Adapter] All terminal nodes completed for Run ID: ${runId}. Declaring workflow complete.`);
+				const finalContext = await context.toJSON();
+				const finalResult = {
+					context: finalContext,
+					serializedContext: this.serializer.serialize(finalContext),
+					status: "completed"
+				};
+				await this.publishFinalResult(runId, {
+					status: "completed",
+					payload: finalResult
+				});
+				clearInterval(heartbeatInterval);
+				return;
+			} else this.logger.info(`[Adapter] Terminal node '${nodeId}' completed for Run ID '${runId}', but other terminal nodes are still running.`);
+		}
+		const nextNodes = await this.runtime.determineNextNodes(blueprint, nodeId, result, context, runId);
+		if (nextNodes.length === 0 && !isTerminalNode) {
+			this.logger.info(`[Adapter] Non-terminal node '${nodeId}' reached end of branch for Run ID '${runId}'. This branch will now terminate.`);
+			clearInterval(heartbeatInterval);
+			return;
+		}
+		for (const { node: nextNodeDef, edge } of nextNodes) {
+			await this.runtime.applyEdgeTransform(edge, result, nextNodeDef, context, void 0, runId);
+			if (await this.isReadyForFanIn(runId, blueprint, nextNodeDef.id)) {
+				this.logger.info(`[Adapter] Node '${nextNodeDef.id}' is ready. Enqueuing job.`);
+				await this.enqueueJob({
+					runId,
+					blueprintId,
+					nodeId: nextNodeDef.id
+				});
+				if (this.eventBus) await this.eventBus.emit({
+					type: "job:enqueued",
+					payload: {
+						runId,
+						blueprintId,
+						nodeId: nextNodeDef.id
+					}
+				});
+			} else this.logger.info(`[Adapter] Node '${nextNodeDef.id}' is waiting for other predecessors to complete.`);
+		}
+		const duration = Date.now() - startTime;
+		if (this.eventBus) await this.eventBus.emit({
+			type: "job:processed",
+			payload: {
+				runId,
+				blueprintId,
+				nodeId,
+				duration,
+				success: true
+			}
+		});
+	}
+	/**
+	* Encapsulates the fan-in join logic using the coordination store.
+	*/
+	async isReadyForFanIn(runId, blueprint, targetNodeId) {
+		const targetNode = blueprint.nodes.find((n) => n.id === targetNodeId);
+		if (!targetNode) throw new Error(`Node '${targetNodeId}' not found in blueprint`);
+		const joinStrategy = targetNode.config?.joinStrategy || "all";
+		const predecessors = blueprint.edges.filter((e) => e.target === targetNodeId);
+		if (predecessors.length <= 1) return true;
+		const poisonKey = `flowcraft:fanin:poison:${runId}:${targetNodeId}`;
+		if (await this.store.get(poisonKey)) {
+			this.logger.info(`[Adapter] Node '${targetNodeId}' is poisoned due to failed predecessor. Failing immediately.`);
+			throw new Error(`Node '${targetNodeId}' failed due to poisoned predecessor in run '${runId}'`);
+		}
+		if (joinStrategy === "any") {
+			const lockKey = `flowcraft:joinlock:${runId}:${targetNodeId}`;
+			if (!await this.store.setIfNotExist(lockKey, "locked", 3600)) {
+				const cancelKey = `flowcraft:fanin:cancel:${runId}:${targetNodeId}`;
+				if (!await this.store.setIfNotExist(cancelKey, "cancelled", 3600)) {
+					this.logger.info(`[Adapter] Node '${targetNodeId}' is cancelled due to failed predecessor. Failing immediately.`);
+					throw new Error(`Node '${targetNodeId}' failed due to cancelled predecessor in run '${runId}'`);
+				}
+				return false;
+			}
+			return true;
+		} else {
+			const fanInKey = `flowcraft:fanin:${runId}:${targetNodeId}`;
+			if (await this.store.increment(fanInKey, 3600) >= predecessors.length) {
+				await this.store.delete(fanInKey);
+				return true;
+			}
+			return false;
+		}
+	}
+	/**
+	* 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.
+	*/
+	async reconcile(runId) {
+		const context = this.createContext(runId);
+		let blueprintId = await context.get("blueprintId");
+		if (!blueprintId) {
+			const blueprintKey = `flowcraft:blueprint:${runId}`;
+			blueprintId = await this.store.get(blueprintKey);
+			if (blueprintId) await context.set("blueprintId", blueprintId);
+			else throw new Error(`Cannot reconcile runId '${runId}': blueprintId not found in context or coordination store.`);
+		}
+		const blueprint = this.runtime.options.blueprints?.[blueprintId];
+		if (blueprint && !await context.has("blueprintVersion")) await context.set("blueprintVersion", blueprint.metadata?.version || null);
+		if (!blueprint) throw new Error(`Cannot reconcile runId '${runId}': Blueprint with ID '${blueprintId}' not found.`);
+		const state = await context.toJSON();
+		const completedNodes = /* @__PURE__ */ new Set();
+		for (const key of Object.keys(state)) if (key.startsWith("_outputs.")) completedNodes.add(key.substring(9));
+		const frontier = this.calculateResumedFrontier(blueprint, completedNodes);
+		const enqueuedNodes = /* @__PURE__ */ new Set();
+		for (const nodeId of frontier) {
+			const joinStrategy = blueprint.nodes.find((n) => n.id === nodeId)?.config?.joinStrategy || "all";
+			const poisonKey = `flowcraft:fanin:poison:${runId}:${nodeId}`;
+			if (await this.store.get(poisonKey)) {
+				this.logger.info(`[Adapter] Reconciling: Node '${nodeId}' is poisoned, skipping.`, { runId });
+				continue;
+			}
+			let shouldEnqueue = false;
+			if (joinStrategy === "any") {
+				const lockKey = `flowcraft:joinlock:${runId}:${nodeId}`;
+				if (await this.store.setIfNotExist(lockKey, "locked-by-reconcile", 3600)) shouldEnqueue = true;
+				else this.logger.info(`[Adapter] Reconciling: Node '${nodeId}' is an 'any' join and is already locked.`, { runId });
+			} else {
+				const lockKey = `flowcraft:nodelock:${runId}:${nodeId}`;
+				if (await this.store.setIfNotExist(lockKey, "locked", 120)) shouldEnqueue = true;
+				else this.logger.info(`[Adapter] Reconciling: Node '${nodeId}' is already locked.`, { runId });
+			}
+			if (shouldEnqueue) {
+				this.logger.info(`[Adapter] Reconciling: Enqueuing ready job for node '${nodeId}'`, { runId });
+				await this.enqueueJob({
+					runId,
+					blueprintId: blueprint.id,
+					nodeId
+				});
+				enqueuedNodes.add(nodeId);
+			}
+		}
+		return enqueuedNodes;
+	}
+	calculateResumedFrontier(blueprint, completedNodes) {
+		const newFrontier = /* @__PURE__ */ new Set();
+		const allPredecessors = /* @__PURE__ */ new Map();
+		for (const node of blueprint.nodes) allPredecessors.set(node.id, /* @__PURE__ */ new Set());
+		for (const edge of blueprint.edges) allPredecessors.get(edge.target)?.add(edge.source);
+		for (const node of blueprint.nodes) {
+			if (completedNodes.has(node.id)) continue;
+			const predecessors = allPredecessors.get(node.id) ?? /* @__PURE__ */ new Set();
+			if (predecessors.size === 0 && !completedNodes.has(node.id)) {
+				newFrontier.add(node.id);
+				continue;
+			}
+			const joinStrategy = node.config?.joinStrategy || "all";
+			const completedPredecessors = [...predecessors].filter((p) => completedNodes.has(p));
+			if (joinStrategy === "any" ? completedPredecessors.length > 0 : completedPredecessors.length === predecessors.size) newFrontier.add(node.id);
+		}
+		return newFrontier;
+	}
+	/**
+	* 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.
+	*/
+	async writePoisonPillForSuccessors(runId, blueprint, failedNodeId) {
+		const successors = blueprint.edges.filter((edge) => edge.source === failedNodeId).map((edge) => edge.target).map((targetId) => blueprint.nodes.find((node) => node.id === targetId)).filter((node) => node);
+		for (const successor of successors) if (successor) {
+			const joinStrategy = successor.config?.joinStrategy || "all";
+			if (joinStrategy === "all") {
+				const poisonKey = `flowcraft:fanin:poison:${runId}:${successor.id}`;
+				await this.store.setIfNotExist(poisonKey, "poisoned", 3600);
+				this.logger.info(`[Adapter] Wrote poison pill for 'all' join node '${successor.id}' due to failed predecessor '${failedNodeId}'`);
+			} else if (joinStrategy === "any") {
+				const cancelKey = `flowcraft:fanin:cancel:${runId}:${successor.id}`;
+				await this.store.setIfNotExist(cancelKey, "cancelled", 3600);
+				this.logger.info(`[Adapter] Wrote cancellation pill for 'any' join node '${successor.id}' due to failed predecessor '${failedNodeId}'`);
+			}
+		}
+	}
+};
+
+//#endregion
+export { BaseDistributedAdapter };

package/dist/runtime/builtin-keys.d.mts

@@ -0,0 +1,37 @@
+//#region src/runtime/builtin-keys.d.ts
+/**
+ * A registry defining the dynamic context keys set by each built-in node.
+ * This object is the single source of truth.
+ */
+declare const BUILTIN_KEYS: {
+  readonly 'batch-scatter': readonly ["currentIndex", "hasMore"];
+  readonly 'batch-gather': readonly ["allWorkerIds", "hasMore"];
+};
+/**
+ * A comprehensive map of all possible dynamic keys to their corresponding TypeScript types.
+ * The compiler will enforce that any key used in `BUILTIN_KEYS` must have an entry here.
+ */
+type DynamicKeyTypeMap = {
+  currentIndex: number;
+  hasMore: boolean;
+  allWorkerIds: string[];
+};
+/**
+ * A utility type that creates a union of all possible dynamic key strings
+ * by flattening the values of the `BUILTIN_KEYS` object.
+ *
+ * Example: 'currentIndex' | 'hasMore' | 'allWorkerIds'
+ */
+type AllDynamicKeyStrings = (typeof BUILTIN_KEYS)[keyof typeof BUILTIN_KEYS][number];
+/**
+ * The final, dynamically generated `DynamicKeys` type.
+ *
+ * It uses a mapped type to construct an object where:
+ * - The keys are the union of all strings from `AllDynamicKeyStrings`.
+ * - The value for each key is looked up from our central `DynamicKeyTypeMap`.
+ *
+ * This ensures that `DynamicKeys` is always perfectly in sync with `BUILTIN_KEYS`.
+ */
+type DynamicKeys = { [K in AllDynamicKeyStrings]: DynamicKeyTypeMap[K] };
+//#endregion
+export { BUILTIN_KEYS, DynamicKeys };

package/dist/runtime/builtin-keys.mjs

@@ -0,0 +1,12 @@
+//#region src/runtime/builtin-keys.ts
+/**
+* A registry defining the dynamic context keys set by each built-in node.
+* This object is the single source of truth.
+*/
+const BUILTIN_KEYS = {
+	"batch-scatter": ["currentIndex", "hasMore"],
+	"batch-gather": ["allWorkerIds", "hasMore"]
+};
+
+//#endregion
+export { BUILTIN_KEYS };

package/dist/runtime/execution-context.d.mts

@@ -0,0 +1,2 @@
+import { k as ExecutionContext } from "../types-BcrXJEPI.mjs";
+export { ExecutionContext };

package/dist/runtime/execution-context.mjs

@@ -0,0 +1,26 @@
+import { WorkflowState } from "./state.mjs";
+
+//#region src/runtime/execution-context.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.
+*/
+var ExecutionContext = class ExecutionContext {
+	constructor(blueprint, state, nodeRegistry, executionId, runtime, services, signal, concurrency) {
+		this.blueprint = blueprint;
+		this.state = state;
+		this.nodeRegistry = nodeRegistry;
+		this.executionId = executionId;
+		this.runtime = runtime;
+		this.services = services;
+		this.signal = signal;
+		this.concurrency = concurrency;
+		this.state.setEventEmitter(this.services.eventBus, this.executionId);
+	}
+	createForSubflow(subBlueprint, initialSubState) {
+		return new ExecutionContext(subBlueprint, new WorkflowState(initialSubState), this.nodeRegistry, this.executionId, this.runtime, this.services, this.signal, this.concurrency);
+	}
+};
+
+//#endregion
+export { ExecutionContext };

package/dist/runtime/executors.d.mts

@@ -0,0 +1,2 @@
+import { B as NodeExecutionResult, H as NodeExecutorConfig, L as ClassNodeExecutor, R as ExecutionStrategy, V as NodeExecutor, z as FunctionNodeExecutor } from "../types-BcrXJEPI.mjs";
+export { ClassNodeExecutor, ExecutionStrategy, FunctionNodeExecutor, NodeExecutionResult, NodeExecutor, NodeExecutorConfig };

package/dist/runtime/executors.mjs

@@ -0,0 +1,259 @@
+import { FlowcraftError } from "../errors.mjs";
+
+//#region src/runtime/executors.ts
+async function withRetries(executor, maxRetries, nodeDef, context, executionId, signal, eventBus) {
+	let lastError;
+	for (let attempt = 1; attempt <= maxRetries; attempt++) try {
+		signal?.throwIfAborted();
+		const result = await executor();
+		if (attempt > 1) context.dependencies.logger.info(`Node execution succeeded after retry`, {
+			nodeId: nodeDef.id,
+			attempt,
+			executionId
+		});
+		return result;
+	} catch (error) {
+		lastError = error;
+		if (error instanceof DOMException && error.name === "AbortError") throw new FlowcraftError("Workflow cancelled", { isFatal: false });
+		if (error instanceof FlowcraftError && error.isFatal) break;
+		if (attempt < maxRetries) {
+			context.dependencies.logger.warn(`Node execution failed, retrying`, {
+				nodeId: nodeDef.id,
+				attempt,
+				maxRetries,
+				error: error instanceof Error ? error.message : String(error),
+				executionId
+			});
+			if (eventBus) await eventBus.emit({
+				type: "node:retry",
+				payload: {
+					nodeId: nodeDef.id,
+					attempt,
+					executionId: executionId || "",
+					blueprintId: context.dependencies.blueprint?.id || ""
+				}
+			});
+		} else context.dependencies.logger.error(`Node execution failed after all retries`, {
+			nodeId: nodeDef.id,
+			attempts: maxRetries,
+			error: error instanceof Error ? error.message : String(error),
+			executionId
+		});
+	}
+	throw lastError;
+}
+var FunctionNodeExecutor = class {
+	constructor(implementation, maxRetries, eventBus) {
+		this.implementation = implementation;
+		this.maxRetries = maxRetries;
+		this.eventBus = eventBus;
+	}
+	async execute(nodeDef, context, executionId, signal) {
+		return withRetries(() => this.implementation(context), this.maxRetries, nodeDef, context, executionId, signal, this.eventBus);
+	}
+};
+var ClassNodeExecutor = class {
+	constructor(implementation, maxRetries, eventBus) {
+		this.implementation = implementation;
+		this.maxRetries = maxRetries;
+		this.eventBus = eventBus;
+	}
+	async execute(nodeDef, context, executionId, signal) {
+		const instance = new this.implementation(nodeDef.params || {}, nodeDef.id);
+		let lastError;
+		try {
+			signal?.throwIfAborted();
+			const prepResult = await instance.prep(context);
+			let execResult;
+			try {
+				execResult = await withRetries(() => instance.exec(prepResult, context), this.maxRetries, nodeDef, context, executionId, signal, this.eventBus);
+			} catch (error) {
+				lastError = error instanceof Error ? error : new Error(String(error));
+				if (error instanceof DOMException && error.name === "AbortError") throw new FlowcraftError("Workflow cancelled", { isFatal: false });
+				if (error instanceof FlowcraftError && error.isFatal) throw error;
+			}
+			if (lastError) {
+				signal?.throwIfAborted();
+				execResult = await instance.fallback(lastError, context);
+			}
+			signal?.throwIfAborted();
+			if (!execResult) throw new Error("Execution failed after all retries");
+			return await instance.post(execResult, context);
+		} catch (error) {
+			lastError = error instanceof Error ? error : new Error(String(error));
+			if (error instanceof DOMException && error.name === "AbortError") throw new FlowcraftError("Workflow cancelled", { isFatal: false });
+			throw error;
+		} finally {
+			if (lastError) try {
+				await instance.recover(lastError, context);
+			} catch (recoverError) {
+				context.dependencies.logger.warn(`Recover phase failed`, {
+					nodeId: nodeDef.id,
+					originalError: lastError.message,
+					recoverError: recoverError instanceof Error ? recoverError.message : String(recoverError),
+					executionId
+				});
+			}
+		}
+	}
+};
+var NodeExecutor = class {
+	context;
+	nodeDef;
+	strategy;
+	constructor(config) {
+		this.context = config.context;
+		this.nodeDef = config.nodeDef;
+		this.strategy = config.strategy;
+	}
+	async execute(input) {
+		const nodeContext = {
+			context: this.context.state.getContext(),
+			input,
+			params: this.nodeDef.params || {},
+			dependencies: {
+				...this.context.services.dependencies,
+				logger: this.context.services.logger,
+				runtime: this.context,
+				workflowState: this.context.state
+			},
+			signal: this.context.signal
+		};
+		const beforeHooks = this.context.services.middleware.map((m) => m.beforeNode).filter((hook) => !!hook);
+		const afterHooks = this.context.services.middleware.map((m) => m.afterNode).filter((hook) => !!hook);
+		const aroundHooks = this.context.services.middleware.map((m) => m.aroundNode).filter((hook) => !!hook);
+		const coreExecution = async () => {
+			let result;
+			let error;
+			try {
+				for (const hook of beforeHooks) await hook(nodeContext.context, this.nodeDef.id);
+				result = await this.strategy.execute(this.nodeDef, nodeContext, this.context.executionId, this.context.signal);
+				return {
+					status: "success",
+					result
+				};
+			} catch (e) {
+				error = e instanceof Error ? e : new Error(String(e));
+				const flowcraftError = error instanceof FlowcraftError ? error : new FlowcraftError(`Node '${this.nodeDef.id}' execution failed`, {
+					cause: error,
+					nodeId: this.nodeDef.id,
+					blueprintId: this.context.blueprint.id,
+					executionId: this.context.executionId,
+					isFatal: false
+				});
+				const fallbackNodeId = this.nodeDef.config?.fallback;
+				const isLastAttempt = this.context.state.isLastAttempt ?? true;
+				if (fallbackNodeId && !flowcraftError.isFatal && isLastAttempt) {
+					this.context.services.logger.warn(`Node failed, fallback required`, {
+						nodeId: this.nodeDef.id,
+						fallbackNodeId,
+						error: error.message,
+						executionId: this.context.executionId
+					});
+					await this.context.services.eventBus.emit({
+						type: "node:fallback",
+						payload: {
+							nodeId: this.nodeDef.id,
+							executionId: this.context.executionId || "",
+							fallback: fallbackNodeId,
+							blueprintId: this.context.blueprint.id
+						}
+					});
+					return {
+						status: "failed_with_fallback",
+						fallbackNodeId,
+						error: flowcraftError
+					};
+				}
+				return {
+					status: "failed",
+					error: flowcraftError
+				};
+			} finally {
+				for (const hook of afterHooks) await hook(nodeContext.context, this.nodeDef.id, result, error);
+			}
+		};
+		let executionChain = coreExecution;
+		for (let i = aroundHooks.length - 1; i >= 0; i--) {
+			const hook = aroundHooks[i];
+			const next = executionChain;
+			executionChain = async () => {
+				let capturedResult;
+				const middlewareResult = await hook(nodeContext.context, this.nodeDef.id, async () => {
+					capturedResult = await next();
+					if (capturedResult.status === "success") return capturedResult.result;
+					throw capturedResult.error;
+				});
+				if (!capturedResult && middlewareResult) return {
+					status: "success",
+					result: middlewareResult
+				};
+				if (!capturedResult) throw new Error("Middleware did not call next() and did not return a result");
+				return capturedResult;
+			};
+		}
+		try {
+			await this.context.services.eventBus.emit({
+				type: "node:start",
+				payload: {
+					nodeId: this.nodeDef.id,
+					executionId: this.context.executionId || "",
+					input: nodeContext.input,
+					blueprintId: this.context.blueprint.id
+				}
+			});
+			const executionResult = await executionChain();
+			if (executionResult.status === "success") await this.context.services.eventBus.emit({
+				type: "node:finish",
+				payload: {
+					nodeId: this.nodeDef.id,
+					result: executionResult.result,
+					executionId: this.context.executionId || "",
+					blueprintId: this.context.blueprint.id
+				}
+			});
+			else await this.context.services.eventBus.emit({
+				type: "node:error",
+				payload: {
+					nodeId: this.nodeDef.id,
+					error: executionResult.error,
+					executionId: this.context.executionId || "",
+					blueprintId: this.context.blueprint.id
+				}
+			});
+			return executionResult;
+		} catch (error) {
+			const err = error instanceof Error ? error : new Error(String(error));
+			const flowcraftError = err instanceof FlowcraftError ? err : new FlowcraftError(`Node '${this.nodeDef.id}' failed execution.`, {
+				cause: err,
+				nodeId: this.nodeDef.id,
+				blueprintId: this.context.blueprint.id,
+				executionId: this.context.executionId,
+				isFatal: false
+			});
+			await this.context.services.eventBus.emit({
+				type: "node:error",
+				payload: {
+					nodeId: this.nodeDef.id,
+					error: flowcraftError,
+					executionId: this.context.executionId || "",
+					blueprintId: this.context.blueprint.id
+				}
+			});
+			if (error instanceof DOMException && error.name === "AbortError") throw new FlowcraftError("Workflow cancelled", {
+				executionId: this.context.executionId,
+				isFatal: false
+			});
+			throw error instanceof FlowcraftError && !error.isFatal ? error : new FlowcraftError(`Node '${this.nodeDef.id}' failed execution.`, {
+				cause: error,
+				nodeId: this.nodeDef.id,
+				blueprintId: this.context.blueprint.id,
+				executionId: this.context.executionId,
+				isFatal: false
+			});
+		}
+	}
+};
+
+//#endregion
+export { ClassNodeExecutor, FunctionNodeExecutor, NodeExecutor };