@softure-ai/db 0.0.0-stage → 0.1.5

package/dist/migrations/introspect.js.map

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

package/dist/migrations/ledger.d.ts

@@ -0,0 +1,27 @@
+import { type MigrationFile } from "./files.js";
+import type { MigrationSession } from "./session.js";
+export declare const LEDGER_MODULE_ID = "softure";
+export declare const LEDGER_SCHEMA = "softure";
+/** The ledger's own format version, recorded as `module_version` of its rows. */
+export declare const LEDGER_VERSION = "1.0.0";
+export declare const LEDGER_FILES: readonly MigrationFile[];
+export type MigrationMethod = "applied" | "adopted";
+export interface JournalRow {
+    readonly module: string;
+    readonly version: number;
+    readonly name: string;
+    readonly checksum: string;
+    readonly method: MigrationMethod;
+}
+export interface LedgerEntry {
+    readonly module: string;
+    readonly version: number;
+    readonly name: string;
+    readonly checksum: string;
+    readonly moduleVersion: string;
+    readonly method: MigrationMethod;
+}
+/** Every ledger row, or none while the ledger table does not exist yet. */
+export declare function readJournal(session: MigrationSession): Promise<JournalRow[]>;
+export declare function recordMigration(session: MigrationSession, entry: LedgerEntry): Promise<void>;
+//# sourceMappingURL=ledger.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ledger.d.ts","sourceRoot":"","sources":["../../src/migrations/ledger.ts"],"names":[],"mappings":"AAOA,OAAO,EAAuB,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC;AACrE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAErD,eAAO,MAAM,gBAAgB,YAAY,CAAC;AAC1C,eAAO,MAAM,aAAa,YAAY,CAAC;AACvC,iFAAiF;AACjF,eAAO,MAAM,cAAc,UAAU,CAAC;AAwBtC,eAAO,MAAM,YAAY,EAAE,SAAS,aAAa,EAAwB,CAAC;AAE1E,MAAM,MAAM,eAAe,GAAG,SAAS,GAAG,SAAS,CAAC;AAEpD,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;CAClC;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;CAClC;AAED,2EAA2E;AAC3E,wBAAsB,WAAW,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAQlF;AAED,wBAAsB,eAAe,CAAC,OAAO,EAAE,gBAAgB,EAAE,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAKlG"}

package/dist/migrations/ledger.js

@@ -0,0 +1,45 @@
+// The migration ledger `softure.migrations` (docs/02-module-standard.md §4). It is owned by the
+// pseudo-module `softure` and created by its own migration, which ships as code so a bundled
+// runner needs no file for it. While the table does not exist the journal reads as empty, so the
+// first run bootstraps through the normal path.
+//
+// NEVER edit LEDGER_MIGRATION: deployed databases hold its checksum (a test pins it). A change to
+// the ledger is a new file, `0002_…`, appended to LEDGER_FILES.
+import { createMigrationFile } from "./files.js";
+export const LEDGER_MODULE_ID = "softure";
+export const LEDGER_SCHEMA = "softure";
+/** The ledger's own format version, recorded as `module_version` of its rows. */
+export const LEDGER_VERSION = "1.0.0";
+const LEDGER_MIGRATION = `-- Rollback: DROP SCHEMA softure CASCADE; this forgets which module migrations ran, the module schemas and their data stay.
+CREATE TABLE softure.migrations (
+  id bigint GENERATED ALWAYS AS IDENTITY UNIQUE,
+  module text NOT NULL CHECK (module ~ '^[a-z][a-z0-9]*(-[a-z0-9]+)*$'),
+  version integer NOT NULL CHECK (version > 0),
+  name text NOT NULL CHECK (name ~ '^[a-z0-9]+(_[a-z0-9]+)*$'),
+  checksum text NOT NULL CHECK (checksum ~ '^[0-9a-f]{64}$'),
+  module_version text NOT NULL,
+  method text NOT NULL CHECK (method IN ('applied', 'adopted')),
+  applied_at timestamptz NOT NULL DEFAULT now(),
+  PRIMARY KEY (module, version)
+);
+`;
+function createLedgerFiles() {
+    const file = createMigrationFile("0001_ledger.sql", LEDGER_MIGRATION);
+    if (typeof file === "string") {
+        throw new Error(`ledger: the built-in migration is invalid: ${file}`);
+    }
+    return [file];
+}
+export const LEDGER_FILES = createLedgerFiles();
+/** Every ledger row, or none while the ledger table does not exist yet. */
+export async function readJournal(session) {
+    const [table] = await session.query("SELECT to_regclass('softure.migrations') IS NOT NULL AS exists");
+    if (table?.exists !== true) {
+        return [];
+    }
+    return session.query("SELECT module, version, name, checksum, method FROM softure.migrations ORDER BY id");
+}
+export async function recordMigration(session, entry) {
+    await session.query("INSERT INTO softure.migrations (module, version, name, checksum, module_version, method) VALUES ($1, $2, $3, $4, $5, $6)", [entry.module, entry.version, entry.name, entry.checksum, entry.moduleVersion, entry.method]);
+}
+//# sourceMappingURL=ledger.js.map

