@intentius/chant 0.124.28 → 0.124.29

package/src/lifecycle/deploy-outcome.ts

@@ -0,0 +1,147 @@
+/**
+ * What a promote, rollback or redeploy left behind when it did not deploy
+ * every component it planned (#4035).
+ *
+ * The release ledger records a component only once its deploy succeeded, so
+ * after a run that applied partly it still names the earlier release for
+ * every component that failed, and nothing says that component may be
+ * running part of the new one. A deploy outcome is the record of that run:
+ * one line per run in `<env>/outcomes.jsonl` on `chant/lifecycle`, beside
+ * the environment's `releases.jsonl` and under the same member prefix,
+ * naming each planned component and what happened to it.
+ *
+ * It is written only when the run ended with some components deployed and
+ * others not, or with a component that failed. A run that stopped at a gate
+ * before deploying anything changed nothing in the environment; its pending
+ * gate is what `workspace status` shows for it.
+ *
+ * The file is append-only, like the release ledger. Whether the environment
+ * is still mixed is derived when it is read ({@link ./mixed-environment.ts}):
+ * a component the outcome names as failed or gated stays unsettled until the
+ * release ledger has a newer record of it, which a redeploy, a rollback or
+ * the same promote run again writes.
+ */
+
+import { sortedJsonReplacer } from "../utils";
+import type { PromotionPlan } from "../components/promote";
+import type { DriverRunResult } from "../components/driver";
+
+/** The file a deploy outcome is appended to, under the environment's directory. */
+export const OUTCOMES_FILE = "outcomes.jsonl";
+
+/** What a run did to one component it planned. */
+export type DeployOutcomeState = "deployed" | "failed" | "gated" | "not-run";
+
+export interface DeployOutcomeComponent {
+  component: string;
+  /** `deployed` (a release record was written), `failed`, `gated` (stopped at a gate after the steps before it ran), or `not-run`. */
+  outcome: DeployOutcomeState;
+  /** The artifact digest the run was deploying. */
+  digest: string;
+  /** The release the run was deploying for this component, or null when it named none. */
+  releaseDigest: string | null;
+}
+
+/** One line of `<env>/outcomes.jsonl`. */
+export interface DeployOutcome {
+  version: 1;
+  env: string;
+  verb: "promote" | "rollback" | "redeploy";
+  /** The run id the run's release records carry. */
+  runId: string;
+  /** The timestamp the run's release records carry. */
+  timestamp: string;
+  actor: string;
+  /** The release the run deployed under (`--release`), or null. */
+  releaseDigest: string | null;
+  /** How the run ended. */
+  status: "fail" | "gated";
+  components: DeployOutcomeComponent[];
+}
+
+/**
+ * The outcome to record for a run, or null when there is nothing to record:
+ * every planned component deployed, or the run stopped at a gate with
+ * nothing deployed and nothing failed.
+ */
+export function deployOutcomeOf(input: {
+  verb: DeployOutcome["verb"];
+  plan: PromotionPlan;
+  run: Pick<DriverRunResult, "status" | "results">;
+  /** The release the run deployed under, if any. */
+  releaseDigest: string | null;
+  runId: string;
+  timestamp: string;
+  actor: string;
+}): DeployOutcome | null {
+  const { plan, run } = input;
+  if (run.status === "ok") return null;
+  const components: DeployOutcomeComponent[] = plan.items.map((item) => {
+    const result = run.results.find((r) => r.component === item.component);
+    const outcome: DeployOutcomeState = !result ? "not-run" : result.status === "ok" ? "deployed" : result.status === "gated" ? "gated" : "failed";
+    return {
+      component: item.component,
+      outcome,
+      digest: item.digest,
+      releaseDigest: input.releaseDigest ?? item.source.releaseDigest ?? null,
+    };
+  });
+  const deployed = components.some((c) => c.outcome === "deployed");
+  const failed = components.some((c) => c.outcome === "failed");
+  if (!deployed && !failed) return null;
+  return {
+    version: 1,
+    env: plan.to,
+    verb: input.verb,
+    runId: input.runId,
+    timestamp: input.timestamp,
+    actor: input.actor,
+    releaseDigest: input.releaseDigest,
+    status: run.status,
+    components,
+  };
+}
+
+const STATES: readonly string[] = ["deployed", "failed", "gated", "not-run"];
+
+function isOutcome(v: unknown): v is DeployOutcome {
+  const o = v as Partial<DeployOutcome> | null;
+  return (
+    o !== null &&
+    typeof o === "object" &&
+    o.version === 1 &&
+    typeof o.env === "string" &&
+    typeof o.runId === "string" &&
+    typeof o.timestamp === "string" &&
+    Array.isArray(o.components) &&
+    o.components.every((c) => c && typeof c.component === "string" && STATES.includes(c.outcome) && typeof c.digest === "string")
+  );
+}
+
+/** Parse the lines of an `outcomes.jsonl`, oldest first. A line that is not an outcome is counted and skipped. */
+export function parseDeployOutcomes(text: string | null): { outcomes: DeployOutcome[]; malformed: number } {
+  const outcomes: DeployOutcome[] = [];
+  let malformed = 0;
+  for (const line of (text ?? "").split("\n").map((l) => l.trim()).filter(Boolean)) {
+    try {
+      const parsed = JSON.parse(line) as unknown;
+      if (isOutcome(parsed)) outcomes.push(parsed);
+      else malformed++;
+    } catch {
+      malformed++;
+    }
+  }
+  return { outcomes, malformed };
+}
+
+/** Append one outcome to `<env>/outcomes.jsonl`. Does not push; the caller pushes with the release records. */
+export async function appendDeployOutcome(outcome: DeployOutcome, opts?: { cwd?: string }): Promise<string> {
+  const { appendLedgerLine } = await import("./git");
+  return appendLedgerLine(outcome.env, OUTCOMES_FILE, JSON.stringify(outcome, sortedJsonReplacer), "Deploy outcome", opts);
+}
+
+/** Every outcome recorded for `env`, oldest first, read where `readReleaseLedger` reads; `[]` when none is. */
+export async function readDeployOutcomes(env: string, opts?: import("./git").LedgerLocation): Promise<DeployOutcome[]> {
+  const { readBlobFromPath } = await import("./git");
+  return parseDeployOutcomes(await readBlobFromPath(env, OUTCOMES_FILE, opts)).outcomes;
+}

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

@@ -10,19 +10,27 @@
  * (`../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 { spawn } from "node:child_process";
+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`. */
-export type GraphIdReader = (projectDir: string) => Promise<{ ids: string[] } | { error: string }>;
+/**
+ * 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;
 
@@ -32,7 +40,7 @@ const GRAPH_TIMEOUT_MS = 300_000;
  * 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[] } | { error: string }> {
+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");
@@ -61,7 +69,9 @@ export async function readGraphIds(projectDir: string, args: readonly string[] =
   }
   const read = readMemberIr(out.stdout);
   if ("reason" in read) return { error: read.reason.message };
-  return { ids: read.ir.nodes.map((n) => n.id) };
+  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;
@@ -102,6 +112,27 @@ export interface StoreGateChangeSetResult {
   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
@@ -118,7 +149,7 @@ export async function storeGateChangeSet(input: StoreGateChangeSetInput): Promis
   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 };
+    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);
   }

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";
@@ -519,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 };

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();
+  });
+});