@intentius/chant-lexicon-sql 0.124.31 → 0.124.32

package/dist/migration-statements.js

@@ -0,0 +1,243 @@
+/**
+ * A schema change's statements, rendered offline (#3644): for two `chant
+ * build` outputs, the ordered statements that take the first to the second,
+ * each with its change's class and rule, for a migration file. No server is
+ * read.
+ *
+ * The statements are the applier's: each dialect's `planStatements` /
+ * `planPgStatements` (`./clickhouse/apply/statements.ts`,
+ * `./postgres/apply/statements.ts`) turns classified changes into steps, and
+ * both the applier and this renderer call it. What differs is only where the
+ * current schema comes from: here the older build, keyed by export name as
+ * `chant sql diff` keys it; in the applier the server's catalog.
+ *
+ * A change the applier refuses in place is a step naming the Op that makes
+ * it, never DDL: a ClickHouse rebuild is `ClickHouseRebuildOp`, a Postgres
+ * column rename or type change across kinds is `PostgresMigrationOp`. One no
+ * Op makes is a manual step. Column and object drops are statements, marked
+ * destructive.
+ *
+ * Where the applier asks the server something, the renderer cannot:
+ *
+ * - ClickHouse: the applier also asks the server's formatter whether a
+ *   difference the rules leave is only formatting; the offline diff is the
+ *   rules' alone, as `chant sql diff` is. Before dropping a database it
+ *   checks the database is empty.
+ * - Postgres: the applier asks the server to normalize expressions the rules
+ *   leave different, and keeps an extension's own comment (from its control
+ *   file) under the trailer when the declaration sets none.
+ * - Both: the applier restamps an object whose comment lost chant's marker;
+ *   offline, the older build's objects carry it.
+ */
+import { statementChange } from "./core/statements.js";
+import { declaredObjects as clickhouseDeclared } from "./clickhouse/apply/apply.js";
+import { planStatements } from "./clickhouse/apply/statements.js";
+import { topologyLabel } from "./clickhouse/topology.js";
+import { diffSchemas } from "./clickhouse/plan/diff.js";
+import { rebuildOpSuggestions } from "./clickhouse/plan/rebuild-handoff.js";
+import { declaredObjects as postgresDeclared } from "./postgres/apply/apply.js";
+import { planPgStatements } from "./postgres/apply/statements.js";
+import { diffPgSchemas } from "./postgres/plan/diff.js";
+import { pgBuildMajor } from "./postgres/plan/schema.js";
+import { migrationOpSuggestions, migrationTarget } from "./postgres/migrate/handoff.js";
+import { POSTGRES_ENTITY_TYPES } from "./postgres/entity-types.js";
+import { POSTGRES_LATEST_MAJOR } from "./spec/postgres-pin.js";
+export { renderStatements } from "./core/statements.js";
+const text = (b) => (typeof b === "string" ? b : JSON.stringify(b));
+/** The dialect a build output names, at its root or under `sql`. */
+function dialectOf(json) {
+    const raw = JSON.parse(json);
+    const d = raw?.sql && typeof raw.sql === "object" ? raw.sql.dialect : raw?.dialect;
+    return typeof d === "string" ? d : undefined;
+}
+/**
+ * The statements that take the schema `before` builds to the one `after`
+ * builds. Each is a `chant build` output of the sql lexicon, as JSON text or
+ * parsed. Both must be the same dialect.
+ */
+export function diffStatements(before, after, options = {}) {
+    const b = text(before);
+    const a = text(after);
+    const dialect = dialectOf(a);
+    if (dialectOf(b) !== dialect)
+        throw new Error(`diffStatements: the builds are different dialects (${dialectOf(b) ?? "none"} and ${dialect ?? "none"})`);
+    if (dialect === "postgres")
+        return postgresStatements(b, a, options);
+    if (dialect === "clickhouse")
+        return clickhouseStatements(b, a, options);
+    throw new Error(`diffStatements: not a sql lexicon build output (dialect ${dialect ?? "missing"})`);
+}
+const at = (object, type, name) => ({ object, type, name });
+// ── ClickHouse ─────────────────────────────────────────────────────────
+function clickhouseStatements(beforeJson, afterJson, options) {
+    const defaultDatabase = options.defaultDatabase ?? "default";
+    const env = options.env ?? "<env>";
+    const topology = options.topology ?? { kind: "single" };
+    const before = clickhouseDeclared(beforeJson, defaultDatabase, topology);
+    const after = clickhouseDeclared(afterJson, defaultDatabase, topology);
+    const keyed = (objs) => objs.map((o) => ({ key: o.exportName, canonical: o.canonical }));
+    const diff = diffSchemas(keyed(before), keyed(after));
+    const plan = planStatements({
+        declared: after,
+        changes: diff.changes,
+        current: new Map(before.map((o) => [o.exportName, o.canonical])),
+        keyOf: (o) => o.exportName,
+        allowDestructive: true,
+        // A user whose password is the environment's exists by the time a migration runs: the GRANTs to it need it too (#3717).
+        environmentCreatesUsers: true,
+        topology,
+        ...(options.marker ? { marker: options.marker } : {}),
+    });
+    const declaredByExport = new Map(after.map((o) => [o.exportName, o.canonical]));
+    const isDestructive = (changes, rule) => changes.some((c) => c.rule === rule && c.destructive);
+    const steps = [];
+    for (const entry of plan.objects) {
+        const where = at(entry.obj.exportName, entry.obj.type, entry.obj.key);
+        if (entry.verdict === "rebuild") {
+            const [op] = rebuildOpSuggestions({ ...diff, rebuilds: entry.refused }, declaredByExport, env);
+            if (op) {
+                steps.push({
+                    kind: "op",
+                    ...where,
+                    op: "ClickHouseRebuildOp",
+                    importPath: "@intentius/chant-lexicon-sql/clickhouse",
+                    options: { name: op.name, env: op.env, table: op.table, dualWrite: op.dualWrite },
+                    declaration: op.declaration,
+                    // The rebuild creates the new table from the declaration, so it makes every change to it.
+                    changes: entry.changes.map(statementChange),
+                    detail: entry.detail,
+                });
+            }
+            else
+                steps.push({ kind: "manual", ...where, changes: entry.refused.map(statementChange), detail: entry.detail });
+            continue;
+        }
+        if (entry.verdict === "withheld")
+            continue; // not reached: destructive changes are planned
+        for (const s of entry.steps) {
+            steps.push({
+                kind: "statement",
+                ...where,
+                sql: s.sql,
+                rule: s.rule,
+                class: s.class,
+                transactional: false,
+                ...(s.rewrite ? { waitsForMutation: true } : {}),
+                ...(s.rule === "SQLCH202" || isDestructive(entry.changes, s.rule) ? { destructive: true } : {}),
+            });
+        }
+    }
+    const beforeByExport = new Map(before.map((o) => [o.exportName, o]));
+    for (const d of plan.drops) {
+        const o = beforeByExport.get(d.key);
+        const change = diff.changes.find((c) => c.object === d.key && c.rule === "SQLCH250");
+        steps.push({
+            kind: "statement",
+            ...at(d.key, d.type, o?.key ?? d.name),
+            sql: d.step.sql,
+            rule: d.step.rule,
+            class: d.step.class,
+            transactional: false,
+            ...(change?.destructive ? { destructive: true } : {}),
+        });
+    }
+    return { dialect: "clickhouse", defaultDatabase, topology: topologyLabel(topology), steps, refused: steps.some((s) => s.kind !== "statement"), hints: diff.hints };
+}
+// ── Postgres ───────────────────────────────────────────────────────────
+function postgresStatements(beforeJson, afterJson, options) {
+    const defaultSchema = options.defaultSchema ?? "public";
+    const env = options.env ?? "<env>";
+    const major = options.major ?? buildMajor(afterJson) ?? buildMajor(beforeJson) ?? POSTGRES_LATEST_MAJOR;
+    const before = postgresDeclared(beforeJson, defaultSchema);
+    const after = postgresDeclared(afterJson, defaultSchema);
+    const keyed = (objs) => objs.map((o) => ({ key: o.exportName, canonical: o.canonical }));
+    const current = keyed(before);
+    const diff = diffPgSchemas(current, keyed(after), { major });
+    const plan = planPgStatements({
+        declared: after,
+        changes: diff.changes,
+        current,
+        keyOf: (o) => o.exportName,
+        major,
+        allowDestructive: true,
+        ...(options.marker ? { marker: options.marker } : {}),
+    });
+    const isDestructive = (changes, rule) => changes.some((c) => c.rule === rule && c.destructive);
+    const steps = [];
+    for (const entry of plan.objects) {
+        const where = at(entry.obj.exportName, entry.obj.type, entry.obj.name);
+        switch (entry.verdict) {
+            case "refused": {
+                const handled = new Set();
+                for (const op of migrationOpSuggestions(entry.refused, new Map([[entry.obj.exportName, entry.obj.canonical]]), env, defaultSchema)) {
+                    const made = entry.refused.filter((c) => {
+                        const t = migrationTarget(c, entry.obj.canonical, defaultSchema);
+                        return t !== undefined && t.table === op.table && t.column === op.column;
+                    });
+                    for (const c of made)
+                        handled.add(c);
+                    steps.push({
+                        kind: "op",
+                        ...where,
+                        op: "PostgresMigrationOp",
+                        importPath: "@intentius/chant-lexicon-sql/postgres",
+                        options: { name: op.name, env: op.env, table: op.table, column: op.column },
+                        declaration: op.declaration,
+                        changes: made.map(statementChange),
+                        detail: entry.detail,
+                    });
+                }
+                const rest = entry.changes.filter((c) => !handled.has(c));
+                if (rest.length > 0)
+                    steps.push(manual(where, rest, handled.size > 0 ? `the applier sends nothing for ${entry.obj.name} while a change to it is refused; these changes are not made by the Op: ${entry.detail}` : entry.detail));
+                continue;
+            }
+            case "unsupported":
+                steps.push(manual(where, entry.changes, entry.detail));
+                continue;
+            case "foreign":
+            case "withheld":
+                continue; // not reached offline: a build declares no foreign object, and destructive changes are planned
+        }
+        for (const s of entry.steps) {
+            steps.push({
+                kind: "statement",
+                ...where,
+                sql: s.sql,
+                rule: s.rule ?? (s.class === "create" ? "SQLPG200" : (entry.changes[0]?.rule ?? "SQLPG200")),
+                class: s.class,
+                transactional: s.transactional,
+                ...(s.rule === "SQLPG204" || isDestructive(entry.changes, s.rule) ? { destructive: true } : {}),
+                ...(s.precheck ? { precheck: { sql: s.precheck.sql, detail: s.precheck.detail } } : {}),
+            });
+        }
+    }
+    // Privileges (#3681), after the objects they are on: one statement each, under the declaration behind it.
+    const afterByExport = new Map(after.map((o) => [o.exportName, o]));
+    for (const c of diff.access ?? []) {
+        const decl = c.exports.map((e) => afterByExport.get(e)).find((o) => o !== undefined);
+        const where = decl ? at(decl.exportName, decl.type, decl.name) : at(c.change.object, c.target.kind === "default" ? POSTGRES_ENTITY_TYPES.defaultPrivileges : POSTGRES_ENTITY_TYPES.grant, c.change.object.slice(4));
+        for (const sql of c.sql)
+            steps.push({ kind: "statement", ...where, sql, rule: c.change.rule, class: c.change.class, transactional: true });
+    }
+    const beforeByExport = new Map(before.map((o) => [o.exportName, o]));
+    for (const d of plan.drops) {
+        const o = beforeByExport.get(d.key);
+        const change = diff.changes.find((c) => c.object === d.key && (c.rule === "SQLPG270" || c.rule === "SQLPG242"));
+        steps.push({
+            kind: "statement",
+            ...at(d.key, o?.type ?? POSTGRES_ENTITY_TYPES[d.kind], o?.name ?? d.name),
+            sql: d.step.sql,
+            rule: d.step.rule ?? "SQLPG270",
+            class: d.step.class,
+            transactional: d.step.transactional,
+            ...(change?.destructive ? { destructive: true } : {}),
+        });
+    }
+    return { dialect: "postgres", defaultSchema, major, steps, refused: steps.some((s) => s.kind !== "statement"), hints: diff.hints };
+}
+const manual = (where, changes, detail) => ({ kind: "manual", ...where, changes: changes.map(statementChange), detail });
+function buildMajor(json) {
+    const raw = JSON.parse(json);
+    return pgBuildMajor(raw.sql && typeof raw.sql === "object" ? JSON.stringify(raw.sql) : json);
+}

