@statewalker/webrun-streams-conformance 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022-2026 statewalker
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,40 @@
+# @statewalker/webrun-streams-conformance
+
+Conformance suite for `Duplex` / `Connect` / `Serve` adapters in the `webrun-streams-*` family. Every adapter ships a one-line test file that calls `describeDuplexAdapter(name, makePair)` with its own pair factory.
+
+## Levels asserted
+
+- **L0** Envelope round-trip via an echo handler for body sizes empty / 1 KiB / 1 MiB / 10 MiB.
+- **L1** N concurrent calls (default 10) with correct per-call body identity.
+- **L2** Half-close — caller exhausts input; handler keeps yielding response chunks.
+- **L3** Mid-stream cancellation — caller `.return()`s output; handler's `finally` runs.
+- **L4** Error propagation — handler `throw`s; caller sees `message` + `stack` + custom fields preserved.
+- **L5** Transport teardown — calling the `serve` teardown twice resolves rather than throwing, and closing the pair after a completed call resolves cleanly. (It does *not* assert what an in-flight call does when the transport closes underneath it; that is deliberately left to each adapter.)
+
+## Reference loopback
+
+`makeLoopbackPair()` returns a `ConnectServePair` whose `call` invokes the registered `handler` directly with no transport. The suite must pass green against the loopback — this is the self-test that the assertions are correctly formulated.
+
+## Usage
+
+```ts
+import { describeDuplexAdapter } from "@statewalker/webrun-streams-conformance";
+import { makeMyAdapterPair } from "./make-pair.js";
+
+describeDuplexAdapter("my-adapter", makeMyAdapterPair);
+```
+
+`makeMyAdapterPair` is a `MakePair` — an async factory returning a
+`ConnectServePair` (`connect()`, `serve(handler)`, `close()`). It is called
+once per test case, so each gets a fresh transport.
+
+A third argument tunes the suite:
+
+| Option | Default | Effect |
+| --- | --- | --- |
+| `concurrency` | `10` | How many concurrent calls L1 runs. |
+| `skipHugeBody` | `false` | Drop L0's 10 MiB case, for transports that rate-limit. |
+
+## License
+
+MIT

package/dist/describe-duplex-adapter.d.ts

@@ -0,0 +1,14 @@
+import type { MakePair } from "./loopback.js";
+export interface DescribeDuplexAdapterOptions {
+    /** Number of concurrent calls for L1. Default 10. */
+    concurrency?: number;
+    /** Bypass the 10 MiB L0 case (some transports rate-limit). Default false. */
+    skipHugeBody?: boolean;
+}
+/**
+ * Runs every conformance level (L0–L5) against the supplied `ConnectServePair`
+ * factory. Each adapter package in the `webrun-streams-*` family invokes this
+ * from its own one-line Vitest file.
+ */
+export declare function describeDuplexAdapter(name: string, makePair: MakePair, opts?: DescribeDuplexAdapterOptions): void;
+//# sourceMappingURL=describe-duplex-adapter.d.ts.map

