@intentius/chant-lexicon-sql 0.124.30 → 0.124.32

package/dist/composites/replacing-table.js

@@ -0,0 +1,28 @@
+/**
+ * `ReplacingTable`: a ReplacingMergeTree table with a version column.
+ *
+ * ReplacingMergeTree keeps one row per sort key. When a merge meets rows with
+ * the same key it keeps the one with the highest version, so writing a row
+ * again with a higher version is how an update is expressed. Until a merge
+ * runs, a query sees every version; read with `FINAL`, or aggregate with
+ * `argMax`, when the latest row is what you want.
+ *
+ * Every field is built from a parameter or fixed by the template, inside the
+ * subset `chant build` interprets, so a drift on the table is reported against
+ * the parameter that produced the field when the composite is interpreted.
+ */
+import { Composite } from "@intentius/chant/composite";
+import { table } from "../clickhouse/entities.js";
+/** A ReplacingMergeTree table that keeps the highest version of each row, with its version column. */
+export const ReplacingTable = Composite((props) => {
+    const version = props.version ?? "version";
+    const replacing = table `
+    CREATE TABLE ${props.name} (
+      ${props.columns},
+      ${version} ${props.versionType ?? "UInt64"}
+    )
+    ENGINE = ReplacingMergeTree(${version})
+    ${props.partitionBy ? `PARTITION BY ${props.partitionBy}` : ""}
+    ORDER BY ${props.orderBy}`;
+    return { table: replacing };
+}, "ReplacingTable");

package/dist/composites/rollup-view.js

@@ -0,0 +1,29 @@
+/**
+ * `RollupView`: a materialized view that rolls a source table up into its own target table.
+ *
+ * The target is a SummingMergeTree (or another engine named by `engine`)
+ * sorted by the rollup's grouping key. The materialized view writes into it
+ * with `TO`, so the target is an ordinary table that can be queried, altered
+ * and backfilled on its own, and dropping the view leaves the data. Every
+ * column the select list writes has to be one the target declares
+ * (SQLCH110), so alias each select item to a target column.
+ *
+ * The view reads `source` by reference, so it depends on the source and on
+ * its target, and the build orders all three.
+ */
+import { Composite } from "@intentius/chant/composite";
+import { table, view } from "../clickhouse/entities.js";
+/** A materialized view that rolls a source table up into a target table it declares beside it. */
+export const RollupView = Composite((props) => {
+    const target = table `
+    CREATE TABLE ${props.name} (${props.columns})
+    ENGINE = ${props.engine ?? "SummingMergeTree"}
+    ${props.partitionBy ? `PARTITION BY ${props.partitionBy}` : ""}
+    ORDER BY ${props.orderBy ?? `(${props.groupBy})`}`;
+    const rollup = view `
+    CREATE MATERIALIZED VIEW ${`${props.name}_mv`} TO ${target} AS
+    SELECT ${props.select}
+    FROM ${props.source}
+    GROUP BY ${props.groupBy}`;
+    return { table: target, view: rollup };
+}, "RollupView");

package/dist/composites/sharded-table.js

@@ -0,0 +1,27 @@
+/**
+ * `ShardedTable`: a ReplicatedMergeTree table on every node of a cluster and the Distributed table that spreads reads and writes across it.
+ *
+ * Both tables are created `ON CLUSTER`. The local table, `<name>_local`, holds
+ * each shard's rows and replicates them within the shard; with no engine
+ * arguments it takes the server's default replication path. The Distributed
+ * table, `<name>`, holds no data: an insert goes to one shard by the sharding
+ * key, and a query runs on every shard and merges the results.
+ *
+ * The Distributed table reads the local one by reference, so the build creates
+ * the local table first. Give `name` without a database: the Distributed
+ * engine names its table in the current database.
+ */
+import { Composite } from "@intentius/chant/composite";
+import { table } from "../clickhouse/entities.js";
+/** A ReplicatedMergeTree table on every node of a cluster and the Distributed table over it. */
+export const ShardedTable = Composite((props) => {
+    const local = table `
+    CREATE TABLE ${`${props.name}_local`} ON CLUSTER ${props.cluster} (${props.columns})
+    ENGINE = ReplicatedMergeTree
+    ${props.partitionBy ? `PARTITION BY ${props.partitionBy}` : ""}
+    ORDER BY ${props.orderBy}`;
+    const distributed = table `
+    CREATE TABLE ${props.name} ON CLUSTER ${props.cluster} (${props.columns})
+    ENGINE = Distributed(${props.cluster}, currentDatabase(), ${local}, ${props.shardingKey ?? "rand()"})`;
+    return { local, distributed };
+}, "ShardedTable");

