@intentius/chant 0.78.0 → 0.80.0

package/src/cli/handlers/operator.test.ts

@@ -17,6 +17,7 @@ const readGateLedgerMock = vi.fn();
 const readRunLedgerMock = vi.fn();
 const pushLifecycleMock = vi.fn();
 const requireLifecycleLedgerMock = vi.fn();
+const loadGatePolicyEvaluatorMock = vi.fn();
 
 vi.mock("../../op/operator", async () => {
   const actual = await vi.importActual<typeof import("../../op/operator")>("../../op/operator");
@@ -69,6 +70,11 @@ vi.mock("../../lifecycle/git", async () => {
   };
 });
 
+vi.mock("../../op/gate-approval", async () => {
+  const actual = await vi.importActual<typeof import("../../op/gate-approval")>("../../op/gate-approval");
+  return { ...actual, loadGatePolicyEvaluator: (...args: unknown[]) => loadGatePolicyEvaluatorMock(...args) };
+});
+
 // Imported after the mocks above are registered.
 const { runOperator, runOperatorStatus, runOperatorLog, runApprove } = await import("./operator");
 
@@ -979,3 +985,82 @@ describe("runApprove — a push that does not land is reported (#2309 review)",
     errSpy.mockRestore();
   });
 });
+
+describe("runApprove — a gate with an approval policy (#2508)", () => {
+  const TEXT = "permit (principal is Chant::Agent, action, resource);\n";
+  const POLICY = { kind: "gate-policy" as const, lexicon: "cedar", name: "ship", version: "sha256:v1", text: TEXT };
+
+  function seedPolicyGate(mode: "log-only" | "enforce"): void {
+    readGateLedgerMock.mockResolvedValue({
+      resolutions: [],
+      pending: [{
+        version: 1, kind: "pending", op: "fountain-apply", gate: "rollout-gate",
+        timestamp: "2026-01-01T00:00:00.000Z", expiresAt: "2099-01-01T00:00:00.000Z", planDigest: PLAN_A,
+        approval: { quorum: { count: 2, roles: ["maintainer"] }, policy: POLICY, mode, context: { risk: "low" } },
+      }],
+      malformed: 0,
+    });
+    appendGateResolutionMock.mockImplementation(async (input: Record<string, unknown>) => ({
+      commit: "sha",
+      record: { version: 1, ...input },
+    }));
+  }
+
+  test("evaluates the policy for an agent's approval and records the decision next to it", async () => {
+    seedPolicyGate("enforce");
+    const evaluateGatePolicy = vi.fn().mockResolvedValue({ decision: "allow", determining: ["agent-low-risk"], errors: [] });
+    loadGatePolicyEvaluatorMock.mockResolvedValue({ evaluateGatePolicy });
+    const errSpy = vi.spyOn(console, "error").mockImplementation(() => undefined);
+
+    expect(await runApprove(ctx({ path: "fountain-apply", extraPositional: "rollout-gate", actor: "release-bot", agent: true }))).toBe(0);
+
+    expect(loadGatePolicyEvaluatorMock).toHaveBeenCalledWith("cedar");
+    expect(evaluateGatePolicy).toHaveBeenCalledWith(POLICY, {
+      principal: { kind: "agent", name: "release-bot", roles: [] },
+      action: "PassGate",
+      resource: { op: "fountain-apply", gate: "rollout-gate" },
+      context: { risk: "low", planDigest: PLAN_A },
+    });
+    expect(appendGateResolutionMock).toHaveBeenCalledWith(expect.objectContaining({
+      approver: { kind: "agent" },
+      policyDecision: {
+        policy: "ship", version: "sha256:v1", mode: "enforce",
+        decision: "allow", determining: ["agent-low-risk"], errors: [],
+      },
+    }));
+    const out = errSpy.mock.calls.map((c) => String(c[0])).join("\n");
+    expect(out).toContain("In enforce mode this permit passes the gate on its own");
+    expect(out).toContain("An agent's approval does not count toward the quorum");
+    errSpy.mockRestore();
+  });
+
+  test("records a human's roles, and reports quorum progress with a log-only decision", async () => {
+    seedPolicyGate("log-only");
+    loadGatePolicyEvaluatorMock.mockResolvedValue({
+      evaluateGatePolicy: async () => ({ decision: "deny", determining: [], errors: [] }),
+    });
+    const errSpy = vi.spyOn(console, "error").mockImplementation(() => undefined);
+
+    expect(await runApprove(ctx({ path: "fountain-apply", extraPositional: "rollout-gate", actor: "alex", roles: ["maintainer"] }))).toBe(0);
+
+    expect(appendGateResolutionMock).toHaveBeenCalledWith(expect.objectContaining({
+      approver: { kind: "human", roles: ["maintainer"] },
+    }));
+    const out = errSpy.mock.calls.map((c) => String(c[0])).join("\n");
+    expect(out).toContain("log-only mode, so the decision is recorded and does not change the outcome");
+    expect(out).toContain("Quorum: 1 of 2 human approval(s) with role maintainer for this plan (alex)");
+    errSpy.mockRestore();
+  });
+
+  test("refuses, and writes nothing, when the policy cannot be evaluated", async () => {
+    seedPolicyGate("enforce");
+    loadGatePolicyEvaluatorMock.mockRejectedValue(new Error("@intentius/chant-lexicon-cedar/gate-policy could not be loaded"));
+    const errSpy = vi.spyOn(console, "error").mockImplementation(() => undefined);
+
+    expect(await runApprove(ctx({ path: "fountain-apply", extraPositional: "rollout-gate", actor: "alex" }))).toBe(1);
+
+    expect(appendGateResolutionMock).not.toHaveBeenCalled();
+    expect(errSpy.mock.calls.map((c) => String(c[0])).join("\n")).toContain('declares policy "ship", which could not be evaluated');
+    errSpy.mockRestore();
+  });
+});

