@specific.dev/spectest 0.127.0 → 0.128.0

package/src/coverage-rust.test.ts

@@ -0,0 +1,74 @@
+import { expect, test } from "bun:test";
+import { promises as fs } from "node:fs";
+import { existsSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import path from "node:path";
+import os from "node:os";
+import { rust } from "./coverage-rust";
+import { captureCoverageTarget } from "./harness/coverage-target";
+import { encodeCoverageBundle } from "./harness/coverage";
+
+async function run(args: string[], cwd?: string) {
+  const child = Bun.spawn(args, { cwd, stdout: "pipe", stderr: "pipe" });
+  const [code, stdout, stderr] = await Promise.all([child.exited, new Response(child.stdout).text(), new Response(child.stderr).text()]);
+  if (code) throw new Error(`${args[0]}: ${stderr}`);
+  return stdout.trim();
+}
+
+const installedTools = (() => {
+  try {
+    const sysroot = execFileSync("rustc", ["--print", "sysroot"], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim();
+    const host = execFileSync("rustc", ["-vV"], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).match(/^host: (.+)$/m)![1];
+    const tools = path.join(sysroot, "lib/rustlib", host, "bin");
+    return existsSync(path.join(tools, "llvm-cov")) && existsSync(path.join(tools, "llvm-profdata")) ? tools : undefined;
+  } catch { return undefined; }
+})();
+test.skipIf(!installedTools)("Rust real LLVM reports capture live and exited processes, subtract baseline, and fail on lost processes", async () => {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), "rust-cov-"));
+  let child: ReturnType<typeof Bun.spawn> | undefined;
+  try {
+    const tools = installedTools!;
+    await fs.access(path.join(tools, "llvm-cov"));
+    await fs.mkdir(path.join(root, "reports"));
+    await fs.copyFile(new URL("./coverage/rust.rs", import.meta.url), path.join(root, "spectest-coverage.rs"));
+    await fs.writeFile(path.join(root, "main.rs"), `#[path="spectest-coverage.rs"] mod coverage;\nuse std::io::{self, BufRead, Write};\nfn choose(left: bool) -> u32 {\n if left { 41 } else { 42 }\n}\nfn main() {\n coverage::start().unwrap();\n println!("ready");\n io::stdout().flush().unwrap();\n for line in io::stdin().lock().lines() {\n  println!("{}",choose(line.unwrap()=="left"));\n  io::stdout().flush().unwrap();\n }\n}\n`);
+    await run(["rustc", "--edition=2024", "-C", "instrument-coverage", "-C", "opt-level=0", "main.rs", "-o", "server"], root);
+    const env = { ...process.env, SPECTEST_COVERAGE_DIR: `${root}/reports`, SPECTEST_LLVM_COV: `${tools}/llvm-cov`, SPECTEST_LLVM_PROFDATA: `${tools}/llvm-profdata` };
+    const launch = () => Bun.spawn([`${root}/server`], { cwd: root, env, stdin: "pipe", stdout: "pipe", stderr: "pipe" });
+    child = launch();
+    let reader = (child.stdout as ReadableStream<Uint8Array>).getReader();
+    const ready = new TextDecoder().decode((await reader.read()).value);
+    if (!ready.includes("ready")) throw new Error(await new Response(child.stderr).text());
+    const context = { service: "rust", reportDir: `${root}/reports`, signal: AbortSignal.timeout(10000),
+      exec: async () => ({ stdout: "", stderr: "" }), writeReport: async () => {}, projectFiles: async () => [], readProjectFile: async () => null };
+    const capture = (baseline = false) => captureCoverageTarget({ context, coverage: { adapters: [rust()] }, root, baseline });
+    const setup = await capture(true);
+    expect(setup.error).toBeUndefined();
+    (child.stdin as { write(value: string): void }).write("left\n");
+    expect(new TextDecoder().decode((await reader.read()).value)).toContain("41");
+    const changed = await capture();
+    if (process.env.SPECTEST_RUNTIME_COVERAGE_EVIDENCE) {
+      const output = path.join(process.env.SPECTEST_RUNTIME_COVERAGE_EVIDENCE, "rust");
+      await fs.mkdir(output, { recursive: true });
+      await fs.writeFile(path.join(output, "setup.json.gz"), encodeCoverageBundle("__setup__", [setup]));
+      await fs.writeFile(path.join(output, "left.json.gz"), encodeCoverageBundle("left", [changed]));
+      await fs.writeFile(path.join(output, "tree.txt"), "main.rs\n");
+      await fs.writeFile(path.join(output, "lines.json"), JSON.stringify({ "main.rs": 14 }));
+    }
+    expect(changed.error).toBeUndefined();
+    expect(changed.reports.map(r => r.content).join()).toMatch(/DA:4,[1-9]/);
+    const idle = await capture();
+    expect(idle.error).toBeUndefined();
+    expect(idle.reports.map(r => r.content).join()).toBe("TN:\n");
+    (child.stdin as { end(): void }).end();
+    expect(await child.exited).toBe(0);
+    expect((await capture()).error).toBeUndefined();
+    // A new process has a unique profile, even if the old PID is reused.
+    child = launch();
+    reader = (child.stdout as ReadableStream<Uint8Array>).getReader();
+    expect(new TextDecoder().decode((await reader.read()).value)).toContain("ready");
+    child.kill("SIGKILL");
+    await child.exited;
+    expect((await capture()).error).toContain("without a final report");
+  } finally { child?.kill(); await fs.rm(root, { recursive: true, force: true }); }
+}, 30000);

