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

package/dist/clickhouse/plan/rules.d.ts

@@ -0,0 +1,60 @@
+/**
+ * The change classifier's rules (#3046 question 3): every way a declared
+ * ClickHouse object can change, the class of change it is on the server, and
+ * the `ALTER` restriction behind the class, cited.
+ *
+ * Three classes:
+ *
+ * - `metadata`: the server records the change and touches no existing data
+ *   (a new column reads its default from old parts; a new index covers new
+ *   parts until `MATERIALIZE INDEX`).
+ * - `rewrite`: the change is a mutation that rewrites existing parts in the
+ *   background (`system.mutations`), with no rollback.
+ * - `rebuild`: ClickHouse cannot make the change to the table it has; the data
+ *   has to be copied into a new table. A plan refuses to make one in place.
+ *
+ * Creating and dropping whole objects are classed `create` and `drop`.
+ */
+import { type ChangeClasses, type ClassifierRule as SqlClassifierRule } from "../../core/classifier.js";
+export type ChangeClass = "metadata" | "rewrite" | "rebuild" | "create" | "drop";
+/** A ClickHouse rule: the shared core's rule shape over these classes, citing a clickhouse.com page. */
+export type ClassifierRule = SqlClassifierRule<ChangeClass>;
+/** The classes as data: report order and labels, and what each costs for `classifyDisruption()`. */
+export declare const CHANGE_CLASSES: ChangeClasses<ChangeClass>;
+export declare const CLASSIFIER_RULES: {
+    readonly SQLCH200: ClassifierRule;
+    readonly SQLCH201: ClassifierRule;
+    readonly SQLCH202: ClassifierRule;
+    readonly SQLCH203: ClassifierRule;
+    readonly SQLCH204: ClassifierRule;
+    readonly SQLCH205: ClassifierRule;
+    readonly SQLCH206: ClassifierRule;
+    readonly SQLCH207: ClassifierRule;
+    readonly SQLCH208: ClassifierRule;
+    readonly SQLCH209: ClassifierRule;
+    readonly SQLCH210: ClassifierRule;
+    readonly SQLCH211: ClassifierRule;
+    readonly SQLCH212: ClassifierRule;
+    readonly SQLCH213: ClassifierRule;
+    readonly SQLCH214: ClassifierRule;
+    readonly SQLCH215: ClassifierRule;
+    readonly SQLCH216: ClassifierRule;
+    readonly SQLCH217: ClassifierRule;
+    readonly SQLCH218: ClassifierRule;
+    readonly SQLCH220: ClassifierRule;
+    readonly SQLCH221: ClassifierRule;
+    readonly SQLCH222: ClassifierRule;
+    readonly SQLCH223: ClassifierRule;
+    readonly SQLCH224: ClassifierRule;
+    readonly SQLCH230: ClassifierRule;
+    readonly SQLCH231: ClassifierRule;
+    readonly SQLCH232: ClassifierRule;
+    readonly SQLCH240: ClassifierRule;
+    readonly SQLCH241: ClassifierRule;
+    readonly SQLCH242: ClassifierRule;
+    readonly SQLCH243: ClassifierRule;
+    readonly SQLCH244: ClassifierRule;
+    readonly SQLCH250: ClassifierRule;
+};
+export type ClassifierRuleId = keyof typeof CLASSIFIER_RULES;
+//# sourceMappingURL=rules.d.ts.map

package/dist/clickhouse/plan/rules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rules.d.ts","sourceRoot":"","sources":["../../../src/clickhouse/plan/rules.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAkB,KAAK,aAAa,EAAE,KAAK,cAAc,IAAI,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAErH,MAAM,MAAM,WAAW,GAAG,UAAU,GAAG,SAAS,GAAG,SAAS,GAAG,QAAQ,GAAG,MAAM,CAAC;AAEjF,wGAAwG;AACxG,MAAM,MAAM,cAAc,GAAG,iBAAiB,CAAC,WAAW,CAAC,CAAC;AAE5D,oGAAoG;AACpG,eAAO,MAAM,cAAc,EAAE,aAAa,CAAC,WAAW,CAIrD,CAAC;AAMF,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA0MsB,CAAC;AAEpD,MAAM,MAAM,gBAAgB,GAAG,MAAM,OAAO,gBAAgB,CAAC"}

