@intentius/chant 0.124.52 → 0.124.54

package/src/components/cli-support.ts

@@ -39,6 +39,7 @@ import {
   type DriverGate,
   type DriverPhase,
   type DriverRunResult,
+  type InterpretGroups,
 } from "./driver";
 import type { PendingGateRecord } from "../lifecycle/gate-ledger";
 import type { GateDigestMismatch, GateLedgerPort } from "../op/gate";
@@ -51,7 +52,10 @@ import { existsSync, statSync } from "node:fs";
 import { getHeadCommit } from "../lifecycle/git";
 import { buildCapabilityRegistry } from "./capability-plugin-loader";
 import type { CapabilityRegistry } from "./capability";
+import type { FanOutPlan } from "./fan-out";
+import { componentSetFanOut, formRunGroups, planAndRunComponentGroup } from "./groups";
 import { applyConfigDefaults } from "./config-defaults";
+import { withDeclaredReads } from "./declared-reads";
 import { loadChantConfig, type ChantConfig } from "../config";
 
 /** One component in `chant list --components` output. */
@@ -510,6 +514,8 @@ export interface RunComponentsResult {
   };
   /** This run's resolved build-time parameters (chant #1108) — the component-driver counterpart of `../cli/commands/build.ts`'s `BuildResult.buildParams`. Present only once the run actually reached dispatch (mirrors `BuildResult.buildParams`, which is likewise absent on an early-error return). */
   buildParams?: BuildParamProvenance[];
+  /** The grouped fan-out the run applied (ws-107, #4465), when a group formed or a component fell back from one. */
+  grouped?: FanOutPlan;
 }
 
 /**
@@ -545,6 +551,13 @@ export interface ResolvedComponentTargets {
   targets: DriverComponent[];
   /** For a list selector (#3950): the dependencies the closure added that the list did not name, in discovery order. */
   added?: string[];
+  /**
+   * For a list selector: the names the list gave, and every enabled component
+   * the closure was taken over (#4516). `runComponents` takes the closure again
+   * once the declared reads are written in, so a listed importer pulls in the
+   * component whose export it reads.
+   */
+  list?: { named: string[]; enabled: DriverComponent[] };
   /** Component name to the environments it declares (#3153), for the components that declare any (#4330). */
   sites?: Record<string, ComponentEnvironmentDeclaration[]>;
   error?: string;
@@ -650,6 +663,14 @@ function resolveComponentList(
   }
 
   const enabled = withoutDisabled(discovered, all);
