pure-effect 0.11.0 → 0.12.0

package/CLAUDE.md

@@ -7,8 +7,9 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 ```bash
 npm test                                          # run all tests
 npx mocha test/all.js --grep "pattern"            # run a single test by name
-npm run format                                    # Prettier over index.js, index.d.ts, examples/*.js, test/all.js, README.md, CLAUDE.md
-npx tsd                                           # type-level gate; the only check that reads index.d.ts
+npm run format                                    # Prettier over index.js, index.d.ts, examples/*.js, test/all.js, test/types.test-d.ts, README.md, CLAUDE.md
+npx tsd                                           # type-level gate over test/types.test-d.ts
+npx tsc -p jsconfig.json                          # strict tsc over index.js, test/all.js, test/types.test-d.ts, and examples/*.js, reading index.d.ts as a consumer; the same config VS Code uses
 npx esbuild index.js --minify --format=esm | gzip -9 | wc -c    # the size the README claims
 ```
 
@@ -46,7 +47,7 @@ The recording and replay exports are a 2x2 rather than four loose helpers: `reco
 
 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.
+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, 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.
 
 Anything that is not an Effect is rejected by `asEffect` / `effectTypeError` with a message naming its source, and the distinction they encode is deliberate: a malformed flow is a bug and throws, while a Command that rejects is a domain outcome and becomes a `Failure`. The interpreter's catch rethrows `EffectTypeError` specifically so a flow bug cannot masquerade as a business error. Two details are important. `chain` validates the return of each pipeline step, which is the only place the offending step's name is known (`fn.name`), so that is where the useful message comes from. And the interpreter's `while` condition guards on `eff &&` before reading `eff.type`, because a continuation returning `undefined` otherwise threw a bare TypeError from the condition itself, outside any handler.
 
@@ -58,10 +59,10 @@ Before this, every one of those mistakes was silent or cryptic: forgetting `Succ
 | --- | --- |
 | `recorder(options?)` | Returns `{ onStep, entries, toTrace }`; the `onStep` hook records every Command's result or error. Options: `redact`, `maxEntries`, `stack` |
 | `recordEffect(flowFn, initialInput, opts?)` | Runs a flow for real while recording; returns `{ result, trace }`. Convenience for tests and scripts |
-| `replayEffect(effect, traceOrResolver, opts?)` | Replays a tree, feeding recorded outcomes to Commands instead of executing them. Takes a trace or a `Resolver`. Options: `context`, `strict`, `fastRetry`, `hooks`, `onMissing`, `onResolved` |
-| `timeTravel(flowFn, traceLog, options?)` | Narrated replay: rebuilds the flow from the recorded input, logs each step, warns on version mismatch and unreached steps |
+| `replayEffect(effect, traceOrResolver, opts?)` | Replays a tree, feeding recorded outcomes to Commands instead of executing them. Takes a trace or a `Resolver`; returns `{ result, unreached }` for a trace and `{ result }` for a `Resolver`. Options: `context`, `fastRetry`, `hooks`, `onMissing`, `onResolved` |
+| `timeTravel(flowFn, traceLog, options?)` | Narrated replay: rebuilds the flow from the recorded input, logs each step, warns on version mismatch and names any unreached steps; returns the bare outcome, since narration is its job |
 
