pure-effect 0.10.0 → 0.11.0

package/CLAUDE.md

@@ -14,10 +14,12 @@ 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 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.
+The README's badge and feature bullet both state a minified-and-gzipped ceiling, currently around 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.
 
+**No `thunk` in the README.** Reader-facing prose says the Command's function, or `cmd`. The word remains fine in this file, in JSDoc, and in code comments, where precision for maintainers matters more than approachability, but a README reader should never need to know it. `grep -n "thunk" README.md` checks a change before it lands.
+
 **No em dashes.** The `—` character does not appear anywhere in this repository: not in `README.md`, not in this file, not in JSDoc, code comments, test names, or assertion messages. Reach for the punctuation that carries the actual relationship instead of a dash that blurs it. A colon when the second half explains or names the first. Parentheses for an aside the sentence could survive without. A semicolon between two linked independent clauses. A comma for a light pause or a trailing "which" clause. A full stop when the clause can stand on its own, which is usually the honest fix for a dash joining two complete thoughts. Nothing enforces this mechanically, so it is on the author; `grep -rn "—" --include="*.js" --include="*.ts" --include="*.md" .` checks a change before it lands. Table cells that need a "not applicable" placeholder use `n/a`.
 
 ## Architecture
@@ -32,15 +34,17 @@ The README's badge and feature bullet both state a minified-and-gzipped ceiling,
 | `Failure(error, initialInput)` | `{ type: 'Failure', error, initialInput }` | Short-circuits the pipeline |
 | `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; the first branch to fail cancels its siblings and its Failure is returned; context flows into all branches |
+| `Retry(effect, options)` | `{ type: 'Retry', effect, options, next }` | Wraps any Effect tree with retry-on-failure semantics; handled natively by the interpreter; a per-use `options.onExhausted` runs a fallback Effect when every attempt has failed |
+| `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` |
 
 The recording and replay exports are a 2x2 rather than four loose helpers: `recorder` and `replayEffect` are the capabilities, at the hook and tree level, while `recordEffect` and `timeTravel` are the flow-level pair that also own trace metadata. That metadata is why the conveniences exist and should not be cut as mere sugar: `initialInput` lets a flow be rebuilt, `context` lets `Ask` resolve on replay, and `version` makes a stale trace detectable. A caller who assembles a trace by hand and forgets `context` gets one that silently diverges. `timeTravel` is presentation over `replayEffect` and could be rebuilt from `onResolved` in about ten lines, but it stays: the one-line form is what makes the feature graspable.
 
-`Command(cmd, next, meta)` keeps that parameter list, and `next` is optional because most of Commands in this repo pass their result straight through: it defaults to `(result) => Success(result)`.
+`Command(cmd, next, meta)` keeps that parameter list, and `next` is optional because most of Commands in this repo pass their result straight through: it defaults to `(result) => Success(result)`. `Parallel`'s `next` follows the same convention, defaulting to `(values) => Success(values)`, so a bare `Parallel(effects)` resolves to the ordered array of success values. The README's `Composing Larger Flows` section documents the composition patterns the primitives already support (sub-pipeline branching, `Parallel` fan-in, local joins that carry a minimal purpose-shaped value); those shapes need no combinators, which is why none were added. The no-accumulator guidance there is deliberate bug avoidance, not taste: a growing scope object hides which step depends on what, lets stale fields outlive their producers, and widens what carries PII, so keep the section's examples threading minimal values if they are ever reworked.
+
+There is deliberately no catch combinator (an `Attempt` node was designed and rejected), and the README's `Which Errors Are Data` section is the guidance that replaced it: an outcome the flow handles is data (a `next` branches on the result, and a rejecting `cmd` function catches into a result shape at the boundary), while `Failure` means abort and is reserved for the shell. Fallbacks written this way are fully traced and replayed; the failed attempt is recorded as that Command's result with the error as data, so nothing is lost, only categorized as handled. Catch was rejected because it reintroduces non-local control flow into a paradigm whose point is explicit data flow, and because every motivating case except one was already expressible. The one exception, recovering from `Retry` exhaustion in-flow, is now covered by the scoped per-use option `Retry(effect, { onExhausted })`. It was added, where general catch was rejected, for three reasons worth keeping: it was the only composition with no in-library expression (the shell workaround split one logical operation across two runs and two traces); retry-then-fallback is a canonical resilience pairing (Polly, resilience4j), so demand was predictable rather than speculative; and it completes `Retry`'s own failure handling rather than adding catch semantics, since `Retry` was already the node that reacts to failures and previously abdicated on the last one. The ceiling stands: no general catch node, nothing but exhaustion is catchable, `onExhausted` is per-use only (the global `retry` defaults cannot carry one, pinned by an `expectError`), and a cancelled branch skips the fallback.
 
 A Command's identity is resolved by the internal `commandName(eff)`: a non-empty string `meta.name`, else `cmd.name`, else `'anonymous'`. That identity is used in three places at once, which is why it has its own function rather than being inlined at the call site: trace entries are keyed on it, strict replay matching compares it against the recorded name, and telemetry spans are titled with it. `meta.name` exists because the previous rule, `cmd.name` alone, made the flagship feature depend on syntax: an inline arrow silently recorded as `'anonymous'`, and any minifier that mangles function names renamed every step of every trace. Both failures are silent, which is the worst property an identity can have. `cmd.name` remains supported and is what the examples use, since naming the thunk reads well and needs no second argument.
 
@@ -75,7 +79,10 @@ runEffect(tree, context, callConfig?)
   → resolves Ask by calling next(context), continues
   → resolves Retry via an inner execute() loop (not recursive runEffect),
     so onRun fires exactly once per runEffect call regardless of attempts;
-    on exhaustion returns Failure({ retryExhausted: true, lastError, attempts })
+    on exhaustion returns Failure({ retryExhausted: true, lastError, attempts }),
+    unless a per-use onExhausted returns a fallback Effect: it executes under the
+    retry's `f` path prefix, its success feeds next, its failure propagates
+    unwrapped, and a cancelled Parallel branch skips it
   → resolves Parallel by running all effects via Promise.all with the same
     context; if any effect returns Failure, returns the first Failure by
     array index and skips next; otherwise calls next with the array of
@@ -135,13 +142,13 @@ 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.
-- **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.
+- **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 retry's `onExhausted` fallback opens `0rf/`). 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.
 
-Two further details: `hooks` defaults to `false`, so a replay cannot reach a telemetry backend or a guardrail that performs I/O; and errors cross the trace via `serializeError` / `reviveError` because `message` and `stack` are non-enumerable on `Error` and a plain `JSON.stringify` would silently drop them. Non-`Error` values pass through unchanged, so a Command that rejected with a string still replays as a string.
+Two further details: `hooks` defaults to `false`, so a replay cannot reach a telemetry backend or a guardrail that performs I/O; and errors cross the trace via `serializeError` / `reviveError` because `message`, `stack`, and `cause` are non-enumerable on `Error` and a plain `JSON.stringify` would silently drop them; `cause` is carried recursively since it is often an `Error` itself. Non-`Error` values pass through unchanged, so a Command that rejected with a string still replays as a string.
 
 Recorded results are snapshotted by the internal `snapshot`, not stored by reference. Without it a later step that mutates a returned object rewrote what the trace said an earlier step returned, and because `toTrace` runs after the flow finishes, the mutation was already baked in by the time a sink serialized it: the trace recorded a value production never saw, and a replay fed that value back. It uses `structuredClone` where available, falls back to a JSON round trip, and falls back again to the reference for values that can be neither, since dropping the entry would be worse. Redaction runs first, so nothing sensitive is cloned before being stripped.
 
@@ -153,7 +160,7 @@ Recorded results are snapshotted by the internal `snapshot`, not stored by refer
 
 Full generic type declarations are in `index.d.ts` and referenced via the `types` field in `package.json`. Type-level tests live in `test/types.test-d.ts` and run via `tsd` as part of `npm test`.
 
-`index.d.ts` is hand-maintained beside `index.js`, so the two drift silently. Nothing but `tsd` reads it: `tsc --allowJs --checkJs` over `index.js` checks the JSDoc and never opens the declarations, and mocha does not typecheck at all. **Check `npm test` by exit code.** `tsd` failures print neither "passing" nor "failing", so piping the output through `grep -E "passing|failing"` hides them entirely, which is how `runEffect`'s declaration stayed deleted through several edits here while every other check reported green. It was removed as collateral by a slice that targeted an adjacent block, so after any structural edit to `index.d.ts`, compare the runtime exports against the declared ones rather than trusting the diff.
+`index.d.ts` is hand-maintained beside `index.js`, so the two can drift. Two mechanisms guard the drift: the `Declaration parity` test pins the export lists to each other in both directions, and `npm test` now runs `tsc -p tsconfig.check.json` (checkJs over `index.js`), which keeps the JSDoc sound; it still never opens the declarations, so signature-level drift remains `tsd`'s job. The tsc leg was added after a narrowing error in the interpreter shipped through a green gate and was found in an editor, the second time a lens existed but was not in the gate. **Check `npm test` by exit code.** `tsd` failures print neither "passing" nor "failing", so piping the output through `grep -E "passing|failing"` hides them entirely, which is how `runEffect`'s declaration stayed deleted through several edits here while every other check reported green. It was removed as collateral by a slice that targeted an adjacent block, so after any structural edit to `index.d.ts`, compare the runtime exports against the declared ones rather than trusting the diff.
 
 Raw `tsc` over `test/types.test-d.ts` is the wrong lens and will always report errors: `expectError(...)` blocks contain deliberate type errors that `tsd` requires to be errors.
 
@@ -161,6 +168,8 @@ Raw `tsc` over `test/types.test-d.ts` is the wrong lens and will always report e
 
 Error unions need explicit return annotations. A step written as `(i: User): Effect<User, 'taken'> => ...` contributes `'taken'` to the pipeline's union, but the same step left to inference from a bare `Success(x) | Failure(y)` return type yields `E = unknown`, and one `unknown` absorbs every other member of the union, so `result.error` degrades to `unknown` for the whole pipeline. Annotate `Effect<T, E>` on any step whose error type is meant to survive, and write type-level examples that way.
 
+`Retry`'s declared error is `RetryExhaustedError<E>`, not `E`, and that is deliberate: the interpreter never lets an inner attempt's error escape unwrapped, so on exhaustion the Failure carries `{ retryExhausted, lastError, attempts }` and the inner `E` survives only as `lastError`. `RetryState`'s `effect` field is typed `Effect<T, any, Ctx>` for the same reason, since the wrapped tree's error type is consumed by the retry loop rather than exposed. The declaration previously claimed `E`, which made `result.error` lie for every flow containing a `Retry`; the tsd assertions in the Retry section pin the corrected shape. With a per-use `onExhausted` the declared error is the fallback's own error type instead, since exhaustion then never escapes; that overload comes first, and `onExhausted` is typed on the per-use options only, so a global `configureEffect` retry default cannot carry one.
+
 The recording and replay exports are declared alongside the primitives (`ReplayStep`, `ReplayOutcome`, `Resolver`, `TraceEntry`, `TraceLog`, `RecorderOptions`, `TraceMeta`, `ReplayOptions<Ctx>`). Known gap: `test/types.test-d.ts` has no coverage for any of the replay exports; their declarations are checked only by `tsc` over the JSDoc in `index.js`. Add `tsd` assertions there when touching those types.
 
 ### Observability

package/README.md

@@ -2,14 +2,14 @@
 
 [![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.
+**Pure Effect** records what your business logic did in production and replays it anywhere: time-travel debugging for JavaScript and TypeScript, with zero dependencies. Business logic is plain data you can test without mocks.
 
 - 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, plus parallel execution that cancels sibling branches on the first failure
 - OpenTelemetry-ready via lifecycle hooks
-- Zero dependencies, under 4 KB minified and gzipped
+- Zero dependencies, 4 KB minified and gzipped
 - Works in JavaScript and TypeScript (full generics, bundled `.d.ts`)
 
 ## Table of Contents
@@ -17,11 +17,14 @@
 - [Installation](#installation)
 - [Quick Start](#quick-start)
 - [Testing Without Mocks](#testing-without-mocks)
+- [How It Works](#how-it-works)
 - [Time-Travel Debugging](#time-travel-debugging)
 - [Recording in Production](#recording-in-production)
 - [Passing Runtime Context](#passing-runtime-context)
 - [Retrying Transient Failures](#retrying-transient-failures)
 - [Running Effects in Parallel](#running-effects-in-parallel)
+- [Composing Larger Flows](#composing-larger-flows)
+- [Which Errors Are Data](#which-errors-are-data)
 - [TypeScript: Typed Errors and Context](#typescript-typed-errors-and-context)
 - [Why Pure Effect](#why-pure-effect)
 - [API Reference](#api-reference)
@@ -35,7 +38,7 @@ npm install pure-effect
 
 ## Quick Start
 
-A complete user registration flow. Every step receives the value the previous step produced, so the pipeline reads top-to-bottom as the flow of data:
+A complete user registration flow. Every step receives the value the previous step produced, so the pipeline reads top-to-bottom as the flow of data. Each I/O step is a pair: the call to make, plus a `next` function that receives its answer and decides what follows.
 
 ```js
 import { Success, Failure, Command, effectPipe, runEffect } from 'pure-effect';