+  return { success: true, ...dependencyClosure(names, enabled), list: { named: names, enabled } };
+}
+
+/**
+ * `names` and every component of `enabled` they depend on, transitively, in
+ * `enabled`'s order, and which of those the names did not give (#3950).
+ */
+export function dependencyClosure(names: readonly string[], enabled: readonly DriverComponent[]): { targets: DriverComponent[]; added: string[] } {
   const byName = new Map(enabled.map((c) => [c.name, c]));
   const included = new Set<string>();
   const visit = (name: string): void => {
@@ -662,7 +683,7 @@ function resolveComponentList(
 
   const targets = enabled.filter((c) => included.has(c.name));
   const named = new Set(names);
-  return { success: true, targets, added: targets.map((c) => c.name).filter((n) => !named.has(n)) };
+  return { targets, added: targets.map((c) => c.name).filter((n) => !named.has(n)) };
 }
 
 export async function runComponents(
@@ -674,13 +695,6 @@ export async function runComponents(
   if (!resolved.success) {
     return { success: false, selected: [], error: resolved.error };
   }
-  const targets = resolved.targets;
-  const narrowed = options.targets ?? {};
-  const outside = Object.keys(narrowed).filter((name) => !targets.some((c) => c.name === name));
-  if (outside.length > 0) {
-    return { success: false, selected: [], error: `--target names ${outside.join(", ")}, which this run does not run` };
-  }
-  const targeted = Object.keys(narrowed).length > 0 ? { targets: narrowed } : {};
 
   // (#629) Resolve `chant.config.ts`'s `sbom`/`signing`/`vulnPolicy` sections
   // and fill their defaults into every recognized step (`generate-sbom`,
@@ -700,8 +714,27 @@ export async function runComponents(
       lexicons: lexiconNames(config.lexicons),
     }));
   const env = options.env ?? "local";
-  const selected = targets.map((c) => c.name);
-  const resolvedTargets = targets.map((component) => applyConfigDefaults(component, config));
+  // #4516: the reads a capability finds in its steps' files (a template's
+  // Fn::ImportValue) order a set run as `deriveFanOut` orders a fan-out, so an
+  // importer runs after the component whose export it reads. A list takes its
+  // closure again with them written in, so a listed importer pulls in its
+  // exporter. A single name runs on its own, against seeded outputs.
+  let resolvedTargets: DriverComponent[];
+  let added = resolved.added ?? [];
+  if (resolved.list) {
+    const enabled = await withDeclaredReads(resolved.list.enabled.map((component) => applyConfigDefaults(component, config)), registry, path);
+    ({ targets: resolvedTargets, added } = dependencyClosure(resolved.list.named, enabled));
+  } else {
+    const defaulted = resolved.targets.map((component) => applyConfigDefaults(component, config));
+    resolvedTargets = selector === "all" ? await withDeclaredReads(defaulted, registry, path) : defaulted;
+  }
+  const selected = resolvedTargets.map((c) => c.name);
+  const narrowed = options.targets ?? {};
+  const outside = Object.keys(narrowed).filter((name) => !selected.includes(name));
+  if (outside.length > 0) {
+    return { success: false, selected: [], error: `--target names ${outside.join(", ")}, which this run does not run` };
+  }
+  const targeted = Object.keys(narrowed).length > 0 ? { targets: narrowed } : {};
   // Cross-component/cross-stack outputs to resolve references against. Seeded
   // from a caller (a downstream CI job passing an upstream job's dumped
   // outputs via `--seed-outputs`); grows as this run's components complete.
@@ -719,16 +752,38 @@ export async function runComponents(
 
   try {
     if (selector === "all" || isComponentList(selector)) {
+      // ws-107 (#4465): the components a capability takes as one plan in their
+      // wave and apply as one group, by the rule the pull-request run uses.
+      // A cycle or unknown dependency throws here the error the driver would:
+      // `componentSetFanOut` drops a dependency outside the set, so the full
+      // graph is resolved first.
+      resolveComponentGraph(resolvedTargets);
+      const grouped = await formRunGroups({ components: resolvedTargets, plan: componentSetFanOut(resolvedTargets), registry, env });
       if (isComponentList(selector) && options.onPlan) {
         // Resolved here, before dispatch, so the order is printed before any
-        // component runs. A cycle or unknown dependency throws the same error
-        // `runInterpretDriver` would, caught below.
-        const graph = resolveComponentGraph(resolvedTargets);
-        options.onPlan({ order: graph.order, waves: graph.waves, added: resolved.added ?? [] });
+        // component runs.
+        options.onPlan({ order: grouped.order, waves: grouped.waves.filter((w) => w.length > 0), added });
       }
+      const byName = new Map(resolvedTargets.map((c) => [c.name, c]));
+      const groups: InterpretGroups | undefined = grouped.groups?.length
+        ? {
+            waves: grouped.waves,
+            groups: grouped.groups,
+            run: (group, componentOutputs) =>
+              planAndRunComponentGroup({
+                group,
+                components: byName,
+                registry,
+                env,
+                ctxOf: (name) => deployContext({ env, releaseIdentity, ...targeted }, name),
+                componentOutputs,
+              }),
+          }
+        : undefined;
       const run = await runInterpretDriver(resolvedTargets, registry, {
         env,
         releaseIdentity,
+        ...(groups ? { groups } : {}),
         ...targeted,
         componentOutputs: seedOutputs,
         ...(emit ? { onRunEvent: emit } : {}),
@@ -740,6 +795,7 @@ export async function runComponents(
         selected,
         components: resolvedTargets,
         buildParams: options.buildParams,
+        ...(grouped.groups?.length || grouped.fallbacks?.length ? { grouped } : {}),
         ...(run.status === "gated" && run.gate
           ? {
               gated: {

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` ──────────────────────
@@ -436,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
@@ -1148,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> }>;
 }
 
 /**
@@ -1219,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 = {
@@ -1239,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(
@@ -1256,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") });
@@ -1274,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,