package/dist/migrations/ledger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ledger.js","sourceRoot":"","sources":["../../src/migrations/ledger.ts"],"names":[],"mappings":"AAAA,gGAAgG;AAChG,6FAA6F;AAC7F,iGAAiG;AACjG,gDAAgD;AAChD,EAAE;AACF,kGAAkG;AAClG,gEAAgE;AAChE,OAAO,EAAE,mBAAmB,EAAsB,MAAM,YAAY,CAAC;AAGrE,MAAM,CAAC,MAAM,gBAAgB,GAAG,SAAS,CAAC;AAC1C,MAAM,CAAC,MAAM,aAAa,GAAG,SAAS,CAAC;AACvC,iFAAiF;AACjF,MAAM,CAAC,MAAM,cAAc,GAAG,OAAO,CAAC;AAEtC,MAAM,gBAAgB,GAAG;;;;;;;;;;;;CAYxB,CAAC;AAEF,SAAS,iBAAiB;IACxB,MAAM,IAAI,GAAG,mBAAmB,CAAC,iBAAiB,EAAE,gBAAgB,CAAC,CAAC;IACtE,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC7B,MAAM,IAAI,KAAK,CAAC,8CAA8C,IAAI,EAAE,CAAC,CAAC;IACxE,CAAC;IACD,OAAO,CAAC,IAAI,CAAC,CAAC;AAChB,CAAC;AAED,MAAM,CAAC,MAAM,YAAY,GAA6B,iBAAiB,EAAE,CAAC;AAqB1E,2EAA2E;AAC3E,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,OAAyB;IACzD,MAAM,CAAC,KAAK,CAAC,GAAG,MAAM,OAAO,CAAC,KAAK,CAAsB,gEAAgE,CAAC,CAAC;IAC3H,IAAI,KAAK,EAAE,MAAM,KAAK,IAAI,EAAE,CAAC;QAC3B,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,OAAO,OAAO,CAAC,KAAK,CAClB,oFAAoF,CACrF,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,OAAyB,EAAE,KAAkB;IACjF,MAAM,OAAO,CAAC,KAAK,CACjB,0HAA0H,EAC1H,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,QAAQ,EAAE,KAAK,CAAC,aAAa,EAAE,KAAK,CAAC,MAAM,CAAC,CAC7F,CAAC;AACJ,CAAC"}

package/dist/migrations/migrator.d.ts

