@specific.dev/spectest 0.79.1 → 0.80.0

package/dist/coverage.d.ts

@@ -8,22 +8,11 @@ export declare const NODE_COVERAGE_EMPTY_REPORT = "coverage-spectest-empty.json"
 /** Prefix of the per-process sockets the node hook answers on, relative
  *  to the coverage dir: `.ctl-<pid>`. */
 export declare const NODE_COVERAGE_SOCKET_PREFIX = ".ctl-";
-/** Where golden keeps the conversion tools (`c8` and its dependencies),
- *  seen from the VM. `SPECTEST_COVERAGE_TOOLS_DIR` overrides it (tests).
- *  The daemon bind-mounts it read-only into every covered container at
- *  {@link NODE_COVERAGE_TOOLS_CONTAINER_DIR} when it exists. */
-export declare const NODE_COVERAGE_TOOLS_DIR = "/opt/spectest/coverage-tools";
-/** Where the container sees {@link NODE_COVERAGE_TOOLS_DIR}. */
-export declare const NODE_COVERAGE_TOOLS_CONTAINER_DIR = "/spectest/coverage-tools";
-/** The `c8` entry point, relative to the tools dir. */
-export declare const NODE_COVERAGE_C8_BIN = "node_modules/c8/bin/c8.js";
-/** The hidden subdirectory of the coverage dir where `node()` parks the
- *  V8 dumps it converts at one capture. Hidden, so the harness never
- *  ships them: the lcov is the report. Emptied at every capture — the
- *  lcov is this capture's delta, see {@link convertV8ReportsToLcov}. */
-export declare const NODE_COVERAGE_DUMPS_SUBDIR = ".v8";
-/** The lcov `node()` writes: the dumps of this capture, merged. */
-export declare const NODE_COVERAGE_LCOV = "node.lcov";
+/** Key of the content hash (`sha256:<hex>`) a shipped `source-map-cache`
+ *  entry carries, and key of the stub that stands in for an entry that
+ *  shipped earlier on the same branch. See {@link compactV8Document}. */
+export declare const SOURCE_MAP_HASH_KEY = "spectestHash";
+export declare const SOURCE_MAP_REF_KEY = "spectestRef";
 /** What `configure` learns about the service it rewrites. */
 export interface CoverageConfigureInfo {
     /** The services-map key. */
@@ -146,50 +135,19 @@ export declare const NODE_COVERAGE_HOOK: string;
  * capture time — the server, and any wrapper it sits behind (`pnpm exec`,
  * `tsx`). Nothing for the app to write.
  *
- * At capture the dumps are **converted to lcov inside the container**
- * with `c8` (`c8 report`), and `node.lcov` is the one report that
- * ships. It holds **what ran since the previous capture**: V8 resets its
- * counters at every `takeCoverage()`, so a live server's dump after a
- * test is that test's own execution — the boot dump (everything loaded,
- * which at file level is everything "ran") lands in the bring-up
- * capture and nowhere else. A run's total is the union over its cases
- * on the server; a test's set is the test's own. Merging every dump on
- * the branch instead was tried first and would have made a long-lived
- * server's per-test set the boot set, every time. The conversion runs
- * in the container, not in the harness, because `v8-to-istanbul` needs
- * the script text (for byte offsets → lines) and the source maps
- * (`--enable-source-maps`, or a `sourceMappingURL` next to each file),
- * and only the container has them. `c8` comes from golden
- * ({@link NODE_COVERAGE_TOOLS_DIR}); on a guest without it the raw V8
- * documents ship instead, compacted ({@link compactV8Document}), as they
- * did before SDK 0.60.
+ * What ships is the V8 documents themselves, compacted
+ * ({@link compactV8Document}): the app's own scripts that ran, and each
+ * script's source map once per branch. Nothing is converted in the VM.
+ * A dump is a **delta** by construction: V8 resets its counters at every
+ * `takeCoverage()`, so a live server's dump after a test is that test's
+ * own execution, and the boot dump (everything loaded) lands in the
+ * bring-up capture and nowhere else. The control plane derives lines
+ * from the stored documents, off the test run. Converting to lcov in
+ * the container (`c8`, SDK 0.60 to 0.79) took seconds per capture per
+ * service on a real project, inside the test run; a real project turned
+ * coverage off because of it, and the conversion went.
  */
 export declare function node(): CoverageAdapter;
