jev-devtools 0.3.0 → 0.4.1

package/lib/flow/index.js

@@ -1,5 +1,7 @@
 import { randomUUID } from "node:crypto";
+import { jsonSnapshot, runCallback } from "./runtime.js";
 const owners = new WeakMap();
+const builderIds = new WeakMap();
 function freezeAst(ast, depth = 0) {
     if (depth > 80)
         throw new Error("Expression nesting exceeds 80");
@@ -35,6 +37,9 @@ export class FlowExpression {
     lt(value) {
         return operation("lt", [this, value]);
     }
+    gt(value) {
+        return operation("gt", [this, value]);
+    }
     gte(value) {
         return operation("gte", [this, value]);
     }
@@ -57,6 +62,23 @@ function operation(op, args) {
 export const all = (...conditions) => operation("all", conditions);
 export const any = (...conditions) => operation("any", conditions);
 export const not = (condition) => operation("not", [condition]);
+// Nested programs share a reservation budget without exposing execution internals in the API.
+const executionBudgets = new WeakMap();
+function withBudget(options, budget) {
+    executionBudgets.set(options, budget);
+    return options;
+}
+function definitionSize(definition) {
+    return definition.nodes.reduce((count, node) => count +
+        1 +
+        (node.itemDefinition ? definitionSize(node.itemDefinition) : 0), 0);
+}
+export class FlowLoopLimitError extends Error {
+    name = "FlowLoopLimitError";
+    constructor() {
+        super("Loop condition is still true at maxIterations");
+    }
+}
 const plain = (v) => !!v &&
     typeof v === "object" &&
     (Object.getPrototypeOf(v) === Object.prototype ||
@@ -101,7 +123,7 @@ function describe(ast) {
         return "[literal]";
     return `${ast.op}(${ast.args.map(describe).join(", ")})`;
 }
-function conditionRule(ast, requests) {
+function conditionRule(ast, requests, tasks) {
     let remaining = 128;
     const visit = (node) => {
         if (--remaining < 0)
@@ -139,10 +161,12 @@ function conditionRule(ast, requests) {
                     ? path.length === 3 && ["noul", "choice", "score"].includes(path[2])
                         ? path[1]
                         : path.slice(1).join(" ")
-                    : (path.at(-1) ?? "Input"),
+                    : path.at(-1) ?? "Input",
                 ...(base.op === "ref" && requests.has(base.id)
                     ? { stepId: base.id, path }
-                    : {}),
+                    : base.op === "ref" && tasks.has(base.id)
+                        ? { stepId: base.id, path, source: "task" }
+                        : {}),
             };
         }
         if (node.op === "literal")
@@ -211,14 +235,15 @@ function evaluate(ast, input, values) {
         !Number.isFinite(a) ||
         !Number.isFinite(b))
         throw new Error("Numeric comparison requires finite numbers");
-    return ast.op === "lt" ? a < b : a >= b;
+    return ast.op === "lt" ? a < b : ast.op === "gt" ? a > b : a >= b;
 }
 export function defineJevFlow(name, build) {
     const owner = {}, ids = new Set(), nodes = [];
     const input = new FlowExpression({ op: "input" }, owner);
     let building = true;
+    let templateSteps = 0;
     let activeBlock;
-    function block(callback, available, path, previous = [], depth = 0, requireOutcome = false) {
+    function block(callback, available, path, previous = [], depth = 0, requireOutcome = false, requireValue = false) {
         if (depth > 16)
             throw new Error("Flow nesting exceeds 16");
         const token = {};
@@ -242,7 +267,7 @@ export function defineJevFlow(name, build) {
                 throw new Error("No steps allowed after a terminal output or branch");
             if (!/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,79}$/.test(id) || ids.has(id))
                 throw new Error(`Invalid or duplicate step ID: ${id}`);
-            if (ids.size >= 256)
+            if (ids.size + templateSteps >= 256)
                 throw new Error("Flows support at most 256 steps");
             const copy = {};
             if (display !== undefined) {
@@ -283,21 +308,45 @@ export function defineJevFlow(name, build) {
         const builder = {
             input,
             jev(id, request, display) {
-                const frozen = mapValue(request, (expr) => expr);
+                const dynamic = "request" in request;
+                if (dynamic && typeof request.request !== "function")
+                    throw new Error("Request factory must be a function");
+                const frozen = mapValue(dynamic ? request.input : request, (expr) => expr);
                 const step = add(id, "jev", frozen, display);
-                step.request = frozen;
+                if (dynamic) {
+                    step.input = frozen;
+                    step.factory = request.request;
+                    step.answerNames = new Set();
+                }
+                else
+                    step.request = frozen;
                 return {
+                    answers: new FlowExpression({ op: "get", from: { op: "ref", id }, key: "answers" }, owner),
                     answer(question) {
-                        if (!Object.hasOwn(frozen.questions, question))
+                        if (!dynamic && !Object.hasOwn(step.request.questions, question))
                             throw new Error(`Unknown question: ${question}`);
-                        const type = frozen.questions[question].type;
-                        const fields = type === "noul"
-                            ? ["type", "noul"]
-                            : type === "choice"
-                                ? ["type", "choice", "confidence", "probabilities"]
-                                : type === "score"
-                                    ? ["type", "score", "confidence", "probabilities", "legend"]
-                                    : ["type", "box", "confidence"];
+                        step.answerNames?.add(question);
+                        const type = dynamic
+                            ? undefined
+                            : step.request.questions[question].type;
+                        const fields = dynamic
+                            ? [
+                                "type",
+                                "noul",
+                                "choice",
+                                "score",
+                                "confidence",
+                                "probabilities",
+                                "legend",
+                                "box",
+                            ]
+                            : type === "noul"
+                                ? ["type", "noul"]
+                                : type === "choice"
+                                    ? ["type", "choice", "confidence", "probabilities"]
+                                    : type === "score"
+                                        ? ["type", "score", "confidence", "probabilities", "legend"]
+                                        : ["type", "box", "confidence"];
                         return Object.fromEntries(fields.map((field) => [
                             field,
                             new FlowExpression({
@@ -317,6 +366,157 @@ export function defineJevFlow(name, build) {
                     },
                 };
             },
+            task(id, task, display) {
+                if (typeof task.run !== "function")
+                    throw new Error("Task run must be a function");
+                if (task.timeoutMs !== undefined &&
+                    (!Number.isInteger(task.timeoutMs) ||
+                        task.timeoutMs < 1 ||
+                        task.timeoutMs > 2_147_483_647))
+                    throw new Error("Task timeoutMs must be a positive 32-bit integer");
+                const frozen = mapValue(task.input, (expr) => expr);
+                const step = add(id, "task", frozen, display);
+                step.input = frozen;
+                step.task = task.run;
+                step.timeoutMs = task.timeoutMs;
+                return new FlowExpression({ op: "ref", id }, owner);
+            },
+            map(id, config, buildItem, display) {
+                const concurrency = config.concurrency ?? 4;
+                if (!Number.isInteger(concurrency) ||
+                    concurrency < 1 ||
+                    concurrency > 16)
+                    throw new Error("Map concurrency must be an integer from 1 to 16");
+                if (!Number.isInteger(config.maxItems) ||
+                    config.maxItems < 1 ||
+                    config.maxItems > 64)
+                    throw new Error("Map maxItems must be an integer from 1 to 64");
+                const frozen = mapValue({ items: config.items, context: config.input }, (e) => e);
+                const step = add(id, "map", frozen, display);
+                const parentScope = activeBlock;
+                activeBlock = undefined;
+                let program;
+                try {
+                    program = defineJevFlow(`Item · ${display?.title ?? id}`.slice(0, 100), (item) => {
+                        const result = buildItem(item);
+                        let outputId = "item-result";
+                        for (let suffix = 1; builderIds.get(item).has(outputId); suffix++)
+                            outputId = `item-result-${suffix}`;
+                        return item.output(outputId, result, {
+                            title: "Item result",
+                        });
+                    });
+                }
+                finally {
+                    activeBlock = parentScope;
+                }
+                if (program.definition.nodes.some((n) => n.kind === "map"))
+                    throw new Error("Nested maps are not supported");
+                if (program.definition.nodes.some((n) => n.kind === "loop"))
+                    throw new Error("Loops inside maps are not supported");
+                templateSteps += definitionSize(program.definition);
+                if (ids.size + templateSteps > 256)
+                    throw new Error("Flows support at most 256 steps including map templates");
+                step.collection = {
+                    ...frozen,
+                    concurrency,
+                    maxItems: config.maxItems,
+                    program: program,
+                };
+                nodes.find((node) => node.id === id).itemDefinition =
+                    program.definition;
+                return new FlowExpression({ op: "ref", id }, owner);
+            },
+            loop(id, config, buildIteration, display) {
+                if (!Number.isInteger(config.maxIterations) ||
+                    config.maxIterations < 1 ||
+                    config.maxIterations > 64)
+                    throw new Error("Loop maxIterations must be an integer from 1 to 64");
+                const gateOwner = {};
+                const when = config.while(new FlowExpression({ op: "input" }, gateOwner));
+                if (!(when instanceof FlowExpression) || owners.get(when) !== gateOwner)
+                    throw new Error("Loop while must be an expression of its state");
+                inspectAst(when.ast, () => {
+                    throw new Error("Loop while cannot reference outer steps");
+                });
+                const frozen = mapValue({ initial: config.initial, context: config.input }, (e) => e);
+                const step = add(id, "loop", frozen, display);
+                const parentScope = activeBlock;
+                activeBlock = undefined;
+                let program;
+                try {
+                    program = defineJevFlow(`Iteration · ${display?.title ?? id}`.slice(0, 100), (iteration) => {
+                        const result = buildIteration(iteration);
+                        let outputId = "iteration-result";
+                        for (let suffix = 1; builderIds.get(iteration).has(outputId); suffix++)
+                            outputId = `iteration-result-${suffix}`;
+                        return iteration.output(outputId, result, {
+                            title: "Next iteration state",
+                        });
+                    });
+                }
+                finally {
+                    activeBlock = parentScope;
+                }
+                if (program.definition.nodes.some((n) => n.kind === "loop"))
+                    throw new Error("Nested loops are not supported");
+                templateSteps += definitionSize(program.definition);
+                if (ids.size + templateSteps > 256)
+                    throw new Error("Flows support at most 256 steps including iteration templates");
+                step.loop = {
+                    ...frozen,
+                    when,
+                    maxIterations: config.maxIterations,
+                    program,
+                };
+                const node = nodes.find((n) => n.id === id);
+                node.itemDefinition = program.definition;
+                // Point displayed gate inputs at the loop's captured latest state.
+                // Execution still evaluates the original isolated state expression.
+                const referenceState = (ast) => {
+                    if (ast.op === "input")
+                        return { op: "ref", id };
+                    if (ast.op === "get")
+                        return { ...ast, from: referenceState(ast.from) };
+                    if ("args" in ast)
+                        return { ...ast, args: ast.args.map(referenceState) };
+                    return ast;
+                };
+                node.conditionRule = conditionRule(referenceState(when.ast), new Set(), new Set([id]));
+                return new FlowExpression({ op: "ref", id }, owner);
+            },
+            if(id, paths, display) {
+                if (!(paths.when instanceof FlowExpression))
+                    throw new Error("if requires a condition expression");
+                const step = add(id, "if", paths.when, display);
+                step.when = paths.when;
+                const node = nodes.find((n) => n.id === id);
+                node.condition = describe(paths.when.ast);
+                node.conditionRule = conditionRule(paths.when.ast, new Set(nodes.filter((n) => n.kind === "jev").map((n) => n.id)), new Set(nodes
+                    .filter((n) => n.kind === "task" || n.kind === "merge" || n.kind === "loop")
+                    .map((n) => n.id)));
+                step.then = block(paths.then, new Set(available), [...path, `${id}:then`], [id], depth + 1, false, true);
+                step.else = block(paths.else, new Set(available), [...path, `${id}:else`], [id], depth + 1, false, true);
+                // A separate merge keeps the diagram acyclic and gives downstream refs a
+                // scope-safe identity, including when an arm returns an existing value.
+                const base = `${id.slice(0, 65)}-result`;
+                let mergeId = base;
+                for (let suffix = 2; ids.has(mergeId); suffix++)
+                    mergeId = `${base}-${suffix}`;
+                const merge = add(mergeId, "merge", undefined, {
+                    title: "Selected result",
+                    description: "Continue with the value returned by the selected path.",
+                });
+                merge.mergeOf = id;
+                const mergeNode = nodes.find((n) => n.id === mergeId);
+                const ends = {
+                    then: step.then.nodes.at(-1)?.id ?? id,
+                    else: step.else.nodes.at(-1)?.id ?? id,
+                };
+                mergeNode.dependencies = [...new Set(Object.values(ends))];
+                mergeNode.merge = { condition: id, ...ends };
+                return new FlowExpression({ op: "ref", id: mergeId }, owner);
+            },
             branch(id, paths, display) {
                 const step = add(id, "branch", paths.when, display);
                 step.when = paths.when;
@@ -324,7 +524,9 @@ export function defineJevFlow(name, build) {
                     throw new Error("branch requires a condition expression");
                 const node = nodes.find((n) => n.id === id);
                 node.condition = describe(paths.when.ast);
-                node.conditionRule = conditionRule(paths.when.ast, new Set(nodes.filter((n) => n.kind === "jev").map((n) => n.id)));
+                node.conditionRule = conditionRule(paths.when.ast, new Set(nodes.filter((n) => n.kind === "jev").map((n) => n.id)), new Set(nodes
+                    .filter((n) => n.kind === "task" || n.kind === "merge" || n.kind === "loop")
+                    .map((n) => n.id)));
                 step.then = block(paths.then, new Set(available), [...path, `${id}:then`], [id], depth + 1, true);
                 step.else = block(paths.else, new Set(available), [...path, `${id}:else`], [id], depth + 1, true);
                 terminal = true;
@@ -358,6 +560,7 @@ export function defineJevFlow(name, build) {
                 return new FlowExpression({ op: "ref", id: outcome }, owner);
             },
         };
+        builderIds.set(builder, ids);
         const parentBlock = activeBlock;
         activeBlock = token;
         let returned;
@@ -369,6 +572,8 @@ export function defineJevFlow(name, build) {
         }
         if (!(returned instanceof FlowExpression))
             throw new Error("Flow callbacks must return an expression, output, or branch");
+        if (requireValue && terminal)
+            throw new Error("if paths must return a value, not a terminal output or branch");
         if (requireOutcome && !terminal)
             throw new Error("Branch paths must end with output or branch");
         if (terminal &&
@@ -409,6 +614,7 @@ export function defineJevFlow(name, build) {
         if (node.lanes)
             Object.freeze(node.lanes);
         freezeRule(node.conditionRule);
+        freezeRule(node.itemDefinition);
         Object.freeze(node);
     }
     Object.freeze(definitionView.nodes);
@@ -417,6 +623,14 @@ export function defineJevFlow(name, build) {
         definition: definitionView,
         async run(data, options) {
             const controller = new AbortController();
+            // Preserve the initiating failure before aborting siblings: their cancellation
+            // can reach a surrounding parallel join before the failing map settles.
+            let siblingFailure;
+            const stopSiblings = (error) => {
+                if (!controller.signal.aborted)
+                    siblingFailure = { error };
+                controller.abort(error);
+            };
             const cancel = () => controller.abort(options.signal?.reason);
             if (options.signal?.aborted)
                 cancel();
@@ -435,6 +649,12 @@ export function defineJevFlow(name, build) {
                 ])),
             };
             const started = performance.now(), values = new Map();
+            const budget = executionBudgets.get(options) ?? { used: nodes.length };
+            const reserve = (count) => {
+                if (budget.used + count > 1024)
+                    throw new RangeError("Flow exceeds 1024 expanded steps");
+                budget.used += count;
+            };
             let observer;
             try {
                 observer = options.devtools?.startFlow(structuredClone(definition), structuredClone(run));
@@ -445,9 +665,12 @@ export function defineJevFlow(name, build) {
             const emit = () => {
                 try {
                     if (observer) {
-                        const { value, ...metadata } = run;
+                        const { value, steps, ...metadata } = run;
+                        // Stable data snapshots are captured once by the recorder, not
+                        // cloned/redacted again on every unrelated step update.
                         observer.update({
                             ...structuredClone(metadata),
+                            steps: Object.fromEntries(Object.entries(steps).map(([id, step]) => [id, { ...step }])),
                             ...(value !== undefined ? { value } : {}),
                         });
                     }
@@ -482,7 +705,29 @@ export function defineJevFlow(name, build) {
                     try {
                         let value;
                         if (step.kind === "jev") {
-                            const request = mapValue(step.request, (e) => evaluate(e.ast, data, values));
+                            const generated = step.factory
+                                ? step.factory(jsonSnapshot(mapValue(step.input, (e) => evaluate(e.ast, data, values))))
+                                : step.request;
+                            if (step.factory) {
+                                if (generated &&
+                                    typeof generated.then ===
+                                        "function") {
+                                    // Invalid async factories must not leave an unhandled rejection.
+                                    void Promise.resolve(generated).catch(() => { });
+                                    throw new TypeError("Request factory must be synchronous");
+                                }
+                                if (!plain(generated) || !plain(generated.questions))
+                                    throw new Error("Request factory must return a synchronous SDK request");
+                                for (const name of step.answerNames)
+                                    if (!Object.hasOwn(generated.questions, name))
+                                        throw new Error(`Unknown generated question: ${name}`);
+                            }
+                            const request = mapValue(generated, (e) => {
+                                if (step.factory)
+                                    throw new Error("Request factories must return resolved values");
+                                return evaluate(e.ast, data, values);
+                            });
+                            abortCheck();
                             const call = () => options.client.systemOne(request, {
                                 signal: controller.signal,
                             });
@@ -491,15 +736,211 @@ export function defineJevFlow(name, build) {
                                 stepId: step.id,
                                 executionId: state.executionId,
                             };
-                            value = await (observer
+                            value = await runCallback(() => observer
                                 ? observer.request(link, (id) => {
+                                    if (controller.signal.aborted ||
+                                        state.status !== "running")
+                                        return;
                                     state.traceId = id;
                                     emit();
                                 }, call)
-                                : call());
+                                : call(), controller.signal);
                             abortCheck();
                         }
-                        else if (step.kind === "branch") {
+                        else if (step.kind === "task") {
+                            const input = jsonSnapshot(mapValue(step.input, (e) => evaluate(e.ast, data, values)));
+                            state.data = { input };
+                            emit();
+                            value = jsonSnapshot(await runCallback((signal) => step.task(jsonSnapshot(input), {
+                                signal,
+                                runId: run.id,
+                                stepId: step.id,
+                                executionId: state.executionId,
+                            }), controller.signal, step.timeoutMs));
+                            abortCheck();
+                            state.data = { input, output: jsonSnapshot(value) };
+                        }
+                        else if (step.kind === "loop") {
+                            const config = step.loop;
+                            const initial = jsonSnapshot(mapValue(config.initial, (e) => evaluate(e.ast, data, values)));
+                            const context = jsonSnapshot(mapValue(config.context, (e) => evaluate(e.ast, data, values)));
+                            let current = jsonSnapshot(initial);
+                            state.collection = { total: 0, concurrency: 1, items: [] };
+                            state.loop = { maxIterations: config.maxIterations };
+                            state.data = { input: initial, output: current };
+                            for (let index = 0;; index++) {
+                                abortCheck();
+                                const decision = evaluate(config.when.ast, current, new Map());
+                                if (typeof decision !== "boolean")
+                                    throw new TypeError("Loop condition did not return a boolean");
+                                state.decision = decision;
+                                if (!decision) {
+                                    state.loop = { ...state.loop, stopReason: "condition" };
+                                    break;
+                                }
+                                if (index === config.maxIterations) {
+                                    state.loop = { ...state.loop, stopReason: "limit" };
+                                    throw new FlowLoopLimitError();
+                                }
+                                reserve(config.program.definition.nodes.length);
+                                state.collection = {
+                                    ...state.collection,
+                                    total: index + 1,
+                                    items: [
+                                        ...state.collection.items,
+                                        { index, status: "waiting" },
+                                    ],
+                                };
+                                const updateIteration = (child) => {
+                                    state.collection = {
+                                        ...state.collection,
+                                        items: state.collection.items.map((item) => item.index === index
+                                            ? {
+                                                index,
+                                                status: child.status === "pending"
+                                                    ? "running"
+                                                    : child.status === "success"
+                                                        ? "completed"
+                                                        : child.status,
+                                                run: child,
+                                            }
+                                            : item),
+                                    };
+                                    emit();
+                                };
+                                const result = await config.program.run({ state: current, index, context }, withBudget({
+                                    client: options.client,
+                                    signal: controller.signal,
+                                    devtools: {
+                                        startFlow(_definition, child) {
+                                            updateIteration(child);
+                                            return {
+                                                update: updateIteration,
+                                                request(link, onTrace, callback) {
+                                                    return observer
+                                                        ? observer.request({
+                                                            ...link,
+                                                            runId: run.id,
+                                                            stepId: `${step.id}/${index}/${link.stepId}`,
+                                                        }, onTrace, callback)
+                                                        : callback();
+                                                },
+                                            };
+                                        },
+                                    },
+                                }, budget));
+                                abortCheck();
+                                current = jsonSnapshot(result.value);
+                                state.data = { input: initial, output: current };
+                            }
+                            value = current;
+                        }
+                        else if (step.kind === "map") {
+                            const config = step.collection;
+                            const items = jsonSnapshot(mapValue(config.items, (e) => evaluate(e.ast, data, values)));
+                            const context = jsonSnapshot(mapValue(config.context, (e) => evaluate(e.ast, data, values)));
+                            if (!Array.isArray(items))
+                                throw new TypeError("Map items must be an array");
+                            if (items.length > config.maxItems)
+                                throw new RangeError("Map exceeds maxItems");
+                            reserve(items.length * config.program.definition.nodes.length);
+                            state.collection = {
+                                total: items.length,
+                                concurrency: config.concurrency,
+                                items: items.map((_, index) => ({ index, status: "waiting" })),
+                            };
+                            emit();
+                            const results = new Array(items.length);
+                            let next = 0, failed = false, firstError;
+                            const updateItem = (index, child) => {
+                                state.collection = {
+                                    ...state.collection,
+                                    items: state.collection.items.map((item) => item.index === index
+                                        ? {
+                                            index,
+                                            status: child.status === "pending"
+                                                ? "running"
+                                                : child.status === "success"
+                                                    ? "completed"
+                                                    : child.status,
+                                            run: child,
+                                        }
+                                        : item),
+                                };
+                                emit();
+                            };
+                            const worker = async () => {
+                                while (!controller.signal.aborted &&
+                                    !failed &&
+                                    next < items.length) {
+                                    const index = next++;
+                                    try {
+                                        const result = await config.program.run({ item: items[index], index, context }, withBudget({
+                                            client: options.client,
+                                            signal: controller.signal,
+                                            devtools: {
+                                                startFlow(_definition, child) {
+                                                    updateItem(index, child);
+                                                    return {
+                                                        update(child) {
+                                                            updateItem(index, child);
+                                                        },
+                                                        request(link, onTrace, callback) {
+                                                            return observer
+                                                                ? observer.request({
+                                                                    ...link,
+                                                                    runId: run.id,
+                                                                    stepId: `${step.id}/${index}/${link.stepId}`,
+                                                                }, onTrace, callback)
+                                                                : callback();
+                                                        },
+                                                    };
+                                                },
+                                            },
+                                        }, budget));
+                                        results[index] = result.value;
+                                    }
+                                    catch (error) {
+                                        if (!failed) {
+                                            failed = true;
+                                            firstError = error;
+                                        }
+                                        stopSiblings(error);
+                                    }
+                                }
+                            };
+                            await Promise.all(Array.from({ length: Math.min(config.concurrency, items.length) }, worker));
+                            if (failed || controller.signal.aborted) {
+                                state.collection = {
+                                    ...state.collection,
+                                    items: state.collection.items.map((item) => item.status === "waiting"
+                                        ? {
+                                            ...item,
+                                            status: options.signal?.aborted
+                                                ? "cancelled"
+                                                : "blocked",
+                                        }
+                                        : item),
+                                };
+                                if (failed)
+                                    throw firstError;
+                                abortCheck();
+                            }
+                            value = results;
+                        }
+                        else if (step.kind === "merge") {
+                            value = values.get(step.mergeOf);
+                            state.decision = run.steps[step.mergeOf].decision;
+                            // Capture is observational; a direct input/reference can contain
+                            // a non-JSON value even though task boundaries require JSON.
+                            try {
+                                state.data = { output: jsonSnapshot(value) };
+                            }
+                            catch {
+                                state.data = "Selected value could not be captured as JSON.";
+                            }
+                        }
+                        else if (step.kind === "branch" || step.kind === "if") {
                             const decision = evaluate(step.when.ast, data, values);
                             if (typeof decision !== "boolean")
                                 throw new Error("Branch condition did not return a boolean");
@@ -518,10 +959,10 @@ export function defineJevFlow(name, build) {
                                 }
                                 catch (e) {
                                     if (!failed) {
-                                        firstError = e;
+                                        firstError = siblingFailure ? siblingFailure.error : e;
                                         failed = true;
                                     }
-                                    controller.abort(e);
+                                    stopSiblings(e);
                                     throw e;
                                 }
                             }));

package/lib/flow/runtime.d.ts

@@ -0,0 +1,5 @@
+import type { Json } from "../src/protocol.js";
+/** Detached JSON snapshot, without capture truncation or lossy JSON.stringify. */
+export declare function jsonSnapshot(value: unknown, seen?: Set<object>, depth?: number): Json;
+/** Cancellation ends awaiting, even when user code ignores the cooperative signal. */
+export declare function runCallback(callback: (signal: AbortSignal) => unknown, parent: AbortSignal, timeoutMs?: number): Promise<unknown>;