@ultimat3/testing 22.6.1 → 22.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/testing",
-  "version": "22.6.1",
+  "version": "22.7.0",
   "description": "Test harness: cloned template DBs per worker, frozen clock, sealed network, 6 test types",
   "license": "MIT",
   "type": "module",
@@ -35,16 +35,18 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/cache": "22.6.1",
-    "@ultimat3/core": "22.6.1",
-    "@ultimat3/db": "22.6.1",
-    "@ultimat3/entity": "22.6.1",
-    "@ultimat3/i18n": "22.6.1",
-    "@ultimat3/jobs": "22.6.1",
-    "@ultimat3/mail": "22.6.1",
-    "@ultimat3/policy": "22.6.1",
-    "@ultimat3/query": "22.6.1",
-    "@ultimat3/realtime": "22.6.1",
-    "@ultimat3/time": "22.6.1"
+    "@ultimat3/action": "22.7.0",
+    "@ultimat3/cache": "22.7.0",
+    "@ultimat3/core": "22.7.0",
+    "@ultimat3/db": "22.7.0",
+    "@ultimat3/entity": "22.7.0",
+    "@ultimat3/i18n": "22.7.0",
+    "@ultimat3/jobs": "22.7.0",
+    "@ultimat3/mail": "22.7.0",
+    "@ultimat3/policy": "22.7.0",
+    "@ultimat3/query": "22.7.0",
+    "@ultimat3/realtime": "22.7.0",
+    "@ultimat3/render": "22.7.0",
+    "@ultimat3/time": "22.7.0"
   }
 }

package/src/app-jsx-loader.ts

@@ -0,0 +1,30 @@
+// An APP's tests compile every `.tsx` with the app's JSX factory from the first file on.
+//
+// Since 22.7 a worker runs many files in one module registry (no `--isolate`), so a `.tsx` module
+// is compiled ONCE per worker and cached. `@ultimat3/render`'s loader is installed by importing
+// `@ultimat3/render/server`; a file that reached a page component before any file had imported it
+// cached the page compiled with Bun's classic factory, and every later file on that worker failed
+// with `React is not defined` (18 notificado.co tests, measured). Installing the loader in the
+// preload makes the first compile the right one.
+//
+// Only in an app (an `app.config.ts` at the run's root): the framework repository's own tests
+// include suites that pin what a process WITHOUT the loader does, and they keep that process.
+
+// why: Bun ships no synchronous file-exists check; Bun.file().exists() is async and a preload
+// decides this before any test file loads.
+import { existsSync } from 'node:fs';
+// why: Bun ships no path-join primitive.
+import { join } from 'node:path';
+
+export const APP_CONFIG = 'app.config.ts';
+
+export const isAppRoot = (root: string = process.cwd()): boolean =>
+  existsSync(join(root, APP_CONFIG));
+
+/** Install the render loader when this run's root is an app. Returns whether it did. */
+export async function installAppJsxLoader(root: string = process.cwd()): Promise<boolean> {
+  if (!isAppRoot(root)) return false;
+  const { installRenderLoader } = await import('@ultimat3/render/server');
+  installRenderLoader();
+  return true;
+}

package/src/file-boundary.ts

