@intentius/chant 0.124.40 → 0.124.41

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 });
+    }
+  });
+});

package/src/wave-blocked.ts

@@ -0,0 +1,271 @@
+/**
+ * A failed member blocks only the members that depend on it (#4291).
+ *
+ * A run applied a wave at a time stops a member when something it reads did
+ * not apply, and lets every other member go on. This module holds the rule
+ * and the records it reads, with no runner in it, so a product that runs its
+ * waves in its own CI stages (terragucci's roots, lifted from its
+ * `blocked.ts`) and chant's own wave jobs (`pr-apply --wave-gate`,
+ * `chant components fan-out --wave-gate`) block the same members for the
+ * same reasons. It imports `node:fs` and `node:path` and nothing else, so it
+ * bundles small (`wave-blocked-bundle.test.ts`).
+ *
+ * ## Outcomes
+ *
+ * Each member of an earlier wave has an outcome. `applied` and `unchanged`
+ * let a dependent through. Every other status holds it:
+ *
+ * - `failed`: its plan or its apply failed.
+ * - `waiting`: its wave waits for an approval.
+ * - `refused`: its wave was refused, held or stood down.
+ * - `decided`: its wave's deciding job decided it, and a share job applies it.
+ * - `not-applied`: its wave applied nothing because another member of it failed to plan.
+ * - `blocked`: something it reads did not apply. `by` names the member whose
+ *   outcome held it, past any member blocked in between.
+ *
+ * ## Outcome files
+ *
+ * A wave job that hands the next job its outcomes as files writes one per
+ * job, `outcome-wave-<k>[-group-<g>][-share-<i>].json`:
+ *
+ *   {
+ *     "version": 1, "wave": 2, "at": "2026-10-18T10:00:09.000Z",
+ *     "members": {
+ *       "cluster-b": { "status": "applied" },
+ *       "cluster-a": { "status": "failed" },
+ *       "app-01": { "status": "blocked", "by": "cluster-a" }
+ *     }
+ *   }
+ *
+ * A wave job runs again on a re-run, so the newest outcome of a member wins.
+ * A file written with `roots` in place of `members` (terragucci's, before
+ * this module) reads the same. `holds_all` marks a wave that holds every
+ * later member, such as a wave of state migrations that did not apply: each
+ * later member is blocked by `wave-<k>`.
+ */
+import { existsSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+export const WAVE_OUTCOME_VERSION = 1;
+
+export type WaveMemberStatus = "applied" | "unchanged" | "failed" | "waiting" | "refused" | "decided" | "not-applied" | "blocked";
+
+export interface WaveMemberOutcome {
+  status: WaveMemberStatus;
+  /** A blocked member's: the member whose outcome held it, past any member blocked in between. */
+  by?: string;
+}
+
+export interface WaveOutcomeFile {
+  version: typeof WAVE_OUTCOME_VERSION;
+  wave: number;
+  /** When the job wrote it: the newest outcome of a member wins. */
+  at: string;
+  members: Record<string, WaveMemberOutcome>;
+  /** The wave holds every later member, each blocked by `wave-<k>`. */
+  holds_all?: true;
+}
+
+const THROUGH: ReadonlySet<WaveMemberStatus> = new Set(["applied", "unchanged"]);
+
+/** Whether `outcome` lets a dependent through: it applied, or had nothing to apply. */
+export function passesThrough(outcome: WaveMemberOutcome | undefined): boolean {
+  return outcome !== undefined && THROUGH.has(outcome.status);
+}
+
+/**
+ * The members of `members` an upstream that did not apply holds, each with
+ * the member whose outcome holds it. `upstreams` is each member's upstreams;
+ * only those in `earlier` count (a member of this wave or a later one is no
+ * upstream it waits for here). An upstream with no outcome did not apply as
+ * far as this run knows, so it holds its dependents and names itself. A
+ * blocked upstream passes on the member that blocked it. With `holdsAll`,
+ * every member is blocked by `wave-<holdsAll>`.
+ */
+export function blockedMembers(
+  members: readonly string[],
+  upstreams: ReadonlyMap<string, Iterable<string>>,
+  earlier: ReadonlySet<string>,
+  outcomes: ReadonlyMap<string, WaveMemberOutcome>,
+  holdsAll?: number,
+): Map<string, string> {
+  if (holdsAll !== undefined) return new Map(members.map((m) => [m, `wave-${holdsAll}`]));
+  const out = new Map<string, string>();
+  for (const member of members) {
+    const by = [...(upstreams.get(member) ?? [])]
+      .filter((u) => earlier.has(u))
+      .sort()
+      .map((u) => {
+        const o = outcomes.get(u);
+        if (passesThrough(o)) return undefined;
+        return o?.status === "blocked" && o.by ? o.by : u;
+      })
+      .find((b): b is string => b !== undefined);
+    if (by !== undefined) out.set(member, by);
+  }
+  return out;
+}
+
+/**
+ * Walk waves 1 to `before - 1` and give each member that has no outcome the
+ * one it ends with: `blocked` behind an upstream that did not apply. A member
+ * with no outcome that nothing blocks has not run yet: it is in `unsettled`,
+ * and wave `before` cannot run until it has. `outcomes` is what the records
+ * say: `applied` for what applied, and `failed`, `waiting` or `not-applied`
+ * for what did not. Returns those outcomes with the blocked members added.
+ */
+export function settleEarlierWaves(
+  waves: readonly (readonly string[])[],
+  before: number,
+  upstreams: ReadonlyMap<string, Iterable<string>>,
+  outcomes: ReadonlyMap<string, WaveMemberOutcome>,
+): { outcomes: Map<string, WaveMemberOutcome>; unsettled: string[] } {
+  const out = new Map(outcomes);
+  const unsettled: string[] = [];
+  const earlier = new Set<string>();
+  for (let k = 1; k < before && k <= waves.length; k++) {
+    const wave = waves[k - 1]!;
+    const open = wave.filter((m) => !out.has(m));
+    const blocked = blockedMembers(open, upstreams, earlier, out);
+    for (const m of open) {
+      const by = blocked.get(m);
+      if (by !== undefined) out.set(m, { status: "blocked", by });
+      else unsettled.push(m);
+    }
+    for (const m of wave) earlier.add(m);
+  }
+  return { outcomes: out, unsettled };
+}
+
+/**
+ * Whether every member that did not apply waits for an approval, or is
+ * blocked behind one that does: the run waits rather than failed, so the
+ * job ends as waiting (exit 3), and the approval's re-run applies them.
+ */
+export function onlyWaiting(outcomes: ReadonlyMap<string, WaveMemberOutcome>): boolean {
+  let held = false;
+  for (const o of outcomes.values()) {
+    if (THROUGH.has(o.status)) continue;
+    held = true;
+    if (o.status === "waiting") continue;
+    if (o.status === "blocked" && o.by !== undefined && outcomes.get(o.by)?.status === "waiting") continue;
+    return false;
+  }
+  return held;
+}
+
+const byName = ([a]: [string, unknown], [b]: [string, unknown]): number => (a < b ? -1 : a > b ? 1 : 0);
+
+/** The blocked members grouped by what blocked them, as a log and a note list them: `app-01, app-02 (blocked by cluster-a)`. */
+export function blockedWords(blocked: ReadonlyMap<string, string>): string {
+  const byRoot = new Map<string, string[]>();
+  for (const [member, by] of [...blocked].sort(byName)) byRoot.set(by, [...(byRoot.get(by) ?? []), member]);
+  return [...byRoot].map(([by, ms]) => `${ms.join(", ")} (blocked by ${by})`).join("; ");
+}
+
+/**
+ * How the run came out, from every member's newest outcome: "8 applied, 1
+ * failed, 6 blocked", with waiting, refused and the rest named when there
+ * are any, and undefined when every member applied or had nothing to apply.
+ */
+export function runSummary(outcomes: Iterable<WaveMemberOutcome>): string | undefined {
+  const counts = new Map<WaveMemberStatus, number>();
+  for (const o of outcomes) counts.set(o.status, (counts.get(o.status) ?? 0) + 1);
+  if (![...counts.keys()].some((s) => !THROUGH.has(s))) return undefined;
+  const parts = [`${counts.get("applied") ?? 0} applied`, `${counts.get("failed") ?? 0} failed`, `${counts.get("blocked") ?? 0} blocked`];
+  for (const s of ["waiting", "refused", "decided", "not-applied"] as const) {
+    if (counts.get(s)) parts.push(`${counts.get(s)} ${s === "decided" ? "not reported by their share" : s}`);
+  }
+  if (counts.get("unchanged")) parts.push(`${counts.get("unchanged")} unchanged`);
+  return parts.join(", ");
+}
+
+/** The outcome file of a wave's job, or of one group or share of it. */
+export function waveOutcomeFileName(wave: number, part: { group?: string; share?: number } = {}): string {
+  const group = part.group !== undefined ? `-group-${part.group.replace(/[^A-Za-z0-9._-]/g, "_")}` : "";
+  const share = part.share !== undefined ? `-share-${part.share}` : "";
+  return `outcome-wave-${wave}${group}${share}.json`;
+}
+
+/** Write a wave job's outcome file in `dir`, members sorted by name. Returns its path. */
+export function writeWaveOutcomeFile(
+  dir: string,
+  wave: number,
+  part: { group?: string; share?: number },
+  members: Record<string, WaveMemberOutcome>,
+  at = new Date().toISOString(),
+  holdsAll = false,
+): string {
+  const file = join(dir, waveOutcomeFileName(wave, part));
+  const body: WaveOutcomeFile = {
+    version: WAVE_OUTCOME_VERSION,
+    wave,
+    at,
+    members: Object.fromEntries(Object.entries(members).sort(byName)),
+    ...(holdsAll ? { holds_all: true as const } : {}),
+  };
+  writeFileSync(file, JSON.stringify(body, null, 2) + "\n");
+  return file;
+}
+
+/** Every outcome file under `dirs`, four directories deep at most: downloaded artifacts keep each job's in a directory of its own. */
+function outcomeFiles(dirs: readonly string[]): string[] {
+  const out: string[] = [];
+  const walk = (dir: string, depth: number): void => {
+    let names: string[];
+    try {
+      names = readdirSync(dir);
+    } catch {
+      return;
+    }
+    for (const name of names) {
+      const abs = join(dir, name);
+      let isDir = false;
+      try {
+        isDir = statSync(abs).isDirectory();
+      } catch {
+        continue;
+      }
+      if (isDir) {
+        if (depth < 4) walk(abs, depth + 1);
+      } else if (/^outcome-wave-\d+.*\.json$/.test(name)) out.push(abs);
+    }
+  };
+  for (const d of dirs) if (existsSync(d)) walk(d, 0);
+  return out.sort();
+}
+
+/**
+ * The outcome of each member of the waves before `wave`, as their jobs wrote
+ * them under `dirs`, and the earliest such wave that holds every later
+ * member, if any. For a member more than one job wrote (a re-run, or a split
+ * wave's deciding job and the share that applied it), the newest. A file
+ * that does not parse, or is of another version, is skipped.
+ */
+export function earlierWaveOutcomes(
+  dirs: readonly string[],
+  wave: number,
+): { members: Map<string, WaveMemberOutcome & { wave: number; at: string }>; holdsAll?: number } {
+  const out = new Map<string, WaveMemberOutcome & { wave: number; at: string }>();
+  const newest = new Map<number, { at: string; holdsAll: boolean }>();
+  for (const file of outcomeFiles(dirs)) {
+    let f: Partial<WaveOutcomeFile> & { roots?: unknown };
+    try {
+      f = JSON.parse(readFileSync(file, "utf-8"));
+    } catch {
+      continue;
+    }
+    const members = (f?.members ?? f?.roots) as Record<string, WaveMemberOutcome> | undefined;
+    if (f?.version !== WAVE_OUTCOME_VERSION || !Number.isInteger(f.wave) || f.wave! >= wave || typeof f.at !== "string") continue;
+    if (typeof members !== "object" || members === null) continue;
+    for (const [member, o] of Object.entries(members)) {
+      const had = out.get(member);
+      if (had && had.at > f.at) continue;
+      out.set(member, { ...o, wave: f.wave!, at: f.at });
+    }
+    const n = newest.get(f.wave!);
+    if (!n || n.at <= f.at) newest.set(f.wave!, { at: f.at, holdsAll: f.holds_all === true });
+  }
+  const holding = [...newest].filter(([, n]) => n.holdsAll).map(([k]) => k).sort((a, b) => a - b);
+  return { members: out, ...(holding.length ? { holdsAll: holding[0] } : {}) };
+}

package/src/wave-engine.ts

@@ -30,6 +30,8 @@ import { dirname } from "node:path";
 import { mkdirSync, renameSync, writeFileSync } from "node:fs";
 import { evaluateGate, type GateCheck, type GateLedgerPort } from "./op/gate";
 import type { AppliedGateRecord } from "./lifecycle/gate-applied";
+import type { ResolvedGateApproval } from "./op/gate-approval";
+import type { GateQuorumJudge } from "./op/gate-quorum";
 
 export { WAVE_GATE_NAME_PATTERN, waveGateNameFrom, waveShare } from "./wave-layout";
 export {
@@ -66,6 +68,10 @@ export interface WaveGateRequest {
   fields?: Record<string, unknown>;
   /** The pending fact carries `neverOverMcp` (#3821). */
   neverOverMcp?: boolean;
+  /** The approval rules the wave takes (#4290), as an `approval` block with a quorum. */
+  approval?: ResolvedGateApproval;
+  /** Judges approvals for those rules (#4290). */
+  judge?: GateQuorumJudge;
 }
 
 /**
@@ -85,6 +91,8 @@ export function decideWaveGate(port: GateLedgerPort, request: WaveGateRequest):
     ...(request.spent ? { spent: request.spent } : {}),
     ...(request.fields ? { fields: request.fields } : {}),
     ...(request.neverOverMcp ? { neverOverMcp: true } : {}),
+    ...(request.approval ? { approval: request.approval } : {}),
+    ...(request.judge ? { judge: request.judge } : {}),
   });
 }
 

package/src/workspace/__fixtures__/two-member-workspace.ts

@@ -10,7 +10,7 @@ import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 
 /** A git repository holding a workspace with two members, a root member and an example group. */
-export function twoMemberWorkspace(options: { root?: boolean; prefix?: string } = {}): string {
+export function twoMemberWorkspace(options: { root?: boolean; prefix?: string; extra?: Record<string, unknown> } = {}): string {
   const repo = realpathSync(mkdtempSync(join(tmpdir(), "chant-member-pipeline-")));
   execFileSync("git", ["init", "-q"], { cwd: repo });
   const ws = options.prefix ? join(repo, options.prefix) : repo;
@@ -21,7 +21,7 @@ export function twoMemberWorkspace(options: { root?: boolean; prefix?: string }
   ];
   if (options.root) members.unshift({ name: "platform", dir: ".", kind: "chant" });
   const files: Record<string, string> = {
-    "chant.workspace.json": JSON.stringify({ name: "shop", schema: 1, members }, null, 2),
+    "chant.workspace.json": JSON.stringify({ name: "shop", schema: 1, members, ...options.extra }, null, 2),
     "services/api/chant.config.ts": "export default {};\n",
     "services/api/src/infra.ts": "\n",
     "apps/web/chant.config.ts": "export default {};\n",

package/src/workspace/ci-branches.test.ts

@@ -0,0 +1,62 @@
+/** Branch routing and label filters for the pull-request loop (#4292). */
+
+import { describe, expect, test } from "vitest";
+import { appliesFrom, plansUnderLabels, pushedBranchFromEnv, routeConflicts, routedBranch } from "./ci-branches";
+
+const branches = { release: ["prod-*", "dr"], staging: ["staging-*"] };
+
+describe("ci.branches", () => {
+  test("a member routes to the first branch whose globs match it, or to none", () => {
+    expect(routedBranch(branches, "prod-eu")).toBe("release");
+    expect(routedBranch(branches, "dr")).toBe("release");
+    expect(routedBranch(branches, "staging-a")).toBe("staging");
+    expect(routedBranch(branches, "api")).toBeNull();
+    expect(routedBranch(undefined, "api")).toBeNull();
+  });
+
+  test("a routed member applies from its branch alone", () => {
+    expect(appliesFrom(branches, "prod-eu", "release")).toEqual({ applies: true, note: "ci.branches: release applies member prod-eu" });
+    expect(appliesFrom(branches, "prod-eu", "main")).toEqual({ applies: false, note: "ci.branches: member prod-eu applies from release, not main" });
+    expect(appliesFrom(branches, "prod-eu", "staging").applies).toBe(false);
+  });
+
+  test("an unrouted member applies from every branch the map does not name", () => {
+    expect(appliesFrom(branches, "api", "main").applies).toBe(true);
+    expect(appliesFrom(branches, "api", "hotfix").applies).toBe(true);
+    expect(appliesFrom(branches, "api", "release")).toEqual({
+      applies: false,
+      note: "ci.branches: release applies only the members its globs match, and member api is not one",
+    });
+    expect(appliesFrom(undefined, "api", "release").applies).toBe(true);
+  });
+
+  test("a member two branches match is a conflict", () => {
+    expect(routeConflicts({ release: ["prod-*"], hotfix: ["prod-eu"] }, ["prod-eu", "prod-us", "api"])).toEqual([{ member: "prod-eu", branches: ["release", "hotfix"] }]);
+    expect(routeConflicts(branches, ["prod-eu", "dr", "api"])).toEqual([]);
+  });
+
+  test("the pushed branch comes from the forge's variables, never from a tag ref", () => {
+    expect(pushedBranchFromEnv({ GITHUB_REF_NAME: "release", GITHUB_REF_TYPE: "branch" })).toBe("release");
+    expect(pushedBranchFromEnv({ GITHUB_REF_NAME: "v1.2.0", GITHUB_REF_TYPE: "tag" })).toBeUndefined();
+    expect(pushedBranchFromEnv({ CI_COMMIT_BRANCH: "release" })).toBe("release");
+    expect(pushedBranchFromEnv({})).toBeUndefined();
+  });
+});
+
+describe("ci.labels", () => {
+  const labels = { "plan:prod": ["prod-*"], "plan:web": ["web"] };
+
+  test("with none of the labels on the pull request, every member plans", () => {
+    expect(plansUnderLabels(labels, "api", [])).toEqual({ plans: true });
+    expect(plansUnderLabels(labels, "api", ["bug"])).toEqual({ plans: true });
+    expect(plansUnderLabels(undefined, "api", ["plan:prod"])).toEqual({ plans: true });
+  });
+
+  test("with some, only the members their globs match plan", () => {
+    expect(plansUnderLabels(labels, "prod-eu", ["plan:prod"])).toEqual({ plans: true, note: "ci.labels: plan:prod plans member prod-eu" });
+    expect(plansUnderLabels(labels, "web", ["plan:prod", "plan:web"]).plans).toBe(true);
+    const out = plansUnderLabels(labels, "api", ["plan:prod", "bug"]);
+    expect(out.plans).toBe(false);
+    expect(out.note).toContain("its record and apply on merge still plan it");
+  });
+});

package/src/workspace/ci-branches.ts

@@ -0,0 +1,79 @@
+/**
+ * Branch routing and label filters for the pull-request loop (#4292).
+ *
+ * `ci.branches` maps a branch to member-name globs. A member a glob matches
+ * applies from that branch: its generated pull-request pipeline targets it,
+ * and its record or apply job does nothing on a push to any other branch. A
+ * member no glob matches applies from every branch but those, the default
+ * branch included. terragucci's `apply.branches` (`branchLayers`) works the
+ * same way over Terraform roots.
+ *
+ * `ci.labels` maps a pull request label to member-name globs. When a pull
+ * request carries one of the labels, its plan job plans only the members
+ * those labels' globs match, and every other member's plan job plans
+ * nothing. A label never gates: the record and apply jobs on the push never
+ * read labels, and an apply still waits for an approval of the digest it
+ * plans. Anyone with triage access can set a label, so a label may narrow
+ * what a reviewer sees ahead of the merge and no more.
+ */
+
+// @ts-ignore: picomatch has no types declaration
+import picomatch from "picomatch";
+
+/** Branch or label name to member-name globs. */
+export type MemberGlobs = Readonly<Record<string, readonly string[]>>;
+
+const matches = (globs: readonly string[], member: string): boolean => globs.some((g) => (picomatch(g) as (s: string) => boolean)(member));
+
+/** The keys of `map` whose globs match `member`, in declaration order. */
+export function keysMatching(map: MemberGlobs | undefined, member: string): string[] {
+  return Object.keys(map ?? {}).filter((k) => matches(map![k]!, member));
+}
+
+/** The branch `ci.branches` routes `member` to, or null when no glob matches it. */
+export function routedBranch(branches: MemberGlobs | undefined, member: string): string | null {
+  return keysMatching(branches, member)[0] ?? null;
+}
+
+/** Each member that two branches' globs match, with the branches. The declaration refuses these. */
+export function routeConflicts(branches: MemberGlobs | undefined, members: readonly string[]): Array<{ member: string; branches: string[] }> {
+  return members.map((member) => ({ member, branches: keysMatching(branches, member) })).filter((c) => c.branches.length > 1);
+}
+
+/**
+ * Whether a push to `pushed` applies `member`, with a line that says why.
+ * A routed member applies only from its branch. Any other member applies
+ * from every branch `ci.branches` does not name.
+ */
+export function appliesFrom(branches: MemberGlobs | undefined, member: string, pushed: string): { applies: boolean; note: string } {
+  const own = routedBranch(branches, member);
+  if (own !== null) {
+    return own === pushed
+      ? { applies: true, note: `ci.branches: ${pushed} applies member ${member}` }
+      : { applies: false, note: `ci.branches: member ${member} applies from ${own}, not ${pushed}` };
+  }
+  if (Object.prototype.hasOwnProperty.call(branches ?? {}, pushed)) {
+    return { applies: false, note: `ci.branches: ${pushed} applies only the members its globs match, and member ${member} is not one` };
+  }
+  return { applies: true, note: `ci.branches: member ${member} is routed to no branch, so ${pushed} applies it` };
+}
+
+/**
+ * Whether a pull request's plan job plans `member`, given the labels the pull
+ * request carries. With none of `ci.labels` on the pull request every member
+ * plans. With some, a member plans only when one of those labels' globs
+ * matches it.
+ */
+export function plansUnderLabels(labels: MemberGlobs | undefined, member: string, carried: readonly string[]): { plans: boolean; note?: string } {
+  const set = carried.filter((l) => Object.prototype.hasOwnProperty.call(labels ?? {}, l));
+  if (set.length === 0) return { plans: true };
+  const by = set.filter((l) => matches(labels![l]!, member));
+  return by.length > 0
+    ? { plans: true, note: `ci.labels: ${by.join(", ")} plan${by.length === 1 ? "s" : ""} member ${member}` }
+    : { plans: false, note: `ci.labels: the pull request's labels ${set.join(", ")} plan other members, so member ${member} is not planned here; its record and apply on merge still plan it` };
+}
+
+/** The branch the job runs on, from the forge's own variables: GitHub and Forgejo's GITHUB_REF_NAME, GitLab's CI_COMMIT_BRANCH. */
+export function pushedBranchFromEnv(env: Record<string, string | undefined> = process.env): string | undefined {
+  return env.CI_COMMIT_BRANCH || (env.GITHUB_REF_TYPE === undefined || env.GITHUB_REF_TYPE === "branch" ? env.GITHUB_REF_NAME : undefined) || undefined;
+}

package/src/workspace/ci-cloud-identity.test.ts

@@ -0,0 +1,53 @@
+/**
+ * #4296: `chant build --pr-loop` reads `ci.identity.cloud` from the working
+ * tree of the workspace that holds the project, and resolves it for the
+ * pipeline's environment and member.
+ */
+
+import { join } from "node:path";
+import { afterEach, describe, expect, test } from "vitest";
+import { cleanScratch, declaration, git, scratchDir, writeFiles } from "./__fixtures__/contract-repo";
+import { declaredCloudIdentity } from "./ci-cloud-identity";
+
+afterEach(() => cleanScratch());
+
+const MEMBERS = [
+  { name: "net", dir: "net", kind: "other", because: "the network" },
+  { name: "app", dir: "app", kind: "other", because: "the app" },
+];
+
+function workspace(ci?: Record<string, unknown>): string {
+  const root = scratchDir("chant-cloud-identity-");
+  git(root, "init", "-q");
+  writeFiles(root, { "chant.workspace.json": declaration(MEMBERS, ci ? { ci } : {}), "net/a.txt": "a\n", "app/a.txt": "a\n" });
+  return root;
+}
+
+describe("declaredCloudIdentity (#4296)", () => {
+  test("each member's pipeline takes the first rule for its environment and member", async () => {
+    const root = workspace({
+      identity: {
+        cloud: {
+          aws: {
+            rules: [
+              { members: ["net"], plan: "arn:aws:iam::1:role/net-plan", apply: "arn:aws:iam::1:role/net-apply" },
+              { plan: "arn:aws:iam::1:role/plan", apply: "arn:aws:iam::1:role/apply" },
+            ],
+          },
+        },
+      },
+    });
+    expect((await declaredCloudIdentity(join(root, "net"), "production", "net"))!.apply.aws!.role).toBe("arn:aws:iam::1:role/net-apply");
+    expect((await declaredCloudIdentity(join(root, "app"), "production", "app"))!.apply.aws!.role).toBe("arn:aws:iam::1:role/apply");
+  });
+
+  test("a workspace with no block, and a directory outside any workspace, read nothing", async () => {
+    expect(await declaredCloudIdentity(workspace(), "production", "net")).toBeUndefined();
+    expect(await declaredCloudIdentity(scratchDir("chant-cloud-identity-none-"), "production")).toBeUndefined();
+  });
+
+  test("a declaration that plans as an apply identity is an error naming its code", async () => {
+    const root = workspace({ identity: { cloud: { aws: { rules: [{ plan: "r", apply: "r" }] } } } });
+    await expect(declaredCloudIdentity(root, "production")).rejects.toThrow(/plans and applies as r.*\[declaration-invalid\]/);
+  });
+});