-`fromTrace(traceLog, { strict })`, which builds a `Resolver` over the reference trace format, is **internal**, and `replayEffect` is its only caller. Deliberately not exported: a caller whose traces live in another shape writes a `Resolver` instead, and a caller who only wants to watch a replay uses `onResolved`. Between them those cover every known need, so exporting it would only widen the public surface. The one thing neither covers is _rewriting_ outcomes from a reference-format trace (substituting one step's result, or chaining a fallback), since `onResolved` is an observer whose return value is ignored. Export it again if that comes up; nothing depends on it staying private.
+`fromTrace(traceLog, { onEntry })`, which builds a `Resolver` over the reference trace format, is **internal**, and `replayEffect` is its only caller. Deliberately not exported: a caller whose traces live in another shape writes a `Resolver` instead, and a caller who only wants to watch a replay uses `onResolved`. The `onEntry` observer is how `replayEffect` learns which entries were handed out; it subtracts those from the trace after the run to produce `unreached`, which is why that field exists for a trace and is absent for a `Resolver`. Between them those cover every known need, so exporting it would only widen the public surface. The one thing neither covers is _rewriting_ outcomes from a reference-format trace (substituting one step's result, or chaining a fallback), since `onResolved` is an observer whose return value is ignored. Export it again if that comes up; nothing depends on it staying private.
 
 See **Time-travel debugging** below for the invariants these depend on, and the README for each option in full.
 
@@ -90,7 +91,7 @@ runEffect(tree, context, callConfig?)
   → resolves to final Success or Failure
 
 replayEffect(tree, traceOrResolver, options?)
-  → a trace goes through fromTrace(trace, { strict }); a function is used as the
+  → a trace goes through fromTrace(trace, { onEntry }); a function is used as the
     Resolver as-is (typeof check: an entries array is data, so it takes the
     trace path); a malformed trace rejects with a ReplayError
   → installs an onStep that answers each step from resolve(step) instead of
@@ -115,7 +116,7 @@ There is one slot per hook, and `configureEffect` merges the configurations of a
 
 The raw hooks are powerful: a hook decides whether the Command runs at all, which is how replay suppresses I/O, and anything it throws becomes the flow's outcome. That power is wrong for anything that only watches, and it caused two real bugs here: the tracing example serialized its input before calling `pipeline()`, so a cyclic input left flows unexecuted, and `recorder` let a throwing `redact` turn a successful run into a `Failure` carrying the redaction bug while recording an entry that claimed the Command had thrown. The internal `observeSteps(handler)` now holds that contract in one place: `op` always runs, its result is always returned, its error always propagates, and anything the observer throws is dropped. Keep it minimal and unexported. `recorder` is its only caller and needs only `onStep`, so there is no `onRun` branch and no error-reporting channel, and an exported second route to the raw hooks would widen the surface for integrations nobody has written. It briefly was exported, as `observe`, with both branches; that cost 270 bytes gzipped for one internal call site and no consumer, which is the same argument that removed `tap`.
 
-Trace entries carry `durationMs`, rounded to microseconds, because `observeSteps` measures the span around `op` anyway and nothing else recorded timings. `timeTravel` narrates it, but only under `strict` matching, since per-Command queues do not map a replayed step back to a recorded position.
+Trace entries carry `durationMs`, rounded to microseconds, because `observeSteps` measures the span around `op` anyway and nothing else recorded timings. `timeTravel` narrates it, looking the entry up by path, or by position for a trace that carries none.
 
 `configureEffect` returns a function that restores the wiring in place when it was called, captured as a snapshot of the resolved runners rather than of the options, and it reverts only while that wiring is still installed. The guard matters because the first version reverted unconditionally: two callers installing and releasing in interleaved order silently discarded each other's hooks, which is the same class of silent clobbering the restore function was added to prevent. It exists because the global was otherwise write-only: there is no getter, so anything that installed hooks clobbered its host permanently and could not put things back, which made the global unusable from a test, a scoped experiment, or a library wrapping this one. Restoring is a snapshot and not a stack, so a restore that runs after a later `configureEffect` reverts to the older wiring and discards the newer one. The two are not interchangeable: `restore()` returns to whatever was installed before, while a bare `configureEffect()` asserts a known-clean slate. Suites here want the clean slate, so they reset; `restore()` is for code that installs hooks over someone else's wiring and has to hand it back.
 
@@ -142,27 +143,27 @@ 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 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.
+- **Path matching, with positional matching for traces that carry no paths.** 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. Duplicate paths throw, since a collision would reintroduce the failure paths exist to prevent. A trace whose entries carry no path (recorded before paths existed, or written by hand) is consumed positionally, each entry checked against the Command the flow asks for; exact for sequential flows, and unable to tell `Parallel` branches apart. There is no matching option any more. `strict` used to choose between that positional mode and a per-Command name-queue mode, which was the only way to replay `Parallel` before paths, and **the name-queue mode was 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`. Once paths made it unnecessary the option was removed rather than left as a footgun; a `Resolver` remains the way to match by any other rule. The positional resolver refuses a step whose path shows it is inside a `Parallel` (a `p` segment), with a `ReplayError` that says to add paths, because a positional answer there would be right only when the replay happened to finish in production's order, and silently wrong otherwise.
 
 - **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`, `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.
+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. `reviveError` defines `name` and `cause` as non-enumerable own properties, matching where a native Error keeps them, because the README's determinism check is `assert.deepEqual(replayed, result)` and Node compares own enumerable keys: assigning `e.name = ...` made every revived error carry an extra key and the check failed for every `Failure` while passing for every `Success`, which is exactly the half of the check that matters. A subclass instance still revives as a plain `Error` (the trace carries a name, not a prototype), so the check is documented as holding for plain errors.
 
 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.
 
 `TraceLog` is the reference trace format, not a contract: `replayEffect` also takes a `Resolver`, so any storage shape works by writing one.
 
-`timeTravel` narrates through `replayEffect`'s `onResolved` hook rather than by wrapping a `Resolver`, which is why it can pass the trace straight through and why `fromTrace` needs no public export. Keep that split: `onResolved` is the seam for _observing_ a replay (logging, counting, step assertions), and a `Resolver` is the seam for _supplying_ outcomes. Narration that reaches for a `Resolver` is a sign the wrong seam is being used.
+`timeTravel` narrates through `replayEffect`'s `onResolved` hook rather than by wrapping a `Resolver`, which is why it can pass the trace straight through and why `fromTrace` needs no public export. Keep that split: `onResolved` is the seam for _observing_ a replay (logging, counting, step assertions), and a `Resolver` is the seam for _supplying_ outcomes. `replayEffect` returns `{ result, unreached }` rather than the bare state, mirroring `recordEffect`'s `{ result, trace }`; `timeTravel` narrates the same list and returns the bare outcome, because narration is its whole job and a caller who wants the entries as data has `replayEffect`. `unreached` exists because a flow that stops issuing Commands early mismatches nothing: no `TimeParadox` fires, the replay ends in `Success`, and the recorded steps it never asked for are the only evidence of the divergence. A regression test for a fix that deliberately skips a step asserts which step; every other recording asserts the list is empty. It rides beside the result rather than on it so the flow's outcome stays exactly what production would have returned, and rather than behind an observer option (which it briefly was) because a value handed to a callback exactly once after completion is a return value in disguise, and the `let unreached` it forced into every test was the tell. It is absent, not empty, for a `Resolver`: an empty list would claim knowledge the replay does not have. `timeTravel` still narrates the list, but not after a `TimeParadox` or `ReplayError`, since the flow never got past the divergence and the error already names it. Narration that reaches for a `Resolver` is a sign the wrong seam is being used.
 
 ### TypeScript
 
 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 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.
+`index.d.ts` is hand-maintained beside `index.js`, so the two can drift. Three mechanisms guard the drift: the `Declaration parity` test pins the export lists to each other in both directions; `tsd` checks the declarations against `test/types.test-d.ts`; and `npm test` runs `tsc -p jsconfig.json`, strict `checkJs` over `index.js`, `test/all.js`, and `examples/*.js`. That last leg reads the declarations too, not only the JSDoc: `test/all.js` imports `../index.js`, and TypeScript resolves that to the sibling `index.d.ts` before it considers the JavaScript, so the test suite is checked as a strict consumer of the public types. The 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. It then had to be widened twice for the same reason. The config listed `index.js` alone while `test/all.js` opened with `// @ts-check` and was annotated to typecheck, so an editor showed errors there that the gate never saw. And it ran without `strict`, while VS Code checks JavaScript with `strictNullChecks` and `strictFunctionTypes` by default and consults only `tsconfig.json` or `jsconfig.json`, so it ignored the old `tsconfig.check.json` and reported errors against a green gate. The file is named `jsconfig.json` and is strict precisely so that the editor and the gate read one configuration; keep both properties, and add any checked JavaScript that lives in this repo to its `include` list. `test/types.test-d.ts` is in the list too, which is possible only because its deliberate errors are `@ts-expect-error` directives rather than `expectError` calls (see below). **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.
+Deliberate type errors in `test/types.test-d.ts` are written as `// @ts-expect-error` directives, never as `tsd`'s `expectError(...)`. Both assert that the next expression fails to typecheck, but only the directive is understood by the compiler itself: `expectError` leaves a real diagnostic in the file that `tsd` swallows and every other tool reports, so with it the file showed ten red lines in VS Code and could not be part of the `tsc` gate, which is how a green `tsd` and a red editor coexisted for a while. With the directive, TypeScript suppresses the error and reports `Unused '@ts-expect-error' directive` if it ever stops occurring, and `tsd` fails on that diagnostic, so the assertion is as strong as before (verified by making a suppressed line valid and watching `tsd` fail). What is given up is `expectError`'s check that the error is one of a few specific codes: a directive is satisfied by any error on the line, so keep each suppressed expression small enough that only the intended mistake can fail it, and give every directive a reason. The directive covers exactly one line, so a suppressed expression stays on one line.
 
 `Effect<T, E, Ctx>` carries three type parameters: value type, error union, and context type. `Ctx` flows through `AskState`, `CommandState`, `RetryState`, and all `effectPipe` overloads. `Ask<T, E, Ctx>` types the context callback parameter, and `runEffect<T, E, Ctx>` enforces that the supplied context matches. `Ctx` defaults to `unknown` so existing code without context typing is unaffected.
 
@@ -170,6 +171,8 @@ Error unions need explicit return annotations. A step written as `(i: User): Eff
 
 `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.
 
+Every state type declares `next` as a method signature (`next(result: R): Effect<...>`) rather than a function-typed property, and that is load-bearing under `strictFunctionTypes`. A property's parameter is checked contravariantly, so a `CommandState<never, ...>`, which is what `Command` infers for a function that only throws or returns `Promise.reject(...)`, could not be assigned to `Effect`, whose member is `CommandState<any, ...>`: `any` is not assignable to `never`. Method parameters are checked bivariantly, so the same node is accepted. Nothing is lost, since `Effect` already erases the result type to `any`; what changed is that the throwing Commands in `test/all.js` stopped being type errors under a strict editor. The `tsd` Command section pins a throwing thunk as assignable to `Effect`, directly, under `Retry`, and through `effectPipe`, so a tidy-up that turns the methods back into properties fails the gate.
+
 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
@@ -186,11 +189,11 @@ Two constraints in that file are load-bearing. Telemetry must never decide wheth
 
 `test/all.js` contains all runtime tests and uses a user-registration domain as the running example. Tests assert on the _returned data structures_ (Commands, Failures) rather than on side effects, which is the core usage pattern to preserve. `registerUserFlow` is the same shape as the README's Quick Start, on purpose: `ensureEmailIsAvailable` is a `Command` whose `next` returns `Success(input)`, so the tests and the documentation cannot drift into demonstrating different idioms.
 
-The `Recording and replay` suite builds flows whose Commands count their own invocations, which is how it asserts that a replay performs **zero** I/O, including a case that exercises every primitive at once. It also covers duplicate Command names, recorded-context `Ask`, retry replay and exhaustion, `Parallel` needing `strict: false`, replaying a trace directly and as a bare entries array, malformed traces rejecting with a `ReplayError`, divergence and exhausted traces, `onMissing`, redaction, `maxEntries` with `dropped`, recorder independence, and `timeTravel`'s narration, including a `Parallel` narration case, which proves `timeTravel` still forwards `strict` now that it no longer resolves the trace itself.
+The `Recording and replay` suite builds flows whose Commands count their own invocations, which is how it asserts that a replay performs **zero** I/O, including a case that exercises every primitive at once. It also covers duplicate Command names, recorded-context `Ask`, retry replay and exhaustion, `Parallel` replaying by path in either finishing order, replaying a trace directly and as a bare entries array, malformed traces rejecting with a `ReplayError`, divergence and exhausted traces, `unreached` (a shortened flow, full consumption, a paradox mid-replay, legacy and bare-array traces, and absence under a `Resolver`), a path-less `Parallel` trace refused, `onMissing`, redaction, `maxEntries` with `dropped`, recorder independence, and `timeTravel`'s narration, including a `Parallel` narration case and a paradox that suppresses the unreached warning.
 
-The `Malformed flows` suite covers the guard: the offending step named, a missing return called what it usually is, a continuation returning a plain value, a flow passed without its input, a flow bug thrown rather than folded into a `Failure`, and a thrown Command still becoming one. The `Command identity` suite pins the resolution order: `meta.name` winning over a named thunk, an inline arrow becoming identifiable through `meta.name`, both fallbacks, non-object and non-string metas ignored, and `meta.name` surviving the rebuild that `chain` performs on every pipe step so it reaches both a trace and a strict replay. The `Recorded step timings` suite reaches `observeSteps` through its only public consumer rather than testing an internal directly: durations recorded for both successful and thrown Commands, rounding, timings not disturbing replay, and an observation failure leaving the outcome alone. The `examples/opentelemetry-example.js` suite injects a stub tracer through the `tracer` option, which is why that option exists, and covers the cyclic input, values never reaching spans, span naming and nesting, error status on a thrown Command, and composition with recording. The `configureEffect merging` suite pins the composition semantics behaviourally rather than by inspecting a merged object: wrapper nesting order, unwind order on a thrown Command, interceptors all running, `retry` merging where attempts come from one configuration and the delay from another, slots left at their defaults, no accumulation across calls, a bare call resetting everything, and the restore function putting back a previous wiring, returning to no hooks, and reverting `retry` defaults. The `examples/recording-example.js` suite runs the reference wiring itself, covering a trace reaching the sink on failure, successes staying out of it, concurrent runs keeping separate traces, redaction before the sink, and recording composing with a telemetry hook.
+The `Malformed flows` suite covers the guard: the offending step named, a missing return called what it usually is, a continuation returning a plain value, a flow passed without its input, a flow bug thrown rather than folded into a `Failure`, and a thrown Command still becoming one. The `Command identity` suite pins the resolution order: `meta.name` winning over a named thunk, an inline arrow becoming identifiable through `meta.name`, both fallbacks, non-object and non-string metas ignored, and `meta.name` surviving the rebuild that `chain` performs on every pipe step so it reaches both a trace and a replay. The `Recorded step timings` suite reaches `observeSteps` through its only public consumer rather than testing an internal directly: durations recorded for both successful and thrown Commands, rounding, timings not disturbing replay, and an observation failure leaving the outcome alone. The `examples/opentelemetry-example.js` suite injects a stub tracer through the `tracer` option, which is why that option exists, and covers the cyclic input, values never reaching spans, span naming and nesting, error status on a thrown Command, and composition with recording. The `configureEffect merging` suite pins the composition semantics behaviourally rather than by inspecting a merged object: wrapper nesting order, unwind order on a thrown Command, interceptors all running, `retry` merging where attempts come from one configuration and the delay from another, slots left at their defaults, no accumulation across calls, a bare call resetting everything, and the restore function putting back a previous wiring, returning to no hooks, and reverting `retry` defaults. The `examples/recording-example.js` suite runs the reference wiring itself, covering a trace reaching the sink on failure, successes staying out of it, concurrent runs keeping separate traces, redaction before the sink, and recording composing with a telemetry hook.
 
-`test/types.test-d.ts` contains type-level tests using `tsd`, verifying that generic type parameters flow correctly through `effectPipe` and `runEffect`.
+`test/types.test-d.ts` contains type-level tests using `tsd`, verifying that generic type parameters flow correctly through `effectPipe` and `runEffect`. Its negative cases are `@ts-expect-error` directives rather than `expectError` calls, for the reason given in the TypeScript section.
 
 ### Example code in the README
 

package/README.md

@@ -99,7 +99,7 @@ assert.equal(step2.cmd.name, 'cmdSaveUser');
 
 ## 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. 
+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.
 
@@ -132,13 +132,28 @@ A production incident becomes a permanent test of the flow's logic, with no mock
 
 ```js
 it('prod incident 8f3a: a 100% promo produces a $0 charge', async () => {
-    const result = await replayEffect(checkoutFlow(trace.initialInput), trace);
+    const { result } = await replayEffect(checkoutFlow(trace.initialInput), trace);
     assert.equal(result.type, 'Failure');
     assert.equal(result.error.code, 'invalid_amount');
 });
 ```
 
-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.
+The test verifies that the flow still takes the recorded path and handles the recorded outcomes the same way: a refactor that reorders or replaces a step raises a `TimeParadox` naming the path it diverged at, and changed error handling fails the assertion.
+
+One divergence is quieter. A flow that stops issuing Commands before the recording ends (a fix that skips the charge, say) mismatches nothing, so no paradox fires and the replay can end in `Success` with recorded steps left over. `replayEffect` returns those steps as `unreached` beside the result, so a test can say which ones it expects to skip, and fail if the answer changes:
+
+```js
+it('incident 8f3a fixed: a 100% promo checks out without a charge', async () => {
+    const { result, unreached } = await replayEffect(checkoutFlow(trace.initialInput), trace);
+    assert.equal(result.type, 'Success');
+    assert.deepEqual(
+        unreached.map((e) => e.command),
+        ['cmdChargeCard']
+    );
+});
+```
+
+For every other recording of the flow, `unreached` should be empty: a fix that skips a step it was not meant to skip then fails loudly instead of passing.
 
 **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.
 
@@ -146,10 +161,12 @@ The test verifies that the flow still takes the recorded path and handles the re
 
 ```js
 const { result, trace } = await recordEffect(registerUserFlow, input);
-const replayed = await replayEffect(registerUserFlow(input), trace);
+const { result: replayed } = await replayEffect(registerUserFlow(input), trace);
 assert.deepEqual(replayed, result); // fails if any step computed a fresh value
 ```
 
+The comparison holds for a `Failure` as well: an error that crossed the trace is revived with the same message, name, cause, and custom properties, and compares deep-equal to the one the Command threw. The one exception is an error class of your own, which revives as a plain `Error` carrying that class's name; compare `error.name` and `error.message` there.
+
 **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
@@ -540,7 +557,7 @@ Runs a flow for real while recording, returning `{ result, trace }`. Accepts `re
 
 #### `replayEffect(effect, traceOrResolver, options?)`
 
-Replays an effect tree, feeding recorded results to Commands instead of running them.
+Replays an effect tree, feeding recorded results to Commands instead of running them. Returns `{ result, unreached }`: the flow's outcome, and the recorded entries the flow never asked for (empty when every step was reached). A flow that stops early mismatches nothing and raises no `TimeParadox`, so `unreached` is where that divergence shows. For a resolver only `{ result }` is returned, since only a trace knows what it holds.
 
 - `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.context`: context for `Ask`; pass the recorded context.
@@ -549,9 +566,11 @@ Replays an effect tree, feeding recorded results to Commands instead of running
 - `options.hooks` (default `false`): whether configured `onRun` / `onBeforeCommand` may fire. Off so a replay cannot reach a telemetry backend.
 - `options.onResolved(step, outcome)`: observe each replayed step.
 
+A trace whose entries carry no `path` (written by hand, or recorded before paths existed) is matched positionally, which is exact for a sequential flow; a `Parallel` step in such a trace is refused with a `ReplayError`, since completion order cannot tell its branches apart.
+
 #### `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`. Takes `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, naming any recorded steps that were never reached and warning when the trace's `version` differs from `options.version`. Returns the flow's outcome; for the unreached entries as data, use `replayEffect`. Takes `options.context` to override the trace's, and `options.log` in place of `console.log`.
 
 ## Limitations
 

package/index.d.ts

@@ -27,14 +27,19 @@ export type CommandState<R, T, E = unknown, Ctx = unknown> = {
      * `Parallel` no argument is passed at all.
      */
     cmd: (signal?: AbortSignal) => Promise<R> | R;
-    next: (result: R) => Effect<T, E, Ctx>;
+    /**
+     * Method syntax, not a function-typed property, on every state's `next`: `strictFunctionTypes`
+     * checks a property's parameter contravariantly, which made a `CommandState<never, ...>` (a `cmd`
+     * that only throws) unassignable to `Effect`. Method parameters are bivariant, so it is accepted.
+     */
+    next(result: R): Effect<T, E, Ctx>;
     meta?: CommandMeta;
     initialInput?: unknown;
 };
 
 export type AskState<T, E = unknown, Ctx = unknown> = {
     type: 'Ask';
-    next: (context: Ctx) => Effect<T, E, Ctx>;
+    next(context: Ctx): Effect<T, E, Ctx>;
     initialInput?: unknown;
 };
 
@@ -53,7 +58,7 @@ export type RetryState<T, E = unknown, Ctx = unknown> = {
     type: 'Retry';
     effect: Effect<T, any, Ctx>;
     options: RetryOptions & { onExhausted?: (error: RetryExhaustedError<any>) => Effect<T, any, Ctx> };
-    next: (value: T) => Effect<T, E, Ctx>;
+    next(value: T): Effect<T, E, Ctx>;
     initialInput?: unknown;
 };
 
@@ -66,7 +71,7 @@ export type RetryExhaustedError<E = unknown> = {
 export type ParallelState<T extends readonly unknown[], R, E = unknown, Ctx = unknown> = {
     type: 'Parallel';
     effects: { [K in keyof T]: Effect<T[K], E, Ctx> };
-    next: (values: [...T]) => Effect<R, E, Ctx>;
+    next(values: [...T]): Effect<R, E, Ctx>;
     initialInput?: unknown;
 };
 
@@ -406,29 +411,45 @@ export interface ReplayOptions<Ctx = unknown> {
      */
     onMissing?: 'throw' | 'execute';
     onResolved?: (step: ReplayStep, outcome: ReplayOutcome | undefined) => void;
-    /**
-     * 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;
+}
+
+/**
+ * What a replay returns: the flow's own outcome and, for a trace, the recorded entries the flow
+ * never asked for. A flow that stops issuing Commands early mismatches nothing, so `result` can be a
+ * `Success` with steps left over; `unreached` is where that shows. It is absent for a Resolver,
+ * since only a trace knows what it holds.
+ */
+export interface Replay<T, E = unknown> {
+    result: SuccessState<T> | FailureState<E>;
+    unreached: TraceEntry[];
 }
 
 /**
  * Pass a trace to replay it directly, or a Resolver when traces are stored in some other
  * shape. To observe a replay rather than change how it resolves, use `onResolved`.
  * A malformed trace rejects with a `ReplayError`.
+ *
+ * Three overloads: a trace yields `unreached`, a Resolver yields none, and a source only known
+ * as the union of the two (a wrapper forwarding whatever it was handed) yields it as optional.
  */
+export declare function replayEffect<T, E = unknown, Ctx = unknown>(
+    effect: Effect<T, E, Ctx>,
+    trace: TraceLog | TraceEntry[],
+    options?: ReplayOptions<Ctx>
+): Promise<Replay<T, E>>;
+export declare function replayEffect<T, E = unknown, Ctx = unknown>(
+    effect: Effect<T, E, Ctx>,
+    resolver: Resolver,
+    options?: ReplayOptions<Ctx>
+): Promise<Omit<Replay<T, E>, 'unreached'>>;
 export declare function replayEffect<T, E = unknown, Ctx = unknown>(
     effect: Effect<T, E, Ctx>,
     traceOrResolver: Resolver | TraceLog | TraceEntry[],
     options?: ReplayOptions<Ctx>
-): Promise<SuccessState<T> | FailureState<E>>;
+): Promise<Omit<Replay<T, E>, 'unreached'> & { unreached?: TraceEntry[] }>;
 
 export declare function timeTravel<T, E = unknown, Ctx = unknown>(
     flowFn: (input: any) => Effect<T, E, Ctx>,
     traceLog: TraceLog,
-    options?: { strict?: boolean; log?: (...args: any[]) => void; context?: Ctx; version?: string }
+    options?: { log?: (...args: any[]) => void; context?: Ctx; version?: string }
 ): Promise<SuccessState<T> | FailureState<E>>;

package/index.js

@@ -89,7 +89,7 @@ const Command = (cmd, next = (/** @type {any} */ result) => Success(result), met
 });
 
 /**
- * The name a Command is known by: what a trace records, what strict replay matches on, and what a
+ * The name a Command is known by: what a trace records, what replay matches on, and what a
  * telemetry span is called.
  *
  * `meta.name` wins when it is a non-empty string. Otherwise the identity is the thunk's own `name`,
@@ -755,11 +755,17 @@ const serializeError = (e, withStack) => {
 const reviveError = (v) => {
     if (!v || typeof v !== 'object' || v.__error !== true) return v;
     const e = new Error(v.message);
-    e.name = v.name;
+    // `name` and `cause` are non-enumerable on a native Error (`name` is inherited, `cause` is set by the
+    // constructor), so they are defined the same way here. Assigning them would make them own enumerable
+    // keys, and the revived error would then never compare deep-equal to the one the Command threw, which
+    // is what the record-then-replay determinism check relies on. Everything else was enumerable on the
+    // original, since `serializeError` read it through `Object.keys`, so plain assignment is faithful.
+    const hidden = { enumerable: false, configurable: true, writable: true };
+    Object.defineProperty(e, 'name', { ...hidden, value: v.name });
     for (const [k, val] of Object.entries(v)) {
-        if (k !== '__error' && k !== 'name' && k !== 'message') {
-            /** @type {any} */ (e)[k] = k === 'cause' ? reviveError(val) : val;
-        }
+        if (k === '__error' || k === 'name' || k === 'message') continue;
+        if (k === 'cause') Object.defineProperty(e, 'cause', { ...hidden, value: reviveError(val) });
+        else /** @type {any} */ (e)[k] = val;
     }
     return e;
 };
