@intentius/chant 0.61.0 → 0.63.0

package/src/lifecycle/git.ts

@@ -8,6 +8,69 @@ import { getRuntime } from "../runtime-adapter";
 
 const STATE_BRANCH = "chant/lifecycle";
 
+/**
+ * The identity chant's ledger commits fall back to when the checkout has none
+ * of its own (#2301).
+ *
+ * A CI checkout is the ordinary case here, not an exotic one: GitLab CI,
+ * GitHub Actions and Forgejo Actions all clone without `user.email` or
+ * `user.name`, and `git commit-tree` refuses outright rather than inventing
+ * one — `fatal: unable to auto-detect email address`. Every write in this
+ * module goes through `commit-tree`, so before #2301 a gate's pending fact,
+ * a run record, a snapshot and a release record all died the same way the
+ * moment they ran anywhere but a developer's laptop.
+ *
+ * This is a *fallback*, applied per-invocation via `git -c` and field by
+ * field: only the half the checkout cannot supply is filled in. A configured
+ * `user.name` or `user.email` — a developer's, or a CI job that sets one
+ * deliberately — is left exactly as it is and still authors these commits, and
+ * nothing is written to the repository's config either way. Override the
+ * fallback with `CHANT_LIFECYCLE_COMMITTER_NAME` / `_EMAIL` when a project
+ * wants its ledger commits attributed to a bot account it controls.
+ */
+const LEDGER_COMMITTER_NAME = "chant";
+const LEDGER_COMMITTER_EMAIL = "chant@localhost";
+
+/**
+ * `git -c` arguments that give {@link writeBlobToPath}'s `commit-tree` a
+ * committer when — and only when — the checkout cannot supply one itself.
+ * Empty for any checkout that has an identity, which keeps every existing
+ * caller's commits byte-identical to what they were before #2301.
+ */
+async function ledgerCommitIdentityArgs(cwd?: string): Promise<string[]> {
+  const rt = getRuntime();
+  const probe = await rt.spawn(["git", "var", "GIT_COMMITTER_IDENT"], { cwd, env: C_LOCALE_ENV });
+  if (probe.exitCode === 0) return [];
+
+  // Per-field, not all-or-nothing (#2309 review). `git var` fails if *either*
+  // half is missing, so filling in both would overwrite a configured
+  // `user.name` in the checkout that has a name but no email — which is not
+  // what "a configured identity is left exactly as it is" promises.
+  const args: string[] = [];
+  for (const [key, envVar, fallback] of [
+    ["user.name", "CHANT_LIFECYCLE_COMMITTER_NAME", LEDGER_COMMITTER_NAME],
+    ["user.email", "CHANT_LIFECYCLE_COMMITTER_EMAIL", LEDGER_COMMITTER_EMAIL],
+  ] as const) {
+    const configured = await rt.spawn(["git", "config", "--get", key], { cwd, env: C_LOCALE_ENV });
+    if (configured.exitCode === 0 && configured.stdout.trim() !== "") continue;
+    args.push("-c", `${key}=${process.env[envVar]?.trim() || fallback}`);
+  }
+  return args;
+}
+
+/**
+ * Prefix every failure out of the ledger write path with what was being
+ * written and where (#2301 deliverable 2). `git commit-tree failed: <stderr>`
+ * on its own does not say that the thing that failed was chant recording a
+ * fact on its own branch, and the caller that swallows it is one stack frame
+ * away from printing nothing at all.
+ */
+function ledgerWriteError(stage: string, path: string, stderr: string): Error {
+  return new Error(
+    `cannot write ${path} on the ${STATE_BRANCH} branch: ${stage} failed: ${(stderr ?? "").trim()}`,
+  );
+}
+
 /**
  * Write a blob to an arbitrary `<environment>/<filename>` path on the orphan
  * branch, preserving every other env/file entry already on the branch.
@@ -56,13 +119,42 @@ export async function writeBlobToPath(
   // annotation) and no shell-quoting dance around embedded single quotes.
   // Content-addressed and idempotent, so this stays outside the retry loop
   // below — nothing about a CAS conflict on the ref ever invalidates it.
+  //
+  // `path` is resolved first only so every failure below can name it (#2301).
+  const path = `${environment}/${filename}`;
+
   const blobResult = await rt.spawn(["git", "hash-object", "-w", "--stdin"], { cwd, stdin: content });
   if (blobResult.exitCode !== 0) {
-    throw new Error(`git hash-object failed: ${blobResult.stderr}`);
+    throw ledgerWriteError("git hash-object", path, blobResult.stderr);
   }
   const blobSha = blobResult.stdout.trim();
 
-  const path = `${environment}/${filename}`;
+  // Resolved once, outside the retry loop: whether the checkout can name a
+  // committer does not change between attempts (#2301).
+  const identityArgs = await ledgerCommitIdentityArgs(cwd);
+
+  // Creating the ledger branch is a different act from extending it, and only
+  // one of them is safe to do blind (#2309 review). With no local
+  // `chant/lifecycle`, everything below builds a tree from an empty read and
+  // commits it with no parent — a brand-new root commit that *replaces* the
+  // branch rather than appending to it, which `updateRefCAS` cannot catch
+  // because "the ref does not exist" is perfectly true locally.
+  //
+  // Until #2301 this was mostly hidden: `commit-tree` died for want of a
+  // committer before it could happen. Supplying an identity turned that loud
+  // failure into a silent branch fabrication on every writer that reaches
+  // here without a ledger — a run record, a snapshot, a release, a build
+  // manifest — and a fabricated branch is precisely the fork the guard above
+  // exists to refuse. So the guard runs here, at the one seam they all pass
+  // through, rather than at each of their call sites.
+  //
+  // Only when the branch is absent: an extend costs no fetch, and the check
+  // that matters is whether the history this is about to discard exists
+  // somewhere. `requireLifecycleLedger` allows `no-remote` and `absent`, so a
+  // genuinely first write still creates the branch.
+  if ((await getStateBranchTip(cwd)) === null) {
+    await requireLifecycleLedger({ ...(cwd ? { cwd } : {}) });
+  }
 
   // 2-5. Read tree, build the commit, and CAS-update the branch ref — retried
   // on a conflict (#1959 finding 1). `writeBlobToPath` had no retry of its
@@ -127,7 +219,7 @@ export async function writeBlobToPath(
 
     const envTreeResult = await rt.spawn(["git", "mktree"], { cwd, stdin: `${envEntries}\n` });
     if (envTreeResult.exitCode !== 0) {
-      throw new Error(`git mktree (env) failed: ${envTreeResult.stderr}`);
+      throw ledgerWriteError("git mktree (env)", path, envTreeResult.stderr);
     }
     const envTreeSha = envTreeResult.stdout.trim();
 
@@ -150,7 +242,7 @@ export async function writeBlobToPath(
       stdin: `${rootEntries.join("\n")}\n`,
     });
     if (rootTreeResult.exitCode !== 0) {
-      throw new Error(`git mktree (root) failed: ${rootTreeResult.stderr}`);
+      throw ledgerWriteError("git mktree (root)", path, rootTreeResult.stderr);
     }
     const rootTreeSha = rootTreeResult.stdout.trim();
 
@@ -160,11 +252,11 @@ export async function writeBlobToPath(
     const parentRef = tip;
     const parentArgs = parentRef ? ["-p", parentRef] : [];
     const commitResult = await rt.spawn(
-      ["git", "commit-tree", ...parentArgs, "-m", commitMessage, rootTreeSha],
+      ["git", ...identityArgs, "commit-tree", ...parentArgs, "-m", commitMessage, rootTreeSha],
       { cwd },
     );
     if (commitResult.exitCode !== 0) {
-      throw new Error(`git commit-tree failed: ${commitResult.stderr}`);
+      throw ledgerWriteError("git commit-tree", path, commitResult.stderr);
     }
     const commitSha = commitResult.stdout.trim();
 
@@ -534,16 +626,225 @@ export async function pushLifecycle(opts?: { cwd?: string }): Promise<boolean> {
  * Fetch the state branch from remote.
  */
 export async function fetchLifecycle(opts?: { cwd?: string }): Promise<boolean> {
+  return (await fetchLifecycleStatus(opts)).status === "fetched";
+}
+
+/**
+ * Why a fetch of the ledger branch did or did not produce local history
+ * (#2303).
+ *
+ * `fetchLifecycle`'s boolean cannot answer the question the gate actually
+ * needs answered. "No local `chant/lifecycle`" has two causes that a reader
+ * of an empty ledger cannot tell apart, and they call for opposite
+ * behaviour: on a project whose ledger has never been written, an empty
+ * ledger is the truth; in a CI checkout that fetched only the pipeline's own
+ * ref, an empty ledger is history the checkout simply cannot see. Reading the
+ * second as the first is what makes a second pending fact look correct, so
+ * these are separate outcomes:
+ *
+ * - `fetched` — the branch is now in this checkout (or already was, and is
+ *   up to date). Whatever the ledger says is the whole truth.
+ * - `no-remote` — nothing to fetch from. A single-machine project; local is
+ *   authoritative by construction, the same assumption `chant operator`'s
+ *   lease already documents.
+ * - `absent` — the remote answered and has no `chant/lifecycle`. The ledger
+ *   is genuinely empty; this is a project's first gate.
+ * - `diverged` — both sides have the branch and neither contains the other.
+ *   Appending here would drop one side's facts.
+ * - `unreachable` — a remote is configured and did not answer (no network,
+ *   no credentials, a shallow-clone refspec that cannot resolve). Whether
+ *   anything is on the branch is unknown, which is exactly the state that
+ *   must not be read as "nothing has been approved".
+ */
+export type LifecycleFetchStatus =
+  | { status: "fetched" }
+  | { status: "no-remote" }
+  | { status: "absent"; remote: string }
+  | { status: "ahead"; remote: string }
+  | { status: "diverged"; remote: string; stderr: string }
+  | { status: "unreachable"; remote: string; stderr: string };
+
+/**
+ * git's wording when the remote answered and simply does not carry the ref.
+ *
+ * Matched against output forced to `LC_ALL=C` ({@link C_LOCALE_ENV}) — both of
+ * these strings are in git's translation catalogs, so on a distro git built
+ * with NLS and a non-C `LANG` an unpinned locale would fail to match and send
+ * a project's genuine first gate down the `unreachable` path, refusing it.
+ */
+const NO_SUCH_REMOTE_REF_RE = /couldn't find remote ref|no such ref was fetched/i;
+/** git's wording when the refspec would not fast-forward the local branch. Same locale caveat. */
+const NON_FAST_FORWARD_RE = /non-fast-forward|rejected/i;
+
+/**
+ * `git` invocations here are parsed by their output, so they are pinned to the
+ * C locale. `LC_ALL` alone is enough — it outranks `LC_MESSAGES` and `LANG` —
+ * but `LANGUAGE` is GNU gettext's own override and outranks all of them, so it
+ * is cleared too.
+ */
+const C_LOCALE_ENV = { LC_ALL: "C", LANGUAGE: "" };
+
+/**
+ * The remote the ledger lives on.
+ *
+ * `origin` when it exists, rather than whichever name sorts first — a repo
+ * with a `backup` remote alongside `origin` would otherwise fetch the ledger
+ * from `backup`. A non-zero exit is *not* read as "no remote": a git that
+ * failed to answer is not evidence that a project is single-machine, and
+ * treating it as one is what lets an unreadable ledger look empty.
+ */
+async function ledgerRemote(cwd?: string): Promise<{ remote: string } | { failed: true; stderr: string } | null> {
   const rt = getRuntime();
-  const remoteResult = await rt.spawn(["git", "remote"], { cwd: opts?.cwd });
-  if (remoteResult.exitCode !== 0 || !remoteResult.stdout.trim()) return false;
+  const result = await rt.spawn(["git", "remote"], { cwd, env: C_LOCALE_ENV });
+  if (result.exitCode !== 0) return { failed: true, stderr: (result.stderr ?? "").trim() };
+  const names = result.stdout.trim().split("\n").map((n) => n.trim()).filter(Boolean);
+  if (names.length === 0) return null;
+  return { remote: names.includes("origin") ? "origin" : names[0] };
+}
+
+/** A scratch ref this module owns, used to resolve the remote tip without touching the ledger branch. */
+const PROBE_REF = "refs/chant/lifecycle-probe";
+
+/**
+ * Fetch `chant/lifecycle` and say what happened, in the terms
+ * {@link LifecycleFetchStatus} defines.
+ *
+ * The refspec is deliberately un-forced (`chant/lifecycle:chant/lifecycle`,
+ * no leading `+`), so a local branch holding facts the remote does not have is
+ * never rewound by a read.
+ *
+ * git reports "non-fast-forward" for two states that could not be more
+ * different, which is why the rejection is not taken at face value (#2309
+ * review): a local branch *ahead* of the remote — the ordinary state right
+ * after an append whose push has not landed yet — and a local branch that has
+ * genuinely *forked*. Resolving the remote tip into a scratch ref and asking
+ * whether it is an ancestor of the local tip separates them. Reading a fork as
+ * the ledger is what destroys approvals; refusing an append that is merely
+ * ahead would break the retry that is supposed to repair a failed push.
+ */
+export async function fetchLifecycleStatus(opts?: { cwd?: string }): Promise<LifecycleFetchStatus> {
+  const rt = getRuntime();
+  const cwd = opts?.cwd;
+  const found = await ledgerRemote(cwd);
+  if (found === null) return { status: "no-remote" };
+  if ("failed" in found) {
+    return { status: "unreachable", remote: "(unknown)", stderr: found.stderr };
+  }
+  const { remote } = found;
 
-  const remote = remoteResult.stdout.trim().split("\n")[0];
   const fetchResult = await rt.spawn(
     ["git", "fetch", remote, `${STATE_BRANCH}:${STATE_BRANCH}`],
-    { cwd: opts?.cwd },
+    { cwd, env: C_LOCALE_ENV },
   );
-  return fetchResult.exitCode === 0;
+  if (fetchResult.exitCode === 0) return { status: "fetched" };
+
+  const stderr = (fetchResult.stderr ?? "").trim();
+  if (NO_SUCH_REMOTE_REF_RE.test(stderr)) return { status: "absent", remote };
+  if (!NON_FAST_FORWARD_RE.test(stderr)) return { status: "unreachable", remote, stderr };
+
+  // Rejected. Resolve the remote tip into our own scratch ref (forced: the ref
+  // is this module's, and nothing reads it but the next two lines) and ask
+  // whether the local branch already contains it.
+  const probe = await rt.spawn(
+    ["git", "fetch", "--force", remote, `${STATE_BRANCH}:${PROBE_REF}`],
+    { cwd, env: C_LOCALE_ENV },
+  );
+  if (probe.exitCode !== 0) {
+    return { status: "unreachable", remote, stderr: (probe.stderr ?? "").trim() || stderr };
+  }
+  const contains = await rt.spawn(
+    ["git", "merge-base", "--is-ancestor", PROBE_REF, `refs/heads/${STATE_BRANCH}`],
+    { cwd, env: C_LOCALE_ENV },
+  );
+  await rt.spawn(["git", "update-ref", "-d", PROBE_REF], { cwd, env: C_LOCALE_ENV });
+  if (contains.exitCode === 0) return { status: "ahead", remote };
+  return { status: "diverged", remote, stderr };
+}
+
+/**
+ * Thrown when the ledger branch cannot be read, rather than being reported as
+ * empty (#2303).
+ */
+export class LifecycleLedgerUnreadableError extends Error {
+  constructor(
+    public readonly reason: "unreachable" | "diverged",
+    public readonly remote: string,
+    public readonly stderr: string,
+    detail: string,
+  ) {
+    super(
+      `the ${STATE_BRANCH} ledger branch ${detail}, so what is on it cannot be read. ` +
+        `Refusing rather than treating an unreadable ledger as an empty one.` +
+        (reason === "diverged"
+          ? `\n  Two histories claim to be the ledger; appending to either one drops the other's facts. ` +
+            `Inspect both before doing anything else:\n` +
+            `    git fetch ${remote} ${STATE_BRANCH}:refs/chant/remote-ledger\n` +
+            `    git log --oneline ${STATE_BRANCH} refs/chant/remote-ledger`
+          : `\n  Fetch it and retry: git fetch ${remote} ${STATE_BRANCH}:${STATE_BRANCH}`) +
+        (stderr ? `\n  git said: ${stderr.split("\n")[0]}` : ""),
+    );
+    this.name = "LifecycleLedgerUnreadableError";
+  }
+}
+
+/**
+ * Bring the ledger branch into this checkout before reading or appending to
+ * it, and refuse when it cannot be (#2303).
+ *
+ * The gate's read is the one that has to be right: `evaluateGate` decides
+ * whether to walk through or to record a *new* pending fact purely from what
+ * the ledger says, so a read that reports history it cannot see as an empty
+ * ledger makes the second run of an already-approved commit record a second
+ * pending fact and gate again. That is what a GitLab CI retry did on
+ * INTENTIUS/choudoufu#1026 — two pending records for one commit, with
+ * different expiries — because a GitLab checkout fetches the pipeline's own
+ * ref at depth 20 and nothing else. `GIT_DEPTH: 0` does not help: GitLab
+ * fetches refspecs, not all branches.
+ *
+ * There was a separate, laxer guard for the read until #2309's review, on the
+ * reasoning that a checkout which already has the branch "has real history to
+ * read". That reasoning is only sound when the local branch *is* the remote's
+ * history, and it let the worst case through: on a fork, the gate read a
+ * ledger missing every remote approval, recorded a fresh pending fact, and
+ * pushed. The push was not protected either — a rejected non-fast-forward
+ * fetch still updates `refs/remotes/<remote>/chant/lifecycle` opportunistically
+ * in a full clone, so `pushLifecycle`'s `--force-with-lease` matched the tip
+ * it had just learned and forced. Verified on git 2.50.1: a remote holding a
+ * pending fact and an approval ended up holding neither.
+ *
+ * So there is one rule now, for readers and writers alike:
+ *
+ * - `diverged` always refuses. A fork is not the ledger, and nothing good
+ *   comes of reading one as if it were.
+ * - `unreachable` refuses only when the checkout has no local history at all,
+ *   which is the case that would otherwise read as an empty ledger. With
+ *   local history and no answer from the remote, the read proceeds and the
+ *   push's lease fails safely on its own — refusing there would strand every
+ *   offline run.
+ * - `fetched`, `no-remote`, `absent` and `ahead` all proceed. `ahead` is the
+ *   ordinary state right after an append whose push has not landed, and is
+ *   exactly what a retry needs to be able to repair.
+ */
+export async function requireLifecycleLedger(opts?: { cwd?: string }): Promise<void> {
+  const hadLocal = (await getStateBranchTip(opts?.cwd)) !== null;
+  const result = await fetchLifecycleStatus(opts);
+
+  if (result.status === "diverged") {
+    throw new LifecycleLedgerUnreadableError(
+      "diverged",
+      result.remote,
+      result.stderr,
+      `has diverged from the copy on "${result.remote}" — neither contains the other`,
+    );
+  }
+  if (result.status === "unreachable" && !hadLocal) {
+    throw new LifecycleLedgerUnreadableError(
+      "unreachable",
+      result.remote,
+      result.stderr,
+      `is not in this checkout and could not be fetched from "${result.remote}"`,
+    );
+  }
 }
 
 // ── Generic ref CAS (#1485) ──────────────────────────────────────────────────

