@intentius/chant 0.124.33 → 0.124.35

package/dist/workspace/release-candidates.js

@@ -24,6 +24,11 @@
  * flags whose record files changed in its range, from the declared flag kinds
  * (#4024).
  *
+ * Each candidate also groups its changes (#4168 4.4) by work item, then by
+ * pull request, then by commit: a change lands under every work item its
+ * trailers name, or under no work item, and within that under its pull
+ * request, or under none for a commit that landed without one.
+ *
  * It reads local refs and tags only and never fetches. Git is read through a
  * local `git` subprocess.
  */
@@ -66,6 +71,34 @@ export function prFromSubject(subject) {
     const m = PR_IN_SUBJECT.exec(subject);
     return m ? Number(m[1]) : null;
 }
+/** The pull request a merge record names in its `source`, or null. */
+export function mergeRecordPr(merge) {
+    const source = merge?.source;
+    return source?.kind === "pull-request" && typeof source.pr === "number" ? source.pr : null;
+}
+/**
+ * Group changes, given newest first, by work item, then pull request, then
+ * commit. A change with work items lands in each one's group; the rest land
+ * in the `work: null` group, last. Within a group, pull requests come in the
+ * order their oldest commit landed, and commits without one last.
+ */
+export function groupChanges(changes) {
+    const oldestFirst = [...changes].reverse();
+    const groups = new Map();
+    const add = (work, pr, commit) => {
+        const byPr = groups.get(work) ?? new Map();
+        groups.set(work, byPr);
+        byPr.set(pr, [commit, ...(byPr.get(pr) ?? [])]);
+    };
+    for (const c of oldestFirst)
+        for (const work of c.work.length > 0 ? c.work : [null])
+            add(work, c.pr, c.commit);
+    const nullLast = (keys) => [...keys.filter((k) => k !== null), ...keys.filter((k) => k === null)];
+    return nullLast([...groups.keys()]).map((work) => {
+        const byPr = groups.get(work);
+        return { work, pullRequests: nullLast([...byPr.keys()]).map((pr) => ({ pr, commits: byPr.get(pr) })) };
+    });
+}
 /** Read the release candidates of the member at `query.cwd`. */
 export async function releaseCandidatesDocument(query) {
     const head = { $schema: RELEASE_CANDIDATES_SCHEMA_ID, contract: RELEASE_CANDIDATES_CONTRACT_VERSION, chant: readerVersion() };
@@ -153,7 +186,8 @@ export async function releaseCandidatesDocument(query) {
             const d = details.get(sha);
             const { work, records } = recordTrailers(d?.trailers ?? {});
             const merge = merges.get(sha) ?? null;
-            const mergePr = merge && typeof merge.pr === "number" ? merge.pr : null;
+            // The merge record names its pull request in `source` (../lifecycle/merge-record.ts).
+            const mergePr = mergeRecordPr(merge);
             const subject = d?.subject ?? "";
             return { commit: sha, subject, date: d?.date ?? "", work, records, pr: mergePr ?? prFromSubject(subject), merge };
         };
@@ -178,13 +212,15 @@ export async function releaseCandidatesDocument(query) {
             if (!tags.green.has(sha))
                 continue;
             const own = change(sha);
+            const changes = open.map(change).reverse();
             candidates.push({
                 commit: sha,
                 subject: own.subject,
                 date: own.date,
                 newFor: environments.filter((e) => i < newestRun.get(e.env)).map((e) => e.env),
                 cut: cutLabels.get(sha) ?? [],
-                changes: open.map(change).reverse(),
+                changes,
+                groups: groupChanges(changes),
                 flags: flagReader(open),
             });
             open = [];

package/dist/workspace/release-candidates.schema.json

@@ -212,6 +212,7 @@
         "newFor",
         "cut",
         "changes",
+        "groups",
         "flags"
       ],
       "properties": {
@@ -245,6 +246,13 @@
           },
           "description": "The first-parent commits after the previous candidate, up to and including this one, newest first."
         },
+        "groups": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/group"
+          },
+          "description": "The same changes by work item, then pull request, then commit (#4168 4.4). Work items come first, in the order the oldest change names them, then `work: null` for changes that name none. A change with two work items is under both."
+        },
         "flags": {
           "type": "array",
           "items": {
@@ -254,6 +262,49 @@
         }
       }
     },
