@specific.dev/spectest 0.82.0 → 0.85.0

package/dist/coverage.js

@@ -26,6 +26,7 @@
 //
 //   import * as coverage from "@specific.dev/spectest/coverage";
 //   coverage: { adapters: [coverage.node(), coverage.browser()] }
+import { createHash } from "node:crypto";
 import { harvestAllBrowserCoverage, takeBrowserCoverageReports } from "./browser-coverage.js";
 import { COVERAGE_CONTAINER_DIR } from "./harness/coverage.js";
 export { COVERAGE_CONTAINER_DIR };
@@ -36,6 +37,9 @@ export const NODE_COVERAGE_EMPTY_REPORT = "coverage-spectest-empty.json";
 /** Prefix of the per-process sockets the node hook answers on, relative
  *  to the coverage dir: `.ctl-<pid>`. */
 export const NODE_COVERAGE_SOCKET_PREFIX = ".ctl-";
+/** The report name the harness writes an adapter's inventory to, in the
+ *  bring-up capture only. */
+export const INVENTORY_REPORT = "inventory.units";
 /** The `reports` mode of a `coverage` value, for the reports no adapter
  *  wrote (the program's own, a `command`'s). */
 export function coverageReportsMode(cov) {
@@ -65,10 +69,13 @@ export function validateCoverage(service, cov) {
                 (a.reports === undefined ||
                     a.reports === "delta" ||
                     a.reports === "cumulative") &&
-                ["configure", "load", "capture"].every((k) => a[k] === undefined ||
+                (a.explains === undefined ||
+                    (Array.isArray(a.explains) &&
+                        a.explains.every((e) => typeof e === "string"))) &&
+                ["configure", "load", "capture", "inventory"].every((k) => a[k] === undefined ||
                     typeof a[k] === "function");
             if (!ok) {
-                throw new Error(`service "${service}" has an invalid coverage adapter — an adapter is \`{ name, reports?, configure?, load?, capture? }\` (see \`defineAdapter\` in @specific.dev/spectest/coverage)`);
+                throw new Error(`service "${service}" has an invalid coverage adapter — an adapter is \`{ name, reports?, explains?, configure?, load?, capture?, inventory? }\` (see \`defineAdapter\` in @specific.dev/spectest/coverage)`);
             }
         }
         return;
@@ -97,7 +104,14 @@ export function applyCoverageAdapters(key, svc) {
             out = a.configure(out, { key });
     }
     const mode = svc.coverage.reports;
-    const wire = { adapters: adapters.map((a) => withWireName(a)), ...(mode ? { reports: mode } : {}) };
+    // `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 wire = {
+        adapters: adapters.map((a) => withWireName(a)),
+        ...(mode ? { reports: mode } : {}),
+        ...(explains.length > 0 ? { explains } : {}),
+    };
     return { ...out, coverage: wire };
 }
 function withWireName(a) {
@@ -153,12 +167,21 @@ export const NODE_COVERAGE_DUMP_PREFIX = "node-";
  *   counters: every dump is the delta since the previous take. No
  *   signal is used: signals are claimed by frameworks (SIGUSR2 stops a
  *   Temporal worker, restarts nodemon), a socket is nobody's.
+ * - Reports **dependencies as units**: a ran script under `node_modules`
+ *   becomes `npm:<name>@<version>` (from the nearest package.json, or the
+ *   path's text) in the dump's `units`; a bundled script's map sources
+ *   under `node_modules` become `sourceUnits` beside the map in its
+ *   record. The control plane compares unit ids by equality and never
+ *   learns what `node_modules` is.
  * - Writes a **dump** `node-<pid>-<thread>-<ms>-<n>.json`: the app's own
  *   scripts (`file://`, outside `node_modules` and `.cache`, not the
  *   hook) in which some range count is above zero, and of each only the
- *   functions that ran, ranges and counts as V8 reported them. Nothing
- *   when nothing ran. Still a V8 coverage document (`result`), plus
- *   `spectestScript` on each script naming its record.
+ *   functions that ran, each 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. Name and block flag
+ *   are in the record, joined on the extent. Nothing when nothing ran.
+ *   `{ spectestVersion: 2, result: [{ url, spectestScript, functions:
+ *   [[s, l, c, o, l, c, …], …] }] }`.
  * - Writes, **once per script per branch**, a **script record**
  *   `scripts/<id>.json` (`id` = sha256 of the URL): the length of every
  *   line of the source V8 compiled (`Debugger.getScriptSource`, so a
@@ -221,6 +244,48 @@ export const NODE_COVERAGE_HOOK = `"use strict";
   function isApp(u) {
     return typeof u === "string" && u.startsWith("file://") && u.indexOf("/node_modules/") < 0 && u.indexOf("/.cache/") < 0 && u !== SELF;
   }
+  function isDep(u) {
+    return typeof u === "string" && u.startsWith("file://") && u.indexOf("/node_modules/") >= 0 && u !== SELF;
+  }
+  // A dependency's unit id, npm:<name>@<version>, from the nearest
+  // package.json above a path inside node_modules (read once per
+  // directory); when the file is not on disk (a bundled dependency whose
+  // sources a multi-stage image dropped), from the path's text.
+  const UNIT_CACHE = new Map();
+  function unitFromText(p) {
+    let m = /\\/node_modules\\/\\.pnpm\\/((?:@[^/@+]+\\+)?[^/@]+)@([^/_]+)/.exec(p);
+    if (m) return "npm:" + m[1].replace("+", "/") + "@" + m[2];
+    m = /\\/node_modules\\/(@[^/]+\\/[^/]+|[^/@.][^/]*)(?:\\/|$)/.exec(p);
+    return m ? "npm:" + m[1] : null;
+  }
+  function unitOf(p) {
+    if (p.indexOf("/node_modules/") < 0) return null;
+    // Walk up to the innermost node_modules boundary and no further: the
+    // directories above it are shared with every other package, so a
+    // cached answer must never sit on them.
+    const visited = [];
+    let d = path.dirname(p);
+    while (d && d !== "/" && path.basename(d) !== "node_modules") {
+      if (UNIT_CACHE.has(d)) {
+        const hit = UNIT_CACHE.get(d);
+        for (const v of visited) UNIT_CACHE.set(v, hit);
+        return hit;
+      }
+      visited.push(d);
+      try {
+        const pj = JSON.parse(fs.readFileSync(path.join(d, "package.json"), "utf8"));
+        if (pj && typeof pj.name === "string" && pj.name) {
+          const u = "npm:" + pj.name + (typeof pj.version === "string" && pj.version ? "@" + pj.version : "");
+          for (const v of visited) UNIT_CACHE.set(v, u);
+          return u;
+        }
+      } catch (e) {}
+      d = path.dirname(d);
+    }
+    const u = unitFromText(p);
+    for (const v of visited) UNIT_CACHE.set(v, u);
+    return u;
+  }
   function ran(f) {
     return f.ranges.some(function (r) { return r.count > 0; });
   }
@@ -276,7 +341,29 @@ export const NODE_COVERAGE_HOOK = `"use strict";
     }
     if (!data || typeof data !== "object" || !("mappings" in data)) return null;
     delete data.sourcesContent;
-    return { url: mapUrl, data: data };
+    // 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;
+        }
+      } 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;
+    });
+    return { url: mapUrl, data: data, sourceUnits: sourceUnits };
   }
   function writeAtomic(file, text) {
     const tmp = file + "." + process.pid + "-" + wt.threadId + ".tmp";
@@ -307,10 +394,19 @@ export const NODE_COVERAGE_HOOK = `"use strict";
     const res = post("Profiler.takePreciseCoverage");
     if (!res || !Array.isArray(res.result)) return;
     const kept = [];
+    const units = new Set();
     for (const s of res.result) {
-      if (isApp(s.url) && Array.isArray(s.functions) && s.functions.some(ran)) kept.push(s);
+      if (!Array.isArray(s.functions) || !s.functions.some(ran)) continue;
+      if (isApp(s.url)) kept.push(s);
+      else if (isDep(s.url)) {
+        let u = null;
+        try {
+          u = unitOf(url.fileURLToPath(s.url));
+        } catch (e) {}
+        if (u) units.add(u);
+      }
     }
-    if (kept.length === 0) return;
+    if (kept.length === 0 && units.size === 0) return;
     const fresh = [];
     for (const s of kept) {
       if (known.has(s.url)) continue;
@@ -331,10 +427,28 @@ export const NODE_COVERAGE_HOOK = `"use strict";
       }
       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.
     const doc = {
-      spectestVersion: 1,
+      spectestVersion: 2,
+      units: Array.from(units).sort(),
       result: kept.map(function (s) {
-        return { url: s.url, scriptId: s.scriptId, spectestScript: idOf(s.url), functions: s.functions.filter(ran) };
+        return {
+          url: s.url,
+          spectestScript: idOf(s.url),
+          functions: s.functions.filter(ran).map(function (f) {
+            const first = f.ranges[0];
+            const out = [first.startOffset, first.endOffset - first.startOffset, first.count];
+            for (let i = 1; i < f.ranges.length; i++) {
+              const r = f.ranges[i];
+              out.push(r.startOffset - first.startOffset, r.endOffset - r.startOffset, r.count);
+            }
+            return out;
+          }),
+        };
       }),
     };
     const name = ${JSON.stringify(NODE_COVERAGE_DUMP_PREFIX)} + process.pid + "-" + wt.threadId + "-" + Date.now() + "-" + seq++ + ".json";
