@intentius/chant-lexicon-sql 0.114.1 → 0.115.0

package/dist/op/activity-contracts.d.ts

@@ -30,6 +30,7 @@ export declare const clickhouseRebuildPlanContract: import("@intentius/chant/op"
     stack?: string | undefined;
     ownershipEnv?: string | undefined;
     cwd?: string | undefined;
+    keepOnFailure?: boolean | undefined;
 }, {
     state: "done" | "rebuild" | "swapped";
     table: string;
@@ -54,6 +55,7 @@ export declare const clickhouseRebuildCreateContract: import("@intentius/chant/o
     stack?: string | undefined;
     ownershipEnv?: string | undefined;
     cwd?: string | undefined;
+    keepOnFailure?: boolean | undefined;
 }, {
     state: "done" | "rebuild" | "swapped";
     table: string;
@@ -76,6 +78,7 @@ export declare const clickhouseRebuildDualWriteContract: import("@intentius/chan
     stack?: string | undefined;
     ownershipEnv?: string | undefined;
     cwd?: string | undefined;
+    keepOnFailure?: boolean | undefined;
 }, {
     state: "done" | "rebuild" | "swapped";
     mode: "app" | "materialized-view";
@@ -99,6 +102,7 @@ export declare const clickhouseRebuildBackfillContract: import("@intentius/chant
     stack?: string | undefined;
     ownershipEnv?: string | undefined;
     cwd?: string | undefined;
+    keepOnFailure?: boolean | undefined;
 }, {
     state: "done" | "rebuild" | "swapped";
     partitions: number;
@@ -123,6 +127,7 @@ export declare const clickhouseRebuildVerifyContract: import("@intentius/chant/o
     stack?: string | undefined;
     ownershipEnv?: string | undefined;
     cwd?: string | undefined;
+    keepOnFailure?: boolean | undefined;
 }, {
     state: "done" | "rebuild" | "swapped";
     partitions: number;
@@ -152,6 +157,7 @@ export declare const clickhouseRebuildSwapContract: import("@intentius/chant/op"
     stack?: string | undefined;
     ownershipEnv?: string | undefined;
     cwd?: string | undefined;
+    keepOnFailure?: boolean | undefined;
 }, {
     state: "done" | "rebuild" | "swapped";
     swapped: boolean;
@@ -176,6 +182,7 @@ export declare const clickhouseRebuildRetainContract: import("@intentius/chant/o
     stack?: string | undefined;
     ownershipEnv?: string | undefined;
     cwd?: string | undefined;
+    keepOnFailure?: boolean | undefined;
 }, {
     state: "done" | "rebuild" | "swapped";
     due: boolean;
@@ -200,6 +207,7 @@ export declare const clickhouseRebuildDropContract: import("@intentius/chant/op"
     stack?: string | undefined;
     ownershipEnv?: string | undefined;
     cwd?: string | undefined;
+    keepOnFailure?: boolean | undefined;
 }, {
     state: "done" | "rebuild" | "swapped";
     dropped: boolean;
@@ -223,6 +231,7 @@ export declare const clickhouseRebuildCompensateContract: import("@intentius/cha
     stack?: string | undefined;
     ownershipEnv?: string | undefined;
     cwd?: string | undefined;
+    keepOnFailure?: boolean | undefined;
 }, {
     dropped: string[];
 }>;
@@ -461,4 +470,15 @@ export declare const postgresMigrationCompensateContract: import("@intentius/cha
 }, {
     dropped: string[];
 }>;
+/** `SqlExecArgs` (`./activities/sql-exec.ts`): one batch's SQL on the environment's server. */
+export declare const sqlExecContract: import("@intentius/chant/op").ActivityContract<{
+    sql: string;
+    environment?: string | undefined;
+    settings?: Record<string, string | number> | undefined;
+    cwd?: string | undefined;
+}, {
+    dialect: "clickhouse" | "postgres";
+    source: string;
+    rows: number;
+}>;
 //# sourceMappingURL=activity-contracts.d.ts.map

package/dist/op/activity-contracts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"activity-contracts.d.ts","sourceRoot":"","sources":["../../src/op/activity-contracts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AA2BH,eAAO,MAAM,6BAA6B;;;;;;;;;;;;;;;;;;;;;;;EAKzC,CAAC;AAEF,eAAO,MAAM,+BAA+B;;;;;;;;;;;;;;;;;;;;;EAK3C,CAAC;AAEF,eAAO,MAAM,kCAAkC;;;;;;;;;;;;;;;;;;;;;;EAK9C,CAAC;AAEF,eAAO,MAAM,iCAAiC;;;;;;;;;;;;;;;;;;;;;;;EAK7C,CAAC;AAEF,eAAO,MAAM,+BAA+B;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAY3C,CAAC;AAEF,eAAO,MAAM,6BAA6B;;;;;;;;;;;;;;;;;;;;;;;EAKzC,CAAC;AAEF,eAAO,MAAM,+BAA+B;;;;;;;;;;;;;;;;;;;;;;;EAK3C,CAAC;AAEF,eAAO,MAAM,6BAA6B;;;;;;;;;;;;;;;;;;;;;;EAKzC,CAAC;AAEF,eAAO,MAAM,mCAAmC;;;;;;;;;;;;;;;;;;;EAK/C,CAAC;AAuBF,eAAO,MAAM,6BAA6B;;;;;;;;;;;;;;;;;;;;;;;;EAKzC,CAAC;AAEF,eAAO,MAAM,+BAA+B;;;;;;;;;;;;;;;;;;;;;EAK3C,CAAC;AAEF,eAAO,MAAM,kCAAkC;;;;;;;;;;;;;;;;;;;;;EAK9C,CAAC;AAEF,eAAO,MAAM,iCAAiC;;;;;;;;;;;;;;;;;;;;;;;;EAK7C,CAAC;AAEF,eAAO,MAAM,8BAA8B;;;;;;;;;;;;;;;;;;;;;;;EAK1C,CAAC;AAEF,eAAO,MAAM,+BAA+B;;;;;;;;;;;;;;;;;;;;;;;;;;EAc3C,CAAC;AAEF,eAAO,MAAM,+BAA+B;;;;;;;;;;;;;;;;;;;;;;EAK3C,CAAC;AAEF,eAAO,MAAM,+BAA+B;;;;;;;;;;;;;;;;;;;;;;;EAK3C,CAAC;AAEF,eAAO,MAAM,iCAAiC;;;;;;;;;;;;;;;;;;;;;;EAK7C,CAAC;AAEF,eAAO,MAAM,mCAAmC;;;;;;;;;;;;;;;;;;;EAK/C,CAAC"}
+{"version":3,"file":"activity-contracts.d.ts","sourceRoot":"","sources":["../../src/op/activity-contracts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AA4BH,eAAO,MAAM,6BAA6B;;;;;;;;;;;;;;;;;;;;;;;;EAKzC,CAAC;AAEF,eAAO,MAAM,+BAA+B;;;;;;;;;;;;;;;;;;;;;;EAK3C,CAAC;AAEF,eAAO,MAAM,kCAAkC;;;;;;;;;;;;;;;;;;;;;;;EAK9C,CAAC;AAEF,eAAO,MAAM,iCAAiC;;;;;;;;;;;;;;;;;;;;;;;;EAK7C,CAAC;AAEF,eAAO,MAAM,+BAA+B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAY3C,CAAC;AAEF,eAAO,MAAM,6BAA6B;;;;;;;;;;;;;;;;;;;;;;;;EAKzC,CAAC;AAEF,eAAO,MAAM,+BAA+B;;;;;;;;;;;;;;;;;;;;;;;;EAK3C,CAAC;AAEF,eAAO,MAAM,6BAA6B;;;;;;;;;;;;;;;;;;;;;;;EAKzC,CAAC;AAEF,eAAO,MAAM,mCAAmC;;;;;;;;;;;;;;;;;;;;EAK/C,CAAC;AAuBF,eAAO,MAAM,6BAA6B;;;;;;;;;;;;;;;;;;;;;;;;EAKzC,CAAC;AAEF,eAAO,MAAM,+BAA+B;;;;;;;;;;;;;;;;;;;;;EAK3C,CAAC;AAEF,eAAO,MAAM,kCAAkC;;;;;;;;;;;;;;;;;;;;;EAK9C,CAAC;AAEF,eAAO,MAAM,iCAAiC;;;;;;;;;;;;;;;;;;;;;;;;EAK7C,CAAC;AAEF,eAAO,MAAM,8BAA8B;;;;;;;;;;;;;;;;;;;;;;;EAK1C,CAAC;AAEF,eAAO,MAAM,+BAA+B;;;;;;;;;;;;;;;;;;;;;;;;;;EAc3C,CAAC;AAEF,eAAO,MAAM,+BAA+B;;;;;;;;;;;;;;;;;;;;;;EAK3C,CAAC;AAEF,eAAO,MAAM,+BAA+B;;;;;;;;;;;;;;;;;;;;;;;EAK3C,CAAC;AAEF,eAAO,MAAM,iCAAiC;;;;;;;;;;;;;;;;;;;;;;EAK7C,CAAC;AAEF,eAAO,MAAM,mCAAmC;;;;;;;;;;;;;;;;;;;EAK/C,CAAC;AAIF,+FAA+F;AAC/F,eAAO,MAAM,eAAe;;;;;;;;;EAS3B,CAAC"}

package/dist/postgres/live/catalog.d.ts

@@ -22,7 +22,7 @@
  *   column's sequence, since the column prints as `serial`;
  * - an index that backs a constraint (the constraint creates it), and an
  *   index partition (the partitioned index creates it);
- * - chant's own receipts tables (`../../core/ownership.ts`), and the working
+ * - chant's own receipts tables and schema (`../../core/ownership.ts`), and the working
  *   columns, constraints and indexes of an expand-and-contract migration in
  *   progress (`../migrate/names.ts`, `../migrate/carry.ts`), so a table reads
  *   as it was before the migration until its switch, and as declared after it.

package/dist/postgres/live/catalog.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../../../src/postgres/live/catalog.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAC/C,OAAO,EAAyB,KAAK,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAKjF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAE3D,iEAAiE;AACjE,eAAO,MAAM,cAAc,UAAmD,CAAC;AAE/E,kFAAkF;AAClF,eAAO,MAAM,cAAc,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAa3D,CAAC;AAEF,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,kBAAkB,CAAC;IACzB,iEAAiE;IACjE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,iDAAiD;IACjD,GAAG,EAAE,MAAM,CAAC;IACZ,uFAAuF;IACvF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB,+FAA+F;IAC/F,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,yCAAyC;AACzC,MAAM,WAAW,WAAW;IAC1B,gHAAgH;IAChH,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7B;AAyCD,UAAU,cAAc;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,OAAO,CAAC;CAChB;AAQD,yFAAyF;AACzF,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC,cAAc,EAAE,MAAM,GAAG,WAAW,GAAG,OAAO,CAAC,CAKtH;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,cAAc,EAAE,QAAQ,EAAE,OAAO,GAAG,MAAM,EAAE,CAa9E;AAcD;;;;GAIG;AACH,wBAAsB,cAAc,CAAC,MAAM,EAAE,cAAc,EAAE,KAAK,GAAE,WAAgB,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAmX7G;AAED,yEAAyE;AACzE,eAAO,MAAM,OAAO,GAAI,MAAM,MAAM,EAAE,QAAQ,MAAM,GAAG,SAAS,EAAE,MAAM,MAAM,KAAG,MAA2C,CAAC;AAE7H;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,SAAS,YAAY,EAAE,EAAE,QAAQ,EAAE,gBAAgB,GAAG,SAAS,GAAG,YAAY,EAAE,CAW1H"}
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../../../src/postgres/live/catalog.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAC/C,OAAO,EAAyB,KAAK,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAKjF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAE3D,iEAAiE;AACjE,eAAO,MAAM,cAAc,UAAmD,CAAC;AAE/E,kFAAkF;AAClF,eAAO,MAAM,cAAc,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAa3D,CAAC;AAEF,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,kBAAkB,CAAC;IACzB,iEAAiE;IACjE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,iDAAiD;IACjD,GAAG,EAAE,MAAM,CAAC;IACZ,uFAAuF;IACvF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB,+FAA+F;IAC/F,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,yCAAyC;AACzC,MAAM,WAAW,WAAW;IAC1B,gHAAgH;IAChH,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7B;AAyCD,UAAU,cAAc;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,OAAO,CAAC;CAChB;AAQD,yFAAyF;AACzF,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC,cAAc,EAAE,MAAM,GAAG,WAAW,GAAG,OAAO,CAAC,CAKtH;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,cAAc,EAAE,QAAQ,EAAE,OAAO,GAAG,MAAM,EAAE,CAa9E;AAcD;;;;GAIG;AACH,wBAAsB,cAAc,CAAC,MAAM,EAAE,cAAc,EAAE,KAAK,GAAE,WAAgB,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAqX7G;AAED,yEAAyE;AACzE,eAAO,MAAM,OAAO,GAAI,MAAM,MAAM,EAAE,QAAQ,MAAM,GAAG,SAAS,EAAE,MAAM,MAAM,KAAG,MAA2C,CAAC;AAE7H;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,SAAS,YAAY,EAAE,EAAE,QAAQ,EAAE,gBAAgB,GAAG,SAAS,GAAG,YAAY,EAAE,CAW1H"}

package/dist/postgres/migrate/receipts.d.ts

@@ -27,9 +27,9 @@
  * stale; onFailure and the contract also delete the migration's receipts.
  *
  * The store implements the shared core's `SqlReceiptStore`
- * (`../../core/receipts.ts`) over the migration's own connection. It is not
- * exported as the `receiptRead` / `receiptWrite` activities, whose names are
- * global to a run and belong to an aws or k8s project's receipt row.
+ * (`../../core/receipts.ts`) over the migration's own connection, which the
+ * backfill reaches directly. A sql project's `effect()` receipts use the same
+ * store over `chant_receipts.receipts` (`../../receipts.ts`).
  */
 import { type SqlReceiptStore } from "../../core/receipts.js";
 import type { PostgresClient } from "../live/client.js";
@@ -38,7 +38,7 @@ export declare const POSTGRES_RECEIPTS_TABLE = "__chant_receipts";
 export { receiptAddress } from "../../core/receipts.js";
 /** A receipts table chant did not make: a user's table under the same name. */
 export declare class ReceiptsTableConflict extends Error {
-    constructor(schema: string);
+    constructor(schema: string, table?: string);
 }
 export interface PostgresReceiptStore extends SqlReceiptStore {
     /** The qualified, quoted table name. */
@@ -52,12 +52,15 @@ export interface PostgresReceiptStore extends SqlReceiptStore {
  * A receipt store in `<schema>.__chant_receipts`, over `client`. `write` runs
  * on the client as it is, so a write inside the caller's transaction commits
  * or rolls back with it. `identity` is the project's ownership stack and env,
- * which every address starts with.
+ * which every address starts with. `table` names the table in `schema`,
+ * `__chant_receipts` by default (`../../receipts.ts` keeps `effect()`
+ * receipts in `chant_receipts.receipts`).
  */
 export declare function postgresReceiptStore(client: PostgresClient, schema: string, identity: {
     stack?: string;
     env?: string;
 }, opts?: {
     runId?: string;
+    table?: string;
 }): PostgresReceiptStore;
 //# sourceMappingURL=receipts.d.ts.map

package/dist/postgres/migrate/receipts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"receipts.d.ts","sourceRoot":"","sources":["../../../src/postgres/migrate/receipts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAKH,OAAO,EAAkB,KAAK,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAE3E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAErD,0DAA0D;AAC1D,eAAO,MAAM,uBAAuB,qBAAqB,CAAC;AAI1D,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAErD,+EAA+E;AAC/E,qBAAa,qBAAsB,SAAQ,KAAK;gBAClC,MAAM,EAAE,MAAM;CAO3B;AAED,MAAM,WAAW,oBAAqB,SAAQ,eAAe;IAC3D,wCAAwC;IACxC,KAAK,EAAE,MAAM,CAAC;IACd,gGAAgG;IAChG,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACxB,iGAAiG;IACjG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACzC;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,EAAE,IAAI,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,oBAAoB,CA4D5K"}
+{"version":3,"file":"receipts.d.ts","sourceRoot":"","sources":["../../../src/postgres/migrate/receipts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAKH,OAAO,EAAkB,KAAK,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAE3E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAErD,0DAA0D;AAC1D,eAAO,MAAM,uBAAuB,qBAAqB,CAAC;AAI1D,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAErD,+EAA+E;AAC/E,qBAAa,qBAAsB,SAAQ,KAAK;gBAClC,MAAM,EAAE,MAAM,EAAE,KAAK,GAAE,MAAgC;CAOpE;AAED,MAAM,WAAW,oBAAqB,SAAQ,eAAe;IAC3D,wCAAwC;IACxC,KAAK,EAAE,MAAM,CAAC;IACd,gGAAgG;IAChG,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACxB,iGAAiG;IACjG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACzC;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,cAAc,EACtB,MAAM,EAAE,MAAM,EACd,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,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GAC5C,oBAAoB,CA6DtB"}

package/dist/receipts.d.ts

@@ -0,0 +1,102 @@
+/**
+ * The sql lexicon's `effect()` receipt store (#3657): where the receipts of a
+ * project that uses only the sql lexicon are kept, on the database server the
+ * environment names.
+ *
+ *     ClickHouse   chant_receipts.receipts
+ *     Postgres     chant_receipts.receipts   (or <receiptsSchema>.__chant_receipts)
+ *
+ * The op activities module binds it as `receiptRead`, `receiptWrite` and
+ * `receiptStaleness` (`./op/activities/index.ts`), listed as fallbacks: a
+ * project that also configures aws or k8s keeps its receipts in that
+ * lexicon's receipt row, in whichever order `lexicons` lists them.
+ *
+ * Which server: the environment is the one `chant run --env` sets
+ * (`CHANT_ENV`), else a literal `ownership.env`. Its `sql.profiles.<env>`
+ * binds the server, a `postgres://` URL making it Postgres; with no profile,
+ * `CLICKHOUSE_URL` or `POSTGRES_URL`, picked by `sql.dialect`. A receipt's
+ * address is `<stack>/<env>/<effect>`, from `ownership.stack` and that
+ * environment, the same identity the rebuild's and the column migration's
+ * receipts carry (`./core/receipts.ts`).
+ *
+ * Both tables carry chant's ownership trailer with the `receipts` key in their
+ * comment (the Postgres schema too), so plan, import and prune leave them out.
+ *
+ * A caller that runs its own Op over a server it has already bound (a
+ * migration runner, say) passes that server instead: a ClickHouse endpoint,
+ * or a Postgres connection, whose receipt writes then commit or roll back
+ * with whatever transaction the caller has open on it.
+ */
+import type { ChantConfig } from "@intentius/chant/config";
+import { type ReceiptActivities, type ReceiptActivityOptions } from "@intentius/chant/op/receipt-store";
+import type { SqlReceiptStore } from "./core/receipts.js";
+import type { ClickHouseEndpoint } from "./clickhouse/http.js";
+import type { Topology } from "./clickhouse/topology.js";
+import type { PostgresClient } from "./postgres/live/client.js";
+/** The database (ClickHouse) or schema (Postgres) the receipts are kept in. */
+export declare const SQL_RECEIPTS_SCHEMA = "chant_receipts";
+/** The table in it. */
+export declare const SQL_RECEIPTS_TABLE = "receipts";
+/** The table's name in a schema of the user's own (`receiptsSchema`), as the column migration names it. */
+export declare const SQL_RECEIPTS_TABLE_BESIDE = "__chant_receipts";
+export interface SqlReceiptStoreOptions {
+    /** The chant environment. Default: `CHANT_ENV`, then a literal `ownership.env`. */
+    environment?: string;
+    /** The address's stack segment. Default: `ownership.stack`. */
+    stack?: string;
+    /** The project directory chant.config.ts is read from. Default: the working directory. */
+    cwd?: string;
+    /** The project's config, instead of reading chant.config.ts. */
+    config?: Pick<ChantConfig, "sql" | "ownership">;
+    /** The process environment the bindings and `CHANT_ENV` are read from. Default: `process.env`. */
+    env?: Record<string, string | undefined>;
+    /** A ClickHouse server already bound: the receipts go there, and no profile is read. */
+    clickhouse?: {
+        endpoint: ClickHouseEndpoint;
+        topology?: Topology;
+    };
+    /**
+     * A Postgres connection already open: the receipts go over it, and it is
+     * never closed. A write runs inside whatever transaction the caller has
+     * open, so it commits or rolls back with it. Call `ensure()` before such a
+     * transaction begins, so the receipts table does not roll back with it.
+     */
+    postgres?: PostgresClient;
+    /** Postgres: the schema to keep the receipts in. Default: the profile's `receiptsSchema`, then `chant_receipts`. */
+    schema?: string;
+    /** Recorded on each receipt written. Default: the current Op run's id. */
+    runId?: string;
+}
+/** The store, and the step a caller with its own transaction takes before one opens. */
+export interface SqlServerReceiptStore extends SqlReceiptStore {
+    /** Create the receipts table (and database or schema) if it is not there. */
+    ensure(): Promise<void>;
+    /** Where the receipts are, as resolved: `chant_receipts.receipts` and the server it is on. */
+    location(): Promise<{
+        dialect: "clickhouse" | "postgres";
+        table: string;
+        source: string;
+        address: string;
+    }>;
+}
+type Config = Pick<ChantConfig, "sql" | "ownership">;
+/** The dialect an environment's receipts are kept in: its profile's URL, else `sql.dialect`, else whichever server variable is set. */
+export declare function receiptDialect(config: Config | undefined, environment: string | undefined, env: Record<string, string | undefined>): "clickhouse" | "postgres";
+/** The run's environment: the option, `CHANT_ENV`, or a literal `ownership.env`. */
+export declare function environmentOf(options: {
+    environment?: string;
+}, config: Pick<ChantConfig, "ownership"> | undefined, env: Record<string, string | undefined>): string | undefined;
+/**
+ * The receipt store on the environment's database server. Nothing is read or
+ * connected until the first read or write; the environment, the server and
+ * the identity are resolved then, once.
+ */
+export declare function sqlReceiptStore(options?: SqlReceiptStoreOptions): SqlServerReceiptStore;
+/**
+ * The `receiptRead`, `receiptWrite` and `receiptStaleness` activities over
+ * {@link sqlReceiptStore}: what the op activities module exports, and what a
+ * caller running an Op of `effect()` steps with its own activity map binds.
+ */
+export declare function sqlReceiptActivities(options?: SqlReceiptStoreOptions, activityOptions?: ReceiptActivityOptions): ReceiptActivities;
+export {};
+//# sourceMappingURL=receipts.d.ts.map

package/dist/receipts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"receipts.d.ts","sourceRoot":"","sources":["../src/receipts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAqB,KAAK,iBAAiB,EAAE,KAAK,sBAAsB,EAAE,MAAM,mCAAmC,CAAC;AAE3H,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEvD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAC5D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAE7D,+EAA+E;AAC/E,eAAO,MAAM,mBAAmB,mBAAmB,CAAC;AACpD,uBAAuB;AACvB,eAAO,MAAM,kBAAkB,aAAa,CAAC;AAC7C,2GAA2G;AAC3G,eAAO,MAAM,yBAAyB,qBAAqB,CAAC;AAE5D,MAAM,WAAW,sBAAsB;IACrC,mFAAmF;IACnF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,+DAA+D;IAC/D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0FAA0F;IAC1F,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,gEAAgE;IAChE,MAAM,CAAC,EAAE,IAAI,CAAC,WAAW,EAAE,KAAK,GAAG,WAAW,CAAC,CAAC;IAChD,kGAAkG;IAClG,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACzC,wFAAwF;IACxF,UAAU,CAAC,EAAE;QAAE,QAAQ,EAAE,kBAAkB,CAAC;QAAC,QAAQ,CAAC,EAAE,QAAQ,CAAA;KAAE,CAAC;IACnE;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,oHAAoH;IACpH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0EAA0E;IAC1E,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,wFAAwF;AACxF,MAAM,WAAW,qBAAsB,SAAQ,eAAe;IAC5D,6EAA6E;IAC7E,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACxB,8FAA8F;IAC9F,QAAQ,IAAI,OAAO,CAAC;QAAE,OAAO,EAAE,YAAY,GAAG,UAAU,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC7G;AAED,KAAK,MAAM,GAAG,IAAI,CAAC,WAAW,EAAE,KAAK,GAAG,WAAW,CAAC,CAAC;AAqBrD,uIAAuI;AACvI,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,EAAE,WAAW,EAAE,MAAM,GAAG,SAAS,EAAE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GAAG,YAAY,GAAG,UAAU,CAO9J;AAED,oFAAoF;AACpF,wBAAgB,aAAa,CAAC,OAAO,EAAE;IAAE,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,EAAE,MAAM,EAAE,IAAI,CAAC,WAAW,EAAE,WAAW,CAAC,GAAG,SAAS,EAAE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GAAG,MAAM,GAAG,SAAS,CAKhL;AAgGD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,OAAO,GAAE,sBAA2B,GAAG,qBAAqB,CA+B3F;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,GAAE,sBAA2B,EAAE,eAAe,CAAC,EAAE,sBAAsB,GAAG,iBAAiB,CAEtI"}

package/package.json

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

package/src/clickhouse/apply/mutations.ts

@@ -49,10 +49,10 @@ export class MutationFailedError extends Error {
 }
 
 /** The table's mutations that are not done. */
-export async function pendingMutations(endpoint: ClickHouseEndpoint, database: string, table: string): Promise<PendingMutation[]> {
+export async function pendingMutations(endpoint: ClickHouseEndpoint, database: string, table: string, source = "system.mutations"): Promise<PendingMutation[]> {
   return clickhouseQuery<PendingMutation>(
     endpoint,
-    `SELECT mutation_id, command, latest_fail_reason FROM system.mutations ` +
+    `SELECT mutation_id, command, latest_fail_reason FROM ${source} ` +
       `WHERE database = ${sqlString(database)} AND table = ${sqlString(table)} AND NOT is_done ORDER BY create_time`,
   );
 }
@@ -63,6 +63,12 @@ export interface WaitOptions {
   /** First poll interval; it doubles up to two seconds. Default: 100ms. */
   intervalMs?: number;
   signal?: AbortSignal;
+  /**
+   * Where the mutations are listed. Default: `system.mutations`, this
+   * server's. A rebuild across the shards of a cluster waits on every
+   * server's, `clusterAllReplicas('<cluster>', system.mutations)` (#3663).
+   */
+  source?: string;
 }
 
 /**
@@ -78,7 +84,7 @@ export async function waitForMutations(endpoint: ClickHouseEndpoint, database: s
   const name = `${database}.${table}`;
   for (;;) {
     opts.signal?.throwIfAborted();
-    const pending = await pendingMutations(endpoint, database, table);
+    const pending = await pendingMutations(endpoint, database, table, opts.source);
     for (const m of pending) seen.add(m.mutation_id);
     if (pending.length === 0) return [...seen];
     const failing = pending.find((m) => m.latest_fail_reason);

package/src/clickhouse/container.ts

@@ -51,8 +51,12 @@ export async function startScratchServer(
 }
 
 export interface ScratchCluster {
-  /** One endpoint per replica, in replica order (`r1`, `r2`, ...). */
+  /** One endpoint per server, in order: shard 1's replicas first (`r1`, `r2`, ...), then shard 2's. */
   replicas: ClickHouseEndpoint[];
+  /** Each server's shard and replica macros, in the order of `replicas`. */
+  layout: Array<{ shard: string; replica: string; host: string }>;
+  /** The cluster `remote_servers` defines over every server: `ON CLUSTER` and `cluster:<name>` name it. */
+  cluster: string;
   /** The containers' common name prefix, for a log line. */
   name: string;
   /** Remove the containers and their network. Safe to call twice. */
@@ -72,23 +76,37 @@ export interface ScratchCluster {
 }
 
 /**
- * Start `replicas` servers of `image` as one shard of replicas, on their own
- * Docker network, and wait until each answers and reaches Keeper.
+ * Start servers of `image` on their own Docker network, and wait until each
+ * answers and reaches Keeper: `replicas` servers as one shard of replicas,
+ * or, with `shards`, that many replicas in each shard (`[2, 1]` is a shard of
+ * two replicas and a shard of one server).
  *
  * Keeper is the server's embedded one (`keeper_server`), run by the first
- * replica, so the pinned server image and its digest pin Keeper too. Each
- * replica gets the macros `{shard}` = `s1` and `{replica}` = `r<n>`, which
- * a `Replicated` database's arguments name. Configuration is copied into each
- * container before it starts, with no bind mount.
+ * server, so the pinned server image and its digest pin Keeper too. Each
+ * server gets the macros `{shard}` = `s<n>` and `{replica}` = `r<n>` (the
+ * replica numbered within its shard), which a `Replicated` database's and a
+ * `Replicated*MergeTree`'s arguments name, and `remote_servers` defines the
+ * cluster `cluster` (default `chant`) over all of them, with
+ * `internal_replication`, so `ON CLUSTER` reaches every server. Configuration
+ * is copied into each container before it starts, with no bind mount.
  */
 export async function startScratchCluster(
   image: string,
-  options: { replicas?: number; namePrefix?: string; readyTimeoutMs?: number } = {},
+  options: { replicas?: number; shards?: number[]; cluster?: string; namePrefix?: string; readyTimeoutMs?: number } = {},
 ): Promise<ScratchCluster> {
-  const count = options.replicas ?? 2;
+  const shards = options.shards ?? [options.replicas ?? 2];
+  const clusterName = options.cluster ?? "chant";
   const name = uniqueContainerName(options.namePrefix ?? "chant-sql-cluster");
   const network = `${name}-net`;
-  const nodes = Array.from({ length: count }, (_, i) => `${name}-r${i + 1}`);
+  // One shard keeps the names the single-shard cluster always had (`<name>-r<n>`).
+  const layout = shards.flatMap((replicas, s) =>
+    Array.from({ length: replicas }, (_, r) => ({
+      shard: `s${s + 1}`,
+      replica: `r${r + 1}`,
+      host: shards.length === 1 ? `${name}-r${r + 1}` : `${name}-s${s + 1}r${r + 1}`,
+    })),
+  );
+  const nodes = layout.map((l) => l.host);
   const dir = mkdtempSync(join(tmpdir(), "chant-sql-cluster-"));
   let removed = false;
   const stop = async (): Promise<void> => {
@@ -100,6 +118,12 @@ export async function startScratchCluster(
   };
 
   const keeper = nodes[0]!;
+  const remoteServers = shards
+    .map((_, s) => {
+      const hosts = layout.filter((l) => l.shard === `s${s + 1}`).map((l) => `<replica><host>${l.host}</host><port>9000</port></replica>`);
+      return `<shard><internal_replication>true</internal_replication>${hosts.join("")}</shard>`;
+    })
+    .join("");
   const config = (node: string, i: number) => `<clickhouse>
 ${
   i === 0
@@ -113,7 +137,9 @@ ${
 `
     : ""
 }  <zookeeper><node><host>${keeper}</host><port>9181</port></node></zookeeper>
-  <macros><shard>s1</shard><replica>r${i + 1}</replica></macros>
+  <distributed_ddl><path>/clickhouse/task_queue/ddl</path></distributed_ddl>
+  <remote_servers><${clusterName}>${remoteServers}</${clusterName}></remote_servers>
+  <macros><shard>${layout[i]!.shard}</shard><replica>${layout[i]!.replica}</replica></macros>
   <interserver_http_host>${node}</interserver_http_host>
 </clickhouse>
 `;
@@ -156,6 +182,8 @@ ${
     };
     return {
       replicas: endpoints,
+      layout,
+      cluster: clusterName,
       name,
       stop,
       async stopReplica(index) {

package/src/clickhouse/plan/cluster-drift.e2e.test.ts

@@ -0,0 +1,117 @@
+/**
+ * Drift on a multi-shard cluster (#3664), against a scratch cluster of the
+ * pinned image: two shards (two replicas and one server) with Keeper and a
+ * cluster `chant` over all three, the profile naming the first server with
+ * topology `cluster:chant`.
+ *
+ * - The schema applied `ON CLUSTER`, with a `Distributed` table declared with
+ *   unquoted identifiers, reads as no drift: the server's quoted arguments
+ *   are the same arguments.
+ * - A TTL changed on shard 2's server alone, without `ON CLUSTER`, is drift,
+ *   seen on that server, though the profile's server still holds the
+ *   declaration.
+ *
+ * Runs the sql lexicon's deep reader and core's deep diff, as
+ * `chant lifecycle diff --live` does. 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 { diffDeepObservation } from "@intentius/chant/lifecycle/deep-observe";
+import { normalizeDeepObservation } from "@intentius/chant/deep-observation";
+import { dockerAvailable, startScratchCluster, type ScratchCluster } from "../container";
+import { clickhouseQuery } from "../http";
+import { clickhouseImage } from "../../spec/pin";
+import { clickhouseApply, toApplyResult } from "../../op/activities/clickhouse-apply";
+import { normalizeApply } from "@intentius/chant/apply";
+import { database, table } from "../entities";
+import { observeResourcesDeep, sqlDeepNormalizationHooks } from "./deep";
+
+const enabled = await dockerAvailable();
+const DB = "chant_e2e_3664";
+let cluster: ScratchCluster | undefined;
+const dir = mkdtempSync(join(tmpdir(), "chant-sql-cluster-drift-"));
+
+const DB_DDL = `CREATE DATABASE ${DB}`;
+const EVENTS_DDL = `CREATE TABLE ${DB}.events
+(
+  id UInt64,
+  ts DateTime
+)
+ENGINE = MergeTree
+ORDER BY id
+TTL ts + INTERVAL 30 DAY`;
+const EVENTS_ALL_DDL = `CREATE TABLE ${DB}.events_all
+(
+  id UInt64,
+  ts DateTime
+)
+ENGINE = Distributed(chant, ${DB}, events, id)`;
+
+const config = () => ({ ownership: { stack: "e2e", env: "test" }, sql: { profiles: { e2e: { url: cluster!.replicas[0]!.url, topology: "cluster:chant" } } } });
+const tag = (fn: (strings: TemplateStringsArray) => unknown, ddl: string) => fn(Object.assign([ddl], { raw: [ddl] }) as unknown as TemplateStringsArray) as unknown as { entityType: string; props: Record<string, unknown> };
+
+const ENTITIES = new Map([
+  ["db", tag(database, DB_DDL)],
+  ["events", tag(table, EVENTS_DDL)],
+  ["eventsAll", tag(table, EVENTS_ALL_DDL)],
+]);
+
+async function drift() {
+  const entities = new Map([...ENTITIES].map(([k, v]) => [k, { entityType: v.entityType, props: v.props }]));
+  const live = await observeResourcesDeep({ environment: "e2e", entityNames: [...entities.keys()], entities, config: config(), env: {} });
+  return diffDeepObservation(entities, normalizeDeepObservation(live), sqlDeepNormalizationHooks).drifted;
+}
+
+beforeAll(async () => {
+  if (!enabled) return;
+  cluster = await startScratchCluster(clickhouseImage(), { shards: [2, 1], cluster: "chant", namePrefix: "chant-sql-cluster-drift" });
+}, 600_000);
+
+afterAll(async () => {
+  await cluster?.stop();
+  rmSync(dir, { recursive: true, force: true });
+});
+
+describe.skipIf(!enabled)("drift on a two-shard cluster (#3664)", () => {
+  test("applied ON CLUSTER, with unquoted Distributed arguments, it reads as no drift", async () => {
+    const build = join(dir, "schema.json");
+    writeFileSync(
+      build,
+      JSON.stringify({
+        dialect: "clickhouse",
+        applyOrder: ["db", "events", "eventsAll"],
+        objects: [
+          { export: "db", type: "ClickHouse::Database", ddl: DB_DDL, dependsOn: [] },
+          { export: "events", type: "ClickHouse::Table", ddl: EVENTS_DDL, dependsOn: ["db"] },
+          { export: "eventsAll", type: "ClickHouse::Table", ddl: EVENTS_ALL_DDL, dependsOn: ["events"] },
+        ],
+      }),
+    );
+    const applied = normalizeApply(toApplyResult(await clickhouseApply({ buildPath: build, environment: "e2e" }, undefined, { config: config(), env: {}, log: () => undefined })));
+    expect(applied.notAttempted).toEqual([]);
+    // Every server has both tables.
+    for (const endpoint of cluster!.replicas) {
+      const rows = await clickhouseQuery<{ name: string }>(endpoint, `SELECT name FROM system.tables WHERE database = '${DB}' ORDER BY name`);
+      expect(rows.map((r) => r.name)).toEqual(["events", "events_all"]);
+    }
+    expect(await drift()).toEqual([]);
+  }, 300_000);
+
+  test("a TTL changed on shard 2 alone is drift, seen on that server", async () => {
+    const shard2 = cluster!.layout.findIndex((l) => l.shard === "s2");
+    await clickhouseQuery(cluster!.replicas[shard2]!, `ALTER TABLE ${DB}.events MODIFY TTL ts + INTERVAL 7 DAY`);
+    // The profile's server still holds the declaration.
+    const [mine] = await clickhouseQuery<{ q: string }>(cluster!.replicas[0]!, `SELECT create_table_query AS q FROM system.tables WHERE database = '${DB}' AND name = 'events'`);
+    expect(mine!.q).toContain("toIntervalDay(30)");
+
+    const drifted = await drift();
+    expect(drifted.map((d) => d.name)).toEqual(["events"]);
+    const ttl = drifted[0]!.changes.find((c) => c.path.startsWith("ttl"));
+    expect(ttl, JSON.stringify(drifted[0]!.changes)).toBeDefined();
+    expect(String(ttl!.live)).toMatch(/7/);
+    expect(ttl!.seenOn).toBe(cluster!.layout[shard2]!.host);
+  }, 300_000);
+});