@intentius/chant 0.124.51 → 0.124.54

package/src/components/declared-reads.test.ts

@@ -0,0 +1,103 @@
+/**
+ * Reads a capability finds in its steps' files (#4466): each becomes a
+ * `stackOutput()` reference in the reader's step and a `dependsOn` on the
+ * upstream, so it orders the fan-out and counts as a read.
+ */
+
+import { describe, expect, test } from "vitest";
+import { CapabilityRegistry, type DeclaredRead, type DeclaredReadMember } from "./capability";
+import { applyDeclaredReads, declaredReadsOf, withDeclaredReads } from "./declared-reads";
+import { planFanOut } from "./fan-out";
+import { unresolvedWiringReferences } from "./driver";
+import { capabilitySteps } from "./wave-plan";
+import type { DriverComponent } from "./driver";
+
+const stack = (name: string, extra: Record<string, unknown> = {}, dependsOn: string[] = []): DriverComponent => ({
+  name,
+  dependsOn,
+  deploy: [{ phase: "Apply", steps: [{ kind: "fake-stack", stack: name, ...extra }] }],
+});
+
+function registry(reads: (members: readonly DeclaredReadMember[]) => DeclaredRead[]) {
+  const asked: DeclaredReadMember[][] = [];
+  const r = new CapabilityRegistry();
+  const unused = async (): Promise<never> => {
+    throw new Error("not called here");
+  };
+  r.register({
+    kind: "fake-stack",
+    run: unused,
+    declaredReads(_ctx: unknown, members: readonly DeclaredReadMember[]) {
+      asked.push([...members]);
+      return reads(members);
+    },
+  } as never);
+  r.register({ kind: "fake-plain", run: unused } as never);
+  return { registry: r, asked };
+}
+
+describe("declared reads (#4466)", () => {
+  test("a read becomes a stackOutput() reference at its place and a dependsOn, so the reader orders after the upstream", async () => {
+    const components = [stack("app"), stack("network")];
+    const { registry: r, asked } = registry(() => [{ reader: "app", upstream: "network", output: "VpcId", at: "/imports/network-VpcId" }]);
+    const out = await withDeclaredReads(components, r, "/project");
+    expect(asked[0]!.map((m) => m.component)).toEqual(["app", "network"]);
+    const app = out.find((c) => c.name === "app")!;
+    expect(app.dependsOn).toEqual(["network"]);
+    expect(capabilitySteps(app.deploy)[0]).toEqual({
+      kind: "fake-stack",
+      stack: "app",
+      imports: { "network-VpcId": { stackOutput: { stack: "network", name: "VpcId" } } },
+    });
+    // The read is now one core sees: no value for network's VpcId yet.
+    const { kind: _kind, ...rest } = capabilitySteps(app.deploy)[0]!;
+    expect(unresolvedWiringReferences(rest, {}).map((x) => x.ref)).toEqual(["network.VpcId"]);
+    // And it orders the fan-out.
+    const plan = planFanOut({ components: out, changed: ["app", "network"] });
+    expect(plan.waves).toEqual([["network"], ["app"]]);
+    // The upstream is untouched.
+    expect(out.find((c) => c.name === "network")).toBe(components[1]);
+  });
+
+  test("a place the declaration already fills is left as it is, and adds no dependsOn", () => {
+    const declared = stack("app", { imports: { "network-VpcId": "vpc-pinned" } });
+    const [out] = applyDeclaredReads([declared], [{ reader: "app", upstream: "network", output: "VpcId", at: "/imports/network-VpcId", index: 0, kind: "fake-stack" }]);
+    expect(out!.dependsOn).toEqual([]);
+    expect(capabilitySteps(out!.deploy)[0]).toMatchObject({ imports: { "network-VpcId": "vpc-pinned" } });
+  });
+
+  test("a dependsOn already declared is not repeated", () => {
+    const declared = stack("app", {}, ["network"]);
+    const [out] = applyDeclaredReads([declared], [{ reader: "app", upstream: "network", output: "VpcId", at: "/imports/a", index: 0, kind: "fake-stack" }]);
+    expect(out!.dependsOn).toEqual(["network"]);
+  });
+
+  test("the read goes into the step of the reported kind and index, and an escaped pointer unescapes", () => {
+    const declared: DriverComponent = {
+      name: "app",
+      deploy: [
+        { phase: "Build", steps: [{ kind: "fake-plain", note: "x" }] },
+        { phase: "Apply", steps: [{ kind: "fake-stack", stack: "one" }, { kind: "fake-stack", stack: "two" }] },
+      ],
+    };
+    const [out] = applyDeclaredReads([declared], [{ reader: "app", upstream: "network", output: "Arn", at: "/imports/a~1b~0c", index: 1, kind: "fake-stack" }]);
+    const steps = capabilitySteps(out!.deploy);
+    expect(steps[0]).toEqual({ kind: "fake-plain", note: "x" });
+    expect(steps[1]).toEqual({ kind: "fake-stack", stack: "one" });
+    expect(steps[2]).toEqual({ kind: "fake-stack", stack: "two", imports: { "a/b~c": { stackOutput: { stack: "network", name: "Arn" } } } });
+  });
+
+  test("a read of itself, or of a component the project does not have, is dropped; a capability that throws reports none", async () => {
+    const components = [stack("app"), stack("network")];
+    const { registry: r } = registry(() => [
+      { reader: "app", upstream: "app", output: "X", at: "/imports/x" },
+      { reader: "app", upstream: "elsewhere", output: "X", at: "/imports/y" },
+    ]);
+    expect(await declaredReadsOf(components, r, "/project")).toEqual([]);
+    const { registry: throwing } = registry(() => {
+      throw new Error("unreadable");
+    });
+    expect(await declaredReadsOf(components, throwing, "/project")).toEqual([]);
+    expect(await withDeclaredReads(components, throwing, "/project")).toEqual(components);
+  });
+});

