@intentius/chant 0.124.31 → 0.124.33

package/src/components/deploy-inputs.ts

@@ -0,0 +1,225 @@
+/**
+ * The local files a component's steps deploy from, and their content digests
+ * (#4155).
+ *
+ * A component gate approves `componentPlanDigest` (./gate-plan.ts). A step
+ * whose capability has a `plan` is bound by what it plans. Every other step
+ * was bound only by its input as written, so a Helm chart, a kustomize
+ * directory or a static site's tree could change after review without moving
+ * the digest. This module names those files and hashes them, so the digest
+ * moves when they do.
+ *
+ * Which fields name a path is data, as the template fields are in
+ * ./release-compile.ts and the unit fields in ./deploy-units.ts: a kind's
+ * fields in {@link DEPLOY_INPUT_FIELDS}, plus `template`, `manifest` and
+ * `values` on any step ({@link TEMPLATE_FIELDS}). Only a literal path counts:
+ * a value wired from another step (`@Build.uri`) or an `archive:` path is a
+ * build output, and binding it would make an approval unusable by a build
+ * that is not reproducible. The build steps' own sources are bound instead.
+ *
+ * - A file is hashed by its bytes.
+ * - A directory is hashed over the files under it that git does not ignore
+ *   (`git ls-files --cached --others --exclude-standard`), each by its path
+ *   and bytes, so `node_modules` and a build's `dist` inside a Docker context
+ *   are left out. Outside a git repository every file is hashed except under
+ *   `.git` and `node_modules`.
+ * - A directory git ignores as a whole is a build output. It is not hashed;
+ *   the step is listed as unbound, with that reason.
+ * - A path that does not exist is left out. One that appears later moves the
+ *   digest.
+ *
+ * A step whose kind runs content chant can't name, such as `shell`, is listed
+ * as unbound ({@link UNBOUND_KINDS}), so the plan note can show a reviewer
+ * what the approval does not cover.
+ */
+
+import { spawnSync } from "node:child_process";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join, relative, resolve, sep } from "node:path";
+import { sha256Hex } from "../content-digest";
+import { computePlanDigest } from "../lifecycle/plan-digest";
+import type { DriverGate, DriverPhase, DriverStep } from "./driver";
+
+/** The fields that name every step's deployed file, whatever its kind (as ./release-compile.ts reads them). */
+export const TEMPLATE_FIELDS: readonly string[] = ["template", "manifest", "values"];
+
+/** Per kind, the fields beyond {@link TEMPLATE_FIELDS} that name a local file or directory the step deploys or builds from. */
+export const DEPLOY_INPUT_FIELDS: Readonly<Record<string, readonly string[]>> = {
+  "helm-upgrade": ["chart"],
+  "kustomize-apply": ["dir"],
+  "fly-release": ["plan"],
+  "fly-rollback": ["plan"],
+  "s3-sync": ["from"],
+  "r2-sync": ["from"],
+  "copy-to-host": ["from"],
+  "wrangler-deploy": ["config"],
+  "wrangler-versions-promote": ["config"],
+  "docker-build": ["context"],
+  "zip-package": ["source"],
+  "jvm-build": ["path"],
+};
+
+/** Kinds that deploy content chant can't name from their input: a command, an agent's work. */
+export const UNBOUND_KINDS: readonly string[] = ["shell", "run-agent"];
+
+/** One path a step names. */
+export interface DeployInputRef {
+  phase: string;
+  kind: string;
+  field: string;
+  /** Relative to the member's directory, as written. */
+  path: string;
+}
+
+/** A named path and the digest of what is there. */
+export interface DeployInputDigest {
+  path: string;
+  /** `sha256:<hex>` of a file's bytes, or a plan digest over a directory's files. */
+  digest: string;
+}
+
+/** A step the digest does not cover, and why. */
+export interface UnboundStep {
+  phase: string;
+  kind: string;
+  reason: string;
+}
+
+/** What a component's steps deploy from: the digests, and the steps they can't cover. */
+export interface ComponentDeployInputs {
+  inputs: DeployInputDigest[];
+  unbound: UnboundStep[];
+}
+
+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);
+}
+
+const isLiteralPath = (v: unknown): v is string =>
+  typeof v === "string" && v !== "" && !v.startsWith("@") && !v.startsWith("$") && !v.startsWith("archive:");
+
+/** Every capability step of a composition with its phase, nested phases included, gates left out. */
+export function stepsWithPhase(phases: readonly DriverPhase[]): Array<{ phase: string; step: DriverStep }> {
+  const out: Array<{ phase: string; step: DriverStep }> = [];
+  const walk = (phase: DriverPhase): void => {
+    for (const step of phase.steps) {
+      if (isPhase(step)) walk(step);
+      else if (!isGate(step)) out.push({ phase: phase.phase, step });
+    }
+  };
+  phases.forEach(walk);
+  return out;
+}
+
+/** The literal paths one step names, in field order. A Docker build's Dockerfile is named under its context. */
+export function stepInputRefs(phase: string, step: DriverStep): DeployInputRef[] {
+  const out: DeployInputRef[] = [];
+  for (const field of [...TEMPLATE_FIELDS, ...(DEPLOY_INPUT_FIELDS[step.kind] ?? [])]) {
+    const raw = step[field];
+    for (const value of Array.isArray(raw) ? raw : [raw]) {
+      if (isLiteralPath(value)) out.push({ phase, kind: step.kind, field, path: value });
+    }
+  }
+  if (step.kind === "docker-build" && isLiteralPath(step.context) && isLiteralPath(step.dockerfile)) {
+    out.push({ phase, kind: step.kind, field: "dockerfile", path: join(step.context, step.dockerfile) });
+  }
+  return out;
+}
+
+function git(root: string, args: string[]): { ok: boolean; out: string } {
+  const r = spawnSync("git", ["-C", root, ...args], { encoding: "utf-8", maxBuffer: 256 * 1024 * 1024 });
+  return { ok: r.status === 0, out: r.stdout ?? "" };
+}
+
+/** The files under `dir` (relative to `root`) a directory digest covers, relative to `root`, sorted. */
+export function directoryFiles(root: string, dir: string): string[] {
+  const listed = git(root, ["ls-files", "-z", "--cached", "--others", "--exclude-standard", "--", dir]);
+  if (listed.ok) {
+    return [...new Set(listed.out.split("\0").filter((p) => p !== ""))]
+      .filter((p) => {
+        const full = resolve(root, p);
+        return existsSync(full) && statSync(full).isFile();
+      })
+      .sort();
+  }
+  return walkFiles(root, dir);
+}
+
+/** Every file under `dir`, relative to `root`, sorted, leaving out `.git` and `node_modules`. What a cut records of a directory git ignores. */
+export function walkFiles(root: string, dir: string): string[] {
+  const out: string[] = [];
+  const walk = (abs: string): void => {
+    for (const entry of readdirSync(abs, { withFileTypes: true })) {
+      if (entry.name === ".git" || entry.name === "node_modules") continue;
+      const full = join(abs, entry.name);
+      if (entry.isDirectory()) walk(full);
+      else if (entry.isFile()) out.push(relative(root, full).split(sep).join("/"));
+    }
+  };
+  walk(resolve(root, dir));
+  return out.sort();
+}
+
+/** Whether git ignores `path` (relative to `root`). False outside a git repository. */
+export function ignoredByGit(root: string, path: string): boolean {
+  return git(root, ["check-ignore", "-q", "--", path]).ok;
+}
+
+/** `sha256:<hex>` of a file's bytes. */
+export function fileDigest(file: string): string {
+  return `sha256:${sha256Hex(readFileSync(file))}`;
+}
+
+/** The digest of the files under `dir`: a plan digest over each file's path (from `dir`) and bytes. */
+export function directoryDigest(root: string, dir: string): string {
+  const base = resolve(root, dir);
+  const files = directoryFiles(root, dir).map((p) => ({
+    path: relative(base, resolve(root, p)).split(sep).join("/"),
+    digest: fileDigest(resolve(root, p)),
+  }));
+  return computePlanDigest("directory", files);
+}
+
+/**
+ * What a component's steps deploy from, read under `root` (the member's
+ * directory). `include` picks the steps to read, all of them by default; the
+ * wave planner passes the steps without a `plan`, which their plan does not
+ * already cover.
+ */
+export function componentDeployInputs(
+  phases: readonly DriverPhase[],
+  root: string,
+  include: (step: DriverStep) => boolean = () => true,
+): ComponentDeployInputs {
+  const inputs = new Map<string, string>();
+  const unbound: UnboundStep[] = [];
+  for (const { phase, step } of stepsWithPhase(phases)) {
+    if (!include(step)) continue;
+    if (UNBOUND_KINDS.includes(step.kind)) {
+      unbound.push({ phase, kind: step.kind, reason: `a ${step.kind} step runs content chant can't name from its input` });
+      continue;
+    }
+    for (const ref of stepInputRefs(phase, step)) {
+      if (inputs.has(ref.path)) continue;
+      const full = resolve(root, ref.path);
+      if (!existsSync(full)) continue;
+      if (statSync(full).isDirectory()) {
+        if (ignoredByGit(root, ref.path)) {
+          unbound.push({ phase, kind: step.kind, reason: `its ${ref.field} "${ref.path}" is a directory git ignores, so a build output; bind its sources through the step that builds it` });
+          continue;
+        }
+        inputs.set(ref.path, directoryDigest(root, ref.path));
+      } else {
+        inputs.set(ref.path, fileDigest(full));
+      }
+    }
+  }
+  return {
+    inputs: [...inputs].map(([path, digest]) => ({ path, digest })).sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0)),
+    unbound,
+  };
+}

