pure-effect 0.11.0 → 0.13.0

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`,
@@ -221,8 +221,22 @@ const asEffect = (value, source) => {
  * @returns {Effect}
  */
 const chain = (effect, fn, initialInput) => {
+    // The outermost pipeline wins. A step can return a sub-pipeline whose nodes already carry that
+    // sub-pipeline's start, and an outer chain reaches every one of them through the wrapped `next`
+    // continuations, so overwriting here is what makes the whole tree, a Failure from any depth, and
+    // the root a hook-based recorder reads carry the input of the flow that was actually called. The
+    // previous rule, stamp only when unset, let a Retry- or Parallel-headed sub-pipeline leave its own
+    // input on the root, and a trace recorded from it rebuilt the flow from the wrong value. A Success
+    // is never stamped: nothing reads the input off a terminal value, and leaving it bare is what lets
+    // `assert.deepEqual(result, Success(v))` hold whatever shape the flow had.
     const withII = (/** @type {Effect} */ e) =>
-        initialInput !== undefined && e.initialInput === undefined ? { ...e, initialInput } : e;
+        initialInput !== undefined && e.type !== 'Success' ? { ...e, initialInput } : e;
+
+    // A continuation that returned nothing has to be caught before `effect.type` is read. Reading it off
+    // `undefined` throws a bare TypeError, and since every continuation runs inside the interpreter's try
+    // block, that TypeError became a domain Failure: the flow bug took the business-error branch and no
+    // step was named. The `default` arm below never sees it, because the switch itself is what throws.
+    if (effect == null) return asEffect(effect, 'A continuation');
 
     switch (effect.type) {
         case 'Success':
@@ -260,7 +274,14 @@ const chain = (effect, fn, initialInput) => {
 const effectPipe = (...fns) => {
     return (start) => {
         const chainWithII = (/** @type {Effect} */ eff, /** @type {(v: any) => Effect} */ fn) => chain(eff, fn, start);
-        return fns.reduce(chainWithII, /** @type {Effect} */ (Success(start)));
+        const tree = fns.reduce(chainWithII, /** @type {Effect} */ (Success(start)));
+        // One identity pass over the finished tree. `chain` re-stamps a sub-pipeline's nodes only as
+        // it wraps the continuations that lead to them, and the last step has no later step to do
+        // that wrapping, so a sub-pipeline returned by the last step would keep its own input on
+        // everything past its head. The pass wraps those continuations too, so every node reachable
+        // from here, a Failure at any depth included, carries this pipeline's `start`. `Success` is the
+        // identity step: it can never return a non-Effect, so no message is ever attributed to it.
+        return chain(tree, Success, start);
     };
 };
 
@@ -282,12 +303,7 @@ const defaultRunWrapper = async (effect, op, flowName) => await op();
 /** @type CommandInterceptor */
 const defaultCommandInterceptor = async (command, context) => {};
 
-let stepRunner = defaultStepRunner;
-let runWrapper = defaultRunWrapper;
-let commandInterceptor = defaultCommandInterceptor;
-
 const defaultRetryOptions = { attempts: 3, delay: 100, backoff: 1 };
-let retryDefaults = { ...defaultRetryOptions };
 
 /**
  * @typedef {Object} EffectConfiguration
@@ -298,63 +314,77 @@ let retryDefaults = { ...defaultRetryOptions };
  */
 
 /**
- * Configures the global behavior of the Effect runner, including the command interceptor and telemetry.
+ * A per-call configuration: an `EffectConfiguration` plus `inherit`. With `inherit: true` (the default)
+ * the call's hooks are added to the wiring `configureEffect` installed, by the merge `configureEffect`
+ * applies to several configurations: global outermost, interceptors in order, `retry` merging with the
+ * call winning. With `inherit: false` the global wiring is not consulted at all, so any slot the call
+ * leaves unset falls back to the library default. A per-call hook cannot replace a single global slot on
+ * its own; that was the previous default, and it is how a per-call recorder silently switched off an
+ * application's tracing.
  *
- * Several configurations can be passed and are merged, which is how independent concerns share the
- * one slot each hook has:
+ * @typedef {EffectConfiguration & { inherit?: boolean }} CallConfiguration
+ */
+
+/** @type {EffectConfiguration[]} */
+let layers = [];
+
+/**
+ * The installed layers merged into one configuration, empty when nothing is configured. This is the
+ * only derived form of `layers`: `runEffect` reads it and merges the call's configuration over it,
+ * and a slot no layer defines is simply absent, so the library default is chosen at the one place the
+ * hook is used rather than held in a second set of variables kept in step by hand.
+ * @type {EffectConfiguration}
+ */
+let globalConfig = {};
+
+/** Recomputes the effective wiring from the installed layers, earlier layers outermost. */
+const applyLayers = () => {
+    globalConfig = chainHooks(...layers);
+};
+
+/**
+ * Adds a configuration to the global wiring of the Effect runner: telemetry, the command interceptor,
+ * and retry defaults.
  *
- *     configureEffect(telemetryHooks(), recordingHooks({ sink }))
+ * Each call adds one layer on top of those already installed and returns a function that removes that
+ * layer, wherever it sits by then. Layers merge the way several configurations passed to one call do:
+ * `onStep` and `onRun` are wrappers, so they nest with the earliest layer outermost and the latest
+ * closest to the Command; `onBeforeCommand` interceptors all run, in the order installed; and `retry`
+ * merges with later layers winning. So these are the same:
  *
- * `onStep` and `onRun` are wrappers, so they nest with the first configuration outermost and the last
- * closest to the Command. `onBeforeCommand` interceptors all run, in the order given, and `retry`
- * merges with later configurations winning.
+ *     configureEffect(telemetryHooks(), recordingHooks({ sink }));
+ *     configureEffect(telemetryHooks()); configureEffect(recordingHooks({ sink }));
  *
- * Merging happens per call and does not accumulate across calls: a later `configureEffect` still
- * replaces the previous wiring entirely, and calling it with nothing resets every slot to its default.
+ * Calling it with no arguments at all removes every layer. A call whose arguments are all `undefined`
+ * is a conditional install that installed nothing: it adds no layer and removes none.
  *
- * Returns a function that puts back whatever was installed when this call was made, so a caller can
- * install hooks without owning the wiring forever. That is what makes this usable from a test, a
- * request-scoped experiment, or a library that wraps this one: without it, installing anything means
- * clobbering the host's telemetry permanently, since there is no way to read the current wiring.
- * Restoring undoes this call only while its wiring is still in effect. If a later `configureEffect` has
- * run since, restoring does nothing rather than discarding that newer wiring, so two callers installing
- * and releasing in interleaved order cannot clobber each other.
+ * Layers replaced the previous one-slot rule, under which a later call displaced the earlier wiring and
+ * the returned function restored a snapshot, guarded so that interleaved installs could not clobber
+ * each other. Removing a layer needs no guard: A installs, B installs, A removes, and B is still there.
+ * It also means a library can install its own hooks without erasing its host's, which under the old rule
+ * was possible only if the host passed the library's configuration into its own call.
  *
- * @param {...(EffectConfiguration | undefined)} configs - Configurations to merge, outermost first
- * @returns {() => void} Restores the wiring that was in place before this call
+ * @param {...(EffectConfiguration | undefined)} configs - Configurations merged into one layer, outermost first
+ * @returns {() => void} Removes the layer this call added; a second call does nothing
  */
 const configureEffect = (...configs) => {
-    const previousStepRunner = stepRunner;
-    const previousRunWrapper = runWrapper;
-    const previousCommandInterceptor = commandInterceptor;
-    const previousRetryDefaults = retryDefaults;
-
-    const options = chainHooks(...configs);
-    stepRunner = options.onStep ? options.onStep : defaultStepRunner;
-    runWrapper = options.onRun ? options.onRun : defaultRunWrapper;
-    commandInterceptor = options.onBeforeCommand ? options.onBeforeCommand : defaultCommandInterceptor;
-    retryDefaults = options.retry ? { ...defaultRetryOptions, ...options.retry } : defaultRetryOptions;
-
-    const installedStepRunner = stepRunner;
-    const installedRunWrapper = runWrapper;
-    const installedCommandInterceptor = commandInterceptor;
-    const installedRetryDefaults = retryDefaults;
-
+    // Only a call with no arguments at all is a reset. A call whose arguments are all absent, such as
+    // `configureEffect(flag ? hooks : undefined)`, is a conditional install that happened not to install
+    // anything, so it adds no layer and must not remove anyone else's.
+    if (configs.length === 0) {
+        layers = [];
+        applyLayers();
+        return () => {};
+    }
+    const present = configs.filter(Boolean);
+    if (present.length === 0) return () => {};
+    const layer = chainHooks(...present);
+    layers = [...layers, layer];
+    applyLayers();
     return () => {
-        // Only undo an install that is still in effect. Without this check, two callers that install
-        // and release in interleaved order silently discard each other's hooks: A installs, B installs,
-        // A restores, and B's wiring is gone though B never released it.
-        const unchanged =
-            stepRunner === installedStepRunner &&
-            runWrapper === installedRunWrapper &&
-            commandInterceptor === installedCommandInterceptor &&
-            retryDefaults === installedRetryDefaults;
-        if (!unchanged) return;
-
-        stepRunner = previousStepRunner;
-        runWrapper = previousRunWrapper;
-        commandInterceptor = previousCommandInterceptor;
-        retryDefaults = previousRetryDefaults;
+        if (!layers.includes(layer)) return;
+        layers = layers.filter((l) => l !== layer);
+        applyLayers();
     };
 };
 
@@ -501,20 +531,32 @@ const runEffect =
      * Iterates through the Effect tree, executing Commands and handling async flow.
      * Ask effects are resolved synchronously with the context object.
      *
-     * Per-call config takes precedence over global configureEffect defaults.
-     * onRun fires exactly once per runEffect call. Retry attempts run inside that
+     * Per-call config is merged over the global configureEffect wiring, or over nothing under
+     * `inherit: false`. onRun fires exactly once per runEffect call. Retry attempts run inside that
      * single span rather than spawning their own, keeping telemetry non-duplicated.
      *
      * @param {Effect} effect - The Effect tree returned by a pipeline
      * @param {any} [context] - Optional context object. Passed to Ask continuations and the Command Interceptor.
-     * @param {EffectConfiguration} [callConfig] - Per-call overrides; merged over global configureEffect defaults.
+     * @param {CallConfiguration} [callConfig] - Per-call configuration, added to the wiring `configureEffect`
+     *        installed unless `inherit: false`, which ignores that wiring for this run.
      * @returns {Promise<SuccessState | FailureState>}
      */
     async function runEffect(effect, context = {}, callConfig = {}) {
-        const localStepRunner = callConfig.onStep ? callConfig.onStep : stepRunner;
-        const localRunWrapper = callConfig.onRun ? callConfig.onRun : runWrapper;
-        const localCommandInterceptor = callConfig.onBeforeCommand ? callConfig.onBeforeCommand : commandInterceptor;
-        const localRetryDefaults = callConfig.retry ? { ...retryDefaults, ...callConfig.retry } : retryDefaults;
+        const { inherit = true, ...local } = callConfig;
+        // A value that is not a boolean, such as a string left over from an older API, must not be
+        // coerced: `'false'` inheriting everything is exactly the silent behaviour this option removes.
+        if (typeof inherit !== 'boolean') {
+            throw new TypeError(`callConfig.inherit must be true or false, got ${JSON.stringify(inherit)}.`);
+        }
+        // The call's configuration is merged over the installed wiring, or over nothing when the call
+        // inherits nothing, by the same merge `configureEffect` applies to several configurations. Most
+        // calls carry no configuration of their own, and those use the installed wiring as it is.
+        const base = inherit ? globalConfig : {};
+        const resolved = Object.keys(local).length ? chainHooks(base, local) : base;
+        const localStepRunner = resolved.onStep || defaultStepRunner;
+        const localRunWrapper = resolved.onRun || defaultRunWrapper;
+        const localCommandInterceptor = resolved.onBeforeCommand || defaultCommandInterceptor;
+        const localRetryDefaults = { ...defaultRetryOptions, ...resolved.retry };
 
         /**
          * @param {Effect} eff
@@ -657,7 +699,17 @@ const runEffect =
             throw effectTypeError(eff, 'The flow');
         }
 
-        return localRunWrapper(effect, () => execute(effect), context?.flowName || '');
+        // Every Failure leaves through here, including one a Parallel branch or a Retry fallback handed
+        // back. `chain` stamps only what passes through the continuations it wraps, and those subtrees
+        // are executed directly rather than reached through a continuation, so their Failures arrive
+        // carrying the subtree's own input or none. Restamping the outcome with the root's input is
+        // what makes "a Failure carries the input of the flow that was called" true at any depth.
+        const rootInput = effect?.initialInput;
+        const run = async () => {
+            const result = await execute(effect);
+            return result.type === 'Failure' && rootInput !== undefined ? Failure(result.error, rootInput) : result;
+        };
+        return localRunWrapper(effect, run, context?.flowName || '');
     };
 
 /**
@@ -755,11 +807,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;
 };
@@ -886,6 +944,8 @@ const recorder = (options = {}) => {
 const recordEffect = async (flowFn, initialInput, options = {}) => {
     const { context = {}, version, ...recorderOptions } = options;
     const rec = recorder(recorderOptions);
+    // The recorder is added to the global wiring, so recording inside an instrumented application keeps
+    // its spans.
     const result = await runEffect(flowFn(initialInput), context, { onStep: rec.onStep });
     return {
         result,
@@ -908,36 +968,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 +1008,24 @@ const fromTrace = (traceLog, options = {}) => {
                 });
             }
             if (entry.command !== step.name) throw timeParadox(step, entry.command);
-            return entryToOutcome(entry);
+            return resolveEntry(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);
-        };
-    }
-
-    /** @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);
     };
 };
 
@@ -1022,16 +1077,28 @@ const zeroRetryDelays = (eff) => {
  * @typedef {Object} ReplayOptions
  * @property {any} [context] - Context for `Ask`; pass the recorded context to reproduce a run faithfully.
  * @property {boolean} [fastRetry] - Strips Retry delays so a replay does not wait out production backoff.
- * @property {boolean} [hooks] - Lets configured `onRun` and `onBeforeCommand` fire. Off by default, so a
- *           replay cannot reach a telemetry backend or a guardrail that performs I/O.
+ * @property {boolean} [hooks] - Runs the replay inside the hooks `configureEffect` installed, with the
+ *           resolver innermost, so a configured `onStep` observes each replayed step and `onRun` and
+ *           `onBeforeCommand` fire. Off by default, which ignores the global hooks, so a replay cannot
+ *           reach a telemetry backend or a guardrail that performs I/O. Global `retry` defaults apply
+ *           either way, since a replay has to make the attempts production made.
  * @property {'throw' | 'execute'} [onMissing] - What to do when the resolver has no recording for a step.
  *           `'throw'` (default) fails the replay, which makes side effects impossible for the whole run.
  *           `'execute'` runs the real Command, giving partial replay: recorded prefix, live tail.
  * @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 +1118,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} */
@@ -1081,32 +1153,38 @@ const replayEffect = async (effect, traceOrResolver, options = {}) => {
         return outcome.result;
     };
 
-    /** @type {EffectConfiguration} */
-    const callConfig = { onStep };
-    if (!hooks) {
-        callConfig.onRun = async (effect, op) => await op();
-        callConfig.onBeforeCommand = async () => {};
-    }
-
-    return runEffect(fastRetry ? zeroRetryDelays(effect) : effect, context, callConfig);
+    // Off, a replay ignores the global hooks, so it can reach neither a telemetry backend nor a guardrail
+    // that performs I/O. On, it runs inside them with the resolver innermost, so a configured onStep
+    // observes each replayed step and the Command still never executes. The global retry defaults are
+    // kept either way: `inherit: false` would drop them with the hooks, and a Retry that production ran
+    // under a configured `attempts` would then exhaust early on replay and report a Failure production
+    // never saw. Retry shape is part of what a replay reproduces; the hooks are not.
+    /** @type {CallConfiguration} */
+    const callConfig = { onStep, inherit: hooks, retry: globalConfig.retry };
+
+    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 +1202,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 +1222,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/package.json

@@ -1,19 +1,47 @@
 {
     "name": "pure-effect",
-    "version": "0.11.0",
+    "version": "0.13.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.",
+    "keywords": [
+        "effect",
+        "effect-system",
+        "functional-core",
+        "imperative-shell",
+        "time-travel",
+        "replay",
+        "tracing",
+        "testing",
+        "zero-dependencies",
+        "typescript"
+    ],
     "type": "module",
     "exports": "./index.js",
     "types": "./index.d.ts",
+    "files": [
+        "index.js",
+        "index.d.ts",
+        "CHANGELOG.md"
+    ],
+    "sideEffects": false,
+    "engines": {
+        "node": ">=18"
+    },
     "scripts": {
-        "test": "mocha && tsd && tsc -p tsconfig.check.json",
-        "format": "prettier --write index.js index.d.ts examples/*.js test/all.js README.md CLAUDE.md"
+        "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 CHANGELOG.md CONTRIBUTING.md"
     },
     "tsd": {
         "directory": "test"
     },
     "author": "Aycan Gulez",
     "homepage": "https://pure-effect.org",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/aycangulez/pure-effect.git"
+    },
+    "bugs": {
+        "url": "https://github.com/aycangulez/pure-effect/issues"
+    },
     "license": "MIT",
     "devDependencies": {
         "@opentelemetry/api": "^1.9.1",

package/.prettierrc

@@ -1,12 +0,0 @@
-{
-    "tabWidth": 4,
-    "useTabs": false,
-    "singleQuote": true,
-    "semi": true,
-    "trailingComma": "none",
-    "jsxSingleQuote": true,
-    "printWidth": 120,
-    "arrowParens": "always",
-    "endOfLine": "lf",
-    "proseWrap": "never"
-}