package/src/cli/handlers/operator.ts

@@ -6,6 +6,7 @@
  * `run.ts`'s `runOpLocal` shape (SIGINT → AbortController, `loadActivities`/
  * `loadProfiles` from the project's configured lexicons).
  */
+import { lexiconNames } from "../../lexicon-module";
 import { loadChantConfig } from "../../config";
 import { build } from "../../build";
 import { isResourceDeclarable } from "../../declarable";
@@ -38,6 +39,11 @@ import {
   resolveApprovalUrl, isApprovalUrl,
 } from "../../lifecycle/gate-ledger";
 import { isPlanDigest } from "../../lifecycle/plan-digest";
+import {
+  gatePolicyRequest, loadGatePolicyEvaluator,
+  type GateApprover, type GatePolicyDecision, type GatePolicyEvaluator, type ResolvedGateApproval,
+} from "../../op/gate-approval";
+import { approverOf, tallyGateApprovals } from "../../op/gate";
 import { FAN_OUT_GATE_OP } from "../../op/gate-name";
 import { pushLifecycle, requireLifecycleLedger } from "../../lifecycle/git";
 import { formatError, formatWarning, formatSuccess, formatBold, formatInfo } from "../format";
@@ -47,7 +53,7 @@ import type { CommandContext } from "../registry";
 async function loadOperatorActivities() {
   let lexicons: string[] = [];
   try {
-    lexicons = (await loadChantConfig(process.cwd())).config.lexicons ?? [];
+    lexicons = lexiconNames((await loadChantConfig(process.cwd())).config.lexicons ?? []);
   } catch {
     // No/invalid chant.config — fall back to base activities only.
   }
@@ -698,6 +704,8 @@ export async function runApprove(ctx: CommandContext): Promise<number> {
     url: ctx.args.url,
     plan: ctx.args.plan,
     allowSameOrigin: ctx.args.allowSameOrigin,
+    ...(ctx.args.roles ? { roles: ctx.args.roles } : {}),
+    ...(ctx.args.agent ? { agent: true } : {}),
   });
   if (!outcome.ok) return 1;
 
@@ -739,6 +747,15 @@ export interface GateApprovalOptions {
    * stays one command: run, read what it planned, approve it.
    */
   plan?: string;
+  /** `--role` (#2508) — roles the approver claims. */
+  roles?: string[];
+  /**
+   * `--agent` (#2508) — record this as an agent's approval. On a
+   * model-authored channel it is one whether or not this is set.
+   */
+  agent?: boolean;
+  /** Replaces the lexicon evaluator a gate policy is loaded from. For tests. */
+  evaluator?: GatePolicyEvaluator;
 }
 
 export type GateApprovalOutcome =