package/dist/clickhouse/plan/schema.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The two sides a diff compares: a build's output (the declarations), or what
+ * a live server reports.
+ */
+import type { SchemaObject } from "./diff.js";
+import type { ClickHouseTarget } from "../live/bind.js";
+/** The objects a `chant build` output holds, keyed by export name. */
+export declare function schemaFromBuildOutput(json: string, defaultDatabase?: string): SchemaObject[];
+export declare function schemaFromBuildFile(path: string, defaultDatabase?: string): SchemaObject[];
+/**
+ * The declared objects re-keyed by `database.name`, the only identity a live
+ * server has. The export name is kept for the report.
+ */
+export declare function keyedByQualifiedName(objects: readonly SchemaObject[]): Array<SchemaObject & {
+    exportName: string;
+}>;
+/**
+ * What the server holds, keyed by `database.name`, limited to the databases
+ * the declarations use (and the target's scope). The `default` database is
+ * left out, as import leaves it out.
+ */
+export declare function schemaFromServer(target: ClickHouseTarget, databases?: ReadonlySet<string>): Promise<SchemaObject[]>;
+//# sourceMappingURL=schema.d.ts.map

package/dist/clickhouse/plan/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../src/clickhouse/plan/schema.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AAC3C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAQrD,sEAAsE;AACtE,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,eAAe,SAAY,GAAG,YAAY,EAAE,CAM/F;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,eAAe,SAAY,GAAG,YAAY,EAAE,CAE7F;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,SAAS,YAAY,EAAE,GAAG,KAAK,CAAC,YAAY,GAAG;IAAE,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC,CAMnH;AAED;;;;GAIG;AACH,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,gBAAgB,EAAE,SAAS,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CASzH"}

package/dist/clickhouse/plan/server-format.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The backstop for normalization against a live server: for each changed
+ * expression the rules leave different, ask the server to format both sides
+ * (`formatQuerySingleLine`, which parses and prints and touches nothing) and
+ * drop the change when they print the same. `a+b*2` and `a + (b * 2)` are one
+ * expression to the server.
+ */
+import { type ClickHouseEndpoint } from "../http.js";
+import type { Change } from "./diff.js";
+/** The changes that remain once the server's formatter has had its say. */
+export declare function dropFormattingOnly(endpoint: ClickHouseEndpoint, changes: Change[]): Promise<Change[]>;
+//# sourceMappingURL=server-format.d.ts.map

package/dist/clickhouse/plan/server-format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-format.d.ts","sourceRoot":"","sources":["../../../src/clickhouse/plan/server-format.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAmB,KAAK,kBAAkB,EAAE,MAAM,SAAS,CAAC;AACnE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAYrC,2EAA2E;AAC3E,wBAAsB,kBAAkB,CAAC,QAAQ,EAAE,kBAAkB,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAgB3G"}

package/dist/clickhouse/rebuild/backfill.d.ts

