@ultimat3/testing 23.0.0 → 25.0.0

package/src/preload.ts

@@ -12,8 +12,7 @@ import { registerFrameworkFixtures } from './framework-fixtures';
 import './matchers';
 import { installAppJsxLoader } from './app-jsx-loader';
 import { onFileBoundary } from './file-boundary';
-import { disposeLiveIslands } from './fixture-island';
-import { releasePluginsAfterIsolatedFile } from './isolated-plugins';
+import { ISOLATED_ENV, releasePluginsAfterIsolatedFile } from './isolated-plugins';
 import { installPerTestReset } from './per-test-reset';
 import { installRegistryLeakGuard } from './registry-leak-guard';
 import { sealNetwork } from './sealed-network';
@@ -44,11 +43,6 @@ Bun.env['ULTIMATE_TEST_SLOT_HELD'] ??= '1';
 // fails a later file in another package, for a reason nothing in that file explains.
 installRegistryLeakGuard();
 
-// A worker runs many files in one global unless the repo opted into `--isolate` (22.7): a mount a
-// file never disposed is disposed between files, and `file-boundary.ts` then puts `globalThis`
-// back to what the first file saw.
-onFileBoundary(disposeLiveIslands);
-
 // And per TEST: the jobs event bus stores what it is handed, so one test's published answer
 // resumed the next test's waiting run (`per-test-reset.ts`).
 installPerTestReset();
@@ -56,7 +50,7 @@ installPerTestReset();
 // A shared worker only (an isolated file is a fresh registry anyway): the app's
 // `defineApi({ pathStyle })` evaluates once per worker, in whichever file first imports it, and
 // must not be refused because an EARLIER file derived action paths under the default style.