-/** The VM-side tools dir, after the test override. */
-export declare function nodeCoverageToolsDir(): string;
-/** True when golden (or the override) ships `c8`. The daemon mounts the
- *  directory into covered containers on the same check, so what the VM
- *  has is what the container sees. */
-export declare function nodeCoverageToolsAvailable(): Promise<boolean>;
-/** The command `convertV8ReportsToLcov` runs in the container. From `/`,
- *  so lcov paths come out relative to the root (made absolute after). */
-export declare function nodeCoverageConvertCommand(): string;
-/**
- * Convert the V8 dumps written since the previous capture to one lcov,
- * `node.lcov`. New dumps at the root of the dir are compacted to the
- * app's scripts (their maps and `sourcesContent` kept — `v8-to-istanbul`
- * reads the original sources from there when they are not on disk, the
- * usual shape of a multi-stage image) and moved into `.v8/`, which is
- * emptied first; `c8 report` merges that directory. So the lcov is this
- * capture's delta: what the live processes ran since their last take,
- * plus every process that exited since. No new dump ⇒ `TN:` alone,
- * nothing ran. The `SF:` paths come out relative to `/` and are made
- * absolute, so they read as container paths like every other tool's.
- */
-export declare function convertV8ReportsToLcov(ctx: CoverageCaptureContext): Promise<void>;
-/** `SF:` records relative to `/` (what `c8` run from `/` writes) made
- *  absolute. An lcov with nothing in it becomes the empty report. */
-export declare function absoluteLcovPaths(lcov: string): string;
 /**
  * Ask every node process that holds a hook socket in `dir` for a dump.
  * A socket nobody answers (its process died without unlinking — SIGKILL,
@@ -197,27 +155,59 @@ export declare function absoluteLcovPaths(lcov: string): string;
  * answered with an error throws.
  */
 export declare function dumpAllNodeProcesses(dir: string, signal: AbortSignal): Promise<number>;
+/** Forget the branch memory (tests). */
+export declare function resetNodeCoverageMemory(): void;
+/** Remove from `dir` the reports an earlier capture shipped. */
+export declare function removeShippedV8Reports(dir: string): Promise<void>;
 /** A script is the app's own when it is a file outside node_modules —
  *  and not our hook, which every dump would otherwise carry. */
 export declare function isAppScriptUrl(url: string): boolean;
+interface V8Range {
+    count?: unknown;
+}
+interface V8Function {
+    ranges?: V8Range[];
+}
+interface V8Script {
+    url?: unknown;
+    functions?: V8Function[];
+}
+/** True when any range of any function of the script has a count above
+ *  zero: something in it ran since the previous take. A script whose
+ *  every count is zero is one V8 still lists after a reset; it says
+ *  nothing and is dropped. */
+export declare function scriptExecuted(script: V8Script): boolean;
 /**
- * Compact one V8 coverage document to the app's own scripts. What Node
- * writes is everything the process loaded: `node:` internals, every
+ * Compact one V8 coverage document to what the derivation needs. What
+ * Node writes is everything the process loaded: `node:` internals, every
  * `node_modules` file, and — under `--enable-source-maps` — a
  * `source-map-cache` with each file's full map **and its sources**,
  * repeated in every dump. Measured on a real project: a 12–20 MiB dump
  * per capture, of which the app's own coverage was under 0.5 MiB, and a
  * suite that hit the 64 MiB cap on its third test. Kept: `file://`
- * scripts outside `node_modules`, the map entries of exactly those
- * scripts, minus `sourcesContent` (the sources are the repo) unless
- * `keepSourcesContent` — the lcov conversion reads original sources from
- * there. Still a V8 document — nothing is converted here.
+ * scripts outside `node_modules` in which something ran, and the map
+ * entries of exactly those scripts, minus `sourcesContent` (the sources
+ * are the repo). Each kept map entry carries its content hash under
+ * {@link SOURCE_MAP_HASH_KEY}; when `shipped` holds the same hash for the
+ * URL — the map went out with an earlier dump on this branch — a stub
+ * `{ [SOURCE_MAP_REF_KEY]: hash }` stands in for it, and the reader finds
+ * the map in an earlier capture of the branch. `shipped` is updated in
+ * place. Still a V8 document — nothing is converted here.
+ */
+export declare function compactV8Document(doc: Record<string, unknown>, shipped?: Map<string, string>): Record<string, unknown>;
+/** What {@link prepareV8Reports} did, for the capture's log line. */
+export interface PrepareV8Stats {
+    dumps: number;
+    scripts: number;
+    bytesIn: number;
+    bytesOut: number;
+}
+/**
+ * Compact, in place, every `coverage-*.json` in `dir` that no earlier
+ * capture shipped, and mark it shipped. A dump mid-write (not yet valid
+ * JSON) is left for the next capture.
  */
