@nodetool-ai/reliability-harness 0.8.1

package/dist/compare.js

@@ -0,0 +1,267 @@
+import { diffNormalizedRecords, formatStreamDiff, streamDiffIsEmpty } from "./core/diff.js";
+import { checkGoldens } from "./core/golden.js";
+import { INVARIANT_CHECKS } from "./core/invariants/index.js";
+import { normalizeRunRecord } from "./core/normalize.js";
+import { getFaultModule } from "./faults/registry.js";
+// Side-effecting import: registers every built-in fault module (task D1's
+// "faults/index.ts registers on import" contract) so `getFaultModule` below
+// resolves journey-declared fault names without every caller of
+// `compareJourney` remembering to import the fault barrel itself.
+import "./faults/index.js";
+function onlyServerToClient(record) {
+    return {
+        ...record,
+        frames: record.frames.filter((f) => f.direction === "server_to_client")
+    };
+}
+/**
+ * Applies every fault in `faults` whose optional `surface` restriction either
+ * matches `surfaceName` or is unset (applies everywhere), in order, and
+ * returns one teardown that undoes them all in reverse — so a single
+ * `finally` block at each call site fully unwinds the fault's process-global
+ * side effects (today: the provider registry) regardless of how the driver
+ * run in between went. A fault name with no registered `FaultModule` is
+ * skipped and reported back via `unknownFaults` (its own return value), never
+ * silently ignored or thrown.
+ */
+async function applyFaults(journey, surfaceName, faults) {
+    const applicable = faults.filter((f) => f.surface === undefined || f.surface === surfaceName);
+    const applied = [];
+    const unknown = [];
+    const teardowns = [];
+    for (const fault of applicable) {
+        const module = getFaultModule(fault.type);
+        if (!module) {
+            unknown.push(fault.type);
+            continue;
+        }
+        const teardown = await module.configure({ journey, surface: surfaceName, fault });
+        teardowns.push(teardown);
+        applied.push(fault.type);
+    }
+    return {
+        applied,
+        unknown,
+        teardown: async () => {
+            for (const teardown of teardowns.reverse()) {
+                await teardown();
+            }
+        }
+    };
+}
+/**
+ * Runs `journey` on every driver in `drivers`, diffing each non-oracle
+ * surface's normalized `server_to_client` stream against the oracle's (the
+ * one driver named `options.oracleName`, default `"kernel"` — §12's "the
+ * kernel surface is the oracle"). `drivers` must include the oracle driver
+ * itself; it both anchors the diff and is reported as its own (trivially
+ * clean) surface.
+ *
+ * `options.faults` (task D1) selects the fault matrix for this run — default
+ * is the journey's own declared `faults` block (`journey.json`), so callers
+ * that don't care about fault injection get the journey's authored behavior
+ * unchanged. Each applicable fault (its `surface` restriction, if any,
+ * matched against the driver about to run) is configured immediately before
+ * that driver's `run()` and torn down immediately after, so faults never
+ * leak across drivers or across `compareJourney` calls.
+ */
+export async function compareJourney(journey, drivers, options = {}) {
+    const oracleName = options.oracleName ?? "kernel";
+    const oracleDriver = drivers.find((d) => d.name === oracleName);
+    if (!oracleDriver) {
+        throw new Error(`compareJourney: no driver named "${oracleName}" among [${drivers
+            .map((d) => d.name)
+            .join(", ")}] — the oracle driver must be included`);
+    }
+    const faults = options.faults ?? journey.manifest.faults;
+    const invariantNames = journey.manifest.assertions.invariants;
+    const checks = invariantNames
+        .map((name) => ({ name, check: INVARIANT_CHECKS[name] }))
+        .filter((c) => !!c.check);
+    const unknownInvariants = invariantNames.filter((name) => !INVARIANT_CHECKS[name]);
+    const issues = [];
+    if (unknownInvariants.length > 0) {
+        issues.push(`journey declares unknown invariant(s), skipped: ${unknownInvariants.join(", ")}`);
+    }
+    const unknownFaultsSeen = new Set();
+    /** Runs one driver with its applicable faults configured/torn down around
+     * the call — shared by the oracle (run once, up front) and every other
+     * surface's loop iteration below. */
+    const runWithFaults = async (driver) => {
+        const { applied, unknown, teardown } = await applyFaults(journey, driver.name, faults);
+        for (const name of unknown)
+            unknownFaultsSeen.add(name);
+        try {
+            const record = await driver.run(journey);
+            return { record, faultsApplied: applied };
+        }
+        finally {
+            await teardown();
+        }
+    };
+    // Run the oracle first — every other surface's diff needs its normalized
+    // record, and running it once (not per-surface) keeps an N-driver compare
+    // to N+1 runs, not 2N.
+    const { record: oracleRecord, faultsApplied: oracleFaultsApplied } = await runWithFaults(oracleDriver);
+    const oracleNormalized = onlyServerToClient(normalizeRunRecord(oracleRecord));
+    const surfaces = [];
+    for (const driver of drivers) {
+        if (driver.supports && !driver.supports(journey)) {
+            surfaces.push({
+                surface: driver.name,
+                ran: false,
+                skipReason: "not applicable to this journey",
+                violations: [],
+                goldens: [],
+                diffVsOracle: null,
+                diffVsOracleEmpty: true,
+                notApplicable: true,
+                faultsApplied: [],
+                ok: true
+            });
+            continue;
+        }
+        let record;
+        let faultsApplied;
+        if (driver.name === oracleDriver.name) {
+            record = oracleRecord;
+            faultsApplied = oracleFaultsApplied;
+        }
+        else {
+            try {
+                const result = await runWithFaults(driver);
+                record = result.record;
+                faultsApplied = result.faultsApplied;
+            }
+            catch (err) {
+                const skipReason = `run failed: ${err instanceof Error ? err.message : String(err)}`;
+                surfaces.push({
+                    surface: driver.name,
+                    ran: false,
+                    skipReason,
+                    violations: [],
+                    goldens: [],
+                    diffVsOracle: null,
+                    diffVsOracleEmpty: false,
+                    notApplicable: false,
+                    faultsApplied: [],
+                    ok: false
+                });
+                issues.push(`${driver.name}: ${skipReason}`);
+                continue;
+            }
+        }
+        const violations = checks.flatMap((c) => c.check(record));
+        // §4's golden fixtures: the only assertion on what the run actually
+        // produced. Every surface is held to them, not just the oracle — a
+        // surface can agree with the oracle frame-for-frame and still be wrong.
+        const goldens = checkGoldens(journey, record, { faultsApplied });
+        const goldenFailures = goldens.flatMap((g) => g.failures);
+        let diff = null;
+        let diffEmpty = true;
+        if (driver.name !== oracleDriver.name) {
+            const normalized = onlyServerToClient(normalizeRunRecord(record));
+            diff = diffNormalizedRecords(oracleNormalized, normalized);
+            diffEmpty = streamDiffIsEmpty(diff);
+        }
+        const ok = violations.length === 0 && diffEmpty && goldenFailures.length === 0;
+        if (violations.length > 0) {
+            issues.push(`${driver.name}: ${violations.length} invariant violation(s)`);
+        }
+        for (const golden of goldens) {
+            if (golden.failures.length === 0)
+                continue;
+            issues.push(`${driver.name}: ${golden.kind} golden mismatch (${golden.failures.length})`);
+        }
+        if (!diffEmpty) {
+            issues.push(`${driver.name}: diverges from ${oracleDriver.name}`);
+        }
+        surfaces.push({
+            surface: driver.name,
+            ran: true,
+            status: record.status,
+            error: record.error,
+            violations,
+            goldens,
+            diffVsOracle: diff,
+            diffVsOracleEmpty: diffEmpty,
+            notApplicable: false,
+            faultsApplied,
+            ok
+        });
+    }
+    const unknownFaults = Array.from(unknownFaultsSeen);
+    if (unknownFaults.length > 0) {
+        issues.push(`fault(s) requested with no registered module: ${unknownFaults.join(", ")}`);
+    }
+    return {
+        journeyId: journey.manifest.name,
+        oracle: oracleDriver.name,
+        unknownInvariants,
+        unknownFaults,
+        surfaces,
+        verdict: { ok: surfaces.every((s) => s.ok) && unknownFaults.length === 0, issues }
+    };
+}
+/** Human-readable rendering of a `CompareReport` for `nodetool reliability run`.
+ * `showDiff` (default `true`) controls whether a diverging surface's full
+ * per-channel stream diff is inlined under its summary line, or just noted —
+ * `nodetool reliability run`'s `--diff` flag maps straight to this. */
+export function formatCompareReport(report, options = {}) {
+    const showDiff = options.showDiff ?? true;
+    const lines = [];
+    lines.push(`journey: ${report.journeyId}  (oracle: ${report.oracle})`);
+    for (const s of report.surfaces) {
+        if (!s.ran) {
+            const mark = s.notApplicable ? "·" : "✗";
+            lines.push(`  ${mark} ${s.surface}: ${s.skipReason}`);
+            continue;
+        }
+        const mark = s.ok ? "✓" : "✗";
+        const bits = [String(s.status)];
+        if (s.error)
+            bits.push(`error: ${s.error}`);
+        if (s.faultsApplied.length > 0)
+            bits.push(`faults: ${s.faultsApplied.join(", ")}`);
+        if (s.violations.length > 0)
+            bits.push(`${s.violations.length} violation(s)`);
+        for (const golden of s.goldens) {
+            if (!golden.checked)
+                bits.push(`${golden.kind} golden skipped`);
+            else if (golden.failures.length > 0) {
+                bits.push(`${golden.kind} golden: ${golden.failures.length} mismatch(es)`);
+            }
+        }
+        if (!s.diffVsOracleEmpty) {
+            bits.push(showDiff ? `diverges from ${report.oracle}` : `diverges from ${report.oracle} (--diff for detail)`);
+        }
+        lines.push(`  ${mark} ${s.surface}: ${bits.join(" — ")}`);
+        for (const v of s.violations) {
+            lines.push(`      [${v.invariant}] ${v.message}`);
+        }
+        for (const golden of s.goldens) {
+            if (!golden.checked && golden.skipReason) {
+                lines.push(`      [${golden.kind}] ${golden.skipReason}`);
+            }
+            for (const failure of golden.failures) {
+                lines.push(`      [${golden.kind}] ${failure}`);
+            }
+        }
+        if (showDiff && !s.diffVsOracleEmpty && s.diffVsOracle) {
+            for (const line of formatStreamDiff(s.diffVsOracle).split("\n")) {
+                lines.push(`      ${line}`);
+            }
+        }
+    }
+    if (report.unknownInvariants.length > 0) {
+        lines.push(`  ! unknown invariant(s) declared: ${report.unknownInvariants.join(", ")}`);
+    }
+    if (report.unknownFaults.length > 0) {
+        lines.push(`  ! unknown fault(s) requested: ${report.unknownFaults.join(", ")}`);
+    }
+    lines.push(report.verdict.ok
+        ? "verdict: OK"
+        : `verdict: FAIL — ${report.verdict.issues.join("; ")}`);
+    return lines.join("\n");
+}
+//# sourceMappingURL=compare.js.map