package/src/lifecycle/index.ts

@@ -23,3 +23,4 @@ export * from "./converge-ledger";
 export * from "./run-ledger";
 export * from "./scenario";
 export * from "./scenario-eval";
+export * from "./plan-digest";

package/src/lifecycle/plan-digest.test.ts

@@ -0,0 +1,49 @@
+import { describe, test, expect } from "vitest";
+import { computePlanDigest, isPlanDigest, describePlanDigest } from "./plan-digest";
+
+describe("computePlanDigest", () => {
+  test("the same change set digests the same, whatever order its keys arrived in", () => {
+    const a = computePlanDigest("terraform-plan", { address: "aws_s3_bucket.a", actions: ["create"] });
+    const b = computePlanDigest("terraform-plan", { actions: ["create"], address: "aws_s3_bucket.a" });
+    expect(a).toBe(b);
+  });
+
+  test("a changed address changes it", () => {
+    expect(computePlanDigest("terraform-plan", { address: "aws_s3_bucket.a" })).not.toBe(
+      computePlanDigest("terraform-plan", { address: "aws_s3_bucket.b" }),
+    );
+  });
+
+  // The kind is hashed alongside the subject so a gate bound to a terraform
+  // plan cannot be satisfied by another kind of plan that happened to
+  // serialize identically.
+  test("two kinds of plan over identical data do not collide", () => {
+    expect(computePlanDigest("terraform-plan", { x: 1 })).not.toBe(
+      computePlanDigest("lifecycle-diff", { x: 1 }),
+    );
+  });
+
+  test("it is a sha256 digest, in the shape isPlanDigest accepts", () => {
+    const digest = computePlanDigest("terraform-plan", {});
+    expect(digest).toMatch(/^sha256:[0-9a-f]{64}$/);
+    expect(isPlanDigest(digest)).toBe(true);
+  });
+});
+
+describe("isPlanDigest", () => {
+  test("refuses everything a copy-paste or a path could be", () => {
+    expect(isPlanDigest("chant.tfplan")).toBe(false);
+    expect(isPlanDigest(`sha256:${"a".repeat(63)}`)).toBe(false);
+    expect(isPlanDigest("a".repeat(64))).toBe(false);
+    expect(isPlanDigest(`sha256:${"A".repeat(64)}`)).toBe(false);
+    expect(isPlanDigest(undefined)).toBe(false);
+    expect(isPlanDigest(12)).toBe(false);
+  });
+});
+
+describe("describePlanDigest", () => {
+  test("an absent digest reads as the pre-#2300 record it is, never as undefined", () => {
+    expect(describePlanDigest(undefined)).toBe("(none — recorded before plan-bound gates)");
+    expect(describePlanDigest("sha256:abc")).toBe("sha256:abc");
+  });
+});

