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

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

@@ -0,0 +1,351 @@
+/**
+ * The rebuild migration against the pinned server (#3198).
+ *
+ * - A sorting-key change: the plan and the applier refuse it and name the
+ *   Op; the Op stops at its gate with the verification on the run record,
+ *   swaps once approved, recreates the materialized view that reads the
+ *   table, keeps the old table, and drops it at the second gate.
+ * - A failure: rows that land in the old table after the backfill fail the
+ *   verification, and onFailure drops the new table.
+ * - An interrupted backfill: stopped after three partitions, then killed
+ *   between a partition's INSERT and its receipt, then resumed: the receipts
+ *   skip what was copied, the half-copied partition is cleared first, and the
+ *   verification finds every row once.
+ *
+ * Runs the Op through core's local executor with an in-memory gate ledger.
+ * Needs Docker; skips cleanly without it.
+ */
+
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { normalizeApply } from "@intentius/chant/apply";
+import { memoryGateLedgerPort, runOpLocally, loadProfiles, OpRunFailure, type ActivityFn, type GateLedgerPort, type OpConfig, type OpRunResult } from "@intentius/chant/op";
+import { dockerAvailable, startScratchServer, type ScratchServer } from "../container";
+import { clickhouseQuery } from "../http";
+import { clickhouseImage } from "../../spec/pin";
+import { planAgainstServer } from "../plan/commands";
+import { clickhouseApply, toApplyResult } from "../../op/activities/clickhouse-apply";
+import * as rebuildActivities from "../../op/activities/clickhouse-rebuild";
+import { ClickHouseRebuildOp, type ClickHouseRebuildOpConfig } from "./op";
+import { clickhouseReceiptStore, RECEIPTS_DATABASE, RECEIPTS_TABLE, type ClickHouseReceiptStore } from "./receipts";
+
+const enabled = await dockerAvailable();
+let server: ScratchServer | undefined;
+const dir = mkdtempSync(join(tmpdir(), "chant-sql-rebuild-"));
+
+beforeAll(async () => {
+  if (!enabled) return;
+  server = await startScratchServer(clickhouseImage(), { namePrefix: "chant-sql-rebuild" });
+}, 600_000);
+
+afterAll(async () => {
+  await server?.stop();
+  rmSync(dir, { recursive: true, force: true });
+});
+
+interface Obj {
+  export: string;
+  type: string;
+  ddl: string;
+  dependsOn?: string[];
+}
+
+function writeBuild(file: string, objects: Obj[]): string {
+  writeFileSync(join(dir, file), JSON.stringify({ dialect: "clickhouse", applyOrder: objects.map((o) => o.export), objects: objects.map((o) => ({ dependsOn: [], ...o })) }));
+  return file;
+}
+
+const MARKER = { stack: "e2e", env: "test" };
+const deps = () => ({ config: { ownership: MARKER }, env: { CLICKHOUSE_URL: server!.endpoint.url }, log: () => undefined });
+const q = <T = Record<string, unknown>>(sql: string) => clickhouseQuery<T>(server!.endpoint, sql);
+const count = async (table: string) => Number((await q<{ n: string }>(`SELECT count() AS n FROM ${table}`))[0]!.n);
+const exists = async (database: string, name: string) => Number((await q<{ n: string }>(`SELECT count() AS n FROM system.tables WHERE database = '${database}' AND name = '${name}'`))[0]!.n) > 0;
+const showCreate = async (name: string) => (await q<{ statement: string }>(`SHOW CREATE TABLE ${name}`))[0]!.statement;
+
+/** The rebuild activities, with the test's config, server and a quiet log, as the local executor resolves them. */
+function activities(): Map<string, ActivityFn> {
+  const map = new Map<string, ActivityFn>();
+  for (const [name, fn] of Object.entries(rebuildActivities)) {
+    if (typeof fn !== "function" || !name.startsWith("clickhouseRebuild")) continue;
+    map.set(name, ((args: Record<string, unknown>, signal?: AbortSignal) =>
+      (fn as (a: unknown, s?: AbortSignal, d?: unknown) => Promise<unknown>)(args, signal, deps())) as ActivityFn);
+  }
+  return map;
+}
+
+async function runOp(config: ClickHouseRebuildOpConfig, gates: GateLedgerPort): Promise<OpRunResult> {
+  const { op } = ClickHouseRebuildOp(config);
+  const props = (op as unknown as { props: OpConfig }).props;
+  return runOpLocally(props, activities(), await loadProfiles(), undefined, { gates, now: new Date().toISOString() });
+}
+
+/** An in-memory gate ledger a person approves on: each approval answers the gate the last run stopped at, for the plan it recorded. */
+class Ledger {
+  private pending: unknown[] = [];
+  private resolutions: unknown[] = [];
+  port = memoryGateLedgerPort();
+
+  approveLast(): void {
+    const last = this.port.appended.at(-1)!;
+    this.pending.push(...this.port.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 });
+  }
+}
+
+const outcome = (r: OpRunResult, name: string) => r.records.flatMap((x) => x.outcomes ?? []).find((o) => o.name === name)?.value;
+
+const DB: Obj = { export: "shop", type: "ClickHouse::Database", ddl: "CREATE DATABASE shop ENGINE = Atomic" };
+const eventsDdl = (orderBy: string) => `CREATE TABLE shop.events
+(
+  ts DateTime,
+  user_id UInt64,
+  kind LowCardinality(String)
+)
+ENGINE = MergeTree
+PARTITION BY toYYYYMM(ts)
+ORDER BY ${orderBy}
+COMMENT 'Raw events'`;
+const EVENTS_V1: Obj = { export: "events", type: "ClickHouse::Table", dependsOn: ["shop"], ddl: eventsDdl("(ts, user_id)") };
+const EVENTS_V2: Obj = { ...EVENTS_V1, ddl: eventsDdl("(user_id, ts)") };
+const DAILY: Obj = {
+  export: "daily",
+  type: "ClickHouse::Table",
+  dependsOn: ["shop"],
+  ddl: "CREATE TABLE shop.daily (day Date, n UInt64) ENGINE = SummingMergeTree ORDER BY day",
+};
+const DAILY_MV: Obj = {
+  export: "dailyMv",
+  type: "ClickHouse::MaterializedView",
+  dependsOn: ["events", "daily"],
+  ddl: "CREATE MATERIALIZED VIEW shop.daily_mv TO shop.daily AS SELECT toDate(ts) AS day, count() AS n FROM shop.events GROUP BY day",
+};
+
+describe.skipIf(!enabled)("a sorting-key change, rebuilt through its gates", () => {
+  const config = (): ClickHouseRebuildOpConfig => ({
+    name: "rebuild-events",
+    env: "e2e",
+    table: "shop.events",
+    dualWrite: { mode: "materialized-view", cutoverColumn: "ts", cutoverDelay: "2s" },
+    build: false,
+    path: dir,
+    output: "events-v2.json",
+    retain: "0s",
+    stack: MARKER.stack,
+    ownershipEnv: MARKER.env,
+  });
+  const ledger = new Ledger();
+
+  test("the plan and the applier refuse the change in place and name the Op", async () => {
+    const v1 = writeBuild("events-v1.json", [DB, EVENTS_V1, DAILY, DAILY_MV]);
+    const applied = normalizeApply(toApplyResult(await clickhouseApply({ buildPath: join(dir, v1), environment: "e2e" }, undefined, deps())));
+    expect(applied.notAttempted).toEqual([]);
+    // Four months of rows, all well before any cut-over.
+    await q("INSERT INTO shop.events SELECT toDateTime('2026-01-01 00:00:00') + number * 6480, number % 50, if(number % 3 = 0, 'click', 'view') FROM numbers(1600)");
+
+    const v2 = writeBuild("events-v2.json", [DB, EVENTS_V2, DAILY, DAILY_MV]);
+    const plan = await planAgainstServer("e2e", join(dir, v2), { config: {}, env: { CLICKHOUSE_URL: server!.endpoint.url } });
+    expect(plan.rebuilds.map((c) => c.rule)).toEqual(["SQLCH220"]);
+    expect(plan.rebuildOps).toEqual([
+      expect.objectContaining({ table: "shop.events", env: "e2e", dualWrite: { mode: "materialized-view", cutoverColumn: "ts" } }),
+    ]);
+    expect(plan.rebuildOps![0]!.declaration).toContain('ClickHouseRebuildOp({ name: "rebuild-shop-events", env: "e2e", table: "shop.events"');
+
+    const refused = normalizeApply(toApplyResult(await clickhouseApply({ buildPath: join(dir, v2), environment: "e2e" }, undefined, deps())));
+    expect(refused.notAttempted).toEqual([expect.objectContaining({ name: "shop.events", reason: "unsupported-kind" })]);
+    expect(refused.notAttempted[0]!.detail).toContain('ClickHouseRebuildOp({ table: "shop.events"');
+  }, 180_000);
+
+  test("the first run fills the new table and stops at the swap gate with the verification attached", async () => {
+    const r = await runOp(config(), ledger.port);
+    expect(r.status).toBe("gated");
+    expect(r.gate).toMatchObject({ gate: "approve-rebuild-events" });
+    expect(r.gate!.planDigest).toMatch(/^jcs1-sha256:/);
+    expect(outcome(r, "RebuildState")).toBe("rebuild");
+    expect(outcome(r, "VerifiedRows")).toBe(1600);
+    expect(outcome(r, "VerifiedPartitions")).toBe(4);
+    expect(String(outcome(r, "Verification"))).toMatch(/4 partition\(s\), 1600 row\(s\) before the cut-over/);
+    expect(await count("shop.events__chant_new")).toBe(1600);
+    expect(await exists("shop", "events__chant_dual")).toBe(true);
+    // Nothing visible to a plan or an apply: the working objects are left out.
+    const plan = await planAgainstServer("e2e", join(dir, "events-v2.json"), { config: {}, env: { CLICKHOUSE_URL: server!.endpoint.url } });
+    expect(plan.changes.map((c) => c.rule)).toEqual(["SQLCH220"]);
+
+    // Writes go on during the rebuild; the dual-write view carries them over.
+    await q("INSERT INTO shop.events VALUES (now() + 3600, 7, 'click')");
+    expect(await count("shop.events__chant_new")).toBe(1601);
+
+    // Running again before anyone approves copies nothing again: the four
+    // partitions are skipped by their receipts. The row just written opened a
+    // fifth partition, whose copy is empty (its rows are after the cut-over,
+    // the dual-write view's), and the verification and the plan it binds are
+    // unchanged, so the gate stands as it was.
+    const again = await runOp(config(), ledger.port);
+    expect(again.status).toBe("gated");
+    expect(outcome(again, "Skipped")).toBe(4);
+    expect(outcome(again, "Copied")).toBe(1);
+    expect(again.gate!.planDigest).toBe(r.gate!.planDigest);
+    expect(await count("shop.events__chant_new")).toBe(1601);
+  }, 300_000);
+
+  test("approved, it swaps, recreates the view that reads the table and stops at the drop gate", async () => {
+    ledger.approveLast();
+    const r = await runOp(config(), ledger.port);
+    expect(r.status).toBe("gated");
+    expect(r.gate).toMatchObject({ gate: "approve-rebuild-events-drop" });
+    expect(outcome(r, "Dependents")).toEqual(["shop.daily_mv"]);
+
+    expect(await showCreate("shop.events")).toMatch(/ORDER BY \(user_id, ts\)/);
+    expect(await count("shop.events")).toBe(1601);
+    expect(await exists("shop", "events__chant_dual")).toBe(false);
+    expect(await exists("shop", "events__chant_new")).toBe(false);
+    expect(await count("shop.events__chant_old")).toBe(1601);
+    const [{ comment }] = await q<{ comment: string }>("SELECT comment FROM system.tables WHERE database = 'shop' AND name = 'events'");
+    expect(comment).toBe("Raw events [chant managed-by=chant stack=e2e env=test]");
+
+    // The materialized view reads the new table.
+    const before = Number((await q<{ n: string }>("SELECT sum(n) AS n FROM shop.daily"))[0]!.n);
+    await q("INSERT INTO shop.events VALUES (now(), 8, 'view')");
+    expect(Number((await q<{ n: string }>("SELECT sum(n) AS n FROM shop.daily"))[0]!.n)).toBe(before + 1);
+  }, 300_000);
+
+  test("approved again, it drops the old table, and the server holds the declaration", async () => {
+    ledger.approveLast();
+    const r = await runOp(config(), ledger.port);
+    expect(r.status).toBe("ok");
+    expect(outcome(r, "Dropped")).toBe(true);
+    expect(await exists("shop", "events__chant_old")).toBe(false);
+    const plan = await planAgainstServer("e2e", join(dir, "events-v2.json"), { config: {}, env: { CLICKHOUSE_URL: server!.endpoint.url } });
+    expect(plan.changes).toEqual([]);
+
+    // A run after it is done finds nothing to do.
+    const done = await runOp(config(), ledger.port);
+    expect(done.status).toBe("ok");
+    expect(outcome(done, "RebuildState")).toBe("done");
+  }, 300_000);
+});
+
+describe.skipIf(!enabled)("a failure runs onFailure, which drops the new table", () => {
+  const clicksDdl = (orderBy: string) => `CREATE TABLE shop.clicks (id UInt64, url String) ENGINE = MergeTree ORDER BY ${orderBy}`;
+  const V1: Obj = { export: "clicks", type: "ClickHouse::Table", dependsOn: ["shop"], ddl: clicksDdl("id") };
+  const V2: Obj = { ...V1, ddl: clicksDdl("(url, id)") };
+  const config = (): ClickHouseRebuildOpConfig => ({
+    name: "rebuild-clicks",
+    env: "e2e",
+    table: "shop.clicks",
+    dualWrite: { mode: "app" },
+    build: false,
+    path: dir,
+    output: "clicks-v2.json",
+    stack: MARKER.stack,
+    ownershipEnv: MARKER.env,
+  });
+
+  test("rows written after the backfill fail the verification and the new table is dropped", async () => {
+    await clickhouseApply({ buildPath: join(dir, writeBuild("clicks-v1.json", [DB, V1])), environment: "e2e" }, undefined, deps());
+    await q("INSERT INTO shop.clicks SELECT number, concat('/p/', toString(number % 7)) FROM numbers(500)");
+    writeBuild("clicks-v2.json", [DB, V2]);
+
+    const ledger = new Ledger();
+    const first = await runOp(config(), ledger.port);
+    expect(first.status).toBe("gated");
+    expect(first.gate).toMatchObject({ gate: "rebuild-clicks-writes-stopped" });
+    expect(await exists("shop", "clicks__chant_new")).toBe(true);
+
+    ledger.approveLast();
+    const second = await runOp(config(), ledger.port);
+    expect(second.status).toBe("gated");
+    expect(second.gate).toMatchObject({ gate: "approve-rebuild-clicks" });
+    expect(await count("shop.clicks__chant_new")).toBe(500);
+
+    // The application did not stop writing after all.
+    await q("INSERT INTO shop.clicks VALUES (9999, '/late')");
+    const failure = await runOp(config(), ledger.port).then(
+      () => undefined,
+      (e: unknown) => e,
+    );
+    expect(failure).toBeInstanceOf(OpRunFailure);
+    const records = (failure as OpRunFailure).result.records;
+    expect(records.find((x) => x.fn === "clickhouseRebuildVerify")?.error).toMatch(/does not match the old one in 1 partition/);
+    expect(records.find((x) => x.fn === "clickhouseRebuildCompensate")?.status).toBe("ok");
+    expect(await exists("shop", "clicks__chant_new")).toBe(false);
+    expect(await count("shop.clicks")).toBe(501);
+    expect(await showCreate("shop.clicks")).toMatch(/ORDER BY id/);
+  }, 300_000);
+});
+
+describe.skipIf(!enabled)("an interrupted backfill resumes from its receipts", () => {
+  const viewsDdl = (orderBy: string) => `CREATE TABLE shop.page_views (day Date, page String, n UInt32) ENGINE = MergeTree PARTITION BY day ORDER BY ${orderBy}`;
+  const V1: Obj = { export: "pageViews", type: "ClickHouse::Table", dependsOn: ["shop"], ddl: viewsDdl("(day, page)") };
+  const V2: Obj = { ...V1, ddl: viewsDdl("(page, day)") };
+  const args = () => ({
+    table: "shop.page_views",
+    buildPath: "views-v2.json",
+    environment: "e2e",
+    dualWrite: { mode: "app" as const },
+    stack: MARKER.stack,
+    ownershipEnv: MARKER.env,
+    cwd: dir,
+  });
+
+  test("stopped after three partitions, killed before a receipt, then resumed: every row once", async () => {
+    await clickhouseApply({ buildPath: join(dir, writeBuild("views-v1.json", [DB, V1])), environment: "e2e" }, undefined, deps());
+    await q("INSERT INTO shop.page_views SELECT toDate('2026-03-01') + number % 6, concat('/p/', toString(number % 11)), number FROM numbers(6000)");
+    writeBuild("views-v2.json", [DB, V2]);
+    await rebuildActivities.clickhouseRebuildCreate(args(), undefined, deps());
+
+    // Interrupted (Ctrl-C) after the third partition.
+    const stop = new AbortController();
+    let done = 0;
+    const interrupted = await rebuildActivities
+      .clickhouseRebuildBackfill(args(), stop.signal, { ...deps(), backfill: { afterPartition: () => void (++done === 3 && stop.abort()) } })
+      .then(
+        () => undefined,
+        (e: unknown) => e,
+      );
+    expect(interrupted).toBeDefined();
+    expect(await count("shop.page_views__chant_new")).toBe(3000);
+
+    // Killed between the fourth partition's INSERT and its receipt.
+    const real = clickhouseReceiptStore(server!.endpoint, MARKER);
+    let writes = 0;
+    const crashing: ClickHouseReceiptStore = {
+      ...real,
+      read: real.read,
+      readAll: real.readAll,
+      write: async (receipt, expectation) => {
+        if (++writes === 1) throw new Error("killed before the receipt");
+        return real.write(receipt, expectation);
+      },
+    };
+    await expect(rebuildActivities.clickhouseRebuildBackfill(args(), undefined, { ...deps(), backfill: { receipts: crashing } })).rejects.toThrow(/killed before the receipt/);
+    expect(await count("shop.page_views__chant_new")).toBe(4000);
+
+    // Resumed: three partitions skipped by receipt, the fourth cleared and copied again, two more copied.
+    const resumed = await rebuildActivities.clickhouseRebuildBackfill(args(), undefined, deps());
+    expect(resumed).toMatchObject({ partitions: 6, skipped: 3, copied: 3, cleared: 1 });
+    expect(await count("shop.page_views__chant_new")).toBe(6000);
+
+    const verified = await rebuildActivities.clickhouseRebuildVerify(args(), undefined, deps());
+    expect(verified).toMatchObject({ partitions: 6, rows: 6000 });
+    const receipts = await q<{ address: string }>(`SELECT DISTINCT address FROM ${RECEIPTS_DATABASE}.${RECEIPTS_TABLE} WHERE address LIKE 'e2e/test/rebuild/shop.page_views/%' ORDER BY address`);
+    expect(receipts).toHaveLength(6);
+
+    // The receipts database is chant's own bookkeeping, not a declared schema.
+    const plan = await planAgainstServer("e2e", join(dir, "views-v2.json"), { config: {}, env: { CLICKHOUSE_URL: server!.endpoint.url } });
+    expect(plan.changes.map((c) => c.object)).not.toContain(RECEIPTS_DATABASE);
+
+    const dropped = await rebuildActivities.clickhouseRebuildCompensate(args(), undefined, deps());
+    expect(dropped.dropped).toEqual(["shop.page_views__chant_new"]);
+  }, 300_000);
+});

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

