@specific.dev/spectest 0.56.2 → 0.57.0

package/dist/daemon.js

@@ -21,7 +21,8 @@ import { existsSync, promises as fs, readFileSync } from "node:fs";
 import net from "node:net";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
-import { assert, expect, expectRaw, lowerIngress, dnsName as makeDnsDecl, isWildcard, proxy as makeProxyDecl, } from "./index.js";
+import { assert, expect, expectRaw, lowerIngress, dnsName as makeDnsDecl, isWildcard, proxy as makeProxyDecl, validateCoverage, } from "./index.js";
+import { COVERAGE_CONTAINER_DIR, coverageBundleRef, coverageHostDir, encodeCoverageBundle, readCoverageDir, } from "./harness/coverage.js";
 import { acquirePersistentBrowser, mobileKey } from "./browser.js";
 import { isMobileApp, openPersistentMobile } from "./mobile.js";
 // Pure ingress hostname matching, ported out of this file (see
@@ -510,6 +511,23 @@ async function ensureVolumes(svc) {
     }
     return flags;
 }
+/**
+ * The coverage directory for an opted-in service: one host dir per service
+ * under the workspace (so the delta-restore teardown wipes it), mounted
+ * writable at `/spectest/coverage/`. World-writable because the container
+ * may run as any user and spectest creates the dir as root. The reports in
+ * it ride snapshots and forks like everything else on the rootfs, which is
+ * what makes each read cumulative along the test's ancestor chain.
+ */
+async function ensureCoverage(svc) {
+    if (svc.coverage === undefined)
+        return [];
+    validateCoverage(svc.name, svc.coverage);
+    const host = coverageHostDir(WORKSPACE, svc.name);
+    await fs.mkdir(host, { recursive: true });
+    await fs.chmod(host, 0o777);
+    return [`--volume=${host}:${COVERAGE_CONTAINER_DIR}`];
+}
 /** Keyed by image ID, not tag: `spectest/<svc>:latest` is retagged onto
  *  new content every rebuild, and a stale uid is silently wrong. */
 const IMAGE_ID_TABLES = new Map();
@@ -2309,6 +2327,7 @@ async function startRuntimeService(spec) {
             ...(await ensureVolumes(svc)),
             ...(await ensureFiles(svc, tag)),
             ...(await ensureCertificates(svc, tag)),
+            ...(await ensureCoverage(svc)),
         ];
         await runContainer(svc, tag, flags, aliases);
         await waitForReady(svc);
@@ -2707,6 +2726,7 @@ async function bootstrapInner() {
             ...(await ensureVolumes(svc)),
             ...(await ensureFiles(svc, tag)),
             ...(await ensureCertificates(svc, tag)),
+            ...(await ensureCoverage(svc)),
         ];
         const tRun = Date.now();
         progressService(svc.name, { status: "starting", detail: undefined });
@@ -2827,18 +2847,37 @@ async function runProjectSetupInner() {
 // bundle in guest RAM — entries older than the last few are always
 // already-fetched leftovers frozen into some snapshot.
 const REPLAY_BUNDLES = new Map();
-const REPLAY_BUNDLES_MAX = 8;
-function stashReplayBundle(caseId, gz) {
+/** Coverage bundles, same side-channel and same lifetime rules; pulled
+ *  through `coverageChunk`. The env-setup baseline parks under the
+ *  control plane's synthetic `__setup__` case id. */
+const COVERAGE_BUNDLES = new Map();
+const PARKED_BUNDLES_MAX = 8;
+/** The control plane's synthetic case id for env-setup captures
+ *  (`storage::SETUP_CASE_ID`). Not a real case id — those are kebab slugs. */
+const SETUP_CASE_ID = "__setup__";
+function stashBundle(map, caseId, gz) {
     // Re-insert to refresh recency (Map iterates in insertion order).
-    REPLAY_BUNDLES.delete(caseId);
-    REPLAY_BUNDLES.set(caseId, gz);
-    while (REPLAY_BUNDLES.size > REPLAY_BUNDLES_MAX) {
-        const oldest = REPLAY_BUNDLES.keys().next().value;
+    map.delete(caseId);
+    map.set(caseId, gz);
+    while (map.size > PARKED_BUNDLES_MAX) {
+        const oldest = map.keys().next().value;
         if (oldest === undefined)
             break;
-        REPLAY_BUNDLES.delete(oldest);
+        map.delete(oldest);
     }
 }
+function stashReplayBundle(caseId, gz) {
+    stashBundle(REPLAY_BUNDLES, caseId, gz);
+}
+/** Encode + park a case's coverage captures; returns the ref for the reply.
+ *  `undefined` when no service opted in, so uncovered projects ship nothing. */
+function parkCoverageBundle(caseId, captures) {
+    if (captures.length === 0)
+        return undefined;
+    const gz = encodeCoverageBundle(caseId, captures);
+    stashBundle(COVERAGE_BUNDLES, caseId, gz);
+    return coverageBundleRef(gz, captures);
+}
 // ────────────────────────────────────────────────────────────────────────
 // Cumulative service logs (per-case deltas → S3, reconstructed on the web)
 // ────────────────────────────────────────────────────────────────────────
@@ -2930,6 +2969,43 @@ async function captureServiceLogDeltas() {
         };
     }));
 }
