@specific.dev/spectest 0.82.0 → 0.85.0

package/dist/components/supabase.js

@@ -27,7 +27,7 @@
 //     supabase: sb.group,      // expands to supabase, supabase-db, supabase-auth, ...
 //     app: {
 //       image: { type: "dockerfile", content: "..." },
-//       env: { ...sb.appEnv }, // SUPABASE_URL / _ANON_KEY / _SERVICE_ROLE_KEY / DATABASE_URL
+//       env: { SUPABASE_URL: sb.url, SUPABASE_ANON_KEY: sb.anonKey, DATABASE_URL: sb.dbUrl },
 //       dependsOn: [sb.ready], // wait for the gateway (and the stack behind it)
 //     },
 //   },
@@ -47,7 +47,7 @@
 // the group naming context, so two Supabase stacks (or a user service
 // innocently named `db`) never collide. The group must be mounted at the key
 // matching the `name` option (default `"supabase"`) since the derived surface
-// (`sb.url`, `sb.appEnv`) embeds it — a mismatch errors at load.
+// (`sb.url`, `sb.dbUrl`) embeds it — a mismatch errors at load.
 import { createHmac } from "node:crypto";
 import { existsSync, readFileSync } from "node:fs";
 import { readdir, stat } from "node:fs/promises";
@@ -59,6 +59,8 @@ import { email, emailHelpers } from "./email.js";
 import { github } from "./github.js";
 import { google } from "./google.js";
 import { microsoft } from "./microsoft.js";
+import { SUPABASE_WEBHOOKS_SQL } from "./supabase-webhooks.js";
+import { postgresTls } from "./postgres-tls.js";
 import { mapSupabaseConfig, parseSupabaseConfigFile, } from "./supabase-config.js";
 // ──────────────────────────────────────────────────────────────────────────
 // Pinned upstream image tags (github.com/supabase/supabase docker-compose.yml,
@@ -78,6 +80,15 @@ const IMAGES = {
     // part). Tiny, and only pulled by a stack that configures a template.
     templates: "busybox:1.37",
 };
