@specific.dev/spectest 0.85.1 → 0.86.1

package/dist/daemon.js

@@ -15,15 +15,16 @@
 // One sandbox = one daemon. Concurrency between tests is achieved by
 // forking the sandbox; inside a single daemon we never run two tests at
 // once — that keeps stdout capture and timeouts simple.
+import { preparedImages } from "./harness/prepared-images.js";
 import { execFile, spawn } from "node:child_process";
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { existsSync, promises as fs, readFileSync } from "node:fs";
 import net from "node:net";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 import { ENVIRONMENT_CA_PATH as CA_PATH } from "./environment-ca.js";
 import { assert, expect, expectRaw, lowerIngress, dnsName as makeDnsDecl, isWildcard, validateServiceImage, proxy as makeProxyDecl, } from "./index.js";
-import { COVERAGE_CONTAINER_DIR, coverageBundleRef, coverageHostDir, encodeCoverageBundle, isEmptyReport, readCoverageDir, applyCoverageDelta, walkProjectFiles, } from "./harness/coverage.js";
+import { COVERAGE_CONTAINER_DIR, coverageBundleRef, coverageHostDir, encodeCoverageBundle, isEmptyReport, readCoverageDir, applyCoverageDelta, walkProjectFiles, ENVIRONMENT_SERVICE, REACH_REPORT, } from "./harness/coverage.js";
 import { configureBrowserCoverage } from "./browser-coverage.js";
 import { INVENTORY_REPORT, NODE_COVERAGE_MARKERS_SUBDIR, NODE_COVERAGE_SCRIPTS_SUBDIR, applyCoverageAdapters, coverageAdapters, coverageReportsMode, validateCoverage, } from "./coverage.js";
 import { serviceForHost as hostToService } from "./harness/browser-coverage.js";
@@ -42,7 +43,8 @@ import { resolveHostPath as resolveVolumeHostPath, sanitizeSegment, } from "./ha
 import { pollUntilReady } from "./harness/ready-poll.js";
 import { runWrapperRules } from "./harness/wrapper-rules.js";
 import { cpus } from "node:os";
-import { APP_DIR, WORKSPACE, resolveExistingProjectPath, resolveProjectPath } from "./project-files.js";
+import { APP_DIR, WORKSPACE, resolveExistingProjectPath, resolveProjectPath, takeProjectReads } from "./project-files.js";
+import { projectReach, renderReach, renderReadsLcov } from "./harness/reach.js";
 import { installFetchWrapper, isTransportError } from "./harness/fetch.js";
 import { bindInstrumentationScope, createInstrumentationScope, runInstrumented, runUninstrumented, } from "./harness/instrumentation-scope.js";
 import { encodeRegistry } from "./harness/names-registry.js";
@@ -2946,23 +2948,31 @@ function logBootstrapTimings(t) {
     }
     console.log(`[bootstrap] total ${t.totalMs}ms across ${t.services.length} service(s)`);
 }