-if (Bun.env['ULTIMATE_TEST_ISOLATED'] !== '1') {
+if (Bun.env[ISOLATED_ENV] !== '1') {
   const { forgetHandedOutActionPaths } = await import('@ultimat3/action');
   onFileBoundary(forgetHandedOutActionPaths);
 }

package/src/quiet-logs.ts

@@ -11,7 +11,7 @@
 // line collected nothing and failed for an environment variable. The level is therefore pinned at
 // `info` for the one moment core loads, and what the author named decides what is PRINTED.
 //
-// A test that asserts on log output hands `createLogger({ level, writer })` its own writer, or
+// A test that asserts on log output hands `structuredLogger({ level, writer })` its own writer, or
 // installs its own `setLogSink` and restores the previous one. Never `process.stdout`.
 
 import type { LogLevel } from '@ultimat3/core';

package/src/registry-leak-error.ts

@@ -0,0 +1,81 @@
+// Single responsibility: `X_TEST_REGISTRY_LEAK`'s message — which file left which cache tags and
+// tiers registered, the isolating lines to paste, and the `bun test` re-run. The CODE is declared
+// in `errors.ts`, the package's registry, which re-exports this class; the shape it reports is
+// `registry-leak-guard.ts`'s. Split from `errors.ts` at the 500-line ceiling.
+
+import { isFixShellSafe, renderCauseValue, renderFixLiteral, UltimateError } from '@ultimat3/core';
+// Type-only, so the cycle with the guard that throws it is erased at build.
+import type { RegistryLeak } from './registry-leak-guard';
+
+/**
+ * Every value in this message is uncontrolled: the path arrives from `Bun.plugin`'s `onLoad`, and
+ * the names are whatever the app under test passed to `declareTags()` / `registerTier()`. So the
+ * sentence renders them (bounded, never throwing while describing a leak) and the command quotes
+ * them (a fix has to parse after a path with a space or a quote in it lands in the middle of it).
+ */
+const describeLeak = (leak: RegistryLeak): string => {
+  const left = [
+    ...(leak.tags.length > 0 ? [`cache tags declared ${renderCauseValue(leak.tags)}`] : []),
+    ...(leak.tiers.length > 0 ? [`cache tiers registered ${renderCauseValue(leak.tiers)}`] : []),
+  ];
+  return `${renderCauseValue(leak.file)} left ${left.join(' and ')} after its last test`;
+};
+
+/** The placeholder is the cause's own sentence: it already names every file, in order. */
+const FILE_PLACEHOLDER = '<the file the cause names>';
+
+/**
+ * Inside double quotes `$`, a backtick and `!` are still live, and `renderFixLiteral` answers double
+ * quotes — so a path carrying one becomes the quoted placeholder in the `bun test` command. Any other
+ * path stays the JSON literal: an ordinary path, or one with a quote JSON escapes, still runs.
+ */
+const DOUBLE_QUOTE_LIVE = /[$`!]/;
+
+const rerunArg = (file: string): string =>
+  isFixShellSafe(file) || !DOUBLE_QUOTE_LIVE.test(file)
+    ? renderFixLiteral(file, FILE_PLACEHOLDER)
+    : `'${FILE_PLACEHOLDER}'`;
+
+/** Every leaked file as `bun test` arguments — one screen, so the fix-shell-arg guard can see it. */
+const rerunFileArgs = (leaks: readonly RegistryLeak[]): string =>
+  leaks.map((leak) => rerunArg(leak.file)).join(' ');
+
+/**
+ * The edit, spelled as the lines to paste — the imports included, since neither call is global.
+ *
+ * Both repairs isolate; neither resets. `afterAll(resetTiers)` was the first spelling of the tier
+ * half and it is the bug wearing the fix's clothes: it drops the tiers, the revalidator and both
+ * logs a NEIGHBOUR registered, and the guard reports additions only, so the damage lands on an
+ * innocent file with nothing pointing back here. An error whose instruction causes the next defect
+ * is worse than no instruction.
+ */
+const repairFor = (leak: RegistryLeak): string => {
+  const imports: string[] = [];
+  const calls: string[] = [];
+  if (leak.tags.length > 0) {
+    imports.push('isolateDeclaredTags');
+    calls.push('const restoreTags = isolateDeclaredTags(); afterAll(restoreTags);');
+  }
+  if (leak.tiers.length > 0) {
+    imports.push('isolateTiers');
+    calls.push('const restoreTiers = isolateTiers(); afterAll(restoreTiers);');
+  }
+  const file = renderFixLiteral(leak.file, FILE_PLACEHOLDER);
+  return `in ${file} add: import { ${imports.join(', ')} } from '@ultimat3/cache'; ${calls.join(' ')}`;
+};
+
+/**
+ * One error for every leaker in the run, not one per file: the run has already finished by the
+ * time the last file can be judged, and two throws would report the second as an unhandled one.
+ * The trailing command reproduces the failure on its own — the guard judges each file against its
+ * own baseline, so one leaking file fails a one-file run exactly as it failed the whole suite.
+ */
+export class RegistryLeakError extends UltimateError {
+  constructor(input: { readonly leaks: readonly RegistryLeak[] }) {
+    super({
+      code: 'X_TEST_REGISTRY_LEAK',
+      cause: input.leaks.map(describeLeak).join('; '),
+      fix: `${input.leaks.map(repairFor).join('; ')} — then re-run: bun test ${rerunFileArgs(input.leaks)}`,
+    });
+  }
+}

package/src/registry-leak-guard.ts

@@ -7,7 +7,7 @@ import { afterAll } from 'bun:test';
 import { knownTags, registeredTiers } from '@ultimat3/cache';
 import { isAppRoot } from './app-jsx-loader';
 import { RegistryLeakError } from './errors';
-import { runFileBoundary } from './file-boundary';
+import { runBoundaryHooks, runFileBoundary } from './file-boundary';
 import type { ProcessRegistrySnapshot } from './registry-snapshot';
 import {
   captureProcessRegistries,
@@ -32,7 +32,7 @@ import {
  * "Idiomatic to leave filled" says nothing about a file that calls `clear*()`/`reset*()` and takes
  * a module-scope declaration from every file after it — a module evaluates once per process, so the
  * next file's own `import` is a cache hit that declares nothing. That is what `registry-snapshot.ts`
- * repairs, and it repairs FOUR registries out of the set that has one:
+ * repairs, and it repairs SIX registries out of the set that has one:
  *
  *   | registry | reset export | owner | in the snapshot? |
  *   |---|---|---|---|
@@ -41,8 +41,9 @@ import {
  *   | routes | `clearRoutes` | `@ultimat3/render` | **no** |
  *   | jobs | `resetJobs` | `@ultimat3/jobs` | **no** |
  *   | tasks | `restoreTasks` | `@ultimat3/jobs` | yes (22.7) |
- *   | actions | `resetRegistry` | `@ultimat3/action` | **no** |
- *   | queries | `resetRegistry` | `@ultimat3/query` | **no** |
+ *   | measurement actor | `resetMeasurementActor` | `@ultimat3/core` | yes |
+ *   | actions | `resetActions` | `@ultimat3/action` | **no** |
+ *   | queries | `resetQueries` | `@ultimat3/query` | **no** |
  *   | models / prompts / agents | `resetModels` / `resetPrompts` / `resetAgents` | `@ultimat3/ai` | **no** |
  *   | mails | `resetMails` | `@ultimat3/mail` | **no** |
  *   | entities | `clearRegistry` | `@ultimat3/entity` | no, by decision — `registry-isolation.ts` |
@@ -219,6 +220,8 @@ export function installRegistryLeakGuard(): void {
   });
 
   afterAll(() => {
+    // The run's LAST file has no boundary after it: its undisposed island mounts end here.
+    runBoundaryHooks();
     close();
     if (leaks.length > 0) throw new RegistryLeakError({ leaks });
   });

package/src/registry-snapshot.ts

@@ -3,11 +3,17 @@
 // module declares at MODULE scope evaluates once per `bun test` process — a neighbour's clear is
 // permanent and there is no second evaluation left to redo it.
 //
-// FOUR registries, out of roughly nine that publish a `clear*`/`reset*`. The missing ones and what
+// SIX registries, out of roughly nine that publish a `clear*`/`reset*`. The missing ones and what
 // each still needs are tabulated in `registry-leak-guard.ts` beside `RegistrySample` — every one of
 // them needs a RESTORE in its owning package first, the way `restorePermissions` / `restoreRoles`
 // were added to `@ultimat3/policy` for the two rows below.
 
+import type { MeasurementActorFactory } from '@ultimat3/core';
+import {
+  declaredMeasurementActor,
+  defineMeasurementActor,
+  resetMeasurementActor,
+} from '@ultimat3/core';
 import type { Catalog, Locale, LocaleConfig } from '@ultimat3/i18n';
 import {
   catalogDeclarationCount,
@@ -24,6 +30,7 @@ import { registeredTasks, restoreTasks } from '@ultimat3/jobs';
 import type { RoleMap } from '@ultimat3/policy';
 import {
   knownPermissions,
+  permissionDeclarationSites,
   restorePermissions,
   restoreRoles,
   roleDeclarationSites,
@@ -39,6 +46,8 @@ export interface ProcessRegistrySnapshot {
   readonly locales: LocaleConfig;
   readonly catalogs: readonly (readonly [Locale, Catalog])[];
   readonly permissions: readonly string[];
+  /** Restored WITH the names: a site-less permission is one the policy step can never judge. */
+  readonly permissionSites: Readonly<Record<string, readonly string[]>>;
   readonly roles: RoleMap;
   /** Kept beside the map: restoring through `defineRoles()` would rewrite every site. */
   readonly roleSites: Readonly<Record<string, string>>;
@@ -50,6 +59,13 @@ export interface ProcessRegistrySnapshot {
   readonly tasks: readonly TaskHandle[];
   /** `defineCatalogs()` calls so far — see `@ultimat3/i18n`'s `catalogDeclarationCount`. */
   readonly catalogDeclarations: number;
+  /**
+   * `defineMeasurementActor()`'s factory, `undefined` for core's default. An `app.config.ts`
+   * declares it at module scope, so a test body that imported a tracked app's config
+   * (`buildIslands(examples/dummy)`) made every later file's `x build` measure as that app's
+   * member — and `prerender-actor.test.ts`'s policy-guarded load was denied X_FORBIDDEN.
+   */
+  readonly measurementActor: MeasurementActorFactory | undefined;
 }
 
 export function captureProcessRegistries(): ProcessRegistrySnapshot {
@@ -57,10 +73,12 @@ export function captureProcessRegistries(): ProcessRegistrySnapshot {
     locales: localeConfig(),
     catalogs: registeredLocales().map((locale) => [locale, catalogFor(locale)] as const),
     permissions: knownPermissions(),
+    permissionSites: permissionDeclarationSites(),
     roles: roleDefinitions(),
     roleSites: roleDeclarationSites(),
     tasks: registeredTasks(),
     catalogDeclarations: catalogDeclarationCount(),
+    measurementActor: declaredMeasurementActor(),
   };
 }
 
@@ -74,9 +92,11 @@ export function restoreProcessRegistries(snapshot: ProcessRegistrySnapshot): voi
   // a partial call can never widen `supported` back.
   configureLocales(snapshot.locales);
   restoreCatalogs(snapshot.catalogs);
-  restorePermissions(snapshot.permissions);
+  restorePermissions(snapshot.permissions, snapshot.permissionSites);
   restoreRoles(snapshot.roles, snapshot.roleSites);
   restoreTasks(snapshot.tasks);
+  if (snapshot.measurementActor === undefined) resetMeasurementActor();
+  else defineMeasurementActor(snapshot.measurementActor);
 }
 
 /**
@@ -138,9 +158,28 @@ export function mergeSnapshots(
     locales: newer.locales,
     catalogs: [...catalogs],
     permissions: [...new Set([...older.permissions, ...newer.permissions])],
+    permissionSites: mergeSites(older.permissionSites, newer.permissionSites),
     roles: { ...older.roles, ...newer.roles },
     roleSites: { ...older.roleSites, ...newer.roleSites },
     tasks: [...tasks.values()],
     catalogDeclarations: Math.max(older.catalogDeclarations, newer.catalogDeclarations),
+    // Last declaration wins, as `defineMeasurementActor` itself has it; "none" never erases one.
+    measurementActor: newer.measurementActor ?? older.measurementActor,
   };
 }
+
+/** Per name, every module either snapshot saw declare it — the union the names themselves are. */
+function mergeSites(
+  older: Readonly<Record<string, readonly string[]>>,
+  newer: Readonly<Record<string, readonly string[]>>,
+): Readonly<Record<string, readonly string[]>> {
+  const merged = new Map<string, Set<string>>();
+  for (const side of [older, newer]) {
+    for (const [name, at] of Object.entries(side)) {
+      const into = merged.get(name) ?? new Set<string>();
+      for (const site of at) into.add(site);
+      merged.set(name, into);
+    }
+  }
+  return Object.fromEntries([...merged].map(([name, at]) => [name, [...at]]));
+}

package/src/render-view.ts

@@ -3,7 +3,7 @@
 // them. No browser, no server, no cast: a test asserts on markup and on visible text.
 
 import type { Actor } from '@ultimat3/core';
-import { assert, createContext, runWithContext } from '@ultimat3/core';
+import { assert, ctxOf, runWithContext } from '@ultimat3/core';
 import type { IslandDirective, RouteConfig, RouteParams } from '@ultimat3/render';
 
 /** What a component rendered. */
@@ -101,7 +101,7 @@ export async function renderRoute<TData>(
   );
   const url = request.url ?? DEFAULT_URL;
   const ctx = { params: request.params ?? {}, url };
-  const islands = render.createIslandCollector({ file: url, hydrate: config.hydrate });
+  const islands = render.islandCollector({ file: url, hydrate: config.hydrate });
 
   const run = async (): Promise<RenderedRoute<TData>> => {
     const data = await render.routeDataFor(config, ctx);
@@ -114,5 +114,5 @@ export async function renderRoute<TData>(
   };
 
   if (request.actor === undefined) return run();
-  return runWithContext(createContext({ actor: request.actor }), run);
+  return runWithContext(ctxOf({ actor: request.actor }), run);
 }

package/src/sealed-network.ts

@@ -1,9 +1,11 @@
 // Sealed network. Any egress a test did not explicitly mock or allow fails the test with the URL
 // and the line that fixes it. A test that quietly reaches the internet is a test that fails in CI
-// for reasons nobody can reproduce — so the default is "nothing gets out".
+// for reasons nobody can reproduce — so the default is "nothing gets out". Three dials are sealed:
+// `fetch` here, `WebSocket` and `Bun.connect` through `sealed-sockets.ts`, all behind one gate.
 
-import { isSelfOrigin } from '@ultimat3/core';
+import { classifyAddress, isSelfOrigin } from '@ultimat3/core';
 import { NetworkOfflineError, NetworkRaceError, NetworkSealedError } from './errors';
+import { installSocketSeal } from './sealed-sockets';
 
 export type FetchLike = typeof globalThis.fetch;
 
@@ -24,6 +26,8 @@ interface SealState {
   readonly mocks: MockRoute[];
   readonly seen: string[];
   original: FetchLike | undefined;
+  /** `installSocketSeal`'s undo, held beside `original` so one unseal restores all three dials. */
+  restoreSockets: (() => void) | undefined;
   network: NetworkState;
 }
 
@@ -32,11 +36,16 @@ const state: SealState = {
   mocks: [],
   seen: [],
   original: undefined,
+  restoreSockets: undefined,
   network: 'online',
 };
 
 const matches = (route: MockRoute, url: string): boolean => {
-  if (route.match instanceof RegExp) return route.match.test(url);
+  if (route.match instanceof RegExp) {
+    // A `g`/`y` pattern's `test` resumes at `lastIndex`: without the reset, every other call missed.
+    route.match.lastIndex = 0;
+    return route.match.test(url);
+  }
   if (route.match.endsWith('*')) return url.startsWith(route.match.slice(0, -1));
   return route.match === url;
 };
@@ -53,10 +62,44 @@ const methodOf = (input: RequestInfo | URL, init: RequestInit | undefined): stri
   return 'GET';
 };
 
-/** Replace global fetch. Idempotent: sealing twice keeps the one original around. */
+/**
+ * A raw socket to THIS machine is not egress, whichever port: it is how a test reaches the
+ * scripted server it `Bun.listen`ed and the compose services the live suites run against, none of
+ * which announce through `markListening`. What fails unreproducibly in CI is the internet, and a
+ * loopback dial with nothing behind it fails the same way on every machine.
+ */
+const isThisMachine = (hostname: string): boolean => {
+  if (hostname.toLowerCase() === 'localhost') return true;
+  const kind = classifyAddress(hostname);
+  return kind === 'loopback' || kind === 'unspecified';
+};
+
+/** The socket dials' gate: the same allow-list, offline state and record as `fetch`. No mocks — a
+ *  socket test injects its transport (`connect`, `client`), it does not intercept the dial. */
+const socketRefusal = (url: string, method: string): Error | undefined => {
+  state.seen.push(url);
+  let target: URL;
+  try {
+    target = new URL(url);
+  } catch {
+    return undefined; // Not a URL: the real constructor refuses it with its own SyntaxError.
+  }
+  // Offline before loopback, the order `fetch` checks in: offline cuts EVERY dial, this machine's
+  // included, or a socket would reach a host the same test's `fetch` is refused.
+  if (state.network !== 'online') {
+    return new NetworkOfflineError({ url, method, mode: state.network });
+  }
+  if (isThisMachine(target.hostname)) return undefined;
+  if (state.allowed.has(target.host)) return undefined;
+  return new NetworkSealedError({ url, method, allowed: [...state.allowed], transport: 'socket' });
+};
+
+/** Replace global fetch, `WebSocket` and `Bun.connect`. Idempotent: sealing twice keeps the one
+ *  set of originals around. */
 export function sealNetwork(): void {
   if (state.original !== undefined) return;
   state.original = globalThis.fetch;
+  state.restoreSockets = installSocketSeal(socketRefusal);
   globalThis.fetch = (async (input: RequestInfo | URL, init?: RequestInit): Promise<Response> => {
     const url = urlOf(input);
     state.seen.push(url);
@@ -94,13 +137,15 @@ export function unsealNetwork(): void {
   if (state.original === undefined) return;
   globalThis.fetch = state.original;
   state.original = undefined;
+  state.restoreSockets?.();
+  state.restoreSockets = undefined;
 }
 
 /** Whether the patch is installed. The `network` fixture seals before going offline, so that
  *  `offline()` has teeth in a process that deliberately unsealed (`ULTIMATE_TEST_ALLOW_NET=1`). */
 export const isNetworkSealed = (): boolean => state.original !== undefined;
 
-/** The one writer of the offline gate — `createTestNetwork()`. Never call it from a test body. */
+/** The one writer of the offline gate — `testNetwork()`. Never call it from a test body. */
 export function setNetworkState(next: NetworkState): void {
   state.network = next;
 }

package/src/sealed-sockets.ts

@@ -0,0 +1,59 @@
+// The socket half of the sealed network: `WebSocket` and `Bun.connect`, the two dials that are not
+// `fetch`. Only the patching lives here; WHETHER a dial may leave is `sealed-network.ts`'s one
+// gate, handed in, so fetch and sockets cannot disagree about the allow-list or the offline state.
+
+/** A dial's verdict: the error to raise, or `undefined` to let it through to the real one. */
+export type SocketGate = (url: string, method: 'WEBSOCKET' | 'CONNECT') => Error | undefined;
+
+/** `Bun.connect`'s two option shapes, read structurally: TCP names a host, a unix socket a path. */
+interface ConnectOptions {
+  readonly hostname?: string;
+  readonly port?: number;
+  readonly unix?: string;
+}
+
+type Connect = (options: ConnectOptions) => Promise<unknown>;
+
+/** A dial target as a URL, so the gate parses one shape. IPv6 literals need their brackets. */
+const tcpUrl = (hostname: string, port: number | undefined): string => {
+  const host = hostname.includes(':') && !hostname.startsWith('[') ? `[${hostname}]` : hostname;
+  return `tcp://${host}:${port ?? 0}`;
+};
+
+/**
+ * Patch both dials and return the uninstaller, which puts back exactly what was there — the same
+ * originals, so `globalThis.WebSocket === original` holds again. Assigned through `Reflect.set`:
+ * `Bun.connect` is a writable data property, but the type declares it a namespace function.
+ */
+export function installSocketSeal(gate: SocketGate): () => void {
+  const OriginalWebSocket = globalThis.WebSocket;
+  const originalConnect = Reflect.get(Bun, 'connect') as Connect;
+
+  // A subclass, not a wrapper function: `instanceof WebSocket`, the static `OPEN`/`CLOSED` and
+  // every option a caller passes keep working. Code before `super()` may not touch `this`, and
+  // does not — the refusal is thrown before the native constructor ever dials.
+  class SealedWebSocket extends OriginalWebSocket {
+    constructor(url: string | URL, protocols?: string | string[]) {
+      const refusal = gate(String(url), 'WEBSOCKET');
+      if (refusal !== undefined) throw refusal;
+      super(url, protocols);
+    }
+  }
+
+  // A promise either way, as the real `Bun.connect` answers a dial it cannot make. A unix socket is
+  // a path on this machine and is never egress.
+  const sealedConnect: Connect = (options) => {
+    if (options.unix === undefined && options.hostname !== undefined) {
+      const refusal = gate(tcpUrl(options.hostname, options.port), 'CONNECT');
+      if (refusal !== undefined) return Promise.reject(refusal);
+    }
+    return originalConnect(options);
+  };
+
+  Reflect.set(globalThis, 'WebSocket', SealedWebSocket);
+  Reflect.set(Bun, 'connect', sealedConnect);
+  return () => {
+    Reflect.set(globalThis, 'WebSocket', OriginalWebSocket);
+    Reflect.set(Bun, 'connect', originalConnect);
+  };
+}

package/src/template-db.ts

@@ -18,7 +18,7 @@ export interface TemplateDbConfig {
   /** Connection URL with rights to CREATE DATABASE. Absent means "fall back to PGlite". */
   readonly adminUrl?: string | undefined;
   readonly templateName?: string;
-  /** Applied once, into the template, under an advisory lock. */
+  /** Applied into the template under an advisory lock, which every worker's clone also holds. */
   readonly migrate?: (url: string) => Promise<void>;
 }
 
@@ -65,7 +65,7 @@ export function urlFor(adminUrl: string, database: string): string {
   return url.toString();
 }
 
-export const createTemplateSql = (template: string): string =>
+export const templateSql = (template: string): string =>
   `CREATE DATABASE "${template}" TEMPLATE template0`;
 
 export const cloneSql = (template: string, target: string): string =>
@@ -132,7 +132,7 @@ export async function acquireWorkerDatabase(
     await admin.exec(lockSql(template));
     try {
       try {
-        await admin.exec(createTemplateSql(template));
+        await admin.exec(templateSql(template));
       } catch (error) {
         // Tolerated for the CREATE alone: "already exists" means another worker got here first, or
         // a Postgres that outlives one run still holds last run's template.
@@ -144,11 +144,14 @@ export async function acquireWorkerDatabase(
       // serialises them, so a failure here is a real failure and `alreadyExists` (a substring match
       // on the message) would read `relation "x_jobs" already exists` as success.
       if (config.migrate !== undefined) await config.migrate(urlFor(adminUrl, template));
+      // INSIDE the lock: `CREATE DATABASE … TEMPLATE` waits 5 s for every session on the template
+      // to leave, then refuses — and the next worker's migration opens one the moment the lock is
+      // free. Measured: a clone outside it failed whenever that migration ran past 5 s.
+      await admin.exec(dropSql(database));
+      await admin.exec(cloneSql(template, database));
     } finally {
       await admin.exec(unlockSql(template));
     }
-    await admin.exec(dropSql(database));
-    await admin.exec(cloneSql(template, database));
   } catch (error) {
     await admin.close();
     throw new TestDatabaseUnavailableError({

package/src/test-types.ts

@@ -79,8 +79,12 @@ export interface PageLike {
   gotoStreamed(url: string): Promise<{ readonly html: string }>;
   /** Called only by `x g route`'s generated e2e template — no driver runs it yet. */
   reload(): Promise<unknown>;
-  /** Resolves once the service worker controls the page, so the offline assertions are not racy. */
-  waitForServiceWorker(): Promise<void>;
+  /**
+   * Resolves once the service worker controls the page, so the offline assertions are not racy. A
+   * page the worker cannot claim — the first of a run, committed before it activated — is reloaded
+   * once (that navigation IS answered by the worker). `timeoutMs` raises this call's budget.
+   */
+  waitForServiceWorker(options?: { readonly timeoutMs?: number | undefined }): Promise<void>;
   /** Called only by `x g route`'s generated e2e template — no driver runs it yet. */
   title(): Promise<string>;
   url(): string;