@intentius/chant 0.124.40 → 0.124.41

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

package/src/workspace/ci-run-index.test.ts

@@ -31,7 +31,8 @@ import schema from "./ci-run-index.schema.json";
 afterAll(cleanScratch);
 
 const JOB_IMAGE = "chant-ci-run-index-test:local";
-const HOST = { PATH: process.env.PATH, HOME: process.env.HOME, GITHUB_TOKEN: "t", GITHUB_REPOSITORY: "acme/estate" };
+// No forge token: a plan job given one posts its note from the report (#4295), which these tests do not look at.
+const HOST = { PATH: process.env.PATH, HOME: process.env.HOME, GITHUB_REPOSITORY: "acme/estate" };
 
 /** The repository every test starts from, built once: one member, and two commits. */
 const repoTemplate = repoFixture(() => {

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

@@ -18,7 +18,8 @@ import { afterAll, beforeAll, describe, expect, test } from "vitest";
 import { cleanScratch, declaration, git, repoFixture, scratchDir, writeFiles } from "./__fixtures__/contract-repo";
 import { checkRunEventLines } from "./__fixtures__/run-event-check";
 import { ciJobCommand, ciJobEnv, ciJobFailure, ciJobOp, ciLoopOptions, ciRun, CiRunError, ciStatusContext, ciStatusFromEnv, ciStatusUrl, formatCiRun } from "./ci-run";
-import type { CommitStatus } from "../pr-forge";
+import type { CommitStatus, ForgeStatus, PrForge } from "../pr-forge";
+import { FORGE_TOKEN_VARS } from "../ci-handover";
 import { ciList, ciTick, evaluateCommit, readOpRunSource, revokedAnnotation } from "./ci-green";
 import type { StepRecord } from "../op/local-executor";
 import { sshFromEd25519 } from "./trust/dsse";
@@ -136,6 +137,28 @@ const HOST = {
   GITHUB_RUN_ID: "999",
 };
 
+/** A plan report for pull request 7 at `sha` in member `app`, which the fake chant writes with FAKE_REPORT (#4295). */
+const PLAN_FIXTURE = JSON.parse(readFileSync(join(import.meta.dirname, "..", "__fixtures__", "pr-loop", "pr-plan.golden.json"), "utf-8")) as Record<string, unknown>;
+const planReport = (sha: string): string => JSON.stringify({ ...PLAN_FIXTURE, pr: 7, head: sha, member: "app" });
+
+/** A forge client that records the plan's status and note the runner posts from the report (#4295). */
+function recordingForge(): { forge: PrForge; statuses: Array<{ sha: string; status: ForgeStatus }>; notes: Array<{ pr: number; marker: string }> } {
+  const statuses: Array<{ sha: string; status: ForgeStatus }> = [];
+  const notes: Array<{ pr: number; marker: string }> = [];
+  const forge = {
+    kind: "forgejo",
+    host: "forgejo.localhost",
+    async setStatus(sha: string, status: ForgeStatus) {
+      statuses.push({ sha, status });
+    },
+    async upsertNote(pr: number, marker: string) {
+      notes.push({ pr, marker });
+      return "1";
+    },
+  } as unknown as PrForge;
+  return { forge, statuses, notes };
+}
+
 const envFile = (dir: string, stage: string): Record<string, string> =>
   Object.fromEntries(
     readFileSync(join(dir, `${stage}.env`), "utf-8")
@@ -235,6 +258,7 @@ describe("chant ci run, then ci tick from runs (#4094)", () => {
   let events: string[];
   let plan: Awaited<ReturnType<typeof ciRun>>;
   let apply: Awaited<ReturnType<typeof ciRun>>;
+  const posted = recordingForge();
 
   beforeAll(async () => {
     w = workspace();
@@ -250,8 +274,9 @@ describe("chant ci run, then ci tick from runs (#4094)", () => {
       base: w.base,
       pr: 7,
       chant,
-      hostEnv: HOST,
-      passEnv: ["AWS_ACCESS_KEY_ID"],
+      hostEnv: { ...HOST, FAKE_REPORT: planReport(w.sha) },
+      passEnv: ["AWS_ACCESS_KEY_ID", "FAKE_REPORT"],
+      planForge: posted.forge,
       runnerKey: BOT.pem,
       output: join(reports, "plan"),
       runId: "chant-plan-1",
@@ -271,20 +296,24 @@ describe("chant ci run, then ci tick from runs (#4094)", () => {
     const out = join(reports, "plan");
     const [job] = prLoopJobs("forgejo", "prod", {}, "app");
     const argv = readFileSync(join(out, "pr-plan.args"), "utf-8").trimEnd().split("\n");
-    expect(argv).toEqual(["components", "pr-plan", "--base", base, "--pr", "7", "--env", "prod", "--gate", "pr-apply", "--output", ".chant/pr", "--forge", "forgejo", "--member", "app"]);
+    expect(argv).toEqual(["components", "pr-plan", "--base", base, "--pr", "7", "--env", "prod", "--gate", "pr-apply", "--output", ".chant/pr", "--forge", "forgejo", "--member", "app", "--no-status"]);
     expect(job!.command.split(" ").slice(1).map((a) => a.replace(/"/g, ""))).toEqual(argv.map((a) => (a === base ? "$BASE_SHA" : a === "7" ? "$PR_NUMBER" : a)));
     const pwd = readFileSync(join(out, "pr-plan.pwd"), "utf-8").trim();
     expect(pwd).toBe(join(plan.checkout, "app"));
     expect(pwd.startsWith(realpathSync(root))).toBe(false);
     expect(existsSync(plan.checkout)).toBe(false);
     expect(git(root, "worktree", "list", "--porcelain")).toBe(worktrees);
-    expect(JSON.parse(readFileSync(join(out, "pr-plan.json"), "utf-8"))).toEqual({ stage: "pr-plan" });
+    expect(JSON.parse(readFileSync(join(out, "pr-plan.json"), "utf-8"))).toMatchObject({ stage: "plan", pr: 7, head: sha });
 
     // The environment is clean: the job's variables and the few the runner hands on. The copied
     // report shows the values of the variables whose names look secret as *** (#4096).
     const env = envFile(out, "pr-plan");
-    expect(env).toMatchObject({ BASE_SHA: base, PR_NUMBER: "7", GITHUB_SHA: sha, CHANT_ENV: "prod", GITHUB_TOKEN: "***", AWS_ACCESS_KEY_ID: "***" });
+    expect(env).toMatchObject({ BASE_SHA: base, PR_NUMBER: "7", GITHUB_SHA: sha, CHANT_ENV: "prod", AWS_ACCESS_KEY_ID: "***" });
     for (const name of ["NOT_FOR_JOBS", "CHANT_RUNNER_KEY", "GITHUB_RUN_ID"]) expect(env).not.toHaveProperty(name);
+    // #4295: the plan runs the pull request's code, so its step got no forge token; the runner posted from its report.
+    for (const name of FORGE_TOKEN_VARS) expect(env).not.toHaveProperty(name);
+    expect(posted.statuses).toEqual([{ sha, status: expect.objectContaining({ context: "chant/plan/app", state: "success" }) }]);
+    expect(posted.notes).toEqual([{ pr: 7, marker: "<!-- chant-pr:prod:app -->" }]);
   });
 
   test("the plan and the apply are recorded signed, with a pipeline run's events", async () => {
@@ -508,7 +537,9 @@ describe("a commit status per job (#4097)", () => {
 
   async function job(over: Record<string, unknown>) {
     const { root, app, base, sha } = workspace();
-    const r = await ciRun({ image: JOB_IMAGE, cwd: app, job: "plan", env: "prod", forge: "forgejo", base, pr: 7, chant: fakeChant(), hostEnv: HOST, push: false, output: join(scratchDir("chant-ci-status-"), "pr"), ...over } as Parameters<typeof ciRun>[0]);
+    // #4295: a plan job's report is a real plan report, and the runner posts it to a recording forge.
+    const plan = { hostEnv: { ...HOST, FAKE_REPORT: planReport(sha) }, passEnv: ["FAKE_REPORT"], planForge: recordingForge().forge };
+    const r = await ciRun({ image: JOB_IMAGE, cwd: app, job: "plan", env: "prod", forge: "forgejo", base, pr: 7, chant: fakeChant(), push: false, output: join(scratchDir("chant-ci-status-"), "pr"), ...plan, ...over } as Parameters<typeof ciRun>[0]);
     return { r, sha };
   }
 
@@ -818,7 +849,8 @@ describe("a generated forge job runs ci run --in-place (#4156)", () => {
   test("with no key the job runs, warns of nothing, and its unsigned record counts in ci list and the run index", async () => {
     const { app, base, sha } = workspace();
     const reports = scratchDir("chant-ci-run-index-");
-    const { CHANT_RUNNER_KEY: _key, ...keyless } = HOST;
+    // #4295: a plan job generated now holds no forge token; its plan-note job posts.
+    const { CHANT_RUNNER_KEY: _key, GITHUB_TOKEN: _token, ...keyless } = HOST;
     const r = await ciRun({ cwd: app, job: "plan", env: "prod", forge: "forgejo", base, pr: 7, chant: fakeChant(), hostEnv: { ...keyless, ...FORGE, GITHUB_JOB: "plan" }, inPlace: true, push: false, runId: "forge-plan-1", loop: { reportUrl: `file://${reports}` } });
     expect(r.status).toBe("ok");
     expect(r.warnings).toEqual([]);
@@ -940,3 +972,70 @@ describe("ci run --local (#4161)", () => {
     expect(parseArgs(["ci", "run", "plan", "--local"]).local).toBe(true);
   });
 });
+
+describe("the plan's steps hold no forge token (#4295)", () => {
+  test("on the runner: no token reaches a step from the runner, --pass-env or a forge name, and the runner posts the note from the report", async () => {
+    const { app, base, sha } = workspace();
+    const output = join(scratchDir("chant-ci-handover-"), "pr");
+    const forge = recordingForge();
+    const tokens = { GH_TOKEN: "gh-token-4295", FORGEJO_TOKEN: "fj-token-4295", CHANT_FORGE_TOKEN: "chant-token-4295", ACTIONS_RUNTIME_TOKEN: "rt-token-4295" };
+    const r = await ciRun({
+      image: JOB_IMAGE,
+      cwd: app,
+      job: "plan",
+      env: "prod",
+      forge: "forgejo",
+      base,
+      pr: 7,
+      chant: fakeChant(),
+      hostEnv: { ...HOST, ...tokens, FAKE_REPORT: planReport(sha) },
+      passEnv: ["FAKE_REPORT", ...Object.keys(tokens)],
+      beforeScript: ["mkdir -p .chant/pr && env | sort > .chant/pr/before.env"],
+      planForge: forge.forge,
+      push: false,
+      output,
+    });
+    expect(r.status).toBe("ok");
+    expect(r.warnings).toEqual([]);
+    const env = readFileSync(join(output, "pr-plan.env"), "utf-8");
+    for (const value of ["forge-token", ...Object.values(tokens)]) expect(env).not.toContain(value);
+    // The build phase's lines run the change's code too.
+    expect(r.record.phases.map((p) => p.name)).toEqual(["build", "plan"]);
+    const before = readFileSync(join(output, "before.env"), "utf-8");
+    for (const value of ["forge-token", ...Object.values(tokens)]) expect(before).not.toContain(value);
+    for (const name of FORGE_TOKEN_VARS) expect(env).not.toMatch(new RegExp(`^${name}=`, "m"));
+    expect(readFileSync(join(output, "pr-plan.args"), "utf-8").trimEnd().split("\n").at(-1)).toBe("--no-status");
+    expect(forge.statuses.map((p) => [p.sha, p.status.context, p.status.state])).toEqual([[sha, "chant/plan/app", "success"]]);
+    expect(forge.notes).toEqual([{ pr: 7, marker: "<!-- chant-pr:prod:app -->" }]);
+  });
+
+  test("a report the change forged for another head posts a failed status and no note", async () => {
+    const { app, base } = workspace();
+    const forge = recordingForge();
+    const r = await ciRun({ image: JOB_IMAGE, cwd: app, job: "plan", env: "prod", forge: "forgejo", base, pr: 7, chant: fakeChant(), hostEnv: { ...HOST, FAKE_REPORT: planReport("3".repeat(40)) }, passEnv: ["FAKE_REPORT"], planForge: forge.forge, push: false, output: join(scratchDir("chant-ci-handover-"), "pr") });
+    expect(r.warnings).toEqual([expect.stringMatching(/the plan report was not posted: the report is for head/)]);
+    expect(forge.statuses.map((p) => p.status.state)).toEqual(["failure"]);
+    expect(forge.notes).toEqual([]);
+  });
+
+  test("in place, a job generated before #4295 still holds a token: its step gets none, the runner posts, and says to regenerate", async () => {
+    const { app, base, sha } = workspace();
+    const forge = recordingForge();
+    const r = await ciRun({ cwd: app, job: "plan", env: "prod", forge: "forgejo", base, pr: 7, chant: fakeChant(), hostEnv: { ...HOST, GITHUB_JOB: "plan", FAKE_REPORT: planReport(sha) }, inPlace: true, push: false, planForge: forge.forge });
+    expect(r.warnings).toEqual([expect.stringMatching(/regenerate the pipeline, whose plan-note job posts the note/)]);
+    const env = envFile(join(app, ".chant/pr"), "pr-plan");
+    expect(env).not.toHaveProperty("GITHUB_TOKEN");
+    expect(env.NOT_FOR_JOBS).toBe("leak");
+    expect(forge.notes).toHaveLength(1);
+  });
+
+  test("the apply and the record keep their token: they run the target branch's code and post themselves", () => {
+    const [, apply, record] = prLoopJobs("forgejo", "prod");
+    expect(apply!.env.GITHUB_TOKEN).toBe("${{ github.token }}");
+    expect(record!.env.GITHUB_TOKEN).toBe("${{ github.token }}");
+    const [plan] = prLoopJobs("forgejo", "prod");
+    expect(plan!.env).not.toHaveProperty("GITHUB_TOKEN");
+    expect(plan!.run.env).not.toHaveProperty("GITHUB_TOKEN");
+    expect(plan!.command.endsWith(" --no-status")).toBe(true);
+  });
+});

package/src/workspace/ci-run.ts

@@ -45,6 +45,16 @@
  * commit: `pending` when it starts, `success` or `failure` when it settles.
  * A status the forge refuses is a warning and never fails the job.
  *
+ * The plan runs the pull request's code, so no step of the plan job gets a
+ * forge token (#4295, ../ci-handover.ts): every name in `FORGE_TOKEN_VARS`
+ * is left out of its steps' environment, from the runner, a secret or the
+ * forge job alike, and `pr-plan` runs with `--no-status`. Once the steps
+ * settle, the runner posts the note and the `chant/plan` status from the
+ * report with its own token (`postPlanReport`, ../pr-post.ts). In place, a
+ * generated job holds no token and its `plan-note` job posts; a job that
+ * still holds one was generated before #4295, and the runner posts for it
+ * with a warning to regenerate.
+ *
  * Signing is opt-in (#4156). With no runner key the record is unsigned, and
  * a reader counts it with no signer. A key `.chant/trust.json` does not list
  * leaves it unsigned with a note `--verbose` prints, unless the declaration
@@ -75,7 +85,9 @@ import { copyFileSync, cpSync, existsSync, mkdirSync, mkdtempSync, readdirSync,
 import { tmpdir } from "node:os";
 import { dirname, join, relative, resolve, sep } from "node:path";
 import { PR_APPLY_RECORD, PR_LOOP_REPORT_DIR, prLoopJobs, prLoopSetup, PR_LOOP_IMAGE, type PrLoopJob, type PrLoopPipelineOptions } from "../components/pr-pipeline";
-import { detectForge, ForgeEnvironmentError, forgeFromEnv, FORGE_KINDS, type CommitStatus, type ForgeKind } from "../pr-forge";
+import { detectForge, ForgeEnvironmentError, forgeFromEnv, FORGE_KINDS, type CommitStatus, type ForgeKind, type PrForge } from "../pr-forge";
+import { holdsForgeToken, withoutForgeTokens } from "../ci-handover";
+import { postPlanReport } from "../pr-post";
 import { PR_APPLY_GATE } from "../pr-loop";
 import type { CommandContext } from "../cli/registry";
 import { formatError, formatWarning } from "../cli/format";
@@ -458,6 +470,12 @@ export interface CiRunRequest {
   secrets?: CiSecrets;
   /** `--output`: where the job's report is copied, from `cwd`. Default `.chant/pr`. */
   output?: string;
+  /**
+   * The forge client that posts the plan's note and `chant/plan` status from
+   * its report once the steps settle (#4295). Default: one built from the
+   * runner's environment when it holds a forge token.
+   */
+  planForge?: PrForge;
   /** `--run-index-limit`: how many runs the index at `loop.reportUrl` keeps (#4098). Default 200. */
   runIndexLimit?: number;
   /** A runner key, PEM, that signs the run's record. */
@@ -675,7 +693,8 @@ export async function ciRun(req: CiRunRequest): Promise<CiRunResult> {
   const started = req.requireRunnerStart || isolated ? runnerStartFor(req, { top, commit, hostEnv }) : undefined;
   // A generated wave job's command, as prLoopWaveJobs writes it. #4161: a local job's command posts no status or note.
   const forgeCommand = req.noForge ? found.command.replace(` --forge ${req.forge}`, "") : found.command;
-  const command = `${forgeCommand}${req.wave !== undefined ? ` --wave ${req.wave}` : ""}${req.local ? " --no-status" : ""}`;
+  const noStatus = req.local && !/ --no-status(?: |$)/.test(forgeCommand);
+  const command = `${forgeCommand}${req.wave !== undefined ? ` --wave ${req.wave}` : ""}${noStatus ? " --no-status" : ""}`;
   const job = { ...found, command, ...(req.wave !== undefined ? { wave: req.wave } : {}) };
   const own = ciJobEnv(job, {
     forge: req.forge,
@@ -686,14 +705,19 @@ export async function ciRun(req: CiRunRequest): Promise<CiRunResult> {
     secrets: ciSecretsFor(req.secrets, req.job),
   });
   // #4156: in place, the forge job's environment is the job's, less the runner key.
-  const jobEnv = req.inPlace ? { ...definedEnv(hostEnv), ...own } : own;
+  // #4295: the plan runs the pull request's code, so no step of it gets a forge token, whatever gave it one.
+  const merged = req.inPlace ? { ...definedEnv(hostEnv), ...own } : own;
+  const jobEnv = req.job === "plan" ? withoutForgeTokens(merged) : merged;
   delete jobEnv[RUNNER_KEY_ENV];
+  const poster = req.job === "plan" ? planPoster(req, hostEnv) : undefined;
   // #4096: the secrets and the job's secret-looking variables, redacted from everything the run writes and returns.
   // In place the forge's own variables come too; one whose value is short, such as a flag, is left out, so it can't blank common words.
   const redact = ciRedactor(req.inPlace ? { ...longValues(jobEnv), ...own } : jobEnv, req.secrets);
   try {
     const ran = await runCiJob(req, { cwd, top, commit, place, job, jobEnv, ...(redact ? { redact } : {}) });
-    const result = started ? { ...ran, notes: [started, ...ran.notes] } : ran;
+    const posted = poster ? await postFromReport(req, poster, ran, { commit, ...(place.member ? { member: place.member } : {}) }) : [];
+    const withPosts = posted.length > 0 ? { ...ran, warnings: [...ran.warnings, ...posted] } : ran;
+    const result = started ? { ...withPosts, notes: [started, ...withPosts.notes] } : withPosts;
     return redact ? { ...result, warnings: result.warnings.map(redact), notes: result.notes.map(redact), ...(result.pushWarning ? { pushWarning: redact(result.pushWarning) } : {}) } : result;
   } catch (err) {
     if (redact && err instanceof Error) err.message = redact(err.message);
@@ -701,6 +725,50 @@ export async function ciRun(req: CiRunRequest): Promise<CiRunResult> {
   }
 }
 
+/**
+ * Who posts the plan's note and `chant/plan` status (#4295): the runner,
+ * from the report, once the plan's steps settled, with the forge token the
+ * steps never got. None on `--local`, for a plain git server (`noForge`), or
+ * without a token. In place, a token means the job was generated before the
+ * plan-note job existed: the runner still posts, and says to regenerate.
+ */
+function planPoster(req: CiRunRequest, hostEnv: Record<string, string | undefined>): { forge: PrForge; warning?: string } | { error: string } | undefined {
+  if (req.local || req.noForge || req.pr === undefined) return undefined;
+  const warning = req.inPlace
+    ? "this plan job holds a forge token, which the pull request's code runs beside in the same job; regenerate the pipeline, whose plan-note job posts the note from a fresh job (#4295)"
+    : undefined;
+  if (req.planForge) return { forge: req.planForge, ...(warning ? { warning } : {}) };
+  if (!holdsForgeToken(hostEnv)) return undefined;
+  try {
+    return { forge: forgeFromEnv(req.forge, hostEnv), ...(warning ? { warning } : {}) };
+  } catch (err) {
+    return { error: `the plan's note and status will not be posted: ${message(err)}` };
+  }
+}
+
+/** Post the plan's note and status from the report the job wrote (#4295), and return the warnings. */
+async function postFromReport(
+  req: CiRunRequest,
+  poster: NonNullable<ReturnType<typeof planPoster>>,
+  ran: CiRunResult,
+  at: { commit: string; member?: string },
+): Promise<string[]> {
+  if ("error" in poster) return [poster.error];
+  const warnings = poster.warning ? [poster.warning] : [];
+  const dir = ran.report ?? resolve(req.cwd, req.output ?? PR_LOOP_REPORT_DIR);
+  const posted = await postPlanReport({
+    forge: poster.forge,
+    dir,
+    pr: req.pr!,
+    head: at.commit,
+    env: req.env,
+    ...(at.member ? { member: at.member } : {}),
+    result: ran.status === "ok" ? "success" : "failure",
+  });
+  if (posted.refused) warnings.push(`the plan report was not posted: ${posted.refused}`);
+  return [...warnings, ...posted.warnings];
+}
+
 /**
  * `--require-runner-start` (#4147): the runner-start statement for this
  * forge job, checked against `.chant/trust.json` at `--base` (the commit

package/src/workspace/declaration.schema.json

@@ -181,10 +181,116 @@
         "workflow": {
           "$ref": "#/$defs/ciWorkflow"
         },
+        "hooks": {
+          "$ref": "#/$defs/ciHooks"
+        },
+        "locks": {
+          "enum": ["apply", "plan"],
+          "description": "When a pull request takes its target locks, _locks/<gate>.json on chant/lifecycle (#4293). apply: the pull request's apply takes them, and chant lock takes them 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, chant components pr-apply refuses a target that another open pull request holds, and a lock whose pull request merged or closed reads as released. Absent: nothing is locked. Read from the declaration at base. Added in schema 1 by chant 0.124.41, so a declaration that uses it sets minReader to 0.124.41 or newer."
+        },
+        "policy": {
+          "$ref": "#/$defs/ciPolicy"
+        },
         "reportUrl": {
           "type": "string",
           "minLength": 1,
           "description": "Where the pull-request jobs copy their reports and events, and where chant ci run keeps the run index, <reportUrl>/runs/index.json (#4160): an s3://<bucket>/<prefix> or file://<directory> URL, as --report-url takes. chant build --pr-loop, chant ci run, chant ci serve and chant ci runs use it when --report-url is not given, and the flag wins. Readers find it in chant workspace ls --json as ci.reportUrl. Added in schema 1 by chant 0.124.32, so a declaration that uses it sets minReader to 0.124.32 or newer."
+        },
+        "branches": {
+          "type": "object",
+          "description": "Branch routing (#4292): a branch name to member-name globs. A member a glob matches applies from that branch alone: chant build --pr-loop targets its pipeline at the branch, and its record and apply jobs plan nothing on a push to any other branch. A member no glob matches applies from every branch the map does not name. One member may not be matched by two branches. Added in schema 1 by chant 0.124.41, so a declaration that uses it sets minReader to 0.124.41 or newer.",
+          "patternProperties": {
+            "^x-": true,
+            "^(?!x-)[^\\s]+$": { "$ref": "#/$defs/ciMemberGlobs" }
+          },
+          "additionalProperties": false
+        },
+        "labels": {
+          "type": "object",
+          "description": "Label filters (#4292): a pull request label to member-name globs. When a pull request carries one of these labels, its plan jobs plan only the members those labels match. A label never gates: the record and apply jobs never read labels, and an apply still needs an approval of the digest it plans. Added in schema 1 by chant 0.124.41, so a declaration that uses it sets minReader to 0.124.41 or newer.",
+          "patternProperties": {
+            "^x-": true,
+            "^(?!x-).+$": { "$ref": "#/$defs/ciMemberGlobs" }
+          },
+          "additionalProperties": false
+        },
+        "identity": {
+          "type": "object",
+          "additionalProperties": false,
+          "patternProperties": { "^x-": true },
+          "description": "Cloud identities for the pull-request jobs (#4296). Added in schema 1 by chant 0.124.41, so a declaration that uses it sets minReader to 0.124.41 or newer.",
+          "properties": {
+            "cloud": {
+              "type": "object",
+              "additionalProperties": false,
+              "patternProperties": { "^x-": true },
+              "description": "Each cloud's plan and apply identities, as rules over environment and member globs. chant build --pr-loop takes the first rule that matches the pipeline's environment and member. The plan job trades its OIDC token for the plan identity before the change is checked out, the record job takes the plan identity, and the apply jobs the apply identity. A rule may not plan as an identity any rule applies as.",
+              "properties": {
+                "aws": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "patternProperties": { "^x-": true },
+                  "required": ["rules"],
+                  "description": "AWS roles, assumed through STS AssumeRoleWithWebIdentity.",
+                  "properties": {
+                    "region": { "type": "string", "minLength": 1, "description": "The STS region. Default us-east-1." },
+                    "audience": { "type": "string", "minLength": 1, "description": "The OIDC token's audience. Default sts.amazonaws.com." },
+                    "endpoint": { "type": "string", "pattern": "^https?://", "description": "The STS endpoint, for an emulator. Default the region's, or AWS_ENDPOINT_URL_STS in the job." },
+                    "rules": { "$ref": "#/$defs/ciCloudIdentityRules" }
+                  }
+                },
+                "gcp": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "patternProperties": { "^x-": true },
+                  "required": ["provider", "rules"],
+                  "description": "GCP service accounts, reached through a workload identity provider and impersonated with IAM generateAccessToken.",
+                  "properties": {
+                    "provider": { "type": "string", "pattern": "^(//iam\\.googleapis\\.com/)?projects/[^/]+/locations/global/workloadIdentityPools/[^/]+/providers/[^/]+$", "description": "The workload identity provider: projects/<number>/locations/global/workloadIdentityPools/<pool>/providers/<provider>." },
+                    "audience": { "type": "string", "minLength": 1, "description": "The OIDC token's audience. Default https://iam.googleapis.com/<provider>." },
+                    "stsEndpoint": { "type": "string", "pattern": "^https?://", "description": "Google's STS, for an emulator. Default https://sts.googleapis.com." },
+                    "iamEndpoint": { "type": "string", "pattern": "^https?://", "description": "IAM credentials, for an emulator. Default https://iamcredentials.googleapis.com." },
+                    "rules": { "$ref": "#/$defs/ciCloudIdentityRules" }
+                  }
+                },
+                "azure": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "patternProperties": { "^x-": true },
+                  "required": ["tenantId", "rules"],
+                  "description": "Entra application clients, each with a federated credential for the forge's tokens. The rules' identities are client ids.",
+                  "properties": {
+                    "tenantId": { "type": "string", "minLength": 1, "description": "The Entra tenant." },
+                    "subscriptionId": { "type": "string", "minLength": 1, "description": "Set as AZURE_SUBSCRIPTION_ID and ARM_SUBSCRIPTION_ID when given." },
+                    "audience": { "type": "string", "minLength": 1, "description": "The OIDC token's audience. Default api://AzureADTokenExchange." },
+                    "authority": { "type": "string", "pattern": "^https?://", "description": "The Entra authority host, for an emulator. Default https://login.microsoftonline.com." },
+                    "rules": { "$ref": "#/$defs/ciCloudIdentityRules" }
+                  }
+                }
+              }
+            }
+          }
+        },
+        "prEnvironment": {
+          "type": "object",
+          "description": "An environment per open pull request (#4298): chant components pr-env up applies the pull request's components to pr-<number>, which takes the template environment's declared endpoint, and pr-env down tears down only what carries that environment's ownership marker. A pull request's environment is never a release target. Read from the declaration at base, so a pull request cannot change its own template or TTL. Added in schema 1 by chant 0.124.42, so a declaration that uses it sets minReader to 0.124.42 or newer.",
+          "required": ["template"],
+          "additionalProperties": false,
+          "patternProperties": {
+            "^x-": true
+          },
+          "properties": {
+            "template": {
+              "type": "string",
+              "pattern": "^[a-z0-9][a-z0-9-]*$",
+              "description": "The declared environment a pull request's environment is derived from: pr-<number> takes its endpoint unless a pr-* entry declares one."
+            },
+            "ttl": {
+              "type": "string",
+              "pattern": "^[1-9][0-9]*(m|h|d)$",
+              "description": "How long a pull request's environment lives after its last apply, such as 72h, 90m or 7d. chant components pr-env sweep tears down one whose TTL passed. 72h when absent."
+            }
+          }
         }
       }
     },
@@ -254,6 +360,36 @@
   },
   "additionalProperties": false,
   "$defs": {
+    "ciCloudIdentityRules": {
+      "type": "array",
+      "minItems": 1,
+      "description": "Rules, first match wins: a rule matches a pipeline when its environments match the pipeline's environment and its members match the pipeline's member. A rule with no environments matches every environment, and one with no members every member and a pipeline outside a member.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "patternProperties": { "^x-": true },
+        "required": ["plan", "apply"],
+        "properties": {
+          "environments": {
+            "type": "array",
+            "minItems": 1,
+            "uniqueItems": true,
+            "items": { "type": "string", "minLength": 1 },
+            "description": "Environment-name globs, such as prod or staging-*."
+          },
+          "members": { "$ref": "#/$defs/ciMemberGlobs" },
+          "plan": { "type": "string", "minLength": 1, "description": "The identity the plan and record jobs take: a role ARN, a service account email or a client id." },
+          "apply": { "type": "string", "minLength": 1, "description": "The identity the apply jobs take." }
+        }
+      }
+    },
+    "ciMemberGlobs": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": { "type": "string", "minLength": 1, "pattern": "^[a-z0-9*?\\[\\]{},!-]+$" },
+      "description": "Globs over member names, such as prod-* or [\"api\", \"web\"]: * and ? within the name, [...] classes, {a,b} alternatives."
+    },
     "retentionDays": {
       "type": "integer",
       "minimum": 0,
@@ -504,6 +640,9 @@
           "properties": {
             "workflow": {
               "$ref": "#/$defs/ciWorkflow"
+            },
+            "hooks": {
+              "$ref": "#/$defs/ciHooks"
             }
           }
         },
@@ -1582,6 +1721,14 @@
       "enum": ["trunk-curated", "trunk-curated+apply-on-merge"],
       "description": "A prescribed delivery workflow (#4168). trunk-curated: a merge records the plan and deploys nothing; releases are cut from green commits and promoted through each member's environments, gated in the last. trunk-curated+apply-on-merge: the same, with the apply on merge turned back on. chant workspace check reports what a member under one still lacks (WSP151), and chant ci init writes it. At the top level for every member, or on a member, which wins. Added in schema 1 by chant 0.124.34, so a declaration that uses it sets minReader to 0.124.34 or newer."
     },
+    "ciHooks": {
+      "type": "object",
+      "description": "Stage hooks the pull-request jobs run (#4288), in the shape an Op waves spec's hooks take: before.observe, before.plan, after.plan, before.apply and after.apply, each a list of { command, name?, onFailure?, perRun?, targets? }. targets are component names or patterns. chant components pr-plan, pr-record and pr-apply read them from the declaration at base, the top level's first and then the member's. after.gate and apply.runBy are refused. Added in schema 1 by chant 0.124.41, so a declaration that uses it sets minReader to 0.124.41 or newer."
+    },
+    "ciPolicy": {
+      "type": "object",
+      "description": "Gate-time policy on the pull-request jobs (#4294): a policy engine run over the change set, with the policy read at base. engine names the result shape the command prints, conftest (the default) or opa. path is the policy directory, relative to the declaration (default policy). namespace is the package to read. command replaces the engine's own argv, with {policy} for the policy directory exported from base and {input} for the input file. deny rules refuse the apply unless an override counts; hold rules make the plan wait for a person's approval; warn rules are advice. There is no unattended outcome. Added in schema 1 by chant 0.124.41, so a declaration that uses it sets minReader to 0.124.41 or newer."
+    },
     "ciPhaseName": {
       "type": "string",
       "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$"

package/src/workspace/declaration.test.ts

@@ -436,6 +436,15 @@ describe("retention (#4036)", () => {
   });
 });
 
+describe("ci.locks (#4293)", () => {
+  test("apply or plan is read; absent leaves it out; anything else is declaration-invalid", () => {
+    expect(parse(base([], { ci: { locks: "plan" } })).ci).toEqual({ green: null, locks: "plan", reportUrl: null });
+    expect(parse(base([], { ci: { locks: "apply" } })).ci?.locks).toBe("apply");
+    expect(parse(base([], { ci: {} })).ci?.locks).toBeUndefined();
+    for (const locks of ["merge", true, ""]) expect(failure(base([], { ci: { locks } })).code).toBe("declaration-invalid");
+  });
+});
+
 describe("ci.reportUrl (#4160)", () => {
   test("an s3:// or file:// URL is read without its trailing slash, beside green or alone, and is null when absent", () => {
     expect(parse(base([])).ci).toBeNull();
@@ -489,3 +498,70 @@ describe("metrics (#4039)", () => {
     }
   });
 });
+
+describe("ci.branches and ci.labels (#4292)", () => {
+  const members = [
+    { name: "prod-eu", dir: "prod-eu", kind: "chant" },
+    { name: "api", dir: "api", kind: "chant" },
+  ];
+
+  test("both maps are read without their x- keys, and stay absent when unset", () => {
+    const d = parse(base(members, { ci: { branches: { release: ["prod-*"], "x-note": "ops" }, labels: { "plan:prod": ["prod-*"] } } }));
+    expect(d.ci?.branches).toEqual({ release: ["prod-*"] });
+    expect(d.ci?.labels).toEqual({ "plan:prod": ["prod-*"] });
+    expect(parse(base(members, { ci: {} })).ci).toEqual({ green: null, reportUrl: null });
+  });
+
+  test("a member two branches route is declaration-invalid at the second branch", () => {
+    const err = failure(base(members, { ci: { branches: { release: ["prod-*"], hotfix: ["prod-eu"] } } }));
+    expect(err.code).toBe("declaration-invalid");
+    expect(err.message).toBe("ci.branches routes member prod-eu to both release and hotfix; a member applies from one branch");
+  });
+
+  test("an empty glob list or a glob that is not a member-name glob is refused", () => {
+    expect(failure(base(members, { ci: { branches: { release: [] } } })).code).toBe("declaration-invalid");
+    expect(failure(base(members, { ci: { branches: { release: ["prod/eu"] } } })).code).toBe("declaration-invalid");
+    expect(failure(base(members, { ci: { labels: { "plan:prod": "prod-*" } } })).code).toBe("declaration-invalid");
+  });
+});
+
+describe("ci.identity.cloud (#4296)", () => {
+  const members = [{ name: "net", dir: "net", kind: "chant" }];
+  const aws = { region: "eu-west-1", "x-note": "ops", rules: [{ environments: ["prod"], members: ["net"], plan: "arn:aws:iam::1:role/plan", apply: "arn:aws:iam::1:role/apply", "x-why": "split" }] };
+
+  test("each cloud is read without its x- keys", () => {
+    const d = parse(base(members, { ci: { identity: { cloud: { aws, azure: { tenantId: "t", rules: [{ plan: "p", apply: "a" }] } } } } }));
+    expect(d.ci?.identity).toEqual({
+      cloud: {
+        aws: { region: "eu-west-1", rules: [{ environments: ["prod"], members: ["net"], plan: "arn:aws:iam::1:role/plan", apply: "arn:aws:iam::1:role/apply" }] },
+        azure: { tenantId: "t", rules: [{ plan: "p", apply: "a" }] },
+      },
+    });
+  });
+
+  test("a rule that plans as an identity some rule applies as is declaration-invalid at that rule", () => {
+    const err = failure(base(members, { ci: { identity: { cloud: { aws: { rules: [{ plan: "r", apply: "r" }] } } } } }));
+    expect(err.code).toBe("declaration-invalid");
+    expect(err.message).toContain("ci.identity.cloud.aws.rules[0] plans and applies as r");
+  });
+
+  test("the schema refuses a rule with no apply, an unknown cloud and a GCP provider that is not a provider's name", () => {
+    expect(failure(base(members, { ci: { identity: { cloud: { aws: { rules: [{ plan: "r" }] } } } } })).code).toBe("declaration-invalid");
+    expect(failure(base(members, { ci: { identity: { cloud: { oci: { rules: [] } } } } })).code).toBe("declaration-invalid");
+    expect(failure(base(members, { ci: { identity: { cloud: { gcp: { provider: "forge", rules: [{ plan: "p", apply: "a" }] } } } } })).code).toBe("declaration-invalid");
+  });
+});
+
+describe("ci.prEnvironment (#4298)", () => {
+  const members = [{ name: "api", dir: "api", kind: "chant" }];
+
+  test("is read with its template and a 72h TTL by default", () => {
+    expect(parse(base(members, { ci: { prEnvironment: { template: "staging" } } })).ci?.prEnvironment).toEqual({ template: "staging", ttl: "72h" });
+    expect(parse(base(members, { ci: { prEnvironment: { template: "staging", ttl: "7d" } } })).ci?.prEnvironment).toEqual({ template: "staging", ttl: "7d" });
+  });
+
+  test("a block with no template, or a TTL in another form, is declaration-invalid", () => {
+    expect(failure(base(members, { ci: { prEnvironment: {} } })).code).toBe("declaration-invalid");
+    expect(failure(base(members, { ci: { prEnvironment: { template: "staging", ttl: "1w" } } })).code).toBe("declaration-invalid");
+  });
+});