package/src/components/declared-reads.ts

@@ -0,0 +1,134 @@
+/**
+ * Reads a capability finds in the files its steps name (#4466).
+ *
+ * A read core can see is a `stackOutput()` or `@<component>.publish.*`
+ * reference in a step. A CloudFormation template that imports another
+ * stack's export reads that stack too, but the read sits inside the
+ * template. A capability that can find such reads says so through
+ * `Capability.declaredReads`, and {@link withDeclaredReads} writes each one
+ * into the reader's step as the `stackOutput()` reference a person would have
+ * written, plus a `dependsOn` on the upstream. From there on it is an ordinary
+ * read: it orders the fan-out, it is named under `unknownInputs` while the
+ * upstream's plan cannot say the value, and a reader whose plan read another
+ * value than the upstream applied is held for a round.
+ */
+
+import type { CapabilityRegistry, DeclaredRead, DeclaredReadMember } from "./capability";
+import type { DriverComponent, DriverPhase, DriverStep } from "./driver";
+import { capabilitySteps } from "./wave-plan";
+
+/** A declared read with the kind of the step it names. */
+export type PlacedRead = DeclaredRead & { index: number; kind: string };
+
+/** `pointer`'s segments, unescaped (RFC 6901). */
+function segments(pointer: string): string[] {
+  if (pointer === "") return [];
+  return pointer
+    .split("/")
+    .slice(1)
+    .map((s) => s.replace(/~1/g, "/").replace(/~0/g, "~"));
+}
+
+/** `value` with `ref` placed at `path`, copying each object on the way; `undefined` when something already sits there. */
+function placed(value: Record<string, unknown>, path: readonly string[], ref: unknown): Record<string, unknown> | undefined {
+  if (path.length === 0) return undefined;
+  const [head, ...rest] = path as [string, ...string[]];
+  const here = value[head];
+  if (rest.length === 0) return here === undefined ? { ...value, [head]: ref } : undefined;
+  if (here !== undefined && (here === null || typeof here !== "object" || Array.isArray(here))) return undefined;
+  const inner = placed((here as Record<string, unknown> | undefined) ?? {}, rest, ref);
+  return inner ? { ...value, [head]: inner } : undefined;
+}
+
+/** `phases` with each step `replace` gives a new value for swapped, in place, nested phases included. */
+function mapSteps(phases: readonly DriverPhase[], replace: (step: DriverStep) => DriverStep): DriverPhase[] {
+  const walk = (steps: DriverPhase["steps"]): DriverPhase["steps"] =>
+    steps.map((step) => {
+      if (typeof (step as DriverPhase).phase === "string" && Array.isArray((step as DriverPhase).steps)) {
+        return { ...(step as DriverPhase), steps: walk((step as DriverPhase).steps) };
+      }
+      if ((step as { kind?: unknown }).kind === "gate") return step;
+      return replace(step as DriverStep);
+    }) as DriverPhase["steps"];
+  return phases.map((phase) => ({ ...phase, steps: walk(phase.steps) }));
+}
+
+/**
+ * Each capability's declared reads among `components` (#4466): every read a
+ * capability with `declaredReads` reports between two components of the
+ * project, its own reads of itself left out. A capability that throws
+ * reports none.
+ */
+export async function declaredReadsOf(
+  components: readonly DriverComponent[],
+  registry: CapabilityRegistry,
+  root: string,
+): Promise<PlacedRead[]> {
+  const names = new Set(components.map((c) => c.name));
+  const byKind = new Map<string, DeclaredReadMember[]>();
+  for (const component of components) {
+    const seen = new Map<string, number>();
+    for (const step of capabilitySteps(component.deploy)) {
+      if (!registry.has(step.kind)) continue;
+      const index = seen.get(step.kind) ?? 0;
+      seen.set(step.kind, index + 1);
+      const { kind, ...rest } = step;
+      (byKind.get(kind) ?? byKind.set(kind, []).get(kind)!).push({ component: component.name, index, step: rest });
+    }
+  }
+  const out: PlacedRead[] = [];
+  for (const [kind, members] of byKind) {
+    const capability = registry.resolve(kind);
+    if (typeof capability.declaredReads !== "function") continue;
+    let reported: DeclaredRead[];
+    try {
+      reported = await capability.declaredReads({ root }, members);
+    } catch {
+      continue;
+    }
+    for (const r of reported ?? []) {
+      if (r.reader === r.upstream || !names.has(r.reader) || !names.has(r.upstream)) continue;
+      out.push({ ...r, index: r.index ?? 0, kind });
+    }
+  }
+  return out.sort((a, b) => a.reader.localeCompare(b.reader) || a.index - b.index || a.at.localeCompare(b.at));
+}
+
+/**
+ * `components` with each declared read written in (#4466): the reader's
+ * step gets `{ stackOutput: { stack: upstream, name: output } }` at the
+ * read's place, unless something sits there already, and the reader depends
+ * on the upstream. Components no read names come back as they were.
+ */
+export function applyDeclaredReads(components: readonly DriverComponent[], reads: readonly PlacedRead[]): DriverComponent[] {
+  const byReader = new Map<string, PlacedRead[]>();
+  for (const r of reads) (byReader.get(r.reader) ?? byReader.set(r.reader, []).get(r.reader)!).push(r);
+  return components.map((component) => {
+    const mine = byReader.get(component.name);
+    if (!mine) return component;
+    const kinds = new Map<string, number>();
+    const added = new Set<string>();
+    const deploy = mapSteps(component.deploy, (step) => {
+      const index = kinds.get(step.kind) ?? 0;
+      kinds.set(step.kind, index + 1);
+      let next: DriverStep = step;
+      for (const r of mine.filter((x) => x.kind === step.kind && x.index === index)) {
+        const { kind, ...rest } = next;
+        const with_ = placed(rest, segments(r.at), { stackOutput: { stack: r.upstream, name: r.output } });
+        if (!with_) continue;
+        next = { kind, ...with_ } as DriverStep;
+        added.add(r.upstream);
+      }
+      return next;
+    });
+    const dependsOn = [...(component.dependsOn ?? [])];
+    for (const up of [...added].sort()) if (!dependsOn.includes(up)) dependsOn.push(up);
+    return { ...component, dependsOn, deploy };
+  });
+}
+
+/** {@link declaredReadsOf} and {@link applyDeclaredReads} in one: `components` with their declared reads written in. */
+export async function withDeclaredReads(components: readonly DriverComponent[], registry: CapabilityRegistry, root: string): Promise<DriverComponent[]> {
+  const reads = await declaredReadsOf(components, registry, root);
+  return reads.length > 0 ? applyDeclaredReads(components, reads) : [...components];
+}

