@intentius/chant 0.124.26 → 0.124.28

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

@@ -0,0 +1,194 @@
+/**
+ * `chant components pr-plan` and `pr-apply` with `--events-json` (#4041,
+ * #4007): the planning as a `plan` phase, the gate's decision as a `gate`
+ * phase, and on pr-apply the waves and components of the apply, all on one
+ * schema-valid stream. Git, the change signal, the derivation and the gate
+ * ledger are fakes; the planning and the apply are the real ones.
+ */
+
+import { mkdtemp, rm } 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: ["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"); } };
+});
+
+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>();
+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 }) {
+      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 { runComponentsPrApply, runComponentsPrPlan } = await import("./pr");
+const { checkRunEventLines, stepTrail } = await import("../../workspace/__fixtures__/run-event-check");
+
+let dir: string;
+let out: 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, eventsJson: true, ...a } as ParsedArgs, plugins: [] }) as never;
+
+beforeEach(async () => {
+  dir = await mkdtemp(join(tmpdir(), "pr-events-"));
+  out = [];
+  failing.clear();
+  gateLedger = memoryGateLedgerPort();
+  vi.spyOn(process.stdout, "write").mockImplementation((chunk: string | Uint8Array) => { out.push(String(chunk)); return true; });
+  vi.spyOn(console, "error").mockImplementation(() => {});
+  vi.spyOn(console, "log").mockImplementation(() => {});
+});
+
+afterEach(async () => {
+  vi.restoreAllMocks();
+  await rm(dir, { recursive: true, force: true });
+});
+
+/** The digest pr-plan printed, read back from its report. */
+async function plannedDigest(): Promise<string> {
+  const { readFile } = await import("node:fs/promises");
+  return JSON.parse(await readFile(join(dir, "pr-plan.json"), "utf8")).digest as string;
+}
+
+describe("pr-plan --events-json", () => {
+  test("plans each component in a plan phase, then says where the approval stands; the run settles ok", async () => {
+    expect(await runComponentsPrPlan(ctx({ pr: 12 }))).toBe(0);
+    const events = checkRunEventLines(out);
+    expect(events[0]).toMatchObject({ type: "run-start", kind: "component", name: "pr-plan pr-12", waves: [["net"], ["app"]] });
+    expect(stepTrail(events)).toEqual([
+      ["step-start", "plan"], ["step-settle", "plan", "ok"],
+      ["step-start", "plan"], ["step-settle", "plan", "ok"],
+      ["step-start", "gate:pr-apply"], ["gate-waiting", "gate:pr-apply"], ["step-settle", "gate:pr-apply", "gated"],
+    ]);
+    expect(events.filter((e) => e.type === "step-start" && e.phase === "plan").map((e) => (e as { component: string }).component)).toEqual(["net", "app"]);
+    // The plan stage reads the ledger and writes nothing to it.
+    expect(gateLedger.appended).toEqual([]);
+    expect(events.at(-1)).toMatchObject({ type: "run-settle", status: "ok" });
+  });
+});
+
+describe("pr-apply --events-json", () => {
+  test("refused: the gate phase settles gated with the reason, nothing applies, and the run is gated", async () => {
+    expect(await runComponentsPrApply(ctx({ pr: 12 }))).toBe(3);
+    const events = checkRunEventLines(out);
+    expect(events[0]).toMatchObject({ name: "pr-apply pr-12" });
+    expect(events.find((e) => e.type === "gate-waiting")).toMatchObject({ op: "pr-12", gate: "pr-apply", message: expect.stringMatching(/No approval stands for this plan/) });
+    expect(events.some((e) => e.type === "wave-start")).toBe(false);
+    expect(events.at(-1)).toMatchObject({ type: "run-settle", status: "gated" });
+  });
+
+  test("approved: the gate resolves, then each wave and component applies; a failure settles the run failed", async () => {
+    await runComponentsPrPlan(ctx({ pr: 12 }));
+    const digest = await plannedDigest();
+    gateLedger = memoryGateLedgerPort({
+      resolutions: [{ version: 1, kind: "resolution", op: "pr-12", gate: "pr-apply", resolvedBy: "github:alice", timestamp: new Date().toISOString(), planDigest: digest }],
+    });
+    out = [];
+    failing.add("app");
+    expect(await runComponentsPrApply(ctx({ pr: 12 }))).toBe(1);
+    const events = checkRunEventLines(out);
+    expect(events.map((e) => e.type).filter((t) => t !== "step-start" && t !== "step-settle")).toEqual([
+      "run-start",
+      "phase-start", "phase-settle",
+      "phase-start", "gate-resolved", "phase-settle",
+      "wave-start", "component-start", "phase-start", "phase-settle", "component-settle", "wave-settle",
+      "wave-start", "component-start", "phase-start", "phase-settle", "component-settle", "wave-settle",
+      "run-settle",
+    ]);
+    expect(events.find((e) => e.type === "gate-resolved")).toMatchObject({ resolvedBy: "github:alice" });
+    expect(events.find((e) => e.type === "component-settle" && e.component === "app")).toMatchObject({ status: "failed" });
+    expect(events.at(-1)).toMatchObject({ type: "run-settle", status: "failed" });
+  });
+});
+
+describe("--events-json beside --json", () => {
+  test("is refused on pr-plan and pr-apply before anything plans, since both print to stdout", async () => {
+    const errors: string[] = [];
+    vi.spyOn(console, "error").mockImplementation((...m: unknown[]) => { errors.push(m.join(" ")); });
+    expect(await runComponentsPrPlan(ctx({ pr: 12, json: true }))).toBe(1);
+    expect(await runComponentsPrApply(ctx({ pr: 12, json: true }))).toBe(1);
+    expect(errors.filter((e) => /--events-json and --json both stream to stdout/.test(e))).toHaveLength(2);
+    expect(out).toEqual([]);
+  });
+});