+// ────────────────────────────────────────────────────────────────────────
+// Coverage capture (opt-in per service; see 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;
+async function captureServiceCoverage() {
+    const l = loaded;
+    if (!l)
+        return [];
+    const byName = new Map();
+    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);
+    return Promise.all(services.map(async (svc) => {
+        const cov = svc.coverage;
+        if (typeof cov === "object" && cov !== null) {
+            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}` : ""}`,
+                };
+            }
+        }
+        return readCoverageDir(svc.name, coverageHostDir(WORKSPACE, svc.name));
+    }));
+}
 /**
  * Mint a session id. `idScope` (the running test's case id; `"eval"`
  * for eval-context sessions) is baked in because `randomUUID()` alone
@@ -4128,6 +4204,33 @@ async function runOne(testCase) {
         // eslint-disable-next-line no-console
         console.warn("[service-logs] delta capture failed:", err);
     }
+    // Coverage for the opted-in services, read after the clock stops like
+    // the log deltas. Unlike them it is NOT best-effort: a service that opted
+    // in and produced nothing readable fails the case, so a hole in the
+    // coverage data is visible where it happened rather than silently
+    // widening every later subset run.
+    let coverageCaptures = [];
+    try {
+        coverageCaptures = await captureServiceCoverage();
+    }
+    catch (err) {
+        coverageCaptures = [
+            {
+                service: "*",
+                reports: [],
+                error: `coverage capture failed: ${err instanceof Error ? err.message : String(err)}`,
+            },
+        ];
+    }
+    const coverageErrors = coverageCaptures
+        .filter((c) => c.error)
+        .map((c) => c.error);
+    if (coverageErrors.length > 0 && outcome.status === "passed") {
+        outcome = {
+            status: "failed",
+            error: { message: coverageErrors.join("\n") },
+        };
+    }
     const events = stopRecording();
     // Drop sessions whose linking event didn't survive — an exec/terminal
     // inside a failed `ctx.poll` iteration has its events removed by
@@ -4147,6 +4250,7 @@ async function runOne(testCase) {
         browserSessions: sessions.map((s) => s.record),
         terminalSessions: terminalSessions.filter((s) => referencedSessions.has(s.sessionId)),
         serviceLogDeltas,
+        coverageCaptures,
         error: outcome.error,
     };
 }
@@ -4898,7 +5002,20 @@ export function harnessMethods(state) {
                 // eslint-disable-next-line no-console
                 console.warn("[service-logs] baseline capture failed:", err);
             }
-            return { serviceLogDeltas };
+            // The coverage baseline rides the same call: what the opted-in
+            // services ran during bring-up + project setup, parked under the
+            // synthetic `__setup__` case for `coverageChunk`. A capture error is
+            // reported in the ref, not thrown — there is no case to fail here,
+            // the control plane logs it.
+            let coverage;
+            try {
+                coverage = parkCoverageBundle(SETUP_CASE_ID, await captureServiceCoverage());
+            }
+            catch (err) {
+                // eslint-disable-next-line no-console
+                console.warn("[coverage] baseline capture failed:", err);
+            }
+            return { serviceLogDeltas, coverage };
         },
         run: async (params) => {
             const caseId = requireString(params, "caseId", "caseId");
@@ -4912,7 +5029,10 @@ export function harnessMethods(state) {
                 // (with a warning) rather than failing the case — and never falls
                 // back to inlining, which is exactly the oversized reply this path
                 // exists to avoid.
-                const { browserSessions, ...wire } = result;
+                const { browserSessions, coverageCaptures, ...wire } = result;
+                // Coverage reports take the same side channel: park, reply with a
+                // ref, let the control plane pull through `coverageChunk`.
+                const coverage = parkCoverageBundle(caseId, coverageCaptures);
                 let replay;
                 if (browserSessions.length > 0) {
                     try {
@@ -4925,7 +5045,7 @@ export function harnessMethods(state) {
                         console.warn("[replay] bundle encode failed; dropping recordings:", err);
                     }
                 }
-                return { ...wire, replay };
+                return { ...wire, replay, coverage };
             });
         },
         // One chunk of a parked replay bundle. Case ids are arbitrary user
@@ -4937,6 +5057,14 @@ export function harnessMethods(state) {
                 throw notFound(`no replay bundle for case: ${caseId}`);
             return replayChunk(gz, params.offset, params.limit);
         },
+        // One chunk of a parked coverage bundle (same shape as replayChunk).
+        coverageChunk: async (params) => {
+            const caseId = requireString(params, "caseId", "caseId");
+            const gz = COVERAGE_BUNDLES.get(caseId);
+            if (!gz)
+                throw notFound(`no coverage bundle for case: ${caseId}`);
+            return replayChunk(gz, params.offset, params.limit);
+        },
     };
 }
 /**

package/dist/harness/coverage.d.ts

@@ -0,0 +1,60 @@
+/** Where the directory is mounted inside an opted-in container. */
+export declare 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
+ *  runaway (a tool writing a new file per request), not coverage. */
+export declare const COVERAGE_MAX_BYTES_PER_SERVICE: number;
+/** Root of the per-service host directories, under the workspace so the
+ *  delta-restore teardown wipes them with everything else. */
+export declare function coverageHostDir(workspace: string, service: string): string;
+/** One report file, verbatim. `name` is its path relative to the
+ *  coverage directory. */
+export interface CoverageReport {
+    name: string;
+    content: string;
+}
+/** One service's capture: every report in its directory, verbatim. */
+export interface ServiceCoverageCapture {
+    service: string;
+    reports: CoverageReport[];
+    /** Set when the capture failed: the command failed, the directory was
+     *  empty, no file held an `SF:` record, or the reports were too large.
+     *  A case with an error here fails — a hole in the coverage data must
+     *  never be silent. */
+    error?: string;
+}
+/** The small ref that rides the `run` reply in place of the bundle. */
+export interface CoverageBundleRef {
+    /** Gzipped bundle size; the control plane pulls exactly this many bytes
+     *  through `coverageChunk`. */
+    bytes: number;
+    services: {
+        service: string;
+        reports: number;
+        /** Raw (uncompressed) bytes of this service's reports. */
+        bytes: number;
+        error?: string;
+    }[];
+}
+/** The gzipped JSON document `coverageChunk` serves. Mirrors
+ *  `storage::CaseCoverageBundle` on the server. */
+export interface CoverageBundle {
+    caseId: string;
+    services: ServiceCoverageCapture[];
+}
+/** True when `text` holds at least one lcov `SF:` record. */
+export declare function hasLcovSourceFile(text: string): boolean;
+/** 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). */
+export declare 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.
+ */
+export declare function readCoverageDir(service: string, dir: string): Promise<ServiceCoverageCapture>;
+/** Gzip a case's captures into the bundle `coverageChunk` serves. */
+export declare function encodeCoverageBundle(caseId: string, services: ServiceCoverageCapture[]): Buffer;
+/** The ref for a bundle: its size plus a per-service summary. */
+export declare function coverageBundleRef(gz: Buffer, services: ServiceCoverageCapture[]): CoverageBundleRef;

