@specific.dev/spectest 0.59.4 → 0.60.1

package/src/coverage.ts

@@ -14,8 +14,11 @@
 //
 // 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. Adapters convert nothing — the control
-// plane derives what it needs from the stored bytes.
+// 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.
 //
 // Imported from `@specific.dev/spectest/coverage`. The three shipped
 // adapters: `node()` (V8 JSON through a hook spectest mounts), `browser()`
@@ -26,10 +29,10 @@
 //   coverage: { adapters: [coverage.node(), coverage.browser()] }
 
 import type { ServiceConfig } from "./index.js";
-import { browserCoverageReports } from "./browser-coverage.js";
+import { harvestAllBrowserCoverage, takeBrowserCoverageReports } from "./browser-coverage.js";
 
-import { COVERAGE_CONTAINER_DIR } from "./harness/coverage.js";
-export { COVERAGE_CONTAINER_DIR };
+import { COVERAGE_CONTAINER_DIR, type CoverageReportsMode } from "./harness/coverage.js";
+export { COVERAGE_CONTAINER_DIR, type CoverageReportsMode };
 
 /** Where `node()` mounts its hook inside the container. */
 export const NODE_COVERAGE_HOOK_PATH = "/spectest/coverage-hook.cjs";
@@ -41,6 +44,27 @@ export const NODE_COVERAGE_EMPTY_REPORT = "coverage-spectest-empty.json";
  *  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";
