pure-effect 0.13.0 → 0.15.0

package/index.js

@@ -34,11 +34,18 @@
  * }} RetryState
  */
 
+/**
+ * `settled` hands branch outcomes to `next` instead of failing on the first one; `limit` caps how many
+ * branches run at once.
+ * @typedef {{ limit?: number, settled?: boolean }} ParallelOptions
+ */
+
 /**
  * @typedef {{
  *   type: 'Parallel',
  *   effects: Effect[],
  *   next: (values: any[]) => Effect,
+ *   options?: ParallelOptions,
  *   initialInput?: any
  * }} ParallelState
  */
@@ -72,36 +79,45 @@ 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'.
  *
  * @param {CommandState} eff
  * @returns {string}
  */
 const commandName = (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';
 };
 
@@ -110,7 +126,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.
@@ -121,121 +142,253 @@ const Ask = (next) => ({ type: 'Ask', next });
  * every Command in it is idempotent.
  *
  * @param {Effect} effect - The inner Effect tree to retry
- * @param {Object} [options] - Per-use retry options; merged over global defaults at runtime
- * @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. When several branches fail in the
- * same tick, the first by array order wins.
+ * 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, `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. `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} [next] - Receives array of success values in order, returns next Effect.
- *        Defaults to `(values) => Success(values)`, same as `Command`'s default.
+ * @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 or skipped
  * @returns {ParallelState}
  */
-const Parallel = (effects, next = (/** @type {any[]} */ values) => Success(values)) => ({
-    type: 'Parallel',
-    effects,
-    next
-});
+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;
+    if (!hasNext && !nextSkipped && !isOptionsObject(nextOrOptions)) {
+        const got = describeArgument(nextOrOptions);
+        throw malformed(`Parallel's second argument must be next or the options, got ${got}.`, nextOrOptions);
+    }
+    const options = hasNext || nextSkipped ? maybeOptions : nextOrOptions;
+    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: 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'
-          : 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)}`;
-
-/**
- * Checks that a value is an Effect, and explains the mistake when it is not.
+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');
+
+/**
+ * @param {Error} error
+ * @returns {Error}
+ */
+const asHarnessError = (error) => Object.defineProperty(error, harnessError, { value: true });
+
+/**
+ * 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
+ */
+
+/**
+ * @param {any} error
+ * @param {any} [initialInput]
+ * @returns {IoFaultState}
+ */
+const IoFault = (error, initialInput) => ({ type: 'IoFault', error, initialInput });
+
+/**
+ * @param {SuccessState | FailureState | IoFaultState} state
+ * @returns {SuccessState | FailureState}
+ */
+const asOutcome = (state) => (state.type === 'IoFault' ? Failure(state.error, state.initialInput) : state);
+
+/**
+ * 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) =>
-    Object.assign(
-        new Error(
-            `${source} returned ${describeValue(value)}. Return Success, Failure, Command, Ask, Retry, or Parallel: ` +
-                'a plain value has to be wrapped, as in Success(value).'
-        ),
-        { name: 'EffectTypeError' }
+    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
     );
 
+/**
+ * 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
  * @param {string} 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);
 };
 
 /**
  * Connects an Effect to the next function in the pipeline.
- * Handles the branching logic for Success, Failure, Command, Ask, and Retry.
+ * Handles the branching logic for Success, Failure, Command, Ask, Retry, and Parallel.
  *
  * @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
  * @returns {Effect} The composed Effect
  */
-/**
- * @param {Effect} effect
- * @param {(value: any) => Effect} fn
- * @param {any} [initialInput]
- * @returns {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.
+    // 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, and since every continuation runs inside the interpreter's try
-    // block, that TypeError became a domain Failure: the flow bug took the business-error branch and no
-    // step was named. The `default` arm below never sees it, because the switch itself is what throws.
+    // Checked before `effect.type` is read, which would otherwise throw a bare TypeError naming no step.
     if (effect == null) return asEffect(effect, 'A continuation');
 
     switch (effect.type) {
@@ -272,24 +425,30 @@ 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);
     };
 };
 
 /**
- * Wraps one Command execution. `path` identifies the Command'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.
+ * 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` 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 */
@@ -305,22 +464,30 @@ const defaultCommandInterceptor = async (command, context) => {};
 
 const defaultRetryOptions = { attempts: 3, delay: 100, backoff: 1 };
 