@@ -0,0 +1,70 @@
+/**
+ * The backfill (#3198): copy the old table into the new one with
+ * `INSERT ... SELECT`, one partition at a time, each partition an effect
+ * with its own receipt.
+ *
+ * Per partition, the cycle core's `effect()` step runs
+ * (concepts/effect-receipts.mdx): read the receipt, skip the copy when it
+ * matches, otherwise copy and write the receipt last, on success only.
+ * `effect()` itself wraps steps declared at build time around one receipt
+ * declared at build time; the partitions are only known when the run reads
+ * the old table, so the cycle runs here, once per partition, over the same
+ * `ReceiptStore` seam (`./receipts.ts`).
+ *
+ * A receipt's expectation is a hash of what the copy is: the table, the new
+ * table's UUID, the partition, the columns copied and the cut-over. A new
+ * table made again, or a new cut-over, makes every receipt stale and the
+ * partitions are copied again into the new table.
+ *
+ * At-least-once is the receipt model's guarantee, and a partition copied
+ * twice would be in the new table twice, so a copy that may have run before
+ * is undone first. A partition with no matching receipt is a partition whose
+ * copy never finished as far as anything recorded; if the new table holds
+ * any of its rows (a run killed between the INSERT and the receipt), they are
+ * deleted, the delete is waited on in `system.mutations`, and the partition
+ * is copied once more. Each copy runs under a query id derived from the new
+ * table and the partition, and any query still running under it (the server
+ * goes on with an INSERT whose client went away) is killed before the
+ * partition is cleared. A backfill interrupted halfway therefore resumes at
+ * the first partition without a receipt, and no row is copied twice.
+ *
+ * In a Replicated database (#3249) a resumed backfill may run on another
+ * replica than the one the copy ran on. The kill is `KILL QUERY ON CLUSTER`
+ * the database's own cluster, so it reaches the replica still running the
+ * copy; before the old table's partitions are listed, and before the new
+ * table's rows are counted, this replica fetches what the others wrote
+ * (`SYSTEM SYNC REPLICA`); and the receipts replicate with the tables
+ * (`./receipts.ts`). Each copy runs with `insert_deduplicate = 0`: a
+ * replicated table remembers the blocks it was given, and a partition copied
+ * again after its rows were cleared would otherwise be dropped as a repeat.
+ *
+ * With a replica down (#3270) the kill goes on without it, and each sync
+ * either finds nothing that replica alone has and returns, or stops the step
+ * naming it (`./replicas.ts`).
+ */
+import { type ClickHouseReceiptStore } from "./receipts.js";
+import { type RebuildObservation } from "./observe.js";
+import { type RebuildRun } from "./steps.js";
+export interface BackfillResult {
+    state: RebuildObservation["state"];
+    /** Partitions of the old table. */
+    partitions: number;
+    /** Copied in this run. */
+    copied: number;
+    /** Skipped: their receipt matched. */
+    skipped: number;
+    /** Partitions this run found partly copied and cleared before copying again. */
+    cleared: number;
+}
+/** The effect a partition's copy is, and its receipt's address suffix. */
+export declare const partitionEffect: (key: string, partition: string) => string;
+/** The receipt's expected value for one partition's copy. */
+export declare function partitionExpectation(o: RebuildObservation, partition: string, cutover: number | undefined): string;
+export interface BackfillDeps {
+    /** The receipt store. Default: the receipts table on the target server. */
+    receipts?: ClickHouseReceiptStore;
+    /** Called after each partition is copied and its receipt written; a test interrupts the backfill here. */
+    afterPartition?: (partition: string) => void | Promise<void>;
+}
+export declare function backfill(run: RebuildRun, deps?: BackfillDeps): Promise<BackfillResult>;
+//# sourceMappingURL=backfill.d.ts.map

package/dist/clickhouse/rebuild/backfill.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backfill.d.ts","sourceRoot":"","sources":["../../../src/clickhouse/rebuild/backfill.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAKH,OAAO,EAA0C,KAAK,sBAAsB,EAAE,MAAM,YAAY,CAAC;AACjG,OAAO,EAAkB,KAAK,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAGpE,OAAO,EAAkE,KAAK,UAAU,EAAE,MAAM,SAAS,CAAC;AAE1G,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,kBAAkB,CAAC,OAAO,CAAC,CAAC;IACnC,mCAAmC;IACnC,UAAU,EAAE,MAAM,CAAC;IACnB,0BAA0B;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,sCAAsC;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,gFAAgF;IAChF,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,0EAA0E;AAC1E,eAAO,MAAM,eAAe,GAAI,KAAK,MAAM,EAAE,WAAW,MAAM,KAAG,MAAuC,CAAC;AAEzG,6DAA6D;AAC7D,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,kBAAkB,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CASlH;AAED,MAAM,WAAW,YAAY;IAC3B,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,sBAAsB,CAAC;IAClC,0GAA0G;IAC1G,cAAc,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9D;AAED,wBAAsB,QAAQ,CAAC,GAAG,EAAE,UAAU,EAAE,IAAI,GAAE,YAAiB,GAAG,OAAO,CAAC,cAAc,CAAC,CAmFhG"}

package/dist/clickhouse/rebuild/observe.d.ts

