@ultimat3/cli 22.15.0 → 23.0.0

package/src/coverage-lcov.ts

@@ -0,0 +1,193 @@
+// The one lcov reader: what `bun test --coverage --coverage-reporter=lcov` wrote, as per-file
+// facts, and how the facts of several test processes add up. `scripts/coverage-gate.ts` (the
+// framework's packages) and `coverage-floor.ts` (an app) both read through it.
+
+/** One `SF:` record, as written: its own totals and every `DA:` line. */
+export interface LcovRecord {
+  /** The `SF:` path, verbatim — Bun writes it relative to the directory the run started in. */
+  readonly file: string;
+  /** `LF` / `LH` / `FNF` / `FNH`. Bun's lcov carries no `FN:` lines, so functions are counts only. */
+  readonly linesFound: number;
+  readonly linesHit: number;
+  readonly funcsFound: number;
+  readonly funcsHit: number;
+  /** line → hits. */
+  readonly lines: ReadonlyMap<number, number>;
+}
+
+export function parseLcov(text: string): readonly LcovRecord[] {
+  const records: LcovRecord[] = [];
+  let file: string | undefined;
+  let lf = 0;
+  let lh = 0;
+  let fnf = 0;
+  let fnh = 0;
+  let lines = new Map<number, number>();
+  for (const line of text.split('\n')) {
+    if (line.startsWith('SF:')) {
+      file = line.slice(3);
+      lf = 0;
+      lh = 0;
+      fnf = 0;
+      fnh = 0;
+      lines = new Map();
+    } else if (file === undefined) {
+      // Before the first record (`TN:`), or between two.
+    } else if (line.startsWith('DA:')) {
+      const comma = line.indexOf(',');
+      const at = Number(line.slice(3, comma));
+      const hits = Number(line.slice(comma + 1));
+      if (comma > 3 && Number.isSafeInteger(at) && Number.isFinite(hits)) lines.set(at, hits);
+    } else if (line.startsWith('LF:')) lf = Number(line.slice(3));
+    else if (line.startsWith('LH:')) lh = Number(line.slice(3));
+    else if (line.startsWith('FNF:')) fnf = Number(line.slice(4));
+    else if (line.startsWith('FNH:')) fnh = Number(line.slice(4));
+    else if (line === 'end_of_record') {
+      records.push({
+        file,
+        linesFound: lf,
+        linesHit: lh,
+        funcsFound: fnf,
+        funcsHit: fnh,
+        lines,
+      });
+      file = undefined;
+    }
+  }
+  return records;
+}
+
+/** One source file's coverage: which lines ran, which could have and did not, and its functions. */
+export interface FileCoverage {
+  readonly hit: readonly number[];
+  readonly miss: readonly number[];
+  readonly funcsFound: number;
+  readonly funcsHit: number;
+}
+
+export const fileCoverageOf = (record: LcovRecord): FileCoverage => {
+  const hit: number[] = [];
+  const miss: number[] = [];
+  for (const [line, hits] of record.lines) (hits > 0 ? hit : miss).push(line);
+  return { hit, miss, funcsFound: record.funcsFound, funcsHit: record.funcsHit };
+};
+
+/**
+ * One file's coverage across several test PROCESSES.
+ *
+ * A line is covered when any process ran it. It is uncovered only when EVERY process that loaded
+ * the file lists it as unrun — because Bun lists a function nothing called in that process by its
+ * whole line range, comments and blank lines included, and lists a function that ran by its
+ * executable lines alone. A union therefore counts the comments of every function one process
+ * called and another merely loaded, and the number moves with how the files were dealt:
+ * `examples/dummy` read 59.9% at four workers, 65.0% at two and 65.5% in one process, same tree
+ * (measured 2026-10-01, Bun 1.4.0, whose own `--parallel` merge is that union). This rule read
+ * 65.90% for 2, 4 and 8 processes and for contiguous chunks — and is exactly what Bun reports for
+ * one `--isolate` process.
+ *
+ * Functions have no identity in Bun's lcov, only two counts, so they cannot be unioned: the file
+ * takes the best any one process reached. That is a lower bound, and the reason the processes are
+ * cut along directories (`verify-coverage-run.ts`) — the tests beside a file run together.
+ */
+export function mergeFileCoverage(parts: readonly FileCoverage[]): FileCoverage {
+  if (parts.length === 1) return parts[0] as FileCoverage;
+  const hit = new Set<number>();
+  for (const part of parts) for (const line of part.hit) hit.add(line);
+  const missIn = parts.map((part) => new Set(part.miss));
+  const miss = [...(missIn[0] ?? [])].filter(
+    (line) => !hit.has(line) && missIn.every((set) => set.has(line)),
+  );
+  return {
+    hit: [...hit].sort((a, b) => a - b),
+    miss: miss.sort((a, b) => a - b),
+    funcsFound: Math.max(0, ...parts.map((part) => part.funcsFound)),
+    funcsHit: Math.max(0, ...parts.map((part) => part.funcsHit)),
+  };
+}
+
+/** file → coverage. A plain record so it survives `--json` between a shard and `x verify merge`. */
+export type CoverageMap = Readonly<Record<string, FileCoverage>>;
+
+/** Several processes' (or several shards') maps as one, file by file. */
+export function mergeCoverage(maps: readonly CoverageMap[]): CoverageMap {
+  const byFile = new Map<string, FileCoverage[]>();
+  for (const map of maps) {
+    for (const [file, coverage] of Object.entries(map)) {
+      const list = byFile.get(file) ?? [];
+      list.push(coverage);
+      byFile.set(file, list);
+    }
+  }
+  return Object.fromEntries(
+    [...byFile]
+      .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+      .map(([file, parts]) => [file, mergeFileCoverage(parts)]),
+  );
+}
+
+/** `hit / found` as a percentage to two decimals; nothing found is 0, never a pass over nothing. */
+export const percent = (hit: number, found: number): number =>
+  found === 0 ? 0 : Math.round((hit / found) * 10_000) / 100;
+
+/** `[1,2,3,7]` → `"1-3,7"`: a shard's facts ride in its `--json` document, so they are kept small. */
+export function encodeLines(lines: readonly number[]): string {
+  const sorted = [...lines].sort((a, b) => a - b);
+  const runs: string[] = [];
+  let start: number | undefined;
+  let last = 0;
+  const flush = (): void => {
+    if (start !== undefined) runs.push(start === last ? String(start) : `${start}-${last}`);
+  };
+  for (const line of sorted) {
+    if (start !== undefined && line === last + 1) {
+      last = line;
+      continue;
+    }
+    flush();
+    start = line;
+    last = line;
+  }
+  flush();
+  return runs.join(',');
+}
+
+/** The inverse of `encodeLines`; a run that does not parse is no lines, never a throw. */
+export function decodeLines(text: string): readonly number[] {
+  const lines: number[] = [];
+  for (const run of text.split(',')) {
+    const match = /^(\d+)(?:-(\d+))?$/.exec(run);
+    if (match === null) continue;
+    const from = Number(match[1]);
+    const to = match[2] === undefined ? from : Number(match[2]);
+    for (let line = from; line <= to && line - from < 1_000_000; line += 1) lines.push(line);
+  }
+  return lines;
+}
+
+/** A file's facts as they cross `--json`: hit runs, miss runs, `[funcsFound, funcsHit]`. */
+export type CoverageWire = Readonly<
+  Record<string, { readonly h: string; readonly m: string; readonly f: readonly [number, number] }>
+>;
+
+export const encodeCoverage = (map: CoverageMap): CoverageWire =>
+  Object.fromEntries(
+    Object.entries(map).map(([file, one]) => [
+      file,
+      { h: encodeLines(one.hit), m: encodeLines(one.miss), f: [one.funcsFound, one.funcsHit] },
+    ]),
+  );
+
+/** A part's `data.coverage.<step>` back into a map, or nothing when it is not one. */
+export function decodeCoverage(value: unknown): CoverageMap | undefined {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return undefined;
+  const out = new Map<string, FileCoverage>();
+  for (const [file, raw] of Object.entries(value)) {
+    if (typeof raw !== 'object' || raw === null) return undefined;
+    const { h, m, f } = raw as { h?: unknown; m?: unknown; f?: unknown };
+    if (typeof h !== 'string' || typeof m !== 'string' || !Array.isArray(f)) return undefined;
+    const [found, hit] = f as unknown[];
+    if (typeof found !== 'number' || typeof hit !== 'number') return undefined;
+    out.set(file, { hit: decodeLines(h), miss: decodeLines(m), funcsFound: found, funcsHit: hit });
+  }
+  return Object.fromEntries(out);
+}

