@intentius/chant-lexicon-sql 0.124.54 → 0.124.56

package/dist/yodel-run.js

@@ -0,0 +1,145 @@
+/**
+ * Running sql-yodeler's versioned migration engine (`yodel`) for the sql
+ * lexicon's `sql-migrate` capability (#4569). The ruling on
+ * sql-yodeler#285 (A) keeps the engine in sql-yodeler and has chant run it
+ * through a fixed argv list, the way the pulumi lexicon runs plunge
+ * (`lexicons/pulumi/src/run.ts`). {@link YODEL_COMMANDS} is that list, and
+ * {@link runAllowedYodel} refuses any argv off it before it reaches the
+ * runner, so no later caller can make this module run another yodel verb.
+ *
+ * The three commands, each the engine's own entry point:
+ *
+ * - `yodel plan <env> --part <file>`: the pending migrations as a chant
+ *   change-set part (sql-yodeler#237, built by this lexicon's
+ *   `sqlVersionedPlanPart`), one entry per object with its change classes.
+ *   Reads only.
+ * - `yodel apply <env> --wave-plan <file> --spec <spec>`: the wave plan the
+ *   op wave's gate binds. Its digest covers the migrations' digest, the
+ *   environment's gate policy at the base commit, whether a pending step is
+ *   destructive, and the promotion evidence. Reads only.
+ * - `yodel apply <env> --wave-apply <file> --spec <spec>`: applies that
+ *   plan under the engine's lock. The engine plans again under the lock and
+ *   refuses a plan that moved, and it checks chant's decision for the wave
+ *   and the gate ledger's approval itself (ruling A on sql-yodeler#300).
+ *
+ * Each may carry, in this order and no other, `--dir <project>`, `--op
+ * <name>` and `--allow-out-of-order`. A value must not start with a dash.
+ *
+ * ## Credentials
+ *
+ * The two planning commands run with the writer taken out of their
+ * environment ({@link readerEnv}): no `YODEL_ROLE` or `YODEL_CREDENTIALS`,
+ * which pick the writer, and no `<ENV>_<DIALECT>_WRITER_USER` or
+ * `..._WRITER_PASSWORD`, the writer's default variables. Only the apply runs
+ * with the job's environment as given, so the writer reaches the apply
+ * alone even when one job plans and applies.
+ *
+ * The runner is injectable, so the tests run no binary.
+ */
+import { execFile } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+/**
+ * The only yodel commands chant runs (ruling A on sql-yodeler#285). Each
+ * may be followed by `--dir <project>`, `--op <name>` and
+ * `--allow-out-of-order`, in that order ({@link YODEL_OPTIONAL_FLAGS}).
+ */
+export const YODEL_COMMANDS = [
+    "yodel plan <env> --part <file>",
+    "yodel apply <env> --wave-plan <file> --spec <spec>",
+    "yodel apply <env> --wave-apply <file> --spec <spec>",
+];
+/** The flags any of {@link YODEL_COMMANDS} may end with, in this order. */
+export const YODEL_OPTIONAL_FLAGS = ["--dir <project>", "--op <name>", "--allow-out-of-order"];
+function common(opts) {
+    return [...(opts.dir ? ["--dir", opts.dir] : []), ...(opts.op ? ["--op", opts.op] : []), ...(opts.allowOutOfOrder ? ["--allow-out-of-order"] : [])];
+}
+/** `yodel plan <env> --part <file>`, without the binary. */
+export function yodelPlanArgs(env, part, opts = {}) {
+    return ["plan", env, "--part", part, ...common(opts)];
+}
+/** `yodel apply <env> --wave-plan <file> --spec <spec>`, without the binary. */
+export function yodelWavePlanArgs(env, file, spec, opts = {}) {
+    return ["apply", env, "--wave-plan", file, "--spec", spec, ...common(opts)];
+}
+/** `yodel apply <env> --wave-apply <file> --spec <spec>`, without the binary. */
+export function yodelWaveApplyArgs(env, file, spec, opts = {}) {
+    return ["apply", env, "--wave-apply", file, "--spec", spec, ...common(opts)];
+}
+/** A value after a flag: present, and not itself a flag. */
+const value = (v) => typeof v === "string" && v.length > 0 && !v.startsWith("-");
+/** The optional tail: `--dir <d>`, `--op <n>`, `--allow-out-of-order`, each at most once, in that order. */
+function allowedTail(rest) {
+    let i = 0;
+    if (rest[i] === "--dir") {
+        if (!value(rest[i + 1]))
+            return false;
+        i += 2;
+    }
+    if (rest[i] === "--op") {
+        if (!value(rest[i + 1]))
+            return false;
+        i += 2;
+    }
+    if (rest[i] === "--allow-out-of-order")
+        i += 1;
+    return i === rest.length;
+}
+/** Whether `args` is one of {@link YODEL_COMMANDS} with an allowed tail. */
+export function allowedYodelArgv(args) {
+    if (!value(args[1]))
+        return false;
+    if (args[0] === "plan")
+        return args[2] === "--part" && value(args[3]) && allowedTail(args.slice(4));
+    if (args[0] === "apply") {
+        return (args[2] === "--wave-plan" || args[2] === "--wave-apply") && value(args[3]) && args[4] === "--spec" && value(args[5]) && allowedTail(args.slice(6));
+    }
+    return false;
+}
+/** Whether `args` is the apply, the one command that writes. */
+export function isYodelApplyArgv(args) {
+    return args[0] === "apply" && args[2] === "--wave-apply";
+}
+/** Run `args` through `run`, refusing any argv off {@link YODEL_COMMANDS}. */
+export async function runAllowedYodel(run, args, opts) {
+    if (!allowedYodelArgv(args)) {
+        throw new Error(`chant runs only ${YODEL_COMMANDS.join(", ")} (each optionally with ${YODEL_OPTIONAL_FLAGS.join(", ")}) for a SQL member, not yodel ${args.join(" ")}`);
+    }
+    return run(args, opts);
+}
+/** The variables that pick the writer (sql-yodeler `credentials.ts`). */
+export const YODEL_ROLE_VARIABLES = ["YODEL_ROLE", "YODEL_CREDENTIALS"];
+/** A writer's default user and password variables, `<ENV>_<DIALECT>_WRITER_USER` and `..._WRITER_PASSWORD`. */
+const WRITER_VARIABLE = /^[A-Z0-9_]+_(CLICKHOUSE|POSTGRES)_WRITER_(USER|PASSWORD)$/;
+/** `env` with the writer taken out: what the planning commands run with. */
+export function readerEnv(env = process.env) {
+    const out = {};
+    for (const [k, v] of Object.entries(env)) {
+        if (YODEL_ROLE_VARIABLES.includes(k) || WRITER_VARIABLE.test(k))
+            continue;
+        out[k] = v;
+    }
+    return out;
+}
+/**
+ * The yodel binary: the project's `node_modules/.bin/yodel`, else the
+ * working directory's, else `yodel` on PATH. Always a file named `yodel`.
+ */
+export function yodelBinary(cwd, dir) {
+    for (const base of [...(dir ? [join(cwd, dir)] : []), cwd]) {
+        const bin = join(base, "node_modules", ".bin", "yodel");
+        if (existsSync(bin))
+            return bin;
+    }
+    return "yodel";
+}
+export const defaultYodelRunner = (args, opts) => new Promise((resolve) => {
+    execFile(yodelBinary(opts.cwd, opts.dir), args, { cwd: opts.cwd, env: opts.env, maxBuffer: 64 * 1024 * 1024 }, (err, stdout, stderr) => {
+        if (!err)
+            return resolve({ code: 0, stdout, stderr });
+        const e = err;
+        if (e.code === "ENOENT")
+            return resolve({ code: null, stdout, stderr: stderr || e.message, missingBinary: true });
+        resolve({ code: typeof e.code === "number" ? e.code : null, stdout, stderr: stderr || e.message });
+    });
+});

