@intentius/chant 0.124.40 → 0.124.41

package/src/workspace/declaration.ts

@@ -19,6 +19,8 @@
 import { RETENTION_KINDS, type RetentionOverride } from "../lifecycle/retention-policy";
 import { parseReportUrl } from "../pr-report-url";
 import schema from "./declaration.schema.json" with { type: "json" };
+import { routeConflicts } from "./ci-branches";
+import { cloudIdentityProblems, CLOUDS, type CloudIdentityDeclaration } from "../ci-identity";
 import { expandGlob } from "./glob";
 import { EXAMPLES_KIND, holdsChantProject } from "./kinds";
 import { parseJsonText, pointerToken, type TextLocation } from "./jsonc";
@@ -27,6 +29,8 @@ import type { SecurityGroup } from "./security";
 import { joinPath, type WorkspaceTree } from "./tree";
 import { loadAjv2020 } from "./ajv2020";
 import { readChantPackageVersion } from "../package-version";
+import { assertPrLoopHooks, type OpWaveHooks } from "../op/op-waves";
+import { assertGatePolicySettings, type GatePolicySettings } from "../gate-policy";
 
 export const DECLARATION_SCHEMA_ID = schema.$id;
 export const DECLARATION_FILES = ["chant.workspace.json", "chant.workspace.jsonc"] as const;
@@ -259,11 +263,22 @@ export type CiSource = "checks" | "runs";
  */
 export type CiWorkflow = "trunk-curated" | "trunk-curated+apply-on-merge";
 
+/**
+ * When a pull request takes its target locks (#4293, ../lifecycle/target-lock.ts).
+ * `apply`: its apply takes them, and `chant lock` does by hand. `plan`: its
+ * plan takes them too, through `chant lock --stage plan` in a job that runs
+ * the target branch's code. Under either, an apply refuses a target another
+ * open pull request holds.
+ */
+export type CiLocks = "apply" | "plan";
+
 /** The declaration's `ci` block (#3573). */
 export interface CiDeclaration {
   green: CiGreen | null;
   /** `ci.workflow` (#4168 step 6): the workflow every member follows unless it names its own; absent when the declaration sets none. */
   workflow?: CiWorkflow;
+  /** `ci.locks` (#4293): when a pull request takes its target locks; absent when the declaration sets none, and then nothing is locked. */
+  locks?: CiLocks;
   /**
    * `ci.reportUrl` (#4160): where the pull-request jobs copy their reports
    * and `chant ci run` keeps the run index, `<reportUrl>/runs/index.json`.
@@ -272,8 +287,56 @@ export interface CiDeclaration {
    * the declaration sets none.
    */
   reportUrl: string | null;
+  /**
+   * `ci.hooks` (#4288): the stage hooks the pull-request jobs run, in the
+   * shape an Op waves spec's `hooks` takes. `chant components pr-plan`,
+   * `pr-record` and `pr-apply` read them from the declaration at base.
+   * Absent when the declaration sets none.
+   */
+  hooks?: OpWaveHooks;
+  /**
+   * `ci.branches` (#4292): branch name to member-name globs. A member a glob
+   * matches applies from that branch alone; the others apply from every
+   * branch the map does not name (./ci-branches.ts). Absent when unset.
+   */
+  branches?: Record<string, string[]>;
+  /**
+   * `ci.labels` (#4292): pull request label to member-name globs. A labelled
+   * pull request plans only the members its labels match. Never a gate.
+   * Absent when unset.
+   */
+  labels?: Record<string, string[]>;
+  /**
+   * `ci.policy` (#4294): the policy engine the pull-request jobs run over
+   * the change set, read with the policy from the declaration at base.
+   * Absent when the declaration sets none.
+   */
+  policy?: GatePolicySettings;
+  /**
+   * `ci.identity` (#4296): `cloud` gives each cloud's plan and apply
+   * identities by environment and member globs (../ci-identity.ts).
+   * Absent when unset.
+   */
+  identity?: { cloud: CloudIdentityDeclaration };
+  /**
+   * `ci.prEnvironment` (#4298): an environment per open pull request,
+   * derived from `template`, torn down on close or after `ttl`
+   * (../components/pr-environment.ts). Absent when unset.
+   */
+  prEnvironment?: CiPrEnvironment;
 }
 