-export declare function compactV8Document(doc: Record<string, unknown>, opts?: {
-    keepSourcesContent?: boolean;
-}): Record<string, unknown>;
-/** Compact every not-yet-compacted V8 document in `dir`, in place. */
-export declare function compactV8Reports(dir: string): Promise<void>;
+export declare function prepareV8Reports(dir: string): Promise<PrepareV8Stats>;
 /**
  * Coverage for the frontend a service serves. The code runs in the guest
  * browser — spectest's own process — so no report can be written by the

package/dist/coverage.js

@@ -14,11 +14,10 @@
 //
 // After every adapter ran, the harness reads the directory the same way
 // it does for `coverage: true`: at least one well-formed report (lcov or
-// V8 JSON), shipped verbatim. The control plane derives what it needs
-// from the stored bytes. One adapter converts: `node()` turns the V8
-// dumps into lcov inside the container (with `c8`, which golden ships),
-// because the conversion needs the sources and the source maps, which
-// only the container has.
+// V8 JSON), shipped verbatim. Nothing is converted in the VM: `node()`
+// compacts its V8 dumps (the app's own scripts, each source map once per
+// branch) and ships them as they are. The control plane derives what it
+// needs from the stored bytes, off the test run.
 //
 // Imported from `@specific.dev/spectest/coverage`. The three shipped
 // adapters: `node()` (V8 JSON through a hook spectest mounts), `browser()`
@@ -27,6 +26,7 @@
 //
 //   import * as coverage from "@specific.dev/spectest/coverage";
 //   coverage: { adapters: [coverage.node(), coverage.browser()] }
+import { createHash } from "node:crypto";
 import { harvestAllBrowserCoverage, takeBrowserCoverageReports } from "./browser-coverage.js";
 import { COVERAGE_CONTAINER_DIR } from "./harness/coverage.js";
 export { COVERAGE_CONTAINER_DIR };
@@ -37,22 +37,11 @@ export const NODE_COVERAGE_EMPTY_REPORT = "coverage-spectest-empty.json";
 /** Prefix of the per-process sockets the node hook answers on, relative
  *  to the coverage dir: `.ctl-<pid>`. */
 export const NODE_COVERAGE_SOCKET_PREFIX = ".ctl-";
