flowcraft 1.0.0-beta.1

package/docs/api-reference/fn.md

@@ -0,0 +1,142 @@
+# API Reference: Functional Helpers
+
+This document covers the functions provided by Flowcraft for a more functional-style approach to creating `Node` instances and simple workflows. All helpers are imported from the main `flowcraft` package.
+
+```typescript
+import {
+	composeContext,
+	contextNode,
+	lens,
+	mapNode,
+	pipeline,
+	transformNode,
+} from 'flowcraft'
+```
+
+## `mapNode<TIn, TOut>(fn)`
+
+Creates a `Node` from a simple, pure function that transforms an input to an output. The node's `params` object is passed as the single argument to the provided function `fn`. The result of `fn` becomes the `exec` result of the node.
+
+### Parameters
+
+- `fn: (input: TIn) => TOut | Promise<TOut>`: A synchronous or asynchronous function that takes an input object and returns a result. `TIn` corresponds to the type of the node's `params`.
+
+### Returns
+
+- `Node<TIn, TOut>`: A new `Node` instance that wraps the function.
+
+### Example
+
+```typescript
+import { mapNode } from 'flowcraft'
+
+// Define a reusable node that doubles the 'value' param
+const doublerNode = mapNode((params: { value: number }) => params.value * 2)
+
+// Use it in a flow
+doublerNode.withParams({ value: 5 }) // This node will produce the result 10
+```
+
+## `contextNode<TIn, TOut>(fn)`
+
+Creates a `Node` from a function that requires access to the shared `Context` in addition to its `params`.
+
+### Parameters
+
+- `fn: (ctx: Context, input: TIn) => TOut | Promise<TOut>`: A function that takes the `Context` as its first argument and the node's `params` as its second. The result of `fn` becomes the `exec` result of the node.
+
+### Returns
+
+- `Node<TIn, TOut>`: A new `Node` instance that wraps the function.
+
+### Example
+
+```typescript
+import { contextKey, contextNode } from 'flowcraft'
+
+const USER_NAME = contextKey<string>('user_name')
+
+// A node that constructs a greeting using a value from the context
+const greetingNode = contextNode(ctx => `Hello, ${ctx.get(USER_NAME)}!`)
+```
+
+## `transformNode(...transforms)`
+
+Creates a `Node` that is used purely for its side effect of modifying the `Context`. It does not produce an `exec` result. Its logic runs in the `prep` phase. It is often used with `ContextTransform` functions created by a `lens`.
+
+### Parameters
+
+- `...transforms: ContextTransform[]`: A sequence of `ContextTransform` functions. A `ContextTransform` is a function of the shape `(ctx: Context) => Context`.
+
+### Returns
+
+- `Node`: A new `Node` instance that will apply the context transformations when it runs.
+
+### Example
+
+```typescript
+import { lens, transformNode } from 'flowcraft'
+
+const NAME = contextKey<string>('name')
+const AGE = contextKey<number>('age')
+const nameLens = lens(NAME)
+const ageLens = lens(AGE)
+
+// A single node that sets both name and age in the context
+const setupContextNode = transformNode(
+	nameLens.set('Alice'),
+	ageLens.set(30)
+)
+```
+
+## `pipeline(...nodes)`
+
+A functional-style alias for the `SequenceFlow` builder. It constructs a linear `Flow` where each node executes in the order it is provided.
+
+### Parameters
+
+- `...nodes: Node[]`: A sequence of `Node` instances to chain together.
+
+### Returns
+
+- `Flow`: A `Flow` instance representing the linear sequence.
+
+## `lens<T>(key)`
+
+Creates a `ContextLens` object, which provides a type-safe way to generate functions that interact with a specific key in the `Context`.
+
+### Parameters
+
+- `key: ContextKey<T>`: The `ContextKey` to focus on.
+
+### Returns
+
+- `ContextLens<T>`: An object with the following methods:
+  - `.get(ctx: Context): T | undefined`: Retrieves the value for the key from the context.
+  - `.set(value: T): ContextTransform`: Returns a function that, when called with a `Context`, will set the key to the provided `value`.
+  - `.update(fn: (current: T | undefined) => T): ContextTransform`: Returns a function that updates the key's value based on its current value.
+
+### Example
+
+```typescript
+const NAME = contextKey<string>('name')
+const nameLens = lens(NAME)
+
+// Create a transform function that sets the name to 'Alice'
+const setNameTransform = nameLens.set('Alice')
+
+// Create a node that applies this transform
+const setNode = transformNode(setNameTransform)
+```
+
+## `composeContext(...transforms)`
+
+Composes multiple `ContextTransform` functions into a single `ContextTransform` function. The transformations are applied in the order they are provided.
+
+### Parameters
+
+- `...transforms: ContextTransform[]`: A sequence of `ContextTransform` functions.
+
+### Returns
+
+- `ContextTransform`: A single function that applies all transformations.

