@softure-ai/db 0.1.5 → 0.1.6

package/dist/migrations/apply.d.ts

@@ -0,0 +1,35 @@
+import type { MigrationFile } from "./files.js";
+import { type MigrationMethod } from "./ledger.js";
+import type { MigrationProblem } from "./problems.js";
+import type { MigrationSession } from "./session.js";
+/** 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[];
+}
+/**
+ * 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 declare function applyFile(session: MigrationSession, input: {
+    unit: MigrationUnit;
+    file: MigrationFile;
+    method: MigrationMethod;
+}): Promise<MigrationProblem | null>;
+/**
+ * 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 declare function rollBack(session: MigrationSession, error: unknown): Promise<string>;
+/** Holds the session-level advisory lock while `run` runs; a second runner waits for it. */
+export declare function withMigrationLock<T>(session: MigrationSession, run: () => Promise<T>): Promise<T>;
+/**
+ * Records `files` of the unit as adopted, all in one transaction: either every row is written or
+ * none. Returns the problem when a write fails.
+ */
+export declare function recordAdoption(session: MigrationSession, unit: MigrationUnit, files: readonly MigrationFile[]): Promise<MigrationProblem | null>;
+export declare function quoteIdentifier(name: string): string;
+export declare function describeError(error: unknown): string;
+//# sourceMappingURL=apply.d.ts.map

package/dist/migrations/apply.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply.d.ts","sourceRoot":"","sources":["../../src/migrations/apply.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,EAAmB,KAAK,eAAe,EAAE,MAAM,aAAa,CAAC;AACpE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACtD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAErD,iFAAiF;AACjF,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,KAAK,EAAE,SAAS,aAAa,EAAE,CAAC;CAC1C;AAKD;;;GAGG;AACH,wBAAsB,SAAS,CAC7B,OAAO,EAAE,gBAAgB,EACzB,KAAK,EAAE;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,IAAI,EAAE,aAAa,CAAC;IAAC,MAAM,EAAE,eAAe,CAAA;CAAE,GAC3E,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CA6BlC;AAeD;;;GAGG;AACH,wBAAsB,QAAQ,CAAC,OAAO,EAAE,gBAAgB,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAQzF;AAED,4FAA4F;AAC5F,wBAAsB,iBAAiB,CAAC,CAAC,EAAE,OAAO,EAAE,gBAAgB,EAAE,GAAG,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAgBvG;AAED;;;GAGG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,gBAAgB,EAAE,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE,SAAS,aAAa,EAAE,GAAG,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAoBtJ;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEpD"}

package/dist/migrations/apply.js

@@ -0,0 +1,115 @@
+import { recordMigration } from "./ledger.js";
+// Any constant works; it only has to be the same for every runner of every app.
+const MIGRATION_LOCK_KEY = "73012026";
+/**
+ * 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, input) {
+    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) {
+    const [row] = await session.query("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, error) {
+    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(session, run) {
+    await session.query("SELECT pg_advisory_lock($1)", [MIGRATION_LOCK_KEY]);
+    let result;
+    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) => {
+            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;
+}
+/**
+ * Records `files` of the unit as adopted, all in one transaction: either every row is written or
+ * none. Returns the problem when a write fails.
+ */
+export async function recordAdoption(session, unit, files) {
+    try {
+        await session.exec("BEGIN");
+        for (const file of files) {
+            await recordMigration(session, {
+                module: unit.module,
+                version: file.version,
+                name: file.name,
+                checksum: file.checksum,
+                moduleVersion: unit.moduleVersion,
+                method: "adopted",
+            });
+        }
+        await session.exec("COMMIT");
+        return null;
+    }
+    catch (error) {
+        const reason = await rollBack(session, error);
+        const first = files[0];
+        return { code: "db.migration_failed", module: unit.module, version: first?.version ?? 0, name: first?.name ?? "", reason };
+    }
+}
+export function quoteIdentifier(name) {
+    return `"${name.replace(/"/g, '""')}"`;
+}
+export function describeError(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+//# sourceMappingURL=apply.js.map

package/dist/migrations/apply.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply.js","sourceRoot":"","sources":["../../src/migrations/apply.ts"],"names":[],"mappings":"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"}

package/dist/migrations/migrator.d.ts

@@ -1,9 +1,9 @@
 import { type AnySoftureModule } from "@softure-ai/core";
 import type { DatabaseHandle } from "../client.js";
-import { type MigrationFile } from "./files.js";
-import { type JournalRow, type MigrationMethod } from "./ledger.js";
+import { type MigrationUnit } from "./apply.js";
+import { type JournalRow } from "./ledger.js";
 import { type MigrationProblem, type MigrationResult } from "./problems.js";
-import { type MigrationSession } from "./session.js";
+export { applyFile, recordAdoption, rollBack, withMigrationLock, type MigrationUnit } from "./apply.js";
 export interface MigrateOptions {
     /** The enabled modules, in any order; dependencies are applied first. */
     readonly modules: readonly AnySoftureModule[];
@@ -14,7 +14,36 @@ 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;
@@ -25,21 +54,36 @@ 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[];
-}
-/** 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[];
+    /** The files a baseline recorded as adopted, in order. */
+    readonly adopted: readonly MigrationStep[];
+    /** The app hooks that ran, in order. */
+    readonly app: readonly AppMigrationPhase[];
 }
 /** The dry run: what `migrate` would apply. Takes no lock and writes nothing. */
 export declare function planMigrations(handle: DatabaseHandle, options: MigrateOptions): Promise<MigrationResult<MigrationPlan>>;
