@specific.dev/spectest 0.118.0 → 0.119.0

package/src/harness/network.test.ts

@@ -0,0 +1,265 @@
+import { test, expect } from "bun:test";
+import { mkdtempSync, readFileSync, writeFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { serveNetwork } from "./network";
+
+test("network harness authenticates, rejects replay, and rebinds a restored heap", async () => {
+  const dir = mkdtempSync(join(tmpdir(), "spectest-network-"));
+  const bindingPath = join(dir, "binding.json");
+  const resolverPath = join(dir, "resolv.conf");
+  writeFileSync(resolverPath, "nameserver 10.0.2.42\n");
+  const token = "p".repeat(64), childToken = "c".repeat(64);
+  const bind = (instanceId: string, token: string) => writeFileSync(bindingPath, JSON.stringify({ instanceId, token }), { mode: 0o600 });
+  let counter = 0;
+  const server = serveNetwork({ increment: async () => ++counter, fail: async () => { throw Error("fixture failure"); } }, { bindingPath, hostname: "127.0.0.1", port: 0, resolverPath });
+  const call = (id: string, key: string, requestId: string, method = "increment") => fetch(`${server.url}rpc`, {
+    method: "POST", headers: { Authorization: `Bearer ${key}`, "X-Spectest-Instance": id },
+    body: JSON.stringify({ requestId, method, params: {} }),
+  });
+  try {
+    expect((await call("parent", token, "1")).status).toBe(503);
+    bind("parent", token);
+    expect((await call("parent", "wrong", "1")).status).toBe(401);
+    expect((await call("child", token, "1")).status).toBe(409);
+    expect(counter).toBe(0);
+    expect(readFileSync(resolverPath, "utf8")).toBe("nameserver 10.0.2.42\n");
+    expect(await (await call("parent", token, "1")).json()).toEqual({ instanceId: "parent", requestId: "1", result: 1 });
+    expect(readFileSync(resolverPath, "utf8")).toContain("nameserver 127.0.0.53");
+    expect((await call("parent", token, "1")).status).toBe(409);
+    expect(counter).toBe(1);
+    bind("child", childToken);
+    writeFileSync(resolverPath, "nameserver 10.0.2.42\n");
+    expect((await call("parent", token, "2")).status).toBe(401);
+    expect(await (await call("child", childToken, "1")).json()).toEqual({ instanceId: "child", requestId: "1", result: 2 });
+    expect(readFileSync(resolverPath, "utf8")).toContain("nameserver 127.0.0.53");
+    expect((await call("child", childToken, "2", "fail")).status).toBe(400);
+    expect((await call("child", childToken, "3", "constructor")).status).toBe(400);
+    expect((await call("child", childToken, "4")).status).toBe(200);
+  } finally { server.stop(true); rmSync(dir, { recursive: true }); }
+});
+
+test("rebound identity cannot enter a harness with an inherited active request", async () => {
+  const dir = mkdtempSync(join(tmpdir(), "spectest-network-"));
+  const bindingPath = join(dir, "binding.json"), token = "s".repeat(64);
+  const bind = (instanceId: string) => writeFileSync(bindingPath, JSON.stringify({ instanceId, token }));
+  let entered!: () => void, release!: () => void;
+  const started = new Promise<void>(r => entered = r);
+  const blocked = new Promise<void>(r => release = r);
+  const server = serveNetwork({ wait: async () => { entered(); await blocked; return {}; }, ping: async () => ({}) }, { bindingPath, hostname: "127.0.0.1", port: 0 });
+  const call = (instanceId: string, method: string) => fetch(`${server.url}rpc`, {
+    method: "POST", headers: { Authorization: `Bearer ${token}`, "X-Spectest-Instance": instanceId },
+    body: JSON.stringify({ requestId: crypto.randomUUID(), method }),
+  });
+  try {
+    bind("parent");
+    const pending = call("parent", "wait");
+    await started;
+    bind("child");
+    expect((await call("child", "ping")).status).toBe(409);
+    release();
+    expect((await pending).status).toBe(200);
+    expect((await call("child", "ping")).status).toBe(200);
+  } finally { release(); server.stop(true); rmSync(dir, { recursive: true }); }
+});
+
+test("async work survives polling, authenticates reads, and never replays after acknowledgement", async () => {
+  const dir = mkdtempSync(join(tmpdir(), "spectest-network-"));
+  const bindingPath = join(dir, "binding.json"), token = "s".repeat(64);
+  const bind = (instanceId: string) => writeFileSync(bindingPath, JSON.stringify({ instanceId, token }));
+  let release!: () => void, counter = 0;
+  const blocked = new Promise<void>(r => release = r);
+  const server = serveNetwork({ wait: async () => { counter++; await blocked; return "finished"; },
+    fail: async () => { throw Error("async failure"); } }, { bindingPath, hostname: "127.0.0.1", port: 0 });
+  const call = (method: string, requestId = "one", instanceId = "parent", key = token, handler = "wait") => fetch(`${server.url}rpc?requestId=${requestId}`, {
+    method, headers: { Authorization: `Bearer ${key}`, "X-Spectest-Instance": instanceId },
+    ...(method === "POST" ? { body: JSON.stringify({ requestId, method: handler, async: true }) } : {}),
+  });
+  try {
+    bind("parent");
+    expect((await call("POST")).status).toBe(202);
+    expect((await call("GET")).status).toBe(202);
+    expect((await call("DELETE")).status).toBe(202); // acknowledgement cannot cancel work
+    expect((await call("POST")).status).toBe(409);
+    expect((await call("GET", "one", "parent", "bad")).status).toBe(401);
+    expect((await call("GET", "one", "child")).status).toBe(409);
+    bind("child");
+    expect((await call("GET", "one", "child")).status).toBe(409);
+    bind("parent");
+    release();
+    for (let i = 0; i < 2; i++) expect(await (await call("GET")).json()).toEqual({ instanceId: "parent", requestId: "one", result: "finished" });
+    expect(counter).toBe(1);
+    expect((await call("DELETE")).status).toBe(200);
+    expect((await call("GET")).status).toBe(404);
+    expect((await call("POST")).status).toBe(409);
+    expect((await call("POST", "error", "parent", token, "fail")).status).toBe(202);
+    const failure = await call("GET", "error");
+    expect(failure.status).toBe(400);
+    expect((await failure.json()).message).toContain("async failure");
+    bind("child");
+    expect((await call("GET", "error", "child")).status).toBe(404);
+    expect((await call("POST", "one", "child")).status).toBe(202);
+    expect((await call("GET", "one", "child")).status).toBe(200);
+    expect(counter).toBe(2);
+  } finally { release(); server.stop(true); rmSync(dir, { recursive: true }); }
+});
+
+test("async results have bounded retention and expiration does not replay work", async () => {
+  const dir = mkdtempSync(join(tmpdir(), "spectest-network-"));
+  const bindingPath = join(dir, "binding.json"), token = "s".repeat(64);
+  writeFileSync(bindingPath, JSON.stringify({ instanceId: "parent", token }));
+  const server = serveNetwork({ large: async () => "x".repeat(2000) }, {
+    bindingPath, hostname: "127.0.0.1", port: 0, resultLimits: { count: 1, bytes: 1000, ttlMs: 100 },
+  });
+  const call = (method: string, requestId: string) => fetch(`${server.url}rpc?requestId=${requestId}`, {
+    method, headers: { Authorization: `Bearer ${token}`, "X-Spectest-Instance": "parent" },
+    ...(method === "POST" ? { body: JSON.stringify({ requestId, method: "large", async: true }) } : {}),
+  });
+  try {
+    expect((await call("POST", "one")).status).toBe(202);
+    expect((await call("GET", "one")).status).toBe(507);
+    expect((await call("POST", "two")).status).toBe(429);
+    await Bun.sleep(120);
+    expect((await call("GET", "one")).status).toBe(404);
+    expect((await call("POST", "one")).status).toBe(409);
+    expect((await call("POST", "two")).status).toBe(202);
+  } finally { server.stop(true); rmSync(dir, { recursive: true }); }
+});
+
+test("Smol ingress uses a separate guest credential and still fences restored identity", async () => {
+  const dir = mkdtempSync(join(tmpdir(), "spectest-smol-network-"));
+  const bindingPath = join(dir, "binding.json"), token = "s".repeat(64);
+  writeFileSync(bindingPath, JSON.stringify({ instanceId: "child", token }));
+  let calls = 0;
+  const server = serveNetwork({ ping: async () => ++calls }, { bindingPath, hostname: "127.0.0.1", port: 0 });
+  const call = (key: string, id = "child") => fetch(`${server.url}rpc`, {
+    method: "POST", headers: { "X-Spectest-Harness-Authorization": `Bearer ${key}`, "X-Spectest-Instance": id },
+    body: JSON.stringify({ requestId: crypto.randomUUID(), method: "ping" }),
+  });
+  try {
+    expect((await call("account-key-is-not-a-guest-key")).status).toBe(401);
+    expect((await call(token, "parent")).status).toBe(409);
+    expect((await call(token)).status).toBe(200);
+    expect(calls).toBe(1);
+  } finally { server.stop(true); rmSync(dir, { recursive: true }); }
+});
+
+test("keep-alive connections reauthenticate every request after rebinding", async () => {
+  const { createConnection } = await import("node:net");
+  const dir = mkdtempSync(join(tmpdir(), "spectest-keepalive-"));
+  const bindingPath = join(dir, "binding.json");
+  const parentToken = "p".repeat(64), childToken = "c".repeat(64);
+  const bind = (instanceId: string, token: string) => writeFileSync(bindingPath, JSON.stringify({ instanceId, token }));
+  bind("parent", parentToken);
+  const server = serveNetwork({ ping: async () => ({ ok: true }) }, { bindingPath, hostname: "127.0.0.1", port: 0 });
+  // Use one actual TCP connection: Bun's node:http shim does not expose reusedSocket.
+  const socket = createConnection({ host: "127.0.0.1", port: server.port! });
+  const call = (instanceId: string, token: string) => new Promise<number>((resolve, reject) => {
+    let data = "";
+    const cleanup = () => { socket.off("data", read); socket.off("error", fail); socket.off("end", closed); };
+    const fail = (error: Error) => { cleanup(); reject(error); };
+    const closed = () => fail(Error("server closed the reusable connection"));
+    const read = (chunk: Buffer) => {
+      data += chunk.toString();
+      const headerEnd = data.indexOf("\r\n\r\n");
+      if (headerEnd < 0) return;
+      const headers = data.slice(0, headerEnd);
+      const length = Number(headers.match(/content-length: (\d+)/i)?.[1]);
+      if (!Number.isFinite(length)) return fail(Error("missing response length"));
+      if (Buffer.byteLength(data.slice(headerEnd + 4)) < length) return;
+      cleanup(); resolve(Number(headers.split(" ")[1]));
+    };
+    socket.on("data", read); socket.once("error", fail); socket.once("end", closed);
+    const body = JSON.stringify({ requestId: crypto.randomUUID(), method: "ping" });
+    socket.write(`POST /rpc HTTP/1.1\r\nHost: 127.0.0.1\r\nConnection: keep-alive\r\nAuthorization: Bearer ${token}\r\nX-Spectest-Instance: ${instanceId}\r\nContent-Length: ${Buffer.byteLength(body)}\r\n\r\n${body}`);
+  });
+  try {
+    expect(await call("parent", parentToken)).toBe(200);
+    expect(await call("parent", parentToken)).toBe(200);
+    bind("child", childToken);
+    expect(await call("parent", parentToken)).toBe(401);
+    expect(await call("child", childToken)).toBe(200);
+  } finally { socket.destroy(); server.stop(true); rmSync(dir, { recursive: true }); }
+});
+
+test("relay forwards future SDK methods and deadlines without importing their registry", async () => {
+  const dir = mkdtempSync(join(tmpdir(), "spectest-forward-"));
+  const bindingPath = join(dir, "binding.json"), token = "s".repeat(64);
+  writeFileSync(bindingPath, JSON.stringify({ instanceId: "vm", token }));
+  const calls: unknown[] = [];
+  const server = serveNetwork({}, { bindingPath, hostname: "127.0.0.1", port: 0,
+    dispatch: async (method, params, timeoutMs) => { calls.push({ method, params, timeoutMs }); return { opaque: true }; },
+  });
+  const call = (key: string, timeoutMs: number) => fetch(`${server.url}rpc`, {
+    method: "POST", headers: { Authorization: `Bearer ${key}`, "X-Spectest-Instance": "vm" },
+    body: JSON.stringify({ requestId: crypto.randomUUID(), method: "futureSdkMethod", params: { x: 2 }, timeoutMs }),
+  });
+  try {
+    expect((await call("wrong", 1234)).status).toBe(401);
+    expect((await call(token, -1)).status).toBe(400);
+    expect(calls).toEqual([]);
+    expect((await (await call(token, 1234)).json()).result).toEqual({ opaque: true });
+    expect(calls).toEqual([{ method: "futureSdkMethod", params: { x: 2 }, timeoutMs: 1234 }]);
+  } finally { server.stop(true); rmSync(dir, { recursive: true }); }
+});
+
+test("result waits wake on completion, reconnect after disconnect, and do not block other calls", async () => {
+  const dir = mkdtempSync(join(tmpdir(), "spectest-result-wait-"));
+  const bindingPath = join(dir, "binding.json"), token = "s".repeat(64);
+  writeFileSync(bindingPath, JSON.stringify({ instanceId: "vm", token }));
+  let release!: () => void, calls = 0;
+  const blocked = new Promise<void>(resolve => release = resolve);
+  const server = serveNetwork({ run: async () => { calls++; await blocked; return "done"; },
+    health: async () => "healthy" }, { bindingPath, hostname: "127.0.0.1", port: 0 });
+  const headers = { Authorization: `Bearer ${token}`, "X-Spectest-Instance": "vm" };
+  const get = (waitMs: number, signal?: AbortSignal) => fetch(`${server.url}rpc?requestId=one&waitMs=${waitMs}`, { headers, signal });
+  try {
+    const accepted = await fetch(`${server.url}rpc`, { method: "POST", headers,
+      body: JSON.stringify({ requestId: "one", method: "run", async: true }) });
+    expect((await accepted.json()).resultWait).toBe(true);
+    expect((await get(-1)).status).toBe(400);
+    expect((await get(25_001)).status).toBe(400);
+    const before = performance.now();
+    expect((await get(40)).status).toBe(202);
+    expect(performance.now() - before).toBeGreaterThanOrEqual(30);
+
+    const abort = new AbortController();
+    const disconnected = get(25_000, abort.signal).then(() => false, () => true);
+    await Bun.sleep(20);
+    abort.abort();
+    expect(await disconnected).toBe(true);
+    let finished = false;
+    const waiting = get(25_000).then(r => { finished = true; return r; });
+    const health = await fetch(`${server.url}rpc`, { method: "POST", headers,
+      body: JSON.stringify({ requestId: "health", method: "health" }) });
+    expect((await health.json()).result).toBe("healthy");
+    expect(finished).toBe(false);
+    release();
+    expect((await (await waiting).json()).result).toBe("done");
+    expect((await (await get(25_000)).json()).result).toBe("done");
+    expect(calls).toBe(1);
+  } finally { release(); server.stop(true); rmSync(dir, { recursive: true }); }
+});
+
+test("an outstanding result wait cannot return the old VM's result after rebinding", async () => {
+  const dir = mkdtempSync(join(tmpdir(), "spectest-wait-rebind-"));
+  const bindingPath = join(dir, "binding.json"), token = "s".repeat(64);
+  const bind = (instanceId: string) => writeFileSync(bindingPath, JSON.stringify({ instanceId, token }));
+  bind("parent");
+  let release!: () => void;
+  const blocked = new Promise<void>(resolve => release = resolve);
+  const server = serveNetwork({ run: async () => { await blocked; return "parent data"; } },
+    { bindingPath, hostname: "127.0.0.1", port: 0 });
+  const headers = { Authorization: `Bearer ${token}`, "X-Spectest-Instance": "parent" };
+  try {
+    expect((await fetch(`${server.url}rpc`, { method: "POST", headers,
+      body: JSON.stringify({ requestId: "one", method: "run", async: true }) })).status).toBe(202);
+    const waiting = fetch(`${server.url}rpc?requestId=one&waitMs=25000`, { headers });
+    await Bun.sleep(20);
+    bind("child");
+    release();
+    const response = await waiting;
+    expect(response.status).toBe(409);
+    expect(await response.text()).not.toContain("parent data");
+  } finally { release(); server.stop(true); rmSync(dir, { recursive: true }); }
+});

package/src/harness/network.ts

@@ -0,0 +1,178 @@
+/** Experimental cloud transport. No VM agent or control-plane credential lives here.
+ * Read the binding on every request: checkpoint children inherit the process heap,
+ * but receive a new binding file before the controller dispatches work to them.
+ * Future guest-initiated forks must perform the same rebind before accepting work.
+ */
+import { readFileSync, writeFileSync } from "node:fs";
+import { timingSafeEqual } from "node:crypto";
+import { codeOf } from "./methods";
+import { describeThrow } from "./protocol";
+
+export interface NetworkBinding { instanceId: string; token: string }
+type PendingResult = { body?: string; status?: number; completedAt?: number; bytes: number;
+  waiters: Set<() => void> };
+type Handler = (params: Record<string, unknown>) => Promise<unknown>;
+
+export function serveNetwork(
+  registry: Record<string, Handler>,
+  options: { bindingPath: string; hostname?: string; port?: number; resolverPath?: string;
+    resultLimits?: { count?: number; bytes?: number; ttlMs?: number };
+    dispatch?: (method: string, params: Record<string, unknown>, timeoutMs?: number) => Promise<unknown> },
+) {
+  let session = "";
+  const seen = new Set<string>();
+  let active = 0;
+  const results = new Map<string, PendingResult>();
+  const maxResults = options.resultLimits?.count ?? 128;
+  const maxBytes = options.resultLimits?.bytes ?? 64 * 1024 * 1024;
+  const ttlMs = options.resultLimits?.ttlMs ?? 10 * 60_000;
+  let resultBytes = 0;
+  const forget = (id: string) => {
+    resultBytes -= results.get(id)?.bytes ?? 0;
+    results.delete(id);
+  };
+  const expire = () => {
+    for (const [id, result] of results)
+      if (result.completedAt !== undefined && Date.now() - result.completedAt >= ttlMs) forget(id);
+  };
+  const reply = (body: unknown, status = 200) => Response.json(body, {
+    status, headers: { "Cache-Control": "no-store" },
+  });
+  return Bun.serve({
+    hostname: options.hostname ?? "0.0.0.0",
+    port: options.port ?? 4318,
+    maxRequestBodySize: 16 * 1024 * 1024,
+    async fetch(req, server) {
+      const url = new URL(req.url);
+      if (url.pathname !== "/rpc" || !["POST", "GET", "DELETE"].includes(req.method))
+        return reply({ error: "not_found" }, 404);
+      let binding: NetworkBinding;
+      try {
+        binding = JSON.parse(readFileSync(options.bindingPath, "utf8"));
+        if (!binding.instanceId || !binding.token || binding.token.length < 32) throw Error();
+      } catch { return reply({ error: "unbound" }, 503); }
+      const supplied = Buffer.from(req.headers.get("X-Spectest-Harness-Authorization") ?? req.headers.get("Authorization") ?? "");
+      const expected = Buffer.from(`Bearer ${binding.token}`);
+      if (supplied.length !== expected.length || !timingSafeEqual(supplied, expected))
+        return reply({ error: "unauthorized" }, 401);
+      if (req.headers.get("X-Spectest-Instance") !== binding.instanceId)
+        return reply({ error: "wrong_instance" }, 409);
+      // Neither parent request IDs nor network connections are child identity.
+      const nextSession = `${binding.instanceId}:${binding.token}`;
+      if (session !== nextSession) {
+        if (active) return reply({ error: "restore_during_request" }, 409);
+        session = nextSession;
+        seen.clear();
+        results.clear();
+        resultBytes = 0;
+      }
+      expire();
+      if (req.method !== "POST") {
+        const requestId = url.searchParams.get("requestId");
+        const envelope = { instanceId: binding.instanceId, requestId };
+        const result = requestId ? results.get(requestId) : undefined;
+        if (!result) return reply({ ...envelope, error: "result_not_found" }, 404);
+        if (req.method === "GET") {
+          const waitMs = Number(url.searchParams.get("waitMs") ?? 0);
+          if (!Number.isSafeInteger(waitMs) || waitMs < 0 || waitMs > 25_000)
+            return reply({ ...envelope, error: "invalid_wait" }, 400);
+          if (result.body === undefined && waitMs > 0 && !req.signal.aborted) {
+            server.timeout(req, 0);
+            // Disconnecting a waiter never cancels the operation. Remove its
+            // listener on every exit, including aborts and bounded timeouts.
+            await new Promise<void>(resolve => {
+              const done = () => {
+                clearTimeout(timer);
+                result.waiters.delete(done);
+                req.signal.removeEventListener("abort", done);
+                resolve();
+              };
+              const timer = setTimeout(done, waitMs);
+              result.waiters.add(done);
+              req.signal.addEventListener("abort", done, { once: true });
+              if (req.signal.aborted) done();
+            });
+            // A restored heap or a concurrent acknowledgement must not expose
+            // a stale result to a connection admitted under the old identity.
+            try {
+              const current: NetworkBinding = JSON.parse(readFileSync(options.bindingPath, "utf8"));
+              if (current.instanceId !== binding.instanceId || current.token !== binding.token)
+                return reply({ ...envelope, error: "stale_binding" }, 409);
+            } catch { return reply({ ...envelope, error: "unbound" }, 503); }
+            if (results.get(requestId!) !== result)
+              return reply({ ...envelope, error: "result_not_found" }, 404);
+          }
+        }
+        if (result.body === undefined) return reply({ ...envelope, state: "pending", resultWait: true }, 202);
+        if (req.method === "DELETE") {
+          forget(requestId!);
+          return reply({ ...envelope, state: "acknowledged" });
+        }
+        return new Response(result.body, { status: result.status,
+          headers: { "Content-Type": "application/json", "Cache-Control": "no-store" } });
+      }
+      let body: { requestId: string; method: string; params?: Record<string, unknown>; async?: boolean; timeoutMs?: number };
+      try {
+        body = await req.json();
+        if (!body || typeof body.requestId !== "string" || body.requestId.length > 100 ||
+            !body.requestId || typeof body.method !== "string" ||
+            (body.async !== undefined && typeof body.async !== "boolean") ||
+            (body.timeoutMs !== undefined && (!Number.isSafeInteger(body.timeoutMs) || body.timeoutMs <= 0)) ||
+            (body.params !== undefined && (!body.params || typeof body.params !== "object" || Array.isArray(body.params))))
+          throw Error();
+      } catch { return reply({ error: "invalid_request" }, 400); }
+      // A request body may have been in flight across a restore/rebind.
+      try {
+        const current: NetworkBinding = JSON.parse(readFileSync(options.bindingPath, "utf8"));
+        if (current.instanceId !== binding.instanceId || current.token !== binding.token)
+          return reply({ error: "stale_binding" }, 409);
+      } catch { return reply({ error: "unbound" }, 503); }
+      const envelope = { instanceId: binding.instanceId, requestId: body.requestId };
+      if (seen.has(body.requestId)) return reply({ ...envelope, error: "duplicate_request" }, 409);
+      const handler = Object.hasOwn(registry, body.method) ? registry[body.method]
+        : options.dispatch ? (params: Record<string, unknown>) => options.dispatch!(body.method, params, body.timeoutMs) : undefined;
+      if (!handler) return reply({ ...envelope, error: "unimplemented" }, 400);
+      if (active >= 32) return reply({ ...envelope, error: "too_many_requests" }, 429);
+      if (body.async && results.size >= maxResults)
+        return reply({ ...envelope, error: "result_capacity" }, 429);
+      seen.add(body.requestId);
+      if (seen.size > 4096) seen.delete(seen.values().next().value!);
+      // Long test calls are bounded by the caller and runner, not the HTTP idle timer.
+      server.timeout(req, 0);
+      active++;
+      const execute = async () => {
+        try {
+          // Unikraft rewrites the resolver on checkpoint restore AND native wake.
+          if (options.resolverPath) {
+            const resolver = "nameserver 127.0.0.53\noptions edns0\n";
+            if (readFileSync(options.resolverPath, "utf8") !== resolver)
+              writeFileSync(options.resolverPath, resolver);
+          }
+          return { body: JSON.stringify({ ...envelope, result: await handler(body.params ?? {}) }), status: 200 };
+        } catch (error) {
+          return { body: JSON.stringify({ ...envelope, error: codeOf(error), message: describeThrow(error) }), status: 400 };
+        } finally { active--; }
+      };
+      if (body.async) {
+        const result: PendingResult = { bytes: 0, waiters: new Set() };
+        results.set(body.requestId, result);
+        // Retain work and its outcome independently of any one HTTP connection.
+        void execute().then(completed => {
+          let bytes = Buffer.byteLength(completed.body);
+          if (resultBytes + bytes > maxBytes) {
+            completed = { body: JSON.stringify({ ...envelope, error: "result_too_large",
+              message: "Harness result storage limit exceeded; work must not be replayed" }), status: 507 };
+            bytes = Buffer.byteLength(completed.body);
+          }
+          Object.assign(result, completed, { bytes, completedAt: Date.now() });
+          resultBytes += bytes;
+          for (const done of result.waiters) done();
+        });
+        return reply({ ...envelope, state: "pending", resultWait: true }, 202);
+      }
+      const completed = await execute();
+      return new Response(completed.body, { status: completed.status,
+        headers: { "Content-Type": "application/json", "Cache-Control": "no-store" } });
+    },
+  });
+}

package/src/locator-recording.test.ts

@@ -0,0 +1,150 @@
+import { expect, test } from "bun:test";
+import { desktopStrategy, makeLocator, type LocatorBackend } from "./locator.js";
+import type { RecordableFields } from "./browser.js";
+import type { Page } from "playwright-core";
+
+// Exercise public locator methods at the recording seam. Arguments must be
+// available even when Playwright rejects an operation before it completes.
+function recorder() {
+  const events: { action: string; fields: Partial<RecordableFields> }[] = [];
+  const backend: LocatorBackend = {
+    async pageOp(action, fields) {
+      events.push({ action, fields });
+      return undefined as never;
+    },
+    async silentRead() { throw new Error("unexpected read"); },
+    async rawTap() {},
+    async recordSettled() { return undefined; },
+  };
+  const locator = (css: string) => makeLocator(backend, desktopStrategy, { steps: [{ m: "locator", args: [css] }] });
+  return { events, locator };
+}
+
+test("records requested state, selection and drag destination before execution", async () => {
+  const { events, locator } = recorder();
+  const input = locator("#input");
+  await input.setChecked(false);
+  await input.selectOption({ label: "Sweden" });
+  await input.selectOption(["Red", "Blue"]);
+  await input.dragTo(locator("#drop zone").nth(2));
+  await input.waitFor({ state: "hidden" });
+  await input.waitFor();
+  expect(events[3].fields.destinationTarget).toEqual([
+    { method: "locator", args: ["#drop zone"] }, { method: "nth", args: [2] },
+  ]);
+  expect(events.map(({ action, fields: { target, destinationTarget, ...fields } }) => ({ action, ...fields }))).toEqual([
+    { action: "setChecked", selector: 'css "#input"', checked: false },
+    { action: "selectOption", selector: 'css "#input"', values: { label: "Sweden" } },
+    { action: "selectOption", selector: 'css "#input"', values: ["Red", "Blue"] },
+    { action: "dragTo", selector: 'css "#input"' },
+    { action: "waitFor", selector: 'css "#input"', state: "hidden" },
+    { action: "waitFor", selector: 'css "#input"', state: "visible" },
+  ]);
+});
+
+test("preserves empty input and file removal, script source and combined filters", async () => {
+  const { events, locator } = recorder();
+  const input = locator("#input");
+  await input.fill("");
+  await input.setInputFiles([]);
+  await input.evaluate("read text", (el) => el.textContent);
+  await input.filter({ hasText: "Hello", hasNotText: "Goodbye" }).first().focus();
+  expect(events[0].fields.target).toEqual([{ method: "locator", args: ["#input"] }]);
+  expect(events[0].fields.text).toBe("");
+  expect(events[1].fields.files).toEqual([]);
+  expect(events[2].fields.script).toContain("textContent");
+  expect(events[2].fields.description).toBe("read text");
+  expect(events[3].fields.selector).toBe('css "#input" ‹ filter(hasText: "Hello") .first()');
+});
+
+
+test("serializes nested locator and regex arguments as data, including all filter conditions", async () => {
+  const { events, locator } = recorder();
+  await locator("#form").getByRole("button", { name: /Submit|Save/i })
+    .filter({ has: locator("span").getByText("Confirm"), hasNotText: /Cancel/ }).nth(2).focus();
+  expect(JSON.parse(JSON.stringify(events[0].fields.target))).toEqual([
+    { method: "locator", args: ["#form"] },
+    { method: "getByRole", args: ["button", { name: { regex: "Submit|Save", flags: "i" } }] },
+    { method: "filter", args: [{ has: [{ method: "locator", args: ["span"] }, { method: "getByText", args: ["Confirm", null] }], hasNotText: { regex: "Cancel", flags: "" } }] },
+    { method: "nth", args: [2] },
+  ]);
+});
+
+function executingRecorder() {
+  const events: { action: string; fields: Partial<RecordableFields> }[] = [];
+  const state = { id: 42, probeFails: false, probes: 0, action: async () => "result" as unknown };
+  const subject = new Proxy({
+    evaluateAll: async () => {
+      state.probes++;
+      if (state.probeFails) throw new Error("recorder unavailable");
+      return state.id;
+    },
+  }, {
+    get: (target, key) => key === "evaluateAll" ? target.evaluateAll : () => state.action(),
+  });
+  const page = { locator: () => subject } as unknown as Page;
+  const backend: LocatorBackend = {
+    async pageOp(action, fields, fn) {
+      try { return await fn(page); }
+      finally { events.push({ action, fields: { ...fields } }); }
+    },
+    async silentRead(fn) { return fn(page); },
+    async rawTap() {},
+    async recordSettled() { return undefined; },
+  };
+  const locator = makeLocator(backend, desktopStrategy, { steps: [{ m: "locator", args: ["#target"] }] });
+  return { locator, state, events };
+}
+
+test("records node identity for element actions, reads and evaluation", async () => {
+  const { locator, events } = executingRecorder();
+  await locator.hover();
+  await locator.check();
+  await locator.selectOption("Sweden");
+  await locator.fill("hello");
+  await locator.focus();
+  await locator.scrollIntoViewIfNeeded();
+  await locator.waitFor();
+  expect(await locator.textContent()).toBe("result");
+  await locator.getAttribute("title");
+  await locator.evaluate("inspect element", (el) => el.textContent);
+  expect(events).toHaveLength(10);
+  for (const event of events) expect(event.fields.targetNodeId).toBe(42);
+});
+
+test("keeps the acted-on identity when the operation replaces its target", async () => {
+  const { locator, state, events } = executingRecorder();
+  state.action = async () => { state.id = 99; };
+  await locator.press("Enter");
+  expect(events[0]!.fields.targetNodeId).toBe(42);
+  expect(state.probes).toBe(1);
+});
+
+test("captures an auto-waited target after it appears", async () => {
+  const { locator, state, events } = executingRecorder();
+  state.id = 0;
+  state.action = async () => { state.id = 77; };
+  await locator.fill("hello");
+  expect(events[0]!.fields.targetNodeId).toBe(77);
+});
+
+test("target probing never replaces operation results or errors", async () => {
+  const { locator, state, events } = executingRecorder();
+  state.probeFails = true;
+  expect(await locator.textContent()).toBe("result");
+  const error = new Error("application failure");
+  state.action = async () => { throw error; };
+  await expect(locator.hover()).rejects.toBe(error);
+  expect(events.every((event) => event.fields.targetNodeId === undefined)).toBe(true);
+});
+
+test("does not choose an arbitrary target for collection reads or disappearance waits", async () => {
+  const { locator, state, events } = executingRecorder();
+  await locator.count();
+  await locator.allTextContents();
+  await locator.allInnerTexts();
+  await locator.waitFor({ state: "hidden" });
+  await locator.waitFor({ state: "detached" });
+  expect(state.probes).toBe(0);
+  expect(events.every((event) => event.fields.targetNodeId === undefined)).toBe(true);
+});