package/dist/harness/coverage.js

@@ -0,0 +1,122 @@
+// Coverage collection — the pure part.
+//
+// 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
+// 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
+// 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.
+//
+// The container side (mount flag, `command` exec) is in `daemon.ts`.
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { gzipSync } from "node:zlib";
+/** Where the directory is mounted inside an opted-in container. */
+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
+ *  runaway (a tool writing a new file per request), not coverage. */
+export const COVERAGE_MAX_BYTES_PER_SERVICE = 64 * 1024 * 1024;
+/** Root of the per-service host directories, under the workspace so the
+ *  delta-restore teardown wipes them with everything else. */
+export function coverageHostDir(workspace, service) {
+    return path.join(workspace, ".spectest", "coverage", service);
+}
+/** True when `text` holds at least one lcov `SF:` record. */
+export function hasLcovSourceFile(text) {
+    return /^SF:\S/m.test(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). */
+export async function listReportFiles(dir) {
+    const out = [];
+    async function walk(d, rel) {
+        let entries;
+        try {
+            entries = await fs.readdir(d, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            if (e.name.startsWith("."))
+                continue;
+            const r = rel ? `${rel}/${e.name}` : e.name;
+            if (e.isDirectory())
+                await walk(path.join(d, e.name), r);
+            else if (e.isFile())
+                out.push(r);
+        }
+    }
+    await walk(dir, "");
+    return out.sort();
+}
+/**
+ * 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.
+ */
+export async function readCoverageDir(service, dir) {
+    const names = await listReportFiles(dir);
+    if (names.length === 0) {
+        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`,
+        };
+    }
+    const reports = [];
+    let total = 0;
+    let anyLcov = false;
+    for (const name of names) {
+        let content;
+        try {
+            content = await fs.readFile(path.join(dir, name), "utf8");
+        }
+        catch {
+            continue;
+        }
+        total += content.length;
+        if (total > COVERAGE_MAX_BYTES_PER_SERVICE) {
+            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`,
+            };
+        }
+        if (hasLcovSourceFile(content))
+            anyLcov = true;
+        reports.push({ name, content });
+    }
+    if (!anyLcov) {
+        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`,
+        };
+    }
+    return { service, reports };
+}
+/** Gzip a case's captures into the bundle `coverageChunk` serves. */
+export function encodeCoverageBundle(caseId, services) {
+    const doc = { caseId, services };
+    return gzipSync(Buffer.from(JSON.stringify(doc)));
+}
+/** The ref for a bundle: its size plus a per-service summary. */
+export function coverageBundleRef(gz, services) {
+    return {
+        bytes: gz.length,
+        services: services.map((s) => ({
+            service: s.service,
+            reports: s.reports.length,
+            bytes: s.reports.reduce((n, r) => n + r.content.length, 0),
+            ...(s.error ? { error: s.error } : {}),
+        })),
+    };
+}

package/dist/index.d.ts

@@ -115,6 +115,27 @@ export interface ServiceConfig {
     tls?: readonly ServiceTls[];
     /** Bind-mounted volumes for state that survives snapshot/fork. */
     volumes?: readonly VolumeMount[];
+    /**
+     * 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.
+     *
+     * - `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.
+     *
+     * 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
+     * `spectest docs /services/coverage`.
+     */
+    coverage?: ServiceCoverage;
     /**
      * Files seeded into the container's filesystem **before it starts**.
      * Each entry's `content` is written to a VM-host staging path and
@@ -642,6 +663,14 @@ export type ServiceImage = {
     /** Extra glob patterns to exclude from the build context. */
     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 | {
+    command: string;
+};
 export interface VolumeMount {
     /**
      * Named shared volume. Two services mounting the same `name` share one
@@ -854,6 +883,11 @@ export interface FakeContext {
      *  for a TLS-provisioning provider hands back to the app under test. */
     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 declare function validateCoverage(service: string, cov: unknown): void;
 /**
  * A single test step. Created via `test(...)` or `createTest(services)`.
  * Tests are referenced (not named by string) when one test depends on

package/dist/index.js

@@ -215,6 +215,21 @@ function expandServiceGroups(input) {
     }
     return out;
 }
+/**
+ * Check one service's `coverage` field. Exported so the daemon applies the
+ * same rule to a runtime `startService` spec.
+ */
+export function validateCoverage(service, cov) {
+    if (cov === undefined || cov === true)
+        return;
+    if (typeof cov === "object" &&
+        cov !== null &&
+        typeof cov.command === "string" &&
+        cov.command.trim().length > 0) {
+        return;
+    }
+    throw new Error(`service "${service}" has an invalid \`coverage\` value — use \`true\` or \`{ command: "<shell command>" }\``);
+}
 function validateEnvironmentConfig(config) {
     const entries = Object.entries(config.services);
     const serviceNames = new Set(entries.map(([n]) => n));
@@ -246,6 +261,7 @@ function validateEnvironmentConfig(config) {
                 throw new Error(`service "${name}" volume name ${JSON.stringify(vol.name)} must be alphanumeric plus [._-]`);
             }
         }
+        validateCoverage(name, svc.coverage);
         for (const raw of svc.hostnames ?? []) {
             const h = raw.toLowerCase();
             if (!HOSTNAME_RE.test(hostPatternBody(h))) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.56.2",
+  "version": "0.57.0",
   "description": "Spectest SDK for defining test environments in TypeScript.",
   "type": "module",
   "main": "./dist/index.js",

package/src/daemon.ts

@@ -32,8 +32,18 @@ import {
   dnsName as makeDnsDecl,
   isWildcard,
   proxy as makeProxyDecl,
+  validateCoverage,
 } from "./index.js";
 import type { DnsTarget, LoweredIngress } from "./index.js";
+import {
+  COVERAGE_CONTAINER_DIR,
+  coverageBundleRef,
+  coverageHostDir,
+  encodeCoverageBundle,
+  readCoverageDir,
+  type CoverageBundleRef,
+  type ServiceCoverageCapture,
+} from "./harness/coverage.js";
 import { acquirePersistentBrowser, mobileKey } from "./browser.js";
 import { isMobileApp, openPersistentMobile } from "./mobile.js";
 // Pure ingress hostname matching, ported out of this file (see
@@ -756,6 +766,23 @@ async function ensureVolumes(svc: NamedService): Promise<string[]> {
   return flags;
 }
 
+/**
+ * The coverage directory for an opted-in service: one host dir per service
+ * under the workspace (so the delta-restore teardown wipes it), mounted
+ * writable at `/spectest/coverage/`. World-writable because the container
+ * may run as any user and spectest creates the dir as root. The reports in
+ * it ride snapshots and forks like everything else on the rootfs, which is
+ * what makes each read cumulative along the test's ancestor chain.
+ */
+async function ensureCoverage(svc: NamedService): Promise<string[]> {
+  if (svc.coverage === undefined) return [];
+  validateCoverage(svc.name, svc.coverage);
+  const host = coverageHostDir(WORKSPACE, svc.name);
+  await fs.mkdir(host, { recursive: true });
+  await fs.chmod(host, 0o777);
+  return [`--volume=${host}:${COVERAGE_CONTAINER_DIR}`];
+}
+
 /** A `user`/`group` pair resolved to the numeric ids the kernel wants.
  *  `-1` is chown(2)'s "leave this one alone". */
 interface OwnerIds {
@@ -2780,6 +2807,7 @@ async function startRuntimeService(spec: RuntimeServiceSpec): Promise<RuntimeSer
       ...(await ensureVolumes(svc)),
       ...(await ensureFiles(svc, tag)),
       ...(await ensureCertificates(svc, tag)),
+      ...(await ensureCoverage(svc)),
     ];
     await runContainer(svc, tag, flags, aliases);
     await waitForReady(svc);
@@ -3228,6 +3256,7 @@ async function bootstrapInner(): Promise<BootstrapTimings> {
       ...(await ensureVolumes(svc)),
       ...(await ensureFiles(svc, tag)),
       ...(await ensureCertificates(svc, tag)),
+      ...(await ensureCoverage(svc)),
     ];
     const tRun = Date.now();
     progressService(svc.name, { status: "starting", detail: undefined });
@@ -3369,6 +3398,16 @@ interface RunResult {
    * failing case's own delta. See {captureServiceLogDeltas}.
    */
   serviceLogDeltas: ServiceLogDelta[];
+  /**
+   * Per-service coverage for the services that opted in (`coverage` on
+   * the service): their lcov reports, verbatim, read after this case.
+   * Cumulative along the ancestor chain by construction. Like
+   * `browserSessions` this never rides the `run` reply — the handler
+   * parks a gzipped bundle and replies with a ref the control plane pulls
+   * through `coverageChunk`. An entry with `error` fails the case. See
+   * {captureServiceCoverage}.
+   */
+  coverageCaptures: ServiceCoverageCapture[];
   error?: { message: string; stack?: string };
 }
 
@@ -3391,19 +3430,42 @@ interface RunResult {
 // bundle in guest RAM — entries older than the last few are always
 // already-fetched leftovers frozen into some snapshot.
 const REPLAY_BUNDLES = new Map<string, Buffer>();
-const REPLAY_BUNDLES_MAX = 8;
-
-function stashReplayBundle(caseId: string, gz: Buffer): void {
+/** Coverage bundles, same side-channel and same lifetime rules; pulled
+ *  through `coverageChunk`. The env-setup baseline parks under the
+ *  control plane's synthetic `__setup__` case id. */
+const COVERAGE_BUNDLES = new Map<string, Buffer>();
+const PARKED_BUNDLES_MAX = 8;
+/** The control plane's synthetic case id for env-setup captures
+ *  (`storage::SETUP_CASE_ID`). Not a real case id — those are kebab slugs. */
+const SETUP_CASE_ID = "__setup__";
+
+function stashBundle(map: Map<string, Buffer>, caseId: string, gz: Buffer): void {
   // Re-insert to refresh recency (Map iterates in insertion order).
-  REPLAY_BUNDLES.delete(caseId);
-  REPLAY_BUNDLES.set(caseId, gz);
-  while (REPLAY_BUNDLES.size > REPLAY_BUNDLES_MAX) {
-    const oldest = REPLAY_BUNDLES.keys().next().value;
+  map.delete(caseId);
+  map.set(caseId, gz);
+  while (map.size > PARKED_BUNDLES_MAX) {
+    const oldest = map.keys().next().value;
     if (oldest === undefined) break;
-    REPLAY_BUNDLES.delete(oldest);
+    map.delete(oldest);
   }
 }
 
+function stashReplayBundle(caseId: string, gz: Buffer): void {
+  stashBundle(REPLAY_BUNDLES, caseId, gz);
+}
+
+/** Encode + park a case's coverage captures; returns the ref for the reply.
+ *  `undefined` when no service opted in, so uncovered projects ship nothing. */
+function parkCoverageBundle(
+  caseId: string,
+  captures: ServiceCoverageCapture[],
+): CoverageBundleRef | undefined {
+  if (captures.length === 0) return undefined;
+  const gz = encodeCoverageBundle(caseId, captures);
+  stashBundle(COVERAGE_BUNDLES, caseId, gz);
+  return coverageBundleRef(gz, captures);
+}
+
 // ────────────────────────────────────────────────────────────────────────
 // Cumulative service logs (per-case deltas → S3, reconstructed on the web)
 // ────────────────────────────────────────────────────────────────────────
@@ -3526,6 +3588,48 @@ async function captureServiceLogDeltas(): Promise<ServiceLogDelta[]> {
   );
 }
 
+// ────────────────────────────────────────────────────────────────────────
+// Coverage capture (opt-in per service; see 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;
+
+async function captureServiceCoverage(): Promise<ServiceCoverageCapture[]> {
+  const l = loaded;
+  if (!l) return [];
+  const byName = new Map<string, NamedService>();
+  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);
+  return Promise.all(
+    services.map(async (svc): Promise<ServiceCoverageCapture> => {
+      const cov = svc.coverage;
+      if (typeof cov === "object" && cov !== null) {
+        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}` : ""}`,
+          };
+        }
+      }
+      return readCoverageDir(svc.name, coverageHostDir(WORKSPACE, svc.name));
+    }),
+  );
+}
+
 /** Per-Browser rrweb session shipped to the control plane. */
 interface BrowserSessionRecord {
   sessionId: string;
@@ -5020,6 +5124,32 @@ async function runOne(testCase: TestCase<unknown>): Promise<RunResult> {
     // eslint-disable-next-line no-console
     console.warn("[service-logs] delta capture failed:", err);
   }
+  // Coverage for the opted-in services, read after the clock stops like
+  // the log deltas. Unlike them it is NOT best-effort: a service that opted
+  // in and produced nothing readable fails the case, so a hole in the
+  // coverage data is visible where it happened rather than silently
+  // widening every later subset run.
+  let coverageCaptures: ServiceCoverageCapture[] = [];
+  try {
+    coverageCaptures = await captureServiceCoverage();
+  } catch (err) {
+    coverageCaptures = [
+      {
+        service: "*",
+        reports: [],
+        error: `coverage capture failed: ${err instanceof Error ? err.message : String(err)}`,
+      },
+    ];
+  }
+  const coverageErrors = coverageCaptures
+    .filter((c) => c.error)
+    .map((c) => c.error as string);
+  if (coverageErrors.length > 0 && outcome.status === "passed") {
+    outcome = {
+      status: "failed",
+      error: { message: coverageErrors.join("\n") },
+    };
+  }
   const events = stopRecording();
   // Drop sessions whose linking event didn't survive — an exec/terminal
   // inside a failed `ctx.poll` iteration has its events removed by
@@ -5038,6 +5168,7 @@ async function runOne(testCase: TestCase<unknown>): Promise<RunResult> {
     browserSessions: sessions.map((s) => s.record),
     terminalSessions: terminalSessions.filter((s) => referencedSessions.has(s.sessionId)),
     serviceLogDeltas,
+    coverageCaptures,
     error: outcome.error,
   };
 }
@@ -5940,7 +6071,19 @@ export function harnessMethods(state: RouteState): MethodTable {
         // eslint-disable-next-line no-console
         console.warn("[service-logs] baseline capture failed:", err);
       }
-      return { serviceLogDeltas };
+      // The coverage baseline rides the same call: what the opted-in
+      // services ran during bring-up + project setup, parked under the
+      // synthetic `__setup__` case for `coverageChunk`. A capture error is
+      // reported in the ref, not thrown — there is no case to fail here,
+      // the control plane logs it.
+      let coverage: CoverageBundleRef | undefined;
+      try {
+        coverage = parkCoverageBundle(SETUP_CASE_ID, await captureServiceCoverage());
+      } catch (err) {
+        // eslint-disable-next-line no-console
+        console.warn("[coverage] baseline capture failed:", err);
+      }
+      return { serviceLogDeltas, coverage };
     },
 
     run: async (params) => {
@@ -5954,7 +6097,10 @@ export function harnessMethods(state: RouteState): MethodTable {
         // (with a warning) rather than failing the case — and never falls
         // back to inlining, which is exactly the oversized reply this path
         // exists to avoid.
-        const { browserSessions, ...wire } = result;
+        const { browserSessions, coverageCaptures, ...wire } = result;
+        // Coverage reports take the same side channel: park, reply with a
+        // ref, let the control plane pull through `coverageChunk`.
+        const coverage = parkCoverageBundle(caseId, coverageCaptures);
         let replay: { bytes: number } | undefined;
         if (browserSessions.length > 0) {
           try {
@@ -5966,7 +6112,7 @@ export function harnessMethods(state: RouteState): MethodTable {
             console.warn("[replay] bundle encode failed; dropping recordings:", err);
           }
         }
-        return { ...wire, replay };
+        return { ...wire, replay, coverage };
       });
     },
 
@@ -5978,6 +6124,14 @@ export function harnessMethods(state: RouteState): MethodTable {
       if (!gz) throw notFound(`no replay bundle for case: ${caseId}`);
       return replayChunk(gz, params.offset as number | undefined, params.limit as number | undefined);
     },
+
+    // One chunk of a parked coverage bundle (same shape as replayChunk).
+    coverageChunk: async (params) => {
+      const caseId = requireString(params, "caseId", "caseId");
+      const gz = COVERAGE_BUNDLES.get(caseId);
+      if (!gz) throw notFound(`no coverage bundle for case: ${caseId}`);
+      return replayChunk(gz, params.offset as number | undefined, params.limit as number | undefined);
+    },
   };
 }
 

