pure-effect 0.9.0 → 0.10.0

package/CLAUDE.md

@@ -14,7 +14,7 @@ npx esbuild index.js --minify --format=esm | gzip -9 | wc -c    # the size the R
 
 No build or lint step: the library ships as plain ES modules with no transpilation. Formatting is Prettier, configured in `.prettierrc`; match it when editing.
 
-The README's badge and feature bullet both state a minified-and-gzipped ceiling, currently under 3.4 KB against a measured 3,394 bytes. Re-measure with the command above after adding anything to `index.js`, because the badge is a static `img.shields.io/badge/` URL with the number written into it rather than a live query, so it cannot correct itself.
+The README's badge and feature bullet both state a minified-and-gzipped ceiling, currently under 4 KB. Re-measure with the command above after adding anything to `index.js`, because the badge is a static `img.shields.io/badge/` URL with the number written into it rather than a live query, so it cannot correct itself.
 
 **Markdown prose has no hard line breaks.** Write each paragraph and each list item as one line and let the editor soft-wrap; never wrap prose at a column. Hard breaks make later edits reflow whole paragraphs, turning a one-word change into a multi-line diff. `proseWrap: never` enforces this, so `npm run format` unwraps any prose that arrives wrapped. Even so, write it unwrapped in the first place rather than relying on the sweep, since a wrapped paragraph reads as an intended shape until something reflows it. Fenced code blocks are untouched by the setting, and table rows stay one per line; only prose joins.
 
@@ -33,7 +33,7 @@ The README's badge and feature bullet both state a minified-and-gzipped ceiling,
 | `Command(cmdFn, nextFn, meta)` | `{ type: 'Command', cmd, next, meta }` | Defers a side effect for the interpreter; `meta.name` sets the Command's identity |
 | `Ask(nextFn)` | `{ type: 'Ask', next }` | Reads the `context` passed to `runEffect`; passes it to `nextFn` |
 | `Retry(effect, options)` | `{ type: 'Retry', effect, options, next }` | Wraps any Effect tree with retry-on-failure semantics; handled natively by the interpreter |
-| `Parallel(effects, next)` | `{ type: 'Parallel', effects, next }` | Runs multiple Effect trees concurrently via `Promise.all`; returns the first Failure by array order if any effect fails; context flows into all branches |
+| `Parallel(effects, next)` | `{ type: 'Parallel', effects, next }` | Runs multiple Effect trees concurrently; the first branch to fail cancels its siblings and its Failure is returned; context flows into all branches |
 | `effectPipe(...fns)` | n/a | Composes functions into a sequential pipeline via `chain` |
 | `runEffect(effect, context, callConfig?)` | async | Interpreter: traverses the effect tree, executes Commands; resolves `Ask` and `Retry`; per-call `callConfig` overrides global defaults |
 | `configureEffect(...configs)` | n/a | Sets process-wide telemetry hooks (`onStep`, `onRun`, `onBeforeCommand`) and global `retry` defaults; merges several configurations into one wiring; returns a restore function; overridden by per-call `callConfig` |
@@ -122,7 +122,7 @@ Three semantics are surprising enough that `Documented sharp edges` in the test
 
 `Retry` repeats the entire wrapped tree on every attempt, including Commands that already succeeded, because the retry loop calls `execute(eff.effect)` again rather than resuming. `Retry(effectPipe(charge, receipt))` charges three times when the receipt step fails twice, and the run still reports `Success`. The semantics are defensible, since retry means run this tree again, but the README's "wraps any Effect tree" invites exactly the dangerous construction, so both the JSDoc and the Retry section now say to wrap the failing Command instead. If this is ever changed to resume rather than repeat, the pinning test is the one to read first.
 
-`Parallel` has no cancellation. Branches are collected with `Promise.all` and the first `Failure` is chosen afterwards, so a failing branch does not stop its siblings from performing I/O.
+`Parallel` cancellation is cooperative. The first branch to fail aborts an `AbortController` scoped to that `Parallel`, linked to the enclosing one so cancellation nests. Two levels of effect follow. A cancelled branch starts no further Commands, checked at the top of `execute`'s loop, which needs nothing from user code and is where most of the benefit is. Stopping the Command already in flight needs its thunk to accept the `AbortSignal` it is handed, which is why `cmd` is now called as `cmd(signal)` inside a `Parallel` and with no argument anywhere else: passing an argument only where it means something keeps a thunk written as `(x) => ...` from silently receiving one. A thunk that ignores the signal runs to completion, so a branch whose first Command is a write can still write after a sibling has failed, which is what the pinning test covers. `Parallel` still awaits every branch before returning, deliberately: returning early would leave cancelled work running unobserved after the Failure, with its rejections unhandled. The triggering branch is tracked separately from branches that failed because they were cancelled, so a cancellation never displaces the real error; when several branches fail in the same tick the first by array order wins, which is the older documented behaviour and is pinned.
 
 Every `Failure` carries `initialInput`, stamped by `chain`, alongside the full error. Neither is trimmed and neither should be: a test asserting on a Failure and a developer reading one both need the whole thing. PII control is split deliberately. `redact` is the single mechanism for a trace, and the shell owns what reaches logs, so the guidance is to log `result.error` rather than serialize a whole Failure.
 
@@ -135,7 +135,9 @@ Because a flow is data, a production run can be recorded and replayed later. Rec
 Four invariants hold the design together; breaking any of them breaks replay in a way tests may not catch:
 
 - **Replay drives the real interpreter.** `replayEffect` calls `runEffect` rather than walking the tree itself, which is why `Ask`, `Retry`, and `Parallel` replay correctly and why replay semantics cannot drift from execution semantics. The interpreter's only execution point is `await localStepRunner(cmdName, 'Command', eff.cmd)`, which hands the Command thunk to `onStep` as `op` instead of calling it. Replay's `onStep` never invokes `op` unless `onMissing: 'execute'`, so **no side effect can occur by default**. Preserve that single-execution-point property: a Command executed anywhere else in the interpreter would be invisible to both recording and replay.
