@nodetool-ai/reliability-harness 0.8.1

package/dist/faults/bridge-faults.js

@@ -0,0 +1,90 @@
+/**
+ * Bridge-seam fault modules (docs/RELIABILITY_ARCHITECTURE.md §9; task D3).
+ *
+ * Each of the five `bridge-*` fault names in `cli.ts`'s `KNOWN_FAULT_TYPES`
+ * drives E2's faithful stdio fake worker
+ * (`packages/runtime/tests/fixtures/fake-python-stdio-worker.ts`) with the
+ * `FAKE_WORKER_*` env var it already understands — the exact same knobs
+ * `packages/runtime/tests/python-stdio-bridge.test.ts` uses directly against
+ * `PythonStdioBridge`. `configure()` sets the env vars ambient (the fake
+ * interpreter shim spawns with `env: process.env`, see
+ * `python-stdio-bridge.ts`'s `_spawnCandidate`), and the teardown restores
+ * whatever was there before — same "process-global side effect, always
+ * undone" contract `provider-faults.ts` uses for the provider registry.
+ *
+ * The driver-side wiring that actually spawns the fake worker for a graph
+ * that needs one lives in `drivers/python-bridge.ts` (shared by the kernel
+ * and ws-server drivers) — these fault modules never touch a driver or a
+ * bridge instance directly, only the env vars the next spawn will read.
+ */
+import { registerFaultModule } from "./registry.js";
+/** `cli.ts`'s `KNOWN_FAULT_TYPES` `bridge-*` entries, mapped to the
+ * `FAKE_WORKER_*` env vars that reproduce each fault against E2's fake
+ * (see that fixture's own doc comment for the full knob list). */
+const FAULT_ENV_BY_NAME = {
+    // Worker exits without responding once it receives an `execute` request —
+    // `PythonStdioBridge.execute()` rejects the pending request when the
+    // process exits (`python-stdio-bridge.test.ts`: "rejects pending requests
+    // when the worker exits mid-request").
+    "bridge-exit-mid-request": { FAKE_WORKER_EXIT_ON_TYPE: "execute" },
+    // Worker replies to `execute` with an absurd length prefix instead of a
+    // real frame — `FrameDecoder` fails the whole connection
+    // (`FrameSizeError`), same path a real desynced/corrupted stream hits.
+    "bridge-framing-violation": { FAKE_WORKER_BAD_LENGTH_ON_TYPE: "execute" },
+    // Worker never emits "NODETOOL_STDIO_READY" — `connect()`'s startup timer
+    // (`FAKE_BRIDGE_STARTUP_TIMEOUT_MS` in `drivers/python-bridge.ts`) fires
+    // instead of a normal ready signal.
+    "bridge-never-ready": { FAKE_WORKER_MODE: "never-ready" },
+    // Worker's stdin read end is closed immediately (before `discover` is even
+    // sent, given the ready-signal head start), so the bridge's very first
+    // write hits a genuinely broken pipe — the same EPIPE path
+    // `python-stdio-bridge.test.ts`'s "fails connect() with EPIPE" test drives.
+    "bridge-epipe": {
+        FAKE_WORKER_CLOSE_STDIN_AFTER_MS: "0",
+        FAKE_WORKER_READY_DELAY_MS: "400"
+    },
+    // Worker reports a `protocol_version` below `MIN_BRIDGE_PROTOCOL_VERSION`
+    // (1, `@nodetool-ai/protocol/bridge-protocol`) — the bridge's hard-floor
+    // check in `python-bridge-base.ts`'s discover handler rejects the connect.
+    "bridge-version-mismatch": { FAKE_WORKER_PROTOCOL_VERSION: "0" }
+};
+function applyEnvOverrides(env) {
+    const previous = {};
+    for (const key of Object.keys(env)) {
+        previous[key] = process.env[key];
+        process.env[key] = env[key];
+    }
+    return () => {
+        for (const key of Object.keys(previous)) {
+            const value = previous[key];
+            if (value === undefined)
+                delete process.env[key];
+            else
+                process.env[key] = value;
+        }
+    };
+}
+function configureBridgeFault(name, _ctx) {
+    const env = FAULT_ENV_BY_NAME[name];
+    if (!env) {
+        throw new Error(`bridge-faults.ts: no env mapping for fault "${name}"`);
+    }
+    return applyEnvOverrides(env);
+}
+function makeBridgeFaultModule(name) {
+    return {
+        name,
+        seam: "bridge",
+        configure: (ctx) => configureBridgeFault(name, ctx)
+    };
+}
+export const BRIDGE_FAULT_MODULES = Object.keys(FAULT_ENV_BY_NAME).map(makeBridgeFaultModule);
+/** Registers every bridge-seam fault module. Called once from
+ * `faults/index.ts`'s module-load side effect (task D1's "call once, own
+ * module state" contract) — safe to call again, last-write-wins. */
+export function registerBridgeFaultModules() {
+    for (const module of BRIDGE_FAULT_MODULES) {
+        registerFaultModule(module);
+    }
+}
+//# sourceMappingURL=bridge-faults.js.map

