@intentius/chant 0.124.33 → 0.124.35

package/src/components/pr-pipeline.ts

@@ -196,10 +196,23 @@ export interface PrLoopJob {
   env: Record<string, string>;
   /** Shell lines to run before the command, to settle values the forge may leave unusable. */
   setup?: string[];
+  /**
+   * Shell lines a generated job runs first, before `setup`, to check out the
+   * commit it works on (#4168 step 9): the apply checks out the newest green
+   * commit. `chant ci run` and `ci serve` already run the job at that commit,
+   * so they skip these.
+   */
+  checkout?: string[];
   /** With `build` (#4088): the build line and the lint line, run in this order before the command. */
   build?: string[];
   /** With `waveGate` (#4003): the wave a generated apply job runs, 1-based. */
   wave?: number;
+  /**
+   * The branch an apply job takes its green commit from (#4168 step 9). A
+   * wave after the first checks out the commit wave 1 took, which the job
+   * receives as `GREEN_SHA` (#4221).
+   */
+  greenBranch?: string;
   /**
    * What the generated job runs in place of `command` (#4156): `chant ci run
    * <job> --in-place` with the same environment, gate, forge, events and
@@ -241,7 +254,7 @@ export function prLoopJobs(forge: ForgeKind, env: string, options: PrLoopPipelin
   // #4156: the flags `chant ci run` rebuilds `command` from. It finds the member from the directory it runs in.
   const ciRun = (job: PrLoopJob["jobName"]): string[] => [
     "chant", "ci", "run", job, "--in-place", ...(job === "plan" ? ["--no-push"] : []),
-    "--base", '"$BASE_SHA"', ...(job === "plan" ? ["--pr", '"$PR_NUMBER"'] : []),
+    ...(job === "apply" ? [] : ["--base", '"$BASE_SHA"']), ...(job === "plan" ? ["--pr", '"$PR_NUMBER"'] : []),
     "--env", env, "--gate", gate, "--forge", forge,
     ...(job !== "record" && options.waveGate ? ["--wave-gate", options.waveGate] : []),
     ...(job !== "plan" && options.branch ? ["--branch", JSON.stringify(options.branch)] : []),
@@ -254,6 +267,7 @@ export function prLoopJobs(forge: ForgeKind, env: string, options: PrLoopPipelin
   const planEnv = github
     ? { BASE_SHA: "${{ github.event.pull_request.base.sha }}", PR_NUMBER: "${{ github.event.pull_request.number }}", ...jobEnv }
     : { BASE_SHA: "$CI_MERGE_REQUEST_DIFF_BASE_SHA", PR_NUMBER: "$CI_MERGE_REQUEST_IID", ...jobEnv };
+  const greenBranch = github ? JSON.stringify(options.branch ?? "main") : options.branch ? JSON.stringify(options.branch) : "$CI_DEFAULT_BRANCH";
   const applyEnv = github ? { BASE_SHA: "${{ github.event.before }}", ...jobEnv } : { BASE_SHA: "$CI_COMMIT_BEFORE_SHA", ...jobEnv };
   return [
     {
@@ -265,17 +279,19 @@ export function prLoopJobs(forge: ForgeKind, env: string, options: PrLoopPipelin
       run: { command: ciRun("plan").join(" "), env: runEnv(planEnv) },
     },
     {
+      // #4168 step 9: the apply applies the newest green commit, measured from the one applied before it.
       jobName: "apply",
       command: [
-        "chant", "components", "pr-apply", "--base", '"$BASE_SHA"', ...common,
+        "chant", "components", "pr-apply", "--green", ...common,
         ...(options.requireReview === true ? ["--require-review"] : []),
         ...(options.waveGate ? ["--wave-gate", options.waveGate] : []),
         "--resume", PR_APPLY_RECORD,
       ].join(" "),
-      env: applyEnv,
-      setup: [github ? githubBaseFallback(options.branch) : gitlabBaseFallback(options.branch)],
+      env: jobEnv,
+      checkout: [greenCheckout(greenBranch)],
+      greenBranch,
       ...build,
-      run: { command: ciRun("apply").join(" "), env: runEnv(applyEnv) },
+      run: { command: ciRun("apply").join(" "), env: runEnv(jobEnv) },
     },
     {
       jobName: "record",
@@ -288,6 +304,15 @@ export function prLoopJobs(forge: ForgeKind, env: string, options: PrLoopPipelin
   ];
 }
 
+/**
+ * What starts the apply under apply on merge (#4168 step 9): on GitHub the
+ * tick's workflow finishing (`workflow_run`, since tags its token pushes start
+ * no workflow), elsewhere a pushed `ci/green/*` tag. The name is
+ * `CI_GREEN_WORKFLOW_NAME` (../workspace/ci-green-workflow.ts).
+ */
+export const GREEN_TICK_WORKFLOW = "chant-ci-green";
+export const GREEN_TAG_PATTERN = "ci/green/**";
+
 /** The job a push to the target branch runs (#4168): `record`, or `apply` when the pipeline opts into apply on merge. */
 export function prLoopMergeJob(jobs: readonly PrLoopJob[], options: PrLoopPipelineOptions = {}): PrLoopJob {
   return jobs.find((j) => j.jobName === (options.applyOnMerge ? "apply" : "record"))!;
@@ -326,6 +351,8 @@ export function prLoopWaveJobs(components: DriverComponent[], apply: PrLoopJob):
     ...apply,
     command: `${apply.command} --wave ${i + 1}`,
     wave: i + 1,
+    // #4221: every wave after the first applies the commit wave 1 took.
+    ...(i > 0 && apply.greenBranch !== undefined ? { checkout: [pinnedGreenCheckout(apply.greenBranch)] } : {}),
     // #4156: the job runs it through chant ci run, which appends the same --wave to pr-apply.
     run: { ...apply.run, command: `${apply.run.command} --wave ${i + 1}` },
   }));