-- **Positional vs name matching.** The default `strict: true` consumes entries in recorded order and raises a `TimeParadox` when the flow asks for a different Command than the trace holds, which is what detects code that has diverged from the recorded run. Flows containing `Parallel` **require** `strict: false`: branches run through `Promise.all` and complete out of array order, so recorded positions are not stable. `strict: false` resolves per-Command FIFO queues instead, which is order-independent and still keeps duplicate Command names apart. `strict` is a `replayEffect` option, forwarded by `timeTravel`, and is ignored when a `Resolver` is passed rather than a trace, because that `Resolver` has already chosen its own matching.
+- **Path matching, with the two older modes kept for legacy traces.** Every step carries a `path`: its position in the Effect tree, numbered sequentially within a subtree, with each `Parallel` branch and each `Retry` attempt opening its own prefix (`0p1/0r2/0` is branch 1, retry attempt 2, first Command). A path depends only on the shape of the tree, never on the order branches finish in, so it is order-independent **and** paradox-detecting at the same time. `fromTrace` matches by path whenever every entry has one, and it does so whatever `strict` says, deliberately: a caller who passed `strict: false` to work around `Parallel` should get correct matching once their traces carry paths rather than keeping the mode that option existed to work around. Duplicate paths throw, since a collision would reintroduce the failure paths exist to prevent. The older modes remain only for traces recorded before paths existed: `strict: true` consumes entries positionally, `strict: false` resolves per-Command FIFO queues. **The name-queue mode is the bug paths fixed.** It paired a step with the next recorded entry of the same name, which is completion order, so two `Parallel` branches calling the same Command swapped results whenever replay timing differed from production, and the replay still reported `Success`. `strict` is ignored when a `Resolver` is passed, because that `Resolver` has already chosen its own matching.
+
+- **The hook contract carries the path as a fourth parameter.** `onStep(name, type, op, path)`. Three-parameter hooks keep working, and `chainHooks` forwards the path through nested wrappers. A hand-rolled wrapper that calls `inner(name, type, op)` without forwarding `path` silently produces a trace with no paths, which then falls back to legacy positional matching: correct for sequential flows, and the old swapping bug for `Parallel`. Forward the fourth argument in anything that wraps `onStep`.
 - **`fastRetry` exists because of merge order.** 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. `zeroRetryDelays` therefore rewrites `Retry` nodes to `delay: 0, backoff: 1` lazily, through their `next` continuations; without it, replaying a flow that retried in production waits out the production backoff.
 - **The outcome wrapper is load-bearing.** A `Resolver` returns `{ result }`, `{ error }`, or `undefined` for "not recorded". The wrapper keeps a Command that legitimately returned `undefined` (`{ result: undefined }`) distinct from having no recording, which is what makes the `onMissing` guard trustworthy.
 

package/README.md

@@ -1,15 +1,15 @@
 # Pure Effect
 
