@intentius/chant 0.124.40 → 0.124.42

package/src/pr-requires.test.ts

@@ -0,0 +1,184 @@
+/**
+ * The requires checks of an apply before merge (#4301, ws-106): the four
+ * PrForge methods on GitHub, Forgejo and GitLab, driven through a recording
+ * fake forge, and checkPrRequires over them.
+ */
+
+import { describe, expect, test } from "vitest";
+import { forgejoForge, githubForge, gitlabForge, type ForgeFetch, type PrForge } from "./pr-forge";
+import { checkPrRequires, PR_APPLY_REQUIRES, unmetRequires } from "./pr-requires";
+
+/** A fake forge: `routes` maps `METHOD path-without-query` to a body, a status, or a function of the query. */
+function fakeFetch(routes: Record<string, unknown | ((q: URLSearchParams) => unknown)>): ForgeFetch {
+  return async (url, init) => {
+    const u = new URL(url);
+    let found = routes[`${init.method} ${u.pathname}`];
+    if (typeof found === "function") found = (found as (q: URLSearchParams) => unknown)(u.searchParams);
+    if (found === undefined) return { ok: false, status: 404, text: async () => '{"message":"Not Found"}' };
+    if (typeof found === "number") return { ok: false, status: found, text: async () => "" };
+    return { ok: true, status: 200, text: async () => JSON.stringify(found) };
+  };
+}
+
+const HEAD = "a".repeat(40);
+const TIP = "b".repeat(40);
+const OTHER = "c".repeat(40);
+
+describe("github", () => {
+  const repo = "/repos/acme/infra";
+  const pull = (over: Record<string, unknown> = {}) => ({ number: 7, state: "open", user: { login: "alice" }, head: { ref: "f", sha: HEAD }, base: { ref: "main" }, mergeable: true, mergeable_state: "clean", ...over });
+  const forge = (routes: Record<string, unknown>) =>
+    githubForge({ apiBase: "https://api.github.com", repo: "acme/infra", token: "t", fetch: fakeFetch({ [`GET ${repo}/pulls/7`]: pull(), [`GET ${repo}/pulls/7/commits`]: [{ author: { login: "alice" }, committer: { login: "alice" } }], ...routes }) });
+
+  test("approved: a reviewer other than the authors approved this head", async () => {
+    const f = forge({ [`GET ${repo}/pulls/7/reviews`]: [{ user: { login: "bob" }, state: "APPROVED", commit_id: HEAD }] });
+    expect(await f.prApproved!(7, HEAD)).toEqual({ passed: true, reason: "approved at aaaaaaaa by bob" });
+  });
+
+  test("approved: an approval of an older head, the author's own, or a request for changes does not pass", async () => {
+    const older = forge({ [`GET ${repo}/pulls/7/reviews`]: [{ user: { login: "bob" }, state: "APPROVED", commit_id: OTHER }, { user: { login: "alice" }, state: "APPROVED", commit_id: HEAD }] });
+    expect((await older.prApproved!(7, HEAD)).passed).toBe(false);
+    const changes = forge({ [`GET ${repo}/pulls/7/reviews`]: [{ user: { login: "bob" }, state: "APPROVED", commit_id: HEAD }, { user: { login: "carol" }, state: "CHANGES_REQUESTED", commit_id: HEAD }] });
+    expect(await changes.prApproved!(7, HEAD)).toEqual({ passed: false, reason: "carol asked for changes" });
+  });
+
+  test("every check fails when the forge's head is another commit", async () => {
+    const f = forge({ [`GET ${repo}/pulls/7`]: pull({ head: { ref: "f", sha: OTHER } }) });
+    const r = await f.prMergeable!(7, HEAD);
+    expect(r.passed).toBe(false);
+    expect(r.reason).toContain("head is cccccccc, not aaaaaaaa");
+  });
+
+  test("mergeable: conflicts and branch protection refuse, an unknown answer is pending", async () => {
+    expect((await forge({}).prMergeable!(7, HEAD)).passed).toBe(true);
+    expect((await forge({ [`GET ${repo}/pulls/7`]: pull({ mergeable: false, mergeable_state: "dirty" }) }).prMergeable!(7, HEAD)).reason).toContain("conflicts with main");
+    expect((await forge({ [`GET ${repo}/pulls/7`]: pull({ mergeable_state: "blocked" }) }).prMergeable!(7, HEAD)).reason).toContain("branch protection");
+    expect(await forge({ [`GET ${repo}/pulls/7`]: pull({ mergeable: null }) }).prMergeable!(7, HEAD)).toMatchObject({ passed: false, pending: true });
+  });
+
+  test("undiverged: reads behind_by from the compare of the base branch with the head", async () => {
+    expect((await forge({ [`GET ${repo}/compare/main...${HEAD}`]: { behind_by: 0 } }).prUndiverged!(7, HEAD)).passed).toBe(true);
+    expect((await forge({ [`GET ${repo}/compare/main...${HEAD}`]: { behind_by: 2 } }).prUndiverged!(7, HEAD)).reason).toBe("aaaaaaaa is 2 commits behind main");
+  });
+
+  test("checks: statuses and check runs, the apply's own left out", async () => {
+    const statuses = (state: string) => ({ statuses: [{ context: "ci/test", state }, { context: "chant/apply", state: "failure" }] });
+    const runs = (conclusion: string | null, status = "completed") => ({ check_runs: [{ name: "lint", status, conclusion }] });
+    const f = (state: string, run: unknown) => forge({ [`GET ${repo}/commits/${HEAD}/status`]: statuses(state), [`GET ${repo}/commits/${HEAD}/check-runs`]: run });
+    expect(await f("success", runs("success")).prChecksPassed!(7, HEAD, ["chant/apply"])).toEqual({ passed: true, reason: "2 checks passed on aaaaaaaa" });
+    expect((await f("success", runs("success")).prChecksPassed!(7, HEAD)).reason).toBe("chant/apply failed on aaaaaaaa");
+    expect(await f("pending", runs("success")).prChecksPassed!(7, HEAD, ["chant/apply"])).toMatchObject({ passed: false, pending: true });
+    expect((await f("success", runs(null, "in_progress")).prChecksPassed!(7, HEAD, ["chant/apply"])).pending).toBe(true);
+    expect((await f("success", runs("failure")).prChecksPassed!(7, HEAD, ["chant/apply"])).reason).toBe("lint failed on aaaaaaaa");
+  });
+
+  test("checks: nothing reported is pending", async () => {
+    const f = forge({ [`GET ${repo}/commits/${HEAD}/status`]: { statuses: [] }, [`GET ${repo}/commits/${HEAD}/check-runs`]: { check_runs: [] } });
+    expect(await f.prChecksPassed!(7, HEAD)).toMatchObject({ passed: false, pending: true });
+  });
+});
+
+describe("forgejo", () => {
+  const repo = "/api/v1/repos/acme/infra";
+  const pull = (over: Record<string, unknown> = {}) => ({ number: 4, user: { login: "alice" }, head: { ref: "f", sha: HEAD }, base: { ref: "main" }, mergeable: true, merge_base: TIP, ...over });
+  const forge = (routes: Record<string, unknown>) =>
+    forgejoForge({ apiBase: "https://code.example/api/v1", repo: "acme/infra", host: "code.example", token: "t", fetch: fakeFetch({ [`GET ${repo}/pulls/4`]: pull(), [`GET ${repo}/pulls/4/commits`]: [], [`GET ${repo}/branches/main`]: { commit: { id: TIP } }, ...routes }) });
+
+  test("approved: Forgejo's REQUEST_CHANGES state refuses", async () => {
+    const f = forge({ [`GET ${repo}/pulls/4/reviews`]: [{ user: { login: "bob" }, state: "APPROVED", commit_id: HEAD }, { user: { login: "dave" }, state: "REQUEST_CHANGES" }] });
+    expect((await f.prApproved!(4, HEAD)).reason).toBe("dave asked for changes");
+  });
+
+  test("undiverged: the pull request's merge base is the base branch's tip", async () => {
+    expect((await forge({}).prUndiverged!(4, HEAD)).passed).toBe(true);
+    expect((await forge({ [`GET ${repo}/pulls/4`]: pull({ merge_base: OTHER }) }).prUndiverged!(4, HEAD)).reason).toBe("aaaaaaaa does not contain main at bbbbbbbb");
+  });
+
+  test("mergeable: no branch protection reading, and checks from the combined status alone", async () => {
+    expect((await forge({ [`GET ${repo}/pulls/4`]: pull({ mergeable_state: "blocked" }) }).prMergeable!(4, HEAD)).passed).toBe(true);
+    const f = forge({ [`GET ${repo}/commits/${HEAD}/status`]: { statuses: [{ context: "ci/test", status: "success" }] } });
+    expect(await f.prChecksPassed!(4, HEAD)).toEqual({ passed: true, reason: "1 check passed on aaaaaaaa" });
+  });
+});
+
+describe("gitlab", () => {
+  const project = "/api/v4/projects/9";
+  const mr = (over: Record<string, unknown> = {}) => ({ iid: 3, sha: HEAD, author: { username: "alice" }, target_branch: "main", detailed_merge_status: "mergeable", diverged_commits_count: 0, ...over });
+  const note = (who: string, body: string, at: string) => ({ system: true, author: { username: who }, body, created_at: at });
+  const forge = (routes: Record<string, unknown>) =>
+    gitlabForge({
+      apiBase: "https://gitlab.example/api/v4",
+      project: "9",
+      token: "t",
+      host: "gitlab.example",
+      fetch: fakeFetch({
+        [`GET ${project}/merge_requests/3`]: mr(),
+        [`GET ${project}/merge_requests/3/commits`]: [],
+        "GET /api/v4/user": { id: 1, username: "chant-bot" },
+        [`GET ${project}/merge_requests/3/versions`]: [{ created_at: "2026-10-01T10:00:00Z" }],
+        ...routes,
+      }),
+    });
+
+  test("approved: an approval after the latest push, not the token user's or the author's", async () => {
+    const f = forge({
+      [`GET ${project}/merge_requests/3/notes`]: [
+        note("erin", "approved this merge request", "2026-10-01T09:00:00Z"),
+        note("chant-bot", "approved this merge request", "2026-10-01T11:00:00Z"),
+        note("alice", "approved this merge request", "2026-10-01T11:00:00Z"),
+      ],
+    });
+    expect((await f.prApproved!(3, HEAD)).passed).toBe(false);
+    const g = forge({ [`GET ${project}/merge_requests/3/notes`]: [note("bob", "approved this merge request", "2026-10-01T11:00:00Z")] });
+    expect(await g.prApproved!(3, HEAD)).toEqual({ passed: true, reason: "approved after aaaaaaaa by bob" });
+    const h = forge({ [`GET ${project}/merge_requests/3/notes`]: [note("bob", "approved this merge request", "2026-10-01T11:00:00Z"), note("carol", "requested changes", "2026-10-01T12:00:00Z")] });
+    expect((await h.prApproved!(3, HEAD)).reason).toBe("carol requested changes");
+  });
+
+  test("mergeable and undiverged read the merge request", async () => {
+    expect((await forge({}).prMergeable!(3, HEAD)).passed).toBe(true);
+    expect(await forge({ [`GET ${project}/merge_requests/3`]: mr({ detailed_merge_status: "checking" }) }).prMergeable!(3, HEAD)).toMatchObject({ passed: false, pending: true });
+    expect((await forge({ [`GET ${project}/merge_requests/3`]: mr({ has_conflicts: true, detailed_merge_status: "conflict" }) }).prMergeable!(3, HEAD)).reason).toContain("conflicts");
+    expect((await forge({}).prUndiverged!(3, HEAD)).passed).toBe(true);
+    expect((await forge({ [`GET ${project}/merge_requests/3`]: mr({ diverged_commits_count: 1 }) }).prUndiverged!(3, HEAD)).reason).toBe("aaaaaaaa is 1 commit behind main");
+  });
+
+  test("checks: each name's newest status, a job allowed to fail holding nothing back", async () => {
+    const f = forge({
+      [`GET ${project}/repository/commits/${HEAD}/statuses`]: [
+        { id: 1, name: "test", status: "failed" },
+        { id: 2, name: "test", status: "success" },
+        { id: 3, name: "flaky", status: "failed", allow_failure: true },
+        { id: 4, name: "apply", status: "running" },
+      ],
+    });
+    expect(await f.prChecksPassed!(3, HEAD, ["apply"])).toEqual({ passed: true, reason: "2 checks passed on aaaaaaaa" });
+    expect((await f.prChecksPassed!(3, HEAD)).pending).toBe(true);
+  });
+});
+
+describe("checkPrRequires", () => {
+  const ok = { passed: true, reason: "ok" };
+  test("asks each check once in order, and a pending one again until it settles", async () => {
+    let reads = 0;
+    const forge = {
+      kind: "github",
+      prApproved: async () => ok,
+      prMergeable: async () => (++reads < 3 ? { passed: false, pending: true, reason: "working it out" } : ok),
+      prUndiverged: async () => ok,
+      prChecksPassed: async (_pr: number, _head: string, ignore?: readonly string[]) => ({ passed: true, reason: `ignored ${ignore?.join(",")}` }),
+    } as unknown as PrForge;
+    const out = await checkPrRequires(forge, 7, HEAD, { ignore: ["chant/apply"], wait: async () => {} });
+    expect(out.map((o) => o.name)).toEqual([...PR_APPLY_REQUIRES]);
+    expect(reads).toBe(3);
+    expect(out[3]!.reason).toBe("ignored chant/apply");
+    expect(unmetRequires(out)).toBeNull();
+  });
+
+  test("a client without a method, or a call that throws, is unmet", async () => {
+    const forge = { kind: "gitlab", prApproved: async () => { throw new Error("401"); } } as unknown as PrForge;
+    const out = await checkPrRequires(forge, 3, HEAD, { reads: 1 });
+    expect(out.every((o) => !o.passed)).toBe(true);
+    expect(unmetRequires(out)).toBe("approved: could not ask gitlab: 401; mergeable: this gitlab client cannot say; undiverged: this gitlab client cannot say; checks: this gitlab client cannot say");
+  });
+});

