@specific.dev/spectest 0.127.0 → 0.128.0

package/dist/components/k3s-coverage.d.ts

@@ -0,0 +1,24 @@
+import { type CoverageAdapter } from "../coverage.js";
+import { type KubernetesImage } from "../harness/component-images.js";
+import type { Patch, Pod } from "./k3s-trust.js";
+interface ImageInfo {
+    aliases: string[];
+    root: string;
+    env: Record<string, string>;
+}
+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 declare function k3sCoverage(images: readonly KubernetesImage[]): {
+    enabled: boolean;
+    volume(cluster: string): {
+        source: string;
+        target: string;
+        reachExempt: boolean;
+    };
+    mutate(cluster: string, podInput: Pod, namespace: string, dryRun: boolean, ephemeral: boolean, uid: string, deps: K3sCoverageDependencies): Promise<Patch[]>;
+    adapter(): CoverageAdapter;
+};
+export {};

package/dist/components/k3s-coverage.js

@@ -0,0 +1,259 @@
+import { createHash } from "node:crypto";
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { applyCoverageAdapters, coverageAdapters } from "../coverage.js";
+import { coverageHostDir, COVERAGE_MAX_BYTES_PER_SERVICE } from "../harness/coverage.js";
+import { captureCoverageTarget } from "../harness/coverage-target.js";
+import { canonicalImageReference } from "../harness/component-images.js";
+import { WORKSPACE } from "../project-files.js";
+const MOUNT = "/spectest/pod-coverage";
+const ANNOTATION = "spectest.dev/coverage";
+const hash = (value) => createHash("sha256").update(value).digest("hex").slice(0, 16);
+const quote = (value) => "'" + value.replaceAll("'", "'\\''") + "'";
+/** One component-owned bridge; runtime adapters remain unaware of Kubernetes. */
+export function k3sCoverage(images) {
+    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();
+    const service = (cluster, reference) => `${cluster}/image-${hash(reference)}`;
+    return {
+        enabled: declarations.length > 0,
+        volume(cluster) {
+            return { source: coverageHostDir(WORKSPACE, cluster), target: MOUNT, reachExempt: true };
+        },
+        async mutate(cluster, podInput, namespace, dryRun, ephemeral, uid, deps) {
+            if (!declarations.length || ephemeral)
+                return [];
+            const pod = podInput;
+            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 = [];
+            const volumes = [...(pod.spec.volumes ?? [])];
+            const instances = [];
+            const namedVolume = (stem, volume) => {
+                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"]) {
+                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(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, mount) => {
+                        if (mounts.some(m => mountPath === m.mountPath || mountPath.startsWith(m.mountPath.replace(/\/$/, "") + "/")))
+                            throw new Error(`coverage mount conflicts with ${mountPath}`);
+                        mounts.push({ mountPath, ...mount });
+                    };
+                    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 = { 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() {
+            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;
+                    try {
+                        entries = await fs.readdir(root);
+                    }
+                    catch (error) {
+                        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;
+                    const findPod = async (id) => {
+                        pods ??= ctx.exec("kubectl get pods -A -o json --request-timeout=10s")
+                            .then(result => JSON.parse(result.stdout).items);
+                        return (await pods).find(p => {
+                            const ids = p.metadata?.annotations?.[ANNOTATION];
+                            return ids && JSON.parse(ids).instances.includes(id);
+                        });
+                    };
+                    const captures = new Map();
+                    const inventories = new Map();
+                    for (const declaration of declarations)
+                        captures.set(declaration.reference, { service: service(ctx.service, declaration.reference), reports: [] });
+                    const collectInstance = async (id) => {
+                        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"));
+                        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();
+                    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()];
+                },
+            };
+        },
+    };
+}

package/dist/components/k3s-trust.d.ts

@@ -12,7 +12,7 @@ interface Container {
         readOnly?: boolean;
     }[];
 }
-interface Pod {
+export interface Pod {
     metadata?: {
         annotations?: Record<string, string>;
     };
@@ -32,7 +32,7 @@ interface Pod {
         ephemeralContainers?: Container[];
     };
 }
-interface Patch {
+export interface Patch {
     op: "add";
     path: string;
     value: unknown;
@@ -43,6 +43,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[]>;
 }
 export declare function installPodTrust(options: {
     name: string;

package/dist/components/k3s-trust.js

@@ -75,6 +75,19 @@ export async function installPodTrust(options, deps) {
                 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, key) => value[key], pod);
+                    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);

package/dist/components/k3s.js

@@ -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";
@@ -1335,6 +1336,7 @@ export function k3s(opts = {}) {
 function createK3sCluster(opts, count) {
     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;
@@ -1497,6 +1499,7 @@ function createK3sCluster(opts, count) {
             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 },
@@ -1505,6 +1508,7 @@ function createK3sCluster(opts, count) {
             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.
@@ -1533,11 +1537,38 @@ function createK3sCluster(opts, count) {
             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) => { 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/dist/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/dist/coverage-bun.d.ts

@@ -0,0 +1,10 @@
+import { type CoverageAdapter, type NodeCoverageOptions } from "./coverage.js";
+/** 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 declare function bun(options?: BunCoverageOptions): CoverageAdapter;

package/dist/coverage-bun.js

@@ -0,0 +1,32 @@
+import { appendEnvFlag, node, NODE_COVERAGE_HOOK, NODE_COVERAGE_HOOK_PATH } from "./coverage.js";
+import { access } from "node:fs/promises";
+import path from "node:path";
+export function bun(options = {}) {
+    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);
+        },
+    };
+}

package/dist/coverage-rust.d.ts

@@ -0,0 +1,23 @@
+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 declare function rustHelperSource(): string;
+/** Flush a socket-backed collector. A dead process without a final flush is
+ * incomplete coverage, never an empty successful report. */
+export declare function flushCoverageSockets(dir: string, prefix: string, signal: AbortSignal): Promise<number>;
+/** 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 declare function rust(options?: RustCoverageOptions): CoverageAdapter;

package/dist/coverage-rust.js

@@ -0,0 +1,71 @@
+import { promises as fs, readFileSync } from "node:fs";
+import path from "node:path";
+import { connect } from "node:net";
+/** 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() {
+    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, prefix, signal) {
+    const names = (await fs.readdir(dir)).filter(name => name.startsWith(prefix));
+    for (const name of names) {
+        signal.throwIfAborted();
+        await new Promise((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 = {}) {
+    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");
+            }
+        },
+    };
+}