@intentius/chant 0.124.27 → 0.124.28

package/src/lifecycle/release-store.ts

@@ -0,0 +1,423 @@
+/**
+ * The release (#4026, ws-104): one green commit of one member, compiled for
+ * every environment the member declares, stored on `chant/lifecycle`.
+ *
+ * A release is a different object from a deploy record. A deploy record is
+ * one line of `<env>/releases.jsonl` (./release-ledger.ts) saying a component
+ * was deployed. A release is what is cut once from a green commit and then
+ * moves through the environments: the commit, the artifacts built once from
+ * it, and one compile target per environment, each with the template digests
+ * and the build parameters that environment was compiled with.
+ *
+ * Storage, per ws-104 question 3:
+ *
+ *   _releases/<releaseDigest>.json      the release, written once and never rewritten
+ *   _releases/cuts.jsonl                one line per cut, with the release's label
+ *   _releases/templates/<digest>.txt    each template's bytes, by content digest
+ *
+ * `:` is written as `_` in file names, as `_plans/` and `_builds/` do. A
+ * workspace member's copy sits under `_members/<member>/` through the same
+ * `ledgerDir` prefix every other store uses.
+ *
+ * The template bytes are kept so that a promote under a release deploys the
+ * templates the cut recorded, not whatever the promoting checkout holds
+ * (ws-104 question 5). They are named by content digest, so a template that
+ * two environments or two releases share is stored once.
+ *
+ * `releaseDigest` is `computePlanDigest("release", subject)` over the member,
+ * the commit, the artifact digests and each target's env, templates and the
+ * name and value of each param. A param's `source`, the label, the actor, the
+ * time and any signature stay outside it, so two cuts of one commit give the
+ * same digest.
+ */
+
+import { sortedJsonReplacer } from "../utils";
+import { contentDigest } from "../content-digest";
+import { computePlanDigest } from "./plan-digest";
+import {
+  ledgerDir,
+  listFilesInDir,
+  readBlobBySha,
+  readBlobFromPath,
+  readPathSha,
+  RefCASConflictError,
+  writeLedgerFiles,
+  type LedgerFileWrite,
+  type LedgerLocation,
+} from "./git";
+import type { RunOrigin } from "./release-ledger";
+
+/** The directory on `chant/lifecycle` that holds releases, cuts and template bytes. */
+export const RELEASES_DIR = "_releases";
+/** The cut log inside {@link RELEASES_DIR}. */
+export const CUTS_FILE = "cuts.jsonl";
+/** The directory inside {@link RELEASES_DIR} that holds template bytes by content digest. */
+export const TEMPLATES_SUBDIR = "templates";
+
+/** The `kind` a release digest is computed under, so it can never equal a plan digest of another kind. */
+export const RELEASE_DIGEST_KIND = "release";
+
+/** An artifact built once from the release's commit: an `image` or `asset` archive entry. */
+export interface ReleaseArtifact {
+  component: string;
+  kind: "image" | "asset";
+  /** The archive path the build step wrote. */
+  path: string;
+  digest: string;
+}
+
+/** One template of a target: a file a component's deploy reads, compiled for the target's environment. */
+export interface ReleaseTemplate {
+  /** The component whose deploy reads it, or null for a project with no components. */
+  component: string | null;
+  /** The path the deploy step names, relative to the member's directory. */
+  path: string;
+  /** `sha256:<hex>` of the file's bytes. */
+  digest: string;
+}
+
+/** One resolved build parameter of a target. */
+export interface ReleaseParam {
+  name: string;
+  value: string | number | boolean;
+  /** Where the value came from: `cli`, `params-file`, `env` or `default`. Outside the digest. */
+  source: string;
+}
+
+/** What one environment compiles to. */
+export interface ReleaseTarget {
+  env: string;
+  templates: ReleaseTemplate[];
+  params: ReleaseParam[];
+}
+
+/** The release file, `_releases/<releaseDigest>.json`. */
+export interface Release {
+  version: 1;
+  releaseDigest: string;
+  /** The workspace member, its path of names joined with `/` when nested, or null outside a workspace. */
+  member: string | null;
+  /** The full sha of the green commit. */
+  commit: string;
+  artifactDigests: ReleaseArtifact[];
+  targets: ReleaseTarget[];
+}
+
+/** One line of `_releases/cuts.jsonl`. */
+export interface ReleaseCut {
+  version: 1;
+  releaseDigest: string;
+  /** The human name of the release, such as `v1.4.0`, or null for a cut with none. */
+  label: string | null;
+  actor: string;
+  timestamp: string;
+  /** The CI run the cut ran in, or null outside CI. */
+  runOrigin: RunOrigin | null;
+  /**
+   * The cut's signature (#4031): an armored ssh signature by the actor's key
+   * in the `chant-release` namespace over the release digest, the label, the
+   * actor and the time, one per line (`releaseSealPayload`). Null for an
+   * unsigned cut, and on every cut written before 0.124.28.
+   */
+  signature: string | null;
+}
+
+/** The parts of a release a digest is computed from. */
+export type ReleaseSubject = Pick<Release, "member" | "commit" | "artifactDigests" | "targets">;
+
+const byString = (a: string, b: string): number => (a < b ? -1 : a > b ? 1 : 0);
+
+/** The same release with every list in the order ws-104 sets: artifacts by component then path, targets by env, templates by component then path, params by name. */
+export function normalizeRelease<T extends ReleaseSubject>(release: T): T {
+  return {
+    ...release,
+    artifactDigests: [...release.artifactDigests]
+      .map(({ component, kind, path, digest }) => ({ component, kind, path, digest }))
+      .sort((a, b) => byString(a.component, b.component) || byString(a.path, b.path)),
+    targets: [...release.targets]
+      .map((t) => ({
+        env: t.env,
+        templates: [...t.templates]
+          .map(({ component, path, digest }) => ({ component, path, digest }))
+          .sort((a, b) => byString(a.component ?? "", b.component ?? "") || byString(a.path, b.path)),
+        params: [...t.params].map(({ name, value, source }) => ({ name, value, source })).sort((a, b) => byString(a.name, b.name)),
+      }))
+      .sort((a, b) => byString(a.env, b.env)),
+  };
+}
+
+/** The hash input of ws-104 question 3: a param's `source` is left out. */
+export function releaseHashInput(release: ReleaseSubject): unknown {
+  const n = normalizeRelease(release);
+  return {
+    member: n.member,
+    commit: n.commit,
+    artifactDigests: n.artifactDigests,
+    targets: n.targets.map((t) => ({ env: t.env, templates: t.templates, params: t.params.map(({ name, value }) => ({ name, value })) })),
+  };
+}
+
+/** `computePlanDigest("release", input)` over {@link releaseHashInput}. */
+export function computeReleaseDigest(release: ReleaseSubject): string {
+  return computePlanDigest(RELEASE_DIGEST_KIND, releaseHashInput(release));
+}
+
+/** A release with its digest computed and its lists in order. */
+export function makeRelease(subject: ReleaseSubject): Release {
+  const normalized = normalizeRelease(subject);
+  return { version: 1, releaseDigest: computeReleaseDigest(normalized), ...normalized };
+}
+
+/** Whether a release's own `releaseDigest` is the digest of what it holds. */
+export function verifyReleaseDigest(release: Release): boolean {
+  return release.releaseDigest === computeReleaseDigest(release);
+}
+
+const stem = (digest: string): string => digest.replace(/:/g, "_");
+const releaseFile = (digest: string): string => `${stem(digest)}.json`;
+const templateFile = (digest: string): string => `${stem(digest)}.txt`;
+
+/** A label names a release in commands such as `chant release cut <label>`, so it is one plain word. */
+const LABEL_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._+-]{0,127}$/;
+
+/** Why a label can't be used, or undefined when it can. */
+export function invalidLabel(label: string): string | undefined {
+  if (LABEL_PATTERN.test(label)) return undefined;
+  return `"${label}" is not a release label: use letters, digits and . _ + -, starting with a letter or digit, at most 128 characters`;
+}
+
+/** Thrown when a cut would give a label two digests, or a digest two labels. */
+export class ReleaseLabelError extends Error {
+  constructor(
+    readonly code: "release-label-taken" | "release-already-labelled" | "release-label-invalid",
+    message: string,
+  ) {
+    super(message);
+    this.name = "ReleaseLabelError";
+  }
+}
+
+/** A release's template bytes, as the cut read them. */
+export interface TemplateContent {
+  digest: string;
+  content: string;
+}
+
+/**
+ * Store a release and its template bytes in one commit. A release already
+ * stored under its digest is never rewritten, and a template already stored
+ * is not written again. Does not push.
+ */
+export async function persistRelease(
+  release: Release,
+  templates: readonly TemplateContent[],
+  opts?: { cwd?: string },
+): Promise<{ commit: string | null; written: boolean }> {
+  if (!verifyReleaseDigest(release)) {
+    throw new Error(`release ${release.releaseDigest} does not hash to its own digest; refusing to store it`);
+  }
+  for (const t of templates) {
+    if (contentDigest(t.content) !== t.digest) throw new Error(`template bytes do not hash to ${t.digest}; refusing to store them`);
+  }
+  const dir = await ledgerDir(RELEASES_DIR, opts);
+  const files: LedgerFileWrite[] = [];
+  const releasePath = `${dir}/${releaseFile(release.releaseDigest)}`;
+  const exists = (await readPathSha(RELEASES_DIR, releaseFile(release.releaseDigest), opts)) !== null;
+  if (!exists) files.push({ path: releasePath, content: `${JSON.stringify(release, sortedJsonReplacer)}\n`, expectPriorSha: null });
+  const seen = new Set<string>();
+  for (const t of templates) {
+    if (seen.has(t.digest)) continue;
+    seen.add(t.digest);
+    if ((await readPathSha(`${RELEASES_DIR}/${TEMPLATES_SUBDIR}`, templateFile(t.digest), opts)) !== null) continue;
+    files.push({ path: `${dir}/${TEMPLATES_SUBDIR}/${templateFile(t.digest)}`, content: t.content, expectPriorSha: null });
+  }
+  if (files.length === 0) return { commit: null, written: false };
+  try {
+    const commit = await writeLedgerFiles(files, `Release ${release.releaseDigest}`, opts);
+    return { commit, written: !exists };
+  } catch (err) {
+    // Another writer stored the same content-addressed files first.
+    if (err instanceof RefCASConflictError) return { commit: null, written: false };
+    throw err;
+  }
+}
+
+/** Parse a stored release file, or null when it is not a release. */
+export function parseRelease(text: string): Release | null {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return null;
+  }
+  if (!parsed || typeof parsed !== "object") return null;
+  const r = parsed as Partial<Release>;
+  const ok =
+    r.version === 1 &&
+    typeof r.releaseDigest === "string" &&
+    (r.member === null || typeof r.member === "string") &&
+    typeof r.commit === "string" &&
+    Array.isArray(r.artifactDigests) &&
+    r.artifactDigests.every((a) => a && typeof a.component === "string" && (a.kind === "image" || a.kind === "asset") && typeof a.path === "string" && typeof a.digest === "string") &&
+    Array.isArray(r.targets) &&
+    r.targets.every(
+      (t) =>
+        t &&
+        typeof t.env === "string" &&
+        Array.isArray(t.templates) &&
+        t.templates.every((x) => x && (x.component === null || typeof x.component === "string") && typeof x.path === "string" && typeof x.digest === "string") &&
+        Array.isArray(t.params) &&
+        t.params.every((p) => p && typeof p.name === "string" && ["string", "number", "boolean"].includes(typeof p.value) && typeof p.source === "string"),
+    );
+  return ok ? (r as Release) : null;
+}
+
+/** Read one release by digest. Null when none is stored, or when the file is not a release whose content hashes to its digest. */
+export async function readRelease(digest: string, opts?: LedgerLocation): Promise<Release | null> {
+  const text = await readBlobFromPath(RELEASES_DIR, releaseFile(digest), opts);
+  if (text === null) return null;
+  const release = parseRelease(text);
+  if (!release || release.releaseDigest !== digest || !verifyReleaseDigest(release)) return null;
+  return release;
+}
+
+/** Every stored release, and how many release files could not be read as one. */
+export async function readAllReleases(opts?: LedgerLocation): Promise<{ releases: Release[]; malformed: number }> {
+  const releases: Release[] = [];
+  let malformed = 0;
+  for (const name of await listFilesInDir(RELEASES_DIR, opts)) {
+    if (!name.endsWith(".json")) continue;
+    const digest = name.slice(0, -".json".length).replace(/_/g, ":");
+    const release = await readRelease(digest, opts);
+    if (release) releases.push(release);
+    else malformed++;
+  }
+  return { releases, malformed };
+}
+
+/** Parse the lines of `cuts.jsonl`. A line that is not a cut is counted and skipped. */
+export function parseCuts(text: string | null): { cuts: ReleaseCut[]; malformed: number } {
+  const cuts: ReleaseCut[] = [];
+  let malformed = 0;
+  for (const line of (text ?? "").split("\n").map((l) => l.trim()).filter(Boolean)) {
+    try {
+      const c = JSON.parse(line) as Partial<ReleaseCut>;
+      const ok =
+        c &&
+        c.version === 1 &&
+        typeof c.releaseDigest === "string" &&
+        (c.label === null || typeof c.label === "string") &&
+        typeof c.actor === "string" &&
+        typeof c.timestamp === "string" &&
+        (c.runOrigin === null || (typeof c.runOrigin === "object" && typeof c.runOrigin?.forge === "string")) &&
+        (c.signature === null || c.signature === undefined || typeof c.signature === "string");
+      if (!ok) {
+        malformed++;
+        continue;
+      }
+      cuts.push({ ...(c as ReleaseCut), signature: c.signature ?? null });
+    } catch {
+      malformed++;
+    }
+  }
+  return { cuts, malformed };
+}
+
+/** Every cut, oldest first. */
+export async function readCuts(opts?: LedgerLocation): Promise<{ cuts: ReleaseCut[]; malformed: number }> {
+  return parseCuts(await readBlobFromPath(RELEASES_DIR, CUTS_FILE, opts));
+}
+
+/** The label each digest carries, from its labelled cuts. */
+export function labelsByDigest(cuts: readonly ReleaseCut[]): Map<string, string> {
+  const out = new Map<string, string>();
+  for (const c of cuts) if (c.label !== null && !out.has(c.releaseDigest)) out.set(c.releaseDigest, c.label);
+  return out;
+}
+
+/** What {@link appendCut} did. */
+export type CutOutcome =
+  | { appended: true; cut: ReleaseCut }
+  /** The digest was already cut; nothing was written. `label` is the label it carries, or null. */
+  | { appended: false; label: string | null };
+
+const CUT_RETRY_ATTEMPTS = 5;
+
+/**
+ * Append a cut for `releaseDigest`. A label names one digest and a digest
+ * takes at most one label (ws-104 question 3): cutting a digest again is a
+ * no-op that returns its label, giving an unlabelled digest a label appends a
+ * cut, and cutting a digest under a label other than its own, or under a
+ * label another digest has, throws {@link ReleaseLabelError}. Does not push.
+ */
+export async function appendCut(
+  input: Omit<ReleaseCut, "version" | "signature"> & { signature?: string | null },
+  opts?: { cwd?: string },
+): Promise<CutOutcome> {
+  if (input.label !== null) {
+    const why = invalidLabel(input.label);
+    if (why) throw new ReleaseLabelError("release-label-invalid", why);
+  }
+  let lastErr: unknown;
+  for (let attempt = 1; attempt <= CUT_RETRY_ATTEMPTS; attempt++) {
+    const priorSha = await readPathSha(RELEASES_DIR, CUTS_FILE, opts);
+    const existing = priorSha ? await readBlobBySha(priorSha, opts) : null;
+    const { cuts } = parseCuts(existing);
+    const labels = labelsByDigest(cuts);
+    const own = labels.get(input.releaseDigest);
+    const alreadyCut = cuts.some((c) => c.releaseDigest === input.releaseDigest);
+    if (own !== undefined) {
+      if (input.label === null || input.label === own) return { appended: false, label: own };
+      throw new ReleaseLabelError(
+        "release-already-labelled",
+        `release ${input.releaseDigest} is already labelled "${own}", and a release takes one label`,
+      );
+    }
+    if (input.label === null && alreadyCut) return { appended: false, label: null };
+    if (input.label !== null) {
+      for (const [digest, label] of labels) {
+        if (label === input.label) {
+          throw new ReleaseLabelError("release-label-taken", `the label "${input.label}" already names release ${digest}`);
+        }
+      }
+    }
+    const cut: ReleaseCut = {
+      version: 1,
+      releaseDigest: input.releaseDigest,
+      label: input.label,
+      actor: input.actor,
+      timestamp: input.timestamp,
+      runOrigin: input.runOrigin,
+      signature: input.signature ?? null,
+    };
+    const content = `${existing ? `${existing.replace(/\n$/, "")}\n` : ""}${JSON.stringify(cut, sortedJsonReplacer)}\n`;
+    try {
+      const dir = await ledgerDir(RELEASES_DIR, opts);
+      await writeLedgerFiles([{ path: `${dir}/${CUTS_FILE}`, content, expectPriorSha: priorSha }], "Release cut", opts);
+      return { appended: true, cut };
+    } catch (err) {
+      if (!(err instanceof RefCASConflictError)) throw err;
+      lastErr = err;
+    }
+  }
+  throw lastErr;
+}
+
+/** A template's bytes by digest, or null when none is stored. */
+export async function readReleaseTemplate(digest: string, opts?: LedgerLocation): Promise<string | null> {
+  return readBlobFromPath(`${RELEASES_DIR}/${TEMPLATES_SUBDIR}`, templateFile(digest), opts);
+}
+
+/**
+ * Find a release by its digest or its label. Null when neither names one.
+ * A string that names a digest is read as a digest first.
+ */
+export async function resolveRelease(ref: string, opts?: LedgerLocation): Promise<{ release: Release; label: string | null } | null> {
+  const { cuts } = await readCuts(opts);
+  const labels = labelsByDigest(cuts);
+  let digest: string | undefined = ref.includes(":") ? ref : undefined;
+  if (!digest) for (const [d, label] of labels) if (label === ref) digest = d;
+  if (!digest) return null;
+  const release = await readRelease(digest, opts);
+  return release ? { release, label: labels.get(digest) ?? null } : null;
+}

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

