@moltzap/protocol 2026.401.0 → 2026.425.0

package/dist/testing/arbitraries/rpc.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Per-`RpcMethodName` arbitrary and the `allRpcMethods` walker.
+ *
+ * Tier A's A5 (RpcMap coverage) and Tier B's B1 (model equivalence) both
+ * iterate every method name. Centralizing the iterator here keeps the
+ * property bodies compiler-checked against `RpcMap`.
+ */
+import * as fc from "fast-check";
+import { type RpcMap, type RpcMethodName } from "../../rpc-registry.js";
+/**
+ * A single drawn RPC invocation: the method name carries through to the
+ * reference model so it can pick the matching reducer.
+ */
+export interface ArbitraryRpcCall<M extends RpcMethodName = RpcMethodName> {
+    readonly method: M;
+    readonly params: RpcMap[M]["params"];
+}
+/**
+ * Ordered list of every `RpcMethodName`. Exposed so properties can assert
+ * "every method exercised at least once" without going through `RpcMap`
+ * directly.
+ */
+export declare const allRpcMethods: ReadonlyArray<RpcMethodName>;
+/** Arbitrary of a valid params tree for a single, fixed RPC. */
+export declare function arbitraryCallFor<M extends RpcMethodName>(method: M): fc.Arbitrary<ArbitraryRpcCall<M>>;
+/**
+ * Arbitrary that draws any method name + matching params. Used by Tier A
+ * A5 and by Tier E E2's cross-RPC fuzz.
+ */
+export declare function arbitraryAnyCall(): fc.Arbitrary<ArbitraryRpcCall>;
+/**
+ * The set of `RpcMethodName`s the reference model predicts `_tag: "ok"`
+ * for on `initialReferenceState` — derived mechanically at module load
+ * by probing `applyCall` with a single drawn params value per method.
+ *
+ * Per architect #197 §2.2: this is NOT a hand-curated list. Methods
+ * move in/out of the confident set automatically when `applyCall`'s
+ * `allowNoEvents` / `uncertainError` split moves, so the sampling
+ * distribution tracks the model.
+ *
+ * **Param-invariance contract:** every kept method is treated as
+ * oracle-confident for every params value. If a future `applyCall`
+ * amendment branches on `call.params`, the safety-net guard in
+ * `registerModelEquivalence` (rpc-semantics.ts) fires loudly on the
+ * first non-confident draw and the derivation must widen from the
+ * single-probe form to an `fc.sample`-based invariant check.
+ */
+export declare const confidentOracleMethods: ReadonlyArray<RpcMethodName>;
+/**
+ * Draw a call from the model's confident-oracle set. Per architect
+ * #197 §2.2 literal shape: `fc.constantFrom(...kept).chain(
+ * arbitraryCallFor)`. Probe at module load uses the same
+ * `arbitraryCallFor(m)` generator as execution — so confidence is
+ * checked on the same distribution the property exercises.
+ *
+ * If a kept method turns out to be param-sensitive under a later
+ * draw (model predicts ok for the one probe sample but rejects a
+ * subsequent arbitrary-drawn params), the safety-net guard in
+ * `registerModelEquivalence` raises `PropertyInvariantViolation`
+ * pointing at this file — the fix is to widen the derivation (probe
+ * K > 1 samples and keep only methods where every probe predicts ok)
+ * per the architect's contract. Single-probe is sufficient when
+ * `applyCall` is method-only (today).
+ */
+export declare function arbitraryConfidentCall(): fc.Arbitrary<ArbitraryRpcCall>;
+//# sourceMappingURL=rpc.d.ts.map

