flowcraft 2.9.3 → 2.10.1

package/dist/runtime/traverser.mjs

@@ -0,0 +1,213 @@
+import { analyzeBlueprint } from "../analysis.mjs";
+import { FlowcraftError } from "../errors.mjs";
+
+//#region src/runtime/traverser.ts
+var GraphTraverser = class GraphTraverser {
+	frontier = /* @__PURE__ */ new Set();
+	allPredecessors;
+	allSuccessors;
+	dynamicBlueprint;
+	completedNodes = /* @__PURE__ */ new Set();
+	nodesInLoops;
+	constructor(blueprint, isStrictMode = false) {
+		this.dynamicBlueprint = structuredClone(blueprint);
+		this.allPredecessors = /* @__PURE__ */ new Map();
+		this.allSuccessors = /* @__PURE__ */ new Map();
+		this.nodesInLoops = /* @__PURE__ */ new Map();
+		for (const node of this.dynamicBlueprint.nodes) {
+			this.allPredecessors.set(node.id, /* @__PURE__ */ new Set());
+			this.allSuccessors.set(node.id, /* @__PURE__ */ new Set());
+		}
+		for (const edge of this.dynamicBlueprint.edges) this.getPredecessors(edge.target).add(edge.source);
+		for (const edge of this.dynamicBlueprint.edges) this.getSuccessors(edge.source).add(edge.target);
+		const analysis = analyzeBlueprint(blueprint);
+		this.filterNodesInLoops(blueprint);
+		this.frontier = new Set(analysis.startNodeIds.filter((id) => !this.isFallbackNode(id)));
+		if (this.frontier.size === 0 && analysis.cycles.length > 0 && !isStrictMode) {
+			const uniqueStartNodes = /* @__PURE__ */ new Set();
+			const cycleEntryPoints = new Set(blueprint.metadata?.cycleEntryPoints || []);
+			for (const cycle of analysis.cycles) if (cycle.length > 0) {
+				const entryPoint = cycle.find((node) => cycleEntryPoints.has(node));
+				uniqueStartNodes.add(entryPoint || cycle[0]);
+			}
+			this.frontier = new Set(uniqueStartNodes);
+		}
+	}
+	/**
+	* Clears all nodes from the execution frontier.
+	*/
+	clearFrontier() {
+		this.frontier.clear();
+	}
+	/**
+	* 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, state) {
+		const traverser = new GraphTraverser(blueprint);
+		traverser.clearFrontier();
+		const completedNodes = state.getCompletedNodes();
+		traverser.completedNodes = new Set(completedNodes);
+		const hasOnlyConditionalIncomingEdges = (nodeId) => {
+			const incomingEdges = blueprint.edges.filter((e) => e.target === nodeId);
+			if (incomingEdges.length === 0) return false;
+			const fromCompletedPredecessors = incomingEdges.filter((e) => completedNodes.has(e.source));
+			if (fromCompletedPredecessors.length === 0) return false;
+			return fromCompletedPredecessors.every((e) => e.condition !== void 0);
+		};
+		for (const node of traverser.dynamicBlueprint.nodes) {
+			if (traverser.completedNodes.has(node.id)) continue;
+			if (hasOnlyConditionalIncomingEdges(node.id)) continue;
+			const requiredPredecessors = traverser.allPredecessors.get(node.id);
+			const joinStrategy = traverser.getJoinStrategy(node.id);
+			if (!requiredPredecessors || requiredPredecessors.size === 0) {
+				traverser.frontier.add(node.id);
+				continue;
+			}
+			const completedPredecessors = [...requiredPredecessors].filter((p) => traverser.completedNodes.has(p));
+			if (joinStrategy === "any" ? completedPredecessors.length > 0 : completedPredecessors.length === requiredPredecessors.size) traverser.frontier.add(node.id);
+		}
+		return traverser;
+	}
+	isFallbackNode(nodeId) {
+		return this.dynamicBlueprint.nodes.some((n) => n.config?.fallback === nodeId);
+	}
+	getJoinStrategy(nodeId) {
+		return this.dynamicBlueprint.nodes.find((n) => n.id === nodeId)?.config?.joinStrategy || "all";
+	}
+	filterNodesInLoops(blueprint) {
+		blueprint.nodes.forEach((node) => {
+			if (node.uses !== "loop-controller") return;
+			const nextInLoopId = blueprint.edges.find((e) => e.source === node.id && e.action === "continue")?.target;
+			if (!nextInLoopId) throw new FlowcraftError(`Loop '${node.id}' has no continue edge to start node. Ensure edges are wired inside the loop and incoming/breaking edges point to the loop controller.`, {
+				nodeId: node.id,
+				blueprintId: blueprint.id
+			});
+			const set = /* @__PURE__ */ new Set();
+			set.add(nextInLoopId);
+			this.nodesInLoops.set(node.id, this.getAllLoopSuccessors(nextInLoopId, blueprint, set));
+		});
+	}
+	getAllLoopSuccessors(nodeId, blueprint, set) {
+		this.getSuccessors(nodeId).forEach((successor) => {
+			if (set.has(successor)) return;
+			const node = this.getNode(successor, blueprint);
+			if (!node || node.uses === "loop-controller") return;
+			set.add(successor);
+			this.getAllLoopSuccessors(successor, blueprint, set);
+		});
+		return set;
+	}
+	getReadyNodes() {
+		const readyNodes = [];
+		for (const nodeId of this.frontier) {
+			const nodeDef = this.dynamicBlueprint.nodes.find((n) => n.id === nodeId);
+			if (nodeDef) readyNodes.push({
+				nodeId,
+				nodeDef
+			});
+		}
+		this.frontier.clear();
+		return readyNodes;
+	}
+	hasMoreWork() {
+		return this.frontier.size > 0;
+	}
+	markNodeCompleted(nodeId, result, nextNodes) {
+		this.completedNodes.add(nodeId);
+		if (result?.dynamicNodes && result.dynamicNodes.length > 0) {
+			const gatherNodeId = result.output?.gatherNodeId;
+			for (const dynamicNode of result.dynamicNodes) {
+				this.dynamicBlueprint.nodes.push(dynamicNode);
+				this.allPredecessors.set(dynamicNode.id, new Set([nodeId]));
+				if (gatherNodeId) this.getPredecessors(gatherNodeId).add(dynamicNode.id);
+				this.frontier.add(dynamicNode.id);
+			}
+		}
+		for (const node of nextNodes) {
+			const joinStrategy = this.getJoinStrategy(node.id);
+			if (joinStrategy !== "any" && this.completedNodes.has(node.id)) continue;
+			const requiredPredecessors = this.getPredecessors(node.id);
+			if (joinStrategy === "any" ? requiredPredecessors.has(nodeId) : [...requiredPredecessors].every((p) => this.completedNodes.has(p))) {
+				this.frontier.add(node.id);
+				if (node.uses === "loop-controller") this.getNodesInLoop(node.id).forEach((id) => {
+					this.resetNodeCompletion(id);
+				});
+			}
+		}
+		if (nextNodes.length === 0) {
+			for (const [potentialNextId, predecessors] of this.allPredecessors) if (predecessors.has(nodeId) && !this.completedNodes.has(potentialNextId)) {
+				if (this.dynamicBlueprint.edges.some((e) => e.target === potentialNextId && e.condition)) continue;
+				if (this.getJoinStrategy(potentialNextId) === "any" ? predecessors.has(nodeId) : [...predecessors].every((p) => this.completedNodes.has(p))) {
+					this.frontier.add(potentialNextId);
+					const node = this.getNode(potentialNextId, this.dynamicBlueprint);
+					if (!node) continue;
+					if (node.uses === "loop-controller") this.getNodesInLoop(node.id).forEach((id) => {
+						this.resetNodeCompletion(id);
+					});
+				}
+			}
+		}
+	}
+	getAllNodeIds() {
+		return new Set(this.dynamicBlueprint.nodes.map((n) => n.id));
+	}
+	getFallbackNodeIds() {
+		const fallbackNodeIds = /* @__PURE__ */ new Set();
+		for (const node of this.dynamicBlueprint.nodes) if (node.config?.fallback) fallbackNodeIds.add(node.config.fallback);
+		return fallbackNodeIds;
+	}
+	getCompletedNodes() {
+		return new Set(this.completedNodes);
+	}
+	getDynamicBlueprint() {
+		return this.dynamicBlueprint;
+	}
+	getAllPredecessors() {
+		return this.allPredecessors;
+	}
+	getAllSuccessors() {
+		return this.allSuccessors;
+	}
+	getPredecessors(nodeId) {
+		const predecessors = this.allPredecessors.get(nodeId);
+		if (!predecessors) return /* @__PURE__ */ new Set();
+		return predecessors;
+	}
+	getSuccessors(nodeId) {
+		const successors = this.allSuccessors.get(nodeId);
+		if (!successors) return /* @__PURE__ */ new Set();
+		return successors;
+	}
+	getNodesInLoop(id) {
+		const loopNodes = this.nodesInLoops.get(id);
+		if (!loopNodes) return /* @__PURE__ */ new Set();
+		return loopNodes;
+	}
+	resetNodeCompletion(nodeId) {
+		this.completedNodes.delete(nodeId);
+	}
+	getNode(nodeId, blueprint) {
+		return blueprint.nodes.find((n) => n.id === nodeId);
+	}
+	addDynamicNode(_nodeId, dynamicNode, predecessorId, gatherNodeId) {
+		this.dynamicBlueprint.nodes.push(dynamicNode);
+		this.allPredecessors.set(dynamicNode.id, new Set([predecessorId]));
+		if (gatherNodeId) this.allPredecessors.get(gatherNodeId)?.add(dynamicNode.id);
+		this.frontier.add(dynamicNode.id);
+	}
+	/**
+	* 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) {
+		this.frontier.add(nodeId);
+	}
+};
+
+//#endregion
+export { GraphTraverser };

package/dist/runtime/types.d.mts

@@ -0,0 +1,2 @@
+import { B as NodeExecutionResult, M as IOrchestrator, N as IRuntime, P as NodeExecutorFactory, V as NodeExecutor, j as ExecutionServices } from "../types-BcrXJEPI.mjs";
+export { ExecutionServices, IOrchestrator, IRuntime, NodeExecutionResult, NodeExecutor, NodeExecutorFactory };

package/dist/runtime/types.mjs

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

package/dist/runtime/workflow-logic-handler.d.mts

@@ -0,0 +1,16 @@
+import { a as IEvaluator, m as NodeDefinition, n as EdgeDefinition, o as IEventBus, t as ContextImplementation, v as NodeResult, w as WorkflowBlueprint } from "../types-BcrXJEPI.mjs";
+
+//#region src/runtime/workflow-logic-handler.d.ts
+declare class WorkflowLogicHandler {
+  private readonly evaluator;
+  private readonly eventBus;
+  constructor(evaluator: IEvaluator, eventBus: IEventBus);
+  determineNextNodes(blueprint: WorkflowBlueprint, completedNodeId: 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: ContextImplementation<any>): Promise<any>;
+}
+//#endregion
+export { WorkflowLogicHandler };

package/dist/runtime/workflow-logic-handler.mjs

@@ -0,0 +1,159 @@
+import { FlowcraftError } from "../errors.mjs";
+import { AsyncContextView } from "../context.mjs";
+
+//#region src/runtime/workflow-logic-handler.ts
+var WorkflowLogicHandler = class {
+	constructor(evaluator, eventBus) {
+		this.evaluator = evaluator;
+		this.eventBus = eventBus;
+	}
+	async determineNextNodes(blueprint, completedNodeId, result, context, executionId) {
+		if (!result) return [];
+		const effectiveSourceNodeId = completedNodeId;
+		const directOutgoingEdges = blueprint.edges.filter((edge) => edge.source === effectiveSourceNodeId);
+		const inheritedOutgoingEdges = blueprint.nodes.filter((n) => n.config?.fallback === completedNodeId).flatMap((originalNode) => blueprint.edges.filter((edge) => edge.source === originalNode.id));
+		const allPossibleEdges = [...directOutgoingEdges, ...inheritedOutgoingEdges];
+		const outgoingEdges = [...new Map(allPossibleEdges.map((edge) => [`${edge.source}-${edge.target}-${edge.action || ""}-${edge.condition || ""}`, edge])).values()];
+		const matched = [];
+		const evaluateEdge = async (edge) => {
+			if (!edge.condition) return true;
+			const contextData = context.type === "sync" ? context.toJSON() : await context.toJSON();
+			const evaluationResult = !!this.evaluator.evaluate(edge.condition, {
+				...contextData,
+				result
+			});
+			await this.eventBus.emit({
+				type: "edge:evaluate",
+				payload: {
+					source: edge.source,
+					target: edge.target,
+					condition: edge.condition,
+					result: evaluationResult
+				}
+			});
+			return evaluationResult;
+		};
+		if (blueprint.nodes.find((n) => n.id === completedNodeId)?.uses === "loop-controller") {
+			const conditionalEdges = outgoingEdges.filter((edge) => edge.condition);
+			for (const edge of conditionalEdges) if (await evaluateEdge(edge)) {
+				const targetNode = blueprint.nodes.find((n) => n.id === edge.target);
+				if (targetNode) matched.push({
+					node: targetNode,
+					edge
+				});
+			} else await this.eventBus.emit({
+				type: "node:skipped",
+				payload: {
+					nodeId: completedNodeId,
+					edge,
+					executionId: executionId || "",
+					blueprintId: blueprint.id
+				}
+			});
+			if (matched.length > 0) return matched;
+		}
+		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
+				});
+			} else await this.eventBus.emit({
+				type: "node:skipped",
+				payload: {
+					nodeId: completedNodeId,
+					edge,
+					executionId: executionId || "",
+					blueprintId: blueprint.id
+				}
+			});
+		}
+		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
+				});
+			} else await this.eventBus.emit({
+				type: "node:skipped",
+				payload: {
+					nodeId: completedNodeId,
+					edge,
+					executionId: executionId || "",
+					blueprintId: blueprint.id
+				}
+			});
+		}
+		return matched;
+	}
+	async applyEdgeTransform(edge, sourceResult, targetNode, context, allPredecessors, executionId) {
+		const asyncContext = context.type === "sync" ? new AsyncContextView(context) : context;
+		const predecessors = allPredecessors?.get(targetNode.id);
+		predecessors && predecessors.size;
+		const hasExplicitInputs = targetNode.inputs !== void 0;
+		const hasEdgeTransform = edge.transform !== void 0;
+		let sourceOutput = sourceResult.output;
+		if (hasEdgeTransform && hasExplicitInputs && typeof targetNode.inputs === "string") {
+			const inputsKey = targetNode.inputs;
+			const resolvedKey = inputsKey.startsWith("_") ? inputsKey : `_outputs.${inputsKey}`;
+			if (await asyncContext.has(resolvedKey) && inputsKey !== edge.source) sourceOutput = await asyncContext.get(resolvedKey);
+		}
+		const finalInput = hasEdgeTransform ? this.evaluator.evaluate(edge.transform, {
+			input: sourceOutput,
+			context: await asyncContext.toJSON()
+		}) : sourceOutput;
+		const inputKey = `_inputs.${targetNode.id}`;
+		await asyncContext.set(inputKey, finalInput);
+		await this.eventBus.emit({
+			type: "context:change",
+			payload: {
+				sourceNode: edge.source,
+				key: inputKey,
+				op: "set",
+				value: finalInput,
+				executionId: executionId || "unknown"
+			}
+		});
+		if (!hasExplicitInputs || hasEdgeTransform) targetNode.inputs = inputKey;
+	}
+	async resolveNodeInput(nodeId, blueprint, context) {
+		const nodeDef = blueprint.nodes.find((n) => n.id === nodeId);
+		if (!nodeDef) throw new FlowcraftError(`Node '${nodeId}' not found in blueprint.`, {
+			nodeId,
+			blueprintId: blueprint.id,
+			isFatal: false
+		});
+		const asyncContext = context.type === "sync" ? new AsyncContextView(context) : context;
+		if (nodeDef.inputs) {
+			if (typeof nodeDef.inputs === "string") {
+				const key = nodeDef.inputs;
+				if (key.startsWith("_")) return await asyncContext.get(key);
+				const outputKey = `_outputs.${key}`;
+				if (await asyncContext.has(outputKey)) return await asyncContext.get(outputKey);
+				return await asyncContext.get(key);
+			}
+			if (typeof nodeDef.inputs === "object") {
+				const input = {};
+				for (const key in nodeDef.inputs) {
+					const contextKey = nodeDef.inputs[key];
+					if (contextKey.startsWith("_")) input[key] = await asyncContext.get(contextKey);
+					else {
+						const outputKey = `_outputs.${contextKey}`;
+						if (await asyncContext.has(outputKey)) input[key] = await asyncContext.get(outputKey);
+						else input[key] = await asyncContext.get(contextKey);
+					}
+				}
+				return input;
+			}
+		}
+		const inputKey = `_inputs.${nodeDef.id}`;
+		return await asyncContext.get(inputKey);
+	}
+};
+
+//#endregion
+export { WorkflowLogicHandler };

package/dist/sanitizer-Bi00YjvO.d.mts

@@ -0,0 +1,11 @@
+import { w as WorkflowBlueprint } from "./types-BcrXJEPI.mjs";
+
+//#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
+export { sanitizeBlueprint as t };

package/dist/sanitizer.d.mts

@@ -0,0 +1,2 @@
+import { t as sanitizeBlueprint } from "./sanitizer-Bi00YjvO.mjs";
+export { sanitizeBlueprint };

package/dist/sanitizer.mjs

@@ -0,0 +1,37 @@
+//#region src/sanitizer.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.
+*/
+function sanitizeBlueprint(raw) {
+	let nodesArray = [];
+	if (Array.isArray(raw.nodes)) nodesArray = raw.nodes;
+	else if (typeof raw.nodes === "object" && raw.nodes !== null) nodesArray = Object.values(raw.nodes);
+	const nodes = nodesArray.map((node) => ({
+		id: node.id,
+		uses: node.uses,
+		params: node.params,
+		inputs: node.inputs,
+		config: node.config
+	}));
+	let edgesArray = [];
+	if (Array.isArray(raw.edges)) edgesArray = raw.edges;
+	else if (typeof raw.edges === "object" && raw.edges !== null) edgesArray = Object.values(raw.edges);
+	const edges = edgesArray.map((edge) => ({
+		source: edge.source,
+		target: edge.target,
+		action: edge.action,
+		condition: edge.condition,
+		transform: edge.transform
+	}));
+	return {
+		id: raw.id,
+		nodes,
+		edges,
+		metadata: raw.metadata
+	};
+}
+
+//#endregion
+export { sanitizeBlueprint };

