@intentius/chant 0.124.32 → 0.124.34

package/src/cli/handlers/lifecycle-health.ts

@@ -0,0 +1,157 @@
+/**
+ * `chant lifecycle health <env> [lexicon] [--json]` (#4177): whether each
+ * declared resource that has a health read is up, separate from drift.
+ *
+ * It builds the project as `lifecycle diff` does, so the entity names are the
+ * graph's node ids, then asks each lexicon with a health read about the
+ * entities whose types it names. An environment's declared endpoint is applied
+ * for the read, as on the other live reads (#1166).
+ *
+ * The JSON is the {@link HEALTH_SCHEMA} shape. A single-stack project prints
+ * `lexicons` at the top level; a multi-stack one nests them under `stacks`,
+ * the same split `lifecycle diff --live --json` makes.
+ */
+
+import { resolve } from "node:path";
+import { build } from "../../build";
+import { loadChantConfig } from "../../config";
+import { isObservableDeclarable } from "../../declarable";
+import { HEALTH_SCHEMA, healthApplicable, observeHealthFor, summarizeHealth, type HealthLexicon, type HealthReadResult } from "../../health";
+import { applyLiveEndpoint } from "../../live-endpoint";
+import type { SerializerResult } from "../../serializer";
+import { CHANT_VERSION } from "../version";
+import { commandBuildParams } from "../build-params-cli";
+import { resolveBuildModes, resolveProjectBuildOptions } from "../build-options";
+import { formatBold, formatError, formatWarning } from "../format";
+import type { CommandContext } from "../registry";
+import { resolveStackTargets } from "./lifecycle";
+
+type ByLexicon = Record<string, HealthReadResult>;
+
+export async function runLifecycleHealth(ctx: CommandContext): Promise<number> {
+  const { args, plugins } = ctx;
+  const environment = args.extraPositional;
+  const lexiconFilter = args.extraPositional2;
+  if (!environment) {
+    console.error(formatError({ message: "Environment is required: chant lifecycle health <environment> [lexicon]" }));
+    return 1;
+  }
+
+  const readers = plugins.filter(
+    (p) => p.observeHealth && (p.healthTypes?.length ?? 0) > 0 && (!lexiconFilter || p.name === lexiconFilter),
+  );
+  if (readers.length === 0) {
+    console.error(formatWarning({
+      message: lexiconFilter
+        ? `${lexiconFilter}: no health read in this lexicon`
+        : "No configured lexicon has a health read (aws, azure and gcp do)",
+    }));
+    return 1;
+  }
+
+  const projectRoot = resolve(".");
+  const { config } = await loadChantConfig(projectRoot);
+  const declaredParams = await commandBuildParams(config.buildParams, args);
+  if (!declaredParams) return 1;
+  const targets = resolveStackTargets(args, config);
+  const buildOptions = resolveProjectBuildOptions({
+    config,
+    configDir: projectRoot,
+    plugins,
+    modes: resolveBuildModes(config, { fold: args.fold, sandbox: args.sandbox }),
+    buildParams: declaredParams,
+  });
+  const serializers = readers.map((p) => p.serializer);
+
+  const endpoint = applyLiveEndpoint(config.environments, environment, readers);
+  if (endpoint.notice) console.error(formatWarning({ message: endpoint.notice }));
+
+  const perStack: Record<string, ByLexicon> = {};
+  let single: ByLexicon | undefined;
+  let anyBuildError = false;
+  const observedAt = new Date().toISOString();
+
+  try {
+    for (const target of targets) {
+      const buildResult = await build(target.root, serializers, undefined, buildOptions);
+      if (buildResult.errors.length > 0) {
+        console.error(formatError({
+          message: `Build failed for ${target.stack ? `stack "${target.stack}"` : "project"}; fix errors before reading health`,
+        }));
+        anyBuildError = true;
+        continue;
+      }
+      const byLexicon: ByLexicon = {};
+      for (const plugin of readers) {
+        const declared = new Map<string, { entityType: string; props: Record<string, unknown> }>();
+        for (const [name, entity] of buildResult.entities) {
+          if (entity.lexicon === plugin.name && isObservableDeclarable(entity)) {
+            declared.set(name, {
+              entityType: entity.entityType,
+              props: (entity.props != null ? entity.props : {}) as Record<string, unknown>,
+            });
+          }
+        }
+        const entities = healthApplicable(plugin as HealthLexicon, declared);
+        if (entities.size === 0) continue;
+        const raw = buildResult.outputs.get(plugin.name);
+        const buildOutput = raw === undefined ? "" : typeof raw === "string" ? raw : (raw as SerializerResult).primary;
+        byLexicon[plugin.name] = await observeHealthFor(plugin as HealthLexicon, {
+          environment,
+          buildOutput,
+          entities,
+          ...(target.stack ? { stack: target.stack } : {}),
+          ...(target.region ? { region: target.region } : {}),
+        });
+      }
+      if (target.stack) perStack[target.stack] = byLexicon;
+      else single = byLexicon;
+    }
+  } finally {
+    endpoint.restore();
+  }
+
+  const all = single ? [single] : Object.values(perStack);
+  const summary = summarizeHealth(all.flatMap((b) => Object.values(b)));
+
+  if (args.json) {
+    console.log(JSON.stringify({
+      schema: HEALTH_SCHEMA,
+      chantVersion: CHANT_VERSION,
+      environment,
+      observedAt,
+      ...(single ? { lexicons: single } : { stacks: perStack }),
+      summary,
+    }));
+  } else {
+    if (single) renderHealth(single);
+    else for (const [stack, byLexicon] of Object.entries(perStack)) {
+      console.log(`\n${formatBold(`■ stack ${stack}`)}`);
+      renderHealth(byLexicon);
+    }
+    const total = summary.healthy + summary.unhealthy + summary.unknown + summary.unobserved + summary.absent;
+    if (total === 0) {
+      console.error(formatWarning({ message: "No declared resource has a health read" }));
+    } else {
+      console.error(
+        `${summary.healthy} healthy, ${summary.unhealthy} unhealthy, ${summary.unknown} unknown` +
+          (summary.unobserved > 0 ? `, ${summary.unobserved} not observed` : "") +
+          (summary.absent > 0 ? `, ${summary.absent} not deployed` : ""),
+      );
+    }
+  }
+  return anyBuildError ? 1 : 0;
+}
+
+function renderHealth(byLexicon: ByLexicon): void {
+  for (const [lexicon, result] of Object.entries(byLexicon)) {
+    console.log(formatBold(lexicon));
+    for (const [name, entry] of Object.entries(result.entities)) {
+      console.log(`  ${entry.state.padEnd(9)} ${name} (${entry.type}): ${entry.detail}`);
+    }
+    for (const [name, hole] of Object.entries(result.unobserved)) {
+      console.log(`  ${"not read".padEnd(9)} ${name}${hole.type ? ` (${hole.type})` : ""}: ${hole.reason}${hole.detail ? `, ${hole.detail}` : ""}`);
+    }
+    for (const name of result.absent) console.log(`  ${"absent".padEnd(9)} ${name}: not deployed`);
+  }
+}

package/src/cli/handlers/lifecycle.ts

@@ -90,7 +90,7 @@ interface StackTarget {
  * observed as the stack named after the environment (unchanged behavior). An
  * explicit `--src` always wins and forces a single scoped target.
  */
-function resolveStackTargets(args: ParsedArgs, config: ChantConfig): StackTarget[] {
+export function resolveStackTargets(args: ParsedArgs, config: ChantConfig): StackTarget[] {
   if (args.src) return [{ root: resolve(args.src) }];
   if (config.stacks && config.stacks.length > 0) {
     return config.stacks.map((s) => ({ stack: s.name, root: resolve(s.src), region: s.region }));

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");