package/dist/testing/arbitraries/rpc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rpc.d.ts","sourceRoot":"","sources":["../../../src/testing/arbitraries/rpc.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,MAAM,YAAY,CAAC;AACjC,OAAO,EAEL,KAAK,MAAM,EACX,KAAK,aAAa,EACnB,MAAM,uBAAuB,CAAC;AAK/B;;;GAGG;AACH,MAAM,WAAW,gBAAgB,CAAC,CAAC,SAAS,aAAa,GAAG,aAAa;IACvE,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;IACnB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;CACtC;AAED;;;;GAIG;AACH,eAAO,MAAM,aAAa,EAAE,aAAa,CAAC,aAAa,CAEtD,CAAC;AAKF,gEAAgE;AAChE,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,aAAa,EACtD,MAAM,EAAE,CAAC,GACR,EAAE,CAAC,SAAS,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAYnC;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI,EAAE,CAAC,SAAS,CAAC,gBAAgB,CAAC,CAKjE;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,sBAAsB,EAAE,aAAa,CAAC,aAAa,CAY5D,CAAC;AAEL;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,sBAAsB,IAAI,EAAE,CAAC,SAAS,CAAC,gBAAgB,CAAC,CASvE"}

package/dist/testing/arbitraries/rpc.js

@@ -0,0 +1,98 @@
+/**
+ * Per-`RpcMethodName` arbitrary and the `allRpcMethods` walker.
+ *
+ * Tier A's A5 (RpcMap coverage) and Tier B's B1 (model equivalence) both
+ * iterate every method name. Centralizing the iterator here keeps the
+ * property bodies compiler-checked against `RpcMap`.
+ */
+import * as fc from "fast-check";
+import { rpcMethods, } from "../../rpc-registry.js";
+import { applyCall } from "../models/dispatch.js";
+import { initialReferenceState } from "../models/state.js";
+import { arbitraryForParams } from "./from-typebox.js";
+/**
+ * Ordered list of every `RpcMethodName`. Exposed so properties can assert
+ * "every method exercised at least once" without going through `RpcMap`
+ * directly.
+ */
+export const allRpcMethods = rpcMethods.map((m) => m.name);
+// Precomputed lookup from wire name → manifest, so `arbitraryCallFor` is O(1).
+const methodByName = new Map(rpcMethods.map((m) => [m.name, m]));
+/** Arbitrary of a valid params tree for a single, fixed RPC. */
+export function arbitraryCallFor(method) {
+    const def = methodByName.get(method);
+    if (def === undefined) {
+        throw new Error(`arbitraryCallFor: unknown method ${String(method)}`);
+    }
+    return arbitraryForParams(def.paramsSchema).map((params) => ({
+        method,
+        params: params,
+    }));
+}
+/**
+ * Arbitrary that draws any method name + matching params. Used by Tier A
+ * A5 and by Tier E E2's cross-RPC fuzz.
+ */
+export function arbitraryAnyCall() {
+    if (allRpcMethods.length === 0) {
+        throw new Error("arbitraryAnyCall: rpcMethods empty");
+    }
+    return fc.constantFrom(...allRpcMethods).chain((m) => arbitraryCallFor(m));
+}
+/**
+ * The set of `RpcMethodName`s the reference model predicts `_tag: "ok"`
+ * for on `initialReferenceState` — derived mechanically at module load
+ * by probing `applyCall` with a single drawn params value per method.
+ *
+ * Per architect #197 §2.2: this is NOT a hand-curated list. Methods
+ * move in/out of the confident set automatically when `applyCall`'s
+ * `allowNoEvents` / `uncertainError` split moves, so the sampling
+ * distribution tracks the model.
+ *
+ * **Param-invariance contract:** every kept method is treated as
+ * oracle-confident for every params value. If a future `applyCall`
+ * amendment branches on `call.params`, the safety-net guard in
+ * `registerModelEquivalence` (rpc-semantics.ts) fires loudly on the
+ * first non-confident draw and the derivation must widen from the
+ * single-probe form to an `fc.sample`-based invariant check.
+ */
+export const confidentOracleMethods = (() => {
+    // `models/dispatch.ts` imports `ArbitraryRpcCall` as a type-only
+    // reference, so the values imported above (`applyCall`,
+    // `initialReferenceState`) are safe to call at module load.
+    const kept = [];
+    for (const method of allRpcMethods) {
+        const [sample] = fc.sample(arbitraryCallFor(method), 1);
+        if (sample === undefined)
+            continue;
+        const outcome = applyCall(initialReferenceState, sample).outcome;
+        if (outcome._tag === "ok")
+            kept.push(method);
+    }
+    return kept;
+})();
+/**
+ * Draw a call from the model's confident-oracle set. Per architect
+ * #197 §2.2 literal shape: `fc.constantFrom(...kept).chain(
+ * arbitraryCallFor)`. Probe at module load uses the same
+ * `arbitraryCallFor(m)` generator as execution — so confidence is
+ * checked on the same distribution the property exercises.
+ *
+ * If a kept method turns out to be param-sensitive under a later
+ * draw (model predicts ok for the one probe sample but rejects a
+ * subsequent arbitrary-drawn params), the safety-net guard in
+ * `registerModelEquivalence` raises `PropertyInvariantViolation`
+ * pointing at this file — the fix is to widen the derivation (probe
+ * K > 1 samples and keep only methods where every probe predicts ok)
+ * per the architect's contract. Single-probe is sufficient when
+ * `applyCall` is method-only (today).
+ */
+export function arbitraryConfidentCall() {
+    if (confidentOracleMethods.length === 0) {
+        throw new Error("arbitraryConfidentCall: model has zero confident-oracle methods; flag needs-structural-rework");
+    }
+    return fc
+        .constantFrom(...confidentOracleMethods)
+        .chain((method) => arbitraryCallFor(method));
+}
+//# sourceMappingURL=rpc.js.map

