@intentius/sql-yodeler 0.0.0-stage → 0.2.0

package/dist/replay/report.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The replay check's result for people (text) and for tools (JSON), and its
+ * exit code.
+ */
+import { type ReplayChange, type ReplayResult } from "./replay.js";
+/** 0 when every migration replays to its recorded schema; 1 for a difference or a statement the server refused; 2 for a step the replay cannot run. */
+export declare function replayExitCode(result: ReplayResult): number;
+/** One difference: the object, the field, and the replay's value against the record's. */
+export declare function describeChange(c: ReplayChange): string;
+/** The failure in one paragraph, naming the first migration that fails; `undefined` when the replay matched. For `yodel lint`. */
+export declare function replayFailure(result: ReplayResult): {
+    migration: string;
+    message: string;
+} | undefined;
+/** The result as text. */
+export declare function renderReplay(result: ReplayResult): string;
+/** The result as JSON. */
+export declare function replayJson(result: ReplayResult): Record<string, unknown>;

package/dist/replay/report.js

@@ -0,0 +1,72 @@
+/**
+ * The replay check's result for people (text) and for tools (JSON), and its
+ * exit code.
+ */
+import { MIGRATIONS_DIR, MIGRATION_JSON, MIGRATION_SQL } from "../migrations/index.js";
+import { UNREPLAYABLE } from "./replay.js";
+/** 0 when every migration replays to its recorded schema; 1 for a difference or a statement the server refused; 2 for a step the replay cannot run. */
+export function replayExitCode(result) {
+    if (result.outcome === "matches")
+        return 0;
+    if (result.outcome === "unreplayable")
+        return UNREPLAYABLE;
+    return 1;
+}
+const shown = (v) => (v === undefined ? "(absent)" : v);
+/** One difference: the object, the field, and the replay's value against the record's. */
+export function describeChange(c) {
+    return `${c.object}: ${c.field}: replay has ${shown(c.before)}, ${MIGRATION_JSON} records ${shown(c.after)} (${c.rule})`;
+}
+/** The failure in one paragraph, naming the first migration that fails; `undefined` when the replay matched. For `yodel lint`. */
+export function replayFailure(result) {
+    const before = result.matched.length > 0 ? ` The ${String(result.matched.length)} migration${result.matched.length === 1 ? "" : "s"} before it replayed to ${result.matched.length === 1 ? "its" : "their"} recorded schema${result.matched.length === 1 ? "" : "s"}.` : "";
+    switch (result.outcome) {
+        case "matches":
+            return undefined;
+        case "differs": {
+            const m = result.migration;
+            const n = result.changes.length;
+            const skipped = m.skipped.length > 0 ? `\nSteps not replayed: ${m.skipped.join("; ")}.` : "";
+            return {
+                migration: m.id,
+                message: `${m.id}: replaying the history through it does not give the schema it records (${MIGRATIONS_DIR}/${m.id}/${MIGRATION_JSON}); ${String(n)} difference${n === 1 ? "" : "s"}:\n` +
+                    result.changes.map((c) => `  ${describeChange(c)}`).join("\n") +
+                    `\n${before.trim() ? `${before.trim()}\n` : ""}` +
+                    `Its statements (the steps in ${MIGRATION_JSON}, which ${MIGRATION_SQL} shows) and its recorded schema disagree: make the statements produce the schema, or record the schema they produce, then yodel repair the migration where it is already applied.${skipped}`,
+            };
+        }
+        case "failed":
+            return {
+                migration: result.migration,
+                message: `${result.migration}: statement ${String(result.step)} failed in the replay: ${result.error}.${before} The history does not apply to an empty database as written.`,
+            };
+        case "unreplayable":
+            return {
+                migration: result.migration,
+                message: `${result.migration}: step ${String(result.step)} cannot be replayed: ${result.reason}.${before} The migrations from it on are not checked.`,
+            };
+    }
+}
+/** The result as text. */
+export function renderReplay(result) {
+    const lines = [`Replay of ${String(result.total)} migration${result.total === 1 ? "" : "s"} (${result.dialect}) into ${result.where}`];
+    if (result.scope.length > 0)
+        lines.push(`  ${result.dialect === "postgres" ? "schemas" : "databases"}: ${result.scope.join(", ")}${result.reset ? " (emptied first)" : ""}${result.kept ? " (left in place)" : ""}`);
+    for (const m of result.matched) {
+        const extra = [...m.ran.map((r) => `ran ${r}`), ...m.skipped.map((s) => `skipped ${s}`)];
+        lines.push(`  ok      ${m.id} (${String(m.statements)} statement${m.statements === 1 ? "" : "s"}${extra.length > 0 ? `; ${extra.join("; ")}` : ""})`);
+    }
+    const failure = replayFailure(result);
+    if (!failure) {
+        lines.push(result.total === 0 ? "No migrations to replay." : "Every migration replays to its recorded schema.");
+        return `${lines.join("\n")}\n`;
+    }
+    lines.push(`  ${result.outcome.padEnd(7)} ${failure.migration}`, "", failure.message);
+    return `${lines.join("\n")}\n`;
+}
+/** The result as JSON. */
+export function replayJson(result) {
+    const failure = replayFailure(result);
+    return { ...result, ok: result.outcome === "matches", ...(failure ? { message: failure.message } : {}) };
+}
+//# sourceMappingURL=report.js.map