package/dist/sdk.d.mts

@@ -27,5 +27,4 @@ declare function waitForEvent<T = any>(_eventName: string): Promise<T>;
  */
 declare function createWebhook<T = any>(): Promise<Webhook<T>>;
 //#endregion
-export { Webhook, createWebhook, sleep, waitForEvent };
-//# sourceMappingURL=sdk.d.mts.map
+export { Webhook, createWebhook, sleep, waitForEvent };

package/dist/sdk.mjs

@@ -25,5 +25,4 @@ function createWebhook() {
 }
 
 //#endregion
-export { createWebhook, sleep, waitForEvent };
-//# sourceMappingURL=sdk.mjs.map
+export { createWebhook, sleep, waitForEvent };

package/dist/serializer-BnmJr13R.d.mts

@@ -0,0 +1,17 @@
+import { c as ISerializer } from "./types-BcrXJEPI.mjs";
+
+//#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 { JsonSerializer as t };

package/dist/serializer.d.mts

@@ -0,0 +1,2 @@
+import { t as JsonSerializer } from "./serializer-BnmJr13R.mjs";
+export { JsonSerializer };

package/dist/serializer.mjs

@@ -0,0 +1,34 @@
+//#region src/serializer.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.
+*/
+var JsonSerializer = class {
+	hasWarned = false;
+	serialize(data) {
+		for (const value of Object.values(data)) if (value instanceof Map || value instanceof Set || value instanceof Date) {
+			if (!this.hasWarned) {
+				console.warn("[Flowcraft] Warning: Default JsonSerializer does not support Map, Set, or Date types. Data may be lost. Consider providing a custom ISerializer (e.g., using superjson).");
+				this.hasWarned = true;
+			}
+		}
+		try {
+			return JSON.stringify(data);
+		} catch {
+			console.warn("[Flowcraft] Warning: Circular reference detected in context. Using safe serialization.");
+			return JSON.stringify({
+				_circularReference: true,
+				message: "Context contains circular references"
+			});
+		}
+	}
+	deserialize(text) {
+		return JSON.parse(text);
+	}
+};
+
+//#endregion
+export { JsonSerializer };