package/dist/testing/arbitraries/rpc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rpc.js","sourceRoot":"","sources":["../../../src/testing/arbitraries/rpc.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,MAAM,YAAY,CAAC;AACjC,OAAO,EACL,UAAU,GAGX,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAClD,OAAO,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAWvD;;;;GAIG;AACH,MAAM,CAAC,MAAM,aAAa,GAAiC,UAAU,CAAC,GAAG,CACvE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CACd,CAAC;AAEF,+EAA+E;AAC/E,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;AAEjE,gEAAgE;AAChE,MAAM,UAAU,gBAAgB,CAC9B,MAAS;IAET,MAAM,GAAG,GAAG,YAAY,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IACrC,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;QACtB,MAAM,IAAI,KAAK,CAAC,oCAAoC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IACxE,CAAC;IACD,OAAO,kBAAkB,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC,GAAG,CAC7C,CAAC,MAAM,EAAE,EAAE,CACT,CAAC;QACC,MAAM;QACN,MAAM,EAAE,MAA6B;KACtC,CAAU,CACd,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB;IAC9B,IAAI,aAAa,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC/B,MAAM,IAAI,KAAK,CAAC,oCAAoC,CAAC,CAAC;IACxD,CAAC;IACD,OAAO,EAAE,CAAC,YAAY,CAAC,GAAG,aAAa,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAC;AAC7E,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAiC,CAAC,GAAG,EAAE;IACxE,iEAAiE;IACjE,wDAAwD;IACxD,4DAA4D;IAC5D,MAAM,IAAI,GAAoB,EAAE,CAAC;IACjC,KAAK,MAAM,MAAM,IAAI,aAAa,EAAE,CAAC;QACnC,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,gBAAgB,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC;QACxD,IAAI,MAAM,KAAK,SAAS;YAAE,SAAS;QACnC,MAAM,OAAO,GAAG,SAAS,CAAC,qBAAqB,EAAE,MAAM,CAAC,CAAC,OAAO,CAAC;QACjE,IAAI,OAAO,CAAC,IAAI,KAAK,IAAI;YAAE,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC/C,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC,CAAC,EAAE,CAAC;AAEL;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,sBAAsB;IACpC,IAAI,sBAAsB,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxC,MAAM,IAAI,KAAK,CACb,+FAA+F,CAChG,CAAC;IACJ,CAAC;IACD,OAAO,EAAE;SACN,YAAY,CAAC,GAAG,sBAAsB,CAAC;SACvC,KAAK,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC,CAAC;AACjD,CAAC"}