@@ -393,10 +507,136 @@ export const NODE_COVERAGE_HOOK = `"use strict";
  * only its own files: what an earlier capture on this branch shipped is
  * removed first (module memory, forks with the environment).
  */
+/** Manifests and lockfiles whose changes the node inventory accounts for. */
+export const NODE_EXPLAINS = [
+    "**/package.json",
+    "**/package-lock.json",
+    "**/npm-shrinkwrap.json",
+    "**/pnpm-lock.yaml",
+    "**/pnpm-workspace.yaml",
+    "**/yarn.lock",
+    "**/bun.lock",
+    "**/bun.lockb",
+];
+/** package.json keys that describe the package rather than shape what
+ *  runs: a change confined to them does not move the manifest's unit. */
+export const NPM_MANIFEST_METADATA_KEYS = [
+    "version",
+    "description",
+    "keywords",
+    "author",
+    "contributors",
+    "maintainers",
+    "license",
+    "repository",
+    "homepage",
+    "bugs",
+    "funding",
+    "private",
+    "publishConfig",
+    "readme",
+    "readmeFilename",
+    "gitHead",
+    "_id",
+];
+/** JSON with every object's keys sorted, at every depth. */
+function canonicalJson(v) {
+    if (Array.isArray(v))
+        return `[${v.map(canonicalJson).join(",")}]`;
+    if (v && typeof v === "object") {
+        const o = v;
+        return `{${Object.keys(o).sort().map((k) => `${JSON.stringify(k)}:${canonicalJson(o[k])}`).join(",")}}`;
+    }
+    return JSON.stringify(v);
+}
+/** `manifest:<path>#<hash>` over a package.json minus its metadata keys,
+ *  keys sorted, so formatting and a version bump leave it unchanged and a
+ *  `scripts`, `exports`, `bin` or dependency change moves it. A file that
+ *  is not JSON hashes as text. */
+export function npmManifestUnit(projectPath, text) {
+    let canon = text;
+    try {
+        const doc = JSON.parse(text);
+        if (doc && typeof doc === "object" && !Array.isArray(doc)) {
+            for (const k of NPM_MANIFEST_METADATA_KEYS)
+                delete doc[k];
+            canon = canonicalJson(doc);
+        }
+    }
+    catch {
+        // not JSON: the text is the fingerprint
+    }
+    const hash = createHash("sha256").update(canon).digest("hex").slice(0, 16);
+    return `manifest:${projectPath}#${hash}`;
+}
+/**
+ * The node script the inventory runs inside the container: every package
+ * installed in a `node_modules` on the path from the working directory up
+ * to `/` — hoisted (`node_modules/<name>`, `@scope/<name>`), nested, and
+ * pnpm's store (`node_modules/.pnpm/<pkg>/node_modules/<name>`, the real
+ * directories only; the symlinks beside them point back into the store).
+ * Prints one `npm:<name>@<version>` per line.
+ */
+export const NODE_INVENTORY_SCRIPT = `"use strict";
+const fs = require("node:fs"), path = require("node:path");
+const out = new Set();
+function isRealDir(p) { try { return fs.lstatSync(p).isDirectory(); } catch (e) { return false; } }
+function readPkg(d) {
+  try {
+    const j = JSON.parse(fs.readFileSync(path.join(d, "package.json"), "utf8"));
+    if (j && typeof j.name === "string" && j.name) out.add("npm:" + j.name + (typeof j.version === "string" && j.version ? "@" + j.version : ""));
+  } catch (e) {}
+}
+function visit(d, depth) {
+  readPkg(d);
+  if (depth < 3) { const nested = path.join(d, "node_modules"); if (isRealDir(nested)) walkNm(nested, depth + 1); }
+}
+function walkNm(nm, depth) {
+  let names; try { names = fs.readdirSync(nm); } catch (e) { return; }
+  for (const n of names) {
+    if (n === ".bin" || n === ".cache" || n === ".modules.yaml") continue;
+    if (n === ".pnpm") {
+      let ps; try { ps = fs.readdirSync(path.join(nm, ".pnpm")); } catch (e) { continue; }
+      for (const p of ps) { const inner = path.join(nm, ".pnpm", p, "node_modules"); if (isRealDir(inner)) walkNm(inner, depth + 1); }
+      continue;
+    }
+    if (n.startsWith("@")) {
+      let ss; try { ss = fs.readdirSync(path.join(nm, n)); } catch (e) { continue; }
+      for (const s of ss) { const d = path.join(nm, n, s); if (isRealDir(d)) visit(d, depth); }
+    } else { const d = path.join(nm, n); if (isRealDir(d)) visit(d, depth); }
+  }
+}
+let d = process.cwd();
+for (;;) {
+  const nm = path.join(d, "node_modules");
+  if (isRealDir(nm)) walkNm(nm, 0);
+  const up = path.dirname(d);
+  if (up === d) break;
+  d = up;
+}
+process.stdout.write(Array.from(out).sort().join("\\n") + (out.size ? "\\n" : ""));
+`;
 export function node() {
     return {
         name: "node",
         reports: "delta",
+        explains: NODE_EXPLAINS,
+        async inventory(ctx) {
+            // Installed packages, from inside the container (the script goes
+            // in through stdin so no quoting crosses the shell); manifest
+            // fingerprints from the project's own package.json files.
+            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:")));
+            for (const f of await ctx.projectFiles()) {
+                if (f !== "package.json" && !f.endsWith("/package.json"))
+                    continue;
+                const text = await ctx.readProjectFile(f);
+                if (text !== null)
+                    units.add(npmManifestUnit(f, text));
+            }
+            return [...units].sort();
+        },
         configure(svc) {
             const env = appendEnvFlag(svc.env, "NODE_OPTIONS", `--require ${NODE_COVERAGE_HOOK_PATH}`);
             env[NODE_COVERAGE_DIR_ENV] = COVERAGE_CONTAINER_DIR;

package/dist/daemon.js

@@ -21,10 +21,11 @@ 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, } from "./harness/coverage.js";
+import { COVERAGE_CONTAINER_DIR, coverageBundleRef, coverageHostDir, encodeCoverageBundle, isEmptyReport, readCoverageDir, applyCoverageDelta, walkProjectFiles, } from "./harness/coverage.js";
 import { configureBrowserCoverage } from "./browser-coverage.js";
-import { NODE_COVERAGE_MARKERS_SUBDIR, NODE_COVERAGE_SCRIPTS_SUBDIR, applyCoverageAdapters, coverageAdapters, coverageReportsMode, validateCoverage, } from "./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";
 import { acquirePersistentBrowser, mobileKey } from "./browser.js";
 import { isMobileApp, openPersistentMobile } from "./mobile.js";
@@ -124,7 +125,6 @@ const BUN_BIN = "/usr/local/bin/bun";
 // (see base.rs::BASE_SETUP_SH). Bind-mounted into every service
 // container so apps can verify HTTPS to the daemon's fakes, and
 // referenced when we layer it into each image's system trust store.
-const CA_PATH = process.env.SPECTEST_CA_PATH ?? "/etc/spectest/ca.crt";
 const CA_KEY_PATH = process.env.SPECTEST_CA_KEY_PATH ?? "/etc/spectest/ca.key";
 // Public roots ⧺ the spectest CA, materialized by `ensureCaBundle` and
 // bind-mounted into every container. `SSL_CERT_FILE`/`REQUESTS_CA_BUNDLE`/
@@ -3458,7 +3458,65 @@ async function coverageRoot(service) {
     COVERAGE_ROOTS.set(service, root);
     return root;
 }
-async function captureServiceCoverage() {
+/** Budget for one service's inventory adapters, all of them. */
+const COVERAGE_INVENTORY_TIMEOUT_MS = 120_000;
+/**
+ * Run one service's `inventory` adapters and write the union as the
+ * `inventory.units` report — for the bring-up capture only: the
+ * inventory is a property of the environment, not of a case. The file
+ * is removed after the read so no later capture ships it again. A
+ * failure is the capture's error, like a failing `capture`.
+ */
+async function writeCoverageInventory(svc) {
+    const adapters = coverageAdapters(svc.coverage).filter((a) => a.inventory);
+    if (adapters.length === 0)
+        return undefined;
+    const ac = new AbortController();
+    const timer = setTimeout(() => ac.abort(), COVERAGE_INVENTORY_TIMEOUT_MS);
+    const reportDir = coverageHostDir(WORKSPACE, svc.name);
+    const ctx = {
+        service: svc.name,
+        signal: ac.signal,
+        async exec(command) {
+            const r = await docker(["exec", svc.name, "sh", "-c", command], COVERAGE_INVENTORY_TIMEOUT_MS);
+            if (r.code !== 0) {
+                const tail = capMiddle((r.stderr || r.stdout).trim(), 2000).value;
+                throw new Error(`${JSON.stringify(command)} exited ${r.code}${tail ? `\n${tail}` : ""}`);
+            }
+            return { stdout: r.stdout, stderr: r.stderr };
+        },
+        projectFiles: () => walkProjectFiles(WORKSPACE),
+        async readProjectFile(p) {
+            try {
+                return await fs.readFile(resolveProjectPath(p), "utf8");
+            }
+            catch {
+                return null;
+            }
+        },
+    };
+    const units = new Set();
+    try {
+        for (const a of adapters) {
+            try {
+                for (const u of await a.inventory(ctx))
+                    units.add(u);
+            }
+            catch (err) {
+                return `coverage adapter "${a.name}" on service "${svc.name}" inventory failed: ${err instanceof Error ? err.message : String(err)}`;
+            }
+        }
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    const file = path.join(reportDir, INVENTORY_REPORT);
+    await fs.mkdir(reportDir, { recursive: true });
+    await fs.writeFile(file, [...units].sort().join("\n") + (units.size ? "\n" : ""));
+    console.log(`[coverage] ${svc.name}: inventory of ${units.size} unit(s)`);
+    return undefined;
+}
+async function captureServiceCoverage(baseline = false) {
     const l = loaded;
     if (!l)
         return [];
@@ -3472,7 +3530,15 @@ async function captureServiceCoverage() {
         const { error, deltaReports } = await runCoverageAdapters(svc);
         if (error)
             return { service: svc.name, reports: [], error };
+        if (baseline) {
+            const invError = await writeCoverageInventory(svc);
+            if (invError)
+                return { service: svc.name, reports: [], error: invError };
+        }
         const read = await readCoverageDir(svc.name, coverageHostDir(WORKSPACE, svc.name));
+        if (baseline) {
+            await fs.rm(path.join(coverageHostDir(WORKSPACE, svc.name), INVENTORY_REPORT), { force: true }).catch(() => { });
+        }
         const root = await coverageRoot(svc.name);
         if (root)
             read.root = root;
@@ -5408,7 +5474,7 @@ export function harnessMethods(state) {
             // the control plane logs it.
             let coverage;
             try {
-                const captures = await captureServiceCoverage();
+                const captures = await captureServiceCoverage(true);
                 for (const c of captures) {
                     // 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 —

package/dist/environment-ca.d.ts

@@ -0,0 +1,8 @@
+/** @internal Shared by certificate issuance, trust mounts and the public reader. */
+export declare const ENVIRONMENT_CA_PATH: string;
+/** Read the environment's public CA certificate as a PEM string.
+ * The base VM creates it before importing the environment definition, so it
+ * can be used directly in service env, file contents or runtime client options.
+ * Normal TLS trust is automatic; use this only when explicit CA data is needed.
+ */
+export declare function ca(): string;

package/dist/environment-ca.js

@@ -0,0 +1,16 @@
+import { readFileSync } from "node:fs";
+/** @internal Shared by certificate issuance, trust mounts and the public reader. */
+export const ENVIRONMENT_CA_PATH = process.env.SPECTEST_CA_PATH ?? "/etc/spectest/ca.crt";
+/** Read the environment's public CA certificate as a PEM string.
+ * The base VM creates it before importing the environment definition, so it
+ * can be used directly in service env, file contents or runtime client options.
+ * Normal TLS trust is automatic; use this only when explicit CA data is needed.
+ */
+export function ca() {
+    try {
+        return readFileSync(ENVIRONMENT_CA_PATH, "utf8");
+    }
+    catch (cause) {
+        throw new Error(`ca(): cannot read the environment CA at ${ENVIRONMENT_CA_PATH}; run this code inside a Spectest environment`, { cause });
+    }
+}

package/dist/harness/container-run.js

@@ -136,6 +136,9 @@ export function runContainerArgs(input) {
         args.push("-e", `SSL_CERT_FILE=${bundle}`);
         args.push("-e", `REQUESTS_CA_BUNDLE=${bundle}`);
         args.push("-e", `AWS_CA_BUNDLE=${bundle}`);
+        // libpq does not use the system trust store by default. Supply the
+        // same combined roots to psql/psycopg without changing their SSL mode.
+        args.push("-e", `PGSSLROOTCERT=${bundle}`);
         // The system store itself, for clients that read no variable at all.
         // Only a real bundle: the caller falls back to the bare CA when the
         // guest's roots are unreadable, and the bare CA over the system store

package/dist/harness/coverage.d.ts

@@ -57,21 +57,33 @@ export declare function hasLcovSourceFile(text: string): boolean;
 export declare function isLcovShaped(text: string): boolean;
 /**
  * True when `text` looks like a V8 coverage JSON document — what
- * `NODE_V8_COVERAGE` / `v8.takeCoverage()` write: an object with a
- * `result` array of scripts. A cheap shape check, not a parse (a report
- * can be megabytes); the control plane parses for real.
+ * `NODE_V8_COVERAGE` / `v8.takeCoverage()` write, and the shape the
+ * `node()` hook's dumps keep: an object with a `result` array of
+ * scripts. A cheap shape check, not a parse (a report can be
+ * megabytes); the control plane parses for real.
  */
 export declare function isV8CoverageJson(text: string): boolean;
 /** True when `text` is a script record the `node()` hook writes
  *  (`scripts/<id>.json`: `{ "spectestScript": { url, lineLengths,
  *  functions, sourceMap } }`), the static side of its dumps. */
 export declare function isSpectestScriptRecord(text: string): boolean;
-/** True when `text` is a report spectest stores: lcov, V8 JSON, or a
- *  node() script record. */
-export declare function isWellFormedReport(text: string): boolean;
+/** True when `text` is a `.units` report: one unit id per non-blank
+ *  line, `<scheme>:<rest>` (`npm:picocolors@1.1.1`,
+ *  `manifest:packages/cli/package.json#3f9a…`). An empty file is a
+ *  report that names no unit. What a unit means is the adapter's; here
+ *  and on the control plane an id is an opaque string. */
+export declare function isUnitsReport(text: string): boolean;
+/** True when `text` is a report spectest stores: lcov, V8 JSON, a node()
+ *  script record, or (by name) a `.units` list. */
+export declare function isWellFormedReport(text: string, name?: string): boolean;
 /** True when a well-formed report names no source file at all (an lcov
- *  with no `SF:`, a V8 document with an empty `result`). */
+ *  with no `SF:`, a V8 document with an empty `result`, a units list
+ *  with no unit). */
 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[]>;
 /** 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

@@ -56,9 +56,10 @@ export function isLcovShaped(text) {
 }
 /**
  * True when `text` looks like a V8 coverage JSON document — what
- * `NODE_V8_COVERAGE` / `v8.takeCoverage()` write: an object with a
- * `result` array of scripts. A cheap shape check, not a parse (a report
- * can be megabytes); the control plane parses for real.
+ * `NODE_V8_COVERAGE` / `v8.takeCoverage()` write, and the shape the
+ * `node()` hook's dumps keep: an object with a `result` array of
+ * scripts. A cheap shape check, not a parse (a report can be
+ * megabytes); the control plane parses for real.
  */
 export function isV8CoverageJson(text) {
     return /^\s*\{/.test(text) && /"result"\s*:\s*\[/.test(text);
@@ -69,18 +70,60 @@ export function isV8CoverageJson(text) {
 export function isSpectestScriptRecord(text) {
     return /^\s*\{\s*"spectestScript"\s*:/.test(text);
 }
-/** True when `text` is a report spectest stores: lcov, V8 JSON, or a
- *  node() script record. */
-export function isWellFormedReport(text) {
+/** True when `text` is a `.units` report: one unit id per non-blank
+ *  line, `<scheme>:<rest>` (`npm:picocolors@1.1.1`,
+ *  `manifest:packages/cli/package.json#3f9a…`). An empty file is a
+ *  report that names no unit. What a unit means is the adapter's; here
+ *  and on the control plane an id is an opaque string. */
+export function isUnitsReport(text) {
+    return text.split(/\r?\n/).every((l) => l.trim().length === 0 || /^[a-z][a-z0-9+.-]*:\S+$/.test(l.trim()));
+}
+/** True when `text` is a report spectest stores: lcov, V8 JSON, a node()
+ *  script record, or (by name) a `.units` list. */
+export function isWellFormedReport(text, name = "") {
+    if (name.endsWith(".units"))
+        return isUnitsReport(text);
     return isLcovShaped(text) || isV8CoverageJson(text) || isSpectestScriptRecord(text);
 }
 /** True when a well-formed report names no source file at all (an lcov
- *  with no `SF:`, a V8 document with an empty `result`). */
+ *  with no `SF:`, a V8 document with an empty `result`, a units list
+ *  with no unit). */
 export function isEmptyReport(text) {
     if (isV8CoverageJson(text))
         return /"result"\s*:\s*\[\s*\]/.test(text);
+    if (isSpectestScriptRecord(text))
+        return false;
+    if (isUnitsReport(text) && !isLcovShaped(text))
+        return text.trim().length === 0;
     return !hasLcovSourceFile(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"]);
+    const out = [];
+    async function walk(d, rel) {
+        let entries;
+        try {
+            entries = await fs.readdir(d, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            if (skip.has(e.name))
+                continue;
+            const r = rel ? `${rel}/${e.name}` : e.name;
+            if (e.isDirectory())
+                await walk(path.join(d, e.name), r);
+            else if (e.isFile())
+                out.push(r);
+        }
+    }
+    await walk(root, "");
+    return out.sort();
+}
 /** 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). */
@@ -143,7 +186,7 @@ export async function readCoverageDir(service, dir) {
                 error: `service "${service}" has more than ${COVERAGE_MAX_BYTES_PER_SERVICE >> 20} MiB of reports in ${COVERAGE_CONTAINER_DIR}/ — that is a runaway, not coverage`,
             };
         }
-        if (isWellFormedReport(content))
+        if (isWellFormedReport(content, name))
             anyReport = true;
         else
             malformed.push(name);
@@ -153,7 +196,7 @@ export async function readCoverageDir(service, dir) {
         return {
             service,
             reports,
-            error: `service "${service}" wrote ${reports.length} file(s) to ${COVERAGE_CONTAINER_DIR}/ but ${anyReport ? `${malformed.slice(0, 5).join(", ")} ${malformed.length === 1 ? "is" : "are"} neither` : "none is"} an lcov report or a V8 coverage JSON document — only those two formats are read`,
+            error: `service "${service}" wrote ${reports.length} file(s) to ${COVERAGE_CONTAINER_DIR}/ but ${anyReport ? `${malformed.slice(0, 5).join(", ")} ${malformed.length === 1 ? "is" : "are"} neither` : "none is"} an lcov report, a V8 coverage JSON document, or a \`.units\` list — only those are read`,
         };
     }
     return { service, reports };

package/dist/index.d.ts

@@ -23,6 +23,7 @@ export type { Terminal, TerminalOpts, TerminalResult } from "./terminal.js";
 import type { Terminal, TerminalOpts, TerminalResult } from "./terminal.js";
 export { type CoverageAdapter, type CoverageCaptureContext, type CoverageConfigureInfo, type CoverageLoadContext, type ServiceCoverage, } from "./coverage.js";
 import { type ServiceCoverage } from "./coverage.js";
+export { ca } from "./environment-ca.js";
 export { certificate, dnsName, proxy, provides, lowerIngress, isWildcard, SELF_SERVICE_TOKEN, } from "./ingress.js";
 export type { CertificateDecl, DnsDecl, ProxyDecl, IngressDecl, DnsTarget, LoweredIngress, } from "./ingress.js";
 import type { DnsTarget } from "./ingress.js";

package/dist/index.js

@@ -44,6 +44,7 @@ import { containsText, containsTextArray, escapeInvisible, matchesText, matchesT
 import { describeUrlPattern, matchesUrl } from "./url-match.js";
 import { applyCoverageAdapters, validateCoverage } from "./coverage.js";
 import { resolveExistingProjectPath } from "./project-files.js";
+export { ca } from "./environment-ca.js";
 // Low-level ingress primitives + the framework lowering that the friendly
 // `tls` / `hostnames` fields and `defineFake(...)` are built on. See
 // `ingress.ts`.