package/dist/sleep-DpwYaY5b.d.mts

@@ -0,0 +1,8 @@
+import { K as BaseNode, p as NodeContext, v as NodeResult } from "./types-BcrXJEPI.mjs";
+
+//#region src/nodes/sleep.d.ts
+declare class SleepNode extends BaseNode {
+  exec(prepResult: any, context: NodeContext<Record<string, any>, any, any>): Promise<Omit<NodeResult, 'error'>>;
+}
+//#endregion
+export { SleepNode as t };

package/dist/subflow-n2IMsRe2.d.mts

@@ -0,0 +1,8 @@
+import { K as BaseNode, p as NodeContext, v as NodeResult } from "./types-BcrXJEPI.mjs";
+
+//#region src/nodes/subflow.d.ts
+declare class SubflowNode extends BaseNode {
+  exec(_prepResult: any, context: NodeContext<Record<string, any>, any, any>): Promise<Omit<NodeResult, 'error'>>;
+}
+//#endregion
+export { SubflowNode as t };

package/dist/testing/event-logger.d.mts

@@ -0,0 +1,62 @@
+import { o as IEventBus, r as FlowcraftEvent } from "../types-BcrXJEPI.mjs";
+
+//#region src/testing/event-logger.d.ts
+/**
+ * A test utility that implements IEventBus to capture all workflow events
+ * in memory, acting as a "flight recorder" for behavioral testing.
+ *
+ * @example
+ * // In your test file (e.g., resiliency.test.ts)
+ * it('should retry a node on failure', async () => {
+ *   const eventLogger = new InMemoryEventLogger();
+ *   const runtime = new FlowRuntime({ eventBus: eventLogger });
+ *
+ *   const flow = createFlow('retry-flow')
+ *     .node('api-call', vi.fn().mockRejectedValueOnce(new Error('fail')), {
+ *       config: { maxRetries: 2 },
+ *     });
+ *
+ *   await runtime.run(flow.toBlueprint());
+ *
+ *   // Assert against the captured event history to prove behavior.
+ *   const retryEvents = eventLogger.filter('node:retry');
+ *   expect(retryEvents).toHaveLength(1); // The first attempt is not a "retry"
+ * });
+ */
+declare class InMemoryEventLogger implements IEventBus {
+  readonly events: FlowcraftEvent[];
+  /**
+   * Clears all captured events.
+   */
+  clear(): void;
+  /**
+   * The `emit` method required by the IEventBus interface.
+   * It simply pushes the received event into the internal events array.
+   * @param event The FlowcraftEvent to record.
+   */
+  emit(event: FlowcraftEvent): Promise<void>;
+  /**
+   * Finds the first event of a specific type.
+   * @param type The event type to find (e.g., 'node:error').
+   * @returns The first matching event, or undefined if not found.
+   */
+  find<T extends FlowcraftEvent['type']>(type: T): Extract<FlowcraftEvent, {
+    type: T;
+  }> | undefined;
+  /**
+   * Filters events to find all occurrences of a specific type.
+   * @param type The event type to filter by.
+   * @returns An array of matching events.
+   */
+  filter<T extends FlowcraftEvent['type']>(type: T): Extract<FlowcraftEvent, {
+    type: T;
+  }>[];
+  /**
+   * Prints a formatted log of all captured events to the console.
+   * Ideal for debugging failing tests.
+   * @param title A title for the log output.
+   */
+  printLog(title?: string): void;
+}
+//#endregion
+export { InMemoryEventLogger };