@intentius/chant 0.124.32 → 0.124.33

package/src/cli/handlers/pr-deploy-inputs.test.ts

@@ -0,0 +1,209 @@
+/**
+ * #4155: a pull request's approval binds the files a step without a `plan`
+ * deploys from. A chart changed after approval, or a function's sources
+ * beside a planning step, moves the digest and pr-apply exits 3. A build
+ * whose output differs every time does not.
+ */
+
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+import type { DriverComponent } from "../../components/driver";
+import type { DeployContext } from "../../components/capability";
+import type { ParsedArgs } from "../registry";
+
+const HEAD = "a".repeat(40);
+const BASE = "b".repeat(40);
+
+vi.mock("../../components/changed-files", () => ({
+  resolveCommit: async () => HEAD,
+  resolveMergeBase: async () => BASE,
+}));
+
+vi.mock("../../config", async () => {
+  const actual = await vi.importActual<typeof import("../../config")>("../../config");
+  return { ...actual, loadChantConfig: async () => ({ config: {} }) };
+});
+
+vi.mock("./fan-out", () => ({
+  resolveChangedUnits: async () => ({ units: { changed: [ESTATE[0]!.name], indeterminate: [] } }),
+}));
+
+vi.mock("../../lifecycle/gate-change-set", () => ({
+  storeGateChangeSet: async () => ({ written: false }),
+  readGraphIds: async () => ({ ids: [] }),
+  setGraphIdReader: () => {},
+  gateGraphReader: () => async () => ({ ids: [] }),
+}));
+vi.mock("../../lifecycle/git", async () => {
+  const actual = await vi.importActual<typeof import("../../lifecycle/git")>("../../lifecycle/git");
+  return { ...actual, pushLifecycleReport: async () => { throw new Error("pr-deploy-inputs.test must not push chant/lifecycle"); } };
+});
+
+vi.mock("./run", () => ({
+  GATED_EXIT_CODE: 3,
+  autoReleaseRun: (id: string) => ({ runId: id, runOrigin: { forge: "local" } }),
+  recordAutoReleasesForRun: async () => [],
+}));
+
+let gateLedger: ReturnType<typeof import("../../op/gate").memoryGateLedgerPort>;
+vi.mock("../../op/gate", async () => {
+  const actual = await vi.importActual<typeof import("../../op/gate")>("../../op/gate");
+  return { ...actual, gitGateLedgerPort: () => gateLedger, gateIsSealed: async () => false };
+});
+
+/** The components under test; each case sets its own. */
+let ESTATE: DriverComponent[] = [];
+
+vi.mock("../../components/fan-out-support", async () => {
+  const { CapabilityRegistry } = await import("../../components/capability");
+  const { planFanOut } = await import("../../components/fan-out");
+  const { computePlanDigest } = await import("../../lifecycle/plan-digest");
+  const registry = new CapabilityRegistry();
+  // A planning step, as cfn-deploy is.
+  registry.register({
+    kind: "fake-root",
+    async plan(_ctx: DeployContext, input: { root: string }) {
+      const planDigest = computePlanDigest("fake-root", { root: input.root });
+      return {
+        member: input.root,
+        planDigest,
+        artifact: { planDigest },
+        changeSet: { member: { member: input.root, lexicon: "aws", planner: "cfn", status: "planned", planDigest, holes: [] }, entries: [] },
+      };
+    },
+    async run() {
+      return { outputs: {} };
+    },
+  } as never);
+  // Steps with no plan, under the kinds whose fields name what they deploy.
+  for (const kind of ["helm-upgrade", "lambda-deploy", "shell"]) {
+    registry.register({ kind, async run() { return { outputs: {} }; } } as never);
+  }
+  // A build that is not reproducible: a new uri every run.
+  registry.register({ kind: "zip-package", async run() { return { outputs: { uri: `s3://bundles/${Math.random()}` } }; } } as never);
+  return {
+    fanOutRegistry: async () => registry,
+    deriveFanOut: async () => ({
+      success: true,
+      components: ESTATE,
+      plan: planFanOut({ components: ESTATE, changed: [ESTATE[0]!.name] }),
+      signal: { changed: [ESTATE[0]!.name], indeterminate: [], unclaimed: [] },
+    }),
+  };
+});
+
+const { memoryGateLedgerPort } = await import("../../op/gate");
+const { runComponentsPrApply, runComponentsPrPlan } = await import("./pr");
+
+let dir: string;
+let project: string;
+
+const ctx = (a: Partial<ParsedArgs>) =>
+  ({ args: { command: "components", path: "pr-apply", format: "", fix: false, watch: false, verbose: false, help: false, live: false, base: "main", env: "prod", output: dir, ...a } as ParsedArgs, plugins: [] }) as never;
+
+beforeEach(async () => {
+  dir = await mkdtemp(join(tmpdir(), "pr-inputs-out-"));
+  project = await mkdtemp(join(tmpdir(), "pr-inputs-project-"));
+  gateLedger = memoryGateLedgerPort();
+  // The steps read their paths from the member's directory, which is the working directory.
+  vi.spyOn(process, "cwd").mockReturnValue(project);
+  vi.spyOn(process.stdout, "write").mockImplementation(() => true);
+  vi.spyOn(console, "error").mockImplementation(() => {});
+  vi.spyOn(console, "log").mockImplementation(() => {});
+});
+
+afterEach(async () => {
+  vi.restoreAllMocks();
+  await rm(dir, { recursive: true, force: true });
+  await rm(project, { recursive: true, force: true });
+});
+
+/** Plan pull request 12 and approve the digest it printed, as a reviewer would. */
+async function planAndApprove(): Promise<string> {
+  expect(await runComponentsPrPlan(ctx({ pr: 12 }))).toBe(0);
+  const digest = JSON.parse(await readFile(join(dir, "pr-plan.json"), "utf8")).digest as string;
+  gateLedger = memoryGateLedgerPort({
+    resolutions: [{ version: 1, kind: "resolution", op: "pr-12", gate: "pr-apply", resolvedBy: "github:alice", timestamp: new Date().toISOString(), planDigest: digest }],
+  });
+  return digest;
+}
+
+async function write(path: string, content: string): Promise<void> {
+  await mkdir(join(project, path, ".."), { recursive: true });
+  await writeFile(join(project, path), content);
+}
+
+describe("a Helm chart changed after approval (#4155)", () => {
+  beforeEach(async () => {
+    ESTATE = [{ name: "web", dependsOn: [], deploy: [{ phase: "Deploy", steps: [{ kind: "helm-upgrade", release: "web", chart: "chart", values: ["values-prod.yaml"] }] }] }];
+    await write("chart/Chart.yaml", "name: web\nversion: 1.0.0\n");
+    await write("chart/templates/deployment.yaml", "replicas: 2\n");
+    await write("values-prod.yaml", "image: web\n");
+  });
+
+  test("applies under the approval when nothing changed", async () => {
+    await planAndApprove();
+    expect(await runComponentsPrApply(ctx({ pr: 12 }))).toBe(0);
+  });
+
+  test("a file in the chart changed: pr-apply exits 3 and applies nothing", async () => {
+    await planAndApprove();
+    await write("chart/templates/deployment.yaml", "replicas: 20\n");
+    expect(await runComponentsPrApply(ctx({ pr: 12 }))).toBe(3);
+    const report = JSON.parse(await readFile(join(dir, "pr-apply.json"), "utf8"));
+    expect(report.status).not.toBe("applied");
+  });
+
+  test("a file added to the chart, or a changed values file, does the same", async () => {
+    await planAndApprove();
+    await write("chart/templates/service.yaml", "port: 80\n");
+    expect(await runComponentsPrApply(ctx({ pr: 12 }))).toBe(3);
+    await planAndApprove();
+    await write("values-prod.yaml", "image: other\n");
+    expect(await runComponentsPrApply(ctx({ pr: 12 }))).toBe(3);
+  });
+});
+
+describe("a function's sources beside a planning step (#4155)", () => {
+  beforeEach(async () => {
+    ESTATE = [{
+      name: "api",
+      dependsOn: [],
+      deploy: [
+        { phase: "Build", steps: [{ kind: "zip-package", source: "fn" }] },
+        { phase: "Deploy", steps: [{ kind: "fake-root", root: "api-stack" }, { kind: "lambda-deploy", functionName: "api", codeRef: "@Build.uri", version: "1" }] },
+      ],
+    }];
+    await write("fn/index.js", "export const handler = () => 1;\n");
+    await write("fn/package-lock.json", "{}\n");
+  });
+
+  test("the plan has a member for the component's other steps", async () => {
+    await planAndApprove();
+    const plan = JSON.parse(await readFile(join(dir, "pr-plan.json"), "utf8"));
+    expect(JSON.stringify(plan)).toContain("api#inputs");
+  });
+
+  test("a changed source moves the digest: pr-apply exits 3", async () => {
+    await planAndApprove();
+    await write("fn/index.js", "export const handler = () => 2;\n");
+    expect(await runComponentsPrApply(ctx({ pr: 12 }))).toBe(3);
+  });
+
+  test("an unchanged rebuild whose output differs every run still applies under the approval", async () => {
+    await planAndApprove();
+    expect(await runComponentsPrApply(ctx({ pr: 12 }))).toBe(0);
+  });
+});
+
+describe("a step chant can't bind (#4155)", () => {
+  test("is a hole on the plan, named unbound, and the plan still applies once approved", async () => {
+    ESTATE = [{ name: "ops", dependsOn: [], deploy: [{ phase: "Deploy", steps: [{ kind: "shell", cmd: "./deploy.sh", reason: "t" }] }] }];
+    await planAndApprove();
+    const plan = JSON.parse(await readFile(join(dir, "pr-plan.json"), "utf8"));
+    expect(JSON.stringify(plan)).toMatch(/unbound: a shell step runs content chant can't name/);
+    expect(await runComponentsPrApply(ctx({ pr: 12 }))).toBe(0);
+  });
+});

package/src/cli/handlers/pr-record.test.ts

@@ -0,0 +1,201 @@
+/**
+ * `chant components pr-record` (#4168 step 1): the record stage a merge
+ * runs unless apply on merge is opted in. It plans the merged commit,
+ * decides the pull request's gate without writing to the ledger, writes the
+ * merge record and the report, and applies nothing. Git, the change signal,
+ * the derivation and the gate ledger are fakes, as in pr.test.ts.
+ */
+
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+import type { DriverComponent } from "../../components/driver";
+import type { DeployContext } from "../../components/capability";
+import type { ParsedArgs } from "../registry";
+import { prStatusState } from "../../pr-loop";
+
+const HEAD = "a".repeat(40);
+const BASE = "b".repeat(40);
+
+vi.mock("../../components/changed-files", () => ({
+  resolveCommit: async () => HEAD,
+  resolveMergeBase: async () => BASE,
+}));
+
+vi.mock("../../config", async () => {
+  const actual = await vi.importActual<typeof import("../../config")>("../../config");
+  return { ...actual, loadChantConfig: async () => ({ config: {} }) };
+});
+
+vi.mock("./fan-out", () => ({
+  resolveChangedUnits: async () => ({ units: { changed: ["net"], indeterminate: [] } }),
+}));
+
+// #4022: pr-apply stores the change set its gate binds on chant/lifecycle and
+// pushes it. These tests run in the chant checkout, so the store is replaced:
+// it must never write or push the real repository's lifecycle branch.
+vi.mock("../../lifecycle/gate-change-set", () => ({
+  storeGateChangeSet: async () => ({ written: false }),
+  readGraphIds: async () => ({ ids: [] }),
+  setGraphIdReader: () => {},
+  gateGraphReader: () => async () => ({ ids: [] }),
+}));
+vi.mock("../../lifecycle/git", async () => {
+  const actual = await vi.importActual<typeof import("../../lifecycle/git")>("../../lifecycle/git");
+  return { ...actual, pushLifecycleReport: async () => { throw new Error("pr.test must not push chant/lifecycle"); } };
+});
+
+// #4168: the record job writes the merge record on chant/lifecycle. Captured here, never written.
+const written: Array<Record<string, unknown>> = [];
+vi.mock("../../lifecycle/merge-record", async () => {
+  const actual = await vi.importActual<typeof import("../../lifecycle/merge-record")>("../../lifecycle/merge-record");
+  return { ...actual, writeMergeRecord: async (r: Record<string, unknown>) => (written.push(r), { commit: null, written: false }) };
+});
+
+vi.mock("./run", () => ({
+  GATED_EXIT_CODE: 3,
+  autoReleaseRun: (id: string) => ({ runId: id, runOrigin: { forge: "local" } }),
+  recordAutoReleasesForRun: async () => [],
+}));
+
+let gateLedger: ReturnType<typeof import("../../op/gate").memoryGateLedgerPort>;
+vi.mock("../../op/gate", async () => {
+  const actual = await vi.importActual<typeof import("../../op/gate")>("../../op/gate");
+  return { ...actual, gitGateLedgerPort: () => gateLedger, gateIsSealed: async () => false };
+});
+
+const failing = new Set<string>();
+/** The error a root's apply throws, in place of applying (#3997). */
+const refusal = new Map<string, Error>();
+/** Called as a component's apply starts, before it can fail. */
+let onRun: (root: string) => void = () => {};
+vi.mock("../../components/fan-out-support", async () => {
+  const { CapabilityRegistry } = await import("../../components/capability");
+  const { planFanOut } = await import("../../components/fan-out");
+  const { computePlanDigest } = await import("../../lifecycle/plan-digest");
+  const registry = new CapabilityRegistry();
+  registry.register({
+    kind: "fake-root",
+    async plan(_ctx: DeployContext, input: { root: string }) {
+      const planDigest = computePlanDigest("fake-root", { root: input.root });
+      return {
+        member: input.root,
+        planDigest,
+        artifact: { planDigest },
+        changeSet: { member: { member: input.root, lexicon: "terraform", planner: "tofu", status: "planned", planDigest, holes: [] }, entries: [] },
+      };
+    },
+    async outputs() {
+      return {};
+    },
+    async run(_ctx: DeployContext, input: { root: string }) {
+      onRun(input.root);
+      if (refusal.has(input.root)) throw refusal.get(input.root);
+      if (failing.has(input.root)) throw new Error(`${input.root} failed`);
+      return { outputs: {} };
+    },
+  } as never);
+  return {
+    fanOutRegistry: async () => registry,
+    deriveFanOut: async () => ({
+      success: true,
+      components: ESTATE,
+      plan: planFanOut({ components: ESTATE, changed: ["net"] }),
+      signal: { changed: ["net"], indeterminate: [], unclaimed: [] },
+    }),
+  };
+});
+
+const root = (name: string, dependsOn: string[] = []): DriverComponent => ({
+  name,
+  dependsOn,
+  deploy: [{ phase: "Apply", steps: [{ kind: "fake-root", root: name }] }],
+});
+const ESTATE: DriverComponent[] = [root("net"), root("app", ["net"])];
+
+const { memoryGateLedgerPort } = await import("../../op/gate");
+const { runComponentsPrPlan, runComponentsPrRecord } = await import("./pr");
+const { checkRunEventLines, stepTrail } = await import("../../workspace/__fixtures__/run-event-check");
+
+let dir: string;
+let errors: string[];
+let applied: string[];
+
+const ctx = (a: Partial<ParsedArgs>) =>
+  ({ args: { command: "components", path: "pr-record", format: "", fix: false, watch: false, verbose: false, help: false, live: false, base: "main", env: "prod", output: dir, ...a } as ParsedArgs, plugins: [] }) as never;
+
+beforeEach(async () => {
+  dir = await mkdtemp(join(tmpdir(), "pr-record-"));
+  errors = [];
+  applied = [];
+  written.length = 0;
+  failing.clear();
+  refusal.clear();
+  onRun = (r) => applied.push(r);
+  gateLedger = memoryGateLedgerPort();
+  vi.spyOn(console, "error").mockImplementation((...m: unknown[]) => { errors.push(m.map(String).join(" ")); });
+  vi.spyOn(console, "log").mockImplementation(() => {});
+});
+
+afterEach(async () => {
+  vi.restoreAllMocks();
+  await rm(dir, { recursive: true, force: true });
+});
+
+const report = (stage: string) => JSON.parse(readFileSync(join(dir, `pr-${stage}.json`), "utf8")) as Record<string, unknown> & { approval: { status: string }; digest: string };
+const approve = (digest: string) =>
+  (gateLedger = memoryGateLedgerPort({
+    resolutions: [{ version: 1, kind: "resolution", op: "pr-12", gate: "pr-apply", resolvedBy: "github:alice", timestamp: new Date().toISOString(), planDigest: digest }],
+  }));
+
+describe("pr-record (#4168)", () => {
+  test("an unapproved merge is recorded, exits 0, writes nothing to the gate ledger and applies nothing", async () => {
+    expect(await runComponentsPrRecord(ctx({ pr: 12 }))).toBe(0);
+    const r = report("record");
+    expect(r).toMatchObject({ stage: "record", status: "recorded", pr: 12, head: HEAD, base: BASE, approval: { status: "pending" } });
+    expect(gateLedger.appended).toEqual([]);
+    expect(applied).toEqual([]);
+    expect(written).toEqual([
+      expect.objectContaining({ commit: HEAD, base: BASE, env: "prod", source: { kind: "pull-request", pr: 12 }, op: "pr-12", gate: "pr-apply", digest: r.digest, plan: "unapproved", approvedBy: [], components: ["net", "app"] }),
+    ]);
+    expect(prStatusState(r as never)).toBe("success");
+  });
+
+  test("the plan a reviewer approved is recorded as approved, by whom", async () => {
+    await runComponentsPrPlan(ctx({ pr: 12 }));
+    approve(report("plan").digest);
+    expect(await runComponentsPrRecord(ctx({ pr: 12 }))).toBe(0);
+    expect(report("record").approval).toEqual({ status: "approved", approvedBy: ["github:alice"] });
+    expect(written[0]).toMatchObject({ plan: "approved", approvedBy: ["github:alice"] });
+    expect(applied).toEqual([]);
+  });
+
+  test("a plan that moved since its approval is recorded, exits 0, and its status fails (decision 1)", async () => {
+    const other = `jcs1-sha256:${"9".repeat(64)}`;
+    approve(other);
+    expect(await runComponentsPrRecord(ctx({ pr: 12 }))).toBe(0);
+    const r = report("record");
+    expect(r.approval).toEqual({ status: "changed", approved: other });
+    expect(String(r.message)).toMatch(/The merge stands and nothing was applied/);
+    expect(prStatusState(r as never)).toBe("failure");
+    expect(written[0]).toMatchObject({ plan: "changed", approvedDigest: other, approvedBy: [] });
+    expect(applied).toEqual([]);
+  });
+
+  test("with no pull request the record names none and reads no gate", async () => {
+    approve(`jcs1-sha256:${"9".repeat(64)}`);
+    expect(await runComponentsPrRecord(ctx({}))).toBe(0);
+    expect(report("record")).toMatchObject({ pr: null, op: "pr-unknown", approval: { status: "pending" } });
+    expect(written[0]).toMatchObject({ source: { kind: "direct-push" }, op: null, plan: "unapproved" });
+  });
+
+  test("a member that fails to plan is recorded as plan-failed and exits 1", async () => {
+    const plan = vi.spyOn(await import("../../components/pr-run"), "planPrSet");
+    plan.mockImplementationOnce(async (input) => ({ ...(await (await vi.importActual<typeof import("../../components/pr-run")>("../../components/pr-run")).planPrSet(input)), failed: true }));
+    expect(await runComponentsPrRecord(ctx({ pr: 12 }))).toBe(1);
+    expect(report("record")).toMatchObject({ status: "plan-failed" });
+    expect(written[0]).toMatchObject({ plan: "plan-failed" });
+  });
+});

package/src/cli/handlers/pr.test.ts

@@ -19,6 +19,13 @@ import { forgePrincipalOf } from "../../pr-forge";
 const HEAD = "a".repeat(40);
 const BASE = "b".repeat(40);
 
+/** The security groups pr-apply reads from the declaration (#4168); none unless a test sets them. */
+let groups: string[] = [];
+vi.mock("../../workspace/security", async (original) => ({
+  ...(await original<typeof import("../../workspace/security")>()),
+  securityGroupsAt: () => new Set(groups),
+}));
+
 vi.mock("../../components/changed-files", () => ({
   resolveCommit: async () => HEAD,
   resolveMergeBase: async () => BASE,
@@ -126,6 +133,7 @@ beforeEach(async () => {
   failing.clear();
   refusal.clear();
   onRun = () => {};
+  groups = [];
   gateLedger = memoryGateLedgerPort();
   vi.spyOn(process.stdout, "write").mockImplementation((chunk: string | Uint8Array) => { out.push(String(chunk)); return true; });
   vi.spyOn(console, "error").mockImplementation((...m: unknown[]) => { errors.push(m.map(String).join(" ")); });
@@ -345,6 +353,12 @@ describe("--events-json beside --json", () => {
   });
 });
 
+test("under the review-rules security group pr-apply needs --forge, since it reads the pull request's reviews (#4168)", async () => {
+  groups = ["review-rules"];
+  expect(await runComponentsPrApply(ctx({ pr: 12, eventsJson: false }))).toBe(1);
+  expect(errors.join("\n")).toContain("the workspace opts into review-rules");
+});
+
 describe("--require-review: whoever wrote the change never counts (#4000)", () => {
   type Kind = "github" | "forgejo" | "gitlab";
   const ENV: Record<Kind, Record<string, string>> = {
@@ -439,6 +453,14 @@ describe("--require-review: whoever wrote the change never counts (#4000)", () =
         expect(report.message).toContain(`approved by ${forgePrincipalOf(kind, HOST[kind], "dave")}, who wrote #12`);
       });
 
+      test("under the review-rules security group the author's approval is refused without --require-review (#4168)", async () => {
+        serve(kind, "carol");
+        await approveAs(kind, "carol");
+        groups = ["review-rules"];
+        expect(await runComponentsPrApply(ctx({ pr: 12, forge: kind, eventsJson: false }))).toBe(3);
+        expect(await applyReport()).toMatchObject({ status: "refused", refusal: "author-approved" });
+      });
+
       test("an outside reviewer approves: the plan applies", async () => {
         serve(kind, "erin");
         await approveAs(kind, "erin");

package/src/cli/handlers/pr.ts

@@ -153,7 +153,7 @@ const fail = (message: string, hint?: string): number => {
 };
 
 /** Everything both stages share: the change and the derivation. Each stage plans the members itself. */
-async function prepare(ctx: CommandContext, stage: "plan" | "apply"): Promise<Prepared | number> {
+async function prepare(ctx: CommandContext, stage: "plan" | "apply" | "record"): Promise<Prepared | number> {
   const { args } = ctx;
   const projectPath = resolve(".");
   const { config } = await loadChantConfig(projectPath).catch(() => ({ config: {} as ChantConfig }));
@@ -297,6 +297,7 @@ function settleOf(status: PrReport["status"]): RunEventSettleStatus {
   switch (status) {
     case "nothing":
     case "planned":
+    case "recorded":
     case "applied":
       return "ok";
     case "refused":
@@ -405,7 +406,7 @@ async function withStageEvents(stage: string, ctx: CommandContext, run: (events:
  * Open the stage's `--report-url` upload under its pull request and commit,
  * when the flag was given. Its events are the lines `openCliRunEvents` writes.
  */
-function openUpload(events: StageEvents, stage: "plan" | "apply", pr: number | null, p: Prepared): PrReportUpload | undefined {
+function openUpload(events: StageEvents, stage: "plan" | "apply" | "record", pr: number | null, p: Prepared): PrReportUpload | undefined {
   if (!events.target) return undefined;
   events.upload = openPrReportUpload({
     target: events.target,
@@ -484,6 +485,11 @@ export function runComponentsPrApply(ctx: CommandContext): Promise<number> {
 }
 
 async function prApply(ctx: CommandContext, stage: StageEvents): Promise<number> {
+  // #4168: the review-rules security group turns --require-review on, read from the declaration at base.
+  const { securityGroupsAt } = await import("../../workspace/security");
+  const reviewRules = !ctx.args.requireReview && securityGroupsAt(process.cwd(), ctx.args.base).has("review-rules");
+  if (reviewRules && !ctx.args.forge) return fail("the workspace opts into review-rules, which reads the pull request's reviews, so pr-apply needs --forge <kind>");
+  if (reviewRules) ctx = { ...ctx, args: { ...ctx.args, requireReview: true } };
   const { args } = ctx;
   if (args.requireReview && !args.forge) return fail("--require-review reads the pull request's reviews, so it needs --forge <kind>");
   if (args.wave !== undefined && !args.waveGate) return fail("--wave runs one wave of a --wave-gate apply, so it needs --wave-gate <name>");
@@ -723,12 +729,129 @@ async function prApply(ctx: CommandContext, stage: StageEvents): Promise<number>
   return code;
 }
 
+/** chant components pr-record --base <ref> [--pr <n>] [--env <env>] [--gate <name>] [--forge <kind>] [--output <dir>] [--json] [--events-json] [--report-url <url>] */
+export function runComponentsPrRecord(ctx: CommandContext): Promise<number> {
+  if (refusesEventsWithJson(ctx.args, "the stage's report")) return Promise.resolve(1);
+  return withStageEvents("pr-record", ctx, (events) => prRecord(ctx, events));
+}
+
+/**
+ * The record stage (#4168 step 1): what a merge does unless apply on merge
+ * is opted in. It plans the members the change reaches on the merged
+ * commit, stores the change set, decides the pull request's gate against
+ * it without writing to the ledger, and writes the merge record
+ * (`../../lifecycle/merge-record.ts`). It applies nothing and refuses
+ * nothing. A plan that differs from the approved one is recorded, and the
+ * `chant/record` status fails (decision 1). It exits 1 only when a member
+ * failed to plan.
+ */
+async function prRecord(ctx: CommandContext, stage: StageEvents): Promise<number> {
+  const { args } = ctx;
+  const p = await prepare(ctx, "record");
+  if (typeof p === "number") return p;
+
+  let pr: number | null = args.pr ?? null;
+  if (pr === null && p.forge) {
+    try {
+      pr = await p.forge.pullRequestFor(p.head);
+    } catch (err) {
+      console.error(formatWarning({ message: `could not ask ${p.forge.kind} which pull request merged ${p.head}, so the record names none: ${err instanceof Error ? err.message : String(err)}` }));
+    }
+  }
+  const op = pr === null ? "pr-unknown" : prOp(pr, p.member);
+  const upload = openUpload(stage, "record", pr, p);
+  const events = await openCliRunEvents(args, { kind: "component", name: `pr-record ${op}`, cwd: resolve(".") }, upload?.line);
+  stage.stream = events;
+  events?.emit({ type: "run-start", waves: p.plan.waves });
+  const set = await planAll(p, events?.emit);
+  const nothing = p.plan.order.length === 0;
+
+  let approval: PrApproval = { status: "pending" };
+  if (!nothing && !set.failed) {
+    await storeChangeSetForGate(ctx, p, set.doc);
+    if (pr !== null) {
+      try {
+        const check = await emitGateStep(events?.emit, { op, gate: p.gate }, () =>
+          decidePrGate(readOnlyLedger(gitGateLedgerPort()), { op, gate: p.gate, digest: set.doc.digest }),
+        );
+        approval = approvalOf(check);
+      } catch (err) {
+        console.error(formatWarning({ message: `could not read the gate ledger, so the record says no approval: ${err instanceof Error ? err.message : String(err)}` }));
+      }
+    }
+  }
+
+  // #4000: the record keeps an approval by someone who wrote the change, which review rules would not count.
+  let authorApproved: string[] | undefined;
+  if (pr !== null && p.forge && approval.status === "approved") {
+    try {
+      const authors = (await p.forge.authors(pr)).map((login) => p.forge!.principalOf(login));
+      authorApproved = approversWhoAuthored(approval.approvedBy ?? [], authors);
+    } catch (err) {
+      console.error(formatWarning({ message: `could not read the authors of #${pr}: ${err instanceof Error ? err.message : String(err)}` }));
+    }
+  }
+
+  const status = nothing ? "nothing" : set.failed ? "plan-failed" : "recorded";
+  const report = prReport({
+    stage: "record",
+    pr,
+    env: p.env,
+    ...(p.member ? { member: p.member } : {}),
+    base: p.base,
+    head: p.head,
+    op,
+    gate: p.gate,
+    plan: p.plan,
+    signal: p.signal,
+    set,
+    approval,
+    status,
+    ...(status === "plan-failed" ? { message: "A member failed to plan on the merged commit, so the record has no plan to compare with the approved one. Nothing was applied." } : {}),
+    ...(status === "recorded" && approval.status === "changed"
+      ? { message: `${describePlanChanged({ op, gate: p.gate, digest: set.doc.digest, approval })} The merge stands and nothing was applied; the release gate decides before this deploys.` }
+      : {}),
+  });
+
+  const { mergeSourceOf, writeMergeRecord, MERGE_RECORD_SCHEMA_ID, MERGE_RECORD_CONTRACT } = await import("../../lifecycle/merge-record");
+  const { pushLifecycleReport } = await import("../../lifecycle/git");
+  try {
+    const written = await writeMergeRecord({
+      $schema: MERGE_RECORD_SCHEMA_ID,
+      contract: MERGE_RECORD_CONTRACT,
+      commit: p.head,
+      base: p.base,
+      env: p.env,
+      ...(p.member ? { member: p.member } : {}),
+      source: mergeSourceOf(resolve("."), p.head, pr),
+      op: pr === null ? null : op,
+      gate: p.gate,
+      digest: nothing ? null : set.doc.digest,
+      plan: nothing ? "nothing" : set.failed ? "plan-failed" : approval.status === "approved" ? "approved" : approval.status === "changed" ? "changed" : "unapproved",
+      ...(approval.status === "changed" && approval.approved ? { approvedDigest: approval.approved } : {}),
+      approvedBy: approval.status === "approved" ? (approval.approvedBy ?? []) : [],
+      ...(authorApproved && authorApproved.length > 0 ? { authorApproved } : {}),
+      components: p.plan.order,
+      recordedAt: new Date().toISOString(),
+    });
+    if (written.written) {
+      const pushed = await pushLifecycleReport();
+      if (pushed.pushWarning) console.error(formatWarning({ message: pushed.pushWarning }));
+    }
+  } catch (err) {
+    console.error(formatWarning({ message: `could not write the merge record for ${p.head}: ${err instanceof Error ? err.message : String(err)}` }));
+  }
+
+  const stop = stopper(ctx, p, events, upload);
+  return stop(report, status === "plan-failed" ? 1 : 0);
+}
+
 /** How a stage stops: settle its events, write and publish the report, say how it ended, and return `code`. */
 function stopper(ctx: CommandContext, p: Prepared, events: RunEventStream | undefined, upload: PrReportUpload | undefined) {
   return async (report: PrReport, code: number, settle?: RunEventSettleStatus): Promise<number> => {
-    events?.settle(settle ?? settleOf(report.status), report.status === "plan-failed" || report.status === "failed" ? report.message ?? `pr-apply ${report.status}` : undefined);
+    events?.settle(settle ?? settleOf(report.status), report.status === "plan-failed" || report.status === "failed" ? report.message ?? `pr-${report.stage} ${report.status}` : undefined);
     await finish(ctx, p, report, upload);
-    console.error((code === 0 ? formatInfo : (m: string) => formatWarning({ message: m }))(`pr-apply: ${report.status}${report.refusal ? ` (${report.refusal})` : ""}`));
+    console.error((code === 0 ? formatInfo : (m: string) => formatWarning({ message: m }))(`pr-${report.stage}: ${report.status}${report.refusal ? ` (${report.refusal})` : ""}`));
     if (report.message) console.error(report.message);
     printMembers(report);
     return code;

package/src/cli/handlers/promote.test.ts

@@ -156,6 +156,12 @@ vi.mock("../../lifecycle/release-revocation", async () => {
   return { ...actual, readRevokedCommits: async () => revokedCommits };
 });
 
+// #4168: the security groups and the release verification, set per test.
+let groups: string[] = [];
+let verification: { status: "verified" | "unsigned" | "unverified"; digestMatches: boolean; reason: string } = { status: "unsigned", digestMatches: true, reason: "no cut of the release carries a signature" };
+vi.mock("../../workspace/security", async (original) => ({ ...(await original<typeof import("../../workspace/security")>()), securityGroupsAt: () => new Set(groups) }));
+vi.mock("../../lifecycle/release-verify", async (original) => ({ ...(await original<typeof import("../../lifecycle/release-verify")>()), verifyRelease: async () => verification }));
+
 // The run handler pulls in every runtime; the promote needs only its exit code.
 vi.mock("./run", () => ({ GATED_EXIT_CODE: 3 }));
 
@@ -214,6 +220,8 @@ beforeEach(() => {
   knownLabels.clear();
   outcomes.length = 0;
   revokedCommits.clear();
+  groups = [];
+  verification = { status: "unsigned", digestMatches: true, reason: "no cut of the release carries a signature" };
   removedTemplates.length = 0;
   ran.length = 0;
   stepInputs.length = 0;
@@ -571,6 +579,15 @@ describe("chant components promote --release binds its gate (#4045)", () => {
     expect(appendReleaseRecordMock).not.toHaveBeenCalled();
   });
 
+  test("under verified-releases a release that does not verify is refused before anything runs, and one that does goes on to its gate (#4168)", async () => {
+    groups = ["verified-releases"];
+    expect(await runComponentsPromote(ctx({ release: "v1.0.0" }))).toBe(1);
+    expect(errors.join("\n")).toMatch(/release-unsigned: release v1\.0\.0 does not verify \(no cut of the release carries a signature\), and the workspace opts into verified-releases/);
+    expect(ran).toEqual([]);
+    verification = { status: "verified", digestMatches: true, reason: "signed by alice" };
+    expect(await runComponentsPromote(ctx({ release: "v1.0.0" }))).toBe(3);
+  });
+
   test("an approval for one release can't be used by another", async () => {
     expect(await runComponentsPromote(ctx({ release: "v1.0.0" }))).toBe(3);
     const pending = releaseGatePort!.appended[0];