@nodetool-ai/reliability-harness 0.8.1

package/dist/core/normalize.js

@@ -0,0 +1,182 @@
+/** Field names (anywhere in a message, at any depth) treated as ids that get
+ * remapped to a stable `<class:N>` placeholder, keyed by their remap class. */
+export const ID_FIELD_CLASSES = {
+    job_id: "job",
+    workflow_id: "workflow",
+    node_id: "node",
+    edge_id: "edge",
+    provider_request_id: "provider-request"
+};
+/** Field names replaced wholesale with `<ts>` — the value never matters, only presence. */
+export const TIMESTAMP_FIELDS = [
+    "timestamp",
+    "ts",
+    "created_at",
+    "generatedAt"
+];
+/** Field names replaced wholesale with `<duration>`. */
+export const DURATION_FIELDS = [
+    "duration",
+    "durationMs",
+    "duration_ms"
+];
+/**
+ * Field values treated as interchangeable "nothing here" signals (added by
+ * C2): a node with zero declared `@prop` fields (the harness's own fixture
+ * nodes in `drivers/fixture-nodes.ts` — no shipped node has none) serializes
+ * its `properties` as `null` on the raw kernel stream but as `{}` once
+ * relayed through the ws-server. Canonicalizing `null` to `{}` for these
+ * keys make the two the same "no properties" value.
+ */
+export const NULLABLE_OBJECT_FIELDS = ["properties"];
+/**
+ * Top-level fields the WebSocket transport stamps on a frame so a dropped
+ * client can replay what it missed (`job-run-registry.ts`,
+ * `chat-turn-registry.ts`). They describe the delivery, not the run, and the
+ * raw kernel stream has no counterpart — dropped from the comparison view so
+ * a resumable surface still diffs clean against a non-resumable one.
+ */
+export const TRANSPORT_ONLY_FIELDS = [
+    "job_seq",
+    "chat_seq"
+];
+/**
+ * Node type prefixes whose `node_update`/`generation_complete` frames are
+ * dropped from comparison (added by C2). This mirrors a real, documented,
+ * intentional ws-server behavior (`websocket-client-session.ts`: "Skip
+ * messages for constant/input nodes — they produce trivial outputs that
+ * don't need to be relayed to the frontend") that the raw kernel stream has
+ * no equivalent for — the kernel emits every node's lifecycle unconditionally.
+ * Normalizing both sides down to what a real frontend actually receives is
+ * the honest comparison; dropping the frames here (not filtering in
+ * `diff.ts`) keeps the diff itself surface-agnostic.
+ */
+export const TRIVIAL_NODE_TYPE_PREFIXES = [
+    "nodetool.constant.",
+    "nodetool.input."
+];
+const TRIVIAL_FRAME_MESSAGE_TYPES = new Set([
+    "node_update",
+    "generation_complete"
+]);
+/** True when `frame` is one `TRIVIAL_NODE_TYPE_PREFIXES` says to drop. */
+function isTrivialNodeFrame(message) {
+    if (!TRIVIAL_FRAME_MESSAGE_TYPES.has(String(message["type"])))
+        return false;
+    const nodeType = message["node_type"];
+    return (typeof nodeType === "string" &&
+        TRIVIAL_NODE_TYPE_PREFIXES.some((prefix) => nodeType.startsWith(prefix)));
+}
+/** Asset references: `asset://…`, an `/assets/…` URL, or an inline data URI. */
+const ASSET_URL_PATTERN = /^(asset:\/\/|https?:\/\/[^\s]+\/assets\/|data:[^;]+;base64,)/;
+/**
+ * Assigns each distinct original id value a stable, order-of-first-sight
+ * placeholder within one normalization pass. Two records normalized
+ * independently line up as long as ids first appear in the same relative
+ * order — which is exactly the "same journey, different surface" case this
+ * exists for.
+ */
+export class IdMapper {
+    maps = new Map();
+    placeholderFor(cls, value) {
+        let map = this.maps.get(cls);
+        if (!map) {
+            map = new Map();
+            this.maps.set(cls, map);
+        }
+        let placeholder = map.get(value);
+        if (!placeholder) {
+            placeholder = `<${cls}:${map.size}>`;
+            map.set(value, placeholder);
+        }
+        return placeholder;
+    }
+}
+function normalizeValue(value, key, mapper) {
+    if (key && key in ID_FIELD_CLASSES && typeof value === "string") {
+        return mapper.placeholderFor(ID_FIELD_CLASSES[key], value);
+    }
+    if (key && TIMESTAMP_FIELDS.includes(key)) {
+        return value == null ? value : "<ts>";
+    }
+    if (key && DURATION_FIELDS.includes(key)) {
+        return value == null ? value : "<duration>";
+    }
+    if (key && NULLABLE_OBJECT_FIELDS.includes(key) && value === null) {
+        return {};
+    }
+    if (typeof value === "string" && ASSET_URL_PATTERN.test(value)) {
+        return "<asset>";
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => normalizeValue(item, null, mapper));
+    }
+    if (value !== null && typeof value === "object") {
+        const out = {};
+        for (const [k, v] of Object.entries(value)) {
+            out[k] = normalizeValue(v, k, mapper);
+        }
+        return out;
+    }
+    return value;
+}
+/**
+ * `job_update`'s optional `result` field (added by C2): the ws-server relay
+ * appends an "authoritative terminal snapshot" `job_update` carrying the
+ * full `result.outputs` whenever the relayed kernel terminal frame lacked
+ * one (`websocket-client-session.ts`'s `terminalWithResultSeen` check) — the
+ * kernel's own `job_update` emissions (`runner.ts`) never set `result` at
+ * all. Dropped only on `job_update` (not `node_update`, whose own `result`
+ * is real per-node data the outputs assertion depends on).
+ */
+function stripJobUpdateResult(message) {
+    if (message["type"] !== "job_update" || !("result" in message))
+        return message;
+    const rest = { ...message };
+    delete rest["result"];
+    return rest;
+}
+/** Normalizes one message (a frame's payload) in place-equivalent (returns a new object). */
+export function normalizeMessage(message, mapper) {
+    const payload = { ...stripJobUpdateResult(message) };
+    for (const field of TRANSPORT_ONLY_FIELDS)
+        delete payload[field];
+    return normalizeValue(payload, null, mapper);
+}
+/**
+ * Normalizes a whole `RunRecord`: every frame's message, plus the record's
+ * own `jobId`/`workflowId` (through the same mapper, so they match the
+ * placeholders used inside the frames). `startedAt`/`finishedAt`/`durationMs`
+ * are dropped — wall-clock fields carry no comparison value once
+ * normalized, per §4.
+ */
+export function normalizeRunRecord(record, mapper = new IdMapper()) {
+    const frames = record.frames
+        // Frames a driver tagged as its surface's own documented redundancy
+        // (`RunFrame.redundant`) have no counterpart on the kernel's raw stream,
+        // so they are dropped here — in the comparison view only. The record
+        // itself keeps them, and the invariants read the record.
+        .filter((frame) => frame.redundant === undefined)
+        .filter((frame) => !isTrivialNodeFrame(frame.message))
+        .map((frame) => ({
+        seq: frame.seq,
+        channel: frame.channel,
+        direction: frame.direction,
+        surface: frame.surface,
+        message: normalizeMessage(frame.message, mapper)
+    }));
+    return {
+        journeyId: record.journeyId,
+        surface: record.surface,
+        status: record.status,
+        error: record.error,
+        jobId: record.jobId !== null
+            ? mapper.placeholderFor(ID_FIELD_CLASSES.job_id, record.jobId)
+            : null,
+        workflowId: record.workflowId !== null
+            ? mapper.placeholderFor(ID_FIELD_CLASSES.workflow_id, record.workflowId)
+            : null,
+        frames
+    };
+}
+//# sourceMappingURL=normalize.js.map