@@ -92,6 +92,16 @@ describe("buildRunRecord", () => {
     expect(input.phases[1].steps.map((s) => s.status)).toEqual(["ok", "skipped"]);
   });
 
+  test("carries the commit and the CI run origin when given (#4020), and neither when not", () => {
+    const times = { started: "2026-01-01T00:00:00.000Z", ended: "2026-01-01T00:00:01.000Z", status: "ok" as const };
+    const withBoth = buildRunRecord({ name: "ship" }, [], { ...times, gitSha: "a".repeat(40), runOrigin: { forge: "github", repo: "acme/app" } });
+    expect(withBoth.gitSha).toBe("a".repeat(40));
+    expect(withBoth.runOrigin).toEqual({ forge: "github", repo: "acme/app" });
+    const without = buildRunRecord({ name: "ship" }, [], times);
+    expect(without).not.toHaveProperty("gitSha");
+    expect(without).not.toHaveProperty("runOrigin");
+  });
+
   test("a phase with a failed step is fail; a phase whose steps all skipped is skipped", () => {
     const input = buildRunRecord(
       { name: "deploy" },

package/src/lifecycle/run-ledger.ts

@@ -89,6 +89,10 @@ export function buildRunRecord(
     steward?: string;
     /** The gate the run resumed at, for a run that resumed (#3947). */
     resumed?: OpRunRecord["resumed"];
+    /** The commit the run built from (#4020). */
+    gitSha?: string;
+    /** The CI run the Op ran in (#4020), when it ran in CI. */
+    runOrigin?: OpRunRecord["runOrigin"];
     /** Each phase's wall-clock time, by name, as the executor measured it. */
     phaseDurations?: Record<string, number>;
   },
@@ -138,6 +142,8 @@ export function buildRunRecord(
     ...(times.point ? { point: times.point } : {}),
     ...(times.steward ? { steward: times.steward } : {}),
     ...(times.resumed ? { resumed: times.resumed } : {}),
+    ...(times.gitSha ? { gitSha: times.gitSha } : {}),
+    ...(times.runOrigin ? { runOrigin: times.runOrigin } : {}),
   };
 }
 

package/src/op/activities/change-coverage.ts

@@ -55,6 +55,9 @@ export async function changeCoverage(args: ChangeCoverageArgs = {}): Promise<Cha
     findings: doc.findings.map(({ code, path, message, severity, records, triage }) => ({ code, path, message, severity, records, triage })),
     summary: doc.summary,
   };
-  if (!doc.ok) throw new Error(`changeCoverage: ${doc.findings.length} change ${doc.findings.length === 1 ? "finding" : "findings"} at severity fail: ${doc.findings.map((f) => `${f.code} ${f.path}`).join(", ")}`);
+  if (!doc.ok) {
+    const all = [...doc.findings.map((f) => `${f.code} ${f.path}`), ...(doc.links?.findings ?? []).map((f) => `${f.code} ${f.commit.slice(0, 8)}`)];
+    throw new Error(`changeCoverage: ${all.length} change ${all.length === 1 ? "finding" : "findings"} at severity fail: ${all.join(", ")}`);
+  }
   return result;
 }

