@intentius/chant 0.124.28 → 0.124.29

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

@@ -0,0 +1,146 @@
+/**
+ * `chant lifecycle gc [--yes] [--push] [--json] [--verbose]` (#4036): prune
+ * stored change sets, releases and their templates from `chant/lifecycle`, and
+ * run event files from this host, by the retention policy.
+ *
+ * Without `--yes` it is a dry run: it prints what it would remove and changes
+ * nothing. With `--yes` it writes one commit to the local `chant/lifecycle`
+ * that removes those files, and deletes the run event files. It pushes only
+ * with `--push`. History is never rewritten, so a pruned file stays in the
+ * branch's earlier commits. The rules are in ../../lifecycle/retention.ts.
+ *
+ * The policy is the defaults, overridden by the `retention` block of the
+ * workspace declaration at base when the checkout is a workspace. The prune
+ * covers the whole branch, every member, from wherever in the repository it
+ * runs.
+ */
+
+import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { formatError, formatSuccess, formatWarning } from "../format";
+import type { CommandContext } from "../registry";
+import type { RetentionPolicy } from "../../lifecycle/retention-policy";
+
+const USAGE = "chant lifecycle gc [--yes] [--push] [--json] [--verbose]";
+
+function tryGit(cwd: string, args: string[]): string | null {
+  try {
+    return execFileSync("git", args, { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+  } catch {
+    return null;
+  }
+}
+
+/** Whether a workspace declaration sits in `cwd` or a directory above it, up to the repository's top. */
+function inWorkspace(cwd: string, top: string): boolean {
+  for (let dir = cwd; ; dir = dirname(dir)) {
+    if (existsSync(join(dir, "chant.workspace.json")) || existsSync(join(dir, "chant.workspace.jsonc"))) return true;
+    if (dir === top || dirname(dir) === dir) return false;
+  }
+}
+
+/** Every commit with a `ci/revoked/<sha>` tag, counted as `chant release cut` counts it. */
+async function revokedCommits(cwd: string, top: string, green: import("../../workspace/declaration").CiGreen | null, workspace: boolean): Promise<Set<string>> {
+  if (workspace) {
+    const { readCiTags } = await import("../../workspace/ci-green");
+    const base = green
+      ? (tryGit(top, ["rev-parse", "--verify", "--quiet", `refs/remotes/origin/${green.branch}^{commit}`]) ??
+        tryGit(top, ["rev-parse", "--verify", "--quiet", `refs/heads/${green.branch}^{commit}`]) ??
+        tryGit(top, ["rev-parse", "HEAD"]))
+      : null;
+    return new Set(readCiTags(top, green, base).revoked.keys());
+  }
+  // With no declaration every tag counts, as readCiTags counts them without `ci.green`.
+  const out = tryGit(cwd, ["for-each-ref", "--format=%(refname:lstrip=4)", "refs/tags/ci/revoked/"]) ?? "";
+  return new Set(out.split("\n").filter((s) => /^[0-9a-f]{40,64}$/.test(s)));
+}
+
+const kb = (bytes: number): string => (bytes >= 1024 * 1024 ? `${(bytes / 1024 / 1024).toFixed(1)} MB` : `${(bytes / 1024).toFixed(1)} KB`);
+
+export async function runLifecycleGc(ctx: CommandContext): Promise<number> {
+  const { args } = ctx;
+  if (args.extraPositional) {
+    console.error(formatError({ message: `lifecycle gc takes no argument, and was given "${args.extraPositional}"`, hint: USAGE }));
+    return 1;
+  }
+  const cwd = resolve(".");
+  const top = tryGit(cwd, ["rev-parse", "--show-toplevel"]);
+  if (!top) {
+    console.error(formatError({ message: "lifecycle gc prunes the chant/lifecycle branch, and this directory is not in a git repository", hint: USAGE }));
+    return 1;
+  }
+  const dryRun = args.yes !== true;
+
+  const { resolveRetention } = await import("../../lifecycle/retention-policy");
+  let policy: RetentionPolicy = resolveRetention(null);
+  let green: import("../../workspace/declaration").CiGreen | null = null;
+  const workspace = inWorkspace(cwd, top);
+  if (workspace) {
+    const { scopeSource } = await import("../../workspace/write-scope");
+    const source = scopeSource(cwd);
+    if (!source.declaration) {
+      console.error(formatError({ message: `the workspace declaration can't be read, so its retention policy is unknown and nothing is pruned: ${source.failure?.message ?? "no declaration"}` }));
+      return 1;
+    }
+    policy = resolveRetention(source.declaration.retention);
+    green = source.declaration.ci?.green ?? null;
+  }
+
+  // Read the remote's facts first: a prune planned on a stale branch could
+  // remove what a newer gate binds, and a forked branch must not be pushed over.
+  const { fetchLifecycleStatus } = await import("../../lifecycle/git");
+  const fetched = await fetchLifecycleStatus({ cwd });
+  if (fetched.status === "diverged" || fetched.status === "unreachable") {
+    const why = fetched.status === "diverged" ? `the local chant/lifecycle and ${fetched.remote}'s have forked` : `${fetched.remote} did not answer: ${fetched.stderr}`;
+    if (!dryRun) {
+      console.error(formatError({ message: `nothing was pruned: ${why}`, hint: "Bring chant/lifecycle up to date with its remote, then run again." }));
+      return 1;
+    }
+    if (!args.json) console.error(formatWarning({ message: `planned on the local branch only: ${why}` }));
+  }
+
+  const { runLifecycleGc: run } = await import("../../lifecycle/retention");
+  const report = await run({
+    cwd,
+    policy,
+    now: new Date(),
+    revokedCommits: await revokedCommits(cwd, top, green, workspace),
+    dryRun,
+    push: args.push === true,
+  });
+
+  if (args.json) {
+    console.log(JSON.stringify(report, null, 2));
+    return 0;
+  }
+
+  const lc = report.lifecycle;
+  const count = (list: ReadonlyArray<{ kind: string }>, kind: string) => list.filter((f) => f.kind === kind).length;
+  const bytes = lc.remove.reduce((n, f) => n + f.bytes, 0);
+  const verb = dryRun ? "would remove" : "removed";
+  if (!lc.tip) {
+    console.error("No chant/lifecycle branch: nothing stored to prune.");
+  } else {
+    console.log(
+      `chant/lifecycle at ${lc.tip.slice(0, 12)}: ${verb} ${count(lc.remove, "change-set")} change set(s), ${count(lc.remove, "release")} release(s) and ${count(lc.remove, "template")} template(s), ${kb(bytes)}; ` +
+        `keeps ${count(lc.keep, "change-set")}, ${count(lc.keep, "release")} and ${count(lc.keep, "template")}`,
+    );
+    console.log(`  tree at the tip: ${lc.before.files} file(s), ${kb(lc.before.bytes)} before; ${lc.after.files} file(s), ${kb(lc.after.bytes)} after. The ledgers (${kb(lc.before.ledgers.bytes)}) are never pruned, and history keeps every removed file.`);
+    if (args.verbose) for (const f of lc.remove) console.log(`  - ${f.path}`);
+  }
+  const ev = report.runEvents;
+  if (ev.dir) {
+    console.log(`  run events in ${ev.dir}: ${verb} ${ev.remove.length} file(s), ${kb(ev.remove.reduce((n, f) => n + f.bytes, 0))}; keeps ${ev.kept.files}`);
+    if (args.verbose) for (const f of ev.remove) console.log(`  - ${f.file}`);
+  }
+  if (dryRun) {
+    console.error("Dry run: nothing was removed. Run again with --yes to prune.");
+  } else if (lc.commit) {
+    console.error(formatSuccess(`Pruned in commit ${lc.commit.slice(0, 12)} on chant/lifecycle`));
+    if (lc.pushed) console.error("  pushed");
+    else if (lc.pushWarning) console.error(formatWarning({ message: lc.pushWarning }));
+    else console.error("  not pushed: run with --push, or push chant/lifecycle yourself");
+  }
+  return 0;
+}

package/src/cli/handlers/pr.test.ts

@@ -8,6 +8,7 @@
 
 import { mkdtemp, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
+import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
 import type { DriverComponent } from "../../components/driver";
@@ -58,6 +59,8 @@ vi.mock("../../op/gate", async () => {
 });
 
 const failing = new Set<string>();
+/** Called as a component's apply starts, before it can fail. */
+let onRun: (root: string) => void = () => {};
 vi.mock("../../components/fan-out-support", async () => {
   const { CapabilityRegistry } = await import("../../components/capability");
   const { planFanOut } = await import("../../components/fan-out");
@@ -78,6 +81,7 @@ vi.mock("../../components/fan-out-support", async () => {
       return {};
     },
     async run(_ctx: DeployContext, input: { root: string }) {
+      onRun(input.root);
       if (failing.has(input.root)) throw new Error(`${input.root} failed`);
       return { outputs: {} };
     },
@@ -106,6 +110,7 @@ const { checkRunEventLines, stepTrail } = await import("../../workspace/__fixtur
 
 let dir: string;
 let out: string[];
+let errors: string[];
 
 const ctx = (a: Partial<ParsedArgs>) =>
   ({ args: { command: "components", path: "pr-apply", format: "", fix: false, watch: false, verbose: false, help: false, live: false, base: "main", env: "prod", output: dir, eventsJson: true, ...a } as ParsedArgs, plugins: [] }) as never;
@@ -113,10 +118,12 @@ const ctx = (a: Partial<ParsedArgs>) =>
 beforeEach(async () => {
   dir = await mkdtemp(join(tmpdir(), "pr-events-"));
   out = [];
+  errors = [];
   failing.clear();
+  onRun = () => {};
   gateLedger = memoryGateLedgerPort();
   vi.spyOn(process.stdout, "write").mockImplementation((chunk: string | Uint8Array) => { out.push(String(chunk)); return true; });
-  vi.spyOn(console, "error").mockImplementation(() => {});
+  vi.spyOn(console, "error").mockImplementation((...m: unknown[]) => { errors.push(m.map(String).join(" ")); });
   vi.spyOn(console, "log").mockImplementation(() => {});
 });
 
@@ -182,6 +189,146 @@ describe("pr-apply --events-json", () => {
   });
 });
 
+/** Plan pull request 12 and approve its digest, as a reviewer would. */
+async function planAndApprove(): Promise<void> {
+  await runComponentsPrPlan(ctx({ pr: 12 }));
+  const digest = await plannedDigest();
+  gateLedger = memoryGateLedgerPort({
+    resolutions: [{ version: 1, kind: "resolution", op: "pr-12", gate: "pr-apply", resolvedBy: "github:alice", timestamp: new Date().toISOString(), planDigest: digest }],
+  });
+  out = [];
+  errors = [];
+}
+
+/** The job log's wave and component lines, without colour. */
+const logLines = (): string[] =>
+  errors.map((l) => l.replace(/\u001b\[[0-9;]*m/g, "")).filter((l) => /^wave \d|^ {2}\S+: /.test(l));
+
+describe("pr-apply's job log (#4007)", () => {
+  test("without --events-json, a line as each wave starts and as each component settles, in order", async () => {
+    await planAndApprove();
+    expect(await runComponentsPrApply(ctx({ pr: 12, eventsJson: false }))).toBe(0);
+    expect(out).toEqual([]);
+    expect(logLines()).toEqual(["wave 1/2: net", "  net: applied", "wave 2/2: app", "  app: applied"]);
+  });
+
+  test("a failed dependency: the component behind it settles blocked, naming it, in the log and the stream", async () => {
+    await planAndApprove();
+    failing.add("net");
+    expect(await runComponentsPrApply(ctx({ pr: 12 }))).toBe(1);
+    expect(logLines()).toEqual(["wave 1/2: net", "  net: failed", "  app: blocked by net, not run"]);
+    const events = checkRunEventLines(out);
+    const blocked = events.find((e) => e.type === "component-settle" && e.component === "app");
+    expect(blocked).toMatchObject({ type: "component-settle", wave: 2, component: "app", status: "blocked", blockedBy: "net" });
+    expect(events.some((e) => e.type === "component-start" && e.component === "app")).toBe(false);
+    expect(events.some((e) => e.type === "wave-start" && e.wave === 2)).toBe(false);
+    expect(events.at(-1)).toMatchObject({ type: "run-settle", status: "failed" });
+  });
+
+  test("a resumed apply settles what the earlier attempt applied as already-applied, before the gate", async () => {
+    await planAndApprove();
+    const resume = join(dir, "attempt.json");
+    failing.add("app");
+    expect(await runComponentsPrApply(ctx({ pr: 12, resume, eventsJson: false }))).toBe(1);
+    failing.clear();
+    out = [];
+    errors = [];
+    expect(await runComponentsPrApply(ctx({ pr: 12, resume }))).toBe(0);
+    const events = checkRunEventLines(out);
+    const settles = events.filter((e) => e.type === "component-settle").map((e) => [e.component, (e as { status: string }).status, (e as { wave: number }).wave]);
+    expect(settles).toEqual([["net", "already-applied", 1], ["app", "ok", 1]]);
+    const gate = events.findIndex((e) => e.type === "phase-start" && e.phase === "gate");
+    expect(events.findIndex((e) => e.type === "component-settle" && e.component === "net")).toBeLessThan(gate);
+    expect(logLines()).toEqual(["  net: already applied in an earlier attempt", "wave 1/1: app", "  app: applied"]);
+  });
+});
+
+describe("--resume carries only an unchanged input (#4081)", () => {
+  test("a component whose input moved since the attempt runs again, and says why", async () => {
+    await planAndApprove();
+    const resume = join(dir, "attempt.json");
+    failing.add("app");
+    expect(await runComponentsPrApply(ctx({ pr: 12, resume, eventsJson: false }))).toBe(1);
+    expect(JSON.parse(readFileSync(resume, "utf8")).inputs).toEqual({ net: expect.stringMatching(/^jcs1-sha256:/) });
+    failing.clear();
+    errors = [];
+    const step = ESTATE[0]!.deploy[0]!.steps[0] as Record<string, unknown>;
+    step.note = "a different change of the same shape";
+    const ran: string[] = [];
+    onRun = (name) => ran.push(name);
+    try {
+      expect(await runComponentsPrApply(ctx({ pr: 12, resume, eventsJson: false }))).toBe(0);
+    } finally {
+      delete step.note;
+    }
+    expect(ran).toEqual(["net", "app"]);
+    expect(errors.join("\n")).toContain("net: changed since the earlier attempt, so it runs again");
+  });
+
+  test("a record without input digests does not carry", async () => {
+    await planAndApprove();
+    const resume = join(dir, "attempt.json");
+    failing.add("app");
+    expect(await runComponentsPrApply(ctx({ pr: 12, resume, eventsJson: false }))).toBe(1);
+    const { writeFileSync } = await import("node:fs");
+    const record = JSON.parse(readFileSync(resume, "utf8"));
+    delete record.inputs;
+    writeFileSync(resume, JSON.stringify(record));
+    failing.clear();
+    errors = [];
+    const ran: string[] = [];
+    onRun = (name) => ran.push(name);
+    expect(await runComponentsPrApply(ctx({ pr: 12, resume, eventsJson: false }))).toBe(0);
+    expect(ran).toEqual(["net", "app"]);
+    expect(errors.join("\n")).toMatch(/does not carry: it does not record what each component applied/);
+  });
+});
+
+describe("--report-url (#4007)", () => {
+  test("refuses a URL it can't upload to, before anything plans", async () => {
+    expect(await runComponentsPrPlan(ctx({ pr: 12, reportUrl: "https://example.invalid/reports" }))).toBe(1);
+    expect(errors.join("\n")).toMatch(/takes an s3:\/\/<bucket>\/<prefix> or file:\/\/<directory> URL/);
+    expect(out).toEqual([]);
+  });
+
+  test("file://: the report, the change set and the events land under <pr>/<commit>/, the events as each wave settles", async () => {
+    const { pathToFileURL } = await import("node:url");
+    const { readFile } = await import("node:fs/promises");
+    const reports = join(dir, "reports");
+    const reportUrl = pathToFileURL(reports).href;
+    await runComponentsPrPlan(ctx({ pr: 12, reportUrl }));
+    const at = join(reports, "12", HEAD);
+    expect(JSON.parse(await readFile(join(at, "pr-plan.json"), "utf8"))).toMatchObject({ stage: "plan", pr: 12, status: "planned" });
+    expect(checkRunEventLines((await readFile(join(at, "pr-plan.events.jsonl"), "utf8")).split(/(?<=\n)/))[0]).toMatchObject({ type: "run-start" });
+
+    await planAndApprove();
+    // What a reader of the URL sees while wave 2 applies: wave 1 settled.
+    let seenMidRun: string[] = [];
+    onRun = (root) => {
+      if (root === "app") seenMidRun = readFileSync(join(at, "pr-apply.events.jsonl"), "utf8").split(/(?<=\n)/);
+    };
+    expect(await runComponentsPrApply(ctx({ pr: 12, reportUrl }))).toBe(0);
+    const mid = seenMidRun.map((l) => JSON.parse(l) as { type: string; wave?: number; status?: string });
+    expect(mid.some((e) => e.type === "wave-settle" && e.wave === 1 && e.status === "ok")).toBe(true);
+    expect(mid.some((e) => e.type === "run-settle")).toBe(false);
+
+    const final = checkRunEventLines((await readFile(join(at, "pr-apply.events.jsonl"), "utf8")).split(/(?<=\n)/));
+    expect(final.at(-1)).toMatchObject({ type: "run-settle", status: "ok" });
+    expect(final.map((e) => e.type).join("\n")).toBe(out.map((l) => JSON.parse(l).type).join("\n"));
+    expect(JSON.parse(await readFile(join(at, "pr-apply.json"), "utf8"))).toMatchObject({ stage: "apply", status: "applied" });
+    expect(JSON.parse(await readFile(join(at, "change-set.json"), "utf8"))).toHaveProperty("digest");
+    expect(errors.join("\n")).toContain(`report  : ${reportUrl}/12/${HEAD}/`);
+  });
+
+  test("without --events-json, only the report and the change set are copied", async () => {
+    const { pathToFileURL } = await import("node:url");
+    const { readdir } = await import("node:fs/promises");
+    const reports = join(dir, "reports");
+    await runComponentsPrPlan(ctx({ pr: 12, reportUrl: pathToFileURL(reports).href, eventsJson: false }));
+    expect((await readdir(join(reports, "12", HEAD))).sort()).toEqual(["change-set.json", "pr-plan.json"]);
+  });
+});
+
 describe("--events-json beside --json", () => {
   test("is refused on pr-plan and pr-apply before anything plans, since both print to stdout", async () => {
     const errors: string[] = [];

package/src/cli/handlers/pr.ts

@@ -33,7 +33,15 @@
  * one `run-event.schema.json` line each: the planning as a `plan` phase with
  * a step per component, the gate's decision as a `gate` phase, and on
  * pr-apply the apply's waves and components as `chant run --components`
- * streams them.
+ * streams them. A component the apply does not start settles too, `blocked`
+ * behind a failed dependency or `already-applied` on a resumed apply.
+ * With or without it, pr-apply prints a line on stderr as each wave starts
+ * and as each component settles, so a job log shows the waves in order.
+ *
+ * `--report-url <s3 or file URL>` (#4007) copies `pr-<stage>.json`,
+ * `change-set.json` and, with `--events-json`, the events to
+ * `<url>/<pr>/<commit>/`, the events again as each wave and component
+ * settles (`../../pr-report-url.ts`).
  *
  * `--member <name>` (#3465) runs a workspace member's loop: the member's
  * generated pipeline passes it from the member's directory. The gate is
@@ -59,11 +67,13 @@ import {
   type PrPlanSet,
 } from "../../components/pr-run";
 import { readFanOutAttempt, writeFanOutAttempt, type FanOutAttempt, type PrApplyRecord } from "../../components/fan-out-record";
+import { componentInputDigests, progressThatCarries } from "../../components/fan-out-inputs";
 import { samePlanDigest } from "../../lifecycle/plan-digest";
 import { gitGateLedgerPort, type GateCheck } from "../../op/gate";
 import { emitGateStep, gateEventsOf, GATE_PHASE, type RunEventSink, type RunEventStream } from "../../run-event-stream";
-import type { RunEventSettleStatus } from "../../run-event";
+import type { RunEventBody, RunEventComponentSettle, RunEventSettleStatus } from "../../run-event";
 import { openCliRunEvents, refusesEventsWithJson } from "../run-events";
+import { openPrReportUpload, parseReportUrl, reportKey, type PrReportUpload, type ReportTarget } from "../../pr-report-url";
 import {
   describePlanChanged,
   PR_APPLY_GATE,
@@ -262,12 +272,18 @@ function settleOf(status: PrReport["status"]): RunEventSettleStatus {
   }
 }
 
-/** Write the report, the change set and the note; print the note's path. */
-function writeOutputs(ctx: CommandContext, report: PrReport, note: string): void {
+/** Write the report, the change set and the note, and hand the first two to `--report-url`'s upload. */
+function writeOutputs(ctx: CommandContext, report: PrReport, note: string, upload?: PrReportUpload): void {
   const dir = resolve(ctx.args.output ?? PR_REPORT_DIR);
   mkdirSync(dir, { recursive: true });
-  writeFileSync(join(dir, `pr-${report.stage}.json`), JSON.stringify(report, null, 2) + "\n");
-  writeFileSync(join(dir, "change-set.json"), JSON.stringify(report.changeSet, null, 2) + "\n");
+  const files: Array<[string, string]> = [
+    [`pr-${report.stage}.json`, JSON.stringify(report, null, 2) + "\n"],
+    ["change-set.json", JSON.stringify(report.changeSet, null, 2) + "\n"],
+  ];
+  for (const [name, body] of files) {
+    writeFileSync(join(dir, name), body);
+    upload?.file(name, body);
+  }
   writeFileSync(join(dir, "pr-note.md"), note);
 }
 
@@ -310,21 +326,32 @@ function printMembers(report: PrReport): void {
   }
 }
 
-async function finish(ctx: CommandContext, p: Prepared, report: PrReport): Promise<void> {
+async function finish(ctx: CommandContext, p: Prepared, report: PrReport, upload?: PrReportUpload): Promise<void> {
   const note = noteFor(report, p.forge);
-  writeOutputs(ctx, report, note);
+  writeOutputs(ctx, report, note, upload);
   await publish(p.forge, report, note);
   if (ctx.args.json) console.log(JSON.stringify(report, null, 2));
 }
 
-/** A stage's stream, held so that a stage that returns or throws before it settles still ends it. */
+/**
+ * A stage's stream and its `--report-url` upload, held so that a stage that
+ * returns or throws before it settles still ends the stream and uploads.
+ */
 interface StageEvents {
   stream?: RunEventStream;
+  /** Where `--report-url` points, read before the stage starts. */
+  target?: ReportTarget;
+  upload?: PrReportUpload;
 }
 
-/** Run a stage, and end its stream as `failed` when the stage did not settle it. */
-async function withStageEvents(stage: string, run: (events: StageEvents) => Promise<number>): Promise<number> {
+/** Run a stage, end its stream as `failed` when the stage did not settle it, and finish its upload. */
+async function withStageEvents(stage: string, ctx: CommandContext, run: (events: StageEvents) => Promise<number>): Promise<number> {
   const events: StageEvents = {};
+  if (ctx.args.reportUrl !== undefined) {
+    const target = parseReportUrl(ctx.args.reportUrl);
+    if ("error" in target) return fail(target.error);
+    events.target = target;
+  }
   try {
     return await run(events);
   } catch (err) {
@@ -332,13 +359,32 @@ async function withStageEvents(stage: string, run: (events: StageEvents) => Prom
     throw err;
   } finally {
     events.stream?.settle("failed", `${stage} stopped before it finished`);
+    if (events.upload) {
+      await events.upload.close();
+      console.error(formatInfo(`report  : ${events.upload.where}/`));
+    }
   }
 }
 
-/** chant components pr-plan --base <ref> --pr <n> [--env <env>] [--gate <name>] [--forge <kind>] [--output <dir>] [--json] [--events-json] */
+/**
+ * Open the stage's `--report-url` upload under its pull request and commit,
+ * when the flag was given. Its events are the lines `openCliRunEvents` writes.
+ */
+function openUpload(events: StageEvents, stage: "plan" | "apply", pr: number | null, p: Prepared): PrReportUpload | undefined {
+  if (!events.target) return undefined;
+  events.upload = openPrReportUpload({
+    target: events.target,
+    key: reportKey(pr, p.head, p.member),
+    stage,
+    warn: (message) => console.error(formatWarning({ message })),
+  });
+  return events.upload;
+}
+
+/** chant components pr-plan --base <ref> --pr <n> [--env <env>] [--gate <name>] [--forge <kind>] [--output <dir>] [--json] [--events-json] [--report-url <url>] */
 export function runComponentsPrPlan(ctx: CommandContext): Promise<number> {
   if (refusesEventsWithJson(ctx.args, "the stage's report")) return Promise.resolve(1);
-  return withStageEvents("pr-plan", (events) => prPlan(ctx, events));
+  return withStageEvents("pr-plan", ctx, (events) => prPlan(ctx, events));
 }
 
 async function prPlan(ctx: CommandContext, stage: StageEvents): Promise<number> {
@@ -348,8 +394,9 @@ async function prPlan(ctx: CommandContext, stage: StageEvents): Promise<number>
   const p = await prepare(ctx, "plan");
   if (typeof p === "number") return p;
   const op = prOp(ctx.args.pr, p.member);
+  const upload = openUpload(stage, "plan", ctx.args.pr, p);
   // `--events-json` (#4041): planning, then where the approval stands.
-  const events = await openCliRunEvents(ctx.args, { kind: "component", name: `pr-plan ${op}`, cwd: resolve(".") });
+  const events = await openCliRunEvents(ctx.args, { kind: "component", name: `pr-plan ${op}`, cwd: resolve(".") }, upload?.line);
   stage.stream = events;
   events?.emit({ type: "run-start", waves: p.plan.waves });
   const set = await planAll(p, events?.emit);
@@ -381,7 +428,7 @@ async function prPlan(ctx: CommandContext, stage: StageEvents): Promise<number>
     approval,
     status,
   });
-  await finish(ctx, p, report);
+  await finish(ctx, p, report, upload);
   // The plan stage settles on its planning: an approval still to come is what it reports, not a stop.
   events?.settle(settleOf(status), status === "plan-failed" ? "a member failed to plan" : undefined);
 
@@ -394,10 +441,10 @@ async function prPlan(ctx: CommandContext, stage: StageEvents): Promise<number>
   return status === "plan-failed" ? 1 : 0;
 }
 
-/** chant components pr-apply --base <ref> [--pr <n>] [--env <env>] [--gate <name>] [--forge <kind>] [--require-review] [--output <dir>] [--json] [--events-json] */
+/** chant components pr-apply --base <ref> [--pr <n>] [--env <env>] [--gate <name>] [--forge <kind>] [--require-review] [--output <dir>] [--json] [--events-json] [--report-url <url>] */
 export function runComponentsPrApply(ctx: CommandContext): Promise<number> {
   if (refusesEventsWithJson(ctx.args, "the stage's report")) return Promise.resolve(1);
-  return withStageEvents("pr-apply", (events) => prApply(ctx, events));
+  return withStageEvents("pr-apply", ctx, (events) => prApply(ctx, events));
 }
 
 async function prApply(ctx: CommandContext, stage: StageEvents): Promise<number> {
@@ -418,7 +465,8 @@ async function prApply(ctx: CommandContext, stage: StageEvents): Promise<number>
   // The run id the release records carry, chosen before the run so that
   // `--events-json` (#4041, #4007) names the run by it too.
   const release = autoReleaseRun(`${op}-${Date.now()}`);
-  const events = await openCliRunEvents(args, { kind: "component", name: `pr-apply ${op}`, runId: release.runId, cwd: resolve(".") });
+  const upload = openUpload(stage, "apply", pr, p);
+  const events = await openCliRunEvents(args, { kind: "component", name: `pr-apply ${op}`, runId: release.runId, cwd: resolve(".") }, upload?.line);
   stage.stream = events;
   events?.emit({ type: "run-start", waves: p.plan.waves });
 
@@ -434,15 +482,28 @@ async function prApply(ctx: CommandContext, stage: StageEvents): Promise<number>
       return fail(`--resume: could not read "${args.resume}": ${err instanceof Error ? err.message : String(err)}`);
     }
   }
-  const resumed = pr !== null && p.plan.order.length > 0 && attempt ? await tryResume(p, attempt, args.resume!, op) : undefined;
+  // What each component would apply now (#4081): progress carries only where it is unchanged.
+  const inputsNow = resumePath ? componentInputDigests(p.components, { projectRoot: resolve("."), env: p.env }) : {};
+  const resumed = pr !== null && p.plan.order.length > 0 && attempt ? await tryResume(p, attempt, args.resume!, op, inputsNow) : undefined;
 
-  if (resumed) emitResumedGate(events, op, p.gate, resumed.check);
+  // The components an earlier attempt applied settle first (#4007), each in
+  // the wave the derivation gave it, which is the run-start's.
+  const log = applyLog();
+  if (resumed) {
+    const waveOf = new Map(p.plan.waves.flatMap((wave, i) => wave.map((name) => [name, i + 1] as const)));
+    for (const component of p.plan.order.filter((name) => resumed.completed.includes(name))) {
+      const body: RunEventComponentSettle = { type: "component-settle", wave: waveOf.get(component)!, component, status: "already-applied" };
+      events?.emit(body);
+      log(body);
+    }
+    emitResumedGate(events, op, p.gate, resumed.check);
+  }
   const set = resumed?.set ?? (await planAll(p, events?.emit));
   const base = { stage: "apply" as const, pr, env: p.env, ...(p.member ? { member: p.member } : {}), base: p.base, head: p.head, op, gate: p.gate, plan: p.plan, signal: p.signal, set };
 
   const stop = async (report: PrReport, code: number, settle?: RunEventSettleStatus): Promise<number> => {
     events?.settle(settle ?? settleOf(report.status), report.status === "plan-failed" || report.status === "failed" ? report.message ?? `pr-apply ${report.status}` : undefined);
-    await finish(ctx, p, report);
+    await finish(ctx, p, report, upload);
     console.error((code === 0 ? formatInfo : (m: string) => formatWarning({ message: m }))(`pr-apply: ${report.status}${report.refusal ? ` (${report.refusal})` : ""}`));
     if (report.message) console.error(report.message);
     printMembers(report);
@@ -538,6 +599,9 @@ async function prApply(ctx: CommandContext, stage: StageEvents): Promise<number>
   // one settles, so a run killed partway still knows what applied.
   const prior = resumed ? { completed: resumed.completed, outputs: resumed.outputs } : { completed: [], outputs: {} };
   const completedSoFar = new Set<string>(prior.completed);
+  const inputsSoFar: Record<string, string> = Object.fromEntries(
+    prior.completed.filter((name) => inputsNow[name] !== undefined).map((name) => [name, inputsNow[name]!]),
+  );
   const failedSoFar: string[] = [];
   const outputsSoFar: Record<string, Record<string, unknown>> = { ...prior.outputs };
   const record: PrApplyRecord = {
@@ -557,6 +621,7 @@ async function prApply(ctx: CommandContext, stage: StageEvents): Promise<number>
       completed: [...completedSoFar].sort(),
       failed: [...failedSoFar].sort(),
       outputs: outputsSoFar,
+      inputs: Object.fromEntries(Object.entries(inputsSoFar).sort(([a], [b]) => a.localeCompare(b))),
       prApply: record,
     });
   };
@@ -569,13 +634,18 @@ async function prApply(ctx: CommandContext, stage: StageEvents): Promise<number>
     env: p.env,
     set,
     ...(resumed ? { resumed: prior } : {}),
-    // The apply is this run's waves, so the fan-out's own run framing is dropped.
-    ...(events ? { onRunEvent: events.nested } : {}),
+    // The apply is this run's waves, so the fan-out's own run framing is
+    // dropped. The log's lines go to stderr with or without --events-json.
+    onRunEvent: (body: RunEventBody) => {
+      events?.nested(body);
+      log(body);
+    },
     ...(resumePath
       ? {
           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);
@@ -600,6 +670,37 @@ async function prApply(ctx: CommandContext, stage: StageEvents): Promise<number>
   return code;
 }
 
+/** What a component's settle says in the job log. */
+function settleWords(body: RunEventComponentSettle): string {
+  switch (body.status) {
+    case "ok":
+      return "applied";
+    case "failed":
+      return "failed";
+    case "gated":
+      return "stopped at its own gate";
+    case "waiting":
+      return "waiting on a decision";
+    case "blocked":
+      return `blocked by ${body.blockedBy ?? "a dependency"}, not run`;
+    case "already-applied":
+      return "already applied in an earlier attempt";
+  }
+}
+
+/**
+ * pr-apply's job log (#4007): a line on stderr as each wave starts and as
+ * each component settles, so the log shows the waves in order while they run.
+ */
+function applyLog(): (body: RunEventBody) => void {
+  let waves = 0;
+  return (body) => {
+    if (body.type === "run-start") waves = body.waves?.length ?? 0;
+    else if (body.type === "wave-start") console.error(formatInfo(`wave ${body.wave}${waves ? `/${waves}` : ""}: ${body.components.join(", ")}`));
+    else if (body.type === "component-settle") console.error(formatInfo(`  ${body.component}: ${settleWords(body)}`));
+  };
+}
+
 /** A resumed apply's gate (#3464), decided against the approved digest, as the run's `gate` phase. */
 function emitResumedGate(events: RunEventStream | undefined, op: string, gate: string, check: GateCheck): void {
   if (!events) return;
@@ -658,8 +759,13 @@ interface Resumed {
  * derivation; when its approval still stands; and when every member left is
  * covered by the approved set. Otherwise it says why on stderr and the apply
  * runs as it would with no record.
+ *
+ * Of the components it applied, only those whose input digest is the same
+ * now carry (#4081), as in `components fan-out --resume`. One that changed
+ * runs again, under the same approval when the approved set covers its new
+ * plan. A record without input digests carries nothing.
  */
-async function tryResume(p: Prepared, attempt: FanOutAttempt, file: string, op: string): Promise<Resumed | undefined> {
+async function tryResume(p: Prepared, attempt: FanOutAttempt, file: string, op: string, inputsNow: Record<string, string>): Promise<Resumed | undefined> {
   const skip = (why: string): undefined => {
     console.error(formatWarning({ message: `--resume: "${file}" does not carry: ${why}`, hint: "Every member is planned again, and the plan needs an approval of its own." }));
     return undefined;
@@ -670,6 +776,11 @@ async function tryResume(p: Prepared, attempt: FanOutAttempt, file: string, op:
   if (record.head !== p.head) return skip(`it records an apply of ${record.head.slice(0, 12)}, not ${p.head.slice(0, 12)}`);
   if (!samePlanDigest(attempt.digest, p.plan.digest)) return skip("the change selects other components than it did");
   if (attempt.completed.length === 0) return undefined;
+  const split = progressThatCarries(attempt, inputsNow);
+  if (split.unrecorded) return skip("it does not record what each component applied, since it was written before chant recorded component inputs");
+  for (const name of split.changed) console.error(formatInfo(`${name}: changed since the earlier attempt, so it runs again`));
+  if (split.carried.length === 0) return undefined;
+  const completed = split.carried;
 
   let check;
   try {
@@ -679,7 +790,7 @@ async function tryResume(p: Prepared, attempt: FanOutAttempt, file: string, op:
   }
   if (!check.satisfied) return skip(`no approval stands for the plan it applied (${record.digest}) any more`);
 
-  const outputs = Object.fromEntries(Object.entries(attempt.outputs).filter(([name]) => attempt.completed.includes(name)));
+  const outputs = Object.fromEntries(Object.entries(attempt.outputs).filter(([name]) => completed.includes(name)));
   const resumed = await resumePrSet({
     components: p.components,
     plan: p.plan,
@@ -687,9 +798,9 @@ async function tryResume(p: Prepared, attempt: FanOutAttempt, file: string, op:
     env: p.env,
     seededOutputs: p.seededOutputs,
     record,
-    completed: attempt.completed,
+    completed,
   });
   if (!resumed.ok) return skip(`what is left is not what was approved. ${resumed.reasons.join("; ")}`);
-  console.error(formatInfo(`resume  : ${attempt.completed.join(", ")} applied in an earlier attempt; applying ${resumed.plan.order.join(", ") || "nothing more"} under the approval of ${record.digest}`));
-  return { plan: resumed.plan, set: resumed.set, check, approval: approvalOf(check), completed: attempt.completed, outputs };
+  console.error(formatInfo(`resume  : ${completed.join(", ")} applied in an earlier attempt; applying ${resumed.plan.order.join(", ") || "nothing more"} under the approval of ${record.digest}`));
+  return { plan: resumed.plan, set: resumed.set, check, approval: approvalOf(check), completed, outputs };
 }