package/dist/core/normalize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize.js","sourceRoot":"","sources":["../../src/core/normalize.ts"],"names":[],"mappings":"AAaA;+EAC+E;AAC/E,MAAM,CAAC,MAAM,gBAAgB,GAAqC;IAChE,MAAM,EAAE,KAAK;IACb,WAAW,EAAE,UAAU;IACvB,OAAO,EAAE,MAAM;IACf,OAAO,EAAE,MAAM;IACf,mBAAmB,EAAE,kBAAkB;CACxC,CAAC;AAEF,2FAA2F;AAC3F,MAAM,CAAC,MAAM,gBAAgB,GAAsB;IACjD,WAAW;IACX,IAAI;IACJ,YAAY;IACZ,aAAa;CACd,CAAC;AAEF,wDAAwD;AACxD,MAAM,CAAC,MAAM,eAAe,GAAsB;IAChD,UAAU;IACV,YAAY;IACZ,aAAa;CACd,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAsB,CAAC,YAAY,CAAC,CAAC;AAExE;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAsB;IACtD,SAAS;IACT,UAAU;CACX,CAAC;AAEF;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAsB;IAC3D,oBAAoB;IACpB,iBAAiB;CAClB,CAAC;AAEF,MAAM,2BAA2B,GAAwB,IAAI,GAAG,CAAC;IAC/D,aAAa;IACb,qBAAqB;CACtB,CAAC,CAAC;AAEH,0EAA0E;AAC1E,SAAS,kBAAkB,CAAC,OAAgC;IAC1D,IAAI,CAAC,2BAA2B,CAAC,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;QAAE,OAAO,KAAK,CAAC;IAC5E,MAAM,QAAQ,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IACtC,OAAO,CACL,OAAO,QAAQ,KAAK,QAAQ;QAC5B,0BAA0B,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,QAAQ,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CACzE,CAAC;AACJ,CAAC;AAED,gFAAgF;AAChF,MAAM,iBAAiB,GACrB,8DAA8D,CAAC;AAEjE;;;;;;GAMG;AACH,MAAM,OAAO,QAAQ;IACF,IAAI,GAAG,IAAI,GAAG,EAA+B,CAAC;IAE/D,cAAc,CAAC,GAAW,EAAE,KAAa;QACvC,IAAI,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC7B,IAAI,CAAC,GAAG,EAAE,CAAC;YACT,GAAG,GAAG,IAAI,GAAG,EAAE,CAAC;YAChB,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;QAC1B,CAAC;QACD,IAAI,WAAW,GAAG,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACjC,IAAI,CAAC,WAAW,EAAE,CAAC;YACjB,WAAW,GAAG,IAAI,GAAG,IAAI,GAAG,CAAC,IAAI,GAAG,CAAC;YACrC,GAAG,CAAC,GAAG,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC;QAC9B,CAAC;QACD,OAAO,WAAW,CAAC;IACrB,CAAC;CACF;AAED,SAAS,cAAc,CAAC,KAAc,EAAE,GAAkB,EAAE,MAAgB;IAC1E,IAAI,GAAG,IAAI,GAAG,IAAI,gBAAgB,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAChE,OAAO,MAAM,CAAC,cAAc,CAAC,gBAAgB,CAAC,GAAG,CAAC,EAAE,KAAK,CAAC,CAAC;IAC7D,CAAC;IACD,IAAI,GAAG,IAAI,gBAAgB,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QAC1C,OAAO,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC;IACxC,CAAC;IACD,IAAI,GAAG,IAAI,eAAe,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QACzC,OAAO,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,YAAY,CAAC;IAC9C,CAAC;IACD,IAAI,GAAG,IAAI,sBAAsB,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QAClE,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,iBAAiB,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QAC/D,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,cAAc,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;IACjE,CAAC;IACD,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAChD,MAAM,GAAG,GAA4B,EAAE,CAAC;QACxC,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAgC,CAAC,EAAE,CAAC;YACtE,GAAG,CAAC,CAAC,CAAC,GAAG,cAAc,CAAC,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC;QACxC,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;GAQG;AACH,SAAS,oBAAoB,CAAC,OAAgC;IAC5D,IAAI,OAAO,CAAC,MAAM,CAAC,KAAK,YAAY,IAAI,CAAC,CAAC,QAAQ,IAAI,OAAO,CAAC;QAAE,OAAO,OAAO,CAAC;IAC/E,MAAM,IAAI,GAAG,EAAE,GAAG,OAAO,EAAE,CAAC;IAC5B,OAAO,IAAI,CAAC,QAAQ,CAAC,CAAC;IACtB,OAAO,IAAI,CAAC;AACd,CAAC;AAED,6FAA6F;AAC7F,MAAM,UAAU,gBAAgB,CAC9B,OAAgC,EAChC,MAAgB;IAEhB,MAAM,OAAO,GAAG,EAAE,GAAG,oBAAoB,CAAC,OAAO,CAAC,EAAE,CAAC;IACrD,KAAK,MAAM,KAAK,IAAI,qBAAqB;QAAE,OAAO,OAAO,CAAC,KAAK,CAAC,CAAC;IACjE,OAAO,cAAc,CAAC,OAAO,EAAE,IAAI,EAAE,MAAM,CAA4B,CAAC;AAC1E,CAAC;AAoBD;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAChC,MAAiB,EACjB,MAAM,GAAa,IAAI,QAAQ,EAAE;IAEjC,MAAM,MAAM,GAAyB,MAAM,CAAC,MAAM;QAChD,oEAAoE;QACpE,yEAAyE;QACzE,qEAAqE;QACrE,yDAAyD;SACxD,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,SAAS,KAAK,SAAS,CAAC;SAChD,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,kBAAkB,CAAC,KAAK,CAAC,OAAkC,CAAC,CAAC;SAChF,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QACf,GAAG,EAAE,KAAK,CAAC,GAAG;QACd,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,SAAS,EAAE,KAAK,CAAC,SAAS;QAC1B,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,OAAO,EAAE,gBAAgB,CAAC,KAAK,CAAC,OAAkC,EAAE,MAAM,CAAC;KAC5E,CAAC,CAAC,CAAC;IAEN,OAAO;QACL,SAAS,EAAE,MAAM,CAAC,SAAS;QAC3B,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,KAAK,EACH,MAAM,CAAC,KAAK,KAAK,IAAI;YACnB,CAAC,CAAC,MAAM,CAAC,cAAc,CAAC,gBAAgB,CAAC,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC;YAC9D,CAAC,CAAC,IAAI;QACV,UAAU,EACR,MAAM,CAAC,UAAU,KAAK,IAAI;YACxB,CAAC,CAAC,MAAM,CAAC,cAAc,CAAC,gBAAgB,CAAC,WAAW,EAAE,MAAM,CAAC,UAAU,CAAC;YACxE,CAAC,CAAC,IAAI;QACV,MAAM;KACP,CAAC;AACJ,CAAC"}

