@intentius/sql-yodeler 0.0.0-stage → 0.2.0

package/dist/steps/kinds.js

@@ -0,0 +1,143 @@
+/**
+ * What each step of a migration is to `yodel apply`, and the hash its
+ * history rows record.
+ *
+ * A migration's `steps` (in `migration.json`) are chant's: a `statement`
+ * apply sends as SQL, an `op` step naming the Op that makes a change no
+ * statement makes, or a `manual` step a person acts on. Apply runs two kinds
+ * of Op step itself, inside the migration and under its lock and gate:
+ *
+ * - `ClickHouseRebuildOp`, the step `yodel new` writes for a ClickHouse sort
+ *   key, engine or key-column change (`./rebuild.ts`);
+ * - `backfill`, a data backfill the author writes as an Op of `effect()`
+ *   steps in a module in the migration's directory (`./backfill.ts`);
+ * - `PostgresMigrationOp`, the step `yodel new` writes for a Postgres column
+ *   rename or type change across kinds (`./postgres-migration.ts`, #13).
+ *
+ * Everything else (a manual step, a rebuild in app mode) is refused before
+ * anything runs, with exit 2.
+ */
+import { createHash } from "node:crypto";
+import { normalizeLineEndings, sortKeys } from "../migrations/document.js";
+/** The `op` of a backfill step. */
+export const BACKFILL_OP = "backfill";
+/** The module a backfill step runs, in the migration's directory, unless its `options.file` names another. */
+export const BACKFILL_FILE = "backfill.ts";
+export const REBUILD_OP = "ClickHouseRebuildOp";
+export const PG_MIGRATION_OP = "PostgresMigrationOp";
+const isRecord = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+/** The step as a backfill step, when it is one. */
+export const asBackfill = (step) => step.kind === "op" && step.op === BACKFILL_OP ? step : undefined;
+/** The file a backfill step names: relative to the migration's directory, `/`-separated, inside it. */
+function backfillFile(options) {
+    const file = isRecord(options) ? options.file : undefined;
+    if (typeof file !== "string" || file === "")
+        return undefined;
+    const parts = file.split("/");
+    if (parts.some((p) => p === "" || p === "." || p === ".." || p.startsWith(".")) || file.includes("\\"))
+        return undefined;
+    return file;
+}
+/** How `yodel apply` treats one step. */
+export function planStep(step) {
+    if (step.kind === "statement")
+        return { run: "statement" };
+    if (step.kind === "manual")
+        return { run: "refused", reason: `a manual step for ${step.object} (${step.name}): no statement and no Op makes it; ${step.detail}` };
+    const backfill = asBackfill(step);
+    if (backfill) {
+        const file = backfillFile(backfill.options);
+        return file ? { run: "backfill", file } : { run: "refused", reason: `a backfill step whose options.file is not a file in the migration's directory (${JSON.stringify(backfill.options)})` };
+    }
+    if (step.op === REBUILD_OP) {
+        const o = step.options;
+        const dw = isRecord(o.dualWrite) ? o.dualWrite : undefined;
+        if (typeof o.name !== "string" || typeof o.table !== "string" || !dw) {
+            return { run: "refused", reason: `${REBUILD_OP} for ${step.object} (${step.name}) without its name, table and dualWrite options` };
+        }
+        if (dw.mode === "app") {
+            return {
+                run: "refused",
+                reason: `${REBUILD_OP} for ${step.object} (${step.name}) in app mode: the application has to stop writing to ${o.table} while it is rebuilt, ` +
+                    `which needs the Op's own writes gate; yodel apply runs materialized-view mode only. Run the Op with chant run (migration.json holds its declaration)`,
+            };
+        }
+        if (dw.mode !== "materialized-view" || typeof dw.cutoverColumn !== "string") {
+            return { run: "refused", reason: `${REBUILD_OP} for ${step.object} (${step.name}): dualWrite ${JSON.stringify(dw)} is not one yodel apply runs` };
+        }
+        return { run: "rebuild", options: { name: o.name, table: o.table, dualWrite: dw } };
+    }
+    if (step.op === PG_MIGRATION_OP)
+        return planPgMigration(step);
+    return { run: "refused", reason: `${step.op} for ${step.object} (${step.name}), not SQL: yodel apply does not run that Op` };
+}
+const optional = (o, key, ok) => {
+    const v = o[key];
+    if (v === undefined)
+        return undefined;
+    return ok(v) ? v : null;
+};
+const isString = (v) => typeof v === "string" && v !== "";
+const isPositiveInt = (v) => typeof v === "number" && Number.isInteger(v) && v > 0;
+const isLag = (v) => v === false || (isRecord(v) && Object.values(v).every((x) => typeof x === "string"));
+function planPgMigration(step) {
+    const o = step.options;
+    const bad = (what) => ({ run: "refused", reason: `${PG_MIGRATION_OP} for ${step.object} (${step.name}): ${what}` });
+    if (!isString(o.name) || !isString(o.table) || !isString(o.column))
+        return bad("without its name, table and column options");
+    const using = optional(o, "using", isString);
+    const retain = optional(o, "retain", isString);
+    const batchSize = optional(o, "batchSize", isPositiveInt);
+    const lockTimeoutMs = optional(o, "lockTimeoutMs", isPositiveInt);
+    const statementTimeoutMs = optional(o, "statementTimeoutMs", isPositiveInt);
+    const replicationLag = optional(o, "replicationLag", isLag);
+    for (const [k, v] of Object.entries({ using, retain, batchSize, lockTimeoutMs, statementTimeoutMs, replicationLag })) {
+        if (v === null)
+            return bad(`options.${k} is ${JSON.stringify(o[k])}, which is not one it takes`);
+    }
+    return {
+        run: "pgMigration",
+        options: {
+            name: o.name,
+            table: o.table,
+            column: o.column,
+            ...(using ? { using } : {}),
+            ...(retain ? { retain } : {}),
+            ...(batchSize ? { batchSize } : {}),
+            ...(lockTimeoutMs ? { lockTimeoutMs } : {}),
+            ...(statementTimeoutMs ? { statementTimeoutMs } : {}),
+            ...(replicationLag !== undefined && replicationLag !== null ? { replicationLag } : {}),
+        },
+    };
+}
+/** One line naming a step, for logs and refusals. */
+export function describeStep(step) {
+    if (step.kind === "statement")
+        return `${step.rule} ${step.class}, ${step.name}`;
+    if (step.kind === "manual")
+        return `manual step for ${step.object} (${step.name})`;
+    const backfill = asBackfill(step);
+    if (backfill)
+        return `backfill ${backfill.options.file}`;
+    return `${step.op} for ${step.object} (${step.name})`;
+}
+/**
+ * The hash a step's history rows record: for a statement, its SQL's (the
+ * history's `statementSha`); for an Op step, its canonical JSON and, for a
+ * backfill, the text of the module it runs. A step that ran and has since
+ * changed is how a part-way migration's edit is caught.
+ */
+export function stepSha(step, files) {
+    const hash = createHash("sha256");
+    if (step.kind === "statement")
+        return `sha256:${hash.update(step.sql, "utf8").digest("hex")}`;
+    hash.update(JSON.stringify(sortKeys(step)), "utf8");
+    const backfill = asBackfill(step);
+    if (backfill) {
+        const file = backfill.options.file;
+        const text = files?.extra?.[file];
+        hash.update(`\n${file} ${text === undefined ? "missing" : String(Buffer.byteLength(normalizeLineEndings(text), "utf8"))}\n${normalizeLineEndings(text ?? "")}`, "utf8");
+    }
+    return `sha256:${hash.digest("hex")}`;
+}
+//# sourceMappingURL=kinds.js.map

