@intentius/chant 0.124.33 → 0.124.35

package/src/workspace/declaration.ts

@@ -221,6 +221,12 @@ export interface CiGreen {
   phases: CiPhase[];
   /** The phases a commit must pass, by name, in file order. */
   require: string[];
+  /**
+   * The phases that must pass before the branch moves (#4168 4.4), by name,
+   * in file order: the quick checks a pull request, a merge queue or a local
+   * run gives before a change lands. Absent or empty when the declaration names none.
+   */
+  preMerge?: string[];
   /**
    * The full sha of the first commit on the branch whose ci tags need a
    * statement signed by a runner key (#4031). A tag on a strict
@@ -244,9 +250,20 @@ export interface CiGreen {
 /** Where `ci tick` reads phase results (#4044): forge check runs, or chant Op runs. */
 export type CiSource = "checks" | "runs";
 
+/**
+ * A prescribed delivery workflow (#4168 section 7). `trunk-curated`: a merge
+ * records the plan and deploys nothing, and releases are cut from green
+ * commits and promoted through the environments. `trunk-curated+apply-on-merge`
+ * adds the apply on merge as an opt-in. `chant workspace check` reports what a
+ * member under one still lacks (./checks/ci-workflow.ts, WSP151).
+ */
+export type CiWorkflow = "trunk-curated" | "trunk-curated+apply-on-merge";
+
 /** The declaration's `ci` block (#3573). */
 export interface CiDeclaration {
   green: CiGreen | null;
+  /** `ci.workflow` (#4168 step 6): the workflow every member follows unless it names its own; absent when the declaration sets none. */
+  workflow?: CiWorkflow;
   /**
    * `ci.reportUrl` (#4160): where the pull-request jobs copy their reports
    * and `chant ci run` keeps the run index, `<reportUrl>/runs/index.json`.
@@ -573,6 +590,8 @@ export interface Member {
   travel: boolean;
   /** The security groups this member adds to the declaration's top-level `security` (#4168 step 7), in file order; empty when it names none. */
   security: SecurityGroup[];
+  /** The member's own `ci.workflow` (#4168 step 6), which wins over the top level's; null when it names none. */
+  ciWorkflow: CiWorkflow | null;
   suppress: Suppression[];
   /** The entry's JSON Pointer in the file, for messages. */
   pointer: string;
@@ -869,6 +888,7 @@ export function parseDeclaration(text: string, file: string, reader: string = re
       because: (e.because as string | undefined) ?? null,
       travel: e.travel === true,
       security: [...((e.security as SecurityGroup[] | undefined) ?? [])],
+      ciWorkflow: ((e.ci as { workflow?: CiWorkflow } | undefined)?.workflow) ?? null,
       suppress,
       pointer,
     };
@@ -1116,7 +1136,8 @@ function retentionOf(raw: unknown): RetentionOverride | null {
 
 function ciOf(raw: unknown, at: (pointer: string, key?: boolean) => ErrorLocation): CiDeclaration | null {
   if (raw === undefined) return null;
-  const block = raw as { reportUrl?: string; green?: { branch: string; window?: string; phases: Record<string, string[] | { runs: string[]; skipped?: CiSkipped; build?: CiBuild }>; require: string[]; signedSince?: string; source?: CiSource } };
+  const block = raw as { reportUrl?: string; workflow?: CiWorkflow; green?: { branch: string; window?: string; phases: Record<string, string[] | { runs: string[]; skipped?: CiSkipped; build?: CiBuild }>; require: string[]; preMerge?: string[]; signedSince?: string; source?: CiSource } };
+  const workflow = block.workflow !== undefined ? { workflow: block.workflow } : {};
   let reportUrl: string | null = null;
   if (block.reportUrl !== undefined) {
     // #4160: refused here as pr-plan and ci run refuse the flag, so a reader never gets a URL no job can write to.
@@ -1124,7 +1145,7 @@ function ciOf(raw: unknown, at: (pointer: string, key?: boolean) => ErrorLocatio
     if ("error" in target) throw new WorkspaceReadError("declaration-invalid", target.error, at("/ci/reportUrl"));
     reportUrl = target.url;
   }
-  if (block.green === undefined) return { green: null, reportUrl };
+  if (block.green === undefined) return { green: null, ...workflow, reportUrl };
   const g = block.green;
   const phases: CiPhase[] = Object.entries(g.phases).map(([name, p]) => ({
     name,
@@ -1141,7 +1162,15 @@ function ciOf(raw: unknown, at: (pointer: string, key?: boolean) => ErrorLocatio
       at(`/ci/green/require/${i}`),
     );
   }
-  return { green: { branch: g.branch, window: g.window ?? DEFAULT_CI_WINDOW, phases, require: [...g.require], signedSince: g.signedSince ?? null, source: g.source ?? "checks", pointer: "/ci/green" }, reportUrl };
+  for (const [i, name] of (g.preMerge ?? []).entries()) {
+    if (phases.some((p) => p.name === name)) continue;
+    throw new WorkspaceReadError(
+      "declaration-invalid",
+      `ci.green.preMerge names the phase ${JSON.stringify(name)}, which ci.green.phases does not declare; declared phases: ${phases.map((p) => p.name).join(", ")}`,
+      at(`/ci/green/preMerge/${i}`),
+    );
+  }
+  return { green: { branch: g.branch, window: g.window ?? DEFAULT_CI_WINDOW, phases, require: [...g.require], ...(g.preMerge !== undefined ? { preMerge: [...g.preMerge] } : {}), signedSince: g.signedSince ?? null, source: g.source ?? "checks", pointer: "/ci/green" }, ...workflow, reportUrl };
 }
 
 function agentsOf(raw: unknown, members: Member[], at: (pointer: string, key?: boolean) => ErrorLocation): AgentDeclaration[] {

package/src/workspace/delivery-metrics.ts

@@ -15,7 +15,9 @@
  *   resolutions, for a deploy that names its release only through its
  *   admission (`releaseOfDeploy`, #4043);
  * - the counted `ci/revoked/<sha>` tags, judged as `release cut` judges them
- *   (`readRevokedCommits`, #4033), and each commit's committer time from git.
+ *   (`readRevokedCommits`, #4033), and each commit's committer time from git;
+ *   a composed commit (#4168 4.3) takes the earliest time of the trunk
+ *   commits it carries.
  *
  * Outside a workspace the project's own ledger is read as one member, `null`.
  * It reads the local branch and the local tags, and never fetches.
@@ -139,11 +141,18 @@ export async function deliveryMetrics(query: MetricsQuery): Promise<DeliveryMetr
     const { readRevokedCommits } = await import("../lifecycle/release-revocation");
     const revoked = await readRevokedCommits(root);
 
+    const { compositionOf } = await import("../lifecycle/compose-refs");
     const commitTimes = new Map<string, number | null>();
+    const ownTime = (sha: string): number | null => {
+      const iso = tryGit(top, ["show", "-s", "--format=%cI", `${sha}^{commit}`]);
+      return iso ? Date.parse(iso) : null;
+    };
     const commitTime = (sha: string): number | null => {
       if (!commitTimes.has(sha)) {
-        const iso = tryGit(top, ["show", "-s", "--format=%cI", `${sha}^{commit}`]);
-        commitTimes.set(sha, iso ? Date.parse(iso) : null);
+        // #4168 4.3: a composed commit's lead time runs from the earliest trunk commit it carries.
+        const sources = compositionOf(top, sha)?.sources ?? [];
+        const times = sources.map(ownTime).filter((t): t is number => t !== null);
+        commitTimes.set(sha, times.length > 0 ? Math.min(...times) : ownTime(sha));
       }
       return commitTimes.get(sha)!;
     };

package/src/workspace/graph-contract.test.ts

@@ -221,10 +221,11 @@ describe("chant workspace graph on the chant repo (#2557)", () => {
   // reference workspace runs its own chant workspace graph (#2551);
   // read-contract.test.ts covers that. Here both are left out, so nothing runs.
   const notRun = (JSON.parse(readFileSync(join(REPO, "chant.workspace.json"), "utf-8")) as { members: { name: string; kind: string }[] }).members
-    .filter((m) => m.kind !== "terraform" && m.kind !== "choudoufu" && m.kind !== "workspace")
+    // npm (release/, #4040) is the one kind chant member; leaving it out keeps this a read with nothing to build.
+    .filter((m) => m.kind !== "terraform" && m.kind !== "choudoufu" && m.kind !== "workspace" && m.kind !== "chant")
     .map((m) => m.name);
 
-  test("validates, and lists every member but the terraform one as skipped: none is kind chant", async () => {
+  test("validates, and lists every member but the terraform one and npm as skipped: no other is kind chant", async () => {
     const { doc, failed } = await workspaceGraph({ cwd: join(REPO, "packages", "core"), members: notRun });
     const g = result(doc);
     expectValid(g);

package/src/workspace/init.ts

@@ -559,7 +559,7 @@ export async function runWorkspaceInit(ctx: CommandContext): Promise<number> {
     console.error(
       formatError({
         message: `${join(root, existing[0])} already exists`,
-        hint: "Edit it by hand, or run chant workspace ls to see what it declares.",
+        hint: "Edit it by hand, or run chant workspace ls to see what it declares. To set it up for a delivery workflow, run chant ci init --workflow trunk-curated.",
       }),
     );
     return 1;
@@ -612,7 +612,7 @@ export async function runWorkspaceInit(ctx: CommandContext): Promise<number> {
     return 0;
   }
   writeFileSync(target, text, { flag: "wx" });
-  console.log(formatSuccess(`Wrote ${target}. chant workspace ls lists what it declares.`));
+  console.log(formatSuccess(`Wrote ${target}. chant workspace ls lists what it declares, and chant ci init --workflow trunk-curated sets up merging and releases.`));
   return 0;
 }
 

package/src/workspace/member-commands.test.ts

@@ -112,22 +112,22 @@ describe("resolveToolchain", () => {
 });
 
 describe("the chant repo's own declaration (#2557)", () => {
-  test("declares no chant members, so build runs the example groups under one toolchain", () => {
+  test("build runs the one chant member, npm (release/, #4040), and the example groups under one toolchain", () => {
     const plan = planMembers("build", REPO);
     expect(plan.workspace.name).toBe("chant");
     expect(plan.unreadable).toEqual([]);
     expect(plan.groups).toHaveLength(1);
     const units = plan.groups[0].units;
-    expect(units.every((u) => u.group)).toBe(true);
+    expect(units.filter((u) => !u.group).map((u) => u.id)).toEqual(["npm"]);
     expect(units.map((u) => u.id)).toContain("fixtures:test/leftness");
     expect(plan.skipped.every((s) => s.reason.code === "kind-not-run")).toBe(true);
     expect(plan.skipped.map((s) => s.name)).toContain("core");
   });
 
-  test("graph and audit run nothing there: every member is kind other", () => {
+  test("graph and audit run only npm there: every other member is kind other", () => {
     for (const verb of ["graph", "audit"] as const) {
       const plan = planMembers(verb, REPO);
-      expect(plan.groups, verb).toEqual([]);
+      expect(plan.groups.flatMap((g) => g.units.map((u) => u.id)), verb).toEqual(["npm"]);
     }
   });
 
@@ -164,6 +164,13 @@ describe("member command lines", () => {
     expect(memberArgv("graph", unit, args({ env: "prod" }))).toEqual(["graph", ".", "--format", "ir", "--env", "prod"]);
   });
 
+  test("graph hands each member the detail tier (#4228)", () => {
+    expect(memberArgv("graph", unit, args({ detail: 1, live: true, overlay: true, env: "local" }))).toEqual([
+      "graph", ".", "--format", "ir", "--env", "local", "--live", "--overlay", "--detail", "1",
+    ]);
+    expect(memberArgv("graph", unit, args({ detail: 0 }))).toEqual(["graph", ".", "--format", "ir", "--detail", "0"]);
+  });
+
   test("a reader unit takes --env only with --live, which needs one (#2874, #2875)", () => {
     const reader = { ...unit, reader: { lexicon: "terraform", config: {}, packageDir: "/p" } } as typeof unit;
     expect(memberArgv("graph", reader, args({ env: "prod" }))).toEqual(["graph", ".", "--format", "ir"]);

package/src/workspace/member-commands.ts

@@ -305,6 +305,9 @@ export function memberArgv(verb: WorkspaceVerb, unit: RunUnit, args: ParsedArgs)
     if (args.live) argv.push("--live");
     if (args.overlay) argv.push("--overlay");
     if (args.traffic) argv.push("--traffic", args.traffic);
+    // The detail tier too, so `workspace graph --detail 1` composes collapsed
+    // composites with their rolled-up status (#4228).
+    if (args.detail !== undefined) argv.push("--detail", String(args.detail));
   }
   return argv;
 }

package/src/workspace/nested-graph.test.ts

@@ -69,6 +69,10 @@ describe("readNestedDocument", () => {
       "workspace", "graph", "/w/inner", "--at", "abc", "--env", "dev", "--live", "--overlay", "--traffic", "10 rps", "--no-cache",
     ]);
   });
+
+  test("passes the detail tier on (#4228)", () => {
+    expect(nestedArgv("/w/inner", { detail: 1 }, null)).toEqual(["workspace", "graph", "/w/inner", "--detail", "1"]);
+  });
 });
 
 describe("foldNested", () => {

package/src/workspace/nested-graph.ts

@@ -43,6 +43,7 @@ export function nestedArgv(dir: string, args: Partial<ParsedArgs>, at: string |
     ...(args.live ? ["--live"] : []),
     ...(args.overlay ? ["--overlay"] : []),
     ...(args.traffic !== undefined ? ["--traffic", String(args.traffic)] : []),
+    ...(args.detail !== undefined ? ["--detail", String(args.detail)] : []),
     ...(args.noCache ? ["--no-cache"] : []),
   ];
 }

package/src/workspace/reason-codes.test.ts

@@ -29,6 +29,7 @@ import { WORK_WARNING_CODES } from "./work";
 import { BOX_FINDING_CODES } from "./checks/boxes";
 import { DIAGRAM_FINDING_CODES } from "./checks/diagrams";
 import { SECURITY_FINDING_CODES } from "./checks/security";
+import { CI_WORKFLOW_FINDING_CODES } from "./ci-workflow";
 import { WORK_ERROR_CODES, WORK_HISTORY_ERROR_CODES, WORK_LEASE_REFUSALS } from "./work-cli";
 import { RUN_STATEMENT_ERROR_CODES, RUNS_ERROR_CODES, RUNS_REASON_CODES, RUNS_WRITE_ERROR_CODES } from "./runs-cli";
 import { RUN_STATEMENT_FAILURE_CODES } from "./trust/run-statement";
@@ -68,6 +69,7 @@ const PER_COMMAND: Record<string, readonly string[]> = {
   BOX_FINDING_CODES,
   DIAGRAM_FINDING_CODES,
   SECURITY_FINDING_CODES,
+  CI_WORKFLOW_FINDING_CODES,
   STATUS_REASON_CODES,
   STATUS_ERROR_CODES,
   STATUS_GATE_REASON_CODES,

package/src/workspace/reason-codes.ts

@@ -247,6 +247,16 @@ export const REASONS = {
   "security-runner-start-no-key": "Under isolated-runners, .chant/trust.json lists no key under runners for a provisioner to sign runner-start statements with.",
   "security-runner-start-no-role": "Under isolated-runners, no principal under runners in .chant/trust.json holds the runner role.",
   "security-trust-unreadable": "Under isolated-runners, .chant/trust.json can't be read, so no runner-start statement can be checked.",
+  // The ci.workflow requirements (check, #4168 step 6). Each is also a WSP151 finding.
+  "ci-workflow-green-undeclared": "Under ci.workflow, the declaration has no ci.green block, so no commit gets a verdict and no release can be cut.",
+  "ci-workflow-no-pre-merge": "Under ci.workflow, ci.green.preMerge names no phase, so nothing says which checks run before the branch moves.",
+  "ci-workflow-apply-in-green": "Under ci.workflow, a phase in ci.green.require matches an apply job, which would wait on its own verdict.",
+  "ci-workflow-no-components": "Under ci.workflow, a member declares no component, so nothing of it can be cut or promoted.",
+  "ci-workflow-no-environments": "Under ci.workflow, a member's chant.config.ts declares no environments, so a release has nowhere to be promoted to.",
+  "ci-workflow-ungated-env": "Under ci.workflow, a component has no gate, so a promote to the last environment waits on no approval.",
+  "ci-workflow-pipeline-missing": "Under ci.workflow, no pipeline file runs the plan job, the merge job or chant ci tick.",
+  "ci-workflow-pipeline-differs": "Under ci.workflow, the merge job does not match the workflow: it applies under trunk-curated, or records under trunk-curated+apply-on-merge.",
+  "ci-workflow-publish-missing": "Under ci.workflow, no pipeline file runs chant release publish.",
   // A box that holds a credential (check, #2726). Each is also a WSP finding.
   "box-credential-declared": "A file in a box member's directory carries a literal secret: a credential's shape, or a literal where a credential goes. A variable or secret-manager reference is not one.",
   "box-capability-unbrokered": "A capability in a member's box block names no broker, so the box would hold its credential.",

package/src/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/src/workspace/release-candidates.test.ts

@@ -11,7 +11,7 @@ import { writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { contract } from "./__fixtures__/contract-repo";
 import candidatesSchema from "./release-candidates.schema.json";
-import { prFromSubject, recordTrailers, releaseCandidatesDocument, RELEASE_CANDIDATES_SCHEMA_ID } from "./release-candidates";
+import { groupChanges, mergeRecordPr, prFromSubject, recordTrailers, releaseCandidatesDocument, RELEASE_CANDIDATES_SCHEMA_ID, type CandidateChange } from "./release-candidates";
 import { appendCut, makeRelease, persistRelease } from "../lifecycle/release-store";
 import { appendReleaseRecord } from "../lifecycle/release-ledger";
 import { writeLedgerFiles } from "../lifecycle/git";
@@ -46,6 +46,33 @@ describe("recordTrailers and prFromSubject", () => {
   });
 });
 
+describe("groupChanges (#4168 4.4)", () => {
+  const change = (commit: string, work: string[], pr: number | null): CandidateChange => ({ commit, subject: commit, date: "", work, records: work.map((w) => `work:${w}`), pr, merge: null });
+
+  test("groups by work item, then pull request, then commit, with the ungrouped last", () => {
+    // Newest first, as a candidate's changes are.
+    const groups = groupChanges([
+      change("f", [], null),
+      change("e", ["w-2"], null),
+      change("d", ["w-1"], 4),
+      change("c", [], 3),
+      change("b", ["w-1", "w-2"], 2),
+      change("a", ["w-1"], 2),
+    ]);
+    expect(groups).toEqual([
+      { work: "w-1", pullRequests: [{ pr: 2, commits: ["b", "a"] }, { pr: 4, commits: ["d"] }] },
+      { work: "w-2", pullRequests: [{ pr: 2, commits: ["b"] }, { pr: null, commits: ["e"] }] },
+      { work: null, pullRequests: [{ pr: 3, commits: ["c"] }, { pr: null, commits: ["f"] }] },
+    ]);
+  });
+
+  test("a merge record names its pull request in source", () => {
+    expect(mergeRecordPr({ source: { kind: "pull-request", pr: 12 } })).toBe(12);
+    expect(mergeRecordPr({ source: { kind: "direct-push" } })).toBeNull();
+    expect(mergeRecordPr(null)).toBeNull();
+  });
+});
+
 describe("releaseCandidatesDocument", () => {
   test("partitions the walk at green commits, skips revoked ones, and says which environments each is new for", async () => {
     await withTestDir(async (dir) => {
@@ -63,7 +90,7 @@ describe("releaseCandidatesDocument", () => {
         { cwd: dir },
       );
       // A merge record for d names its pull request.
-      await writeLedgerFiles([{ path: `_merges/${d}.json`, content: JSON.stringify({ pr: 40, approvedDigest: "sha256:x" }) }], "merge record", { cwd: dir });
+      await writeLedgerFiles([{ path: `_merges/${d}.json`, content: JSON.stringify({ source: { kind: "pull-request", pr: 40 }, approvedDigest: "sha256:x" }) }], "merge record", { cwd: dir });
 
       const doc = await releaseCandidatesDocument({ cwd: dir });
       expectValid(doc);
@@ -78,7 +105,7 @@ describe("releaseCandidatesDocument", () => {
       expect(doc.candidates.map((x) => x.commit)).toEqual([d, b, init]);
       expect(doc.candidates[0]).toMatchObject({ newFor: ["staging", "prod"], cut: [] });
       expect(doc.candidates[0].changes.map((x) => x.commit)).toEqual([d, c]);
-      expect(doc.candidates[0].changes[0]).toMatchObject({ pr: 40, merge: { pr: 40, approvedDigest: "sha256:x" } });
+      expect(doc.candidates[0].changes[0]).toMatchObject({ pr: 40, merge: { source: { kind: "pull-request", pr: 40 }, approvedDigest: "sha256:x" } });
       expect(doc.candidates[1].changes.map((x) => x.commit)).toEqual([b, a]);
       expect(doc.candidates[1].changes[0].work).toEqual(["w-7"]);
       expect(doc.candidates[1].changes[1].pr).toBe(1);

package/src/workspace/release-candidates.ts

@@ -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.
  */
@@ -76,6 +81,20 @@ export interface CandidateChange {
   merge: Record<string, unknown> | null;
 }
 
+/** A candidate's changes under one pull request, or under none (`pr: null`) for commits that landed without one. */
+export interface CandidatePullRequestGroup {
+  pr: number | null;
+  /** Newest first. */
+  commits: string[];
+}
+
+/** A candidate's changes under one work item, or under none (`work: null`). Work items come first, in the order the oldest change names them. */
+export interface CandidateGroup {
+  work: string | null;
+  /** Pull requests in the order their oldest commit landed, then `pr: null`. */
+  pullRequests: CandidatePullRequestGroup[];
+}
+
 export interface CandidateFlag {
   id: string;
   member: string;
@@ -95,6 +114,8 @@ export interface Candidate {
   /** The labels of releases already cut from it. */
   cut: string[];
   changes: CandidateChange[];
+  /** The same changes by work item, then pull request, then commit (#4168 4.4). */
+  groups: CandidateGroup[];
   flags: CandidateFlag[];
 }
 
@@ -156,6 +177,34 @@ export function prFromSubject(subject: string): number | null {
   return m ? Number(m[1]) : null;
 }
 
+/** The pull request a merge record names in its `source`, or null. */
+export function mergeRecordPr(merge: Record<string, unknown> | null): number | null {
+  const source = merge?.source as { kind?: unknown; pr?: unknown } | undefined;
+  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: readonly CandidateChange[]): CandidateGroup[] {
+  const oldestFirst = [...changes].reverse();
+  const groups = new Map<string | null, Map<number | null, string[]>>();
+  const add = (work: string | null, pr: number | null, commit: string): void => {
+    const byPr = groups.get(work) ?? new Map<number | null, string[]>();
+    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 = <K>(keys: K[]): K[] => [...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: ReleaseCandidatesQuery): Promise<ReleaseCandidatesDocument> {
   const head = { $schema: RELEASE_CANDIDATES_SCHEMA_ID, contract: RELEASE_CANDIDATES_CONTRACT_VERSION, chant: readerVersion() };
@@ -240,7 +289,8 @@ export async function releaseCandidatesDocument(query: ReleaseCandidatesQuery):
       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 };
     };
@@ -265,13 +315,15 @@ export async function releaseCandidatesDocument(query: ReleaseCandidatesQuery):
       }
       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 = [];