package/src/op/activities/source-release.ts

@@ -20,6 +20,7 @@
 
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
+import type { ReleaseAdmission } from "../../lifecycle/release-ledger";
 import { sortedJsonReplacer } from "../../utils";
 import { archiveSourceTree, sha256Digest, type SourceArchive } from "../source-archive";
 
@@ -126,16 +127,19 @@ export async function releaseRecord(args: ReleaseRecordArgs): Promise<ReleaseRec
   const env = plan.env as string;
   const gitSha = plan.gitSha as string;
 
-  const { readReleaseLedger, latestPerComponent, appendReleaseRecord, resolveRunId } = await import("../../lifecycle/release-ledger");
+  const { readReleaseLedger, latestPerComponent, appendReleaseRecord, resolveRunId, admissionOf } = await import("../../lifecycle/release-ledger");
   const { persistReleasePlan } = await import("../../lifecycle/plan-ledger");
   const { pushLifecycle } = await import("../../lifecycle/git");
 
   let approver: string | null = null;
+  let admission: ReleaseAdmission | undefined;
   if (args.approval) {
     const { readGateLedger } = await import("../../lifecycle/gate-ledger");
     const { resolutions } = await readGateLedger(args.approval.op, opts);
-    const bound = resolutions.filter((r) => r.gate === args.approval!.gate && r.planDigest === plan.digest);
-    approver = bound.length > 0 ? [...new Set(bound.map((r) => r.resolvedBy))].join(", ") : null;
+    // #4020: the approver and the gate resolution that admitted the release.
+    const admitted = admissionOf(resolutions, { ...args.approval, planDigest: plan.digest });
+    approver = admitted?.approver ?? null;
+    admission = admitted?.admission;
   }
 
   const latest = latestPerComponent((await readReleaseLedger(env, opts)).records).get(component);