package/src/components/deploy-units.ts

@@ -64,6 +64,10 @@ export const DEPLOY_UNIT_RULES: readonly DeployUnitRule[] = [
   // A Config Connector manifest applied over REST (#4273). Its unit is the
   // step's `stack`, the member its plan names.
   { kind: "gcp-apply", field: "stack", lexicon: "gcp" },
+  // Another workspace member's outputs (#4455). Its unit is the member, so a
+  // change signal naming the member puts the component in the change. No
+  // lexicon observes it: the member's own pipeline reports its status.
+  { kind: "member-outputs", field: "member", lexicon: "workspace" },
 ];
 
 /** One resolved unit a component's deploy composition targets. */

package/src/components/driver.ts

@@ -54,7 +54,8 @@ 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 type { CapabilityRegistry, DeployContext, GroupMemberStatus } from "./capability";
+import type { FanOutGroup } from "./fan-out";
 import { isPlanMovedError, PLAN_MOVED_EXIT_CODE, TargetsRefusedError, targetRefusal } from "./capability";
 import { isPromotedArtifact } from "./auto-release";
 import type { ReleaseIdentity } from "../telemetry-attribution";
@@ -222,6 +223,8 @@ export interface DriverRunResult {
    * component that ran in an earlier job.
    */
   componentOutputs: Record<string, Record<string, unknown>>;
+  /** How each member of a group that ran ended, as its capability said (ws-107, #4465), by component. Absent when no group ran. */
+  groupOutcomes?: Record<string, GroupMemberStatus>;
 }
 
 // ── Graph: order + parallel-safe waves from `dependsOn` ──────────────────────