package/dist/replay/report.js.map

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

package/dist/replay/shared.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The replay empties every database (ClickHouse) or schema (Postgres) the
+ * history names on the server its profile binds. When another profile binds
+ * the same server and names one of those too (locally, `dev` and `replay`
+ * both on the emulator at 127.0.0.1), the replay would drop that profile's
+ * database: the one just applied to. So it refuses, naming the profile,
+ * even with `--reset`, unless that profile is named with
+ * `--reset-shared <profile>` (#12).
+ *
+ * Only profiles that resolve are compared: one whose credentials are not set
+ * in this shell (a CI job that holds only the replay server's) binds no
+ * server here, and the replay cannot reach its data through it.
+ */
+import { type Environment, type Project } from "../project.js";
+/** Another profile the replay would empty part of. */
+export interface SharedProfile {
+    profile: string;
+    /** `host:port` (ClickHouse) or `host:port/database` (Postgres). */
+    server: string;
+    /** The databases or schemas both name. */
+    names: string[];
+}
+/** A server URL as a comparable key: loopback names folded together, the default port filled in, no credentials. */
+export declare function serverKey(dialect: Project["dialect"], url: string): string;
+/** The other profiles on `env`'s server that name one of `scope`, the databases or schemas the replay empties. */
+export declare function sharedProfiles(project: Project, env: Environment, scope: readonly string[], processEnv?: NodeJS.ProcessEnv): Promise<SharedProfile[]>;
+/** Refuses a replay that would empty another profile's databases, unless each such profile is named in `allowed`. */
+export declare function refuseShared(env: Environment, shared: readonly SharedProfile[], allowed: readonly string[], dialect: Project["dialect"]): void;

package/dist/replay/shared.js

@@ -0,0 +1,77 @@
+/**
+ * The replay empties every database (ClickHouse) or schema (Postgres) the
+ * history names on the server its profile binds. When another profile binds
+ * the same server and names one of those too (locally, `dev` and `replay`
+ * both on the emulator at 127.0.0.1), the replay would drop that profile's
+ * database: the one just applied to. So it refuses, naming the profile,
+ * even with `--reset`, unless that profile is named with
+ * `--reset-shared <profile>` (#12).
+ *
+ * Only profiles that resolve are compared: one whose credentials are not set
+ * in this shell (a CI job that holds only the replay server's) binds no
+ * server here, and the replay cannot reach its data through it.
+ */
+import { YodelError } from "../project.js";
+import { environmentSettings } from "../config/settings.js";
+import { NOT_FRESH } from "./replay.js";
+const LOOPBACK = new Set(["localhost", "127.0.0.1", "::1", "[::1]"]);
+/** A server URL as a comparable key: loopback names folded together, the default port filled in, no credentials. */
+export function serverKey(dialect, url) {
+    let u;
+    try {
+        u = new URL(url);
+    }
+    catch {
+        return url;
+    }
+    const host = LOOPBACK.has(u.hostname) ? "127.0.0.1" : u.hostname.toLowerCase();
+    if (dialect === "postgres")
+        return `${host}:${u.port || "5432"}/${decodeURIComponent(u.pathname.replace(/^\/+/, "")) || "postgres"}`;
+    return `${host}:${u.port || (u.protocol === "https:" ? "8443" : "8123")}`;
+}
+async function bind(project, name, processEnv) {
+    if (project.dialect === "postgres") {
+        const { resolvePostgresTarget, isUnresolvedTarget } = await import("@intentius/chant-lexicon-sql/postgres/live/bind");
+        const t = resolvePostgresTarget({ environment: name, config: project.config, env: processEnv });
+        if (isUnresolvedTarget(t) || !t.source.startsWith("sql.profiles."))
+            return undefined;
+        return { key: serverKey("postgres", t.endpoint.url), names: t.schemas };
+    }
+    const { resolveClickHouseTarget, isUnresolvedTarget } = await import("@intentius/chant-lexicon-sql/clickhouse/live/bind");
+    const t = resolveClickHouseTarget({ environment: name, config: project.config, env: processEnv });
+    if (isUnresolvedTarget(t) || !t.source.startsWith("sql.profiles."))
+        return undefined;
+    return { key: serverKey("clickhouse", t.endpoint.url), names: t.databases };
+}
+/** The other profiles on `env`'s server that name one of `scope`, the databases or schemas the replay empties. */
+export async function sharedProfiles(project, env, scope, processEnv = process.env) {
+    const profiles = Object.keys(project.config.sql?.profiles ?? {});
+    const own = await bind(project, env.name, processEnv);
+    if (!own)
+        return [];
+    const shared = [];
+    for (const other of profiles) {
+        if (other === env.name)
+            continue;
+        const b = await bind(project, other, processEnv).catch(() => undefined);
+        if (!b || b.key !== own.key)
+            continue;
+        const history = environmentSettings(project, other, processEnv).historyDatabase;
+        const theirs = b.names === undefined ? undefined : new Set([...b.names, history]);
+        const names = scope.filter((s) => theirs === undefined || theirs.has(s));
+        if (names.length > 0)
+            shared.push({ profile: other, server: own.key, names });
+    }
+    return shared;
+}
+/** Refuses a replay that would empty another profile's databases, unless each such profile is named in `allowed`. */
+export function refuseShared(env, shared, allowed, dialect) {
+    const blocking = shared.filter((s) => !allowed.includes(s.profile));
+    if (blocking.length === 0)
+        return;
+    const what = dialect === "postgres" ? "schema" : "database";
+    const lines = blocking.map((s) => `${env.name} and ${s.profile} are the same server (${s.server}) and both name ${s.names.join(", ")}; the replay would drop ${s.profile}'s ${what}${s.names.length === 1 ? "" : "s"}, with or without --reset`);
+    throw new YodelError(`refused: ${lines.join("; ")}. Point ${env.name} at a throwaway server of its own (a second emulator on another port), ` +
+        `or, to empty ${blocking.map((s) => s.profile).join(" and ")} too, add ${blocking.map((s) => `--reset-shared ${s.profile}`).join(" ")}. Nothing was run.`, NOT_FRESH);
+}
+//# sourceMappingURL=shared.js.map

package/dist/replay/shared.js.map

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

package/dist/schemas.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The JSON Schemas of `yodel <command> --json` and of `yodel mcp`'s tool
+ * results. They are written beside the code, in `schemas/` at the package
+ * root, and ship in the package; the docs site serves them at their `$id`.
+ * test/schemas.test.ts validates each command's output against its schema.
+ *
+ * Within a version a schema only gains fields, and a reader ignores fields it
+ * does not know. Removing a field or changing what one means is a new version:
+ * a new `v<N>/` in every `$id`, and {@link SCHEMA_VERSION} moves with it.
+ */
+export declare const SCHEMA_VERSION = 1;
+/** Where the schemas are published; each `$id` is this plus `<name>.schema.json`. */
+export declare const SCHEMA_BASE: string;
+/** `schemas/` in the package: src/ and dist/ are both one level below it. */
+export declare const schemasDir: string;
+/** The schema of each command's `--json` output, by the command line that prints it. */
+export declare const COMMAND_SCHEMAS: {
+    readonly init: "init";
+    readonly plan: "plan";
+    readonly apply: "apply";
+    readonly new: "new";
+    readonly lint: "lint";
+    readonly "lint --rules": "lint-rules";
+    readonly status: "status";
+    readonly drift: "drift";
+    readonly rebase: "rebase";
+    readonly repair: "repair";
+};
+/** Every schema file: the commands', the definitions they share, and the MCP tool results. */
+export declare const SCHEMA_NAMES: readonly ["common", ...("lint" | "plan" | "status" | "apply" | "drift" | "init" | "new" | "lint-rules" | "rebase" | "repair")[], "mcp"];
+export type SchemaName = (typeof SCHEMA_NAMES)[number];
+export declare const schemaId: (name: SchemaName) => string;
+/** A schema as the package ships it. */
+export declare function readSchema(name: SchemaName): Record<string, unknown>;

package/dist/schemas.js

@@ -0,0 +1,38 @@
+/**
+ * The JSON Schemas of `yodel <command> --json` and of `yodel mcp`'s tool
+ * results. They are written beside the code, in `schemas/` at the package
+ * root, and ship in the package; the docs site serves them at their `$id`.
+ * test/schemas.test.ts validates each command's output against its schema.
+ *
+ * Within a version a schema only gains fields, and a reader ignores fields it
+ * does not know. Removing a field or changing what one means is a new version:
+ * a new `v<N>/` in every `$id`, and {@link SCHEMA_VERSION} moves with it.
+ */
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+export const SCHEMA_VERSION = 1;
+/** Where the schemas are published; each `$id` is this plus `<name>.schema.json`. */
+export const SCHEMA_BASE = `https://intentius.io/sql-yodeler/schemas/v${String(SCHEMA_VERSION)}/`;
+/** `schemas/` in the package: src/ and dist/ are both one level below it. */
+export const schemasDir = fileURLToPath(new URL("../schemas/", import.meta.url));
+/** The schema of each command's `--json` output, by the command line that prints it. */
+export const COMMAND_SCHEMAS = {
+    init: "init",
+    plan: "plan",
+    apply: "apply",
+    new: "new",
+    lint: "lint",
+    "lint --rules": "lint-rules",
+    status: "status",
+    drift: "drift",
+    rebase: "rebase",
+    repair: "repair",
+};
+/** Every schema file: the commands', the definitions they share, and the MCP tool results. */
+export const SCHEMA_NAMES = ["common", ...Object.values(COMMAND_SCHEMAS), "mcp"];
+export const schemaId = (name) => `${SCHEMA_BASE}${name}.schema.json`;
+/** A schema as the package ships it. */
+export function readSchema(name) {
+    return JSON.parse(readFileSync(`${schemasDir}${name}.schema.json`, "utf8"));
+}
+//# sourceMappingURL=schemas.js.map

package/dist/schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.js","sourceRoot":"","sources":["../src/schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAC;AAEhC,qFAAqF;AACrF,MAAM,CAAC,MAAM,WAAW,GAAG,6CAA6C,MAAM,CAAC,cAAc,CAAC,GAAG,CAAC;AAElG,6EAA6E;AAC7E,MAAM,CAAC,MAAM,UAAU,GAAG,aAAa,CAAC,IAAI,GAAG,CAAC,aAAa,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAEjF,wFAAwF;AACxF,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,IAAI,EAAE,MAAM;IACZ,IAAI,EAAE,MAAM;IACZ,KAAK,EAAE,OAAO;IACd,GAAG,EAAE,KAAK;IACV,IAAI,EAAE,MAAM;IACZ,cAAc,EAAE,YAAY;IAC5B,MAAM,EAAE,QAAQ;IAChB,KAAK,EAAE,OAAO;IACd,MAAM,EAAE,QAAQ;IAChB,MAAM,EAAE,QAAQ;CACR,CAAC;AAEX,8FAA8F;AAC9F,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,QAAQ,EAAE,GAAG,MAAM,CAAC,MAAM,CAAC,eAAe,CAAC,EAAE,KAAK,CAAU,CAAC;AAI1F,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,IAAgB,EAAU,EAAE,CAAC,GAAG,WAAW,GAAG,IAAI,cAAc,CAAC;AAE1F,wCAAwC;AACxC,MAAM,UAAU,UAAU,CAAC,IAAgB;IACzC,OAAO,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,GAAG,UAAU,GAAG,IAAI,cAAc,EAAE,MAAM,CAAC,CAA4B,CAAC;AACzG,CAAC"}

package/dist/server.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Which server a command reached, for the first line of its output (#11):
+ * `postgres 16.14 at 127.0.0.1:5432/postgres`. A wrong target (a native
+ * Postgres on localhost:5432 instead of the emulator) then shows in the
+ * header, by its address and its version.
+ *
+ * The address comes from the profile's URL, without credentials; the
+ * version is asked of the server. A server that does not answer the version
+ * query still gets its address.
+ */
+import type { Environment, Project, SqlDialect } from "./project.js";
+export interface ServerInfo {
+    dialect: SqlDialect;
+    /** `host:port/database` on Postgres, `host:port` on ClickHouse. */
+    address: string;
+    /** The server's own version string, first word: `16.14`, `25.3.2.39`. */
+    version?: string | undefined;
+}
+/** `postgres 16.14 at 127.0.0.1:5432/postgres`. */
+export declare function describeServer(s: ServerInfo): string;
+/** `host:port/database` (Postgres) or `host:port` (ClickHouse) from a server URL, with no credentials. */
+export declare function serverAddress(dialect: SqlDialect, url: string): string;
+/** The first word of a version string: `16.14 (Homebrew)` is `16.14`. */
+export declare const versionWord: (v: unknown) => string | undefined;
+/** Asks a Postgres connection its version. */
+export declare function postgresVersion(client: {
+    query<T>(sql: string): Promise<T[]>;
+}): Promise<string | undefined>;
+/** Asks a ClickHouse server its version. */
+export declare function clickhouseVersion(port: {
+    query<T>(sql: string): Promise<T[]>;
+}): Promise<string | undefined>;
+/** Runs `probe`, giving up quietly: the header is worth a line, not a failure. */
+export declare function softly<T>(probe: () => Promise<T>): Promise<T | undefined>;
+/**
+ * The server `sql.profiles.<env>` binds, with its version when it answers,
+ * for a command that does not hold its own connection (the declarative plan
+ * and apply, drift). Undefined when the profile binds no server.
+ */
+export declare function probeServer(project: Project, env: Environment, processEnv?: NodeJS.ProcessEnv): Promise<ServerInfo | undefined>;

package/dist/server.js

@@ -0,0 +1,87 @@
+/**
+ * Which server a command reached, for the first line of its output (#11):
+ * `postgres 16.14 at 127.0.0.1:5432/postgres`. A wrong target (a native
+ * Postgres on localhost:5432 instead of the emulator) then shows in the
+ * header, by its address and its version.
+ *
+ * The address comes from the profile's URL, without credentials; the
+ * version is asked of the server. A server that does not answer the version
+ * query still gets its address.
+ */
+/** `postgres 16.14 at 127.0.0.1:5432/postgres`. */
+export function describeServer(s) {
+    return `${s.dialect}${s.version ? ` ${s.version}` : ""} at ${s.address}`;
+}
+/** `host:port/database` (Postgres) or `host:port` (ClickHouse) from a server URL, with no credentials. */
+export function serverAddress(dialect, url) {
+    let u;
+    try {
+        u = new URL(url);
+    }
+    catch {
+        return url.replace(/\/\/[^@/]*@/, "//");
+    }
+    if (dialect === "postgres") {
+        const port = u.port || "5432";
+        const db = decodeURIComponent(u.pathname.replace(/^\/+/, "")) || "postgres";
+        return `${u.hostname}:${port}/${db}`;
+    }
+    const port = u.port || (u.protocol === "https:" ? "8443" : "8123");
+    return `${u.hostname}:${port}`;
+}
+/** The first word of a version string: `16.14 (Homebrew)` is `16.14`. */
+export const versionWord = (v) => (typeof v === "string" && v.trim() ? v.trim().split(/\s+/)[0] : undefined);
+/** Asks a Postgres connection its version. */
+export async function postgresVersion(client) {
+    const rows = await client.query("SHOW server_version");
+    return versionWord(rows[0]?.server_version);
+}
+/** Asks a ClickHouse server its version. */
+export async function clickhouseVersion(port) {
+    const rows = await port.query("SELECT version() AS version");
+    return versionWord(rows[0]?.version);
+}
+/** Runs `probe`, giving up quietly: the header is worth a line, not a failure. */
+export async function softly(probe) {
+    try {
+        return await probe();
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The server `sql.profiles.<env>` binds, with its version when it answers,
+ * for a command that does not hold its own connection (the declarative plan
+ * and apply, drift). Undefined when the profile binds no server.
+ */
+export async function probeServer(project, env, processEnv = process.env) {
+    return softly(async () => {
+        if (project.dialect === "postgres") {
+            const { resolvePostgresTarget, isUnresolvedTarget } = await import("@intentius/chant-lexicon-sql/postgres/live/bind");
+            const target = resolvePostgresTarget({ environment: env.name, config: project.config, env: processEnv });
+            if (isUnresolvedTarget(target))
+                return undefined;
+            const info = { dialect: "postgres", address: serverAddress("postgres", target.endpoint.url) };
+            const { connectPostgres } = await import("@intentius/chant-lexicon-sql/postgres/live/client");
+            const client = await softly(() => connectPostgres(target.endpoint, { applicationName: "yodel" }));
+            if (client) {
+                try {
+                    info.version = await softly(() => postgresVersion(client));
+                }
+                finally {
+                    await client.end();
+                }
+            }
+            return info;
+        }
+        const { resolveClickHouseTarget, isUnresolvedTarget } = await import("@intentius/chant-lexicon-sql/clickhouse/live/bind");
+        const target = resolveClickHouseTarget({ environment: env.name, config: project.config, env: processEnv });
+        if (isUnresolvedTarget(target))
+            return undefined;
+        const { httpPort } = await import("./history/client.js");
+        const port = await httpPort(target.endpoint);
+        return { dialect: "clickhouse", address: serverAddress("clickhouse", target.endpoint.url), version: await softly(() => clickhouseVersion(port)) };
+    });
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

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

package/dist/steps/backfill.d.ts

@@ -0,0 +1,132 @@
+/**
+ * A backfill step: a data migration the author writes, run inside the
+ * migration between the statements around it, resumable from receipts.
+ *
+ * The step names a module in the migration's directory (`backfill.ts` by
+ * default) that exports a chant Op as `op` (or as its default export). Each
+ * step of its phases is an `effect()` step: one batch of the backfill, with
+ * its own receipt. The nested steps run SQL on the environment's server with
+ * the `yodelSql` activity yodel provides, or any activity chant has:
+ *
+ *     import { EffectReceipt } from "@intentius/chant";
+ *     import { Op, activity, effect, phase } from "@intentius/chant/op";
+ *
+ *     const months = ["202601", "202602", "202603"];
+ *     const batch = (m: string) =>
+ *       effect(EffectReceipt(`country-${m}`, { effect: `country/${m}`, flavor: "existence" }), [
+ *         activity("yodelSql", { sql: `ALTER TABLE shop.orders UPDATE country = ... WHERE toYYYYMM(ts) = ${m}` }, "atMostOnce"),
+ *       ]);
+ *
+ *     export const op = Op({ name: "backfill-country", overview: "...", phases: [phase("Backfill", months.map(batch))] });
+ *
+ * How a run goes is chant's `effect()` cycle, run by chant's local executor:
+ * for each batch, read its receipt; skip the batch when the receipt is there
+ * (an earlier run finished it); otherwise run its steps and write the
+ * receipt last, only when they all succeeded. A run that fails or is killed
+ * part way leaves the finished batches' receipts, so the next `yodel apply`
+ * resumes at the first batch without one and never redoes a finished one.
+ * A batch that was running when it stopped runs again: make each batch safe
+ * to repeat (an idempotent `UPDATE`, or a delete of its rows before the
+ * insert), as the rebuild's backfill does per partition.
+ *
+ * The receipts are rows on the environment's server, kept by the sql
+ * lexicon's receipt store (`sqlReceiptStore`), addressed
+ * `yodel/<env>/<migration id>/<effect>`, so the same effect name in two
+ * migrations is two receipts:
+ *
+ * - ClickHouse: `chant_receipts.receipts` (the table `ClickHouseRebuildOp`
+ *   keeps its partition receipts in).
+ * - Postgres: `<history schema>.__chant_receipts`, in the schema yodel's
+ *   history is in, over the apply's connection. Each batch runs in one
+ *   transaction on that connection, and its receipt is written last
+ *   inside it: the batch's statements and its receipt commit together or
+ *   not at all, so a run killed anywhere leaves no batch half done, and a
+ *   resumed backfill runs no batch twice. A batch's statements must be ones
+ *   Postgres runs in a transaction block (no `CREATE INDEX CONCURRENTLY`,
+ *   no `VACUUM`). The environment's `lockTimeoutMs` and `scanTimeoutMs` are
+ *   the batch's `lock_timeout` and `statement_timeout`, and `yodelSql`'s
+ *   `settings` are set for the batch's transaction (`set_config(..., true)`).
+ *
+ * The module is one of the migration's own files: it counts in the
+ * migration's checksum, so the plan digest an approval binds covers it, and
+ * an edit after it ran is a checksum mismatch. It is imported from the
+ * migration's directory, so it imports packages only (no relative imports).
+ * Its Op has no gates (the migration's gate approves it).
+ */
+import type { OpConfig } from "@intentius/chant/op/types";
+import type { SqlDialect } from "@intentius/chant-lexicon-sql/dialects";
+import type { ClickHouseEndpoint } from "@intentius/chant-lexicon-sql/clickhouse/http";
+import type { ReceiptStore } from "@intentius/chant/op/receipt-store";
+import type { StepRecord } from "@intentius/chant/op/local-executor";
+import type { ClickHousePort } from "../history/index.js";
+import type { PgClient } from "../history/postgres/index.js";
+import type { PgTimeouts } from "../versioned/postgres/executor.js";
+import { type RunOpOptions } from "./run.js";
+import { type BackfillStep } from "./kinds.js";
+/** The activity a backfill's steps run SQL with: `activity("yodelSql", { sql, settings? })`. */
+export declare const SQL_ACTIVITY = "yodelSql";
+/** The step `yodel new --backfill` adds to a migration. */
+export declare function backfillStep(migrationName: string, file?: string): BackfillStep;
+/** Text only the template holds: a backfill still carrying it has not been written. */
+export declare const TEMPLATE_MARK = "write the backfill of";
+/** What `yodel new --backfill <file>` writes at `<file>` when there is none yet. */
+export declare function backfillTemplate(name: string, dialect?: SqlDialect): string;
+/** The Op config a module exports as `op` or as its default export. */
+export declare function exportedOp(mod: Record<string, unknown>): OpConfig | undefined;
+/** What is wrong with a backfill's Op, if anything: every phase step is an effect() step, and there are no gates. */
+export declare function backfillProblems(config: OpConfig): string[];
+/** Imports a backfill module and returns its Op, or throws naming what is wrong. `text` busts the import cache when the file changed. */
+export declare function loadBackfill(path: string, text?: string): Promise<OpConfig>;
+export interface BackfillSummary {
+    op: "backfill";
+    file: string;
+    /** The Op's name. */
+    name: string;
+    /** Batches (effect steps) the Op has. */
+    effects: number;
+    /** Batches skipped: their receipt was there (an earlier run finished them). */
+    skipped: number;
+    /** Batches run, and their receipt written, in this run. */
+    ran: number;
+}
+/** A receipt store whose every effect is under `prefix`, so receipts of different migrations never meet. */
+export declare function prefixedStore(store: ReceiptStore, prefix: string): ReceiptStore;
+/** Where a backfill's receipts are kept: the environment's ClickHouse server, or the apply's Postgres connection and the schema to keep them in. */
+export type ReceiptServer = {
+    clickhouse: ClickHouseEndpoint;
+} | {
+    postgres: PgClient;
+    schema: string;
+};
+/**
+ * The sql lexicon's receipt store on the environment's server, under the
+ * stack `yodel`. On Postgres it writes over the apply's connection (so a
+ * receipt written inside a batch's transaction commits with it, and the
+ * store never closes it), and the table is made here, before any batch's
+ * transaction opens.
+ */
+export declare function serverReceipts(server: ReceiptServer, environment: string): Promise<ReceiptStore>;
+/** A backfill on Postgres: the connection its batches run on, and the environment's timeouts. */
+export interface PgBackfillServer {
+    client: PgClient;
+    timeouts: Pick<PgTimeouts, "lockTimeoutMs" | "scanTimeoutMs">;
+}
+export interface RunBackfillOptions extends Omit<RunOpOptions, "activities" | "cwd"> {
+    projectDir: string;
+    migrationId: string;
+    /** The migration's directory. */
+    dir: string;
+    /** The module's text as the migration read it (and checksummed). */
+    text?: string | undefined;
+    /** The ClickHouse server the SQL runs on; or `postgres`. */
+    port?: ClickHousePort | undefined;
+    /** The Postgres server the SQL runs on, a transaction per batch; or `port`. */
+    postgres?: PgBackfillServer | undefined;
+    receipts: ReceiptStore;
+    log?: (line: string) => void;
+}
+/** Runs a backfill step to the end, counting batches as they skip or finish. */
+export declare function runBackfill(file: string, run: RunBackfillOptions): Promise<{
+    summary: BackfillSummary;
+    records: StepRecord[];
+}>;