@specific.dev/spectest 0.121.0 → 0.122.0

package/src/components/supabase-coverage.test.ts

@@ -0,0 +1,261 @@
+import { expect, test } from "bun:test";
+import { mkdtemp, mkdir, writeFile, readdir, rm } from "node:fs/promises";
+import { homedir } from "node:os";
+import path from "node:path";
+import { supabase } from "./supabase.js";
+import { SUPABASE_COVERAGE_COLLECTOR, supabaseFunctionsCoverage } from "./supabase-coverage.js";
+import { isWellFormedReport } from "../harness/coverage.js";
+import type { ServiceDefinition } from "../index.js";
+
+type Report = { name: string; content: string };
+const runtime = process.env.SPECTEST_TEST_EDGE_RUNTIME;
+
+// Use Supabase's pinned v1.74.0 release executable (and its bundled libraries),
+// not stock Deno. No database, Docker daemon, or production endpoint is needed.
+// SPECTEST_TEST_EDGE_RUNTIME=/path/bin/edge-runtime bun test src/components/supabase-coverage.test.ts
+for (const layout of ["shared", "per-function", "workspace"] as const) {
+  const mode = layout === "shared" ? "shared" : "per-function";
+  test.skipIf(!runtime)(`real edge runtime: ${layout} source identity, setup and capture deltas`, async () => {
+    // /tmp is a private in-memory filesystem inside Edge Runtime. Keep sources
+    // on disk and generated helpers on a different root to exercise relocation
+    // exactly as production's /repo and /home/deno do.
+    const root = await mkdtemp(path.join(homedir(), ".spectest-edge-test-"));
+    const generated = await mkdtemp("/dev/shm/spectest-edge-test-");
+    const repository = path.join(root, "repo");
+    const functions = path.join(repository, "custom/backend/functions");
+    const oldWorkspace = process.env.SPECTEST_WORKSPACE;
+    let child: ReturnType<typeof Bun.spawn> | undefined;
+    let logs: Promise<string> | undefined;
+    // Reserve random ports; the executable starts immediately after release.
+    const reserve = () => Bun.serve({ port: 0, fetch: () => new Response() });
+    const http = reserve(), inspector = reserve();
+    const httpPort = http.port!, inspectorPort = inspector.port!;
+    http.stop(true); inspector.stop(true);
+    const base = `http://127.0.0.1:${httpPort}`;
+    try {
+      await mkdir(path.join(functions, "alpha"), { recursive: true });
+      await mkdir(path.join(functions, "beta"), { recursive: true });
+      await mkdir(path.join(repository, "packages/shared"), { recursive: true });
+      await writeFile(path.join(repository, "packages/shared/logic.ts"), [
+        'export function first(): string {', '  return "first ✓🙂";', '}',
+        'export function second(): string {', '  return "second";', '}',
+        'export function initialize(): string { return "initialized"; }',
+      ].join("\n"));
+      await writeFile(path.join(functions, "alpha/index.ts"), [
+        `import { first, second, initialize } from "${mode === "per-function" ? "shared-logic" : "../../../../packages/shared/logic.ts"}";`,
+        'initialize();',
+        'Deno.serve(req => new Response(new URL(req.url).pathname.endsWith("/first") ? first() : second()));',
+      ].join("\n"));
+      await writeFile(path.join(functions, "beta/index.ts"), 'export default { fetch() { return new Response("beta"); } };\n');
+      if (mode === "per-function") {
+        const imports = { "shared-logic": "../../../../packages/shared/logic.ts" };
+        if (layout === "workspace") {
+          await writeFile(path.join(repository, "deno.json"), JSON.stringify({
+            workspace: ["./custom/backend/functions/alpha", "./packages/shared"],
+          }));
+          await writeFile(path.join(repository, "packages/shared/deno.json"), JSON.stringify({
+            name: "@fixture/shared", version: "1.0.0", exports: "./logic.ts",
+          }));
+          await writeFile(path.join(functions, "alpha/deno.json"), JSON.stringify({ imports }));
+        } else {
+          await writeFile(path.join(functions, "alpha/deno.json"), '{"importMap":"./import_map.json"}');
+          await writeFile(path.join(functions, "alpha/import_map.json"), JSON.stringify({ imports }));
+        }
+        // More workers than runtime threads: coverage gates must keep the
+        // event loop live while all inspectors attach concurrently.
+        for (let i = 0; i < 18; i++) {
+          const dir = path.join(functions, `extra${i}`);
+          await mkdir(dir);
+          await writeFile(path.join(dir, "index.ts"), 'Deno.serve(() => new Response("extra"));\n');
+        }
+      }
+      process.env.SPECTEST_WORKSPACE = repository;
+      const parts = supabase({ name: "custom-stack", dir: "custom/backend" }).group.services({
+        name: "custom-stack", key: part => `custom-stack-${part}`,
+      });
+      const service = parts.functions as ServiceDefinition;
+      expect(service.coverage).toBeDefined();
+      const replace = (text: string) => text.replaceAll("/home/deno", generated)
+        .replaceAll("/repo", repository).replaceAll("127.0.0.1:9229", `127.0.0.1:${inspectorPort}`);
+      for (const file of service.files!) {
+        const target = replace(file.path);
+        await mkdir(path.dirname(target), { recursive: true });
+        await writeFile(target, replace(file.content));
+      }
+      child = Bun.spawn([runtime!, "start", "--main-service", path.join(generated, "main"),
+        "--port", String(httpPort), `--inspect=127.0.0.1:${inspectorPort}`], {
+        env: { ...process.env, FUNCTIONS_DIR: functions, VERIFY_JWT: "false", EDGE_RUNTIME_WORKER_POOL_SIZE: "1" }, stdout: "ignore", stderr: "pipe",
+      });
+      logs = new Response(child.stderr).text();
+      const request = async (route: string, method = "GET") => {
+        const response = await fetch(base + route, { method, signal: AbortSignal.timeout(60_000) });
+        const text = await response.text();
+        if (!response.ok) throw new Error(`${route}: ${response.status}: ${text}`);
+        return text;
+      };
+      const deadline = Date.now() + 20_000;
+      while (true) {
+        try { await request("/_spectest/health"); break; } catch (error) {
+          if (Date.now() > deadline || child.exitCode !== null) throw error;
+          await Bun.sleep(30);
+        }
+      }
+      const warmed = JSON.parse(await request("/_spectest/warm"));
+      expect(warmed.mode).toBe(mode);
+      expect(warmed.failed).toEqual({});
+      const records = new Map<string, any>();
+      const captures: Report[][] = [];
+      async function capture() {
+        const { reports } = JSON.parse(await request("/_spectest/coverage", "POST")) as { reports: Report[] };
+        captures.push(reports);
+        for (const report of reports) {
+          expect(isWellFormedReport(report.content, report.name)).toBe(true);
+          const doc = JSON.parse(report.content);
+          if (doc.spectestScript) {
+            records.set(path.basename(report.name, ".json"), doc.spectestScript);
+            expect(report.content).not.toContain("sourcesContent");
+            expect(doc.spectestScript.url.startsWith(`file://${repository}/`)).toBe(true);
+          }
+        }
+        const dump = JSON.parse(reports.find(r => /^edge-\d+\.json$/.test(r.name))!.content);
+        const names = new Set<string>();
+        for (const script of dump.result) {
+          const record = records.get(script.spectestScript);
+          expect(record).toBeDefined();
+          for (const f of script.functions) {
+            const definition = record.functions.find((d: any) => d[1] === f[0] && d[2] === f[0] + f[1]);
+            expect(definition).toBeDefined();
+            if (f[2] > 0) names.add(definition[0]);
+          }
+        }
+        return { names, dump, reports };
+      }
+      const setup = await capture();
+      expect(setup.dump.result.length).toBeGreaterThan(0);
+      expect(setup.names.has("initialize")).toBe(true);
+      expect(setup.names.has("first")).toBe(false);
+      expect(setup.names.has("second")).toBe(false);
+      expect((await capture()).dump.result).toEqual([]);
+      expect(await request("/alpha/first")).toBe("first ✓🙂");
+      const first = await capture();
+      expect(first.names.has("first")).toBe(true);
+      expect(first.names.has("second")).toBe(false);
+      expect(first.reports.every(r => !r.name.startsWith("edge-scripts/"))).toBe(true);
+      expect(await request("/alpha/second")).toBe("second");
+      const second = await capture();
+      expect(second.names.has("first")).toBe(false);
+      expect(second.names.has("second")).toBe(true);
+      expect(await request("/beta")).toBe("beta");
+      expect((await capture()).dump.result.some((s: any) => s.url.endsWith("/beta/index.ts"))).toBe(true);
+      expect((await capture()).dump.result).toEqual([]);
+      // Optional handoff to the control-plane decoder regression below.
+      if (process.env.SPECTEST_EDGE_COVERAGE_FIXTURE) {
+        const serialized = JSON.stringify(captures).replaceAll(repository, "/repo");
+        await writeFile(process.env.SPECTEST_EDGE_COVERAGE_FIXTURE + "." + layout + ".json", serialized);
+      }
+      // Ensure the fallback actually created independent workers.
+      const targets = await fetch(`http://127.0.0.1:${inspectorPort}/json/list`).then(r => r.json()) as any[];
+      expect(targets.length).toBe(mode === "shared" ? 1 : 20);
+      expect((await readdir(path.join(functions, "alpha"))).some(name => name.startsWith(".spectest"))).toBe(false);
+    } finally {
+      if (oldWorkspace === undefined) delete process.env.SPECTEST_WORKSPACE;
+      else process.env.SPECTEST_WORKSPACE = oldWorkspace;
+      if (child) { child.kill("SIGKILL"); await child.exited; }
+      const output = await logs;
+      if (output?.includes("coverage") || output?.includes("error")) console.error(output);
+      await rm(root, { recursive: true, force: true });
+      await rm(generated, { recursive: true, force: true });
+    }
+  }, 150_000);
+}
+
+test("collector rejects missing workers and latches capture gaps", async () => {
+  // Exercise failure behavior without requiring an executable. Stop its timer;
+  // the protocol itself is exercised by the real-runtime tests above.
+  const { EdgeCoverage } = await import(`data:text/javascript;base64,${Buffer.from(SUPABASE_COVERAGE_COLLECTOR).toString("base64")}`);
+  const collector = new EdgeCoverage();
+  clearInterval(collector.timer);
+  collector.ready = async () => {};
+  collector.sessions.set("lost", { ready: Promise.resolve(), post: async () => { throw new Error("lost isolate"); } });
+  await expect(collector.capture()).rejects.toThrow("lost isolate");
+  collector.sessions.clear();
+  await expect(collector.capture()).rejects.toThrow("lost isolate");
+});
+
+test("collector overlaps isolate takes and descriptors, then merges deterministically", async () => {
+  const { EdgeCoverage } = await import(`data:text/javascript;base64,${Buffer.from(SUPABASE_COVERAGE_COLLECTOR).toString("base64")}`);
+  const collector = new EdgeCoverage();
+  clearInterval(collector.timer);
+  collector.ready = async () => {};
+  const takes = [Promise.withResolvers<any>(), Promise.withResolvers<any>()];
+  const descriptions = Array.from({ length: 4 }, () => Promise.withResolvers<any>());
+  const allTaking = Promise.withResolvers<void>();
+  const allDescribing = Promise.withResolvers<void>();
+  let taking = 0, describing = 0;
+  for (let i = 0; i < 2; i++) collector.sessions.set(String(i), {
+    base: "/", prefix: "/", entry: "/generated/entry.mjs",
+    post: async (method: string) => {
+      expect(method).toBe("Profiler.takePreciseCoverage");
+      if (++taking === 2) allTaking.resolve();
+      return takes[i]!.promise;
+    },
+  });
+  collector.describe = async (_session: unknown, script: any) => {
+    if (++describing === 4) allDescribing.resolve();
+    return descriptions[Number(script.scriptId)]!.promise;
+  };
+  const script = (i: number) => ({ scriptId: String(i), url: `file:///repo/${i % 2}.ts`,
+    functions: [{ functionName: "handler", ranges: [{ startOffset: 0, endOffset: 20, count: 1 }] }] });
+  const pending = collector.capture();
+  await allTaking.promise; // neither isolate needs the other's response to start
+  takes[1]!.resolve({ result: [script(2), script(3)] });
+  takes[0]!.resolve({ result: [script(0), script(1)] });
+  await allDescribing.promise; // all scripts overlap, including within one isolate
+  for (const i of [3, 2, 1, 0]) descriptions[i]!.resolve({ id: `record-${i % 2}`, content: `descriptor-${i % 2}` });
+  const { reports } = await pending;
+  expect(reports.map((r: Report) => r.name)).toEqual(["edge-scripts/record-0.json", "edge-scripts/record-1.json", "edge-1.json"]);
+  const dump = JSON.parse(reports[2].content);
+  expect(dump.result.map((r: any) => r.url)).toEqual(["file:///repo/0.ts", "file:///repo/1.ts", "file:///repo/0.ts", "file:///repo/1.ts"]);
+});
+
+test("failed parallel captures drain pending takes and permanently reject later captures", async () => {
+  const { EdgeCoverage } = await import(`data:text/javascript;base64,${Buffer.from(SUPABASE_COVERAGE_COLLECTOR).toString("base64")}`);
+  const collector = new EdgeCoverage();
+  clearInterval(collector.timer);
+  collector.ready = async () => {};
+  const slow = Promise.withResolvers<any>();
+  const started = Promise.withResolvers<void>();
+  let takes = 0;
+  collector.sessions.set("failed", { post: async () => { takes++; throw new Error("lost isolate"); } });
+  collector.sessions.set("slow", { post: async () => { takes++; started.resolve(); return slow.promise; } });
+  let settled = false;
+  const pending = collector.capture().then(() => null, (error: Error) => { settled = true; return error; });
+  await started.promise;
+  await Bun.sleep(0);
+  expect(settled).toBe(false);
+  await expect(collector.capture()).rejects.toThrow("already in progress");
+  expect(takes).toBe(2);
+  slow.resolve({ result: [] });
+  expect((await pending)?.message).toBe("lost isolate");
+  expect(collector.records.size).toBe(0);
+  await expect(collector.capture()).rejects.toThrow("lost isolate");
+  expect(takes).toBe(2);
+});
+
+test("function discovery changes invalidate the inventory for any component directory", async () => {
+  const adapter = supabaseFunctionsCoverage("nested/backend/functions");
+  const files = ["nested/backend/functions/one/index.ts", "nested/backend/functions/_shared/helpers.ts"];
+  let config = '{"imports":{}}';
+  const ctx = { projectFiles: async () => files, readProjectFile: async () => config } as any;
+  const before = await adapter.inventory!(ctx);
+  files.push("nested/backend/functions/_private/index.ts", "unrelated/functions/two/index.ts");
+  expect(await adapter.inventory!(ctx)).toEqual(before);
+  files.push("nested/backend/functions/two/index.ts");
+  expect(await adapter.inventory!(ctx)).not.toEqual(before);
+  const added = await adapter.inventory!(ctx);
+  files.push("nested/backend/functions/two/deno.json");
+  expect(await adapter.inventory!(ctx)).not.toEqual(added);
+  const configured = await adapter.inventory!(ctx);
+  config = '{"imports":{"shared":"./other.ts"}}';
+  expect(await adapter.inventory!(ctx)).not.toEqual(configured);
+});

