jev-devtools 0.4.1 → 0.5.0

package/README.md

@@ -1,12 +1,14 @@
 # Jev DevTools
 
-[![npm version 0.4.1](https://img.shields.io/badge/npm-v0.4.1-E551BA?labelColor=0D0A0F&logo=npm)](https://www.npmjs.com/package/jev-devtools/v/0.4.1)
+[![npm version 0.5.0](https://img.shields.io/badge/npm-v0.5.0-E551BA?labelColor=0D0A0F&logo=npm)](https://www.npmjs.com/package/jev-devtools/v/0.5.0)
 
 A React drawer and Node adapter for inspecting TypeSafe Jev requests with animated diagrams. Includes request history, context, questions, typed answers, transport attempts, and raw snapshots.
 
-**Version 0.4.1 is prepared for release; publication is pending.** Check the release history for verified publication status. **Experimental (pre-1.0).** React 18/19 and Node 22.12+ are supported. APIs may change before 1.0. Verification uses sample responses through the real TypeSafe SDK, not live inference.
+**Source version: 0.5.0.** Check the [release history](https://github.com/diegoag64/jev-devtools/blob/main/CHANGELOG.md) for npm availability. If trying this source before publication, install the local archive below. **Experimental (pre-1.0).** React 18/19 and Node 22.12+ are supported. APIs may change before 1.0. Verification uses sample responses through the real TypeSafe SDK, not live inference.
 
-[Changelog and release history](https://github.com/diegoag64/jev-devtools/blob/main/CHANGELOG.md) — published versions and unreleased work.
+[Website](https://jevtools.dev/) · [Documentation](https://docs.jevtools.dev/) · [Quick start](https://docs.jevtools.dev/getting-started/) · [API reference](https://docs.jevtools.dev/api/reference/) · [Release history](https://docs.jevtools.dev/changelog/)
+
+Hosted docs update separately; use the installed declarations and bundled skill for your exact version, and the [repository changelog](https://github.com/diegoag64/jev-devtools/blob/main/CHANGELOG.md) for release-candidate status.
 
 ## Demo
 
@@ -31,10 +33,10 @@ The [setup skill](https://github.com/diegoag64/jev-devtools/blob/main/packages/j
 
 ## Install
 
-The npm command installs the latest published release (0.4.0 at preparation time):
+Install from npm:
 
 ```sh
-npm install jev-devtools @typesafe-ai/sdk
+pnpm add jev-devtools @typesafe-ai/sdk
 ```
 
 To try local changes before a future release:
@@ -44,7 +46,7 @@ To try local changes before a future release:
 npm ci
 npm run pack:devtools
 # From the consuming app:
-npm install /absolute/path/to/jev-devtools-0.4.1.tgz
+npm install /absolute/path/to/jev-devtools-0.5.0.tgz
 ```
 
 Mount once. The drawer loads its own styles; no CSS import is needed:
@@ -74,15 +76,19 @@ Only calls through that client are captured. The React component subscribes via
 
 History is bounded to 50 calls in memory by default. API routes and inspector endpoints must share an adapter instance; distributed processes and edge runtimes are not supported. Without `authorize`, the middleware accepts only loopback connections; Web Request handlers can't see the connection's address, so run those servers on `127.0.0.1`. Captures include bounded/redacted context and answers, not hidden model reasoning.
 
-For Next.js App Router, use `getJevDevtools(appKey, optionsFactory)` from `/server` to share an adapter across server reloads, expose `handleNodeRoute` through an optional catch-all Route Handler, and mount the root component in a client boundary. See the [Next.js guide](https://github.com/diegoag64/jev-devtools/blob/main/docs/nextjs.md) and runnable example. No Next dependency is required by this package.
+Known credential fields are always redacted from DevTools captures; SDK and runtime data remain unchanged. The optional `<JevDevtools redactAdditionalSensitiveData={false} />` prop controls **display-only** masking of supported email, phone, postal address, SSN and card-number fields. It defaults to `true` and updates existing views immediately. These additional values still exist in capture/stream/browser memory while masked. Custom server redaction remains active, and neither credentials nor custom-redacted values can be revealed. Headers/options are not captured. See the [exact policy and limitations](https://github.com/diegoag64/jev-devtools/blob/main/docs/integration.md#redaction-policy); arbitrary secrets in prose and unusual field names still need application-specific redaction.
+
+For Next.js App Router, use `getJevDevtools(appKey, optionsFactory)` from `/server` to share an adapter across server reloads, expose `handleNodeRoute` through an optional catch-all Route Handler, and mount the root component in a client boundary. See the [Next.js guide](https://docs.jevtools.dev/guides/nextjs/) and runnable example. No Next dependency is required by this package.
 
-[Full integration guide](https://github.com/diegoag64/jev-devtools/blob/main/docs/integration.md) · [Repository and playground](https://github.com/diegoag64/jev-devtools)
+[Quick start](https://docs.jevtools.dev/getting-started/) · [Detailed integration and access controls](https://github.com/diegoag64/jev-devtools/blob/main/docs/integration.md) · [Repository and playground](https://github.com/diegoag64/jev-devtools)
+
+Jev DevTools is an independent, open-source community project. It is not affiliated with TypeSafe AI.
 
 MIT for project code. See bundled LICENSE and THIRD_PARTY_NOTICES.txt for original design attribution and TypeSafe branding.
 
 ## Connected Jev flows with `jev-devtools/flow`
 
-Define calls, conditions, parallel checks, and named outcomes with `jev-devtools/flow`. **0.4.0 adds** server function steps (`task`), runtime request factories, bounded collections (`map`), returning conditionals (`if`), stateful iteration (`loop`), and strict numeric `.gt()` comparisons. The drawer connects request diagrams, function results, selected paths, collection items, and loop iterations on one canvas. Existing single-request integrations remain supported.
+Define calls, conditions, parallel checks, and named outcomes with `jev-devtools/flow`. The builder supports server function steps (`task`), runtime request factories, bounded collections (`map`), returning conditionals (`if`), stateful iteration (`loop`), and strict numeric `.gt()` comparisons. The drawer connects request diagrams, function results, selected paths, collection items, and loop iterations on one canvas. Existing single-request integrations remain supported.
 
 On the server, reuse the instrumented `jev` client and `inspector` from the setup above:
 
@@ -111,9 +117,11 @@ const result = await review.run({ message: 'Please review my ticket.' }, {
 // Handle result.outcome in your app. The flow does not execute business actions.
 ```
 
-Define once in a Node module and run per request. Use `flow.parallel` for concurrent named lanes; downstream calls wait for every lane to succeed. `flow.branch` is terminal in its block; use `flow.if` when selected values feed shared downstream work. Tasks execute application code on Node with JSON-compatible inputs/results; maps and loops have explicit bounds. Runs have SDK retries and cooperative cancellation, with bounded in-memory inspector history. They do not provide durable or distributed execution. Keep the 0.4.0 server and drawer together to inspect its new step kinds.
+Define once in a Node module and run per request. Use `flow.parallel` for concurrent named lanes; downstream calls wait for every lane to succeed. `flow.branch` is terminal in its block; use `flow.if` when selected values feed shared downstream work. Tasks execute application code on Node with JSON-compatible inputs/results; maps and loops have explicit bounds. Runs have SDK retries and cooperative cancellation, with bounded in-memory inspector history. They do not provide durable or distributed execution. Keep the server and drawer on the same package version to inspect every supported step kind.
+
+**Added in 0.5.0.** **Copy fixture** in the drawer saves a run as JSON, and `replayClient(fixture)` from `jev-devtools/flow` replays its Jev calls in tests with no network access or API key; tasks run again. `compareWithFixture` from `jev-devtools/flow` compares a live run's answers, routing and item steps with a saved fixture.
 
-[Full flow guide](https://github.com/diegoag64/jev-devtools/blob/main/docs/flows.md) · [AI flow recipe](https://github.com/diegoag64/jev-devtools/blob/main/packages/jev-devtools/skills/setup-jev-devtools/references/flows.md)
+[Beginner flow guide](https://docs.jevtools.dev/guides/flow-basics/) · [Flow API reference](https://docs.jevtools.dev/api/flow/) · [Detailed flow guide](https://github.com/diegoag64/jev-devtools/blob/main/docs/flows.md) · [AI flow recipe](https://github.com/diegoag64/jev-devtools/blob/main/packages/jev-devtools/skills/setup-jev-devtools/references/flows.md)
 
 To have your coding agent add a flow after installation:
 

package/lib/flow/compare.d.ts

@@ -0,0 +1,61 @@
+import type { FlowDefinition } from "../src/flow-protocol.js";
+import type { FlowFixture } from "../src/flow-fixture.js";
+import type { FlowOutcome, FlowRunOptions } from "./index.js";
+type AnswerValue = string | number | boolean | null;
+/** One scalar answer field of a jev step both sides ran; delta is set when both sides and their difference are finite. Answer drift never sets FixtureComparison.changed on its own. */
+export type AnswerChange = {
+    stepId: string;
+    question: string;
+    field: string;
+    recorded?: AnswerValue;
+    live?: AnswerValue;
+    delta?: number;
+    changed: boolean;
+};
+export type FixtureComparison = {
+    /** Outcome, value or a decision differs, or a jev step ran on only one side. Answer drift alone does not set it. */
+    changed: boolean;
+    outcome: {
+        recorded: string;
+        live: string;
+        changed: boolean;
+    };
+    value: {
+        recorded?: unknown;
+        live?: unknown;
+        changed: boolean;
+    };
+    decisions: {
+        stepId: string;
+        recorded?: boolean;
+        live?: boolean;
+        changed: boolean;
+    }[];
+    answers: AnswerChange[];
+    /** Jev step ids; map and loop items use `${parentId}/${index}/${innerId}`. */
+    steps: {
+        onlyRecorded: string[];
+        onlyLive: string[];
+    };
+    /** The live run's response bodies, unredacted and untruncated. */
+    liveFixture: FlowFixture;
+};
+/** Any flow from defineJevFlow, typed by its input. */
+export type ComparableFlow<T> = {
+    definition: FlowDefinition;
+    run(input: T, options: FlowRunOptions): Promise<FlowOutcome & {
+        runId: string;
+    }>;
+};
+/**
+ * Replays `fixture` offline and runs the flow with `options.client` on the same input, then
+ * reports what changed. Only the live run reaches `options.devtools`. Tasks run on both
+ * sides, the recorded side on the replayed answers. Rejects when the
+ * fixture cannot replay this input, or with the live run's own error.
+ */
+export declare function compareWithFixture<T>(flow: ComparableFlow<T>, input: T, fixture: FlowFixture, options: FlowRunOptions & {
+    tolerance?: number;
+}): Promise<FixtureComparison>;
+/** One plain line per change, or "no changes from fixture". */
+export declare function formatComparison(comparison: FixtureComparison): string;
+export {};

package/lib/flow/compare.js

@@ -0,0 +1,336 @@
+import { isDeepStrictEqual } from "node:util";
+import { replayClient } from "./replay.js";
+import { observeRequest } from "./runtime.js";
+const record = (v) => !!v && typeof v === "object" && !Array.isArray(v);
+async function observe(flow, input, options) {
+    const bodies = new Map();
+    const captures = [];
+    let latest;
+    const user = options.devtools;
+    const devtools = {
+        startFlow(definition, run) {
+            latest = run;
+            let inner;
+            try {
+                inner = user?.startFlow(structuredClone(definition), structuredClone(run));
+            }
+            catch {
+                /* Recording cannot stop execution. */
+            }
+            return {
+                update(next) {
+                    latest = next;
+                    try {
+                        // Recording consumers cannot alter the comparison's private snapshot.
+                        inner?.update(structuredClone(next));
+                    }
+                    catch {
+                        /* Best effort capture. */
+                    }
+                },
+                request(link, onTrace, callback) {
+                    const stepId = link.stepId;
+                    // Capture the runner's result even if recording skips, throws or substitutes it.
+                    const result = observeRequest(callback, inner
+                        ? (callOnce) => inner.request({ ...link }, onTrace, callOnce)
+                        : undefined);
+                    // A separate subscriber; the runner awaits the original result unchanged.
+                    const capture = Promise.resolve(result).then(
+                    // Observers may retain the result and mutate it on later run updates.
+                    (body) => bodies.set(stepId, structuredClone(body)), () => undefined);
+                    // Handle snapshot failures now, then surface them after successful execution.
+                    void capture.catch(() => { });
+                    captures.push(capture);
+                    return result;
+                },
+            };
+        },
+    };
+    const result = await flow.run(input, { ...options, devtools });
+    await Promise.all(captures);
+    return {
+        outcome: result.outcome,
+        ...(result.value !== undefined ? { value: result.value } : {}),
+        ...(latest ? { run: latest } : {}),
+        bodies,
+    };
+}
+/**
+ * Visits both runs' nodes in flowFixture's order: definition order, and at a map or loop
+ * its items by ascending index, each item walked whole before the next.
+ */
+function walk(definition, recorded, live, visit, prefix = "") {
+    const items = (step) => new Map((step?.collection?.items ?? []).flatMap((item) => item.run ? [[item.index, item.run]] : []));
+    for (const node of definition.nodes) {
+        const r = recorded?.steps[node.id], l = live?.steps[node.id];
+        if (node.itemDefinition) {
+            const before = items(r), after = items(l);
+            // Items complete in any order, so walk them by index.
+            for (const index of union(before.keys(), after.keys()).sort((a, b) => a - b))
+                walk(node.itemDefinition, before.get(index), after.get(index), visit, `${prefix}${node.id}/${index}/`);
+        }
+        visit(node, prefix + node.id, r, l);
+    }
+}
+/** Scalar leaves of an answer, by path segments, without the type discriminator. */
+function leaves(value, path = [], out = []) {
+    if (!value || typeof value !== "object")
+        return out;
+    for (const [key, child] of Object.entries(value)) {
+        if (!path.length && key === "type")
+            continue;
+        if (child && typeof child === "object")
+            leaves(child, [...path, key], out);
+        else if (child === null ||
+            typeof child === "string" ||
+            typeof child === "number" ||
+            typeof child === "boolean")
+            out.push({ path: [...path, key], value: child });
+    }
+    return out;
+}
+/** Dotted for plain keys; keys with dots, brackets or quotes are bracketed so paths stay distinct. */
+const fieldName = (path) => path.reduce((name, key) => key && !/[.[\]"]/.test(key)
+    ? name + (name ? "." : "") + key
+    : `${name}[${JSON.stringify(key)}]`, "");
+const byPath = (leaves) => new Map(leaves.map((leaf) => [JSON.stringify(leaf.path), leaf]));
+const answersOf = (body) => record(body) && record(body.answers) ? body.answers : {};
+/** Recorded keys first, then keys only the live side has. */
+const union = (recorded, live) => [
+    ...new Set([...recorded, ...live]),
+];
+function compareAnswers(stepId, recordedBody, liveBody, tolerance) {
+    const recorded = answersOf(recordedBody), live = answersOf(liveBody), changes = [];
+    for (const question of union(Object.keys(recorded), Object.keys(live))) {
+        const before = byPath(leaves(recorded[question])), after = byPath(leaves(live[question]));
+        for (const key of union(before.keys(), after.keys())) {
+            const r = before.get(key)?.value, l = after.get(key)?.value;
+            const leaf = before.get(key) ?? after.get(key);
+            if (!leaf)
+                continue; // Every key comes from one of the two maps.
+            const change = {
+                stepId,
+                question,
+                field: fieldName(leaf.path),
+                changed: false,
+            };
+            if (before.has(key))
+                change.recorded = r;
+            if (after.has(key))
+                change.live = l;
+            if (typeof r === "number" && typeof l === "number") {
+                const delta = l - r;
+                if (!Number.isFinite(r) || !Number.isFinite(l))
+                    change.changed = !Object.is(r, l);
+                else if (!Number.isFinite(delta))
+                    change.changed = true; // Overflow: never read as unchanged.
+                else {
+                    change.delta = delta;
+                    // Allow float noise at the boundary (0.4 - 0.3 is 0.10000000000000003).
+                    change.changed =
+                        Math.abs(delta) > tolerance + tolerance * 8 * Number.EPSILON;
+                }
+            }
+            else
+                change.changed = before.has(key) !== after.has(key) || r !== l;
+            changes.push(change);
+        }
+    }
+    return changes;
+}
+/**
+ * Replays `fixture` offline and runs the flow with `options.client` on the same input, then
+ * reports what changed. Only the live run reaches `options.devtools`. Tasks run on both
+ * sides, the recorded side on the replayed answers. Rejects when the
+ * fixture cannot replay this input, or with the live run's own error.
+ */
+export async function compareWithFixture(flow, input, fixture, options) {
+    const { tolerance = 0, ...runOptions } = options;
+    if (!Number.isFinite(tolerance) || tolerance < 0)
+        throw new TypeError("tolerance must be a non-negative finite number");
+    // Outside the try, so an invalid fixture rejects with replayClient's own TypeError.
+    const client = replayClient(fixture);
+    let recorded;
+    try {
+        recorded = await observe(flow, input, {
+            client,
+            ...(runOptions.signal ? { signal: runOptions.signal } : {}),
+        });
+    }
+    catch (error) {
+        if (error instanceof Error &&
+            ["AbortError", "APIUserAbortError"].includes(error.name))
+            throw error;
+        throw new Error(`Fixture replay failed: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+    }
+    const live = await observe(flow, input, runOptions);
+    const decisions = [], answers = [], onlyRecorded = [], onlyLive = [], steps = {};
+    walk(flow.definition, recorded.run, live.run, (node, id, rs, ls) => {
+        // Merges copy their if()'s decision and loops keep their last while(); neither counts.
+        if (node.kind === "branch" || node.kind === "if") {
+            const r = rs?.decision, l = ls?.decision;
+            if (r !== undefined || l !== undefined)
+                decisions.push({
+                    stepId: id,
+                    ...(r !== undefined ? { recorded: r } : {}),
+                    ...(l !== undefined ? { live: l } : {}),
+                    changed: r !== l,
+                });
+            return;
+        }
+        if (node.kind !== "jev")
+            return;
+        // Item status is under the bare id; bodies arrive under the composed id.
+        const inRecorded = rs?.status === "completed" && recorded.bodies.has(id), inLive = ls?.status === "completed" && live.bodies.has(id);
+        if (inLive)
+            steps[id] = structuredClone(live.bodies.get(id));
+        if (inRecorded && inLive)
+            answers.push(...compareAnswers(id, recorded.bodies.get(id), live.bodies.get(id), tolerance));
+        else if (inRecorded)
+            onlyRecorded.push(id);
+        else if (inLive)
+            onlyLive.push(id);
+    });
+    const outcome = {
+        recorded: recorded.outcome,
+        live: live.outcome,
+        changed: recorded.outcome !== live.outcome,
+    };
+    const value = {
+        ...(recorded.value !== undefined ? { recorded: recorded.value } : {}),
+        ...(live.value !== undefined ? { live: live.value } : {}),
+        changed: !isDeepStrictEqual(recorded.value, live.value),
+    };
+    return {
+        changed: outcome.changed ||
+            value.changed ||
+            decisions.some((d) => d.changed) ||
+            onlyRecorded.length > 0 ||
+            onlyLive.length > 0,
+        outcome,
+        value,
+        decisions,
+        answers,
+        steps: { onlyRecorded, onlyLive },
+        liveFixture: { version: 1, flow: flow.definition.name, steps },
+    };
+}
+/** JSON for ordinary values; never throws on BigInt, cycles, functions or symbols. */
+function json(v) {
+    if (v === undefined)
+        return "(none)";
+    try {
+        const text = JSON.stringify(v);
+        if (text !== undefined)
+            return text;
+    }
+    catch {
+        /* Not plain JSON; render it below. */
+    }
+    try {
+        return loose(v, new Set()) ?? `[${typeof v}]`;
+    }
+    catch {
+        return "[unserializable]";
+    }
+}
+/** JSON.stringify's layout, with BigInt as 1n, cycles as [cycle] and other values by type. */
+function loose(v, ancestors) {
+    if (typeof v === "bigint")
+        return `${v}n`;
+    if (typeof v === "function" || typeof v === "symbol")
+        return `[${typeof v}]`;
+    if (v === undefined)
+        return undefined;
+    if (v === null || typeof v !== "object")
+        return JSON.stringify(v);
+    if (ancestors.has(v))
+        return "[cycle]";
+    const toJSON = v.toJSON;
+    if (typeof toJSON === "function")
+        return loose(toJSON.call(v), ancestors);
+    ancestors.add(v);
+    const text = Array.isArray(v)
+        ? `[${v.map((item) => loose(item, ancestors) ?? "null").join(",")}]`
+        : `{${Object.entries(v)
+            .flatMap(([key, item]) => {
+            const shown = loose(item, ancestors);
+            return shown === undefined ? [] : [`${JSON.stringify(key)}:${shown}`];
+        })
+            .join(",")}}`;
+    ancestors.delete(v);
+    return text;
+}
+/** Report text beyond this many characters is cut; the comparison keeps values in full. */
+const LIMIT = 160;
+/** Up to LIMIT characters from start, marking cut ends; never splits a surrogate pair. */
+function cut(text, start) {
+    if (start > 0 && /[\uDC00-\uDFFF]/.test(text[start]))
+        start--;
+    if (start === 0 && text.length <= LIMIT)
+        return text;
+    let end = Math.min(start + LIMIT, text.length);
+    if (end < text.length && /[\uD800-\uDBFF]/.test(text[end - 1]))
+        end--;
+    return `${start ? "..." : ""}${text.slice(start, end)}${end < text.length ? "..." : ""} (${text.length} chars)`;
+}
+/** Cuts both sides alike; when the first difference is past the cut, both show a window around it. */
+function clipPair(a, b) {
+    let at = 0;
+    while (at < a.length && at < b.length && a[at] === b[at])
+        at++;
+    const start = a !== b && a.length > LIMIT && b.length > LIMIT && at >= LIMIT - 1
+        ? at - 40
+        : 0;
+    return [cut(a, start), cut(b, start)];
+}
+const route = (v) => v === undefined ? "(not run)" : v ? "then" : "else";
+const scalar = (v, digits) => v === undefined
+    ? "(none)"
+    : typeof v === "number" && digits !== undefined
+        ? v.toFixed(digits)
+        : String(v);
+/** Two decimals, more when two different numbers would print the same, else exact. */
+function precision(a, b) {
+    if (typeof a !== "number" || typeof b !== "number" || a === b)
+        return 2;
+    for (let digits = 2; digits <= 20; digits++)
+        if (a.toFixed(digits) !== b.toFixed(digits))
+            return digits;
+    return undefined;
+}
+function signed(delta, digits) {
+    const sign = delta < 0 ? "-" : "+";
+    if (digits !== undefined)
+        for (; digits <= 20; digits++)
+            if (delta === 0 || Number(delta.toFixed(digits)) !== 0)
+                return sign + Math.abs(delta).toFixed(digits);
+    return sign + String(Math.abs(delta));
+}
+/** One plain line per change, or "no changes from fixture". */
+export function formatComparison(comparison) {
+    const lines = [];
+    const { outcome, value, decisions, steps, answers } = comparison;
+    if (outcome.changed)
+        lines.push(`outcome: ${outcome.recorded} -> ${outcome.live}`);
+    if (value.changed) {
+        const [recorded, live] = clipPair(json(value.recorded), json(value.live));
+        lines.push(`value: ${recorded} -> ${live}`);
+    }
+    for (const d of decisions)
+        if (d.changed)
+            lines.push(`decision ${d.stepId}: ${route(d.recorded)} -> ${route(d.live)}`);
+    for (const id of steps.onlyRecorded)
+        lines.push(`step ${id}: recorded only`);
+    for (const id of steps.onlyLive)
+        lines.push(`step ${id}: live only`);
+    for (const a of answers) {
+        if (!a.changed)
+            continue;
+        const digits = precision(a.recorded, a.live);
+        const [recorded, live] = clipPair(scalar(a.recorded, digits), scalar(a.live, digits));
+        lines.push(`${fieldName([a.stepId, a.question])}${a.field.startsWith("[") ? "" : "."}${a.field}: ${recorded} -> ${live}` +
+            (a.delta !== undefined ? ` (${signed(a.delta, digits)})` : ""));
+    }
+    return lines.length ? lines.join("\n") : "no changes from fixture";
+}

package/lib/flow/index.d.ts

@@ -1,6 +1,9 @@
 import type { Questions, ResultFor, SystemOneRequest, TypeSafeClient } from "@typesafe-ai/sdk";
 import type { FlowDefinition, FlowDisplay, FlowRun } from "../src/flow-protocol.js";
 export type { FlowDisplay, FlowDefinition, FlowRun, FlowStep, } from "../src/flow-protocol.js";
+export { replayClient, type FlowFixture } from "./replay.js";
+export { flowFixture, type BuiltFlowFixture } from "../src/flow-fixture.js";
+export { compareWithFixture, formatComparison, type AnswerChange, type ComparableFlow, type FixtureComparison, } from "./compare.js";
 type Ast = {
     op: "input";
 } | {
@@ -74,6 +77,7 @@ export type FlowRequestFactory<I, Q extends Questions> = {
 export type FlowObserver = {
     startFlow(definition: FlowDefinition, run: FlowRun): {
         update(run: FlowRun): void;
+        /** Call through synchronously to establish recording context. The runner owns the result. */
         request<T>(link: {
             runId: string;
             stepId: string;

package/lib/flow/index.js

@@ -1,5 +1,9 @@
 import { randomUUID } from "node:crypto";
-import { jsonSnapshot, runCallback } from "./runtime.js";
+import { jsonSnapshot, observerSnapshot, observeRequest, runCallback, } from "./runtime.js";
+import { stepContext } from "./step-context.js";
+export { replayClient } from "./replay.js";
+export { flowFixture } from "../src/flow-fixture.js";
+export { compareWithFixture, formatComparison, } from "./compare.js";
 const owners = new WeakMap();
 const builderIds = new WeakMap();
 function freezeAst(ast, depth = 0) {
@@ -64,8 +68,10 @@ 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) {
+const itemScopes = new WeakMap();
+function withBudget(options, budget, scope) {
     executionBudgets.set(options, budget);
+    itemScopes.set(options, scope);
     return options;
 }
 function definitionSize(definition) {
@@ -650,6 +656,11 @@ export function defineJevFlow(name, build) {
             };
             const started = performance.now(), values = new Map();
             const budget = executionBudgets.get(options) ?? { used: nodes.length };
+            const scope = itemScopes.get(options) ?? {
+                runId: run.id,
+                flow: name,
+                prefix: "",
+            };
             const reserve = (count) => {
                 if (budget.used + count > 1024)
                     throw new RangeError("Flow exceeds 1024 expanded steps");
@@ -662,16 +673,56 @@ export function defineJevFlow(name, build) {
             catch {
                 /* Recording cannot stop execution. */
             }
+            // Data objects are replaced, never mutated by execution. Keep detached
+            // copies stable so the recorder can reuse its captures on unrelated updates.
+            const observerData = new WeakMap();
+            const snapshotData = (value) => {
+                if (value && typeof value === "object" && observerData.has(value))
+                    return observerData.get(value);
+                let snapshot;
+                try {
+                    snapshot = observerSnapshot(value);
+                }
+                catch {
+                    // Direct flow outputs may be non-JSON; only their capture is unavailable.
+                    snapshot = "[capture unavailable]";
+                }
+                if (value && typeof value === "object")
+                    observerData.set(value, snapshot);
+                return snapshot;
+            };
             const emit = () => {
                 try {
                     if (observer) {
                         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 } : {}),
+                            steps: Object.fromEntries(Object.entries(steps).map(([id, step]) => [
+                                id,
+                                {
+                                    ...step,
+                                    ...(step.data !== undefined
+                                        ? { data: snapshotData(step.data) }
+                                        : {}),
+                                    ...(step.loop ? { loop: { ...step.loop } } : {}),
+                                    ...(step.captureWarnings
+                                        ? { captureWarnings: [...step.captureWarnings] }
+                                        : {}),
+                                    ...(step.collection
+                                        ? {
+                                            collection: {
+                                                ...step.collection,
+                                                // Child runs have already crossed this snapshot boundary.
+                                                // Copy mutable collection metadata, reuse detached children.
+                                                items: step.collection.items.map((item) => ({
+                                                    ...item,
+                                                })),
+                                            },
+                                        }
+                                        : {}),
+                                },
+                            ])),
+                            ...(value !== undefined ? { value: snapshotData(value) } : {}),
                         });
                     }
                 }
@@ -728,23 +779,31 @@ export function defineJevFlow(name, build) {
                                 return evaluate(e.ast, data, values);
                             });
                             abortCheck();
-                            const call = () => options.client.systemOne(request, {
-                                signal: controller.signal,
-                            });
+                            const call = () => {
+                                abortCheck();
+                                return stepContext.run({
+                                    runId: scope.runId,
+                                    stepId: scope.prefix + step.id,
+                                    executionId: state.executionId,
+                                    flow: scope.flow,
+                                }, () => options.client.systemOne(request, {
+                                    signal: controller.signal,
+                                }));
+                            };
                             const link = {
                                 runId: run.id,
                                 stepId: step.id,
                                 executionId: state.executionId,
                             };
-                            value = await runCallback(() => observer
-                                ? observer.request(link, (id) => {
+                            value = await runCallback(() => observeRequest(call, observer
+                                ? (callOnce) => observer.request(link, (id) => {
                                     if (controller.signal.aborted ||
                                         state.status !== "running")
                                         return;
                                     state.traceId = id;
                                     emit();
-                                }, call)
-                                : call(), controller.signal);
+                                }, callOnce)
+                                : undefined), controller.signal);
                             abortCheck();
                         }
                         else if (step.kind === "task") {
@@ -828,7 +887,7 @@ export function defineJevFlow(name, build) {
                                             };
                                         },
                                     },
-                                }, budget));
+                                }, budget, { ...scope, prefix: `${scope.prefix}${step.id}/${index}/` }));
                                 abortCheck();
                                 current = jsonSnapshot(result.value);
                                 state.data = { input: initial, output: current };
@@ -897,7 +956,10 @@ export function defineJevFlow(name, build) {
                                                     };
                                                 },
                                             },
-                                        }, budget));
+                                        }, budget, {
+                                            ...scope,
+                                            prefix: `${scope.prefix}${step.id}/${index}/`,
+                                        }));
                                         results[index] = result.value;
                                     }
                                     catch (error) {
@@ -1004,7 +1066,7 @@ export function defineJevFlow(name, build) {
                     throw new Error("Flow must return a named output");
                 run.status = "success";
                 run.outcome = result.outcome;
-                // Only the recorder snapshots output data; runtime keeps the actual typed value.
+                // emit() detaches the observer's output; callers keep the actual typed value.
                 if (result.value !== undefined)
                     run.value = result.value;
                 return { runId: run.id, ...result };