@specific.dev/spectest 0.127.0 → 0.128.0

package/src/components/k3s-coverage.ts

@@ -0,0 +1,234 @@
+import { createHash } from "node:crypto";
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { applyCoverageAdapters, coverageAdapters, type CoverageAdapter, type ServiceCoverage } from "../coverage.js";
+import { coverageHostDir, COVERAGE_MAX_BYTES_PER_SERVICE, type ServiceCoverageCapture } from "../harness/coverage.js";
+import { captureCoverageTarget } from "../harness/coverage-target.js";
+import { canonicalImageReference, type KubernetesImage } from "../harness/component-images.js";
+import type { ServiceConfig } from "../index.js";
+import { WORKSPACE } from "../project-files.js";
+import type { Patch, Pod } from "./k3s-trust.js";
+
+const MOUNT = "/spectest/pod-coverage";
+const ANNOTATION = "spectest.dev/coverage";
+const hash = (value: string) => createHash("sha256").update(value).digest("hex").slice(0, 16);
+const quote = (value: string) => "'" + value.replaceAll("'", "'\\''") + "'";
+interface ImageInfo { aliases: string[]; root: string; env: Record<string, string> }
+interface Instance { id: string; image: string; container: string; root: string; namespace: string }
+interface Container {
+  name: string; image: string; workingDir?: string;
+  env?: { name: string; value?: string; valueFrom?: unknown }[];
+  volumeMounts?: { name: string; mountPath: string; [key: string]: unknown }[];
+}
+interface CoveragePod {
+  metadata?: { name?: string; annotations?: Record<string, string> };
+  spec?: { containers?: Container[]; initContainers?: Container[]; volumes?: { name: string; [key: string]: unknown }[] };
+  status?: { containerStatuses?: { name: string; state?: { running?: unknown } }[]; initContainerStatuses?: { name: string; state?: { running?: unknown } }[] };
+}
+export interface K3sCoverageDependencies {
+  image(reference: string): Promise<ImageInfo>;
+  files(namespace: string, name: string, data: Record<string, string>): Promise<void>;
+}
+
+/** One component-owned bridge; runtime adapters remain unaware of Kubernetes. */
+export function k3sCoverage(images: readonly KubernetesImage[]) {
+  const declarations = images.flatMap(image => typeof image === "string" || image.coverage === undefined ? [] : [{
+    reference: canonicalImageReference(image.reference), coverage: image.coverage,
+  }]);
+  for (const image of declarations) {
+    const adapters = coverageAdapters(image.coverage);
+    if (adapters.some(adapter => adapter.load || adapter.collect)) throw new Error("k3s image coverage accepts container adapters; put browser coverage on the cluster service");
+    applyCoverageAdapters(image.reference, { image: { type: "registry", reference: image.reference }, coverage: image.coverage });
+  }
+  const metadata = new Map<string, ImageInfo>();
+  const service = (cluster: string, reference: string) => `${cluster}/image-${hash(reference)}`;
+  return {
+    enabled: declarations.length > 0,
+    volume(cluster: string) {
+      return { source: coverageHostDir(WORKSPACE, cluster), target: MOUNT, reachExempt: true };
+    },
+    async mutate(cluster: string, podInput: Pod, namespace: string, dryRun: boolean, ephemeral: boolean, uid: string, deps: K3sCoverageDependencies): Promise<Patch[]> {
+      if (!declarations.length || ephemeral) return [];
+      const pod = podInput as CoveragePod;
+      if (!pod.spec) return [];
+      const existing = pod.metadata?.annotations?.[ANNOTATION];
+      if (existing) {
+        if (JSON.parse(existing).admission === uid) return [];
+        throw new Error("remove inherited spectest.dev/coverage annotations before creating another Pod");
+      }
+      const patch: Patch[] = [];
+      const volumes = [...(pod.spec.volumes ?? [])];
+      const instances: Instance[] = [];
+      const namedVolume = (stem: string, volume: Record<string, unknown>) => {
+        let name = stem;
+        for (let i = 1; volumes.some(v => v.name === name); i++) name = `${stem}-${i}`;
+        volumes.push({ name, ...volume }); return name;
+      };
+      for (const group of ["initContainers", "containers"] as const) {
+        for (const [index, container] of (pod.spec[group] ?? []).entries()) {
+          const requested = canonicalImageReference(container.image);
+          let declaration = declarations.find(image => image.reference === requested);
+          // Tangent deploys the prepared image by digest. Resolve aliases from
+          // CRI's actual image record, never by stripping a repository tag.
+          if (!declaration && requested.includes("@")) {
+            for (const candidate of declarations) {
+              let info = metadata.get(candidate.reference);
+              if (!info) metadata.set(candidate.reference, info = await deps.image(candidate.reference));
+              if (info.aliases.includes(requested)) { declaration = candidate; break; }
+            }
+          }
+          if (!declaration) continue;
+          let info = metadata.get(declaration.reference);
+          if (!info) metadata.set(declaration.reference, info = await deps.image(declaration.reference));
+          const id = hash(`${uid}/${group}/${container.name}`);
+          const name = service(cluster, declaration.reference);
+          const env = { ...info.env };
+          for (const entry of container.env ?? []) if (entry.value !== undefined) env[entry.name] = entry.value;
+          const configured = applyCoverageAdapters<ServiceConfig>(name, { image: { type: "registry", reference: container.image }, env, coverage: declaration.coverage });
+          if (Object.keys(configured).some(key => !["image", "env", "coverage", "files"].includes(key))) {
+            throw new Error("Kubernetes coverage adapters may inject env and files only; configure the workload's command and mounts in its manifest");
+          }
+          const changed = Object.entries(configured.env ?? {}).filter(([key, value]) => env[key] !== value);
+          for (const [key] of changed) if (container.env?.some(e => e.name === key && e.valueFrom)) throw new Error(`cannot inject coverage into dynamic ${key}`);
+          const mounts = [...(container.volumeMounts ?? [])];
+          const addMount = (mountPath: string, mount: Record<string, unknown>) => {
+            if (mounts.some(m => mountPath === m.mountPath || mountPath.startsWith(m.mountPath.replace(/\/$/, "") + "/"))) throw new Error(`coverage mount conflicts with ${mountPath}`);
+            mounts.push({ mountPath, ...mount } as typeof mounts[number]);
+          };
+          const volume = namedVolume(`spectest-cov-${id}`, { hostPath: { path: `${MOUNT}/.pods/${id}`, type: "Directory" } });
+          addMount("/spectest/coverage", { name: volume });
+          const files = configured.files ?? [];
+          if (files.some(file => file.user !== undefined || file.group !== undefined || (file.mode !== undefined && !["444", "0444", "644", "0644"].includes(file.mode)))) {
+            throw new Error("Kubernetes coverage hook files must be world-readable and need no custom ownership");
+          }
+          if (files.length) {
+            const data = Object.fromEntries(files.map((file, index) => [`file${index}`, file.content]));
+            const configMap = `spectest-coverage-${hash(JSON.stringify(data))}`;
+            if (!dryRun) await deps.files(namespace, configMap, data);
+            const fileVolume = namedVolume(`spectest-hooks-${id}`, { configMap: { name: configMap, defaultMode: 0o444 } });
+            files.forEach((file, index) => addMount(file.path, { name: fileVolume, subPath: `file${index}`, readOnly: true }));
+          }
+          const instance: Instance = { id, image: declaration.reference, namespace, container: container.name, root: container.workingDir || info.root || "/" };
+          if (!dryRun) {
+            const dir = path.join(coverageHostDir(WORKSPACE, cluster), ".pods", id);
+            await fs.mkdir(dir, { recursive: true, mode: 0o777 });
+            await fs.chmod(dir, 0o777);
+            await fs.writeFile(path.join(dir, ".instance.json"), JSON.stringify(instance));
+          }
+          instances.push(instance);
+          patch.push({ op: "add", path: `/spec/${group}/${index}/env`, value: [
+            ...(container.env ?? []).filter(e => !changed.some(([key]) => key === e.name)),
+            ...changed.map(([name, value]) => ({ name, value })),
+          ] }, { op: "add", path: `/spec/${group}/${index}/volumeMounts`, value: mounts });
+        }
+      }
+      if (!instances.length) return [];
+      patch.push({ op: "add", path: "/spec/volumes", value: volumes });
+      patch.push({ op: "add", path: "/metadata/annotations", value: { ...pod.metadata?.annotations,
+        [ANNOTATION]: JSON.stringify({ admission: uid, instances: instances.map(i => i.id) }),
+      } });
+      return patch;
+    },
+    adapter(): CoverageAdapter {
+      return {
+        name: "k3s-containers",
+        // Include nested policy AND injected hooks in the warm identity. An
+        // adapter's functions would otherwise disappear from JSON.stringify.
+        toJSON() { return { adapter: "k3s-containers", images: declarations.map(image => ({
+          reference: image.reference,
+          config: applyCoverageAdapters(image.reference, { image: { type: "registry", reference: image.reference }, coverage: image.coverage }),
+        })) }; },
+        async collect(ctx, baseline) {
+          const root = path.join(ctx.reportDir, ".pods");
+          let entries: string[];
+          try { entries = await fs.readdir(root); } catch (error: any) { if (error.code !== "ENOENT") throw error; entries = []; }
+          // Native adapters flush through the shared Unix sockets, including
+          // after Pod deletion. Only inventory or command adapters need the API.
+          let pods: Promise<CoveragePod[]> | undefined;
+          const findPod = async (id: string) => {
+            pods ??= ctx.exec("kubectl get pods -A -o json --request-timeout=10s")
+              .then(result => JSON.parse(result.stdout).items as CoveragePod[]);
+            return (await pods).find(p => {
+              const ids = p.metadata?.annotations?.[ANNOTATION];
+              return ids && (JSON.parse(ids).instances as string[]).includes(id);
+            });
+          };
+          const captures = new Map<string, ServiceCoverageCapture>();
+          const inventories = new Map<string, Set<string>>();
+          for (const declaration of declarations) captures.set(declaration.reference, { service: service(ctx.service, declaration.reference), reports: [] });
+          const collectInstance = async (id: string) => {
+            ctx.signal.throwIfAborted();
+            if (!/^[a-f0-9]{16}$/.test(id)) throw new Error("invalid coverage instance directory");
+            const dir = path.join(root, id);
+            const instance = JSON.parse(await fs.readFile(path.join(dir, ".instance.json"), "utf8")) as Instance;
+            const declaration = declarations.find(d => d.reference === instance.image);
+            if (!declaration) throw new Error(`coverage image no longer declared: ${instance.image}`);
+            const adapters = coverageAdapters(declaration.coverage);
+            const livePod = async () => {
+              const pod = await findPod(id);
+              const statuses = [...(pod?.status?.containerStatuses ?? []), ...(pod?.status?.initContainerStatuses ?? [])];
+              return statuses.some(status => status.name === instance.container && status.state?.running) ? pod : undefined;
+            };
+            for (const adapter of adapters) {
+              if (adapter.name === "node") {
+                try { await fs.access(path.join(dir, `.attached-${adapter.name}`)); }
+                catch { throw new Error(`coverage hook never attached to ${instance.namespace}/${instance.container} (${adapter.name})`); }
+              }
+            }
+            const captured = await captureCoverageTarget({
+              coverage: declaration.coverage, root: instance.root, baseline,
+              inventoryAvailable: baseline && adapters.some(a => a.inventory) ? !!await livePod() : false,
+              counterKey: `${service(ctx.service, instance.image)}/${id}`,
+              context: { ...ctx, service: service(ctx.service, instance.image), reportDir: dir,
+                exec: async command => {
+                  const pod = await livePod();
+                  if (!pod?.metadata?.name) throw new Error(`coverage command requires live container ${instance.container}`);
+                  return ctx.exec(`kubectl exec -n ${quote(instance.namespace)} ${quote(pod.metadata.name)} -c ${quote(instance.container)} -- sh -c ${quote(command)}`);
+                },
+              },
+            });
+            return { id, instance, captured };
+          };
+          // Bound simultaneous LLVM exports and API execs. Drain all workers
+          // even on error so no collector can race the following VM snapshot.
+          const pending = entries.sort();
+          const results = new Map<string, Awaited<ReturnType<typeof collectInstance>>>();
+          let cursor = 0;
+          const workers = await Promise.allSettled(Array.from({ length: Math.min(8, pending.length) }, async () => {
+            while (cursor < pending.length) {
+              const id = pending[cursor++];
+              results.set(id, await collectInstance(id));
+            }
+          }));
+          const failure = workers.find(worker => worker.status === "rejected");
+          if (failure?.status === "rejected") throw failure.reason;
+          for (const id of pending) {
+            const { instance, captured } = results.get(id)!;
+            const aggregate = captures.get(instance.image)!;
+            if (captured.error) aggregate.error = [aggregate.error, `${instance.namespace}/${instance.container}: ${captured.error}`].filter(Boolean).join("; ");
+            if (aggregate.root && aggregate.root !== instance.root) {
+              aggregate.error = "coverage containers from one image have different working directories; use a common workingDir for this image's covered containers";
+            }
+            aggregate.root = instance.root;
+            for (const report of captured.reports) {
+              if (report.name === "inventory.units") {
+                let units = inventories.get(instance.image);
+                if (!units) inventories.set(instance.image, units = new Set());
+                for (const unit of report.content.split("\n")) if (unit) units.add(unit);
+              } else aggregate.reports.push({ ...report, name: `${id}/${report.name}` });
+            }
+          }
+          for (const [image, units] of inventories) captures.get(image)!.reports.push({ name: "inventory.units", content: [...units].sort().join("\n") });
+          for (const capture of captures.values()) {
+            if (!capture.reports.length && !capture.error) capture.reports.push({ name: "empty.lcov", content: "TN:\n" });
+            if (capture.reports.reduce((bytes, report) => bytes + Buffer.byteLength(report.content), 0) > COVERAGE_MAX_BYTES_PER_SERVICE) {
+              capture.reports = [];
+              capture.error = "Kubernetes image coverage exceeds the per-service report size limit";
+            }
+          }
+          return [...captures.values()];
+        },
+      } as CoverageAdapter;
+    },
+  };
+}