@@ -0,0 +1,157 @@
+/**
+ * The rebuild migration's view of the server (#3198): which table is being
+ * rebuilt, how far the rebuild has got, and what it will do.
+ *
+ * Every step of the Op re-observes from here rather than trusting what an
+ * earlier run or step said, so the Op converges: run it again after a crash,
+ * a gate or an approval, and each step finds its work done or still to do.
+ * The progress is read off the server's own objects:
+ *
+ * - the table being rebuilt, `db.t`, as declared and as the server has it;
+ * - `db.t__chant_new`, the new table being filled (`role=new` in its comment);
+ * - `db.t__chant_dual`, the dual-write materialized view (`role=dual`);
+ * - `db.t__chant_old`, the old table kept after the swap (`role=old`, with
+ *   `retain-until`).
+ *
+ * Each working object carries chant's ownership trailer plus
+ * `rebuild=<db.t>` and its role (`../ownership.ts`), so it is chant's and
+ * this rebuild's, and schema reads leave it out.
+ *
+ * States:
+ *
+ * - `rebuild`: the declaration differs from the server by at least one
+ *   rebuild-class change, and the old table has not been swapped out yet.
+ * - `swapped`: the swap ran; the old table is retained until its date.
+ * - `done`: the server holds the declaration and nothing of the rebuild is
+ *   left.
+ *
+ * Anything else is refused with a {@link RebuildRefusal}: a database that is
+ * neither Atomic nor Replicated, a table that is not there, a change that is
+ * not a rebuild, a working object chant did not make.
+ *
+ * A Replicated database (#3249) is Atomic on every replica, with its DDL run
+ * on each through Keeper, so the same EXCHANGE swaps the table everywhere.
+ * Its tables have to be `Replicated*MergeTree` on both sides of the rebuild:
+ * a plain MergeTree there keeps a different set of rows on each replica, and
+ * a copy run on one replica would fill the new table with that replica's rows
+ * alone.
+ */
+import type { OwnershipMarker } from "@intentius/chant/ownership";
+import type { ClickHouseTarget } from "../live/bind.js";
+import { type CanonicalObject } from "../plan/normalize.js";
+import { type Change } from "../plan/diff.js";
+import { ident, type DeclaredObject } from "../apply/statements.js";
+/** How the new table keeps up with writes to the old one while it is filled. */
+export type DualWrite = {
+    /**
+     * A materialized view on the old table writes every row whose
+     * `cutoverColumn` is at or after the cut-over into the new table; the
+     * backfill copies the rows before it. The cut-over is the server's time
+     * when the view is made plus `cutoverDelay` (default `1m`), and the
+     * backfill starts once it has passed. The column must be a time
+     * (`Date`, `DateTime`, `DateTime64`) that rows arrive in order of, give
+     * or take the delay; a row that arrives later than that is caught by
+     * the verification, which then fails the run.
+     */
+    mode: "materialized-view";
+    cutoverColumn: string;
+    cutoverDelay?: string;
+} | {
+    /**
+     * The application stops writing to the old table (pauses, or buffers)
+     * and a person says so at a gate before the backfill. The backfill then
+     * copies every row, and writes resume against the table's own name
+     * after the swap.
+     */
+    mode: "app";
+};
+/** A refusal: the rebuild cannot start, or cannot go on, for a reason a person has to act on. */
+export declare class RebuildRefusal extends Error {
+    constructor(message: string);
+}
+/** The table's name and its working objects' names. */
+export interface RebuildNames {
+    /** `db.t`, the rebuild's identity. */
+    key: string;
+    database: string;
+    name: string;
+    newName: string;
+    dualName: string;
+    oldName: string;
+    /** Quoted, qualified: `` `db`.`t` `` and so on. */
+    table: string;
+    newTable: string;
+    dualView: string;
+    oldTable: string;
+}
+export declare function rebuildNames(database: string, name: string): RebuildNames;
+/** One object on the server, as `system.tables` reports it. */
+export interface ServerObject {
+    name: string;
+    uuid: string;
+    engine: string;
+    comment: string;
+    partitionKey: string;
+    /** The working-object pairs in its comment's trailer, if any. */
+    pairs?: Map<string, string>;
+}
+/** A column copied from the old table into the new one. */
+export interface CopiedColumn {
+    /** Its name in the new table. */
+    name: string;
+    /** Its name in the old table: the same, or the `-- previously:` name. */
+    source: string;
+}
+export interface RebuildObservation {
+    state: "rebuild" | "swapped" | "done";
+    names: RebuildNames;
+    declared: DeclaredObject;
+    /** The table under its own name. */
+    live: ServerObject;
+    /** Its definition on the server, as the classifier compares it. */
+    liveCanonical: CanonicalObject;
+    /** The classified changes from the server's table to the declaration. */
+    changes: Change[];
+    newTable?: ServerObject;
+    dual?: ServerObject;
+    old?: ServerObject;
+    /** After the EXCHANGE and before the swap finished: the old table, still under the new table's name. */
+    exchangedOld?: ServerObject;
+    /** The swap's EXCHANGE ran and the swap has not finished: the table's own name holds the new table. */
+    exchanged: boolean;
+    /** The columns the backfill copies, and the verification compares. */
+    copied: CopiedColumn[];
+    /**
+     * The database is Replicated: every replica runs its DDL, the tables'
+     * rows replicate through Keeper, and a step reading rows first waits for
+     * this replica to catch up (`SYSTEM SYNC REPLICA`).
+     */
+    replicated: boolean;
+}
+/** The declared table with the given key (`db.t`), or a refusal naming what is declared. */
+export declare function declaredTable(declared: readonly DeclaredObject[], key: string): DeclaredObject;
+/**
+ * The columns the backfill copies: every declared column the old table has
+ * under its name or its `-- previously:` name, except a `MATERIALIZED`,
+ * `ALIAS` or `EPHEMERAL` one, which the new table computes itself.
+ */
+export declare function copiedColumns(declared: CanonicalObject, live: CanonicalObject): CopiedColumn[];
+/** A canonical definition without what names it, for comparing and digesting by role. */
+export declare function anonymous(c: CanonicalObject): Record<string, unknown>;
+/** The definition `SHOW CREATE` prints, less chant's trailer, canonical. */
+export declare function showCreate(target: ClickHouseTarget, qualified: string): Promise<CanonicalObject>;
+/** The classified changes from one definition to another, compared by role, with server formatting differences dropped. */
+export declare function changesBetween(target: ClickHouseTarget, key: string, from: CanonicalObject, to: CanonicalObject): Promise<Change[]>;
+/** Observe the rebuild of the declared table on the server. */
+export declare function observeRebuild(target: ClickHouseTarget, declared: DeclaredObject, marker: OwnershipMarker | undefined): Promise<RebuildObservation>;
+/**
+ * What the rebuild will do, independent of how far it has got: the changes,
+ * the definitions on both sides, the columns copied and how writes are kept
+ * up. The Plan phase publishes its digest; the gate binds a digest of this
+ * plus the verification.
+ */
+export declare function rebuildPlanSubject(o: RebuildObservation, dualWrite: DualWrite): Record<string, unknown>;
+export declare const rebuildPlanDigest: (o: RebuildObservation, dualWrite: DualWrite) => string;
+/** `ident` re-exported for the steps, which quote column names. */
+export { ident };
+//# sourceMappingURL=observe.d.ts.map