package/src/components/driver.test.ts

@@ -11,7 +11,7 @@
  */
 
 import { describe, expect, it } from "vitest";
-import { CapabilityRegistry, type DeployContext } from "./capability";
+import { CapabilityRegistry, isPlanMovedError, type DeployContext } from "./capability";
 import { stubCapability } from "./verbs/stub";
 import { describeGateMismatch, memoryGateLedgerPort } from "../op/gate";
 import { componentPlanDigest } from "./gate-plan";
@@ -22,6 +22,7 @@ import {
   UnknownDependencyError,
   accumulateComponentOutputs,
   collectComponentOutputs,
+  failedRunExitCode,
   resolveComponentGraph,
   resolveWiring,
   runComponentDeploy,
@@ -1173,3 +1174,37 @@ describe("unresolvedWiringSources (#4084)", () => {
     ).toEqual([]);
   });
 });
+
+describe("a step that refuses a moved plan (#3997)", () => {
+  it.each([
+    ["planMoved: true", { planMoved: true }, true],
+    ["exitCode 3", { exitCode: 3 }, true],
+    ["exitCode 7", { exitCode: 7 }, false],
+    ['exitCode "3"', { exitCode: "3" }, false],
+    ["planMoved: \"yes\"", { planMoved: "yes" }, false],
+    ["no mark", {}, false],
+  ])("isPlanMovedError reads an error with %s", (_label, mark, moved) => {
+    expect(isPlanMovedError(Object.assign(new Error("refused"), mark))).toBe(moved);
+  });
+
+  it("is not fooled by a non-object", () => {
+    expect(isPlanMovedError(null)).toBe(false);
+    expect(isPlanMovedError("planMoved")).toBe(false);
+  });
+
+  it("marks the failed step's record, and failedRunExitCode answers 3 for it and 1 for any other failure", async () => {
+    const run = async (mark: object) => {
+      const registry = new CapabilityRegistry();
+      registry.register(fakeCapability("apply", { run: () => { throw Object.assign(new Error("refused"), mark); } }).capability);
+      const component: DriverComponent = { name: "c", deploy: [{ phase: "Apply", steps: [{ kind: "apply" }] }] };
+      return runComponentDeploy(component, { env: "dev", component: "c" }, registry, {});
+    };
+    const moved = await run({ exitCode: 3 });
+    expect(moved.records[0]).toMatchObject({ status: "fail", planMoved: true });
+    expect(failedRunExitCode([moved])).toBe(3);
+    const other = await run({ exitCode: 7 });
+    expect(other.records[0]).not.toHaveProperty("planMoved");
+    expect(failedRunExitCode([other])).toBe(1);
+    expect(failedRunExitCode([other, moved])).toBe(3);
+  });
+});