@@ -841,7 +858,8 @@ export async function recordGateApproval(
   // resolved over the same one has no second party in it. Refused by default,
   // the way #2300 refuses a plan nobody approved.
   const origin = opts.origin ?? currentGateOrigin();
-  const standingForOrigin = latestPendingGate((await readGateLedger(opName)).pending, gate);
+  const ledger = await readGateLedger(opName);
+  const standingForOrigin = latestPendingGate(ledger.pending, gate);
   const refusal = sameOriginRefusal(standingForOrigin?.origin, origin);
   if (refusal && !opts.allowSameOrigin) {
     console.error(formatError({
@@ -862,11 +880,58 @@ export async function recordGateApproval(
       ? UNATTESTED_APPROVER
       : process.env.GITHUB_ACTOR ?? process.env.GITLAB_USER_LOGIN ?? process.env.USER ?? "unknown");
 
+  // #2508: who this is, as the gate's quorum and policy read it. A model on
+  // MCP or ACP is an agent whatever it claims, the same reasoning that gives
+  // it `UNATTESTED_APPROVER` for a name.
+  const approver: GateApprover = {
+    kind: opts.agent || isModelAuthored(origin) ? "agent" : "human",
+    ...(opts.roles && opts.roles.length > 0 ? { roles: [...new Set(opts.roles)] } : {}),
+  };
+
+  // #2508: a gate with a policy has it evaluated for this approval now, while
+  // the approver is known, against the context the gated run recorded. The
+  // decision is written next to the approval, so a pass can be traced to the
+  // rule that allowed it.
+  const approval = standingForOrigin?.approval;
+  let policyDecision: GatePolicyDecision | undefined;
+  if (approval?.policy) {
+    try {
+      const evaluator = opts.evaluator ?? (await loadGatePolicyEvaluator(approval.policy.lexicon));
+      const answer = await evaluator.evaluateGatePolicy(
+        approval.policy,
+        gatePolicyRequest({
+          op: opName,
+          gate,
+          resolvedBy,
+          approver,
+          ...(planDigest !== undefined ? { planDigest } : {}),
+          ...(approval.context ? { context: approval.context } : {}),
+        }),
+      );
+      policyDecision = {
+        policy: approval.policy.name,
+        version: approval.policy.version,
+        mode: approval.mode,
+        decision: answer.decision,
+        determining: answer.determining,
+        errors: answer.errors,
+      };
+    } catch (err) {
+      console.error(formatError({
+        message: `Gate "${gate}" on "${opName}" declares policy "${approval.policy.name}", which could not be evaluated: ${err instanceof Error ? err.message : String(err)}`,
+        hint: `Install the ${approval.policy.lexicon} lexicon in this project, or approve from a checkout that has it.`,
+      }));
+      return { ok: false };
+    }
+  }
+
   const { record } = await appendGateResolution({
     op: opName,
     gate,
     resolvedBy,
     timestamp: new Date().toISOString(),
+    approver,
+    ...(policyDecision ? { policyDecision } : {}),
     ...(opts.note ? { note: opts.note } : {}),
     ...(url ? { url } : {}),
     ...(planDigest !== undefined ? { planDigest } : {}),
@@ -889,5 +954,56 @@ export async function recordGateApproval(
         "differs refuses rather than applying it.",
     ));
   }
+  if (approval) {
+    for (const line of describeApprovalProgress(approval, record, ledger.resolutions, standingForOrigin)) {
+      console.error(formatInfo(line));
+    }
+  }
   return { ok: true, record };
 }
+
+/**
+ * What a just-recorded approval did to a gate with an `approval` block
+ * (#2508): the policy's decision and whether it binds, then the quorum count
+ * for this plan. The run decides the gate from the ledger; these lines only
+ * say what it will find.
+ */
+export function describeApprovalProgress(
+  approval: ResolvedGateApproval,
+  record: GateResolutionRecord,
+  prior: GateResolutionRecord[],
+  standing: PendingGateRecord | undefined,
+): string[] {
+  const lines: string[] = [];
+  const decision = record.policyDecision;
+  if (decision) {
+    const rules = decision.determining.length > 0 ? ` (${decision.determining.join(", ")})` : "";
+    const binds =
+      approval.mode === "enforce"
+        ? decision.decision === "allow"
+          ? "In enforce mode this permit passes the gate on its own."
+          : "In enforce mode only a permit passes the gate on its own, so this approval counts only toward the quorum."
+        : "The gate is in log-only mode, so the decision is recorded and does not change the outcome.";
+    lines.push(`Policy "${decision.policy}" ${decision.version}: ${decision.decision}${rules}. ${binds}`);
+    for (const error of decision.errors) lines.push(`Policy evaluation error: ${error}`);
+  }
+
+  const tally = tallyGateApprovals(
+    [...prior, record],
+    record.gate,
+    standing?.timestamp ?? new Date(0).toISOString(),
+    record.planDigest,
+    approval,
+  );
+  const roles = approval.quorum?.roles ? ` with role ${approval.quorum.roles.join(" or ")}` : "";
+  const who = tally.counted.map((r) => r.resolvedBy).join(", ") || "none yet";
+  lines.push(`Quorum: ${tally.counted.length} of ${tally.need} human approval(s)${roles} for this plan (${who}).`);
+  if (!tally.counted.includes(record)) {
+    lines.push(
+      approverOf(record).kind === "agent"
+        ? "An agent's approval does not count toward the quorum."
+        : `This approval does not count toward the quorum: the approver claims none of its roles (${approval.quorum?.roles?.join(", ")}).`,
+    );
+  }
+  return lines;
+}

package/src/cli/handlers/promote.test.ts

@@ -0,0 +1,261 @@
+/**
+ * `chant components promote` (#2530), with the ledger, discovery and the
+ * capability registry replaced by fakes.
+ */
+
+import { describe, test, expect, vi, beforeEach, afterEach } from "vitest";
+import { CapabilityRegistry, type DeployContext } from "../../components/capability";
+import type { DriverComponent } from "../../components/driver";
+import type { ReleaseRecord } from "../../lifecycle/release-ledger";
+import type { ParsedArgs } from "../registry";
+
+const appendReleaseRecordMock = vi.fn();
+const readReleaseLedgerMock = vi.fn();
+const pushLifecycleMock = vi.fn();
+const resolveTargetsMock = vi.fn();
+const ran: string[] = [];
+let publishedDigest = "sha256:api";
+let failApplyFor: string | undefined;
+
+vi.mock("../../lifecycle/git", () => ({
+  getHeadCommit: async () => "abc123",
+  fetchLifecycle: async () => true,
+  pushLifecycle: (...args: unknown[]) => pushLifecycleMock(...args),
+}));
+
+vi.mock("../../lifecycle/release-ledger", async () => {
+  const actual = await vi.importActual<typeof import("../../lifecycle/release-ledger")>("../../lifecycle/release-ledger");
+  return {
+    ...actual,
+    appendReleaseRecord: (...args: unknown[]) => appendReleaseRecordMock(...args),
+    readReleaseLedger: (...args: unknown[]) => readReleaseLedgerMock(...args),
+  };
+});
+
+vi.mock("../../config", async () => {
+  const actual = await vi.importActual<typeof import("../../config")>("../../config");
+  return { ...actual, loadChantConfig: async () => ({ config: {} }) };
+});
+
+vi.mock("../../components/cli-support", () => ({
+  resolveComponentTargets: (...args: unknown[]) => resolveTargetsMock(...args),
+}));
+
+vi.mock("../../components/fan-out-support", () => ({
+  fanOutRegistry: async () => {
+    const registry = new CapabilityRegistry();
+    const step = (kind: string, output: (ctx: DeployContext) => unknown) =>
+      registry.register({ kind, async run(ctx: DeployContext) { ran.push(`${ctx.env}:${kind}`); return output(ctx); } } as never);
+    step("docker-build", () => ({ digest: "sha256:rebuilt" }));
+    step("publish-image", () => ({ digest: publishedDigest, uri: `reg/api@${publishedDigest}` }));
+    step("apply", (ctx) => {
+      if (ctx.component === failApplyFor) throw new Error("apply failed");
+      return {};
+    });
+    return registry;
+  },
+}));
+
+// Gates read an in-memory ledger rather than the git branch.
+vi.mock("../../op/gate", async () => {
+  const actual = await vi.importActual<typeof import("../../op/gate")>("../../op/gate");
+  const port = actual.memoryGateLedgerPort();
+  return { ...actual, gitGateLedgerPort: () => port };
+});
+
+// The run handler pulls in every runtime; the promote needs only its exit code.
+vi.mock("./run", () => ({ GATED_EXIT_CODE: 3 }));
+
+const { runComponentsPromote, runComponentsRollback } = await import("./promote");
+
+const api: DriverComponent = {
+  name: "api",
+  deploy: [
+    { phase: "Build", steps: [{ kind: "docker-build", context: ".", into: "api.tar" }] },
+    { phase: "Publish", steps: [{ kind: "publish-image", from: "archive:api.tar" }] },
+    { phase: "Apply", steps: [{ kind: "apply", imageRef: "@Publish.digest" }] },
+  ],
+};
+
+const staging: ReleaseRecord = {
+  version: 1,
+  component: "api",
+  env: "staging",
+  digest: "sha256:api",
+  gitSha: "abc123",
+  runId: "run-7",
+  timestamp: "2026-01-02T00:00:00.000Z",
+  actor: "ci",
+};
+
+function args(overrides: Partial<ParsedArgs>): ParsedArgs {
+  return {
+    command: "components",
+    path: "promote",
+    format: "",
+    fix: false,
+    watch: false,
+    verbose: false,
+    help: false,
+    live: false,
+    migrateFrom: "staging",
+    migrateTo: "prod",
+    actor: "bob",
+    runId: "run-9",
+    ...overrides,
+  } as ParsedArgs;
+}
+
+const ctx = (a: Partial<ParsedArgs>) => ({ args: args(a), plugins: [] }) as never;
+
+let errors: string[];
+let logs: string[];
+
+beforeEach(() => {
+  ran.length = 0;
+  publishedDigest = "sha256:api";
+  failApplyFor = undefined;
+  errors = [];
+  logs = [];
+  vi.spyOn(console, "error").mockImplementation((...m: unknown[]) => { errors.push(m.join(" ")); });
+  vi.spyOn(console, "log").mockImplementation((...m: unknown[]) => { logs.push(m.join(" ")); });
+  vi.spyOn(process.stderr, "write").mockImplementation(() => true);
+  appendReleaseRecordMock.mockReset().mockImplementation(async (input: object) => ({ commit: "c0ffee0", record: { version: 1, ...input } }));
+  readReleaseLedgerMock.mockReset().mockResolvedValue({ records: [staging], malformed: 0 });
+  pushLifecycleMock.mockReset().mockResolvedValue(undefined);
+  resolveTargetsMock.mockReset().mockResolvedValue({ success: true, targets: [api] });
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe("chant components promote", () => {
+  test("--from and --to are required", async () => {
+    expect(await runComponentsPromote(ctx({ migrateTo: undefined }))).toBe(1);
+    expect(errors.join("\n")).toMatch(/--from <env> and --to <env> are required/);
+  });
+
+  test("deploys the staging digest to prod without building, and records the promotion", async () => {
+    expect(await runComponentsPromote(ctx({}))).toBe(0);
+    expect(readReleaseLedgerMock).toHaveBeenCalledWith("staging");
+    expect(ran).toEqual(["prod:publish-image", "prod:apply"]);
+    expect(appendReleaseRecordMock).toHaveBeenCalledTimes(1);
+    expect(appendReleaseRecordMock.mock.calls[0][0]).toMatchObject({
+      component: "api",
+      env: "prod",
+      digest: "sha256:api",
+      gitSha: "abc123",
+      runId: "run-9",
+      actor: "bob",
+      promotedFrom: { env: "staging", runId: "run-7", timestamp: "2026-01-02T00:00:00.000Z" },
+    });
+    expect(pushLifecycleMock).toHaveBeenCalledTimes(1);
+  });
+
+  test("a digest missing from the source ledger fails clearly and deploys nothing", async () => {
+    expect(await runComponentsPromote(ctx({ component: "api", digest: "sha256:unknown" }))).toBe(1);
+    expect(errors.join("\n")).toMatch(/sha256:unknown is not recorded for "api" in "staging"/);
+    expect(ran).toEqual([]);
+    expect(appendReleaseRecordMock).not.toHaveBeenCalled();
+  });
+
+  test("--dry-run prints the plan and deploys nothing", async () => {
+    expect(await runComponentsPromote(ctx({ dryRun: true, json: true }))).toBe(0);
+    expect(ran).toEqual([]);
+    expect(appendReleaseRecordMock).not.toHaveBeenCalled();
+    const plan = JSON.parse(logs.join("\n"));
+    expect(plan.items).toEqual([expect.objectContaining({ component: "api", digest: "sha256:api", notRun: ["docker-build"] })]);
+  });
+
+  test("a publish that does not match the recorded digest fails and records nothing", async () => {
+    publishedDigest = "sha256:other";
+    expect(await runComponentsPromote(ctx({}))).toBe(1);
+    expect(ran).toEqual(["prod:publish-image"]);
+    expect(appendReleaseRecordMock).not.toHaveBeenCalled();
+  });
+
+  test("a gate in the composition stops the promote with exit 3 and records nothing", async () => {
+    const gated: DriverComponent = {
+      ...api,
+      deploy: [...api.deploy.slice(0, 2), { phase: "Apply", steps: [{ kind: "gate", gate: "prod-release" }, { kind: "apply" }] }],
+    };
+    resolveTargetsMock.mockResolvedValue({ success: true, targets: [gated] });
+    expect(await runComponentsPromote(ctx({}))).toBe(3);
+    expect(ran).not.toContain("prod:apply");
+    expect(appendReleaseRecordMock).not.toHaveBeenCalled();
+    expect(errors.join("\n")).toMatch(/chant approve api prod-release/);
+  });
+
+  test("a component that deployed is recorded even when another one failed", async () => {
+    const web: DriverComponent = { ...api, name: "web" };
+    resolveTargetsMock.mockResolvedValue({ success: true, targets: [api, web] });
+    readReleaseLedgerMock.mockResolvedValue({ records: [staging, { ...staging, component: "web" }], malformed: 0 });
+    failApplyFor = "web";
+    expect(await runComponentsPromote(ctx({}))).toBe(1);
+    expect(appendReleaseRecordMock).toHaveBeenCalledTimes(1);
+    expect(appendReleaseRecordMock.mock.calls[0][0]).toMatchObject({ component: "api", env: "prod" });
+  });
+
+  test("a component with no publish step is refused before anything runs", async () => {
+    resolveTargetsMock.mockResolvedValue({
+      success: true,
+      targets: [{ name: "api", deploy: [{ phase: "Apply", steps: [{ kind: "apply" }] }] }],
+    });
+    expect(await runComponentsPromote(ctx({}))).toBe(1);
+    expect(errors.join("\n")).toMatch(/no publish step/);
+    expect(ran).toEqual([]);
+  });
+});
+
+describe("chant components rollback", () => {
+  const prod = (digest: string, timestamp: string, runId: string): ReleaseRecord =>
+    ({ ...staging, env: "prod", digest, timestamp, runId });
+
+  beforeEach(() => {
+    readReleaseLedgerMock.mockResolvedValue({
+      records: [prod("sha256:old", "2026-01-01T00:00:00.000Z", "run-1"), prod("sha256:new", "2026-01-02T00:00:00.000Z", "run-2")],
+      malformed: 0,
+    });
+  });
+
+  const rb = (a: Partial<ParsedArgs>) => ctx({ migrateFrom: undefined, migrateTo: undefined, path: "rollback", extraPositional: "prod", component: "api", ...a });
+
+  test("an environment and --component are required", async () => {
+    expect(await runComponentsRollback(rb({ component: undefined }))).toBe(1);
+    expect(errors.join("\n")).toMatch(/--component <name> are required/);
+  });
+
+  test("redeploys the previous release from its recorded digest and records what it restored", async () => {
+    expect(await runComponentsRollback(rb({}))).toBe(0);
+    expect(readReleaseLedgerMock).toHaveBeenCalledWith("prod");
+    // Neither a build nor a publish: the environment already has the artifact.
+    expect(ran).toEqual(["prod:apply"]);
+    expect(appendReleaseRecordMock.mock.calls[0][0]).toMatchObject({
+      component: "api",
+      env: "prod",
+      digest: "sha256:old",
+      restores: { env: "prod", runId: "run-1", timestamp: "2026-01-01T00:00:00.000Z" },
+    });
+    expect(appendReleaseRecordMock.mock.calls[0][0]).not.toHaveProperty("promotedFrom");
+  });
+
+  test("a digest the environment never recorded fails clearly", async () => {
+    expect(await runComponentsRollback(rb({ digest: "sha256:elsewhere" }))).toBe(1);
+    expect(errors.join("\n")).toMatch(/sha256:elsewhere is not recorded for "api" in "prod"/);
+    expect(ran).toEqual([]);
+  });
+
+  test("the environment's gate applies to a rollback", async () => {
+    const gated: DriverComponent = {
+      ...api,
+      name: "api",
+      deploy: [...api.deploy.slice(0, 2), { phase: "Apply", steps: [{ kind: "gate", gate: "rollback-ok" }, { kind: "apply" }] }],
+    };
+    resolveTargetsMock.mockResolvedValue({ success: true, targets: [gated] });
+    expect(await runComponentsRollback(rb({}))).toBe(3);
+    expect(ran).not.toContain("prod:apply");
+    expect(appendReleaseRecordMock).not.toHaveBeenCalled();
+    expect(errors.join("\n")).toMatch(/chant approve api rollback-ok/);
+  });
+});