@@ -381,6 +408,30 @@ function pushBaseFallback(target: string, commit: string, diffBase?: string): st
   );
 }
 
+/**
+ * The line that checks out the newest green commit of `branch` (#4168 step
+ * 9), after fetching the branch and its tags, for the apply job. `chant ci
+ * last-green` exits 1 when no commit is green, which fails the job.
+ */
+export function greenCheckout(branch: string): string {
+  return `${fetchBranch(branch)} && GREEN_SHA="$(chant ci last-green)" && git checkout --quiet --detach "$GREEN_SHA"`;
+}
+
+/**
+ * The line a wave after the first runs in place of {@link greenCheckout}
+ * (#4221): it checks out `GREEN_SHA`, the commit wave 1 took, so a commit
+ * that goes green while the waves run waits for a run of its own. An empty
+ * `GREEN_SHA` fails the job.
+ */
+export function pinnedGreenCheckout(branch: string): string {
+  return `test -n "$GREEN_SHA" && ${fetchBranch(branch)} && git checkout --quiet --detach "$GREEN_SHA"`;
+}
+
+function fetchBranch(branch: string): string {
+  const name = branch.replace(/^"|"$/g, "");
+  return `git fetch --quiet --tags origin "+refs/heads/${name}:refs/remotes/origin/${name}"`;
+}
+
 /**
  * GitLab sets `CI_COMMIT_BEFORE_SHA` to forty zeros on a branch's first push.
  * The line replaces it with the merge request's diff base when the pipeline

package/src/components/promote-rounds.test.ts

@@ -0,0 +1,220 @@
+/**
+ * Rounds and per-wave gates at promote (#4168 step 4): a dependent planned
+ * against its upstream's planned outputs is planned again once the upstream
+ * applied as another value, and `--wave-gate` checks each wave.
+ */
+
+import { describe, expect, test } from "vitest";
+import { composeChangeSet, type ChangeSetDocument } from "../change-set";
+import type { DriverComponent, DriverRunResult, ReleaseGateBinding } from "./driver";
+import { movedInputs, renameGates, runPromotionInRounds } from "./promote-rounds";
+
+const sha = (c: string) => `sha256:${c.repeat(64)}`;
+
+const net: DriverComponent = { name: "net", deploy: [{ phase: "Apply", steps: [{ kind: "gate", gate: "prod-release" }, { kind: "tf", name: "net" }] }] };
+const svc: DriverComponent = {
+  name: "svc",
+  dependsOn: ["net"],
+  deploy: [{ phase: "Apply", steps: [{ kind: "gate", gate: "prod-release" }, { kind: "tf", name: "svc", vpc: { stackOutput: { stack: "net", name: "id" } } }] }],
+};
+
+/** A change set of one planned member per name, each at the digest given; `writes` adds an update of that member's `vpc`. */
+const doc = (members: Record<string, string>, writes: Record<string, string> = {}): ChangeSetDocument =>
+  composeChangeSet(
+    Object.entries(members).map(([member, digest]) => ({
+      member: { member, lexicon: "terraform", planner: "terraform" as const, status: "planned" as const, planDigest: digest, holes: [] },
+      entries: writes[member]
+        ? [{ member, lexicon: "terraform", planner: "terraform" as const, address: `${member}.main`, type: "x", name: "main", action: "update" as const, attributes: [{ path: "vpc", after: writes[member] }] }]
+        : [],
+    })),
+  );
+
+const approved = doc({ net: sha("1"), svc: sha("2") }, { svc: "vpc-new" });
+const binding: ReleaseGateBinding = { op: "release", planDigest: approved.digest, releaseDigest: sha("r") };
+
+/** A run that applies every component and leaves `exposes` as its outputs, recording what it was handed. */
+function runner(exposes: Record<string, Record<string, unknown>>) {
+  const calls: Array<{ names: string[]; gates: string[]; binding: string; outputs: Record<string, Record<string, unknown>> }> = [];
+  const run = async (components: DriverComponent[], outputs: Record<string, Record<string, unknown>>, b: ReleaseGateBinding): Promise<DriverRunResult> => {
+    const gates = components.flatMap((c) => c.deploy.flatMap((p) => p.steps.filter((s) => (s as { kind?: string }).kind === "gate").map((s) => (s as { gate: string }).gate)));
+    calls.push({ names: components.map((c) => c.name), gates, binding: b.planDigest, outputs });
+    const out = { ...outputs };
+    for (const c of components) if (exposes[c.name]) out[c.name] = exposes[c.name];
+    return {
+      order: components.map((c) => c.name),
+      waves: [components.map((c) => c.name)],
+      results: components.map((c) => ({ component: c.name, ok: true, status: "ok" as const, records: [] })),
+      ok: true,
+      status: "ok",
+      componentOutputs: out,
+    };
+  };
+  return { run, calls };
+}
+
+const bindings: string[][] = [];
+const bind = async (d: ChangeSetDocument, gates: string[]): Promise<ReleaseGateBinding> => {
+  bindings.push(gates);
+  return { op: "release", planDigest: d.digest, releaseDigest: sha("r") };
+};
+
+describe("movedInputs", () => {
+  test("names each reference that resolves to another value than its plan read", () => {
+    expect(movedInputs(svc, { net: { id: "vpc-new" } }, { net: { id: "vpc-new" } })).toEqual([]);
+    expect(movedInputs(svc, { net: { id: "vpc-new" } }, { net: { id: "vpc-other" } })).toEqual(["net.id"]);
+    expect(movedInputs(svc, undefined, { net: { id: "x" } })).toEqual([]);
+  });
+});
+
+describe("renameGates", () => {
+  test("renames every gate, nested phases included, and drops the old key", () => {
+    const c: DriverComponent = { name: "x", deploy: [{ phase: "A", steps: [{ phase: "B", steps: [{ kind: "gate", signalName: "old" }] }, { kind: "gate", gate: "g" }] }] };
+    const renamed = renameGates(c, (g) => `${g}-round-2`);
+    expect(JSON.stringify(renamed)).toContain('"gate":"old-round-2"');
+    expect(JSON.stringify(renamed)).toContain('"gate":"g-round-2"');
+    expect(JSON.stringify(renamed)).not.toContain("signalName");
+  });
+});
+
+describe("runPromotionInRounds", () => {
+  test("an upstream that applies as its plan said leaves the dependent under the approval it has", async () => {
+    const { run, calls } = runner({ net: { id: "vpc-new" } });
+    const result = await runPromotionInRounds({
+      components: [svc, net],
+      outputs: {},
+      binding,
+      approved,
+      reads: { svc: { net: { id: "vpc-new" } } },
+      run,
+      replan: async () => { throw new Error("not planned again"); },
+      bind,
+    });
+    expect(result.run.status).toBe("ok");
+    expect(result.stages).toEqual([]);
+    expect(calls.map((c) => [c.names, c.binding])).toEqual([[["net"], approved.digest], [["svc"], approved.digest]]);
+    expect(calls[1].outputs).toEqual({ net: { id: "vpc-new" } });
+    expect(result.completed).toEqual(["net", "svc"]);
+  });
+
+  test("an upstream that applies as another value plans the dependent again; a covered plan applies under the approval", async () => {
+    const { run, calls } = runner({ net: { id: "vpc-other" } });
+    const result = await runPromotionInRounds({
+      components: [net, svc],
+      outputs: {},
+      binding,
+      approved,
+      reads: { svc: { net: { id: "vpc-new" } } },
+      run,
+      replan: async () => doc({ svc: sha("2") }, { svc: "vpc-new" }),
+      bind,
+    });
+    expect(result.stages).toEqual([]);
+    expect(calls[1]).toMatchObject({ names: ["svc"], binding: approved.digest, gates: ["prod-release"] });
+  });
+
+  test("a moved plan the approval does not cover waits at <gate>-round-2, bound to the new digest", async () => {
+    const { run, calls } = runner({ net: { id: "vpc-other" } });
+    const fresh = doc({ svc: sha("9") }, { svc: "vpc-other" });
+    const result = await runPromotionInRounds({
+      components: [net, svc],
+      outputs: {},
+      binding,
+      approved,
+      reads: { svc: { net: { id: "vpc-new" } } },
+      run,
+      replan: async (only, outputs) => {
+        expect([...only]).toEqual(["svc"]);
+        expect(outputs).toEqual({ net: { id: "vpc-other" } });
+        return fresh;
+      },
+      bind,
+    });
+    expect(result.stages).toHaveLength(1);
+    expect(result.stages[0]).toMatchObject({ kind: "round", number: 2, components: ["svc"], digest: fresh.digest, status: "applied" });
+    expect(result.stages[0].notCovered[0]).toMatch(/svc/);
+    expect(calls[1]).toMatchObject({ names: ["svc"], binding: fresh.digest, gates: ["prod-release-round-2"] });
+  });
+
+  test("--wave-gate checks every wave after the first and names one gate per wave", async () => {
+    const { run, calls } = runner({ net: { id: "vpc-new" } });
+    const fresh = doc({ svc: sha("8") }, { svc: "vpc-other" });
+    const result = await runPromotionInRounds({
+      components: [net, svc],
+      outputs: {},
+      binding,
+      approved,
+      reads: { svc: { net: { id: "vpc-new" } } },
+      waveGate: "deploy",
+      run,
+      replan: async () => fresh,
+      bind,
+    });
+    expect(result.stages[0]).toMatchObject({ kind: "wave", number: 2, digest: fresh.digest });
+    expect(calls[1].gates).toEqual(["deploy-wave-2"]);
+  });
+
+  test("a stage whose components declare no gate stops with nothing more deployed", async () => {
+    const plain: DriverComponent = { ...svc, deploy: [{ phase: "Apply", steps: [{ kind: "tf", name: "svc", vpc: { stackOutput: { stack: "net", name: "id" } } }] }] };
+    const { run, calls } = runner({ net: { id: "vpc-other" } });
+    const result = await runPromotionInRounds({
+      components: [net, plain],
+      outputs: {},
+      binding,
+      approved,
+      reads: { svc: { net: { id: "vpc-new" } } },
+      run,
+      replan: async () => doc({ svc: sha("9") }, { svc: "vpc-other" }),
+      bind,
+    });
+    expect(result.run.status).toBe("fail");
+    expect(result.stages[0]).toMatchObject({ status: "failed" });
+    expect(result.stages[0].message).toMatch(/no gate/);
+    expect(calls.map((c) => c.names)).toEqual([["net"]]);
+  });
+
+  test("a resume skips what applied and starts from the outputs it kept", async () => {
+    const { run, calls } = runner({});
+    const result = await runPromotionInRounds({
+      components: [net, svc],
+      outputs: { net: { id: "vpc-new" } },
+      binding,
+      approved,
+      reads: { svc: { net: { id: "vpc-new" } } },
+      completed: ["net"],
+      run,
+      replan: async () => { throw new Error("not planned again"); },
+      bind,
+    });
+    expect(calls.map((c) => c.names)).toEqual([["svc"]]);
+    expect(result.completed).toEqual(["net", "svc"]);
+  });
+
+  test("a gated wave stops the run and leaves what applied", async () => {
+    const calls: string[][] = [];
+    const result = await runPromotionInRounds({
+      components: [net, svc],
+      outputs: {},
+      binding,
+      approved,
+      reads: {},
+      run: async (components, outputs) => {
+        calls.push(components.map((c) => c.name));
+        return {
+          order: ["net"],
+          waves: [["net"]],
+          results: [{ component: "net", ok: false, status: "gated", records: [] }],
+          ok: false,
+          status: "gated",
+          gatedComponent: "net",
+          componentOutputs: outputs,
+        };
+      },
+      replan: async () => approved,
+      bind,
+    });
+    expect(result.run.status).toBe("gated");
+    expect(result.run.gatedComponent).toBe("net");
+    expect(calls).toEqual([["net"]]);
+    expect(result.completed).toEqual([]);
+  });
+});