package/dist/steps/kinds.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"kinds.js","sourceRoot":"","sources":["../../src/steps/kinds.ts"],"names":[],"mappings":"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"}

package/dist/steps/postgres-migration.d.ts

@@ -0,0 +1,95 @@
+/**
+ * A `PostgresMigrationOp` step: a Postgres column rename (SQLPG205) or type
+ * change across kinds (SQLPG208), which `yodel new` writes as a step since
+ * Postgres cannot make it in place without breaking readers, run inside the
+ * migration as chant's expand-and-contract Op.
+ *
+ * The Op is chant's own (`PostgresMigrationOp` from the sql lexicon), built
+ * from the step's options with the apply's environment, and run by chant's
+ * local executor with the lexicon's activities, as `ClickHouseRebuildOp` is
+ * (`./rebuild.ts`):
+ *
+ *   Plan, Expand, Dual write, Backfill, Carry over, Verify, Switch, Retain, Contract
+ *
+ * What differs from `chant run` of the Op:
+ *
+ * - The declaration is the migration's recorded schema (`migration.json`'s
+ *   `schema`), written to a temporary build file, not a fresh `chant build`.
+ * - Its two gates (before the switch, before the contract) are left out. The
+ *   approval is the migration's: the step and its options are in the
+ *   migration's checksum, so in the plan digest the migrations Op's gate
+ *   approved. The verification still runs before the switch, and a
+ *   difference (a row whose new column is not the expression over the old,
+ *   a NULL where NOT NULL is declared) fails the step with nothing switched.
+ * - The old column's retention is the step's `options.retain` when it sets
+ *   one, else none (`0s`): the contract drops the old column (and a rename's
+ *   trigger) in the same run, right after the switch, as the migration's
+ *   recorded schema says it is gone. A step that sets `retain` keeps the old
+ *   column that long; the step succeeds with it kept, its note says until
+ *   when, and dropping it after the date is `chant run` of the Op's
+ *   declaration (in `migration.json`), whose contract is convergent.
+ * - Its onFailure (which drops what the expand added) is left out, so a step
+ *   that failed or was stopped resumes on the next `yodel apply`. Every
+ *   phase of the Op re-reads the server and does what is left of it: the
+ *   expand finds the new column there and adds nothing, the dual write finds
+ *   its trigger, the backfill skips every batch whose receipt is in
+ *   `<schema>.__chant_receipts` (each receipt commits with its batch, so a
+ *   batch is never filled twice), the carry over builds only the indexes and
+ *   constraints not yet built (an INVALID one it left is built again), the
+ *   verification runs again over every row, and a switch that already ran is
+ *   not run again. To start over instead, drop the new column, its trigger
+ *   and function (chant's working objects, named in their comments).
+ */
+import type { OpConfig, PhaseDefinition } from "@intentius/chant/op/types";
+import type { ActivityFn } from "@intentius/chant/op/activity-registry";
+import type { StepRecord } from "@intentius/chant/op/local-executor";
+import type { PgMigrationOptions } from "./kinds.js";
+import { type RunOpOptions } from "./run.js";
+/** The retention a step runs with when its options set none: the contract runs in the same apply. */
+export declare const STEP_RETAIN = "0s";
+/** `PostgresMigrationOp`'s phases as a step runs them: no gates, no onFailure. */
+export declare function pgStepPhases(config: OpConfig): PhaseDefinition[];
+/** The Op a step runs. `buildPath` is the recorded schema's file; `projectDir` holds chant.config.ts. */
+export declare function pgMigrationOpConfig(options: PgMigrationOptions, ctx: {
+    environment: string;
+    projectDir: string;
+    buildPath: string;
+    lockTimeoutMs?: number | undefined;
+}): Promise<OpConfig>;
+export interface PgMigrationSummary {
+    op: "PostgresMigrationOp";
+    table: string;
+    column: string;
+    /** The Plan's state when the step began: `migrate`, or `switched` / `done` when an earlier run got that far. */
+    state?: string;
+    change?: string;
+    /** Backfill batches filled in this run, and skipped (their receipt was there). */
+    filled?: number;
+    skipped?: number;
+    backfilledRows?: number;
+    /** Indexes and constraints built on the new column in this run. */
+    carried?: number;
+    verifiedRows?: number;
+    switched?: boolean;
+    oldColumn?: string;
+    retainUntil?: string;
+    /** The contract dropped the old column. */
+    dropped?: boolean;
+}
+/** Folds one migration activity's result into the summary. */
+export declare function summarizePg(summary: PgMigrationSummary, fn: string, result: unknown): void;
+export interface RunPgMigrationOptions extends Omit<RunOpOptions, "activities" | "cwd"> {
+    projectDir: string;
+    /** The migration's recorded schema: the `chant build` output after it. */
+    schema: unknown;
+    /** The environment's lock timeout, used when the step's options set none. */
+    lockTimeoutMs?: number | undefined;
+    /** Activities to use in place of the lexicon's, for a test. */
+    activities?: Record<string, ActivityFn>;
+    log?: (line: string) => void;
+}
+/** Runs a `PostgresMigrationOp` step to the end. The summary fills in as the activities return, so a failure still says how far it got. */
+export declare function runPgMigration(options: PgMigrationOptions, run: RunPgMigrationOptions, summary?: PgMigrationSummary): Promise<{
+    summary: PgMigrationSummary;
+    records: StepRecord[];
+}>;

