@specific.dev/spectest 0.88.3 → 0.89.1

package/src/harness/ws-bridge.test.ts

@@ -0,0 +1,224 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+
+import {
+  WS_BRIDGE_HANDLERS,
+  openUpstreamWebSocket,
+  parseSubprotocols,
+  upstreamHandshakeHeaders,
+  type WsBridgeData,
+} from "./ws-bridge";
+
+describe("parseSubprotocols", () => {
+  test("splits, trims, drops empty tokens, keeps order", () => {
+    expect(parseSubprotocols("console, ticket-abc")).toEqual(["console", "ticket-abc"]);
+    expect(parseSubprotocols(" a ,, b ,")).toEqual(["a", "b"]);
+    expect(parseSubprotocols(null)).toEqual([]);
+    expect(parseSubprotocols("")).toEqual([]);
+  });
+});
+
+describe("upstreamHandshakeHeaders", () => {
+  test("forwards cookies and origin, drops the client's handshake fields, stamps provenance", () => {
+    const req = new Headers({
+      host: "api.prod.specific.dev",
+      connection: "Upgrade",
+      upgrade: "websocket",
+      "sec-websocket-key": "abc==",
+      "sec-websocket-version": "13",
+      "sec-websocket-protocol": "console, ticket",
+      "sec-websocket-extensions": "permessage-deflate",
+      cookie: "sid=1",
+      origin: "https://app.test",
+      authorization: "Bearer t",
+    });
+    const out = upstreamHandshakeHeaders(req, {
+      service: "api",
+      port: 4000,
+      proto: "https",
+      clientIp: "10.0.0.7",
+    });
+    expect(out["cookie"]).toBe("sid=1");
+    expect(out["origin"]).toBe("https://app.test");
+    expect(out["authorization"]).toBe("Bearer t");
+    expect(out["host"]).toBe("api:4000");
+    expect(out["x-forwarded-host"]).toBe("api.prod.specific.dev");
+    expect(out["x-forwarded-proto"]).toBe("https");
+    expect(out["x-forwarded-for"]).toBe("10.0.0.7");
+    for (const k of Object.keys(out)) {
+      expect(k.startsWith("sec-websocket-")).toBe(false);
+      expect(["connection", "upgrade"]).not.toContain(k);
+    }
+  });
+
+  test("appends the client to an existing x-forwarded-for", () => {
+    const out = upstreamHandshakeHeaders(new Headers({ "x-forwarded-for": "1.2.3.4" }), {
+      service: "api",
+      port: 1,
+      proto: "http",
+      clientIp: "10.0.0.7",
+    });
+    expect(out["x-forwarded-for"]).toBe("1.2.3.4, 10.0.0.7");
+  });
+});
+
+/**
+ * A loopback copy of the daemon's arrangement: an upstream that admits a
+ * connection only when the SECOND subprotocol is the ticket (the shape of
+ * Specific's console API), a bridge listener in front of it that does what
+ * `proxyToService` does, and a client through the bridge.
+ */
+describe("the bridge on loopback", () => {
+  let upstream: ReturnType<typeof Bun.serve>;
+  let bridge: ReturnType<typeof Bun.serve>;
+  /** What the upstream saw on its last handshake. */
+  let seen: { protocols: string[]; cookie: string | null; xfh: string | null } | null = null;
+
+  beforeAll(() => {
+    upstream = Bun.serve({
+      port: 0,
+      fetch(req, server) {
+        const protocols = parseSubprotocols(req.headers.get("sec-websocket-protocol"));
+        seen = {
+          protocols,
+          cookie: req.headers.get("cookie"),
+          xfh: req.headers.get("x-forwarded-host"),
+        };
+        if (protocols[1] !== "ticket-ok") return new Response("Unauthorized", { status: 401 });
+        const ok = server.upgrade(req, {
+          headers: { "sec-websocket-protocol": protocols[0] },
+          data: { admitted: protocols[1] },
+        });
+        return ok ? undefined : new Response("refused", { status: 426 });
+      },
+      websocket: {
+        open(ws) {
+          ws.send("ready");
+        },
+        message(ws, m) {
+          if (typeof m === "string") {
+            if (m === "close-me") ws.close(4402, "app said so");
+            else ws.send(`echo:${m}`);
+          } else {
+            ws.send(new Uint8Array(m).reverse());
+          }
+        },
+      },
+    });
+
+    bridge = Bun.serve({
+      port: 0,
+      async fetch(req, server) {
+        const protocols = parseSubprotocols(req.headers.get("sec-websocket-protocol"));
+        const headers = upstreamHandshakeHeaders(req.headers, {
+          service: "api",
+          port: upstream.port!,
+          proto: "https",
+        });
+        const url = new URL(req.url);
+        const opened = await openUpstreamWebSocket(
+          `ws://127.0.0.1:${upstream.port}${url.pathname}${url.search}`,
+          { protocols, headers },
+        );
+        if (!opened.ok) return new Response(opened.reason, { status: 502 });
+        const data: WsBridgeData = { upstreamUrl: "", upstream: opened.socket };
+        const ok = server.upgrade(req, {
+          headers: opened.socket.protocol
+            ? { "sec-websocket-protocol": opened.socket.protocol }
+            : undefined,
+          data,
+        });
+        if (!ok) {
+          opened.socket.close();
+          return new Response("refused", { status: 426 });
+        }
+        return undefined;
+      },
+      websocket: WS_BRIDGE_HANDLERS,
+    });
+  });
+
+  afterAll(() => {
+    upstream.stop(true);
+    bridge.stop(true);
+  });
+
+  function connect(protocols: string[]): Promise<{
+    ws: WebSocket;
+    events: Array<{ kind: "open" | "message" | "close" | "error"; value?: unknown }>;
+    done: Promise<void>;
+  }> {
+    const Ctor = WebSocket as unknown as new (
+      url: string,
+      opts: { protocols?: string[]; headers?: Record<string, string> },
+    ) => WebSocket;
+    const ws = new Ctor(`ws://127.0.0.1:${bridge.port}/console?x=1`, {
+      protocols,
+      headers: { cookie: "sid=abc", host: "api.prod.specific.dev" },
+    });
+    ws.binaryType = "arraybuffer";
+    const events: Array<{ kind: "open" | "message" | "close" | "error"; value?: unknown }> = [];
+    const done = new Promise<void>((resolve) => {
+      ws.addEventListener("close", (ev) => {
+        events.push({ kind: "close", value: { code: ev.code, reason: ev.reason } });
+        resolve();
+      });
+    });
+    ws.addEventListener("error", (ev) => events.push({ kind: "error", value: (ev as { message?: string }).message }));
+    ws.addEventListener("message", (ev) => events.push({ kind: "message", value: ev.data }));
+    return new Promise((resolve, reject) => {
+      ws.addEventListener("open", () => {
+        events.push({ kind: "open" });
+        resolve({ ws, events, done });
+      });
+      done.then(() => reject(new Error(`closed before open: ${JSON.stringify(events)}`)));
+    });
+  }
+
+  test("the full protocol list and the headers reach the upstream; the selected protocol comes back", async () => {
+    const { ws, events, done } = await connect(["console", "ticket-ok"]);
+    expect(ws.protocol).toBe("console");
+    expect(seen).toEqual({
+      protocols: ["console", "ticket-ok"],
+      cookie: "sid=abc",
+      xfh: "api.prod.specific.dev",
+    });
+    await Bun.sleep(20);
+    ws.send("hi");
+    ws.send(new Uint8Array([1, 2, 3]));
+    await Bun.sleep(50);
+    ws.close(1000, "bye");
+    await done;
+    const messages = events.filter((e) => e.kind === "message").map((e) => e.value);
+    expect(messages[0]).toBe("ready");
+    expect(messages[1]).toBe("echo:hi");
+    expect(Array.from(new Uint8Array(messages[2] as ArrayBuffer))).toEqual([3, 2, 1]);
+  });
+
+  test("an upstream close code after the handshake is relayed to the client", async () => {
+    const { ws, events, done } = await connect(["console", "ticket-ok"]);
+    await Bun.sleep(20);
+    ws.send("close-me");
+    await done;
+    const close = events.find((e) => e.kind === "close")?.value as { code: number; reason: string };
+    expect(close.code).toBe(4402);
+    expect(close.reason).toBe("app said so");
+  });
+
+  test("an upstream that refuses the handshake never gives the client a 101", async () => {
+    // A plain fetch with the upgrade headers shows the status the bridge
+    // answers with; a WebSocket client only reports a failed handshake.
+    const res = await fetch(`http://127.0.0.1:${bridge.port}/console`, {
+      headers: {
+        connection: "Upgrade",
+        upgrade: "websocket",
+        "sec-websocket-version": "13",
+        "sec-websocket-key": "dGhlIHNhbXBsZSBub25jZQ==",
+        "sec-websocket-protocol": "console, ticket-bad",
+      },
+    });
+    expect(res.status).toBe(502);
+    expect(await res.text()).toContain("upstream handshake failed");
+    expect(seen?.protocols).toEqual(["console", "ticket-bad"]);
+    await expect(connect(["console", "ticket-bad"])).rejects.toThrow(/closed before open/);
+  });
+});