package/dist/clickhouse/rebuild/observe.d.ts.map

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

package/dist/clickhouse/rebuild/op.d.ts

@@ -0,0 +1,108 @@
+/**
+ * `ClickHouseRebuildOp` (#3198): the change ClickHouse cannot make with
+ * `ALTER` (a sorting key, a primary key, a partition key, an engine, a key
+ * column's type), run as a gated composite Op.
+ *
+ *     export const { op } = ClickHouseRebuildOp({
+ *       name: "rebuild-shop-events",
+ *       env: "prod",
+ *       table: "shop.events",
+ *       dualWrite: { mode: "materialized-view", cutoverColumn: "ts" },
+ *     });
+ *
+ * | Phase | Step |
+ * |---|---|
+ * | Build | `chant build` (`build: false` skips it) |
+ * | Plan | classify the table's change against the server; refuse what is not a rebuild |
+ * | Create | the new table, `t__chant_new`, from the declaration |
+ * | Dual write | a materialized view from the old table to the new one, or a gate for the app to stop writing |
+ * | Backfill | `INSERT ... SELECT` per partition, each with a receipt |
+ * | Verify | row counts and checksums per partition |
+ * | Approve | a gate bound to the plan and the verification |
+ * | Swap | `EXCHANGE TABLES`, then recreate the materialized views that read the table |
+ * | Retain | the old table, `t__chant_old`, until `retain` has passed |
+ * | Approve drop | a gate bound to that old table |
+ * | Drop | the old table, once its date has passed |
+ * | onFailure | drop the new table and the dual-write view |
+ *
+ * Run it until it is done: each run goes as far as the next gate. Every step
+ * re-reads the server, so a run after a gate, a crash or an approval picks up
+ * where the last stopped. A run killed during the backfill (Ctrl-C, a lost
+ * machine) is not a failure, runs no onFailure, and the next run resumes the
+ * backfill from its receipts; a step that fails runs onFailure, and the next
+ * run starts again from a new table.
+ */
+import { type GateApproval } from "@intentius/chant/op";
+import type { OpResource } from "@intentius/chant/op";
+import type { DualWrite } from "./observe.js";
+export interface ClickHouseRebuildOpConfig {
+    /** Op name (kebab-case). */
+    name: string;
+    /** The chant environment: selects `sql.profiles.<env>`. */
+    env: string;
+    /** The table to rebuild, `database.name` as the server knows it (or its export name). */
+    table: string;
+    /** How writes reach the new table while it is filled. */
+    dualWrite: DualWrite;
+    /** The build output the declaration is read from. Default: `dist/schema.json`. */
+    output?: string;
+    /** Project directory to build. Default: `.`. */
+    path?: string;
+    /** Run `chant build` first (the project's `build` script). Default: true. */
+    build?: boolean;
+    /** How long the old table is kept after the swap, as a duration (`7d`, `36h`). Default: `7d`. */
+    retain?: string;
+    /** The gate before the swap. Default name `approve-<name>`. */
+    gate?: {
+        gate?: string;
+        timeout?: string;
+        description?: string;
+        /** Quorum, roles and a policy (#2508). With a policy, the verification's counts are added to its context. */
+        approval?: GateApproval;
+    };
+    /** The gate before the old table is dropped. Default name `approve-<name>-drop`. */
+    dropGate?: {
+        gate?: string;
+        timeout?: string;
+        description?: string;
+    };
+    /** App mode: the gate the application's write stop is confirmed at. Default name `<name>-writes-stopped`. */
+    writesGate?: {
+        gate?: string;
+        timeout?: string;
+        description?: string;
+    };
+    /** One attempt of the backfill step. Default: `6h`, the longest a step may run. */
+    backfillTimeout?: string;
+    /** How long to wait for one table's mutations. Default: `10m`. */
+    mutationTimeout?: string;
+    /**
+     * In a Replicated database, how long a step that reads rows waits for the
+     * replica it talks to to fetch what the others wrote, before it stops
+     * naming a replica that is down and holds parts no other has. Each attempt
+     * of the step waits this long. Default: `2m`.
+     */
+    replicaTimeout?: string;
+    /** Ownership stack. Default: `ownership.stack` in `chant.config.ts`. */
+    stack?: string;
+    /** Ownership env. Default: `ownership.env` in `chant.config.ts`. */
+    ownershipEnv?: string;
+}
+export interface ClickHouseRebuildOpResources {
+    op: InstanceType<typeof OpResource>;
+}
+/** The arguments every rebuild activity takes. */
+export interface ClickHouseRebuildArgs {
+    table: string;
+    buildPath: string;
+    environment?: string;
+    dualWrite: DualWrite;
+    retain?: string;
+    mutationTimeout?: string;
+    replicaTimeout?: string;
+    stack?: string;
+    ownershipEnv?: string;
+    cwd?: string;
+}
+export declare function ClickHouseRebuildOp(config: ClickHouseRebuildOpConfig): ClickHouseRebuildOpResources;
+//# sourceMappingURL=op.d.ts.map

