pure-effect 0.18.0 → 0.20.0

package/index.js

@@ -4,12 +4,15 @@
 //
 // 1. Types: the JSDoc shapes of the nodes a flow is made of.
 // 2. Building flows: the constructors; the checks, error messages and kinds of failure the later sections
-//    share, `checkOptions` and `Retry`'s defaults among them; and `effectPipe`, with the `chain` that joins its
-//    steps and the `flowInputs` it records for `onRun`.
+//    share, `checkOptions` and `Retry`'s defaults among them; `effectPipe`, with the `chain` that joins its
+//    steps, the stop listeners and `restarts` `chain` keeps for generator flows, and the `flowInputs` it records
+//    for `onRun` and `recordEffect`; and `step` and `effectGen`, which build a flow from a generator function.
 // 3. Configuration: the hook types and their defaults, `configureEffect` and its layers, and `chainHooks`, which
 //    merges them.
 // 4. Running flows: the helpers `Retry`, `Parallel` and Commands run on; `interpret`, which builds a run's
-//    `Runtime`, then `execute` and a function for each kind of node, which each take it; and `runEffect`.
+//    `Runtime`, then `stopAt`, which tells a waiting generator flow its step stopped, `ownRun`, which builds a
+//    generator flow again for each execution after its first, `execute` and a function for each kind of node,
+//    which each take it; and `runEffect`.
 // 5. Recording and replay: the trace format and replay errors, copying values and errors into a trace,
 //    `recorder` and `recordEffect`, then `fromTrace`, `replayEffect` and `timeTravel`, each followed by the
 //    functions it hands its parts to.
@@ -45,7 +48,7 @@
  * @typedef {{
  *   type: 'Retry',
  *   effect: Effect,
- *   options: Readonly<{ attempts?: number, delay?: number, backoff?: number, onExhausted?: (error: any) => Effect }>,
+ *   options: Readonly<{ retries?: number, delay?: number, backoff?: number, onExhausted?: (error: any) => Effect }>,
  *   next: (value: any) => Effect
  * }} RetryState
  */
