flowcraft 1.0.0-beta.1

package/src/builder/graph.ts

@@ -0,0 +1,336 @@
+import type { AbstractNode, FILTER_FAILED, Logger, NodeArgs } from '../workflow'
+import type { BuildResult, GraphBuilderOptions, GraphEdge, GraphNode, NodeRegistry, TypedNodeRegistry, TypedWorkflowGraph, WorkflowGraph } from './graph.types'
+import { generateMermaidGraph } from '../utils/mermaid'
+import { DEFAULT_ACTION, Flow, Node, NullLogger } from '../workflow'
+import { ParallelFlow } from './collection'
+
+/**
+ * A type-safe helper function for creating a `TypedNodeRegistry`.
+ * This function preserves the strong typing of the registry object, enabling
+ * compile-time validation of `TypedWorkflowGraph` definitions.
+ *
+ * @param registry The registry object, where keys are node types and values are `Node` constructors.
+ * @returns The same registry object, correctly typed for use with `GraphBuilder`.
+ */
+export function createNodeRegistry<T extends { [K in keyof T]: Record<string, any> }>(registry: TypedNodeRegistry<T>): TypedNodeRegistry<T> {
+	return registry
+}
+
+/**
+ * An internal node used by the GraphBuilder to handle the `inputs` mapping
+ * of an inlined sub-workflow. It copies data from the parent context scope
+ * to the sub-workflow's context scope.
+ * @internal
+ */
+class InputMappingNode extends Node {
+	private mappings: Record<string, string>
+	constructor(options: { data: Record<string, string> }) {
+		super()
+		const { nodeId, ...mappings } = options.data
+		this.mappings = mappings
+	}
+
+	async prep({ ctx, logger }: NodeArgs) {
+		for (const [subKey, parentKey] of Object.entries(this.mappings)) {
+			if (ctx.has(parentKey)) {
+				ctx.set(subKey, ctx.get(parentKey))
+			}
+			else {
+				logger.warn(`[InputMapper] Input mapping failed. Key '${parentKey}' not found in context.`)
+			}
+		}
+	}
+}
+
+/**
+ * An internal node used by the GraphBuilder to handle the `outputs` mapping
+ * of an inlined sub-workflow. It copies data from the sub-workflow's
+ * context scope back to the parent's context scope.
+ * @internal
+ */
+class OutputMappingNode extends Node {
+	private mappings: Record<string, string>
+	constructor(options: { data: Record<string, string> }) {
+		super()
+		const { nodeId, ...mappings } = options.data
+		this.mappings = mappings
+	}
+
+	async prep({ ctx, logger }: NodeArgs) {
+		for (const [parentKey, subKey] of Object.entries(this.mappings)) {
+			if (ctx.has(subKey)) {
+				ctx.set(parentKey, ctx.get(subKey))
+			}
+			else {
+				logger.warn(`[OutputMapper] Output mapping failed. Key '${subKey}' not found in context.`)
+			}
+		}
+	}
+}
+
+/** A private class used by the builder to represent parallel execution blocks. */
+class ParallelBranchContainer extends ParallelFlow {
+	/** A tag to reliably identify this node type in the visualizer. */
+	public readonly isParallelContainer = true
+	constructor(public readonly nodesToRun: AbstractNode[]) { super(nodesToRun) }
+}
+
+/**
+ * Constructs an executable `Flow` from a declarative `WorkflowGraph` definition.
+ * It supports a fully type-safe API for compile-time validation of graph definitions
+ * and intelligently handles complex patterns like parallel fan-out and fan-in.
+ * @template T A `NodeTypeMap` for validating type-safe graph definitions.
+ */
+export class GraphBuilder<T extends { [K in keyof T]: Record<string, any> }> {
+	private registry: Map<string, new (...args: any[]) => AbstractNode>
+	private subWorkflowNodeTypes: string[]
+	private logger: Logger
+
+	/**
+	 * @param registry A type-safe object or a `Map` where keys are node `type` strings and
+	 * values are the corresponding `Node` class constructors. For type-safety, use `createNodeRegistry`.
+	 * @param nodeOptionsContext An optional object that is passed to every node's
+	 * constructor, useful for dependency injection (e.g., passing a database client or the builder itself).
+	 */
+	// type-safe overload
+	constructor(registry: TypedNodeRegistry<T>, nodeOptionsContext?: Record<string, any>, options?: GraphBuilderOptions, logger?: Logger)
+	// untyped overload
+	constructor(registry: NodeRegistry, nodeOptionsContext?: Record<string, any>, options?: GraphBuilderOptions, logger?: Logger)
+	// handle both cases
+	constructor(
+		registry: TypedNodeRegistry<T> | NodeRegistry,
+		private nodeOptionsContext: Record<string, any> = {},
+		options: GraphBuilderOptions = {},
+		logger: Logger = new NullLogger(),
+	) {
+		this.logger = logger
+		if (registry instanceof Map) {
+			this.registry = registry
+		}
+		else {
+			this.registry = new Map(Object.entries(registry))
+		}
+		this.registry.set('__internal_input_mapper__', InputMappingNode as any)
+		this.registry.set('__internal_output_mapper__', OutputMappingNode as any)
+		this.subWorkflowNodeTypes = options.subWorkflowNodeTypes ?? []
+	}
+
+	private _logMermaid(flow: Flow) {
+		if (!(this.logger instanceof NullLogger)) {
+			this.logger.info('[GraphBuilder] Flattened Graph')
+			const mermaid = generateMermaidGraph(flow)
+			mermaid.split('\n').forEach(line => this.logger.info(line))
+		}
+	}
+
+	private _flattenGraph(graph: WorkflowGraph, idPrefix = ''): WorkflowGraph {
+		const finalNodes: GraphNode[] = []
+		const finalEdges: GraphEdge[] = []
+
+		const localNodeIds = new Set(graph.nodes.map(n => n.id))
+
+		// Pass 1: Recursively add all nodes, inlining sub-workflows and rewriting input paths.
+		for (const node of graph.nodes) {
+			const prefixedNodeId = `${idPrefix}${node.id}`
+			const isRegisteredSubWorkflow = this.subWorkflowNodeTypes.includes(node.type)
+			const hasWorkflowId = node.data && 'workflowId' in node.data
+
+			// Create a mutable copy of node data to safely rewrite input paths.
+			const newNodeData = JSON.parse(JSON.stringify(node.data || {}))
+
+			if (newNodeData.inputs) {
+				const inputs = newNodeData.inputs as Record<string, string | string[]>
+				for (const [templateKey, sourcePathOrPaths] of Object.entries(inputs)) {
+					const sourcePaths = Array.isArray(sourcePathOrPaths) ? sourcePathOrPaths : [sourcePathOrPaths]
+					const newSourcePaths = sourcePaths.map((sourcePath) => {
+						// If the input source is another node within this same graph file, prefix its ID.
+						// Otherwise, leave it as is (it's from a parent context or an initial value).
+						if (localNodeIds.has(sourcePath))
+							return `${idPrefix}${sourcePath}`
+
+						return sourcePath
+					})
+					inputs[templateKey] = Array.isArray(sourcePathOrPaths) ? newSourcePaths : newSourcePaths[0]
+				}
+			}
+
+			if (isRegisteredSubWorkflow) {
+				const subWorkflowData = node.data as any
+				const subWorkflowId = subWorkflowData.workflowId
+				const registry = this.nodeOptionsContext.registry as any
+				if (!registry || typeof registry.getGraph !== 'function')
+					throw new Error('GraphBuilder needs a registry with a `getGraph` method in its context to resolve sub-workflows.')
+
+				const subGraph: WorkflowGraph | undefined = registry.getGraph(subWorkflowId)
+				if (!subGraph)
+					throw new Error(`Sub-workflow with ID ${subWorkflowId} not found in registry.`)
+
+				const inputMapperId = `${prefixedNodeId}_input_mapper`
+				const outputMapperId = `${prefixedNodeId}_output_mapper`
+				finalNodes.push({ id: inputMapperId, type: '__internal_input_mapper__', data: subWorkflowData.inputs || {} })
+				finalNodes.push({ id: outputMapperId, type: '__internal_output_mapper__', data: subWorkflowData.outputs || {} })
+
+				const inlinedSubGraph = this._flattenGraph(subGraph, `${prefixedNodeId}:`)
+				finalNodes.push(...inlinedSubGraph.nodes)
+				finalEdges.push(...inlinedSubGraph.edges)
+
+				const subGraphStartIds = inlinedSubGraph.nodes.map(n => n.id).filter(id => !inlinedSubGraph.edges.some(e => e.target === id))
+				for (const startId of subGraphStartIds)
+					finalEdges.push({ source: inputMapperId, target: startId, action: DEFAULT_ACTION as any })
+
+				const subGraphTerminalIds = inlinedSubGraph.nodes.map(n => n.id).filter(id => !inlinedSubGraph.edges.some(e => e.source === id))
+				for (const terminalId of subGraphTerminalIds)
+					finalEdges.push({ source: terminalId, target: outputMapperId, action: DEFAULT_ACTION as any })
+			}
+			else if (hasWorkflowId) {
+				throw new Error(
+					`GraphBuilder Error: Node with ID '${node.id}' and type '${node.type}' contains a 'workflowId' property, `
+					+ `but its type is not registered in the 'subWorkflowNodeTypes' option. `
+					+ `Please add '${node.type}' to the subWorkflowNodeTypes array in the GraphBuilder constructor.`,
+				)
+			}
+			else {
+				// Add the normal node with its newly resolved input paths.
+				finalNodes.push({ ...node, id: prefixedNodeId, data: newNodeData })
+			}
+		}
+
+		// Pass 2: Re-wire all original edges to connect to the correct nodes in the flattened graph.
+		for (const edge of graph.edges) {
+			const sourceNode = graph.nodes.find(n => n.id === edge.source)!
+			const targetNode = graph.nodes.find(n => n.id === edge.target)!
+			const prefixedSourceId = `${idPrefix}${edge.source}`
+			const prefixedTargetId = `${idPrefix}${edge.target}`
+
+			const isSourceSub = this.subWorkflowNodeTypes.includes(sourceNode.type)
+			const isTargetSub = this.subWorkflowNodeTypes.includes(targetNode.type)
+
+			if (isSourceSub && isTargetSub)
+				finalEdges.push({ ...edge, source: `${prefixedSourceId}_output_mapper`, target: `${prefixedTargetId}_input_mapper` })
+			else if (isSourceSub)
+				finalEdges.push({ ...edge, source: `${prefixedSourceId}_output_mapper`, target: prefixedTargetId })
+			else if (isTargetSub)
+				finalEdges.push({ ...edge, source: prefixedSourceId, target: `${prefixedTargetId}_input_mapper` })
+			else
+				finalEdges.push({ ...edge, source: prefixedSourceId, target: prefixedTargetId })
+		}
+		return { nodes: finalNodes, edges: finalEdges }
+	}
+
+	/**
+	 * Builds a runnable `Flow` from a graph definition.
+	 * @param graph The `WorkflowGraph` object describing the flow.
+	 * @returns A `BuildResult` object containing the executable `flow` and a `nodeMap`.
+	 */
+	// type-safe overload
+	build(graph: TypedWorkflowGraph<T>): BuildResult
+	// untyped overload
+	build(graph: WorkflowGraph): BuildResult
+	// single implementation that handles both cases
+	build(graph: TypedWorkflowGraph<T> | WorkflowGraph): BuildResult {
+		const flatGraph = this._flattenGraph(graph as WorkflowGraph)
+
+		const nodeMap = new Map<string, AbstractNode>()
+		const predecessorMap = new Map<string, Set<string>>()
+		for (const edge of flatGraph.edges) {
+			if (!predecessorMap.has(edge.target))
+				predecessorMap.set(edge.target, new Set())
+			predecessorMap.get(edge.target)!.add(edge.source)
+		}
+		const predecessorCountMap = new Map<string, number>()
+		for (const node of flatGraph.nodes) {
+			const uniquePredecessors = predecessorMap.get(node.id)
+			predecessorCountMap.set(node.id, uniquePredecessors ? uniquePredecessors.size : 0)
+		}
+
+		// Pass 1: Instantiate all nodes.
+		for (const graphNode of flatGraph.nodes) {
+			const NodeClass = this.registry.get(graphNode.type.toString())
+			if (!NodeClass)
+				throw new Error(`GraphBuilder: Node type '${graphNode.type.toString()}' not found in the registry.`)
+
+			const nodeOptions = {
+				...this.nodeOptionsContext,
+				data: { ...graphNode.data, nodeId: graphNode.id },
+			}
+			const executableNode = new NodeClass(nodeOptions)
+				.withId(graphNode.id)
+				.withGraphData(graphNode)
+			nodeMap.set(graphNode.id, executableNode)
+		}
+
+		// Pass 2: Group all edges by their source and action. This map is the source of truth for wiring.
+		const edgeGroups = new Map<string, Map<string | typeof DEFAULT_ACTION | typeof FILTER_FAILED, AbstractNode[]>>()
+		for (const edge of flatGraph.edges) {
+			const sourceId = edge.source
+			const action = edge.action || DEFAULT_ACTION
+			const targetNode = nodeMap.get(edge.target)!
+
+			if (!edgeGroups.has(sourceId))
+				edgeGroups.set(sourceId, new Map())
+			const sourceActions = edgeGroups.get(sourceId)!
+			if (!sourceActions.has(action))
+				sourceActions.set(action, [])
+			sourceActions.get(action)!.push(targetNode)
+		}
+
+		// Pass 3: Wire the graph using the grouped edges, creating ParallelFlows where necessary.
+		for (const [sourceId, actions] of edgeGroups.entries()) {
+			const sourceNode = nodeMap.get(sourceId)!
+			for (const [action, successors] of actions.entries()) {
+				if (successors.length === 1) {
+					// Simple 1-to-1 connection.
+					sourceNode.next(successors[0], action)
+				}
+				else if (successors.length > 1) {
+					// Fan-out detected. Use our named container.
+					const parallelNode = new ParallelBranchContainer(successors)
+					sourceNode.next(parallelNode, action)
+
+					// Determine the single convergence point for this parallel block.
+					const firstBranchSuccessor = edgeGroups.get(successors[0].id!.toString())?.get(DEFAULT_ACTION)?.[0]
+					if (firstBranchSuccessor) {
+						const allConverge = successors.slice(1).every(
+							node => edgeGroups.get(node.id!.toString())?.get(DEFAULT_ACTION)?.[0] === firstBranchSuccessor,
+						)
+						// If all branches lead to the same next node, wire the container to it.
+						if (allConverge)
+							parallelNode.next(firstBranchSuccessor)
+					}
+				}
+			}
+		}
+
+		// Final Step: Determine the start node(s) for the entire flow.
+		const allNodeIds = Array.from(nodeMap.keys())
+		const allTargetIds = new Set(flatGraph.edges.map(e => e.target))
+		const startNodeIds = allNodeIds.filter(id => !allTargetIds.has(id))
+
+		if (startNodeIds.length === 0 && allNodeIds.length > 0)
+			throw new Error('GraphBuilder: This graph has a cycle and no clear start node.')
+
+		if (startNodeIds.length === 1) {
+			const startNode = nodeMap.get(startNodeIds[0])!
+			const flow = new Flow(startNode)
+			this._logMermaid(flow)
+			return { flow, nodeMap, predecessorCountMap }
+		}
+
+		// Handle parallel start nodes.
+		const startNodes = startNodeIds.map(id => nodeMap.get(id)!)
+		const parallelStartNode = new ParallelBranchContainer(startNodes)
+
+		if (startNodes.length > 0) {
+			const firstSuccessor = edgeGroups.get(startNodes[0].id!.toString())?.get(DEFAULT_ACTION)?.[0]
+			if (firstSuccessor) {
+				const allConverge = startNodes.slice(1).every(node => edgeGroups.get(node.id!.toString())?.get(DEFAULT_ACTION)?.[0] === firstSuccessor)
+				if (allConverge)
+					parallelStartNode.next(firstSuccessor)
+			}
+		}
+
+		const flow = new Flow(parallelStartNode)
+		this._logMermaid(flow)
+		return { flow, nodeMap, predecessorCountMap }
+	}
+}