+/** The `ci.prEnvironment` block (#4298), with its default TTL. */
+export interface CiPrEnvironment {
+  /** The declared environment `pr-<n>` takes its endpoint from. */
+  template: string;
+  /** How long the environment lives after its last apply: `72h` when absent. */
+  ttl: string;
+}
+
+/** The default `ci.prEnvironment.ttl`. */
+export const DEFAULT_PR_ENVIRONMENT_TTL = "72h";
+
 export interface MemberRole {
   name: string;
   /** Relative to the member's directory, or null for the whole member. */
@@ -592,6 +655,8 @@ export interface Member {
   security: SecurityGroup[];
   /** The member's own `ci.workflow` (#4168 step 6), which wins over the top level's; null when it names none. */
   ciWorkflow: CiWorkflow | null;
+  /** The member's own `ci.hooks` (#4288), run after the top level's; null when it names none. */
+  ciHooks: OpWaveHooks | null;
   suppress: Suppression[];
   /** The entry's JSON Pointer in the file, for messages. */
   pointer: string;
@@ -889,6 +954,7 @@ export function parseDeclaration(text: string, file: string, reader: string = re
       travel: e.travel === true,
       security: [...((e.security as SecurityGroup[] | undefined) ?? [])],
       ciWorkflow: ((e.ci as { workflow?: CiWorkflow } | undefined)?.workflow) ?? null,
+      ciHooks: ciHooksOf((e.ci as { hooks?: unknown } | undefined)?.hooks, `${pointer}/ci/hooks`, at),
       suppress,
       pointer,
     };
@@ -1013,6 +1079,15 @@ export function parseDeclaration(text: string, file: string, reader: string = re
   const tierSession = factoryTierSessionProblem(members, agents);
   if (tierSession) throw new WorkspaceReadError("declaration-invalid", tierSession.message, at(tierSession.pointer));
   const ci = ciOf(obj.ci, at);
+  // #4292: a member applies from one branch, so two branches may not both route it.
+  const [conflict] = routeConflicts(ci?.branches, members.map((m) => m.name));
+  if (conflict) {
+    throw new WorkspaceReadError(
+      "declaration-invalid",
+      `ci.branches routes member ${conflict.member} to both ${conflict.branches.join(" and ")}; a member applies from one branch`,
+      at(`/ci/branches/${pointerToken(conflict.branches[1]!)}`),
+    );
+  }
 
   const pins = ((obj.pins as Record<string, string>[] | undefined) ?? []).map((p) => ({
     package: p.package ?? null,
@@ -1134,10 +1209,67 @@ function retentionOf(raw: unknown): RetentionOverride | null {
   return out;
 }
 
+/** A `ci.hooks` block (#4288), refused when a pull-request job could not run it. Null when absent. */
+function ciHooksOf(raw: unknown, pointer: string, at: (pointer: string, key?: boolean) => ErrorLocation): OpWaveHooks | null {
+  if (raw === undefined) return null;
+  try {
+    assertPrLoopHooks(pointer.slice(1).replace(/\//g, "."), raw as OpWaveHooks);
+  } catch (err) {
+    throw new WorkspaceReadError("declaration-invalid", err instanceof Error ? err.message : String(err), at(pointer));
+  }
+  return structuredClone(raw as OpWaveHooks);
+}
+
+/** A `ci.branches` or `ci.labels` map, copied without its `x-` keys. */
+function globMap(raw: Record<string, string[]>): Record<string, string[]> {
+  return Object.fromEntries(Object.entries(raw).filter(([k]) => !k.startsWith("x-")).map(([k, v]) => [k, [...v]]));
+}
+
+/** A `ci.policy` block (#4294), refused when the pull-request jobs could not run it. Null when absent. */
+function ciPolicyOf(raw: unknown, at: (pointer: string, key?: boolean) => ErrorLocation): GatePolicySettings | null {
+  if (raw === undefined) return null;
+  try {
+    assertGatePolicySettings("ci.policy", raw);
+  } catch (err) {
+    throw new WorkspaceReadError("declaration-invalid", err instanceof Error ? err.message : String(err), at("/ci/policy"));
+  }
+  return structuredClone(raw);
+}
+
+/**
+ * `ci.identity.cloud` (#4296), copied without its `x-` keys. A rule that
+ * plans as an identity some rule applies as is refused: the plan runs the
+ * pull request's code.
+ */
+function cloudIdentityOf(raw: CloudIdentityDeclaration, at: (pointer: string, key?: boolean) => ErrorLocation): CloudIdentityDeclaration {
+  const out: CloudIdentityDeclaration = {};
+  for (const cloud of CLOUDS) {
+    const c = raw[cloud];
+    if (c === undefined) continue;
+    const kept = Object.fromEntries(Object.entries(c).filter(([k]) => !k.startsWith("x-")));
+    const rules = c.rules.map((r) => Object.fromEntries(Object.entries(r).filter(([k]) => !k.startsWith("x-")).map(([k, v]) => [k, Array.isArray(v) ? [...v] : v])));
+    (out as Record<string, unknown>)[cloud] = { ...kept, rules };
+  }
+  const [problem] = cloudIdentityProblems(out);
+  if (problem) throw new WorkspaceReadError("declaration-invalid", problem.message, at(problem.pointer));
+  return out;
+}
+
 function ciOf(raw: unknown, at: (pointer: string, key?: boolean) => ErrorLocation): CiDeclaration | null {
   if (raw === undefined) return null;
-  const block = raw as { reportUrl?: string; workflow?: CiWorkflow; green?: { branch: string; window?: string; phases: Record<string, string[] | { runs: string[]; skipped?: CiSkipped; build?: CiBuild }>; require: string[]; preMerge?: string[]; signedSince?: string; source?: CiSource } };
-  const workflow = block.workflow !== undefined ? { workflow: block.workflow } : {};
+  const block = raw as { reportUrl?: string; workflow?: CiWorkflow; hooks?: unknown; identity?: { cloud?: CloudIdentityDeclaration }; branches?: Record<string, string[]>; labels?: Record<string, string[]>; locks?: CiLocks; policy?: unknown; prEnvironment?: { template: string; ttl?: string }; green?: { branch: string; window?: string; phases: Record<string, string[] | { runs: string[]; skipped?: CiSkipped; build?: CiBuild }>; require: string[]; preMerge?: string[]; signedSince?: string; source?: CiSource } };
+  const hooks = ciHooksOf(block.hooks, "/ci/hooks", at);
+  const policy = ciPolicyOf(block.policy, at);
+  const workflow = {
+    ...(block.workflow !== undefined ? { workflow: block.workflow } : {}),
+    ...(hooks ? { hooks } : {}),
+    ...(block.branches !== undefined ? { branches: globMap(block.branches) } : {}),
+    ...(block.labels !== undefined ? { labels: globMap(block.labels) } : {}),
+    ...(block.locks !== undefined ? { locks: block.locks } : {}),
+    ...(policy ? { policy } : {}),
+    ...(block.identity?.cloud !== undefined ? { identity: { cloud: cloudIdentityOf(block.identity.cloud, at) } } : {}),
+    ...(block.prEnvironment !== undefined ? { prEnvironment: { template: block.prEnvironment.template, ttl: block.prEnvironment.ttl ?? DEFAULT_PR_ENVIRONMENT_TTL } } : {}),
+  };
   let reportUrl: string | null = null;
   if (block.reportUrl !== undefined) {
     // #4160: refused here as pr-plan and ci run refuse the flag, so a reader never gets a URL no job can write to.

package/src/workspace/identity-gate-rule.ts

@@ -14,7 +14,7 @@
  * else: no zod, no ajv, no package loading, so it bundles small.
  */
 
-import { GATE_SEAL_NAMESPACE, gateSealPayload, namespaceAllowed, sshKeyFingerprint, sshSignatureKey, verifySshSignatureWith, type SealedGateApproval } from "./trust/gate-seal";
+import { GATE_SEAL_NAMESPACE, gateSealPayload, namespaceAllowed, sshKeyFingerprint, sshSignatureKey, verifySshSignatureWith, type SealedGateApproval } from "../lifecycle/gate-seal";
 import type { Signer } from "./trust/trust-files";
 
 /** The core classes, in the order a principal's roles are tried; `human` holds no role and is the rest. */

package/src/workspace/identity.ts

@@ -31,7 +31,7 @@ import { classesOf, coreClassRegistry, roleGrants, type ClassRegistry } from "./
 import type { ReasonCode } from "./reason-codes";
 import { normalisePrincipal } from "./records";
 import type { TrustPolicy } from "./trust/policy";
-import type { SealedGateApproval } from "./trust/gate-seal";
+import type { SealedGateApproval } from "../lifecycle/gate-seal";
 import { scopeSource } from "./write-scope";
 
 /** The forges a forge identity can name. */

package/src/workspace/lineage-upgrade.ts

@@ -42,6 +42,7 @@ import { tmpdir } from "node:os";
 import { basename, dirname, join, relative, resolve, sep } from "node:path";
 import { computePlanDigest } from "../lifecycle/plan-digest";
 import type { ResolvedGateApproval } from "../op/gate-approval";
+import { quorumRules, type GateQuorumSpec } from "../op/gate-quorum";
 import { checkLineage, findingKey, type CheckFinding } from "./lineage-check";
 import { dirLabel, git, parseDirSpec, parseTemplateSource, portableUrl, readTemplateDir, readTemplateTree, recordedDirPath } from "./lineage-init";
 import {
@@ -589,11 +590,13 @@ async function rulesAtHead(repo: string, paths: string[]): Promise<ResolvedGateA
       for (const { config, filePath } of ops.values()) {
         const rel = relative(repo, filePath).split(sep).join("/");
         if (!opFiles.has(rel)) continue;
+        // #4290: a quorum may be a list of rules; the strictest count is asked for.
         for (const approval of gateApprovals(config)) {
-          const need = approval.quorum?.count ?? 1;
-          if (need > count) {
-            count = need;
-            roles = approval.quorum?.roles;
+          for (const rule of quorumRules(approval.quorum)) {
+            if (rule.count > count) {
+              count = rule.count;
+              roles = rule.roles;
+            }
           }
         }
       }
@@ -602,10 +605,10 @@ async function rulesAtHead(repo: string, paths: string[]): Promise<ResolvedGateA
   return { mode: "log-only", quorum: { count, ...(roles && roles.length > 0 ? { roles } : {}) } };
 }
 
-type StepLike = { kind: string; approval?: { quorum?: { count: number; roles?: string[] } }; steps?: StepLike[] };
+type StepLike = { kind: string; approval?: { quorum?: GateQuorumSpec }; steps?: StepLike[] };
 
-function gateApprovals(config: { phases?: Array<{ steps: StepLike[] }>; onFailure?: Array<{ steps: StepLike[] }> }): Array<{ quorum?: { count: number; roles?: string[] } }> {
-  const out: Array<{ quorum?: { count: number; roles?: string[] } }> = [];
+function gateApprovals(config: { phases?: Array<{ steps: StepLike[] }>; onFailure?: Array<{ steps: StepLike[] }> }): Array<{ quorum?: GateQuorumSpec }> {
+  const out: Array<{ quorum?: GateQuorumSpec }> = [];
   const visit = (step: StepLike): void => {
     if (step.kind === "gate") out.push(step.approval ?? {});
     if (step.kind === "effect") (step.steps ?? []).forEach(visit);
@@ -1042,7 +1045,7 @@ export function describeStaged(staged: StagedUpgrade): string[] {
   }
   for (const s of staged.manualSteps) lines.push(`  manual step: ${at(s.path)} (${s.reason})`);
   if (staged.governance) {
-    const q = staged.governance.approval.quorum!;
+    const q = quorumRules(staged.governance.approval.quorum)[0]!;
     lines.push(
       `  governance: ${staged.governance.paths.join(", ")}; needs ${q.count} human approval(s)${q.roles ? ` with a role in ${q.roles.join(", ")}` : ""}, from the rules at ${staged.governance.rules.slice(0, 12)}`,
     );

package/src/workspace/member-pipeline.test.ts

@@ -178,3 +178,32 @@ describe("the generated-file record", () => {
     expect(readGeneratedRecord(dir).files.map((f) => f.path)).toEqual(["a.yml", "b.yml"]);
   });
 });
+
+describe("ci.branches routes a member's pull-request pipeline (#4292)", () => {
+  const routed = () => {
+    rmSync(repo, { recursive: true, force: true });
+    repo = twoMemberWorkspace({ extra: { ci: { branches: { release: ["api"] } } } });
+  };
+  const plan = (dir: string, branch?: string) =>
+    planMemberComponentPipeline({ projectDir: dir, found: findWorkspaceRoot(dir)!, lexicon: "github", env: "staging", prLoop: branch ? { branch } : {} })!;
+
+  test("a routed member's pipeline targets its branch, with or without --branch naming it", () => {
+    routed();
+    const dir = join(repo, "services/api");
+    expect(plan(dir).branch).toBe("release");
+    expect(plan(dir, "release").branch).toBe("release");
+    expect(plan(dir).command).toBe("chant build --components --generate github --env staging --pr-loop");
+  });
+
+  test("--branch may not move a routed member, nor put another member on a routed branch", () => {
+    routed();
+    expect(() => plan(join(repo, "services/api"), "main")).toThrow("--branch main: ci.branches routes member api to release, so its pull-request pipeline targets release");
+    expect(() => plan(join(repo, "apps/web"), "release")).toThrow("--branch release: ci.branches applies only the members its globs match from release, and member web is not one");
+  });
+
+  test("an unrouted member keeps --branch, or the generator's default", () => {
+    routed();
+    expect(plan(join(repo, "apps/web")).branch).toBeUndefined();
+    expect(plan(join(repo, "apps/web"), "trunk").branch).toBe("trunk");
+  });
+});

package/src/workspace/member-pipeline.ts

@@ -26,6 +26,7 @@ import { GENERATED_MARKER } from "../discovery/files";
 import type { PipelineMember } from "../lexicon";
 import type { WorkspaceRootSearch } from "../project-root";
 import { ownerOf, readDeclaration, resolveGroups, rootExclusions, WorkspaceReadError, type Declaration, type Member } from "./declaration";
+import { routedBranch } from "./ci-branches";
 import { gitTop, workingTree } from "./tree";
 
 /**
@@ -196,6 +197,12 @@ export interface MemberComponentPlan {
   /** The command that regenerates it, run in the member's directory. */
   command: string;
   env: string;
+  /**
+   * With `--pr-loop`, the branch the pipeline targets: `--branch`, else the
+   * branch `ci.branches` routes the member to (#4292). Undefined for the
+   * generator's default.
+   */
+  branch?: string;
 }
 
 export interface ComponentPlanInput {
@@ -234,6 +241,7 @@ export function planMemberComponentPipeline(input: ComponentPlanInput): MemberCo
   const ctx = resolveMemberContext(input.projectDir, input.found);
   if (!ctx) return undefined;
   const env = input.env ?? DEFAULT_ENV;
+  const branch = input.prLoop ? prLoopBranch(ctx, input.prLoop.branch) : undefined;
   let target: string;
   if (input.output) {
     target = resolve(input.output);
@@ -273,9 +281,31 @@ export function planMemberComponentPipeline(input: ComponentPlanInput): MemberCo
     target,
     command: parts.map(shellArg).join(" "),
     env,
+    ...(branch !== undefined ? { branch } : {}),
   };
 }
 
+/**
+ * The branch a member's pull-request pipeline targets (#4292): the one
+ * `ci.branches` routes it to, which `--branch` may repeat but not change.
+ * Without a route, `--branch` as given, which may not name a routed branch
+ * whose globs leave the member out.
+ */
+function prLoopBranch(ctx: MemberContext, flag: string | undefined): string | undefined {
+  const branches = ctx.declaration.ci?.branches;
+  const own = routedBranch(branches, ctx.member.name);
+  if (own !== null) {
+    if (flag !== undefined && flag !== own) {
+      throw new Error(`--branch ${flag}: ci.branches routes member ${ctx.member.name} to ${own}, so its pull-request pipeline targets ${own}`);
+    }
+    return own;
+  }
+  if (flag !== undefined && Object.prototype.hasOwnProperty.call(branches ?? {}, flag)) {
+    throw new Error(`--branch ${flag}: ci.branches applies only the members its globs match from ${flag}, and member ${ctx.member.name} is not one`);
+  }
+  return flag;
+}
+
 /** Write a member's pipeline with its header and record it as the member's generated file. */
 export function writeMemberComponentPipeline(plan: MemberComponentPlan, yaml: string): void {
   mkdirSync(dirname(plan.target), { recursive: true });

package/src/workspace/pr-report.schema.json

@@ -37,8 +37,8 @@
       "description": "planned: every member planned (plan stage). recorded (#4168, chant 0.124.33 and newer): every member planned on the merged commit and the merge record was written (record stage); approval says whether the plan is the approved one, and nothing applied. plan-failed: a member failed to plan, so nothing can apply. nothing: no component deploys what the change touches. applied: every member applied. failed: a member failed to apply and its dependents did not run. wave-applied (#4003, chant 0.124.32 and newer): with --wave-gate and --wave, the wave applied and a later wave is still to run. refused: nothing applied, see refusal. waiting (#3999): the approved plans applied except members held back after an upstream applied, which wait on an approval of the plan the last of rounds made."
     },
     "refusal": {
-      "enum": ["not-approved", "plan-changed", "not-a-reviewer", "author-approved", "no-pull-request", "wave-not-approved", "wave-plan-changed", "earlier-wave"],
-      "description": "Why an apply refused. plan-changed: an approval stands for another digest, so the plan changed after review. author-approved (#4000): under --require-review, an approval names the pull request's author or an author or committer of one of its commits. With --wave-gate (#4003, chant 0.124.32 and newer): wave-not-approved, a wave's new plan is not covered by the approved one and no approval of its gate stands for it; wave-plan-changed, an approval of its gate stands for another digest; earlier-wave, an earlier wave has work left or no record says it applied. The waves that applied before a wave refused stay applied; waves says which."
+      "enum": ["not-approved", "plan-changed", "not-a-reviewer", "author-approved", "no-pull-request", "wave-not-approved", "wave-plan-changed", "earlier-wave", "locked", "policy-denied", "policy-error"],
+      "description": "Why an apply refused. plan-changed: an approval stands for another digest, so the plan changed after review. author-approved (#4000): under --require-review, an approval names the pull request's author or an author or committer of one of its commits. With --wave-gate (#4003, chant 0.124.32 and newer): wave-not-approved, a wave's new plan is not covered by the approved one and no approval of its gate stands for it; wave-plan-changed, an approval of its gate stands for another digest; earlier-wave, an earlier wave has work left or no record says it applied. The waves that applied before a wave refused stay applied; waves says which. locked (#4293, chant 0.124.41 and newer): under ci.locks, another open pull request holds a lock on a target the apply reaches, and nothing applied. With ci.policy (#4294, chant 0.124.41 and newer): policy-denied, the policy at base denied the plan and no override counts; policy-error, the policy could not be run or gave no readable answer."
     },
     "message": { "type": "string", "description": "The refusal or failure as printed." },
     "resumed": {
@@ -77,6 +77,21 @@
         }
       }
     },
+    "overdue": {
+      "type": "array",
+      "description": "Added within contract version 1 by #4289, written by chant 0.124.41 and newer. Plan stage: the scheduled watch and reconcile Ops whose cron has fired at least twice since their job last ran, or since their pipeline file was added when no run is on record. Absent when none is overdue or the forge was not asked.",
+      "items": {
+        "type": "object",
+        "required": ["op", "cron", "since", "message"],
+        "properties": {
+          "op": { "type": "string" },
+          "cron": { "type": "string" },
+          "since": { "type": "string", "description": "The job's last run, or the pipeline file's first commit when neverRan, ISO 8601." },
+          "neverRan": { "type": "boolean" },
+          "message": { "type": "string", "description": "The warning as the plan note prints it." }
+        }
+      }
+    },
     "plannedOutputs": {
       "type": "object",
       "description": "Added within contract version 1 by #3999, written by chant 0.124.32 and newer. Per dependency in the change that a member was planned against, the names of the outputs its plan knows, sorted. An output a member reads that is not listed is known only after apply, and the member lists it under unknownInputs. Absent when no member read one.",
@@ -175,6 +190,62 @@
     "changeSet": {
       "type": "object",
       "description": "The change-set document over every member (change-set.schema.json). Its digest equals digest."
+    },
+    "hooks": {
+      "type": "array",
+      "description": "Added within contract version 1 by #4288, written by chant 0.124.41 and newer. The stage hooks the job ran, in order, from ci.hooks in the workspace declaration at base. Absent when it ran none.",
+      "items": {
+        "type": "object",
+        "required": ["moment", "name", "exit", "outcome"],
+        "additionalProperties": false,
+        "properties": {
+          "moment": { "enum": ["before-observe", "before-plan", "after-plan", "before-apply", "after-apply"] },
+          "name": { "type": "string" },
+          "target": { "type": "string", "description": "The component, for a perRun hook." },
+          "exit": { "type": "integer" },
+          "outcome": { "enum": ["passed", "failed", "held"], "description": "held: an onFailure approve hook failed, which the pull request's gate answers." }
+        }
+      }
+    },
+    "policy": {
+      "type": "object",
+      "description": "Added within contract version 1 by #4294, written by chant 0.124.41 and newer. What ci.policy in the workspace declaration at base said about the change set. Absent when the base sets no policy, or the stage reached no plan to judge.",
+      "required": ["result", "engine", "base", "denials", "holds", "warnings"],
+      "additionalProperties": false,
+      "properties": {
+        "result": { "enum": ["passed", "denied", "held", "error"], "description": "denied wins over held. error: the policy did not run or gave no readable answer, and nothing applies." },
+        "engine": { "enum": ["conftest", "opa"], "description": "The result shape read." },
+        "base": { "type": "string", "description": "The commit the settings and the policy were read at." },
+        "denials": { "type": "array", "items": { "$ref": "#/$defs/policyFinding" } },
+        "rules": { "type": "array", "items": { "type": "string" }, "description": "The ids of the rules that denied, sorted: what an override names." },
+        "holds": { "type": "array", "items": { "$ref": "#/$defs/policyFinding" }, "description": "Rules that hold the plan for a person's approval of its digest." },
+        "warnings": { "type": "array", "items": { "type": "string" } },
+        "error": { "type": "string" },
+        "override": {
+          "type": "object",
+          "required": ["by", "at", "reason", "digest"],
+          "additionalProperties": false,
+          "description": "The override on _gates/policy-override.jsonl that lets the denied plan through.",
+          "properties": {
+            "by": { "type": "string" },
+            "at": { "type": "string" },
+            "reason": { "type": "string" },
+            "digest": { "type": "string", "description": "The override digest: the op, the plan digest and the rules." }
+          }
+        },
+        "overrideCommand": { "type": "string", "description": "While denied: the command that overrides the denial." }
+      }
+    }
+  },
+  "$defs": {
+    "policyFinding": {
+      "type": "object",
+      "required": ["rule", "message"],
+      "additionalProperties": false,
+      "properties": {
+        "rule": { "type": "string", "description": "<package>.<rule>, such as main.deny_public_bucket." },
+        "message": { "type": "string" }
+      }
     }
   }
 }

package/src/workspace/security.ts

@@ -109,6 +109,10 @@ export const SECURITY_FEATURES: readonly SecurityFeature[] = [
   { feature: "Apply jobs require a runner-start statement", byDefault: "off", setting: "`--require-runner-start`", group: "isolated-runners", codes: ["security-runner-start-no-key", "security-runner-start-no-role", "security-trust-unreadable"] },
   { feature: "Secrets file", byDefault: "off", setting: "`--secrets`", group: null, codes: [] },
   { feature: "Env allowlist and log redaction", byDefault: "on: `ci run`'s contract, a listed exception", setting: "`--pass-env`", group: null, codes: [] },
+  // #4295: the plan job's steps never hold a forge token; the plan-note job posts. Part of the generated pipeline, so nothing turns it on.
+  { feature: "Plan steps hold no forge token", byDefault: "on: the plan job's contract, a listed exception", setting: "regenerate the pipeline", group: null, codes: [] },
+  // #4296: the plan job trades its OIDC token for the plan identity before the checkout, and the apply jobs take the apply identity.
+  { feature: "Separate plan and apply cloud identities", byDefault: "off: no job requests an OIDC token", setting: "`ci.identity.cloud`", group: null, codes: [] },
 ];
 
 /** The reference page's table of {@link SECURITY_FEATURES}, as markdown. */

package/src/workspace/status-gates.ts

@@ -24,6 +24,7 @@ import { samePlanDigest } from "../lifecycle/plan-digest";
 import type { GateResolutionRecord, PendingGateRecord } from "../lifecycle/gate-ledger";
 import { isPendingGateExpired, latestPendingGate, latestResolutionForPlan, parseGateLedger } from "../lifecycle/gate-ledger";
 import { humanQuorumSince, tallyGateApprovals, type GateApprovalRule } from "../op/gate";
+import type { GateQuorumJudge } from "../op/gate-quorum";
 import type { ReasonCode } from "./reason-codes";
 import type { ReleaseRevocation } from "../lifecycle/release-revocation";
 import { CHANGE_SETS_DIR, changeSetFile } from "../lifecycle/change-set-store";
@@ -188,7 +189,7 @@ export function approveCommand(component: string, gate: string, env: string | nu
 const approvalOf = (r: GateResolutionRecord): StatusGateApproval => ({ principal: r.resolvedBy, channel: r.origin ?? null, relayedBy: r.relayedBy ?? null, at: r.timestamp });
 
 /** One gate in one environment, decided against its newest pending fact. */
-function decide(component: string, standing: PendingGateRecord, facts: PendingGateRecord[], all: GateResolutionRecord[], now: string, rule: GateApprovalRule | null): StatusGate {
+function decide(component: string, standing: PendingGateRecord, facts: PendingGateRecord[], all: GateResolutionRecord[], now: string, rule: GateApprovalRule | null, judge?: GateQuorumJudge): StatusGate {
   const gate = standing.gate;
   // #3163: under identity.gates, an unsigned approval, or one from outside the class, doesn't count, as a run reads it.
   // #4045: nor does an approval for another release, and an `empty` pass is never an approval.
@@ -208,8 +209,9 @@ function decide(component: string, standing: PendingGateRecord, facts: PendingGa
   let mismatched: GateResolutionRecord | undefined;
   if (standing.approval) {
     // #3206: a human approval from before a fact re-recorded for a mode or context change still counts.
-    const tally = tallyGateApprovals(own, gate, since, planDigest, standing.approval, humanQuorumSince(facts, standing));
-    approved = tally.permit !== undefined || tally.counted.length >= tally.need;
+    // #4290: approval rules count roles from .chant/trust.json at base, for a proven approver.
+    const tally = tallyGateApprovals(own, gate, since, planDigest, standing.approval, humanQuorumSince(facts, standing), judge);
+    approved = tally.permit !== undefined || tally.met;
     approvals = tally.permit && !tally.counted.includes(tally.permit) ? [...tally.counted, tally.permit] : tally.counted;
     needed = tally.need;
     mismatched = tally.mismatched;
@@ -249,7 +251,7 @@ function decide(component: string, standing: PendingGateRecord, facts: PendingGa
  * gate whose other facts have one is left out, as a run leaves it out: such a
  * line binds no environment, and `chant approve --expire` writes one.
  */
-export function gatesInLedger(component: string, content: string, envs: readonly string[], now: string, rules: GateRuleLookup = () => null): { gates: StatusGate[]; malformed: number } {
+export function gatesInLedger(component: string, content: string, envs: readonly string[], now: string, rules: GateRuleLookup = () => null, judge?: GateQuorumJudge): { gates: StatusGate[]; malformed: number } {
   const { pending, resolutions, malformed } = parseGateLedger(content);
   const gates: StatusGate[] = [];
   for (const gate of [...new Set(pending.map((p) => p.gate))].sort()) {
@@ -264,7 +266,7 @@ export function gatesInLedger(component: string, content: string, envs: readonly
     }
     for (const env of [...byEnv.keys()].sort((a, b) => envs.indexOf(a ?? "") - envs.indexOf(b ?? ""))) {
       const envFacts = byEnv.get(env)!;
-      gates.push(decide(component, latestPendingGate(envFacts, gate)!, envFacts, resolutions, now, rules(gate)));
+      gates.push(decide(component, latestPendingGate(envFacts, gate)!, envFacts, resolutions, now, rules(gate), judge));
     }
   }
   return { gates, malformed };
@@ -281,6 +283,7 @@ export async function readMemberGates(
   read: GateLedgerReader = defaultGateLedgerReader,
   rules: GateRuleLookup = () => null,
   listChangeSets: ChangeSetLister = defaultChangeSetLister,
+  judge?: GateQuorumJudge,
 ): Promise<{ gates: StatusGate[]; ledger: StatusGateLedger }> {
   const ledger: StatusGateLedger = { layout, path: dir, shared: false, malformed: 0, reason: null };
   if (commit === null) {
@@ -298,7 +301,7 @@ export async function readMemberGates(
   }
   const gates: StatusGate[] = [];
   for (const component of [...files.keys()].sort()) {
-    const read = gatesInLedger(component, files.get(component)!, envs, now, rules);
+    const read = gatesInLedger(component, files.get(component)!, envs, now, rules, judge);
     gates.push(...read.gates);
     ledger.malformed += read.malformed;
   }

package/src/workspace/status.ts

@@ -61,6 +61,7 @@ import { gateAdmissionFrom, releaseRuleFrom } from "./identity";
 import { checkReleaseSignature, type GateAdmissionRule, type ReleaseSignatureCheck } from "./identity-gate-rule";
 import { scopeSource } from "./write-scope";
 import { GATE_REASON_CODES, readMemberGates, type GateLedgerReader, type StatusGate, type StatusGateLedger } from "./status-gates";
+import { trustQuorumJudge } from "../op/gate-quorum";
 import { STEWARD_REASON_CODES, readMemberStewards, type StatusSteward, type StewardReasonCode } from "./status-stewards";
 import { gitTop, workingTree } from "./tree";
 import { handToRootChant } from "./which-chant";
@@ -718,6 +719,8 @@ export async function workspaceStatus(query: StatusQuery): Promise<StatusDocumen
     const ruleSource = scopeSource(found.dir);
     const rules = (gate: string) => gateAdmissionFrom(ruleSource, gate);
     const releaseRule = releaseRuleFrom(ruleSource).rule;
+    // #4290: approval rules read roles from the trust policy at base, for a proven approver.
+    const judge = trustQuorumJudge({ signers: ruleSource.policy, roles: ruleSource.policy.roles });
     // #4033 (ws-105): revoked commits, read from local tags once and only when a release is met.
     // Tags that can't be judged read as none revoked; workspace check reports the declaration.
     let revokedCommits: Promise<ReadonlyMap<string, ReleaseRevocation>> | undefined;
@@ -730,7 +733,7 @@ export async function workspaceStatus(query: StatusQuery): Promise<StatusDocumen
       const environments: StatusEnvironment[] = [];
       for (const env of envs) environments.push(await readEnvironment(m, env, found.dir, read, revokedOf, query.readOutcomes));
       const own = await hasMemberLedger(m, found.dir);
-      const gates = await readMemberGates(own ? `${MEMBERS_DIR}/${m.name}/${GATES_DIR}` : GATES_DIR, own ? "members" : "flat", commit, envs, found.dir, now, query.readGates, rules);
+      const gates = await readMemberGates(own ? `${MEMBERS_DIR}/${m.name}/${GATES_DIR}` : GATES_DIR, own ? "members" : "flat", commit, envs, found.dir, now, query.readGates, rules, undefined, judge);
       const stewards = await (query.readStewards ?? readMemberStewards)(resolve(found.dir, m.dir), query.env, now, m.kind, m.box);
       // The declaration's x- keys go back on the objects that hold them (#3595).
       const x = (pointer: string) => extensionsAt(declaration, pointer);

package/src/workspace/trust/gate-seal.test.ts

@@ -11,7 +11,7 @@ import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterAll, describe, expect, test } from "vitest";
-import { GATE_SEAL_NAMESPACE, gateSealPayload, gateSealRefusal, gateSealVersion, sshKeyFingerprint, verifySshSignatureWith, type GateSigners, type SealedGateApproval } from "./gate-seal";
+import { GATE_SEAL_NAMESPACE, gateSealPayload, gateSealRefusal, gateSealVersion, sshKeyFingerprint, verifySshSignatureWith, type GateSigners, type SealedGateApproval } from "../../lifecycle/gate-seal";
 import { checkGateSeal } from "./seal";
 import { emptyPolicy, parseAllowedSigners, type TrustPolicy } from "./policy";
 import { hasSshKeygen } from "./test-repo";

package/src/workspace/trust/seal.ts

@@ -30,10 +30,10 @@ import type { SealCode } from "../records";
 import { type TrustPolicy } from "./policy";
 import type { Signer } from "./trust-files";
 import { sshKeygen, verifySshSignature } from "./ssh-commit";
-import { GATE_SEAL_NAMESPACE, gateSealPayload, namespaceAllowed, sshSignatureKey, verifySshSignatureWith, type SealedGateApproval } from "./gate-seal";
+import { GATE_SEAL_NAMESPACE, gateSealPayload, namespaceAllowed, sshSignatureKey, verifySshSignatureWith, type SealedGateApproval } from "../../lifecycle/gate-seal";
 import { RELEASE_SEAL_NAMESPACE, releaseSealPayload } from "../identity-gate-rule";
 
-export { GATE_SEAL_NAMESPACE, gateSealPayload, gateSealVersion, sealedFieldsOf, type SealedGateApproval } from "./gate-seal";
+export { GATE_SEAL_NAMESPACE, gateSealPayload, gateSealVersion, sealedFieldsOf, type SealedGateApproval } from "../../lifecycle/gate-seal";
 
 /** The ssh signature namespace of a verdict seal. */
 export const REVIEW_SEAL_NAMESPACE = "chant-review";

package/dist/workspace/trust/gate-seal.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"gate-seal.d.ts","sourceRoot":"","sources":["../../../src/workspace/trust/gate-seal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAE5C;;;GAGG;AACH,eAAO,MAAM,mBAAmB,eAAe,CAAC;AAEhD,kIAAkI;AAClI,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,2EAA2E;IAC3E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,uFAAuF;IACvF,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,iGAAiG;IACjG,WAAW,CAAC,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,gBAAgB,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACzF,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,kBAAkB,GAAG,kBAAkB,CAWxE;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,IAAI,CAAC,kBAAkB,EAAE,kBAAkB,GAAG,aAAa,CAAC,GAAG,CAAC,GAAG,CAAC,CAGtG;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,kBAAkB,GAAG,MAAM,CAKpE;AA8BD,kFAAkF;AAClF,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEtD;AAmCD,iDAAiD;AACjD,MAAM,MAAM,iBAAiB,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAE1F;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,iBAAiB,CA0CtI;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAU9D;AAID;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,0EAA0E;IAC1E,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,6BAA6B;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,uGAAuG;IACvG,MAAM,EAAE,OAAO,CAAC;IAChB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,yFAAyF;IACzF,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAID,kJAAkJ;AAClJ,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAYrF;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,WAAW,EAAE,CAAC,EAAE,kBAAkB,GAAG,MAAM,GAAG,IAAI,CAmB1F"}