package/dist/compare.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compare.js","sourceRoot":"","sources":["../src/compare.ts"],"names":[],"mappings":"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"}

package/dist/core/diff.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Per-node-channel stream diff (§4, §12).
+ *
+ * Grown from `packages/cli/src/debug/diff.ts`, which diffs two
+ * `DebugReport`s at the verdict/summary level (issues, token/cost deltas)
+ * for the debug harness's `--watch` mode. This module diffs two
+ * `NormalizedRunRecord`s at the *message* level, one node-channel at a time
+ * — because the actor model legitimately interleaves frames across nodes,
+ * a global stream diff would flag reorderings that are not bugs.
+ * `diffIsEmpty`/`formatDiff` there and `streamDiffIsEmpty`/`formatStreamDiff`
+ * here are deliberately parallel APIs; the debug-harness copy is untouched
+ * so its own tests and callers stay green.
+ */
+import type { NormalizedRunRecord } from "./normalize.js";
+interface ChannelDiffEntry {
+    kind: "added" | "removed" | "changed" | "unchanged";
+    /** Index within the side the entry belongs to (baseline for removed/changed, candidate for added). */
+    baselineMessage?: Record<string, unknown>;
+    candidateMessage?: Record<string, unknown>;
+}
+interface ChannelDiff {
+    channel: string;
+    entries: ChannelDiffEntry[];
+}
+export interface StreamDiff {
+    channels: ChannelDiff[];
+}
+/**
+ * Diffs two normalized records channel by channel. `baseline` is
+ * conventionally the kernel (oracle) surface (§12: "the kernel surface is
+ * the oracle"), but the function is symmetric in shape — either side can be
+ * either record.
+ */
+export declare function diffNormalizedRecords(baseline: NormalizedRunRecord, candidate: NormalizedRunRecord): StreamDiff;
+/** True when no channel diverged — the C1 done-when: a record diffed against itself is empty. */
+export declare function streamDiffIsEmpty(diff: StreamDiff): boolean;
+export declare function formatStreamDiff(diff: StreamDiff): string;
+export {};
+//# sourceMappingURL=diff.d.ts.map