package/src/builder/graph.types.ts

@@ -0,0 +1,104 @@
+import type { AbstractNode, Flow, NodeOptions } from '../workflow'
+
+export interface NodeTypeMap { [key: string]: Record<string, any> }
+
+/**
+ * The standard options object passed to a Node's constructor by the `GraphBuilder`.
+ * @template T The type of the `data` payload for this specific node.
+ */
+export interface NodeConstructorOptions<T> extends NodeOptions {
+	/** The `data` payload from the graph definition, with `nodeId` injected for logging/debugging. */
+	data: T & { nodeId: string }
+	/** A context object containing any dependencies injected into the `GraphBuilder` constructor. */
+	[key: string]: any
+}
+
+/**
+ * Represents a single, type-safe node within a declarative workflow graph.
+ * This is a discriminated union based on the `type` property, ensuring that
+ * the `data` payload matches the node's type as defined in the `TypedNodeRegistry`.
+ * @template T The `NodeTypeMap` that defines all possible node types and their data schemas.
+ */
+export type TypedGraphNode<T extends { [K in keyof T]: Record<string, any> }> = {
+	[K in keyof T]: {
+		/** A unique identifier for the node within the graph. */
+		id: string
+		/** The type of the node, used to look up the corresponding Node class in the registry. */
+		type: K
+		/** A flexible data object that must match the schema defined in the `NodeTypeMap` for this type. */
+		data: T[K]
+	}
+}[keyof T]
+
+/**
+ * Represents a directed edge connecting two nodes in a workflow graph.
+ */
+export interface GraphEdge {
+	/** The `id` of the source node. */
+	source: string
+	/** The `id` of the target node. */
+	target: string
+	/** The action from the source node that triggers this edge. Defaults to `DEFAULT_ACTION`. */
+	action?: string
+}
+
+/**
+ * Defines the structure of a type-safe, declarative workflow graph.
+ * @template T The `NodeTypeMap` that validates the graph's node definitions.
+ */
+export interface TypedWorkflowGraph<T extends { [K in keyof T]: Record<string, any> }> {
+	/** An array of node definitions. */
+	nodes: TypedGraphNode<T>[]
+	/** An array of edge definitions that connect the nodes. */
+	edges: GraphEdge[]
+}
+
+/**
+ * A type-safe registry that maps a node type string to its corresponding `Node` constructor.
+ * TypeScript ensures that the constructor's options match the schema defined in the `NodeTypeMap`.
+ * @template T The `NodeTypeMap` that defines all possible node types and their data schemas.
+ */
+export type TypedNodeRegistry<T extends { [K in keyof T]: Record<string, any> }> = {
+	[K in keyof T]: new (options: NodeConstructorOptions<T[K]>) => AbstractNode
+}
+
+/**
+ * The result of a successful `GraphBuilder.build()` call.
+ */
+export interface BuildResult {
+	/** The fully wired, executable `Flow` instance. */
+	flow: Flow
+	/** A map of all created node instances, keyed by their `id` from the graph definition. */
+	nodeMap: Map<string, AbstractNode>
+	/** A map of all node `id`s to their predecessor count. */
+	predecessorCountMap: Map<string, number>
+}
+
+/**
+ * Represents a node within the workflow graph.
+ * This is a simpler (UNTYPED) version of the `TypedGraphNode` type
+ */
+export interface GraphNode {
+	id: string
+	type: string
+	data?: Record<string, any>
+}
+
+/**
+ * Defines the structure of a workflow graph.
+ * This is a simpler (UNTYPED) version of the `TypedWorkflowGraph` type
+ */
+export interface WorkflowGraph {
+	nodes: GraphNode[]
+	edges: GraphEdge[]
+}
+
+/**
+ * A permissive (UNTYPED) registry that maps a node type string to a constructor.
+ * This is a simpler (UNTYPED) version of the `TypedNodeRegistry` type
+ */
+export type NodeRegistry = Map<string, new (...args: any[]) => AbstractNode>
+
+export interface GraphBuilderOptions {
+	subWorkflowNodeTypes?: string[]
+}

