@intentius/chant 0.61.0 → 0.63.0

package/src/op/gate.ts

@@ -19,6 +19,14 @@
  * pre-authorize a future run's gate that has since been recorded pending; a
  * resolution from last month does not answer the fact this run just wrote.
  *
+ * Since #2300 a gate can also bind a plan. `GateCheckInput.planDigest` is
+ * what this run's Plan phase produced (`../lifecycle/plan-digest.ts`), and a
+ * resolution counts only when it was recorded for that same plan — recency
+ * demoted from the criterion to the tiebreak. Approve, edit the root, re-run,
+ * and the gate refuses by name instead of applying something no approver saw,
+ * which is what INTENTIUS/choudoufu#1026 measured it doing. A gate with no
+ * `planDigest` decides exactly as it did before.
+ *
  * Ledger access goes through {@link GateLedgerPort} rather than straight to
  * git, so a test (and the operator's own in-memory paths) can drive the
  * decision without an orphan branch on disk.
@@ -28,7 +36,7 @@ import {
   appendPendingGate,
   isPendingGateExpired,
   latestPendingGate,
-  latestResolutionSince,
+  latestResolutionForPlan,
   readGateLedger,
   resolveApprovalUrl,
   DEFAULT_GATE_EXPIRY,
@@ -36,32 +44,80 @@ import {
   type PendingGateInput,
   type PendingGateRecord,
 } from "../lifecycle/gate-ledger";
-import { pushLifecycle } from "../lifecycle/git";
+import { describePlanDigest } from "../lifecycle/plan-digest";
+import { pushLifecycle, requireLifecycleLedger } from "../lifecycle/git";
 import { parseDuration } from "./duration";
 
+/**
+ * What appending a pending fact learned about reaching the remote.
+ *
+ * The append to the local `chant/lifecycle` branch always lands — that half
+ * was fixed by #2309's fetch-before-append. This is the other half: whether
+ * the push that follows it did, and why not when it didn't, in one line a
+ * renderer can show directly (#2310).
+ */
+export interface PendingGatePush {
+  record: PendingGateRecord;
+  /**
+   * True when the push reached the remote. False when there was no remote
+   * configured, or the push was rejected — `pushWarning` says which.
+   */
+  pushed: boolean;
+  /** Set when `pushed` is false. */
+  pushWarning?: string;
+}
+
 /** The gate ledger, as the two executors need it: read both kinds of line, append a pending fact. */
 export interface GateLedgerPort {
   read(op: string): Promise<{ resolutions: GateResolutionRecord[]; pending: PendingGateRecord[] }>;
-  appendPending(input: PendingGateInput): Promise<PendingGateRecord>;
+  appendPending(input: PendingGateInput): Promise<PendingGatePush>;
 }
 
 /**
- * The real port: the `chant/lifecycle` orphan branch. Pushes best-effort after
- * appending, the same two-step-collapsed-into-one shape `chant approve` uses
- * (`../cli/handlers/operator.ts` calls `pushLifecycle().catch(...)` right after
- * its append) — a pending fact that only ever reaches the local branch is still
- * a correct local answer, so a missing remote never fails the run.
+ * The real port: the `chant/lifecycle` orphan branch.
+ *
+ * Appending is always local-first and always lands (#2309's fetch-before-
+ * append). The push that follows is reported rather than swallowed (#2310):
+ * a pending fact that never reaches the remote is still a correct local
+ * answer — the run is right to gate, and does — but an operator elsewhere
+ * cannot approve a gate whose pending record they cannot see, so the caller
+ * gets `pushed: false` and a reason instead of silence. Mirrors the shape
+ * `chant approve` reports through (`../cli/handlers/operator.ts`'s
+ * `reportedPush`, #2309 review).
  */
 export function gitGateLedgerPort(opts?: { cwd?: string }): GateLedgerPort {
   return {
     async read(op) {
+      // The ledger branch has to be in the checkout before it is read
+      // (#2303): a CI clone fetches the pipeline's own ref and nothing else,
+      // and an unfetched branch reads as an empty ledger — which is
+      // indistinguishable from "nothing has been approved" and makes a
+      // retried job record a second pending fact for a gate that was already
+      // approved. Refuses rather than guessing when the fetch cannot settle
+      // it; see `requireLifecycleLedger`.
+      await requireLifecycleLedger(opts);
       const { resolutions, pending } = await readGateLedger(op, opts);
       return { resolutions, pending };
     },
     async appendPending(input) {
       const { record } = await appendPendingGate(input, opts);
-      await pushLifecycle(opts).catch(() => undefined);
-      return record;
+      try {
+        const pushed = await pushLifecycle(opts);
+        return pushed
+          ? { record, pushed }
+          : {
+              record,
+              pushed,
+              pushWarning:
+                "no remote is configured for chant/lifecycle — the pending fact was recorded locally only",
+            };
+      } catch (err) {
+        return {
+          record,
+          pushed: false,
+          pushWarning: err instanceof Error ? err.message : String(err),
+        };
+      }
     },
   };
 }
@@ -82,7 +138,8 @@ export function memoryGateLedgerPort(
       const record: PendingGateRecord = { version: 1, kind: "pending", ...input };
       pending.push(record);
       appended.push(record);
-      return record;
+      // No remote in an in-memory ledger — there is nothing to fail to reach.
+      return { record, pushed: true };
     },
   };
 }