package/src/components/driver.ts

@@ -52,8 +52,10 @@ import { evaluateGate, gitGateLedgerPort, type GateDigestMismatch, type GateLedg
 import { gateName } from "../op/gate-name";
 import { GateNotRecordableError } from "../lifecycle/no-record";
 import { componentPlanDigest } from "./gate-plan";
+import { componentDeployInputs } from "./deploy-inputs";
 import type { PendingGateRecord } from "../lifecycle/gate-ledger";
 import type { CapabilityRegistry, DeployContext } from "./capability";
+import { isPlanMovedError, PLAN_MOVED_EXIT_CODE } from "./capability";
 import { isPromotedArtifact } from "./auto-release";
 import type { ReleaseIdentity } from "../telemetry-attribution";
 import type { RunProgressEvent } from "./run-progress";
@@ -154,6 +156,8 @@ export interface DriverStepRecord {
   durationMs: number;
   output?: unknown;
   error?: string;
+  /** Set on a failed step whose capability refused a plan that moved since it was approved (`isPlanMovedError`, #3997). */
+  planMoved?: true;
   /** Set on a `gate` step that passed (#2119): who resolved it, when, and at what address. */
   approval?: {
     gate: string;
@@ -356,12 +360,51 @@ export function unresolvedWiringSources(
   input: Record<string, unknown>,
   componentOutputs: Record<string, Record<string, unknown>>,
 ): string[] {
-  const found = new Set<string>();
+  return [...new Set(unresolvedWiringReferences(input, componentOutputs).map((r) => r.source))].sort();
+}
+
+/** One cross-component reference a step input makes: whose output, and which. */
+export interface WiringReference {
+  /** The component or stack whose output it reads. */
+  source: string;
+  /** `<stack>.<name>` for `stackOutput()`, `<component>.publish.<field>` for an artifact. */
+  ref: string;
+  /**
+   * Whether it reads a published artifact's identity (#3999): an
+   * `@<component>.publish.*` reference, or a `stackOutput()` whose name is
+   * under `publish`. The driver namespaces every publish-family output there
+   * (`collectComponentOutputs`), whatever capability wrote it.
+   */
+  publish: boolean;
+}
+
+/**
+ * Every cross-component reference in `input` that has no value in
+ * `componentOutputs`, sorted by `ref` and each once (#3999). A pull
+ * request's plan names these when the output is known only after its
+ * upstream applies.
+ */
+export function unresolvedWiringReferences(
+  input: Record<string, unknown>,
+  componentOutputs: Record<string, Record<string, unknown>>,
+): WiringReference[] {
+  return wiringReferences(input).filter((r) => r.value(componentOutputs) === undefined).map(({ source, ref, publish }) => ({ source, ref, publish }));
+}
+
+/**
+ * Every cross-component reference in `input`, each once, sorted by `ref`,
+ * with the value it resolves to against a given outputs map.
+ */
+function wiringReferences(input: Record<string, unknown>): Array<WiringReference & { value: (outputs: Record<string, Record<string, unknown>>) => unknown }> {
+  const found = new Map<string, WiringReference & { value: (outputs: Record<string, Record<string, unknown>>) => unknown }>();
   const walk = (value: unknown): void => {
     if (typeof value === "string") {
       if (PRIOR_STEP_REF.test(value)) return;
       const ref = value.match(COMPONENT_ARTIFACT_REF);
-      if (ref && resolvePath(componentOutputs[ref[1]]?.publish, ref[2]) === undefined) found.add(ref[1]);
+      if (ref) {
+        const [, source, field] = ref;
+        found.set(`${source}.publish.${field}`, { source, ref: `${source}.publish.${field}`, publish: true, value: (o) => resolvePath(o[source]?.publish, field) });
+      }
       return;
     }
     if (Array.isArray(value)) {
@@ -371,14 +414,29 @@ export function unresolvedWiringSources(
     if (value && typeof value === "object") {
       if ("stackOutput" in value) {
         const { stack, name } = (value as { stackOutput: { stack: string; name: string } }).stackOutput;
-        if (resolvePath(componentOutputs[stack], name) === undefined) found.add(stack);
+        found.set(`${stack}.${name}`, { source: stack, ref: `${stack}.${name}`, publish: name === "publish" || name.startsWith("publish."), value: (o) => resolvePath(o[stack], name) });
         return;
       }
       Object.values(value as Record<string, unknown>).forEach(walk);
     }
   };
   walk(input);
-  return [...found].sort();
+  return [...found.values()].sort((a, b) => a.ref.localeCompare(b.ref));
+}
+
+/**
+ * The cross-component references in `input` that resolve to another value
+ * against `now` than against `read`, sorted (#3999). A pull request's apply
+ * holds back a member whose plan read `read` when its upstream applied and
+ * left `now`.
+ */
+export function movedWiringReferences(
+  input: Record<string, unknown>,
+  read: Record<string, Record<string, unknown>>,
+  now: Record<string, Record<string, unknown>>,
+): WiringReference[] {
+  const same = (a: unknown, b: unknown) => JSON.stringify(a ?? null) === JSON.stringify(b ?? null);
+  return wiringReferences(input).filter((r) => !same(r.value(read), r.value(now))).map(({ source, ref, publish }) => ({ source, ref, publish }));
 }
 
 // ── Step + phase execution ───────────────────────────────────────────────
@@ -501,6 +559,7 @@ async function runCapabilityStep(
         status: "fail",
         durationMs: Date.now() - start,
         error: errMessage(err),
+        ...(isPlanMovedError(err) ? { planMoved: true as const } : {}),
       },
       resolvedInput,
     };
@@ -795,6 +854,13 @@ async function rollbackExecuted(
 
 // ── Per-component deploy ─────────────────────────────────────────────────
 
+/** Whether a component's composition has a gate step anywhere, nested phases and `rollback` included. */
+function hasGateStep(component: DriverComponent): boolean {
+  const walk = (steps: DriverPhase["steps"]): boolean =>
+    steps.some((step) => isGateStep(step) || (Array.isArray((step as DriverPhase).steps) && walk((step as DriverPhase).steps)));
+  return [...component.deploy, ...(component.rollback ?? [])].some((p) => walk(p.steps));
+}
+
 /**
  * Run one component's `deploy` composition. On terminal failure: unwind every
  * executed step in reverse via its capability's `rollback` (saga
@@ -842,6 +908,9 @@ export async function runComponentDeploy(
         component,
         ...(ctx.vars ? { vars: ctx.vars } : {}),
         ...(release !== undefined ? { release } : {}),
+        // #4155: the files the steps deploy from, read where the steps read
+        // them. Only a gate reads the digest, so a run with none skips the hashing.
+        ...(hasGateStep(component) ? { inputs: componentDeployInputs(component.deploy, process.cwd()).inputs } : {}),
       }),
   };
   const records: DriverStepRecord[] = [];
@@ -995,6 +1064,20 @@ function findStackOutputs(
   return found;
 }
 
+/** Whether a step in `results` refused a plan that moved since it was approved (#3997). */
+export function planMovedIn(results: readonly DriverComponentResult[]): boolean {
+  return results.some((r) => r.records.some((s) => s.planMoved === true));
+}
+
+/**
+ * The exit code of a run that failed: {@link PLAN_MOVED_EXIT_CODE} when a
+ * step refused a plan that moved since it was approved, 1 otherwise. Every
+ * command that runs capability steps ends a failed run with it.
+ */
+export function failedRunExitCode(results: readonly DriverComponentResult[]): number {
+  return planMovedIn(results) ? PLAN_MOVED_EXIT_CODE : 1;
+}
+
 function errMessage(err: unknown): string {
   return err instanceof Error ? err.message : String(err);
 }

package/src/components/fan-out-record.ts

@@ -38,7 +38,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import { readWaveRecords, writeWaveRecordFile, type WaveRecord } from "../wave-engine";
 import type { ChangeSetDocument } from "../change-set";
-import type { PrMember } from "../pr-loop";
+import type { PrMember, PrWave } from "../pr-loop";
 
 /** What a pull request's apply approved, kept so a re-run can finish it (#3464). */
 export interface PrApplyRecord {
@@ -59,6 +59,11 @@ export interface PrApplyRecord {
    * against them again, so an unchanged member plans to the same digest.
    */
   planOutputs: Record<string, Record<string, unknown>>;
+  /**
+   * With `--wave-gate` (#4003): each wave reached so far and the approval it
+   * applied or waits under, so the next wave's job reports every wave.
+   */
+  waves?: PrWave[];
 }
 
 export interface FanOutAttempt {
@@ -100,6 +105,7 @@ function readPrApplyRecord(value: unknown): PrApplyRecord | undefined {
   if (isRecord(planOutputs)) {
     for (const [name, v] of Object.entries(planOutputs)) if (isRecord(v)) outputs[name] = v;
   }
+  const waves = Array.isArray(value.waves) ? value.waves.map(readPrWave).filter((w): w is PrWave => w !== undefined) : [];
   return {
     op,
     gate,
@@ -109,6 +115,28 @@ function readPrApplyRecord(value: unknown): PrApplyRecord | undefined {
     members: members as unknown as PrMember[],
     changeSet: changeSet as unknown as ChangeSetDocument,
     planOutputs: outputs,
+    ...(waves.length > 0 ? { waves } : {}),
+  };
+}
+
+const WAVE_STATUSES: ReadonlySet<string> = new Set(["applied", "failed", "plan-failed", "waiting"]);
+
+/** One `prApply.waves` entry, or `undefined` when it is malformed. */
+function readPrWave(value: unknown): PrWave | undefined {
+  if (!isRecord(value)) return undefined;
+  const { wave, components, status, approval, gate, digest } = value;
+  if (typeof wave !== "number" || !isStringArray(components) || typeof status !== "string" || !WAVE_STATUSES.has(status)) return undefined;
+  if ((approval !== "pull-request" && approval !== "wave") || typeof gate !== "string" || typeof digest !== "string") return undefined;
+  return {
+    wave,
+    components,
+    status: status as PrWave["status"],
+    approval,
+    gate,
+    digest,
+    ...(isStringArray(value.approvedBy) ? { approvedBy: value.approvedBy } : {}),
+    ...(typeof value.approved === "string" ? { approved: value.approved } : {}),
+    ...(isStringArray(value.moved) ? { moved: value.moved } : {}),
   };
 }
 

package/src/components/fan-out-run.test.ts

@@ -209,3 +209,38 @@ describe("one approval over the whole set", () => {
     expect(ran.sort()).toEqual(["app-one", "app-three", "app-two", "cluster-b"]);
   });
 });
+
+describe("holding a component back (#3999)", () => {
+  test("a held component and what is downstream of it do not run and settle waiting; independent branches run", async () => {
+    const plan = planFanOut({ components: ESTATE, changed: ["net"] });
+    const { registry, ran } = registryWith();
+    const events: Array<{ type: string; component?: string; status?: string }> = [];
+    const asked: Array<[string, string[]]> = [];
+    const result = await runFanOut(plan, ESTATE, registry, {
+      ...opts(),
+      onRunEvent: (e) => events.push(e as never),
+      hold: (name, outputs) => {
+        asked.push([name, Object.keys(outputs).sort()]);
+        return name === "cluster-a" ? "its plan read net.id before that output applied as another value" : undefined;
+      },
+    });
+    expect(result.status).toBe("ok");
+    expect(ran).not.toContain("cluster-a");
+    expect(ran).not.toContain("app-one");
+    expect(ran).toContain("app-three");
+    expect(result.held).toEqual([
+      { component: "cluster-a", reason: "its plan read net.id before that output applied as another value" },
+      { component: "app-one", reason: "its plan read net.id before that output applied as another value", heldBy: "cluster-a" },
+      { component: "app-two", reason: "its plan read net.id before that output applied as another value", heldBy: "cluster-a" },
+    ].sort((a, b) => plan.order.indexOf(a.component) - plan.order.indexOf(b.component)));
+    // Asked once per component as its wave starts, never for one already held.
+    expect(asked.map(([name]) => name).sort()).toEqual(["app-three", "cluster-a", "cluster-b", "net"]);
+    expect(events.filter((e) => e.type === "component-settle" && e.status === "waiting").map((e) => e.component).sort()).toEqual(["app-one", "app-two", "cluster-a"]);
+  });
+
+  test("with no hook, or a hook that holds nothing, the result has no held list", async () => {
+    const plan = planFanOut({ components: ESTATE, changed: ["net"] });
+    expect((await runFanOut(plan, ESTATE, registryWith().registry, opts())).held).toBeUndefined();
+    expect((await runFanOut(plan, ESTATE, registryWith().registry, { ...opts(), hold: () => undefined })).held).toBeUndefined();
+  });
+});

package/src/components/fan-out-run.ts

@@ -205,6 +205,25 @@ export interface FanOutRunOptions {
    * the returned result cannot do.
    */
   onComponentSettled?: (result: DriverComponentResult, outputs: Record<string, unknown> | undefined) => void;
+  /**
+   * Asked as each component's wave starts, with the outputs standing then
+   * (#3999). A reason holds the component back: it does not run, and nothing
+   * downstream of it runs either; each is listed in `held` and settles
+   * `waiting`. A pull request's apply holds a member whose plan read an
+   * upstream output that applied as another value, or that was known only
+   * after apply. Not with `waveGate`, which plans each wave after the one
+   * before it applied.
+   */
+  hold?: (component: string, componentOutputs: Record<string, Record<string, unknown>>) => string | undefined;
+}
+
+/** A component {@link FanOutRunOptions.hold} held back, or one downstream of it. */
+export interface FanOutHeld {
+  component: string;
+  /** Why the hook held it, or, downstream, why it held the component named in `heldBy`. */
+  reason: string;
+  /** Downstream of a held component: that component. */
+  heldBy?: string;
 }
 
 export interface FanOutRunResult {
@@ -223,6 +242,8 @@ export interface FanOutRunResult {
   gate?: PendingGateRecord;
   /** With `waveGate`: each wave this attempt planned, in order, the one it stopped at included. */
   waves?: WaveRecord[];
+  /** What {@link FanOutRunOptions.hold} held back, in plan order. Absent when nothing was. */
+  held?: FanOutHeld[];
 }
 
 /**
@@ -296,9 +317,21 @@ export async function runFanOut(
   const completed: string[] = [];
   const failed: string[] = [];
   const blockedBy = new Map<string, string>();
+  const held = new Map<string, FanOutHeld>();
   let gatedFact: PendingGateRecord | undefined;
 
   const inPlan = new Set(active.order);
+  const waveOf = waveNumbers(active.waves);
+  /** Hold `root` and everything downstream of it that has not settled otherwise. */
+  const markHeld = (root: string, reason: string): void => {
+    held.set(root, { component: root, reason });
+    emit?.({ type: "component-settle", wave: waveOf.get(root)!, component: root, status: "waiting" });
+    for (const [component] of downstreamWithin(components, inPlan, [root])) {
+      if (held.has(component) || blockedBy.has(component) || failed.includes(component)) continue;
+      held.set(component, { component, reason, heldBy: root });
+      emit?.({ type: "component-settle", wave: waveOf.get(component)!, component, status: "waiting" });
+    }
+  };
   /** Skip everything downstream of `root`, blaming `root` rather than the nearest edge. */
   const markBlocked = (root: string): void => {
     for (const [component, by] of downstreamWithin(components, inPlan, [root])) {
@@ -310,7 +343,12 @@ export async function runFanOut(
   for (const [waveIndex, wave] of active.waves.entries()) {
     const waveNum = waveIndex + 1;
     // A component whose upstream failed in an earlier wave is not dispatched.
-    const runnable = wave.filter((name) => inPlan.has(name) && !blockedBy.has(name));
+    const candidates = wave.filter((name) => inPlan.has(name) && !blockedBy.has(name) && !held.has(name));
+    for (const name of candidates) {
+      const reason = options.hold?.(name, componentOutputs);
+      if (reason !== undefined) markHeld(name, reason);
+    }
+    const runnable = candidates.filter((name) => !held.has(name));
     if (runnable.length === 0) continue;
 
     emit?.({ type: "wave-start", wave: waveNum, components: runnable });
@@ -384,6 +422,7 @@ export async function runFanOut(
     blocked,
     componentOutputs,
     ...(gatedFact ? { gate: gatedFact } : {}),
+    ...(held.size > 0 ? { held: active.order.filter((name) => held.has(name)).map((name) => held.get(name)!) } : {}),
   };
 }
 

package/src/components/gate-plan.ts

@@ -17,6 +17,11 @@
  *   its publish output against a recorded digest that is not in the
  *   composition, so it passes that digest here.
  * - `vars`, the environment config the caller resolved ahead of the run.
+ * - The content digests of the local files the steps deploy from (#4155,
+ *   ./deploy-inputs.ts): a chart, a manifest, a site's tree, a build step's
+ *   sources. A file changed after review moves the digest. The key is left
+ *   out when no step names an existing file, so a composition that deploys
+ *   none keeps the digest it had before #4155.
  *
  * ## What it leaves out
  *
@@ -28,6 +33,7 @@
  */
 
 import { computePlanDigest } from "../lifecycle/plan-digest";
+import type { DeployInputDigest } from "./deploy-inputs";
 import type { DriverComponent } from "./driver";
 
 /** What a component gate's plan digest is taken over. */
@@ -37,6 +43,8 @@ export interface ComponentGatePlan {
   vars?: Record<string, unknown>;
   /** The recorded digest a promote or rollback deploys, when the caller has one. */
   release?: string;
+  /** What the steps deploy from (`componentDeployInputs`), when the caller read it. */
+  inputs?: readonly DeployInputDigest[];
 }
 
 /** The plan digest a component gate records and approves. */
@@ -49,5 +57,6 @@ export function componentPlanDigest(plan: ComponentGatePlan): string {
     rollback: component.rollback ?? null,
     vars: plan.vars ?? null,
     release: plan.release ?? null,
+    ...(plan.inputs && plan.inputs.length > 0 ? { inputs: plan.inputs } : {}),
   });
 }