package/dist/composites/soft-delete-table.js

@@ -0,0 +1,34 @@
+/**
+ * `SoftDeleteTable`: a table whose rows carry created and updated timestamps and are deleted by marking them.
+ *
+ * The composite appends `created_at` and `updated_at` (both `timestamptz NOT
+ * NULL DEFAULT now()`) and a nullable `deleted_at` to the columns it is
+ * given. A row is live while `deleted_at` is null. The `<name>_live` view
+ * reads the live rows (it sets `security_invoker`, so row-level security on
+ * the table applies to whoever reads the view), and a partial index on the
+ * live rows keeps lookups by the key the app uses off the dead ones.
+ *
+ * Postgres has no column default that follows an update: the app, or a
+ * trigger it owns, sets `updated_at`.
+ */
+import { Composite } from "@intentius/chant/composite";
+import { index, literal, table, view } from "../postgres/entities.js";
+/** A table with created and updated timestamps and a soft-delete column, a view of its live rows and an index over them. */
+export const SoftDeleteTable = Composite((props) => {
+    const schema = props.schema ?? "public";
+    const deleted = props.deletedAt ?? "deleted_at";
+    const rows = table `
+    CREATE TABLE ${schema}.${props.name} (
+      ${props.columns},
+      ${props.createdAt ?? "created_at"} timestamptz NOT NULL DEFAULT now(),
+      ${props.updatedAt ?? "updated_at"} timestamptz NOT NULL DEFAULT now(),
+      ${deleted} timestamptz
+    );
+    COMMENT ON TABLE ${schema}.${props.name} IS ${literal(props.comment ?? "Soft-deleted: a row is live while its deletion timestamp is null")}`;
+    const live = view `
+    CREATE VIEW ${schema}.${`${props.name}_live`} WITH (security_invoker = true) AS
+    SELECT * FROM ${rows} WHERE ${deleted} IS NULL`;
+    const liveIndex = index `
+    CREATE INDEX ${`${props.name}_live_idx`} ON ${rows} (${props.liveKey ?? "id"}) WHERE ${deleted} IS NULL`;
+    return { table: rows, live, liveIndex };
+}, "SoftDeleteTable");

package/dist/composites/tenant-table.js

@@ -0,0 +1,26 @@
+/**
+ * `TenantTable`: a multi-tenant table whose tenant key leads every key and index.
+ *
+ * The composite adds the tenant column (`NOT NULL`) in front of the columns it
+ * is given, makes the primary key `(<tenant>, <primaryKey>)` and creates one
+ * index on `(<tenant>, <indexOn>)`. With the tenant first in each, a query
+ * scoped to one tenant reads one contiguous range of every index, and no index
+ * serves a cross-tenant scan by accident. Row-level security is separate: a
+ * policy on the table is what keeps one tenant's role out of another's rows.
+ */
+import { Composite } from "@intentius/chant/composite";
+import { index, table } from "../postgres/entities.js";
+/** A multi-tenant table with the tenant key first in its primary key and its index. */
+export const TenantTable = Composite((props) => {
+    const schema = props.schema ?? "public";
+    const tenant = props.tenant ?? "tenant_id";
+    const rows = table `
+    CREATE TABLE ${schema}.${props.name} (
+      ${tenant} ${props.tenantType ?? "uuid"} NOT NULL,
+      ${props.columns},
+      PRIMARY KEY (${tenant}, ${props.primaryKey})
+    )`;
+    const byTenant = index `
+    CREATE INDEX ${`${props.name}_tenant_idx`} ON ${rows} (${tenant}, ${props.indexOn})`;
+    return { table: rows, index: byTenant };
+}, "TenantTable");