@@ -391,6 +394,18 @@ export function unresolvedWiringReferences(
   return wiringReferences(input).filter((r) => r.value(componentOutputs) === undefined).map(({ source, ref, publish }) => ({ source, ref, publish }));
 }
 
+/**
+ * Every cross-component reference in `input`, sorted by `ref` and each once,
+ * with whether `componentOutputs` holds a value for it. A pull request's
+ * report records each as a read between components, known at plan or not.
+ */
+export function wiringReads(
+  input: Record<string, unknown>,
+  componentOutputs: Record<string, Record<string, unknown>>,
+): Array<WiringReference & { known: boolean }> {
+  return wiringReferences(input).map(({ source, ref, publish, value }) => ({ source, ref, publish, known: value(componentOutputs) !== undefined }));
+}
+
 /**
  * Every cross-component reference in `input`, each once, sorted by `ref`,
  * with the value it resolves to against a given outputs map.
@@ -424,6 +439,42 @@ function wiringReferences(input: Record<string, unknown>): Array<WiringReference
   return [...found.values()].sort((a, b) => a.ref.localeCompare(b.ref));
 }
 
+/**
+ * Every cross-component reference in `input` with where it sits, as a JSON
+ * Pointer into `input` (ws-107), and the output it names (`publish.<field>`
+ * for an artifact). A reference made twice is listed at each place. Sorted
+ * by `ref`, then by `at`.
+ */
+export function wiringReferencesAt(input: Record<string, unknown>): Array<WiringReference & { at: string; output: string }> {
+  const found: Array<WiringReference & { at: string; output: string }> = [];
+  const pointer = (path: readonly string[]): string => path.map((p) => "/" + p.replace(/~/g, "~0").replace(/\//g, "~1")).join("");
+  const walk = (value: unknown, path: string[]): void => {
+    if (typeof value === "string") {
+      if (PRIOR_STEP_REF.test(value)) return;
+      const ref = value.match(COMPONENT_ARTIFACT_REF);
+      if (ref) {
+        const [, source, field] = ref;
+        found.push({ source, ref: `${source}.publish.${field}`, publish: true, at: pointer(path), output: `publish.${field}` });
+      }
+      return;
+    }
+    if (Array.isArray(value)) {
+      value.forEach((v, i) => walk(v, [...path, String(i)]));
+      return;
+    }
+    if (value && typeof value === "object") {
+      if ("stackOutput" in value) {
+        const { stack, name } = (value as { stackOutput: { stack: string; name: string } }).stackOutput;
+        found.push({ source: stack, ref: `${stack}.${name}`, publish: name === "publish" || name.startsWith("publish."), at: pointer(path), output: name });
+        return;
+      }
+      for (const [k, v] of Object.entries(value as Record<string, unknown>)) walk(v, [...path, k]);
+    }
+  };
+  walk(input, []);
+  return found.sort((a, b) => a.ref.localeCompare(b.ref) || a.at.localeCompare(b.at));
+}
+
 /**
  * The cross-component references in `input` that resolve to another value
  * against `now` than against `read`, sorted (#3999). A pull request's apply
@@ -1136,6 +1187,27 @@ export interface InterpretRunOptions {
   releaseIdentity?: (component: string) => ReleaseIdentity | undefined;
   /** The addresses each component narrows to (#4300), by component: its `DeployContext.targets`. */
   targets?: Readonly<Record<string, readonly string[]>>;
+  /** Groups applied as one (ws-107, #4465). See {@link InterpretGroups}. Absent: every component runs its own deploy. */
+  groups?: InterpretGroups;
+}
+
+/**
+ * Groups a run applies as one (ws-107, #4465): a promote under a release and
+ * `run --components` hand them over, already placed by `groupFanOut`. Each
+ * group runs once, through `run`, in the wave its members sit in and in place
+ * of their own deploys. A member that does not end `ok` stops the run after
+ * its wave, as a failed component does.
+ */
+export interface InterpretGroups {
+  /** The grouped waves, which replace the ones `dependsOn` gives. Every component of the run is in one; an empty wave is passed over. */
+  waves: string[][];
+  /** Each group's members are components of the run, in one wave. */
+  groups: readonly FanOutGroup[];
+  /** Apply one group with the outputs standing, adding each applied member's own: one result per member, and how each ended. */
+  run: (
+    group: FanOutGroup,
+    componentOutputs: Record<string, Record<string, unknown>>,
+  ) => Promise<{ results: DriverComponentResult[]; outcomes: Record<string, GroupMemberStatus> }>;
 }
 
 /**
@@ -1207,8 +1279,20 @@ export async function runInterpretDriver(
   registry: CapabilityRegistry,
   options: InterpretRunOptions,
 ): Promise<DriverRunResult> {
-  const { order, waves } = resolveComponentGraph(components);
+  const graph = resolveComponentGraph(components);
   const byName = new Map(components.map((c) => [c.name, c]));
+  // ws-107 (#4465): the grouped waves, and each member's group.
+  const waves = options.groups ? options.groups.waves.map((w) => w.filter((name) => byName.has(name))).filter((w) => w.length > 0) : graph.waves;
+  const order = options.groups ? waves.flat() : graph.order;
+  const placed = new Set(order);
+  const unplaced = components.filter((c) => !placed.has(c.name)).map((c) => c.name);
+  if (unplaced.length > 0) throw new Error(`the grouped waves leave out ${unplaced.join(", ")}, which this run runs`);
+  // A group keeps its members in this run; one left with fewer than two is no group, and its member runs its own deploy.
+  const runGroups = (options.groups?.groups ?? [])
+    .map((g) => ({ ...g, components: g.components.filter((c) => byName.has(c)) }))
+    .filter((g) => g.components.length > 1);
+  const groupOf = new Map(runGroups.flatMap((g) => g.components.map((c) => [c, g] as const)));
+  const groupOutcomes: Record<string, GroupMemberStatus> = {};
   const componentOutputs: Record<string, Record<string, unknown>> = { ...(options.componentOutputs ?? {}) };
   const emit = joinRunEventSinks(options.onRunEvent, progressSinkOf(options.onProgress));
   const gates: GateContext = {
@@ -1227,8 +1311,19 @@ export async function runInterpretDriver(
   waveLoop: for (const [waveIndex, wave] of waves.entries()) {
     const waveNum = waveIndex + 1;
     emit?.({ type: "wave-start", wave: waveNum, components: wave });
-    const waveComponents = wave.map((name) => byName.get(name)!);
-    const waveResults = await Promise.all(
+    const waveComponents = wave.filter((name) => !groupOf.has(name)).map((name) => byName.get(name)!);
+    const groupsHere = [...new Set(wave.map((name) => groupOf.get(name)).filter((g): g is FanOutGroup => g !== undefined))];
+    // Groups and the wave's other components run side by side, as a wave's components do.
+    const groupResults = Promise.all(
+      groupsHere.map(async (group) => {
+        for (const name of group.components) emit?.({ type: "component-start", wave: waveNum, component: name });
+        const ran = await options.groups!.run(group, componentOutputs);
+        Object.assign(groupOutcomes, ran.outcomes);
+        for (const result of ran.results) emit?.({ type: "component-settle", wave: waveNum, component: result.component, status: progressStatus(result.status) });
+        return ran.results;
+      }),
+    );
+    const ownResults = await Promise.all(
       waveComponents.map(async (component) => {
         emit?.({ type: "component-start", wave: waveNum, component: component.name });
         const result = await runComponentDeploy(
@@ -1244,6 +1339,7 @@ export async function runInterpretDriver(
         return result;
       }),
     );
+    const waveResults = [...ownResults, ...(await groupResults).flat()];
     results.push(...waveResults);
     const stopped = waveResults.find((r) => r.status !== "ok");
     emit?.({ type: "wave-settle", wave: waveNum, status: progressStatus(stopped?.status ?? "ok") });
@@ -1262,6 +1358,7 @@ export async function runInterpretDriver(
   emit?.({ type: "run-settle", status: progressStatus(status), durationMs: null });
   const result: DriverRunResult = {
     order, waves, results, ok, status, failedComponent, componentOutputs,
+    ...(Object.keys(groupOutcomes).length > 0 ? { groupOutcomes } : {}),
     ...(gated
       ? {
           gatedComponent: gated.component,

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

@@ -46,13 +46,14 @@ import {
   type GateContext,
 } from "./driver";
 import type { ReleaseIdentity } from "../telemetry-attribution";
-import { downstreamWithin, remainingFanOut, type FanOutPlan, type FanOutProgress, type FanOutSkip } from "./fan-out";
+import { downstreamWithin, remainingFanOut, type FanOutGroup, type FanOutPlan, type FanOutProgress, type FanOutSkip } from "./fan-out";
 import { evaluateGate, gitGateLedgerPort, type GateCheck, type GateLedgerPort } from "../op/gate";
 import type { RunProgressEvent } from "./run-progress";
 import { emitGateStep, joinRunEventSinks, progressSinkOf, type RunEventSink } from "../run-event-stream";
-import type { CapabilityRegistry } from "./capability";
+import type { CapabilityRegistry, GroupMemberStatus, GroupRun } from "./capability";
 import type { PendingGateRecord } from "../lifecycle/gate-ledger";
 import type { DeployContext } from "./capability";
+import { groupsByComponent, narrowGroups, planAndRunComponentGroup, runComponentGroup } from "./groups";
 import { planWaveComponent, type WaveComponentPlan } from "./wave-plan";
 import { computePlanDigest } from "../lifecycle/plan-digest";
 import { decideWaveGate, runWaveLoop, waveGateName, waveSetDigest, type WaveMember, type WaveRecord } from "../wave-engine";
@@ -247,6 +248,20 @@ export interface FanOutRunOptions {
    * before it applied.
    */
   hold?: (component: string, componentOutputs: Record<string, Record<string, unknown>>) => string | undefined;
+  /**
+   * The approved plan of each group in `plan.groups` (ws-107), by the
+   * group's first component. A group runs through `runGroup` in its wave,
+   * in place of its members' own runs, and is held and blocked as one: a
+   * member held or blocked holds or blocks the rest. Not with `waveGate`.
+   */
+  groupRuns?: Record<string, GroupRun>;
+  /**
+   * A group with no entry in `groupRuns` plans in its wave against the
+   * outputs standing, then applies (#4465): `components fan-out` plans
+   * nothing before it runs. Without it such a group fails, which is what a
+   * pull request's apply wants for a group nobody approved.
+   */
+  planGroupsAtWave?: boolean;
 }
 
 /** A component {@link FanOutRunOptions.hold} held back, or one downstream of it. */
