@intentius/chant-lexicon-sql 0.112.1 → 0.113.0

package/src/op/watch-drift.e2e.test.ts

@@ -0,0 +1,302 @@
+/**
+ * A scheduled drift check over a sql environment, run end to end (#3642).
+ *
+ * For each dialect, a project in a temporary directory declares a schema, an
+ * `ApplyOp` that creates it as an admin, and a `WatchOp` with a `schedule`
+ * over a second environment whose profile reads the server as a user that can
+ * only read. `chant run` runs the watch, as the job `generateOpsPipeline`
+ * renders does (`watch-pipeline.test.ts`), and its `Drift` outcome is read off
+ * the run:
+ *
+ * - false on the schema as applied;
+ * - false after a table the project does not own is created beside it;
+ * - true after an owned object's property is changed out of band;
+ * - true after an owned object is dropped.
+ *
+ * Everything is written to the database (ClickHouse) or schema (Postgres)
+ * `yodel_3642`, and a reader user named after it.
+ *
+ * The servers: `CHANT_SQL_WATCH_CLICKHOUSE_URL` and
+ * `CHANT_SQL_WATCH_POSTGRES_URL` (a `postgres://user@host:port/db` URL, with
+ * `CHANT_SQL_WATCH_POSTGRES_PASSWORD`) name running ones, such as the servers
+ * `chant emulator up --lexicon sql` starts. Without them, each dialect starts
+ * a throwaway server at the same pin, and skips cleanly when Docker is not
+ * available.
+ */
+
+import { execFile } from "node:child_process";
+import { mkdirSync, mkdtempSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { dockerAvailable, startScratchServer, type ScratchServer } from "../clickhouse/container";
+import { clickhouseQuery, type ClickHouseEndpoint } from "../clickhouse/http";
+import { clickhouseImage } from "../spec/pin";
+import { startTestPostgres, type TestPostgres } from "../postgres/testing/server";
+import { connectPostgres, type PostgresClient, type PostgresEndpoint } from "../postgres/live/client";
+
+const exec = promisify(execFile);
+
+const REPO = join(import.meta.dirname, "../../../..");
+const BIN = join(REPO, "node_modules/.bin");
+const NAME = "yodel_3642";
+const READER = `${NAME}_reader`;
+const READER_PASSWORD = "reader-3642";
+
+const givenClickHouse = process.env.CHANT_SQL_WATCH_CLICKHOUSE_URL;
+const givenPostgres = process.env.CHANT_SQL_WATCH_POSTGRES_URL;
+const docker = givenClickHouse && givenPostgres ? false : await dockerAvailable();
+
+interface Watch {
+  drift: boolean;
+  output: string;
+}
+
+/**
+ * A project directory chant can run in: the repository's `node_modules`
+ * linked in, so `@intentius/chant` and the sql lexicon resolve, and a git
+ * repository, which the watch's snapshot is written to.
+ */
+async function project(files: Record<string, string>): Promise<{ dir: string; run(op: string, env?: Record<string, string>): Promise<Watch> }> {
+  const dir = mkdtempSync(join(tmpdir(), "chant-sql-watch-"));
+  symlinkSync(join(REPO, "node_modules"), join(dir, "node_modules"), "dir");
+  const all: Record<string, string> = {
+    "package.json": JSON.stringify({ name: "sql-watch-e2e", private: true, type: "module", scripts: { build: "chant build src --lexicon sql -o dist/schema.json" } }),
+    ".gitignore": "node_modules\ndist\n.chant\n",
+    ...files,
+  };
+  for (const [path, text] of Object.entries(all)) {
+    mkdirSync(join(dir, path, ".."), { recursive: true });
+    writeFileSync(join(dir, path), text);
+  }
+  const git = (...args: string[]) => exec("git", ["-c", "user.email=e2e@chant.invalid", "-c", "user.name=e2e", ...args], { cwd: dir });
+  await git("init", "-q");
+  await git("add", "-A");
+  await git("commit", "-qm", "the schema");
+  return {
+    dir,
+    async run(op, env = {}) {
+      const result = await exec(join(BIN, "chant"), ["run", op], {
+        cwd: dir,
+        env: { ...process.env, ...env, PATH: `${BIN}:${process.env.PATH ?? ""}` },
+        maxBuffer: 16 * 1024 * 1024,
+      }).catch((err: { stdout?: string; stderr?: string; message: string }) => {
+        throw new Error(`chant run ${op} failed: ${err.message}\n${err.stdout ?? ""}${err.stderr ?? ""}`);
+      });
+      const output = `${result.stdout}${result.stderr}`.replace(/\u001b\[[0-9;]*m/g, "");
+      const outcome = /\[outcome\] Drift=(true|false)/.exec(output);
+      if (op === "schema-watch" && !outcome) throw new Error(`chant run ${op} reported no Drift outcome:\n${output}`);
+      return { drift: outcome?.[1] === "true", output };
+    },
+  };
+}
+
+const OPS = (target: string) => ({
+  "ops/apply.op.ts": `import { ApplyOp } from "@intentius/chant/op";
+const { op } = ApplyOp({ name: "schema-apply", env: "admin", target: "${target}" });
+export default op;
+`,
+  "ops/watch.op.ts": `import { WatchOp } from "@intentius/chant/op";
+const { op } = WatchOp({ name: "schema-watch", env: "watch", schedule: "17 * * * *" });
+export default op;
+`,
+});
+
+const config = (sql: Record<string, unknown>) => `import type { ChantConfig } from "@intentius/chant";
+import "@intentius/chant-lexicon-sql";
+
+export default {
+  lexicons: ["sql"],
+  ownership: { stack: "yodel-3642", env: "watch" },
+  sql: ${JSON.stringify(sql, null, 2)},
+} satisfies ChantConfig;
+`;
+
+const READER_ENV = { WATCH_USER: READER, WATCH_PASSWORD: READER_PASSWORD };
+
+// ── ClickHouse ──────────────────────────────────────────────────────────────
+
+describe.skipIf(!givenClickHouse && !docker)("a scheduled WatchOp over a ClickHouse environment (#3642)", () => {
+  let server: ScratchServer | undefined;
+  let admin: ClickHouseEndpoint;
+  let p: Awaited<ReturnType<typeof project>>;
+  const q = (sql: string) => clickhouseQuery(admin, sql);
+  const cleanup = async () => {
+    await q(`DROP DATABASE IF EXISTS ${NAME} SYNC`);
+    await q(`DROP USER IF EXISTS ${READER}`);
+  };
+
+  beforeAll(async () => {
+    if (givenClickHouse) admin = { url: givenClickHouse };
+    else {
+      server = await startScratchServer(clickhouseImage(), { namePrefix: "chant-sql-watch" });
+      admin = server.endpoint;
+    }
+    await cleanup();
+    p = await project({
+      ...OPS("clickhouse"),
+      "chant.config.ts": config({
+        dialect: "clickhouse",
+        profiles: {
+          admin: { url: admin.url, databases: [NAME] },
+          watch: { url: admin.url, user: { env: "WATCH_USER" }, password: { env: "WATCH_PASSWORD" }, databases: [NAME] },
+        },
+      }),
+      "src/schema.ts": `import { database, table, view } from "@intentius/chant-lexicon-sql/clickhouse";
+
+export const db = database\`CREATE DATABASE ${NAME} ENGINE = Atomic COMMENT 'drift watch'\`;
+
+export const events = table\`
+  CREATE TABLE \${db}.events (
+    user_id UInt64,
+    kind    LowCardinality(String),
+    ts      DateTime
+  )
+  ENGINE = MergeTree
+  ORDER BY (user_id, ts)
+  TTL ts + INTERVAL 180 DAY
+  COMMENT 'Raw events'\`;
+
+export const byKind = view\`
+  CREATE VIEW \${db}.by_kind AS
+  SELECT \${events.columns.kind} AS kind, count() AS n FROM \${events} GROUP BY kind\`;
+`,
+    });
+    const applied = await p.run("schema-apply");
+    expect(applied.output).toMatch(/Op "schema-apply" completed/);
+    // A reader: SELECT on the database and nothing else, and readonly besides.
+    await q(`CREATE USER ${READER} IDENTIFIED WITH sha256_password BY '${READER_PASSWORD}' SETTINGS readonly = 1`);
+    await q(`GRANT SELECT ON ${NAME}.* TO ${READER}`);
+  }, 600_000);
+
+  afterAll(async () => {
+    if (admin) await cleanup().catch(() => undefined);
+    await server?.stop();
+    if (p) rmSync(p.dir, { recursive: true, force: true });
+  });
+
+  test("reports no drift on the schema as applied", async () => {
+    const watch = await p.run("schema-watch", READER_ENV);
+    expect(watch.output).toContain("No drift detected");
+    expect(watch.drift).toBe(false);
+  }, 120_000);
+
+  test("reports nothing for a table the project does not own", async () => {
+    await q(`CREATE TABLE ${NAME}.made_by_hand (id UInt64) ENGINE = MergeTree ORDER BY id COMMENT 'not chant'`);
+    const watch = await p.run("schema-watch", READER_ENV);
+    expect(watch.output).not.toContain("made_by_hand");
+    expect(watch.drift).toBe(false);
+  }, 120_000);
+
+  test("reports drift when an owned table's TTL is changed out of band", async () => {
+    await q(`ALTER TABLE ${NAME}.events MODIFY TTL ts + INTERVAL 30 DAY`);
+    const watch = await p.run("schema-watch", READER_ENV);
+    expect(watch.output).toContain("PROPERTY DRIFT");
+    expect(watch.output).toMatch(/- events \(ClickHouse::Table\)\n\s+ttl: ts \+ INTERVAL 180 DAY → ts \+ toIntervalDay\(30\)/);
+    expect(watch.drift).toBe(true);
+    await q(`ALTER TABLE ${NAME}.events MODIFY TTL ts + INTERVAL 180 DAY`);
+  }, 120_000);
+
+  test("reports drift when an owned view is dropped", async () => {
+    await q(`DROP VIEW ${NAME}.by_kind`);
+    const watch = await p.run("schema-watch", READER_ENV);
+    expect(watch.output).toMatch(/MISSING \(declared, provider reports not in cloud\):\n\s+- byKind /);
+    expect(watch.drift).toBe(true);
+  }, 120_000);
+});
+
+// ── Postgres ────────────────────────────────────────────────────────────────
+
+describe.skipIf(!givenPostgres && !docker)("a scheduled WatchOp over a Postgres environment (#3642)", () => {
+  let server: TestPostgres | undefined;
+  let endpoint: PostgresEndpoint;
+  let admin: PostgresClient;
+  let p: Awaited<ReturnType<typeof project>>;
+  const q = (sql: string) => admin.query(sql);
+  const cleanup = async () => {
+    await q(`DROP SCHEMA IF EXISTS ${NAME} CASCADE`);
+    await q(`DROP ROLE IF EXISTS ${READER}`);
+  };
+
+  beforeAll(async () => {
+    if (givenPostgres) endpoint = { url: givenPostgres, password: process.env.CHANT_SQL_WATCH_POSTGRES_PASSWORD };
+    else {
+      server = await startTestPostgres();
+      endpoint = server.endpoint();
+    }
+    admin = await connectPostgres(endpoint);
+    await cleanup();
+    const readerUrl = new URL(endpoint.url);
+    readerUrl.username = READER;
+    p = await project({
+      ...OPS("postgres"),
+      "chant.config.ts": config({
+        dialect: "postgres",
+        profiles: {
+          admin: { url: endpoint.url, password: { env: "ADMIN_PASSWORD" }, schemas: [NAME] },
+          watch: { url: readerUrl.toString(), password: { env: "WATCH_PASSWORD" }, schemas: [NAME] },
+        },
+      }),
+      "src/schema.ts": `import { schema, table, index } from "@intentius/chant-lexicon-sql/postgres";
+
+export const app = schema\`CREATE SCHEMA ${NAME};
+COMMENT ON SCHEMA ${NAME} IS 'drift watch'\`;
+
+export const orders = table\`
+  CREATE TABLE \${app}.orders (
+    id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+    status text NOT NULL DEFAULT 'new',
+    amount numeric(12, 2) NOT NULL
+  );
+  COMMENT ON TABLE \${app}.orders IS 'One row per order'\`;
+
+export const ordersStatus = index\`CREATE INDEX orders_status_idx ON \${orders} (\${orders.columns.status})\`;
+`,
+    });
+    const applied = await p.run("schema-apply", { ADMIN_PASSWORD: endpoint.password ?? "" });
+    expect(applied.output).toMatch(/Op "schema-apply" completed/);
+    // A reader: it may log in and look in the schema, and every transaction it opens is read-only.
+    await q(`CREATE ROLE ${READER} LOGIN PASSWORD '${READER_PASSWORD}'`);
+    await q(`ALTER ROLE ${READER} SET default_transaction_read_only = on`);
+    await q(`GRANT USAGE ON SCHEMA ${NAME} TO ${READER}`);
+  }, 600_000);
+
+  afterAll(async () => {
+    if (admin) {
+      await cleanup().catch(() => undefined);
+      await admin.end();
+    }
+    await server?.stop();
+    if (p) rmSync(p.dir, { recursive: true, force: true });
+  });
+
+  test("reports no drift on the schema as applied", async () => {
+    const watch = await p.run("schema-watch", READER_ENV);
+    expect(watch.output).toContain("No drift detected");
+    expect(watch.drift).toBe(false);
+  }, 120_000);
+
+  test("reports nothing for a table the project does not own", async () => {
+    await q(`CREATE TABLE ${NAME}.made_by_hand (id int)`);
+    const watch = await p.run("schema-watch", READER_ENV);
+    expect(watch.output).not.toContain("made_by_hand");
+    expect(watch.drift).toBe(false);
+  }, 120_000);
+
+  test("reports drift when an owned column's default is changed out of band", async () => {
+    await q(`ALTER TABLE ${NAME}.orders ALTER COLUMN status SET DEFAULT 'pending'`);
+    const watch = await p.run("schema-watch", READER_ENV);
+    expect(watch.output).toContain("PROPERTY DRIFT");
+    expect(watch.output).toMatch(/- orders \(Postgres::Table\)\n\s+columns\[1\]\.default: 'new' → 'pending'::text/);
+    expect(watch.drift).toBe(true);
+    await q(`ALTER TABLE ${NAME}.orders ALTER COLUMN status SET DEFAULT 'new'`);
+  }, 120_000);
+
+  test("reports drift when an owned index is dropped", async () => {
+    await q(`DROP INDEX ${NAME}.orders_status_idx`);
+    const watch = await p.run("schema-watch", READER_ENV);
+    expect(watch.output).toMatch(/MISSING \(declared, provider reports not in cloud\):\n\s+- ordersStatus /);
+    expect(watch.drift).toBe(true);
+  }, 120_000);
+});

package/src/op/watch-pipeline.test.ts

@@ -0,0 +1,113 @@
+/**
+ * The scheduled drift check for a sql environment, rendered to CI (#3642).
+ *
+ * `examples/drift-watch` declares a `WatchOp` with a `schedule` over its
+ * `prod` environment, whose `sql.profiles.prod` reads the server as a reader
+ * user. `generateOpsPipeline` renders it for each forge chant targets, through
+ * the real github, gitlab and forgejo plugins and real Op discovery. The job
+ * holds read-only credentials: the reader's user and password and nothing
+ * else, and, where the forge lets a workflow say so, a token that can only
+ * read the repository.
+ *
+ * `watch-drift.e2e.test.ts` runs the same kind of Op against a server.
+ */
+
+import { join } from "node:path";
+import { describe, expect, test } from "vitest";
+import { generateOpsPipeline } from "@intentius/chant/op";
+import { parseYAML } from "@intentius/chant/yaml";
+import type { ScheduledOpSpec } from "@intentius/chant/lexicon";
+
+const EXAMPLE = join(import.meta.dirname, "../../examples/drift-watch");
+
+/** The reader's credentials, as each forge names a secret. */
+const reader = (secret: (name: string) => string): ScheduledOpSpec => ({
+  name: "schema-watch",
+  variables: {
+    CLICKHOUSE_READER_USER: "chant_reader",
+    CLICKHOUSE_READER_PASSWORD: secret("CLICKHOUSE_READER_PASSWORD"),
+  },
+});
+const actionsSecret = (name: string) => `\${{ secrets.${name} }}`;
+const gitlabVariable = (name: string) => `$${name}`;
+
+/**
+ * Install the project, and put its `chant` on the job's PATH: `chant run`
+ * runs `chant lifecycle` itself. A GitHub or Forgejo step is a shell of its
+ * own, so the path goes through `$GITHUB_PATH`; GitLab's script lines share one.
+ */
+const INSTALL = {
+  actions: ["npm ci", 'echo "$PWD/node_modules/.bin" >> "$GITHUB_PATH"'],
+  gitlab: ["npm ci", 'export PATH="$PWD/node_modules/.bin:$PATH"'],
+};
+
+async function render(forge: "github" | "gitlab" | "forgejo", spec: ScheduledOpSpec) {
+  const beforeScript = forge === "gitlab" ? INSTALL.gitlab : INSTALL.actions;
+  const result = await generateOpsPipeline([spec], forge, { beforeScript }, EXAMPLE);
+  expect(result.error).toBeUndefined();
+  expect(result.success).toBe(true);
+  expect(result.files).toHaveLength(1);
+  expect(result.jobs).toEqual([
+    { jobName: "schema-watch", op: "schema-watch", trigger: { kind: "cron", schedule: "17 * * * *" }, findingMode: "report" },
+  ]);
+  const file = result.files![0]!;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- a parsed workflow, read by path
+  return { file, doc: parseYAML(file.yaml) as Record<string, any> };
+}
+
+const runLine = (steps: Array<Record<string, unknown>>) => steps.find((s) => s.run === "chant run schema-watch");
+
+describe("generateOpsPipeline renders the sql drift watch (#3642)", () => {
+  test("GitHub: the Op's own cron, a read-only token and the reader's credentials", async () => {
+    const { file, doc } = await render("github", reader(actionsSecret));
+    expect(file.name).toBe("schema-watch.yml");
+    expect(doc.on.schedule).toEqual([{ cron: "17 * * * *" }]);
+    expect(doc.permissions).toEqual({ contents: "read" });
+    const job = doc.jobs["schema-watch"];
+    expect(job.env).toEqual({
+      CLICKHOUSE_READER_USER: "chant_reader",
+      CLICKHOUSE_READER_PASSWORD: "${{ secrets.CLICKHOUSE_READER_PASSWORD }}",
+    });
+    expect(job.permissions).toBeUndefined();
+    expect(job.steps.map((s: Record<string, unknown>) => s.run).filter(Boolean)).toEqual([...INSTALL.actions, "chant run schema-watch"]);
+    expect(runLine(job.steps)?.env).toEqual({ GITHUB_TOKEN: "${{ github.token }}" });
+    expect(file.yaml).toMatchSnapshot();
+  });
+
+  test("GitLab: a schedule-only job with the reader's credentials and no token of its own", async () => {
+    const { file, doc } = await render("gitlab", reader(gitlabVariable));
+    expect(file.yaml).toContain('#   schema-watch: cron "17 * * * *", CHANT_SCHEDULED_OP="schema-watch", finding-mode report');
+    const job = doc["schema-watch"];
+    expect(job.rules).toEqual([{ if: '$CI_PIPELINE_SOURCE == "schedule" && $CHANT_SCHEDULED_OP == "schema-watch"' }]);
+    expect(job.variables).toEqual({
+      CLICKHOUSE_READER_USER: "chant_reader",
+      CLICKHOUSE_READER_PASSWORD: "$CLICKHOUSE_READER_PASSWORD",
+    });
+    expect(doc.variables).toBeUndefined();
+    expect(job.script).toEqual([...INSTALL.gitlab, "chant run schema-watch"]);
+    expect(file.yaml).toMatchSnapshot();
+  });
+
+  test("Forgejo: the Op's own cron and the reader's credentials; the runner's token takes no permissions block", async () => {
+    const { file, doc } = await render("forgejo", reader(actionsSecret));
+    expect(file.name).toBe("schema-watch.yml");
+    expect(doc.on.schedule).toEqual([{ cron: "17 * * * *" }]);
+    // Forgejo's runner reads no `permissions:`, so the generator writes none.
+    expect(doc.permissions).toBeUndefined();
+    const job = doc.jobs["schema-watch"];
+    expect(job.env).toEqual({
+      CLICKHOUSE_READER_USER: "chant_reader",
+      CLICKHOUSE_READER_PASSWORD: "${{ secrets.CLICKHOUSE_READER_PASSWORD }}",
+    });
+    expect(job.steps.map((s: Record<string, unknown>) => s.run).filter(Boolean)).toEqual([...INSTALL.actions, "chant run schema-watch"]);
+    expect(file.yaml).toMatchSnapshot();
+  });
+
+  test("the example's profile reads the server as the user and password the job holds", async () => {
+    const { default: config } = await import(join(EXAMPLE, "chant.config.ts"));
+    expect(config.sql.profiles.prod).toMatchObject({
+      user: { env: "CLICKHOUSE_READER_USER" },
+      password: { env: "CLICKHOUSE_READER_PASSWORD" },
+    });
+  });
+});

package/src/postgres/apply/apply.ts

@@ -68,7 +68,7 @@
 
 import type { OwnershipMarker } from "@intentius/chant/ownership";
 import type { ApplyRef } from "@intentius/chant/apply";
-import { SqlApplyError, changesByObject, dependencyFailedDetail, missingDependencies, readBuildObjects, type SqlApplyOutcome } from "../../core/apply";
+import { SqlApplyError, dependencyFailedDetail, missingDependencies, readBuildObjects, type SqlApplyOutcome } from "../../core/apply";
 import { carriesMarker, isChantManaged } from "../../core/ownership";
 import { PostgresQueryError, type PostgresClient } from "../live/client";
 import type { PostgresTarget } from "../live/bind";
@@ -83,18 +83,7 @@ import type { PostgresEntityType } from "../entity-types";
 import type { PgChangeClass } from "../plan/rules";
 import type { CanonicalKind } from "../plan/normalize";
 import { quoteIdent } from "../keywords";
-import {
-  alterSteps,
-  commentStatement,
-  createSteps,
-  dropStatement,
-  isDestructive,
-  isRefused,
-  refusalDetail,
-  scansRows,
-  type DeclaredPgObject,
-  type PgStep,
-} from "./statements";
+import { planPgStatements, scansRows, type DeclaredPgObject, type PgDropStatement, type PgStep } from "./statements";
 
 /** The timeouts a statement runs with, in milliseconds; 0 is no limit. */
 export interface PostgresApplyTimeouts {
@@ -195,19 +184,6 @@ export interface PostgresApplyOptions {
   serverNormalize?: typeof serverNormalized;
 }
 
-/** Drop order: what reads from a table before the table, types after the tables using them, a schema last. */
-const DROP_ORDER: Record<CanonicalKind, number> = {
-  materializedView: 0,
-  view: 1,
-  index: 2,
-  table: 3,
-  sequence: 4,
-  domain: 5,
-  enum: 6,
-  extension: 7,
-  schema: 8,
-};
-
 const SQLSTATE_LOCK_NOT_AVAILABLE = "55P03";
 const SQLSTATE_QUERY_CANCELED = "57014";
 const SQLSTATE_DEPENDENT_OBJECTS = "2BP01";
@@ -273,82 +249,52 @@ export async function applyPostgres(
     ...(opts.readLive ? { readLive: opts.readLive } : {}),
     ...(opts.serverNormalize ? { serverNormalize: opts.serverNormalize } : {}),
   });
-  const byObject = changesByObject(plan.diff.changes);
   const normalizedByKey = new Map(plan.declared.map((o) => [o.key, o.canonical]));
-  const liveByKey = new Map(plan.live.map((o) => [o.key, o.canonical]));
   const liveRawByKey = new Map(plan.liveObjects.map((o) => [qualifiedKey(liveCanonicalAddress(o)), o]));
-  const matchedLive = new Map<string, string>();
-  for (const m of matchPgObjects(plan.live, plan.declared)) if (m.kind === "matched") matchedLive.set(m.after.key, m.before.key);
+  const objects = declared.map((original) => ({ ...original, canonical: { ...original.canonical, ...normalizedByKey.get(original.key) } }));
+  const matchedLive = new Set<string>();
+  for (const m of matchPgObjects(plan.live, plan.declared)) if (m.kind === "matched") matchedLive.add(m.after.key);
 
   // An extension's own comment stays under the trailer when the declaration sets none.
-  const extensionComments = await extensionDefaults(client, declared.filter((o) => o.canonical.kind === "extension" && !matchedLive.has(o.key)).map((o) => o.canonical.name));
+  const extensionComments = await extensionDefaults(client, objects.filter((o) => o.canonical.kind === "extension" && !matchedLive.has(o.key)).map((o) => o.canonical.name));
 
   // ── Each object's statements, or its verdict when it has none to send. ──
+  const statements = planPgStatements({
+    declared: objects,
+    changes: plan.diff.changes,
+    current: plan.live,
+    major: plan.major ?? POSTGRES_LATEST_MAJOR,
+    allowDestructive: opts.prune === true,
+    carriesMarker: (_live, key) => carriesMarker(liveRawByKey.get(key)?.comment, opts.marker),
+    extensionComment: (name) => extensionComments.get(name),
+    ...(opts.marker ? { marker: opts.marker } : {}),
+  });
+
   const units: Unit[] = [];
   const onServer = new Set<string>();
   const exportNames = new Set(declared.map((o) => o.exportName));
-  const recreatedRelations = new Set<string>();
-  for (const original of declared) {
-    const obj = { ...original, canonical: { ...original.canonical, ...normalizedByKey.get(original.key) } };
+  for (const entry of statements.objects) {
+    const obj = entry.obj;
     const ref = { kind: obj.type, name: obj.name };
-    const liveKey = matchedLive.get(obj.key);
-    const live = liveKey !== undefined ? liveByKey.get(liveKey) : undefined;
-    const liveRaw = liveKey !== undefined ? liveRawByKey.get(liveKey) : undefined;
-    const mine = byObject.get(obj.key) ?? [];
-
-    if (live?.foreign) {
-      onServer.add(obj.exportName);
-      outcome.notAttempted.push({ ...ref, reason: "filtered", detail: `${live.foreign} keeps ${obj.name}; it is not chant's to change` });
-      continue;
-    }
-    const refused = mine.filter(isRefused);
-    if (refused.length > 0) {
-      if (live) onServer.add(obj.exportName);
-      outcome.notAttempted.push({ ...ref, reason: "unsupported-kind", detail: refusalDetail(refused, obj.name, obj.canonical) });
-      continue;
-    }
-    const destructive = mine.filter(isDestructive);
-    if (destructive.length > 0 && !opts.prune) {
-      onServer.add(obj.exportName);
-      outcome.notAttempted.push({
-        ...ref,
-        reason: "filtered",
-        detail: `drops ${destructive.map((c) => c.field).join(", ")}, which destroys the data in it; an apply that may delete (prune, ApplyOp delete "owned-only" or "gated") makes it`,
-      });
-      continue;
-    }
-
-    // An index on a materialized view this apply recreates went with the view, so it is created again.
-    const onRecreated = obj.canonical.kind === "index" && recreatedRelations.has(String(obj.canonical.fields.table));
-    const created = !live || onRecreated;
-    let steps: PgStep[];
-    if (created) {
-      const base = obj.canonical.kind === "extension" ? extensionComments.get(obj.canonical.name) : undefined;
-      // An index on a table that exists is built under the scan timeout (SQLPG240, SQLPG241); one on a new table is part of the create.
-      const how = mine.find((c) => c.rule === "SQLPG200" || c.rule === "SQLPG240" || c.rule === "SQLPG241");
-      steps = createSteps(obj, opts.marker, { ...(base !== undefined ? { base } : {}), ...(how ? { cls: how.class, rule: how.rule } : {}) });
-    } else {
-      const altered = alterSteps(obj, live, mine, { ...(opts.marker ? { marker: opts.marker } : {}), major: plan.major ?? POSTGRES_LATEST_MAJOR });
-      if (altered.unsupported.length > 0) {
+    const liveRaw = entry.live ? liveRawByKey.get(qualifiedKey(entry.live)) : undefined;
+    switch (entry.verdict) {
+      case "foreign":
+      case "withheld":
+      case "unsupported":
         onServer.add(obj.exportName);
-        outcome.notAttempted.push({
-          ...ref,
-          reason: "unsupported-kind",
-          detail: `${obj.name}: ${altered.unsupported.map((u) => `${u.change.rule} ${u.change.field}: ${u.why}`).join("; ")}. Nothing was sent for it.`,
-        });
+        outcome.notAttempted.push({ ...ref, reason: entry.verdict === "unsupported" ? "unsupported-kind" : "filtered", detail: entry.detail });
+        continue;
+      case "refused":
+        if (entry.live) onServer.add(obj.exportName);
+        outcome.notAttempted.push({ ...ref, reason: "unsupported-kind", detail: entry.detail });
         continue;
-      }
-      steps = altered.steps;
-      if (mine.some((c) => c.rule === "SQLPG252")) recreatedRelations.add(`${obj.canonical.schema}.${obj.canonical.name}`);
-      const stamp = commentStatement(obj, opts.marker);
-      if (!steps.some((s) => s.sql === stamp) && !carriesMarker(liveRaw?.comment, opts.marker)) steps.push({ sql: stamp, class: "metadata", transactional: true, rule: "SQLPG216" });
     }
-    if (steps.length === 0) {
+    if (entry.steps.length === 0) {
       onServer.add(obj.exportName);
       outcome.applied.push({ ...ref, action: "unchanged", ...(liveRaw ? { physicalId: liveRaw.oid } : {}), statements: [] });
       continue;
     }
-    units.push({ obj, ref, created: !live, ...(liveRaw ? { physicalId: liveRaw.oid } : {}), steps, ran: [], pending: [], done: 0, state: "planned" });
+    units.push({ obj, ref, created: !entry.live, ...(liveRaw ? { physicalId: liveRaw.oid } : {}), steps: entry.steps, ran: [], pending: [], done: 0, state: "planned" });
   }
 
   // ── Run them, grouped into transactions. ──
@@ -482,7 +428,7 @@ export async function applyPostgres(
   }
   await commit();
 
-  if (opts.prune) await prune(client, plan.diff.changes, liveRawByKey, opts, timeouts, outcome, log);
+  if (opts.prune) await prune(client, statements.drops, liveRawByKey, opts, timeouts, outcome, log);
   if (outcome.failed.length > 0) throw new PostgresApplyError(outcome);
   return outcome;
 }
@@ -529,21 +475,17 @@ async function dropInvalidIndex(client: PostgresClient, index: string, log: (lin
 
 async function prune(
   client: PostgresClient,
-  changes: readonly PgChange[],
+  drops: readonly PgDropStatement[],
   liveRawByKey: Map<string, LivePgObject>,
   opts: PostgresApplyOptions,
   timeouts: PostgresApplyTimeouts,
   outcome: PostgresApplyOutcome,
   log: (line: string) => void,
 ): Promise<void> {
-  const orphans = changes
-    .filter((c) => (c.rule === "SQLPG270" || c.rule === "SQLPG242") && c.after === undefined)
-    .map((c) => liveRawByKey.get(c.object))
-    .filter((o): o is LivePgObject => o !== undefined && !o.foreign)
-    .map((o) => ({ raw: o, address: liveCanonicalAddress(o) }))
-    .sort((a, b) => DROP_ORDER[a.address.kind] - DROP_ORDER[b.address.kind]);
-
-  for (const { raw, address } of orphans) {
+  for (const drop of drops) {
+    const raw = liveRawByKey.get(drop.key);
+    if (!raw || raw.foreign) continue;
+    const address = liveCanonicalAddress(raw);
     const ref = { kind: raw.type, name: refName(address) };
     if (!isChantManaged(raw.comment)) continue; // not chant's: never touched, never reported
     if (!opts.marker?.stack) {
@@ -555,7 +497,7 @@ async function prune(
       continue;
     }
     if (!carriesMarker(raw.comment, opts.marker)) continue; // another stack's or env's
-    const s = dropStatement(address.kind, address.schema, address.name);
+    const s = drop.step;
     const t = { lockTimeoutMs: timeouts.lockTimeoutMs, statementTimeoutMs: scansRows(s.class) ? timeouts.scanTimeoutMs : timeouts.statementTimeoutMs };
     try {
       opts.signal?.throwIfAborted();