+/** Override tables without mutating the parsed project config. */
+function mergeConfig(base, overrides) {
+    const table = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+    const result = Object.assign(Object.create(null), table(base) ? base : {});
+    for (const [key, value] of Object.entries(overrides)) {
+        result[key] = table(value) ? mergeConfig(result[key], value) : value;
+    }
+    return result;
+}
 /**
  * Social sign-in providers this stack can serve, by the name GoTrue (and
  * `[auth.external.<name>]`) uses. Each factory builds one container answering
@@ -214,6 +225,30 @@ function apiKey(role, secret) {
 function pgLiteral(s) {
     return `'${s.replace(/'/g, "''")}'`;
 }
+function pgIdentifier(s) {
+    if (!s || s.includes("\0"))
+        throw new Error("supabase(): an SQL identifier must be non-empty and contain no NUL");
+    return `"${s.replace(/"/g, '""')}"`;
+}
+function extensionSql(extensions) {
+    return Object.entries(extensions ?? {}).map(([name, { schema, version }]) => {
+        const install = `CREATE EXTENSION IF NOT EXISTS ${pgIdentifier(name)}` +
+            (schema ? ` SCHEMA ${pgIdentifier(schema)}` : "") +
+            (version ? ` VERSION ${pgLiteral(version)}` : "") + ";";
+        // IF NOT EXISTS does not validate an already-installed extension.
+        const matches = [
+            version ? `e.extversion = ${pgLiteral(version)}` : "true",
+            schema ? `n.nspname = ${pgLiteral(schema)}` : "true",
+        ].join(" AND ");
+        const check = `BEGIN
+      IF EXISTS (SELECT 1 FROM pg_extension e JOIN pg_namespace n ON n.oid = e.extnamespace
+                 WHERE e.extname = ${pgLiteral(name)} AND NOT (${matches})) THEN
+        RAISE EXCEPTION USING MESSAGE = ${pgLiteral(`supabase: extension ${name} does not match the requested schema/version`)};
+      END IF;
+    END`;
+        return `${install}\nDO ${pgLiteral(check)};`;
+    }).join("\n");
+}
 function buildBootstrapSql(dbPassword, jwtSecret, withRealtime) {
     const pw = pgLiteral(dbPassword);
     const lines = [
@@ -1213,11 +1248,14 @@ async function reloadPostgrestSchema(ctx, db, rest) {
 /**
  * A ready-to-use self-hosted Supabase stack. Mount `.group` at the key
  * matching the `name` option (default `"supabase"`) and wire the app with
- * `.appEnv` / `.ready`:
+ * its connection values and `.ready`:
  *
  * ```ts
  * const sb = supabase({ dbPassword: "postgres" });
- * services: { supabase: sb.group, app: { image, env: sb.appEnv, dependsOn: [sb.ready] } }
+ * services: { supabase: sb.group, app: {
+ *   image, env: { SUPABASE_URL: sb.url, SUPABASE_ANON_KEY: sb.anonKey },
+ *   dependsOn: [sb.ready],
+ * } }
  * ```
  *
  * See the file header for the full picture. Tests get an instrumented DB client
@@ -1272,11 +1310,27 @@ export function supabase(opts = {}) {
     // services map is returned. `config.json` wins where a newer CLI wrote one.
     const configPath = inDir("config.json") ?? inDir("config.toml");
     let mapped = null;
-    if (configPath !== null) {
-        const shown = configPath.startsWith(projectRootPath())
+    if (configPath !== null || opts.configOverrides !== undefined) {
+        const shown = configPath === null ? "configOverrides" : configPath.startsWith(projectRootPath())
             ? configPath.slice(projectRootPath().length + 1)
             : configPath;
-        mapped = mapSupabaseConfig(parseSupabaseConfigFile(configPath));
+        mapped = mapSupabaseConfig(mergeConfig(configPath === null ? {} : parseSupabaseConfigFile(configPath), opts.configOverrides ?? {}));
+        for (const [target, { from, key }] of Object.entries(mapped.deferredAuth)) {
+            const enabled = target.replace(/_(URI|SECRETS)$/, "_ENABLED");
+            if (!withAuth || mapped.auth[enabled] !== "true")
+                continue;
+            const value = opts.env?.[from];
+            if (value === undefined || value === "") {
+                throw new Error(`supabase(): ${key} reads env(${from}); supply a non-empty test value with env: { ${from}: "…" }.`);
+            }
+            mapped.auth[target] = value;
+        }
+        for (const key of mapped.encryptedValues) {
+            const hook = /^auth\.hook\.([^.]+)\.(uri|secrets)$/.exec(key);
+            if (withAuth && hook && mapped.auth[`GOTRUE_HOOK_${hook[1].toUpperCase()}_ENABLED`] === "true") {
+                throw new Error(`supabase(): ${key} is encrypted; override it with env(NAME) and supply the test value through env.`);
+            }
+        }
         // What the file asked for and did not get. Reported, never fatal: the
         // config belongs to the project and describes more than this environment,
         // so a key that is meaningless in a hermetic VM is not grounds to refuse
@@ -1302,6 +1356,7 @@ export function supabase(opts = {}) {
         // and nothing says why.
         const referenced = new Set([
             ...Object.values(mapped.deferredSecrets),
+            ...Object.values(mapped.deferredAuth).map(({ from }) => from),
             ...Object.values(mapped.externalProviders).flatMap((p) => [p.clientIdFrom, p.secretFrom].filter((n) => n !== undefined)),
         ]);
         const unread = Object.keys(opts.env ?? {}).filter((k) => !referenced.has(k));
@@ -1361,17 +1416,20 @@ export function supabase(opts = {}) {
     }
     const anonKey = apiKey("anon", jwtSecret);
     const serviceRoleKey = apiKey("service_role", jwtSecret);
-    // Derived surface, embedded in `appEnv` / `url` before the group expands.
+    // Derived connection values, available before the group expands.
     // `expectKey: name` on the group guarantees these names and the expanded
     // service keys agree (`g.key("db")` at expansion === `${name}-db` here).
     const dbKey = `${name}-db`;
     const url = opts.hostname ? `https://${opts.hostname}` : `http://${name}:8000`;
     // App-facing URL: the conventional `postgres` role (owns migrated tables).
-    const dbUrl = `postgresql://postgres:${dbPassword}@${dbKey}:5432/postgres`;
+    const dbTls = opts.db?.tls !== false ? postgresTls() : undefined;
+    const dbUrl = `postgresql://postgres:${encodeURIComponent(dbPassword)}@${dbKey}:5432/postgres` +
+        (dbTls ? "?sslmode=verify-full" : "");
     // The test-side `ctx.svc.<name>.sql` helper connects as the superuser
     // `supabase_admin` so it can inspect everything — public tables plus the
     // `auth`/`storage` schemas — regardless of ownership.
-    const adminDbUrl = `postgresql://supabase_admin:${dbPassword}@${dbKey}:5432/postgres`;
+    const adminDbUrl = `postgresql://supabase_admin:${encodeURIComponent(dbPassword)}@${dbKey}:5432/postgres` +
+        (dbTls ? "?sslmode=verify-full" : "");
     // ── social sign-in ────────────────────────────────────────────────────
     // Every `[auth.external.<name>]` the config enables: served in-environment
     // where there is an emulator for it, reported where there isn't. The app
@@ -1415,7 +1473,7 @@ export function supabase(opts = {}) {
             const parts = {};
             // ── db ──────────────────────────────────────────────────────────
             const dbDef = {
-                image: { type: "registry", reference: IMAGES.db },
+                image: { type: "registry", reference: opts.db?.image ?? IMAGES.db },
                 // `args` (not `command`): keep the image's docker-entrypoint.sh so it
                 // runs initdb + its baked init-scripts before starting.
                 args: [
@@ -1424,7 +1482,9 @@ export function supabase(opts = {}) {
                     "config_file=/etc/postgresql/postgresql.conf",
                     "-c",
                     "log_min_messages=fatal",
+                    ...(dbTls?.args ?? []),
                 ],
+                ...(dbTls ? { certificates: dbTls.certificates } : {}),
                 env: {
                     POSTGRES_HOST: "/var/run/postgresql",
                     PGPORT: "5432",
@@ -1451,6 +1511,10 @@ export function supabase(opts = {}) {
                     // database — superuser-only. `postgres` is deliberately NOT a
                     // superuser in modern supabase/postgres; `supabase_admin` is.
                     "supabase_admin");
+                    await applySqlFile(ctx, SUPABASE_WEBHOOKS_SQL, "database webhooks", "supabase_admin");
+                    const extensions = extensionSql(opts.db?.extensions);
+                    if (extensions)
+                        await applySqlFile(ctx, extensions, "configured extensions", "postgres");
                 },
             };
             parts.db = dbDef;
@@ -1834,12 +1898,6 @@ export function supabase(opts = {}) {
             ...(withMail ? { mail: emailHelpers(mailKey) } : {}),
         }),
     });
-    const appEnv = {
-        SUPABASE_URL: url,
-        SUPABASE_ANON_KEY: anonKey,
-        SUPABASE_SERVICE_ROLE_KEY: serviceRoleKey,
-        DATABASE_URL: dbUrl,
-    };
     return {
         group,
         url,
@@ -1847,7 +1905,6 @@ export function supabase(opts = {}) {
         serviceRoleKey,
         dbUrl,
         ready: name,
-        appEnv,
         ...(withMail ? { smtp: { host: mailKey, port: 1025 } } : {}),
     };
 }

package/dist/components/temporal.d.ts

@@ -0,0 +1,89 @@
+import { type ServicesMap } from "../index.js";
+export type TemporalSearchAttributeType = "Text" | "Keyword" | "Int" | "Double" | "Bool" | "Datetime" | "KeywordList";
+export type TemporalTaskType = "workflow" | "activity";
+export interface TemporalPoller {
+    identity: string;
+    lastAccessTime?: string;
+}
+export interface TemporalWorkerOptions {
+    namespace?: string;
+    /** Both by default; activity-only workers can select ["activity"]. */
+    types?: TemporalTaskType[];
+    /** Require every named worker identity on each requested queue type. */
+    identities?: string[];
+    minPollers?: number;
+    maxAgeMs?: number;
+    timeoutMs?: number;
+}
+export interface TemporalNamespace {
+    namespaceInfo: {
+        name: string;
+        state: string;
+        id: string;
+    };
+    config?: {
+        workflowExecutionRetentionTtl?: string;
+    };
+}
+export interface TemporalOptions {
+    name?: string;
+    /** Pinned CLI image, including the real Temporal server and SQLite. */
+    image?: string;
+    namespace?: string;
+    namespaces?: string[];
+    searchAttributes?: Record<string, TemporalSearchAttributeType>;
+    port?: number;
+    httpPort?: number;
+    /** Off by default; no UI process or assets are needed by workers. */
+    ui?: boolean;
+    /** Optional native gRPC TLS endpoint; adds a small TLS terminator. */
+    tls?: {
+        hostname: string;
+    };
+}
+/** Stateless HTTP client, also usable inside a fake that provisions real namespaces.
+ * No gRPC channel survives a VM restore, and no CLI process is spawned per request.
+ */
+export declare function temporalClient(httpUrl: string, namespace?: string, fetcher?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>): {
+    httpUrl: string;
+    namespace: string;
+    describeNamespace(name?: string): Promise<TemporalNamespace>;
+    registerNamespace(name: string, options?: {
+        retentionDays?: number;
+        timeoutMs?: number;
+    }): Promise<TemporalNamespace>;
+    waitForWorkers(taskQueue: string, options?: TemporalWorkerOptions): Promise<{
+        [k: string]: TemporalPoller[];
+    }>;
+};
+export type TemporalClient = ReturnType<typeof temporalClient>;
+export declare function temporal(opts?: TemporalOptions): {
+    group: import("../index.js").ServiceGroup<ServicesMap, {
+        httpUrl: string;
+        namespace: string;
+        describeNamespace(name?: string): Promise<TemporalNamespace>;
+        registerNamespace(name: string, options?: {
+            retentionDays?: number;
+            timeoutMs?: number;
+        }): Promise<TemporalNamespace>;
+        waitForWorkers(taskQueue: string, options?: TemporalWorkerOptions): Promise<{
+            [k: string]: TemporalPoller[];
+        }>;
+    }, "tls" | "server">;
+    address: string;
+    httpUrl: string;
+    namespace: string;
+    ready: string;
+    client: {
+        httpUrl: string;
+        namespace: string;
+        describeNamespace(name?: string): Promise<TemporalNamespace>;
+        registerNamespace(name: string, options?: {
+            retentionDays?: number;
+            timeoutMs?: number;
+        }): Promise<TemporalNamespace>;
+        waitForWorkers(taskQueue: string, options?: TemporalWorkerOptions): Promise<{
+            [k: string]: TemporalPoller[];
+        }>;
+    };
+};