@@ -276,6 +291,14 @@ export interface FanOutRunResult {
   waves?: WaveRecord[];
   /** What {@link FanOutRunOptions.hold} held back, in plan order. Absent when nothing was. */
   held?: FanOutHeld[];
+  /**
+   * Members of a group whose apply stopped before their part began (ws-107),
+   * sorted. Each has a `fail` result but is not in `failed`; what depends on
+   * it outside the group is blocked by it. Absent when none.
+   */
+  notStarted?: string[];
+  /** How each member of a group that ran ended, as its capability said (#4446), by component. Absent when no group ran. */
+  groupOutcomes?: Record<string, GroupMemberStatus>;
 }
 
 /**
@@ -299,7 +322,8 @@ export async function runFanOut(
 
   // Resume first, so the gate is decided against the work that is actually left
   // and a re-run does not re-approve. The digest is carried, not recomputed.
-  const active = options.progress ? remainingFanOut(plan, components, options.progress) : plan;
+  // A group keeps what is left of it (#4465).
+  const active = options.progress ? narrowGroups(remainingFanOut(plan, components, options.progress), components, plan.groups) : plan;
 
   if (options.gate && options.waveGate) {
     throw new Error("a fan-out takes one gate over the set or one gate per wave, not both");
@@ -307,6 +331,9 @@ export async function runFanOut(
   if (options.waveGate && options.plans) {
     throw new Error("a gated-wave fan-out plans each wave itself, so it takes no plans made beforehand");
   }
+  if (options.waveGate && plan.groups?.length) {
+    throw new Error("a gated-wave fan-out plans component by component, so it takes no groups");
+  }
   if (options.waveGate) {
     return runGatedWaves(plan, active, components, registry, options, options.waveGate, gates, componentOutputs);
   }
@@ -348,44 +375,80 @@ export async function runFanOut(
   const results: DriverComponentResult[] = [];
   const completed: string[] = [];
   const failed: string[] = [];
+  const notStarted: string[] = [];
+  const groupOutcomes: Record<string, GroupMemberStatus> = {};
   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 });
+  // ws-107: a group applies as one unit, so it is held and blocked as one.
+  const groupOf = groupsByComponent(active);
+  /** Hold `root` and everything downstream of it that has not settled otherwise. With `heldBy`, `root` is held for that component's reason. */
+  const markHeld = (root: string, reason: string, heldBy?: string): void => {
+    held.set(root, { component: root, reason, ...(heldBy ? { heldBy } : {}) });
     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 });