+/**
+ * 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 (isObject(config) && 'retry' in config)
+        throw new TypeError(
+            `${source} no longer takes 'retry'. Retry options are per-use: pass them to Retry(effect, options).`
+        );
+};
+
 /**
  * @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.
- * @property {{ attempts?: number, delay?: number, backoff?: number }} [retry] - Global Retry defaults; merged under per-use options.
  */
 
 /**
  * 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, `retry` merging with the
- * call winning. 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
  */
@@ -329,10 +496,8 @@ const defaultRetryOptions = { attempts: 3, delay: 100, backoff: 1 };
 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 = {};
@@ -343,40 +508,34 @@ const applyLayers = () => {
 };
 
 /**
- * Adds a configuration to the global wiring of the Effect runner: telemetry, the command interceptor,
- * and retry defaults.
+ * Adds a configuration to the global wiring of the Effect runner: telemetry and the command
+ * interceptor. Retry options are not part of it; they are per-use, passed to `Retry(effect, options)`.
  *
  * Each call adds one layer on top of those already installed and returns a function that removes that
  * layer, wherever it sits by then. Layers merge the way several configurations passed to one call do:
  * `onStep` and `onRun` are wrappers, so they nest with the earliest layer outermost and the latest
- * closest to the Command; `onBeforeCommand` interceptors all run, in the order installed; and `retry`
- * merges with later layers winning. So these are the same:
+ * closest to the Command; and `onBeforeCommand` interceptors all run, in the order installed. So these
+ * are the same:
  *
  *     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);
+    // 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);
     layers = [...layers, layer];
@@ -390,8 +549,8 @@ const configureEffect = (...configs) => {
 
 /**
  * @typedef {Object} StepStart
- * @property {string} name - `cmd.name`, or 'anonymous'.
- * @property {string} type - Always 'Command' today.
+ * @property {string} name - The Command's identity: `meta.name`, else `cmd.name`, else 'anonymous'.
+ * @property {string} type - 'Command', or 'Parallel' for a Parallel's decision.
  * @property {string} [path] - The Command's position in the Effect tree.
  */
 
