@specific.dev/spectest 0.58.0 → 0.59.1

package/src/daemon.ts

@@ -32,9 +32,6 @@ import {
   dnsName as makeDnsDecl,
   isWildcard,
   proxy as makeProxyDecl,
-  validateCoverage,
-  coverageUsesBrowser,
-  coverageUsesContainer,
 } from "./index.js";
 import type { DnsTarget, LoweredIngress } from "./index.js";
 import {
@@ -42,15 +39,20 @@ import {
   coverageBundleRef,
   coverageHostDir,
   encodeCoverageBundle,
+  isEmptyReport,
   readCoverageDir,
   type CoverageBundleRef,
   type CoverageReport,
   type ServiceCoverageCapture,
 } from "./harness/coverage.js";
+import { configureBrowserCoverage } from "./browser-coverage.js";
 import {
-  browserCoverageReports,
-  configureBrowserCoverage,
-} from "./browser-coverage.js";
+  applyCoverageAdapters,
+  coverageAdapters,
+  validateCoverage,
+  type CoverageAdapter,
+  type CoverageCaptureContext,
+} from "./coverage.js";
 import { serviceForHost as hostToService } from "./harness/browser-coverage.js";
 import { acquirePersistentBrowser, mobileKey } from "./browser.js";
 import { isMobileApp, openPersistentMobile } from "./mobile.js";