package/dist/steps/postgres-migration.js

@@ -0,0 +1,149 @@
+/**
+ * A `PostgresMigrationOp` step: a Postgres column rename (SQLPG205) or type
+ * change across kinds (SQLPG208), which `yodel new` writes as a step since
+ * Postgres cannot make it in place without breaking readers, run inside the
+ * migration as chant's expand-and-contract Op.
+ *
+ * The Op is chant's own (`PostgresMigrationOp` from the sql lexicon), built
+ * from the step's options with the apply's environment, and run by chant's
+ * local executor with the lexicon's activities, as `ClickHouseRebuildOp` is
+ * (`./rebuild.ts`):
+ *
+ *   Plan, Expand, Dual write, Backfill, Carry over, Verify, Switch, Retain, Contract
+ *
+ * What differs from `chant run` of the Op:
+ *
+ * - The declaration is the migration's recorded schema (`migration.json`'s
+ *   `schema`), written to a temporary build file, not a fresh `chant build`.
+ * - Its two gates (before the switch, before the contract) are left out. The
+ *   approval is the migration's: the step and its options are in the
+ *   migration's checksum, so in the plan digest the migrations Op's gate
+ *   approved. The verification still runs before the switch, and a
+ *   difference (a row whose new column is not the expression over the old,
+ *   a NULL where NOT NULL is declared) fails the step with nothing switched.
+ * - The old column's retention is the step's `options.retain` when it sets
+ *   one, else none (`0s`): the contract drops the old column (and a rename's
+ *   trigger) in the same run, right after the switch, as the migration's
+ *   recorded schema says it is gone. A step that sets `retain` keeps the old
+ *   column that long; the step succeeds with it kept, its note says until
+ *   when, and dropping it after the date is `chant run` of the Op's
+ *   declaration (in `migration.json`), whose contract is convergent.
+ * - Its onFailure (which drops what the expand added) is left out, so a step
+ *   that failed or was stopped resumes on the next `yodel apply`. Every
+ *   phase of the Op re-reads the server and does what is left of it: the
+ *   expand finds the new column there and adds nothing, the dual write finds
+ *   its trigger, the backfill skips every batch whose receipt is in
+ *   `<schema>.__chant_receipts` (each receipt commits with its batch, so a
+ *   batch is never filled twice), the carry over builds only the indexes and
+ *   constraints not yet built (an INVALID one it left is built again), the
+ *   verification runs again over every row, and a switch that already ran is
+ *   not run again. To start over instead, drop the new column, its trigger
+ *   and function (chant's working objects, named in their comments).
+ */
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { runOp, StepOpFailed } from "./run.js";
+/** The retention a step runs with when its options set none: the contract runs in the same apply. */
+export const STEP_RETAIN = "0s";
+/** `PostgresMigrationOp`'s phases as a step runs them: no gates, no onFailure. */
+export function pgStepPhases(config) {
+    return config.phases.map((p) => ({ ...p, steps: p.steps.filter((s) => s.kind !== "gate") })).filter((p) => p.steps.length > 0);
+}
+/** The Op a step runs. `buildPath` is the recorded schema's file; `projectDir` holds chant.config.ts. */
+export async function pgMigrationOpConfig(options, ctx) {
+    const { PostgresMigrationOp } = await import("@intentius/chant-lexicon-sql/postgres/migrate/op");
+    const lockTimeoutMs = options.lockTimeoutMs ?? ctx.lockTimeoutMs;
+    const { op } = PostgresMigrationOp({
+        name: options.name,
+        env: ctx.environment,
+        table: options.table,
+        column: options.column,
+        ...(options.using !== undefined ? { using: options.using } : {}),
+        retain: options.retain ?? STEP_RETAIN,
+        ...(options.batchSize !== undefined ? { batchSize: options.batchSize } : {}),
+        ...(options.replicationLag !== undefined ? { replicationLag: options.replicationLag } : {}),
+        ...(lockTimeoutMs !== undefined ? { lockTimeoutMs } : {}),
+        ...(options.statementTimeoutMs !== undefined ? { statementTimeoutMs: options.statementTimeoutMs } : {}),
+        build: false,
+        output: ctx.buildPath,
+        path: ctx.projectDir,
+    });
+    const full = op.props;
+    const rest = { ...full, phases: pgStepPhases(full) };
+    delete rest.onFailure;
+    return rest;
+}
+/** The migration activities whose results the history's summary keeps. */
+const SUMMARIZED = ["postgresMigrationPlan", "postgresMigrationBackfill", "postgresMigrationCarry", "postgresMigrationVerify", "postgresMigrationSwitch", "postgresMigrationContract"];
+const num = (v) => (typeof v === "number" ? v : undefined);
+const str = (v) => (typeof v === "string" ? v : undefined);
+/** Folds one migration activity's result into the summary. */
+export function summarizePg(summary, fn, result) {
+    const r = (typeof result === "object" && result !== null ? result : {});
+    const put = (k, v) => {
+        if (v !== undefined)
+            summary[k] = v;
+    };
+    if (fn === "postgresMigrationPlan") {
+        put("state", str(r.state));
+        put("change", str(r.change));
+    }
+    if (fn === "postgresMigrationBackfill") {
+        put("filled", num(r.filled));
+        put("skipped", num(r.skipped));
+        put("backfilledRows", num(r.rows));
+    }
+    if (fn === "postgresMigrationCarry")
+        put("carried", num(r.built));
+    if (fn === "postgresMigrationVerify")
+        put("verifiedRows", num(r.rows));
+    if (fn === "postgresMigrationSwitch") {
+        put("switched", typeof r.switched === "boolean" ? r.switched : undefined);
+        put("oldColumn", str(r.oldColumn));
+        put("retainUntil", str(r.retainUntil));
+    }
+    if (fn === "postgresMigrationContract") {
+        put("dropped", typeof r.dropped === "boolean" ? r.dropped : undefined);
+        put("oldColumn", str(r.oldColumn));
+        put("retainUntil", str(r.retainUntil));
+    }
+}
+/** Runs a `PostgresMigrationOp` step to the end. The summary fills in as the activities return, so a failure still says how far it got. */
+export async function runPgMigration(options, run, summary = { op: "PostgresMigrationOp", table: options.table, column: options.column }) {
+    const dir = mkdtempSync(join(tmpdir(), "yodel-pg-migration-"));
+    try {
+        const buildPath = join(dir, "schema.json");
+        writeFileSync(buildPath, JSON.stringify(run.schema));
+        const config = await pgMigrationOpConfig(options, { environment: run.environment, projectDir: run.projectDir, buildPath, lockTimeoutMs: run.lockTimeoutMs });
+        const lexicon = run.activities ?? (await import("@intentius/chant-lexicon-sql/op/activities"));
+        const wrapped = {};
+        for (const fn of SUMMARIZED) {
+            const inner = lexicon[fn];
+            if (!inner)
+                continue;
+            wrapped[fn] = async (args, signal) => {
+                const result = await inner(args, signal);
+                summarizePg(summary, fn, result);
+                return result;
+            };
+        }
+        const records = await runOp(config, {
+            cwd: run.projectDir,
+            environment: run.environment,
+            activities: { ...(run.activities ?? {}), ...wrapped },
+            ...(run.base ? { base: run.base } : {}),
+            ...(run.signal ? { signal: run.signal } : {}),
+            ...(run.onRecord ? { onRecord: run.onRecord } : {}),
+        }).catch((e) => {
+            if (e instanceof StepOpFailed)
+                e.summary = summary;
+            throw e;
+        });
+        return { summary, records };
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+}
+//# sourceMappingURL=postgres-migration.js.map

package/dist/steps/postgres-migration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"postgres-migration.js","sourceRoot":"","sources":["../../src/steps/postgres-migration.ts"],"names":[],"mappings":"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"}