@@ -0,0 +1,69 @@
+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 MigrationProblem, type MigrationResult } from "./problems.js";
+import { type MigrationSession } from "./session.js";
+export interface MigrateOptions {
+    /** The enabled modules, in any order; dependencies are applied first. */
+    readonly modules: readonly AnySoftureModule[];
+    /**
+     * Read each module's files from `<migrationsDir>/<module id>/` instead of the module's own
+     * folder: the container path, where a bundle cannot locate package folders.
+     */
+    readonly migrationsDir?: URL;
+    /** Called after each file is committed, e.g. to print progress. */
+    readonly onApplied?: (step: MigrationStep) => void;
+}
+export interface MigrationStep {
+    readonly module: string;
+    readonly schema: string;
+    readonly version: number;
+    readonly name: string;
+    readonly checksum: string;
+}
+export interface MigrationPlan {
+    /** What `migrate` would apply, in order. */
+    readonly pending: 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 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. */
+export declare function migrate(handle: DatabaseHandle, options: MigrateOptions): Promise<MigrationResult<MigrationReport>>;
+/**
+ * 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.
+ */
+export declare function prepareUnits(modules: readonly AnySoftureModule[], migrationsDir: URL | undefined): Promise<MigrationResult<MigrationUnit[]>>;
+/** Checks applied files against the folder and lists the pending ones in run order. */
+export declare function compareJournal(units: readonly MigrationUnit[], journal: readonly JournalRow[]): {
+    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

@@ -0,0 +1 @@
+{"version":3,"file":"migrator.d.ts","sourceRoot":"","sources":["../../src/migrations/migrator.ts"],"names":[],"mappings":"AAIA,OAAO,EAAiC,KAAK,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACxF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,EAAsB,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC;AACpE,OAAO,EAOL,KAAK,UAAU,EACf,KAAK,eAAe,EACrB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAY,KAAK,gBAAgB,EAAE,KAAK,eAAe,EAAE,MAAM,eAAe,CAAC;AACtF,OAAO,EAAe,KAAK,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAElE,MAAM,WAAW,cAAc;IAC7B,yEAAyE;IACzE,QAAQ,CAAC,OAAO,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAC9C;;;OAGG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,GAAG,CAAC;IAC7B,mEAAmE;IACnE,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,aAAa,KAAK,IAAI,CAAC;CACpD;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,aAAa;IAC5B,4CAA4C;IAC5C,QAAQ,CAAC,OAAO,EAAE,SAAS,aAAa,EAAE,CAAC;CAC5C;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,OAAO,EAAE,SAAS,aAAa,EAAE,CAAC;CAC5C;AAED,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;AAOD,iFAAiF;AACjF,wBAAsB,cAAc,CAAC,MAAM,EAAE,cAAc,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC,aAAa,CAAC,CAAC,CAQ7H;AAED,+DAA+D;AAC/D,wBAAsB,OAAO,CAAC,MAAM,EAAE,cAAc,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC,eAAe,CAAC,CAAC,CA6BxH;AAED;;;GAGG;AACH,wBAAsB,YAAY,CAChC,OAAO,EAAE,SAAS,gBAAgB,EAAE,EACpC,aAAa,EAAE,GAAG,GAAG,SAAS,GAC7B,OAAO,CAAC,eAAe,CAAC,aAAa,EAAE,CAAC,CAAC,CA2B3C;AAED,uFAAuF;AACvF,wBAAgB,cAAc,CAC5B,KAAK,EAAE,SAAS,aAAa,EAAE,EAC/B,OAAO,EAAE,SAAS,UAAU,EAAE,GAC7B;IAAE,QAAQ,EAAE,gBAAgB,EAAE,CAAC;IAAC,OAAO,EAAE,aAAa,EAAE,CAAA;CAAE,CA4B5D;AAED;;;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"}

package/dist/migrations/migrator.js

@@ -0,0 +1,217 @@
+// The module migrator (docs/02-module-standard.md §4). Every enabled module's SQL files run in the
+// 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.
+import { ok, sortModulesByDependencies } from "@softure-ai/core";
+import { readMigrationFiles } from "./files.js";
+import { LEDGER_FILES, LEDGER_MODULE_ID, LEDGER_SCHEMA, LEDGER_VERSION, readJournal, recordMigration, } from "./ledger.js";
+import { failWith } from "./problems.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"]);
+const MAX_IDENTIFIER_BYTES = 63;
+/** The dry run: what `migrate` would apply. Takes no lock and writes nothing. */
+export async function planMigrations(handle, options) {
+    const units = await prepareUnits(options.modules, options.migrationsDir);
+    if (!units.ok) {
+        return units;
+    }
+    const journal = await withSession(handle, readJournal);
+    const comparison = compareJournal(units.value, journal);
+    return comparison.problems.length > 0 ? failWith(comparison.problems) : ok({ pending: comparison.pending });
+}
+/** Applies every pending migration under the advisory lock. */
+export async function migrate(handle, options) {
+    const units = await prepareUnits(options.modules, options.migrationsDir);
+    if (!units.ok) {
+        return units;
+    }
+    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));
+        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 failure = await applyFile(session, { unit, file, method: "applied" });
+            if (failure !== null) {
+                return failWith([failure]);
+            }
+            applied.push(step);
+            options.onApplied?.(step);
+        }
+        return ok({ applied });
+    }));
+}
+/**
+ * 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.
+ */
+export async function prepareUnits(modules, migrationsDir) {
+    const problems = modules.flatMap(checkModule);
+    const sorted = sortModulesByDependencies(modules);
+    if (!sorted.ok) {
+        problems.push({ code: "db.dependency_cycle", modules: modules.map((module) => module.id) });
+    }
+    if (problems.length > 0 || !sorted.ok) {
+        return failWith(problems);
+    }
+    const units = [
+        { module: LEDGER_MODULE_ID, schema: LEDGER_SCHEMA, moduleVersion: LEDGER_VERSION, files: LEDGER_FILES },
+    ];
+    for (const module of sorted.value) {
+        const schema = module.manifest.dbSchema;
+        if (schema === null || module.migrations === null) {
+            continue;
+        }
+        const dir = migrationsDir === undefined ? module.migrations.dir : new URL(`${module.id}/`, ensureFolderUrl(migrationsDir));
+        const files = await readMigrationFiles(module.id, dir);
+        if (files.ok) {
+            units.push({ module: module.id, schema, moduleVersion: module.manifest.version, files: files.value });
+        }
+        else {
+            problems.push(...files.problems);
+        }
+    }
+    return problems.length > 0 ? failWith(problems) : ok(units);
+}
+/** Checks applied files against the folder and lists the pending ones in run order. */
+export function compareJournal(units, journal) {
+    const problems = [];
+    const pending = [];
+    for (const unit of units) {
+        const rows = journal.filter((row) => row.module === unit.module);
+        const appliedVersions = new Set(rows.map((row) => row.version));
+        const lastApplied = Math.max(0, ...rows.map((row) => row.version));
+        for (const row of rows) {
+            const file = unit.files.find((candidate) => candidate.version === row.version);
+            if (file === undefined) {
+                problems.push({ code: "db.migration_missing", module: unit.module, version: row.version, name: row.name });
+            }
+            else if (file.checksum !== row.checksum || file.name !== row.name) {
+                problems.push({ code: "db.migration_changed", module: unit.module, version: row.version, name: row.name });
+            }
+        }
+        for (const file of unit.files) {
+            if (appliedVersions.has(file.version)) {
+                continue;
+            }
+            if (file.version < lastApplied) {
+                problems.push({ code: "db.migration_out_of_order", module: unit.module, version: file.version, appliedVersion: lastApplied });
+            }
+            else {
+                pending.push({ module: unit.module, schema: unit.schema, version: file.version, name: file.name, checksum: file.checksum });
+            }
+        }
+    }
+    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))) {
+        return [{ code: "db.reserved_module", module: module.id }];
+    }
+    if (schema === null && module.migrations !== null) {
+        return [{ code: "db.migrations_without_schema", module: module.id }];
+    }
+    return [];
+}
+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