package/dist/testing/canonicalize.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Canonicalization primitives — narrow, composable building blocks for
+ * body-compare property assertions.
+ *
+ * Per architect #197 §3: properties that compare response bodies route
+ * through a named canonical-projection function that normalizes order
+ * **only where the protocol spec marks it unordered**. These primitives
+ * let the property author that projection without reaching for a
+ * blanket deep-sort that would hide real re-ordering regressions inside
+ * nested arrays.
+ *
+ * Callers cite the spec clause for each array they sort, in JSDoc on
+ * the projection. Reviewer spot-checks during stamina pass.
+ *
+ * No blanket `canonicalizeUnordered` helper: picking which arrays to
+ * sort is a spec decision, not an ergonomic default.
+ */
+/**
+ * Sort a JSON-array by the canonical stringification of each element.
+ * Shallow: does NOT recurse into elements. Caller composes with
+ * `sortObjectKeysDeep` per element if element-wise key-order stability
+ * matters. Preserves input immutability (returns a fresh array).
+ */
+export declare function sortJsonArray(arr: ReadonlyArray<unknown>): ReadonlyArray<unknown>;
+/**
+ * Deep key-sort on objects; array order preserved at every depth.
+ * Use before final `JSON.stringify` so key-order noise does not break
+ * byte-compare. Safe to apply over any payload.
+ */
+export declare function sortObjectKeysDeep(value: unknown): unknown;
+/**
+ * Final stable serialization: `sortObjectKeysDeep → JSON.stringify`.
+ * Intended as the last step after the property has applied whatever
+ * array-scoped sorts its spec citation allows. Array order is
+ * preserved; object key order is normalized.
+ */
+export declare function canonicalJson(value: unknown): string;
+//# sourceMappingURL=canonicalize.d.ts.map

package/dist/testing/canonicalize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonicalize.d.ts","sourceRoot":"","sources":["../../src/testing/canonicalize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,GAAG,EAAE,aAAa,CAAC,OAAO,CAAC,GAC1B,aAAa,CAAC,OAAO,CAAC,CAIxB;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAS1D;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEpD"}

package/dist/testing/canonicalize.js

@@ -0,0 +1,55 @@
+/**
+ * Canonicalization primitives — narrow, composable building blocks for
+ * body-compare property assertions.
+ *
+ * Per architect #197 §3: properties that compare response bodies route
+ * through a named canonical-projection function that normalizes order
+ * **only where the protocol spec marks it unordered**. These primitives
+ * let the property author that projection without reaching for a
+ * blanket deep-sort that would hide real re-ordering regressions inside
+ * nested arrays.
+ *
+ * Callers cite the spec clause for each array they sort, in JSDoc on
+ * the projection. Reviewer spot-checks during stamina pass.
+ *
+ * No blanket `canonicalizeUnordered` helper: picking which arrays to
+ * sort is a spec decision, not an ergonomic default.
+ */
+/**
+ * Sort a JSON-array by the canonical stringification of each element.
+ * Shallow: does NOT recurse into elements. Caller composes with
+ * `sortObjectKeysDeep` per element if element-wise key-order stability
+ * matters. Preserves input immutability (returns a fresh array).
+ */
+export function sortJsonArray(arr) {
+    const keyed = arr.map((el) => ({ el, key: canonicalJson(el) }));
+    keyed.sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
+    return keyed.map((k) => k.el);
+}
+/**
+ * Deep key-sort on objects; array order preserved at every depth.
+ * Use before final `JSON.stringify` so key-order noise does not break
+ * byte-compare. Safe to apply over any payload.
+ */
+export function sortObjectKeysDeep(value) {
+    if (Array.isArray(value))
+        return value.map(sortObjectKeysDeep);
+    if (value === null || typeof value !== "object")
+        return value;
+    const out = {};
+    for (const key of Object.keys(value).sort()) {
+        const v = value[key];
+        out[key] = sortObjectKeysDeep(v);
+    }
+    return out;
+}
+/**
+ * Final stable serialization: `sortObjectKeysDeep → JSON.stringify`.
+ * Intended as the last step after the property has applied whatever
+ * array-scoped sorts its spec citation allows. Array order is
+ * preserved; object key order is normalized.
+ */
+export function canonicalJson(value) {
+    return JSON.stringify(sortObjectKeysDeep(value));
+}
+//# sourceMappingURL=canonicalize.js.map

