@specific.dev/spectest 0.119.0 → 0.119.2

package/dist/coverage.d.ts

@@ -127,6 +127,10 @@ export declare const INVENTORY_REPORT = "inventory.units";
 export type ServiceCoverage = true | {
     adapters?: readonly CoverageAdapter[];
     reports?: CoverageReportsMode;
+    /** Repository-relative root of this service's build/bundler workspace.
+     * For a monorepo built from packages/, set sourceRoot: "packages".
+     * Paths are checked against the repository; no suffix guessing. */
+    sourceRoot?: string;
 };
 /** The `reports` mode of a `coverage` value, for the reports no adapter
  *  wrote (the program's own, a `command`'s). */
@@ -259,7 +263,13 @@ export declare function npmManifestUnit(projectPath: string, text: string): stri
  * Prints one `npm:<name>@<version>` per line.
  */
 export declare const NODE_INVENTORY_SCRIPT = "\"use strict\";\nconst fs = require(\"node:fs\"), path = require(\"node:path\");\nconst out = new Set();\nfunction isRealDir(p) { try { return fs.lstatSync(p).isDirectory(); } catch (e) { return false; } }\nfunction readPkg(d) {\n  try {\n    const j = JSON.parse(fs.readFileSync(path.join(d, \"package.json\"), \"utf8\"));\n    if (j && typeof j.name === \"string\" && j.name) out.add(\"npm:\" + j.name + (typeof j.version === \"string\" && j.version ? \"@\" + j.version : \"\"));\n  } catch (e) {}\n}\nfunction visit(d, depth) {\n  readPkg(d);\n  if (depth < 3) { const nested = path.join(d, \"node_modules\"); if (isRealDir(nested)) walkNm(nested, depth + 1); }\n}\nfunction walkNm(nm, depth) {\n  let names; try { names = fs.readdirSync(nm); } catch (e) { return; }\n  for (const n of names) {\n    if (n === \".bin\" || n === \".cache\" || n === \".modules.yaml\") continue;\n    if (n === \".pnpm\") {\n      let ps; try { ps = fs.readdirSync(path.join(nm, \".pnpm\")); } catch (e) { continue; }\n      for (const p of ps) { const inner = path.join(nm, \".pnpm\", p, \"node_modules\"); if (isRealDir(inner)) walkNm(inner, depth + 1); }\n      continue;\n    }\n    if (n.startsWith(\"@\")) {\n      let ss; try { ss = fs.readdirSync(path.join(nm, n)); } catch (e) { continue; }\n      for (const s of ss) { const d = path.join(nm, n, s); if (isRealDir(d)) visit(d, depth); }\n    } else { const d = path.join(nm, n); if (isRealDir(d)) visit(d, depth); }\n  }\n}\nlet d = process.cwd();\nfor (;;) {\n  const nm = path.join(d, \"node_modules\");\n  if (isRealDir(nm)) walkNm(nm, 0);\n  const up = path.dirname(d);\n  if (up === d) break;\n  d = up;\n}\nprocess.stdout.write(Array.from(out).sort().join(\"\\n\") + (out.size ? \"\\n\" : \"\"));\n";