package/src/builder/index.ts

@@ -0,0 +1,3 @@
+export * from './collection'
+export * from './graph'
+export * from './graph.types'

package/src/context.ts

@@ -0,0 +1,111 @@
+/**
+ * A type-safe, opaque key for storing and retrieving values from the Context.
+ * Using a `ContextKey` provides compile-time safety for your workflow's state.
+ * @template T The type of the value this key refers to.
+ */
+export type ContextKey<T> = symbol & { __type: T }
+
+/**
+ * Creates a new, unique `ContextKey` for type-safe access to the `Context`.
+ * @template T The type of the value this key will hold.
+ * @param description An optional description for debugging purposes (e.g., in logs or test snapshots).
+ * @returns A unique `ContextKey<T>`.
+ */
+export const contextKey = <T>(description?: string): ContextKey<T> => Symbol(description) as ContextKey<T>
+
+/**
+ * Defines the interface for the shared context object passed through the workflow.
+ * It acts as the shared memory for all nodes in a flow. It supports both
+ * type-safe `ContextKey`s and flexible `string` keys.
+ */
+export interface Context {
+	/** Retrieves a value from the context. */
+	get: (<T>(key: ContextKey<T>) => T | undefined) & (<T = any>(key: string) => T | undefined)
+	/** Stores a value in the context. */
+	set: (<T>(key: ContextKey<T>, value: T) => this) & ((key: string, value: any) => this)
+	/** Checks if a key exists in the context. */
+	has: ((key: ContextKey<any>) => boolean) & ((key: string) => boolean)
+	/** Returns an iterator of all [key, value] pairs in the context. */
+	entries: () => IterableIterator<[any, any]>
+}
+
+/**
+ * The default, `Map`-based implementation of the `Context` interface.
+ */
+export class TypedContext implements Context {
+	private data: Map<any, any>
+
+	/**
+	 * @param initialData An optional iterable (like an array of `[key, value]` pairs)
+	 * to initialize the context with.
+	 */
+	constructor(initialData?: Iterable<readonly [ContextKey<any> | string, any]> | null) {
+		this.data = new Map<any, any>(initialData)
+	}
+
+	get(key: ContextKey<any> | string): any {
+		return this.data.get(key)
+	}
+
+	set(key: ContextKey<any> | string, value: any): this {
+		this.data.set(key, value)
+		return this
+	}
+
+	has(key: ContextKey<any> | string): boolean {
+		return this.data.has(key)
+	}
+
+	entries(): IterableIterator<[any, any]> {
+		return this.data.entries()
+	}
+}
+
+/** A function that takes a `Context` and returns a (potentially new) `Context`. */
+export type ContextTransform = (ctx: Context) => Context
+
+/**
+ * A "lens" provides a way to "focus" on a single key in the `Context`,
+ * creating reusable, type-safe functions to get, set, or update its value.
+ * @template T The type of the value the lens focuses on.
+ */
+export interface ContextLens<T> {
+	/** Retrieves the value for the key from the context. */
+	get: (ctx: Context) => T | undefined
+	/** Returns a `ContextTransform` function that will set the key to the provided value. */
+	set: (value: T) => ContextTransform
+	/** Returns a `ContextTransform` function that updates the key's value based on its current value. */
+	update: (fn: (current: T | undefined) => T) => ContextTransform
+}
+
+/**
+ * Creates a `ContextLens` object for a specific `ContextKey`.
+ * This is the entry point for functional context manipulation.
+ *
+ * @example
+ * const NAME = contextKey<string>('name')
+ * const nameLens = lens(NAME)
+ * const setNameTransform = nameLens.set('Alice') // This is a function: (ctx) => ctx.set(NAME, 'Alice')
+ *
+ * @param key The `ContextKey` to focus on.
+ * @returns A `ContextLens<T>` object with `.get()`, `.set()`, and `.update()` methods.
+ */
+export function lens<T>(key: ContextKey<T>): ContextLens<T> {
+	return {
+		get: (ctx: Context) => ctx.get(key),
+		set: (value: T) => (ctx: Context) => ctx.set(key, value),
+		update: (fn: (current: T | undefined) => T) => (ctx: Context) =>
+			ctx.set(key, fn(ctx.get(key))),
+	}
+}
+
+/**
+ * Composes multiple `ContextTransform` functions into a single `ContextTransform` function.
+ * The transformations are applied in the order they are provided.
+ *
+ * @param transforms A sequence of `ContextTransform` functions.
+ * @returns A single function that applies all transformations.
+ */
+export function composeContext(...transforms: ContextTransform[]): ContextTransform {
+	return (ctx: Context) => transforms.reduce((acc, transform) => transform(acc), ctx)
+}