package/docs/api-reference/index.md

@@ -0,0 +1,38 @@
+# API Reference
+
+This section provides a detailed, technical breakdown of the core classes, functions, and types available in the Flowcraft framework. It is intended as a reference for when you know what component you need to use and want to understand its specific capabilities.
+
+All components are imported from the main `flowcraft` package. For a more narrative-driven explanation of these concepts, please see the **[Guide](../guide/)**.
+
+## Core Workflow API
+
+This is the main entry point for the most essential components of the framework.
+
+- **[Core Workflow API](./workflow.md)**: Detailed documentation for the fundamental building blocks:
+  - `Node`: The base class for a unit of work.
+  - `Flow`: The orchestrator for a graph of nodes.
+  - `IExecutor` and `InMemoryExecutor`: The execution engine contract and its default implementation.
+  - `Context`, `TypedContext`, `ContextKey`, and `contextKey()`: For type-safe state management.
+  - `Logger` implementations: `ConsoleLogger` and `NullLogger`.
+  - Error types: `WorkflowError` and `AbortError`.
+
+## Builder API
+
+This module contains classes that simplify the creation of common and complex workflow patterns.
+
+- **[Builder API](./builder.md)**: Documentation for the builder classes:
+  - `SequenceFlow`: For creating simple, linear workflows.
+  - `BatchFlow`: For processing a collection of items sequentially.
+  - `ParallelBatchFlow`: For processing a collection of items concurrently.
+  - `GraphBuilder`: For constructing a `Flow` from a declarative, type-safe graph definition.
+
+## Functional API
+
+This module provides a set of functions for creating nodes and pipelines in a more functional programming style.
+
+- **[Functional API](./fn.md)**: Documentation for the functional helpers:
+  - `mapNode`: Creates a `Node` from a simple, pure function.
+  - `contextNode`: Creates a `Node` from a function that requires `Context` access.
+  - `pipeline`: A functional alias for creating a linear `SequenceFlow`.
+  - `transformNode`: Creates a `Node` for declaratively updating the `Context` using lenses.
+  - `lens` and `composeContext`: Utilities for functional context manipulation.

package/docs/api-reference/workflow.md