package/dist/op/activities/clickhouse-apply.js

@@ -0,0 +1,83 @@
+/**
+ * `clickhouseApply`, the Op activity for the ClickHouse applier (#3208), and
+ * `toApplyResult`, its projection onto core's apply envelope (#1446).
+ *
+ * It reads a build's output (`chant build -o dist/schema.json`), binds the
+ * environment's server the way observation and import do
+ * (`sql.profiles.<env>`, else `CLICKHOUSE_URL`; ../../clickhouse/live/bind.ts),
+ * and hands the declarations to `applyClickHouse`
+ * (../../clickhouse/apply/apply.ts), which holds the decisions.
+ *
+ * The ownership marker is the project's: `ownership.stack` and
+ * `ownership.env` from `chant.config.ts`, or `stack` / `ownershipEnv` passed
+ * in. Without a stack the apply still runs, stamping only the managed-by
+ * marker, and a prune declines (as `not-prunable`) rather than drop another
+ * project's tables.
+ */
+import { readFileSync } from "node:fs";
+import { notAttemptedOutcome, resolveOwnershipMarker } from "../../core/apply.js";
+import { bindClickHouse, ClickHouseBindingError, classifyClickHouseFailure } from "../../clickhouse/live/bind.js";
+import { applyClickHouse, declaredObjects, planRefs } from "../../clickhouse/apply/apply.js";
+export { toApplyResult } from "../../core/apply.js";
+async function loadConfig(cwd) {
+    try {
+        const { loadChantConfig } = await import("@intentius/chant/config");
+        return (await loadChantConfig(cwd)).config;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The marker to stamp and prune by: the arguments, else the project's `ownership` config. */
+export function resolveMarker(args, config) {
+    return resolveOwnershipMarker(args, config, "clickhouse apply");
+}
+/**
+ * Apply a sql build to the environment's ClickHouse server. A server that
+ * cannot be bound, or refuses the credentials on the first read, returns
+ * every declared object as not attempted, with the reason.
+ */
+export async function clickhouseApply(args, signal, deps = {}) {
+    const config = deps.config ?? (await loadConfig(args.cwd ?? process.cwd()));
+    const marker = resolveMarker(args, config);
+    const json = readFileSync(args.buildPath, "utf8");
+    const log = deps.log ?? ((line) => console.log(line));
+    let target;
+    try {
+        target = await bindClickHouse({ ...(args.environment !== undefined ? { environment: args.environment } : {}), config: config ?? {}, ...(deps.env ? { env: deps.env } : {}) });
+    }
+    catch (err) {
+        if (!(err instanceof ClickHouseBindingError))
+            throw err;
+        return refused(declaredObjects(json), err.unresolved.reason, err.unresolved.detail);
+    }
+    const declared = declaredObjects(json, target.defaultDatabase, target.topology);
+    let outcome;
+    try {
+        outcome = await applyClickHouse(target, declared, {
+            ...(marker ? { marker } : {}),
+            ...(args.prune ? { prune: true } : {}),
+            ...(args.mutationTimeoutMs !== undefined ? { mutationTimeoutMs: args.mutationTimeoutMs } : {}),
+            ...(signal ? { signal } : {}),
+            log,
+        });
+    }
+    catch (err) {
+        // A server that never answered the first read was not written to at all.
+        const why = classifyClickHouseFailure(err);
+        if (why.reason === "no-credentials" && !(err instanceof Error && err.name === "ClickHouseApplyError")) {
+            return { ...refused(declared, "no-credentials", why.detail), target: target.endpoint.url, source: target.source };
+        }
+        throw err;
+    }
+    for (const a of outcome.applied)
+        log(`${a.action}: ${a.kind}/${a.name}`);
+    for (const p of outcome.pruned)
+        log(`pruned: ${p.kind}/${p.name}`);
+    for (const n of outcome.notAttempted)
+        log(`not attempted: ${n.kind}/${n.name}: ${n.reason}${n.detail ? ` (${n.detail})` : ""}`);
+    return outcome;
+    function refused(objects, reason, detail) {
+        return notAttemptedOutcome(planRefs(objects), reason, detail);
+    }
+}

package/dist/op/activities/clickhouse-emulator.js

@@ -0,0 +1,53 @@
+/**
+ * The sql lexicon's emulator capability (#3208): the pinned
+ * `clickhouse/clickhouse-server`, the same image and digest generation and
+ * the live tests run (../../spec/pin.ts), so `chant emulator up` boots a real
+ * server rather than a stand-in.
+ *
+ * `upstream` is left off on purpose. The freshness check compares the image
+ * tag against the repo's latest GitHub release, and ClickHouse's latest
+ * release is a monthly one, not the LTS line the pin follows; the lexicon's
+ * `upstreamPin` already tracks the LTS tags (`-lts`).
+ */
+import { emulatorLifecycle } from "@intentius/chant/op";
+import { clickhouseImage } from "../../spec/pin.js";
+/**
+ * The server's UUID (#3673), read in the container and through the endpoint
+ * `status` prints, so a server of another origin on the same port is told
+ * apart from the emulator.
+ */
+export const CLICKHOUSE_EMULATOR_IDENTITY = {
+    server: "ClickHouse",
+    command: ["clickhouse-client", "-q", "SELECT serverUUID()"],
+    async probe(endpoint) {
+        const url = new URL(endpoint);
+        url.searchParams.set("query", "SELECT serverUUID(), version() FORMAT TSV");
+        const res = await fetch(url, { signal: AbortSignal.timeout(5000) });
+        const body = (await res.text()).trim();
+        if (!res.ok)
+            throw new Error(`HTTP ${res.status}: ${body.split("\n")[0]}`);
+        const [id = "", version = "(unknown version)"] = body.split("\t");
+        return { id, label: `ClickHouse ${version}` };
+    },
+};
+export const CLICKHOUSE_EMULATOR_SPEC = {
+    name: "chant-clickhouse",
+    image: clickhouseImage(),
+    containerPort: 8123,
+    healthPath: "/ping",
+    // The image disables network access for the passwordless default user
+    // unless this is set; a local server is reached as `default` with no password.
+    runArgs: ["-e", "CLICKHOUSE_SKIP_USER_SETUP=1"],
+    identity: CLICKHOUSE_EMULATOR_IDENTITY,
+    credentials: "user default, no password",
+};
+/** `CLICKHOUSE_URL` is the variable binding reads when no `sql.profiles.<env>` names a server. */
+export const CLICKHOUSE_EMULATOR = {
+    spec: CLICKHOUSE_EMULATOR_SPEC,
+    env: (endpoint) => ({ CLICKHOUSE_URL: endpoint }),
+};
+const lifecycle = emulatorLifecycle(CLICKHOUSE_EMULATOR_SPEC);
+/** Boot the pinned ClickHouse server in Docker and return its endpoint. */
+export const clickhouseUp = (args = {}, signal) => lifecycle.up(args, signal);
+/** Stop and remove it (a no-op when it is gone). */
+export const clickhouseDown = (args = {}, signal) => lifecycle.down(args, signal);

package/dist/op/activities/clickhouse-rebuild.js

@@ -0,0 +1,119 @@
+/**
+ * The rebuild migration's activities (#3198), one per step of
+ * `ClickHouseRebuildOp` (`../../clickhouse/rebuild/op.ts`). Each takes the
+ * same arguments, reads the build's declaration of the table and binds the
+ * environment's server the way the applier does (`./clickhouse-apply.ts`),
+ * then runs its step (`../../clickhouse/rebuild/`), which re-reads the server.
+ */
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { currentOpRun, parseDuration } from "@intentius/chant/op";
+import { bindClickHouse } from "../../clickhouse/live/bind.js";
+import { declaredObjects } from "../../clickhouse/apply/apply.js";
+import { declaredTable, observeRebuild, rebuildPlanDigest, RebuildRefusal } from "../../clickhouse/rebuild/observe.js";
+import { backfill } from "../../clickhouse/rebuild/backfill.js";
+import { RebuildVerificationError, verifyRebuild } from "../../clickhouse/rebuild/verify.js";
+import { compensate, createNewTable, dropOldTable, retainPlan, startDualWrite, swapTables, } from "../../clickhouse/rebuild/steps.js";
+import { CLASSIFIER_RULES } from "../../clickhouse/plan/rules.js";
+import { clusterSharding } from "../../clickhouse/rebuild/shards.js";
+import { resolveMarker } from "./clickhouse-apply.js";
+import { statementChange } from "../../core/statements.js";
+import { clickhouseRebuildPart } from "../../change-set.js";
+async function loadConfig(cwd) {
+    try {
+        const { loadChantConfig } = await import("@intentius/chant/config");
+        return (await loadChantConfig(cwd)).config;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Bind the server and read the declaration: what every step starts from. */
+export async function rebuildRun(args, signal, deps) {
+    const cwd = args.cwd ?? process.cwd();
+    const config = deps.config ?? (await loadConfig(cwd));
+    const marker = resolveMarker(args, config);
+    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,
+        ...(marker ? { marker } : {}),
+        dualWrite: args.dualWrite,
+        retainMs: parseDuration(args.retain ?? "7d"),
+        ...(args.mutationTimeout ? { mutationTimeoutMs: parseDuration(args.mutationTimeout) } : {}),
+        ...(args.replicaTimeout ? { replicaTimeoutMs: parseDuration(args.replicaTimeout) } : {}),
+        ...(args.cutoverTimeout ? { cutoverTimeoutMs: parseDuration(args.cutoverTimeout) } : {}),
+        log: deps.log ?? ((line) => 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(args, fn) {
+    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;
+    }
+}
+/** Plan: classify the table's change against the server and say how far the rebuild has got. */
+export async function clickhouseRebuildPlan(args, signal, deps = {}) {
+    return noting(args, () => plan(args, signal, deps));
+}
+async function plan(args, signal, deps) {
+    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"}` : ""}`);
+    const rebuilds = o.changes.filter((c) => c.class === "rebuild").map((c) => `${c.rule} ${CLASSIFIER_RULES[c.rule].title}`);
+    const summary = o.state === "rebuild"
+        ? `${o.names.key} needs a rebuild (${rebuilds.join("; ")}); ${o.copied.length} column(s) copied${o.newTable ? ", new table already made" : ""}`
+        : o.state === "swapped"
+            ? `${o.names.key} has been swapped; the old table is kept as ${o.names.database}.${o.names.oldName}`
+            : `${o.names.key} holds its declaration; nothing to rebuild`;
+    run.log(`-- ${summary}`);
+    for (const c of changes)
+        run.log(`--   ${c}`);
+    const classified = o.changes.map(statementChange);
+    const result = { state: o.state, table: o.names.key, ...(o.state === "rebuild" ? { planDigest: rebuildPlanDigest(o, run.dualWrite) } : {}), changes, classified };
+    const part = clickhouseRebuildPart({ member: o.names.key, plan: result, ...(args.environment !== undefined ? { environment: args.environment } : {}) });
+    return { ...result, part, summary };
+}
+export async function clickhouseRebuildCreate(args, signal, deps = {}) {
+    return noting(args, async () => createNewTable(await rebuildRun(args, signal, deps)));
+}
+export async function clickhouseRebuildDualWrite(args, signal, deps = {}) {
+    return noting(args, async () => startDualWrite(await rebuildRun(args, signal, deps)));
+}
+export async function clickhouseRebuildBackfill(args, signal, deps = {}) {
+    return noting(args, async () => backfill(await rebuildRun(args, signal, deps), deps.backfill));
+}
+export async function clickhouseRebuildVerify(args, signal, deps = {}) {
+    return noting(args, async () => verifyRebuild(await rebuildRun(args, signal, deps)));
+}
+export async function clickhouseRebuildSwap(args, signal, deps = {}) {
+    return noting(args, async () => swapTables(await rebuildRun(args, signal, deps)));
+}
+export async function clickhouseRebuildRetain(args, signal, deps = {}) {
+    return retainPlan(await rebuildRun(args, signal, deps));
+}
+export async function clickhouseRebuildDrop(args, signal, deps = {}) {
+    return dropOldTable(await rebuildRun(args, signal, deps));
+}
+/** onFailure: drop the new table and the dual-write view. */
+export async function clickhouseRebuildCompensate(args, signal, deps = {}) {
+    return compensate(await rebuildRun(args, signal, deps));
+}

package/dist/op/activities/index.js

@@ -0,0 +1,26 @@
+import { sqlReceiptActivities } from "../../receipts.js";
+export { clickhouseApply, toApplyResult, resolveMarker } from "./clickhouse-apply.js";
+export { clickhouseUp, clickhouseDown, CLICKHOUSE_EMULATOR, CLICKHOUSE_EMULATOR_SPEC } from "./clickhouse-emulator.js";
+export { postgresApply } from "./postgres-apply.js";
+export { postgresUp, postgresDown, POSTGRES_EMULATOR, POSTGRES_EMULATOR_SPEC } from "./postgres-emulator.js";
+// 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 = ["receiptRead", "receiptWrite", "receiptStaleness"];
+// Bound per call: the environment (`chant run --env`) and the project are read when a step runs.
+export const receiptRead = (args, signal) => sqlReceiptActivities().receiptRead(args, signal);
+export const receiptWrite = (args, signal) => sqlReceiptActivities().receiptWrite(args, signal);
+export const receiptStaleness = (args, signal) => sqlReceiptActivities().receiptStaleness(args, signal);
+export { sqlExec } from "./sql-exec.js";
+// 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, with the copy's own identity.
+export { clickhouseRebuildPlan, clickhouseRebuildCreate, clickhouseRebuildDualWrite, clickhouseRebuildBackfill, clickhouseRebuildVerify, clickhouseRebuildSwap, clickhouseRebuildRetain, clickhouseRebuildDrop, clickhouseRebuildCompensate, } from "./clickhouse-rebuild.js";
+// The Postgres expand-and-contract migration (#3281): one activity per step of
+// PostgresMigrationOp (../../postgres/migrate/op.ts). Its receipts are kept in
+// the migrated table's schema and written by the backfill directly, in each
+// batch's own transaction.
+export { postgresMigrationPlan, postgresMigrationExpand, postgresMigrationDualWrite, postgresMigrationBackfill, postgresMigrationCarry, postgresMigrationVerify, postgresMigrationSwitch, postgresMigrationRetain, postgresMigrationContract, postgresMigrationCompensate, } from "./postgres-migration.js";

package/dist/op/activities/postgres-apply.js

@@ -0,0 +1,126 @@
+/**
+ * `postgresApply`, the Op activity for the Postgres applier (#3280), and
+ * `toApplyResult`, its projection onto core's apply envelope (#1446), the
+ * same projection the ClickHouse applier exports.
+ *
+ * It reads a build's output (`chant build -o dist/schema.json`), binds the
+ * environment's server the way observation, import and `chant sql plan` do
+ * (`sql.profiles.<env>`, else `POSTGRES_URL`; ../../postgres/live/bind.ts),
+ * connects with node-postgres (loaded only now), and hands the declarations
+ * to `applyPostgres` (../../postgres/apply/apply.ts), which holds the
+ * decisions.
+ *
+ * The server's major is the build output's `postgresMajor` (#3315), else
+ * `sql.postgresMajor`, else the newest pinned one.
+ *
+ * The ownership marker is the project's: `ownership.stack` and
+ * `ownership.env` from `chant.config.ts`, or `stack` / `ownershipEnv` passed
+ * in. Without a stack the apply still runs, stamping only the managed-by
+ * marker, and a prune declines (as `not-prunable`) rather than drop another
+ * project's objects. The timeouts are the profile's, else the applier's
+ * defaults, and an argument overrides either.
+ */
+import { readFileSync } from "node:fs";
+import { notAttemptedOutcome, resolveOwnershipMarker } from "../../core/apply.js";
+import { classifyPostgresFailure, PostgresBindingError, resolveBoundTarget } from "../../postgres/live/bind.js";
+import { connectPostgres } from "../../postgres/live/client.js";
+import { DEFAULT_POSTGRES_APPLY_TIMEOUTS, applyPostgres, declaredObjects, planRefs, } from "../../postgres/apply/apply.js";
+/** The build output's `postgresMajor`, when it carries one. */
+export function buildMajor(json) {
+    try {
+        const raw = JSON.parse(json);
+        const m = raw.sql && typeof raw.sql === "object" ? raw.sql.postgresMajor : raw.postgresMajor;
+        return typeof m === "number" ? m : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function loadConfig(cwd) {
+    try {
+        const { loadChantConfig } = await import("@intentius/chant/config");
+        return (await loadChantConfig(cwd)).config;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Apply a sql build to the environment's Postgres server. A server that
+ * cannot be bound, or refuses the credentials when connecting, returns every
+ * declared object as not attempted, with the reason.
+ */
+export async function postgresApply(args, signal, deps = {}) {
+    const config = deps.config ?? (await loadConfig(args.cwd ?? process.cwd()));
+    const marker = resolveOwnershipMarker(args, config, "postgres apply");
+    const json = readFileSync(args.buildPath, "utf8");
+    const log = deps.log ?? ((line) => console.log(line));
+    const timeouts = {
+        ...(args.lockTimeoutMs !== undefined ? { lockTimeoutMs: args.lockTimeoutMs } : {}),
+        ...(args.statementTimeoutMs !== undefined ? { statementTimeoutMs: args.statementTimeoutMs } : {}),
+        ...(args.scanTimeoutMs !== undefined ? { scanTimeoutMs: args.scanTimeoutMs } : {}),
+    };
+    // The major the build targets (#3315): what an apply does can differ by major (SET EXPRESSION from 17, SET STORAGE DEFAULT from 16).
+    const major = buildMajor(json) ?? config?.sql?.postgresMajor;
+    let target;
+    try {
+        target = await resolveBoundTarget({ ...(args.environment !== undefined ? { environment: args.environment } : {}), config: config ?? {}, ...(deps.env ? { env: deps.env } : {}) });
+    }
+    catch (err) {
+        if (!(err instanceof PostgresBindingError))
+            throw err;
+        return refused(declaredObjects(json), undefined, err.unresolved.reason, err.unresolved.detail);
+    }
+    const declared = declaredObjects(json, target.defaultSchema);
+    let client;
+    try {
+        client = await (deps.connect ?? ((e) => connectPostgres(e, { applicationName: "chant apply" })))(target.endpoint);
+    }
+    catch (err) {
+        // A server that refused the credentials was not written to at all; one that cannot be reached is an error.
+        const why = classifyPostgresFailure(err);
+        if (why.reason === "no-credentials")
+            return refused(declared, target, "no-credentials", why.detail);
+        throw err;
+    }
+    let outcome;
+    try {
+        outcome = await applyPostgres(client, target, declared, {
+            ...(marker ? { marker } : {}),
+            ...(args.prune ? { prune: true } : {}),
+            timeouts,
+            ...(major !== undefined ? { major } : {}),
+            ...(signal ? { signal } : {}),
+            ...(deps.readLive ? { readLive: deps.readLive } : {}),
+            ...(deps.serverNormalize ? { serverNormalize: deps.serverNormalize } : {}),
+            log,
+        });
+    }
+    catch (err) {
+        // The first read is the catalog read: a refusal there means nothing was written.
+        const why = classifyPostgresFailure(err);
+        if (why.reason === "no-credentials" && !(err instanceof Error && err.name === "PostgresApplyError")) {
+            return refused(declared, target, "no-credentials", why.detail);
+        }
+        throw err;
+    }
+    finally {
+        await client.end();
+    }
+    for (const a of outcome.applied)
+        log(`${a.action}: ${a.kind}/${a.name}`);
+    for (const p of outcome.pruned)
+        log(`pruned: ${p.kind}/${p.name}`);
+    for (const n of outcome.notAttempted)
+        log(`not attempted: ${n.kind}/${n.name}: ${n.reason}${n.detail ? ` (${n.detail})` : ""}`);
+    return outcome;
+    function refused(objects, t, reason, detail) {
+        return {
+            ...notAttemptedOutcome(planRefs(objects), reason, detail),
+            ...(t ? { target: t.endpoint.url, source: t.source } : {}),
+            timeouts: { ...DEFAULT_POSTGRES_APPLY_TIMEOUTS, ...t?.timeouts, ...timeouts },
+            statements: [],
+            transactions: [],
+        };
+    }
+}