-export declare function node(): CoverageAdapter;
+export interface NodeCoverageOptions {
+    /** Generated runtime entrypoints, relative to the service working directory.
+     * Track their exact contents as units rather than inventing repository lines.
+     * A content change changes the inventory and invalidates dependent tests. */
+    generated?: readonly string[];
+}
+export declare function node(options?: NodeCoverageOptions): CoverageAdapter;
 /**
  * Ask every node process that holds a hook socket in `dir` for a dump.
  * A socket nobody answers (its process died without unlinking — SIGKILL,

package/dist/coverage.js

@@ -57,14 +57,19 @@ export function validateCoverage(service, cov) {
     const obj = typeof cov === "object" && cov !== null ? cov : null;
     const adapters = obj?.adapters;
     const reports = obj?.reports;
+    const sourceRoot = obj?.sourceRoot;
     // `explains` is what `applyCoverageAdapters` adds for the wire; the
     // config is validated again after that, so it must pass here.
     const explains = obj?.explains;
-    const knownKeys = obj !== null && Object.keys(obj).every((k) => k === "adapters" || k === "reports" || k === "explains");
+    const knownKeys = obj !== null && Object.keys(obj).every((k) => k === "adapters" || k === "reports" || k === "explains" || k === "sourceRoot");
+    const okRoot = sourceRoot === undefined || (typeof sourceRoot === "string" &&
+        (sourceRoot === "." || (sourceRoot.length > 0 && !sourceRoot.includes("\\") &&
+            !sourceRoot.includes(":") && !sourceRoot.includes("\0") &&
+            sourceRoot.split("/").every(p => p !== "" && p !== "." && p !== ".."))));
     const okReports = reports === undefined || reports === "delta" || reports === "cumulative";
     const okAdapters = adapters === undefined || Array.isArray(adapters);
     const okExplains = explains === undefined || (Array.isArray(explains) && explains.every((e) => typeof e === "string"));
-    if (obj !== null && knownKeys && okReports && okAdapters && okExplains && (adapters !== undefined || reports !== undefined)) {
+    if (obj !== null && knownKeys && okRoot && okReports && okAdapters && okExplains && (adapters !== undefined || reports !== undefined)) {
         for (const a of adapters ?? []) {
             const ok = typeof a === "object" &&
                 a !== null &&
@@ -111,7 +116,9 @@ export function applyCoverageAdapters(key, svc) {
     // `explains` rides the wire config so the control plane's selector can
     // read it without knowing any adapter.
     const explains = [...new Set(adapters.flatMap((a) => a.explains ?? []))];
+    const sourceRoot = typeof svc.coverage === "object" ? svc.coverage.sourceRoot : undefined;
     const wire = {
+        ...(sourceRoot !== undefined ? { sourceRoot } : {}),
         adapters: adapters.map((a) => withWireName(a)),
         ...(mode ? { reports: mode } : {}),
         ...(explains.length > 0 ? { explains } : {}),
@@ -241,6 +248,21 @@ export const NODE_COVERAGE_HOOK = `"use strict";
   if (post("Profiler.enable") === null) return;
   post("Profiler.startPreciseCoverage", { callCount: true, detailed: true });
 
+  // Attach before app scripts execute. Enabling only at capture loses the
+  // source of collected vm contexts (e.g. Temporal workflow bundles).
+  // Bound V8's collected-script cache; live sources remain owned by V8.
+  post("Debugger.enable", { maxScriptsCacheSize: 16 * 1024 * 1024 });
+
+  const GENERATED = new Map();
+  try {
+    for (const file of JSON.parse(process.env.SPECTEST_COVERAGE_GENERATED_FILES || "[]")) {
+      GENERATED.set(url.pathToFileURL(path.resolve(file)).href, file);
+    }
+  } catch (e) {}
+  const generatedUnits = new Map();
+  function generatedUnit(file, text) {
+    return "generated:" + process.env.SPECTEST_COVERAGE_SERVICE + ":" + file + "#" + crypto.createHash("sha256").update(text).digest("hex");
+  }
   const SELF = url.pathToFileURL(__filename).href;
   const SCRIPTS = path.join(dir, ${JSON.stringify(NODE_COVERAGE_SCRIPTS_SUBDIR)});
   const MARKERS = path.join(dir, ${JSON.stringify(NODE_COVERAGE_MARKERS_SUBDIR)});
@@ -347,31 +369,47 @@ export const NODE_COVERAGE_HOOK = `"use strict";
     } catch (e) {
       return null;
     }
-    if (!data || typeof data !== "object" || !("mappings" in data)) return null;
-    delete data.sourcesContent;
     // A source inside node_modules is a dependency: its unit id rides
     // beside the map (\`sourceUnits[i]\`, null for the project's own), so
     // the control plane never has to know what node_modules is.
     const mapDir = mapUrl ? path.dirname(url.fileURLToPath(mapUrl)) : path.dirname(scriptPath);
-    const root = typeof data.sourceRoot === "string" && data.sourceRoot ? data.sourceRoot : "";
-    const sourceUnits = (Array.isArray(data.sources) ? data.sources : []).map(function (src) {
-      if (typeof src !== "string") return null;
-      let abs;
-      if (src.startsWith("file://")) {
-        try {
-          abs = url.fileURLToPath(src);
-        } catch (e) {
-          return null;
+    function sourceUnits(data) {
+      const root = typeof data.sourceRoot === "string" ? data.sourceRoot : "";
+      return data.sources.map(function (src) {
+        if (typeof src !== "string") return null;
+        let abs;
+        if (src.startsWith("file://")) {
+          try {
+            abs = url.fileURLToPath(src);
+          } catch (e) {
+            return null;
+          }
+        } else if (/^[a-z][a-z0-9+.-]*:/i.test(src)) {
+          return src.indexOf("/node_modules/") >= 0 ? unitFromText(src) : null;
+        } else {
+          const rel = root && !src.startsWith("/") ? root.replace(/\\/$/, "") + "/" + src : src;
+          abs = path.resolve(mapDir, rel);
         }
-      } else if (/^[a-z][a-z0-9+.-]*:/i.test(src)) {
-        return src.indexOf("/node_modules/") >= 0 ? unitFromText(src) : null;
-      } else {
-        const rel = root && !src.startsWith("/") ? root.replace(/\\/$/, "") + "/" + src : src;
-        abs = path.resolve(mapDir, rel);
+        return abs.indexOf("/node_modules/") >= 0 ? unitOf(abs) : null;
+      });
+    }
+    function prepareMap(data, depth) {
+      if (!data || typeof data !== "object" || depth > 32) return false;
+      delete data.sourcesContent;
+      if (Array.isArray(data.sections)) {
+        if ("mappings" in data) return false;
+        return data.sections.every(function (section) {
+          return section && !section.url && prepareMap(section.map, depth + 1);
+        });
       }
-      return abs.indexOf("/node_modules/") >= 0 ? unitOf(abs) : null;
-    });
-    return { url: mapUrl, data: data, sourceUnits: sourceUnits };
+      if (!Array.isArray(data.sources) || typeof data.mappings !== "string") return false;
+      data.x_spectestSourceUnits = sourceUnits(data);
+      return true;
+    }
+    if (!prepareMap(data, 0)) return null;
+    const units = data.x_spectestSourceUnits;
+    delete data.x_spectestSourceUnits;
+    return { url: mapUrl, data: data, sourceUnits: units };
   }
   function writeAtomic(file, text) {
     const tmp = file + "." + process.pid + "-" + wt.threadId + ".tmp";
@@ -420,34 +458,44 @@ export const NODE_COVERAGE_HOOK = `"use strict";
     if (kept.length === 0 && units.size === 0) return;
     const fresh = [];
     for (const s of kept) {
-      if (!known.has(s.scriptId)) fresh.push(s);
+      if (!known.has(s.scriptId) && !generatedUnits.has(s.scriptId)) fresh.push(s);
     }
     if (fresh.length > 0) {
       try {
         fs.mkdirSync(SCRIPTS, { recursive: true });
         fs.mkdirSync(MARKERS, { recursive: true });
       } catch (e) {}
-      post("Debugger.enable");
       for (const s of fresh) {
         const r = post("Debugger.getScriptSource", { scriptId: s.scriptId });
         try {
-          known.set(s.scriptId, describe(s, r && r.scriptSource));
+          const source = r && r.scriptSource;
+          if (GENERATED.has(s.url) && typeof source === "string") {
+            generatedUnits.set(s.scriptId, generatedUnit(GENERATED.get(s.url), source));
+            continue;
+          }
+          const id = describe(s, source);
+          // A failed source fetch remains visible in this dump, but is not
+          // memoized as a successful descriptor for subsequent captures.
+          if (typeof source === "string") known.set(s.scriptId, id);
+          s.missingSourceRecord = id;
         } catch (e) {}
       }
-      post("Debugger.disable");
     }
     // A ran function is one flat array: [start, length, count] for its
     // extent (V8's first range), then [offset from start, length, count]
     // per block range in V8's order. Small numbers, so the dump gzips to
     // less than half of V8's own JSON; name and block flag live in the
     // script record, joined on the extent.
+    for (const s of kept) {
+      if (generatedUnits.has(s.scriptId)) units.add(generatedUnits.get(s.scriptId));
+    }
     const doc = {
       spectestVersion: 2,
       units: Array.from(units).sort(),
-      result: kept.map(function (s) {
+      result: kept.filter(function (s) { return !generatedUnits.has(s.scriptId); }).map(function (s) {
         return {
           url: s.url,
-          spectestScript: known.get(s.scriptId) || null,
+          spectestScript: known.get(s.scriptId) || s.missingSourceRecord || null,
           functions: s.functions.filter(ran).map(function (f) {
             const first = f.ranges[0];
             const out = [first.startOffset, first.endOffset - first.startOffset, first.count];
@@ -625,7 +673,15 @@ for (;;) {
 }
 process.stdout.write(Array.from(out).sort().join("\\n") + (out.size ? "\\n" : ""));
 `;
-export function node() {
+export function node(options = {}) {
+    if (options.generated !== undefined && (!Array.isArray(options.generated) || options.generated.some(p => typeof p !== "string"))) {
+        throw new Error("coverage.node generated must be a list of relative files");
+    }
+    const generated = [...new Set(options.generated ?? [])].sort();
+    if (generated.some(p => !p || p.includes("\\") || p.includes(":") || p.includes("\0") ||
+        p.split("/").some(c => !c || c === "." || c === ".."))) {
+        throw new Error("coverage.node generated paths must be relative files without traversal");
+    }
     return {
         name: "node",
         reports: "delta",
@@ -637,6 +693,16 @@ export function node() {
             const b64 = Buffer.from(NODE_INVENTORY_SCRIPT).toString("base64");
             const r = await ctx.exec(`echo ${b64} | base64 -d | node -`);
             const units = new Set(r.stdout.split("\n").map((l) => l.trim()).filter((l) => l.startsWith("npm:")));
+            if (generated.length) {
+                const script = `const fs=require("node:fs"),crypto=require("node:crypto");
+          for(const file of ${JSON.stringify(generated)}) console.log(
+            ${JSON.stringify("generated:" + ctx.service + ":")} + file + "#" +
+            crypto.createHash("sha256").update(fs.readFileSync(file)).digest("hex"));`;
+                const result = await ctx.exec(`echo ${Buffer.from(script).toString("base64")} | base64 -d | node -`);
+                for (const unit of result.stdout.trim().split("\n"))
+                    if (unit)
+                        units.add(unit);
+            }
             for (const f of await ctx.projectFiles()) {
                 if (f !== "package.json" && !f.endsWith("/package.json"))
                     continue;
@@ -646,9 +712,13 @@ export function node() {
             }
             return [...units].sort();
         },
-        configure(svc) {
+        configure(svc, info) {
             const env = appendEnvFlag(svc.env, "NODE_OPTIONS", `--require ${NODE_COVERAGE_HOOK_PATH}`);
             env[NODE_COVERAGE_DIR_ENV] = COVERAGE_CONTAINER_DIR;
+            if (generated.length) {
+                env.SPECTEST_COVERAGE_GENERATED_FILES = JSON.stringify(generated);
+                env.SPECTEST_COVERAGE_SERVICE = info.key;
+            }
             return {
                 ...svc,
                 env,

package/dist/daemon.js

@@ -1003,7 +1003,7 @@ async function resolveDockerfileBuild(svc) {
         throw new Error(`service "${svc.name}" image is not a Dockerfile build`);
     }
     const contextRel = image.context ?? ".";
-    const contextDir = resolveExistingProjectPath(contextRel, `service "${svc.name}" build context`);
+    const contextDir = resolveExistingProjectPath(contextRel, `service "${svc.name}" build context`, { record: false });
     let content;
     let adjacent = null;
     let adjacentPath = null;
@@ -1214,7 +1214,10 @@ async function runServiceBuild(name, image, tag) {
             buildArgs = ["build", ...argFlags, "-t", tag, "-f", dfPath, contextDir];
         }
         progressService(name, { status: "building", detail: "starting build" });
-        const build = await shxStream("docker", buildArgs, 1_800_000, buildEnv, (line) => {
+        // The controller owns the bootstrap/prepareImages deadline and tears
+        // down the VM on expiry. A separate build timer would cut short an
+        // environment's explicit timeoutSecs allowance (e.g. long Rust builds).
+        const build = await shxStream("docker", buildArgs, undefined, buildEnv, (line) => {
             // BuildKit `--progress=plain` declares each step as
             // `#N [<stage> M/N] <cmd>`; the legacy builder as `Step M/N : <cmd>`.
             // Track the most-recent step as live detail.
@@ -3436,6 +3439,9 @@ async function captureServiceCoverage(baseline = false) {
         const root = await coverageRoot(svc.name);
         if (root)
             read.root = root;
+        if (typeof svc.coverage === "object" && svc.coverage.sourceRoot !== undefined) {
+            read.sourceRoot = svc.coverage.sourceRoot;
+        }
         // What ships is what ran during this capture, whatever the tool
         // counts: cumulative lcov is subtracted against the previous
         // capture (module memory, forks with the env); a delta adapter's

package/dist/harness/browser-coverage.d.ts

@@ -61,12 +61,12 @@ export declare function isForeignSource(path: string): boolean;
  */
 export declare function isDocumentScriptPath(pathname: string): boolean;
 /**
- * Decode a source map document. Index maps (`sections`) are not
- * supported and decode to `null`, as does anything malformed — the
+ * Decode flat and embedded index maps. Unsupported external section URLs
+ * and malformed maps decode to `null` — 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 declare function decodeSourceMap(doc: unknown): DecodedSourceMap | null;
+export declare function decodeSourceMap(doc: unknown, depth?: number): DecodedSourceMap | null;
 /**
  * Attribute generated line counts to original (file, line)s through the
  * map. Every original line a generated line's segments name gets that

package/dist/harness/browser-coverage.js

@@ -83,6 +83,8 @@ export function decodeVlq(segment) {
             shift = 0;
         }
     }
+    if (shift !== 0)
+        throw new Error("unterminated VLQ");
     return out;
 }
 /**
@@ -121,6 +123,9 @@ export function normalizeSourcePath(src, sourceRoot) {
 /** Sources nobody's change can be attributed to: dependencies and bundler
  *  runtime shims. */
 export function isForeignSource(path) {
+    // Preserve project namespaces; only the explicit Turbopack runtime is foreign.
+    if (path.startsWith("turbopack:///[turbopack]/"))
+        return true;
     return (path.length === 0 ||
         path.includes("node_modules/") ||
         path.startsWith("webpack/") ||
@@ -143,16 +148,53 @@ export function isDocumentScriptPath(pathname) {
     return !last.includes(".");
 }
 /**
- * Decode a source map document. Index maps (`sections`) are not
- * supported and decode to `null`, as does anything malformed — the
+ * Decode flat and embedded index maps. Unsupported external section URLs
+ * and malformed maps decode to `null` — 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) {
+export function decodeSourceMap(doc, depth = 0) {
+    if (depth > 32)
+        return null;
     if (!doc || typeof doc !== "object")
         return null;
     const m = doc;
-    if (m.sections || !Array.isArray(m.sources) || typeof m.mappings !== "string") {
+    if (m.sections !== undefined) {
+        if (!Array.isArray(m.sections) || m.mappings !== undefined)
+            return null;
+        const out = { sources: [], lines: [] };
+        let previous;
+        for (const section of m.sections) {
+            const { line, column } = section?.offset ?? {};
+            if (section?.url !== undefined || !Number.isSafeInteger(line) || line < 0 ||
+                !Number.isSafeInteger(column) || column < 0 || line > 1_000_000 ||
+                (previous && (line < previous[0] || (line === previous[0] && column <= previous[1]))))
+                return null;
+            previous = [line, column];
+            const child = decodeSourceMap(section.map, depth + 1);
+            if (!child)
+                return null;
+            if (out.lines.some((segments, i) => i > line && segments.length > 0 ||
+                i === line && segments.some(s => s.col >= column)))
+                return null;
+            const base = out.sources.length;
+            for (const source of child.sources)
+                out.sources.push(source);
+            for (let i = 0; i < child.lines.length; i++) {
+                const target = line + i;
+                if (target > 1_000_000)
+                    return null;
+                while (out.lines.length <= target)
+                    out.lines.push([]);
+                for (const seg of child.lines[i])
+                    out.lines[target].push({
+                        col: seg.col + (i === 0 ? column : 0), src: seg.src + base, line: seg.line,
+                    });
+            }
+        }
+        return out;
+    }
+    if (!Array.isArray(m.sources) || typeof m.mappings !== "string") {
         return null;
     }
     const sourceRoot = typeof m.sourceRoot === "string" ? m.sourceRoot : undefined;
@@ -169,10 +211,16 @@ export function decodeSourceMap(doc) {
                     if (seg.length === 0)
                         continue;
                     const f = decodeVlq(seg);
+                    if (![1, 4, 5].includes(f.length))
+                        return null;
                     col += f[0];
+                    if (!Number.isSafeInteger(col) || col < 0)
+                        return null;
                     if (f.length >= 4) {
                         src += f[1];
                         line += f[2];
+                        if (src < 0 || src >= sources.length || !Number.isSafeInteger(line) || line < 0)
+                            return null;
                         segs.push({ col, src, line });
                     }
                 }

package/dist/harness/coverage.d.ts

@@ -32,6 +32,8 @@ export interface ServiceCoverageCapture {
      *  never has to fetch code to do so. Absent for a container it could
      *  not be read from. */
     root?: string;
+    /** Repository root of the service build/bundler workspace, when explicit. */
+    sourceRoot?: string;
     /** 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

package/dist/index.js

@@ -296,7 +296,7 @@ export function validateServiceImage(serviceName, input) {
         if (typeof image.context !== "string" || image.context === "") {
             throw new Error(`service "${serviceName}" image context must be a directory path relative to the project root (\`"."\` for the root)`);
         }
-        const dir = resolveExistingProjectPath(image.context, `service "${serviceName}" build context`);
+        const dir = resolveExistingProjectPath(image.context, `service "${serviceName}" build context`, { record: false });
         if (!statSync(dir).isDirectory()) {
             throw new Error(`service "${serviceName}" build context ${JSON.stringify(image.context)} is not a directory`);
         }

package/dist/project-files.d.ts

@@ -20,4 +20,6 @@ export declare function resolveProjectPath(p: string, opts?: {
 /** {@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. */
-export declare function resolveExistingProjectPath(p: string, what?: string): string;
+export declare function resolveExistingProjectPath(p: string, what?: string, opts?: {
+    record?: boolean;
+}): string;

package/dist/project-files.js

@@ -68,8 +68,8 @@ export function resolveProjectPath(p, opts = {}) {
 /** {@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. */
-export function resolveExistingProjectPath(p, what = "file") {
-    const resolved = resolveProjectPath(p);
+export function resolveExistingProjectPath(p, what = "file", opts = {}) {
+    const resolved = resolveProjectPath(p, opts);
     if (existsSync(resolved))
         return resolved;
     const rel = relative(p);

package/package.json

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

package/src/coverage.test.ts

@@ -51,6 +51,14 @@ describe("validateCoverage", () => {
     expect(() => validateCoverage("a", { adapters: [], extra: 1 })).toThrow(/invalid `coverage` value/);
     expect(() => validateCoverage("a", {})).toThrow(/invalid `coverage` value/);
   });
+  test("sourceRoot is explicit, validated, and survives adapter wire serialization", () => {
+    const out = applyCoverageAdapters("web", { ...base, coverage: { adapters: [node(), browser()], sourceRoot: "packages" } });
+    expect(JSON.parse(JSON.stringify(out)).coverage.sourceRoot).toBe("packages");
+    expect(() => validateCoverage("web", out.coverage)).not.toThrow();
+    for (const sourceRoot of ["", "/packages", "../packages", "packages//dashboard", "packages/./dashboard", "C:\\app", "bad\0root"]) {
+      expect(() => validateCoverage("web", { adapters: [node()], sourceRoot })).toThrow();
+    }
+  });
   test("reports mode: cumulative unless declared; the shipped adapters write deltas", () => {
     expect(coverageReportsMode(undefined)).toBe("cumulative");
     expect(coverageReportsMode(true)).toBe("cumulative");
@@ -375,6 +383,76 @@ describe.if(hasNode)("nodeCoverage hook (real node)", () => {
     expect(new Set(all.map((s) => s.spectestScript))).toEqual(ids);
   });
 
+  test("declared generated entrypoints are content-addressed units in capture and inventory", async () => {
+    const dir = await scratch();
+    const adapter = node({ generated: ["server.js"] });
+    const config = adapter.configure!({ ...base, env: {} }, {key: "web"});
+    const env = {...hookEnv(dir), SPECTEST_COVERAGE_SERVICE: config.env!.SPECTEST_COVERAGE_SERVICE!,
+      SPECTEST_COVERAGE_GENERATED_FILES: config.env!.SPECTEST_COVERAGE_GENERATED_FILES!};
+    async function inventory() {
+      return adapter.inventory!({ service: "web", projectFiles: async () => [], readProjectFile: async () => null,
+        signal: new AbortController().signal,
+        async exec(command) {
+          const proc = Bun.spawn(["sh", "-c", command], {cwd:dir, stdout:"pipe", stderr:"pipe"});
+          const stdout = await new Response(proc.stdout).text();
+          const stderr = await new Response(proc.stderr).text();
+          if (await proc.exited !== 0) throw new Error(stderr);
+          return {stdout,stderr};
+        }
+      });
+    }
+    async function run() {
+      const child = spawn("node", [path.join(dir,"server.js")], {cwd:dir,env,stdio:"ignore"});
+      expect(await new Promise(r => child.on("exit",r))).toBe(0);
+    }
+    await fs.writeFile(path.join(dir,"server.js"), "globalThis.value = 1;\n");
+    const first = await inventory();
+    expect(first).toHaveLength(1);
+    expect(first[0]).toMatch(/^generated:web:server.js#[a-f0-9]{64}$/);
+    await run();
+    const dump = await readDump(dir,(await dumpsIn(dir))[0]!);
+    expect((dump as Dump & {units:string[]}).units).toEqual(first);
+    expect(dump.result).toEqual([]);
+    expect((await records(dir)).size).toBe(0);
+    await fs.writeFile(path.join(dir,"server.js"), "globalThis.value = 2;\n");
+    expect(await inventory()).not.toEqual(first);
+    expect(() => node({generated:["../server.js"]})).toThrow();
+  });
+
+  test("collected VM contexts retain their compiled source with a bounded debugger cache", async () => {
+    const dir = await scratch();
+    await fs.writeFile(path.join(dir, "main.js"), `
+      const vm = require("node:vm");
+      new vm.Script("globalThis.value = 42; /*" + "x".repeat(8 * 1024 * 1024) + "*/", {
+        filename: "file:///tmp/workflow-bundle.js"
+      }).runInNewContext();
+      for (let i = 0; i < 3; i++) global.gc();
+    `);
+    const child = spawn("node", ["--expose-gc", path.join(dir, "main.js")], { env: hookEnv(dir), stdio: "ignore" });
+    expect(await new Promise(r => child.on("exit", r))).toBe(0);
+    const rec = (await records(dir)).get("file:///tmp/workflow-bundle.js")!;
+    expect(rec.lineLengths?.length).toBe(1);
+    expect(rec.lineLengths![0]).toBeGreaterThan(8 * 1024 * 1024);
+    expect(JSON.stringify(rec).length).toBeLessThan(1024);
+  });
+
+  test("indexed maps retain offsets and dependency units and strip nested source contents", async () => {
+    const dir = await scratch();
+    await fs.writeFile(path.join(dir, "main.js"), "globalThis.value = 1;\n");
+    const leaf = { version: 3, sources: ["turbopack:///[project]/dashboard/page.ts", "webpack:///node_modules/pkg/a.js"],
+      sourcesContent: ["secret application source", "dependency source"], mappings: "AAAA,CCAA" };
+    await fs.writeFile(path.join(dir, "main.js.map"), JSON.stringify({ version: 3, sections: [
+      { offset: { line: 0, column: 0 }, map: { version: 3, sections: [{ offset: { line: 0, column: 0 }, map: leaf }] } }
+    ] }));
+    expect(await runOnce(dir, "main.js")).toBe(0);
+    const rec = (await records(dir)).get(`file://${path.join(dir, "main.js")}`)!;
+    const text = JSON.stringify(rec.sourceMap);
+    expect(text).not.toContain("sourcesContent");
+    expect(text).not.toContain("secret application source");
+    expect(text).toContain('"x_spectestSourceUnits":[null,"npm:pkg"]');
+    expect(text).toContain('"offset":{"line":0,"column":0}');
+  });
+
   test("short-lived CLI processes write at exit; the map next to the script is recorded once, no NODE_V8_COVERAGE", async () => {
     const dir = await scratch();
     await fs.writeFile(path.join(dir, "cli.js"), "function used() { return 1 }\nfunction unused() { return 2 }\nused();\n");

package/src/coverage.ts

@@ -164,7 +164,14 @@ export const INVENTORY_REPORT = "inventory.units";
  *  program itself writes count (`reports`, default `"cumulative"`). */
 export type ServiceCoverage =
   | true
-  | { adapters?: readonly CoverageAdapter[]; reports?: CoverageReportsMode };
+  | {
+      adapters?: readonly CoverageAdapter[];
+      reports?: CoverageReportsMode;
+      /** Repository-relative root of this service's build/bundler workspace.
+       * For a monorepo built from packages/, set sourceRoot: "packages".
+       * Paths are checked against the repository; no suffix guessing. */
+      sourceRoot?: string;
+    };
 
 /** The `reports` mode of a `coverage` value, for the reports no adapter
  *  wrote (the program's own, a `command`'s). */
@@ -184,14 +191,19 @@ export function validateCoverage(service: string, cov: unknown): void {
   const obj = typeof cov === "object" && cov !== null ? (cov as Record<string, unknown>) : null;
   const adapters = obj?.adapters;
   const reports = obj?.reports;
+  const sourceRoot = obj?.sourceRoot;
   // `explains` is what `applyCoverageAdapters` adds for the wire; the
   // config is validated again after that, so it must pass here.
   const explains = obj?.explains;
-  const knownKeys = obj !== null && Object.keys(obj).every((k) => k === "adapters" || k === "reports" || k === "explains");
+  const knownKeys = obj !== null && Object.keys(obj).every((k) => k === "adapters" || k === "reports" || k === "explains" || k === "sourceRoot");
+  const okRoot = sourceRoot === undefined || (typeof sourceRoot === "string" &&
+    (sourceRoot === "." || (sourceRoot.length > 0 && !sourceRoot.includes("\\") &&
+      !sourceRoot.includes(":") && !sourceRoot.includes("\0") &&
+      sourceRoot.split("/").every(p => p !== "" && p !== "." && p !== ".."))));
   const okReports = reports === undefined || reports === "delta" || reports === "cumulative";
   const okAdapters = adapters === undefined || Array.isArray(adapters);
   const okExplains = explains === undefined || (Array.isArray(explains) && explains.every((e) => typeof e === "string"));
-  if (obj !== null && knownKeys && okReports && okAdapters && okExplains && (adapters !== undefined || reports !== undefined)) {
+  if (obj !== null && knownKeys && okRoot && okReports && okAdapters && okExplains && (adapters !== undefined || reports !== undefined)) {
     for (const a of (adapters as unknown[] | undefined) ?? []) {
       const ok =
         typeof a === "object" &&
@@ -246,7 +258,9 @@ export function applyCoverageAdapters<S extends ServiceConfig>(key: string, svc:
   // `explains` rides the wire config so the control plane's selector can
   // read it without knowing any adapter.
   const explains = [...new Set(adapters.flatMap((a) => a.explains ?? []))];
+  const sourceRoot = typeof svc.coverage === "object" ? svc.coverage.sourceRoot : undefined;
   const wire = {
+    ...(sourceRoot !== undefined ? { sourceRoot } : {}),
     adapters: adapters.map((a) => withWireName(a)),
     ...(mode ? { reports: mode } : {}),
     ...(explains.length > 0 ? { explains } : {}),
@@ -387,6 +401,21 @@ export const NODE_COVERAGE_HOOK = `"use strict";
   if (post("Profiler.enable") === null) return;
   post("Profiler.startPreciseCoverage", { callCount: true, detailed: true });
 
+  // Attach before app scripts execute. Enabling only at capture loses the
+  // source of collected vm contexts (e.g. Temporal workflow bundles).
+  // Bound V8's collected-script cache; live sources remain owned by V8.
+  post("Debugger.enable", { maxScriptsCacheSize: 16 * 1024 * 1024 });
+
+  const GENERATED = new Map();
+  try {
+    for (const file of JSON.parse(process.env.SPECTEST_COVERAGE_GENERATED_FILES || "[]")) {
+      GENERATED.set(url.pathToFileURL(path.resolve(file)).href, file);
+    }
+  } catch (e) {}
+  const generatedUnits = new Map();
+  function generatedUnit(file, text) {
+    return "generated:" + process.env.SPECTEST_COVERAGE_SERVICE + ":" + file + "#" + crypto.createHash("sha256").update(text).digest("hex");
+  }
   const SELF = url.pathToFileURL(__filename).href;
   const SCRIPTS = path.join(dir, ${JSON.stringify(NODE_COVERAGE_SCRIPTS_SUBDIR)});
   const MARKERS = path.join(dir, ${JSON.stringify(NODE_COVERAGE_MARKERS_SUBDIR)});
@@ -493,31 +522,47 @@ export const NODE_COVERAGE_HOOK = `"use strict";
     } catch (e) {
       return null;
     }
-    if (!data || typeof data !== "object" || !("mappings" in data)) return null;
-    delete data.sourcesContent;
     // A source inside node_modules is a dependency: its unit id rides
     // beside the map (\`sourceUnits[i]\`, null for the project's own), so
     // the control plane never has to know what node_modules is.
     const mapDir = mapUrl ? path.dirname(url.fileURLToPath(mapUrl)) : path.dirname(scriptPath);
-    const root = typeof data.sourceRoot === "string" && data.sourceRoot ? data.sourceRoot : "";
-    const sourceUnits = (Array.isArray(data.sources) ? data.sources : []).map(function (src) {
-      if (typeof src !== "string") return null;
-      let abs;
-      if (src.startsWith("file://")) {
-        try {
-          abs = url.fileURLToPath(src);
-        } catch (e) {
-          return null;
+    function sourceUnits(data) {
+      const root = typeof data.sourceRoot === "string" ? data.sourceRoot : "";
+      return data.sources.map(function (src) {
+        if (typeof src !== "string") return null;
+        let abs;
+        if (src.startsWith("file://")) {
+          try {
+            abs = url.fileURLToPath(src);
+          } catch (e) {
+            return null;
+          }
+        } else if (/^[a-z][a-z0-9+.-]*:/i.test(src)) {
+          return src.indexOf("/node_modules/") >= 0 ? unitFromText(src) : null;
+        } else {
+          const rel = root && !src.startsWith("/") ? root.replace(/\\/$/, "") + "/" + src : src;
+          abs = path.resolve(mapDir, rel);
         }
-      } else if (/^[a-z][a-z0-9+.-]*:/i.test(src)) {
-        return src.indexOf("/node_modules/") >= 0 ? unitFromText(src) : null;
-      } else {
-        const rel = root && !src.startsWith("/") ? root.replace(/\\/$/, "") + "/" + src : src;
-        abs = path.resolve(mapDir, rel);
+        return abs.indexOf("/node_modules/") >= 0 ? unitOf(abs) : null;
+      });
+    }
+    function prepareMap(data, depth) {
+      if (!data || typeof data !== "object" || depth > 32) return false;
+      delete data.sourcesContent;
+      if (Array.isArray(data.sections)) {
+        if ("mappings" in data) return false;
+        return data.sections.every(function (section) {
+          return section && !section.url && prepareMap(section.map, depth + 1);
+        });
       }
-      return abs.indexOf("/node_modules/") >= 0 ? unitOf(abs) : null;
-    });
-    return { url: mapUrl, data: data, sourceUnits: sourceUnits };
+      if (!Array.isArray(data.sources) || typeof data.mappings !== "string") return false;
+      data.x_spectestSourceUnits = sourceUnits(data);
+      return true;
+    }
+    if (!prepareMap(data, 0)) return null;
+    const units = data.x_spectestSourceUnits;
+    delete data.x_spectestSourceUnits;
+    return { url: mapUrl, data: data, sourceUnits: units };
   }
   function writeAtomic(file, text) {
     const tmp = file + "." + process.pid + "-" + wt.threadId + ".tmp";
@@ -566,34 +611,44 @@ export const NODE_COVERAGE_HOOK = `"use strict";
     if (kept.length === 0 && units.size === 0) return;
     const fresh = [];
     for (const s of kept) {
-      if (!known.has(s.scriptId)) fresh.push(s);
+      if (!known.has(s.scriptId) && !generatedUnits.has(s.scriptId)) fresh.push(s);
     }
     if (fresh.length > 0) {
       try {
         fs.mkdirSync(SCRIPTS, { recursive: true });
         fs.mkdirSync(MARKERS, { recursive: true });
       } catch (e) {}
-      post("Debugger.enable");
       for (const s of fresh) {
         const r = post("Debugger.getScriptSource", { scriptId: s.scriptId });
         try {
-          known.set(s.scriptId, describe(s, r && r.scriptSource));
+          const source = r && r.scriptSource;
+          if (GENERATED.has(s.url) && typeof source === "string") {
+            generatedUnits.set(s.scriptId, generatedUnit(GENERATED.get(s.url), source));
+            continue;
+          }
+          const id = describe(s, source);
+          // A failed source fetch remains visible in this dump, but is not
+          // memoized as a successful descriptor for subsequent captures.
+          if (typeof source === "string") known.set(s.scriptId, id);
+          s.missingSourceRecord = id;
         } catch (e) {}
       }
-      post("Debugger.disable");
     }
     // A ran function is one flat array: [start, length, count] for its
     // extent (V8's first range), then [offset from start, length, count]
     // per block range in V8's order. Small numbers, so the dump gzips to
     // less than half of V8's own JSON; name and block flag live in the
     // script record, joined on the extent.
+    for (const s of kept) {
+      if (generatedUnits.has(s.scriptId)) units.add(generatedUnits.get(s.scriptId));
+    }
     const doc = {
       spectestVersion: 2,
       units: Array.from(units).sort(),
-      result: kept.map(function (s) {
+      result: kept.filter(function (s) { return !generatedUnits.has(s.scriptId); }).map(function (s) {
         return {
           url: s.url,
-          spectestScript: known.get(s.scriptId) || null,
+          spectestScript: known.get(s.scriptId) || s.missingSourceRecord || null,
           functions: s.functions.filter(ran).map(function (f) {
             const first = f.ranges[0];
             const out = [first.startOffset, first.endOffset - first.startOffset, first.count];
@@ -774,7 +829,22 @@ for (;;) {
 process.stdout.write(Array.from(out).sort().join("\\n") + (out.size ? "\\n" : ""));
 `;
 
-export function node(): CoverageAdapter {
+export interface NodeCoverageOptions {
+  /** Generated runtime entrypoints, relative to the service working directory.
+   * Track their exact contents as units rather than inventing repository lines.
+   * A content change changes the inventory and invalidates dependent tests. */
+  generated?: readonly string[];
+}
+
+export function node(options: NodeCoverageOptions = {}): CoverageAdapter {
+  if (options.generated !== undefined && (!Array.isArray(options.generated) || options.generated.some(p => typeof p !== "string"))) {
+    throw new Error("coverage.node generated must be a list of relative files");
+  }
+  const generated: string[] = [...new Set<string>(options.generated ?? [])].sort();
+  if (generated.some(p => !p || p.includes("\\") || p.includes(":") || p.includes("\0") ||
+      p.split("/").some(c => !c || c === "." || c === ".."))) {
+    throw new Error("coverage.node generated paths must be relative files without traversal");
+  }
   return {
     name: "node",
     reports: "delta",
@@ -786,6 +856,14 @@ export function node(): CoverageAdapter {
       const b64 = Buffer.from(NODE_INVENTORY_SCRIPT).toString("base64");
       const r = await ctx.exec(`echo ${b64} | base64 -d | node -`);
       const units = new Set<string>(r.stdout.split("\n").map((l) => l.trim()).filter((l) => l.startsWith("npm:")));
+      if (generated.length) {
+        const script = `const fs=require("node:fs"),crypto=require("node:crypto");
+          for(const file of ${JSON.stringify(generated)}) console.log(
+            ${JSON.stringify("generated:" + ctx.service + ":")} + file + "#" +
+            crypto.createHash("sha256").update(fs.readFileSync(file)).digest("hex"));`;
+        const result = await ctx.exec(`echo ${Buffer.from(script).toString("base64")} | base64 -d | node -`);
+        for (const unit of result.stdout.trim().split("\n")) if (unit) units.add(unit);
+      }
       for (const f of await ctx.projectFiles()) {
         if (f !== "package.json" && !f.endsWith("/package.json")) continue;
         const text = await ctx.readProjectFile(f);
@@ -793,9 +871,13 @@ export function node(): CoverageAdapter {
       }
       return [...units].sort();
     },
-    configure(svc) {
+    configure(svc, info) {
       const env = appendEnvFlag(svc.env, "NODE_OPTIONS", `--require ${NODE_COVERAGE_HOOK_PATH}`);
       env[NODE_COVERAGE_DIR_ENV] = COVERAGE_CONTAINER_DIR;
+      if (generated.length) {
+        env.SPECTEST_COVERAGE_GENERATED_FILES = JSON.stringify(generated);
+        env.SPECTEST_COVERAGE_SERVICE = info.key;
+      }
       return {
         ...svc,
         env,

package/src/daemon.ts

@@ -1351,7 +1351,7 @@ async function resolveDockerfileBuild(svc: NamedService): Promise<DockerfileBuil
     throw new Error(`service "${svc.name}" image is not a Dockerfile build`);
   }
   const contextRel = image.context ?? ".";
-  const contextDir = resolveExistingProjectPath(contextRel, `service "${svc.name}" build context`);
+  const contextDir = resolveExistingProjectPath(contextRel, `service "${svc.name}" build context`, { record: false });
   let content: string;
   let adjacent: string | null = null;
   let adjacentPath: string | null = null;
@@ -1576,7 +1576,10 @@ async function runServiceBuild(
       buildArgs = ["build", ...argFlags, "-t", tag, "-f", dfPath, contextDir];
     }
     progressService(name, { status: "building", detail: "starting build" });
-    const build = await shxStream("docker", buildArgs, 1_800_000, buildEnv, (line) => {
+    // The controller owns the bootstrap/prepareImages deadline and tears
+    // down the VM on expiry. A separate build timer would cut short an
+    // environment's explicit timeoutSecs allowance (e.g. long Rust builds).
+    const build = await shxStream("docker", buildArgs, undefined, buildEnv, (line) => {
       // BuildKit `--progress=plain` declares each step as
       // `#N [<stage> M/N] <cmd>`; the legacy builder as `Step M/N : <cmd>`.
       // Track the most-recent step as live detail.
@@ -4068,6 +4071,9 @@ async function captureServiceCoverage(baseline = false): Promise<ServiceCoverage
       }
       const root = await coverageRoot(svc.name);
       if (root) read.root = root;
+      if (typeof svc.coverage === "object" && svc.coverage.sourceRoot !== undefined) {
+        read.sourceRoot = svc.coverage.sourceRoot;
+      }
       // What ships is what ran during this capture, whatever the tool
       // counts: cumulative lcov is subtracted against the previous
       // capture (module memory, forks with the env); a delta adapter's

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

@@ -48,8 +48,8 @@ describe("source maps", () => {
     expect(files.get("src/b.ts")!.get(5)).toBe(0);
   });
 
-  test("index maps and garbage decode to null", () => {
-    expect(decodeSourceMap({ version: 3, sections: [] })).toBeNull();
+  test("empty index maps are generated code; malformed maps remain unresolved", () => {
+    expect(decodeSourceMap({ version: 3, sections: [] })).toEqual({ sources: [], lines: [] });
     expect(decodeSourceMap({ version: 3, sources: ["a"], mappings: "!!" })).toBeNull();
     expect(decodeSourceMap("nope")).toBeNull();
   });
@@ -112,3 +112,18 @@ describe("turbopack + inline scripts", () => {
     expect(isDocumentScriptPath("/app.js")).toBe(false);
   });
 });
+
+test("nested indexed maps apply section line and column offsets and reject overlaps", () => {
+  const leaf = { version: 3, sources: ["turbopack:///[project]/dashboard/a.ts"], mappings: "AAAA;AACA" };
+  const doc = { version: 3, sections: [
+    { offset: { line: 1, column: 3 }, map: { version: 3, sections: [{offset: {line: 0, column: 2}, map: leaf}] } },
+    { offset: { line: 3, column: 0 }, map: { version: 3, sources: ["b.ts"], mappings: "AAAA" } },
+  ] };
+  const map = decodeSourceMap(doc)!;
+  expect(map.lines).toEqual([[], [{col:5, src:0, line:0}], [{col:0, src:0, line:1}], [{col:0, src:1, line:0}]]);
+  expect([...mapToOriginal(map, new Map([[2,1],[3,2],[4,3]])).keys()]).toEqual([leaf.sources[0], "b.ts"]);
+  expect(decodeSourceMap({version:3,sections:[{offset:{line:0,column:0},url:"remote.map"}]})).toBeNull();
+  expect(decodeSourceMap({...doc,sections:[doc.sections[1],doc.sections[0]]})).toBeNull();
+  expect(isForeignSource("turbopack:///[turbopack]/browser/runtime/base/runtime-base.ts")).toBe(true);
+  expect(isForeignSource("turbopack:///[project]/turbopack/runtime.ts")).toBe(false);
+});

package/src/harness/browser-coverage.ts

@@ -115,6 +115,7 @@ export function decodeVlq(segment: string): number[] {
       shift = 0;
     }
   }
+  if (shift !== 0) throw new Error("unterminated VLQ");
   return out;
 }
 
@@ -152,6 +153,8 @@ export function normalizeSourcePath(src: string, sourceRoot?: string): string {
 /** Sources nobody's change can be attributed to: dependencies and bundler
  *  runtime shims. */
 export function isForeignSource(path: string): boolean {
+  // Preserve project namespaces; only the explicit Turbopack runtime is foreign.
+  if (path.startsWith("turbopack:///[turbopack]/")) return true;
   return (
     path.length === 0 ||
     path.includes("node_modules/") ||
@@ -178,12 +181,13 @@ export function isDocumentScriptPath(pathname: string): boolean {
 }
 
 /**
- * Decode a source map document. Index maps (`sections`) are not
- * supported and decode to `null`, as does anything malformed — the
+ * Decode flat and embedded index maps. Unsupported external section URLs
+ * and malformed maps decode to `null` — 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 {
+export function decodeSourceMap(doc: unknown, depth = 0): DecodedSourceMap | null {
+  if (depth > 32) return null;
   if (!doc || typeof doc !== "object") return null;
   const m = doc as {
     version?: number;
@@ -192,7 +196,34 @@ export function decodeSourceMap(doc: unknown): DecodedSourceMap | null {
     mappings?: unknown;
     sections?: unknown;
   };
-  if (m.sections || !Array.isArray(m.sources) || typeof m.mappings !== "string") {
+  if (m.sections !== undefined) {
+    if (!Array.isArray(m.sections) || m.mappings !== undefined) return null;
+    const out: DecodedSourceMap = { sources: [], lines: [] };
+    let previous: [number, number] | undefined;
+    for (const section of m.sections) {
+      const { line, column } = section?.offset ?? {};
+      if (section?.url !== undefined || !Number.isSafeInteger(line) || line < 0 ||
+          !Number.isSafeInteger(column) || column < 0 || line > 1_000_000 ||
+          (previous && (line < previous[0] || (line === previous[0] && column <= previous[1])))) return null;
+      previous = [line, column];
+      const child = decodeSourceMap(section.map, depth + 1);
+      if (!child) return null;
+      if (out.lines.some((segments, i) => i > line && segments.length > 0 ||
+          i === line && segments.some(s => s.col >= column))) return null;
+      const base = out.sources.length;
+      for (const source of child.sources) out.sources.push(source);
+      for (let i = 0; i < child.lines.length; i++) {
+        const target = line + i;
+        if (target > 1_000_000) return null;
+        while (out.lines.length <= target) out.lines.push([]);
+        for (const seg of child.lines[i]!) out.lines[target]!.push({
+          col: seg.col + (i === 0 ? column : 0), src: seg.src + base, line: seg.line,
+        });
+      }
+    }
+    return out;
+  }
+  if (!Array.isArray(m.sources) || typeof m.mappings !== "string") {
     return null;
   }
   const sourceRoot = typeof m.sourceRoot === "string" ? m.sourceRoot : undefined;
@@ -210,10 +241,13 @@ export function decodeSourceMap(doc: unknown): DecodedSourceMap | null {
         for (const seg of group.split(",")) {
           if (seg.length === 0) continue;
           const f = decodeVlq(seg);
+          if (![1,4,5].includes(f.length)) return null;
           col += f[0];
+          if (!Number.isSafeInteger(col) || col < 0) return null;
           if (f.length >= 4) {
             src += f[1];
             line += f[2];
+            if (src < 0 || src >= sources.length || !Number.isSafeInteger(line) || line < 0) return null;
             segs.push({ col, src, line });
           }
         }

package/src/harness/coverage.ts

@@ -76,6 +76,8 @@ export interface ServiceCoverageCapture {
    *  never has to fetch code to do so. Absent for a container it could
    *  not be read from. */
   root?: string;
+  /** Repository root of the service build/bundler workspace, when explicit. */
+  sourceRoot?: string;
   /** 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

package/src/index.ts

@@ -1384,7 +1384,7 @@ export function validateServiceImage(serviceName: string, input: ServiceImage):
         `service "${serviceName}" image context must be a directory path relative to the project root (\`"."\` for the root)`,
       );
     }
-    const dir = resolveExistingProjectPath(image.context, `service "${serviceName}" build context`);
+    const dir = resolveExistingProjectPath(image.context, `service "${serviceName}" build context`, { record: false });
     if (!statSync(dir).isDirectory()) {
       throw new Error(
         `service "${serviceName}" build context ${JSON.stringify(image.context)} is not a directory`,

package/src/project-files.test.ts

@@ -0,0 +1,25 @@
+import { expect, test } from "bun:test";
+import { mkdtemp, mkdir, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+test("resolving a build context records no directory read, while source files remain covered", async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "spectest-project-reads-"));
+  try {
+    await mkdir(path.join(dir, "packages"));
+    await writeFile(path.join(dir, "packages/Dockerfile"), "FROM scratch\n");
+    const module = new URL("./project-files.ts", import.meta.url).pathname;
+    const script = `import {resolveExistingProjectPath,takeProjectReads} from ${JSON.stringify(module)};
+      import {validateServiceImage} from ${JSON.stringify(new URL("./index.ts", import.meta.url).pathname)};
+      resolveExistingProjectPath(".","build context",{record:false});
+      resolveExistingProjectPath("packages","build context",{record:false});
+      validateServiceImage("web",{type:"dockerfile",context:"packages",path:"packages/Dockerfile"});
+      console.log(JSON.stringify(takeProjectReads()));`;
+    const proc = Bun.spawn([process.execPath, "-e", script], {
+      env: {...process.env, SPECTEST_WORKSPACE:dir}, stdout:"pipe", stderr:"pipe",
+    });
+    const text = await new Response(proc.stdout).text();
+    expect(await proc.exited).toBe(0);
+    expect(JSON.parse(text)).toEqual(["packages/Dockerfile"]);
+  } finally { await rm(dir, {recursive:true, force:true}); }
+});

package/src/project-files.ts

@@ -72,8 +72,8 @@ export function resolveProjectPath(p: string, opts: { record?: boolean } = {}):
 /** {@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. */
-export function resolveExistingProjectPath(p: string, what = "file"): string {
-  const resolved = resolveProjectPath(p);
+export function resolveExistingProjectPath(p: string, what = "file", opts: { record?: boolean } = {}): string {
+  const resolved = resolveProjectPath(p, opts);
   if (existsSync(resolved)) return resolved;
   const rel = relative(p);
   const looked = path.isAbsolute(p)