package/dist/core/record.d.ts

@@ -0,0 +1,160 @@
+/**
+ * `RunRecord`: the universal currency of the reliability harness (§12).
+ *
+ * Every driver — kernel, ws-server, cli, browser, app-headless, packaged,
+ * electron — produces the same shape: every frame, both directions,
+ * timestamped, surface-tagged. It is a superset of two existing shapes:
+ *
+ * - the debug harness's bundle (`packages/cli/src/debug/`: `report.json` +
+ *   `server/messages.jsonl`) — one direction (server → client), no per-frame
+ *   timestamps, one `ProcessingMessage` per JSONL line;
+ * - the e2e_runner's `record.json` (`web/src/e2e_runner/types.ts`'s
+ *   `RunRecord`) — one direction, a flat `events: WsEvent[]` array plus
+ *   distilled `outputs`/`logs`/`nodeIO`.
+ *
+ * Invariants and diffs (§6, `diff.ts`) are pure functions over this shape,
+ * so they run identically whether the record came from a live driver run or
+ * from a user's field debug bundle.
+ */
+import type { ProcessingMessage } from "@nodetool-ai/protocol";
+/** Which side of the wire a frame crossed. Debug bundles and today's
+ * e2e_runner records only ever carry `server_to_client`; a real ws-server
+ * driver also records `client_to_server` control frames (run/cancel/
+ * stream_input), which is what makes the record a strict superset. */
+export type FrameDirection = "server_to_client" | "client_to_server";
+/** A single frame in a run's stream, normalized to one shared shape. */
+export interface RunFrame {
+    /** 0-based arrival order within this record — the tiebreaker when two
+     * frames share a timestamp, and the only ordering source for records
+     * whose origin (e.g. a JSONL bundle) never carried per-frame timestamps. */
+    seq: number;
+    /** Capture time, epoch ms. Synthetic (derived from `seq`) when the source
+     * record didn't preserve a real one — see `tsSource`. */
+    ts: number;
+    /** Whether `ts` is a real capture time or a synthetic ordering stand-in. */
+    tsSource: "captured" | "synthetic";
+    direction: FrameDirection;
+    /** Driver/converter that produced this frame (e.g. "kernel", "ws-server", "debug-bundle"). */
+    surface: string;
+    /** Per-node-channel diff key: `node:<id>` when the message names a node,
+     * `job` for job-level frames, `control` otherwise (§4's "per-node-channel,
+     * not globally" comparison). */
+    channel: string;
+    /** The raw frame payload. A `ProcessingMessage` for server→client frames;
+     * an untyped record for client→server control frames (run/cancel/…). */
+    message: ProcessingMessage | Record<string, unknown>;
+    /**
+     * Set when a driver recognizes this frame as its own surface's *documented*
+     * redundancy — a repeat of information an earlier frame already carried,
+     * emitted for client convenience (the ws-server's eager "running" ack and
+     * its authoritative terminal snapshot; see `drivers/ws-server.ts`). The
+     * value is the reason tag.
+     *
+     * The frame is still recorded: dropping repeats outright, as this driver
+     * used to, makes "exactly one terminal job_update" unfalsifiable on the one
+     * surface that has a wire. Cross-surface normalization skips tagged frames
+     * (they have no kernel counterpart), and the invariants that assert
+     * uniqueness discount them — so an *undocumented* duplicate, which is never
+     * tagged, still fails both.
+     */
+    redundant?: string;
+}
+/**
+ * Point-in-time snapshot of the leak-accounting counters §6's "Cleanup and
+ * leaks" section names: zero live actors, zero pending control responses,
+ * zero timers beyond the trigger timeout, zero pending Python-bridge
+ * requests, and WS slot accounting (`activeJobs`/`startingJobs`) back to
+ * empty. `at` distinguishes a baseline snapshot (taken before the run, so a
+ * driver can express "returned to its starting count" rather than
+ * "reached exactly zero" for a long-lived process) from the post-run one
+ * `leaks.ts` actually asserts against.
+ */
+export interface ResourceCounterSnapshot {
+    at: "before" | "after";
+    liveActors: number;
+    pendingControlResponses: number;
+    pendingTimers: number;
+    pythonBridgePendingRequests: number;
+    activeJobs: number;
+    startingJobs: number;
+}
+/**
+ * One recorded client `WebSocketManager` state transition (§6 "State
+ * transitions", `WebSocketManager.ts:95`'s `STATE_TRANSITIONS`). `action` and
+ * `from`/`to` mirror that table's shape so `state-machine.ts` can replay the
+ * sequence against the declared machine.
+ */
+export interface RecordedTransition {
+    /** Ordering key — a frame `seq` this transition is anchored to, or a plain
+     * incrementing index when the driver has no frame to anchor on. */
+    at: number;
+    action: string;
+    from: string;
+    to: string;
+}
+export interface RunRecord {
+    /** Journey this record was captured for, when known. */
+    journeyId?: string;
+    /** The driver/surface that produced this record. */
+    surface: string;
+    jobId: string | null;
+    workflowId: string | null;
+    /** Epoch ms; null when the source never recorded a start. */
+    startedAt: number | null;
+    finishedAt: number | null;
+    durationMs: number | null;
+    /** Terminal status ("completed" | "failed" | "cancelled" | …), or "unknown". */
+    status: string;
+    error: string | null;
+    params: Record<string, unknown>;
+    frames: RunFrame[];
+    /**
+     * Leak-accounting snapshots (§6), additive over C1's shape. Absent when the
+     * driver that produced this record doesn't instrument these counters (e.g.
+     * a debug-bundle conversion) — `leaks.ts` reports no violations rather than
+     * treating absence itself as a leak.
+     */
+    resourceCounters?: ResourceCounterSnapshot[];
+    /**
+     * Client `WebSocketManager` transitions observed during this run (§6),
+     * additive over C1's shape. Absent when the driver never touches a real
+     * client connection (e.g. the kernel driver) — `state-machine.ts` reports
+     * no violations rather than treating absence itself as a violation.
+     */
+    transitions?: RecordedTransition[];
+}
+/** Per-node-channel diff key for a message (§4, §12). */
+export declare function channelForMessage(message: ProcessingMessage | Record<string, unknown>): string;
+/** Builds one `RunFrame`, filling in `channel` and a synthetic `ts` when none is given. */
+export declare function makeFrame(seq: number, surface: string, direction: FrameDirection, message: ProcessingMessage | Record<string, unknown>, ts?: number): RunFrame;
+/** Minimal shape the debug harness's `report.json` needs to expose for conversion. */
+interface DebugBundleReportLike {
+    target?: {
+        workflowId?: string | null;
+    } | null;
+    server?: {
+        status?: string;
+        error?: string | null;
+        durationMs?: number | null;
+    } | null;
+}
+/**
+ * Converts a decoded debug-bundle `report.json` + its `server/messages.jsonl`
+ * lines into a `RunRecord`. Pure — the IO (reading the bundle directory off
+ * disk) lives in {@link loadRunRecordFromDebugBundle}, so this half is
+ * unit-testable without touching the filesystem.
+ */
+export declare function runRecordFromDebugBundle(report: DebugBundleReportLike, messages: Array<ProcessingMessage | Record<string, unknown>>, options?: {
+    journeyId?: string;
+    startedAt?: number;
+}): RunRecord;
+/**
+ * Reads a debug bundle directory (`report.json` + `server/messages.jsonl`)
+ * off disk and converts it into a `RunRecord`. This is the "debug bundle
+ * round-trips into a RunRecord" half of C1's done-when.
+ */
+export declare function loadRunRecordFromDebugBundle(bundleDir: string, options?: {
+    journeyId?: string;
+}): Promise<RunRecord>;
+export {};
+//# sourceMappingURL=record.d.ts.map

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

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