@@ -98,14 +155,82 @@ export interface GateCheckInput {
   timeout?: string;
   /** Identifies the run that reached the gate, when the caller has one. */
   runId?: string;
+  /**
+   * The plan this run reached the gate with (#2300) — `computePlanDigest`'s
+   * output (`../lifecycle/plan-digest.ts`), from the Plan phase that ran a
+   * moment ago.
+   *
+   * Supplying it makes the gate plan-bound: only a resolution recorded for
+   * this exact digest satisfies it, and one recorded for a different plan (or
+   * for no plan at all) is reported as a {@link GateDigestMismatch} instead.
+   * Omitting it keeps the pre-#2300 rule, where the newest resolution since
+   * the standing pending fact satisfies the gate whatever has changed since.
+   */
+  planDigest?: string;
   /** ISO-8601 "now" — supplied by the caller, so the decision is deterministic under test. */
   now?: string;
 }
 
+/**
+ * A standing resolution that answers this gate but not this plan (#2300) —
+ * what a refusal names.
+ */
+export interface GateDigestMismatch {
+  /** The plan that was approved. `undefined` for a resolution written before #2300, which recorded no plan at all. */
+  approved?: string;
+  /** The plan this run's Plan phase produced. */
+  planned: string;
+  /** Who recorded the approval that does not apply here. */
+  resolvedBy: string;
+  /** When they recorded it. */
+  timestamp: string;
+}
+
+/**
+ * The refusal line for a {@link GateDigestMismatch}: which plan was approved,
+ * which was planned, and what closes the gap. One function so the executor's
+ * step record, the human render and the CI summary say the same thing.
+ *
+ * The two cases get different prose because they are different facts. A
+ * resolution for another plan means something changed between the approval
+ * and this run. A resolution with no plan on it means nothing is known to
+ * have changed — the record simply never said what it approved, which is
+ * every record written before #2300.
+ */
+export function describeGateMismatch(op: string, gate: string, mismatch: GateDigestMismatch): string {
+  const why =
+    mismatch.approved === undefined
+      ? "That resolution predates plan-bound gates (#2300) and records no plan at all, so it cannot " +
+        "answer for this one. Approving again binds it:"
+      : "The configuration or the live system changed between that approval and this plan, so it needs " +
+        "a fresh one:";
+  return (
+    `Gate "${gate}" is approved, but not for this plan. ` +
+    `approved: ${describePlanDigest(mismatch.approved)} (by ${mismatch.resolvedBy} at ${mismatch.timestamp}); ` +
+    `planned: ${mismatch.planned}. ` +
+    `${why} ${approveCommand(op, gate)}`
+  );
+}
+
 /** Either the gate is answered, or it is a standing fact. */
 export type GateCheck =
   | { satisfied: true; resolution: GateResolutionRecord }