@@ -408,7 +567,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}
@@ -443,12 +603,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. `retry` is plain data and merges with later
- * configs winning. A hook no config defines is left unset, so `configureEffect` 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}
@@ -465,7 +623,6 @@ const chainHooks = (...configs) => {
     const steps = /** @type {StepRunner[]} */ (present('onStep'));
     const runs = /** @type {RunWrapper[]} */ (present('onRun'));
     const interceptors = /** @type {CommandInterceptor[]} */ (present('onBeforeCommand'));
-    const retries = present('retry');
 
     if (steps.length) {
         merged.onStep = steps.reduceRight(
@@ -482,27 +639,115 @@ const chainHooks = (...configs) => {
             for (const intercept of interceptors) await intercept(command, context);
         };
     }
-    if (retries.length) merged.retry = Object.assign({}, ...retries);
     return merged;
 };
 
 /**
- * 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.
+ * 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 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.
+ * It is recorded as the Parallel's own step, since it is decided by timing and a replay cannot recompute it.
+ * @typedef {{ cancelled: false } | { cancelled: true, branch: number | null }} ParallelDecision
+ */
+
+/**
+ * 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 (!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 isBranchIndex(branch, branches) ? { cancelled: true, branch } : undefined;
+};
+
+/**
+ * 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');
+
+/**
+ * @param {string} path
  * @returns {Error}
  */
-const parallelCancelled = () =>
-    Object.assign(new Error('Parallel branch cancelled.'), {
-        name: 'ParallelCancelled'
-    });
+const replayCutError = (path) =>
+    Object.defineProperty(
+        asHarnessError(new Error(`Replay stopped a cancelled Parallel branch at path '${path}'.`)),
+        replayCut,
+        { value: true }
+    );
+
+/**
+ * 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 };
+};
 
 /**
- * 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.
+ * 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>}
+ */
+const runBounded = async (tasks, limit) => {
+    if (!limit || limit >= tasks.length) {
+        await Promise.all(tasks.map((task) => task()));
+        return;
+    }
+    let cursor = 0;
+    const worker = async () => {
+        for (let i = cursor++; i < tasks.length; i = cursor++) await tasks[i]();
+    };
+    await Promise.all(Array.from({ length: limit }, worker));
+};
+
+/**
+ * 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]
@@ -514,6 +759,12 @@ const delayFor = (ms, signal) =>
             setTimeout(resolve, ms);
             return;
         }
+        // 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;
+        }
         const onAbort = () => {
             clearTimeout(timer);
             resolve();
@@ -525,197 +776,384 @@ 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;
         const localRunWrapper = resolved.onRun || defaultRunWrapper;
         const localCommandInterceptor = resolved.onBeforeCommand || defaultCommandInterceptor;
-        const localRetryDefaults = { ...defaultRetryOptions, ...resolved.retry };
 
         /**
+         * 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.
-         * @returns {Promise<SuccessState | FailureState>}
+         * @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);
+            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') {
                     eff = eff.next(context);
                     continue;
                 }
-                if (eff.type === 'Retry') {
-                    const opts = { ...localRetryDefaults, ...eff.options };
-                    const { attempts } = opts;
-                    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;
-                        }
-                        lastError = result.error;
-                    }
-
-                    if (!succeeded) {
-                        const exhausted = { retryExhausted: true, lastError, attempts };
-                        const { onExhausted } = opts;
-                        if (typeof onExhausted !== 'function') return Failure(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 === 'Failure') 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.
+                eff = eff.next(outcome.value);
+            }
+            if (isOutcome(eff)) return eff;
+            throw effectTypeError(eff, '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`;
-                    // 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.
-                    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 });
-                    }
-
-                    /** @type {(SuccessState | FailureState)[]} */
-                    const results = new Array(eff.effects.length);
-                    // Which branch failed on its own account rather than because it was cancelled.
-                    const triggered = new Array(eff.effects.length).fill(false);
-                    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 Promise.all(
-                            eff.effects.map(async (e, i) => {
-                                const result = await execute(e, branchSignal, `${branchPath}${i}/`);
-                                results[i] = result;
-                                // Read-then-abort is atomic here, so exactly one branch is the trigger.
-                                if (result.type === 'Failure' && !branchSignal?.aborted) {
-                                    triggered[i] = true;
-                                    scope?.abort();
-                                }
-                            })
-                        );
-                    } finally {
-                        if (signal && scope) signal.removeEventListener('abort', relay);
-                    }
-
-                    const trigger = triggered.indexOf(true);
-                    const failure = trigger >= 0 ? results[trigger] : results.find((r) => r.type === 'Failure');
-                    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;
-                // The signal reaches the thunk only inside a Parallel, so a thunk written to take a
-                // parameter is not handed an argument it never expected anywhere else.
-                const op = signal ? () => cmd(signal) : cmd;
+                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);
-                    const result = await localStepRunner(cmdName, 'Command', op, cmdPath);
-                    eff = eff.next(result);
-                } catch (e) {
-                    // A malformed flow is a bug, not a domain failure, so it must not masquerade as one.
-                    if (e instanceof Error && e.name === 'EffectTypeError') throw e;
-                    return Failure(e, initialInput);
+                    results[i] = await execute(branch, scope?.signal, `${branchPath}${i}/`);
+                } catch (error) {
+                    thrown[i] = { error };
+                }
+                // 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();
                 }