package/dist/core/record.js

@@ -0,0 +1,74 @@
+function messageNodeId(message) {
+    const nodeId = message["node_id"];
+    return typeof nodeId === "string" && nodeId.length > 0 ? nodeId : null;
+}
+/** Per-node-channel diff key for a message (§4, §12). */
+export function channelForMessage(message) {
+    const record = message;
+    const nodeId = messageNodeId(record);
+    if (nodeId)
+        return `node:${nodeId}`;
+    if (record["type"] === "job_update")
+        return "job";
+    return "control";
+}
+/** Builds one `RunFrame`, filling in `channel` and a synthetic `ts` when none is given. */
+export function makeFrame(seq, surface, direction, message, ts) {
+    return {
+        seq,
+        ts: ts ?? seq,
+        tsSource: ts === undefined ? "synthetic" : "captured",
+        direction,
+        surface,
+        channel: channelForMessage(message),
+        message
+    };
+}
+/**
+ * Converts a decoded debug-bundle `report.json` + its `server/messages.jsonl`
+ * lines into a `RunRecord`. Pure — the IO (reading the bundle directory off
+ * disk) lives in {@link loadRunRecordFromDebugBundle}, so this half is
+ * unit-testable without touching the filesystem.
+ */
+export function runRecordFromDebugBundle(report, messages, options = {}) {
+    const startedAt = options.startedAt ?? 0;
+    const frames = messages.map((message, index) => makeFrame(index, "debug-bundle", "server_to_client", message, startedAt + index));
+    const jobUpdates = frames.filter((f) => f.channel === "job");
+    const firstJob = jobUpdates[0]?.message;
+    const lastJob = jobUpdates[jobUpdates.length - 1]?.message;
+    return {
+        journeyId: options.journeyId,
+        surface: "debug-bundle",
+        jobId: firstJob?.["job_id"] ??
+            lastJob?.["job_id"] ??
+            null,
+        workflowId: report.target?.workflowId ?? null,
+        startedAt: frames.length > 0 ? startedAt : null,
+        finishedAt: frames.length > 0 ? startedAt + (frames.length - 1) : null,
+        durationMs: report.server?.durationMs ?? null,
+        status: report.server?.status ?? "unknown",
+        error: report.server?.error ?? null,
+        params: {},
+        frames
+    };
+}
+/**
+ * Reads a debug bundle directory (`report.json` + `server/messages.jsonl`)
+ * off disk and converts it into a `RunRecord`. This is the "debug bundle
+ * round-trips into a RunRecord" half of C1's done-when.
+ */
+export async function loadRunRecordFromDebugBundle(bundleDir, options = {}) {
+    const { readFile } = await import("node:fs/promises");
+    const { join } = await import("node:path");
+    const reportRaw = await readFile(join(bundleDir, "report.json"), "utf8");
+    const report = JSON.parse(reportRaw);
+    const messagesFile = join(bundleDir, "server", "messages.jsonl");
+    const messagesRaw = await readFile(messagesFile, "utf8");
+    const messages = messagesRaw
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0)
+        .map((line) => JSON.parse(line));
+    return runRecordFromDebugBundle(report, messages, options);
+}
+//# sourceMappingURL=record.js.map