@@ -0,0 +1,138 @@
+// "One test file ended, the next begins" — the moment a shared worker process must hand the next
+// file the process it would have had alone.
+//
+// Since 22.7 `x test` / `x verify` run each worker WITHOUT `--isolate`: one global and one module
+// registry per worker, reused across every file it runs (2-5x faster, measured in
+// `@ultimat3/cli`'s `test-workers.ts`). What a file leaves on `globalThis` then reaches every
+// later file on that worker. Measured on notificado.co: one island test that never disposed its
+// mount left the fake `window`/`document` installed, PGlite then took the process for a browser
+// (`window.location.pathname` of undefined), and 264 unrelated tests failed.
+//
+// Bun gives a preload no per-file hook. The one signal is a test file being LOADED, which
+// `registry-leak-guard.ts` already intercepts; it calls `runFileBoundary()` there, and this module
+// owns what happens: the hooks registered with `onFileBoundary` (island mounts disposed first,
+// while their fake DOM is still installed), then the globals put back.
+
+type Hook = () => void;
+
+const hooks: Hook[] = [];
+
+/** Run `hook` between every two test files of one worker process. */
+export function onFileBoundary(hook: Hook): void {
+  hooks.push(hook);
+}
+
+/**
+ * Globals a file may add and keep: `__`-prefixed helper slots (tslib's `__extends`, seroval's
+ * `__SEROVAL_REFS__`) that a module installs ONCE at import and reads back later — the module is
+ * cached, so deleting its slot would break the next file that uses it, not protect it.
+ */
+const kept = (key: string): boolean => key.startsWith('__') || /^\d+$/.test(key);
+
+interface Baseline {
+  readonly keys: ReadonlySet<string>;
+  readonly descriptors: ReadonlyMap<string, PropertyDescriptor>;
+}
+
+let baseline: Baseline | undefined;
+let envBaseline: Readonly<Record<string, string | undefined>> | undefined;
+
+/**
+ * `process.env` back to what the first file saw: a test that sets `ULTIMATE_EVAL_RECORD` (or any
+ * key) and forgets it changes what every later file on the worker reads — measured, the framework's
+ * own `verify.run` MCP test then saw the eval step red. Returns the keys it touched.
+ */
+export function restoreEnv(
+  snapshot: Readonly<Record<string, string | undefined>>,
+  env: Record<string, string | undefined> = process.env,
+): readonly string[] {
+  const touched: string[] = [];
+  for (const key of Object.keys(env)) {
+    if (!(key in snapshot)) {
+      delete env[key];
+      touched.push(key);
+    }
+  }
+  for (const [key, value] of Object.entries(snapshot)) {
+    if (env[key] !== value && value !== undefined) {
+      env[key] = value;
+      touched.push(key);
+    }
+  }
+  return touched;
+}
+
+/**
+ * The globals the process started with — taken at the FIRST file boundary, not at preload time,
+ * so every preload (the app's own, a DOM registrator among them) is part of the baseline.
+ */
+export function captureGlobals(host: object = globalThis): Baseline {
+  const keys = new Set(Object.getOwnPropertyNames(host));
+  const descriptors = new Map<string, PropertyDescriptor>();
+  for (const key of keys) {
+    if (kept(key)) continue;
+    const descriptor = Object.getOwnPropertyDescriptor(host, key);
+    if (descriptor !== undefined) descriptors.set(key, descriptor);
+  }
+  return { keys, descriptors };
+}
+
+const same = (a: PropertyDescriptor, b: PropertyDescriptor): boolean =>
+  a.value === b.value && a.get === b.get && a.set === b.set;
+
+/**
+ * Delete what the last file added and put back what it replaced. Returns the keys it touched, so
+ * a test can pin it. A property the host refuses to change is left alone — never a throw here.
+ */
+export function restoreGlobals(snapshot: Baseline, host: object = globalThis): readonly string[] {
+  const record = host as Record<string, unknown>;
+  const touched: string[] = [];
+  for (const key of Object.getOwnPropertyNames(host)) {
+    if (kept(key)) continue;
+    if (!snapshot.keys.has(key)) {
+      try {
+        if (delete record[key]) touched.push(key);
+      } catch {
+        // Non-configurable: nothing a restore can do, and the run must go on.
+      }
+      continue;
+    }
+    const was = snapshot.descriptors.get(key);
+    const now = Object.getOwnPropertyDescriptor(host, key);
+    if (was === undefined || now === undefined || same(was, now)) continue;
+    try {
+      Object.defineProperty(host, key, was);
+      touched.push(key);
+    } catch {
+      // Non-configurable and changed: leave it.
+    }
+  }
+  for (const [key, descriptor] of snapshot.descriptors) {
+    if (Object.getOwnPropertyDescriptor(host, key) !== undefined) continue;
+    try {
+      Object.defineProperty(host, key, descriptor);
+      touched.push(key);
+    } catch {
+      // Could not be put back; the next file sees it missing, as it would have anyway.
+    }
+  }
+  return touched;
+}
+
+/** Called by the leak guard as each test file loads. The first call only takes the baseline. */
+export function runFileBoundary(): void {
+  if (baseline === undefined) {
+    baseline = captureGlobals();
+    envBaseline = { ...process.env };
+    return;
+  }
+  for (const hook of hooks) {
+    try {
+      hook();
+    } catch {
+      // A hook that throws (an island's own disposer) must not stop the rest of the reset.
+    }
+  }
+  restoreGlobals(baseline);
+  if (envBaseline !== undefined) restoreEnv(envBaseline);
+}