@@ -0,0 +1,126 @@
+# API Reference: Core Workflow
+
+This document covers the core classes and types exported from the main `flowcraft` entry point. These are the fundamental building blocks of any workflow.
+
+```typescript
+import {
+	Context,
+	ContextKey,
+	contextKey,
+	Flow,
+	InMemoryExecutor,
+	Node,
+	TypedContext,
+	// ...and more
+} from 'flowcraft'
+```
+
+## `Node<PrepRes, ExecRes, PostRes>`
+
+The base class for a single unit of work.
+
+### Constructor
+
+`new Node(options?: NodeOptions)`
+
+- `options`: An optional object to configure the node's behavior.
+  - `maxRetries?: number`: Total number of `exec` attempts. Defaults to `1`.
+  - `wait?: number`: Milliseconds to wait between failed `exec` attempts. Defaults to `0`.
+
+### Lifecycle Methods
+
+These methods are designed to be overridden in your custom `Node` subclasses.
+
+- `async prep(args: NodeArgs): Promise<PrepRes>`: Prepares data for execution. Runs before `exec`. Ideal for reading from the context.
+- `async exec(args: NodeArgs<PrepRes>): Promise<ExecRes>`: Performs the core, isolated logic. Its result is passed to `post`. This is the only phase that is retried on failure.
+- `async post(args: NodeArgs<PrepRes, ExecRes>): Promise<PostRes>`: Processes results and determines the next step. Runs after `exec`. Ideal for writing to the context. Should return an action string. The default return is `DEFAULT_ACTION`.
+- `async execFallback(args: NodeArgs<PrepRes>): Promise<ExecRes>`: Runs if all `exec` retries fail. If not implemented, the error will be re-thrown.
+
+### Fluent API Methods
+
+> [!IMPORTANT]
+> These methods are **immutable**. They return a *new* `Node` instance for creating data processing pipelines and do not modify the original node. You must chain them or assign the result to a new variable.
+
+- `.map<NewRes>(fn)`: Transforms the `exec` result into a new type.
+- `.toContext(key)`: Stores the `exec` result in the `Context` using the provided `ContextKey`.
+- `.filter(predicate)`: Conditionally proceeds. Returns `DEFAULT_ACTION` if the predicate is true, `FILTER_FAILED` otherwise.
+- `.tap(fn)`: Performs a side-effect with the `exec` result without modifying it.
+- `.withLens(lens, value)`: Applies a context mutation using a `ContextLens` before this node's `prep` phase.
+
+### Other Methods
+
+- `.next(node, action?)`: Connects this node to a successor. Returns the successor node for chaining.
+- `.withParams(params)`: Sets or merges parameters for the node.
+- `.run(ctx, options?)`: Runs the node as a standalone unit using an `IExecutor`.
+
+## `Flow`
+
+A special `Node` that acts as a container for a graph of other nodes and their shared middleware.
+
+`extends Node`
+
+### Constructor
+
+`new Flow(startNode?: AbstractNode)`
+
+- `startNode`: The node where the flow's execution should begin.
+
+### Methods
+
+- `.use(fn: Middleware)`: Adds a middleware function that the `Executor` will apply to every node within this flow.
+- `.start(node)`: Sets the starting node of the flow. Returns the start node.
+- `.run(ctx, options?)`: Runs the entire flow using an `IExecutor`. This is the main entry point for executing a workflow. The method returns the action from the last node executed.
+- `.exec(args)`: This lifecycle method is called when a `Flow` is used as a sub-flow (a node within another flow). It contains the logic to orchestrate the sub-flow's internal graph from start to finish.
+- `.getNodeById(id: string | number): AbstractNode | undefined`: Finds a node within the flow's graph by its unique ID. This method performs a breadth-first search from the `startNode` and is useful for debugging or dynamic modifications of programmatically-built flows.
+
+> [!WARNING]
+> `.getNodeById()` traverses the graph on each call (O(V+E) complexity). For flows built with `GraphBuilder`, it is much more efficient to use the `nodeMap` returned by the `.build()` method for O(1) lookups.
+
+## `IExecutor` and `InMemoryExecutor`
+
+- `IExecutor`: The interface that defines the contract for a workflow execution engine.
+- `InMemoryExecutor`: The standard `IExecutor` implementation for running flows in-memory. This is the default executor if none is provided.
+
+### `InMemoryExecutor` Constructor
+
+`new InMemoryExecutor()`
+
+## `Context` and `TypedContext`
+
+The shared memory of a workflow.
+
+- `Context`: The interface that defines the contract for a context object.
+- `TypedContext`: The standard `Map`-based implementation of the `Context` interface.
+
+### `TypedContext` Constructor
+
+`new TypedContext(initialData?)`
+
+- `initialData`: An optional iterable (like an array of `[key, value]` pairs) to initialize the context with.
+
+### Methods
+
+- `.get<T>(key)`: Retrieves a value from the context. Can be called with a `ContextKey<T>` (returns `T | undefined`) or a `string` (returns `any`).
+- `.set<T>(key, value)`: Stores a value in the context.
+- `.has(key)`: Checks if a key exists in the context.
+
+## `ContextKey` and `contextKey()`
+
+The mechanism for type-safe access to the `Context`.
+
+> [!IMPORTANT]
+> Always prefer `contextKey()` over raw strings to access the context. This provides compile-time type checking and prevents common bugs from typos.
+
+- `ContextKey<T>`: An opaque type representing a key for a value of type `T`.
+- `contextKey<T>(description?: string)`: A factory function that creates a new, unique `ContextKey<T>`. The `description` is used for debugging and is not functionally significant.
+
+## Logger Interfaces
+
+- `Logger`: The interface that any logger passed to a flow must implement (`debug`, `info`, `warn`, `error`).
+- `ConsoleLogger`: A default implementation that logs messages to the `console`.
+- `NullLogger`: A default implementation that performs no action. This is the framework's default if no logger is provided, ensuring it is silent by default.
+
+## Error Types
+
+- `WorkflowError`: A custom error wrapper that provides context about a failure (`nodeName`, `phase`, `originalError`).
+- `AbortError`: The error thrown when a workflow is cancelled via an `AbortSignal`.

