@nodetool-ai/reliability-harness 0.8.1

package/dist/drivers/packaged.js

@@ -0,0 +1,303 @@
+/**
+ * Packaged driver (§12) — stages the backend bundle the same way
+ * `npm run backend:smoke` does (`scripts/bundle-backend.mjs` +
+ * `scripts/smoke-backend-bundle.mjs`'s packaged-module-layout trick), boots
+ * the staged `server.mjs` on a free port, and runs the journey against it
+ * over the real WS protocol — the same msgpack codec `ws-server.ts` uses
+ * (`@nodetool-ai/websocket`'s `packWebSocketMessage`/`unpackWebSocketMessage`
+ * is the wire protocol itself, not an internal seam). Journey 15 (§5): "the
+ * packaged-backend journey ring".
+ *
+ * EXPENSIVE: staging alone copies/rewrites hundreds of MB and takes minutes,
+ * so `stageBackendBundle` is opt-in — callers (tests, the CLI) gate it behind
+ * an env flag (`RELIABILITY_PACKAGED=1`) and otherwise point `bundleDir` at
+ * an already-staged tree. The driver itself has no such gate: given a bundle,
+ * `run()` always boots it for real.
+ */
+import { spawn } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { existsSync } from "node:fs";
+import { mkdtemp, rename, rm } from "node:fs/promises";
+import net from "node:net";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { WebSocket } from "ws";
+import { packWebSocketMessage, unpackWebSocketMessage } from "@nodetool-ai/websocket";
+import { makeFrame } from "../core/record.js";
+import { AnchorWaiter } from "./anchors.js";
+import { isConnectionControlMessage, stripRelayOnlyFields } from "./relay-fields.js";
+import { findRepoRoot } from "./repo-root.js";
+const TERMINAL_JOB_STATUSES = new Set(["completed", "failed", "cancelled", "suspended"]);
+const DEFAULT_HEALTH_TIMEOUT_MS = 120_000;
+function freePort() {
+    return new Promise((resolvePromise, reject) => {
+        const srv = net.createServer();
+        srv.on("error", reject);
+        srv.listen(0, "127.0.0.1", () => {
+            const address = srv.address();
+            const port = typeof address === "object" && address !== null ? address.port : 0;
+            srv.close(() => resolvePromise(port));
+        });
+    });
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/**
+ * Stages the backend bundle via the exact entry point `npm run backend:smoke`
+ * uses (`npm run prepare-backend --workspace=electron`, i.e.
+ * `scripts/bundle-backend.mjs`). Expensive (minutes) — call once per journey
+ * session, not per journey.
+ */
+export async function stageBackendBundle(repoRoot = findRepoRoot()) {
+    await new Promise((resolvePromise, reject) => {
+        const child = spawn("npm", ["run", "prepare-backend", "--workspace=electron"], {
+            cwd: repoRoot,
+            stdio: "inherit"
+        });
+        child.on("exit", (code) => {
+            if (code === 0)
+                resolvePromise();
+            else
+                reject(new Error(`prepare-backend exited with code ${code}`));
+        });
+        child.on("error", reject);
+    });
+    return join(repoRoot, "electron", "backend-bundle");
+}
+/**
+ * Electron-builder's `afterPack` promotes the staged `_modules/` to
+ * `node_modules/` in the packed app — `_modules` only exists pre-pack to
+ * dodge electron-builder's own `node_modules` exclusion rule
+ * (`scripts/smoke-backend-bundle.mjs`'s exact comment). Node needs the real
+ * name to resolve `server.mjs`'s externals, so this driver does the same
+ * rename, and restores it afterward so a staged tree round-trips through a
+ * driver run unchanged.
+ */
+async function withPackagedModuleLayout(bundleDir) {
+    const staged = join(bundleDir, "_modules");
+    const packaged = join(bundleDir, "node_modules");
+    if (existsSync(packaged))
+        return async () => { };
+    if (!existsSync(staged)) {
+        throw new Error(`neither _modules/ nor node_modules/ exists in ${bundleDir} — stage it first ` +
+            `(npm run prepare-backend --workspace=electron, or stageBackendBundle())`);
+    }
+    await rename(staged, packaged);
+    return async () => {
+        await rename(packaged, staged);
+    };
+}
+function resolveNodeBinary(bundleDir, override) {
+    if (override)
+        return override;
+    const bundled = join(bundleDir, "runtime", process.platform === "win32" ? "node.exe" : "node");
+    return existsSync(bundled) ? bundled : process.execPath;
+}
+async function bootServer(bundleDir, nodeBinary, healthTimeoutMs) {
+    const restoreModuleLayout = await withPackagedModuleLayout(bundleDir);
+    const port = await freePort();
+    const dataDir = await mkdtemp(join(tmpdir(), "nodetool-reliability-packaged-"));
+    const output = [];
+    const child = spawn(nodeBinary, ["server.mjs"], {
+        cwd: bundleDir,
+        env: {
+            ...process.env,
+            PORT: String(port),
+            HOME: dataDir,
+            XDG_DATA_HOME: dataDir,
+            APPDATA: dataDir,
+            SECRETS_MASTER_KEY: randomBytes(32).toString("base64"),
+            NODETOOL_LOG_LEVEL: process.env["NODETOOL_LOG_LEVEL"] ?? "warn"
+        },
+        stdio: ["ignore", "pipe", "pipe"]
+    });
+    child.stdout?.on("data", (buf) => output.push(buf.toString()));
+    child.stderr?.on("data", (buf) => output.push(buf.toString()));
+    let exited = false;
+    child.on("exit", () => {
+        exited = true;
+    });
+    const deadline = Date.now() + healthTimeoutMs;
+    let healthy = false;
+    while (Date.now() < deadline && !exited && !healthy) {
+        await sleep(500);
+        try {
+            const res = await fetch(`http://127.0.0.1:${port}/health`);
+            healthy = res.ok;
+        }
+        catch {
+            // Not up yet.
+        }
+    }
+    if (!healthy) {
+        if (!exited)
+            child.kill("SIGKILL");
+        await restoreModuleLayout();
+        await rm(dataDir, { recursive: true, force: true }).catch(() => { });
+        throw new Error(`packaged driver: server.mjs never answered /health within ${healthTimeoutMs}ms\n` +
+            `--- server output ---\n${output.join("").trimEnd() || "(no output)"}`);
+    }
+    return { child, port, output, restoreModuleLayout, dataDir };
+}
+async function teardownServer(server) {
+    if (server.child.exitCode === null && server.child.signalCode === null) {
+        server.child.kill("SIGTERM");
+        const hardKill = setTimeout(() => server.child.kill("SIGKILL"), 10_000);
+        await new Promise((resolvePromise) => {
+            server.child.once("exit", () => resolvePromise());
+        });
+        clearTimeout(hardKill);
+    }
+    await server.restoreModuleLayout();
+    await rm(server.dataDir, { recursive: true, force: true }).catch(() => { });
+}
+function requireJobId(jobId, journeyName, action) {
+    if (!jobId) {
+        throw new Error(`journey "${journeyName}": "${action}" interaction fired before a job_id was observed`);
+    }
+    return jobId;
+}
+export class PackagedDriver {
+    options;
+    name = "packaged";
+    constructor(options = {}) {
+        this.options = options;
+    }
+    /** True when a bundle is staged at the configured (or default) location. */
+    isStaged() {
+        const bundleDir = this.options.bundleDir ?? join(findRepoRoot(), "electron", "backend-bundle");
+        return existsSync(join(bundleDir, "server.mjs"));
+    }
+    async run(journey) {
+        const bundleDir = this.options.bundleDir ?? join(findRepoRoot(), "electron", "backend-bundle");
+        if (!existsSync(join(bundleDir, "server.mjs"))) {
+            throw new Error(`packaged driver: no staged bundle at ${bundleDir} — run ` +
+                `stageBackendBundle() or 'npm run prepare-backend --workspace=electron' first`);
+        }
+        const nodeBinary = resolveNodeBinary(bundleDir, this.options.nodeBinary);
+        const server = await bootServer(bundleDir, nodeBinary, this.options.healthTimeoutMs ?? DEFAULT_HEALTH_TIMEOUT_MS);
+        const frames = [];
+        let seq = 0;
+        const waiter = new AnchorWaiter();
+        let jobId = null;
+        let terminalStatus = null;
+        let terminalError = null;
+        const seenJobUpdateStatuses = new Set();
+        let resolveTerminal;
+        const terminalPromise = new Promise((resolvePromise) => {
+            resolveTerminal = resolvePromise;
+        });
+        const ws = new WebSocket(`ws://127.0.0.1:${server.port}/ws`);
+        ws.on("message", (data, isBinary) => {
+            const raw = (isBinary ? unpackWebSocketMessage(data) : JSON.parse(data.toString("utf8")));
+            // The packaged server is a relay, exactly like `ws-server.ts`'s surface:
+            // it boots the real `server.mjs`, whose Fastify plugin announces the
+            // connection and whose `WebSocketClientSession` backfills run identity
+            // onto frames the kernel oracle emits bare. Both are cancelled here so
+            // the packaged stream is comparable to the oracle frame-for-frame.
+            if (isConnectionControlMessage(raw))
+                return;
+            const message = stripRelayOnlyFields(raw);
+            waiter.notify(message);
+            if (typeof message["job_id"] === "string") {
+                jobId = message["job_id"];
+            }
+            if (typeof message["type"] !== "string")
+                return;
+            if (message["type"] === "job_update") {
+                const status = String(message["status"]);
+                if (seenJobUpdateStatuses.has(status))
+                    return;
+                seenJobUpdateStatuses.add(status);
+                if (TERMINAL_JOB_STATUSES.has(status)) {
+                    terminalStatus = status;
+                    terminalError =
+                        typeof message["error"] === "string" ? message["error"] : null;
+                    frames.push(makeFrame(seq++, "packaged", "server_to_client", message));
+                    resolveTerminal();
+                    return;
+                }
+            }
+            frames.push(makeFrame(seq++, "packaged", "server_to_client", message));
+        });
+        try {
+            await new Promise((resolvePromise, reject) => {
+                ws.once("open", () => resolvePromise());
+                ws.once("error", reject);
+            });
+            const send = (command, data) => {
+                const envelope = { command, data };
+                frames.push(makeFrame(seq++, "packaged", "client_to_server", envelope));
+                ws.send(packWebSocketMessage(envelope));
+            };
+            const interactions = journey.interactions.length > 0 ? journey.interactions : [{ action: "run" }];
+            for (const interaction of interactions) {
+                if (interaction.at) {
+                    await waiter.wait(interaction.at);
+                }
+                switch (interaction.action) {
+                    case "run":
+                        send("run_job", {
+                            graph: journey.workflow,
+                            workflow_id: journey.manifest.name,
+                            params: journey.manifest.params,
+                            execution_options: { persistence: "session" }
+                        });
+                        break;
+                    case "cancel":
+                        send("cancel_job", {
+                            job_id: requireJobId(jobId, journey.manifest.name, "cancel")
+                        });
+                        break;
+                    case "stream_input":
+                        if (!interaction.nodeId) {
+                            throw new Error(`journey "${journey.manifest.name}": "stream_input" interaction needs nodeId`);
+                        }
+                        send("stream_input", {
+                            job_id: requireJobId(jobId, journey.manifest.name, "stream_input"),
+                            input: interaction.nodeId,
+                            value: interaction.value
+                        });
+                        break;
+                    case "end_input_stream":
+                        if (!interaction.nodeId) {
+                            throw new Error(`journey "${journey.manifest.name}": "end_input_stream" interaction needs nodeId`);
+                        }
+                        send("end_input_stream", {
+                            job_id: requireJobId(jobId, journey.manifest.name, "end_input_stream"),
+                            input: interaction.nodeId
+                        });
+                        break;
+                    case "reconnect":
+                        throw new Error(`journey "${journey.manifest.name}": packaged driver does not support ` +
+                            `the "reconnect" interaction`);
+                }
+            }
+            const timeoutMs = journey.manifest.timeoutMs + 30_000;
+            await Promise.race([
+                terminalPromise,
+                sleep(timeoutMs).then(() => {
+                    throw new Error(`journey "${journey.manifest.name}": packaged driver timed out after ${timeoutMs}ms ` +
+                        `waiting for a terminal job_update`);
+                })
+            ]);
+        }
+        finally {
+            ws.close();
+            await teardownServer(server);
+        }
+        return {
+            journeyId: journey.manifest.name,
+            surface: this.name,
+            jobId,
+            workflowId: journey.manifest.name,
+            startedAt: frames.length > 0 ? frames[0].ts : null,
+            finishedAt: frames.length > 0 ? frames[frames.length - 1].ts : null,
+            durationMs: null,
+            status: terminalStatus ?? "unknown",
+            error: terminalError,
+            params: journey.manifest.params,
+            frames
+        };
+    }
+}
+//# sourceMappingURL=packaged.js.map

package/dist/drivers/packaged.js.map

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

package/dist/drivers/python-bridge.d.ts

@@ -0,0 +1,22 @@
+import type { BridgeFactory } from "@nodetool-ai/execution";
+/** The interpreter shim `PythonStdioBridge` spawns in place of a real
+ * `python` (see `packages/runtime/tests/fixtures/fake-python-interpreter.mjs`
+ * for why the indirection over the fixture worker exists). */
+export declare function fakePythonInterpreterPath(): string;
+/** Journeys never wait on a real Python install, so a misbehaving (or
+ * deliberately never-ready) fake should fail fast instead of eating a
+ * journey's `timeoutMs` budget. */
+export declare const FAKE_BRIDGE_STARTUP_TIMEOUT_MS = 3000;
+/**
+ * `BridgeFactory` (`@nodetool-ai/execution`'s facade hook) that spawns the
+ * faithful stdio fake instead of a real Python worker whenever a journey's
+ * graph contains a node type the TS registry can't resolve. Reused
+ * unmodified by every `bridge-*` fault — those faults act by setting the
+ * `FAKE_WORKER_*` env vars the fake fixture reads, not by changing this
+ * factory. Both the kernel driver (directly, as `ExecutionSession`'s
+ * `bridgeFactory`) and the ws-server driver (via its own `resolveExecutor`,
+ * `connectPythonBridgeForGraph` isn't wired into `WebSocketClientSession`
+ * automatically the way it is into `ExecutionSession`) use this one factory.
+ */
+export declare const journeyPythonBridgeFactory: BridgeFactory;
+//# sourceMappingURL=python-bridge.d.ts.map

package/dist/drivers/python-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"python-bridge.d.ts","sourceRoot":"","sources":["../../src/drivers/python-bridge.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAG5D;;8DAE8D;AAC9D,wBAAgB,yBAAyB,IAAI,MAAM,CASlD;AAED;;mCAEmC;AACnC,eAAO,MAAM,8BAA8B,OAAO,CAAC;AAEnD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,0BAA0B,EAAE,aAOrC,CAAC"}

package/dist/drivers/python-bridge.js

@@ -0,0 +1,48 @@
+/**
+ * Shared Python-bridge wiring for journey 7 (`python-node-workflow`) and
+ * task D3's `bridge-*` fault modules (`faults/bridge-faults.ts`).
+ *
+ * Both the kernel driver and the ws-server driver route any graph node type
+ * the TS registry can't resolve to E2's faithful stdio fake
+ * (`packages/runtime/tests/fixtures/fake-python-stdio-worker.ts`) — the same
+ * fake `python-stdio-bridge.test.ts` drives directly — launched through the
+ * same `fake-python-interpreter.mjs` shim, never the real
+ * `python -m nodetool.worker --stdio`. `connectPythonBridgeForGraph`
+ * (`@nodetool-ai/runtime`) already gates the spawn on "does this graph
+ * actually contain an unresolved node type", so wiring this factory in as
+ * the default for every journey (not just journey 7) costs nothing: a graph
+ * built entirely from real TS nodes never triggers a spawn.
+ *
+ * Fault modules act purely by setting the `FAKE_WORKER_*` env vars the fake
+ * fixture reads (ambient, exactly like `python-stdio-bridge.test.ts`'s own
+ * `makeBridge` helper) — this factory never changes.
+ */
+import { join } from "node:path";
+import { connectPythonBridgeForGraph } from "@nodetool-ai/runtime";
+import { findRepoRoot } from "./repo-root.js";
+/** The interpreter shim `PythonStdioBridge` spawns in place of a real
+ * `python` (see `packages/runtime/tests/fixtures/fake-python-interpreter.mjs`
+ * for why the indirection over the fixture worker exists). */
+export function fakePythonInterpreterPath() {
+    return join(findRepoRoot(), "packages", "runtime", "tests", "fixtures", "fake-python-interpreter.mjs");
+}
+/** Journeys never wait on a real Python install, so a misbehaving (or
+ * deliberately never-ready) fake should fail fast instead of eating a
+ * journey's `timeoutMs` budget. */
+export const FAKE_BRIDGE_STARTUP_TIMEOUT_MS = 3000;
+/**
+ * `BridgeFactory` (`@nodetool-ai/execution`'s facade hook) that spawns the
+ * faithful stdio fake instead of a real Python worker whenever a journey's
+ * graph contains a node type the TS registry can't resolve. Reused
+ * unmodified by every `bridge-*` fault — those faults act by setting the
+ * `FAKE_WORKER_*` env vars the fake fixture reads, not by changing this
+ * factory. Both the kernel driver (directly, as `ExecutionSession`'s
+ * `bridgeFactory`) and the ws-server driver (via its own `resolveExecutor`,
+ * `connectPythonBridgeForGraph` isn't wired into `WebSocketClientSession`
+ * automatically the way it is into `ExecutionSession`) use this one factory.
+ */
+export const journeyPythonBridgeFactory = (nodes, hasTsExecutor) => connectPythonBridgeForGraph(nodes, hasTsExecutor, {
+    pythonPath: fakePythonInterpreterPath(),
+    startupTimeoutMs: FAKE_BRIDGE_STARTUP_TIMEOUT_MS
+});
+//# sourceMappingURL=python-bridge.js.map

package/dist/drivers/python-bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"python-bridge.js","sourceRoot":"","sources":["../../src/drivers/python-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,2BAA2B,EAAE,MAAM,sBAAsB,CAAC;AAEnE,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAE9C;;8DAE8D;AAC9D,MAAM,UAAU,yBAAyB;IACvC,OAAO,IAAI,CACT,YAAY,EAAE,EACd,UAAU,EACV,SAAS,EACT,OAAO,EACP,UAAU,EACV,6BAA6B,CAC9B,CAAC;AACJ,CAAC;AAED;;mCAEmC;AACnC,MAAM,CAAC,MAAM,8BAA8B,GAAG,IAAI,CAAC;AAEnD;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAkB,CACvD,KAAK,EACL,aAAa,EACb,EAAE,CACF,2BAA2B,CAAC,KAAK,EAAE,aAAa,EAAE;IAChD,UAAU,EAAE,yBAAyB,EAAE;IACvC,gBAAgB,EAAE,8BAA8B;CACjD,CAAC,CAAC"}

package/dist/drivers/registry.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Node registry shared by the kernel driver and, via `registerFixtureNodes`,
+ * added onto the ws-server driver's own registry — the same real node
+ * classes (`registerBaseNodes`) run on both surfaces, so journeys exercise
+ * identical node behavior everywhere. See `fixture-nodes.ts` for the three
+ * nodes neither surface's real registry has.
+ */
+import { NodeRegistry } from "@nodetool-ai/node-sdk";
+/** Fresh registry for one kernel-driver run: real base nodes + harness fixtures. */
+export declare function buildJourneyRegistry(): NodeRegistry;
+//# sourceMappingURL=registry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/drivers/registry.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAIrD,oFAAoF;AACpF,wBAAgB,oBAAoB,IAAI,YAAY,CAKnD"}

package/dist/drivers/registry.js

@@ -0,0 +1,18 @@
+/**
+ * Node registry shared by the kernel driver and, via `registerFixtureNodes`,
+ * added onto the ws-server driver's own registry — the same real node
+ * classes (`registerBaseNodes`) run on both surfaces, so journeys exercise
+ * identical node behavior everywhere. See `fixture-nodes.ts` for the three
+ * nodes neither surface's real registry has.
+ */
+import { NodeRegistry } from "@nodetool-ai/node-sdk";
+import { registerBaseNodes } from "@nodetool-ai/base-nodes";
+import { registerFixtureNodes } from "./fixture-nodes.js";
+/** Fresh registry for one kernel-driver run: real base nodes + harness fixtures. */
+export function buildJourneyRegistry() {
+    const registry = new NodeRegistry();
+    registerBaseNodes(registry);
+    registerFixtureNodes(registry);
+    return registry;
+}
+//# sourceMappingURL=registry.js.map

package/dist/drivers/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/drivers/registry.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AACrD,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAE1D,oFAAoF;AACpF,MAAM,UAAU,oBAAoB;IAClC,MAAM,QAAQ,GAAG,IAAI,YAAY,EAAE,CAAC;IACpC,iBAAiB,CAAC,QAAQ,CAAC,CAAC;IAC5B,oBAAoB,CAAC,QAAQ,CAAC,CAAC;IAC/B,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/drivers/relay-fields.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Relay-only field policy, shared by every driver whose surface speaks the
+ * WS wire protocol (`ws-server.ts`, `packaged.ts`).
+ *
+ * Both of those surfaces run the same relay — `WebSocketClientSession` — so
+ * both receive the same downstream enrichment the kernel oracle's raw stream
+ * never carries. `packages/protocol/src/messages.ts` specifies this: `job_id`
+ * is "Stamped downstream by the relay (the unified websocket runner and the
+ * browser runner), not by the kernel actor, so it is optional on the wire",
+ * and `generation_complete` is emitted by the actor as "a BARE event" with
+ * `job_id` and `index` "stamped DOWNSTREAM by the relay".
+ *
+ * Lives here rather than in each driver because a rule that only one relay
+ * surface applies is not a policy, it is a discrepancy — `packaged.ts` not
+ * having it is exactly what made the Ring 2 release gate unpassable.
+ */
+/**
+ * Message `type`s the relay backfills `job_id` onto uniformly (its "outbound
+ * spread", `websocket-client-session.ts`) that the kernel's own emissions for
+ * these types (`runner.ts`/`actor.ts`) never carry at all. Scoped per-type
+ * (not a blanket drop) because `job_update` DOES set both, and `edge_update`
+ * DOES set `job_id`, on the raw kernel stream too — dropping either there
+ * would hide a real regression instead of a harmless relay addition. Kept as
+ * a driver-local rule (not a `normalize.ts` field list) because
+ * `normalize.ts`'s generic per-key visitor has other callers — including its
+ * own unit tests — that legitimately expect `job_id`/`workflow_id` preserved
+ * on a `node_update`. The relay drivers are the only place that actually
+ * knows which of these are relay-only enrichment on their wire protocol.
+ */
+export declare const RELAY_ONLY_JOB_ID_TYPES: ReadonlySet<string>;
+/** As {@link RELAY_ONLY_JOB_ID_TYPES}, for `workflow_id`. Includes
+ * `edge_update` — the kernel stamps `job_id` there but never `workflow_id`. */
+export declare const RELAY_ONLY_WORKFLOW_ID_TYPES: ReadonlySet<string>;
+/**
+ * Message `type`s that exist only as connection-scoped transport control and
+ * are never part of a run's stream. `sdk_execution_target` is sent once per
+ * socket, at upgrade time and BEFORE any workflow is submitted, by the
+ * production Fastify plugin when an SDK live-runner registry is wired
+ * (`packages/websocket/src/plugins/websocket.ts`). `renderer_registered` is
+ * the same shape for the frontend-renderer registry: sent once per socket
+ * right after `connect()`, naming a `renderer_id` no other surface has
+ * anything to compare against. The kernel oracle has no connection to
+ * announce, so there is nothing to compare either against.
+ *
+ * The rest are the relay's own timers and observers, which fire on wall-clock
+ * cadence rather than on anything the run does
+ * (`websocket-client-session.ts`): `system_stats` ~1s after connect and every
+ * 5s after, `ping` every 25s, `pong` in reply to a client ping,
+ * `resource_change` whenever a model or resource event lands. Whether one of
+ * them interleaves into a run depends on how long the run happens to take, so
+ * recording them makes the stream non-deterministic —
+ * a `system_stats` landing mid-run is what failed `linear-text-pipeline` on
+ * the packaged surface in Ring 1 (run 31619279663), which in turn blocked
+ * the Fly deploy of 2868cffe. They are all outbound *control* frames in the
+ * protocol's own taxonomy (`outboundControlMessageSchemas`), not
+ * `ProcessingMessage`s, so no run assertion loses coverage by dropping them.
+ */
+export declare const CONNECTION_CONTROL_MESSAGE_TYPES: ReadonlySet<string>;
+/** True when `message` is transport control rather than a run frame — callers
+ * drop these before recording (see {@link CONNECTION_CONTROL_MESSAGE_TYPES}). */
+export declare function isConnectionControlMessage(message: Record<string, unknown>): boolean;
+/** Strips fields the relay adds that the kernel driver's raw stream never has,
+ * so the two are comparable frame-for-frame (see
+ * {@link RELAY_ONLY_JOB_ID_TYPES}/{@link RELAY_ONLY_WORKFLOW_ID_TYPES}).
+ * `generation_complete.index` is the same kind of addition — an
+ * arrival-order stamp (`websocket-client-session.ts`'s
+ * `generationIndexByNode`) the kernel's own `generation_complete` emission
+ * never sets. */
+export declare function stripRelayOnlyFields(message: Record<string, unknown>): Record<string, unknown>;
+//# sourceMappingURL=relay-fields.d.ts.map

