@intentius/chant-lexicon-sql 0.124.54 → 0.124.56

package/dist/capability-plugin.d.ts

@@ -0,0 +1,160 @@
+import type { Capability } from "@intentius/chant/components/capability";
+import { type CapabilityPlugin } from "@intentius/chant/components/capability-plugin";
+import { type ChangeSetHole } from "@intentius/chant/change-set";
+import { type ChantExitCode } from "@intentius/chant/exit-codes";
+import { type SqlDeclarativeChange } from "./change-set.js";
+import { type YodelRunner } from "./yodel-run.js";
+/** A plan that moved since it was decided: nothing was applied (core's `isPlanMovedError`). */
+export declare class SqlPlanMovedError extends Error {
+    readonly member: string;
+    readonly planMoved = true;
+    constructor(member: string, message: string);
+}
+/** A yodel run that did not succeed, with the code chant's table gives it. */
+export declare class YodelRunError extends Error {
+    /** The table's code for the run (`CHANT_EXIT`). Named so core never reads it as an exit code. */
+    readonly chantExit: ChantExitCode;
+    readonly yodelExit: number | null;
+    constructor(message: string, 
+    /** The table's code for the run (`CHANT_EXIT`). Named so core never reads it as an exit code. */
+    chantExit: ChantExitCode, yodelExit: number | null);
+}
+/** The input of a `sql-migrate` step. */
+export interface SqlMigrateStepInput {
+    /** The yodel environment (`{target}` in an op wave), a tenant (`<env>/<tenant>`) or a slot of a tenant set. */
+    environment: string;
+    /** The yodel project directory, relative to the job's working directory. Default: the working directory. */
+    dir?: string;
+    /** The migrations Op, when more than one applies the environment. */
+    op?: string;
+    allowOutOfOrder?: boolean;
+    /**
+     * The op-waves spec file the wave runs (`yodel-waves.json`), which the
+     * engine reads chant's decision for the wave by. Set: plan the wave plan
+     * and allow `run`. Absent: plan the migrations only, as a pull request's
+     * plan does; `run` refuses.
+     */
+    spec?: string;
+    /** The yodel predates sql-yodeler#288 and exits by its own table. */
+    legacyExit?: boolean;
+}
+/** What `sql-migrate`'s plan hands its run. */
+export interface SqlMigrateArtifact {
+    kind: "sql-migrate";
+    environment: string;
+    planDigest: string;
+    /** The wave plan file `--wave-plan` wrote, relative to the working directory. */
+    wavePlan?: string;
+    spec?: string;
+    /** The migrations' own digest, as `yodel apply --digest` prints it. */
+    migrations?: string;
+    pending: string[];
+}
+export interface SqlMigrateStepOutput {
+    environment: string;
+    planDigest: string;
+    /** What yodel printed on standard output: `Applied: ...`, `Nothing to apply.` or the stand-down line. */
+    summary: string;
+}
+/** The parts of the wave plan file `yodel apply --wave-plan` writes that the capability reads. */
+interface YodelWavePlanFile {
+    planDigest: string;
+    migrations?: string;
+    environment?: string;
+    empty?: boolean;
+    pending?: string[];
+    destructiveSteps?: Array<{
+        migration?: string;
+        step?: number;
+        why?: string;
+    }>;
+}
+/** What `sql-migrate` is built with. Tests pass a fake runner. */
+export interface SqlMigrateDeps {
+    run?: YodelRunner;
+    /** The job's working directory. Default `process.cwd()`. */
+    cwd?: () => string;
+    /** The job's environment. Default `process.env`. */
+    env?: () => NodeJS.ProcessEnv;
+}
+/** Where the capability keeps a run's yodel files, relative to the working directory. */
+export declare function sqlMigrateFiles(environment: string): {
+    part: string;
+    wavePlan: string;
+};
+/** The destructive classes of a wave plan: each step's rules, as the engine's lint names them, sorted. */
+export declare function wavePlanDestructive(plan: Pick<YodelWavePlanFile, "destructiveSteps">): string[];
+/** The `sql-migrate` capability, with its runner and environment injectable. */
+export declare function createSqlMigrateCapability(deps?: SqlMigrateDeps): Capability<SqlMigrateStepInput, SqlMigrateStepOutput>;
+export declare const sqlMigrateCapability: Capability<SqlMigrateStepInput, SqlMigrateStepOutput>;
+/** The input of a `sql-apply` step. */
+export interface SqlApplyStepInput {
+    /** The chant environment, which selects `sql.profiles.<environment>`. */
+    environment: string;
+    /** The build's output (`chant build src --lexicon sql -o dist/schema.json`). */
+    build: string;
+    /** Drop this project's objects the build no longer declares. Destructive, so off by default. */
+    prune?: boolean;
+    stack?: string;
+    ownershipEnv?: string;
+    /** Postgres: `lock_timeout` per statement, in ms. */
+    lockTimeoutMs?: number;
+    /** Postgres: `statement_timeout` for a catalog-only statement, in ms. */
+    statementTimeoutMs?: number;
+    /** Postgres: `statement_timeout` for a statement that reads or rewrites rows, in ms. */
+    scanTimeoutMs?: number;
+    /** ClickHouse: how long to wait for one table's background rewrite, in ms. */
+    mutationTimeoutMs?: number;
+    /** Project directory for `chant.config.ts`. Default: the working directory. */
+    cwd?: string;
+}
+/** A declarative plan, as `sql-apply` reads it from the dialect's planner. */
+export interface SqlDeclarativePlan {
+    dialect: "clickhouse" | "postgres";
+    changes: SqlDeclarativeChange[];
+    /** Changes the applier will not make in place, each with the Op to run instead when the planner names one. */
+    refused: Array<{
+        object: string;
+        field: string;
+        op?: string;
+    }>;
+    holes: ChangeSetHole[];
+    /** Why the plan cannot be applied besides (a named collection missing on the server). */
+    problems: string[];
+}
+export interface SqlApplyArtifact {
+    kind: "sql-apply";
+    environment: string;
+    dialect: "clickhouse" | "postgres";
+    planDigest: string;
+}
+export interface SqlApplyStepOutput {
+    environment: string;
+    dialect: "clickhouse" | "postgres";
+    planDigest: string;
+    applied: string[];
+    pruned: string[];
+}
+/** What `sql-apply` is built with. Tests pass fakes for the planner and the applier. */
+export interface SqlApplyDeps {
+    plan?: (input: SqlApplyStepInput, dialect: "clickhouse" | "postgres") => Promise<SqlDeclarativePlan>;
+    apply?: (input: SqlApplyStepInput, dialect: "clickhouse" | "postgres") => Promise<{
+        applied: string[];
+        pruned: string[];
+        notAttempted: Array<{
+            name: string;
+            reason: string;
+        }>;
+    }>;
+}
+/** The dialect a build output names: `postgres`, else `clickhouse`. */
+export declare function buildDialect(path: string): "clickhouse" | "postgres";
+/** The `sql-apply` capability, with its planner and applier injectable. */
+export declare function createSqlApplyCapability(deps?: SqlApplyDeps): Capability<SqlApplyStepInput, SqlApplyStepOutput>;
+export declare const sqlApplyCapability: Capability<SqlApplyStepInput, SqlApplyStepOutput>;
+export declare const SQL_VERB_FAMILIES: {
+    readonly apply: readonly ["sql-apply", "sql-migrate"];
+};
+export declare const sqlCapabilityPlugin: CapabilityPlugin;
+export {};
+//# sourceMappingURL=capability-plugin.d.ts.map

