@intentius/chant-lexicon-sql 0.112.0 → 0.113.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-sql",
-  "version": "0.112.0",
+  "version": "0.113.0",
   "description": "SQL lexicon for chant — database schema as typed declarations, one dialect at a time; ClickHouse first, with types read from a pinned server's catalog",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",
@@ -70,7 +70,7 @@
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "@intentius/chant": "^0.112.0",
+    "@intentius/chant": "^0.113.0",
     "typescript": "^5.9.3"
   }
 }

package/src/clickhouse/apply/apply.ts

@@ -36,7 +36,6 @@ import type { OwnershipMarker } from "@intentius/chant/ownership";
 import type { ApplyRef } from "@intentius/chant/apply";
 import {
   SqlApplyError,
-  changesByObject,
   dependencyFailedDetail,
   missingDependencies,
   readBuildObjects,
@@ -50,19 +49,7 @@ import { diffSchemas, type Change } from "../plan/diff";
 import { dropFormattingOnly } from "../plan/server-format";
 import { CLICKHOUSE_ENTITY_TYPES, type ClickHouseEntityType } from "../entities";
 import { carriesMarker, isChantManaged } from "../ownership";
-import {
-  alterSteps,
-  commentStatement,
-  createStatement,
-  dropStatement,
-  isDestructiveAlter,
-  isRebuild,
-  refusalDetail,
-  sqlString,
-  stepsSetComment,
-  type DeclaredObject,
-  type Step,
-} from "./statements";
+import { planStatements, sqlString, type DeclaredObject, type DropStatement, type Step } from "./statements";
 import { waitForMutations } from "./mutations";
 
 export type { FailedObject } from "../../core/apply";
@@ -117,14 +104,6 @@ export class ClickHouseApplyError extends SqlApplyError<ClickHouseApplyOutcome>
 
 const liveKey = (o: LiveObject) => (o.database !== undefined ? `${o.database}.${o.name}` : o.name);
 
-/** Drop order: what reads from a table before the table, a database last. */
-const DROP_ORDER: Record<string, number> = {
-  [CLICKHOUSE_ENTITY_TYPES.materializedView]: 0,
-  [CLICKHOUSE_ENTITY_TYPES.view]: 1,
-  [CLICKHOUSE_ENTITY_TYPES.table]: 2,
-  [CLICKHOUSE_ENTITY_TYPES.database]: 3,
-};
-
 /**
  * The server's objects in the databases the declarations use, as the diff
  * compares them. The `default` database itself is never part of a schema.
@@ -160,7 +139,6 @@ export async function applyClickHouse(target: ClickHouseTarget, declared: readon
   const { objects: liveObjects, canonical: live } = await liveSchema(target, declared);
   const liveByKey = new Map(liveObjects.map((o) => [liveKey(o), o]));
   const changes = await plannedChanges(target, declared, live);
-  const byObject = changesByObject(changes);
 
   const outcome: ClickHouseApplyOutcome = { target: target.endpoint.url, source: target.source, applied: [], pruned: [], notAttempted: [], failed: [] };
   /** Export names whose object is on the server. */
@@ -181,35 +159,33 @@ export async function applyClickHouse(target: ClickHouseTarget, declared: readon
     }
   };
 