package/dist/core/diff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diff.d.ts","sourceRoot":"","sources":["../../src/core/diff.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAsB,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAG9E,UAAU,gBAAgB;IACxB,IAAI,EAAE,OAAO,GAAG,SAAS,GAAG,SAAS,GAAG,WAAW,CAAC;IACpD,sGAAsG;IACtG,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC1C,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC5C;AAED,UAAU,WAAW;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,gBAAgB,EAAE,CAAC;CAC7B;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,WAAW,EAAE,CAAC;CACzB;AA6ED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,mBAAmB,EAC7B,SAAS,EAAE,mBAAmB,GAC7B,UAAU,CAwBZ;AAED,iGAAiG;AACjG,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAE3D;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAczD"}

package/dist/core/diff.js

@@ -0,0 +1,114 @@
+import { stableStringify } from "./stable-json.js";
+function canonicalKey(message) {
+    return stableStringify(message);
+}
+function groupByChannel(frames) {
+    const groups = new Map();
+    for (const frame of frames) {
+        const group = groups.get(frame.channel);
+        if (group)
+            group.push(frame);
+        else
+            groups.set(frame.channel, [frame]);
+    }
+    return groups;
+}
+/**
+ * Longest-common-subsequence diff over two message sequences (by canonical
+ * JSON equality), yielding `equal`/`remove`/`add` runs in original order.
+ * O(n·m); channels are short (one node's messages in one run), so this is
+ * cheap in practice.
+ */
+function lcsDiff(baseline, candidate) {
+    const bKeys = baseline.map(canonicalKey);
+    const cKeys = candidate.map(canonicalKey);
+    const n = baseline.length;
+    const m = candidate.length;
+    // dp[i][j] = length of LCS of bKeys[i:] and cKeys[j:]
+    const dp = Array.from({ length: n + 1 }, () => new Array(m + 1).fill(0));
+    for (let i = n - 1; i >= 0; i--) {
+        for (let j = m - 1; j >= 0; j--) {
+            dp[i][j] =
+                bKeys[i] === cKeys[j]
+                    ? dp[i + 1][j + 1] + 1
+                    : Math.max(dp[i + 1][j], dp[i][j + 1]);
+        }
+    }
+    const entries = [];
+    let i = 0;
+    let j = 0;
+    while (i < n && j < m) {
+        if (bKeys[i] === cKeys[j]) {
+            entries.push({
+                kind: "unchanged",
+                baselineMessage: baseline[i],
+                candidateMessage: candidate[j]
+            });
+            i++;
+            j++;
+        }
+        else if (dp[i + 1][j] >= dp[i][j + 1]) {
+            entries.push({ kind: "removed", baselineMessage: baseline[i] });
+            i++;
+        }
+        else {
+            entries.push({ kind: "added", candidateMessage: candidate[j] });
+            j++;
+        }
+    }
+    while (i < n) {
+        entries.push({ kind: "removed", baselineMessage: baseline[i] });
+        i++;
+    }
+    while (j < m) {
+        entries.push({ kind: "added", candidateMessage: candidate[j] });
+        j++;
+    }
+    return entries;
+}
+/**
+ * Diffs two normalized records channel by channel. `baseline` is
+ * conventionally the kernel (oracle) surface (§12: "the kernel surface is
+ * the oracle"), but the function is symmetric in shape — either side can be
+ * either record.
+ */
+export function diffNormalizedRecords(baseline, candidate) {
+    const baselineGroups = groupByChannel(baseline.frames);
+    const candidateGroups = groupByChannel(candidate.frames);
+    const channels = new Set([
+        ...baselineGroups.keys(),
+        ...candidateGroups.keys()
+    ]);
+    const result = [];
+    for (const channel of Array.from(channels).sort()) {
+        const baselineMessages = (baselineGroups.get(channel) ?? []).map((f) => f.message);
+        const candidateMessages = (candidateGroups.get(channel) ?? []).map((f) => f.message);
+        const entries = lcsDiff(baselineMessages, candidateMessages).filter((e) => e.kind !== "unchanged");
+        if (entries.length > 0) {
+            result.push({ channel, entries });
+        }
+    }
+    return { channels: result };
+}
+/** True when no channel diverged — the C1 done-when: a record diffed against itself is empty. */
+export function streamDiffIsEmpty(diff) {
+    return diff.channels.length === 0;
+}
+export function formatStreamDiff(diff) {
+    if (streamDiffIsEmpty(diff))
+        return "No divergence.";
+    const lines = [];
+    for (const channel of diff.channels) {
+        lines.push(`channel ${channel.channel}:`);
+        for (const entry of channel.entries) {
+            if (entry.kind === "removed") {
+                lines.push(`  - ${canonicalKey(entry.baselineMessage)}`);
+            }
+            else if (entry.kind === "added") {
+                lines.push(`  + ${canonicalKey(entry.candidateMessage)}`);
+            }
+        }
+    }
+    return lines.join("\n");
+}
+//# sourceMappingURL=diff.js.map

