@intentius/chant-lexicon-sql 0.118.1 → 0.121.0

package/src/clickhouse/rebuild/engines.ts

@@ -0,0 +1,163 @@
+/**
+ * Which table engines the rebuild reads as merged (#3674): the verification
+ * (`./verify.ts`) and the plan's hand-off note (`../plan/rebuild-handoff.ts`).
+ */
+
+/**
+ * The MergeTree engines that collapse rows sharing a sorting key when parts
+ * merge, as `system.tables.engine` names them, replicated or shared too. A
+ * count of such a table depends on which parts have merged; under `FINAL` it
+ * does not.
+ */
+const COLLAPSING_ENGINE = /^(?:Replicated|Shared)?(?:Summing|Replacing|Aggregating|Collapsing|VersionedCollapsing|Coalescing|Graphite)MergeTree$/;
+
+/** Whether an engine collapses rows that share a sorting key (#3674). */
+export const collapsesRows = (engine: string | undefined): boolean => COLLAPSING_ENGINE.test(engine ?? "");
+
+/** A column of the new table, as `system.columns` reports it. */
+export interface EngineColumn {
+  name: string;
+  type: string;
+  /** Part of the sorting key: the engine never merges its values. */
+  inSortingKey: boolean;
+  /** Part of the partition key: rows that merge share its value, so a SummingMergeTree does not sum it. */
+  inPartitionKey?: boolean;
+}
+
+/**
+ * How a collapsing engine merges the rows that share a sorting key, as what a
+ * merge leaves the same (#3727): for each key, the aggregates it preserves and
+ * whether it keeps the key at all. Both tables are grouped by the new table's
+ * sorting key and compared on these, so it does not matter which parts have
+ * merged, and a table that never collapses (a plain MergeTree) compares with
+ * one that does.
+ */
+export interface CollapseSemantics {
+  /** The engine's name without `Replicated` or `Shared`. */
+  engine: string;
+  /** Per key: what merging leaves unchanged. SQL over the new table's column names. */
+  aggregates: string[];
+  /** Per key: whether the engine keeps a row for it. Absent: every key keeps one. */
+  having?: string;
+  /** One line for the summary and the error: what is compared per key. */
+  describe: string;
+}
+
+/** Split on the commas outside parentheses and quotes. */
+export function splitTopLevel(text: string): string[] {
+  const out: string[] = [];
+  let depth = 0;
+  let quote: string | undefined;
+  let start = 0;
+  for (let i = 0; i < text.length; i++) {
+    const c = text[i]!;
+    if (quote) {
+      if (c === "\\") i++;
+      else if (c === quote) quote = undefined;
+    } else if (c === "'" || c === '"' || c === "`") quote = c;
+    else if (c === "(" || c === "[") depth++;
+    else if (c === ")" || c === "]") depth--;
+    else if (c === "," && depth === 0) {
+      out.push(text.slice(start, i).trim());
+      start = i + 1;
+    }
+  }
+  const last = text.slice(start).trim();
+  if (last || out.length > 0) out.push(last);
+  return out;
+}
+
+/** The engine's own arguments in `system.tables.engine_full`, without a `Replicated` engine's Keeper path and replica name. */
+export function engineArguments(engineFull: string): string[] {
+  const m = /^\s*(\w+)\s*\(/.exec(engineFull);
+  if (!m) return [];
+  let depth = 0;
+  let quote: string | undefined;
+  const from = m[0].length;
+  let end = -1;
+  for (let i = from - 1; i < engineFull.length && end < 0; i++) {
+    const c = engineFull[i]!;
+    if (quote) {
+      if (c === "\\") i++;
+      else if (c === quote) quote = undefined;
+    } else if (c === "'") quote = c;
+    else if (c === "(") depth++;
+    else if (c === ")" && --depth === 0) end = i;
+  }
+  if (end < 0) return [];
+  const args = splitTopLevel(engineFull.slice(from, end)).filter((a) => a !== "");
+  if (/^(?:Replicated|Shared)/.test(m[1]!)) while (args.length > 0 && args[0]!.startsWith("'")) args.shift();
+  return args;
+}
+
+const NUMERIC = /^(?:U?Int(?:8|16|32|64|128|256)|Float(?:32|64)|BFloat16|Decimal(?:32|64|128|256)?\s*\(.*\))$/;
+const FLOAT = /^(?:Float(?:32|64)|BFloat16)$/;
+/** The SimpleAggregateFunction functions whose result a merge keeps exactly, whatever the order of the rows. */
+const SIMPLE_ORDER_FREE = new Set(["sum", "sumWithOverflow", "min", "max", "groupBitAnd", "groupBitOr", "groupBitXor"]);
+
+const quoted = (name: string) => `\`${name.replace(/\\/g, "\\\\").replace(/`/g, "\\`")}\``;
+const typeLiteral = (type: string) => `'${type.replace(/\\/g, "\\\\").replace(/'/g, "\\'")}'`;
+/** A sum in the column's own type, as the engine stores it; a float to 32 bits, since the order rows are added in moves its last bits. */
+const summed = (c: EngineColumn) => (FLOAT.test(c.type) ? `toFloat32(sum(${quoted(c.name)}))` : `CAST(sum(${quoted(c.name)}), ${typeLiteral(c.type)})`);
+
+/**
+ * What a merge of `engine` keeps per sorting key, or undefined for an engine
+ * that does not collapse rows, or whose result depends on the order rows
+ * merge in (`GraphiteMergeTree` thins its rows by age).
+ */
+export function collapseSemantics(engine: string, engineFull: string, columns: readonly EngineColumn[]): CollapseSemantics | undefined {
+  if (!collapsesRows(engine)) return undefined;
+  const base = engine.replace(/^(?:Replicated|Shared)/, "").replace(/MergeTree$/, "");
+  const args = engineArguments(engineFull);
+  const values = columns.filter((c) => !c.inSortingKey);
+  const named = (n: string | undefined) => (n ? columns.find((c) => c.name === n.replace(/^`|`$/g, "")) : undefined);
+  switch (base) {
+    case "Summing": {
+      // The columns listed, else every numeric column outside the sorting and partition keys; a key whose sums are all zero is removed.
+      const listed = args[0] ? splitTopLevel(args[0].replace(/^\((.*)\)$/s, "$1")).map(named) : undefined;
+      const sums = (listed ? listed.filter((c): c is EngineColumn => c !== undefined) : values).filter((c) => !c.inSortingKey && !c.inPartitionKey && NUMERIC.test(c.type));
+      const aggregates = sums.map(summed);
+      return {
+        engine: `${base}MergeTree`,
+        aggregates,
+        ...(aggregates.length > 0 ? { having: `NOT (${aggregates.map((a) => `${a} = 0`).join(" AND ")})` } : {}),
+        describe: sums.length > 0 ? `the sums of ${sums.map((c) => c.name).join(", ")}` : "the keys",
+      };
+    }
+    case "Replacing": {
+      // The row with the highest version is kept; without a version, the last one written, so only the key is compared.
+      const ver = named(args[0]);
+      return { engine: `${base}MergeTree`, aggregates: ver ? [`max(${quoted(ver.name)})`] : [], describe: ver ? `the highest ${ver.name}` : "the keys" };
+    }
+    case "Collapsing":
+    case "VersionedCollapsing": {
+      // A pair of rows with opposite signs cancels: the sum of the signs is what a merge keeps, and a key whose signs cancel out is removed.
+      const sign = named(args[0]);
+      if (!sign) return undefined;
+      const s = `sum(${quoted(sign.name)})`;
+      return { engine: `${base}MergeTree`, aggregates: [s], having: `${s} != 0`, describe: `the sum of ${sign.name}` };
+    }
+    case "Aggregating": {
+      const simple = values.flatMap((c) => {
+        const m = /^SimpleAggregateFunction\(\s*(\w+)\s*,/.exec(c.type);
+        return m && SIMPLE_ORDER_FREE.has(m[1]!) ? [{ c, fn: m[1]! }] : [];
+      });
+      return {
+        engine: `${base}MergeTree`,
+        aggregates: simple.map(({ c, fn }) => `${fn}(${quoted(c.name)})`),
+        describe: simple.length > 0 ? `${simple.map(({ c, fn }) => `${fn}(${c.name})`).join(", ")}` : "the keys",
+      };
+    }
+    case "Coalescing": {
+      // The last value that is not NULL is kept: whether a column has one is what a merge keeps.
+      const nullable = values.filter((c) => /^Nullable\(/.test(c.type));
+      return {
+        engine: `${base}MergeTree`,
+        aggregates: nullable.map((c) => `count(${quoted(c.name)}) > 0`),
+        describe: nullable.length > 0 ? `which of ${nullable.map((c) => c.name).join(", ")} hold a value` : "the keys",
+      };
+    }
+    default:
+      return undefined;
+  }
+}

package/src/clickhouse/rebuild/rebuild-collapsing.e2e.test.ts

@@ -0,0 +1,120 @@
+/**
+ * A rebuild of a SummingMergeTree with unmerged parts (#3674).
+ *
+ * Three rows for one key, in three parts the server is kept from merging.
+ * The copy inserts them in one block, which the new table collapses into one
+ * row as it writes it, so the raw counts differ (3 and 1) although the data
+ * is the same. The Verify phase reads both tables under FINAL, finds them
+ * equal, and the run reaches the swap gate.
+ *
+ * Runs against `CHANT_SQL_E2E_CLICKHOUSE_URL` when it is set (a shared
+ * server: everything is in the database `chant_e2e_3674`, dropped
+ * afterwards, with this test's receipts), otherwise a scratch server, which
+ * needs Docker and 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 { memoryGateLedgerPort, runOpLocally, loadProfiles, type ActivityFn, type OpConfig } from "@intentius/chant/op";
+import { dockerAvailable, startScratchServer, type ScratchServer } from "../container";
+import { clickhouseQuery, type ClickHouseEndpoint } from "../http";
+import { clickhouseImage } from "../../spec/pin";
+import { clickhouseApply } from "../../op/activities/clickhouse-apply";
+import * as rebuildActivities from "../../op/activities/clickhouse-rebuild";
+import { ClickHouseRebuildOp } from "./op";
+import { RECEIPTS_DATABASE, RECEIPTS_TABLE } from "./receipts";
+
+const given = process.env.CHANT_SQL_E2E_CLICKHOUSE_URL;
+const enabled = given ? true : await dockerAvailable();
+const DB = "chant_e2e_3674";
+const MARKER = { stack: "chant_e2e_3674", env: "test" };
+let server: ScratchServer | undefined;
+let endpoint: ClickHouseEndpoint;
+const dir = mkdtempSync(join(tmpdir(), "chant-sql-rebuild-collapsing-"));
+
+const q = <T = Record<string, unknown>>(sql: string) => clickhouseQuery<T>(endpoint, sql);
+const count = async (from: string) => Number((await q<{ n: string }>(`SELECT count() AS n FROM ${from}`))[0]!.n);
+
+async function cleanup(): Promise<void> {
+  await q(`DROP DATABASE IF EXISTS ${DB} SYNC`);
+  const receipts = await q<{ n: string }>(`SELECT count() AS n FROM system.tables WHERE database = '${RECEIPTS_DATABASE}' AND name = '${RECEIPTS_TABLE}'`);
+  if (Number(receipts[0]!.n) > 0) {
+    await clickhouseQuery(endpoint, `ALTER TABLE ${RECEIPTS_DATABASE}.${RECEIPTS_TABLE} DELETE WHERE position(address, '${MARKER.stack}') > 0`, { settings: { mutations_sync: "2" } });
+  }
+}
+
+beforeAll(async () => {
+  if (!enabled) return;
+  if (given) endpoint = { url: given, user: "default", password: process.env.CHANT_SQL_E2E_CLICKHOUSE_PASSWORD ?? "" };
+  else {
+    server = await startScratchServer(clickhouseImage(), { namePrefix: "chant-sql-rebuild-collapsing" });
+    endpoint = server.endpoint;
+  }
+  await cleanup();
+}, 600_000);
+
+afterAll(async () => {
+  if (enabled) await cleanup().catch(() => undefined);
+  await server?.stop();
+  rmSync(dir, { recursive: true, force: true });
+});
+
+const deps = () => ({ config: { ownership: MARKER }, env: { CLICKHOUSE_URL: endpoint.url, CLICKHOUSE_USER: endpoint.user, CLICKHOUSE_PASSWORD: endpoint.password }, log: () => undefined });
+
+function writeBuild(file: string, orderBy: string): string {
+  const objects = [
+    { export: "db", type: "ClickHouse::Database", ddl: `CREATE DATABASE ${DB} ENGINE = Atomic`, dependsOn: [] },
+    {
+      export: "daily",
+      type: "ClickHouse::Table",
+      dependsOn: ["db"],
+      ddl: `CREATE TABLE ${DB}.daily (day Date, total Decimal(18, 2), n UInt64 DEFAULT 0) ENGINE = SummingMergeTree ORDER BY ${orderBy}`,
+    },
+  ];
+  writeFileSync(join(dir, file), JSON.stringify({ dialect: "clickhouse", applyOrder: objects.map((o) => o.export), objects }));
+  return join(dir, file);
+}
+
+describe.skipIf(!enabled)("a SummingMergeTree with unmerged parts, rebuilt with a new sorting key", () => {
+  test("the Verify phase compares the tables under FINAL and the run reaches the swap gate", async () => {
+    await clickhouseApply({ buildPath: writeBuild("daily-v1.json", "day"), environment: "e2e" }, undefined, deps());
+    await q(`SYSTEM STOP MERGES ${DB}.daily`);
+    for (const total of [30, 30, 40]) await q(`INSERT INTO ${DB}.daily VALUES ('2026-10-10', ${total}, 0)`);
+    expect(await count(`${DB}.daily`)).toBe(3);
+    writeBuild("daily-v2.json", "(day, n)");
+
+    const { op } = ClickHouseRebuildOp({
+      name: "rebuild-daily",
+      env: "e2e",
+      table: `${DB}.daily`,
+      dualWrite: { mode: "materialized-view", cutoverColumn: "day", cutoverDelay: "1s" },
+      build: false,
+      path: dir,
+      output: "daily-v2.json",
+      stack: MARKER.stack,
+      ownershipEnv: MARKER.env,
+    });
+    const activities = new Map<string, ActivityFn>();
+    for (const [name, fn] of Object.entries(rebuildActivities)) {
+      if (typeof fn !== "function" || !name.startsWith("clickhouseRebuild")) continue;
+      activities.set(name, ((args: Record<string, unknown>, signal?: AbortSignal) =>
+        (fn as (a: unknown, s?: AbortSignal, d?: unknown) => Promise<unknown>)(args, signal, deps())) as ActivityFn);
+    }
+    const r = await runOpLocally((op as unknown as { props: OpConfig }).props, activities, await loadProfiles(), undefined, {
+      gates: memoryGateLedgerPort(),
+      now: new Date().toISOString(),
+    });
+
+    const verify = r.records.find((x) => x.fn === "clickhouseRebuildVerify");
+    expect(verify?.error).toBeUndefined();
+    expect(r.status).toBe("gated");
+    expect(r.gate).toMatchObject({ gate: "approve-rebuild-daily" });
+    const verification = r.records.flatMap((x) => x.outcomes ?? []).find((o) => o.name === "Verification")?.value;
+    expect(String(verification)).toMatch(/1 row\(s\).*read under FINAL \(SummingMergeTree\)/);
+    // The old table still holds its three unmerged rows; the new one holds them collapsed.
+    expect(await count(`${DB}.daily`)).toBe(3);
+    expect(await q(`SELECT toString(day) AS day, toString(total) AS total FROM ${DB}.daily__chant_new`)).toEqual([{ day: "2026-10-10", total: "100" }]);
+  }, 300_000);
+});

package/src/clickhouse/rebuild/rebuild-into-collapsing.e2e.test.ts

@@ -0,0 +1,198 @@
+/**
+ * A plain MergeTree rebuilt into a SummingMergeTree (#3727).
+ *
+ * The old table keeps every row it was given; the new one keeps one row per
+ * sorting key, its sums, and drops a key whose sums are all zero. So the row
+ * counts differ by design. The Verify phase groups both tables by the new
+ * sorting key and compares each key's sums, finds them equal, and the run
+ * swaps once approved. A key the new table lost, or a sum it changed, still
+ * fails the verification.
+ *
+ * Runs against `CHANT_SQL_E2E_CLICKHOUSE_URL` when it is set (a shared
+ * server: everything is in the databases `chant_e2e_3727` and
+ * `chant_e2e_3727_loss`, dropped afterwards, with this test's receipts),
+ * otherwise a scratch server, which needs Docker and 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 { memoryGateLedgerPort, runOpLocally, loadProfiles, type ActivityFn, type GateLedgerPort, type OpConfig } from "@intentius/chant/op";
+import { dockerAvailable, startScratchServer, type ScratchServer } from "../container";
+import { clickhouseQuery, type ClickHouseEndpoint } from "../http";
+import { clickhouseImage } from "../../spec/pin";
+import { clickhouseApply } from "../../op/activities/clickhouse-apply";
+import * as rebuildActivities from "../../op/activities/clickhouse-rebuild";
+import { ClickHouseRebuildOp } from "./op";
+import { RECEIPTS_DATABASE, RECEIPTS_TABLE } from "./receipts";
+
+const given = process.env.CHANT_SQL_E2E_CLICKHOUSE_URL;
+const enabled = given ? true : await dockerAvailable();
+const DATABASES = ["chant_e2e_3727", "chant_e2e_3727_loss"];
+const MARKER = { stack: "chant_e2e_3727", env: "test" };
+let server: ScratchServer | undefined;
+let endpoint: ClickHouseEndpoint;
+const dir = mkdtempSync(join(tmpdir(), "chant-sql-rebuild-into-collapsing-"));
+
+const q = <T = Record<string, unknown>>(sql: string) => clickhouseQuery<T>(endpoint, sql);
+const count = async (from: string) => Number((await q<{ n: string }>(`SELECT count() AS n FROM ${from}`))[0]!.n);
+const mutate = (sql: string) => clickhouseQuery(endpoint, sql, { settings: { mutations_sync: "2" } });
+
+async function cleanup(): Promise<void> {
+  for (const db of DATABASES) await q(`DROP DATABASE IF EXISTS ${db} SYNC`);
+  const receipts = await q<{ n: string }>(`SELECT count() AS n FROM system.tables WHERE database = '${RECEIPTS_DATABASE}' AND name = '${RECEIPTS_TABLE}'`);
+  if (Number(receipts[0]!.n) > 0) await mutate(`ALTER TABLE ${RECEIPTS_DATABASE}.${RECEIPTS_TABLE} DELETE WHERE position(address, '${MARKER.stack}') > 0`);
+}
+
+beforeAll(async () => {
+  if (!enabled) return;
+  if (given) endpoint = { url: given, user: "default", password: process.env.CHANT_SQL_E2E_CLICKHOUSE_PASSWORD ?? "" };
+  else {
+    server = await startScratchServer(clickhouseImage(), { namePrefix: "chant-sql-rebuild-into-collapsing" });
+    endpoint = server.endpoint;
+  }
+  await cleanup();
+}, 600_000);
+
+afterAll(async () => {
+  if (enabled) await cleanup().catch(() => undefined);
+  await server?.stop();
+  rmSync(dir, { recursive: true, force: true });
+});
+
+const deps = () => ({ config: { ownership: MARKER }, env: { CLICKHOUSE_URL: endpoint.url, CLICKHOUSE_USER: endpoint.user, CLICKHOUSE_PASSWORD: endpoint.password }, log: () => undefined });
+
+function writeBuild(db: string, file: string, engine: string): string {
+  const objects = [
+    { export: "db", type: "ClickHouse::Database", ddl: `CREATE DATABASE ${db} ENGINE = Atomic`, dependsOn: [] },
+    {
+      export: "daily",
+      type: "ClickHouse::Table",
+      dependsOn: ["db"],
+      ddl: `CREATE TABLE ${db}.daily (day Date, shop UInt32, total Decimal(18, 2), n UInt64) ENGINE = ${engine} PARTITION BY toYYYYMM(day) ORDER BY (day, shop)`,
+    },
+  ];
+  writeFileSync(join(dir, file), JSON.stringify({ dialect: "clickhouse", applyOrder: objects.map((o) => o.export), objects }));
+  return join(dir, file);
+}
+
+/** Eleven rows: shop 1 three times and shop 2 twice on one day, shop 3 whose rows sum to zero, and six single rows across two months. */
+async function seed(db: string): Promise<void> {
+  await q(
+    `INSERT INTO ${db}.daily VALUES ` +
+      `('2026-09-01', 1, 10, 1), ('2026-09-01', 1, 20, 1), ('2026-09-01', 1, 30, 1), ('2026-09-01', 2, 5, 1), ('2026-09-01', 2, 7, 2), ` +
+      `('2026-09-01', 3, 4, 0), ('2026-09-01', 3, -4, 0), ` +
+      `('2026-09-02', 1, 1, 1), ('2026-09-03', 1, 2, 1), ('2026-10-01', 1, 3, 1), ('2026-10-02', 2, 4, 1)`,
+  );
+}
+
+const activities = (): Map<string, ActivityFn> => {
+  const out = new Map<string, ActivityFn>();
+  for (const [name, fn] of Object.entries(rebuildActivities)) {
+    if (typeof fn !== "function" || !name.startsWith("clickhouseRebuild")) continue;
+    out.set(name, ((args: Record<string, unknown>, signal?: AbortSignal) => (fn as (a: unknown, s?: AbortSignal, d?: unknown) => Promise<unknown>)(args, signal, deps())) as ActivityFn);
+  }
+  return out;
+};
+
+/** An in-memory gate ledger: each approval answers the gate the last run stopped at, for the plan it recorded. */
+class Ledger {
+  private pending: unknown[] = [];
+  private resolutions: unknown[] = [];
+  port: GateLedgerPort = memoryGateLedgerPort();
+
+  approveLast(): void {
+    const last = (this.port as ReturnType<typeof memoryGateLedgerPort>).appended.at(-1)!;
+    this.pending.push(...(this.port as ReturnType<typeof memoryGateLedgerPort>).appended);
+    this.resolutions.push({
+      version: 1,
+      kind: "resolution",
+      op: last.op,
+      gate: last.gate,
+      resolvedBy: "e2e",
+      timestamp: new Date(Date.parse(last.timestamp) + 1000).toISOString(),
+      ...(last.planDigest ? { planDigest: last.planDigest } : {}),
+    });
+    this.port = memoryGateLedgerPort({ pending: this.pending as never, resolutions: this.resolutions as never });
+  }
+}
+
+describe.skipIf(!enabled)("a MergeTree rebuilt into a SummingMergeTree", () => {
+  const DB = "chant_e2e_3727";
+  test("the Verify phase compares each sorting key's sums, and the run swaps once approved", async () => {
+    await clickhouseApply({ buildPath: writeBuild(DB, "daily-v1.json", "MergeTree"), environment: "e2e" }, undefined, deps());
+    await seed(DB);
+    writeBuild(DB, "daily-v2.json", "SummingMergeTree");
+
+    const { op } = ClickHouseRebuildOp({
+      name: "rebuild-daily-3727",
+      env: "e2e",
+      table: `${DB}.daily`,
+      dualWrite: { mode: "materialized-view", cutoverColumn: "day", cutoverDelay: "1s" },
+      build: false,
+      path: dir,
+      output: "daily-v2.json",
+      stack: MARKER.stack,
+      ownershipEnv: MARKER.env,
+    });
+    const props = (op as unknown as { props: OpConfig }).props;
+    const ledger = new Ledger();
+    const run = async () => runOpLocally(props, activities(), await loadProfiles(), undefined, { gates: ledger.port, now: new Date().toISOString() });
+
+    const first = await run();
+    expect(first.records.find((x) => x.fn === "clickhouseRebuildVerify")?.error).toBeUndefined();
+    expect(first.status).toBe("gated");
+    expect(first.gate).toMatchObject({ gate: "approve-rebuild-daily-3727" });
+    const verification = first.records.flatMap((x) => x.outcomes ?? []).find((o) => o.name === "Verification")?.value;
+    expect(String(verification)).toMatch(/2 partition\(s\), 11 row\(s\) of the old table as 6 key\(s\).*grouped by the sorting key of the new SummingMergeTree and compared on the sums of total, n/);
+
+    ledger.approveLast();
+    const swapped = await run();
+    expect(swapped.records.find((x) => x.fn === "clickhouseRebuildSwap")?.status).toBe("ok");
+    expect(swapped.gate).toMatchObject({ gate: "approve-rebuild-daily-3727-drop" });
+    expect(await q<{ engine: string }>(`SELECT engine FROM system.tables WHERE database = '${DB}' AND name = 'daily'`)).toEqual([{ engine: "SummingMergeTree" }]);
+    expect(await q(`SELECT toString(day) AS day, shop, toString(total) AS total, toString(n) AS n FROM ${DB}.daily FINAL WHERE day = '2026-09-01' ORDER BY shop`)).toEqual([
+      { day: "2026-09-01", shop: 1, total: "60", n: "3" },
+      { day: "2026-09-01", shop: 2, total: "12", n: "3" },
+    ]);
+  }, 300_000);
+});
+
+describe.skipIf(!enabled)("a MergeTree rebuilt into a SummingMergeTree that lost rows", () => {
+  const DB = "chant_e2e_3727_loss";
+  const args = {
+    table: `${DB}.daily`,
+    buildPath: "loss-v2.json",
+    environment: "e2e",
+    dualWrite: { mode: "materialized-view" as const, cutoverColumn: "day", cutoverDelay: "1s" },
+    stack: MARKER.stack,
+    ownershipEnv: MARKER.env,
+    cwd: dir,
+  };
+
+  test("a changed sum, or a key missing from the new table, fails the verification and nothing is swapped", async () => {
+    await clickhouseApply({ buildPath: writeBuild(DB, "loss-v1.json", "MergeTree"), environment: "e2e" }, undefined, deps());
+    await seed(DB);
+    writeBuild(DB, "loss-v2.json", "SummingMergeTree");
+    await rebuildActivities.clickhouseRebuildCreate(args, undefined, deps());
+    await rebuildActivities.clickhouseRebuildDualWrite(args, undefined, deps());
+    await rebuildActivities.clickhouseRebuildBackfill(args, undefined, deps());
+    expect(await rebuildActivities.clickhouseRebuildVerify(args, undefined, deps())).toMatchObject({ rows: 11, partitions: 2 });
+
+    // A sum the copy got wrong.
+    await mutate(`ALTER TABLE ${DB}.daily__chant_new UPDATE total = total + 1 WHERE shop = 2 AND day = '2026-09-01'`);
+    await expect(rebuildActivities.clickhouseRebuildVerify(args, undefined, deps())).rejects.toThrow(
+      /does not match the old one in 1 partition\(s\): \(?202609\)?: old 4 keys.*new 4 keys.*compared per key on the sums of total, n/,
+    );
+    await mutate(`ALTER TABLE ${DB}.daily__chant_new UPDATE total = total - 1 WHERE shop = 2 AND day = '2026-09-01'`);
+    expect(await rebuildActivities.clickhouseRebuildVerify(args, undefined, deps())).toMatchObject({ rows: 11 });
+
+    // A key the copy lost: the swap compares again before the EXCHANGE and stops.
+    await mutate(`ALTER TABLE ${DB}.daily__chant_new DELETE WHERE shop = 1 AND day = '2026-10-01'`);
+    await expect(rebuildActivities.clickhouseRebuildSwap(args, undefined, deps())).rejects.toThrow(/does not match the old one in 1 partition\(s\): \(?202610\)?: old 2 keys.*new 1 keys/);
+    expect(await q<{ engine: string }>(`SELECT engine FROM system.tables WHERE database = '${DB}' AND name = 'daily'`)).toEqual([{ engine: "MergeTree" }]);
+    expect(await count(`${DB}.daily`)).toBe(11);
+    await rebuildActivities.clickhouseRebuildCompensate(args, undefined, deps());
+  }, 300_000);
+});

package/src/clickhouse/rebuild/rebuild.test.ts

@@ -24,6 +24,8 @@ import { partitionEffect } from "./backfill";
 import { insertTarget, waitForCutover, type CutoverProbe } from "./steps";
 import { intoShard, onShard, onShardServers, shardTable } from "./shards";
 import { renameColumns, sourcePartitionExpression } from "./partitions";
+import { collapseSemantics, collapsesRows, engineArguments, splitTopLevel, type EngineColumn } from "./engines";
+import { RebuildVerificationError } from "./verify";
 import { canonicalObject } from "../plan/normalize";
 import { diffSchemas } from "../plan/diff";
 import { renderDiff } from "../plan/report";
@@ -226,6 +228,42 @@ describe("the plan hands a rebuild to the Op", () => {
   });
 });
 