package/dist/capability-plugin.d.ts.map

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

package/dist/capability-plugin.js

@@ -0,0 +1,370 @@
+/**
+ * The sql lexicon's capability plugin (#4569): `sql-migrate` and
+ * `sql-apply`, so op waves (`step: { kind, ...input }`, #4545) and
+ * `chant components pr-plan` plan and apply a SQL member through chant, as
+ * they do a Terraform root (`terraform-apply`). A project that lists `sql`
+ * among its lexicons gets both registered when its registry is built
+ * (`loadCapabilityPluginsFromLexicons`).
+ *
+ * ## sql-migrate: the versioned path
+ *
+ * The versioned migration engine stays in sql-yodeler (ruling A on
+ * sql-yodeler#285), and this capability runs it through the fixed argv list
+ * in `./yodel-run.ts`:
+ *
+ * ```json
+ * { "step": { "kind": "sql-migrate", "environment": "{target}", "spec": "yodel-waves.json" } }
+ * ```
+ *
+ * - `plan` runs `yodel plan <env> --part <file>` for the change-set part,
+ *   one entry per object the pending migrations touch, with real counts.
+ *   With `spec` (an op wave) it also runs `yodel apply <env> --wave-plan
+ *   <file> --spec <spec>`, and the wave plan's digest is the member's: the
+ *   value the wave's gate binds and the engine checks again under its lock.
+ *   The wave plan's destructive steps come back as
+ *   {@link CapabilityPlan.destructive}, each the lint rule that classes it,
+ *   so `on-destructive` waits on what the engine calls destructive. Without
+ *   `spec` (a pull request's plan) the digest is the migrations' own, the
+ *   one `yodel approve` binds. A plan the engine would refuse fails the
+ *   plan, naming the refusal.
+ * - `run` runs `yodel apply <env> --wave-apply <file> --spec <spec>` with
+ *   the plan the wave decided, which `DeployContext.plans` hands back. The
+ *   engine plans again under its lock and refuses a plan that moved; that
+ *   refusal is a moved plan here ({@link SqlPlanMovedError}), and the wave
+ *   exits 4. The engine also checks chant's decision for the wave and the
+ *   gate ledger's approval itself (ruling A on sql-yodeler#300), so an
+ *   apply that chant let through and the ledger does not hold still refuses.
+ *   `run` applies only a plan an op wave made with `spec`: an apply happens
+ *   on the merged branch, never before the merge (ruling E on
+ *   sql-yodeler#285).
+ *
+ * yodel's exit status reads through `yodelExitOf` (`./exit-codes.ts`,
+ * #4570). A yodel before sql-yodeler#288 exits by its own table; set
+ * `legacyExit: true` for one, and its moved plan is read from the line it
+ * prints.
+ *
+ * Both kinds take the `target` lock grain, the environment, and refuse
+ * `resource` by name (`./lock-grain.ts`, #4571).
+ *
+ * The planning commands run without the writer's variables; only the apply
+ * gets them (`readerEnv` in `./yodel-run.ts`).
+ *
+ * ## sql-apply: the declarative path
+ *
+ * `sql-apply` plans a build (`chant build -o dist/schema.json`) against the
+ * environment's server, as `chant sql plan` does, and applies it with the
+ * lexicon's applier, `clickhouseApply` or `postgresApply`, by the build's
+ * dialect:
+ *
+ * ```json
+ * { "kind": "sql-apply", "environment": "prod", "build": "dist/schema.json" }
+ * ```
+ *
+ * The part has one entry per object the classified changes touch. A change
+ * the applier refuses (a ClickHouse rebuild, a Postgres expand and contract),
+ * an object the plan cannot read, or a named collection the server lacks
+ * fails the plan, naming the migration Op to run instead. `run` plans again
+ * and applies only when the digest is still the one decided; otherwise it
+ * refuses as moved and sends nothing.
+ */
+import { existsSync, mkdirSync, readFileSync, rmSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { ownPackageVersion } from "@intentius/chant/components/capability-plugin";
+import { readChangeSetPartFile } from "@intentius/chant/change-set";
+import { CHANT_EXIT } from "@intentius/chant/exit-codes";
+import { sqlDeclarativePlanPart } from "./change-set.js";
+import { yodelExitOf } from "./exit-codes.js";
+import { sqlDefaultLockGrain, sqlLockGrainRefusal } from "./lock-grain.js";
+import { defaultYodelRunner, readerEnv, runAllowedYodel, yodelPlanArgs, yodelWaveApplyArgs, yodelWavePlanArgs, } from "./yodel-run.js";
+/** A plan that moved since it was decided: nothing was applied (core's `isPlanMovedError`). */
+export class SqlPlanMovedError extends Error {
+    constructor(member, message) {
+        super(message);
+        this.member = member;
+        this.planMoved = true;
+        this.name = "SqlPlanMovedError";
+    }
+}
+/** A yodel run that did not succeed, with the code chant's table gives it. */
+export class YodelRunError extends Error {
+    constructor(message, 
+    /** The table's code for the run (`CHANT_EXIT`). Named so core never reads it as an exit code. */
+    chantExit, yodelExit) {
+        super(message);
+        this.chantExit = chantExit;
+        this.yodelExit = yodelExit;
+        this.name = "YodelRunError";
+    }
+}
+/** Where the capability keeps a run's yodel files, relative to the working directory. */
+export function sqlMigrateFiles(environment) {
+    const key = environment.replace(/[^A-Za-z0-9._-]/g, "_");
+    return { part: `.chant/sql/yodel/${key}.part.json`, wavePlan: `.chant/sql/yodel/${key}.wave-plan.json` };
+}
+function requireEnvironment(input) {
+    if (typeof input?.environment !== "string" || input.environment.trim() === "" || input.environment.startsWith("-")) {
+        throw new Error("sql-migrate: the step needs `environment`, the yodel environment to migrate (\"{target}\" in an op wave)");
+    }
+    if (input.spec !== undefined && (typeof input.spec !== "string" || input.spec === "" || input.spec.startsWith("-"))) {
+        throw new Error("sql-migrate: `spec` must name the op-waves spec file, such as \"yodel-waves.json\"");
+    }
+}
+const commonOf = (input) => ({
+    ...(input.dir ? { dir: input.dir } : {}),
+    ...(input.op ? { op: input.op } : {}),
+    ...(input.allowOutOfOrder ? { allowOutOfOrder: true } : {}),
+});
+/** The last few lines a failed run printed, for a message. */
+function tail(run) {
+    const text = (run.stderr || run.stdout).trim();
+    return text.split("\n").slice(-4).join("\n");
+}
+/** A failed yodel run as an error, its exit read through chant's table. */
+function runError(what, run, command, legacy) {
+    if (run.missingBinary)
+        return new YodelRunError(`${what}: the yodel binary was not found (the project's node_modules/.bin/yodel, or yodel on PATH); install @intentius/sql-yodeler`, CHANT_EXIT.failed, null);
+    const chantExit = yodelExitOf({ code: run.code, command, legacy });
+    return new YodelRunError(`${what} exited ${run.code === null ? "without a status" : String(run.code)}: ${tail(run)}`, chantExit, run.code);
+}
+function readJson(path) {
+    return JSON.parse(readFileSync(path, "utf-8"));
+}
+/** The destructive classes of a wave plan: each step's rules, as the engine's lint names them, sorted. */
+export function wavePlanDestructive(plan) {
+    const out = new Set();
+    for (const s of plan.destructiveSteps ?? [])
+        for (const why of (s.why ?? "").split(","))
+            if (why.trim())
+                out.add(why.trim());
+    return [...out].sort();
+}
+function isSqlMigrateArtifact(value) {
+    const v = value;
+    return v?.kind === "sql-migrate" && typeof v.environment === "string" && typeof v.planDigest === "string";
+}
+/** A legacy yodel's moved wave plan, read from the line it prints (it exits 1, as for any error). */
+const LEGACY_MOVED = /wave plan moved since the wave was decided/;
+/** The `sql-migrate` capability, with its runner and environment injectable. */
+export function createSqlMigrateCapability(deps = {}) {
+    const run = deps.run ?? defaultYodelRunner;
+    const cwdOf = deps.cwd ?? (() => process.cwd());
+    const envOf = deps.env ?? (() => process.env);
+    return {
+        kind: "sql-migrate",
+        // A migration has no undo short of a revert, which is a change of its own (`yodel revert`).
+        rollbackPolicy: "needs-opt-out",
+        targets: { refuse: "sql-migrate applies an environment's pending migrations in chain order, so it cannot narrow to some objects" },
+        // #4571: the environment's history is the grain; resource is refused by name (./lock-grain.ts).
+        defaultLockGrain: () => sqlDefaultLockGrain(),
+        lockGrainRefusal: (_input, grain) => sqlLockGrainRefusal("sql-migrate", grain),
+        async plan(_ctx, input) {
+            requireEnvironment(input);
+            const cwd = cwdOf();
+            const env = input.environment;
+            const files = sqlMigrateFiles(env);
+            const legacy = input.legacyExit === true;
+            const reader = readerEnv(envOf());
+            const opts = { cwd, env: reader, ...(input.dir ? { dir: input.dir } : {}) };
+            mkdirSync(dirname(join(cwd, files.part)), { recursive: true });
+            // A file an earlier plan left must not pass for this one's.
+            rmSync(join(cwd, files.part), { force: true });
+            rmSync(join(cwd, files.wavePlan), { force: true });
+            // The part: real counts, one entry per object the pending migrations touch.
+            const planned = await runAllowedYodel(run, yodelPlanArgs(env, files.part, commonOf(input)), opts);
+            if (!existsSync(join(cwd, files.part)))
+                throw runError(`sql-migrate: yodel plan ${env}`, planned, "plan", legacy);
+            const part = readChangeSetPartFile(readJson(join(cwd, files.part)), "sql", env, "sql");
+            if (part.member.status === "failed") {
+                // A refusal no approval fixes (a checksum, a fork, the directory): `failed` on chant's table (#4570).
+                throw new YodelRunError(`sql-migrate: yodel would refuse to apply ${env}: ${part.member.error ?? tail(planned)}`, CHANT_EXIT.failed, planned.code);
+            }
+            // 2: a pending step the engine does not run; the part still says which, and the wave plan refuses it.
+            if (planned.code !== 0 && planned.code !== 2)
+                throw runError(`sql-migrate: yodel plan ${env}`, planned, "plan", legacy);
+            if (input.spec === undefined) {
+                // A pull request's plan: the migrations' digest, the one `yodel approve` binds.
+                const planDigest = part.member.planDigest;
+                const artifact = { kind: "sql-migrate", environment: env, planDigest, migrations: planDigest, pending: [] };
+                return { member: env, planDigest, artifact, changeSet: part };
+            }
+            if (!existsSync(join(cwd, input.spec)))
+                throw new Error(`sql-migrate: the op-waves spec ${input.spec} is not in ${cwd}; the engine reads chant's decision for the wave by it`);
+            const waved = await runAllowedYodel(run, yodelWavePlanArgs(env, files.wavePlan, input.spec, commonOf(input)), opts);
+            if (waved.code !== 0 || !existsSync(join(cwd, files.wavePlan)))
+                throw runError(`sql-migrate: yodel apply ${env} --wave-plan`, waved, "apply", legacy);
+            const wave = readJson(join(cwd, files.wavePlan));
+            if (typeof wave.planDigest !== "string" || wave.planDigest === "")
+                throw new Error(`sql-migrate: ${files.wavePlan} has no planDigest; it is not a plan yodel apply --wave-plan wrote`);
+            const destructive = wavePlanDestructive(wave);
+            const artifact = {
+                kind: "sql-migrate",
+                environment: env,
+                planDigest: wave.planDigest,
+                wavePlan: files.wavePlan,
+                spec: input.spec,
+                ...(wave.migrations ? { migrations: wave.migrations } : {}),
+                pending: wave.pending ?? [],
+            };
+            // The member's digest is the wave plan's, so a gate on the member alone and the wave bind one value.
+            const changeSet = { ...part, member: { ...part.member, planDigest: wave.planDigest } };
+            return { member: env, planDigest: wave.planDigest, artifact, changeSet, ...(destructive.length > 0 ? { destructive } : {}) };
+        },
+        async run(ctx, input) {
+            requireEnvironment(input);
+            const env = input.environment;
+            const decided = ctx.plans?.[env];
+            if (!isSqlMigrateArtifact(decided) || decided.wavePlan === undefined || decided.spec === undefined) {
+                throw new Error(`sql-migrate: ${env} applies only the plan an op wave decided, planned with \`spec\`; migrations apply on the merged branch, never before the merge (sql-yodeler#285, ruling E). Nothing was applied`);
+            }
+            const cwd = cwdOf();
+            const legacy = input.legacyExit === true;
+            const file = join(cwd, decided.wavePlan);
+            if (!existsSync(file))
+                throw new Error(`sql-migrate: the wave plan of ${env} is gone from ${decided.wavePlan}; nothing was applied. Run the wave again`);
+            const onDisk = readJson(file);
+            if (onDisk.planDigest !== decided.planDigest) {
+                throw new SqlPlanMovedError(env, `sql-migrate: ${decided.wavePlan} holds plan ${String(onDisk.planDigest)}, and the wave decided ${decided.planDigest}; nothing was applied`);
+            }
+            // The apply alone runs with the job's environment, so the writer reaches it and nothing else.
+            const applied = await runAllowedYodel(run, yodelWaveApplyArgs(env, decided.wavePlan, decided.spec, commonOf(input)), { cwd, env: envOf(), ...(input.dir ? { dir: input.dir } : {}) });
+            if (applied.code === 0)
+                return { environment: env, planDigest: decided.planDigest, summary: applied.stdout.trim() };
+            const error = runError(`sql-migrate: yodel apply ${env} --wave-apply`, applied, "apply", legacy);
+            if (error.chantExit === CHANT_EXIT.moved || (legacy && LEGACY_MOVED.test(`${applied.stderr}\n${applied.stdout}`)))
+                throw new SqlPlanMovedError(env, error.message);
+            throw error;
+        },
+    };
+}
+export const sqlMigrateCapability = createSqlMigrateCapability();
+/** The dialect a build output names: `postgres`, else `clickhouse`. */
+export function buildDialect(path) {
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(path, "utf-8"));
+    }
+    catch (err) {
+        throw new Error(`sql-apply: the build ${path} cannot be read: ${err instanceof Error ? err.message : String(err)}. Run chant build first`);
+    }
+    const d = raw.sql && typeof raw.sql === "object" ? raw.sql.dialect : raw.dialect;
+    return d === "postgres" ? "postgres" : "clickhouse";
+}
+const pick = (o) => Object.fromEntries(Object.entries(o).filter(([, v]) => v !== undefined));
+async function defaultPlan(input, dialect) {
+    const cwd = input.cwd ? { cwd: input.cwd } : {};
+    if (dialect === "postgres") {
+        const { planPgAgainstServer } = await import("./postgres/plan/commands.js");
+        const diff = await planPgAgainstServer(input.environment, input.build, cwd);
+        const { HANDED_OFF } = await import("./postgres/migrate/handoff.js");
+        return {
+            dialect,
+            changes: diff.changes,
+            // A column rename or a type change across kinds is a PostgresMigrationOp's; the other expand and contract changes are made by hand.
+            refused: diff.refused.map((c) => ({ object: c.object, field: c.field, ...(HANDED_OFF.has(c.rule) ? { op: "PostgresMigrationOp" } : {}) })),
+            holes: [],
+            problems: [],
+        };
+    }
+    const { planAgainstServer } = await import("./clickhouse/plan/commands.js");
+    const { namedCollectionsFail } = await import("./clickhouse/live/named-collections.js");
+    const diff = await planAgainstServer(input.environment, input.build, cwd);
+    const missing = namedCollectionsFail(diff.namedCollections) ? diff.namedCollections.missing : [];
+    return {
+        dialect,
+        changes: diff.changes,
+        refused: diff.rebuilds.map((c) => ({ object: c.object, field: c.field, op: "ClickHouseRebuildOp" })),
+        holes: (diff.unreadable ?? []).map((u) => ({ address: u.object, type: u.type, reason: u.reason })),
+        problems: missing.length > 0 ? [`the build references named collection(s) the server does not have: ${missing.join(", ")}`] : [],
+    };
+}
+async function defaultApply(input, dialect) {
+    const args = pick({ buildPath: input.build, environment: input.environment, prune: input.prune, stack: input.stack, ownershipEnv: input.ownershipEnv, cwd: input.cwd });
+    const outcome = dialect === "postgres"
+        ? await (await import("./op/activities/postgres-apply.js")).postgresApply({
+            ...args,
+            buildPath: input.build,
+            ...pick({ lockTimeoutMs: input.lockTimeoutMs, statementTimeoutMs: input.statementTimeoutMs, scanTimeoutMs: input.scanTimeoutMs }),
+        })
+        : await (await import("./op/activities/clickhouse-apply.js")).clickhouseApply({ ...args, buildPath: input.build, ...pick({ mutationTimeoutMs: input.mutationTimeoutMs }) });
+    return {
+        applied: outcome.applied.map((a) => `${a.kind}/${a.name}`),
+        pruned: outcome.pruned.map((p) => `${p.kind}/${p.name}`),
+        notAttempted: outcome.notAttempted.map((n) => ({ name: `${n.kind}/${n.name}`, reason: `${n.reason}${n.detail ? `: ${n.detail}` : ""}` })),
+    };
+}
+function requireApplyInput(input) {
+    if (typeof input?.environment !== "string" || input.environment.trim() === "")
+        throw new Error("sql-apply: the step needs `environment`, which selects sql.profiles.<environment>");
+    if (typeof input.build !== "string" || input.build.trim() === "")
+        throw new Error("sql-apply: the step needs `build`, the chant build output to apply (dist/schema.json)");
+}
+/** Plan `input` and say why it cannot be applied, if it cannot. */
+async function planDeclarative(plan, input) {
+    const dialect = buildDialect(input.build);
+    const planned = await plan(input, dialect);
+    const why = [...planned.problems];
+    if (planned.refused.length > 0) {
+        why.push(`the applier does not make ${planned.refused.map((r) => `${r.object} (${r.field}${r.op ? `, run a ${r.op}` : ""})`).join(", ")} in place`);
+    }
+    if (planned.holes.length > 0)
+        why.push(`the plan cannot read ${planned.holes.map((h) => `${h.address}: ${h.reason}`).join("; ")}`);
+    if (why.length > 0)
+        throw new Error(`sql-apply: ${input.environment} cannot apply this build: ${why.join("; and ")}`);
+    const part = sqlDeclarativePlanPart({ member: input.environment, dialect, environment: input.environment, changes: planned.changes });
+    return { part, dialect };
+}
+/** The `sql-apply` capability, with its planner and applier injectable. */
+export function createSqlApplyCapability(deps = {}) {
+    const plan = deps.plan ?? defaultPlan;
+    const apply = deps.apply ?? defaultApply;
+    return {
+        kind: "sql-apply",
+        // An apply has no undo short of applying the previous build, which is a change of its own.
+        rollbackPolicy: "needs-opt-out",
+        targets: { refuse: "sql-apply applies a whole build, since its objects depend on each other in creation order" },
+        // #4571: the environment is the grain, as for sql-migrate.
+        defaultLockGrain: () => sqlDefaultLockGrain(),
+        lockGrainRefusal: (_input, grain) => sqlLockGrainRefusal("sql-apply", grain),
+        async plan(_ctx, input) {
+            requireApplyInput(input);
+            const { part, dialect } = await planDeclarative(plan, input);
+            const planDigest = part.member.planDigest;
+            const artifact = { kind: "sql-apply", environment: input.environment, dialect, planDigest };
+            return { member: input.environment, planDigest, artifact, changeSet: part };
+        },
+        async run(ctx, input) {
+            requireApplyInput(input);
+            const decided = ctx.plans?.[input.environment];
+            if (decided?.kind !== "sql-apply" || typeof decided.planDigest !== "string") {
+                throw new Error(`sql-apply: ${input.environment} applies only a plan that was planned and decided first (DeployContext.plans); nothing was applied`);
+            }
+            // Planned again just before the apply: a server or build that moved since the decision applies nothing.
+            const { part, dialect } = await planDeclarative(plan, input);
+            if (part.member.planDigest !== decided.planDigest) {
+                throw new SqlPlanMovedError(input.environment, `sql-apply: ${input.environment}'s plan moved since it was decided (decided ${decided.planDigest}, now ${String(part.member.planDigest)}); nothing was applied`);
+            }
+            const outcome = await apply(input, dialect);
+            if (outcome.notAttempted.length > 0 && outcome.applied.length === 0 && outcome.pruned.length === 0 && part.entries.length > 0) {
+                throw new Error(`sql-apply: nothing was applied to ${input.environment}: ${outcome.notAttempted.map((n) => `${n.name} (${n.reason})`).join(", ")}`);
+            }
+            return { environment: input.environment, dialect, planDigest: decided.planDigest, applied: outcome.applied, pruned: outcome.pruned };
+        },
+    };
+}
+export const sqlApplyCapability = createSqlApplyCapability();
+// ── the plugin ────────────────────────────────────────────────────────────────
+export const SQL_VERB_FAMILIES = {
+    apply: ["sql-apply", "sql-migrate"],
+};
+export const sqlCapabilityPlugin = {
+    name: "sql",
+    get version() {
+        return ownPackageVersion(import.meta.url);
+    },
+    capabilities() {
+        return [sqlMigrateCapability, sqlApplyCapability];
+    },
+    families() {
+        return SQL_VERB_FAMILIES;
+    },
+};

