@intentius/chant-lexicon-sql 0.124.30 → 0.124.32

package/dist/postgres/migrate/handoff.js

@@ -0,0 +1,59 @@
+/**
+ * How a Postgres plan hands an expand-and-contract change to the migration
+ * Op (#3281), as the ClickHouse plan hands a rebuild to its Op (#3250).
+ *
+ * `chant sql plan`, `chant sql diff`, the `classify-change` MCP tool and the
+ * applier refuse an expand-and-contract change in place. For a column
+ * rename (SQLPG205) and a type change across kinds (SQLPG208) what they hand
+ * on is a `PostgresMigrationOp` declaration per column, ready to put in an
+ * `*.op.ts` file, reviewed in the pull request like the schema change it
+ * carries out. The Op's own Plan phase classifies the change again against
+ * the server. The other expand-and-contract rules (a NOT NULL column with no
+ * default, partitioning, an object rename, a view's columns, enum labels, a
+ * domain's type, an object's kind) have no Op yet, and get none.
+ *
+ * Nothing is written for the user. The hand-off's shape is the shared
+ * core's (`../../core/handoff.ts`).
+ */
+import { migrationOpName, renderMigrationOps } from "../../core/handoff.js";
+/** The rules a refused change is handed to the Op for. */
+export const HANDED_OFF = new Set(["SQLPG205", "SQLPG208"]);
+const COLUMN = /^columns\.([^.]+)(?:\.type)?$/;
+/** The table and column a refused change is about, when the Op makes it. */
+export function migrationTarget(c, declared, defaultSchema = "public") {
+    if (!HANDED_OFF.has(c.rule) || !declared || declared.kind !== "table")
+        return undefined;
+    const m = COLUMN.exec(c.field);
+    if (!m || (c.rule === "SQLPG208" && !c.field.endsWith(".type")) || (c.rule === "SQLPG205" && c.field.endsWith(".type")))
+        return undefined;
+    return { table: `${declared.schema ?? defaultSchema}.${declared.name}`, column: m[1] };
+}
+/** The Op's declaration for one column. */
+export function migrationDeclaration(name, env, table, column) {
+    return `export const { op } = PostgresMigrationOp({ name: ${JSON.stringify(name)}, env: ${JSON.stringify(env)}, table: ${JSON.stringify(table)}, column: ${JSON.stringify(column)} });`;
+}
+/**
+ * One suggestion per column the diff refuses for a rename or a type change
+ * across kinds. `declared` maps the diff's object keys to the declared
+ * definitions.
+ */
+export function migrationOpSuggestions(refused, declared, env, defaultSchema = "public") {
+    const out = [];
+    const seen = new Set();
+    for (const c of refused) {
+        const t = migrationTarget(c, declared.get(c.object), defaultSchema);
+        if (!t)
+            continue;
+        const id = `${t.table}.${t.column}`;
+        if (seen.has(id))
+            continue;
+        seen.add(id);
+        const name = migrationOpName("migrate", id);
+        out.push({ table: t.table, column: t.column, rule: c.rule, name, env, declaration: migrationDeclaration(name, env, t.table, t.column) });
+    }
+    return out;
+}
+/** The suggestions as text, for the report. */
+export function renderMigrationOpSuggestions(ops) {
+    return renderMigrationOps(ops, { what: "the expand-and-contract migration Op", exportName: "PostgresMigrationOp", importPath: "@intentius/chant-lexicon-sql/postgres" });
+}

package/dist/postgres/migrate/names.js

