@intentius/chant 0.124.26 → 0.124.28

package/src/components/release-promote.ts

@@ -0,0 +1,232 @@
+/**
+ * A promote under a release (#4026, ws-104 question 5): the deploy reads the
+ * templates the release recorded for the target environment, not the ones in
+ * the promoting checkout.
+ *
+ * Each template a promoted component's deploy names ({@link templateRefs}) has
+ * to be one the release's target records for that component. Its bytes are
+ * read from `_releases/templates/` on `chant/lifecycle` and checked against
+ * the target's digest, the way a promote checks the publish digest, and a
+ * mismatch refuses the promote before anything runs. The bytes are written
+ * under `.chant/release-templates/<digest>/` in the member's directory and the
+ * step reads them from there. The path is relative and fixed by the digest,
+ * so a gate approval bound to the promote's plan still matches on a re-run.
+ */
+
+import { mkdirSync, readdirSync, rmSync, rmdirSync, writeFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { contentDigest } from "../content-digest";
+import type { DriverComponent, DriverGate, DriverPhase, DriverStep } from "./driver";
+import { TEMPLATE_FIELDS, templateRefs } from "./release-compile";
+import type { Release, ReleaseTarget } from "../lifecycle/release-store";
+import type { ReleaseRecord } from "../lifecycle/release-ledger";
+import type { BuildArchiveManifest } from "./verbs/build-archive";
+
+/** Where a promote under a release writes the recorded templates, relative to the member's directory. */
+export const RELEASE_TEMPLATES_DIR = ".chant/release-templates";
+
+/** A template ready to write: where, and its bytes. */
+export interface PinnedTemplate {
+  /** Relative to the member's directory. */
+  path: string;
+  content: string;
+}
+
+/** The release's target for `env`, or an error naming the environments it has. */
+export function targetFor(release: Release, env: string): { target: ReleaseTarget } | { error: string } {
+  const target = release.targets.find((t) => t.env === env);
+  if (target) return { target };
+  return {
+    error: `release ${release.releaseDigest} has no target for "${env}"; it was compiled for ${release.targets.map((t) => t.env).join(", ") || "no environment"}`,
+  };
+}
+
+/** Whether a release is of a project with no components (#4046): no artifact, and every template it records has `component: null`. */
+export function isImplicitRelease(release: Release): boolean {
+  const templates = release.targets.flatMap((t) => t.templates);
+  return release.artifactDigests.length === 0 && templates.length > 0 && templates.every((t) => t.component === null);
+}
+
+function isGate(step: DriverStep | DriverGate | DriverPhase): step is DriverGate {
+  return (step as { kind?: unknown }).kind === "gate";
+}
+
+function isPhase(step: DriverStep | DriverGate | DriverPhase): step is DriverPhase {
+  return typeof (step as { phase?: unknown }).phase === "string" && Array.isArray((step as DriverPhase).steps);
+}
+
+/**
+ * Point every template `components` read at the target's recorded bytes.
+ * Returns the rewritten compositions and the files to write, or the reasons
+ * the promote is refused: a template the target does not record, one whose
+ * bytes are missing, or one whose bytes do not hash to the target's digest.
+ */
+export async function pinReleaseTemplates(
+  components: readonly DriverComponent[],
+  release: Release,
+  target: ReleaseTarget,
+  readTemplate: (digest: string) => Promise<string | null>,
+): Promise<{ components: DriverComponent[]; files: PinnedTemplate[] } | { errors: string[] }> {
+  const errors: string[] = [];
+  const files: PinnedTemplate[] = [];
+  const out: DriverComponent[] = [];
+  for (const component of components) {
+    const replace = new Map<string, string>();
+    for (const ref of templateRefs(component)) {
+      if (replace.has(ref.value)) continue;
+      const recorded = target.templates.find((t) => t.component === component.name && t.path === ref.path);
+      if (!recorded) {
+        errors.push(
+          `component "${component.name}" reads ${ref.field} "${ref.value}", which release ${release.releaseDigest} does not record for "${target.env}"; ` +
+            `this checkout's deploy is not the one the release was compiled from (commit ${release.commit.slice(0, 12)})`,
+        );
+        continue;
+      }
+      const content = await readTemplate(recorded.digest);
+      if (content === null) {
+        errors.push(`component "${component.name}": the bytes of template "${ref.path}" (${recorded.digest}) are not on the chant/lifecycle branch; fetch it and try again`);
+        continue;
+      }
+      const got = contentDigest(content);
+      if (got !== recorded.digest) {
+        errors.push(
+          `component "${component.name}": template "${ref.path}" hashes to ${got}, but the release's target for "${target.env}" records ${recorded.digest}; refusing to deploy it`,
+        );
+        continue;
+      }
+      const path = join(RELEASE_TEMPLATES_DIR, recorded.digest.replace(/:/g, "_"), basename(ref.path));
+      files.push({ path, content });
+      replace.set(ref.value, path);
+    }
+    const rewrite = (phase: DriverPhase): DriverPhase => ({
+      ...phase,
+      steps: phase.steps.map((step) => {
+        if (isPhase(step)) return rewrite(step);
+        if (isGate(step)) return step;
+        const next: DriverStep = { ...step };
+        for (const field of TEMPLATE_FIELDS) {
+          const v = next[field];
+          if (typeof v === "string" && replace.has(v)) next[field] = replace.get(v);
+          else if (Array.isArray(v)) next[field] = v.map((x) => (typeof x === "string" && replace.has(x) ? replace.get(x) : x));
+        }
+        return next;
+      }),
+    });
+    out.push({ ...component, deploy: component.deploy.map(rewrite) });
+  }
+  return errors.length > 0 ? { errors } : { components: out, files };
+}
+
+/**
+ * The files a release's target records, read back by digest and checked, for
+ * `chant release export` (#4046). A project with no components has no deploy
+ * step for a promote to point at the recorded bytes, so its deploy (an Op such
+ * as `chant run deploy`, or a CI job) reads the files this writes instead of
+ * building them again. Each path is the one the build wrote, relative to the
+ * member's directory; a template whose bytes are missing or don't hash to the
+ * target's digest is refused, as {@link pinReleaseTemplates} refuses one.
+ */
+export async function targetFiles(
+  release: Release,
+  target: ReleaseTarget,
+  readTemplate: (digest: string) => Promise<string | null>,
+): Promise<{ files: PinnedTemplate[] } | { errors: string[] }> {
+  const errors: string[] = [];
+  const files: PinnedTemplate[] = [];
+  for (const t of target.templates) {
+    const who = t.component === null ? "" : `component "${t.component}": `;
+    if (t.path.startsWith("/") || t.path.split("/").includes("..")) {
+      errors.push(`${who}template "${t.path}" is not a path inside the member's directory; refusing to write it`);
+      continue;
+    }
+    const content = await readTemplate(t.digest);
+    if (content === null) {
+      errors.push(`${who}the bytes of template "${t.path}" (${t.digest}) are not on the chant/lifecycle branch; fetch it and try again`);
+      continue;
+    }
+    const got = contentDigest(content);
+    if (got !== t.digest) {
+      errors.push(`${who}template "${t.path}" hashes to ${got}, but release ${release.releaseDigest} records ${t.digest} for "${target.env}"; refusing to write it`);
+      continue;
+    }
+    const same = files.find((f) => f.path === t.path);
+    if (same) {
+      if (same.content !== content) errors.push(`two components record different bytes at "${t.path}" for "${target.env}", so they can't both be written there`);
+      continue;
+    }
+    files.push({ path: t.path, content });
+  }
+  return errors.length > 0 ? { errors } : { files };
+}
+
+/** Write the pinned templates under `dir`, the member's directory. */
+export function writePinnedTemplates(dir: string, files: readonly PinnedTemplate[]): void {
+  for (const f of files) {
+    const full = join(dir, f.path);
+    mkdirSync(dirname(full), { recursive: true });
+    writeFileSync(full, f.content);
+  }
+}
+
+/**
+ * Remove the templates {@link writePinnedTemplates} wrote once the promote is
+ * done, and {@link RELEASE_TEMPLATES_DIR} with them when nothing else is in
+ * it, so a promote leaves the checkout as it found it. A re-run writes them
+ * again from the release.
+ */
+export function removePinnedTemplates(dir: string, files: readonly PinnedTemplate[]): void {
+  for (const f of files) rmSync(dirname(join(dir, f.path)), { recursive: true, force: true });
+  const root = join(dir, RELEASE_TEMPLATES_DIR);
+  try {
+    if (readdirSync(root).length === 0) rmdirSync(root);
+  } catch {
+    // Already gone, or not ours to remove.
+  }
+}
+
+/**
+ * Whether the artifact a promote deploys under a release is one the release
+ * built (#4045, the rule #4026 left open). The release records build digests
+ * (`artifactDigests`, the digest the archive step returned), and a deploy
+ * record carries the publish digest, which is another value for an image, so
+ * the two are compared through the build manifest the source deploy record
+ * names (`manifestDigest`), whose entries carry build digests at the same
+ * archive paths:
+ *
+ * - a source record that names this release in `releaseDigest` matches;
+ * - else, each of the release's artifacts for the component must be in that
+ *   manifest at its path with the release's digest, and one that differs is
+ *   a mismatch;
+ * - a record with no `manifestDigest`, a manifest that isn't stored, or an
+ *   artifact path the manifest doesn't hold can't be compared.
+ *
+ * A mismatch is a warning, not a refusal. The environment promoted from was
+ * deployed by its own `run --components`, which builds again, and an image
+ * build is not reproducible, so its digest differs from the cut's for the
+ * same commit. Refusing would refuse every image promote until a deploy can
+ * run the release's own artifacts (#4043).
+ */
+export async function releaseArtifactMismatches(
+  release: Release,
+  sources: ReadonlyArray<{ component: string; source: ReleaseRecord }>,
+  readManifest: (manifestDigest: string) => Promise<BuildArchiveManifest | null>,
+): Promise<string[]> {
+  const out: string[] = [];
+  for (const { component, source } of sources) {
+    if (source.releaseDigest === release.releaseDigest) continue;
+    const artifacts = release.artifactDigests.filter((a) => a.component === component);
+    if (artifacts.length === 0 || source.manifestDigest === undefined) continue;
+    const manifest = await readManifest(source.manifestDigest);
+    if (!manifest) continue;
+    for (const a of artifacts) {
+      const entry = manifest.contents.find((e) => e.path === a.path && e.kind === a.kind);
+      if (entry && entry.digest !== a.digest) {
+        out.push(
+          `${component}: the ${source.env} deploy being promoted was built with ${a.path} at ${entry.digest}, ` +
+            `but release ${release.releaseDigest} built it at ${a.digest}, so the artifact deployed is not the release's own`,
+        );
+      }
+    }
+  }
+  return out;
+}

package/src/components/run-progress.ts

@@ -90,6 +90,13 @@ export interface RunDoneEvent {
   status: RunProgressStatus;
 }
 
+/**
+ * @deprecated Read `RunEvent` (`../run-event.ts`, exported from
+ * `@intentius/chant`) instead: one contract for Op, component and pipeline
+ * runs, with the run id, commit and runtime on every event (#4019).
+ * `runEventOfProgress` maps each of these onto it. `--progress-json` keeps
+ * printing this shape until #4041 moves it to the run-event stream.
+ */
 export type RunProgressEvent =
   | RunStartEvent
   | WaveStartEvent

package/src/components/wave-plan.ts

@@ -44,7 +44,7 @@ function emptyPart(member: WaveMember): ChangeSetPart {
 }
 
 /** Every capability step in a composition, nested phases included, gates left out. */
-function capabilitySteps(phases: readonly DriverPhase[]): DriverStep[] {
+export function capabilitySteps(phases: readonly DriverPhase[]): DriverStep[] {
   const out: DriverStep[] = [];
   const walk = (steps: DriverPhase["steps"]): void => {
     for (const step of steps) {

package/src/config.ts

@@ -22,8 +22,13 @@ import { decideConfigSchema, type DecideConfig } from "./op/decide-config";
  * silently querying real AWS. See {@link environmentName}, {@link
  * environmentNames}, {@link environmentEndpoint} below, and
  * `./live-endpoint.ts`'s `applyLiveEndpoint`, the CLI-side consumer.
+ *
+ * The array's order is the member's promotion order (#4030, see
+ * `./workspace/promotion-order.ts`), and `canary: true` marks a step as the
+ * canary step of that order. The canary is declared and surfaced; chant does
+ * not yet act on it.
  */
-export type EnvironmentDeclaration = string | { name: string; endpoint?: string };
+export type EnvironmentDeclaration = string | { name: string; endpoint?: string; canary?: boolean };
 
 /**
  * `ownership.env`: a literal environment identity, or a reference to a
@@ -124,6 +129,7 @@ const EnvironmentEntrySchema = z.union([
   z.object({
     name: z.string().min(1),
     endpoint: z.string().min(1).optional(),
+    canary: z.boolean().optional(),
   }),
 ]);
 

package/src/index.ts

@@ -153,6 +153,8 @@ export type { SymbolDeclaration, SymbolResolver } from "./workspace/symbols";
 export * from "./lsp/lexicon-providers";
 export * from "./mcp/types";
 export * from "./lifecycle/index";
+// The run-event contract (#4019): the types and the one writer of a run's stream.
+export * from "./run-event";
 // Op builders — use explicit exports to avoid collision with the core `build` function
 export { Op, phase, activity, gate, kubectlApply, helmInstall, waitForStack,
          gitlabPipeline, lifecycleSnapshot, shell, teardown, OpResource } from "./op/index";

package/src/lifecycle/change-set-store.test.ts

@@ -0,0 +1,217 @@
+/**
+ * Stored change sets (#4022) against temp git repos: the store, the gate's
+ * call that maps and stores, `chant change-set show`'s document and the link
+ * a gate in `workspace status` carries. Graph reads are injected here;
+ * `gate-change-set.e2e.test.ts` reads a real one.
+ */
+
+import { describe, expect, test } from "vitest";
+import { withTestDir } from "@intentius/chant-test-utils";
+import { spawnSync } from "node:child_process";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { composeChangeSet, lifecyclePlanPart, type ChangeSetDocument } from "../change-set";
+import type { ChangeSet as LifecycleChangeSet } from "./change-set";
+import { CHANGE_SETS_DIR, changeSetFile, ChangeSetStoreError, persistChangeSet, readStoredChangeSet } from "./change-set-store";
+import { storeGateChangeSet } from "./gate-change-set";
+import { appendPendingGate } from "./gate-ledger";
+import { writeLedgerFiles } from "./git";
+import { clearMemberLedgerCache } from "./member-ledger";
+import { changeSetShowDocument } from "../workspace/change-set-show";
+import { readMemberGates } from "../workspace/status-gates";
+import { loadAjv2020 } from "../workspace/ajv2020";
+import showSchema from "../workspace/change-set-show.schema.json";
+import changeSetSchema from "../workspace/change-set.schema.json";
+
+const plan = JSON.parse(readFileSync(join(import.meta.dirname, "..", "__fixtures__", "change-set", "lifecycle-plan.floci.json"), "utf8")) as LifecycleChangeSet;
+const doc = (): ChangeSetDocument => composeChangeSet([lifecyclePlanPart({ member: "queues", plan })]);
+
+function git(dir: string, ...args: string[]): string {
+  const r = spawnSync("git", args, { cwd: dir, encoding: "utf-8" });
+  if (r.status !== 0) throw new Error(`git ${args.join(" ")}: ${r.stderr}`);
+  return r.stdout.trim();
+}
+
+function initRepo(dir: string): string {
+  git(dir, "init", "-q", "-b", "main");
+  git(dir, "config", "user.email", "test@chant.dev");
+  git(dir, "config", "user.name", "Test");
+  writeFileSync(join(dir, "README.md"), "fixture\n");
+  git(dir, "add", ".");
+  git(dir, "commit", "-q", "-m", "init");
+  return git(dir, "rev-parse", "HEAD");
+}
+
+function validator(schema: object) {
+  const Ajv = loadAjv2020();
+  const ajv = new Ajv({ strict: false, allErrors: true }) as unknown as { compile(s: object): ((d: unknown) => boolean) & { errors?: unknown } };
+  return ajv.compile(schema);
+}
+
+describe("persistChangeSet and readStoredChangeSet", () => {
+  test("stores a document under its digest once, and reads it back", async () => {
+    await withTestDir(async (dir) => {
+      initRepo(dir);
+      const d = doc();
+      expect(await readStoredChangeSet(d.digest, { cwd: dir })).toEqual({ status: "missing" });
+      const first = await persistChangeSet(d, { cwd: dir });
+      expect(first.written).toBe(true);
+      expect(git(dir, "ls-tree", "--name-only", `chant/lifecycle:${CHANGE_SETS_DIR}`)).toBe(changeSetFile(d.digest));
+      expect(changeSetFile(d.digest)).not.toContain(":");
+      const again = await persistChangeSet(d, { cwd: dir });
+      expect(again).toEqual({ commit: null, written: false });
+      const read = await readStoredChangeSet(d.digest, { cwd: dir });
+      expect(read).toEqual({ status: "found", document: JSON.parse(JSON.stringify(d)) });
+    });
+  });
+
+  test("refuses a document that does not hash to its digest", async () => {
+    await withTestDir(async (dir) => {
+      initRepo(dir);
+      const d = doc();
+      const forged = { ...d, entries: d.entries.slice(1) };
+      await expect(persistChangeSet(forged, { cwd: dir })).rejects.toBeInstanceOf(ChangeSetStoreError);
+      await expect(persistChangeSet({ ...d, $schema: "x" } as never, { cwd: dir })).rejects.toBeInstanceOf(ChangeSetStoreError);
+    });
+  });
+
+  test("a file under a digest that is not that document reads as malformed", async () => {
+    await withTestDir(async (dir) => {
+      initRepo(dir);
+      const d = doc();
+      const other = { ...d, entries: d.entries.slice(1) };
+      await writeLedgerFiles([{ path: `${CHANGE_SETS_DIR}/${changeSetFile(d.digest)}`, content: JSON.stringify(other), expectPriorSha: null }], "forged", { cwd: dir });
+      const read = await readStoredChangeSet(d.digest, { cwd: dir });
+      expect(read.status).toBe("malformed");
+    });
+  });
+});
+
+describe("storeGateChangeSet", () => {
+  test("maps the entries onto the graph it reads, and stores in the member's ledger", async () => {
+    await withTestDir(async (dir) => {
+      initRepo(dir);
+      writeFileSync(join(dir, "chant.workspace.json"), JSON.stringify({ name: "acme", schema: 1, members: [{ name: "delivery", dir: "delivery", kind: "chant" }] }));
+      mkdirSync(join(dir, "delivery"));
+      clearMemberLedgerCache();
+      const d = doc();
+      const reads: string[] = [];
+      const stored = await storeGateChangeSet({
+        doc: d,
+        cwd: join(dir, "delivery"),
+        at: "c".repeat(40),
+        readGraph: async (at) => {
+          reads.push(at);
+          return { ids: ["jobs", "events", "dlq"] };
+        },
+      });
+      expect(stored).toEqual({ digest: d.digest, written: true, graph: { member: "delivery", at: "c".repeat(40) } });
+      expect(reads).toEqual([join(dir, "delivery")]);
+      expect(git(dir, "ls-tree", "-r", "--name-only", "chant/lifecycle")).toBe(`_members/delivery/${CHANGE_SETS_DIR}/${changeSetFile(d.digest)}`);
+
+      // Stored already: the graph is not read again.
+      expect(await storeGateChangeSet({ doc: d, cwd: join(dir, "delivery"), readGraph: async () => { throw new Error("read again"); } })).toEqual({ digest: d.digest, written: false });
+
+      // chant change-set show, from the workspace root with --member, and from the member's directory.
+      const shown = await changeSetShowDocument({ cwd: dir, digest: d.digest, member: ["delivery"] });
+      expect(validator(showSchema)(shown)).toBe(true);
+      if ("error" in shown) throw new Error(shown.error.message);
+      expect(shown.member).toBe("delivery");
+      expect(shown.reason).toBeNull();
+      expect(validator(changeSetSchema)(shown.changeSet)).toBe(true);
+      expect(shown.changeSet!.entries.map((e) => [e.address, e.node])).toEqual([
+        ["alerts", null],
+        ["dlq", "delivery/dlq"],
+        ["events", "delivery/events"],
+        ["jobs", "delivery/jobs"],
+      ]);
+      const fromMember = await changeSetShowDocument({ cwd: join(dir, "delivery"), digest: d.digest });
+      expect(fromMember).toEqual(shown);
+      // The flat ledger holds nothing under that digest.
+      const flat = await changeSetShowDocument({ cwd: dir, digest: d.digest });
+      expect(flat).toMatchObject({ member: null, changeSet: null, reason: null });
+      expect(validator(showSchema)(flat)).toBe(true);
+    });
+  });
+
+  test("a graph that can't be read stores the document with null nodes and says why", async () => {
+    await withTestDir(async (dir) => {
+      initRepo(dir);
+      clearMemberLedgerCache();
+      const d = doc();
+      const stored = await storeGateChangeSet({ doc: d, cwd: dir, readGraph: async () => ({ error: "chant graph --format ir exited 1" }) });
+      expect(stored.written).toBe(true);
+      expect(stored.graph).toBeNull();
+      expect(stored.warning).toContain("exited 1");
+      const read = await readStoredChangeSet(d.digest, { cwd: dir });
+      if (read.status !== "found") throw new Error(read.status);
+      expect(read.document.graph).toBeNull();
+      expect(read.document.entries.every((e) => e.node === null)).toBe(true);
+    });
+  });
+
+  test("show reports a malformed file and a checkout with no git", async () => {
+    await withTestDir(async (dir) => {
+      const outside = await changeSetShowDocument({ cwd: dir, digest: doc().digest });
+      expect(outside).toMatchObject({ error: { code: "not-a-git-repository" } });
+      expect(validator(showSchema)(outside)).toBe(true);
+      initRepo(dir);
+      clearMemberLedgerCache();
+      const d = doc();
+      await writeLedgerFiles([{ path: `${CHANGE_SETS_DIR}/${changeSetFile(d.digest)}`, content: "{", expectPriorSha: null }], "broken", { cwd: dir });
+      const shown = await changeSetShowDocument({ cwd: dir, digest: d.digest });
+      expect(shown).toMatchObject({ changeSet: null, reason: { code: "ledger-malformed" } });
+      expect(validator(showSchema)(shown)).toBe(true);
+    });
+  });
+});
+
+describe("a gate in workspace status links to its stored change set", () => {
+  test("a gate whose planDigest names a stored change set carries changeSet; a component gate does not", async () => {
+    await withTestDir(async (dir) => {
+      initRepo(dir);
+      clearMemberLedgerCache();
+      const d = doc();
+      await storeGateChangeSet({ doc: d, cwd: dir, readGraph: async () => ({ ids: ["jobs"] }) });
+      const now = "2026-10-16T00:00:00.000Z";
+      const later = "2026-10-17T00:00:00.000Z";
+      await appendPendingGate({ op: "pr-7", gate: "pr-apply", planDigest: d.digest, timestamp: now, expiresAt: later }, { cwd: dir });
+      const lifecyclePlan = "jcs1-sha256:" + "0".repeat(64);
+      await appendPendingGate({ op: "api", gate: "prod-approval", planDigest: lifecyclePlan, environment: "prod", timestamp: now, expiresAt: later }, { cwd: dir });
+      const commit = git(dir, "rev-parse", "chant/lifecycle");
+      const { gates } = await readMemberGates("_gates", "flat", commit, ["prod"], dir, now);
+      const byOp = Object.fromEntries(gates.map((g) => [g.component, g]));
+      expect(byOp["pr-7"]).toMatchObject({ state: "pending", planDigest: d.digest, changeSet: d.digest });
+      expect(byOp.api.planDigest).toBe(lifecyclePlan);
+      expect(byOp.api).not.toHaveProperty("changeSet");
+    });
+  });
+});
+
+describe("a release gate's stored change set (#4045)", () => {
+  test("names the release and environment it was planned for, and a release gate in status names its release", async () => {
+    await withTestDir(async (dir) => {
+      initRepo(dir);
+      clearMemberLedgerCache();
+      const releaseDigest = "jcs1-sha256:" + "a".repeat(64);
+      const d = composeChangeSet([lifecyclePlanPart({ member: "queues", plan })], { planned: { releaseDigest, environment: "prod" } });
+      await storeGateChangeSet({ doc: d, cwd: dir, readGraph: async () => ({ ids: ["jobs"] }) });
+      const read = await readStoredChangeSet(d.digest, { cwd: dir });
+      if (read.status !== "found") throw new Error(read.status);
+      expect(read.document).toMatchObject({ releaseDigest, environment: "prod" });
+      expect(validator(changeSetSchema)(read.document)).toBe(true);
+      const shown = await changeSetShowDocument({ cwd: dir, digest: d.digest });
+      expect(shown).toMatchObject({ changeSet: { releaseDigest, environment: "prod" } });
+      expect(validator(showSchema)(shown)).toBe(true);
+
+      const now = "2026-10-16T00:00:00.000Z";
+      await appendPendingGate(
+        { op: "release", gate: "prod-release", planDigest: d.digest, environment: "prod", releaseDigest, timestamp: now, expiresAt: "2026-10-17T00:00:00.000Z" },
+        { cwd: dir },
+      );
+      const commit = git(dir, "rev-parse", "chant/lifecycle");
+      const { gates } = await readMemberGates("_gates", "flat", commit, ["prod"], dir, now);
+      expect(gates).toEqual([expect.objectContaining({ component: "release", releaseDigest, changeSet: d.digest, state: "pending" })]);
+    });
+  });
+});

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

@@ -0,0 +1,112 @@
+/**
+ * Stored change sets (#4022): each change-set document a gate binds, kept on
+ * `chant/lifecycle` under its digest so the plan an approval bound can be read
+ * once the run that planned it is gone.
+ *
+ * A pull-request gate, a release gate and an `empty` resolution (ws-104
+ * question 2 and 6) bind the change-set document's `digest`
+ * (`../change-set.ts`) in `planDigest`. Only that value reaches the gate
+ * ledger, so this store keeps the document beside it:
+ *
+ *   _change-sets/<digest>.json    the document, written once and never rewritten
+ *
+ * `:` is written as `_` in the file name, as `_plans/`, `_builds/` and
+ * `_releases/` do. A workspace member's copy sits under
+ * `_members/<member>/_change-sets/` through the same `ledgerDir` prefix the
+ * gate ledger uses, so a gate and its change set are read from one member.
+ *
+ * The stored document is the one the gate bound, with each entry's graph
+ * `node` (`../change-set-graph.ts`) and the `graph` it came from. Neither is
+ * hashed, so the stored document still verifies against its digest. A
+ * component gate in a plain `run --components` binds a lifecycle-plan digest
+ * and stores nothing here.
+ *
+ * How long a stored change set is kept is #4036's retention policy.
+ */
+
+import { sortedJsonReplacer } from "../utils";
+import { CHANGE_SET_CONTRACT, CHANGE_SET_SCHEMA_ID, verifyChangeSetDigest, type ChangeSetDocument } from "../change-set";
+import { ledgerDir, readBlobFromPath, readPathSha, RefCASConflictError, writeLedgerFiles, type LedgerLocation } from "./git";
+
+/** The directory on `chant/lifecycle` that holds stored change sets. */
+export const CHANGE_SETS_DIR = "_change-sets";
+
+/** The file a change set with `digest` is stored in, inside {@link CHANGE_SETS_DIR}. */
+export function changeSetFile(digest: string): string {
+  return `${digest.replace(/:/g, "_")}.json`;
+}
+
+/** Thrown when a document can't be stored: it is not a change-set document, or its content does not hash to its digest. */
+export class ChangeSetStoreError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ChangeSetStoreError";
+  }
+}
+
+/**
+ * Store a change-set document under its digest. A document already stored
+ * under the digest is never rewritten. Refuses a document whose content does
+ * not hash to its own `digest`. Does not push: call `pushLifecycleReport`
+ * (./git.ts) after, or let the gate's own pending fact push it.
+ */
+export async function persistChangeSet(
+  doc: ChangeSetDocument,
+  opts?: { cwd?: string },
+): Promise<{ commit: string | null; written: boolean }> {
+  if (doc?.$schema !== CHANGE_SET_SCHEMA_ID || doc.contract !== CHANGE_SET_CONTRACT) {
+    throw new ChangeSetStoreError(`not a change-set document: its $schema is not ${CHANGE_SET_SCHEMA_ID} with contract ${CHANGE_SET_CONTRACT}`);
+  }
+  if (!verifyChangeSetDigest(doc)) {
+    throw new ChangeSetStoreError(`change set ${doc.digest} does not hash to its own digest; refusing to store it`);
+  }
+  const file = changeSetFile(doc.digest);
+  if ((await readPathSha(CHANGE_SETS_DIR, file, opts)) !== null) return { commit: null, written: false };
+  const dir = await ledgerDir(CHANGE_SETS_DIR, opts);
+  try {
+    const commit = await writeLedgerFiles(
+      [{ path: `${dir}/${file}`, content: `${JSON.stringify(doc, sortedJsonReplacer)}\n`, expectPriorSha: null }],
+      `Change set ${doc.digest}`,
+      opts,
+    );
+    return { commit, written: true };
+  } catch (err) {
+    // Another writer stored the same digest first; what is there is the same document.
+    if (err instanceof RefCASConflictError) return { commit: null, written: false };
+    throw err;
+  }
+}
+
+/** What reading one stored change set found. */
+export type StoredChangeSetRead =
+  | { status: "found"; document: ChangeSetDocument }
+  | { status: "missing" }
+  /** A file is stored under the digest, and it is not a change-set document whose content hashes to that digest. */
+  | { status: "malformed"; message: string };
+
+/** Parse a stored file, checking it is the document `digest` names. */
+export function parseStoredChangeSet(text: string, digest: string): StoredChangeSetRead {
+  let doc: ChangeSetDocument;
+  try {
+    doc = JSON.parse(text) as ChangeSetDocument;
+  } catch (err) {
+    return { status: "malformed", message: `the file stored under ${digest} is not JSON: ${err instanceof Error ? err.message : String(err)}` };
+  }
+  if (!doc || typeof doc !== "object" || doc.$schema !== CHANGE_SET_SCHEMA_ID || doc.contract !== CHANGE_SET_CONTRACT || !Array.isArray(doc.entries) || !Array.isArray(doc.members)) {
+    return { status: "malformed", message: `the file stored under ${digest} is not a change-set document` };
+  }
+  if (doc.digest !== digest || !verifyChangeSetDigest(doc)) {
+    return { status: "malformed", message: `the change set stored under ${digest} does not hash to that digest` };
+  }
+  return { status: "found", document: doc };
+}
+
+/**
+ * Read the change set stored under `digest`. Reads the local `chant/lifecycle`
+ * branch and never fetches. Throws only when git itself fails.
+ */
+export async function readStoredChangeSet(digest: string, opts?: LedgerLocation): Promise<StoredChangeSetRead> {
+  const text = await readBlobFromPath(CHANGE_SETS_DIR, changeSetFile(digest), opts);
+  if (text === null) return { status: "missing" };
+  return parseStoredChangeSet(text, digest);
+}

package/src/lifecycle/commit-sha.ts

@@ -0,0 +1,23 @@
+/**
+ * The commit a run, a gate or a deploy is for (#4020), as one answer for every
+ * record that carries it. The checkout's `HEAD` is what the process builds
+ * from, so it comes first; a CI job whose checkout has no git (a bare
+ * artifact job) falls back to the commit the forge says it started for.
+ * Undefined when neither is known, so a record leaves the field out rather
+ * than guessing.
+ */
+
+import { ciCommitFromEnv } from "../op/gate-run-locator";
+import { getHeadCommit } from "./git";
+
+export async function resolveCommitSha(
+  opts: { cwd?: string; env?: Record<string, string | undefined> } = {},
+): Promise<string | undefined> {
+  try {
+    const head = await getHeadCommit(opts.cwd ? { cwd: opts.cwd } : undefined);
+    if (/^[0-9a-f]{40,64}$/.test(head)) return head;
+  } catch {
+    // Not a checkout, or no git on the path: the environment may still say.
+  }
+  return ciCommitFromEnv(opts.env);
+}