@@ -908,36 +914,36 @@ const entryToOutcome = (entry) => ('error' in entry ? { error: reviveError(entry
  *
  * 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.
+ * and still paradox-detecting: it works for `Parallel` as it is, and it tells two branches that
+ * call the same Command apart by where they are rather than by which finished first.
  *
- * 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.
+ * A trace whose entries carry no path (recorded before paths existed, or written by hand) is
+ * matched positionally: entries are consumed in recorded order and each must name the Command the
+ * flow asks for. That is exact for sequential flows and cannot tell `Parallel` branches apart, which
+ * is what paths were added to fix.
  *
  * @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`).
- *        Ignored for a trace carrying paths.
+ * @param {(entry: TraceEntry) => void} [options.onEntry] - Observes each entry as it is handed to a step,
+ *        which is how `replayEffect` learns which recorded entries the flow never asked for.
  * @returns {Resolver}
  */
 const fromTrace = (traceLog, options = {}) => {
-    const { strict = true } = options;
+    const { onEntry } = options;
     const entries = Array.isArray(traceLog) ? traceLog : traceLog?.trace;
     if (!Array.isArray(entries)) throw replayError('Trace has no `trace` array.');
+    const resolveEntry = (/** @type {TraceEntry} */ entry) => {
+        if (onEntry) onEntry(entry);
+        return entryToOutcome(entry);
+    };
 
-    // 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.');
+            throw replayError('Trace has duplicate step paths.');
         }
         return (step) => {
             const entry = byPath.get(step.path);
@@ -948,29 +954,24 @@ const fromTrace = (traceLog, options = {}) => {
                 });
             }
             if (entry.command !== step.name) throw timeParadox(step, entry.command);
-            return entryToOutcome(entry);
-        };
-    }
-
-    if (strict) {
-        return (step) => {
-            const entry = entries[step.index];
-            if (!entry) throw replayError(`Trace exhausted: no entry #${step.index} for '${step.name}'.`);
-            if (entry.command !== step.name) throw timeParadox(step, entry.command);
-            return entryToOutcome(entry);
+            return resolveEntry(entry);
         };
     }
 
-    /** @type {Map<string, TraceEntry[]>} */
-    const queues = new Map();
-    for (const entry of entries) {
-        if (!queues.has(entry.command)) queues.set(entry.command, []);
-        /** @type {TraceEntry[]} */ (queues.get(entry.command)).push(entry);
-    }
     return (step) => {
-        const queue = queues.get(step.name);
-        if (!queue || queue.length === 0) throw replayError(`No recorded result left for '${step.name}'.`);
-        return entryToOutcome(/** @type {TraceEntry} */ (queue.shift()));
+        // Positional matching pairs steps by completion order, which is exactly what makes Parallel
+        // branches indistinguishable. Refusing is better than a result that is right only when the
+        // replay happens to finish in production's order.
+        if (typeof step.path === 'string' && /p\d+\//.test(step.path)) {
+            throw replayError(
+                `Trace carries no paths, so '${step.name}' inside a Parallel cannot be matched positionally.`,
+                { command: step.name, path: step.path }
+            );
+        }
+        const entry = entries[step.index];
+        if (!entry) throw replayError(`Trace exhausted: no entry #${step.index} for '${step.name}'.`);
+        if (entry.command !== step.name) throw timeParadox(step, entry.command);
+        return resolveEntry(entry);
     };
 };
 