@@ -0,0 +1,61 @@
+/**
+ * The names an expand-and-contract migration of one column uses (#3281), and
+ * the trailer that marks its working objects.
+ *
+ * A migration is keyed by `<schema>.<table>.<column>`, the column as the
+ * build declares it. Its working objects are:
+ *
+ * - the new column: the declared name for a rename (`login`), or
+ *   `<column>__chant_new` for a type change, until the switch;
+ * - the old column after the switch: the old name for a rename (`email`,
+ *   still written by the dual-write trigger), or `<column>__chant_old` for a
+ *   type change (no longer written);
+ * - the dual-write trigger `<column>__chant_sync` on the table and its
+ *   function `<table>__<column>__chant_sync` in the table's schema;
+ * - the check `<new>__chant_nn` that proves NOT NULL before it is set.
+ *
+ * Each carries chant's ownership trailer (`../../core/ownership.ts`) with
+ * `migration=<key>` and its role in its comment. The catalog read
+ * (`../live/catalog.ts`) leaves out a column or a constraint whose comment
+ * carries the `migration` key, so a plan, an import and a prune see the table
+ * as it was before the migration until the switch, and as declared after it.
+ */
+import { createHash } from "node:crypto";
+import { quoteIdent } from "../keywords.js";
+/** The trailer key on a migration's working objects. */
+export const MIGRATION_TRAILER_KEY = "migration";
+/** The longest identifier Postgres keeps (NAMEDATALEN - 1 bytes). */
+const MAX_IDENT = 63;
+/** A name Postgres keeps whole: `base`, or its first bytes and a short hash of all of it when it is longer than 63 bytes. */
+export function pgName(base) {
+    if (Buffer.byteLength(base, "utf8") <= MAX_IDENT)
+        return base;
+    const hash = createHash("sha256").update(base).digest("hex").slice(0, 8);
+    let head = base;
+    while (Buffer.byteLength(`${head}_${hash}`, "utf8") > MAX_IDENT)
+        head = head.slice(0, -1);
+    return `${head}_${hash}`;
+}
+export function migrationNames(schema, table, column, change, source) {
+    const newColumn = change === "rename" ? column : pgName(`${column}__chant_new`);
+    const fn = pgName(`${table}__${column}__chant_sync`);
+    return {
+        key: `${schema}.${table}.${column}`,
+        schema,
+        table,
+        column,
+        change,
+        source,
+        newColumn,
+        oldColumn: change === "rename" ? source : pgName(`${column}__chant_old`),
+        trigger: pgName(`${column}__chant_sync`),
+        fn,
+        check: pgName(`${newColumn}__chant_nn`),
+        qualifiedTable: pgQualified(schema, table),
+        qualifiedFn: pgQualified(schema, fn),
+    };
+}
+/** `schema.name`, each part quoted where Postgres needs it. */
+const pgQualified = (schema, name) => `${quoteIdent(schema)}.${quoteIdent(name)}`;
+/** A quoted column name. */
+export const col = (name) => quoteIdent(name);

package/dist/postgres/migrate/observe.js

