jev-devtools 0.4.1 → 0.5.1

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.1](https://img.shields.io/badge/npm-v0.5.1-E551BA?labelColor=0D0A0F&logo=npm)](https://www.npmjs.com/package/jev-devtools/v/0.5.1)
 
 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.1.** 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,12 +33,14 @@ 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
 ```
 
+Use ESM imports, matching React/React DOM **18.x or 19.x**, Node **22.12+**, and TypeSafe SDK **0.7.x**. TypeScript consumers need **5.4+** and compatible React/Node types. React and React DOM are required package peers even for server-only installations. See [compatibility and all public imports](https://github.com/diegoag64/jev-devtools/blob/main/docs/integration.md#compatibility-and-public-imports); `/server` and `/flow` run only on Node.
+
 To try local changes before a future release:
 
 ```sh
@@ -44,7 +48,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.1.tgz
 ```
 
 Mount once. The drawer loads its own styles; no CSS import is needed:
@@ -70,19 +74,23 @@ app.use(inspector.middleware); // Mount at root, before fallback handlers.
 // Call inspector.dispose() on shutdown.
 ```
 
-Only calls through that client are captured. The React component subscribes via same-origin SSE, receiving an initial snapshot followed by changed traces. Older client/server combinations remain compatible through full snapshots. Both sides default to disabled. API keys remain server-side. Browser code is SSR-safe. The drawer uses a Shadow DOM boundary and its own stylesheet so host page selectors cannot alter its internal layout. Existing stylesheet imports remain supported; no Tailwind or shadcn installation is required. Drag the Flow canvas to pan, scroll/pinch to zoom, or use Fit.
+Only calls through that client are captured. The React component subscribes via same-origin SSE, receiving an initial snapshot followed by changed traces. Older client/server combinations remain compatible through full snapshots. Both sides default to disabled. API keys remain server-side. Browser code is SSR-safe. The drawer uses a Shadow DOM boundary and its own stylesheet so host page selectors cannot alter its internal layout. No Tailwind or shadcn installation is required. Drag the Flow canvas to pan, scroll/pinch to zoom, or use Fit.
 
 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 +119,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";
 } | {
@@ -23,7 +26,8 @@ export declare class FlowExpression<T> {
     readonly ast: Ast;
     protected readonly [valueTypeBrand]: T;
     constructor(ast: Ast, owner?: object);
-    get<K extends keyof T & (string | number)>(key: K): FlowExpression<T[K]>;
+    /** Select an own field from an object or array; primitive properties are unsupported. */
+    get<K extends keyof T & (string | number)>(this: FlowExpression<object>, key: K): FlowExpression<T[K]>;
     eq(value: T | FlowExpression<T>): FlowExpression<boolean>;
     lt(this: FlowExpression<number>, value: number | FlowExpression<number>): FlowExpression<boolean>;
     gt(this: FlowExpression<number>, value: number | FlowExpression<number>): FlowExpression<boolean>;
@@ -74,6 +78,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;