package/dist/migrations/migrator.js.map

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

package/dist/migrations/problems.d.ts

@@ -0,0 +1,84 @@
+import type { Err, Ok } from "@softure-ai/core";
+export type MigrationProblem = {
+    readonly code: "db.invalid_migration_file";
+    readonly module: string;
+    readonly file: string;
+    readonly reason: string;
+} | {
+    readonly code: "db.migrations_unreadable";
+    readonly module: string;
+    readonly dir: string;
+    readonly reason: string;
+} | {
+    readonly code: "db.migration_changed";
+    readonly module: string;
+    readonly version: number;
+    readonly name: string;
+} | {
+    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.reserved_module";
+    readonly module: string;
+} | {
+    readonly code: "db.migrations_without_schema";
+    readonly module: string;
+} | {
+    readonly code: "db.dependency_cycle";
+    readonly modules: readonly string[];
+} | {
+    readonly code: "db.adopt_unknown_module";
+    readonly module: string;
+} | {
+    readonly code: "db.adopt_version_mismatch";
+    readonly module: string;
+    readonly requested: string;
+    readonly enabled: string;
+} | {
+    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_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[];
+};
+export type MigrationErrorCode = MigrationProblem["code"];
+/** A failed migration operation: the code of its first problem, and every problem found. */
+export interface MigrationFailure extends Err<MigrationErrorCode> {
+    readonly problems: readonly MigrationProblem[];
+}
+export type MigrationResult<T> = Ok<T> | MigrationFailure;
+export declare function failWith(problems: readonly MigrationProblem[]): MigrationFailure;
+/** One English line per problem, naming the module and the file or object involved. */
+export declare function describeProblem(problem: MigrationProblem): string;
+//# sourceMappingURL=problems.d.ts.map

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

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