-  | { satisfied: false; pending: PendingGateRecord; recorded: boolean };
+  | {
+      satisfied: false;
+      pending: PendingGateRecord;
+      recorded: boolean;
+      /**
+       * Whether this run's own append reached the remote — set only when
+       * `recorded` is true. A gate left standing from an earlier run pushed
+       * (or didn't) on that run; this one wrote nothing, so it has nothing
+       * new to report (#2310).
+       */
+      pushed?: boolean;
+      /** Set when `pushed` is false. */
+      pushWarning?: string;
+      /** Present when a resolution stands for this gate but for another plan (#2300). */
+      mismatch?: GateDigestMismatch;
+    };
 
 /** The beginning of time — the anchor for a gate that has never been recorded pending, so any resolution for it counts. */
 const EPOCH = new Date(0).toISOString();
@@ -114,28 +239,61 @@ const EPOCH = new Date(0).toISOString();
  * Decide a gate against the ledger, recording the pending fact when it isn't
  * answered.
  *
- * - A resolution newer than the newest pending fact satisfies the gate.
- * - Otherwise, a pending fact that hasn't expired stands as it is: the run
- *   ends `gated` and the ledger is left alone, so an operator ticking every
- *   minute against an unapproved gate does not append a line a minute.
- * - Otherwise (no pending fact, or the newest one has expired) a fresh pending
- *   fact is appended and the run ends `gated`. `recorded` says which of the
- *   two happened, so a renderer can tell "just recorded" from "still standing".
+ * - A resolution recorded for this run's own plan, newer than the newest
+ *   pending fact, satisfies the gate. On a gate that binds no plan
+ *   (`input.planDigest` absent) the plan half of that drops out and the rule
+ *   is the pre-#2300 one: any resolution newer than the pending fact.
+ * - A resolution that stands for the gate but for a different plan does not
+ *   satisfy it (#2300). The run is gated, `mismatch` names both plans, and a
+ *   fresh pending fact is recorded for the plan that actually ran — so
+ *   `chant approve` has something current to approve and the loop closes in
+ *   one more command rather than needing the digest typed out.
+ * - Otherwise, a pending fact that hasn't expired *and was recorded for this
+ *   same plan* stands as it is: the run ends `gated` and the ledger is left
+ *   alone, so an operator ticking every minute against an unapproved gate
+ *   does not append a line a minute. A pending fact for a different plan is
+ *   stale in the way that matters and is replaced.
+ * - Otherwise (no pending fact, or the newest one has expired, or it is for
+ *   another plan) a fresh pending fact is appended and the run ends `gated`.
+ *   `recorded` says which of the two happened, so a renderer can tell "just
+ *   recorded" from "still standing".
  */
 export async function evaluateGate(port: GateLedgerPort, input: GateCheckInput): Promise<GateCheck> {
   const now = input.now ?? new Date().toISOString();
   const { resolutions, pending } = await port.read(input.op);
 
   const standing = latestPendingGate(pending, input.gate);
-  const resolution = latestResolutionSince(resolutions, input.gate, standing?.timestamp ?? EPOCH);
+  const { resolution, mismatched } = latestResolutionForPlan(
+    resolutions,
+    input.gate,
+    standing?.timestamp ?? EPOCH,
+    input.planDigest,
+  );
   if (resolution) return { satisfied: true, resolution };
 
-  if (standing && !isPendingGateExpired(standing, now)) {
-    return { satisfied: false, pending: standing, recorded: false };
+  // `input.planDigest` is defined whenever `mismatched` is — `latestResolutionForPlan`
+  // returns a mismatch only on the plan-bound path.
+  const mismatch: GateDigestMismatch | undefined = mismatched
+    ? {
+        ...(mismatched.planDigest !== undefined ? { approved: mismatched.planDigest } : {}),
+        planned: input.planDigest!,
+        resolvedBy: mismatched.resolvedBy,
+        timestamp: mismatched.timestamp,
+      }
+    : undefined;
+  const asMismatch = mismatch ? { mismatch } : {};
+
+  // A standing fact only stands for the plan it was recorded against. When
+  // the plan has moved, re-recording is what gives `chant approve` (which
+  // defaults to the newest pending fact's digest) the current plan to
+  // approve; leaving the old fact standing would make the common path
+  // approve a plan that is no longer the one being run.
+  if (standing && !isPendingGateExpired(standing, now) && standing.planDigest === input.planDigest) {
+    return { satisfied: false, pending: standing, recorded: false, ...asMismatch };
   }
 
   const url = resolveApprovalUrl();
-  const record = await port.appendPending({
+  const { record, pushed, pushWarning } = await port.appendPending({
     op: input.op,
     gate: input.gate,
     timestamp: now,
@@ -145,8 +303,16 @@ export async function evaluateGate(port: GateLedgerPort, input: GateCheckInput):
     ...(input.description ? { description: input.description } : {}),
     ...(input.runId ? { runId: input.runId } : {}),
     ...(url ? { url } : {}),
+    ...(input.planDigest !== undefined ? { planDigest: input.planDigest } : {}),
   });
-  return { satisfied: false, pending: record, recorded: true };
+  return {
+    satisfied: false,
+    pending: record,
+    recorded: true,
+    pushed,
+    ...(pushWarning ? { pushWarning } : {}),
+    ...asMismatch,
+  };
 }
 
 /** The line every renderer prints to say how a pending gate is cleared. */

package/src/op/index.ts

@@ -50,8 +50,11 @@ export type { ActivityProfile, ActivityProfileName } from "./activity-profiles";
 export { NonRetryableActivityError, nonRetryableFailure } from "./activity-failure";
 export { runOpLocally, parseDuration, OpRunFailure } from "./local-executor";
 export type { StepRecord, OpRunResult, RunOpOptions } from "./local-executor";
-export { evaluateGate, gitGateLedgerPort, memoryGateLedgerPort, approveCommand } from "./gate";
-export type { GateLedgerPort, GateCheck, GateCheckInput } from "./gate";
+export { evaluateGate, gitGateLedgerPort, memoryGateLedgerPort, approveCommand, describeGateMismatch } from "./gate";
+export type { GateLedgerPort, GateCheck, GateCheckInput, PendingGatePush, GateDigestMismatch } from "./gate";
+export {
+  computePlanDigest, isPlanDigest, describePlanDigest, PLAN_DIGEST_ALGORITHM,
+} from "../lifecycle/plan-digest";
 export { gateName, usesDeprecatedGateKey, DEPRECATED_GATE_KEY_WARNING } from "./gate-name";
 export type { GateNamed } from "./gate-name";
 export { createLocalOpRuntime } from "./runtimes/local";

package/src/op/local-executor.test.ts

@@ -6,8 +6,10 @@ import {
   parseDuration,
   OpRunFailure,
 } from "./local-executor";
-import { memoryGateLedgerPort } from "./gate";
-import type { GateResolutionRecord, PendingGateRecord } from "../lifecycle/gate-ledger";
+import { memoryGateLedgerPort, type GateLedgerPort } from "./gate";
+import { computePlanDigest } from "../lifecycle/plan-digest";
+import { renderHuman } from "./local-output";
+import type { GateResolutionRecord, PendingGateRecord, PendingGateInput } from "../lifecycle/gate-ledger";
 import { stepOutput } from "./step-output-ref";
 
 // Fast profiles so retry/timeout tests run in milliseconds.
@@ -324,6 +326,33 @@ describe("runOpLocally — gate as fact (#2119)", () => {
     ]);
   });
 
+  // #2310: the gate still ends the run `gated` — an append that only reaches
+  // the local branch is still a correct local answer, and the #2309 author
+  // was right that this must not become a failure. But the run used to say
+  // nothing at all about the rejected push; now it does.
+  test("a pending fact whose push was rejected still ends the run gated, and says the push failed", async () => {
+    const { calls, activities } = tracked();
+    const port = {
+      async read() {
+        return { resolutions: [] as GateResolutionRecord[], pending: [] as PendingGateRecord[] };
+      },
+      async appendPending(input: PendingGateInput) {
+        return {
+          record: { version: 1 as const, kind: "pending" as const, ...input },
+          pushed: false,
+          pushWarning: "chant/lifecycle remote branch has moved since this run started",
+        };
+      },
+    };
+    const result = await runOpLocally(gatedOp(), activities, PROFILES, undefined, { gates: port, now: NOW });
+
+    expect(result.status).toBe("gated");
+    expect(calls).toEqual(["before"]);
+    expect(result.gate).toMatchObject({ op: "test-op", gate: "approve-prod" });
+    expect(result.gatePushed).toBe(false);
+    expect(result.gatePushWarning).toBe("chant/lifecycle remote branch has moved since this run started");
+  });
+
   // #2202: the gate step's name key is `gate`; `signalName` is read through
   // 0.59.0, so a step still spelling it that way reaches the same ledger entry.
   test("a gate step still using the deprecated `signalName` key names the same gate", async () => {
@@ -497,3 +526,312 @@ describe("runOpLocally — step-output references (#1290)", () => {
     expect(result.records[1].args).toEqual({ stacks: ["stack-a"] });
   });
 });
+
+/**
+ * #2301 deliverable 2. The reported symptom was a whole apply that printed
+ * `Op "live-apply" failed after 43.8s` and nothing else — no error line, no
+ * failing step — because the gate's ledger write threw a plain `Error` and
+ * the executor's catch only ever unpacked `PhaseFailure` and `GateStop`.
+ * Everything else was built into an `OpRunFailure` and never read again.
+ *
+ * These assert the two halves separately: the gate step now produces a
+ * failing record like any other step, and the outer catch no longer drops an
+ * error it does not recognise. The second is the general one — the gate is
+ * where it was found, not the only place it bites.
+ */
+describe("runOpLocally — a failure inside the run says what it was (#2301)", () => {
+  const NOW = "2026-09-05T12:00:00.000Z";
+  const LEDGER_ERROR =
+    "cannot write _gates/live-apply.jsonl on the chant/lifecycle branch: " +
+    "git commit-tree failed: fatal: unable to auto-detect email address (got 'runner@runner.(none)')";
+
+  /** A gate ledger whose append fails the way a CI checkout with no git identity does. */
+  function unwritablePort(message = LEDGER_ERROR) {
+    return {
+      async read() {
+        return { resolutions: [] as GateResolutionRecord[], pending: [] as PendingGateRecord[] };
+      },
+      async appendPending(): Promise<never> {
+        throw new Error(message);
+      },
+    };
+  }
+
+  function gateOnly(): OpConfig {
+    return op({
+      phases: [
+        { name: "Plan", steps: [{ kind: "activity", fn: "plan" }] },
+        { name: "Gate", steps: [{ kind: "gate", gate: "approve-live-apply" }] },
+        { name: "Apply", steps: [{ kind: "activity", fn: "apply" }] },
+      ],
+    });
+  }
+
+  const noopActivities = new Map<string, ActivityFn>([
+    ["plan", async () => undefined],
+    ["apply", async () => undefined],
+  ]);
+
+  test("a gate whose ledger write fails is a failing step carrying the cause", async () => {
+    const err = await runOpLocally(gateOnly(), noopActivities, PROFILES, undefined, {
+      gates: unwritablePort(),
+      now: NOW,
+    }).then(() => undefined, (e: unknown) => e);
+
+    expect(err).toBeInstanceOf(OpRunFailure);
+    const { result } = err as OpRunFailure;
+    expect(result.status).toBe("fail");
+
+    const gateRecord = result.records.find((r) => r.fn === "gate:approve-live-apply");
+    expect(gateRecord?.status).toBe("fail");
+    expect(gateRecord?.error).toBe(LEDGER_ERROR);
+
+    // The run stops at the gate, exactly as a failing activity stops its
+    // phase — the Apply phase never starts.
+    expect(result.records.map((r) => [r.fn, r.status])).toEqual([
+      ["plan", "ok"],
+      ["gate:approve-live-apply", "fail"],
+    ]);
+  });
+
+  test("the rendered output names the cause instead of a bare failure line", async () => {
+    const err = await runOpLocally(gateOnly(), noopActivities, PROFILES, undefined, {
+      gates: unwritablePort(),
+      now: NOW,
+    }).then(() => undefined, (e: unknown) => e);
+
+    const lines: string[] = [];
+    renderHuman((err as OpRunFailure).result, (line) => lines.push(line));
+
+    expect(lines).toContain(`    ${LEDGER_ERROR}`);
+    expect(lines.at(-1)).toMatch(/^Op "test-op" failed after /);
+    // The whole point: the failing step is visible, so the last line is no
+    // longer the only line about the failure.
+    expect(lines.some((l) => l.startsWith("  ✗ gate:approve-live-apply"))).toBe(true);
+  });
+
+  test("an error the executor does not recognise is recorded rather than dropped", async () => {
+    // Neither a step's own failure nor a gate: the caller's progress callback
+    // throws, which unwinds the phase loop as a plain `Error`. Before #2301
+    // that produced an `OpRunFailure` whose `records` held nothing marked
+    // failed and nothing carrying a message — a run that failed and said
+    // nothing at all about why. The gate is where this was found, not the
+    // only thing it swallowed.
+    const config = op({ phases: [{ name: "P", steps: [{ kind: "activity", fn: "plan" }] }] });
+
+    const err = await runOpLocally(config, noopActivities, PROFILES, undefined, {
+      onRecord: () => {
+        throw new Error("progress sink exploded");
+      },
+    }).then(() => undefined, (e: unknown) => e);
+
+    expect(err).toBeInstanceOf(OpRunFailure);
+    const failure = err as OpRunFailure;
+    expect(failure.result.records).toHaveLength(1);
+    expect(failure.result.records[0]).toMatchObject({
+      status: "fail",
+      error: expect.stringContaining("progress sink exploded"),
+    });
+    // The original error object is still reachable for a programmatic caller.
+    expect((failure.cause as Error).message).toMatch(/progress sink exploded/);
+
+    const lines: string[] = [];
+    renderHuman(failure.result, (line) => lines.push(line));
+    expect(lines.some((l) => l.includes("progress sink exploded"))).toBe(true);
+  });
+});
+
+/**
+ * #2300, measured on INTENTIUS/choudoufu#1026.
+ *
+ * The exact sequence that issue ran against a floci-backed root: `chant run
+ * live-apply` returns `gated`, `chant approve` writes the resolution, a
+ * resource in the root is renamed, and `chant run live-apply` runs again. It
+ * applied, with no refusal, because the resolution carried the op, the gate,
+ * the approver and a timestamp — and nothing about the plan. The approval had
+ * authorised the next run rather than the plan its approver read.
+ *
+ * These drive the same four steps through the executor, with a Plan phase
+ * whose digest moves when the root does.
+ */
+describe("runOpLocally — a gate approves a plan, not the next run (#2300)", () => {
+  const NOW = "2026-09-09T12:00:00.000Z";
+
+  /**
+   * A gate ledger a test can approve against, which `memoryGateLedgerPort`
+   * cannot: `chant approve` appends a resolution *between* two runs, and the
+   * shared port has to carry it into the second one.
+   */
+  function approvableLedger(): GateLedgerPort & {
+    approve(gate: string, planDigest: string | undefined, at: string): void;
+    pending: PendingGateRecord[];
+  } {
+    const resolutions: GateResolutionRecord[] = [];
+    const pending: PendingGateRecord[] = [];
+    return {
+      pending,
+      approve(gate, planDigest, at) {
+        resolutions.push({
+          version: 1, op: "live-apply", gate, resolvedBy: "alex", timestamp: at,
+          ...(planDigest !== undefined ? { planDigest } : {}),
+        });
+      },
+      async read() {
+        return { resolutions: [...resolutions], pending: [...pending] };
+      },
+      async appendPending(input) {
+        const record: PendingGateRecord = { version: 1, kind: "pending", ...input };
+        pending.push(record);
+        // No remote in an in-memory ledger — nothing to fail to reach (#2310).
+        return { record, pushed: true };
+      },
+    };
+  }
+
+  /**
+   * The root under test, and the Op over it. `terraformPlan` digests whatever
+   * `root.address` currently is, so renaming a resource between runs is one
+   * assignment — the test's stand-in for editing the `.tf` file.
+   */
+  function harness() {
+    const root = { address: "aws_s3_bucket.original" };
+    const applied: string[] = [];
+    const activities = new Map<string, ActivityFn>([
+      ["terraformPlan", async () => ({
+        planFile: "chant.tfplan",
+        planDigest: computePlanDigest("terraform-plan", { resourceChanges: [{ address: root.address }] }),
+      })],
+      ["terraformApply", async (args) => {
+        applied.push(String(args.planFile));
+        return { applied: true };
+      }],
+    ]);
+    const config = op({
+      name: "live-apply",
+      phases: [
+        { name: "Plan", steps: [{ kind: "activity", fn: "terraformPlan", id: "plan", args: { root: "app" } }] },
+        {
+          name: "Gate",
+          steps: [{ kind: "gate", gate: "approve-live-apply", plan: stepOutput("plan", "planDigest") }],
+        },
+        {
+          name: "Apply",
+          steps: [{ kind: "activity", fn: "terraformApply", args: { planFile: stepOutput("plan", "planFile") } }],
+        },
+      ],
+    });
+    const digestOf = (address: string) =>
+      computePlanDigest("terraform-plan", { resourceChanges: [{ address }] });
+    return { root, applied, activities, config, digestOf };
+  }
+
+  test("approve, rename a resource in the root, re-run — the Apply phase refuses, naming both digests", async () => {
+    const { root, applied, activities, config, digestOf } = harness();
+    const gates = approvableLedger();
+
+    // 1. `chant run live-apply` — gated, and the pending fact names the plan.
+    const first = await runOpLocally(config, activities, PROFILES, undefined, { gates, now: NOW });
+    expect(first.status).toBe("gated");
+    expect(first.gate?.planDigest).toBe(digestOf("aws_s3_bucket.original"));
+    expect(applied).toEqual([]);
+
+    // 2. `chant approve live-apply approve-live-apply` — for the plan above.
+    gates.approve("approve-live-apply", digestOf("aws_s3_bucket.original"), "2026-09-09T12:05:00.000Z");
+
+    // 3. A resource in the root is renamed.
+    root.address = "aws_s3_bucket.renamed";
+
+    // 4. `chant run live-apply` again. On the pre-#2300 rule this applied.
+    const second = await runOpLocally(config, activities, PROFILES, undefined, {
+      gates, now: "2026-09-09T12:10:00.000Z",
+    });
+
+    expect(second.status).toBe("gated");
+    expect(applied).toEqual([]);
+
+    const gateRecord = second.records.find((r) => r.fn === "gate:approve-live-apply");
+    expect(gateRecord?.refusal).toContain(`approved: ${digestOf("aws_s3_bucket.original")}`);
+    expect(gateRecord?.refusal).toContain(`planned: ${digestOf("aws_s3_bucket.renamed")}`);
+    expect(gateRecord?.refusal).toContain("chant approve live-apply approve-live-apply");
+    expect(gateRecord?.refusal).toContain("changed between that approval and this plan");
+    // The Apply step never ran, and says so.
+    expect(second.records.find((r) => r.fn === "terraformApply")?.status).toBe("skipped");
+
+    // The refusal reaches a reader, not just the record.
+    const lines: string[] = [];
+    renderHuman(second, (line) => lines.push(line));
+    expect(lines.some((l) => l.includes("[refused]") && l.includes("not for this plan"))).toBe(true);
+  });
+
+  test("approve, re-run with the root unchanged — it applies", async () => {
+    const { applied, activities, config, digestOf } = harness();
+    const gates = approvableLedger();
+
+    expect((await runOpLocally(config, activities, PROFILES, undefined, { gates, now: NOW })).status).toBe("gated");
+    gates.approve("approve-live-apply", digestOf("aws_s3_bucket.original"), "2026-09-09T12:05:00.000Z");
+
+    const second = await runOpLocally(config, activities, PROFILES, undefined, {
+      gates, now: "2026-09-09T12:10:00.000Z",
+    });
+
+    expect(second.status).toBe("ok");
+    expect(applied).toEqual(["chant.tfplan"]);
+    expect(second.records.find((r) => r.fn === "gate:approve-live-apply")?.approval?.resolvedBy).toBe("alex");
+  });
+
+  /**
+   * The migration (#2300). Every resolution written before this change has no
+   * `planDigest` at all, and the safe reading is that it matches nothing: such
+   * a record proves someone approved something and nothing about what.
+   * Accepting it once — the other candidate reading — would apply exactly the
+   * unreviewed change this check exists to catch, on the estates that have
+   * been running longest.
+   */
+  test("a resolution recorded before plan-bound gates does not pass, and the refusal says so", async () => {
+    const { applied, activities, config, digestOf } = harness();
+    const gates = approvableLedger();
+
+    expect((await runOpLocally(config, activities, PROFILES, undefined, { gates, now: NOW })).status).toBe("gated");
+    // A pre-#2300 resolution: newer than the pending fact, no plan on it.
+    gates.approve("approve-live-apply", undefined, "2026-09-09T12:05:00.000Z");
+
+    const second = await runOpLocally(config, activities, PROFILES, undefined, {
+      gates, now: "2026-09-09T12:10:00.000Z",
+    });
+
+    expect(second.status).toBe("gated");
+    expect(applied).toEqual([]);
+    const gateRecord = second.records.find((r) => r.fn === "gate:approve-live-apply");
+    expect(gateRecord?.refusal).toContain("approved: (none — recorded before plan-bound gates)");
+    expect(gateRecord?.refusal).toContain(`planned: ${digestOf("aws_s3_bucket.original")}`);
+    // ...and says why, which is not "something changed": nothing is known to
+    // have changed, the record just never said what it approved.
+    expect(gateRecord?.refusal).toContain("records no plan at all");
+  });
+
+  /**
+   * A gate with no `plan` is every gate that existed before #2300 — a
+   * component gate, an authored `gate()` with nothing to bind. Those decide
+   * exactly as they did: newest resolution since the pending fact wins.
+   */
+  test("a gate that binds no plan is unchanged", async () => {
+    const activities = new Map<string, ActivityFn>([["deploy", async () => ({ ok: true })]]);
+    const config = op({
+      name: "live-apply",
+      phases: [
+        { name: "Gate", steps: [{ kind: "gate", gate: "approve-live-apply" }] },
+        { name: "Deploy", steps: [{ kind: "activity", fn: "deploy" }] },
+      ],
+    });
+    const gates = approvableLedger();
+
+    expect((await runOpLocally(config, activities, PROFILES, undefined, { gates, now: NOW })).status).toBe("gated");
+    expect(gates.pending[0].planDigest).toBeUndefined();
+    gates.approve("approve-live-apply", undefined, "2026-09-09T12:05:00.000Z");
+
+    const second = await runOpLocally(config, activities, PROFILES, undefined, {
+      gates, now: "2026-09-09T12:10:00.000Z",
+    });
+    expect(second.status).toBe("ok");
+  });
+});