package/dist/steps/rebuild.d.ts

@@ -0,0 +1,97 @@
+/**
+ * A `ClickHouseRebuildOp` step: the change ClickHouse cannot make with
+ * `ALTER` (a sort key, an engine, a key column's type or name), run inside
+ * the migration as chant's rebuild Op.
+ *
+ * The Op is chant's own (`ClickHouseRebuildOp` from the sql lexicon), built
+ * from the step's options with the apply's environment, and run by chant's
+ * local executor with the lexicon's rebuild activities:
+ *
+ *   Plan, Create, Dual write (materialized-view mode), Backfill, Verify, Swap, Retain
+ *
+ * Three things differ from running the Op with `chant run`:
+ *
+ * - The declaration is the migration's recorded schema (`migration.json`'s
+ *   `schema`), written to a temporary build file, not a fresh `chant build`:
+ *   the table is rebuilt as this migration declares it, however far the
+ *   declared schema has moved on since.
+ * - It is built with `gates: "outer"`: the swap gate's approval is the
+ *   migration's (the step's options are in the migration's checksum, which
+ *   is in the plan digest the migrations Op's gate approved), so the Op has
+ *   no gate and no Drop phase. The verification still runs before the swap,
+ *   and a difference fails the step with nothing swapped. The old table is
+ *   kept, `<table>__chant_old`, until its retention date (7 days).
+ * - It is built with `onFailure: "keep"`, so a step that failed or was
+ *   killed part way keeps `<table>__chant_new` and `<table>__chant_dual` and
+ *   resumes from the backfill's receipts on the next `yodel apply`: every
+ *   partition with a receipt is skipped. To start the rebuild over instead,
+ *   drop those two tables (a refusal names them).
+ *
+ * The activities render their DDL for the topology chant resolves from
+ * `sql.profiles.<env>.topology`. When the environment's topology comes from
+ * elsewhere (`yodel.config.ts`, or `YODEL_TOPOLOGY`, #9), the step hands
+ * every rebuild activity chant's config with that topology set on the
+ * profile ({@link rebuildChantConfig}), so the rebuild renders for the same
+ * topology as the migration's statements. On a cluster of more than one
+ * shard the Op copies and verifies every shard; it needs the `{shard}` macro
+ * on each server, distinct per shard, and refuses the cluster without it.
+ */
+import type { OpConfig } from "@intentius/chant/op/types";
+import type { ActivityFn } from "@intentius/chant/op/activity-registry";
+import type { StepRecord } from "@intentius/chant/op/local-executor";
+import type { Topology } from "@intentius/chant-lexicon-sql/clickhouse/topology";
+import type { RebuildOptions } from "./kinds.js";
+import { type ProjectConfig } from "../project.js";
+import { type RunOpOptions } from "./run.js";
+/** `config` with `sql.profiles.<environment>.topology` set to `topology`. Pure; `config` is not changed. */
+export declare function withProfileTopology(config: ProjectConfig, environment: string, topology: Topology): ProjectConfig;
+/**
+ * The chant config a rebuild step's activities bind with: the project's,
+ * with the environment's resolved topology on its profile when chant would
+ * not find it there itself. `undefined` when chant's own resolution already
+ * gives the same topology (set in the profile, or no topology anywhere).
+ */
+export declare function rebuildChantConfig(projectDir: string, environment: string, env?: NodeJS.ProcessEnv): Promise<ProjectConfig | undefined>;
+/** The Op a rebuild step runs. `buildPath` is the recorded schema's file; `projectDir` holds chant.config.ts. */
+export declare function rebuildOpConfig(options: RebuildOptions, ctx: {
+    environment: string;
+    projectDir: string;
+    buildPath: string;
+}): Promise<OpConfig>;
+export interface RebuildSummary {
+    op: "ClickHouseRebuildOp";
+    table: string;
+    /** The Plan's state when the step began: `rebuild`, or `swapped` / `done` when an earlier run got that far. */
+    state?: string;
+    partitions?: number;
+    /** Partitions copied in this run. */
+    copied?: number;
+    /** Partitions skipped: their receipt matched (copied by an earlier run). */
+    skipped?: number;
+    /** Partitions found partly copied and cleared before copying again. */
+    cleared?: number;
+    /** Rows copied by both the backfill and the dual-write view, deleted and copied again. */
+    repaired?: number;
+    /** Rows compared in the whole table, old against new. */
+    verifiedRows?: number;
+    swapped?: boolean;
+    oldTable?: string;
+    retainUntil?: string;
+}
+/** Folds one rebuild activity's result into the summary. */
+export declare function summarize(summary: RebuildSummary, fn: string, result: unknown): void;
+export interface RunRebuildOptions extends Omit<RunOpOptions, "activities" | "cwd"> {
+    projectDir: string;
+    /** The migration's recorded schema: the `chant build` output after it. */
+    schema: unknown;
+    /** Activities to use in place of the lexicon's, for a test. */
+    activities?: Record<string, ActivityFn>;
+    log?: (line: string) => void;
+    /** The chant config the rebuild activities bind with (see {@link rebuildChantConfig}). Default: they load chant.config.ts. */
+    config?: ProjectConfig | undefined;
+}
+/** Runs a rebuild step to the end. The summary is filled in as the activities return, so a failure still says how far it got. */
+export declare function runRebuild(options: RebuildOptions, run: RunRebuildOptions, summary?: RebuildSummary): Promise<{
+    summary: RebuildSummary;
+    records: StepRecord[];
+}>;