+    "group": {
+      "type": "object",
+      "required": [
+        "work",
+        "pullRequests"
+      ],
+      "properties": {
+        "work": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "The work item id a `Chant-Record: work:<id>` trailer names, or null."
+        },
+        "pullRequests": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": [
+              "pr",
+              "commits"
+            ],
+            "properties": {
+              "pr": {
+                "type": [
+                  "integer",
+                  "null"
+                ],
+                "description": "The pull request, or null for commits that landed without one."
+              },
+              "commits": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                },
+                "description": "Newest first."
+              }
+            }
+          },
+          "description": "Pull requests in the order their oldest commit landed, then `pr: null`."
+        }
+      }
+    },
     "change": {
       "type": "object",
       "required": [

package/dist/workspace/release-workflow.d.ts

@@ -0,0 +1,31 @@
+import type { SecurityGroup } from "./security.js";
+export declare const RELEASE_WORKFLOW_FORGES: readonly ["github", "forgejo", "gitlab"];
+export type ReleaseWorkflowForge = (typeof RELEASE_WORKFLOW_FORGES)[number];
+/** Where each forge's publish workflow is written, relative to the repository root. */
+export declare const RELEASE_WORKFLOW_FILES: Record<ReleaseWorkflowForge, string>;
+export interface ReleaseWorkflowInput {
+    forge: ReleaseWorkflowForge;
+    /** The security groups the workspace opts into at its root. */
+    groups: ReadonlySet<SecurityGroup>;
+    /** The command that installs what the build needs. Default `npm ci`. */
+    install?: string;
+    /** The command that builds what the targets upload, or none. Default `npm run build`. */
+    build?: string | null;
+    /** What runs chant. Default `npx chant`. */
+    chant?: string;
+    /** The workspace root relative to the repository root, `.` at the top. */
+    workspaceRoot?: string;
+}
+/** The flags `chant release publish` gets under the groups. */
+export declare function publishFlags(groups: ReadonlySet<SecurityGroup>): string[];
+/** The workflow file's text, without the generated-by header. */
+export declare function renderReleaseWorkflow(input: ReleaseWorkflowInput): string;
+/** The header that marks the file generated, naming the command that regenerates it. */
+export declare function releaseWorkflowHeader(command: string): string;
+/**
+ * `chant release workflow [--forge github|gitlab|forgejo] [--install <command>]
+ * [--build <command>|--no-build] [--chant <command>] [--output <file>]`: write
+ * the publish workflow for the workspace's forge, under its security groups.
+ */
+export declare function runReleaseWorkflow(ctx: import("../cli/registry.js").CommandContext): Promise<number>;
+//# sourceMappingURL=release-workflow.d.ts.map

package/dist/workspace/release-workflow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"release-workflow.d.ts","sourceRoot":"","sources":["../../src/workspace/release-workflow.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,eAAO,MAAM,uBAAuB,YAAI,QAAQ,EAAE,SAAS,EAAE,QAAQ,CAAU,CAAC;AAChF,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE5E,uFAAuF;AACvF,eAAO,MAAM,sBAAsB,EAAE,MAAM,CAAC,oBAAoB,EAAE,MAAM,CAKvE,CAAC;AAEF,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,oBAAoB,CAAC;IAC5B,+DAA+D;IAC/D,MAAM,EAAE,WAAW,CAAC,aAAa,CAAC,CAAC;IACnC,wEAAwE;IACxE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yFAAyF;IACzF,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,4CAA4C;IAC5C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0EAA0E;IAC1E,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,+DAA+D;AAC/D,wBAAgB,YAAY,CAAC,MAAM,EAAE,WAAW,CAAC,aAAa,CAAC,GAAG,MAAM,EAAE,CAEzE;AAED,iEAAiE;AACjE,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,oBAAoB,GAAG,MAAM,CAwDzE;AAED,wFAAwF;AACxF,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE7D;AAED;;;;GAIG;AACH,wBAAsB,kBAAkB,CAAC,GAAG,EAAE,OAAO,iBAAiB,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CA8CvG"}

package/dist/workspace/release-workflow.js

@@ -0,0 +1,150 @@
+/**
+ * `chant release workflow` (#4168 step 6): the publish workflow, generated
+ * the way `chant ci workflow` writes the tick, where the guides used to have
+ * one pasted (guide/release-from-workstation.mdx).
+ *
+ * The job runs on a `release/**` tag, checks the tag out, fetches the ci tags
+ * and `chant/lifecycle`, builds what the targets upload, and runs `chant
+ * release publish` for the label the tag names. The security groups decide
+ * the rest, and nothing is on without one (#4168 section 8):
+ *
+ * - `supply-chain` adds `--require-provenance`, so a run with no OIDC token
+ *   fails rather than publishing without provenance.
+ * - `verified-releases` adds a `chant release verify` step before the publish.
+ *
+ * The OIDC permission (`id-token: write`, or GitLab's `id_tokens`) is always
+ * there: it costs nothing, and with it what the job uploads carries
+ * provenance whether or not the group requires it.
+ */
+import { GENERATED_MARKER } from "../discovery/files.js";
+export const RELEASE_WORKFLOW_FORGES = ["github", "forgejo", "gitlab"];
+/** Where each forge's publish workflow is written, relative to the repository root. */
+export const RELEASE_WORKFLOW_FILES = {
+    github: ".github/workflows/chant-release.yml",
+    forgejo: ".forgejo/workflows/chant-release.yml",
+    // GitLab reads one .gitlab-ci.yml, which includes this file: `include: { local: .gitlab/chant-release.yml }`.
+    gitlab: ".gitlab/chant-release.yml",
+};
+/** The flags `chant release publish` gets under the groups. */
+export function publishFlags(groups) {
+    return [...(groups.has("supply-chain") ? ["--require-provenance"] : []), "--yes"];
+}
+/** The workflow file's text, without the generated-by header. */
+export function renderReleaseWorkflow(input) {
+    const chant = input.chant ?? "npx chant";
+    const install = input.install ?? "npm ci";
+    const build = input.build === undefined ? "npm run build" : input.build;
+    const root = input.workspaceRoot && input.workspaceRoot !== "." ? input.workspaceRoot : null;
+    const verify = input.groups.has("verified-releases");
+    const flags = publishFlags(input.groups).join(" ");
+    if (input.forge === "gitlab") {
+        const label = '"${CI_COMMIT_TAG#release/}"';
+        const lines = [
+            "chant-release-publish:",
+            "  rules:",
+            "    - if: $CI_COMMIT_TAG =~ /^release\\//",
+            "  id_tokens:",
+            "    SIGSTORE_ID_TOKEN:",
+            "      aud: sigstore",
+            "  script:",
+            ...(root ? [`    - cd ${root}`] : []),
+            `    - ${install}`,
+            ...(build ? [`    - ${build}`] : []),
+            "    - git fetch origin 'refs/tags/ci/*:refs/tags/ci/*'",
+            "    - git fetch origin chant/lifecycle:chant/lifecycle",
+            ...(verify ? [`    - ${chant} release verify ${label}`] : []),
+            `    - ${chant} release publish ${label} ${flags}`,
+        ];
+        return `${lines.join("\n")}\n`;
+    }
+    const label = '"${GITHUB_REF_NAME#release/}"';
+    const lines = [
+        "name: chant release publish",
+        "on:",
+        "  push:",
+        '    tags: ["release/**"]',
+        "permissions:",
+        "  contents: write",
+        "  id-token: write",
+        "jobs:",
+        "  publish:",
+        "    runs-on: ubuntu-latest",
+        ...(root ? ["    defaults:", "      run:", `        working-directory: ${root}`] : []),
+        "    steps:",
+        "      - uses: actions/checkout@v4",
+        "        with:",
+        "          fetch-depth: 0",
+        "      - uses: actions/setup-node@v4",
+        "        with:",
+        "          node-version: 24",
+        "          registry-url: https://registry.npmjs.org",
+        `      - run: ${install}`,
+        ...(build ? [`      - run: ${build}`] : []),
+        "      - run: git fetch origin 'refs/tags/ci/*:refs/tags/ci/*'",
+        "      - run: git fetch origin chant/lifecycle:chant/lifecycle",
+        ...(verify ? [`      - run: ${chant} release verify ${label}`] : []),
+        `      - run: ${chant} release publish ${label} ${flags}`,
+    ];
+    return `${lines.join("\n")}\n`;
+}
+/** The header that marks the file generated, naming the command that regenerates it. */
+export function releaseWorkflowHeader(command) {
+    return `# ${GENERATED_MARKER}. Regenerate with: ${command} (in the workspace root)\n`;
+}
+/**
+ * `chant release workflow [--forge github|gitlab|forgejo] [--install <command>]
+ * [--build <command>|--no-build] [--chant <command>] [--output <file>]`: write
+ * the publish workflow for the workspace's forge, under its security groups.
+ */
+export async function runReleaseWorkflow(ctx) {
+    const { existsSync, mkdirSync, realpathSync, writeFileSync } = await import("node:fs");
+    const { dirname, join, relative, resolve, sep } = await import("node:path");
+    const { formatError, formatSuccess } = await import("../cli/format.js");
+    const { findWorkspaceRoot } = await import("../project-root.js");
+    const { gitTop } = await import("./tree.js");
+    const { securityGroupsAt } = await import("./security.js");
+    const { shellArg } = await import("./member-pipeline.js");
+    const usage = "chant release workflow [--forge github|gitlab|forgejo] [--install <command>] [--build <command>] [--chant <command>] [--output <file>]";
+    const { args } = ctx;
+    const found = findWorkspaceRoot(process.cwd());
+    if (!found) {
+        console.error(formatError({ message: "no chant.workspace.json between this directory and the git root", hint: usage }));
+        return 1;
+    }
+    const root = realpathSync(found.dir);
+    const repoRoot = gitTop(root) ?? root;
+    const forge = (args.forge ??
+        (existsSync(join(repoRoot, ".github", "workflows")) ? "github" : existsSync(join(repoRoot, ".forgejo", "workflows")) ? "forgejo" : existsSync(join(repoRoot, ".gitlab-ci.yml")) ? "gitlab" : "github"));
+    if (!RELEASE_WORKFLOW_FORGES.includes(forge)) {
+        console.error(formatError({ message: `--forge ${JSON.stringify(forge)} is not one of ${RELEASE_WORKFLOW_FORGES.join(", ")}`, hint: usage }));
+        return 1;
+    }
+    const groups = securityGroupsAt(root);
+    const workspaceRoot = relative(repoRoot, root).split(sep).join("/") || ".";
+    const text = renderReleaseWorkflow({
+        forge,
+        groups,
+        workspaceRoot,
+        ...(args.ciInstall ? { install: args.ciInstall } : {}),
+        ...(args.buildCommand ? { build: args.buildCommand } : {}),
+        ...(args.ciChant ? { chant: args.ciChant } : {}),
+    });
+    const target = args.output ? resolve(process.cwd(), args.output) : join(repoRoot, RELEASE_WORKFLOW_FILES[forge]);
+    const parts = ["chant", "release", "workflow", "--forge", forge];
+    if (args.ciInstall)
+        parts.push("--install", args.ciInstall);
+    if (args.buildCommand)
+        parts.push("--build", args.buildCommand);
+    if (args.ciChant)
+        parts.push("--chant", args.ciChant);
+    if (args.output)
+        parts.push("--output", relative(root, target).split(sep).join("/"));
+    mkdirSync(dirname(target), { recursive: true });
+    writeFileSync(target, releaseWorkflowHeader(parts.map(shellArg).join(" ")) + text);
+    const shown = relative(process.cwd(), target).split(sep).join("/") || target;
+    const extras = [groups.has("supply-chain") ? "requires OIDC provenance (supply-chain)" : null, groups.has("verified-releases") ? "verifies the release first (verified-releases)" : null].filter(Boolean);
+    console.log(formatSuccess(`Wrote ${shown}: publishes the release a release/** tag names${extras.length > 0 ? `, and ${extras.join(" and ")}` : ""}.`));
+    if (forge === "gitlab")
+        console.log(`Include it from .gitlab-ci.yml: include: [{ local: ${RELEASE_WORKFLOW_FILES.gitlab} }]`);
+    return 0;
+}

package/dist/workspace/releases.schema.json

@@ -363,6 +363,36 @@
               "type": "string"
             }
           }