package/src/coverage-rust.ts

@@ -0,0 +1,79 @@
+import { promises as fs, readFileSync } from "node:fs";
+import path from "node:path";
+import { connect } from "node:net";
+import type { CoverageAdapter, CoverageSourceOptions } from "./coverage.js";
+
+export interface RustCoverageOptions extends CoverageSourceOptions {
+  /** Only for idle command containers where no Rust process has run yet. */
+  allowEmpty?: boolean;
+  /** Compiler workspace directory, when different from the runtime workdir.
+   * Exact SF paths below it are made repository-relative before archiving. */
+  buildRoot?: string;
+  /** Matching rustup llvm-tools-preview executables, in the runtime image. */
+  llvmCov?: string;
+  llvmProfdata?: string;
+  /** LLVM filename regex for external/generated sources, not application code. */
+  ignoreFilenameRegex?: string;
+}
+
+/** Source for a test-build-only module, copied as spectest-coverage.rs. The
+ * application links only this std-only helper, never the JavaScript SDK. */
+export function rustHelperSource(): string {
+  return readFileSync(new URL("./coverage/rust.rs", import.meta.url), "utf8");
+}
+
+/** Flush a socket-backed collector. A dead process without a final flush is
+ * incomplete coverage, never an empty successful report. */
+export async function flushCoverageSockets(dir: string, prefix: string, signal: AbortSignal): Promise<number> {
+  const names = (await fs.readdir(dir)).filter(name => name.startsWith(prefix));
+  for (const name of names) {
+    signal.throwIfAborted();
+    await new Promise<void>((resolve, reject) => {
+      const socket = connect(path.join(dir, name), () => socket.end("dump\n"));
+      let reply = "";
+      const abort = () => socket.destroy(new Error(`coverage flush aborted: ${name}`));
+      signal.addEventListener("abort", abort, { once: true });
+      socket.setTimeout(55_000, () => socket.destroy(new Error(`coverage flush timed out: ${name}`)));
+      socket.on("data", chunk => { reply += chunk; if (reply.length > 8192) socket.destroy(new Error("oversized coverage reply")); });
+      socket.on("error", error => reject(new Error(`coverage process ${name} exited without a final report or could not be reached: ${error.message}`)));
+      socket.on("close", () => {
+        signal.removeEventListener("abort", abort);
+        if (reply.trim() === "ok") resolve();
+        else reject(new Error(`coverage process ${name} did not flush: ${reply.trim() || "process exited without a final report"}`));
+      });
+    });
+  }
+  return names.length;
+}
+
+/** Requires instrumented binaries calling the shipped coverage/rust.rs helper.
+ * The helper exports cumulative per-process LCOV before exit and on request;
+ * no compiler tools or binaries need to be copied out of terminated pods. */
+export function rust(options: RustCoverageOptions = {}): CoverageAdapter {
+  const { sourceRoot, excludeSources, llvmCov, llvmProfdata, ignoreFilenameRegex, buildRoot } = options;
+  if (buildRoot !== undefined && (!buildRoot.startsWith("/") || buildRoot === "/" || /[\0\r\n]/.test(buildRoot) || buildRoot.split("/").includes(".."))) throw new Error("Rust buildRoot must be an absolute compiler workspace directory");
+  for (const value of [llvmCov, llvmProfdata, ignoreFilenameRegex]) {
+    if (value !== undefined && (!value || /[\0\r\n]/.test(value))) throw new Error("invalid Rust coverage option");
+  }
+  return {
+    name: "rust", reports: "cumulative",
+    sourceOptions: { ...(sourceRoot !== undefined ? { sourceRoot } : {}), ...(excludeSources ? { excludeSources } : {}) },
+    ownsReport: name => /^rust-.*\.lcov$/.test(name),
+    configure: service => ({ ...service, env: { ...service.env,
+      SPECTEST_COVERAGE_DIR: "/spectest/coverage",
+      ...(buildRoot ? { SPECTEST_RUST_BUILD_ROOT: buildRoot } : {}),
+      ...(llvmCov ? { SPECTEST_LLVM_COV: llvmCov } : {}),
+      ...(llvmProfdata ? { SPECTEST_LLVM_PROFDATA: llvmProfdata } : {}),
+      ...(ignoreFilenameRegex ? { SPECTEST_RUST_IGNORE: ignoreFilenameRegex } : {}),
+    } }),
+    async capture(ctx) {
+      await flushCoverageSockets(ctx.reportDir, ".rust-ctl-", ctx.signal);
+      const names = await fs.readdir(ctx.reportDir);
+      if (names.some(name => name.startsWith("rust-error-"))) throw new Error("Rust coverage helper failed; inspect rust-error report");
+      if (!names.some(name => /^rust-.*\.lcov$/.test(name))) {
+        if (options.allowEmpty) { await ctx.writeReport("rust-empty.lcov", "TN:\n"); return; }
+        throw new Error("no Rust coverage reports: build with -C instrument-coverage and call spectest_coverage::start() before application work");
+      }
+    },
+  };
+}

