@specific.dev/spectest 0.86.0 → 0.86.2

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

@@ -15,8 +15,9 @@
 // One sandbox = one daemon. Concurrency between tests is achieved by
 // forking the sandbox; inside a single daemon we never run two tests at
 // once — that keeps stdout capture and timeouts simple.
+import { preparedImages } from "./harness/prepared-images.js";
 import { execFile, spawn } from "node:child_process";
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { existsSync, promises as fs, readFileSync } from "node:fs";
 import net from "node:net";
 import path from "node:path";
@@ -2947,23 +2948,31 @@ function logBootstrapTimings(t) {
     }
     console.log(`[bootstrap] total ${t.totalMs}ms across ${t.services.length} service(s)`);
 }
-async function bootstrap() {
+async function bootstrap(prepared) {
     // Tee everything this bootstrap logs — ours and every service `setup`
     // hook's — into the boot log, so GET /boot-log can explain a slow or
     // finished boot. Restored in the finally at the end.
     const restoreBootLog = captureConsole(BOOT_LOG_SINK);
     try {
-        return await bootstrapInner();
+        return await bootstrapInner(prepared);
     }
     finally {
         restoreBootLog();
     }
 }
-async function bootstrapInner() {
+async function imageInput(svc) {
+    const input = svc.image.type === "registry" ? svc.image : await resolveDockerfileBuild(svc);
+    return createHash("sha256").update(JSON.stringify(input)).digest("hex");
+}
+async function bootstrapInner(prepared, identity) {
     const bootStart = Date.now();
     const cfg = requireLoaded().project.environment;
     const services = namedServices(cfg);
     const timings = new Map();
+    if (prepared && (prepared.version !== 1 || !prepared.images ||
+        Object.keys(prepared.images).sort().join("\n") !== services.map(s => s.name).sort().join("\n"))) {
+        throw new Error("prepared image manifest does not match the environment's services");
+    }
     progressInit(services);
     // Build dedup is only valid within one workspace generation — a fresh
     // bootstrap may follow a workspace re-upload with the same dockerfile
@@ -3010,11 +3019,25 @@ async function bootstrapInner() {
     const tags = new Map();
     // Bootstrap is the only dedup scope: all its builds share one
     // /workspace generation (see prepareServiceImage).
-    const prepImage = (svc) => prepareServiceImage(svc, { dedup: true });
+    const prepImage = async (svc) => {
+        if (!prepared)
+            return prepareServiceImage(svc, { dedup: true });
+        const entry = prepared.images[svc.name];
+        if (!entry || entry.input !== await imageInput(svc) || !/^sha256:[a-f0-9]{64}$/.test(entry.image)) {
+            throw new Error(`prepared image inputs changed for ${svc.name}`);
+        }
+        const found = await docker(["image", "inspect", "--format", "{{.Id}}", entry.image], 30_000);
+        if (found.code !== 0 || found.stdout.trim() !== entry.image) {
+            throw new Error(`prepared image missing for ${svc.name}: ${entry.image}`);
+        }
+        return { tag: entry.image, buildSteps: entry.buildSteps };
+    };
     const prep = new Map();
+    const prepOffsets = new Map();
     for (const svc of services) {
         const p = (async () => {
             const t0 = Date.now();
+            prepOffsets.set(svc.name, Date.now() - bootStart);
             const { tag, buildSteps } = await prepImage(svc);
             progressService(svc.name, { status: "prepared", detail: undefined });
             tags.set(svc.name, tag);
@@ -3032,6 +3055,21 @@ async function bootstrapInner() {
         p.catch(() => undefined);
         prep.set(svc.name, p);
     }
+    if (identity !== undefined) {
+        // No application services, setup hooks, ingress, or runtime state in the builder.
+        await Promise.all(prep.values());
+        const images = Object.create(null);
+        for (const svc of services) {
+            const out = await docker(["image", "inspect", "--format", "{{.Id}}", tags.get(svc.name)], 30_000);
+            const image = out.stdout.trim();
+            if (out.code !== 0 || !/^sha256:[a-f0-9]{64}$/.test(image)) {
+                throw new Error(`cannot resolve prepared image for ${svc.name}: ${out.stderr}`);
+            }
+            const ti = timings.get(svc.name);
+            images[svc.name] = { input: await imageInput(svc), image, prepMs: ti.prepMs, startMs: prepOffsets.get(svc.name), buildSteps: ti.buildSteps };
+        }
+        return { version: 1, identity, images };
+    }
     // Ingress (fakes + service-tls proxies) comes up BEFORE services so
     // that any service that calls a fake URL during its own startup
     // probe finds it answering. Service-tls proxies will return 502
@@ -3488,8 +3526,13 @@ async function writeCoverageInventory(svc) {
         },
         projectFiles: () => walkProjectFiles(WORKSPACE),
         async readProjectFile(p) {
+            // Not recorded as a read: an inventory fingerprinting every
+            // manifest is bookkeeping, not the suite depending on the files.
+            // Recording them made the setup set name every package.json as a
+            // whole file, so a version bump was "ran during environment
+            // setup" — a full run, the exact case the inventory exists for.
             try {
-                return await fs.readFile(resolveProjectPath(p), "utf8");
+                return await fs.readFile(resolveProjectPath(p, { record: false }), "utf8");
             }
             catch {
                 return null;
@@ -3521,9 +3564,22 @@ async function writeCoverageInventory(svc) {
  * The project's reach (`harness/reach.ts`): every project file some
  * service's build context includes, some volume mounts, or a build
  * reads. Computed from the same resolution the builds use, once at the
- * bring-up capture.
+ * bring-up capture. The resolution's own path lookups are bookkeeping,
+ * not reads: they are taken out of the read set again afterwards.
  */
 async function computeProjectReach(all) {
+    const before = takeProjectReads();
+    try {
+        return await computeProjectReachInner(all);
+    }
+    finally {
+        // Discard what the resolution recorded, restore what was there.
+        takeProjectReads();
+        for (const p of before)
+            resolveProjectPath(p);
+    }
+}
+async function computeProjectReachInner(all) {
     const files = await walkProjectFiles(WORKSPACE, [".git"]);
     const sources = [];
     for (const svc of all) {
@@ -5398,7 +5454,7 @@ function loadedSummary(l) {
  */
 export function harnessMethods(state) {
     return {
-        health: async () => ({ ok: true }),
+        health: async () => ({ ok: true, capabilities: ["prepared-images-v1"] }),
         // Live bootstrap progress, polled by the control plane during
         // `bootstrap` and streamed into the test-run row. `{}` before the
         // first bootstrap of this harness process.
@@ -5497,10 +5553,19 @@ export function harnessMethods(state) {
             }
             return { refs: [...refs] };
         },
-        bootstrap: async () => exclusive(state, "inFlightBootstrap", "bootstrap already in progress", async () => ({
-            ok: true,
-            timings: await bootstrap(),
-        })),
+        prepareImages: async (params) => exclusive(state, "inFlightBootstrap", "bootstrap already in progress", async () => {
+            const restore = captureConsole(BOOT_LOG_SINK);
+            try {
+                return await bootstrapInner(undefined, requireString(params, "identity"));
+            }
+            finally {
+                restore();
+            }
+        }),
+        bootstrap: async (params) => exclusive(state, "inFlightBootstrap", "bootstrap already in progress", async () => {
+            const prepared = params.prepared === undefined ? undefined : preparedImages(params.prepared, params.identity, namedServices(requireLoaded().project.environment).map(s => s.name));
+            return { ok: true, timings: await bootstrap(prepared) };
+        }),
         projectSetup: async () => exclusive(state, "inFlightProjectSetup", "project-setup already in progress", () => runProjectSetup()),
         eval: async (params) => {
             const code = requireString(params, "code");

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

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

package/dist/harness/prepared-images.js

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

package/dist/project-files.d.ts

@@ -14,7 +14,9 @@ export declare function takeProjectReads(): string[];
  * the caller's own `fs` error names a real path — `readProjectFile` keeps
  * reporting ENOENT the way it always has.
  */
-export declare function resolveProjectPath(p: string): string;
+export declare function resolveProjectPath(p: string, opts?: {
+    record?: boolean;
+}): string;
 /** {@link resolveProjectPath}, but a missing file is an error that names every
  *  place we looked. For inputs a user hands us by name — a fixture — where an
  *  ENOENT on one guessed path reads as a spectest bug rather than a typo. */

package/dist/project-files.js

@@ -74,11 +74,16 @@ function relative(p) {
  * the caller's own `fs` error names a real path — `readProjectFile` keeps
  * reporting ENOENT the way it always has.
  */
-export function resolveProjectPath(p) {
+export function resolveProjectPath(p, opts = {}) {
     if (path.isAbsolute(p))
         return p;
     const rel = relative(p);
-    PROJECT_READS.add(rel);
+    // A read is coverage of the file for the case that made it — unless
+    // the caller says otherwise: the harness's own bookkeeping reads (a
+    // coverage inventory fingerprinting every manifest) are not the
+    // suite's dependence on those files.
+    if (opts.record !== false)
+        PROJECT_READS.add(rel);
     if (rel.startsWith("spectest/")) {
         const app = path.join(APP_DIR, rel);
         if (existsSync(app))

package/package.json

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

package/src/components/supabase-dir.test.ts

@@ -113,7 +113,7 @@ describe("supabase({ dir })", () => {
     });
     expect(parts.functions).toBeDefined();
     expect(parts.templates).toBeDefined();
-    expect(stack.group.setup).toBeDefined();
+    expect(parts.migrations?.setup).toBeDefined();
   });
 
   test("an unresolved HTTP hook secret fails with its config key and env name", () => {

package/src/components/supabase-migrations.test.ts

@@ -0,0 +1,116 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { ExecOpts, ServiceSetupContext } from "../index.js";
+import { supabase, type SupabaseOptions } from "./supabase.js";
+
+const roots: string[] = [];
+function fixture(files: Record<string, string> = {}) {
+  const root = mkdtempSync(join(tmpdir(), "supabase-migrations-"));
+  roots.push(root);
+  mkdirSync(join(root, "migrations"));
+  for (const [name, sql] of Object.entries(files)) writeFileSync(join(root, name), sql);
+  return root;
+}
+afterEach(() => {
+  for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true });
+});
+
+function parts(dir: string, options: SupabaseOptions = {}) {
+  const name = options.name ?? "supabase";
+  return supabase({ dir, ...options }).group.services({
+    name, key: (part) => part === "gateway" ? name : `${name}-${part}`,
+  });
+}
+
+test("SQL waits for schema owners; REST waits for SQL without a storage cycle", () => {
+  for (const auth of [false, true]) for (const storage of [false, true]) for (const realtime of [false, true]) {
+    const services = parts(fixture(), { auth, storage, realtime, name: "custom" });
+    expect(services.migrations!.dependsOn).toEqual([
+      "db", ...(auth ? ["auth"] : []), ...(storage ? ["storage"] : []), ...(realtime ? ["realtime"] : []),
+    ]);
+    expect(services.rest!.dependsOn).toEqual(["migrations"]);
+    expect(services.rest!.readyCheck).toMatchObject({ type: "http", port: 3001, path: "/ready" });
+    if (storage) expect(services.storage!.dependsOn).toEqual(["db", "imgproxy"]);
+  }
+});
+
+test("hundreds of sorted migrations and a seed use one exec without reading SQL into the harness", async () => {
+  const root = fixture({ "seed.sql": "select 1" });
+  for (let i = 558; i >= 0; i--) writeFileSync(join(root, "migrations", `${String(i).padStart(4, "0")}.sql`), "select 1");
+  writeFileSync(join(root, "migrations", "ignored.txt"), "not SQL");
+  const services = parts(root);
+  expect(services.db!.volumes).toContainEqual({ source: root, target: "/spectest/supabase", readOnly: true });
+  const calls: { service: string; command: string[]; opts?: ExecOpts }[] = [];
+  await services.migrations!.setup!({
+    exec: async (service: string, command: string[], opts?: ExecOpts) => {
+      calls.push({ service, command, opts });
+      return { exitCode: 0, stdout: "", stderr: "" };
+    },
+  } as ServiceSetupContext);
+  expect(calls).toHaveLength(1);
+  expect(calls[0]!.service).toBe("supabase-db");
+  expect(calls[0]!.opts?.stdin).toBeUndefined();
+  const command = calls[0]!.command;
+  const files = command.flatMap((arg, i) => arg === "-f" ? [command[i + 1]] : []);
+  expect(files).toHaveLength(560);
+  expect(files[0]).toBe("/spectest/supabase/migrations/0000.sql");
+  expect(files.at(-2)).toBe("/spectest/supabase/migrations/0558.sql");
+  expect(files.at(-1)).toBe("/spectest/supabase/seed.sql");
+});
+
+test("an empty SQL directory skips exec; a failed batch preserves psql diagnostics", async () => {
+  const root = fixture();
+  let calls = 0;
+  const ctx = { exec: async () => {
+    calls++;
+    return { exitCode: 3, stdout: "", stderr: "psql:/spectest/supabase/migrations/bad.sql:7: ERROR: broken" };
+  } } as unknown as ServiceSetupContext;
+  await parts(root).migrations!.setup!(ctx);
+  expect(calls).toBe(0);
+  writeFileSync(join(root, "migrations", "bad.sql"), "broken");
+  await expect(parts(root).migrations!.setup!(ctx)).rejects.toThrow("bad.sql:7: ERROR: broken");
+});
+
+// Opt in to a disposable container; no existing database is touched.
+describe.skipIf(process.env.SPECTEST_TEST_SUPABASE_MIGRATIONS !== "1")("real psql migration batching", () => {
+  test("preserves file boundaries, COPY, nontransactional DDL, isolation and fail-fast errors", async () => {
+    const root = fixture({
+      "migrations/01.sql": "CREATE TABLE public.batch_probe (id int); INSERT INTO public.batch_probe VALUES (1)",
+      "migrations/02.sql": "COPY public.batch_probe FROM stdin;\n2\n3\n\\.\nCREATE INDEX CONCURRENTLY batch_idx ON public.batch_probe(id);\nCREATE TEMP TABLE batch_temp (id int); SET search_path = pg_catalog; SET ROLE anon;",
+      "migrations/03 'quoted.sql": "DO $$ BEGIN IF current_user <> 'postgres' OR to_regclass('batch_temp') IS NOT NULL THEN RAISE EXCEPTION 'session leaked'; END IF; END $$;\nINSERT INTO batch_probe VALUES (4); BEGIN; INSERT INTO batch_probe VALUES (99);",
+      "seed.sql": "INSERT INTO batch_probe VALUES (5);",
+    });
+    const name = `spectest-batch-test-${process.pid}`;
+    async function docker(args: string[], stdin = "") {
+      const child = Bun.spawn(["sudo", "docker", ...args], { stdin: new Blob([stdin]), stdout: "pipe", stderr: "pipe" });
+      const [stdout, stderr, exitCode] = await Promise.all([new Response(child.stdout).text(), new Response(child.stderr).text(), child.exited]);
+      return { stdout, stderr, exitCode };
+    }
+    const services = parts(root, { db: { tls: false } });
+    const ctx = { exec: (_service: string, command: string[], opts?: ExecOpts) => docker(["exec", "-i", name, ...command], opts?.stdin) } as ServiceSetupContext;
+    const sql = (statement: string) => ctx.exec(name, ["psql", "-XAt", "-v", "ON_ERROR_STOP=1", "-U", "postgres", "-d", "postgres", "-c", statement]);
+    try {
+      const started = await docker(["run", "-d", "--name", name, "-e", "POSTGRES_PASSWORD=postgres", "-v", `${root}:/spectest/supabase:ro`, "supabase/postgres:17.6.1.136"]);
+      if (started.exitCode) throw new Error(started.stderr);
+      let ready = false;
+      for (let i = 0; i < 120; i++) {
+        if ((await docker(["exec", name, "pg_isready", "-U", "postgres", "-h", "127.0.0.1"])).exitCode === 0) { ready = true; break; }
+        await Bun.sleep(500);
+      }
+      expect(ready).toBe(true);
+      await services.db!.setup!({ ...ctx, name } as ServiceSetupContext);
+      await services.migrations!.setup!(ctx);
+      expect((await sql("SELECT array_agg(id ORDER BY id) FROM batch_probe")).stdout.trim()).toBe("{1,2,3,4,5}");
+      rmSync(join(root, "migrations"), { recursive: true });
+      mkdirSync(join(root, "migrations"));
+      writeFileSync(join(root, "migrations", "broken.sql"), "SELECT 1;\nSELECT * FROM missing_batch_table;\n");
+      writeFileSync(join(root, "seed.sql"), "INSERT INTO batch_probe VALUES (6)");
+      await expect(services.migrations!.setup!(ctx)).rejects.toThrow(/broken.sql:2: ERROR/);
+      expect((await sql("SELECT count(*) FROM batch_probe")).stdout.trim()).toBe("5");
+    } finally {
+      await docker(["rm", "-fv", name]);
+    }
+  }, 180_000);
+});

package/src/components/supabase.ts

@@ -56,7 +56,6 @@ import { dirname, join } from "node:path";
 
 import {
   serviceGroup,
-  type ServiceConfig,
   type ServiceDefinition,
   type ServiceGroup,
   type ServiceSetupContext,
@@ -318,7 +317,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>
    * ```
@@ -1517,34 +1516,16 @@ function buildKongYaml(
 }
 
 // ──────────────────────────────────────────────────────────────────────────
-// Migration application. Runs in the **group's** `setup`, which chains after
-// the primary (the gateway), and the gateway is the group's dependency sink
-// — so by then every service is up and has finished its own bootstrap. That
-// ordering is the whole point:
-//
-//   Several services own schema of their own and create it when THEY boot,
-//   not when the database does. storage-api creates `storage.buckets` /
-//   `storage.objects`; GoTrue creates the modern `auth.*` tables
-//   (`identities`, `sessions`, `mfa_*`, `one_time_tokens`); realtime creates
-//   its own. The stock `supabase/postgres` image ships only the legacy auth
-//   stubs (`auth.users` and friends) and nothing at all under `storage`.
-//
-//   Applied any earlier, an ordinary migration — `insert into
-//   storage.buckets`, a policy on `auth.identities` — fails with `relation
-//   … does not exist`, and the error points at the user's SQL rather than at
-//   the ordering. This is also the point at which `supabase db reset`
-//   applies migrations: against a stack that is already running.
-//
-// The database's OWN bootstrap (roles, JWT GUC, `_realtime` schema) stays in
-// the db service's `setup`, because the other services need it to start at
-// all.
-//
-// Uses the setup context's `exec` (docker exec with piped stdin) and
-// `projectRoot` — no hand-rolled child_process, no hard-coded workspace path.
+// 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.
 // ──────────────────────────────────────────────────────────────────────────
 
-/** Either setup hook's context: the db part's (no helpers) or the group's
- *  (the consolidated handle). Nothing below reads `helpers`. */
+/** Read-only project SQL inside the database container. */
+const SQL_MOUNT = "/spectest/supabase";
+
+/** Shared by the database bootstrap and project migration hooks. */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 type SetupCtx = ServiceSetupContext<any>;
 
@@ -1558,9 +1539,7 @@ async function applySqlFile(
   sql: string,
   label: string,
   user: string,
-  /** 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: string = ctx.name,
 ): Promise<void> {
   const res = await ctx.exec(
@@ -1587,7 +1566,7 @@ async function applySqlFile(
 async function applyMigrations(
   ctx: SetupCtx,
   migrations: string,
-  /** Where `psql` runs — the db part, named from the group hook. */
+  /** Where `psql` runs — the db part, named from the migration hook. */
   db: string,
 ): Promise<void> {
   const dir = migrations.startsWith("/")
@@ -1605,108 +1584,37 @@ async function applyMigrations(
   }
 
   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: SetupCtx,
-  db: string,
-  rest: string,
-): Promise<void> {
-  // 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) return;
-
-  /** One check: are all the tables served right now? */
-  const served = async (): Promise<string[]> => {
-    const res = await fetch(`http://${rest}:3000/`);
-    if (!res.ok) return tables;
-    const spec = (await res.json()) as { paths?: Record<string, unknown> };
-    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: string[] = 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;
+  if (existsSync(seedPath)) paths.push(`${SQL_MOUNT}/seed.sql`);
+  if (paths.length === 0) return;
+
+  // 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.`);
 }
 
 /**
@@ -1979,7 +1887,7 @@ export function supabase(opts: SupabaseOptions = {}): SupabaseStack {
       // be reachable at `realtime-dev.<realtime key>` — the host Kong
       // routes to.
       const realtimeHost = `realtime-dev.${g.key("realtime")}`;
-      const parts: Record<string, ServiceConfig> = {};
+      const parts: ServicesMap = {};
 
       // ── db ──────────────────────────────────────────────────────────
       const dbDef: ServiceDefinition = {
@@ -2006,6 +1914,11 @@ export function supabase(opts: SupabaseOptions = {}): SupabaseStack {
           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.
@@ -2014,8 +1927,7 @@ export function supabase(opts: SupabaseOptions = {}): SupabaseStack {
           // 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),
@@ -2051,10 +1963,10 @@ export function supabase(opts: SupabaseOptions = {}): SupabaseStack {
           ...(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) ─────────
@@ -2241,7 +2153,9 @@ export function supabase(opts: SupabaseOptions = {}): SupabaseStack {
           },
           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 },
         };
       }
@@ -2379,6 +2293,21 @@ export function supabase(opts: SupabaseOptions = {}): SupabaseStack {
         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),
+        } satisfies ServiceDefinition;
+      }
+
       // ── kong (gateway / primary) — no explicit dependsOn: the group
       // expansion makes the primary depend on every member ──────────────
       parts.gateway = {
@@ -2414,15 +2343,6 @@ export function supabase(opts: SupabaseOptions = {}): SupabaseStack {
 
       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: (): SupabaseHelpers => ({
       sql: new SQL(adminDbUrl, { label: name }),

package/src/daemon.ts

@@ -16,9 +16,10 @@
 // forking the sandbox; inside a single daemon we never run two tests at
 // once — that keeps stdout capture and timeouts simple.
 
+import { preparedImages, type PreparedImages } from "./harness/prepared-images.js";
 import { execFile, spawn } from "node:child_process";
 import type { ChildProcess } from "node:child_process";
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { existsSync, promises as fs, readFileSync } from "node:fs";
 import net from "node:net";
 import path from "node:path";
@@ -3512,23 +3513,34 @@ function logBootstrapTimings(t: BootstrapTimings): void {
   console.log(`[bootstrap] total ${t.totalMs}ms across ${t.services.length} service(s)`);
 }
 
-async function bootstrap(): Promise<BootstrapTimings> {
+async function bootstrap(prepared?: PreparedImages): Promise<BootstrapTimings> {
   // Tee everything this bootstrap logs — ours and every service `setup`
   // hook's — into the boot log, so GET /boot-log can explain a slow or
   // finished boot. Restored in the finally at the end.
   const restoreBootLog = captureConsole(BOOT_LOG_SINK);
   try {
-    return await bootstrapInner();
+    return await bootstrapInner(prepared);
   } finally {
     restoreBootLog();
   }
 }
 
-async function bootstrapInner(): Promise<BootstrapTimings> {
+async function imageInput(svc: NamedService): Promise<string> {
+  const input = svc.image.type === "registry" ? svc.image : await resolveDockerfileBuild(svc);
+  return createHash("sha256").update(JSON.stringify(input)).digest("hex");
+}
+
+async function bootstrapInner(prepared?: PreparedImages): Promise<BootstrapTimings>;
+async function bootstrapInner(prepared: undefined, identity: string): Promise<PreparedImages>;
+async function bootstrapInner(prepared?: PreparedImages, identity?: string): Promise<BootstrapTimings | PreparedImages> {
   const bootStart = Date.now();
   const cfg: EnvironmentConfig = requireLoaded().project.environment;
   const services = namedServices(cfg);
   const timings = new Map<string, ServiceTiming>();
+  if (prepared && (prepared.version !== 1 || !prepared.images ||
+      Object.keys(prepared.images).sort().join("\n") !== services.map(s => s.name).sort().join("\n"))) {
+    throw new Error("prepared image manifest does not match the environment's services");
+  }
   progressInit(services);
   // Build dedup is only valid within one workspace generation — a fresh
   // bootstrap may follow a workspace re-upload with the same dockerfile
@@ -3579,12 +3591,24 @@ async function bootstrapInner(): Promise<BootstrapTimings> {
   const tags = new Map<string, string>();
   // Bootstrap is the only dedup scope: all its builds share one
   // /workspace generation (see prepareServiceImage).
-  const prepImage = (svc: NamedService): Promise<{ tag: string; buildSteps?: BuildStep[] }> =>
-    prepareServiceImage(svc, { dedup: true });
+  const prepImage = async (svc: NamedService): Promise<{ tag: string; buildSteps?: BuildStep[] }> => {
+    if (!prepared) return prepareServiceImage(svc, { dedup: true });
+    const entry = prepared.images[svc.name];
+    if (!entry || entry.input !== await imageInput(svc) || !/^sha256:[a-f0-9]{64}$/.test(entry.image)) {
+      throw new Error(`prepared image inputs changed for ${svc.name}`);
+    }
+    const found = await docker(["image", "inspect", "--format", "{{.Id}}", entry.image], 30_000);
+    if (found.code !== 0 || found.stdout.trim() !== entry.image) {
+      throw new Error(`prepared image missing for ${svc.name}: ${entry.image}`);
+    }
+    return { tag: entry.image, buildSteps: entry.buildSteps };
+  };
   const prep = new Map<string, Promise<void>>();
+  const prepOffsets = new Map<string, number>();
   for (const svc of services) {
     const p = (async () => {
       const t0 = Date.now();
+      prepOffsets.set(svc.name, Date.now() - bootStart);
       const { tag, buildSteps } = await prepImage(svc);
       progressService(svc.name, { status: "prepared", detail: undefined });
       tags.set(svc.name, tag);
@@ -3603,6 +3627,22 @@ async function bootstrapInner(): Promise<BootstrapTimings> {
     prep.set(svc.name, p);
   }
 
+  if (identity !== undefined) {
+    // No application services, setup hooks, ingress, or runtime state in the builder.
+    await Promise.all(prep.values());
+    const images: PreparedImages["images"] = Object.create(null);
+    for (const svc of services) {
+      const out = await docker(["image", "inspect", "--format", "{{.Id}}", tags.get(svc.name)!], 30_000);
+      const image = out.stdout.trim();
+      if (out.code !== 0 || !/^sha256:[a-f0-9]{64}$/.test(image)) {
+        throw new Error(`cannot resolve prepared image for ${svc.name}: ${out.stderr}`);
+      }
+      const ti = timings.get(svc.name)!;
+      images[svc.name] = { input: await imageInput(svc), image, prepMs: ti.prepMs, startMs: prepOffsets.get(svc.name), buildSteps: ti.buildSteps };
+    }
+    return { version: 1, identity, images };
+  }
+
   // Ingress (fakes + service-tls proxies) comes up BEFORE services so
   // that any service that calls a fake URL during its own startup
   // probe finds it answering. Service-tls proxies will return 502
@@ -4159,8 +4199,13 @@ async function writeCoverageInventory(svc: NamedService): Promise<string | undef
     },
     projectFiles: () => walkProjectFiles(WORKSPACE),
     async readProjectFile(p: string) {
+      // Not recorded as a read: an inventory fingerprinting every
+      // manifest is bookkeeping, not the suite depending on the files.
+      // Recording them made the setup set name every package.json as a
+      // whole file, so a version bump was "ran during environment
+      // setup" — a full run, the exact case the inventory exists for.
       try {
-        return await fs.readFile(resolveProjectPath(p), "utf8");
+        return await fs.readFile(resolveProjectPath(p, { record: false }), "utf8");
       } catch {
         return null;
       }
@@ -4189,9 +4234,21 @@ async function writeCoverageInventory(svc: NamedService): Promise<string | undef
  * The project's reach (`harness/reach.ts`): every project file some
  * service's build context includes, some volume mounts, or a build
  * reads. Computed from the same resolution the builds use, once at the
- * bring-up capture.
+ * bring-up capture. The resolution's own path lookups are bookkeeping,
+ * not reads: they are taken out of the read set again afterwards.
  */
 async function computeProjectReach(all: NamedService[]): Promise<string[]> {
+  const before = takeProjectReads();
+  try {
+    return await computeProjectReachInner(all);
+  } finally {
+    // Discard what the resolution recorded, restore what was there.
+    takeProjectReads();
+    for (const p of before) resolveProjectPath(p);
+  }
+}
+
+async function computeProjectReachInner(all: NamedService[]): Promise<string[]> {
   const files = await walkProjectFiles(WORKSPACE, [".git"]);
   const sources: ReachSource[] = [];
   for (const svc of all) {
@@ -6484,7 +6541,7 @@ function loadedSummary(l: ReturnType<typeof requireLoaded>) {
  */
 export function harnessMethods(state: RouteState): MethodTable {
   return {
-    health: async () => ({ ok: true }),
+    health: async () => ({ ok: true, capabilities: ["prepared-images-v1"] }),
 
     // Live bootstrap progress, polled by the control plane during
     // `bootstrap` and streamed into the test-run row. `{}` before the
@@ -6593,11 +6650,20 @@ export function harnessMethods(state: RouteState): MethodTable {
       return { refs: [...refs] };
     },
 
-    bootstrap: async () =>
-      exclusive(state, "inFlightBootstrap", "bootstrap already in progress", async () => ({
-        ok: true,
-        timings: await bootstrap(),
-      })),
+    prepareImages: async (params) =>
+      exclusive(state, "inFlightBootstrap", "bootstrap already in progress", async () => {
+        const restore = captureConsole(BOOT_LOG_SINK);
+        try { return await bootstrapInner(undefined, requireString(params, "identity")); }
+        finally { restore(); }
+      }),
+
+    bootstrap: async (params) =>
+      exclusive(state, "inFlightBootstrap", "bootstrap already in progress", async () => {
+        const prepared = params.prepared === undefined ? undefined : preparedImages(
+          params.prepared, params.identity, namedServices(requireLoaded().project.environment).map(s => s.name),
+        );
+        return { ok: true, timings: await bootstrap(prepared) };
+      }),
 
     projectSetup: async () =>
       exclusive(

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

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

package/src/harness/prepared-images.ts

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

package/src/project-files.ts

@@ -80,10 +80,14 @@ function relative(p: string): string {
  * the caller's own `fs` error names a real path — `readProjectFile` keeps
  * reporting ENOENT the way it always has.
  */
-export function resolveProjectPath(p: string): string {
+export function resolveProjectPath(p: string, opts: { record?: boolean } = {}): string {
   if (path.isAbsolute(p)) return p;
   const rel = relative(p);
-  PROJECT_READS.add(rel);
+  // A read is coverage of the file for the case that made it — unless
+  // the caller says otherwise: the harness's own bookkeeping reads (a
+  // coverage inventory fingerprinting every manifest) are not the
+  // suite's dependence on those files.
+  if (opts.record !== false) PROJECT_READS.add(rel);
   if (rel.startsWith("spectest/")) {
     const app = path.join(APP_DIR, rel);
     if (existsSync(app)) return app;