+      held.set(component, { component, reason, heldBy: 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])) {
-      if (blockedBy.has(component) || failed.includes(component)) continue;
+  /** Skip everything downstream of `roots`, blaming a root rather than the nearest edge. */
+  const markBlocked = (...roots: string[]): void => {
+    for (const [component, by] of downstreamWithin(components, inPlan, roots)) {
+      if (blockedBy.has(component) || failed.includes(component) || completed.includes(component) || notStarted.includes(component)) continue;
       blockedBy.set(component, by);
     }
   };
 
   for (const [waveIndex, wave] of active.waves.entries()) {
     const waveNum = waveIndex + 1;
+    // A member blocked blocks its whole group, by the same failure.
+    for (const name of wave) {
+      const by = blockedBy.get(name);
+      if (by === undefined) continue;
+      for (const mate of groupOf.get(name)?.components ?? []) if (!blockedBy.has(mate) && mate !== by) blockedBy.set(mate, by);
+    }
     // A component whose upstream failed in an earlier wave is not dispatched.
     const candidates = wave.filter((name) => inPlan.has(name) && !blockedBy.has(name) && !held.has(name));
     for (const name of candidates) {
+      if (held.has(name)) continue;
       const reason = options.hold?.(name, componentOutputs);
-      if (reason !== undefined) markHeld(name, reason);
+      if (reason === undefined) continue;
+      markHeld(name, reason);
+      for (const mate of groupOf.get(name)?.components ?? []) if (!held.has(mate)) markHeld(mate, reason, name);
     }
     const runnable = candidates.filter((name) => !held.has(name));
     if (runnable.length === 0) continue;
 
     emit?.({ type: "wave-start", wave: waveNum, components: runnable });
+    const groupsHere = [...new Set(runnable.map((name) => groupOf.get(name)).filter((g): g is FanOutGroup => g !== undefined))];
+    // Groups and the wave's other components run side by side, as a wave's components do.
+    const groupRuns = Promise.all(
+      groupsHere.map(async (group) => {
+        for (const name of group.components) emit?.({ type: "component-start", wave: waveNum, component: name });
+        const approved = options.groupRuns?.[group.components[0]!];
+        const each = {
+          group,
+          components: byName,
+          registry,
+          env: options.env,
+          ...(options.vars ? { vars: options.vars } : {}),
+          ctxOf: (name: string) => fanOutContext(options, name),
+          componentOutputs,
+        };
+        const ran = approved === undefined && options.planGroupsAtWave ? await planAndRunComponentGroup(each) : await runComponentGroup({ ...each, run: approved });
+        for (const result of ran.results) {
+          emit?.({ type: "component-settle", wave: waveNum, component: result.component, status: result.status === "fail" ? "failed" : result.status });
+          options.onComponentSettled?.(result, componentOutputs[result.component]);
+        }
+        return ran;
+      }),
+    );
     const waveResults = await Promise.all(
-      runnable.map(async (name) => {
+      runnable.filter((name) => !groupOf.has(name)).map(async (name) => {
         emit?.({ type: "component-start", wave: waveNum, component: name });
         const planned = options.plans?.[name];
         const result = await runComponentDeploy(
@@ -407,6 +470,7 @@ export async function runFanOut(
         return result;
       }),
     );
+    const groupResults = await groupRuns;
     results.push(...waveResults);
 
     for (const result of waveResults) {
@@ -425,8 +489,22 @@ export async function runFanOut(
       gatedFact ??= result.gate;
       markBlocked(result.component);
     }
+    // A group's members settle together; what depends on a member that failed
+    // or never started, outside the group, is blocked by that member.
+    for (const ran of groupResults) {
+      results.push(...ran.results);
+      Object.assign(groupOutcomes, ran.outcomes);
+      const stopped: string[] = [];
+      for (const result of ran.results) {
+        if (result.status === "ok") completed.push(result.component);
+        else if (ran.notStarted.includes(result.component)) notStarted.push(result.component);
+        else failed.push(result.component);
+        if (result.status !== "ok") stopped.push(result.component);
+      }
+      if (stopped.length > 0) markBlocked(...stopped);
+    }
 
-    const waveFailed = waveResults.some((r) => r.status === "fail");
+    const waveFailed = waveResults.some((r) => r.status === "fail") || groupResults.some((ran) => ran.results.some((r) => r.status === "fail"));
     emit?.({
       type: "wave-settle",
       wave: waveNum,
@@ -442,7 +520,7 @@ export async function runFanOut(
 
   // A failure outranks a gate: something is actually broken, and reporting the
   // run as "waiting on a human" would hide it. Same precedence the driver uses.
-  const status: FanOutRunResult["status"] = failed.length > 0 ? "fail" : gatedFact ? "gated" : "ok";
+  const status: FanOutRunResult["status"] = failed.length > 0 || notStarted.length > 0 ? "fail" : gatedFact ? "gated" : "ok";
   emit?.({ type: "run-settle", status: status === "fail" ? "failed" : status, durationMs: null });
 
   return {
@@ -455,6 +533,8 @@ export async function runFanOut(
     componentOutputs,
     ...(gatedFact ? { gate: gatedFact } : {}),
     ...(held.size > 0 ? { held: active.order.filter((name) => held.has(name)).map((name) => held.get(name)!) } : {}),
+    ...(notStarted.length > 0 ? { notStarted: [...notStarted].sort() } : {}),
+    ...(Object.keys(groupOutcomes).length > 0 ? { groupOutcomes } : {}),
   };
 }
 

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

@@ -19,6 +19,7 @@ import { applyConfigDefaults } from "./config-defaults";
 import { buildCapabilityRegistry } from "./capability-plugin-loader";
 import { componentsForUnits, planFanOut, type ChangedUnits, type ComponentChangeSignal, type FanOutPlan } from "./fan-out";
 import type { CapabilityRegistry } from "./capability";
+import { withDeclaredReads } from "./declared-reads";
 import type { DriverComponent } from "./driver";
 import type { ComponentEnvironmentDeclaration } from "./component";
 import type { BuildParamProvenance } from "../provenance";
@@ -36,6 +37,12 @@ export interface DeriveFanOutOptions {
   config?: ChantConfig;
   /** Components that form wave 1 (#3049). See `FanOutRequest.canary`. */
   canary?: string[];
+  /**
+   * The registry whose capabilities' `declaredReads` (#4466) are written into
+   * the components before the order is derived. Absent, the project's own
+   * (`fanOutRegistry`) is built for it.
+   */
+  registry?: CapabilityRegistry;
 }
 
 export interface DerivedFanOut {
@@ -78,7 +85,9 @@ export async function deriveFanOut(options: DeriveFanOutOptions): Promise<Derive
   }
 
   const { config } = options.config ? { config: options.config } : await loadChantConfig(options.path);
-  const components = resolved.targets.map((component) => applyConfigDefaults(component, config));
+  const defaulted = resolved.targets.map((component) => applyConfigDefaults(component, config));
+  // #4466: the reads a capability finds in its steps' files, such as a template's Fn::ImportValue, order and hold like declared ones.
+  const components = await withDeclaredReads(defaulted, options.registry ?? (await fanOutRegistry(options.path, config)), options.path);
 
   const signal = componentsForUnits(components, options.units);
   const plan = planFanOut({