package/dist/clickhouse/rebuild/op.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"op.d.ts","sourceRoot":"","sources":["../../../src/clickhouse/rebuild/op.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,EAAyC,KAAK,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAC/F,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAEtD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAE3C,MAAM,WAAW,yBAAyB;IACxC,4BAA4B;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,2DAA2D;IAC3D,GAAG,EAAE,MAAM,CAAC;IACZ,yFAAyF;IACzF,KAAK,EAAE,MAAM,CAAC;IACd,yDAAyD;IACzD,SAAS,EAAE,SAAS,CAAC;IACrB,kFAAkF;IAClF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gDAAgD;IAChD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,6EAA6E;IAC7E,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,iGAAiG;IACjG,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,+DAA+D;IAC/D,IAAI,CAAC,EAAE;QACL,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,6GAA6G;QAC7G,QAAQ,CAAC,EAAE,YAAY,CAAC;KACzB,CAAC;IACF,oFAAoF;IACpF,QAAQ,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACrE,6GAA6G;IAC7G,UAAU,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACvE,mFAAmF;IACnF,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,kEAAkE;IAClE,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,wEAAwE;IACxE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,oEAAoE;IACpE,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,4BAA4B;IAC3C,EAAE,EAAE,YAAY,CAAC,OAAO,UAAU,CAAC,CAAC;CACrC;AAED,kDAAkD;AAClD,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,SAAS,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,yBAAyB,GAAG,4BAA4B,CAqGnG"}