package/dist/migrations/problems.js

@@ -0,0 +1,56 @@
+export function failWith(problems) {
+    const [first] = problems;
+    if (first === undefined) {
+        throw new Error("failWith: a migration failure needs at least one problem");
+    }
+    return { ok: false, error: first.code, problems };
+}
+/** One English line per problem, naming the module and the file or object involved. */
+export function describeProblem(problem) {
+    switch (problem.code) {
+        case "db.invalid_migration_file":
+            return `${problem.module}: migration file ${problem.file} is invalid: ${problem.reason}`;
+        case "db.migrations_unreadable":
+            return `${problem.module}: cannot read the migrations folder ${problem.dir}: ${problem.reason}`;
+        case "db.migration_changed":
+            return `${problem.module}: applied migration ${formatFile(problem.version, problem.name)} was edited (checksum differs); add a new migration instead`;
+        case "db.migration_missing":
+            return `${problem.module}: applied migration ${formatFile(problem.version, problem.name)} is missing from the module`;
+        case "db.migration_out_of_order":
+            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.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)`;
+        case "db.migrations_without_schema":
+            return `${problem.module}: has migrations but no dbSchema in its manifest`;
+        case "db.dependency_cycle":
+            return `modules ${problem.modules.join(", ")} depend on each other in a cycle`;
+        case "db.adopt_unknown_module":
+            return `${problem.module}: cannot adopt a module that is not enabled in the config`;
+        case "db.adopt_version_mismatch":
+            return `${problem.module}: --adopt asks for ${problem.requested} but ${problem.enabled} is enabled`;
+        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`;
+        case "db.adopt_no_schema":
+            return `${problem.module}: has no dbSchema, so there is nothing to adopt`;
+        case "db.adopt_reference_failed":
+            return `${problem.module}: could not build the reference schema: ${problem.reason}`;
+        case "db.export_target_not_empty":
+            return `${problem.module}: ${problem.dir} holds other files (${problem.entries.join(", ")}); export into an empty folder`;
+        case "db.schema_mismatch":
+            return [
+                `${problem.module}: schema "${problem.schema}" differs from what its migrations create:`,
+                ...problem.differences.map((difference) => `  ${difference}`),
+            ].join("\n");
+    }
+}
+function formatVersion(version) {
+    return String(version).padStart(4, "0");
+}
+function formatFile(version, name) {
+    return `${formatVersion(version)}_${name}.sql`;
+}
+//# sourceMappingURL=problems.js.map

