@intentius/chant 0.124.34 → 0.124.36

package/src/lifecycle/release-compose.test.ts

@@ -0,0 +1,125 @@
+/**
+ * `release compose` (#4168 4.3): chosen trunk commits cherry-picked onto a
+ * base, each with a `Chant-Composed-From` trailer, on a pushed
+ * `chant/compose/<name>` branch, appended to and never rewritten.
+ */
+
+import { describe, test, expect } from "vitest";
+import { withTestDir } from "@intentius/chant-test-utils";
+import { spawnSync } from "node:child_process";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { composeRelease, ComposeError } from "./release-compose";
+import { composeBranchContaining, composedFrom, composedIncluding, compositionOf } from "./compose-refs";
+
+function git(dir: string, ...args: string[]): string {
+  const r = spawnSync("git", args, { cwd: dir, encoding: "utf-8" });
+  if (r.status !== 0) throw new Error(r.stderr);
+  return r.stdout.trim();
+}
+
+/** A clone of a bare remote with trunk: base, then #1 (a.txt), #2 (b.txt, work w-2), #3 (a.txt again). */
+function trunk(dir: string): { clone: string; remote: string; base: string; c1: string; c2: string; c3: string } {
+  const remote = join(dir, "remote.git");
+  const clone = join(dir, "clone");
+  git(dir, "init", "-q", "--bare", "-b", "main", remote);
+  mkdirSync(clone);
+  for (const args of [["init", "-q", "-b", "main"], ["config", "user.email", "t@chant.dev"], ["config", "user.name", "T"], ["remote", "add", "origin", remote]]) git(clone, ...args);
+  const commit = (file: string, text: string, message: string): string => {
+    writeFileSync(join(clone, file), text);
+    git(clone, "add", file);
+    git(clone, "commit", "-q", "-m", message);
+    return git(clone, "rev-parse", "HEAD");
+  };
+  const base = commit("a.txt", "a0\n", "base");
+  const c1 = commit("a.txt", "a1\n", "fix a (#1)");
+  const c2 = commit("b.txt", "b\n", "add b (#2)\n\nChant-Record: work:w-2");
+  const c3 = commit("a.txt", "a3\n", "rework a (#3)");
+  git(clone, "push", "-q", "origin", "main");
+  git(clone, "fetch", "-q", "origin");
+  return { clone, remote, base, c1, c2, c3 };
+}
+
+const TRUNK = { remote: "origin", branch: "main" };
+
+describe("composeRelease", () => {
+  test("picks the chosen changes in trunk order onto the base, with trailers, and pushes the branch", async () => {
+    await withTestDir(async (dir) => {
+      const t = trunk(dir);
+      const dry = await composeRelease({ cwd: t.clone, name: "hotfix", base: t.base, prs: [], works: ["w-2"], yes: false, trunk: TRUNK });
+      expect(dry.written).toBe(false);
+      expect(dry.picked.map((s) => s.commit)).toEqual([t.c2]);
+      expect(git(t.clone, "branch", "--list", "chant/compose/hotfix")).toBe("");
+
+      const r = await composeRelease({ cwd: t.clone, name: "hotfix", base: t.base, prs: [2, 1], works: [], yes: true, trunk: TRUNK });
+      expect(r.picked.map((s) => s.commit)).toEqual([t.c1, t.c2]);
+      expect(r.picked[1].work).toEqual(["w-2"]);
+      expect(r.written).toBe(true);
+      expect(r.pushed).toBe(true);
+      expect(git(t.remote, "rev-parse", "refs/heads/chant/compose/hotfix")).toBe(r.tip);
+      expect(composedFrom(t.clone, r.tip)).toEqual([t.c2]);
+      expect(compositionOf(t.clone, r.tip)).toEqual({ branch: null, base: t.base, sources: [t.c1, t.c2] });
+      expect(composeBranchContaining(t.clone, r.tip)?.branch).toBe("chant/compose/hotfix");
+      expect(composedIncluding(t.clone, t.c1)).toEqual([{ branch: "chant/compose/hotfix", commit: git(t.clone, "rev-parse", `${r.tip}^`) }]);
+      expect(git(t.clone, "show", `${r.tip}:a.txt`)).toBe("a1");
+    });
+  });
+
+  test("appends to the branch, skips what it carries, and refuses another base", async () => {
+    await withTestDir(async (dir) => {
+      const t = trunk(dir);
+      const first = await composeRelease({ cwd: t.clone, name: "x", base: t.base, prs: [1], works: [], yes: true, trunk: TRUNK });
+      const again = await composeRelease({ cwd: t.clone, name: "x", prs: [1, 2], works: [], yes: true, trunk: TRUNK });
+      expect(again.from).toBe(first.tip);
+      expect(again.already.map((s) => s.commit)).toEqual([t.c1]);
+      expect(again.picked.map((s) => s.commit)).toEqual([t.c2]);
+      expect(git(t.clone, "rev-parse", `${again.tip}^`)).toBe(first.tip);
+      await expect(composeRelease({ cwd: t.clone, name: "x", base: t.c1, prs: [3], works: [], yes: true, trunk: TRUNK })).rejects.toMatchObject({ code: "compose-base-differs" });
+    });
+  });
+
+  test("stops on a conflict, names the change and the file, and writes nothing", async () => {
+    await withTestDir(async (dir) => {
+      const t = trunk(dir);
+      const err = await composeRelease({ cwd: t.clone, name: "y", base: t.base, prs: [3], works: [], yes: true, trunk: TRUNK }).catch((e: unknown) => e);
+      expect(err).toBeInstanceOf(ComposeError);
+      expect((err as ComposeError).code).toBe("compose-conflict");
+      expect((err as ComposeError).conflict).toMatchObject({ commit: t.c3, files: ["a.txt"] });
+      expect((err as ComposeError).message).toContain("#3");
+      expect(git(t.clone, "branch", "--list", "chant/compose/y")).toBe("");
+      expect(spawnSync("git", ["rev-parse", "--verify", "--quiet", "refs/heads/chant/compose/y"], { cwd: t.remote }).status).not.toBe(0);
+      expect(git(t.clone, "worktree", "list").split("\n")).toHaveLength(1);
+    });
+  });
+
+  test("refuses a change trunk does not have, a bad name, and no base for a new branch", async () => {
+    await withTestDir(async (dir) => {
+      const t = trunk(dir);
+      await expect(composeRelease({ cwd: t.clone, name: "z", base: t.base, prs: [9], works: [], yes: false, trunk: TRUNK })).rejects.toMatchObject({ code: "compose-source-unknown" });
+      await expect(composeRelease({ cwd: t.clone, name: "../z", base: t.base, prs: [1], works: [], yes: false, trunk: TRUNK })).rejects.toMatchObject({ code: "compose-name-invalid" });
+      await expect(composeRelease({ cwd: t.clone, name: "z", prs: [1], works: [], yes: false, trunk: TRUNK })).rejects.toMatchObject({ code: "compose-base-unknown" });
+      await expect(composeRelease({ cwd: t.clone, name: "z", base: t.base, prs: [], works: [], yes: false, trunk: TRUNK })).rejects.toMatchObject({ code: "compose-nothing-chosen" });
+    });
+  });
+});
+
+describe("composeRelease after a hand-made commit", () => {
+  test("keeps the branch's base when its tip carries no trailer", async () => {
+    await withTestDir(async (dir) => {
+      const t = trunk(dir);
+      const first = await composeRelease({ cwd: t.clone, name: "h", base: t.base, prs: [1], works: [], yes: true, trunk: TRUNK });
+      // A person resolves something on the branch and pushes it.
+      git(t.clone, "checkout", "-q", "chant/compose/h");
+      writeFileSync(join(t.clone, "c.txt"), "by hand\n");
+      git(t.clone, "add", "c.txt");
+      git(t.clone, "commit", "-q", "-m", "by hand");
+      git(t.clone, "push", "-q", "origin", "chant/compose/h");
+      git(t.clone, "checkout", "-q", "main");
+      const next = await composeRelease({ cwd: t.clone, name: "h", base: t.base, prs: [1, 2], works: [], yes: true, trunk: TRUNK });
+      expect(next.base).toBe(t.base);
+      expect(next.already.map((s) => s.commit)).toEqual([t.c1]);
+      expect(next.picked.map((s) => s.commit)).toEqual([t.c2]);
+      expect(git(t.clone, "rev-parse", `${next.tip}~2`)).toBe(first.tip);
+    });
+  });
+});

