pure-effect 0.16.0 → 0.17.0

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 All notable changes to pure-effect are recorded here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and from 1.0.0 the project follows [Semantic Versioning](https://semver.org/). Before 1.0.0 a minor version could change behaviour; each such change is marked below.
 
+## [0.17.0] - 2026-10-06
+
+### Changed
+
+- **Inside a `Parallel`, a Command's function gets the `AbortSignal` only if it takes a parameter.** Every function was handed the signal, so one passed by name whose first parameter has a default value read the signal in its place: `Command(nanoid)` returned an empty ID inside a `Parallel` and a full one outside, and a helper with a default page size got the signal as its page size. The signal now goes only to a function that declares a parameter, counted as `Function.length` counts them, which leaves out parameters with default values, so such a function keeps its default everywhere. A function that reads the signal through a parameter with a default value or through `...args`, or that a wrapper hides behind a `length` of 0, is no longer given it, and runs to completion when its branch is cancelled, as a function that ignores the signal does; write it as `(signal) => ...`. A plain first parameter that a function treats as optional still takes the signal, as before.
+- **An `options` argument refuses a name it does not read.** `Retry`, `Parallel`, `recorder`, `recordEffect`, `replayEffect` and `timeTravel` ignored any other name, so a misspelt or borrowed one ran with the default and nothing said so: `Parallel(batch, { concurrency: 4 })`, the name p-limit uses, ran with no limit, `{ settle: true }` ran fail-fast so one bad record cancelled the batch, and `{ attemps: 5 }` got 3 attempts. Such a name now throws, naming it and the options the function reads; `Retry` and `Parallel` throw an `EffectTypeError` as the flow is built, the others a `TypeError`. TypeScript already refused most of them in an object literal written in the call. An option set to `undefined` is still accepted.
+- **The message for a step a trace lacks says what `onMissing: 'execute'` would run.** It advised `'execute'` where the Commands only read, so a replay that met a newly added lookup could run it that way, and every step after it, which had moved to a new path, ran live too. The message now says so, and advises `'execute'` only where every Command the flow can still reach goes to a test double or only reads.
+
+### Fixed
+
+- **An `onStep` hook that calls `op()` without awaiting it can no longer replace a Command's result with `undefined`.** A hook that returned `undefined` in place of the Command's value made the run reject, but the check ran as soon as the hook returned, while a Command that took any time was still running, so a found user still reached `next` as `undefined` and the flow took the branch for a missing one. The interpreter now waits for a Command the hook left running before it judges the step: the run rejects if the Command returned a value, a throw from it is an I/O fault, as it is for a hook that awaited `op`, and nothing is left running unobserved.
+- **`timeTravel` warns about unreached steps after a flow's own error named like a replay error.** It recognized its own replay errors by name, so a flow that ended on an error of its own named `ReplayError` or `TimeParadox` lost the warning about recorded steps it never reached. It now recognizes only the errors the library raises.
+
 ## [0.16.0] - 2026-10-01
 
 ### Added
@@ -223,6 +236,7 @@ All notable changes to pure-effect are recorded here. The format follows [Keep a
 
 - Initial release: `Success`, `Failure`, `Command`, `effectPipe`, and `runEffect`.
 
+[0.17.0]: https://github.com/aycangulez/pure-effect/compare/v0.16.0...v0.17.0
 [0.16.0]: https://github.com/aycangulez/pure-effect/compare/v0.15.0...v0.16.0
 [0.15.0]: https://github.com/aycangulez/pure-effect/compare/v0.14.0...v0.15.0
 [0.14.0]: https://github.com/aycangulez/pure-effect/compare/v0.13.0...v0.14.0

package/README.md

@@ -9,7 +9,7 @@
 - Inject context without touching function signatures
 - Built-in retry, plus parallel execution that cancels sibling branches on the first failure
 - OpenTelemetry-ready via lifecycle hooks
-- Zero dependencies, about 7 KB minified and gzipped
+- Zero dependencies, under 8 KB minified and gzipped
 - Works in JavaScript, and in TypeScript 5.1 or later (full generics, bundled `.d.ts`)
 
 ## Table of Contents
@@ -171,6 +171,8 @@ A flow does what `async`/`await` code does, as data. Instead of making a call an
 | a value from the request, such as the tenant | `Ask`; see [Passing Runtime Context](#passing-runtime-context) |
 | `Date.now()` or a random ID | a Command, so a replay gets the recorded value |
 
+One rule is behind every row. In `async` code, an `if` or a loop can have an `await` inside it. In a flow it can't: an `if` goes in a step or a Command's `next`, where the answer has already arrived, and a loop that makes calls becomes a `Parallel` or a `Retry`. So each decision lives in a small function of its own, which a test can call directly.
+
 The Quick Start's `registerUserFlow` is this function, translated row by row: each `await` became a Command, the code after it became that Command's `next`, and each `throw` became a `Failure`.
 
 ```js
@@ -205,6 +207,20 @@ assert.deepEqual(ensureEmailAvailable(input).next({ id: 1 }), Failure('Email alr
 
 This is what the small functions are for. Each step is a place a test can start, so a branch is tested by calling the step it lives in. An `async` function has one way in, so a test of any branch runs everything before it, with every call on the way replaced. The mocks can check one thing these tests 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. The function keeps its name and parameters, and its body runs the flow and turns a `Failure` back into a throw, so the code that calls it does not change. The mocked test above passes against this version too, so it checks the switch before the flow's own tests replace it:
+
+```js
+// Callers still await registerUserAsync and catch what it throws.
+async function registerUserAsync(input) {
+    const result = await runEffect(registerUserFlow(input));
+    // A step's Failure holds the error as written, here a string; a Command's function threw an Error.
+    if (result.type === 'Failure') throw result.error instanceof Error ? result.error : new Error(result.error);
+    return result.value;
+}
+
+await assert.rejects(registerUserAsync({ email: 'bad-email', password: '123' }), { message: 'Invalid email.' });
+```
+
 A loop is written in two parts: a step that gets the list, and a `Parallel` over it. `Parallel` runs a list of flows, at the same time unless told otherwise, and `limit: 1` makes it run them one after another, like 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:
 
 ```js
@@ -570,7 +586,7 @@ Bugs in the flow are not collected. An `EffectTypeError`, thrown for a malformed
 
 `limit` caps how many branches run at once; the rest start as others finish. Results and recorded paths stay in array order, so a limit changes only the pacing, and a trace recorded with a limit replays the same without one. A `limit` that is not a positive integer throws a `TypeError`.
 
-**Cancelling is a request, not a guarantee.** A cancelled branch starts no new Commands: a three-step branch whose first step is running when a sibling fails finishes that step and stops. To stop the running step itself, its function has to accept the `AbortSignal` it is given and pass it on to the I/O:
+**Cancelling is a request, not a guarantee.** A cancelled branch starts no new Commands: a three-step branch whose first step is running when a sibling fails finishes that step and stops. To stop the running step itself, its function has to take the `AbortSignal` as a parameter, written without a default value, and pass it on to the I/O:
 
 ```js
 // Cancellable: the request is aborted the moment a sibling branch fails.
@@ -737,8 +753,6 @@ Retry(
 | 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 |
-| an `onStep` hook threw after the Command's function succeeded | a bug | nothing; it is thrown, not returned | nothing |
-| an `onStep` hook returned `undefined` after the Command's function returned a value | a bug | nothing; it is thrown, not returned | nothing |
 
 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 treated as a bug: `runEffect` rejects with the thrown error instead of returning a `Failure`.
 
@@ -817,6 +831,8 @@ Timings are from Node 22 on a MacBook Pro with M4 Pro CPU:
 
 ## API Reference
 
+Every `options` argument below throws for a name it does not read, so a misspelt option fails instead of running with its default.
+
 ### Building blocks
 
 #### `Success(value)`
@@ -831,7 +847,7 @@ Returns `{ type: 'Failure', error, initialInput }`. Stops the pipeline immediate
 
 Returns `{ type: 'Command', cmd, next, meta }`.
 
-- `cmd`: the function, sync or async, that does the I/O. Inside a `Parallel` branch it gets an `AbortSignal` that fires when a sibling fails, and elsewhere no argument, so wrap a function that takes an optional first argument (see [Limitations](#limitations)).
+- `cmd`: the function, sync or async, that does the I/O. Inside a `Parallel` branch, a function that takes a parameter gets an `AbortSignal` in it that fires when a sibling fails; one with no parameters, or only parameters with default values, gets none, and so does every function outside a `Parallel` (see [Limitations](#limitations)).
 - `next`: receives `cmd`'s result and returns the next Effect; by default `(result) => Success(result)`.
 - `meta`: metadata passed to `onBeforeCommand`. A string `meta.name` names the Command.
 
@@ -931,7 +947,7 @@ remove();
 - `onRun(effect, pipeline, flowName)`: wraps the whole run. It must `await pipeline()` and return its result.
 - `onStep(name, type, op, path)`: wraps each Command, and each `Parallel` with `name` and `type` both `'Parallel'`. It must `await op()` and return its result, and pass `path` on to any hook it calls, since a replay matches steps on it.
     - For a Command, `op()` returns a promise, even for a synchronous function. Returning a value without calling `op()` answers for the Command, which is how replay works, and throwing without calling it counts as the Command failing.
-    - A throw after `op()` succeeded, or `undefined` returned in place of its value, as a hook that forgot its `return` does, is a bug in the hook: the run rejects, and `Retry` does not run the Command again.
+    - A throw after `op()` succeeded, or `undefined` returned in place of its value, as a hook that forgot its `return` or its `await` does, is a bug in the hook: the run rejects, and `Retry` does not run the Command again.
     - For a `Parallel`, `op()` runs the branches, so a hook must call it or the run rejects with a `TypeError`. It returns which branch, if any, cancelled the others, as in `{ cancelled: true, branch: 0 }`, even when a branch threw.
 - `onBeforeCommand(command, context)`: runs before each Command. A throw vetoes the Command: the run returns a `Failure` carrying the thrown error, and `Retry` does not retry it.
 
@@ -1033,8 +1049,8 @@ Replays a trace and narrates each step with its recorded duration, naming any re
 ## Limitations
 
 - **`Retry` repeats everything it wraps, including a Command's `next`.** When a Command's function throws, every Command inside the `Retry` runs again, including the ones that already succeeded. If a retried Command's `next` continues the flow, everything after it is retried too. Give a retried Command the default `next` and continue in a later pipeline step, or make sure every Command it reaches is safe to run more than once. A `Failure` a step returned is not retried at all, so a function that catches its own error and returns it as a value is never retried: see [Which Errors Are Data](#which-errors-are-data).
-- **Cancelling a `Parallel` branch cannot stop everything.** A cancelled branch starts no new Commands, and a function that uses the `AbortSignal` it is given can be stopped while running. A function that ignores the signal runs to completion, so a branch whose _first_ Command is a write can still write after another branch has failed. `Parallel` waits for every branch to finish before returning, so no cancelled work is still running after the `Failure` is returned.
-- **Inside a `Parallel`, a Command's function gets the `AbortSignal` as its first argument.** A function passed by name that has an optional first argument takes the signal for it, so the same Command behaves differently inside a `Parallel` than outside one: `Command(nanoid)` returns an empty ID, since `nanoid(size = 21)` reads the signal as the size, and a repository helper with a default page size gets the signal as its page size. Wrap such a function, as in `Command(() => nanoid())`. In TypeScript, a function whose first parameter cannot be an `AbortSignal` does not compile as a Command.
+- **Cancelling a `Parallel` branch cannot stop everything.** A cancelled branch starts no new Commands, and a function that uses the `AbortSignal` it is given can be stopped while running. A function that ignores the signal runs to completion, so a branch whose _first_ Command is a write can still write after another branch has failed. So does a function that is never given the signal: one written as `(...args)` or `({ signal } = {})`, or wrapped by a helper that hides its parameters. `Parallel` waits for every branch to finish before returning, so no cancelled work is still running after the `Failure` is returned.
+- **Inside a `Parallel`, a Command's function that takes a parameter gets the `AbortSignal` in it.** A function passed by name whose first parameter is optional but written without a default value takes the signal for it, so the same Command behaves differently inside a `Parallel` than outside one: `function listUsers(page) { page ??= 1; return db.users(page); }` gets the signal as its page. A parameter with a default value does not count, so `Command(nanoid)`, whose size is written `size = 21`, works everywhere. Wrap such a function, as in `Command(() => listUsers())`. In TypeScript, a function whose first parameter cannot be an `AbortSignal` does not compile as a Command.
 - **A `Failure` carries everything.** It holds the full error and the `initialInput` that `effectPipe` attached, and neither is trimmed, because tests and debugging need both. `redact` keeps sensitive data out of a **trace**. Keeping it out of your **logs** is up to you: log `result.error` rather than the whole `Failure`. The same goes for the outcomes a settled `Parallel` passes to `next`, which can carry their branch's input; for a login or registration flow, that input holds credentials.
 - **Replay checks the path, not the values.** Replaying an old trace cannot check a fix that changes what a flow computes, because every Command's result comes from the recording: the replay hands the step the value from before the fix, reports `Success`, and flags nothing. It can check a fix that changes which Commands run. A removed step shows up in `unreached` only if it was the last step the flow reached; removed from the middle, it shifts the later paths and the replay stops at a `TimeParadox`.
 - **A trace keeps data, not objects.** Recorded results come back without their classes: a money object or a database entity as a plain object, a `Buffer` as a plain byte array, and an error inside a result without properties such as `code`. Through JSON, a `Date` also comes back as a string and a `Map` as `{}`. A flow whose `next` calls a method on a result, or branches on one of those properties, replays differently from production. Return plain data from Commands; see [Recording in Production](#recording-in-production).

package/index.js

@@ -1,5 +1,20 @@
 // @ts-check
 
+// Contents. Each section is a `#region`, so an editor can fold it.
+//
+// 1. Types: the JSDoc shapes of the nodes a flow is made of.
+// 2. Building flows: the constructors; the checks, error messages and kinds of failure the later sections
+//    share; and `effectPipe`, with the `chain` that joins its steps.
+// 3. Configuration: the hook types and the library's defaults, `configureEffect` and its layers, and
+//    `chainHooks`, which merges them.
+// 4. Running flows: the helpers `Retry` and `Parallel` run on, the interpreter, and `runEffect`.
+// 5. Recording and replay: the trace format and replay errors, copying values and errors into a trace,
+//    `recorder`, built on `observeSteps`, and `recordEffect`, then `fromTrace`, `replayEffect` and `timeTravel`.
+//
+// A new definition goes in the section it serves, which is usually the one that calls it.
+
+// #region Types
+
 /** @typedef {{ type: 'Success', value: any, initialInput?: any }} SuccessState */
 /** @typedef {{ type: 'Failure', error: any, initialInput?: any }} FailureState */
 /**
@@ -55,6 +70,9 @@
  * @typedef {SuccessState | FailureState | CommandState | AskState | RetryState | ParallelState} Effect
  */
 
+// #endregion
+// #region Building flows
+
 /**
  * Represents a successful computation
  * @param {any} value - The result value
@@ -78,9 +96,9 @@ const Failure = (error, initialInput) => ({
  * Represents a side effect to be executed later.
  *
  * @param {(signal?: AbortSignal) => Promise<any>|any} cmd - The side-effect function to execute. Inside a
- *        `Parallel` branch it receives an `AbortSignal` that fires when a sibling branch fails, so I/O that
- *        accepts one can be cancelled in flight. Outside a `Parallel` no argument is passed. The signal is the
- *        first argument, so wrap a function that takes an optional one, as in `() => nanoid()`.
+ *        `Parallel` branch, a function that declares a parameter receives an `AbortSignal` in it that fires when a
+ *        sibling branch fails, so I/O that accepts one can be cancelled in flight. A parameter with a default value
+ *        does not count, so `nanoid(size = 21)` keeps its default. Outside a `Parallel` no argument is passed.
  * @param {(result: any) => Effect} [next] - Receives the result of `cmd` and returns the next Effect.
  *        Defaults to `(result) => Success(result)`, which is what most Commands want; `null` counts as omitted.
  * @param {CommandMeta} [meta] - Optional metadata, passed to `onBeforeCommand`. A string `meta.name`
@@ -164,6 +182,9 @@ const Retry = (effect, options) => {
         const hint = typeof options === 'number' ? `: write Retry(effect, { attempts: ${options} })` : '';
         throw malformed(`Retry's options must be an object, got ${describeArgument(options)}${hint}.`, options);
     }
+    rejectUnknownOptions(options, 'Retry', ['attempts', 'delay', 'backoff', 'onExhausted'], (m) =>
+        malformed(m, options)
+    );
     return { type: 'Retry', effect, options: options ?? {}, next: (value) => Success(value) };
 };
 
@@ -221,6 +242,7 @@ const Parallel = (effects, nextOrOptions, maybeOptions) => {
     if (options != null && !isOptionsObject(options)) {
         throw malformed(`Parallel's options must be an object, got ${describeArgument(options)}.`, options);
     }
+    rejectUnknownOptions(options, 'Parallel', ['limit', 'settled'], (m) => malformed(m, options));
     return {
         type: 'Parallel',
         effects,
@@ -255,6 +277,22 @@ const isFiniteNonNegative = (value) => Number.isFinite(value) && value >= 0;
  */
 const isOptionsObject = (value) => isObject(value) && !Array.isArray(value) && !isEffect(value);
 
+/**
+ * Refuses an option name a function does not read. A misspelt name, or one borrowed from another library, as
+ * `concurrency` is from p-limit, otherwise ran with the default and nothing to say so.
+ * @param {any} options
+ * @param {string} source - The function that takes them, as the message names it
+ * @param {string[]} known
+ * @param {(message: string) => Error} [raise] - Builds the error; a constructor's argument errors are EffectTypeErrors
+ */
+const rejectUnknownOptions = (options, source, known, raise = (message) => new TypeError(message)) => {
+    const name = isObject(options) ? Object.keys(options).find((key) => !known.includes(key)) : undefined;
+    if (name !== undefined) {
+        const list = `${known.slice(0, -1).join(', ')} and ${known[known.length - 1]}`;
+        throw raise(`${source} has no option named '${name}'; its options are ${list}.`);
+    }
+};
+
 /**
  * Describes a value for an error message, leading with the mistake it most likely is.
  * @param {any} value
@@ -448,7 +486,8 @@ const chain = (effect, fn, initialInput, from) => {
  * Composes a list of functions into a single Effect pipeline.
  * Each function receives the output of the previous one.
  *
- * @param {...(input: any) => Effect} fns - Functions that return Success, Failure, Command, or Ask.
+ * @param {...(input: any) => Effect} fns - Functions that each return an Effect: Success, Failure, Command, Ask,
+ *        Retry, or Parallel.
  * @returns {(start: any) => Effect} A function that accepts an initial input and returns the final Effect tree.
  */
 const effectPipe = (...fns) => {
@@ -471,6 +510,9 @@ const effectPipe = (...fns) => {
     };
 };
 
+// #endregion
+// #region Configuration
+
 /**
  * Wraps one Command execution, or one Parallel: `type` is 'Parallel', and `op` runs the branches and
  * returns the Parallel's decision, even when a branch threw, so a hook must call it. Only a replay passes
@@ -541,7 +583,8 @@ const applyLayers = () => {
  * Each call adds one layer on top of those already installed and returns a function that removes that
  * layer, wherever it sits by then. Layers merge the way several configurations passed to one call do:
  * `onStep` and `onRun` are wrappers, so they nest with the earliest layer outermost and the latest
- * closest to the Command; and `onBeforeCommand` interceptors all run, in the order installed. So these
+ * closest to the Command; and `onBeforeCommand` interceptors run in the order installed, the first to throw
+ * vetoing the Command. So these
  * are the same:
  *
  *     configureEffect(telemetryHooks(), recordingHooks({ sink }));
@@ -574,65 +617,13 @@ const configureEffect = (...configs) => {
     };
 };
 
-/**
- * @typedef {Object} StepStart
- * @property {string} name - The Command's identity: `meta.name`, else `cmd.name`, else 'anonymous'.
- * @property {string} type - 'Command', or 'Parallel' for a Parallel's decision.
- * @property {string} [path] - The Command's position in the Effect tree.
- */
-
-/**
- * @typedef {Object} StepEnd
- * @property {string} name
- * @property {string} type
- * @property {string} [path]
- * @property {any} [result] - What the Command returned, when it succeeded.
- * @property {any} [error] - What it threw, when it did not.
- * @property {number} durationMs
- */
-
-const now = () => (typeof performance === 'object' ? performance.now() : Date.now());
-
-/**
- * Wraps a step observer into an `onStep` that cannot change the run: `op` always runs, its result is
- * returned, its error propagates, and anything the observer throws is dropped.
- *
- * @param {(start: StepStart) => (end: StepEnd) => void} handler - Returns a finisher for the outcome
- * @returns {StepRunner}
- */
-const observeSteps = (handler) => async (name, type, op, path) => {
-    /** @type {((end: StepEnd) => void) | undefined} */
-    let finish;
-    try {
-        finish = handler({ name, type, path });
-    } catch {
-        finish = undefined;
-    }
-    const report = (/** @type {StepEnd} */ end) => {
-        try {
-            if (finish) finish(end);
-        } catch {
-            // Observation does not get to decide the outcome, so a broken observer is dropped.
-        }
-    };
-
-    const started = now();
-    try {
-        const result = await op();
-        report({ name, type, path, result, durationMs: now() - started });
-        return result;
-    } catch (error) {
-        report({ name, type, path, error, durationMs: now() - started });
-        throw error;
-    }
-};
-
 /**
  * Merges several configurations into one, so independent concerns can share the hooks.
  *
  * `onStep` and `onRun` are wrappers around an `op`, so they nest: the first config given is the
  * outermost and the last sits closest to the Command, so a thrown Command unwinds from the last back
- * to the first. `onBeforeCommand` is an observer, so every interceptor runs in the order given. A hook
+ * to the first. `onBeforeCommand` interceptors do not nest: they run in the order given, and the first to
+ * throw vetoes the Command, so the ones after it do not run. A hook
  * no config defines is left unset, so the caller keeps its default for that slot.
  *
  * @param {...(EffectConfiguration | undefined)} configs - Configurations to merge, outermost first
@@ -669,6 +660,9 @@ const chainHooks = (...configs) => {
     return merged;
 };
 
+// #endregion
+// #region Running flows
+
 /**
  * The Failure a cancelled `Parallel` branch stops with. Its error is named so it is never mistaken for
  * the failure that triggered the cancellation.
@@ -719,7 +713,8 @@ const asDecision = (value, branches) => {
 
 /**
  * Marks a step a replay reached that production never ran, in a branch a recorded decision cancelled.
- * The interpreter stops the branch there, as production did. Only `fromTrace` raises it.
+ * Only `fromTrace` raises it, and `runCommand` and `runParallel` catch it and stop the branch there, as
+ * production did.
  */
 const replayCut = Symbol('pure-effect.replayCut');
 
@@ -946,6 +941,7 @@ const interpret =
                 throw new TypeError(`Parallel 'limit' must be a positive integer, received ${describeValue(limit)}.`);
             // Cast rather than annotated, since only `op` assigns it.
             let run = /** @type {BranchRun | undefined} */ (undefined);
+            // A replay passes the recorded decision, from `replayEffect`'s onStep; a live run passes nothing.
             const op = async (/** @type {any} */ recorded) => {
                 run = await runBranches(parallel.effects, options, signal, branchPath, recorded);
                 return run.decision;
@@ -953,7 +949,7 @@ const interpret =
             try {
                 await localStepRunner('Parallel', 'Parallel', op, branchPath);
             } catch (e) {
-                // A replay found this Parallel inside a branch production had already stopped.
+                // A cut from `fromTrace`: a replay found this Parallel inside a branch production had already stopped.
                 if (hasMark(e, replayCut)) return cancelledBranch(parallel.initialInput);
                 throw e;
             }
@@ -988,7 +984,8 @@ const interpret =
          * @param {ParallelOptions} options
          * @param {AbortSignal | undefined} signal - The enclosing Parallel's cancellation, if any
          * @param {string} branchPath
-         * @param {any} recorded - The recorded decision, when a replay supplies one
+         * @param {any} recorded - The recorded decision, which `replayEffect`'s onStep passes to the Parallel's
+         *        `op`; undefined in a live run
          * @returns {Promise<BranchRun>}
          */
         async function runBranches(effects, options, signal, branchPath, recorded) {
@@ -999,10 +996,10 @@ const interpret =
             const pastTheEnd = Number.isInteger(recordedBranch) && recordedBranch >= effects.length;
             if (pastTheEnd) {
                 const count = effects.length === 1 ? '1 branch' : `${effects.length} branches`;
-                throw replayError(
-                    `Time paradox at path '${branchPath}': the recorded run was cancelled by branch ` +
-                        `${recordedBranch}, but this Parallel has ${count}.`,
-                    { name: 'TimeParadox', path: branchPath, branch: recordedBranch }
+                throw timeParadoxAt(
+                    `path '${branchPath}'`,
+                    `the recorded run was cancelled by branch ${recordedBranch}, but this Parallel has ${count}.`,
+                    { path: branchPath, branch: recordedBranch }
                 );
             }
             const forced = asDecision(recorded, effects.length);
@@ -1022,10 +1019,10 @@ const interpret =
                 const recordedTriggerSucceeded =
                     !thrown && forced.branch !== null && results[forced.branch].type === 'Success';
                 if (recordedTriggerSucceeded) {
-                    throw replayError(
-                        `Time paradox at path '${branchPath}': the recorded run was cancelled by ` +
-                            `branch ${forced.branch}, which did not fail in this replay.`,
-                        { name: 'TimeParadox', path: branchPath, branch: forced.branch }
+                    throw timeParadoxAt(
+                        `path '${branchPath}'`,
+                        `the recorded run was cancelled by branch ${forced.branch}, which did not fail in this replay.`,
+                        { path: branchPath, branch: forced.branch }
                     );
                 }
                 return { results, decision: forced, thrown };
@@ -1115,15 +1112,28 @@ const interpret =
             // What it returned, so a hook that loses it is caught.
             /** @type {unknown} */
             let value;
-            // The signal is passed only inside a Parallel. There it is still the first argument, so a function
-            // passed by name with an optional first parameter, `nanoid(size = 21)` say, takes the signal for it:
-            // a documented sharp edge. Async, so a hook always gets a promise, even from a synchronous function.
-            const op = async () => {
+            // The signal goes only to a function that declares a parameter for it, and only inside a Parallel. A
+            // parameter with a default value does not count toward `length`, so `nanoid(size = 21)` passed by name
+            // keeps its default rather than reading the signal as its size. A plain first parameter the function
+            // treats as optional still takes the signal: a documented sharp edge.
+            const takesSignal = signal !== undefined && cmd.length > 0;
+            // Async, so a hook always gets a promise, even from a synchronous function. The latest call is kept,
+            // with whether it is still running, so a hook that does not wait for it is caught.
+            /** @type {Promise<unknown> | undefined} */
+            let call;
+            let running = false;
+            const run = async () => {
                 succeeded = false;
-                value = await (signal ? cmd(signal) : cmd());
-                succeeded = true;
-                return value;
+                running = true;
+                try {
+                    value = await (takesSignal ? cmd(signal) : cmd());
+                    succeeded = true;
+                    return value;
+                } finally {
+                    running = false;
+                }
             };
+            const op = () => (call = run());
             try {
                 await localCommandInterceptor(command, context);
             } catch (e) {
@@ -1133,10 +1143,18 @@ const interpret =
             // Again, since an interceptor can wait (a rate limiter, say) while a sibling fails.
             if (signal?.aborted) return cancelledBranch(initialInput);
             let returned;
+            let unwaited = false;
             try {
                 returned = await localStepRunner(cmdName, 'Command', op, cmdPath);
+                // A hook that called `op` without waiting for it returned while the Command ran, so the check below
+                // would have nothing to check yet. Waiting here judges the step as though the hook had awaited `op`.
+                if (returned === undefined && running) {
+                    unwaited = true;
+                    await call;
+                }
             } catch (e) {
-                // A step production never ran, in a branch a Parallel cancelled: stop here, as production did.
+                // A cut from `fromTrace`: a step production never ran, in a branch a Parallel cancelled. Stop here,
+                // as production did.
                 if (hasMark(e, replayCut)) return cancelledBranch(initialInput);
                 if (hasMark(e, harnessError)) throw e;
                 // A hook threw after the function returned, which is a bug in the hook. A hook that throws
@@ -1149,8 +1167,9 @@ const interpret =
             // refused, so a hook that returns a copy of the result still works.
             if (returned === undefined && succeeded && value !== undefined) {
                 throw new TypeError(
-                    `An onStep hook called op for '${cmdName}' at path '${cmdPath}' and returned undefined, although ` +
-                        'the Command returned a value. A hook has to return what op returns.'
+                    `An onStep hook called op for '${cmdName}' at path '${cmdPath}' and returned undefined` +
+                        `${unwaited ? ' before op had finished' : ''}, although the Command returned a value. ` +
+                        'A hook has to await op() and return what it returns.'
                 );
             }
             return Success(returned);
@@ -1179,6 +1198,9 @@ const interpret =
  */
 const runEffect = (effect, context, callConfig) => interpret(effect, context, callConfig);
 
+// #endregion
+// #region Recording and replay
+
 /**
  * The step a replay is asking about. `path` is the Command's position in the Effect tree and is stable
  * across runs; `index` is its position in this run's completion order, which is not stable for a flow
@@ -1244,25 +1266,32 @@ const replayError = (message, props = {}) =>
     );
 
 /**
- * Signals that the flow being replayed asked for a different Command than the trace
- * recorded, which means the code has diverged from the recorded run.
+ * Builds a `TimeParadox`: the replay reached a point where the flow no longer matches its recording, which
+ * means the code has diverged from the recorded run.
+ * @param {string} at - Where, as the message names it
+ * @param {string} detail - How the flow and the recording disagree
+ * @param {Object} props - The fields that locate it, such as `path`
+ * @returns {Error}
+ */
+const timeParadoxAt = (at, detail, props) =>
+    replayError(`Time paradox at ${at}: ${detail}`, { name: 'TimeParadox', ...props });
+
+/**
+ * Signals that the flow being replayed asked for a different Command than the trace recorded.
  * @param {ReplayStep} step - The step the flow asked for
  * @param {string} recorded - The command name the trace holds at that position
  * @returns {Error}
  */
 const timeParadox = (step, recorded) =>
-    replayError(
-        `Time paradox at ${step.path !== undefined ? `path '${step.path}'` : `step ${step.index}`}: ` +
-            `flow asked for '${step.name}', trace recorded '${recorded}'`,
-        {
-            name: 'TimeParadox',
-            index: step.index,
-            path: step.path,
-            expected: recorded,
-            actual: step.name
-        }
+    timeParadoxAt(
+        step.path !== undefined ? `path '${step.path}'` : `step ${step.index}`,
+        `flow asked for '${step.name}', trace recorded '${recorded}'`,
+        { index: step.index, path: step.path, expected: recorded, actual: step.name }
     );
 
+/** The keys `serializeError` carries whatever their enumerability, which a native Error sets as hidden. */
+const carriedKeys = ['name', 'message', 'cause'];
+
 /**
  * Converts a thrown value into something JSON can carry. `message` and `stack` are
  * non-enumerable on Error, so a plain `JSON.stringify` would silently drop them.
@@ -1301,9 +1330,6 @@ const serializeError = (e, withStack, ancestors = new Set()) => {
     return out;
 };
 
-/** The keys `serializeError` carries whatever their enumerability, which a native Error sets as hidden. */
-const carriedKeys = ['name', 'message', 'cause'];
-
 /**
  * Rebuilds an Error from `serializeError` output. Non-Error values pass through, so a
  * Command that rejected with a string still replays as a string.
@@ -1409,15 +1435,70 @@ const snapshot = (value) => {
 };
 
 /**
- * Builds an `onStep` hook that records what every Command returned, plus a packager
- * for the reference trace format. Pass `onStep` to `runEffect` as per-call config. A recorder holds the steps
- * of every run it sees, so installed with `configureEffect` for a whole application it mixes requests into one
- * trace with duplicate paths, which a replay refuses; examples/recording-example.js gives each run its own.
+ * @typedef {Object} StepStart
+ * @property {string} name - The Command's identity: `meta.name`, else `cmd.name`, else 'anonymous'.
+ * @property {string} type - 'Command', or 'Parallel' for a Parallel's decision.
+ * @property {string} [path] - The Command's position in the Effect tree.
+ */
+
+/**
+ * @typedef {Object} StepEnd
+ * @property {string} name
+ * @property {string} type
+ * @property {string} [path]
+ * @property {any} [result] - What the Command returned, when it succeeded.
+ * @property {any} [error] - What it threw, when it did not.
+ * @property {number} durationMs
+ */
+
+const now = () => (typeof performance === 'object' ? performance.now() : Date.now());
+
+/**
+ * Wraps a step observer into an `onStep` that cannot change the run: `op` always runs, its result is
+ * returned, its error propagates, and anything the observer throws is dropped.
+ *
+ * @param {(start: StepStart) => (end: StepEnd) => void} handler - Returns a finisher for the outcome
+ * @returns {StepRunner}
+ */
+const observeSteps = (handler) => async (name, type, op, path) => {
+    /** @type {((end: StepEnd) => void) | undefined} */
+    let finish;
+    try {
+        finish = handler({ name, type, path });
+    } catch {
+        finish = undefined;
+    }
+    const report = (/** @type {StepEnd} */ end) => {
+        try {
+            if (finish) finish(end);
+        } catch {
+            // Observation does not get to decide the outcome, so a broken observer is dropped.
+        }
+    };
+
+    const started = now();
+    try {
+        const result = await op();
+        report({ name, type, path, result, durationMs: now() - started });
+        return result;
+    } catch (error) {
+        report({ name, type, path, error, durationMs: now() - started });
+        throw error;
+    }
+};
+
+/**
+ * Builds an `onStep` hook that records every Command's result or error and every Parallel's decision, plus
+ * a packager for the reference trace format. Pass `onStep` to `runEffect` as per-call config. A recorder holds
+ * the steps of every run it sees, so installed with `configureEffect` for a whole application it mixes requests
+ * into one trace with duplicate paths, which a replay refuses; examples/recording-example.js gives each run its
+ * own.
  *
  * @param {RecorderOptions} [options] - Redaction and size limits
  * @returns {{ onStep: StepRunner, entries: TraceEntry[], toTrace: (meta?: TraceMeta) => TraceLog }}
  */
 const recorder = (options = {}) => {
+    rejectUnknownOptions(options, 'recorder', ['redact', 'maxEntries', 'stack']);
     const { redact = (/** @type {any} */ r) => r, maxEntries = Infinity, stack = false } = options;
     /** @type {TraceEntry[]} */
     const entries = [];
@@ -1493,6 +1574,7 @@ const recorder = (options = {}) => {
  * @returns {Promise<{ result: SuccessState | FailureState, trace: TraceLog }>}
  */
 const recordEffect = async (flowFn, initialInput, options = {}) => {
+    rejectUnknownOptions(options, 'recordEffect', ['context', 'version', 'redact', 'maxEntries', 'stack']);
     const { context = {}, version, ...recorderOptions } = options;
     const rec = recorder(recorderOptions);
     // Packaged before the run, so a Command that writes to the input or the context, as an ORM save
@@ -1583,7 +1665,8 @@ const fromTrace = (traceLog, options = {}) => {
         /** Recorded Parallel decisions that cancelled branches, by the Parallel's path. */
         const cancellations = entries.filter(isDecisionEntry).filter((e) => e.result?.cancelled === true);
         // A missing step is where production stopped a branch when it lies in a branch a recorded decision
-        // cancelled: any branch but the cancelling one, or every branch of a Parallel cancelled from outside.
+        // cancelled: any branch but the cancelling one, or every branch of a Parallel cancelled from outside. Such a
+        // step throws a cut, which `runCommand` or `runParallel` catches to stop the branch.
         const stoppedInProduction = (/** @type {string | undefined} */ stepPath) =>
             typeof stepPath === 'string' &&
             cancellations.some((e) => {
@@ -1595,7 +1678,8 @@ const fromTrace = (traceLog, options = {}) => {
         const resolve = (step) => {
             const entry = byPath.get(step.path);
             if (step.type === 'Parallel') {
-                // A decision rather than I/O. With none recorded, the Parallel replays under timing.
+                // A decision rather than I/O. `replayEffect` hands a recorded one to the Parallel's `op`, and
+                // `runBranches` reproduces it; with none recorded, the Parallel replays under timing.
                 if (entry && entry.command !== 'Parallel') throw timeParadox(step, entry.command);
                 if (entry) return resolveEntry(entry);
                 if (stoppedInProduction(step.path)) throw replayCutError(/** @type {string} */ (step.path));
@@ -1635,6 +1719,35 @@ const fromTrace = (traceLog, options = {}) => {
     return { resolve, missing };
 };
 
+/**
+ * The error for a step a replay has no recorded outcome for, which it refuses to run live.
+ * @param {ReplayStep} step
+ * @param {((step: ReplayStep) => string) | undefined} describe - `fromTrace`'s `missing`; a Resolver has none
+ * @param {number} droppedEntries - How many entries the trace dropped under `maxEntries`
+ * @returns {Error}
+ */
+const missingStepError = (step, describe, droppedEntries) => {
+    const what = describe ? describe(step) : `No recorded outcome for '${step.name}' at step ${step.index}`;
+    // Why the step may be missing decides the fix. A capped trace needs a higher cap, since the step may be one
+    // production ran; any other missing step may be one production never ran, and running it live against
+    // production would do I/O production refused.
+    const why =
+        droppedEntries > 0
+            ? `The trace dropped ${droppedEntries} entries under maxEntries, so production may have run ` +
+              'this step and the recorder not kept it; record the flow with a higher maxEntries to ' +
+              'replay past it.'
+            : 'Production may never have run it: a Command an onBeforeCommand hook vetoed leaves no ' +
+              'entry, and neither does a step added since the recording or one the flow reaches now that ' +
+              "it did not then. onMissing: 'execute' runs such a step for real, and after an added step " +
+              'every step that follows it, since they all move to new paths, so pass it only where every ' +
+              'Command the flow can still reach goes to a test double or only reads.';
+    return replayError(`${what}; refusing to run the real Command. ${why}`, {
+        command: step.name,
+        index: step.index,
+        path: step.path
+    });
+};
+
 /**
  * @typedef {Object} ReplayOptions
  * @property {any} [context] - Context for `Ask`; defaults to the context a trace recorded.
@@ -1685,6 +1798,7 @@ const fromTrace = (traceLog, options = {}) => {
  */
 // `async` so a malformed trace arrives as a rejection rather than a synchronous throw.
 const replayEffect = async (effect, traceOrResolver, options = {}) => {
+    rejectUnknownOptions(options, 'replayEffect', ['context', 'fastRetry', 'hooks', 'onMissing', 'onResolved']);
     const { fastRetry = true, hooks = false, onMissing = 'throw', onResolved } = options;
     // A trace is data and a Resolver is a function, so nothing else is needed to tell them
     // apart, including the bare entries array that `fromTrace` also accepts.
@@ -1719,7 +1833,7 @@ const replayEffect = async (effect, traceOrResolver, options = {}) => {
     /** @type {StepRunner} */
     const onStep = async (name, type, op, path) => {
         if (type === 'Parallel') {
-            // A Parallel's step carries its recorded decision into `op`, which runs the branches under it.
+            // A Parallel's step carries its recorded decision into `op`, where `runBranches` reproduces it.
             // It is not a Command: `index` still counts Commands, and `onResolved` still sees only them.
             const outcome = resolve({ index, name, type, path });
             return await op(outcome && 'result' in outcome ? outcome.result : undefined);
@@ -1735,24 +1849,7 @@ const replayEffect = async (effect, traceOrResolver, options = {}) => {
             }
         }
         if (outcome === undefined) {
-            if (onMissing !== 'execute') {
-                const what = missing ? missing(step) : `No recorded outcome for '${name}' at step ${step.index}`;
-                // Why the step may be missing decides the fix. A capped trace needs a higher cap, since the step
-                // may be one production ran; any other missing step may be one production never ran, and
-                // running it live against production would do I/O production refused.
-                const why = capped
-                    ? `The trace dropped ${droppedEntries} entries under maxEntries, so production may have run ` +
-                      'this step and the recorder not kept it; record the flow with a higher maxEntries to ' +
-                      'replay past it.'
-                    : 'Production may never have run it: a Command an onBeforeCommand hook vetoed leaves no ' +
-                      "entry, and neither does a step added since the recording. onMissing: 'execute' runs such " +
-                      'steps for real, so pass it only where the Commands reach test doubles or only read.';
-                throw replayError(`${what}; refusing to run the real Command. ${why}`, {
-                    command: name,
-                    index: step.index,
-                    path
-                });
-            }
+            if (onMissing !== 'execute') throw missingStepError(step, missing, droppedEntries);
             return await op();
         }
         if ('error' in outcome) throw outcome.error;
@@ -1795,6 +1892,7 @@ const replayEffect = async (effect, traceOrResolver, options = {}) => {
  *          a caller who wants the unreached entries as data uses `replayEffect`.
  */
 const timeTravel = async (flowFn, traceLog, options = {}) => {
+    rejectUnknownOptions(options, 'timeTravel', ['log', 'context', 'version']);
     const { log = console.log, context, version } = options;
     const { initialInput, trace, flowName, version: traceVersion } = traceLog;
     // `message` is non-enumerable on Error, so JSON.stringify alone would drop it. JSON.stringify throws on
@@ -1857,8 +1955,9 @@ const timeTravel = async (flowFn, traceLog, options = {}) => {
     log(`Replay finished with state: ${result.type}`);
     log(result.type === 'Failure' ? `Error: ${format(result.error)}` : `Result: ${format(result.value)}`);
     // After a replay error the flow never got past the divergence, and the error already names where it
-    // split. Only a flow that ended on its own terms with steps left over is worth a warning.
-    const haltedByReplay = result.type === 'Failure' && /^(TimeParadox|ReplayError)$/.test(result.error?.name);
+    // split. Only a flow that ended on its own terms with steps left over is worth a warning. Told by the
+    // mark rather than the name, which a flow's own error can share.
+    const haltedByReplay = result.type === 'Failure' && hasMark(result.error, replayFault);
     if (unreached.length > 0 && !haltedByReplay) {
         // Named, not just counted: the step a fix stopped issuing is usually the one under suspicion.
         const names = unreached.map((e) => (hasPath(e) ? `${e.command} (path '${e.path}')` : e.command));
@@ -1868,6 +1967,8 @@ const timeTravel = async (flowFn, traceLog, options = {}) => {
     return result;
 };
 
+// #endregion
+
 export {
     Success,
     Failure,

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "pure-effect",
-    "version": "0.16.0",
+    "version": "0.17.0",
     "description": "Records what your business logic did in production and replays it anywhere: time-travel debugging for JavaScript and TypeScript, with zero dependencies. Business logic is plain data you can test without mocks.",
     "keywords": [
         "effect",
@@ -31,7 +31,7 @@
         "test": "mocha && tsd && tsc -p jsconfig.json",
         "test:ts-minimum": "npx --yes -p typescript@5.1 tsc -p test/tsconfig.minimum.json",
         "generate": "node scripts/effect-pipe-overloads.js",
-        "format": "prettier --write index.js index.d.ts examples/*.js scripts/*.js test/all.js test/types.test-d.ts README.md CLAUDE.md CHANGELOG.md CONTRIBUTING.md"
+        "format": "prettier --write index.js index.d.ts examples/*.js scripts/*.js test/all.js test/types.test-d.ts README.md CLAUDE.md DESIGN.md CHANGELOG.md CONTRIBUTING.md"
     },
     "tsd": {
         "directory": "test"