@intentius/chant 0.124.40 → 0.124.42

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/checks/ci-workflow.test.ts

@@ -120,6 +120,15 @@ describe("ci.workflow (WSP151)", () => {
     expect(await found(repo(complete({ "chant.workspace.json": decl, ".github/workflows/chant-pr.yml": noRecord })))).toEqual([["ci-workflow-pipeline-missing", null]]);
   });
 
+  test("apply-before-merge needs a job that applies before merge, and the other workflows refuse one (#4301)", async () => {
+    const early = `${PIPELINE}  apply:\n    steps:\n      - run: chant ci run apply --in-place --base "$BASE_SHA" --pr "$PR_NUMBER" --apply-before-merge --env prod --gate pr-apply --forge github\n`;
+    const decl = declaration({ ci: { workflow: "apply-before-merge", green: green() } });
+    expect(await found(repo(complete({ "chant.workspace.json": decl })))).toEqual([["ci-workflow-pipeline-differs", null]]);
+    expect(await found(repo(complete({ "chant.workspace.json": decl, ".github/workflows/chant-pr.yml": early })))).toEqual([]);
+    expect(await found(repo(complete({ ".github/workflows/chant-pr.yml": early })))).toEqual([["ci-workflow-pipeline-differs", null]]);
+    expect(workflowOf({ ci: { green: null, reportUrl: null, workflow: "apply-before-merge" } } as never, null)).toBe("apply-before-merge");
+  });
+
   test("a member's own workflow wins, and a top-level workflow skips members that don't build with chant", async () => {
     const root = repo({
       ...complete(),

package/src/workspace/checks/ci-workflow.ts

@@ -14,7 +14,7 @@
 
 import type { WorkspaceCheck, WorkspaceDiagnostic } from "../checks";
 import type { CiWorkflow, Member } from "../declaration";
-import { appliesOnMerge, STUB_MARKER, workflowOf, type CiWorkflowCode } from "../ci-workflow";
+import { appliesBeforeMerge, appliesOnMerge, STUB_MARKER, workflowOf, type CiWorkflowCode } from "../ci-workflow";
 import { matchesCheckRun } from "../ci-green";
 import { staticPromotionOrder } from "../promotion-order";
 import { joinPath } from "../tree";
@@ -27,6 +27,8 @@ const memberDir = (dir: string) => (dir === "." ? "" : dir);
 const PLAN = /\bci\s+run\s+plan\b|\bcomponents\s+pr-plan\b/;
 const RECORD = /\bci\s+run\s+record\b|\bcomponents\s+pr-record\b/;
 const APPLY = /\bci\s+run\s+apply\b|\bcomponents\s+pr-apply\b/;
+/** An apply before merge (#4301): `pr-apply --before-merge`, or `ci run apply --apply-before-merge`. */
+const BEFORE_MERGE = /--(?:apply-)?before-merge\b/;
 const TICK = /\bci\s+tick\b/;
 const PUBLISH = /\brelease\s+publish\b/;
 
@@ -113,16 +115,28 @@ export const CI_WORKFLOW_CHECKS: readonly WorkspaceCheck[] = [
       if (missing.length > 0) {
         finding("ci-workflow-pipeline-missing", `no pipeline file runs ${missing.join(", ")}; generate them with chant build --components --generate <forge> --pr-loop and chant ci workflow`);
       }
+      // #4301: an apply before merge is its own job, allowed only under apply-before-merge.
+      const beforeMerge = under.some((u) => appliesBeforeMerge(u.workflow)) || appliesBeforeMerge(d.ci?.workflow ?? null);
+      const earlyLines = commandLines(ctx, APPLY).filter((c) => BEFORE_MERGE.test(c.text));
+      if (!beforeMerge) {
+        for (const l of earlyLines) {
+          finding("ci-workflow-pipeline-differs", `${l.path} applies before merge, and no member's workflow is apply-before-merge; regenerate without --apply-before-merge, or set ci.workflow to apply-before-merge`, { treeFile: l.path, line: l.line });
+        }
+      } else if (earlyLines.length === 0 && has(PLAN)) {
+        const l = commandLines(ctx, PLAN)[0]!;
+        finding("ci-workflow-pipeline-differs", `${l.path} has no job that applies before merge, and the workflow is apply-before-merge; regenerate with --apply-before-merge`, { treeFile: l.path, line: l.line });
+      }
+      const mergeApply = (l: { text: string }) => !BEFORE_MERGE.test(l.text);
       if (!applyOnMerge) {
-        for (const l of commandLines(ctx, APPLY)) {
+        for (const l of commandLines(ctx, APPLY).filter(mergeApply)) {
           finding("ci-workflow-pipeline-differs", `${l.path} applies on merge, and the workflow is trunk-curated, where a merge records the plan and deploys nothing; regenerate without --apply-on-merge, or set ci.workflow to trunk-curated+apply-on-merge`, { treeFile: l.path, line: l.line });
         }
-      } else if (!has(APPLY) && has(RECORD)) {
+      } else if (!commandLines(ctx, APPLY).some(mergeApply) && has(RECORD)) {
         const l = commandLines(ctx, RECORD)[0]!;
         finding("ci-workflow-pipeline-differs", `${l.path} records on merge, and the workflow is trunk-curated+apply-on-merge; regenerate with --apply-on-merge`, { treeFile: l.path, line: l.line });
       } else {
         // #4168 step 9: an apply measured from a push's base applies each merge; the workflow applies green commits.
-        for (const l of commandLines(ctx, APPLY).filter((c) => /--base\b/.test(c.text) || (/\bcomponents\s+pr-apply\b/.test(c.text) && !/--green\b/.test(c.text)))) {
+        for (const l of commandLines(ctx, APPLY).filter(mergeApply).filter((c) => /--base\b/.test(c.text) || (/\bcomponents\s+pr-apply\b/.test(c.text) && !/--green\b/.test(c.text)))) {
           finding("ci-workflow-pipeline-differs", `${l.path} applies each merge, and under trunk-curated+apply-on-merge the apply applies the newest green commit; regenerate with --apply-on-merge`, { treeFile: l.path, line: l.line });
         }
       }

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

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

@@ -0,0 +1,23 @@
+/**
+ * The cloud identities a generated pull-request pipeline takes (#4296): the
+ * workspace declaration's `ci.identity.cloud`, resolved for the pipeline's
+ * environment and member (../ci-identity.ts). Read from the working tree of
+ * the workspace that holds `cwd`, as `ci.reportUrl` is (./ci-report-url.ts).
+ * A directory outside a workspace reads nothing.
+ */
+
+import { findWorkspaceRoot } from "../project-root";
+import { resolveCloudIdentity, type PipelineCloudIdentity } from "../ci-identity";
+
+/** The plan and apply identities of the pipeline for `env` and `member`, or undefined. */
+export async function declaredCloudIdentity(cwd: string, env: string, member?: string): Promise<PipelineCloudIdentity | undefined> {
+  const found = findWorkspaceRoot(cwd);
+  if (!found) return undefined;
+  const [{ readDeclaration, WorkspaceReadError }, { workingTree }] = await Promise.all([import("./declaration"), import("./tree")]);
+  try {
+    return resolveCloudIdentity(readDeclaration(workingTree(found.dir)).ci?.identity?.cloud, env, member);
+  } catch (err) {
+    if (!(err instanceof WorkspaceReadError)) throw err;
+    throw Object.assign(new Error(`${err.describe()} [${err.code}]`), { code: err.code });
+  }
+}

package/src/workspace/ci-init.ts

@@ -37,7 +37,7 @@ import { formatError, formatSuccess } from "../cli/format";
 import { parseYAMLDocument } from "../yaml";
 import { CI_WORKFLOW_CHECKS } from "./checks/ci-workflow";
 import type { WorkspaceDiagnostic } from "./checks";
-import { CI_WORKFLOWS, STUB_MARKER, appliesOnMerge } from "./ci-workflow";
+import { CI_WORKFLOWS, STUB_MARKER, appliesBeforeMerge, appliesOnMerge } from "./ci-workflow";
 
 export { STUB_MARKER };
 import { CI_GREEN_WORKFLOW_FILE, jobCheckRuns, readWorkflowSources, workflowsHolding } from "./ci-green-workflow";
@@ -48,7 +48,7 @@ import { SECURITY_GROUPS, type SecurityGroup } from "./security";
 import { gitTop, workingTree, type WorkspaceTree } from "./tree";
 import { RELEASE_WORKFLOW_FORGES, type ReleaseWorkflowForge } from "./release-workflow";
 
-const USAGE = "chant ci init --workflow trunk-curated|trunk-curated+apply-on-merge [--forge github|gitlab|forgejo] [--security <group>]... [--yes]";
+const USAGE = "chant ci init --workflow trunk-curated|trunk-curated+apply-on-merge|apply-before-merge [--forge github|gitlab|forgejo] [--security <group>]... [--yes]";
 
 
 /** The environments a config with none is given. */
@@ -280,11 +280,12 @@ export function proposeCiInit(root: string, options: CiInitOptions): CiInitPropo
     if (reported("ci-workflow-pipeline-missing") || reported("ci-workflow-pipeline-differs")) {
       for (const m of releasing) {
         const env = firstEnv.get(m.name);
+        const workflow = m.ciWorkflow ?? proposed.ci!.workflow!;
         commands.push({
           cwd: memberDir(m.dir) || ".",
           // The root member builds alone: at a workspace root, chant build refuses without --root-only (WSP000).
-          args: ["build", "--components", "--generate", forge, "--pr-loop", ...(m.dir === "." ? ["--root-only"] : []), ...(env ? ["--env", env] : []), ...(appliesOnMerge(m.ciWorkflow ?? proposed.ci!.workflow!) ? ["--apply-on-merge"] : [])],
-          why: `the pull-request pipeline for ${m.name}: plan on a pull request, ${appliesOnMerge(m.ciWorkflow ?? proposed.ci!.workflow!) ? "apply" : "record"} on merge`,
+          args: ["build", "--components", "--generate", forge, "--pr-loop", ...(m.dir === "." ? ["--root-only"] : []), ...(env ? ["--env", env] : []), ...(appliesOnMerge(workflow) ? ["--apply-on-merge"] : []), ...(appliesBeforeMerge(workflow) ? ["--apply-before-merge"] : [])],
+          why: `the pull-request pipeline for ${m.name}: plan on a pull request, ${appliesBeforeMerge(workflow) ? "apply on request before merge, record" : appliesOnMerge(workflow) ? "apply" : "record"} on merge`,
         });
       }
       if (forge === "github") {

package/src/workspace/ci-locks.ts

@@ -0,0 +1,16 @@
+/**
+ * `ci.locks` (#4293): when a pull request takes its target locks
+ * (../lifecycle/target-lock.ts). Read from the declaration at base, the
+ * target branch's tip, as the security groups are (./security.ts), so a
+ * pull request cannot turn its own locks off. Null outside a workspace and
+ * when the declaration sets none.
+ */
+import type { CiLocks } from "./declaration";
+import { scopeSource } from "./write-scope";
+
+export const CI_LOCKS = ["apply", "plan"] as const satisfies readonly CiLocks[];
+
+/** The `ci.locks` of the workspace holding `cwd`, read at `at` when given, else at base, else from the working tree. */
+export function ciLocksAt(cwd: string, at?: string): CiLocks | null {
+  return scopeSource(cwd, at).declaration?.ci?.locks ?? null;
+}