@intentius/chant 0.101.0 → 0.104.0

package/src/components/pr-run.test.ts

@@ -0,0 +1,205 @@
+/**
+ * Planning and applying a pull request's members (#3183), against a fake
+ * root capability and an in-memory gate ledger. The five-root run against
+ * real `tofu` roots is `lexicons/terraform/src/components/pr-loop.tofu.test.ts`.
+ *
+ * The capability stands in for `terraform-apply`: `plan` returns the root, a
+ * digest over what it would write (its `version` and every input) and a
+ * change-set part; `outputs` reads what it exposes now; `run` applies.
+ */
+
+import { describe, expect, test } from "vitest";
+import { CapabilityRegistry, type DeployContext } from "./capability";
+import { memoryGateLedgerPort } from "../op/gate";
+import { planFanOut } from "./fan-out";
+import { applyPrSet, approvalOf, approversWithoutReview, decidePrGate, planPrSet, readOnlyLedger } from "./pr-run";
+import { changeSetDigest } from "../change-set";
+import { computePlanDigest } from "../lifecycle/plan-digest";
+import type { DriverComponent } from "./driver";
+
+interface RootInput {
+  root: string;
+  vars?: Record<string, unknown>;
+}
+
+const root = (name: string, dependsOn: string[] = [], vars?: Record<string, unknown>): DriverComponent => ({
+  name,
+  dependsOn,
+  deploy: [{ phase: "Apply", steps: [{ kind: "fake-root", root: name, ...(vars ? { vars } : {}) }] }],
+});
+
+/** net -> a, b; a -> app; dns alone. */
+const ESTATE: DriverComponent[] = [
+  root("net"),
+  root("a", ["net"], { cidr: { stackOutput: { stack: "net", name: "cidr" } } }),
+  root("b", ["net"], { cidr: { stackOutput: { stack: "net", name: "cidr" } } }),
+  root("app", ["a"], { subnet: { stackOutput: { stack: "a", name: "id" } } }),
+  root("dns"),
+];
+
+function world() {
+  const w = {
+    registry: new CapabilityRegistry(),
+    /** What each root would write. */
+    versions: {} as Record<string, string>,
+    /** What each root's state exposes. */
+    state: { net: { cidr: "10.0.0.0/16" }, a: { id: "a-v1" } } as Record<string, Record<string, unknown>>,
+    planned: [] as Array<{ root: string; vars?: Record<string, unknown> }>,
+    outputsRead: [] as string[],
+    applied: [] as string[],
+    fromPlan: {} as Record<string, boolean>,
+    failing: new Set<string>(),
+    planFailing: new Set<string>(),
+  };
+  const digestOf = (input: RootInput) => computePlanDigest("fake-root", { root: input.root, version: w.versions[input.root] ?? "v1", vars: input.vars ?? null });
+  w.registry.register({
+    kind: "fake-root",
+    async plan(_ctx: DeployContext, input: RootInput) {
+      w.planned.push({ root: input.root, ...(input.vars ? { vars: input.vars } : {}) });
+      if (w.planFailing.has(input.root)) throw new Error(`${input.root}: no value for a required variable`);
+      const planDigest = digestOf(input);
+      const changes = (w.versions[input.root] ?? "v1") !== "v1";
+      return {
+        member: input.root,
+        planDigest,
+        artifact: { planDigest },
+        changeSet: {
+          member: { member: input.root, lexicon: "terraform", planner: "tofu", status: "planned", planDigest, holes: [] },
+          entries: changes
+            ? [{ member: input.root, lexicon: "terraform", planner: "tofu", address: "terraform_data.x", type: "terraform_data", action: "update", attributes: [] }]
+            : [],
+        },
+      };
+    },
+    async outputs(_ctx: DeployContext, input: RootInput) {
+      w.outputsRead.push(input.root);
+      return { ...(w.state[input.root] ?? {}) };
+    },
+    async run(ctx: DeployContext, input: RootInput) {
+      w.fromPlan[input.root] = ctx.plans?.[input.root] !== undefined;
+      if (w.failing.has(input.root)) throw new Error(`${input.root} failed`);
+      w.applied.push(input.root);
+      if (input.root === "a") w.state.a = { id: `a-${w.versions.a ?? "v1"}` };
+      return { outputs: { ...(w.state[input.root] ?? {}) } };
+    },
+  } as never);
+  return w;
+}
+
+const NOW = "2026-10-03T00:00:00Z";
+const LATER = "2026-10-03T01:00:00Z";
+
+const approval = (planDigest: string, resolvedBy = "github:alice") => ({
+  version: 1 as const,
+  kind: "resolution" as const,
+  op: "pr-12",
+  gate: "pr-apply",
+  resolvedBy,
+  timestamp: LATER,
+  planDigest,
+});
+
+describe("planPrSet", () => {
+  test("plans the changed root and its dependents, each against the outputs its dependency has now", async () => {
+    const w = world();
+    w.versions.a = "v2";
+    const plan = planFanOut({ components: ESTATE, changed: ["a"] });
+    const set = await planPrSet({ components: ESTATE, plan, registry: w.registry, env: "prod" });
+
+    expect(plan.order).toEqual(["a", "app"]);
+    expect(w.planned).toEqual([
+      { root: "a", vars: { cidr: "10.0.0.0/16" } },
+      { root: "app", vars: { subnet: "a-v1" } },
+    ]);
+    // net is read for a, and a for app, before anything applies.
+    expect(w.outputsRead).toEqual(["net", "a"]);
+    expect(set.members.map((m) => [m.member, m.status, m.counts.update])).toEqual([
+      ["a", "planned", 1],
+      ["app", "planned", 0],
+    ]);
+    expect(set.doc.digest).toBe(changeSetDigest(set.members.map((m) => ({ member: m.member, planDigest: m.planDigest }))));
+    expect(set.failed).toBe(false);
+  });
+
+  test("planning the same members against the same state gives the same digest; a changed root moves it", async () => {
+    const plan = planFanOut({ components: ESTATE, changed: ["a"] });
+    const w = world();
+    w.versions.a = "v2";
+    const first = await planPrSet({ components: ESTATE, plan, registry: w.registry, env: "prod" });
+    const again = await planPrSet({ components: ESTATE, plan, registry: w.registry, env: "prod" });
+    w.versions.a = "v3";
+    const moved = await planPrSet({ components: ESTATE, plan, registry: w.registry, env: "prod" });
+    expect(again.doc.digest).toBe(first.doc.digest);
+    expect(moved.doc.digest).not.toBe(first.doc.digest);
+  });
+
+  test("a component that fails to plan is a failed member with no digest", async () => {
+    const w = world();
+    w.planFailing.add("app");
+    const set = await planPrSet({ components: ESTATE, plan: planFanOut({ components: ESTATE, changed: ["a"] }), registry: w.registry, env: "prod" });
+    expect(set.failed).toBe(true);
+    expect(set.members.find((m) => m.member === "app")).toMatchObject({ status: "plan-failed", planDigest: null, error: "app: no value for a required variable" });
+  });
+});
+
+describe("the gate", () => {
+  test("pending with no approval, approved for the digest, changed for another one", async () => {
+    const w = world();
+    const set = await planPrSet({ components: ESTATE, plan: planFanOut({ components: ESTATE, changed: ["a"] }), registry: w.registry, env: "prod" });
+    const input = { op: "pr-12", gate: "pr-apply", digest: set.doc.digest, now: NOW };
+
+    expect(approvalOf(await decidePrGate(readOnlyLedger(memoryGateLedgerPort()), input))).toEqual({ status: "pending" });
+    expect(approvalOf(await decidePrGate(memoryGateLedgerPort({ resolutions: [approval(set.doc.digest)] }), input))).toEqual({
+      status: "approved",
+      approvedBy: ["github:alice"],
+    });
+    const other = `jcs1-sha256:${"9".repeat(64)}`;
+    expect(approvalOf(await decidePrGate(memoryGateLedgerPort({ resolutions: [approval(other)] }), input))).toEqual({ status: "changed", approved: other });
+  });
+
+  test("the plan stage's ledger records nothing", async () => {
+    const ledger = memoryGateLedgerPort();
+    await decidePrGate(readOnlyLedger(ledger), { op: "pr-12", gate: "pr-apply", digest: `jcs1-sha256:${"1".repeat(64)}`, now: NOW });
+    expect(ledger.appended).toEqual([]);
+  });
+
+  test("an approver needs a standing approving review, named the forge's way", () => {
+    expect(approversWithoutReview(["github:alice", "GitHub:Bob"], ["github:alice", "github:bob"])).toEqual([]);
+    expect(approversWithoutReview(["github:mallory"], ["github:alice"])).toEqual(["github:mallory"]);
+  });
+});
+
+describe("applyPrSet", () => {
+  test("applies each member's approved plan in order and marks a dependent whose inputs moved", async () => {
+    const w = world();
+    w.versions.a = "v2";
+    const plan = planFanOut({ components: ESTATE, changed: ["a"] });
+    const set = await planPrSet({ components: ESTATE, plan, registry: w.registry, env: "prod" });
+    const { members, status } = await applyPrSet({ components: ESTATE, plan, registry: w.registry, env: "prod", set });
+
+    expect(status).toBe("applied");
+    expect(w.applied).toEqual(["a", "app"]);
+    expect(w.fromPlan).toEqual({ a: true, app: true });
+    expect(members.map((m) => [m.member, m.status, m.inputsMoved])).toEqual([
+      ["a", "applied", undefined],
+      ["app", "applied", ["a"]],
+    ]);
+  });
+
+  test("a failed member blocks its dependents and nothing else", async () => {
+    const w = world();
+    w.failing.add("a");
+    const plan = planFanOut({ components: ESTATE, changed: ["net", "dns"] });
+    const set = await planPrSet({ components: ESTATE, plan, registry: w.registry, env: "prod" });
+    const { members, status } = await applyPrSet({ components: ESTATE, plan, registry: w.registry, env: "prod", set });
+    expect(status).toBe("failed");
+    expect(Object.fromEntries(members.map((m) => [m.member, m.status]))).toEqual({
+      a: "failed",
+      app: "blocked",
+      b: "applied",
+      dns: "applied",
+      net: "applied",
+    });
+    expect(members.find((m) => m.member === "a")?.error).toBe("a failed");
+  });
+});

