@intentius/chant 0.61.0 → 0.63.0

package/src/lifecycle/gate-ledger.test.ts

@@ -6,7 +6,8 @@ import { join } from "node:path";
 import {
   appendGateResolution, appendPendingGate, readGateResolutions, readGateLedger,
   latestResolutionSince, latestPendingGate, isPendingGateExpired,
-  resolveApprovalUrl, isApprovalUrl, type PendingGateRecord,
+  resolveApprovalUrl, isApprovalUrl, latestResolutionForPlan,
+  type PendingGateRecord, type GateResolutionRecord,
 } from "./gate-ledger";
 import { readBlobFromPath, writeBlobToPath } from "./git";
 
@@ -253,3 +254,134 @@ describe("lifecycle/gate-ledger — pending facts (#2119)", () => {
     });
   });
 });
+
+/**
+ * #2300. `latestResolutionSince` asks "is there a newer approval", which a run
+ * answers yes to however much has changed since it was written. That is the
+ * rule INTENTIUS/choudoufu#1026 measured applying a renamed resource without
+ * complaint. `latestResolutionForPlan` asks "is there an approval of *this*",
+ * with recency demoted from the criterion to the tiebreak.
+ */
+describe("latestResolutionForPlan (#2300)", () => {
+  const EPOCH = new Date(0).toISOString();
+  const PLAN_A = `sha256:${"a".repeat(64)}`;
+  const PLAN_B = `sha256:${"b".repeat(64)}`;
+
+  const resolution = (over: Partial<GateResolutionRecord>): GateResolutionRecord => ({
+    version: 1, op: "live-apply", gate: "approve-live-apply", resolvedBy: "alex",
+    timestamp: "2026-01-02T00:00:00.000Z", ...over,
+  });
+
+  test("a resolution for this plan answers the gate", () => {
+    const found = latestResolutionForPlan([resolution({ planDigest: PLAN_A })], "approve-live-apply", EPOCH, PLAN_A);
+    expect(found.resolution?.resolvedBy).toBe("alex");
+    expect(found.mismatched).toBeUndefined();
+  });
+
+  test("a resolution for another plan does not, and comes back named", () => {
+    const found = latestResolutionForPlan([resolution({ planDigest: PLAN_B })], "approve-live-apply", EPOCH, PLAN_A);
+    expect(found.resolution).toBeUndefined();
+    expect(found.mismatched?.planDigest).toBe(PLAN_B);
+  });
+
+  // The migration, and the safe reading of it: a record with no digest proves
+  // someone approved something, and nothing about what.
+  test("a resolution written before #2300 never matches a plan-bound gate", () => {
+    const found = latestResolutionForPlan([resolution({})], "approve-live-apply", EPOCH, PLAN_A);
+    expect(found.resolution).toBeUndefined();
+    expect(found.mismatched).toBeDefined();
+    expect(found.mismatched?.planDigest).toBeUndefined();
+  });
+
+  // Recency is the tiebreak, not the criterion: a newer approval of the wrong
+  // plan does not shadow an older approval of the right one.
+  test("an older resolution for this plan beats a newer one for another", () => {
+    const found = latestResolutionForPlan(
+      [
+        resolution({ planDigest: PLAN_A, resolvedBy: "right", timestamp: "2026-01-02T00:00:00.000Z" }),
+        resolution({ planDigest: PLAN_B, resolvedBy: "wrong", timestamp: "2026-01-09T00:00:00.000Z" }),
+      ],
+      "approve-live-apply", EPOCH, PLAN_A,
+    );
+    expect(found.resolution?.resolvedBy).toBe("right");
+  });
+
+  test("among several for this plan, the newest wins", () => {
+    const found = latestResolutionForPlan(
+      [
+        resolution({ planDigest: PLAN_A, resolvedBy: "first", timestamp: "2026-01-02T00:00:00.000Z" }),
+        resolution({ planDigest: PLAN_A, resolvedBy: "second", timestamp: "2026-01-03T00:00:00.000Z" }),
+      ],
+      "approve-live-apply", EPOCH, PLAN_A,
+    );
+    expect(found.resolution?.resolvedBy).toBe("second");
+  });
+
+  test("the staleness rule still applies — a resolution older than the pending fact is no answer to it", () => {
+    const found = latestResolutionForPlan(
+      [resolution({ planDigest: PLAN_A, timestamp: "2026-01-01T00:00:00.000Z" })],
+      "approve-live-apply", "2026-01-05T00:00:00.000Z", PLAN_A,
+    );
+    expect(found.resolution).toBeUndefined();
+    expect(found.mismatched).toBeUndefined();
+  });
+
+  test("a gate that binds no plan decides exactly as latestResolutionSince does", () => {
+    const records = [resolution({}), resolution({ resolvedBy: "newer", timestamp: "2026-01-04T00:00:00.000Z" })];
+    expect(latestResolutionForPlan(records, "approve-live-apply", EPOCH, undefined).resolution?.resolvedBy)
+      .toBe(latestResolutionSince(records, "approve-live-apply", EPOCH)?.resolvedBy);
+  });
+
+  test("another gate's resolutions are not read as this one's", () => {
+    const found = latestResolutionForPlan(
+      [resolution({ gate: "approve-live-adopt", planDigest: PLAN_A })],
+      "approve-live-apply", EPOCH, PLAN_A,
+    );
+    expect(found.resolution).toBeUndefined();
+    expect(found.mismatched).toBeUndefined();
+  });
+});
+
+/**
+ * A `planDigest` that is present but not a string is a malformed line, not a
+ * line with a field to ignore (#2300) — ignoring it would demote a plan-bound
+ * record to a digest-less one, which is the shape a plan-bound gate refuses.
+ */
+describe("readGateLedger — a corrupted planDigest is malformed (#2300)", () => {
+  test("a non-string planDigest is counted, not read as an approval of nothing", async () => {
+    await withTestDir(async (dir) => {
+      await initRepo(dir);
+      await writeBlobToPath(
+        "_gates", "live-apply.jsonl",
+        JSON.stringify({
+          version: 1, op: "live-apply", gate: "g", resolvedBy: "alex",
+          timestamp: "2026-01-01T00:00:00.000Z", planDigest: { sha: "…" },
+        }),
+        "hand-written",
+        { cwd: dir },
+      );
+      const { resolutions, malformed } = await readGateLedger("live-apply", { cwd: dir });
+      expect(malformed).toBe(1);
+      expect(resolutions).toEqual([]);
+    });
+  });
+
+  test("a string planDigest round-trips onto both kinds of record", async () => {
+    await withTestDir(async (dir) => {
+      await initRepo(dir);
+      const digest = `sha256:${"a".repeat(64)}`;
+      await appendPendingGate(
+        { op: "live-apply", gate: "g", timestamp: "2026-01-01T00:00:00.000Z", expiresAt: "2026-01-03T00:00:00.000Z", planDigest: digest },
+        { cwd: dir },
+      );
+      await appendGateResolution(
+        { op: "live-apply", gate: "g", resolvedBy: "alex", timestamp: "2026-01-02T00:00:00.000Z", planDigest: digest },
+        { cwd: dir },
+      );
+      const { resolutions, pending, malformed } = await readGateLedger("live-apply", { cwd: dir });
+      expect(malformed).toBe(0);
+      expect(pending[0].planDigest).toBe(digest);
+      expect(resolutions[0].planDigest).toBe(digest);
+    });
+  });
+});