package/dist/change-set.d.ts

@@ -11,6 +11,8 @@
  * - the plan step of the lexicon's own migration Ops, `ClickHouseRebuildOp`
  *   and `PostgresMigrationOp`. {@link clickhouseRebuildPart} and
  *   {@link postgresMigrationPart}.
+ * - a declarative plan's classified changes, as the `sql-apply` capability
+ *   plans them (#4569). {@link sqlDeclarativePlanPart}.
  *
  * Each returns a part with planner `sql`, so it composes with every other
  * member's in `composeChangeSet`, and a gate that binds the document gets its
@@ -170,5 +172,38 @@ export declare function clickhouseRebuildPart(input: SqlOpPlanPartInput): Change
  * propose nothing.
  */
 export declare function postgresMigrationPart(input: SqlOpPlanPartInput): ChangeSetPart;
+/**
+ * One classified change of a declarative plan (`chant sql plan`): a build
+ * against the environment's server, as the dialects' classifiers write it.
+ */
+export interface SqlDeclarativeChange {
+    /** The object, as the plan labels it. */
+    object: string;
+    field: string;
+    rule: string;
+    class: string;
+    before?: string;
+    after?: string;
+    destructive?: boolean;
+}
+export interface SqlDeclarativePlanPartInput {
+    member: string;
+    dialect: "clickhouse" | "postgres";
+    /** The environment it plans into: the member's and every entry's `scope`. */
+    environment: string;
+    changes: readonly SqlDeclarativeChange[];
+    /** What the plan could not read (#3653), as holes. */
+    holes?: ChangeSetHole[];
+    /** Default `"sql"`. */
+    lexicon?: string;
+}
+/** The digest of a declarative plan: the dialect, the environment and every change, sorted. */
+export declare function sqlDeclarativePlanDigest(input: Pick<SqlDeclarativePlanPartInput, "dialect" | "environment" | "changes">): string;
+/**
+ * A declarative plan's part (#4569): one entry per object the changes touch,
+ * the action and disruption from their classes as for a versioned plan, the
+ * fields as attributes. Its digest is {@link sqlDeclarativePlanDigest}.
+ */
+export declare function sqlDeclarativePlanPart(input: SqlDeclarativePlanPartInput): ChangeSetPart;
 export {};
 //# sourceMappingURL=change-set.d.ts.map

package/dist/change-set.d.ts.map

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

package/dist/change-set.js

@@ -11,6 +11,8 @@
  * - the plan step of the lexicon's own migration Ops, `ClickHouseRebuildOp`
  *   and `PostgresMigrationOp`. {@link clickhouseRebuildPart} and
  *   {@link postgresMigrationPart}.
+ * - a declarative plan's classified changes, as the `sql-apply` capability
+ *   plans them (#4569). {@link sqlDeclarativePlanPart}.
  *
  * Each returns a part with planner `sql`, so it composes with every other
  * member's in `composeChangeSet`, and a gate that binds the document gets its
@@ -249,3 +251,44 @@ export function postgresMigrationPart(input) {
     const table = migration.split(".").slice(0, -1).join(".") || migration;
     return opPart(input, "PostgresMigrationOp", "migrate", table, "Postgres::Table");
 }
+/** The entry type a declarative change gets: the classified change names no object kind. */
+const DECLARATIVE_TYPE = { clickhouse: "ClickHouse::Object", postgres: "Postgres::Object" };
+/** The digest of a declarative plan: the dialect, the environment and every change, sorted. */
+export function sqlDeclarativePlanDigest(input) {
+    const changes = input.changes
+        .map((c) => ({ object: c.object, field: c.field, rule: c.rule, class: c.class, before: c.before ?? null, after: c.after ?? null, destructive: c.destructive === true }))
+        .sort((a, b) => (a.object === b.object ? (a.field < b.field ? -1 : a.field > b.field ? 1 : 0) : a.object < b.object ? -1 : 1));
+    return computePlanDigest("sql-declarative-plan", { dialect: input.dialect, environment: input.environment, changes });
+}
+/**
+ * A declarative plan's part (#4569): one entry per object the changes touch,
+ * the action and disruption from their classes as for a versioned plan, the
+ * fields as attributes. Its digest is {@link sqlDeclarativePlanDigest}.
+ */
+export function sqlDeclarativePlanPart(input) {
+    const lexicon = input.lexicon ?? SQL_CHANGE_SET_LEXICON;
+    const byAddress = new Map();
+    for (const c of input.changes) {
+        let o = byAddress.get(c.object);
+        if (!o) {
+            o = { address: c.object, type: DECLARATIVE_TYPE[input.dialect], classes: [], actions: [], destructive: false, ops: [], manual: [], sql: [], fields: new Map() };
+            byAddress.set(c.object, o);
+        }
+        o.classes.push(c.class);
+        if (c.destructive)
+            o.destructive = true;
+        o.fields.set(c.field, { rule: c.rule, class: c.class, field: c.field, ...(c.before !== undefined ? { before: c.before } : {}), ...(c.after !== undefined ? { after: c.after } : {}), ...(c.destructive ? { destructive: true } : {}) });
+    }
+    return {
+        member: {
+            member: input.member,
+            lexicon,
+            planner: "sql",
+            scope: input.environment,
+            status: "planned",
+            planDigest: sqlDeclarativePlanDigest(input),
+            holes: input.holes ?? [],
+        },
+        entries: entriesOf(input.member, lexicon, input.environment, [...byAddress.values()]),
+    };
+}