package/src/components/pr-run.ts

@@ -0,0 +1,280 @@
+/**
+ * Plan and apply a pull request's members (#3183).
+ *
+ * `../pr-loop.ts` says what the gate binds and what the report holds; this
+ * produces them. Both stages call {@link planPrSet}: the plan stage to show
+ * the plan and its digest, the apply stage to plan the same members again
+ * before anything applies and decide the gate against what it gets. Planning
+ * everything before applying anything is what makes the two digests
+ * comparable: each member is planned against the same state both times.
+ *
+ * ## Dependents read the outputs standing now
+ *
+ * A member that reads another one's output through `stackOutput()` is
+ * planned with the value that output has now, read through the capability's
+ * `outputs` (`readComponentOutputs`). When the change moves that output, the
+ * dependent's approved plan still carries the old value; the apply applies
+ * it as approved and marks the member `inputsMoved`, and the next run plans
+ * it against the new value. A change that must carry a moved output through
+ * its dependents in one rollout is what gated waves are for (#3049): each
+ * wave is planned after the one before it applied.
+ */
+
+import { composeChangeSet, type ChangeSetDocument, type ChangeSetPart } from "../change-set";
+import { evaluateGate, type GateCheck, type GateLedgerPort } from "../op/gate";
+import {
+  memberCounts,
+  PR_REPORT_CONTRACT,
+  PR_REPORT_SCHEMA_ID,
+  type PrApproval,
+  type PrMember,
+  type PrRefusal,
+  type PrReport,
+  type PrStatus,
+} from "../pr-loop";
+import { deployContext, type DriverComponent } from "./driver";
+import { deployUnits } from "./deploy-units";
+import { runFanOut, type FanOutRunResult } from "./fan-out-run";
+import type { ComponentChangeSignal, FanOutPlan } from "./fan-out";
+import type { CapabilityRegistry } from "./capability";
+import type { RunProgressEvent } from "./run-progress";
+import { planWaveComponent, readComponentOutputs } from "./wave-plan";
+
+export interface PrPlanSetOptions {
+  /** Every component in the project. */
+  components: DriverComponent[];
+  /** The fan-out the change derives (`planFanOut`). Its `order` is what is planned. */
+  plan: FanOutPlan;
+  registry: CapabilityRegistry;
+  env: string;
+  vars?: Record<string, unknown>;
+  /** Outputs supplied by the caller (`--seed-outputs`). They win over outputs read here. */
+  seededOutputs?: Record<string, Record<string, unknown>>;
+}
+
+/** Every member of a pull request, planned. */
+export interface PrPlanSet {
+  /** The change-set document over every member. Its digest is what the gate binds. */
+  doc: ChangeSetDocument;
+  members: PrMember[];
+  /** Per component, per member: what its steps hand `run`, so it applies this plan. */
+  plans: Record<string, Record<string, unknown>>;
+  /** The outputs the plans read: the seeds, and each dependency's outputs as they stood. */
+  outputs: Record<string, Record<string, unknown>>;
+  /** Whether any component failed to plan. */
+  failed: boolean;
+}
+
+/** A failed component's members: the units its steps target, else the component itself. */
+function failedParts(component: DriverComponent, error: string): ChangeSetPart[] {
+  const units = deployUnits(component.deploy).map((u) => u.unit);
+  return (units.length > 0 ? units : [component.name]).map((member) => ({
+    member: { member, lexicon: "chant", planner: "chant", status: "failed", error, planDigest: null, holes: [] },
+    entries: [],
+  }));
+}
+
+/**
+ * Plan every component in `plan.order`, a wave at a time, each against the
+ * outputs its dependencies have now. Never throws for a component that fails
+ * to plan: it becomes a failed member, and `failed` is set.
+ */
+export async function planPrSet(options: PrPlanSetOptions): Promise<PrPlanSet> {
+  const byName = new Map(options.components.map((c) => [c.name, c]));
+  const outputs: Record<string, Record<string, unknown>> = { ...(options.seededOutputs ?? {}) };
+  const read = new Set(Object.keys(outputs));
+  const parts: ChangeSetPart[] = [];
+  const componentOf = new Map<string, string>();
+  const plans: Record<string, Record<string, unknown>> = {};
+  let failed = false;
+
+  for (const wave of options.plan.waves) {
+    // The dependencies' outputs first, each read once. A dependency that
+    // cannot say leaves its references unresolved, which its dependent's
+    // plan reports if it needs them.
+    for (const name of wave) {
+      for (const dep of byName.get(name)?.dependsOn ?? []) {
+        if (read.has(dep) || !byName.has(dep)) continue;
+        read.add(dep);
+        const found = await readComponentOutputs(byName.get(dep)!, options.registry, deployContext(options, dep), outputs);
+        if (found) outputs[dep] = found;
+      }
+    }
+    const planned = await Promise.all(
+      wave.map((name) => planWaveComponent(byName.get(name)!, options.registry, deployContext(options, name), outputs)),
+    );
+    for (const p of planned) {
+      const component = byName.get(p.component)!;
+      if ("error" in p) {
+        failed = true;
+        for (const part of failedParts(component, p.error)) {
+          parts.push(part);
+          componentOf.set(part.member.member, p.component);
+        }
+        continue;
+      }
+      plans[p.component] = p.plans;
+      for (const part of p.parts) {
+        parts.push(part);
+        componentOf.set(part.member.member, p.component);
+      }
+    }
+  }
+
+  const doc = composeChangeSet(parts);
+  const members: PrMember[] = doc.members.map((m) => ({
+    member: m.member,
+    component: componentOf.get(m.member) ?? m.member,
+    planDigest: m.planDigest,
+    status: m.status === "failed" ? "plan-failed" : "planned",
+    counts: memberCounts(doc, m.member),
+    ...(m.error ? { error: m.error } : {}),
+  }));
+  return { doc, members, plans, outputs, failed };
+}
+
+/**
+ * A ledger that reads the real one and records nothing. The plan stage
+ * decides the gate only to say where the approval stands; it runs the pull
+ * request's own code and holds no write access to `chant/lifecycle`.
+ */
+export function readOnlyLedger(port: GateLedgerPort): GateLedgerPort {
+  return {
+    read: (op) => port.read(op),
+    ...(port.approvalRule ? { approvalRule: (gate: string) => port.approvalRule!(gate) } : {}),
+    async appendPending(input) {
+      return { record: { version: 1, kind: "pending", ...input }, pushed: false, pushWarning: "not recorded: the plan stage writes nothing" };
+    },
+  };
+}
+
+/** Where the approval stands, as the report says it. */
+export function approvalOf(check: GateCheck): PrApproval {
+  if (check.satisfied) {
+    const by = check.approvals?.length ? check.approvals.map((r) => r.resolvedBy) : [check.resolution.resolvedBy];
+    return { status: "approved", approvedBy: [...new Set(by)] };
+  }
+  if (check.mismatch) return { status: "changed", ...(check.mismatch.approved ? { approved: check.mismatch.approved } : {}) };
+  return { status: "pending" };
+}
+
+/** Decide the pull request's gate against `digest`. */
+export async function decidePrGate(
+  port: GateLedgerPort,
+  input: { op: string; gate: string; digest: string; description?: string; now?: string },
+): Promise<GateCheck> {
+  return evaluateGate(port, {
+    op: input.op,
+    gate: input.gate,
+    planDigest: input.digest,
+    ...(input.description ? { description: input.description } : {}),
+    ...(input.now ? { now: input.now } : {}),
+  });
+}
+
+/**
+ * Who approved the gate but has no standing approving review on the pull
+ * request. Each approval's `resolvedBy` is compared with the forge's own
+ * naming of each approver (#3163's form).
+ */
+export function approversWithoutReview(approvedBy: readonly string[], reviewers: readonly string[]): string[] {
+  const norm = (s: string) => s.trim().toLowerCase();
+  const allowed = new Set(reviewers.map(norm));
+  return approvedBy.filter((by) => !allowed.has(norm(by)));
+}
+
+export interface PrApplyOptions {
+  components: DriverComponent[];
+  plan: FanOutPlan;
+  registry: CapabilityRegistry;
+  env: string;
+  vars?: Record<string, unknown>;
+  /** The set {@link planPrSet} planned and the gate approved. */
+  set: PrPlanSet;
+  onProgress?: (event: RunProgressEvent) => void;
+}
+
+const sameJson = (a: unknown, b: unknown): boolean => JSON.stringify(a ?? null) === JSON.stringify(b ?? null);
+
+/**
+ * Apply the approved plans in dependency order. A failed component blocks
+ * its dependents and nothing else (`runFanOut`).
+ */
+export async function applyPrSet(options: PrApplyOptions): Promise<{ members: PrMember[]; status: "applied" | "failed"; run: FanOutRunResult }> {
+  const before = options.set.outputs;
+  const run = await runFanOut(options.plan, options.components, options.registry, {
+    env: options.env,
+    ...(options.vars ? { vars: options.vars } : {}),
+    plans: options.set.plans,
+    componentOutputs: { ...before },
+    ...(options.onProgress ? { onProgress: options.onProgress } : {}),
+  });
+  const completed = new Set(run.completed);
+  const blocked = new Set(run.blocked.map((b) => b.component));
+  const errorOf = (component: string): string | undefined => {
+    const result = run.results.find((r) => r.component === component);
+    if (result?.status === "gated") return `stopped at its own gate ${result.gate?.gate ?? ""}`.trim();
+    return result?.records.find((r) => r.status === "fail")?.error;
+  };
+  const byName = new Map(options.components.map((c) => [c.name, c]));
+  const members = options.set.members.map((m): PrMember => {
+    if (completed.has(m.component)) {
+      const moved = (byName.get(m.component)?.dependsOn ?? [])
+        .filter((dep) => completed.has(dep) && !sameJson(before[dep], run.componentOutputs[dep]))
+        .sort();
+      return { ...m, status: "applied", ...(moved.length > 0 ? { inputsMoved: moved } : {}) };
+    }
+    if (blocked.has(m.component)) return { ...m, status: "blocked" };
+    const error = errorOf(m.component);
+    return { ...m, status: "failed", ...(error ? { error } : {}) };
+  });
+  return { members, status: run.status === "ok" ? "applied" : "failed", run };
+}
+
+export interface PrReportInput {
+  stage: "plan" | "apply";
+  pr: number | null;
+  env: string;
+  base: string;
+  head: string;
+  op: string;
+  gate: string;
+  plan: FanOutPlan;
+  signal: ComponentChangeSignal;
+  set: PrPlanSet;
+  approval: PrApproval;
+  status: PrStatus;
+  members?: PrMember[];
+  refusal?: PrRefusal;
+  message?: string;
+}
+
+/** The report a stage writes. */
+export function prReport(input: PrReportInput): PrReport {
+  const changed = new Set(input.signal.changed);
+  return {
+    $schema: PR_REPORT_SCHEMA_ID,
+    contract: PR_REPORT_CONTRACT,
+    stage: input.stage,
+    pr: input.pr,
+    env: input.env,
+    base: input.base,
+    head: input.head,
+    op: input.op,
+    gate: input.gate,
+    digest: input.set.doc.digest,
+    status: input.status,
+    ...(input.refusal ? { refusal: input.refusal } : {}),
+    ...(input.message ? { message: input.message } : {}),
+    approval: input.approval,
+    selection: {
+      changed: input.plan.order.filter((c) => changed.has(c)),
+      dependents: input.plan.order.filter((c) => !changed.has(c)),
+      unclaimed: input.signal.unclaimed,
+      indeterminate: input.plan.indeterminate,
+      waves: input.plan.waves,
+    },
+    members: input.members ?? input.set.members,
+    changeSet: input.set.doc,
+  };
+}