package/src/harness/coverage.test.ts

@@ -0,0 +1,88 @@
+import { describe, expect, test } from "bun:test";
+import { promises as fs } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { gunzipSync } from "node:zlib";
+import {
+  coverageBundleRef,
+  coverageHostDir,
+  encodeCoverageBundle,
+  hasLcovSourceFile,
+  listReportFiles,
+  readCoverageDir,
+} from "./coverage";
+
+async function tmp(): Promise<string> {
+  return fs.mkdtemp(path.join(os.tmpdir(), "spectest-cov-"));
+}
+
+describe("hasLcovSourceFile", () => {
+  test("finds an SF record anywhere, tolerating CRLF", () => {
+    expect(hasLcovSourceFile("TN:\r\nSF:/app/server.js\r\nDA:1,1\n")).toBe(true);
+    expect(hasLcovSourceFile("TN:\nSF:\nend_of_record\n")).toBe(false);
+    expect(hasLcovSourceFile("{}")).toBe(false);
+  });
+});
+
+describe("readCoverageDir", () => {
+  test("ships every report verbatim, nested, with relative names", async () => {
+    const dir = await tmp();
+    await fs.mkdir(path.join(dir, "sub"));
+    await fs.writeFile(path.join(dir, "lcov.info"), "SF:/app/b.js\nDA:1,1\nend_of_record\n");
+    await fs.writeFile(path.join(dir, "sub", "more.info"), "SF:/app/c.js\n");
+    await fs.writeFile(path.join(dir, ".seq"), "3");
+    const r = await readCoverageDir("web", dir);
+    expect(r.error).toBeUndefined();
+    expect(r.reports).toEqual([
+      { name: "lcov.info", content: "SF:/app/b.js\nDA:1,1\nend_of_record\n" },
+      { name: "sub/more.info", content: "SF:/app/c.js\n" },
+    ]);
+  });
+
+  test("an empty directory is an error, not an empty capture", async () => {
+    const dir = await tmp();
+    const r = await readCoverageDir("web", dir);
+    expect(r.reports).toEqual([]);
+    expect(r.error).toContain("holds no report");
+  });
+
+  test("a missing directory is reported like an empty one", async () => {
+    const r = await readCoverageDir("web", "/nonexistent/spectest-cov");
+    expect(r.error).toContain("holds no report");
+  });
+
+  test("files with no SF record are an error, but still shipped", async () => {
+    const dir = await tmp();
+    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:");
+  });
+
+  test("listReportFiles skips dotfiles", async () => {
+    const dir = await tmp();
+    await fs.writeFile(path.join(dir, ".lock"), "");
+    await fs.writeFile(path.join(dir, "a.info"), "");
+    expect(await listReportFiles(dir)).toEqual(["a.info"]);
+  });
+});
+
+test("bundle round-trips and the ref summarises it", () => {
+  const services = [
+    { service: "web", reports: [{ name: "lcov.info", content: "SF:/app/a.js\n" }] },
+    { service: "api", reports: [], error: "no report" },
+  ];
+  const gz = encodeCoverageBundle("case-1", services);
+  expect(JSON.parse(gunzipSync(gz).toString())).toEqual({ caseId: "case-1", services });
+  expect(coverageBundleRef(gz, services)).toEqual({
+    bytes: gz.length,
+    services: [
+      { service: "web", reports: 1, bytes: 13 },
+      { service: "api", reports: 0, bytes: 0, error: "no report" },
+    ],
+  });
+});
+
+test("coverageHostDir sits under the workspace's .spectest", () => {
+  expect(coverageHostDir("/workspace", "api")).toBe("/workspace/.spectest/coverage/api");
+});

