@softure-ai/db 0.1.5 → 0.1.7

package/src/migrations/migrator.ts

@@ -2,21 +2,20 @@
 // module's own schema, dependencies first, one transaction per file together with its ledger row.
 // Everything that can be checked (names, numbering, checksums, order) is checked for all modules
 // before the first file runs, so a problem in one module never leaves another half-migrated.
+// The app's own migrations (drizzle's, usually) plug in through `app.before` / `app.after`, and
+// `app.baseline` names the module files the app's own history already creates (issue #152).
 import { ok, sortModulesByDependencies, type AnySoftureModule } from "@softure-ai/core";
 import type { DatabaseHandle } from "../client.js";
-import { readMigrationFiles, type MigrationFile } from "./files.js";
-import {
-  LEDGER_FILES,
-  LEDGER_MODULE_ID,
-  LEDGER_SCHEMA,
-  LEDGER_VERSION,
-  readJournal,
-  recordMigration,
-  type JournalRow,
-  type MigrationMethod,
-} from "./ledger.js";
+import { applyFile, describeError, recordAdoption, withMigrationLock, type MigrationUnit } from "./apply.js";
+import { readMigrationFiles } from "./files.js";
+import { describeSchema, diffSchemas } from "./introspect.js";
+import { LEDGER_FILES, LEDGER_MODULE_ID, LEDGER_SCHEMA, LEDGER_VERSION, readJournal, type JournalRow } from "./ledger.js";
 import { failWith, type MigrationProblem, type MigrationResult } from "./problems.js";
+import { buildReferenceSchema, listOwnedSchemas } from "./reference.js";
 import { withSession, type MigrationSession } from "./session.js";
