@intentius/chant 0.124.27 → 0.124.29

package/src/lifecycle/gate-change-set.ts

@@ -0,0 +1,164 @@
+/**
+ * Store the change set a gate binds (#4022), mapped onto the member's graph.
+ *
+ * {@link storeGateChangeSet} is what a gate that binds a change-set document's
+ * digest calls before it decides the gate: `components pr-apply`, and
+ * `components promote --release` before it decides a release gate or writes
+ * an `empty` resolution (#4045). It reads the member's
+ * graph the way `chant workspace graph` reads it, from the member's own
+ * `chant graph --format ir`, maps each entry onto a node
+ * (`../change-set-graph.ts`), and stores the document under its digest
+ * (`./change-set-store.ts`).
+ *
+ * Each entry mapped onto a node that has a source location also records that
+ * file from the repository root as `source` (#4025), which the overlap report
+ * in `workspace status` attributes the entry to work items by.
+ *
+ * The graph is read only when the digest is not stored yet. A graph that
+ * can't be read never stops the gate: the document is stored with `graph:
+ * null` and every `node` null, and the caller gets a warning to print.
+ */
+
+import { execFileSync, spawn } from "node:child_process";
+import { posix } from "node:path";
+import { mapChangeSetToGraph, type ChangeSetGraphNodes } from "../change-set-graph";
+import type { ChangeSetDocument, ChangeSetGraph } from "../change-set";
+import { persistChangeSet, readStoredChangeSet } from "./change-set-store";
+import { resolveMemberLedger } from "./member-ledger";
+
+/**
+ * Reads the node ids of the graph of the project at `projectDir`, with each
+ * node's source file (relative to `projectDir`) when the graph gives one.
+ */
+export type GraphIdReader = (projectDir: string) => Promise<{ ids: string[]; sources?: Record<string, string> } | { error: string }>;
+
+const GRAPH_TIMEOUT_MS = 300_000;
+
+/**
+ * The node ids of `chant graph --format ir` in `projectDir`, run under the
+ * chant that directory resolves (its own `node_modules/.bin/chant`, else this
+ * one), as `chant workspace graph` runs each member. `args` are passed after
+ * `graph --format ir`, such as the run's `--param` flags.
+ */
+export async function readGraphIds(projectDir: string, args: readonly string[] = []): Promise<{ ids: string[]; sources: Record<string, string> } | { error: string }> {
+  const { readerToolchain, resolveToolchain } = await import("../workspace/member-commands");
+  const { readMemberIr } = await import("../workspace/compose-graph");
+  const { findWorkspaceRoot } = await import("../project-root");
+  const root = findWorkspaceRoot(projectDir)?.dir ?? projectDir;
+  const toolchain = resolveToolchain(projectDir, root, readerToolchain());
+  const [command, ...pre] = toolchain.command;
+  const out = await new Promise<{ code: number | null; stdout: string; stderr: string }>((resolveRun) => {
+    const child = spawn(command, [...pre, "graph", "--format", "ir", ...args], { cwd: projectDir, stdio: ["ignore", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+    const timer = setTimeout(() => child.kill("SIGKILL"), GRAPH_TIMEOUT_MS);
+    child.stdout.on("data", (d) => (stdout += d));
+    child.stderr.on("data", (d) => (stderr += d));
+    child.on("error", (err) => {
+      clearTimeout(timer);
+      resolveRun({ code: null, stdout, stderr: err.message });
+    });
+    child.on("close", (code) => {
+      clearTimeout(timer);
+      resolveRun({ code, stdout, stderr });
+    });
+  });
+  if (out.code !== 0) {
+    const line = out.stderr.split("\n").map((l) => l.trim()).find(Boolean);
+    return { error: `chant graph --format ir exited ${out.code ?? "on a signal"}${line ? `: ${line}` : ""}` };
+  }
+  const read = readMemberIr(out.stdout);
+  if ("reason" in read) return { error: read.reason.message };
+  const sources: Record<string, string> = {};
+  for (const n of read.ir.nodes) if (n.sourceLoc?.file) sources[n.id] = n.sourceLoc.file;
+  return { ids: read.ir.nodes.map((n) => n.id), sources };
+}
+
+let graphReaderOverride: GraphIdReader | undefined;
+
+/**
+ * Replace how a gate reads the graph wherever the default is taken, such as
+ * in `components pr-apply`; `undefined` restores {@link readGraphIds}. For
+ * tests that drive a gate and read node ids in process, so they don't start a
+ * `chant graph` child process (`gate-change-set.e2e.test.ts` covers that one).
+ */
+export function setGraphIdReader(reader: GraphIdReader | undefined): void {
+  graphReaderOverride = reader;
+}
+
+/** The graph reader a gate uses: the one {@link setGraphIdReader} set, else {@link readGraphIds} with `args`. */
+export function gateGraphReader(args: readonly string[] = []): GraphIdReader {
+  return graphReaderOverride ?? ((dir) => readGraphIds(dir, args));
+}
+
+export interface StoreGateChangeSetInput {
+  /** The document whose `digest` the gate binds. */
+  doc: ChangeSetDocument;
+  /** The member's directory: where the graph is read and whose ledger it is stored in. */
+  cwd: string;
+  /** The commit the document was planned at, recorded as the graph's `at`. */
+  at?: string | null;
+  /** How to read the graph. Defaults to {@link gateGraphReader}. */
+  readGraph?: GraphIdReader;
+}
+
+export interface StoreGateChangeSetResult {
+  digest: string;
+  /** True when this call wrote the document; false when it was stored already. */
+  written: boolean;
+  /** The graph the stored document's nodes come from, null when none could be read. Absent when it was stored already. */
+  graph?: ChangeSetGraph | null;
+  /** Why no graph was read, when none was. */
+  warning?: string;
+}
+
+/**
+ * Each node's source file as a path from the repository root (#4025): the
+ * graph gives it relative to the member's directory at `cwd`. Undefined when
+ * the graph gives none or `cwd` is in no git repository.
+ */
+function repoSources(cwd: string, sources: Record<string, string> | undefined): Map<string, string> | undefined {
+  if (!sources || Object.keys(sources).length === 0) return undefined;
+  let prefix: string;
+  try {
+    prefix = execFileSync("git", ["rev-parse", "--show-prefix"], { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+  } catch {
+    return undefined;
+  }
+  const out = new Map<string, string>();
+  for (const [id, file] of Object.entries(sources)) {
+    const path = posix.normalize(posix.join(prefix, file.split("\\").join("/")));
+    if (!path.startsWith("../") && path !== "..") out.set(id, path);
+  }
+  return out;
+}
+
+/**
+ * Store `doc` under its digest in the member's ledger at `cwd`, mapped onto
+ * the member's graph, unless it is stored already. Does not push; the gate's
+ * pending fact or resolution pushes the branch after it.
+ */
+export async function storeGateChangeSet(input: StoreGateChangeSetInput): Promise<StoreGateChangeSetResult> {
+  const { doc, cwd } = input;
+  const loc = { cwd };
+  if ((await readStoredChangeSet(doc.digest, loc)).status !== "missing") return { digest: doc.digest, written: false };
+  const ledger = await resolveMemberLedger(cwd);
+  const member = ledger.members.length > 0 ? ledger.members.join("/") : null;
+  let nodes: ChangeSetGraphNodes | null = null;
+  let warning: string | undefined;
+  try {
+    const read = await (input.readGraph ?? gateGraphReader())(cwd);
+    if ("error" in read) warning = read.error;
+    else nodes = { member, at: input.at ?? null, ids: read.ids, sources: repoSources(cwd, read.sources) };
+  } catch (err) {
+    warning = err instanceof Error ? err.message : String(err);
+  }
+  const mapped = mapChangeSetToGraph(doc, nodes);
+  const { written } = await persistChangeSet(mapped, loc);
+  return {
+    digest: doc.digest,
+    written,
+    graph: mapped.graph ?? null,
+    ...(warning ? { warning: `the change set is stored without graph nodes: ${warning}` } : {}),
+  };
+}

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

@@ -503,3 +503,36 @@ describe("pending fact wave and heldBy (#3886, #3887)", () => {
     expect(pending[0]!.heldBy).toBeUndefined();
   });
 });
+
+describe("commit and run on gate records (#4020)", () => {
+  const base = { version: 1, op: "tg", gate: "g", timestamp: "2026-10-01T00:00:00Z" };
+  const parse = (...lines: Record<string, unknown>[]) => parseGateLedger(lines.map((l) => JSON.stringify(l)).join("\n"));
+  test("a pending fact and a resolution read back with their commit and run", () => {
+    const { pending, resolutions, malformed } = parse(
+      { ...base, kind: "pending", expiresAt: "2026-10-02T00:00:00Z", gitSha: "a".repeat(40), runId: "9001" },
+      { ...base, resolvedBy: "alice", gitSha: "a".repeat(40), runId: "9001" },
+    );
+    expect(malformed).toBe(0);
+    expect(pending[0]).toMatchObject({ gitSha: "a".repeat(40), runId: "9001" });
+    expect(resolutions[0]).toMatchObject({ gitSha: "a".repeat(40), runId: "9001" });
+  });
+  test("lines written before the fields existed still read, with neither", () => {
+    const { pending, resolutions, malformed } = parse(
+      { ...base, kind: "pending", expiresAt: "2026-10-02T00:00:00Z" },
+      { ...base, resolvedBy: "alice" },
+    );
+    expect(malformed).toBe(0);
+    expect(pending[0]).not.toHaveProperty("gitSha");
+    expect(resolutions[0]).not.toHaveProperty("runId");
+  });
+  test("a commit or run of the wrong type is dropped and the line is kept", () => {
+    const { pending, resolutions, malformed } = parse(
+      { ...base, kind: "pending", expiresAt: "2026-10-02T00:00:00Z", gitSha: 7, runId: { id: 1 } },
+      { ...base, resolvedBy: "alice", gitSha: ["x"] },
+    );
+    expect(malformed).toBe(0);
+    expect(pending[0]!.gitSha).toBeUndefined();
+    expect(pending[0]!.runId).toBeUndefined();
+    expect(resolutions[0]!.gitSha).toBeUndefined();
+  });
+});

package/src/lifecycle/gate-ledger.ts

@@ -47,7 +47,7 @@ import { currentGateOrigin, type GateOrigin } from "./gate-origin";
 import type { GateApprover, GatePolicyDecision, ResolvedGateApproval } from "../op/gate-approval";
 import type { GateApprovalSource } from "../op/op-waves";
 import type { GateRunLocator } from "../op/gate-run-locator";
-import { readBlobFromPath, readPathSha, readBlobBySha, writeBlobToPath, RefCASConflictError } from "./git";
+import { readBlobFromPath, readPathSha, readBlobBySha, writeBlobToPath, RefCASConflictError, type LedgerLocation } from "./git";
 
 // The facts a pending record is written with live apart, so a bundle can import them without git (#3816).
 export { DEFAULT_GATE_EXPIRY, isApprovalUrl, resolveApprovalUrl } from "./gate-pending";
@@ -138,6 +138,16 @@ export interface GateResolutionRecord {
    * such a record proves is that somebody approved *something*.
    */
   planDigest?: string;
+  /**
+   * The commit the gate was waiting on (#4020), copied off the pending fact the
+   * approval answers, or the run's own commit for a resolution a run writes
+   * itself (a decision point's answer, a review, a carried approval). It is not
+   * the approver's checkout, and a seal does not cover it. Absent on a
+   * resolution written before 0.124.28 and when no commit was known.
+   */
+  gitSha?: string;
+  /** The run the gate was waiting on (#4020), copied the same way as {@link GateResolutionRecord.gitSha}. */
+  runId?: string;
   /**
    * The checkpoint this approval lets a run resume from (#3947), copied off
    * the pending fact it answers. Set only on an approval of a gate that
@@ -151,6 +161,26 @@ export interface GateResolutionRecord {
    * recorded for its own environment and plan.
    */
   environment?: string;
+  /**
+   * The release this approval is for (#4045, ws-104 question 2), copied off
+   * the pending fact it answers. Set on a release gate, the gate `chant
+   * components promote --release` passes for an environment. A release gate
+   * counts only a resolution recorded for its own release, environment and
+   * change-set document digest (`planDigest`), so it names the release it
+   * admitted. Absent on every other gate, and on a resolution written before
+   * 0.124.28.
+   */
+  releaseDigest?: string;
+  /**
+   * The resolution passes a release gate over an empty change set (#4045,
+   * ws-104 question 6): the promote wrote it itself, with the actor running
+   * it in `resolvedBy`, because the change set its `planDigest` names changes
+   * nothing. A gate counts it only after it reads the stored document under
+   * `planDigest` and finds it empty, and neither a quorum nor a signing rule
+   * applies to it. It never counts as a person's approval. Absent on every
+   * other resolution.
+   */
+  empty?: true;
   /**
    * The channel this resolution was authored on (chant#2384) — set by the
    * writer, never by the caller. `chant approve` records `"cli"`, the
@@ -292,8 +322,19 @@ export interface PendingGateRecord {
   gate: string;
   /** The gate's human-readable description, when it declared one — what `chant operator status` shows a reader who wasn't there for the run. */
   description?: string;
-  /** The run that reached the gate, when the caller identifies its runs. */
+  /**
+   * The run that reached the gate. An Op run records its own id; a run with no
+   * id of its own (a component gate) records the CI run id when it ran in CI
+   * (#4020). Absent outside CI for a run that mints none.
+   */
   runId?: string;
+  /**
+   * The commit the run reached the gate at (#4020): the checkout's `HEAD`, else
+   * the commit the CI job started for. It is the commit the gate waits on, and
+   * `chant approve` copies it onto the resolution. Absent on a record written
+   * before 0.124.28 and when the run knew no commit.
+   */
+  gitSha?: string;
   /** ISO-8601 timestamp, caller-supplied (library code never calls `Date.now()` internally). */
   timestamp: string;
   /** ISO-8601 expiry, from the gate's `timeout` (default {@link DEFAULT_GATE_EXPIRY}). Past it, the fact is stale and a run re-records it. */
@@ -334,6 +375,13 @@ export interface PendingGateRecord {
    * can pick one.
    */
   environment?: string;
+  /**
+   * The release the run reached this gate for (#4045): on a release gate, the
+   * `releaseDigest` of the release `chant components promote --release`
+   * deploys. `chant approve` copies it onto the approval with the plan.
+   * Absent on every other gate, and on a fact written before 0.124.28.
+   */
+  releaseDigest?: string;
   /**
    * The channel the run that reached this gate was driven from (chant#2384).
    *
@@ -471,7 +519,7 @@ async function appendGateLine(
  */
 export async function readGateLedger(
   op: string,
-  opts?: { cwd?: string },
+  opts?: LedgerLocation,
 ): Promise<{ resolutions: GateResolutionRecord[]; pending: PendingGateRecord[]; malformed: number }> {
   const content = await readBlobFromPath(DIR, filename(op), opts);
   if (!content) return { resolutions: [], pending: [], malformed: 0 };
@@ -519,12 +567,29 @@ export function parseGateLedger(
         malformed++;
         continue;
       }
+      // #4045: and for the release a release gate approval is bound to.
+      const rawRelease: unknown = (parsed as { releaseDigest?: unknown }).releaseDigest;
+      if (rawRelease !== undefined && typeof rawRelease !== "string") {
+        malformed++;
+        continue;
+      }
+      // #4045: an `empty` that is not a boolean can't be told from a pass or an approval.
+      const rawEmpty: unknown = (parsed as { empty?: unknown }).empty;
+      if (rawEmpty !== undefined && typeof rawEmpty !== "boolean") {
+        malformed++;
+        continue;
+      }
       // #3947: and for the checkpoint an approval lets a run resume from.
       const rawCheckpoint: unknown = (parsed as { checkpointDigest?: unknown }).checkpointDigest;
       if (rawCheckpoint !== undefined && typeof rawCheckpoint !== "string") {
         malformed++;
         continue;
       }
+      // #4020: a commit or run id of the wrong type is dropped, so a reader can trust the type without losing the line.
+      for (const key of ["gitSha", "runId"] as const) {
+        const v: unknown = (parsed as Record<string, unknown>)[key];
+        if (v !== undefined && typeof v !== "string") delete (parsed as Record<string, unknown>)[key];
+      }
       if (parsed.kind === "pending") {
         if (typeof parsed.expiresAt !== "string") {
           malformed++;

package/src/lifecycle/git.ts

@@ -171,6 +171,21 @@ export interface LedgerFileWrite {
   expectPriorSha?: string | null;
 }
 
+/**
+ * One file for {@link writeLedgerFiles} to remove (#4036): retention's
+ * garbage collection takes a stored change set, release or template out of
+ * the tree in a new commit. The history keeps it.
+ */
+export interface LedgerFileRemoval {
+  /** The file's full path on the branch. No prefix is added. */
+  path: string;
+  remove: true;
+  /** The blob sha the caller saw at the path; a different sha, or no file, is a conflict. */
+  expectPriorSha?: string | null;
+}
+
+const isRemoval = (f: LedgerFileWrite | LedgerFileRemoval): f is LedgerFileRemoval => (f as LedgerFileRemoval).remove === true;
+
 /**
  * Write several files to the branch in one commit (#2538). Paths are full
  * branch paths, so one commit can write the ledgers of several members, for
@@ -185,9 +200,18 @@ export interface LedgerFileWrite {
  * of an unchanged directory keeps its sha.
  */
 export async function writeLedgerFiles(
-  files: LedgerFileWrite[],
+  files: Array<LedgerFileWrite | LedgerFileRemoval>,
   commitMessage: string,
-  opts?: { cwd?: string },
+  opts?: {
+    cwd?: string;
+    /**
+     * The branch tip the caller read before deciding what to write (#4036).
+     * A different tip is a conflict, thrown at once and never retried here,
+     * so a caller whose choice depends on files it does not write (garbage
+     * collection reading the gate ledgers) reads again.
+     */
+    expectTip?: string;
+  },
 ): Promise<string> {
   const rt = getRuntime();
   const cwd = opts?.cwd;
@@ -208,8 +232,13 @@ export async function writeLedgerFiles(
   // kubectl.kubernetes.io/last-applied-configuration annotation) and no
   // shell-quoting dance around embedded single quotes. Content-addressed
   // and idempotent, so this stays outside the retry loop below.
-  const blobs: { path: string; sha: string }[] = [];
+  // A removal has no blob: its sha is null, and step 3 deletes the entry.
+  const blobs: { path: string; sha: string | null }[] = [];
   for (const f of files) {
+    if (isRemoval(f)) {
+      blobs.push({ path: f.path, sha: null });
+      continue;
+    }
     const blobResult = await rt.spawn(["git", "hash-object", "-w", "--stdin"], { cwd, stdin: f.content });
     if (blobResult.exitCode !== 0) {
       throw ledgerWriteError("git hash-object", f.path, blobResult.stderr);
@@ -283,6 +312,9 @@ export async function writeLedgerFiles(
     // there instead can observe a newer tip than the listings reflect, which
     // makes the CAS succeed against a tree built from a stale read.
     const tip = await getStateBranchTip(cwd);
+    if (opts?.expectTip !== undefined && tip !== opts.expectTip) {
+      throw new RefCASConflictError(`refs/heads/${STATE_BRANCH}`, opts.expectTip, `the branch moved to ${tip ?? "(none)"} since it was read`);
+    }
     const trees = new Map<string, Map<string, TreeLine>>();
     const listing = async (dir: string): Promise<Map<string, TreeLine>> => {
       let entries = trees.get(dir);
@@ -312,16 +344,22 @@ export async function writeLedgerFiles(
     // rebuild below has each parent in hand.
     for (const b of blobs) {
       const { dir, name } = splitPath(b.path);
-      (await listing(dir)).set(name, { mode: "100644", type: "blob", sha: b.sha });
+      if (b.sha === null) (await listing(dir)).delete(name);
+      else (await listing(dir)).set(name, { mode: "100644", type: "blob", sha: b.sha });
       for (let d = dir; d !== ""; d = parentDir(d)) await listing(parentDir(d));
     }
 
-    // 4. Rebuild the touched trees, deepest first, then the root.
+    // 4. Rebuild the touched trees, deepest first, then the root. A directory
+    // a removal left empty is dropped from its parent, as git itself would.
     const touched = [...trees.keys()].sort((a, b) => depth(b) - depth(a) || (a < b ? -1 : 1));
     let rootTreeSha = "";
     for (const dir of touched) {
+      if (dir !== "" && trees.get(dir)!.size === 0) {
+        trees.get(parentDir(dir))!.delete(baseName(dir));
+        continue;
+      }
       const lines = [...trees.get(dir)!].map(([name, e]) => `${e.mode} ${e.type} ${e.sha}\t${name}`).join("\n");
-      const result = await rt.spawn(["git", "mktree"], { cwd, stdin: `${lines}\n` });
+      const result = await rt.spawn(["git", "mktree"], { cwd, stdin: lines === "" ? "" : `${lines}\n` });
       if (result.exitCode !== 0) {
         throw ledgerWriteError(`git mktree (${dir === "" ? "root" : dir})`, path, result.stderr);
       }
@@ -517,15 +555,30 @@ export async function appendReleaseRecordLine(
   recordJson: string,
   opts?: { cwd?: string },
 ): Promise<string> {
-  const filename = "releases.jsonl";
+  return appendLedgerLine(environment, "releases.jsonl", recordJson, "Release record", opts);
+}
 
+/**
+ * Append one line to `<environment>/<filename>` on the orphan branch, with
+ * the same read, append and compare-and-swap retry as
+ * {@link appendReleaseRecordLine}. The deploy outcomes of
+ * ../lifecycle/deploy-outcome.ts (#4035) are appended through here, beside
+ * the environment's `releases.jsonl`.
+ */
+export async function appendLedgerLine(
+  environment: string,
+  filename: string,
+  recordJson: string,
+  commitMessage: string,
+  opts?: { cwd?: string },
+): Promise<string> {
   let lastErr: unknown;
   for (let attempt = 1; attempt <= WRITE_BLOB_RETRY_ATTEMPTS; attempt++) {
     try {
       const priorSha = await readPathSha(environment, filename, opts);
       const existing = priorSha ? await readBlobBySha(priorSha, opts) : null;
       const content = `${existing ? `${existing.replace(/\n$/, "")}\n` : ""}${recordJson}\n`;
-      return await writeBlobToPath(environment, filename, content, "Release record", {
+      return await writeBlobToPath(environment, filename, content, commitMessage, {
         ...opts,
         expectPriorPathSha: priorSha,
       });

package/src/lifecycle/index.ts

@@ -12,6 +12,10 @@ export * from "./unobserved-gate";
 export * from "./receipt-plan";
 export * from "./affected";
 export * from "./release-ledger";
+export * from "./release-join";
+export * from "./retention-policy";
+export * from "./delivery-metrics";
+export { planLifecycleGc, runLifecycleGc, type GcFile, type GcKept, type GcKeepCode, type GcKeepReason, type GcKind, type GcReport, type LifecycleGcPlan } from "./retention";
 export * from "./build-ledger";
 export * from "./build-ledger-store";
 export * from "./oras-referrer-lookup";

package/src/lifecycle/mixed-environment.test.ts

@@ -0,0 +1,97 @@
+/**
+ * #4035: what a partly applied run records, and how a mixed environment is
+ * derived from it and the release ledger. Pure; nothing is read or written.
+ */
+
+import { describe, expect, test } from "vitest";
+import { deployOutcomeOf, parseDeployOutcomes, type DeployOutcome } from "./deploy-outcome";
+import { mixedEnvironment, rollbackTarget, unsettledComponents, type ReleaseCheck } from "./mixed-environment";
+import type { ReleaseRecord } from "./release-ledger";
+import type { PromotionPlan } from "../components/promote";
+
+const R1 = `jcs1-sha256:${"1".repeat(64)}`;
+const R2 = `jcs1-sha256:${"2".repeat(64)}`;
+const R3 = `jcs1-sha256:${"3".repeat(64)}`;
+
+const rec = (component: string, timestamp: string, releaseDigest?: string): ReleaseRecord => ({
+  version: 1, component, env: "prod", digest: `sha256:${component}-${releaseDigest?.slice(12, 13) ?? "x"}`, gitSha: "abc", runId: "r", timestamp, actor: "ci",
+  ...(releaseDigest ? { releaseDigest } : {}),
+});
+
+const plan: PromotionPlan = {
+  from: "staging",
+  to: "prod",
+  items: ["api", "web"].map((component) => ({ component, digest: `sha256:${component}`, source: rec(component, "2026-01-01T00:00:00.000Z") })),
+  notPromoted: [],
+};
+
+const outcome = (timestamp: string, components: DeployOutcome["components"], releaseDigest: string | null = R2): DeployOutcome => ({
+  version: 1, env: "prod", verb: "promote", runId: "run-9", timestamp, actor: "bob", releaseDigest, status: "fail", components,
+});
+
+const all = async (): Promise<ReleaseCheck> => ({ kept: true, revoked: false });
+const labels: Record<string, string> = { [R1]: "v1", [R2]: "v2", [R3]: "v3" };
+const label = async (d: string) => labels[d];
+
+describe("deployOutcomeOf", () => {
+  const run = (statuses: Array<"ok" | "fail" | "gated" | undefined>, status: "ok" | "fail" | "gated") => ({
+    status,
+    results: statuses.flatMap((s, i) => (s ? [{ component: plan.items[i].component, ok: s === "ok", status: s, records: [] }] : [])),
+  });
+  const of = (r: ReturnType<typeof run>) => deployOutcomeOf({ verb: "promote", plan, run: r, releaseDigest: R2, runId: "run-9", timestamp: "t", actor: "bob" });
+
+  test("records a run that deployed some components and not others, or failed", () => {
+    expect(of(run(["ok", "fail"], "fail"))?.components.map((c) => [c.component, c.outcome, c.releaseDigest])).toEqual([["api", "deployed", R2], ["web", "failed", R2]]);
+    expect(of(run(["fail", undefined], "fail"))?.components.map((c) => c.outcome)).toEqual(["failed", "not-run"]);
+    expect(of(run(["ok", "gated"], "gated"))?.status).toBe("gated");
+  });
+
+  test("records nothing for a run that deployed everything, or stopped at a gate before deploying anything", () => {
+    expect(of(run(["ok", "ok"], "ok"))).toBeNull();
+    expect(of(run(["gated", undefined], "gated"))).toBeNull();
+  });
+});
+
+describe("parseDeployOutcomes", () => {
+  test("skips a line that is not an outcome", () => {
+    const good = JSON.stringify(outcome("t", [{ component: "api", outcome: "failed", digest: "sha256:a", releaseDigest: null }]));
+    expect(parseDeployOutcomes(`${good}\nnot json\n{"version":1}\n`)).toMatchObject({ outcomes: [{ runId: "run-9" }], malformed: 2 });
+  });
+});
+
+describe("mixed environments", () => {
+  test("a failed component stays unsettled until the ledger records it after the run", () => {
+    const o = outcome("2026-01-02T00:00:00.000Z", [{ component: "api", outcome: "deployed", digest: "sha256:a", releaseDigest: R2 }, { component: "web", outcome: "failed", digest: "sha256:w", releaseDigest: R2 }]);
+    const records = [rec("api", "2026-01-01T00:00:00.000Z", R1), rec("web", "2026-01-01T00:00:00.000Z", R1), rec("api", "2026-01-02T00:00:00.000Z", R2)];
+    expect([...unsettledComponents(records, [o]).keys()]).toEqual(["web"]);
+    expect(unsettledComponents([...records, rec("web", "2026-01-03T00:00:00.000Z", R1)], [o]).size).toBe(0);
+  });
+
+  test("components on different releases are mixed, a record of no release counting as one; no release at all is not", async () => {
+    const mixed = await mixedEnvironment({ env: "prod", records: [rec("api", "2026-01-02T00:00:00.000Z", R2), rec("web", "2026-01-01T00:00:00.000Z")], outcomes: [], label, check: all });
+    expect(mixed?.components.map((c) => [c.component, c.releaseLabel, c.state])).toEqual([["api", "v2", "settled"], ["web", null, "settled"]]);
+    expect(mixed?.rollback).toBeNull();
+    expect(await mixedEnvironment({ env: "prod", records: [rec("api", "t1"), rec("web", "t1")], outcomes: [], label, check: all })).toBeNull();
+    expect(await mixedEnvironment({ env: "prod", records: [rec("api", "t1", R1), rec("web", "t1", R1)], outcomes: [], label, check: all })).toBeNull();
+  });
+
+  test("a run that failed before deploying anything leaves the environment mixed, and the rollback goes back past the release it tried", async () => {
+    const records = [rec("api", "2026-01-01T00:00:00.000Z", R1), rec("api", "2026-01-02T00:00:00.000Z", R2)];
+    const o = outcome("2026-01-03T00:00:00.000Z", [{ component: "api", outcome: "failed", digest: "sha256:a3", releaseDigest: R3 }], R3);
+    const mixed = await mixedEnvironment({ env: "prod", records, outcomes: [o], label, check: all });
+    expect(mixed).toMatchObject({
+      components: [{ component: "api", releaseLabel: "v2", state: "failed", attempt: { releaseLabel: "v3" } }],
+      redeploy: ["chant components redeploy prod --component api"],
+      rollback: "chant components rollback prod --release v2",
+    });
+  });
+
+  test("the rollback target skips a revoked release and one that is no longer kept, and honours before", async () => {
+    const records = [rec("api", "2026-01-01T00:00:00.000Z", R1), rec("api", "2026-01-02T00:00:00.000Z", R2), rec("api", "2026-01-03T00:00:00.000Z", R3)];
+    const check = async (d: string): Promise<ReleaseCheck> => ({ kept: d !== R2, revoked: false });
+    expect(await rollbackTarget({ records, exclude: new Set([R3]), check })).toBe(R1);
+    expect(await rollbackTarget({ records, exclude: new Set(), check: async (d) => ({ kept: true, revoked: d === R3 }) })).toBe(R2);
+    expect(await rollbackTarget({ records, exclude: new Set(), before: "2026-01-02T00:00:00.000Z", check: all })).toBe(R1);
+    expect(await rollbackTarget({ records, exclude: new Set([R1, R2, R3]), check: all })).toBeNull();
+  });
+});