@intentius/chant-lexicon-sql 0.124.54 → 0.124.55

package/src/clickhouse/plan/deep.ts

@@ -18,10 +18,15 @@
  * server's, that copy is what is reported, with the server in `observedOn`,
  * which the drift report prints as `seen on`.
  *
- * Where the profile manages access, the grants an apply would give or take
- * from each declared grantee are reported as `pending` (#3733), the same
- * statements `chant sql plan` plans (SQLCH273, SQLCH274), so a privilege
- * granted or revoked by hand after an approval moves the plan digest.
+ * Where the profile manages access, each grant declaration is read as
+ * `grants.<grantee>.<atom>` (#4582): a privilege or role it declares that the
+ * grantee does not hold (revoked by hand, SQLCH273) is `absent` drift on that
+ * declaration. A grant declaration whose grantee the server does not have is
+ * not read here; the thin diff reports it missing. A privilege a grantee holds
+ * that no declaration gives (granted by hand, SQLCH274) belongs to no one
+ * declaration, so it is reported as `pending` (#3733) with every statement an
+ * apply would send that grantee, as `chant sql plan` plans them. Either way a
+ * privilege granted or revoked by hand after an approval moves the plan digest.
  */
 
 import {
@@ -39,7 +44,7 @@ import { sqlString } from "../apply/statements";
 import { stripMarkerFromStatement } from "../ownership";
 import { database, dictionary, func, policy, quota, role, settingsProfile, table, user, view, CLICKHOUSE_ENTITY_TYPES, type ColumnDef } from "../entities";
 import { canonicalObject, grantsObject, objectKey, type CanonicalColumn, type CanonicalObject } from "./normalize";
-import { grantStatement, grantsByGrantee, revokeStatement, type GrantAtom } from "../access";
+import { atomKey, declaredGrantAtoms, grantStatement, grantsByGrantee, holdsAtom, revokeStatement, type GrantAtom } from "../access";
 import { renderFor } from "../topology";
 
 type Props = Record<string, unknown>;
@@ -47,8 +52,48 @@ type Props = Record<string, unknown>;
 // `concurrently` is how a Postgres index is created, not a property of it.
 const PRUNED = new Set(["ddl", "source", "lineage", "reads", "to", "orReplace", "ifNotExists", "concurrently"]);
 
+/** What a held grant atom reads as, on both sides of the diff. */
+const GRANTED = "granted";
+
+/**
+ * A grant declaration's tree as the diff compares it (#4582):
+ * `{ grants: { <grantee>: { <atom>: "granted" } } }`, each atom as the
+ * declaration spells it. The reader writes the live side in the same shape,
+ * with the atoms the grantee holds. Undefined when the statement does not
+ * parse as a grant.
+ */
+export function declaredGrantTree(ddl: string): Props | undefined {
+  try {
+    const grants: Record<string, Record<string, string>> = {};
+    for (const { grantee, key } of declaredGrantAtoms(ddl)) (grants[grantee] ??= {})[key] = GRANTED;
+    return { grants };
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * A grant declaration's live tree (#4582): each atom it declares that the
+ * grantee holds, keyed as {@link declaredGrantTree} keys it. Undefined when
+ * the server does not have one of its grantees.
+ */
+export function liveGrantTree(ddl: string, held: ReadonlyMap<string, readonly GrantAtom[]>, defaultDatabase: string): Props | undefined {
+  const grants: Record<string, Record<string, string>> = {};
+  for (const { grantee, key, atom } of declaredGrantAtoms(ddl, defaultDatabase)) {
+    const have = held.get(grantee);
+    if (!have) return undefined;
+    if (holdsAtom(have, atom)) (grants[grantee] ??= {})[key] = GRANTED;
+  }
+  return Object.keys(grants).length > 0 ? { grants } : {};
+}
+
 export const sqlDeepNormalizationHooks: DeepNormalizationHooks = {
   prune: (node) => PRUNED.has(node.pattern.split(/[.[]/)[0]!),
+  // A grant declaration is compared atom by atom (#4582); the reader writes the live side in this shape.
+  prepare: (tree, { entityType, side }) => {
+    if (entityType !== CLICKHOUSE_ENTITY_TYPES.grant || side !== "declared" || typeof tree.ddl !== "string") return tree;
+    return declaredGrantTree(tree.ddl) ?? tree;
+  },
 };
 
 function liveProps(o: LiveObject): Props {
@@ -259,9 +304,11 @@ export async function observeResourcesDeep(
     return deepObservation({}, unobserved);
   }
   const pending: DeepPendingChange[] = [];
+  let held: Map<string, GrantAtom[]> | undefined;
   if (target.access === true) {
     try {
-      pending.push(...(await pendingGrants(target, options.entities)));
+      held = await heldGrants(target, options.entities);
+      pending.push(...(await pendingGrants(target, options.entities, held)));
     } catch (err) {
       const why = classifyClickHouseFailure(err);
       for (const name of options.entityNames) {
@@ -281,12 +328,15 @@ export async function observeResourcesDeep(
       continue;
     }
     if (entity.entityType === CLICKHOUSE_ENTITY_TYPES.grant) {
-      if (unobserved[name]) continue;
-      unobserved[name] = {
-        type: entity.entityType,
-        reason: "unsupported-kind",
-        detail: "a grant is compared as part of its grantees' grants: what an apply would grant or revoke is listed as pending (SQLCH273, SQLCH274)",
-      };
+      if (unobserved[name] || !held) continue;
+      const ddl = String(entity.props.ddl ?? "");
+      try {
+        const properties = liveGrantTree(ddl, held, target.defaultDatabase);
+        // A grantee the server does not have: the thin diff reports the declaration missing.
+        if (properties) resources[name] = { type: entity.entityType, physicalId: `grants ${[...new Set(declaredGrantAtoms(ddl).map((a) => a.grantee))].join(", ")}`, properties };
+      } catch (err) {
+        unobserved[name] = { type: entity.entityType, reason: "read-failed", detail: `the grant does not parse: ${(err as Error).message}` };
+      }
       continue;
     }
     const props = entity.props;
@@ -331,37 +381,58 @@ export async function observeResourcesDeep(
   return deepObservation(resources, unobserved, pending);
 }
 
+const grantDeclarations = (entities: ReadonlyMap<string, { entityType: string; props: Record<string, unknown> }>) =>
+  grantsByGrantee([...entities].map(([name, e]) => ({ export: name, type: e.entityType, ddl: String(e.props.ddl ?? "") })));
+
 /**
- * The grants an apply would give or take from each declared grantee (#3733),
- * as `chant sql plan` compares them: the declared grants against what
- * `SHOW GRANTS FOR` prints, atom by atom. One change per grantee, its
- * REVOKEs before its GRANTs as the applier sends them, with the grant
- * declarations behind it. A grantee the server does not hold yet is given
- * every declared grant.
+ * What the server holds for each declared grantee, as `SHOW GRANTS FOR`
+ * prints it, folded into atoms. A grantee the server does not have is left
+ * out.
+ */
+export async function heldGrants(target: ClickHouseTarget, entities: ReadonlyMap<string, { entityType: string; props: Record<string, unknown> }>): Promise<Map<string, GrantAtom[]>> {
+  const declared = grantDeclarations(entities);
+  if (declared.length === 0) return new Map();
+  const live = await readLiveAccess(target, declared.map((g) => ({ kind: "grants", name: g.grantee })));
+  return new Map(
+    live
+      .filter((o) => o.type === CLICKHOUSE_ENTITY_TYPES.grant)
+      .map((o) => [o.name, Object.values(grantsObject(o.statement, o.name, target.defaultDatabase).access ?? {}).map((json) => JSON.parse(json) as GrantAtom)]),
+  );
+}
+
+/**
+ * The grantees holding a privilege or role no declaration gives them
+ * (#3733), as `chant sql plan` compares them: the declared grants against
+ * what `SHOW GRANTS FOR` prints, atom by atom. One change per such grantee,
+ * every statement an apply would send it, its REVOKEs before its GRANTs as
+ * the applier sends them, with the grant declarations behind it. A grantee
+ * that only lacks declared grants has nothing pending: each declaration
+ * reports those as `absent` drift of its own (#4582). A grantee the server
+ * does not have is the thin diff's missing.
  */
 export async function pendingGrants(
   target: ClickHouseTarget,
   entities: ReadonlyMap<string, { entityType: string; props: Record<string, unknown> }>,
+  held?: ReadonlyMap<string, readonly GrantAtom[]>,
 ): Promise<DeepPendingChange[]> {
-  const declared = grantsByGrantee([...entities].map(([name, e]) => ({ export: name, type: e.entityType, ddl: String(e.props.ddl ?? "") })));
+  const declared = grantDeclarations(entities);
   if (declared.length === 0) return [];
-  const live = await readLiveAccess(target, declared.map((g) => ({ kind: "grants", name: g.grantee })));
-  const held = new Map(live.filter((o) => o.type === CLICKHOUSE_ENTITY_TYPES.grant).map((o) => [o.name, grantsObject(o.statement, o.name, target.defaultDatabase).access ?? {}]));
+  const live = held ?? (await heldGrants(target, entities));
   const atom = (json: string) => JSON.parse(json) as GrantAtom;
   const out: DeepPendingChange[] = [];
   for (const g of declared) {
+    const atoms = live.get(g.grantee);
+    if (!atoms) continue;
+    const have = Object.fromEntries(atoms.map((a) => [atomKey(a), JSON.stringify(a)]));
     const want = grantsObject(g.ddl, g.grantee, target.defaultDatabase).access ?? {};
-    const have = held.get(g.grantee) ?? {};
-    const statements = [
-      ...Object.keys(have)
-        .filter((k) => !(k in want))
-        .map((k) => revokeStatement(atom(have[k]!), g.grantee)),
-      ...Object.keys(want)
-        .filter((k) => !(k in have))
-        .map((k) => grantStatement(atom(want[k]!), g.grantee)),
-    ];
-    if (statements.length === 0) continue;
-    out.push({ subject: `grants ${g.grantee}`, change: statements.join("; "), entities: [...g.exports].sort() });
+    const revokes = Object.keys(have)
+      .filter((k) => !(k in want))
+      .map((k) => revokeStatement(atom(have[k]!), g.grantee));
+    if (revokes.length === 0) continue;
+    const grants = Object.keys(want)
+      .filter((k) => !(k in have))
+      .map((k) => grantStatement(atom(want[k]!), g.grantee));
+    out.push({ subject: `grants ${g.grantee}`, change: [...revokes, ...grants].join("; "), entities: [...g.exports].sort() });
   }
   return out;
 }

package/src/exit-codes.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, test } from "vitest";
+import { CHANT_EXIT } from "@intentius/chant/exit-codes";
+import { sqlExitOf, sqlPlanMoved, YODEL_LEGACY_EXIT, yodelExitOf } from "./exit-codes";
+
+describe("SQL engine outcomes on chant's table (#4570)", () => {
+  test("a moved wave plan and an approval of another digest are moved", () => {
+    expect(sqlExitOf("plan-moved")).toBe(CHANT_EXIT.moved);
+    expect(sqlExitOf("approval-moved")).toBe(CHANT_EXIT.moved);
+    expect(sqlPlanMoved("plan-moved")).toBe(true);
+    expect(sqlPlanMoved("checksum-mismatch")).toBe(false);
+  });
+
+  test("denial, lock, promotion and drift each have their own row", () => {
+    expect(sqlExitOf("policy-denied")).toBe(CHANT_EXIT.denied);
+    expect(sqlExitOf("lock-held")).toBe(CHANT_EXIT.held);
+    expect(sqlExitOf("promotion-unmet")).toBe(CHANT_EXIT.waiting);
+    expect(sqlExitOf("pending")).toBe(CHANT_EXIT.waiting);
+    expect(sqlExitOf("drift")).toBe(CHANT_EXIT.drift);
+    expect(sqlExitOf("stood-down")).toBe(CHANT_EXIT.superseded);
+  });
+
+  test("a refusal no approval fixes is failed, lint errors included", () => {
+    for (const o of ["checksum-mismatch", "fork", "out-of-order", "directory", "shared-identity", "reader-write", "lint-errors"] as const) {
+      expect(sqlExitOf(o)).toBe(CHANT_EXIT.failed);
+    }
+  });
+});
+
+describe("yodel exit statuses (#4570)", () => {
+  test("a yodel on chant's table passes through", () => {
+    for (const code of Object.values(CHANT_EXIT)) expect(yodelExitOf({ code })).toBe(code);
+    expect(yodelExitOf({ code: 99 })).toBe(CHANT_EXIT.failed);
+    expect(yodelExitOf({ code: null })).toBe(CHANT_EXIT.failed);
+  });
+
+  test("a legacy yodel's codes are read by meaning", () => {
+    const legacy = true;
+    expect(yodelExitOf({ code: YODEL_LEGACY_EXIT.needsOp, command: "drift", legacy })).toBe(CHANT_EXIT.drift);
+    expect(yodelExitOf({ code: YODEL_LEGACY_EXIT.needsOp, command: "apply", legacy })).toBe(CHANT_EXIT.waiting);
+    expect(yodelExitOf({ code: YODEL_LEGACY_EXIT.outstanding, command: "lint", legacy })).toBe(CHANT_EXIT.failed);
+    expect(yodelExitOf({ code: YODEL_LEGACY_EXIT.outstanding, command: "status", legacy })).toBe(CHANT_EXIT.waiting);
+    expect(yodelExitOf({ code: YODEL_LEGACY_EXIT.refused, command: "apply", legacy })).toBe(CHANT_EXIT.failed);
+    expect(yodelExitOf({ code: YODEL_LEGACY_EXIT.locked, legacy })).toBe(CHANT_EXIT.held);
+    expect(yodelExitOf({ code: 0, legacy })).toBe(CHANT_EXIT.done);
+  });
+});

package/src/exit-codes.ts

@@ -0,0 +1,140 @@
+/**
+ * SQL engine outcomes mapped onto chant's exit-code table (#4553, `CHANT_EXIT`
+ * in `@intentius/chant/exit-codes`), for the versioned migration engine chant
+ * runs through the sql capability (sql-yodeler, `yodel`).
+ *
+ * sql-yodeler from sql-yodeler#288 on exits by chant's table, so its codes
+ * pass through. An older yodel has its own table, where 3 means anything
+ * outstanding (lint errors included) and 4 every refusal; {@link yodelExitOf}
+ * reads one of those with the command it came from.
+ *
+ * | Engine outcome | Table |
+ * |---|---|
+ * | applied, nothing pending, stood down at plan time | `done` |
+ * | a wave plan that moved (`WavePlanMoved`), an approval of another digest | `moved` |
+ * | a policy rule denies the plan and no override counts | `denied` |
+ * | another apply holds the history lock | `held` |
+ * | a newer commit on the branch applies the same environment (stand-down) | `superseded` |
+ * | an apply stopped at its gate, pending migrations under `yodel status`, a migration the required environment has not applied, a change that needs an Op the engine does not run, a manual step | `waiting` |
+ * | drift found by `yodel drift` | `drift` |
+ * | a checksum mismatch, a fork, an out-of-order migration, an applied migration gone from the directory, reader and writer one identity, a write run with the reader, lint errors | `failed` |
+ */
+import { CHANT_EXIT, type ChantExitCode } from "@intentius/chant/exit-codes";
+
+/** An outcome of the versioned migration engine, by name. */
+export type SqlEngineOutcome =
+  | "applied"
+  | "unchanged"
+  | "plan-moved"
+  | "approval-moved"
+  | "policy-denied"
+  | "lock-held"
+  | "stood-down"
+  | "gated"
+  | "pending"
+  | "promotion-unmet"
+  | "needs-op"
+  | "manual-step"
+  | "drift"
+  | "checksum-mismatch"
+  | "fork"
+  | "out-of-order"
+  | "directory"
+  | "shared-identity"
+  | "reader-write"
+  | "lint-errors"
+  | "failed";
+
+const OUTCOME_EXIT: Record<SqlEngineOutcome, ChantExitCode> = {
+  applied: CHANT_EXIT.done,
+  unchanged: CHANT_EXIT.done,
+  "plan-moved": CHANT_EXIT.moved,
+  "approval-moved": CHANT_EXIT.moved,
+  "policy-denied": CHANT_EXIT.denied,
+  "lock-held": CHANT_EXIT.held,
+  "stood-down": CHANT_EXIT.superseded,
+  gated: CHANT_EXIT.waiting,
+  pending: CHANT_EXIT.waiting,
+  "promotion-unmet": CHANT_EXIT.waiting,
+  "needs-op": CHANT_EXIT.waiting,
+  "manual-step": CHANT_EXIT.waiting,
+  drift: CHANT_EXIT.drift,
+  "checksum-mismatch": CHANT_EXIT.failed,
+  fork: CHANT_EXIT.failed,
+  "out-of-order": CHANT_EXIT.failed,
+  directory: CHANT_EXIT.failed,
+  "shared-identity": CHANT_EXIT.failed,
+  "reader-write": CHANT_EXIT.failed,
+  "lint-errors": CHANT_EXIT.failed,
+  failed: CHANT_EXIT.failed,
+};
+
+/**
+ * The table's code for an engine outcome. A refusal no approval fixes is
+ * `failed`; one a person can clear (a gate, an unmet promotion) is `waiting`.
+ */
+export function sqlExitOf(outcome: SqlEngineOutcome): ChantExitCode {
+  return OUTCOME_EXIT[outcome];
+}
+
+/** Whether `outcome` is a plan that moved since its approval. */
+export function sqlPlanMoved(outcome: SqlEngineOutcome): boolean {
+  return sqlExitOf(outcome) === CHANT_EXIT.moved;
+}
+
+/** yodel's own exit table before sql-yodeler#288 (its `src/exit.ts` up to 0.10). */
+export const YODEL_LEGACY_EXIT = {
+  ok: 0,
+  error: 1,
+  /** Something yodel will not do itself; drift, for `yodel drift`. */
+  needsOp: 2,
+  /** Something outstanding: a gate, pending migrations, lint errors. */
+  outstanding: 3,
+  /** Refused, nothing done: every refusal, policy denials and unmet promotions included. */
+  refused: 4,
+  locked: 5,
+} as const;
+
+/** A `yodel` exit status and the command it came from. */
+export interface YodelExitSource {
+  code: number | null | undefined;
+  /** The yodel verb (`apply`, `status`, `lint`, `drift`, ...). */
+  command?: string;
+  /** The yodel predates sql-yodeler#288 and exits by {@link YODEL_LEGACY_EXIT}. */
+  legacy?: boolean;
+}
+
+/**
+ * The table's code for a `yodel` exit status. A yodel on chant's table passes
+ * through (a code outside the table is `failed`). A legacy yodel's codes are
+ * read by meaning:
+ *
+ * | legacy yodel | Table |
+ * |---|---|
+ * | 0 | `done` |
+ * | 2 from `yodel drift` | `drift` |
+ * | 2 from any other verb, a change that needs an Op or a manual step | `waiting` |
+ * | 3 from `yodel lint` | `failed` (sql-yodeler#285 ruling C) |
+ * | 3 from any other verb | `waiting` |
+ * | 4, any refusal | `failed`: the legacy code does not tell a policy denial or an unmet promotion apart |
+ * | 5 | `held` |
+ * | 1, anything else | `failed` |
+ */
+export function yodelExitOf(source: YodelExitSource): ChantExitCode {
+  const { code, command, legacy } = source;
+  if (code === 0) return CHANT_EXIT.done;
+  if (!legacy) {
+    for (const value of Object.values(CHANT_EXIT)) if (value === code) return value;
+    return CHANT_EXIT.failed;
+  }
+  switch (code) {
+    case YODEL_LEGACY_EXIT.needsOp:
+      return command === "drift" ? CHANT_EXIT.drift : CHANT_EXIT.waiting;
+    case YODEL_LEGACY_EXIT.outstanding:
+      return command === "lint" ? CHANT_EXIT.failed : CHANT_EXIT.waiting;
+    case YODEL_LEGACY_EXIT.locked:
+      return CHANT_EXIT.held;
+    default:
+      return CHANT_EXIT.failed;
+  }
+}

package/src/index.ts

@@ -47,3 +47,31 @@ export {
   type SqlFileOptions,
   type SqlFileSource,
 } from "./sql-files";
+
+// SQL engine and yodel outcomes on chant's exit-code table (#4570); also at
+// `@intentius/chant-lexicon-sql/exit-codes`.
+export { sqlExitOf, sqlPlanMoved, yodelExitOf, YODEL_LEGACY_EXIT, type SqlEngineOutcome, type YodelExitSource } from "./exit-codes";
+
+// The `sql-migrate` and `sql-apply` capabilities (#4569), contributed to core's
+// capability-plugin seam: core loads `sqlCapabilityPlugin` when a project's
+// chant.config lists this lexicon, so op waves and pr-plan plan and apply a
+// SQL member through chant. sql-yodeler's engine runs by a fixed argv list
+// (`YODEL_COMMANDS`).
+export {
+  sqlCapabilityPlugin,
+  sqlMigrateCapability,
+  sqlApplyCapability,
+  createSqlMigrateCapability,
+  createSqlApplyCapability,
+  SqlPlanMovedError,
+  YodelRunError,
+  SQL_VERB_FAMILIES,
+  type SqlMigrateStepInput,
+  type SqlMigrateStepOutput,
+  type SqlMigrateArtifact,
+  type SqlApplyStepInput,
+  type SqlApplyStepOutput,
+} from "./capability-plugin";
+// The lock grain of a SQL member (#4571): target, with resource refused by name.
+export { sqlDefaultLockGrain, sqlLockGrainRefusal, type SqlLockGrainKind } from "./lock-grain";
+export { YODEL_COMMANDS, YODEL_OPTIONAL_FLAGS, runAllowedYodel, allowedYodelArgv, type YodelRunner, type YodelRun } from "./yodel-run";

package/src/lock-grain.test.ts

@@ -0,0 +1,57 @@
+/**
+ * The lock grain of a SQL member (#4571): both kinds default to `target`,
+ * refuse `resource` naming the engine, and leave `repo` alone. Resolved
+ * through core's `resolvePlannedLock`, as pr-apply and op waves resolve it.
+ */
+import { describe, expect, test } from "vitest";
+import { LockGrainRefusedError, resolvePlannedLock } from "@intentius/chant/lifecycle/lock-rows";
+import { createSqlApplyCapability, createSqlMigrateCapability } from "./capability-plugin";
+import { sqlDefaultLockGrain, sqlLockGrainRefusal } from "./lock-grain";
+
+const migrate = createSqlMigrateCapability({ run: async () => ({ code: 0, stdout: "", stderr: "" }) });
+const apply = createSqlApplyCapability({
+  plan: async (_input, dialect) => ({ dialect, changes: [], refused: [], holes: [], problems: [] }),
+  apply: async () => ({ applied: [], pruned: [], notAttempted: [] }),
+});
+const migrateInput = { environment: "prod", spec: "yodel-waves.json" };
+const applyInput = { environment: "prod", build: "dist/schema.json" };
+const plan = { member: "prod" };
+
+describe("the SQL lock grain (#4571)", () => {
+  test("the default is target, the environment's history", () => {
+    expect(sqlDefaultLockGrain()).toBe("target");
+    expect(migrate.defaultLockGrain?.(migrateInput)).toBe("target");
+    expect(apply.defaultLockGrain?.(applyInput)).toBe("target");
+  });
+
+  test("an undeclared member resolves to target from the lexicon, with no rows", async () => {
+    for (const [cap, input] of [
+      [migrate, migrateInput],
+      [apply, applyInput],
+    ] as const) {
+      const lock = await resolvePlannedLock(cap, input, plan, undefined);
+      expect(lock).toEqual({ grain: "target", source: "lexicon", rows: [] });
+    }
+  });
+
+  test("resource is refused by name, for both kinds", async () => {
+    expect(sqlLockGrainRefusal("sql-migrate", "resource")).toMatch(/SQL Yodeler.*KeeperMap.*advisory lock/);
+    expect(sqlLockGrainRefusal("sql-apply", "resource")).toMatch(/creation order/);
+    const refused = await resolvePlannedLock(migrate, migrateInput, plan, "resource").catch((e: unknown) => e);
+    expect(refused).toBeInstanceOf(LockGrainRefusedError);
+    expect((refused as Error).message).toMatch(/^"prod": the resource lock grain is refused: SQL Yodeler/);
+    await expect(resolvePlannedLock(apply, applyInput, plan, "resource")).rejects.toThrow(/the resource lock grain is refused: the sql lexicon's applier/);
+  });
+
+  test("target and repo, declared, are taken as declared", async () => {
+    expect(sqlLockGrainRefusal("sql-migrate", "target")).toBeUndefined();
+    expect(sqlLockGrainRefusal("sql-apply", "repo")).toBeUndefined();
+    expect(await resolvePlannedLock(migrate, migrateInput, plan, "repo")).toEqual({ grain: "repo", source: "declared", rows: [] });
+    expect(await resolvePlannedLock(apply, applyInput, plan, "target")).toEqual({ grain: "target", source: "declared", rows: [] });
+  });
+
+  test("neither kind names rows", () => {
+    expect(migrate.lockRows).toBeUndefined();
+    expect(apply.lockRows).toBeUndefined();
+  });
+});

package/src/lock-grain.ts

@@ -0,0 +1,37 @@
+/**
+ * The lock grain of a SQL member (#4571, on #4552's hooks).
+ *
+ * A SQL member's grain is `target`: one environment's history. Two applies
+ * of one environment are kept apart by the environment's own lock, which
+ * sql-yodeler takes for every apply (a KeeperMap row on ClickHouse, a
+ * session advisory lock on Postgres), and by chant's target lock on the
+ * environment. `sql-apply` sends a whole build in creation order, so it
+ * holds the environment too.
+ *
+ * `resource` is refused by name, as it is on Terraform and stock Pulumi: a
+ * migration chain applies in order, and a row per object would let two
+ * applies of one chain interleave. Neither kind answers `lockRows`. `repo`
+ * is the pipeline's, and any member may take it.
+ *
+ * sql-yodeler's rendered apply jobs set `APPLY_LOCK` (`YODEL_LOCK_WAIT`,
+ * `YODEL_STAND_DOWN`, src/ci/render.ts:323) for the engine's lock wait and
+ * its stand-down; dropping it for these hooks is sql-yodeler#293's.
+ */
+import type { LockGrain } from "@intentius/chant/lifecycle/lock-rows";
+
+/** The capability kinds this lexicon gives a grain to. */
+export type SqlLockGrainKind = "sql-migrate" | "sql-apply";
+
+/** The grain a SQL member takes when `ci.lockGrain` sets none: always `target`. */
+export function sqlDefaultLockGrain(): LockGrain {
+  return "target";
+}
+
+/** Why a SQL member cannot take `grain`, naming the engine; undefined for `target` and `repo`. */
+export function sqlLockGrainRefusal(kind: SqlLockGrainKind, grain: LockGrain): string | undefined {
+  if (grain !== "resource") return undefined;
+  if (kind === "sql-migrate") {
+    return "SQL Yodeler applies an environment's migrations in chain order under the environment's own lock (a KeeperMap row on ClickHouse, a session advisory lock on Postgres), so nothing in it is per resource (ci.lockGrain: target)";
+  }
+  return "the sql lexicon's applier sends a whole build in creation order, since its objects depend on each other, so nothing in it is per resource (ci.lockGrain: target)";
+}

package/src/plugin.ts

@@ -33,6 +33,7 @@ import { looksLikePostgres } from "./migrate/from-postgres/detect";
 import { sqlWorkspaceOutputs } from "./workspace-outputs";
 import { CDC_TEMPLATE, DEFAULT_TEMPLATE, EVENTS_TEMPLATE, POSTGRES_EVENTS_TEMPLATE, POSTGRES_TEMPLATE, POSTGRES_TENANT_TEMPLATE } from "./init-templates";
 import { compositeCatalog } from "./composites/catalog";
+import { sqlCiServices, sqlCiSetup } from "./ci-setup";
 
 export const sqlPlugin: LexiconPlugin = {
   name: "sql",
@@ -45,6 +46,14 @@ export const sqlPlugin: LexiconPlugin = {
   /** chant's marker is a trailer on the object's comment (#3208, ./clickhouse/ownership.ts). */
   ownershipChannel: SQL_OWNERSHIP_CHANNEL,
 
+  // #4572: the setup lines for the pull request pipeline's default image, and the replay server per dialect.
+  ciSetup(ctx: { dir: string }): string[] {
+    return sqlCiSetup(ctx);
+  },
+  ciServices(ctx: { dir: string }) {
+    return sqlCiServices(ctx);
+  },
+
   async generate(options?: { verbose?: boolean }): Promise<void> {
     const { generate, writeGeneratedFiles } = await import("./codegen/generate");
     writeGeneratedFiles(await generate(options));

package/src/testdata/fake-yodel.mjs

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+// A fake `yodel` for the sql-migrate tests (#4569). It answers the three
+// commands chant runs, writes the files sql-yodeler would, and appends each
+// call (argv, and whether the writer was in its environment) to
+// $FAKE_YODEL_LOG. $FAKE_YODEL_APPLY_EXIT sets the apply's exit status, and
+// $FAKE_YODEL_WAVE_DIGEST the wave plan's digest.
+import { appendFileSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+
+const args = process.argv.slice(2);
+const at = (flag) => args[args.indexOf(flag) + 1];
+const write = (file, doc) => {
+  const path = resolve(file);
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(doc, null, 2)}\n`);
+};
+
+if (process.env.FAKE_YODEL_LOG) {
+  appendFileSync(
+    process.env.FAKE_YODEL_LOG,
+    `${JSON.stringify({ args, role: process.env.YODEL_ROLE ?? null, writer: process.env.DEV_POSTGRES_WRITER_PASSWORD ?? null })}\n`,
+  );
+}
+
+const env = args[1];
+if (args[0] === "plan") {
+  write(at("--part"), {
+    member: { member: "app", lexicon: "sql", planner: "sql", scope: env, status: "planned", planDigest: "jcs1-sha256:migrations", holes: [] },
+    entries: [
+      { member: "app", lexicon: "sql", planner: "sql", address: "app.users", type: "Postgres::Table", action: "update", disruption: "rolling", scope: env, attributes: [{ path: "columns.email", after: "text" }] },
+      { member: "app", lexicon: "sql", planner: "sql", address: "app.audit", type: "Postgres::Table", action: "create", scope: env, attributes: [] },
+    ],
+  });
+  process.exit(0);
+}
+if (args[0] === "apply" && args[2] === "--wave-plan") {
+  write(at("--wave-plan"), {
+    planDigest: process.env.FAKE_YODEL_WAVE_DIGEST ?? "jcs1-sha256:wave",
+    destructive: true,
+    empty: false,
+    environment: env,
+    migrations: "jcs1-sha256:migrations",
+    gate: "on-destructive",
+    base: "0".repeat(40),
+    pending: ["0002_users_email"],
+    destructiveSteps: [{ migration: "0002_users_email", step: 0, what: "ALTER TABLE app.users", why: "pg-rewrite, pg-lock" }],
+    requires: [],
+  });
+  process.exit(0);
+}
+if (args[0] === "apply" && args[2] === "--wave-apply") {
+  const code = Number(process.env.FAKE_YODEL_APPLY_EXIT ?? "0");
+  if (code === 0) process.stdout.write("Applied: 0002_users_email\n");
+  else process.stderr.write(`refused: ${env}'s wave plan moved since the wave was decided; nothing was applied. Run the wave again.\n`);
+  process.exit(code);
+}
+process.stderr.write(`fake yodel: no answer for ${args.join(" ")}\n`);
+process.exit(1);