-[![npm version](https://img.shields.io/npm/v/pure-effect)](https://www.npmjs.com/package/pure-effect) [![bundle size](https://img.shields.io/badge/minified%2Bgzipped-%3C3.4KB-brightgreen)](https://bundlephobia.com/package/pure-effect) [![license](https://img.shields.io/npm/l/pure-effect)](https://github.com/aycangulez/pure-effect/blob/main/LICENSE)
+[![npm version](https://img.shields.io/npm/v/pure-effect)](https://www.npmjs.com/package/pure-effect) [![bundle size](https://img.shields.io/badge/minified%2Bgzipped-4KB-brightgreen)](https://bundlephobia.com/package/pure-effect) [![license](https://img.shields.io/npm/l/pure-effect)](https://github.com/aycangulez/pure-effect/blob/main/LICENSE)
 
 **Pure Effect** is a zero-dependency effect library for JavaScript and TypeScript with time-travel debugging, dependency injection, retry, and OpenTelemetry, where business logic is plain data you can test without mocks.
 
 - Replay a production failure locally, with no database and no network
 - No mocks needed to test async pipelines
 - Inject context without touching function signatures
-- Built-in retry and parallel execution with configurable delay, backoff, and `Promise.all` semantics
+- Built-in retry, plus parallel execution that cancels sibling branches on the first failure
 - OpenTelemetry-ready via lifecycle hooks
-- Zero dependencies, under 3.4 KB minified and gzipped
+- Zero dependencies, under 4 KB minified and gzipped
 - Works in JavaScript and TypeScript (full generics, bundled `.d.ts`)
 
 ## Table of Contents
@@ -47,19 +47,21 @@ const validateRegistration = (input) => {
     return Success(input);
 };
 
-// These functions return a Command object. They do NOT call the database.
-// Name the thunk: traces, replay matching, and telemetry spans are keyed on it.
+// These following two functions return a Command object. They do NOT call the database.
+// Name the commands since traces, replay matching, and telemetry spans are keyed on them.
 const ensureEmailAvailable = (input) => {
     const cmdFindUser = () => db.findUser(input.email);
-    return Command(cmdFindUser, (found) => (found ? Failure('Email already in use.') : Success(input)));
+    const next = (found) => (found ? Failure('Email already in use.') : Success(input));
+    return Command(cmdFindUser, next);
 };
 
-// With no continuation, the result passes straight through.
+// With no continuation (next), the result passes straight through.
 const saveUser = (input) => {
     const cmdSaveUser = () => db.saveUser(input);
     return Command(cmdSaveUser);
 };
 
+// Create flow (not executed yet)
 const registerUserFlow = (input) => effectPipe(validateRegistration, ensureEmailAvailable, saveUser)(input);
 
 // Imperative shell: this is the only place side effects run
@@ -125,7 +127,7 @@ it('prod incident 8f3a: a 100% promo produces a $0 charge', async () => {
 });
 ```
 
-The test verifies that the flow still takes the recorded path and handles the recorded outcomes the same way: a refactor that reorders or drops a step raises a `TimeParadox`, and changed error handling fails the assertion.
+The test verifies that the flow still takes the recorded path and handles the recorded outcomes the same way: a refactor that reorders or drops a step raises a `TimeParadox` naming the path it diverged at, and changed error handling fails the assertion.
 
 **Nondeterminism belongs inside a Command.** A value that varies between runs (the current time, a random ID) is I/O as far as replay is concerned. Wrap it in a Command and it is recorded and replayed like any other response; a step that calls `Date.now()` directly computes a fresh value on every replay and silently diverges from the trace.
 
@@ -223,7 +225,7 @@ Every attempt is a recorded step, so a replay reproduces the exact sequence of f
 
 ## Running Effects in Parallel
 
-`Parallel` runs multiple Effect trees concurrently and passes their results to `next` as an ordered array. If any effect fails, `next` is not called and the `Failure` propagates immediately.
+`Parallel` runs multiple Effect trees concurrently and passes their results to `next` as an ordered array. The first branch to fail cancels its siblings, `next` is not called, and that branch's `Failure` is what propagates.
 
 ```js
 import { Success, Command, Parallel } from 'pure-effect';
@@ -234,7 +236,17 @@ const loadProfile = (userId) =>
 
 `Ask` context flows into all parallel branches without any extra wiring.
 
-Note for replay: branches complete out of array order, so recorded positions are not stable. Replay flows containing `Parallel` with `{ strict: false }`, which matches per-Command queues instead of positions.
+**Cancellation is cooperative, and it works at two levels.** A cancelled branch starts no further Commands. For example, a three-step branch whose first step is in flight when a sibling fails runs that step and stops. Cancelling the step already in flight needs the function to accept the `AbortSignal` it is handed and pass it to whatever performs the I/O:
+
+```js
+// Cancellable: the request is aborted the moment a sibling branch fails.
+const fetchProfile = (userId) => Command((signal) => fetch(`/users/${userId}`, { signal }).then((r) => r.json()));
+
+// Not cancellable: this runs to completion even after a sibling fails.
+const fetchProfileUncancellable = (userId) => Command(() => fetch(`/users/${userId}`).then((r) => r.json()));
+```
+
+Outside a `Parallel` the function is called with no arguments at all, so nothing changes for a Command that never runs in a branch. A `Retry` inside a cancelled branch stops retrying rather than working through the rest of its backoff schedule.
 
 ## TypeScript: Typed Errors and Context
 
@@ -296,7 +308,7 @@ Returns `{ type: 'Failure', error, initialInput }`. Stops the pipeline immediate
 
 Returns `{ type: 'Command', cmd, next, meta }`.
 
-- `cmd`: A function (sync or async) that performs the side effect.
+- `cmd`: A function (sync or async) that performs the side effect. Inside a `Parallel` branch it is called with an `AbortSignal` that fires when a sibling branch fails; elsewhere it is called with no arguments.
 - `next`: Receives the result of `cmd` and returns the next Effect. Optional, defaulting to `(result) => Success(result)`, which is what most Commands want.
 - `meta`: Optional metadata, passed to `onBeforeCommand`. A string `meta.name` becomes the Command's identity. Otherwise, the name of the function is used (`cmd.name`).
 
@@ -324,7 +336,7 @@ Returns `{ type: 'Retry', effect, options, next }`.
 
 #### `Parallel(effects, next)`
 
-Returns `{ type: 'Parallel', effects, next }`. Runs all effects concurrently via `Promise.all`. The first `Failure` is returned immediately and `next` is not called.
+Returns `{ type: 'Parallel', effects, next }`. Runs all effects concurrently. The first branch to fail cancels its siblings and its `Failure` is returned; `next` is not called. When several branches fail in the same tick, the first by array order wins. Each branch's Commands receive an `AbortSignal` as their only argument, so I/O that accepts one is cancelled in flight; see [Running Effects in Parallel](#running-effects-in-parallel).
 
 ### Combinators
 
@@ -404,7 +416,7 @@ restore();
 
 Returns `{ onStep, entries, toTrace }`. Pass `onStep` to `runEffect` or `configureEffect` to record what every Command returned.
 
-Each entry is `{ command, result, durationMs }`, or `{ command, error, durationMs }` when the Command threw, so a trace also answers which step was slow. Results are snapshotted on capture, so a later step that mutates a returned object cannot rewrite what the trace says an earlier step saw. Values that cannot be structurally cloned, such as an object holding a function, are stored by reference instead. Recording cannot change a run: a `redact` that throws records `'[redaction failed]'` for that step instead of failing the flow.
+Each entry is `{ command, path, result, durationMs }`, or `{ command, path, error, durationMs }` when the Command threw, so a trace also answers which step was slow. `path` is the Command's position in the Effect tree, which is what a replay matches on. Results are snapshotted on capture, so a later step that mutates a returned object cannot rewrite what the trace says an earlier step saw. Values that cannot be structurally cloned, such as an object holding a function, are stored by reference instead. Recording cannot change a run: a `redact` that throws records `'[redaction failed]'` for that step instead of failing the flow.
 
 - `options.redact(value, name, kind)`: The single place PII is kept out of a trace. It sees every value a trace holds, with `kind` distinguishing them:
 
@@ -433,7 +445,6 @@ Runs a flow for real while recording, returning `{ result, trace }`. Accepts `re
 Replays an effect tree, feeding recorded results to Commands instead of running them.
 
 - `traceOrResolver`: a trace (or bare entries array) to replay directly, or a resolver function for traces stored in some other shape. A resolver returns `{ result }`, `{ error }`, or `undefined` if the step is unrecorded. A malformed trace rejects with a `ReplayError`.
-- `options.strict` (default `true`): consume trace entries in recorded order and raise `TimeParadox` if the flow asks for a different Command. Set `false` for flows containing `Parallel`, whose branches complete out of array order, to match per-Command queues instead of positions. Ignored when a resolver was passed, since it already matches its own way.
 - `options.context`: context for `Ask`; pass the recorded context.
 - `options.onMissing`: `'throw'` (default) fails on an unrecorded step; `'execute'` runs the real Command, giving a recorded prefix with a live tail.
 - `options.fastRetry` (default `true`): strip `Retry` delays.
@@ -442,14 +453,14 @@ Replays an effect tree, feeding recorded results to Commands instead of running
 
 #### `timeTravel(flowFn, traceLog, options?)`
 
-Replays a trace and narrates each step with its recorded duration, warning when recorded steps were never reached or when the trace's `version` differs from `options.version`. Durations are reported only under `strict` matching, where a replayed step maps back to its recorded entry by position. Takes `options.strict` (default `true`; set `false` for `Parallel`), `options.context` to override the trace's, and `options.log` in place of `console.log`.
+Replays a trace and narrates each step with its recorded duration, warning when recorded steps were never reached or when the trace's `version` differs from `options.version`. Takes `options.context` to override the trace's, and `options.log` in place of `console.log`.
 
 ## Limitations
 
 - **`Retry` repeats the whole wrapped tree.** Commands that already succeeded run again on every attempt, so wrapping a pipeline re-executes its side effects. Wrap the single Command that fails transiently unless every Command in the tree is idempotent.
-- **`Parallel` has no cancellation.** Every branch runs to completion even after another fails, because the results are collected with `Promise.all` and the first `Failure` is selected afterwards. A branch that fails validation does not prevent a sibling branch from writing.
+- **`Parallel` cancellation is cooperative, so it cannot stop everything.** A cancelled branch starts no further Commands, and a function that accepts the `AbortSignal` it is passed can be cut off in flight. A function that ignores the signal cannot: it runs to completion, so a branch whose _first_ Command is a write can still write after a sibling has failed. `Parallel` also waits for every branch to settle before returning, deliberately, so no cancelled work is left running unobserved after the `Failure` is returned.
 - **A `Failure` is complete by design.** It carries the full error and the `initialInput` that `effectPipe` stamped on it, and neither is trimmed, because a test asserting on a Failure and a developer debugging one both need everything. Keeping PII out of a **trace** is `redact`'s job. Keeping it out of your **logs** is the shell's: log `result.error` rather than serializing the whole `Failure`, which for a login or registration flow holds the credentials that flow received.
-- **Replay reproduces observed inputs, not concurrency.** A stale read replays exactly. A race between two concurrent requests does not: a trace records one flow's view, and `Parallel` interleaving is not captured.
+- **Replay reproduces observed inputs, not concurrency.** A stale read replays exactly. A race between two concurrent requests does not: a trace records one flow's view. `Parallel` branches replay with the results their own branch saw, since every step is matched by its position in the tree, but the interleaving between them is not reproduced, so a flow whose branches race each other through shared state is not something a replay can settle.
 - **A trace records responses, not requests.** Command arguments live in a closure and are unreachable, so a trace shows what a call returned but not what was passed to it. This also bounds what a replay verifies: the flow's path and its handling of recorded outcomes. The upside is that arguments can never leak into a trace.
 - **Global configuration is per module instance.** `configureEffect` writes to module-level state, so two copies of the library in one process, from a dual ESM and CJS resolution, two versions in a dependency tree, or a worker thread, each carry their own wiring. Code that configures one gets nothing in the other, with no error.
 - **A Command needs an identity.** `meta.name` is stable under minification; relying on `cmd.name` instead means a mangler renames every step of every trace, so mangling has to be disabled or names preserved.

package/index.d.ts

@@ -19,7 +19,14 @@ export type CommandMeta = { name?: string } & Record<string, unknown>;
 
 export type CommandState<R, T, E = unknown, Ctx = unknown> = {
     type: 'Command';
-    cmd: () => Promise<R> | R;
+    /**
+     * Performs the side effect. Inside a `Parallel` branch it receives an `AbortSignal` that fires when a
+     * sibling branch fails; forward it to `fetch`, a driver, or an `AbortController`-aware client to have
+     * the work cancelled in flight. Ignoring it is fine and is what every thunk written before this did:
+     * the interpreter still refuses to start any *later* Command in a cancelled branch. Outside a
+     * `Parallel` no argument is passed at all.
+     */
+    cmd: (signal?: AbortSignal) => Promise<R> | R;
     next: (result: R) => Effect<T, E, Ctx>;
     meta?: CommandMeta;
     initialInput?: unknown;
@@ -77,7 +84,7 @@ export declare function Failure<E = unknown>(error: E, initialInput?: unknown):
  * and immune to minification. Without one the identity falls back to `cmd.name`, then to 'anonymous'.
  */
 export declare function Command<R, T = R, E = unknown, Ctx = unknown>(
-    cmd: () => Promise<R> | R,
+    cmd: (signal?: AbortSignal) => Promise<R> | R,
     next?: (result: R) => Effect<T, E, Ctx>,
     meta?: CommandMeta
 ): CommandState<R, T, E, Ctx>;
@@ -231,7 +238,12 @@ export declare function effectPipe<
     f8: (i: I) => Effect<J, E8, Ctx>
 ): (start: A) => Effect<J, E1 | E2 | E3 | E4 | E5 | E6 | E7 | E8, Ctx>;
 
-export type StepRunner = (name: string, type: string, op: () => Promise<unknown>) => Promise<unknown>;
+/**
+ * Wraps one Command execution. `path` is the Command's position in the Effect tree rather than its
+ * position in completion order, so it is the same in a replay as in the recorded run even when
+ * `Parallel` branches finish in a different order. Hooks that take three parameters are unaffected.
+ */
+export type StepRunner = (name: string, type: string, op: () => Promise<unknown>, path?: string) => Promise<unknown>;
 
 export type RunWrapper = (
     effect: Effect<unknown>,
@@ -268,12 +280,21 @@ export declare function runEffect<T, E = unknown, Ctx = unknown>(
 ): Promise<SuccessState<T> | FailureState<E>>;
 
 export type ReplayStep = {
-    /** Zero-based position in this run's Command sequence. */
+    /**
+     * Zero-based position in this run's completion order. Not stable for a flow containing `Parallel`,
+     * whose branches finish in whatever order they finish in. Prefer `path`.
+     */
     index: number;
     /** `cmd.name`, or 'anonymous'. */
     name: string;
     /** Always 'Command' today; reserved. */
     type: string;
+    /**
+     * The Command's position in the Effect tree, stable across runs: steps are numbered within a
+     * subtree, and each `Parallel` branch and `Retry` attempt opens its own prefix. This is what a
+     * replay matches on, and what a Resolver should key off. Absent on traces recorded before paths.
+     */
+    path?: string;
 };
 
 /**
@@ -287,6 +308,11 @@ export type Resolver = (step: ReplayStep) => ReplayOutcome | undefined;
 
 export type TraceEntry = {
     command: string;
+    /**
+     * The Command's position in the Effect tree. Order-independent, so a replay lines a recorded step
+     * up with the step that asked for it even when `Parallel` branches finish out of order.
+     */
+    path?: string;
     result?: unknown;
     error?: unknown;
     /** How long the Command took in production, rounded to microseconds. */
@@ -351,11 +377,11 @@ export interface ReplayOptions<Ctx = unknown> {
     onMissing?: 'throw' | 'execute';
     onResolved?: (step: ReplayStep, outcome: ReplayOutcome | undefined) => void;
     /**
-     * Matching mode used when a trace is passed instead of a Resolver. `true` (default)
-     * consumes entries positionally and raises a `TimeParadox` on divergence; `false`
-     * matches per-Command FIFO queues, which is required for flows containing `Parallel`,
-     * whose branches complete out of array order. Ignored when a Resolver is supplied,
-     * since that Resolver has already chosen how it matches.
+     * Legacy matching mode, used only for a trace whose entries carry no `path`. `true` (default)
+     * consumes entries positionally and raises a `TimeParadox` on divergence; `false` matches
+     * per-Command FIFO queues, which used to be required for flows containing `Parallel`. Ignored
+     * for a trace carrying paths, which is matched by path, and when a Resolver is supplied, since
+     * that Resolver has already chosen how it matches.
      */
     strict?: boolean;
 }

package/index.js

@@ -10,7 +10,7 @@
 /**
  * @typedef {{
  *   type: 'Command',
- *   cmd: () => Promise<any>|any,
+ *   cmd: (signal?: AbortSignal) => Promise<any>|any,
  *   next: (result: any) => Effect,
  *   meta?: any,
  *   initialInput?: any
@@ -70,7 +70,10 @@ const Failure = (error, initialInput) => ({
 /**
  * Represents a side effect to be executed later.
  *
- * @param {() => Promise<any>|any} cmd - The side-effect function to execute
+ * @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.
  * @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.
  * @param {CommandMeta} [meta] - Optional metadata, passed to `onBeforeCommand`. A string `meta.name`
@@ -132,7 +135,15 @@ const Retry = (effect, options = {}) => ({
 });
 
 /**
- * Runs multiple Effect trees concurrently. If any effect fails, returns the first Failure by array order and skips next.
+ * 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.
+ *
+ * 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
+ * signal runs to completion, so a branch's first Command can still write after a sibling has failed.
+ *
  * @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
  * @returns {ParallelState}
@@ -244,7 +255,13 @@ const effectPipe = (...fns) => {
     };
 };
 
-/** @typedef {(name: string, type: string, op: function) => Promise<any>} StepRunner */
+/**
+ * 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.
+ * @typedef {(name: string, type: string, op: function, path?: string) => Promise<any>} StepRunner
+ */
 /** @type StepRunner */
 const defaultStepRunner = async (name, type, op) => await op();
 
@@ -336,12 +353,14 @@ const configureEffect = (...configs) => {
  * @typedef {Object} StepStart
  * @property {string} name - `cmd.name`, or 'anonymous'.
  * @property {string} type - Always 'Command' today.
+ * @property {string} [path] - The Command's position in the Effect tree.
  */
 
 /**
  * @typedef {Object} StepEnd
  * @property {string} name
  * @property {string} type
+ * @property {string} [path]
  * @property {any} [result] - What the Command returned, when it succeeded.
  * @property {any} [error] - What it threw, when it did not.
  * @property {number} durationMs
@@ -355,11 +374,11 @@ const now = () => (typeof performance === 'object' ? performance.now() : Date.no
  * @param {(start: StepStart) => (end: StepEnd) => void} handler - Returns a finisher for the outcome
  * @returns {StepRunner}
  */
-const observeSteps = (handler) => async (name, type, op) => {
+const observeSteps = (handler) => async (name, type, op, path) => {
     /** @type {((end: StepEnd) => void) | undefined} */
     let finish;
     try {
-        finish = handler({ name, type });
+        finish = handler({ name, type, path });
     } catch {
         finish = undefined;
     }
@@ -374,10 +393,10 @@ const observeSteps = (handler) => async (name, type, op) => {
     const started = now();
     try {
         const result = await op();
-        report({ name, type, result, durationMs: now() - started });
+        report({ name, type, path, result, durationMs: now() - started });
         return result;
     } catch (error) {
-        report({ name, type, error, durationMs: now() - started });
+        report({ name, type, path, error, durationMs: now() - started });
         throw error;
     }
 };
@@ -411,7 +430,7 @@ const chainHooks = (...configs) => {
 
     if (steps.length) {
         merged.onStep = steps.reduceRight(
-            (inner, outer) => (name, type, op) => outer(name, type, () => inner(name, type, op))
+            (inner, outer) => (name, type, op, path) => outer(name, type, () => inner(name, type, op, path), path)
         );
     }
     if (runs.length) {
@@ -428,6 +447,45 @@ const chainHooks = (...configs) => {
     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.
+ * @returns {Error}
+ */
+const parallelCancelled = () =>
+    Object.assign(new Error('Parallel branch cancelled.'), {
+        name: 'ParallelCancelled'
+    });
+
+/**
+ * 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.
+ *
+ * @param {number} ms
+ * @param {AbortSignal} [signal]
+ * @returns {Promise<void>}
+ */
+const delayFor = (ms, signal) =>
+    new Promise((resolve) => {
+        if (!signal) {
+            setTimeout(resolve, ms);
+            return;
+        }
+        const onAbort = () => {
+            clearTimeout(timer);
+            resolve();
+        };
+        const timer = setTimeout(() => {
+            signal.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        signal.addEventListener('abort', onAbort, { once: true });
+    });
+
 const runEffect =
     /**
      * The Interpreter
@@ -451,13 +509,25 @@ const runEffect =
 
         /**
          * @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>}
          */
-        async function execute(eff) {
+        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);
                 if (eff.type === 'Ask') {
                     eff = eff.next(context);
                     continue;
@@ -467,12 +537,19 @@ const runEffect =
                     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`;
 
                     for (let attempt = 0; attempt <= attempts; attempt++) {
                         if (attempt > 0) {
-                            await new Promise((r) => setTimeout(r, opts.delay * Math.pow(opts.backoff, attempt - 1)));
+                            await delayFor(opts.delay * Math.pow(opts.backoff, attempt - 1), signal);
                         }
-                        const result = await execute(eff.effect);
+                        // 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 = eff.next(result.value);
                             succeeded = true;
@@ -487,17 +564,60 @@ const runEffect =
                     continue;
                 }
                 if (eff.type === 'Parallel') {
-                    const results = await Promise.all(eff.effects.map((e) => execute(e)));
-                    const failure = results.find((r) => r.type === 'Failure');
+                    // 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;
                 }
                 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;
                 try {
                     await localCommandInterceptor(eff, context);
-                    const result = await localStepRunner(cmdName, 'Command', eff.cmd);
+                    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.
@@ -512,7 +632,12 @@ const runEffect =
         return localRunWrapper(effect, () => execute(effect), context?.flowName || '');
     };
 
-/** @typedef {{ index: number, name: string, type: string }} ReplayStep */
+/**
+ * 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.
+ * @typedef {{ index: number, name: string, type: string, path?: string }} ReplayStep
+ */
 
 /**
  * What production observed for a step. `{ result }` is handed to the Command's
@@ -527,7 +652,9 @@ const runEffect =
 /**
  * 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.
- * @typedef {{ command: string, result?: any, error?: any, durationMs?: number }} TraceEntry
+ * `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
  */
 
 /**
@@ -560,12 +687,17 @@ const replayError = (message, props = {}) => Object.assign(new Error(message), {
  * @returns {Error}
  */
 const timeParadox = (step, recorded) =>
-    replayError(`Time paradox at step ${step.index}: flow asked for '${step.name}', trace recorded '${recorded}'`, {
-        name: 'TimeParadox',
-        index: step.index,
-        expected: recorded,
-        actual: step.name
-    });
+    replayError(
+        `Time paradox at ${step.path !== undefined ? `path '${step.path}'` : `step ${step.index}`}: ` +
+            `flow asked for '${step.name}', trace recorded '${recorded}'`,
+        {
+            name: 'TimeParadox',
+            index: step.index,
+            path: step.path,
+            expected: recorded,
+            actual: step.name
+        }
+    );
 
 /**
  * Converts a thrown value into something JSON can carry. `message` and `stack` are
@@ -678,16 +810,17 @@ const recorder = (options = {}) => {
 
     // 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 }) => (end) => {
+    const onStep = observeSteps(({ name, path }) => (end) => {
         const durationMs = Math.round(end.durationMs * 1000) / 1000;
         push(
             'error' in end
                 ? {
                       command: name,
+                      path,
                       error: snapshot(safeRedact(serializeError(end.error, stack), name, 'error')),
                       durationMs
                   }
-                : { command: name, result: snapshot(safeRedact(end.result, name, 'result')), durationMs }
+                : { command: name, path, result: snapshot(safeRedact(end.result, name, 'result')), durationMs }
         );
     });
 
@@ -741,18 +874,21 @@ const entryToOutcome = (entry) => ('error' in entry ? { error: reviveError(entry
  * 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.
  *
- * Strict matching consumes entries in recorded order and verifies that the flow asks
- * for the Command the trace expects, which is what detects divergence between the
- * recorded run and the code being replayed.
+ * 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` without `strict: false`, and it tells two
+ * branches that call the same Command apart by where they are rather than by which finished first.
+ * `strict` does not apply, since path matching is neither positional nor lenient.
  *
- * Name matching is required for flows containing `Parallel`: branches run through
- * `Promise.all` and therefore complete out of array order, so recorded positions are
- * not stable. It resolves per-Command FIFO queues instead, which is order-independent
- * and still keeps duplicate Command names apart.
+ * The two older modes remain for traces recorded before paths existed. Strict matching consumes
+ * entries in recorded order and verifies the flow asks for the Command the trace expects. Name
+ * matching resolves per-Command FIFO queues, which was the only option for `Parallel` and is the
+ * mode that could pair a branch with a sibling's result when both called the same Command.
  *
  * @param {TraceLog | TraceEntry[]} traceLog - A reference-format trace, or a bare array of entries
  * @param {Object} [options]
- * @param {boolean} [options.strict] - Positional matching with paradox detection (default `true`)
+ * @param {boolean} [options.strict] - Positional matching with paradox detection (default `true`).
+ *        Ignored for a trace carrying paths.
  * @returns {Resolver}
  */
 const fromTrace = (traceLog, options = {}) => {
@@ -760,6 +896,30 @@ const fromTrace = (traceLog, options = {}) => {
     const entries = Array.isArray(traceLog) ? traceLog : traceLog?.trace;
     if (!Array.isArray(entries)) throw replayError('Trace has no `trace` array.');
 
+    // Paths win when the trace has them, whatever `strict` says: a caller who passed `strict: false`
+    // to work around Parallel should get the correct matching once their traces carry paths, rather
+    // than keeping the mode that option existed to work around.
+    if (entries.length > 0 && entries.every((e) => typeof e.path === 'string')) {
+        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.
+        if (byPath.size !== entries.length) {
+            throw replayError('Trace has duplicate step paths, so it cannot be matched by path.');
+        }
+        return (step) => {
+            const entry = byPath.get(step.path);
+            if (!entry) {
+                throw replayError(`Trace has no step at path '${step.path}' for '${step.name}'.`, {
+                    command: step.name,
+                    path: step.path
+                });
+            }
+            if (entry.command !== step.name) throw timeParadox(step, entry.command);
+            return entryToOutcome(entry);
+        };
+    }
+
     if (strict) {
         return (step) => {
             const entry = entries[step.index];
@@ -863,8 +1023,8 @@ const replayEffect = async (effect, traceOrResolver, options = {}) => {
     let index = 0;
 
     /** @type {StepRunner} */
-    const onStep = async (name, type, op) => {
-        const step = { index: index++, name, type };
+    const onStep = async (name, type, op, path) => {
+        const step = { index: index++, name, type, path };
         const outcome = resolve(step);
         if (onResolved) onResolved(step, outcome);
         if (outcome === undefined) {
@@ -918,17 +1078,19 @@ const timeTravel = async (flowFn, traceLog, options = {}) => {
     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';
+    const stepsText = trace.length === 0 || trace.length > 1 ? 'steps' : 'step';
     log(`Replaying '${flowName || 'flow'}' (${trace.length} 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.
     let consumed = 0;
-    // Only strict matching maps a replayed step back to its recorded entry by position, so timings
-    // are narrated there and omitted when per-Command queues are matching by name.
+    // 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 legacy trace with
+    // no paths, and only under strict matching, since per-Command queues carry no position.
+    const byPath = new Map(trace.filter((e) => typeof e.path === 'string').map((e) => [e.path, e]));
     const timing = (/** @type {ReplayStep} */ step) => {
-        const recorded = strict ? trace[step.index] : undefined;
+        const recorded = byPath.get(step.path) ?? (strict ? trace[step.index] : undefined);
         return typeof recorded?.durationMs === 'number' ? ` in ${recorded.durationMs}ms` : '';
     };
     const result = await replayEffect(flowFn(initialInput), traceLog, {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "pure-effect",
-    "version": "0.9.0",
+    "version": "0.10.0",
     "description": "A zero-dependency effect library for JavaScript and TypeScript with time-travel debugging, dependency injection, retry, and OpenTelemetry, where business logic is plain data you can test without mocks.",
     "type": "module",
     "exports": "./index.js",

package/test/all.js

@@ -474,7 +474,7 @@ describe('Recording and replay', function () {
         assert.equal(error.lastError.message, 'down');
     });
 
-    it('should require name matching for Parallel, whose branches finish out of order', async function () {
+    it('should replay a Parallel flow whose branches finish out of order', async function () {
         const flow = (/** @type {any} */ id) =>
             Parallel(
                 [
@@ -500,14 +500,115 @@ describe('Recording and replay', function () {
             ['cmdFast', 'cmdSlow'],
             'recording order follows completion, not the effects array'
         );
+        assert.deepEqual(
+            trace.trace.map((e) => e.path),
+            ['0p1/0', '0p0/0'],
+            'each entry is labelled by its branch, so completion order does not matter'
+        );
+
+        // No `strict: false` needed: paths are order-independent, so the default replays correctly.
+        const replayed = await replayEffect(flow('u1'), trace);
+        assert.equal(replayed.type, 'Success');
+        assert.deepEqual(valueOf(replayed), valueOf(result));
+    });
+
+    it('should keep two Parallel branches that call the same Command apart', async function () {
+        // The failure this pins is silent: per-Command queues pair branches by completion order, so
+        // reversing the branch latencies between recording and replay swapped one branch's result
+        // onto the other and the replay still reported Success.
+        const flow = (/** @type {[number, number]} */ delays) =>
+            Parallel(
+                [
+                    Command(
+                        function cmdFetch() {
+                            return new Promise((r) => setTimeout(() => r('A'), delays[0]));
+                        },
+                        (/** @type {any} */ v) => Success(v)
+                    ),
+                    Command(
+                        function cmdFetch() {
+                            return new Promise((r) => setTimeout(() => r('B'), delays[1]));
+                        },
+                        (/** @type {any} */ v) => Success(v)
+                    )
+                ],
+                (/** @type {any} */ vals) => Success(vals)
+            );
 
-        const strictReplay = await replayEffect(flow('u1'), trace);
-        assert.equal(strictReplay.type, 'Failure', 'positional matching reports a false paradox');
-        assert.equal(/** @type {Error} */ (errorOf(strictReplay)).name, 'TimeParadox');
+        const { result, trace } = await recordEffect(flow, [40, 5]);
+        assert.deepEqual(valueOf(result), ['A', 'B']);
 
-        const replayed = await replayEffect(flow('u1'), trace, { strict: false });
+        // Replay with the latencies reversed, so completion order is the opposite of the recorded run.
+        const replayed = await replayEffect(flow([5, 40]), trace);
+        assert.equal(replayed.type, 'Success');
+        assert.deepEqual(valueOf(replayed), ['A', 'B'], 'branch results were not swapped');
+    });
+
+    it('should still resolve a legacy trace that carries no paths', async function () {
+        const a = makeFlow();
+        const { result, trace } = await recordEffect(a.flow, { id: 'legacy' });
+        const legacy = {
+            ...trace,
+            trace: trace.trace.map(({ path, ...rest }) => rest)
+        };
+        assert.ok(
+            legacy.trace.every((e) => e.path === undefined),
+            'the fixture really has no paths'
+        );
+
+        const b = makeFlow();
+        const replayed = await replayEffect(b.flow(trace.initialInput), legacy);
         assert.equal(replayed.type, 'Success');
         assert.deepEqual(valueOf(replayed), valueOf(result));
+        assert.deepEqual(b.calls, { read: 0, write: 0 }, 'a legacy trace still performs no I/O');
+    });
+
+    it('should raise a TimeParadox naming the path when a flow diverges', async function () {
+        const original = (/** @type {any} */ id) =>
+            effectPipe(
+                () =>
+                    Command(
+                        function cmdRead() {
+                            return id;
+                        },
+                        (/** @type {any} */ v) => Success(v)
+                    ),
+                (/** @type {any} */ v) =>
+                    Command(
+                        function cmdWrite() {
+                            return v;
+                        },
+                        (/** @type {any} */ w) => Success(w)
+                    )
+            )(id);
+        const { trace } = await recordEffect(original, 'x1');
+
+        // The second step is a different Command than the trace recorded at that path.
+        const diverged = (/** @type {any} */ id) =>
+            effectPipe(
+                () =>
+                    Command(
+                        function cmdRead() {
+                            return id;
+                        },
+                        (/** @type {any} */ v) => Success(v)
+                    ),
+                (/** @type {any} */ v) =>
+                    Command(
+                        function cmdAudit() {
+                            return v;
+                        },
+                        (/** @type {any} */ w) => Success(w)
+                    )
+            )(id);
+
+        const replayed = await replayEffect(diverged('x1'), trace);
+        assert.equal(replayed.type, 'Failure');
+        const error = /** @type {any} */ (errorOf(replayed));
+        assert.equal(error.name, 'TimeParadox');
+        assert.equal(error.path, '1');
+        assert.equal(error.expected, 'cmdWrite');
+        assert.equal(error.actual, 'cmdAudit');
     });
 
     it('should accept a trace directly, without building a Resolver', async function () {
@@ -1665,8 +1766,11 @@ describe('Documented sharp edges', function () {
         assert.equal(charges.length, 3, 'one order, three charges: wrap the Command, not the pipeline');
     });
 
-    it('should run every Parallel branch to completion even after one fails', async function () {
-        // Pinned deliberately: Promise.all has no cancellation, so a Failure does not stop sibling I/O.
+    it('should not stop an in-flight Command whose thunk ignores the signal', async function () {
+        // Pinned deliberately: cancellation is cooperative. The sibling's write is already in flight
+        // inside the branch's first Command, and a thunk that ignores its signal cannot be interrupted,
+        // so the write still lands. What cancellation does buy is in the suite below: no *later*
+        // Command in that branch starts, and a thunk that honours the signal is cut off.
         /** @type {string[]} */
         const written = [];
         const result = await runEffect(
@@ -1695,7 +1799,7 @@ describe('Documented sharp edges', function () {
         );
         assert.equal(result.type, 'Failure');
         assert.equal(errorOf(result), 'validation_failed');
-        assert.deepEqual(written, ['wrote'], 'the sibling branch still performed its write');
+        assert.deepEqual(written, ['wrote'], 'an uninterruptible in-flight write still performed');
     });
 
     it('should carry the initial input on every Failure', async function () {
@@ -1799,3 +1903,165 @@ describe('Malformed flows', function () {
         assert.equal(/** @type {Error} */ (errorOf(result)).message, 'boom');
     });
 });
+
+describe('Parallel cancellation', function () {
+    beforeEach(function () {
+        configureEffect();
+    });
+
+    /** Resolves after `ms`, or rejects as soon as `signal` aborts. */
+    const cancellableSleep = (/** @type {number} */ ms, /** @type {AbortSignal} */ signal) =>
+        new Promise((resolve, reject) => {
+            const timer = setTimeout(resolve, ms);
+            signal?.addEventListener(
+                'abort',
+                () => {
+                    clearTimeout(timer);
+                    reject(new Error('aborted'));
+                },
+                { once: true }
+            );
+        });
+
+    it('should cancel a branch whose thunk honours the signal', async function () {
+        let completed = false;
+        const started = Date.now();
+        const result = await runEffect(
+            Parallel(
+                [
+                    Command(function cmdFail() {
+                        throw new Error('fail_fast');
+                    }),
+                    Command(async function cmdSlow(/** @type {AbortSignal} */ signal) {
+                        await cancellableSleep(400, signal);
+                        completed = true;
+                        return 'wrote';
+                    })
+                ],
+                (/** @type {any} */ v) => Success(v)
+            )
+        );
+        assert.equal(result.type, 'Failure');
+        assert.equal(/** @type {Error} */ (errorOf(result)).message, 'fail_fast');
+        assert.equal(completed, false, 'the cancelled branch never finished its work');
+        assert.ok(Date.now() - started < 200, 'the run did not wait out the cancelled branch');
+    });
+
+    it('should not start a later Command in a cancelled branch', async function () {
+        /** @type {string[]} */
+        const ran = [];
+        const step = (/** @type {string} */ name) => () =>
+            Command(
+                async function cmdWrite() {
+                    await cancellableSleep(30, undefined);
+                    ran.push(name);
+                    return name;
+                },
+                (/** @type {any} */ v) => Success(v)
+            );
+        const result = await runEffect(
+            Parallel(
+                [
+                    Command(async function cmdFail() {
+                        await cancellableSleep(5, undefined);
+                        throw new Error('validation_failed');
+                    }),
+                    effectPipe(step('write1'), step('write2'), step('write3'))(null)
+                ],
+                (/** @type {any} */ v) => Success(v)
+            )
+        );
+        assert.equal(result.type, 'Failure');
+        assert.deepEqual(ran, ['write1'], 'the in-flight write landed; the two after it never started');
+    });
+
+    it('should stop retrying in a cancelled branch', async function () {
+        let attempts = 0;
+        const result = await runEffect(
+            Parallel(
+                [
+                    Command(async function cmdFail() {
+                        await cancellableSleep(30, undefined);
+                        throw new Error('primary_failed');
+                    }),
+                    Retry(
+                        Command(function cmdFlaky() {
+                            attempts++;
+                            throw new Error('flaky');
+                        }),
+                        { attempts: 5, delay: 100 }
+                    )
+                ],
+                (/** @type {any} */ v) => Success(v)
+            )
+        );
+        assert.equal(/** @type {Error} */ (errorOf(result)).message, 'primary_failed');
+        assert.ok(attempts < 5, `the cancelled branch stopped retrying (made ${attempts} attempts, not 6)`);
+    });
+
+    it('should propagate cancellation into a nested Parallel', async function () {
+        let inner = false;
+        const result = await runEffect(
+            Parallel(
+                [
+                    Command(function cmdOuterFail() {
+                        throw new Error('outer_failed');
+                    }),
+                    Parallel(
+                        [
+                            Command(async function cmdInner(/** @type {AbortSignal} */ signal) {
+                                await cancellableSleep(300, signal);
+                                inner = true;
+                                return 1;
+                            })
+                        ],
+                        (/** @type {any} */ v) => Success(v)
+                    )
+                ],
+                (/** @type {any} */ v) => Success(v)
+            )
+        );
+        assert.equal(/** @type {Error} */ (errorOf(result)).message, 'outer_failed');
+        assert.equal(inner, false, 'the inner branch was cancelled with the outer one');
+    });
+
+    it('should return the triggering Failure rather than the cancellation', async function () {
+        const result = await runEffect(
+            Parallel(
+                [
+                    Command(async function cmdSlowOk(/** @type {AbortSignal} */ signal) {
+                        await cancellableSleep(200, signal);
+                        return 'ok';
+                    }),
+                    Command(function cmdRealFailure() {
+                        throw new Error('THE_REAL_ERROR');
+                    })
+                ],
+                (/** @type {any} */ v) => Success(v)
+            )
+        );
+        assert.equal(
+            /** @type {Error} */ (errorOf(result)).message,
+            'THE_REAL_ERROR',
+            'a cancelled sibling must not displace the failure that caused the cancellation'
+        );
+    });
+
+    it('should still pick the first Failure by array order when branches fail together', async function () {
+        const result = await runEffect(Parallel([Failure('a'), Failure('b')], (/** @type {any} */ v) => Success(v)));
+        assert.equal(errorOf(result), 'a');
+    });
+
+    it('should pass no argument to a Command outside a Parallel', async function () {
+        /** @type {any[]} */
+        const args = [];
+        const result = await runEffect(
+            Command(function cmdRecordArgs() {
+                args.push([...arguments]);
+                return 'done';
+            })
+        );
+        assert.equal(result.type, 'Success');
+        assert.deepEqual(args, [[]], 'a thunk outside a Parallel is called with no arguments at all');
+    });
+});