package/dist/migrations/problems.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"problems.js","sourceRoot":"","sources":["../../src/migrations/problems.ts"],"names":[],"mappings":"AAiCA,MAAM,UAAU,QAAQ,CAAC,QAAqC;IAC5D,MAAM,CAAC,KAAK,CAAC,GAAG,QAAQ,CAAC;IACzB,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,MAAM,IAAI,KAAK,CAAC,0DAA0D,CAAC,CAAC;IAC9E,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,IAAI,EAAE,QAAQ,EAAE,CAAC;AACpD,CAAC;AAED,uFAAuF;AACvF,MAAM,UAAU,eAAe,CAAC,OAAyB;IACvD,QAAQ,OAAO,CAAC,IAAI,EAAE,CAAC;QACrB,KAAK,2BAA2B;YAC9B,OAAO,GAAG,OAAO,CAAC,MAAM,oBAAoB,OAAO,CAAC,IAAI,gBAAgB,OAAO,CAAC,MAAM,EAAE,CAAC;QAC3F,KAAK,0BAA0B;YAC7B,OAAO,GAAG,OAAO,CAAC,MAAM,uCAAuC,OAAO,CAAC,GAAG,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC;QAClG,KAAK,sBAAsB;YACzB,OAAO,GAAG,OAAO,CAAC,MAAM,uBAAuB,UAAU,CAAC,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,6DAA6D,CAAC;QACxJ,KAAK,sBAAsB;YACzB,OAAO,GAAG,OAAO,CAAC,MAAM,uBAAuB,UAAU,CAAC,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,6BAA6B,CAAC;QACxH,KAAK,2BAA2B;YAC9B,OAAO,GAAG,OAAO,CAAC,MAAM,eAAe,aAAa,CAAC,OAAO,CAAC,OAAO,CAAC,mBAAmB,aAAa,CAAC,OAAO,CAAC,cAAc,CAAC,qBAAqB,CAAC;QACrJ,KAAK,qBAAqB;YACxB,OAAO,GAAG,OAAO,CAAC,MAAM,eAAe,UAAU,CAAC,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,gCAAgC,OAAO,CAAC,MAAM,EAAE,CAAC;QACnI,KAAK,oBAAoB;YACvB,OAAO,GAAG,OAAO,CAAC,MAAM,kIAAkI,CAAC;QAC7J,KAAK,8BAA8B;YACjC,OAAO,GAAG,OAAO,CAAC,MAAM,kDAAkD,CAAC;QAC7E,KAAK,qBAAqB;YACxB,OAAO,WAAW,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,kCAAkC,CAAC;QACjF,KAAK,yBAAyB;YAC5B,OAAO,GAAG,OAAO,CAAC,MAAM,2DAA2D,CAAC;QACtF,KAAK,2BAA2B;YAC9B,OAAO,GAAG,OAAO,CAAC,MAAM,sBAAsB,OAAO,CAAC,SAAS,QAAQ,OAAO,CAAC,OAAO,aAAa,CAAC;QACtG,KAAK,0BAA0B;YAC7B,OAAO,GAAG,OAAO,CAAC,MAAM,gGAAgG,CAAC;QAC3H,KAAK,6BAA6B;YAChC,OAAO,GAAG,OAAO,CAAC,MAAM,gBAAgB,OAAO,CAAC,UAAU,0DAA0D,OAAO,CAAC,UAAU,QAAQ,CAAC;QACjJ,KAAK,oBAAoB;YACvB,OAAO,GAAG,OAAO,CAAC,MAAM,iDAAiD,CAAC;QAC5E,KAAK,2BAA2B;YAC9B,OAAO,GAAG,OAAO,CAAC,MAAM,2CAA2C,OAAO,CAAC,MAAM,EAAE,CAAC;QACtF,KAAK,4BAA4B;YAC/B,OAAO,GAAG,OAAO,CAAC,MAAM,KAAK,OAAO,CAAC,GAAG,uBAAuB,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,gCAAgC,CAAC;QAC5H,KAAK,oBAAoB;YACvB,OAAO;gBACL,GAAG,OAAO,CAAC,MAAM,aAAa,OAAO,CAAC,MAAM,4CAA4C;gBACxF,GAAG,OAAO,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC,KAAK,UAAU,EAAE,CAAC;aAC9D,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACjB,CAAC;AACH,CAAC;AAED,SAAS,aAAa,CAAC,OAAe;IACpC,OAAO,MAAM,CAAC,OAAO,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;AAC1C,CAAC;AAED,SAAS,UAAU,CAAC,OAAe,EAAE,IAAY;IAC/C,OAAO,GAAG,aAAa,CAAC,OAAO,CAAC,IAAI,IAAI,MAAM,CAAC;AACjD,CAAC"}

package/dist/migrations/session.d.ts