+            };
+            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.
+        /**
+         * 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 = await execute(effect);
+            const result = asOutcome(await execute(effect));
             return result.type === 'Failure' && rootInput !== undefined ? Failure(result.error, rootInput) : result;
         };
         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
- * containing `Parallel`. Prefer `path` when writing a Resolver.
+ * containing `Parallel`. Prefer `path` when writing a Resolver. A step whose `type` is 'Parallel' asks
+ * for a Parallel's recorded decision; it does not advance `index`, and anything but a decision replays
+ * that Parallel under timing.
  * @typedef {{ index: number, name: string, type: string, path?: string }} ReplayStep
  */
 
@@ -730,11 +1168,12 @@ const runEffect =
 /** @typedef {(step: ReplayStep) => ReplayOutcome | undefined} Resolver */
 
 /**
- * A recorded step. `durationMs` is how long the Command 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.
- * @typedef {{ command: string, path?: string, result?: any, error?: any, durationMs?: number }} TraceEntry
+ * 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. `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
  */
 
 /**
@@ -751,13 +1190,27 @@ const runEffect =
  */
 
 /**
- * Creates a replay error. Thrown from a resolver, it is caught by the interpreter
- * and returned as a Failure, exactly like a rejected Command.
+ * 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, 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}
  */
-const replayError = (message, props = {}) => Object.assign(new Error(message), { name: 'ReplayError' }, props);
+const replayError = (message, props = {}) =>
+    Object.defineProperty(
+        asHarnessError(Object.assign(new Error(message), { name: 'ReplayError' }, props)),
+        replayFault,
+        {
+            value: true
+        }
+    );
 
 /**
  * Signals that the flow being replayed asked for a different Command than the trace
@@ -785,19 +1238,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);
-    for (const k of Object.keys(e)) out[k] = /** @type {any} */ (e)[k];
+    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;
+    const hasHiddenErrors = Array.isArray(errors) && !Object.prototype.propertyIsEnumerable.call(e, 'errors');
+    if (hasHiddenErrors) {
+        out.__errors = errors.map((x) => serializeError(x, withStack, ancestors));
+    }
+    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.
@@ -805,18 +1280,22 @@ 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) });
+        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;
@@ -828,7 +1307,8 @@ const reviveError = (v) => {
  *           each Command's result, each serialized error, and the `initialInput` and `context` stored on the
  *           trace itself. `kind` is `'result'`, `'error'`, `'initialInput'`, or `'context'`, and `name` is the
  *           Command's name for the first two and the kind for the last two. It is the single place PII is kept
- *           out of a trace, so it has to see all four.
+ *           out of a trace, so it has to see all four. It is handed a copy, so changing the value in place
+ *           never reaches the run.
  * @property {number} [maxEntries] - Caps trace length; further steps are counted in `dropped`, not stored.
  * @property {boolean} [stack] - Records stack traces for thrown errors.
  */
@@ -842,29 +1322,66 @@ const reviveError = (v) => {
  */
 
 /**
- * Snapshots a value on its way into a 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.
  *
- * 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. Values
- * that cannot be cloned fall back to the reference.
+ * @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 (!isObject(value)) return value;
+    if (seen.has(value)) return seen.get(value);
+    if (!isPlainContainer(value)) {
+        try {
+            return structuredClone(value);
+        } catch {
+            return value;
+        }
+    }
+    /** @type {any} */
+    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, 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 {
-        return value;
+        return copyAround(value, new Map());
     }
 };
 
 /**
  * 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 }}
@@ -880,9 +1397,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);
@@ -892,29 +1407,34 @@ const recorder = (options = {}) => {
     };
 
     /**
-     * Redacts and snapshots one of the trace's own fields. `undefined` is left alone so a flow with no
+     * Snapshots one of the trace's own fields and redacts the copy. `undefined` is left alone so a flow with no
      * context does not acquire an empty object from a redact function that spreads its argument.
      */
     const redactField = (/** @type {any} */ value, /** @type {string} */ kind) =>
-        value === undefined ? undefined : snapshot(safeRedact(value, kind, kind));
+        value === undefined ? undefined : safeRedact(snapshot(value), kind, kind);
 
-    // Built on `observe` 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, path }) => (end) => {
+    const onStep = observeSteps(({ name, type, path }) => (end) => {
         const durationMs = Math.round(end.durationMs * 1000) / 1000;
+        // 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(
             'error' in end
                 ? {
                       command: name,
                       path,
-                      error: snapshot(safeRedact(serializeError(end.error, stack), name, 'error')),
+                      threw: true,
+                      error: safeRedact(snapshot(serializeError(end.error, stack)), name, 'error'),
                       durationMs
                   }
-                : { command: name, path, result: snapshot(safeRedact(end.result, name, 'result')), durationMs }
+                : { command: name, path, result: recorded(end.result), durationMs }
         );
     });
 
     /**
+     * Redacts and copies `meta.initialInput` and `meta.context` when it is called, so call it before the run
+     * when the run can change them, and take `dropped` and `trace` from a second call once it ends.
      * @param {TraceMeta} [meta]
      * @returns {TraceLog}
      */