package/dist/drivers/relay-fields.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relay-fields.d.ts","sourceRoot":"","sources":["../../src/drivers/relay-fields.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,uBAAuB,EAAE,WAAW,CAAC,MAAM,CAStD,CAAC;AAEH;+EAC+E;AAC/E,eAAO,MAAM,4BAA4B,EAAE,WAAW,CAAC,MAAM,CAM3D,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,gCAAgC,EAAE,WAAW,CAAC,MAAM,CAO/D,CAAC;AAEH;iFACiF;AACjF,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAEpF;AAED;;;;;;iBAMiB;AACjB,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAOzB"}

package/dist/drivers/relay-fields.js

@@ -0,0 +1,104 @@
+/**
+ * Relay-only field policy, shared by every driver whose surface speaks the
+ * WS wire protocol (`ws-server.ts`, `packaged.ts`).
+ *
+ * Both of those surfaces run the same relay — `WebSocketClientSession` — so
+ * both receive the same downstream enrichment the kernel oracle's raw stream
+ * never carries. `packages/protocol/src/messages.ts` specifies this: `job_id`
+ * is "Stamped downstream by the relay (the unified websocket runner and the
+ * browser runner), not by the kernel actor, so it is optional on the wire",
+ * and `generation_complete` is emitted by the actor as "a BARE event" with
+ * `job_id` and `index` "stamped DOWNSTREAM by the relay".
+ *
+ * Lives here rather than in each driver because a rule that only one relay
+ * surface applies is not a policy, it is a discrepancy — `packaged.ts` not
+ * having it is exactly what made the Ring 2 release gate unpassable.
+ */
+/**
+ * Message `type`s the relay backfills `job_id` onto uniformly (its "outbound
+ * spread", `websocket-client-session.ts`) that the kernel's own emissions for
+ * these types (`runner.ts`/`actor.ts`) never carry at all. Scoped per-type
+ * (not a blanket drop) because `job_update` DOES set both, and `edge_update`
+ * DOES set `job_id`, on the raw kernel stream too — dropping either there
+ * would hide a real regression instead of a harmless relay addition. Kept as
+ * a driver-local rule (not a `normalize.ts` field list) because
+ * `normalize.ts`'s generic per-key visitor has other callers — including its
+ * own unit tests — that legitimately expect `job_id`/`workflow_id` preserved
+ * on a `node_update`. The relay drivers are the only place that actually
+ * knows which of these are relay-only enrichment on their wire protocol.
+ */
+export const RELAY_ONLY_JOB_ID_TYPES = new Set([
+    "node_update",
+    "generation_complete",
+    "output_update",
+    // `llm_call` (task D1, journey 8 — the first journey to run a real LLM
+    // node): the relay backfills `job_id`/`workflow_id` here the same way it
+    // does for `node_update`; the kernel's own `llm_call` emission
+    // (`BaseProvider`'s tracing helper) never carries either.
+    "llm_call"
+]);
+/** As {@link RELAY_ONLY_JOB_ID_TYPES}, for `workflow_id`. Includes
+ * `edge_update` — the kernel stamps `job_id` there but never `workflow_id`. */
+export const RELAY_ONLY_WORKFLOW_ID_TYPES = new Set([
+    "node_update",
+    "generation_complete",
+    "output_update",
+    "edge_update",
+    "llm_call"
+]);
+/**
+ * Message `type`s that exist only as connection-scoped transport control and
+ * are never part of a run's stream. `sdk_execution_target` is sent once per
+ * socket, at upgrade time and BEFORE any workflow is submitted, by the
+ * production Fastify plugin when an SDK live-runner registry is wired
+ * (`packages/websocket/src/plugins/websocket.ts`). `renderer_registered` is
+ * the same shape for the frontend-renderer registry: sent once per socket
+ * right after `connect()`, naming a `renderer_id` no other surface has
+ * anything to compare against. The kernel oracle has no connection to
+ * announce, so there is nothing to compare either against.
+ *
+ * The rest are the relay's own timers and observers, which fire on wall-clock
+ * cadence rather than on anything the run does
+ * (`websocket-client-session.ts`): `system_stats` ~1s after connect and every
+ * 5s after, `ping` every 25s, `pong` in reply to a client ping,
+ * `resource_change` whenever a model or resource event lands. Whether one of
+ * them interleaves into a run depends on how long the run happens to take, so
+ * recording them makes the stream non-deterministic —
+ * a `system_stats` landing mid-run is what failed `linear-text-pipeline` on
+ * the packaged surface in Ring 1 (run 31619279663), which in turn blocked
+ * the Fly deploy of 2868cffe. They are all outbound *control* frames in the
+ * protocol's own taxonomy (`outboundControlMessageSchemas`), not
+ * `ProcessingMessage`s, so no run assertion loses coverage by dropping them.
+ */
+export const CONNECTION_CONTROL_MESSAGE_TYPES = new Set([
+    "sdk_execution_target",
+    "renderer_registered",
+    "system_stats",
+    "resource_change",
+    "ping",
+    "pong"
+]);
+/** True when `message` is transport control rather than a run frame — callers
+ * drop these before recording (see {@link CONNECTION_CONTROL_MESSAGE_TYPES}). */
+export function isConnectionControlMessage(message) {
+    return CONNECTION_CONTROL_MESSAGE_TYPES.has(String(message["type"]));
+}
+/** Strips fields the relay adds that the kernel driver's raw stream never has,
+ * so the two are comparable frame-for-frame (see
+ * {@link RELAY_ONLY_JOB_ID_TYPES}/{@link RELAY_ONLY_WORKFLOW_ID_TYPES}).
+ * `generation_complete.index` is the same kind of addition — an
+ * arrival-order stamp (`websocket-client-session.ts`'s
+ * `generationIndexByNode`) the kernel's own `generation_complete` emission
+ * never sets. */
+export function stripRelayOnlyFields(message) {
+    const type = String(message["type"]);
+    const rest = { ...message };
+    if (RELAY_ONLY_JOB_ID_TYPES.has(type))
+        delete rest["job_id"];
+    if (RELAY_ONLY_WORKFLOW_ID_TYPES.has(type))
+        delete rest["workflow_id"];
+    if (type === "generation_complete")
+        delete rest["index"];
+    return rest;
+}
+//# sourceMappingURL=relay-fields.js.map

