@intentius/chant-lexicon-sql 0.0.0-stage → 0.112.1

package/src/postgres/migrate/handoff.ts

@@ -0,0 +1,73 @@
+/**
+ * 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, type MigrationOpSuggestion } from "../../core/handoff";
+import type { PgChange } from "../plan/diff";
+import type { PgDiffObject } from "../plan/schema";
+
+export interface PostgresMigrationOpSuggestion extends MigrationOpSuggestion {
+  /** `schema.table`, the Op's `table`. */
+  table: string;
+  /** The declared column, the Op's `column`. */
+  column: string;
+  /** The rule the Op makes the change for. */
+  rule: "SQLPG205" | "SQLPG208";
+}
+
+/** 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: PgChange, declared: Pick<PgDiffObject, "kind" | "schema" | "name"> | undefined, defaultSchema = "public"): { table: string; column: string } | undefined {
+  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: string, env: string, table: string, column: string): string {
+  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: readonly PgChange[], declared: ReadonlyMap<string, PgDiffObject>, env: string, defaultSchema = "public"): PostgresMigrationOpSuggestion[] {
+  const out: PostgresMigrationOpSuggestion[] = [];
+  const seen = new Set<string>();
+  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 as "SQLPG205" | "SQLPG208", name, env, declaration: migrationDeclaration(name, env, t.table, t.column) });
+  }
+  return out;
+}
+
+/** The suggestions as text, for the report. */
+export function renderMigrationOpSuggestions(ops: readonly PostgresMigrationOpSuggestion[]): string[] {
+  return renderMigrationOps(ops, { what: "the expand-and-contract migration Op", exportName: "PostgresMigrationOp", importPath: "@intentius/chant-lexicon-sql/postgres" });
+}

package/src/postgres/migrate/kinds.e2e.test.ts