package/dist/describe-duplex-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"describe-duplex-adapter.d.ts","sourceRoot":"","sources":["../src/describe-duplex-adapter.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C,MAAM,WAAW,4BAA4B;IAC3C,qDAAqD;IACrD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6EAA6E;IAC7E,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,QAAQ,EAClB,IAAI,GAAE,4BAAiC,GACtC,IAAI,CAmMN"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { type DescribeDuplexAdapterOptions, describeDuplexAdapter, } from "./describe-duplex-adapter.js";
+export { type ConnectServePair, type MakePair, makeLoopbackPair } from "./loopback.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,4BAA4B,EACjC,qBAAqB,GACtB,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAE,KAAK,gBAAgB,EAAE,KAAK,QAAQ,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1,255 @@
+import { collectBytes } from "@statewalker/webrun-streams";
+import { describe, expect, it } from "vitest";
+//#region src/describe-duplex-adapter.ts
+/**
+* Runs every conformance level (L0–L5) against the supplied `ConnectServePair`
+* factory. Each adapter package in the `webrun-streams-*` family invokes this
+* from its own one-line Vitest file.
+*/
+function describeDuplexAdapter(name, makePair, opts = {}) {
+	const concurrency = opts.concurrency ?? 10;
+	describe(`${name} — Duplex conformance`, () => {
+		describe("L0: envelope round-trip", () => {
+			const cases = [
+				{
+					label: "empty",
+					size: 0
+				},
+				{
+					label: "1 KiB",
+					size: 1024
+				},
+				{
+					label: "1 MiB",
+					size: 1048576
+				}
+			];
+			if (!opts.skipHugeBody) cases.push({
+				label: "10 MiB",
+				size: 10485760
+			});
+			for (const { label, size } of cases) it(`round-trips ${label} body via echo handler`, async () => {
+				const pair = await makePair();
+				try {
+					await pair.serve(echoHandler);
+					const { call, close } = await pair.connect();
+					try {
+						const input = randomBytes(size);
+						const out = call([input]);
+						const received = await collectBytes(out);
+						expect(received.byteLength).toBe(size);
+						expect(bytesEqual(received, input)).toBe(true);
+					} finally {
+						await close();
+					}
+				} finally {
+					await pair.close();
+				}
+			});
+		});
+		describe("L1: concurrent calls", () => {
+			it(`completes ${concurrency} concurrent calls with correct per-call bodies`, async () => {
+				const pair = await makePair();
+				try {
+					await pair.serve(echoHandler);
+					const { call, close } = await pair.connect();
+					try {
+						const calls = Array.from({ length: concurrency }, async (_, i) => {
+							const body = new TextEncoder().encode(`body-${i}-${"x".repeat(64)}`);
+							const out = call([body]);
+							return {
+								i,
+								received: await collectBytes(out),
+								body
+							};
+						});
+						const results = await Promise.all(calls);
+						for (const { i, received, body } of results) {
+							expect(received.byteLength, `call ${i}`).toBe(body.byteLength);
+							expect(bytesEqual(received, body), `call ${i}`).toBe(true);
+						}
+					} finally {
+						await close();
+					}
+				} finally {
+					await pair.close();
+				}
+			});
+		});
+		describe("L2: half-close", () => {
+			it("response continues yielding after input exhausts", async () => {
+				const pair = await makePair();
+				try {
+					await pair.serve(async function* lateResponder(input) {
+						for await (const _ of input);
+						yield new TextEncoder().encode("a");
+						await delay(30);
+						yield new TextEncoder().encode("b");
+						await delay(30);
+						yield new TextEncoder().encode("c");
+					});
+					const { call, close } = await pair.connect();
+					try {
+						const out = call((async function* () {
+							yield new TextEncoder().encode("ping");
+						})());
+						const text = new TextDecoder().decode(await collectBytes(out));
+						expect(text).toBe("abc");
+					} finally {
+						await close();
+					}
+				} finally {
+					await pair.close();
+				}
+			});
+		});
+		describe("L3: mid-stream cancellation", () => {
+			it("propagates caller .return() to handler", async () => {
+				const pair = await makePair();
+				try {
+					let handlerCleanupRan = false;
+					await pair.serve(async function* unboundedResponder() {
+						try {
+							while (true) {
+								yield new TextEncoder().encode("tick");
+								await delay(10);
+							}
+						} finally {
+							handlerCleanupRan = true;
+						}
+					});
+					const { call, close } = await pair.connect();
+					try {
+						const out = call([/* @__PURE__ */ new Uint8Array(0)]);
+						let count = 0;
+						for await (const _ of out) {
+							count++;
+							if (count >= 3) break;
+						}
+						await delay(50);
+						expect(count).toBe(3);
+						expect(handlerCleanupRan).toBe(true);
+					} finally {
+						await close();
+					}
+				} finally {
+					await pair.close();
+				}
+			});
+		});
+		describe("L4: error propagation", () => {
+			it("preserves message, custom fields, and stack across the wire", async () => {
+				const pair = await makePair();
+				try {
+					await pair.serve(async function* failingHandler() {
+						const err = /* @__PURE__ */ new Error("intentional failure");
+						Object.assign(err, {
+							status: 418,
+							code: "TEAPOT"
+						});
+						throw err;
+					});
+					const { call, close } = await pair.connect();
+					try {
+						const out = call([/* @__PURE__ */ new Uint8Array(0)]);
+						await expect(async () => {
+							for await (const _ of out);
+						}).rejects.toMatchObject({
+							message: "intentional failure",
+							status: 418,
+							code: "TEAPOT"
+						});
+						try {
+							for await (const _ of call([/* @__PURE__ */ new Uint8Array(0)]));
+						} catch (caught) {
+							expect(typeof caught.stack).toBe("string");
+							expect((caught.stack ?? "").length).toBeGreaterThan(0);
+						}
+					} finally {
+						await close();
+					}
+				} finally {
+					await pair.close();
+				}
+			});
+		});
+		describe("L5: transport teardown", () => {
+			it("idempotent serve teardown", async () => {
+				const pair = await makePair();
+				try {
+					const teardown = await pair.serve(echoHandler);
+					await teardown();
+					await expect(teardown()).resolves.toBeUndefined();
+				} finally {
+					await pair.close();
+				}
+			});
+			it("pair close after operation completes without throwing", async () => {
+				const pair = await makePair();
+				await pair.serve(echoHandler);
+				const { call, close } = await pair.connect();
+				const out = call([new TextEncoder().encode("x")]);
+				await collectBytes(out);
+				await close();
+				await expect(pair.close()).resolves.toBeUndefined();
+			});
+		});
+	});
+}
+const echoHandler = async function* echo(input) {
+	for await (const chunk of input) yield chunk;
+};
+function randomBytes(size) {
+	const out = new Uint8Array(size);
+	for (let i = 0; i < size; i++) out[i] = i * 2654435761 & 255;
+	return out;
+}
+function bytesEqual(a, b) {
+	if (a.byteLength !== b.byteLength) return false;
+	for (let i = 0; i < a.byteLength; i++) if (a[i] !== b[i]) return false;
+	return true;
+}
+function delay(ms) {
+	return new Promise((r) => setTimeout(r, ms));
+}
+//#endregion
+//#region src/loopback.ts
+/**
+* Loopback pair: `call` invokes the registered `handler` directly, no
+* transport. The conformance suite must pass against this — it self-validates
+* that the assertions are correctly formulated independent of any wire
+* protocol or `emulateMux` behaviour.
+*/
+const makeLoopbackPair = async () => {
+	let handler = null;
+	let closed = false;
+	const call = (input) => {
+		if (closed) return (async function* () {
+			throw new Error("loopback: pair closed");
+		})();
+		if (!handler) return (async function* () {
+			throw new Error("loopback: no handler registered");
+		})();
+		return handler(input);
+	};
+	return {
+		async connect() {
+			return {
+				call,
+				async close() {}
+			};
+		},
+		async serve(h) {
+			handler = h;
+			return async () => {
+				if (handler === h) handler = null;
+			};
+		},
+		async close() {
+			closed = true;
+			handler = null;
+		}
+	};
+};
+//#endregion
+export { describeDuplexAdapter, makeLoopbackPair };

package/dist/loopback.d.ts

@@ -0,0 +1,22 @@
+import type { Duplex } from "@statewalker/webrun-streams";
+/**
+ * The shape every adapter test factory returns. The suite drives `connect`
+ * for each test case and uses `serve` to register the handler.
+ */
+export interface ConnectServePair {
+    connect(): Promise<{
+        call: Duplex;
+        close: () => Promise<void>;
+    }>;
+    serve(handler: Duplex): Promise<() => Promise<void>>;
+    close(): Promise<void>;
+}
+export type MakePair = () => Promise<ConnectServePair>;
+/**
+ * Loopback pair: `call` invokes the registered `handler` directly, no
+ * transport. The conformance suite must pass against this — it self-validates
+ * that the assertions are correctly formulated independent of any wire
+ * protocol or `emulateMux` behaviour.
+ */
+export declare const makeLoopbackPair: MakePair;
+//# sourceMappingURL=loopback.d.ts.map

package/dist/loopback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loopback.d.ts","sourceRoot":"","sources":["../src/loopback.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,6BAA6B,CAAC;AAE1D;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,OAAO,IAAI,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;KAAE,CAAC,CAAC;IACjE,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;IACrD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,MAAM,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,gBAAgB,CAAC,CAAC;AAEvD;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,EAAE,QAwC9B,CAAC"}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@statewalker/webrun-streams-conformance",
+  "version": "0.1.1",
+  "private": false,
+  "type": "module",
+  "description": "Conformance test suite for Duplex/Connect/Serve adapters in the webrun-streams-* family",
+  "homepage": "https://github.com/statewalker/webrun-wire",
+  "author": {
+    "name": "Mikhail Kotelnikov",
+    "email": "mikhail.kotelnikov@gmail.com"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git@github.com:statewalker/webrun-wire.git"
+  },
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "vitest": "^4.1.10",
+    "@statewalker/webrun-streams": "0.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "^26.2.0",
+    "rimraf": "^6.1.3",
+    "rolldown": "^1.2.4",
+    "typescript": "^7.0.2"
+  },
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "rimraf dist && rolldown -c && tsc --emitDeclarationOnly --declaration",
+    "test": "vitest run",
+    "lint": "biome check src tests"
+  }
+}