@@ -0,0 +1,360 @@
+/**
+ * The expand-and-contract migration's view of the server (#3281): which
+ * column of which table is migrated, how far the migration has got, and
+ * what it will do.
+ *
+ * Every step of the Op re-observes from here rather than trusting what an
+ * earlier run or step said, so the Op converges: run it again after a crash,
+ * a gate or an approval, and each step finds its work done or still to do.
+ * The progress is read off the table itself: its columns, the dual-write
+ * trigger and its function, and the NOT NULL check, each carrying chant's
+ * trailer with `migration=<key>` and a role (`./names.ts`).
+ *
+ * The change is found the way `chant sql plan` finds it: the declared table
+ * against what the catalog read prints (`../plan/commands.ts`), which leaves
+ * the working columns out. So the plan shows the change refused until the
+ * switch, and the declaration held after it.
+ *
+ * States:
+ *
+ * - `migrate`: the declared column differs from the server's by a rename
+ *   (SQLPG205) or a type change (SQLPG207, SQLPG208), and the switch has not
+ *   run.
+ * - `switched`: the switch ran; the old column is kept until its date.
+ * - `done`: the server holds the declared column and nothing of the
+ *   migration is left.
+ *
+ * Anything else is refused with a {@link MigrationRefusal}, naming what to
+ * do: a table that is not there, a partition (run it on the partitioned
+ * table) or an inheritance tree; no primary key to batch by; a column in the
+ * partition key; a generated column; a column change the Op does not make
+ * (a rename and a type change at once, a rename of a column with a default
+ * or a sequence); something that uses the column and is
+ * not carried over to the new one (`./carry.ts`: indexes, key, check and
+ * foreign key constraints and declared views are); a publication that sends
+ * it; a working object chant did not make.
+ */
+import { computePlanDigest } from "@intentius/chant/op";
+import { carriesMarker, readTrailerPairs } from "../../core/ownership.js";
+import { planAgainstClient } from "../plan/commands.js";
+import { PG_CLASSIFIER_RULES } from "../plan/rules.js";
+import { qualifiedKey } from "../plan/schema.js";
+import { POSTGRES_ENTITY_TYPES } from "../entity-types.js";
+import { col, migrationNames, MIGRATION_TRAILER_KEY, pgName } from "./names.js";
+import { publicationsOf } from "./replication.js";
+import { keyText } from "./batches.js";
+import { carriedStates, carriedSubject, discoverDependents, replaceColumn, storedType } from "./carry.js";
+/** A refusal: the migration cannot start, or cannot go on, for a reason a person has to act on. */
+export class MigrationRefusal extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "MigrationRefusal";
+    }
+}
+/** The rules the Op makes: a rename, and a type change with or without a rewrite in place. */
+export const MIGRATION_RULES = new Set(["SQLPG205", "SQLPG207", "SQLPG208"]);
+/** The declared table with the given key (`schema.table`) or export name, or a refusal naming what is declared. */
+export function declaredTable(declared, key) {
+    const found = declared.find((o) => o.name === key || o.exportName === key);
+    if (!found) {
+        throw new MigrationRefusal(`${key} is not declared in the build. Declared tables: ${declared.filter((o) => o.type === POSTGRES_ENTITY_TYPES.table).map((o) => o.name).join(", ") || "none"}`);
+    }
+    if (found.type !== POSTGRES_ENTITY_TYPES.table)
+        throw new MigrationRefusal(`${key} is a ${found.type}, and the migration Op migrates a table's column`);
+    return found;
+}
+const pairsOf = (comment) => {
+    const p = readTrailerPairs(comment);
+    return p?.has(MIGRATION_TRAILER_KEY) ? p : undefined;
+};
+async function serverColumns(client, oid) {
+    const rows = await client.query(`SELECT a.attnum, a.attname AS name, pg_catalog.format_type(a.atttypid, a.atttypmod) AS type, a.attnotnull AS notnull,
+            pg_catalog.pg_get_expr(d.adbin, d.adrelid, true) AS dflt, pg_catalog.col_description(a.attrelid, a.attnum) AS comment,
+            a.attgenerated::text AS generated, a.attidentity::text AS identity
+     FROM pg_catalog.pg_attribute a LEFT JOIN pg_catalog.pg_attrdef d ON d.adrelid = a.attrelid AND d.adnum = a.attnum
+     WHERE a.attrelid = $1::oid AND a.attnum > 0 AND NOT a.attisdropped ORDER BY a.attnum`, [oid]);
+    return new Map(rows.map((r) => {
+        const comment = r.comment ?? undefined;
+        const pairs = pairsOf(comment);
+        return [
+            r.name,
+            {
+                attnum: Number(r.attnum),
+                name: r.name,
+                type: r.type,
+                notNull: r.notnull,
+                ...(r.dflt !== null ? { default: r.dflt } : {}),
+                ...(comment !== undefined ? { comment } : {}),
+                generated: r.generated !== "",
+                identity: r.identity !== "",
+                ...(pairs ? { pairs } : {}),
+            },
+        ];
+    }));
+}
+/** The server's major, from `server_version_num`. */
+export async function serverMajor(client) {
+    const [row] = await client.query("SELECT pg_catalog.current_setting('server_version_num') AS v");
+    return Math.floor(Number(row?.v ?? "0") / 10000);
+}
+/**
+ * A working object is this migration's only when it carries this project's
+ * marker, names this migration and has the role its name says. One that has
+ * the name and not the marker is somebody else's, and the migration stops
+ * rather than drop or fill it.
+ */
+function own(o, names, role, what, marker) {
+    if (!o)
+        return undefined;
+    if (!carriesMarker(o.comment, marker) || o.pairs?.get(MIGRATION_TRAILER_KEY) !== names.key || o.pairs.get("role") !== role) {
+        throw new MigrationRefusal(`${names.schema}.${names.table}: ${what} ${o.name} exists and is not this migration's (its comment carries no migration=${names.key} role=${role} marker for this project). ` +
+            `The migration uses that name, so it stops rather than touch it; rename or drop it by hand.`);
+    }
+    return o;
+}
+/** The change the declaration makes to the column, as a plan against the server classifies it. */
+async function columnChanges(input) {
+    const { declared } = input;
+    const plan = await planAgainstClient(input.client, input.target, [{ key: declared.exportName, canonical: declared.canonical }], input.major !== undefined ? { major: input.major } : {});
+    const key = qualifiedKey(declared.canonical);
+    const changes = plan.diff.changes.filter((c) => c.object === key && (c.field === `columns.${input.column}` || c.field.startsWith(`columns.${input.column}.`)));
+    return { changes, ...(plan.major !== undefined ? { major: plan.major } : {}) };
+}
+const ruleText = (c) => `${c.rule} ${PG_CLASSIFIER_RULES[c.rule].title} (${c.field}${c.before !== undefined || c.after !== undefined ? `: ${c.before ?? "-"} -> ${c.after ?? "-"}` : ""})`;
+/**
+ * The tables the Op migrates: an ordinary table, and a partitioned one, whose
+ * partitions take every column change, trigger, check and `NOT NULL` from it.
+ * A partition is migrated through its partitioned table. Inheritance (not
+ * partitioning) is refused: a write to a child table does not fire its
+ * parent's trigger, so the dual write would miss it, and a child's indexes
+ * and constraints are its own, which the carry-over does not read.
+ */
+function refuseRelation(where, rel) {
+    if (rel.partition) {
+        throw new MigrationRefusal(`${where} is a partition of ${rel.parents}. A partition's columns are its partitioned table's: run the Op on ${rel.parents}, which migrates every partition.`);
+    }
+    if (rel.parents) {
+        throw new MigrationRefusal(`${where} inherits from ${rel.parents}. An inherited column is changed through its parent, and the Op does not migrate inheritance trees: ` +
+            `a write to a child table does not fire its parent's dual-write trigger, and each child's indexes and constraints are its own. Migrate by hand, or move to declarative partitioning (chant #3333).`);
+    }
+    if (rel.kind === "r" && rel.children) {
+        throw new MigrationRefusal(`${where} has inheritance children (${rel.children}). The Op does not migrate inheritance trees: a write to a child table does not fire the parent's dual-write trigger, ` +
+            `so the new column would miss it, and each child's indexes and constraints are its own. Migrate by hand, or move to declarative partitioning (chant #3333).`);
+    }
+    if (rel.kind !== "r" && rel.kind !== "p")
+        throw new MigrationRefusal(`${where} is not a table (relkind ${rel.kind}); the migration Op migrates a table's column`);
+}
+/** Observe the migration of the declared table's column on the server. */
+export async function observeMigration(input) {
+    const { client, declared, marker } = input;
+    const schema = declared.canonical.schema ?? input.target.defaultSchema;
+    const table = declared.canonical.name;
+    const where = `${schema}.${table}`;
+    const [rel] = await client.query(`SELECT c.oid::text AS oid, c.relkind::text AS kind, c.relispartition AS partition,
+            (SELECT pg_catalog.string_agg(i.inhparent::pg_catalog.regclass::text, ', ') FROM pg_catalog.pg_inherits i WHERE i.inhrelid = c.oid) AS parents,
+            (SELECT pg_catalog.string_agg(i.inhrelid::pg_catalog.regclass::text, ', ' ORDER BY i.inhrelid::pg_catalog.regclass::text) FROM pg_catalog.pg_inherits i WHERE i.inhparent = c.oid) AS children,
+            CASE WHEN c.relkind = 'p' THEN pg_catalog.pg_get_partkeydef(c.oid) END AS partkey,
+            (SELECT p.partattrs::int2[] FROM pg_catalog.pg_partitioned_table p WHERE p.partrelid = c.oid) AS partattrs
+     FROM pg_catalog.pg_class c WHERE c.oid = pg_catalog.to_regclass($1)`, [`${col(schema)}.${col(table)}`]);
+    if (!rel)
+        throw new MigrationRefusal(`${where} is not on the server, so there is no column to migrate; the applier creates it`);
+    refuseRelation(where, rel);
+    const declaredColumns = declared.props.columns ?? [];
+    const column = declaredColumns.find((c) => c.name === input.column);
+    if (!column)
+        throw new MigrationRefusal(`${where} declares no column ${input.column}. Declared columns: ${declaredColumns.map((c) => c.name).join(", ") || "none"}`);
+    const columns = await serverColumns(client, rel.oid);
+    const { changes, major: planned } = await columnChanges(input);
+    const major = planned ?? (await serverMajor(client));
+    // The change, and the column it comes from: from the plan while it is
+    // pending, else from the old column this migration kept after its switch.
+    const rename = changes.find((c) => c.rule === "SQLPG205");
+    const typeChange = changes.find((c) => c.rule === "SQLPG206" || c.rule === "SQLPG207" || c.rule === "SQLPG208");
+    const key = `${schema}.${table}.${input.column}`;
+    const mine = [...columns.values()].filter((c) => c.pairs?.get(MIGRATION_TRAILER_KEY) === key);
+    const keptOld = mine.find((c) => c.pairs.get("role") === "old");
+    let change = "type";
+    let sourceName = input.column;
+    if (rename) {
+        change = "rename";
+        sourceName = String(rename.before);
+    }
+    else if (keptOld && keptOld.name !== pgName(`${input.column}__chant_old`)) {
+        change = "rename";
+        sourceName = keptOld.name;
+    }
+    const names = migrationNames(schema, table, input.column, change, sourceName);
+    // Whatever the state, a working object under a migration name, or with this
+    // migration's key, is this migration's or it is refused.
+    for (const c of mine)
+        own(c, names, String(c.pairs.get("role")), "column", marker);
+    const working = (name) => (change === "type" || columns.get(name)?.pairs ? columns.get(name) : undefined);
+    const newColumn = own(working(names.newColumn), names, "new", "column", marker);
+    const old = own(working(names.oldColumn), names, "old", "column", marker);
+    const [trigRow] = await client.query("SELECT t.tgname AS name, pg_catalog.obj_description(t.oid, 'pg_trigger') AS comment FROM pg_catalog.pg_trigger t WHERE t.tgrelid = $1::oid AND t.tgname = $2", [rel.oid, names.trigger]);
+    const [fnRow] = await client.query("SELECT p.proname AS name, pg_catalog.obj_description(p.oid, 'pg_proc') AS comment FROM pg_catalog.pg_proc p JOIN pg_catalog.pg_namespace n ON n.oid = p.pronamespace WHERE n.nspname = $1 AND p.proname = $2 AND p.pronargs = 0", [schema, names.fn]);
+    const [checkRow] = await client.query("SELECT c.conname AS name, pg_catalog.obj_description(c.oid, 'pg_constraint') AS comment, c.convalidated AS validated FROM pg_catalog.pg_constraint c WHERE c.conrelid = $1::oid AND c.conname = $2", [rel.oid, names.check]);
+    const asObject = (r) => r ? { name: r.name, ...(r.comment !== null ? { comment: r.comment } : {}), ...(pairsOf(r.comment ?? undefined) ? { pairs: pairsOf(r.comment ?? undefined) } : {}) } : undefined;
+    const trigger = own(asObject(trigRow), names, "dual", "trigger", marker);
+    const fn = own(asObject(fnRow), names, "dual", "function", marker);
+    const checkObj = own(asObject(checkRow), names, "nn", "check constraint", marker);
+    const check = checkObj ? { ...checkObj, validated: checkRow.validated } : undefined;
+    const migrating = rename !== undefined || (typeChange !== undefined && typeChange.rule !== "SQLPG206");
+    let state;
+    if (old) {
+        if (migrating) {
+            throw new MigrationRefusal(`${where}.${input.column} differs from its declaration again, and the old column of the last migration is still kept as ${names.oldColumn}. ` +
+                `Run the contract (its gate, then the Contract phase) before migrating the column again.`);
+        }
+        state = "switched";
+    }
+    else if (migrating) {
+        state = "migrate";
+    }
+    else if (changes.length === 0) {
+        if (newColumn || trigger || fn || check) {
+            throw new MigrationRefusal(`${where}.${input.column} already holds its declaration, and ${[newColumn && `column ${newColumn.name}`, trigger && `trigger ${trigger.name}`, fn && `function ${fn.name}`, check && `check ${check.name}`].filter(Boolean).join(", ")} ` +
+                `from an unfinished migration is still there. The run fails so onFailure drops it.`);
+        }
+        state = "done";
+    }
+    else {
+        throw new MigrationRefusal(`${where}.${input.column} has no change the migration Op makes: ${changes.map(ruleText).join("; ")}. ` +
+            `The applier makes these in place (ApplyOp with target "postgres").`);
+    }
+    const source = state === "migrate" ? columns.get(sourceName) : undefined;
+    let batchKey = "";
+    let keyColumns = [];
+    let dependents = { carried: [], views: [] };
+    let states = new Map();
+    let expression = col(sourceName);
+    let publications = [];
+    if (state === "migrate") {
+        if (!source)
+            throw new MigrationRefusal(`${where}: the column ${sourceName} the values come from is not on the server`);
+        ({ batchKey, keyColumns, dependents } = await refuseUnsupported(input, names, rel, source, column, changes, rename !== undefined, typeChange));
+        states = await carriedStates(client, dependents.carried, (comment) => {
+            const pairs = pairsOf(comment);
+            if (!pairs)
+                return comment === undefined ? "none" : "theirs";
+            return pairs.get(MIGRATION_TRAILER_KEY) === names.key && pairs.get("role") === "carry" && carriesMarker(comment, marker) ? "ours" : "theirs";
+        }, (what) => {
+            throw new MigrationRefusal(`${where}: ${what} exists and is not this migration's (its comment carries no migration=${names.key} role=carry marker for this project). The migration uses that name, so it stops rather than touch it; rename or drop it by hand.`);
+        });
+        if (change === "type") {
+            expression = input.using ?? `CAST(${col(sourceName)} AS ${storedType(column.type)})`;
+            if (expression.includes("$chant$"))
+                throw new MigrationRefusal(`${where}: the using expression may not contain $chant$, which quotes the dual-write function's body`);
+        }
+        else if (input.using !== undefined) {
+            throw new MigrationRefusal(`${where}.${input.column} is a rename of ${sourceName}, which copies the value as it is; using is for a type change`);
+        }
+        // The declared type as the classifier compared it: the server's spelling (character varying(10), not varchar(10)).
+        const serial = storedType(column.type) !== column.type;
+        const expectedType = change === "type" ? (serial ? storedType(column.type) : String(typeChange?.after ?? column.type)) : source.type;
+        if (newColumn && newColumn.type !== expectedType) {
+            throw new MigrationRefusal(`${where}: ${newColumn.name} was made as ${newColumn.type}, from another declaration of ${input.column} (now ${column.type}). The run fails so onFailure drops it, and the next run starts again from the current declaration.`);
+        }
+        publications = await publicationsOf(client, schema, table, sourceName, major);
+        if (publications.length > 0) {
+            throw new MigrationRefusal(`${where}.${sourceName} is sent by logical replication publication(s) ${publications.map((p) => `${p.name}${p.allColumns ? " (every column)" : ""}`).join(", ")}. ` +
+                `A subscriber applies changes by column name and must have every column the publisher sends, so the column the expand adds would stop the subscriber's apply at the first backfilled row, ` +
+                `and the switch would need the same change on the subscriber at the same moment (https://www.postgresql.org/docs/18/logical-replication-col-lists.html). ` +
+                `Leave the column out of the publication with a column list (15 and later), or migrate the subscriber's table as well and run this Op on a table no publication sends. ` +
+                `A migration of the publisher and the subscriber together is chant #3332.`);
+        }
+    }
+    return {
+        state,
+        names,
+        declared,
+        column,
+        oid: rel.oid,
+        batchKey,
+        keyColumns,
+        carried: dependents.carried,
+        carriedStates: states,
+        views: dependents.views,
+        ...(dependents.sequence ? { sequence: dependents.sequence } : {}),
+        partitioned: rel.kind === "p",
+        columns,
+        ...(source ? { source } : {}),
+        ...(newColumn ? { newColumn } : {}),
+        ...(old ? { old } : {}),
+        ...(trigger ? { trigger } : {}),
+        ...(fn ? { fn } : {}),
+        ...(check ? { check } : {}),
+        changes,
+        expression,
+        publications,
+        major,
+    };
+}
+/** The checks that hold only while there is something to migrate. Returns the batch key and what the Op carries over. */
+async function refuseUnsupported(input, names, rel, source, column, changes, rename, typeChange) {
+    const where = `${names.schema}.${names.table}`;
+    const oid = rel.oid;
+    if (rename && typeChange) {
+        throw new MigrationRefusal(`${where}: ${source.name} is renamed to ${names.column} and its type changes (${typeChange.before} -> ${typeChange.after}) in one declaration. ` +
+            `Migrate one at a time: declare the rename with the old type, run the Op to its end, then change the type. ` +
+            `(In one run both names would stay written until the contract, which needs a conversion back to the old type for writers of the new name; chant #3331.)`);
+    }
+    if (rename && (source.default !== undefined || column.default !== undefined)) {
+        throw new MigrationRefusal(`${where}: ${source.name} has a default (${source.default ?? column.default}). During a rename both columns are written, each from the other, ` +
+            `and a row inserted by a writer that names one column would get the other's default, which the trigger cannot tell from a value it was given. ` +
+            `Drop the default first (the applier does), rename, then declare it again. A rename that keeps its default needs versioned views (chant #3331).`);
+    }
+    if (source.generated || (column.generated && column.generated.kind !== "identity")) {
+        throw new MigrationRefusal(`${where}.${source.name} is a generated column. There is no expand and contract for one: Postgres cannot make an existing column generated, so the new column could only be added generated, ` +
+            `which computes every row under ACCESS EXCLUSIVE (a stored one) or needs no migration (a virtual one stores nothing). The applier makes the change in place (SQLPG207), in a maintenance window for a stored column.`);
+    }
+    const unsupported = changes.filter((c) => /\.(generated|identity|collate|storage)$/.test(c.field));
+    if (unsupported.length > 0) {
+        throw new MigrationRefusal(`${where}.${names.column}: a change to its collation, storage, generation or identity (${unsupported.map(ruleText).join("; ")}) is not one the Op makes; the applier makes it in place.`);
+    }
+    if (rel.kind === "p" && ((rel.partattrs ?? []).map(Number).includes(source.attnum) || (rel.partkey !== null && replaceColumn(rel.partkey, source.name, `${source.name}_`) !== rel.partkey))) {
+        throw new MigrationRefusal(`${where}.${source.name} is in the partition key (${rel.partkey}). A changed partition key would move rows between partitions, which no trigger can do; the Op migrates a partitioned table's other columns.`);
+    }
+    const dependents = await discoverDependents({
+        client: input.client,
+        names,
+        oid,
+        attnum: source.attnum,
+        objects: input.objects ?? [input.declared],
+        declared: input.declared,
+        defaultSchema: input.target.defaultSchema,
+        partitioned: rel.kind === "p",
+    });
+    if (dependents.refused.length > 0) {
+        throw new MigrationRefusal(`${where}.${source.name} is used by what the migration Op does not carry over to the new column: ${dependents.refused.join("; ")}. ` +
+            `The old column could not be dropped while they use it.`);
+    }
+    const keys = await input.client.query(`SELECT a.attname AS name, pg_catalog.format_type(a.atttypid, a.atttypmod) AS type
+     FROM pg_catalog.pg_constraint c, pg_catalog.unnest(c.conkey) WITH ORDINALITY AS k(attnum, ord)
+     JOIN pg_catalog.pg_attribute a ON a.attnum = k.attnum
+     WHERE c.conrelid = $1::oid AND c.contype = 'p' AND a.attrelid = c.conrelid ORDER BY k.ord`, [oid]);
+    if (keys.length === 0) {
+        throw new MigrationRefusal(`${where} has no primary key. The backfill fills the new column in batches of the primary key's ranges, the same rows in every run, which needs one; declare a primary key first.`);
+    }
+    return { batchKey: keyText(keys), keyColumns: keys, dependents: { carried: dependents.carried, views: dependents.views, ...(dependents.sequence ? { sequence: dependents.sequence } : {}) } };
+}
+/**
+ * What the migration will do, independent of how far it has got: the
+ * change, the column on both sides, the expression, the batch key. The
+ * Plan phase publishes its digest; the gate binds a digest of this and the
+ * verification.
+ */
+export function migrationPlanSubject(o) {
+    return {
+        migration: o.names.key,
+        change: o.names.change,
+        from: o.source ? { name: o.source.name, type: o.source.type, notNull: o.source.notNull, default: o.source.default ?? null } : null,
+        to: { name: o.column.name, type: o.column.type ?? null, notNull: o.column.notNull === true, default: o.column.default ?? null, comment: o.column.comment ?? null },
+        expression: o.expression,
+        batchKey: o.batchKey,
+        rules: o.changes.map((c) => c.rule),
+        ...(o.carried.length > 0 || o.views.length > 0 || o.sequence ? { dependents: carriedSubject(o) } : {}),
+    };
+}
+export const migrationPlanDigest = (o) => computePlanDigest("postgres-migration", migrationPlanSubject(o));
+export { MIGRATION_TRAILER_KEY };