package/src/components/k3s-trust.ts

@@ -14,7 +14,7 @@ interface Container {
   env?: { name: string; value?: string; valueFrom?: unknown }[];
   volumeMounts?: { name: string; mountPath: string; subPath?: string; readOnly?: boolean }[];
 }
-interface Pod {
+export interface Pod {
   metadata?: { annotations?: Record<string, string> };
   spec?: {
     os?: { name: string };
@@ -22,7 +22,7 @@ interface Pod {
     containers?: Container[]; initContainers?: Container[]; ephemeralContainers?: Container[];
   };
 }
-interface Patch { op: "add"; path: string; value: unknown }
+export interface Patch { op: "add"; path: string; value: unknown }
 export const TRUST_OPT_OUT = "spectest.dev/inject-ca";
 
 export function podTrustPatch(pod: Pod, configMap: string, ephemeral = false): Patch[] {
@@ -67,6 +67,8 @@ export interface TrustDependencies {
   /** Ensure this immutable ConfigMap exists in the requesting namespace. */
   ensureBundle(namespace: string, name: string, bundle: string): Promise<void>;
   apply(configuration: unknown): Promise<void>;
+  /** Component-owned pod instrumentation runs after trust patching. */
+  mutatePod?(pod: Pod, namespace: string, dryRun: boolean, ephemeral: boolean, uid: string): Promise<Patch[]>;
 }
 const servers = new Map<string, Server>();
 
@@ -91,6 +93,16 @@ export async function installPodTrust(options: {
         res.writeHead(400).end("invalid Pod admission request"); return;
       }
       const patch = podTrustPatch(request.object, configMap, request.subResource === "ephemeralcontainers");
+      if (deps.mutatePod) {
+        const pod = structuredClone(request.object);
+        for (const operation of patch) {
+          const keys = operation.path.slice(1).split("/");
+          const key = keys.pop()!;
+          const parent = keys.reduce((value: any, key) => value[key], pod as any);
+          if (key === "-") parent.push(operation.value); else parent[key] = operation.value;
+        }
+        patch.push(...await deps.mutatePod(pod, request.namespace, !!request.dryRun, request.subResource === "ephemeralcontainers", request.uid));
+      }
       // Dry runs return the same patch but perform no API writes.
       if (patch.length && !request.dryRun) await deps.ensureBundle(request.namespace, configMap, options.bundle);
       res.setHeader("Content-Type", "application/json");

package/src/components/k3s.ts

@@ -1,6 +1,7 @@
 import { isIP } from "node:net";
 import { waitForK3sNodes } from "./k3s-nodes.js";
 import { installPodTrust } from "./k3s-trust.js";
+import { k3sCoverage } from "./k3s-coverage.js";
 import { waitForAll } from "../harness/concurrency.js";
 import { CONTENT_BLOBS, REGISTRY_CONTENT, REGISTRY_DATA, REGISTRY_IMAGE, registryDirectory, seedRegistry } from "../harness/registry-seed.js";
 import { loadK3sBuildImages } from "../harness/k3s-image-loader.js";
@@ -1969,6 +1970,7 @@ export function k3s(opts: K3sOptions = {}) {
 function createK3sCluster(opts: K3sOptions, count: number) {
   const version = opts.version ?? DEFAULT_K3S_VERSION;
   const images = kubernetesImages(opts.images ?? []);
+  const coverage = k3sCoverage(opts.images ?? []);
   const extra = opts.extraArgs ?? [];
   assertUsableExtraArgs(extra);
   const registryEnabled = opts.registry !== false;
@@ -2132,6 +2134,7 @@ function createK3sCluster(opts: K3sOptions, count: number) {
       volumes: [{ name: `spectest-k3s-${cluster}-join`, target: JOIN_DIRECTORY }, ...(sticky
         ? [{ source: `${stickyKubernetesDirectory(SELF_SERVICE_TOKEN, version)}/containerd`, target: CLUSTER_STORE_TARGET }]
         : [{ target: CLUSTER_STORE_TARGET }]),
+        ...(coverage.enabled ? [coverage.volume(cluster)] : []),
         ...(server && publishBuilds.length ? [
           { source: registryDirectory(SELF_SERVICE_TOKEN), target: REGISTRY_DATA },
           { source: contentDirectory, target: REGISTRY_CONTENT, readOnly: true },
@@ -2140,6 +2143,7 @@ function createK3sCluster(opts: K3sOptions, count: number) {
       files: [
         ...(registriesYaml ? [{ path: "/etc/rancher/k3s/registries.yaml", content: registriesYaml }] : []),
       ],
+      ...(server && coverage.enabled ? { coverage: { adapters: [coverage.adapter()] } } : {}),
       // Agents start before the server and wait for its join token. The group
       // setup below gates readiness on every actual Kubernetes Node, including
       // the server, rather than treating container startup as cluster readiness.
@@ -2167,11 +2171,33 @@ function createK3sCluster(opts: K3sOptions, count: number) {
       const nodes = nodeNames(name);
       if (images.builds.length && !runtime) throw new Error(`k3s(${name}): prepared image inputs are missing`);
       const admission = (async () => {
+        if (coverage.enabled && (!runtime?.caBundle || !caPresent())) throw new Error(`k3s(${name}): coverage injection requires the environment CA`);
         if (runtime?.caBundle && caPresent()) {
           const { cert, key } = await issueIngressCert([runtime.gateway]);
           await installPodTrust({ name, gateway: runtime.gateway, cert, key,
             ca: await readFile(CA_PATH, "utf8"), bundle: await readFile(runtime.caBundle, "utf8"),
           }, {
+            mutatePod: (pod, namespace, dryRun, ephemeral, uid) => coverage.mutate(name, pod, namespace, dryRun, ephemeral, uid, {
+              async image(reference) {
+                const result = await exec(name, ["crictl", "--runtime-endpoint", "unix:///run/k3s/containerd/containerd.sock", "inspecti", reference]);
+                if (result.exitCode !== 0) throw new Error(`coverage image metadata: ${result.stderr}`);
+                const record = JSON.parse(result.stdout);
+                const config = record.info?.imageSpec?.config;
+                if (!config) throw new Error(`coverage image ${reference} has no OCI configuration`);
+                return { aliases: record.status?.repoDigests ?? [], root: config.WorkingDir || "/",
+                  env: Object.fromEntries((config.Env ?? []).map((entry: string) => { const split = entry.indexOf("="); return [entry.slice(0, split), entry.slice(split + 1)]; })),
+                };
+              },
+              async files(namespace, name, data) {
+                try {
+                  await helpers.client.core.createNamespacedConfigMap({ namespace, body: { metadata: { name, namespace }, immutable: true, data } });
+                } catch (error) {
+                  const existing = (await helpers.client.core.readNamespacedConfigMap({ namespace, name })).unwrap();
+                  if (!existing.immutable || Object.keys(existing.data ?? {}).length !== Object.keys(data).length ||
+                    Object.entries(data).some(([key, value]) => existing.data?.[key] !== value)) throw error;
+                }
+              },
+            }),
             apply: async configuration => { await helpers.apply(JSON.stringify(configuration)); },
             ensureBundle: async (namespace, configMap, bundle) => {
               try {

package/src/coverage/rust.rs

@@ -0,0 +1,102 @@
+// Copy to your test build as spectest-coverage.rs and include behind a coverage
+// feature. Call start()? at the beginning of main in EACH instrumented binary.
+// No Spectest service, compiler or network connection is needed at runtime.
+use std::{ffi::CString, fs, io::{self, BufRead, Read, Write}, os::unix::net::UnixListener,
+    path::PathBuf, process::Command, sync::{Mutex, OnceLock}, time::{SystemTime, UNIX_EPOCH}};
+
+unsafe extern "C" {
+    fn __llvm_profile_get_size_for_buffer() -> u64;
+    fn __llvm_profile_write_buffer(buffer: *mut u8) -> i32;
+    fn __llvm_profile_set_filename(filename: *const std::ffi::c_char);
+    fn atexit(callback: extern "C" fn()) -> i32;
+}
+
+struct Collector { dir: PathBuf, id: String, socket: PathBuf, binary: PathBuf, lock: Mutex<()> }
+static COLLECTOR: OnceLock<Collector> = OnceLock::new();
+
+fn failure(error: impl std::fmt::Display) {
+    if let Some(c) = COLLECTOR.get() {
+        let _ = fs::write(c.dir.join(format!("rust-error-{}.txt", c.id)), error.to_string());
+    }
+}
+
+fn tool(name: &str, default: &str, args: &[&std::ffi::OsStr]) -> io::Result<Vec<u8>> {
+    let output = Command::new(std::env::var_os(name).unwrap_or_else(|| default.into())).args(args).output()?;
+    if !output.status.success() {
+        return Err(io::Error::other(format!("{default}: {}", String::from_utf8_lossy(&output.stderr))));
+    }
+    Ok(output.stdout)
+}
+
+fn capture() -> io::Result<()> {
+    let c = COLLECTOR.get().expect("coverage initialized");
+    let _guard = c.lock.lock().map_err(|_| io::Error::other("coverage lock poisoned"))?;
+    let raw = c.dir.join(format!(".rust/{}.profraw", c.id));
+    let data = c.dir.join(format!(".rust/{}.profdata", c.id));
+    // A buffer snapshot overwrites this process's profile. write_file() with
+    // merge patterns would repeatedly add its inherited counters to itself.
+    let mut buffer = vec![0u8; unsafe { __llvm_profile_get_size_for_buffer() } as usize];
+    if unsafe { __llvm_profile_write_buffer(buffer.as_mut_ptr()) } != 0 {
+        return Err(io::Error::other("LLVM could not snapshot counters"));
+    }
+    fs::write(&raw, buffer)?;
+    tool("SPECTEST_LLVM_PROFDATA", "llvm-profdata", &["merge".as_ref(), "-sparse".as_ref(), raw.as_os_str(), "-o".as_ref(), data.as_os_str()])?;
+    let ignore = std::env::var("SPECTEST_RUST_IGNORE").unwrap_or_else(|_| "(/rustc/|/\\.cargo/registry/|/spectest-coverage\\.rs$)".into());
+    let report = tool("SPECTEST_LLVM_COV", "llvm-cov", &["export".as_ref(), "-format=lcov".as_ref(), "-instr-profile".as_ref(), data.as_os_str(),
+        c.binary.as_os_str(), format!("-ignore-filename-regex={ignore}").as_ref()])?;
+    if !report.starts_with(b"SF:") && !report.starts_with(b"TN:") {
+        return Err(io::Error::other("LLVM exported no LCOV source records"));
+    }
+    let mut report = String::from_utf8(report).map_err(io::Error::other)?;
+    if let Ok(root) = std::env::var("SPECTEST_RUST_BUILD_ROOT") {
+        let prefix = format!("SF:{}/", root.trim_end_matches('/'));
+        report = report.lines().map(|line| match line.strip_prefix(&prefix) {
+            Some(relative) => format!("SF:{relative}\n"), None => format!("{line}\n"),
+        }).collect();
+    }
+    let temporary = c.dir.join(format!(".rust/{}.lcov.tmp", c.id));
+    fs::write(&temporary, report)?;
+    fs::rename(temporary, c.dir.join(format!("rust-{}.lcov", c.id)))?;
+    Ok(())
+}
+
+extern "C" fn finish() {
+    if let Err(error) = capture() { failure(error); }
+    if let Some(c) = COLLECTOR.get() { let _ = fs::remove_file(&c.socket); }
+}
+
+/// Disabled when SPECTEST_COVERAGE_DIR is absent. Requires Unix and LLVM
+/// instrumentation at link time; gate this module behind your coverage build.
+pub fn start() -> io::Result<()> {
+    let Some(dir) = std::env::var_os("SPECTEST_COVERAGE_DIR") else { return Ok(()); };
+    if COLLECTOR.get().is_some() { return Ok(()); }
+    let dir = PathBuf::from(dir);
+    fs::create_dir_all(dir.join(".rust"))?;
+    let nonce = SystemTime::now().duration_since(UNIX_EPOCH).map_err(io::Error::other)?.as_nanos();
+    let id = format!("{:x}-{nonce:x}", std::process::id());
+    let socket = dir.join(format!(".rust-ctl-{id}"));
+    let listener = UnixListener::bind(&socket)?;
+    let binary = std::env::current_exe()?;
+    let exit_path = CString::new(dir.join(format!(".rust/{id}.exit.profraw")).as_os_str().as_encoded_bytes())?;
+    // The profiler may retain the filename until process exit.
+    unsafe { __llvm_profile_set_filename(exit_path.into_raw()); }
+    COLLECTOR.set(Collector { dir, id, socket, binary, lock: Mutex::new(()) }).map_err(|_| io::Error::other("coverage already initialized"))?;
+    if unsafe { atexit(finish) } != 0 { return Err(io::Error::other("could not register coverage exit handler")); }
+    // Establish a report before readiness; an uninstrumented/mismatched build
+    // must fail before it can supply an apparently empty baseline.
+    if let Err(error) = capture() { failure(&error); return Err(error); }
+    std::thread::Builder::new().name("spectest-coverage".into()).spawn(move || {
+        for connection in listener.incoming() {
+            let mut stream = match connection { Ok(stream) => stream, Err(error) => { failure(error); break; } };
+            let _ = stream.set_read_timeout(Some(std::time::Duration::from_secs(5)));
+            let mut request = String::new();
+            let result = io::BufReader::new(&stream).take(32).read_line(&mut request)
+                .and_then(|_| if request == "dump\n" { capture() } else { Err(io::Error::other("invalid coverage request")) });
+            match result {
+                Ok(()) => { let _ = stream.write_all(b"ok\n"); }
+                Err(error) => { failure(&error); let _ = writeln!(stream, "error {error}"); }
+            }
+        }
+    })?;
+    Ok(())
+}

package/src/coverage-bun.test.ts

@@ -0,0 +1,103 @@
+import { expect, test } from "bun:test";
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { bun, applyCoverageAdapters, NODE_COVERAGE_HOOK } from "./coverage";
+import { readCoverageDir, encodeCoverageBundle } from "./harness/coverage";
+
+async function checked(args: string[], cwd: string, env?: Record<string, string | undefined>) {
+  const child = Bun.spawn(args, { cwd, env: { ...process.env, ...env }, 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.join(" ")}: ${stderr}`);
+  return stdout;
+}
+
+test("Bun native coverage preserves bundle maps, captures exit, and rejects unmappable runtime transpilation", async () => {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), "bun-cov-"));
+  const reports = path.join(root, "reports");
+  await fs.mkdir(reports);
+  try {
+    await fs.writeFile(path.join(root, "hook.cjs"), NODE_COVERAGE_HOOK);
+    await fs.writeFile(path.join(root, "app.ts"), `export function choice(x: boolean) {\n if(x) return 'left';\n return 'right';\n}\nconsole.log(choice(true));\n`);
+    await checked([process.execPath, "build", "--target=bun", "--sourcemap=external", "--outdir=dist", "app.ts"], root);
+    const env = { BUN_OPTIONS: `--preload ${root}/hook.cjs`, SPECTEST_COVERAGE_DIR: reports, SPECTEST_COVERAGE_RUNTIME: "bun" };
+    expect(await checked([process.execPath, "dist/app.js"], root, env)).toContain("left");
+    const adapter = bun();
+    const context = { service: "bun", reportDir: reports, signal: AbortSignal.timeout(5000), exec: async () => ({ stdout: "", stderr: "" }),
+      writeReport: (name: string, content: string) => fs.writeFile(path.join(reports, name), content) };
+    await adapter.capture!(context);
+    const capture = await readCoverageDir("bun", reports);
+    expect(capture.error).toBeUndefined();
+    const scripts = capture.reports.filter(r => r.name.startsWith("scripts/")).map(r => JSON.parse(r.content).spectestScript);
+    expect(scripts).toHaveLength(1);
+    expect(scripts[0].sourceMap.data.sources.join()).toContain("app.ts");
+    expect(scripts[0].sourceMap.data.sourcesContent).toBeUndefined();
+    const dump = capture.reports.find(r => r.name.startsWith("node-"))!;
+    expect(JSON.parse(dump.content).result[0].functions.length).toBeGreaterThan(0);
+    await adapter.capture!(context);
+    expect((await readCoverageDir("bun", reports)).reports.some(r => r.name.startsWith("node-"))).toBe(false);
+    await checked([process.execPath, "app.ts"], root, env);
+    expect((await readCoverageDir("bun", reports)).error).toContain("neither");
+    const config = applyCoverageAdapters("cli", { image: "oven/bun", env: { BUN_OPTIONS: "--smol" }, coverage: { adapters: [adapter] } });
+    expect(config.env.BUN_OPTIONS).toContain("--smol --preload");
+  } finally { await fs.rm(root, { recursive: true, force: true }); }
+}, 20000);
+
+test("Bun live captures reset execution counts between calls", async () => {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), "bun-live-"));
+  let child: ReturnType<typeof Bun.spawn> | undefined;
+  try {
+    await fs.mkdir(path.join(root, "reports"));
+    await fs.writeFile(path.join(root, "hook.cjs"), NODE_COVERAGE_HOOK);
+    await fs.writeFile(path.join(root, "server.ts"), `import { createInterface } from 'node:readline';\nfunction left() {\n return 41;\n}\nfunction right() {\n return 42;\n}\ncreateInterface({input:process.stdin}).on('line', line => console.log(line === 'left' ? left() : right()));\nconsole.log('ready');\n`);
+    await checked([process.execPath, "build", "--target=bun", "--sourcemap=external", "--outdir=dist", "server.ts"], root);
+    child = Bun.spawn([process.execPath, "dist/server.js"], { cwd: root, stdin: "pipe", stdout: "pipe", stderr: "pipe", env: {
+      ...process.env, BUN_OPTIONS: `--preload ${root}/hook.cjs`, SPECTEST_COVERAGE_DIR: `${root}/reports`, SPECTEST_COVERAGE_RUNTIME: "bun",
+    } });
+    const reader = (child.stdout as ReadableStream<Uint8Array>).getReader();
+    expect(new TextDecoder().decode((await reader.read()).value)).toContain("ready");
+    const ctx = { service: "live", reportDir: `${root}/reports`, signal: AbortSignal.timeout(5000), exec: async () => ({ stdout: "", stderr: "" }),
+      writeReport: (name: string, content: string) => fs.writeFile(path.join(root, "reports", name), content) };
+    const adapter = bun();
+    await adapter.capture!(ctx);
+    const setup = await readCoverageDir("live", ctx.reportDir);
+    const compiled = await fs.readFile(path.join(root, "dist/server.js"), "utf8");
+    const descriptor = JSON.parse(setup.reports.find(r => r.name.startsWith("scripts/"))!.content).spectestScript;
+    for (const name of ["left", "right"]) {
+      const start = compiled.indexOf(`function ${name}(`);
+      const range = descriptor.functions.find((f: [string, number, number]) => f[1] === start);
+      expect(range).toBeDefined();
+      expect(compiled[range[2] - 1]).toBe("}");
+    }
+    (child.stdin as { write(value: string): void }).write("left\n");
+    expect(new TextDecoder().decode((await reader.read()).value)).toContain("41");
+    await adapter.capture!(ctx);
+    const first = await readCoverageDir("live", ctx.reportDir);
+    if (process.env.SPECTEST_RUNTIME_COVERAGE_EVIDENCE) {
+      const output = path.join(process.env.SPECTEST_RUNTIME_COVERAGE_EVIDENCE, "bun");
+      await fs.mkdir(output, { recursive: true });
+      await fs.writeFile(path.join(output, "setup.json.gz"), encodeCoverageBundle("__setup__", [{ ...setup, root }]));
+      await fs.writeFile(path.join(output, "left.json.gz"), encodeCoverageBundle("left", [{ ...first, root }]));
+      await fs.writeFile(path.join(output, "tree.txt"), "server.ts\n");
+      await fs.writeFile(path.join(output, "lines.json"), JSON.stringify({ "server.ts": 9 }));
+    }
+    expect(first.error).toBeUndefined();
+    const functions = first.reports.filter(r => r.name.startsWith("node-")).flatMap(r => JSON.parse(r.content).result.flatMap((s: any) => s.functions));
+    expect(functions.length).toBeGreaterThan(0);
+    await adapter.capture!(ctx);
+    const idle = await readCoverageDir("live", ctx.reportDir);
+    // No executed application ranges survive an idle take.
+    const idleFunctions = idle.reports.filter(r => r.name.startsWith("node-")).flatMap(r => JSON.parse(r.content).result.flatMap((s: any) => s.functions));
+    expect(idleFunctions).toHaveLength(0);
+    (child.stdin as { write(value: string): void }).write("right\n");
+    expect(new TextDecoder().decode((await reader.read()).value)).toContain("42");
+    await adapter.capture!(ctx);
+    const right = await readCoverageDir("live", ctx.reportDir);
+    expect(right.error).toBeUndefined();
+    if (process.env.SPECTEST_RUNTIME_COVERAGE_EVIDENCE) {
+      await fs.writeFile(path.join(process.env.SPECTEST_RUNTIME_COVERAGE_EVIDENCE, "bun/right.json.gz"), encodeCoverageBundle("right", [{ ...right, root }]));
+    }
+    (child.stdin as { end(): void }).end();
+    await child.exited;
+  } finally { child?.kill(); await fs.rm(root, { recursive: true, force: true }); }
+}, 20000);

package/src/coverage-bun.ts

@@ -0,0 +1,40 @@
+import { appendEnvFlag, node, NODE_COVERAGE_HOOK, NODE_COVERAGE_HOOK_PATH, type CoverageAdapter, type NodeCoverageOptions } from "./coverage.js";
+import { access } from "node:fs/promises";
+import path from "node:path";
+
+/** Bun's native precise profiler, for `bun build --target=bun` bundles.
+ * Keep external or inline source maps with the bundle. Raw TS/JS requiring
+ * runtime transpilation is rejected because Bun cannot supply its compiled
+ * source through the in-process inspector. */
+export interface BunCoverageOptions extends NodeCoverageOptions {
+  /** Only for idle command containers where no Bun process has run yet. */
+  allowEmpty?: boolean;
+}
+
+export function bun(options: BunCoverageOptions = {}): CoverageAdapter {
+  const adapter = node(options);
+  return {
+    ...adapter,
+    name: "bun",
+    configure(service, info) {
+      const configured = adapter.configure!(service, info);
+      const env = appendEnvFlag(service.env, "BUN_OPTIONS", `--preload ${NODE_COVERAGE_HOOK_PATH}`);
+      return { ...configured, env: {
+        ...configured.env, BUN_OPTIONS: env.BUN_OPTIONS,
+        // The Node adapter also contributes metadata for generated bundles.
+        NODE_OPTIONS: service.env?.NODE_OPTIONS ?? "",
+        SPECTEST_COVERAGE_RUNTIME: "bun",
+      }, files: [...(service.files ?? []), { path: NODE_COVERAGE_HOOK_PATH, content: NODE_COVERAGE_HOOK }] };
+    },
+    inventory: ctx => adapter.inventory!({ ...ctx, exec: command => ctx.exec(
+      command.replace(/\| node -/g, "| env BUN_OPTIONS= SPECTEST_COVERAGE_DIR= bun run -"),
+    ) }),
+    async capture(ctx) {
+      if (!options.allowEmpty) {
+        try { await access(path.join(ctx.reportDir, ".attached-bun")); }
+        catch { throw new Error("Bun coverage hook never attached; use a supported Bun runtime and preserve BUN_OPTIONS"); }
+      }
+      await adapter.capture!(ctx);
+    },
+  };
+}