-/** Where golden keeps the conversion tools (`c8` and its dependencies),
- *  seen from the VM. `SPECTEST_COVERAGE_TOOLS_DIR` overrides it (tests).
- *  The daemon bind-mounts it read-only into every covered container at
- *  {@link NODE_COVERAGE_TOOLS_CONTAINER_DIR} when it exists. */
-export const NODE_COVERAGE_TOOLS_DIR = "/opt/spectest/coverage-tools";
-/** Where the container sees {@link NODE_COVERAGE_TOOLS_DIR}. */
-export const NODE_COVERAGE_TOOLS_CONTAINER_DIR = "/spectest/coverage-tools";
-/** The `c8` entry point, relative to the tools dir. */
-export const NODE_COVERAGE_C8_BIN = "node_modules/c8/bin/c8.js";
-/** The hidden subdirectory of the coverage dir where `node()` parks the
- *  V8 dumps it converts at one capture. Hidden, so the harness never
- *  ships them: the lcov is the report. Emptied at every capture — the
- *  lcov is this capture's delta, see {@link convertV8ReportsToLcov}. */
-export const NODE_COVERAGE_DUMPS_SUBDIR = ".v8";
-/** The lcov `node()` writes: the dumps of this capture, merged. */
-export const NODE_COVERAGE_LCOV = "node.lcov";
+/** Key of the content hash (`sha256:<hex>`) a shipped `source-map-cache`
+ *  entry carries, and key of the stub that stands in for an entry that
+ *  shipped earlier on the same branch. See {@link compactV8Document}. */
+export const SOURCE_MAP_HASH_KEY = "spectestHash";
+export const SOURCE_MAP_REF_KEY = "spectestRef";
 /** The `reports` mode of a `coverage` value, for the reports no adapter
  *  wrote (the program's own, a `command`'s). */
 export function coverageReportsMode(cov) {
@@ -193,23 +182,17 @@ if (process.env.NODE_V8_COVERAGE && require("node:worker_threads").isMainThread)
  * capture time — the server, and any wrapper it sits behind (`pnpm exec`,
  * `tsx`). Nothing for the app to write.
  *
- * At capture the dumps are **converted to lcov inside the container**
- * with `c8` (`c8 report`), and `node.lcov` is the one report that
- * ships. It holds **what ran since the previous capture**: V8 resets its
- * counters at every `takeCoverage()`, so a live server's dump after a
- * test is that test's own execution — the boot dump (everything loaded,
- * which at file level is everything "ran") lands in the bring-up
- * capture and nowhere else. A run's total is the union over its cases
- * on the server; a test's set is the test's own. Merging every dump on
- * the branch instead was tried first and would have made a long-lived
- * server's per-test set the boot set, every time. The conversion runs
- * in the container, not in the harness, because `v8-to-istanbul` needs
- * the script text (for byte offsets → lines) and the source maps
- * (`--enable-source-maps`, or a `sourceMappingURL` next to each file),
- * and only the container has them. `c8` comes from golden
- * ({@link NODE_COVERAGE_TOOLS_DIR}); on a guest without it the raw V8
- * documents ship instead, compacted ({@link compactV8Document}), as they
- * did before SDK 0.60.
+ * What ships is the V8 documents themselves, compacted
+ * ({@link compactV8Document}): the app's own scripts that ran, and each
+ * script's source map once per branch. Nothing is converted in the VM.
+ * A dump is a **delta** by construction: V8 resets its counters at every
+ * `takeCoverage()`, so a live server's dump after a test is that test's
+ * own execution, and the boot dump (everything loaded) lands in the
+ * bring-up capture and nowhere else. The control plane derives lines
+ * from the stored documents, off the test run. Converting to lcov in
+ * the container (`c8`, SDK 0.60 to 0.79) took seconds per capture per
+ * service on a real project, inside the test run; a real project turned
+ * coverage off because of it, and the conversion went.
  */
 export function node() {
     return {
@@ -234,114 +217,25 @@ export function node() {
             // rather than failed: an empty report is a report. A server whose
             // hook never loaded (NODE_OPTIONS not reaching it) then shows as
             // empty reports after bring-up, which the boot log warns about.
-            await dumpAllNodeProcesses(ctx.reportDir, ctx.signal);
-            if (await nodeCoverageToolsAvailable()) {
-                await convertV8ReportsToLcov(ctx);
-                return;
-            }
-            await compactV8Reports(ctx.reportDir);
-            if (!(await hasV8Reports(ctx.reportDir))) {
+            //
+            // Each capture ships only its own dumps: what an earlier capture on
+            // this branch shipped is removed first (module memory, forks with
+            // the environment).
+            const t0 = performance.now();
+            await removeShippedV8Reports(ctx.reportDir);
+            const live = await dumpAllNodeProcesses(ctx.reportDir, ctx.signal);
+            const t1 = performance.now();
+            const stats = await prepareV8Reports(ctx.reportDir);
+            if (stats.dumps === 0) {
                 await ctx.writeReport(NODE_COVERAGE_EMPTY_REPORT, '{"result":[]}\n');
+                SHIPPED_V8_REPORTS.add((await import("node:path")).join(ctx.reportDir, NODE_COVERAGE_EMPTY_REPORT));
             }
+            const t2 = performance.now();
+            console.log(`[coverage] node/${ctx.service}: ${live} live process(es) dumped in ${Math.round(t1 - t0)} ms; ` +
+                `${stats.dumps} dump(s), ${stats.scripts} script(s), ${stats.bytesIn} → ${stats.bytesOut} bytes compacted in ${Math.round(t2 - t1)} ms`);
         },
     };
 }
-/** The VM-side tools dir, after the test override. */
-export function nodeCoverageToolsDir() {
-    return process.env.SPECTEST_COVERAGE_TOOLS_DIR || NODE_COVERAGE_TOOLS_DIR;
-}
-/** True when golden (or the override) ships `c8`. The daemon mounts the
- *  directory into covered containers on the same check, so what the VM
- *  has is what the container sees. */
-export async function nodeCoverageToolsAvailable() {
-    const fs = await import("node:fs/promises");
-    const path = await import("node:path");
-    try {
-        await fs.access(path.join(nodeCoverageToolsDir(), NODE_COVERAGE_C8_BIN));
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-/** The command `convertV8ReportsToLcov` runs in the container. From `/`,
- *  so lcov paths come out relative to the root (made absolute after). */
-export function nodeCoverageConvertCommand() {
-    const c8 = `${NODE_COVERAGE_TOOLS_CONTAINER_DIR}/${NODE_COVERAGE_C8_BIN}`;
-    const dumps = `${COVERAGE_CONTAINER_DIR}/${NODE_COVERAGE_DUMPS_SUBDIR}`;
-    const out = `${COVERAGE_CONTAINER_DIR}/.c8`;
-    // `env -u`: the converter is a node process in a container whose env
-    // carries NODE_V8_COVERAGE and the `--require` hook, so without this it
-    // would load the hook and write a dump of itself at exit — a raw V8
-    // document at the root of the dir, shipped as a report (seen on the
-    // first run of hello-node under 0.60).
-    return `cd / && env -u NODE_V8_COVERAGE -u NODE_OPTIONS node ${c8} report --temp-directory ${dumps} --reporter=lcovonly --reports-dir ${out}`;
-}
-/**
- * Convert the V8 dumps written since the previous capture to one lcov,
- * `node.lcov`. New dumps at the root of the dir are compacted to the
- * app's scripts (their maps and `sourcesContent` kept — `v8-to-istanbul`
- * reads the original sources from there when they are not on disk, the
- * usual shape of a multi-stage image) and moved into `.v8/`, which is
- * emptied first; `c8 report` merges that directory. So the lcov is this
- * capture's delta: what the live processes ran since their last take,
- * plus every process that exited since. No new dump ⇒ `TN:` alone,
- * nothing ran. The `SF:` paths come out relative to `/` and are made
- * absolute, so they read as container paths like every other tool's.
- */
-export async function convertV8ReportsToLcov(ctx) {
-    const fs = await import("node:fs/promises");
-    const path = await import("node:path");
-    const dumpsDir = path.join(ctx.reportDir, NODE_COVERAGE_DUMPS_SUBDIR);
-    await fs.rm(dumpsDir, { recursive: true, force: true });
-    await fs.mkdir(dumpsDir, { recursive: true });
-    await fs.chmod(dumpsDir, 0o755);
-    let dumps = 0;
-    for (const name of await fs.readdir(ctx.reportDir)) {
-        if (!name.startsWith("coverage-") || !name.endsWith(".json"))
-            continue;
-        const file = path.join(ctx.reportDir, name);
-        if (name === NODE_COVERAGE_EMPTY_REPORT) {
-            await fs.unlink(file).catch(() => { }); // a pre-0.60 placeholder
-            continue;
-        }
-        let doc;
-        try {
-            doc = JSON.parse(await fs.readFile(file, "utf8"));
-        }
-        catch {
-            continue; // a dump mid-write; the next capture takes it
-        }
-        if (!Array.isArray(doc.result))
-            continue;
-        const target = path.join(dumpsDir, name);
-        await fs.writeFile(`${target}.tmp`, JSON.stringify(compactV8Document(doc, { keepSourcesContent: true })));
-        await fs.chmod(`${target}.tmp`, 0o644);
-        await fs.rename(`${target}.tmp`, target);
-        await fs.unlink(file);
-        dumps++;
-    }
-    if (dumps === 0) {
-        await ctx.writeReport(NODE_COVERAGE_LCOV, "TN:\n");
-        return;
-    }
-    await ctx.exec(nodeCoverageConvertCommand());
-    let lcov;
-    try {
-        lcov = await fs.readFile(path.join(ctx.reportDir, ".c8", "lcov.info"), "utf8");
-    }
-    catch (err) {
-        throw new Error(`c8 wrote no lcov.info: ${err instanceof Error ? err.message : String(err)}`);
-    }
-    await ctx.writeReport(NODE_COVERAGE_LCOV, absoluteLcovPaths(lcov));
-}
-/** `SF:` records relative to `/` (what `c8` run from `/` writes) made
- *  absolute. An lcov with nothing in it becomes the empty report. */
-export function absoluteLcovPaths(lcov) {
-    if (lcov.trim().length === 0)
-        return "TN:\n";
-    return lcov.replace(/^SF:(?!\/)/gm, "SF:/");
-}
 /**
  * Ask every node process that holds a hook socket in `dir` for a dump.
  * A socket nobody answers (its process died without unlinking — SIGKILL,
@@ -396,20 +290,31 @@ export async function dumpAllNodeProcesses(dir, signal) {
     }
     return live;
 }
-/** True when `dir` holds at least one `coverage-*.json` other than the
- *  empty placeholder. */
-async function hasV8Reports(dir) {
+/** Report files shipped at an earlier capture on this branch, by host
+ *  path. Module memory: forks with the environment, so a forked child
+ *  removes its ancestors' reports at its first capture and ships only
+ *  its own. */
+const SHIPPED_V8_REPORTS = new Set();
+/** Source-map entries shipped earlier on this branch: script URL → hash
+ *  of the entry. Module memory, forks with the environment. A later dump
+ *  of the same script carries a stub that refers to the hash instead of
+ *  the map again. */
+const SHIPPED_SOURCE_MAPS = new Map();
+/** Forget the branch memory (tests). */
+export function resetNodeCoverageMemory() {
+    SHIPPED_V8_REPORTS.clear();
+    SHIPPED_SOURCE_MAPS.clear();
+}
+/** Remove from `dir` the reports an earlier capture shipped. */
+export async function removeShippedV8Reports(dir) {
     const fs = await import("node:fs/promises");
-    try {
-        return (await fs.readdir(dir)).some((n) => n.startsWith("coverage-") && n.endsWith(".json") && n !== NODE_COVERAGE_EMPTY_REPORT);
-    }
-    catch {
-        return false;
+    for (const file of [...SHIPPED_V8_REPORTS]) {
+        if (!file.startsWith(dir + "/"))
+            continue;
+        await fs.unlink(file).catch(() => { });
+        SHIPPED_V8_REPORTS.delete(file);
     }
 }
-/** V8 files already compacted, by path. Module memory: forks with the
- *  environment, so a child never re-parses its ancestors' dumps. */
-const COMPACTED_V8_REPORTS = new Set();
 /** A script is the app's own when it is a file outside node_modules —
  *  and not our hook, which every dump would otherwise carry. */
 export function isAppScriptUrl(url) {
@@ -420,22 +325,34 @@ export function isAppScriptUrl(url) {
         !url.includes("/.cache/") &&
         !url.endsWith("/" + NODE_COVERAGE_HOOK_PATH.split("/").pop()));
 }
+/** True when any range of any function of the script has a count above
+ *  zero: something in it ran since the previous take. A script whose
+ *  every count is zero is one V8 still lists after a reset; it says
+ *  nothing and is dropped. */
+export function scriptExecuted(script) {
+    const fns = Array.isArray(script.functions) ? script.functions : [];
+    return fns.some((f) => Array.isArray(f.ranges) && f.ranges.some((r) => typeof r.count === "number" && r.count > 0));
+}
 /**
- * Compact one V8 coverage document to the app's own scripts. What Node
- * writes is everything the process loaded: `node:` internals, every
+ * Compact one V8 coverage document to what the derivation needs. What
+ * Node writes is everything the process loaded: `node:` internals, every
  * `node_modules` file, and — under `--enable-source-maps` — a
  * `source-map-cache` with each file's full map **and its sources**,
  * repeated in every dump. Measured on a real project: a 12–20 MiB dump
  * per capture, of which the app's own coverage was under 0.5 MiB, and a
  * suite that hit the 64 MiB cap on its third test. Kept: `file://`
- * scripts outside `node_modules`, the map entries of exactly those
- * scripts, minus `sourcesContent` (the sources are the repo) unless
- * `keepSourcesContent` — the lcov conversion reads original sources from
- * there. Still a V8 document — nothing is converted here.
+ * scripts outside `node_modules` in which something ran, and the map
+ * entries of exactly those scripts, minus `sourcesContent` (the sources
+ * are the repo). Each kept map entry carries its content hash under
+ * {@link SOURCE_MAP_HASH_KEY}; when `shipped` holds the same hash for the
+ * URL — the map went out with an earlier dump on this branch — a stub
+ * `{ [SOURCE_MAP_REF_KEY]: hash }` stands in for it, and the reader finds
+ * the map in an earlier capture of the branch. `shipped` is updated in
+ * place. Still a V8 document — nothing is converted here.
  */
-export function compactV8Document(doc, opts = {}) {
+export function compactV8Document(doc, shipped) {
     const result = Array.isArray(doc.result) ? doc.result : [];
-    const kept = result.filter((s) => typeof s.url === "string" && isAppScriptUrl(s.url));
+    const kept = result.filter((s) => typeof s.url === "string" && isAppScriptUrl(s.url) && scriptExecuted(s));
     const out = { ...doc, result: kept };
     const cache = doc["source-map-cache"];
     if (cache && typeof cache === "object") {
@@ -445,11 +362,20 @@ export function compactV8Document(doc, opts = {}) {
             if (!urls.has(url) || !entry || typeof entry !== "object")
                 continue;
             const e = { ...entry };
-            if (!opts.keepSourcesContent && e.data && typeof e.data === "object") {
+            if (e.data && typeof e.data === "object") {
                 const { sourcesContent: _dropped, ...data } = e.data;
                 e.data = data;
             }
-            slim[url] = e;
+            delete e[SOURCE_MAP_HASH_KEY];
+            delete e[SOURCE_MAP_REF_KEY];
+            const hash = "sha256:" + createHash("sha256").update(JSON.stringify(e)).digest("hex");
+            if (shipped?.get(url) === hash) {
+                slim[url] = { [SOURCE_MAP_REF_KEY]: hash };
+            }
+            else {
+                slim[url] = { ...e, [SOURCE_MAP_HASH_KEY]: hash };
+                shipped?.set(url, hash);
+            }
         }
         if (Object.keys(slim).length > 0)
             out["source-map-cache"] = slim;
@@ -458,37 +384,50 @@ export function compactV8Document(doc, opts = {}) {
     }
     return out;
 }
-/** Compact every not-yet-compacted V8 document in `dir`, in place. */
-export async function compactV8Reports(dir) {
+/**
+ * Compact, in place, every `coverage-*.json` in `dir` that no earlier
+ * capture shipped, and mark it shipped. A dump mid-write (not yet valid
+ * JSON) is left for the next capture.
+ */
+export async function prepareV8Reports(dir) {
     const fs = await import("node:fs/promises");
     const path = await import("node:path");
+    const stats = { dumps: 0, scripts: 0, bytesIn: 0, bytesOut: 0 };
     let names;
     try {
         names = await fs.readdir(dir);
     }
     catch {
-        return;
+        return stats;
     }
-    for (const name of names) {
-        if (!name.startsWith("coverage-") || !name.endsWith(".json"))
+    for (const name of names.sort()) {
+        if (!name.startsWith("coverage-") || !name.endsWith(".json") || name === NODE_COVERAGE_EMPTY_REPORT)
             continue;
         const file = path.join(dir, name);
-        if (COMPACTED_V8_REPORTS.has(file))
+        if (SHIPPED_V8_REPORTS.has(file))
             continue;
+        let text;
         let doc;
         try {
-            doc = JSON.parse(await fs.readFile(file, "utf8"));
+            text = await fs.readFile(file, "utf8");
+            doc = JSON.parse(text);
         }
         catch {
             continue; // a dump mid-write, or not ours; the read path judges it
         }
         if (!Array.isArray(doc.result))
             continue;
+        const out = JSON.stringify(compactV8Document(doc, SHIPPED_SOURCE_MAPS));
         const tmp = path.join(dir, `.${name}.compact`);
-        await fs.writeFile(tmp, JSON.stringify(compactV8Document(doc)));
+        await fs.writeFile(tmp, out);
         await fs.rename(tmp, file);
-        COMPACTED_V8_REPORTS.add(file);
+        SHIPPED_V8_REPORTS.add(file);
+        stats.dumps++;
+        stats.scripts += doc.result.length;
+        stats.bytesIn += text.length;
+        stats.bytesOut += out.length;
     }
+    return stats;
 }
 // ── browser ───────────────────────────────────────────────────────
 /**