+
 /** What `configure` learns about the service it rewrites. */
 export interface CoverageConfigureInfo {
   /** The services-map key. */
@@ -87,6 +111,15 @@ export interface CoverageCaptureContext {
 export interface CoverageAdapter {
   /** Names the adapter in errors (`coverage adapter "node" on service …`). */
   name: string;
+  /**
+   * How the reports this adapter writes (through `ctx.writeReport`)
+   * count: `"delta"` — what ran since the previous capture, the tool
+   * resets its own counters; `"cumulative"` (the default) — since
+   * process start, and spectest subtracts the previous capture. Reports
+   * the adapter makes appear some other way (`command`) follow the
+   * service's own `reports`.
+   */
+  reports?: CoverageReportsMode;
   /**
    * Rewrite the service at config time. Must be pure and deterministic
    * (the result is hashed into the warm-template key) and must **append**
@@ -99,9 +132,18 @@ export interface CoverageAdapter {
   capture?(ctx: CoverageCaptureContext): void | Promise<void>;
 }
 
-/** `ServiceConfig.coverage`: the program writes its own reports, or a
- *  list of adapters gets them out. */
-export type ServiceCoverage = true | { adapters: readonly CoverageAdapter[] };
+/** `ServiceConfig.coverage`: the program writes its own reports (`true`),
+ *  or a list of adapters gets them out, and/or how the reports the
+ *  program itself writes count (`reports`, default `"cumulative"`). */
+export type ServiceCoverage =
+  | true
+  | { adapters?: readonly CoverageAdapter[]; reports?: CoverageReportsMode };
+
+/** The `reports` mode of a `coverage` value, for the reports no adapter
+ *  wrote (the program's own, a `command`'s). */
+export function coverageReportsMode(cov: ServiceCoverage | undefined): CoverageReportsMode {
+  return typeof cov === "object" && cov !== null && cov.reports ? cov.reports : "cumulative";
+}
 
 /** Type an inline adapter. Identity at runtime. */
 export function defineAdapter(adapter: CoverageAdapter): CoverageAdapter {
@@ -112,14 +154,22 @@ export function defineAdapter(adapter: CoverageAdapter): CoverageAdapter {
  *  the same rule to a runtime `startService` spec. */
 export function validateCoverage(service: string, cov: unknown): void {
   if (cov === undefined || cov === true) return;
-  const adapters = (cov as { adapters?: unknown } | null)?.adapters;
-  if (typeof cov === "object" && cov !== null && Array.isArray(adapters)) {
-    for (const a of adapters) {
+  const obj = typeof cov === "object" && cov !== null ? (cov as Record<string, unknown>) : null;
+  const adapters = obj?.adapters;
+  const reports = obj?.reports;
+  const knownKeys = obj !== null && Object.keys(obj).every((k) => k === "adapters" || k === "reports");
+  const okReports = reports === undefined || reports === "delta" || reports === "cumulative";
+  const okAdapters = adapters === undefined || Array.isArray(adapters);
+  if (obj !== null && knownKeys && okReports && okAdapters && (adapters !== undefined || reports !== undefined)) {
+    for (const a of (adapters as unknown[] | undefined) ?? []) {
       const ok =
         typeof a === "object" &&
         a !== null &&
         typeof (a as CoverageAdapter).name === "string" &&
         (a as CoverageAdapter).name.length > 0 &&
+        ((a as CoverageAdapter).reports === undefined ||
+          (a as CoverageAdapter).reports === "delta" ||
+          (a as CoverageAdapter).reports === "cumulative") &&
         ["configure", "load", "capture"].every(
           (k) =>
             (a as Record<string, unknown>)[k] === undefined ||
@@ -127,20 +177,20 @@ export function validateCoverage(service: string, cov: unknown): void {
         );
       if (!ok) {
         throw new Error(
-          `service "${service}" has an invalid coverage adapter — an adapter is \`{ name, configure?, load?, capture? }\` (see \`defineAdapter\` in @specific.dev/spectest/coverage)`,
+          `service "${service}" has an invalid coverage adapter — an adapter is \`{ name, reports?, configure?, load?, capture? }\` (see \`defineAdapter\` in @specific.dev/spectest/coverage)`,
         );
       }
     }
     return;
   }
   throw new Error(
-    `service "${service}" has an invalid \`coverage\` value — use \`true\` (the program writes its own reports) or \`{ adapters: [...] }\` from @specific.dev/spectest/coverage (\`node()\`, \`browser()\`, \`command("…")\`)`,
+    `service "${service}" has an invalid \`coverage\` value — use \`true\` (the program writes its own reports), \`{ adapters: [...] }\` from @specific.dev/spectest/coverage (\`node()\`, \`browser()\`, \`command("…")\`), and/or \`{ reports: "delta" | "cumulative" }\``,
   );
 }
 
 /** The adapters of a `coverage` value (`true` has none). */
 export function coverageAdapters(cov: ServiceCoverage | undefined): readonly CoverageAdapter[] {
-  return typeof cov === "object" && cov !== null ? cov.adapters : [];
+  return typeof cov === "object" && cov !== null ? (cov.adapters ?? []) : [];
 }
 
 /**
@@ -158,7 +208,8 @@ export function applyCoverageAdapters<S extends ServiceConfig>(key: string, svc:
   for (const a of adapters) {
     if (a.configure) out = a.configure(out, { key });
   }
-  const wire = { adapters: adapters.map((a) => withWireName(a)) };
+  const mode = (svc.coverage as { reports?: CoverageReportsMode }).reports;
+  const wire = { adapters: adapters.map((a) => withWireName(a)), ...(mode ? { reports: mode } : {}) };
   return { ...out, coverage: wire } as unknown as S;
 }
 
@@ -243,15 +294,30 @@ if (process.env.NODE_V8_COVERAGE && require("node:worker_threads").isMainThread)
  * container then writes V8 coverage JSON when it exits) and `--require`s
  * a hook that lets spectest ask every live node process for a dump at
  * capture time — the server, and any wrapper it sits behind (`pnpm exec`,
- * `tsx`). Nothing
- * for the app to write. Each dump is compacted to the app's own scripts
- * at capture ({@link compactV8Document}). Source maps: with `--enable-source-maps` (or a
- * `sourceMappingURL` next to the file) Node records the map in the
- * report, which is what maps a TypeScript service back to its sources.
+ * `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.
  */
 export function node(): CoverageAdapter {
   return {
     name: "node",
+    reports: "delta",
     configure(svc) {
       const env = appendEnvFlag(svc.env, "NODE_OPTIONS", `--require ${NODE_COVERAGE_HOOK_PATH}`);
       env.NODE_V8_COVERAGE = COVERAGE_CONTAINER_DIR;
@@ -266,12 +332,16 @@ export function node(): CoverageAdapter {
       // here; a service whose node processes are short-lived (a CLI run
       // by `ctx.exec` from a `sleep infinity` container) has no socket to
       // answer and its coverage is the exit-time dumps already on disk.
-      // So no live process is not an error. No report at all — nothing
-      // has run yet on this branch — is recorded as an empty document
+      // So no live process is not an error. No dump at all — nothing
+      // has run yet on this branch — is recorded as an empty report
       // 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))) {
         await ctx.writeReport(NODE_COVERAGE_EMPTY_REPORT, '{"result":[]}\n');
@@ -280,6 +350,101 @@ export function node(): CoverageAdapter {
   };
 }
 
+/** The VM-side tools dir, after the test override. */
+export function nodeCoverageToolsDir(): string {
+  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(): Promise<boolean> {
+  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(): string {
+  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: CoverageCaptureContext): Promise<void> {
+  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: Record<string, unknown>;
+    try {
+      doc = JSON.parse(await fs.readFile(file, "utf8")) as Record<string, unknown>;
+    } 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: string;
+  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: string): string {
+  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,
@@ -369,10 +534,14 @@ export function isAppScriptUrl(url: string): boolean {
  * 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). Still a V8
- * document — nothing is converted.
+ * 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.
  */
-export function compactV8Document(doc: Record<string, unknown>): Record<string, unknown> {
+export function compactV8Document(
+  doc: Record<string, unknown>,
+  opts: { keepSourcesContent?: boolean } = {},
+): Record<string, unknown> {
   const result = Array.isArray(doc.result) ? (doc.result as { url?: unknown }[]) : [];
   const kept = result.filter((s) => typeof s.url === "string" && isAppScriptUrl(s.url));
   const out: Record<string, unknown> = { ...doc, result: kept };
@@ -383,7 +552,7 @@ export function compactV8Document(doc: Record<string, unknown>): Record<string,
     for (const [url, entry] of Object.entries(cache as Record<string, unknown>)) {
       if (!urls.has(url) || !entry || typeof entry !== "object") continue;
       const e = { ...(entry as Record<string, unknown>) };
-      if (e.data && typeof e.data === "object") {
+      if (!opts.keepSourcesContent && e.data && typeof e.data === "object") {
         const { sourcesContent: _dropped, ...data } = e.data as Record<string, unknown>;
         e.data = data;
       }
@@ -430,17 +599,21 @@ export async function compactV8Reports(dir: string): Promise<void> {
  * browser — spectest's own process — so no report can be written by the
  * container; spectest collects V8 coverage for every script the browser
  * loads from this service's origins, maps it back to source through the
- * served source map, and writes one lcov per capture. Nothing ran yet on
- * this branch ⇒ an lcov with no records, which is a report saying so.
+ * served source map, and writes one lcov per capture (`browser.lcov`)
+ * holding what ran since the previous capture: every live session is
+ * harvested first, and the totals are taken and cleared. Nothing ran ⇒
+ * an lcov with no records, which is a report saying so.
  */
 export function browser(): CoverageAdapter {
   return {
     name: "browser",
+    reports: "delta",
     load(ctx) {
       ctx.collectBrowserScripts();
     },
     async capture(ctx) {
-      const lcov = browserCoverageReports().get(ctx.service) ?? "TN:\n";
+      await harvestAllBrowserCoverage();
+      const lcov = takeBrowserCoverageReports().get(ctx.service) ?? "TN:\n";
       await ctx.writeReport("browser.lcov", lcov);
     },
   };
@@ -451,7 +624,10 @@ export function browser(): CoverageAdapter {
 /**
  * Run `command` (via `sh -c`) in the container at every capture, so the
  * service writes a fresh report into `/spectest/coverage/`. The escape
- * hatch for a runtime with no shipped adapter.
+ * hatch for a runtime with no shipped adapter. The reports it makes
+ * appear follow the service's `reports` mode (cumulative by default —
+ * spectest subtracts the previous capture; `{ reports: "delta" }` when
+ * the tool resets its own counters).
  */
 export function command(command: string): CoverageAdapter {
   if (typeof command !== "string" || command.trim().length === 0) {

package/src/daemon.ts

@@ -41,6 +41,7 @@ import {
   encodeCoverageBundle,
   isEmptyReport,
   readCoverageDir,
+  applyCoverageDelta,
   type CoverageBundleRef,
   type CoverageReport,
   type ServiceCoverageCapture,
@@ -49,7 +50,11 @@ import { configureBrowserCoverage } from "./browser-coverage.js";
 import {
   applyCoverageAdapters,
   coverageAdapters,
+  coverageReportsMode,
   validateCoverage,
+  nodeCoverageToolsAvailable,
+  nodeCoverageToolsDir,
+  NODE_COVERAGE_TOOLS_CONTAINER_DIR,
   type CoverageAdapter,
   type CoverageCaptureContext,
 } from "./coverage.js";
@@ -790,7 +795,16 @@ async function ensureCoverage(svc: NamedService): Promise<string[]> {
   const host = coverageHostDir(WORKSPACE, svc.name);
   await fs.mkdir(host, { recursive: true });
   await fs.chmod(host, 0o777);
-  return [`--volume=${host}:${COVERAGE_CONTAINER_DIR}`];
+  const flags = [`--volume=${host}:${COVERAGE_CONTAINER_DIR}`];
+  // The conversion tools golden ships (`c8` for `coverage.node()`),
+  // read-only, on the same existence check the adapter makes at capture
+  // — so the VM and the container agree on whether they are there. A
+  // plain `--volume`, never a config `volumes` entry: an absolute-source
+  // volume dir is listed in the delta-restore manifest and wiped.
+  if (await nodeCoverageToolsAvailable()) {
+    flags.push(`--volume=${nodeCoverageToolsDir()}:${NODE_COVERAGE_TOOLS_CONTAINER_DIR}:ro`);
+  }
+  return flags;
 }
 
 /** A `user`/`group` pair resolved to the numeric ids the kernel wants.
@@ -3667,8 +3681,14 @@ function rebuildBrowserCoverageResolver(): void {
   });
 }
 
-/** The context one adapter's `capture` runs against. */
-function coverageCaptureContext(svc: NamedService, signal: AbortSignal): CoverageCaptureContext {
+/** The context one adapter's `capture` runs against. Every report it
+ *  writes through `writeReport` is added to `written`, so the delta step
+ *  knows which files came from which adapter. */
+function coverageCaptureContext(
+  svc: NamedService,
+  signal: AbortSignal,
+  written: Set<string>,
+): CoverageCaptureContext {
   const reportDir = coverageHostDir(WORKSPACE, svc.name);
   return {
     service: svc.name,
@@ -3691,20 +3711,27 @@ function coverageCaptureContext(svc: NamedService, signal: AbortSignal): Coverag
       const tmp = path.join(path.dirname(file), `.${path.basename(file)}.tmp`);
       await fs.writeFile(tmp, content);
       await fs.rename(tmp, file);
+      written.add(path.relative(reportDir, file));
     },
   };
 }
 
 /** Run one service's adapters in order under one budget. Returns the
- *  error to fail the capture with, naming the adapter. */
-async function runCoverageAdapters(svc: NamedService): Promise<string | undefined> {
+ *  error to fail the capture with, naming the adapter, and the reports
+ *  written by adapters that declare `reports: "delta"`. */
+async function runCoverageAdapters(
+  svc: NamedService,
+): Promise<{ error?: string; deltaReports: Set<string> }> {
+  const deltaReports = new Set<string>();
   const adapters = coverageAdapters(svc.coverage).filter((a) => a.capture);
-  if (adapters.length === 0) return undefined;
+  if (adapters.length === 0) return { deltaReports };
   const ac = new AbortController();
   const timer = setTimeout(() => ac.abort(), COVERAGE_CAPTURE_TIMEOUT_MS);
-  const ctx = coverageCaptureContext(svc, ac.signal);
+  const written = new Set<string>();
+  const ctx = coverageCaptureContext(svc, ac.signal, written);
   try {
     for (const a of adapters) {
+      written.clear();
       try {
         await Promise.race([
           (a as Required<Pick<CoverageAdapter, "capture">>).capture(ctx),
@@ -3717,12 +3744,16 @@ async function runCoverageAdapters(svc: NamedService): Promise<string | undefine
           }),
         ]);
       } catch (err) {
-        return `coverage adapter "${a.name}" on service "${svc.name}" failed: ${
-          err instanceof Error ? err.message : String(err)
-        }`;
+        return {
+          error: `coverage adapter "${a.name}" on service "${svc.name}" failed: ${
+            err instanceof Error ? err.message : String(err)
+          }`,
+          deltaReports,
+        };
       }
+      if (a.reports === "delta") for (const n of written) deltaReports.add(n);
     }
-    return undefined;
+    return { deltaReports };
   } finally {
     clearTimeout(timer);
   }
@@ -3737,9 +3768,14 @@ async function captureServiceCoverage(): Promise<ServiceCoverageCapture[]> {
   const services = [...byName.values()].filter((s) => s.coverage !== undefined);
   return Promise.all(
     services.map(async (svc): Promise<ServiceCoverageCapture> => {
-      const error = await runCoverageAdapters(svc);
+      const { error, deltaReports } = await runCoverageAdapters(svc);
       if (error) return { service: svc.name, reports: [], error };
-      return readCoverageDir(svc.name, coverageHostDir(WORKSPACE, svc.name));
+      const read = await readCoverageDir(svc.name, coverageHostDir(WORKSPACE, svc.name));
+      // What ships is what ran during this capture, whatever the tool
+      // counts: cumulative lcov is subtracted against the previous
+      // capture (module memory, forks with the env); a delta adapter's
+      // files and V8 JSON pass through.
+      return applyCoverageDelta(read, coverageReportsMode(svc.coverage), deltaReports);
     }),
   );
 }

package/src/harness/coverage.test.ts

@@ -131,3 +131,88 @@ test("bundle round-trips and the ref summarises it", () => {
 test("coverageHostDir sits under the workspace's .spectest", () => {
   expect(coverageHostDir("/workspace", "api")).toBe("/workspace/.spectest/coverage/api");
 });
+
+import {
+  applyCoverageDelta,
+  parseLcovCounts,
+  renderLcovCounts,
+  resetCoverageDeltaMemory,
+  subtractLcovCounts,
+} from "./coverage.js";
+
+describe("coverage delta", () => {
+  const boot = "TN:\nSF:/app/a.py\nFN:1,main\nFNDA:1,main\nDA:1,1\nDA:2,1\nDA:3,0\nend_of_record\nSF:/app/b.py\nDA:1,5\nend_of_record\n";
+  const later = "TN:\nSF:/app/a.py\nFN:1,main\nFNDA:1,main\nDA:1,1\nDA:2,1\nDA:3,4\nend_of_record\nSF:/app/b.py\nDA:1,5\nend_of_record\nSF:/app/c.py\nDA:1,2\nend_of_record\n";
+
+  test("parse merges records for one path and reads DA/FNDA/FN", () => {
+    const c = parseLcovCounts("SF:/x\nDA:1,1\nend_of_record\nSF:/x\nDA:1,2\nFN:3,f\nFNDA:4,f\nend_of_record\nSF:\nDA:9,9\n");
+    expect([...c.keys()]).toEqual(["/x"]);
+    expect(c.get("/x")!.lines.get(1)).toBe(3);
+    expect(c.get("/x")!.functions.get("f")).toBe(4);
+    expect(c.get("/x")!.functionLines.get("f")).toBe(3);
+  });
+
+  test("subtract keeps only what ran since; a dropped counter is a restart; a new file counts whole", () => {
+    const d = subtractLcovCounts(parseLcovCounts(later), parseLcovCounts(boot));
+    expect([...d.keys()].sort()).toEqual(["/app/a.py", "/app/c.py"]); // b.py: nothing new
+    expect(d.get("/app/a.py")!.lines.get(3)).toBe(4);
+    expect(d.get("/app/a.py")!.lines.get(1)).toBe(0);
+    expect(d.get("/app/a.py")!.functions.get("main")).toBe(0);
+    expect(d.get("/app/c.py")!.lines.get(1)).toBe(2);
+    const names: string[] = [];
+    const restarted = subtractLcovCounts(parseLcovCounts("SF:/app/b.py\nDA:1,2\nend_of_record\n"), parseLcovCounts(boot), names);
+    expect(restarted.get("/app/b.py")!.lines.get(1)).toBe(2);
+    expect(names).toEqual(["/app/b.py"]);
+    // A restart is per record: one dropped counter means every count in
+    // that record stands, including a line that ran exactly as often
+    // again (the boot line: 1 before, 1 now — not 0). Other records in
+    // the same report still subtract.
+    const mixed = subtractLcovCounts(
+      parseLcovCounts("SF:/app/a.py\nFNDA:1,main\nDA:1,1\nDA:2,1\nDA:3,0\nend_of_record\nSF:/app/b.py\nDA:1,3\nend_of_record\n"),
+      parseLcovCounts("SF:/app/a.py\nFNDA:1,main\nDA:1,1\nDA:2,1\nDA:3,7\nend_of_record\nSF:/app/b.py\nDA:1,1\nend_of_record\n"),
+    );
+    expect(mixed.get("/app/a.py")!.lines.get(1)).toBe(1);
+    expect(mixed.get("/app/a.py")!.functions.get("main")).toBe(1);
+    expect(mixed.get("/app/b.py")!.lines.get(1)).toBe(2);
+    // A record with no counts at all: presence is its signal, new only once.
+    const bare = "SF:/app/bare.py\nend_of_record\n";
+    expect(subtractLcovCounts(parseLcovCounts(bare), new Map()).has("/app/bare.py")).toBe(true);
+    expect(subtractLcovCounts(parseLcovCounts(bare), parseLcovCounts(bare)).has("/app/bare.py")).toBe(false);
+  });
+
+  test("render round-trips and totals the header counts", () => {
+    const text = renderLcovCounts(subtractLcovCounts(parseLcovCounts(later), parseLcovCounts(boot)));
+    expect(text).toBe(
+      "TN:\nSF:/app/a.py\nFN:1,main\nFNDA:0,main\nFNF:1\nFNH:0\nDA:1,0\nDA:2,0\nDA:3,4\nLF:3\nLH:1\nend_of_record\nSF:/app/c.py\nFNF:0\nFNH:0\nDA:1,2\nLF:1\nLH:1\nend_of_record\n",
+    );
+    expect(parseLcovCounts(text).get("/app/a.py")!.lines.get(3)).toBe(4);
+  });
+
+  test("applyCoverageDelta: cumulative reports are subtracted per service and name; delta and V8 reports pass", () => {
+    resetCoverageDeltaMemory();
+    const first = applyCoverageDelta(
+      { service: "api", reports: [{ name: "cov.lcov", content: boot }, { name: "node.lcov", content: later }, { name: "coverage-1.json", content: '{"result":[]}' }] },
+      "cumulative",
+      new Set(["node.lcov"]),
+    );
+    // First capture: no previous, the whole boot set.
+    expect(first.reports[0]!.content).toContain("SF:/app/a.py");
+    expect(first.reports[0]!.content).toContain("SF:/app/b.py");
+    expect(first.reports[1]!.content).toBe(later); // delta adapter's own file, untouched
+    expect(first.reports[2]!.content).toBe('{"result":[]}');
+    const second = applyCoverageDelta({ service: "api", reports: [{ name: "cov.lcov", content: later }] }, "cumulative", new Set());
+    expect(second.reports[0]!.content).not.toContain("SF:/app/b.py");
+    expect(second.reports[0]!.content).toContain("DA:3,4");
+    // Nothing new: an lcov with no records.
+    const third = applyCoverageDelta({ service: "api", reports: [{ name: "cov.lcov", content: later }] }, "cumulative", new Set());
+    expect(third.reports[0]!.content).toBe("TN:\n");
+    // Another service has its own memory; a delta-mode service is never touched.
+    const other = applyCoverageDelta({ service: "web", reports: [{ name: "cov.lcov", content: later }] }, "cumulative", new Set());
+    expect(other.reports[0]!.content).toContain("SF:/app/b.py");
+    const asIs = applyCoverageDelta({ service: "api", reports: [{ name: "cov.lcov", content: later }] }, "delta", new Set());
+    expect(asIs.reports[0]!.content).toBe(later);
+    // An errored capture passes through.
+    const err = applyCoverageDelta({ service: "api", reports: [], error: "x" }, "cumulative", new Set());
+    expect(err.error).toBe("x");
+  });
+});