package/src/components/promote.ts

@@ -560,6 +560,11 @@ export async function runPromotion(options: RunPromotionOptions): Promise<Driver
       // #2574: a gate approval for this promote or rollback is bound to the
       // release it deploys, as well as the environment and composition.
       releases: expected,
+      // #3061: the workload's service.version and vcs.ref.head.revision are the earlier release's own.
+      releaseIdentity: (component) => {
+        const item = plan.items.find((i) => i.component === component);
+        return item ? { version: item.digest, revision: item.source.gitSha } : undefined;
+      },
       ...(options.onProgress ? { onProgress: options.onProgress } : {}),
       ...(options.gates ? { gates: options.gates } : {}),
       ...(options.now ? { now: options.now } : {}),

package/src/components/verbs/shell.test.ts

@@ -33,4 +33,15 @@ describe("shell (#557)", () => {
   it("declares no rollback — an escape-hatch shell owns its own compensation", () => {
     expect(createShellCapability(createMockProcessRunner().runner).rollback).toBeUndefined();
   });
+
+  it("exports a release's attributes for a docker compose up, and a value the step sets wins (#3061)", async () => {
+    const mock = createMockProcessRunner();
+    const release = { version: "sha256:abc", revision: "0123abc" };
+    await createShellCapability(mock.runner).run({ ...ctx, release }, { cmd: "docker compose up -d", reason: "compose" });
+    expect(mock.calls.at(-1)!.command).toBe(
+      "env CHANT_RELEASE_ATTRIBUTES=',service.version=sha256%3Aabc,vcs.ref.head.revision=0123abc' docker compose up -d",
+    );
+    await createShellCapability(mock.runner).run({ ...ctx, release }, { cmd: "up", env: { CHANT_RELEASE_ATTRIBUTES: "" }, reason: "x" });
+    expect(mock.calls.at(-1)!.command).toBe("env CHANT_RELEASE_ATTRIBUTES='' up");
+  });
 });