package/dist/components/temporal.js

@@ -0,0 +1,185 @@
+import { serviceGroup } from "../index.js";
+import { rawFetch } from "../harness/raw-fetch.js";
+import { readRaw } from "../inspect.js";
+class TemporalApiError extends Error {
+    status;
+    code;
+    constructor(status, code, message) {
+        super(message);
+        this.status = status;
+        this.code = code;
+    }
+}
+class TemporalTransportError extends Error {
+}
+const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const positive = (name, n) => {
+    if (!Number.isFinite(n) || n <= 0)
+        throw new Error(`temporal(): ${name} must be positive`);
+    return n;
+};
+const namespaceName = (name) => {
+    if (!name || name.includes("\0"))
+        throw new Error("temporal(): namespace must be non-empty and contain no NUL");
+    return name;
+};
+/** Stateless HTTP client, also usable inside a fake that provisions real namespaces.
+ * No gRPC channel survives a VM restore, and no CLI process is spawned per request.
+ */
+export function temporalClient(httpUrl, namespace = "default", fetcher = rawFetch) {
+    const nsPath = (ns) => `/api/v1/namespaces/${encodeURIComponent(namespaceName(ns))}`;
+    async function request(path, init, timeoutMs = 5000) {
+        let response;
+        let body;
+        try {
+            response = await fetcher(`${httpUrl}${path}`, { ...init, signal: AbortSignal.timeout(Math.max(1, Math.ceil(timeoutMs))) });
+            body = await response.text();
+        }
+        catch (cause) {
+            throw new TemporalTransportError(`Temporal ${path}: ${String(cause)}`, { cause });
+        }
+        let value;
+        try {
+            value = body ? JSON.parse(body) : {};
+        }
+        catch {
+            if (response.ok)
+                throw new Error(`Temporal ${path}: invalid JSON (HTTP ${response.status}): ${body.slice(0, 500)}`);
+            value = {}; // Gateways may return plain text or HTML for a transient error.
+        }
+        if (!response.ok)
+            throw new TemporalApiError(response.status, value?.code, `Temporal ${path}: HTTP ${response.status}: ${value?.message ?? body.slice(0, 500)}`);
+        return value;
+    }
+    async function until(description, timeoutMs, probe) {
+        const deadline = Date.now() + positive("timeoutMs", timeoutMs);
+        let last = "condition not met";
+        let interval = 50;
+        do {
+            try {
+                const value = await probe(Math.min(5000, Math.max(1, deadline - Date.now())));
+                if (value !== null)
+                    return value;
+            }
+            catch (error) {
+                if (!(error instanceof TemporalTransportError) &&
+                    !(error instanceof TemporalApiError && [404, 429, 502, 503, 504].includes(error.status)))
+                    throw error;
+                last = error;
+            }
+            const remaining = deadline - Date.now();
+            if (remaining <= 0)
+                break;
+            await delay(Math.min(interval, remaining));
+            interval = Math.min(500, interval * 2);
+        } while (Date.now() < deadline);
+        throw new Error(`Timed out after ${timeoutMs}ms waiting for ${description}. Last result: ${String(last)}`);
+    }
+    return {
+        httpUrl, namespace,
+        describeNamespace(name = namespace) { return request(nsPath(name)); },
+        async registerNamespace(name, options = {}) {
+            namespaceName(name);
+            const timeoutMs = positive("timeoutMs", options.timeoutMs ?? 10000);
+            const deadline = Date.now() + timeoutMs;
+            const retentionSeconds = positive("retentionDays", options.retentionDays ?? 1) * 86400;
+            await until(`Temporal namespace ${JSON.stringify(name)} creation`, timeoutMs, async (remaining) => {
+                try {
+                    await request("/api/v1/namespaces", { method: "POST", headers: { "content-type": "application/json" },
+                        body: JSON.stringify({ namespace: name, workflowExecutionRetentionPeriod: `${retentionSeconds}s` }) }, remaining);
+                }
+                catch (error) {
+                    // A retry after a lost response is safe: names are unique, and an
+                    // existing namespace is never updated by this operation.
+                    if (!(error instanceof TemporalApiError && error.code === 6))
+                        throw error;
+                }
+                return true;
+            });
+            return until(`Temporal namespace ${JSON.stringify(name)} to be registered`, Math.max(1, deadline - Date.now()), async (remaining) => {
+                const result = await request(nsPath(name), undefined, remaining);
+                return result.namespaceInfo?.state === "NAMESPACE_STATE_REGISTERED" ? result : null;
+            });
+        },
+        async waitForWorkers(taskQueue, options = {}) {
+            if (!taskQueue)
+                throw new Error("temporal(): taskQueue must be non-empty");
+            const ns = options.namespace ?? namespace;
+            const types = [...new Set(options.types ?? ["workflow", "activity"])];
+            if (!types.length || types.some(t => t !== "workflow" && t !== "activity"))
+                throw new Error("temporal(): types must contain workflow and/or activity");
+            const minPollers = positive("minPollers", options.minPollers ?? 1);
+            if (!Number.isInteger(minPollers))
+                throw new Error("temporal(): minPollers must be an integer");
+            const maxAgeMs = positive("maxAgeMs", options.maxAgeMs ?? 120000);
+            let observed = {};
+            try {
+                return await until(`Temporal workers on ${ns}/${taskQueue} (${types.join(", ")})`, options.timeoutMs ?? 30000, async (remaining) => {
+                    const entries = await Promise.all(types.map(async (type) => {
+                        const result = await request(`${nsPath(ns)}/task-queues/${encodeURIComponent(taskQueue)}?taskQueueType=${type === "workflow" ? 1 : 2}`, undefined, remaining);
+                        const pollers = (result.pollers ?? []).filter(p => p.identity && p.lastAccessTime && Date.now() - Date.parse(p.lastAccessTime) <= maxAgeMs);
+                        return [type, pollers];
+                    }));
+                    observed = Object.fromEntries(entries.map(([t, ps]) => [t, ps.map(p => p.identity)]));
+                    return entries.every(([, ps]) => new Set(ps.map(p => p.identity)).size >= minPollers &&
+                        (options.identities ?? []).every(id => ps.some(p => p.identity === id))) ? Object.fromEntries(entries) : null;
+                });
+            }
+            catch (error) {
+                if (error instanceof Error)
+                    error.message += ` Observed pollers: ${JSON.stringify(observed)}`;
+                throw error;
+            }
+        },
+    };
+}
+export function temporal(opts = {}) {
+    const name = opts.name ?? "temporal";
+    const namespace = namespaceName(opts.namespace ?? "default");
+    const port = opts.port ?? 7233;
+    const httpPort = opts.httpPort ?? 7243;
+    for (const p of [port, httpPort])
+        if (!Number.isInteger(p) || p < 1 || p > 65535)
+            throw new Error("temporal(): ports must be integers between 1 and 65535");
+    if (port === httpPort || (opts.ui && [port, httpPort].includes(8233)))
+        throw new Error("temporal(): listener ports must be distinct");
+    if (opts.tls && !/^(?:[a-z0-9-]+\.)+[a-z0-9-]+$/.test(opts.tls.hostname))
+        throw new Error("temporal(): TLS hostname must be a multi-label DNS name");
+    const serverName = opts.tls ? `${name}-server` : name;
+    const address = `${opts.tls?.hostname ?? name}:${port}`;
+    const httpUrl = `http://${serverName}:${httpPort}`;
+    const namespaces = [...new Set([namespace, ...(opts.namespaces ?? [])])].map(namespaceName);
+    const args = ["server", "start-dev", "--ip", "0.0.0.0", "--port", String(port), "--http-port", String(httpPort), "--log-format", "json"];
+    args.push(...(opts.ui ? ["--ui-port", "8233", "--ui-disable-news-fetch"] : ["--headless"]));
+    for (const ns of namespaces)
+        if (ns !== "default")
+            args.push("--namespace", ns);
+    for (const [key, type] of Object.entries(opts.searchAttributes ?? {})) {
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key) || !["Text", "Keyword", "Int", "Double", "Bool", "Datetime", "KeywordList"].includes(type))
+            throw new Error(`temporal(): invalid search attribute ${key}=${type}`);
+        args.push("--search-attribute", `${key}=${type}`);
+    }
+    const primary = opts.tls ? "tls" : "server";
+    const group = serviceGroup({
+        primary, expectKey: name,
+        services: () => {
+            const server = {
+                image: { type: "registry", reference: opts.image ?? "temporalio/temporal:1.9.1" }, args,
+                ports: [port, httpPort, ...(opts.ui ? [8233] : [])],
+                readyCheck: { type: "http", port: httpPort, path: `/api/v1/namespaces/${encodeURIComponent(namespace)}`, timeoutSecs: 30 },
+            };
+            if (!opts.tls)
+                return { server };
+            return { server, tls: {
+                    image: { type: "registry", reference: "nginx:1.29.6-alpine" },
+                    ports: [port], hostnames: [opts.tls.hostname], dependsOn: [serverName],
+                    certificates: [{ hostnames: [opts.tls.hostname], certPath: "/tls/server.crt", keyPath: "/tls/server.key" }],
+                    files: [{ path: "/etc/nginx/nginx.conf", content: `worker_processes 1;\nevents { worker_connections 1024; }\nstream { server { listen ${port} ssl; ssl_certificate /tls/server.crt; ssl_certificate_key /tls/server.key; ssl_protocols TLSv1.2 TLSv1.3; ssl_alpn h2; proxy_pass ${serverName}:${port}; } }\n` }],
+                    readyCheck: { type: "tcp", port, timeoutSecs: 30 },
+                } };
+        },
+        helpers: (ctx) => temporalClient(httpUrl, namespace, async (input, init) => readRaw(await ctx.fetch(String(input), init))),
+    });
+    return { group, address, httpUrl, namespace, ready: name,
+        client: temporalClient(httpUrl, namespace) };
+}

