pure-effect 0.14.0 → 0.16.0

package/index.js

@@ -79,36 +79,49 @@ const Failure = (error, initialInput) => ({
  *
  * @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. Ignoring it is fine: the interpreter still refuses to start
- *        any later Command in a cancelled branch. Outside a `Parallel` no argument is passed.
+ *        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()`.
  * @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.
+ *        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`
- *        becomes this Command's identity for traces, replay matching, and telemetry spans, which makes
- *        the identity independent of how `cmd` was declared and immune to minification.
+ *        becomes this Command's identity for traces, replay matching, and telemetry spans.
  * @returns {CommandState}
  */
-const Command = (cmd, next = (/** @type {any} */ result) => Success(result), meta) => ({
-    type: 'Command',
-    cmd,
-    next,
-    meta
-});
+const Command = (cmd, next, meta) => {
+    // Checked as the flow is built, so a mistake is reported before the I/O it would have run.
+    if (typeof cmd !== 'function') {
+        throw malformed(
+            /** @type {any} */ (cmd) instanceof Promise
+                ? 'Command expects a function, got a Promise.'
+                : `Command expects the function that does the I/O, got ${describeArgument(cmd)}.`,
+            cmd
+        );
+    }
+    if (next != null && typeof next !== 'function') {
+        throw malformed(
+            isOptionsObject(next)
+                ? "Command's second argument is next, and meta goes third: Command(fn, undefined, { name: 'chargeCard' })."
+                : `Command's next must be a function, got ${describeArgument(next)}.`,
+            next
+        );
+    }
+    return { type: 'Command', cmd, next: next ?? ((/** @type {any} */ result) => Success(result)), meta };
+};
 
 /**
  * The name a Command is known by: what a trace records, what replay matches on, and what a
- * telemetry span is called.
- *
- * `meta.name` wins when it is a non-empty string. Otherwise the identity is the thunk's own `name`,
- * so an inline arrow records as 'anonymous' and a minifier that mangles function names silently
- * renames every step of every trace. Passing `meta.name` avoids both.
+ * telemetry span is called. A non-empty string `meta.name`, else `cmd.name`, else 'anonymous'.
+ * Exported so a test walking a flow checks each step by the same rule.
  *
  * @param {CommandState} eff
  * @returns {string}
  */
 const commandName = (eff) => {
+    if (eff?.type !== 'Command') {
+        throw malformed(`commandName expects a Command, got ${describeArgument(eff)}.`, eff);
+    }
     const meta = eff.meta;
-    const named = meta && typeof meta === 'object' ? meta.name : undefined;
+    const named = isObject(meta) ? meta.name : undefined;
     return typeof named === 'string' && named !== '' ? named : eff.cmd.name || 'anonymous';
 };
 
@@ -117,7 +130,12 @@ const commandName = (eff) => {
  * @param {(context: any) => Effect} next - Receives the context and returns the next Effect
  * @returns {AskState}
  */
-const Ask = (next) => ({ type: 'Ask', next });
+const Ask = (next) => {
+    if (typeof next !== 'function') {
+        throw malformed(`Ask expects a function that receives the context, got ${describeArgument(next)}.`, next);
+    }
+    return { type: 'Ask', next };
+};
 
 /**
  * Wraps an Effect tree with retry-on-failure semantics.
@@ -128,87 +146,149 @@ const Ask = (next) => ({ type: 'Ask', next });
  * every Command in it is idempotent.
  *
  * @param {Effect} effect - The inner Effect tree to retry
- * @param {Object} [options] - Retry options, merged over the library defaults at runtime; there are no
- *        configured defaults, since how a dependency misbehaves is a property of that dependency
- * @param {number} [options.attempts] - Max retries (not counting first try)
- * @param {number} [options.delay] - Ms before first retry
- * @param {number} [options.backoff] - Multiplier applied to delay on each subsequent retry
+ * @param {Object} [options] - Retry options, merged over the library defaults at runtime. An option set to
+ *        `undefined` keeps its default, as an absent config key does.
+ * @param {number} [options.attempts] - Max retries (not counting first try), a positive integer
+ * @param {number} [options.delay] - Ms before first retry, a finite number of 0 or more
+ * @param {number} [options.backoff] - Multiplier applied to delay on each subsequent retry, a finite number
+ *        of 0 or more
  * @param {(error: any) => Effect} [options.onExhausted] - Runs a fallback Effect when every attempt has
  *        failed, receiving `{ retryExhausted, lastError, attempts }`. The fallback's success feeds `next`
- *        exactly as the primary's would have; its failure propagates unwrapped. Per-use only, never a
- *        global default, and a fallback never starts in a `Parallel` branch a sibling has cancelled.
+ *        exactly as the primary's would have; its failure propagates unwrapped. A fallback never starts
+ *        in a `Parallel` branch a sibling has cancelled.
  * @returns {RetryState}
  */
-const Retry = (effect, options = {}) => ({
-    type: 'Retry',
-    effect,
-    options,
-    next: (value) => Success(value)
-});
+const Retry = (effect, options) => {
+    if (!isEffect(effect)) throw malformed(`Retry expects the Effect to run, got ${describeValue(effect)}.`, effect);
+    if (options != null && !isOptionsObject(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);
+    }
+    return { type: 'Retry', effect, options: options ?? {}, next: (value) => Success(value) };
+};
 
 /**
  * Runs multiple Effect trees concurrently. The first branch to fail cancels its siblings, and that
  * branch's Failure is what the Parallel returns; `next` is skipped. Which branch fails first depends on
  * timing, so it is recorded, and a replay returns the same one.
  *
- * Cancellation is cooperative and works at two levels. A cancelled branch starts no further Commands,
- * which needs nothing from the caller. Stopping the Command already in flight needs its thunk to accept
- * the `AbortSignal` it is passed and hand it to whatever performs the I/O; a thunk that ignores the
+ * A cancelled branch starts no further Commands. Stopping the Command already in flight needs its
+ * function to pass the `AbortSignal` it receives to whatever performs the I/O; one that ignores the
  * signal runs to completion, so a branch's first Command can still write after a sibling has failed.
  *
  * `settled: true` turns off that first-failure rule: every branch runs to completion and `next`
- * receives the branch outcomes themselves, `Success` and `Failure` nodes in array order, so one
- * record's failure cannot abort a batch. An `EffectTypeError` still escapes, because a malformed flow
- * is a bug rather than a branch outcome. `limit: n` keeps at most `n` branches in flight, for a
- * resource that rate limits; results and paths stay in array order either way.
+ * receives the branch outcomes, `Success` and `Failure` nodes in array order. An `EffectTypeError`
+ * still escapes. `limit: n` keeps at most `n` branches in flight. Results and paths stay in array
+ * order either way.
  *
  * The second argument is the `next` function or the options, whichever it looks like, so
- * `Parallel(effects, { limit: 5 })` needs no placeholder.
+ * `Parallel(effects, { limit: 5 })` needs no placeholder. `undefined` or `null` there is a skipped `next`,
+ * so `Parallel(effects, undefined, { limit: 5 })` still reads the options.
  *
  * @param {Effect[]} effects - Array of Effect trees to run concurrently
- * @param {((values: any[]) => Effect) | ParallelOptions} [nextOrOptions] - Receives array of success
+ * @param {((values: any[]) => Effect) | ParallelOptions | null} [nextOrOptions] - Receives array of success
  *        values in order and returns the next Effect, or the options. `next` defaults to
  *        `(values) => Success(values)`, same as `Command`'s default.
- * @param {ParallelOptions} [maybeOptions] - Options, when `next` was given
+ * @param {ParallelOptions} [maybeOptions] - Options, when `next` was given or skipped
  * @returns {ParallelState}
  */
 const Parallel = (effects, nextOrOptions, maybeOptions) => {
+    if (!Array.isArray(effects)) {
+        throw malformed(`Parallel expects an array of Effects, got ${describeArgument(effects)}.`, effects);
+    }
+    effects.forEach((branch, i) => {
+        if (!isEffect(branch)) throw malformed(`Parallel's branch ${i} is ${describeValue(branch)}.`, branch);
+    });
     const hasNext = typeof nextOrOptions === 'function';
+    // A caller forwarding an absent `next` still passes its options third, as the signature reads.
+    const nextSkipped = nextOrOptions == null;
+    const optionsSecond = !hasNext && !nextSkipped;
+    if (optionsSecond && !isOptionsObject(nextOrOptions)) {
+        const got = describeArgument(nextOrOptions);
+        throw malformed(`Parallel's second argument must be next or the options, got ${got}.`, nextOrOptions);
+    }
+    // Nothing reads a third argument after the options, so a `next` passed there would silently be skipped.
+    if (optionsSecond && maybeOptions != null) {
+        throw malformed(
+            typeof maybeOptions === 'function'
+                ? "Parallel's next goes second and its options third: Parallel(effects, next, options)."
+                : `Parallel takes one options object, and with the options second its third argument, ` +
+                      `${describeArgument(maybeOptions)}, would be ignored.`,
+            maybeOptions
+        );
+    }
+    const options = optionsSecond ? nextOrOptions : maybeOptions;
+    if (options != null && !isOptionsObject(options)) {
+        throw malformed(`Parallel's options must be an object, got ${describeArgument(options)}.`, options);
+    }
     return {
         type: 'Parallel',
         effects,
         next: hasNext ? nextOrOptions : (/** @type {any[]} */ values) => Success(values),
-        options: (hasNext ? maybeOptions : nextOrOptions) ?? {}
+        options: options ?? {}
     };
 };
 
+/**
+ * Whether a value is an object that can carry properties: not `null`, a primitive, or a function.
+ * @param {any} value
+ * @returns {boolean}
+ */
+const isObject = (value) => value !== null && typeof value === 'object';
+
+/**
+ * @param {any} value
+ * @returns {boolean}
+ */
+const isPositiveInteger = (value) => Number.isInteger(value) && value >= 1;
+
+/**
+ * @param {any} value
+ * @returns {boolean}
+ */
+const isFiniteNonNegative = (value) => Number.isFinite(value) && value >= 0;
+
+/**
+ * An object that can hold options or meta: not an array, and not an Effect passed in the wrong place.
+ * @param {any} value
+ * @returns {boolean}
+ */
+const isOptionsObject = (value) => isObject(value) && !Array.isArray(value) && !isEffect(value);
+
 /**
  * Describes a value for an error message, leading with the mistake it most likely is.
  * @param {any} value
  * @returns {string}
  */
-const describeValue = (value) =>
-    value === undefined
-        ? 'undefined, which usually means a missing return'
-        : value === null
-          ? 'null'
-          : value instanceof Promise
-            ? 'a Promise, which usually means an async function'
-            : typeof value === 'function'
-              ? 'a function, which usually means a flow was passed without being called with its input'
-              : typeof value === 'object'
-                ? typeof value.type === 'string'
-                    ? `an object with an unrecognised type '${value.type}'`
-                    : 'a plain object'
-                : `the ${typeof value} ${JSON.stringify(value)}`;
-
-/**
- * Marks an error as the harness failing rather than the flow. The interpreter rethrows anything
- * carrying it instead of folding it into a `Failure`, which keeps it out of reach of everything that
- * legitimately handles a domain failure: a Command's `next`, `Retry`'s `onExhausted`, and the outcomes
- * a settled `Parallel` collects. A malformed flow and a trace that cannot answer a step are both this
- * kind of error, and a new one gets the mark rather than a new name for the interpreter to know about.
- * Non-enumerable, so it cannot show up in a serialized error or upset a `deepEqual` on an outcome.
+const describeValue = (value) => {
+    if (value === undefined) return 'undefined, which usually means a missing return';
+    if (value === null) return 'null';
+    if (value instanceof Promise) return 'a Promise, which usually means an async function';
+    if (typeof value === 'function')
+        return 'a function, which usually means a flow was passed without being called with its input';
+    // `String`, since `JSON.stringify` prints NaN and Infinity as null and throws on a BigInt.
+    if (typeof value !== 'object') {
+        return `the ${typeof value} ${typeof value === 'string' ? JSON.stringify(value) : String(value)}`;
+    }
+    if (typeof value.type === 'string') return `an object with an unrecognised type '${value.type}'`;
+    return 'a plain object';
+};
+
+/**
+ * Describes a constructor's argument for an error message. A missing one is usually a misspelt name
+ * rather than a missing return, and an Effect in the wrong place is named by its type.
+ * @param {any} value
+ * @returns {string}
+ */
+const describeArgument = (value) =>
+    value === undefined ? 'undefined' : isEffect(value) ? `an Effect of type '${value.type}'` : describeValue(value);
+
+/**
+ * Marks an error as the harness failing rather than the flow: a malformed flow, or a trace that cannot
+ * answer a step. The interpreter rethrows anything carrying it instead of folding it into a `Failure`, so
+ * nothing that handles a domain failure can absorb it. A new kind of harness error gets this mark rather
+ * than a name the interpreter has to know. Non-enumerable, so it never shows up in a serialized error or
+ * a `deepEqual`.
  */
 const harnessError = Symbol('pure-effect.harnessError');
 
@@ -219,11 +299,17 @@ const harnessError = Symbol('pure-effect.harnessError');
 const asHarnessError = (error) => Object.defineProperty(error, harnessError, { value: true });
 
 /**
- * An I/O fault: a Command's function threw, or a `Retry` ran out of attempts, rather than the flow
- * deciding to stop. `Retry` acts on this and not on a `Failure` a step returned, which is an abort.
- * Internal: only `execute` returns one, and it becomes a plain `Failure` wherever it would reach user
- * code, at the `runEffect` boundary and in a settled `Parallel`'s outcomes. So whatever a step returns
- * is an abort, and no object a caller holds carries provenance it could keep or lose by accident.
+ * Whether a thrown value carries one of the library's marks: `harnessError`, `replayCut`, or `replayFault`.
+ * @param {unknown} e
+ * @param {symbol} mark
+ * @returns {boolean}
+ */
+const hasMark = (e, mark) => Boolean(e && /** @type {any} */ (e)[mark]);
+
+/**
+ * An I/O fault: a Command's function threw, or a `Retry` ran out of attempts. `Retry` retries this, never a
+ * `Failure` a step returned, which is an abort. Internal: only `execute` and its per-node functions return
+ * one, and `asOutcome` turns it into a plain `Failure` before it reaches user code.
  * @typedef {{ type: 'IoFault', error: any, initialInput?: any }} IoFaultState
  */
 
@@ -241,33 +327,66 @@ const IoFault = (error, initialInput) => ({ type: 'IoFault', error, initialInput
 const asOutcome = (state) => (state.type === 'IoFault' ? Failure(state.error, state.initialInput) : state);
 
 /**
- * Checks that a value is an Effect, and explains the mistake when it is not.
+ * Builds an `EffectTypeError`, for a malformed flow: a step or continuation that returned something other
+ * than an Effect, or a constructor given an argument it cannot use. It is a harness error: a malformed flow
+ * is a bug, so it is thrown rather than becoming a `Failure`.
  *
- * `EffectTypeError` is a bug in the flow rather than a domain failure, so it is thrown instead of
- * becoming a `Failure`, and the interpreter rethrows it rather than folding it into one.
+ * @param {string} message
+ * @param {any} value - The malformed value
+ * @returns {Error}
+ */
+const malformed = (message, value) => {
+    // This error already reports the bug, so the Promise rejecting must not also crash the process as
+    // unhandled. Only a native Promise: calling `then` on a Knex or Mongoose query builder runs the query.
+    if (value instanceof Promise) value.catch(() => {});
+    return asHarnessError(Object.assign(new Error(message), { name: 'EffectTypeError' }));
+};
+
+/**
+ * Builds the error for a value that is not an Effect, explaining the likely mistake.
  *
  * @param {any} value
  * @param {string} source - What produced the value, named where it is known
  * @returns {Error}
  */
-const effectTypeError = (value, source) => {
-    const isPromise = value instanceof Promise;
-    // This error already reports the bug, so a rejection of the same Promise must not also crash the
-    // process as unhandled after the caller has caught it. Only a native Promise, which is what an async
-    // function returns: calling `then` on a query builder from Knex or Mongoose runs the query.
-    if (isPromise) value.catch(() => {});
-    return asHarnessError(
-        Object.assign(
-            new Error(
-                `${source} returned ${describeValue(value)}. Return Success, Failure, Command, Ask, Retry, or Parallel: ` +
-                    (isPromise
-                        ? 'a step cannot be async, so do the awaited work in a Command and continue in its next.'
-                        : 'a plain value has to be wrapped, as in Success(value).')
-            ),
-            { name: 'EffectTypeError' }
-        )
+const effectTypeError = (value, source) =>
+    malformed(
+        `${source} returned ${describeValue(value)}. Return Success, Failure, Command, Ask, Retry, or Parallel: ` +
+            (value instanceof Promise
+                ? 'a step cannot be async, so do the awaited work in a Command and continue in its next.'
+                : 'a plain value has to be wrapped, as in Success(value).'),
+        value
     );
-};
+
+/**
+ * Names the node whose `next` returned a value, for an error message: a Command by its name, any other by its type.
+ * @param {Effect} node
+ * @returns {string}
+ */
+const nextOf = (node) =>
+    node.type === 'Command'
+        ? `The next of Command '${commandName(node)}'`
+        : `The next of ${node.type === 'Ask' ? 'an' : 'a'} ${node.type}`;
+
+/**
+ * A Success or a Failure: a flow with nothing left to run.
+ * @param {any} value
+ * @returns {value is SuccessState | FailureState}
+ */
+const isOutcome = (value) => ['Success', 'Failure'].includes(value?.type);
+
+/**
+ * A Command, Ask, Retry, or Parallel: a flow the interpreter still has work to do on.
+ * @param {any} value
+ * @returns {value is CommandState | AskState | RetryState | ParallelState}
+ */
+const isPending = (value) => ['Command', 'Ask', 'Retry', 'Parallel'].includes(value?.type);
+
+/**
+ * @param {any} value
+ * @returns {value is Effect}
+ */
+const isEffect = (value) => isOutcome(value) || isPending(value);
 
 /**
  * @param {any} value
@@ -275,7 +394,7 @@ const effectTypeError = (value, source) => {
  * @returns {Effect}
  */
 const asEffect = (value, source) => {
-    if (value && ['Success', 'Failure', 'Command', 'Ask', 'Retry', 'Parallel'].includes(value.type)) return value;
+    if (isEffect(value)) return value;
     throw effectTypeError(value, source);
 };
 
@@ -286,25 +405,18 @@ const asEffect = (value, source) => {
  * @param {Effect} effect - The current Effect object
  * @param {(value: any) => Effect} fn - The next function to run if the current effect is a Success
  * @param {any} [initialInput] - The pipeline's starting value, stamped on every node but a Success
+ * @param {Effect} [from] - The node whose `next` returned `effect`, which an error names
  * @returns {Effect} The composed Effect
  */
-const chain = (effect, fn, initialInput) => {
-    // The outermost pipeline wins. A step can return a sub-pipeline whose nodes already carry that
-    // sub-pipeline's start, and an outer chain reaches every one of them through the wrapped `next`
-    // continuations, so overwriting here is what makes the whole tree, a Failure from any depth, and
-    // the root a hook-based recorder reads carry the input of the flow that was actually called. The
-    // previous rule, stamp only when unset, let a Retry- or Parallel-headed sub-pipeline leave its own
-    // input on the root, and a trace recorded from it rebuilt the flow from the wrong value. A Success
-    // is never stamped: nothing reads the input off a terminal value, and leaving it bare is what lets
-    // `assert.deepEqual(result, Success(v))` hold whatever shape the flow had.
+const chain = (effect, fn, initialInput, from) => {
+    const source = () => (from ? nextOf(from) : 'A continuation');
+    // Overwrites a sub-pipeline's own stamp, so the root and a Failure at any depth carry the input of the
+    // flow that was actually called. A Success stays bare, so `deepEqual(result, Success(v))` always holds.
     const withII = (/** @type {Effect} */ e) =>
         initialInput !== undefined && e.type !== 'Success' ? { ...e, initialInput } : e;
 
-    // A continuation that returned nothing has to be caught before `effect.type` is read. Reading it off
-    // `undefined` throws a bare TypeError that names no step, and the run would reject with that. This
-    // guard turns it into an EffectTypeError that says what went wrong. The `default` arm below never sees
-    // it, because the switch itself is what throws.
-    if (effect == null) return asEffect(effect, 'A continuation');
+    // Checked before `effect.type` is read, which would otherwise throw a bare TypeError naming no step.
+    if (effect == null) return asEffect(effect, source());
 
     switch (effect.type) {
         case 'Success':
@@ -312,23 +424,23 @@ const chain = (effect, fn, initialInput) => {
         case 'Failure':
             return withII(effect);
         case 'Command': {
-            const next = (/** @type {any} */ result) => chain(effect.next(result), fn, initialInput);
+            const next = (/** @type {any} */ result) => chain(effect.next(result), fn, initialInput, effect);
             return withII(Command(effect.cmd, next, effect.meta));
         }
         case 'Ask': {
-            const next = (/** @type {any} */ ctx) => chain(effect.next(ctx), fn, initialInput);
+            const next = (/** @type {any} */ ctx) => chain(effect.next(ctx), fn, initialInput, effect);
             return withII(Ask(next));
         }
         case 'Retry': {
-            const next = (/** @type {any} */ result) => chain(effect.next(result), fn, initialInput);
+            const next = (/** @type {any} */ result) => chain(effect.next(result), fn, initialInput, effect);
             return withII({ ...effect, next });
         }
         case 'Parallel': {
-            const next = (/** @type {any} */ result) => chain(effect.next(result), fn, initialInput);
+            const next = (/** @type {any} */ result) => chain(effect.next(result), fn, initialInput, effect);
             return withII({ ...effect, next });
         }
         default:
-            return asEffect(effect, 'A continuation');
+            return asEffect(effect, source());
     }
 };
 
@@ -340,15 +452,21 @@ const chain = (effect, fn, initialInput) => {
  * @returns {(start: any) => Effect} A function that accepts an initial input and returns the final Effect tree.
  */
 const effectPipe = (...fns) => {
+    // Checked where the pipeline is defined, so a misspelt import is named before any flow is built from it.
+    fns.forEach((fn, i) => {
+        if (typeof fn !== 'function') {
+            const got = describeArgument(fn);
+            throw malformed(
+                `effectPipe's step ${i + 1} is ${got}; each step is a function that returns an Effect.`,
+                fn
+            );
+        }
+    });
     return (start) => {
         const chainWithII = (/** @type {Effect} */ eff, /** @type {(v: any) => Effect} */ fn) => chain(eff, fn, start);
         const tree = fns.reduce(chainWithII, /** @type {Effect} */ (Success(start)));
-        // One identity pass over the finished tree. `chain` re-stamps a sub-pipeline's nodes only as
-        // it wraps the continuations that lead to them, and the last step has no later step to do
-        // that wrapping, so a sub-pipeline returned by the last step would keep its own input on
-        // everything past its head. The pass wraps those continuations too, so every node reachable
-        // from here, a Failure at any depth included, carries this pipeline's `start`. `Success` is the
-        // identity step: it can never return a non-Effect, so no message is ever attributed to it.
+        // An identity pass. `chain` stamps a sub-pipeline's nodes only through the continuations it wraps,
+        // and a sub-pipeline returned by the last step has no later step to wrap them.
         return chain(tree, Success, start);
     };
 };
@@ -356,10 +474,8 @@ const effectPipe = (...fns) => {
 /**
  * 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
- * `op` an argument, the recorded decision. `path` identifies the step's position in the Effect tree rather than its position
- * in completion order, so it is the same in a replay as it was in the recorded run even when `Parallel`
- * branches finish in a different order. Hooks written before `path` existed take three parameters and
- * are unaffected.
+ * `op` an argument, the recorded decision. `path` is the step's position in the Effect tree, so it matches
+ * between a run and its replay whatever order `Parallel` branches finish in.
  * @typedef {(name: string, type: string, op: function, path?: string) => Promise<any>} StepRunner
  */
 /** @type StepRunner */
@@ -376,15 +492,13 @@ const defaultCommandInterceptor = async (command, context) => {};
 const defaultRetryOptions = { attempts: 3, delay: 100, backoff: 1 };
 
 /**
- * Retry options were once a process-wide default that a per-use `Retry` merged over. They describe how
- * one dependency misbehaves rather than a property of the process, so they are per-use only now, and a
- * leftover `retry` key throws instead of being ignored: silently falling back to the library defaults
- * is how a configured `attempts: 5` quietly becomes 3. Remove this guard at 1.0.
+ * Refuses the removed `retry` key rather than ignoring it, which would quietly turn a configured
+ * `attempts: 5` back into 3. Migration scaffolding: remove at 1.0.
  * @param {any} config
  * @param {string} source
  */
 const rejectRetryKey = (config, source) => {
-    if (config && typeof config === 'object' && 'retry' in config)
+    if (isObject(config) && 'retry' in config)
         throw new TypeError(
             `${source} no longer takes 'retry'. Retry options are per-use: pass them to Retry(effect, options).`
         );
@@ -392,18 +506,15 @@ const rejectRetryKey = (config, source) => {
 
 /**
  * @typedef {Object} EffectConfiguration
- * @property {StepRunner} [onStep] - Fires every time a Command is executed. It wraps the `cmd` call.
+ * @property {StepRunner} [onStep] - Wraps each Command's execution, and each Parallel's branches.
  * @property {RunWrapper} [onRun] - Fires once per runEffect call. It wraps the entire workflow execution.
  * @property {CommandInterceptor} [onBeforeCommand] - Intercepts a Command and any context passed to runEffect before execution.
  */
 
 /**
  * A per-call configuration: an `EffectConfiguration` plus `inherit`. With `inherit: true` (the default)
- * the call's hooks are added to the wiring `configureEffect` installed, by the merge `configureEffect`
- * applies to several configurations: global outermost, interceptors in order. With `inherit: false` the global wiring is not consulted at all, so any slot the call
- * leaves unset falls back to the library default. A per-call hook cannot replace a single global slot on
- * its own; that was the previous default, and it is how a per-call recorder silently switched off an
- * application's tracing.
+ * the call's hooks are merged over the wiring `configureEffect` installed, global outermost. With
+ * `inherit: false` that wiring is ignored, so a slot the call leaves unset falls back to the library default.
  *
  * @typedef {EffectConfiguration & { inherit?: boolean }} CallConfiguration
  */
@@ -412,10 +523,8 @@ const rejectRetryKey = (config, source) => {
 let layers = [];
 
 /**
- * The installed layers merged into one configuration, empty when nothing is configured. This is the
- * only derived form of `layers`: `runEffect` reads it and merges the call's configuration over it,
- * and a slot no layer defines is simply absent, so the library default is chosen at the one place the
- * hook is used rather than held in a second set of variables kept in step by hand.
+ * The installed layers merged into one configuration. A slot no layer defines is absent, and `runEffect`
+ * picks the library default where it reads the slot.
  * @type {EffectConfiguration}
  */
 let globalConfig = {};
@@ -438,29 +547,21 @@ const applyLayers = () => {
  *     configureEffect(telemetryHooks(), recordingHooks({ sink }));
  *     configureEffect(telemetryHooks()); configureEffect(recordingHooks({ sink }));
  *
- * Calling it with no arguments at all removes every layer. A call whose arguments are all `undefined`
- * is a conditional install that installed nothing: it adds no layer and removes none.
- *
- * Layers replaced the previous one-slot rule, under which a later call displaced the earlier wiring and
- * the returned function restored a snapshot, guarded so that interleaved installs could not clobber
- * each other. Removing a layer needs no guard: A installs, B installs, A removes, and B is still there.
- * It also means a library can install its own hooks without erasing its host's, which under the old rule
- * was possible only if the host passed the library's configuration into its own call.
+ * Calling it with no arguments at all removes every layer. A call whose arguments are all `undefined`,
+ * such as `configureEffect(flag ? hooks : undefined)`, is a conditional install that installed nothing:
+ * it adds no layer and removes none.
  *
  * @param {...(EffectConfiguration | undefined)} configs - Configurations merged into one layer, outermost first
  * @returns {() => void} Removes the layer this call added; a second call does nothing
  */
 const configureEffect = (...configs) => {
-    // Only a call with no arguments at all is a reset. A call whose arguments are all absent, such as
-    // `configureEffect(flag ? hooks : undefined)`, is a conditional install that happened not to install
-    // anything, so it adds no layer and must not remove anyone else's.
     if (configs.length === 0) {
         layers = [];
         applyLayers();
         return () => {};
     }
     const present = configs.filter(Boolean);
-    // Checked before anything is installed, so a refused call leaves the wiring exactly as it found it.
+    // Before installing anything, so a refused call leaves the wiring untouched.
     present.forEach((config) => rejectRetryKey(config, 'configureEffect'));
     if (present.length === 0) return () => {};
     const layer = chainHooks(...present);
@@ -493,7 +594,8 @@ const configureEffect = (...configs) => {
 const now = () => (typeof performance === 'object' ? performance.now() : Date.now());
 
 /**
- * Wraps a step observer into an `onStep` that cannot change the run.
+ * 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}
@@ -528,11 +630,10 @@ const observeSteps = (handler) => async (name, type, op, path) => {
 /**
  * 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 wrapper and the last sits closest to the Command, which also means a thrown
- * Command unwinds from the last config back to the first. `onBeforeCommand` is an observer,
- * so every interceptor runs in the order given. Nothing else merges, since every slot is a hook. A hook
- * no config defines is left unset, so the caller of the merged wiring keeps its default for that slot.
+ * `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
+ * no config defines is left unset, so the caller keeps its default for that slot.
  *
  * @param {...(EffectConfiguration | undefined)} configs - Configurations to merge, outermost first
  * @returns {EffectConfiguration}
@@ -569,17 +670,13 @@ const chainHooks = (...configs) => {
 };
 
 /**
- * The Failure a `Parallel` branch resolves to when a sibling branch has already failed.
- *
- * Branches are cancelled, not merely ignored: this is what `Parallel` returns for a branch that was
- * still in flight, and it is deliberately distinguishable so it can be told apart from the genuine
- * failure that triggered the cancellation.
- * @returns {Error}
+ * The Failure a cancelled `Parallel` branch stops with. Its error is named so it is never mistaken for
+ * the failure that triggered the cancellation.
+ * @param {any} initialInput
+ * @returns {FailureState}
  */
-const parallelCancelled = () =>
-    Object.assign(new Error('Parallel branch cancelled.'), {
-        name: 'ParallelCancelled'
-    });
+const cancelledBranch = (initialInput) =>
+    Failure(Object.assign(new Error('Parallel branch cancelled.'), { name: 'ParallelCancelled' }), initialInput);
 
 /**
  * Which branch, if any, cancelled a Parallel. `branch: null` means an enclosing Parallel cancelled it.
@@ -588,25 +685,41 @@ const parallelCancelled = () =>
  */
 
 /**
- * Reads a recorded decision, or `undefined` for anything that is not one, so a Resolver written for
- * Commands, or a trace from before decisions were recorded, replays a Parallel under timing as before.
+ * What running a Parallel's branches produced: each branch's outcome in array order, the decision, and
+ * the first error a branch threw, which the Parallel rethrows once its step has returned the decision.
+ * @typedef {{
+ *   results: (SuccessState | FailureState | IoFaultState)[],
+ *   decision: ParallelDecision,
+ *   thrown: { error: unknown } | undefined
+ * }} BranchRun
+ */
+
+/**
+ * @param {any} branch
+ * @param {number} count - How many branches the Parallel has
+ * @returns {boolean}
+ */
+const isBranchIndex = (branch, count) => Number.isInteger(branch) && branch >= 0 && branch < count;
+
+/**
+ * Reads a recorded decision, or `undefined` for anything that is not one, which replays the Parallel
+ * under timing.
  * @param {any} value
  * @param {number} branches - How many branches the Parallel has, so a stale branch index is refused too
  * @returns {ParallelDecision | undefined}
  */
 const asDecision = (value, branches) => {
-    if (!value || typeof value !== 'object') return undefined;
+    if (!isObject(value)) return undefined;
     if (value.cancelled === false) return { cancelled: false };
     if (value.cancelled !== true) return undefined;
     const { branch } = value;
     if (branch === null) return { cancelled: true, branch: null };
-    return Number.isInteger(branch) && branch >= 0 && branch < branches ? { cancelled: true, branch } : undefined;
+    return isBranchIndex(branch, branches) ? { cancelled: true, branch } : undefined;
 };
 
 /**
- * Marks the point where a replay reached a step that production never ran, in a branch a Parallel had
- * cancelled. The interpreter stops the branch there, as production did, rather than treating the gap
- * as a divergence. Only `fromTrace` raises it, and only where a recorded decision explains the gap.
+ * 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.
  */
 const replayCut = Symbol('pure-effect.replayCut');
 
@@ -622,10 +735,27 @@ const replayCutError = (path) =>
     );
 
 /**
- * Awaits every task, with at most `limit` of them in flight. Without a limit this is `Promise.all`,
- * which is what `Parallel` did before the option existed. Workers pull by index, so a slow branch
- * holds one slot rather than a position: results land where the caller put the effect, never where it
- * happened to finish, which is also what keeps trace paths stable.
+ * A cancellation scope for one Parallel, linked to the enclosing one so cancellation nests. Without an
+ * `AbortController` there is no scope, and every branch runs to completion.
+ * @param {AbortSignal} [signal] - The enclosing Parallel's signal, if any
+ * @returns {{ scope: AbortController | undefined, unlink: () => void }}
+ */
+const linkedScope = (signal) => {
+    const scope = typeof AbortController === 'function' ? new AbortController() : undefined;
+    const relay = () => scope?.abort();
+    if (signal && scope) {
+        if (signal.aborted) scope.abort();
+        else signal.addEventListener('abort', relay, { once: true });
+    }
+    const unlink = () => {
+        if (signal && scope) signal.removeEventListener('abort', relay);
+    };
+    return { scope, unlink };
+};
+
+/**
+ * Awaits every task, with at most `limit` of them in flight. Workers pull by index, so results land where
+ * the caller put the effect rather than where it finished, which keeps trace paths stable.
  * @param {(() => Promise<void>)[]} tasks
  * @param {number} [limit]
  * @returns {Promise<void>}
@@ -643,9 +773,8 @@ const runBounded = async (tasks, limit) => {
 };
 
 /**
- * Sleeps, but gives up early when the surrounding branch is cancelled, so a sibling's failure does not
- * have to wait out a retry backoff that is now pointless. Resolves either way: the caller's abort check
- * is what turns a cancelled wait into a Failure.
+ * Sleeps, but gives up early when the surrounding branch is cancelled. Resolves either way: the
+ * caller's abort check is what turns a cancelled wait into a Failure.
  *
  * @param {number} ms
  * @param {AbortSignal} [signal]
@@ -657,9 +786,8 @@ const delayFor = (ms, signal) =>
             setTimeout(resolve, ms);
             return;
         }
-        // A listener added to a signal that has already fired never runs. That is the usual case, not an edge:
-        // a Command that honours the signal rejects the moment a sibling fails, and the Retry around it starts
-        // its backoff on the aborted signal.
+        // A listener added to an aborted signal never runs, and this is the usual case: a Command that
+        // honours the signal rejects when a sibling fails, and the Retry around it backs off on that signal.
         if (signal.aborted) {
             resolve();
             return;
@@ -675,33 +803,27 @@ const delayFor = (ms, signal) =>
         signal.addEventListener('abort', onAbort, { once: true });
     });
 
-const runEffect =
+const interpret =
     /**
-     * The Interpreter
-     * Iterates through the Effect tree, executing Commands and handling async flow.
-     * Ask effects are resolved synchronously with the context object.
-     *
-     * Per-call config is merged over the global configureEffect wiring, or over nothing under
-     * `inherit: false`. onRun fires exactly once per runEffect call. Retry attempts run inside that
-     * single span rather than spawning their own, keeping telemetry non-duplicated.
+     * The interpreter: walks the Effect tree, executing Commands and resolving Ask, Retry, and Parallel.
+     * `runEffect` and `replayEffect` both run flows through it, so a replay cannot drift from a run.
+     * `fastRetry` is the one thing only a replay sets: it waits no time between retry attempts, since a
+     * delay is written on the Retry node and nothing else can override it.
      *
-     * @param {Effect} effect - The Effect tree returned by a pipeline
-     * @param {any} [context] - Optional context object. Passed to Ask continuations and the Command Interceptor.
-     * @param {CallConfiguration} [callConfig] - Per-call configuration, added to the wiring `configureEffect`
-     *        installed unless `inherit: false`, which ignores that wiring for this run.
+     * @param {Effect} effect
+     * @param {any} [context]
+     * @param {CallConfiguration} [callConfig]
+     * @param {boolean} [fastRetry]
      * @returns {Promise<SuccessState | FailureState>}
      */
-    async function runEffect(effect, context = {}, callConfig = {}) {
+    async function interpret(effect, context = {}, callConfig = {}, fastRetry = false) {
         rejectRetryKey(callConfig, "runEffect's callConfig");
         const { inherit = true, ...local } = callConfig;
-        // A value that is not a boolean, such as a string left over from an older API, must not be
-        // coerced: `'false'` inheriting everything is exactly the silent behaviour this option removes.
+        // Not coerced: `'false'` quietly inheriting everything is the behaviour this option exists to remove.
         if (typeof inherit !== 'boolean') {
             throw new TypeError(`callConfig.inherit must be true or false, got ${JSON.stringify(inherit)}.`);
         }
-        // The call's configuration is merged over the installed wiring, or over nothing when the call
-        // inherits nothing, by the same merge `configureEffect` applies to several configurations. Most
-        // calls carry no configuration of their own, and those use the installed wiring as it is.
+        // Merged the way `configureEffect` merges layers. A call with no hooks of its own skips the merge.
         const base = inherit ? globalConfig : {};
         const resolved = Object.keys(local).length ? chainHooks(base, local) : base;
         const localStepRunner = resolved.onStep || defaultStepRunner;
@@ -709,325 +831,334 @@ const runEffect =
         const localCommandInterceptor = resolved.onBeforeCommand || defaultCommandInterceptor;
 
         /**
+         * Walks a subtree until it reaches a Success or a Failure. Every node but `Ask` runs in its own
+         * function, which returns a Success carrying the value for the node's `next`, or the Failure or I/O
+         * fault that stops the subtree.
+         *
          * @param {Effect} eff
          * @param {AbortSignal} [signal] - Cancellation for this subtree, set for `Parallel` branches.
-         *        A branch stops starting new Commands once it is aborted, and the signal is handed to
-         *        each Command's thunk so I/O that accepts one can be cancelled in flight.
-         * @param {string} [path] - Prefix identifying this subtree's position in the Effect tree.
-         *        Steps are numbered sequentially within a subtree and each `Parallel` branch and `Retry`
-         *        attempt opens its own prefix, so a Command's full path depends only on the shape of the
-         *        tree and not on the order branches happen to finish in. That is what lets a replay line
-         *        a recorded step up with the step that asked for it.
+         * @param {string} [path] - Prefix for this subtree's position in the Effect tree. Steps are numbered
+         *        within a subtree and each `Parallel` branch and `Retry` attempt opens its own prefix, so a
+         *        path depends only on the tree's shape, never on the order branches finish in.
          * @returns {Promise<SuccessState | FailureState | IoFaultState>}
          */
         async function execute(eff, signal, path = '') {
             let step = 0;
-            while (
-                eff &&
-                (eff.type === 'Command' || eff.type === 'Ask' || eff.type === 'Retry' || eff.type === 'Parallel')
-            ) {
-                // Checked before every node, which is what short-circuits a branch whose Commands
-                // ignore the signal: the one in flight cannot be stopped, but the next never starts.
-                if (signal?.aborted) return Failure(parallelCancelled(), eff.initialInput);
+            /** @type {Effect | undefined} The node whose `next` returned `eff`, which an error names. */
+            let from;
+            while (isPending(eff)) {
+                // Checked before every node: a Command already in flight cannot be stopped, but the next never starts.
+                if (signal?.aborted) return cancelledBranch(eff.initialInput);
                 if (eff.type === 'Ask') {
+                    from = eff;
                     eff = eff.next(context);
                     continue;
                 }
-                if (eff.type === 'Retry') {
-                    const opts = { ...defaultRetryOptions, ...eff.options };
-                    const { attempts } = opts;
-                    // A Retry that does not retry is not a Retry, and `attempts: 0` was also the one
-                    // spelling that made `onExhausted` a plain catch for free. Both readings are wrong,
-                    // so the value is refused rather than coerced.
-                    if (!Number.isInteger(attempts) || attempts < 1)
-                        throw new TypeError(
-                            `Retry 'attempts' must be a positive integer, received ${describeValue(attempts)}. ` +
-                                `To handle an outcome without retrying, branch on it as data in the Command's ` +
-                                `next, or isolate a failing branch with Parallel's settled option.`
-                        );
-                    let lastError;
-                    let succeeded = false;
-                    // Each attempt gets its own prefix, so the Commands of attempt 2 cannot be mistaken
-                    // for the Commands of attempt 1 when a trace is matched back up.
-                    const retryPath = `${path}${step++}r`;
-                    // Captured while `eff` is still narrowed to a Retry node: the loop reassigns `eff`
-                    // on success, after which the checker cannot prove the fallback path still holds it.
-                    const retryNext = eff.next;
-
-                    for (let attempt = 0; attempt <= attempts; attempt++) {
-                        if (attempt > 0) {
-                            await delayFor(opts.delay * Math.pow(opts.backoff, attempt - 1), signal);
-                        }
-                        // Checked after the wait, so a branch cancelled mid-backoff stops here rather
-                        // than buying one more attempt, and a sibling's failure does not pay for the
-                        // rest of this branch's retry schedule.
-                        if (signal?.aborted) return Failure(parallelCancelled(), eff.initialInput);
-                        const result = await execute(eff.effect, signal, `${retryPath}${attempt}/`);
-                        if (result.type === 'Success') {
-                            eff = retryNext(result.value);
-                            succeeded = true;
-                            break;
-                        }
-                        // An abort is the flow deciding, not the I/O failing, so there is nothing to
-                        // try again and nothing for a fallback to answer. It leaves unwrapped: the
-                        // exhaustion shape would be a claim about retrying that never happened.
-                        if (result.type !== 'IoFault') return result;
-                        lastError = result.error;
-                    }
-
-                    if (!succeeded) {
-                        const exhausted = { retryExhausted: true, lastError, attempts };
-                        const { onExhausted } = opts;
-                        // An exhaustion came from I/O, so it is a fault too, which is what keeps an
-                        // enclosing Retry retrying this one.
-                        if (typeof onExhausted !== 'function') return IoFault(exhausted, eff.initialInput);
-                        // A cancelled branch must not start its fallback, for the same reason it starts
-                        // no further Commands: recovery must not resurrect work a sibling's failure ended.
-                        if (signal?.aborted) return Failure(parallelCancelled(), eff.initialInput);
-                        // The fallback gets its own path prefix, so a fallback-path trace can never be
-                        // confused with a success-path one when it is matched back up on replay.
-                        const fallback = await execute(
-                            asEffect(onExhausted(exhausted), "Retry option 'onExhausted'"),
-                            signal,
-                            `${retryPath}f/`
-                        );
-                        // A failing fallback propagates as-is: the flow's last word was the fallback's
-                        // error, not the exhaustion it was already told about.
-                        if (fallback.type !== 'Success') return fallback;
-                        eff = retryNext(fallback.value);
-                    }
-                    continue;
+                const stepPath = `${path}${step++}`;
+                const outcome =
+                    eff.type === 'Retry'
+                        ? await runRetry(eff, signal, stepPath)
+                        : eff.type === 'Parallel'
+                          ? await runParallel(eff, signal, stepPath)
+                          : await runCommand(eff, signal, stepPath);
+                if (outcome.type !== 'Success') return outcome;
+                // Outside every catch: `next` and the pure steps it reaches are code, not I/O, so a throw there
+                // rejects the run.
+                from = eff;
+                eff = eff.next(outcome.value);
+            }
+            if (isOutcome(eff)) return eff;
+            throw effectTypeError(eff, from ? nextOf(from) : 'The flow');
+        }
+
+        /**
+         * Runs a Retry's wrapped tree until it succeeds or runs out of attempts, then its fallback if it has
+         * one. Each attempt opens its own path prefix, and so does the fallback.
+         *
+         * @param {RetryState} retry
+         * @param {AbortSignal | undefined} signal
+         * @param {string} stepPath
+         * @returns {Promise<SuccessState | FailureState | IoFaultState>}
+         */
+        async function runRetry(retry, signal, stepPath) {
+            // An option set to `undefined` keeps its default, since that is how an absent config key arrives.
+            const given = Object.entries(retry.options ?? {}).filter(([, value]) => value !== undefined);
+            const opts = /** @type {typeof defaultRetryOptions & RetryState['options']} */ ({
+                ...defaultRetryOptions,
+                ...Object.fromEntries(given)
+            });
+            const { attempts, onExhausted } = opts;
+            // `0` is refused rather than meaning run once: it would make `onExhausted` a free catch.
+            if (!isPositiveInteger(attempts))
+                throw new TypeError(
+                    `Retry 'attempts' must be a positive integer, received ${describeValue(attempts)}. ` +
+                        `To handle an outcome without retrying, branch on it as data in the Command's ` +
+                        `next, or isolate a failing branch with Parallel's settled option.`
+                );
+            // A wait that is NaN, negative or infinite used to be no wait at all, so a flapping dependency was
+            // called back to back.
+            for (const key of /** @type {const} */ (['delay', 'backoff'])) {
+                if (!isFiniteNonNegative(opts[key]))
+                    throw new TypeError(
+                        `Retry '${key}' must be a finite number of 0 or more, received ${describeValue(opts[key])}.`
+                    );
+            }
+            let lastError;
+            for (let attempt = 0; attempt <= attempts; attempt++) {
+                // Under `fastRetry` this waits for no time rather than skipping the wait, so branches replayed by
+                // timing still interleave as they do with a delay.
+                if (attempt > 0) {
+                    await delayFor(fastRetry ? 0 : opts.delay * Math.pow(opts.backoff, attempt - 1), signal);
                 }
-                if (eff.type === 'Parallel') {
-                    // Branch prefixes come from the branch's index in the array, never from the order
-                    // branches complete in, which is the whole point: two branches calling the same
-                    // Command are told apart by where they are rather than by who finished first.
-                    const branchPath = `${path}${step++}p`;
-                    const { limit, settled } = eff.options ?? {};
-                    if (limit !== undefined && (!Number.isInteger(limit) || limit < 1))
-                        throw new TypeError(
-                            `Parallel 'limit' must be a positive integer, received ${describeValue(limit)}.`
-                        );
-                    // Captured while `eff` is still narrowed to a Parallel node, since `op` below runs later.
-                    const effects = eff.effects;
-                    const parallelInput = eff.initialInput;
-
-                    /** @type {(SuccessState | FailureState | IoFaultState)[]} */
-                    let results = [];
-                    // Cast rather than annotated: `runBranches` reassigns it, which the checker cannot see from
-                    // here, and an annotated literal would be narrowed to `{ cancelled: false }` for good.
-                    let decision = /** @type {ParallelDecision} */ ({ cancelled: false });
-                    let ran = false;
-                    // What a branch threw, held until this Parallel's step has returned its decision. Cast
-                    // rather than annotated, for the same reason as `decision`.
-                    let branchThrow = /** @type {{ error: unknown } | undefined} */ (undefined);
-
-                    /**
-                     * Runs the branches and returns the decision: which branch, if any, cancelled the others.
-                     * That decision comes from timing, so it is handed to `onStep` as this Parallel's step
-                     * and recorded like a Command's result. A replay passes the recorded decision back in,
-                     * and a cancelled one is reproduced rather than recomputed: nothing aborts, each branch
-                     * runs its recorded steps and is stopped where its recording stops, and the recorded
-                     * branch's failure is the result. Replaying the abort at replay speed is what let a
-                     * cancelled branch's AbortError win, or let a branch run past where production stopped it.
-                     * A branch that throws gets a decision too, and its throw is rethrown once the step has
-                     * returned it: thrown from here, the step failed and recorded the error where the decision
-                     * belonged, so the replay of a run that crashed raced the branches again.
-                     * @param {any} [recorded]
-                     * @returns {Promise<ParallelDecision>}
-                     */
-                    const runBranches = async (recorded) => {
-                        ran = true;
-                        // A recorded decision naming a branch past the end of this Parallel means the shape
-                        // changed since the recording. Falling back to timing would let whichever remaining
-                        // branch the replay reaches first decide, which is the wrong answer this fixed. A
-                        // negative branch is not a decision at all, since none is ever recorded, so it replays
-                        // by timing like anything else that is not one.
-                        const recordedBranch = recorded?.cancelled === true ? recorded.branch : undefined;
-                        if (Number.isInteger(recordedBranch) && recordedBranch >= effects.length) {
-                            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 }
-                            );
-                        }
-                        const forced = asDecision(recorded, effects.length);
-                        const reproducing = forced !== undefined && forced.cancelled;
-                        // One scope per Parallel, linked to the enclosing one so cancellation nests.
-                        // Absent AbortController (very old runtimes), `branchSignal` stays undefined and
-                        // the old run-everything-to-completion behaviour is what happens. The scope is kept
-                        // under `settled` so an enclosing Parallel can still cancel this one; what settled
-                        // drops is a branch cancelling its own siblings.
-                        const scope = typeof AbortController === 'function' ? new AbortController() : undefined;
-                        const branchSignal = scope?.signal;
-                        const relay = () => scope?.abort();
-                        if (signal && scope) {
-                            if (signal.aborted) scope.abort();
-                            else signal.addEventListener('abort', relay, { once: true });
-                        }
-
-                        results = new Array(effects.length);
-                        // Which branch failed on its own account rather than because it was cancelled.
-                        const triggered = new Array(effects.length).fill(false);
-                        // A branch that throws (a bug in its code, or a harness error) cancels its siblings
-                        // like a failing one, and is the trigger when it is the first to, under `settled` too,
-                        // since the run is rejecting either way. When reproducing, nothing aborts: the recorded
-                        // decision already says where each branch stops. The error is held rather than rethrown
-                        // at once: rejecting `runBounded` early used to leave the siblings running unobserved,
-                        // and under `limit` it stopped that worker.
-                        /** @type {{ error: unknown }[]} */
-                        const thrown = new Array(effects.length);
-                        try {
-                            // Still awaits every branch, so no cancelled work is left running unobserved
-                            // after the Failure is returned. Cancelled branches settle promptly; a branch
-                            // whose in-flight Command ignores the signal is the one case that does not.
-                            await runBounded(
-                                effects.map((e, i) => async () => {
-                                    let result;
-                                    try {
-                                        result = await execute(e, branchSignal, `${branchPath}${i}/`);
-                                    } catch (error) {
-                                        thrown[i] = { error };
-                                        if (reproducing) return;
-                                        if (!branchSignal?.aborted) triggered[i] = true;
-                                        scope?.abort();
-                                        return;
-                                    }
-                                    results[i] = result;
-                                    // Read-then-abort is atomic here, so exactly one branch is the trigger.
-                                    const cancels = !settled && !reproducing && !branchSignal?.aborted;
-                                    if (result.type !== 'Success' && cancels) {
-                                        triggered[i] = true;
-                                        scope?.abort();
-                                    }
-                                }),
-                                limit
-                            );
-                        } finally {
-                            if (signal && scope) signal.removeEventListener('abort', relay);
-                        }
-                        // The first by array order. A thrown error is held until every branch has settled, so
-                        // position can decide here, where a failing branch is taken in the order it finishes.
-                        branchThrow = thrown.find(Boolean);
-
-                        if (forced !== undefined && forced.cancelled) {
-                            // A branch that threw has no result to check, and its throw is what is rethrown.
-                            if (!branchThrow && forced.branch !== null && results[forced.branch].type === 'Success') {
-                                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 }
-                                );
-                            }
-                            decision = forced;
-                            return decision;
-                        }
-                        const trigger = triggered.indexOf(true);
-                        decision =
-                            trigger >= 0
-                                ? { cancelled: true, branch: trigger }
-                                : branchSignal?.aborted
-                                  ? { cancelled: true, branch: null }
-                                  : { cancelled: false };
-                        return decision;
-                    };
-
-                    try {
-                        await localStepRunner('Parallel', 'Parallel', runBranches, branchPath);
-                    } catch (e) {
-                        // A replay found this Parallel inside a branch production had already stopped.
-                        if (e && /** @type {any} */ (e)[replayCut]) return Failure(parallelCancelled(), parallelInput);
-                        throw e;
-                    }
-                    if (!ran) {
-                        throw new TypeError(
-                            `An onStep hook returned without calling op for the Parallel at path '${branchPath}'. ` +
-                                'A hook has to call op for a Parallel, because op runs its branches.'
-                        );
-                    }
-                    // Rethrown here, after the step has returned its decision, so the decision is recorded.
-                    if (branchThrow) throw branchThrow.error;
-
-                    // Settled hands the outcomes on as plain Success and Failure nodes. A branch that
-                    // failed is data here, so `next` runs and the Parallel itself never fails on a
-                    // branch's account; and a Failure `next` returns is an abort like any other.
-                    if (settled) {
-                        eff = eff.next(results.map(asOutcome));
-                        continue;
-                    }
-
-                    const failure =
-                        decision.cancelled && decision.branch !== null
-                            ? results[decision.branch]
-                            : results.find((r) => r.type !== 'Success');
-                    if (failure) return failure;
-                    eff = eff.next(results.map((r) => /** @type {SuccessState} */ (r).value));
-                    continue;
+                // After the wait, so a branch cancelled mid-backoff makes no further attempt.
+                if (signal?.aborted) return cancelledBranch(retry.initialInput);
+                const result = await execute(retry.effect, signal, `${stepPath}r${attempt}/`);
+                // A Success feeds `next`. An abort is the flow deciding, not the I/O failing: not retried, not
+                // wrapped.
+                if (result.type !== 'IoFault') return result;
+                lastError = result.error;
+            }
+            const exhausted = { retryExhausted: true, lastError, attempts };
+            // An exhaustion is a fault too, which keeps an enclosing Retry retrying this one.
+            if (typeof onExhausted !== 'function') return IoFault(exhausted, retry.initialInput);
+            // A cancelled branch starts no fallback, as it starts no further Commands.
+            if (signal?.aborted) return cancelledBranch(retry.initialInput);
+            // A failing fallback propagates as it is, not wrapped as another exhaustion.
+            return execute(asEffect(onExhausted(exhausted), "Retry option 'onExhausted'"), signal, `${stepPath}rf/`);
+        }
+
+        /**
+         * Runs a Parallel as one step of its own, whose `op` runs the branches and returns the decision, so
+         * the decision is recorded and a replay can hand it back.
+         *
+         * @param {ParallelState} parallel
+         * @param {AbortSignal | undefined} signal
+         * @param {string} stepPath
+         * @returns {Promise<SuccessState | FailureState | IoFaultState>}
+         */
+        async function runParallel(parallel, signal, stepPath) {
+            // Branch prefixes come from array index, never completion order, so two branches calling the same
+            // Command are told apart by position.
+            const branchPath = `${stepPath}p`;
+            const options = parallel.options ?? {};
+            const { limit, settled } = options;
+            if (limit !== undefined && !isPositiveInteger(limit))
+                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);
+            const op = async (/** @type {any} */ recorded) => {
+                run = await runBranches(parallel.effects, options, signal, branchPath, recorded);
+                return run.decision;
+            };
+            try {
+                await localStepRunner('Parallel', 'Parallel', op, branchPath);
+            } catch (e) {
+                // A replay found this Parallel inside a branch production had already stopped.
+                if (hasMark(e, replayCut)) return cancelledBranch(parallel.initialInput);
+                throw e;
+            }
+            if (!run) {
+                throw new TypeError(
+                    `An onStep hook returned without letting op run the Parallel at path '${branchPath}'. ` +
+                        'A hook has to call op for a Parallel and pass on what it returns or throws, because op ' +
+                        'runs its branches.'
+                );
+            }
+            const { results, decision, thrown } = run;
+            // Rethrown here, after the step has returned its decision, so the decision is recorded.
+            if (thrown) throw thrown.error;
+            // Settled hands `next` the outcomes as plain Success and Failure nodes, so the Parallel never fails
+            // on a branch's account.
+            if (settled) return Success(results.map(asOutcome));
+            const failure =
+                decision.cancelled && decision.branch !== null
+                    ? results[decision.branch]
+                    : results.find((r) => r.type !== 'Success');
+            if (failure) return failure;
+            return Success(results.map((r) => /** @type {SuccessState} */ (r).value));
+        }
+
+        /**
+         * Runs a Parallel's branches and decides which branch, if any, cancelled the others. In a live run
+         * timing decides it, which is why the decision is recorded. A recorded cancellation passed in by a
+         * replay is reproduced rather than recomputed: no branch cancels another, each runs its recorded steps
+         * and stops where its recording stops, and the recorded branch's failure is the result.
+         *
+         * @param {Effect[]} effects
+         * @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
+         * @returns {Promise<BranchRun>}
+         */
+        async function runBranches(effects, options, signal, branchPath, recorded) {
+            const { limit, settled } = options;
+            // A recorded branch past the end means the flow changed shape since the recording. A negative one is
+            // not a decision, so it replays by timing like anything else.
+            const recordedBranch = recorded?.cancelled === true ? recorded.branch : undefined;
+            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 }
+                );
+            }
+            const forced = asDecision(recorded, effects.length);
+            const reproducing = forced !== undefined && forced.cancelled;
+            // Live, a throw cancels the others, and so does a failure unless `settled`; the run rejects on a throw
+            // either way, and an enclosing Parallel can still cancel this one. Reproducing, nothing cancels, since
+            // the recording already says where each branch stops.
+            const { results, thrown, trigger, cancelled } = await settleBranches(
+                effects,
+                limit,
+                signal,
+                branchPath,
+                reproducing ? () => false : (threw, result) => threw || (!settled && result.type !== 'Success')
+            );
+            if (reproducing) {
+                // A branch that threw has no result to check, and its throw is what is rethrown.
+                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 }
+                    );
                 }
-                const cmdName = commandName(eff);
-                const initialInput = eff.initialInput;
-                const cmdPath = `${path}${step++}`;
-                const cmd = eff.cmd;
-                // Whether the Command's function itself succeeded. That is what tells a throw from the step
-                // runner apart: the function failing is an I/O fault, while a hook failing after the function
-                // returned is a bug, and retrying it would repeat work that is already done.
-                let succeeded = false;
-                // The signal reaches the function only inside a Parallel, so a function written to take a
-                // parameter is not handed an argument it never expected anywhere else. `op` always returns a
-                // promise, as the declared type and the README's "must await op()" say, and a synchronous
-                // throw arrives as a rejection. It used to hand back a synchronous function's value as it was,
-                // so a hook written as `op().then(...)` compiled and then rejected every such run.
-                const op = async () => {
-                    succeeded = false;
-                    const value = await (signal ? cmd(signal) : cmd());
-                    succeeded = true;
-                    return value;
-                };
-                // Three separate regions, because a throw means something different in each. An
-                // interceptor that throws is vetoing the Command, which is the flow being stopped rather
-                // than the I/O failing, so it is an abort and `Retry` passes it on. Only a throw from the
-                // Command's function is an I/O fault. A malformed flow is a bug, not a domain failure,
-                // so in either catch it must not masquerade as one.
+                return { results, decision: forced, thrown };
+            }
+            /** @type {ParallelDecision} */
+            const decision =
+                trigger >= 0
+                    ? { cancelled: true, branch: trigger }
+                    : cancelled
+                      ? { cancelled: true, branch: null }
+                      : { cancelled: false };
+            return { results, decision, thrown };
+        }
+
+        /**
+         * Runs every branch to completion, at most `limit` at once, under one cancellation scope linked to the
+         * enclosing one. A branch that settles in a way `cancelsOthers` accepts cancels the rest, and the first
+         * to do so is the trigger.
+         *
+         * @param {Effect[]} effects
+         * @param {number | undefined} limit
+         * @param {AbortSignal | undefined} signal
+         * @param {string} branchPath
+         * @param {(threw: boolean, result: SuccessState | FailureState | IoFaultState) => boolean} cancelsOthers
+         * @returns {Promise<{
+         *   results: (SuccessState | FailureState | IoFaultState)[],
+         *   thrown: { error: unknown } | undefined,
+         *   trigger: number,
+         *   cancelled: boolean
+         * }>}
+         */
+        async function settleBranches(effects, limit, signal, branchPath, cancelsOthers) {
+            const { scope, unlink } = linkedScope(signal);
+            /** @type {(SuccessState | FailureState | IoFaultState)[]} */
+            const results = new Array(effects.length);
+            // Held rather than rethrown, so every branch still settles and no `limit` worker stops early.
+            /** @type {{ error: unknown }[]} */
+            const thrown = new Array(effects.length);
+            // Which branch cancelled the others on its own account rather than because it was cancelled.
+            const triggered = new Array(effects.length).fill(false);
+            const settle = async (/** @type {Effect} */ branch, /** @type {number} */ i) => {
                 try {
-                    await localCommandInterceptor(eff, context);
-                } catch (e) {
-                    if (e && /** @type {any} */ (e)[harnessError]) throw e;
-                    return Failure(e, initialInput);
+                    results[i] = await execute(branch, scope?.signal, `${branchPath}${i}/`);
+                } catch (error) {
+                    thrown[i] = { error };
                 }
-                // Checked again because an interceptor can wait, a rate limiter handing out tokens for one, and a
-                // sibling can fail meanwhile. The check at the top of the loop ran before that wait.
-                if (signal?.aborted) return Failure(parallelCancelled(), initialInput);
-                let result;
-                try {
-                    result = await localStepRunner(cmdName, 'Command', op, cmdPath);
-                } catch (e) {
-                    // A replay reached a step production never ran, in a branch a Parallel had cancelled:
-                    // this is where production stopped the branch, so the replay stops it here too.
-                    if (e && /** @type {any} */ (e)[replayCut]) return Failure(parallelCancelled(), initialInput);
-                    if (e && /** @type {any} */ (e)[harnessError]) throw e;
-                    // The function returned and a hook threw afterwards: a bug in the hook, rejected like a
-                    // throw from `next`. A hook that throws without calling `op` is still a fault, since that
-                    // is how replay reports a recorded error.
-                    if (succeeded) throw e;
-                    return IoFault(e, initialInput);
+                // Read-then-abort is atomic here, so exactly one branch is the trigger.
+                if (cancelsOthers(thrown[i] !== undefined, results[i])) {
+                    if (!scope?.signal.aborted) triggered[i] = true;
+                    scope?.abort();
                 }
-                // Outside both catches: `next`, and every pure step it reaches up to the next Command, is
-                // code rather than I/O, so a throw there is a bug and rejects the run like a throw from
-                // any other continuation. Inside the catch it was an I/O fault, and `Retry` re-ran a
-                // Command that had succeeded because a TypeError followed it.
-                eff = eff.next(result);
+            };
+            try {
+                // Awaits every branch, so no cancelled work runs on unobserved after the Parallel returns.
+                await runBounded(
+                    effects.map((branch, i) => () => settle(branch, i)),
+                    limit
+                );
+            } finally {
+                unlink();
             }
-            if (eff && (eff.type === 'Success' || eff.type === 'Failure')) return eff;
-            throw effectTypeError(eff, 'The flow');
+            return {
+                results,
+                // The first by array order, since every branch has settled by now.
+                thrown: thrown.find(Boolean),
+                trigger: triggered.indexOf(true),
+                cancelled: Boolean(scope?.signal.aborted)
+            };
         }
 
-        // Every Failure leaves through here, including one a Parallel branch or a Retry fallback handed
-        // back. `chain` stamps only what passes through the continuations it wraps, and those subtrees
-        // are executed directly rather than reached through a continuation, so their Failures arrive
-        // carrying the subtree's own input or none. Restamping the outcome with the root's input is
-        // what makes "a Failure carries the input of the flow that was called" true at any depth. An I/O
-        // fault becomes a plain Failure here too, since this is where it would first reach the caller.
+        /**
+         * Runs one Command. A throw means something different in each region: an interceptor throwing vetoes
+         * the Command, which is an abort, and the Command's function throwing is an I/O fault. A harness error
+         * is rethrown from either.
+         *
+         * @param {CommandState} command
+         * @param {AbortSignal | undefined} signal
+         * @param {string} cmdPath
+         * @returns {Promise<SuccessState | FailureState | IoFaultState>}
+         */
+        async function runCommand(command, signal, cmdPath) {
+            const cmdName = commandName(command);
+            const { initialInput, cmd } = command;
+            // Whether the function itself succeeded: a hook throwing after it did is a bug, and retrying would
+            // repeat work already done.
+            let succeeded = false;
+            // 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 () => {
+                succeeded = false;
+                value = await (signal ? cmd(signal) : cmd());
+                succeeded = true;
+                return value;
+            };
+            try {
+                await localCommandInterceptor(command, context);
+            } catch (e) {
+                if (hasMark(e, harnessError)) throw e;
+                return Failure(e, initialInput);
+            }
+            // Again, since an interceptor can wait (a rate limiter, say) while a sibling fails.
+            if (signal?.aborted) return cancelledBranch(initialInput);
+            let returned;
+            try {
+                returned = await localStepRunner(cmdName, 'Command', op, cmdPath);
+            } catch (e) {
+                // 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
+                // without calling `op` is still a fault, since that is how replay reports a recorded error.
+                if (succeeded) throw e;
+                return IoFault(e, initialInput);
+            }
+            // A hook that awaited `op` and forgot to return its result: `next` would take the branch for a Command
+            // that returned nothing, while a recorder inside the hook kept the real value. Only `undefined` is
+            // 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.'
+                );
+            }
+            return Success(returned);
+        }
+
+        // Every outcome leaves through here, so this is where a Failure gets the root's input: one from a
+        // Parallel branch or a Retry fallback carries its own subtree's input, which `chain` never reaches.
+        // An I/O fault becomes a plain Failure here too.
         const rootInput = effect?.initialInput;
         const run = async () => {
             const result = asOutcome(await execute(effect));
@@ -1036,6 +1167,18 @@ const runEffect =
         return localRunWrapper(effect, run, context?.flowName || '');
     };
 
+/**
+ * Runs a flow: executes its Commands, resolving `Ask` with the context and running `Retry` and `Parallel`.
+ * onRun fires exactly once per call; Retry attempts run inside that single span.
+ *
+ * @param {Effect} effect - The Effect tree returned by a pipeline
+ * @param {any} [context] - Optional context object. Passed to Ask continuations and the Command Interceptor.
+ * @param {CallConfiguration} [callConfig] - Per-call configuration, added to the wiring `configureEffect`
+ *        installed unless `inherit: false`, which ignores that wiring for this run.
+ * @returns {Promise<SuccessState | FailureState>}
+ */
+const runEffect = (effect, context, callConfig) => interpret(effect, context, callConfig);
+
 /**
  * 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
@@ -1057,11 +1200,8 @@ const runEffect =
 
 /**
  * A recorded step: a Command's result or error, or a Parallel's decision, recorded as `command`
- * 'Parallel' at the Parallel's own path with the decision as its `result`.
- * `durationMs` is how long the step took in production, rounded to microseconds,
- * which is the one question a trace could not answer before: which step was slow.
- * `path` locates the Command in the Effect tree, which is what a replay matches on: it does not move
- * when `Parallel` branches finish in a different order than they did in production.
+ * 'Parallel' at the Parallel's own path with the decision as its `result`. `durationMs` is how long
+ * the step took in production, rounded to microseconds. `path` is what a replay matches on.
  * `threw` marks a step that threw. The `error` key alone cannot, since JSON drops it when the value is
  * `undefined`, as it is for `reject()` with no argument or an error `redact` removed.
  * @typedef {{ command: string, path?: string, result?: any, threw?: true, error?: any, durationMs?: number }} TraceEntry
@@ -1081,17 +1221,15 @@ const runEffect =
  */
 
 /**
- * A replay fault: the trace cannot answer the flow, or disagrees with it. It is a harness error while
- * the flow runs, so nothing inside the flow can swallow it, and `replayEffect` turns it back into a
- * `Failure` at its own boundary, where there is no longer anything to swallow it and a caller can
- * inspect it. An `EffectTypeError` carries no replay mark and keeps propagating, since a malformed
- * flow is a bug in the flow rather than a problem with the trace.
+ * A replay fault: the trace cannot answer the flow, or disagrees with it. A harness error while the flow
+ * runs, so nothing inside the flow can swallow it; `replayEffect` turns it into a `Failure` at its own
+ * boundary. An `EffectTypeError` carries no replay mark and keeps propagating, since a malformed flow is
+ * a bug in the flow rather than a problem with the trace.
  */
 const replayFault = Symbol('pure-effect.replayFault');
 
 /**
- * Creates a replay error. Thrown from a resolver, it is rethrown by the interpreter rather than folded
- * into a Failure, and `replayEffect` turns it into one at its own boundary.
+ * Creates a replay error, which `replayEffect` turns into a Failure at its own boundary.
  * @param {string} message - Human-readable reason
  * @param {Object} [props] - Extra fields such as `name`, `index`, `expected`, `actual`
  * @returns {Error}
@@ -1131,27 +1269,41 @@ const timeParadox = (step, recorded) =>
  *
  * @param {any} e - The thrown value
  * @param {boolean} [withStack] - Include the stack (off by default: noisy, leaks paths)
+ * @param {Set<Error>} [ancestors] - The errors whose `cause` or `errors` led here
  * @returns {any}
  */
-const serializeError = (e, withStack) => {
+const serializeError = (e, withStack, ancestors = new Set()) => {
     if (!(e instanceof Error)) return e;
     /** @type {any} */
     const out = { __error: true, name: e.name, message: e.message };
+    // A chain that comes back to an error it passed through is cut there, with the name and message only:
+    // following it overflowed the stack, and the recorder dropped the whole step. Only ancestors count, so an
+    // error that merely appears twice is carried in full both times.
+    if (ancestors.has(e)) return out;
+    ancestors.add(e);
     if (withStack) out.stack = e.stack;
     // `cause` is non-enumerable too, and it can itself be an Error, so it is carried recursively.
-    if ('cause' in e) out.cause = serializeError(e.cause, withStack);
-    // So is an AggregateError's `errors`, and that is where the detail lives: Node's refused connection to
-    // localhost has an empty message and one entry per address it tried. It is kept under its own key so
-    // that revival can tell it from an enumerable `errors`, which a validation error carries as data and
-    // the loop below copies as it is.
+    if ('cause' in e) out.cause = serializeError(e.cause, withStack, ancestors);
+    // So is an AggregateError's `errors`, which is where its detail lives. It goes under its own key so
+    // revival can tell it from an enumerable `errors`, which is data and is copied below as it is.
     const errors = /** @type {any} */ (e).errors;
-    if (Array.isArray(errors) && !Object.prototype.propertyIsEnumerable.call(e, 'errors')) {
-        out.__errors = errors.map((x) => serializeError(x, withStack));
+    const hasHiddenErrors = Array.isArray(errors) && !Object.prototype.propertyIsEnumerable.call(e, 'errors');
+    if (hasHiddenErrors) {
+        out.__errors = errors.map((x) => serializeError(x, withStack, ancestors));
     }
-    for (const k of Object.keys(e)) out[k] = /** @type {any} */ (e)[k];
+    ancestors.delete(e);
+    // Assigning `name`, `message` or `cause`, as `e.name = 'TimeoutError'` or `e.cause = inner` does, makes it
+    // enumerable. It is carried above already, so it is listed for revival to restore as it was rather than
+    // copied again, where a raw cause would replace the serialized one and reach JSON as {}.
+    const shown = carriedKeys.filter((k) => Object.prototype.propertyIsEnumerable.call(e, k));
+    if (shown.length > 0) out.__enumerable = shown;
+    for (const k of Object.keys(e)) if (!carriedKeys.includes(k)) out[k] = /** @type {any} */ (e)[k];
     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.
@@ -1159,21 +1311,23 @@ const serializeError = (e, withStack) => {
  * @returns {any}
  */
 const reviveError = (v) => {
-    if (!v || typeof v !== 'object' || v.__error !== true) return v;
+    if (!isObject(v) || v.__error !== true) return v;
     const e = new Error(v.message);
-    // `name` and `cause` are non-enumerable on a native Error (`name` is inherited, `cause` is set by the
-    // constructor), so they are defined the same way here. Assigning them would make them own enumerable
-    // keys, and the revived error would then never compare deep-equal to the one the Command threw, which
-    // is what the record-then-replay determinism check relies on. Everything else was enumerable on the
-    // original, since `serializeError` read it through `Object.keys`, so plain assignment is faithful.
-    const hidden = { enumerable: false, configurable: true, writable: true };
-    Object.defineProperty(e, 'name', { ...hidden, value: v.name });
+    // `name`, `message`, `cause` and `errors` are defined as the original had them, so a revived error
+    // deep-equals the one the Command threw: non-enumerable, as on a native Error, unless `__enumerable` lists
+    // them. Every other key was enumerable on the original.
+    const shown = Array.isArray(v.__enumerable) ? v.__enumerable : [];
+    const restore = (/** @type {string} */ key, /** @type {any} */ value) =>
+        Object.defineProperty(e, key, { enumerable: shown.includes(key), configurable: true, writable: true, value });
+    restore('name', v.name);
+    if (shown.includes('message')) restore('message', v.message);
+    // The markers are dropped, and `name` and `message` are already set.
+    const alreadyHandled = ['__error', '__enumerable', 'name', 'message'];
     for (const [k, val] of Object.entries(v)) {
-        if (k === '__error' || k === 'name' || k === 'message') continue;
-        if (k === 'cause') Object.defineProperty(e, 'cause', { ...hidden, value: reviveError(val) });
-        else if (k === '__errors' && Array.isArray(val)) {
-            Object.defineProperty(e, 'errors', { ...hidden, value: val.map(reviveError) });
-        } else /** @type {any} */ (e)[k] = val;
+        if (alreadyHandled.includes(k)) continue;
+        if (k === 'cause') restore('cause', reviveError(val));
+        else if (k === '__errors' && Array.isArray(val)) restore('errors', val.map(reviveError));
+        else /** @type {any} */ (e)[k] = val;
     }
     return e;
 };
@@ -1198,21 +1352,31 @@ const reviveError = (v) => {
  * @property {string} [version] - Commit or build id, so a replay can detect a stale trace.
  */
 
+/**
+ * An array, a plain object, or an object with no prototype: the shapes `copyAround` rebuilds itself rather
+ * than handing to `structuredClone`.
+ * @param {object} value
+ * @returns {boolean}
+ */
+const isPlainContainer = (value) => {
+    if (Array.isArray(value)) return true;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+};
+
 /**
  * Copies what `structuredClone` refused. Arrays and plain objects are rebuilt and everything inside them is
  * copied in turn, so only the parts that cannot be copied, such as a function or an object holding one, are
- * kept as they are. A context holding a logger is the usual case, and keeping the whole context by reference
- * handed `redact` the live object the flow's `Ask` reads.
+ * kept as they are. A context holding a logger is the usual case.
  *
  * @param {any} value
  * @param {Map<object, any>} seen - Copies made so far, so a cycle is copied as a cycle
  * @returns {any}
  */
 const copyAround = (value, seen) => {
-    if (value === null || typeof value !== 'object') return value;
+    if (!isObject(value)) return value;
     if (seen.has(value)) return seen.get(value);
-    const proto = Object.getPrototypeOf(value);
-    if (!Array.isArray(value) && proto !== Object.prototype && proto !== null) {
+    if (!isPlainContainer(value)) {
         try {
             return structuredClone(value);
         } catch {
@@ -1220,26 +1384,23 @@ const copyAround = (value, seen) => {
         }
     }
     /** @type {any} */
-    const copy = Array.isArray(value) ? [] : Object.create(proto);
+    const copy = Array.isArray(value) ? [] : Object.create(Object.getPrototypeOf(value));
     seen.set(value, copy);
     for (const key of Object.keys(value)) copy[key] = copyAround(value[key], seen);
     return copy;
 };
 
 /**
- * Snapshots a value on its way into a trace, and on its way out of one in a replay.
- *
- * Commands return live objects, and a later step that mutates one would otherwise rewrite what the
- * trace says an earlier step returned: `toTrace` runs after the flow finishes, so by serialization
- * time the mutation is already baked in and the trace records a value production never saw. The copy
- * is also what `redact` is handed, so it has to be one the flow never sees. A value that cannot be
- * cloned whole is copied around the parts that cannot be copied.
+ * Snapshots a value on its way into a trace, and on its way out of one in a replay, so a later mutation
+ * cannot rewrite what the trace says a step returned. The copy is also what `redact` is handed, so it has
+ * to be one the flow never sees. A value that cannot be cloned whole is copied around the parts that
+ * cannot be copied.
  *
  * @param {any} value
  * @returns {any}
  */
 const snapshot = (value) => {
-    if (value === null || typeof value !== 'object') return value;
+    if (!isObject(value)) return value;
     try {
         return typeof structuredClone === 'function' ? structuredClone(value) : JSON.parse(JSON.stringify(value));
     } catch {
@@ -1249,8 +1410,9 @@ 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, or
- * to `configureEffect` to record globally.
+ * 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 }}
@@ -1266,9 +1428,7 @@ const recorder = (options = {}) => {
         else dropped++;
     };
 
-    /**
-     * `redact` is the caller's code.
-     */
+    // `redact` is the caller's code, and a throw from it must not reach the run.
     const safeRedact = (/** @type {any} */ value, /** @type {string} */ name, /** @type {string} */ kind) => {
         try {
             return redact(value, name, kind);
@@ -1284,14 +1444,10 @@ const recorder = (options = {}) => {
     const redactField = (/** @type {any} */ value, /** @type {string} */ kind) =>
         value === undefined ? undefined : safeRedact(snapshot(value), kind, kind);
 
-    // Built on `observeSteps` so the hook contract lives in one place: `op` always runs, its result is
-    // always returned, and its error always propagates.
     const onStep = observeSteps(({ name, type, path }) => (end) => {
         const durationMs = Math.round(end.durationMs * 1000) / 1000;
-        // `redact` is handed a copy. Handed the live value, a redact that deleted a field in place removed it
-        // from the result the flow's `next` was about to receive, or the error the caller would get, so
-        // recording changed what production did. A Parallel's result is its decision, which holds no user
-        // data and has to survive intact for a replay to reproduce it, so `redact` is not asked about it.
+        // A Parallel's result is its decision, which holds no user data and must survive intact for a replay
+        // to reproduce it, so it is not redacted.
         const recorded = (/** @type {any} */ result) =>
             type === 'Parallel' ? snapshot(result) : safeRedact(snapshot(result), name, 'result');
         push(
@@ -1327,8 +1483,8 @@ const recorder = (options = {}) => {
 
 /**
  * Runs a flow for real while recording every Command result, and returns both the
- * outcome and a replayable trace. Convenient in tests and scripts; in an application,
- * install `recorder().onStep` once via `configureEffect` instead of changing call sites.
+ * outcome and a replayable trace. Convenient in tests and scripts; to record an application without
+ * changing call sites, give each run its own recorder, as examples/recording-example.js does.
  *
  * @param {(input: any) => Effect} flowFn - Builds the Effect tree from its input
  * @param {any} initialInput - The value the flow is called with; stored so a replay can rebuild it
@@ -1339,35 +1495,46 @@ const recorder = (options = {}) => {
 const recordEffect = async (flowFn, initialInput, options = {}) => {
     const { context = {}, version, ...recorderOptions } = options;
     const rec = recorder(recorderOptions);
-    // Packaged before the run, which is when `toTrace` copies the input and the context. Packaged after it, a
-    // Command that wrote to either, such as an ORM save assigning an id to the object it was handed, rewrote
-    // what the trace says production received, and the replay was rebuilt from a value the run never saw.
+    // Packaged before the run, so a Command that writes to the input or the context, as an ORM save
+    // assigning an id does, cannot rewrite what the trace says the run received.
     const head = rec.toTrace({ initialInput, flowName: context.flowName, context, version });
-    // The recorder is added to the global wiring, so recording inside an instrumented application keeps
-    // its spans.
+    // Merged over the global wiring, so recording inside an instrumented application keeps its spans.
     const result = await runEffect(flowFn(initialInput), context, { onStep: rec.onStep });
     const { dropped, trace } = rec.toTrace();
     return { result, trace: { ...head, dropped, trace } };
 };
 
 /**
- * Turns a recorded entry into the outcome a Resolver must return.
- *
- * The recorded value is snapshotted on the way out, as it was on the way in. Handing the flow the
- * entry's own object let a replayed step that mutates its result rewrite the trace, so replaying the
- * same trace twice gave two different answers.
- *
- * An entry with `threw` is an error, and so is one with an `error` key, which is how an entry recorded
- * before `threw` existed, or written by hand, says it. Relying on the key alone turned a step that threw
- * `undefined` into one that returned it, once the trace had been through JSON.
+ * Whether a recorded entry says its step threw: `threw`, or an `error` key, which is how older and
+ * hand-written traces say it.
+ * @param {TraceEntry} entry
+ * @returns {boolean}
+ */
+const entryThrew = (entry) => entry.threw === true || 'error' in entry;
+
+/**
+ * Whether a trace entry or a replay step carries a path.
+ * @param {{ path?: string }} step
+ * @returns {boolean}
+ */
+const hasPath = (step) => typeof step.path === 'string';
+
+/**
+ * Whether a path lies inside a Parallel branch, which a `p` followed by the branch number marks.
+ * @param {string | undefined} path
+ * @returns {boolean}
+ */
+const isInsideParallel = (path) => typeof path === 'string' && /p\d+\//.test(path);
+
+/**
+ * Turns a recorded entry into the outcome a Resolver must return, snapshotted so a replayed step that
+ * mutates its result cannot rewrite the trace.
  *
  * @param {TraceEntry} entry
  * @returns {ReplayOutcome}
  */
 const entryToOutcome = (entry) =>
-    entry.threw === true || 'error' in entry
-        ? { error: reviveError(snapshot(entry.error)) }
-        : { result: snapshot(entry.result) };
+    entryThrew(entry) ? { error: reviveError(snapshot(entry.error)) } : { result: snapshot(entry.result) };
 
 /**
  * Whether an entry is a Parallel's recorded decision rather than a Command's result. A Parallel's path
@@ -1380,24 +1547,16 @@ const isDecisionEntry = (entry) =>
     entry.command === 'Parallel' && typeof entry.path === 'string' && entry.path.endsWith('p');
 
 /**
- * Builds a Resolver for the reference trace format. Internal: `replayEffect` calls this
- * when handed a trace instead of a Resolver, and is the only caller. Callers with traces
- * in some other shape write a Resolver instead, which is the extension point.
+ * Builds a Resolver for the reference trace format. Internal: `replayEffect` is the only caller, and a
+ * caller with traces in another shape writes a Resolver instead.
  *
- * Path matching is used whenever every entry carries a `path`, which is every trace this
- * version records. A path is the Command's position in the Effect tree, so it is order-independent
- * and still paradox-detecting: it works for `Parallel` as it is, and it tells two branches that
- * call the same Command apart by where they are rather than by which finished first.
+ * When every entry carries a `path`, steps are matched by path, which is order-independent and still
+ * detects a paradox: two `Parallel` branches calling the same Command are told apart by position. A
+ * trace without paths is matched positionally, each entry checked against the Command the flow asks
+ * for, which is exact for sequential flows and cannot tell `Parallel` branches apart.
  *
- * A trace whose entries carry no path (recorded before paths existed, or written by hand) is
- * matched positionally: entries are consumed in recorded order and each must name the Command the
- * flow asks for. That is exact for sequential flows and cannot tell `Parallel` branches apart, which
- * is what paths were added to fix.
- *
- * A step the trace does not hold resolves to `undefined`, "not recorded", exactly as it does from a
- * Resolver, so `replayEffect` applies `onMissing` to both. This used to throw a `ReplayError` here,
- * which meant `onMissing: 'execute'` had no effect on a trace. `missing` describes such a step, so the
- * error `replayEffect` raises under `'throw'` still says what the trace lacks.
+ * A step the trace does not hold resolves to `undefined`, as from a Resolver, so `replayEffect` applies
+ * `onMissing` to both; `missing` describes the step for the error.
  *
  * @param {TraceLog | TraceEntry[]} traceLog - A reference-format trace, or a bare array of entries
  * @param {Object} [options]
@@ -1414,11 +1573,10 @@ const fromTrace = (traceLog, options = {}) => {
         return entryToOutcome(entry);
     };
 
-    if (entries.length > 0 && entries.every((e) => typeof e.path === 'string')) {
+    if (entries.length > 0 && entries.every(hasPath)) {
         const byPath = new Map(entries.map((e) => [e.path, e]));
-        // Paths are derived from tree position, so they are unique by construction. A collision means
-        // either a hand-built trace or a bug in path derivation, and silently keeping the last entry
-        // would reintroduce exactly the wrong-result-per-branch failure paths exist to prevent.
+        // Paths are unique by construction, so a collision means a hand-built trace or a bug, and keeping
+        // either entry would hand a branch the wrong result.
         if (byPath.size !== entries.length) {
             throw replayError('Trace has duplicate step paths.');
         }
@@ -1437,8 +1595,7 @@ 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, as
-                // it did before decisions were recorded.
+                // A decision rather than I/O. 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));
@@ -1461,10 +1618,9 @@ const fromTrace = (traceLog, options = {}) => {
     const resolve = (step) => {
         // A trace with no paths predates recorded decisions, so a Parallel replays under timing.
         if (step.type === 'Parallel') return undefined;
-        // Positional matching pairs steps by completion order, which is exactly what makes Parallel
-        // branches indistinguishable. Refusing is better than a result that is right only when the
-        // replay happens to finish in production's order.
-        if (typeof step.path === 'string' && /p\d+\//.test(step.path)) {
+        // Positional matching pairs steps by completion order, which cannot tell Parallel branches apart.
+        // Refusing beats a result that is right only when the replay finishes in production's order.
+        if (isInsideParallel(step.path)) {
             throw replayError(
                 `Trace carries no paths, so '${step.name}' inside a Parallel cannot be matched positionally.`,
                 { command: step.name, path: step.path }
@@ -1479,61 +1635,20 @@ const fromTrace = (traceLog, options = {}) => {
     return { resolve, missing };
 };
 
-/**
- * Rewrites `Retry` nodes to zero delay, lazily, through their `next` continuations.
- *
- * Needed because a delay is written at the call site and nothing outside the node
- * can override it: retry options are per-use only. Without this, replaying a flow
- * that retried in production waits out the production backoff.
- *
- * @param {any} eff - Any Effect node
- * @returns {any} The same tree with Retry delays removed
- */
-const zeroRetryDelays = (eff) => {
-    if (!eff || typeof eff.type !== 'string') return eff;
-    switch (eff.type) {
-        case 'Retry': {
-            const options = { ...eff.options, delay: 0, backoff: 1 };
-            // The fallback tree only exists once onExhausted runs, so it is rewritten lazily too;
-            // otherwise a Retry inside the fallback keeps its production backoff during replay.
-            if (typeof options.onExhausted === 'function') {
-                const original = options.onExhausted;
-                options.onExhausted = (/** @type {any} */ error) => zeroRetryDelays(original(error));
-            }
-            return {
-                ...eff,
-                options,
-                effect: zeroRetryDelays(eff.effect),
-                next: (/** @type {any} */ value) => zeroRetryDelays(eff.next(value))
-            };
-        }
-        case 'Command':
-            return { ...eff, next: (/** @type {any} */ result) => zeroRetryDelays(eff.next(result)) };
-        case 'Ask':
-            return { ...eff, next: (/** @type {any} */ ctx) => zeroRetryDelays(eff.next(ctx)) };
-        case 'Parallel':
-            return {
-                ...eff,
-                effects: eff.effects.map(zeroRetryDelays),
-                next: (/** @type {any} */ values) => zeroRetryDelays(eff.next(values))
-            };
-        default:
-            return eff;
-    }
-};
-
 /**
  * @typedef {Object} ReplayOptions
- * @property {any} [context] - Context for `Ask`; pass the recorded context to reproduce a run faithfully.
- * @property {boolean} [fastRetry] - Strips Retry delays so a replay does not wait out production backoff.
+ * @property {any} [context] - Context for `Ask`; defaults to the context a trace recorded.
+ * @property {boolean} [fastRetry] - Waits no time between Retry attempts, so a replay does not wait out
+ *           production backoff. On by default.
  * @property {boolean} [hooks] - Runs the replay inside the hooks `configureEffect` installed, with the
  *           resolver innermost, so a configured `onStep` observes each replayed step and `onRun` and
  *           `onBeforeCommand` fire. Off by default, which ignores the global hooks, so a replay cannot
- *           reach a telemetry backend or a guardrail that performs I/O. Retry options travel with the
- *           node either way, so a replay makes the attempts production made.
+ *           reach a telemetry backend or a guardrail that performs I/O.
  * @property {'throw' | 'execute'} [onMissing] - What to do when the resolver has no recording for a step.
  *           `'throw'` (default) fails the replay, which makes side effects impossible for the whole run.
- *           `'execute'` runs the real Command, giving partial replay: recorded prefix, live tail.
+ *           `'execute'` runs the real Command, so pass it only where the Commands reach test doubles or only
+ *           read. A trace that dropped entries under `maxEntries` refuses it, since a step it lacks may be one
+ *           production ran.
  * @property {(step: ReplayStep, outcome: ReplayOutcome | undefined) => void} [onResolved] - Observes each step.
  */
 
@@ -1545,8 +1660,7 @@ const zeroRetryDelays = (eff) => {
  * A flow that stops issuing Commands before its recording ends mismatches nothing, so no
  * `TimeParadox` fires and `result` can be a `Success` with recorded steps left over. That is
  * sometimes the point of a fix and sometimes a fix that quietly dropped a step; `unreached` is
- * the only place the difference shows, which is why it travels with the result rather than
- * behind an option.
+ * the only place the difference shows.
  * @typedef {{ result: SuccessState | FailureState, unreached?: TraceEntry[] }} Replay
  */
 
@@ -1569,8 +1683,7 @@ const zeroRetryDelays = (eff) => {
  * @param {ReplayOptions} [options]
  * @returns {Promise<Replay>} `{ result, unreached }` for a trace, `{ result }` for a Resolver
  */
-// `async` so a malformed trace arrives as a rejection rather than a synchronous throw:
-// the function otherwise returns a promise, and callers should not have to handle both.
+// `async` so a malformed trace arrives as a rejection rather than a synchronous throw.
 const replayEffect = async (effect, traceOrResolver, options = {}) => {
     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
@@ -1581,16 +1694,26 @@ const replayEffect = async (effect, traceOrResolver, options = {}) => {
     const { resolve, missing } = fromResolver
         ? { resolve: traceOrResolver, missing: undefined }
         : fromTrace(traceOrResolver, { onEntry: (entry) => void reached.add(entry) });
-    // A trace carries the context production ran with, and `Ask` has to see it for the replay to take the
-    // branches production took. An empty context replayed an `Ask` gate the other way, with no paradox to
-    // flag it, whenever a caller passed only the flow and the trace, as the README's replays do.
-    const recorded = fromResolver || Array.isArray(traceOrResolver) ? undefined : traceOrResolver.context;
-    const context = options.context ?? recorded ?? {};
+    // Only a trace log carries metadata; a bare entries array and a Resolver carry none.
+    const traceLog = fromResolver || Array.isArray(traceOrResolver) ? undefined : traceOrResolver;
+    // Defaults to the trace's context: an `Ask` gate replayed with another one takes another branch, and
+    // no paradox flags it.
+    const context = options.context ?? traceLog?.context ?? {};
+    // A trace capped by `maxEntries` lacks steps production ran, so running a missing step live repeats
+    // production's I/O: a billing batch replayed that way charged and invoiced subscriptions again.
+    const droppedEntries = Number(traceLog?.dropped) || 0;
+    const capped = droppedEntries > 0;
+    if (capped && onMissing === 'execute') {
+        throw replayError(
+            `The trace dropped ${droppedEntries} entries under maxEntries, so a step it lacks may be one ` +
+                "production ran, and onMissing: 'execute' would run it again. Replay without it to stop at the " +
+                'first missing step, or record the flow with a higher maxEntries.'
+        );
+    }
     let index = 0;
-    // What `onResolved` threw, if it did. The throw happened before the recorded result was handed back, so it
-    // counted as the Command failing and a Retry asked for an attempt production never made. It stops the
-    // replay instead, as a throw from any other code in the flow does, and the replay rejects with it. Cast
-    // rather than annotated, since only the step runner assigns it.
+    // What `onResolved` threw. It stops the replay, which rejects with it, rather than counting as the
+    // Command failing, which would let a Retry ask for an attempt production never made. Cast rather than
+    // annotated, since only the step runner assigns it.
     let observerFailure = /** @type {{ error: unknown } | undefined} */ (undefined);
 
     /** @type {StepRunner} */
@@ -1614,11 +1737,21 @@ 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}`;
-                throw replayError(
-                    `${what}; refusing to run the real Command. ` +
-                        `Pass onMissing: 'execute' to allow live I/O for unrecorded steps.`,
-                    { command: name, index: step.index, path }
-                );
+                // 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
+                });
             }
             return await op();
         }
@@ -1626,25 +1759,19 @@ const replayEffect = async (effect, traceOrResolver, options = {}) => {
         return outcome.result;
     };
 
-    // Off, a replay ignores the global hooks, so it can reach neither a telemetry backend nor a guardrail
-    // that performs I/O. On, it runs inside them with the resolver innermost, so a configured onStep
-    // observes each replayed step and the Command still never executes. Retry shape needs nothing from
-    // the wiring either way, since retry options live on the node: a replay makes the attempts production
-    // made whichever way this is set.
+    // With `hooks` off the replay ignores the global wiring, so it reaches no telemetry backend or
+    // guardrail. On, the resolver sits innermost and a configured onStep observes each replayed step.
     /** @type {CallConfiguration} */
     const callConfig = { onStep, inherit: hooks };
 
-    // The interpreter rethrows a replay fault rather than folding it into a `Failure`, so that neither
-    // `onExhausted` nor a settled `Parallel` can absorb one: a truncated trace used to replay as a
-    // `Success` whose branches each carried the ReplayError as though production had returned it. It
-    // becomes a `Failure` here instead, which is the shape this function has always returned and the
-    // one place where nothing downstream can catch it.
+    // The interpreter rethrows a replay fault so nothing in the flow can absorb it; it becomes a Failure
+    // here, where nothing downstream can.
     let result;
     try {
-        result = await runEffect(fastRetry ? zeroRetryDelays(effect) : effect, context, callConfig);
+        result = await interpret(effect, context, callConfig, fastRetry);
     } catch (e) {
         if (observerFailure) throw observerFailure.error;
-        if (!(e && /** @type {any} */ (e)[replayFault])) throw e;
+        if (!hasMark(e, replayFault)) throw e;
         result = Failure(e, effect.initialInput);
     }
     if (fromResolver) return { result };
@@ -1670,9 +1797,8 @@ const replayEffect = async (effect, traceOrResolver, options = {}) => {
 const timeTravel = async (flowFn, traceLog, options = {}) => {
     const { log = console.log, context, version } = options;
     const { initialInput, trace, flowName, version: traceVersion } = traceLog;
-    // `message` and `stack` are non-enumerable on Error, so JSON.stringify alone would
-    // drop the most useful line of the report. It throws on a BigInt and on a cycle, both of which a
-    // recorded result can hold, and narration must not be what fails a replay.
+    // `message` is non-enumerable on Error, so JSON.stringify alone would drop it. JSON.stringify throws on
+    // a BigInt and on a cycle, and narration must not be what fails a replay.
     const format = (/** @type {any} */ v) => {
         try {
             return JSON.stringify(v instanceof Error ? { ...v, name: v.name, message: v.message } : v, null, 2);
@@ -1684,19 +1810,32 @@ const timeTravel = async (flowFn, traceLog, options = {}) => {
     if (version && traceVersion && version !== traceVersion) {
         log(`Warning: trace was recorded at ${traceVersion}, replaying against ${version}.`);
     }
-    // Parallel decisions are recorded alongside the Commands but are not narrated as steps, so the header
-    // counts Commands and its step numbers match the lines below.
+    // The flow is rebuilt from this input, and a recorder installed as a hook reads it off the flow, where only
+    // effectPipe puts it.
+    if (initialInput === undefined) {
+        log(
+            'Warning: the trace holds no initial input, so the flow is rebuilt from undefined. A recorder ' +
+                'installed as a hook finds the input only on a flow built with effectPipe.'
+        );
+    }
+    // A replay tells steps apart by name, so two anonymous Commands that swapped places replay without complaint.
+    const anonymous = trace.filter((e) => e.command === 'anonymous').length;
+    if (anonymous > 0) {
+        log(
+            `Warning: ${anonymous} of the recorded steps are named 'anonymous', usually inline arrow Commands, so ` +
+                'this replay cannot tell them apart and would not notice two of them trading places. Name them with ' +
+                'a const or meta.name.'
+        );
+    }
+    // Parallel decisions are not narrated as steps, so the header counts Commands to match the lines below.
     const commandCount = trace.filter((e) => !isDecisionEntry(e)).length;
     const stepsText = commandCount === 1 ? 'step' : 'steps';
     log(`Replaying '${flowName || 'flow'}' (${commandCount} recorded ${stepsText})`);
     log(`Initial input: ${format(initialInput)}`);
 
-    // Narration goes through `onResolved` rather than a wrapped Resolver: observing each
-    // step is all this needs, and `replayEffect` already resolves the trace itself.
-    // A path maps a replayed step back to its recorded entry whatever order branches finished in, so
-    // timings are narrated for Parallel too. Positional lookup is the fallback for a trace with no paths,
-    // which is how such a trace is matched anyway.
-    const byPath = new Map(trace.filter((e) => typeof e.path === 'string').map((e) => [e.path, e]));
+    // Timings are looked up by path, whatever order branches finished in, or by position for a trace
+    // with no paths, which is how such a trace is matched anyway.
+    const byPath = new Map(trace.filter(hasPath).map((e) => [e.path, e]));
     const timing = (/** @type {ReplayStep} */ step) => {
         const recorded = byPath.get(step.path) ?? trace[step.index];
         return typeof recorded?.durationMs === 'number' ? ` in ${recorded.durationMs}ms` : '';
@@ -1717,15 +1856,12 @@ 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, so the entries behind it are not
-    // news; the error already names where the timeline split. Only a flow that ended on its own terms
-    // with steps left over is worth a warning.
+    // 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);
     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) =>
-            typeof e.path === 'string' ? `${e.command} (path '${e.path}')` : e.command
-        );
+        const names = unreached.map((e) => (hasPath(e) ? `${e.command} (path '${e.path}')` : e.command));
         const count = unreached.length === 1 ? '1 recorded step was' : `${unreached.length} recorded steps were`;
         log(`Warning: ${count} never reached: ${names.join(', ')}. The flow diverged.`);
     }
@@ -1745,5 +1881,6 @@ export {
     recorder,
     recordEffect,
     replayEffect,
-    timeTravel
+    timeTravel,
+    commandName
 };