package/dist/core/diff.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diff.js","sourceRoot":"","sources":["../../src/core/diff.ts"],"names":[],"mappings":"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"}

package/dist/core/golden.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Golden-fixture assertions (§4): the `expected/outputs.json` and
+ * `expected/stream.shape.json` a journey opts into via
+ * `assertions.outputs` / `assertions.streamShape`.
+ *
+ * These are the only checks that pin down *what a run produced*. Invariants
+ * describe stream shape and lifecycle; the cross-surface diff only says the
+ * surfaces agree — both pass happily when every surface returns the same
+ * wrong answer. A journey that declares a golden must have it compared, or
+ * declaring it means nothing.
+ */
+import type { Journey } from "./journey.js";
+import type { RunRecord } from "./record.js";
+import { type NormalizedRunRecord } from "./normalize.js";
+/** One golden entry, matching `expected/stream.shape.json`'s element shape. */
+interface StreamShapeEntry {
+    channel: string;
+    message: Record<string, unknown>;
+}
+export interface GoldenCheckResult {
+    kind: "outputs" | "streamShape";
+    /** False when the journey didn't declare it, or the run couldn't be compared. */
+    checked: boolean;
+    /** Why it wasn't checked. Only set when `!checked`. */
+    skipReason?: string;
+    /** Human-readable mismatches; empty when the golden matched. */
+    failures: string[];
+}
+/**
+ * A run's terminal outputs, keyed the way `expected/outputs.json` is: by an
+ * Output node's public `output_name`, last value wins (a node that streams
+ * several values ends on the one a client would display).
+ */
+export declare function terminalOutputsOf(record: RunRecord): Record<string, unknown>;
+/** A run's normalized `server_to_client` stream in golden-fixture shape. */
+export declare function streamShapeOf(record: RunRecord, normalized?: NormalizedRunRecord): StreamShapeEntry[];
+/**
+ * Runs the golden comparisons a journey declared against one surface's record.
+ *
+ * Faulted runs are skipped rather than compared: a golden describes what the
+ * journey produces when nothing is broken, and every fault journey that opts
+ * into outputs (`host-disk-full-write`, `python-node-workflow`) declares its
+ * faults precisely because the run is *supposed* to fail under them. The skip
+ * is reported, never silent.
+ */
+export declare function checkGoldens(journey: Journey, record: RunRecord, options?: {
+    faultsApplied?: readonly string[];
+}): GoldenCheckResult[];
+export {};
+//# sourceMappingURL=golden.d.ts.map