package/src/coverage.test.ts

@@ -540,7 +540,7 @@ describe.if(hasNode)("nodeCoverage hook (real node)", () => {
     const names = await dumpsIn(dir);
     expect(names.length).toBe(2);
     const byThread = new Map<string, Dump>();
-    for (const n of names) byThread.set(n.split("-")[2]!, await readDump(dir, n));
+    for (const n of names) byThread.set(n.split("-")[3]!, await readDump(dir, n));
     const recs = await records(dir);
     expect(recs.size).toBe(1); // one script, one record, whichever thread came first
     const rec = recs.get(`file://${path.join(dir, "threads.js")}`)!;
@@ -600,14 +600,14 @@ describe.if(hasNode)("nodeCoverage hook (real node)", () => {
     expect(out.trim().split("\n")).toEqual(["npm:@s/b@2.0.0", "npm:a@1.0.0", "npm:c@3.0.0", "npm:d@4.0.0", "npm:e", "npm:f@6.0.0"]);
   });
 
-  test("a stale socket left by a killed process is removed at capture", async () => {
+  test("a killed covered process makes capture incomplete instead of silently losing execution", async () => {
     const dir = await scratch();
     const server = await start(dir, "server.js", 1);
     server.kill("SIGKILL");
     await new Promise<void>((r) => server.on("exit", () => r()));
     expect((await socketsIn(dir)).length).toBe(1); // SIGKILL: no exit handler, socket left behind
-    await node().capture!(fakeCtx(dir));
-    expect((await socketsIn(dir)).length).toBe(0);
+    await expect(node().capture!(fakeCtx(dir))).rejects.toThrow("without a final report");
+    expect((await socketsIn(dir)).length).toBe(1);
   });
 
   test("no process and no dump: an empty report is written, once", async () => {

package/src/coverage.ts

@@ -36,6 +36,8 @@ import { harvestAllBrowserCoverage, takeBrowserCoverageReport } from "./browser-
 import { COVERAGE_CONTAINER_DIR, type CoverageReportsMode } from "./harness/coverage.js";
 export { COVERAGE_CONTAINER_DIR, type CoverageReportsMode };
 export { next, type NextCoverageOptions } from "./coverage-next.js";
+export { bun, type BunCoverageOptions } from "./coverage-bun.js";
+export { rust, rustHelperSource, type RustCoverageOptions } from "./coverage-rust.js";
 
 /** Where `node()` mounts its hook inside the container. */
 export const NODE_COVERAGE_HOOK_PATH = "/spectest/coverage-hook.cjs";
@@ -44,7 +46,7 @@ export const NODE_COVERAGE_HOOK_PATH = "/spectest/coverage-hook.cjs";
 export const NODE_COVERAGE_EMPTY_REPORT = "coverage-spectest-empty.json";
 
 /** Prefix of the per-process sockets the node hook answers on, relative
- *  to the coverage dir: `.ctl-<pid>`. */
+ *  to the coverage dir: `.ctl-<pid>-<nonce>`. */
 export const NODE_COVERAGE_SOCKET_PREFIX = ".ctl-";
 
 
@@ -150,6 +152,10 @@ export interface CoverageAdapter {
   load?(ctx: CoverageLoadContext): void | Promise<void>;
   /** Make the report appear in the directory. A throw fails the test. */
   capture?(ctx: CoverageCaptureContext): void | Promise<void>;
+  /** Component-owned containers (for example k3s pods). Their reports retain
+   * their own source roots and counter baselines, rather than the outer
+   * service's filesystem identity. Internal: ordinary adapters use capture. */
+  collect?(ctx: CoverageInventoryContext & CoverageCaptureContext, baseline: boolean): Promise<import("./harness/coverage.js").ServiceCoverageCapture[]>;
   /**
    * Project paths (gitignore-style patterns, project-relative) whose
    * changes this adapter's **inventory** accounts for — a package
@@ -245,7 +251,7 @@ export function validateCoverage(service: string, cov: unknown): void {
         ((a as CoverageAdapter).explains === undefined ||
           (Array.isArray((a as CoverageAdapter).explains) &&
             ((a as CoverageAdapter).explains as unknown[]).every((e) => typeof e === "string"))) &&
-        ["configure", "load", "capture", "inventory", "ownsReport"].every(
+        ["configure", "load", "capture", "collect", "inventory", "ownsReport"].every(
           (k) =>
             (a as Record<string, unknown>)[k] === undefined ||
             typeof (a as Record<string, unknown>)[k] === "function",
@@ -398,7 +404,7 @@ export const NODE_COVERAGE_DUMP_PREFIX = "node-";
  *   without `--enable-source-maps`. For a bundled CLI that was 12 MB per
  *   invocation, inside the test's own time, parsed again at capture.
  * - **Takes** on request — the main thread binds a Unix socket
- *   `.ctl-<pid>` in the coverage directory and takes on `dump\n`; every
+ *   `.ctl-<pid>-<nonce>` in the coverage directory and takes on `dump\n`; every
  *   process binds its own (the first node process is often a wrapper,
  *   `pnpm exec`, `tsx`, `npm run`) — and in every thread's `exit`
  *   handler, which is how a short-lived CLI and a worker thread report.
@@ -448,6 +454,7 @@ export const NODE_COVERAGE_HOOK = `"use strict";
 (function () {
   const dir = process.env[${JSON.stringify(NODE_COVERAGE_DIR_ENV)}];
   if (!dir) return;
+  const bunRuntime = !!process.versions.bun && process.env.SPECTEST_COVERAGE_RUNTIME === "bun";
   let inspector, fs, path, crypto, url, wt, net;
   try {
     inspector = require("node:inspector");
@@ -468,19 +475,46 @@ export const NODE_COVERAGE_HOOK = `"use strict";
   }
   // An in-process session answers before post() returns.
   function post(method, params) {
+    // Bun's callback API queues a microtask, including during process exit.
+    // Its synchronous return API is necessary for short-lived commands.
+    if (bunRuntime) return session.post(method, params || {});
     let out = null;
     session.post(method, params || {}, function (err, res) {
       out = err ? null : res;
     });
     return out;
   }
-  if (post("Profiler.enable") === null) return;
-  post("Profiler.startPreciseCoverage", { callCount: true, detailed: true });
+  fs.mkdirSync(dir, { recursive: true });
+  function fail(error) {
+    fs.writeFileSync(path.join(dir, "coverage-error-" + process.pid + ".txt"), String(error));
+  }
+  try {
+    if (post("Profiler.enable") === null) throw new Error("coverage profiler unavailable");
+    if (!post("Profiler.startPreciseCoverage", { callCount: true, detailed: true })) throw new Error("precise coverage unavailable");
+    if (bunRuntime && (!process.versions.bun || !wt.isMainThread)) throw new Error("Bun coverage requires a supported main-thread runtime");
+  } catch (error) { fail(error); throw error; }
+  let bunRangeAdjustment = 0;
+  if (bunRuntime) {
+    // Bun releases have exposed both JSC-inclusive and V8-exclusive range
+    // ends. Probe the actual runtime before app code loads: interpreting an
+    // inclusive closing brace as exclusive attributes its source-map token
+    // to startup, making untouched function bodies appear boot-executed.
+    const probe = "let x=0;\\nfunction spectestCoverageProbe(){return 1;}\\nspectestCoverageProbe();\\n//# sourceURL=spectest-coverage-probe";
+    eval(probe);
+    const measured = post("Profiler.takePreciseCoverage");
+    const script = measured && measured.result.find(s => s.url === "spectest-coverage-probe");
+    const fn = script && script.functions.find(f => f.ranges[0].startOffset === probe.indexOf("function"));
+    if (!fn) { const error = new Error("Bun precise coverage capability probe failed"); fail(error); throw error; }
+    bunRangeAdjustment = probe.indexOf("}") + 1 - fn.ranges[0].endOffset;
+    if (bunRangeAdjustment !== 0 && bunRangeAdjustment !== 1) {
+      const error = new Error("unsupported Bun coverage range semantics"); fail(error); throw error;
+    }
+  }
 
   // Attach before app scripts execute. Enabling only at capture loses the
   // source of collected vm contexts (e.g. Temporal workflow bundles).
   // Bound V8's collected-script cache; live sources remain owned by V8.
-  post("Debugger.enable", { maxScriptsCacheSize: 16 * 1024 * 1024 });
+  if (!bunRuntime) post("Debugger.enable", { maxScriptsCacheSize: 16 * 1024 * 1024 });
 
   const GENERATED = new Map();
   try {
@@ -499,6 +533,10 @@ export const NODE_COVERAGE_HOOK = `"use strict";
   // can be reused by another process, vm context, or compilation.
   const known = new Map();
   let seq = 0;
+  const processToken = process.pid + "-" + crypto.randomBytes(6).toString("hex");
+  const liveMarker = path.join(dir, ".live-" + processToken + "-" + wt.threadId);
+  fs.writeFileSync(liveMarker, "");
+  fs.writeFileSync(path.join(dir, ".attached-" + (bunRuntime ? "bun" : "node")), "");
 
   function isApp(u) {
     return typeof u === "string" && u.startsWith("file://") && u.indexOf("/node_modules/") < 0 && u.indexOf("/.cache/") < 0 && u !== SELF;
@@ -674,6 +712,12 @@ export const NODE_COVERAGE_HOOK = `"use strict";
     const kept = [];
     const units = new Set();
     for (const s of res.result) {
+      if (bunRuntime && bunRangeAdjustment && Array.isArray(s.functions)) {
+        const length = Math.max(...s.functions.flatMap(f => f.ranges.map(r => r.endOffset)));
+        for (const f of s.functions) for (const range of f.ranges) {
+          if (range.endOffset < length) range.endOffset += bunRangeAdjustment;
+        }
+      }
       if (!Array.isArray(s.functions) || !s.functions.some(ran)) continue;
       if (isApp(s.url)) kept.push(s);
       else if (isDep(s.url)) {
@@ -695,7 +739,18 @@ export const NODE_COVERAGE_HOOK = `"use strict";
         fs.mkdirSync(MARKERS, { recursive: true });
       } catch (e) {}
       for (const s of fresh) {
-        const r = post("Debugger.getScriptSource", { scriptId: s.scriptId });
+        let r;
+        if (bunRuntime) {
+          // Bun does not expose getScriptSource through the in-process API.
+          // Accept only precompiled, untranspiled bundles, never guess that
+          // disk TypeScript offsets describe executed JavaScript.
+          const source = fs.readFileSync(url.fileURLToPath(s.url), "utf8");
+          const extent = Math.max(...s.functions.flatMap(f => f.ranges.map(r => r.endOffset)));
+          if (!source.startsWith("// @bun\\n") || source.length !== extent) {
+            throw new Error("Bun coverage needs an unchanged bun build --target=bun bundle with source maps: " + s.url);
+          }
+          r = { scriptSource: source };
+        } else r = post("Debugger.getScriptSource", { scriptId: s.scriptId });
         try {
           const source = r && r.scriptSource;
           if (GENERATED.has(s.url) && typeof source === "string") {
@@ -737,12 +792,12 @@ export const NODE_COVERAGE_HOOK = `"use strict";
         };
       }),
     };
-    const name = ${JSON.stringify(NODE_COVERAGE_DUMP_PREFIX)} + process.pid + "-" + wt.threadId + "-" + Date.now() + "-" + seq++ + ".json";
+    const name = ${JSON.stringify(NODE_COVERAGE_DUMP_PREFIX)} + processToken + "-" + wt.threadId + "-" + Date.now() + "-" + seq++ + ".json";
     writeAtomic(path.join(dir, name), JSON.stringify(doc));
   }
 
   if (wt.isMainThread) {
-    const SOCK = path.join(dir, ${JSON.stringify(NODE_COVERAGE_SOCKET_PREFIX)} + process.pid);
+    const SOCK = path.join(dir, ${JSON.stringify(NODE_COVERAGE_SOCKET_PREFIX)} + processToken);
     const server = net.createServer(function (conn) {
       let buf = "";
       conn.on("data", function (chunk) {
@@ -754,6 +809,7 @@ export const NODE_COVERAGE_HOOK = `"use strict";
           take();
           reply = "ok\\n";
         } catch (err) {
+          fail(err);
           reply = "error " + (err && err.message ? err.message : String(err)) + "\\n";
         }
         conn.end(reply);
@@ -774,7 +830,8 @@ export const NODE_COVERAGE_HOOK = `"use strict";
   process.on("exit", function () {
     try {
       take();
-    } catch (e) {}
+      fs.unlinkSync(liveMarker);
+    } catch (e) { fail(e); }
   });
 })();
 `;
@@ -992,9 +1049,9 @@ export function node(options: NodeCoverageOptions = {}): CoverageAdapter {
 
 /**
  * Ask every node process that holds a hook socket in `dir` for a dump.
- * A socket nobody answers (its process died without unlinking — SIGKILL,
- * OOM) is removed. Returns how many processes answered; a process that
- * answered with an error throws.
+ * An unanswered socket with a live marker means the process died without
+ * a final report and fails collection. Stale sockets without live markers
+ * are removed. Returns how many processes answered; error replies throw.
  */
 export async function dumpAllNodeProcesses(dir: string, signal: AbortSignal): Promise<number> {
   const fs = await import("node:fs/promises");
@@ -1029,6 +1086,10 @@ export async function dumpAllNodeProcesses(dir: string, signal: AbortSignal): Pr
       });
     });
     if (reply === null) {
+      const pid = name.slice(NODE_COVERAGE_SOCKET_PREFIX.length);
+      if ((await fs.readdir(dir)).some(marker => marker.startsWith(".live-" + pid + "-"))) {
+        throw new Error(`coverage process ${name} exited without a final report`);
+      }
       // Nobody home: the process is gone. Clean up so the next capture
       // does not knock again.
       await fs.unlink(sock).catch(() => {});

package/src/daemon.ts

@@ -3873,7 +3873,11 @@ async function captureServiceCoverage(baseline = false): Promise<ServiceCoverage
   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 all = [...byName.values()];
-  const services = all.filter((s) => s.coverage !== undefined);
+  const covered = all.filter((s) => s.coverage !== undefined);
+  const services = covered.filter(s => {
+    const adapters = coverageAdapters(s.coverage);
+    return !adapters.some(a => a.collect) || adapters.some(a => !a.collect);
+  });
   // The environment's own capture is unconditional (see above); the
   // services' come from the ones that opted in, none included.
   const environment = captureEnvironmentCoverage(all, baseline);
@@ -3922,7 +3926,23 @@ async function captureServiceCoverage(baseline = false): Promise<ServiceCoverage
       return applyCoverageDelta(read, coverageReportsMode(svc.coverage), deltaReports);
     }),
   );
-  return [...captures, await environment];
+  const components = await Promise.all(covered.flatMap(svc => coverageAdapters(svc.coverage)
+    .filter(a => a.collect).map(async adapter => {
+      const signal = AbortSignal.timeout(COVERAGE_CAPTURE_TIMEOUT_MS);
+      try {
+        return await adapter.collect!({
+          ...coverageCaptureContext(svc, signal, new Set()),
+          projectFiles: () => walkProjectFiles(WORKSPACE),
+          async readProjectFile(p) {
+            try { return await fs.readFile(resolveProjectPath(p, { record: false }), "utf8"); }
+            catch { return null; }
+          },
+        }, baseline);
+      } catch (error) {
+        return [{ service: `${svc.name}/${adapter.name}`, reports: [], error: String(error) }];
+      }
+    })));
+  return [...captures, ...components.flat(), await environment];
 }
 
 /** Per-Browser rrweb session shipped to the control plane. */

package/src/harness/component-images.ts

@@ -1,7 +1,7 @@
 import { createHash } from "node:crypto";
 import type { BuildImage, ComponentImageBuild, ServiceConfig } from "../index.js";
 
-export type KubernetesImage = string | (BuildImage & { reference: string });
+export type KubernetesImage = string | (BuildImage & { reference: string; coverage?: import("../coverage.js").ServiceCoverage });
 
 /** containerd/CRI use fully qualified names, including the default tag. */
 export function canonicalImageReference(reference: string): string {
@@ -45,7 +45,10 @@ export function kubernetesImages(images: readonly KubernetesImage[]): { pulls: s
     }
     seen.set(reference, identity);
     if (typeof image === "string") pulls.push(image);
-    else builds.push({ reference, image });
+    else {
+      const { coverage: _coverage, ...build } = image;
+      builds.push({ reference, image: image.coverage === undefined ? image : build });
+    }
   }
   return { pulls, builds };
 }

