@intentius/chant 0.124.28 → 0.124.29

package/src/cli/handlers/fan-out.test.ts

@@ -233,7 +233,8 @@ describe("proof: a plan-only invocation prints the derivation and dispatches not
 
       ran = [];
       stderrLines = [];
-      expect(await runComponentsFanOut(ctx({ base: "main", resume, dryRun: true }))).toBe(0);
+      // The same environment: progress is bound to it (#4081).
+      expect(await runComponentsFanOut(ctx({ base: "main", env: "test", resume, dryRun: true }))).toBe(0);
 
       expect(ran).toEqual([]);
       const out = stderr();
@@ -656,6 +657,46 @@ describe("--events-json (#4041)", () => {
     expect(events.at(-1)).toMatchObject({ type: "run-settle", status: "failed" });
   });
 
+  test("a component behind a failure settles blocked, naming it, after the failing wave and before the next starts (#4007)", async () => {
+    failing = ["cluster-a"];
+    expect(await runComponentsFanOut(ctx({ base: "main", env: "test", eventsJson: true }))).toBe(1);
+    const events = checkRunEventLines(lines());
+    const blocked = events.filter((e) => e.type === "component-settle" && e.status === "blocked");
+    expect(blocked.map((e) => ({ wave: (e as { wave: number }).wave, component: (e as { component: string }).component, blockedBy: (e as { blockedBy?: string }).blockedBy }))).toEqual([
+      { wave: 3, component: "app-one", blockedBy: "cluster-a" },
+      { wave: 3, component: "app-two", blockedBy: "cluster-a" },
+    ]);
+    const wave2Settle = events.findIndex((e) => e.type === "wave-settle" && e.wave === 2);
+    const wave3Start = events.findIndex((e) => e.type === "wave-start" && e.wave === 3);
+    expect(events.indexOf(blocked[0]!)).toBeGreaterThan(wave2Settle);
+    expect(events.indexOf(blocked[1]!)).toBeLessThan(wave3Start);
+    // A blocked component never starts.
+    expect(events.some((e) => e.type === "component-start" && e.component === "app-one")).toBe(false);
+  });
+
+  test("a resumed fan-out settles what the earlier attempt applied as already-applied, in the derivation's waves (#4007)", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "fan-out-"));
+    try {
+      const resume = join(dir, "attempt.json");
+      failing = ["cluster-a"];
+      expect(await runComponentsFanOut(ctx({ base: "main", env: "test", resume }))).toBe(1);
+      failing = [];
+      stdoutLines = [];
+      expect(await runComponentsFanOut(ctx({ base: "main", env: "test", resume, eventsJson: true }))).toBe(0);
+      const events = checkRunEventLines(lines());
+      const firstWave = events.findIndex((e) => e.type === "wave-start");
+      const applied = events.filter((e) => e.type === "component-settle" && e.status === "already-applied");
+      expect(applied.map((e) => [(e as { component: string }).component, (e as { wave: number }).wave])).toEqual([["app-three", 3], ["cluster-b", 2], ["net", 1]]);
+      for (const e of applied) expect(events.indexOf(e)).toBeLessThan(firstWave);
+      // --progress-json never printed them, and still does not.
+      stdoutLines = [];
+      expect(await runComponentsFanOut(ctx({ base: "main", env: "test", resume, progressJson: true }))).toBe(0);
+      expect(stdoutLines.filter((l) => l.startsWith('{"type"')).map((l) => JSON.parse(l).type)).toEqual(["run-start", "run-done"]);
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+
   test("--progress-json on a set the gate stops now prints run-start and run-done gated (a level-0 change)", async () => {
     expect(await runComponentsFanOut(ctx({ base: "main", env: "test", gate: "release", progressJson: true }))).toBe(3);
     const progress = stdoutLines.filter((l) => l.startsWith('{"type"')).map((l) => JSON.parse(l));
@@ -670,3 +711,141 @@ describe("--events-json (#4041)", () => {
     expect(stderr()).toContain("--events-json and --progress-json both stream to stdout");
   });
 });
+
+describe("progress carries only for an unchanged input (#4081)", () => {
+  /** The estate with each component deploying a built template from `templates/`, read relative to the project. */
+  const templated = ESTATE.map((c) => ({
+    ...c,
+    deploy: [{ phase: "Apply", steps: [{ kind: "cfn-deploy", stack: `${c.name}-stack`, template: `templates/${c.name}.json` }] }],
+  }));
+  let dir: string;
+  const writeTemplate = (name: string, body: unknown) =>
+    writeFile(join(dir, "templates", `${name}.json`), JSON.stringify(body));
+
+  beforeEach(async () => {
+    dir = await mkdtemp(join(tmpdir(), "fan-out-inputs-"));
+    const { mkdir } = await import("node:fs/promises");
+    await mkdir(join(dir, "templates"));
+    for (const c of templated) await writeTemplate(c.name, { Resources: { [c.name]: { Type: "AWS::SNS::Topic" } } });
+    // The project is the temp directory, so the templates are read from there and nothing touches the checkout.
+    vi.spyOn(process, "cwd").mockReturnValue(dir);
+    discoverComponentsMock.mockResolvedValue({
+      components: new Map(templated.map((c) => [c.name, { component: c, exportName: c.name, filePath: `${c.name}.component.ts` }])),
+      sourceFiles: [],
+      errors: [],
+    });
+  });
+  afterEach(async () => {
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  test("same shape, changed content: a stale record does not skip the components whose input moved", async () => {
+    const resume = join(dir, "attempt.json");
+    expect(await runComponentsFanOut(ctx({ base: "main", env: "test", resume }))).toBe(0);
+    const first = JSON.parse(await readFile(resume, "utf8"));
+    expect(first.completed).toEqual(["app-one", "app-three", "app-two", "cluster-a", "cluster-b", "net"]);
+    expect(Object.keys(first.inputs).sort()).toEqual(first.completed);
+    const digest = /plan: (jcs1-sha256:[0-9a-f]{64})/.exec(stderr())?.[1];
+
+    // The next change: net's topic gets a display name and cluster-a a queue.
+    // Same components, same edges, so the same plan digest.
+    await writeTemplate("net", { Resources: { net: { Type: "AWS::SNS::Topic", Properties: { DisplayName: "estate" } } } });
+    await writeTemplate("cluster-a", { Resources: { "cluster-a": { Type: "AWS::SNS::Topic" }, events: { Type: "AWS::SQS::Queue" } } });
+    ran = [];
+    stderrLines = [];
+    expect(await runComponentsFanOut(ctx({ base: "main", env: "test", resume }))).toBe(0);
+
+    expect([...ran].sort()).toEqual(["app-one", "app-three", "app-two", "cluster-a", "cluster-b", "net"]);
+    const out = stderr();
+    expect(out).toContain(`plan: ${digest}`);
+    expect(out).toContain("net: changed since the earlier attempt, so it runs again");
+    expect(out).toContain("cluster-a: changed since the earlier attempt, so it runs again");
+    // Downstream of net, so its parameters read a changed upstream.
+    expect(out).toContain("app-three: changed since the earlier attempt, so it runs again");
+    expect(out).not.toMatch(/already-applied/);
+    expect(out).toContain("fan-out completed: 6 applied, 0 failed, 0 blocked");
+    const second = JSON.parse(await readFile(resume, "utf8"));
+    expect(second.inputs.net).not.toBe(first.inputs.net);
+    expect(second.inputs["cluster-b"]).not.toBe(first.inputs["cluster-b"]);
+  });
+
+  test("a change below the root reruns only its own subtree", async () => {
+    const resume = join(dir, "attempt.json");
+    expect(await runComponentsFanOut(ctx({ base: "main", env: "test", resume }))).toBe(0);
+    await writeTemplate("cluster-a", { Resources: { "cluster-a": { Type: "AWS::SNS::Topic" }, events: { Type: "AWS::SQS::Queue" } } });
+    ran = [];
+    stderrLines = [];
+    expect(await runComponentsFanOut(ctx({ base: "main", env: "test", resume }))).toBe(0);
+    expect(ran).toEqual(["cluster-a", "app-one", "app-two"]);
+    expect(stderr()).toMatch(/cluster-b +already-applied/);
+    expect(stderr()).not.toContain("net: changed");
+  });
+
+  test("the README's fail-then-fix: the fix reruns the failed subtree and the rest stay already-applied", async () => {
+    const resume = join(dir, "attempt.json");
+    failing = ["cluster-a"];
+    await writeTemplate("cluster-a", { Resources: { events: { Type: "AWS::SQS::Queue", Properties: { FifoQueue: true, QueueName: "events" } } } });
+    expect(await runComponentsFanOut(ctx({ base: "main", env: "test", resume }))).toBe(1);
+    const digest = /plan: (jcs1-sha256:[0-9a-f]{64})/.exec(stderr())?.[1];
+
+    // The fix changes cluster-a's template, which never applied.
+    failing = [];
+    await writeTemplate("cluster-a", { Resources: { events: { Type: "AWS::SQS::Queue", Properties: { FifoQueue: true, QueueName: "events.fifo" } } } });
+    ran = [];
+    stderrLines = [];
+    expect(await runComponentsFanOut(ctx({ base: "main", env: "test", resume }))).toBe(0);
+    expect(ran).toEqual(["cluster-a", "app-one", "app-two"]);
+    const out = stderr();
+    expect(out).toContain(`plan: ${digest}`);
+    expect(out).not.toContain("changed since the earlier attempt");
+    for (const name of ["net", "cluster-b", "app-three"]) expect(out).toMatch(new RegExp(`${name} +already-applied`));
+    expect(out).toContain("fan-out completed: 3 applied, 0 failed, 0 blocked");
+  });
+
+  test("the fix keeps the approval: approval binds the derivation, progress binds the inputs", async () => {
+    const resume = join(dir, "attempt.json");
+    failing = ["cluster-a"];
+    expect(await runComponentsFanOut(ctx({ base: "main", env: "test", gate: "release", resume }))).toBe(3);
+    const pending = gateLedger.appended[0]!;
+    gateLedger = memoryGateLedgerPort({
+      pending: [pending],
+      resolutions: [
+        {
+          version: 1,
+          kind: "resolution",
+          op: "fan-out",
+          gate: "release",
+          resolvedBy: "operator",
+          timestamp: new Date(Date.parse(pending.timestamp) + 1000).toISOString(),
+          planDigest: pending.planDigest,
+        },
+      ],
+    });
+    expect(await runComponentsFanOut(ctx({ base: "main", env: "test", gate: "release", resume }))).toBe(1);
+
+    failing = [];
+    await writeTemplate("cluster-a", { Resources: { fixed: { Type: "AWS::SQS::Queue" } } });
+    ran = [];
+    expect(await runComponentsFanOut(ctx({ base: "main", env: "test", gate: "release", resume }))).toBe(0);
+    expect(ran).toEqual(["cluster-a", "app-one", "app-two"]);
+  });
+
+  test("the input digest is per environment: progress against one does not carry into another", async () => {
+    const resume = join(dir, "attempt.json");
+    expect(await runComponentsFanOut(ctx({ base: "main", env: "test", resume }))).toBe(0);
+    ran = [];
+    expect(await runComponentsFanOut(ctx({ base: "main", env: "prod", resume }))).toBe(0);
+    expect(ran).toHaveLength(6);
+  });
+
+  test("a record without input digests carries nothing, and says so", async () => {
+    const resume = join(dir, "attempt.json");
+    expect(await runComponentsFanOut(ctx({ base: "main", env: "test", dryRun: true }))).toBe(0);
+    const digest = /plan: (jcs1-sha256:[0-9a-f]{64})/.exec(stderr())![1]!;
+    await writeFile(resume, JSON.stringify({ digest, completed: ["net", "cluster-b"], failed: [], outputs: {} }));
+    stderrLines = [];
+    expect(await runComponentsFanOut(ctx({ base: "main", env: "test", resume }))).toBe(0);
+    expect(ran).toHaveLength(6);
+    expect(stderr()).toContain("does not record what each component applied, so none of its progress carries");
+  });
+});

package/src/cli/handlers/fan-out.ts

@@ -34,6 +34,15 @@
  * the plan before the gate is decided, and the digest is carried rather than
  * recomputed, so the approval still stands.
  *
+ * The approval and the progress are bound to different things (#4081). The
+ * approval is bound to the plan digest, the derivation: who runs, in what
+ * order, off which edges. The progress is bound to each component's input
+ * digest (../../components/fan-out-inputs.ts): a component the earlier
+ * attempt applied stays `already-applied` only while what it would apply is
+ * the same, and one whose template, step inputs or upstream moved runs again
+ * with a line saying so. The fix after a failure keeps the approval, and a
+ * different change of the same shape does not inherit the progress.
+ *
  * `--wave-gate <name>` (#3049) swaps the one gate for one per wave: the same
  * repeated command stops at each wave's gate in turn, each planned after the
  * wave before it applied, and `chant approve fan-out <name>-wave-<n>` answers
@@ -49,6 +58,7 @@ import { changedFilesBetween, lexiconChangedUnits } from "../../components/chang
 import { deriveFanOut, fanOutRegistry } from "../../components/fan-out-support";
 import { EarlierWaveNotAppliedError, runFanOut } from "../../components/fan-out-run";
 import { readFanOutAttempt, writeFanOutAttempt, type FanOutAttempt } from "../../components/fan-out-record";
+import { componentInputDigests, progressThatCarries } from "../../components/fan-out-inputs";
 import { describeChangedWave, withWaveRecord, type WaveRecord } from "../../gated-waves";
 import { renderFanOutHuman, renderFanOutJson, renderFanOutPlan } from "../../components/fan-out-output";
 import { ndjsonProgressSink } from "../../components/run-progress";
@@ -253,7 +263,12 @@ export async function runComponentsFanOut(ctx: CommandContext): Promise<number>
   // real run happens inside `runFanOut`, before the gate is decided, so an
   // approval survives the resume rather than being re-asked for.
   const resumePath = args.resume ? resolve(args.resume) : undefined;
+  // What each component would apply now (#4081). The record keeps it for
+  // every component that applies, and a later attempt carries progress only
+  // where it is unchanged.
+  const inputsNow = resumePath ? componentInputDigests(derived.components, { projectRoot: projectPath, env: args.env ?? "local" }) : {};
   let priorCompleted: string[] = [];
+  let priorInputs: Record<string, string> = {};
   let priorOutputs: Record<string, Record<string, unknown>> = {};
   let priorWaves: WaveRecord[] = [];
   let priorCarried: Record<string, unknown> = {};
@@ -277,11 +292,28 @@ export async function runComponentsFanOut(ctx: CommandContext): Promise<number>
       // as progress would block their subtrees again on the very run that
       // exists to retry them — the operator repeated the command precisely
       // because the thing that failed is now expected to work.
-      priorCompleted = attempt.completed;
+      //
+      // And only the part of `completed` whose input is the same now (#4081).
+      // The plan digest identifies the derivation, which a different change
+      // of the same shape shares; the input digest says what was applied.
+      const split = progressThatCarries(attempt, inputsNow);
+      if (split.unrecorded && split.changed.length > 0) {
+        console.error(formatWarning({
+          message: `--resume: "${args.resume}" does not record what each component applied, so none of its progress carries`,
+          hint: "It was written before chant recorded component inputs. Everything selected will run.",
+        }));
+      } else {
+        for (const name of split.changed) {
+          console.error(formatInfo(`${name}: changed since the earlier attempt, so it runs again`));
+        }
+      }
+      const carried = new Set(split.carried);
+      priorCompleted = split.carried;
+      priorInputs = Object.fromEntries(split.carried.map((name) => [name, inputsNow[name]!]));
       priorOutputs = Object.fromEntries(
-        Object.entries(attempt.outputs).filter(([name]) => attempt.completed.includes(name)),
+        Object.entries(attempt.outputs).filter(([name]) => carried.has(name)),
       );
-      progress = { completed: attempt.completed };
+      progress = { completed: split.carried };
       priorWaves = attempt.waves ?? [];
       // What steps kept per member (#3459), such as a choudoufu root's wave
       // resume file. Each step decides whether what it kept still applies.
@@ -319,6 +351,7 @@ export async function runComponentsFanOut(ctx: CommandContext): Promise<number>
   // runner, ctrl-c) then still knows that the first two applied, and the
   // repeated command picks up from there instead of redoing them.
   const completedSoFar = new Set(priorCompleted);
+  const inputsSoFar: Record<string, string> = { ...priorInputs };
   const failedSoFar: string[] = [];
   const outputsSoFar = { ...priorOutputs };
   let wavesSoFar = priorWaves;
@@ -330,6 +363,7 @@ export async function runComponentsFanOut(ctx: CommandContext): Promise<number>
       completed: [...completedSoFar].sort(),
       failed: [...failedSoFar].sort(),
       outputs: outputsSoFar,
+      inputs: Object.fromEntries(Object.entries(inputsSoFar).sort(([a], [b]) => a.localeCompare(b))),
       ...(wavesSoFar.length > 0 ? { waves: wavesSoFar } : {}),
       ...(Object.keys(carriedSoFar).length > 0 ? { carried: carriedSoFar } : {}),
     };
@@ -377,6 +411,7 @@ export async function runComponentsFanOut(ctx: CommandContext): Promise<number>
             onComponentSettled: (settled, outputs) => {
               if (settled.status === "ok") {
                 completedSoFar.add(settled.component);
+                if (inputsNow[settled.component] !== undefined) inputsSoFar[settled.component] = inputsNow[settled.component]!;
                 if (outputs) outputsSoFar[settled.component] = outputs;
               } else if (settled.status === "fail") {
                 failedSoFar.push(settled.component);

package/src/cli/handlers/intent-trace.e2e.test.ts

@@ -0,0 +1,201 @@
+/**
+ * The why chain of `graph --intent` (#4023), from work item to production
+ * release. Everything runs in a temp repo with no remote, so nothing is
+ * pushed: a workspace with a work item, a commit whose trailer links it, a
+ * green tag, a real cut, a real `components promote --release` into prod that
+ * stops at its release gate, a real `chant approve`, and the promote that
+ * follows. Only the capability registry is replaced, so no deploy step
+ * reaches a cloud, and the member's graph, so the resource node resolves to
+ * its component file without building the member.
+ */
+
+import { afterEach, describe, expect, test, vi } 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 { CapabilityRegistry, type DeployContext } from "../../components/capability";
+import type { DriverComponent } from "../../components/driver";
+import type { ParsedArgs } from "../registry";
+import { appendReleaseRecord, readReleaseLedger } from "../../lifecycle/release-ledger";
+import { readGateLedger } from "../../lifecycle/gate-ledger";
+import { cutRelease } from "../../lifecycle/release-cut";
+import { resetGateOrigin } from "../../lifecycle/gate-origin";
+import { contract, REPO } from "../../workspace/__fixtures__/contract-repo";
+import { intentGraph, type IntentDocument } from "../../workspace/intent";
+import intentSchema from "../../workspace/intent.schema.json";
+import type { ReleaseArtifact } from "../../lifecycle/release-store";
+import type { CompiledTarget, TargetCompiler } from "../../components/release-compile";
+
+const DIGEST = `sha256:${"0123456789abcdef".repeat(4)}`;
+
+const api: DriverComponent = {
+  name: "api",
+  deploy: [
+    { phase: "Publish", steps: [{ kind: "publish-image", from: "archive:api.tar" }] },
+    { phase: "Apply", steps: [{ kind: "gate", gate: "prod-release" }, { kind: "apply", template: "dist/api.template.json", imageRef: "@Publish.digest" }] },
+  ],
+};
+
+vi.mock("../../config", async () => {
+  const actual = await vi.importActual<typeof import("../../config")>("../../config");
+  return { ...actual, loadChantConfig: async () => ({ config: {} }) };
+});
+vi.mock("../../components/cli-support", () => ({
+  isComponentList: () => false,
+  resolveComponentTargets: async () => ({ success: true, targets: [api] }),
+}));
+vi.mock("../../components/fan-out-support", () => ({
+  fanOutRegistry: async () => {
+    const registry = new CapabilityRegistry();
+    registry.register({ kind: "publish-image", async run(_ctx: DeployContext) { return { digest: DIGEST, uri: `reg/api@${DIGEST}` }; } } as never);
+    registry.register({ kind: "apply", async run() { return {}; } } as never);
+    return registry;
+  },
+}));
+vi.mock("../../op/discover", () => ({ discoverOps: async () => ({ errors: [], ops: new Map() }) }));
+vi.mock("./run", () => ({ GATED_EXIT_CODE: 3 }));
+
+const { runComponentsPromote } = await import("./promote");
+const { recordGateApproval } = await import("./approve");
+
+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();
+}
+
+/** A compiler that compiles each environment to its own template and builds one image. */
+const compiler: TargetCompiler = {
+  async compile(env): Promise<CompiledTarget> {
+    return {
+      env,
+      params: [],
+      components: ["api"],
+      buildSteps: { api: [{ kind: "docker-build", context: "api", into: "api.tar" }] },
+      buildInputs: { api: ["api"] },
+      componentFiles: { api: "api.component.ts" },
+      templates: [{ component: "api", path: "dist/api.template.json", content: `{"env":"${env}"}\n` }],
+    };
+  },
+  async buildArtifacts(_env, components): Promise<ReleaseArtifact[]> {
+    return components.map((c) => ({ component: c, kind: "image" as const, path: `${c}.tar`, digest: DIGEST }));
+  },
+};
+
+function args(overrides: Partial<ParsedArgs>): ParsedArgs {
+  return {
+    command: "components", path: "promote", format: "", fix: false, watch: false, verbose: false, help: false, live: false,
+    migrateFrom: "staging", migrateTo: "prod", actor: "bob", runId: "run-9", ...overrides,
+  } as ParsedArgs;
+}
+const ctx = (a: Partial<ParsedArgs>) => ({ args: args(a), plugins: [] }) as never;
+
+const REF = join(REPO, "reference-workspace");
+const KIND_FILES: Record<string, string> = {
+  "work/work.kind.mjs": readFileSync(join(REF, "work", "work.kind.mjs"), "utf-8"),
+  "work/work.schema.json": readFileSync(join(REF, "work", "work.schema.json"), "utf-8"),
+  "decisions/decision.kind.mjs": readFileSync(join(REF, "decisions", "decision.kind.mjs"), "utf-8"),
+  "decisions/decision.schema.json": readFileSync(join(REF, "decisions", "decision.schema.json"), "utf-8"),
+};
+const W001 = `---\n${JSON.stringify({ schema: 1, id: "W-001", title: "Ship the api to prod", state: "open", implements: [], needs: [], constrains: ["path:api.component.ts"], evidence: [], opened_on: "2026-10-16", supersedes: [] }, null, 2)}\n---\n\n# W-001\n`;
+const DECLARATION = JSON.stringify({ name: "shop", schema: 1, members: [{ name: "api", dir: ".", kind: "other", because: "the api and its component" }] });
+const intent = contract(intentSchema);
+type Result = Exclude<IntentDocument, { error: unknown }>;
+
+describe("the why chain from work item to production release (#4023)", () => {
+  const cwd = process.cwd();
+  afterEach(() => {
+    process.chdir(cwd);
+    resetGateOrigin();
+    vi.restoreAllMocks();
+  });
+
+  test(
+    "the trace from the api's resource node walks W-001, the linked commit, its green tag, the cut, the release gate approval and the prod deploy",
+    async () => {
+      vi.spyOn(console, "error").mockImplementation(() => {});
+      vi.spyOn(console, "log").mockImplementation(() => {});
+      vi.spyOn(process.stderr, "write").mockImplementation(() => true);
+      await withTestDir(async (dir) => {
+        git(dir, "init", "-q", "-b", "main");
+        git(dir, "config", "user.email", "t@chant.dev");
+        git(dir, "config", "user.name", "T");
+        const files: Record<string, string> = {
+          "chant.workspace.json": DECLARATION,
+          "chant.config.ts": `export default { environments: ["dev", "staging", "prod"] };\n`,
+          "api.component.ts": "export const api = {};\n",
+          "work/W-001-ship.md": W001,
+          ...KIND_FILES,
+        };
+        for (const [path, text] of Object.entries(files)) {
+          mkdirSync(join(dir, path, ".."), { recursive: true });
+          writeFileSync(join(dir, path), text);
+        }
+        git(dir, "add", ".");
+        git(dir, "commit", "-q", "-m", "the api and W-001");
+        // The work: a commit whose trailer names W-001, made green.
+        writeFileSync(join(dir, "api.component.ts"), "export const api = { port: 8081 };\n");
+        git(dir, "commit", "-q", "-am", "serve the api on 8081", "--trailer", "Chant-Record: work:W-001");
+        const sha = git(dir, "rev-parse", "HEAD");
+        git(dir, "tag", `ci/green/${sha}`, sha);
+        process.chdir(dir);
+
+        // The release is cut from the green commit, and promoted to prod through its release gate.
+        const cut = await cutRelease({ cwd: dir, compiler, label: "v1.0.0", actor: "alice", env: {}, now: () => new Date("2026-10-16T10:00:00.000Z") });
+        const releaseDigest = cut.release.releaseDigest;
+        await appendReleaseRecord({ component: "api", env: "staging", digest: DIGEST, gitSha: sha, runId: "run-1", timestamp: "2026-10-16T10:30:00.000Z", actor: "ci" }, { cwd: dir });
+        expect(await runComponentsPromote(ctx({ release: "v1.0.0" }))).toBe(3);
+        expect((await recordGateApproval("release", "prod-release", { origin: "cli", actor: "alice", cwd: dir, environment: "prod" })).ok).toBe(true);
+        expect(await runComponentsPromote(ctx({ release: "v1.0.0" }))).toBe(0);
+        const [deploy] = (await readReleaseLedger("prod", { cwd: dir })).records;
+        const [resolution] = (await readGateLedger("release", { cwd: dir })).resolutions;
+
+        const walk = async (region: string): Promise<Result> => {
+          const { doc } = await intentGraph({
+            cwd: dir,
+            region,
+            kinds: [join(dir, "work/work.kind.mjs")],
+            resolveNode: async (_cwd, _at, member, id) => (member === "api" && id === "api/api" ? { file: "api.component.ts", line: null } : null),
+          });
+          intent.expectValid(doc);
+          if ("error" in doc) throw new Error(`${doc.error.code}: ${doc.error.message}`);
+          return doc;
+        };
+
+        // From the resource node: who asked for it, and who let it ship, in one read.
+        const doc = await walk("api/api");
+        expect(doc.nodes[0]).toMatchObject({ kind: "region", path: "api.component.ts", node: "api/api" });
+        const trace = doc.trace!;
+        expect(trace.reasons).toEqual([]);
+        const c = trace.commits.find((x) => x.sha === sha)!;
+        expect(c.work).toEqual({ state: "linked", items: [{ id: "work:W-001", node: "record:work/W-001", source: { ref: sha, field: "Chant-Record", value: "work:W-001" } }], problems: [] });
+        expect(c.tag).toMatchObject({ state: "green", green: { tag: `ci/green/${sha}` } });
+        expect(c.releases).toEqual([{ release: releaseDigest, link: "cut-from", source: { ref: `chant/lifecycle:_releases/${releaseDigest.replace(/:/g, "_")}.json`, field: "commit", value: sha } }]);
+        expect(c.deploys.map((d) => [d.env, d.link])).toEqual([["prod", "built-from"], ["staging", "built-from"]]);
+
+        const [release] = trace.releases;
+        expect(trace.releases).toHaveLength(1);
+        expect(release).toMatchObject({ releaseDigest, label: "v1.0.0", commit: sha, tag: { state: "green" }, cuts: [{ label: "v1.0.0", actor: "alice" }] });
+        // The gate approval: who, on which channel, when, and the change set the promote stored for it (#4022).
+        expect(release.gates).toEqual([
+          expect.objectContaining({ op: "release", gate: "prod-release", environment: "prod", resolvedBy: "alice", channel: "cli", at: resolution.timestamp, planDigest: resolution.planDigest, changeSet: resolution.planDigest, empty: false }),
+        ]);
+        expect(release.gates[0].changeSetSource).toEqual({ ref: `chant/lifecycle:_change-sets/${resolution.planDigest!.replace(/:/g, "_")}.json`, field: "planDigest", value: resolution.planDigest });
+
+        // The prod deploy record, admitted by that resolution.
+        const prod = trace.deploys.find((d) => d.env === "prod")!;
+        expect(release.deploys).toEqual([prod.id]);
+        expect(prod).toMatchObject({ component: "api", runId: deploy.runId, gitSha: sha, release: releaseDigest, approver: "alice", admittedBy: { op: "release", gate: "prod-release", resolvedBy: "alice", at: resolution.timestamp } });
+        // Staging was a plain deploy of the same commit: it names no release.
+        expect(trace.deploys.find((d) => d.env === "staging")).toMatchObject({ release: null, admittedBy: null });
+
+        // The same chain from the commit itself.
+        const byCommit = await walk(sha);
+        expect(byCommit.trace!.commits).toEqual([c]);
+        expect(byCommit.trace!.releases).toEqual(trace.releases);
+      });
+    },
+    240_000,
+  );
+});

package/src/cli/handlers/lifecycle-gc.test.ts

@@ -0,0 +1,126 @@
+/** #4036: `chant lifecycle gc [--yes] [--push] [--json]`, in temp repos. */
+
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+import type { ParsedArgs } from "../registry";
+import { runLifecycleGc } from "./lifecycle-gc";
+import { writeLedgerFiles } from "../../lifecycle/git";
+import { makeRelease } from "../../lifecycle/release-store";
+import type { GcReport } from "../../lifecycle/retention";
+
+function args(o: Partial<ParsedArgs>): ParsedArgs {
+  return { command: "lifecycle", path: ".", format: "", fix: false, watch: false, verbose: false, help: false, live: false, ...o };
+}
+
+const git = (cwd: string, ...a: string[]) => execFileSync("git", a, { cwd, encoding: "utf-8" }).trim();
+
+let dir: string;
+let cwd: string;
+let out: string[];
+let err: string[];
+beforeEach(() => {
+  cwd = process.cwd();
+  dir = realpathSync(mkdtempSync(join(tmpdir(), "lifecycle-gc-")));
+  vi.stubEnv("CHANT_RUN_EVENTS_DIR", join(dir, ".events"));
+  git(dir, "init", "-q", "-b", "main");
+  git(dir, "config", "user.email", "t@t");
+  git(dir, "config", "user.name", "t");
+  process.chdir(dir);
+  out = [];
+  err = [];
+  vi.spyOn(console, "log").mockImplementation((s: string) => void out.push(String(s)));
+  vi.spyOn(console, "error").mockImplementation((s: string) => void err.push(String(s)));
+});
+afterEach(() => {
+  vi.restoreAllMocks();
+  vi.unstubAllEnvs();
+  process.chdir(cwd);
+  rmSync(dir, { recursive: true, force: true });
+});
+
+function commitAll(): string {
+  writeFileSync(join(dir, "README.md"), "x\n");
+  git(dir, "add", ".");
+  git(dir, "commit", "-q", "-m", "init");
+  return git(dir, "rev-parse", "HEAD");
+}
+
+const changeSet = `_change-sets/jcs1-sha256_${"1".repeat(64)}.json`;
+const ctx = (o: Partial<ParsedArgs>) => ({ args: args(o), plugins: [], serializers: [] });
+const report = (): GcReport => JSON.parse(out.join("\n")) as GcReport;
+
+describe("chant lifecycle gc", () => {
+  test("a dry run by default; --yes prunes in one local commit and pushes nothing", async () => {
+    writeFileSync(join(dir, "chant.workspace.json"), JSON.stringify({ name: "w", schema: 1, members: [], retention: { changeSets: { days: 0 } } }));
+    commitAll();
+    await writeLedgerFiles([{ path: changeSet, content: "{}\n", expectPriorSha: null }], "fixture", { cwd: dir });
+    const tip = git(dir, "rev-parse", "chant/lifecycle");
+
+    expect(await runLifecycleGc(ctx({}))).toBe(0);
+    expect(out[0]).toMatch(/^chant\/lifecycle at [0-9a-f]{12}: would remove 1 change set\(s\), 0 release\(s\) and 0 template\(s\)/);
+    expect(err.join("\n")).toContain("Dry run: nothing was removed");
+    expect(git(dir, "rev-parse", "chant/lifecycle")).toBe(tip);
+
+    out = [];
+    expect(await runLifecycleGc(ctx({ yes: true, json: true }))).toBe(0);
+    const r = report();
+    expect(r.dryRun).toBe(false);
+    expect(r.policy.changeSets.days).toBe(0);
+    expect(r.lifecycle.remove.map((f) => f.path)).toEqual([changeSet]);
+    expect(r.lifecycle.commit).toBe(git(dir, "rev-parse", "chant/lifecycle"));
+    expect(git(dir, "rev-parse", "chant/lifecycle^")).toBe(tip);
+    expect(r.lifecycle.pushed).toBe(false);
+  });
+
+  test("outside a workspace the defaults apply, and a release of a revoked commit is not promotable", async () => {
+    const head = commitAll();
+    const cut = (commit: string) => {
+      const r = makeRelease({ member: null, commit, artifactDigests: [], targets: [{ env: "prod", templates: [], params: [] }] });
+      return { r, line: JSON.stringify({ version: 1, releaseDigest: r.releaseDigest, label: null, actor: "a", timestamp: new Date().toISOString(), runOrigin: null, signature: null }) };
+    };
+    const revoked = cut(head);
+    const fine = cut("b".repeat(40));
+    const file = (d: string) => `_releases/${d.replace(/:/g, "_")}.json`;
+    await writeLedgerFiles(
+      [
+        { path: changeSet, content: "{}\n" },
+        { path: file(revoked.r.releaseDigest), content: `${JSON.stringify(revoked.r)}\n` },
+        { path: file(fine.r.releaseDigest), content: `${JSON.stringify(fine.r)}\n` },
+        { path: "_releases/cuts.jsonl", content: `${revoked.line}\n${fine.line}\n` },
+      ],
+      "fixture",
+      { cwd: dir },
+    );
+    git(dir, "tag", `ci/revoked/${head}`, head);
+
+    expect(await runLifecycleGc(ctx({ json: true }))).toBe(0);
+    const r = report();
+    expect(r.policy.releases).toEqual({ days: 14, keep: 10 });
+    expect(r.lifecycle.remove.map((f) => f.path)).toEqual([file(revoked.r.releaseDigest)]);
+    expect(r.lifecycle.keep.map((f) => [f.path, f.reasons.map((x) => x.code)])).toEqual(
+      expect.arrayContaining([[changeSet, ["within-window"]], [file(fine.r.releaseDigest), ["newest", "within-window"]]]),
+    );
+  });
+
+  test("a workspace whose declaration can't be read prunes nothing", async () => {
+    writeFileSync(join(dir, "chant.workspace.json"), JSON.stringify({ name: "w", schema: 1, members: [], retention: { changeSets: { days: -1 } } }));
+    commitAll();
+    expect(await runLifecycleGc(ctx({ yes: true }))).toBe(1);
+    expect(err.join("\n")).toContain("its retention policy is unknown and nothing is pruned");
+  });
+
+  test("a directory outside git is refused", async () => {
+    const plain = realpathSync(mkdtempSync(join(tmpdir(), "lifecycle-gc-plain-")));
+    try {
+      process.chdir(plain);
+      expect(await runLifecycleGc(ctx({}))).toBe(1);
+      expect(err.join("\n")).toContain("not in a git repository");
+    } finally {
+      process.chdir(dir);
+      rmSync(plain, { recursive: true, force: true });
+    }
+  });
+});