package/src/lifecycle/plan-digest.ts

@@ -0,0 +1,86 @@
+/**
+ * Plan identity for a gate (#2300, measured on INTENTIUS/choudoufu#1026).
+ *
+ * A gate resolution used to carry the op, the gate, the approver and a
+ * timestamp, and nothing about what was approved. Approve, edit the root,
+ * re-run, and the second run re-planned and applied: the resolution had
+ * authorised the *next run* of that op rather than the plan the approver
+ * read. This module is the missing half — one string that identifies a plan,
+ * written onto the pending fact the run records, onto the resolution `chant
+ * approve` appends, and compared by {@link latestResolutionForPlan} when a
+ * later run decides the gate.
+ *
+ * ## What a digest covers
+ *
+ * The change set, and only the change set: what a run proposes to create,
+ * update, replace or destroy, at which addresses, with which values. Two
+ * plans share a digest exactly when applying either one would do the same
+ * thing to the estate.
+ *
+ * ## What it deliberately does not cover
+ *
+ * - **When the plan was taken.** A plan file's own `timestamp`, and the
+ *   resolution's. Re-planning an unchanged root a minute later must produce
+ *   the same digest, or every approval would expire on the clock rather than
+ *   on the content.
+ * - **Which run took it.** `runId`, the CI job number, the workflow attempt.
+ *   Approving a plan and re-running the workflow is the whole loop; binding
+ *   the run id would make the approval unusable by the run that consumes it.
+ * - **The tool that produced it.** The terraform/choudoufu version, the plan
+ *   file's binary bytes and its path on disk. The digest is taken over the
+ *   `show -json` rendering rather than the file, so a plan-format bump does
+ *   not read as a changed plan.
+ * - **Who approved it, or where.** `resolvedBy`, `note`, `url` — those
+ *   describe the approval, not the plan.
+ *
+ * The identity is therefore a claim about consequence, not about provenance.
+ * That is the claim an approver is actually making.
+ */
+import { sortedJsonReplacer } from "../utils";
+import { getRuntime } from "../runtime-adapter";
+
+/** The hash a plan digest is taken with, and the prefix every digest carries. */
+export const PLAN_DIGEST_ALGORITHM = "sha256";
+
+/** Shape of a well-formed digest: `sha256:` and 64 lowercase hex characters. */
+const PLAN_DIGEST_PATTERN = /^sha256:[0-9a-f]{64}$/;
+
+/**
+ * Hash a plan's change set into a stable identity.
+ *
+ * `kind` names the shape `subject` is in (`"terraform-plan"`,
+ * `"lifecycle-diff"`), and is hashed alongside it so two different kinds of
+ * plan can never collide into the same digest by coincidence — a gate bound
+ * to a terraform plan must not be satisfiable by a lifecycle diff that
+ * happened to serialize identically.
+ *
+ * `subject` is canonicalised by {@link sortedJsonReplacer}, so object key
+ * order — which neither terraform's JSON writer nor `JSON.parse` guarantees
+ * across versions — does not change the answer. It is the caller's job to
+ * hand in a projection that already excludes the volatile fields this
+ * module's doc comment lists.
+ */
+export function computePlanDigest(kind: string, subject: unknown): string {
+  const canonical = JSON.stringify({ kind, subject }, sortedJsonReplacer);
+  return `${PLAN_DIGEST_ALGORITHM}:${getRuntime().hash(canonical)}`;
+}
+
+/**
+ * Whether `raw` is a digest this code produced. Used at the `chant approve
+ * --plan` boundary, so a typo, a truncated copy-paste or a plan *file* path
+ * is refused before it is written into an immutable resolution that would
+ * then never match anything.
+ */
+export function isPlanDigest(raw: unknown): raw is string {
+  return typeof raw === "string" && PLAN_DIGEST_PATTERN.test(raw);
+}
+
+/**
+ * A digest as it reads in a message, and the one place that decides how an
+ * absent one reads. Records written before #2300 carry no digest at all, and
+ * "(none — recorded before plan-bound gates)" is what a refusal has to say
+ * about them instead of printing `undefined`.
+ */
+export function describePlanDigest(digest: string | undefined): string {
+  return digest ?? "(none — recorded before plan-bound gates)";
+}

package/src/lifecycle/run-ledger.ts

@@ -105,6 +105,7 @@ export function buildRunRecord(
       ...(record.outcome ? { outcome: record.outcome } : {}),
       ...(record.approval ? { approval: record.approval } : {}),
       ...(record.error !== undefined ? { error: record.error } : {}),
+      ...(record.refusal !== undefined ? { refusal: record.refusal } : {}),
     });
     if (record.outcome) outcomes[record.outcome.name] = record.outcome.value;
   }