@@ -55,13 +58,13 @@ const ensureEmailAvailable = (input) => {
     return Command(cmdFindUser, next);
 };
 
-// With no continuation (next), the result passes straight through.
+// With no next function, the result passes straight through.
 const saveUser = (input) => {
     const cmdSaveUser = () => db.saveUser(input);
     return Command(cmdSaveUser);
 };
 
-// Create flow (not executed yet)
+// Build the flow. Validation runs now; no I/O happens until runEffect.
 const registerUserFlow = (input) => effectPipe(validateRegistration, ensureEmailAvailable, saveUser)(input);
 
 // Imperative shell: this is the only place side effects run
@@ -94,6 +97,14 @@ assert.equal(step2.cmd.name, 'cmdSaveUser');
 // The full flow is verified. The database was never touched.
 ```
 
+## How It Works
+
+A flow is a chain of pairs: an I/O call to make, plus a `next` function that receives its answer and returns whatever comes after, another Command, a Success, or a Failure. `runEffect` walks that chain in a loop. 
+
+Recording and replay attach at the single point where a Command's function is called: recording wraps that call to write down each answer, and replay substitutes the recorded answer without making the call, which is why a replayed flow performs no I/O.
+
+Building a flow runs the pure steps immediately: `registerUserFlow(badInput)` returns the validation `Failure` synchronously, which is why the tests above do not need `runEffect`. Only the I/O inside Commands requires it.
+
 ## Time-Travel Debugging
 
 Record what each Command returned, then feed those results back into the same flow to retrace the exact path a request took, with no database and no network attached.
@@ -131,6 +142,14 @@ The test verifies that the flow still takes the recorded path and handles the re
 
 **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.
 
+**A determinism check is one round trip.** Record a flow, replay it immediately, and compare the outcomes. A step that computes a fresh nondeterministic value surfaces as a `TimeParadox` when it changes which Commands run, or as a mismatch in the final value:
+
+```js
+const { result, trace } = await recordEffect(registerUserFlow, input);
+const replayed = await replayEffect(registerUserFlow(input), trace);
+assert.deepEqual(replayed, result); // fails if any step computed a fresh value
+```
+
 **The trace format is yours.** `replayEffect` also takes a resolver function in place of a trace, so OpenTelemetry spans, a log pipeline, or a database table work as well as the JSON that `recorder` produces.
 
 ```js