package/docs/guide/advanced-guides/cancellation.md

@@ -0,0 +1,117 @@
+# Cancellation Support
+
+In many applications, especially those involving long-running asynchronous operations, you need a way to gracefully abort a process that is already in flight. Flowcraft provides robust cancellation support out of the box by integrating with the standard web `AbortController` and `AbortSignal` APIs.
+
+## How It Works
+
+When you run a `Flow`, you can pass an `AbortController` instance in the `RunOptions`.
+
+```typescript
+const controller = new AbortController()
+flow.run(context, { controller })
+```
+
+> [!IMPORTANT]
+> Flowcraft passes the `AbortSignal` to every node, but it's your responsibility to use it. The framework cannot magically interrupt your asynchronous code. You must design your `exec` logic to listen for the abort event and stop its work, as shown in the examples below.
+
+Calling `controller.abort()` will cause the currently running asynchronous operation to throw an `AbortError`, which immediately and cleanly halts the entire workflow.
+
+## When to Use Cancellation
+
+- **User-Initiated Actions**: In a web server, a user might navigate away from a page or click a "Cancel" button while a complex background job is running. You can use the `AbortSignal` from the HTTP request to abort the workflow.
+- **Timeouts**: You can implement a timeout by calling `controller.abort()` after a certain duration.
+- **Resource Management**: If a parent process is shutting down, it can signal its child workflows to abort their tasks cleanly.
+
+## Implementing a Cancellable Node
+
+To make a `Node` cancellable, you need to use the `signal` object provided in the `NodeArgs` within your asynchronous logic.
+
+### Example: A Cancellable `sleep`
+
+The most common use case is passing the `signal` to I/O-bound operations like `fetch` or custom-built helpers. Let's create a `sleep` function that respects the `AbortSignal`.
+
+```typescript
+import { AbortError } from 'flowcraft'
+
+// A helper that rejects if the signal is aborted
+async function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+	return new Promise((resolve, reject) => {
+		// Check if the operation was already aborted
+		if (signal?.aborted) {
+			return reject(new AbortError())
+		}
+
+		const timeoutId = setTimeout(resolve, ms)
+
+		// Add an event listener to clean up when aborted
+		signal?.addEventListener('abort', () => {
+			clearTimeout(timeoutId)
+			reject(new AbortError())
+		})
+	})
+}
+```
+
+(Note: A `sleep` utility like this is included in Flowcraft).
+
+### Example: A Long-Running Node
+
+Now, let's use this `sleep` function inside a `Node`.
+
+```typescript
+import { AbortError, ConsoleLogger, Flow, Node, sleep, TypedContext } from 'flowcraft'
+
+class LongRunningNode extends Node {
+	async exec({ signal, logger }) {
+		logger.info('Starting a very long task...')
+		try {
+			// Pass the signal to our async operation
+			await sleep(5000, signal)
+			logger.info('Task finished successfully.')
+		}
+		catch (e) {
+			if (e instanceof AbortError) {
+				logger.warn('The long task was aborted!')
+			}
+			// Re-throw the error to ensure the flow stops
+			throw e
+		}
+	}
+}
+
+const flow = new Flow(new LongRunningNode())
+const context = new TypedContext()
+const controller = new AbortController()
+
+// Set a timeout to abort the flow after 1 second
+setTimeout(() => {
+	console.log('>>> Aborting workflow from the outside!')
+	controller.abort()
+}, 1000)
+
+try {
+	await flow.run(context, { controller, logger: new ConsoleLogger() })
+}
+catch (e) {
+	if (e instanceof AbortError) {
+		console.error('Workflow execution was successfully aborted.')
+	}
+	else {
+		console.error('An unexpected error occurred:', e)
+	}
+}
+```
+
+When you run this code, the output will be:
+
+```
+[INFO] Running node: LongRunningNode
+[INFO] Starting a very long task...
+>>> Aborting workflow from the outside!
+[WARN] The long task was aborted!
+Workflow execution was successfully aborted.
+```
+
+The `sleep` function was interrupted, the `catch` block inside the node logged a warning, and the re-thrown `AbortError` was caught at the top level, confirming that the workflow was gracefully terminated.
+
+This cancellation pattern is robust and extends to custom execution environments. For instance, the distributed worker example demonstrates how to bridge an external cancellation signal (from Redis) to the standard `AbortSignal`, ensuring that even long-running, distributed jobs can be gracefully terminated mid-flight.