@@ -0,0 +1,204 @@
+/**
+ * Identity, serial and partitioned tables in the migration Op (#3322),
+ * against the pinned server, and what it refuses among the rest:
+ *
+ * - `integer` to `bigint` on an identity primary key another table
+ *   references: the identity moves to the new column under its sequence's
+ *   name and carries on from where the old one stood.
+ * - `serial` to `bigserial`: the sequence is handed to the new column,
+ *   widened, and stays its default.
+ * - A column of a partitioned table: every partition follows the
+ *   partitioned table.
+ * - Refused, each naming why: a partition, an inheritance tree, a column in
+ *   the partition key, an index on a partitioned table, a generated column,
+ *   a rename of an identity column.
+ *
+ * Needs Docker; skips cleanly without it.
+ */
+
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { dockerAvailable, startTestPostgres, type TestPostgres } from "../testing/server";
+import { ApprovingLedger, runMigrationOp, runOutcome } from "../testing/migration";
+import type { PostgresClient } from "../live/client";
+import { planPgAgainstServer } from "../plan/commands";
+import { postgresApply } from "../../op/activities/postgres-apply";
+import { postgresMigrationPlan, type PostgresMigrationDeps } from "../../op/activities/postgres-migration";
+import type { PostgresMigrationOpConfig } from "./op";
+
+const enabled = await dockerAvailable();
+let server: TestPostgres | undefined;
+let admin: PostgresClient | undefined;
+const dir = mkdtempSync(join(tmpdir(), "chant-pg-kinds-"));
+
+beforeAll(async () => {
+  if (!enabled) return;
+  server = await startTestPostgres();
+  admin = await server.connect();
+}, 600_000);
+
+afterAll(async () => {
+  await admin?.end();
+  await server?.stop();
+  rmSync(dir, { recursive: true, force: true });
+});
+
+interface Obj {
+  export: string;
+  type: string;
+  ddl: string;
+  dependsOn?: string[];
+}
+
+function writeBuild(file: string, objects: Obj[]): string {
+  writeFileSync(join(dir, file), JSON.stringify({ dialect: "postgres", postgresMajor: 18, applyOrder: objects.map((o) => o.export), objects: objects.map((o) => ({ dependsOn: [], ...o })) }));
+  return file;
+}
+
+const MARKER = { stack: "e2e", env: "test" };
+const profile = () => ({
+  config: { ownership: MARKER, sql: { profiles: { e2e: { url: server!.endpoint().url, password: { env: "PG_E2E_PASSWORD" } } } } },
+  env: { PG_E2E_PASSWORD: server!.endpoint().password },
+});
+const deps = (): PostgresMigrationDeps => ({ ...profile(), log: () => undefined });
+const apply = (file: string) => postgresApply({ buildPath: join(dir, file), environment: "e2e" }, undefined, { ...profile(), log: () => undefined });
+const plan = (file: string) => planPgAgainstServer("e2e", join(dir, file), profile());
+const one = async <T>(sql: string): Promise<T> => (await admin!.query<T>(sql))[0]!;
+const schemaObj = (name: string): Obj => ({ export: name, type: "Postgres::Schema", ddl: `CREATE SCHEMA ${name}` });
+const table = (exportName: string, schema: string, ddl: string, dependsOn: string[] = []): Obj => ({ export: exportName, type: "Postgres::Table", dependsOn: [schema, ...dependsOn], ddl });
+const config = (over: Pick<PostgresMigrationOpConfig, "name" | "table" | "column" | "output"> & Partial<PostgresMigrationOpConfig>): PostgresMigrationOpConfig => ({
+  env: "e2e",
+  build: false,
+  path: dir,
+  retain: "0s",
+  stack: MARKER.stack,
+  ownershipEnv: MARKER.env,
+  ...over,
+});
+const typeOf = async (table: string, column: string) =>
+  (await one<{ t: string }>(`SELECT pg_catalog.format_type(atttypid, atttypmod) AS t FROM pg_catalog.pg_attribute WHERE attrelid = '${table}'::regclass AND attname = '${column}'`)).t;
+
+/** Run the Op, approving each gate, until it is done; `between` runs after the first run (writes during the migration). */
+async function runToEnd(c: PostgresMigrationOpConfig, between?: () => Promise<void>) {
+  const ledger = new ApprovingLedger();
+  const runs = [];
+  for (let i = 0; i < 4; i++) {
+    const r = await runMigrationOp(c, ledger.port, deps);
+    runs.push(r);
+    if (i === 0) await between?.();
+    if (r.status !== "gated") break;
+    ledger.approveLast();
+  }
+  return runs;
+}
+
+describe.skipIf(!enabled)("an identity primary key another table references, integer to bigint", () => {
+  test("the identity moves to the bigint column under its sequence's name and carries on where it stood", async () => {
+    const IDN = schemaObj("idn");
+    const users = (t: string) => table("users", "idn", `CREATE TABLE idn.users (id ${t} GENERATED ALWAYS AS IDENTITY PRIMARY KEY, name text NOT NULL)`);
+    const POSTS = table("posts", "idn", "CREATE TABLE idn.posts (id bigint PRIMARY KEY, user_id integer NOT NULL REFERENCES idn.users (id))", ["users"]);
+    await apply(writeBuild("idn-v1.json", [IDN, users("integer"), POSTS]));
+    await admin!.query("INSERT INTO idn.users (name) SELECT 'u' || g FROM generate_series(1, 1500) g");
+    await admin!.query("INSERT INTO idn.posts SELECT g, (g % 1500) + 1 FROM generate_series(1, 2000) g");
+    writeBuild("idn-v2.json", [IDN, users("bigint"), POSTS]);
+
+    const runs = await runToEnd(config({ name: "migrate-users-id", table: "idn.users", column: "id", output: "idn-v2.json" }), async () => {
+      // A writer during the migration takes its id from the old identity; the trigger fills the new column.
+      await admin!.query("INSERT INTO idn.users (name) VALUES ('during')");
+    });
+    expect(runs.map((r) => r.status)).toEqual(["gated", "gated", "ok"]);
+    expect(String(runOutcome(runs[0]!, "Verification"))).toMatch(/foreign-key posts_user_id_fkey, key users_pkey carried over/);
+    expect(await typeOf("idn.users", "id")).toBe("bigint");
+    expect(await one("SELECT a.attidentity::text AS identity, pg_catalog.pg_get_serial_sequence('idn.users', 'id') AS seq FROM pg_catalog.pg_attribute a WHERE a.attrelid = 'idn.users'::regclass AND a.attname = 'id'")).toEqual({
+      identity: "a",
+      seq: "idn.users_id_seq",
+    });
+    expect(await one("SELECT data_type::text AS t FROM pg_catalog.pg_sequences WHERE schemaname = 'idn' AND sequencename = 'users_id_seq'")).toEqual({ t: "bigint" });
+    // The next id carries on from the last one the old identity gave.
+    expect(await one("INSERT INTO idn.users (name) VALUES ('after') RETURNING id::int AS id")).toEqual({ id: 1502 });
+    await admin!.query("INSERT INTO idn.posts VALUES (5000, 1502)");
+    expect((await plan("idn-v2.json")).changes).toEqual([]);
+  }, 300_000);
+});
+
+describe.skipIf(!enabled)("a serial column widened to bigserial", () => {
+  test("the sequence is handed to the new column, widened, and stays its default", async () => {
+    const SR = schemaObj("sr");
+    const items = (t: string) => table("items", "sr", `CREATE TABLE sr.items (id ${t} PRIMARY KEY, v text)`);
+    await apply(writeBuild("sr-v1.json", [SR, items("serial")]));
+    await admin!.query("INSERT INTO sr.items (v) SELECT 'v' || g FROM generate_series(1, 800) g");
+    writeBuild("sr-v2.json", [SR, items("bigserial")]);
+    // serial to bigserial is integer to bigint, SQLPG207, with the sequence widened: the plan prints it unqualified.
+    expect((await plan("sr-v2.json")).changes.map((c) => [c.rule, c.field, c.before, c.after])).toEqual([["SQLPG207", "columns.id.type", "serial", "bigserial"]]);
+
+    const runs = await runToEnd(config({ name: "migrate-items-id", table: "sr.items", column: "id", output: "sr-v2.json" }), async () => {
+      await admin!.query("INSERT INTO sr.items (v) VALUES ('during')");
+    });
+    expect(runs.map((r) => r.status)).toEqual(["gated", "gated", "ok"]);
+    expect(await typeOf("sr.items", "id")).toBe("bigint");
+    expect(await one("SELECT pg_catalog.pg_get_serial_sequence('sr.items', 'id') AS seq, (SELECT data_type::text FROM pg_catalog.pg_sequences WHERE sequencename = 'items_id_seq') AS t")).toEqual({
+      seq: "sr.items_id_seq",
+      t: "bigint",
+    });
+    expect(await one("INSERT INTO sr.items (v) VALUES ('after') RETURNING id::int AS id")).toEqual({ id: 802 });
+    expect((await plan("sr-v2.json")).changes).toEqual([]);
+  }, 300_000);
+});
+
+describe.skipIf(!enabled)("a column of a partitioned table", () => {
+  test("text to numeric: every partition follows the partitioned table", async () => {
+    const PT = schemaObj("pt");
+    const events = (t: string) => table("events", "pt", `CREATE TABLE pt.events (id bigint, at date NOT NULL, amount ${t} NOT NULL, PRIMARY KEY (id, at)) PARTITION BY RANGE (at)`);
+    const part = (y: number): Obj => table(`events${y}`, "pt", `CREATE TABLE pt.events_${y} PARTITION OF pt.events FOR VALUES FROM ('${y}-01-01') TO ('${y + 1}-01-01')`, ["events"]);
+    await apply(writeBuild("pt-v1.json", [PT, events("text"), part(2025), part(2026)]));
+    await admin!.query("INSERT INTO pt.events SELECT g, DATE '2025-06-01' + (g % 400), (g % 90) || '.5' FROM generate_series(1, 1200) g");
+    writeBuild("pt-v2.json", [PT, events("numeric(10,2)"), part(2025), part(2026)]);
+    expect((await plan("pt-v2.json")).changes.map((c) => [c.rule, c.field])).toEqual([["SQLPG208", "columns.amount.type"]]);
+
+    const runs = await runToEnd(config({ name: "migrate-events-amount", table: "pt.events", column: "amount", output: "pt-v2.json", batchSize: 500 }), async () => {
+      await admin!.query("INSERT INTO pt.events VALUES (9000, DATE '2026-03-01', '2.25')");
+    });
+    expect(runs.map((r) => r.status)).toEqual(["gated", "gated", "ok"]);
+    expect(runOutcome(runs[0]!, "Filled")).toBe(3);
+    for (const t of ["pt.events", "pt.events_2025", "pt.events_2026"]) expect(await typeOf(t, "amount")).toBe("numeric(10,2)");
+    expect(await one("SELECT amount::text AS a FROM pt.events WHERE id = 9000")).toEqual({ a: "2.25" });
+    expect(await one("SELECT count(*)::int AS n FROM pg_catalog.pg_attribute WHERE attrelid IN ('pt.events'::regclass, 'pt.events_2025'::regclass, 'pt.events_2026'::regclass) AND attname LIKE 'amount__chant%' AND NOT attisdropped")).toEqual({ n: 0 });
+    expect((await plan("pt-v2.json")).changes).toEqual([]);
+  }, 300_000);
+});
+
+describe.skipIf(!enabled)("what the Op refuses among the rest", () => {
+  const RF = schemaObj("rf");
+  const refusal = (tableName: string, column: string, output: string) =>
+    postgresMigrationPlan({ table: tableName, column, buildPath: output, environment: "e2e", stack: MARKER.stack, ownershipEnv: MARKER.env, cwd: dir }, undefined, deps()).then(
+      () => "",
+      (e: unknown) => String((e as Error).message),
+    );
+
+  test("a partition, an inheritance tree, the partition key, an index on a partitioned table, a generated column, a renamed identity", async () => {
+    const parted = (v: string, key = "at") => table("parted", "rf", `CREATE TABLE rf.parted (id bigint, at date, v ${v}, PRIMARY KEY (id, at)) PARTITION BY RANGE (${key})`);
+    const p1 = table("parted1", "rf", "CREATE TABLE rf.parted1 PARTITION OF rf.parted FOR VALUES FROM ('2025-01-01') TO ('2026-01-01')", ["parted"]);
+    const parent = (v: string) => table("parent", "rf", `CREATE TABLE rf.parent (id bigint PRIMARY KEY, v ${v})`);
+    const gen = (g: string) => table("gen", "rf", `CREATE TABLE rf.gen (id bigint PRIMARY KEY, a integer, g ${g} GENERATED ALWAYS AS (a * 2) STORED)`);
+    const ident = (c: string, hint = "") => table("ident", "rf", `CREATE TABLE rf.ident (\n  ${c} integer GENERATED ALWAYS AS IDENTITY PRIMARY KEY,${hint}\n  v text\n)`);
+    await apply(writeBuild("rf-v1.json", [RF, parted("integer"), p1, parent("integer"), gen("integer"), ident("id")]));
+    await admin!.query("CREATE TABLE rf.child (extra text) INHERITS (rf.parent)");
+    await admin!.query("CREATE INDEX parted_v_idx ON rf.parted (v)");
+    writeBuild("rf-v2.json", [RF, parted("bigint"), p1, parent("bigint"), gen("bigint"), ident("key", " -- previously: id")]);
+
+    expect(await refusal("rf.parted1", "v", "rf-v2.json")).toMatch(/^rf\.parted1 is a partition of rf\.parted\. A partition's columns are its partitioned table's: run the Op on rf\.parted/);
+    expect(await refusal("rf.parent", "v", "rf-v2.json")).toMatch(/^rf\.parent has inheritance children \(rf\.child\)\. The Op does not migrate inheritance trees: a write to a child table does not fire the parent's dual-write trigger/);
+    expect(await refusal("rf.parted", "v", "rf-v2.json")).toMatch(/index rf\.parted_v_idx is a partitioned index, which cannot be built CONCURRENTLY/);
+    expect(await refusal("rf.gen", "g", "rf-v2.json")).toMatch(/^rf\.gen\.g is a generated column\. There is no expand and contract for one/);
+    expect(await refusal("rf.ident", "key", "rf-v2.json")).toMatch(/sequence rf\.ident_id_seq gives the column its values \(an identity column\); during a rename/);
+
+    await admin!.query("DROP INDEX rf.parted_v_idx");
+    writeBuild("rf-v3.json", [RF, parted("integer", "v"), p1]);
+    await admin!.query("DROP TABLE rf.parted");
+    await apply(writeBuild("rf-v3.json", [RF, table("parted", "rf", "CREATE TABLE rf.parted (id bigint, at date, v integer, PRIMARY KEY (id, v)) PARTITION BY RANGE (v)")]));
+    writeBuild("rf-v4.json", [RF, table("parted", "rf", "CREATE TABLE rf.parted (id bigint, at date, v bigint, PRIMARY KEY (id, v)) PARTITION BY RANGE (v)")]);
+    expect(await refusal("rf.parted", "v", "rf-v4.json")).toMatch(/rf\.parted\.v is in the partition key \(RANGE \(v\)\)/);
+  }, 300_000);
+});

package/src/postgres/migrate/migrate.e2e.test.ts

@@ -0,0 +1,362 @@
+/**
+ * The expand-and-contract migration against the pinned server (#3281).
+ *
+ * - A column rename: the plan and the applier refuse it and name the Op; the
+ *   Op stops at its gate with the verification on the run record while old
+ *   writers keep working, switches once approved with both names written,
+ *   and drops the old name at the contract gate.
+ * - A column type change across kinds: the same, with the columns swapped by
+ *   name at the switch and the old one kept unwritten until the contract.
+ * - A failure: a value the new type cannot hold fails the backfill, and
+ *   onFailure drops what the expand added.
+ * - An interrupted backfill: stopped after three batches, then killed before
+ *   a batch's commit, then resumed: the receipts skip what was filled, and
+ *   no row is updated twice.
+ *
+ * Runs the Op through core's local executor with an in-memory gate ledger.
+ * Needs Docker; skips cleanly without it.
+ */
+
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { normalizeApply } from "@intentius/chant/apply";
+import { OpRunFailure, type GateLedgerPort, type OpRunResult } from "@intentius/chant/op";
+import { dockerAvailable, startTestPostgres, type TestPostgres } from "../testing/server";
+import type { PostgresClient } from "../live/client";
+import { planPgAgainstServer } from "../plan/commands";
+import { postgresApply } from "../../op/activities/postgres-apply";
+import { toApplyResult } from "../../op/activities";
+import * as migrationActivities from "../../op/activities/postgres-migration";
+import type { PostgresMigrationDeps } from "../../op/activities/postgres-migration";
+import type { PostgresMigrationArgs, PostgresMigrationOpConfig } from "./op";
+import { ApprovingLedger, runMigrationOp, runOutcome } from "../testing/migration";
+import { POSTGRES_RECEIPTS_TABLE } from "./receipts";
+
+const enabled = await dockerAvailable();
+let server: TestPostgres | undefined;
+let admin: PostgresClient | undefined;
+const dir = mkdtempSync(join(tmpdir(), "chant-pg-migrate-"));
+
+beforeAll(async () => {
+  if (!enabled) return;
+  server = await startTestPostgres();
+  admin = await server.connect();
+}, 600_000);
+
+afterAll(async () => {
+  await admin?.end();
+  await server?.stop();
+  rmSync(dir, { recursive: true, force: true });
+});
+
+interface Obj {
+  export: string;
+  type: string;
+  ddl: string;
+  dependsOn?: string[];
+}
+
+function writeBuild(file: string, objects: Obj[]): string {
+  writeFileSync(join(dir, file), JSON.stringify({ dialect: "postgres", postgresMajor: 18, applyOrder: objects.map((o) => o.export), objects: objects.map((o) => ({ dependsOn: [], ...o })) }));
+  return file;
+}
+
+const MARKER = { stack: "e2e", env: "test" };
+const profile = () => ({
+  config: {
+    ownership: MARKER,
+    sql: { profiles: { e2e: { url: server!.endpoint().url, password: { env: "PG_E2E_PASSWORD" } } } },
+  },
+  env: { PG_E2E_PASSWORD: server!.endpoint().password },
+});
+const deps = (extra: Partial<PostgresMigrationDeps> = {}): PostgresMigrationDeps => ({ ...profile(), log: () => undefined, ...extra });
+const apply = (file: string) => postgresApply({ buildPath: join(dir, file), environment: "e2e" }, undefined, { ...profile(), log: () => undefined });
+const plan = (file: string) => planPgAgainstServer("e2e", join(dir, file), profile());
+const one = async <T>(sql: string): Promise<T> => (await admin!.query<T>(sql))[0]!;
+const columnsOf = async (table: string) =>
+  (await admin!.query<{ name: string }>(`SELECT attname AS name FROM pg_attribute WHERE attrelid = '${table}'::regclass AND attnum > 0 AND NOT attisdropped ORDER BY attnum`)).map((r) => r.name);
+const receiptsTableExists = async (schema: string) => (await one<{ t: string | null }>(`SELECT to_regclass('${schema}.${POSTGRES_RECEIPTS_TABLE}')::text AS t`)).t !== null;
+
+const runOp = (config: PostgresMigrationOpConfig, gates: GateLedgerPort): Promise<OpRunResult> => runMigrationOp(config, gates, () => deps());
+const Ledger = ApprovingLedger;
+const outcome = runOutcome;
+const failed = async (p: Promise<unknown>): Promise<OpRunFailure> => {
+  const e = await p.then(
+    () => undefined,
+    (err: unknown) => err,
+  );
+  expect(e).toBeInstanceOf(OpRunFailure);
+  return e as OpRunFailure;
+};
+
+// Each scenario has a schema of its own, so its plans read only its own table.
+const schemaObj = (name: string): Obj => ({ export: name, type: "Postgres::Schema", ddl: `CREATE SCHEMA ${name}` });
+const APP = schemaObj("app");
+const SHOP = schemaObj("shop");
+const REF = schemaObj("ref");
+const EV = schemaObj("ev");
+
+describe.skipIf(!enabled)("a column rename, migrated through its gates", () => {
+  const usersDdl = (column: string) => `CREATE TABLE app.users (
+  id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+  ${column}
+  name text
+);
+COMMENT ON TABLE app.users IS 'One row per account'`;
+  const V1: Obj = { export: "users", type: "Postgres::Table", dependsOn: ["app"], ddl: usersDdl("email text NOT NULL,") };
+  const V2: Obj = { ...V1, ddl: usersDdl("login text NOT NULL, -- previously: email") };
+  const config = (): PostgresMigrationOpConfig => ({
+    name: "migrate-users-login",
+    env: "e2e",
+    table: "app.users",
+    column: "login",
+    build: false,
+    path: dir,
+    output: "users-v2.json",
+    retain: "0s",
+    batchSize: 1000,
+    stack: MARKER.stack,
+    ownershipEnv: MARKER.env,
+  });
+  const ledger = new Ledger();
+
+  test("the plan and the applier refuse the rename in place and name the Op", async () => {
+    const applied = normalizeApply(toApplyResult(await apply(writeBuild("users-v1.json", [APP, V1]))));
+    expect(applied.notAttempted).toEqual([]);
+    await admin!.query("INSERT INTO app.users (email, name) SELECT 'u' || g || '@example.com', 'n' || g FROM generate_series(1, 2500) g");
+
+    writeBuild("users-v2.json", [APP, V2]);
+    const p = await plan("users-v2.json");
+    expect(p.refused.map((c) => c.rule)).toEqual(["SQLPG205"]);
+    expect(p.migrationOps).toEqual([expect.objectContaining({ table: "app.users", column: "login", env: "e2e", rule: "SQLPG205" })]);
+    expect(p.migrationOps![0]!.declaration).toBe('export const { op } = PostgresMigrationOp({ name: "migrate-app-users-login", env: "e2e", table: "app.users", column: "login" });');
+
+    const refused = normalizeApply(toApplyResult(await apply("users-v2.json")));
+    expect(refused.notAttempted).toEqual([expect.objectContaining({ name: "app.users", reason: "unsupported-kind" })]);
+    expect(refused.notAttempted[0]!.detail).toContain('PostgresMigrationOp({ table: "app.users", column: "login", ... })');
+  }, 180_000);
+
+  test("the first run fills the new column and stops at the switch gate with the verification attached", async () => {
+    const r = await runOp(config(), ledger.port);
+    expect(r.status).toBe("gated");
+    expect(r.gate).toMatchObject({ gate: "approve-migrate-users-login" });
+    expect(r.gate!.planDigest).toMatch(/^jcs1-sha256:/);
+    expect(outcome(r, "MigrationState")).toBe("migrate");
+    expect(outcome(r, "Change")).toBe("rename");
+    expect(outcome(r, "Filled")).toBe(3);
+    expect(outcome(r, "BackfilledRows")).toBe(2500);
+    expect(outcome(r, "VerifiedRows")).toBe(2500);
+    expect(String(outcome(r, "Verification"))).toMatch(/2500 row\(s\), login equal to email in every one/);
+    expect(await one("SELECT count(*)::int AS n FROM app.users WHERE login IS DISTINCT FROM email")).toEqual({ n: 0 });
+    // Nothing visible to a plan: the working column is left out, and the rename is still what is refused.
+    expect((await plan("users-v2.json")).changes.map((c) => c.rule)).toEqual(["SQLPG205"]);
+
+    // Writers on the old name go on working, and the trigger fills the new one.
+    await admin!.query("INSERT INTO app.users (email) VALUES ('late@example.com')");
+    expect(await one("SELECT login FROM app.users WHERE email = 'late@example.com'")).toEqual({ login: "late@example.com" });
+    await admin!.query("UPDATE app.users SET email = 'first@example.com' WHERE id = 1");
+    expect(await one("SELECT login FROM app.users WHERE id = 1")).toEqual({ login: "first@example.com" });
+
+    // Running again before anyone approves fills nothing again: the three
+    // batches are skipped by their receipts, and the gate stands as it was.
+    const again = await runOp(config(), ledger.port);
+    expect(again.status).toBe("gated");
+    expect(outcome(again, "Skipped")).toBe(3);
+    expect(outcome(again, "Filled")).toBe(0);
+    expect(again.gate!.planDigest).toBe(r.gate!.planDigest);
+  }, 300_000);
+
+  test("approved, it switches: the new name is the declared column, both names are written, and it stops at the contract gate", async () => {
+    ledger.approveLast();
+    const r = await runOp(config(), ledger.port);
+    expect(r.status).toBe("gated");
+    expect(r.gate).toMatchObject({ gate: "approve-migrate-users-login-contract" });
+    expect(outcome(r, "OldColumn")).toBe("email");
+    expect(await one("SELECT attnotnull FROM pg_attribute WHERE attrelid = 'app.users'::regclass AND attname = 'login'")).toEqual({ attnotnull: true });
+    expect(await one("SELECT count(*)::int AS n FROM pg_constraint WHERE conrelid = 'app.users'::regclass AND contype = 'c'")).toEqual({ n: 0 });
+    // The plan sees the declaration: login, and email is left out until the contract drops it.
+    expect((await plan("users-v2.json")).changes).toEqual([]);
+
+    // A reader or writer still on the old name works until the contract; a new writer fills both.
+    await admin!.query("INSERT INTO app.users (login) VALUES ('new@example.com')");
+    expect(await one("SELECT email FROM app.users WHERE login = 'new@example.com'")).toEqual({ email: "new@example.com" });
+    await admin!.query("INSERT INTO app.users (email) VALUES ('old@example.com')");
+    expect(await one("SELECT login FROM app.users WHERE email = 'old@example.com'")).toEqual({ login: "old@example.com" });
+  }, 300_000);
+
+  test("approved again, it drops the old name, its trigger and its receipts, and the server holds the declaration", async () => {
+    ledger.approveLast();
+    const r = await runOp(config(), ledger.port);
+    expect(r.status).toBe("ok");
+    expect(outcome(r, "Dropped")).toBe(true);
+    expect(await columnsOf("app.users")).toEqual(["id", "name", "login"]);
+    expect(await one("SELECT count(*)::int AS n FROM pg_trigger WHERE tgrelid = 'app.users'::regclass AND NOT tgisinternal")).toEqual({ n: 0 });
+    expect(await receiptsTableExists("app")).toBe(false);
+    expect((await plan("users-v2.json")).changes).toEqual([]);
+    expect(await one("SELECT count(*)::int AS n FROM app.users")).toEqual({ n: 2503 });
+
+    const done = await runOp(config(), ledger.port);
+    expect(done.status).toBe("ok");
+    expect(outcome(done, "MigrationState")).toBe("done");
+  }, 300_000);
+});
+
+describe.skipIf(!enabled)("a column type change across kinds, migrated through its gates", () => {
+  const ordersDdl = (amount: string) => `CREATE TABLE shop.orders (id bigint PRIMARY KEY, ${amount}, note text)`;
+  const V1: Obj = { export: "orders", type: "Postgres::Table", dependsOn: ["shop"], ddl: ordersDdl("amount text NOT NULL") };
+  const V2: Obj = { ...V1, ddl: `${ordersDdl("amount numeric(12,2) NOT NULL DEFAULT 0")};\nCOMMENT ON COLUMN shop.orders.amount IS 'In euros'` };
+  const config = (): PostgresMigrationOpConfig => ({
+    name: "migrate-orders-amount",
+    env: "e2e",
+    table: "shop.orders",
+    column: "amount",
+    build: false,
+    path: dir,
+    output: "orders-v2.json",
+    retain: "0s",
+    batchSize: 500,
+    stack: MARKER.stack,
+    ownershipEnv: MARKER.env,
+  });
+  const ledger = new Ledger();
+
+  test("refused in place, then filled, switched by name and contracted", async () => {
+    await apply(writeBuild("orders-v1.json", [SHOP, V1]));
+    await admin!.query("INSERT INTO shop.orders (id, amount) SELECT g, (g % 100) || '.25' FROM generate_series(1, 1200) g");
+    writeBuild("orders-v2.json", [SHOP, V2]);
+    const p = await plan("orders-v2.json");
+    expect(p.refused.map((c) => [c.rule, c.field])).toEqual([["SQLPG208", "columns.amount.type"]]);
+    expect(p.migrationOps?.map((o) => [o.table, o.column])).toEqual([["shop.orders", "amount"]]);
+
+    const first = await runOp(config(), ledger.port);
+    expect(first.status).toBe("gated");
+    expect(outcome(first, "Change")).toBe("type");
+    expect(outcome(first, "Filled")).toBe(3);
+    expect(outcome(first, "VerifiedRows")).toBe(1200);
+    expect(await one("SELECT format_type(atttypid, atttypmod) AS t FROM pg_attribute WHERE attrelid = 'shop.orders'::regclass AND attname = 'amount__chant_new'")).toEqual({ t: "numeric(12,2)" });
+    // A write during the migration is converted by the trigger.
+    await admin!.query("INSERT INTO shop.orders (id, amount) VALUES (5000, '7.5')");
+    expect(await one("SELECT amount__chant_new::text AS v FROM shop.orders WHERE id = 5000")).toEqual({ v: "7.50" });
+
+    ledger.approveLast();
+    const switched = await runOp(config(), ledger.port);
+    expect(switched.status).toBe("gated");
+    expect(switched.gate).toMatchObject({ gate: "approve-migrate-orders-amount-contract" });
+    expect(outcome(switched, "OldColumn")).toBe("amount__chant_old");
+    expect(await one("SELECT format_type(atttypid, atttypmod) AS t, attnotnull AS nn FROM pg_attribute WHERE attrelid = 'shop.orders'::regclass AND attname = 'amount'")).toEqual({
+      t: "numeric(12,2)",
+      nn: true,
+    });
+    expect(await one("SELECT col_description('shop.orders'::regclass, (SELECT attnum FROM pg_attribute WHERE attrelid = 'shop.orders'::regclass AND attname = 'amount')) AS c")).toEqual({ c: "In euros" });
+    expect(await one("SELECT sum(amount)::text AS s FROM shop.orders")).toEqual({ s: "59707.50" });
+    expect((await plan("orders-v2.json")).changes).toEqual([]);
+    // Writers now write the new type; the old column is kept as it was and no longer written.
+    await admin!.query("INSERT INTO shop.orders (id, amount) VALUES (5001, 3.333)");
+    expect(await one("SELECT amount::text AS v, amount__chant_old AS old FROM shop.orders WHERE id = 5001")).toEqual({ v: "3.33", old: null });
+    await admin!.query("INSERT INTO shop.orders (id) VALUES (5002)");
+    expect(await one("SELECT amount::text AS v FROM shop.orders WHERE id = 5002")).toEqual({ v: "0.00" });
+
+    ledger.approveLast();
+    const contracted = await runOp(config(), ledger.port);
+    expect(contracted.status).toBe("ok");
+    expect(await columnsOf("shop.orders")).toEqual(["id", "note", "amount"]);
+    expect((await plan("orders-v2.json")).changes).toEqual([]);
+  }, 300_000);
+});
+
+describe.skipIf(!enabled)("a failure runs onFailure, which drops what the expand added", () => {
+  const V1: Obj = { export: "codes", type: "Postgres::Table", dependsOn: ["ref"], ddl: "CREATE TABLE ref.codes (id integer PRIMARY KEY, code text)" };
+  const V2: Obj = { ...V1, ddl: "CREATE TABLE ref.codes (id integer PRIMARY KEY, code integer)" };
+
+  test("a value the new type cannot hold fails the backfill; the new column, trigger, function and receipts are dropped", async () => {
+    await apply(writeBuild("codes-v1.json", [REF, V1]));
+    await admin!.query("INSERT INTO ref.codes SELECT g, g::text FROM generate_series(1, 300) g");
+    await admin!.query("UPDATE ref.codes SET code = 'n/a' WHERE id = 250");
+    writeBuild("codes-v2.json", [REF, V2]);
+
+    const failure = await failed(
+      runOp({ name: "migrate-codes", env: "e2e", table: "ref.codes", column: "code", build: false, path: dir, output: "codes-v2.json", batchSize: 100, stack: MARKER.stack, ownershipEnv: MARKER.env }, new Ledger().port),
+    );
+    const records = failure.result.records;
+    expect(records.find((x) => x.fn === "postgresMigrationBackfill")?.error).toMatch(/invalid input syntax for type integer: "n\/a"/);
+    expect(records.find((x) => x.fn === "postgresMigrationCompensate")?.status).toBe("ok");
+    expect(await columnsOf("ref.codes")).toEqual(["id", "code"]);
+    expect(await one("SELECT count(*)::int AS n FROM pg_trigger WHERE tgrelid = 'ref.codes'::regclass AND NOT tgisinternal")).toEqual({ n: 0 });
+    expect(await one("SELECT count(*)::int AS n FROM pg_proc WHERE proname = 'codes__code__chant_sync'")).toEqual({ n: 0 });
+    expect(await receiptsTableExists("ref")).toBe(false);
+    expect((await plan("codes-v2.json")).changes.map((c) => c.rule)).toEqual(["SQLPG208"]);
+  }, 300_000);
+});
+
+describe.skipIf(!enabled)("an interrupted backfill resumes from its receipts", () => {
+  const V1: Obj = { export: "events", type: "Postgres::Table", dependsOn: ["ev"], ddl: "CREATE TABLE ev.events (id bigint PRIMARY KEY, kind varchar(20) NOT NULL)" };
+  const V2: Obj = { ...V1, ddl: "CREATE TABLE ev.events (id bigint PRIMARY KEY, kind varchar(10) NOT NULL)" };
+  const args = (): PostgresMigrationArgs => ({ table: "ev.events", column: "kind", buildPath: "events-v2.json", environment: "e2e", batchSize: 1000, stack: MARKER.stack, ownershipEnv: MARKER.env, cwd: dir });
+  const m = migrationActivities;
+
+  test("stopped after three batches, killed before a commit, then resumed: every row updated once", async () => {
+    await apply(writeBuild("events-v1.json", [EV, V1]));
+    await admin!.query("INSERT INTO ev.events SELECT g, CASE WHEN g % 2 = 0 THEN 'click' ELSE 'view' END FROM generate_series(0, 5999) g");
+    // Every row update the backfill makes, counted by a trigger of the application's own.
+    await admin!.query("CREATE SCHEMA audit");
+    await admin!.query("CREATE TABLE audit.updates (id bigint)");
+    await admin!.query("CREATE FUNCTION audit.count_update() RETURNS trigger LANGUAGE plpgsql AS $$ BEGIN INSERT INTO audit.updates VALUES (NEW.id); RETURN NEW; END $$");
+    await admin!.query("CREATE TRIGGER audit_update AFTER UPDATE ON ev.events FOR EACH ROW EXECUTE FUNCTION audit.count_update()");
+    writeBuild("events-v2.json", [EV, V2]);
+
+    // varchar(20) to varchar(10) is a rewrite in place (SQLPG207), which the Op makes in batches instead.
+    expect((await plan("events-v2.json")).changes.map((c) => c.rule)).toEqual(["SQLPG207"]);
+    expect(await m.postgresMigrationPlan(args(), undefined, deps())).toMatchObject({ state: "migrate", change: "type" });
+    await m.postgresMigrationExpand(args(), undefined, deps());
+    await m.postgresMigrationDualWrite(args(), undefined, deps());
+
+    // Interrupted (Ctrl-C) after the third batch.
+    const stop = new AbortController();
+    let done = 0;
+    const interrupted = await m
+      .postgresMigrationBackfill(args(), stop.signal, deps({ backfill: { afterBatch: () => void (++done === 3 && stop.abort()) } }))
+      .then(
+        () => undefined,
+        (e: unknown) => e,
+      );
+    expect(interrupted).toBeDefined();
+    expect(await one("SELECT count(*)::int AS n FROM ev.events WHERE kind__chant_new IS NOT NULL")).toEqual({ n: 3000 });
+
+    // Killed after the fourth batch's UPDATE and receipt, before its commit: neither is kept.
+    await expect(
+      m.postgresMigrationBackfill(
+        args(),
+        undefined,
+        deps({
+          backfill: {
+            beforeCommit: () => {
+              throw new Error("killed before the commit");
+            },
+          },
+        }),
+      ),
+    ).rejects.toThrow(/killed before the commit/);
+    expect(await one("SELECT count(*)::int AS n FROM ev.events WHERE kind__chant_new IS NOT NULL")).toEqual({ n: 3000 });
+    expect(await one(`SELECT count(*)::int AS n FROM ev.${POSTGRES_RECEIPTS_TABLE}`)).toEqual({ n: 3 });
+
+    // Resumed: three batches skipped by receipt, three filled.
+    const resumed = await m.postgresMigrationBackfill(args(), undefined, deps());
+    expect(resumed).toMatchObject({ batches: 6, skipped: 3, filled: 3, rows: 3000 });
+    expect(await one("SELECT count(*)::int AS rows, count(DISTINCT id)::int AS ids, max(n)::int AS most FROM (SELECT id, count(*) AS n FROM audit.updates GROUP BY id) s")).toEqual({
+      rows: 6000,
+      ids: 6000,
+      most: 1,
+    });
+    expect(await one(`SELECT count(*)::int AS n FROM ev.${POSTGRES_RECEIPTS_TABLE} WHERE address LIKE 'e2e/test/migrate/ev.events.kind/%'`)).toEqual({ n: 6 });
+    expect(await m.postgresMigrationVerify(args(), undefined, deps())).toMatchObject({ rows: 6000, mismatched: 0 });
+
+    // The receipts table is chant's own bookkeeping, not a declared schema.
+    expect((await plan("events-v2.json")).changes.map((c) => c.object)).not.toContain(`relation ev.${POSTGRES_RECEIPTS_TABLE}`);
+
+    const dropped = await m.postgresMigrationCompensate(args(), undefined, deps());
+    expect(dropped.dropped).toEqual(["trigger kind__chant_sync", "function ev.events__kind__chant_sync", "column ev.events.kind__chant_new", "6 receipt(s)"]);
+    expect(await receiptsTableExists("ev")).toBe(false);
+  }, 300_000);
+});