@@ -932,8 +1452,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
@@ -944,43 +1464,74 @@ const recorder = (options = {}) => {
 const recordEffect = async (flowFn, initialInput, options = {}) => {
     const { context = {}, version, ...recorderOptions } = options;
     const rec = recorder(recorderOptions);
-    // The recorder is added to the global wiring, so recording inside an instrumented application keeps
-    // its spans.
+    // 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 });
+    // Merged over the global wiring, so recording inside an instrumented application keeps its spans.
     const result = await runEffect(flowFn(initialInput), context, { onStep: rec.onStep });
-    return {
-        result,
-        trace: rec.toTrace({ initialInput, flowName: context.flowName, context, version })
-    };
+    const { dropped, trace } = rec.toTrace();
+    return { result, trace: { ...head, dropped, trace } };
 };
 
 /**
- * Turns a recorded entry into the outcome a Resolver must return.
+ * 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) => ('error' in entry ? { error: reviveError(entry.error) } : { result: entry.result });
+const entryToOutcome = (entry) =>
+    entryThrew(entry) ? { error: reviveError(snapshot(entry.error)) } : { result: snapshot(entry.result) };
 
 /**
- * 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.
+ * Whether an entry is a Parallel's recorded decision rather than a Command's result. A Parallel's path
+ * ends in its `p` marker and a Command's in its step number, so a Command that happens to be named
+ * 'Parallel' is never mistaken for one.
+ * @param {TraceEntry} entry
+ * @returns {boolean}
+ */
+const isDecisionEntry = (entry) =>
+    entry.command === 'Parallel' && typeof entry.path === 'string' && entry.path.endsWith('p');
+
+/**
+ * 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`, 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]
  * @param {(entry: TraceEntry) => void} [options.onEntry] - Observes each entry as it is handed to a step,
  *        which is how `replayEffect` learns which recorded entries the flow never asked for.
- * @returns {Resolver}
+ * @returns {{ resolve: Resolver, missing: (step: ReplayStep) => string }}
  */
 const fromTrace = (traceLog, options = {}) => {
     const { onEntry } = options;
@@ -991,97 +1542,77 @@ 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.');
         }
-        return (step) => {
+        /** Recorded Parallel decisions that cancelled branches, by the Parallel's path. */
+        const cancellations = entries.filter(isDecisionEntry).filter((e) => e.result?.cancelled === true);
+        // A missing step is where production stopped a branch when it lies in a branch a recorded decision
+        // cancelled: any branch but the cancelling one, or every branch of a Parallel cancelled from outside.
+        const stoppedInProduction = (/** @type {string | undefined} */ stepPath) =>
+            typeof stepPath === 'string' &&
+            cancellations.some((e) => {
+                const at = /** @type {string} */ (e.path);
+                const branch = stepPath.startsWith(at) ? /^(\d+)\//.exec(stepPath.slice(at.length)) : null;
+                return branch !== null && (e.result.branch === null || Number(branch[1]) !== e.result.branch);
+            });
+        /** @type {Resolver} */
+        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.
+                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));
+                return undefined;
+            }
             if (!entry) {
-                throw replayError(`Trace has no step at path '${step.path}' for '${step.name}'.`, {
-                    command: step.name,
-                    path: step.path
-                });
+                // Production never ran this step, so it is not run live under `onMissing` either.
+                if (stoppedInProduction(step.path)) throw replayCutError(/** @type {string} */ (step.path));
+                return undefined;
             }
             if (entry.command !== step.name) throw timeParadox(step, entry.command);
             return resolveEntry(entry);
         };
