@astralarium/repo-postgres 0.0.0-stage → 0.2.0

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/queue.d.ts

@@ -0,0 +1,86 @@
+import { type Sql, type TransactionSql } from "./sql.ts";
+/** A Cloudflare Queues producer binding, as `enqueueClaimed` sends. */
+export interface Queue<Body> {
+    send(body: Body): Promise<unknown>;
+}
+/** A Cloudflare Queues message, as `consumeClaimed` settles it. */
+export interface QueueMessage<Body> {
+    readonly body: Body;
+    /** Deliveries so far, this one included: 1 on the first. */
+    readonly attempts: number;
+    ack(): void;
+    retry(options?: {
+        delaySeconds?: number;
+    }): void;
+}
+/** A Cloudflare Queues consumer batch. */
+export interface MessageBatch<Body> {
+    /** Queue name. */
+    readonly queue: string;
+    readonly messages: readonly QueueMessage<Body>[];
+}
+/** A claimed task's queue message body. */
+export interface ClaimedTask<Task> {
+    /** Claim key (`claimTask`). */
+    key: string;
+    /** Claim token (`claimTask`). */
+    claim: string;
+    /** Claim window (`claimTask`); a held retry's claim ends one window past
+     *  its due time. */
+    windowSeconds: number;
+    task: Task;
+}
+/** Claims `key` for `windowSeconds`: a fresh token, or undefined while an
+ *  unexpired claim holds it. */
+export declare function claimTask(sql: Sql | TransactionSql, key: string, { windowSeconds }: {
+    windowSeconds: number;
+}): Promise<string | undefined>;
+/** Holds `key`'s claim by `token` through a retry due in `delaySeconds`,
+ *  then `windowSeconds` more, reclaiming a freed key; a later claim
+ *  stays. */
+export declare function holdTask(sql: Sql | TransactionSql, key: string, token: string, { delaySeconds, windowSeconds, }: {
+    delaySeconds: number;
+    windowSeconds: number;
+}): Promise<void>;
+/** Frees `key`'s claim by `token`; a later claim stays. */
+export declare function releaseTask(sql: Sql | TransactionSql, key: string, token: string): Promise<void>;
+/** Sends `task` to `queue` under a fresh claim of `key` (`claimTask`);
+ *  resolves to the claim token, undefined while a claim holds the key.
+ *  A failed send releases the claim and throws the send's error; a failed
+ *  release logs, its claim held for the window. Takes a client outside any
+ *  transaction: the claim commits before the send. */
+export declare function enqueueClaimed<Task>(sql: Sql, queue: Queue<ClaimedTask<Task>>, key: string, task: Task, options: {
+    windowSeconds: number;
+}): Promise<string | undefined>;
+/** How `consumeClaimed` runs a batch's tasks. */
+export interface ConsumeClaimedOptions<Task> {
+    /** The task a message carries; undefined or a throw for one it cannot
+     *  run. */
+    parse: (task: unknown) => Task | undefined;
+    /** Runs one task; a throw fails the attempt. Idempotent: a task can run
+     *  more than once. */
+    run: (task: Task) => Promise<void>;
+    /** The consumer's `max_retries`: retries after the first delivery, an
+     *  integer from 0. */
+    maxRetries: number;
+    /** Milliseconds a `run` throw asks to wait (e.g. `Retry-After`): a finite
+     *  number from 0, or undefined for none. Another value or a throw counts
+     *  as none. */
+    retryAfterMs?: (exception: unknown) => number | undefined;
+}
+/**
+ * Queue consumer of claimed tasks, messages in order. A run acks, keeping
+ * its claim until the window ends: a trigger inside the window coalesces.
+ * A failure retries after 30 s, doubling each attempt, or a longer
+ * `retryAfterMs`, up to 12 hours, holding the claim through the retry
+ * (`holdTask`). The last failure logs, releases the claim and acks; so does
+ * a task `parse` rejects or throws on. A body lacking a claim logs and acks.
+ * A failed claim write logs and the delivery settles as decided: a failed
+ * hold retries, a failed release acks, the key claimed for the window. The
+ * batch continues. Delivery is at-least-once (a queue redelivery reruns a
+ * task): `run` must be idempotent. Takes a client
+ * outside any transaction: each claim write commits before its message
+ * settles. Rejects with a `RangeError` for a `maxRetries` other than an
+ * integer from 0.
+ */
+export declare function consumeClaimed<Task>(sql: Sql, batch: MessageBatch<unknown>, options: ConsumeClaimedOptions<Task>): Promise<void>;