package/src/components/verbs/shell.ts

@@ -8,6 +8,7 @@
 
 import type { Capability } from "../capability";
 import { defaultProcessRunner, q, type ProcessRunner } from "./process-runner";
+import { releaseEnvironment } from "../../telemetry-attribution";
 
 export interface ShellInput {
   /** Command to run. */
@@ -36,10 +37,13 @@ export interface ShellOutput {
 export function createShellCapability(processRunner: ProcessRunner = defaultProcessRunner()): Capability<ShellInput, ShellOutput> {
   return {
     kind: "shell",
-    async run(_ctx, input) {
+    async run(ctx, input) {
+      // A release run exports its attributes (#3061, ws-081), so a `docker compose up` here fills the
+      // Compose file's `${CHANT_RELEASE_ATTRIBUTES:-}`. A value the step sets itself wins.
+      const env = { ...releaseEnvironment(ctx.release), ...(input.env ?? {}) };
       const envPrefix =
-        input.env && Object.keys(input.env).length > 0
-          ? `env ${Object.entries(input.env).map(([k, v]) => `${k}=${q(v)}`).join(" ")} `
+        Object.keys(env).length > 0
+          ? `env ${Object.entries(env).map(([k, v]) => `${k}=${q(v)}`).join(" ")} `
           : "";
       const { stdout } = await processRunner.run(`${envPrefix}${input.cmd}`, { cwd: input.cwd });
       return { stdout, exitCode: 0 };

package/src/components/wave-plan.ts

@@ -0,0 +1,124 @@
+/**
+ * Plan one wave of a gated-wave fan-out (#3049).
+ *
+ * Each component in the wave is asked what it would change: every deploy
+ * step whose capability has a `plan` (`Capability.plan`, ./capability.ts) is
+ * planned, with its wiring resolved against the outputs the earlier waves
+ * left behind. That is the point of planning at the wave rather than up
+ * front: a root that reads an upstream output plans against the value the
+ * upstream wave actually wrote.
+ *
+ * A component with no plannable step is still a member of the wave. Its plan
+ * digest is the composition digest a gate inside it would bind
+ * (`componentPlanDigest`, ./gate-plan.ts, #2574), so a wave mixing roots and
+ * other components still has one digest that moves when any of them does.
+ *
+ * Known limit: a step input that reads an earlier step of the same
+ * component (`@Phase.field`) has no value before the component runs, so it
+ * plans as `undefined`. Cross-component wiring (`stackOutput()`,
+ * `@<component>.publish.*`) resolves.
+ */
+
+import { resolveStepInput, type DriverComponent, type DriverPhase, type DriverStep } from "./driver";
+import { componentPlanDigest } from "./gate-plan";
+import type { CapabilityRegistry, DeployContext } from "./capability";
+import type { WaveMember } from "../gated-waves";
+import type { ChangeSetPart } from "../change-set";
+
+/**
+ * What planning one component produced: its members, what its steps hand to
+ * `run`, and each member's change-set part (#3183), or why it could not plan.
+ * A member whose capability returns no part gets one with no entries, so the
+ * parts always cover the members.
+ */
+export type WaveComponentPlan =
+  | { component: string; members: WaveMember[]; plans: Record<string, unknown>; parts: ChangeSetPart[] }
+  | { component: string; error: string };
+
+/** A part with no entries, for a member whose planner describes no changes. */
+function emptyPart(member: WaveMember): ChangeSetPart {
+  return {
+    member: { member: member.member, lexicon: "chant", planner: "chant", status: "planned", planDigest: member.planDigest, holes: [] },
+    entries: [],
+  };
+}
+
+/** Every capability step in a composition, nested phases included, gates left out. */
+function capabilitySteps(phases: readonly DriverPhase[]): DriverStep[] {
+  const out: DriverStep[] = [];
+  const walk = (steps: DriverPhase["steps"]): void => {
+    for (const step of steps) {
+      if (typeof (step as DriverPhase).phase === "string" && Array.isArray((step as DriverPhase).steps)) {
+        walk((step as DriverPhase).steps);
+        continue;
+      }
+      if ((step as { kind?: unknown }).kind === "gate") continue;
+      out.push(step as DriverStep);
+    }
+  };
+  for (const phase of phases) walk(phase.steps);
+  return out;
+}
+
+/** Plan one component against the outputs earlier waves produced. Never throws: a failure comes back as `error`. */
+export async function planWaveComponent(
+  component: DriverComponent,
+  registry: CapabilityRegistry,
+  ctx: DeployContext,
+  componentOutputs: Record<string, Record<string, unknown>>,
+): Promise<WaveComponentPlan> {
+  try {
+    const members: WaveMember[] = [];
+    const plans: Record<string, unknown> = {};
+    const parts: ChangeSetPart[] = [];
+    for (const step of capabilitySteps(component.deploy)) {
+      const capability = registry.resolve(step.kind);
+      if (!capability.plan) continue;
+      const { kind: _kind, ...rest } = step;
+      const input = resolveStepInput(rest, {}, componentOutputs);
+      const planned = await capability.plan(ctx, input as never);
+      const member = { member: planned.member, planDigest: planned.planDigest };
+      members.push(member);
+      parts.push(planned.changeSet ?? emptyPart(member));
+      if (planned.artifact !== undefined) plans[planned.member] = planned.artifact;
+    }
+    if (members.length === 0) {
+      const member = {
+        member: component.name,
+        planDigest: componentPlanDigest({
+          environment: ctx.env,
+          component,
+          ...(ctx.vars ? { vars: ctx.vars } : {}),
+        }),
+      };
+      members.push(member);
+      parts.push(emptyPart(member));
+    }
+    return { component: component.name, members, plans, parts };
+  } catch (err) {
+    return { component: component.name, error: err instanceof Error ? err.message : String(err) };
+  }
+}
+
+/**
+ * The outputs `component` exposes now, read from each step whose capability
+ * has `outputs` (#3183), merged the way the driver merges a run's outputs.
+ * `undefined` when no step can say. A pull request's plan reads these for
+ * the components a planned one depends on, before anything has applied.
+ */
+export async function readComponentOutputs(
+  component: DriverComponent,
+  registry: CapabilityRegistry,
+  ctx: DeployContext,
+  componentOutputs: Record<string, Record<string, unknown>>,
+): Promise<Record<string, unknown> | undefined> {
+  let found: Record<string, unknown> | undefined;
+  for (const step of capabilitySteps(component.deploy)) {
+    const capability = registry.resolve(step.kind);
+    if (!capability.outputs) continue;
+    const { kind: _kind, ...rest } = step;
+    const input = resolveStepInput(rest, {}, componentOutputs);
+    found = { ...found, ...(await capability.outputs(ctx, input as never)) };
+  }
+  return found;
+}