@intentius/chant-lexicon-sql 0.114.1 → 0.115.0

package/src/op/activities/clickhouse-rebuild.ts

@@ -12,9 +12,9 @@ import type { ChantConfig } from "@intentius/chant/config";
 import { currentOpRun, parseDuration } from "@intentius/chant/op";
 import { bindClickHouse } from "../../clickhouse/live/bind";
 import { declaredObjects } from "../../clickhouse/apply/apply";
-import { declaredTable, observeRebuild, rebuildPlanDigest } from "../../clickhouse/rebuild/observe";
+import { declaredTable, observeRebuild, rebuildPlanDigest, RebuildRefusal } from "../../clickhouse/rebuild/observe";
 import { backfill, type BackfillDeps, type BackfillResult } from "../../clickhouse/rebuild/backfill";
-import { verifyRebuild, type VerifyResult } from "../../clickhouse/rebuild/verify";
+import { RebuildVerificationError, verifyRebuild, type VerifyResult } from "../../clickhouse/rebuild/verify";
 import {
   compensate,
   createNewTable,
@@ -32,6 +32,7 @@ import {
 } from "../../clickhouse/rebuild/steps";
 import type { ClickHouseRebuildArgs } from "../../clickhouse/rebuild/op";
 import { CLASSIFIER_RULES } from "../../clickhouse/plan/rules";
+import { clusterSharding } from "../../clickhouse/rebuild/shards";
 import { resolveMarker } from "./clickhouse-apply";
 
 export type { ClickHouseRebuildArgs } from "../../clickhouse/rebuild/op";
@@ -61,6 +62,7 @@ export async function rebuildRun(args: ClickHouseRebuildArgs, signal: AbortSigna
   const target = await bindClickHouse({ ...(args.environment !== undefined ? { environment: args.environment } : {}), config: config ?? {}, ...(deps.env ? { env: deps.env } : {}) });
   const declared = declaredTable(declaredObjects(readFileSync(resolve(cwd, args.buildPath), "utf8"), target.defaultDatabase, target.topology), args.table);
   const runId = currentOpRun()?.runId;
+  const sharding = await clusterSharding(target);
   return {
     target,
     declared,
@@ -72,9 +74,28 @@ export async function rebuildRun(args: ClickHouseRebuildArgs, signal: AbortSigna
     log: deps.log ?? ((line: string) => console.log(line)),
     ...(signal ? { signal } : {}),
     ...(runId ? { runId } : {}),
+    ...(sharding ? { sharding } : {}),
   };
 }
 
+/**
+ * With `onFailure: "keep"` (#3658) no onFailure drops the new table, so a
+ * step that fails says what a person does instead: a refusal or a failed
+ * verification would otherwise fail every run after it the same way.
+ */
+async function noting<T>(args: ClickHouseRebuildArgs, fn: () => Promise<T>): Promise<T> {
+  try {
+    return await fn();
+  } catch (err) {
+    if (args.keepOnFailure && (err instanceof RebuildRefusal || err instanceof RebuildVerificationError)) {
+      err.message +=
+        ` This rebuild keeps its new table on failure (onFailure: "keep"), so nothing drops it: ` +
+        `drop ${args.table}__chant_new and ${args.table}__chant_dual by hand to start again from a new table.`;
+    }
+    throw err;
+  }
+}
+
 export interface RebuildPlanResult {
   state: "rebuild" | "swapped" | "done";
   table: string;
@@ -87,6 +108,10 @@ export interface RebuildPlanResult {
 
 /** Plan: classify the table's change against the server and say how far the rebuild has got. */
 export async function clickhouseRebuildPlan(args: ClickHouseRebuildArgs, signal?: AbortSignal, deps: ClickHouseRebuildDeps = {}): Promise<RebuildPlanResult> {
+  return noting(args, () => plan(args, signal, deps));
+}
+
+async function plan(args: ClickHouseRebuildArgs, signal: AbortSignal | undefined, deps: ClickHouseRebuildDeps): Promise<RebuildPlanResult> {
   const run = await rebuildRun(args, signal, deps);
   const o = await observeRebuild(run.target, run.declared, run.marker);
   const changes = o.changes.map((c) => `${c.rule} ${c.field}${c.before !== undefined || c.after !== undefined ? `: ${c.before ?? "none"} -> ${c.after ?? "none"}` : ""}`);
@@ -103,23 +128,23 @@ export async function clickhouseRebuildPlan(args: ClickHouseRebuildArgs, signal?
 }
 
 export async function clickhouseRebuildCreate(args: ClickHouseRebuildArgs, signal?: AbortSignal, deps: ClickHouseRebuildDeps = {}): Promise<CreateResult> {
-  return createNewTable(await rebuildRun(args, signal, deps));
+  return noting(args, async () => createNewTable(await rebuildRun(args, signal, deps)));
 }
 
 export async function clickhouseRebuildDualWrite(args: ClickHouseRebuildArgs, signal?: AbortSignal, deps: ClickHouseRebuildDeps = {}): Promise<DualWriteResult> {
-  return startDualWrite(await rebuildRun(args, signal, deps));
+  return noting(args, async () => startDualWrite(await rebuildRun(args, signal, deps)));
 }
 
 export async function clickhouseRebuildBackfill(args: ClickHouseRebuildArgs, signal?: AbortSignal, deps: ClickHouseRebuildDeps = {}): Promise<BackfillResult> {
-  return backfill(await rebuildRun(args, signal, deps), deps.backfill);
+  return noting(args, async () => backfill(await rebuildRun(args, signal, deps), deps.backfill));
 }
 
 export async function clickhouseRebuildVerify(args: ClickHouseRebuildArgs, signal?: AbortSignal, deps: ClickHouseRebuildDeps = {}): Promise<VerifyResult> {
-  return verifyRebuild(await rebuildRun(args, signal, deps));
+  return noting(args, async () => verifyRebuild(await rebuildRun(args, signal, deps)));
 }
 
 export async function clickhouseRebuildSwap(args: ClickHouseRebuildArgs, signal?: AbortSignal, deps: ClickHouseRebuildDeps = {}): Promise<SwapResult> {
-  return swapTables(await rebuildRun(args, signal, deps));
+  return noting(args, async () => swapTables(await rebuildRun(args, signal, deps)));
 }
 
 export async function clickhouseRebuildRetain(args: ClickHouseRebuildArgs, signal?: AbortSignal, deps: ClickHouseRebuildDeps = {}): Promise<RetainResult> {

package/src/op/activities/index.ts

@@ -4,8 +4,12 @@
  * applier (`clickhouseApply`, #3208), the Postgres applier (`postgresApply`,
  * #3280) and their envelope projection (`toApplyResult`, one for both), which
  * core's apply activity looks up by name for the `clickhouse` and `postgres`
- * targets, the emulator lifecycles, and the steps of the two migration Ops.
+ * targets, the emulator lifecycles, the steps of the two migration Ops, and
+ * the receipt store and SQL step of an Op of `effect()` batches.
  */
+import type { ReceiptReadArgs, ReceiptStalenessArgs, ReceiptWriteArgs } from "@intentius/chant/op/receipt-store";
+import { sqlReceiptActivities } from "../../receipts";
+
 export { clickhouseApply, toApplyResult, resolveMarker } from "./clickhouse-apply";
 export type { ClickHouseApplyArgs, ClickHouseApplyDeps, ClickHouseApplyOutcome } from "./clickhouse-apply";
 export { clickhouseUp, clickhouseDown, CLICKHOUSE_EMULATOR, CLICKHOUSE_EMULATOR_SPEC } from "./clickhouse-emulator";
@@ -13,11 +17,24 @@ export { postgresApply } from "./postgres-apply";
 export type { PostgresApplyArgs, PostgresApplyDeps, PostgresApplyOutcome } from "./postgres-apply";
 export { postgresUp, postgresDown, POSTGRES_EMULATOR, POSTGRES_EMULATOR_SPEC } from "./postgres-emulator";
 
+// effect() steps (#3657): their receipts are kept on the environment's
+// database server (../../receipts.ts, `chant_receipts.receipts`), and
+// `sqlExec` runs a batch's SQL there. The receipt activities are fallbacks
+// (core's ACTIVITY_FALLBACKS): those names are global to a run, and a project
+// that also lists aws or k8s keeps its receipts in that lexicon's row.
+
+/** The activities this module provides only when no other configured lexicon does. */
+export const ACTIVITY_FALLBACKS: readonly string[] = ["receiptRead", "receiptWrite", "receiptStaleness"];
+// Bound per call: the environment (`chant run --env`) and the project are read when a step runs.
+export const receiptRead = (args: ReceiptReadArgs, signal?: AbortSignal) => sqlReceiptActivities().receiptRead(args, signal);
+export const receiptWrite = (args: ReceiptWriteArgs, signal?: AbortSignal) => sqlReceiptActivities().receiptWrite(args, signal);
+export const receiptStaleness = (args: ReceiptStalenessArgs, signal?: AbortSignal) => sqlReceiptActivities().receiptStaleness(args, signal);
+export { sqlExec } from "./sql-exec";
+export type { SqlExecArgs, SqlExecResult, SqlExecDeps } from "./sql-exec";
+
 // The rebuild migration (#3198): one activity per step of ClickHouseRebuildOp
 // (../../clickhouse/rebuild/op.ts). Its receipts are kept in ClickHouse and
-// reached by the backfill directly, so this module exports no receiptRead or
-// receiptWrite: those names are global to a run and belong to the receipt row
-// of a project's aws or k8s lexicon.
+// reached by the backfill directly, with the copy's own identity.
 export {
   clickhouseRebuildPlan,
   clickhouseRebuildCreate,

package/src/op/activities/sql-exec.ts

@@ -0,0 +1,84 @@
+/**
+ * `sqlExec` (#3657): run SQL on the environment's database server, the step
+ * an `effect()` batch of a sql project is made of.
+ *
+ *     effect(EffectReceipt("country-202601", { effect: "country/202601", flavor: "existence" }), [
+ *       activity("sqlExec", { sql: "ALTER TABLE shop.orders UPDATE country = 'NL' WHERE toYYYYMM(ts) = 202601" }, "atMostOnce"),
+ *     ])
+ *
+ * The server is the one `effect()`'s receipts are kept on
+ * (`../../receipts.ts`): `sql.profiles.<env>` for the environment
+ * `chant run --env` sets, else `CLICKHOUSE_URL` or `POSTGRES_URL`. `environment`
+ * in the arguments names another. On Postgres the SQL runs on a connection of
+ * its own with the role's default `search_path`, as one implicit transaction;
+ * on ClickHouse, `settings` are sent with the query.
+ */
+
+import type { ChantConfig } from "@intentius/chant/config";
+import { clickhouseQuery } from "../../clickhouse/http";
+import { bindClickHouse } from "../../clickhouse/live/bind";
+import { resolveBoundTarget } from "../../postgres/live/bind";
+import { connectPostgres } from "../../postgres/live/client";
+import { environmentOf, receiptDialect } from "../../receipts";
+
+export interface SqlExecArgs {
+  /** The SQL to run: one statement on ClickHouse; one or more on Postgres. */
+  sql: string;
+  /** The chant environment whose server it runs on. Default: `CHANT_ENV`, then a literal `ownership.env`. */
+  environment?: string;
+  /** ClickHouse: query settings (`mutations_sync`, `max_execution_time`). */
+  settings?: Record<string, string | number>;
+  /** The project directory chant.config.ts is read from. Default: the working directory. */
+  cwd?: string;
+}
+
+export interface SqlExecResult {
+  dialect: "clickhouse" | "postgres";
+  /** Where the server binding came from: `sql.profiles.prod` or `env CLICKHOUSE_URL`. */
+  source: string;
+  /** Rows the statement returned (a `SELECT`); 0 for one that returns none. */
+  rows: number;
+}
+
+/** What a test may inject instead of the project's config and the process env. */
+export interface SqlExecDeps {
+  config?: Pick<ChantConfig, "sql" | "ownership">;
+  env?: Record<string, string | undefined>;
+  log?: (line: string) => void;
+}
+
+async function loadConfig(cwd: string): Promise<Pick<ChantConfig, "sql" | "ownership"> | undefined> {
+  try {
+    const { loadChantConfig } = await import("@intentius/chant/config");
+    return (await loadChantConfig(cwd)).config;
+  } catch {
+    return undefined;
+  }
+}
+
+export async function sqlExec(args: SqlExecArgs, signal?: AbortSignal, deps: SqlExecDeps = {}): Promise<SqlExecResult> {
+  if (typeof args?.sql !== "string" || args.sql.trim() === "") throw new Error('sqlExec: needs { sql: "<statement>" }');
+  signal?.throwIfAborted();
+  const env = deps.env ?? process.env;
+  const config = deps.config ?? (await loadConfig(args.cwd ?? process.cwd()));
+  const environment = environmentOf(args, config, env);
+  const log = deps.log ?? ((line: string) => console.log(line));
+  const where = environment !== undefined ? { environment } : {};
+  log(args.sql);
+  if (receiptDialect(config, environment, env) === "postgres") {
+    const target = await resolveBoundTarget({ ...where, config: config ?? {}, env });
+    const client = await connectPostgres(target.endpoint, { applicationName: "chant sqlExec" });
+    try {
+      // The catalog reader's empty search_path is not what a hand-written statement expects.
+      await client.query("RESET search_path");
+      const rows = await client.query(args.sql);
+      return { dialect: "postgres", source: target.source, rows: Array.isArray(rows) ? rows.length : 0 };
+    } finally {
+      await client.end();
+    }
+  }
+  const target = await bindClickHouse({ ...where, config: config ?? {}, env });
+  const settings = args.settings ? Object.fromEntries(Object.entries(args.settings).map(([k, v]) => [k, String(v)])) : undefined;
+  const rows = await clickhouseQuery(target.endpoint, args.sql, { ...(settings ? { settings } : {}), ...(signal ? { signal } : {}) });
+  return { dialect: "clickhouse", source: target.source, rows: rows.length };
+}

package/src/op/activity-contracts.ts

@@ -34,6 +34,7 @@ const rebuildArgs = z.strictObject({
   stack: z.string().optional(),
   ownershipEnv: z.string().optional(),
   cwd: z.string().optional(),
+  keepOnFailure: z.boolean().optional(),
 });
 
 const state = z.enum(["rebuild", "swapped", "done"]);
@@ -208,3 +209,17 @@ export const postgresMigrationCompensateContract = activityContract(
   z.object({ dropped: z.array(z.string()) }),
   tableEntity,
 );
+
+// ── effect() batches (#3657) ───────────────────────────────────────────
+
+/** `SqlExecArgs` (`./activities/sql-exec.ts`): one batch's SQL on the environment's server. */
+export const sqlExecContract = activityContract(
+  "sqlExec",
+  z.strictObject({
+    sql: z.string().min(1),
+    environment: z.string().optional(),
+    settings: z.record(z.string(), z.union([z.string(), z.number()])).optional(),
+    cwd: z.string().optional(),
+  }),
+  z.object({ dialect: z.enum(["clickhouse", "postgres"]), source: z.string(), rows: z.number() }),
+);

package/src/op/effect-receipts.e2e.test.ts

@@ -0,0 +1,277 @@
+/**
+ * A project that uses only the sql lexicon runs an Op of `effect()` batches
+ * with `chant run`, and its receipts are kept on the environment's server
+ * (#3657), end to end on both dialects.
+ *
+ * For each dialect, a project in a temporary directory declares an Op of
+ * three batches. Each batch is an `effect()` whose steps run SQL with
+ * `sqlExec`: the batch records itself in a log table. The second batch fails
+ * while a stop table holds a row. The first `chant run --env admin` runs the
+ * first batch, fails on the second, and leaves one receipt. With the stop
+ * row deleted, the second run skips the first batch (the log holds it once),
+ * runs the other two, and leaves three receipts, in
+ * `chant_receipts.receipts` under `chant_e2e_3657/admin/`. A third run runs
+ * nothing.
+ *
+ * The test's own objects are in the database (ClickHouse) or schema
+ * (Postgres) `chant_e2e_3657`; its receipts are the rows of
+ * `chant_receipts.receipts` whose address starts `chant_e2e_3657/`, deleted
+ * afterwards.
+ *
+ * The servers: `CHANT_SQL_RECEIPTS_CLICKHOUSE_URL` and
+ * `CHANT_SQL_RECEIPTS_POSTGRES_URL` (a `postgres://user@host:port/db` URL, with
+ * `CHANT_SQL_RECEIPTS_POSTGRES_PASSWORD`) name running ones, such as the
+ * servers `chant emulator up --lexicon sql` starts. Without them, each dialect
+ * starts a throwaway server at the same pin, and skips cleanly when Docker is
+ * not available.
+ */
+
+import { execFile } from "node:child_process";
+import { mkdirSync, mkdtempSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { dockerAvailable, startScratchServer, type ScratchServer } from "../clickhouse/container";
+import { clickhouseQuery, type ClickHouseEndpoint } from "../clickhouse/http";
+import { clickhouseImage } from "../spec/pin";
+import { startTestPostgres, type TestPostgres } from "../postgres/testing/server";
+import { connectPostgres, type PostgresClient, type PostgresEndpoint } from "../postgres/live/client";
+
+const exec = promisify(execFile);
+
+const REPO = join(import.meta.dirname, "../../../..");
+const BIN = join(REPO, "node_modules/.bin");
+const NAME = "chant_e2e_3657";
+const OP = "fill-batches";
+const ENV = "admin";
+const PREFIX = `${NAME}/${ENV}/`;
+
+const givenClickHouse = process.env.CHANT_SQL_RECEIPTS_CLICKHOUSE_URL;
+const givenPostgres = process.env.CHANT_SQL_RECEIPTS_POSTGRES_URL;
+const docker = givenClickHouse && givenPostgres ? false : await dockerAvailable();
+
+interface Run {
+  code: number;
+  output: string;
+}
+
+const strip = (s: string) => s.replace(/\u001b\[[0-9;]*m/g, "");
+
+/** A project directory chant can run in: the repository's `node_modules` linked in, and a git repository. */
+async function project(files: Record<string, string>, env: Record<string, string>) {
+  const dir = mkdtempSync(join(tmpdir(), "chant-sql-receipts-"));
+  symlinkSync(join(REPO, "node_modules"), join(dir, "node_modules"), "dir");
+  for (const [path, text] of Object.entries({
+    "package.json": JSON.stringify({ name: "sql-receipts-e2e", private: true, type: "module" }),
+    ".gitignore": "node_modules\ndist\n.chant\n",
+    ...files,
+  })) {
+    mkdirSync(join(dir, path, ".."), { recursive: true });
+    writeFileSync(join(dir, path), text);
+  }
+  const git = (...args: string[]) => exec("git", ["-c", "user.email=e2e@chant.invalid", "-c", "user.name=e2e", ...args], { cwd: dir });
+  await git("init", "-q");
+  await git("add", "-A");
+  await git("commit", "-qm", "the op");
+  const chant = async (...args: string[]): Promise<Run> => {
+    try {
+      const r = await exec(join(BIN, "chant"), args, {
+        cwd: dir,
+        env: { ...process.env, ...env, PATH: `${BIN}:${process.env.PATH ?? ""}` },
+        maxBuffer: 16 * 1024 * 1024,
+      });
+      return { code: 0, output: strip(`${r.stdout}${r.stderr}`) };
+    } catch (err) {
+      const e = err as { code?: number; stdout?: string; stderr?: string };
+      return { code: typeof e.code === "number" ? e.code : 1, output: strip(`${e.stdout ?? ""}${e.stderr ?? ""}`) };
+    }
+  };
+  return { dir, chant };
+}
+
+const config = (sql: Record<string, unknown>) => `import type { ChantConfig } from "@intentius/chant";
+import "@intentius/chant-lexicon-sql";
+
+export default {
+  lexicons: ["sql"],
+  ownership: { stack: "${NAME}", env: "${ENV}" },
+  sql: ${JSON.stringify(sql, null, 2)},
+} satisfies ChantConfig;
+`;
+
+/** The Op: three batches; each runs `stop` (which fails while the stop table holds a row) and then `record`. */
+const opFile = (stop: string, record: (batch: string) => string) => `import { EffectReceipt } from "@intentius/chant";
+import { Op, activity, effect, phase } from "@intentius/chant/op";
+
+const batch = (b: string, steps: ReturnType<typeof activity>[]) =>
+  effect(EffectReceipt(\`fill-\${b}\`, { effect: \`fill/\${b}\`, flavor: "existence" }), steps);
+const record = (b: string) => activity("sqlExec", { sql: ${JSON.stringify(record("__B__"))}.replace("__B__", b) }, "atMostOnce");
+
+const op = Op({
+  name: "${OP}",
+  overview: "three batches, each with its receipt",
+  phases: [
+    phase("Fill", [
+      batch("b1", [record("b1")]),
+      batch("b2", [activity("sqlExec", { sql: ${JSON.stringify(stop)} }, "atMostOnce"), record("b2")]),
+      batch("b3", [record("b3")]),
+    ]),
+  ],
+});
+export default op;
+`;
+
+/**
+ * The shared scenario. `log` reads the batches the log table holds, in
+ * order; `receipts` the receipt addresses under the test's prefix; `unstop`
+ * deletes the stop row.
+ */
+async function failThenResume(p: Awaited<ReturnType<typeof project>>, io: { log: () => Promise<string[]>; receipts: () => Promise<string[]>; unstop: () => Promise<void> }) {
+  const first = await p.chant("run", OP, "--env", ENV);
+  expect(first.code, first.output).not.toBe(0);
+  expect(await io.log()).toEqual(["b1"]);
+  expect(await io.receipts()).toEqual([`${PREFIX}fill/b1`]);
+
+  await io.unstop();
+  const second = await p.chant("run", OP, "--env", ENV);
+  expect(second.code, second.output).toBe(0);
+  // b1 ran once: the second run read its receipt and skipped it.
+  expect(await io.log()).toEqual(["b1", "b2", "b3"]);
+  expect(await io.receipts()).toEqual([`${PREFIX}fill/b1`, `${PREFIX}fill/b2`, `${PREFIX}fill/b3`]);
+
+  const third = await p.chant("run", OP, "--env", ENV);
+  expect(third.code, third.output).toBe(0);
+  expect(await io.log()).toEqual(["b1", "b2", "b3"]);
+}
+
+// ── ClickHouse ──────────────────────────────────────────────────────────────
+
+describe.skipIf(!givenClickHouse && !docker)("effect() batches on ClickHouse keep their receipts in chant_receipts.receipts (#3657)", () => {
+  let server: ScratchServer | undefined;
+  let admin: ClickHouseEndpoint;
+  let p: Awaited<ReturnType<typeof project>>;
+  const q = <T = Record<string, unknown>>(sql: string) => clickhouseQuery<T>(admin, sql);
+  const forget = async () => {
+    const [t] = await q<{ n: string }>("SELECT count() AS n FROM system.tables WHERE database = 'chant_receipts' AND name = 'receipts'");
+    if (Number(t?.n ?? 0) > 0) await clickhouseQuery(admin, `ALTER TABLE chant_receipts.receipts DELETE WHERE startsWith(address, '${NAME}/')`, { settings: { mutations_sync: "1" } });
+  };
+
+  beforeAll(async () => {
+    if (givenClickHouse) admin = { url: givenClickHouse };
+    else {
+      server = await startScratchServer(clickhouseImage(), { namePrefix: "chant-sql-receipts" });
+      admin = server.endpoint;
+    }
+    await q(`DROP DATABASE IF EXISTS ${NAME} SYNC`);
+    await forget();
+    await q(`CREATE DATABASE ${NAME}`);
+    await q(`CREATE TABLE ${NAME}.log (batch String, at DateTime64(3) DEFAULT now64(3)) ENGINE = MergeTree ORDER BY at`);
+    await q(`CREATE TABLE ${NAME}.stop (x UInt8) ENGINE = MergeTree ORDER BY x`);
+    await q(`INSERT INTO ${NAME}.stop VALUES (1)`);
+    p = await project(
+      {
+        "chant.config.ts": config({ dialect: "clickhouse", profiles: { [ENV]: { url: admin.url, databases: [NAME] } } }),
+        "ops/fill.op.ts": opFile(`SELECT throwIf(count() > 0, 'stopped') FROM ${NAME}.stop`, (b) => `INSERT INTO ${NAME}.log (batch) VALUES ('${b}')`),
+      },
+      {},
+    );
+  }, 600_000);
+
+  afterAll(async () => {
+    if (admin) {
+      await q(`DROP DATABASE IF EXISTS ${NAME} SYNC`).catch(() => undefined);
+      await forget().catch(() => undefined);
+    }
+    await server?.stop();
+    if (p) rmSync(p.dir, { recursive: true, force: true });
+  });
+
+  test("a failed run keeps the finished batch's receipt; the rerun skips it", async () => {
+    await failThenResume(p, {
+      log: async () => (await q<{ batch: string }>(`SELECT batch FROM ${NAME}.log ORDER BY at, batch`)).map((r) => r.batch),
+      receipts: async () =>
+        (await q<{ address: string }>(`SELECT DISTINCT address FROM chant_receipts.receipts WHERE startsWith(address, '${NAME}/') ORDER BY address`)).map((r) => r.address),
+      unstop: async () => {
+        await q(`TRUNCATE TABLE ${NAME}.stop`);
+      },
+    });
+    // The receipts database is chant's: its comment carries the receipts key.
+    const [db] = await q<{ comment: string }>("SELECT comment FROM system.databases WHERE name = 'chant_receipts'");
+    expect(db?.comment).toContain("receipts=effects");
+  }, 600_000);
+});
+
+// ── Postgres ────────────────────────────────────────────────────────────────
+
+describe.skipIf(!givenPostgres && !docker)("effect() batches on Postgres keep their receipts in chant_receipts.receipts (#3657)", () => {
+  let server: TestPostgres | undefined;
+  let endpoint: PostgresEndpoint;
+  let admin: PostgresClient;
+  let p: Awaited<ReturnType<typeof project>>;
+  /** Whether chant_receipts was there before the test: the test drops it afterwards only when it made it. */
+  let hadReceiptsSchema = true;
+  const q = <T = Record<string, unknown>>(sql: string) => admin.query<T>(sql);
+  const forget = async () => {
+    const [t] = await q<{ present: boolean }>("SELECT pg_catalog.to_regclass('chant_receipts.receipts') IS NOT NULL AS present");
+    if (t?.present) await q(`DELETE FROM chant_receipts.receipts WHERE starts_with(address, '${NAME}/')`);
+  };
+
+  beforeAll(async () => {
+    if (givenPostgres) endpoint = { url: givenPostgres, password: process.env.CHANT_SQL_RECEIPTS_POSTGRES_PASSWORD };
+    else {
+      server = await startTestPostgres();
+      endpoint = server.endpoint();
+    }
+    admin = await connectPostgres(endpoint);
+    const [s] = await q<{ n: number }>("SELECT count(*)::int AS n FROM pg_catalog.pg_namespace WHERE nspname = 'chant_receipts'");
+    hadReceiptsSchema = (s?.n ?? 0) > 0;
+    await q(`DROP SCHEMA IF EXISTS ${NAME} CASCADE`);
+    await forget();
+    await q(`CREATE SCHEMA ${NAME}`);
+    await q(`CREATE TABLE ${NAME}.log (id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY, batch text NOT NULL)`);
+    await q(`CREATE TABLE ${NAME}.stop (x int)`);
+    await q(`INSERT INTO ${NAME}.stop VALUES (1)`);
+    p = await project(
+      {
+        "chant.config.ts": config({
+          dialect: "postgres",
+          profiles: { [ENV]: { url: endpoint.url, password: { env: "ADMIN_PASSWORD" }, schemas: [NAME] } },
+        }),
+        "ops/fill.op.ts": opFile(
+          `DO $$ BEGIN IF EXISTS (SELECT 1 FROM ${NAME}.stop) THEN RAISE EXCEPTION 'stopped'; END IF; END $$`,
+          (b) => `INSERT INTO ${NAME}.log (batch) VALUES ('${b}')`,
+        ),
+      },
+      { ADMIN_PASSWORD: endpoint.password ?? "" },
+    );
+  }, 600_000);
+
+  afterAll(async () => {
+    if (admin) {
+      await q(`DROP SCHEMA IF EXISTS ${NAME} CASCADE`).catch(() => undefined);
+      await forget().catch(() => undefined);
+      if (!hadReceiptsSchema) await q("DROP SCHEMA IF EXISTS chant_receipts CASCADE").catch(() => undefined);
+      await admin.end();
+    }
+    await server?.stop();
+    if (p) rmSync(p.dir, { recursive: true, force: true });
+  });
+
+  test("a failed run keeps the finished batch's receipt; the rerun skips it", async () => {
+    await failThenResume(p, {
+      log: async () => (await q<{ batch: string }>(`SELECT batch FROM ${NAME}.log ORDER BY id`)).map((r) => r.batch),
+      receipts: async () =>
+        (await q<{ address: string }>(`SELECT address FROM chant_receipts.receipts WHERE starts_with(address, '${NAME}/') ORDER BY address`)).map((r) => r.address),
+      unstop: async () => {
+        await q(`DELETE FROM ${NAME}.stop`);
+      },
+    });
+    // The schema and the table are chant's: their comments carry the receipts key.
+    const [c] = await q<{ schema: string; tbl: string }>(
+      "SELECT pg_catalog.obj_description('chant_receipts'::regnamespace, 'pg_namespace') AS schema, pg_catalog.obj_description('chant_receipts.receipts'::regclass, 'pg_class') AS tbl",
+    );
+    expect(c?.schema).toContain("receipts=effects");
+    expect(c?.tbl).toContain("receipts=effects");
+  }, 600_000);
+});

package/src/postgres/live/catalog.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.
@@ -199,6 +199,8 @@ export async function readLiveSchema(client: PostgresClient, scope: SchemaScope
     );
     for (const r of rows) {
       const name = String(r.name);
+      // chant's own receipts schema (`../../receipts.ts`), like the receipts tables.
+      if (hasChantTrailerKey(str(r.comment), [RECEIPTS_TRAILER_KEY])) continue;
       out.push({
         type: POSTGRES_ENTITY_TYPES.schema,
         name,

package/src/postgres/migrate/migrate.test.ts

@@ -102,12 +102,13 @@ describe("PostgresMigrationOp", () => {
     }
   });
 
-  test("every migration step is an activity the sql lexicon exports, and none is a receipt activity", () => {
+  test("every migration step is an activity the sql lexicon exports, and the receipt activities are only fallbacks", () => {
     const exported = new Set(Object.entries(activitiesModule).filter(([, v]) => typeof v === "function").map(([k]) => k));
     const steps = propsOf(BASE).phases.flatMap((p) => p.steps).filter((s) => s.kind === "activity" && (s as { fn: string }).fn.startsWith("postgresMigration"));
     expect(steps).toHaveLength(9);
     for (const s of steps) expect(exported.has((s as { fn: string }).fn)).toBe(true);
-    expect(exported.has("receiptRead")).toBe(false);
+    // The receipt activities are exported for effect() steps only as fallbacks (#3657), so they never take over another lexicon's receipt row.
+    expect((activitiesModule as { ACTIVITY_FALLBACKS?: readonly string[] }).ACTIVITY_FALLBACKS).toEqual(["receiptRead", "receiptWrite", "receiptStaleness"]);
   });
 });
 

package/src/postgres/migrate/receipts.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 { OWNERSHIP_MANAGED_BY_VALUE } from "@intentius/chant/ownership";
@@ -48,10 +48,10 @@ export { receiptAddress } from "../../core/receipts";
 
 /** A receipts table chant did not make: a user's table under the same name. */
 export class ReceiptsTableConflict extends Error {
-  constructor(schema: string) {
+  constructor(schema: string, table: string = POSTGRES_RECEIPTS_TABLE) {
     super(
-      `${schema}.${POSTGRES_RECEIPTS_TABLE} exists and is not chant's receipts table (its comment carries no receipts marker). ` +
-        `The migration keeps its receipts under that name, so it stops rather than write into it; rename the table.`,
+      `${schema}.${table} exists and is not chant's receipts table (its comment carries no receipts marker). ` +
+        `chant keeps its receipts under that name, so it stops rather than write into it; rename the table.`,
     );
     this.name = "ReceiptsTableConflict";
   }
@@ -70,10 +70,18 @@ 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 function postgresReceiptStore(client: PostgresClient, schema: string, identity: { stack?: string; env?: string }, opts: { runId?: string } = {}): PostgresReceiptStore {
-  const table = `${quoteIdent(schema)}.${quoteIdent(POSTGRES_RECEIPTS_TABLE)}`;
+export function postgresReceiptStore(
+  client: PostgresClient,
+  schema: string,
+  identity: { stack?: string; env?: string },
+  opts: { runId?: string; table?: string } = {},
+): PostgresReceiptStore {
+  const name = opts.table ?? POSTGRES_RECEIPTS_TABLE;
+  const table = `${quoteIdent(schema)}.${quoteIdent(name)}`;
   let ensured = false;
   const comment = async (): Promise<string | null | undefined> => {
     const [row] = await client.query<{ present: boolean; comment: string | null }>(
@@ -87,7 +95,7 @@ export function postgresReceiptStore(client: PostgresClient, schema: string, ide
     if (ensured) return true;
     const c = await comment();
     if (c === undefined) return false;
-    if (!hasChantTrailerKey(c ?? undefined, [RECEIPTS_TRAILER_KEY])) throw new ReceiptsTableConflict(schema);
+    if (!hasChantTrailerKey(c ?? undefined, [RECEIPTS_TRAILER_KEY])) throw new ReceiptsTableConflict(schema, name);
     return true;
   };
   const address = (receipt: EffectReceiptRef) => receiptAddress(identity, receipt.effect);