package/src/lifecycle/release-compose.ts

@@ -0,0 +1,312 @@
+/**
+ * `chant release compose` (#4168 4.3, mode b): a release of chosen changes
+ * on a base, when trunk carries work that is not ready to ship.
+ *
+ * The changes are named by pull request (`--pr <n>`) or work item
+ * (`--work <id>`) and found on trunk's first-parent line after the base:
+ * a pull request by the merge record `_merges/<sha>.json` on
+ * `chant/lifecycle` (./merge-record.ts) or the squash subject `... (#n)`,
+ * a work item by the commit's `Chant-Record: work:<id>` trailers or a merge
+ * record that names it. Each commit is cherry-picked in trunk order onto the
+ * base, in a temporary detached worktree, with a `Chant-Composed-From: <sha>`
+ * trailer, and the result goes on the branch `chant/compose/<name>`, pushed
+ * so the forge's CI builds it (decision 6).
+ *
+ * It only appends. A branch that exists is composed onto from its tip, with
+ * the base it already has; a change it already carries is skipped. On a
+ * conflict it stops, names the change and the files, and writes nothing: a
+ * person resolves it in a pull request to the compose branch.
+ *
+ * Without `yes` it is a dry run: the picks are made in the temporary
+ * worktree, so a conflict shows now, and no ref is moved or pushed.
+ */
+
+import { execFileSync, spawnSync } from "node:child_process";
+import { mkdtempSync, realpathSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { COMPOSE_BRANCH_PREFIX, COMPOSED_FROM_TRAILER, compositionOnTrunk } from "./compose-refs";
+
+export type ComposeCode =
+  | "not-a-git-repository"
+  | "compose-name-invalid"
+  | "compose-nothing-chosen"
+  | "compose-base-unknown"
+  | "compose-base-differs"
+  | "compose-branch-diverged"
+  | "compose-source-unknown"
+  | "compose-conflict"
+  | "compose-push-refused";
+
+export class ComposeError extends Error {
+  constructor(
+    readonly code: ComposeCode,
+    message: string,
+    readonly fix?: string,
+    /** With `compose-conflict`: the change that did not apply and the files it conflicts in. */
+    readonly conflict?: { commit: string; subject: string; files: string[] },
+  ) {
+    super(message);
+    this.name = "ComposeError";
+  }
+}
+
+export interface ComposeRequest {
+  cwd: string;
+  name: string;
+  /** A release label or digest, or a commit. Required when the branch does not exist yet. */
+  base?: string;
+  prs: readonly number[];
+  works: readonly string[];
+  /** Move the branch and push it. Otherwise a dry run. */
+  yes: boolean;
+  /** The trunk branch, `ci.green.branch` as the cut resolves it. */
+  trunk: { remote: string; branch: string };
+  /** Push the branch to the trunk's remote with `yes`. Default true. */
+  push?: boolean;
+}
+
+/** One trunk commit a compose picks, and why. */
+export interface ComposeSource {
+  commit: string;
+  subject: string;
+  pr: number | null;
+  work: string[];
+  /** The `--pr` and `--work` values that chose it. */
+  chosenBy: string[];
+}
+
+export interface ComposeResult {
+  name: string;
+  branch: string;
+  base: string;
+  /** The branch's tip before the compose, or null when it is new. */
+  from: string | null;
+  /** The commits picked now, in trunk order. */
+  picked: ComposeSource[];
+  /** Chosen commits the branch already carries. */
+  already: ComposeSource[];
+  /** The branch's tip after the picks. Under a dry run, the tip it would have. */
+  tip: string;
+  /** Whether the branch was moved here. False under a dry run. */
+  written: boolean;
+  /** Whether it was pushed. */
+  pushed: boolean;
+}
+
+const NAME = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+const PR_IN_SUBJECT = /\(#(\d+)\)\s*$/;
+
+function git(cwd: string, args: string[], env?: NodeJS.ProcessEnv): string {
+  return execFileSync("git", args, { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: 64 * 1024 * 1024, ...(env ? { env } : {}) }).trim();
+}
+
+function tryGit(cwd: string, args: string[]): string | null {
+  try {
+    return git(cwd, args);
+  } catch {
+    return null;
+  }
+}
+
+const isAncestor = (top: string, a: string, b: string): boolean => spawnSync("git", ["merge-base", "--is-ancestor", a, b], { cwd: top, stdio: "ignore" }).status === 0;
+
+/** The branch a compose name lives on. */
+export function composeBranchName(name: string): string {
+  return `${COMPOSE_BRANCH_PREFIX}${name}`;
+}
+
+async function resolveBase(top: string, cwd: string, ref: string): Promise<string> {
+  const { resolveRelease } = await import("./release-store");
+  const found = await resolveRelease(ref, { cwd }).catch(() => null);
+  if (found) return found.release.commit;
+  const sha = tryGit(top, ["rev-parse", "--verify", "--quiet", `${ref}^{commit}`]);
+  if (!sha) {
+    throw new ComposeError("compose-base-unknown", `--base ${ref} names no release of this member and no commit this clone has`, "Name a release label (chant release list) or a commit, after fetching it.");
+  }
+  return sha;
+}
+
+/** The merge record of `sha`, as stored, or null. */
+async function mergeRecordOf(cwd: string, sha: string): Promise<Record<string, unknown> | null> {
+  const { readBlobFromPath } = await import("./git");
+  const text = await readBlobFromPath("_merges", `${sha}.json`, { cwd }).catch(() => null);
+  if (text === null) return null;
+  try {
+    const parsed = JSON.parse(text) as unknown;
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? (parsed as Record<string, unknown>) : null;
+  } catch {
+    return null;
+  }
+}
+
+/** The pull request and work items a merge record names. */
+function fromMergeRecord(merge: Record<string, unknown> | null): { pr: number | null; work: string[] } {
+  if (!merge) return { pr: null, work: [] };
+  const source = merge.source as { kind?: unknown; pr?: unknown; records?: unknown } | undefined;
+  const pr = source?.kind === "pull-request" && typeof source.pr === "number" ? source.pr : typeof merge.pr === "number" ? merge.pr : null;
+  const work =
+    source?.kind === "work-item" && Array.isArray(source.records)
+      ? source.records.filter((r): r is { kind: string; id: string } => !!r && typeof r === "object" && (r as { kind?: unknown }).kind === "work").map((r) => r.id)
+      : [];
+  return { pr, work };
+}
+
+/**
+ * Compose the chosen changes onto the base, on `chant/compose/<name>`.
+ * Throws {@link ComposeError} before any ref moves.
+ */
+export async function composeRelease(req: ComposeRequest): Promise<ComposeResult> {
+  const top = tryGit(req.cwd, ["rev-parse", "--show-toplevel"]);
+  if (!top) throw new ComposeError("not-a-git-repository", "a compose picks commits, and this directory is not in a git repository");
+  if (!NAME.test(req.name)) {
+    throw new ComposeError("compose-name-invalid", `"${req.name}" can't name a compose branch: use letters, digits, dots, dashes and underscores, starting with a letter or digit`);
+  }
+  if (req.prs.length === 0 && req.works.length === 0) {
+    throw new ComposeError("compose-nothing-chosen", "a compose needs the changes it carries", "Name them: --pr <n> or --work <id>, each as often as needed.");
+  }
+  const { remote } = req.trunk;
+  const branch = composeBranchName(req.name);
+  const remoteRef = `refs/remotes/${remote}/${branch}`;
+  const localRef = `refs/heads/${branch}`;
+  // The branch as the remote has it, when the remote is reachable; a new branch is absent there.
+  if (tryGit(top, ["remote", "get-url", remote]) !== null) tryGit(top, ["fetch", "--quiet", "--no-tags", remote, `+${localRef}:${remoteRef}`]);
+  const remoteTip = tryGit(top, ["rev-parse", "--verify", "--quiet", `${remoteRef}^{commit}`]);
+  const localTip = tryGit(top, ["rev-parse", "--verify", "--quiet", `${localRef}^{commit}`]);
+  if (remoteTip && localTip && !isAncestor(top, localTip, remoteTip) && !isAncestor(top, remoteTip, localTip)) {
+    throw new ComposeError(
+      "compose-branch-diverged",
+      `${branch} here and on ${remote} have diverged, and a compose only appends`,
+      `Keep the remote's: git branch -f ${branch} ${remote}/${branch}`,
+    );
+  }
+  const from = remoteTip && localTip ? (isAncestor(top, localTip, remoteTip) ? remoteTip : localTip) : (remoteTip ?? localTip);
+  const trunkRef =
+    tryGit(top, ["rev-parse", "--verify", "--quiet", `refs/remotes/${remote}/${req.trunk.branch}^{commit}`]) ??
+    tryGit(top, ["rev-parse", "--verify", "--quiet", `refs/heads/${req.trunk.branch}^{commit}`]);
+  if (!trunkRef) throw new ComposeError("compose-source-unknown", `this clone has neither ${remote}/${req.trunk.branch} nor ${req.trunk.branch}, so there is no trunk to pick from`);
+  // What the branch carries: back to trunk, past a commit a person made on it, such as a resolved conflict.
+  const existing = from ? compositionOnTrunk(top, from, trunkRef, branch) : null;
+
+  let base: string;
+  if (from) {
+    base = existing?.base ?? from;
+    if (req.base !== undefined) {
+      const asked = await resolveBase(top, req.cwd, req.base);
+      if (asked !== base) {
+        throw new ComposeError(
+          "compose-base-differs",
+          `${branch} is composed on ${base.slice(0, 12)}, and --base names ${asked.slice(0, 12)}; a compose only appends to its branch`,
+          `Drop --base to add to ${branch}, or compose under another name.`,
+        );
+      }
+    }
+  } else {
+    if (req.base === undefined) throw new ComposeError("compose-base-unknown", `${branch} does not exist yet, so the compose needs --base`, "Name the release or commit to compose on: --base <label|sha>");
+    base = await resolveBase(top, req.cwd, req.base);
+  }
+
+  // Trunk's first-parent commits after the base, oldest first.
+  const line = (tryGit(top, ["rev-list", "--first-parent", "--reverse", trunkRef, `^${base}`]) ?? "").split("\n").filter(Boolean);
+  const { commitDetails } = await import("../workspace/intent");
+  const { recordTrailers } = await import("../workspace/release-candidates");
+  const details = commitDetails(top, line);
+
+  const chosen = new Map<string, ComposeSource>();
+  const choose = (sha: string, by: string, pr: number | null, work: string[]) => {
+    const entry = chosen.get(sha) ?? { commit: sha, subject: details.get(sha)?.subject ?? "", pr, work, chosenBy: [] };
+    if (!entry.chosenBy.includes(by)) entry.chosenBy.push(by);
+    chosen.set(sha, entry);
+  };
+  const unmatched = new Set<string>([...req.prs.map((n) => `--pr ${n}`), ...req.works.map((w) => `--work ${w}`)]);
+  for (const sha of line) {
+    const d = details.get(sha);
+    const merge = fromMergeRecord(await mergeRecordOf(req.cwd, sha));
+    const subjectPr = PR_IN_SUBJECT.exec(d?.subject ?? "");
+    const pr = merge.pr ?? (subjectPr ? Number(subjectPr[1]) : null);
+    const work = [...new Set([...recordTrailers(d?.trailers ?? {}).work, ...merge.work])];
+    for (const n of req.prs) {
+      if (pr === n) {
+        choose(sha, `--pr ${n}`, pr, work);
+        unmatched.delete(`--pr ${n}`);
+      }
+    }
+    for (const w of req.works) {
+      if (work.includes(w)) {
+        choose(sha, `--work ${w}`, pr, work);
+        unmatched.delete(`--work ${w}`);
+      }
+    }
+  }
+  if (unmatched.size > 0) {
+    throw new ComposeError(
+      "compose-source-unknown",
+      `${[...unmatched].join(", ")} names no commit on ${remote}/${req.trunk.branch} after ${base.slice(0, 12)}`,
+      "A pull request is found by its merge record or its squash subject (#n), and a work item by a Chant-Record: work:<id> trailer. Fetch trunk and chant/lifecycle if it merged elsewhere.",
+    );
+  }
+
+  // Trunk order, and what the branch already carries.
+  const carried = new Set(existing?.sources ?? []);
+  const ordered = line.filter((sha) => chosen.has(sha)).map((sha) => chosen.get(sha)!);
+  const already = ordered.filter((s) => carried.has(s.commit));
+  const picked = ordered.filter((s) => !carried.has(s.commit));
+
+  const tip = picked.length === 0 ? (from ?? base) : pickOnto(top, from ?? base, picked);
+  let written = false;
+  let pushed = false;
+  if (req.yes && picked.length > 0) {
+    git(top, ["update-ref", "-m", `chant release compose ${req.name}`, localRef, tip, localTip ?? ""]);
+    written = true;
+  }
+  if (req.yes && (req.push ?? true) && tryGit(top, ["remote", "get-url", remote]) !== null && tip !== remoteTip) {
+    try {
+      git(top, ["push", "--quiet", remote, `${tip}:${localRef}`]);
+      tryGit(top, ["update-ref", remoteRef, tip]);
+      pushed = true;
+    } catch (err) {
+      const stderr = (err as { stderr?: Buffer | string }).stderr?.toString().trim() ?? String(err);
+      throw new ComposeError("compose-push-refused", `${branch} was composed here at ${tip.slice(0, 12)} and ${remote} refused the push: ${stderr}`, `Push it by hand once the remote allows it: git push ${remote} ${branch}`);
+    }
+  }
+  return { name: req.name, branch, base, from, picked, already, tip, written, pushed };
+}
+
+/**
+ * Cherry-pick `sources` in order onto `start` in a temporary detached
+ * worktree, each with its trailer, and return the last commit. Throws
+ * `compose-conflict` naming the change and its files when one does not
+ * apply. The worktree is removed either way.
+ */
+function pickOnto(top: string, start: string, sources: readonly ComposeSource[]): string {
+  const realTop = realpathSync(top);
+  const dir = mkdtempSync(join(tmpdir(), "chant-compose-"));
+  git(realTop, ["worktree", "add", "--detach", "--quiet", dir, start]);
+  try {
+    for (const s of sources) {
+      const parents = (tryGit(dir, ["rev-list", "--parents", "-n", "1", s.commit]) ?? "").split(" ").length - 1;
+      const args = ["cherry-pick", "--allow-empty", "--keep-redundant-commits", ...(parents > 1 ? ["-m", "1"] : []), s.commit];
+      const run = spawnSync("git", args, { cwd: dir, encoding: "utf-8" });
+      if (run.status !== 0) {
+        const files = (tryGit(dir, ["diff", "--name-only", "--diff-filter=U"]) ?? "").split("\n").filter(Boolean);
+        tryGit(dir, ["cherry-pick", "--abort"]);
+        const what = [s.pr !== null ? `#${s.pr}` : null, ...s.work.map((w) => `work:${w}`)].filter(Boolean).join(", ");
+        throw new ComposeError(
+          "compose-conflict",
+          `${s.commit.slice(0, 12)} (${s.subject}${what ? `; ${what}` : ""}) does not apply on the composed commits${files.length > 0 ? `: it conflicts in ${files.join(", ")}` : `: ${(run.stderr || run.stdout).trim()}`}. Nothing was written`,
+          "Resolve it by hand in a pull request to the compose branch, or compose without that change.",
+          { commit: s.commit, subject: s.subject, files },
+        );
+      }
+      git(dir, ["commit", "--quiet", "--amend", "--no-edit", "--allow-empty", "--no-verify", "--trailer", `${COMPOSED_FROM_TRAILER}: ${s.commit}`]);
+    }
+    return git(dir, ["rev-parse", "HEAD"]);
+  } finally {
+    try {
+      git(realTop, ["worktree", "remove", "--force", dir]);
+    } catch {
+      rmSync(dir, { recursive: true, force: true });
+      tryGit(realTop, ["worktree", "prune"]);
+    }
+  }
+}

package/src/lifecycle/release-cut.ts

@@ -102,6 +102,10 @@ export interface CutRequest {
    * must be the principal the signers file lists the key for.
    */
   sign?: string | true;
+  /** The composition of a composed commit (#4168 4.3), recorded on the cut. */
+  composed?: { branch: string; base: string; sources: string[] };
+  /** The publish channel recorded on the cut (#4168 4.3), in place of `latest`. */
+  channel?: string;
 }
 
 export interface CutResult {
@@ -501,6 +505,8 @@ export async function cutRelease(req: CutRequest): Promise<CutResult> {
       runId: ci?.runId ?? `local-${Date.parse(timestamp)}`,
       runOrigin: ci?.runOrigin ?? { forge: "local" },
       signature,
+      ...(req.composed ? { composed: req.composed } : {}),
+      ...(req.channel ? { channel: req.channel } : {}),
     },
     { cwd },
   );

package/src/lifecycle/release-publish.ts

@@ -129,6 +129,10 @@ export interface PublishDeps {
   fetch?: PublishFetch;
   /** The npm executable. Default: `npm` on `PATH`. */
   npm?: string;
+  /** How a target waits between polls of a registry (#4244). Default: a timer. */
+  sleep?: (ms: number) => Promise<void>;
+  /** The clock a target's wait reads (#4244). Default: `Date.now`. */
+  now?: () => number;
 }
 
 /** The subset of the WHATWG `fetch` the targets use. */
@@ -278,6 +282,8 @@ export interface PublishPlan {
   redactor: Redactor;
   /** Whether a target with no SBOM source is refused (`publish-sbom-missing`): the workspace opts into `supply-chain` (#4168). Otherwise it publishes without one. */
   requireSbom: boolean;
+  /** The channel a cut of the release names (#4168 4.3), the tag moved in place of `latest`, or null. */
+  channel: string | null;
 }
 
 /**
@@ -399,7 +405,8 @@ export async function preparePublish(req: {
   const member = ledger.members.length > 0 ? ledger.members.join("/") : null;
   const releaseTag = label !== null ? releaseTagName(member, label) : null;
   const redactor = createRedactor(env, targets.flatMap((t) => t.credentialEnv));
-  return { release, label, signature, provenance, warning, signatureWarning, cut, releaseTag, targets, redactor, requireSbom: groups.has("supply-chain") };
+  const channel = [...cuts].reverse().find((c) => c.channel)?.channel ?? null;
+  return { release, label, signature, provenance, warning, signatureWarning, cut, releaseTag, targets, redactor, requireSbom: groups.has("supply-chain"), channel };
 }
 
 /**

package/src/lifecycle/release-store.ts

@@ -149,6 +149,17 @@ export interface ReleaseCut {
    * unsigned cut, and on every cut written before 0.124.28.
    */
   signature: string | null;
+  /**
+   * A cut of a composed commit (#4168 4.3): its compose branch, the base it
+   * was composed on, and the trunk commits picked onto the base, oldest
+   * first. Absent on a cut of a trunk commit.
+   */
+  composed?: { branch: string; base: string; sources: string[] };
+  /**
+   * The channel the release publishes to (#4168 4.3): the npm dist-tag or
+   * image tag a publish moves in place of `latest`. Absent for `latest`.
+   */
+  channel?: string;
 }
 
 /** The parts of a release a digest is computed from. */
@@ -364,7 +375,9 @@ export function parseCuts(text: string | null): { cuts: ReleaseCut[]; malformed:
         typeof c.timestamp === "string" &&
         (c.runOrigin === null || (typeof c.runOrigin === "object" && typeof c.runOrigin?.forge === "string")) &&
         (c.signature === null || c.signature === undefined || typeof c.signature === "string") &&
-        (c.runId === null || c.runId === undefined || typeof c.runId === "string");
+        (c.runId === null || c.runId === undefined || typeof c.runId === "string") &&
+        (c.channel === undefined || typeof c.channel === "string") &&
+        (c.composed === undefined || (typeof c.composed === "object" && c.composed !== null && typeof c.composed.base === "string" && Array.isArray(c.composed.sources)));
       if (!ok) {
         malformed++;
         continue;
@@ -444,6 +457,8 @@ export async function appendCut(
       runId: input.runId ?? null,
       runOrigin: input.runOrigin,
       signature: input.signature ?? null,
+      ...(input.composed ? { composed: input.composed } : {}),
+      ...(input.channel ? { channel: input.channel } : {}),
     };
     const content = `${existing ? `${existing.replace(/\n$/, "")}\n` : ""}${JSON.stringify(cut, sortedJsonReplacer)}\n`;
     try {

package/src/workspace/checks/ci-workflow.test.ts

@@ -47,6 +47,8 @@ const PIPELINE = [
   "      - run: chant ci run record --in-place --env prod --gate pr-apply --forge github",
   "",
 ].join("\n");
+/** #4168 step 9: under apply on merge a merge is recorded, and the apply applies the newest green commit, with no push base. */
+const APPLY_PIPELINE = `${PIPELINE}  apply:\n    steps:\n      - run: chant ci run apply --in-place --env prod --gate pr-apply --forge github\n`;
 const TICK = "jobs:\n  tick:\n    steps:\n      - run: npx --yes @intentius/chant@0.124.33 ci tick\n";
 const PUBLISH = "jobs:\n  publish:\n    steps:\n      - run: npx chant release publish \"$LABEL\"\n";
 
@@ -100,14 +102,22 @@ describe("ci.workflow (WSP151)", () => {
   });
 
   test("trunk-curated with an apply job on merge differs", async () => {
-    const root = repo(complete({ ".github/workflows/chant-pr.yml": PIPELINE.replace("ci run record", "ci run apply") }));
+    const root = repo(complete({ ".github/workflows/chant-pr.yml": APPLY_PIPELINE }));
     expect(await found(root)).toEqual([["ci-workflow-pipeline-differs", null]]);
   });
 
   test("trunk-curated+apply-on-merge with only a record job differs, and with an apply job passes", async () => {
     const decl = declaration({ ci: { workflow: "trunk-curated+apply-on-merge", green: green() } });
     expect(await found(repo(complete({ "chant.workspace.json": decl })))).toEqual([["ci-workflow-pipeline-differs", null]]);
-    expect(await found(repo(complete({ "chant.workspace.json": decl, ".github/workflows/chant-pr.yml": PIPELINE.replace("ci run record", "ci run apply") })))).toEqual([]);
+    expect(await found(repo(complete({ "chant.workspace.json": decl, ".github/workflows/chant-pr.yml": APPLY_PIPELINE })))).toEqual([]);
+  });
+
+  test("trunk-curated+apply-on-merge: an apply of each merge differs, and a pipeline with no record job is missing it (#4168 step 9)", async () => {
+    const decl = declaration({ ci: { workflow: "trunk-curated+apply-on-merge", green: green() } });
+    const perMerge = APPLY_PIPELINE.replace("ci run apply --in-place", 'ci run apply --in-place --base "$BASE_SHA"');
+    expect(await found(repo(complete({ "chant.workspace.json": decl, ".github/workflows/chant-pr.yml": perMerge })))).toEqual([["ci-workflow-pipeline-differs", null]]);
+    const noRecord = PIPELINE.replace("ci run record", "ci run apply");
+    expect(await found(repo(complete({ "chant.workspace.json": decl, ".github/workflows/chant-pr.yml": noRecord })))).toEqual([["ci-workflow-pipeline-missing", null]]);
   });
 
   test("a member's own workflow wins, and a top-level workflow skips members that don't build with chant", async () => {

package/src/workspace/checks/ci-workflow.ts

@@ -106,7 +106,8 @@ export const CI_WORKFLOW_CHECKS: readonly WorkspaceCheck[] = [
       const applyOnMerge = under.some((u) => appliesOnMerge(u.workflow)) || (d.ci?.workflow ? appliesOnMerge(d.ci.workflow) : false);
       const missing = [
         ...(has(PLAN) ? [] : ["a plan job (ci run plan)"]),
-        ...(has(RECORD) || has(APPLY) ? [] : [applyOnMerge ? "an apply job (ci run apply)" : "a record job (ci run record)"]),
+        // #4168 step 9: every merge is recorded, apply on merge or not, since the apply reads the merge records.
+        ...(has(RECORD) ? [] : ["a record job (ci run record)"]),
         ...(has(TICK) ? [] : ["chant ci tick"]),
       ];
       if (missing.length > 0) {
@@ -119,6 +120,11 @@ export const CI_WORKFLOW_CHECKS: readonly WorkspaceCheck[] = [
       } else if (!has(APPLY) && has(RECORD)) {
         const l = commandLines(ctx, RECORD)[0]!;
         finding("ci-workflow-pipeline-differs", `${l.path} records on merge, and the workflow is trunk-curated+apply-on-merge; regenerate with --apply-on-merge`, { treeFile: l.path, line: l.line });
+      } else {
+        // #4168 step 9: an apply measured from a push's base applies each merge; the workflow applies green commits.
+        for (const l of commandLines(ctx, APPLY).filter((c) => /--base\b/.test(c.text) || (/\bcomponents\s+pr-apply\b/.test(c.text) && !/--green\b/.test(c.text)))) {
+          finding("ci-workflow-pipeline-differs", `${l.path} applies each merge, and under trunk-curated+apply-on-merge the apply applies the newest green commit; regenerate with --apply-on-merge`, { treeFile: l.path, line: l.line });
+        }
       }
       if (!has(PUBLISH)) {
         finding("ci-workflow-publish-missing", "no pipeline file runs chant release publish, so a cut release is never published; generate one with chant release workflow");

package/src/workspace/ci-green-cli.ts

@@ -154,7 +154,9 @@ export async function runCiWorkflow(ctx: CommandContext): Promise<number> {
     const sources = readWorkflowSources(repoRoot, fromRepo);
     const scan = workflowsHolding(green, sources);
     // #4169: the triggers and concurrency of the workflows holding a phase that sets build. Refused before anything is written.
-    const edits = buildTriggerEdits(green, sources);
+    // #4220: under a ci.workflow, composed releases' branches run the phases and tick too.
+    const compose = declaration.ci?.workflow !== undefined || declaration.members.some((m) => m.ciWorkflow !== null);
+    const edits = buildTriggerEdits(green, sources, { compose });
     const extra = ctx.args.ciWorkflows ?? [];
     const workflows = [...new Set([...scan.workflows, ...extra])].sort();
     for (const f of scan.unreadable) console.error(`warning: ${f} is not valid YAML, so its jobs were not read`);
@@ -180,10 +182,10 @@ export async function runCiWorkflow(ctx: CommandContext): Promise<number> {
     const workspaceRoot = relative(repoRoot, root).split(sep).join("/") || ".";
     // The install runs in the workspace root, so its lockfile there keys setup-node's npm cache.
     const npmLock = ctx.args.ciInstall && existsSync(join(root, "package-lock.json")) ? (workspaceRoot === "." ? "package-lock.json" : `${workspaceRoot}/package-lock.json`) : undefined;
-    const yaml = renderCiGreenWorkflow({ green, workflows, chantVersion: readerVersion(), workspaceRoot, chant: ctx.args.ciChant, install: ctx.args.ciInstall, npmLock, push, ...(runnerKeySecret ? { runnerKeySecret } : {}) });
+    const yaml = renderCiGreenWorkflow({ green, workflows, chantVersion: readerVersion(), workspaceRoot, chant: ctx.args.ciChant, install: ctx.args.ciInstall, npmLock, push, ...(runnerKeySecret ? { runnerKeySecret } : {}), ...(compose ? { compose } : {}) });
     const written = writeWorkflowFile(target, ciGreenHeader(command, member ? "member" : "root") + yaml);
     if (member) recordGeneratedFiles(member.memberRoot, [{ path: fromRepo, command }]);
-    console.log(`Wrote ${written}: ticks when ${workflows.join(", ")} complete${workflows.length === 1 ? "s" : ""} on ${green.branch}, and every 15 minutes.`);
+    console.log(`Wrote ${written}: ticks when ${workflows.join(", ")} complete${workflows.length === 1 ? "s" : ""} on ${green.branch}${compose ? " or a chant/compose/ branch" : ""}, and every 15 minutes.`);
     for (const e of edits) {
       if (!e.changed) continue;
       const path = writeWorkflowFile(join(repoRoot, e.path), e.text);