package/src/harness/coverage-target.ts

@@ -0,0 +1,55 @@
+// Runtime adapters operate on this same context in Docker and nested runtimes.
+// Counter baselines belong to an instance; source identity belongs to its image.
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { attachCoverageSourceOptions, coverageAdapters, coverageReportsMode, resolveCoverageSourceOptions,
+  type CoverageCaptureContext, type CoverageInventoryContext, type ServiceCoverage } from "../coverage.js";
+import { applyCoverageDelta, readCoverageDir, type ServiceCoverageCapture } from "./coverage.js";
+
+export async function captureCoverageTarget(options: {
+  context: CoverageCaptureContext & CoverageInventoryContext;
+  coverage: ServiceCoverage;
+  root: string;
+  baseline: boolean;
+  inventoryAvailable?: boolean;
+  counterKey?: string;
+}): Promise<ServiceCoverageCapture> {
+  const { context: ctx, coverage, root, baseline } = options;
+  const adapters = coverageAdapters(coverage);
+  const written = new Set<string>();
+  const delta = new Set<string>();
+  const context = { ...ctx, async writeReport(name: string, content: string) {
+    const resolved = path.resolve(ctx.reportDir, name);
+    if (!resolved.startsWith(path.resolve(ctx.reportDir) + path.sep)) throw new Error("coverage report escapes directory");
+    await fs.mkdir(path.dirname(resolved), { recursive: true });
+    await fs.writeFile(resolved + ".tmp", content);
+    await fs.rename(resolved + ".tmp", resolved);
+    written.add(name);
+  } };
+  try {
+    ctx.signal.throwIfAborted();
+    const policies = await resolveCoverageSourceOptions(adapters, ctx, typeof coverage === "object" ? {
+      sourceRoot: coverage.sourceRoot, excludeSources: coverage.excludeSources,
+    } : undefined);
+    for (const adapter of adapters) {
+      if (adapter.collect || adapter.load) throw new Error(`adapter ${adapter.name} cannot run inside a container; attach browser coverage to the cluster service`);
+      written.clear();
+      await adapter.capture?.(context);
+      if (adapter.reports === "delta") for (const name of written) delta.add(name);
+    }
+    if (baseline && options.inventoryAvailable !== false) {
+      const units = new Set<string>();
+      for (const adapter of adapters) for (const unit of await adapter.inventory?.(context) ?? []) units.add(unit);
+      await context.writeReport("inventory.units", [...units].sort().join("\n"));
+    }
+    ctx.signal.throwIfAborted();
+    const capture = await readCoverageDir(ctx.service, ctx.reportDir);
+    if (baseline) await fs.rm(path.join(ctx.reportDir, "inventory.units"), { force: true });
+    capture.root = root;
+    attachCoverageSourceOptions(capture, policies);
+    const result = applyCoverageDelta({ ...capture, service: options.counterKey ?? capture.service }, coverageReportsMode(coverage), delta);
+    return { ...result, service: capture.service };
+  } catch (error) {
+    return { service: ctx.service, reports: [], error: String(error) };
+  }
+}