package/dist/core/record.js.map

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

package/dist/core/stable-json.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Order-independent JSON serialization, recursive at every depth — the
+ * canonical form both the stream diff (`diff.ts`) and the golden comparisons
+ * (`golden.ts`) key messages by.
+ *
+ * `JSON.stringify(value, keyArray)` cannot do this: its array form is a key
+ * *whitelist* applied at every nesting level, so a top-level key list erases
+ * every nested object's contents — `{result: {output: "A"}}` and
+ * `{result: {output: "B"}}` both serialize to `{"result":{}}`, and output,
+ * metadata, and nested error divergences compare equal.
+ */
+export declare function stableStringify(value: unknown): string;
+//# sourceMappingURL=stable-json.d.ts.map

package/dist/core/stable-json.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stable-json.d.ts","sourceRoot":"","sources":["../../src/core/stable-json.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CActD"}

package/dist/core/stable-json.js

@@ -0,0 +1,28 @@
+/**
+ * Order-independent JSON serialization, recursive at every depth — the
+ * canonical form both the stream diff (`diff.ts`) and the golden comparisons
+ * (`golden.ts`) key messages by.
+ *
+ * `JSON.stringify(value, keyArray)` cannot do this: its array form is a key
+ * *whitelist* applied at every nesting level, so a top-level key list erases
+ * every nested object's contents — `{result: {output: "A"}}` and
+ * `{result: {output: "B"}}` both serialize to `{"result":{}}`, and output,
+ * metadata, and nested error divergences compare equal.
+ */
+export function stableStringify(value) {
+    if (value === undefined)
+        return "null";
+    if (value === null || typeof value !== "object") {
+        return JSON.stringify(value) ?? "null";
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map(stableStringify).join(",")}]`;
+    }
+    const entries = Object.entries(value)
+        .filter(([, v]) => v !== undefined)
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    return `{${entries
+        .map(([k, v]) => `${JSON.stringify(k)}:${stableStringify(v)}`)
+        .join(",")}}`;
+}
+//# sourceMappingURL=stable-json.js.map

package/dist/core/stable-json.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stable-json.js","sourceRoot":"","sources":["../../src/core/stable-json.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,MAAM,UAAU,eAAe,CAAC,KAAc;IAC5C,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC;IACvC,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAChD,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,MAAM,CAAC;IACzC,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,IAAI,KAAK,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;IACrD,CAAC;IACD,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,KAAgC,CAAC;SAC7D,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,SAAS,CAAC;SAClC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACpD,OAAO,IAAI,OAAO;SACf,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,eAAe,CAAC,CAAC,CAAC,EAAE,CAAC;SAC7D,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;AAClB,CAAC"}

package/dist/drivers/anchors.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Event-anchor matching for scripted `JourneyInteraction`s (§4: "event-
+ * anchored, not time-anchored"). An interaction's `at` string names a
+ * message to wait for before firing — never a wall-clock delay — so both
+ * drivers cancel/stream-input at the same logical point in the run
+ * regardless of how fast either surface actually executes.
+ *
+ * Supported anchor shapes (the only ones the four C2 journeys need; extend
+ * here, not per-driver, when a later journey needs more):
+ *   - `"node_update:<nodeId>:<status>"` — a `node_update` for that node id
+ *     reaching that status (e.g. `"node_update:probe:running"`).
+ *   - `"job_update:<status>"` — a `job_update` reaching that status.
+ *   - `"<type>"` — any message of that `type`, e.g. `"chunk"`.
+ */
+export type AnchoredMessage = Record<string, unknown>;
+export declare function matchesAnchor(message: AnchoredMessage, anchor: string): boolean;
+/**
+ * Registers anchor waiters and resolves them as matching messages flow
+ * through a driver's message pump. Registration must happen synchronously
+ * (no `await` in between) relative to the pump starting to consume already-
+ * queued messages, or a fast-arriving anchor could be missed — both drivers
+ * follow that rule (see the comment at each `run()`'s interaction loop).
+ */
+export declare class AnchorWaiter {
+    private waiters;
+    wait(anchor: string): Promise<void>;
+    notify(message: AnchoredMessage): void;
+}
+//# sourceMappingURL=anchors.d.ts.map

package/dist/drivers/anchors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"anchors.d.ts","sourceRoot":"","sources":["../../src/drivers/anchors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEtD,wBAAgB,aAAa,CAAC,OAAO,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAoB/E;AAOD;;;;;;GAMG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,OAAO,CAAgB;IAE/B,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAIlC;IAED,MAAM,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI,CAOrC;CACF"}

package/dist/drivers/anchors.js

@@ -0,0 +1,48 @@
+export function matchesAnchor(message, anchor) {
+    const parts = anchor.split(":");
+    const type = parts[0];
+    if (message["type"] !== type)
+        return false;
+    if (type === "node_update") {
+        const [, nodeId, status] = parts;
+        if (nodeId !== undefined && message["node_id"] !== nodeId)
+            return false;
+        if (status !== undefined && message["status"] !== status)
+            return false;
+        return true;
+    }
+    if (type === "job_update") {
+        const [, status] = parts;
+        if (status !== undefined && message["status"] !== status)
+            return false;
+        return true;
+    }
+    // Bare type match (e.g. "chunk") — no further qualifiers supported yet.
+    return true;
+}
+/**
+ * Registers anchor waiters and resolves them as matching messages flow
+ * through a driver's message pump. Registration must happen synchronously
+ * (no `await` in between) relative to the pump starting to consume already-
+ * queued messages, or a fast-arriving anchor could be missed — both drivers
+ * follow that rule (see the comment at each `run()`'s interaction loop).
+ */
+export class AnchorWaiter {
+    waiters = [];
+    wait(anchor) {
+        return new Promise((resolve) => {
+            this.waiters.push({ test: (m) => matchesAnchor(m, anchor), resolve });
+        });
+    }
+    notify(message) {
+        const remaining = [];
+        for (const waiter of this.waiters) {
+            if (waiter.test(message))
+                waiter.resolve();
+            else
+                remaining.push(waiter);
+        }
+        this.waiters = remaining;
+    }
+}
+//# sourceMappingURL=anchors.js.map

package/dist/drivers/anchors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"anchors.js","sourceRoot":"","sources":["../../src/drivers/anchors.ts"],"names":[],"mappings":"AAgBA,MAAM,UAAU,aAAa,CAAC,OAAwB,EAAE,MAAc;IACpE,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAChC,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;IACtB,IAAI,OAAO,CAAC,MAAM,CAAC,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAE3C,IAAI,IAAI,KAAK,aAAa,EAAE,CAAC;QAC3B,MAAM,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,KAAK,CAAC;QACjC,IAAI,MAAM,KAAK,SAAS,IAAI,OAAO,CAAC,SAAS,CAAC,KAAK,MAAM;YAAE,OAAO,KAAK,CAAC;QACxE,IAAI,MAAM,KAAK,SAAS,IAAI,OAAO,CAAC,QAAQ,CAAC,KAAK,MAAM;YAAE,OAAO,KAAK,CAAC;QACvE,OAAO,IAAI,CAAC;IACd,CAAC;IAED,IAAI,IAAI,KAAK,YAAY,EAAE,CAAC;QAC1B,MAAM,CAAC,EAAE,MAAM,CAAC,GAAG,KAAK,CAAC;QACzB,IAAI,MAAM,KAAK,SAAS,IAAI,OAAO,CAAC,QAAQ,CAAC,KAAK,MAAM;YAAE,OAAO,KAAK,CAAC;QACvE,OAAO,IAAI,CAAC;IACd,CAAC;IAED,wEAAwE;IACxE,OAAO,IAAI,CAAC;AACd,CAAC;AAOD;;;;;;GAMG;AACH,MAAM,OAAO,YAAY;IACf,OAAO,GAAa,EAAE,CAAC;IAE/B,IAAI,CAAC,MAAc;QACjB,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;YAC7B,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,aAAa,CAAC,CAAC,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC;QACxE,CAAC,CAAC,CAAC;IACL,CAAC;IAED,MAAM,CAAC,OAAwB;QAC7B,MAAM,SAAS,GAAa,EAAE,CAAC;QAC/B,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YAClC,IAAI,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC;gBAAE,MAAM,CAAC,OAAO,EAAE,CAAC;;gBACtC,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAC9B,CAAC;QACD,IAAI,CAAC,OAAO,GAAG,SAAS,CAAC;IAC3B,CAAC;CACF"}

package/dist/drivers/app-headless.d.ts

@@ -0,0 +1,39 @@
+import type { ProcessingMessage } from "@nodetool-ai/protocol";
+import type { Journey } from "../core/journey.js";
+import { type RunRecord } from "../core/record.js";
+import type { RunDriver } from "./types.js";
+/** Minimal shape this driver needs from an `AppDebugReport`'s `report.json`
+ * (`packages/cli/src/app-debug/types.ts`). */
+export interface AppDebugReportLike {
+    target?: {
+        workflowId?: string | null;
+    } | null;
+    runs?: Array<{
+        status?: string;
+        error?: string | null;
+        durationMs?: number | null;
+        messagesFile?: string;
+    }>;
+}
+/** True when a journey's workflow carries an `app_doc` the app-headless
+ * driver can run — pure, no IO, so `compare.ts` and tests can check
+ * applicability without spawning a process. */
+export declare function journeyHasAppDoc(journey: Journey): boolean;
+/**
+ * Folds a decoded `AppDebugReport` (`report.json`) plus each triggered run's
+ * own `server/run-N.messages.jsonl` lines (already read, in `runs[]` order)
+ * into one `RunRecord`. Pure — mirrors `record.ts`'s
+ * `runRecordFromDebugBundle` split between the pure conversion and the IO
+ * that reads the bundle off disk, so this half is unit-testable without a
+ * real app document or a spawned process.
+ */
+export declare function runRecordFromAppDebugReport(report: AppDebugReportLike, runMessages: Array<Array<ProcessingMessage | Record<string, unknown>>>, options?: {
+    journeyId?: string;
+    startedAt?: number;
+}): RunRecord;
+export declare class AppHeadlessDriver implements RunDriver {
+    readonly name = "app-headless";
+    supports(journey: Journey): boolean;
+    run(journey: Journey): Promise<RunRecord>;
+}
+//# sourceMappingURL=app-headless.d.ts.map

package/dist/drivers/app-headless.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-headless.d.ts","sourceRoot":"","sources":["../../src/drivers/app-headless.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC/D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAA4B,KAAK,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAE7E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C;8CAC8C;AAC9C,MAAM,WAAW,kBAAkB;IACjC,MAAM,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,GAAG,IAAI,CAAC;IAC/C,IAAI,CAAC,EAAE,KAAK,CAAC;QACX,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QACtB,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAC3B,YAAY,CAAC,EAAE,MAAM,CAAC;KACvB,CAAC,CAAC;CACJ;AAED;;+CAE+C;AAC/C,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAE1D;AAED;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,kBAAkB,EAC1B,WAAW,EAAE,KAAK,CAAC,KAAK,CAAC,iBAAiB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,EACtE,OAAO,GAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAO,GACvD,SAAS,CA6BX;AAED,qBAAa,iBAAkB,YAAW,SAAS;IACjD,QAAQ,CAAC,IAAI,kBAAkB;IAE/B,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAElC;IAEK,GAAG,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,SAAS,CAAC,CAiE9C;CACF"}