@softure-ai/db 0.0.0-stage → 0.1.6

package/dist/migrations/problems.d.ts

@@ -0,0 +1,93 @@
+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.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[];
+} | {
+    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_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[];
+};
+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,62 @@
+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.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, 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":
+            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}, whose pending migrations could not be applied (see above); adopt ${problem.dependency} first`;
+        case "db.adopt_no_schema":
+            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":
+            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":"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"}

package/dist/migrations/reference.d.ts

@@ -0,0 +1,23 @@
+import { type AnySoftureModule } from "@softure-ai/core";
+import { type MigrationUnit } from "./apply.js";
+import { type MigrationResult } from "./problems.js";
+import { type AppCatalog } from "./stubs.js";
+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 declare function buildReferenceSchema(input: ReferenceInput): Promise<MigrationResult<string[]>>;
+/** The schemas the migrator owns, which hold no app table: the ledger's, every unit's and drizzle's. */
+export declare function listOwnedSchemas(units: readonly MigrationUnit[]): string[];
+/** The ids of the target and every enabled module it depends on, directly or not. */
+export declare function collectWithDependencies(modules: readonly AnySoftureModule[], target: string): Set<string>;
+//# sourceMappingURL=reference.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"reference.d.ts","sourceRoot":"","sources":["../../src/migrations/reference.ts"],"names":[],"mappings":"AAKA,OAAO,EAAM,KAAK,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAE7D,OAAO,EAAa,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC;AAG3D,OAAO,EAAmC,KAAK,eAAe,EAAE,MAAM,eAAe,CAAC;AAEtF,OAAO,EAAkB,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAK7D,MAAM,WAAW,cAAc;IAC7B,qDAAqD;IACrD,QAAQ,CAAC,OAAO,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAC9C,oFAAoF;IACpF,QAAQ,CAAC,KAAK,EAAE,SAAS,aAAa,EAAE,CAAC;IACzC,4CAA4C;IAC5C,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,wEAAwE;IACxE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,iFAAiF;IACjF,QAAQ,CAAC,SAAS,CAAC,EAAE,UAAU,CAAC;CACjC;AAED,6FAA6F;AAC7F,wBAAsB,oBAAoB,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC,MAAM,EAAE,CAAC,CAAC,CAuBpG;AAED,wGAAwG;AACxG,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,SAAS,aAAa,EAAE,GAAG,MAAM,EAAE,CAE1E;AAED,qFAAqF;AACrF,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,SAAS,gBAAgB,EAAE,EAAE,MAAM,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,CAWzG"}

package/dist/migrations/reference.js

@@ -0,0 +1,64 @@
+// 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 } from "@softure-ai/core";
+import { createDatabase } from "../client.js";
+import { applyFile } from "./apply.js";
+import { describeSchema } from "./introspect.js";
+import { LEDGER_MODULE_ID, LEDGER_SCHEMA } from "./ledger.js";
+import { failWith } from "./problems.js";
+import { withSession } from "./session.js";
+import { createAppStubs } from "./stubs.js";
+// drizzle's ledger schema (`drizzle.__drizzle_migrations`): never an app table a module references.
+const APP_MIGRATOR_SCHEMA = "drizzle";
+/** Every line `describeSchema` prints for the target's schema after its files 1..through. */
+export async function buildReferenceSchema(input) {
+    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) {
+    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, target) {
+    const byId = new Map(modules.map((module) => [module.id, module]));
+    const collected = new Set();
+    const visit = (id) => {
+        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) {
+    return problem.code === "db.migration_failed" ? `${problem.module} ${problem.name}: ${problem.reason}` : problem.code;
+}
+//# sourceMappingURL=reference.js.map

package/dist/migrations/reference.js.map

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

package/dist/migrations/session.d.ts

@@ -0,0 +1,15 @@
+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, 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 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;AAInD,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;AASD;;;;;GAKG;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,CAgCvH"}

package/dist/migrations/session.js

@@ -0,0 +1,56 @@
+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, 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(handle, run) {
+    if (handle.kind === "pglite") {
+        const { client } = handle;
+        const before = (await client.query(SESSION_SETTINGS_SQL)).rows;
+        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 restoreSessionSettings(client, before);
+        }
+    }
+    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);
+    }
+}
+/** Puts back every value in `before` (also one the run reset) and resets every session setting the run added. */
+async function restoreSessionSettings(client, before) {
+    const after = new Map((await client.query(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('"', '""')}"`);
+    }
+}
+//# 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":"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"}

package/dist/migrations/stubs.d.ts

