pure-effect 0.10.0 → 0.12.0

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;
 };
 
@@ -44,11 +49,16 @@ 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;
-    next: (value: T) => Effect<T, E, Ctx>;
+    effect: Effect<T, any, Ctx>;
+    options: RetryOptions & { onExhausted?: (error: RetryExhaustedError<any>) => Effect<T, any, Ctx> };
+    next(value: T): Effect<T, E, Ctx>;
     initialInput?: unknown;
 };
 
@@ -61,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;
 };
 
@@ -93,10 +103,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> },
@@ -376,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

@@ -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
@@ -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`,
@@ -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;
 };
@@ -725,9 +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] = 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;
 };
@@ -876,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);
@@ -916,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);
     };
 };
 
@@ -956,13 +989,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':
@@ -988,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
  */
 
 /**
@@ -1011,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} */
@@ -1048,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.
@@ -1084,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)}`
@@ -1107,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/jsconfig.json

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

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.12.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",
-        "format": "prettier --write index.js index.d.ts examples/*.js test/all.js README.md CLAUDE.md"
+        "test": "mocha && tsd && tsc -p jsconfig.json",
+        "format": "prettier --write index.js index.d.ts examples/*.js test/all.js test/types.test-d.ts 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",