@specific.dev/spectest 0.56.2 → 0.58.0

package/src/harness/browser-coverage.test.ts

@@ -0,0 +1,94 @@
+import { describe, expect, test } from "bun:test";
+import {
+  decodeSourceMap,
+  decodeVlq,
+  isForeignSource,
+  lcovDocument,
+  mapToOriginal,
+  mergeFileCounts,
+  normalizeSourcePath,
+  rangesToLineCounts,
+  serviceForHost,
+} from "./browser-coverage";
+
+describe("rangesToLineCounts", () => {
+  test("outer range sets lines, narrower ranges override, blanks dropped", () => {
+    const src = "function f() {\n  if (x) {\n    a();\n  }\n\n  b();\n}\n";
+    const fnRange = { startOffset: 0, endOffset: src.length, count: 3 };
+    const ifBlock = { startOffset: src.indexOf("{\n    a"), endOffset: src.indexOf("}\n\n") + 1, count: 0 };
+    const counts = rangesToLineCounts(src, [{ ranges: [fnRange, ifBlock] }]);
+    expect(counts.get(1)).toBe(3);
+    expect(counts.get(3)).toBe(0);
+    expect(counts.get(6)).toBe(3);
+    expect(counts.has(5)).toBe(false);
+  });
+});
+
+describe("source maps", () => {
+  test("decodeVlq", () => {
+    expect(decodeVlq("AAAA")).toEqual([0, 0, 0, 0]);
+    expect(decodeVlq("IACC")).toEqual([4, 0, 1, 1]);
+    expect(decodeVlq("D")).toEqual([-1]);
+  });
+
+  test("decode + map generated lines onto original files", () => {
+    // Two generated lines: line 1 maps to src/a.ts:1 and node_modules/x.js:1,
+    // line 2 maps to src/b.ts:5 (columns irrelevant for line attribution).
+    const map = decodeSourceMap({
+      version: 3,
+      sources: ["webpack:///./src/a.ts", "webpack:///./node_modules/x.js", "./src/b.ts"],
+      mappings: "AAAA,ICAA;ACIA",
+    });
+    expect(map).not.toBeNull();
+    expect(map!.sources).toEqual(["src/a.ts", "node_modules/x.js", "src/b.ts"]);
+    const files = mapToOriginal(map!, new Map([[1, 2], [2, 0]]));
+    expect([...files.keys()]).toEqual(["src/a.ts", "src/b.ts"]);
+    expect(files.get("src/a.ts")!.get(1)).toBe(2);
+    expect(files.get("src/b.ts")!.get(5)).toBe(0);
+  });
+
+  test("index maps and garbage decode to null", () => {
+    expect(decodeSourceMap({ version: 3, sections: [] })).toBeNull();
+    expect(decodeSourceMap({ version: 3, sources: ["a"], mappings: "!!" })).toBeNull();
+    expect(decodeSourceMap("nope")).toBeNull();
+  });
+
+  test("normalizeSourcePath strips schemes, roots and queries", () => {
+    expect(normalizeSourcePath("webpack:///./src/a.ts")).toBe("src/a.ts");
+    expect(normalizeSourcePath("http://app.test/src/a.ts?t=1")).toBe("/src/a.ts");
+    expect(normalizeSourcePath("/@fs/repo/src/a.ts")).toBe("/repo/src/a.ts");
+    expect(normalizeSourcePath("a.ts", "/app/src")).toBe("/app/src/a.ts");
+    expect(normalizeSourcePath("file:///app/src/a.ts")).toBe("/app/src/a.ts");
+    expect(isForeignSource("webpack/bootstrap")).toBe(true);
+    expect(isForeignSource("src/a.ts")).toBe(false);
+  });
+});
+
+test("lcovDocument is sorted, one record per file, merge sums", () => {
+  const files = new Map([["b.js", new Map([[2, 1]])], ["a.js", new Map([[1, 0], [3, 2]])]]);
+  mergeFileCounts(files, new Map([["a.js", new Map([[3, 1]])]]));
+  expect(lcovDocument(files)).toBe(
+    "TN:\nSF:a.js\nDA:1,0\nDA:3,3\nLF:2\nLH:1\nend_of_record\nSF:b.js\nDA:2,1\nLF:1\nLH:1\nend_of_record\n",
+  );
+});
+
+describe("serviceForHost", () => {
+  const table = {
+    proxies: [{ hostname: "app.test", service: "web" }],
+    aliasesByService: { api: ["api.todos.local"] },
+    wildcards: [
+      { pattern: "*.apps.test", target: { service: "k8s" } },
+      { pattern: "*.fake.test", target: { ingress: true } },
+    ],
+  };
+  const services = ["web", "api", "k8s"];
+  test("service key, .internal, alias, proxy, wildcard", () => {
+    expect(serviceForHost("web", services, table)).toBe("web");
+    expect(serviceForHost("WEB.internal", services, table)).toBe("web");
+    expect(serviceForHost("api.todos.local", services, table)).toBe("api");
+    expect(serviceForHost("app.test", services, table)).toBe("web");
+    expect(serviceForHost("a.b.apps.test", services, table)).toBe("k8s");
+    expect(serviceForHost("x.fake.test", services, table)).toBeUndefined();
+    expect(serviceForHost("example.com", services, table)).toBeUndefined();
+  });
+});