package/src/pr-requires.ts

@@ -0,0 +1,79 @@
+/**
+ * The requires checks of an apply before merge (#4301, ws-106): the pull
+ * request is approved, mergeable, undiverged and its checks passed, each
+ * asked of the forge through its {@link PrForge} method. All four must pass.
+ *
+ * The checks are terragucci's `apply.requires` (comment-apply.ts:781-860 at
+ * INTENTIUS/terragucci e6cb431), with no setting to drop one. A check the
+ * forge has not settled, such as GitHub working out whether a pull request
+ * can merge, is asked again a few times before it counts as unmet.
+ *
+ * Like ./pr-forge.ts this imports nothing beyond it, so a product bundles it
+ * without the TypeScript toolchain.
+ */
+import type { PrForge, PrRequireResult } from "./pr-forge";
+
+/** The four checks, in the order they run and the report lists them. */
+export const PR_APPLY_REQUIRES = ["approved", "mergeable", "undiverged", "checks"] as const;
+
+export type PrApplyRequire = (typeof PR_APPLY_REQUIRES)[number];
+
+/** One check as the pull-request report's `beforeMerge.requires` holds it. */
+export interface PrRequireOutcome extends PrRequireResult {
+  name: PrApplyRequire;
+}
+
+export interface PrRequiresOptions {
+  /** Status names the `checks` require leaves out: the apply's own. */
+  ignore?: readonly string[];
+  /** How many times a pending check is asked in all. Default 5. */
+  reads?: number;
+  /** The wait between reads. Default 3 seconds. */
+  wait?: (ms: number) => Promise<void>;
+}
+
+const READS = 5;
+const WAIT_MS = 3000;
+
+/**
+ * Ask `forge` each of the four checks for pull request `pr` at `head`. A
+ * forge client without a method, or a call that throws, gives an unmet
+ * check with the reason, so nothing applies on a check nobody made.
+ */
+export async function checkPrRequires(forge: PrForge, pr: number, head: string, opts: PrRequiresOptions = {}): Promise<PrRequireOutcome[]> {
+  const wait = opts.wait ?? ((ms: number) => new Promise<void>((r) => setTimeout(r, ms)));
+  const reads = Math.max(1, opts.reads ?? READS);
+  const ask: Record<PrApplyRequire, (() => Promise<PrRequireResult>) | undefined> = {
+    approved: forge.prApproved ? () => forge.prApproved!(pr, head) : undefined,
+    mergeable: forge.prMergeable ? () => forge.prMergeable!(pr, head) : undefined,
+    undiverged: forge.prUndiverged ? () => forge.prUndiverged!(pr, head) : undefined,
+    checks: forge.prChecksPassed ? () => forge.prChecksPassed!(pr, head, opts.ignore ?? []) : undefined,
+  };
+  const out: PrRequireOutcome[] = [];
+  for (const name of PR_APPLY_REQUIRES) {
+    const call = ask[name];
+    if (!call) {
+      out.push({ name, passed: false, reason: `this ${forge.kind} client cannot say` });
+      continue;
+    }
+    let result: PrRequireResult;
+    for (let read = 1; ; read++) {
+      try {
+        result = await call();
+      } catch (err) {
+        result = { passed: false, reason: `could not ask ${forge.kind}: ${err instanceof Error ? err.message : String(err)}` };
+      }
+      if (result.passed || !result.pending || read >= reads) break;
+      await wait(WAIT_MS);
+    }
+    out.push({ name, ...result });
+  }
+  return out;
+}
+
+/** The unmet checks as one line, or null when all four passed. */
+export function unmetRequires(outcomes: readonly PrRequireOutcome[]): string | null {
+  const unmet = outcomes.filter((o) => !o.passed);
+  if (unmet.length === 0) return null;
+  return unmet.map((o) => `${o.name}: ${o.reason}`).join("; ");
+}