package/docs/guide/advanced-guides/composition.md

@@ -0,0 +1,68 @@
+# Composition
+
+One of the most powerful features of Flowcraft is its composability. Because a `Flow` is itself a type of `Node`, you can treat an entire workflow as a single building block within a larger, more complex workflow.
+
+Flowcraft supports two primary models for composition, each suited to different use cases.
+
+## 1. Programmatic Composition (In-Memory)
+
+When you build workflows programmatically (by instantiating `Node` and `Flow` classes and wiring them with `.next()`), you can place one `Flow` instance inside another.
+
+**How It Works:** The `InMemoryExecutor` understands this pattern. When its orchestration loop encounters a `Flow` node, it calls that node's `exec` method. The `Flow.exec` method then takes over and runs its *own* internal orchestration loop, executing its entire graph from start to finish. The final action from the sub-flow is returned to the parent, allowing for branching.
+
+**When to Use:** This model is excellent for simple, in-memory workflows where you want to organize logic into reusable, testable sub-units.
+
+### Example: A Reusable "Math" Sub-Flow
+
+```typescript
+// --- sub-flow.ts ---
+// A sub-flow that adds 10, multiplies by 2, and returns an action.
+export function createMathFlow(): Flow {
+	const addNode = new Node().exec(async ({ params }) => params.input + 10).toContext(MATH_VALUE)
+	const multiplyNode = new Node().exec(async ({ ctx }) => ctx.get(MATH_VALUE)! * 2).toContext(MATH_VALUE)
+	const checkNode = new CheckResultNode() // Returns 'over_50' or 'under_50'
+
+	addNode.next(multiplyNode).next(checkNode)
+	return new Flow(addNode)
+}
+
+// --- main.ts ---
+const mathSubFlow = createMathFlow()
+const handleOver50Node = new Node().exec(() => console.log('Result was over 50.'))
+const handleUnder50Node = new Node().exec(() => console.log('Result was 50 or under.'))
+
+// The parent flow starts with the sub-flow instance.
+const parentFlow = new Flow(mathSubFlow)
+mathSubFlow.next(handleOver50Node, 'over_50')
+mathSubFlow.next(handleUnder50Node, 'under_50')
+
+await parentFlow.withParams({ input: 20 }).run(new TypedContext()) // "Result was over 50."
+```
+
+## 2. Declarative Composition with `GraphBuilder`
+
+For complex, declarative, and distributed workflows, Flowcraft uses a more powerful **"Graph Inlining"** pattern. This is the recommended approach for building scalable systems.
+
+> [!IMPORTANT]
+> **You must explicitly tell the builder which node types represent sub-workflows** by passing them in its constructor. This gives you the flexibility to use semantically rich names like `"search-workflow"` or `"process-document-pipeline"`.
+>
+> If the builder encounters a node with a `workflowId` property in its `data` payload whose `type` has not been registered as a sub-workflow, it will throw a configuration error.
+
+**How It Works:** This is a **build-time** process, not a runtime one. When the `GraphBuilder` encounters a node whose type is registered as a sub-workflow, it performs "graph surgery":
+
+1.  **Replaces the Node**: It removes the composite node from the graph.
+2.  **Inlines the Graph**: It fetches the sub-workflow's graph definition and injects all of its nodes and edges into the parent graph, prefixing their IDs to prevent collisions.
+3.  **Inserts Mapping Nodes**: It automatically creates two lightweight "gatekeeper" nodes:
+    *   An **`InputMappingNode`** at the entry point, which copies data from the parent context to the keys expected by the sub-workflow (based on your `inputs` map).
+    *   An **`OutputMappingNode`** at the exit point, which copies data from the sub-workflow's context back to the parent (based on your `outputs` map).
+4.  **Re-wires Edges**: All original edges are seamlessly re-wired to these new mapping nodes.
+
+The result is a single, unified, "flat" graph that is handed to the executor.
+
+### Benefits of Graph Inlining
+
+-   **Simplified Runtimes**: The executor (e.g., `BullMQExecutor`) is completely unaware of composition. It just runs a larger, pre-compiled graph, making the runtime logic much simpler and faster.
+-   **Non-Blocking Workers**: This is critical for distributed systems. A worker never has to block and wait for a sub-workflow to finish. It executes its single node and moves on.
+-   **Clear Data Contracts**: The `inputs` and `outputs` maps in your JSON definition become an explicit, declarative data contract, preventing state leakage and making data flow easy to trace. See the guide on **[Best Practices: Data Flow in Sub-Workflows](../best-practices/sub-workflow-data.md)** for more details.
+
+This powerful pattern moves complexity from the runtime to the build step, which is a best practice for building robust, high-performance systems.