package/dist/clickhouse/rebuild/partitions.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Partitions, as the backfill copies them and the verification counts them.
+ *
+ * The unit of work is a partition of the old table. Its rows can land in
+ * other partitions of the new table when the rebuild changes the partition
+ * key, so "the rows of old partition p" is found on the new table by
+ * computing the old partition key over the new table's columns:
+ * `partitionID(<old key>)`, which the server computes the same way it named
+ * the old partition (`_partition_id`). When the key is unchanged that is the
+ * new table's own `_partition_id`; when the old table has no partition key
+ * every row is in partition `all`.
+ */
+import type { ClickHouseTarget } from "../live/bind.js";
+import type { CopiedColumn, RebuildNames } from "./observe.js";
+/** The old table's active partitions, by id. */
+export declare function sourcePartitions(target: ClickHouseTarget, names: RebuildNames): Promise<string[]>;
+/** Rename the columns an expression names, old name to new, leaving function names and qualified names alone. */
+export declare function renameColumns(expr: string, copied: readonly CopiedColumn[]): string;
+/**
+ * The expression that gives, for a row of the new table, the id of the old
+ * table's partition the row came from.
+ */
+export declare function sourcePartitionExpression(oldKey: string, newKey: string, copied: readonly CopiedColumn[]): string;
+//# sourceMappingURL=partitions.d.ts.map

package/dist/clickhouse/rebuild/partitions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"partitions.d.ts","sourceRoot":"","sources":["../../../src/clickhouse/rebuild/partitions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAErD,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAE5D,gDAAgD;AAChD,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,gBAAgB,EAAE,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAOvG;AAED,iHAAiH;AACjH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,YAAY,EAAE,GAAG,MAAM,CAQnF;AAeD;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,YAAY,EAAE,GAAG,MAAM,CAKjH"}

