@intentius/chant 0.124.41 → 0.124.42

package/src/pr-requires.test.ts

@@ -0,0 +1,184 @@
+/**
+ * The requires checks of an apply before merge (#4301, ws-106): the four
+ * PrForge methods on GitHub, Forgejo and GitLab, driven through a recording
+ * fake forge, and checkPrRequires over them.
+ */
+
+import { describe, expect, test } from "vitest";
+import { forgejoForge, githubForge, gitlabForge, type ForgeFetch, type PrForge } from "./pr-forge";
+import { checkPrRequires, PR_APPLY_REQUIRES, unmetRequires } from "./pr-requires";
+
+/** A fake forge: `routes` maps `METHOD path-without-query` to a body, a status, or a function of the query. */
+function fakeFetch(routes: Record<string, unknown | ((q: URLSearchParams) => unknown)>): ForgeFetch {
+  return async (url, init) => {
+    const u = new URL(url);
+    let found = routes[`${init.method} ${u.pathname}`];
+    if (typeof found === "function") found = (found as (q: URLSearchParams) => unknown)(u.searchParams);
+    if (found === undefined) return { ok: false, status: 404, text: async () => '{"message":"Not Found"}' };
+    if (typeof found === "number") return { ok: false, status: found, text: async () => "" };
+    return { ok: true, status: 200, text: async () => JSON.stringify(found) };
+  };
+}
+
+const HEAD = "a".repeat(40);
+const TIP = "b".repeat(40);
+const OTHER = "c".repeat(40);
+
+describe("github", () => {
+  const repo = "/repos/acme/infra";
+  const pull = (over: Record<string, unknown> = {}) => ({ number: 7, state: "open", user: { login: "alice" }, head: { ref: "f", sha: HEAD }, base: { ref: "main" }, mergeable: true, mergeable_state: "clean", ...over });
+  const forge = (routes: Record<string, unknown>) =>
+    githubForge({ apiBase: "https://api.github.com", repo: "acme/infra", token: "t", fetch: fakeFetch({ [`GET ${repo}/pulls/7`]: pull(), [`GET ${repo}/pulls/7/commits`]: [{ author: { login: "alice" }, committer: { login: "alice" } }], ...routes }) });
+
+  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" });
+  });
+
+  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" });
+  });
+
+  test("every check fails when the forge's head is another commit", async () => {
+    const f = forge({ [`GET ${repo}/pulls/7`]: pull({ head: { ref: "f", sha: OTHER } }) });
+    const r = await f.prMergeable!(7, HEAD);
+    expect(r.passed).toBe(false);
+    expect(r.reason).toContain("head is cccccccc, not aaaaaaaa");
+  });
+
+  test("mergeable: conflicts and branch protection refuse, an unknown answer is pending", async () => {
+    expect((await forge({}).prMergeable!(7, HEAD)).passed).toBe(true);
+    expect((await forge({ [`GET ${repo}/pulls/7`]: pull({ mergeable: false, mergeable_state: "dirty" }) }).prMergeable!(7, HEAD)).reason).toContain("conflicts with main");
+    expect((await forge({ [`GET ${repo}/pulls/7`]: pull({ mergeable_state: "blocked" }) }).prMergeable!(7, HEAD)).reason).toContain("branch protection");
+    expect(await forge({ [`GET ${repo}/pulls/7`]: pull({ mergeable: null }) }).prMergeable!(7, HEAD)).toMatchObject({ passed: false, pending: true });
+  });
+
+  test("undiverged: reads behind_by from the compare of the base branch with the head", async () => {
+    expect((await forge({ [`GET ${repo}/compare/main...${HEAD}`]: { behind_by: 0 } }).prUndiverged!(7, HEAD)).passed).toBe(true);
+    expect((await forge({ [`GET ${repo}/compare/main...${HEAD}`]: { behind_by: 2 } }).prUndiverged!(7, HEAD)).reason).toBe("aaaaaaaa is 2 commits behind main");
+  });
+
+  test("checks: statuses and check runs, the apply's own left out", async () => {
+    const statuses = (state: string) => ({ statuses: [{ context: "ci/test", state }, { context: "chant/apply", state: "failure" }] });
+    const runs = (conclusion: string | null, status = "completed") => ({ check_runs: [{ name: "lint", status, conclusion }] });
+    const f = (state: string, run: unknown) => forge({ [`GET ${repo}/commits/${HEAD}/status`]: statuses(state), [`GET ${repo}/commits/${HEAD}/check-runs`]: run });
+    expect(await f("success", runs("success")).prChecksPassed!(7, HEAD, ["chant/apply"])).toEqual({ passed: true, reason: "2 checks passed on aaaaaaaa" });
+    expect((await f("success", runs("success")).prChecksPassed!(7, HEAD)).reason).toBe("chant/apply failed on aaaaaaaa");
+    expect(await f("pending", runs("success")).prChecksPassed!(7, HEAD, ["chant/apply"])).toMatchObject({ passed: false, pending: true });
+    expect((await f("success", runs(null, "in_progress")).prChecksPassed!(7, HEAD, ["chant/apply"])).pending).toBe(true);
+    expect((await f("success", runs("failure")).prChecksPassed!(7, HEAD, ["chant/apply"])).reason).toBe("lint failed on aaaaaaaa");
+  });
+
+  test("checks: nothing reported is pending", async () => {
+    const f = forge({ [`GET ${repo}/commits/${HEAD}/status`]: { statuses: [] }, [`GET ${repo}/commits/${HEAD}/check-runs`]: { check_runs: [] } });
+    expect(await f.prChecksPassed!(7, HEAD)).toMatchObject({ passed: false, pending: true });
+  });
+});
+
+describe("forgejo", () => {
+  const repo = "/api/v1/repos/acme/infra";
+  const pull = (over: Record<string, unknown> = {}) => ({ number: 4, user: { login: "alice" }, head: { ref: "f", sha: HEAD }, base: { ref: "main" }, mergeable: true, merge_base: TIP, ...over });
+  const forge = (routes: Record<string, unknown>) =>
+    forgejoForge({ apiBase: "https://code.example/api/v1", repo: "acme/infra", host: "code.example", token: "t", fetch: fakeFetch({ [`GET ${repo}/pulls/4`]: pull(), [`GET ${repo}/pulls/4/commits`]: [], [`GET ${repo}/branches/main`]: { commit: { id: TIP } }, ...routes }) });
+
+  test("approved: Forgejo's REQUEST_CHANGES state refuses", async () => {
+    const f = forge({ [`GET ${repo}/pulls/4/reviews`]: [{ user: { login: "bob" }, state: "APPROVED", commit_id: HEAD }, { user: { login: "dave" }, state: "REQUEST_CHANGES" }] });
+    expect((await f.prApproved!(4, HEAD)).reason).toBe("dave asked for changes");
+  });
+
+  test("undiverged: the pull request's merge base is the base branch's tip", async () => {
+    expect((await forge({}).prUndiverged!(4, HEAD)).passed).toBe(true);
+    expect((await forge({ [`GET ${repo}/pulls/4`]: pull({ merge_base: OTHER }) }).prUndiverged!(4, HEAD)).reason).toBe("aaaaaaaa does not contain main at bbbbbbbb");
+  });
+
+  test("mergeable: no branch protection reading, and checks from the combined status alone", async () => {
+    expect((await forge({ [`GET ${repo}/pulls/4`]: pull({ mergeable_state: "blocked" }) }).prMergeable!(4, HEAD)).passed).toBe(true);
+    const f = forge({ [`GET ${repo}/commits/${HEAD}/status`]: { statuses: [{ context: "ci/test", status: "success" }] } });
+    expect(await f.prChecksPassed!(4, HEAD)).toEqual({ passed: true, reason: "1 check passed on aaaaaaaa" });
+  });
+});
+
+describe("gitlab", () => {
+  const project = "/api/v4/projects/9";
+  const mr = (over: Record<string, unknown> = {}) => ({ iid: 3, sha: HEAD, author: { username: "alice" }, target_branch: "main", detailed_merge_status: "mergeable", diverged_commits_count: 0, ...over });
+  const note = (who: string, body: string, at: string) => ({ system: true, author: { username: who }, body, created_at: at });
+  const forge = (routes: Record<string, unknown>) =>
+    gitlabForge({
+      apiBase: "https://gitlab.example/api/v4",
+      project: "9",
+      token: "t",
+      host: "gitlab.example",
+      fetch: fakeFetch({
+        [`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" }],
+        ...routes,
+      }),
+    });
+
+  test("approved: an approval after the latest push, not the token user's or the author's", async () => {
+    const f = forge({
+      [`GET ${project}/merge_requests/3/notes`]: [
+        note("erin", "approved this merge request", "2026-10-01T09:00:00Z"),
+        note("chant-bot", "approved this merge request", "2026-10-01T11:00:00Z"),
+        note("alice", "approved this merge request", "2026-10-01T11:00:00Z"),
+      ],
+    });
+    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" });
+    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");
+  });
+
+  test("mergeable and undiverged read the merge request", async () => {
+    expect((await forge({}).prMergeable!(3, HEAD)).passed).toBe(true);
+    expect(await forge({ [`GET ${project}/merge_requests/3`]: mr({ detailed_merge_status: "checking" }) }).prMergeable!(3, HEAD)).toMatchObject({ passed: false, pending: true });
+    expect((await forge({ [`GET ${project}/merge_requests/3`]: mr({ has_conflicts: true, detailed_merge_status: "conflict" }) }).prMergeable!(3, HEAD)).reason).toContain("conflicts");
+    expect((await forge({}).prUndiverged!(3, HEAD)).passed).toBe(true);
+    expect((await forge({ [`GET ${project}/merge_requests/3`]: mr({ diverged_commits_count: 1 }) }).prUndiverged!(3, HEAD)).reason).toBe("aaaaaaaa is 1 commit behind main");
+  });
+
+  test("checks: each name's newest status, a job allowed to fail holding nothing back", async () => {
+    const f = forge({
+      [`GET ${project}/repository/commits/${HEAD}/statuses`]: [
+        { id: 1, name: "test", status: "failed" },
+        { id: 2, name: "test", status: "success" },
+        { id: 3, name: "flaky", status: "failed", allow_failure: true },
+        { id: 4, name: "apply", status: "running" },
+      ],
+    });
+    expect(await f.prChecksPassed!(3, HEAD, ["apply"])).toEqual({ passed: true, reason: "2 checks passed on aaaaaaaa" });
+    expect((await f.prChecksPassed!(3, HEAD)).pending).toBe(true);
+  });
+});
+
+describe("checkPrRequires", () => {
+  const ok = { passed: true, reason: "ok" };
+  test("asks each check once in order, and a pending one again until it settles", async () => {
+    let reads = 0;
+    const forge = {
+      kind: "github",
+      prApproved: async () => ok,
+      prMergeable: async () => (++reads < 3 ? { passed: false, pending: true, reason: "working it out" } : ok),
+      prUndiverged: async () => ok,
+      prChecksPassed: async (_pr: number, _head: string, ignore?: readonly string[]) => ({ passed: true, reason: `ignored ${ignore?.join(",")}` }),
+    } as unknown as PrForge;
+    const out = await checkPrRequires(forge, 7, HEAD, { ignore: ["chant/apply"], wait: async () => {} });
+    expect(out.map((o) => o.name)).toEqual([...PR_APPLY_REQUIRES]);
+    expect(reads).toBe(3);
+    expect(out[3]!.reason).toBe("ignored chant/apply");
+    expect(unmetRequires(out)).toBeNull();
+  });
+
+  test("a client without a method, or a call that throws, is unmet", async () => {
+    const forge = { kind: "gitlab", prApproved: async () => { throw new Error("401"); } } as unknown as PrForge;
+    const out = await checkPrRequires(forge, 3, HEAD, { reads: 1 });
+    expect(out.every((o) => !o.passed)).toBe(true);
+    expect(unmetRequires(out)).toBe("approved: could not ask gitlab: 401; mergeable: this gitlab client cannot say; undiverged: this gitlab client cannot say; checks: this gitlab client cannot say");
+  });
+});

package/src/pr-requires.ts

@@ -0,0 +1,79 @@
+/**
+ * The requires checks of an apply before merge (#4301, ws-106): the pull
+ * request is approved, mergeable, undiverged and its checks passed, each
+ * asked of the forge through its {@link PrForge} method. All four must pass.
+ *
+ * The checks are terragucci's `apply.requires` (comment-apply.ts:781-860 at
+ * INTENTIUS/terragucci e6cb431), with no setting to drop one. A check the
+ * forge has not settled, such as GitHub working out whether a pull request
+ * can merge, is asked again a few times before it counts as unmet.
+ *
+ * Like ./pr-forge.ts this imports nothing beyond it, so a product bundles it
+ * without the TypeScript toolchain.
+ */
+import type { 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;
+
+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;
+}
+
+export interface PrRequiresOptions {
+  /** Status names the `checks` require leaves out: the apply's own. */
+  ignore?: readonly string[];
+  /** How many times a pending check is asked in all. Default 5. */
+  reads?: number;
+  /** The wait between reads. Default 3 seconds. */
+  wait?: (ms: number) => Promise<void>;
+}
+
+const READS = 5;
+const WAIT_MS = 3000;
+
+/**
+ * Ask `forge` each of the four checks for pull request `pr` at `head`. A
+ * forge client without a method, or a call that throws, gives an unmet
+ * check with the reason, so nothing applies on a check nobody made.
+ */
+export async function checkPrRequires(forge: PrForge, pr: number, head: string, opts: PrRequiresOptions = {}): Promise<PrRequireOutcome[]> {
+  const wait = opts.wait ?? ((ms: number) => new Promise<void>((r) => setTimeout(r, ms)));
+  const reads = Math.max(1, opts.reads ?? READS);
+  const ask: Record<PrApplyRequire, (() => Promise<PrRequireResult>) | undefined> = {
+    approved: forge.prApproved ? () => forge.prApproved!(pr, head) : undefined,
+    mergeable: forge.prMergeable ? () => forge.prMergeable!(pr, head) : undefined,
+    undiverged: forge.prUndiverged ? () => forge.prUndiverged!(pr, head) : undefined,
+    checks: forge.prChecksPassed ? () => forge.prChecksPassed!(pr, head, opts.ignore ?? []) : undefined,
+  };
+  const out: PrRequireOutcome[] = [];
+  for (const name of PR_APPLY_REQUIRES) {
+    const call = ask[name];
+    if (!call) {
+      out.push({ name, passed: false, reason: `this ${forge.kind} client cannot say` });
+      continue;
+    }
+    let result: PrRequireResult;
+    for (let read = 1; ; read++) {
+      try {
+        result = await call();
+      } catch (err) {
+        result = { passed: false, reason: `could not ask ${forge.kind}: ${err instanceof Error ? err.message : String(err)}` };
+      }
+      if (result.passed || !result.pending || read >= reads) break;
+      await wait(WAIT_MS);
+    }
+    out.push({ name, ...result });
+  }
+  return out;
+}
+
+/** The unmet checks as one line, or null when all four passed. */
+export function unmetRequires(outcomes: readonly PrRequireOutcome[]): string | null {
+  const unmet = outcomes.filter((o) => !o.passed);
+  if (unmet.length === 0) return null;
+  return unmet.map((o) => `${o.name}: ${o.reason}`).join("; ");
+}

package/src/review-agent-bundle.test.ts

@@ -0,0 +1,35 @@
+/**
+ * The review agent bundles alone (#4299): a product such as terragucci
+ * imports `@intentius/chant/op/activities/review-agent` into one bundled
+ * file, so it must not reach predict-behaviour's estate code. This bundles
+ * the module and reads esbuild's list of what went in.
+ */
+
+import { join } from "node:path";
+import { build } from "esbuild";
+import { describe, expect, test } from "vitest";
+import { REPO } from "./workspace/__fixtures__/contract-repo";
+
+describe("the review-agent bundle", () => {
+  test("holds the review agent, the note it posts through and nothing else", async () => {
+    const result = await build({
+      entryPoints: [join(REPO, "packages", "core", "src", "op", "activities", "review-agent.ts")],
+      bundle: true,
+      platform: "node",
+      format: "esm",
+      write: false,
+      metafile: true,
+      outdir: "out",
+      logLevel: "silent",
+    });
+    expect(Object.keys(result.metafile.inputs).map((i) => i.replace(/^.*?packages\//, "packages/")).sort()).toEqual([
+      "packages/core/src/op/activities/forge-pull-request.ts",
+      "packages/core/src/op/activities/gh-host.ts",
+      "packages/core/src/op/activities/pr-refs.ts",
+      "packages/core/src/op/activities/reconcile.ts",
+      "packages/core/src/op/activities/review-agent.ts",
+      "packages/core/src/pr-forge.ts",
+    ]);
+    expect(result.outputFiles.reduce((n, f) => n + f.contents.byteLength, 0)).toBeLessThan(96 * 1024);
+  });
+});

package/src/stage-hooks-bundle.test.ts

@@ -0,0 +1,38 @@
+/**
+ * The stage-hook runner bundles alone (#4288): a product that runs
+ * `ci.hooks` around its own stages imports
+ * `@intentius/chant/op/stage-hooks` into one bundled file, without the wave
+ * loop, the gate or the ledger. This bundles the module and reads esbuild's
+ * list of what went in.
+ */
+
+import { join } from "node:path";
+import { build } from "esbuild";
+import { describe, expect, test } from "vitest";
+import { REPO } from "./workspace/__fixtures__/contract-repo";
+
+describe("the stage-hooks bundle", () => {
+  test("holds the hook runner and the Op waves spec, and no wave loop, gate or ledger", async () => {
+    const result = await build({
+      entryPoints: [join(REPO, "packages", "core", "src", "op", "stage-hooks.ts")],
+      bundle: true,
+      platform: "node",
+      format: "esm",
+      write: false,
+      metafile: true,
+      outdir: "out",
+      logLevel: "silent",
+    });
+    expect(Object.keys(result.metafile.inputs).map((i) => i.replace(/^.*?packages\//, "packages/")).sort()).toEqual([
+      "packages/core/src/lifecycle/gate-seal.ts",
+      "packages/core/src/notify-verify.ts",
+      "packages/core/src/notify.ts",
+      "packages/core/src/op/gate-point.ts",
+      "packages/core/src/op/gate-quorum.ts",
+      "packages/core/src/op/op-waves.ts",
+      "packages/core/src/op/stage-hooks.ts",
+      "packages/core/src/wave-layout.ts",
+    ]);
+    expect(result.outputFiles.reduce((n, f) => n + f.contents.byteLength, 0)).toBeLessThan(48 * 1024);
+  });
+});

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

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

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

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

package/src/workspace/ci-init.ts

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

package/src/workspace/ci-run.ts

@@ -1040,13 +1040,14 @@ export function ciLoopOptions(args: CommandContext["args"]): PrLoopPipelineOptio
     ...(args.prBuildCommand ? { buildCommand: args.prBuildCommand } : {}),
     ...(args.waveGate ? { waveGate: args.waveGate } : {}),
     ...(args.requireReview === true ? { requireReview: true } : {}),
+    ...(args.applyBeforeMerge ? { applyBeforeMerge: true } : {}),
   };
 }
 
 const USAGE =
   "chant ci run plan|record|apply --env <env> --base <sha> [--pr <n>] [--commit <sha>] [--forge github|gitlab|forgejo] " +
   "[--gate <name>] [--wave-gate <name>] [--wave <k>] [--branch <name>] [--events-json] [--report-url <url>] [--run-index-limit <n>] [--image <image>] [--before-script <line>]... " +
-  "[--pr-build] [--pr-build-command <line>] [--require-review] [--no-status] [--status-url <url template>] " +
+  "[--pr-build] [--pr-build-command <line>] [--require-review] [--apply-before-merge] [--no-status] [--status-url <url template>] " +
   "[--chant <command>] [--pass-env <NAME>]... [--secrets <file>] [--key <runner key.pem>] [-o <dir>] [--in-place | --local] [--no-push] [--verbose] | chant ci run --at <sha> | chant ci run --setup-key [--trust [--principal <name>]] [--state <dir>] [--branch <name>]";
 
 const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;

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

@@ -0,0 +1,23 @@
+/**
+ * `ci.workflow` read at base (#4301, ws-106), as `ci.locks` is
+ * (./ci-locks.ts): the target branch's tip, so a pull request that sets
+ * `apply-before-merge` in its own copy of the declaration gets nothing from it.
+ */
+import type { CiWorkflow } from "./declaration";
+import { workflowOf } from "./ci-workflow";
+import { memberAtCwd } from "./security";
+import { scopeSource } from "./write-scope";
+
+/**
+ * The workflow the member holding `cwd` follows, or `member` when given:
+ * its own `ci.workflow`, else the top level's, read at `at` when given, else
+ * at base, else from the working tree. Null outside a workspace and when
+ * neither sets one.
+ */
+export function ciWorkflowAt(cwd: string, at?: string, member?: string): CiWorkflow | null {
+  const source = scopeSource(cwd, at);
+  const d = source.declaration;
+  if (!d) return null;
+  const name = member ?? memberAtCwd(source, cwd);
+  return workflowOf(d, d.members.find((m) => m.name === name) ?? null);
+}

package/src/workspace/ci-workflow.ts

@@ -7,6 +7,8 @@
  * from a green commit and promoted through the member's environments, gated
  * in the last (4.2). `trunk-curated+apply-on-merge` is the same, and each
  * newest green commit is also applied (section 5, step 9).
+ * `apply-before-merge` (#4301, ws-106) is `trunk-curated`, and a person may
+ * also apply an open pull request's plan from its head before it merges.
  *
  * A workflow requires no security group: those are opt-in on their own
  * (./security.ts). `chant workspace check` reports what a member under a
@@ -19,13 +21,22 @@ import type { CiWorkflow, Declaration, Member } from "./declaration";
 /** The marker a component stub `chant ci init` writes carries until someone fills it in. WSP151 reports a member whose only components carry it. */
 export const STUB_MARKER = "TODO(chant ci init)";
 
-export const CI_WORKFLOWS = ["trunk-curated", "trunk-curated+apply-on-merge"] as const satisfies readonly CiWorkflow[];
+export const CI_WORKFLOWS = ["trunk-curated", "trunk-curated+apply-on-merge", "apply-before-merge"] as const satisfies readonly CiWorkflow[];
 
 /** Whether `workflow` turns the apply on merge back on. */
 export function appliesOnMerge(workflow: CiWorkflow): boolean {
   return workflow === "trunk-curated+apply-on-merge";
 }
 
+/**
+ * Whether `workflow` lets an open pull request's plan apply from its head
+ * before it merges (#4301, ws-106). Only `apply-before-merge` does, so with
+ * no workflow or either trunk-curated one nothing applies before merge.
+ */
+export function appliesBeforeMerge(workflow: CiWorkflow | null): boolean {
+  return workflow === "apply-before-merge";
+}
+
 /** The workflow `member` follows: its own `ci.workflow`, else the top level's, else null. */
 export function workflowOf(declaration: Pick<Declaration, "ci">, member: Pick<Member, "ciWorkflow"> | null): CiWorkflow | null {
   return member?.ciWorkflow ?? declaration.ci?.workflow ?? null;
@@ -56,7 +67,7 @@ export const CI_WORKFLOW_REQUIREMENTS = [
   { code: "ci-workflow-no-environments", requirement: "the member's `chant.config.ts` declares `environments`, the promotion order", fix: "`environments` in `chant.config.ts`", perMember: true },
   { code: "ci-workflow-ungated-env", requirement: "each component has a gate, so a promote to the last environment waits on an approval", fix: "a `gate()` step in the component", perMember: true },
   { code: "ci-workflow-pipeline-missing", requirement: "a pipeline file runs the plan job, the record job (`ci run record`) and `chant ci tick`", fix: "`chant build --components --generate <forge> --pr-loop` and `chant ci workflow`", perMember: false },
-  { code: "ci-workflow-pipeline-differs", requirement: "the pipeline matches the workflow: no apply job under `trunk-curated`, and under `trunk-curated+apply-on-merge` an apply job that applies the newest green commit, not each merge", fix: "regenerate the pull-request pipeline, with `--apply-on-merge` only under apply on merge", perMember: false },
+  { code: "ci-workflow-pipeline-differs", requirement: "the pipeline matches the workflow: no apply job under `trunk-curated`, and under `trunk-curated+apply-on-merge` an apply job that applies the newest green commit, not each merge; a job that applies before merge only, and always, under `apply-before-merge`", fix: "regenerate the pull-request pipeline, with `--apply-on-merge` only under apply on merge and `--apply-before-merge` only under apply before merge", perMember: false },
   { code: "ci-workflow-publish-missing", requirement: "a pipeline file runs `chant release publish`", fix: "`chant release workflow`", perMember: false },
 ] as const satisfies readonly CiWorkflowRequirement[];
 

package/src/workspace/declaration.schema.json

@@ -1718,8 +1718,8 @@
       "additionalProperties": false
     },
     "ciWorkflow": {
-      "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."
+      "enum": ["trunk-curated", "trunk-curated+apply-on-merge", "apply-before-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. apply-before-merge (#4301, ws-106): the same as trunk-curated, and a person may also apply an open pull request's plan from its head under its gate, once it is approved, mergeable, undiverged and its checks passed (chant components pr-apply --before-merge); added by chant 0.124.42, so a declaration that uses it sets minReader to 0.124.42 or newer. 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",

package/src/workspace/declaration.ts

@@ -258,10 +258,13 @@ export type CiSource = "checks" | "runs";
  * A prescribed delivery workflow (#4168 section 7). `trunk-curated`: a merge
  * records the plan and deploys nothing, and releases are cut from green
  * commits and promoted through the environments. `trunk-curated+apply-on-merge`
- * adds the apply on merge as an opt-in. `chant workspace check` reports what a
- * member under one still lacks (./checks/ci-workflow.ts, WSP151).
+ * adds the apply on merge as an opt-in. `apply-before-merge` (#4301, ws-106)
+ * is `trunk-curated` with an open pull request's plan applied from its head
+ * on request, once it is approved, mergeable, undiverged and green. `chant
+ * workspace check` reports what a member under one still lacks
+ * (./checks/ci-workflow.ts, WSP151).
  */
-export type CiWorkflow = "trunk-curated" | "trunk-curated+apply-on-merge";
+export type CiWorkflow = "trunk-curated" | "trunk-curated+apply-on-merge" | "apply-before-merge";
 
 /**
  * When a pull request takes its target locks (#4293, ../lifecycle/target-lock.ts).

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

@@ -8,7 +8,7 @@
   "properties": {
     "$schema": { "const": "https://intentius.io/chant/schemas/workspace/pr-report/v1/pr-report.schema.json" },
     "contract": { "const": 1 },
-    "stage": { "enum": ["plan", "apply", "record"], "description": "plan: on the pull request. record (#4168, chant 0.124.33 and newer): on merge, the default; it plans the merged commit and writes the merge record, applying nothing. apply: on merge with --apply-on-merge." },
+    "stage": { "enum": ["plan", "apply", "record"], "description": "plan: on the pull request. record (#4168, chant 0.124.33 and newer): on merge, the default; it plans the merged commit and writes the merge record, applying nothing. apply: on merge with --apply-on-merge, or (#4301, chant 0.124.42 and newer) at an open pull request's head with --before-merge, when beforeMerge is set." },
     "pr": {
       "type": ["integer", "null"],
       "minimum": 1,
@@ -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", "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."
+      "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", "requires-unmet", "before-merge-off"],
+      "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. With pr-apply --before-merge (#4301, chant 0.124.42 and newer): requires-unmet, the pull request is not approved, mergeable, undiverged or green, and beforeMerge says which; before-merge-off, the declaration at base does not set ci.workflow to apply-before-merge for the member. Nothing applied."
     },
     "message": { "type": "string", "description": "The refusal or failure as printed." },
     "resumed": {
@@ -207,6 +207,26 @@
         }
       }
     },
+    "beforeMerge": {
+      "type": "object",
+      "required": ["requires"],
+      "description": "Added within contract version 1 by #4301, written by chant 0.124.42 and newer. pr-apply --before-merge: the requires checks the forge answered before anything planned (ws-106). Absent on every other stage.",
+      "properties": {
+        "requires": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["name", "passed", "reason"],
+            "properties": {
+              "name": { "enum": ["approved", "mergeable", "undiverged", "checks"] },
+              "passed": { "type": "boolean" },
+              "pending": { "type": "boolean", "description": "The forge had not settled it when asked: a check still ran, or it had not worked out whether the pull request merges." },
+              "reason": { "type": "string" }
+            }
+          }
+        }
+      }
+    },
     "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.",

package/src/workspace/reason-codes.ts

@@ -255,7 +255,7 @@ export const REASONS = {
   "ci-workflow-no-environments": "Under ci.workflow, a member's chant.config.ts declares no environments, so a release has nowhere to be promoted to.",
   "ci-workflow-ungated-env": "Under ci.workflow, a component has no gate, so a promote to the last environment waits on no approval.",
   "ci-workflow-pipeline-missing": "Under ci.workflow, no pipeline file runs the plan job, the merge job or chant ci tick.",
-  "ci-workflow-pipeline-differs": "Under ci.workflow, the merge job does not match the workflow: it applies under trunk-curated, or records under trunk-curated+apply-on-merge.",
+  "ci-workflow-pipeline-differs": "Under ci.workflow, the pipeline does not match the workflow: it applies on merge under trunk-curated, records under trunk-curated+apply-on-merge, or applies before merge, or fails to, against apply-before-merge.",
   "ci-workflow-publish-missing": "Under ci.workflow, no pipeline file runs chant release publish.",
   // A box that holds a credential (check, #2726). Each is also a WSP finding.
   "box-credential-declared": "A file in a box member's directory carries a literal secret: a credential's shape, or a literal where a credential goes. A variable or secret-manager reference is not one.",