package/src/harness/ws-bridge.ts

@@ -0,0 +1,210 @@
+/**
+ * The ingress WebSocket bridge: one client WebSocket on an ingress
+ * listener, one upstream WebSocket to the service, frames copied in both
+ * directions.
+ *
+ * The handshake is the part that matters. A client that sends
+ * `Sec-WebSocket-Protocol: console, <ticket>` expects the upstream to see
+ * the full list, and expects to get back the one the upstream selected.
+ * The first version of this bridge opened the upstream with no protocols
+ * and no headers, so a ticket or a cookie that rode on the handshake never
+ * reached the service, and the service refused the connection after the
+ * client already saw a 101. So the bridge now opens the upstream FIRST,
+ * with the client's protocol list and forwardable headers, waits for the
+ * upstream handshake, and only then upgrades the client with the protocol
+ * the upstream selected. An upstream that refuses the handshake becomes a
+ * 502 to the client, the same as the HTTP proxy path.
+ *
+ * `daemon.ts` owns the listener and the route lookup; this module owns
+ * the handshake and the frame relay so the two can be tested on loopback
+ * without a VM.
+ */
+
+import { forwardableHeaders } from "./http-proxy.js";
+
+/** Headers that belong to the client's own WebSocket handshake. Bun's
+ *  WebSocket client mints its own key and version, and the protocol list
+ *  goes through the constructor option, so these never travel as plain
+ *  headers. */
+const HANDSHAKE_HEADERS: ReadonlySet<string> = new Set([
+  "sec-websocket-key",
+  "sec-websocket-version",
+  "sec-websocket-protocol",
+  "sec-websocket-extensions",
+  "sec-websocket-accept",
+]);
+
+/** Per-bridge context stored on `ws.data` of the client socket. */
+export interface WsBridgeData {
+  upstreamUrl: string;
+  /** Open by the time the client socket exists: the handshake awaited it. */
+  upstream: WebSocket;
+}
+
+/** `Sec-WebSocket-Protocol` is a comma-separated list; each token is
+ *  trimmed, empty tokens are dropped, order is kept (RFC 6455 §4.1 lets
+ *  the server pick from the list, so order is the client's preference). */
+export function parseSubprotocols(header: string | null | undefined): string[] {
+  if (!header) return [];
+  return header
+    .split(",")
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0);
+}
+
+/**
+ * The headers the upstream handshake carries: everything forwardable from
+ * the client's request (cookies, authorization, origin, user-agent …),
+ * minus the client's own handshake fields, plus the proxy provenance
+ * headers and a Host that names the service.
+ */
+export function upstreamHandshakeHeaders(
+  req: Headers,
+  opts: {
+    service: string;
+    port: number;
+    proto: string;
+    clientIp?: string;
+  },
+): Record<string, string> {
+  const out: Record<string, string> = {};
+  forwardableHeaders(req).forEach((value, key) => {
+    if (HANDSHAKE_HEADERS.has(key)) return;
+    out[key] = value;
+  });
+  const priorXff = req.get("x-forwarded-for");
+  const xff = opts.clientIp
+    ? priorXff
+      ? `${priorXff}, ${opts.clientIp}`
+      : opts.clientIp
+    : priorXff;
+  if (xff) out["x-forwarded-for"] = xff;
+  out["x-forwarded-proto"] = opts.proto;
+  const publicHost = req.get("host");
+  if (publicHost) out["x-forwarded-host"] = publicHost;
+  out["host"] = `${opts.service}:${opts.port}`;
+  return out;
+}
+
+/** Bun's WebSocket constructor takes an options object with `headers`;
+ *  the bundled types only declare the WHATWG `protocols` form. */
+type BunWebSocketCtor = new (
+  url: string,
+  opts: { protocols?: string[]; headers?: Record<string, string> },
+) => WebSocket;
+
+export type UpstreamOpen =
+  | { ok: true; socket: WebSocket }
+  | { ok: false; reason: string };
+
+/**
+ * Open the upstream WebSocket and wait for its handshake. Resolves once
+ * the socket is open, or once it failed; the handshake listeners are
+ * removed either way so a later close does not fire them again.
+ */
+export function openUpstreamWebSocket(
+  url: string,
+  opts: { protocols: string[]; headers: Record<string, string>; timeoutMs?: number },
+): Promise<UpstreamOpen> {
+  const Ctor = WebSocket as unknown as BunWebSocketCtor;
+  let socket: WebSocket;
+  try {
+    socket = new Ctor(url, { protocols: opts.protocols, headers: opts.headers });
+  } catch (err) {
+    return Promise.resolve({ ok: false, reason: String(err) });
+  }
+  // ArrayBuffer so binary frames can be sent to the client verbatim.
+  socket.binaryType = "arraybuffer";
+  return new Promise<UpstreamOpen>((resolve) => {
+    let settled = false;
+    const timeoutMs = opts.timeoutMs ?? 30_000;
+    const timer = setTimeout(() => finish({ ok: false, reason: "upstream handshake timed out" }), timeoutMs);
+    const onOpen = (): void => finish({ ok: true, socket });
+    const onError = (ev: Event): void => {
+      const msg = (ev as { message?: string }).message;
+      finish({ ok: false, reason: msg ? `upstream handshake failed: ${msg}` : "upstream handshake failed" });
+    };
+    const onClose = (ev: CloseEvent): void =>
+      finish({ ok: false, reason: `upstream closed during handshake (${ev.code}${ev.reason ? ` ${ev.reason}` : ""})` });
+    const finish = (result: UpstreamOpen): void => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      socket.removeEventListener("open", onOpen);
+      socket.removeEventListener("error", onError);
+      socket.removeEventListener("close", onClose);
+      if (!result.ok) {
+        try {
+          socket.close();
+        } catch {
+          /* already closed */
+        }
+      }
+      resolve(result);
+    };
+    socket.addEventListener("open", onOpen);
+    socket.addEventListener("error", onError);
+    socket.addEventListener("close", onClose);
+  });
+}
+
+/** The minimum of Bun's ServerWebSocket that the relay uses. */
+interface ClientSocket {
+  data: WsBridgeData;
+  send(data: string | ArrayBuffer | Uint8Array): unknown;
+  close(code?: number, reason?: string): unknown;
+}
+
+/**
+ * The `websocket` handler set for `Bun.serve`. The upstream is already
+ * open when `open()` runs, so frames go straight through in both
+ * directions, and a close on either side closes the other with the same
+ * code and reason.
+ */
+export const WS_BRIDGE_HANDLERS = {
+  open(ws: ClientSocket): void {
+    const { upstream } = ws.data;
+    upstream.addEventListener("message", (ev: MessageEvent) => {
+      try {
+        ws.send(ev.data);
+      } catch {
+        /* client gone */
+      }
+    });
+    upstream.addEventListener("close", (ev: CloseEvent) => {
+      try {
+        ws.close(ev.code, ev.reason);
+      } catch {
+        /* already closed */
+      }
+    });
+    upstream.addEventListener("error", () => {
+      try {
+        ws.close(1011, "upstream error");
+      } catch {
+        /* already closed */
+      }
+    });
+    // The upstream can have closed between the handshake and this
+    // callback; the close listener above was not attached yet then.
+    if (upstream.readyState !== WebSocket.OPEN) {
+      try {
+        ws.close(1011, "upstream closed");
+      } catch {
+        /* already closed */
+      }
+    }
+  },
+  message(ws: ClientSocket, message: string | Buffer): void {
+    const { upstream } = ws.data;
+    const payload = typeof message === "string" ? message : new Uint8Array(message);
+    if (upstream.readyState === WebSocket.OPEN) upstream.send(payload);
+  },
+  close(ws: ClientSocket, code: number, reason: string): void {
+    try {
+      ws.data.upstream.close(code, reason);
+    } catch {
+      /* ignore */
+    }
+  },
+};