package/src/components/promote-rounds.ts

@@ -0,0 +1,232 @@
+/**
+ * A promote under a release that plans again once an upstream applied, and a
+ * gate per wave (#4168 step 4). Merging deploys nothing since step 1, so what
+ * `pr-apply` did on merge happens here, at promote:
+ *
+ * - **Rounds** (#3999's rule, `../pr-loop.ts`). The release gate approves a
+ *   change set in which each dependent was planned against its upstream's
+ *   planned outputs (`planReleaseSet` in ./release-gate.ts). The promote runs
+ *   a wave at a time. Before a wave runs, a component whose plan read an
+ *   upstream output that the run left as another value
+ *   (`movedWiringReferences`) is planned again against what stands. When the
+ *   approved change set covers the new plan (`waveNotCovered`, the test a
+ *   pull request's resume uses), it applies under the approval it has.
+ *   Otherwise its gates are decided as `<gate>-round-<n>` (`prRoundGate`),
+ *   bound to the new plan's digest.
+ * - **A gate per wave** (`--wave-gate <gate>`, #4157's rule). Every wave
+ *   after the first is planned again against what the waves before it left,
+ *   and a wave the approved change set does not cover waits at
+ *   `<gate>-wave-<k>` (`waveGateName`), one gate for the whole wave, bound to
+ *   that wave's digest.
+ *
+ * A stage whose components declare no gate has nowhere to wait, so the
+ * promote stops there with nothing more deployed.
+ *
+ * A promote that stops at a round's or a wave's gate writes a resume record
+ * ({@link PromoteResume}): the components that applied and the outputs they
+ * left. The same promote run again with it skips what applied and carries on
+ * from the wave it stopped at, so an approval of the round or wave it waits on
+ * is decided against the same plan.
+ */
+
+import { movedWiringReferences, type DriverComponent, type DriverGate, type DriverPhase, type DriverRunResult, type DriverStep, type ReleaseGateBinding } from "./driver";
+import { resolveComponentGraph } from "./driver";
+import { waveNotCovered } from "./pr-run";
+import { prRoundGate } from "../pr-loop";
+import { waveGateName } from "../gated-waves";
+import { capabilitySteps } from "./wave-plan";
+import type { ChangeSetDocument } from "../change-set";
+import type { ReleasePlan } from "./release-gate";
+
+export const PROMOTE_RESUME_SCHEMA = "chant-promote-resume/v1";
+
+/** What a promote that stopped at a round's or a wave's gate leaves for the next attempt. */
+export interface PromoteResume {
+  schema: typeof PROMOTE_RESUME_SCHEMA;
+  env: string;
+  releaseDigest: string;
+  /** The change set the release gate approved before anything applied. */
+  approvedDigest: string;
+  /** Components that applied, in run order. */
+  completed: string[];
+  /** The outputs standing after them. */
+  outputs: Record<string, Record<string, unknown>>;
+  /** ISO 8601. */
+  at: string;
+}
+
+/** One round or wave that needed its own approval. */
+export interface PromoteStage {
+  kind: "round" | "wave";
+  /** The round number (2 and up) or the wave number (1-based). */
+  number: number;
+  components: string[];
+  /** The plan the stage's gates bind. */
+  digest: string;
+  /** Why the approved change set did not cover it, one line per member. */
+  notCovered: string[];
+  status: "applied" | "waiting" | "failed";
+  /** With `failed` before anything ran: why. */
+  message?: string;
+}
+
+export interface PromoteRoundsOptions {
+  /** The promoted compositions, in no particular order. */
+  components: DriverComponent[];
+  /** Outputs standing before the run: the seeds, and on a resume the record's. */
+  outputs: Record<string, Record<string, unknown>>;
+  /** The release gate the change set was approved under. */
+  binding: ReleaseGateBinding;
+  /** The approved change set, and what each component's plan read. */
+  approved: ChangeSetDocument;
+  reads: ReleasePlan["reads"];
+  /** Components an earlier attempt applied. Skipped. */
+  completed?: readonly string[];
+  /** `--wave-gate <gate>`: check every wave after the first, not only the components whose inputs moved, and name a wave's gate `<gate>-wave-<k>`. */
+  waveGate?: string;
+  /** Run one subset of the components with `outputs` standing (`runPromotion` with the binding). */
+  run: (components: DriverComponent[], outputs: Record<string, Record<string, unknown>>, binding: ReleaseGateBinding) => Promise<DriverRunResult>;
+  /** Plan `only` again with `outputs` standing (`planReleaseSet`). */
+  replan: (only: ReadonlySet<string>, outputs: Record<string, Record<string, unknown>>) => Promise<ChangeSetDocument>;
+  /** Store a stage's plan and bind its gates (empty resolutions included). */
+  bind: (doc: ChangeSetDocument, gates: string[]) => Promise<ReleaseGateBinding>;
+}
+
+export interface PromoteRoundsResult {
+  run: DriverRunResult;
+  /** The rounds and waves that needed their own approval. */
+  stages: PromoteStage[];
+  /** Every component that applied, earlier attempts included, in run order. */
+  completed: string[];
+  outputs: Record<string, Record<string, unknown>>;
+}
+
+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);
+}
+
+/** `component` with each gate renamed by `rename`, nested phases included. */
+export function renameGates(component: DriverComponent, rename: (gate: string) => string): DriverComponent {
+  const walk = (phase: DriverPhase): DriverPhase => ({
+    ...phase,
+    steps: phase.steps.map((step) => {
+      if (isPhase(step)) return walk(step);
+      if (!isGate(step)) return step;
+      const { signalName: _old, ...rest } = step;
+      return { ...rest, gate: rename(step.gate ?? step.signalName ?? "") };
+    }),
+  });
+  return { ...component, deploy: component.deploy.map(walk) };
+}
+
+/** The gate names `components` declare, sorted and distinct. */
+function gatesOf(components: readonly DriverComponent[]): string[] {
+  const names = new Set<string>();
+  const walk = (steps: DriverPhase["steps"]): void => {
+    for (const step of steps) {
+      if (isPhase(step)) walk(step.steps);
+      else if (isGate(step)) names.add(step.gate ?? step.signalName ?? "");
+    }
+  };
+  for (const c of components) for (const phase of c.deploy) walk(phase.steps);
+  return [...names].sort();
+}
+
+/** The references `component`'s steps make that resolve to another value now than when its plan read them. */
+export function movedInputs(component: DriverComponent, read: Record<string, Record<string, unknown>> | undefined, now: Record<string, Record<string, unknown>>): string[] {
+  if (!read) return [];
+  const moved = new Set<string>();
+  for (const step of capabilitySteps(component.deploy)) {
+    const { kind: _kind, ...rest } = step;
+    for (const r of movedWiringReferences(rest, read, now)) if (!r.publish) moved.add(r.ref);
+  }
+  return [...moved].sort();
+}
+
+function joinRuns(runs: DriverRunResult[], outputs: Record<string, Record<string, unknown>>): DriverRunResult {
+  const last = runs[runs.length - 1];
+  const base: DriverRunResult = {
+    order: runs.flatMap((r) => r.order),
+    waves: runs.flatMap((r) => r.waves),
+    results: runs.flatMap((r) => r.results),
+    ok: runs.every((r) => r.ok),
+    status: "ok",
+    componentOutputs: outputs,
+  };
+  if (!last || last.status === "ok") return base;
+  const { order: _o, waves: _w, results: _r, ok: _ok, componentOutputs: _c, ...stop } = last;
+  return { ...base, ...stop, ok: false };
+}
+
+/**
+ * Run the promote a wave at a time, planning again where an upstream applied
+ * as another value, and with `waveGate`, checking each wave. Stops at the
+ * first wave that fails or waits on a gate.
+ */
+export async function runPromotionInRounds(options: PromoteRoundsOptions): Promise<PromoteRoundsResult> {
+  const byName = new Map(options.components.map((c) => [c.name, c]));
+  const { waves } = resolveComponentGraph(options.components.map((c) => ({ ...c, dependsOn: (c.dependsOn ?? []).filter((d) => byName.has(d)) })));
+  const completed = [...(options.completed ?? [])];
+  const done = new Set(completed);
+  let outputs = { ...options.outputs };
+  const runs: DriverRunResult[] = [];
+  const stages: PromoteStage[] = [];
+  let round = 1;
+
+  for (const [index, wave] of waves.entries()) {
+    const waveNumber = index + 1;
+    const pending = wave.filter((name) => !done.has(name));
+    if (pending.length === 0) continue;
+    const check = options.waveGate !== undefined && waveNumber > 1
+      ? pending
+      : pending.filter((name) => movedInputs(byName.get(name)!, options.reads[name], outputs).length > 0);
+    const batches: Array<{ names: string[]; binding: ReleaseGateBinding; stage?: PromoteStage; rename?: (g: string) => string }> = [];
+    const rest = pending.filter((name) => !check.includes(name));
+    if (check.length > 0) {
+      const fresh = await options.replan(new Set(check), outputs);
+      const notCovered = waveNotCovered(options.approved, fresh);
+      if (notCovered.length === 0) {
+        rest.push(...check);
+      } else {
+        const kind: PromoteStage["kind"] = options.waveGate !== undefined ? "wave" : "round";
+        if (kind === "round") round += 1;
+        const number = kind === "wave" ? waveNumber : round;
+        const base = options.waveGate;
+        const rename = (g: string) => (base !== undefined ? waveGateName(base, number) : prRoundGate(g, number));
+        const renamed = check.map((name) => renameGates(byName.get(name)!, rename));
+        const gates = gatesOf(renamed);
+        const stage: PromoteStage = { kind, number, components: check, digest: fresh.digest, notCovered, status: "waiting" };
+        stages.push(stage);
+        if (gates.length === 0) {
+          stage.status = "failed";
+          stage.message = `${check.join(", ")} planned again past the approved change set and declare${check.length === 1 ? "s" : ""} no gate to approve the new plan on`;
+          const stop: DriverRunResult = { order: [], waves: [], results: [], ok: false, status: "fail", failedComponent: check[0], componentOutputs: outputs };
+          return { run: joinRuns([...runs, stop], outputs), stages, completed, outputs };
+        }
+        const binding = await options.bind(fresh, gates);
+        batches.push({ names: check, binding, stage, rename });
+      }
+    }
+    if (rest.length > 0) batches.unshift({ names: pending.filter((n) => rest.includes(n)), binding: options.binding });
+
+    for (const batch of batches) {
+      const components = batch.names.map((name) => (batch.rename ? renameGates(byName.get(name)!, batch.rename) : byName.get(name)!));
+      const run = await options.run(components, outputs, batch.binding);
+      runs.push(run);
+      outputs = { ...outputs, ...run.componentOutputs };
+      for (const r of run.results) {
+        if (r.status === "ok" && !done.has(r.component)) {
+          done.add(r.component);
+          completed.push(r.component);
+        }
+      }
+      if (batch.stage) batch.stage.status = run.status === "ok" ? "applied" : run.status === "gated" ? "waiting" : "failed";
+      if (run.status !== "ok") return { run: joinRuns(runs, outputs), stages, completed, outputs };
+    }
+  }
+  return { run: joinRuns(runs, outputs), stages, completed, outputs };
+}