package/src/coverage-source.ts

@@ -0,0 +1,136 @@
+// What counts as an app's OWN source for the coverage floor, and what a file no test loaded
+// weighs. Bun writes an lcov record only for a file something imported, so a module nothing
+// reaches is absent from both halves of the fraction — and makes the number BETTER.
+
+// why: Bun ships no path-joining primitive; `join` builds the host path to each source file.
+import { join } from 'node:path';
+import { maskLiterals, stripComments } from '@ultimat3/core';
+
+/** A test file, whatever its suite: `*.test.ts`, `*.contract.test.tsx`, … */
+export const TEST_FILE = /\.test\.[cm]?[jt]sx?$/;
+
+/** Index just past the balanced `{ … }` that starts at or after `from`. */
+function skipBalanced(text: string, from: number): number {
+  let depth = 0;
+  for (let i = from; i < text.length; i += 1) {
+    const ch = text[i];
+    if (ch === '{') depth += 1;
+    else if (ch === '}') {
+      depth -= 1;
+      if (depth === 0) return i + 1;
+    }
+  }
+  return text.length;
+}
+
+/**
+ * Index just past the `;` that ends a `type` alias — the first one at nesting depth zero.
+ *
+ * Depth matters and a naive scan gets it wrong: `type _A = Assert<[FactKeysOf<{ a: 1 }>] extends
+ * [Actor] ? true : false>;` contains a `{ … }` whose closing brace is NOT the end of the
+ * declaration, and matching braces there leaves `, ] extends [Actor] … >;` behind, which then
+ * reads as executable code.
+ */
+function endOfTypeAlias(text: string, from: number): number {
+  let depth = 0;
+  for (let i = from; i < text.length; i += 1) {
+    const ch = text[i];
+    if (ch === '{' || ch === '[' || ch === '(' || ch === '<') depth += 1;
+    else if (ch === '}' || ch === ']' || ch === ')' || ch === '>') depth -= 1;
+    else if (ch === ';' && depth <= 0) return i + 1;
+  }
+  return text.length;
+}
+
+/**
+ * Whether a file emits anything at RUNTIME, as opposed to a barrel or a types-only module.
+ *
+ * Load-bearing, not cosmetic: bun writes an lcov record only for a file that produced executable
+ * code, so a pure barrel and a types-only module are legitimately absent — while a real module
+ * nothing imported is absent for the opposite reason and must be reported.
+ * `packages/core/src/type-pins.ts` says it of itself: "This module emits nothing and exports
+ * nothing anybody imports."
+ *
+ * A regex cannot decide this. `metrics-types.ts` contains `(() => number)` in a TYPE position, so
+ * scanning for `=>` calls a types-only file executable. Hence a scanner: strip comments and
+ * re-export statements, then remove `interface` blocks by brace matching and `type` aliases to
+ * their depth-zero `;`, and ask whether anything is left.
+ *
+ * `declare module` and `declare global` are removed the same way, and for the same reason the
+ * `declare const` line exists: an ambient block emits nothing at runtime, so bun writes no lcov
+ * record for a file built only from one. Their bodies go with them — an augmentation's members
+ * are declarations whatever they look like. Without this, `matcher-surface.ts` (a
+ * `declare module 'bun:test'` and nothing else) read as executable and was reported as a real
+ * module no test imports, which is the opposite of what it is.
+ */
+export function hasExecutableCode(source: string): boolean {
+  let text = source
+    .replace(/\/\*[\s\S]*?\*\//g, '')
+    .replace(/^[ \t]*\/\/.*$/gm, '')
+    .replace(/^[ \t]*(?:import|export)\b[^;]*?from\s*'[^']*';[ \t]*$/gm, '')
+    .replace(/^[ \t]*import\s+type\b[^;]*;[ \t]*$/gm, '')
+    // `declare const x: T;` is ambient — it emits nothing, and `type-pins.ts` files are built
+    // almost entirely from them.
+    .replace(/^[ \t]*declare\s+(?:const|let|var|function|class)\b[^;]*;[ \t]*$/gm, '');
+
+  // Ambient blocks first: their bodies hold `interface` members that the loop below would strip
+  // individually, leaving a bare `declare module '…' { }` shell behind that reads as code.
+  for (;;) {
+    const ambient = /(?:^|\n)[ \t]*declare\s+(?:module\s+'[^']*'|global)\s*\{/.exec(text);
+    if (ambient === null) break;
+    const start = ambient.index + (ambient[0].startsWith('\n') ? 1 : 0);
+    text = text.slice(0, start) + text.slice(skipBalanced(text, text.indexOf('{', start)));
+  }
+
+  for (;;) {
+    const found = /(?:^|\n)[ \t]*(?:export\s+)?(?:declare\s+)?(interface|type)\s/.exec(text);
+    if (found === null) break;
+    const start = found.index + (found[0].startsWith('\n') ? 1 : 0);
+    const end =
+      found[1] === 'interface'
+        ? skipBalanced(text, text.indexOf('{', start))
+        : endOfTypeAlias(text, start);
+    text = text.slice(0, start) + text.slice(end);
+  }
+  return text.replace(/\s/g, '') !== '';
+}
+
+/**
+ * What a file with NO lcov record weighs, read off its source because nothing else knows: its
+ * non-blank, non-comment lines, and one function per `function` keyword or arrow (at least one —
+ * it has executable code, or it would not be asked). An estimate, deliberately on the heavy side
+ * of what Bun reports for a loaded file (1.34x over `examples/dummy`'s loaded sources,
+ * 2026-10-01): the only way to make it exact is to load the file from a test, which is the fix.
+ */
+export function unloadedWeight(source: string): { readonly lines: number; readonly funcs: number } {
+  const stripped = stripComments(source);
+  const lines = stripped.split('\n').filter((line) => line.trim() !== '').length;
+  const funcs = (maskLiterals(stripped).match(/\bfunction\b|=>/g) ?? []).length;
+  return { lines: Math.max(1, lines), funcs: Math.max(1, funcs) };
+}
+
+/** Never an app's own source, wherever it sits. */
+const NOT_SOURCE = /(?:^|\/)(?:node_modules|dist|build|\.x)\//;
+
+/**
+ * Every `.ts` / `.tsx` under the app's `apps/` and `packages/` that is its own source: not a
+ * test, not a declaration file, not installed or built output, and not excluded by `exclude`
+ * (globs relative to the app root). Sorted, so two runs of one tree read one list.
+ */
+export function appSourceFiles(root: string, exclude: readonly string[] = []): readonly string[] {
+  const globs = exclude.map((pattern) => new Bun.Glob(pattern));
+  const files: string[] = [];
+  for (const rel of new Bun.Glob('{apps,packages}/**/*.{ts,tsx}').scanSync({ cwd: root })) {
+    const path = rel.split('\\').join('/');
+    if (NOT_SOURCE.test(path) || TEST_FILE.test(path) || path.endsWith('.d.ts')) continue;
+    if (globs.some((glob) => glob.match(path))) continue;
+    files.push(path);
+  }
+  return files.sort();
+}
+
+/** The source text of `rel` under `root`, or nothing when it cannot be read. */
+export const readSource = (root: string, rel: string): Promise<string | undefined> =>
+  Bun.file(join(root, rel))
+    .text()
+    .catch(() => undefined);

package/src/db-object-drift.ts

@@ -0,0 +1,30 @@
+// `x db migrate`'s second look at the database it just migrated: does it hold a trigger, function,
+// view, type or sequence that replaying the migrations does not create? `runMigrations` compares
+// tables against the snapshot and closes its connection; a snapshot records only what entities
+// declare, so everything else is asked here, against the catalog the schema dump was rendered from.
+
+import type { DriftDifference } from '@ultimat3/db';
+import type { CatalogDescription } from '@ultimat3/db/schema-dump';
+import { introspectCatalog, unexpectedObjects } from '@ultimat3/db/schema-dump';
+import { resolveServices } from './runtime-bindings';
+import { startQueue } from './runtime-queue';
+
+type Env = Readonly<Record<string, string | undefined>>;
+
+/**
+ * The same boot `runMigrations` used, reopened: that function is `serve.ts`'s and is deliberately
+ * not wrapped, so the connection it held is gone by the time its report is in hand. Reopening an
+ * embedded database is a fraction of a second; `x db migrate` is not a hot path.
+ */
+export async function liveObjectDrift(
+  root: string,
+  env: Env,
+  expected: CatalogDescription,
+): Promise<readonly DriftDifference[]> {
+  const queue = await startQueue(resolveServices(root, env), undefined, env);
+  try {
+    return unexpectedObjects(await introspectCatalog({ client: queue.db }), expected);
+  } finally {
+    await queue.stop();
+  }
+}

package/src/db-replay-engine.ts

@@ -0,0 +1,115 @@
+// Which database the schema dump is replayed on, and that database, opened and thrown away. ONE
+// rule: the embedded database, unless the migrations create an extension it cannot link — then a
+// real Postgres, in a database this module creates and drops. Decided from the migrations and the
+// installed PGlite alone, never from which URL happens to be set, so a laptop and CI choose alike.
+
+// why: Bun ships no path joiner.
+import { join } from 'node:path';
+import type { DbClient, LinkedExtensions, Migration } from '@ultimat3/db';
+import {
+  createPgliteClient,
+  createPostgresClient,
+  DbError,
+  linkPgliteExtensions,
+  raw,
+} from '@ultimat3/db';
+import { migrationExtensions } from './migration-extensions';
+
+type Env = Readonly<Record<string, string | undefined>>;
+
+/**
+ * Where a real Postgres is looked for, in order — the admin URL `@ultimat3/testing` already
+ * clones its template databases from (`template-db.ts`), so a CI that runs the `live` suite has
+ * it set and nothing new to configure.
+ */
+export const REPLAY_URL_ENVS = ['TEST_DATABASE_URL', 'DATABASE_URL'] as const;
+
+export type ReplayEngine =
+  | { readonly kind: 'embedded'; readonly extensions: readonly string[] }
+  | {
+      readonly kind: 'postgres';
+      readonly adminUrl: string;
+      /** The extensions that forced it, for the finding a missing URL becomes. */
+      readonly requires: readonly string[];
+    };
+
+/**
+ * The migrations need a server and none is named. `X_SCHEMA_DUMP_DRIFT`, because the dump cannot
+ * be produced or held; the cause names the extension, the fix the variable and the command.
+ */
+export function replayServerMissing(requires: readonly string[]): DbError {
+  const named = requires.map((name) => `"${name}"`).join(', ');
+  return new DbError({
+    code: 'X_SCHEMA_DUMP_DRIFT',
+    cause: `the migrations create extension ${named}, which the embedded database cannot link, so the schema dump is replayed on a real Postgres — and neither ${REPLAY_URL_ENVS.join(' nor ')} names one`,
+    fix: `${REPLAY_URL_ENVS[0]}=postgres://<user>:<password>@localhost:5432/postgres x db gen   # a server with that extension installed, and a role that may create a database`,
+    meta: { kind: 'engine-unavailable', extensions: [...requires] },
+  });
+}
+
+export type ExtensionLinker = (names: readonly string[]) => Promise<LinkedExtensions>;
+
+/** The rule. Throws `replayServerMissing` when it selects a server nobody named. */
+export async function chooseReplayEngine(
+  migrations: readonly Migration[],
+  env: Env,
+  link: ExtensionLinker = linkPgliteExtensions,
+): Promise<ReplayEngine> {
+  const extensions = migrationExtensions(migrations);
+  const { missing } = await link(extensions);
+  if (missing.length === 0) return { kind: 'embedded', extensions };
+  const adminUrl = REPLAY_URL_ENVS.map((name) => env[name]).find(
+    (value) => value !== undefined && value.length > 0,
+  );
+  if (adminUrl === undefined) throw replayServerMissing(missing);
+  return { kind: 'postgres', adminUrl, requires: missing };
+}
+
+/** Unique per call: two `x db gen` runs against one server must not share a scratch database. */
+const scratchName = (): string => `x_schema_dump_${process.pid}_${crypto.randomUUID().slice(0, 8)}`;
+
+async function withPostgresScratch<T>(
+  adminUrl: string,
+  work: (client: DbClient) => Promise<T>,
+): Promise<T> {
+  const database = scratchName();
+  const admin = createPostgresClient({ url: adminUrl });
+  try {
+    // `template0`: the server's `template1` may carry objects an operator put there, and they
+    // would be dumped as the app's.
+    await admin.execute(raw(`create database ${database} template template0`));
+    const target = new URL(adminUrl);
+    target.pathname = `/${database}`;
+    const client = createPostgresClient({ url: target.toString() });
+    try {
+      return await work(client);
+    } finally {
+      await client.close();
+      await admin.execute(raw(`drop database if exists ${database} with (force)`));
+    }
+  } finally {
+    await admin.close();
+  }
+}
+
+/**
+ * Run `work` against an empty scratch database on `engine`, and release it. The embedded one
+ * boots from the snapshot cache under `stateDir`, so only the first boot per PGlite version runs
+ * `initdb`.
+ */
+export async function withScratchDatabase<T>(
+  engine: ReplayEngine,
+  stateDir: string | undefined,
+  work: (client: DbClient) => Promise<T>,
+): Promise<T> {
+  if (engine.kind === 'postgres') return withPostgresScratch(engine.adminUrl, work);
+  const client = createPgliteClient({
+    extensions: engine.extensions,
+    ...(stateDir === undefined ? {} : { snapshotDir: join(stateDir, 'cache') }),
+  });
+  try {
+    return await work(client);
+  } finally {
+    await client.close();
+  }
+}

package/src/db-schema-dump.ts

@@ -0,0 +1,150 @@
+// The app's schema dump — `packages/db/schema/` — produced, read and written. ONE producer: a
+// scratch database (`db-replay-engine.ts` says which) with the framework's tables applied and
+// every migration replayed, never the developer's own database. `x db gen`, `x db migrate` and the `drift` step all call it,
+// so the bytes the gate compares against are the bytes the commands wrote, on one engine.
+
+// why: Bun has no directory probe — `Bun.file().exists()` answers about a file.
+import { existsSync } from 'node:fs';
+// why: Bun ships no path joiner.
+import { join } from 'node:path';
+import type { Migration } from '@ultimat3/db';
+import { migrate, raw } from '@ultimat3/db';
+import type {
+  CatalogDescription,
+  SchemaDumpDifference,
+  SchemaDumpFile,
+} from '@ultimat3/db/schema-dump';
+import {
+  introspectCatalog,
+  loadSchemaDump,
+  reloadDifferences,
+  renderSchemaDump,
+  schemaDumpDifferenceOf,
+} from '@ultimat3/db/schema-dump';
+import { chooseReplayEngine, withScratchDatabase } from './db-replay-engine';
+import { applyFrameworkSchema } from './framework-schema';
+import { resolveServices } from './runtime-bindings';
+
+/** Where the dump lives. App-root-relative, POSIX — beside `MIGRATIONS_DIR`, its one source. */
+export const SCHEMA_DUMP_DIR = 'packages/db/schema';
+
+export interface ReplayedSchema {
+  readonly catalog: CatalogDescription;
+  readonly files: readonly SchemaDumpFile[];
+  /** Empty when a database loaded from `files` renders `files` again. Always empty without `reload`. */
+  readonly reload: readonly SchemaDumpDifference[];
+}
+
+export interface ReplayOptions {
+  /** Also prove load equals replay: reset the schema, load the dump, render it again. */
+  readonly reload?: boolean | undefined;
+  /** The app's state directory (`.x/`), where the embedded scratch boot keeps its snapshot. */
+  readonly stateDir?: string | undefined;
+  /** Read for the server URL when the migrations cannot replay on the embedded database. */
+  readonly env?: Readonly<Record<string, string | undefined>> | undefined;
+}
+
+/**
+ * Framework tables first, then every migration — the order every real boot runs them in
+ * (`startQueue`, then `migrate`), so a migration's foreign key into `x_users` finds its target.
+ * The client is handed to each call and never installed as the ambient `db()`: this runs inside
+ * `x verify`, beside steps that own that accessor.
+ *
+ * The reload reuses the SAME database, emptied — a second scratch database is a second boot for a
+ * question `drop schema … cascade` answers as well. It is asked only of a dump that claims to be
+ * whole: one that lists objects in `unrendered.sql` has already said a database loaded from it is
+ * not the migrated one.
+ */
+export async function replaySchema(
+  migrations: readonly Migration[],
+  options: ReplayOptions = {},
+): Promise<ReplayedSchema> {
+  const engine = await chooseReplayEngine(migrations, options.env ?? Bun.env);
+  return withScratchDatabase(engine, options.stateDir, async (client) => {
+    await applyFrameworkSchema((statement) => client.execute(raw(statement)));
+    await migrate({ migrations, client });
+    const catalog = await introspectCatalog({ client });
+    const files = renderSchemaDump(catalog);
+    if (options.reload !== true || catalog.unrendered.length > 0) {
+      return { catalog, files, reload: [] };
+    }
+    await client.execute(raw('drop schema public cascade'));
+    await client.execute(raw('create schema public'));
+    try {
+      await loadSchemaDump({ client, files });
+    } catch (error) {
+      // A refusal to load is a verdict about the dump, not a failed replay: reported as the
+      // difference it is, so the caller's finding names the file rather than the engine.
+      const refused = schemaDumpDifferenceOf(error);
+      if (refused === undefined) throw error;
+      return { catalog, files, reload: [refused] };
+    }
+    const reloaded = renderSchemaDump(await introspectCatalog({ client }));
+    return { catalog, files, reload: reloadDifferences(files, reloaded) };
+  });
+}
+
+/** The replay for an app on disk: its own state directory, its command's environment. */
+export const replayFor = (
+  root: string,
+  env: Readonly<Record<string, string | undefined>>,
+  reload: boolean,
+): ((migrations: readonly Migration[]) => Promise<ReplayedSchema>) => {
+  return (migrations) =>
+    replaySchema(migrations, { reload, env, stateDir: resolveServices(root, env).stateDir });
+};
+
+export const hasSchemaDump = (root: string): boolean => existsSync(join(root, SCHEMA_DUMP_DIR));
+
+/** Every `.sql` under the dump directory, sorted by path — the shape `renderSchemaDump` answers in. */
+export async function readSchemaDump(root: string): Promise<readonly SchemaDumpFile[]> {
+  const dir = join(root, SCHEMA_DUMP_DIR);
+  if (!existsSync(dir)) return [];
+  const paths: string[] = [];
+  for await (const path of new Bun.Glob('**/*.sql').scan({ cwd: dir })) {
+    paths.push(path.replaceAll('\\', '/'));
+  }
+  paths.sort();
+  const files: SchemaDumpFile[] = [];
+  for (const path of paths) {
+    files.push({ path, content: await Bun.file(join(dir, path)).text() });
+  }
+  return files;
+}
+
+export interface SchemaDumpWrite {
+  /** App-root-relative paths whose bytes this call changed or created. */
+  readonly written: readonly string[];
+  /** Files the dump no longer produces, deleted. */
+  readonly removed: readonly string[];
+  /** Every file the dump holds after the write. */
+  readonly total: number;
+}
+
+/**
+ * Make the directory equal to `files`: write what differs, delete what nothing renders. A file
+ * whose bytes already match is left untouched, so an unchanged table keeps its mtime and a
+ * one-table migration is a one-file write.
+ */
+export async function writeSchemaDump(
+  root: string,
+  files: readonly SchemaDumpFile[],
+): Promise<SchemaDumpWrite> {
+  const dir = join(root, SCHEMA_DUMP_DIR);
+  const held = new Map((await readSchemaDump(root)).map((file) => [file.path, file.content]));
+  const written: string[] = [];
+  for (const file of files) {
+    if (held.get(file.path) === file.content) continue;
+    // `createPath` is Bun's default, spelled: a kind directory may not exist yet.
+    await Bun.write(join(dir, file.path), file.content, { createPath: true });
+    written.push(`${SCHEMA_DUMP_DIR}/${file.path}`);
+  }
+  const rendered = new Set(files.map((file) => file.path));
+  const removed: string[] = [];
+  for (const path of held.keys()) {
+    if (rendered.has(path)) continue;
+    await Bun.file(join(dir, path)).delete();
+    removed.push(`${SCHEMA_DUMP_DIR}/${path}`);
+  }
+  return { written, removed, total: files.length };
+}