-/** 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 declare function migrate(handle: DatabaseHandle, options: MigrateOptions): Promise<MigrationResult<MigrationReport>>;
+/** `through` must be a whole number from 1 to the unit's file count. */
+export declare function checkThrough(unit: MigrationUnit, through: number): MigrationProblem[];
+export declare function toStep(unit: MigrationUnit, file: MigrationUnit["files"][number]): MigrationStep;
+/**
+ * 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 declare function runAppMigrations(handle: DatabaseHandle, app: AppMigrations, phase: AppMigrationPhase): Promise<MigrationResult<{
+    ran: boolean;
+}>>;
 /**
  * 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.
@@ -50,20 +94,4 @@ export declare function compareJournal(units: readonly MigrationUnit[], journal:
     problems: MigrationProblem[];
     pending: MigrationStep[];
 };
-/**
- * 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 declare function applyFile(session: MigrationSession, input: {
-    unit: MigrationUnit;
-    file: MigrationFile;
-    method: MigrationMethod;
-}): Promise<MigrationProblem | null>;
-/**
- * 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 declare function rollBack(session: MigrationSession, error: unknown): Promise<string>;
-/** Holds the session-level advisory lock while `run` runs; a second runner waits for it. */
-export declare function withMigrationLock<T>(session: MigrationSession, run: () => Promise<T>): Promise<T>;
 //# sourceMappingURL=migrator.d.ts.map

package/dist/migrations/migrator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"migrator.d.ts","sourceRoot":"","sources":["../../src/migrations/migrator.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"migrator.d.ts","sourceRoot":"","sources":["../../src/migrations/migrator.ts"],"names":[],"mappings":"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"}

package/dist/migrations/migrator.js

@@ -2,14 +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 } from "@softure-ai/core";
+import { applyFile, describeError, recordAdoption, withMigrationLock } from "./apply.js";
 import { readMigrationFiles } from "./files.js";
-import { LEDGER_FILES, LEDGER_MODULE_ID, LEDGER_SCHEMA, LEDGER_VERSION, readJournal, recordMigration, } from "./ledger.js";
+import { describeSchema, diffSchemas } from "./introspect.js";
+import { LEDGER_FILES, LEDGER_MODULE_ID, LEDGER_SCHEMA, LEDGER_VERSION, readJournal } from "./ledger.js";
 import { failWith } from "./problems.js";
+import { buildReferenceSchema, listOwnedSchemas } from "./reference.js";
 import { withSession } from "./session.js";
-// 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"]);
+import { readAppTables } from "./stubs.js";
+export { applyFile, recordAdoption, rollBack, withMigrationLock } from "./apply.js";
+// `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. */
 export async function planMigrations(handle, options) {
@@ -17,39 +23,202 @@ export async function planMigrations(handle, options) {
     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, options) {
     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 = [];
-        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 = [];
+        const ranHooks = [];
+        const applySteps = async (steps) => {
+            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);
+            }
+            return null;
+        };
+        const runHook = async (phase) => {
+            const failure = await runAppHook(handle, app, phase);
+            if (failure === null && app[phase] !== undefined) {
+                ranHooks.push(phase);
+                options.onAppMigrated?.(phase);
             }
-            const failure = await applyFile(session, { unit, file, method: "applied" });
-            if (failure !== null) {
-                return failWith([failure]);
+            return failure;
+        };
+        // Unit by unit in dependency order, so a module's dependencies are migrated before its
+        // baseline is compared.
+        const migrateModules = async () => {
+            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;
             }
-            applied.push(step);
-            options.onApplied?.(step);
+            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, input) {
+    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, units, baseline) {
+    return Object.entries(baseline).flatMap(([module, through]) => {
+        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, through) {
+    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, baseline, journal) {
+    const through = baseline[step.module];
+    return through !== undefined && step.version <= through && !journal.some((row) => row.module === step.module);
+}
+function findFile(units, step) {
+    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, file) {
+    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, app, phase) {
+    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, app, phase) {
+    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) {
+    const messages = [];
+    let current = 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.
@@ -113,85 +282,6 @@ export function compareJournal(units, journal) {
     }
     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, input) {
-    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) {
-    const [row] = await session.query("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, error) {
-    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(session, run) {
-    await session.query("SELECT pg_advisory_lock($1)", [MIGRATION_LOCK_KEY]);
-    let result;
-    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) => {
-            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) {
     const schema = module.manifest.dbSchema;
     if (module.id === LEDGER_MODULE_ID || (schema !== null && isReservedSchema(schema))) {
@@ -205,13 +295,7 @@ function checkModule(module) {
 function isReservedSchema(schema) {
     return RESERVED_SCHEMAS.has(schema) || schema.startsWith("pg_") || Buffer.byteLength(schema, "utf8") > MAX_IDENTIFIER_BYTES;
 }
-function quoteIdentifier(name) {
-    return `"${name.replace(/"/g, '""')}"`;
-}
 function ensureFolderUrl(url) {
     return url.href.endsWith("/") ? url : new URL(`${url.href}/`);
 }
-function describeError(error) {
-    return error instanceof Error ? error.message : String(error);
-}
 //# sourceMappingURL=migrator.js.map