@@ -1028,10 +1029,19 @@ const zeroRetryDelays = (eff) => {
  *           `'throw'` (default) fails the replay, which makes side effects impossible for the whole run.
  *           `'execute'` runs the real Command, giving partial replay: recorded prefix, live tail.
  * @property {(step: ReplayStep, outcome: ReplayOutcome | undefined) => void} [onResolved] - Observes each step.
- * @property {boolean} [strict] - 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`.
- *           Ignored when a Resolver is supplied, since that Resolver has already chosen how it matches.
+ */
+
+/**
+ * What a replay returns: the flow's own outcome, and, when a trace was supplied, the recorded
+ * entries the flow never asked for. `unreached` is absent for a Resolver, since only a trace
+ * knows what it holds.
+ *
+ * A flow that stops issuing Commands before its recording ends mismatches nothing, so no
+ * `TimeParadox` fires and `result` can be a `Success` with recorded steps left over. That is
+ * sometimes the point of a fix and sometimes a fix that quietly dropped a step; `unreached` is
+ * the only place the difference shows, which is why it travels with the result rather than
+ * behind an option.
+ * @typedef {{ result: SuccessState | FailureState, unreached?: TraceEntry[] }} Replay
  */
 
 /**
@@ -1051,15 +1061,20 @@ const zeroRetryDelays = (eff) => {
  *        Resolver supplying each Command's recorded outcome (`undefined` if it has none). Write a Resolver when
  *        traces are stored in some other shape; to observe a replay without one, use `onResolved`.
  * @param {ReplayOptions} [options]
- * @returns {Promise<SuccessState | FailureState>}
+ * @returns {Promise<Replay>} `{ result, unreached }` for a trace, `{ result }` for a Resolver
  */
 // `async` so a malformed trace arrives as a rejection rather than a synchronous throw:
 // the function otherwise returns a promise, and callers should not have to handle both.
 const replayEffect = async (effect, traceOrResolver, options = {}) => {
-    const { context = {}, fastRetry = true, hooks = false, onMissing = 'throw', onResolved, strict = true } = options;
+    const { context = {}, fastRetry = true, hooks = false, onMissing = 'throw', onResolved } = options;
     // A trace is data and a Resolver is a function, so nothing else is needed to tell them
     // apart, including the bare entries array that `fromTrace` also accepts.
-    const resolve = typeof traceOrResolver === 'function' ? traceOrResolver : fromTrace(traceOrResolver, { strict });
+    const fromResolver = typeof traceOrResolver === 'function';
+    /** @type {Set<TraceEntry>} */
+    const reached = new Set();
+    const resolve = fromResolver
+        ? traceOrResolver
+        : fromTrace(traceOrResolver, { onEntry: (entry) => void reached.add(entry) });
     let index = 0;
 
     /** @type {StepRunner} */
@@ -1088,25 +1103,29 @@ const replayEffect = async (effect, traceOrResolver, options = {}) => {
         callConfig.onBeforeCommand = async () => {};
     }
 
-    return runEffect(fastRetry ? zeroRetryDelays(effect) : effect, context, callConfig);
+    const result = await runEffect(fastRetry ? zeroRetryDelays(effect) : effect, context, callConfig);
+    if (fromResolver) return { result };
+    // `fromTrace` has already validated the shape, so the entries are here in one form or the other.
+    const entries = Array.isArray(traceOrResolver) ? traceOrResolver : traceOrResolver.trace;
+    return { result, unreached: entries.filter((entry) => !reached.has(entry)) };
 };
 
 /**
  * Replays a reference-format trace and narrates each step. Rebuilds the flow from the
- * recorded input, reports the outcome, and warns when recorded steps were never
+ * recorded input, reports the outcome, and names any recorded steps that were never
  * reached, which means the current code issued fewer Commands than production did.
  *
  * @param {(input: any) => Effect} flowFn - The same flow function that produced the trace
  * @param {TraceLog} traceLog - A trace from `recordEffect` or a `recorder`
  * @param {Object} [options]
- * @param {boolean} [options.strict] - Positional matching with paradox detection; set `false` for `Parallel`
  * @param {(...args: any[]) => void} [options.log] - Defaults to `console.log`
  * @param {any} [options.context] - Overrides the context stored on the trace
  * @param {string} [options.version] - Current build id; warns when it differs from the trace's
- * @returns {Promise<SuccessState | FailureState>}
+ * @returns {Promise<SuccessState | FailureState>} The flow's outcome. Narration is the point of this function;
+ *          a caller who wants the unreached entries as data uses `replayEffect`.
  */
 const timeTravel = async (flowFn, traceLog, options = {}) => {
-    const { strict = true, log = console.log, context, version } = options;
+    const { log = console.log, context, version } = options;
     const { initialInput, trace, flowName, version: traceVersion } = traceLog;
     // `message` and `stack` are non-enumerable on Error, so JSON.stringify alone would
     // drop the most useful line of the report.
@@ -1124,22 +1143,19 @@ const timeTravel = async (flowFn, traceLog, options = {}) => {
 
     // 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;
     // 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.
+    // timings are narrated for Parallel too. Positional lookup is the fallback for a trace with no paths,
+    // which is how such a trace is matched anyway.
     const byPath = new Map(trace.filter((e) => typeof e.path === 'string').map((e) => [e.path, e]));
     const timing = (/** @type {ReplayStep} */ step) => {
-        const recorded = byPath.get(step.path) ?? (strict ? trace[step.index] : undefined);
+        const recorded = byPath.get(step.path) ?? trace[step.index];
         return typeof recorded?.durationMs === 'number' ? ` in ${recorded.durationMs}ms` : '';
     };
-    const result = await replayEffect(flowFn(initialInput), traceLog, {
-        strict,
+    const replay = await replayEffect(flowFn(initialInput), traceLog, {
         context: context !== undefined ? context : traceLog.context || {},
         onResolved: (step, outcome) => {
             // Resolving from a trace either answers or throws, so this is never undefined.
             if (outcome === undefined) return;
-            consumed++;
             log(
                 'error' in outcome
                     ? `Step ${step.index + 1}: ${step.name} threw${timing(step)} ${format(outcome.error)}`
@@ -1147,11 +1163,21 @@ const timeTravel = async (flowFn, traceLog, options = {}) => {
             );
         }
     });
+    const { result, unreached = [] } = replay;
 
     log(`Replay finished with state: ${result.type}`);
     log(result.type === 'Failure' ? `Error: ${format(result.error)}` : `Result: ${format(result.value)}`);
-    if (consumed < trace.length) {
-        log(`Warning: ${trace.length - consumed} recorded ${stepsText} were never reached. The flow diverged.`);
+    // After a replay error the flow never got past the divergence, so the entries behind it are not
+    // news; the error already names where the timeline split. Only a flow that ended on its own terms
+    // with steps left over is worth a warning.
+    const haltedByReplay = result.type === 'Failure' && /^(TimeParadox|ReplayError)$/.test(result.error?.name);
+    if (unreached.length > 0 && !haltedByReplay) {
+        // Named, not just counted: the step a fix stopped issuing is usually the one under suspicion.
+        const names = unreached.map((e) =>
+            typeof e.path === 'string' ? `${e.command} (path '${e.path}')` : e.command
+        );
+        const count = unreached.length === 1 ? '1 recorded step was' : `${unreached.length} recorded steps were`;
+        log(`Warning: ${count} never reached: ${names.join(', ')}. The flow diverged.`);
     }
     return result;
 };

package/{tsconfig.check.json → jsconfig.json}

@@ -2,11 +2,12 @@
     "compilerOptions": {
         "allowJs": true,
         "checkJs": true,
+        "strict": true,
         "noEmit": true,
         "target": "es2022",
         "module": "nodenext",
         "moduleResolution": "nodenext",
         "lib": ["es2022", "dom"]
     },
-    "files": ["index.js"]
+    "include": ["index.js", "test/all.js", "test/types.test-d.ts", "examples/*.js"]
 }