+        const missing = (/** @type {ReplayStep} */ step) =>
+            `Trace has no step at path '${step.path}' for '${step.name}'`;
+        return { resolve, missing };
     }
 
-    return (step) => {
-        // 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)) {
+    /** @type {Resolver} */
+    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 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 }
             );
         }
         const entry = entries[step.index];
-        if (!entry) throw replayError(`Trace exhausted: no entry #${step.index} for '${step.name}'.`);
+        if (!entry) return undefined;
         if (entry.command !== step.name) throw timeParadox(step, entry.command);
         return resolveEntry(entry);
     };
-};
-
-/**
- * Rewrites `Retry` nodes to zero delay, lazily, through their `next` continuations.
- *
- * Needed because the interpreter merges per-use options over call config
- * (`{ ...localRetryDefaults, ...eff.options }`), so a `callConfig.retry` cannot
- * override a delay written at the call site. 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;
-    }
+    const missing = (/** @type {ReplayStep} */ step) => `Trace exhausted: no entry #${step.index} for '${step.name}'`;
+    return { resolve, missing };
 };
 
 /**
  * @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. Global `retry` defaults apply
- *           either way, since a replay has to make 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.
@@ -1096,8 +1627,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
  */
 
@@ -1105,7 +1635,7 @@ const zeroRetryDelays = (eff) => {
  * Replays an Effect tree, feeding recorded results to Commands instead of running them.
  *
  * No side effect can occur by default. The interpreter's only execution point is
- * `await localStepRunner(cmdName, 'Command', eff.cmd)`, which hands the Command thunk
+ * `await localStepRunner(cmdName, 'Command', op, cmdPath)`, which hands the Command thunk
  * to `onStep` as `op` rather than calling it. The `onStep` installed here never invokes
  * `op` unless `onMissing: 'execute'` is set, so `eff.cmd` is never applied and the I/O
  * it describes does not happen.
@@ -1120,31 +1650,56 @@ 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 { context = {}, fastRetry = true, hooks = false, onMissing = 'throw', onResolved } = 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
     // apart, including the bare entries array that `fromTrace` also accepts.
     const fromResolver = typeof traceOrResolver === 'function';
     /** @type {Set<TraceEntry>} */
     const reached = new Set();
-    const resolve = fromResolver
-        ? traceOrResolver
+    const { resolve, missing } = fromResolver
+        ? { resolve: traceOrResolver, missing: undefined }
         : fromTrace(traceOrResolver, { onEntry: (entry) => void reached.add(entry) });
+    // Defaults to the trace's context: an `Ask` gate replayed with another one takes another branch, and
+    // no paradox flags it.
+    const recorded = fromResolver || Array.isArray(traceOrResolver) ? undefined : traceOrResolver.context;
+    const context = options.context ?? recorded ?? {};
     let index = 0;
+    // 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} */
     const onStep = async (name, type, op, path) => {
+        if (type === 'Parallel') {
+            // A Parallel's step carries its recorded decision into `op`, which runs the branches under it.
+            // It is not a Command: `index` still counts Commands, and `onResolved` still sees only them.
+            const outcome = resolve({ index, name, type, path });
+            return await op(outcome && 'result' in outcome ? outcome.result : undefined);
+        }
         const step = { index: index++, name, type, path };
         const outcome = resolve(step);
-        if (onResolved) onResolved(step, outcome);
+        if (onResolved) {
+            try {
+                onResolved(step, outcome);
+            } catch (error) {
+                observerFailure ??= { error };
+                throw asHarnessError(new Error('onResolved threw.'));
+            }
+        }
         if (outcome === undefined) {
             if (onMissing !== 'execute') {
+                const what = missing ? missing(step) : `No recorded outcome for '${name}' at step ${step.index}`;
+                // The option is named with its one safe use, since a step with no entry may be one production
+                // never ran, and running it live would do I/O production refused.
                 throw replayError(
-                    `No recorded outcome for '${name}' at step ${step.index}; refusing to run the real Command. ` +
-                        `Pass onMissing: 'execute' to allow live I/O for unrecorded steps.`,
-                    { command: name, index: step.index }
+                    `${what}; refusing to run the real Command. Production may never have run it: a Command ` +
+                        'an onBeforeCommand hook vetoed leaves no entry, and neither does a step added since the ' +
+                        "recording. Pass onMissing: 'execute' to run unrecorded steps live only when the trace was " +
+                        'cut short, as by maxEntries.',
+                    { command: name, index: step.index, path }
                 );
             }
             return await op();
@@ -1153,16 +1708,21 @@ 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. The global retry defaults are
-    // kept either way: `inherit: false` would drop them with the hooks, and a Retry that production ran
-    // under a configured `attempts` would then exhaust early on replay and report a Failure production
-    // never saw. Retry shape is part of what a replay reproduces; the hooks are not.
+    // 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, retry: globalConfig.retry };
+    const callConfig = { onStep, inherit: hooks };
 
-    const result = await runEffect(fastRetry ? zeroRetryDelays(effect) : effect, context, callConfig);
+    // 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 interpret(effect, context, callConfig, fastRetry);
+    } catch (e) {
+        if (observerFailure) throw observerFailure.error;
+        if (!hasMark(e, replayFault)) throw e;
+        result = Failure(e, effect.initialInput);
+    }
     if (fromResolver) return { result };
     // `fromTrace` has already validated the shape, so the entries are here in one form or the other.
     const entries = Array.isArray(traceOrResolver) ? traceOrResolver : traceOrResolver.trace;
@@ -1186,26 +1746,36 @@ 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.
-    const format = (/** @type {any} */ v) =>
-        v instanceof Error
-            ? JSON.stringify({ ...v, name: v.name, message: v.message }, null, 2)
-            : JSON.stringify(v, null, 2);
+    // `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);
+        } catch {
+            return String(v);
+        }
+    };
 
     if (version && traceVersion && version !== traceVersion) {
         log(`Warning: trace was recorded at ${traceVersion}, replaying against ${version}.`);
     }
-    const stepsText = trace.length === 0 || trace.length > 1 ? 'steps' : 'step';
-    log(`Replaying '${flowName || 'flow'}' (${trace.length} recorded ${stepsText})`);
+    // 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.'
+        );
+    }
+    // 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` : '';
@@ -1213,7 +1783,7 @@ const timeTravel = async (flowFn, traceLog, options = {}) => {
     const replay = await replayEffect(flowFn(initialInput), traceLog, {
         context: context !== undefined ? context : traceLog.context || {},
         onResolved: (step, outcome) => {
-            // Resolving from a trace either answers or throws, so this is never undefined.
+            // A step the trace does not hold is refused or run live by `replayEffect`, not narrated here.
             if (outcome === undefined) return;
             log(
                 'error' in outcome
@@ -1226,15 +1796,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.`);
     }