package/dist/coverage.d.ts

@@ -29,6 +29,29 @@ export interface CoverageLoadContext {
      */
     collectBrowserScripts(): void;
 }
+/**
+ * What one adapter's `inventory` runs against, once per environment, at
+ * the bring-up capture. The inventory is the set of **units** the
+ * environment resolved for this service — dependencies, and fingerprints
+ * of the manifests that declare them (see {@link CoverageAdapter.inventory}).
+ */
+export interface CoverageInventoryContext {
+    /** The services-map key. */
+    service: string;
+    /** Run a shell command (`sh -c`) inside the container. Rejects on a
+     *  non-zero exit with the command's output in the message. */
+    exec(command: string): Promise<{
+        stdout: string;
+        stderr: string;
+    }>;
+    /** Every file of the uploaded project, project-relative, `/`-separated,
+     *  `node_modules`, `.git` and the like skipped. */
+    projectFiles(): Promise<string[]>;
+    /** One project file's text (project-relative path); `null` when absent. */
+    readProjectFile(path: string): Promise<string | null>;
+    /** Aborts when the inventory budget runs out. */
+    signal: AbortSignal;
+}
 /** What one adapter's `capture` runs against. */
 export interface CoverageCaptureContext {
     /** The services-map key. */
@@ -73,7 +96,31 @@ export interface CoverageAdapter {
     load?(ctx: CoverageLoadContext): void | Promise<void>;
     /** Make the report appear in the directory. A throw fails the test. */
     capture?(ctx: CoverageCaptureContext): void | Promise<void>;
+    /**
+     * Project paths (gitignore-style patterns, project-relative) whose
+     * changes this adapter's **inventory** accounts for — a package
+     * manifest, a lockfile. The subset selector sets such a changed file
+     * aside instead of treating it as a file no coverage names (which is a
+     * full run), and judges the change by the inventory instead: a unit
+     * that is gone selects the tests that ran it; a gone unit no test ran
+     * is a full run. Part of the wire config (`coverage.explains`).
+     */
+    explains?: readonly string[];
+    /**
+     * The **units** the environment resolved for this service, once per
+     * environment at the bring-up capture: one opaque id per line of the
+     * `inventory.units` report. Dependencies as `<scheme>:<name>@<version>`
+     * (`npm:picocolors@1.1.1`), and a fingerprint per manifest as
+     * `manifest:<project path>#<hash>` over the manifest minus its metadata
+     * keys, so a version bump does not move it and a `scripts` change does.
+     * The control plane compares inventories across runs by string
+     * equality and knows no scheme; what a unit is, is the adapter's.
+     */
+    inventory?(ctx: CoverageInventoryContext): Promise<readonly string[]>;
 }
+/** The report name the harness writes an adapter's inventory to, in the
+ *  bring-up capture only. */
+export declare const INVENTORY_REPORT = "inventory.units";
 /** `ServiceConfig.coverage`: the program writes its own reports (`true`),
  *  or a list of adapters gets them out, and/or how the reports the
  *  program itself writes count (`reports`, default `"cumulative"`). */
@@ -141,12 +188,21 @@ export declare 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
@@ -182,6 +238,25 @@ export declare const NODE_COVERAGE_HOOK: string;
  * 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 declare const NODE_EXPLAINS: readonly string[];
+/** 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 declare const NPM_MANIFEST_METADATA_KEYS: readonly string[];
+/** `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 declare function npmManifestUnit(projectPath: string, text: string): string;
+/**
+ * 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 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;
 /**
  * Ask every node process that holds a hook socket in `dir` for a dump.