@specific.dev/spectest 0.86.1 → 0.87.0

package/dist/components/supabase.d.ts

@@ -105,7 +105,7 @@ export interface SupabaseOptions {
      * ```
      * supabase/
      *   config.toml     ← auth rules, mail templates, per-function JWT verification
-     *   migrations/     ← applied in filename order once the stack is up
+     *   migrations/     ← applied after Auth/Storage/Realtime, before REST
      *   seed.sql        ← applied after them, if it's there
      *   functions/      ← one directory per function, served at /functions/v1/<name>
      * ```

package/dist/components/supabase.js

@@ -1116,15 +1116,21 @@ function buildKongYaml(key, vals) {
         .join("\n");
     return y;
 }
+// ──────────────────────────────────────────────────────────────────────────
+// Project SQL runs after Auth, Storage and Realtime have created their own
+// schemas, but before PostgREST starts. The migrations part is a dependency
+// barrier: its setup finishes before REST and the gateway can become ready.
+// This prevents the DDL notifications from rebuilding a half-built schema.
+// ──────────────────────────────────────────────────────────────────────────
+/** Read-only project SQL inside the database container. */
+const SQL_MOUNT = "/spectest/supabase";
 /** Pipe one SQL file's contents into `psql` inside the db container. Uses
  *  `psql -f -` (stdin) so multi-statement files and non-transactional DDL
  *  (e.g. `CREATE INDEX CONCURRENTLY`) behave exactly as `supabase db reset`
  *  applies them — not wrapped in a single transaction. `ON_ERROR_STOP=1` fails
  *  fast on the first bad statement. */
 async function applySqlFile(ctx, sql, label, user, 
-/** The db service to run `psql` in. Defaults to the hook's own service,
- *  which is the db only for the bootstrap; the project's migrations run
- *  from the group hook, where `ctx.name` is the gateway. */
+/** The db service to run `psql` in; defaults to the hook's own service. */
 service = ctx.name) {
     const res = await ctx.exec(service, ["psql", "-v", "ON_ERROR_STOP=1", "-U", user, "-d", "postgres", "-f", "-"], { stdin: sql, timeoutMs: 300_000 });
     if (res.exitCode !== 0) {
@@ -1139,7 +1145,7 @@ service = ctx.name) {
  *  Only ever called with a path the user gave: there is no assumed location,
  *  so this never applies SQL nobody asked for. */
 async function applyMigrations(ctx, migrations, 
-/** Where `psql` runs — the db part, named from the group hook. */
+/** Where `psql` runs — the db part, named from the migration hook. */
 db) {
     const dir = migrations.startsWith("/")
         ? migrations
@@ -1153,97 +1159,34 @@ db) {
             `.spectestignore).`);
     }
     const files = (await readdir(dir)).filter((f) => f.endsWith(".sql")).sort();
-    for (const f of files) {
-        const sql = await ctx.readProjectFile(join(dir, f));
-        await applySqlFile(ctx, sql, `migration ${f}`, "postgres", db);
-    }
-    // `seed.sql` sits next to the migrations directory in the layout the
-    // Supabase CLI creates, so it needs no option of its own — pointing at
-    // the migrations is enough to say where the project's SQL lives. Absent
-    // is fine: plenty of projects have migrations and no seed.
+    const paths = files.map((f) => `${SQL_MOUNT}/migrations/${f}`);
     const seedPath = join(dirname(dir), "seed.sql");
-    if (existsSync(seedPath)) {
-        const sql = await ctx.readProjectFile(seedPath);
-        await applySqlFile(ctx, sql, "seed.sql", "postgres", db);
-    }
-}
-/**
- * Make PostgREST serve the schema the migrations just created, and do not
- * return until it does so **stably**.
- *
- * PostgREST reads the schema once, at boot, and now boots before the
- * project's migrations run. Without this, the first REST call for a new
- * table answers `PGRST205 Could not find the table` — the failure the user
- * would otherwise have to diagnose and work around themselves.
- *
- * Two things make this more than one request:
- *
- *  - **A rebuild is not atomic from the outside.** While PostgREST reloads,
- *    a request can still miss the table. So a single successful check is not
- *    proof; the cache has to answer correctly several times in a row.
- *  - **Reloads are already in flight.** The `supabase/postgres` image ships
- *    `pgrst_ddl_watch`, an event trigger that notifies on every DDL, so a
- *    migration run queues several reloads of its own. Ours goes *first* and
- *    the settle loop then waits them all out — checking before sending the
- *    notify was a real bug: the poll passed, our own notify landed after it,
- *    and a test raced the rebuild it caused.
- *
- * The expectation comes from the database itself: every base table in the
- * exposed `public` schema should be listed. A stack with no public tables
- * has nothing to wait for.
- */
-async function reloadPostgrestSchema(ctx, db, rest) {
-    // Ours first, so every reload — ours and the DDL trigger's — is already
-    // queued before we start watching for the result.
-    await applySqlFile(ctx, "notify pgrst, 'reload schema';\n", "schema reload", "postgres", db);
-    // Only the tables PostgREST will actually publish. The spec below is
-    // fetched unauthenticated, so it is the `anon` role's view — and a table
-    // deliberately granted to nobody else (Supabase projects do this routinely:
-    // a lookup table only `supabase_auth_admin` may read, RLS with no anon
-    // grant) never appears in it. Waiting for those would wait for ever, on a
-    // schema cache that is in fact up to date.
-    const listed = await ctx.exec(db, [
-        "psql", "-U", "postgres", "-d", "postgres", "-t", "-A", "-c",
-        "select c.relname from pg_class c join pg_namespace n on n.oid = c.relnamespace " +
-            "where n.nspname = 'public' and c.relkind = 'r' " +
-            // `anon` is created by this component's own bootstrap, so it exists.
-            "and has_table_privilege('anon', c.oid, 'SELECT') order by 1",
-    ], { timeoutMs: 60_000 });
-    const tables = String(listed.stdout)
-        .split("\n")
-        .map((t) => t.trim())
-        .filter(Boolean);
-    if (tables.length === 0)
+    if (existsSync(seedPath))
+        paths.push(`${SQL_MOUNT}/seed.sql`);
+    if (paths.length === 0)
         return;
-    /** One check: are all the tables served right now? */
-    const served = async () => {
-        const res = await fetch(`http://${rest}:3000/`);
-        if (!res.ok)
-            return tables;
-        const spec = (await res.json());
-        const paths = Object.keys(spec.paths ?? {});
-        return tables.filter((t) => !paths.includes(`/${t}`));
-    };
-    const SETTLE = 3;
-    const deadline = Date.now() + 30_000;
-    let streak = 0;
-    let missing = tables;
-    while (Date.now() < deadline) {
-        try {
-            missing = await served();
-            streak = missing.length === 0 ? streak + 1 : 0;
-            if (streak >= SETTLE)
-                return;
-        }
-        catch {
-            // Mid-reload PostgREST can refuse the connection outright.
-            streak = 0;
+    // Repeated -f keeps psql's file boundaries (COPY, EOF without a semicolon,
+    // and filename:line diagnostics), with one docker exec and one connection.
+    // Do not use --single-transaction: concurrent indexes and explicit
+    // transaction control in existing migrations must continue to work.
+    const command = ["psql", "-X", "-q", "-v", "ON_ERROR_STOP=1", "-U", "postgres", "-d", "postgres"];
+    for (const path of paths) {
+        if (path !== paths[0]) {
+            // Each file previously had its own session. Roll back unfinished work
+            // and discard roles, GUCs, temporary tables, prepared statements and
+            // advisory locks before the next file. Separate -c calls are essential:
+            // DISCARD ALL cannot execute inside a multi-statement transaction.
+            command.push("-c", "\\set ON_ERROR_STOP on", "-c", "\\set AUTOCOMMIT on");
+            command.push("-c", "ROLLBACK", "-c", "DISCARD ALL");
         }
-        await new Promise((r) => setTimeout(r, 150));
+        command.push("-f", path);
     }
-    throw new Error(`supabase: PostgREST did not settle on the migrated schema within 30s ` +
-        `(still missing: ${missing.join(", ") || "nothing, but not stably"}). ` +
-        `The migrations applied — this is the REST schema cache, not your SQL.`);
+    const started = Date.now();
+    const res = await ctx.exec(db, command, { timeoutMs: 300_000 });
+    if (res.exitCode !== 0) {
+        throw new Error(`supabase: applying migrations/seed failed (psql rc=${res.exitCode}):\n${res.stderr.trim() || res.stdout.trim()}`);
+    }
+    console.log(`supabase(): applied ${files.length} migrations${paths.length > files.length ? " and seed.sql" : ""} in ${((Date.now() - started) / 1000).toFixed(1)}s.`);
 }
 /**
  * A ready-to-use self-hosted Supabase stack. Mount `.group` at the key
@@ -1496,6 +1439,11 @@ export function supabase(opts = {}) {
                     JWT_SECRET: jwtSecret,
                     JWT_EXP: "3600",
                 },
+                // Read SQL directly, including large seeds, without copying it through
+                // the harness and docker exec stdin. Keep this out of PGDATA.
+                ...(migrationsPath === null ? {} : {
+                    volumes: [{ source: dirname(migrationsPath), target: SQL_MOUNT, readOnly: true }],
+                }),
                 ports: [5432],
                 // `pg_isready` succeeds only once the image finishes initdb + its
                 // baked init-scripts and starts serving for real.
@@ -1504,8 +1452,7 @@ export function supabase(opts = {}) {
                     // Only the database's own bootstrap (role passwords / JWT GUC /
                     // `_realtime` schema) runs here: the other services need it before
                     // they can start. The project's migrations run later, from the
-                    // group hook, once the whole stack is up — see the migration
-                    // section above for why.
+                    // migrations hook, once the schema-owning services are up.
                     await applySqlFile(ctx, buildBootstrapSql(dbPassword, jwtSecret, withRealtime), "supabase bootstrap", 
                     // The bootstrap alters reserved roles (authenticator, …) and the
                     // database — superuser-only. `postgres` is deliberately NOT a
@@ -1537,10 +1484,10 @@ export function supabase(opts = {}) {
                     ...(mapped?.rest ?? {}),
                 },
                 ports: [3000],
-                dependsOn: ["db"],
-                // PostgREST opens :3000 only after connecting to the DB and loading
-                // the schema cache, so a TCP connect is a good ready signal.
-                readyCheck: { type: "tcp", port: 3000, timeoutSecs: 120 },
+                dependsOn: [migrationsPath === null ? "db" : "migrations"],
+                // The HTTP socket can open before schema loading completes. /ready
+                // checks both the database pool and the populated schema cache.
+                readyCheck: { type: "http", port: 3001, path: "/ready", timeoutSecs: 120 },
             };
             // ── mail (SMTP capture, the standard email() component) ─────────
             if (withMail && !mailExternal) {
@@ -1719,7 +1666,9 @@ export function supabase(opts = {}) {
                     },
                     volumes: [storageData],
                     ports: [5000],
-                    dependsOn: ["db", "rest", "imgproxy"],
+                    // Storage initializes and serves /status using Postgres directly;
+                    // POSTGREST_URL does not require REST to run during its bootstrap.
+                    dependsOn: ["db", "imgproxy"],
                     readyCheck: { type: "http", port: 5000, path: "/status", timeoutSecs: 90 },
                 };
             }
@@ -1846,6 +1795,20 @@ export function supabase(opts = {}) {
                 };
                 parts.functions = functionsDef;
             }
+            if (migrationsPath !== null) {
+                parts.migrations = {
+                    // Reuse an already required image for this lightweight setup barrier.
+                    image: dbDef.image,
+                    command: "exec sleep infinity",
+                    dependsOn: [
+                        "db",
+                        ...(withAuth ? ["auth"] : []),
+                        ...(withStorage ? ["storage"] : []),
+                        ...(withRealtime ? ["realtime"] : []),
+                    ],
+                    setup: (ctx) => applyMigrations(ctx, migrationsPath, db),
+                };
+            }
             // ── kong (gateway / primary) — no explicit dependsOn: the group
             // expansion makes the primary depend on every member ──────────────
             parts.gateway = {
@@ -1879,16 +1842,6 @@ export function supabase(opts = {}) {
             };
             return parts;
         },
-        // The project's own SQL, applied with the whole stack up (the group
-        // hook chains after the primary, and the primary is the group's
-        // dependency sink). Still inside bring-up, so the result is captured
-        // into the cached environment like everything else.
-        setup: async (ctx) => {
-            if (migrationsPath === null)
-                return;
-            await applyMigrations(ctx, migrationsPath, dbKey);
-            await reloadPostgrestSchema(ctx, dbKey, `${name}-rest`);
-        },
         // The group's consolidated handle at `ctx.svc.<name>`.
         helpers: () => ({
             sql: new SQL(adminDbUrl, { label: name }),

package/dist/daemon.js

@@ -24,7 +24,7 @@ import path from "node:path";
 import { pathToFileURL } from "node:url";
 import { ENVIRONMENT_CA_PATH as CA_PATH } from "./environment-ca.js";
 import { assert, expect, expectRaw, lowerIngress, dnsName as makeDnsDecl, isWildcard, validateServiceImage, proxy as makeProxyDecl, } from "./index.js";
-import { COVERAGE_CONTAINER_DIR, coverageBundleRef, coverageHostDir, encodeCoverageBundle, isEmptyReport, readCoverageDir, applyCoverageDelta, walkProjectFiles, ENVIRONMENT_SERVICE, REACH_REPORT, } from "./harness/coverage.js";
+import { COVERAGE_CONTAINER_DIR, coverageBundleRef, coverageHostDir, encodeCoverageBundle, isEmptyReport, readCoverageDir, applyCoverageDelta, walkProjectFiles, ENVIRONMENT_SERVICE, REACH_REPORT, READS_REPORT, } from "./harness/coverage.js";
 import { configureBrowserCoverage } from "./browser-coverage.js";
 import { INVENTORY_REPORT, NODE_COVERAGE_MARKERS_SUBDIR, NODE_COVERAGE_SCRIPTS_SUBDIR, applyCoverageAdapters, coverageAdapters, coverageReportsMode, validateCoverage, } from "./coverage.js";
 import { serviceForHost as hostToService } from "./harness/browser-coverage.js";
@@ -41,10 +41,10 @@ import { summarizeBuildKit } from "./harness/buildkit-progress.js";
 import { LOG_DELTA_MAX_BYTES, capMiddle, streamDelta } from "./harness/log-delta.js";
 import { resolveHostPath as resolveVolumeHostPath, sanitizeSegment, } from "./harness/volume-paths.js";
 import { pollUntilReady } from "./harness/ready-poll.js";
-import { runWrapperRules } from "./harness/wrapper-rules.js";
+import { fsUsageDiagnostics, runWrapperRules } from "./harness/wrapper-rules.js";
 import { cpus } from "node:os";
 import { APP_DIR, WORKSPACE, resolveExistingProjectPath, resolveProjectPath, takeProjectReads } from "./project-files.js";
-import { projectReach, renderReach, renderReadsLcov } from "./harness/reach.js";
+import { compactReach, projectReach, renderReachRules, renderReadsLcov } from "./harness/reach.js";
 import { installFetchWrapper, isTransportError } from "./harness/fetch.js";
 import { bindInstrumentationScope, createInstrumentationScope, runInstrumented, runUninstrumented, } from "./harness/instrumentation-scope.js";
 import { encodeRegistry } from "./harness/names-registry.js";
@@ -3584,6 +3584,7 @@ async function computeProjectReachInner(all) {
     const sources = [];
     for (const svc of all) {
         const src = {
+            service: svc.name,
             volumeSources: (svc.volumes ?? []).flatMap((v) => (v.source ? [v.source] : [])),
         };
         if (svc.image.type === "dockerfile") {
@@ -3603,29 +3604,33 @@ async function computeProjectReachInner(all) {
         }
         sources.push(src);
     }
-    return projectReach(files, sources);
+    const reach = projectReach(files, sources);
+    return { version: 1, sources, prefixes: compactReach(files, reach) };
 }
 /**
  * The synthetic `__environment__` capture: what the environment itself
- * knows — the project's reach (bring-up only) and the project files the
- * harness read through the SDK since the previous capture, as whole
- * lcov records. Present whenever some service opted in, so the two ride
- * the same bundle as the services' reports.
+ * knows — the project's reach as rules (bring-up only) and the project
+ * files the harness read through the SDK since the previous capture, as
+ * whole lcov records. Present on every capture of every project, coverage
+ * adapters or not: the reach is a property of the environment config,
+ * and it is what lets the control plane tell that a change to `site/**`
+ * can affect no test at all. When services opted in, the two ride the
+ * same bundle as their reports.
  */
 async function captureEnvironmentCoverage(all, baseline) {
     const reports = [];
     if (baseline) {
         try {
-            const reach = await computeProjectReach(all);
-            reports.push({ name: REACH_REPORT, content: renderReach(reach) });
-            console.log(`[coverage] project reach: ${reach.length} file(s) some build or volume can carry`);
+            const rules = await computeProjectReach(all);
+            reports.push({ name: REACH_REPORT, content: renderReachRules(rules) });
+            console.log(`[coverage] project reach: ${rules.sources.length} source(s), ${rules.prefixes.length} prefix(es) some build or volume can carry`);
         }
         catch (err) {
             console.warn(`[coverage] project reach not computed: ${err instanceof Error ? err.message : String(err)}`);
         }
     }
     const reads = takeProjectReads();
-    reports.push({ name: "reads.lcov", content: renderReadsLcov(reads) });
+    reports.push({ name: READS_REPORT, content: renderReadsLcov(reads) });
     return { service: ENVIRONMENT_SERVICE, reports };
 }
 async function captureServiceCoverage(baseline = false) {
@@ -3639,8 +3644,8 @@ async function captureServiceCoverage(baseline = false) {
         byName.set(name, s);
     const all = [...byName.values()];
     const services = all.filter((s) => s.coverage !== undefined);
-    if (services.length === 0)
-        return [];
+    // The environment's own capture is unconditional (see above); the
+    // services' come from the ones that opted in, none included.
     const environment = captureEnvironmentCoverage(all, baseline);
     const captures = await Promise.all(services.map(async (svc) => {
         const { error, deltaReports } = await runCoverageAdapters(svc);
@@ -5352,7 +5357,7 @@ async function runTypecheck() {
         return { status: "failed", errors: [], totalErrors: 0, durationMs, detail: "typecheck timed out" };
     }
     const { errors, total, suppressed } = parseTscOutput(res.stdout + res.stderr);
-    const wrapper = await runWrapperRulesReport(config);
+    const wrapper = [...(await runWrapperRulesReport(config)), ...(await rawFsReport())];
     const strip = ({ file, line, column, code, message }) => ({
         file,
         line,
@@ -5389,6 +5394,31 @@ async function runTypecheck() {
         ...(blocking.length > 0 ? { blocking } : {}),
     };
 }
+/**
+ * The raw-fs rule (`SPECTEST2003`, advisory) over the test tree: a test
+ * that opens a project file through `node:fs` hides a dependence from the
+ * subset selector. Textual, so it needs no compiler; best-effort.
+ */
+async function rawFsReport() {
+    const root = path.join(APP_DIR, "tests");
+    if (!existsSync(root))
+        return [];
+    try {
+        const files = await walkProjectFiles(root, ["node_modules"]);
+        const out = [];
+        for (const rel of files) {
+            if (!/\.(ts|tsx|js|jsx|mts|cts)$/.test(rel))
+                continue;
+            const text = await fs.readFile(path.join(root, rel), "utf8");
+            out.push(...fsUsageDiagnostics(path.join("tests", rel), text));
+        }
+        return out;
+    }
+    catch (err) {
+        console.warn(`[typecheck] raw fs rule threw: ${err?.message ?? err}`);
+        return [];
+    }
+}
 /**
  * The blocking rules, run against the BAKED compiler whatever the project
  * pins. Best-effort in every direction: an install that predates the API, a

package/dist/harness/coverage.d.ts

@@ -3,9 +3,12 @@ export declare const COVERAGE_CONTAINER_DIR = "/spectest/coverage";
 /** The synthetic service the environment's own reports ride under: the
  *  project's reach (bring-up) and the project files the harness read. */
 export declare const ENVIRONMENT_SERVICE = "__environment__";
-/** The bring-up report listing the project's reach, one project-relative
- *  path per line (`harness/reach.ts`). */
-export declare const REACH_REPORT = "reach.paths";
+/** The bring-up report carrying the project's reach as rules plus a
+ *  compacted prefix list (`harness/reach.ts`, `ReachRules`). */
+export declare const REACH_REPORT = "reach.json";
+/** The per-capture report naming the project files the harness read
+ *  through the SDK since the previous capture, as whole lcov records. */
+export declare const READS_REPORT = "reads.lcov";
 /** Raw bytes of reports one service may ship per capture. Reports are
  *  bounded by code size times chain depth, so anything past this is a
  *  runaway (a tool writing a new file per request), not coverage. */
@@ -82,6 +85,9 @@ 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 `text` is a `reach.json` document: a JSON object with a
+ *  `sources` array and a `prefixes` array. */
+export declare function isReachRules(text: 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`, a units list
  *  with no unit). */

package/dist/harness/coverage.js

@@ -36,9 +36,12 @@ export const COVERAGE_CONTAINER_DIR = "/spectest/coverage";
 /** The synthetic service the environment's own reports ride under: the
  *  project's reach (bring-up) and the project files the harness read. */
 export const ENVIRONMENT_SERVICE = "__environment__";
-/** The bring-up report listing the project's reach, one project-relative
- *  path per line (`harness/reach.ts`). */
-export const REACH_REPORT = "reach.paths";
+/** The bring-up report carrying the project's reach as rules plus a
+ *  compacted prefix list (`harness/reach.ts`, `ReachRules`). */
+export const REACH_REPORT = "reach.json";
+/** The per-capture report naming the project files the harness read
+ *  through the SDK since the previous capture, as whole lcov records. */
+export const READS_REPORT = "reads.lcov";
 /** Raw bytes of reports one service may ship per capture. Reports are
  *  bounded by code size times chain depth, so anything past this is a
  *  runaway (a tool writing a new file per request), not coverage. */
@@ -89,12 +92,27 @@ export function isUnitsReport(text) {
 export function isWellFormedReport(text, name = "") {
     if (name.endsWith(".units"))
         return isUnitsReport(text);
+    if (name === REACH_REPORT)
+        return isReachRules(text);
     return isLcovShaped(text) || isV8CoverageJson(text) || isSpectestScriptRecord(text);
 }
+/** True when `text` is a `reach.json` document: a JSON object with a
+ *  `sources` array and a `prefixes` array. */
+export function isReachRules(text) {
+    try {
+        const v = JSON.parse(text);
+        return typeof v === "object" && v !== null && Array.isArray(v.sources) && Array.isArray(v.prefixes);
+    }
+    catch {
+        return false;
+    }
+}
 /** True when a well-formed report names no source file at all (an lcov
  *  with no `SF:`, a V8 document with an empty `result`, a units list
  *  with no unit). */
 export function isEmptyReport(text) {
+    if (isReachRules(text))
+        return false;
     if (isV8CoverageJson(text))
         return /"result"\s*:\s*\[\s*\]/.test(text);
     if (isSpectestScriptRecord(text))

package/dist/harness/reach.d.ts

@@ -12,6 +12,8 @@ export declare function compileDockerignore(text: string): Pattern[];
 export declare function isExcluded(patterns: Pattern[], rel: string): boolean;
 /** One service's contribution to the reach. */
 export interface ReachSource {
+    /** The service the source belongs to (for the shadow page's verdicts). */
+    service?: string;
     /** Build context directory, project-relative (`.` for the root); absent
      *  for a registry image. */
     context?: string;
@@ -30,8 +32,33 @@ export interface ReachSource {
  * Dockerfiles the builds read. Sorted, unique.
  */
 export declare function projectReach(files: readonly string[], sources: readonly ReachSource[]): string[];
-/** The `reach.paths` report: one path per line. */
-export declare function renderReach(paths: readonly string[]): string;
+/** The `reach.json` report. Mirrors `reach::ReachRules` on the server. */
+export interface ReachRules {
+    version: 1;
+    /** Every service's contribution, as rules. */
+    sources: ReachSource[];
+    /** The current file reach, compacted: `dir/` for a directory every
+     *  project file of which is in the reach, a bare path for a file on its
+     *  own, `.` when the whole project is. */
+    prefixes: string[];
+}
+/**
+ * Compact a file reach against the project's file list: a directory
+ * whose every file is in the reach becomes one `dir/` prefix (the root
+ * becomes `.`), and a file whose directory is not wholly reached stays a
+ * path. Only directories that hold a project file exist here; an empty
+ * directory has nothing to be in or out of the reach.
+ */
+export declare function compactReach(files: readonly string[], reach: readonly string[]): string[];
+/** Is `path` (project-relative) in the reach the rules describe? The
+ *  compacted prefixes answer first; a path outside them is evaluated
+ *  against every source, so a file that did not exist when the prefixes
+ *  were computed gets the same answer the build would give. */
+export declare function reachContains(rules: ReachRules, path: string): boolean;
+/** The first source whose rules carry `path`, or `undefined`. */
+export declare function sourceOf(sources: readonly ReachSource[], path: string): ReachSource | undefined;
+/** The `reach.json` report text. */
+export declare function renderReachRules(rules: ReachRules): string;
 /** An lcov document that names `paths` as files with no line data —
  *  "whole" records, which the index reads as every line unknown, so any
  *  change to the file selects the case that read it. */

package/dist/harness/reach.js

@@ -4,14 +4,24 @@
 // a service's **build context** (so an image may carry it), it is the
 // **source of a volume** a service mounts, or a test **reads** it through
 // the SDK. The first two are known from the environment config before any
-// test runs; the harness computes their union here — the project's
-// **reach** — and ships it with the bring-up capture (`reach.paths`, one
-// project-relative path per line, under the synthetic `__environment__`
-// service). The subset selector then treats a changed file outside the
-// reach as one that cannot affect the suite: `site/**` behind a
+// test runs; the harness ships them with the bring-up capture as
+// **rules** (`reach.json`, under the synthetic `__environment__`
+// service): per service its context directory, the composed
+// `.dockerignore` text, the Dockerfile it reads and the volume sources it
+// mounts. Rules, not a file list: the control plane evaluates any changed
+// path against them, a file that did not exist at the base included, and
+// a project of ten thousand files ships a few lines. Beside the rules
+// rides a **compacted** view of the current file reach — a directory
+// every file of which is in the reach as one `dir/` prefix, the odd file
+// alone — which the control plane uses as a fast path and the shadow page
+// as the summary. The subset selector then treats a changed file outside
+// the reach as one that cannot affect the suite: `site/**` behind a
 // `.dockerignore`, `.github/**` outside every context. The third door is
 // recorded as it happens (`project-files.ts`, `takeProjectReads`).
 //
+// The rules are shipped for every project, coverage adapters or not: the
+// reach is a property of the environment config alone.
+//
 // The context of a build is what `docker build` would send: every file
 // under the context directory minus what the composed `.dockerignore`
 // (the project's own rules plus the service's `exclude`) matches, with
@@ -144,9 +154,101 @@ export function projectReach(files, sources) {
     }
     return [...out].sort();
 }
-/** The `reach.paths` report: one path per line. */
-export function renderReach(paths) {
-    return paths.join("\n") + (paths.length ? "\n" : "");
+/**
+ * Compact a file reach against the project's file list: a directory
+ * whose every file is in the reach becomes one `dir/` prefix (the root
+ * becomes `.`), and a file whose directory is not wholly reached stays a
+ * path. Only directories that hold a project file exist here; an empty
+ * directory has nothing to be in or out of the reach.
+ */
+export function compactReach(files, reach) {
+    const inReach = new Set(reach);
+    // Per directory: how many project files live below it, how many of
+    // those the reach holds. "" is the root.
+    const total = new Map();
+    const hit = new Map();
+    const children = new Map();
+    const filesIn = new Map();
+    for (const f of files) {
+        const parts = f.split("/");
+        let dir = "";
+        for (let i = 0; i < parts.length; i += 1) {
+            total.set(dir, (total.get(dir) ?? 0) + 1);
+            if (inReach.has(f))
+                hit.set(dir, (hit.get(dir) ?? 0) + 1);
+            if (i === parts.length - 1) {
+                let list = filesIn.get(dir);
+                if (!list)
+                    filesIn.set(dir, (list = []));
+                list.push(f);
+            }
+            else {
+                const child = dir === "" ? parts[i] : `${dir}/${parts[i]}`;
+                let set = children.get(dir);
+                if (!set)
+                    children.set(dir, (set = new Set()));
+                set.add(child);
+                dir = child;
+            }
+        }
+    }
+    const out = [];
+    const walk = (dir) => {
+        const n = total.get(dir) ?? 0;
+        if (n > 0 && (hit.get(dir) ?? 0) === n) {
+            out.push(dir === "" ? "." : `${dir}/`);
+            return;
+        }
+        for (const f of filesIn.get(dir) ?? [])
+            if (inReach.has(f))
+                out.push(f);
+        for (const c of children.get(dir) ?? [])
+            walk(c);
+    };
+    walk("");
+    return out.sort();
+}
+/** Is `path` (project-relative) in the reach the rules describe? The
+ *  compacted prefixes answer first; a path outside them is evaluated
+ *  against every source, so a file that did not exist when the prefixes
+ *  were computed gets the same answer the build would give. */
+export function reachContains(rules, path) {
+    const p = normRel(path);
+    for (const pre of rules.prefixes) {
+        if (pre === "." || pre === p || (pre.endsWith("/") && p.startsWith(pre)))
+            return true;
+    }
+    return sourceOf(rules.sources, p) !== undefined;
+}
+/** The first source whose rules carry `path`, or `undefined`. */
+export function sourceOf(sources, path) {
+    const p = normRel(path);
+    for (const s of sources) {
+        if (s.context !== undefined) {
+            const ctx = normRel(s.context);
+            const prefix = ctx === "" ? "" : `${ctx}/`;
+            if (!prefix || p.startsWith(prefix)) {
+                const rel = p.slice(prefix.length);
+                if (rel === ".dockerignore" || rel === "Dockerfile" || !isExcluded(compileDockerignore(s.ignore ?? ""), rel))
+                    return s;
+            }
+        }
+        for (const e of s.extraFiles ?? [])
+            if (normRel(e) === p)
+                return s;
+        for (const v of s.volumeSources ?? []) {
+            if (v.startsWith("/"))
+                continue;
+            const src = normRel(v);
+            if (p === src || p.startsWith(`${src}/`))
+                return s;
+        }
+    }
+    return undefined;
+}
+/** The `reach.json` report text. */
+export function renderReachRules(rules) {
+    return JSON.stringify(rules);
 }
 /** An lcov document that names `paths` as files with no line data —
  *  "whole" records, which the index reads as every line unknown, so any

package/dist/harness/wrapper-rules.d.ts

@@ -1,3 +1,16 @@
+/**
+ * A test that opens a project file through `node:fs` (or `Bun.file`)
+ * instead of `ctx.readProjectFile`. **Advisory.** The subset selector
+ * learns which project files a test depends on from the reads the SDK
+ * serves (`project-files.ts`); a raw read is a dependence it never sees,
+ * so a change to that file can skip the test. The rule is textual — an
+ * import or `require` of the fs modules, or a `Bun.file(` call — and is
+ * applied to the test tree only, where the alternative exists. It turns
+ * blocking when the reach gate enforces (`SUBSET_RUNS.md`).
+ */
+export declare const CODE_RAW_FS = "SPECTEST2003";
+/** The raw-fs findings of one test file, from its text alone. */
+export declare function fsUsageDiagnostics(file: string, text: string): WrapperDiagnostic[];
 /** A finding, shaped like the `TypecheckError` the report already carries. */
 export interface WrapperDiagnostic {
     /** Path relative to the app dir, matching the advisory diagnostics. */