@@ -160,6 +164,7 @@ export async function releaseRecord(args: ReleaseRecordArgs): Promise<ReleaseRec
       timestamp: new Date().toISOString(),
       actor,
       ...(approver ? { approver } : {}),
+      ...(admission ? { admission } : {}),
     },
     opts,
   );

package/src/op/activities/source-rollback.ts

@@ -24,7 +24,7 @@
 import { execFileSync } from "node:child_process";
 import { realpathSync } from "node:fs";
 import { join, resolve } from "node:path";
-import type { ReleaseRecord, ReleaseRef } from "../../lifecycle/release-ledger";
+import type { ReleaseAdmission, ReleaseRecord, ReleaseRef } from "../../lifecycle/release-ledger";
 import { archiveSourceTree } from "../source-archive";
 import { readReleasePlan, releasePlan, releasePlanDigest } from "./source-release";
 
@@ -200,15 +200,18 @@ export async function releaseRollbackRecord(args: ReleaseRollbackRecordArgs): Pr
   const env = plan.env as string;
   const gitSha = plan.gitSha as string;
 
-  const { readReleaseLedger, latestPerComponent, appendReleaseRecord, resolveRunId } = await import("../../lifecycle/release-ledger");
+  const { readReleaseLedger, latestPerComponent, appendReleaseRecord, resolveRunId, admissionOf } = await import("../../lifecycle/release-ledger");
   const { pushLifecycle } = await import("../../lifecycle/git");
 
   let approver: string | null = null;