package/src/fixture-island.ts

@@ -218,6 +218,26 @@ function installGlobals(values: Readonly<Record<string, unknown>>): () => void {
  * file's island. The disposer runs while the fake `document` is still installed, because what it
  * clears (a listener on `document`, an interval whose callback reads it) was made against that one.
  */
+/**
+ * Every mount not yet disposed. A worker runs many files in one global (22.7), so a mount a file
+ * forgot to `using` is disposed at the file boundary (`file-boundary.ts`) instead of handing its
+ * fake `window`/`document` to every later file.
+ */
+const liveMounts = new Set<() => void>();
+
+/** Dispose every mount still installed, newest first. Returns how many there were. */
+export function disposeLiveIslands(): number {
+  const pending = [...liveMounts].reverse();
+  for (const dispose of pending) {
+    try {
+      dispose();
+    } catch {
+      // The island's own disposer threw; its globals were still restored in `dispose`'s finally.
+    }
+  }
+  return pending.length;
+}
+
 export async function mountIsland(options: MountIslandOptions): Promise<MountedIsland> {
   // `only`, because this fixture has always KNOWN which island it wants and asked for all of them
   // anyway — `island-bundle.ts` added the option for exactly this caller ("a test that mounts a
@@ -266,6 +286,7 @@ export async function mountIsland(options: MountIslandOptions): Promise<MountedI
       // disposer is idempotent while an island's `clearInterval` wrapper need not be.
       if (disposed) return;
       disposed = true;
+      liveMounts.delete(dispose);
       try {
         unmount?.();
       } finally {
@@ -274,6 +295,7 @@ export async function mountIsland(options: MountIslandOptions): Promise<MountedI
         restore();
       }
     };
+    liveMounts.add(dispose);
     const resolve = (target: string | FakeElement | null | undefined): FakeElement | null =>
       typeof target === 'string' ? el.querySelector(target) : (target ?? null);
     return {

package/src/index.ts

@@ -271,6 +271,8 @@ export type { RegistryLeak, RegistrySample } from './registry-leak-guard';
 export { installRegistryLeakGuard, leakBetween, sampleRegistries } from './registry-leak-guard';
 export type { ProcessRegistrySnapshot } from './registry-snapshot';
 export { captureProcessRegistries, restoreProcessRegistries } from './registry-snapshot';
+export type { DatabaseSnapshot } from './reusable-database';
+export { restoreDatabase, reusableDatabase, snapshotDatabase } from './reusable-database';
 export type { MockRoute, NetworkSnapshot, NetworkState } from './sealed-network';
 // `setNetworkState` is deliberately not here: it is the offline gate's one writer, and a test that
 // called it directly would bypass the `network` fixture's disposal and leave the whole process

package/src/preload.ts

@@ -8,6 +8,9 @@
 import { installDeterminism } from './determinism';
 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 { installRegistryLeakGuard } from './registry-leak-guard';
 import { sealNetwork } from './sealed-network';
@@ -22,10 +25,32 @@ installDeterminism({
 
 registerFrameworkFixtures();
 
+// Inside a test process the machine's test slots are already accounted for — by the `x test` /
+// `x verify` that spawned it, or by nobody when `bun test` ran bare. An `x test` a test runs in
+// process (the framework's own suites do) must never lease from the real pool: it would wait on
+// its own parent's slots. `@ultimat3/cli`'s `test-slots.ts` reads this.
+Bun.env['ULTIMATE_TEST_SLOT_HELD'] ??= '1';
+
 // One `bun test` invocation is one process: a file that leaves a process-global registry dirty
 // 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);
+
+// 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') {
+  const { forgetHandedOutActionPaths } = await import('@ultimat3/action');
+  onFileBoundary(forgetHandedOutActionPaths);
+}
+
+// An app's `.tsx` compiles with the app's JSX factory on the first file, never cached classic.
+await installAppJsxLoader();
+
 // Isolated runs only (`x test` says so): Bun 1.4.0 keeps every finished file alive while a plugin
 // is registered. See `isolated-plugins.ts`.
 releasePluginsAfterIsolatedFile();

package/src/registry-leak-guard.ts

@@ -5,9 +5,15 @@
 
 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 type { ProcessRegistrySnapshot } from './registry-snapshot';
-import { captureProcessRegistries, restoreProcessRegistries } from './registry-snapshot';
+import {
+  captureProcessRegistries,
+  mergeSnapshots,
+  restoreProcessRegistries,
+} from './registry-snapshot';
 
 /**
  * What is REPORTED, and why only these two. Both are BOOT installs — `declareTags` takes the
@@ -34,7 +40,7 @@ import { captureProcessRegistries, restoreProcessRegistries } from './registry-s
  *   | permissions / roles | `restorePermissions` / `restoreRoles` | `@ultimat3/policy` | yes |
  *   | routes | `clearRoutes` | `@ultimat3/render` | **no** |
  *   | jobs | `resetJobs` | `@ultimat3/jobs` | **no** |
- *   | tasks | `resetTasks` | `@ultimat3/jobs` | **no** |
+ *   | tasks | `restoreTasks` | `@ultimat3/jobs` | yes (22.7) |
  *   | actions | `resetRegistry` | `@ultimat3/action` | **no** |
  *   | queries | `resetRegistry` | `@ultimat3/query` | **no** |
  *   | models / prompts / agents | `resetModels` / `resetPrompts` / `resetAgents` | `@ultimat3/ai` | **no** |
@@ -129,6 +135,11 @@ export function installRegistryLeakGuard(): void {
       }
     | undefined;
   const leaks: RegistryLeak[] = [];
+  // Everything every earlier file inherited, merged: what a shared worker restores to.
+  let accumulated: ProcessRegistrySnapshot | undefined;
+  // The locale config before any app code ran — preload time.
+  const pristineLocales = JSON.stringify(captureProcessRegistries().locales);
+  const inApp = isAppRoot();
 
   const close = (): void => {
     if (current === undefined) return;
@@ -137,7 +148,33 @@ export function installRegistryLeakGuard(): void {
     // The repair, at the only point it is safe: the file is over and the next one has not
     // evaluated yet, so what goes back is exactly what that file inherited — module-scope
     // declarations included, which is the half a plain `resetX()` in a `beforeEach` destroys.
-    restoreProcessRegistries(current.snapshot);
+    //
+    // In an APP, declarations are put back as a UNION with what the process holds now (22.7,
+    // shared worker): an app module a test imported lazily declared its permissions and roles once,
+    // for the life of the worker, and taking them away here would leave every later file without
+    // them. The framework repository's own suites keep the exact restore: many of them lean on an
+    // EMPTY permission set (no validation), and a test body's declaration must not switch it on for
+    // every later file. Tasks go back EXACTLY everywhere: one a test body registered must not fire
+    // in the next file's scheduler round.
+    const live = captureProcessRegistries();
+    const merged = inApp ? mergeSnapshots(live, current.snapshot) : current.snapshot;
+    // Locales likewise, in one case: the file's baseline still held the framework's pristine
+    // config and an app's `defineCatalogs()` ran during the file (a lazily imported catalog
+    // module) — that configured the worker for good, since the module will not evaluate again.
+    // A test that called `configureLocales()` by hand is undone, as before.
+    // Only in an app: there `defineCatalogs()` can only be THE app's catalog module, while the
+    // framework repository's own suites define a fixture app's catalogs per test, to be undone.
+    const declaredLazily =
+      inApp &&
+      JSON.stringify(current.snapshot.locales) === pristineLocales &&
+      live.catalogDeclarations > current.snapshot.catalogDeclarations;
+    const restored = {
+      ...merged,
+      locales: declaredLazily ? live.locales : current.snapshot.locales,
+      tasks: current.snapshot.tasks,
+    };
+    restoreProcessRegistries(restored);
+    accumulated = mergeSnapshots(accumulated, restored);
     current = undefined;
   };
 
@@ -146,11 +183,8 @@ export function installRegistryLeakGuard(): void {
   // how an app declares its tags — and everything after this point is the file's own to undo.
   hookHost[BASELINE_HOOK] = () => {
     if (pending === undefined) return;
-    current = {
-      file: pending,
-      before: sampleRegistries(),
-      snapshot: captureProcessRegistries(),
-    };
+    accumulated = mergeSnapshots(accumulated, captureProcessRegistries());
+    current = { file: pending, before: sampleRegistries(), snapshot: accumulated };
     pending = undefined;
   };
 
@@ -172,6 +206,8 @@ export function installRegistryLeakGuard(): void {
       // `.test.tsx` files exist and the convention is `<file>.test.ts`, so the narrower filter
       // costs nothing today; a `.test.tsx` added later is unguarded rather than mis-compiled.
       build.onLoad({ filter: /\.test\.ts$/ }, async (args) => {
+        // Before the registry restore: an island disposed here still needs its fake DOM.
+        runFileBoundary();
         close();
         pending = repoRelative(args.path);
         return {

package/src/registry-snapshot.ts

@@ -10,6 +10,7 @@
 
 import type { Catalog, Locale, LocaleConfig } from '@ultimat3/i18n';
 import {
+  catalogDeclarationCount,
   catalogFor,
   configureLocales,
   localeConfig,
@@ -18,6 +19,8 @@ import {
   registeredLocales,
   resetCatalogs,
 } from '@ultimat3/i18n';
+import type { TaskHandle } from '@ultimat3/jobs';
+import { registeredTasks, restoreTasks } from '@ultimat3/jobs';
 import type { RoleMap } from '@ultimat3/policy';
 import {
   knownPermissions,
@@ -39,6 +42,14 @@ export interface ProcessRegistrySnapshot {
   readonly roles: RoleMap;
   /** Kept beside the map: restoring through `defineRoles()` would rewrite every site. */
   readonly roleSites: Readonly<Record<string, string>>;
+  /**
+   * Scheduled tasks. Since 22.7 a worker process runs many files in ONE global, so a task a test
+   * body registered (`packages/jobs/src/task.test.ts`'s deliberately throwing `aBrokenDigest`)
+   * fired in every later file's `appManifest` round — 14 framework failures, measured.
+   */
+  readonly tasks: readonly TaskHandle[];
+  /** `defineCatalogs()` calls so far — see `@ultimat3/i18n`'s `catalogDeclarationCount`. */
+  readonly catalogDeclarations: number;
 }
 
 export function captureProcessRegistries(): ProcessRegistrySnapshot {
@@ -48,6 +59,8 @@ export function captureProcessRegistries(): ProcessRegistrySnapshot {
     permissions: knownPermissions(),
     roles: roleDefinitions(),
     roleSites: roleDeclarationSites(),
+    tasks: registeredTasks(),
+    catalogDeclarations: catalogDeclarationCount(),
   };
 }
 
@@ -63,6 +76,7 @@ export function restoreProcessRegistries(snapshot: ProcessRegistrySnapshot): voi
   restoreCatalogs(snapshot.catalogs);
   restorePermissions(snapshot.permissions);
   restoreRoles(snapshot.roles, snapshot.roleSites);
+  restoreTasks(snapshot.tasks);
 }
 
 /**
@@ -99,3 +113,34 @@ function restoreCatalogs(snapshot: readonly (readonly [Locale, Catalog])[]): voi
     registerCatalog(locale, mergeCatalogs(inherited.get(locale) ?? {}, live.get(locale) ?? {}));
   }
 }
+
+/**
+ * What a shared worker restores to after a file: everything any earlier file's module graph
+ * declared, plus what this file inherited. Since 22.7 a worker runs many files in one module
+ * registry, so a module a file imports evaluates ONCE — a later file that resets the permission
+ * set at module scope would otherwise hand every file after it a registry missing declarations no
+ * cached module will ever make again (measured on notificado.co: "admin:read is not in the
+ * permission set (8 known)"). Newer wins on a conflict, so a file's own redefinition still stands
+ * for that file.
+ */
+export function mergeSnapshots(
+  older: ProcessRegistrySnapshot | undefined,
+  newer: ProcessRegistrySnapshot,
+): ProcessRegistrySnapshot {
+  if (older === undefined) return newer;
+  const catalogs = new Map(older.catalogs);
+  for (const [locale, catalog] of newer.catalogs) {
+    catalogs.set(locale, mergeCatalogs(catalogs.get(locale) ?? {}, catalog));
+  }
+  const tasks = new Map(older.tasks.map((handle) => [handle.name, handle] as const));
+  for (const handle of newer.tasks) tasks.set(handle.name, handle);
+  return {
+    locales: newer.locales,
+    catalogs: [...catalogs],
+    permissions: [...new Set([...older.permissions, ...newer.permissions])],
+    roles: { ...older.roles, ...newer.roles },
+    roleSites: { ...older.roleSites, ...newer.roleSites },
+    tasks: [...tasks.values()],
+    catalogDeclarations: Math.max(older.catalogDeclarations, newer.catalogDeclarations),
+  };
+}

package/src/reusable-database.ts

@@ -0,0 +1,118 @@
+// One database per test WORKER, reset between files — instead of one booted per test file.
+//
+// Booting an embedded Postgres (PGlite) from a migrated template costs 2.4-7 s of CPU on a
+// 12-core box (measured, 64 MB template: 2.7-7.2 s cold, 2.4-2.9 s with the WASM module and fs
+// bundle already compiled — the untar and the postgres start are the cost, not the compile). A
+// suite that boots one per file pays that in every file: notificado.co's unit tier has 236 such
+// files, ~700 s of CPU, which is most of its wall time at any width.
+//
+// Since 22.7 a worker runs many files in one process (no `--isolate`), so the database can outlive
+// a file. `reusableDatabase(open)` opens it ONCE per worker, snapshots every table's rows and every
+// sequence right after (the migrated template: reference data, seeded rows), and on each later
+// acquire puts the data back to exactly that: TRUNCATE every table, re-insert the snapshot, reset
+// the sequences — with triggers off for the duration (`session_replication_role = replica`), so an
+// insert-only guard on an evidence table does not refuse the reset the way it refuses a test.
+//
+// What it does NOT undo: DDL a test ran (a table it created stays; one it dropped stays gone). A
+// test that changes the schema opens its own database.
+
+import type { DbClient, SqlFragment } from '@ultimat3/db';
+import { identifier, raw, sql } from '@ultimat3/db';
+
+interface TableSnapshot {
+  readonly table: string;
+  /** Insertable columns — generated ones are recomputed, never written. */
+  readonly columns: readonly string[];
+  /** The rows as JSON text, or null for an empty table. */
+  readonly rows: string | null;
+}
+
+interface SequenceSnapshot {
+  readonly sequence: string;
+  readonly lastValue: string | null;
+}
+
+export interface DatabaseSnapshot {
+  readonly tables: readonly TableSnapshot[];
+  readonly sequences: readonly SequenceSnapshot[];
+}
+
+const list = (names: readonly string[]): SqlFragment =>
+  raw(names.map((name) => `"${name.replaceAll('"', '""')}"`).join(', '));
+
+/** Every public table's rows and every public sequence's position, as they are now. */
+export async function snapshotDatabase(client: DbClient): Promise<DatabaseSnapshot> {
+  const tables = await client.query<{ table_name: string }>(
+    sql`select table_name from information_schema.tables where table_schema = 'public' and table_type = 'BASE TABLE' order by table_name`,
+  );
+  const snapshots: TableSnapshot[] = [];
+  for (const { table_name: table } of tables) {
+    const columns = (
+      await client.query<{ column_name: string }>(
+        sql`select column_name from information_schema.columns where table_schema = 'public' and table_name = ${table} and is_generated = 'NEVER' order by ordinal_position`,
+      )
+    ).map((row) => row.column_name);
+    const row = await client.one<{ rows: string | null }>(
+      sql`select json_agg(t)::text as rows from ${identifier(table)} t`,
+    );
+    snapshots.push({ table, columns, rows: row?.rows ?? null });
+  }
+  const sequences = await client.query<{ sequencename: string; last_value: string | null }>(
+    sql`select sequencename, last_value::text as last_value from pg_sequences where schemaname = 'public'`,
+  );
+  return {
+    tables: snapshots,
+    sequences: sequences.map((row) => ({ sequence: row.sequencename, lastValue: row.last_value })),
+  };
+}
+
+/** Put every table's rows and every sequence back to `snapshot`. Triggers are off meanwhile. */
+export async function restoreDatabase(client: DbClient, snapshot: DatabaseSnapshot): Promise<void> {
+  const current = (
+    await client.query<{ table_name: string }>(
+      sql`select table_name from information_schema.tables where table_schema = 'public' and table_type = 'BASE TABLE'`,
+    )
+  ).map((row) => row.table_name);
+  await client.execute(raw('set session_replication_role = replica'));
+  try {
+    if (current.length > 0) {
+      await client.execute(sql`truncate ${list(current)} restart identity cascade`);
+    }
+    for (const table of snapshot.tables) {
+      if (table.rows === null || !current.includes(table.table)) continue;
+      const columns = list(table.columns);
+      await client.execute(
+        sql`insert into ${identifier(table.table)} (${columns}) overriding system value select ${columns} from json_populate_recordset(null::${identifier(table.table)}, ${table.rows}::json)`,
+      );
+    }
+    for (const { sequence, lastValue } of snapshot.sequences) {
+      await client.execute(
+        lastValue === null
+          ? sql`select setval(${`"${sequence}"`}::regclass, 1, false)`
+          : sql`select setval(${`"${sequence}"`}::regclass, ${lastValue}::bigint, true)`,
+      );
+    }
+  } finally {
+    await client.execute(raw('set session_replication_role = origin'));
+  }
+}
+
+/**
+ * `acquire()` answers the same client for the life of the worker process, with its data reset to
+ * what it held right after `open()`. The first call opens and snapshots; each later one restores.
+ * Never close what it hands out — the worker's exit does.
+ */
+export function reusableDatabase<C extends DbClient>(open: () => Promise<C>): () => Promise<C> {
+  let opened: Promise<{ client: C; snapshot: DatabaseSnapshot }> | undefined;
+  let first = true;
+  return async () => {
+    opened ??= (async () => {
+      const client = await open();
+      return { client, snapshot: await snapshotDatabase(client) };
+    })();
+    const { client, snapshot } = await opened;
+    if (first) first = false;
+    else await restoreDatabase(client, snapshot);
+    return client;
+  };
+}