package/src/index.ts

@@ -175,7 +175,7 @@ export {
   type CoverageLoadContext,
   type ServiceCoverage,
 } from "./coverage.js";
-import { applyCoverageAdapters, validateCoverage, type ServiceCoverage } from "./coverage.js";
+import { applyCoverageAdapters, coverageAdapters, validateCoverage, type ServiceCoverage } from "./coverage.js";
 import { resolveExistingProjectPath } from "./project-files.js";
 export { ca } from "./environment-ca.js";
 
@@ -1138,6 +1138,15 @@ function expandServiceGroups(input: InputServicesMap): ServicesMap {
       // Rewrite relative dependsOn to final keys; a spread keeps function
       // fields (helpers/setup) and the enumerable-symbol ingress decls.
       const final: ServiceConfig = { ...svc, ...(part === entry.primary ? primaryOverrides : {}) };
+      // Component-owned nested containers keep their collection when callers
+      // add ordinary service coverage (for example browser coverage on k3s).
+      const collectors = coverageAdapters(svc.coverage).filter(adapter => adapter.collect);
+      if (part === entry.primary && collectors.length && primaryOverrides.coverage !== undefined) {
+        const extra = primaryOverrides.coverage;
+        final.coverage = { ...(typeof extra === "object" ? extra : {}), adapters: [
+          ...collectors, ...coverageAdapters(extra).filter(adapter => !collectors.includes(adapter)),
+        ] };
+      }
       if (final.dependsOn?.length) {
         final.dependsOn = final.dependsOn.map((d) =>
           partKeys.has(d) ? naming.key(d) : d,