@intentius/chant 0.124.44 → 0.124.46

package/src/op/op-waves.ts

@@ -76,6 +76,7 @@
 
 import type { OpEnvironment, OpSetupStep } from "../lexicon";
 import type { CiRunner } from "../ci-jobs";
+import type { CloudTradeSpec } from "../ci-identity";
 import { gatePointProblems, type GatePoint } from "./gate-point";
 import { quorumProblems, type GateQuorumRule } from "./gate-quorum";
 import { notifyConfigProblem, type NotifyConfig } from "../notify";
@@ -261,6 +262,13 @@ export interface OpWaveJobGroup {
    * is requested.
    */
   idTokens?: Record<string, string>;
+  /**
+   * The cloud identities the group's jobs trade the job's OIDC token for
+   * (#4332), in place of the wave's: a {@link CloudTradeSpec}, as
+   * `cloudIdentityWave` in ../ci-identity.ts gives a group its apply
+   * identities. The trade runs before the checkout.
+   */
+  cloud?: CloudTradeSpec;
 }
 
 /** One wave: runs that apply together, behind one gate. */
@@ -321,6 +329,15 @@ export interface OpWave {
    * job's, and a group's own replace them.
    */
   idTokens?: Record<string, string>;
+  /**
+   * The cloud identities this wave's jobs trade the job's OIDC token for
+   * (#4332), before the checkout: a {@link CloudTradeSpec}. With `jobs`,
+   * the deciding job's, and a group's own `cloud` replaces it.
+   * `cloudIdentityWave` in ../ci-identity.ts gives the deciding job every
+   * plan identity of the wave's targets. Each later step of the job starts
+   * without the variables a token is requested with.
+   */
+  cloud?: CloudTradeSpec;
   /**
    * Split the wave's apply into job groups (#3914): a deciding job, which
    * runs with the wave's own settings, plans every run and decides the gate,
@@ -644,6 +661,7 @@ export function assertOpWavesSpec(spec: OpWavesSpec): void {
     }
     if (wave.runner !== undefined) assertOpWaveRunner(where, `wave "${wave.name}" runner`, wave.runner);
     if (wave.idTokens !== undefined) assertOpWaveIdTokens(where, `wave "${wave.name}" idTokens`, wave.idTokens);
+    if (wave.cloud !== undefined) assertOpWaveCloud(where, `wave "${wave.name}" cloud`, wave.cloud);
     if (wave.jobs !== undefined) assertOpWaveJobGroups(where, wave);
     if (wave.discover !== undefined && typeof wave.discover !== "boolean") throw new Error(`${where}: wave "${wave.name}" has discover ${JSON.stringify(wave.discover)}; use true or false.`);
     if (wave.rest !== undefined && typeof wave.rest !== "boolean") throw new Error(`${where}: wave "${wave.name}" has rest ${JSON.stringify(wave.rest)}; use true or false.`);
@@ -684,6 +702,24 @@ export function assertOpWavesSpec(spec: OpWavesSpec): void {
 
 const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
 
+/** The key each cloud of a `cloud` trade names its identity under (`IDENTITY_KEY` in ../ci-identity.ts, kept here so this module imports none of it). */
+const CLOUD_IDENTITY_KEY: Record<string, string> = { aws: "role", gcp: "serviceAccount", azure: "clientId" };
+
+/** Refuse a `cloud` (#4332) the trade could not run: an unknown cloud, one that names no identity, or no audience. */
+function assertOpWaveCloud(where: string, field: string, cloud: unknown): void {
+  if (cloud === null || typeof cloud !== "object" || Array.isArray(cloud) || Object.keys(cloud).length === 0) throw new Error(`${where}: ${field} must name one or more of aws, gcp and azure.`);
+  for (const [name, c] of Object.entries(cloud as Record<string, unknown>)) {
+    const key = CLOUD_IDENTITY_KEY[name];
+    if (!key) throw new Error(`${where}: ${field}.${name} is not a cloud; use aws, gcp or azure.`);
+    const t = c as Record<string, unknown> | null;
+    const targets = t?.targets;
+    const targetsOk = targets === undefined || (Array.isArray(targets) && targets.every((e) => e && Array.isArray((e as { targets?: unknown }).targets) && typeof (e as Record<string, unknown>)[key] === "string"));
+    if (!t || typeof t.audience !== "string" || !targetsOk || (typeof t[key] !== "string" && !(Array.isArray(targets) && targets.length > 0))) {
+      throw new Error(`${where}: ${field}.${name} must give an audience and a ${key}, or targets each with targets and a ${key}, as cloudIdentityWave gives them.`);
+    }
+  }
+}
+
 /** Refuse a `runner` no forge could read (#3914). */
 function assertOpWaveRunner(where: string, field: string, runner: unknown): void {
   const labels = (value: unknown): boolean => Array.isArray(value) && value.length > 0 && value.every((l) => typeof l === "string" && l.trim() !== "");
@@ -723,7 +759,7 @@ function assertOpWaveJobGroups(where: string, wave: OpWave): void {
     if (group.name === "decide" || /^share-\d+$/.test(group.name)) throw new Error(`${where}: ${field} is named like the wave's own jobs (decide, share-<i>); name it another way.`);
     if (names.has(group.name)) throw new Error(`${where}: ${at} names job group "${group.name}" twice.`);
     names.add(group.name);
-    const known = new Set(["name", "runs", "shares", "runner", "environment", "variables", "setup", "idTokens"]);
+    const known = new Set(["name", "runs", "shares", "runner", "environment", "variables", "setup", "idTokens", "cloud"]);
     const extra = Object.keys(group).find((key) => !known.has(key));
     if (extra !== undefined) throw new Error(`${where}: ${field}.${extra} is not a setting; a job group takes ${[...known].join(", ")}.`);
     if (!Array.isArray(group.runs) || group.runs.length === 0 || !group.runs.every((r) => typeof r === "string" && r.trim() !== "")) {
@@ -733,6 +769,7 @@ function assertOpWaveJobGroups(where: string, wave: OpWave): void {
     if (!Number.isInteger(shares) || shares < 1) throw new Error(`${where}: ${field} has shares ${group.shares}; use a whole number from 1.`);
     if (group.runner !== undefined) assertOpWaveRunner(where, `${field} runner`, group.runner);
     if (group.idTokens !== undefined) assertOpWaveIdTokens(where, `${field} idTokens`, group.idTokens);
+    if (group.cloud !== undefined) assertOpWaveCloud(where, `${field} cloud`, group.cloud);
     if (group.variables !== undefined && (group.variables === null || typeof group.variables !== "object" || Array.isArray(group.variables) || !Object.values(group.variables).every((v) => typeof v === "string"))) {
       throw new Error(`${where}: ${field} variables must be { "<name>": "<value>" }.`);
     }

package/src/pr-forge-bundle.test.ts

@@ -34,7 +34,7 @@ describe("the pr-forge bundle", () => {
       expect(inputs.filter((i) => pattern.test(i)), String(pattern)).toEqual([]);
     }
     expect(inputs.map((i) => i.replace(/^.*?packages\//, "packages/")).sort()).toEqual(["packages/core/src/pr-forge.ts"]);
-    // About 50 KB today, after the pull request authors (#4000), pullRequestOpen for target locks (#4293), the four requires checks of an apply before merge (#4301) and the approver filter (#4337).
+    // About 50 KB today, after the pull request authors (#4000), pullRequestOpen for target locks (#4293), the four requires checks of an apply before merge (#4301) the approver filter (#4337) and the approved fields (#4287).
     expect(result.outputFiles.reduce((n, f) => n + f.contents.byteLength, 0)).toBeLessThan(52 * 1024);
   });
 });

package/src/pr-forge.ts

@@ -420,8 +420,11 @@ export interface PrForge {
    * counts when it came after the merge request's latest push, read from its
    * system notes, and never from the token's own user. `approvers` narrows
    * who counts (#4337), and a refusal names each approver left out and why.
+   * The result also lists who counted and who was left out (#4287), so a
+   * caller never parses `reason`. On GitLab the newest diff version must be
+   * of `head`, or the check is pending.
    */
-  prApproved?(pr: number, head: string, approvers?: PrApproverFilter): Promise<PrRequireResult>;
+  prApproved?(pr: number, head: string, approvers?: PrApproverFilter): Promise<PrApprovalResult>;
   /**
    * The forge says `pr` merges as it stands: no conflicts, and on GitHub no
    * branch protection blocking it. Pending while the forge works it out. On
@@ -481,19 +484,26 @@ async function countApprovers(
   authors: ReadonlySet<string>,
   filter: PrApproverFilter | undefined,
   rule: (login: string) => Promise<string | undefined>,
-): Promise<{ by: string[]; not: string[] }> {
+): Promise<{ by: string[]; not: PrExcludedApprover[] }> {
   const by: string[] = [];
-  const not: string[] = [];
+  const not: PrExcludedApprover[] = [];
   for (const login of approved) {
     const why = authors.has(login) ? `${login} is one of its authors` : (excludedWhy(filter, login) ?? (filter?.forgeRule ? await rule(login) : undefined));
-    if (why) not.push(why);
+    if (why) not.push({ login, reason: why });
     else by.push(login);
   }
   return { by, not };
 }
 
-/** A refusal for no approver counted, naming each one left out. */
-const noApprover = (line: string, not: readonly string[]): PrRequireResult => refuse(not.length > 0 ? `${line}: ${not.join("; ")}` : line);
+/** The approved verdict over who counted: a pass naming them, or a refusal naming each one left out and why. */
+function approvalVerdict(by: string[], not: PrExcludedApprover[], passLine: string, noneLine: string): PrApprovalResult {
+  const fields = { approvers: by, excluded: not };
+  if (by.length > 0) return { ...pass(`${passLine} by ${by.join(", ")}`), ...fields };
+  return { ...refuse(not.length > 0 ? `${noneLine}: ${not.map((n) => n.reason).join("; ")}` : noneLine), ...fields };
+}
+
+/** An approved refusal before anyone was counted. */
+const notCounted = (r: PrRequireResult): PrApprovalResult => ({ ...r, approvers: [], excluded: [] });
 
 /** GitLab's access level for Developer, the least that may push. */
 const GITLAB_DEVELOPER = 30;
@@ -510,6 +520,18 @@ export interface PrRequireResult {
   reason: string;
 }
 
+/**
+ * What {@link PrForge.prApproved} found (#4287). `approvers` and `excluded`
+ * are empty when it refused before counting, such as on a moved head or a
+ * request for changes.
+ */
+export interface PrApprovalResult extends PrRequireResult {
+  /** The logins whose approval of the head counted, sorted. */
+  approvers: string[];
+  /** The logins that approved and did not count, each with the reason the refusal gives. */
+  excluded: PrExcludedApprover[];
+}
+
 const short = (sha: string | undefined): string => (sha ?? "nothing").slice(0, 8);
 const pass = (reason: string): PrRequireResult => ({ passed: true, reason });
 const refuse = (reason: string, pending = false): PrRequireResult => ({ passed: false, ...(pending ? { pending: true } : {}), reason });
@@ -867,7 +889,7 @@ function githubShaped(kind: "github" | "forgejo", opts: GithubForgeOptions): Git
     async prApproved(pr, head, approvers) {
       const got = await api.call("GET", `${repo}/pulls/${pr}`);
       const at = headOf(got);
-      if (at !== head) return moved(`pull request ${pr}`, head, at);
+      if (at !== head) return notCounted(moved(`pull request ${pr}`, head, at));
       // A reviewer's newest deciding review stands, as in approvers; an approval counts only of this head.
       const standing = new Map<string, { state: string; commit?: string; official?: boolean }>();
       for (const r of await api.list(`${repo}/pulls/${pr}/reviews`, pageParams, pageSize)) {
@@ -879,7 +901,7 @@ function githubShaped(kind: "github" | "forgejo", opts: GithubForgeOptions): Git
         standing.set(login, { state, ...(commit ? { commit } : {}), ...(typeof r.official === "boolean" ? { official: r.official } : {}) });
       }
       const changes = [...standing].filter(([, r]) => r.state === "CHANGES_REQUESTED" || r.state === "REQUEST_CHANGES").map(([l]) => l).sort();
-      if (changes.length > 0) return refuse(`${changes.join(", ")} asked for changes`);
+      if (changes.length > 0) return notCounted(refuse(`${changes.join(", ")} asked for changes`));
       const authors = new Set(await authorsOf(pr));
       const approved = [...standing].filter(([, r]) => r.state === "APPROVED" && r.commit === head).map(([l]) => l).sort();
       const rule = async (login: string): Promise<string | undefined> => {
@@ -895,8 +917,7 @@ function githubShaped(kind: "github" | "forgejo", opts: GithubForgeOptions): Git
         return p.some((x) => x !== undefined && GITHUB_WRITERS.has(x)) ? undefined : `${login} has no write access`;
       };
       const { by, not } = await countApprovers(approved, authors, approvers, rule);
-      if (by.length === 0) return noApprover(`no reviewer other than its authors approved its head ${short(head)}`, not);
-      return pass(`approved at ${short(head)} by ${by.join(", ")}`);
+      return approvalVerdict(by, not, `approved at ${short(head)}`, `no reviewer other than its authors approved its head ${short(head)}`);
     },
     async prMergeable(pr, head) {
       const got = await api.call("GET", `${repo}/pulls/${pr}`);
@@ -1262,14 +1283,21 @@ export function gitlabForge(opts: GitlabForgeOptions): PrForge {
     async prApproved(mr, head, approvers) {
       const got = await api.call("GET", `${notes}/${mr}`);
       const at = isObject(got) ? str(got.sha) : undefined;
-      if (at !== head) return moved(`merge request !${mr}`, head, at);
+      if (at !== head) return notCounted(moved(`merge request !${mr}`, head, at));
       // The token's own user approves for the pipeline, never as a reviewer.
       const me = await api.call("GET", "/user");
       const self = isObject(me) ? str(me.username) : undefined;
-      if (!self) return refuse("GitLab did not say which user the job's token acts as, so no approval counts");
-      // An approval counts once it came after the latest push: the newest version of the diff.
+      if (!self) return notCounted(refuse("GitLab did not say which user the job's token acts as, so no approval counts"));
+      // An approval counts once it came after the latest push: the newest version of the diff, which must be of head.
       const versions = await api.call("GET", `${notes}/${mr}/versions`);
-      const since = Math.max(-Infinity, ...(Array.isArray(versions) ? versions : []).map((v) => Date.parse((isObject(v) ? str(v.created_at) : undefined) ?? "")).filter(Number.isFinite));
+      let since = -Infinity;
+      let latest: string | undefined;
+      for (const v of Array.isArray(versions) ? versions : []) {
+        const when = Date.parse((isObject(v) ? str(v.created_at) : undefined) ?? "");
+        if (Number.isFinite(when) && when > since) [since, latest] = [when, isObject(v) ? str(v.head_commit_sha) : undefined];
+      }
+      // GitLab records a push's version after it moves the head, so an older one is asked again.
+      if (latest !== head) return notCounted(refuse(`merge request !${mr}'s newest diff version is of ${short(latest)}, not ${short(head)}`, true));
       const said = new Map<string, { what: string; at: number; id?: number }>();
       for (const n of await api.list(`${notes}/${mr}/notes?sort=asc&order_by=created_at`, pageParams, 100)) {
         if (!isObject(n) || n.system !== true) continue;
@@ -1283,7 +1311,7 @@ export function gitlabForge(opts: GitlabForgeOptions): PrForge {
         if (!before || when >= before.at) said.set(who, { what, at: when, ...(id !== undefined ? { id } : {}) });
       }
       const changes = [...said].filter(([, v]) => v.what === "changes").map(([w]) => w).sort();
-      if (changes.length > 0) return refuse(`${changes.join(", ")} requested changes`);
+      if (changes.length > 0) return notCounted(refuse(`${changes.join(", ")} requested changes`));
       const authors = new Set(await authorsOf(mr));
       const approved = [...said].filter(([, v]) => v.what === "approved" && v.at > since).map(([w]) => w).sort();
       const least = approvers?.minAccessLevel ?? GITLAB_DEVELOPER;
@@ -1301,8 +1329,7 @@ export function gitlabForge(opts: GitlabForgeOptions): PrForge {
         return level >= least ? undefined : `${login} has access level ${level}, under ${least}`;
       };
       const { by, not } = await countApprovers(approved, authors, approvers, rule);
-      if (by.length === 0) return noApprover(`no member other than its authors approved it after its latest push, ${short(head)}`, not);
-      return pass(`approved after ${short(head)} by ${by.join(", ")}`);
+      return approvalVerdict(by, not, `approved after ${short(head)}`, `no member other than its authors approved it after its latest push, ${short(head)}`);
     },
     async prMergeable(mr, head) {
       const got = await api.call("GET", `${notes}/${mr}`);

package/src/pr-requires.test.ts

@@ -32,14 +32,14 @@ describe("github", () => {
 
   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" });
+    expect(await f.prApproved!(7, HEAD)).toEqual({ passed: true, reason: "approved at aaaaaaaa by bob", approvers: ["bob"], excluded: [] });
   });
 
   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" });
+    expect(await changes.prApproved!(7, HEAD)).toEqual({ passed: false, reason: "carol asked for changes", approvers: [], excluded: [] });
   });
 
   test("approved: forgeRule counts only writers, exclude leaves a login out, and the refusal says why (#4337)", async () => {
@@ -53,10 +53,24 @@ describe("github", () => {
       [`GET ${repo}/collaborators/bob/permission`]: { permission: "read", role_name: "triage" },
       [`GET ${repo}/collaborators/Carol/permission`]: { permission: "write", role_name: "maintain" },
     });
-    expect(await f.prApproved!(7, HEAD, { forgeRule: true })).toEqual({ passed: true, reason: "approved at aaaaaaaa by Carol" });
+    expect(await f.prApproved!(7, HEAD, { forgeRule: true })).toEqual({
+      passed: true,
+      reason: "approved at aaaaaaaa by Carol",
+      approvers: ["Carol"],
+      excluded: [
+        { login: "alice", reason: "alice is one of its authors" },
+        { login: "bob", reason: "bob has no write access" },
+      ],
+    });
     expect(await f.prApproved!(7, HEAD, { forgeRule: true, exclude: [{ login: "carol", reason: "carol asked for aaaaaaa" }] })).toEqual({
       passed: false,
       reason: "no reviewer other than its authors approved its head aaaaaaaa: carol asked for aaaaaaa; alice is one of its authors; bob has no write access",
+      approvers: [],
+      excluded: [
+        { login: "Carol", reason: "carol asked for aaaaaaa" },
+        { login: "alice", reason: "alice is one of its authors" },
+        { login: "bob", reason: "bob has no write access" },
+      ],
     });
     expect((await f.prApproved!(7, HEAD, { exclude: ["bob"] })).reason).toBe("approved at aaaaaaaa by Carol");
   });
@@ -112,7 +126,14 @@ describe("forgejo", () => {
     const f = forge({ [`GET ${repo}/pulls/4/reviews`]: [{ user: { login: "bob" }, state: "APPROVED", commit_id: HEAD, official: false }, { user: { login: "erin" }, state: "APPROVED", commit_id: HEAD, official: true }] });
     expect((await f.prApproved!(4, HEAD, { forgeRule: true })).reason).toBe("approved at aaaaaaaa by erin");
     const out = await checkPrRequires(f, 4, HEAD, { only: ["approved"], approvers: { forgeRule: true, exclude: ["erin"] } });
-    expect(out[0]!.reason).toBe("no reviewer other than its authors approved its head aaaaaaaa: bob's review is not official; erin is excluded");
+    expect(out[0]).toMatchObject({
+      reason: "no reviewer other than its authors approved its head aaaaaaaa: bob's review is not official; erin is excluded",
+      approvers: [],
+      excluded: [
+        { login: "bob", reason: "bob's review is not official" },
+        { login: "erin", reason: "erin is excluded" },
+      ],
+    });
   });
 
   test("undiverged: the pull request's merge base is the base branch's tip", async () => {
@@ -150,7 +171,7 @@ describe("gitlab", () => {
         [`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" }],
+        [`GET ${project}/merge_requests/3/versions`]: [{ created_at: "2026-10-01T10:00:00Z", head_commit_sha: HEAD }],
         ...routes,
       }),
     });
@@ -165,7 +186,7 @@ describe("gitlab", () => {
     });
     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" });
+    expect(await g.prApproved!(3, HEAD)).toEqual({ passed: true, reason: "approved after aaaaaaaa by bob", approvers: ["bob"], excluded: [] });
     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");
   });
@@ -185,6 +206,22 @@ describe("gitlab", () => {
     expect((await f.prApproved!(3, HEAD, { forgeRule: true, minAccessLevel: 50 })).reason).toBe(
       "no member other than its authors approved it after its latest push, aaaaaaaa: bob has access level 20, under 50; dan has access level 40, under 50; eve is not a member",
     );
+    expect((await f.prApproved!(3, HEAD, { forgeRule: true })).excluded).toEqual([
+      { login: "bob", reason: "bob has access level 20, under 30" },
+      { login: "eve", reason: "eve is not a member" },
+    ]);
+  });
+
+  test("approved: pending until GitLab's newest diff version is of the head, as terragucci checked (#4287)", async () => {
+    const approval = note("bob", "approved this merge request", "2026-10-01T11:00:00Z");
+    const versions = [
+      { created_at: "2026-10-01T10:00:00Z", head_commit_sha: HEAD },
+      { created_at: "2026-10-01T12:00:00Z", head_commit_sha: OTHER },
+    ];
+    const f = forge({ [`GET ${project}/merge_requests/3/notes`]: [approval], [`GET ${project}/merge_requests/3/versions`]: versions });
+    expect(await f.prApproved!(3, HEAD)).toEqual({ passed: false, pending: true, reason: "merge request !3's newest diff version is of cccccccc, not aaaaaaaa", approvers: [], excluded: [] });
+    const none = forge({ [`GET ${project}/merge_requests/3/notes`]: [approval], [`GET ${project}/merge_requests/3/versions`]: [] });
+    expect(await none.prApproved!(3, HEAD)).toMatchObject({ passed: false, pending: true });
   });
 
   test("mergeable and undiverged read the merge request", async () => {

package/src/pr-requires.ts

@@ -13,7 +13,7 @@
  * Like ./pr-forge.ts this imports nothing beyond it, so a product bundles it
  * without the TypeScript toolchain.
  */
-import type { PrApproverFilter, PrForge, PrRequireResult } from "./pr-forge";
+import type { PrApproverFilter, PrExcludedApprover, 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;
@@ -23,6 +23,10 @@ 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;
+  /** `approved` only (#4287): the logins that counted, as {@link PrApprovalResult} gives them. */
+  approvers?: string[];
+  /** `approved` only (#4287): the logins left out, each with why. */
+  excluded?: PrExcludedApprover[];
 }
 
 export interface PrRequiresOptions {

package/src/workspace/capabilities-contract.test.ts

@@ -0,0 +1,88 @@
+/**
+ * The `capabilities` document of the read contract (#4375): its schema, the
+ * document `chant search --capabilities --json` prints, and its failure.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, test } from "vitest";
+import { contract, validSchema } from "./__fixtures__/contract-repo";
+import { READ_CONTRACT_FLOOR, READ_CONTRACT_VERSION, REASONS } from "./reason-codes";
+import { CAPABILITIES_OUTPUT_SCHEMA_ID, CAPABILITY_SUPPORT_CODES, capabilitiesDocument, capabilitiesFailure, formatCapabilities } from "./capabilities-contract";
+import { READ_CONTRACT_COMMANDS, READ_CONTRACT_SCHEMAS, MCP_READ_TOOLS, mcpToolCall } from "./conformance";
+import schema from "./capabilities.schema.json";
+
+const { expectValid } = contract(schema);
+
+/** The lexicons' mappings as they ship them, read as data: loading a lexicon's plugin takes seconds. */
+const LEXICONS = join(import.meta.dirname, "..", "..", "..", "..", "lexicons");
+const load = async (name: string) => {
+  if (name !== "aws" && name !== "terraform") throw new Error(`no lexicon ${name}`);
+  return { capabilityPack: { mapping: JSON.parse(readFileSync(join(LEXICONS, name, "src", "capabilities", "mapping.json"), "utf-8")) } };
+};
+
+describe("capabilities.schema.json", () => {
+  test("is a valid draft 2020-12 document at the contract version, naming the floor", () => {
+    expect(validSchema(schema)).toBe(true);
+    expect(schema.$id).toBe(CAPABILITIES_OUTPUT_SCHEMA_ID);
+    expect(schema.$id).toBe(`https://intentius.io/chant/schemas/workspace/capabilities/v${READ_CONTRACT_VERSION}/capabilities.schema.json`);
+    for (const branch of ["result", "failure"] as const) {
+      const props = (schema.$defs as Record<string, { properties: Record<string, unknown> }>)[branch].properties;
+      expect(props.contract).toEqual({ const: READ_CONTRACT_VERSION });
+      expect(props.$schema).toEqual({ const: schema.$id });
+    }
+    expect(schema.description).toContain(`chant ${READ_CONTRACT_FLOOR} and newer`);
+  });
+
+  test("names each support code in the closed list", () => {
+    for (const code of CAPABILITY_SUPPORT_CODES) expect(Object.keys(REASONS)).toContain(code);
+  });
+
+  test("is in the conformance suite as workspace search --capabilities, served by the capabilities MCP tool", () => {
+    expect(READ_CONTRACT_COMMANDS).toContain("search --capabilities");
+    expect(READ_CONTRACT_SCHEMAS["search --capabilities"]).toBe("capabilities.schema.json");
+    expect(MCP_READ_TOOLS["search --capabilities"]).toBe("capabilities");
+    expect(mcpToolCall(["workspace", "search", "--capabilities", "--json"])).toEqual({ name: "capabilities", arguments: {} });
+    expect(mcpToolCall(["workspace", "search", "app", "--capabilities", "--json"])).toBeUndefined();
+  });
+});
+
+describe("the document", () => {
+  test("lists the fifteen capabilities with a support statement for each lexicon asked about", async () => {
+    const doc = await capabilitiesDocument(["aws", "terraform", "no-such-lexicon"], load);
+    expectValid(doc);
+    expect(doc.contract).toBe(1);
+    expect(doc.capabilities).toHaveLength(16);
+    const reaches = doc.capabilities.find((c) => c.name === "reaches")!;
+    expect(reaches).toMatchObject({
+      shape: "edge",
+      search: "->[cap=reaches]",
+      depth: "declared",
+      params: [{ name: "action", optional: true }],
+      uses: ["can-assume", "grants"],
+      lexicons: {
+        aws: "supported",
+        terraform: "supported",
+        "no-such-lexicon": { code: "lexicon-not-loaded" },
+      },
+    });
+    expect(reaches.rule).toBe("reaches(r, x; action?) := r:Role ->{0,}can-assume ->grants($action) x");
+    expect(reaches.notEvaluated).toContain('Resource "*"');
+    expect(doc.helpers.map((h) => h.name)).toEqual(["in-sg", "ingress-of", "world-open", "allows", "denies", "pivot"]);
+    for (const c of doc.capabilities) {
+      expect(c.answers.length, c.name).toBeGreaterThan(0);
+      expect(c.search, c.name).toBe(c.shape === "set" ? `cap:${c.name}` : `->[cap=${c.name}]`);
+    }
+  });
+
+  test("prints as text, a line per capability with its parameters", async () => {
+    const lines = formatCapabilities(await capabilitiesDocument([], load));
+    expect(lines[0]).toMatch(/^cap:internet-facing +set +its subnet routes 0\.0\.0\.0\/0 to an internet gateway$/);
+    expect(lines).toContainEqual(expect.stringMatching(/^ +port\?: a port the open rule must cover, such as 22$/));
+    expect(lines.at(-1)).toBe("— 16 capabilities · --json prints each rule");
+  });
+
+  test("a refusal is a failure document with a code", async () => {
+    const doc = await capabilitiesFailure({ code: "usage-invalid", message: "m" });
+    expectValid(doc);
+  });
+});

package/src/workspace/capabilities-contract.ts

@@ -0,0 +1,132 @@
+/**
+ * The `capabilities` document of the read contract (#4375, ws-017): the
+ * capability catalog `chant search` answers `cap:` terms with, described by
+ * `capabilities.schema.json` beside this file.
+ *
+ * `chant search --capabilities --json` prints it for one project, with a
+ * support statement for each lexicon the project loads. `chant workspace
+ * search --capabilities --json` prints it from the workspace root's chant,
+ * for every lexicon a member loads (a terraform member's reader lexicon
+ * included, #4380): capability rules run once, under
+ * the workspace's chant, so the catalog is that chant's. chant's MCP
+ * `capabilities` tool returns whichever of the two applies where the server
+ * runs, unchanged.
+ */
+
+import { resolve } from "node:path";
+import type { ReasonCode } from "./reason-codes";
+import type { CapabilityEntry } from "../capabilities/catalog";
+
+/** The version of the `capabilities` document this chant writes. */
+export const CAPABILITIES_CONTRACT_VERSION = 1;
+
+/** `$id` of the JSON Schema for the document, shipped beside this file. */
+export const CAPABILITIES_OUTPUT_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace/capabilities/v1/capabilities.schema.json";
+
+/** Why no catalog was printed. */
+export const CAPABILITIES_ERROR_CODES = ["usage-invalid"] as const satisfies readonly ReasonCode[];
+export type CapabilitiesErrorCode = (typeof CAPABILITIES_ERROR_CODES)[number];
+
+/** Why a lexicon can't supply a capability. */
+export const CAPABILITY_SUPPORT_CODES = ["lexicon-has-no-mapping", "capability-not-derivable", "lexicon-not-loaded"] as const satisfies readonly ReasonCode[];
+
+interface CapabilitiesHead {
+  $schema: typeof CAPABILITIES_OUTPUT_SCHEMA_ID;
+  contract: typeof CAPABILITIES_CONTRACT_VERSION;
+  /** The chant that wrote the document. */
+  chant: string;
+}
+
+export interface CapabilitiesResult extends CapabilitiesHead {
+  capabilities: CapabilityEntry[];
+  helpers: { name: string; rule: string }[];
+}
+
+export interface CapabilitiesFailure extends CapabilitiesHead {
+  error: { code: CapabilitiesErrorCode; message: string; hint?: string };
+}
+
+export type CapabilitiesDocument = CapabilitiesResult | CapabilitiesFailure;
+
+async function head(): Promise<CapabilitiesHead> {
+  const { readChantPackageVersion } = await import("../package-version");
+  return { $schema: CAPABILITIES_OUTPUT_SCHEMA_ID, contract: CAPABILITIES_CONTRACT_VERSION, chant: readChantPackageVersion() };
+}
+
+/**
+ * The catalog, with a support statement for each lexicon named. Each is
+ * loaded on its own, so one that isn't installed is said to be, and the rest
+ * still read.
+ */
+export async function capabilitiesDocument(
+  lexicons: string[],
+  load?: (name: string) => Promise<{ capabilityPack?: { mapping: unknown } }>,
+): Promise<CapabilitiesResult> {
+  const loadPlugin = load ?? (await import("../cli/plugins")).loadPlugin;
+  const { capabilityCatalog } = await import("../capabilities/catalog");
+  const mappings: Record<string, Parameters<typeof capabilityCatalog>[0][string]> = {};
+  const notLoaded: string[] = [];
+  for (const name of [...new Set(lexicons)].sort()) {
+    try {
+      mappings[name] = (await loadPlugin(name)).capabilityPack?.mapping as (typeof mappings)[string];
+    } catch {
+      notLoaded.push(name);
+      mappings[name] = undefined;
+    }
+  }
+  const catalog = capabilityCatalog(mappings);
+  for (const c of catalog.capabilities) {
+    for (const name of notLoaded) {
+      c.lexicons[name] = { code: "lexicon-not-loaded", message: `the ${name} lexicon isn't installed where this chant runs, so its mapping wasn't read` };
+    }
+  }
+  return { ...(await head()), ...catalog };
+}
+
+export async function capabilitiesFailure(error: CapabilitiesFailure["error"]): Promise<CapabilitiesFailure> {
+  return { ...(await head()), error };
+}
+
+/**
+ * The lexicons the members of the workspace at `cwd` load, for its catalog:
+ * each chant member's own, and for a member of a package's kind, such as
+ * `terraform`, the lexicon its reader project declares (#4380).
+ */
+export async function workspaceLexicons(cwd: string): Promise<string[]> {
+  const { listWorkspace } = await import("./ls");
+  const { findWorkspaceRoot } = await import("../project-root");
+  const { resolveProjectLexicons } = await import("../cli/plugins");
+  const { loadKindRegistry } = await import("./kinds");
+  const located = findWorkspaceRoot(cwd);
+  const doc = listWorkspace({ cwd });
+  if (!located || "error" in doc) return [];
+  const out = new Set<string>();
+  const kinds = doc.members.some((m) => m.kind !== "chant" && m.readable) ? loadKindRegistry(doc.workspace.pins, located.dir).registry : undefined;
+  for (const m of doc.members) {
+    if (!m.readable) continue;
+    const reader = m.kind === "chant" ? undefined : kinds?.get(m.kind)?.graph?.lexicon;
+    if (reader) out.add(reader);
+    if (m.kind !== "chant") continue;
+    try {
+      for (const l of await resolveProjectLexicons(resolve(located.dir, m.dir))) out.add(l);
+    } catch {
+      // A member whose lexicons can't be resolved adds none; its own search says why.
+    }
+  }
+  return [...out];
+}
+
+/** The catalog as text: one capability per line, its search term and meaning, then its parameters. */
+export function formatCapabilities(doc: CapabilitiesResult): string[] {
+  const width = Math.max(...doc.capabilities.map((c) => c.search.length));
+  const lines: string[] = [];
+  for (const c of doc.capabilities) {
+    lines.push(`${c.search.padEnd(width)}  ${c.shape.padEnd(4)}  ${c.meaning}`);
+    for (const p of c.params) lines.push(`${"".padEnd(width)}        ${p.name}${p.optional ? "?" : ""}: ${p.meaning}`);
+    const unsupported = Object.entries(c.lexicons).filter(([, s]) => s !== "supported");
+    for (const [lex, s] of unsupported) lines.push(`${"".padEnd(width)}        not in ${lex}: ${(s as { message: string }).message}`);
+  }
+  const lexicons = Object.keys(doc.capabilities[0]?.lexicons ?? {});
+  lines.push(`— ${doc.capabilities.length} capabilities${lexicons.length ? ` · lexicons ${lexicons.join(", ")}` : ""} · --json prints each rule`);
+  return lines;
+}