@@ -785,9 +787,6 @@ async function ensureVolumes(svc: NamedService): Promise<string[]> {
 async function ensureCoverage(svc: NamedService): Promise<string[]> {
   if (svc.coverage === undefined) return [];
   validateCoverage(svc.name, svc.coverage);
-  // A browser-only opt-in has no container process to write reports, so it
-  // gets no mount — its coverage comes from the guest browser.
-  if (!coverageUsesContainer(svc.coverage)) return [];
   const host = coverageHostDir(WORKSPACE, svc.name);
   await fs.mkdir(host, { recursive: true });
   await fs.chmod(host, 0o777);
@@ -1813,7 +1812,11 @@ function buildIngress(project: Project): void {
   // generic decl set the daemon executes. The special-casing lives in the
   // SDK's lowerIngress, not here.
   LOWERED = lowerIngress(project);
-  configureCoverageAttribution(project);
+  BROWSER_COVERAGE_SERVICES.clear();
+  void runCoverageLoadHooks(namedServices(project.environment)).catch((err) => {
+    // eslint-disable-next-line no-console
+    console.warn("[coverage] load hook failed:", err);
+  });
   if (!project.fakes) return;
   for (const [name, def] of Object.entries(project.fakes)) {
     FAKES.set(name, {
@@ -2797,7 +2800,9 @@ const RUNTIME_SERVICES = new Map<string, NamedService>();
 // the orchestration helpers want a NamedService, which is the same shape.
 function specToNamedService(spec: RuntimeServiceSpec): NamedService {
   const { name, ...rest } = spec;
-  return { name, ...(rest as ServiceConfig) };
+  // A runtime spec skipped `defineEnvironment`, so its coverage adapters
+  // get their config-time pass here.
+  return { name, ...applyCoverageAdapters(name, rest as ServiceConfig) };
 }
 
 /** Implementation behind `ctx.startService` / a fake's `ctx.startService`.
@@ -2811,6 +2816,7 @@ async function startRuntimeService(spec: RuntimeServiceSpec): Promise<RuntimeSer
   const t0 = Date.now();
   const resv = reserveEvent();
   const svc = specToNamedService(spec);
+  await runCoverageLoadHooks([svc]);
   const aliases = (spec.hostnames ?? []).map((h) => h.toLowerCase());
   const imageRef = svc.image.type === "registry" ? svc.image.reference : "(dockerfile)";
   try {
@@ -3601,34 +3607,53 @@ async function captureServiceLogDeltas(): Promise<ServiceLogDelta[]> {
 }
 
 // ────────────────────────────────────────────────────────────────────────
-// Coverage capture (opt-in per service; see harness/coverage.ts)
+// Coverage capture (opt-in per service; see coverage.ts + harness/coverage.ts)
 // ────────────────────────────────────────────────────────────────────────
 //
-// Read after bring-up and after every test, on every case. The reports are
-// cumulative from process start and live on the rootfs, so what a child
-// fork reads already includes everything its ancestors ran — no markers,
-// no deltas (unlike the service logs above). A `command` runs in the
-// container first so the service writes a fresh report. The reports ship
-// verbatim; the server derives what it needs from the stored bytes.
-
-const COVERAGE_COMMAND_TIMEOUT_MS = 60_000;
-
-/** Set the browser-coverage host→service attribution from the loaded
- *  project: only services that opted in to `coverage: { browser: true }`
- *  are attributed, so a script from an uncovered service is ignored. Null
- *  when no service opted in — coverage then attaches nothing. Called on
- *  every /load. */
-function configureCoverageAttribution(project: Project): void {
-  const env = project.environment;
-  const browserServices = new Set<string>();
-  for (const svc of namedServices(env)) {
-    if (coverageUsesBrowser(svc.coverage)) browserServices.add(svc.name);
+// Read after bring-up and after every test, on every case. A service's
+// adapters run first (each makes its report appear in the directory —
+// `nodeCoverage` asks the hook for a dump, `browserCoverage` writes the
+// harness's totals, `commandCoverage` runs the command), then the
+// directory is read the same way for every service, `coverage: true`
+// included. The reports live on the rootfs, so what a child fork reads
+// already includes everything its ancestors ran — no markers, no deltas
+// (unlike the service logs above). The reports ship verbatim; the server
+// derives what it needs from the stored bytes.
+
+/** Budget for one service's adapters at one capture, all of them. */
+const COVERAGE_CAPTURE_TIMEOUT_MS = 60_000;
+
+/** Services whose adapters asked for browser scripts at /load
+ *  (`CoverageLoadContext.collectBrowserScripts`). Cleared on every /load;
+ *  a runtime service's adapters add to it when it starts. */
+const BROWSER_COVERAGE_SERVICES = new Set<string>();
+
+/** Run every adapter's `load` hook for `services`, then rebuild the
+ *  browser-coverage attribution from whoever asked. The attribution is a
+ *  host → service resolver over the lowered ingress, restricted to those
+ *  services, so a script from an uncovered service is ignored; null when
+ *  nobody asked, which costs nothing. */
+async function runCoverageLoadHooks(services: NamedService[]): Promise<void> {
+  for (const svc of services) {
+    for (const a of coverageAdapters(svc.coverage)) {
+      if (!a.load) continue;
+      await a.load({
+        service: svc.name,
+        collectBrowserScripts: () => {
+          BROWSER_COVERAGE_SERVICES.add(svc.name);
+        },
+      });
+    }
   }
-  if (browserServices.size === 0) {
+  rebuildBrowserCoverageResolver();
+}
+
+function rebuildBrowserCoverageResolver(): void {
+  if (BROWSER_COVERAGE_SERVICES.size === 0 || !loaded) {
     configureBrowserCoverage(null);
     return;
   }
-  const all = namedServices(env).map((s) => s.name);
+  const all = [...namedServices(loaded.project.environment).map((s) => s.name), ...RUNTIME_SERVICES.keys()];
   const table = {
     proxies: LOWERED.proxies,
     aliasesByService: LOWERED.aliasesByService,
@@ -3637,11 +3662,72 @@ function configureCoverageAttribution(project: Project): void {
   configureBrowserCoverage({
     serviceForHost(host: string): string | undefined {
       const svc = hostToService(host, all, table);
-      return svc && browserServices.has(svc) ? svc : undefined;
+      return svc && BROWSER_COVERAGE_SERVICES.has(svc) ? svc : undefined;
     },
   });
 }
 
+/** The context one adapter's `capture` runs against. */
+function coverageCaptureContext(svc: NamedService, signal: AbortSignal): CoverageCaptureContext {
+  const reportDir = coverageHostDir(WORKSPACE, svc.name);
+  return {
+    service: svc.name,
+    reportDir,
+    signal,
+    async exec(command: string) {
+      const r = await docker(["exec", svc.name, "sh", "-c", command], COVERAGE_CAPTURE_TIMEOUT_MS);
+      if (r.code !== 0) {
+        const tail = capMiddle((r.stderr || r.stdout).trim(), 2000).value;
+        throw new Error(`${JSON.stringify(command)} exited ${r.code}${tail ? `\n${tail}` : ""}`);
+      }
+      return { stdout: r.stdout, stderr: r.stderr };
+    },
+    async writeReport(name: string, content: string) {
+      const file = path.join(reportDir, name);
+      if (path.relative(reportDir, file).startsWith("..")) {
+        throw new Error(`writeReport: ${JSON.stringify(name)} leaves the coverage directory`);
+      }
+      await fs.mkdir(path.dirname(file), { recursive: true });
+      const tmp = path.join(path.dirname(file), `.${path.basename(file)}.tmp`);
+      await fs.writeFile(tmp, content);
+      await fs.rename(tmp, 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> {
+  const adapters = coverageAdapters(svc.coverage).filter((a) => a.capture);
+  if (adapters.length === 0) return undefined;
+  const ac = new AbortController();
+  const timer = setTimeout(() => ac.abort(), COVERAGE_CAPTURE_TIMEOUT_MS);
+  const ctx = coverageCaptureContext(svc, ac.signal);
+  try {
+    for (const a of adapters) {
+      try {
+        await Promise.race([
+          (a as Required<Pick<CoverageAdapter, "capture">>).capture(ctx),
+          new Promise<never>((_, reject) => {
+            ac.signal.addEventListener(
+              "abort",
+              () => reject(new Error(`no report within ${COVERAGE_CAPTURE_TIMEOUT_MS / 1000}s`)),
+              { once: true },
+            );
+          }),
+        ]);
+      } catch (err) {
+        return `coverage adapter "${a.name}" on service "${svc.name}" failed: ${
+          err instanceof Error ? err.message : String(err)
+        }`;
+      }
+    }
+    return undefined;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
 async function captureServiceCoverage(): Promise<ServiceCoverageCapture[]> {
   const l = loaded;
   if (!l) return [];
@@ -3649,48 +3735,11 @@ async function captureServiceCoverage(): Promise<ServiceCoverageCapture[]> {
   for (const s of namedServices(l.project.environment)) byName.set(s.name, s);
   for (const [name, s] of RUNTIME_SERVICES) byName.set(name, s);
   const services = [...byName.values()].filter((s) => s.coverage !== undefined);
-  // Browser coverage is per-service lcov, accumulated in module memory
-  // (browser-coverage.ts) across every harvest; read it once here.
-  const browser = browserCoverageReports();
   return Promise.all(
     services.map(async (svc): Promise<ServiceCoverageCapture> => {
-      const cov = svc.coverage;
-      const reports: CoverageReport[] = [];
-      // Container reports (a `command` runs first to flush a fresh dump).
-      if (coverageUsesContainer(cov)) {
-        if (typeof cov === "object" && cov !== null && cov.command) {
-          const r = await docker(
-            ["exec", svc.name, "sh", "-c", cov.command],
-            COVERAGE_COMMAND_TIMEOUT_MS,
-          );
-          if (r.code !== 0) {
-            const tail = capMiddle((r.stderr || r.stdout).trim(), 2000).value;
-            return {
-              service: svc.name,
-              reports: [],
-              error: `coverage command for service "${svc.name}" failed (exit ${r.code}): ${JSON.stringify(cov.command)}${tail ? `\n${tail}` : ""}`,
-            };
-          }
-        }
-        const dir = await readCoverageDir(svc.name, coverageHostDir(WORKSPACE, svc.name));
-        // A service that ALSO does browser coverage may legitimately have
-        // an empty container dir for a test — don't fail if the browser
-        // side has something. Otherwise the container contract stands.
-        if (dir.error && !(coverageUsesBrowser(cov) && browser.has(svc.name))) {
-          return dir;
-        }
-        reports.push(...dir.reports);
-      }
-      // Browser report for this service, when any script it served ran.
-      const lcov = browser.get(svc.name);
-      if (lcov) reports.push({ name: "browser.lcov", content: lcov });
-      if (reports.length === 0 && coverageUsesBrowser(cov) && !coverageUsesContainer(cov)) {
-        // Browser-only service, no browser activity yet this branch. Not an
-        // error — a test needn't open a browser; the report appears once
-        // one does (and forks to descendants from there).
-        return { service: svc.name, reports: [] };
-      }
-      return { service: svc.name, reports };
+      const error = await runCoverageAdapters(svc);
+      if (error) return { service: svc.name, reports: [], error };
+      return readCoverageDir(svc.name, coverageHostDir(WORKSPACE, svc.name));
     }),
   );
 }
@@ -6143,7 +6192,19 @@ export function harnessMethods(state: RouteState): MethodTable {
       // the control plane logs it.
       let coverage: CoverageBundleRef | undefined;
       try {
-        coverage = parkCoverageBundle(SETUP_CASE_ID, await captureServiceCoverage());
+        const captures = await captureServiceCoverage();
+        for (const c of captures) {
+          // After bring-up the code that started the service has run, so a
+          // report set that names no file at all is a misconfigured tool —
+          // visible in the boot log, never a failure (there is no case).
+          if (!c.error && c.reports.length > 0 && c.reports.every((r) => isEmptyReport(r.content))) {
+            // eslint-disable-next-line no-console
+            console.warn(
+              `[coverage] service "${c.service}": every report is empty after bring-up — is coverage enabled at process start?`,
+            );
+          }
+        }
+        coverage = parkCoverageBundle(SETUP_CASE_ID, captures);
       } catch (err) {
         // eslint-disable-next-line no-console
         console.warn("[coverage] baseline capture failed:", err);

package/src/harness/coverage.test.ts

@@ -8,6 +8,10 @@ import {
   coverageHostDir,
   encodeCoverageBundle,
   hasLcovSourceFile,
+  isEmptyReport,
+  isLcovShaped,
+  isV8CoverageJson,
+  isWellFormedReport,
   listReportFiles,
   readCoverageDir,
 } from "./coverage";
@@ -24,7 +28,48 @@ describe("hasLcovSourceFile", () => {
   });
 });
 
+describe("report shapes", () => {
+  test("lcov: every non-blank line a record; an SF-less report is well-formed and empty", () => {
+    expect(isLcovShaped("TN:\nSF:/a.js\nDA:1,1\nend_of_record\n")).toBe(true);
+    expect(isLcovShaped("TN:\n")).toBe(true);
+    expect(isEmptyReport("TN:\n")).toBe(true);
+    expect(isEmptyReport("TN:\nSF:/a.js\n")).toBe(false);
+    expect(isLcovShaped("")).toBe(false);
+    expect(isLcovShaped("hello world\n")).toBe(false);
+    expect(isLcovShaped("SF:/a.js\ngarbage\n")).toBe(false);
+  });
+  test("V8 JSON: shape check only; an empty result is empty", () => {
+    const v8 = '{"result":[{"scriptId":"1","url":"file:///app/a.js","functions":[]}]}';
+    expect(isV8CoverageJson(v8)).toBe(true);
+    expect(isEmptyReport(v8)).toBe(false);
+    expect(isEmptyReport('{"result":[]}')).toBe(true);
+    expect(isV8CoverageJson("{}")).toBe(false);
+    expect(isWellFormedReport(v8)).toBe(true);
+    expect(isWellFormedReport("TN:\n")).toBe(true);
+    expect(isWellFormedReport("nope")).toBe(false);
+  });
+});
+
 describe("readCoverageDir", () => {
+  test("a V8 coverage JSON file satisfies the contract", async () => {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), "spectest-cov-"));
+    await fs.writeFile(
+      path.join(dir, "coverage-1-2-3.json"),
+      '{"result":[{"scriptId":"1","url":"file:///app/a.js","functions":[]}]}',
+    );
+    const r = await readCoverageDir("web", dir);
+    expect(r.error).toBeUndefined();
+    expect(r.reports.length).toBe(1);
+  });
+  test("a malformed file next to a good one is an error naming the file", async () => {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), "spectest-cov-"));
+    await fs.writeFile(path.join(dir, "lcov.info"), "TN:\nSF:/a.js\nend_of_record\n");
+    await fs.writeFile(path.join(dir, "junk.txt"), "not a report\n");
+    const r = await readCoverageDir("web", dir);
+    expect(r.error).toContain("junk.txt");
+    expect(r.reports.length).toBe(2);
+  });
+
   test("ships every report verbatim, nested, with relative names", async () => {
     const dir = await tmp();
     await fs.mkdir(path.join(dir, "sub"));
@@ -56,7 +101,7 @@ describe("readCoverageDir", () => {
     await fs.writeFile(path.join(dir, "coverage.json"), "{}");
     const r = await readCoverageDir("web", dir);
     expect(r.reports.length).toBe(1);
-    expect(r.error).toContain("SF:");
+    expect(r.error).toContain("none is an lcov report or a V8 coverage JSON document");
   });
 
   test("listReportFiles skips dotfiles", async () => {

package/src/harness/coverage.ts

@@ -2,12 +2,15 @@
 //
 // A service that opts in (`coverage: true | { command }`) gets a writable
 // directory bind-mounted at `/spectest/coverage/` in its container. The
-// service's own tool writes lcov reports there. The daemon reads the
+// service's own tool, or its coverage adapters, write reports there —
+// lcov, or the V8 coverage JSON that `NODE_V8_COVERAGE` writes. The daemon reads the
 // directory from the VM side (no `docker exec` to fetch) after bring-up
 // and after each test, and ships the reports **verbatim** to the control
 // plane as a gzipped bundle. Nothing is interpreted here beyond the one
-// contract the harness must fail a case on: at least one report, and at
-// least one lcov `SF:` record among them. The server derives whatever it
+// contract the harness must fail a case on: at least one report, every
+// one well-formed. Counters may reset between dumps and a dump may be a
+// new file: the directory forks with the environment, so it accumulates
+// along the ancestor chain by itself. The server derives whatever it
 // needs (today the set of source files; later, finer things) from the
 // stored bytes, so a change in that derivation is a re-read of stored
 // runs, never a hole in the history.
@@ -22,7 +25,7 @@ import { gzipSync } from "node:zlib";
 export const COVERAGE_CONTAINER_DIR = "/spectest/coverage";
 
 /** Raw bytes of reports one service may ship per capture. Reports are
- *  cumulative and bounded by code size, so anything past this is a
+ *  bounded by code size times chain depth, so anything past this is a
  *  runaway (a tool writing a new file per request), not coverage. */
 export const COVERAGE_MAX_BYTES_PER_SERVICE = 64 * 1024 * 1024;
 
@@ -76,6 +79,37 @@ export function hasLcovSourceFile(text: string): boolean {
   return /^SF:\S/m.test(text);
 }
 
+/** True when `text` is lcov-shaped: at least one line, every non-blank
+ *  line an `XX:` record or `end_of_record`. An lcov with no `SF:` record
+ *  at all (`TN:` alone) is well-formed — it is a report that says
+ *  nothing ran. */
+export function isLcovShaped(text: string): boolean {
+  const lines = text.split(/\r?\n/).filter((l) => l.trim().length > 0);
+  return lines.length > 0 && lines.every((l) => /^[A-Z]{2,5}:/.test(l) || l.trim() === "end_of_record");
+}
+
+/**
+ * True when `text` looks like a V8 coverage JSON document — what
+ * `NODE_V8_COVERAGE` / `v8.takeCoverage()` write: an object with a
+ * `result` array of scripts. A cheap shape check, not a parse (a report
+ * can be megabytes); the control plane parses for real.
+ */
+export function isV8CoverageJson(text: string): boolean {
+  return /^\s*\{/.test(text) && /"result"\s*:\s*\[/.test(text);
+}
+
+/** True when `text` is a report spectest stores: lcov or V8 JSON. */
+export function isWellFormedReport(text: string): boolean {
+  return isLcovShaped(text) || isV8CoverageJson(text);
+}
+
+/** True when a well-formed report names no source file at all (an lcov
+ *  with no `SF:`, a V8 document with an empty `result`). */
+export function isEmptyReport(text: string): boolean {
+  if (isV8CoverageJson(text)) return /"result"\s*:\s*\[\s*\]/.test(text);
+  return !hasLcovSourceFile(text);
+}
+
 /** Every regular file under `dir`, recursively, as paths relative to it.
  *  Hidden files are skipped (a tool's own bookkeeping — `.seq`, `.lock`,
  *  a tmp file mid-write — is not a report). */
@@ -100,9 +134,11 @@ export async function listReportFiles(dir: string): Promise<string[]> {
 }
 
 /**
- * Read every report under `dir`, verbatim. An empty directory, or one with
- * no `SF:` record anywhere, is an error rather than an empty capture: the
- * contract is that an opted-in service always has a report to read.
+ * Read every report under `dir`, verbatim. An empty directory, or a file
+ * that is neither lcov nor V8 JSON, is an error rather than an empty
+ * capture: the contract is that an opted-in service always has a
+ * well-formed report to read. A report that names no file is fine — it
+ * says nothing ran.
  */
 export async function readCoverageDir(
   service: string,
@@ -113,12 +149,13 @@ export async function readCoverageDir(
     return {
       service,
       reports: [],
-      error: `service "${service}" opted in to coverage but ${COVERAGE_CONTAINER_DIR}/ holds no report — the service (or its coverage command) must write an lcov file there`,
+      error: `service "${service}" opted in to coverage but ${COVERAGE_CONTAINER_DIR}/ holds no report — the service (or its coverage command) must write an lcov or V8 coverage JSON file there`,
     };
   }
   const reports: CoverageReport[] = [];
   let total = 0;
-  let anyLcov = false;
+  let anyReport = false;
+  const malformed: string[] = [];
   for (const name of names) {
     let content: string;
     try {
@@ -131,17 +168,20 @@ export async function readCoverageDir(
       return {
         service,
         reports: [],
-        error: `service "${service}" has more than ${COVERAGE_MAX_BYTES_PER_SERVICE >> 20} MiB of reports in ${COVERAGE_CONTAINER_DIR}/ — reports must be cumulative, not one file per dump`,
+        error: `service "${service}" has more than ${COVERAGE_MAX_BYTES_PER_SERVICE >> 20} MiB of reports in ${COVERAGE_CONTAINER_DIR}/ — that is a runaway, not coverage`,
       };
     }
-    if (hasLcovSourceFile(content)) anyLcov = true;
+    if (isWellFormedReport(content)) anyReport = true;
+    else malformed.push(name);
     reports.push({ name, content });
   }
-  if (!anyLcov) {
+  if (!anyReport || malformed.length > 0) {
     return {
       service,
       reports,
-      error: `service "${service}" wrote ${reports.length} file(s) to ${COVERAGE_CONTAINER_DIR}/ but none holds an lcov \`SF:\` record — only lcov reports are read`,
+      error: `service "${service}" wrote ${reports.length} file(s) to ${COVERAGE_CONTAINER_DIR}/ but ${
+        anyReport ? `${malformed.slice(0, 5).join(", ")} ${malformed.length === 1 ? "is" : "are"} neither` : "none is"
+      } an lcov report or a V8 coverage JSON document — only those two formats are read`,
     };
   }
   return { service, reports };

package/src/index.ts

@@ -132,6 +132,19 @@ export type { Terminal, TerminalOpts, TerminalResult } from "./terminal.js";
 
 import type { Terminal, TerminalOpts, TerminalResult } from "./terminal.js";
 
+// Coverage adapter types. The adapters themselves (`node()`, `browser()`,
+// `command()`, `defineAdapter`) are imported from
+// `@specific.dev/spectest/coverage` — see `coverage.ts` and
+// `spectest docs /services/coverage`.
+export {
+  type CoverageAdapter,
+  type CoverageCaptureContext,
+  type CoverageConfigureInfo,
+  type CoverageLoadContext,
+  type ServiceCoverage,
+} from "./coverage.js";
+import { applyCoverageAdapters, validateCoverage, type ServiceCoverage } from "./coverage.js";
+
 // Low-level ingress primitives + the framework lowering that the friendly
 // `tls` / `hostnames` fields and `defineFake(...)` are built on. See
 // `ingress.ts`.
@@ -256,20 +269,24 @@ export interface ServiceConfig {
    * Opt this service in to **code coverage collection** (experimental).
    *
    * The service gets a writable directory bind-mounted at
-   * `/spectest/coverage/`. The service's own coverage tool writes **lcov**
-   * reports there — cumulative from process start, never reset. After
-   * bring-up and after every test, spectest runs `command` (if given) inside
-   * the container, then reads every file in the directory and records the
-   * set of source files that ran. Only the `SF:` records are read.
+   * `/spectest/coverage/`. After bring-up and after every test, spectest
+   * reads every file in it — **lcov** or **V8 coverage JSON**, verbatim —
+   * and stores them with the test; the control plane derives what ran.
    *
-   * - `true`: the service writes its reports by itself (a dump on a timer,
-   *   an exit-time dump for short-lived processes).
-   * - `{ command }`: run this (via `sh -c`) in the container to make the
-   *   service write a report, before the directory is read.
+   * - `true`: the program writes its own reports there (an exit-time dump
+   *   for a short-lived process, a dump on a timer, its own hook).
+   * - `{ adapters: [...] }`: spectest gets the reports out. From
+   *   `@specific.dev/spectest/coverage`: `node()` (V8 JSON from a node
+   *   service, through a hook spectest mounts), `browser()` (the frontend
+   *   this service serves, collected from the guest browser),
+   *   `command(cmd)` (run a command in the container first), or your own
+   *   via `defineAdapter`.
    *
-   * The directory must hold at least one lcov report each time it is read;
-   * an empty directory or a failed command fails the test with a clear
-   * error, so a hole in the coverage data is never silent. See
+   * The directory must hold at least one well-formed report each time it
+   * is read; an empty directory or a failing adapter fails the test with a
+   * clear error, so a hole in the coverage data is never silent. Reports
+   * accumulate along the test's ancestor chain by themselves (the
+   * directory forks with the environment). See
    * `spectest docs /services/coverage`.
    */
   coverage?: ServiceCoverage;
@@ -1038,31 +1055,8 @@ export type ServiceImage =
       exclude?: readonly string[];
     };
 
-/**
- * A service's opt-in to coverage collection — see `ServiceConfig.coverage`.
- * `true` when the service writes its own reports; `{ command }` when
- * spectest must run a command in the container to produce one.
- */
-export type ServiceCoverage =
-  | true
-  | {
-      /** Run this (via `sh -c`) in the container before the coverage
-       *  directory is read, so the service writes a fresh lcov report. */
-      command?: string;
-      /**
-       * Collect **frontend** coverage for the app this service serves.
-       * The code runs in the guest browser — spectest's own process — so
-       * the user cannot write a report for it: spectest turns on V8
-       * coverage for every script `ctx.browser()`/`ctx.mobile()` loads
-       * from this service's origin, maps it back to original sources
-       * through the served source maps, and adds one lcov report to this
-       * service's capture. Scripts a source map can't resolve are
-       * attributed to their served path (which the repo mapping then
-       * treats as unknown — the safe answer). Needs the app to serve
-       * source maps to the test environment.
-       */
-      browser?: boolean;
-    };
+// Coverage adapters live in `coverage.ts`; the type is re-declared here
+// through the import below so `ServiceConfig.coverage` reads in one place.
 
 export interface VolumeMount {
   /**
@@ -1283,39 +1277,6 @@ export interface FakeContext {
   certificate(hostnames: readonly string[]): Promise<CertificateMaterial>;
 }
 
-/**
- * Check one service's `coverage` field. Exported so the daemon applies the
- * same rule to a runtime `startService` spec.
- */
-export function validateCoverage(service: string, cov: unknown): void {
-  if (cov === undefined || cov === true) return;
-  if (typeof cov === "object" && cov !== null) {
-    const o = cov as { command?: unknown; browser?: unknown };
-    const cmdOk =
-      o.command === undefined ||
-      (typeof o.command === "string" && o.command.trim().length > 0);
-    const browserOk = o.browser === undefined || typeof o.browser === "boolean";
-    if (cmdOk && browserOk && (o.command !== undefined || o.browser === true)) return;
-  }
-  throw new Error(
-    `service "${service}" has an invalid \`coverage\` value — use \`true\`, \`{ command: "<shell command>" }\`, or \`{ browser: true }\``,
-  );
-}
-
-/** Whether a `coverage` value collects reports from the container's own
- *  filesystem (`/spectest/coverage/`). True for `true`, `{ command }`, and
- *  any object that isn't browser-only. */
-export function coverageUsesContainer(cov: ServiceCoverage | undefined): boolean {
-  if (cov === undefined) return false;
-  if (cov === true) return true;
-  return cov.command !== undefined || cov.browser !== true;
-}
-
-/** Whether a `coverage` value collects frontend (browser) coverage. */
-export function coverageUsesBrowser(cov: ServiceCoverage | undefined): boolean {
-  return typeof cov === "object" && cov.browser === true;
-}
-
 function validateEnvironmentConfig<S extends ServicesMap>(
   config: EnvironmentConfig<S>,
 ): void {
@@ -2236,9 +2197,13 @@ export function defineEnvironment<
   // { name, services, timeoutSecs } — with plain, fully-expanded services —
   // is stored as `config` and shipped to the control plane.
   const { fakes, services: rawServices, ...rest } = input;
+  const expanded = expandServiceGroups(rawServices);
+  for (const [key, svc] of Object.entries(expanded)) {
+    expanded[key] = applyCoverageAdapters(key, svc);
+  }
   const config: EnvironmentConfig<S> = {
     ...rest,
-    services: expandServiceGroups(rawServices) as S,
+    services: expanded as S,
   };
   validateEnvironmentConfig(config);
   if (fakes) validateFakes(config, fakes);