-  for (const obj of declared) {
+  const plan = planStatements({
+    declared,
+    changes,
+    current: live,
+    allowDestructive: opts.prune === true,
+    carriesMarker: (key) => carriesMarker(liveByKey.get(key)?.comment, opts.marker),
+    ...(opts.marker ? { marker: opts.marker } : {}),
+  });
+
+  for (const entry of plan.objects) {
+    const obj = entry.obj;
     const ref = { kind: obj.type, name: obj.key };
-    const mine = byObject.get(obj.key) ?? [];
-    const created = mine.some((c) => c.rule === "SQLCH200");
-    const renamedFrom = mine.find((c) => c.rule === "SQLCH230" || c.rule === "SQLCH231")?.before;
+    const renamedFrom = entry.changes.find((c) => c.rule === "SQLCH230" || c.rule === "SQLCH231")?.before;
     const liveObject = liveByKey.get(renamedFrom ?? obj.key);
-    const liveCanonical = live.get(renamedFrom ?? obj.key);
 
-    const refused = mine.filter(isRebuild);
-    if (refused.length > 0) {
+    if (entry.verdict === "rebuild") {
       if (liveObject) onServer.add(obj.exportName);
-      outcome.notAttempted.push({ ...ref, reason: "unsupported-kind", detail: refusalDetail(refused, obj.key, obj.type) });
+      outcome.notAttempted.push({ ...ref, reason: "unsupported-kind", detail: entry.detail });
       continue;
     }
-    const destructive = mine.filter(isDestructiveAlter);
-    if (destructive.length > 0 && !opts.prune) {
+    if (entry.verdict === "withheld") {
       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`,
-      });
+      outcome.notAttempted.push({ ...ref, reason: "filtered", detail: entry.detail });
       continue;
     }
-
-    const restamp = !created && !stepsSetComment(obj, mine) && (mine.some((c) => c.field === "comment") || !carriesMarker(liveObject?.comment, opts.marker));
-    const steps: Step[] = created
-      ? [{ sql: createStatement(obj, opts.marker), rewrite: false }]
-      : [...alterSteps(obj, mine, { ...(liveCanonical ? { live: liveCanonical } : {}), ...(opts.marker ? { marker: opts.marker } : {}) }), ...(restamp ? [{ sql: commentStatement(obj, opts.marker), rewrite: false }] : [])];
+    const created = entry.verdict === "create";
+    const steps = entry.steps;
 
     if (steps.length === 0) {
       onServer.add(obj.exportName);
@@ -235,26 +211,22 @@ export async function applyClickHouse(target: ClickHouseTarget, declared: readon
     }
   }
 
-  if (opts.prune) await prune(target, changes, liveByKey, opts, outcome, log);
+  if (opts.prune) await prune(target, plan.drops, liveByKey, opts, outcome, log);
   if (outcome.failed.length > 0) throw new ClickHouseApplyError(outcome);
   return outcome;
 }
 
 async function prune(
   target: ClickHouseTarget,
-  changes: readonly Change[],
+  drops: readonly DropStatement[],
   liveByKey: Map<string, LiveObject>,
   opts: ClickHouseApplyOptions,
   outcome: ClickHouseApplyOutcome,
   log: (line: string) => void,
 ): Promise<void> {
-  const orphans = changes
-    .filter((c) => c.rule === "SQLCH250")
-    .map((c) => liveByKey.get(c.object))
-    .filter((o): o is LiveObject => o !== undefined)
-    .sort((a, b) => (DROP_ORDER[a.type] ?? 9) - (DROP_ORDER[b.type] ?? 9));
-
-  for (const o of orphans) {
+  for (const drop of drops) {
+    const o = liveByKey.get(drop.key);
+    if (!o) continue;
     const ref = { kind: o.type, name: liveKey(o) };
     if (!isChantManaged(o.comment)) continue; // not chant's: never touched, never reported
     if (!opts.marker?.stack) {
@@ -275,7 +247,7 @@ async function prune(
           continue;
         }
       }
-      const sql = dropStatement(o.type, o.database, o.name);
+      const sql = drop.step.sql;
       opts.signal?.throwIfAborted();
       log(sql);
       await clickhouseQuery(target.endpoint, sql);

package/src/clickhouse/apply/statements.ts

@@ -20,7 +20,7 @@ import { isTrivia, tokenizeText, type Token } from "../tokens";
 import { parseCreate, type CreateNode, type Span, type TableNode, type ViewNode } from "../parser";
 import { canonicalObject, type CanonicalObject } from "../plan/normalize";
 import type { Change } from "../plan/diff";
-import { CLASSIFIER_RULES } from "../plan/rules";
+import { CLASSIFIER_RULES, type ChangeClass, type ClassifierRuleId } from "../plan/rules";
 import { stampedComment } from "../ownership";
 import { CLICKHOUSE_ENTITY_TYPES, type ClickHouseEntityType } from "../entities";
 
@@ -53,11 +53,21 @@ export interface DeclaredObject {
   dependsOn: string[];
 }
 
-/** One statement to send, and whether it starts a background rewrite to wait on. */
+/** One statement to send, the change it makes, and whether it starts a background rewrite to wait on. */
 export interface Step {
   sql: string;
   /** A mutation follows on the server; wait on `system.mutations` before the next step. */
   rewrite: boolean;
+  /** The classifier rule of the change it makes. */
+  rule: ClassifierRuleId;
+  /** That rule's class. */
+  class: ChangeClass;
+}
+
+/** The step for a statement that makes a change under `rule`: a rewrite-class rule waits on its mutation. */
+export function stepFor(sql: string, rule: ClassifierRuleId): Step {
+  const cls = CLASSIFIER_RULES[rule].class;
+  return { sql, rewrite: cls === "rewrite", rule, class: cls };
 }
 
 interface Parsed {
@@ -259,7 +269,7 @@ function reorderSteps(t: string, tokens: Token[], node: TableNode, live: Canonic
     if (have === want) continue;
     current.splice(at, 1);
     current.splice(want === undefined ? 0 : current.indexOf(want) + 1, 0, name);
-    steps.push({ sql: `ALTER TABLE ${t} MODIFY COLUMN ${ident(name)} ${columnType(tokens, node, name)} ${want === undefined ? "FIRST" : `AFTER ${ident(want)}`}`, rewrite: false });
+    steps.push(stepFor(`ALTER TABLE ${t} MODIFY COLUMN ${ident(name)} ${columnType(tokens, node, name)} ${want === undefined ? "FIRST" : `AFTER ${ident(want)}`}`, "SQLCH209"));
   }
   return steps;
 }
@@ -267,11 +277,11 @@ function reorderSteps(t: string, tokens: Token[], node: TableNode, live: Canonic
 function tableSteps(obj: DeclaredObject, changes: readonly Change[], live: CanonicalObject | undefined): Step[] {
   const { tokens, node } = parsed(obj) as { tokens: Token[]; node: TableNode };
   const t = objectIdent(obj);
-  const alter = (clause: string, rewrite = false): Step => ({ sql: `ALTER TABLE ${t} ${clause}`, rewrite });
+  const alter = (clause: string, rule: ClassifierRuleId): Step => stepFor(`ALTER TABLE ${t} ${clause}`, rule);
   const steps: Step[] = [];
   const of = (rule: string) => changes.filter((c) => c.rule === rule);
 
-  for (const c of of("SQLCH212")) steps.push(alter(`RENAME COLUMN ${ident(c.before!)} TO ${ident(c.after!)}`));
+  for (const c of of("SQLCH212")) steps.push(alter(`RENAME COLUMN ${ident(c.before!)} TO ${ident(c.after!)}`, "SQLCH212"));
 
   // Added columns, in declared order, each at its declared place. Appending
   // new columns to the sorting key has to happen in the same ALTER as adding
@@ -281,10 +291,10 @@ function tableSteps(obj: DeclaredObject, changes: readonly Change[], live: Canon
     .sort((a, b) => node.columns.findIndex((c) => c.name === a) - node.columns.findIndex((c) => c.name === b));
   const adds = added.map((name) => `ADD COLUMN ${columnDefinition(tokens, node, name)} ${position(node, name)}`);
   const sortKey = of("SQLCH216")[0];
-  if (sortKey) steps.push(alter([...adds, `MODIFY ORDER BY ${text(tokens, node.orderBy)}`].join(", ")));
-  else for (const a of adds) steps.push(alter(a));
+  if (sortKey) steps.push(alter([...adds, `MODIFY ORDER BY ${text(tokens, node.orderBy)}`].join(", "), "SQLCH216"));
+  else for (const a of adds) steps.push(alter(a, "SQLCH201"));
 
-  for (const c of of("SQLCH202")) steps.push(alter(`DROP COLUMN ${ident(columnField(c.field)!.column)}`));
+  for (const c of of("SQLCH202")) steps.push(alter(`DROP COLUMN ${ident(columnField(c.field)!.column)}`, "SQLCH202"));
 
   for (const c of changes) {
     const f = columnField(c.field);
@@ -293,59 +303,56 @@ function tableSteps(obj: DeclaredObject, changes: readonly Change[], live: Canon
     const name = ident(f.column);
     switch (c.rule) {
       case "SQLCH210":
-        steps.push(alter(`MODIFY COLUMN ${name} ${columnType(tokens, node, f.column)}`, true));
+        steps.push(alter(`MODIFY COLUMN ${name} ${columnType(tokens, node, f.column)}`, c.rule));
         break;
       case "SQLCH207":
-        if (col.default) steps.push(alter(`MODIFY COLUMN ${name} ${col.default.kind}${col.default.expr ? ` ${text(tokens, col.default.expr)}` : ""}`));
-        else steps.push(alter(`MODIFY COLUMN ${name} REMOVE ${(c.before ?? "DEFAULT").split(" ")[0]}`));
+        if (col.default) steps.push(alter(`MODIFY COLUMN ${name} ${col.default.kind}${col.default.expr ? ` ${text(tokens, col.default.expr)}` : ""}`, c.rule));
+        else steps.push(alter(`MODIFY COLUMN ${name} REMOVE ${(c.before ?? "DEFAULT").split(" ")[0]}`, c.rule));
         break;
       case "SQLCH208":
-        steps.push(alter(col.codec ? `MODIFY COLUMN ${name} CODEC(${text(tokens, col.codec)})` : `MODIFY COLUMN ${name} REMOVE CODEC`));
+        steps.push(alter(col.codec ? `MODIFY COLUMN ${name} CODEC(${text(tokens, col.codec)})` : `MODIFY COLUMN ${name} REMOVE CODEC`, c.rule));
         break;
       case "SQLCH205":
-        steps.push(alter(col.ttl ? `MODIFY COLUMN ${name} TTL ${text(tokens, col.ttl)}` : `MODIFY COLUMN ${name} REMOVE TTL`, true));
+        steps.push(alter(col.ttl ? `MODIFY COLUMN ${name} TTL ${text(tokens, col.ttl)}` : `MODIFY COLUMN ${name} REMOVE TTL`, c.rule));
         break;
       case "SQLCH203":
-        steps.push(alter(`COMMENT COLUMN ${name} ${sqlString(obj.canonical.columns.find((x) => x.name === f.column)?.comment ?? "")}`));
+        steps.push(alter(`COMMENT COLUMN ${name} ${sqlString(obj.canonical.columns.find((x) => x.name === f.column)?.comment ?? "")}`, c.rule));
         break;
     }
   }
 
   for (const c of of("SQLCH204")) {
     const name = c.field.slice("indexes.".length);
-    if (c.before !== undefined) steps.push(alter(`DROP INDEX ${ident(name)}`));
+    if (c.before !== undefined) steps.push(alter(`DROP INDEX ${ident(name)}`, c.rule));
     const ix = node.indexes.find((x) => x.name === name);
     if (ix) {
       steps.push(
-        alter(`ADD INDEX ${ident(name)} ${text(tokens, ix.expr)} TYPE ${text(tokens, ix.type)}${ix.granularity ? ` GRANULARITY ${text(tokens, ix.granularity)}` : ""}`),
+        alter(`ADD INDEX ${ident(name)} ${text(tokens, ix.expr)} TYPE ${text(tokens, ix.type)}${ix.granularity ? ` GRANULARITY ${text(tokens, ix.granularity)}` : ""}`, c.rule),
       );
     }
   }
   for (const c of of("SQLCH214")) {
     const name = c.field.slice("projections.".length);
-    if (c.before !== undefined) steps.push(alter(`DROP PROJECTION ${ident(name)}`));
+    if (c.before !== undefined) steps.push(alter(`DROP PROJECTION ${ident(name)}`, c.rule));
     const p = node.projections.find((x) => x.name === name);
-    if (p) steps.push(alter(`ADD PROJECTION ${ident(name)} (${text(tokens, p.body)})`));
+    if (p) steps.push(alter(`ADD PROJECTION ${ident(name)} (${text(tokens, p.body)})`, c.rule));
   }
   for (const c of of("SQLCH215")) {
     const name = c.field.slice("constraints.".length);
-    if (c.before !== undefined) steps.push(alter(`DROP CONSTRAINT ${ident(name)}`));
+    if (c.before !== undefined) steps.push(alter(`DROP CONSTRAINT ${ident(name)}`, c.rule));
     const k = node.constraints.find((x) => x.name === name);
-    if (k) steps.push(alter(`ADD CONSTRAINT ${ident(name)} ${k.kind} ${text(tokens, k.expr)}`));
+    if (k) steps.push(alter(`ADD CONSTRAINT ${ident(name)} ${k.kind} ${text(tokens, k.expr)}`, c.rule));
   }
 
   for (const c of of("SQLCH205").filter((x) => x.field === "ttl")) {
-    steps.push(alter(node.ttl ? `MODIFY TTL ${text(tokens, node.ttl)}` : "REMOVE TTL", true));
-  }
-  for (const c of of("SQLCH217")) {
-    void c;
-    steps.push(alter(node.sampleBy ? `MODIFY SAMPLE BY ${text(tokens, node.sampleBy)}` : "REMOVE SAMPLE BY"));
+    steps.push(alter(node.ttl ? `MODIFY TTL ${text(tokens, node.ttl)}` : "REMOVE TTL", c.rule));
   }
+  for (const c of of("SQLCH217")) steps.push(alter(node.sampleBy ? `MODIFY SAMPLE BY ${text(tokens, node.sampleBy)}` : "REMOVE SAMPLE BY", c.rule));
   for (const c of of("SQLCH206")) {
     const key = c.field.slice("settings.".length);
     const s = node.settings?.find((x) => x.key === key);
     // A setting declared at its default compares as absent: set it as written.
-    steps.push(alter(s ? `MODIFY SETTING ${key} = ${text(tokens, s.value)}` : `RESET SETTING ${key}`));
+    steps.push(alter(s ? `MODIFY SETTING ${key} = ${text(tokens, s.value)}` : `RESET SETTING ${key}`, c.rule));
   }
 
   if (of("SQLCH209").length > 0) steps.push(...reorderSteps(t, tokens, node, live, changes));
@@ -357,11 +364,11 @@ function viewSteps(obj: DeclaredObject, changes: readonly Change[], marker: Owne
   const t = objectIdent(obj);
   const steps: Step[] = [];
   if (!node.materialized) {
-    if (changes.some((c) => c.rule === "SQLCH240")) steps.push({ sql: createStatement(obj, marker, { orReplace: true }), rewrite: false });
+    if (changes.some((c) => c.rule === "SQLCH240")) steps.push(stepFor(createStatement(obj, marker, { orReplace: true }), "SQLCH240"));
     return steps;
   }
-  if (changes.some((c) => c.rule === "SQLCH241")) steps.push({ sql: `ALTER TABLE ${t} MODIFY QUERY ${text(tokens, node.select)}`, rewrite: false });
-  if (changes.some((c) => c.rule === "SQLCH244") && node.refresh) steps.push({ sql: `ALTER TABLE ${t} MODIFY REFRESH ${text(tokens, node.refresh)}`, rewrite: false });
+  if (changes.some((c) => c.rule === "SQLCH241")) steps.push(stepFor(`ALTER TABLE ${t} MODIFY QUERY ${text(tokens, node.select)}`, "SQLCH241"));
+  if (changes.some((c) => c.rule === "SQLCH244") && node.refresh) steps.push(stepFor(`ALTER TABLE ${t} MODIFY REFRESH ${text(tokens, node.refresh)}`, "SQLCH244"));
   return steps;
 }
 
@@ -376,11 +383,11 @@ function viewSteps(obj: DeclaredObject, changes: readonly Change[], marker: Owne
  */
 export function alterSteps(obj: DeclaredObject, changes: readonly Change[], opts: { live?: CanonicalObject; marker?: OwnershipMarker } = {}): Step[] {
   const steps: Step[] = [];
-  for (const c of changes.filter((x) => x.rule === "SQLCH231")) steps.push({ sql: `RENAME DATABASE ${ident(c.before!)} TO ${ident(c.after!)}`, rewrite: false });
+  for (const c of changes.filter((x) => x.rule === "SQLCH231")) steps.push(stepFor(`RENAME DATABASE ${ident(c.before!)} TO ${ident(c.after!)}`, "SQLCH231"));
   for (const c of changes.filter((x) => x.rule === "SQLCH230")) {
     const from = splitQualified(c.before!);
     const to = splitQualified(c.after!);
-    steps.push({ sql: `RENAME TABLE ${qualifiedIdent(from.database, from.name)} TO ${qualifiedIdent(to.database, to.name)}`, rewrite: false });
+    steps.push(stepFor(`RENAME TABLE ${qualifiedIdent(from.database, from.name)} TO ${qualifiedIdent(to.database, to.name)}`, "SQLCH230"));
   }
   if (obj.type === CLICKHOUSE_ENTITY_TYPES.table) steps.push(...tableSteps(obj, changes, opts.live));
   else if (obj.type === CLICKHOUSE_ENTITY_TYPES.view || obj.type === CLICKHOUSE_ENTITY_TYPES.materializedView) steps.push(...viewSteps(obj, changes, opts.marker));
@@ -391,3 +398,114 @@ export function alterSteps(obj: DeclaredObject, changes: readonly Change[], opts
 export function stepsSetComment(obj: DeclaredObject, changes: readonly Change[]): boolean {
   return obj.type === CLICKHOUSE_ENTITY_TYPES.view && changes.some((c) => c.rule === "SQLCH240");
 }
+
+// ── a schema's statements ─────────────────────────────────────────────
+
+/**
+ * What one declared object takes, as the applier and the offline renderer
+ * (`../../migration-statements.ts`) both see it:
+ *
+ * - `create` or `alter`: the statements, in the order they run. An `alter`
+ *   with none is an object already as declared.
+ * - `rebuild`: a change ALTER cannot make; nothing is sent for the object and
+ *   the rebuild migration Op makes it (`detail` names the Op).
+ * - `withheld`: a column drop, which destroys data, in a plan not allowed to
+ *   delete.
+ */
+export type ObjectStatements =
+  | { verdict: "create" | "alter"; obj: DeclaredObject; changes: Change[]; steps: Step[] }
+  | { verdict: "rebuild"; obj: DeclaredObject; changes: Change[]; refused: Change[]; detail: string }
+  | { verdict: "withheld"; obj: DeclaredObject; changes: Change[]; withheld: Change[]; detail: string };
+
+/** An object a schema no longer declares, and the `DROP` for it. */
+export interface DropStatement {
+  /** The key the changes name it by. */
+  key: string;
+  type: ClickHouseEntityType;
+  database?: string;
+  name: string;
+  step: Step;
+}
+
+export interface StatementPlanInput {
+  /** The declared objects, in creation order. */
+  declared: readonly DeclaredObject[];
+  /** The classified changes from the current schema to the declared one. */
+  changes: readonly Change[];
+  /** The current definitions, keyed as the changes key objects. */
+  current: ReadonlyMap<string, CanonicalObject>;
+  /** How the changes key a declared object: `database.name` against a server (the default), the export name between two builds. */
+  keyOf?: (obj: DeclaredObject) => string;
+  /** The marker every `CREATE` and restamped comment carries. */
+  marker?: OwnershipMarker;
+  /** Column drops are planned, not withheld. Default: off. */
+  allowDestructive?: boolean;
+  /** Whether the current object (by its key in `current`) carries the marker already; one that does not is restamped. Default: it does. */
+  carriesMarker?: (currentKey: string) => boolean;
+}
+
+export interface StatementPlan {
+  /** One entry per declared object, in creation order. */
+  objects: ObjectStatements[];
+  /** The objects the declarations no longer hold, in drop order: what reads from a table first, a database last. */
+  drops: DropStatement[];
+}
+
+/** Drop order: what reads from a table before the table, a database last. */
+const DROP_ORDER: Record<string, number> = { materializedView: 0, view: 1, table: 2, database: 3 };
+
+/**
+ * The statements that take the current schema to the declared one, from the
+ * classified changes between them. Pure: nothing is read or sent. The applier
+ * (`./apply.ts`) runs the steps against a server; `diffStatements`
+ * (`../../migration-statements.ts`) renders the same steps for a migration
+ * file. Anything that changes the SQL sent for a change belongs here, so
+ * both see it.
+ */
+export function planStatements(input: StatementPlanInput): StatementPlan {
+  const keyOf = input.keyOf ?? ((o: DeclaredObject) => o.key);
+  const byObject = new Map<string, Change[]>();
+  for (const c of input.changes) byObject.set(c.object, [...(byObject.get(c.object) ?? []), c]);
+
+  const objects: ObjectStatements[] = input.declared.map((obj): ObjectStatements => {
+    const key = keyOf(obj);
+    const mine = byObject.get(key) ?? [];
+    const refused = mine.filter(isRebuild);
+    if (refused.length > 0) return { verdict: "rebuild", obj, changes: mine, refused, detail: refusalDetail(refused, obj.key, obj.type) };
+    const destructive = mine.filter(isDestructiveAlter);
+    if (destructive.length > 0 && !input.allowDestructive) {
+      return {
+        verdict: "withheld",
+        obj,
+        changes: mine,
+        withheld: destructive,
+        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`,
+      };
+    }
+    if (mine.some((c) => c.rule === "SQLCH200")) return { verdict: "create", obj, changes: mine, steps: [stepFor(createStatement(obj, input.marker), "SQLCH200")] };
+
+    const renamedFrom = mine.find((c) => c.rule === "SQLCH230" || c.rule === "SQLCH231")?.before;
+    const currentKey = renamedFrom !== undefined && input.current.has(renamedFrom) ? renamedFrom : key;
+    const live = input.current.get(currentKey);
+    const restamp = !stepsSetComment(obj, mine) && (mine.some((c) => c.field === "comment") || !(input.carriesMarker?.(currentKey) ?? true));
+    const steps = [
+      ...alterSteps(obj, mine, { ...(live ? { live } : {}), ...(input.marker ? { marker: input.marker } : {}) }),
+      ...(restamp ? [stepFor(commentStatement(obj, input.marker), "SQLCH203")] : []),
+    ];
+    return { verdict: "alter", obj, changes: mine, steps };
+  });
+
+  const drops: DropStatement[] = [];
+  for (const c of input.changes) {
+    if (c.rule !== "SQLCH250") continue;
+    const o = input.current.get(c.object);
+    if (!o) continue;
+    const type = CLICKHOUSE_ENTITY_TYPES[o.kind as keyof typeof CLICKHOUSE_ENTITY_TYPES];
+    const database = o.kind === "database" ? undefined : o.database;
+    drops.push({ key: c.object, type, ...(database !== undefined ? { database } : {}), name: o.name, step: stepFor(dropStatement(type, database, o.name), "SQLCH250") });
+  }
+  drops.sort((a, b) => (DROP_ORDER[kindOf(a.type)] ?? 9) - (DROP_ORDER[kindOf(b.type)] ?? 9));
+  return { objects, drops };
+}
+
+const kindOf = (type: string): string => Object.entries(CLICKHOUSE_ENTITY_TYPES).find(([, t]) => t === type)?.[0] ?? "table";