@@ -0,0 +1,23 @@
+import type { MigrationSession } from "./session.js";
+/** One DDL statement for the scratch database, with the object it creates for reports. */
+export interface StubStatement {
+    /** `schema.table`, `schema.table.column`, `schema.table.constraint` or `schema.type`, unquoted. */
+    readonly object: string;
+    readonly sql: string;
+}
+/** The app's tables as statements to replay, in a runnable order. */
+export interface AppCatalog {
+    readonly statements: readonly StubStatement[];
+}
+/**
+ * The app's tables in every schema except `pg_*`, `information_schema` and `excludedSchemas` (the
+ * ledger, the enabled modules' schemas, the app migrator's own). Runs in its own read-only transaction.
+ */
+export declare function readAppTables(session: MigrationSession, excludedSchemas: readonly string[]): Promise<AppCatalog>;
+/**
+ * Replays the catalog on the scratch database, each statement on its own: a statement that fails
+ * (a type the scratch lacks, a key on a skipped column) is skipped, so a module that never
+ * references that table still builds its reference. Returns the skipped objects with the reason.
+ */
+export declare function createAppStubs(session: MigrationSession, catalog: AppCatalog): Promise<string[]>;
+//# sourceMappingURL=stubs.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"stubs.d.ts","sourceRoot":"","sources":["../../src/migrations/stubs.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAErD,0FAA0F;AAC1F,MAAM,WAAW,aAAa;IAC5B,mGAAmG;IACnG,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED,qEAAqE;AACrE,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,UAAU,EAAE,SAAS,aAAa,EAAE,CAAC;CAC/C;AA2ED;;;GAGG;AACH,wBAAsB,aAAa,CAAC,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,UAAU,CAAC,CAuBtH;AAED;;;;GAIG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,gBAAgB,EAAE,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAUtG"}

package/dist/migrations/stubs.js