package/dist/src/queue.js

@@ -0,0 +1,201 @@
+/**
+ * Claimed tasks on Cloudflare Queues: a task key queues once per claim
+ * window, its claim (`taskclaim.claim`) held through retries. Needs the
+ * `taskclaim` schema module; `taskclaimJobs` deletes expired claims.
+ *
+ * `enqueueClaimed` and `consumeClaimed` take a client outside any
+ * transaction. `Sql` rejects a `begin` transaction's client; a reserved
+ * connection inside a manual `BEGIN` type-checks, so the requirement rests
+ * on the caller.
+ */
+import { log } from "@astralarium/repo-telemetry";
+import { msInterval } from "./sql.js";
+/** Claims `key` for `windowSeconds`: a fresh token, or undefined while an
+ *  unexpired claim holds it. */
+export async function claimTask(sql, key, { windowSeconds }) {
+    const [claimed] = await sql `
+    INSERT INTO taskclaim.claim AS c (key, expires_at, token)
+    VALUES (
+      ${key},
+      CURRENT_TIMESTAMP + ${msInterval(sql, windowSeconds * 1000)},
+      gen_random_uuid()
+    )
+    ON CONFLICT (key) DO UPDATE SET
+      expires_at = EXCLUDED.expires_at,
+      token = EXCLUDED.token
+    WHERE c.expires_at < CURRENT_TIMESTAMP
+    RETURNING token
+  `;
+    return claimed?.token;
+}
+/** Holds `key`'s claim by `token` through a retry due in `delaySeconds`,
+ *  then `windowSeconds` more, reclaiming a freed key; a later claim
+ *  stays. */
+export async function holdTask(sql, key, token, { delaySeconds, windowSeconds, }) {
+    const held = msInterval(sql, (delaySeconds + windowSeconds) * 1000);
+    await sql `
+    INSERT INTO taskclaim.claim AS c (key, expires_at, token)
+    VALUES (${key}, CURRENT_TIMESTAMP + ${held}, ${token})
+    ON CONFLICT (key) DO UPDATE SET
+      expires_at = EXCLUDED.expires_at
+    WHERE c.token = EXCLUDED.token
+  `;
+}
+/** Frees `key`'s claim by `token`; a later claim stays. */
+export async function releaseTask(sql, key, token) {
+    await sql `
+    DELETE FROM taskclaim.claim
+    WHERE key = ${key} AND token = ${token}
+  `;
+}
+/** Sends `task` to `queue` under a fresh claim of `key` (`claimTask`);
+ *  resolves to the claim token, undefined while a claim holds the key.
+ *  A failed send releases the claim and throws the send's error; a failed
+ *  release logs, its claim held for the window. Takes a client outside any
+ *  transaction: the claim commits before the send. */
+export async function enqueueClaimed(sql, queue, key, task, options) {
+    const claim = await claimTask(sql, key, options);
+    if (!claim)
+        return undefined;
+    try {
+        await queue.send({
+            key,
+            claim,
+            windowSeconds: options.windowSeconds,
+            task,
+        });
+    }
+    catch (sendException) {
+        try {
+            await releaseTask(sql, key, claim);
+        }
+        catch (exception) {
+            log.error("queue.claim_release_failed", "task {key} send failed, then its claim release; key claimed for the window", { key, exception });
+        }
+        throw sendException;
+    }
+    return claim;
+}
+/** Longest delay of a queue retry: Cloudflare Queues' 12 hours. */
+const MAX_RETRY_DELAY_SECONDS = 43_200;
+/** Seconds before the retry of a task's `attempts`th failed delivery: 30,
+ *  doubling each attempt, or a longer `retryAfterMs`; at most
+ *  `MAX_RETRY_DELAY_SECONDS`. A non-finite or negative `retryAfterMs`
+ *  counts as none. */
+function retryDelaySeconds(attempts, retryAfterMs) {
+    const backoff = 30 * 2 ** (attempts - 1);
+    const retryAfter = retryAfterMs !== undefined &&
+        Number.isFinite(retryAfterMs) &&
+        retryAfterMs >= 0
+        ? Math.ceil(retryAfterMs / 1000)
+        : 0;
+    return Math.min(Math.max(backoff, retryAfter), MAX_RETRY_DELAY_SECONDS);
+}
+/** Milliseconds `retryAfterMs` asks to wait after `exception`; undefined
+ *  for none or a throw. */
+function requestedWaitMs(retryAfterMs, exception) {
+    try {
+        return retryAfterMs?.(exception);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** A claim token: a uuid, as `taskclaim.claim.token` stores it. */
+const CLAIM_TOKEN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** `body` as a claimed task envelope; undefined for another shape. */
+function envelopeOf(body) {
+    if (typeof body !== "object" || body === null)
+        return undefined;
+    const { key, claim, windowSeconds, task } = body;
+    return typeof key === "string" &&
+        typeof claim === "string" &&
+        CLAIM_TOKEN.test(claim) &&
+        typeof windowSeconds === "number" &&
+        Number.isFinite(windowSeconds) &&
+        windowSeconds >= 0
+        ? { key, claim, windowSeconds, task }
+        : undefined;
+}
+/**
+ * Queue consumer of claimed tasks, messages in order. A run acks, keeping
+ * its claim until the window ends: a trigger inside the window coalesces.
+ * A failure retries after 30 s, doubling each attempt, or a longer
+ * `retryAfterMs`, up to 12 hours, holding the claim through the retry
+ * (`holdTask`). The last failure logs, releases the claim and acks; so does
+ * a task `parse` rejects or throws on. A body lacking a claim logs and acks.
+ * A failed claim write logs and the delivery settles as decided: a failed
+ * hold retries, a failed release acks, the key claimed for the window. The
+ * batch continues. Delivery is at-least-once (a queue redelivery reruns a
+ * task): `run` must be idempotent. Takes a client
+ * outside any transaction: each claim write commits before its message
+ * settles. Rejects with a `RangeError` for a `maxRetries` other than an
+ * integer from 0.
+ */
+export async function consumeClaimed(sql, batch, options) {
+    const { maxRetries } = options;
+    if (!(Number.isInteger(maxRetries) && maxRetries >= 0))
+        throw new RangeError(`maxRetries must be an integer from 0: ${maxRetries}`);
+    const { queue } = batch;
+    for (const message of batch.messages) {
+        const envelope = envelopeOf(message.body);
+        if (!envelope) {
+            log.warn("queue.message_malformed", "{queue} message lacks a task claim; acked", { queue });
+            message.ack();
+            continue;
+        }
+        const { key, claim, windowSeconds } = envelope;
+        const settlement = await attempt(queue, envelope, message, options);
+        try {
+            if (!settlement.ack) {
+                await holdTask(sql, key, claim, {
+                    delaySeconds: settlement.delaySeconds,
+                    windowSeconds,
+                });
+            }
+            else if (settlement.release) {
+                await releaseTask(sql, key, claim);
+            }
+        }
+        catch (exception) {
+            if (settlement.ack)
+                log.error("queue.claim_release_failed", "{queue} task {key} claim release failed; acked, key claimed for the window", { queue, key, exception });
+            else
+                log.error("queue.claim_hold_failed", "{queue} task {key} claim hold failed; retrying", { queue, key, exception });
+        }
+        if (settlement.ack)
+            message.ack();
+        else
+            message.retry({ delaySeconds: settlement.delaySeconds });
+    }
+}
+/** Parses and runs `envelope`'s task, logging an unparseable or finally
+ *  failed one; resolves to the delivery's settlement. */
+async function attempt(queue, { key, task: body }, { attempts }, { parse, run, maxRetries, retryAfterMs }) {
+    let task;
+    try {
+        task = parse(body);
+    }
+    catch (exception) {
+        log.warn("queue.task_unparseable", "{queue} task {key} unparseable; releasing its claim and acking", { queue, key, exception });
+        return { ack: true, release: true };
+    }
+    if (task === undefined) {
+        log.warn("queue.task_unparseable", "{queue} task {key} unparseable; releasing its claim and acking", { queue, key });
+        return { ack: true, release: true };
+    }
+    try {
+        await run(task);
+        return { ack: true, release: false };
+    }
+    catch (exception) {
+        if (attempts <= maxRetries) {
+            return {
+                ack: false,
+                delaySeconds: retryDelaySeconds(attempts, requestedWaitMs(retryAfterMs, exception)),
+            };
+        }
+        log.error("queue.task_failed", "{queue} task {key} failed after {attempts, plural, one {# attempt} other {# attempts}}", { queue, key, attempts, exception });
+        return { ack: true, release: true };
+    }
+}

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, slug, taskclaim, taskclaimJobs, 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, slug, taskclaim, taskclaimJobs, 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[];

package/dist/src/schema/module.js

@@ -0,0 +1,122 @@
+/** Schema modules: a package's slice of the app database, loaded after
+ *  the modules it requires. psql runs module SQL from the staged schema
+ *  directory (`@astralarium/repo-postgres/provision` `stageSchema`). */
+import { basename, isAbsolute, resolve } from "node:path";
+import { ExpectedError } from "@astralarium/repo-telemetry";
+import { z } from "zod";
+/** Module and staged directory names. */
+const MODULE_NAME = /^[a-z][a-z0-9_-]*$/;
+const moduleName = z.string().regex(MODULE_NAME, {
+    error: "name must be lowercase letters, digits, - and _",
+});
+const absoluteRoot = z
+    .string()
+    .refine(isAbsolute, { error: "root must be absolute" });
+const sqlPath = z
+    .string()
+    .refine((path) => !isAbsolute(path) && path.endsWith(".sql"), {
+    error: "must be a relative .sql path",
+});
+const relativePath = z
+    .string()
+    .min(1)
+    .refine((path) => !isAbsolute(path), { error: "must be a relative path" });
+const absolutePath = z
+    .string()
+    .refine(isAbsolute, { error: "must be an absolute path" });
+const absoluteSqlPath = z
+    .string()
+    .refine((path) => isAbsolute(path) && path.endsWith(".sql"), {
+    error: "must be an absolute .sql path",
+});
+/** Non-empty strings, e.g. extensions or server arguments. */
+export const stringList = z.array(z.string().min(1)).readonly();
+/** `SchemaModule`'s shape; any installed copy of this package matches. */
+const schemaModule = z.object({
+    name: moduleName,
+    root: absoluteRoot,
+    files: z.array(absoluteSqlPath).readonly(),
+    assets: z.array(absolutePath).readonly(),
+    get requires() {
+        return z.array(schemaModule).readonly();
+    },
+    extensions: stringList,
+    preload: stringList,
+    serverArgs: stringList,
+    beforeReset: absoluteSqlPath.optional(),
+    scrub: absoluteSqlPath.optional(),
+});
+/** A value shaped as `defineSchemaModule` returns. */
+export function isSchemaModule(value) {
+    return schemaModule.safeParse(value).success;
+}
+const declaration = z
+    .object({
+    name: moduleName,
+    root: absoluteRoot,
+    files: z.array(sqlPath).readonly(),
+    assets: z.array(relativePath).readonly().optional(),
+    requires: z
+        .array(z.custom(isSchemaModule, {
+        error: "requires must hold defineSchemaModule results",
+    }))
+        .readonly()
+        .optional(),
+    extensions: stringList.optional(),
+    preload: stringList.optional(),
+    serverArgs: stringList.optional(),
+    beforeReset: sqlPath.optional(),
+    scrub: sqlPath.optional(),
+})
+    .refine(({ files, assets = [] }) => {
+    const paths = [...files, ...assets];
+    return new Set(paths.map((path) => basename(path))).size === paths.length;
+}, { error: "files and assets must have unique basenames" });
+/** A schema module; the declaration is validated (`ExpectedError`). */
+export function defineSchemaModule(module) {
+    const result = declaration.safeParse(module);
+    if (!result.success)
+        throw new ExpectedError(`invalid schema module ${module.name}:\n${z.prettifyError(result.error)}`);
+    const { root } = module;
+    return Object.freeze({
+        name: module.name,
+        root,
+        files: module.files.map((file) => resolve(root, file)),
+        assets: (module.assets ?? []).map((asset) => resolve(root, asset)),
+        requires: [...(module.requires ?? [])],
+        extensions: [...(module.extensions ?? [])],
+        preload: [...(module.preload ?? [])],
+        serverArgs: [...(module.serverArgs ?? [])],
+        ...(module.beforeReset && {
+            beforeReset: resolve(root, module.beforeReset),
+        }),
+        ...(module.scrub && { scrub: resolve(root, module.scrub) }),
+    });
+}
+/**
+ * `modules` and their `requires` closure in load order. One name on two
+ * module objects (two installed copies of a package) is an `ExpectedError`.
+ */
+export function loadOrder(modules) {
+    const order = [];
+    const seen = new Set();
+    // Declarations reference already-defined modules: the graph is acyclic.
+    const visit = (module) => {
+        if (seen.has(module))
+            return;
+        seen.add(module);
+        for (const required of module.requires)
+            visit(required);
+        order.push(module);
+    };
+    for (const module of modules)
+        visit(module);
+    const named = new Map();
+    for (const module of order) {
+        const held = named.get(module.name);
+        if (held)
+            throw new ExpectedError(`schema module ${module.name} is declared twice, from ${held.root} and ${module.root}; install one copy of its package`);
+        named.set(module.name, module);
+    }
+    return order;
+}

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

@@ -0,0 +1,24 @@
+/** The `app` schema: owned by `app_admin`, used by `app_service`. */
+export declare const appSchema: import("./module.ts").SchemaModule;
+/** pg_partman in schema `partman`, granted to `app_admin`; `reset.sql`
+ *  clears its config for the dropped schemas. */
+export declare const partman: import("./module.ts").SchemaModule;
+/** Schema `slug`: `slug.slug(name)`, a name's URL slug (NFC, lowercase
+ *  alphanumerics, spaces as `-`), immutable. */
+export declare const slug: import("./module.ts").SchemaModule;
+/** Schema `taskclaim`: table `taskclaim.claim`, one claim per task key,
+ *  for `@astralarium/repo-postgres/queue`, and `taskclaim.delete_expired()`;
+ *  a snapshot's scrub empties it. */
+export declare const taskclaim: import("./module.ts").SchemaModule;
+/** pg_trgm, for trigram (name) search. */
+export declare const trgm: import("./module.ts").SchemaModule;
+/**
+ * pg_cron on persistent instances, running jobs in `db_template`; job
+ * `cron-history-ttl` deletes run history past 7 days daily.
+ * Disposable instances skip it: its background worker holds
+ * `db_template` open, and test databases clone it as a template, which
+ * needs it idle.
+ */
+export declare const cron: import("./module.ts").SchemaModule;
+/** pg_cron job `taskclaim-ttl`: `taskclaim.delete_expired()` hourly. */
+export declare const taskclaimJobs: import("./module.ts").SchemaModule;