package/dist/composites/typed.js

@@ -0,0 +1,8 @@
+/**
+ * chant#3787 — the call signature a composite is typed with, so a member's
+ * `.columns` are the generated `SqlSchema` entry for the name its props give
+ * it. `users.table.columns.emial` then fails tsc as `table<"app.users">`'s
+ * would. The definition is unchanged at run time: `Composite`'s third type
+ * argument carries this signature in front of the plain one.
+ */
+export {};

package/dist/config.js

@@ -0,0 +1,206 @@
+/**
+ * The `sql` namespace in `chant.config.ts`.
+ *
+ * ```ts
+ * import type { ChantConfig } from "@intentius/chant/config";
+ * import "@intentius/chant-lexicon-sql";   // brings the `sql` key into ChantConfig
+ *
+ * export default {
+ *   lexicons: ["sql"],
+ *   sql: {
+ *     dialect: "clickhouse",
+ *     profiles: {
+ *       staging: { url: "http://clickhouse.staging:8123", user: { env: "CH_USER" }, password: { env: "CH_PASSWORD" } },
+ *       prod: { url: "https://clickhouse.example.com:8443", user: { env: "CH_USER" }, password: { env: "CH_PROD_PASSWORD" }, databases: ["analytics"] },
+ *     },
+ *   },
+ * } satisfies ChantConfig;
+ * ```
+ *
+ * A profile is keyed by chant environment, as `grafana.profiles.<env>` is:
+ * the server `chant import --from <env>`, `chant lifecycle diff <env> --live`
+ * and `plan` read. Credentials are named by their environment variable, never
+ * written in the config, or minted as a short-lived token (`password:
+ * { token: "rds-iam" }`; `./token-source.ts`). An environment with no profile falls back to
+ * `CLICKHOUSE_URL`, `CLICKHOUSE_USER` and `CLICKHOUSE_PASSWORD`, or for
+ * Postgres `POSTGRES_URL`, `POSTGRES_USER` and `POSTGRES_PASSWORD`. A profile
+ * whose `url` is `postgres://` or `postgresql://` is a Postgres server.
+ *
+ * `dialect` names the database a project's schema is for. Declarations carry
+ * their dialect in their own type (a ClickHouse table is `ClickHouse::Table`),
+ * so the setting is for the things a declaration cannot answer: which dialect
+ * a live environment is read as on import, and which dialect's checks run on
+ * output that names none. It defaults to `clickhouse`, the first dialect.
+ * `postgres` is the second (#3289). A list (`dialect: ["clickhouse",
+ * "postgres"]`) is accepted for a workspace with members of more than one
+ * dialect (#3047 question 1); one build still holds one dialect.
+ *
+ * `provider` (#3282) names the managed Postgres service, on the namespace or
+ * on one profile: `sql: { dialect: "postgres", provider: "rds" }`, or
+ * `profiles: { prod: { url, provider: "aurora" } }`. A provider's data lives
+ * in `@intentius/chant-lexicon-sql/postgres` (`providerData`).
+ */
+import { z } from "zod";
+import { PLANNED_SQL_DIALECTS, SQL_DIALECTS } from "./dialects.js";
+import { POSTGRES_PROVIDERS } from "./postgres/providers/types.js";
+import { POSTGRES_MAJORS } from "./spec/postgres-pin.js";
+import { parseTopology } from "./clickhouse/topology.js";
+import { tokenSourceSchema } from "./token-source.js";
+const envRef = z.strictObject({ env: z.string() });
+/** The managed Postgres service an environment runs on (#3282). */
+const providerName = z.enum(POSTGRES_PROVIDERS, {
+    error: () => `expected a Postgres provider (${POSTGRES_PROVIDERS.join(", ")})`,
+});
+/** A ClickHouse topology, in its string form or its object form (`./clickhouse/topology.ts`). */
+const topologySchema = z.union([
+    z.string().refine((v) => {
+        try {
+            parseTopology(v);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }, { error: "expected single, cluster:<name>, replicated, replicated:<cluster> or cloud" }),
+    z.discriminatedUnion("kind", [
+        z.strictObject({ kind: z.literal("single") }),
+        z.strictObject({ kind: z.literal("cluster"), cluster: z.string().min(1), replicaPath: z.string().optional(), replicaName: z.string().optional() }),
+        z.strictObject({ kind: z.literal("replicated"), cluster: z.string().min(1).optional() }),
+        z.strictObject({ kind: z.literal("cloud") }),
+    ]),
+]);
+export const sqlProfileSchema = z.strictObject({
+    /**
+     * Where the server is. ClickHouse: the base URL of its HTTP interface
+     * (`http://clickhouse:8123`). Postgres: a connection URL
+     * (`postgres://db.internal:5432/shop`), with no password in it; the scheme
+     * is what makes a profile a Postgres one.
+     */
+    url: z.string(),
+    /** The user, named by its environment variable. `default` when omitted. */
+    user: envRef.optional(),
+    /**
+     * The password, named by its environment variable, or a token source that
+     * mints a short-lived one when a connection needs it (#3685):
+     * `{ token: "rds-iam" }`, `{ token: "cloud-sql-iam" }`, `{ token: "entra" }`
+     * (Postgres), or `{ token: "command", command: ["./mint.sh"] }`, whose
+     * standard output is the password. A token is minted again before it
+     * expires. See `./token-source.ts`.
+     */
+    password: z.union([envRef, tokenSourceSchema]).optional(),
+    /**
+     * The databases this environment's schema lives in. Import reads these and
+     * nothing else; when omitted, every database except the server's own
+     * (`system`, `information_schema`, `INFORMATION_SCHEMA`).
+     */
+    databases: z.array(z.string()).optional(),
+    /** The database an unqualified declaration is created in. `default` when omitted. */
+    defaultDatabase: z.string().optional(),
+    /**
+     * ClickHouse import (#3718): the SQL user-defined functions `chant import
+     * --from <env>` adopts besides those the imported objects use, by name, or
+     * by prefix with a trailing `*` (`shop_*`). A function belongs to no
+     * database, so without this only the functions the imported tables, views
+     * and dictionaries use (and the functions those call) are imported. A use
+     * is found by name or, since ClickHouse stores a call as the function's
+     * body, by that body (#3745).
+     */
+    importFunctions: z.array(z.string()).optional(),
+    /**
+     * ClickHouse: the topology this environment runs, which the applier, the
+     * plan and the rebuild migration render every statement for: `single`,
+     * `cluster:<name>` (`ON CLUSTER`, `Replicated*MergeTree` with a Keeper
+     * path), `replicated` (a `Replicated` database; `replicated:<cluster>`
+     * creates the databases on that cluster) or `cloud`. The object form sets
+     * a cluster's Keeper path and replica name:
+     * `{ kind: "cluster", cluster: "main", replicaPath, replicaName }`. When
+     * omitted, statements are sent as declared.
+     */
+    topology: topologySchema.optional(),
+    /**
+     * Postgres: the schemas this environment's schema lives in. Import and
+     * observation read these and nothing else; when omitted, every schema except
+     * the server's own (`pg_catalog`, `information_schema`, `pg_toast`, the temp
+     * schemas).
+     */
+    schemas: z.array(z.string()).optional(),
+    /** Postgres: the schema an unqualified declaration is created in. `public` when omitted. */
+    defaultSchema: z.string().optional(),
+    /**
+     * Postgres: the schema `effect()` receipts are kept in, as
+     * `<schema>.__chant_receipts`. When omitted they are in
+     * `chant_receipts.receipts`, a schema chant creates; name an existing schema
+     * on a server where the role cannot `CREATE SCHEMA`.
+     */
+    receiptsSchema: z.string().optional(),
+    /**
+     * The managed service this environment's Postgres runs on, when it differs
+     * from `sql.provider`. Import reads the provider's own roles, schemas and
+     * extensions as foreign.
+     */
+    provider: providerName.optional(),
+    /**
+     * Postgres apply: how long one statement waits for its lock before it
+     * fails (`lock_timeout`), in milliseconds, so a change blocked behind a
+     * long query fails fast instead of queueing every query behind it. The
+     * catalog reads (`chant lifecycle diff --live`, `chant sql plan`, the
+     * import, and an apply's read before its first statement) wait under it
+     * too, and name the session holding the lock when it passes. 5000 when
+     * omitted.
+     */
+    lockTimeoutMs: z.number().int().nonnegative().optional(),
+    /**
+     * Postgres apply: the `statement_timeout` for a statement that changes only
+     * the catalog, in milliseconds. 60000 when omitted.
+     */
+    statementTimeoutMs: z.number().int().nonnegative().optional(),
+    /**
+     * Postgres apply: the `statement_timeout` for a statement that reads or
+     * rewrites every row (a table rewrite, a constraint validation, a
+     * `CONCURRENTLY` index build), in milliseconds. 0, no limit, when omitted.
+     */
+    scanTimeoutMs: z.number().int().nonnegative().optional(),
+    /**
+     * Whether chant manages access in this environment. Postgres (#3681): the
+     * declared row-level security policies and each table's row-level security,
+     * the declared roles (created when missing, never dropped), and the
+     * privileges on the declared objects and the default privileges, which a
+     * plan compares and an apply grants and revokes. ClickHouse (#3716): the
+     * declared users, roles, row policies and grants. Off when omitted: the
+     * access declarations are not planned or applied, and the server's access
+     * is not read, so a project that manages access elsewhere is not affected.
+     */
+    access: z.boolean().optional(),
+});
+const dialectName = z.enum(SQL_DIALECTS);
+/** Why a `dialect` value is refused: a planned dialect is "not implemented yet", anything else unknown. */
+function dialectError(input) {
+    const names = Array.isArray(input) ? input : [input];
+    const planned = names.find((n) => typeof n === "string" && PLANNED_SQL_DIALECTS.includes(n));
+    if (planned !== undefined) {
+        return `the ${planned} dialect is not implemented yet; the implemented dialects are ${SQL_DIALECTS.join(", ")}`;
+    }
+    return `expected a dialect (${SQL_DIALECTS.join(", ")}) or a non-empty list of them`;
+}
+export const sqlConfigSchema = z.strictObject({
+    /** The dialect, or the dialects, the project's schema is for. */
+    dialect: z.union([dialectName, z.array(dialectName).min(1)], { error: (iss) => dialectError(iss.input) }).optional(),
+    /**
+     * The managed Postgres service the project deploys to (`rds`, `aurora`,
+     * `cloud-sql`, `azure`, `neon`, `supabase`). SQLPG004 reads it to refuse an
+     * extension the provider does not allow. Omit it for a self-hosted server.
+     */
+    provider: providerName.optional(),
+    /**
+     * The Postgres major the project targets. The editor completes and hovers
+     * only what that major has (a function added in 18 is not offered at 16);
+     * without it, the newest supported major is used.
+     */
+    postgresMajor: z
+        .number()
+        .int()
+        .refine((n) => POSTGRES_MAJORS.includes(n), { error: `expected a supported Postgres major (${POSTGRES_MAJORS.join(", ")})` })
+        .optional(),
+    /** One server per chant environment. */
+    profiles: z.record(z.string(), sqlProfileSchema).optional(),
+});

package/dist/core/apply.js

@@ -0,0 +1,93 @@
+/**
+ * The applier's plumbing, the same in every dialect (lexicon-authoring/
+ * applying.mdx): reading a build's output, the outcome's tri-state (applied,
+ * not attempted, and failed for a statement the server refused), its
+ * projection onto core's apply envelope, and the ownership marker an apply
+ * stamps and prunes by.
+ *
+ * What a dialect's applier decides for itself: the statements a change takes,
+ * which changes it refuses and why, how it waits for the server, and how a
+ * prune drops an object.
+ */
+import { applyResult, notAttemptedAll, } from "@intentius/chant/apply";
+const isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+/**
+ * The objects a `chant build` output declares for `dialect`, in creation
+ * order, each passed through `map`. Takes the sql lexicon's primary output,
+ * or a multi-lexicon output holding it under `sql`.
+ */
+export function readBuildObjects(json, dialect, map) {
+    const raw = JSON.parse(json);
+    const doc = isObject(raw) && isObject(raw.sql) ? raw.sql : raw;
+    if (!isObject(doc) || doc.dialect !== dialect || !Array.isArray(doc.objects)) {
+        throw new Error(`not a sql lexicon build output: expected { dialect: "${dialect}", objects: [...] }`);
+    }
+    return doc.objects.map((o, i) => {
+        if (!isObject(o) || typeof o.export !== "string" || typeof o.ddl !== "string" || typeof o.type !== "string") {
+            throw new Error(`sql build output: objects[${i}] has no export, type or ddl`);
+        }
+        const dependsOn = [...new Set((Array.isArray(o.dependsOn) ? o.dependsOn : []).filter((d) => typeof d === "string").map((d) => d.split(".")[0]))];
+        return map({ export: o.export, type: o.type, ddl: o.ddl, dependsOn }, i);
+    });
+}
+/**
+ * An apply in which the server refused a statement. The envelope has no
+ * bucket for "attempted and not converged", so the applier finishes the rest
+ * and throws this, carrying the outcome.
+ */
+export class SqlApplyError extends Error {
+    constructor(
+    /** The dialect as a message names it: `ClickHouse`. */
+    dialect, outcome) {
+        super(`${dialect} apply to ${outcome.target}: ${outcome.failed.length} object(s) failed ` +
+            `(${outcome.failed.map((f) => `${f.kind}/${f.name}: ${f.error}`).join("; ")}); ` +
+            `${outcome.applied.length} applied, ${outcome.pruned.length} pruned, ${outcome.notAttempted.length} not attempted before and after`);
+        this.outcome = outcome;
+        this.name = "SqlApplyError";
+    }
+}
+/** An outcome in which nothing was attempted: every object not attempted with one reason. */
+export function notAttemptedOutcome(refs, reason, detail) {
+    return { target: "", source: "", applied: [], pruned: [], notAttempted: notAttemptedAll(refs, reason, detail), failed: [] };
+}
+/**
+ * Project an apply outcome onto core's apply envelope. The outcome keeps what
+ * the envelope has no room for: the statements each object took and the
+ * server they went to.
+ */
+export function toApplyResult(outcome) {
+    return applyResult(outcome.applied.map((a) => ({ kind: a.kind, name: a.name, action: a.action, ...(a.physicalId ? { physicalId: a.physicalId } : {}) })), outcome.pruned.map((p) => ({ kind: p.kind, name: p.name, deleted: p.deleted })), outcome.notAttempted.map((n) => ({ kind: n.kind, name: n.name, reason: n.reason, ...(n.detail ? { detail: n.detail } : {}) })));
+}
+/**
+ * The marker to stamp and prune by: `stack` and `ownershipEnv` when passed,
+ * else the project's `ownership` config. Undefined without a stack. `who`
+ * names the caller in the error for an env an apply cannot resolve.
+ */
+export function resolveOwnershipMarker(args, config, who) {
+    const o = config?.ownership;
+    const configured = o && o.enabled !== false ? o : undefined;
+    const stack = args.stack ?? configured?.stack;
+    if (!stack)
+        return undefined;
+    const env = args.ownershipEnv ?? (typeof configured?.env === "string" ? configured.env : undefined);
+    if (env === undefined && configured?.env !== undefined) {
+        throw new Error(`${who}: ownership.env is a build parameter reference, which an apply cannot resolve; pass ownershipEnv`);
+    }
+    return { stack, ...(env ? { env } : {}) };
+}
+/** Changes grouped by the object they change, in order. */
+export function changesByObject(changes) {
+    const byObject = new Map();
+    for (const c of changes)
+        byObject.set(c.object, [...(byObject.get(c.object) ?? []), c]);
+    return byObject;
+}
+/**
+ * The declared objects `dependsOn` names that are not on the server: declared
+ * in this build, and not created or found in this apply. An object with any
+ * is not attempted, `dependency-failed`, with {@link dependencyFailedDetail}.
+ */
+export function missingDependencies(self, dependsOn, declared, onServer) {
+    return dependsOn.filter((d) => declared.has(d) && d !== self && !onServer.has(d));
+}
+export const dependencyFailedDetail = (missing) => `references ${missing.join(", ")}, which is not on the server: it failed or was not attempted in this apply`;

package/dist/core/classifier.js

@@ -0,0 +1,115 @@
+/**
+ * The change classifier's framework, the same in every dialect: the shape of
+ * a rule, a classified change, `classifyDisruption()` over a dialect's rules,
+ * and the text report.
+ *
+ * The classes are data, one set per dialect. ClickHouse classes a change by
+ * whether `ALTER` can make it (metadata, background rewrite, rebuild); another
+ * dialect classes by the lock a change takes and whether it rewrites the
+ * table. Each dialect declares its classes with {@link ChangeClasses} and its
+ * rules with {@link classifierRule}, every rule citing the database's own
+ * documentation for the restriction behind it.
+ */
+export const classifierRule = (id, cls, title, restriction, cite) => ({
+    id,
+    class: cls,
+    title,
+    restriction,
+    cite,
+});
+/** A classified change from `before` to `after`, its class read from `rules`. */
+export function classifiedChange(rules, object, field, rule, before, after, extra = {}) {
+    return {
+        object,
+        field,
+        ...(before !== undefined ? { before: String(before) } : {}),
+        ...(after !== undefined ? { after: String(after) } : {}),
+        rule,
+        class: rules[rule].class,
+        ...extra,
+    };
+}
+// ── classifyDisruption() ────────────────────────────────────────────────
+const RANK = { "in-place": 0, rolling: 1, replace: 2, destroy: 3, unknown: 4 };
+/**
+ * `classifyDisruption()` over a dialect's rules: each update's disruption is
+ * the worst class among its changed paths, and `unknown` when any path cannot
+ * be classified from the path alone.
+ */
+export function classifyDisruptionWith(classifier, options) {
+    const out = {};
+    for (const q of options.changes) {
+        if (q.type !== undefined && !q.type.startsWith(classifier.typePrefix))
+            continue;
+        let level = "in-place";
+        const because = [];
+        const rules = new Set();
+        let ambiguous = false;
+        for (const d of q.deltas) {
+            const r = classifier.ruleFor(d.path);
+            if (r === undefined || r === "ambiguous") {
+                ambiguous = true;
+                because.push(d.path);
+                continue;
+            }
+            const l = classifier.classes.disruption[classifier.rules[r].class];
+            if (RANK[l] > RANK[level]) {
+                level = l;
+                because.length = 0;
+            }
+            if (RANK[l] === RANK[level])
+                because.push(d.path);
+            rules.add(r);
+        }
+        if (ambiguous) {
+            out[q.name] = { disruption: "unknown", because, detail: classifier.ambiguousDetail };
+            continue;
+        }
+        out[q.name] = {
+            disruption: level,
+            because,
+            detail: [...rules].map((r) => `${r} ${classifier.rules[r].title}`).join("; "),
+        };
+    }
+    return out;
+}
+// ── The report ──────────────────────────────────────────────────────────
+/**
+ * A change set as text, for a terminal or a pull request: each object's
+ * changes with their class, rule, restriction and citation, then a count per
+ * class and the hints. `trailer` is the dialect's closing lines (what a plan
+ * refuses and what to run instead); it is left out when nothing changed.
+ */
+export function renderChangeSet(diff, opts) {
+    const lines = [];
+    if (opts.title)
+        lines.push(opts.title, "");
+    if (diff.changes.length === 0) {
+        lines.push("No changes.");
+        return lines.join("\n");
+    }
+    const byObject = new Map();
+    for (const c of diff.changes)
+        byObject.set(c.object, [...(byObject.get(c.object) ?? []), c]);
+    for (const [object, changes] of byObject) {
+        lines.push(object);
+        for (const c of changes) {
+            const rule = opts.rules[c.rule];
+            const values = c.before !== undefined && c.after !== undefined ? `: ${c.before} -> ${c.after}` : c.after !== undefined ? `: ${c.after}` : c.before !== undefined ? `: ${c.before}` : "";
+            lines.push(`  [${opts.classes.label[c.class]}] ${c.field}${values}`);
+            lines.push(`      ${c.rule} ${rule.title}${c.destructive ? " (destroys data)" : ""}. ${rule.restriction} ${rule.cite}`);
+            if (c.note)
+                lines.push(`      ${c.note}`);
+        }
+    }
+    const counts = opts.classes.order
+        .map((k) => [k, diff.changes.filter((c) => c.class === k).length])
+        .filter(([, n]) => n > 0)
+        .map(([k, n]) => `${n} ${opts.classes.label[k]}`);
+    lines.push("", counts.join(", "));
+    for (const h of diff.hints)
+        lines.push(`hint: ${h}`);
+    if (opts.trailer)
+        lines.push(...opts.trailer);
+    return lines.join("\n");
+}

package/dist/core/container.js

@@ -0,0 +1,69 @@
+/**
+ * A throwaway database server in a container, for every dialect: started on a
+ * random loopback port under a unique name, waited on until it answers, and
+ * always removed.
+ *
+ * Generation uses it on a pin move to read the pinned server's catalog, and
+ * the live tests use it so every container chant starts is started and
+ * cleaned up one way. What "answers" means (an HTTP ping, a query) and the
+ * image's environment are the dialect's.
+ */
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { randomBytes } from "node:crypto";
+const exec = promisify(execFile);
+/** True when a Docker daemon answers. Tests that need a server skip when this is false. */
+export async function dockerAvailable() {
+    try {
+        await exec("docker", ["info", "--format", "{{.ServerVersion}}"], { timeout: 15000 });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** A container name no other run picks: `<prefix>-<pid>-<random>`. */
+export function uniqueContainerName(prefix) {
+    return `${prefix}-${process.pid}-${randomBytes(4).toString("hex")}`;
+}
+/** The loopback host port Docker published for `containerPort` on `name`. */
+export async function publishedPort(name, containerPort) {
+    const { stdout } = await exec("docker", ["port", name, `${containerPort}/tcp`]);
+    const port = stdout.split("\n")[0]?.trim().split(":").pop();
+    if (!port)
+        throw new Error(`docker port reported no host port for ${name}`);
+    return port;
+}
+/**
+ * Run `image` detached, publish `containerPort` on a random loopback port,
+ * and wait until `ready(port)` is true, polling every half second. Pulls the
+ * image when it is not present, which is the one network step here. On any
+ * failure the container is removed before the error is thrown.
+ */
+export async function startScratchContainer(options) {
+    const name = uniqueContainerName(options.namePrefix);
+    let removed = false;
+    const stop = async () => {
+        if (removed)
+            return;
+        removed = true;
+        await exec("docker", ["rm", "-f", ...(options.removeVolumes ? ["-v"] : []), name]).catch(() => undefined);
+    };
+    try {
+        const env = Object.entries(options.env ?? {}).flatMap(([k, v]) => ["-e", `${k}=${v}`]);
+        await exec("docker", ["run", "-d", "--name", name, "-p", `127.0.0.1::${options.containerPort}`, ...env, options.image], { timeout: 600000 });
+        const port = await publishedPort(name, options.containerPort);
+        options.onStarted?.(name);
+        const deadline = Date.now() + options.readyTimeoutMs;
+        while (!(await options.ready(port))) {
+            if (Date.now() > deadline)
+                throw new Error(`${name} ${options.notReady} within the timeout`);
+            await new Promise((r) => setTimeout(r, 500));
+        }
+        return { name, port, stop };
+    }
+    catch (err) {
+        await stop();
+        throw err;
+    }
+}