-async function bootstrap() {
+async function bootstrap(prepared) {
     // Tee everything this bootstrap logs — ours and every service `setup`
     // hook's — into the boot log, so GET /boot-log can explain a slow or
     // finished boot. Restored in the finally at the end.
     const restoreBootLog = captureConsole(BOOT_LOG_SINK);
     try {
-        return await bootstrapInner();
+        return await bootstrapInner(prepared);
     }
     finally {
         restoreBootLog();
     }
 }
-async function bootstrapInner() {
+async function imageInput(svc) {
+    const input = svc.image.type === "registry" ? svc.image : await resolveDockerfileBuild(svc);
+    return createHash("sha256").update(JSON.stringify(input)).digest("hex");
+}
+async function bootstrapInner(prepared, identity) {
     const bootStart = Date.now();
     const cfg = requireLoaded().project.environment;
     const services = namedServices(cfg);
     const timings = new Map();
+    if (prepared && (prepared.version !== 1 || !prepared.images ||
+        Object.keys(prepared.images).sort().join("\n") !== services.map(s => s.name).sort().join("\n"))) {
+        throw new Error("prepared image manifest does not match the environment's services");
+    }
     progressInit(services);
     // Build dedup is only valid within one workspace generation — a fresh
     // bootstrap may follow a workspace re-upload with the same dockerfile
@@ -3009,11 +3019,25 @@ async function bootstrapInner() {
     const tags = new Map();
     // Bootstrap is the only dedup scope: all its builds share one
     // /workspace generation (see prepareServiceImage).
-    const prepImage = (svc) => prepareServiceImage(svc, { dedup: true });
+    const prepImage = async (svc) => {
+        if (!prepared)
+            return prepareServiceImage(svc, { dedup: true });
+        const entry = prepared.images[svc.name];
+        if (!entry || entry.input !== await imageInput(svc) || !/^sha256:[a-f0-9]{64}$/.test(entry.image)) {
+            throw new Error(`prepared image inputs changed for ${svc.name}`);
+        }
+        const found = await docker(["image", "inspect", "--format", "{{.Id}}", entry.image], 30_000);
+        if (found.code !== 0 || found.stdout.trim() !== entry.image) {
+            throw new Error(`prepared image missing for ${svc.name}: ${entry.image}`);
+        }
+        return { tag: entry.image, buildSteps: entry.buildSteps };
+    };
     const prep = new Map();
+    const prepOffsets = new Map();
     for (const svc of services) {
         const p = (async () => {
             const t0 = Date.now();
+            prepOffsets.set(svc.name, Date.now() - bootStart);
             const { tag, buildSteps } = await prepImage(svc);
             progressService(svc.name, { status: "prepared", detail: undefined });
             tags.set(svc.name, tag);
@@ -3031,6 +3055,21 @@ async function bootstrapInner() {
         p.catch(() => undefined);
         prep.set(svc.name, p);
     }
+    if (identity !== undefined) {
+        // No application services, setup hooks, ingress, or runtime state in the builder.
+        await Promise.all(prep.values());
+        const images = Object.create(null);
+        for (const svc of services) {
+            const out = await docker(["image", "inspect", "--format", "{{.Id}}", tags.get(svc.name)], 30_000);
+            const image = out.stdout.trim();
+            if (out.code !== 0 || !/^sha256:[a-f0-9]{64}$/.test(image)) {
+                throw new Error(`cannot resolve prepared image for ${svc.name}: ${out.stderr}`);
+            }
+            const ti = timings.get(svc.name);
+            images[svc.name] = { input: await imageInput(svc), image, prepMs: ti.prepMs, startMs: prepOffsets.get(svc.name), buildSteps: ti.buildSteps };
+        }
+        return { version: 1, identity, images };
+    }
     // Ingress (fakes + service-tls proxies) comes up BEFORE services so
     // that any service that calls a fake URL during its own startup
     // probe finds it answering. Service-tls proxies will return 502
@@ -3487,8 +3526,13 @@ async function writeCoverageInventory(svc) {
         },
         projectFiles: () => walkProjectFiles(WORKSPACE),
         async readProjectFile(p) {
+            // Not recorded as a read: an inventory fingerprinting every
+            // manifest is bookkeeping, not the suite depending on the files.
+            // Recording them made the setup set name every package.json as a
+            // whole file, so a version bump was "ran during environment
+            // setup" — a full run, the exact case the inventory exists for.
             try {
-                return await fs.readFile(resolveProjectPath(p), "utf8");
+                return await fs.readFile(resolveProjectPath(p, { record: false }), "utf8");
             }
             catch {
                 return null;
@@ -3516,6 +3560,74 @@ async function writeCoverageInventory(svc) {
     console.log(`[coverage] ${svc.name}: inventory of ${units.size} unit(s)`);
     return undefined;
 }
+/**
+ * The project's reach (`harness/reach.ts`): every project file some
+ * service's build context includes, some volume mounts, or a build
+ * reads. Computed from the same resolution the builds use, once at the
+ * bring-up capture. The resolution's own path lookups are bookkeeping,
+ * not reads: they are taken out of the read set again afterwards.
+ */
+async function computeProjectReach(all) {
+    const before = takeProjectReads();
+    try {
+        return await computeProjectReachInner(all);
+    }
+    finally {
+        // Discard what the resolution recorded, restore what was there.
+        takeProjectReads();
+        for (const p of before)
+            resolveProjectPath(p);
+    }
+}
+async function computeProjectReachInner(all) {
+    const files = await walkProjectFiles(WORKSPACE, [".git"]);
+    const sources = [];
+    for (const svc of all) {
+        const src = {
+            volumeSources: (svc.volumes ?? []).flatMap((v) => (v.source ? [v.source] : [])),
+        };
+        if (svc.image.type === "dockerfile") {
+            try {
+                const b = await resolveDockerfileBuild(svc);
+                src.context = b.context;
+                src.ignore = b.ignore;
+                if (typeof svc.image.path === "string")
+                    src.extraFiles = [svc.image.path];
+            }
+            catch {
+                // Unresolvable here: count the whole project as its context, the
+                // conservative answer.
+                src.context = ".";
+                src.ignore = "";
+            }
+        }
+        sources.push(src);
+    }
+    return projectReach(files, sources);
+}
+/**
+ * The synthetic `__environment__` capture: what the environment itself
+ * knows — the project's reach (bring-up only) and the project files the
+ * harness read through the SDK since the previous capture, as whole
+ * lcov records. Present whenever some service opted in, so the two ride
+ * the same bundle as the services' reports.
+ */
+async function captureEnvironmentCoverage(all, baseline) {
+    const reports = [];
+    if (baseline) {
+        try {
+            const reach = await computeProjectReach(all);
+            reports.push({ name: REACH_REPORT, content: renderReach(reach) });
+            console.log(`[coverage] project reach: ${reach.length} file(s) some build or volume can carry`);
+        }
+        catch (err) {
+            console.warn(`[coverage] project reach not computed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    const reads = takeProjectReads();
+    reports.push({ name: "reads.lcov", content: renderReadsLcov(reads) });
+    return { service: ENVIRONMENT_SERVICE, reports };
+}
 async function captureServiceCoverage(baseline = false) {
     const l = loaded;
     if (!l)
@@ -3525,8 +3637,12 @@ async function captureServiceCoverage(baseline = false) {
         byName.set(s.name, s);
     for (const [name, s] of RUNTIME_SERVICES)
         byName.set(name, s);
-    const services = [...byName.values()].filter((s) => s.coverage !== undefined);
-    return Promise.all(services.map(async (svc) => {
+    const all = [...byName.values()];
+    const services = all.filter((s) => s.coverage !== undefined);
+    if (services.length === 0)
+        return [];
+    const environment = captureEnvironmentCoverage(all, baseline);
+    const captures = await Promise.all(services.map(async (svc) => {
         const { error, deltaReports } = await runCoverageAdapters(svc);
         if (error)
             return { service: svc.name, reports: [], error };
@@ -3548,6 +3664,7 @@ async function captureServiceCoverage(baseline = false) {
         // files and V8 JSON pass through.
         return applyCoverageDelta(read, coverageReportsMode(svc.coverage), deltaReports);
     }));
+    return [...captures, await environment];
 }
 /**
  * Mint a session id. `idScope` (the running test's case id; `"eval"`
@@ -5337,7 +5454,7 @@ function loadedSummary(l) {
  */
 export function harnessMethods(state) {
     return {
-        health: async () => ({ ok: true }),
+        health: async () => ({ ok: true, capabilities: ["prepared-images-v1"] }),
         // Live bootstrap progress, polled by the control plane during
         // `bootstrap` and streamed into the test-run row. `{}` before the
         // first bootstrap of this harness process.
@@ -5436,10 +5553,19 @@ export function harnessMethods(state) {
             }
             return { refs: [...refs] };
         },
-        bootstrap: async () => exclusive(state, "inFlightBootstrap", "bootstrap already in progress", async () => ({
-            ok: true,
-            timings: await bootstrap(),
-        })),
+        prepareImages: async (params) => exclusive(state, "inFlightBootstrap", "bootstrap already in progress", async () => {
+            const restore = captureConsole(BOOT_LOG_SINK);
+            try {
+                return await bootstrapInner(undefined, requireString(params, "identity"));
+            }
+            finally {
+                restore();
+            }
+        }),
+        bootstrap: async (params) => exclusive(state, "inFlightBootstrap", "bootstrap already in progress", async () => {
+            const prepared = params.prepared === undefined ? undefined : preparedImages(params.prepared, params.identity, namedServices(requireLoaded().project.environment).map(s => s.name));
+            return { ok: true, timings: await bootstrap(prepared) };
+        }),
         projectSetup: async () => exclusive(state, "inFlightProjectSetup", "project-setup already in progress", () => runProjectSetup()),
         eval: async (params) => {
             const code = requireString(params, "code");
@@ -5479,7 +5605,7 @@ export function harnessMethods(state) {
                     // After bring-up the code that started the service has run, so a
                     // report set that names no file at all is a misconfigured tool —
                     // visible in the boot log, never a failure (there is no case).
-                    if (!c.error && c.reports.length > 0 && c.reports.every((r) => isEmptyReport(r.content))) {
+                    if (c.service !== ENVIRONMENT_SERVICE && !c.error && c.reports.length > 0 && c.reports.every((r) => isEmptyReport(r.content))) {
                         // eslint-disable-next-line no-console
                         console.warn(`[coverage] service "${c.service}": every report is empty after bring-up — is coverage enabled at process start?`);
                     }

package/dist/harness/coverage.d.ts

@@ -1,5 +1,11 @@
 /** Where the directory is mounted inside an opted-in container. */
 export declare const COVERAGE_CONTAINER_DIR = "/spectest/coverage";
+/** The synthetic service the environment's own reports ride under: the
+ *  project's reach (bring-up) and the project files the harness read. */
+export declare const ENVIRONMENT_SERVICE = "__environment__";
+/** The bring-up report listing the project's reach, one project-relative
+ *  path per line (`harness/reach.ts`). */
+export declare const REACH_REPORT = "reach.paths";
 /** Raw bytes of reports one service may ship per capture. Reports are
  *  bounded by code size times chain depth, so anything past this is a
  *  runaway (a tool writing a new file per request), not coverage. */
@@ -83,7 +89,7 @@ export declare function isEmptyReport(text: string): boolean;
 /** Every regular file under `root`, recursively, as `/`-separated paths
  *  relative to it, with the directories no project file lives in
  *  skipped. The harness's project file list for an adapter's inventory. */
-export declare function walkProjectFiles(root: string): Promise<string[]>;
+export declare function walkProjectFiles(root: string, skipNames?: readonly string[]): Promise<string[]>;
 /** 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). */

package/dist/harness/coverage.js

@@ -33,6 +33,12 @@ 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";
+/** The synthetic service the environment's own reports ride under: the
+ *  project's reach (bring-up) and the project files the harness read. */
+export const ENVIRONMENT_SERVICE = "__environment__";
+/** The bring-up report listing the project's reach, one project-relative
+ *  path per line (`harness/reach.ts`). */
+export const REACH_REPORT = "reach.paths";
 /** Raw bytes of reports one service may ship per capture. Reports are
  *  bounded by code size times chain depth, so anything past this is a
  *  runaway (a tool writing a new file per request), not coverage. */
@@ -100,8 +106,8 @@ export function isEmptyReport(text) {
 /** Every regular file under `root`, recursively, as `/`-separated paths
  *  relative to it, with the directories no project file lives in
  *  skipped. The harness's project file list for an adapter's inventory. */
-export async function walkProjectFiles(root) {
-    const skip = new Set(["node_modules", ".git", ".spectest", "target", "__pycache__", ".venv", "dist", "build", ".next"]);
+export async function walkProjectFiles(root, skipNames = ["node_modules", ".git", ".spectest", "target", "__pycache__", ".venv", "dist", "build", ".next"]) {
+    const skip = new Set(skipNames);
     const out = [];
     async function walk(d, rel) {
         let entries;

package/dist/harness/prepared-images.d.ts

@@ -0,0 +1,14 @@
+import type { BuildStep } from "./buildkit-progress.js";
+export interface PreparedImages {
+    version: 1;
+    identity: string;
+    images: Record<string, {
+        input: string;
+        image: string;
+        prepMs: number;
+        startMs?: number;
+        buildSteps?: BuildStep[];
+    }>;
+}
+/** Build outputs are required inputs, never a hint to rebuild or pull again. */
+export declare function preparedImages(value: unknown, identity: unknown, names: string[]): PreparedImages;

package/dist/harness/prepared-images.js

@@ -0,0 +1,18 @@
+/** Build outputs are required inputs, never a hint to rebuild or pull again. */
+export function preparedImages(value, identity, names) {
+    const manifest = value;
+    if (!manifest || manifest.version !== 1 || typeof identity !== "string" || !identity || manifest.identity !== identity) {
+        throw new Error("prepared image source/SDK identity mismatch");
+    }
+    if (!manifest.images || typeof manifest.images !== "object" ||
+        Object.keys(manifest.images).sort().join("\n") !== [...names].sort().join("\n")) {
+        throw new Error("prepared image manifest does not match the environment's services");
+    }
+    for (const name of names) {
+        const entry = manifest.images[name];
+        if (!entry || !/^sha256:[a-f0-9]{64}$/.test(entry.image) || !/^[a-f0-9]{64}$/.test(entry.input)) {
+            throw new Error(`invalid prepared image for ${name}`);
+        }
+    }
+    return manifest;
+}

package/dist/harness/reach.d.ts

@@ -0,0 +1,39 @@
+/** One compiled pattern: its regex over the context-relative path, and
+ *  whether it is an exception (`!pattern`). */
+interface Pattern {
+    re: RegExp;
+    exception: boolean;
+}
+/** Compile a `.dockerignore` text. */
+export declare function compileDockerignore(text: string): Pattern[];
+/** Is `rel` (a file path relative to the context root) excluded from the
+ *  context? The last matching pattern decides; a pattern matching any
+ *  parent directory of the file counts as matching the file. */
+export declare function isExcluded(patterns: Pattern[], rel: string): boolean;
+/** One service's contribution to the reach. */
+export interface ReachSource {
+    /** Build context directory, project-relative (`.` for the root); absent
+     *  for a registry image. */
+    context?: string;
+    /** The composed `.dockerignore` text of the build. */
+    ignore?: string;
+    /** Files the build reads outside the context rules: the Dockerfile
+     *  named by `path` (project-relative). */
+    extraFiles?: string[];
+    /** Volume sources, project-relative; an absolute source is not a
+     *  project path and is skipped. */
+    volumeSources?: string[];
+}
+/**
+ * The project's reach: every project file (`files`, project-relative)
+ * some service's build context includes or some volume mounts, plus the
+ * Dockerfiles the builds read. Sorted, unique.
+ */
+export declare function projectReach(files: readonly string[], sources: readonly ReachSource[]): string[];
+/** The `reach.paths` report: one path per line. */
+export declare function renderReach(paths: readonly string[]): string;
+/** An lcov document that names `paths` as files with no line data —
+ *  "whole" records, which the index reads as every line unknown, so any
+ *  change to the file selects the case that read it. */
+export declare function renderReadsLcov(paths: readonly string[]): string;
+export {};

package/dist/harness/reach.js

@@ -0,0 +1,159 @@
+// What a change to a project file can reach — the pure part.
+//
+// A project file affects a test only through one of three doors: it is in
+// a service's **build context** (so an image may carry it), it is the
+// **source of a volume** a service mounts, or a test **reads** it through
+// the SDK. The first two are known from the environment config before any
+// test runs; the harness computes their union here — the project's
+// **reach** — and ships it with the bring-up capture (`reach.paths`, one
+// project-relative path per line, under the synthetic `__environment__`
+// service). The subset selector then treats a changed file outside the
+// reach as one that cannot affect the suite: `site/**` behind a
+// `.dockerignore`, `.github/**` outside every context. The third door is
+// recorded as it happens (`project-files.ts`, `takeProjectReads`).
+//
+// The context of a build is what `docker build` would send: every file
+// under the context directory minus what the composed `.dockerignore`
+// (the project's own rules plus the service's `exclude`) matches, with
+// Docker's semantics — a pattern is matched against the path relative to
+// the context root, `*` and `?` stay inside one segment, `**` spans
+// segments, `!` re-includes, and a pattern that matches a directory
+// excludes everything below it. When in doubt the answer is "reachable":
+// over-approximating the reach only costs a full run.
+/** Docker's `.dockerignore` pattern → a regex over a `/`-separated path,
+ *  after moby's `patternmatcher`. */
+function compilePattern(raw) {
+    let p = raw.trim().replace(/\\/g, "/");
+    while (p.startsWith("./"))
+        p = p.slice(2);
+    p = p.replace(/^\/+/, "").replace(/\/+$/, "");
+    let out = "^";
+    let i = 0;
+    while (i < p.length) {
+        const c = p[i];
+        if (c === "*") {
+            if (p[i + 1] === "*") {
+                // "**": swallow a trailing separator; at the end of the pattern
+                // it matches everything below, elsewhere zero or more segments.
+                i += 2;
+                if (p[i] === "/")
+                    i += 1;
+                out += i >= p.length ? ".*" : "(?:.*/)?";
+                continue;
+            }
+            out += "[^/]*";
+        }
+        else if (c === "?") {
+            out += "[^/]";
+        }
+        else if (c === "[") {
+            const close = p.indexOf("]", i);
+            if (close < 0) {
+                out += "\\[";
+            }
+            else {
+                out += p.slice(i, close + 1);
+                i = close;
+            }
+        }
+        else if (".+()|{}$^".includes(c)) {
+            out += `\\${c}`;
+        }
+        else {
+            out += c;
+        }
+        i += 1;
+    }
+    out += "$";
+    return new RegExp(out);
+}
+/** Compile a `.dockerignore` text. */
+export function compileDockerignore(text) {
+    const out = [];
+    for (const raw of text.split(/\r?\n/)) {
+        const line = raw.trim();
+        if (line.length === 0 || line.startsWith("#"))
+            continue;
+        const exception = line.startsWith("!");
+        const body = exception ? line.slice(1).trim() : line;
+        if (body.length === 0)
+            continue;
+        out.push({ re: compilePattern(body), exception });
+    }
+    return out;
+}
+/** Is `rel` (a file path relative to the context root) excluded from the
+ *  context? The last matching pattern decides; a pattern matching any
+ *  parent directory of the file counts as matching the file. */
+export function isExcluded(patterns, rel) {
+    const candidates = [rel];
+    let cut = rel.lastIndexOf("/");
+    while (cut > 0) {
+        candidates.push(rel.slice(0, cut));
+        cut = rel.lastIndexOf("/", cut - 1);
+    }
+    let excluded = false;
+    for (const pat of patterns) {
+        if (candidates.some((c) => pat.re.test(c)))
+            excluded = !pat.exception;
+    }
+    return excluded;
+}
+function normRel(p) {
+    let s = p.replace(/\\/g, "/");
+    while (s.startsWith("./"))
+        s = s.slice(2);
+    s = s.replace(/^\/+/, "").replace(/\/+$/, "");
+    return s === "." ? "" : s;
+}
+/**
+ * The project's reach: every project file (`files`, project-relative)
+ * some service's build context includes or some volume mounts, plus the
+ * Dockerfiles the builds read. Sorted, unique.
+ */
+export function projectReach(files, sources) {
+    const out = new Set();
+    for (const s of sources) {
+        if (s.context !== undefined) {
+            const ctx = normRel(s.context);
+            const prefix = ctx === "" ? "" : `${ctx}/`;
+            const patterns = compileDockerignore(s.ignore ?? "");
+            for (const f of files) {
+                if (prefix && !f.startsWith(prefix))
+                    continue;
+                const rel = f.slice(prefix.length);
+                // `docker build` always sends the Dockerfile and .dockerignore.
+                if (rel === ".dockerignore" || rel === "Dockerfile" || !isExcluded(patterns, rel))
+                    out.add(f);
+            }
+        }
+        for (const e of s.extraFiles ?? []) {
+            const rel = normRel(e);
+            if (rel)
+                out.add(rel);
+        }
+        for (const v of s.volumeSources ?? []) {
+            if (v.startsWith("/"))
+                continue;
+            const src = normRel(v);
+            for (const f of files) {
+                if (f === src || f.startsWith(`${src}/`))
+                    out.add(f);
+            }
+        }
+    }
+    return [...out].sort();
+}
+/** The `reach.paths` report: one path per line. */
+export function renderReach(paths) {
+    return paths.join("\n") + (paths.length ? "\n" : "");
+}
+/** An lcov document that names `paths` as files with no line data —
+ *  "whole" records, which the index reads as every line unknown, so any
+ *  change to the file selects the case that read it. */
+export function renderReadsLcov(paths) {
+    let out = "TN:\n";
+    for (const p of paths)
+        out += `SF:${p}\nend_of_record\n`;
+    return out;
+}

package/dist/project-files.d.ts

@@ -2,6 +2,9 @@
 export declare const WORKSPACE: string;
 /** The app dir; the user's `spectest/` sits directly under it. */
 export declare const APP_DIR: string;
+/** Take (and clear) the project-relative paths resolved since the last
+ *  take. Coverage attributes them to the case as whole files. */
+export declare function takeProjectReads(): string[];
 /**
  * Absolute in-VM path for a path in the user's repo. Absolute input is
  * returned as-is. A relative path resolves against the project, preferring the
@@ -11,7 +14,9 @@ export declare const APP_DIR: string;
  * the caller's own `fs` error names a real path — `readProjectFile` keeps
  * reporting ENOENT the way it always has.
  */
-export declare function resolveProjectPath(p: string): string;
+export declare function resolveProjectPath(p: string, opts?: {
+    record?: boolean;
+}): string;
 /** {@link resolveProjectPath}, but a missing file is an error that names every
  *  place we looked. For inputs a user hands us by name — a fixture — where an
  *  ENOENT on one guessed path reads as a spectest bug rather than a typo. */

package/dist/project-files.js

@@ -49,6 +49,18 @@ function envIgnored() {
     _envIgnored = new Set(paths);
     return _envIgnored;
 }
+/** Project files resolved since the last take — what a test read
+ *  through the SDK. Module memory: forks with the environment; the
+ *  coverage capture takes and clears it after every case, so a forked
+ *  child starts with what its parent's capture left, which is nothing. */
+const PROJECT_READS = new Set();
+/** Take (and clear) the project-relative paths resolved since the last
+ *  take. Coverage attributes them to the case as whole files. */
+export function takeProjectReads() {
+    const out = [...PROJECT_READS].sort();
+    PROJECT_READS.clear();
+    return out;
+}
 /** Repo-relative form of `p`: no leading `./`, POSIX separators. */
 function relative(p) {
     return path.normalize(p).replace(/^\.\//, "").replace(/^\/+/, "");
@@ -62,10 +74,16 @@ function relative(p) {
  * the caller's own `fs` error names a real path — `readProjectFile` keeps
  * reporting ENOENT the way it always has.
  */
-export function resolveProjectPath(p) {
+export function resolveProjectPath(p, opts = {}) {
     if (path.isAbsolute(p))
         return p;
     const rel = relative(p);
+    // A read is coverage of the file for the case that made it — unless
+    // the caller says otherwise: the harness's own bookkeeping reads (a
+    // coverage inventory fingerprinting every manifest) are not the
+    // suite's dependence on those files.
+    if (opts.record !== false)
+        PROJECT_READS.add(rel);
     if (rel.startsWith("spectest/")) {
         const app = path.join(APP_DIR, rel);
         if (existsSync(app))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.85.1",
+  "version": "0.86.1",
   "description": "Spectest SDK for defining test environments in TypeScript.",
   "type": "module",
   "main": "./dist/index.js",

package/src/daemon.ts

@@ -16,9 +16,10 @@
 // forking the sandbox; inside a single daemon we never run two tests at
 // once — that keeps stdout capture and timeouts simple.
 
+import { preparedImages, type PreparedImages } from "./harness/prepared-images.js";
 import { execFile, spawn } from "node:child_process";
 import type { ChildProcess } from "node:child_process";
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { existsSync, promises as fs, readFileSync } from "node:fs";
 import net from "node:net";
 import path from "node:path";
@@ -45,6 +46,8 @@ import {
   readCoverageDir,
   applyCoverageDelta,
   walkProjectFiles,
+  ENVIRONMENT_SERVICE,
+  REACH_REPORT,
   type CoverageBundleRef,
   type CoverageReport,
   type ServiceCoverageCapture,
@@ -97,7 +100,8 @@ import { pollUntilReady } from "./harness/ready-poll.js";
 import { runWrapperRules } from "./harness/wrapper-rules.js";
 import type { WrapperDiagnostic } from "./harness/wrapper-rules.js";
 import { cpus, tmpdir } from "node:os";
-import { APP_DIR, WORKSPACE, resolveExistingProjectPath, resolveProjectPath } from "./project-files.js";
+import { APP_DIR, WORKSPACE, resolveExistingProjectPath, resolveProjectPath, takeProjectReads } from "./project-files.js";
+import { projectReach, renderReach, renderReadsLcov, type ReachSource } from "./harness/reach.js";
 import { installFetchWrapper, isTransportError } from "./harness/fetch.js";
 import {
   bindInstrumentationScope,
@@ -3509,23 +3513,34 @@ function logBootstrapTimings(t: BootstrapTimings): void {
   console.log(`[bootstrap] total ${t.totalMs}ms across ${t.services.length} service(s)`);
 }
 
-async function bootstrap(): Promise<BootstrapTimings> {
+async function bootstrap(prepared?: PreparedImages): Promise<BootstrapTimings> {
   // Tee everything this bootstrap logs — ours and every service `setup`
   // hook's — into the boot log, so GET /boot-log can explain a slow or
   // finished boot. Restored in the finally at the end.
   const restoreBootLog = captureConsole(BOOT_LOG_SINK);
   try {
-    return await bootstrapInner();
+    return await bootstrapInner(prepared);
   } finally {
     restoreBootLog();
   }
 }
 
-async function bootstrapInner(): Promise<BootstrapTimings> {
+async function imageInput(svc: NamedService): Promise<string> {
+  const input = svc.image.type === "registry" ? svc.image : await resolveDockerfileBuild(svc);
+  return createHash("sha256").update(JSON.stringify(input)).digest("hex");
+}
+
+async function bootstrapInner(prepared?: PreparedImages): Promise<BootstrapTimings>;
+async function bootstrapInner(prepared: undefined, identity: string): Promise<PreparedImages>;
+async function bootstrapInner(prepared?: PreparedImages, identity?: string): Promise<BootstrapTimings | PreparedImages> {
   const bootStart = Date.now();
   const cfg: EnvironmentConfig = requireLoaded().project.environment;
   const services = namedServices(cfg);
   const timings = new Map<string, ServiceTiming>();
+  if (prepared && (prepared.version !== 1 || !prepared.images ||
+      Object.keys(prepared.images).sort().join("\n") !== services.map(s => s.name).sort().join("\n"))) {
+    throw new Error("prepared image manifest does not match the environment's services");
+  }
   progressInit(services);
   // Build dedup is only valid within one workspace generation — a fresh
   // bootstrap may follow a workspace re-upload with the same dockerfile
@@ -3576,12 +3591,24 @@ async function bootstrapInner(): Promise<BootstrapTimings> {
   const tags = new Map<string, string>();
   // Bootstrap is the only dedup scope: all its builds share one
   // /workspace generation (see prepareServiceImage).
-  const prepImage = (svc: NamedService): Promise<{ tag: string; buildSteps?: BuildStep[] }> =>
-    prepareServiceImage(svc, { dedup: true });
+  const prepImage = async (svc: NamedService): Promise<{ tag: string; buildSteps?: BuildStep[] }> => {
+    if (!prepared) return prepareServiceImage(svc, { dedup: true });
+    const entry = prepared.images[svc.name];
+    if (!entry || entry.input !== await imageInput(svc) || !/^sha256:[a-f0-9]{64}$/.test(entry.image)) {
+      throw new Error(`prepared image inputs changed for ${svc.name}`);
+    }
+    const found = await docker(["image", "inspect", "--format", "{{.Id}}", entry.image], 30_000);
+    if (found.code !== 0 || found.stdout.trim() !== entry.image) {
+      throw new Error(`prepared image missing for ${svc.name}: ${entry.image}`);
+    }
+    return { tag: entry.image, buildSteps: entry.buildSteps };
+  };
   const prep = new Map<string, Promise<void>>();
+  const prepOffsets = new Map<string, number>();
   for (const svc of services) {
     const p = (async () => {
       const t0 = Date.now();
+      prepOffsets.set(svc.name, Date.now() - bootStart);
       const { tag, buildSteps } = await prepImage(svc);
       progressService(svc.name, { status: "prepared", detail: undefined });
       tags.set(svc.name, tag);
@@ -3600,6 +3627,22 @@ async function bootstrapInner(): Promise<BootstrapTimings> {
     prep.set(svc.name, p);
   }
 
+  if (identity !== undefined) {
+    // No application services, setup hooks, ingress, or runtime state in the builder.
+    await Promise.all(prep.values());
+    const images: PreparedImages["images"] = Object.create(null);
+    for (const svc of services) {
+      const out = await docker(["image", "inspect", "--format", "{{.Id}}", tags.get(svc.name)!], 30_000);
+      const image = out.stdout.trim();
+      if (out.code !== 0 || !/^sha256:[a-f0-9]{64}$/.test(image)) {
+        throw new Error(`cannot resolve prepared image for ${svc.name}: ${out.stderr}`);
+      }
+      const ti = timings.get(svc.name)!;
+      images[svc.name] = { input: await imageInput(svc), image, prepMs: ti.prepMs, startMs: prepOffsets.get(svc.name), buildSteps: ti.buildSteps };
+    }
+    return { version: 1, identity, images };
+  }
+
   // Ingress (fakes + service-tls proxies) comes up BEFORE services so
   // that any service that calls a fake URL during its own startup
   // probe finds it answering. Service-tls proxies will return 502
@@ -4156,8 +4199,13 @@ async function writeCoverageInventory(svc: NamedService): Promise<string | undef
     },
     projectFiles: () => walkProjectFiles(WORKSPACE),
     async readProjectFile(p: string) {
+      // Not recorded as a read: an inventory fingerprinting every
+      // manifest is bookkeeping, not the suite depending on the files.
+      // Recording them made the setup set name every package.json as a
+      // whole file, so a version bump was "ran during environment
+      // setup" — a full run, the exact case the inventory exists for.
       try {
-        return await fs.readFile(resolveProjectPath(p), "utf8");
+        return await fs.readFile(resolveProjectPath(p, { record: false }), "utf8");
       } catch {
         return null;
       }
@@ -4182,14 +4230,83 @@ async function writeCoverageInventory(svc: NamedService): Promise<string | undef
   return undefined;
 }
 
+/**
+ * The project's reach (`harness/reach.ts`): every project file some
+ * service's build context includes, some volume mounts, or a build
+ * reads. Computed from the same resolution the builds use, once at the
+ * bring-up capture. The resolution's own path lookups are bookkeeping,
+ * not reads: they are taken out of the read set again afterwards.
+ */
+async function computeProjectReach(all: NamedService[]): Promise<string[]> {
+  const before = takeProjectReads();
+  try {
+    return await computeProjectReachInner(all);
+  } finally {
+    // Discard what the resolution recorded, restore what was there.
+    takeProjectReads();
+    for (const p of before) resolveProjectPath(p);
+  }
+}
+
+async function computeProjectReachInner(all: NamedService[]): Promise<string[]> {
+  const files = await walkProjectFiles(WORKSPACE, [".git"]);
+  const sources: ReachSource[] = [];
+  for (const svc of all) {
+    const src: ReachSource = {
+      volumeSources: (svc.volumes ?? []).flatMap((v) => (v.source ? [v.source] : [])),
+    };
+    if (svc.image.type === "dockerfile") {
+      try {
+        const b = await resolveDockerfileBuild(svc);
+        src.context = b.context;
+        src.ignore = b.ignore;
+        if (typeof svc.image.path === "string") src.extraFiles = [svc.image.path];
+      } catch {
+        // Unresolvable here: count the whole project as its context, the
+        // conservative answer.
+        src.context = ".";
+        src.ignore = "";
+      }
+    }
+    sources.push(src);
+  }
+  return projectReach(files, sources);
+}
+
+/**
+ * The synthetic `__environment__` capture: what the environment itself
+ * knows — the project's reach (bring-up only) and the project files the
+ * harness read through the SDK since the previous capture, as whole
+ * lcov records. Present whenever some service opted in, so the two ride
+ * the same bundle as the services' reports.
+ */
+async function captureEnvironmentCoverage(all: NamedService[], baseline: boolean): Promise<ServiceCoverageCapture> {
+  const reports: CoverageReport[] = [];
+  if (baseline) {
+    try {
+      const reach = await computeProjectReach(all);
+      reports.push({ name: REACH_REPORT, content: renderReach(reach) });
+      console.log(`[coverage] project reach: ${reach.length} file(s) some build or volume can carry`);
+    } catch (err) {
+      console.warn(`[coverage] project reach not computed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+  const reads = takeProjectReads();
+  reports.push({ name: "reads.lcov", content: renderReadsLcov(reads) });
+  return { service: ENVIRONMENT_SERVICE, reports };
+}
+
 async function captureServiceCoverage(baseline = false): Promise<ServiceCoverageCapture[]> {
   const l = loaded;
   if (!l) return [];
   const byName = new Map<string, NamedService>();
   for (const s of namedServices(l.project.environment)) byName.set(s.name, s);
   for (const [name, s] of RUNTIME_SERVICES) byName.set(name, s);
-  const services = [...byName.values()].filter((s) => s.coverage !== undefined);
-  return Promise.all(
+  const all = [...byName.values()];
+  const services = all.filter((s) => s.coverage !== undefined);
+  if (services.length === 0) return [];
+  const environment = captureEnvironmentCoverage(all, baseline);
+  const captures = await Promise.all(
     services.map(async (svc): Promise<ServiceCoverageCapture> => {
       const { error, deltaReports } = await runCoverageAdapters(svc);
       if (error) return { service: svc.name, reports: [], error };
@@ -4210,6 +4327,7 @@ async function captureServiceCoverage(baseline = false): Promise<ServiceCoverage
       return applyCoverageDelta(read, coverageReportsMode(svc.coverage), deltaReports);
     }),
   );
+  return [...captures, await environment];
 }
 
 /** Per-Browser rrweb session shipped to the control plane. */
@@ -6423,7 +6541,7 @@ function loadedSummary(l: ReturnType<typeof requireLoaded>) {
  */
 export function harnessMethods(state: RouteState): MethodTable {
   return {
-    health: async () => ({ ok: true }),
+    health: async () => ({ ok: true, capabilities: ["prepared-images-v1"] }),
 
     // Live bootstrap progress, polled by the control plane during
     // `bootstrap` and streamed into the test-run row. `{}` before the
@@ -6532,11 +6650,20 @@ export function harnessMethods(state: RouteState): MethodTable {
       return { refs: [...refs] };
     },
 
-    bootstrap: async () =>
-      exclusive(state, "inFlightBootstrap", "bootstrap already in progress", async () => ({
-        ok: true,
-        timings: await bootstrap(),
-      })),
+    prepareImages: async (params) =>
+      exclusive(state, "inFlightBootstrap", "bootstrap already in progress", async () => {
+        const restore = captureConsole(BOOT_LOG_SINK);
+        try { return await bootstrapInner(undefined, requireString(params, "identity")); }
+        finally { restore(); }
+      }),
+
+    bootstrap: async (params) =>
+      exclusive(state, "inFlightBootstrap", "bootstrap already in progress", async () => {
+        const prepared = params.prepared === undefined ? undefined : preparedImages(
+          params.prepared, params.identity, namedServices(requireLoaded().project.environment).map(s => s.name),
+        );
+        return { ok: true, timings: await bootstrap(prepared) };
+      }),
 
     projectSetup: async () =>
       exclusive(
@@ -6586,7 +6713,7 @@ export function harnessMethods(state: RouteState): MethodTable {
           // After bring-up the code that started the service has run, so a
           // report set that names no file at all is a misconfigured tool —
           // visible in the boot log, never a failure (there is no case).
-          if (!c.error && c.reports.length > 0 && c.reports.every((r) => isEmptyReport(r.content))) {
+          if (c.service !== ENVIRONMENT_SERVICE && !c.error && c.reports.length > 0 && c.reports.every((r) => isEmptyReport(r.content))) {
             // eslint-disable-next-line no-console
             console.warn(
               `[coverage] service "${c.service}": every report is empty after bring-up — is coverage enabled at process start?`,

package/src/harness/coverage.ts

@@ -36,6 +36,14 @@ import { gzipSync } from "node:zlib";
 /** Where the directory is mounted inside an opted-in container. */
 export const COVERAGE_CONTAINER_DIR = "/spectest/coverage";
 
+/** The synthetic service the environment's own reports ride under: the
+ *  project's reach (bring-up) and the project files the harness read. */
+export const ENVIRONMENT_SERVICE = "__environment__";
+
+/** The bring-up report listing the project's reach, one project-relative
+ *  path per line (`harness/reach.ts`). */
+export const REACH_REPORT = "reach.paths";
+
 /** Raw bytes of reports one service may ship per capture. Reports are
  *  bounded by code size times chain depth, so anything past this is a
  *  runaway (a tool writing a new file per request), not coverage. */
@@ -153,8 +161,11 @@ export function isEmptyReport(text: string): boolean {
 /** Every regular file under `root`, recursively, as `/`-separated paths
  *  relative to it, with the directories no project file lives in
  *  skipped. The harness's project file list for an adapter's inventory. */
-export async function walkProjectFiles(root: string): Promise<string[]> {
-  const skip = new Set(["node_modules", ".git", ".spectest", "target", "__pycache__", ".venv", "dist", "build", ".next"]);
+export async function walkProjectFiles(
+  root: string,
+  skipNames: readonly string[] = ["node_modules", ".git", ".spectest", "target", "__pycache__", ".venv", "dist", "build", ".next"],
+): Promise<string[]> {
+  const skip = new Set(skipNames);
   const out: string[] = [];
   async function walk(d: string, rel: string): Promise<void> {
     let entries;

package/src/harness/prepared-images.test.ts

@@ -0,0 +1,22 @@
+import { expect, test } from "bun:test";
+import { preparedImages } from "./prepared-images";
+
+const entry = { input: "a".repeat(64), image: `sha256:${"b".repeat(64)}`, prepMs: 12 };
+const manifest = () => ({ version: 1, identity: "source-and-sdk", images: { api: entry } });
+
+test("handoff pins immutable images and rejects a result from another source or SDK", () => {
+  expect(preparedImages(manifest(), "source-and-sdk", ["api"]).images.api.image).toBe(entry.image);
+  expect(() => preparedImages(manifest(), "different-source", ["api"])).toThrow(/identity/);
+});
+
+test("a missing or added service cannot silently fall back to an in-runtime build", () => {
+  expect(() => preparedImages(manifest(), "source-and-sdk", ["api", "worker"])).toThrow(/services/);
+  expect(() => preparedImages(manifest(), "source-and-sdk", [])).toThrow(/services/);
+});
+
+test("mutable image tags and malformed manifests are rejected", () => {
+  const m = manifest();
+  m.images.api = { ...entry, image: "spectest/api:latest" };
+  expect(() => preparedImages(m, "source-and-sdk", ["api"])).toThrow(/invalid/);
+  expect(() => preparedImages(null, "source-and-sdk", ["api"])).toThrow();
+});

package/src/harness/prepared-images.ts

@@ -0,0 +1,26 @@
+import type { BuildStep } from "./buildkit-progress.js";
+
+export interface PreparedImages {
+  version: 1;
+  identity: string;
+  images: Record<string, { input: string; image: string; prepMs: number; startMs?: number; buildSteps?: BuildStep[] }>;
+}
+
+/** Build outputs are required inputs, never a hint to rebuild or pull again. */
+export function preparedImages(value: unknown, identity: unknown, names: string[]): PreparedImages {
+  const manifest = value as PreparedImages | null;
+  if (!manifest || manifest.version !== 1 || typeof identity !== "string" || !identity || manifest.identity !== identity) {
+    throw new Error("prepared image source/SDK identity mismatch");
+  }
+  if (!manifest.images || typeof manifest.images !== "object" ||
+      Object.keys(manifest.images).sort().join("\n") !== [...names].sort().join("\n")) {
+    throw new Error("prepared image manifest does not match the environment's services");
+  }
+  for (const name of names) {
+    const entry = manifest.images[name];
+    if (!entry || !/^sha256:[a-f0-9]{64}$/.test(entry.image) || !/^[a-f0-9]{64}$/.test(entry.input)) {
+      throw new Error(`invalid prepared image for ${name}`);
+    }
+  }
+  return manifest;
+}

package/src/harness/reach.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, test } from "bun:test";
+import { compileDockerignore, isExcluded, projectReach, renderReadsLcov } from "./reach.js";
+
+describe("dockerignore semantics", () => {
+  const ex = (text: string, rel: string) => isExcluded(compileDockerignore(text), rel);
+  test("a bare name matches only at the context root; **/ matches at any depth", () => {
+    expect(ex("node_modules", "node_modules/x.js")).toBe(true);
+    expect(ex("node_modules", "packages/a/node_modules/x.js")).toBe(false);
+    expect(ex("**/node_modules/**", "packages/a/node_modules/x.js")).toBe(true);
+    expect(ex("**/node_modules", "packages/a/node_modules/x.js")).toBe(true);
+  });
+  test("site/** excludes the tree; a directory match covers every file below", () => {
+    expect(ex("site/**", "site/app/page.tsx")).toBe(true);
+    expect(ex("site", "site/app/page.tsx")).toBe(true);
+    expect(ex("site/**", "sites/x")).toBe(false);
+    expect(ex("docs", "docs.md")).toBe(false);
+  });
+  test("* and ? stay within a segment; [] classes; ! re-includes, last match wins", () => {
+    expect(ex("*.md", "README.md")).toBe(true);
+    expect(ex("*.md", "docs/README.md")).toBe(false);
+    expect(ex("**/*.md", "docs/README.md")).toBe(true);
+    expect(ex("a?c", "abc")).toBe(true);
+    expect(ex("a?c", "a/c")).toBe(false);
+    expect(ex("[ab]x", "ax")).toBe(true);
+    expect(ex("docs/**\n!docs/keep.md", "docs/keep.md")).toBe(false);
+    expect(ex("docs/**\n!docs/keep.md", "docs/other.md")).toBe(true);
+    expect(ex("!docs/keep.md\ndocs/**", "docs/keep.md")).toBe(true);
+  });
+  test("comments, blanks, ./ and leading slashes", () => {
+    expect(ex("# a comment\n\n./site/**\n", "site/x")).toBe(true);
+    expect(ex("/site/**", "site/x")).toBe(true);
+  });
+});
+
+describe("projectReach", () => {
+  const files = [
+    "package.json",
+    "packages/api/src/a.ts",
+    "packages/api/Dockerfile",
+    "packages/dashboard/src/b.tsx",
+    "site/app/page.tsx",
+    ".github/workflows/ci.yml",
+    "docs/x.md",
+    "spectest/index.ts",
+    "data/seed.sql",
+  ];
+  test("a root context minus its ignore, a narrowed context, a Dockerfile path, a volume source", () => {
+    const reach = projectReach(files, [
+      { context: ".", ignore: "site/**\ndocs/**\n", extraFiles: ["packages/api/Dockerfile"] },
+      { context: "packages/dashboard", ignore: "" },
+      { volumeSources: ["data", "/var/run/docker.sock"] },
+    ]);
+    expect(reach).toEqual([
+      ".github/workflows/ci.yml",
+      "data/seed.sql",
+      "package.json",
+      "packages/api/Dockerfile",
+      "packages/api/src/a.ts",
+      "packages/dashboard/src/b.tsx",
+      "spectest/index.ts",
+    ]);
+  });
+  test("a narrowed context alone reaches only its subtree", () => {
+    expect(projectReach(files, [{ context: "packages/dashboard", ignore: "" }])).toEqual(["packages/dashboard/src/b.tsx"]);
+  });
+  test("renderReadsLcov names whole files", () => {
+    expect(renderReadsLcov(["docs/x.md"])).toBe("TN:\nSF:docs/x.md\nend_of_record\n");
+  });
+});

package/src/harness/reach.ts

@@ -0,0 +1,171 @@
+// What a change to a project file can reach — the pure part.
+//
+// A project file affects a test only through one of three doors: it is in
+// a service's **build context** (so an image may carry it), it is the
+// **source of a volume** a service mounts, or a test **reads** it through
+// the SDK. The first two are known from the environment config before any
+// test runs; the harness computes their union here — the project's
+// **reach** — and ships it with the bring-up capture (`reach.paths`, one
+// project-relative path per line, under the synthetic `__environment__`
+// service). The subset selector then treats a changed file outside the
+// reach as one that cannot affect the suite: `site/**` behind a
+// `.dockerignore`, `.github/**` outside every context. The third door is
+// recorded as it happens (`project-files.ts`, `takeProjectReads`).
+//
+// The context of a build is what `docker build` would send: every file
+// under the context directory minus what the composed `.dockerignore`
+// (the project's own rules plus the service's `exclude`) matches, with
+// Docker's semantics — a pattern is matched against the path relative to
+// the context root, `*` and `?` stay inside one segment, `**` spans
+// segments, `!` re-includes, and a pattern that matches a directory
+// excludes everything below it. When in doubt the answer is "reachable":
+// over-approximating the reach only costs a full run.
+
+/** One compiled pattern: its regex over the context-relative path, and
+ *  whether it is an exception (`!pattern`). */
+interface Pattern {
+  re: RegExp;
+  exception: boolean;
+}
+
+/** Docker's `.dockerignore` pattern → a regex over a `/`-separated path,
+ *  after moby's `patternmatcher`. */
+function compilePattern(raw: string): RegExp {
+  let p = raw.trim().replace(/\\/g, "/");
+  while (p.startsWith("./")) p = p.slice(2);
+  p = p.replace(/^\/+/, "").replace(/\/+$/, "");
+  let out = "^";
+  let i = 0;
+  while (i < p.length) {
+    const c = p[i]!;
+    if (c === "*") {
+      if (p[i + 1] === "*") {
+        // "**": swallow a trailing separator; at the end of the pattern
+        // it matches everything below, elsewhere zero or more segments.
+        i += 2;
+        if (p[i] === "/") i += 1;
+        out += i >= p.length ? ".*" : "(?:.*/)?";
+        continue;
+      }
+      out += "[^/]*";
+    } else if (c === "?") {
+      out += "[^/]";
+    } else if (c === "[") {
+      const close = p.indexOf("]", i);
+      if (close < 0) {
+        out += "\\[";
+      } else {
+        out += p.slice(i, close + 1);
+        i = close;
+      }
+    } else if (".+()|{}$^".includes(c)) {
+      out += `\\${c}`;
+    } else {
+      out += c;
+    }
+    i += 1;
+  }
+  out += "$";
+  return new RegExp(out);
+}
+
+/** Compile a `.dockerignore` text. */
+export function compileDockerignore(text: string): Pattern[] {
+  const out: Pattern[] = [];
+  for (const raw of text.split(/\r?\n/)) {
+    const line = raw.trim();
+    if (line.length === 0 || line.startsWith("#")) continue;
+    const exception = line.startsWith("!");
+    const body = exception ? line.slice(1).trim() : line;
+    if (body.length === 0) continue;
+    out.push({ re: compilePattern(body), exception });
+  }
+  return out;
+}
+
+/** Is `rel` (a file path relative to the context root) excluded from the
+ *  context? The last matching pattern decides; a pattern matching any
+ *  parent directory of the file counts as matching the file. */
+export function isExcluded(patterns: Pattern[], rel: string): boolean {
+  const candidates: string[] = [rel];
+  let cut = rel.lastIndexOf("/");
+  while (cut > 0) {
+    candidates.push(rel.slice(0, cut));
+    cut = rel.lastIndexOf("/", cut - 1);
+  }
+  let excluded = false;
+  for (const pat of patterns) {
+    if (candidates.some((c) => pat.re.test(c))) excluded = !pat.exception;
+  }
+  return excluded;
+}
+
+/** One service's contribution to the reach. */
+export interface ReachSource {
+  /** Build context directory, project-relative (`.` for the root); absent
+   *  for a registry image. */
+  context?: string;
+  /** The composed `.dockerignore` text of the build. */
+  ignore?: string;
+  /** Files the build reads outside the context rules: the Dockerfile
+   *  named by `path` (project-relative). */
+  extraFiles?: string[];
+  /** Volume sources, project-relative; an absolute source is not a
+   *  project path and is skipped. */
+  volumeSources?: string[];
+}
+
+function normRel(p: string): string {
+  let s = p.replace(/\\/g, "/");
+  while (s.startsWith("./")) s = s.slice(2);
+  s = s.replace(/^\/+/, "").replace(/\/+$/, "");
+  return s === "." ? "" : s;
+}
+
+/**
+ * The project's reach: every project file (`files`, project-relative)
+ * some service's build context includes or some volume mounts, plus the
+ * Dockerfiles the builds read. Sorted, unique.
+ */
+export function projectReach(files: readonly string[], sources: readonly ReachSource[]): string[] {
+  const out = new Set<string>();
+  for (const s of sources) {
+    if (s.context !== undefined) {
+      const ctx = normRel(s.context);
+      const prefix = ctx === "" ? "" : `${ctx}/`;
+      const patterns = compileDockerignore(s.ignore ?? "");
+      for (const f of files) {
+        if (prefix && !f.startsWith(prefix)) continue;
+        const rel = f.slice(prefix.length);
+        // `docker build` always sends the Dockerfile and .dockerignore.
+        if (rel === ".dockerignore" || rel === "Dockerfile" || !isExcluded(patterns, rel)) out.add(f);
+      }
+    }
+    for (const e of s.extraFiles ?? []) {
+      const rel = normRel(e);
+      if (rel) out.add(rel);
+    }
+    for (const v of s.volumeSources ?? []) {
+      if (v.startsWith("/")) continue;
+      const src = normRel(v);
+      for (const f of files) {
+        if (f === src || f.startsWith(`${src}/`)) out.add(f);
+      }
+    }
+  }
+  return [...out].sort();
+}
+
+/** The `reach.paths` report: one path per line. */
+export function renderReach(paths: readonly string[]): string {
+  return paths.join("\n") + (paths.length ? "\n" : "");
+}
+
+/** An lcov document that names `paths` as files with no line data —
+ *  "whole" records, which the index reads as every line unknown, so any
+ *  change to the file selects the case that read it. */
+export function renderReadsLcov(paths: readonly string[]): string {
+  let out = "TN:\n";
+  for (const p of paths) out += `SF:${p}\nend_of_record\n`;
+  return out;
+}

package/src/project-files.ts

@@ -52,6 +52,20 @@ function envIgnored(): Set<string> {
   return _envIgnored;
 }
 
+/** Project files resolved since the last take — what a test read
+ *  through the SDK. Module memory: forks with the environment; the
+ *  coverage capture takes and clears it after every case, so a forked
+ *  child starts with what its parent's capture left, which is nothing. */
+const PROJECT_READS = new Set<string>();
+
+/** Take (and clear) the project-relative paths resolved since the last
+ *  take. Coverage attributes them to the case as whole files. */
+export function takeProjectReads(): string[] {
+  const out = [...PROJECT_READS].sort();
+  PROJECT_READS.clear();
+  return out;
+}
+
 /** Repo-relative form of `p`: no leading `./`, POSIX separators. */
 function relative(p: string): string {
   return path.normalize(p).replace(/^\.\//, "").replace(/^\/+/, "");
@@ -66,9 +80,14 @@ function relative(p: string): string {
  * the caller's own `fs` error names a real path — `readProjectFile` keeps
  * reporting ENOENT the way it always has.
  */
-export function resolveProjectPath(p: string): string {
+export function resolveProjectPath(p: string, opts: { record?: boolean } = {}): string {
   if (path.isAbsolute(p)) return p;
   const rel = relative(p);
+  // A read is coverage of the file for the case that made it — unless
+  // the caller says otherwise: the harness's own bookkeeping reads (a
+  // coverage inventory fingerprinting every manifest) are not the
+  // suite's dependence on those files.
+  if (opts.record !== false) PROJECT_READS.add(rel);
   if (rel.startsWith("spectest/")) {
     const app = path.join(APP_DIR, rel);
     if (existsSync(app)) return app;