+import { readAppTables } from "./stubs.js";
+
+export { applyFile, recordAdoption, rollBack, withMigrationLock, type MigrationUnit } from "./apply.js";
 
 export interface MigrateOptions {
   /** The enabled modules, in any order; dependencies are applied first. */
@@ -28,8 +27,40 @@ export interface MigrateOptions {
   readonly migrationsDir?: URL;
   /** Called after each file is committed, e.g. to print progress. */
   readonly onApplied?: (step: MigrationStep) => void;
+  /** Called after each file a baseline recorded as adopted, e.g. to print progress. */
+  readonly onAdopted?: (step: MigrationStep) => void;
+  /**
+   * The app's own migrations around the module files, and its baseline. `planMigrations` runs no
+   * hook; it reads only the baseline.
+   */
+  readonly app?: AppMigrations;
+  /** Called after an app hook succeeded, e.g. to print progress. */
+  readonly onAppMigrated?: (phase: AppMigrationPhase) => void;
 }
 
+/**
+ * The app's own migration runner, called by `migrate` under the migration lock on every run (it
+ * must skip what it already applied, as drizzle's migrator does). A throw or rejection is reported
+ * as `db.app_migration_failed`.
+ */
+export type AppMigrationHook = (handle: DatabaseHandle) => Promise<void>;
+
+export interface AppMigrations {
+  /** Runs before the module files: app tables that module SQL references (normally the app's whole history). */
+  readonly before?: AppMigrationHook;
+  /** Runs after the module files: app migrations that reference tables a module creates. */
+  readonly after?: AppMigrationHook;
+  /**
+   * The module files the app's own history already creates: module id → the last such file (1..n).
+   * For a listed module the ledger has never seen, `migrate` compares the module's schema with
+   * files 1..n once `before` ran and records them as `adopted`, then applies the later files; an
+   * empty schema is migrated normally. Once the module is in the ledger the entry has no effect.
+   */
+  readonly baseline?: Readonly<Record<string, number>>;
+}
+
+export type AppMigrationPhase = "before" | "after";
+
 export interface MigrationStep {
   readonly module: string;
   readonly schema: string;
@@ -41,23 +72,23 @@ export interface MigrationStep {
 export interface MigrationPlan {
   /** What `migrate` would apply, in order. */
   readonly pending: readonly MigrationStep[];
+  /**
+   * The pending steps a baseline may adopt instead of applying: they are adopted when the module's
+   * schema already holds objects after `before` (which a plan does not run).
+   */
+  readonly baseline: readonly MigrationStep[];
 }
 
 export interface MigrationReport {
   readonly applied: readonly MigrationStep[];
+  /** The files a baseline recorded as adopted, in order. */
+  readonly adopted: readonly MigrationStep[];
+  /** The app hooks that ran, in order. */
+  readonly app: readonly AppMigrationPhase[];
 }
 
-/** One migration owner: the ledger itself or an enabled module with a schema. */
-export interface MigrationUnit {
-  readonly module: string;
-  readonly schema: string;
-  readonly moduleVersion: string;
-  readonly files: readonly MigrationFile[];
-}
-
-// Any constant works; it only has to be the same for every runner of every app.
-const MIGRATION_LOCK_KEY = "73012026";
-const RESERVED_SCHEMAS = new Set([LEDGER_SCHEMA, "public", "information_schema"]);
+// `drizzle` holds drizzle's own ledger (`drizzle.__drizzle_migrations`) in every app on this stack.
+const RESERVED_SCHEMAS = new Set([LEDGER_SCHEMA, "public", "information_schema", "drizzle"]);
 const MAX_IDENTIFIER_BYTES = 63;
 
 /** The dry run: what `migrate` would apply. Takes no lock and writes nothing. */
@@ -66,43 +97,222 @@ export async function planMigrations(handle: DatabaseHandle, options: MigrateOpt
   if (!units.ok) {
     return units;
   }
+  const baseline = options.app?.baseline ?? {};
+  const baselineProblems = checkBaseline(options.modules, units.value, baseline);
+  if (baselineProblems.length > 0) {
+    return failWith(baselineProblems);
+  }
   const journal = await withSession(handle, readJournal);
   const comparison = compareJournal(units.value, journal);
-  return comparison.problems.length > 0 ? failWith(comparison.problems) : ok({ pending: comparison.pending });
+  if (comparison.problems.length > 0) {
+    return failWith(comparison.problems);
+  }
+  const adoptable = comparison.pending.filter((step) => isBaselineStep(step, baseline, journal));
+  return ok({ pending: comparison.pending, baseline: adoptable });
 }
 
-/** Applies every pending migration under the advisory lock. */
+/**
+ * Applies every pending migration under the advisory lock: the ledger, `app.before`, the module
+ * files (adopting a baseline where it applies), then `app.after`. Nothing runs when a check fails.
+ */
 export async function migrate(handle: DatabaseHandle, options: MigrateOptions): Promise<MigrationResult<MigrationReport>> {
   const units = await prepareUnits(options.modules, options.migrationsDir);
   if (!units.ok) {
     return units;
   }
+  const app = options.app ?? {};
+  const baseline = app.baseline ?? {};
+  const baselineProblems = checkBaseline(options.modules, units.value, baseline);
+  if (baselineProblems.length > 0) {
+    return failWith(baselineProblems);
+  }
   return withSession(handle, (session) =>
     withMigrationLock(session, async () => {
       // Read after the lock: a runner that waited sees what the first one applied.
-      const comparison = compareJournal(units.value, await readJournal(session));
+      const journal = await readJournal(session);
+      const comparison = compareJournal(units.value, journal);
       if (comparison.problems.length > 0) {
         return failWith(comparison.problems);
       }
       const applied: MigrationStep[] = [];
-      for (const step of comparison.pending) {
-        const unit = units.value.find((candidate) => candidate.module === step.module);
-        const file = unit?.files.find((candidate) => candidate.version === step.version);
-        if (unit === undefined || file === undefined) {
-          throw new Error(`migrate: step ${step.module} ${step.version} has no file; compareJournal is broken`);
+      const adopted: MigrationStep[] = [];
+      const ranHooks: AppMigrationPhase[] = [];
+      const applySteps = async (steps: readonly MigrationStep[]): Promise<MigrationProblem | null> => {
+        for (const step of steps) {
+          const { unit, file } = findFile(units.value, step);
+          const failure = await applyFile(session, { unit, file, method: "applied" });
+          if (failure !== null) {
+            return failure;
+          }
+          applied.push(step);
+          options.onApplied?.(step);
         }
-        const failure = await applyFile(session, { unit, file, method: "applied" });
-        if (failure !== null) {
-          return failWith([failure]);
+        return null;
+      };
+      const runHook = async (phase: AppMigrationPhase): Promise<MigrationProblem | null> => {
+        const failure = await runAppHook(handle, app, phase);
+        if (failure === null && app[phase] !== undefined) {
+          ranHooks.push(phase);
+          options.onAppMigrated?.(phase);
         }
-        applied.push(step);
-        options.onApplied?.(step);
+        return failure;
+      };
+      // Unit by unit in dependency order, so a module's dependencies are migrated before its
+      // baseline is compared.
+      const migrateModules = async (): Promise<MigrationProblem | null> => {
+        for (const unit of units.value) {
+          if (unit.module === LEDGER_MODULE_ID) continue;
+          const steps = comparison.pending.filter((step) => step.module === unit.module);
+          const through = baseline[unit.module];
+          if (through === undefined || journal.some((row) => row.module === unit.module)) {
+            const failure = await applySteps(steps);
+            if (failure !== null) return failure;
+            continue;
+          }
+          const adoption = await adoptBaseline(session, { modules: options.modules, units: units.value, unit, through });
+          if (adoption.problem !== null) return adoption.problem;
+          for (const step of adoption.adopted) {
+            adopted.push(step);
+            options.onAdopted?.(step);
+          }
+          const failure = await applySteps(steps.filter((step) => !adoption.adopted.some((done) => done.version === step.version)));
+          if (failure !== null) return failure;
+        }
+        return null;
+      };
+
+      // The ledger first, so it exists whatever a hook does; then before, the modules, after.
+      const ledgerSteps = comparison.pending.filter((step) => step.module === LEDGER_MODULE_ID);
+      const failure = (await applySteps(ledgerSteps)) ?? (await runHook("before")) ?? (await migrateModules()) ?? (await runHook("after"));
+      if (failure !== null) {
+        return failWith([failure]);
       }
-      return ok({ applied });
+      return ok({ applied, adopted, app: ranHooks });
     }),
   );
 }
 
+/**
+ * Adopt-or-migrate for a baseline module the ledger has never seen: an empty schema adopts
+ * nothing (its files are then applied normally); otherwise the schema must equal files 1..through,
+ * which are then recorded as adopted in one transaction.
+ */
+async function adoptBaseline(
+  session: MigrationSession,
+  input: { modules: readonly AnySoftureModule[]; units: readonly MigrationUnit[]; unit: MigrationUnit; through: number },
+): Promise<{ adopted: MigrationStep[]; problem: MigrationProblem | null }> {
+  const { unit, through } = input;
+  const live = await describeSchema(session, unit.schema);
+  if (live.length === 0) {
+    return { adopted: [], problem: null };
+  }
+  // Built only here, so a database whose modules are all in the ledger never needs PGlite. The app's
+  // tables exist by now (`before` ran), so module SQL that references them finds their stubs.
+  const appTables = await readAppTables(session, listOwnedSchemas(input.units));
+  const reference = await buildReferenceSchema({ modules: input.modules, units: input.units, target: unit, through, appTables });
+  if (!reference.ok) {
+    return { adopted: [], problem: reference.problems[0] ?? null };
+  }
+  const differences = diffSchemas(reference.value, live);
+  if (differences.length > 0) {
+    return { adopted: [], problem: { code: "db.schema_mismatch", module: unit.module, schema: unit.schema, differences } };
+  }
+  const files = unit.files.filter((file) => file.version <= through);
+  const failure = await recordAdoption(session, unit, files);
+  if (failure !== null) {
+    return { adopted: [], problem: failure };
+  }
+  return { adopted: files.map((file) => toStep(unit, file)), problem: null };
+}
+
+/**
+ * A baseline may name only enabled modules with a schema and migrations, and a last file between
+ * 1 and the module's file count. Checked before anything runs.
+ */
+function checkBaseline(
+  modules: readonly AnySoftureModule[],
+  units: readonly MigrationUnit[],
+  baseline: Readonly<Record<string, number>>,
+): MigrationProblem[] {
+  return Object.entries(baseline).flatMap(([module, through]): MigrationProblem[] => {
+    if (!modules.some((candidate) => candidate.id === module)) {
+      return [{ code: "db.adopt_unknown_module", module }];
+    }
+    const unit = units.find((candidate) => candidate.module === module);
+    if (unit === undefined) {
+      return [{ code: "db.adopt_no_schema", module }];
+    }
+    return checkThrough(unit, through);
+  });
+}
+
+/** `through` must be a whole number from 1 to the unit's file count. */
+export function checkThrough(unit: MigrationUnit, through: number): MigrationProblem[] {
+  const files = unit.files.length;
+  return Number.isInteger(through) && through >= 1 && through <= files
+    ? []
+    : [{ code: "db.adopt_through_out_of_range", module: unit.module, through, files }];
+}
+
+function isBaselineStep(step: MigrationStep, baseline: Readonly<Record<string, number>>, journal: readonly JournalRow[]): boolean {
+  const through = baseline[step.module];
+  return through !== undefined && step.version <= through && !journal.some((row) => row.module === step.module);
+}
+
+function findFile(units: readonly MigrationUnit[], step: MigrationStep): { unit: MigrationUnit; file: MigrationUnit["files"][number] } {
+  const unit = units.find((candidate) => candidate.module === step.module);
+  const file = unit?.files.find((candidate) => candidate.version === step.version);
+  if (unit === undefined || file === undefined) {
+    throw new Error(`migrate: step ${step.module} ${step.version} has no file; compareJournal is broken`);
+  }
+  return { unit, file };
+}
+
+export function toStep(unit: MigrationUnit, file: MigrationUnit["files"][number]): MigrationStep {
+  return { module: unit.module, schema: unit.schema, version: file.version, name: file.name, checksum: file.checksum };
+}
+
+/**
+ * Runs one app hook alone under the migration lock (the CLI's `--adopt` runs `before` first, so the
+ * app migration that moves a table and the adoption are one command). Ok when there is no hook.
+ */
+export async function runAppMigrations(
+  handle: DatabaseHandle,
+  app: AppMigrations,
+  phase: AppMigrationPhase,
+): Promise<MigrationResult<{ ran: boolean }>> {
+  if (app[phase] === undefined) {
+    return ok({ ran: false });
+  }
+  const failure = await withSession(handle, (session) => withMigrationLock(session, () => runAppHook(handle, app, phase)));
+  return failure === null ? ok({ ran: true }) : failWith([failure]);
+}
+
+async function runAppHook(handle: DatabaseHandle, app: AppMigrations, phase: AppMigrationPhase): Promise<MigrationProblem | null> {
+  const hook = app[phase];
+  if (hook === undefined) {
+    return null;
+  }
+  try {
+    await hook(handle);
+    return null;
+  } catch (error) {
+    return { code: "db.app_migration_failed", phase, reason: describeErrorChain(error) };
+  }
+}
+
+// drizzle wraps the database error (`Failed query: <sql>`, the Postgres message in `cause`), so the
+// whole chain is the reason.
+function describeErrorChain(error: unknown): string {
+  const messages: string[] = [];
+  let current: unknown = error;
+  while (current !== undefined && current !== null && messages.length < 5) {
+    messages.push(describeError(current));
+    current = current instanceof Error ? current.cause : undefined;
+  }
+  return messages.join(": ");
+}
+
 /**
  * Validates the module list and reads every file: the ledger first, then the modules with a
  * schema in dependency order. Fails with every problem found.
@@ -173,90 +383,6 @@ export function compareJournal(
   return { problems, pending };
 }
 
-/**
- * Runs one file and its ledger row in one transaction, inside the unit's schema. Returns the
- * problem when the SQL fails; the transaction is rolled back first.
- */
-export async function applyFile(
-  session: MigrationSession,
-  input: { unit: MigrationUnit; file: MigrationFile; method: MigrationMethod },
-): Promise<MigrationProblem | null> {
-  const { unit, file, method } = input;
-  // The schema passed the manifest's lower_snake_case rule and checkModule; quoting is a second line.
-  const schema = quoteIdentifier(unit.schema);
-  try {
-    await session.exec(`BEGIN; CREATE SCHEMA IF NOT EXISTS ${schema}; SET LOCAL search_path TO ${schema}, public;`);
-    const transactionId = await readTransactionId(session);
-    if (method === "applied") {
-      await session.exec(file.sql);
-    }
-    // Second line behind findTransactionControl: a file that still ended the transaction left
-    // part of itself committed, so it must not be reported as cleanly rolled back.
-    if ((await readTransactionId(session)) !== transactionId) {
-      throw new TransactionEndedError();
-    }
-    await recordMigration(session, {
-      module: unit.module,
-      version: file.version,
-      name: file.name,
-      checksum: file.checksum,
-      moduleVersion: unit.moduleVersion,
-      method,
-    });
-    await session.exec("COMMIT");
-    return null;
-  } catch (error) {
-    const reason = await rollBack(session, error);
-    return { code: "db.migration_failed", module: unit.module, version: file.version, name: file.name, reason };
-  }
-}
-
-class TransactionEndedError extends Error {
-  constructor() {
-    super("the file ended the migrator's transaction, so the statements before that point may be committed; check the schema by hand");
-  }
-}
-
-// The transaction id, not now(): two transactions can share a start time (PGlite's clock ticks in
-// milliseconds), but never an id.
-async function readTransactionId(session: MigrationSession): Promise<string> {
-  const [row] = await session.query<{ id: string }>("SELECT pg_current_xact_id()::text AS id");
-  return row?.id ?? "";
-}
-
-/**
- * Rolls the open transaction back and returns the reason to report. A failing ROLLBACK (a lost
- * connection) is added to the reason instead of hiding the original error.
- */
-export async function rollBack(session: MigrationSession, error: unknown): Promise<string> {
-  const reason = describeError(error);
-  try {
-    await session.exec("ROLLBACK");
-    return reason;
-  } catch (rollbackError) {
-    return `${reason} (and ROLLBACK failed: ${describeError(rollbackError)})`;
-  }
-}
-
-/** Holds the session-level advisory lock while `run` runs; a second runner waits for it. */
-export async function withMigrationLock<T>(session: MigrationSession, run: () => Promise<T>): Promise<T> {
-  await session.query("SELECT pg_advisory_lock($1)", [MIGRATION_LOCK_KEY]);
-  let result: T;
-  try {
-    result = await run();
-  } catch (error) {
-    // The run's own error wins; an unlock failure here is secondary (the session is discarded).
-    await session.query("SELECT pg_advisory_unlock($1)", [MIGRATION_LOCK_KEY]).catch((unlockError: unknown) => {
-      throw new Error(`migration run failed (${describeError(error)}) and releasing the lock failed: ${describeError(unlockError)}`, {
-        cause: error,
-      });
-    });
-    throw error;
-  }
-  await session.query("SELECT pg_advisory_unlock($1)", [MIGRATION_LOCK_KEY]);
-  return result;
-}
-
 function checkModule(module: AnySoftureModule): MigrationProblem[] {
   const schema = module.manifest.dbSchema;
   if (module.id === LEDGER_MODULE_ID || (schema !== null && isReservedSchema(schema))) {
@@ -272,14 +398,6 @@ function isReservedSchema(schema: string): boolean {
   return RESERVED_SCHEMAS.has(schema) || schema.startsWith("pg_") || Buffer.byteLength(schema, "utf8") > MAX_IDENTIFIER_BYTES;
 }
 
-function quoteIdentifier(name: string): string {
-  return `"${name.replace(/"/g, '""')}"`;
-}
-
 function ensureFolderUrl(url: URL): URL {
   return url.href.endsWith("/") ? url : new URL(`${url.href}/`);
 }
-
-function describeError(error: unknown): string {
-  return error instanceof Error ? error.message : String(error);
-}

package/src/migrations/problems.ts

@@ -1,6 +1,6 @@
 // Every expected migration failure, as a value (AGENTS.md: expected failures are results). Each
-// problem names the module and file it is about; `describeProblem` turns it into the English line
-// the CLI prints and `createTestDatabase` throws.
+// problem names the module and file it is about (or the app's hook phase); `describeProblem` turns
+// it into the English line the CLI prints and `createTestDatabase` throws.
 import type { Err, Ok } from "@softure-ai/core";
 
 export type MigrationProblem =
@@ -10,6 +10,7 @@ export type MigrationProblem =
   | { readonly code: "db.migration_missing"; readonly module: string; readonly version: number; readonly name: string }
   | { readonly code: "db.migration_out_of_order"; readonly module: string; readonly version: number; readonly appliedVersion: number }
   | { readonly code: "db.migration_failed"; readonly module: string; readonly version: number; readonly name: string; readonly reason: string }
+  | { readonly code: "db.app_migration_failed"; readonly phase: "before" | "after"; readonly reason: string }
   | { readonly code: "db.reserved_module"; readonly module: string }
   | { readonly code: "db.migrations_without_schema"; readonly module: string }
   | { readonly code: "db.dependency_cycle"; readonly modules: readonly string[] }
@@ -18,6 +19,7 @@ export type MigrationProblem =
   | { readonly code: "db.adopt_already_applied"; readonly module: string }
   | { readonly code: "db.adopt_dependency_pending"; readonly module: string; readonly dependency: string }
   | { readonly code: "db.adopt_no_schema"; readonly module: string }
+  | { readonly code: "db.adopt_through_out_of_range"; readonly module: string; readonly through: number; readonly files: number }
   | { readonly code: "db.adopt_reference_failed"; readonly module: string; readonly reason: string }
   | { readonly code: "db.export_target_not_empty"; readonly module: string; readonly dir: string; readonly entries: readonly string[] }
   | { readonly code: "db.schema_mismatch"; readonly module: string; readonly schema: string; readonly differences: readonly string[] };
@@ -54,8 +56,12 @@ export function describeProblem(problem: MigrationProblem): string {
       return `${problem.module}: migration ${formatVersion(problem.version)} is pending but ${formatVersion(problem.appliedVersion)} is already applied`;
     case "db.migration_failed":
       return `${problem.module}: migration ${formatFile(problem.version, problem.name)} failed and was rolled back: ${problem.reason}`;
+    case "db.app_migration_failed":
+      return problem.phase === "before"
+        ? `app: the before migrations failed: ${problem.reason}; no module migration ran`
+        : `app: the after migrations failed: ${problem.reason}; the module migrations before it stay applied`;
     case "db.reserved_module":
-      return `${problem.module}: uses a reserved id or schema (the id "softure"; the schemas softure, public, information_schema, pg_* and names over 63 bytes)`;
+      return `${problem.module}: uses a reserved id or schema (the id "softure"; the schemas softure, public, information_schema, drizzle, pg_* and names over 63 bytes)`;
     case "db.migrations_without_schema":
       return `${problem.module}: has migrations but no dbSchema in its manifest`;
     case "db.dependency_cycle":
@@ -67,9 +73,11 @@ export function describeProblem(problem: MigrationProblem): string {
     case "db.adopt_already_applied":
       return `${problem.module}: already has migrations in the ledger; adopt only works on a module the ledger has never seen`;
     case "db.adopt_dependency_pending":
-      return `${problem.module}: depends on ${problem.dependency}, which has migrations still pending; migrate or adopt ${problem.dependency} first`;
+      return `${problem.module}: depends on ${problem.dependency}, whose pending migrations could not be applied (see above); adopt ${problem.dependency} first`;
     case "db.adopt_no_schema":
-      return `${problem.module}: has no dbSchema, so there is nothing to adopt`;
+      return `${problem.module}: has no dbSchema or no migrations, so there is nothing to adopt`;
+    case "db.adopt_through_out_of_range":
+      return `${problem.module}: cannot adopt through ${String(problem.through)}; it is the number of the last file to adopt, a whole number from 1 to ${problem.files}`;
     case "db.adopt_reference_failed":
       return `${problem.module}: could not build the reference schema: ${problem.reason}`;
     case "db.export_target_not_empty":

package/src/migrations/reference.ts

@@ -0,0 +1,78 @@
+// The reference schema for adoption: what a module's files 1..N create, built on a scratch
+// in-memory PGlite together with the modules it depends on (directly or not), because its SQL may
+// reference them. `adoptModule` and a baseline in `migrate` compare a live schema with it. Module
+// SQL may also reference the app's own tables; their stubs, copied from the live database
+// (`stubs.ts`), are created first (issue #170).
+import { ok, type AnySoftureModule } from "@softure-ai/core";
+import { createDatabase } from "../client.js";
+import { applyFile, type MigrationUnit } from "./apply.js";
+import { describeSchema } from "./introspect.js";
+import { LEDGER_MODULE_ID, LEDGER_SCHEMA } from "./ledger.js";
+import { failWith, type MigrationProblem, type MigrationResult } from "./problems.js";
+import { withSession } from "./session.js";
+import { createAppStubs, type AppCatalog } from "./stubs.js";
+
+// drizzle's ledger schema (`drizzle.__drizzle_migrations`): never an app table a module references.
+const APP_MIGRATOR_SCHEMA = "drizzle";
+
+export interface ReferenceInput {
+  /** The enabled modules, for the dependency graph. */
+  readonly modules: readonly AnySoftureModule[];
+  /** Their prepared units (`prepareUnits`), the ledger first, in dependency order. */
+  readonly units: readonly MigrationUnit[];
+  /** The module whose schema is described. */
+  readonly target: MigrationUnit;
+  /** The last file of the target to run; its dependencies run in full. */
+  readonly through: number;
+  /** Stubs of the app's tables (`readAppTables`), created before any file runs. */
+  readonly appTables?: AppCatalog;
+}
+
+/** Every line `describeSchema` prints for the target's schema after its files 1..through. */
+export async function buildReferenceSchema(input: ReferenceInput): Promise<MigrationResult<string[]>> {
+  const included = collectWithDependencies(input.modules, input.target.module);
+  const units = input.units
+    .filter((unit) => unit.module === LEDGER_MODULE_ID || included.has(unit.module))
+    .map((unit) => (unit.module === input.target.module ? { ...unit, files: unit.files.filter((file) => file.version <= input.through) } : unit));
+  const scratch = await createDatabase("pglite://");
+  try {
+    return await withSession(scratch, async (session) => {
+      const skipped = input.appTables === undefined ? [] : await createAppStubs(session, input.appTables);
+      for (const unit of units) {
+        for (const file of unit.files) {
+          const failure = await applyFile(session, { unit, file, method: "applied" });
+          if (failure !== null) {
+            const reason = describeFailure(failure) + (skipped.length > 0 ? ` (app table stubs skipped: ${skipped.join("; ")})` : "");
+            return failWith([{ code: "db.adopt_reference_failed", module: input.target.module, reason }]);
+          }
+        }
+      }
+      return ok(await describeSchema(session, input.target.schema));
+    });
+  } finally {
+    await scratch.close();
+  }
+}
+
+/** The schemas the migrator owns, which hold no app table: the ledger's, every unit's and drizzle's. */
+export function listOwnedSchemas(units: readonly MigrationUnit[]): string[] {
+  return [...new Set([LEDGER_SCHEMA, APP_MIGRATOR_SCHEMA, ...units.map((unit) => unit.schema)])];
+}
+
+/** The ids of the target and every enabled module it depends on, directly or not. */
+export function collectWithDependencies(modules: readonly AnySoftureModule[], target: string): Set<string> {
+  const byId = new Map(modules.map((module) => [module.id, module]));
+  const collected = new Set<string>();
+  const visit = (id: string): void => {
+    const module = byId.get(id);
+    if (module === undefined || collected.has(id)) return;
+    collected.add(id);
+    for (const dependency of Object.keys(module.manifest.dependsOn)) visit(dependency);
+  };
+  visit(target);
+  return collected;
+}
+
+function describeFailure(problem: MigrationProblem): string {
+  return problem.code === "db.migration_failed" ? `${problem.module} ${problem.name}: ${problem.reason}` : problem.code;
+}

package/src/migrations/session.ts

@@ -2,6 +2,8 @@
 // transaction and every statement of a run must share this connection (never `pool.query`).
 import type { DatabaseHandle } from "../client.js";
 
+type PgliteClient = Extract<DatabaseHandle, { kind: "pglite" }>["client"];
+
 export interface MigrationSession {
   /** A parameterised statement; returns its rows. */
   readonly query: <T>(text: string, params?: readonly unknown[]) => Promise<T[]>;
@@ -9,14 +11,23 @@ export interface MigrationSession {
   readonly exec: (sql: string) => Promise<void>;
 }
 
+interface SessionSetting {
+  readonly name: string;
+  readonly value: string;
+}
+
+const SESSION_SETTINGS_SQL = "SELECT name, current_setting(name) AS value FROM pg_settings WHERE source = 'session'";
+
 /**
  * Runs `run` on one dedicated connection. A pg client is destroyed afterwards instead of going
  * back to the pool, so a `SET` inside a migration file or a lock that failed to release cannot
- * leak into the app's queries. PGlite has one connection, so its settings are reset instead.
+ * leak into the app's queries. PGlite has one connection, shared with the app, so the settings the
+ * run changed are put back afterwards; the app's own (`TimeZone`, `search_path`) stay as they were.
  */
 export async function withSession<T>(handle: DatabaseHandle, run: (session: MigrationSession) => Promise<T>): Promise<T> {
   if (handle.kind === "pglite") {
     const { client } = handle;
+    const before = (await client.query<SessionSetting>(SESSION_SETTINGS_SQL)).rows;
     try {
       return await run({
         query: async <R>(text: string, params?: readonly unknown[]) => (await client.query<R>(text, params ? [...params] : undefined)).rows,
@@ -25,7 +36,7 @@ export async function withSession<T>(handle: DatabaseHandle, run: (session: Migr
         },
       });
     } finally {
-      await client.exec("RESET ALL");
+      await restoreSessionSettings(client, before);
     }
   }
 
@@ -46,3 +57,18 @@ export async function withSession<T>(handle: DatabaseHandle, run: (session: Migr
     client.off("error", ignoreClientError);
   }
 }
+
+/** Puts back every value in `before` (also one the run reset) and resets every session setting the run added. */
+async function restoreSessionSettings(client: PgliteClient, before: readonly SessionSetting[]): Promise<void> {
+  const after = new Map((await client.query<SessionSetting>(SESSION_SETTINGS_SQL)).rows.map((setting) => [setting.name, setting.value]));
+  for (const setting of before) {
+    if (after.get(setting.name) !== setting.value) {
+      await client.query("SELECT set_config($1, $2, false)", [setting.name, setting.value]);
+    }
+    after.delete(setting.name);
+  }
+  for (const name of after.keys()) {
+    // Names come from pg_settings, not from input; quoted as identifiers all the same.
+    await client.exec(`RESET "${name.replaceAll('"', '""')}"`);
+  }
+}