@intentius/chant 0.124.34 → 0.124.35

package/src/codegen/release-wiring.test.ts

@@ -44,6 +44,12 @@ function releaseTagShapes(): Array<{ recipe: string; example: string }> {
       .replace(/\$\{?next\}?/g, "9.9.9");
     shapes.push({ recipe: raw, example });
   }
+  // `just release` (#4040) tags nothing itself: the cut makes the tag, and the
+  // recipe pushes it as `git push origin "refs/tags/release/npm/$next"`.
+  for (const m of justfile.matchAll(/git push origin "refs\/tags\/([^"]+)"/g)) {
+    if (m[1] === "$rtag") continue;
+    shapes.push({ recipe: m[1], example: m[1].replace(/\$\{?next\}?/g, "9.9.9") });
+  }
   return shapes;
 }
 
@@ -79,6 +85,7 @@ describe("release wiring: justfile tags vs publish.yml trigger", () => {
     const examples = releaseTagShapes().map((s) => s.example);
     // Whole-repo release and single-lexicon patch. If a recipe stops
     // producing one of these, the assertion above would pass vacuously.
+    expect(examples).toContain("release/npm/9.9.9");
     expect(examples).toContain("chant-v9.9.9");
     expect(examples).toContain("lexicon-docker-v9.9.9");
   });
@@ -124,7 +131,7 @@ describe("release wiring: peer ranges stay in lockstep (#1255)", () => {
     // The rewrite is generic (`with_entries` over every `@intentius/*`
     // peer) rather than named keys — a hand-listed rewrite goes stale the
     // same way the hand-listed publish steps did.
-    const body = recipeBody("release");
+    const body = recipeBody("release-legacy");
     expect(body).toMatch(/\.peerDependencies\s*\|=\s*with_entries/);
     expect(body).toMatch(/startswith\("@intentius\/"\)/);
   });