package/package.json

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

package/src/capability-plugin.test.ts

@@ -0,0 +1,317 @@
+/**
+ * The sql lexicon's capabilities (#4569): `sql-migrate` runs sql-yodeler's
+ * engine through the fixed argv list (ruling A on sql-yodeler#285), and
+ * `sql-apply` plans and applies a build with the lexicon's appliers. The
+ * runner, planner and applier are fakes; the last block runs
+ * `testdata/fake-yodel.mjs` as the project's `node_modules/.bin/yodel`, so no
+ * real yodel and no server is involved.
+ */
+import { chmodSync, copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { describe, expect, test } from "vitest";
+import { CapabilityRegistry, isPlanMovedError } from "@intentius/chant/components/capability";
+import { isCapabilityPlugin } from "@intentius/chant/components/capability-plugin";
+import { CHANT_EXIT } from "@intentius/chant/exit-codes";
+import { planOpWaveStep, applyOpWaveStep } from "@intentius/chant/op/op-waves-capability";
+import type { OpWavesSpec } from "@intentius/chant/op/op-waves";
+import {
+  createSqlApplyCapability,
+  createSqlMigrateCapability,
+  sqlCapabilityPlugin,
+  sqlMigrateFiles,
+  wavePlanDestructive,
+  YodelRunError,
+  type SqlDeclarativePlan,
+} from "./capability-plugin";
+import { allowedYodelArgv, defaultYodelRunner, readerEnv, runAllowedYodel, YODEL_COMMANDS, type YodelRunner } from "./yodel-run";
+
+const scratch = () => mkdtempSync(join(tmpdir(), "chant-sql-capability-"));
+
+function writeJson(path: string, doc: unknown): void {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(doc)}\n`);
+}
+
+const part = (env: string, digest = "jcs1-sha256:migrations", status: "planned" | "failed" = "planned") => ({
+  member: { member: "app", lexicon: "sql", planner: "sql", scope: env, status, ...(status === "failed" ? { error: "0001_init's checksum does not match the history" } : {}), planDigest: status === "failed" ? null : digest, holes: [] },
+  entries: [{ member: "app", lexicon: "sql", planner: "sql", address: "app.users", type: "Postgres::Table", action: "update", disruption: "rolling", scope: env, attributes: [] }],
+});
+
+/** A runner that writes what yodel would, and records each call with its environment. */
+function fakeRunner(cwd: string, answers: { planStatus?: "planned" | "failed"; waveDigest?: string; applyCode?: number; applyStderr?: string } = {}) {
+  const calls: Array<{ args: string[]; env: NodeJS.ProcessEnv }> = [];
+  const run: YodelRunner = async (args, opts) => {
+    calls.push({ args, env: opts.env });
+    if (args[0] === "plan") {
+      writeJson(join(cwd, args[3]!), part(args[1]!, undefined, answers.planStatus));
+      return { code: answers.planStatus === "failed" ? 4 : 0, stdout: "", stderr: "" };
+    }
+    if (args[2] === "--wave-plan") {
+      writeJson(join(cwd, args[3]!), {
+        planDigest: answers.waveDigest ?? "jcs1-sha256:wave",
+        migrations: "jcs1-sha256:migrations",
+        environment: args[1],
+        empty: false,
+        pending: ["0002_users_email"],
+        destructiveSteps: [{ migration: "0002_users_email", step: 0, why: "pg-rewrite, pg-lock" }],
+      });
+      return { code: 0, stdout: "", stderr: "" };
+    }
+    const code = answers.applyCode ?? 0;
+    return { code, stdout: code === 0 ? "Applied: 0002_users_email\n" : "", stderr: answers.applyStderr ?? "" };
+  };
+  return { run, calls };
+}
+
+const jobEnv = { PATH: "/usr/bin", YODEL_ROLE: "writer:dev", DEV_POSTGRES_WRITER_USER: "w", DEV_POSTGRES_WRITER_PASSWORD: "secret", DEV_POSTGRES_READER_USER: "r", DEV_POSTGRES_READER_PASSWORD: "read" };
+
+describe("the yodel argv list (ruling A on sql-yodeler#285)", () => {
+  test("the three commands, with the optional tail in order, are allowed", () => {
+    expect(YODEL_COMMANDS).toEqual(["yodel plan <env> --part <file>", "yodel apply <env> --wave-plan <file> --spec <spec>", "yodel apply <env> --wave-apply <file> --spec <spec>"]);
+    expect(allowedYodelArgv(["plan", "dev", "--part", "p.json"])).toBe(true);
+    expect(allowedYodelArgv(["apply", "prod/@1of4", "--wave-plan", "w.json", "--spec", "yodel-waves.json", "--dir", "db", "--op", "migrate-prod", "--allow-out-of-order"])).toBe(true);
+    expect(allowedYodelArgv(["apply", "dev", "--wave-apply", "w.json", "--spec", "yodel-waves.json"])).toBe(true);
+  });
+
+  test("anything else is refused before it runs", async () => {
+    for (const args of [
+      ["apply", "dev", "--execute"],
+      ["apply", "dev"],
+      ["plan", "dev", "--part", "p.json", "--comment"],
+      ["plan", "dev", "--part", "--comment"],
+      ["plan", "--json", "--part", "p.json"],
+      ["apply", "dev", "--wave-apply", "w.json", "--spec", "s.json", "--op", "x", "--dir", "db"],
+      ["apply", "dev", "--wave-apply", "w.json"],
+      ["revert", "dev", "0001"],
+      ["approve", "dev"],
+    ]) {
+      expect(allowedYodelArgv(args)).toBe(false);
+    }
+    let ran = false;
+    await expect(runAllowedYodel(async () => ((ran = true), { code: 0, stdout: "", stderr: "" }), ["apply", "dev", "--execute"], { cwd: ".", env: {} })).rejects.toThrow(/chant runs only/);
+    expect(ran).toBe(false);
+  });
+
+  test("the planning environment has no writer", () => {
+    const env = readerEnv({ ...jobEnv, YODEL_CREDENTIALS: "writer", PROD_CLICKHOUSE_WRITER_PASSWORD: "x" });
+    expect(env).toEqual({ PATH: "/usr/bin", DEV_POSTGRES_READER_USER: "r", DEV_POSTGRES_READER_PASSWORD: "read" });
+  });
+});
+
+describe("sql-migrate", () => {
+  test("a pull request's plan: the part with real counts, under the migrations' digest", async () => {
+    const cwd = scratch();
+    const { run, calls } = fakeRunner(cwd);
+    const cap = createSqlMigrateCapability({ run, cwd: () => cwd, env: () => jobEnv });
+    const planned = await cap.plan!({ env: "dev", component: "db" }, { environment: "dev" });
+    expect(calls.map((c) => c.args)).toEqual([["plan", "dev", "--part", sqlMigrateFiles("dev").part]]);
+    expect(planned.member).toBe("dev");
+    expect(planned.planDigest).toBe("jcs1-sha256:migrations");
+    expect(planned.changeSet?.member.member).toBe("dev");
+    expect(planned.changeSet?.entries.map((e) => [e.member, e.address, e.action])).toEqual([["dev", "app.users", "update"]]);
+    expect(planned.destructive).toBeUndefined();
+    expect(calls[0]!.env.YODEL_ROLE).toBeUndefined();
+    expect(calls[0]!.env.DEV_POSTGRES_WRITER_PASSWORD).toBeUndefined();
+  });
+
+  test("a pull request's plan does not apply: run refuses without a wave's plan (ruling E)", async () => {
+    const cwd = scratch();
+    const { run, calls } = fakeRunner(cwd);
+    const cap = createSqlMigrateCapability({ run, cwd: () => cwd, env: () => jobEnv });
+    const planned = await cap.plan!({ env: "dev", component: "db" }, { environment: "dev" });
+    await expect(cap.run({ env: "dev", component: "db", plans: { dev: planned.artifact } }, { environment: "dev" })).rejects.toThrow(/merged branch/);
+    await expect(cap.run({ env: "dev", component: "db" }, { environment: "dev" })).rejects.toThrow(/only the plan an op wave decided/);
+    expect(calls.filter((c) => c.args[2] === "--wave-apply")).toEqual([]);
+  });
+
+  test("a plan the engine would refuse fails, naming the refusal", async () => {
+    const cwd = scratch();
+    const { run } = fakeRunner(cwd, { planStatus: "failed" });
+    const cap = createSqlMigrateCapability({ run, cwd: () => cwd, env: () => jobEnv });
+    const err = await cap.plan!({ env: "dev", component: "db" }, { environment: "dev" }).catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(YodelRunError);
+    expect((err as Error).message).toMatch(/checksum does not match/);
+    expect((err as YodelRunError).chantExit).toBe(CHANT_EXIT.failed);
+  });
+
+  test("in an op wave: the wave plan's digest, the engine's destructive classes, then the apply with the writer", async () => {
+    const cwd = scratch();
+    writeJson(join(cwd, "yodel-waves.json"), { name: "yodel-apply", waves: [{ name: "dev", runs: [{ target: "dev" }] }] });
+    const { run, calls } = fakeRunner(cwd);
+    const cap = createSqlMigrateCapability({ run, cwd: () => cwd, env: () => jobEnv });
+    const input = { environment: "dev", spec: "yodel-waves.json", dir: "db" };
+    const planned = await cap.plan!({ env: "dev", component: "dev" }, input);
+    expect(planned.planDigest).toBe("jcs1-sha256:wave");
+    expect(planned.changeSet?.member.planDigest).toBe("jcs1-sha256:wave");
+    expect(planned.destructive).toEqual(["pg-lock", "pg-rewrite"]);
+    const out = await cap.run({ env: "dev", component: "dev", plans: { dev: planned.artifact } }, input);
+    expect(out.summary).toBe("Applied: 0002_users_email");
+    const files = sqlMigrateFiles("dev");
+    expect(calls.map((c) => c.args)).toEqual([
+      ["plan", "dev", "--part", files.part, "--dir", "db"],
+      ["apply", "dev", "--wave-plan", files.wavePlan, "--spec", "yodel-waves.json", "--dir", "db"],
+      ["apply", "dev", "--wave-apply", files.wavePlan, "--spec", "yodel-waves.json", "--dir", "db"],
+    ]);
+    // The writer reaches the apply alone.
+    expect(calls.map((c) => c.env.DEV_POSTGRES_WRITER_PASSWORD ?? null)).toEqual([null, null, "secret"]);
+    expect(calls.map((c) => c.env.YODEL_ROLE ?? null)).toEqual([null, null, "writer:dev"]);
+  });
+
+  test("an apply the engine refuses as moved is a moved plan; a held lock is not", async () => {
+    const cwd = scratch();
+    writeJson(join(cwd, "yodel-waves.json"), { name: "yodel-apply", waves: [{ name: "dev", runs: [{ target: "dev" }] }] });
+    const input = { environment: "dev", spec: "yodel-waves.json" };
+    for (const [answers, moved, chantExit] of [
+      [{ applyCode: 4 }, true, CHANT_EXIT.moved],
+      [{ applyCode: 1, applyStderr: "refused: dev's wave plan moved since the wave was decided" }, false, CHANT_EXIT.failed],
+      [{ applyCode: 5 }, false, CHANT_EXIT.held],
+    ] as const) {
+      const { run } = fakeRunner(cwd, answers);
+      const cap = createSqlMigrateCapability({ run, cwd: () => cwd, env: () => jobEnv });
+      const planned = await cap.plan!({ env: "dev", component: "dev" }, input);
+      const err = await cap.run({ env: "dev", component: "dev", plans: { dev: planned.artifact } }, input).catch((e: unknown) => e);
+      expect(isPlanMovedError(err)).toBe(moved);
+      if (!moved) expect((err as YodelRunError).chantExit).toBe(chantExit);
+    }
+  });
+
+  test("a legacy yodel's moved plan is read from its line", async () => {
+    const cwd = scratch();
+    writeJson(join(cwd, "yodel-waves.json"), { name: "yodel-apply", waves: [{ name: "dev", runs: [{ target: "dev" }] }] });
+    const input = { environment: "dev", spec: "yodel-waves.json", legacyExit: true };
+    const { run } = fakeRunner(cwd, { applyCode: 1, applyStderr: "refused: dev's wave plan moved since the wave was decided (decided a, now b)" });
+    const cap = createSqlMigrateCapability({ run, cwd: () => cwd, env: () => jobEnv });
+    const planned = await cap.plan!({ env: "dev", component: "dev" }, input);
+    const err = await cap.run({ env: "dev", component: "dev", plans: { dev: planned.artifact } }, input).catch((e: unknown) => e);
+    expect(isPlanMovedError(err)).toBe(true);
+  });
+
+  test("a wave plan file rewritten since the decision refuses as moved, and yodel never runs", async () => {
+    const cwd = scratch();
+    writeJson(join(cwd, "yodel-waves.json"), { name: "yodel-apply", waves: [{ name: "dev", runs: [{ target: "dev" }] }] });
+    const input = { environment: "dev", spec: "yodel-waves.json" };
+    const { run, calls } = fakeRunner(cwd);
+    const cap = createSqlMigrateCapability({ run, cwd: () => cwd, env: () => jobEnv });
+    const planned = await cap.plan!({ env: "dev", component: "dev" }, input);
+    writeJson(join(cwd, sqlMigrateFiles("dev").wavePlan), { planDigest: "jcs1-sha256:other", migrations: "x" });
+    const err = await cap.run({ env: "dev", component: "dev", plans: { dev: planned.artifact } }, input).catch((e: unknown) => e);
+    expect(isPlanMovedError(err)).toBe(true);
+    expect(calls.some((c) => c.args[2] === "--wave-apply")).toBe(false);
+  });
+
+  test("an op wave's step plans through it, destructive by the engine's classes, and applies with no callback", async () => {
+    const cwd = scratch();
+    writeJson(join(cwd, "yodel-waves.json"), { name: "yodel-apply", waves: [{ name: "dev", runs: [{ target: "dev" }] }] });
+    const { run, calls } = fakeRunner(cwd);
+    const registry = new CapabilityRegistry().register(createSqlMigrateCapability({ run, cwd: () => cwd, env: () => jobEnv }));
+    const spec = { name: "yodel-apply", op: "migrate-dev", step: { kind: "sql-migrate", environment: "{target}", spec: "yodel-waves.json" }, waves: [{ name: "dev", runs: [{ target: "dev" }] }] } as unknown as OpWavesSpec;
+    const wave = spec.waves[0]!;
+    const runOf = wave.runs![0]!;
+    const plan = await planOpWaveStep({ spec, wave, cwd, registry, planPath: ".chant/op-waves/yodel-apply/wave-1/dev.plan.json" }, runOf);
+    expect(plan.planDigest).toBe("jcs1-sha256:wave");
+    expect(plan.destructive).toBe(true);
+    expect(plan.empty).toBe(false);
+    const applied = await applyOpWaveStep({ spec, wave, registry }, runOf, plan);
+    expect(applied.outcome).toBe("applied");
+    expect(calls.map((c) => c.args[2] ?? c.args[0])).toEqual(["--part", "--wave-plan", "--wave-apply"]);
+  });
+
+  test("wavePlanDestructive splits and sorts each step's rules", () => {
+    expect(wavePlanDestructive({ destructiveSteps: [{ why: "op-step" }, { why: "destructive, pg-lock" }, { why: "pg-lock" }] })).toEqual(["destructive", "op-step", "pg-lock"]);
+    expect(wavePlanDestructive({})).toEqual([]);
+  });
+});
+
+describe("sql-migrate against a fake yodel binary", () => {
+  test("the project's node_modules/.bin/yodel runs, and only the apply holds the writer", async () => {
+    const cwd = scratch();
+    const bin = join(cwd, "node_modules", ".bin", "yodel");
+    mkdirSync(dirname(bin), { recursive: true });
+    copyFileSync(join(import.meta.dirname, "testdata", "fake-yodel.mjs"), bin);
+    chmodSync(bin, 0o755);
+    writeJson(join(cwd, "yodel-waves.json"), { name: "yodel-apply", waves: [{ name: "dev", runs: [{ target: "dev" }] }] });
+    const log = join(cwd, "calls.jsonl");
+    const cap = createSqlMigrateCapability({ run: defaultYodelRunner, cwd: () => cwd, env: () => ({ ...process.env, ...jobEnv, PATH: process.env.PATH, FAKE_YODEL_LOG: log }) });
+    const input = { environment: "dev", spec: "yodel-waves.json" };
+    const planned = await cap.plan!({ env: "dev", component: "dev" }, input);
+    expect(planned.changeSet?.entries.map((e) => e.action).sort()).toEqual(["create", "update"]);
+    const out = await cap.run({ env: "dev", component: "dev", plans: { dev: planned.artifact } }, input);
+    expect(out.summary).toBe("Applied: 0002_users_email");
+    expect(existsSync(log)).toBe(true);
+    const lines = readFileSync(log, "utf-8").trim().split("\n").map((l) => JSON.parse(l) as { args: string[]; role: string | null; writer: string | null });
+    expect(lines.map((l) => [l.args[0], l.args[2], l.role, l.writer])).toEqual([
+      ["plan", "--part", null, null],
+      ["apply", "--wave-plan", null, null],
+      ["apply", "--wave-apply", "writer:dev", "secret"],
+    ]);
+  });
+});
+
+describe("sql-apply", () => {
+  const build = (dialect: "clickhouse" | "postgres") => {
+    const cwd = scratch();
+    const path = join(cwd, "schema.json");
+    writeJson(path, { dialect });
+    return path;
+  };
+  const plan = (over: Partial<SqlDeclarativePlan> = {}): SqlDeclarativePlan => ({
+    dialect: "postgres",
+    changes: [
+      { object: "app.users", field: "columns.email", rule: "SQLPG201", class: "metadata", after: "text" },
+      { object: "app.users", field: "columns.name", rule: "SQLPG240", class: "rewrite" },
+      { object: "app.audit", field: "name", rule: "SQLPG100", class: "create" },
+    ],
+    refused: [],
+    holes: [],
+    problems: [],
+    ...over,
+  });
+
+  test("plans the build against the server as one entry per object, and applies the decided plan", async () => {
+    const path = build("postgres");
+    const applied: string[] = [];
+    const cap = createSqlApplyCapability({ plan: async () => plan(), apply: async (input, dialect) => (applied.push(`${dialect}:${input.environment}`), { applied: ["table/app.users"], pruned: [], notAttempted: [] }) });
+    const planned = await cap.plan!({ env: "prod", component: "db" }, { environment: "prod", build: path });
+    expect(planned.changeSet?.entries.map((e) => [e.address, e.action, e.disruption])).toEqual([
+      ["app.users", "update", "rolling"],
+      ["app.audit", "create", undefined],
+    ]);
+    const out = await cap.run({ env: "prod", component: "db", plans: { prod: planned.artifact } }, { environment: "prod", build: path });
+    expect(out.applied).toEqual(["table/app.users"]);
+    expect(applied).toEqual(["postgres:prod"]);
+  });
+
+  test("a server that moved since the decision refuses as moved and sends nothing", async () => {
+    const path = build("postgres");
+    let n = 0;
+    let sent = false;
+    const cap = createSqlApplyCapability({
+      plan: async () => (n++ === 0 ? plan() : plan({ changes: [{ object: "app.users", field: "columns.email", rule: "SQLPG201", class: "drop", destructive: true }] })),
+      apply: async () => ((sent = true), { applied: [], pruned: [], notAttempted: [] }),
+    });
+    const planned = await cap.plan!({ env: "prod", component: "db" }, { environment: "prod", build: path });
+    const err = await cap.run({ env: "prod", component: "db", plans: { prod: planned.artifact } }, { environment: "prod", build: path }).catch((e: unknown) => e);
+    expect(isPlanMovedError(err)).toBe(true);
+    expect(sent).toBe(false);
+  });
+
+  test("a rebuild the applier refuses fails the plan, naming the Op", async () => {
+    const path = build("clickhouse");
+    const cap = createSqlApplyCapability({ plan: async () => plan({ dialect: "clickhouse", refused: [{ object: "db.events", field: "orderBy", op: "ClickHouseRebuildOp" }] }) });
+    await expect(cap.plan!({ env: "prod", component: "db" }, { environment: "prod", build: path })).rejects.toThrow(/ClickHouseRebuildOp/);
+  });
+
+  test("run refuses with no decided plan", async () => {
+    const path = build("postgres");
+    const cap = createSqlApplyCapability({ plan: async () => plan() });
+    await expect(cap.run({ env: "prod", component: "db" }, { environment: "prod", build: path })).rejects.toThrow(/planned and decided first/);
+  });
+});
+
+describe("the plugin", () => {
+  test("is a capability plugin with both kinds", () => {
+    expect(isCapabilityPlugin(sqlCapabilityPlugin)).toBe(true);
+    expect(sqlCapabilityPlugin.capabilities().map((c) => c.kind)).toEqual(["sql-migrate", "sql-apply"]);
+  });
+});