package/src/harness/browser-coverage.ts

@@ -0,0 +1,310 @@
+// Browser coverage — the pure part.
+//
+// A frontend runs in the guest Chromium, which is spectest's own process,
+// so the user cannot write a coverage report for it the way a service
+// process can. A service declares `coverage: { browser: true }` and
+// spectest collects it: V8 precise coverage over CDP for every script the
+// browser loads from that service, mapped back to original sources
+// through the served source maps, and written as one lcov report per
+// service into the same `case-coverage` bundle the container path uses.
+//
+// This module has no CDP in it: source-map decoding, V8 range → line
+// counts, host → service attribution, lcov output. The collector that
+// talks to the page is `../browser-coverage.ts`.
+
+/** Per-line hit counts, 1-based line numbers. */
+export type LineCounts = Map<number, number>;
+
+/** Per-file line counts. Keys are source paths as the source map (or the
+ *  script URL, when there is no map) reports them. */
+export type FileCounts = Map<string, LineCounts>;
+
+// ── V8 precise coverage → generated line counts ─────────────────────────
+
+/** Byte offset at which each line starts. */
+export function lineStartsOf(source: string): number[] {
+  const starts = [0];
+  for (let i = 0; i < source.length; i++) {
+    if (source.charCodeAt(i) === 10) starts.push(i + 1);
+  }
+  return starts;
+}
+
+/** 1-based line holding `offset`. */
+export function lineOf(starts: number[], offset: number): number {
+  let lo = 0;
+  let hi = starts.length - 1;
+  while (lo < hi) {
+    const mid = (lo + hi + 1) >> 1;
+    if (starts[mid] <= offset) lo = mid;
+    else hi = mid - 1;
+  }
+  return lo + 1;
+}
+
+/** One V8 `FunctionCoverage` as `Profiler.takePreciseCoverage` reports it. */
+export interface V8FunctionCoverage {
+  functionName?: string;
+  ranges: { startOffset: number; endOffset: number; count: number }[];
+  isBlockCoverage?: boolean;
+}
+
+/**
+ * Fold a script's block ranges onto its lines. Ranges come outer-first
+ * and a narrower range overrides the lines it spans, so a line inside an
+ * unexecuted branch ends at 0 even though its enclosing function ran.
+ * Blank lines are dropped. Approximate — a line holding two blocks gets
+ * the narrower one's count — which is exact at the file level, the only
+ * level anything reads today.
+ */
+export function rangesToLineCounts(
+  source: string,
+  functions: readonly V8FunctionCoverage[],
+): LineCounts {
+  const starts = lineStartsOf(source);
+  const counts: LineCounts = new Map();
+  for (const fn of functions) {
+    for (const r of fn.ranges) {
+      const a = lineOf(starts, r.startOffset);
+      const b = lineOf(starts, Math.max(r.startOffset, r.endOffset - 1));
+      for (let l = a; l <= b; l++) counts.set(l, r.count);
+    }
+  }
+  for (const l of [...counts.keys()]) {
+    const text = source.slice(starts[l - 1], starts[l] ?? source.length);
+    if (text.trim().length === 0) counts.delete(l);
+  }
+  return counts;
+}
+
+// ── Source maps ─────────────────────────────────────────────────────────
+
+/** One mapping segment: generated column → original (source, line). */
+export interface Segment {
+  col: number;
+  src: number;
+  line: number;
+}
+
+export interface DecodedSourceMap {
+  /** Normalised source paths, indexed by segment `src`. */
+  sources: string[];
+  /** Segments per generated line (0-based), sorted by column. */
+  lines: Segment[][];
+}
+
+const B64 = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+const B64_INDEX = new Map([...B64].map((c, i) => [c, i]));
+
+/** Decode one VLQ-encoded segment into its fields. */
+export function decodeVlq(segment: string): number[] {
+  const out: number[] = [];
+  let value = 0;
+  let shift = 0;
+  for (const ch of segment) {
+    const digit = B64_INDEX.get(ch);
+    if (digit === undefined) throw new Error(`bad VLQ char ${JSON.stringify(ch)}`);
+    value += (digit & 31) << shift;
+    if (digit & 32) {
+      shift += 5;
+    } else {
+      const negative = value & 1;
+      value >>>= 1;
+      out.push(negative ? -value : value);
+      value = 0;
+      shift = 0;
+    }
+  }
+  return out;
+}
+
+/**
+ * Normalise a source-map `sources` entry to a plain path. Bundlers prefix
+ * their own scheme (`webpack:///./src/a.ts`), dev servers serve absolute
+ * URLs paths (`/src/a.ts`), builds write relative ones (`../src/a.ts`).
+ * The server maps these onto the repo by suffix, so all that matters here
+ * is stripping what is not a path.
+ */
+export function normalizeSourcePath(src: string, sourceRoot?: string): string {
+  let s = src;
+  if (sourceRoot && !/^[a-z]+:/i.test(s)) {
+    s = sourceRoot.replace(/\/?$/, "/") + s;
+  }
+  s = s.replace(/^webpack:\/\/\/?/, "").replace(/^file:\/\//, "");
+  // A URL (`http://host/src/a.ts`, Vite's `/@fs/…`) keeps only its path.
+  const m = /^[a-z]+:\/\/[^/]*(\/.*)$/i.exec(s);
+  if (m) s = m[1];
+  s = s.replace(/^\/@fs\//, "/");
+  s = s.replace(/\?.*$/, "");
+  while (s.startsWith("./")) s = s.slice(2);
+  return s;
+}
+
+/** Sources nobody's change can be attributed to: dependencies and bundler
+ *  runtime shims. */
+export function isForeignSource(path: string): boolean {
+  return (
+    path.length === 0 ||
+    path.includes("node_modules/") ||
+    path.startsWith("webpack/") ||
+    path.startsWith("(webpack)") ||
+    path.startsWith("\0") ||
+    path.startsWith("vite/") ||
+    path.startsWith("@vite/")
+  );
+}
+
+/**
+ * Decode a source map document. Index maps (`sections`) are not
+ * supported and decode to `null`, as does anything malformed — the
+ * caller then falls back to attributing the script to its own URL, which
+ * the repo mapping cannot resolve, which is the safe answer.
+ */
+export function decodeSourceMap(doc: unknown): DecodedSourceMap | null {
+  if (!doc || typeof doc !== "object") return null;
+  const m = doc as {
+    version?: number;
+    sources?: unknown;
+    sourceRoot?: unknown;
+    mappings?: unknown;
+    sections?: unknown;
+  };
+  if (m.sections || !Array.isArray(m.sources) || typeof m.mappings !== "string") {
+    return null;
+  }
+  const sourceRoot = typeof m.sourceRoot === "string" ? m.sourceRoot : undefined;
+  const sources = m.sources.map((s) =>
+    typeof s === "string" ? normalizeSourcePath(s, sourceRoot) : "",
+  );
+  const lines: Segment[][] = [];
+  let src = 0;
+  let line = 0;
+  try {
+    for (const group of m.mappings.split(";")) {
+      const segs: Segment[] = [];
+      let col = 0;
+      if (group.length > 0) {
+        for (const seg of group.split(",")) {
+          if (seg.length === 0) continue;
+          const f = decodeVlq(seg);
+          col += f[0];
+          if (f.length >= 4) {
+            src += f[1];
+            line += f[2];
+            segs.push({ col, src, line });
+          }
+        }
+      }
+      lines.push(segs);
+    }
+  } catch {
+    return null;
+  }
+  return { sources, lines };
+}
+
+/**
+ * Attribute generated line counts to original (file, line)s through the
+ * map. Every original line a generated line's segments name gets that
+ * line's count (max over the generated lines that touch it). Foreign
+ * sources are dropped.
+ */
+export function mapToOriginal(map: DecodedSourceMap, generated: LineCounts): FileCounts {
+  const out: FileCounts = new Map();
+  for (const [genLine, count] of generated) {
+    const segs = map.lines[genLine - 1];
+    if (!segs || segs.length === 0) continue;
+    for (const seg of segs) {
+      const file = map.sources[seg.src];
+      if (file === undefined || isForeignSource(file)) continue;
+      let lc = out.get(file);
+      if (!lc) {
+        lc = new Map();
+        out.set(file, lc);
+      }
+      const l = seg.line + 1;
+      lc.set(l, Math.max(lc.get(l) ?? 0, count));
+    }
+  }
+  return out;
+}
+
+// ── Accumulation + lcov ─────────────────────────────────────────────────
+
+/** Add `from` into `into` (sums — takes reset V8's counters). */
+export function mergeLineCounts(into: LineCounts, from: LineCounts): void {
+  for (const [l, c] of from) into.set(l, (into.get(l) ?? 0) + c);
+}
+
+export function mergeFileCounts(into: FileCounts, from: FileCounts): void {
+  for (const [file, counts] of from) {
+    let target = into.get(file);
+    if (!target) {
+      target = new Map();
+      into.set(file, target);
+    }
+    mergeLineCounts(target, counts);
+  }
+}
+
+/** One lcov document for a set of files. */
+export function lcovDocument(files: FileCounts): string {
+  let out = "TN:\n";
+  for (const [file, counts] of [...files].sort((a, b) => (a[0] < b[0] ? -1 : 1))) {
+    out += `SF:${file}\n`;
+    let found = 0;
+    let hit = 0;
+    for (const [l, c] of [...counts].sort((a, b) => a[0] - b[0])) {
+      out += `DA:${l},${c}\n`;
+      found++;
+      if (c > 0) hit++;
+    }
+    out += `LF:${found}\nLH:${hit}\nend_of_record\n`;
+  }
+  return out;
+}
+
+// ── Host → service ──────────────────────────────────────────────────────
+
+/** The slice of the lowered ingress that names hosts. */
+export interface HostTable {
+  proxies: readonly { hostname: string; service: string }[];
+  aliasesByService: Readonly<Record<string, readonly string[]>>;
+  wildcards: readonly {
+    pattern: string;
+    target: { service?: string } | { ingress?: boolean } | Record<string, unknown>;
+  }[];
+}
+
+/**
+ * Which service a script URL's host belongs to: the service key itself,
+ * `<key>.internal`, its `hostnames`/`dnsName` aliases, a `tls`/`proxy`
+ * hostname routed to it, or a wildcard pointed at it. Exact first, then
+ * the longest wildcard suffix — the resolver's own precedence.
+ */
+export function serviceForHost(
+  host: string,
+  services: readonly string[],
+  table: HostTable,
+): string | undefined {
+  const h = host.toLowerCase().replace(/\.$/, "");
+  for (const s of services) {
+    if (h === s.toLowerCase() || h === `${s.toLowerCase()}.internal`) return s;
+  }
+  for (const [svc, aliases] of Object.entries(table.aliasesByService)) {
+    if (aliases.some((a) => a.toLowerCase() === h)) return svc;
+  }
+  for (const p of table.proxies) {
+    if (p.hostname.toLowerCase() === h) return p.service;
+  }
+  let best: { len: number; service: string } | undefined;
+  for (const w of table.wildcards) {
+    const service = (w.target as { service?: string }).service;
+    if (!service) continue;
+    const suffix = w.pattern.toLowerCase().replace(/^\*/, "");
+    if (h.endsWith(suffix) && h.length > suffix.length) {
+      if (!best || suffix.length > best.len) best = { len: suffix.length, service };
+    }
+  }
+  return best?.service;
+}

package/src/harness/coverage.test.ts

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

package/src/harness/coverage.ts

@@ -0,0 +1,173 @@
+// Coverage collection — the pure part.
+//
+// A service that opts in (`coverage: true | { command }`) gets a writable
+// directory bind-mounted at `/spectest/coverage/` in its container. The
+// service's own tool writes lcov reports there. The daemon reads the
+// directory from the VM side (no `docker exec` to fetch) after bring-up
+// and after each test, and ships the reports **verbatim** to the control
+// plane as a gzipped bundle. Nothing is interpreted here beyond the one
+// contract the harness must fail a case on: at least one report, and at
+// least one lcov `SF:` record among them. The server derives whatever it
+// needs (today the set of source files; later, finer things) from the
+// stored bytes, so a change in that derivation is a re-read of stored
+// runs, never a hole in the history.
+//
+// The container side (mount flag, `command` exec) is in `daemon.ts`.
+
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { gzipSync } from "node:zlib";
+
+/** Where the directory is mounted inside an opted-in container. */
+export const COVERAGE_CONTAINER_DIR = "/spectest/coverage";
+
+/** Raw bytes of reports one service may ship per capture. Reports are
+ *  cumulative and bounded by code size, so anything past this is a
+ *  runaway (a tool writing a new file per request), not coverage. */
+export const COVERAGE_MAX_BYTES_PER_SERVICE = 64 * 1024 * 1024;
+
+/** Root of the per-service host directories, under the workspace so the
+ *  delta-restore teardown wipes them with everything else. */
+export function coverageHostDir(workspace: string, service: string): string {
+  return path.join(workspace, ".spectest", "coverage", service);
+}
+
+/** One report file, verbatim. `name` is its path relative to the
+ *  coverage directory. */
+export interface CoverageReport {
+  name: string;
+  content: string;
+}
+
+/** One service's capture: every report in its directory, verbatim. */
+export interface ServiceCoverageCapture {
+  service: string;
+  reports: CoverageReport[];
+  /** Set when the capture failed: the command failed, the directory was
+   *  empty, no file held an `SF:` record, or the reports were too large.
+   *  A case with an error here fails — a hole in the coverage data must
+   *  never be silent. */
+  error?: string;
+}
+
+/** The small ref that rides the `run` reply in place of the bundle. */
+export interface CoverageBundleRef {
+  /** Gzipped bundle size; the control plane pulls exactly this many bytes
+   *  through `coverageChunk`. */
+  bytes: number;
+  services: {
+    service: string;
+    reports: number;
+    /** Raw (uncompressed) bytes of this service's reports. */
+    bytes: number;
+    error?: string;
+  }[];
+}
+
+/** The gzipped JSON document `coverageChunk` serves. Mirrors
+ *  `storage::CaseCoverageBundle` on the server. */
+export interface CoverageBundle {
+  caseId: string;
+  services: ServiceCoverageCapture[];
+}
+
+/** True when `text` holds at least one lcov `SF:` record. */
+export function hasLcovSourceFile(text: string): boolean {
+  return /^SF:\S/m.test(text);
+}
+
+/** Every regular file under `dir`, recursively, as paths relative to it.
+ *  Hidden files are skipped (a tool's own bookkeeping — `.seq`, `.lock`,
+ *  a tmp file mid-write — is not a report). */
+export async function listReportFiles(dir: string): Promise<string[]> {
+  const out: string[] = [];
+  async function walk(d: string, rel: string): Promise<void> {
+    let entries;
+    try {
+      entries = await fs.readdir(d, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      if (e.name.startsWith(".")) continue;
+      const r = rel ? `${rel}/${e.name}` : e.name;
+      if (e.isDirectory()) await walk(path.join(d, e.name), r);
+      else if (e.isFile()) out.push(r);
+    }
+  }
+  await walk(dir, "");
+  return out.sort();
+}
+
+/**
+ * Read every report under `dir`, verbatim. An empty directory, or one with
+ * no `SF:` record anywhere, is an error rather than an empty capture: the
+ * contract is that an opted-in service always has a report to read.
+ */
+export async function readCoverageDir(
+  service: string,
+  dir: string,
+): Promise<ServiceCoverageCapture> {
+  const names = await listReportFiles(dir);
+  if (names.length === 0) {
+    return {
+      service,
+      reports: [],
+      error: `service "${service}" opted in to coverage but ${COVERAGE_CONTAINER_DIR}/ holds no report — the service (or its coverage command) must write an lcov file there`,
+    };
+  }
+  const reports: CoverageReport[] = [];
+  let total = 0;
+  let anyLcov = false;
+  for (const name of names) {
+    let content: string;
+    try {
+      content = await fs.readFile(path.join(dir, name), "utf8");
+    } catch {
+      continue;
+    }
+    total += content.length;
+    if (total > COVERAGE_MAX_BYTES_PER_SERVICE) {
+      return {
+        service,
+        reports: [],
+        error: `service "${service}" has more than ${COVERAGE_MAX_BYTES_PER_SERVICE >> 20} MiB of reports in ${COVERAGE_CONTAINER_DIR}/ — reports must be cumulative, not one file per dump`,
+      };
+    }
+    if (hasLcovSourceFile(content)) anyLcov = true;
+    reports.push({ name, content });
+  }
+  if (!anyLcov) {
+    return {
+      service,
+      reports,
+      error: `service "${service}" wrote ${reports.length} file(s) to ${COVERAGE_CONTAINER_DIR}/ but none holds an lcov \`SF:\` record — only lcov reports are read`,
+    };
+  }
+  return { service, reports };
+}
+
+/** Gzip a case's captures into the bundle `coverageChunk` serves. */
+export function encodeCoverageBundle(
+  caseId: string,
+  services: ServiceCoverageCapture[],
+): Buffer {
+  const doc: CoverageBundle = { caseId, services };
+  return gzipSync(Buffer.from(JSON.stringify(doc)));
+}
+
+/** The ref for a bundle: its size plus a per-service summary. */
+export function coverageBundleRef(
+  gz: Buffer,
+  services: ServiceCoverageCapture[],
+): CoverageBundleRef {
+  return {
+    bytes: gz.length,
+    services: services.map((s) => ({
+      service: s.service,
+      reports: s.reports.length,
+      bytes: s.reports.reduce((n, r) => n + r.content.length, 0),
+      ...(s.error ? { error: s.error } : {}),
+    })),
+  };
+}