+        },
+        "composed": {
+          "type": "object",
+          "required": [
+            "branch",
+            "base",
+            "sources"
+          ],
+          "properties": {
+            "branch": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "base": {
+              "type": "string"
+            },
+            "sources": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
+          },
+          "description": "Added by #4168 4.3, written by chant 0.124.35 and newer. On a cut of a composed commit only: its chant/compose/<name> branch, the trunk commit it was composed on, and the trunk commits picked onto that base, oldest first."
+        },
+        "channel": {
+          "type": "string",
+          "description": "Added by #4168 4.3, written by chant 0.124.35 and newer. The tag release publish moves in place of latest (an npm dist-tag, an image tag), from release cut --channel. Absent for latest."
         }
       }
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant",
-  "version": "0.124.33",
+  "version": "0.124.35",
   "description": "Declarative infrastructure-as-code toolkit — TypeScript on Node.js",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",

package/src/cli/handlers/graph.ts

@@ -432,7 +432,7 @@ async function runGraphLive(
     // no stack carries a `src`.
     const scopedStacks = stacks.filter((s) => s.src);
     if (scopedStacks.length > 0) {
-      const declaredIr = await buildDeclaredPerStack(scopedStacks, projectPath);
+      const declaredIr = await buildDeclaredPerStack(scopedStacks, projectPath, (g, entities) => withLexiconEdges(g, plugins, entities));
       ir =
         args.overlayAnchor === "live"
           ? overlayGraphs(ir, declaredIr, overlayOpts)
@@ -455,7 +455,7 @@ async function runGraphLive(
         console.error(formatWarning({ message: "overlay: a build root failed to render — showing the provisioned graph without the declared overlay" }));
       } else {
         await mergeGraphOps(declared.entities, declared.sourceFiles, projectPath);
-        const declaredIr = buildGraphIr(declared.entities, projectPath);
+        const declaredIr = withLexiconEdges(buildGraphIr(declared.entities, projectPath), plugins, declared.entities);
         ir =
           args.overlayAnchor === "live"
             ? overlayGraphs(ir, declaredIr, overlayOpts)

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

@@ -0,0 +1,230 @@
+/**
+ * `chant components pr-apply --green` (#4168 step 9): apply on merge applies
+ * a green commit, under the approved plans of the merges since the last
+ * applied one when they cover it, and otherwise at a gate of its own on the
+ * combined digest. Git, the green target, the derivation and the gate ledger
+ * are fakes; the planning, the coverage and the apply are the real ones.
+ */
+
+import { mkdtemp, readFile, 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 { ChangeSetDocument } from "../../change-set";
+import type { GreenApplyRecord } from "../../lifecycle/green-apply";
+import type { GreenTargetResult } from "../../components/green-cover";
+import type { ParsedArgs } from "../registry";
+
+const HEAD = "a".repeat(40);
+const BASE = "b".repeat(40);
+
+vi.mock("../../workspace/security", async (original) => ({
+  ...(await original<typeof import("../../workspace/security")>()),
+  securityGroupsAt: () => new Set<string>(),
+}));
+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: [] } }),
+}));
+// Nothing here may write or push the real repository's chant/lifecycle.
+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 () => ({}) };
+});
+const applied: GreenApplyRecord[] = [];
+vi.mock("../../lifecycle/green-apply", async () => {
+  const actual = await vi.importActual<typeof import("../../lifecycle/green-apply")>("../../lifecycle/green-apply");
+  return { ...actual, writeGreenApply: async (r: GreenApplyRecord) => (applied.push(r), "ledger-commit") };
+});
+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 };
+});
+
+let target: GreenTargetResult;
+let asked: Array<{ base?: string }> = [];
+vi.mock("../../components/green-cover", async () => {
+  const actual = await vi.importActual<typeof import("../../components/green-cover")>("../../components/green-cover");
+  return { ...actual, resolveGreenTarget: async (req: { base?: string }) => (asked.push(req), target) };
+});
+
+/** What each root's plan writes, so a test can move it. */
+const values = new Map<string, string>();
+const ran: 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 value = values.get(input.root) ?? "1";
+      const planDigest = computePlanDigest("fake-root", { root: input.root, value });
+      return {
+        member: input.root,
+        planDigest,
+        artifact: { planDigest },
+        changeSet: {
+          member: { member: input.root, lexicon: "terraform", planner: "tofu", status: "planned", planDigest, holes: [] },
+          entries: [{ member: input.root, lexicon: "terraform", planner: "tofu", address: `${input.root}.main`, type: "fake", action: "update", attributes: [{ path: "value", after: value }] }],
+        },
+      };
+    },
+    async outputs() {
+      return {};
+    },
+    async run(_ctx: DeployContext, input: { root: string }) {
+      ran.push(input.root);
+      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 { composeChangeSet } = await import("../../change-set");
+
+let dir: string;
+let errors: 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-green-"));
+  errors = [];
+  applied.length = 0;
+  ran.length = 0;
+  values.clear();
+  asked = [];
+  gateLedger = memoryGateLedgerPort();
+  vi.spyOn(process.stdout, "write").mockImplementation(() => true);
+  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 });
+});
+
+/** The change set a pull request's plan made with the values set now. */
+async function planned(): Promise<ChangeSetDocument> {
+  await runComponentsPrPlan(ctx({ pr: 12, path: "pr-plan" }));
+  return JSON.parse(await readFile(join(dir, "change-set.json"), "utf8")) as ChangeSetDocument;
+}
+
+const greenTarget = (approved: Array<{ doc: ChangeSetDocument; pr: number; approvedBy: string[] }>): GreenTargetResult => ({
+  status: "target",
+  target: {
+    commit: HEAD,
+    base: BASE,
+    baseFrom: "applied",
+    merges: [BASE.replace(/b/g, "c"), HEAD],
+    prs: approved.map((m) => m.pr),
+    approved: approved.map((m, i) => ({ commit: i === approved.length - 1 ? HEAD : BASE.replace(/b/g, "c"), ...m })),
+  },
+});
+const OP = `green-${HEAD.slice(0, 12)}`;
+
+describe("pr-apply --green (#4168 step 9)", () => {
+  test("the merges' approved plans cover the plan at the green commit: it applies under them, with no gate, and records the commit applied", async () => {
+    const doc = await planned();
+    target = greenTarget([{ doc, pr: 12, approvedBy: ["github:alice"] }]);
+    expect(await runComponentsPrApply(ctx({ green: true }))).toBe(0);
+    expect(ran).toEqual(["net", "app"]);
+    expect(gateLedger.appended).toEqual([]);
+    expect(applied).toEqual([expect.objectContaining({ env: "prod", commit: HEAD, base: BASE, approval: "merges", approvedBy: ["github:alice"], digest: doc.digest })]);
+    const report = JSON.parse(await readFile(join(dir, "pr-apply.json"), "utf8"));
+    expect(report).toMatchObject({ op: OP, pr: null, status: "applied", approval: { status: "approved", approvedBy: ["github:alice"] } });
+  });
+
+  test("two merges, each approving one member, cover the plan together (the case one pull request's apply stopped at plan-changed)", async () => {
+    values.set("app", "1");
+    const first = await planned();
+    values.set("app", "2");
+    const both = await planned();
+    // #13 touched app alone, so its plan holds app alone.
+    const second = composeChangeSet([{ member: both.members.find((m) => m.member === "app")!, entries: both.entries.filter((e) => e.member === "app") }]);
+    // #12 approved net and app at 1; #13 approved app at 2; the green commit plans net at 1 and app at 2.
+    target = greenTarget([
+      { doc: first, pr: 12, approvedBy: ["github:alice"] },
+      { doc: second, pr: 13, approvedBy: ["github:bob"] },
+    ]);
+    expect(await runComponentsPrApply(ctx({ green: true }))).toBe(0);
+    expect(ran).toEqual(["net", "app"]);
+    expect(applied[0]).toMatchObject({ approval: "merges", approvedBy: ["github:alice", "github:bob"] });
+  });
+
+  test("a plan the merges did not approve waits at the green commit's own gate on the combined digest, then applies once that is approved", async () => {
+    const doc = await planned();
+    values.set("net", "9");
+    target = greenTarget([{ doc, pr: 12, approvedBy: ["github:alice"] }]);
+    expect(await runComponentsPrApply(ctx({ green: true }))).toBe(3);
+    expect(ran).toEqual([]);
+    expect(applied).toEqual([]);
+    const refused = JSON.parse(await readFile(join(dir, "pr-apply.json"), "utf8"));
+    expect(refused).toMatchObject({ op: OP, status: "refused", refusal: "not-approved" });
+    expect(refused.message).toContain("do not cover it: net now writes net.main.value to a different value than the approved plan (checked against #12)");
+    expect(refused.message).toContain(`chant approve ${OP} pr-apply --plan ${refused.digest}`);
+
+    gateLedger = memoryGateLedgerPort({
+      resolutions: [{ version: 1, kind: "resolution", op: OP, gate: "pr-apply", resolvedBy: "github:carol", timestamp: new Date().toISOString(), planDigest: refused.digest }],
+    });
+    expect(await runComponentsPrApply(ctx({ green: true }))).toBe(0);
+    expect(ran).toEqual(["net", "app"]);
+    expect(applied[0]).toMatchObject({ approval: "gate", approvedBy: ["github:carol"], digest: refused.digest });
+  });
+
+  test("the green commit last applied is nothing to do, and --green takes no --pr", async () => {
+    target = { status: "applied", commit: HEAD };
+    expect(await runComponentsPrApply(ctx({ green: true }))).toBe(0);
+    expect(ran).toEqual([]);
+    expect(errors.join("\n")).toContain("is the green commit last applied to prod");
+    expect(await runComponentsPrApply(ctx({ green: true, pr: 12 }))).toBe(1);
+    target = { status: "error", message: "abc is not a green commit", hint: "check it out" };
+    expect(await runComponentsPrApply(ctx({ green: true }))).toBe(1);
+    expect(errors.join("\n")).toContain("abc is not a green commit");
+    // --base reaches the target as the first apply's fallback.
+    expect(asked.at(-1)).toMatchObject({ base: "main" });
+  });
+});