package/dist/faults/bridge-faults.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge-faults.js","sourceRoot":"","sources":["../../src/faults/bridge-faults.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAGpD;;kEAEkE;AAClE,MAAM,iBAAiB,GAA+D;IACpF,0EAA0E;IAC1E,qEAAqE;IACrE,0EAA0E;IAC1E,uCAAuC;IACvC,yBAAyB,EAAE,EAAE,wBAAwB,EAAE,SAAS,EAAE;IAClE,wEAAwE;IACxE,yDAAyD;IACzD,uEAAuE;IACvE,0BAA0B,EAAE,EAAE,8BAA8B,EAAE,SAAS,EAAE;IACzE,0EAA0E;IAC1E,yEAAyE;IACzE,oCAAoC;IACpC,oBAAoB,EAAE,EAAE,gBAAgB,EAAE,aAAa,EAAE;IACzD,2EAA2E;IAC3E,uEAAuE;IACvE,2DAA2D;IAC3D,4EAA4E;IAC5E,cAAc,EAAE;QACd,gCAAgC,EAAE,GAAG;QACrC,0BAA0B,EAAE,KAAK;KAClC;IACD,0EAA0E;IAC1E,yEAAyE;IACzE,2EAA2E;IAC3E,yBAAyB,EAAE,EAAE,4BAA4B,EAAE,GAAG,EAAE;CACjE,CAAC;AAEF,SAAS,iBAAiB,CAAC,GAAqC;IAC9D,MAAM,QAAQ,GAAuC,EAAE,CAAC;IACxD,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QACnC,QAAQ,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACjC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC;IAC9B,CAAC;IACD,OAAO,GAAG,EAAE;QACV,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;YACxC,MAAM,KAAK,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC;YAC5B,IAAI,KAAK,KAAK,SAAS;gBAAE,OAAO,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;;gBAC5C,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;QAChC,CAAC;IACH,CAAC,CAAC;AACJ,CAAC;AAED,SAAS,oBAAoB,CAAC,IAAY,EAAE,IAAkB;IAC5D,MAAM,GAAG,GAAG,iBAAiB,CAAC,IAAI,CAAC,CAAC;IACpC,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,MAAM,IAAI,KAAK,CAAC,+CAA+C,IAAI,GAAG,CAAC,CAAC;IAC1E,CAAC;IACD,OAAO,iBAAiB,CAAC,GAAG,CAAC,CAAC;AAChC,CAAC;AAED,SAAS,qBAAqB,CAAC,IAAY;IACzC,OAAO;QACL,IAAI;QACJ,IAAI,EAAE,QAAQ;QACd,SAAS,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,oBAAoB,CAAC,IAAI,EAAE,GAAG,CAAC;KACpD,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,MAAM,oBAAoB,GAA2B,MAAM,CAAC,IAAI,CACrE,iBAAiB,CAClB,CAAC,GAAG,CAAC,qBAAqB,CAAC,CAAC;AAE7B;;oEAEoE;AACpE,MAAM,UAAU,0BAA0B;IACxC,KAAK,MAAM,MAAM,IAAI,oBAAoB,EAAE,CAAC;QAC1C,mBAAmB,CAAC,MAAM,CAAC,CAAC;IAC9B,CAAC;AACH,CAAC"}