package/src/components/promote.test.ts

@@ -197,6 +197,13 @@ describe("taking the build out of a composition", () => {
     expect("error" in prepared && prepared.error).toMatch(/no publish step/);
   });
 
+  test("#4222: no publish step passes when a release records its templates, and says it is template-only", () => {
+    const c: DriverComponent = { name: "chart", deploy: [{ phase: "Apply", steps: [{ kind: "helm-upgrade" }] }] };
+    const prepared = withoutBuildSteps(c, { templatesPinned: true });
+    expect("error" in prepared).toBe(false);
+    expect("templateOnly" in prepared && prepared.templateOnly).toBe(true);
+  });
+
   test("two publish steps are refused", () => {
     const c = service("api");
     c.deploy[1].steps.push({ kind: "publish-artifact", from: "archive:x.jar" });

package/src/components/promote.ts

@@ -23,7 +23,7 @@
  *
  * A composition the transform cannot pin to one recorded digest is refused
  * before anything runs: one with no publish step (nothing would carry the
- * digest), one with more than one (the ledger records one digest per
+ * digest) unless a release records its templates (#4222), one with more than one (the ledger records one digest per
  * component), and one whose remaining steps read an output of a removed build
  * step (it would resolve to nothing).
  *
@@ -402,6 +402,8 @@ export interface PromotableComponent {
   component: DriverComponent;
   /** The kinds removed, in composition order. */
   removed: string[];
+  /** #4222: the component has no publish step and deploys the templates a release records, so its record carries their digest. */
+  templateOnly?: boolean;
 }
 
 /**
@@ -433,7 +435,7 @@ export const recordedDigestCapability: Capability<{ digest: string }, { digest:
  */
 export function withoutBuildSteps(
   component: DriverComponent,
-  opts: { pinDigest?: string; verb?: string } = {},
+  opts: { pinDigest?: string; verb?: string; templatesPinned?: boolean } = {},
 ): PromotableComponent | { error: string } {
   const verb = opts.verb ?? (opts.pinDigest === undefined ? "a promote" : "a rollback");
   const removed: string[] = [];
@@ -487,7 +489,10 @@ export function withoutBuildSteps(
 
   const deploy = component.deploy.map(strip).filter((p): p is DriverPhase => p !== undefined);
 
-  if (publishSteps === 0) {
+  // #4222: under a release that records this component's templates, the
+  // deploy reads them from the release (./release-promote.ts), so a component
+  // with no artifact deploys the release's content, not its current source.
+  if (publishSteps === 0 && !opts.templatesPinned) {
     return {
       error: `component "${component.name}" has no publish step, so nothing in its deploy carries a recorded digest; ` +
         `${verb} would deploy whatever its current source produces`,
@@ -519,7 +524,7 @@ export function withoutBuildSteps(
       }
     }
   }
-  return { component: { ...component, deploy }, removed };
+  return { component: { ...component, deploy }, removed, ...(publishSteps === 0 ? { templateOnly: true } : {}) };
 }
 
 /** Every same-project wiring reference anywhere in a step's fields (cross-stack `stackOutput` objects excluded). */