package/dist/drivers/relay-fields.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"relay-fields.js","sourceRoot":"","sources":["../../src/drivers/relay-fields.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAwB,IAAI,GAAG,CAAC;IAClE,aAAa;IACb,qBAAqB;IACrB,eAAe;IACf,uEAAuE;IACvE,yEAAyE;IACzE,+DAA+D;IAC/D,0DAA0D;IAC1D,UAAU;CACX,CAAC,CAAC;AAEH;+EAC+E;AAC/E,MAAM,CAAC,MAAM,4BAA4B,GAAwB,IAAI,GAAG,CAAC;IACvE,aAAa;IACb,qBAAqB;IACrB,eAAe;IACf,aAAa;IACb,UAAU;CACX,CAAC,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,CAAC,MAAM,gCAAgC,GAAwB,IAAI,GAAG,CAAC;IAC3E,sBAAsB;IACtB,qBAAqB;IACrB,cAAc;IACd,iBAAiB;IACjB,MAAM;IACN,MAAM;CACP,CAAC,CAAC;AAEH;iFACiF;AACjF,MAAM,UAAU,0BAA0B,CAAC,OAAgC;IACzE,OAAO,gCAAgC,CAAC,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;AACvE,CAAC;AAED;;;;;;iBAMiB;AACjB,MAAM,UAAU,oBAAoB,CAClC,OAAgC;IAEhC,MAAM,IAAI,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;IACrC,MAAM,IAAI,GAAG,EAAE,GAAG,OAAO,EAAE,CAAC;IAC5B,IAAI,uBAAuB,CAAC,GAAG,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC7D,IAAI,4BAA4B,CAAC,GAAG,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC,aAAa,CAAC,CAAC;IACvE,IAAI,IAAI,KAAK,qBAAqB;QAAE,OAAO,IAAI,CAAC,OAAO,CAAC,CAAC;IACzD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/drivers/repo-root.d.ts

@@ -0,0 +1,9 @@
+/** Walks up from this module to the checked-out repo root (the directory
+ * whose `packages/cli/src/nodetool.ts` exists) — works from both `src/`
+ * (ts-node/tsx dev) and `dist/` (built) locations since it only depends on
+ * directory depth, not file extension. */
+export declare function findRepoRoot(): string;
+/** The workspace-hoisted `tsx` binary, falling back to a bare `tsx` for a
+ * shell to resolve if the root install ever changes shape. */
+export declare function resolveTsxBin(repoRoot: string): string;
+//# sourceMappingURL=repo-root.d.ts.map

package/dist/drivers/repo-root.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"repo-root.d.ts","sourceRoot":"","sources":["../../src/drivers/repo-root.ts"],"names":[],"mappings":"AAcA;;;0CAG0C;AAC1C,wBAAgB,YAAY,IAAI,MAAM,CAerC;AAED;8DAC8D;AAC9D,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAQtD"}