@@ -0,0 +1,190 @@
+/**
+ * The rebuild migration's pieces that need no server (#3198): the Op's
+ * shape and its contracts, the partition arithmetic, the working-object
+ * trailer, and the plan's hand-off to the Op. `rebuild.e2e.test.ts` runs it
+ * against the pinned server.
+ */
+
+import { describe, expect, test } from "vitest";
+import {
+  collectActivityContracts,
+  gatePolicyVersion,
+  loadActivityContracts,
+  mergeActivityContracts,
+  validateActivitySteps,
+  validateStepOutputRefs,
+  type ActivityContract,
+  type OpConfig,
+} from "@intentius/chant/op";
+import * as contractsModule from "../../op/activity-contracts";
+import * as activitiesModule from "../../op/activities";
+import { ClickHouseRebuildOp, type ClickHouseRebuildOpConfig } from "./op";
+import { copiedColumns } from "./observe";
+import { renameColumns, sourcePartitionExpression } from "./partitions";
+import { canonicalObject } from "../plan/normalize";
+import { diffSchemas } from "../plan/diff";
+import { renderDiff } from "../plan/report";
+import { rebuildOpSuggestions } from "../plan/rebuild-handoff";
+import { isChantWorkingObject, isRebuildObject, readMarker, stampedComment, stripMarkerFromStatement } from "../ownership";
+
+const BASE: ClickHouseRebuildOpConfig = {
+  name: "rebuild-events",
+  env: "prod",
+  table: "shop.events",
+  dualWrite: { mode: "materialized-view", cutoverColumn: "ts" },
+};
+const propsOf = (config: ClickHouseRebuildOpConfig) => (ClickHouseRebuildOp(config).op as unknown as { props: OpConfig }).props;
+
+describe("ClickHouseRebuildOp", () => {
+  test("its phases, in order, with onFailure dropping the new table", () => {
+    const props = propsOf(BASE);
+    expect(props.phases.map((p) => p.name)).toEqual([
+      "Build",
+      "Plan",
+      "Create",
+      "Dual write",
+      "Backfill",
+      "Verify",
+      "Approve",
+      "Swap",
+      "Retain",
+      "Approve drop",
+      "Drop",
+    ]);
+    expect(props.onFailure?.map((p) => p.steps.map((s) => (s as { fn?: string }).fn))).toEqual([["clickhouseRebuildCompensate"]]);
+    expect(props.labels).toEqual({ Rebuild: "true", Env: "prod", Table: "shop.events" });
+  });
+
+  test("the swap gate binds the verification's digest and the drop gate the retained table's", () => {
+    const props = propsOf(BASE);
+    const gates = props.phases.flatMap((p) => p.steps).filter((s) => s.kind === "gate") as Array<{ gate: string; plan: unknown }>;
+    expect(gates.map((g) => g.gate)).toEqual(["approve-rebuild-events", "approve-rebuild-events-drop"]);
+    expect(JSON.stringify(gates[0]!.plan)).toContain('"verify"');
+    expect(JSON.stringify(gates[0]!.plan)).toContain('"planDigest"');
+    expect(JSON.stringify(gates[1]!.plan)).toContain('"dropDigest"');
+  });
+
+  test("app mode replaces the dual-write view with a gate for the write stop", () => {
+    const props = propsOf({ ...BASE, dualWrite: { mode: "app" }, build: false });
+    expect(props.phases[0]!.name).toBe("Plan");
+    const dual = props.phases.find((p) => p.name === "Dual write")!;
+    expect(dual.steps).toEqual([expect.objectContaining({ kind: "gate", gate: "rebuild-events-writes-stopped" })]);
+  });
+
+  test("a policy on the swap gate gets the verification's counts as context", () => {
+    const text = "permit (principal, action, resource);";
+    const policy = { kind: "gate-policy" as const, lexicon: "cedar", name: "ship", version: gatePolicyVersion(text), text };
+    const props = propsOf({ ...BASE, gate: { approval: { policy, mode: "log-only" } } });
+    const gate = props.phases.find((p) => p.name === "Approve")!.steps[0] as { approval: { context: Record<string, unknown> } };
+    expect(Object.keys(gate.approval.context)).toEqual(["verifiedPartitions", "verifiedRows"]);
+  });
+
+  test("bad configuration fails when the Op is built", () => {
+    expect(() => ClickHouseRebuildOp({ ...BASE, table: "shop.events; DROP" })).toThrow(/table must be/);
+    expect(() => ClickHouseRebuildOp({ ...BASE, dualWrite: { mode: "materialized-view", cutoverColumn: "" } })).toThrow(/cutoverColumn/);
+    expect(() => ClickHouseRebuildOp({ ...BASE, dualWrite: { mode: "both" } as never })).toThrow(/dualWrite\.mode/);
+  });
+
+  test("every step passes the contracts OPS012 and OPS013 check it against at build", async () => {
+    const contracts = new Map<string, ActivityContract>();
+    collectActivityContracts(contractsModule as unknown as Record<string, unknown>, contracts);
+    const merged = mergeActivityContracts(await loadActivityContracts([]), contracts);
+    for (const config of [BASE, { ...BASE, dualWrite: { mode: "app" as const }, retain: "3d", replicaTimeout: "30s", stack: "shop", ownershipEnv: "prod" }]) {
+      const props = propsOf(config);
+      expect(validateActivitySteps(props, merged)).toEqual([]);
+      expect(validateStepOutputRefs(props, merged)).toEqual([]);
+    }
+  });
+
+  test("every rebuild step is an activity the sql lexicon exports, and none is a receipt activity", () => {
+    const exported = new Set(Object.entries(activitiesModule).filter(([, v]) => typeof v === "function").map(([k]) => k));
+    const steps = propsOf(BASE).phases.flatMap((p) => p.steps).filter((s) => s.kind === "activity" && (s as { fn: string }).fn.startsWith("clickhouseRebuild"));
+    for (const s of steps) expect(exported.has((s as { fn: string }).fn)).toBe(true);
+    expect(exported.has("receiptRead")).toBe(false);
+    expect(exported.has("receiptWrite")).toBe(false);
+  });
+});
+
+describe("partitions", () => {
+  const copied = [
+    { name: "ts", source: "ts" },
+    { name: "account", source: "user_id" },
+  ];
+
+  test("an unchanged key is the new table's own partition id", () => {
+    expect(sourcePartitionExpression("toYYYYMM(ts)", "toYYYYMM(ts)", copied)).toBe("_partition_id");
+  });
+  test("a changed key computes the old one over the new table's columns", () => {
+    expect(sourcePartitionExpression("toYYYYMM(ts)", "toDate(ts)", copied)).toBe("partitionID(toYYYYMM(ts))");
+    expect(sourcePartitionExpression("(user_id, toYYYYMM(ts))", "toYYYYMM(ts)", copied)).toBe("partitionID(`account`, toYYYYMM(ts))");
+    expect(sourcePartitionExpression("user_id % 4", "user_id % 4", copied)).toBe("partitionID(`account` % 4)");
+  });
+  test("no partition key is the one partition `all`", () => {
+    expect(sourcePartitionExpression("", "toYYYYMM(ts)", copied)).toBe("'all'");
+  });
+  test("renaming leaves function names and other columns alone", () => {
+    expect(renameColumns("cityHash64(user_id) + user_id_extra", copied)).toBe("cityHash64(`account`) + user_id_extra");
+  });
+
+  test("the copied columns follow renames and skip what the new table computes", () => {
+    const live = canonicalObject("CREATE TABLE t (ts DateTime, user_id UInt64, kind String) ENGINE = MergeTree ORDER BY ts");
+    const declared = canonicalObject(
+      "CREATE TABLE t (ts DateTime, account UInt64, -- previously: user_id\n kind String, day Date MATERIALIZED toDate(ts), fresh UInt8 DEFAULT 1) ENGINE = MergeTree ORDER BY (account, ts)",
+    );
+    expect(copiedColumns(declared, live)).toEqual([
+      { name: "ts", source: "ts" },
+      { name: "account", source: "user_id" },
+      { name: "kind", source: "kind" },
+    ]);
+  });
+});
+
+describe("working objects", () => {
+  const marker = { stack: "shop", env: "prod" };
+
+  test("the trailer carries the rebuild's pairs after the marker, and still reads as this project's", () => {
+    const c = stampedComment(undefined, marker, { rebuild: "shop.events", role: "dual", cutover: "2026-10-02T12:00:00.000Z" });
+    expect(c).toBe("[chant managed-by=chant stack=shop env=prod rebuild=shop.events role=dual cutover=2026-10-02T12%3A00%3A00.000Z]");
+    expect(readMarker(c)).toEqual({ managedBy: "chant", ...marker });
+    expect(isRebuildObject(c)).toBe(true);
+    expect(isChantWorkingObject(c)).toBe(true);
+    expect(isRebuildObject("Raw events [chant managed-by=chant stack=shop env=prod]")).toBe(false);
+    expect(isChantWorkingObject("chant effect receipts [chant managed-by=chant receipts=effects]")).toBe(true);
+    expect(stripMarkerFromStatement(`CREATE TABLE t (x UInt8) ENGINE = Log COMMENT 'Raw ${c}'`)).toBe("CREATE TABLE t (x UInt8) ENGINE = Log COMMENT 'Raw'");
+  });
+
+  test("a trailer key outside the pair grammar is refused", () => {
+    expect(() => stampedComment(undefined, marker, { "bad key": "x" })).toThrow(/is not/);
+  });
+});
+
+describe("the plan hands a rebuild to the Op", () => {
+  const ddl = (orderBy: string, timeType = "DateTime") => `CREATE TABLE shop.events (ts ${timeType}, user_id UInt64) ENGINE = MergeTree ORDER BY ${orderBy}`;
+
+  test("each refused table gets a ClickHouseRebuildOp declaration, materialized-view mode on its time column", () => {
+    const after = [{ key: "events", canonical: canonicalObject(ddl("(user_id, ts)")) }];
+    const diff = diffSchemas([{ key: "events", canonical: canonicalObject(ddl("(ts, user_id)")) }], after);
+    const ops = rebuildOpSuggestions(diff, new Map(after.map((o) => [o.key, o.canonical])), "prod");
+    expect(ops).toEqual([
+      {
+        table: "shop.events",
+        name: "rebuild-shop-events",
+        env: "prod",
+        dualWrite: { mode: "materialized-view", cutoverColumn: "ts" },
+        declaration:
+          'export const { op } = ClickHouseRebuildOp({ name: "rebuild-shop-events", env: "prod", table: "shop.events", dualWrite: { mode: "materialized-view", cutoverColumn: "ts" } });',
+      },
+    ]);
+    const text = renderDiff({ ...diff, rebuildOps: ops });
+    expect(text).toMatch(/Refused: 1 change\(s\) need a rebuild/);
+    expect(text).toContain("ClickHouseRebuildOp } from \"@intentius/chant-lexicon-sql/clickhouse\"");
+    expect(text).toContain(ops[0]!.declaration);
+  });
+
+  test("a table with no time column is suggested app mode", () => {
+    const noTime = (o: string) => `CREATE TABLE shop.clicks (id UInt64, url String) ENGINE = MergeTree ORDER BY ${o}`;
+    const after = [{ key: "clicks", canonical: canonicalObject(noTime("(url, id)")) }];
+    const diff = diffSchemas([{ key: "clicks", canonical: canonicalObject(noTime("id")) }], after);
+    expect(rebuildOpSuggestions(diff, new Map(after.map((o) => [o.key, o.canonical])), "<env>")[0]!.dualWrite).toEqual({ mode: "app" });
+  });
+});