@astralarium/repo-postgres 0.0.0-stage → 0.1.0

package/dist/src/provision/index.js

@@ -0,0 +1,205 @@
+/**
+ * Postgres as a `DatabaseProvider`: the app's schema image, one persistent
+ * container per checkout for dev, a disposable one per test run.
+ */
+import { isAbsolute } from "node:path";
+import { keepOrFindPort, RESOURCE_NAME, succeeds, } from "@astralarium/repo-dev";
+import { ExpectedError, log } from "@astralarium/repo-telemetry";
+import { z } from "zod";
+import { isSchemaModule, loadOrder, stringList, } from "../schema/module.js";
+import { adminConnectionString, APP_SERVICE_ROLE, appConnectionString, DEFAULT_PORT, probePostgres, } from "./connection.js";
+import { claimable, detectRuntime, holders, inspectContainer, OWNER_LABEL, removeContainer, removeVolume, StaleSchemaError, startPostgresContainer, volumeName, } from "./container.js";
+import { loadData } from "./data.js";
+import { checkDumpExclude, migrationMounts, requireFile, runDisposableServer, runUpgradeDump, } from "./disposable.js";
+import { buildImages, ensureImage, ensureUtilImage, schemaHash, writeTestImage, } from "./image.js";
+import { moduleServerArgs, stageSchema } from "./schema.js";
+import { startTestInstance, } from "./test-database.js";
+export { APP_SERVICE_ROLE } from "./connection.js";
+export { ensureUtilImage } from "./image.js";
+/** Container names tried per base: `<base>`, `<base>-2`, … */
+const NAME_ATTEMPTS = 100;
+const postgresOptions = z.object({
+    modules: z
+        .array(z.custom(isSchemaModule, {
+        error: "modules must hold defineSchemaModule results",
+    }))
+        .min(1, { error: "modules lists no schema module" })
+        .readonly()
+        .check((ctx) => {
+        try {
+            loadOrder(ctx.value);
+        }
+        catch (cause) {
+            ctx.issues.push({
+                code: "custom",
+                input: ctx.value,
+                message: cause instanceof Error ? cause.message : String(cause),
+            });
+        }
+    }),
+    name: z.string().regex(RESOURCE_NAME, {
+        error: "name must be a container resource name",
+    }),
+    serverArgs: stringList.optional(),
+    ephemeralArgs: stringList.optional(),
+    data: z
+        .array(z.string().refine(isAbsolute, { error: "data paths must be absolute" }))
+        .readonly()
+        .optional(),
+});
+class Postgres {
+    name;
+    #options;
+    #runtime;
+    constructor(options) {
+        this.#options = options;
+        this.name = options.name;
+    }
+    /** Detected once per process. */
+    get runtime() {
+        return (this.#runtime ??= detectRuntime());
+    }
+    async allocate({ base, owner, saved, }) {
+        const runtime = this.runtime;
+        const names = [
+            base,
+            ...Array.from({ length: NAME_ATTEMPTS - 1 }, (_, i) => `${base}-${i + 2}`),
+        ];
+        const name = [
+            ...new Set([
+                ...(saved.name && names.includes(saved.name) ? [saved.name] : []),
+                ...names,
+            ]),
+        ].find((candidate) => claim(runtime, candidate, owner));
+        if (!name)
+            throw new ExpectedError(`no free container name from ${base} to ${names.at(-1)}`);
+        // A claimable container is this checkout's: a running one keeps its port.
+        const container = inspectContainer(runtime, name);
+        const port = container?.running && container.bindings[0]?.HostPort
+            ? Number(container.bindings[0].HostPort)
+            : await keepOrFindPort(saved.port, DEFAULT_PORT);
+        return { name, port };
+    }
+    async ensure(resources, { allocation: { name, port }, image, owner, program, }) {
+        const options = this.#options;
+        const runtime = this.runtime;
+        const hash = schemaHash(options);
+        const resetHint = `${program} reset --db-name ${image} recreates it; this deletes local data.`;
+        try {
+            await startPostgresContainer(runtime, resources, {
+                name,
+                image: ensureImage(options, runtime, hash, image),
+                hash,
+                port,
+                volume: volumeName(name),
+                owner,
+                serverArgs: [
+                    ...moduleServerArgs(options.modules),
+                    ...(options.serverArgs ?? []),
+                ],
+            });
+        }
+        catch (cause) {
+            if (cause instanceof StaleSchemaError)
+                throw new ExpectedError(`${cause.message} ${resetHint}`, { cause });
+            throw cause;
+        }
+        try {
+            await probePostgres(appConnectionString(port, "db_template"));
+        }
+        catch (cause) {
+            throw new ExpectedError(`${name}: ${APP_SERVICE_ROLE} cannot connect to db_template with the dev credentials. Inspect the database, or ${resetHint}`, { cause });
+        }
+        await loadData(adminConnectionString(port, "db_template"), options.data ?? []);
+        log.info("dev.db_ready", "{name}: ready on :{port}", { name, port });
+    }
+    reset(name, image) {
+        removeContainer(this.runtime, name);
+        removeVolume(this.runtime, volumeName(name));
+        this.build(image);
+    }
+    stop(name, owner) {
+        let runtime;
+        try {
+            runtime = this.runtime;
+        }
+        catch {
+            return;
+        }
+        if (claimable(runtime, name, owner))
+            succeeds(runtime, ["stop", name]);
+    }
+    build(image) {
+        buildImages(this.#options, this.runtime, schemaHash(this.#options), {
+            name: image,
+            refreshBase: true,
+        });
+    }
+    async runDisposable({ allocation, image, serverArgs, snapshot, signal, }) {
+        if (snapshot)
+            requireFile(snapshot.dump);
+        await runDisposableServer(this.runtime, {
+            name: `${allocation.name}-${snapshot ? "snapshot" : "temp"}`,
+            image: this.#image(image),
+            port: await keepOrFindPort(undefined, DEFAULT_PORT, new Set([allocation.port])),
+            serverArgs,
+            snapshot,
+            signal,
+        });
+    }
+    async upgradeDump({ allocation, image, migrations, signal, }) {
+        const mounts = migrationMounts(migrations);
+        // eslint-disable-next-line turbo/no-undeclared-env-vars -- no turbo task runs this CLI
+        checkDumpExclude(process.env.DB_DUMP_EXCLUDE);
+        await runUpgradeDump(this.runtime, {
+            name: `${allocation.name}-upgrade`,
+            image: this.#image(image),
+            util: ensureUtilImage(this.runtime, image),
+            mounts,
+            signal,
+        });
+    }
+    /** This checkout's schema image under base name `image`, built when
+     *  missing: its immutable ID. */
+    #image(image) {
+        return ensureImage(this.#options, this.runtime, schemaHash(this.#options), image);
+    }
+    connectionString({ port }) {
+        return appConnectionString(port, "db_template");
+    }
+    startTestInstance(resources, name) {
+        return startTestInstance(resources, name, this.#options);
+    }
+    writeTestImage(file) {
+        writeTestImage(this.#options, file);
+    }
+    stageSchema(dir) {
+        stageSchema(this.#options.modules, dir);
+    }
+}
+/**
+ * `claimable`, naming each holder of `name` lacking `OWNER_LABEL` (a
+ * container or data volume) and the command freeing it: that holder keeps
+ * the name and its port from every checkout.
+ */
+function claim(runtime, name, owner) {
+    const held = holders(runtime, name);
+    if (held.every((holder) => holder.owner === owner))
+        return true;
+    for (const holder of held)
+        if (holder.owner === undefined)
+            log.warn("dev.db_name_held", "{kind, select, volume {Data volume} other {Container}} {name} carries no {label} label, so this checkout skips the name; free it with: {remove}", {
+                kind: holder.kind,
+                name: holder.name,
+                label: OWNER_LABEL,
+                remove: `${runtime} ${holder.kind === "volume" ? "volume rm" : "rm -f"} ${holder.name}`,
+            });
+    return false;
+}
+/** The app's Postgres provider; the declaration is validated (`ExpectedError`). */
+export function postgresDatabase(options) {
+    const result = postgresOptions.safeParse(options);
+    if (!result.success)
+        throw new ExpectedError(`invalid Postgres options:\n${z.prettifyError(result.error)}`);
+    return new Postgres(options);
+}

package/dist/src/provision/options.d.ts

@@ -0,0 +1,23 @@
+import type { SchemaModule } from "../schema/module.ts";
+/** What an app declares for its Postgres image and local instances. */
+export interface PostgresOptions {
+    /**
+     * The app's schema modules; their `requires` load too. Files hash into
+     * the image tag; extensions install in the image; `preload` and
+     * `serverArgs` reach the dev instance.
+     */
+    modules: readonly SchemaModule[];
+    /** Image and instance base name; `DB_NAME` and `--db-name` override it. */
+    name: string;
+    /** Postgres server arguments for the dev instance, after the modules'. */
+    serverArgs?: readonly string[];
+    /** Postgres server arguments for disposable (test) instances; stock Postgres by default. */
+    ephemeralArgs?: readonly string[];
+    /**
+     * Data SQL after the schema: absolute `.sql` files, or directories whose
+     * `*.sql` run in name order. Loads into `db_template` on every dev start
+     * and once per test run, before project databases clone it; idempotent.
+     * Its digest joins the test image manifest.
+     */
+    data?: readonly string[];
+}

package/dist/src/provision/options.js

@@ -0,0 +1 @@
+export {};

package/dist/src/provision/schema.d.ts

@@ -0,0 +1,11 @@
+import { type SchemaModule } from "../schema/module.ts";
+/** sha256 over the staged psql entries, then the module file, asset,
+ *  `beforeReset` and `scrub` paths and contents, in load order. */
+export declare function schemaDigest(modules: readonly SchemaModule[]): string;
+/** Extensions every module installs, deduplicated in load order. */
+export declare function moduleExtensions(modules: readonly SchemaModule[]): string[];
+/** Persistent-instance server arguments: one `shared_preload_libraries`
+ *  over every module's `preload`, then each module's `serverArgs`. */
+export declare function moduleServerArgs(modules: readonly SchemaModule[]): string[];
+/** Writes the staged directory under `dir`, creating it. */
+export declare function stageSchema(modules: readonly SchemaModule[], dir: string): void;

package/dist/src/provision/schema.js

@@ -0,0 +1,134 @@
+/**
+ * The app's schema modules as psql loads them: a staged directory holding
+ * `schema.sql` (one `\i sql/<module>/<file>` per module file, in load
+ * order) beside `sql/` (each module's files and assets),
+ * `before-reset.sql` and `before-reset/` (each module's `beforeReset`),
+ * `scrub.sql` and `scrub/` (each module's `scrub`), and this package's
+ * `roles.sql`, `database-grants.sql`, `bootstrap.sql`, `reset.sql` and
+ * `drop-schemas.sql`. psql runs every entry with this directory as cwd.
+ * The image bakes it and runs `roles.sql`, `database-grants.sql`, then
+ * `schema.sql`, at first boot.
+ */
+import { createHash } from "node:crypto";
+import { copyFileSync, mkdirSync, readdirSync, readFileSync, writeFileSync, } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { packageRoot } from "@astralarium/repo-package-files";
+import { ExpectedError } from "@astralarium/repo-telemetry";
+import { loadOrder } from "../schema/module.js";
+/** Entry psql runs from the staged directory. */
+const SCHEMA_ENTRY = "schema.sql";
+/** Directory of the staged module files, beside the entry. */
+const SCHEMA_FILES = "sql";
+/** Entry `reset.sql` runs ahead of its drop. */
+const BEFORE_RESET_ENTRY = "before-reset.sql";
+/** Directory of the staged `beforeReset` files. */
+const BEFORE_RESET_FILES = "before-reset";
+/** Entry a snapshot runs after its dump loads. */
+const SCRUB_ENTRY = "scrub.sql";
+/** Directory of the staged `scrub` files. */
+const SCRUB_FILES = "scrub";
+/** Each module's `files` or `assets` in load order, under `sql/<module>/`. */
+function moduleFiles(order, kind) {
+    return order.flatMap((module) => module[kind].map((path) => ({
+        staged: `${SCHEMA_FILES}/${module.name}/${basename(path)}`,
+        path,
+    })));
+}
+/** Each module's `beforeReset` or `scrub` in load order, as
+ *  `<dir>/<module>.sql`. */
+function moduleScripts(order, kind, dir) {
+    return order.flatMap((module) => {
+        const path = module[kind];
+        return path ? [{ staged: `${dir}/${module.name}.sql`, path }] : [];
+    });
+}
+/** Every staged module file, asset, `beforeReset` and `scrub` file, in load
+ *  order. */
+function stagedFiles(order) {
+    return [
+        ...moduleFiles(order, "files"),
+        ...moduleFiles(order, "assets"),
+        ...moduleScripts(order, "beforeReset", BEFORE_RESET_FILES),
+        ...moduleScripts(order, "scrub", SCRUB_FILES),
+    ];
+}
+/** psql entry including `files` in order. */
+function entry(header, files) {
+    return [header, ...files.map((file) => `\\i ${file.staged}`), ""].join("\n");
+}
+/** Staged psql entries as `[file name, text]`. */
+function entries(order) {
+    return [
+        [
+            SCHEMA_ENTRY,
+            entry("-- Schema load order, staged by @astralarium/repo-postgres from the app's schema modules.\n-- Run connected to the app database, after roles.sql and database-grants.sql.", moduleFiles(order, "files")),
+        ],
+        [
+            BEFORE_RESET_ENTRY,
+            entry("-- Each schema module's beforeReset in load order, staged by @astralarium/repo-postgres.\n-- Run by reset.sql as app_admin, inside its transaction.", moduleScripts(order, "beforeReset", BEFORE_RESET_FILES)),
+        ],
+        [
+            SCRUB_ENTRY,
+            entry("-- Each schema module's scrub in load order, staged by @astralarium/repo-postgres.\n-- Run by run-snapshot as superuser in db_template, inside one transaction.", moduleScripts(order, "scrub", SCRUB_FILES)),
+        ],
+    ];
+}
+/** The file's contents; a missing file names the path and its likely cause. */
+function readSchemaFile({ path }) {
+    try {
+        return readFileSync(path);
+    }
+    catch (cause) {
+        throw new ExpectedError(`schema file ${path} is missing: check the module declaring it, or install the package providing it`, { cause });
+    }
+}
+/** sha256 over the staged psql entries, then the module file, asset,
+ *  `beforeReset` and `scrub` paths and contents, in load order. */
+export function schemaDigest(modules) {
+    const order = loadOrder(modules);
+    const hash = createHash("sha256");
+    for (const [name, text] of entries(order)) {
+        hash.update(`${name}\0`);
+        hash.update(text);
+        hash.update("\0");
+    }
+    for (const file of stagedFiles(order)) {
+        hash.update(`${file.staged}\0`);
+        hash.update(readSchemaFile(file));
+        hash.update("\0");
+    }
+    return hash.digest("hex");
+}
+/** Extensions every module installs, deduplicated in load order. */
+export function moduleExtensions(modules) {
+    return [
+        ...new Set(loadOrder(modules).flatMap((module) => module.extensions)),
+    ];
+}
+/** Persistent-instance server arguments: one `shared_preload_libraries`
+ *  over every module's `preload`, then each module's `serverArgs`. */
+export function moduleServerArgs(modules) {
+    const order = loadOrder(modules);
+    const preload = [...new Set(order.flatMap((module) => module.preload))];
+    return [
+        ...(preload.length
+            ? ["-c", `shared_preload_libraries=${preload.join(",")}`]
+            : []),
+        ...order.flatMap((module) => module.serverArgs),
+    ];
+}
+/** Writes the staged directory under `dir`, creating it. */
+export function stageSchema(modules, dir) {
+    const order = loadOrder(modules);
+    for (const file of stagedFiles(order)) {
+        const target = join(dir, file.staged);
+        mkdirSync(dirname(target), { recursive: true });
+        writeFileSync(target, readSchemaFile(file));
+    }
+    for (const [name, text] of entries(order))
+        writeFileSync(join(dir, name), text);
+    const scripts = join(packageRoot(import.meta.filename), "sql");
+    for (const name of readdirSync(scripts))
+        if (name.endsWith(".sql"))
+            copyFileSync(join(scripts, name), join(dir, name));
+}

package/dist/src/provision/test-database.d.ts

@@ -0,0 +1,29 @@
+import { type ResourceScope, type TestContainer, type TestDatabase } from "@astralarium/repo-dev";
+import type { PostgresOptions } from "./options.ts";
+/** Running seeded instance; fixtures may run tools in its container or network namespace. */
+export declare class PostgresTestDatabase implements TestDatabase {
+    /** Published loopback port. */
+    readonly port: number;
+    /** Container running the instance; other containers join its network
+     *  namespace. */
+    readonly container: TestContainer;
+    constructor(instance: {
+        port: number;
+        container: TestContainer;
+    });
+    /**
+     * `CREATE DATABASE … TEMPLATE db_template`; returns the `app_service`
+     * connection. A project whose name maps to an existing database is an
+     * `ExpectedError`.
+     */
+    createDatabase(name: string): Promise<string>;
+    /** `postgres` connection to the project database. */
+    adminConnectionString(name: string): string;
+}
+/**
+ * Sweeps stale test containers (`sweepTestInstances`), then starts
+ * `db-test-<name>-<uuid>`, labeled with this process's pid, on an assigned
+ * loopback port and loads the app's data into `db_template` (`testImage`).
+ * The run's resources remove the container and its data at teardown.
+ */
+export declare function startTestInstance(resources: ResourceScope, name: string, options: PostgresOptions): Promise<PostgresTestDatabase>;

package/dist/src/provision/test-database.js

@@ -0,0 +1,130 @@
+/** Postgres instance per test run; a database per project. */
+import { randomUUID } from "node:crypto";
+import { existsSync } from "node:fs";
+import { output, succeeds, } from "@astralarium/repo-dev";
+import { ExpectedError } from "@astralarium/repo-telemetry";
+import { isSqlstate, SQLSTATE, withSql } from "../sql.js";
+import { adminConnectionString, appConnectionString, probePostgres, } from "./connection.js";
+import { removeContainer, startPostgresContainer } from "./container.js";
+import { dataDigest, loadData } from "./data.js";
+import { prepareTestImage, readTestImage, schemaHash, } from "./image.js";
+/** Name prefix of every test instance's container. */
+const TEST_PREFIX = "db-test-";
+/** Test container label carrying the pid of the process that owns it. */
+const TEST_OWNER_LABEL = "db.test-pid";
+/** Running seeded instance; fixtures may run tools in its container or network namespace. */
+export class PostgresTestDatabase {
+    /** Published loopback port. */
+    port;
+    /** Container running the instance; other containers join its network
+     *  namespace. */
+    container;
+    constructor(instance) {
+        this.port = instance.port;
+        this.container = instance.container;
+    }
+    /**
+     * `CREATE DATABASE … TEMPLATE db_template`; returns the `app_service`
+     * connection. A project whose name maps to an existing database is an
+     * `ExpectedError`.
+     */
+    async createDatabase(name) {
+        const database = testDatabaseName(name);
+        try {
+            await withSql(adminConnectionString(this.port, "postgres"), (sql) => sql `CREATE DATABASE ${sql(database)} TEMPLATE db_template`);
+        }
+        catch (cause) {
+            if (isSqlstate(cause, SQLSTATE.duplicateDatabase))
+                throw new ExpectedError(`Test project ${name} maps to database ${database}, which another project already uses; rename one`, { cause });
+            throw cause;
+        }
+        return appConnectionString(this.port, database);
+    }
+    /** `postgres` connection to the project database. */
+    adminConnectionString(name) {
+        return adminConnectionString(this.port, testDatabaseName(name));
+    }
+}
+/**
+ * The DB_TEST_IMAGE manifest when built for `options.name`, an
+ * `ExpectedError` when malformed or built from other schema or data
+ * sources; otherwise, the file unset or missing included, the schema
+ * image prepared locally.
+ */
+function testImage(options) {
+    const file = process.env.DB_TEST_IMAGE;
+    const supplied = file && existsSync(file) ? readTestImage(file) : undefined;
+    if (supplied?.name !== options.name)
+        return prepareTestImage(options);
+    if (supplied.hash !== schemaHash(options) ||
+        supplied.data !== dataDigest(options.data ?? []))
+        throw new ExpectedError(`${file} was prepared from other schema or data sources than the current ones; rerun the app's db:image task to regenerate it`);
+    return supplied;
+}
+/** Process `pid` has exited. */
+function exited(pid) {
+    try {
+        process.kill(pid, 0);
+        return false;
+    }
+    catch (error) {
+        return error.code === "ESRCH";
+    }
+}
+/**
+ * Removes test containers left by earlier runs whose `TEST_OWNER_LABEL`
+ * process has exited. Best effort; a container another run removes first
+ * is fine.
+ */
+function sweepTestInstances(runtime) {
+    const listed = output(runtime, [
+        "ps",
+        "-a",
+        "--filter",
+        `name=^${TEST_PREFIX}`,
+        "--format",
+        `{{.Names}}\t{{.Label "${TEST_OWNER_LABEL}"}}`,
+    ]);
+    for (const line of listed?.split("\n") ?? []) {
+        const [name, label] = line.split("\t");
+        if (!name?.startsWith(TEST_PREFIX))
+            continue;
+        const pid = Number(label);
+        if (Number.isInteger(pid) && pid > 0 && exited(pid))
+            succeeds(runtime, ["rm", "-f", "-v", name]);
+    }
+}
+/**
+ * Sweeps stale test containers (`sweepTestInstances`), then starts
+ * `db-test-<name>-<uuid>`, labeled with this process's pid, on an assigned
+ * loopback port and loads the app's data into `db_template` (`testImage`).
+ * The run's resources remove the container and its data at teardown.
+ */
+export async function startTestInstance(resources, name, options) {
+    resources.signal.throwIfAborted();
+    const { runtime, hash, image } = testImage(options);
+    sweepTestInstances(runtime);
+    const container = `${TEST_PREFIX}${name}-${randomUUID()}`;
+    resources.own({ dispose: () => removeContainer(runtime, container) });
+    const { port } = await startPostgresContainer(runtime, resources, {
+        name: container,
+        hash,
+        image,
+        serverArgs: options.ephemeralArgs,
+        labels: { [TEST_OWNER_LABEL]: String(process.pid) },
+    });
+    const connectionString = adminConnectionString(port, "db_template");
+    await probePostgres(connectionString);
+    await loadData(connectionString, options.data ?? []);
+    return new PostgresTestDatabase({
+        port,
+        container: { runtime, name: container },
+    });
+}
+/** SQL identifier derived from a nonempty project name. */
+function testDatabaseName(name) {
+    const database = name.replace(/[^a-z0-9_]/gi, "_").toLowerCase();
+    if (!database || database.length > 63)
+        throw new Error("Test project names must contain 1–63 characters");
+    return database;
+}

package/dist/src/schema/index.d.ts

@@ -0,0 +1,3 @@
+/** Schema modules: each package's slice of the app database. */
+export { defineSchemaModule, type SchemaModule, type SchemaModuleDeclaration, } from "./module.ts";
+export { appSchema, cron, partman, trgm } from "./modules.ts";

package/dist/src/schema/index.js

@@ -0,0 +1,3 @@
+/** Schema modules: each package's slice of the app database. */
+export { defineSchemaModule, } from "./module.js";
+export { appSchema, cron, partman, trgm } from "./modules.js";

package/dist/src/schema/module.d.ts

@@ -0,0 +1,59 @@
+import { z } from "zod";
+/** What a package declares for its slice of the app database. */
+export interface SchemaModuleDeclaration {
+    /** Unique per install; names the module's staged directory. */
+    name: string;
+    /** Absolute directory `files`, `assets`, `beforeReset` and `scrub`
+     *  resolve from: an app's SQL directory, or a package's
+     *  `packageRoot(import.meta.filename)`. */
+    root: string;
+    /** SQL in load order, relative to `root`; basenames unique across `files`
+     *  and `assets`. psql runs it connected to the app database, after the
+     *  roles exist, with the staged directory as cwd: this module's files and
+     *  assets sit at `sql/<name>/<basename>`. `reset.sql` runs every module's
+     *  SQL inside one transaction. */
+    files: readonly string[];
+    /** Files the module's SQL reads via psql (e.g. `\copy` CSVs), relative to
+     *  `root`, any extension; staged beside `files`. */
+    assets?: readonly string[];
+    /** Modules loading first; also those the module's queries read at runtime. */
+    requires?: readonly SchemaModule[];
+    /** Extensions the image installs: Debian `postgresql-<major>-<name>` packages. */
+    extensions?: readonly string[];
+    /** `shared_preload_libraries` entries for persistent instances. */
+    preload?: readonly string[];
+    /** Further Postgres server arguments for persistent instances. */
+    serverArgs?: readonly string[];
+    /** SQL relative to `root`, run as `app_admin` inside `reset.sql`'s
+     *  transaction before it drops the schemas. */
+    beforeReset?: string;
+    /** SQL relative to `root`, run by `run-snapshot` as superuser in
+     *  `db_template` after the dump loads, with the staged directory as cwd;
+     *  every module's scrub runs inside one transaction. Clears
+     *  environment-bound state (credentials, deploy state, build-keyed rows). */
+    scrub?: string;
+}
+/** A declared module: paths absolute, every list present. */
+export interface SchemaModule {
+    readonly name: string;
+    readonly root: string;
+    readonly files: readonly string[];
+    readonly assets: readonly string[];
+    readonly requires: readonly SchemaModule[];
+    readonly extensions: readonly string[];
+    readonly preload: readonly string[];
+    readonly serverArgs: readonly string[];
+    readonly beforeReset?: string;
+    readonly scrub?: string;
+}
+/** Non-empty strings, e.g. extensions or server arguments. */
+export declare const stringList: z.ZodReadonly<z.ZodArray<z.ZodString>>;
+/** A value shaped as `defineSchemaModule` returns. */
+export declare function isSchemaModule(value: unknown): value is SchemaModule;
+/** A schema module; the declaration is validated (`ExpectedError`). */
+export declare function defineSchemaModule(module: SchemaModuleDeclaration): SchemaModule;
+/**
+ * `modules` and their `requires` closure in load order. One name on two
+ * module objects (two installed copies of a package) is an `ExpectedError`.
+ */
+export declare function loadOrder(modules: readonly SchemaModule[]): SchemaModule[];