package/src/review-agent-bundle.test.ts

@@ -0,0 +1,35 @@
+/**
+ * The review agent bundles alone (#4299): a product such as terragucci
+ * imports `@intentius/chant/op/activities/review-agent` into one bundled
+ * file, so it must not reach predict-behaviour's estate code. This bundles
+ * the module and reads esbuild's list of what went in.
+ */
+
+import { join } from "node:path";
+import { build } from "esbuild";
+import { describe, expect, test } from "vitest";
+import { REPO } from "./workspace/__fixtures__/contract-repo";
+
+describe("the review-agent bundle", () => {
+  test("holds the review agent, the note it posts through and nothing else", async () => {
+    const result = await build({
+      entryPoints: [join(REPO, "packages", "core", "src", "op", "activities", "review-agent.ts")],
+      bundle: true,
+      platform: "node",
+      format: "esm",
+      write: false,
+      metafile: true,
+      outdir: "out",
+      logLevel: "silent",
+    });
+    expect(Object.keys(result.metafile.inputs).map((i) => i.replace(/^.*?packages\//, "packages/")).sort()).toEqual([
+      "packages/core/src/op/activities/forge-pull-request.ts",
+      "packages/core/src/op/activities/gh-host.ts",
+      "packages/core/src/op/activities/pr-refs.ts",
+      "packages/core/src/op/activities/reconcile.ts",
+      "packages/core/src/op/activities/review-agent.ts",
+      "packages/core/src/pr-forge.ts",
+    ]);
+    expect(result.outputFiles.reduce((n, f) => n + f.contents.byteLength, 0)).toBeLessThan(96 * 1024);
+  });
+});

package/src/stage-hooks-bundle.test.ts

@@ -0,0 +1,38 @@
+/**
+ * The stage-hook runner bundles alone (#4288): a product that runs
+ * `ci.hooks` around its own stages imports
+ * `@intentius/chant/op/stage-hooks` into one bundled file, without the wave
+ * loop, the gate or the ledger. This bundles the module and reads esbuild's
+ * list of what went in.
+ */
+
+import { join } from "node:path";
+import { build } from "esbuild";
+import { describe, expect, test } from "vitest";
+import { REPO } from "./workspace/__fixtures__/contract-repo";
+
+describe("the stage-hooks bundle", () => {
+  test("holds the hook runner and the Op waves spec, and no wave loop, gate or ledger", async () => {
+    const result = await build({
+      entryPoints: [join(REPO, "packages", "core", "src", "op", "stage-hooks.ts")],
+      bundle: true,
+      platform: "node",
+      format: "esm",
+      write: false,
+      metafile: true,
+      outdir: "out",
+      logLevel: "silent",
+    });
+    expect(Object.keys(result.metafile.inputs).map((i) => i.replace(/^.*?packages\//, "packages/")).sort()).toEqual([
+      "packages/core/src/lifecycle/gate-seal.ts",
+      "packages/core/src/notify-verify.ts",
+      "packages/core/src/notify.ts",
+      "packages/core/src/op/gate-point.ts",
+      "packages/core/src/op/gate-quorum.ts",
+      "packages/core/src/op/op-waves.ts",
+      "packages/core/src/op/stage-hooks.ts",
+      "packages/core/src/wave-layout.ts",
+    ]);
+    expect(result.outputFiles.reduce((n, f) => n + f.contents.byteLength, 0)).toBeLessThan(48 * 1024);
+  });
+});

package/src/wave-blocked-bundle.test.ts

@@ -0,0 +1,25 @@
+/**
+ * The blocked-member rules bundle on their own (#4291): terragucci calls them
+ * from its CI stages as one bundled file with no TypeScript toolchain, as it
+ * calls `./gated-waves` (#3421).
+ */
+
+import { join } from "node:path";
+import { build } from "esbuild";
+import { expect, test } from "vitest";
+import { REPO } from "./workspace/__fixtures__/contract-repo";
+
+test("wave-blocked bundles with nothing but itself", async () => {
+  const result = await build({
+    entryPoints: [join(REPO, "packages", "core", "src", "wave-blocked.ts")],
+    bundle: true,
+    platform: "node",
+    format: "esm",
+    write: false,
+    metafile: true,
+    outdir: "out",
+    logLevel: "silent",
+  });
+  expect(Object.keys(result.metafile.inputs).map((i) => i.replace(/^.*?packages\//, "packages/"))).toEqual(["packages/core/src/wave-blocked.ts"]);
+  expect(result.outputFiles.reduce((n, f) => n + f.contents.byteLength, 0)).toBeLessThan(12 * 1024);
+});

package/src/wave-blocked.test.ts

@@ -0,0 +1,146 @@
+/**
+ * A failed member blocks only the members that depend on it (#4291): the
+ * rule, the walk over earlier waves, and the outcome files a wave job hands
+ * the next one. The rules are terragucci's `blocked.ts`, lifted.
+ */
+
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, test } from "vitest";
+import {
+  blockedMembers,
+  blockedWords,
+  earlierWaveOutcomes,
+  onlyWaiting,
+  runSummary,
+  settleEarlierWaves,
+  waveOutcomeFileName,
+  writeWaveOutcomeFile,
+  type WaveMemberOutcome,
+} from "./wave-blocked";
+
+/** cluster-a and cluster-b, then app-01 (reads cluster-a) and app-02 (reads cluster-b), then edge (reads app-01). */
+const UPSTREAMS = new Map<string, string[]>([
+  ["app-01", ["cluster-a"]],
+  ["app-02", ["cluster-b"]],
+  ["edge", ["app-01"]],
+]);
+const WAVES = [["cluster-a", "cluster-b"], ["app-01", "app-02"], ["edge"]];
+
+describe("blockedMembers", () => {
+  test("a failed upstream blocks its dependents and names itself; the rest go through", () => {
+    const outcomes = new Map<string, WaveMemberOutcome>([
+      ["cluster-a", { status: "failed" }],
+      ["cluster-b", { status: "applied" }],
+    ]);
+    const blocked = blockedMembers(["app-01", "app-02"], UPSTREAMS, new Set(WAVES[0]), outcomes);
+    expect([...blocked]).toEqual([["app-01", "cluster-a"]]);
+  });
+
+  test("a blocked upstream passes on the member that blocked it", () => {
+    const outcomes = new Map<string, WaveMemberOutcome>([["app-01", { status: "blocked", by: "cluster-a" }]]);
+    expect([...blockedMembers(["edge"], UPSTREAMS, new Set(["app-01"]), outcomes)]).toEqual([["edge", "cluster-a"]]);
+  });
+
+  test("unchanged lets a dependent through; an upstream with no outcome holds it", () => {
+    expect(blockedMembers(["app-01"], UPSTREAMS, new Set(["cluster-a"]), new Map([["cluster-a", { status: "unchanged" }]])).size).toBe(0);
+    expect([...blockedMembers(["app-01"], UPSTREAMS, new Set(["cluster-a"]), new Map())]).toEqual([["app-01", "cluster-a"]]);
+  });
+
+  test("an upstream outside the earlier waves is no upstream here", () => {
+    expect(blockedMembers(["app-01"], UPSTREAMS, new Set(), new Map([["cluster-a", { status: "failed" }]])).size).toBe(0);
+  });
+
+  test("a wave that holds all blocks every member by its name", () => {
+    expect([...blockedMembers(["app-01", "app-02"], UPSTREAMS, new Set(), new Map(), 1)]).toEqual([
+      ["app-01", "wave-1"],
+      ["app-02", "wave-1"],
+    ]);
+  });
+});
+
+describe("settleEarlierWaves", () => {
+  test("walks the earlier waves, blocking behind failures, and names what has not run", () => {
+    const { outcomes, unsettled } = settleEarlierWaves(
+      WAVES,
+      4,
+      UPSTREAMS,
+      new Map([
+        ["cluster-a", { status: "failed" }],
+        ["cluster-b", { status: "applied" }],
+      ]),
+    );
+    expect(outcomes.get("app-01")).toEqual({ status: "blocked", by: "cluster-a" });
+    expect(outcomes.get("edge")).toEqual({ status: "blocked", by: "cluster-a" });
+    expect(unsettled).toEqual(["app-02"]);
+  });
+});
+
+describe("onlyWaiting, blockedWords and runSummary", () => {
+  test("a run whose only holds are a wait, and what it blocked, waits", () => {
+    expect(
+      onlyWaiting(
+        new Map<string, WaveMemberOutcome>([
+          ["cluster-a", { status: "waiting" }],
+          ["app-01", { status: "blocked", by: "cluster-a" }],
+          ["cluster-b", { status: "applied" }],
+        ]),
+      ),
+    ).toBe(true);
+    expect(onlyWaiting(new Map<string, WaveMemberOutcome>([["cluster-a", { status: "failed" }]]))).toBe(false);
+    expect(onlyWaiting(new Map<string, WaveMemberOutcome>([["cluster-a", { status: "applied" }]]))).toBe(false);
+  });
+
+  test("the blocked set reads grouped by what blocked it", () => {
+    expect(blockedWords(new Map([["edge", "cluster-a"], ["app-01", "cluster-a"], ["app-02", "cluster-b"]]))).toBe(
+      "app-01, edge (blocked by cluster-a); app-02 (blocked by cluster-b)",
+    );
+  });
+
+  test("the run's summary counts each status, and is undefined when all applied", () => {
+    expect(runSummary([{ status: "applied" }, { status: "unchanged" }])).toBeUndefined();
+    expect(runSummary([{ status: "applied" }, { status: "failed" }, { status: "blocked", by: "x" }, { status: "waiting" }])).toBe(
+      "1 applied, 1 failed, 1 blocked, 1 waiting",
+    );
+  });
+});
+
+describe("outcome files", () => {
+  test("the newest outcome of a member wins, later waves are left out, and terragucci's roots key reads too", () => {
+    const dir = mkdtempSync(join(tmpdir(), "chant-wave-outcomes-"));
+    try {
+      writeWaveOutcomeFile(dir, 1, {}, { "cluster-a": { status: "failed" }, "cluster-b": { status: "applied" } }, "2026-10-18T10:00:00.000Z");
+      const rerun = join(dir, "rerun");
+      mkdirSync(rerun);
+      writeWaveOutcomeFile(rerun, 1, {}, { "cluster-a": { status: "applied" } }, "2026-10-18T11:00:00.000Z");
+      writeFileSync(
+        join(dir, waveOutcomeFileName(2, { share: 1 })),
+        JSON.stringify({ version: 1, wave: 2, at: "2026-10-18T10:05:00.000Z", roots: { "app-01": { status: "applied" } } }),
+      );
+      writeWaveOutcomeFile(dir, 3, {}, { edge: { status: "failed" } }, "2026-10-18T10:10:00.000Z");
+      writeFileSync(join(dir, "outcome-wave-9.json"), "not json");
+
+      const { members, holdsAll } = earlierWaveOutcomes([dir], 3);
+      expect(holdsAll).toBeUndefined();
+      expect(Object.fromEntries([...members].map(([m, o]) => [m, o.status]))).toEqual({
+        "cluster-a": "applied",
+        "cluster-b": "applied",
+        "app-01": "applied",
+      });
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("a wave that holds all is named", () => {
+    const dir = mkdtempSync(join(tmpdir(), "chant-wave-outcomes-"));
+    try {
+      writeWaveOutcomeFile(dir, 1, { group: "core/x" }, {}, "2026-10-18T10:00:00.000Z", true);
+      expect(waveOutcomeFileName(1, { group: "core/x" })).toBe("outcome-wave-1-group-core_x.json");
+      expect(earlierWaveOutcomes([dir], 2).holdsAll).toBe(1);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});