@intentius/sql-yodeler 0.0.0-stage → 0.2.0

package/dist/versioned/op.js

@@ -0,0 +1,185 @@
+/**
+ * The approval: a versioned apply runs as a chant Op, behind a gate bound to
+ * the plan digest, the same machinery #6's declarative apply runs through.
+ *
+ * The project declares one Op per environment:
+ *
+ *   Plan     shell("yodel apply <env> --digest", { id: "plan" })
+ *            prints the digest of the pending migrations and the live schema
+ *   Approve  gate(..., { plan: stepOutput(plan, "stdout") })
+ *            a resolution counts only for that digest (`chant approve <op> <gate> --plan <digest>`)
+ *   Apply    shell("yodel apply <env> --execute", { env: { YODEL_APPROVED_PLAN: stepOutput(plan, "stdout") } })
+ *            takes the lock, computes the digest again, refuses if it moved, applies
+ *
+ * `yodel apply <env>` runs it with `chant run <op>`, as #6 runs an ApplyOp.
+ * The gate ledger is chant's (the `chant/lifecycle` branch); yodel keeps no
+ * approval store of its own. The digest is checked twice: by the gate, on
+ * every run, against the approval; and by the Apply step, under the lock,
+ * against the digest the gate passed, so a change between the two (another
+ * runner applying, a table altered out of band) refuses too.
+ *
+ * `chant run <op>` run directly (in CI) needs `yodel` on PATH, e.g.
+ * `PATH="$PWD/node_modules/.bin:$PATH"`. When `yodel apply` runs it, yodel
+ * puts a `yodel` that runs itself first on the child's PATH.
+ */
+import { chmodSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { delimiter, extname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { YodelError } from "../project.js";
+import { chantInstall, runChant } from "../chant/process.js";
+import { discoveryError, GATED, readApplyRun } from "../chant/apply.js";
+/** The env var the Apply step reads the approved digest from. */
+export const APPROVED_PLAN_ENV = "YODEL_APPROVED_PLAN";
+/** Passes `--allow-out-of-order` through `chant run` to the Op's steps. */
+export const ALLOW_OUT_OF_ORDER_ENV = "YODEL_ALLOW_OUT_OF_ORDER";
+const command = (verb) => new RegExp(`^(?:npx\\s+)?yodel\\s+apply\\s+(\\S+)\\s+${verb}(?:\\s|$)`);
+const DIGEST = command("--digest");
+const EXECUTE = command("--execute");
+const steps = (config) => config.phases.flatMap((p) => p.steps);
+function shellCmd(step) {
+    if (step.kind !== "activity" || step.fn !== "shellCmd")
+        return undefined;
+    const cmd = step.args?.cmd;
+    return typeof cmd === "string" ? { cmd: cmd.trim(), ...(step.id ? { id: step.id } : {}) } : undefined;
+}
+/** The parts of a migrations Op for `env`, when `config` is one. */
+export function migrateOpParts(config, env) {
+    const all = steps(config);
+    const plan = all.map(shellCmd).find((s) => s && DIGEST.exec(s.cmd)?.[1] === env);
+    const execute = all.map(shellCmd).find((s) => s && EXECUTE.exec(s.cmd)?.[1] === env);
+    if (!plan || !execute)
+        return undefined;
+    const gate = all.find((s) => {
+        if (s.kind !== "gate" || s.plan === undefined || typeof s.plan === "string")
+            return false;
+        return s.plan.step === plan.id;
+    });
+    return gate?.kind === "gate" ? { gate: gate.gate, quorum: gate.approval !== undefined } : { gate: undefined, quorum: false };
+}
+/** How to declare the Op `yodel apply` looks for. */
+export function migrateOpExample(env) {
+    return [
+        `// ops/migrate-${env}.op.ts`,
+        `import { Op, phase, gate, shell, stepOutput } from "@intentius/chant/op";`,
+        ``,
+        `const plan = shell("yodel apply ${env} --digest", { id: "plan" });`,
+        `const digest = stepOutput(plan, "stdout");`,
+        ``,
+        `export const op = Op({`,
+        `  name: "migrate-${env}",`,
+        `  overview: "Apply the pending migrations to ${env}, behind an approval bound to their plan digest",`,
+        `  phases: [`,
+        `    phase("Plan", [plan]),`,
+        `    phase("Approve", [gate("approve-migrate-${env}", { plan: digest })]),`,
+        `    phase("Apply", [shell("yodel apply ${env} --execute", { env: { ${APPROVED_PLAN_ENV}: digest }, timeout: "2h" })]),`,
+        `  ],`,
+        `});`,
+    ].join("\n");
+}
+/** Picks the migrations Op for `env` from discovered Ops. Pure. */
+export function selectMigrateOp(ops, project, env, name) {
+    const found = [...ops.values()].flatMap((o) => {
+        const parts = migrateOpParts(o.config, env.name);
+        return parts ? [{ ...o, parts }] : [];
+    });
+    const chosen = name ? found.filter((o) => o.config.name === name) : found;
+    if (chosen.length === 0) {
+        if (name && ops.has(name))
+            throw new YodelError(`Op "${name}" is not a migrations Op for environment ${env.name} (a Plan step running "yodel apply ${env.name} --digest", a gate bound to it, an Apply step running "yodel apply ${env.name} --execute")`);
+        throw new YodelError(name
+            ? `no Op named "${name}" in ${project.dir}`
+            : `no Op applies the migrations to environment ${env.name} in ${project.dir}; declare one, for example:\n\n${migrateOpExample(env.name)}`);
+    }
+    if (chosen.length > 1)
+        throw new YodelError(`${String(chosen.length)} Ops apply the migrations to ${env.name} (${chosen.map((o) => o.config.name).join(", ")}); pick one with --op <name>`);
+    const [op] = chosen;
+    if (!op.parts.gate) {
+        throw new YodelError(`Op "${op.config.name}" (${op.filePath}) has no approval gate bound to its Plan step's digest, and yodel only applies behind one; give it gate(..., { plan: stepOutput(plan, "stdout") })`);
+    }
+    return { name: op.config.name, filePath: op.filePath, gate: op.parts.gate, quorum: op.parts.quorum };
+}
+export async function findMigrateOp(project, env, name) {
+    const { discoverOps } = await import("@intentius/chant/op/discover");
+    let found;
+    try {
+        found = await discoverOps({ cwd: project.dir });
+    }
+    catch (e) {
+        throw discoveryError(project.dir, e);
+    }
+    if (found.errors.length > 0 && found.ops.size === 0)
+        throw new YodelError(`could not discover Ops in ${project.dir}:\n${found.errors.join("\n")}`);
+    return selectMigrateOp(found.ops, project, env, name);
+}
+/** This yodel's own entry point: `bin.js` when built, `bin.ts` from source. */
+function selfEntry() {
+    const here = fileURLToPath(import.meta.url);
+    return fileURLToPath(new URL(`../bin${extname(here)}`, import.meta.url));
+}
+/** A directory holding a `yodel` that runs this yodel, for a child's PATH. */
+export function yodelShim() {
+    const dir = mkdtempSync(join(tmpdir(), "yodel-shim-"));
+    const q = (s) => `'${s.replace(/'/g, `'\\''`)}'`;
+    const script = `#!/bin/sh\nexec ${q(process.execPath)} --import ${q(chantInstall().loader)} ${q(selfEntry())} "$@"\n`;
+    const path = join(dir, "yodel");
+    writeFileSync(path, script);
+    chmodSync(path, 0o755);
+    return { dir, dispose: () => { rmSync(dir, { recursive: true, force: true }); } };
+}
+/**
+ * Where `yodel apply --execute` (the Op's Apply step) writes its exit code,
+ * so the outer `yodel apply` exits with it (5 for the lock, 4 for a refusal)
+ * rather than with `chant run`'s 1.
+ */
+export const STEP_EXIT_ENV = "YODEL_STEP_EXIT_FILE";
+/** Records an Op step's exit code where the outer `yodel apply` reads it. Never fails the step. */
+export function recordStepExit(code, env = process.env) {
+    const file = env[STEP_EXIT_ENV];
+    if (!file)
+        return;
+    try {
+        writeFileSync(file, `${String(code)}\n`);
+    }
+    catch {
+        // The outer run then reports chant run's own exit.
+    }
+}
+/** The exit code the Op's Apply step recorded, when it ran. */
+export function readStepExit(file) {
+    try {
+        const n = Number(readFileSync(file, "utf8").trim());
+        return Number.isInteger(n) ? n : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Runs the migrations Op with `chant run`, with this yodel on PATH and `--allow-out-of-order` passed through. */
+export async function runMigrateOp(project, op, options) {
+    const shim = yodelShim();
+    try {
+        const base = options.env ?? process.env;
+        // The approved digest only ever comes from the gate, never from the caller's environment.
+        const rest = Object.fromEntries(Object.entries(base).filter(([k]) => k !== APPROVED_PLAN_ENV && k !== ALLOW_OUT_OF_ORDER_ENV));
+        const exitFile = join(shim.dir, "step-exit");
+        const env = {
+            ...rest,
+            [STEP_EXIT_ENV]: exitFile,
+            PATH: [shim.dir, base.PATH ?? ""].filter(Boolean).join(delimiter),
+            ...(options.allowOutOfOrder ? { [ALLOW_OUT_OF_ORDER_ENV]: "1" } : {}),
+        };
+        const result = await runChant(["run", op.name, "--gated-exit", String(GATED)], {
+            cwd: project.dir,
+            env,
+            ...(options.onOutput ? { onStdout: options.onOutput, onStderr: options.onOutput } : {}),
+        });
+        const run = readApplyRun(result.code, `${result.stdout}\n${result.stderr}`);
+        const stepExit = readStepExit(exitFile);
+        return stepExit === undefined ? run : { ...run, stepExit };
+    }
+    finally {
+        shim.dispose();
+    }
+}
+//# sourceMappingURL=op.js.map

package/dist/versioned/op.js.map

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

package/dist/versioned/policy.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Policy over the plan (#53): the rules `yodel.config.ts` `policy` declares
+ * (`../config/define.ts`), evaluated over the plan `yodel apply` would run,
+ * and the overrides recorded against them.
+ *
+ * `yodel plan` reports each rule's outcome; `yodel apply` refuses (exit 4)
+ * before the gate, and its Apply step again under the lock, a plan a rule
+ * denies. An override is a person's decision to run that plan anyway:
+ * `yodel override <env> --rule <id> --reason <text>` records it on chant's
+ * gate ledger (the `chant/lifecycle` branch) as an approval of the gate
+ * `override-<id>` of the migrations Op, for exactly the current plan digest,
+ * with the reason as its note. It counts only when the plan digest is the
+ * same, so it is refused once the plan moves, and only when
+ * `policy.overriders` lists who recorded it. The Apply step writes the
+ * overrides it relied on into the history (the `note` of each migration's
+ * `started` row).
+ */
+import type { GateLedgerPort } from "@intentius/chant/op/gate";
+import type { PolicyConfig, PolicyPlan } from "../config/define.js";
+import type { SqlDialect } from "../project.js";
+import { YodelError } from "../project.js";
+import type { MigrateOpRef } from "./op.js";
+import type { PendingMigration } from "./state.js";
+/** The gate an override of `rule` is recorded as an approval of. */
+export declare const overrideGate: (rule: string) => string;
+/** An override that counts: who recorded it, when, why, and the digest it is for. */
+export interface PolicyOverride {
+    rule: string;
+    by: string;
+    at: string;
+    reason: string;
+    digest: string;
+}
+export interface RuleResult {
+    id: string;
+    description?: string | undefined;
+    /** `denied` stands; `overridden` was denied, and an override counts. */
+    outcome: "allowed" | "denied" | "overridden";
+    /** Why it denies the plan, one line each. */
+    reasons: string[];
+    override?: PolicyOverride | undefined;
+}
+/** The plan a rule sees. */
+export declare function policyPlan(environment: string, dialect: SqlDialect, toApply: readonly PendingMigration[], now?: Date): PolicyPlan;
+/** Each rule that applies to the plan's environment, allowed or denied. No overrides yet. */
+export declare function evaluatePolicy(policy: PolicyConfig | undefined, plan: PolicyPlan): RuleResult[];
+/** The overrides on the ledger that count for `digest`: of a rule's override gate, for that digest, with a reason, by someone `overriders` lists. The newest per rule. */
+export declare function readOverrides(port: GateLedgerPort, op: MigrateOpRef, digest: string, overriders: readonly string[] | undefined): Promise<PolicyOverride[]>;
+/** The results with each denied rule an override counts for marked overridden. */
+export declare function withOverrides(results: readonly RuleResult[], overrides: readonly PolicyOverride[]): RuleResult[];
+/** The refusal for the rules that deny the plan with no override, or `undefined`. */
+export declare function policyRefusal(results: readonly RuleResult[], environment: string, digest: string | undefined, when: string): YodelError | undefined;
+/** The whole evaluation: the rules over the plan, with the overrides on the ledger for `digest`. Empty when the config declares no policy. */
+export declare function judgePlan(input: {
+    policy: PolicyConfig | undefined;
+    environment: string;
+    dialect: SqlDialect;
+    toApply: readonly PendingMigration[];
+    digest: string | undefined;
+    ledger: () => Promise<{
+        port: GateLedgerPort;
+        op: MigrateOpRef;
+    } | undefined>;
+    now?: Date;
+}): Promise<RuleResult[]>;
+/** One line per rule, for text output. */
+export declare function describeResults(results: readonly RuleResult[]): string[];

package/dist/versioned/policy.js

@@ -0,0 +1,161 @@
+/**
+ * Policy over the plan (#53): the rules `yodel.config.ts` `policy` declares
+ * (`../config/define.ts`), evaluated over the plan `yodel apply` would run,
+ * and the overrides recorded against them.
+ *
+ * `yodel plan` reports each rule's outcome; `yodel apply` refuses (exit 4)
+ * before the gate, and its Apply step again under the lock, a plan a rule
+ * denies. An override is a person's decision to run that plan anyway:
+ * `yodel override <env> --rule <id> --reason <text>` records it on chant's
+ * gate ledger (the `chant/lifecycle` branch) as an approval of the gate
+ * `override-<id>` of the migrations Op, for exactly the current plan digest,
+ * with the reason as its note. It counts only when the plan digest is the
+ * same, so it is refused once the plan moves, and only when
+ * `policy.overriders` lists who recorded it. The Apply step writes the
+ * overrides it relied on into the history (the `note` of each migration's
+ * `started` row).
+ */
+import { YodelError } from "../project.js";
+import { EXIT_REFUSED } from "../exit.js";
+import { silencesOf } from "../lint/index.js";
+import { sameDigest } from "./digest.js";
+/** The gate an override of `rule` is recorded as an approval of. */
+export const overrideGate = (rule) => `override-${rule}`;
+/** The plan a rule sees. */
+export function policyPlan(environment, dialect, toApply, now = new Date()) {
+    return {
+        environment,
+        dialect,
+        now: now.toISOString(),
+        pending: toApply.map((p) => ({
+            id: p.id,
+            checksum: p.checksum,
+            outOfOrder: p.outOfOrder,
+            steps: p.migration.document.steps.map((s, index) => {
+                if (s.kind === "statement") {
+                    return { index, kind: "statement", object: s.object, name: s.name, classes: [s.class], destructive: s.destructive === true, rules: [s.rule], sql: s.sql };
+                }
+                return {
+                    index,
+                    kind: s.kind,
+                    object: s.object,
+                    name: s.name,
+                    classes: [...new Set(s.changes.map((c) => c.class))],
+                    destructive: s.changes.some((c) => c.destructive === true),
+                    rules: [...new Set(s.changes.map((c) => c.rule))],
+                    ...(s.kind === "op" ? { op: s.op } : {}),
+                };
+            }),
+            silences: silencesOf(p.migration).map(({ step, rule, reason }) => ({ step, rule, reason })),
+        })),
+    };
+}
+const applies = (rule, environment) => rule.environments === undefined || rule.environments.includes(environment);
+function denials(rule, plan) {
+    const out = [];
+    if (rule.refuse) {
+        const { classes = [], destructive = false } = rule.refuse;
+        for (const m of plan.pending) {
+            for (const s of m.steps) {
+                const cls = s.classes.filter((c) => classes.includes(c));
+                if (cls.length > 0)
+                    out.push(`${m.id} step ${String(s.index)} (${s.name}) is ${cls.join(", ")}`);
+                else if (destructive && s.destructive)
+                    out.push(`${m.id} step ${String(s.index)} (${s.name}) is destructive`);
+            }
+        }
+    }
+    if (rule.silences) {
+        const { rules, reason } = rule.silences;
+        for (const m of plan.pending) {
+            for (const s of m.silences) {
+                if (rules && !rules.includes(s.rule))
+                    continue;
+                reason.lastIndex = 0;
+                if (!reason.test(s.reason))
+                    out.push(`${m.id} step ${String(s.step)} silences ${s.rule} with a reason that does not match ${String(reason)}: ${JSON.stringify(s.reason)}`);
+            }
+        }
+    }
+    if (rule.check) {
+        let said;
+        try {
+            said = rule.check(plan);
+        }
+        catch (e) {
+            said = `its check threw: ${e instanceof Error ? e.message : String(e)}`;
+        }
+        if (said === false)
+            out.push(rule.description ?? "its check denies the plan");
+        else if (typeof said === "string")
+            out.push(said);
+        else if (Array.isArray(said))
+            out.push(...said);
+    }
+    return out;
+}
+/** Each rule that applies to the plan's environment, allowed or denied. No overrides yet. */
+export function evaluatePolicy(policy, plan) {
+    return (policy?.rules ?? [])
+        .filter((r) => applies(r, plan.environment))
+        .map((r) => {
+        const reasons = denials(r, plan);
+        return { id: r.id, ...(r.description ? { description: r.description } : {}), outcome: reasons.length > 0 ? "denied" : "allowed", reasons };
+    });
+}
+/** The overrides on the ledger that count for `digest`: of a rule's override gate, for that digest, with a reason, by someone `overriders` lists. The newest per rule. */
+export async function readOverrides(port, op, digest, overriders) {
+    const { resolutions } = await port.read(op.name);
+    const byRule = new Map();
+    for (const r of resolutions) {
+        if (!r.gate.startsWith("override-") || !r.note || !(overriders ?? []).includes(r.resolvedBy))
+            continue;
+        if (!(await sameDigest(r.planDigest, digest)))
+            continue;
+        const rule = r.gate.slice("override-".length);
+        const prior = byRule.get(rule);
+        if (!prior || prior.at < r.timestamp)
+            byRule.set(rule, { rule, by: r.resolvedBy, at: r.timestamp, reason: r.note, digest });
+    }
+    return [...byRule.values()];
+}
+/** The results with each denied rule an override counts for marked overridden. */
+export function withOverrides(results, overrides) {
+    return results.map((r) => {
+        const o = r.outcome === "denied" ? overrides.find((x) => x.rule === r.id) : undefined;
+        return o ? { ...r, outcome: "overridden", override: o } : r;
+    });
+}
+/** The refusal for the rules that deny the plan with no override, or `undefined`. */
+export function policyRefusal(results, environment, digest, when) {
+    const denied = results.filter((r) => r.outcome === "denied");
+    if (denied.length === 0)
+        return undefined;
+    const lines = denied.flatMap((r) => [`  ${r.id}${r.description ? ` (${r.description})` : ""}:`, ...r.reasons.map((x) => `    ${x}`)]);
+    const ids = denied.map((r) => r.id).join(", ");
+    return new YodelError(`refused by policy ${when}: ${denied.length === 1 ? "rule" : "rules"} ${ids} ${denied.length === 1 ? "denies" : "deny"} this plan${digest ? ` (${digest})` : ""}. Nothing was applied:\n${lines.join("\n")}\n` +
+        `To run it anyway, someone policy.overriders lists records why, for exactly this plan: ${denied.map((r) => `yodel override ${environment} --rule ${r.id} --reason "<why>"`).join("; ")}`, EXIT_REFUSED);
+}
+/** The whole evaluation: the rules over the plan, with the overrides on the ledger for `digest`. Empty when the config declares no policy. */
+export async function judgePlan(input) {
+    if (!input.policy || input.toApply.length === 0)
+        return [];
+    const results = evaluatePolicy(input.policy, policyPlan(input.environment, input.dialect, input.toApply, input.now));
+    if (!input.digest || !results.some((r) => r.outcome === "denied"))
+        return results;
+    const at = await input.ledger();
+    if (!at)
+        return results;
+    return withOverrides(results, await readOverrides(at.port, at.op, input.digest, input.policy.overriders));
+}
+/** One line per rule, for text output. */
+export function describeResults(results) {
+    return results.map((r) => {
+        if (r.outcome === "allowed")
+            return `policy ${r.id}: allowed`;
+        if (r.outcome === "overridden" && r.override)
+            return `policy ${r.id}: denied, overridden by ${r.override.by} at ${r.override.at}: ${r.override.reason}`;
+        return `policy ${r.id}: denied: ${r.reasons.join("; ")}`;
+    });
+}
+//# sourceMappingURL=policy.js.map

package/dist/versioned/policy.js.map

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

package/dist/versioned/postgres/catalog.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The live-schema fingerprint a Postgres plan digest covers: every object
+ * chant's catalog reader sees in the environment's schemas
+ * (`sql.profiles.<env>.schemas`; every schema but the server's own when it
+ * names none), by its type, schema, name, the statements that create it as
+ * the server prints them, and its comment. The history schema is left out,
+ * so recording a run does not move the digest, and so are chant's own
+ * working objects (a migration's new column, its receipts), which the reader
+ * skips.
+ *
+ * It is the same reader `chant sql plan` and the applier diff against, so a
+ * change the plan would see (a column added out of band, an index dropped, a
+ * default changed) is a new fingerprint, and an approval given before it
+ * does not carry over.
+ */
+import type { PgClient } from "../../history/postgres/index.js";
+export interface PgLiveScope {
+    /** The schemas in scope; every schema but the server's own when undefined. */
+    schemas: string[] | undefined;
+    /** Left out of the fingerprint. */
+    historySchema: string;
+}
+export interface PgCatalogEntry {
+    type: string;
+    schema: string;
+    name: string;
+    statement: string;
+    comment: string;
+}
+/** Reads what the fingerprint covers, in a stable order. */
+export declare function readPgCatalog(client: PgClient, scope: PgLiveScope): Promise<PgCatalogEntry[]>;
+/** `sha256:<hex>` over the catalog's canonical JSON. */
+export declare function pgCatalogFingerprint(entries: readonly PgCatalogEntry[]): string;

package/dist/versioned/postgres/catalog.js

@@ -0,0 +1,34 @@
+/**
+ * The live-schema fingerprint a Postgres plan digest covers: every object
+ * chant's catalog reader sees in the environment's schemas
+ * (`sql.profiles.<env>.schemas`; every schema but the server's own when it
+ * names none), by its type, schema, name, the statements that create it as
+ * the server prints them, and its comment. The history schema is left out,
+ * so recording a run does not move the digest, and so are chant's own
+ * working objects (a migration's new column, its receipts), which the reader
+ * skips.
+ *
+ * It is the same reader `chant sql plan` and the applier diff against, so a
+ * change the plan would see (a column added out of band, an index dropped, a
+ * default changed) is a new fingerprint, and an approval given before it
+ * does not carry over.
+ */
+import { createHash } from "node:crypto";
+/** Byte order, so the order never depends on the machine's locale. */
+const cmp = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+/** Reads what the fingerprint covers, in a stable order. */
+export async function readPgCatalog(client, scope) {
+    const { readLiveSchema } = await import("@intentius/chant-lexicon-sql/postgres/live/catalog");
+    const schemas = scope.schemas?.filter((s) => s !== scope.historySchema);
+    const objects = await readLiveSchema(client, schemas ? { schemas } : {});
+    return objects
+        .filter((o) => o.schema !== scope.historySchema && !(o.type === "Postgres::Schema" && o.name === scope.historySchema))
+        .map((o) => ({ type: o.type, schema: o.schema ?? "", name: o.name, statement: o.statement, comment: o.comment ?? "" }))
+        .sort((a, b) => cmp(a.type, b.type) || cmp(a.schema, b.schema) || cmp(a.name, b.name));
+}
+/** `sha256:<hex>` over the catalog's canonical JSON. */
+export function pgCatalogFingerprint(entries) {
+    const canonical = entries.map((e) => [e.type, e.schema, e.name, e.statement, e.comment]);
+    return `sha256:${createHash("sha256").update(JSON.stringify(canonical), "utf8").digest("hex")}`;
+}
+//# sourceMappingURL=catalog.js.map

package/dist/versioned/postgres/catalog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.js","sourceRoot":"","sources":["../../../src/versioned/postgres/catalog.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAkBzC,sEAAsE;AACtE,MAAM,GAAG,GAAG,CAAC,CAAS,EAAE,CAAS,EAAU,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAE3E,4DAA4D;AAC5D,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,MAAgB,EAAE,KAAkB;IACtE,MAAM,EAAE,cAAc,EAAE,GAAG,MAAM,MAAM,CAAC,oDAAoD,CAAC,CAAC;IAC9F,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,KAAK,CAAC,aAAa,CAAC,CAAC;IACxE,MAAM,OAAO,GAAG,MAAM,cAAc,CAAC,MAA8C,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IACjH,OAAO,OAAO;SACX,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,KAAK,CAAC,aAAa,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,KAAK,kBAAkB,IAAI,CAAC,CAAC,IAAI,KAAK,KAAK,CAAC,aAAa,CAAC,CAAC;SACrH,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,IAAI,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,SAAS,EAAE,CAAC,CAAC,SAAS,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,IAAI,EAAE,EAAE,CAAC,CAAC;SACtH,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;AAC3F,CAAC;AAED,wDAAwD;AACxD,MAAM,UAAU,oBAAoB,CAAC,OAAkC;IACrE,MAAM,SAAS,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;IACzF,OAAO,UAAU,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;AAClG,CAAC"}

package/dist/versioned/postgres/driver.d.ts

@@ -0,0 +1,71 @@
+/**
+ * The versioned apply on Postgres (#13): binding an environment's server,
+ * its history, its lock and its statements.
+ *
+ * Settings:
+ *
+ *   the environment's history database (`yodel.config.ts`
+ *   `environments.<env>.history.database`, else YODEL_HISTORY_DATABASE,
+ *   default `yodeler`) is the history's schema: `<schema>.history`, and the lock's key
+ *   YODEL_LOCK_RETRIES      how many more times a statement that hit the lock timeout is tried (default 5)
+ *
+ * and from `sql.profiles.<env>`, as chant's applier reads them:
+ *
+ *   lockTimeoutMs       lock_timeout for every statement, and for the live-schema read (default 5000)
+ *   statementTimeoutMs  statement_timeout for a catalog change (default 60000)
+ *   scanTimeoutMs       statement_timeout for a statement that reads or rewrites rows (default none)
+ *   schemas             the schemas the plan digest's fingerprint covers (default every schema but the server's own)
+ *
+ * Two connections: the work connection, opened on first use, on which the
+ * history is read and written and the statements run; and the lock's,
+ * opened when the lock is taken and closed when it is released.
+ */
+import type { PostgresEndpoint } from "@intentius/chant-lexicon-sql/postgres/live/client";
+import { type Environment, type Project } from "../../project.js";
+import { PostgresHistoryStore, type PgLockConnection } from "../../history/postgres/index.js";
+import type { VersionedDriver } from "../driver.js";
+import { type PgTimeouts } from "./executor.js";
+/** Opens a connection to the server: chant's `connectPostgres`, or a fake in the tests. */
+export type PgConnect = (endpoint: PostgresEndpoint, applicationName: string) => Promise<PgLockConnection>;
+export interface PgSettings {
+    historySchema: string;
+    timeouts: PgTimeouts;
+    lockRetries: number;
+}
+export declare function pgSettings(target: {
+    timeouts?: Partial<PgTimeouts>;
+}, env?: NodeJS.ProcessEnv, historySchema?: string): PgSettings;
+/** A connection opened on its first query, so a verb that reads nothing opens none. */
+export declare class LazyConnection implements PgLockConnection {
+    private readonly open;
+    private conn;
+    constructor(open: () => Promise<PgLockConnection>);
+    query<T = Record<string, unknown>>(sql: string, params?: readonly unknown[]): Promise<T[]>;
+    end(): Promise<void>;
+}
+/** Everything the versioned verbs need about one Postgres environment. */
+export interface PostgresEnv {
+    endpoint: PostgresEndpoint;
+    /** `sql.profiles.<env>.schemas`. */
+    schemas: string[] | undefined;
+    defaultSchema: string;
+    settings: PgSettings;
+    client: LazyConnection;
+    store: PostgresHistoryStore;
+    driver: VersionedDriver;
+}
+/** Binds `env`'s Postgres server (`sql.profiles.<env>`) and its history. Connects on first use. */
+export declare function openPostgres(project: Project, env: Environment, processEnv?: NodeJS.ProcessEnv, historySchema?: string, connect?: PgConnect): Promise<PostgresEnv>;
+export interface PostgresDriverInput {
+    client: LazyConnection;
+    /** Opens the lock's own connection. */
+    connect: () => Promise<PgLockConnection>;
+    settings: PgSettings;
+    schemas: string[] | undefined;
+    store: PostgresHistoryStore;
+    sleep?: (ms: number) => Promise<void>;
+    retryBaseMs?: number;
+    /** Where a read held up by another session's lock says so; default stderr. */
+    log?: (line: string) => void;
+}
+export declare function postgresDriver(input: PostgresDriverInput): VersionedDriver;