package/src/index.ts

@@ -17,9 +17,21 @@ export type {
   Wrapped,
   WrappedObject,
   WrappedArray,
+  WrappedHeaders,
+  WrappedBuffer,
+  WrappedBinaryView,
+  WrappedBytes,
+  WrappedBlob,
+  WrappedFile,
+  WrappedFormData,
+  WrappedStream,
+  WrappedReader,
+  WrappedBYOBReader,
+  WrappedReadResult,
   WrappedResponse,
   Provenanced,
   SpectestFetch,
+  SpectestRequestInit,
   Unwrap,
 } from "./inspect.js";
 import type { OpTag, Provenanced, SpectestFetch, Wrapped } from "./inspect.js";
@@ -475,11 +487,15 @@ export interface SpectestContext<
   /**
    * Instrumented `fetch`. In a test each call is recorded on the timeline
    * and resolves to a {@link WrappedResponse}: reads carry provenance so
-   * `expect(res.status)` / `expect(await res.json())` nest under the HTTP
+   * `expect(res.status)`, `expect(res.headers.get("content-type"))`, and
+   * `expect(await res.json())` nest under the HTTP
    * call. Because the status-line accessors are {@link Carrier}s, a raw
    * `res.status === 200` is a *type error* — use `res.status.unwrap()` /
    * `res.unwrap().status`, or assert via `expect`. Outside a test the
    * result is wrapped the same way, just with no timeline to link to.
+   * Body readers (`bytes`, `arrayBuffer`, `blob`, `formData`, `json`, `text`)
+   * and stream reader values also retain provenance. Use `captureBody: false`
+   * for open-ended streams; SSE responses skip recorder body capture automatically.
    *
    * (The plain global `fetch` is wrapped the same way at runtime but keeps
    * the standard `Response` type, so prefer `ctx.fetch` for honestly-typed

package/src/inspect-fetch.test.ts

@@ -0,0 +1,202 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { expect as assertValue } from "./index.js";
+import { readRaw, readTag, wrap, wrapResponse } from "./inspect.js";
+import { recordHttp, startRecording, stopRecording, type AssertionEvent } from "./recorder.js";
+
+let seq: number;
+beforeEach(() => {
+  startRecording();
+  seq = recordHttp({ method: "GET", url: "http://test/", status: 200, durationMs: 0 })!;
+});
+afterEach(() => { stopRecording(); });
+
+function paths() {
+  const assertions = stopRecording().filter((e): e is AssertionEvent => e.kind === "assertion");
+  for (const assertion of assertions) expect(assertion.sourceSeq).toBe(seq);
+  return assertions.map((e) => e.path);
+}
+
+describe("fetch body provenance", () => {
+  test("bytes retain indexes, sizes, derived values and native escape hatches", async () => {
+    const raw = new Uint8Array([0x89, 0x50, 0, 0xff]);
+    const res = wrapResponse(new Response(raw), seq);
+    assertValue(res.bodyUsed).toBe(false);
+    const bytes = await res.bytes();
+    assertValue(res.bodyUsed).toBe(true);
+    assertValue(bytes).toEqual(raw);
+    assertValue(bytes).toHaveLength(4);
+    assertValue(bytes.byteLength).toBe(4);
+    assertValue(bytes[0]).toBe(0x89);
+    assertValue(bytes.slice(1, 3)).toEqual(new Uint8Array([0x50, 0]));
+    assertValue(bytes.subarray(1).at(0)).toBe(0x50);
+    assertValue(bytes.includes(0xff)).toBe(true);
+    assertValue(bytes.filter((v) => v === 0)).toHaveLength(1);
+    assertValue(bytes.map((v) => v + 1)[2]).toBe(1);
+    assertValue(bytes.at(99)).toBe(undefined);
+    expect(bytes.length).toBe(4);
+    expect([...bytes]).toEqual([...raw]);
+    expect(bytes.unwrap()).toBeInstanceOf(Uint8Array);
+    expect(readRaw<unknown>(bytes)).toBe(bytes.unwrap());
+    expect(new TextDecoder().decode(bytes.unwrap())).toBe(new TextDecoder().decode(raw));
+    expect(paths()).toContainEqual(["body", "<subarray>", "<at>"]);
+  });
+
+  test("array buffers and derived DataViews retain provenance", async () => {
+    const res = wrapResponse(new Response(new Uint8Array([1, 2, 3])), seq);
+    const buffer = await res.arrayBuffer();
+    assertValue(buffer.byteLength).toBe(3);
+    assertValue(buffer.slice(1).byteLength).toBe(2);
+    const bytes = buffer.transform("bytes", (b) => new Uint8Array(b));
+    assertValue(bytes.buffer.byteLength).toBe(3);
+    const view = buffer.transform("view", (b) => new DataView(b));
+    assertValue(view.getUint16(0)).toBe(258);
+    expect(new Uint8Array(buffer.unwrap())).toEqual(new Uint8Array([1, 2, 3]));
+    expect(paths()).toEqual([
+      ["body", "byteLength"], ["body", "<slice>", "byteLength"],
+      ["body", "<bytes>", "buffer", "byteLength"], ["body", "<view>", "<getUint16>"],
+    ]);
+  });
+
+  test("blobs wrap metadata, slices, decoded bodies and streams", async () => {
+    const res = wrapResponse(new Response("hello", { headers: { "content-type": "text/plain" } }), seq);
+    const blob = await res.blob();
+    assertValue(blob.size).toBe(5);
+    assertValue(blob.type).toBe(blob.unwrap().type);
+    assertValue(await blob.slice(1, 4).text()).toBe("ell");
+    assertValue((await blob.bytes())[0]).toBe(104);
+    assertValue((await blob.arrayBuffer()).byteLength).toBe(5);
+    const reader = blob.stream().getReader();
+    try {
+      const chunk = await reader.read();
+      expect(chunk.done).toBe(false);
+      assertValue(chunk.value).toEqual(new TextEncoder().encode("hello"));
+    } finally { await reader.cancel(); reader.releaseLock(); }
+    expect(blob.unwrap()).toBeInstanceOf(Blob);
+    expect(paths()).toContainEqual(["body", "<stream>", "<read>", "0"]);
+  });
+
+  test("form data wraps missing and repeated fields and uploaded files", async () => {
+    const form = new FormData();
+    form.append("tag", "one");
+    form.append("tag", "two");
+    form.append("file", new File(["hello"], "hello.txt", { type: "text/plain", lastModified: 123 }));
+    const res = wrapResponse(new Response(form), seq);
+    const parsed = await res.formData();
+    assertValue(parsed.get("tag")).toBe("one");
+    assertValue(parsed.getAll("tag")).toEqual(["one", "two"]);
+    assertValue(parsed.getAll("tag")[1]).toBe("two");
+    assertValue(parsed.has("tag")).toBe(true);
+    assertValue(parsed.has("missing")).toBe(false);
+    assertValue(parsed.get("missing")).toBe(null);
+    const file = parsed.get("file");
+    if (!file || !("name" in file)) throw new Error("Expected a file");
+    assertValue(file.name).toBe("hello.txt");
+    assertValue(file.type).toBe(file.unwrap().type);
+    assertValue(file.size).toBe(5);
+    assertValue(file.lastModified).toBe(file.unwrap().lastModified);
+    assertValue(await file.text()).toBe("hello");
+    assertValue((await file.bytes())[0]).toBe(104);
+    expect([...parsed][0]).toEqual(["tag", "one"]);
+    expect(parsed.unwrap()).toBeInstanceOf(FormData);
+    expect(paths()).toContainEqual(["body", "file", "<text>"]);
+  });
+
+  test("top-level JSON null and absent bodies retain provenance", async () => {
+    const json = wrapResponse(new Response("null"), seq);
+    assertValue(await json.json<null>()).toBe(null);
+    const empty = wrapResponse(new Response(null, { status: 204 }), seq);
+    assertValue(empty.body).toBe(null);
+    expect(paths()).toEqual([["body"], ["body"]]);
+  });
+
+  test("Bun header helpers are wrapped and serialization stays native", () => {
+    const res = wrapResponse(new Response(null, { headers: [
+      ["x-test", "yes"], ["set-cookie", "a=1"], ["set-cookie", "b=2"],
+    ] }), seq);
+    assertValue(res.headers.getAll("Set-Cookie")).toEqual(["a=1", "b=2"]);
+    assertValue(res.headers.toJSON()["x-test"]).toBe("yes");
+    assertValue(res.headers.count).toBe(res.unwrap().headers.count);
+    expect(JSON.stringify(res.headers)).toBe(JSON.stringify(res.unwrap().headers));
+    expect(paths()).toEqual([["headers", "set-cookie"], ["headers", "x-test"], ["headers", "count"]]);
+  });
+
+  test("reader values are wrapped but done and locked remain control-flow booleans", async () => {
+    const res = wrapResponse(new Response("hello"), seq);
+    const body = res.body!;
+    expect(res.body).toBe(body);
+    const reader = body.getReader();
+    expect(body.locked).toBe(true);
+    expect(readRaw<unknown>(reader)).toBe(reader.unwrap());
+    let chunks = 0;
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      assertValue(value.byteLength).toBe(5);
+      chunks++;
+    }
+    expect(chunks).toBe(1);
+    reader.releaseLock();
+    expect(body.locked).toBe(false);
+    expect(paths()).toEqual([["body", "<read>", "0", "byteLength"]]);
+  });
+
+  test("BYOB readers wrap the returned view while preserving buffer semantics", async () => {
+    const stream = new ReadableStream<Uint8Array>({
+      type: "bytes",
+      pull(controller) {
+        controller.enqueue(new Uint8Array([1, 2, 3]));
+        controller.close();
+      },
+    });
+    const res = wrapResponse(new Response(stream), seq);
+    const reader = res.body!.getReader({ mode: "byob" });
+    const chunk = await reader.read(new Uint8Array(8));
+    expect(chunk.done).toBe(false);
+    assertValue(chunk.value).toEqual(new Uint8Array([1, 2, 3]));
+    expect((await reader.read(new Uint8Array(8))).done).toBe(true);
+    reader.releaseLock();
+    expect(paths()).toEqual([["body", "<read>", "0"]]);
+  });
+
+  test("tee and pipeThrough preserve provenance and pipeTo consumes native chunks", async () => {
+    const res = wrapResponse(new Response("hi"), seq);
+    const [left, right] = res.body!.tee();
+    const decoded = left.pipeThrough(new TextDecoderStream());
+    const reader = decoded.getReader();
+    assertValue((await reader.read()).value).toBe("hi");
+    reader.releaseLock();
+    const chunks: Uint8Array[] = [];
+    await right.pipeTo(new WritableStream({ write(chunk) { chunks.push(chunk); } }));
+    expect(chunks).toEqual([new TextEncoder().encode("hi")]);
+    expect(paths()).toEqual([["body", "<tee>", "0", "<pipeThrough>", "<read>", "0"]]);
+  });
+
+  test("native reader errors and body consumption errors propagate", async () => {
+    const res = wrapResponse(new Response("once"), seq);
+    await res.bytes();
+    await expect(res.text()).rejects.toThrow();
+    const failure = new Error("stream failed");
+    const broken = wrapResponse(new Response(new ReadableStream({ start(c) { c.error(failure); } })), seq);
+    const reader = broken.body!.getReader();
+    await expect(reader.read()).rejects.toBe(failure);
+    reader.releaseLock();
+  });
+
+  test("native body wrappers are available without a recorded event", async () => {
+    const bytes = await wrapResponse(new Response("hi"), undefined).bytes();
+    expect(bytes.byteLength.unwrap()).toBe(2);
+    expect(readTag(bytes[0])).toEqual({ sourceSeq: undefined, path: ["body", "0"] });
+  });
+
+  test("retagging native values unwraps fully and replaces their provenance", async () => {
+    const bytes = await wrapResponse(new Response("hi"), seq).bytes();
+    const retagged = wrap(bytes, 99, ["poll"]);
+    expect(retagged.unwrap()).toBe(bytes.unwrap());
+    expect(readTag(retagged.byteLength)).toEqual({ sourceSeq: 99, path: ["poll", "byteLength"] });
+    expect(retagged.byteLength.unwrap()).toBe(2);
+    const blob = await wrapResponse(new Response("hi"), seq).blob();
+    const retaggedBlob = wrap(blob, 99, ["poll"]);
+    expect(retaggedBlob.unwrap()).toBe(blob.unwrap());
+    expect((await retaggedBlob.text()).unwrap()).toBe("hi");
+  });
+});