flowcraft 2.9.3 → 2.10.1

package/README.md

@@ -1,8 +1,8 @@
 # `flowcraft`
 
-[![NPM Version](https://img.shields.io/npm/v/flowcraft.svg)](https://www.npmjs.com/package/flowcraft)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Codecov](https://img.shields.io/codecov/c/github/gorango/flowcraft/master)](https://codecov.io/github/gorango/flowcraft)
+[![NPM Version](https://img.shields.io/npm/v/flowcraft.svg)](https://www.npmjs.com/package/flowcraft)
+[![Codecov](https://img.shields.io/codecov/c/github/gorango/flowcraft/master?flag=core)](https://codecov.io/github/gorango/flowcraft/tree/master/packages/core/src?flags[0]=core)
 
 Build complex, multi-step processes with a lightweight, composable, and type-safe approach. Model complex business processes, data pipelines, ETL workflows, or AI agents and scale from in-memory scripts to distributed systems without changing the core business logic.
 
@@ -106,4 +106,4 @@ For a complete overview of features, patterns, examples, and APIs, see the full
 
 ## License
 
-Flowcraft is licensed under the [MIT License](LICENSE).
+Flowcraft is licensed under the [MIT License](https://github.com/gorango/flowcraft/blob/master/LICENSE).

package/dist/adapter-DzeZVjSE.d.mts

@@ -0,0 +1,133 @@
+import { A as FlowRuntime, D as WorkflowResult, c as ISerializer, i as IAsyncContext, m as NodeDefinition, o as IEventBus, s as ILogger, w as WorkflowBlueprint, x as RuntimeOptions } from "./types-BcrXJEPI.mjs";
+
+//#region src/runtime/adapter.d.ts
+/**
+ * Defines the contract for an atomic, distributed key-value store required by
+ * the adapter for coordination tasks like fan-in joins and locking.
+ */
+interface ICoordinationStore {
+  /** Atomically increments a key and returns the new value. Ideal for 'all' joins. */
+  increment: (key: string, ttlSeconds: number) => Promise<number>;
+  /** Sets a key only if it does not already exist. Ideal for 'any' joins (locking). */
+  setIfNotExist: (key: string, value: string, ttlSeconds: number) => Promise<boolean>;
+  /** Extends the TTL of an existing key. Used for heartbeat mechanism in long-running jobs. */
+  extendTTL: (key: string, ttlSeconds: number) => Promise<boolean>;
+  /** Deletes a key. Used for cleanup. */
+  delete: (key: string) => Promise<void>;
+  /** Gets the value of a key. */
+  get: (key: string) => Promise<string | undefined>;
+}
+/** Configuration options for constructing a BaseDistributedAdapter. */
+interface AdapterOptions {
+  runtimeOptions: RuntimeOptions<any>;
+  coordinationStore: ICoordinationStore;
+  eventBus?: IEventBus;
+}
+/** The data payload expected for a job in the queue. */
+interface JobPayload {
+  runId: string;
+  blueprintId: string;
+  nodeId: string;
+  /** Used to suppress intermediate failures and fallback triggers when delegating to Queue retries */
+  isLastAttempt?: boolean;
+  /** Optional attempt tracking metadata */
+  attempt?: number;
+}
+/**
+ * The base class for all distributed adapters. It handles the technology-agnostic
+ * orchestration logic and leaves queue-specific implementation to subclasses.
+ */
+declare abstract class BaseDistributedAdapter {
+  protected readonly runtime: FlowRuntime<any, any>;
+  protected readonly store: ICoordinationStore;
+  protected readonly serializer: ISerializer;
+  protected readonly logger: ILogger;
+  protected readonly eventBus?: IEventBus;
+  constructor(options: AdapterOptions);
+  /**
+   * Starts the worker, which begins listening for and processing jobs from the queue.
+   */
+  start(): void;
+  /**
+   * 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).
+   */
+  protected shouldRetryInProcess(_nodeDef: NodeDefinition): boolean;
+  /**
+   * Returns queue-level retry options for enqueuing successor jobs.
+   * Only used when shouldRetryInProcess() returns false.
+   */
+  protected getQueueRetryOptions(_nodeDef: NodeDefinition): Record<string, any> | undefined;
+  /**
+   * Creates a technology-specific distributed context for a given workflow run.
+   * @param runId The unique ID for the workflow execution.
+   */
+  protected abstract createContext(runId: string): IAsyncContext<Record<string, any>>;
+  /**
+   * Sets up the listener for the message queue. The implementation should call the
+   * provided `handler` function for each new job received.
+   * @param handler The core logic to execute for each job.
+   */
+  protected abstract processJobs(handler: (job: JobPayload) => Promise<void>): void;
+  /**
+   * Enqueues a new job onto the message queue.
+   * @param job The payload for the job to be enqueued.
+   */
+  protected abstract enqueueJob(job: JobPayload): Promise<void>;
+  /**
+   * Publishes the final result of a completed or failed workflow run.
+   * @param runId The unique ID of the workflow run.
+   * @param result The final status and payload of the workflow.
+   */
+  protected abstract publishFinalResult(runId: string, result: {
+    status: 'completed' | 'failed';
+    payload?: WorkflowResult;
+    reason?: string;
+  }): Promise<void>;
+  /**
+   * Registers a webhook endpoint for a specific node in a workflow run.
+   * @param runId The unique ID of the workflow run.
+   * @param nodeId The ID of the node that will wait for the webhook.
+   * @returns The URL and event name for the webhook.
+   */
+  abstract registerWebhookEndpoint(runId: string, nodeId: string): Promise<{
+    url: string;
+    event: string;
+  }>;
+  /**
+   * Hook called at the start of job processing. Subclasses can override this
+   * to perform additional setup (e.g., timestamp tracking for reconciliation).
+   */
+  protected onJobStart(_runId: string, _blueprintId: string, _nodeId: string): Promise<void>;
+  /**
+   * The main handler for processing a single job from the queue.
+   */
+  protected handleJob(job: JobPayload): Promise<void>;
+  /**
+   * Handles post-execution logic: terminal node checks, successor determination,
+   * and enqueueing of ready nodes. Extracted to support the idempotency guard.
+   */
+  private handleNodeCompletion;
+  /**
+   * Encapsulates the fan-in join logic using the coordination store.
+   */
+  protected isReadyForFanIn(runId: string, blueprint: WorkflowBlueprint, targetNodeId: string): Promise<boolean>;
+  /**
+   * Reconciles the state of a workflow run. It inspects the persisted
+   * context to find completed nodes, determines the next set of executable
+   * nodes (the frontier), and enqueues jobs for them if they aren't
+   * already running. This is the core of the resume functionality.
+   *
+   * @param runId The unique ID of the workflow execution to reconcile.
+   * @returns The set of node IDs that were enqueued for execution.
+   */
+  reconcile(runId: string): Promise<Set<string>>;
+  private calculateResumedFrontier;
+  /**
+   * Writes a poison pill for 'all' join successors and a cancellation pill for 'any' join successors of a failed node to prevent stalling or ambiguous states.
+   */
+  private writePoisonPillForSuccessors;
+}
+//#endregion
+export { JobPayload as i, BaseDistributedAdapter as n, ICoordinationStore as r, AdapterOptions as t };

package/dist/adapters/index.d.mts

@@ -0,0 +1,2 @@
+import { n as InMemoryEventStore, r as PersistentEventBusAdapter, t as IEventStore } from "../persistent-event-bus-COiQOpWh.mjs";
+export { IEventStore, InMemoryEventStore, PersistentEventBusAdapter };

package/dist/adapters/index.mjs

@@ -0,0 +1,3 @@
+import { InMemoryEventStore, PersistentEventBusAdapter } from "./persistent-event-bus.mjs";
+
+export { InMemoryEventStore, PersistentEventBusAdapter };

package/dist/adapters/persistent-event-bus.d.mts

@@ -0,0 +1,2 @@
+import { n as InMemoryEventStore, r as PersistentEventBusAdapter, t as IEventStore } from "../persistent-event-bus-COiQOpWh.mjs";
+export { IEventStore, InMemoryEventStore, PersistentEventBusAdapter };

package/dist/adapters/persistent-event-bus.mjs

@@ -0,0 +1,59 @@
+//#region src/adapters/persistent-event-bus.ts
+/**
+* A pluggable event bus adapter that persists all workflow events
+* to a configurable storage backend, enabling time-travel debugging and replay.
+*
+* @example
+* ```typescript
+* // Using a database-backed store
+* const eventStore = new DatabaseEventStore(dbConnection)
+* const eventBus = new PersistentEventBusAdapter(eventStore)
+* const runtime = new FlowRuntime({ eventBus })
+*
+* // Later, replay the execution
+* const events = await eventStore.retrieve(executionId)
+* const finalState = await runtime.replay(blueprint, events)
+* ```
+*/
+var PersistentEventBusAdapter = class {
+	constructor(store) {
+		this.store = store;
+	}
+	/**
+	* Emit an event by storing it persistently.
+	* Also emits to console for debugging (can be made configurable).
+	*/
+	async emit(event) {
+		let executionId = "unknown";
+		if ("executionId" in event.payload) executionId = event.payload.executionId;
+		await this.store.store(event, executionId);
+	}
+};
+/**
+* Simple in-memory event store for testing and development.
+* Not suitable for production use.
+*/
+var InMemoryEventStore = class {
+	events = /* @__PURE__ */ new Map();
+	async store(event, executionId) {
+		if (!this.events.has(executionId)) this.events.set(executionId, []);
+		this.events.get(executionId)?.push(event);
+	}
+	async retrieve(executionId) {
+		return this.events.get(executionId) || [];
+	}
+	async retrieveMultiple(executionIds) {
+		const result = /* @__PURE__ */ new Map();
+		for (const id of executionIds) result.set(id, await this.retrieve(id));
+		return result;
+	}
+	/**
+	* Clear all stored events (useful for testing).
+	*/
+	clear() {
+		this.events.clear();
+	}
+};
+
+//#endregion
+export { InMemoryEventStore, PersistentEventBusAdapter };

package/dist/analysis-B5Twr7sD.d.mts

@@ -0,0 +1,52 @@
+import { r as FlowcraftEvent, w as WorkflowBlueprint } from "./types-BcrXJEPI.mjs";
+
+//#region src/analysis.d.ts
+/**
+ * A list of cycles found in the graph. Each cycle is an array of node IDs.
+ */
+type Cycles = string[][];
+/**
+ * Analysis result for a workflow blueprint
+ */
+interface BlueprintAnalysis {
+  /** Cycles found in the graph */
+  cycles: Cycles;
+  /** Node IDs that have no incoming edges (start nodes) */
+  startNodeIds: string[];
+  /** Node IDs that have no outgoing edges (terminal nodes) */
+  terminalNodeIds: string[];
+  /** Total number of nodes */
+  nodeCount: number;
+  /** Total number of edges */
+  edgeCount: number;
+  /** Whether the graph is a valid DAG (no cycles) */
+  isDag: boolean;
+}
+/**
+ * Analyzes a workflow blueprint to detect cycles using an iterative DFS algorithm.
+ * This avoids stack overflow issues for deep graphs compared to the recursive version.
+ * @param blueprint The WorkflowBlueprint object containing nodes and edges.
+ * @returns An array of cycles found. Each cycle is represented as an array of node IDs.
+ */
+declare function checkForCycles(blueprint: WorkflowBlueprint): Cycles;
+/**
+ * Generates Mermaid diagram syntax from a WorkflowBlueprint
+ * @param blueprint The WorkflowBlueprint object containing nodes and edges
+ * @returns Mermaid syntax string for the flowchart
+ */
+declare function generateMermaid(blueprint: WorkflowBlueprint): string;
+/**
+ * Generates Mermaid diagram syntax from a WorkflowBlueprint with execution history styling
+ * @param blueprint The WorkflowBlueprint object containing nodes and edges
+ * @param events Array of FlowcraftEvent objects from the workflow execution
+ * @returns Mermaid syntax string for the flowchart with execution path highlighting
+ */
+declare function generateMermaidForRun(blueprint: WorkflowBlueprint, events: FlowcraftEvent[]): string;
+/**
+ * Analyzes a workflow blueprint and returns comprehensive analysis
+ * @param blueprint The WorkflowBlueprint object containing nodes and edges
+ * @returns Analysis result with cycles, start nodes, terminal nodes, and other metrics
+ */
+declare function analyzeBlueprint(blueprint: WorkflowBlueprint): BlueprintAnalysis;
+//#endregion
+export { generateMermaid as a, checkForCycles as i, Cycles as n, generateMermaidForRun as o, analyzeBlueprint as r, BlueprintAnalysis as t };

package/dist/analysis.d.mts

@@ -0,0 +1,2 @@
+import { a as generateMermaid, i as checkForCycles, n as Cycles, o as generateMermaidForRun, r as analyzeBlueprint, t as BlueprintAnalysis } from "./analysis-B5Twr7sD.mjs";
+export { BlueprintAnalysis, Cycles, analyzeBlueprint, checkForCycles, generateMermaid, generateMermaidForRun };

package/dist/analysis.mjs

@@ -0,0 +1,164 @@
+//#region src/analysis.ts
+/**
+* Analyzes a workflow blueprint to detect cycles using an iterative DFS algorithm.
+* This avoids stack overflow issues for deep graphs compared to the recursive version.
+* @param blueprint The WorkflowBlueprint object containing nodes and edges.
+* @returns An array of cycles found. Each cycle is represented as an array of node IDs.
+*/
+function checkForCycles(blueprint) {
+	const cycles = [];
+	if (!blueprint?.nodes || blueprint.nodes.length === 0) return cycles;
+	const allNodeIds = blueprint.nodes.map((node) => node.id);
+	const adj = /* @__PURE__ */ new Map();
+	for (const id of allNodeIds) adj.set(id, []);
+	for (const edge of blueprint.edges) adj.get(edge.source)?.push(edge.target);
+	const state = /* @__PURE__ */ new Map();
+	for (const id of allNodeIds) state.set(id, 0);
+	for (const startNode of allNodeIds) {
+		if (state.get(startNode) !== 0) continue;
+		const stack = [{
+			node: startNode,
+			path: []
+		}];
+		const pathSet = /* @__PURE__ */ new Set();
+		while (stack.length > 0) {
+			const { node, path } = stack[stack.length - 1];
+			if (state.get(node) === 0) {
+				state.set(node, 1);
+				pathSet.add(node);
+				path.push(node);
+			}
+			const neighbors = adj.get(node) || [];
+			let foundUnvisited = false;
+			for (const neighbor of neighbors) if (state.get(neighbor) === 1) {
+				const cycleStartIndex = path.indexOf(neighbor);
+				const cycle = path.slice(cycleStartIndex);
+				cycles.push([...cycle, neighbor]);
+			} else if (state.get(neighbor) === 0) {
+				stack.push({
+					node: neighbor,
+					path: [...path]
+				});
+				foundUnvisited = true;
+				break;
+			}
+			if (!foundUnvisited) {
+				state.set(node, 2);
+				stack.pop();
+				pathSet.delete(node);
+			}
+		}
+	}
+	return cycles;
+}
+/**
+* Generates Mermaid diagram syntax from a WorkflowBlueprint
+* @param blueprint The WorkflowBlueprint object containing nodes and edges
+* @returns Mermaid syntax string for the flowchart
+*/
+function generateMermaid(blueprint) {
+	if (!blueprint?.nodes || blueprint.nodes.length === 0) return "flowchart TD\n    empty[Empty Blueprint]";
+	let mermaid = "flowchart TD\n";
+	for (const node of blueprint.nodes) {
+		const paramsString = node.params ? `<br/>params: ${JSON.stringify(node.params)}` : "";
+		const nodeLabel = `${node.id}${paramsString}`;
+		mermaid += `    ${node.id}["${nodeLabel}"]\n`;
+	}
+	for (const edge of blueprint.edges || []) {
+		const labelParts = [];
+		if (edge.action) labelParts.push(edge.action);
+		if (edge.condition) labelParts.push(edge.condition);
+		if (edge.transform) labelParts.push(edge.transform);
+		if (labelParts.length > 0) {
+			const edgeLabel = labelParts.join(" | ");
+			mermaid += `    ${edge.source} -- "${edgeLabel}" --> ${edge.target}\n`;
+		} else mermaid += `    ${edge.source} --> ${edge.target}\n`;
+	}
+	return mermaid;
+}
+/**
+* Generates Mermaid diagram syntax from a WorkflowBlueprint with execution history styling
+* @param blueprint The WorkflowBlueprint object containing nodes and edges
+* @param events Array of FlowcraftEvent objects from the workflow execution
+* @returns Mermaid syntax string for the flowchart with execution path highlighting
+*/
+function generateMermaidForRun(blueprint, events) {
+	if (!blueprint?.nodes || blueprint.nodes.length === 0) return "flowchart TD\n    empty[Empty Blueprint]";
+	let mermaid = "flowchart TD\n";
+	const successfulNodes = /* @__PURE__ */ new Set();
+	const failedNodes = /* @__PURE__ */ new Set();
+	const takenEdges = /* @__PURE__ */ new Set();
+	for (const event of events) switch (event.type) {
+		case "node:finish":
+			successfulNodes.add(event.payload.nodeId);
+			break;
+		case "node:error":
+			failedNodes.add(event.payload.nodeId);
+			break;
+		case "edge:evaluate":
+			if (event.payload.result) {
+				const edgeKey = `${event.payload.source}->${event.payload.target}`;
+				takenEdges.add(edgeKey);
+			}
+			break;
+	}
+	for (const node of blueprint.nodes) {
+		const paramsString = node.params ? `<br/>params: ${JSON.stringify(node.params)}` : "";
+		const nodeLabel = `${node.id}${paramsString}`;
+		mermaid += `    ${node.id}["${nodeLabel}"]\n`;
+	}
+	for (const node of blueprint.nodes) if (successfulNodes.has(node.id)) mermaid += `    style ${node.id} fill:#d4edda,stroke:#c3e6cb\n`;
+	else if (failedNodes.has(node.id)) mermaid += `    style ${node.id} fill:#f8d7da,stroke:#f5c6cb\n`;
+	let edgeIndex = 0;
+	for (const edge of blueprint.edges || []) {
+		const labelParts = [];
+		if (edge.action) labelParts.push(edge.action);
+		if (edge.condition) labelParts.push(edge.condition);
+		if (edge.transform) labelParts.push(edge.transform);
+		const edgeKey = `${edge.source}->${edge.target}`;
+		const isTaken = takenEdges.has(edgeKey);
+		let edgeLine;
+		if (labelParts.length > 0) {
+			const edgeLabel = labelParts.join(" | ");
+			edgeLine = `    ${edge.source} -- "${edgeLabel}" --> ${edge.target}\n`;
+		} else edgeLine = `    ${edge.source} --> ${edge.target}\n`;
+		mermaid += edgeLine;
+		if (isTaken) mermaid += `    linkStyle ${edgeIndex} stroke:#007bff,stroke-width:3px\n`;
+		edgeIndex++;
+	}
+	return mermaid;
+}
+/**
+* Analyzes a workflow blueprint and returns comprehensive analysis
+* @param blueprint The WorkflowBlueprint object containing nodes and edges
+* @returns Analysis result with cycles, start nodes, terminal nodes, and other metrics
+*/
+function analyzeBlueprint(blueprint) {
+	if (!blueprint?.nodes || blueprint.nodes.length === 0) return {
+		cycles: [],
+		startNodeIds: [],
+		terminalNodeIds: [],
+		nodeCount: 0,
+		edgeCount: 0,
+		isDag: true
+	};
+	const cycles = checkForCycles(blueprint);
+	const nodeCount = blueprint.nodes.length;
+	const edgeCount = blueprint.edges?.length || 0;
+	const nodesWithIncoming = /* @__PURE__ */ new Set();
+	for (const edge of blueprint.edges || []) nodesWithIncoming.add(edge.target);
+	const startNodeIds = blueprint.nodes.map((node) => node.id).filter((nodeId) => !nodesWithIncoming.has(nodeId));
+	const nodesWithOutgoing = /* @__PURE__ */ new Set();
+	for (const edge of blueprint.edges || []) nodesWithOutgoing.add(edge.source);
+	return {
+		cycles,
+		startNodeIds,
+		terminalNodeIds: blueprint.nodes.map((node) => node.id).filter((nodeId) => !nodesWithOutgoing.has(nodeId)),
+		nodeCount,
+		edgeCount,
+		isDag: cycles.length === 0
+	};
+}
+
+//#endregion
+export { analyzeBlueprint, checkForCycles, generateMermaid, generateMermaidForRun };

package/dist/batch-gather-BhF-IzQR.d.mts

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

package/dist/batch-scatter-DD8TU0Wm.d.mts

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

package/dist/container-BKdd-9wf.d.mts

@@ -0,0 +1,24 @@
+//#region src/container.d.ts
+type ServiceToken<_T = any> = string | symbol;
+declare class DIContainer {
+  private services;
+  private factories;
+  register<T>(token: ServiceToken<T>, implementation: T): void;
+  registerFactory<T>(token: ServiceToken<T>, factory: (container: DIContainer) => T): void;
+  resolve<T>(token: ServiceToken<T>): T;
+  has(token: ServiceToken): boolean;
+  createChild(): DIContainer;
+}
+declare const ServiceTokens: {
+  readonly Logger: symbol;
+  readonly Serializer: symbol;
+  readonly Evaluator: symbol;
+  readonly EventBus: symbol;
+  readonly Orchestrator: symbol;
+  readonly Middleware: symbol;
+  readonly NodeRegistry: symbol;
+  readonly BlueprintRegistry: symbol;
+  readonly Dependencies: symbol;
+};
+//#endregion
+export { ServiceToken as n, ServiceTokens as r, DIContainer as t };

package/dist/container-factory-fDY2kkxt.d.mts

@@ -0,0 +1,17 @@
+import { a as IEvaluator, b as RuntimeDependencies, c as ISerializer, d as NodeClass, h as NodeFunction, o as IEventBus, s as ILogger, u as Middleware, w as WorkflowBlueprint } from "./types-BcrXJEPI.mjs";
+import { t as DIContainer } from "./container-BKdd-9wf.mjs";
+
+//#region src/container-factory.d.ts
+interface ContainerOptions<TDependencies extends RuntimeDependencies = RuntimeDependencies> {
+  logger?: ILogger;
+  serializer?: ISerializer;
+  evaluator?: IEvaluator;
+  eventBus?: IEventBus;
+  middleware?: Middleware[];
+  registry?: Record<string, NodeFunction | NodeClass>;
+  blueprints?: Record<string, WorkflowBlueprint>;
+  dependencies?: TDependencies;
+}
+declare function createDefaultContainer<TDependencies extends RuntimeDependencies = RuntimeDependencies>(options?: ContainerOptions<TDependencies>): DIContainer;
+//#endregion
+export { createDefaultContainer as n, ContainerOptions as t };

package/dist/container-factory.d.mts

@@ -0,0 +1,2 @@
+import { n as createDefaultContainer, t as ContainerOptions } from "./container-factory-fDY2kkxt.mjs";
+export { ContainerOptions, createDefaultContainer };

package/dist/container-factory.mjs

@@ -0,0 +1,23 @@
+import { DIContainer, ServiceTokens } from "./container.mjs";
+import { PropertyEvaluator } from "./evaluator.mjs";
+import { NullLogger } from "./logger.mjs";
+import { DefaultOrchestrator } from "./runtime/orchestrator.mjs";
+import { JsonSerializer } from "./serializer.mjs";
+
+//#region src/container-factory.ts
+function createDefaultContainer(options = {}) {
+	const container = new DIContainer();
+	container.register(ServiceTokens.Logger, options.logger || new NullLogger());
+	container.register(ServiceTokens.Serializer, options.serializer || new JsonSerializer());
+	container.register(ServiceTokens.Evaluator, options.evaluator || new PropertyEvaluator());
+	container.register(ServiceTokens.EventBus, options.eventBus || { emit: async () => {} });
+	container.register(ServiceTokens.Middleware, options.middleware || []);
+	container.register(ServiceTokens.NodeRegistry, options.registry || {});
+	container.register(ServiceTokens.BlueprintRegistry, options.blueprints || {});
+	container.register(ServiceTokens.Dependencies, options.dependencies || {});
+	container.registerFactory(ServiceTokens.Orchestrator, () => new DefaultOrchestrator());
+	return container;
+}
+
+//#endregion
+export { createDefaultContainer };

package/dist/container.d.mts

@@ -0,0 +1,2 @@
+import { n as ServiceToken, r as ServiceTokens, t as DIContainer } from "./container-BKdd-9wf.mjs";
+export { DIContainer, ServiceToken, ServiceTokens };

package/dist/container.mjs

@@ -0,0 +1,43 @@
+//#region src/container.ts
+var DIContainer = class DIContainer {
+	services = /* @__PURE__ */ new Map();
+	factories = /* @__PURE__ */ new Map();
+	register(token, implementation) {
+		this.services.set(token, implementation);
+	}
+	registerFactory(token, factory) {
+		this.factories.set(token, factory);
+	}
+	resolve(token) {
+		if (this.services.has(token)) return this.services.get(token);
+		if (this.factories.has(token)) {
+			const instance = this.factories.get(token)?.(this);
+			this.services.set(token, instance);
+			return instance;
+		}
+		throw new Error(`Service not found for token: ${String(token)}`);
+	}
+	has(token) {
+		return this.services.has(token) || this.factories.has(token);
+	}
+	createChild() {
+		const child = new DIContainer();
+		child.services = new Map(this.services);
+		child.factories = new Map(this.factories);
+		return child;
+	}
+};
+const ServiceTokens = {
+	Logger: Symbol.for("flowcraft:logger"),
+	Serializer: Symbol.for("flowcraft:serializer"),
+	Evaluator: Symbol.for("flowcraft:evaluator"),
+	EventBus: Symbol.for("flowcraft:eventBus"),
+	Orchestrator: Symbol.for("flowcraft:orchestrator"),
+	Middleware: Symbol.for("flowcraft:middleware"),
+	NodeRegistry: Symbol.for("flowcraft:nodeRegistry"),
+	BlueprintRegistry: Symbol.for("flowcraft:blueprintRegistry"),
+	Dependencies: Symbol.for("flowcraft:dependencies")
+};
+
+//#endregion
+export { DIContainer, ServiceTokens };

package/dist/context-ZVtzXuZu.d.mts

@@ -0,0 +1,64 @@
+import { i as IAsyncContext, l as ISyncContext, y as PatchOperation } from "./types-BcrXJEPI.mjs";
+
+//#region src/context.d.ts
+/**
+ * A default, high-performance, in-memory implementation of ISyncContext using a Map.
+ */
+declare class Context<TContext extends Record<string, any>> implements ISyncContext<TContext> {
+  readonly type: "sync";
+  private data;
+  constructor(initialData?: Partial<TContext>);
+  get<K extends keyof TContext>(key: K): TContext[K] | undefined;
+  set<K extends keyof TContext>(key: K, value: TContext[K]): void;
+  has<K extends keyof TContext>(key: K): boolean;
+  delete<K extends keyof TContext>(key: K): boolean;
+  toJSON(): Record<string, any>;
+}
+/**
+ * An adapter that provides a consistent, Promise-based view of a synchronous context.
+ * This is created by the runtime and is transparent to the node author.
+ */
+declare class AsyncContextView<TContext extends Record<string, any>> implements IAsyncContext<TContext> {
+  private syncContext;
+  readonly type: "async";
+  constructor(syncContext: ISyncContext<TContext>);
+  get<K extends keyof TContext>(key: K): Promise<TContext[K] | undefined>;
+  set<K extends keyof TContext>(key: K, value: TContext[K]): Promise<void>;
+  has<K extends keyof TContext>(key: K): Promise<boolean>;
+  delete<K extends keyof TContext>(key: K): Promise<boolean>;
+  toJSON(): Promise<Record<string, any>>;
+  patch(_operations: PatchOperation[]): Promise<void>;
+}
+/**
+ * A proxy wrapper that tracks changes to an async context for delta-based persistence.
+ * Records all mutations (set/delete operations) to enable efficient partial updates.
+ */
+declare class TrackedAsyncContext<TContext extends Record<string, any>> implements IAsyncContext<TContext> {
+  readonly type: "async";
+  private deltas;
+  private innerContext;
+  private eventBus?;
+  private executionId?;
+  private sourceNode?;
+  constructor(innerContext: IAsyncContext<TContext>, eventBus?: any, executionId?: string, sourceNode?: string);
+  get<K extends keyof TContext>(key: K): Promise<TContext[K] | undefined>;
+  set<K extends keyof TContext>(key: K, value: TContext[K]): Promise<void>;
+  has<K extends keyof TContext>(key: K): Promise<boolean>;
+  delete<K extends keyof TContext>(key: K): Promise<boolean>;
+  toJSON(): Promise<Record<string, any>>;
+  patch(operations: PatchOperation[]): Promise<void>;
+  getDeltas(): PatchOperation[];
+  clearDeltas(): void;
+  /**
+   * Configures the event emitter for tracking context changes.
+   * This enables the context to emit events when set/delete operations occur,
+   * allowing for external monitoring and persistence of context mutations.
+   *
+   * @param eventBus - The event bus instance to emit context change events
+   * @param executionId - The unique identifier for the current workflow execution
+   * @param sourceNode - Optional identifier for the node that triggered the context change
+   */
+  configureEventEmitter(eventBus: any, executionId: string, sourceNode?: string): void;
+}
+//#endregion
+export { Context as n, TrackedAsyncContext as r, AsyncContextView as t };

package/dist/context.d.mts

@@ -0,0 +1,2 @@
+import { n as Context, r as TrackedAsyncContext, t as AsyncContextView } from "./context-ZVtzXuZu.mjs";
+export { AsyncContextView, Context, TrackedAsyncContext };