@specific.dev/spectest 0.126.0 → 0.128.0

package/src/components/k3s-coverage.test.ts

@@ -0,0 +1,160 @@
+import { expect, test } from "bun:test";
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { k3sCoverage } from "./k3s-coverage";
+import { k3s } from "./k3s";
+import { node, browser, rust, type CoverageAdapter } from "../coverage";
+import { defineEnvironment } from "../index";
+import type { Pod, Patch } from "./k3s-trust";
+import { podTrustPatch } from "./k3s-trust";
+
+function apply(pod: any, patches: Patch[]): any {
+  const out = structuredClone(pod);
+  for (const operation of patches) {
+    const keys = operation.path.slice(1).split("/");
+    const key = keys.pop()!;
+    const parent = keys.reduce((value, key) => value[key], out);
+    if (key === "-") parent.push(operation.value); else parent[key] = operation.value;
+  }
+  return out;
+}
+const digest = `images.test/api@sha256:${"a".repeat(64)}`;
+const image = { reference: "images.test/api:test", content: "FROM node:24", coverage: { adapters: [node({ sourceRoot: "packages" })] } };
+const dependencies = {
+  image: async () => ({ aliases: [digest], root: "/app", env: { NODE_OPTIONS: "--max-old-space-size=512" } }),
+  files: async () => {},
+};
+
+test("admission recognizes prepared digest, preserves trust/user settings, covers init containers, and is idempotent", async () => {
+  const coverage = k3sCoverage([image]);
+  const pod = { metadata: { name: "api", annotations: { other: "value" } }, spec: {
+    containers: [{ name: "api", image: digest, env: [{ name: "FOO", value: "bar" }], securityContext: { runAsUser: 1000, readOnlyRootFilesystem: true } },
+      { name: "db", image: "postgres:17" }], initContainers: [{ name: "migrate", image: image.reference }],
+  } };
+  const trusted = apply(pod, podTrustPatch(pod, "ca-bundle"));
+  const patches = await coverage.mutate("k8s", trusted, "app", true, false, "admission", dependencies);
+  const result = apply(trusted, patches);
+  expect(result.spec.containers[0].image).toBe(digest);
+  expect(result.spec.containers[0].securityContext).toEqual(pod.spec.containers[0].securityContext);
+  expect(result.spec.containers[0].env).toContainEqual({ name: "NODE_OPTIONS", value: "--max-old-space-size=512 --require /spectest/coverage-hook.cjs" });
+  expect(result.spec.containers[0].env).toContainEqual({ name: "FOO", value: "bar" });
+  expect(result.spec.containers[0].volumeMounts.some((m: any) => m.mountPath === "/spectest/ca-bundle.crt")).toBe(true);
+  expect(result.spec.containers[1]).toEqual(trusted.spec.containers[1]);
+  const ids = JSON.parse(result.metadata.annotations["spectest.dev/coverage"]).instances;
+  expect(new Set(ids).size).toBe(2);
+  expect(await coverage.mutate("k8s", result, "app", true, false, "admission", dependencies)).toEqual([]);
+  await expect(coverage.mutate("k8s", result, "app", true, false, "another-pod", dependencies)).rejects.toThrow("inherited");
+  expect(await coverage.mutate("k8s", trusted, "app", true, true, "ephemeral", dependencies)).toEqual([]);
+  const other = structuredClone(pod);
+  other.spec.containers[0].image = `images.test/api@sha256:${"b".repeat(64)}`;
+  other.spec.initContainers = [];
+  expect(await coverage.mutate("k8s", other, "app", true, false, "other", dependencies)).toEqual([]);
+});
+
+test("coverage refuses colliding mounts and dynamic NODE_OPTIONS", async () => {
+  const coverage = k3sCoverage([image]);
+  for (const extra of [{ volumeMounts: [{ name: "user", mountPath: "/spectest" }] }, { env: [{ name: "NODE_OPTIONS", valueFrom: { secretKeyRef: { name: "options", key: "flags" } } }] }]) {
+    const pod = { metadata: {}, spec: { containers: [{ name: "api", image: digest, ...extra }] } };
+    await expect(coverage.mutate("k8s", pod as Pod, "app", true, false, "id", dependencies)).rejects.toThrow();
+  }
+});
+
+test("k3s mounts fork-local storage on every node and preserves image collectors when browser coverage is added", () => {
+  const environment = defineEnvironment({ name: "coverage", services: { k8s: {
+    ...k3s({ nodes: 3, images: [image], ingressDomains: ["app.test"] }),
+    coverage: { adapters: [browser()] },
+  } } });
+  const services = environment.config.services;
+  for (const service of Object.values(services)) {
+    const volume = service.volumes?.find(v => v.target === "/spectest/pod-coverage");
+    expect(volume?.source).toEndWith("/.spectest/coverage/k8s");
+    expect(volume?.reachExempt).toBe(true);
+  }
+  const wire = JSON.parse(JSON.stringify(services.k8s));
+  expect(wire.coverage.adapters.map((a: any) => a.adapter)).toEqual(["k3s-containers", "browser"]);
+  expect(wire.coverage.adapters[0].images[0].config.env.NODE_OPTIONS).toContain("--require");
+  expect(wire.imageBuilds[0].image.coverage).toBeUndefined();
+  const changed = defineEnvironment({ name: "coverage", services: { k8s: k3s({ images: [{ ...image, coverage: { adapters: [rust()] } }] }) } });
+  expect(JSON.stringify(changed.config)).not.toBe(JSON.stringify(environment.config));
+});
+
+test("replica counters are independent, reports survive pod deletion, and capture errors remain visible", async () => {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), "k3s-cov-"));
+  try {
+    const adapter: CoverageAdapter = { name: "lcov", reports: "cumulative", sourceOptions: { sourceRoot: "packages" }, ownsReport: n => n.endsWith(".lcov"),
+      async inventory(ctx) { await ctx.exec("inventory-probe"); return ["npm:api@1.0.0", "npm:unused@2.0.0"]; },
+    };
+    const coverage = k3sCoverage([{ ...image, coverage: { adapters: [adapter] } }]);
+    const ids = ["a".repeat(16), "b".repeat(16)];
+    for (const id of ids) {
+      const dir = path.join(root, ".pods", id);
+      await fs.mkdir(dir, { recursive: true });
+      await fs.writeFile(path.join(dir, ".instance.json"), JSON.stringify({ id, image: image.reference, container: "api", namespace: "app", root: "/app" }));
+      await fs.writeFile(path.join(dir, "app.lcov"), "TN:\nSF:/app/src/api.ts\nDA:1,2\nend_of_record\n");
+    }
+    let pods = ids.map(id => ({ metadata: { name: `api-${id}`, annotations: { "spectest.dev/coverage": JSON.stringify({ instances: [id] }) } },
+      status: { containerStatuses: [{ name: "api", state: { running: {} } }] } }));
+    const commands: string[] = [];
+    const ctx = { service: "k8s", reportDir: root, signal: AbortSignal.timeout(5000), exec: async (command: string) => {
+      commands.push(command); return { stdout: command.startsWith("kubectl get") ? JSON.stringify({ items: pods }) : "", stderr: "" };
+    },
+      projectFiles: async () => [], readProjectFile: async () => null, writeReport: async () => {} };
+    const first = await coverage.adapter().collect!(ctx, true);
+    expect(first).toHaveLength(1);
+    expect(first[0].error).toBeUndefined();
+    expect(first[0].reports).toHaveLength(3);
+    expect(first[0].reports.filter(r => r.name.endsWith(".lcov")).every(r => r.sourceOptions?.sourceRoot === "packages")).toBe(true);
+    // The consumer recognizes this exact name; per-replica prefixes would hide it.
+    expect(first[0].reports.find(r => r.name === "inventory.units")?.content).toBe("npm:api@1.0.0\nnpm:unused@2.0.0");
+    expect(commands.filter(command => command.includes("inventory-probe")).sort()).toEqual(ids.map(id => `kubectl exec -n 'app' 'api-${id}' -c 'api' -- sh -c 'inventory-probe'`));
+    expect(commands.filter(command => command.startsWith("kubectl get"))).toHaveLength(1);
+    // No pod exists any longer. Reports remain on fork-local node storage.
+    pods = [];
+    commands.length = 0;
+    await fs.writeFile(path.join(root, ".pods", ids[1], "app.lcov"), "TN:\nSF:/app/src/api.ts\nDA:1,3\nend_of_record\n");
+    const next = await coverage.adapter().collect!(ctx, false);
+    expect(next[0].reports[0].content).toBe("TN:\n");
+    expect(next[0].reports[1].content).toContain("DA:1,1");
+    expect(commands).toEqual([]); // Native collection needs neither API discovery nor exec.
+    await fs.writeFile(path.join(root, ".pods", ids[0], "failed.txt"), "lost report");
+    expect((await coverage.adapter().collect!(ctx, false))[0].error).toContain("neither");
+  } finally { await fs.rm(root, { recursive: true, force: true }); }
+});
+
+test("collection bounds parallel targets and shares lazy discovery for command adapters", async () => {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), "k3s-cov-parallel-"));
+  try {
+    let active = 0;
+    let peak = 0;
+    let release!: () => void;
+    const gate = new Promise<void>(resolve => { release = resolve; });
+    const adapter: CoverageAdapter = { name: "command", async capture(ctx) {
+      peak = Math.max(peak, ++active);
+      if (active === 8) release();
+      await gate;
+      await ctx.exec("capture-probe");
+      await ctx.writeReport("app.lcov", "TN:\nSF:/app/main.rs\nDA:1,1\nend_of_record\n");
+      active--;
+    } };
+    const ids = Array.from({ length: 11 }, (_, index) => index.toString(16).padStart(16, "0"));
+    for (const id of ids) {
+      const dir = path.join(root, ".pods", id);
+      await fs.mkdir(dir, { recursive: true });
+      await fs.writeFile(path.join(dir, ".instance.json"), JSON.stringify({ id, image: image.reference, container: "api", namespace: "app", root: "/app" }));
+    }
+    const pods = ids.map(id => ({ metadata: { name: `api-${id}`, annotations: { "spectest.dev/coverage": JSON.stringify({ instances: [id] }) } },
+      status: { containerStatuses: [{ name: "api", state: { running: {} } }] } }));
+    const commands: string[] = [];
+    const ctx = { service: "k8s", reportDir: root, signal: AbortSignal.timeout(5000), exec: async (command: string) => {
+      commands.push(command); return { stdout: command.startsWith("kubectl get") ? JSON.stringify({ items: pods }) : "", stderr: "" };
+    }, projectFiles: async () => [], readProjectFile: async () => null, writeReport: async () => {} };
+    const capture = (await k3sCoverage([{ ...image, coverage: { adapters: [adapter] } }]).adapter().collect!(ctx, false))[0];
+    expect(capture.error).toBeUndefined();
+    expect(capture.reports.map(report => report.name)).toEqual(ids.map(id => `${id}/app.lcov`));
+    expect(active).toBe(0);
+    expect(peak).toBe(8);
+    expect(commands.filter(command => command.startsWith("kubectl get"))).toHaveLength(1);
+    expect(commands.filter(command => command.includes("capture-probe"))).toHaveLength(11);
+  } finally { await fs.rm(root, { recursive: true, force: true }); }
+}, 10000);

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(())
+}