package/docs/guide/advanced-guides/custom-executor.md

@@ -0,0 +1,180 @@
+# Building a Custom Executor
+
+The `IExecutor` pattern is one of Flowcraft's most powerful architectural features. It decouples the definition of a workflow (the graph of `Node`s) from its execution environment. While the default `InMemoryExecutor` is perfect for many use cases, you can create your own executors to run workflows in different environments, such as a distributed task queue, a test environment, or even a system that requires pausing and resuming.
+
+This guide will walk you through the responsibilities of an executor and show you how to build a simple `DryRunExecutor` from scratch.
+
+## The `IExecutor` Interface
+
+At its core, an executor is any class that implements the `IExecutor` interface. The interface is intentionally simple:
+
+```typescript
+interface IExecutor {
+	run: (flow: Flow, context: Context, options?: RunOptions) => Promise<any>
+}
+```
+
+The `run` method is the main entry point. When you call `flow.run(ctx, { executor: myExecutor })`, your executor's `run` method is invoked.
+
+## Core Responsibilities of an Executor
+
+An executor is responsible for the entire orchestration of a `Flow`. This involves several key tasks:
+
+1. **The `run` Entry Point**: This public method kicks off the workflow. It's responsible for setting up the initial state and starting the execution loop.
+2. **The Execution Loop**: It must traverse the workflow graph, executing one node at a time. This typically involves a `while` loop that continues as long as there is a `currentNode` to process.
+3. **Applying Middleware**: Before executing a node, it must apply any middleware that has been attached to the `Flow`.
+4. **Passing Arguments**: It is responsible for constructing the `NodeArgs` object and passing the correct `ctx`, `params`, `signal`, `logger`, and a reference to *itself* down to the `node._run()` method (or a middleware chain).
+5. **Handling Actions & Branching**: After a node runs, the executor must take the returned `action`, look up the correct successor node in `currentNode.successors`, and determine the next node to execute.
+6. **State Management (for distributed systems)**: If the executor runs across different processes, it is responsible for serializing the `Context` before passing it to the next job and deserializing it upon receipt.
+
+## Step-by-Step Example: Building a `DryRunExecutor`
+
+To understand these responsibilities in practice, let's build a `DryRunExecutor`. This executor will traverse an entire workflow graph and log the path it would take, but it will **not** execute the core `exec()` logic of any node. This is a great tool for debugging the structure and conditional logic of a complex flow.
+
+### 1. The Class Structure
+
+First, create the class and implement the `IExecutor` interface.
+
+```typescript
+// src/executors/dry-run-executor.ts
+import {
+	AbstractNode,
+	Context,
+	DEFAULT_ACTION,
+	Flow,
+	IExecutor,
+	Logger,
+	NullLogger,
+	RunOptions
+} from 'flowcraft'
+
+export class DryRunExecutor implements IExecutor {
+	public async run(flow: Flow, context: Context, options?: RunOptions): Promise<any> {
+		// Implementation will go here
+	}
+}
+```
+
+### 2. The `run` Method and Orchestration Loop
+
+The `run` method will prepare the logger and initial parameters and then enter the main orchestration loop. This is where the core logic of the executor lives.
+
+```typescript
+// Inside DryRunExecutor class...
+public async run(flow: Flow, context: Context, options?: RunOptions): Promise<any> {
+    const logger = options?.logger ?? new NullLogger()
+    const params = { ...flow.params, ...options?.params }
+
+    logger.info(`[DryRunExecutor] Starting dry run for flow: ${flow.constructor.name}`)
+
+    if (!flow.startNode) {
+        logger.warn('[DryRunExecutor] Flow has no start node.')
+        return
+    }
+
+    let currentNode: AbstractNode | undefined = flow.startNode
+    let lastAction: any
+
+    // The executor's main orchestration loop.
+    while (currentNode) {
+        logger.info(`[DryRunExecutor] --> Visiting node: ${currentNode.constructor.name}`)
+
+        // For a dry run, we simulate execution to get the next action.
+        // We run `prep` and `post` to see data flow and branching, but SKIP `exec`.
+        // This is a powerful debugging pattern.
+        const node = currentNode
+        let action
+
+        if (node instanceof Flow) {
+            // If the node is a sub-flow, we must run it to get its final action.
+            // A real executor (like InMemoryExecutor) delegates this to a helper
+            // method, e.g., `_orchestrateGraph(subFlow.startNode, ...)`.
+            // For our dry run, we can recursively call ourself.
+            action = await new DryRunExecutor().run(node, context, { ...options, params })
+        } else {
+            // For a regular node, run prep and post, but not exec.
+            await node.prep({ ctx: context, params, logger } as any)
+            // We call post with a null `execRes` as exec was skipped.
+            action = await node.post({ ctx: context, params, logger, execRes: null } as any)
+        }
+
+        lastAction = action
+
+        // Display the action for logging.
+        const actionDisplay = (typeof lastAction === 'symbol' && lastAction === DEFAULT_ACTION)
+            ? 'default'
+            : String(lastAction)
+
+        logger.info(`[DryRunExecutor] <-- Node returned action: '${actionDisplay}'`)
+
+        // Find the next node based on the action.
+        currentNode = node.successors.get(lastAction)
+    }
+
+    logger.info('[DryRunExecutor] Dry run complete.')
+    return lastAction
+}
+```
+
+### 3. Using the Custom Executor
+
+Now you can use this executor with any flow. Note that the node's `exec` logic (the `console.log`) will not run.
+
+```typescript
+// main.ts
+import { ConsoleLogger, contextKey, Flow, Node, TypedContext } from 'flowcraft'
+import { DryRunExecutor } from './executors/dry-run-executor'
+
+const VALUE = contextKey<number>('value')
+
+// A node to set up initial state
+const startNode = new Node().prep(async ({ ctx }) => ctx.set(VALUE, 15))
+
+// A conditional node
+class CheckValueNode extends Node<void, void, 'over' | 'under'> {
+	async post({ ctx }) {
+		return ctx.get(VALUE)! > 10 ? 'over' : 'under'
+	}
+}
+const checkNode = new CheckValueNode()
+
+// Nodes for different branches
+const overNode = new Node().exec(() => console.log('This should NOT be logged!'))
+const underNode = new Node().exec(() => console.log('This should NOT be logged either!'))
+
+// Wire the graph
+startNode.next(checkNode)
+checkNode.next(overNode, 'over')
+checkNode.next(underNode, 'under')
+
+const flow = new Flow(startNode)
+const context = new TypedContext()
+const logger = new ConsoleLogger()
+const dryRunExecutor = new DryRunExecutor()
+
+console.log('--- Starting Dry Run ---')
+await flow.run(context, { logger, executor: dryRunExecutor })
+```
+
+### Expected Output
+
+When you run this code, you'll see the executor's logs tracing the path. The `context` is modified by `prep` and `post`, so the conditional logic works, but the `console.log` messages inside the `overNode`'s `exec` method will **not** appear.
+
+```
+--- Starting Dry Run ---
+[INFO] [DryRunExecutor] Starting dry run for flow: Flow
+[INFO] [DryRunExecutor] --> Visiting node: Node
+[INFO] [DryRunExecutor] <-- Node returned action: 'default'
+[INFO] [DryRunExecutor] --> Visiting node: CheckValueNode
+[INFO] [DryRunExecutor] <-- Node returned action: 'over'
+[INFO] [DryRunExecutor] --> Visiting node: Node
+[INFO] [DryRunExecutor] <-- Node returned action: 'default'
+[INFO] [DryRunExecutor] Dry run complete.
+```
+
+## Real-World Examples
+
+This `DryRunExecutor` is a simplified example. For a complete understanding, it's highly recommended to study the source code of the official executors:
+
+- **`InMemoryExecutor`**: The canonical implementation of a real executor. It shows the full orchestration logic, including how to correctly apply middleware. ([`src/executors/in-memory.ts`](https://github.com/gorango/flowcraft/tree/master/src/executors/in-memory.ts))
+- **`BullMQExecutor`**: A full-featured distributed executor. It demonstrates a completely different execution strategy, managing a job queue instead of an in-memory loop. ([`sandbox/5.distributed/src/executor.ts`](https://github.com/gorango/flowcraft/tree/master/sandbox/5.distributed/src/executor.ts))