package/dist/faults/host-faults.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Host-seam fault modules (docs/RELIABILITY_ARCHITECTURE.md §9; task D3).
+ *
+ * Of the three §9 "process/host" faults, only `host-disk-full` is a
+ * `FaultModule` here:
+ *
+ * - `host-disk-full`: an injectable `StorageAdapter` whose writes fail with
+ *   ENOSPC. Wired into the **kernel driver only** (`drivers/kernel.ts`
+ *   consults {@link getInjectedHostStorage} when building the run's
+ *   `ProcessingContext`) — the ws-server driver's asset storage comes from
+ *   `websocket-client-session.ts`'s own module-level `getTempAdapter()`
+ *   singleton (`lib/storage.ts`), which task A5 explicitly reserves for a
+ *   later `ExecutionSession` migration ("do not refactor
+ *   `websocket-client-session.ts`... pin behavior with tests around it").
+ *   Journeys exercising this fault must scope it to `"surface": "kernel"`.
+ * - `host-db-locked` has no `FaultModule`: the swallowed failure it pins
+ *   (`websocket-client-session.ts` ~2868) is job-table persistence, which
+ *   neither driver's hermetic runs touch (both run with `persistence:
+ *   "session"`/no persistence hook) — see
+ *   `packages/websocket/tests/job-persistence-failure.test.ts` for the
+ *   dedicated pin instead. `--faults host-db-locked` correctly reports
+ *   "unknown fault" from this harness until a journey exists that actually
+ *   exercises job persistence.
+ * - `host-sigkill-restart` has no `FaultModule`: killing and restarting the
+ *   server process is a harness-level *test* (spawns/kills a real process),
+ *   not a per-run "configure/teardown around one driver call" fault — see
+ *   `tests/journeys/host-sigkill-restart.test.ts`.
+ */
+import { type StorageAdapter } from "@nodetool-ai/runtime";
+import type { FaultModule } from "./types.js";
+/** Consulted by the kernel driver when building a run's `ProcessingContext` —
+ * non-null only while `host-disk-full` is configured for the current
+ * `compareJourney` call. */
+export declare function getInjectedHostStorage(): StorageAdapter | null;
+export declare const HOST_FAULT_MODULES: readonly FaultModule[];
+/** Registers every host-seam fault module this harness implements. Called
+ * once from `faults/index.ts`'s module-load side effect — safe to call
+ * again, last-write-wins. */
+export declare function registerHostFaultModules(): void;
+//# sourceMappingURL=host-faults.d.ts.map

package/dist/faults/host-faults.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-faults.d.ts","sourceRoot":"","sources":["../../src/faults/host-faults.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAU3D,OAAO,KAAK,EAAgB,WAAW,EAAiB,MAAM,YAAY,CAAC;AAsD3E;;4BAE4B;AAC5B,wBAAgB,sBAAsB,IAAI,cAAc,GAAG,IAAI,CAE9D;AAUD,eAAO,MAAM,kBAAkB,EAAE,SAAS,WAAW,EAMpD,CAAC;AAEF;;6BAE6B;AAC7B,wBAAgB,wBAAwB,IAAI,IAAI,CAI/C"}

package/dist/faults/host-faults.js

@@ -0,0 +1,70 @@
+import { InMemoryStorageAdapter } from "@nodetool-ai/storage";
+import { registerFaultModule } from "./registry.js";
+function enospcError(key) {
+    const err = new Error(`ENOSPC: no space left on device, write '${key}'`);
+    err.code = "ENOSPC";
+    return err;
+}
+/** Wraps a real adapter, failing every WRITE op with an ENOSPC-shaped error —
+ * reads still work (a full disk doesn't un-write what's already on it),
+ * matching what an actual write failure looks like mid-run. */
+class EnospcStorageAdapter {
+    inner;
+    constructor(inner) {
+        this.inner = inner;
+    }
+    store(key) {
+        throw enospcError(key);
+    }
+    retrieve(uri) {
+        return this.inner.retrieve(uri);
+    }
+    exists(uri) {
+        return this.inner.exists(uri);
+    }
+    uriForKey(key) {
+        return this.inner.uriForKey(key);
+    }
+    list(prefix, opts) {
+        return this.inner.list(prefix, opts);
+    }
+    delete(uri) {
+        throw enospcError(uri);
+    }
+    stat(uri) {
+        return this.inner.stat(uri);
+    }
+    localPath(uri) {
+        return this.inner.localPath(uri);
+    }
+}
+let injectedStorage = null;
+/** Consulted by the kernel driver when building a run's `ProcessingContext` —
+ * non-null only while `host-disk-full` is configured for the current
+ * `compareJourney` call. */
+export function getInjectedHostStorage() {
+    return injectedStorage;
+}
+function configureDiskFullFault(_ctx) {
+    const previous = injectedStorage;
+    injectedStorage = new EnospcStorageAdapter(new InMemoryStorageAdapter());
+    return () => {
+        injectedStorage = previous;
+    };
+}
+export const HOST_FAULT_MODULES = [
+    {
+        name: "host-disk-full",
+        seam: "host",
+        configure: configureDiskFullFault
+    }
+];
+/** Registers every host-seam fault module this harness implements. Called
+ * once from `faults/index.ts`'s module-load side effect — safe to call
+ * again, last-write-wins. */
+export function registerHostFaultModules() {
+    for (const module of HOST_FAULT_MODULES) {
+        registerFaultModule(module);
+    }
+}
+//# sourceMappingURL=host-faults.js.map

package/dist/faults/host-faults.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-faults.js","sourceRoot":"","sources":["../../src/faults/host-faults.ts"],"names":[],"mappings":"AA6BA,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAUpD,SAAS,WAAW,CAAC,GAAW;IAC9B,MAAM,GAAG,GAAG,IAAI,KAAK,CACnB,2CAA2C,GAAG,GAAG,CACzB,CAAC;IAC3B,GAAG,CAAC,IAAI,GAAG,QAAQ,CAAC;IACpB,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;+DAE+D;AAC/D,MAAM,oBAAoB;IACK,KAAK;IAAlC,YAA6B,KAAqB;qBAArB,KAAK;IAAmB,CAAC;IAEtD,KAAK,CAAC,GAAW;QACf,MAAM,WAAW,CAAC,GAAG,CAAC,CAAC;IACzB,CAAC;IAED,QAAQ,CAAC,GAAW;QAClB,OAAO,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;IAClC,CAAC;IAED,MAAM,CAAC,GAAW;QAChB,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAChC,CAAC;IAED,SAAS,CAAC,GAAW;QACnB,OAAO,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;IACnC,CAAC;IAED,IAAI,CACF,MAAc,EACd,IAA6B;QAE7B,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IACvC,CAAC;IAED,MAAM,CAAC,GAAW;QAChB,MAAM,WAAW,CAAC,GAAG,CAAC,CAAC;IACzB,CAAC;IAED,IAAI,CAAC,GAAW;QACd,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC9B,CAAC;IAED,SAAS,CAAC,GAAW;QACnB,OAAO,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;IACnC,CAAC;CACF;AAED,IAAI,eAAe,GAA0B,IAAI,CAAC;AAElD;;4BAE4B;AAC5B,MAAM,UAAU,sBAAsB;IACpC,OAAO,eAAe,CAAC;AACzB,CAAC;AAED,SAAS,sBAAsB,CAAC,IAAkB;IAChD,MAAM,QAAQ,GAAG,eAAe,CAAC;IACjC,eAAe,GAAG,IAAI,oBAAoB,CAAC,IAAI,sBAAsB,EAAE,CAAC,CAAC;IACzE,OAAO,GAAG,EAAE;QACV,eAAe,GAAG,QAAQ,CAAC;IAC7B,CAAC,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,MAAM,kBAAkB,GAA2B;IACxD;QACE,IAAI,EAAE,gBAAgB;QACtB,IAAI,EAAE,MAAM;QACZ,SAAS,EAAE,sBAAsB;KAClC;CACF,CAAC;AAEF;;6BAE6B;AAC7B,MAAM,UAAU,wBAAwB;IACtC,KAAK,MAAM,MAAM,IAAI,kBAAkB,EAAE,CAAC;QACxC,mBAAmB,CAAC,MAAM,CAAC,CAAC;IAC9B,CAAC;AACH,CAAC"}

package/dist/faults/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Fault layer barrel (task D1). Importing this module registers every
+ * built-in fault module as a side effect — the same "import to register"
+ * shape `@nodetool-ai/base-nodes`' `registerBaseNodes` and this harness's own
+ * `registerFixtureNodes` use — so `compare.ts`/`cli.ts` only need to import
+ * `faults/index.js` once to have every known fault name resolvable.
+ *
+ * D2 (WS proxy) and D3 (bridge/host) add a sibling module file exporting
+ * their own `FaultModule[]` plus a `register*FaultModules()` function, call
+ * it from this barrel, and are done — `types.ts`/`registry.ts`/`compare.ts`
+ * need no changes.
+ */
+export * from "./types.js";
+export * from "./registry.js";
+export * from "./provider-faults.js";
+export * from "./net-proxy.js";
+export * from "./ws-proxy.js";
+export * from "./ws-faults.js";
+export * from "./bridge-faults.js";
+export * from "./host-faults.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/faults/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/faults/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,sBAAsB,CAAC;AACrC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC"}

package/dist/faults/index.js

@@ -0,0 +1,29 @@
+/**
+ * Fault layer barrel (task D1). Importing this module registers every
+ * built-in fault module as a side effect — the same "import to register"
+ * shape `@nodetool-ai/base-nodes`' `registerBaseNodes` and this harness's own
+ * `registerFixtureNodes` use — so `compare.ts`/`cli.ts` only need to import
+ * `faults/index.js` once to have every known fault name resolvable.
+ *
+ * D2 (WS proxy) and D3 (bridge/host) add a sibling module file exporting
+ * their own `FaultModule[]` plus a `register*FaultModules()` function, call
+ * it from this barrel, and are done — `types.ts`/`registry.ts`/`compare.ts`
+ * need no changes.
+ */
+export * from "./types.js";
+export * from "./registry.js";
+export * from "./provider-faults.js";
+export * from "./net-proxy.js";
+export * from "./ws-proxy.js";
+export * from "./ws-faults.js";
+export * from "./bridge-faults.js";
+export * from "./host-faults.js";
+import { registerProviderFaultModules } from "./provider-faults.js";
+import { registerWsFaultModules } from "./ws-faults.js";
+import { registerBridgeFaultModules } from "./bridge-faults.js";
+import { registerHostFaultModules } from "./host-faults.js";
+registerProviderFaultModules();
+registerWsFaultModules();
+registerBridgeFaultModules();
+registerHostFaultModules();
+//# sourceMappingURL=index.js.map

package/dist/faults/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/faults/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,sBAAsB,CAAC;AACrC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AAEjC,OAAO,EAAE,4BAA4B,EAAE,MAAM,sBAAsB,CAAC;AACpE,OAAO,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,EAAE,0BAA0B,EAAE,MAAM,oBAAoB,CAAC;AAChE,OAAO,EAAE,wBAAwB,EAAE,MAAM,kBAAkB,CAAC;AAE5D,4BAA4B,EAAE,CAAC;AAC/B,sBAAsB,EAAE,CAAC;AACzB,0BAA0B,EAAE,CAAC;AAC7B,wBAAwB,EAAE,CAAC"}

package/dist/faults/net-proxy.d.ts

@@ -0,0 +1,75 @@
+/** The six `ws-*` fault kinds §9 names, mapped 1:1 onto `cli.ts`'s
+ * `KNOWN_FAULT_TYPES` `ws-*` entries (`ws-faults.ts` does that mapping). */
+export type WsProxyFaultKind = "drop-no-fin" | "delay" | "reorder" | "fragment" | "stall-reads" | "abrupt-close";
+export interface WsProxyFaultConfig {
+    kind: WsProxyFaultKind;
+    /**
+     * Frame-count anchor: the fault arms on the first frame *after* this many
+     * frames have already been forwarded in the fault's relevant direction
+     * (server->client for every kind except `abrupt-close`, which counts
+     * client->server frames — see the class doc). Default 0: arm immediately,
+     * i.e. on the very first frame.
+     */
+    afterFrames?: number;
+    /** `delay` only: fixed added latency per chunk, ms. Default 200. */
+    delayMs?: number;
+    /** `fragment` only: TCP-write chunk size in bytes. Default 4. */
+    chunkBytes?: number;
+}
+/**
+ * Incrementally counts complete WebSocket frames in a byte stream that may
+ * arrive split across many `data` events. Parses only the frame header
+ * (RFC 6455 §5.2 — 2-10 header bytes plus an optional 4-byte mask key) to
+ * find each frame's total length; payload bytes are never inspected. Good
+ * enough for frame-boundary anchoring — not a full WS parser (continuation
+ * frames are counted as their own frame, which is fine: this harness's
+ * fixture messages are always single-frame sends).
+ */
+export declare class WsFrameCounter {
+    private buf;
+    /** Number of complete frames seen so far. */
+    count: number;
+    feed(chunk: Buffer): void;
+    /** Returns the total byte length of the frame starting at `buf[0]`, or
+     * `null` if `buf` doesn't yet hold a complete header. */
+    static tryFrameLength(buf: Buffer): number | null;
+}
+/**
+ * One TCP proxy instance in front of one `(targetHost, targetPort)`. Every
+ * accepted client connection gets its own pair of pipes (client->server,
+ * server->client); `fault` (settable any time via {@link setFault}) governs
+ * both pipes of every connection accepted while it's set — matching how a
+ * real network fault (a flaky link, a saturated NAT table) affects whatever
+ * is talking over it, not just connections opened after the fault started.
+ */
+export declare class WsFaultProxy {
+    private readonly targetHost;
+    private readonly targetPort;
+    private fault;
+    private server;
+    private readonly connections;
+    private port;
+    constructor(targetHost: string, targetPort: number, fault?: WsProxyFaultConfig | null);
+    setFault(fault: WsProxyFaultConfig | null): void;
+    listen(): Promise<number>;
+    getPort(): number;
+    close(): Promise<void>;
+    /**
+     * Forces every currently-open connection's pair dead — used by the
+     * client-reconnect-mid-run journey to sever a client mid-run outside the
+     * declarative fault matrix. `"reset"` destroys both sockets (an ordinary
+     * TCP RST/FIN teardown); `"half-open"` stops all forwarding and pauses
+     * both sockets' reads without closing either — the same net-level black
+     * hole `drop-no-fin` produces, just triggered on demand instead of after
+     * a frame count.
+     */
+    killConnections(mode: "reset" | "half-open"): void;
+    private handleConnection;
+    /** Builds the `data`-event handler for one direction of one connection.
+     * Per-pipe state (the frame counter, the one-shot flags below) lives in
+     * this closure, not on the proxy or the connection entry, so concurrent
+     * connections and the two directions of the same connection never share
+     * counters. */
+    private makePipe;
+}
+//# sourceMappingURL=net-proxy.d.ts.map

package/dist/faults/net-proxy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"net-proxy.d.ts","sourceRoot":"","sources":["../../src/faults/net-proxy.ts"],"names":[],"mappings":"AAqBA;4EAC4E;AAC5E,MAAM,MAAM,gBAAgB,GACxB,aAAa,GACb,OAAO,GACP,SAAS,GACT,UAAU,GACV,aAAa,GACb,cAAc,CAAC;AAEnB,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,gBAAgB,CAAC;IACvB;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,oEAAoE;IACpE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iEAAiE;IACjE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAOD;;;;;;;;GAQG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,GAAG,CAA2B;IACtC,6CAA6C;IAC7C,KAAK,SAAK;IAEV,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAQxB;IAED;6DACyD;IACzD,MAAM,CAAC,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAiBhD;CACF;AAmCD;;;;;;;GAOG;AACH,qBAAa,YAAY;IAMrB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,KAAK;IAPf,OAAO,CAAC,MAAM,CAAuB;IACrC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAgC;IAC5D,OAAO,CAAC,IAAI,CAAK;IAEjB,YACmB,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAC3B,KAAK,GAAE,kBAAkB,GAAG,IAAW,EAC7C;IAEJ,QAAQ,CAAC,KAAK,EAAE,kBAAkB,GAAG,IAAI,GAAG,IAAI,CAE/C;IAEK,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC,CAS9B;IAED,OAAO,IAAI,MAAM,CAEhB;IAEK,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAW3B;IAED;;;;;;;;OAQG;IACH,eAAe,CAAC,IAAI,EAAE,OAAO,GAAG,WAAW,GAAG,IAAI,CAUjD;IAED,OAAO,CAAC,gBAAgB;IAwBxB;;;;mBAIe;IACf,OAAO,CAAC,QAAQ;CAuHjB"}

package/dist/faults/net-proxy.js

@@ -0,0 +1,305 @@
+/**
+ * Net-level TCP fault proxy (docs/RELIABILITY_ARCHITECTURE.md §9 "WS
+ * transport" row; task D2). Sits in front of a real TCP server (the
+ * ws-server driver's hermetic `e2e-server`) and forwards bytes verbatim in
+ * both directions until a configured {@link WsProxyFaultConfig} tells one
+ * direction's pipe to misbehave.
+ *
+ * This is a raw byte-level proxy, not a WebSocket-aware one — it never
+ * terminates the WS handshake or decodes frame payloads. The one thing it
+ * does parse is the RFC 6455 frame *header* (via {@link WsFrameCounter}), just
+ * enough to find frame boundaries in the byte stream so a fault can be
+ * anchored on "after N frames" rather than an arbitrary byte count or a
+ * wall-clock delay (§9: "event-anchored, not time-anchored", mirroring
+ * `drivers/anchors.ts`'s message-type anchors one layer down, at the wire
+ * instead of the decoded message).
+ *
+ * `ws-proxy.ts` is the seam-facing half (process-wide "is a fault active"
+ * state the `WsServerDriver` consults); this file is the mechanism.
+ */
+import { connect, createServer } from "node:net";
+/**
+ * Incrementally counts complete WebSocket frames in a byte stream that may
+ * arrive split across many `data` events. Parses only the frame header
+ * (RFC 6455 §5.2 — 2-10 header bytes plus an optional 4-byte mask key) to
+ * find each frame's total length; payload bytes are never inspected. Good
+ * enough for frame-boundary anchoring — not a full WS parser (continuation
+ * frames are counted as their own frame, which is fine: this harness's
+ * fixture messages are always single-frame sends).
+ */
+export class WsFrameCounter {
+    buf = Buffer.alloc(0);
+    /** Number of complete frames seen so far. */
+    count = 0;
+    feed(chunk) {
+        this.buf = this.buf.length > 0 ? Buffer.concat([this.buf, chunk]) : chunk;
+        for (;;) {
+            const frameLength = WsFrameCounter.tryFrameLength(this.buf);
+            if (frameLength === null || this.buf.length < frameLength)
+                return;
+            this.count += 1;
+            this.buf = this.buf.subarray(frameLength);
+        }
+    }
+    /** Returns the total byte length of the frame starting at `buf[0]`, or
+     * `null` if `buf` doesn't yet hold a complete header. */
+    static tryFrameLength(buf) {
+        if (buf.length < 2)
+            return null;
+        const secondByte = buf[1];
+        const masked = (secondByte & 0x80) !== 0;
+        let payloadLength = secondByte & 0x7f;
+        let offset = 2;
+        if (payloadLength === 126) {
+            if (buf.length < 4)
+                return null;
+            payloadLength = buf.readUInt16BE(2);
+            offset = 4;
+        }
+        else if (payloadLength === 127) {
+            if (buf.length < 10)
+                return null;
+            payloadLength = Number(buf.readBigUInt64BE(2));
+            offset = 10;
+        }
+        if (masked)
+            offset += 4;
+        return offset + payloadLength;
+    }
+}
+/**
+ * Writes `chunk` to `socket` in `chunkBytes`-sized pieces. Synchronous and
+ * loop-based (not `setImmediate`-deferred) on purpose: this runs inside a
+ * `data` event handler, and a deferred, multi-tick version can still be
+ * mid-flight when the *next* `data` event fires on the same socket pair —
+ * two concurrently-running fragmenters racing to `write()` the same
+ * destination socket interleave their pieces and corrupt the byte stream.
+ * A single synchronous loop can't race anything: it either fully finishes
+ * before the next `data` event is even dispatched, or the destination socket
+ * is already destroyed (checked per piece) and the rest is silently dropped.
+ */
+function writeFragmented(socket, chunk, chunkBytes) {
+    const step = Math.max(1, chunkBytes);
+    for (let offset = 0; offset < chunk.length; offset += step) {
+        if (socket.destroyed)
+            return;
+        socket.write(chunk.subarray(offset, Math.min(offset + step, chunk.length)));
+    }
+}
+/** Which direction a given fault kind's frame-count anchor applies to.
+ * `abrupt-close` models "close hard right after the run_job command is
+ * forwarded" (§9) — every journey's first `client_to_server` frame is the
+ * `run_job` command envelope (`ws-server.ts`'s driver always sends `run`
+ * first), so counting client->server frames with the default `afterFrames:
+ * 0` closes right after that command reaches the server. Every other kind
+ * targets server->client frames — the direction a client's parser actually
+ * has to tolerate misbehaving. */
+function relevantDirection(kind) {
+    return kind === "abrupt-close" ? "client-to-server" : "server-to-client";
+}
+/**
+ * One TCP proxy instance in front of one `(targetHost, targetPort)`. Every
+ * accepted client connection gets its own pair of pipes (client->server,
+ * server->client); `fault` (settable any time via {@link setFault}) governs
+ * both pipes of every connection accepted while it's set — matching how a
+ * real network fault (a flaky link, a saturated NAT table) affects whatever
+ * is talking over it, not just connections opened after the fault started.
+ */
+export class WsFaultProxy {
+    targetHost;
+    targetPort;
+    fault;
+    server = null;
+    connections = new Set();
+    port = 0;
+    constructor(targetHost, targetPort, fault = null) {
+        this.targetHost = targetHost;
+        this.targetPort = targetPort;
+        this.fault = fault;
+    }
+    setFault(fault) {
+        this.fault = fault;
+    }
+    async listen() {
+        this.server = createServer((clientSocket) => this.handleConnection(clientSocket));
+        await new Promise((resolve, reject) => {
+            this.server.once("error", reject);
+            this.server.listen(0, "127.0.0.1", () => resolve());
+        });
+        const address = this.server.address();
+        this.port = typeof address === "object" && address !== null ? address.port : 0;
+        return this.port;
+    }
+    getPort() {
+        return this.port;
+    }
+    async close() {
+        for (const conn of this.connections) {
+            conn.clientSocket.destroy();
+            conn.serverSocket.destroy();
+        }
+        this.connections.clear();
+        const server = this.server;
+        this.server = null;
+        if (server) {
+            await new Promise((resolve) => server.close(() => resolve()));
+        }
+    }
+    /**
+     * Forces every currently-open connection's pair dead — used by the
+     * client-reconnect-mid-run journey to sever a client mid-run outside the
+     * declarative fault matrix. `"reset"` destroys both sockets (an ordinary
+     * TCP RST/FIN teardown); `"half-open"` stops all forwarding and pauses
+     * both sockets' reads without closing either — the same net-level black
+     * hole `drop-no-fin` produces, just triggered on demand instead of after
+     * a frame count.
+     */
+    killConnections(mode) {
+        for (const conn of this.connections) {
+            if (mode === "reset") {
+                conn.clientSocket.destroy();
+                conn.serverSocket.destroy();
+            }
+            else {
+                conn.clientSocket.pause();
+                conn.serverSocket.pause();
+            }
+        }
+    }
+    handleConnection(clientSocket) {
+        const serverSocket = connect(this.targetPort, this.targetHost);
+        const entry = { clientSocket, serverSocket };
+        this.connections.add(entry);
+        clientSocket.setNoDelay(true);
+        serverSocket.setNoDelay(true);
+        let cleaned = false;
+        const cleanup = () => {
+            if (cleaned)
+                return;
+            cleaned = true;
+            this.connections.delete(entry);
+            clientSocket.destroy();
+            serverSocket.destroy();
+        };
+        clientSocket.on("error", cleanup);
+        serverSocket.on("error", cleanup);
+        clientSocket.on("close", cleanup);
+        serverSocket.on("close", cleanup);
+        clientSocket.on("data", this.makePipe(clientSocket, serverSocket, "client-to-server"));
+        serverSocket.on("data", this.makePipe(serverSocket, clientSocket, "server-to-client"));
+    }
+    /** Builds the `data`-event handler for one direction of one connection.
+     * Per-pipe state (the frame counter, the one-shot flags below) lives in
+     * this closure, not on the proxy or the connection entry, so concurrent
+     * connections and the two directions of the same connection never share
+     * counters. */
+    makePipe(from, to, direction) {
+        const counter = new WsFrameCounter();
+        let blackHoled = false;
+        let reorderPending = null;
+        // The very first bytes in either direction are the plain-text HTTP
+        // Upgrade request/response, not a WS frame at all — `WsFrameCounter`'s
+        // frame-header parser applied to arbitrary HTTP header bytes produces a
+        // garbage "frame length" that usually resolves within the header block
+        // itself, silently arming a fault (and, for `drop-no-fin`/`stall-reads`,
+        // swallowing the 101 response before the client ever sees it) during
+        // the handshake instead of the application traffic the fault is meant to
+        // target. Every fault kind is a no-op (plain pass-through, no counting)
+        // until this direction's own handshake terminator (`\r\n\r\n`) has been
+        // seen; a connection whose handshake never terminates within 16 KiB
+        // (never happens for this harness's own client/server) falls back to
+        // fault-active rather than hanging the scan forever.
+        let handshakeDone = false;
+        let handshakeScan = Buffer.alloc(0);
+        return (chunk) => {
+            if (blackHoled)
+                return;
+            if (!handshakeDone) {
+                to.write(chunk);
+                handshakeScan =
+                    handshakeScan.length > 0 ? Buffer.concat([handshakeScan, chunk]) : chunk;
+                if (handshakeScan.includes("\r\n\r\n") || handshakeScan.length > 16384) {
+                    handshakeDone = true;
+                }
+                return;
+            }
+            const fault = this.fault;
+            if (!fault || direction !== relevantDirection(fault.kind)) {
+                to.write(chunk);
+                return;
+            }
+            counter.feed(chunk);
+            const armed = counter.count > (fault.afterFrames ?? 0);
+            switch (fault.kind) {
+                case "drop-no-fin":
+                    // Half-open: once armed, never forward and never close either
+                    // socket — a live-looking connection nothing moves on.
+                    if (armed) {
+                        blackHoled = true;
+                        return;
+                    }
+                    to.write(chunk);
+                    return;
+                case "abrupt-close":
+                    // Forward the frame that arms the fault (the run_job command
+                    // itself must actually reach the server), then hang up hard —
+                    // no FIN, no close frame — right after.
+                    to.write(chunk);
+                    if (armed) {
+                        blackHoled = true;
+                        from.destroy();
+                        to.destroy();
+                    }
+                    return;
+                case "stall-reads":
+                    // Stop reading from `from` (the server side) once armed — its
+                    // socket buffer, then its own send buffer, backs up because
+                    // nothing drains it, which is the drain-timeout path's trigger.
+                    // The client-facing socket is untouched: any already-forwarded
+                    // bytes remain delivered.
+                    if (armed) {
+                        blackHoled = true;
+                        from.pause();
+                        return;
+                    }
+                    to.write(chunk);
+                    return;
+                case "delay":
+                    setTimeout(() => {
+                        if (!to.destroyed)
+                            to.write(chunk);
+                    }, fault.delayMs ?? 200);
+                    return;
+                case "fragment":
+                    writeFragmented(to, chunk, fault.chunkBytes ?? 4);
+                    return;
+                case "reorder":
+                    // Swap exactly one adjacent pair once armed, then resume in-order
+                    // forwarding — enough to exercise a client's/server's tolerance
+                    // for a single out-of-order delivery without permanently
+                    // reordering the whole stream.
+                    if (!armed) {
+                        to.write(chunk);
+                        return;
+                    }
+                    if (reorderPending === null) {
+                        reorderPending = chunk;
+                        return;
+                    }
+                    // Synchronous double-write, not `setImmediate`-deferred — same
+                    // interleaving hazard `writeFragmented` has: a deferred write can
+                    // still be pending when the next `data` event's own writes land,
+                    // putting bytes on `to` out of the order this fault itself
+                    // intended.
+                    {
+                        const previous = reorderPending;
+                        reorderPending = null;
+                        to.write(chunk);
+                        to.write(previous);
+                    }
+                    return;
+            }
+        };
+    }
+}
+//# sourceMappingURL=net-proxy.js.map