@specific.dev/spectest 0.63.0 → 0.66.0

package/dist/components/supabase.d.ts

@@ -33,6 +33,20 @@ export interface SupabaseOptions {
     storage?: boolean;
     /** Include Realtime (`<name>-realtime`). Default `true`. */
     realtime?: boolean;
+    /**
+     * Edge functions. `isolation` picks how they run on the edge runtime:
+     * `"shared"` (default) loads every function into **one** isolate, so a
+     * shared module graph (`_shared/`, npm packages) is loaded once rather than
+     * once per function — measured on a 51-function project as 230 MB against
+     * 3.6 GB. Hosted Supabase runs one isolate per function, and the one thing
+     * that differs is module-level state: a singleton in `_shared` is one
+     * object for all functions here, one per function there. `"per-function"`
+     * runs it the hosted way. Either way the runtime, the request each
+     * function sees and the per-function `verify_jwt` are the same.
+     */
+    functions?: {
+        isolation?: "shared" | "per-function";
+    };
     /**
      * Also serve the gateway over **HTTPS** at `https://<hostname>` via the
      * daemon's CA-trusted TLS reverse proxy (in addition to the plain

package/dist/components/supabase.js

@@ -698,12 +698,307 @@ async function validJwt(token: string): Promise<boolean> {
   }
 }
 
+/** How the functions run: every function in one isolate (the default), or
+ *  one isolate per function as hosted Supabase does — see sharedWorker. */
+const ISOLATION = Deno.env.get("FUNCTIONS_ISOLATION") === "per-function" ? "per-function" : "shared";
+/** Where the generated entry of the shared isolate lives — outside the repo
+ *  mount, which is read-only and the user's checkout, and NOT under /tmp:
+ *  the runtime gives its workers an in-memory /tmp, so a file the main
+ *  worker writes there does not exist for the user worker's bootstrap
+ *  ("could not find an appropriate entrypoint"). */
+const SHARED_DIR = "/home/deno/spectest-functions";
+const WORKER_TIMEOUT_MS = 24 * 60 * 60 * 1000;
+
+/** One isolate per function, reused across requests (the runtime pools by
+ *  servicePath). The idle timeout is a day, not upstream's five minutes: a
+ *  test environment is a snapshot lineage whose forks inherit these
+ *  isolates, and an isolate reaped for idleness is rebooted by the next
+ *  test that calls the function — a boot's worth of dirtied memory in that
+ *  test's own snapshot diff. */
+function workerFor(name: string) {
+  return EdgeRuntime.userWorkers.create({
+    servicePath: FUNCTIONS_DIR + "/" + name,
+    memoryLimitMb: 256,
+    workerTimeoutMs: WORKER_TIMEOUT_MS,
+    noModuleCache: false,
+    importMapPath: null,
+    envVars: Object.entries(Deno.env.toObject()),
+  });
+}
+
+async function exists(path: string): Promise<boolean> {
+  try {
+    await Deno.stat(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** The function directories: every child of FUNCTIONS_DIR with an index.ts,
+ *  minus the conventional private ones. */
+async function functionNames(): Promise<string[]> {
+  const names: string[] = [];
+  for await (const entry of Deno.readDir(FUNCTIONS_DIR)) {
+    if (!entry.isDirectory || entry.name.startsWith("_") || entry.name.startsWith(".")) continue;
+    if (await exists(FUNCTIONS_DIR + "/" + entry.name + "/index.ts")) names.push(entry.name);
+  }
+  return names.sort();
+}
+
+/** Every "https://deno.land/std@…/http/server.ts" a source under the
+ *  functions directory imports — the legacy serve() each of them has to be
+ *  redirected to the shim in the shared isolate. */
+async function stdServerUrls(dir: string, out: Set<string>): Promise<void> {
+  for await (const e of Deno.readDir(dir)) {
+    const p = dir + "/" + e.name;
+    if (e.isDirectory) {
+      if (e.name !== "node_modules" && !e.name.startsWith(".")) await stdServerUrls(p, out);
+      continue;
+    }
+    if (!/\.(ts|tsx|js|mjs|jsx)$/.test(e.name)) continue;
+    const src = await Deno.readTextFile(p);
+    for (const m of src.matchAll(/https:\/\/deno\.land\/std@[0-9.]+\/http\/server\.ts/g)) out.add(m[0]);
+  }
+}
+
+// ── The shared isolate ────────────────────────────────────────────────────
+//
+// The runtime's own model is one isolate per function, each loading its own
+// copy of the module graph. On a project with dozens of functions sharing a
+// \`_shared/\` tree that is dozens of copies of the same graph — measured at
+// ~90 MB and ~1 s per function, against 18 MB for an empty isolate — and in
+// an 8 GB guest that memory comes straight out of the page cache every test
+// needs. So by default every function is loaded into ONE user worker: a
+// generated entry module imports each function's index.ts in turn, a prelude
+// (imported first, so it runs first) has replaced \`Deno.serve\` with a
+// registration that records the handler under the function whose module is
+// calling, the std \`serve()\` the older functions use is redirected to the
+// same registration by an import map, and the worker's own server routes a
+// request to the handler of the function its path names. The runtime, the
+// request a function receives and the per-function JWT check are unchanged;
+// what differs from hosted Supabase is that module-level state is one
+// object for every function rather than one per function.
+//
+// It stands in only where it can be exact. A function with its own
+// deno.json / import map (per-function resolution the one config cannot
+// express), a functions/deno.jsonc (comments; not merged) or a config that
+// names an importMap keep the per-function isolates, and so does a shared
+// isolate that fails to boot — with the reason in the log, since a boot
+// failure names the module at fault.
+
+interface SharedSpec {
+  names: string[];
+  reason: string | null;
+}
+let sharedSpec: Promise<SharedSpec> | null = null;
+
+/** Why the shared isolate cannot stand in for per-function ones, or null. */
+async function sharedBlocker(names: string[]): Promise<string | null> {
+  for (const n of names) {
+    for (const f of ["deno.json", "deno.jsonc", "import_map.json"]) {
+      if (await exists(FUNCTIONS_DIR + "/" + n + "/" + f)) return "function \"" + n + "\" has its own " + f;
+    }
+  }
+  if (await exists(FUNCTIONS_DIR + "/deno.jsonc")) return "functions/deno.jsonc is not merged (comments)";
+  return null;
+}
+
+/** POSIX-relative path from directory \`from\` to \`to\`. The entry imports the
+ *  functions relatively: an absolute file specifier is refused by the
+ *  runtime's module bundler ("Module not found"), a relative one resolves. */
+function relativePath(from: string, to: string): string {
+  const a = from.split("/").filter(Boolean);
+  const b = to.split("/").filter(Boolean);
+  let i = 0;
+  while (i < a.length && i < b.length && a[i] === b[i]) i++;
+  const up = a.slice(i).map(() => "..");
+  const rel = [...up, ...b.slice(i)].join("/");
+  return rel.startsWith(".") ? rel : "./" + rel;
+}
+
+function reString(s: string): string {
+  return s.replace(/[.*+?^$()|[\]\\\/{}]/g, "\\$&");
+}
+
+/** Write SHARED_DIR: the entry, the prelude, the std shim and the config. */
+async function writeShared(names: string[]): Promise<string | null> {
+  await Deno.mkdir(SHARED_DIR, { recursive: true });
+
+  // Config: the project's functions/deno.json (its imports are what every
+  // function resolves against) plus the std shim redirections.
+  let cfg: Record<string, unknown> = {};
+  if (await exists(FUNCTIONS_DIR + "/deno.json")) {
+    try {
+      cfg = JSON.parse(await Deno.readTextFile(FUNCTIONS_DIR + "/deno.json"));
+    } catch (e) {
+      return "functions/deno.json could not be parsed: " + String(e);
+    }
+    if (typeof cfg.importMap === "string") return "functions/deno.json names an importMap";
+  }
+  const urls = new Set<string>();
+  await stdServerUrls(FUNCTIONS_DIR, urls);
+  const imports: Record<string, string> = { ...((cfg.imports as Record<string, string>) ?? {}) };
+  for (const u of urls) imports[u] = "./std-http-server.ts";
+  await Deno.writeTextFile(
+    SHARED_DIR + "/deno.json",
+    JSON.stringify({ ...cfg, lock: false, imports }, null, 2),
+  );
+
+  // The registration. Which function is calling comes from the stack: the
+  // first frame under FUNCTIONS_DIR whose directory is a function.
+  const known = JSON.stringify(names);
+  const prelude = [
+    "// spectest-generated. Do not edit.",
+    "const g = globalThis as any;",
+    "g.__spectestHandlers = {};",
+    "const known = new Set(" + known + ");",
+    "const frame = new RegExp(\"" + reString(FUNCTIONS_DIR) + "/([^/]+)/\", \"g\");",
+    "// serve()'s onError is part of the contract: a project maps its thrown",
+    "// errors to responses there, and without it every throw is a bare 500.",
+    "g.__spectestRegister = (handler: unknown, onError?: unknown) => {",
+    "  if (typeof handler !== \"function\") throw new TypeError(\"spectest: serve() without a handler function\");",
+    "  const stack = new Error().stack ?? \"\";",
+    "  let name: string | null = null;",
+    "  for (const m of stack.matchAll(frame)) { if (known.has(m[1])) { name = m[1]; break; } }",
+    "  if (name === null) throw new Error(\"spectest: could not tell which function registered a handler; the call must come from under \" + JSON.stringify(\"" + FUNCTIONS_DIR + "\"));",
+    "  g.__spectestHandlers[name] = { handler, onError: typeof onError === \"function\" ? onError : null };",
+    "};",
+    "g.__spectestRealServe = Deno.serve.bind(Deno);",
+    "const listener = { finished: new Promise<void>(() => {}), addr: { transport: \"tcp\", hostname: \"0.0.0.0\", port: 8000 }, shutdown: async () => {}, ref() {}, unref() {} };",
+    "(Deno as any).serve = (a: any, b: any) => {",
+    "  const h = typeof a === \"function\" ? a : typeof b === \"function\" ? b : a?.handler ?? a?.fetch;",
+    "  const opts = typeof a === \"function\" ? b : a;",
+    "  g.__spectestRegister(h, opts?.onError);",
+    "  return listener;",
+    "};",
+    "",
+  ].join("\n");
+  await Deno.writeTextFile(SHARED_DIR + "/prelude.ts", prelude);
+
+  // std's legacy serve(handler, options): the same registration.
+  await Deno.writeTextFile(
+    SHARED_DIR + "/std-http-server.ts",
+    [
+      "// spectest-generated stand-in for https://deno.land/std/http/server.ts. Do not edit.",
+      "export function serve(handler: unknown, options?: { onError?: unknown }): Promise<void> {",
+      "  (globalThis as any).__spectestRegister(handler, options?.onError);",
+      "  return new Promise(() => {});",
+      "}",
+      "export type ConnInfo = { localAddr: Deno.Addr; remoteAddr: Deno.Addr };",
+      "export type Handler = (request: Request, connInfo: ConnInfo) => Response | Promise<Response>;",
+      "export type ServeInit = Record<string, unknown>;",
+      "",
+    ].join("\n"),
+  );
+
+  // The entry: the prelude first, then every function, then the router. A
+  // function written the declarative way (export default { fetch }) never
+  // calls serve, so its default export is picked up here.
+  const lines = ["// spectest-generated entry of the shared functions isolate. Do not edit.", "import \"./prelude.ts\";"];
+  const fnRel = relativePath(SHARED_DIR, FUNCTIONS_DIR);
+  names.forEach((n, i) => lines.push("import * as f" + i + " from " + JSON.stringify(fnRel + "/" + n + "/index.ts") + ";"));
+  lines.push("const mods: Record<string, any> = {");
+  names.forEach((n, i) => lines.push("  " + JSON.stringify(n) + ": f" + i + ","));
+  lines.push("};");
+  lines.push(
+    "const g = globalThis as any;",
+    "for (const [n, m] of Object.entries(mods)) {",
+    "  const d = m.default;",
+    "  if (!g.__spectestHandlers[n] && d && typeof d.fetch === \"function\") g.__spectestHandlers[n] = { handler: d.fetch.bind(d), onError: null };",
+    "}",
+    "const addr = { transport: \"tcp\", hostname: \"127.0.0.1\", port: 0 };",
+    "g.__spectestRealServe(async (req: Request) => {",
+    "  const name = new URL(req.url).pathname.split(\"/\")[1] ?? \"\";",
+    "  const h = g.__spectestHandlers[name];",
+    "  if (!h) return new Response(JSON.stringify({ msg: \"function \" + name + \" registered no handler\" }), { status: 500, headers: { \"content-type\": \"application/json\" } });",
+    "  try {",
+    "    return await h.handler(req, { remoteAddr: addr, localAddr: addr, completed: Promise.resolve() });",
+    "  } catch (e) {",
+    "    if (h.onError) return await h.onError(e);",
+    "    console.error(e);",
+    "    return new Response(\"Internal Server Error\", { status: 500 });",
+    "  }",
+    "});",
+    "",
+  );
+  await Deno.writeTextFile(SHARED_DIR + "/index.ts", lines.join("\n"));
+  return null;
+}
+
+/** The shared isolate (pooled by the runtime under SHARED_DIR), or null when
+ *  the functions run one isolate each — decided once, with the reason logged. */
+async function sharedWorker(): Promise<any | null> {
+  if (ISOLATION !== "shared") return null;
+  if (!sharedSpec) {
+    sharedSpec = (async () => {
+      const names = await functionNames();
+      let reason = names.length === 0 ? "no functions" : await sharedBlocker(names);
+      if (reason === null) reason = await writeShared(names);
+      if (reason === null) {
+        try {
+          await createShared();
+        } catch (e) {
+          reason = "the shared isolate failed to boot: " + String(e);
+        }
+      }
+      if (reason !== null) console.warn("spectest: functions run one isolate each — " + reason);
+      return { names, reason };
+    })();
+  }
+  const spec = await sharedSpec;
+  return spec.reason === null ? createShared() : null;
+}
+
+function createShared() {
+  return EdgeRuntime.userWorkers.create({
+    servicePath: SHARED_DIR,
+    // A cap on the one isolate that holds every function, not a reservation.
+    memoryLimitMb: 2048,
+    workerTimeoutMs: WORKER_TIMEOUT_MS,
+    // The supervisor counts CPU time over the worker's LIFETIME (soft limit:
+    // retire, hard limit: terminate and cancel in-flight requests with
+    // "request has been cancelled by supervisor"). One isolate serving every
+    // function for a day of tests spends what 51 short-lived ones never
+    // would, so its budget is the day itself. Per-function isolates keep the
+    // runtime's defaults.
+    cpuTimeSoftLimitMs: WORKER_TIMEOUT_MS,
+    cpuTimeHardLimitMs: WORKER_TIMEOUT_MS,
+    noModuleCache: false,
+    importMapPath: null,
+    envVars: Object.entries(Deno.env.toObject()),
+  });
+}
+
+/** Boot the functions now, without calling them: the shared isolate, or —
+ *  where it cannot stand in — every function's own. Loading a function
+ *  runs its module top level, which for a function is its serve()
+ *  registration, no business logic. Called once at environment setup,
+ *  before the warm snapshot, so the isolates are shared, clean pages of the
+ *  snapshot rather than a boot in every test that first touches a function. */
+async function warmAll(): Promise<{ mode: "shared" | "per-function"; warmed: string[]; failed: Record<string, string> }> {
+  const names = await functionNames();
+  if ((await sharedWorker()) !== null) return { mode: "shared", warmed: names, failed: {} };
+  // All at once: each boot is mostly module loading, and the isolates come
+  // up concurrently.
+  const results = await Promise.allSettled(names.map((name) => workerFor(name)));
+  const warmed: string[] = [];
+  const failed: Record<string, string> = {};
+  results.forEach((r, i) => {
+    if (r.status === "fulfilled") warmed.push(names[i]);
+    else failed[names[i]] = String(r.reason);
+  });
+  return { mode: "per-function", warmed: warmed.sort(), failed };
+}
+
 Deno.serve(async (req: Request) => {
   const { pathname } = new URL(req.url);
 
   // Ready probe — answered before any auth check, so bring-up never needs a
   // token, and never treated as a function name.
   if (pathname === "/_spectest/health") return new Response("ok");
+  // Setup-time warm-up (see warmAll); never treated as a function name.
+  if (pathname === "/_spectest/warm") return json(await warmAll());
 
   const name = pathname.split("/")[1] ?? "";
   if (name === "") return json({ msg: "missing function name in request" }, 400);
@@ -718,14 +1013,7 @@ Deno.serve(async (req: Request) => {
 
   const servicePath = FUNCTIONS_DIR + "/" + name;
   try {
-    const worker = await EdgeRuntime.userWorkers.create({
-      servicePath,
-      memoryLimitMb: 256,
-      workerTimeoutMs: 5 * 60 * 1000,
-      noModuleCache: false,
-      importMapPath: null,
-      envVars: Object.entries(Deno.env.toObject()),
-    });
+    const worker = (await sharedWorker()) ?? (await workerFor(name));
     return await worker.fetch(req);
   } catch (e) {
     // A missing directory lands here too, so say which function was asked
@@ -1416,7 +1704,7 @@ export function supabase(opts = {}) {
             }
             // ── functions (edge runtime) ────────────────────────────────────
             if (withFunctions) {
-                parts.functions = {
+                const functionsDef = {
                     // Built rather than pulled, so the functions' remote imports are
                     // fetched by the host builder and cached into the image — see
                     // `functionsDockerfile`.
@@ -1441,6 +1729,9 @@ export function supabase(opts = {}) {
                         JWT_SECRET: jwtSecret,
                         // Where the router looks for `<name>/`, inside the repo mount.
                         FUNCTIONS_DIR: fnServePath,
+                        // One isolate for all functions (default) or one each — see the
+                        // `functions` option and the router's shared-isolate notes.
+                        FUNCTIONS_ISOLATION: opts.functions?.isolation ?? "shared",
                         // The default a function inherits when the config says nothing:
                         // reject an unauthenticated call, as hosted Supabase does.
                         VERIFY_JWT: "true",
@@ -1472,7 +1763,30 @@ export function supabase(opts = {}) {
                         path: "/_spectest/health",
                         timeoutSecs: 120,
                     },
+                    // Boot every function's isolate before the warm snapshot is
+                    // taken (see warmAll in the router). Measured on a real project
+                    // (Harmony, 2026-08-28): a test that first touched a few
+                    // functions dirtied ~1 GB booting them — memory that then had to
+                    // be written into that test's snapshot diff and paid for by every
+                    // fork of it. Warm, the isolates are clean shared pages of the
+                    // snapshot and a test's diff is what its requests mutate.
+                    setup: async () => {
+                        const t0 = Date.now();
+                        const res = await fetch(`http://${g.key("functions")}:9000/_spectest/warm`);
+                        if (!res.ok) {
+                            console.warn(`supabase(): edge functions warm-up answered ${res.status}; functions boot on first call instead.`);
+                            return;
+                        }
+                        const { mode, warmed, failed } = (await res.json());
+                        const secs = ((Date.now() - t0) / 1000).toFixed(1);
+                        const how = mode === "shared" ? "in one isolate" : "one isolate each (see the functions service log for why)";
+                        console.log(`supabase(): warmed ${warmed.length} edge function${warmed.length === 1 ? "" : "s"} ${how} in ${secs}s${warmed.length ? ` (${warmed.join(", ")})` : ""}.`);
+                        for (const [name, err] of Object.entries(failed)) {
+                            console.warn(`supabase(): edge function "${name}" failed to boot at warm-up — it will be retried on first call: ${err}`);
+                        }
+                    },
                 };
+                parts.functions = functionsDef;
             }
             // ── kong (gateway / primary) — no explicit dependsOn: the group
             // expansion makes the primary depend on every member ──────────────

package/package.json

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

package/src/components/supabase.ts

@@ -235,6 +235,18 @@ export interface SupabaseOptions {
   storage?: boolean;
   /** Include Realtime (`<name>-realtime`). Default `true`. */
   realtime?: boolean;
+  /**
+   * Edge functions. `isolation` picks how they run on the edge runtime:
+   * `"shared"` (default) loads every function into **one** isolate, so a
+   * shared module graph (`_shared/`, npm packages) is loaded once rather than
+   * once per function — measured on a 51-function project as 230 MB against
+   * 3.6 GB. Hosted Supabase runs one isolate per function, and the one thing
+   * that differs is module-level state: a singleton in `_shared` is one
+   * object for all functions here, one per function there. `"per-function"`
+   * runs it the hosted way. Either way the runtime, the request each
+   * function sees and the per-function `verify_jwt` are the same.
+   */
+  functions?: { isolation?: "shared" | "per-function" };
 
   /**
    * Also serve the gateway over **HTTPS** at `https://<hostname>` via the
@@ -1043,12 +1055,307 @@ async function validJwt(token: string): Promise<boolean> {
   }
 }
 
+/** How the functions run: every function in one isolate (the default), or
+ *  one isolate per function as hosted Supabase does — see sharedWorker. */
+const ISOLATION = Deno.env.get("FUNCTIONS_ISOLATION") === "per-function" ? "per-function" : "shared";
+/** Where the generated entry of the shared isolate lives — outside the repo
+ *  mount, which is read-only and the user's checkout, and NOT under /tmp:
+ *  the runtime gives its workers an in-memory /tmp, so a file the main
+ *  worker writes there does not exist for the user worker's bootstrap
+ *  ("could not find an appropriate entrypoint"). */
+const SHARED_DIR = "/home/deno/spectest-functions";
+const WORKER_TIMEOUT_MS = 24 * 60 * 60 * 1000;
+
+/** One isolate per function, reused across requests (the runtime pools by
+ *  servicePath). The idle timeout is a day, not upstream's five minutes: a
+ *  test environment is a snapshot lineage whose forks inherit these
+ *  isolates, and an isolate reaped for idleness is rebooted by the next
+ *  test that calls the function — a boot's worth of dirtied memory in that
+ *  test's own snapshot diff. */
+function workerFor(name: string) {
+  return EdgeRuntime.userWorkers.create({
+    servicePath: FUNCTIONS_DIR + "/" + name,
+    memoryLimitMb: 256,
+    workerTimeoutMs: WORKER_TIMEOUT_MS,
+    noModuleCache: false,
+    importMapPath: null,
+    envVars: Object.entries(Deno.env.toObject()),
+  });
+}
+
+async function exists(path: string): Promise<boolean> {
+  try {
+    await Deno.stat(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** The function directories: every child of FUNCTIONS_DIR with an index.ts,
+ *  minus the conventional private ones. */
+async function functionNames(): Promise<string[]> {
+  const names: string[] = [];
+  for await (const entry of Deno.readDir(FUNCTIONS_DIR)) {
+    if (!entry.isDirectory || entry.name.startsWith("_") || entry.name.startsWith(".")) continue;
+    if (await exists(FUNCTIONS_DIR + "/" + entry.name + "/index.ts")) names.push(entry.name);
+  }
+  return names.sort();
+}
+
+/** Every "https://deno.land/std@…/http/server.ts" a source under the
+ *  functions directory imports — the legacy serve() each of them has to be
+ *  redirected to the shim in the shared isolate. */
+async function stdServerUrls(dir: string, out: Set<string>): Promise<void> {
+  for await (const e of Deno.readDir(dir)) {
+    const p = dir + "/" + e.name;
+    if (e.isDirectory) {
+      if (e.name !== "node_modules" && !e.name.startsWith(".")) await stdServerUrls(p, out);
+      continue;
+    }
+    if (!/\.(ts|tsx|js|mjs|jsx)$/.test(e.name)) continue;
+    const src = await Deno.readTextFile(p);
+    for (const m of src.matchAll(/https:\/\/deno\.land\/std@[0-9.]+\/http\/server\.ts/g)) out.add(m[0]);
+  }
+}
+
+// ── The shared isolate ────────────────────────────────────────────────────
+//
+// The runtime's own model is one isolate per function, each loading its own
+// copy of the module graph. On a project with dozens of functions sharing a
+// \`_shared/\` tree that is dozens of copies of the same graph — measured at
+// ~90 MB and ~1 s per function, against 18 MB for an empty isolate — and in
+// an 8 GB guest that memory comes straight out of the page cache every test
+// needs. So by default every function is loaded into ONE user worker: a
+// generated entry module imports each function's index.ts in turn, a prelude
+// (imported first, so it runs first) has replaced \`Deno.serve\` with a
+// registration that records the handler under the function whose module is
+// calling, the std \`serve()\` the older functions use is redirected to the
+// same registration by an import map, and the worker's own server routes a
+// request to the handler of the function its path names. The runtime, the
+// request a function receives and the per-function JWT check are unchanged;
+// what differs from hosted Supabase is that module-level state is one
+// object for every function rather than one per function.
+//
+// It stands in only where it can be exact. A function with its own
+// deno.json / import map (per-function resolution the one config cannot
+// express), a functions/deno.jsonc (comments; not merged) or a config that
+// names an importMap keep the per-function isolates, and so does a shared
+// isolate that fails to boot — with the reason in the log, since a boot
+// failure names the module at fault.
+
+interface SharedSpec {
+  names: string[];
+  reason: string | null;
+}
+let sharedSpec: Promise<SharedSpec> | null = null;
+
+/** Why the shared isolate cannot stand in for per-function ones, or null. */
+async function sharedBlocker(names: string[]): Promise<string | null> {
+  for (const n of names) {
+    for (const f of ["deno.json", "deno.jsonc", "import_map.json"]) {
+      if (await exists(FUNCTIONS_DIR + "/" + n + "/" + f)) return "function \"" + n + "\" has its own " + f;
+    }
+  }
+  if (await exists(FUNCTIONS_DIR + "/deno.jsonc")) return "functions/deno.jsonc is not merged (comments)";
+  return null;
+}
+
+/** POSIX-relative path from directory \`from\` to \`to\`. The entry imports the
+ *  functions relatively: an absolute file specifier is refused by the
+ *  runtime's module bundler ("Module not found"), a relative one resolves. */
+function relativePath(from: string, to: string): string {
+  const a = from.split("/").filter(Boolean);
+  const b = to.split("/").filter(Boolean);
+  let i = 0;
+  while (i < a.length && i < b.length && a[i] === b[i]) i++;
+  const up = a.slice(i).map(() => "..");
+  const rel = [...up, ...b.slice(i)].join("/");
+  return rel.startsWith(".") ? rel : "./" + rel;
+}
+
+function reString(s: string): string {
+  return s.replace(/[.*+?^$()|[\]\\\/{}]/g, "\\$&");
+}
+
+/** Write SHARED_DIR: the entry, the prelude, the std shim and the config. */
+async function writeShared(names: string[]): Promise<string | null> {
+  await Deno.mkdir(SHARED_DIR, { recursive: true });
+
+  // Config: the project's functions/deno.json (its imports are what every
+  // function resolves against) plus the std shim redirections.
+  let cfg: Record<string, unknown> = {};
+  if (await exists(FUNCTIONS_DIR + "/deno.json")) {
+    try {
+      cfg = JSON.parse(await Deno.readTextFile(FUNCTIONS_DIR + "/deno.json"));
+    } catch (e) {
+      return "functions/deno.json could not be parsed: " + String(e);
+    }
+    if (typeof cfg.importMap === "string") return "functions/deno.json names an importMap";
+  }
+  const urls = new Set<string>();
+  await stdServerUrls(FUNCTIONS_DIR, urls);
+  const imports: Record<string, string> = { ...((cfg.imports as Record<string, string>) ?? {}) };
+  for (const u of urls) imports[u] = "./std-http-server.ts";
+  await Deno.writeTextFile(
+    SHARED_DIR + "/deno.json",
+    JSON.stringify({ ...cfg, lock: false, imports }, null, 2),
+  );
+
+  // The registration. Which function is calling comes from the stack: the
+  // first frame under FUNCTIONS_DIR whose directory is a function.
+  const known = JSON.stringify(names);
+  const prelude = [
+    "// spectest-generated. Do not edit.",
+    "const g = globalThis as any;",
+    "g.__spectestHandlers = {};",
+    "const known = new Set(" + known + ");",
+    "const frame = new RegExp(\"" + reString(FUNCTIONS_DIR) + "/([^/]+)/\", \"g\");",
+    "// serve()'s onError is part of the contract: a project maps its thrown",
+    "// errors to responses there, and without it every throw is a bare 500.",
+    "g.__spectestRegister = (handler: unknown, onError?: unknown) => {",
+    "  if (typeof handler !== \"function\") throw new TypeError(\"spectest: serve() without a handler function\");",
+    "  const stack = new Error().stack ?? \"\";",
+    "  let name: string | null = null;",
+    "  for (const m of stack.matchAll(frame)) { if (known.has(m[1])) { name = m[1]; break; } }",
+    "  if (name === null) throw new Error(\"spectest: could not tell which function registered a handler; the call must come from under \" + JSON.stringify(\"" + FUNCTIONS_DIR + "\"));",
+    "  g.__spectestHandlers[name] = { handler, onError: typeof onError === \"function\" ? onError : null };",
+    "};",
+    "g.__spectestRealServe = Deno.serve.bind(Deno);",
+    "const listener = { finished: new Promise<void>(() => {}), addr: { transport: \"tcp\", hostname: \"0.0.0.0\", port: 8000 }, shutdown: async () => {}, ref() {}, unref() {} };",
+    "(Deno as any).serve = (a: any, b: any) => {",
+    "  const h = typeof a === \"function\" ? a : typeof b === \"function\" ? b : a?.handler ?? a?.fetch;",
+    "  const opts = typeof a === \"function\" ? b : a;",
+    "  g.__spectestRegister(h, opts?.onError);",
+    "  return listener;",
+    "};",
+    "",
+  ].join("\n");
+  await Deno.writeTextFile(SHARED_DIR + "/prelude.ts", prelude);
+
+  // std's legacy serve(handler, options): the same registration.
+  await Deno.writeTextFile(
+    SHARED_DIR + "/std-http-server.ts",
+    [
+      "// spectest-generated stand-in for https://deno.land/std/http/server.ts. Do not edit.",
+      "export function serve(handler: unknown, options?: { onError?: unknown }): Promise<void> {",
+      "  (globalThis as any).__spectestRegister(handler, options?.onError);",
+      "  return new Promise(() => {});",
+      "}",
+      "export type ConnInfo = { localAddr: Deno.Addr; remoteAddr: Deno.Addr };",
+      "export type Handler = (request: Request, connInfo: ConnInfo) => Response | Promise<Response>;",
+      "export type ServeInit = Record<string, unknown>;",
+      "",
+    ].join("\n"),
+  );
+
+  // The entry: the prelude first, then every function, then the router. A
+  // function written the declarative way (export default { fetch }) never
+  // calls serve, so its default export is picked up here.
+  const lines = ["// spectest-generated entry of the shared functions isolate. Do not edit.", "import \"./prelude.ts\";"];
+  const fnRel = relativePath(SHARED_DIR, FUNCTIONS_DIR);
+  names.forEach((n, i) => lines.push("import * as f" + i + " from " + JSON.stringify(fnRel + "/" + n + "/index.ts") + ";"));
+  lines.push("const mods: Record<string, any> = {");
+  names.forEach((n, i) => lines.push("  " + JSON.stringify(n) + ": f" + i + ","));
+  lines.push("};");
+  lines.push(
+    "const g = globalThis as any;",
+    "for (const [n, m] of Object.entries(mods)) {",
+    "  const d = m.default;",
+    "  if (!g.__spectestHandlers[n] && d && typeof d.fetch === \"function\") g.__spectestHandlers[n] = { handler: d.fetch.bind(d), onError: null };",
+    "}",
+    "const addr = { transport: \"tcp\", hostname: \"127.0.0.1\", port: 0 };",
+    "g.__spectestRealServe(async (req: Request) => {",
+    "  const name = new URL(req.url).pathname.split(\"/\")[1] ?? \"\";",
+    "  const h = g.__spectestHandlers[name];",
+    "  if (!h) return new Response(JSON.stringify({ msg: \"function \" + name + \" registered no handler\" }), { status: 500, headers: { \"content-type\": \"application/json\" } });",
+    "  try {",
+    "    return await h.handler(req, { remoteAddr: addr, localAddr: addr, completed: Promise.resolve() });",
+    "  } catch (e) {",
+    "    if (h.onError) return await h.onError(e);",
+    "    console.error(e);",
+    "    return new Response(\"Internal Server Error\", { status: 500 });",
+    "  }",
+    "});",
+    "",
+  );
+  await Deno.writeTextFile(SHARED_DIR + "/index.ts", lines.join("\n"));
+  return null;
+}
+
+/** The shared isolate (pooled by the runtime under SHARED_DIR), or null when
+ *  the functions run one isolate each — decided once, with the reason logged. */
+async function sharedWorker(): Promise<any | null> {
+  if (ISOLATION !== "shared") return null;
+  if (!sharedSpec) {
+    sharedSpec = (async () => {
+      const names = await functionNames();
+      let reason = names.length === 0 ? "no functions" : await sharedBlocker(names);
+      if (reason === null) reason = await writeShared(names);
+      if (reason === null) {
+        try {
+          await createShared();
+        } catch (e) {
+          reason = "the shared isolate failed to boot: " + String(e);
+        }
+      }
+      if (reason !== null) console.warn("spectest: functions run one isolate each — " + reason);
+      return { names, reason };
+    })();
+  }
+  const spec = await sharedSpec;
+  return spec.reason === null ? createShared() : null;
+}
+
+function createShared() {
+  return EdgeRuntime.userWorkers.create({
+    servicePath: SHARED_DIR,
+    // A cap on the one isolate that holds every function, not a reservation.
+    memoryLimitMb: 2048,
+    workerTimeoutMs: WORKER_TIMEOUT_MS,
+    // The supervisor counts CPU time over the worker's LIFETIME (soft limit:
+    // retire, hard limit: terminate and cancel in-flight requests with
+    // "request has been cancelled by supervisor"). One isolate serving every
+    // function for a day of tests spends what 51 short-lived ones never
+    // would, so its budget is the day itself. Per-function isolates keep the
+    // runtime's defaults.
+    cpuTimeSoftLimitMs: WORKER_TIMEOUT_MS,
+    cpuTimeHardLimitMs: WORKER_TIMEOUT_MS,
+    noModuleCache: false,
+    importMapPath: null,
+    envVars: Object.entries(Deno.env.toObject()),
+  });
+}
+
+/** Boot the functions now, without calling them: the shared isolate, or —
+ *  where it cannot stand in — every function's own. Loading a function
+ *  runs its module top level, which for a function is its serve()
+ *  registration, no business logic. Called once at environment setup,
+ *  before the warm snapshot, so the isolates are shared, clean pages of the
+ *  snapshot rather than a boot in every test that first touches a function. */
+async function warmAll(): Promise<{ mode: "shared" | "per-function"; warmed: string[]; failed: Record<string, string> }> {
+  const names = await functionNames();
+  if ((await sharedWorker()) !== null) return { mode: "shared", warmed: names, failed: {} };
+  // All at once: each boot is mostly module loading, and the isolates come
+  // up concurrently.
+  const results = await Promise.allSettled(names.map((name) => workerFor(name)));
+  const warmed: string[] = [];
+  const failed: Record<string, string> = {};
+  results.forEach((r, i) => {
+    if (r.status === "fulfilled") warmed.push(names[i]);
+    else failed[names[i]] = String(r.reason);
+  });
+  return { mode: "per-function", warmed: warmed.sort(), failed };
+}
+
 Deno.serve(async (req: Request) => {
   const { pathname } = new URL(req.url);
 
   // Ready probe — answered before any auth check, so bring-up never needs a
   // token, and never treated as a function name.
   if (pathname === "/_spectest/health") return new Response("ok");
+  // Setup-time warm-up (see warmAll); never treated as a function name.
+  if (pathname === "/_spectest/warm") return json(await warmAll());
 
   const name = pathname.split("/")[1] ?? "";
   if (name === "") return json({ msg: "missing function name in request" }, 400);
@@ -1063,14 +1370,7 @@ Deno.serve(async (req: Request) => {
 
   const servicePath = FUNCTIONS_DIR + "/" + name;
   try {
-    const worker = await EdgeRuntime.userWorkers.create({
-      servicePath,
-      memoryLimitMb: 256,
-      workerTimeoutMs: 5 * 60 * 1000,
-      noModuleCache: false,
-      importMapPath: null,
-      envVars: Object.entries(Deno.env.toObject()),
-    });
+    const worker = (await sharedWorker()) ?? (await workerFor(name));
     return await worker.fetch(req);
   } catch (e) {
     // A missing directory lands here too, so say which function was asked
@@ -1917,7 +2217,7 @@ export function supabase(opts: SupabaseOptions = {}): SupabaseStack {
 
       // ── functions (edge runtime) ────────────────────────────────────
       if (withFunctions) {
-        parts.functions = {
+        const functionsDef: ServiceDefinition = {
           // Built rather than pulled, so the functions' remote imports are
           // fetched by the host builder and cached into the image — see
           // `functionsDockerfile`.
@@ -1942,6 +2242,9 @@ export function supabase(opts: SupabaseOptions = {}): SupabaseStack {
             JWT_SECRET: jwtSecret,
             // Where the router looks for `<name>/`, inside the repo mount.
             FUNCTIONS_DIR: fnServePath,
+            // One isolate for all functions (default) or one each — see the
+            // `functions` option and the router's shared-isolate notes.
+            FUNCTIONS_ISOLATION: opts.functions?.isolation ?? "shared",
             // The default a function inherits when the config says nothing:
             // reject an unauthenticated call, as hosted Supabase does.
             VERIFY_JWT: "true",
@@ -1976,7 +2279,34 @@ export function supabase(opts: SupabaseOptions = {}): SupabaseStack {
             path: "/_spectest/health",
             timeoutSecs: 120,
           },
+          // Boot every function's isolate before the warm snapshot is
+          // taken (see warmAll in the router). Measured on a real project
+          // (Harmony, 2026-08-28): a test that first touched a few
+          // functions dirtied ~1 GB booting them — memory that then had to
+          // be written into that test's snapshot diff and paid for by every
+          // fork of it. Warm, the isolates are clean shared pages of the
+          // snapshot and a test's diff is what its requests mutate.
+          setup: async () => {
+            const t0 = Date.now();
+            const res = await fetch(`http://${g.key("functions")}:9000/_spectest/warm`);
+            if (!res.ok) {
+              console.warn(`supabase(): edge functions warm-up answered ${res.status}; functions boot on first call instead.`);
+              return;
+            }
+            const { mode, warmed, failed } = (await res.json()) as {
+              mode: "shared" | "per-function";
+              warmed: string[];
+              failed: Record<string, string>;
+            };
+            const secs = ((Date.now() - t0) / 1000).toFixed(1);
+            const how = mode === "shared" ? "in one isolate" : "one isolate each (see the functions service log for why)";
+            console.log(`supabase(): warmed ${warmed.length} edge function${warmed.length === 1 ? "" : "s"} ${how} in ${secs}s${warmed.length ? ` (${warmed.join(", ")})` : ""}.`);
+            for (const [name, err] of Object.entries(failed)) {
+              console.warn(`supabase(): edge function "${name}" failed to boot at warm-up — it will be retried on first call: ${err}`);
+            }
+          },
         };
+        parts.functions = functionsDef;
       }
 
       // ── kong (gateway / primary) — no explicit dependsOn: the group