package/src/harness/coverage.ts

@@ -0,0 +1,173 @@
+// Coverage collection — the pure part.
+//
+// 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
+// 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
+// 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.
+//
+// The container side (mount flag, `command` exec) is in `daemon.ts`.
+
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { gzipSync } from "node:zlib";
+
+/** Where the directory is mounted inside an opted-in container. */
+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
+ *  runaway (a tool writing a new file per request), not coverage. */
+export const COVERAGE_MAX_BYTES_PER_SERVICE = 64 * 1024 * 1024;
+
+/** Root of the per-service host directories, under the workspace so the
+ *  delta-restore teardown wipes them with everything else. */
+export function coverageHostDir(workspace: string, service: string): string {
+  return path.join(workspace, ".spectest", "coverage", service);
+}
+
+/** One report file, verbatim. `name` is its path relative to the
+ *  coverage directory. */
+export interface CoverageReport {
+  name: string;
+  content: string;
+}
+
+/** One service's capture: every report in its directory, verbatim. */
+export interface ServiceCoverageCapture {
+  service: string;
+  reports: CoverageReport[];
+  /** Set when the capture failed: the command failed, the directory was
+   *  empty, no file held an `SF:` record, or the reports were too large.
+   *  A case with an error here fails — a hole in the coverage data must
+   *  never be silent. */
+  error?: string;
+}
+
+/** The small ref that rides the `run` reply in place of the bundle. */
+export interface CoverageBundleRef {
+  /** Gzipped bundle size; the control plane pulls exactly this many bytes
+   *  through `coverageChunk`. */
+  bytes: number;
+  services: {
+    service: string;
+    reports: number;
+    /** Raw (uncompressed) bytes of this service's reports. */
+    bytes: number;
+    error?: string;
+  }[];
+}
+
+/** The gzipped JSON document `coverageChunk` serves. Mirrors
+ *  `storage::CaseCoverageBundle` on the server. */
+export interface CoverageBundle {
+  caseId: string;
+  services: ServiceCoverageCapture[];
+}
+
+/** True when `text` holds at least one lcov `SF:` record. */
+export function hasLcovSourceFile(text: string): boolean {
+  return /^SF:\S/m.test(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). */
+export async function listReportFiles(dir: string): Promise<string[]> {
+  const out: string[] = [];
+  async function walk(d: string, rel: string): Promise<void> {
+    let entries;
+    try {
+      entries = await fs.readdir(d, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      if (e.name.startsWith(".")) continue;
+      const r = rel ? `${rel}/${e.name}` : e.name;
+      if (e.isDirectory()) await walk(path.join(d, e.name), r);
+      else if (e.isFile()) out.push(r);
+    }
+  }
+  await walk(dir, "");
+  return out.sort();
+}
+
+/**
+ * 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.
+ */
+export async function readCoverageDir(
+  service: string,
+  dir: string,
+): Promise<ServiceCoverageCapture> {
+  const names = await listReportFiles(dir);
+  if (names.length === 0) {
+    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`,
+    };
+  }
+  const reports: CoverageReport[] = [];
+  let total = 0;
+  let anyLcov = false;
+  for (const name of names) {
+    let content: string;
+    try {
+      content = await fs.readFile(path.join(dir, name), "utf8");
+    } catch {
+      continue;
+    }
+    total += content.length;
+    if (total > COVERAGE_MAX_BYTES_PER_SERVICE) {
+      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`,
+      };
+    }
+    if (hasLcovSourceFile(content)) anyLcov = true;
+    reports.push({ name, content });
+  }
+  if (!anyLcov) {
+    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`,
+    };
+  }
+  return { service, reports };
+}
+
+/** Gzip a case's captures into the bundle `coverageChunk` serves. */
+export function encodeCoverageBundle(
+  caseId: string,
+  services: ServiceCoverageCapture[],
+): Buffer {
+  const doc: CoverageBundle = { caseId, services };
+  return gzipSync(Buffer.from(JSON.stringify(doc)));
+}
+
+/** The ref for a bundle: its size plus a per-service summary. */
+export function coverageBundleRef(
+  gz: Buffer,
+  services: ServiceCoverageCapture[],
+): CoverageBundleRef {
+  return {
+    bytes: gz.length,
+    services: services.map((s) => ({
+      service: s.service,
+      reports: s.reports.length,
+      bytes: s.reports.reduce((n, r) => n + r.content.length, 0),
+      ...(s.error ? { error: s.error } : {}),
+    })),
+  };
+}

package/src/index.ts

@@ -252,6 +252,27 @@ export interface ServiceConfig {
   tls?: readonly ServiceTls[];
   /** Bind-mounted volumes for state that survives snapshot/fork. */
   volumes?: readonly VolumeMount[];
+  /**
+   * 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.
+   *
+   * - `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.
+   *
+   * 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
+   * `spectest docs /services/coverage`.
+   */
+  coverage?: ServiceCoverage;
   /**
    * Files seeded into the container's filesystem **before it starts**.
    * Each entry's `content` is written to a VM-host staging path and
@@ -1017,6 +1038,13 @@ 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 | { command: string };
+
 export interface VolumeMount {
   /**
    * Named shared volume. Two services mounting the same `name` share one
@@ -1236,6 +1264,25 @@ 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 &&
+    typeof (cov as { command?: unknown }).command === "string" &&
+    (cov as { command: string }).command.trim().length > 0
+  ) {
+    return;
+  }
+  throw new Error(
+    `service "${service}" has an invalid \`coverage\` value — use \`true\` or \`{ command: "<shell command>" }\``,
+  );
+}
+
 function validateEnvironmentConfig<S extends ServicesMap>(
   config: EnvironmentConfig<S>,
 ): void {
@@ -1281,6 +1328,7 @@ function validateEnvironmentConfig<S extends ServicesMap>(
         );
       }
     }
+    validateCoverage(name, svc.coverage);
     for (const raw of svc.hostnames ?? []) {
       const h = raw.toLowerCase();
       if (!HOSTNAME_RE.test(hostPatternBody(h))) {