package/dist/clickhouse/rebuild/receipts.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Effect receipts kept in ClickHouse (#3198): where the rebuild migration's
+ * backfill records which partitions it has copied.
+ *
+ * A receipt is the proof that one effect ran, kept where the effect happened
+ * (concepts/effect-receipts.mdx). The backfill's effect is "this partition of
+ * the old table is in the new table", and both tables are on the server, so
+ * the receipt is a row on the same server:
+ *
+ *     SELECT * FROM chant_receipts.receipts
+ *
+ * Why not git (core's lifecycle receipt store, `chant/lifecycle`): the
+ * receipt has to die with the data it witnesses. The rebuild's `onFailure`
+ * drops the new table; a receipt kept in git would go on saying partitions
+ * were copied into a table that no longer exists, and a resumed backfill
+ * would skip them. Here every receipt's expectation is bound to the new
+ * table's UUID, so a new table made again reads every old receipt as stale,
+ * and the receipts are read and written over the connection the copy already
+ * uses, with no commit and push per partition. Readable with nothing but a
+ * ClickHouse client, which is the walk-away property the other rows have.
+ *
+ * The store implements core's `ReceiptStore` seam
+ * (`@intentius/chant/op/receipt-store`), as the sql lexicon's shared
+ * `SqlReceiptStore` (`../../core/receipts.ts`). It is not exported as the
+ * `receiptRead` / `receiptWrite` activities: those names are global to a
+ * run, and a project that also configures aws or k8s would have its
+ * `effect()` steps read ClickHouse instead of SSM or a ConfigMap. The backfill
+ * activity reaches the store directly, the way the fly lexicon's release
+ * component reaches its own.
+ *
+ * Write discipline: the backfill writes a partition's receipt after the
+ * partition's copy succeeded, last, and nothing else writes one.
+ *
+ * In a Replicated database (#3249) the receipts sit beside the tables they
+ * witness, in `<db>.__chant_receipts`, a `ReplicatedReplacingMergeTree`: the
+ * database runs its CREATE on every replica and the table replicates its
+ * rows, so a receipt written by a copy on one replica is read by a resumed
+ * backfill on another. Each read first waits for this replica to fetch what
+ * the others wrote (`SYSTEM SYNC REPLICA ... LIGHTWEIGHT`). A separate
+ * `chant_receipts` database would exist on the one replica the backfill
+ * first ran on. With a replica down (#3270) the CREATE goes on without it,
+ * and a read that cannot fetch a receipt only that replica has stops the
+ * backfill, naming it (`./replicas.ts`).
+ */
+import { type SqlReceiptStore } from "../../core/receipts.js";
+import { type ClickHouseEndpoint } from "../http.js";
+/** The database the receipts live in. Its comment marks it as chant's, so schema reads leave it out. */
+export declare const RECEIPTS_DATABASE = "chant_receipts";
+/** The table, one row per receipt write. */
+export declare const RECEIPTS_TABLE = "receipts";
+/** The table in a Replicated database that holds the receipts of the rebuilds in it. */
+export declare const REPLICATED_RECEIPTS_TABLE = "__chant_receipts";
+/** Where the receipts are kept: `chant_receipts.receipts`, or `<db>.__chant_receipts` for a Replicated database. */
+export declare function receiptsTable(replicatedIn?: string): {
+    database: string;
+    name: string;
+};
+export { receiptAddress } from "../../core/receipts.js";
+/** The shared core's receipt store, kept on a ClickHouse server. */
+export type ClickHouseReceiptStore = SqlReceiptStore;
+/**
+ * A receipt store on the server at `endpoint`. Creates the receipts database
+ * and table on first write if they are not there. `identity` is the
+ * project's ownership stack and env, which every address starts with.
+ * `replicatedIn` names a Replicated database to keep them in instead, and
+ * `replicaTimeoutMs` how long a read waits for this replica to catch up there.
+ */
+export declare function clickhouseReceiptStore(endpoint: ClickHouseEndpoint, identity: {
+    stack?: string;
+    env?: string;
+}, opts?: {
+    runId?: string;
+    replicatedIn?: string;
+    replicaTimeoutMs?: number;
+}): ClickHouseReceiptStore;
+//# sourceMappingURL=receipts.d.ts.map

package/dist/clickhouse/rebuild/receipts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"receipts.d.ts","sourceRoot":"","sources":["../../../src/clickhouse/rebuild/receipts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAIH,OAAO,EAAkB,KAAK,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC3E,OAAO,EAAmB,KAAK,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAKnE,wGAAwG;AACxG,eAAO,MAAM,iBAAiB,mBAAmB,CAAC;AAClD,4CAA4C;AAC5C,eAAO,MAAM,cAAc,aAAa,CAAC;AAEzC,wFAAwF;AACxF,eAAO,MAAM,yBAAyB,qBAAqB,CAAC;AAE5D,oHAAoH;AACpH,wBAAgB,aAAa,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAEvF;AAMD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAErD,oEAAoE;AACpE,MAAM,MAAM,sBAAsB,GAAG,eAAe,CAAC;AAErD;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,kBAAkB,EAC5B,QAAQ,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,EAC1C,IAAI,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAAC,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAAO,GAC9E,sBAAsB,CAwDxB"}