package/dist/testing/canonicalize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonicalize.js","sourceRoot":"","sources":["../../src/testing/canonicalize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAC3B,GAA2B;IAE3B,MAAM,KAAK,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,GAAG,EAAE,aAAa,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IAChE,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACnE,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;AAChC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAc;IAC/C,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC;IAC/D,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC9D,MAAM,GAAG,GAA4B,EAAE,CAAC;IACxC,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;QAC5C,MAAM,CAAC,GAAa,KAA2C,CAAC,GAAG,CAAC,CAAC;QACrE,GAAG,CAAC,GAAG,CAAC,GAAG,kBAAkB,CAAC,CAAC,CAAC,CAAC;IACnC,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,OAAO,IAAI,CAAC,SAAS,CAAC,kBAAkB,CAAC,KAAK,CAAC,CAAC,CAAC;AACnD,CAAC"}

package/dist/testing/captures.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Bounded, ordered capture buffers. TestClient captures every frame the
+ * real server replied with; TestServer captures every frame a real client
+ * pushed in. Both are append-only ring buffers exposed as `Effect` Streams
+ * so property code can `Stream.take` or `Stream.filter` without racing the
+ * underlying fiber.
+ *
+ * Exhaustiveness: `CaptureKind` discriminates inbound vs outbound so the
+ * same buffer can record both sides when a primitive is proxied through
+ * Toxiproxy (Tier D).
+ */
+import { Effect, Stream } from "effect";
+import type { AnyFrame, MalformedFrameKind } from "./codec.js";
+export type CaptureKind = "inbound" | "outbound";
+/**
+ * One recorded event. `frame` is `null` when the capture is a raw-bytes
+ * record that failed to decode — Tier A's A4 property asserts on both the
+ * raw bytes and the typed `FrameSchemaError` that fired.
+ */
+export interface CapturedFrame {
+    readonly at: number;
+    readonly kind: CaptureKind;
+    readonly raw: string;
+    readonly frame: AnyFrame | null;
+    readonly malformed: MalformedFrameKind | null;
+}
+/** Opaque handle to a running buffer; held by TestClient / TestServer. */
+export interface CaptureBuffer {
+    readonly snapshot: Effect.Effect<ReadonlyArray<CapturedFrame>>;
+    readonly stream: Stream.Stream<CapturedFrame>;
+    readonly clear: Effect.Effect<void>;
+    /** @internal — used by primitives to append. Not exported from barrel. */
+    readonly _publish: (entry: CapturedFrame) => Effect.Effect<void>;
+    /** @internal — soft capacity so `mergeCaptures` can fan messages out safely. */
+    readonly _capacity: number;
+}
+/**
+ * Ring-buffer + PubSub implementation. The Ref holds the bounded
+ * array; PubSub fans each append out to every subscriber so `stream`
+ * behaves as a live tail.
+ */
+export declare function makeCaptureBuffer(opts: {
+    readonly capacity: number;
+}): Effect.Effect<CaptureBuffer>;
+/**
+ * Multiplex captures across many connections — used by Tier C properties
+ * where N real clients emit concurrently and the property asserts on the
+ * merged ordered stream.
+ *
+ * Semantics:
+ *   - `snapshot` returns every buffer's current contents concatenated and
+ *     sorted by `at` (stable for equal timestamps by buffer index).
+ *   - `stream` is `Stream.mergeAll(stream...)` — live events in arrival order.
+ *   - `clear` clears every upstream buffer.
+ */
+export declare function mergeCaptures(buffers: ReadonlyArray<CaptureBuffer>): Effect.Effect<CaptureBuffer>;
+/** Internal hook used by primitives to push a decode failure as-bytes. */
+export declare function recordMalformed(buffer: CaptureBuffer, raw: string, kind: MalformedFrameKind): Effect.Effect<void>;
+/** Internal hook: push a successfully-decoded frame. */
+export declare function recordFrame(buffer: CaptureBuffer, kind: CaptureKind, raw: string, frame: AnyFrame): Effect.Effect<void>;
+//# sourceMappingURL=captures.d.ts.map