@@ -0,0 +1,99 @@
+// Names come back quoted by Postgres (`quote_ident`, `format('%I')`), so no DDL below concatenates
+// a raw identifier. Each query takes the excluded schemas as $1.
+const IN_APP_SCHEMA = (alias) => `${alias}.nspname <> ALL($1::text[]) AND ${alias}.nspname <> 'information_schema' AND ${alias}.nspname NOT LIKE 'pg\\_%'`;
+const NOT_IN_EXTENSION = (catalog, alias) => `NOT EXISTS (SELECT 1 FROM pg_depend dep WHERE dep.classid = '${catalog}'::regclass AND dep.objid = ${alias}.oid AND dep.deptype = 'e')`;
+const QUERIES = {
+    schemas: `
+    SELECT DISTINCT n.nspname AS name, quote_ident(n.nspname) AS quoted
+    FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace
+    WHERE c.relkind IN ('r', 'p') AND ${IN_APP_SCHEMA("n")} AND ${NOT_IN_EXTENSION("pg_class", "c")}
+    ORDER BY 1`,
+    enums: `
+    SELECT n.nspname || '.' || t.typname AS object, format('%I.%I', n.nspname, t.typname) AS quoted,
+      (SELECT string_agg(quote_literal(e.enumlabel), ', ' ORDER BY e.enumsortorder) FROM pg_enum e WHERE e.enumtypid = t.oid) AS labels
+    FROM pg_type t JOIN pg_namespace n ON n.oid = t.typnamespace
+    WHERE t.typtype = 'e' AND ${IN_APP_SCHEMA("n")} AND ${NOT_IN_EXTENSION("pg_type", "t")}
+    ORDER BY 1`,
+    tables: `
+    SELECT n.nspname || '.' || c.relname AS object, format('%I.%I', n.nspname, c.relname) AS quoted
+    FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace
+    WHERE c.relkind IN ('r', 'p') AND ${IN_APP_SCHEMA("n")} AND ${NOT_IN_EXTENSION("pg_class", "c")}
+    ORDER BY 1`,
+    columns: `
+    SELECT n.nspname || '.' || c.relname AS table_object, format('%I.%I', n.nspname, c.relname) AS table_quoted,
+      a.attname AS name, quote_ident(a.attname) AS quoted, format_type(a.atttypid, a.atttypmod) AS type
+    FROM pg_attribute a
+      JOIN pg_class c ON c.oid = a.attrelid
+      JOIN pg_namespace n ON n.oid = c.relnamespace
+    WHERE c.relkind IN ('r', 'p') AND a.attnum > 0 AND NOT a.attisdropped
+      AND ${IN_APP_SCHEMA("n")} AND ${NOT_IN_EXTENSION("pg_class", "c")}
+    ORDER BY 1, a.attnum`,
+    keys: `
+    SELECT n.nspname || '.' || c.relname AS table_object, format('%I.%I', n.nspname, c.relname) AS table_quoted,
+      con.conname AS name, quote_ident(con.conname) AS quoted, pg_get_constraintdef(con.oid) AS definition
+    FROM pg_constraint con
+      JOIN pg_class c ON c.oid = con.conrelid
+      JOIN pg_namespace n ON n.oid = c.relnamespace
+    WHERE con.contype IN ('p', 'u') AND c.relkind IN ('r', 'p')
+      AND ${IN_APP_SCHEMA("n")} AND ${NOT_IN_EXTENSION("pg_class", "c")}
+    ORDER BY 1, con.contype, 3`,
+    // A unique index that backs no key constraint. A foreign key records the index it references in
+    // `conindid` too, so only key constraints count.
+    uniqueIndexes: `
+    SELECT n.nspname || '.' || c.relname AS table_object, i.relname AS name, pg_get_indexdef(i.oid) AS definition
+    FROM pg_index x
+      JOIN pg_class i ON i.oid = x.indexrelid
+      JOIN pg_class c ON c.oid = x.indrelid
+      JOIN pg_namespace n ON n.oid = c.relnamespace
+    WHERE x.indisunique AND x.indpred IS NULL AND x.indexprs IS NULL AND c.relkind IN ('r', 'p')
+      AND NOT EXISTS (SELECT 1 FROM pg_constraint con WHERE con.conindid = x.indexrelid AND con.contype IN ('p', 'u', 'x'))
+      AND ${IN_APP_SCHEMA("n")} AND ${NOT_IN_EXTENSION("pg_class", "c")}
+    ORDER BY 1, 2`,
+};
+/**
+ * The app's tables in every schema except `pg_*`, `information_schema` and `excludedSchemas` (the
+ * ledger, the enabled modules' schemas, the app migrator's own). Runs in its own read-only transaction.
+ */
+export async function readAppTables(session, excludedSchemas) {
+    await session.exec("BEGIN READ ONLY; SET LOCAL search_path = pg_catalog;");
+    try {
+        const params = [[...excludedSchemas]];
+        const schemas = await session.query(QUERIES.schemas, params);
+        const enums = await session.query(QUERIES.enums, params);
+        const tables = await session.query(QUERIES.tables, params);
+        const columns = await session.query(QUERIES.columns, params);
+        const keys = await session.query(QUERIES.keys, params);
+        const indexes = await session.query(QUERIES.uniqueIndexes, params);
+        return {
+            statements: [
+                ...schemas.map((row) => ({ object: row.name, sql: `CREATE SCHEMA IF NOT EXISTS ${row.quoted}` })),
+                ...enums.map((row) => ({ object: row.object, sql: `CREATE TYPE ${row.quoted} AS ENUM (${row.labels})` })),
+                ...tables.map((row) => ({ object: row.object, sql: `CREATE TABLE ${row.quoted} ()` })),
+                ...columns.map((row) => ({ object: `${row.table_object}.${row.name}`, sql: `ALTER TABLE ${row.table_quoted} ADD COLUMN ${row.quoted} ${row.type}` })),
+                ...keys.map((row) => ({ object: `${row.table_object}.${row.name}`, sql: `ALTER TABLE ${row.table_quoted} ADD CONSTRAINT ${row.quoted} ${row.definition}` })),
+                ...indexes.map((row) => ({ object: `${row.table_object}.${row.name}`, sql: row.definition })),
+            ],
+        };
+    }
+    finally {
+        await session.exec("ROLLBACK");
+    }
+}
+/**
+ * Replays the catalog on the scratch database, each statement on its own: a statement that fails
+ * (a type the scratch lacks, a key on a skipped column) is skipped, so a module that never
+ * references that table still builds its reference. Returns the skipped objects with the reason.
+ */
+export async function createAppStubs(session, catalog) {
+    const skipped = [];
+    for (const statement of catalog.statements) {
+        try {
+            await session.exec(statement.sql);
+        }
+        catch (error) {
+            skipped.push(`${statement.object}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    return skipped;
+}
+//# sourceMappingURL=stubs.js.map

package/dist/migrations/stubs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stubs.js","sourceRoot":"","sources":["../../src/migrations/stubs.ts"],"names":[],"mappings":"AAqBA,mGAAmG;AACnG,iEAAiE;AACjE,MAAM,aAAa,GAAG,CAAC,KAAa,EAAU,EAAE,CAC9C,GAAG,KAAK,mCAAmC,KAAK,wCAAwC,KAAK,4BAA4B,CAAC;AAE5H,MAAM,gBAAgB,GAAG,CAAC,OAAe,EAAE,KAAa,EAAU,EAAE,CAClE,gEAAgE,OAAO,+BAA+B,KAAK,6BAA6B,CAAC;AAE3I,MAAM,OAAO,GAAG;IACd,OAAO,EAAE;;;wCAG6B,aAAa,CAAC,GAAG,CAAC,QAAQ,gBAAgB,CAAC,UAAU,EAAE,GAAG,CAAC;eACpF;IACb,KAAK,EAAE;;;;gCAIuB,aAAa,CAAC,GAAG,CAAC,QAAQ,gBAAgB,CAAC,SAAS,EAAE,GAAG,CAAC;eAC3E;IACb,MAAM,EAAE;;;wCAG8B,aAAa,CAAC,GAAG,CAAC,QAAQ,gBAAgB,CAAC,UAAU,EAAE,GAAG,CAAC;eACpF;IACb,OAAO,EAAE;;;;;;;YAOC,aAAa,CAAC,GAAG,CAAC,QAAQ,gBAAgB,CAAC,UAAU,EAAE,GAAG,CAAC;yBAC9C;IACvB,IAAI,EAAE;;;;;;;YAOI,aAAa,CAAC,GAAG,CAAC,QAAQ,gBAAgB,CAAC,UAAU,EAAE,GAAG,CAAC;+BACxC;IAC7B,gGAAgG;IAChG,iDAAiD;IACjD,aAAa,EAAE;;;;;;;;YAQL,aAAa,CAAC,GAAG,CAAC,QAAQ,gBAAgB,CAAC,UAAU,EAAE,GAAG,CAAC;kBACrD;CACR,CAAC;AAkBX;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,OAAyB,EAAE,eAAkC;IAC/F,MAAM,OAAO,CAAC,IAAI,CAAC,sDAAsD,CAAC,CAAC;IAC3E,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,CAAC,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC;QACtC,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,KAAK,CAAmC,OAAO,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QAC/F,MAAM,KAAK,GAAG,MAAM,OAAO,CAAC,KAAK,CAAqD,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;QAC7G,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,KAAK,CAAqC,OAAO,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAC/F,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,KAAK,CAAY,OAAO,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QACxE,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,KAAK,CAAS,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QAC/D,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,KAAK,CAA6D,OAAO,CAAC,aAAa,EAAE,MAAM,CAAC,CAAC;QAC/H,OAAO;YACL,UAAU,EAAE;gBACV,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,IAAI,EAAE,GAAG,EAAE,+BAA+B,GAAG,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;gBACjG,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,EAAE,eAAe,GAAG,CAAC,MAAM,aAAa,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;gBACzG,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,EAAE,gBAAgB,GAAG,CAAC,MAAM,KAAK,EAAE,CAAC,CAAC;gBACtF,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,GAAG,CAAC,YAAY,IAAI,GAAG,CAAC,IAAI,EAAE,EAAE,GAAG,EAAE,eAAe,GAAG,CAAC,YAAY,eAAe,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;gBACrJ,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,GAAG,CAAC,YAAY,IAAI,GAAG,CAAC,IAAI,EAAE,EAAE,GAAG,EAAE,eAAe,GAAG,CAAC,YAAY,mBAAmB,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;gBAC5J,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,GAAG,CAAC,YAAY,IAAI,GAAG,CAAC,IAAI,EAAE,EAAE,GAAG,EAAE,GAAG,CAAC,UAAU,EAAE,CAAC,CAAC;aAC9F;SACF,CAAC;IACJ,CAAC;YAAS,CAAC;QACT,MAAM,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IACjC,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,OAAyB,EAAE,OAAmB;IACjF,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,KAAK,MAAM,SAAS,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;QAC3C,IAAI,CAAC;YACH,MAAM,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;QACpC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,CAAC,IAAI,CAAC,GAAG,SAAS,CAAC,MAAM,KAAK,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QACjG,CAAC;IACH,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,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

package/dist/shared.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../src/shared.ts"],"names":[],"mappings":"AAIA,OAAO,EAAkB,KAAK,qBAAqB,EAAE,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAQ9F;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,qBAA0B,GAAG,OAAO,CAAC,cAAc,CAAC,CAS3G;AAED,+EAA+E;AAC/E,wBAAsB,oBAAoB,IAAI,OAAO,CAAC,IAAI,CAAC,CAO1D"}

package/dist/shared.js

@@ -0,0 +1,32 @@
+// One database handle per URL for the whole server process, shared by every module's Next.js
+// adapter and the app. Package code cannot import the app's own handle, and `next dev` re-evaluates
+// modules on every change, so the handles live on `globalThis` under a `Symbol.for` key: each
+// reload, and each copy of this file in separate server bundles, finds the same pool.
+import { createDatabase } from "./client.js";
+const HANDLES_KEY = Symbol.for("@softure-ai/db/shared-handles");
+const host = globalThis;
+/**
+ * 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 function getSharedDatabase(url, options = {}) {
+    const handles = (host[HANDLES_KEY] ??= new Map());
+    let handle = handles.get(url);
+    if (handle === undefined) {
+        handle = createDatabase(url, options);
+        handles.set(url, handle);
+        handle.catch(() => handles.delete(url));
+    }
+    return handle;
+}
+/** Closes and forgets every shared handle. For tests and graceful shutdown. */
+export async function closeSharedDatabases() {
+    const handles = host[HANDLES_KEY];
+    if (handles === undefined)
+        return;
+    const opened = [...handles.values()];
+    handles.clear();
+    const results = await Promise.allSettled(opened);
+    await Promise.all(results.flatMap((result) => (result.status === "fulfilled" ? [result.value.close()] : [])));
+}
+//# sourceMappingURL=shared.js.map

package/dist/shared.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.js","sourceRoot":"","sources":["../src/shared.ts"],"names":[],"mappings":"AAAA,6FAA6F;AAC7F,oGAAoG;AACpG,8FAA8F;AAC9F,sFAAsF;AACtF,OAAO,EAAE,cAAc,EAAmD,MAAM,aAAa,CAAC;AAE9F,MAAM,WAAW,GAAG,MAAM,CAAC,GAAG,CAAC,+BAA+B,CAAC,CAAC;AAIhE,MAAM,IAAI,GAAG,UAAmC,CAAC;AAEjD;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAW,EAAE,UAAiC,EAAE;IAChF,MAAM,OAAO,GAAG,CAAC,IAAI,CAAC,WAAW,CAAC,KAAK,IAAI,GAAG,EAAmC,CAAC,CAAC;IACnF,IAAI,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC9B,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,MAAM,GAAG,cAAc,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QACtC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;QACzB,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1C,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,+EAA+E;AAC/E,MAAM,CAAC,KAAK,UAAU,oBAAoB;IACxC,MAAM,OAAO,GAAG,IAAI,CAAC,WAAW,CAAC,CAAC;IAClC,IAAI,OAAO,KAAK,SAAS;QAAE,OAAO;IAClC,MAAM,MAAM,GAAG,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IACrC,OAAO,CAAC,KAAK,EAAE,CAAC;IAChB,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;IACjD,MAAM,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,MAAM,KAAK,WAAW,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;AAChH,CAAC"}

package/dist/testing.d.ts

@@ -0,0 +1,23 @@
+import { PGlite } from "@electric-sql/pglite";
+import type { AnySoftureModule } from "@softure-ai/core";
+import { type PgliteClientDatabase } from "./client.js";
+import { type AppMigrations } from "./migrations/migrator.js";
+export interface TestDatabase {
+    readonly db: PgliteClientDatabase;
+    readonly client: PGlite;
+    readonly close: () => Promise<void>;
+}
+export interface CreateTestDatabaseOptions {
+    /**
+     * The app's own migrations, run around the module files as `migrate` runs them. The template is
+     * cached per hook object: define the hooks once, at module level, not inline per call.
+     */
+    readonly app?: AppMigrations;
+}
+/**
+ * A fresh, migrated, in-memory database per call. List the module under test and the modules it
+ * depends on. Throws when a migration (a module file or an app hook) fails: that is a bug in the
+ * module package or the app's migrations.
+ */
+export declare function createTestDatabase(modules?: readonly AnySoftureModule[], options?: CreateTestDatabaseOptions): Promise<TestDatabase>;
+//# sourceMappingURL=testing.d.ts.map

package/dist/testing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAC9C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACzD,OAAO,EAAsB,KAAK,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAC5E,OAAO,EAAkC,KAAK,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAG9F,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,EAAE,oBAAoB,CAAC;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CACrC;AAED,MAAM,WAAW,yBAAyB;IACxC;;;OAGG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,aAAa,CAAC;CAC9B;AAMD;;;;GAIG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,GAAE,SAAS,gBAAgB,EAAO,EAAE,OAAO,GAAE,yBAA8B,GAAG,OAAO,CAAC,YAAY,CAAC,CAIlJ"}