package/src/describe-duplex-adapter.ts

@@ -0,0 +1,241 @@
+import { collectBytes, type Duplex } from "@statewalker/webrun-streams";
+import { describe, expect, it } from "vitest";
+import type { MakePair } from "./loopback.js";
+
+export interface DescribeDuplexAdapterOptions {
+  /** Number of concurrent calls for L1. Default 10. */
+  concurrency?: number;
+  /** Bypass the 10 MiB L0 case (some transports rate-limit). Default false. */
+  skipHugeBody?: boolean;
+}
+
+/**
+ * Runs every conformance level (L0–L5) against the supplied `ConnectServePair`
+ * factory. Each adapter package in the `webrun-streams-*` family invokes this
+ * from its own one-line Vitest file.
+ */
+export function describeDuplexAdapter(
+  name: string,
+  makePair: MakePair,
+  opts: DescribeDuplexAdapterOptions = {},
+): void {
+  const concurrency = opts.concurrency ?? 10;
+
+  describe(`${name} — Duplex conformance`, () => {
+    describe("L0: envelope round-trip", () => {
+      const cases: Array<{ label: string; size: number }> = [
+        { label: "empty", size: 0 },
+        { label: "1 KiB", size: 1024 },
+        { label: "1 MiB", size: 1024 * 1024 },
+      ];
+      if (!opts.skipHugeBody) cases.push({ label: "10 MiB", size: 10 * 1024 * 1024 });
+
+      for (const { label, size } of cases) {
+        it(`round-trips ${label} body via echo handler`, async () => {
+          const pair = await makePair();
+          try {
+            await pair.serve(echoHandler);
+            const { call, close } = await pair.connect();
+            try {
+              const input = randomBytes(size);
+              const out = call([input]);
+              const received = await collectBytes(out);
+              expect(received.byteLength).toBe(size);
+              expect(bytesEqual(received, input)).toBe(true);
+            } finally {
+              await close();
+            }
+          } finally {
+            await pair.close();
+          }
+        });
+      }
+    });
+
+    describe("L1: concurrent calls", () => {
+      it(`completes ${concurrency} concurrent calls with correct per-call bodies`, async () => {
+        const pair = await makePair();
+        try {
+          await pair.serve(echoHandler);
+          const { call, close } = await pair.connect();
+          try {
+            const calls = Array.from({ length: concurrency }, async (_, i) => {
+              const body = new TextEncoder().encode(`body-${i}-${"x".repeat(64)}`);
+              const out = call([body]);
+              const received = await collectBytes(out);
+              return { i, received, body };
+            });
+            const results = await Promise.all(calls);
+            for (const { i, received, body } of results) {
+              expect(received.byteLength, `call ${i}`).toBe(body.byteLength);
+              expect(bytesEqual(received, body), `call ${i}`).toBe(true);
+            }
+          } finally {
+            await close();
+          }
+        } finally {
+          await pair.close();
+        }
+      });
+    });
+
+    describe("L2: half-close", () => {
+      it("response continues yielding after input exhausts", async () => {
+        const pair = await makePair();
+        try {
+          await pair.serve(async function* lateResponder(input) {
+            // Drain input.
+            for await (const _ of input) {
+              /* discard */
+            }
+            // Then yield over time.
+            yield new TextEncoder().encode("a");
+            await delay(30);
+            yield new TextEncoder().encode("b");
+            await delay(30);
+            yield new TextEncoder().encode("c");
+          });
+          const { call, close } = await pair.connect();
+          try {
+            const out = call(
+              (async function* () {
+                yield new TextEncoder().encode("ping");
+              })(),
+            );
+            const text = new TextDecoder().decode(await collectBytes(out));
+            expect(text).toBe("abc");
+          } finally {
+            await close();
+          }
+        } finally {
+          await pair.close();
+        }
+      });
+    });
+
+    describe("L3: mid-stream cancellation", () => {
+      it("propagates caller .return() to handler", async () => {
+        const pair = await makePair();
+        try {
+          let handlerCleanupRan = false;
+          await pair.serve(async function* unboundedResponder() {
+            try {
+              while (true) {
+                yield new TextEncoder().encode("tick");
+                await delay(10);
+              }
+            } finally {
+              handlerCleanupRan = true;
+            }
+          });
+          const { call, close } = await pair.connect();
+          try {
+            const out = call([new Uint8Array(0)]);
+            let count = 0;
+            for await (const _ of out) {
+              count++;
+              if (count >= 3) break;
+            }
+            // Give the handler a moment to observe the cancellation.
+            await delay(50);
+            expect(count).toBe(3);
+            expect(handlerCleanupRan).toBe(true);
+          } finally {
+            await close();
+          }
+        } finally {
+          await pair.close();
+        }
+      });
+    });
+
+    describe("L4: error propagation", () => {
+      it("preserves message, custom fields, and stack across the wire", async () => {
+        const pair = await makePair();
+        try {
+          await pair.serve(async function* failingHandler() {
+            const err = new Error("intentional failure");
+            Object.assign(err, { status: 418, code: "TEAPOT" });
+            if ((0 as number) === 0) throw err;
+            yield new Uint8Array(0);
+          });
+          const { call, close } = await pair.connect();
+          try {
+            const out = call([new Uint8Array(0)]);
+            await expect(async () => {
+              for await (const _ of out) {
+                /* drain */
+              }
+            }).rejects.toMatchObject({
+              message: "intentional failure",
+              status: 418,
+              code: "TEAPOT",
+            });
+            // Stack must be a non-empty string (modulo loopback returning the
+            // same Error instance, native bridges reconstructing it).
+            try {
+              for await (const _ of call([new Uint8Array(0)])) {
+                /* drain */
+              }
+            } catch (caught) {
+              expect(typeof (caught as Error).stack).toBe("string");
+              expect(((caught as Error).stack ?? "").length).toBeGreaterThan(0);
+            }
+          } finally {
+            await close();
+          }
+        } finally {
+          await pair.close();
+        }
+      });
+    });
+
+    describe("L5: transport teardown", () => {
+      it("idempotent serve teardown", async () => {
+        const pair = await makePair();
+        try {
+          const teardown = await pair.serve(echoHandler);
+          await teardown();
+          await expect(teardown()).resolves.toBeUndefined();
+        } finally {
+          await pair.close();
+        }
+      });
+
+      it("pair close after operation completes without throwing", async () => {
+        const pair = await makePair();
+        await pair.serve(echoHandler);
+        const { call, close } = await pair.connect();
+        const out = call([new TextEncoder().encode("x")]);
+        await collectBytes(out);
+        await close();
+        await expect(pair.close()).resolves.toBeUndefined();
+      });
+    });
+  });
+}
+
+const echoHandler: Duplex = async function* echo(input) {
+  for await (const chunk of input) yield chunk;
+};
+
+function randomBytes(size: number): Uint8Array {
+  const out = new Uint8Array(size);
+  // Cheap deterministic-but-non-trivial fill — full crypto.getRandomValues is
+  // capped at 64 KiB per call in browsers, and conformance just needs the
+  // bytes to round-trip, not be cryptographically random.
+  for (let i = 0; i < size; i++) out[i] = (i * 2654435761) & 0xff;
+  return out;
+}
+
+function bytesEqual(a: Uint8Array, b: Uint8Array): boolean {
+  if (a.byteLength !== b.byteLength) return false;
+  for (let i = 0; i < a.byteLength; i++) {
+    if (a[i] !== b[i]) return false;
+  }
+  return true;
+}
+
+function delay(ms: number): Promise<void> {
+  return new Promise((r) => setTimeout(r, ms));
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export {
+  type DescribeDuplexAdapterOptions,
+  describeDuplexAdapter,
+} from "./describe-duplex-adapter.js";
+export { type ConnectServePair, type MakePair, makeLoopbackPair } from "./loopback.js";

package/src/loopback.ts

@@ -0,0 +1,61 @@
+import type { Duplex } from "@statewalker/webrun-streams";
+
+/**
+ * The shape every adapter test factory returns. The suite drives `connect`
+ * for each test case and uses `serve` to register the handler.
+ */
+export interface ConnectServePair {
+  connect(): Promise<{ call: Duplex; close: () => Promise<void> }>;
+  serve(handler: Duplex): Promise<() => Promise<void>>;
+  close(): Promise<void>;
+}
+
+export type MakePair = () => Promise<ConnectServePair>;
+
+/**
+ * Loopback pair: `call` invokes the registered `handler` directly, no
+ * transport. The conformance suite must pass against this — it self-validates
+ * that the assertions are correctly formulated independent of any wire
+ * protocol or `emulateMux` behaviour.
+ */
+export const makeLoopbackPair: MakePair = async () => {
+  let handler: Duplex | null = null;
+  let closed = false;
+
+  const call: Duplex = (input) => {
+    if (closed) {
+      return (async function* () {
+        if ((0 as number) === 0) throw new Error("loopback: pair closed");
+        yield new Uint8Array(0);
+      })();
+    }
+    if (!handler) {
+      return (async function* () {
+        if ((0 as number) === 0) throw new Error("loopback: no handler registered");
+        yield new Uint8Array(0);
+      })();
+    }
+    return handler(input);
+  };
+
+  return {
+    async connect() {
+      return {
+        call,
+        async close() {
+          /* no-op for loopback; pair.close handles teardown */
+        },
+      };
+    },
+    async serve(h) {
+      handler = h;
+      return async () => {
+        if (handler === h) handler = null;
+      };
+    },
+    async close() {
+      closed = true;
+      handler = null;
+    },
+  };
+};