package/src/errors.ts

@@ -0,0 +1,34 @@
+/**
+ * Error thrown when a workflow is gracefully aborted via an `AbortSignal`.
+ * This error is caught by the execution engine to halt the flow.
+ */
+export class AbortError extends Error {
+	constructor(message = 'Workflow aborted') {
+		super(message)
+		this.name = 'AbortError'
+	}
+}
+
+/**
+ * A custom error class for failures within a workflow, providing additional
+ * context about where and when the error occurred.
+ */
+export class WorkflowError extends Error {
+	/**
+	 * @param message The error message.
+	 * @param nodeName The name of the `Node` class where the error occurred.
+	 * @param phase The lifecycle phase (`'prep'`, `'exec'`, or `'post'`) where the error was thrown.
+	 * @param originalError The underlying error that was caught and wrapped.
+	 */
+	constructor(
+		message: string,
+		public readonly nodeName: string,
+		public readonly phase: 'prep' | 'exec' | 'post',
+		public readonly originalError?: Error,
+	) {
+		super(message)
+		this.name = 'WorkflowError'
+		if (originalError?.stack)
+			this.stack = `${this.stack}\nCaused by: ${originalError.stack}`
+	}
+}

package/src/executor.ts

@@ -0,0 +1,29 @@
+import type { Context, Flow, Logger, Params, RunOptions } from './workflow'
+
+/**
+ * Defines the contract for a workflow execution engine.
+ * An executor is responsible for taking a `Flow` definition and running it,
+ * orchestrating the traversal of the node graph.
+ */
+export interface IExecutor {
+	/**
+	 * Executes a given flow with a specific context and options.
+	 * @param flow The `Flow` instance to execute.
+	 * @param context The shared `Context` for the workflow run.
+	 * @param options Runtime options, which can include a logger, abort controller, or initial params.
+	 * @returns A promise that resolves with the final action of the workflow, or another result
+	 * depending on the executor's implementation (e.g., a job ID for a distributed executor).
+	 */
+	run: (flow: Flow, context: Context, options?: RunOptions) => Promise<any>
+}
+
+/**
+ * Internal, normalized run options used by executors.
+ * @internal
+ */
+export interface InternalRunOptions {
+	logger: Logger
+	signal?: AbortSignal
+	params: Params
+	executor: IExecutor
+}