pure-effect 0.20.0 → 0.20.1

package/README.md

@@ -6,20 +6,20 @@
 
 - Replay a production failure locally, with no database and no network
 - No mocks needed to test async pipelines
-- Inject context without touching function signatures
+- Read request values, such as the tenant, from any step with `Ask`, without passing them along
 - Built-in retry, plus parallel execution that cancels sibling branches on the first failure
-- OpenTelemetry-ready via lifecycle hooks
+- OpenTelemetry-ready via lifecycle hooks, with a reference integration to copy
 - Zero dependencies, about 11 KB minified and gzipped
-- Works in JavaScript, and in TypeScript 5.1 or later (full generics, bundled `.d.ts`)
+- Works in JavaScript on Node 22 or later, and in TypeScript 5.1 or later (full generics, bundled `.d.ts`)
 
 ## Table of Contents
 
-- **Getting started:** [Installation](#installation) · [Quick Start](#quick-start) · [How It Works](#how-it-works) · [Testing Without Mocks](#testing-without-mocks) · [Coming from async/await](#coming-from-asyncawait) · [Writing Flows as Generators](#writing-flows-as-generators)
-- **Recording and replay:** [Time-Travel Debugging](#time-travel-debugging) · [Recording in Production](#recording-in-production) · [Hooks](#hooks)
-- **Building flows:** [Passing Runtime Context](#passing-runtime-context) · [Retrying Transient Failures](#retrying-transient-failures) · [Running Effects in Parallel](#running-effects-in-parallel) · [Composing Larger Flows](#composing-larger-flows) · [Writing Loops](#writing-loops) · [Which Errors Are Data](#which-errors-are-data) · [Generator Flows in Depth](#generator-flows-in-depth) · [TypeScript](#typescript-typed-errors-and-context)
+- **Getting started:** [Installation](#installation) · [The Core](#the-core) · [Quick Start](#quick-start) · [Coming from async/await](#coming-from-asyncawait) · [Writing Flows as Generators](#writing-flows-as-generators) · [Testing Without Mocks](#testing-without-mocks) · [Rules for Writing a Flow](#rules-for-writing-a-flow)
+- **Building flows:** [Passing Runtime Context](#passing-runtime-context) · [Retrying Transient Failures](#retrying-transient-failures) · [Running Effects in Parallel](#running-effects-in-parallel) · [Composing Larger Flows](#composing-larger-flows) · [Writing Loops](#writing-loops) · [Which Errors Are Data](#which-errors-are-data) · [Generator Flows in Depth](#generator-flows-in-depth) · [Parallel in Depth](#parallel-in-depth) · [TypeScript](#typescript-typed-errors-and-context)
+- **Recording and replay:** [Time-Travel Debugging](#time-travel-debugging) · [Recording in Production](#recording-in-production) · [Hooks](#hooks) · [Replay in Depth](#replay-in-depth)
 - **Reference:** [Why Pure Effect](#why-pure-effect) · [API Reference](#api-reference) · [Limitations](#limitations)
 
-The six sections under Getting started are enough to write and test a flow. Come back to the rest when a flow needs it: recording, retries, loops, steps that run at the same time, or TypeScript.
+The seven sections under Getting started are enough to write and test a flow. Come back to the rest when a flow needs it: retries, loops, steps that run at the same time, TypeScript, or recording.
 
 ## Installation
 
@@ -27,22 +27,30 @@ The six sections under Getting started are enough to write and test a flow. Come
 npm install pure-effect
 ```
 
+## The Core
+
+Every flow is built from these:
+
+| Piece | What it is |
+| --- | --- |
+| `Success(value)` | A step that succeeded, carrying its value on to the next step. |
+| `Failure(error)` | A step that stops the flow, carrying its error to the caller. |
+| `Command(cmd, next)` | A call to make, and a function that turns its answer into the next step. |
+| `effectPipe(...)`, `effectGen(...)` | Join steps into a flow: as a pipeline, or written like `async` code with `yield* step(...)`. |
+| `runEffect(flow)` | Runs the flow, the only place the calls are made, and returns a `Success` or a `Failure`. |
+
+Everything else adds to these. `Ask` reads request values, `Retry` and `Parallel` wrap steps, and recording and replay watch `runEffect` make its calls.
+
 ## Quick Start
 
-A user registration flow. Each step receives the value the previous step produced. An I/O step is a pair: the call to make, and a `next` function that receives the answer and decides what happens next.
+Five steps take you from a plain `async` function to a tested flow. The example registers a user.
 
-```js
-import { Success, Failure, Command, effectPipe, runEffect } from 'pure-effect';
+**1. Describe each call as a Command.** A Command holds a call to make, and a `next` function that turns its answer into the next step. Building one makes no call.
 
-// Pure. No I/O, instantly testable.
-const validateRegistration = (input) => {
-    if (!input.email.includes('@')) return Failure('Invalid email.');
-    if (input.password.length < 8) return Failure('Password too short.');
-    return Success(input);
-};
+```js
+import { Success, Failure, Command, Retry, effectPipe, effectGen, step, runEffect } from 'pure-effect';
 
-// The next two functions return a Command object. They do not call the database.
-// Name the commands: traces, replay matching, and telemetry spans use the names.
+// Name each Command's function: traces, replay and telemetry refer to the Command by it.
 const ensureEmailAvailable = (input) => {
     const cmdFindUser = () => db.findUser(input.email);
     const next = (found) => (found ? Failure('Email already in use.') : Success(input));
@@ -54,27 +62,27 @@ const saveUser = (input) => {
     const cmdSaveUser = () => db.saveUser(input);
     return Command(cmdSaveUser);
 };
+```
 
-// Build the flow. Validation runs now; no I/O happens until runEffect.
-const registerUserFlow = (input) => effectPipe(validateRegistration, ensureEmailAvailable, saveUser)(input);
+Keep a Command's function to the one call. Tests never run it, so nothing else in it gets tested.
 
-// This is the only place side effects actually run
-async function registerUser(input) {
-    const result = await runEffect(registerUserFlow(input));
+**2. Join the steps into a flow.** A step with no I/O returns `Success` or `Failure` itself. `effectPipe` hands each step the value the step before it produced.
 
-    if (result.type === 'Success') {
-        console.log('User created:', result.value);
-    } else {
-        console.error('Error:', result.error);
-    }
-}
+```js
+// Pure. No I/O, instantly testable.
+const validateRegistration = (input) => {
+    if (!input.email.includes('@')) return Failure('Invalid email.');
+    if (input.password.length < 8) return Failure('Password too short.');
+    return Success(input);
+};
+
+// Validation runs as the flow is built. No I/O happens until runEffect.
+const registerUserFlow = (input) => effectPipe(validateRegistration, ensureEmailAvailable, saveUser)(input);
 ```
 
 The same flow can be written as a generator, with `yield* step(...)` where `async` code writes `await`. [Writing Flows as Generators](#writing-flows-as-generators) covers what to know.
 
 ```js
-import { effectGen, step } from 'pure-effect';
-
 const registerUserFlowGen = effectGen(function* (input) {
     yield* step(validateRegistration(input));
     yield* step(ensureEmailAvailable(input));
@@ -82,103 +90,72 @@ const registerUserFlowGen = effectGen(function* (input) {
 });
 ```
 
-## How It Works
-
-A flow is a chain of pairs: an I/O call, and a `next` function that receives its answer and returns the next Command, a Success, or a Failure. `runEffect` walks the chain in a loop. A generator flow builds the same Commands: `effectGen` runs your function up to each `yield*` and continues it with the answer.
-
-Recording and replay hook into the one place where a Command's function is called. Recording writes down each answer. Replay supplies the recorded answer instead of making the call, so a replayed flow does no I/O.
-
-Building a flow runs the pure steps right away: `registerUserFlow(badInput)` returns the validation `Failure` synchronously, so the tests below do not need `runEffect`. Only Commands need it.
+**3. Return a `Failure`, and throw only when trying again could help.** The two ways to fail do different things:
 
-## Testing Without Mocks
-
-A flow is plain objects, so a test can check what it will do without running it. Validation runs as soon as the flow is built, so testing it needs nothing else:
+- An outcome the flow decides, such as an invalid email or one already in use, is a `Failure` a step returns. The flow stops there, and nothing retries it.
+- A call that broke, such as a timeout or a dropped connection, is an error the Command's function throws. `Retry` makes the call again:
 
 ```js
-const badInput = { email: 'bad-email', password: '123' };
-assert.deepEqual(registerUserFlow(badInput), Failure('Invalid email.'));
+// Up to three calls. Wrap only the Command: Retry runs everything it wraps again.
+const saveUserWithRetry = (input) => Retry(saveUser(input), { retries: 2 });
 ```
 
-Next, test the steps. Hand a step an answer and check what it returns:
-
-```js
-const input = { email: 'test@test.com', password: 'password123' };
-
-// The email is free, so the step passes the input on.
-assert.deepEqual(ensureEmailAvailable(input).next(null), Success(input));
+Either way, the caller gets a `Failure` once the flow gives up. A call that throws outside a `Retry` ends the run in a `Failure` holding the error it threw.
 
-// The email is taken, so the flow stops here.
-assert.deepEqual(ensureEmailAvailable(input).next({ id: 1 }), Failure('Email already in use.'));
-```
+After a `Retry` gives up, the `Failure` holds `{ retryExhausted, lastError, retries }`, with the last error thrown as `lastError`. When a call throws an error the flow should decide on, such as a declined card, catch it inside the Command's function and return it; [Which Errors Are Data](#which-errors-are-data) shows how.
 
-Then test the flow: the right calls, in the right order. `commandName` gives the name a Command is recorded under:
+**4. Test it without mocks.** A flow is plain objects. Hand a step the answer you choose and check what it returns:
 
 ```js
-import { commandName } from 'pure-effect';
-
-const step1 = registerUserFlow(input);
-assert.equal(commandName(step1), 'cmdFindUser');
-
-const step2 = step1.next(null); // pretend no user was found
-assert.equal(commandName(step2), 'cmdSaveUser');
-// The database was never touched.
+// The email is taken, so the flow stops here. No database was touched.
+const taken = ensureEmailAvailable({ email: 'taken@test.com', password: 'password123' }).next({ id: 1 });
+assert.deepEqual(taken, Failure('Email already in use.'));
 ```
 
-Write both kinds: only a step test sees the value passed from one step to the next. Suppose the email guard returned `Success(true)` instead of `Success(input)`. The step test would fail. The flow test would still pass, since the calls and their order are unchanged, while the flow saved `true` instead of the user.
-
-A walk meets a `Retry` or a `Parallel` as a step of its own. A `Retry` holds the step it repeats as `effect`, a `Parallel` holds its branches as `effects`, and the `next` of either is the rest of the flow. The walks in [Writing Loops](#writing-loops) and [Undoing what succeeded when a branch fails](#undoing-what-succeeded-when-a-branch-fails) go through each.
-
-To run the whole flow instead of walking it, `Retry` and `Parallel` included, hand `replayEffect` a function that answers each Command by name. Nothing is called and no retry waits; answering `{ error }` makes that Command throw, which is how a test reaches a `Retry`'s fallback:
-
-```js
-import { replayEffect } from 'pure-effect';
-
-const answers = { cmdFindUser: null, cmdSaveUser: { id: 1, ...input } };
-const answer = (step) => (step.name in answers ? { result: answers[step.name] } : undefined);
-const { result } = await replayEffect(registerUserFlow(input), answer);
-assert.deepEqual(result, Success({ id: 1, ...input }));
-```
+[Testing Without Mocks](#testing-without-mocks) shows each kind of test, and how to run a whole flow with no I/O.
 
-Hand it a recorded run instead, and each Command gets what it returned the first time. That is how a run recorded in production replays on your machine, with nothing connected:
+**5. Run it.** `runEffect` makes the calls and returns a `Success` or a `Failure`. It is the only place a call is made, so it sits at the edge of your app:
 
 ```js
-import { recordEffect } from 'pure-effect';
-
-// A real run returns its result, and a trace of what each Command returned.
-const { result: live, trace } = await recordEffect(registerUserFlow(input));
+async function registerUser(input) {
+    const result = await runEffect(registerUserFlow(input));
 
-// Anywhere else, with nothing connected, the same flow gets the same answers.
-const { result: replayed } = await replayEffect(registerUserFlow(trace.initialInput), trace);
-assert.deepEqual(replayed, live);
+    if (result.type === 'Success') {
+        console.log('User created:', result.value);
+    } else {
+        console.error('Error:', result.error);
+    }
+}
 ```
 
-[Time-Travel Debugging](#time-travel-debugging) turns such a trace into a regression test, and [Recording in Production](#recording-in-production) records every run of an application.
-
-Tests cannot see inside a Command's function without running it. If `cmdFindUser` said `db.findUser(input.name)` instead of `input.email`, every test on this page would still pass. Keep those functions to a single call, and let an integration test cover them, with the services passed in as [Passing Runtime Context](#passing-runtime-context) shows.
-
-In TypeScript, a walk needs a check at each step that the step is a Command; [Testing a flow in TypeScript](#testing-a-flow-in-typescript) has a helper that makes that one line.
+That is a whole flow. [Rules for Writing a Flow](#rules-for-writing-a-flow) lists the twelve rules that cover most of what goes wrong, and [Time-Travel Debugging](#time-travel-debugging) shows how to record a run in production and replay it on your machine. In TypeScript, [TypeScript: Typed Errors and Context](#typescript-typed-errors-and-context) covers typing a flow's errors and context, handling every error, and testing a flow.
 
 ## Coming from async/await
 
-A flow does what `async`/`await` code does, as data. Instead of making a call and waiting for it, a step returns a Command: which call to make, and what to do with the answer. Each thing you would write with `async`/`await` has an equivalent:
+A flow does what `async`/`await` code does, as data. Instead of making a call and waiting for it, a step returns a Command: which call to make, and what to do with the answer. Each thing you would write with `async`/`await` has an equivalent.
+
+Where the two styles differ:
 
 | `async`/`await` | Generator flow | Pipeline |
 | --- | --- | --- |
-| `await db.findUser(email)` | `yield* step(findUser(email))` | `Command(() => db.findUser(email), next)` |
+| `await db.findUser(email)` | `yield* step(findUser(email))` | `Command(cmdFindUser, next)` |
 | the code after the `await` | the next `yield*` | the Command's `next` |
 | an `if` on a result | a step that returns `Success` or `Failure` | a branch in `next` |
 | `return value` | `return value` | `Success(value)` |
 | `throw` to stop | a step that returns `Failure(error)` | `Failure(error)` |
-| `try`/`catch` around a call | a catch inside the Command's function | the same |
-| a loop that retries a call | `yield* step(Retry(...))` | `Retry(...)` |
-| `await Promise.all([...])` | `yield* step(Parallel([...]))` | `Parallel([...])` |
 | a `for` loop with an `await` inside | the same loop, with `yield*` | `Parallel(list.map(...), { limit: 1 })` |
-| a loop that keeps going past a failure | `Parallel(..., { settled: true })` | the same |
 | a call that needs two earlier results | two variables | a named step that passes both on |
-| a value from the request | `yield* step(Ask())` | `Ask` |
-| `Date.now()` or a random ID | a Command | a Command |
 
-`findUser` stands for a step that returns the Command, as `ensureEmailAvailable` does in the Quick Start. A `catch` around `yield*` can log and rethrow, but it cannot recover; see [Which Errors Are Data](#which-errors-are-data).
+The rest are the same in both styles, and a generator flow runs each one with `yield* step(...)`:
+
+- `try`/`catch` around a call: a catch inside the Command's function
+- a loop that retries a call: `Retry`
+- `await Promise.all([...])`: `Parallel`
+- a loop that keeps going past a failure: `Parallel` with `settled: true`
+- a value from the request: `Ask`
+- `Date.now()` or a random ID: a Command
+
+`cmdFindUser` is the named function `() => db.findUser(email)`, and `findUser` stands for a step that returns the Command, as `ensureEmailAvailable` does in the Quick Start. A `catch` around `yield*` can log and rethrow, but it cannot recover; see [Which Errors Are Data](#which-errors-are-data).
 
 One rule is behind both columns: each decision lives in a small step function that receives the answer it depends on and returns `Success` or `Failure`, so a test can call it directly. A pipeline joins those steps with `effectPipe`; a generator flow puts them in order with `yield*`. An `if` around a `yield*` works, but it can be tested only by walking the whole flow, so keep the body to putting steps in order. A `for` loop that runs a step for each item decides nothing, so it is fine.
 
@@ -193,30 +170,9 @@ async function registerUserAsync(input) {
 }
 ```
 
-The difference shows in the tests. To reach the branch where the email is taken, a test of `registerUserAsync` has to replace the database's methods, run the function, and put them back, here with Node's built-in mocks:
-
-```js
-import { mock } from 'node:test';
-
-const input = { email: 'test@test.com', password: 'password123' };
-
-mock.method(db, 'findUser', async () => ({ id: 1 }));
-const saveUser = mock.method(db, 'saveUser', async (user) => user);
-
-await assert.rejects(registerUserAsync(input), { message: 'Email already in use.' });
-assert.equal(saveUser.mock.callCount(), 0);
-mock.restoreAll();
-```
-
-The flow's test of the same branch hands one step the answer, with nothing to replace, wait for, or put back:
-
-```js
-assert.deepEqual(ensureEmailAvailable(input).next({ id: 1 }), Failure('Email already in use.'));
-```
-
-Each step is a place a test can start, so a test reaches a branch by calling the step it lives in. A test of an `async` function has to run everything before the branch, with every call on the way replaced. The mocks do check one thing these tests cannot: the arguments each call received, which [Testing Without Mocks](#testing-without-mocks) leaves to an integration test.
+The difference shows in the tests. To reach the branch where the email is taken, a test of `registerUserAsync` has to replace `db.findUser` and `db.saveUser` with mocks, run the function, and put them back. The flow's test hands the one step the answer, `ensureEmailAvailable(input).next({ id: 1 })`, with nothing to replace or put back. The mocks do check one thing that test cannot: the arguments each call received, which [Testing Without Mocks](#testing-without-mocks) leaves to an integration test.
 
-You can switch one function at a time. Keep its name and parameters, run the flow in its body, and turn a `Failure` back into a throw, so the code that calls it does not change. The mocked test above passes against this version too:
+You can switch one function at a time. Keep its name and parameters, run the flow in its body, and turn a `Failure` back into a throw, so the code that calls it does not change:
 
 ```js
 // Callers still await registerUserAsync and catch what it throws.
@@ -230,11 +186,13 @@ async function registerUserAsync(input) {
 await assert.rejects(registerUserAsync({ email: 'bad-email', password: '123' }), { message: 'Invalid email.' });
 ```
 
+If the flow has a `Retry`, a `Failure` from one that gave up holds `{ retryExhausted, lastError, retries }`; throw its `lastError` to rethrow what the call threw, as the old function did.
+
 A loop becomes a step that gets the list and a `Parallel` over it, as the table shows; [Writing Loops](#writing-loops) translates one.
 
 ## Writing Flows as Generators
 
-A generator flow is written like `async` code, with `yield* step(...)` where `async` code writes `await`. `effectGen` turns it into the same Commands a pipeline builds, so recording, replay, `Retry`, `Parallel` and the tests above work the same for both. The Quick Start's `registerUserFlowGen` is one. The same steps in the same order record the same paths in either form, so a trace recorded from a pipeline replays against its generator version. A loop written as a `for` loop rather than a `Parallel` records differently; see [Writing Loops](#writing-loops).
+A generator flow is written like `async` code, with `yield* step(...)` where `async` code writes `await`. `effectGen` turns it into the same Commands a pipeline builds, so recording, replay, `Retry`, `Parallel` and the tests in [Testing Without Mocks](#testing-without-mocks) work the same for both. The Quick Start's `registerUserFlowGen` is one. The same steps in the same order record the same paths in either form, so a trace recorded from a pipeline replays against its generator version. A loop written as a `for` loop rather than a `Parallel` records differently; see [Writing Loops](#writing-loops).
 
 ### Where a generator helps
 
@@ -261,315 +219,103 @@ A pipeline would need a step that passes the user and the workspace on together;
 
 The body can run more than once: for each `Retry` attempt and each run, as an `async` function does when called again, and when a test walks a second branch. So keep it to its own variables, and get `Date.now()` or a random ID from a Command, so a replay gets the recorded one. [Generator Flows in Depth](#generator-flows-in-depth) covers when it runs again, how a `catch` or `finally` in it behaves when a step stops the flow, and the mistakes `effectGen` catches.
 
-### Testing a generator flow
+## Testing Without Mocks
 
-Test each step function by handing it an answer, as [Testing Without Mocks](#testing-without-mocks) does, since the generator only puts the steps in order. Then run the whole flow with each Command answered by name, as for a pipeline:
+A flow is plain objects, so a test can check what it will do without running it. Validation runs as soon as the flow is built, so testing it needs nothing else:
 
 ```js
-const answers = { cmdFindUser: null, cmdSaveUser: { id: 1, ...input } };
-const answerByName = (asked) => (asked.name in answers ? { result: answers[asked.name] } : undefined);
-const { result } = await replayEffect(registerUserFlowGen(input), answerByName);
-assert.deepEqual(result, Success({ id: 1, ...input }));
+const badInput = { email: 'bad-email', password: '123' };
+assert.deepEqual(registerUserFlow(badInput), Failure('Invalid email.'));
 ```
 
-Walking the flow step by step works as it does for a pipeline: a walk straight through runs the body once, and walking a second branch runs it again.
-
-## Time-Travel Debugging
-
-Record what each Command returned, then feed those results back into the flow to retrace the path a request took, with no database or network.
+Next, test the steps. Hand a step an answer and check what it returns:
 
 ```js
-import { recordEffect, replayEffect, timeTravel } from 'pure-effect';
-
-// Record a real run. The context's flowName names the flow in the trace.
-const { result, trace } = await recordEffect(checkoutFlow(input), {
-    version: process.env.BUILD_ID,
-    context: { flowName: 'checkout' }
-});
+const input = { email: 'test@test.com', password: 'password123' };
 
-// Later, somewhere else, with nothing connected:
-await timeTravel(checkoutFlow, trace);
-```
+// The email is free, so the step passes the input on.
+assert.deepEqual(ensureEmailAvailable(input).next(null), Success(input));
 
-```
-Replaying 'checkout' (3 recorded steps)
-Initial input: {
-  "cartId": "cart_abc123",
-  "promoCode": "FREE_YEAR_VIP"
-}
-Step 1: cmdFetchCart returned in 41.277ms {
-  "totalAmount": "120.00"
-}
-Step 2: cmdValidatePromo returned in 26.814ms {
-  "isValid": true,
-  "discountValue": 100
-}
-Step 3: cmdChargeCard threw in 181.507ms {
-  "code": "invalid_amount",
-  "name": "Error",
-  "message": "Amount must be non-zero."
-}
-Replay finished with state: Failure
-Error: {
-  "code": "invalid_amount",
-  "name": "Error",
-  "message": "Amount must be non-zero."
-}
+// The email is taken, so the flow stops here.
+assert.deepEqual(ensureEmailAvailable(input).next({ id: 1 }), Failure('Email already in use.'));
 ```
 
-A production incident becomes a regression test, with no mocks or fixtures:
+Then test the flow: the right calls, in the right order. Handing each Command's `next` the answer you choose, and checking the step it returns, is called walking the flow; nothing runs. `commandName` gives the name a Command is recorded under:
 
 ```js
-it('prod incident 8f3a: a 100% promo produces a $0 charge', async () => {
-    const { result } = await replayEffect(checkoutFlow(trace.initialInput), trace);
-    assert.equal(result.type, 'Failure');
-    assert.equal(result.error.code, 'invalid_amount');
-});
-```
-
-The test checks that the flow still takes the recorded path and handles the recorded outcomes the same way. It does not check the values the flow computes, since every result comes from the recording; see [What a replay cannot check](#what-a-replay-cannot-check). If a refactor reorders or replaces a step, the replay ends in a `Failure` whose error is a `TimeParadox` naming where it diverged. It is not thrown, so a test that expects a `Failure` should check the error too, as this one checks its `code`.
-
-A step the trace lacks ends the replay in a `Failure` holding a `ReplayError`. A trace lacks a step that comes after the end of the recording, one a hook vetoed in production, and one the recorder dropped under `maxEntries`.
+import { commandName } from 'pure-effect';
 
-A flow that stops issuing Commands before the recording ends (for example, a fix that skips the charge) produces no `TimeParadox`, and the replay can end in `Success` with recorded steps left over. `replayEffect` returns those steps as `unreached`, so a test can assert which ones it expects to skip:
+const step1 = registerUserFlow(input);
+assert.equal(commandName(step1), 'cmdFindUser');
 
-```js
-it('incident 8f3a fixed: a 100% promo checks out without a charge', async () => {
-    const { result, unreached } = await replayEffect(checkoutFlow(trace.initialInput), trace);
-    assert.equal(result.type, 'Success');
-    assert.deepEqual(
-        unreached.map((e) => e.command),
-        ['cmdChargeCard']
-    );
-});
+const step2 = step1.next(null); // pretend no user was found
+assert.equal(commandName(step2), 'cmdSaveUser');
+// The database was never touched.
 ```
 
-For every other recording, `unreached` should be empty, so a fix that skips a step by accident fails the test. This works when the removed step is the last one the flow reaches. Remove a step from the middle and every later step moves to a different path, so the replay stops at a `TimeParadox`, and `unreached` lists the steps it never got to.
-
-### Reading a trace
-
-A trace is plain JSON. This one is from a checkout whose card charge timed out once and then went through:
+Write both kinds: only a step test sees the value passed from one step to the next. Suppose the email guard returned `Success(true)` instead of `Success(input)`. The step test would fail. The flow test would still pass, since the calls and their order are unchanged, while the flow saved `true` instead of the user.
 
-```text
-{
-  "flowName": "checkout",
-  "version": "b42",
-  "initialInput": { "cartId": "cart_1" },
-  "context": { "flowName": "checkout" },
-  "dropped": 0,
-  "trace": [
-    { "command": "cmdFetchCart", "path": "0", "result": { "total": 120 }, "durationMs": 41.3 },
-    { "command": "cmdChargeCard", "path": "1r0/0", "threw": true,
-      "error": { "__error": true, "name": "Error", "message": "gateway timeout", "code": "ETIMEDOUT" }, "durationMs": 5002.1 },
-    { "command": "cmdChargeCard", "path": "1r1/0", "result": { "chargeId": "ch_1" }, "durationMs": 181.5 }
-  ]
-}
-```
+A walk meets a `Retry` or a `Parallel` as a step of its own. A `Retry` holds the step it repeats as `effect`, a `Parallel` holds its branches as `effects`, and the `next` of either is the rest of the flow. The walks in [Writing Loops](#writing-loops) and [Undoing what succeeded when a branch fails](#undoing-what-succeeded-when-a-branch-fails) go through each.
 
-`trace` holds one entry per step, in the order the steps finished; [`recorder`](#recorderoptions) lists each kind of entry. A replay matches each step by its `path`, its position in the flow, and a `TimeParadox` names the path where the flow and the trace part ways:
+A generator flow is tested the same way. Its decisions are in step functions, which get the step tests, and a walk or a whole-flow run works on `registerUserFlowGen` as it does on `registerUserFlow`. A walk straight through runs the body once, and walking a second branch runs it again.
 
-- A number counts the Commands, `Retry`s and `Parallel`s the flow reached, from `0`. A `Success` or an `Ask` between them adds nothing.
-- `r` and a number is one attempt of the `Retry` at that position, `r0` being the first try, and `rf` is its `onExhausted` fallback.
-- `p` and a number is one branch of the `Parallel` at that position, from `p0`. The `Parallel` has an entry of its own, at a path such as `2p`, which records whether a branch cancelled the others.
-- `/` goes one level in. `1r1/0` is the first step of the second try of the `Retry` at position 1. `2p1/0` is the first step of the second branch of the `Parallel` at position 2.
+[Testing a whole flow](#testing-a-whole-flow) shows how to run a whole flow in a test instead, `Retry` and `Parallel` included, with no I/O.
 
-### What a replay cannot check
+Tests cannot see inside a Command's function without running it. If `cmdFindUser` said `db.findUser(input.name)` instead of `input.email`, every test on this page would still pass. Keep those functions to a single call, and let an integration test cover them, with the services passed in as [Passing Runtime Context](#passing-runtime-context) shows.
 
-A replay proves that the flow asks for the same Commands in the same order and handles the same answers. Every result comes from the recording, so it cannot check:
+In TypeScript, a walk needs a check at each step that the step is a Command; [Testing a flow in TypeScript](#testing-a-flow-in-typescript) has a helper that makes that one line.
 
-- **What the flow computes.** Fix how a refund amount is calculated and replay the bad run: the charge step still gets the old amount from the recording. The replay reports `Success`, returns the value from before the fix, and flags nothing. Test a value change against the pure step that computes it.
-- **A fix inside a Command's function.** The function never runs, so an old trace hands the flow what it returned or threw before the fix. Catch a duplicate-key error inside the function and return it as data, and the old trace still replays the throw. Cover such a fix with an integration test.
-- **The arguments a Command was called with.** A trace records results only. Given the recorded input and results, the flow does the same thing again, so replaying up to a step rebuilds its arguments for a debugger, but a test cannot assert on them. Storing them would also double what `redact` has to cover, since arguments are usually the sensitive part of a call.
+### Testing a whole flow
 
-When a Command's result changes shape, rename the Command. A trace matches it by name. So under the old name, an old trace hands the new code a result in the old shape, which it can take for another answer without any `TimeParadox`.
+To run a whole flow in a test instead of walking it, `Retry` and `Parallel` included, hand `replayEffect` a function that answers each Command. Nothing is called and no retry waits. The function gets each step the flow asks for, with its `name`, and returns `{ result }` for the Command to return, `{ error }` for it to throw, or `undefined` for a step it has no answer for, which ends the replay in a `Failure` holding a `ReplayError`:
 
-### Keeping a replay faithful
+```js
+import { replayEffect } from 'pure-effect';
 
-Put anything that varies between runs inside a Command. For replay, the current time or a random ID counts as I/O. In a Command it is recorded and replayed like any other result. A step that calls `Date.now()` directly gets a new value on every replay, and drifts from the trace.
+const answers = { cmdFindUser: null, cmdSaveUser: { id: 1, ...input } };
+const answer = (step) => (step.name in answers ? { result: answers[step.name] } : undefined);
+const { result } = await replayEffect(registerUserFlow(input), answer);
+assert.deepEqual(result, Success({ id: 1, ...input }));
+```
 
-To check a flow, record it, replay the trace, and compare the outcomes. A step that computes a fresh value shows up as a different final value, or as a `TimeParadox` if it changes which Commands run. A trace holds each result in the form JSON stores it, so this also catches a result your storage cannot keep, such as a `Date` the flow calls a method on:
+Answering `{ error }` is how a test reaches a `Retry`'s next attempt or its `onExhausted` fallback. An answer takes the place of the Command's function, its `catch` included: for a function that catches an error and returns it, answer with what it returns, not `{ error }`. To answer each attempt differently, give a name a list of answers and hand them out in turn. Here the Quick Start's `saveUserWithRetry` fails once, then goes through:
 
 ```js
-const { result, trace } = await recordEffect(registerUserFlow(input));
-const { result: replayed } = await replayEffect(registerUserFlow(input), trace);
-assert.deepEqual(replayed, result); // fails if a step computed a fresh value, or a result did not survive storage
+const answers = { cmdSaveUser: [{ error: new Error('connection reset') }, { result: { id: 1, ...input } }] };
+const inTurn = (step) => answers[step.name]?.shift();
+const { result } = await replayEffect(saveUserWithRetry(input), inTurn);
+assert.deepEqual(result, Success({ id: 1, ...input }));
 ```
 
-A `Failure` compares the same way when the Command threw a plain `Error`. It comes back with its message, name, cause, custom properties and an `AggregateError`'s list of errors, even a `name` or `cause` set after it was created. An error of any other class, built-in ones included, comes back as a plain `Error` carrying that class's name. So `deepEqual` from `node:assert/strict` refuses the replayed `TypeError` that `fetch` rejects with when the network fails. Where a Command can throw one, compare `error.name` and `error.message` instead.
+The function is also asked about each `Parallel`, under the name `'Parallel'`; answering `undefined` lets its branches run as written. A step also carries its `path`, its position in the flow, which [Reading a trace](#reading-a-trace) explains; answer by path to tell apart two Commands with the same name.
 
-### Replaying from your own storage
+## Rules for Writing a Flow
 
-`replayEffect` also accepts a resolver function instead of a trace, so you can replay from OpenTelemetry spans, a log pipeline, or a database table, not only from the JSON that `recorder` produces. Whatever you store needs each step's `path`, which `onStep` receives, and its result; the telemetry example records neither, since it keeps values off spans.
+Twelve rules cover most of what goes wrong. The same rules ship in the package as `RULES.md`, with an index of where each task is covered.
 
-```js
-// A resolver answers one question: what did production get back for this step? Look the step up by its path, its
-// position in the flow. `step.index` counts steps in the order they finished, which shifts around a Parallel.
-const outputs = new Map(mySpans.map((span) => [span.attributes.path, span.attributes.output]));
-const resolve = (step) => (outputs.has(step.path) ? { result: outputs.get(step.path) } : undefined);
-await replayEffect(checkoutFlow(input), resolve);
-```
+<!-- rules:start -->
 
-## Recording in Production
+1. **Put every call that does I/O inside a Command, and keep its function to that one call:** `Command(() => db.findUser(email))`, never `step(db.findUser(email))`. Tests never run the function, so anything else in it goes untested. See [Testing Without Mocks](#testing-without-mocks).
+2. **Name every Command,** with a named function such as `const cmdFindUser = () => ...`, or with `meta.name`. Traces, replay and telemetry use the name, and a minifier can strip a function's name. See [`Command`](#commandcmdfn-nextfn-meta).
+3. **Put each decision in a step function** that receives one value and returns `Success`, `Failure` or the next Command, so a test can call it directly. See [Coming from async/await](#coming-from-asyncawait).
+4. **Return an outcome the caller should see as `Failure(error)`; never throw it.** A `Failure` stops the flow, is never retried, and only the code that calls `runEffect` acts on it. See [Which Errors Are Data](#which-errors-are-data).
+5. **A `catch` in a generator flow cannot recover.** It can log and rethrow, and it sees a `FlowStopped` error saying where the flow stopped, not the original. To handle an error, catch it inside the Command's function and return it as data. See [How a generator flow stops](#how-a-generator-flow-stops).
+6. **Let a Command's function throw only when `Retry` should try again.** An error it catches and returns is data, and `Retry` never sees it. To retry some errors and not others, rethrow the first kind and return the second. A throw also skips any undo the Command's `next` would have run. See [Which Errors Are Data](#which-errors-are-data).
+7. **Wrap only the Command that fails in `Retry`, and continue in a later step.** `Retry` runs everything it wraps again, the Command's `next` included. `retries: 2` means up to three calls, and `onExhausted` is where you give up. See [Retrying Transient Failures](#retrying-transient-failures).
+8. **Write a loop as a step that gets the list, then `Parallel(list.map(f), { limit: 1 })`.** `limit` caps how many run at once, and `settled: true` keeps going past a failure. A generator flow can use a `for` loop with `yield*`. See [Writing Loops](#writing-loops).
+9. **Get the time, random IDs and anything else that changes between runs from a Command.** A replay then gets the recorded value, and a generator body, which can run more than once, sees the same value each time. See [What runs once, and what runs again](#what-runs-once-and-what-runs-again).
+10. **Return plain data from Commands, and keep the context to plain values.** A trace stores JSON, so a `Date` comes back as a string. Reach a service from the Command's function, and hand it to the function that builds the flow. See [Passing Runtime Context](#passing-runtime-context).
+11. **Clean up in a `try`/`finally` around `runEffect`,** not inside the flow. See [How a generator flow stops](#how-a-generator-flow-stops).
+12. **Check a replay's error, not only its type.** A replay of a flow that changed shape ends in a `Failure` holding a `TimeParadox`, the error naming where the flow and the trace part ways, so a test that only expects a `Failure` passes by accident. See [Time-Travel Debugging](#time-travel-debugging).
 
-`recordEffect` suits tests and scripts, where one call covers the whole run. To record an application without changing any call site, install the hooks once at startup. The two files imported below ship in the package's `examples` folder, `node_modules/pure-effect/examples`, and in the repository's [examples folder](https://github.com/aycangulez/pure-effect/blob/main/examples); copy them into your project.
+<!-- rules:end -->
+
+## Passing Runtime Context
+
+Some values come from the framework (an authenticated tenant, a request ID, environment config) rather than from the data being processed. `Ask` lets a step read the `context` object passed to `runEffect` without passing it through every function:
 
 ```js
-import { randomUUID } from 'node:crypto';
-import { configureEffect } from 'pure-effect';
-import { recordingHooks } from './recording-example.js';
-import { telemetryHooks } from './opentelemetry-example.js';
-
-configureEffect(
-    telemetryHooks(),
-    recordingHooks({
-        sink: (trace) => putObject(`traces/${trace.flowName}/${randomUUID()}.json`, JSON.stringify(trace)),
-        // A replay runs validation again on the stored input, so the stand-in keeps the password rule's verdict.
-        redact: (value, name, kind) =>
-            kind === 'initialInput' ? { ...value, password: value.password.length >= 8 ? '[redacted]' : '' } : value,
-        maxEntries: 500,
-        keep: (result) => result.type === 'Failure' // the default; keep everything, or sample
-    })
-);
-```
-
-What the example does with each run:
-
-- **Which runs it keeps.** `keep` decides. By default it keeps a run that ended in a `Failure`, and discards a successful one after holding it in memory.
-- **When your own code throws.** A `TypeError` after an API changed the shape of its response, say, makes the run reject. `keep` is offered a `Failure` carrying the thrown error, so by default its trace is kept, and replaying it reproduces the throw. A step before the flow's first Command runs when the flow is built, outside `runEffect`, so its throw reaches no hook and is not recorded. That run did no I/O, so its input reproduces it.
-- **What a trace holds.** `redact` runs before anything enters the trace, including the stored `initialInput` and `context`. A value it throws on, or one JSON cannot hold, such as a `BigInt`, is left out and marked `unrecorded`, and a replay stops there. Everything else is already in the form JSON holds, so the sink can write it to S3 or a database column with `JSON.stringify`.
-- **How long a trace gets.** `maxEntries` caps it and reports the overflow as `dropped`, and a capped trace replays only up to the first step it lacks.
-- **When storage fails.** If `keep` or the sink throws, for example because storage is unreachable, the run keeps its own outcome and the error goes to `onSinkError`, which defaults to `console.error`.
-- **What it warns about.** The example warns through `onWarning`, once per flow, when it keeps a trace that was capped, one holding values it could not record, or one whose steps include any named `'anonymous'`.
-
-The example takes the input from `onRun`, which is handed it only for a flow `effectPipe` or `effectGen` built, so build the outermost flow with one of them. A flow that starts with a bare `Command`, `Ask`, `Retry`, or `Parallel` records no input, and `timeTravel` would rebuild it from `undefined`. A one-step pipeline is enough, as in `runEffect(effectPipe(loadProfile)(userId))`. The example warns through `onWarning`, which defaults to `console.warn`, the first time it keeps a trace of such a flow, and `timeTravel` warns when it replays one.
-
-The example also takes the context from the run's first Command, so a run that stops before any Command, for example at an `Ask` check, records no context. Such a run did no I/O, so running the flow again with its input and the context from your logs reproduces it.
-
-**A trace keeps data, not objects.** A value is copied into the form JSON stores when it is recorded, and copied again each time a replay hands it to the flow. So neither a later step nor a replay can change what the trace says, and a replay from memory gets what a replay from storage gets. The copy keeps values but not classes:
-
-| Recorded                            | Replayed as                                         |
-| ----------------------------------- | --------------------------------------------------- |
-| a money object or a database entity | a plain object, without its methods                 |
-| a `Date`                            | a string                                            |
-| a `Map` or a `Set`                  | `{}`                                                |
-| a `Buffer`                          | `{ type: 'Buffer', data }`                          |
-| `undefined` in an array             | `null`                                              |
-| an error returned inside a result   | its own fields, such as `code`, without its message |
-
-A reference back to an object the value is inside of, as between an HTTP client's request and response, is cut. A value JSON cannot hold at all, such as a `BigInt` or an object whose getter throws, is left out of the trace and marked `unrecorded` before `redact` sees it. So a context holding a lazy client is left out whole.
-
-So return plain data from a Command's function. Turn a class instance into a plain object before returning it, with a small named function you can test on its own, as in `() => db.findCart(id).then(cartToData)`. Rebuild the object in `next` if the flow needs its methods. When you catch an error to return it as data, copy the fields the flow branches on, as in `.catch((error) => ({ ok: false, code: error.code }))`, rather than returning the error itself.
-
-### Keeping secrets out of a trace
-
-`redact` sees everything a trace stores: each result, each thrown error, the flow's input and the context, told apart by `kind`. It gets a copy in the form the trace stores, so changing it in place is safe, and what it returns is stored in that form too. A thrown `Error` arrives as a plain object holding its `name`, `message` and own fields, and any object returned for it replays as an `Error`.
-
-Check a value before replacing a field in it, since `{ ...value, email: '[redacted]' }` turns a `null` into an object and the replay takes the other branch:
-
-```js
-// Masks a field only where there is one, so a lookup that found nothing still records null.
-const mask = (value, field) =>
-    value && typeof value === 'object' && field in value ? { ...value, [field]: '[redacted]' } : value;
-
-const redact = (value, name, kind) => {
-    if (kind === 'initialInput') return mask(value, 'cardNumber');
-    if (kind === 'context') return mask(value, 'authToken');
-    if (kind === 'error') return mask(value, 'attempted');
-    return name === 'cmdFetchUser' ? mask(value, 'email') : value;
-};
-recorder({ redact });
-
-assert.equal(redact(null, 'cmdFetchUser', 'result'), null); // still nothing found
-assert.equal(redact('card_declined', 'cmdCharge', 'error'), 'card_declined'); // still a string
-```
-
-A replay rebuilds the flow from the redacted input and context. So a field a step checks, such as a password, needs a stand-in the check treats the same way, as the example at the top of this section does. A context field an `Ask` reads should stay.
-
-## Hooks
-
-Hooks see every run, and recording, replay and the telemetry example are built on them. There are three: `onRun` wraps a whole run, `onStep` wraps each Command and each `Parallel`, and `onBeforeCommand` runs before each Command and can veto it by throwing. A hook that only watches must `await` what it wraps and return its result; [`configureEffect`](#configureeffectconfigs) lists each hook's arguments.
-
-`configureEffect` adds a layer of hooks for the whole process and returns a function that removes it. Removing a layer removes only that layer, even when others were installed after it, so a library can add and remove its own hooks without touching the application's:
-
-```js
-const remove = configureEffect(telemetryHooks(), recordingHooks({ sink }));
-// the same as configureEffect(telemetryHooks()) followed by configureEffect(recordingHooks({ sink }))
-remove();
-```
-
-Layers run in the order they were installed, the first outermost, so a result or a thrown error unwinds from the innermost hook out:
-
-```
-runEffect(flow(input))
-│
-├─ telemetry.onRun                       first configuration: outermost
-│  └─ recording.onRun                    last configuration: innermost
-│     │
-│     │  for each Command:
-│     ├─ telemetry.onBeforeCommand       interceptors all run, in the order given
-│     ├─ recording.onBeforeCommand
-│     ├─ telemetry.onStep
-│     │  └─ recording.onStep             closest to the Command
-│     │     └─ cmd()
-│     │  ┌─ recording.onStep returns     a result, or a thrown error, unwinds
-│     ├─ telemetry.onStep returns        from the inside out
-│     │
-│  ┌─ recording.onRun returns
-├─ telemetry.onRun returns
-```
-
-**Knowing which request a step belongs to.** `onStep` and `onRun` get no context, so a hook that logs per request finds the request the way the rest of your logging does. An `AsyncLocalStorage` scope entered around `runEffect` reaches every hook the run calls, and the recording example uses one to give each run its own recorder:
-
-```js
-import { AsyncLocalStorage } from 'node:async_hooks';
-
-const requestScope = new AsyncLocalStorage();
-const stepLog = [];
-
-// Logs each step with its request and duration, and returns what the step returned.
-const removeStepLog = configureEffect({
-    onStep: async (name, type, op, path) => {
-        const started = performance.now();
-        try {
-            return await op();
-        } finally {
-            const { requestId } = requestScope.getStore() ?? {};
-            stepLog.push({ requestId, name, path, ms: performance.now() - started });
-        }
-    }
-});
-
-await requestScope.run({ requestId: 'req_1' }, () => runEffect(registerUserFlow(input)));
-assert.deepEqual(
-    stepLog.map((line) => [line.requestId, line.name]),
-    [
-        ['req_1', 'cmdFindUser'],
-        ['req_1', 'cmdSaveUser']
-    ]
-);
-removeStepLog();
-```
-
-A Command that `onBeforeCommand` vetoes never reaches `onStep`, so log a veto where you make it. In tests, call `configureEffect()` with no arguments in a `beforeEach`, so a test that fails before removing its hooks does not leave them installed for the next.
-
-**Per-call hooks.** `runEffect`'s third argument takes hooks for that call only. They are merged with the configured ones by the same rules: the configured wrappers run outside them, and the configured `onBeforeCommand` hooks run first. `inherit: false` leaves the configured hooks out. With configured hooks `C` and a call `K` that supplies only `onStep`:
-
-```
-                  inherit: true (default)        inherit: false
-
-onRun             C.onRun                        (none)
-onBeforeCommand   C.onBeforeCommand              (none)
-onStep            C.onStep( K.onStep( cmd ) )    K.onStep
-```
-
-`recordEffect` inherits, so recording inside an application that already traces still produces spans. `replayEffect` passes `inherit: false` unless `hooks: true`.
-
-## Passing Runtime Context
-
-Some values come from the framework (an authenticated tenant, a request ID, environment config) rather than from the data being processed. `Ask` lets a step read the `context` object passed to `runEffect` without passing it through every function:
-
-```js
-import { Success, Failure, Command, Ask, effectPipe, runEffect } from 'pure-effect';
+import { Success, Failure, Command, Ask, effectPipe, runEffect } from 'pure-effect';
 
 const findProduct = (productId) =>
     Ask((ctx) => {
@@ -615,20 +361,21 @@ const flakyNetwork = { retries: 3, delay: 200, backoff: 2 };
 Retry(fetchPrice(sku), flakyNetwork);
 ```
 
-The settings are a plain object, so a test can check them without running anything:
+The settings are a plain object, so a test can check them without running anything. The `Retry` wraps only the Command, and the decision about its answer comes in the next step, outside the `Retry`:
 
 ```js
-import { Success, Failure, Command, Retry, runEffect } from 'pure-effect';
+import { Success, Failure, Command, Retry, effectPipe } from 'pure-effect';
 
 const fetchWeather = (city) => {
     const cmdFetchWeather = () =>
         fetch(`https://example-weather-api.com/v1/current?city=${city}`).then((r) => r.json());
-    return Retry(
-        Command(cmdFetchWeather, (data) => (data.error ? Failure(data.error) : Success(data))),
-        { retries: 3, delay: 200, backoff: 2 } // 200ms, 400ms, 800ms
-    );
+    // Four calls in all, waiting 200ms, 400ms, then 800ms.
+    return Retry(Command(cmdFetchWeather), { retries: 3, delay: 200, backoff: 2 });
 };
 
+const requireWeather = (data) => (data.error ? Failure(data.error) : Success(data));
+const weatherFlow = (city) => effectPipe(fetchWeather, requireWeather)(city);
+
 const weatherFn = fetchWeather('Tokyo');
 assert.equal(weatherFn.type, 'Retry');
 assert.equal(weatherFn.options.retries, 3);
@@ -686,6 +433,10 @@ const fetchPrice = (sku) =>
 
 Every attempt and the fallback are recorded, so a replay repeats the same failures and the same fallback, without the delays. A fallback never starts in a `Parallel` branch that has already been cancelled. With `onExhausted` set, the fallback's error type takes the place of `RetryExhaustedError` in the TypeScript error union.
 
+### Waiting as long as the server asks
+
+`Retry` waits a fixed `delay`, so it cannot wait as long as a server names, as a rate limit's `Retry-After` does. Catch that answer inside the Command's function and return it as data, as [Which Errors Are Data](#which-errors-are-data) shows, then have `next` return a Command that waits that long, followed by the same request again. A replay answers the wait from the trace like any other Command, so it does not wait.
+
 ## Running Effects in Parallel
 
 `Parallel` runs several flows at the same time and passes their results to `next` as an array, in order. If a branch fails, the other branches are cancelled, `next` is not called, and that branch's `Failure` is returned.
@@ -829,35 +580,7 @@ assert.deepEqual(
 
 A settled `Parallel` cancels nothing, so both steps always run to the end, and the undoing starts once both have finished. The undo steps are part of the flow, so a trace records them and a replay repeats them. An undo step that fails ends the flow with its own error rather than the original one; wrap it in `Retry` if it can fail for a moment.
 
-### Errors no branch returned
-
-A `Failure` among a settled `Parallel`'s outcomes can also hold an error the branch never returned: what one of its Commands threw, or what an `onBeforeCommand` hook vetoed it with. Neither is in the branch's declared error type. So give the code that reads the outcomes a case for an error it does not recognise, as for a run's result (see [TypeScript](#typescript-typed-errors-and-context)). Otherwise it falls into the last error it expects, and reports a vetoed charge as a declined card.
-
-Fewer such errors reach the outcomes when a branch returns what it can as data. Catch an error the flow can handle inside the Command's function and return it (see [Which Errors Are Data](#which-errors-are-data)). To stop a batch, read the operator's switch in a Command whose `next` returns a `Failure`, rather than vetoing in `onBeforeCommand`:
-
-```js
-// Read before each charge, so a switch flipped mid-batch stops the charges that have not started.
-const cmdBillingHalted = () => flags.get('billing.halted');
-const billUnlessHalted = (subscription) =>
-    Command(cmdBillingHalted, (halted) => (halted ? Failure('halted') : billOne(subscription)));
-
-Parallel(subscriptions.map(billUnlessHalted), (outcomes) => Success(outcomes.map(summarize)), {
-    limit: 5,
-    settled: true
-});
-```
-
-The halt is then one of the branch's declared errors, typed like a declined card, and the trace records each read of the switch, so the batch replays. A vetoed Command leaves no entry in the trace, so a replay of a vetoed batch fails at the first veto.
-
-Bugs in the flow are not collected. An `EffectTypeError`, thrown for a malformed flow, and an error thrown by a `next` function or a pure step both still escape a settled `Parallel`, after the other branches are cancelled.
-
-### Replaying a cancelled `Parallel`
-
-Which branch failed first and cancelled the others depends on timing, so it is recorded with the trace. A replay of a cancelled `Parallel` returns the same failure production did, and stops each other branch where production stopped it, rather than letting whichever branch the replay reaches first decide. The same holds when the branch that cancelled the others was a `next` function or a pure step that threw: the replay throws the same error.
-
-If the branch that cancelled the others no longer fails, or the `Parallel` no longer has that branch, the replay ends in a `TimeParadox` naming it. The trace also records how many branches each `Parallel` had, so a replay of one that has gained or lost a branch ends in a `TimeParadox` before any of its branches run.
-
-A generator flow in a cancelled branch can run its `catch` and `finally` one step later in a replay than it did in production. A trace marks where a branch stopped only by its Commands. So a branch cancelled during a `Retry`'s wait, just before an `Ask`, or at a `Retry` or `Parallel` with no Command in it replays as though it stopped at its next Command.
+Under `settled`, a branch whose Command throws reaches `next` as a `Failure`, so the undo still runs. When one call follows another instead, as a shipment follows a charge, the later Command's function has to catch its own error and return it as data: a throw stops the flow before its `next` runs, and the charge stays. [Translating `try`/`catch`](#translating-trycatch) shows that shape.
 
 ## Composing Larger Flows
 
@@ -896,6 +619,40 @@ When the lookup is written in place rather than reused, the Command's own `next`
 
 In a generator flow, most of this comes for free. A step that branches into another flow is yielded like any other, as in `yield* step(processOrder(order))`. Values that do not depend on each other are joined with `const [cart, user] = yield* step(Parallel([fetchCart(input.cartId), fetchUser(input.userId)]))`. Values that do are variables, with no step to pass them on together; see [Where a generator helps](#where-a-generator-helps). Keep each decision in a step function that takes only what it needs, as the advice above says for a pipeline's steps.
 
+### Ending a flow early without an error
+
+Not every early end is an error. A webhook that has already handled an event should answer `duplicate` and do nothing else. A pipeline stops only at a `Failure`, so the step that decides ends the flow by what it returns: a `Success` holding the result, or the rest of the flow. Make it the last step of its pipeline, since a `Success` anywhere else passes on to the next step:
+
+```js
+const requireOrderId = (event) => (event.orderId ? Success(event) : Failure('Missing order ID.'));
+
+// The rest of the flow, for an event seen for the first time.
+const markOrderPaid = (event) => {
+    const cmdMarkOrderPaid = () => orderStore.markPaid(event.orderId);
+    return Command(cmdMarkOrderPaid, () => Success({ status: 'processed' }));
+};
+
+// Claiming the event decides: a duplicate ends the flow here, with a result rather than an error.
+const claimEvent = (event) => {
+    const cmdClaimEvent = () => eventLog.claim(event.eventId);
+    return Command(cmdClaimEvent, (firstTime) => (firstTime ? markOrderPaid(event) : Success({ status: 'duplicate' })));
+};
+
+const handleEvent = (event) => effectPipe(requireOrderId, claimEvent)(event);
+
+assert.deepEqual(
+    await runEffect(handleEvent({ eventId: 'evt_1', orderId: 'order_1' })),
+    Success({ status: 'processed' })
+);
+assert.deepEqual(
+    await runEffect(handleEvent({ eventId: 'evt_seen', orderId: 'order_1' })),
+    Success({ status: 'duplicate' })
+);
+assert.deepEqual(await runEffect(handleEvent({ eventId: 'evt_2' })), Failure('Missing order ID.'));
+```
+
+When the rest of the flow is longer, the step returns it as a pipeline of its own, as `processOrder` does above. In a generator flow, `return` ends the flow anywhere, but keep the decision in a step all the same: `return yield* step(claimEvent(event))`.
+
 ## Writing Loops
 
 A loop is written in two parts: a step that gets the list, and a `Parallel` over it, with `limit: 1` so the items run one after another, as in a `for` loop. The `async` version is usually split the same way. Paying a customer's unpaid invoices in order, and stopping at the first that fails:
@@ -995,7 +752,7 @@ const listAllOrders = () => {
 };
 ```
 
-To the flow, the whole loop is one step. A trace records the finished list as that step's result, and a replay hands the list back without replaying the pages. A `Retry` around the Command starts again from the first page. A flow test cannot see inside it, so, like any Command's function, it is left to an integration test.
+To the flow, the whole loop is one step. A trace records the finished list as that step's result, and a replay hands the list back without replaying the pages. A `Retry` around the Command starts again from the first page. A flow test cannot see inside it, so, like any Command's function, it is left to an integration test. This is rule 1 applied to a loop: the Command's function is the one call, `fetchAllOrders()`, and the loop lives in a function of its own that an integration test covers.
 
 The loop belongs in the flow only when the flow has to decide something on each pass, such as stopping at the first order that matches, or saving each page as it arrives. Then the Command's `next` returns the Command for the next page instead of a `Success`, until there are no more pages.
 
@@ -1023,7 +780,7 @@ const fetchPrice = (sku) => {
 
 The failed attempt is recorded as that Command's result, with the error's `code` and `message`, so a replay takes the same fallback branch. Copy the fields you need rather than returning the error itself: a trace keeps data, not objects, so an error stored inside a result loses its message (see [Recording in Production](#recording-in-production)).
 
-**A `Failure` means abort.** It stops the flow and goes back to the code that called `runEffect`, which decides what it means: an HTTP status, a queue retry, an alert. Nothing inside the flow can catch a `Failure`, so a reader never has to look elsewhere for a handler.
+**A `Failure` stops the flow.** It goes back to the code that called `runEffect`, which decides what it means: an HTTP status, a queue retry, an alert. Nothing inside the flow can catch a `Failure`, so a reader never has to look elsewhere for a handler.
 
 Rule of thumb: if you would handle it, return it as a value; if you would only report it, return a `Failure`. The one exception is retry exhaustion, which happens inside `Retry`; handle it with the `onExhausted` option in [Retrying Transient Failures](#retrying-transient-failures).
 
@@ -1050,16 +807,90 @@ Retry(
 );
 ```
 
+To retry some errors and not others, do both in one function: return the errors the flow handles, and rethrow the rest so `Retry` tries again. Here a charge the gateway refuses is handled, and anything else, such as a timeout, is retried:
+
+```js
+const chargeAmount = (amount) => {
+    const cmdChargeAmount = () =>
+        gateway.charge(amount).catch((error) => {
+            if (error.code === 'invalid_amount') return { refused: true, code: error.code };
+            throw error; // may pass on a later try
+        });
+    return Retry(Command(cmdChargeAmount), { retries: 2 });
+};
+
+// A later step turns the handled error into the flow's outcome.
+const requireCharge = (charge) => (charge.refused ? Failure(`Charge refused: ${charge.code}`) : Success(charge));
+const pay = (amount) => effectPipe(chargeAmount, requireCharge)(amount);
+
+assert.deepEqual(await runEffect(pay(0)), Failure('Charge refused: invalid_amount'));
+assert.deepEqual(await runEffect(pay(25)), Success({ chargeId: 'ch_1', amount: 25 }));
+```
+
 `runEffect` tells these cases apart:
 
-| what happened | what it is | what `Retry` does | what `onExhausted` sees |
-| --- | --- | --- | --- |
-| a step returned `Failure(...)`, or an `onBeforeCommand` hook threw | an abort | nothing; it propagates at once, unwrapped | nothing |
-| a Command's function threw | an I/O fault | retries it | the exhaustion, once the attempts are gone |
-| a `next` function or a pure step threw, or the flow is malformed | a bug | nothing; it is thrown, not returned | nothing |
+| what happened | what it is | what `Retry` does | what `onExhausted` sees | what the caller's `Failure` holds |
+| --- | --- | --- | --- | --- |
+| a step returned `Failure(...)`, or an `onBeforeCommand` hook threw | a stop | nothing; it propagates at once, unwrapped | nothing | the error returned or thrown |
+| a Command's function threw | an I/O fault | retries it | the exhaustion, once the attempts are gone | the error thrown, or, once a `Retry` gives up, `{ retryExhausted, lastError, retries }` |
+| a `next` function or a pure step threw, or the flow is malformed | a bug | nothing; it is thrown, not returned | nothing | nothing; `runEffect` rejects |
 
 In short, **you can recover from an error your I/O produced, but you cannot catch a `Failure` a step returned.** Only the code that called `runEffect` acts on it. For the same reason, do not throw business errors from a Command's function: a throw there tells `Retry` that the I/O broke, and `Retry` will try again. A throw anywhere else in the flow is a bug, and is thrown as it is rather than returned as a `Failure`. `runEffect` rejects with it, or, from a step before the first Command, the call that builds the flow throws it.
 
+### Translating `try`/`catch`
+
+A `catch` around `yield*` can log and rethrow, but it cannot recover, and it sees a `FlowStopped` error rather than the original. So each `try`/`catch` in an `async` function moves to where its error happens. The four common shapes:
+
+- **Carry on past a failed call.** Catch inside the Command's function and return the error as data, as below.
+- **Undo the calls that succeeded when one running beside them fails.** Run the calls in a `Parallel` with `settled: true`, and have its `next` undo the ones that succeeded; see [Undoing what succeeded when a branch fails](#undoing-what-succeeded-when-a-branch-fails).
+- **Undo an earlier call when a later one fails.** Catch inside the later Command's function and return the error as data, and have its `next` return the Command that undoes the earlier one, as in the second example below. A later Command that throws instead stops the flow before its `next` runs, so nothing is undone.
+- **Retry, then give up.** Wrap the Command in `Retry`, and put what the `catch` did after the last try in `onExhausted`; see [Retrying Transient Failures](#retrying-transient-failures).
+
+A welcome email whose failure the flow reports but does not stop for:
+
+```js
+// Takes the mailer, so a test can hand it one that fails.
+const makeSendWelcome = (mailer) => (user) => {
+    const cmdSendWelcome = () =>
+        mailer
+            .sendWelcome(user.email)
+            .then(() => ({ sent: true }))
+            .catch((error) => ({ sent: false, reason: error.message }));
+    return Command(cmdSendWelcome);
+};
+
+const failingMailer = {
+    sendWelcome: async () => {
+        throw new Error('smtp down');
+    }
+};
+const welcome = await runEffect(makeSendWelcome(failingMailer)({ email: 'test@test.com' }));
+assert.deepEqual(welcome, Success({ sent: false, reason: 'smtp down' }));
+```
+
+A reservation made after a charge, which refunds the charge when the reservation fails:
+
+```js
+const refundCharge = (charge, reason) => {
+    const cmdRefundCharge = () => payments.refund(charge.chargeId);
+    return Command(cmdRefundCharge, () => Failure(`Reservation failed: ${reason}`));
+};
+
+const reserveStock = (charge) => {
+    const cmdReserveStock = () =>
+        warehouse
+            .reserve(charge.orderId)
+            .then(() => ({ reserved: true }))
+            .catch((error) => ({ reserved: false, reason: error.message }));
+    return Command(cmdReserveStock, (reservation) =>
+        reservation.reserved ? Success(charge) : refundCharge(charge, reservation.reason)
+    );
+};
+
+const reservation = await runEffect(reserveStock({ orderId: 'order_1', chargeId: 'ch_1' }));
+assert.deepEqual(reservation, Failure('Reservation failed: out of stock'));
+```
+
 ### A malformed flow
 
 A flow that is not made of Effects is a bug, so it throws an `EffectTypeError` that says where, rather than returning a `Failure`. The steps before a flow's first Command run as it is built. So a mistake in one of them is thrown by the call that builds the flow, as `registerUserFlow(input)` would throw if its first step returned a plain object:
@@ -1160,6 +991,40 @@ A step in a body's `finally` is not supported. It runs when the body ends normal
 
 In TypeScript, most of these do not compile; see [TypeScript](#typescript-typed-errors-and-context).
 
+## Parallel in Depth
+
+What [Running Effects in Parallel](#running-effects-in-parallel) leaves out: errors no branch returned, and how a cancelled `Parallel` replays.
+
+### Errors no branch returned
+
+A `Failure` among a settled `Parallel`'s outcomes can also hold an error the branch never returned: what one of its Commands threw, or what an `onBeforeCommand` hook vetoed it with. Neither is in the branch's declared error type. So give the code that reads the outcomes a case for an error it does not recognise, as for a run's result (see [TypeScript](#typescript-typed-errors-and-context)). Otherwise it falls into the last error it expects, and reports a vetoed charge as a declined card.
+
+Fewer such errors reach the outcomes when a branch returns what it can as data. Catch an error the flow can handle inside the Command's function and return it (see [Which Errors Are Data](#which-errors-are-data)). To stop a batch, read the operator's switch in a Command whose `next` returns a `Failure`, rather than vetoing in `onBeforeCommand`:
+
+```js
+// Read before each charge, so a switch flipped mid-batch stops the charges that have not started.
+const cmdBillingHalted = () => flags.get('billing.halted');
+const billUnlessHalted = (subscription) =>
+    Command(cmdBillingHalted, (halted) => (halted ? Failure('halted') : billOne(subscription)));
+
+Parallel(subscriptions.map(billUnlessHalted), (outcomes) => Success(outcomes.map(summarize)), {
+    limit: 5,
+    settled: true
+});
+```
+
+The halt is then one of the branch's declared errors, typed like a declined card, and the trace records each read of the switch, so the batch replays. A vetoed Command leaves no entry in the trace, so a replay of a vetoed batch fails at the first veto.
+
+Bugs in the flow are not collected. An `EffectTypeError`, thrown for a malformed flow, and an error thrown by a `next` function or a pure step both still escape a settled `Parallel`, after the other branches are cancelled.
+
+### Replaying a cancelled `Parallel`
+
+Which branch failed first and cancelled the others depends on timing, so it is recorded with the trace. A replay of a cancelled `Parallel` returns the same failure production did, and stops each other branch where production stopped it, rather than letting whichever branch the replay reaches first decide. The same holds when the branch that cancelled the others was a `next` function or a pure step that threw: the replay throws the same error.
+
+If the branch that cancelled the others no longer fails, or the `Parallel` no longer has that branch, the replay ends in a `TimeParadox` naming it. The trace also records how many branches each `Parallel` had, so a replay of one that has gained or lost a branch ends in a `TimeParadox` before any of its branches run.
+
+A generator flow in a cancelled branch can run its `catch` and `finally` one step later in a replay than it did in production. A trace marks where a branch stopped only by its Commands. So a branch cancelled during a `Retry`'s wait, just before an `Ask`, or at a `Retry` or `Parallel` with no Command in it replays as though it stopped at its next Command.
+
 ## TypeScript: Typed Errors and Context
 
 The bundled declarations need TypeScript 5.1 or later.
@@ -1195,6 +1060,30 @@ Value types are checked through the pipeline too, so a step that reads a field t
 
 `effectPipe` is typed for up to 20 steps. A pipeline is itself a step, so a longer one nests, which is usually easier to read anyway: `effectPipe(effectPipe(s1, s2), effectPipe(s3, s4))`.
 
+### Handling every error
+
+A `switch` over a flow's error union can make TypeScript refuse a case you forgot. Check first for a thrown error, which reaches `result.error` without being in the union, and end the `switch` with a `never`, so a case added to the union later is a compile error until it is handled. TypeScript narrows a `switch` only over a union, so with a single error type, leave out the `default`:
+
+```ts
+type BillingError = { type: 'NoSubscription' } | { type: 'CardDeclined'; code: string };
+
+const result = await runEffect(billTenant(tenantId), context);
+if (result.type === 'Failure') {
+    const thrown: unknown = result.error;
+    if (thrown instanceof Error) return serverError(thrown); // a Command's function threw
+    switch (result.error.type) {
+        case 'NoSubscription':
+            return skipTenant();
+        case 'CardDeclined':
+            return notifyDecline(result.error.code);
+        default: {
+            const unhandled: never = result.error;
+            return serverError(unhandled);
+        }
+    }
+}
+```
+
 ### Typed context with `Ask`
 
 `Effect<T, E, Ctx>` carries a third type parameter for the context object:
@@ -1223,7 +1112,28 @@ const registerUser = effectGen(function* (input: { email: string }) {
 // (input: { email: string }) => Effect<User, 'EMAIL_TAKEN' | the errors findUser and saveUser declare>
 ```
 
-`yield* x` without `step`, reading a property of a step, and an `async function*` do not compile, and a body that returns an untyped value keeps its steps' errors. Returning a step or a Promise compiles, so that a generic helper returning a value of its type parameter does too, and fails when it runs. `yield step(x)` without the star does, and fails when it runs. Name the context `Ask()` reads as `Ask<AppContext>()`.
+`yield* x` without `step`, reading a property of a step, and an `async function*` do not compile, and a body that returns an untyped value keeps its steps' errors. Returning a step or a Promise compiles, so that a generic helper returning a value of its type parameter does too, and fails when it runs. `yield step(x)` without the star does, and fails when it runs. Name the context `Ask()` reads as `Ask<AppContext>()`. Given a function, `Ask`'s first type argument is the value instead, so annotate the parameter: `Ask((ctx: AppContext) => ...)`.
+
+### A flow with no input
+
+A flow takes its input as one parameter. For one that needs none, such as a nightly job that gets everything from its Commands, type the parameter `void`, so the flow is called with no argument. In a pipeline, that is the first step's parameter. Without it, `nightlyReport()` fails to compile with "Expected 1 arguments, but got 0":
+
+```ts
+const nightlyReport = effectGen(function* (_input: void) {
+    const users = yield* step(listUsers());
+    return users.length;
+});
+
+const result = await runEffect(nightlyReport());
+
+// The same as a pipeline.
+const nightlyCount = effectPipe(
+    (_input: void) => listUsers(),
+    (users) => Success(users.length)
+);
+
+const counted = await runEffect(nightlyCount());
+```
 
 ### Testing a flow in TypeScript
 
@@ -1247,6 +1157,369 @@ assertCommand(step1.next(null), 'cmdSaveUser');
 
 For a step that returns its Command directly, as in `ensureEmailAvailable(input).next(found)`, `next` is checked against what the Command's function returns. So where [Testing Without Mocks](#testing-without-mocks) passes `{ id: 1 }` for a user that was found, a TypeScript test passes a whole user, of the type `db.findUser` returns. A Command reached any other way, by walking the whole flow or through an `Ask`'s `next`, accepts any value, since its type does not say which Command it is.
 
+## Time-Travel Debugging
+
+Record what each Command returned, then feed those results back into the flow to retrace the path a request took, with no database or network.
+
+Record a run with `recordEffect`, and `replayEffect` hands each Command what it returned the first time. That is how a run recorded in production replays on your machine, with nothing connected:
+
+```js
+import { recordEffect, replayEffect } from 'pure-effect';
+
+// A real run returns its result, and a trace of what each Command returned.
+const { result: live, trace } = await recordEffect(registerUserFlow(input));
+
+// Anywhere else, with nothing connected, the same flow gets the same answers.
+const { result: replayed } = await replayEffect(registerUserFlow(trace.initialInput), trace);
+assert.deepEqual(replayed, live);
+```
+
+In production, record each run with a version and a flow name, and replay its trace anywhere with `timeTravel`, which narrates each step:
+
+```js
+import { recordEffect, replayEffect, timeTravel } from 'pure-effect';
+
+// Record a real run. The context's flowName names the flow in the trace.
+const { result, trace } = await recordEffect(checkoutFlow(input), {
+    version: process.env.BUILD_ID,
+    context: { flowName: 'checkout' }
+});
+
+// Later, somewhere else, with nothing connected:
+await timeTravel(checkoutFlow, trace);
+```
+
+```
+Replaying 'checkout' (3 recorded steps)
+Initial input: {
+  "cartId": "cart_abc123",
+  "promoCode": "FREE_YEAR_VIP"
+}
+Step 1: cmdFetchCart returned in 41.277ms {
+  "totalAmount": "120.00"
+}
+Step 2: cmdValidatePromo returned in 26.814ms {
+  "isValid": true,
+  "discountValue": 100
+}
+Step 3: cmdChargeCard threw in 181.507ms {
+  "code": "invalid_amount",
+  "name": "Error",
+  "message": "Amount must be non-zero."
+}
+Replay finished with state: Failure
+Error: {
+  "code": "invalid_amount",
+  "name": "Error",
+  "message": "Amount must be non-zero."
+}
+```
+
+A production incident becomes a regression test, with no mocks:
+
+```js
+it('prod incident 8f3a: a 100% promo produces a $0 charge', async () => {
+    const { result } = await replayEffect(checkoutFlow(trace.initialInput), trace);
+    assert.equal(result.type, 'Failure');
+    assert.equal(result.error.code, 'invalid_amount');
+});
+```
+
+The test checks that the flow still takes the recorded path and handles the recorded outcomes the same way. It does not check the values the flow computes, since every result comes from the recording; see [What a replay cannot check](#what-a-replay-cannot-check). If a refactor reorders or replaces a step, the replay ends in a `Failure` whose error is a `TimeParadox` naming where it diverged. It is not thrown, so a test that expects a `Failure` should check the error too, as this one checks its `code`.
+
+A step the trace lacks ends the replay in a `Failure` holding a `ReplayError`. A trace lacks a step that comes after the end of the recording, one a hook vetoed in production, and one the recorder dropped under `maxEntries`.
+
+A flow that stops issuing Commands before the recording ends (for example, a fix that skips the charge) produces no `TimeParadox`, and the replay can end in `Success` with recorded steps left over. `replayEffect` returns those steps as `unreached`, so a test can assert which ones it expects to skip:
+
+```js
+it('incident 8f3a fixed: a 100% promo checks out without a charge', async () => {
+    const { result, unreached } = await replayEffect(checkoutFlow(trace.initialInput), trace);
+    assert.equal(result.type, 'Success');
+    assert.deepEqual(
+        unreached.map((e) => e.command),
+        ['cmdChargeCard']
+    );
+});
+```
+
+For every other recording, `unreached` should be empty, so a fix that skips a step by accident fails the test. This works when the removed step is the last one the flow reaches. Remove a step from the middle and every later step moves to a different path, so the replay stops at a `TimeParadox`, and `unreached` lists the steps it never got to. [Proving a fix that changes the flow's shape](#proving-a-fix-that-changes-the-flows-shape) shows how to test such a fix.
+
+A test can also run a whole flow with no recording at all, answering each Command itself; see [Testing a whole flow](#testing-a-whole-flow).
+
+### Reading a trace
+
+A trace is plain JSON. This one is from a checkout whose card charge timed out once and then went through:
+
+```text
+{
+  "flowName": "checkout",
+  "version": "b42",
+  "initialInput": { "cartId": "cart_1" },
+  "context": { "flowName": "checkout" },
+  "dropped": 0,
+  "trace": [
+    { "command": "cmdFetchCart", "path": "0", "result": { "total": 120 }, "durationMs": 41.3 },
+    { "command": "cmdChargeCard", "path": "1r0/0", "threw": true,
+      "error": { "__error": true, "name": "Error", "message": "gateway timeout", "code": "ETIMEDOUT" }, "durationMs": 5002.1 },
+    { "command": "cmdChargeCard", "path": "1r1/0", "result": { "chargeId": "ch_1" }, "durationMs": 181.5 }
+  ]
+}
+```
+
+`trace` holds one entry per step, in the order the steps finished; [`recorder`](#recorderoptions) lists each kind of entry. A replay matches each step by its `path`, its position in the flow, and a `TimeParadox` names the path where the flow and the trace part ways:
+
+- A number counts the Commands, `Retry`s and `Parallel`s the flow reached, from `0`. A `Success` or an `Ask` between them adds nothing.
+- `r` and a number is one attempt of the `Retry` at that position, `r0` being the first try, and `rf` is its `onExhausted` fallback.
+- `p` and a number is one branch of the `Parallel` at that position, from `p0`. The `Parallel` has an entry of its own, at a path such as `2p`, which records whether a branch cancelled the others.
+- `/` goes one level in. `1r1/0` is the first step of the second try of the `Retry` at position 1. `2p1/0` is the first step of the second branch of the `Parallel` at position 2.
+
+### What a replay cannot check
+
+A replay proves that the flow asks for the same Commands in the same order and handles the same answers. Every result comes from the recording, so it cannot check:
+
+- **What the flow computes.** Fix how a refund amount is calculated and replay the bad run: the charge step still gets the old amount from the recording. The replay reports `Success`, returns the value from before the fix, and flags nothing. Test a value change against the pure step that computes it.
+- **A fix inside a Command's function.** The function never runs, so an old trace hands the flow what it returned or threw before the fix. Catch a duplicate-key error inside the function and return it as data, and the old trace still replays the throw. Cover such a fix with an integration test.
+- **The arguments a Command was called with.** A trace records results only. Given the recorded input and results, the flow does the same thing again, so replaying up to a step rebuilds its arguments for a debugger, but a test cannot assert on them. Storing them would also double what `redact` has to cover, since arguments are usually the sensitive part of a call.
+
+When a Command's result changes shape, rename the Command. A trace matches it by name. So under the old name, an old trace hands the new code a result in the old shape, which it can take for another answer without any `TimeParadox`.
+
+## Recording in Production
+
+`recordEffect` suits tests and scripts, where one call covers the whole run. To record an application without changing any call site, install the hooks once at startup. The two files imported below ship in the package's `examples` folder, `node_modules/pure-effect/examples`, and in the repository's [examples folder](https://github.com/aycangulez/pure-effect/blob/main/examples); copy them into your project.
+
+```js
+import { randomUUID } from 'node:crypto';
+import { configureEffect } from 'pure-effect';
+import { recordingHooks } from './recording-example.js';
+import { telemetryHooks } from './opentelemetry-example.js';
+
+configureEffect(
+    telemetryHooks(),
+    recordingHooks({
+        sink: (trace) => putObject(`traces/${trace.flowName}/${randomUUID()}.json`, JSON.stringify(trace)),
+        // Attached to each trace, so timeTravel warns when it replays one against another build.
+        version: process.env.BUILD_ID,
+        // A replay runs validation again on the stored input, so the stand-in keeps the password rule's verdict.
+        redact: (value, name, kind) =>
+            kind === 'initialInput' ? { ...value, password: value.password.length >= 8 ? '[redacted]' : '' } : value,
+        maxEntries: 500,
+        keep: (result) => result.type === 'Failure' // the default; keep everything, or sample
+    })
+);
+```
+
+What the example does with each run:
+
+- **Which runs it keeps.** `keep` decides. By default it keeps a run that ended in a `Failure`, and discards a successful one after holding it in memory.
+- **When your own code throws.** A `TypeError` after an API changed the shape of its response, say, makes the run reject. `keep` is offered a `Failure` carrying the thrown error, so by default its trace is kept, and replaying it reproduces the throw. A step before the flow's first Command runs when the flow is built, outside `runEffect`, so its throw reaches no hook and is not recorded. That run did no I/O, so its input reproduces it.
+- **What a trace holds.** `redact` runs before anything enters the trace, including the stored `initialInput` and `context`. A value it throws on, or one JSON cannot hold, such as a `BigInt`, is left out and marked `unrecorded`, and a replay stops there. Everything else is already in the form JSON holds, so the sink can write it to S3 or a database column with `JSON.stringify`.
+- **How long a trace gets.** `maxEntries` caps it and reports the overflow as `dropped`, and a capped trace replays only up to the first step it lacks.
+- **When storage fails.** If `keep` or the sink throws, for example because storage is unreachable, the run keeps its own outcome and the error goes to `onSinkError`, which defaults to `console.error`.
+- **What it warns about.** The example warns through `onWarning`, once per flow, when it keeps a trace that was capped, one holding values it could not record, or one whose steps include any named `'anonymous'`.
+
+The example takes the input from `onRun`, which is handed it only for a flow `effectPipe` or `effectGen` built, so build the outermost flow with one of them. A flow that starts with a bare `Command`, `Ask`, `Retry`, or `Parallel` records no input, and `timeTravel` would rebuild it from `undefined`. A one-step pipeline is enough, as in `runEffect(effectPipe(loadProfile)(userId))`. The example warns through `onWarning`, which defaults to `console.warn`, the first time it keeps a trace of such a flow, and `timeTravel` warns when it replays one.
+
+The example also takes the context from the run's first Command, so a run that stops before any Command, for example at an `Ask` check, records no context. Such a run did no I/O, so running the flow again with its input and the context from your logs reproduces it.
+
+**A trace keeps data, not objects.** A value is copied into the form JSON stores when it is recorded, and copied again each time a replay hands it to the flow. So neither a later step nor a replay can change what the trace says, and a replay from memory gets what a replay from storage gets. The copy keeps values but not classes:
+
+| Recorded                            | Replayed as                                         |
+| ----------------------------------- | --------------------------------------------------- |
+| a money object or a database entity | a plain object, without its methods                 |
+| a `Date`                            | a string                                            |
+| a `Map` or a `Set`                  | `{}`                                                |
+| a `Buffer`                          | `{ type: 'Buffer', data }`                          |
+| `undefined` in an array             | `null`                                              |
+| an error returned inside a result   | its own fields, such as `code`, without its message |
+
+A reference back to an object the value is inside of, as between an HTTP client's request and response, is cut. A value JSON cannot hold at all, such as a `BigInt` or an object whose getter throws, is left out of the trace and marked `unrecorded` before `redact` sees it. So a context holding a lazy client is left out whole.
+
+So return plain data from a Command's function. Turn a class instance into a plain object before returning it, with a small named function you can test on its own, as in `() => db.findCart(id).then(cartToData)`. Rebuild the object in `next` if the flow needs its methods. When you catch an error to return it as data, copy the fields the flow branches on, as in `.catch((error) => ({ ok: false, code: error.code }))`, rather than returning the error itself.
+
+### Keeping secrets out of a trace
+
+`redact` sees everything a trace stores: each result, each thrown error, the flow's input and the context, told apart by `kind`. It gets a copy in the form the trace stores, so changing it in place is safe, and what it returns is stored in that form too. A thrown `Error` arrives as a plain object holding its `name`, `message` and own fields, and any object returned for it replays as an `Error`.
+
+Check a value before replacing a field in it, since `{ ...value, email: '[redacted]' }` turns a `null` into an object and the replay takes the other branch:
+
+```js
+// Masks a field only where there is one, so a lookup that found nothing still records null.
+const mask = (value, field) =>
+    value && typeof value === 'object' && field in value ? { ...value, [field]: '[redacted]' } : value;
+
+const redact = (value, name, kind) => {
+    if (kind === 'initialInput') return mask(value, 'cardNumber');
+    if (kind === 'context') return mask(value, 'authToken');
+    if (kind === 'error') return mask(value, 'attempted');
+    return name === 'cmdFetchUser' ? mask(value, 'email') : value;
+};
+recorder({ redact });
+
+assert.equal(redact(null, 'cmdFetchUser', 'result'), null); // still nothing found
+assert.equal(redact('card_declined', 'cmdCharge', 'error'), 'card_declined'); // still a string
+```
+
+A replay rebuilds the flow from the redacted input and context. So a field a step checks, such as a password, needs a stand-in the check treats the same way, as the example at the top of this section does. A context field an `Ask` reads should stay.
+
+## Hooks
+
+Hooks see every run, and recording, replay and the telemetry example are built on them. There are three: `onRun` wraps a whole run, `onStep` wraps each Command and each `Parallel`, and `onBeforeCommand` runs before each Command and can veto it by throwing. A hook that only watches must `await` what it wraps and return its result; [`configureEffect`](#configureeffectconfigs) lists each hook's arguments.
+
+`configureEffect` adds a layer of hooks for the whole process and returns a function that removes it. Removing a layer removes only that layer, even when others were installed after it, so a library can add and remove its own hooks without touching the application's:
+
+```js
+const remove = configureEffect(telemetryHooks(), recordingHooks({ sink }));
+// the same as configureEffect(telemetryHooks()) followed by configureEffect(recordingHooks({ sink }))
+remove();
+```
+
+Layers run in the order they were installed, the first outermost, so a result or a thrown error unwinds from the innermost hook out:
+
+```
+runEffect(flow(input))
+│
+├─ telemetry.onRun                       first configuration: outermost
+│  └─ recording.onRun                    last configuration: innermost
+│     │
+│     │  for each Command:
+│     ├─ telemetry.onBeforeCommand       interceptors all run, in the order given
+│     ├─ recording.onBeforeCommand
+│     ├─ telemetry.onStep
+│     │  └─ recording.onStep             closest to the Command
+│     │     └─ cmd()
+│     │  ┌─ recording.onStep returns     a result, or a thrown error, unwinds
+│     ├─ telemetry.onStep returns        from the inside out
+│     │
+│  ┌─ recording.onRun returns
+├─ telemetry.onRun returns
+```
+
+**Knowing which request a step belongs to.** `onStep` and `onRun` get no context, so a hook that logs per request finds the request the way the rest of your logging does. An `AsyncLocalStorage` scope entered around `runEffect` reaches every hook the run calls, and the recording example uses one to give each run its own recorder:
+
+```js
+import { AsyncLocalStorage } from 'node:async_hooks';
+
+const requestScope = new AsyncLocalStorage();
+const stepLog = [];
+
+// Logs each step with its request and duration, and returns what the step returned.
+const removeStepLog = configureEffect({
+    onStep: async (name, type, op, path) => {
+        const started = performance.now();
+        try {
+            return await op();
+        } finally {
+            const { requestId } = requestScope.getStore() ?? {};
+            stepLog.push({ requestId, name, path, ms: performance.now() - started });
+        }
+    }
+});
+
+await requestScope.run({ requestId: 'req_1' }, () => runEffect(registerUserFlow(input)));
+assert.deepEqual(
+    stepLog.map((line) => [line.requestId, line.name]),
+    [
+        ['req_1', 'cmdFindUser'],
+        ['req_1', 'cmdSaveUser']
+    ]
+);
+removeStepLog();
+```
+
+A Command that `onBeforeCommand` vetoes never reaches `onStep`, so log a veto where you make it. In tests, call `configureEffect()` with no arguments in a `beforeEach`, so a test that fails before removing its hooks does not leave them installed for the next.
+
+**Per-call hooks.** `runEffect`'s third argument takes hooks for that call only. They are merged with the configured ones by the same rules: the configured wrappers run outside them, and the configured `onBeforeCommand` hooks run first. `inherit: false` leaves the configured hooks out. With configured hooks `C` and a call `K` that supplies only `onStep`:
+
+```
+                  inherit: true (default)        inherit: false
+
+onRun             C.onRun                        (none)
+onBeforeCommand   C.onBeforeCommand              (none)
+onStep            C.onStep( K.onStep( cmd ) )    K.onStep
+```
+
+`recordEffect` inherits, so recording inside an application that already traces still produces spans. `replayEffect` passes `inherit: false` unless `hooks: true`.
+
+## Replay in Depth
+
+What [Time-Travel Debugging](#time-travel-debugging) leaves out: proving a fix that changes a flow's shape, keeping a replay faithful, and replaying from storage other than a trace.
+
+### Proving a fix that changes the flow's shape
+
+A fix that removes or moves a step in the middle of a flow changes the path of every step after it, so its old trace stops at a `TimeParadox`. Here the incident is a checkout that tried to charge a free cart, and the fix skips the charge, so the save moves to where the charge was:
+
+```js
+const fetchCart = (cartId) => {
+    const cmdFetchCart = () => carts.find(cartId);
+    return Command(cmdFetchCart);
+};
+
+const chargeCart = (cart) => {
+    const cmdChargeCard = () => gateway.charge(cart.total);
+    return Command(cmdChargeCard, () => Success(cart));
+};
+
+const saveOrder = (cart) => {
+    const cmdSaveOrder = () => orderStore.save(cart);
+    return Command(cmdSaveOrder);
+};
+
+// Production ran this, and recorded the charge failing.
+const checkoutBefore = (cartId) => effectPipe(fetchCart, chargeCart, saveOrder)(cartId);
+const { trace: incident } = await recordEffect(checkoutBefore('cart_free'));
+
+// The fix: no charge when there is nothing to charge.
+const chargeIfDue = (cart) => (cart.total === 0 ? Success(cart) : chargeCart(cart));
+const checkoutFixed = (cartId) => effectPipe(fetchCart, chargeIfDue, saveOrder)(cartId);
+
+// Against the old trace, the fixed flow stops where the save took the charge's place.
+const { result: paradox } = await replayEffect(checkoutFixed(incident.initialInput), incident);
+assert.equal(paradox.error.name, 'TimeParadox');
+```
+
+Prove such a fix in three parts. Test the decision that changed, as a pure step. Then walk the fixed flow from the incident's input, handing each step the answer production got for it, for as long as the fix leaves the steps as they were:
+
+```js
+import { commandName } from 'pure-effect';
+
+// The decision that changed: a free cart is not charged.
+assert.deepEqual(chargeIfDue({ id: 'cart_free', total: 0 }), Success({ id: 'cart_free', total: 0 }));
+
+// Given the cart production fetched, the fixed flow saves the order without charging it.
+const fetchedCart = incident.trace.find((entry) => entry.command === 'cmdFetchCart').result;
+const first = checkoutFixed(incident.initialInput);
+assert.equal(commandName(first), 'cmdFetchCart');
+assert.equal(commandName(first.next(fetchedCart)), 'cmdSaveOrder');
+```
+
+The walk takes production's answers only up to the change. Past it, each recorded answer belongs to a step that has moved, so the trace has nothing more to say about the fixed flow. Last, once the fix ships, record the incident again, so its regression test is a plain replay once more.
+
+### Keeping a replay faithful
+
+Put anything that varies between runs inside a Command. For replay, the current time or a random ID counts as I/O. In a Command it is recorded and replayed like any other result. A step that calls `Date.now()` directly gets a new value on every replay, and drifts from the trace.
+
+To check a flow, record it, replay the trace, and compare the outcomes. A step that computes a fresh value shows up as a different final value, or as a `TimeParadox` if it changes which Commands run. A trace holds each result in the form JSON stores it, so this also catches a result your storage cannot keep, such as a `Date` the flow calls a method on:
+
+```js
+const { result, trace } = await recordEffect(registerUserFlow(input));
+const { result: replayed } = await replayEffect(registerUserFlow(input), trace);
+assert.deepEqual(replayed, result); // fails if a step computed a fresh value, or a result did not survive storage
+```
+
+A `Failure` compares the same way when the Command threw a plain `Error`. It comes back with its message, name, cause, custom properties and an `AggregateError`'s list of errors, even a `name` or `cause` set after it was created. An error of any other class, built-in ones included, comes back as a plain `Error` carrying that class's name. So `deepEqual` from `node:assert/strict` refuses the replayed `TypeError` that `fetch` rejects with when the network fails. Where a Command can throw one, compare `error.name` and `error.message` instead.
+
+### Replaying from your own storage
+
+`replayEffect` also accepts a resolver function instead of a trace, so you can replay from OpenTelemetry spans, a log pipeline, or a database table, not only from the JSON that `recorder` produces. Whatever you store needs each step's `path`, which `onStep` receives, and its result; the telemetry example records neither, since it keeps values off spans.
+
+```js
+// A resolver answers one question: what did production get back for this step? Look the step up by its path, its
+// position in the flow. `step.index` counts steps in the order they finished, which shifts around a Parallel.
+const outputs = new Map(mySpans.map((span) => [span.attributes.path, span.attributes.output]));
+const resolve = (step) => (outputs.has(step.path) ? { result: outputs.get(step.path) } : undefined);
+await replayEffect(checkoutFlow(input), resolve);
+```
+
 ## Why Pure Effect
 
 **vs. Temporal and durable execution (Restate, Inngest):** The closest relatives, built on the same idea: record what every step returned and replay it. Those engines store the history on a server and resume workflows automatically after a crash. Pure Effect leaves storage and restarts to your application, and there is no infrastructure to run.
@@ -1366,7 +1639,7 @@ Runs a flow and resolves with its `Success` or `Failure`. See [Which Errors Are
 
 - `context`: what `Ask` reads, also passed to `onBeforeCommand`. `context.flowName` names the run in traces and telemetry.
 - `callConfig`: `onStep`, `onRun` and `onBeforeCommand` for this call only, added to the configured hooks, or used alone with `inherit: false`; see [Hooks](#hooks).
-- A throw from a Command's function, or an `onBeforeCommand` veto, ends the run with a `Failure`.
+- A throw from a Command's function, or an `onBeforeCommand` veto, ends the run with a `Failure` holding the error thrown; under a `Retry` that gave up, it holds `{ retryExhausted, lastError, retries }`.
 - A malformed flow, or a throw from a `next` or a pure step, is a bug. The call that builds the flow throws it before the first Command, and `runEffect` rejects with it after.
 
 #### `configureEffect(...configs)`
@@ -1418,7 +1691,7 @@ Runs a flow with each Command answered from a trace instead of run, and returns
 
 - A flow that no longer matches the trace ends in a `Failure` whose `error` is a `TimeParadox`, or a `ReplayError` for a step the trace lacks. Neither is thrown, so a test checks `error.name`.
 - A malformed trace rejects with a `ReplayError`.
-- `traceOrResolver`: a trace, its bare entries, or a resolver: a function that answers each step with `{ result }`, `{ error }`, or `undefined` for a step it has no record of. See [Replaying from your own storage](#replaying-from-your-own-storage).
+- `traceOrResolver`: a trace, its bare entries, or a resolver: a function that answers each step with `{ result }`, `{ error }`, or `undefined` for a step it has no record of. See [Testing a whole flow](#testing-a-whole-flow) and [Replaying from your own storage](#replaying-from-your-own-storage).
 - Any other answer from a resolver, `null` included, or a throw from it, rejects the replay. With a resolver, `unreached` is absent.
 - A resolver is also asked about each `Parallel`, with `step.type` set to `'Parallel'`. Answering with the recorded cancellation as `{ result }` replays it as production decided, and anything else replays it by timing.
 - `options.context`: the context for `Ask`, by default the one the trace recorded. A resolver has none, so pass one if the flow reads `Ask`; a trace whose context could not be recorded refuses to replay without one.