package/src/components/supabase-coverage.ts

@@ -0,0 +1,373 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import type { CoverageAdapter } from "../coverage.js";
+import { rawFetch } from "../harness/raw-fetch.js";
+
+// Drain all work even on failure: no writes may outlive the capture boundary.
+async function finishAll<T>(pending: Promise<T>[]): Promise<T[]> {
+  const results = await Promise.allSettled(pending);
+  return results.map(result => {
+    if (result.status === "rejected") throw result.reason;
+    return result.value;
+  });
+}
+
+/** The inspector stays on container loopback; only the component's router
+ * talks to it. Reports use the existing, runtime-independent V8 wire format. */
+export function supabaseFunctionsCoverage(functionRoot: string): CoverageAdapter {
+  const shippedByService = new Map<string, Set<string>>();
+  return {
+    name: "supabase-functions",
+    reports: "delta",
+    sourceOptions: { sourceRoot: "." },
+    ownsReport: name => name.startsWith("edge-") || name.startsWith("edge-scripts/"),
+    async inventory(ctx) {
+      // Functions are discovered by directory, not by an import in user code.
+      // Changing the catalogue must invalidate selection even for a new file.
+      // A removed fingerprint with no executed unit conservatively runs all.
+      const prefix = functionRoot + "/";
+      const files = await ctx.projectFiles();
+      const entries = files.filter(file => {
+        if (!file.startsWith(prefix)) return false;
+        const parts = file.slice(prefix.length).split("/");
+        return parts.length === 2 && !/^[_.]/.test(parts[0]!) && parts[1] === "index.ts";
+      }).sort();
+      const configNames = new Set(["deno.json", "deno.jsonc", "deno.lock", "import_map.json", "package.json"]);
+      const configPaths = files.filter(file => {
+        if (!configNames.has(path.posix.basename(file))) return file === path.posix.join(path.posix.dirname(functionRoot), "config.toml");
+        const dir = path.posix.dirname(file);
+        return dir === "." || file.startsWith(prefix) || functionRoot.startsWith(dir + "/") || dir === functionRoot;
+      }).sort();
+      const configs = await Promise.all(configPaths.map(async file => [file, await ctx.readProjectFile(file)]));
+      const digest = createHash("sha256").update(JSON.stringify({ entries, configs })).digest("hex");
+      return [`manifest:edge-functions:${encodeURIComponent(functionRoot)}#${digest}`];
+    },
+    async capture(ctx) {
+      let shipped = shippedByService.get(ctx.service);
+      if (!shipped) shippedByService.set(ctx.service, shipped = new Set());
+      const response = await rawFetch(`http://${ctx.service}:9000/_spectest/coverage`, {
+        method: "POST", signal: ctx.signal,
+      });
+      if (!response.ok) throw new Error(`edge coverage: ${await response.text()}`);
+      const payload = await response.json() as { reports: { name: string; content: string }[] };
+      if (!payload || !Array.isArray(payload.reports) || !payload.reports.length) throw new Error("edge coverage returned no reports");
+      for (const report of payload.reports) {
+        if (!report || !/^(edge-[\w-]+\.json|edge-scripts\/[a-f0-9]+\.json)$/.test(report.name) || typeof report.content !== "string") {
+          throw new Error("invalid edge coverage report");
+        }
+      }
+      // State and files both fork with the VM. Remove only reports that this
+      // adapter previously shipped, never another adapter's output.
+      await finishAll([...shipped].map(name => fs.rm(path.join(ctx.reportDir, name), { force: true })));
+      shipped.clear();
+      await finishAll(payload.reports.map(async report => {
+        // Track attempted writes too, so a failed write is cleaned up next time.
+        shipped.add(report.name);
+        await ctx.writeReport(report.name, report.content);
+      }));
+    },
+  };
+}
+
+/** Runs in the trusted main worker, not in a sandboxed user function. Keep
+ * this plain JS so the same module is exercised against the pinned runtime. */
+export const SUPABASE_COVERAGE_COLLECTOR = String.raw`
+const INTERNAL = /^(ext:|node:|internal:)/;
+const COMPILED = /^\/var\/tmp\/sb-compile-[^/]+\//;
+const TIMEOUT = 30000;
+// Keep failed captures fenced until every independent operation has settled.
+const finishAll = async pending => {
+  const results = await Promise.allSettled(pending);
+  return results.map(result => {
+    if (result.status === "rejected") throw result.reason;
+    return result.value;
+  });
+};
+const hash = async text => Array.from(new Uint8Array(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(text))), b => b.toString(16).padStart(2, "0")).join("");
+const fileUrl = path => "file://" + path.split("/").map(encodeURIComponent).join("/");
+
+export class EdgeCoverage {
+  constructor({ inspector = "http://127.0.0.1:9229", projectRoot = "/repo", generatedRoot = "/home/deno/spectest-functions" } = {}) {
+    this.inspector = inspector;
+    this.projectRoot = projectRoot.replace(/\/$/, "");
+    this.generatedRoot = generatedRoot;
+    this.entries = new Set();
+    this.wrappers = new Map();
+    this.mirrors = new Map();
+    this.sessions = new Map();
+    this.records = new Set();
+    this.error = null;
+    this.polling = null;
+    this.capturing = false;
+    this.sequence = 0;
+    this.timer = setInterval(() => this.poll().catch(e => this.fail(e)), 100);
+  }
+  fail(error) { this.error ??= String(error?.stack ?? error); }
+  register(entry) { this.entries.add(entry); }
+  wrap(entry) {
+    if (!this.wrappers.has(entry)) this.wrappers.set(entry, this.writeEntry(entry));
+    return this.wrappers.get(entry);
+  }
+  mirrorDirectory(relative) {
+    if (this.mirrors.has(relative)) return this.mirrors.get(relative);
+    const pending = (async () => {
+      const source = this.projectRoot + (relative ? "/" + relative : "");
+      const target = this.generatedRoot + "/project" + (relative ? "/" + relative : "");
+      if (relative) {
+        await this.mirrorDirectory(relative.includes("/") ? relative.slice(0, relative.lastIndexOf("/")) : "");
+        await Deno.remove(target); // replace this directory's link with an overlay
+      }
+      await Deno.mkdir(target, { recursive: true });
+      const items = [];
+      for await (const item of Deno.readDir(source)) items.push(item.name);
+      await finishAll(items.map(name => Deno.symlink(source + "/" + name, target + "/" + name)));
+      return target;
+    })();
+    this.mirrors.set(relative, pending);
+    return pending;
+  }
+  async writeEntry(entry) {
+    const slash = entry.lastIndexOf("/");
+    let directory = entry.slice(0, slash);
+    if (entry.startsWith(this.projectRoot + "/")) {
+      // Keep the complete directory/config layout, including ancestor Deno
+      // workspaces, relative import maps and packages. Only directories along
+      // the entry's ancestry are materialized; everything else is a symlink.
+      directory = await this.mirrorDirectory(directory.slice(this.projectRoot.length + 1));
+    }
+    const wrapper = directory + "/.spectest-coverage-" + (await hash(entry)).slice(0, 16) + ".mjs";
+    const code = [
+      "// spectest-generated coverage gate. Do not edit.",
+      "const keepAlive = setInterval(() => {}, 25);",
+      "const gate = {};",
+      "globalThis[Symbol.for('spectest.edgeCoverage')] = gate;",
+      "await new Promise(resolve => { gate.release = resolve; });",
+      "clearInterval(keepAlive);",
+      "const mod = await import(" + JSON.stringify("./" + entry.slice(slash + 1)) + ");",
+      "export default ('default' in mod ? mod.default : {});",
+    ].join("\n");
+    await Deno.writeTextFile(wrapper, code, { createNew: true });
+    this.register(wrapper);
+    return fileUrl(wrapper);
+  }
+  async forgetUnstarted(entry) {
+    // Compilation can reject the shared graph before an isolate exists. That
+    // is a normal reason for the component to retry in per-function mode.
+    const wrapper = await this.wrappers.get(entry);
+    if (!wrapper) return;
+    const original = decodeURIComponent(new URL(wrapper).pathname);
+    if (![...this.sessions.values()].some(s => s.entry === original)) this.entries.delete(original);
+  }
+  async ready() {
+    const deadline = Date.now() + TIMEOUT;
+    while (true) {
+      await this.poll();
+      if (this.error) throw new Error(this.error);
+      const attached = new Set([...this.sessions.values()].map(s => s.entry));
+      if ([...this.entries].every(entry => attached.has(entry))) {
+        await Promise.all([...this.sessions.values()].map(s => s.ready));
+        return;
+      }
+      if (Date.now() >= deadline) throw new Error("edge coverage did not attach to every warmed worker");
+      await new Promise(resolve => setTimeout(resolve, 25));
+    }
+  }
+  async poll() {
+    if (this.polling) return this.polling;
+    this.polling = this.discover();
+    try { await this.polling; } finally { this.polling = null; }
+  }
+  async discover() {
+    const response = await fetch(this.inspector + "/json/list", { signal: AbortSignal.timeout(TIMEOUT) });
+    if (!response.ok) throw new Error("edge inspector discovery failed: " + response.status);
+    const targets = await response.json();
+    if (!Array.isArray(targets)) throw new Error("invalid edge inspector target list");
+    const live = new Set(targets.map(t => t.id));
+    for (const [id] of this.sessions) if (!live.has(id)) throw new Error("edge coverage lost worker " + id);
+    for (const target of targets) {
+      if (this.sessions.has(target.id)) continue;
+      const session = this.connect(target);
+      this.sessions.set(target.id, session);
+      // Discover all isolates while their sessions initialize. ready() joins
+      // initialization separately; one worker never blocks discovery of others.
+      session.ready.catch(e => this.fail(e));
+    }
+  }
+  connect(target) {
+    const url = new URL(target.url);
+    if (url.protocol !== "file:") throw new Error("unexpected edge worker entry: " + target.url);
+    const compiledPath = decodeURIComponent(url.pathname);
+    const relative = compiledPath.replace(COMPILED, "");
+    // The runtime relocates the entire module graph under sb-compile-*/.
+    // Its registered entrypoint and our exact original entrypoint establish
+    // the relocation, independently for every isolate. Never guess a source
+    // file by basename or by a repository suffix.
+    const candidates = [...this.entries].filter(entry => compiledPath === entry || entry.endsWith("/" + relative));
+    if (candidates.length !== 1) throw new Error("ambiguous edge worker entry: " + target.url);
+    const original = candidates[0];
+    const base = COMPILED.test(compiledPath) ? original.slice(0, -relative.length) : "/";
+    const prefix = COMPILED.exec(compiledPath)?.[0] ?? "/";
+    const socketUrl = new URL(target.webSocketDebuggerUrl);
+    const inspector = new URL(this.inspector);
+    socketUrl.host = inspector.host;
+    const ws = new WebSocket(socketUrl);
+    const session = { ws, base, prefix, entry: original, scripts: new Map(), descriptions: new Map(), nextId: 0, pending: new Map() };
+    session.post = (method, params = {}) => new Promise((resolve, reject) => {
+      const id = ++session.nextId;
+      const timer = setTimeout(() => { session.pending.delete(id); reject(new Error("edge inspector timeout: " + method)); }, TIMEOUT);
+      session.pending.set(id, { resolve, reject, timer });
+      ws.send(JSON.stringify({ id, method, params }));
+    });
+    ws.onmessage = event => {
+      try {
+        const message = JSON.parse(event.data);
+        if (message.id) {
+          const pending = session.pending.get(message.id);
+          if (!pending) return;
+          clearTimeout(pending.timer);
+          session.pending.delete(message.id);
+          if (message.error) pending.reject(new Error(JSON.stringify(message.error)));
+          else pending.resolve(message.result);
+        } else if (message.method === "Debugger.scriptParsed") {
+          session.scripts.set(message.params.scriptId, message.params);
+        } else if (message.method === "Debugger.paused") {
+          session.post("Debugger.resume").catch(e => this.fail(e));
+        }
+      } catch (e) { this.fail(e); }
+    };
+    ws.onclose = () => {
+      const error = new Error("edge coverage inspector disconnected: " + target.id);
+      for (const p of session.pending.values()) { clearTimeout(p.timer); p.reject(error); }
+      session.pending.clear();
+      this.fail(error);
+    };
+    session.ready = (async () => {
+      await new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error("edge inspector connection timeout")), TIMEOUT);
+        ws.onopen = () => { clearTimeout(timer); resolve(); };
+        ws.onerror = () => { clearTimeout(timer); reject(new Error("edge inspector connection failed")); };
+      });
+      await session.post("Debugger.enable", { maxScriptsCacheSize: 16 * 1024 * 1024 });
+      await session.post("Profiler.enable");
+      await session.post("Profiler.startPreciseCoverage", { callCount: true, detailed: true });
+      // --inspect-brk can park inside the pinned runtime's inspector before
+      // its pending session handshake is polled. Use a live JS gate instead:
+      // no project module executes until precise coverage is acknowledged.
+      const released = await session.post("Runtime.evaluate", {
+        expression: "(async () => { const key = Symbol.for('spectest.edgeCoverage'); while (!globalThis[key]?.release) await new Promise(resolve => setTimeout(resolve, 10)); globalThis[key].release(); await new Promise(resolve => setTimeout(resolve, 0)); })()\n//# sourceURL=spectest:edge-coverage-bootstrap",
+        awaitPromise: true,
+      });
+      if (released.exceptionDetails) throw new Error("edge coverage gate failed: " + JSON.stringify(released.exceptionDetails));
+    })();
+    return session;
+  }
+  originalPath(session, url) {
+    const parsed = new URL(url);
+    if (parsed.protocol !== "file:") return null;
+    const pathname = decodeURIComponent(parsed.pathname);
+    if (!pathname.startsWith(session.prefix)) throw new Error("unknown edge source root: " + url);
+    return session.base + pathname.slice(session.prefix.length);
+  }
+  sourcePath(file) {
+    const mirror = this.generatedRoot + "/project/";
+    return file.startsWith(mirror) ? this.projectRoot + "/" + file.slice(mirror.length) : file;
+  }
+  async describe(session, script, original) {
+    if (session.descriptions.has(script.scriptId)) return session.descriptions.get(script.scriptId);
+    const { scriptSource: text } = await session.post("Debugger.getScriptSource", { scriptId: script.scriptId });
+    if (typeof text !== "string") throw new Error("missing edge source: " + script.url);
+    const metadata = session.scripts.get(script.scriptId);
+    const mapUrl = metadata?.sourceMapURL;
+    let sourceMap = null;
+    if (mapUrl) {
+      if (!mapUrl.startsWith("data:")) throw new Error("unsupported edge source map: " + mapUrl);
+      const comma = mapUrl.indexOf(",");
+      const encoded = mapUrl.slice(comma + 1);
+      const decoded = mapUrl.slice(0, comma).endsWith(";base64")
+        ? new TextDecoder().decode(Uint8Array.from(atob(encoded), c => c.charCodeAt(0))) : decodeURIComponent(encoded);
+      const data = JSON.parse(decoded);
+      if (!Array.isArray(data.sources) || !Array.isArray(data.sourcesContent) || typeof data.mappings !== "string" || data.sections || data.sourceRoot) {
+        throw new Error("missing edge source-map identity: " + script.url);
+      }
+      // Edge Runtime's map sources are relative to the graph root, rather
+      // than the script directory. Validate their contents against the actual
+      // mounted sources before archiving the normalized identities.
+      data.sources = await finishAll(data.sources.map(async (name, i) => {
+        const source = new URL(name, fileUrl(session.base));
+        if (source.protocol !== "file:") throw new Error("unexpected mapped edge source: " + source.href);
+        const file = this.sourcePath(decodeURIComponent(source.pathname));
+        if (!file.startsWith(this.projectRoot + "/")) throw new Error("edge map escapes project: " + file);
+        if (await Deno.readTextFile(file) !== data.sourcesContent[i]) throw new Error("edge source content mismatch: " + file);
+        return fileUrl(file);
+      }));
+      delete data.sourcesContent;
+      delete data.sourceRoot;
+      sourceMap = { url: null, data };
+    } else {
+      // JavaScript may need no transpilation. TypeScript without a map must
+      // not silently attribute generated line numbers to authored source.
+      if (await Deno.readTextFile(original) !== text) throw new Error("edge source has no usable map: " + original);
+    }
+    const record = { url: fileUrl(original), sourceHash: await hash(text),
+      lineLengths: text.split(/[\n\u2028\u2029]/).map(line => line.length),
+      functions: script.functions.map(f => [f.functionName, f.ranges[0].startOffset, f.ranges[0].endOffset]), sourceMap };
+    const content = JSON.stringify({ spectestScript: record });
+    const descriptor = { id: await hash(content), content };
+    session.descriptions.set(script.scriptId, descriptor);
+    return descriptor;
+  }
+  async capture() {
+    if (this.capturing) throw new Error("edge coverage capture already in progress");
+    this.capturing = true;
+    try {
+      await this.ready();
+      if (this.error) throw new Error(this.error);
+      // Each isolate owns its counters. Take all deltas concurrently, and
+      // fetch independent script descriptors concurrently within each isolate.
+      // Join before merging so ordering/deduplication don't depend on timing.
+      const captures = await finishAll([...this.sessions.values()].map(async session => {
+        const dump = await session.post("Profiler.takePreciseCoverage");
+        return finishAll(dump.result.map(async script => {
+          if (!script.functions.some(f => f.ranges.some(r => r.count > 0))) return null;
+          if (INTERNAL.test(script.url)) return null;
+          if (script.url === "spectest:edge-coverage-bootstrap") return null;
+          if (/^(https?:|npm:|jsr:)/.test(script.url)) return { unit: "deno:" + script.url };
+          if (!script.url) throw new Error("anonymous executed edge script cannot be mapped");
+          const rawPath = this.originalPath(session, script.url);
+          if (rawPath === session.entry) return null; // the generated startup gate
+          const original = rawPath && this.sourcePath(rawPath);
+          if (original?.startsWith(this.generatedRoot + "/")) return null;
+          if (original?.includes("/node_modules/")) return { unit: "deno:" + script.url };
+          if (!original?.startsWith(this.projectRoot + "/")) throw new Error("unmapped edge script: " + script.url);
+          const descriptor = await this.describe(session, script, original);
+          return { descriptor, result: { url: fileUrl(original), spectestScript: descriptor.id,
+            functions: script.functions.filter(f => f.ranges.some(r => r.count > 0)).map(f => {
+              const start = f.ranges[0].startOffset;
+              return f.ranges.flatMap((r, i) => [i ? r.startOffset - start : start, r.endOffset - r.startOffset, r.count]);
+            }) } };
+        }));
+      }));
+      const reports = [], result = [], units = new Set();
+      for (const capture of captures) for (const item of capture) {
+        if (!item) continue;
+        if (item.unit) { units.add(item.unit); continue; }
+        const { descriptor } = item;
+        if (!this.records.has(descriptor.id)) {
+          reports.push({ name: "edge-scripts/" + descriptor.id + ".json", content: descriptor.content });
+          this.records.add(descriptor.id);
+        }
+        result.push(item.result);
+      }
+      if (this.error) throw new Error(this.error);
+      reports.push({ name: "edge-" + (++this.sequence) + ".json", content: JSON.stringify({ spectestVersion: 2, result, units: [...units] }) });
+      return { reports };
+    } catch (e) {
+      // A take resets V8 counters. If processing fails afterwards, subsequent
+      // captures cannot repair that gap. Keep the failure sticky on this fork.
+      this.fail(e);
+      throw e;
+    } finally { this.capturing = false; }
+  }
+}
+`;