@@ -150,7 +157,7 @@ describe("release wiring: peer ranges stay in lockstep (#1255)", () => {
   });
 
   it("both recipes keep the committed lockfile in step", () => {
-    for (const recipe of ["release", "release-lexicon"]) {
+    for (const recipe of ["release-legacy", "release-lexicon"]) {
       expect(recipeBody(recipe)).toMatch(/npm install --package-lock-only/);
     }
   });
@@ -162,7 +169,7 @@ describe("release wiring: peer ranges stay in lockstep (#1255)", () => {
  */
 describe("release wiring: preflight gates both recipes (#1255)", () => {
   it("every release recipe runs the preflight before tagging", () => {
-    for (const recipe of ["release", "release-lexicon"]) {
+    for (const recipe of ["release-legacy", "release-lexicon"]) {
       const body = recipeBody(recipe);
       expect(
         body.includes("scripts/release-preflight.sh"),
@@ -183,7 +190,7 @@ describe("release wiring: preflight gates both recipes (#1255)", () => {
  */
 describe("release wiring: release the newest green commit (#2816)", () => {
   it("both recipes tag the commit the preflight chose, not HEAD", () => {
-    for (const recipe of ["release", "release-lexicon"]) {
+    for (const recipe of ["release-legacy", "release-lexicon"]) {
       const body = recipeBody(recipe);
       expect(body).toMatch(/sha=\$\(bash scripts\/release-preflight\.sh/);
       expect(body).toMatch(/release_open "\$sha"/);
@@ -191,7 +198,7 @@ describe("release wiring: release the newest green commit (#2816)", () => {
   });
 
   it("both recipes merge the tag back into main instead of pushing HEAD", () => {
-    for (const recipe of ["release", "release-lexicon"]) {
+    for (const recipe of ["release-legacy", "release-lexicon"]) {
       const body = recipeBody(recipe);
       expect(body).toMatch(/release_ship "\$tag"/);
       expect(body).not.toMatch(/git push/);
@@ -205,16 +212,22 @@ describe("release wiring: release the newest green commit (#2816)", () => {
   });
 
   it("both recipes offer a dry run that stops before committing", () => {
-    for (const recipe of ["release", "release-lexicon"]) {
+    for (const recipe of ["release-legacy", "release-lexicon"]) {
       const body = recipeBody(recipe);
       expect(body.indexOf("RELEASE_DRY_RUN")).toBeGreaterThan(-1);
       expect(body.indexOf("RELEASE_DRY_RUN")).toBeLessThan(body.indexOf("git commit"));
     }
   });
 
-  it("the whole-repo floor reads main as well as the green commit", () => {
-    expect(recipeBody("release")).toMatch(/release_version_at "\$RELEASE_MAIN"/);
-    expect(recipeBody("release-lexicon")).toMatch(/release_version_at "\$RELEASE_MAIN"/);
+  it("the floor reads main as well as the green commit", () => {
+    expect(recipeBody("release-legacy")).toMatch(/release_version_at "\$RELEASE_MAIN"/);
+    // release-lexicon floors through release_lexicon_floor (#4040), which also reads tags and npm.
+    expect(recipeBody("release-lexicon")).toMatch(/release_lexicon_floor \{\{name\}\} "\$sha"/);
+    const lib = readFileSync(join(repoRoot, "scripts", "release-lib.sh"), "utf-8");
+    const floor = lib.slice(lib.indexOf("release_lexicon_floor() {"));
+    expect(floor).toMatch(/release_version_at "\$\{RELEASE_MAIN:-origin\/main\}"/);
+    expect(floor).toMatch(/git tag -l 'release\/npm\/\*'/);
+    expect(floor).toMatch(/npm view "\$pkg" version/);
   });
 
   it("a push to main does not cancel main's chant run; PR runs still cancel", () => {
@@ -226,3 +239,37 @@ describe("release wiring: release the newest green commit (#2816)", () => {
     expect(block).toMatch(/cancel-in-progress: \$\{\{ github\.ref != 'refs\/heads\/main' \}\}/);
   });
 });
+
+/**
+ * #4040 — `just release` cuts chant with its own release command: the
+ * preflight still picks the green commit, `chant release cut --at` cuts it
+ * with no bump commit and no signing, and the recipe pushes the tag the cut
+ * made. Its floor reads every tag, since package.json no longer moves.
+ */
+describe("release wiring: just release runs chant release cut (#4040)", () => {
+  const body = () => recipeBody("release");
+
+  it("cuts the commit the preflight chose, from the release/ member", () => {
+    expect(body()).toMatch(/sha=\$\(bash scripts\/release-preflight\.sh/);
+    expect(body()).toMatch(/cd release && .*release cut "\$next" --at "\$sha"/);
+    expect(body().indexOf("scripts/release-preflight.sh")).toBeLessThan(body().indexOf("release cut"));
+  });
+
+  it("makes no bump commit and signs nothing", () => {
+    expect(body()).not.toMatch(/git commit/);
+    expect(body()).not.toMatch(/--sign/);
+  });
+
+  it("a dry run cuts without --yes and stops before any push", () => {
+    expect(body()).toMatch(/\[ "\$RELEASE_DRY_RUN" = 1 \] \|\| yes=\(--yes\)/);
+    const dry = body().indexOf('if [ "$RELEASE_DRY_RUN" = 1 ]; then');
+    expect(dry).toBeGreaterThan(-1);
+    expect(dry).toBeLessThan(body().indexOf("git push"));
+  });
+
+  it("floors on package.json at the commit and on every chant-v and release/npm tag", () => {
+    expect(body()).toMatch(/release_version_at "\$sha"/);
+    expect(body()).toMatch(/git tag -l 'chant-v\*'/);
+    expect(body()).toMatch(/git tag -l 'release\/npm\/\*'/);
+  });
+});

package/src/components/auto-release.test.ts

@@ -170,6 +170,28 @@ describe("maybeRecordAutoRelease", () => {
     expect(appendReleaseRecordMock).not.toHaveBeenCalled();
   });
 
+  test("#4222: no artifact under a release -> recorded with the release's templates digest", async () => {
+    appendReleaseRecordMock.mockResolvedValue({
+      commit: "c".repeat(40),
+      record: { version: 1, component: "infra", env: "staging", digest: "sha256:tpl", gitSha: "x", runId: "r", timestamp: "t", actor: "alice" },
+    });
+    const outcome = await maybeRecordAutoRelease(
+      { component: "infra", env: "staging", success: true, records: [applyRecord()], runId: "run-1", releaseDigest: "sha256:rel", templatesDigest: "sha256:tpl" },
+      { actor: "alice", gitSha: "a".repeat(40) },
+    );
+    expect(outcome).toMatchObject({ recorded: true });
+    const [input] = appendReleaseRecordMock.mock.calls[0];
+    expect(input).toMatchObject({ digest: "sha256:tpl", releaseDigest: "sha256:rel" });
+  });
+
+  test("#4222: a templates digest without a release is ignored", async () => {
+    const outcome = await maybeRecordAutoRelease(
+      { component: "infra", env: "staging", success: true, records: [applyRecord()], runId: "run-1", templatesDigest: "sha256:tpl" },
+      { actor: "alice" },
+    );
+    expect(outcome).toMatchObject({ recorded: false, reason: "no-digest" });
+  });
+
   test("no resolvable actor -> skipped, not an error", async () => {
     const outcome = await maybeRecordAutoRelease(
       { component: "svc", env: "prod", success: true, records: [publishRecord("sha256:abc")], runId: "run-1" },

package/src/components/auto-release.ts

@@ -103,6 +103,12 @@ export interface AutoReleaseRunInfo {
   inputDigest?: string;
   /** The release the deploy was made under (#4043), recorded as the release record's `releaseDigest`. Set only when the caller named a release; never inferred. */
   releaseDigest?: string;
+  /**
+   * The digest of the templates the release records for this component in
+   * this environment (#4222, `releaseTemplatesDigest`), recorded as `digest`
+   * when the run published no artifact. Set only with `releaseDigest`.
+   */
+  templatesDigest?: string;
 }
 
 /** Opt-out + field-override knobs for auto-release recording, threaded from CLI flags/config (#597: "opt-out-able (flag/config), documented default"). */
@@ -135,7 +141,8 @@ function resolveActor(override?: string): string | undefined {
  *  - `options.disabled` — the opt-out flag/config was set.
  *  - `run.success` false — defensive; callers should not reach here on failure.
  *  - no digest found in the run's records — a component with no publish step
- *    has nothing to bind a release record to.
+ *    has nothing to bind a release record to, unless the run was made under a
+ *    release that records its templates (`templatesDigest`, #4222).
  *  - no resolvable actor — mirrors `runComponentsReleaseRecord`'s hard
  *    requirement; an unattributed record defeats the ledger's purpose.
  *
@@ -159,7 +166,7 @@ export async function maybeRecordAutoRelease(
     return { recorded: false, reason: "run-not-successful" };
   }
 
-  const digest = run.digest ?? extractRunDigest(run.records ?? []);
+  const digest = run.digest ?? extractRunDigest(run.records ?? []) ?? (run.releaseDigest ? run.templatesDigest : undefined);
   if (!digest) {
     return { recorded: false, reason: "no-digest", detail: `component "${run.component}" published no digest-bearing artifact` };
   }

package/src/components/green-cover.test.ts

@@ -0,0 +1,170 @@
+/**
+ * #4168 step 9: apply on merge per green commit. `coverByMerges` checks the
+ * plan at a green commit against the approved plans of the merges since the
+ * last applied one; `resolveGreenTarget` finds those merges and where the
+ * change is measured from.
+ */
+
+import { afterAll, describe, expect, test } from "vitest";
+import { composeChangeSet, type ChangeSetEntry } from "../change-set";
+import { cleanScratch, commitAll, declaration, git, repo, writeFiles } from "../workspace/__fixtures__/contract-repo";
+import { memoryGateLedgerPort } from "../op/gate";
+import { persistChangeSet } from "../lifecycle/change-set-store";
+import { MERGE_RECORD_CONTRACT, MERGE_RECORD_SCHEMA_ID, writeMergeRecord, type MergeRecord } from "../lifecycle/merge-record";
+import { GREEN_APPLY_CONTRACT, readGreenApply, writeGreenApply } from "../lifecycle/green-apply";
+import { coverByMerges, greenOp, resolveGreenTarget, type ApprovedMerge } from "./green-cover";
+
+afterAll(cleanScratch);
+
+const member = (name: string, digest: string) => ({
+  member: name,
+  lexicon: "terraform",
+  planner: "tofu" as const,
+  status: "planned" as const,
+  planDigest: `jcs1-sha256:${digest.repeat(64)}`,
+  holes: [],
+});
+const write = (name: string, cidr: string, action: ChangeSetEntry["action"] = "update"): ChangeSetEntry => ({
+  member: name,
+  lexicon: "terraform",
+  planner: "tofu",
+  address: `${name}.main`,
+  type: "aws_subnet",
+  action,
+  attributes: action === "no-op" ? [] : [{ path: "cidr", after: cidr }],
+});
+const merge = (commit: string, pr: number, parts: Array<[string, string, string]>, approvedBy = [`github:r${pr}`]): ApprovedMerge => ({
+  commit,
+  pr,
+  doc: composeChangeSet(parts.map(([name, digest, cidr]) => ({ member: member(name, digest), entries: [write(name, cidr)] }))),
+  approvedBy,
+});
+
+describe("coverByMerges", () => {
+  test("each member is checked against the newest merge that planned it, and the approvers of the merges used are kept", () => {
+    const merges = [merge("a".repeat(40), 1, [["net", "1", "10.0.0.0/16"], ["app", "2", "10.1.0.0/16"]]), merge("b".repeat(40), 2, [["app", "3", "10.2.0.0/16"]])];
+    // net as #1 approved it, app as #2 (the newer one) approved it.
+    const fresh = composeChangeSet([
+      { member: member("net", "1"), entries: [write("net", "10.0.0.0/16")] },
+      { member: member("app", "3"), entries: [write("app", "10.2.0.0/16")] },
+    ]);
+    expect(coverByMerges(fresh, merges)).toEqual({ covered: true, uncovered: [], approvedBy: ["github:r1", "github:r2"], coveredBy: ["a".repeat(40), "b".repeat(40)] });
+  });
+
+  test("an older merge's plan does not cover a member a newer merge planned again", () => {
+    const merges = [merge("a".repeat(40), 1, [["app", "2", "10.1.0.0/16"]]), merge("b".repeat(40), 2, [["app", "3", "10.2.0.0/16"]])];
+    const fresh = composeChangeSet([{ member: member("app", "4"), entries: [write("app", "10.1.0.0/16")] }]);
+    const cover = coverByMerges(fresh, merges);
+    expect(cover.covered).toBe(false);
+    expect(cover.uncovered).toEqual(["app now writes app.main.cidr to a different value than the approved plan (checked against #2)"]);
+  });
+
+  test("a member no merge planned is not covered, and a member with nothing to do needs no approval", () => {
+    const merges = [merge("a".repeat(40), 1, [["net", "1", "10.0.0.0/16"]])];
+    const fresh = composeChangeSet([
+      { member: member("net", "1"), entries: [write("net", "10.0.0.0/16")] },
+      { member: member("edge", "5"), entries: [write("edge", "10.9.0.0/16")] },
+      { member: member("idle", "6"), entries: [write("idle", "", "no-op")] },
+    ]);
+    expect(coverByMerges(fresh, merges)).toMatchObject({
+      covered: false,
+      uncovered: ["edge: no merge since the last applied green commit had an approved plan for it"],
+      coveredBy: ["a".repeat(40)],
+    });
+    expect(coverByMerges(composeChangeSet([{ member: member("idle", "6"), entries: [write("idle", "", "no-op")] }]), [])).toMatchObject({ covered: true, approvedBy: [] });
+  });
+
+  test("a green commit's own gate is recorded under green-<sha>", () => {
+    expect(greenOp("c".repeat(40))).toBe(`green-${"c".repeat(12)}`);
+    expect(greenOp("c".repeat(40), "net")).toBe(`green-${"c".repeat(12)}-net`);
+  });
+});
+
+describe("resolveGreenTarget", () => {
+  const GREEN = { branch: "main", phases: { test: ["test"] }, require: ["test"], source: "runs" };
+
+  /** A repository with three commits on main: c1 and c3 tagged green, c2 not. */
+  function history(): { root: string; c1: string; c2: string; c3: string } {
+    const root = repo({ "chant.workspace.json": declaration([], { ci: { green: GREEN } }), "a.txt": "1\n" }, true);
+    git(root, "branch", "-M", "main");
+    const c1 = git(root, "rev-parse", "HEAD");
+    writeFiles(root, { "a.txt": "2\n" });
+    const c2 = commitAll(root, "two");
+    writeFiles(root, { "a.txt": "3\n" });
+    const c3 = commitAll(root, "three");
+    for (const c of [c1, c3]) git(root, "tag", `ci/green/${c}`, c);
+    return { root, c1, c2, c3 };
+  }
+
+  const record = (commit: string, base: string, pr: number, plan: MergeRecord["plan"], digest: string | null): MergeRecord => ({
+    $schema: MERGE_RECORD_SCHEMA_ID,
+    contract: MERGE_RECORD_CONTRACT,
+    commit,
+    base,
+    env: "prod",
+    source: { kind: "pull-request", pr },
+    op: `pr-${pr}`,
+    gate: "pr-apply",
+    digest,
+    plan,
+    approvedBy: [],
+    components: ["net"],
+    recordedAt: "2026-10-21T00:00:00Z",
+  });
+
+  test("HEAD must be green", async () => {
+    const { root, c2 } = history();
+    git(root, "checkout", "-q", c2);
+    const r = await resolveGreenTarget({ cwd: root, env: "prod", gate: "pr-apply" });
+    expect(r).toMatchObject({ status: "error", message: expect.stringContaining("is not a green commit") });
+  });
+
+  test("with nothing applied it measures from the green commit before, else --base, and lists the merges with a standing approval", async () => {
+    const { root, c1, c2, c3 } = history();
+    const approved = composeChangeSet([{ member: member("net", "1"), entries: [write("net", "10.0.0.0/16")] }]);
+    await persistChangeSet(approved, { cwd: root });
+    await writeMergeRecord(record(c2, c1, 2, "approved", approved.digest), { cwd: root });
+    await writeMergeRecord(record(c3, c2, 3, "unapproved", null), { cwd: root });
+    const ledger = memoryGateLedgerPort({
+      resolutions: [{ version: 1, kind: "resolution", op: "pr-2", gate: "pr-apply", resolvedBy: "github:alice", timestamp: "2026-10-21T00:00:00Z", planDigest: approved.digest }],
+    });
+
+    const r = await resolveGreenTarget({ cwd: root, env: "prod", gate: "pr-apply", ledger });
+    expect(r.status).toBe("target");
+    if (r.status !== "target") return;
+    expect(r.target).toMatchObject({ commit: c3, base: c1, baseFrom: "previous-green", merges: [c2, c3], prs: [2, 3] });
+    expect(r.target.approved.map((m) => [m.commit, m.pr, m.doc.digest, m.approvedBy])).toEqual([[c2, 2, approved.digest, ["github:alice"]]]);
+
+    // No approval stands for #2 any more: nothing covers.
+    const none = await resolveGreenTarget({ cwd: root, env: "prod", gate: "pr-apply", ledger: memoryGateLedgerPort() });
+    expect(none.status === "target" && none.target.approved).toEqual([]);
+
+    const flagged = await resolveGreenTarget({ cwd: root, env: "prod", gate: "pr-apply", base: c2, ledger });
+    expect(flagged).toMatchObject({ status: "target", target: { base: c2, baseFrom: "flag", merges: [c3] } });
+  });
+
+  test("once a green commit is applied the next measures from it, and applying it again is nothing", async () => {
+    const { root, c1, c2, c3 } = history();
+    const applied = { contract: GREEN_APPLY_CONTRACT, env: "prod", commit: c2, base: c1, digest: "jcs1-sha256:x", approval: "gate" as const, approvedBy: [], merges: [c2], appliedAt: "2026-10-21T00:00:00Z" };
+    await writeGreenApply(applied, { cwd: root });
+    expect(await readGreenApply("prod", { cwd: root })).toEqual(applied);
+    // The record wins over --base.
+    expect(await resolveGreenTarget({ cwd: root, env: "prod", gate: "pr-apply", base: c1, ledger: memoryGateLedgerPort() })).toMatchObject({
+      status: "target",
+      target: { base: c2, baseFrom: "applied", merges: [c3], prs: [] },
+    });
+    await writeGreenApply({ ...applied, commit: c3, base: c2, merges: [c3] }, { cwd: root });
+    expect(await resolveGreenTarget({ cwd: root, env: "prod", gate: "pr-apply" })).toEqual({ status: "applied", commit: c3 });
+    // Another environment has applied nothing.
+    expect(await resolveGreenTarget({ cwd: root, env: "staging", gate: "pr-apply", ledger: memoryGateLedgerPort() })).toMatchObject({ status: "target", target: { base: c1 } });
+  });
+
+  test("without ci.green there is no green commit to apply", async () => {
+    const root = repo({ "chant.workspace.json": declaration([]), "a.txt": "1\n" }, true);
+    expect(await resolveGreenTarget({ cwd: root, env: "prod", gate: "pr-apply" })).toMatchObject({
+      status: "error",
+      message: expect.stringContaining("apply on merge applies green commits"),
+      hint: expect.stringContaining("ci.green"),
+    });
+  });
+});

package/src/components/green-cover.ts

@@ -0,0 +1,186 @@
+/**
+ * Apply on merge per green commit (#4168 step 9): whether the change sets
+ * approved for the merges since the last applied green commit cover the plan
+ * at the green one.
+ *
+ * Each member of the fresh plan is checked against the newest approved change
+ * set that planned it, with the same rule `pr-apply` uses for one pull request
+ * (`planCoveredBy`, ./pr-run.ts). A member with nothing to do is covered by
+ * nothing. Any member left uncovered sends the whole plan to a gate of its own,
+ * bound to the combined digest.
+ */
+
+import { execFileSync } from "node:child_process";
+import type { ChangeSetDocument } from "../change-set";
+import type { GateLedgerPort } from "../op/gate";
+import { planCoveredBy } from "./pr-run";
+
+/** One merge's approved change set, with who approved it. */
+export interface ApprovedMerge {
+  commit: string;
+  pr?: number;
+  doc: ChangeSetDocument;
+  approvedBy: readonly string[];
+}
+
+export interface GreenCover {
+  covered: boolean;
+  /** Why each uncovered member is not covered, one line each. */
+  uncovered: string[];
+  /** The approvers of the change sets that covered a member, sorted. */
+  approvedBy: string[];
+  /** The merges whose approval covered a member, in trunk order. */
+  coveredBy: string[];
+}
+
+/** Whether `member` has anything to apply in `doc`. */
+function hasWork(doc: ChangeSetDocument, member: string): boolean {
+  const m = doc.members.find((x) => x.member === member);
+  if (m && m.status === "failed") return true;
+  if (doc.entries.some((e) => e.member === member && e.action !== "no-op" && e.action !== "read")) return true;
+  return (doc.sideEffects ?? []).some((s) => s.member === member);
+}
+
+/**
+ * Check `fresh` against `merges`, given oldest first, as the first-parent
+ * history between the last applied green commit and this one runs.
+ */
+export function coverByMerges(fresh: ChangeSetDocument, merges: readonly ApprovedMerge[]): GreenCover {
+  const uncovered: string[] = [];
+  const approvers = new Set<string>();
+  const used = new Set<string>();
+  for (const member of fresh.members.map((m) => m.member)) {
+    if (!hasWork(fresh, member)) continue;
+    const newest = [...merges].reverse().find((m) => m.doc.members.some((x) => x.member === member));
+    if (!newest) {
+      uncovered.push(`${member}: no merge since the last applied green commit had an approved plan for it`);
+      continue;
+    }
+    const why = planCoveredBy(newest.doc, fresh, member);
+    if (why) {
+      uncovered.push(`${why} (checked against ${newest.pr !== undefined ? `#${newest.pr}` : newest.commit.slice(0, 12)})`);
+      continue;
+    }
+    used.add(newest.commit);
+    for (const a of newest.approvedBy) approvers.add(a);
+  }
+  return {
+    covered: uncovered.length === 0,
+    uncovered,
+    approvedBy: [...approvers].sort(),
+    coveredBy: merges.filter((m) => used.has(m.commit)).map((m) => m.commit),
+  };
+}
+
+/** The green commit `pr-apply --green` applies, what it is measured from, and the approved merges between. */
+export interface GreenTarget {
+  commit: string;
+  /** The last green commit applied to the environment, else `--base`, else the green commit before this one, else its parent. */
+  base: string;
+  /** Where `base` came from. */
+  baseFrom: "applied" | "flag" | "previous-green" | "parent";
+  /** The first-parent commits after `base` up to `commit`, oldest first. */
+  merges: string[];
+  /** Their pull requests, from the merge records, in trunk order. */
+  prs: number[];
+  /** The merges whose approved change set still stands, oldest first. */
+  approved: ApprovedMerge[];
+}
+
+export type GreenTargetResult =
+  | { status: "target"; target: GreenTarget }
+  /** The checkout is the green commit last applied. */
+  | { status: "applied"; commit: string }
+  | { status: "error"; message: string; hint?: string };
+
+function gitOut(cwd: string, args: string[]): string | undefined {
+  try {
+    return execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Resolve the green target for `env` at `cwd`'s HEAD (#4168 step 9). HEAD must
+ * carry a counting `ci/green` tag and no `ci/revoked` one, judged by the
+ * declaration's `ci.green` as `release cut` judges them. Reads the local tags
+ * and `chant/lifecycle` and never fetches.
+ */
+export async function resolveGreenTarget(req: { cwd: string; env: string; base?: string; gate: string; ledger?: GateLedgerPort }): Promise<GreenTargetResult> {
+  const { readGreen, CI_GREEN_TAG_PREFIX } = await import("../workspace/ci-green");
+  const { judgedCiTags } = await import("../lifecycle/release-revocation");
+  let green: ReturnType<typeof readGreen>["green"];
+  let top: string;
+  try {
+    ({ green, top } = readGreen(req.cwd));
+  } catch (err) {
+    return {
+      status: "error",
+      message: `apply on merge applies green commits (#4168), and ${err instanceof Error ? err.message : String(err)}`,
+      hint: "Declare ci.green in chant.workspace.json, or run chant ci init --workflow trunk-curated+apply-on-merge.",
+    };
+  }
+  const head = gitOut(req.cwd, ["rev-parse", "HEAD"]);
+  if (!head) return { status: "error", message: "pr-apply --green applies the checkout's HEAD, and it has none" };
+  const tags = await judgedCiTags(top, green);
+  const counts = (sha: string) => tags.green.has(sha) && !tags.revoked.has(sha);
+  if (!counts(head)) {
+    return {
+      status: "error",
+      message: `${head.slice(0, 12)} is not a green commit (no counting ${CI_GREEN_TAG_PREFIX}${head.slice(0, 12)}… tag, or a ci/revoked one), so apply on merge does not apply it`,
+      hint: "Check out the newest green commit first: git checkout --detach \"$(chant ci last-green)\"",
+    };
+  }
+
+  const { readGreenApply } = await import("../lifecycle/green-apply");
+  const last = await readGreenApply(req.env, { cwd: req.cwd });
+  if (last?.commit === head) return { status: "applied", commit: head };
+  let base: string | undefined;
+  let baseFrom: GreenTarget["baseFrom"] = "applied";
+  if (last && gitOut(req.cwd, ["merge-base", "--is-ancestor", last.commit, head]) !== undefined) base = last.commit;
+  if (!base && req.base) {
+    base = gitOut(req.cwd, ["rev-parse", "--verify", "--quiet", `${req.base}^{commit}`]);
+    baseFrom = "flag";
+    if (!base) return { status: "error", message: `--base ${req.base} names no commit here` };
+  }
+  if (!base) {
+    const before = (gitOut(req.cwd, ["rev-list", "--first-parent", `${head}^`]) ?? "").split("\n").filter(Boolean);
+    base = before.find(counts);
+    baseFrom = "previous-green";
+    if (!base) {
+      base = before[0];
+      baseFrom = "parent";
+    }
+  }
+  if (!base) return { status: "error", message: `${head.slice(0, 12)} is a root commit, so there is nothing to measure its change from; pass --base` };
+
+  const merges = (gitOut(req.cwd, ["rev-list", "--first-parent", "--reverse", `${base}..${head}`]) ?? "").split("\n").filter(Boolean);
+  const { readMergeRecord } = await import("../lifecycle/merge-record");
+  const { readStoredChangeSet } = await import("../lifecycle/change-set-store");
+  const { gitGateLedgerPort } = await import("../op/gate");
+  const { decidePrGate, readOnlyLedger, approvalOf } = await import("./pr-run");
+  const prs: number[] = [];
+  const approved: ApprovedMerge[] = [];
+  for (const commit of merges) {
+    const record = await readMergeRecord(commit, { cwd: req.cwd }).catch(() => null);
+    if (!record || record.env !== req.env) continue;
+    const pr = record.source.kind === "pull-request" ? record.source.pr : undefined;
+    if (pr !== undefined) prs.push(pr);
+    // The digest a person approved: the merged plan's when it matched, else the one approved before it moved.
+    const digest = record.plan === "approved" ? record.digest : record.plan === "changed" ? record.approvedDigest : undefined;
+    if (!digest || !record.op) continue;
+    const stored = await readStoredChangeSet(digest, { cwd: req.cwd }).catch(() => ({ status: "missing" as const }));
+    if (stored.status !== "found") continue;
+    // The approval must still stand: one revoked since the merge covers nothing.
+    const check = await decidePrGate(readOnlyLedger(req.ledger ?? gitGateLedgerPort()), { op: record.op, gate: record.gate ?? req.gate, digest }).catch(() => undefined);
+    if (!check?.satisfied) continue;
+    approved.push({ commit, ...(pr !== undefined ? { pr } : {}), doc: stored.document, approvedBy: approvalOf(check).approvedBy ?? [] });
+  }
+  return { status: "target", target: { commit: head, base, baseFrom, merges, prs, approved } };
+}
+
+/** The op a green commit's own gate is recorded under: `green-<sha>`, or `green-<sha>-<member>` for a workspace member. */
+export function greenOp(commit: string, member?: string): string {
+  return member ? `green-${commit.slice(0, 12)}-${member}` : `green-${commit.slice(0, 12)}`;
+}

package/src/components/pr-pipeline.test.ts

@@ -10,7 +10,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterAll, describe, expect, test } from "vitest";
 import { EMPTY_TREE_SHA } from "./changed-files";
-import { githubBaseFallback, gitlabBaseFallback, prLoopJobs } from "./pr-pipeline";
+import { githubBaseFallback, gitlabBaseFallback, greenCheckout, GREEN_TICK_WORKFLOW, prLoopJobs } from "./pr-pipeline";
 
 const ZEROS = "0".repeat(40);
 const dir = mkdtempSync(join(tmpdir(), "chant-pr-base-"));
@@ -90,11 +90,21 @@ describe("gitlabBaseFallback", () => {
 });
 
 describe("prLoopJobs", () => {
-  test("every forge's apply settles its base first; no plan does", () => {
+  test("every forge's record settles its base first; no plan does, and the apply checks out the newest green commit (#4168 step 9)", () => {
     for (const forge of ["github", "forgejo", "gitlab"] as const) {
-      const [plan, apply] = prLoopJobs(forge, "prod", { branch: "trunk" });
+      const [plan, apply, record] = prLoopJobs(forge, "prod", { branch: "trunk" });
       expect(plan!.setup).toBeUndefined();
-      expect(apply!.setup).toEqual([forge === "gitlab" ? gitlabBaseFallback("trunk") : githubBaseFallback("trunk")]);
+      expect(record!.setup).toEqual([forge === "gitlab" ? gitlabBaseFallback("trunk") : githubBaseFallback("trunk")]);
+      expect(apply!.setup).toBeUndefined();
+      expect(apply!.checkout).toEqual([greenCheckout('"trunk"')]);
+      expect(apply!.env).not.toHaveProperty("BASE_SHA");
+      expect(apply!.command).toContain("pr-apply --green");
+      expect(apply!.run.command).not.toContain("--base");
     }
   });
+
+  test("the green tick workflow's name is the one ci workflow writes", async () => {
+    const { CI_GREEN_WORKFLOW_NAME } = await import("../workspace/ci-green-workflow");
+    expect(GREEN_TICK_WORKFLOW).toBe(CI_GREEN_WORKFLOW_NAME);
+  });
 });