@@ -221,7 +240,21 @@ When all attempts are exhausted, `runEffect` returns a structured `Failure`:
 { retryExhausted: true, lastError: <the last error>, attempts: 3 }
 ```
 
-Every attempt is a recorded step, so a replay reproduces the exact sequence of failures. It also skips the delays, because waiting out production backoff during debugging is never what you want.
+In TypeScript, a `Retry` contributes `RetryExhaustedError<E>` to the pipeline's error union rather than the inner `E` itself, matching what the Failure actually carries: the wrapped tree's error type survives as `result.error.lastError`.
+
+**Recover from exhaustion in-flow with `onExhausted`.** When every attempt has failed, the fallback Effect runs instead of returning the structured Failure. Its success feeds the rest of the pipeline exactly as the primary's would have, and its failure propagates unwrapped:
+
+```js
+const fetchPrice = (sku) =>
+    Retry(fetchLivePrice(sku), {
+        attempts: 3,
+        onExhausted: (err) => fetchCachedPrice(sku) // err = { retryExhausted, lastError, attempts }
+    });
+```
+
+Fallback steps are recorded under their own trace paths, so a replay reproduces the fallback exactly, and a fallback never starts in a `Parallel` branch that a sibling's failure has already cancelled. With `onExhausted` set, the exhaustion error never escapes, so in TypeScript the node contributes the fallback's error type to the pipeline's union instead of `RetryExhaustedError<E>`.
+
+Every attempt is a recorded step, so a replay reproduces the exact sequence of failures. It also skips the delays.
 
 ## Running Effects in Parallel
 
@@ -234,6 +267,8 @@ const loadProfile = (userId) =>
     Parallel([getUser(userId), getPermissions(userId)], ([user, permissions]) => Success({ user, permissions }));
 ```
 