+describe("a table whose engine collapses rows by sorting key (#3674)", () => {
+  test("the collapsing MergeTree engines are read under FINAL, replicated or shared too; the others are not", () => {
+    for (const e of ["SummingMergeTree", "ReplacingMergeTree", "AggregatingMergeTree", "CollapsingMergeTree", "VersionedCollapsingMergeTree", "ReplicatedSummingMergeTree", "SharedReplacingMergeTree"]) {
+      expect(collapsesRows(e), e).toBe(true);
+    }
+    for (const e of ["MergeTree", "ReplicatedMergeTree", "Log", "Distributed", undefined]) expect(collapsesRows(e), String(e)).toBe(false);
+  });
+
+  test("a difference on such a table names the engine and the OPTIMIZE that merges it, not only a late write", () => {
+    const mismatch = [{ partition: "all", old: { partition: "all", rows: 3, checksum: "1" }, new: { partition: "all", rows: 1, checksum: "2" } }];
+    const collapsing = new RebuildVerificationError("db.daily", mismatch, "SummingMergeTree").message;
+    expect(collapsing).toMatch(/Nothing was swapped\. db\.daily is a SummingMergeTree, .*compared under FINAL/);
+    expect(collapsing).toContain("run OPTIMIZE TABLE db.daily FINAL");
+    const plain = new RebuildVerificationError("db.events", mismatch).message;
+    expect(plain).not.toMatch(/FINAL/);
+    expect(plain).toMatch(/The usual cause is in materialized-view mode a row written to the old table later than the cut-over delay/);
+  });
+
+  test("from a plain MergeTree, a difference names what was compared per key", () => {
+    const mismatch = [{ partition: "202610", old: { partition: "202610", rows: 2, checksum: "1" }, new: { partition: "202610", rows: 1, checksum: "2" } }];
+    const message = new RebuildVerificationError("db.daily", mismatch, { engine: "SummingMergeTree", how: "keys", describe: "the sums of total" }).message;
+    expect(message).toContain("202610: old 2 keys, checksum 1, new 1 keys, checksum 2");
+    expect(message).toMatch(/The new table is a SummingMergeTree, .*compared per key on the sums of total/);
+    expect(message).not.toMatch(/OPTIMIZE/);
+  });
+
+  test("the plan's hand-off says so for such a table", () => {
+    const ddl = (o: string) => `CREATE TABLE db.daily (day Date, total Decimal(18, 2), n UInt64) ENGINE = SummingMergeTree ORDER BY ${o}`;
+    const after = [{ key: "daily", canonical: canonicalObject(ddl("(day, n)")) }];
+    const diff = diffSchemas([{ key: "daily", canonical: canonicalObject(ddl("day")) }], after);
+    const ops = rebuildOpSuggestions(diff, new Map(after.map((o) => [o.key, o.canonical])), "prod");
+    expect(ops[0]!.note).toMatch(/^db\.daily is a SummingMergeTree: when the old table's engine collapses rows too, the Verify phase reads both tables under FINAL/);
+    expect(renderDiff({ ...diff, rebuildOps: ops })).toContain(`  Note: ${ops[0]!.note}`);
+  });
+});
+
 describe("a rebuild across the shards of a cluster (#3663)", () => {
   const sharding = { cluster: "main", shards: [{ num: 1, macro: "s1", slot: 0 }, { num: 2, macro: "s2", slot: 1 }] };
   const shard2 = sharding.shards[1]!;
@@ -294,3 +332,43 @@ describe("the wait for the cut-over (#3700)", () => {
     expect(insertTarget("SELECT * FROM shop.events", "shop")).toBeUndefined();
   });
 });
+
+describe("what a collapsing engine keeps per sorting key (#3727)", () => {
+  const col = (name: string, type: string, inSortingKey = false): EngineColumn => ({ name, type, inSortingKey });
+  const columns = [col("day", "Date", true), col("shop", "UInt32", true), col("total", "Decimal(18, 2)"), col("n", "UInt64"), col("ratio", "Float64"), col("note", "String"), col("sign", "Int8"), col("ver", "UInt32")];
+
+  test("splitTopLevel and engineArguments read engine_full, without a Replicated engine's Keeper path", () => {
+    expect(splitTopLevel("toStartOfInterval(ts, toIntervalDay(1)), id")).toEqual(["toStartOfInterval(ts, toIntervalDay(1))", "id"]);
+    expect(splitTopLevel("")).toEqual([]);
+    expect(engineArguments("SummingMergeTree((total, n)) PARTITION BY toYYYYMM(day) ORDER BY (day, shop) SETTINGS index_granularity = 8192")).toEqual(["(total, n)"]);
+    expect(engineArguments("ReplicatedCollapsingMergeTree('/clickhouse/tables/{uuid}/{shard}', '{replica}', sign) ORDER BY id")).toEqual(["sign"]);
+    expect(engineArguments("SummingMergeTree ORDER BY id")).toEqual([]);
+  });
+
+  test("SummingMergeTree: the sums of every numeric column outside the key, or of those listed, in their own types; a key whose sums are zero is removed", () => {
+    const all = collapseSemantics("SummingMergeTree", "SummingMergeTree ORDER BY (day, shop)", columns)!;
+    expect(all.aggregates).toEqual(["CAST(sum(`total`), 'Decimal(18, 2)')", "CAST(sum(`n`), 'UInt64')", "toFloat32(sum(`ratio`))", "CAST(sum(`sign`), 'Int8')", "CAST(sum(`ver`), 'UInt32')"]);
+    expect(all.having).toBe(`NOT (${all.aggregates.map((a) => `${a} = 0`).join(" AND ")})`);
+    const listed = collapseSemantics("ReplicatedSummingMergeTree", "ReplicatedSummingMergeTree('/p', '{replica}', (total, n)) ORDER BY (day, shop)", columns)!;
+    expect(listed).toMatchObject({ engine: "SummingMergeTree", aggregates: ["CAST(sum(`total`), 'Decimal(18, 2)')", "CAST(sum(`n`), 'UInt64')"], describe: "the sums of total, n" });
+    const partitioned = collapseSemantics("SummingMergeTree", "SummingMergeTree PARTITION BY g ORDER BY k", [col("k", "UInt32", true), { ...col("g", "UInt8"), inPartitionKey: true }, col("a", "UInt32")])!;
+    expect(partitioned.aggregates).toEqual(["CAST(sum(`a`), 'UInt32')"]);
+  });
+
+  test("Replacing keeps the highest version, Collapsing the sum of its signs, Aggregating its order-free simple functions, Coalescing which columns hold a value", () => {
+    expect(collapseSemantics("ReplacingMergeTree", "ReplacingMergeTree(ver) ORDER BY id", columns)).toMatchObject({ aggregates: ["max(`ver`)"], describe: "the highest ver" });
+    expect(collapseSemantics("ReplacingMergeTree", "ReplacingMergeTree ORDER BY id", columns)).toMatchObject({ aggregates: [], describe: "the keys" });
+    expect(collapseSemantics("CollapsingMergeTree", "CollapsingMergeTree(sign) ORDER BY id", columns)).toMatchObject({ aggregates: ["sum(`sign`)"], having: "sum(`sign`) != 0" });
+    expect(collapseSemantics("VersionedCollapsingMergeTree", "VersionedCollapsingMergeTree(sign, ver) ORDER BY id", columns)).toMatchObject({ aggregates: ["sum(`sign`)"], having: "sum(`sign`) != 0" });
+    const agg = [col("k", "UInt32", true), col("hi", "SimpleAggregateFunction(max, UInt64)"), col("any", "SimpleAggregateFunction(anyLast, String)"), col("u", "AggregateFunction(uniq, UInt64)")];
+    expect(collapseSemantics("AggregatingMergeTree", "AggregatingMergeTree ORDER BY k", agg)).toMatchObject({ aggregates: ["max(`hi`)"], describe: "max(hi)" });
+    const coalescing = [col("k", "UInt32", true), col("v", "Nullable(String)"), col("w", "UInt8")];
+    expect(collapseSemantics("CoalescingMergeTree", "CoalescingMergeTree ORDER BY k", coalescing)).toMatchObject({ aggregates: ["count(`v`) > 0"] });
+  });
+
+  test("an engine that keeps every row, or whose rows depend on the order of merges, has none", () => {
+    expect(collapseSemantics("MergeTree", "MergeTree ORDER BY id", columns)).toBeUndefined();
+    expect(collapseSemantics("GraphiteMergeTree", "GraphiteMergeTree('graphite_rollup') ORDER BY id", columns)).toBeUndefined();
+    expect(collapseSemantics("CollapsingMergeTree", "CollapsingMergeTree(missing) ORDER BY id", columns)).toBeUndefined();
+  });
+});