package/src/clickhouse/plan/commands.ts

@@ -4,7 +4,7 @@
  * says `"dialect": "postgres"`) or a Postgres binding goes to
  * `../../postgres/plan/commands.ts`.
  *
- *     chant sql diff <before.json> <after.json> [--json]
+ *     chant sql diff <before.json> <after.json> [--json] [--statements]
  *     chant sql plan <env> <build.json> [--json]
  *
  * `diff` is offline: it compares two `chant build` outputs, say a pull
@@ -14,6 +14,11 @@
  * rebuild, which a plan refuses to make in place, and 0 otherwise; for each
  * refused table they name the `ClickHouseRebuildOp` to run instead
  * (`rebuildOps` in `--json`, `./rebuild-handoff.ts`).
+ *
+ * `diff --statements` prints the statements instead, for a migration file:
+ * each one the applier would send, with its change's rule and class, and a
+ * refused change as the Op that makes it (`../../migration-statements.ts`).
+ * The marker in each `CREATE` is the project's `ownership` config's.
  */
 
 import type { CommandGroup, CommandGroupContext } from "@intentius/chant/cli/command-group";
@@ -34,8 +39,26 @@ function outputDialect(path: string): string | undefined {
   }
 }
 
-function split(args: string[]): { positional: string[]; json: boolean } {
-  return { positional: args.filter((a) => !a.startsWith("--")), json: args.includes("--json") };
+function split(args: string[]): { positional: string[]; json: boolean; statements: boolean } {
+  return { positional: args.filter((a) => !a.startsWith("--")), json: args.includes("--json"), statements: args.includes("--statements") };
+}
+
+/** `chant sql diff --statements`: the statements between two builds, as SQL with comments or as JSON. Exits 2 when a step is an Op or manual. */
+async function runDiffStatements(before: string, after: string, json: boolean): Promise<number> {
+  const { diffStatements, renderStatements } = await import("../../migration-statements");
+  const { resolveOwnershipMarker } = await import("../../core/apply");
+  let marker;
+  try {
+    const { loadChantConfig } = await import("@intentius/chant/config");
+    const config = await loadChantConfig(process.cwd()).then((r) => r.config).catch(() => undefined);
+    marker = resolveOwnershipMarker({}, config, "chant sql diff --statements");
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    return 1;
+  }
+  const doc = diffStatements(readFileSync(before, "utf-8"), readFileSync(after, "utf-8"), marker ? { marker } : {});
+  console.log(json ? JSON.stringify(doc, null, 2) : renderStatements(doc));
+  return doc.refused ? 2 : 0;
 }
 
 function emit(diff: SchemaDiff, json: boolean, title: string): number {
@@ -44,11 +67,12 @@ function emit(diff: SchemaDiff, json: boolean, title: string): number {
 }
 
 export async function runDiff(ctx: CommandGroupContext): Promise<number> {
-  const { positional, json } = split(ctx.rawArgs);
+  const { positional, json, statements } = split(ctx.rawArgs);
   if (positional.length !== 2) {
-    console.error("usage: chant sql diff <before.json> <after.json> [--json]");
+    console.error("usage: chant sql diff <before.json> <after.json> [--json] [--statements]");
     return 1;
   }
+  if (statements) return runDiffStatements(positional[0]!, positional[1]!, json);
   if (outputDialect(positional[1]!) === "postgres") {
     const { diffPgBuildFiles, emitPg, projectMajor } = await import("../../postgres/plan/commands");
     return emitPg(diffPgBuildFiles(positional[0]!, positional[1]!, await projectMajor()), json, `${positional[0]} -> ${positional[1]}`);
@@ -95,7 +119,7 @@ export const sqlCommands: CommandGroup = {
   name: "sql",
   description: "Schema changes, classified: between two builds, or a build and a live server",
   commands: [
-    { name: "diff", description: "Classify the change between two chant build outputs (offline)", handler: runDiff },
+    { name: "diff", description: "Classify the change between two chant build outputs (offline); --statements prints the statements it takes", handler: runDiff },
     { name: "plan", description: "Classify the change from an environment's server to a chant build output", handler: runPlan },
   ],
 };

package/src/clickhouse/topology.e2e.test.ts

@@ -0,0 +1,100 @@
+/**
+ * The single-node rendering against a server (#3645): one migration source
+ * written for a cluster (`ON CLUSTER`, `Replicated*MergeTree` with Keeper
+ * paths, a `Replicated` database) is refused by a single node as written
+ * and applies once rendered for it, with the plain MergeTree family.
+ *
+ * Runs against `CLICKHOUSE_URL` when it is set (the emulator, `chant
+ * emulator up --lexicon sql`), else a scratch server of the pinned image.
+ * Everything it writes is in the database `yodel_3645`. Needs one or the
+ * other; skips cleanly without Docker.
+ */
+
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { dockerAvailable, startScratchServer, type ScratchServer } from "./container";
+import { clickhouseQuery, type ClickHouseEndpoint } from "./http";
+import { clickhouseImage } from "../spec/pin";
+import { renderStatement, type Topology } from "./topology";
+
+const DB = "yodel_3645";
+const fromEnv = process.env.CLICKHOUSE_URL;
+const enabled = fromEnv !== undefined || (await dockerAvailable());
+let server: ScratchServer | undefined;
+let endpoint: ClickHouseEndpoint;
+
+const q = <T = Record<string, unknown>>(sql: string) => clickhouseQuery<T>(endpoint, sql);
+
+beforeAll(async () => {
+  if (!enabled) return;
+  if (fromEnv !== undefined) {
+    endpoint = {
+      url: fromEnv,
+      ...(process.env.CLICKHOUSE_USER ? { user: process.env.CLICKHOUSE_USER } : {}),
+      ...(process.env.CLICKHOUSE_PASSWORD ? { password: process.env.CLICKHOUSE_PASSWORD } : {}),
+    };
+  } else {
+    server = await startScratchServer(clickhouseImage(), { namePrefix: "chant-sql-topology" });
+    endpoint = server.endpoint;
+  }
+  await q(`DROP DATABASE IF EXISTS ${DB} SYNC`);
+}, 600_000);
+
+afterAll(async () => {
+  if (enabled) await q(`DROP DATABASE IF EXISTS ${DB} SYNC`).catch(() => undefined);
+  await server?.stop();
+});
+
+const SINGLE: Topology = { kind: "single" };
+
+/** One migration, written for a cluster named `main`. */
+const SOURCE = [
+  `CREATE DATABASE ${DB} ON CLUSTER main ENGINE = Replicated('/clickhouse/databases/${DB}', '{shard}', '{replica}') COMMENT 'topology e2e'`,
+  `CREATE TABLE ${DB}.events ON CLUSTER main (
+    id UInt64,
+    ts DateTime,
+    kind LowCardinality(String)
+  ) ENGINE = ReplicatedReplacingMergeTree('/clickhouse/tables/{shard}/${DB}/events', '{replica}', ts)
+  ORDER BY id`,
+  `CREATE MATERIALIZED VIEW ${DB}.by_kind ON CLUSTER main
+  ENGINE = ReplicatedSummingMergeTree('/clickhouse/tables/{shard}/${DB}/by_kind', '{replica}')
+  ORDER BY kind
+  AS SELECT kind, count() AS n FROM ${DB}.events GROUP BY kind`,
+  `CREATE TABLE ${DB}.staging ON CLUSTER main (id UInt64, ts DateTime, kind LowCardinality(String)) ENGINE = ReplicatedReplacingMergeTree(ts) ORDER BY id`,
+  `ALTER TABLE ${DB}.events ON CLUSTER main ADD COLUMN source String DEFAULT 'web' AFTER kind`,
+  `ALTER TABLE ${DB}.staging ON CLUSTER main ADD COLUMN source String DEFAULT 'web' AFTER kind`,
+  `ALTER TABLE ${DB}.events ON CLUSTER main MODIFY COMMENT 'events'`,
+  `EXCHANGE TABLES ${DB}.events AND ${DB}.staging ON CLUSTER main`,
+  `RENAME TABLE ${DB}.staging TO ${DB}.events_old ON CLUSTER main`,
+  `DROP TABLE ${DB}.events_old ON CLUSTER main SYNC`,
+];
+
+describe.skipIf(!enabled)("the single-node rendering against a server (#3645)", () => {
+  test("the source as written for a cluster is refused by a single node", async () => {
+    await expect(q(SOURCE[0]!)).rejects.toThrow();
+    await expect(q(renderStatement(SOURCE[0]!, SINGLE))).resolves.toEqual([]);
+    // The database is there now; the table as written still fails, on its ON CLUSTER or its Keeper path.
+    await expect(q(SOURCE[1]!)).rejects.toThrow();
+    await q(`DROP DATABASE ${DB} SYNC`);
+  });
+
+  test("every statement rendered for a single node applies, with the plain MergeTree family", async () => {
+    for (const sql of SOURCE) {
+      const rendered = renderStatement(sql, SINGLE);
+      expect(rendered).not.toMatch(/ON CLUSTER|Replicated/);
+      await q(rendered);
+    }
+    const db = await q<{ engine: string }>(`SELECT engine FROM system.databases WHERE name = '${DB}'`);
+    expect(db).toEqual([{ engine: "Atomic" }]);
+    const tables = await q<{ name: string; engine: string }>(
+      `SELECT name, engine FROM system.tables WHERE database = '${DB}' AND NOT startsWith(name, '.inner') ORDER BY name`,
+    );
+    expect(tables).toEqual([
+      { name: "by_kind", engine: "MaterializedView" },
+      { name: "events", engine: "ReplacingMergeTree" },
+    ]);
+    const inner = await q<{ engine: string }>(`SELECT engine FROM system.tables WHERE database = '${DB}' AND startsWith(name, '.inner')`);
+    expect(inner).toEqual([{ engine: "SummingMergeTree" }]);
+    const cols = await q<{ name: string }>(`SELECT name FROM system.columns WHERE database = '${DB}' AND table = 'events' ORDER BY position`);
+    expect(cols.map((c) => c.name)).toEqual(["id", "ts", "kind", "source"]);
+  });
+});