+  let admission: ReleaseAdmission | undefined;
   if (args.approval) {
     const { readGateLedger } = await import("../../lifecycle/gate-ledger");
     const { resolutions } = await readGateLedger(args.approval.op, opts);
-    const bound = resolutions.filter((r) => r.gate === args.approval!.gate && r.planDigest === plan.digest);
-    approver = bound.length > 0 ? [...new Set(bound.map((r) => r.resolvedBy))].join(", ") : null;
+    // #4020: the approver and the gate resolution that admitted the release.
+    const admitted = admissionOf(resolutions, { ...args.approval, planDigest: plan.digest });
+    approver = admitted?.approver ?? null;
+    admission = admitted?.admission;
   }
 
   const latest = latestPerComponent((await readReleaseLedger(env, opts)).records.filter((r) => r.component === component)).get(component);
@@ -230,6 +233,7 @@ export async function releaseRollbackRecord(args: ReleaseRollbackRecordArgs): Pr
       timestamp: new Date().toISOString(),
       actor,
       ...(approver ? { approver } : {}),
+      ...(admission ? { admission } : {}),
       restores: rollback.restores,
     },
     opts,

package/src/op/commit-run-gate-deploy-join.test.ts

@@ -0,0 +1,117 @@
+/**
+ * A gated deploy leaves four records that name each other (#4020): the run
+ * record, the pending gate fact, the resolution and the release record. From
+ * any one of them, the other three are one lookup away, by the commit sha, the
+ * run id or the gate.
+ */
+import { describe, test, expect, afterEach, vi } from "vitest";
+import type { ActivityFn, ActivityProfile } from "./activity-registry";
+import type { OpConfig } from "./types";
+import { runOpLocally } from "./local-executor";
+import { memoryGateLedgerPort } from "./gate";
+import { resolveGateRunLocator, runOriginOfLocator } from "./gate-run-locator";
+import { admissionOf, resolveRunId, type ReleaseRecord } from "../lifecycle/release-ledger";
+import type { GateResolutionRecord } from "../lifecycle/gate-ledger";
+
+const SHA = "c0ffee".repeat(6) + "c0ff";
+const PROFILES: Record<string, ActivityProfile> = { single: { timeout: "5m", retry: { maximumAttempts: 1 } } };
+const NOW = "2026-10-16T10:00:00.000Z";
+const CI = {
+  GITHUB_ACTIONS: "true",
+  GITHUB_REPOSITORY: "acme/app",
+  GITHUB_RUN_ID: "9001",
+  GITHUB_SERVER_URL: "https://github.example",
+  GITHUB_API_URL: "https://github.example/api/v3",
+};
+
+afterEach(() => vi.unstubAllEnvs());
+
+const config: OpConfig = {
+  name: "ship",
+  overview: "",
+  labels: { Env: "prod" },
+  phases: [
+    { name: "Build", steps: [{ kind: "activity", fn: "build" }] },
+    { name: "Release", steps: [{ kind: "gate", gate: "approve-release" }, { kind: "activity", fn: "release" }] },
+  ],
+};
+const activities = new Map<string, ActivityFn>([
+  ["build", async () => undefined],
+  ["release", async () => undefined],
+]);
+
+describe("a gated deploy: commit, run, gate and deploy record join (#4020)", () => {
+  test("each record names the commit, and the run, gate and deploy name one another", async () => {
+    for (const [k, v] of Object.entries(CI)) vi.stubEnv(k, v);
+    const port = memoryGateLedgerPort();
+
+    // 1. The run reaches the gate and stops. Its record and the pending fact carry the commit.
+    const first = await runOpLocally(config, activities, PROFILES, undefined, { gates: port, now: NOW, commit: SHA });
+    expect(first.status).toBe("gated");
+    const run = first.record;
+    const pending = port.appended[0]!;
+    expect(run.gitSha).toBe(SHA);
+    expect(run.runOrigin).toEqual({ forge: "github", repo: "acme/app", url: "https://github.example/acme/app/actions/runs/9001" });
+    expect(pending.gitSha).toBe(SHA);
+    expect(pending.runId).toBe(run.id);
+
+    // 2. Someone approves. `chant approve` copies the commit and run off the pending fact it answers.
+    const resolution: GateResolutionRecord = {
+      version: 1, op: pending.op, gate: pending.gate, resolvedBy: "alice", timestamp: "2026-10-16T10:05:00.000Z",
+      gitSha: pending.gitSha, runId: pending.runId,
+    };
+    const second = await runOpLocally(config, activities, PROFILES, undefined, {
+      gates: memoryGateLedgerPort({ pending: [pending], resolutions: [resolution] }),
+      now: "2026-10-16T10:06:00.000Z",
+      commit: SHA,
+    });
+    expect(second.status).toBe("ok");
+
+    // 3. The release activity records the deploy, naming the gate that admitted it.
+    const admitted = admissionOf([resolution], { op: "ship", gate: "approve-release" })!;
+    const ci = resolveRunId();
+    const release: ReleaseRecord = {
+      version: 1, component: "site", env: "prod", digest: `sha256:${"d".repeat(64)}`, gitSha: SHA,
+      runId: ci.runId, runOrigin: ci.runOrigin, timestamp: "2026-10-16T10:07:00.000Z", actor: "ci",
+      approver: admitted.approver, admission: admitted.admission,
+    };
+
+    // From the commit: the run, the gate and the deploy.
+    const byCommit = {
+      runs: [run, second.record].filter((r) => r.gitSha === SHA),
+      pending: port.appended.filter((p) => p.gitSha === SHA),
+      resolutions: [resolution].filter((r) => r.gitSha === SHA),
+      releases: [release].filter((r) => r.gitSha === SHA),
+    };
+    expect(byCommit.runs.map((r) => r.id)).toContain(run.id);
+    expect(byCommit.pending).toEqual([pending]);
+    expect(byCommit.resolutions).toEqual([resolution]);
+    expect(byCommit.releases).toEqual([release]);
+
+    // From the run: its gate, by run id, and the CI run it ran in.
+    expect(run.gate).toMatchObject({ name: pending.gate });
+    expect(resolution.runId).toBe(run.id);
+    expect(pending.runId).toBe(run.id);
+
+    // From the deploy: the gate resolution that admitted it, the approver, and the CI run the run was in.
+    expect(release.admission).toEqual({ op: pending.op, gate: pending.gate, resolvedAt: resolution.timestamp });
+    expect(release.approver).toBe(resolution.resolvedBy);
+    expect(release.runOrigin).toEqual(run.runOrigin);
+    expect(release.runId).toBe(runOriginOfLocator(resolveGateRunLocator()!).runId);
+    expect(release.gitSha).toBe(run.gitSha);
+  });
+
+  test("a run outside CI records its commit and no run origin", async () => {
+    for (const k of ["GITHUB_RUN_ID", "CI_PIPELINE_ID"]) vi.stubEnv(k, "");
+    const result = await runOpLocally(config, activities, PROFILES, undefined, { gates: memoryGateLedgerPort(), now: NOW, commit: SHA });
+    expect(result.record.gitSha).toBe(SHA);
+    expect(result.record).not.toHaveProperty("runOrigin");
+  });
+
+  test("admissionOf names the newest of several approvals and joins their approvers", () => {
+    const at = (resolvedBy: string, timestamp: string): GateResolutionRecord => ({ version: 1, op: "ship", gate: "g", resolvedBy, timestamp, planDigest: "p" });
+    expect(admissionOf([at("a", "2026-01-01T00:00:00Z"), at("b", "2026-01-02T00:00:00Z"), at("a", "2026-01-03T00:00:00Z")], { op: "ship", gate: "g", planDigest: "p" }))
+      .toEqual({ approver: "a, b", admission: { op: "ship", gate: "g", resolvedAt: "2026-01-03T00:00:00Z" } });
+    expect(admissionOf([at("a", "2026-01-01T00:00:00Z")], { op: "ship", gate: "g", planDigest: "other" })).toBeUndefined();
+  });
+});