@intentius/chant 0.124.51 → 0.124.54

package/src/components/promote-rounds.ts

@@ -22,6 +22,12 @@
  * A stage whose components declare no gate has nowhere to wait, so the
  * promote stops there with nothing more deployed.
  *
+ * - **Groups** (ws-107, #4465). With `grouped`, the waves are the grouped
+ *   fan-out's, so each group sits in one wave and is checked, planned again
+ *   and run as one: when any member's input moved, every member left of the
+ *   group is planned again with it. Under `--wave-gate` no group forms
+ *   (`formRunGroups`), so there is none here.
+ *
  * A promote that stops at a round's or a wave's gate writes a resume record
  * ({@link PromoteResume}): the components that applied and the outputs they
  * left. The same promote run again with it skips what applied and carries on
@@ -37,6 +43,8 @@ import { waveGateName } from "../gated-waves";
 import { capabilitySteps } from "./wave-plan";
 import type { ChangeSetDocument } from "../change-set";
 import type { ReleasePlan } from "./release-gate";
+import type { FanOutGroup, FanOutPlan } from "./fan-out";
+import { groupsByComponent } from "./groups";
 
 export const PROMOTE_RESUME_SCHEMA = "chant-promote-resume/v1";
 
@@ -90,6 +98,8 @@ export interface PromoteRoundsOptions {
   replan: (only: ReadonlySet<string>, outputs: Record<string, Record<string, unknown>>) => Promise<ChangeSetDocument>;
   /** Store a stage's plan and bind its gates (empty resolutions included). */
   bind: (doc: ChangeSetDocument, gates: string[]) => Promise<ReleaseGateBinding>;
+  /** The grouped fan-out (#4465): its waves replace the ones `dependsOn` gives, and each group is checked as one. */
+  grouped?: FanOutPlan;
 }
 
 export interface PromoteRoundsResult {
@@ -169,7 +179,17 @@ function joinRuns(runs: DriverRunResult[], outputs: Record<string, Record<string
  */
 export async function runPromotionInRounds(options: PromoteRoundsOptions): Promise<PromoteRoundsResult> {
   const byName = new Map(options.components.map((c) => [c.name, c]));
-  const { waves } = resolveComponentGraph(options.components.map((c) => ({ ...c, dependsOn: (c.dependsOn ?? []).filter((d) => byName.has(d)) })));
+  const grouped = options.grouped?.groups?.length ? options.grouped : undefined;
+  const placed = new Set(grouped?.order ?? []);
+  // A grouped fan-out over what a resume left holds no wave for what applied earlier; that is skipped anyway.
+  const waves = grouped
+    ? grouped.waves.map((w) => w.filter((name) => byName.has(name)))
+    : resolveComponentGraph(options.components.map((c) => ({ ...c, dependsOn: (c.dependsOn ?? []).filter((d) => byName.has(d)) }))).waves;
+  if (grouped) {
+    const missing = options.components.filter((c) => !placed.has(c.name) && !(options.completed ?? []).includes(c.name)).map((c) => c.name);
+    if (missing.length > 0) throw new Error(`the grouped waves leave out ${missing.join(", ")}, which this promote runs`);
+  }
+  const groupOf = grouped ? groupsByComponent(grouped) : new Map<string, FanOutGroup>();
   const completed = [...(options.completed ?? [])];
   const done = new Set(completed);
   let outputs = { ...options.outputs };
@@ -181,9 +201,12 @@ export async function runPromotionInRounds(options: PromoteRoundsOptions): Promi
     const waveNumber = index + 1;
     const pending = wave.filter((name) => !done.has(name));
     if (pending.length === 0) continue;
-    const check = options.waveGate !== undefined && waveNumber > 1
+    const moved = options.waveGate !== undefined && waveNumber > 1
       ? pending
       : pending.filter((name) => movedInputs(byName.get(name)!, options.reads[name], outputs).length > 0);
+    // A group is planned again as one: a member whose input moved takes the rest of its group with it.
+    const withMates = new Set(moved.flatMap((name) => [name, ...(groupOf.get(name)?.components ?? [])]));
+    const check = pending.filter((name) => withMates.has(name));
     const batches: Array<{ names: string[]; binding: ReleaseGateBinding; stage?: PromoteStage; rename?: (g: string) => string }> = [];
     const rest = pending.filter((name) => !check.includes(name));
     if (check.length > 0) {

package/src/components/promote.ts

@@ -44,6 +44,8 @@ import { CapabilityRegistry, type Capability } from "./capability";
 import {
   runInterpretDriver,
   DriverRunFailure,
+  deployContext,
+  type InterpretGroups,
   type DriverComponent,
   type DriverComponentResult,
   type DriverGate,
@@ -53,6 +55,9 @@ import {
   type DriverStep,
 } from "./driver";
 import type { GateLedgerPort } from "../op/gate";
+import type { GroupRun } from "./capability";
+import type { FanOutGroup, FanOutPlan } from "./fan-out";
+import { planAndRunComponentGroup, runComponentGroup } from "./groups";
 import type { Release } from "../lifecycle/release-store";
 import type { RunProgressEvent } from "./run-progress";
 import type { RunEventSink } from "../run-event-stream";
@@ -631,6 +636,27 @@ export interface RunPromotionOptions {
   onProgress?: (event: RunProgressEvent) => void;
   /** Where the run's events go (#4041, `--events-json`). */
   onRunEvent?: RunEventSink;
+  /**
+   * The grouped fan-out (ws-107, #4465, `formRunGroups`): each of its groups
+   * applies as one, in the wave it places it in. Absent, or without
+   * `groups`: every component runs its own deploy, as before.
+   */
+  grouped?: FanOutPlan;
+  /**
+   * The approved plan of each group, as the release gate's plan made it
+   * (`ReleasePlan.groups`). A group runs the one whose members are its own;
+   * the newest first. A group with none plans in its wave and applies only
+   * under `planGroupsAtWave`, and fails otherwise.
+   */
+  groupRuns?: readonly GroupRun[];
+  /** A promote with no release gate to bind plans each group in its wave (#4465). */
+  planGroupsAtWave?: boolean;
+}
+
+/** The run in `runs` that plans exactly the members of `group`. */
+function approvedRunOf(runs: readonly GroupRun[] | undefined, group: FanOutGroup): GroupRun | undefined {
+  const want = [...group.components].sort().join("\n");
+  return runs?.find((r) => Object.keys(r.plans).sort().join("\n") === want);
 }
 
 /**
@@ -647,18 +673,42 @@ export async function runPromotion(options: RunPromotionOptions): Promise<Driver
     .filter((c) => names.has(c.name))
     .map((c) => ({ ...c, dependsOn: (c.dependsOn ?? []).filter((d) => names.has(d)) }));
   const expected = new Map(plan.items.map((i) => [i.component, i.digest]));
+  const registry = checkPublishedDigest(options.registry, expected);
+  const releaseIdentity = (component: string) => {
+    const item = plan.items.find((i) => i.component === component);
+    return item ? { version: item.digest, revision: item.source.gitSha } : undefined;
+  };
+  // ws-107 (#4465): a group applies as one, through its approved plan.
+  const grouped = options.grouped?.groups?.length ? options.grouped : undefined;
+  const byName = new Map(targets.map((c) => [c.name, c]));
+  const groups: InterpretGroups | undefined = grouped
+    ? {
+        waves: grouped.waves,
+        groups: grouped.groups!,
+        run: (group, componentOutputs) => {
+          const each = {
+            group,
+            components: byName,
+            registry,
+            env: plan.to,
+            ctxOf: (name: string) => deployContext({ env: plan.to, releaseIdentity }, name),
+            componentOutputs,
+          };
+          const approved = approvedRunOf(options.groupRuns, group);
+          return approved === undefined && options.planGroupsAtWave ? planAndRunComponentGroup(each) : runComponentGroup({ ...each, run: approved });
+        },
+      }
+    : undefined;
   try {
-    return await runInterpretDriver(targets, checkPublishedDigest(options.registry, expected), {
+    return await runInterpretDriver(targets, registry, {
       env: plan.to,
       componentOutputs: options.componentOutputs ?? {},
       // #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;
-      },
+      releaseIdentity,
+      ...(groups ? { groups } : {}),
       ...(options.onProgress ? { onProgress: options.onProgress } : {}),
       ...(options.onRunEvent ? { onRunEvent: options.onRunEvent } : {}),
       ...(options.gates ? { gates: options.gates } : {}),

package/src/components/registry.test.ts

@@ -99,7 +99,7 @@ describe("createCapabilityRegistry", () => {
   // for them to live in instead.
   test("family table lists exactly the agnostic starter families plus the Cloudflare apply leaves (#1293)", () => {
     expect(Object.keys(STARTER_VERB_FAMILIES).sort()).toEqual(
-      ["build", "cloudflare", "escapeHatch", "publish", "sbom", "secrets", "supplyChainPolicy", "supplyChainSecurity", "waitVerify"].sort(),
+      ["build", "cloudflare", "engineOutputs", "escapeHatch", "publish", "sbom", "secrets", "supplyChainPolicy", "supplyChainSecurity", "waitVerify"].sort(),
     );
   });
 

package/src/components/release-gate.ts

@@ -60,7 +60,9 @@
  * recorded since (#4035): its record names what ran before that run.
  */
 
-import type { CapabilityRegistry, PlannedOutputs } from "./capability";
+import type { CapabilityRegistry, GroupRun, PlannedOutputs } from "./capability";
+import type { FanOutGroup, FanOutGroupFallback, FanOutPlan } from "./fan-out";
+import { groupsByComponent, planComponentGroup } from "./groups";
 import { deployContext, resolveComponentGraph, resolveStepInput, unresolvedWiringReferences, type DriverComponent, type DriverGate, type DriverPhase, type DriverStep } from "./driver";
 import { componentPlanDigest } from "./gate-plan";
 import { gateName, RELEASE_GATE_OP } from "../op/gate-name";
@@ -137,6 +139,24 @@ export interface ReleaseChangeSetInput {
    * `seededOutputs`, which then holds what the run left. Default: every one.
    */
   only?: ReadonlySet<string>;
+  /**
+   * The promote's grouped fan-out (ws-107, #4465, `formRunGroups`). Each of
+   * its groups plans with one `planGroup` call in the wave it places it in,
+   * and the group digest is folded into each member's part, so the release
+   * gate's digest binds the composition. Absent, or without `groups`: every
+   * component plans by itself, wave by wave.
+   */
+  grouped?: FanOutPlan;
+}
+
+/** A group the release gate's plan planned as one (ws-107, #4465). */
+export interface ReleasePlanGroup extends FanOutGroup {
+  /** The group digest folded into each member's `planDigest`; `null` when the group failed to plan. */
+  digest: string | null;
+  /** Why the group failed to plan. Every member is then a failed member. */
+  error?: string;
+  /** What `runGroup` gets back. It lives in the process that planned, as the promote that applies it is. */
+  run?: GroupRun;
 }
 
 /** A release's change set for an environment, and what each component was planned against. */
@@ -148,6 +168,10 @@ export interface ReleasePlan {
   plannedOutputs?: Record<string, string[]>;
   /** Per component, the references to a promoted upstream that no value stands for until it applies, sorted. Absent when none. */
   unknownInputs?: Record<string, string[]>;
+  /** The groups planned as one (#4465), in the order they planned. Absent when none. */
+  groups?: ReleasePlanGroup[];
+  /** The components that could have grouped and did not, with why: `grouped.fallbacks`. Absent when none. */
+  fallbacks?: FanOutGroupFallback[];
 }
 
 const byString = (a: string, b: string): number => (a < b ? -1 : a > b ? 1 : 0);
@@ -287,10 +311,94 @@ export async function planReleaseSet(input: ReleaseChangeSetInput): Promise<Rele
   const inPlan = (name: string): boolean => input.only === undefined || input.only.has(name);
   const isPlannable = (c: DriverComponent): boolean =>
     capabilitySteps(c.deploy).some((s) => registry.has(s.kind) && registry.resolve(s.kind).plan !== undefined);
-  const { waves } = resolveComponentGraph(components.map((c) => ({ ...c, dependsOn: (c.dependsOn ?? []).filter((d) => byName.has(d)) })));
+  const failedPart = (member: string, err: unknown): ChangeSetPart => ({
+    member: {
+      member,
+      lexicon: "chant",
+      planner: "chant",
+      status: "failed",
+      error: err instanceof Error ? err.message : String(err),
+      planDigest: null,
+      holes: [],
+    },
+    entries: [],
+  });
+  /** Read each dependency of `component` once, leaving out `mates`, its own group (#4465), and keep what it read. */
+  const readDependencies = async (component: DriverComponent, mates: ReadonlySet<string>): Promise<void> => {
+    for (const dep of component.dependsOn ?? []) {
+      if (mates.has(dep) || read.has(dep) || !byName.has(dep)) continue;
+      read.add(dep);
+      // A dependency this promote plans exposes what its plan says (#3999).
+      if (plannedBy.has(dep) && isPlannable(byName.get(dep)!)) {
+        const known = plannedBy.get(dep)?.known ?? {};
+        outputs[dep] = { ...known };
+        planned[dep] = Object.keys(known).sort();
+        continue;
+      }
+      const found = await readComponentOutputs(byName.get(dep)!, registry, deployContext({ env }, dep), outputs);
+      if (found) outputs[dep] = found;
+    }
+    reads[component.name] = Object.fromEntries(
+      (component.dependsOn ?? []).filter((d) => !mates.has(d) && d in outputs).map((d) => [d, structuredClone(outputs[d])]),
+    );
+  };
+  /** The references of `component`'s plannable steps to a promoted upstream outside `mates` that its plan can't say yet. */
+  const unknownOf = (component: DriverComponent, mates: ReadonlySet<string>): Set<string> => {
+    const unknown = new Set<string>();
+    for (const step of capabilitySteps(component.deploy)) {
+      if (!registry.has(step.kind) || registry.resolve(step.kind).plan === undefined) continue;
+      const { kind: _kind, ...rest } = step;
+      for (const r of unresolvedWiringReferences(rest, outputs)) if (plannedBy.has(r.source) && !r.publish && !mates.has(r.source)) unknown.add(r.ref);
+    }
+    return unknown;
+  };
+
+  // ws-107 (#4465): a group plans once, in the wave the grouped fan-out places it in.
+  const grouped = input.grouped?.groups?.length ? input.grouped : undefined;
+  const groupOf = grouped ? groupsByComponent(grouped) : new Map<string, FanOutGroup>();
+  const groups: ReleasePlanGroup[] = [];
+  const planGroupAt = async (group: FanOutGroup): Promise<void> => {
+    const mates = new Set(group.components);
+    try {
+      for (const name of group.components) await readDependencies(byName.get(name)!, mates);
+    } catch (err) {
+      for (const name of group.components) {
+        plannedBy.set(name, undefined);
+        parts.push(failedPart(name, err));
+      }
+      groups.push({ ...group, digest: null, error: err instanceof Error ? err.message : String(err) });
+      return;
+    }
+    const g = await planComponentGroup({ group, components: byName, registry, env, ctxOf: (name) => deployContext({ env }, name), outputs });
+    const error = g.plans.find((p): p is Extract<typeof p, { error: string }> => "error" in p)?.error;
+    groups.push({ ...group, digest: g.digest ?? null, ...(error !== undefined ? { error } : {}), ...(g.run ? { run: g.run } : {}) });
+    for (const p of g.plans) {
+      if ("error" in p) {
+        plannedBy.set(p.component, undefined);
+        parts.push(failedPart(p.component, p.error));
+        continue;
+      }
+      plannedBy.set(p.component, p.outputs);
+      parts.push(...p.parts);
+      const unknown = unknownOf(byName.get(p.component)!, mates);
+      if (unknown.size > 0) unknownInputs[p.component] = [...unknown].sort();
+    }
+  };
+
+  const waves = grouped
+    ? grouped.waves.map((w) => w.filter((name) => byName.has(name)))
+    : resolveComponentGraph(components.map((c) => ({ ...c, dependsOn: (c.dependsOn ?? []).filter((d) => byName.has(d)) }))).waves;
   for (const wave of waves) {
     const planning = wave.filter(inPlan);
+    const inWave = new Set(planning);
+    // What is left of a group in this plan; one member alone plans by itself.
+    const groupsHere = [...new Set(planning.map((name) => groupOf.get(name)).filter((g): g is FanOutGroup => g !== undefined))]
+      .map((g) => ({ ...g, components: g.components.filter((c) => inWave.has(c)) }))
+      .filter((g) => g.components.length > 1);
+    const grouping = new Set(groupsHere.flatMap((g) => g.components));
+    for (const group of groupsHere) await planGroupAt(group);
     for (const name of planning) {
+      if (grouping.has(name)) continue;
       const component = byName.get(name)!;
       const digest = input.digests.get(name) ?? "";
       const plannable = capabilitySteps(component.deploy).filter((s) => registry.has(s.kind) && registry.resolve(s.kind).plan !== undefined);
@@ -300,25 +408,11 @@ export async function planReleaseSet(input: ReleaseChangeSetInput): Promise<Rele
       }
       const ctx = deployContext({ env }, name);
       try {
-        for (const dep of component.dependsOn ?? []) {
-          if (read.has(dep) || !byName.has(dep)) continue;
-          read.add(dep);
-          // A dependency this promote plans exposes what its plan says (#3999).
-          if (plannedBy.has(dep) && isPlannable(byName.get(dep)!)) {
-            const known = plannedBy.get(dep)?.known ?? {};
-            outputs[dep] = { ...known };
-            planned[dep] = Object.keys(known).sort();
-            continue;
-          }
-          const found = await readComponentOutputs(byName.get(dep)!, registry, deployContext({ env }, dep), outputs);
-          if (found) outputs[dep] = found;
-        }
-        reads[name] = Object.fromEntries((component.dependsOn ?? []).filter((d) => d in outputs).map((d) => [d, structuredClone(outputs[d])]));
-        const unknown = new Set<string>();
+        await readDependencies(component, new Set());
+        const unknown = unknownOf(component, new Set());
         let exposes: PlannedOutputs | undefined;
         for (const step of plannable) {
           const { kind, ...rest } = step;
-          for (const r of unresolvedWiringReferences(rest, outputs)) if (plannedBy.has(r.source) && !r.publish) unknown.add(r.ref);
           const result = await registry.resolve(kind).plan!(planContext(ctx, rest, outputs), resolveStepInput(rest, {}, outputs) as never);
           if (result.outputs) exposes = { known: { ...(exposes?.known ?? {}), ...result.outputs.known }, unknown: [...new Set([...(exposes?.unknown ?? []), ...result.outputs.unknown])].sort() };
           parts.push(
@@ -339,18 +433,7 @@ export async function planReleaseSet(input: ReleaseChangeSetInput): Promise<Rele
         if (unknown.size > 0) unknownInputs[name] = [...unknown].sort();
       } catch (err) {
         plannedBy.set(name, undefined);
-        parts.push({
-          member: {
-            member: name,
-            lexicon: "chant",
-            planner: "chant",
-            status: "failed",
-            error: err instanceof Error ? err.message : String(err),
-            planDigest: null,
-            holes: [],
-          },
-          entries: [],
-        });
+        parts.push(failedPart(name, err));
       }
     }
   }
@@ -363,6 +446,8 @@ export async function planReleaseSet(input: ReleaseChangeSetInput): Promise<Rele
     reads,
     ...(Object.keys(planned).length > 0 ? { plannedOutputs: planned } : {}),
     ...(Object.keys(unknownInputs).length > 0 ? { unknownInputs } : {}),
+    ...(groups.length > 0 ? { groups } : {}),
+    ...(input.grouped?.fallbacks?.length ? { fallbacks: input.grouped.fallbacks } : {}),
   };
 }