package/dist/core/golden.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"golden.d.ts","sourceRoot":"","sources":["../../src/core/golden.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAsB,KAAK,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAG9E,+EAA+E;AAC/E,UAAU,gBAAgB;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,SAAS,GAAG,aAAa,CAAC;IAChC,iFAAiF;IACjF,OAAO,EAAE,OAAO,CAAC;IACjB,uDAAuD;IACvD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gEAAgE;IAChE,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAKD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAW5E;AAED,4EAA4E;AAC5E,wBAAgB,aAAa,CAC3B,MAAM,EAAE,SAAS,EACjB,UAAU,GAAE,mBAAgD,GAC3D,gBAAgB,EAAE,CAIpB;AAyFD;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,SAAS,EACjB,OAAO,GAAE;IAAE,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAAO,GAClD,iBAAiB,EAAE,CA0CrB"}

package/dist/core/golden.js

@@ -0,0 +1,150 @@
+import { normalizeRunRecord } from "./normalize.js";
+import { stableStringify } from "./stable-json.js";
+/** Max mismatching stream-shape entries reported before truncating. */
+const MAX_REPORTED_ENTRIES = 10;
+/**
+ * A run's terminal outputs, keyed the way `expected/outputs.json` is: by an
+ * Output node's public `output_name`, last value wins (a node that streams
+ * several values ends on the one a client would display).
+ */
+export function terminalOutputsOf(record) {
+    const outputs = {};
+    for (const frame of record.frames) {
+        if (frame.direction !== "server_to_client")
+            continue;
+        const message = frame.message;
+        if (message["type"] !== "output_update")
+            continue;
+        const name = message["output_name"];
+        if (typeof name !== "string")
+            continue;
+        outputs[name] = message["value"];
+    }
+    return outputs;
+}
+/** A run's normalized `server_to_client` stream in golden-fixture shape. */
+export function streamShapeOf(record, normalized = normalizeRunRecord(record)) {
+    return normalized.frames
+        .filter((frame) => frame.direction === "server_to_client")
+        .map((frame) => ({ channel: frame.channel, message: frame.message }));
+}
+function compareOutputs(expected, record) {
+    const actual = terminalOutputsOf(record);
+    const expectedRecord = (expected ?? {});
+    const failures = [];
+    const keys = new Set([
+        ...Object.keys(expectedRecord),
+        ...Object.keys(actual)
+    ]);
+    for (const key of Array.from(keys).sort()) {
+        const want = stableStringify(expectedRecord[key]);
+        const got = stableStringify(actual[key]);
+        if (want === got)
+            continue;
+        if (!(key in expectedRecord)) {
+            failures.push(`unexpected output "${key}": ${got}`);
+        }
+        else if (!(key in actual)) {
+            failures.push(`missing output "${key}" (expected ${want})`);
+        }
+        else {
+            failures.push(`output "${key}": expected ${want}, got ${got}`);
+        }
+    }
+    return failures;
+}
+function byChannel(entries) {
+    const groups = new Map();
+    for (const entry of entries) {
+        const serialized = stableStringify(entry.message);
+        const group = groups.get(entry.channel);
+        if (group)
+            group.push(serialized);
+        else
+            groups.set(entry.channel, [serialized]);
+    }
+    return groups;
+}
+/**
+ * Compared per node-channel, in channel order — the same rule the
+ * cross-surface diff uses (§4: "per-node-channel, not globally"). The actor
+ * model legitimately interleaves frames across nodes run to run, so a global
+ * index-wise comparison would flag reorderings that are not regressions;
+ * within one channel the order is the node's own and is asserted exactly.
+ *
+ * One limit is inherited from normalization: id placeholders are numbered by
+ * order of first sight (`IdMapper`), so a run where a *different* node emits
+ * first renumbers them and mismatches. The cross-surface diff has the same
+ * property; journeys whose node start order isn't structurally fixed should
+ * not declare `streamShape`.
+ */
+function compareStreamShape(expected, record, normalized) {
+    if (!Array.isArray(expected)) {
+        return ["expected/stream.shape.json is not an array of {channel, message}"];
+    }
+    const golden = byChannel(expected);
+    const actual = byChannel(streamShapeOf(record, normalized));
+    const failures = [];
+    const channels = Array.from(new Set([...golden.keys(), ...actual.keys()])).sort();
+    for (const channel of channels) {
+        const want = golden.get(channel) ?? [];
+        const got = actual.get(channel) ?? [];
+        for (let i = 0; i < Math.max(want.length, got.length); i++) {
+            if (failures.length >= MAX_REPORTED_ENTRIES) {
+                failures.push("… further mismatches not reported");
+                return failures;
+            }
+            if (want[i] === got[i])
+                continue;
+            if (want[i] === undefined) {
+                failures.push(`${channel}[${i}]: unexpected ${got[i]}`);
+            }
+            else if (got[i] === undefined) {
+                failures.push(`${channel}[${i}]: missing ${want[i]}`);
+            }
+            else {
+                failures.push(`${channel}[${i}]: expected ${want[i]}, got ${got[i]}`);
+            }
+        }
+    }
+    return failures;
+}
+/**
+ * Runs the golden comparisons a journey declared against one surface's record.
+ *
+ * Faulted runs are skipped rather than compared: a golden describes what the
+ * journey produces when nothing is broken, and every fault journey that opts
+ * into outputs (`host-disk-full-write`, `python-node-workflow`) declares its
+ * faults precisely because the run is *supposed* to fail under them. The skip
+ * is reported, never silent.
+ */
+export function checkGoldens(journey, record, options = {}) {
+    const { assertions } = journey.manifest;
+    const faults = options.faultsApplied ?? [];
+    const results = [];
+    const skipReason = faults.length > 0
+        ? `not compared under fault(s): ${faults.join(", ")}`
+        : undefined;
+    // Normalize once — both goldens read from the same view.
+    const normalized = assertions.streamShape ? normalizeRunRecord(record) : null;
+    if (assertions.outputs) {
+        results.push(skipReason
+            ? { kind: "outputs", checked: false, skipReason, failures: [] }
+            : {
+                kind: "outputs",
+                checked: true,
+                failures: compareOutputs(journey.expected.outputs, record)
+            });
+    }
+    if (assertions.streamShape) {
+        results.push(skipReason
+            ? { kind: "streamShape", checked: false, skipReason, failures: [] }
+            : {
+                kind: "streamShape",
+                checked: true,
+                failures: compareStreamShape(journey.expected.streamShape, record, normalized)
+            });
+    }
+    return results;
+}
+//# sourceMappingURL=golden.js.map