@@ -137,10 +140,14 @@ const commandName = (eff) => {
 
 /**
  * Reads the context object from the current `runEffect` call.
- * @param {(context: any) => Effect} next - Receives the context and returns the next Effect
+ * @param {...((context: any) => Effect)} args - `next`, which receives the context and returns the next Effect. With
+ *        no argument, the Ask succeeds with the context itself, as `yield* step(Ask())` reads it.
  * @returns {AskState}
  */
-const Ask = (next) => {
+const Ask = (...args) => {
+    // Only a call with no argument: an explicit `undefined` is usually a misspelt name.
+    if (args.length === 0) return { type: 'Ask', next: (/** @type {any} */ context) => Success(context) };
+    const [next] = args;
     if (typeof next !== 'function') {
         throw malformed(`Ask expects a function that receives the context, got ${describeArgument(next)}.`, next);
     }
@@ -156,12 +163,12 @@ const Ask = (next) => {
  *
  * @param {Effect} effect - The inner Effect tree to retry
  * @param {Object} [options] - Merged over the defaults when it runs; an option set to `undefined` keeps its default.
- * @param {number} [options.attempts] - Retries after the first try, a positive integer
+ * @param {number} [options.retries] - Tries after the first, a positive integer
  * @param {number} [options.delay] - Ms before the first retry, a finite number of 0 or more
  * @param {number} [options.backoff] - Multiplier applied to the delay on each later retry, a finite number of 0 or
  *        more
  * @param {(error: any) => Effect} [options.onExhausted] - Builds a fallback from `{ retryExhausted, lastError,
- *        attempts }` once every attempt has failed. Its success feeds `next`; its failure propagates unwrapped.
+ *        retries }` once every attempt has failed. Its success feeds `next`; its failure propagates unwrapped.
  * @returns {RetryState}
  */
 const Retry = (effect, options) => {
@@ -169,7 +176,7 @@ const Retry = (effect, options) => {
     if (typeof options === 'number') {
         const got = describeArgument(options);
         throw malformed(
-            `Retry's options must be an object, got ${got}: write Retry(effect, { attempts: ${options} }).`,
+            `Retry's options must be an object, got ${got}: write Retry(effect, { retries: ${options} }).`,
             options
         );
     }
@@ -311,7 +318,7 @@ const checkOptions = (options, source, rules, raise = (message) => new TypeError
 };
 
 /** What `Retry` uses for an option left out or set to `undefined`. */
-const defaultRetryOptions = { attempts: 3, delay: 100, backoff: 1 };
+const defaultRetryOptions = { retries: 3, delay: 100, backoff: 1 };
 
 /**
  * Checked when the Retry is built, which keeps a frozen copy of the options, so they cannot change before it runs.
@@ -319,7 +326,7 @@ const defaultRetryOptions = { attempts: 3, delay: 100, backoff: 1 };
  */
 const retryOptionRules = {
     // Not 0, which would make `onExhausted` a catch.
-    attempts: [
+    retries: [
         isPositiveInteger,
         'a positive integer',
         "To handle an outcome without retrying, branch on it as data in the Command's next, or isolate a failing " +
@@ -486,21 +493,76 @@ const asEffect = (value, source) => {
  * @param {Effect} effect - The current Effect object
  * @param {(value: any) => Effect} fn - The next function to run if the current effect is a Success
  * @param {Effect} [from] - The node whose `next` returned `effect`, which an error names
+ * @param {StopListener} [onStop] - Set by `effectGen`: told when a Failure passes `fn`, and kept on each copy for
+ *        `execute`'s `stopAt`, which calls it when the copy itself stops the flow
  * @returns {Effect} The composed Effect
  */
-const chain = (effect, fn, from) => {
+const chain = (effect, fn, from, onStop) => {
     // Before reading `.type`, so a missing return is named rather than thrown as a bare TypeError.
     if (!isEffect(effect)) throw effectTypeError(effect, from ? nextOf(from) : 'A continuation');
     if (effect.type === 'Success') return asEffect(fn(effect.value), `Step '${fn.name || 'anonymous'}'`);
-    if (effect.type === 'Failure') return effect;
-    const next = (/** @type {any} */ value) => chain(effect.next(value), fn, effect);
+    if (effect.type === 'Failure') {
+        onStop?.(from);
+        return effect;
+    }
+    const next = (/** @type {any} */ value) => chain(effect.next(value), fn, effect, onStop);
     // A Command goes back through its constructor, which checks the function of one built by hand.
-    return effect.type === 'Command' ? Command(effect.cmd, next, effect.meta) : { ...effect, next };
+    const copy = effect.type === 'Command' ? Command(effect.cmd, next, effect.meta) : { ...effect, next };
+    const waiting = stopListeners.get(effect);
+    if (onStop) stopListeners.set(copy, [...(waiting ?? []), onStop]);
+    else if (waiting) stopListeners.set(copy, waiting);
+    const restart = restarts.get(effect);
+    if (restart) {
+        restarts.set(copy, { built: restart.built, rebuild: () => chain(restart.rebuild(), fn, from, onStop) });
+    }
+    return copy;
 };
 
 /**
- * The input each flow `effectPipe` built was called with, keyed on the flow's root, for `interpret` to hand `onRun`.
- * Kept off the flow, so no node or outcome carries it.
+ * Told that the flow stopped at `node`, or at a Failure when `node` is undefined, so a generator flow waiting on it
+ * runs its `catch` and `finally` blocks.
+ * @typedef {(node: Effect | undefined) => void} StopListener
+ */
+
+/**
+ * The generator flows waiting on each node `chain` copied for them, innermost first. `chain` calls one when a Failure
+ * passes the continuation it guards, and `execute`'s `stopAt` calls them all when the node itself stops the flow.
+ * @type {WeakMap<Effect, StopListener[]>}
+ */
+const stopListeners = new WeakMap();
+
+/**
+ * The body run a generator flow made as it was built, which the first execution of the flow takes over if nothing
+ * has used it. `claimed` is shared by every copy of the flow's root, so only one execution takes it over.
+ * @typedef {{ run: BodyRun, position: number, state: BodyRun['state'], claimed: boolean }} BuiltRun
+ */
+
+/**
+ * How to build each generator flow's root again from its input, and the run it was built with. `effectGen` sets one,
+ * `chain` and `copyRoot` keep it on their copies, and `execute`'s `ownRun` builds the flow again for every execution
+ * after the first, so a `Retry` or a reused flow value runs the body afresh, as a retried `async` function does.
+ * @type {WeakMap<Effect, { built: BuiltRun, rebuild: () => Effect }>}
+ */
+const restarts = new WeakMap();
+
+/**
+ * Copies a flow's root, which `flowInputs` is keyed on, keeping the generator flows waiting on it and how to build it
+ * again.
+ * @param {Effect} tree
+ * @returns {Effect}
+ */
+const copyRoot = (tree) => {
+    const root = { ...tree };
+    const waiting = stopListeners.get(tree);
+    if (waiting) stopListeners.set(root, waiting);
+    const restart = restarts.get(tree);
+    if (restart) restarts.set(root, { built: restart.built, rebuild: () => copyRoot(restart.rebuild()) });
+    return root;
+};
+
+/**
+ * The input each flow `effectPipe` or `effectGen` built was called with, keyed on the flow's root, for `interpret` to
+ * hand `onRun` and for `recordEffect` to store in its trace. Kept off the flow, so no node or outcome carries it.
  * @type {WeakMap<Effect, any>}
  */
 const flowInputs = new WeakMap();
@@ -527,19 +589,443 @@ const effectPipe = (...fns) => {
     return (start) => {
         const tree = fns.reduce((eff, fn) => chain(eff, fn), /** @type {Effect} */ (Success(start)));
         // Keyed on a copy, since the last step can return an object other flows share, such as a constant Failure.
-        const root = { ...tree };
+        const root = copyRoot(tree);
         flowInputs.set(root, start);
         return root;
     };
 };
 
+/**
+ * Every marker a step's iterator yielded, so `effectGen` can tell one from a value the body yielded itself.
+ * @type {WeakSet<StepMarker>}
+ */
+const stepMarkers = new WeakSet();
+
+/**
+ * The markers `effectGen` received, so a step's iterator can tell `yield*` from a spread or a `for...of`.
+ * @type {WeakSet<StepMarker>}
+ */
+const claimedMarkers = new WeakSet();
+
+/**
+ * The Effect inside each step wrapper, so `effectGen` can name a step yielded or returned without `yield*`.
+ * @type {WeakMap<object, Effect>}
+ */
+const stepEffects = new WeakMap();
+
+/** @typedef {Readonly<{ effect: Effect }>} StepMarker */
+
+/**
+ * @param {any} value
+ * @returns {boolean}
+ */
+const isThenable = (value) => isObject(value) && typeof value.then === 'function';
+
+/**
+ * Names a step for a message, and for comparing one run of a body with the next.
+ * @param {Effect} effect
+ * @returns {string}
+ */
+const describeStep = (effect) =>
+    effect.type === 'Command'
+        ? `Command '${commandName(effect)}'`
+        : `${effect.type === 'Ask' ? 'an' : 'a'} ${effect.type}`;
+
+/**
+ * Wraps an Effect for `yield*` inside `effectGen`, which gives back the Effect's value. The wrapper is a proxy that throws
+ * when it is used as a value, and its iterator throws unless `effectGen` claimed what it yielded.
+ *
+ * @param {Effect} effect
+ * @returns {any}
+ */
+const step = (effect) => {
+    if (!isEffect(effect)) {
+        throw malformed(
+            isThenable(effect)
+                ? 'step expects an Effect, got a Promise: put the call in a Command, as in ' +
+                      'yield* step(Command(() => db.findUser(email))).'
+                : `step expects an Effect, got ${describeArgument(effect)}.`,
+            effect
+        );
+    }
+    /** @returns {Generator<StepMarker, any, any>} */
+    const iterate = function* () {
+        const marker = Object.freeze({ effect });
+        stepMarkers.add(marker);
+        try {
+            return yield marker;
+        } finally {
+            // Only `effectGen` claims a marker, so an unclaimed one means a spread, `Array.from` or a `for...of`.
+            if (!claimedMarkers.has(marker)) {
+                throw malformed(
+                    `step(${describeStep(effect)}) was iterated outside yield*; write yield* step(...).`,
+                    effect
+                );
+            }
+        }
+    };
+    const refuse = () => {
+        throw malformed(`step(${describeStep(effect)}) was used as a value; write yield* step(...).`, effect);
+    };
+    const inspectCustom = Symbol.for('nodejs.util.inspect.custom');
+    const hint = () => `[step: ${describeStep(effect)}, use with yield*]`;
+    // On the target as well, since Node's inspect reads a proxy's target without running its traps.
+    const target = Object.freeze(Object.defineProperty({}, inspectCustom, { value: hint }));
+    const wrapper = new Proxy(target, {
+        get: (_, key) => (key === Symbol.iterator ? iterate : key === inspectCustom ? hint : refuse()),
+        has: refuse,
+        ownKeys: refuse,
+        getOwnPropertyDescriptor: refuse,
+        set: refuse,
+        defineProperty: refuse,
+        deleteProperty: refuse
+    });
+    stepEffects.set(wrapper, effect);
+    return wrapper;
+};
+
+/** What an `async function*` inherits from, which `effectGen` refuses before it builds anything. */
+const asyncGeneratorFunction = Object.getPrototypeOf(async function* () {});
+
+/**
+ * A generator flow called with its input, which a re-run starts its body from again.
+ * @typedef {{ body: (input: any) => any, input: any }} GenFlow
+ */
+
+/**
+ * One run of a body: its generator, the position of the step it is waiting at, whether it can still resume, and
+ * whether an execution took it over (`takeBuiltRun`), which only ever moves it forward.
+ * @typedef {{ generator: Generator<any, any, any>, position: number, state: 'suspended' | 'done', owned: boolean }} BodyRun
+ */
+
+/**
+ * The answers a body was given before a position, newest first, each with the step it answered, so a re-run can feed
+ * them again and check the body asks for the same steps. Shared between continuations, never copied.
+ * @typedef {{ signature: string, answer: any, earlier: Trail } | null} Trail
+ */
+
+/**
+ * Where a run an execution owns keeps its earlier answers: nowhere, since running it again builds the flow again from
+ * its input, so a long loop holds only the answer it is on. `rerun` refuses a trail that reaches it.
+ * @type {NonNullable<Trail>}
+ */
+const droppedAnswers = Object.freeze({ signature: '', answer: undefined, earlier: null });
+
+/**
+ * @typedef {(generator: Generator<any, any, any>) => IteratorResult<any, any>} Resume
+ */
+
+/**
+ * Starts a body. A function that returns anything but a synchronous generator is refused here, which covers a bundled
+ * `async function*` the prototype check in `effectGen` missed.
+ * @param {GenFlow} flow
+ * @returns {BodyRun}
+ */
+const startRun = (flow) => {
+    const generator = flow.body(flow.input);
+    const isGenerator =
+        isObject(generator) &&
+        ['next', 'throw', 'return'].every((name) => typeof generator[name] === 'function') &&
+        generator[Symbol.toStringTag] !== 'AsyncGenerator';
+    if (!isGenerator) {
+        throw malformed(
+            'effectGen expects a generator function, function* (input) { ... }; ' +
+                `its function returned ${describeValue(generator)}.`,
+            generator
+        );
+    }
+    return { generator, position: 0, state: 'suspended', owned: false };
+};
+
+/**
+ * Adds a hint to V8's error for `yield*` on a value that is not iterable, keeping the original as `cause`.
+ * @param {unknown} e
+ * @returns {unknown}
+ */
+const explainBodyThrow = (e) => {
+    // V8's two wordings; the second is not unique to yield*, so the hint is conditional.
+    const notIterable = [
+        /^yield\* .* is not iterable$/,
+        /^object is not iterable \(cannot read property Symbol\(Symbol\.iterator\)\)$/
+    ];
+    if (!(e instanceof TypeError) || hasMark(e, harnessError) || !notIterable.some((p) => p.test(e.message))) {
+        return e;
+    }
+    const error = malformed(
+        `A generator flow threw "${e.message}". If it came from yield* on an Effect, write yield* step(effect).`,
+        undefined
+    );
+    return Object.defineProperty(error, 'cause', { value: e, writable: true, configurable: true });
+};
+
+/**
+ * @param {BodyRun} run
+ * @param {Resume} resume
+ * @returns {IteratorResult<any, any>}
+ */
+const resumeBody = (run, resume) => {
+    try {
+        const result = resume(run.generator);
+        if (result.done) run.state = 'done';
+        return result;
+    } catch (e) {
+        run.state = 'done';
+        throw explainBodyThrow(e);
+    }
+};
+
+/**
+ * Takes the Effect out of what a body yielded, claiming its marker, or refuses what is not a step.
+ * @param {any} value
+ * @returns {Effect}
+ */
+const claimStep = (value) => {
+    // First, since reading anything from a step wrapper throws.
+    const unstarred = stepEffects.get(value);
+    if (unstarred) {
+        throw malformed(
+            `A generator flow yielded step(${describeStep(unstarred)}) without the star; write yield* step(...).`,
+            undefined
+        );
+    }
+    if (stepMarkers.has(value)) {
+        claimedMarkers.add(value);
+        return value.effect;
+    }
+    if (isEffect(value)) {
+        throw malformed(`A generator flow yielded ${describeArgument(value)}; write yield* step(effect).`, value);
+    }
+    if (isThenable(value)) {
+        throw malformed(
+            'A generator flow yielded a Promise; put the call in a Command and yield* step(command).',
+            value
+        );
+    }
+    throw malformed(`A generator flow yielded ${describeValue(value)}; it can only yield* step(effect).`, value);
+};
+
+/**
+ * What a body's `return` means: an Effect runs as it is, a plain value is a `Success`.
+ * @param {any} value
+ * @returns {Effect}
+ */
+const returnedEffect = (value) => {
+    if (stepEffects.has(value)) {
+        throw malformed(
+            'A generator flow returned step(...); write return yield* step(...), or return the Effect itself.',
+            undefined
+        );
+    }
+    if (isEffect(value)) return value;
+    if (isThenable(value)) {
+        throw malformed(
+            'A generator flow returned a Promise; put the call in a Command and return yield* step(command).',
+            value
+        );
+    }
+    return Success(value);
+};
+
+/**
+ * Runs a body again from the top, feeding it the answers in `trail`, and checks it asks for the same steps. A step it
+ * builds again but does not run, since its answer is known, is stopped as a skipped one is (`stopSkipped`), so a
+ * generator flow inside it that has already entered its `try` runs its `finally`.
+ * @param {GenFlow} flow
+ * @param {Trail} trail
+ * @param {string} signature - The step the body has to be waiting at once the answers are fed
+ * @returns {BodyRun} The new run, waiting at that step
+ */
+const rerun = (flow, trail, signature) => {
+    const run = startRun(flow);
+    /** @returns {Effect} The step the body asked for */
+    const expect = (/** @type {IteratorResult<any, any>} */ result, /** @type {string} */ wanted) => {
+        const effect = result.done ? undefined : claimStep(result.value);
+        const asked = effect && describeStep(effect);
+        if (!effect || asked !== wanted) {
+            const did = asked === undefined ? 'returned' : `asked for ${asked}`;
+            throw malformed(
+                `A generator flow ${did} where its earlier run asked for ${wanted}. Something in its ` +
+                    'body changes between runs, such as Date.now(), Math.random(), or a variable outside the body; ' +
+                    "make it a Command, or pass it in the flow's input.",
+                undefined
+            );
+        }
+        if (effect.type !== 'Success') stopSkipped(effect, Success(undefined), undefined);
+        return effect;
+    };
+    /** @type {{ signature: string, answer: any }[]} */
+    const answers = [];
+    for (let cell = trail; cell; cell = cell.earlier) {
+        if (cell === droppedAnswers) {
+            throw malformed(
+                `A step of a generator flow was answered again after a run had gone past it, at ${signature}, and ` +
+                    'that run keeps no earlier answers to run the body again with. Walk a flow before running it, ' +
+                    'not a step a run handed a hook.',
+                undefined
+            );
+        }
+        answers.unshift(cell);
+    }
+    let result = resumeBody(run, (g) => g.next());
+    for (const { signature: asked, answer } of answers) {
+        const effect = expect(result, asked);
+        run.position++;
+        // A pure step's value is the one this run just computed, never an object the earlier run went on to change.
+        const value = effect.type === 'Success' ? effect.value : answer;
+        result = resumeBody(run, (g) => g.next(value));
+    }
+    expect(result, signature);
+    return run;
+};
+
+/**
+ * The run waiting at `position`: the live one if it is there, else a new one the earlier answers bring there, as
+ * when a test walks a second branch.
+ * @param {GenFlow} flow
+ * @param {BodyRun} run
+ * @param {number} position
+ * @param {Trail} trail
+ * @param {string} signature
+ * @returns {BodyRun}
+ */
+const runAt = (flow, run, position, trail, signature) =>
+    run.state === 'suspended' && run.position === position ? run : rerun(flow, trail, signature);
+
+/**
+ * Resumes a body and turns what it does next into an Effect: the step it yields, chained back into the body, or what
+ * it returns.
+ * @param {GenFlow} flow
+ * @param {BodyRun} run
+ * @param {Trail} trail - The answers before the position the body resumes at
+ * @param {Resume} resume
+ * @returns {Effect}
+ */
+const advance = (flow, run, trail, resume) => {
+    for (;;) {
+        const result = resumeBody(run, resume);
+        if (result.done) return returnedEffect(result.value);
+        const effect = claimStep(result.value);
+        const position = run.position;
+        const signature = describeStep(effect);
+        const before = trail;
+        if (effect.type === 'Success') {
+            // Fed straight back rather than through `chain`, so a long run of pure steps does not grow the stack.
+            trail = { signature, answer: effect.value, earlier: before };
+            run.position = position + 1;
+            resume = (g) => g.next(effect.value);
+            continue;
+        }
+        return chain(
+            effect,
+            (answer) => continueBody(flow, run, position, before, signature, answer),
+            undefined,
+            (node) => stopBody(flow, run, position, before, signature, node)
+        );
+    }
+};
+
+/**
+ * Hands a step's answer to the body waiting at it.
+ * @param {GenFlow} flow
+ * @param {BodyRun} run
+ * @param {number} position
+ * @param {Trail} trail
+ * @param {string} signature
+ * @param {any} answer
+ * @returns {Effect}
+ */
+const continueBody = (flow, run, position, trail, signature, answer) => {
+    const current = runAt(flow, run, position, trail, signature);
+    current.position = position + 1;
+    const after = current.owned ? droppedAnswers : { signature, answer, earlier: trail };
+    return advance(flow, current, after, (g) => g.next(answer));
+};
+
+/**
+ * Throws a stop into the body waiting at a step that stopped the flow, so its `catch` and `finally` blocks run. Only
+ * the stop coming back out is accepted: a body that swallows it, throws something else, or yields while stopping
+ * rejects the run.
+ * @param {GenFlow} flow
+ * @param {BodyRun} run
+ * @param {number} position
+ * @param {Trail} trail
+ * @param {string} signature
+ * @param {Effect | undefined} node - The node that stopped the flow; undefined for a Failure
+ */
+const stopBody = (flow, run, position, trail, signature, node) => {
+    const current = runAt(flow, run, position, trail, signature);
+    current.state = 'done';
+    const where = node && isPending(node) ? describeStep(node) : 'a Failure';
+    const advice = "return the error as data inside the Command's function, or use Retry's onExhausted.";
+    // Carries neither the error nor what kind of stop it was, so user code cannot branch on either.
+    const stop = Object.assign(
+        new Error(`The flow stopped ${node ? 'after' : 'at'} ${where}. Nothing can be caught here: ${advice}`),
+        {
+            name: 'FlowStopped'
+        }
+    );
+    try {
+        current.generator.throw(stop);
+    } catch (e) {
+        if (e === stop) return;
+        if (hasMark(e, harnessError)) throw e;
+        const error = malformed(
+            `A catch in a generator flow threw another error after ${where} stopped it; a catch around yield* ` +
+                'cannot recover, so let the stop pass.',
+            undefined
+        );
+        throw Object.defineProperty(error, 'cause', { value: e, writable: true, configurable: true });
+    }
+    throw malformed(
+        `A generator flow kept going after ${where} stopped it: a catch swallowed the stop, or a finally ran a ` +
+            `step. Nothing can be caught here: ${advice}`,
+        undefined
+    );
+};
+
+/**
+ * Builds a flow function from a generator function, which writes `yield* step(effect)` where `async` code writes
+ * `await`. Calling the flow function runs the body up to its first step, and the flow it returns is made of ordinary
+ * nodes, so it records, replays and tests as a pipeline does. The first execution of the flow takes over that run of
+ * the body, and every later one builds the flow again from its input, as calling an `async` function again does.
+ *
+ * @param {(input: any) => Generator<any, any, any>} body
+ * @returns {(input: any) => Effect}
+ */
+const effectGen = (body) => {
+    if (typeof body !== 'function') {
+        throw malformed(
+            `effectGen expects a generator function, function* (input) { ... }, got ${describeArgument(body)}.`,
+            body
+        );
+    }
+    if (Object.getPrototypeOf(body) === asyncGeneratorFunction) {
+        throw malformed(
+            'effectGen expects function*, not async function*: get each result with yield* step(command) instead of await.',
+            body
+        );
+    }
+    /** @param {any} input */
+    const build = (input) => {
+        const flow = { body, input };
+        const run = startRun(flow);
+        // Keyed on a copy, as `effectPipe`'s root is, since a body can return a shared object.
+        const root = copyRoot(advance(flow, run, null, (g) => g.next()));
+        flowInputs.set(root, input);
+        const built = { run, position: run.position, state: run.state, claimed: false };
+        restarts.set(root, { built, rebuild: () => build(input) });
+        return root;
+    };
+    return build;
+};
+
 // #endregion
 // #region Configuration
 
 /**
  * Wraps one Command, or one Parallel, whose `op` runs the branches and returns the decision, so a hook must call it.
  * Only a replay passes `op` an argument, the recorded decision. `path` is the step's position in the Effect tree.
- * @typedef {(name: string, type: string, op: function, path?: string) => Promise<any>} StepRunner
+ * @typedef {(name: string, type: 'Command' | 'Parallel', op: function, path?: string) => Promise<any>} StepRunner
  */
 /** @type StepRunner */
 const defaultStepRunner = async (name, type, op) => await op();
@@ -708,8 +1194,10 @@ const cancelledBranch = () =>
 /**
  * Which branch, if any, cancelled a Parallel, and how many branches it had; `branch: null` means an enclosing Parallel
  * did. Timing decides it, so it is recorded as the Parallel's own step for a replay to hand back, and the count lets a
- * replay see a branch added or removed.
- * @typedef {{ cancelled: false, branches: number } | { cancelled: true, branch: number | null, branches: number }} ParallelDecision
+ * replay see a branch added or removed. `threw` says a branch threw, which marked the scope, so a replay stops no
+ * generator flow there, as production did not once the throw came.
+ * @typedef {{ cancelled: false, branches: number }
+ *   | { cancelled: true, branch: number | null, branches: number, threw?: true }} ParallelDecision
  */
 
 /**
@@ -747,8 +1235,10 @@ const asDecision = (value, branches) => {
     if (value.cancelled === false) return { cancelled: false, branches };
     if (value.cancelled !== true) return undefined;
     const { branch } = value;
-    if (branch === null) return { cancelled: true, branch: null, branches };
-    return isBranchIndex(branch, branches) ? { cancelled: true, branch, branches } : undefined;
+    if (branch !== null && !isBranchIndex(branch, branches)) return undefined;
+    return value.threw === true
+        ? { cancelled: true, branch, branches, threw: true }
+        : { cancelled: true, branch, branches };
 };
 
 /**
@@ -768,6 +1258,13 @@ const replayCutError = (path) =>
         { value: true }
     );
 
+/**
+ * Cancellation scopes a branch's throw aborted, and the scopes linked under them. `stopAt` stops no generator flow
+ * under one, since the throw rejects the run.
+ * @type {WeakSet<AbortSignal>}
+ */
+const thrownScopes = new WeakSet();
+
 /**
  * A cancellation scope for one Parallel, linked to the enclosing one so cancellation nests.
  * @param {AbortSignal} [signal] - The enclosing Parallel's signal, if any
@@ -775,9 +1272,13 @@ const replayCutError = (path) =>
  */
 const linkedScope = (signal) => {
     const scope = new AbortController();
-    const relay = () => scope.abort();
+    if (signal && thrownScopes.has(signal)) thrownScopes.add(scope.signal);
+    const relay = () => {
+        if (signal && thrownScopes.has(signal)) thrownScopes.add(scope.signal);
+        scope.abort();
+    };
     if (signal) {
-        if (signal.aborted) scope.abort();
+        if (signal.aborted) relay();
         else signal.addEventListener('abort', relay, { once: true });
     }
     const unlink = () => {
@@ -882,6 +1383,64 @@ const interpret = async (effect, context = {}, callConfig = {}, fastRetry = fals
     return onRun(effect, op, context?.flowName || '', flowInputs.get(effect));
 };
 
+/**
+ * Tells the generator flows waiting on `node` that it stopped the flow, innermost first. The other end of the
+ * protocol is `chain`, which keeps the listeners on each node it copies. Returns `result`, for a `return` to pass on.
+ * Under a scope a throw cancelled it tells none, since the run is about to reject and a `catch` could hide why.
+ *
+ * @param {Effect} node
+ * @param {SuccessState | FailureState | IoFaultState} result
+ * @param {AbortSignal | undefined} signal
+ * @returns {SuccessState | FailureState | IoFaultState}
+ */
+const stopAt = (node, result, signal) => {
+    if (signal && thrownScopes.has(signal)) return result;
+    stopListeners.get(node)?.forEach((listener) => listener(node));
+    return result;
+};
+
+/**
+ * `stopAt` for a node a cancellation skipped, which also tells the generator flows built inside a skipped `Retry` or
+ * `Parallel`, innermost first, since each body ran up to its first step as it was built.
+ *
+ * @param {Effect} node
+ * @param {SuccessState | FailureState | IoFaultState} result
+ * @param {AbortSignal | undefined} signal
+ * @returns {SuccessState | FailureState | IoFaultState}
+ */
+const stopSkipped = (node, result, signal) => {
+    // A generator flow another execution took over, or a test walked, is not this one's to stop.
+    const restart = restarts.get(node);
+    if (restart && !takeBuiltRun(restart.built)) return result;
+    if (node.type === 'Retry') stopSkipped(node.effect, result, signal);
+    if (node.type === 'Parallel') node.effects.forEach((branch) => stopSkipped(branch, result, signal));
+    return stopAt(node, result, signal);
+};
+
+/**
+ * Takes over the run a generator flow made as it was built, if nothing has: no execution took it over, and no test
+ * walked it on from where it was built.
+ * @param {BuiltRun} built
+ * @returns {boolean} Whether the run was free
+ */
+const takeBuiltRun = (built) => {
+    const free = !built.claimed && built.run.position === built.position && built.run.state === built.state;
+    built.claimed = true;
+    if (free) built.run.owned = true;
+    return free;
+};
+
+/**
+ * The node to run in place of `eff`: `eff` itself, unless it is a generator flow's root whose built run is taken, when
+ * it is the flow built again from its input. The other end is `restarts`, which `effectGen` fills.
+ * @param {Effect} eff
+ * @returns {Effect}
+ */
+const ownRun = (eff) => {
+    const restart = restarts.get(eff);
+    return restart && !takeBuiltRun(restart.built) ? restart.rebuild() : eff;
+};
+
 /**
  * Walks a subtree until it reaches a Success, a Failure or an I/O fault. Every node but `Ask` runs in its
  * own function, which returns a Success carrying the value for the node's `next`, or what stops the subtree.
@@ -899,7 +1458,12 @@ const execute = async (runtime, eff, signal, path = '') => {
     let from;
     while (isPending(eff)) {
         // A Command already in flight cannot be stopped, but the next one never starts.
-        if (signal?.aborted) return cancelledBranch();
+        if (signal?.aborted) return stopSkipped(eff, cancelledBranch(), signal);
+        const own = ownRun(eff);
+        if (own !== eff) {
+            eff = own;
+            continue;
+        }
         if (eff.type === 'Ask') {
             from = eff;
             eff = eff.next(runtime.context);
@@ -912,7 +1476,7 @@ const execute = async (runtime, eff, signal, path = '') => {
                 : eff.type === 'Parallel'
                   ? await runParallel(runtime, eff, signal, stepPath)
                   : await runCommand(runtime, eff, signal, stepPath);
-        if (outcome.type !== 'Success') return outcome;
+        if (outcome.type !== 'Success') return stopAt(eff, outcome, signal);
         // Outside every catch: `next` and the pure steps it reaches are code, not I/O, so a throw there
         // rejects the run.
         from = eff;
@@ -938,9 +1502,9 @@ const runRetry = async (runtime, retry, signal, stepPath) => {
         ...defaultRetryOptions,
         ...Object.fromEntries(given)
     });
-    const { attempts, onExhausted } = opts;
+    const { retries, onExhausted } = opts;
     let lastError;
-    for (let attempt = 0; attempt <= attempts; attempt++) {
+    for (let attempt = 0; attempt <= retries; attempt++) {
         // `fastRetry` waits for no time rather than skipping the wait, so branches replayed by timing still
         // interleave.
         if (attempt > 0) {
@@ -953,7 +1517,7 @@ const runRetry = async (runtime, retry, signal, stepPath) => {
         if (result.type !== 'IoFault') return result;
         lastError = result.error;
     }
-    const exhausted = { retryExhausted: true, lastError, attempts };
+    const exhausted = { retryExhausted: true, lastError, retries };
     // A fault too, so an enclosing Retry retries this one.
     if (typeof onExhausted !== 'function') return IoFault(exhausted);
     if (signal?.aborted) return cancelledBranch();
@@ -985,8 +1549,12 @@ const runParallel = async (runtime, parallel, signal, stepPath) => {
     try {
         await runtime.onStep('Parallel', 'Parallel', op, branchPath);
     } catch (e) {
-        // A cut from `fromTrace`: production had already stopped the branch this Parallel is in.
-        if (hasMark(e, replayCut)) return cancelledBranch();
+        // A cut from `fromTrace`: production had already stopped the branch this Parallel is in, so it skipped this
+        // Parallel, and `stopSkipped` tells the flows built in its branches, as production's cancellation did.
+        if (hasMark(e, replayCut)) {
+            parallel.effects.forEach((branch) => stopSkipped(branch, cancelledBranch(), signal));
+            return cancelledBranch();
+        }
         throw e;
     }
     if (!branchRun) {
@@ -1057,7 +1625,8 @@ const runBranches = async (runtime, effects, options, signal, branchPath, record
         limit,
         signal,
         branchPath,
-        reproducing ? () => false : (threw, result) => threw || (!settled && result.type !== 'Success')
+        reproducing ? () => false : (threw, result) => threw || (!settled && result.type !== 'Success'),
+        reproducing && forced.threw === true
     );
     if (reproducing) {
         // A branch that threw has no result to check, and its throw is what is rethrown.
@@ -1079,6 +1648,8 @@ const runBranches = async (runtime, effects, options, signal, branchPath, record
             : cancelled
               ? { cancelled: true, branch: null, branches }
               : { cancelled: false, branches };
+    // A throw from any branch marked the scope, whichever branch cancelled the others first.
+    if (thrown !== undefined && decision.cancelled) decision.threw = true;
     return { results, decision, thrown };
 };
 
@@ -1093,6 +1664,7 @@ const runBranches = async (runtime, effects, options, signal, branchPath, record
  * @param {AbortSignal | undefined} signal
  * @param {string} branchPath
  * @param {(threw: boolean, result: SuccessState | FailureState | IoFaultState) => boolean} cancelsOthers
+ * @param {boolean} [recordedThrow] - A replay's recorded decision says a branch threw, so no generator flow stops
  * @returns {Promise<{
  *   results: (SuccessState | FailureState | IoFaultState)[],
  *   thrown: { error: unknown } | undefined,
@@ -1100,8 +1672,9 @@ const runBranches = async (runtime, effects, options, signal, branchPath, record
  *   cancelled: boolean
  * }>}
  */
-const settleBranches = async (runtime, effects, limit, signal, branchPath, cancelsOthers) => {
+const settleBranches = async (runtime, effects, limit, signal, branchPath, cancelsOthers, recordedThrow = false) => {
     const { scope, unlink } = linkedScope(signal);
+    if (recordedThrow) thrownScopes.add(scope.signal);
     /** @type {(SuccessState | FailureState | IoFaultState)[]} */
     const results = new Array(effects.length);
     // Held rather than rethrown, so every branch still settles and no `limit` worker stops early.
@@ -1118,6 +1691,7 @@ const settleBranches = async (runtime, effects, limit, signal, branchPath, cance
         // Read-then-abort is atomic here, so exactly one branch is the trigger.
         if (cancelsOthers(thrown[i] !== undefined, results[i])) {
             if (!scope.signal.aborted) triggered[i] = true;
+            if (thrown[i] !== undefined) thrownScopes.add(scope.signal);
             scope.abort();
         }
     };
@@ -1253,7 +1827,7 @@ const runEffect = (effect, context, callConfig) => interpret(effect, context, ca
  * position in completion order, which is not stable for a flow with a `Parallel`. A step whose `type` is 'Parallel'
  * asks for the recorded decision and does not advance `index`; an answer that holds no decision replays that
  * Parallel by timing.
- * @typedef {{ index: number, name: string, type: string, path?: string }} ReplayStep
+ * @typedef {{ index: number, name: string, type: 'Command' | 'Parallel', path?: string }} ReplayStep
  */
 
 /**
@@ -1628,24 +2202,26 @@ const packTrace = (settings, meta, entries, dropped) => {
 };
 
 /**
- * Runs a flow for real while recording it, and returns the outcome and a replayable trace. Convenient in tests and
- * scripts; to record an application, give each run its own recorder, as examples/recording-example.js does.
+ * Runs a flow for real while recording it, and returns the outcome and a replayable trace. The trace holds the input
+ * of a flow `effectPipe` or `effectGen` built, read from `flowInputs`. Convenient in tests and scripts; to record an
+ * application, give each run its own recorder, as examples/recording-example.js does.
  *
- * @param {(input: any) => Effect} flowFn - Builds the Effect tree from its input
- * @param {any} initialInput - The value the flow is called with; stored so a replay can rebuild it
+ * @param {Effect} effect - The flow, called with its input
  * @param {RecorderOptions & { context?: any, version?: string }} [options] - Recorder options, plus the
  *        `context` given to `runEffect` (stored so `Ask` can be replayed) and a build id
  * @returns {Promise<{ result: SuccessState | FailureState, trace: TraceLog }>}
  */
-const recordEffect = async (flowFn, initialInput, options = {}) => {
+const recordEffect = async (effect, options = {}) => {
+    // Before the options, so a call written the old way, with the flow function and its input, is named as that.
+    asEffect(effect, 'The flow');
     checkOptions(options, 'recordEffect', { context: null, version: null, ...recorderOptionRules });
-    checkFlowFn(flowFn, 'recordEffect');
     const { context = {}, version, ...recorderOptions } = options ?? {};
     const rec = recorder(recorderOptions);
     // Before the run, so a Command that writes to the input or the context cannot rewrite what the trace received.
+    const initialInput = flowInputs.get(effect);
     const head = rec.toTrace({ initialInput, flowName: context?.flowName, context, version });
     // Merged over the global wiring, so recording inside an instrumented application keeps its spans.
-    const result = await runEffect(flowFn(initialInput), context, { onStep: rec.onStep });
+    const result = await runEffect(effect, context, { onStep: rec.onStep });
     const { dropped, trace } = rec.toTrace();
     return { result, trace: { ...head, dropped, trace } };
 };
@@ -2224,8 +2800,7 @@ const replayHook = ({ resolve, missing, onResolved, onMissing, droppedEntries })
  * @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>} The flow's outcome. For the unreached entries as data, use
- *          `replayEffect`.
+ * @returns {Promise<Replay>} `{ result, unreached }`, as `replayEffect` returns for a trace
  */
 const timeTravel = async (flowFn, traceLog, options = {}) => {
     checkOptions(options, 'timeTravel', { log: [isFunction, 'a function'], context: null, version: null });
@@ -2262,7 +2837,7 @@ const timeTravel = async (flowFn, traceLog, options = {}) => {
     log(result.type === 'Failure' ? `Error: ${formatForLog(result.error)}` : `Result: ${formatForLog(result.value)}`);
     const warning = unreachedWarning(result, unreached);
     if (warning !== undefined) log(warning);
-    return result;
+    return { result, unreached };
 };
 
 /**
@@ -2280,8 +2855,8 @@ const traceWarnings = (traceLog, trace, version) => {
     }
     if (traceLog.initialInput === undefined) {
         warnings.push(
-            'Warning: the trace holds no initial input, so the flow is rebuilt from undefined. A recorder ' +
-                'installed as a hook finds the input only on a flow built with effectPipe.'
+            'Warning: the trace holds no initial input, so the flow is rebuilt from undefined. A trace holds ' +
+                'the input only of a flow built with effectPipe or effectGen.'
         );
     }
     const anonymous = trace.filter((e) => e.command === 'anonymous').length;
@@ -2353,5 +2928,7 @@ export {
     recordEffect,
     replayEffect,
     timeTravel,
-    commandName
+    commandName,
+    effectGen,
+    step
 };