package/src/lifecycle/gate-ledger.ts

@@ -22,6 +22,13 @@
  * `chant approve` locally can write one, the same trust boundary a local
  * commit already has.
  *
+ * Since #2300 both halves also carry a plan identity (`./plan-digest.ts`): a
+ * run records the plan it reached the gate with, `chant approve` records the
+ * plan it approves, and {@link latestResolutionForPlan} matches on that
+ * rather than on recency alone. Before it, an approval authorised the next
+ * run of an op rather than the plan its approver had read
+ * (INTENTIUS/choudoufu#1026).
+ *
  * Since #2119 the file carries both halves of the loop. A `gate` step the
  * local executor reaches (`../op/local-executor.ts`) appends a
  * {@link PendingGateRecord} and ends that run with status `gated`; `chant
@@ -119,6 +126,18 @@ export interface GateResolutionRecord {
    * URL — see {@link isApprovalUrl}.
    */
   url?: string;
+  /**
+   * The plan this approval is for (#2300) — `computePlanDigest`'s output
+   * (`./plan-digest.ts`), normally copied off the {@link PendingGateRecord}
+   * this resolution answers.
+   *
+   * Absent on every resolution written before #2300, and on one written for a
+   * gate that binds no plan. Absent is not a wildcard: {@link
+   * latestResolutionForPlan} refuses a digest-less resolution against a
+   * plan-bound gate rather than letting it through, because the only thing
+   * such a record proves is that somebody approved *something*.
+   */
+  planDigest?: string;
 }
 
 export type GateResolutionInput = Omit<GateResolutionRecord, "version" | "kind">;
@@ -154,6 +173,16 @@ export interface PendingGateRecord {
   expiresAt: string;
   /** The address approval happens at, when the run knew one — see {@link resolveApprovalUrl}. */
   url?: string;
+  /**
+   * The plan the run reached this gate with (#2300) — `computePlanDigest`'s
+   * output (`./plan-digest.ts`). This is what `chant approve` copies onto the
+   * resolution by default, so approving the standing fact approves the plan
+   * the approver was shown rather than the next run's.
+   *
+   * Absent when the gate binds no plan (a component gate, an authored `gate`
+   * step with no `plan`), which is the shape every gate had before #2300.
+   */
+  planDigest?: string;
 }
 
 export type PendingGateInput = Omit<PendingGateRecord, "version" | "kind">;
@@ -262,6 +291,16 @@ export async function readGateLedger(
         malformed++;
         continue;
       }
+      // #2300: a `planDigest` that is present but not a string is a
+      // malformed line, not a line with a field to ignore. Ignoring it would
+      // silently demote a plan-bound record to a digest-less one, which is
+      // the shape `latestResolutionForPlan` refuses — a corrupted approval
+      // must not read as an approval of anything at all.
+      const rawDigest: unknown = (parsed as { planDigest?: unknown }).planDigest;
+      if (rawDigest !== undefined && typeof rawDigest !== "string") {
+        malformed++;
+        continue;
+      }
       if (parsed.kind === "pending") {
         if (typeof parsed.expiresAt !== "string") {
           malformed++;
@@ -319,3 +358,72 @@ export function latestResolutionSince(
   }
   return latest;
 }
+
+/** What {@link latestResolutionForPlan} found for the plan a run is holding. */
+export interface PlanBoundResolution {
+  /** The resolution that answers this gate for this plan. Absent when nothing does. */
+  resolution?: GateResolutionRecord;
+  /**
+   * Present instead of {@link PlanBoundResolution.resolution} when a
+   * resolution stands for this gate but for a different plan — the newest
+   * such record, so a refusal can name who approved what and when. Its
+   * `planDigest` is `undefined` for a record written before #2300.
+   */
+  mismatched?: GateResolutionRecord;
+}
+
+/**
+ * The resolution that answers `gate` for the plan `planDigest` identifies
+ * (#2300).
+ *
+ * The criterion is the digest; recency is only the tiebreak between several
+ * resolutions that all match it. That inversion is the whole point of the
+ * issue: {@link latestResolutionSince} asks "is there a newer approval",
+ * which a run answers yes to no matter what has changed since, and this asks
+ * "is there an approval of *this*".
+ *
+ * - `planDigest` `undefined` — the gate binds no plan (a component gate, a
+ *   `gate` step authored with no `plan`). Falls straight through to
+ *   {@link latestResolutionSince}: gates that never claimed to bind a plan
+ *   behave exactly as they did before #2300.
+ * - A resolution whose `planDigest` equals `planDigest` answers the gate.
+ * - A resolution for a different plan does not, and comes back as
+ *   `mismatched` so the caller can name both digests.
+ * - A resolution with no `planDigest` at all — every record written before
+ *   #2300 — does not either, and comes back as `mismatched` with an absent
+ *   `planDigest`. This is the safe reading of the migration: such a record
+ *   proves someone approved something, and nothing about what. Accepting it
+ *   once would silently apply the very change this check exists to catch, on
+ *   exactly the estates that have been running longest. The cost is one
+ *   further `chant approve` per gate after the upgrade, which the refusal
+ *   says out loud.
+ */
+export function latestResolutionForPlan(
+  records: GateResolutionRecord[],
+  gate: string,
+  sinceIso: string,
+  planDigest: string | undefined,
+): PlanBoundResolution {
+  if (planDigest === undefined) {
+    const resolution = latestResolutionSince(records, gate, sinceIso);
+    return resolution ? { resolution } : {};
+  }
+
+  const since = new Date(sinceIso).getTime();
+  let matched: GateResolutionRecord | undefined;
+  let mismatched: GateResolutionRecord | undefined;
+  for (const r of records) {
+    if (r.gate !== gate) continue;
+    if (new Date(r.timestamp).getTime() < since) continue;
+    const newest = (best: GateResolutionRecord | undefined) =>
+      !best || new Date(r.timestamp).getTime() >= new Date(best.timestamp).getTime();
+    if (r.planDigest === planDigest) {
+      if (newest(matched)) matched = r;
+    } else if (newest(mismatched)) {
+      mismatched = r;
+    }
+  }
+
+  if (matched) return { resolution: matched };
+  return mismatched ? { mismatched } : {};
+}

package/src/lifecycle/git.test.ts

@@ -420,8 +420,18 @@ describe("lifecycle/git", () => {
     }
   });
 
-  test("concurrent write rejected: second push throws StaleLifecycleBranchError", async () => {
-    // Simulate two concurrent operators by setting up two clones of the same remote.
+  /**
+   * Rewritten for #2309's review. This used to assert that operator B's push
+   * was *rejected*: B had no local `chant/lifecycle`, so its write built an
+   * unrelated root commit, and the lease was the only thing standing between
+   * that fork and A's history on the remote.
+   *
+   * A write that has to be caught by a lease is the bug, not the contract.
+   * `writeBlobToPath` now brings the branch in before it creates one, so B
+   * never forks: it appends to A's history and pushes cleanly, and both
+   * snapshots survive. The genuine stale-lease case is the test below.
+   */
+  test("a second writer with no local ledger appends to the first's history rather than forking", async () => {
     const { clonePath: cloneA, remotePath, cleanup } = await setupClonePair();
     const cloneB = join(tmpdir(), `chant-state-clone-b-${Date.now()}-${Math.random()}`);
     try {
@@ -433,9 +443,43 @@ describe("lifecycle/git", () => {
       await writeSnapshot("prod", "aws", JSON.stringify({ a: 1 }), { cwd: cloneA });
       expect(await pushLifecycle({ cwd: cloneA })).toBe(true);
 
-      // Operator B writes from the same baseline (chant/lifecycle doesn't exist
-      // on cloneB's remote-tracking yet) and tries to push — should fail
-      // with StaleLifecycleBranchError because A's push moved the remote ref.
+      // Operator B has never seen `chant/lifecycle`.
+      expect(git(["rev-parse", "--verify", "refs/heads/chant/lifecycle"], cloneB).exitCode).not.toBe(0);
+      await writeSnapshot("staging", "gcp", JSON.stringify({ b: 2 }), { cwd: cloneB });
+      expect(await pushLifecycle({ cwd: cloneB })).toBe(true);
+
+      // Neither snapshot was lost.
+      expect(await readSnapshot("prod", "aws", { cwd: cloneB })).toBe(JSON.stringify({ a: 1 }));
+      expect(await readSnapshot("staging", "gcp", { cwd: cloneB })).toBe(JSON.stringify({ b: 2 }));
+    } finally {
+      await cleanup();
+      const { rm } = await import("node:fs/promises");
+      await rm(cloneB, { recursive: true, force: true });
+    }
+  });
+
+  test("concurrent write rejected: second push throws StaleLifecycleBranchError", async () => {
+    const { clonePath: cloneA, remotePath, cleanup } = await setupClonePair();
+    const cloneB = join(tmpdir(), `chant-state-clone-b-${Date.now()}-${Math.random()}`);
+    try {
+      git(["clone", "-q", remotePath, cloneB], tmpdir());
+      git(["config", "user.email", "test@chant.dev"], cloneB);
+      git(["config", "user.name", "Test"], cloneB);
+
+      await writeSnapshot("prod", "aws", JSON.stringify({ a: 1 }), { cwd: cloneA });
+      expect(await pushLifecycle({ cwd: cloneA })).toBe(true);
+
+      // B takes a copy of the branch, so it has local history and a
+      // remote-tracking ref pinned to what it saw.
+      git(["fetch", "-q", "origin", "chant/lifecycle:chant/lifecycle"], cloneB);
+
+      // A moves the remote on again, behind B's back.
+      git(["fetch", "-q", "origin", "+refs/heads/chant/lifecycle:refs/remotes/origin/chant/lifecycle"], cloneA);
+      await writeSnapshot("prod", "aws", JSON.stringify({ a: 2 }), { cwd: cloneA });
+      expect(await pushLifecycle({ cwd: cloneA })).toBe(true);
+
+      // B appends to the tip it knows and pushes against a lease that no
+      // longer matches the remote.
       await writeSnapshot("staging", "gcp", JSON.stringify({ b: 2 }), { cwd: cloneB });
       await expect(pushLifecycle({ cwd: cloneB })).rejects.toBeInstanceOf(StaleLifecycleBranchError);
     } finally {