+`next` is optional, defaulting to `(values) => Success(values)` just like `Command`'s, so a bare `Parallel(effects)` resolves to the ordered array of success values.
+
 `Ask` context flows into all parallel branches without any extra wiring.
 
 **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:
@@ -248,6 +283,68 @@ const fetchProfileUncancellable = (userId) => Command(() => fetch(`/users/${user
 
 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.
 
+## Composing Larger Flows
+
+`effectPipe` is a straight line, but flows rarely are. Branching and fan-in work with the existing primitives. Here is how:
+
+**A step can return a sub-pipeline.** `effectPipe(...)(value)` returns an Effect like any other, so a step can branch into a whole sub-flow, and the sub-flow's `Failure` short-circuits the outer pipeline exactly like a local one:
+
+```js
+const processOrder = (order) => (order.isGift ? giftFlow(order) : standardFlow(order));
+
+const fulfillment = effectPipe(validateOrder, processOrder, scheduleShipping);
+```
+
+**Independent fan-in: `Parallel`.** When a later step needs several values that do not depend on each other, run them concurrently and join structurally. With `next` omitted, the branch results arrive as an ordered array:
+
+```js
+const loadCheckout = effectPipe(
+    (input) => Parallel([fetchCart(input.cartId), fetchUser(input.userId)]),
+    ([cart, user]) => Success({ cart, user, total: cartTotal(cart) })
+);
+```
+
+**Dependent fan-in: join locally.** When step B needs step A's result and step C needs both, carry both forward in a value shaped for the next step. A local sub-pipeline that closes over its own parameter makes the join without nested callbacks:
+
+```js
+const applyLoyaltyDiscount = (orderId) =>
+    effectPipe(
+        fetchOrder,
+        (order) => effectPipe(fetchCustomer, (customer) => Success({ order, customer }))(order.customerId),
+        ({ order, customer }) => Success(discountedTotal(order, customer))
+    )(orderId);
+```
+
+**Carry exactly what downstream needs, never an accumulator.** Passing a minimal, purpose-shaped value between steps, rather than a scope object that grows with everything ever computed, is a strategy for avoiding bugs, not a style preference. Each step's input is its complete contract, so a step cannot quietly depend on a value produced far upstream, a stale field cannot outlive the step that should have replaced it, and two steps cannot collide on a key neither knows the other uses. It also keeps data alive no longer than the flow needs it, which matters when the values are credentials or PII. In TypeScript the same discipline is what keeps the pipeline checked end to end: every step consumes the value it receives, so changing what an upstream step produces is a compile error at exactly the step that reads it, instead of an `undefined` at runtime.
+
+## Which Errors Are Data
+
+There is no catch combinator, and that is deliberate. A flow's outcomes divide into two kinds, and the division decides how each is written.
+
+**An outcome the flow handles is data.** A Command's `next` receives the result and can branch into any Effect, including a whole fallback sub-pipeline. When the I/O itself can reject, catch inside the Command's `cmd` function and return the miss as a value:
+
+```js
+const fetchCachedPrice = (sku) => {
+    const cmdFetchCachedPrice = () => cache.get(sku);
+    return Command(cmdFetchCachedPrice, (price) => Success({ ...price, stale: true }));
+};
+
+const fetchPrice = (sku) => {
+    const cmdFetchLivePrice = () =>
+        pricing
+            .get(sku)
+            .then((price) => ({ ok: true, price }))
+            .catch((error) => ({ ok: false, error }));
+    return Command(cmdFetchLivePrice, (r) => (r.ok ? Success({ ...r.price, stale: false }) : fetchCachedPrice(sku)));
+};
+```
+
+The failed live attempt is recorded as that Command's result, error included, so a replay takes the same fallback branch and an incident trace still becomes a regression test. Nothing is hidden; the miss is simply categorized as what it is, an outcome the flow was written to handle.
+
+**A `Failure` means abort.** It short-circuits everything and lands in the shell, which is the one place that decides what a dead flow means: an HTTP status, a queue retry, an alert. Reserving `Failure` for outcomes the flow cannot handle keeps its meaning brutally simple; a reader never has to scan up the tree for a handler, because there is none. A catch combinator would reintroduce exactly the non-local control flow that writing effects as data is meant to eliminate.
+
+The rule of thumb: if you would handle it, return it; if you would only report it, fail with it. The one handled outcome that cannot be modeled as data is retry exhaustion, since the failing happens inside the `Retry` node; that case has its own in-flow form, the `onExhausted` option in [Retrying Transient Failures](#retrying-transient-failures).
+
 ## TypeScript: Typed Errors and Context
 
 ### Error union across pipeline steps
@@ -284,9 +381,9 @@ const result = await runEffect(findProduct('abc'), { tenant: 'acme', requestId:
 
 ## Why Pure Effect
 
-**vs. Effect-TS:** Effect-TS is a full functional programming ecosystem with fibers, streaming, schema validation, structured concurrency, and more, though it comes with a steep learning curve. Pure Effect covers a narrower scope: testable pipelines, context injection, retry, parallel execution, and replayable traces. If you need fibers, in-flight cancellation, or streaming, Effect-TS is the right tool.
+**vs. Temporal and durable execution (Restate, Inngest):** The closest relatives, because they are built on the same idea: record what every step returned, replay it deterministically. Those engines run it as a managed execution guarantee: histories persist server-side, and workflows resume automatically after a crash. The difference is who operates it. An engine stores histories and restarts dead runs for you; with Pure Effect that is your application's job, and there is no infrastructure to run.
 
-**vs. fp-ts:** fp-ts brings category theory abstractions (functors, monads, applicatives) to TypeScript. Pure Effect borrows only the concept of effects as data, without that vocabulary.
+**vs. Effect-TS (and fp-ts):** A full functional programming ecosystem with fibers, streaming, schema validation, structured concurrency, and more, though it comes with a steep learning curve and a vocabulary of its own. Pure Effect borrows only the concept of effects as data, and covers a narrower scope: testable pipelines, context injection, retry, parallel execution, and replayable traces. If you need fibers, in-flight cancellation, or streaming, Effect-TS is the right tool.
 
 **vs. plain async/await with mocks:** A mock that passes all your tests but diverges from what the real driver does is worse than no test. Business logic never executes I/O, so there is nothing to mock.
 
@@ -333,12 +430,13 @@ Returns `{ type: 'Retry', effect, options, next }`.
 - `options.attempts`: Max retries, not counting the first try (default: `3`).
 - `options.delay`: Ms before the first retry (default: `100`).
 - `options.backoff`: Multiplier applied to delay on each attempt (default: `1`, flat).
+- `options.onExhausted(error)`: Runs a fallback Effect when every attempt has failed, receiving `{ retryExhausted, lastError, attempts }`. The fallback's success feeds `next`; its failure propagates unwrapped. Per-use only. See [Retrying Transient Failures](#retrying-transient-failures).
 
-#### `Parallel(effects, next)`
+#### `Parallel(effects, next?)`
 
-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).
+Returns `{ type: 'Parallel', effects, next }`. Runs all effects concurrently. `next` receives the ordered array of success values and is optional, defaulting to `(values) => Success(values)` like `Command`'s. 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
+### Building pipelines
 
 #### `effectPipe(...functions)`
 
@@ -370,7 +468,7 @@ Commands are data, so a Command that is constructed and discarded never runs, an
 
 Traverses the effect tree, executes Commands with `async/await`, resolves `Ask` with the supplied `context`, and returns the final `Success` or `Failure`.
 
-- `context`: Passed to `Ask` continuations and `onBeforeCommand`. `context.flowName` names the workflow in telemetry.
+- `context`: Passed to `Ask`'s next function and to `onBeforeCommand`. `context.flowName` names the workflow in telemetry.
 - `callConfig`: Per-call overrides for `onStep`, `onRun`, `onBeforeCommand`, and `retry`. Takes precedence over `configureEffect` globals.
 - `onRun` fires exactly once per `runEffect` call. Retry attempts run inside that single span.
 
@@ -381,7 +479,7 @@ Step 'validateRegistration' returned a plain object. Return Success, Failure, Co
 Retry, or Parallel: a plain value has to be wrapped, as in Success(value).
 ```
 
-The same check catches a missing `return`, a Command continuation that returns a plain value, and `runEffect(flow)` where `runEffect(flow(input))` was meant. A Command that throws is still a `Failure`.
+The same check catches a missing `return`, a Command's next function returning a plain value, and `runEffect(flow)` where `runEffect(flow(input))` was meant. A Command that throws is still a `Failure`.
 
 #### `configureEffect(...configs)`
 

package/index.d.ts

@@ -44,10 +44,15 @@ export type RetryOptions = {
     backoff?: number;
 };
 
+/**
+ * `E` is the error the node contributes to its pipeline, which for a Retry is the exhaustion failure:
+ * the interpreter never lets an inner attempt's error escape unwrapped, so the wrapped tree's own
+ * error type is consumed by the retry loop rather than exposed here.
+ */
 export type RetryState<T, E = unknown, Ctx = unknown> = {
     type: 'Retry';
-    effect: Effect<T, E, Ctx>;
-    options: RetryOptions;
+    effect: Effect<T, any, Ctx>;
+    options: RetryOptions & { onExhausted?: (error: RetryExhaustedError<any>) => Effect<T, any, Ctx> };
     next: (value: T) => Effect<T, E, Ctx>;
     initialInput?: unknown;
 };
@@ -93,10 +98,35 @@ export declare function Ask<T, E = unknown, Ctx = unknown>(
     next: (context: Ctx) => Effect<T, E, Ctx>
 ): AskState<T, E, Ctx>;
 
+/**
+ * With `onExhausted`, the exhaustion failure never escapes: the fallback Effect runs instead, its
+ * success feeds `next`, and its failure propagates unwrapped, so the node's declared error is the
+ * fallback's own error type. `onExhausted` is a per-use option only; the global `retry` defaults in
+ * `EffectConfiguration` deliberately cannot carry one.
+ */
+export declare function Retry<T, E = unknown, E2 = unknown, Ctx = unknown>(
+    effect: Effect<T, E, Ctx>,
+    options: RetryOptions & { onExhausted: (error: RetryExhaustedError<E>) => Effect<T, E2, Ctx> }
+): RetryState<T, E2, Ctx>;
+
+/**
+ * Without `onExhausted`, the declared error type is `RetryExhaustedError<E>`, because that is what
+ * a Retry's Failure actually carries: on exhaustion the interpreter returns
+ * `Failure({ retryExhausted: true, lastError, attempts })` rather than the inner error itself,
+ * so `result.error.lastError` is where the wrapped tree's `E` survives.
+ */
 export declare function Retry<T, E = unknown, Ctx = unknown>(
     effect: Effect<T, E, Ctx>,
     options?: RetryOptions
-): RetryState<T, E, Ctx>;
+): RetryState<T, RetryExhaustedError<E>, Ctx>;
+
+/**
+ * `next` is optional and defaults to `(values) => Success(values)`, same as `Command`'s default,
+ * so a bare `Parallel(effects)` resolves to the ordered array of success values.
+ */
+export declare function Parallel<T extends readonly unknown[], E = unknown, Ctx = unknown>(effects: {
+    [K in keyof T]: Effect<T[K], E, Ctx>;
+}): ParallelState<[...T], [...T], E, Ctx>;
 
 export declare function Parallel<T extends readonly unknown[], R, E = unknown, Ctx = unknown>(
     effects: { [K in keyof T]: Effect<T[K], E, Ctx> },

package/index.js

@@ -28,7 +28,7 @@
  * @typedef {{
  *   type: 'Retry',
  *   effect: Effect,
- *   options: { attempts?: number, delay?: number, backoff?: number },
+ *   options: { attempts?: number, delay?: number, backoff?: number, onExhausted?: (error: any) => Effect },
  *   next: (value: any) => Effect,
  *   initialInput?: any
  * }} RetryState
@@ -125,6 +125,10 @@ const Ask = (next) => ({ type: 'Ask', next });
  * @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 {(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.
  * @returns {RetryState}
  */
 const Retry = (effect, options = {}) => ({
@@ -145,10 +149,15 @@ const Retry = (effect, options = {}) => ({
  * 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
+ * @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.
  * @returns {ParallelState}
  */
-const Parallel = (effects, next) => ({ type: 'Parallel', effects, next });
+const Parallel = (effects, next = (/** @type {any[]} */ values) => Success(values)) => ({
+    type: 'Parallel',
+    effects,
+    next
+});
 
 /**
  * Describes a value for an error message, leading with the mistake it most likely is.
@@ -540,6 +549,9 @@ const runEffect =
                     // 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) {
@@ -551,7 +563,7 @@ const runEffect =
                         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);
+                            eff = retryNext(result.value);
                             succeeded = true;
                             break;
                         }
@@ -559,7 +571,23 @@ const runEffect =
                     }
 
                     if (!succeeded) {
-                        return Failure({ retryExhausted: true, lastError, attempts }, eff.initialInput);
+                        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;
                 }
@@ -712,6 +740,8 @@ const serializeError = (e, withStack) => {
     /** @type {any} */
     const out = { __error: true, name: e.name, message: e.message };
     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];
     return out;
 };
@@ -727,7 +757,9 @@ const reviveError = (v) => {
     const e = new Error(v.message);
     e.name = v.name;
     for (const [k, val] of Object.entries(v)) {
-        if (k !== '__error' && k !== 'name' && k !== 'message') /** @type {any} */ (e)[k] = val;
+        if (k !== '__error' && k !== 'name' && k !== 'message') {
+            /** @type {any} */ (e)[k] = k === 'cause' ? reviveError(val) : val;
+        }
     }
     return e;
 };
@@ -956,13 +988,21 @@ const fromTrace = (traceLog, options = {}) => {
 const zeroRetryDelays = (eff) => {
     if (!eff || typeof eff.type !== 'string') return eff;
     switch (eff.type) {
-        case 'Retry':
+        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: { ...eff.options, delay: 0, backoff: 1 },
+                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':

package/package.json

@@ -1,19 +1,19 @@
 {
     "name": "pure-effect",
-    "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.",
+    "version": "0.11.0",
+    "description": "Records what your business logic did in production and replays it anywhere: time-travel debugging for JavaScript and TypeScript, with zero dependencies. Business logic is plain data you can test without mocks.",
     "type": "module",
     "exports": "./index.js",
     "types": "./index.d.ts",
     "scripts": {
-        "test": "mocha && tsd",
+        "test": "mocha && tsd && tsc -p tsconfig.check.json",
         "format": "prettier --write index.js index.d.ts examples/*.js test/all.js README.md CLAUDE.md"
     },
     "tsd": {
         "directory": "test"
     },
     "author": "Aycan Gulez",
-    "homepage": "https://github.com/aycangulez/pure-effect",
+    "homepage": "https://pure-effect.org",
     "license": "MIT",
     "devDependencies": {
         "@opentelemetry/api": "^1.9.1",

package/test/all.js

@@ -16,6 +16,8 @@ import {
     replayEffect,
     timeTravel
 } from '../index.js';
+import * as lib from '../index.js';
+import ts from 'typescript';
 import { enableTelemetry, telemetryHooks } from '../examples/opentelemetry-example.js';
 import { enableRecording, recordingHooks } from '../examples/recording-example.js';
 
@@ -247,6 +249,14 @@ describe('Core', function () {
         assert.equal(result.next, next);
     });
 
+    it('should default next to Success of the values array when omitted', async () => {
+        const e1 = Command(async () => 'a');
+        const e2 = Command(async () => 'b');
+        const result = await runEffect(Parallel([e1, e2]));
+        assert.equal(result.type, 'Success');
+        assert.deepEqual(result.value, ['a', 'b']);
+    });
+
     it('should run effects concurrently and pass results to next', async () => {
         const e1 = Command(
             async () => 'a',
@@ -309,6 +319,138 @@ describe('Core', function () {
     });
 });
 
+describe('Retry onExhausted', function () {
+    beforeEach(() => configureEffect());
+
+    it('should run the fallback on exhaustion and feed its value downstream', async function () {
+        let liveCalls = 0;
+        /** @type {any} */
+        let sawError;
+        const flow = effectPipe(
+            (/** @type {any} */ sku) =>
+                Retry(
+                    Command(function cmdFetchLive() {
+                        liveCalls++;
+                        return Promise.reject(new Error('down'));
+                    }),
+                    {
+                        attempts: 2,
+                        delay: 0,
+                        onExhausted: (/** @type {any} */ err) => {
+                            sawError = err;
+                            return Command(function cmdFetchCached() {
+                                return Promise.resolve({ sku, amount: 95 });
+                            });
+                        }
+                    }
+                ),
+            (/** @type {any} */ price) => Success({ ...price, stale: true })
+        );
+        const result = /** @type {any} */ (await runEffect(flow('sku-1')));
+        assert.equal(result.type, 'Success');
+        assert.deepEqual(result.value, { sku: 'sku-1', amount: 95, stale: true });
+        assert.equal(liveCalls, 3, 'the primary still runs the full retry schedule first');
+        assert.equal(sawError.retryExhausted, true);
+        assert.equal(sawError.attempts, 2);
+        assert.equal(sawError.lastError.message, 'down');
+    });
+
+    it('should propagate a failing fallback unwrapped', async function () {
+        const flow = Retry(
+            Command(function cmdPrimary() {
+                return Promise.reject('primary down');
+            }),
+            { attempts: 0, delay: 0, onExhausted: () => Failure('cache empty') }
+        );
+        const result = /** @type {any} */ (await runEffect(flow));
+        assert.equal(result.type, 'Failure');
+        assert.equal(result.error, 'cache empty', 'the fallback failure must not be wrapped in retryExhausted');
+    });
+
+    it('should not run the fallback in a cancelled Parallel branch', async function () {
+        let fallbackRuns = 0;
+        const slowFailing = Retry(
+            Command(async function cmdSlowFail() {
+                await new Promise((resolve) => setTimeout(resolve, 30));
+                throw new Error('slow branch failed');
+            }),
+            {
+                attempts: 0,
+                delay: 0,
+                onExhausted: () => {
+                    fallbackRuns++;
+                    return Success('recovered');
+                }
+            }
+        );
+        const fastFailing = Command(async function cmdFastFail() {
+            await new Promise((resolve) => setTimeout(resolve, 5));
+            throw new Error('fast branch failed');
+        });
+        const result = /** @type {any} */ (await runEffect(Parallel([fastFailing, slowFailing])));
+        assert.equal(result.type, 'Failure');
+        assert.equal(result.error.message, 'fast branch failed');
+        assert.equal(fallbackRuns, 0, 'a cancelled branch must not start its fallback');
+    });
+
+    it('should record the fallback under its own path and replay it with zero I/O', async function () {
+        const calls = { live: 0, cached: 0 };
+        const flow = (/** @type {any} */ sku) =>
+            Retry(
+                Command(function cmdFetchLive() {
+                    calls.live++;
+                    return Promise.reject(new Error('down'));
+                }),
+                {
+                    attempts: 1,
+                    delay: 0,
+                    onExhausted: () =>
+                        Command(function cmdFetchCached() {
+                            calls.cached++;
+                            return Promise.resolve(95);
+                        })
+                }
+            );
+        const { result, trace } = await recordEffect(flow, 'sku-1');
+        assert.equal(result.type, 'Success');
+        assert.ok(
+            trace.trace.some((/** @type {any} */ e) => e.command === 'cmdFetchCached' && /f\//.test(e.path)),
+            'the fallback step must be recorded under a fallback path prefix'
+        );
+        const before = { ...calls };
+        const replayed = /** @type {any} */ (await replayEffect(flow('sku-1'), trace));
+        assert.equal(replayed.type, 'Success');
+        assert.deepEqual(replayed.value, /** @type {any} */ (result).value);
+        assert.deepEqual(calls, before, 'replay must perform no I/O');
+    });
+
+    it('should strip Retry delays inside the fallback during replay', async function () {
+        const flow = (/** @type {any} */ n) =>
+            Retry(
+                Command(function cmdPrimary() {
+                    return Promise.reject('nope');
+                }),
+                {
+                    attempts: 0,
+                    delay: 0,
+                    onExhausted: () =>
+                        Retry(
+                            Command(function cmdSecondary() {
+                                return Promise.reject('still nope');
+                            }),
+                            { attempts: 2, delay: 200 }
+                        )
+                }
+            );
+        const { trace } = await recordEffect(flow, 1);
+        const started = Date.now();
+        const replayed = /** @type {any} */ (await replayEffect(flow(1), trace));
+        const elapsed = Date.now() - started;
+        assert.equal(replayed.type, 'Failure');
+        assert.ok(elapsed < 150, `replay must not wait out the fallback backoff, took ${elapsed}ms`);
+    });
+});
+
 /** Reads `.value` off a runEffect result once its type has been asserted. */
 const valueOf = (/** @type {any} */ result) => result.value;
 
@@ -628,6 +770,41 @@ describe('Recording and replay', function () {
         assert.deepEqual(valueOf(fromEntries), valueOf(result));
     });
 
+    it('should carry an error cause through a trace and back', async function () {
+        const flow = (/** @type {any} */ input) =>
+            Command(function cmdCharge() {
+                return Promise.reject(new Error('charge declined', { cause: new Error('card expired') }));
+            });
+
+        const { result, trace } = await recordEffect(flow, { id: 'cause' });
+        assert.equal(result.type, 'Failure');
+
+        // The trace must survive JSON, which is where a non-enumerable cause would silently vanish.
+        const stored = JSON.parse(JSON.stringify(trace));
+        const replayed = await replayEffect(flow(stored.initialInput), stored);
+        assert.equal(replayed.type, 'Failure');
+        const error = /** @type {any} */ (errorOf(replayed));
+        assert.equal(error.message, 'charge declined');
+        assert.ok(error.cause instanceof Error, 'the revived error must keep its cause');
+        assert.equal(error.cause.message, 'card expired');
+    });
+
+    it('should carry a nested cause chain and a non-Error cause', async function () {
+        const flow = (/** @type {any} */ input) =>
+            Command(function cmdFetch() {
+                return Promise.reject(
+                    new Error('fetch failed', { cause: new Error('socket closed', { cause: 'ECONNRESET' }) })
+                );
+            });
+
+        const { trace } = await recordEffect(flow, { id: 'chain' });
+        const stored = JSON.parse(JSON.stringify(trace));
+        const replayed = await replayEffect(flow(stored.initialInput), stored);
+        const error = /** @type {any} */ (errorOf(replayed));
+        assert.equal(error.cause.message, 'socket closed');
+        assert.equal(error.cause.cause, 'ECONNRESET', 'a non-Error cause must pass through unchanged');
+    });
+
     it('should reject a malformed trace as a ReplayError, not a TypeError', async function () {
         const { flow } = makeFlow();
         for (const bad of [undefined, null, 42, {}, { trace: 'nope' }]) {
@@ -2065,3 +2242,24 @@ describe('Parallel cancellation', function () {
         assert.deepEqual(args, [[]], 'a thunk outside a Parallel is called with no arguments at all');
     });
 });
+
+describe('Declaration parity', function () {
+    it('should declare exactly the exports the runtime ships', function () {
+        // index.d.ts is hand-maintained beside index.js, so the two can drift silently: a
+        // declaration once vanished as edit collateral while every check stayed green. This pins
+        // existence in both directions; signatures remain tsd's job.
+        const program = ts.createProgram(['index.d.ts'], { noEmit: true });
+        const source = program.getSourceFile('index.d.ts');
+        assert.ok(source, 'index.d.ts must be part of the program');
+        const checker = program.getTypeChecker();
+        const moduleSymbol = checker.getSymbolAtLocation(/** @type {import('typescript').Node} */ (source));
+        assert.ok(moduleSymbol, 'index.d.ts must be a module');
+        const declared = checker
+            .getExportsOfModule(moduleSymbol)
+            .filter((s) => s.flags & ts.SymbolFlags.Value)
+            .map((s) => s.name)
+            .sort();
+        const shipped = Object.keys(lib).sort();
+        assert.deepEqual(declared, shipped);
+    });
+});

package/test/types.test-d.ts

@@ -104,13 +104,14 @@ const innerCmd = Command(
     (n) => Success(n)
 );
 
-// Retry with options preserves T
+// Retry with options preserves T; the error type is the exhaustion failure, not the inner error,
+// because the interpreter wraps the last inner error rather than letting it escape
 const retried = Retry(innerCmd, { attempts: 3 });
-expectType<RetryState<number, unknown>>(retried);
+expectType<RetryState<number, RetryExhaustedError<unknown>>>(retried);
 
 // Retry without options is valid
 const retriedNoOpts = Retry(innerCmd);
-expectType<RetryState<number, unknown>>(retriedNoOpts);
+expectType<RetryState<number, RetryExhaustedError<unknown>>>(retriedNoOpts);
 
 // Retry in effectPipe preserves type flow
 const retryFlow = effectPipe((input: User) =>
@@ -122,7 +123,35 @@ const retryFlow = effectPipe((input: User) =>
         { attempts: 2 }
     )
 );
-expectType<Effect<SavedUser>>(retryFlow({ email: 'a@b.com', password: 'secret123' }));
+expectType<Effect<SavedUser, RetryExhaustedError<unknown>>>(retryFlow({ email: 'a@b.com', password: 'secret123' }));
+
+// The inner error type survives inside the exhaustion failure, so lastError is typed
+const retriedTyped = Retry(Success(1) as Effect<number, 'net_down'>);
+expectType<RetryState<number, RetryExhaustedError<'net_down'>>>(retriedTyped);
+
+const retryResult = await runEffect(Retry(Success(1) as Effect<number, 'flaky'>, { attempts: 1 }));
+if (retryResult.type === 'Failure') {
+    expectType<RetryExhaustedError<'flaky'>>(retryResult.error);
+    expectType<'flaky'>(retryResult.error.lastError);
+}
+
+// onExhausted consumes the exhaustion, so the fallback's error type is what remains
+const recovered = Retry(Success(1) as Effect<number, 'flaky'>, {
+    attempts: 1,
+    onExhausted: (err) => {
+        expectType<RetryExhaustedError<'flaky'>>(err);
+        return Success(0) as Effect<number, 'cache_miss'>;
+    }
+});
+expectType<RetryState<number, 'cache_miss'>>(recovered);
+
+const recoveredResult = await runEffect(recovered);
+if (recoveredResult.type === 'Failure') {
+    expectType<'cache_miss'>(recoveredResult.error);
+}
+
+// onExhausted is per-use only: global retry defaults cannot carry a fallback
+expectError(configureEffect({ retry: { attempts: 2, onExhausted: () => Success(1) } }));
 
 // RetryExhaustedError shape is usable for narrowing exhaustion failures
 const exhaustedErr: RetryExhaustedError<Error> = {
@@ -168,6 +197,14 @@ expectType<Effect<{ email: string; password: string }>>(parallelFlow({ email: 'a
 const parallelResult = await runEffect(Parallel([Success(1), Success('x')], ([n, s]) => Success({ n, s })));
 expectType<SuccessState<{ n: number; s: string }> | FailureState<unknown>>(parallelResult);
 
+// With next omitted, the Parallel resolves to the values tuple itself
+const parBare = Parallel([Success(42), Success('hello')]);
+expectType<ParallelState<[number, string], [number, string]>>(parBare);
+const parBareResult = await runEffect(parBare);
+if (parBareResult.type === 'Success') {
+    expectType<[number, string]>(parBareResult.value);
+}
+
 // --- Ctx (context type) ---
 
 interface AppCtx {

package/tsconfig.check.json

@@ -0,0 +1,12 @@
+{
+    "compilerOptions": {
+        "allowJs": true,
+        "checkJs": true,
+        "noEmit": true,
+        "target": "es2022",
+        "module": "nodenext",
+        "moduleResolution": "nodenext",
+        "lib": ["es2022", "dom"]
+    },
+    "files": ["index.js"]
+}

package/.claude/settings.local.json

@@ -1,17 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "Bash(npm test *)",
-      "Bash(npm view *)",
-      "Bash(npx mocha *)",
-      "Bash(echo \"exit: $?\")",
-      "Bash(npx prettier *)",
-      "Bash(echo \"npm test exit: $?\")",
-      "Bash(npx tsc *)",
-      "Bash(echo \"tsc exit: $?\")",
-      "Read(//tmp/**)",
-      "Bash(npx esbuild *)",
-      "Bash(gzip -9)"
-    ]
-  }
-}