package/src/cli/handlers/pr.ts

@@ -29,6 +29,12 @@
  *
  * Every run writes `pr-plan.json` or `pr-apply.json` (`pr-report.schema.json`),
  * `change-set.json` and `pr-note.md` under `--output` (default `.chant/pr`). *
+ * `--events-json` (#4041, #4007) streams the stage's run events to stdout,
+ * one `run-event.schema.json` line each: the planning as a `plan` phase with
+ * a step per component, the gate's decision as a `gate` phase, and on
+ * pr-apply the apply's waves and components as `chant run --components`
+ * streams them.
+ *
  * `--member <name>` (#3465) runs a workspace member's loop: the member's
  * generated pipeline passes it from the member's directory. The gate is
  * recorded under `pr-<n>-<member>`, and the note and the statuses carry the
@@ -54,7 +60,10 @@ import {
 } from "../../components/pr-run";
 import { readFanOutAttempt, writeFanOutAttempt, type FanOutAttempt, type PrApplyRecord } from "../../components/fan-out-record";
 import { samePlanDigest } from "../../lifecycle/plan-digest";
-import { gitGateLedgerPort } from "../../op/gate";
+import { gitGateLedgerPort, type GateCheck } from "../../op/gate";
+import { emitGateStep, gateEventsOf, GATE_PHASE, type RunEventSink, type RunEventStream } from "../../run-event-stream";
+import type { RunEventSettleStatus } from "../../run-event";
+import { openCliRunEvents, refusesEventsWithJson } from "../run-events";
 import {
   describePlanChanged,
   PR_APPLY_GATE,
@@ -74,7 +83,7 @@ import { resolveCliBuildParams, parseParamFlags } from "../build-params-cli";
 import { formatError, formatInfo, formatSuccess, formatWarning } from "../format";
 import { findWorkspaceRoot } from "../../project-root";
 import { resolveChangedUnits } from "./fan-out";
-import { GATED_EXIT_CODE, recordAutoReleasesForRun } from "./run";
+import { GATED_EXIT_CODE, autoReleaseRun, recordAutoReleasesForRun } from "./run";
 import type { CommandContext } from "../registry";
 import type { ComponentChangeSignal, FanOutPlan } from "../../components/fan-out";
 import type { DriverComponent } from "../../components/driver";
@@ -225,8 +234,32 @@ async function checkMember(projectPath: string, names: string[]): Promise<string
 }
 
 /** Plan every member the derivation selects. */
-function planAll(p: Prepared): Promise<PrPlanSet> {
-  return planPrSet({ components: p.components, plan: p.plan, registry: p.registry, env: p.env, seededOutputs: p.seededOutputs });
+function planAll(p: Prepared, onRunEvent?: RunEventSink): Promise<PrPlanSet> {
+  return planPrSet({
+    components: p.components,
+    plan: p.plan,
+    registry: p.registry,
+    env: p.env,
+    seededOutputs: p.seededOutputs,
+    ...(onRunEvent ? { onRunEvent } : {}),
+  });
+}
+
+/**
+ * How a stage's report settles its run's events (#4041): a refusal waits on
+ * a person, as a gate does, and exits the same way.
+ */
+function settleOf(status: PrReport["status"]): RunEventSettleStatus {
+  switch (status) {
+    case "nothing":
+    case "planned":
+    case "applied":
+      return "ok";
+    case "refused":
+      return "gated";
+    default:
+      return "failed";
+  }
 }
 
 /** Write the report, the change set and the note; print the note's path. */
@@ -284,20 +317,50 @@ async function finish(ctx: CommandContext, p: Prepared, report: PrReport): Promi
   if (ctx.args.json) console.log(JSON.stringify(report, null, 2));
 }
 
-/** chant components pr-plan --base <ref> --pr <n> [--env <env>] [--gate <name>] [--forge <kind>] [--output <dir>] [--json] */
-export async function runComponentsPrPlan(ctx: CommandContext): Promise<number> {
+/** A stage's stream, held so that a stage that returns or throws before it settles still ends it. */
+interface StageEvents {
+  stream?: RunEventStream;
+}
+
+/** Run a stage, and end its stream as `failed` when the stage did not settle it. */
+async function withStageEvents(stage: string, run: (events: StageEvents) => Promise<number>): Promise<number> {
+  const events: StageEvents = {};
+  try {
+    return await run(events);
+  } catch (err) {
+    events.stream?.settle("failed", err instanceof Error ? err.message : String(err));
+    throw err;
+  } finally {
+    events.stream?.settle("failed", `${stage} stopped before it finished`);
+  }
+}
+
+/** chant components pr-plan --base <ref> --pr <n> [--env <env>] [--gate <name>] [--forge <kind>] [--output <dir>] [--json] [--events-json] */
+export function runComponentsPrPlan(ctx: CommandContext): Promise<number> {
+  if (refusesEventsWithJson(ctx.args, "the stage's report")) return Promise.resolve(1);
+  return withStageEvents("pr-plan", (events) => prPlan(ctx, events));
+}
+
+async function prPlan(ctx: CommandContext, stage: StageEvents): Promise<number> {
   if (ctx.args.pr === undefined) {
     return fail("pr-plan needs the pull or merge request: --pr <n>", "Its approval is recorded under op pr-<n>, so one pull request's approval never answers another's.");
   }
   const p = await prepare(ctx, "plan");
   if (typeof p === "number") return p;
-  const set = await planAll(p);
   const op = prOp(ctx.args.pr, p.member);
+  // `--events-json` (#4041): planning, then where the approval stands.
+  const events = await openCliRunEvents(ctx.args, { kind: "component", name: `pr-plan ${op}`, cwd: resolve(".") });
+  stage.stream = events;
+  events?.emit({ type: "run-start", waves: p.plan.waves });
+  const set = await planAll(p, events?.emit);
 
   let approval: PrApproval = { status: "pending" };
   if (p.plan.order.length > 0) {
     try {
-      approval = approvalOf(await decidePrGate(readOnlyLedger(gitGateLedgerPort()), { op, gate: p.gate, digest: set.doc.digest }));
+      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 approval reads as pending: ${err instanceof Error ? err.message : String(err)}` }));
     }
@@ -319,6 +382,8 @@ export async function runComponentsPrPlan(ctx: CommandContext): Promise<number>
     status,
   });
   await finish(ctx, p, report);
+  // The plan stage settles on its planning: an approval still to come is what it reports, not a stop.
+  events?.settle(settleOf(status), status === "plan-failed" ? "a member failed to plan" : undefined);
 
   console.error(formatInfo(`pr-plan: ${report.members.length} member(s), ${status}`));
   printMembers(report);
@@ -329,8 +394,13 @@ export async function runComponentsPrPlan(ctx: CommandContext): Promise<number>
   return status === "plan-failed" ? 1 : 0;
 }
 
-/** chant components pr-apply --base <ref> [--pr <n>] [--env <env>] [--gate <name>] [--forge <kind>] [--require-review] [--output <dir>] [--json] */
-export async function runComponentsPrApply(ctx: CommandContext): Promise<number> {
+/** chant components pr-apply --base <ref> [--pr <n>] [--env <env>] [--gate <name>] [--forge <kind>] [--require-review] [--output <dir>] [--json] [--events-json] */
+export function runComponentsPrApply(ctx: CommandContext): Promise<number> {
+  if (refusesEventsWithJson(ctx.args, "the stage's report")) return Promise.resolve(1);
+  return withStageEvents("pr-apply", (events) => prApply(ctx, events));
+}
+
+async function prApply(ctx: CommandContext, stage: StageEvents): Promise<number> {
   const { args } = ctx;
   if (args.requireReview && !args.forge) return fail("--require-review reads the pull request's reviews, so it needs --forge <kind>");
   const p = await prepare(ctx, "apply");
@@ -345,6 +415,12 @@ export async function runComponentsPrApply(ctx: CommandContext): Promise<number>
     }
   }
   const op = pr === null ? "pr-unknown" : prOp(pr, p.member);
+  // The run id the release records carry, chosen before the run so that
+  // `--events-json` (#4041, #4007) names the run by it too.
+  const release = autoReleaseRun(`${op}-${Date.now()}`);
+  const events = await openCliRunEvents(args, { kind: "component", name: `pr-apply ${op}`, runId: release.runId, cwd: resolve(".") });
+  stage.stream = events;
+  events?.emit({ type: "run-start", waves: p.plan.waves });
 
   // `--resume` (#3464): an earlier attempt at this change on this commit
   // applied part of an approved set. When the members left are covered by
@@ -360,10 +436,12 @@ export async function runComponentsPrApply(ctx: CommandContext): Promise<number>
   }
   const resumed = pr !== null && p.plan.order.length > 0 && attempt ? await tryResume(p, attempt, args.resume!, op) : undefined;
 
-  const set = resumed?.set ?? (await planAll(p));
+  if (resumed) emitResumedGate(events, op, p.gate, resumed.check);
+  const set = resumed?.set ?? (await planAll(p, events?.emit));
   const base = { stage: "apply" as const, 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 };
 
-  const stop = async (report: PrReport, code: number): Promise<number> => {
+  const stop = 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);
     await finish(ctx, p, report);
     console.error((code === 0 ? formatInfo : (m: string) => formatWarning({ message: m }))(`pr-apply: ${report.status}${report.refusal ? ` (${report.refusal})` : ""}`));
     if (report.message) console.error(report.message);
@@ -398,16 +476,32 @@ export async function runComponentsPrApply(ctx: CommandContext): Promise<number>
     );
   }
 
+  // #4022: keep the change set the gate binds on chant/lifecycle under its
+  // digest before deciding the gate, so the plan an approval bound, or the
+  // one a pending fact waits on, can be read once this job is gone.
+  await storeChangeSetForGate(ctx, p, set.doc);
+
   let approval: PrApproval;
   if (resumed) {
     approval = resumed.approval;
   } else {
-    const check = await decidePrGate(gitGateLedgerPort(), {
-      op,
-      gate: p.gate,
-      digest: set.doc.digest,
-      description: `pull request #${pr}: ${p.plan.order.join(", ")}`,
-    });
+    const check = await emitGateStep(
+      events?.emit,
+      { op, gate: p.gate },
+      () =>
+        decidePrGate(gitGateLedgerPort(), {
+          op,
+          gate: p.gate,
+          digest: set.doc.digest,
+          description: `pull request #${pr}: ${p.plan.order.join(", ")}`,
+        }),
+      (unapproved) => {
+        const a = approvalOf(unapproved);
+        return a.status === "changed"
+          ? describePlanChanged({ op, gate: p.gate, digest: set.doc.digest, approval: a })
+          : `No approval stands for this plan. Approve it: ${prApproveCommand({ op, gate: p.gate, digest: set.doc.digest })}`;
+      },
+    );
     approval = approvalOf(check);
     if (!check.satisfied) {
       const partial = { ...base, approval, status: "refused" as const };
@@ -431,19 +525,12 @@ export async function runComponentsPrApply(ctx: CommandContext): Promise<number>
     }
     const strangers = approversWithoutReview(approval.approvedBy ?? [], reviewers);
     if (strangers.length > 0) {
-      return stop(
-        prReport({
-          ...base,
-          approval,
-          status: "refused",
-          refusal: "not-a-reviewer",
-          message:
-            `The plan is approved by ${strangers.join(", ")}, who ${strangers.length === 1 ? "has" : "have"} no approving review on #${pr}` +
-            ` (approving reviews: ${reviewers.join(", ") || "none"}). Nothing was applied. ` +
-            `An approval counts when it names the reviewer the way the forge does: ${p.forge.principalOf("<login>")}.`,
-        }),
-        GATED_EXIT_CODE,
-      );
+      const message =
+        `The plan is approved by ${strangers.join(", ")}, who ${strangers.length === 1 ? "has" : "have"} no approving review on #${pr}` +
+        ` (approving reviews: ${reviewers.join(", ") || "none"}). Nothing was applied. ` +
+        `An approval counts when it names the reviewer the way the forge does: ${p.forge.principalOf("<login>")}.`;
+      emitReviewStop(events, message);
+      return stop(prReport({ ...base, approval, status: "refused", refusal: "not-a-reviewer", message }), GATED_EXIT_CODE);
     }
   }
 
@@ -482,6 +569,8 @@ export async function runComponentsPrApply(ctx: CommandContext): Promise<number>
     env: p.env,
     set,
     ...(resumed ? { resumed: prior } : {}),
+    // The apply is this run's waves, so the fan-out's own run framing is dropped.
+    ...(events ? { onRunEvent: events.nested } : {}),
     ...(resumePath
       ? {
           onComponentSettled: (settled, outputs) => {
@@ -497,7 +586,7 @@ export async function runComponentsPrApply(ctx: CommandContext): Promise<number>
       : {}),
   });
   recordAttempt();
-  await recordAutoReleasesForRun(applied.run.results, p.env, `${op}-${Date.now()}`, resolveAutoReleaseDisabled(p.config, args.noReleaseRecord));
+  await recordAutoReleasesForRun(applied.run.results, p.env, release.runId, resolveAutoReleaseDisabled(p.config, args.noReleaseRecord), release.runOrigin);
   const report = prReport({
     ...base,
     approval,
@@ -505,14 +594,59 @@ export async function runComponentsPrApply(ctx: CommandContext): Promise<number>
     members: applied.members,
     ...(resumed ? { resumed: resumed.completed } : {}),
   });
-  const code = await stop(report, applied.status === "applied" ? 0 : 1);
+  // A component that stopped at a gate of its own leaves the apply waiting on a person.
+  const code = await stop(report, applied.status === "applied" ? 0 : 1, applied.run.status === "gated" ? "gated" : undefined);
   if (applied.status === "applied") console.error(formatSuccess(`applied the plan ${report.digest} approved by ${(approval.approvedBy ?? []).join(", ")}`));
   return code;
 }
 
+/** A resumed apply's gate (#3464), decided against the approved digest, as the run's `gate` phase. */
+function emitResumedGate(events: RunEventStream | undefined, op: string, gate: string, check: GateCheck): void {
+  if (!events) return;
+  const where = { component: null, phase: GATE_PHASE, step: `gate:${gate}` };
+  events.emit({ type: "phase-start", component: null, phase: GATE_PHASE });
+  events.emit({ type: "step-start", ...where });
+  for (const body of gateEventsOf(check, { ...where, op, gate }, { durationMs: null })) events.emit(body);
+  events.emit({ type: "phase-settle", component: null, phase: GATE_PHASE, status: check.satisfied ? "ok" : "gated" });
+}
+
+/** An approval by someone with no approving review (#3183) stops the apply: a `review` phase that settles `gated`. */
+function emitReviewStop(events: RunEventStream | undefined, message: string): void {
+  if (!events) return;
+  events.emit({ type: "phase-start", component: null, phase: "review" });
+  events.emit({ type: "step-start", component: null, phase: "review", step: "review" });
+  events.emit({ type: "step-settle", component: null, phase: "review", step: "review", status: "gated", durationMs: null, message });
+  events.emit({ type: "phase-settle", component: null, phase: "review", status: "gated" });
+}
+
+/**
+ * Store `doc` under its digest with its entries mapped onto the member's
+ * graph (`storeGateChangeSet`), and push. A failure is a warning: the gate
+ * decides the same either way.
+ */
+async function storeChangeSetForGate(ctx: CommandContext, p: Prepared, doc: PrPlanSet["doc"]): Promise<void> {
+  const { storeGateChangeSet, gateGraphReader } = await import("../../lifecycle/gate-change-set");
+  const { pushLifecycleReport } = await import("../../lifecycle/git");
+  const graphArgs = [
+    ...(ctx.args.param ?? []).flatMap((kv) => ["--param", kv]),
+    ...(ctx.args.paramsFile ? ["--params-file", ctx.args.paramsFile] : []),
+  ];
+  try {
+    const stored = await storeGateChangeSet({ doc, cwd: resolve("."), at: p.head, readGraph: gateGraphReader(graphArgs) });
+    if (stored.warning) console.error(formatWarning({ message: stored.warning }));
+    // The push's own outcome is said by the gate's pending fact, or by the
+    // release records the apply writes, which push the same branch.
+    if (stored.written) await pushLifecycleReport();
+  } catch (err) {
+    console.error(formatWarning({ message: `could not store the change set ${doc.digest}: ${err instanceof Error ? err.message : String(err)}` }));
+  }
+}
+
 interface Resumed {
   plan: FanOutPlan;
   set: PrPlanSet;
+  /** The gate's decision against the approved digest. */
+  check: GateCheck;
   approval: PrApproval;
   completed: string[];
   outputs: Record<string, Record<string, unknown>>;
@@ -557,5 +691,5 @@ async function tryResume(p: Prepared, attempt: FanOutAttempt, file: string, op:
   });
   if (!resumed.ok) return skip(`what is left is not what was approved. ${resumed.reasons.join("; ")}`);
   console.error(formatInfo(`resume  : ${attempt.completed.join(", ")} applied in an earlier attempt; applying ${resumed.plan.order.join(", ") || "nothing more"} under the approval of ${record.digest}`));
-  return { plan: resumed.plan, set: resumed.set, approval: approvalOf(check), completed: attempt.completed, outputs };
+  return { plan: resumed.plan, set: resumed.set, check, approval: approvalOf(check), completed: attempt.completed, outputs };
 }