@intentius/chant 0.124.28 → 0.124.30

package/src/lifecycle/delivery-metrics.ts

@@ -0,0 +1,263 @@
+/**
+ * The four DORA metrics of one environment's deploy records (#4039): how
+ * often it deploys, the lead time from commit to running release, the change
+ * failure rate and the time to restore.
+ *
+ * Everything here is pure. The caller reads the ledgers, the release files
+ * and the ci tags, and hands this module one environment's records with
+ * lookups for the rest; `workspace/delivery-metrics.ts` does that for
+ * `chant workspace metrics`.
+ *
+ * A deploy is one record in `<env>/releases.jsonl`: one component deployed
+ * once. A redeploy, which puts the running release back, is counted apart and
+ * is not a deploy for the metrics. A deploy fails when, within the failure window after it, the commit
+ * it deployed is revoked (a counted `ci/revoked/<sha>` tag, #4033) or the
+ * environment is rolled back from it. Which records are rollbacks, and which
+ * put the current release back, is decided in {@link rollbackOf} and
+ * {@link isRedeploy} and nowhere else, so a new kind of rollback record
+ * (#4035) changes those two functions only.
+ */
+
+import type { ReleaseRecord, ReleaseRef } from "./release-ledger";
+
+/** The failure window when the declaration's `metrics.failureWindowDays` is not set. */
+export const DEFAULT_FAILURE_WINDOW_DAYS = 7;
+
+const DAY_MS = 86_400_000;
+
+/**
+ * The earlier deploy a rollback record restores, or null when the record is
+ * not a rollback. Today a rollback is a record `chant components rollback`
+ * wrote, which names what it restores in `restores` (#2531). Every rule below
+ * that asks whether a record rolled an environment back asks this function.
+ */
+export function rollbackOf(record: Pick<ReleaseRecord, "restores">): ReleaseRef | null {
+  return record.restores ?? null;
+}
+
+/**
+ * Whether the record put the current release back (`chant components
+ * redeploy`, #2604). A redeploy deploys the same release again, so it neither
+ * restores a failed deploy nor stands between a deploy and its rollback.
+ */
+export function isRedeploy(record: Pick<ReleaseRecord, "redeploys">): boolean {
+  return record.redeploys !== undefined;
+}
+
+/** A counted revoked tag on a commit, with the time it was made, or null for a lightweight tag. */
+export interface CommitRevocation {
+  tag: string;
+  tagged: string | null;
+}
+
+/** What the caller knows beyond the records, as lookups. */
+export interface MetricsLookups {
+  /** The release a deploy record names: its `releaseDigest`, else the one its release-gate admission names. Undefined when it names none. */
+  releaseOf: (record: ReleaseRecord) => string | undefined;
+  /** The commit a release was cut from, or null when its file can't be read here. */
+  commitOfRelease: (releaseDigest: string) => string | null;
+  /** The release's label, or null. */
+  labelOf: (releaseDigest: string) => string | null;
+  /** The counted revoked tag on a commit, or null when the commit is not revoked. */
+  revocationOf: (commit: string) => CommitRevocation | null;
+  /** The commit's committer time in milliseconds, or null when the commit is not in this repository. */
+  commitTime: (commit: string) => number | null;
+}
+
+/** The span of time the metrics count deploys in. */
+export interface MetricsWindow {
+  /** ISO-8601, inclusive. */
+  since: string;
+  /** ISO-8601, inclusive. */
+  until: string;
+}
+
+/** A record named the way `restores` names one. */
+export interface DeployRef {
+  runId: string;
+  timestamp: string;
+}
+
+/** One failed deploy, and how it was restored. */
+export interface DeployFailure {
+  component: string;
+  timestamp: string;
+  runId: string;
+  /** The release the deploy came from, or null for a deploy made from no release. */
+  releaseDigest: string | null;
+  label: string | null;
+  /** The commit it deployed: the release's commit, or the record's `gitSha` for a deploy made from no release. */
+  commit: string;
+  /** Why it counts as failed: `revoked`, `rolled-back`, or both. */
+  causes: Array<"revoked" | "rolled-back">;
+  /** The revoked tag on the commit, when that is a cause. */
+  revoked: CommitRevocation | null;
+  /** The rollback record that rolled the environment back from it, when that is a cause. */
+  rolledBackBy: DeployRef | null;
+  /** The next deploy of the component in the environment whose commit is not revoked, or null while there is none. */
+  restoredBy: DeployRef | null;
+  /** Seconds from the failed deploy to `restoredBy`, or null while it is not restored. */
+  restoreSeconds: number | null;
+}
+
+/** The four metrics of one environment. */
+export interface EnvironmentMetrics {
+  env: string;
+  deployments: {
+    /** Deploy records in the window, one per component deployed, leaving out redeploys. Rollbacks count. */
+    count: number;
+    /** Redeploys in the window: records that put the running release back, counted apart from `count`. */
+    redeploys: number;
+    /** Distinct `runId` values among them, so a run that deploys several components counts once. */
+    runs: number;
+    /** Of `count`, the deploys made from a release. */
+    fromRelease: number;
+    /** `count` over the window in weeks, to two decimals. */
+    perWeek: number;
+  };
+  leadTime: {
+    /** Changes whose first deploy here falls in the window and whose commit time is known. */
+    changes: number;
+    /** Of `changes`, releases (the first deploy naming the release). */
+    fromRelease: number;
+    /** Of `changes`, commits deployed from no release (the first deploy with that `gitSha`). */
+    fromCommit: number;
+    /** Changes left out because their commit is not in this repository. */
+    unknown: number;
+    /** The median, in seconds, or null when `changes` is 0. */
+    medianSeconds: number | null;
+  };
+  changeFailure: {
+    deployments: number;
+    failed: number;
+    /** Failed deploys whose commit was revoked within the window after them. */
+    revoked: number;
+    /** Failed deploys the environment was rolled back from within the window after them. */
+    rolledBack: number;
+    /** `failed` over `deployments`, to four decimals, or null with no deployments. */
+    rate: number | null;
+  };
+  restore: {
+    restored: number;
+    open: number;
+    medianSeconds: number | null;
+  };
+  /** The failed deploys in the window, oldest first. */
+  failures: DeployFailure[];
+}
+
+function median(values: number[]): number | null {
+  if (values.length === 0) return null;
+  const s = [...values].sort((a, b) => a - b);
+  const mid = Math.floor(s.length / 2);
+  return Math.round(s.length % 2 === 1 ? s[mid] : (s[mid - 1] + s[mid]) / 2);
+}
+
+const at = (iso: string): number => Date.parse(iso);
+const ref = (r: ReleaseRecord): DeployRef => ({ runId: r.runId, timestamp: r.timestamp });
+
+/**
+ * The metrics of one environment's records. `records` is the whole ledger of
+ * the environment, every component, in ledger order: deploys before the
+ * window still decide lead times, and deploys after a failure decide its
+ * restore. Only deploys whose `timestamp` falls in `window` are counted.
+ */
+export function environmentMetrics(
+  env: string,
+  records: readonly ReleaseRecord[],
+  lookups: MetricsLookups,
+  window: MetricsWindow,
+  failureWindowDays: number = DEFAULT_FAILURE_WINDOW_DAYS,
+): EnvironmentMetrics {
+  // Ledger order breaks timestamp ties, as `latestPerComponent` does.
+  const sorted = records.map((r, i) => ({ r, i })).sort((a, b) => at(a.r.timestamp) - at(b.r.timestamp) || a.i - b.i).map((x) => x.r);
+  const since = at(window.since);
+  const until = at(window.until);
+  const failureMs = failureWindowDays * DAY_MS;
+  const inWindow = (r: ReleaseRecord) => at(r.timestamp) >= since && at(r.timestamp) <= until;
+
+  const facts = sorted.map((r) => {
+    const releaseDigest = lookups.releaseOf(r) ?? null;
+    const commit = (releaseDigest !== null ? lookups.commitOfRelease(releaseDigest) : null) ?? r.gitSha;
+    return { r, releaseDigest, commit, revocation: lookups.revocationOf(commit) };
+  });
+
+  // A redeploy puts the running release back: it is counted apart, and
+  // neither fails nor restores on its own.
+  const deployments = facts.filter((f) => inWindow(f.r) && !isRedeploy(f.r));
+  const failures: DeployFailure[] = [];
+  for (const [i, f] of facts.entries()) {
+    if (!inWindow(f.r) || isRedeploy(f.r)) continue;
+    const t = at(f.r.timestamp);
+    const later = facts.slice(i + 1).filter((g) => g.r.component === f.r.component);
+
+    // Revoked within the window after the deploy. A tag with no time, or one
+    // made before the deploy, revokes what was deployed all the same.
+    const revoked = f.revocation !== null && (f.revocation.tagged === null || at(f.revocation.tagged) - t <= failureMs) ? f.revocation : null;
+
+    // Rolled back from it: the next deploy of the component that is not a
+    // redeploy is a rollback, within the window.
+    const next = later.find((g) => !isRedeploy(g.r));
+    const rolledBack = next !== undefined && rollbackOf(next.r) !== null && at(next.r.timestamp) - t <= failureMs ? next.r : null;
+
+    if (!revoked && !rolledBack) continue;
+    const restore = later.find((g) => !isRedeploy(g.r) && g.revocation === null);
+    failures.push({
+      component: f.r.component,
+      timestamp: f.r.timestamp,
+      runId: f.r.runId,
+      releaseDigest: f.releaseDigest,
+      label: f.releaseDigest !== null ? lookups.labelOf(f.releaseDigest) : null,
+      commit: f.commit,
+      causes: [...(revoked ? (["revoked"] as const) : []), ...(rolledBack ? (["rolled-back"] as const) : [])],
+      revoked,
+      rolledBackBy: rolledBack ? ref(rolledBack) : null,
+      restoredBy: restore ? ref(restore.r) : null,
+      restoreSeconds: restore ? Math.round((at(restore.r.timestamp) - t) / 1000) : null,
+    });
+  }
+
+  // Lead time: one change per release, or per commit deployed from no
+  // release, timed at its first deploy in this environment.
+  const firstDeploy = new Map<string, (typeof facts)[number]>();
+  for (const f of facts) {
+    const key = f.releaseDigest !== null ? `release:${f.releaseDigest}` : `commit:${f.r.gitSha}`;
+    if (!firstDeploy.has(key)) firstDeploy.set(key, f);
+  }
+  const leads: number[] = [];
+  let fromRelease = 0;
+  let unknown = 0;
+  for (const f of firstDeploy.values()) {
+    if (!inWindow(f.r)) continue;
+    const committed = lookups.commitTime(f.commit);
+    if (committed === null) {
+      unknown++;
+      continue;
+    }
+    leads.push(Math.max(0, (at(f.r.timestamp) - committed) / 1000));
+    if (f.releaseDigest !== null) fromRelease++;
+  }
+
+  const weeks = Math.max(until - since, DAY_MS) / (7 * DAY_MS);
+  const restored = failures.filter((x) => x.restoreSeconds !== null);
+  return {
+    env,
+    deployments: {
+      count: deployments.length,
+      redeploys: facts.filter((f) => inWindow(f.r) && isRedeploy(f.r)).length,
+      runs: new Set(deployments.map((f) => f.r.runId)).size,
+      fromRelease: deployments.filter((f) => f.releaseDigest !== null).length,
+      perWeek: Math.round((deployments.length / weeks) * 100) / 100,
+    },
+    leadTime: { changes: leads.length, fromRelease, fromCommit: leads.length - fromRelease, unknown, medianSeconds: median(leads) },
+    changeFailure: {
+      deployments: deployments.length,
+      failed: failures.length,
+      revoked: failures.filter((x) => x.revoked !== null).length,
+      rolledBack: failures.filter((x) => x.rolledBackBy !== null).length,
+      rate: deployments.length === 0 ? null : Math.round((failures.length / deployments.length) * 10_000) / 10_000,
+    },
+    restore: { restored: restored.length, open: failures.length - restored.length, medianSeconds: median(restored.map((x) => x.restoreSeconds!)) },
+    failures,
+  };
+}

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";