package/dist/testing/captures.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"captures.d.ts","sourceRoot":"","sources":["../../src/testing/captures.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAE,MAAM,EAAO,MAAM,EAAU,MAAM,QAAQ,CAAC;AACrD,OAAO,KAAK,EAAE,QAAQ,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAE/D,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,UAAU,CAAC;AAEjD;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,QAAQ,GAAG,IAAI,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE,kBAAkB,GAAG,IAAI,CAAC;CAC/C;AAED,0EAA0E;AAC1E,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,aAAa,CAAC,CAAC,CAAC;IAC/D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC;IAC9C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACpC,0EAA0E;IAC1E,QAAQ,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACjE,gFAAgF;IAChF,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAID;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE;IACtC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B,GAAG,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,CAwB/B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,aAAa,CAAC,aAAa,CAAC,GACpC,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,CAkC9B;AAED,0EAA0E;AAC1E,wBAAgB,eAAe,CAC7B,MAAM,EAAE,aAAa,EACrB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,kBAAkB,GACvB,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAQrB;AAED,wDAAwD;AACxD,wBAAgB,WAAW,CACzB,MAAM,EAAE,aAAa,EACrB,IAAI,EAAE,WAAW,EACjB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,QAAQ,GACd,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAQrB"}

package/dist/testing/captures.js

@@ -0,0 +1,99 @@
+/**
+ * Bounded, ordered capture buffers. TestClient captures every frame the
+ * real server replied with; TestServer captures every frame a real client
+ * pushed in. Both are append-only ring buffers exposed as `Effect` Streams
+ * so property code can `Stream.take` or `Stream.filter` without racing the
+ * underlying fiber.
+ *
+ * Exhaustiveness: `CaptureKind` discriminates inbound vs outbound so the
+ * same buffer can record both sides when a primitive is proxied through
+ * Toxiproxy (Tier D).
+ */
+import { Effect, Ref, Stream, PubSub } from "effect";
+const startTime = Date.now();
+/**
+ * Ring-buffer + PubSub implementation. The Ref holds the bounded
+ * array; PubSub fans each append out to every subscriber so `stream`
+ * behaves as a live tail.
+ */
+export function makeCaptureBuffer(opts) {
+    return Effect.gen(function* () {
+        const cap = Math.max(1, opts.capacity);
+        const ref = yield* Ref.make([]);
+        const pubsub = yield* PubSub.sliding(cap);
+        const publish = (entry) => Effect.gen(function* () {
+            yield* Ref.update(ref, (cur) => {
+                const next = cur.length >= cap ? cur.slice(1) : cur.slice();
+                return [...next, entry];
+            });
+            yield* PubSub.publish(pubsub, entry);
+        });
+        const buf = {
+            snapshot: Ref.get(ref),
+            stream: Stream.fromPubSub(pubsub),
+            clear: Ref.set(ref, []),
+            _publish: publish,
+            _capacity: cap,
+        };
+        return buf;
+    });
+}
+/**
+ * Multiplex captures across many connections — used by Tier C properties
+ * where N real clients emit concurrently and the property asserts on the
+ * merged ordered stream.
+ *
+ * Semantics:
+ *   - `snapshot` returns every buffer's current contents concatenated and
+ *     sorted by `at` (stable for equal timestamps by buffer index).
+ *   - `stream` is `Stream.mergeAll(stream...)` — live events in arrival order.
+ *   - `clear` clears every upstream buffer.
+ */
+export function mergeCaptures(buffers) {
+    return Effect.gen(function* () {
+        const merged = yield* makeCaptureBuffer({
+            capacity: buffers.reduce((sum, b) => sum + b._capacity, 0) || 1,
+        });
+        // Return a view that aggregates snapshots on demand rather than a live
+        // merged copy: the source buffers are authoritative.
+        const snapshot = Effect.gen(function* () {
+            const snaps = yield* Effect.forEach(buffers, (b) => b.snapshot, {
+                concurrency: "unbounded",
+            });
+            const flat = snaps.flat();
+            return [...flat].sort((a, b) => a.at - b.at);
+        });
+        const stream = Stream.mergeAll(buffers.map((b) => b.stream), { concurrency: "unbounded" });
+        const clear = Effect.forEach(buffers, (b) => b.clear, {
+            concurrency: "unbounded",
+        }).pipe(Effect.asVoid);
+        return {
+            snapshot,
+            stream,
+            clear,
+            _publish: merged._publish,
+            _capacity: merged._capacity,
+        };
+    });
+}
+/** Internal hook used by primitives to push a decode failure as-bytes. */
+export function recordMalformed(buffer, raw, kind) {
+    return buffer._publish({
+        at: Date.now() - startTime,
+        kind: "inbound",
+        raw,
+        frame: null,
+        malformed: kind,
+    });
+}
+/** Internal hook: push a successfully-decoded frame. */
+export function recordFrame(buffer, kind, raw, frame) {
+    return buffer._publish({
+        at: Date.now() - startTime,
+        kind,
+        raw,
+        frame,
+        malformed: null,
+    });
+}
+//# sourceMappingURL=captures.js.map