@@ -0,0 +1,14 @@
+import type { DatabaseHandle } from "../client.js";
+export interface MigrationSession {
+    /** A parameterised statement; returns its rows. */
+    readonly query: <T>(text: string, params?: readonly unknown[]) => Promise<T[]>;
+    /** One or more statements without parameters (a migration file). */
+    readonly exec: (sql: string) => Promise<void>;
+}
+/**
+ * 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.
+ */
+export declare function withSession<T>(handle: DatabaseHandle, run: (session: MigrationSession) => Promise<T>): Promise<T>;
+//# sourceMappingURL=session.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/migrations/session.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEnD,MAAM,WAAW,gBAAgB;IAC/B,mDAAmD;IACnD,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,OAAO,EAAE,KAAK,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;IAC/E,oEAAoE;IACpE,QAAQ,CAAC,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/C;AAED;;;;GAIG;AACH,wBAAsB,WAAW,CAAC,CAAC,EAAE,MAAM,EAAE,cAAc,EAAE,GAAG,EAAE,CAAC,OAAO,EAAE,gBAAgB,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CA+BvH"}

package/dist/migrations/session.js

@@ -0,0 +1,39 @@
+/**
+ * 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.
+ */
+export async function withSession(handle, run) {
+    if (handle.kind === "pglite") {
+        const { client } = handle;
+        try {
+            return await run({
+                query: async (text, params) => (await client.query(text, params ? [...params] : undefined)).rows,
+                exec: async (sql) => {
+                    await client.exec(sql);
+                },
+            });
+        }
+        finally {
+            await client.exec("RESET ALL");
+        }
+    }
+    const client = await handle.pool.connect();
+    // A dropped connection makes pg emit 'error' on the client; without a listener Node crashes the
+    // process. The pending query rejects on its own, so the listener only has to exist.
+    const ignoreClientError = () => undefined;
+    client.on("error", ignoreClientError);
+    try {
+        return await run({
+            query: async (text, params) => (await client.query(text, params ? [...params] : undefined)).rows,
+            exec: async (sql) => {
+                await client.query(sql);
+            },
+        });
+    }
+    finally {
+        client.release(true);
+        client.off("error", ignoreClientError);
+    }
+}
+//# sourceMappingURL=session.js.map

package/dist/migrations/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../../src/migrations/session.ts"],"names":[],"mappings":"AAWA;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAI,MAAsB,EAAE,GAA8C;IACzG,IAAI,MAAM,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC7B,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC;QAC1B,IAAI,CAAC;YACH,OAAO,MAAM,GAAG,CAAC;gBACf,KAAK,EAAE,KAAK,EAAK,IAAY,EAAE,MAA2B,EAAE,EAAE,CAAC,CAAC,MAAM,MAAM,CAAC,KAAK,CAAI,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI;gBACnI,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE;oBAClB,MAAM,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;gBACzB,CAAC;aACF,CAAC,CAAC;QACL,CAAC;gBAAS,CAAC;YACT,MAAM,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;QACjC,CAAC;IACH,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;IAC3C,gGAAgG;IAChG,oFAAoF;IACpF,MAAM,iBAAiB,GAAG,GAAS,EAAE,CAAC,SAAS,CAAC;IAChD,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,iBAAiB,CAAC,CAAC;IACtC,IAAI,CAAC;QACH,OAAO,MAAM,GAAG,CAAC;YACf,KAAK,EAAE,KAAK,EAAK,IAAY,EAAE,MAA2B,EAAE,EAAE,CAAC,CAAC,MAAM,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAW;YACvI,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE;gBAClB,MAAM,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;YAC1B,CAAC;SACF,CAAC,CAAC;IACL,CAAC;YAAS,CAAC;QACT,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QACrB,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,iBAAiB,CAAC,CAAC;IACzC,CAAC;AACH,CAAC"}

package/dist/shared.d.ts

@@ -0,0 +1,9 @@
+import { type CreateDatabaseOptions, type DatabaseHandle } from "./client.js";
+/**
+ * The process-wide handle for `url`, opened on first use. `options` apply only to that first call.
+ * A failed open is not kept, so the next call tries again.
+ */
+export declare function getSharedDatabase(url: string, options?: CreateDatabaseOptions): Promise<DatabaseHandle>;
+/** Closes and forgets every shared handle. For tests and graceful shutdown. */
+export declare function closeSharedDatabases(): Promise<void>;
+//# sourceMappingURL=shared.d.ts.map