package/dist/testing/captures.js.map

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

package/dist/testing/codec.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Frame codec for the testing primitives.
+ *
+ * Satisfies §5.A1/A2/A3/A4 and Invariant I3: every frame crossing a
+ * primitive is `Value.Check`-validated before it is surfaced to property
+ * code. Malformed-frame arbitraries are generated *here* so Tier A can
+ * inject bit-flips, truncations, and oversized frames without leaking the
+ * malformation strategy into the primitives.
+ */
+import { Effect } from "effect";
+import { type RequestFrame, type ResponseFrame, type EventFrame } from "../schema/frames.js";
+import { FrameSchemaError } from "./errors.js";
+/**
+ * Valid-frame kinds exposed on the wire. The string literal discriminator
+ * matches the `type` field in `RequestFrameSchema` / `ResponseFrameSchema`
+ * and the outer `type: "event"` sentinel for `EventFrameSchema`.
+ */
+export type AnyFrame = ({
+    readonly type: "request";
+} & RequestFrame) | ({
+    readonly type: "response";
+} & ResponseFrame) | ({
+    readonly type: "event";
+} & EventFrame);
+/**
+ * Kinds of malformation Tier A / Tier D-slicer can inject. Each maps to a
+ * deterministic mutation driven by fast-check so shrinks reproduce.
+ */
+export type MalformedFrameKind = "bit-flip" | "truncated" | "oversized" | "invalid-utf8" | "missing-required-field" | "extra-property";
+/** Serialize a typed frame to the wire bytes. */
+export declare function encodeFrame(frame: AnyFrame): string;
+/**
+ * Parse + `Value.Check` an inbound frame. `FrameSchemaError` captures
+ * the failing branch so Tier A can assert "drop or typed error, never
+ * crash."
+ */
+export declare function decodeFrame(raw: string, direction: "outbound" | "inbound"): Effect.Effect<AnyFrame, FrameSchemaError>;
+/**
+ * Produce a malformed wire payload from a valid frame. The mutation is
+ * deterministic given the `kind` + `seed`; replaying with the same seed
+ * reproduces the exact bytes. Used by Tier A (A4) and Tier D (D3).
+ */
+export declare function malformFrame(base: AnyFrame, kind: MalformedFrameKind, seed: number): string;
+//# sourceMappingURL=codec.d.ts.map

package/dist/testing/codec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codec.d.ts","sourceRoot":"","sources":["../../src/testing/codec.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEhC,OAAO,EAIL,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,KAAK,UAAU,EAChB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE/C;;;;GAIG;AACH,MAAM,MAAM,QAAQ,GAChB,CAAC;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;CAAE,GAAG,YAAY,CAAC,GAC7C,CAAC;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;CAAE,GAAG,aAAa,CAAC,GAC/C,CAAC;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAAG,UAAU,CAAC,CAAC;AAE9C;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAC1B,UAAU,GACV,WAAW,GACX,WAAW,GACX,cAAc,GACd,wBAAwB,GACxB,gBAAgB,CAAC;AAErB,iDAAiD;AACjD,wBAAgB,WAAW,CAAC,KAAK,EAAE,QAAQ,GAAG,MAAM,CAEnD;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CACzB,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,UAAU,GAAG,SAAS,GAChC,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE,gBAAgB,CAAC,CAiF3C;AAaD;;;;GAIG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,QAAQ,EACd,IAAI,EAAE,kBAAkB,EACxB,IAAI,EAAE,MAAM,GACX,MAAM,CAoDR"}