@intentius/chant 0.124.28 → 0.124.29

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

@@ -8,7 +8,7 @@ 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 { cutRelease, differingBuildSteps, ReleaseCutError } from "./release-cut";
+import { cutRelease, differingBuildSteps, planRelease, ReleaseCutError } from "./release-cut";
 import {
   appendCut,
   computeReleaseDigest,
@@ -149,7 +149,16 @@ describe("cutRelease", () => {
       expect(await readReleaseTemplate(prod.templates[0].digest, { cwd: dir })).toBe(`{"env":"prod"}\n`);
       const { cuts } = await readCuts({ cwd: dir });
       expect(cuts).toEqual([
-        { version: 1, releaseDigest: release.releaseDigest, label: "v1.0.0", actor: "alice", timestamp: "2026-10-16T10:00:00.000Z", runOrigin: null, signature: null },
+        {
+          version: 1,
+          releaseDigest: release.releaseDigest,
+          label: "v1.0.0",
+          actor: "alice",
+          timestamp: "2026-10-16T10:00:00.000Z",
+          runId: `local-${Date.parse("2026-10-16T10:00:00.000Z")}`,
+          runOrigin: { forge: "local" },
+          signature: null,
+        },
       ]);
       expect(git(dir, "ls-tree", "-r", "--name-only", "chant/lifecycle").split("\n").filter((p) => p.endsWith("releases.jsonl"))).toEqual([]);
       expect(await resolveRelease("v1.0.0", { cwd: dir })).toEqual({ release, label: "v1.0.0" });
@@ -409,3 +418,66 @@ describe("differingBuildSteps", () => {
     expect(differingBuildSteps([t("dev", { a: [{ x: 1 }], b: [{ y: 1 }] }), t("prod", { a: [{ x: 2 }], b: [{ y: 1 }] }), t("qa", { c: [] })])).toEqual([{ component: "a", envs: ["dev", "prod"] }]);
   });
 });
+
+describe("the dry run of a cut (#4027)", () => {
+  const plan = (dir: string, compiler: TargetCompiler, label: string | null) =>
+    planRelease({ cwd: dir, compiler, label, actor: "alice", env: {}, now: () => new Date("2026-10-16T10:00:00.000Z") });
+
+  test("compiles every environment and says what it would build, without building, storing or cutting", () =>
+    withTestDir(async (dir) => {
+      green(dir, initRepo(dir));
+      const compiler = fixtureCompiler();
+      const p = await plan(dir, compiler, "v1.0.0");
+      expect(compiler.compiled).toEqual(["dev", "staging", "prod"]);
+      expect(compiler.built).toEqual([]);
+      expect(p).toMatchObject({ label: "v1.0.0", releaseDigest: null, alreadyCut: null, build: [{ component: "api", env: "dev" }], reused: [], signatureRequired: false });
+      expect(p.targets.map((t) => [t.env, t.templates])).toEqual([
+        ["dev", [{ component: "api", path: "dist/api.template.json" }]],
+        ["staging", [{ component: "api", path: "dist/api.template.json" }]],
+        ["prod", [{ component: "api", path: "dist/api.template.json" }]],
+      ]);
+      expect(spawnSync("git", ["rev-parse", "--verify", "--quiet", "refs/heads/chant/lifecycle"], { cwd: dir }).status).not.toBe(0);
+    }));
+
+  test("knows the digest when every artifact is carried, and that it is already cut", () =>
+    withTestDir(async (dir) => {
+      green(dir, initRepo(dir));
+      const first = await cut(dir, fixtureCompiler(), "v1.0.0");
+      const sha = commitFile(dir, "README.md", "docs only\n");
+      green(dir, sha);
+      const p = await plan(dir, fixtureCompiler(), "v1.1.0");
+      expect(p.build).toEqual([]);
+      expect(p.reused).toEqual([{ component: "api", from: first.release.releaseDigest }]);
+      const second = await cut(dir, fixtureCompiler(), "v1.1.0");
+      expect(p.releaseDigest).toBe(second.release.releaseDigest);
+      expect((await plan(dir, fixtureCompiler(), "v1.1.0")).alreadyCut).toBe(second.release.releaseDigest);
+      expect((await plan(dir, fixtureCompiler(), null)).alreadyCut).toBe(second.release.releaseDigest);
+    }));
+
+  test("refuses a label another commit's release holds, and one that is not a label", () =>
+    withTestDir(async (dir) => {
+      green(dir, initRepo(dir));
+      await cut(dir, fixtureCompiler(), "v1.0.0");
+      green(dir, commitFile(dir, "api/Dockerfile", "FROM busybox\n"));
+      const taken = await plan(dir, fixtureCompiler(), "v1.0.0").catch((e: unknown) => e);
+      expect(taken).toBeInstanceOf(ReleaseLabelError);
+      expect((taken as ReleaseLabelError).code).toBe("release-label-taken");
+      expect((taken as ReleaseLabelError).message).toMatch(/cut from commit [0-9a-f]{12}/);
+      expect(((await plan(dir, fixtureCompiler(), "-bad").catch((e: unknown) => e)) as ReleaseLabelError).code).toBe("release-label-invalid");
+    }));
+
+  test("lists each component's publish steps with the environments whose deploy runs them", () =>
+    withTestDir(async (dir) => {
+      green(dir, initRepo(dir));
+      const base = fixtureCompiler();
+      const compiler: TargetCompiler = {
+        ...base,
+        async compile(env) {
+          const t = await base.compile(env);
+          return { ...t, publishSteps: { api: [{ kind: "publish-image", from: "archive", to: "$env.registry" }] } };
+        },
+      };
+      const p = await plan(dir, compiler, null);
+      expect(p.publishSteps).toEqual([{ component: "api", kind: "publish-image", to: "$env.registry", envs: ["dev", "staging", "prod"] }]);
+    }));
+});

package/src/lifecycle/release-cut.ts

@@ -43,10 +43,14 @@ import { resolveMemberLedger } from "./member-ledger";
 import { resolveCiRun } from "./release-ledger";
 import {
   appendCut,
+  invalidLabel,
+  labelsByDigest,
   makeRelease,
   persistRelease,
   readAllReleases,
   readCuts,
+  readRelease,
+  ReleaseLabelError,
   type Release,
   type ReleaseArtifact,
   type ReleaseCut,
@@ -136,15 +140,10 @@ export async function greenState(
   sha: string,
   green: import("../workspace/declaration").CiGreen | null = null,
 ): Promise<{ state: "green" | "revoked" | "none"; ignored: Array<{ tag: string; status: string; reason: string }> }> {
-  const { readCiTags } = await import("../workspace/ci-green");
-  const base = green
-    ? (tryGit(top, ["rev-parse", "--verify", "--quiet", `refs/remotes/origin/${green.branch}^{commit}`]) ??
-      tryGit(top, ["rev-parse", "--verify", "--quiet", `refs/heads/${green.branch}^{commit}`]) ??
-      tryGit(top, ["rev-parse", "HEAD"]))
-    : null;
-  let tags: ReturnType<typeof readCiTags>;
+  const { judgedCiTags } = await import("./release-revocation");
+  let tags: Awaited<ReturnType<typeof judgedCiTags>>;
   try {
-    tags = readCiTags(top, green, base);
+    tags = await judgedCiTags(top, green);
   } catch (err) {
     const { WorkspaceReadError } = await import("../workspace/declaration");
     if (err instanceof WorkspaceReadError) throw new ReleaseCutError("declaration-invalid", err.message);
@@ -186,15 +185,28 @@ async function previousRelease(top: string, commit: string, cwd: string): Promis
   return candidates[0]?.r;
 }
 
+/** What every cut and every dry run reads and compiles before it decides. */
+interface Prepared {
+  cwd: string;
+  commit: string;
+  envs: readonly string[];
+  compiled: CompiledTarget[];
+  releaseRule: ReturnType<typeof import("../workspace/identity").releaseRuleFrom>;
+  /** The components to build, by the environment they are built in. */
+  toBuild: Map<string, string[]>;
+  /** The artifacts carried from an earlier release. */
+  carried: ReleaseArtifact[];
+  reused: CutResult["reused"];
+  member: string | null;
+}
+
 /**
- * Cut a release of the member at `req.cwd` from its checkout's `HEAD`. Writes
- * the release and the cut to the local `chant/lifecycle` branch and does not
- * push. Throws {@link ReleaseCutError} before anything is written when the
- * commit isn't green, the tree is dirty, or an environment can't be compiled
- * to the same artifacts, and `ReleaseLabelError` (./release-store.ts) when the
- * label is taken or the release already carries another one.
+ * The checks and the compile a cut makes before it builds or writes: the
+ * commit is green and not revoked, the cut is signed when the release gate
+ * asks, the tree is clean, every environment compiles with the same build
+ * steps, and which artifacts are carried from an earlier release.
  */
-export async function cutRelease(req: CutRequest): Promise<CutResult> {
+async function prepare(req: CutRequest): Promise<Prepared> {
   const cwd = resolve(req.cwd);
   const top = tryGit(cwd, ["rev-parse", "--show-toplevel"]);
   if (!top) throw new ReleaseCutError("not-a-git-repository", "a release is cut from a commit, and this directory is not in a git repository");
@@ -296,11 +308,22 @@ export async function cutRelease(req: CutRequest): Promise<CutResult> {
     }
     toBuild.set(target.env, [...(toBuild.get(target.env) ?? []), component]);
   }
-  for (const env of envs) {
-    const names = toBuild.get(env);
-    if (names) artifacts.push(...(await req.compiler.buildArtifacts(env, names)));
-  }
+  const ledger = await resolveMemberLedger(cwd);
+  return {
+    cwd,
+    commit,
+    envs,
+    compiled,
+    releaseRule,
+    toBuild,
+    carried: artifacts,
+    reused,
+    member: ledger.members.length > 0 ? ledger.members.join("/") : null,
+  };
+}
 
+/** The targets and template bytes of a compile, each template by its content digest. */
+function targetsOf(compiled: readonly CompiledTarget[]): { targets: ReleaseTarget[]; templates: TemplateContent[] } {
   const templates: TemplateContent[] = [];
   const targets: ReleaseTarget[] = compiled.map((t) => ({
     env: t.env,
@@ -311,9 +334,121 @@ export async function cutRelease(req: CutRequest): Promise<CutResult> {
       return { component: tpl.component, path: tpl.path, digest };
     }),
   }));
+  return { targets, templates };
+}
 
-  const ledger = await resolveMemberLedger(cwd);
-  const release = makeRelease({ member: ledger.members.length > 0 ? ledger.members.join("/") : null, commit, artifactDigests: artifacts, targets });
+/** What a dry run of the cut found (#4027): what the cut would do, with nothing built, signed or written. */
+export interface CutPlan {
+  commit: string;
+  member: string | null;
+  label: string | null;
+  /** The release's digest when no artifact needs building, so it is known now; null when a build decides it. */
+  releaseDigest: string | null;
+  /** The digest already cut under `label`, or this digest when it is already cut: the cut would then write no new release. */
+  alreadyCut: string | null;
+  /** Each environment's target: its params, and its templates by component and path. */
+  targets: Array<{ env: string; params: ReleaseTarget["params"]; templates: Array<{ component: string | null; path: string }> }>;
+  /** The components whose artifacts would be built, and the environment each is built in. */
+  build: Array<{ component: string; env: string }>;
+  /** The components whose artifacts would be carried from an earlier release. */
+  reused: CutResult["reused"];
+  /** Each component's publish steps, with the environments whose deploy runs them. */
+  publishSteps: Array<{ component: string; kind: string; to: string | null; envs: string[] }>;
+  /** Whether the release gate in identity.gates requires a signed cut. */
+  signatureRequired: boolean;
+}
+
+/**
+ * The dry run of {@link cutRelease} (#4027): the same checks and compile,
+ * then what the cut would build, carry and record, without building an
+ * artifact, signing, or writing anything. Throws what the cut throws before
+ * it builds, and `ReleaseLabelError` when the label is invalid or names a
+ * release of another commit.
+ */
+export async function planRelease(req: CutRequest): Promise<CutPlan> {
+  const p = await prepare(req);
+  const { targets } = targetsOf(p.compiled);
+  const build: CutPlan["build"] = [];
+  for (const env of p.envs) for (const component of p.toBuild.get(env) ?? []) build.push({ component, env });
+  const releaseDigest = build.length === 0 ? makeRelease({ member: p.member, commit: p.commit, artifactDigests: p.carried, targets }).releaseDigest : null;
+
+  const { cuts } = await readCuts({ cwd: p.cwd });
+  const labels = labelsByDigest(cuts);
+  let alreadyCut: string | null = null;
+  if (req.label !== null) {
+    const why = invalidLabel(req.label);
+    if (why) throw new ReleaseLabelError("release-label-invalid", why);
+    const named = [...labels].find(([, l]) => l === req.label)?.[0];
+    if (named !== undefined) {
+      const other = await readRelease(named, { cwd: p.cwd });
+      const sameCommit = other?.commit === p.commit;
+      if (!sameCommit || (releaseDigest !== null && named !== releaseDigest)) {
+        throw new ReleaseLabelError(
+          "release-label-taken",
+          `the label "${req.label}" already names release ${named}${other && !sameCommit ? `, cut from commit ${other.commit.slice(0, 12)}` : ""}`,
+        );
+      }
+      alreadyCut = named;
+    }
+  }
+  if (releaseDigest !== null && alreadyCut === null && cuts.some((c) => c.releaseDigest === releaseDigest)) {
+    const own = labels.get(releaseDigest);
+    if (own !== undefined && req.label !== null && own !== req.label) {
+      throw new ReleaseLabelError("release-already-labelled", `release ${releaseDigest} is already labelled "${own}", and a release takes one label`);
+    }
+    alreadyCut = releaseDigest;
+  }
+
+  const steps = new Map<string, CutPlan["publishSteps"][number]>();
+  for (const t of p.compiled) {
+    for (const [component, list] of Object.entries(t.publishSteps ?? {})) {
+      for (const step of list as Array<{ kind?: unknown; to?: unknown }>) {
+        const kind = typeof step.kind === "string" ? step.kind : "publish";
+        const to = typeof step.to === "string" ? step.to : null;
+        const key = JSON.stringify([component, kind, to]);
+        const entry = steps.get(key) ?? { component, kind, to, envs: [] };
+        if (!entry.envs.includes(t.env)) entry.envs.push(t.env);
+        steps.set(key, entry);
+      }
+    }
+  }
+
+  return {
+    commit: p.commit,
+    member: p.member,
+    label: req.label,
+    releaseDigest,
+    alreadyCut,
+    targets: targets.map((t) => ({ env: t.env, params: t.params, templates: t.templates.map(({ component, path }) => ({ component, path })) })),
+    build,
+    reused: p.reused,
+    publishSteps: [...steps.values()],
+    signatureRequired: p.releaseRule.requirement !== null,
+  };
+}
+
+/**
+ * Cut a release of the member at `req.cwd` from its checkout's `HEAD`. Writes
+ * the release and the cut to the local `chant/lifecycle` branch and does not
+ * push. Throws {@link ReleaseCutError} before anything is written when the
+ * commit isn't green, the tree is dirty, or an environment can't be compiled
+ * to the same artifacts, and `ReleaseLabelError` (./release-store.ts) when the
+ * label is taken or the release already carries another one.
+ *
+ * The cut line names its run (#4027): the CI run's id and origin in CI, and
+ * outside CI an id minted from the cut's time, `local-<epoch ms>`, with the
+ * origin `{ forge: "local" }`.
+ */
+export async function cutRelease(req: CutRequest): Promise<CutResult> {
+  const p = await prepare(req);
+  const { cwd, commit, compiled, releaseRule, reused } = p;
+  const artifacts = [...p.carried];
+  for (const env of p.envs) {
+    const names = p.toBuild.get(env);
+    if (names) artifacts.push(...(await req.compiler.buildArtifacts(env, names)));
+  }
+  const { targets, templates } = targetsOf(compiled);
+  const release = makeRelease({ member: p.member, commit, artifactDigests: artifacts, targets });
   const timestamp = (req.now ?? (() => new Date()))().toISOString();
   const signed = { releaseDigest: release.releaseDigest, label: req.label, actor: req.actor, timestamp };
   let signature: string | null = null;
@@ -352,7 +487,8 @@ export async function cutRelease(req: CutRequest): Promise<CutResult> {
       label: req.label,
       actor: req.actor,
       timestamp,
-      runOrigin: ci?.runOrigin ?? null,
+      runId: ci?.runId ?? `local-${Date.parse(timestamp)}`,
+      runOrigin: ci?.runOrigin ?? { forge: "local" },
       signature,
     },
     { cwd },

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

@@ -0,0 +1,112 @@
+/**
+ * A flag change is a commit, so it is gated like any change (#4024, ws-104):
+ * the release cut from it carries the flag's new value as a param whose
+ * source names the flag record, keeps the previous release's artifact
+ * digests when no artifact source changed, and its change set for the
+ * environment whose value moved shows the difference while the others are
+ * empty. On the fixture in `../workspace/__fixtures__/flag-workspace.ts`,
+ * with a compiler that resolves each environment's parameters as a build
+ * does and compiles them into the template.
+ */
+
+import { readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { afterAll, describe, expect, test } from "vitest";
+import { cutRelease } from "./release-cut";
+import type { ReleaseArtifact, Release } from "./release-store";
+import type { ReleaseRecord } from "./release-ledger";
+import type { CompiledTarget, TargetCompiler } from "../components/release-compile";
+import { chantComponentPart } from "../components/release-gate";
+import type { DriverComponent } from "../components/driver";
+import { composeChangeSet, isEmptyChangeSet } from "../change-set";
+import type { BuildParamsConfig } from "../build-params";
+import { resolveFlaggedBuildParams } from "../flag-params";
+import { cleanScratch, commitAll, git } from "../workspace/__fixtures__/contract-repo";
+import { flagRecord, flagWorkspace } from "../workspace/__fixtures__/flag-workspace";
+
+afterAll(cleanScratch);
+
+const SHOP: BuildParamsConfig = { newCheckout: { type: "boolean", default: false } };
+const IMAGE = `sha256:${"a".repeat(64)}`;
+
+/** Compiles each environment with the parameters a build resolves there, flags included, into the shop's template. */
+function flagCompiler(memberDir: string): TargetCompiler & { built: string[][] } {
+  const built: string[][] = [];
+  return {
+    built,
+    async compile(env): Promise<CompiledTarget> {
+      const resolved = await resolveFlaggedBuildParams(memberDir, SHOP, { echo: false }, env);
+      if (!resolved.success) throw new Error(resolved.errors.join("\n"));
+      const params = resolved.provenance.map(({ name, value, source }) => ({ name, value, source }));
+      return {
+        env,
+        params,
+        components: ["shop"],
+        buildSteps: { shop: [{ kind: "docker-build", context: "app", into: "shop.tar" }] },
+        buildInputs: { shop: ["app", "app/Dockerfile"] },
+        componentFiles: { shop: "shop.component.ts" },
+        templates: [{ component: "shop", path: "dist/shop.json", content: JSON.stringify({ env, params: Object.fromEntries(params.map((p) => [p.name, p.value])) }) + "\n" }],
+      };
+    },
+    async buildArtifacts(env, components): Promise<ReleaseArtifact[]> {
+      built.push([env, ...components]);
+      return components.map((c) => ({ component: c, kind: "image" as const, path: `${c}.tar`, digest: IMAGE }));
+    },
+  };
+}
+
+const shop: DriverComponent = { name: "shop", deploy: [{ phase: "Apply", steps: [{ kind: "gate", gate: "prod-release" }, { kind: "apply", template: "dist/shop.json" }] }] };
+
+const deployed = (release: Release, env: string): ReleaseRecord => ({
+  version: 1,
+  component: "shop",
+  env,
+  digest: IMAGE,
+  gitSha: release.commit,
+  runId: "run-1",
+  timestamp: "2026-10-16T00:00:00.000Z",
+  actor: "ci",
+  releaseDigest: release.releaseDigest,
+});
+
+describe("a flag change is a release of its own (#4024)", () => {
+  test("it carries the new value with source flag:<id>, the previous artifact digests, and a change set only where the value moved", async () => {
+    const root = flagWorkspace({ "shop/app/Dockerfile": "FROM scratch\n" });
+    const member = join(root, "shop");
+    const compiler = flagCompiler(member);
+    const cut = (label: string) => cutRelease({ cwd: member, compiler, label, actor: "alice", env: {}, now: () => new Date("2026-10-17T10:00:00.000Z") });
+
+    const first = git(root, "rev-parse", "HEAD");
+    git(root, "tag", `ci/green/${first}`, first);
+    const v1 = (await cut("v1")).release;
+    expect(compiler.built).toEqual([["dev", "shop"]]);
+    expect(v1.targets.find((t) => t.env === "prod")!.params).toEqual([{ name: "newCheckout", value: false, source: "flag:new-checkout" }]);
+
+    // Turning the flag on in prod is a commit to the flag record, and nothing else.
+    const flagFile = join(root, "flags", "new-checkout.flag.md");
+    writeFileSync(flagFile, flagRecord("new-checkout", { work: "W-002", member: "shop", param: "newCheckout", values: { dev: true, prod: true } }));
+    expect(readFileSync(flagFile, "utf-8")).toMatch(/"prod": true/);
+    const second = commitAll(root, "turn new-checkout on in prod");
+    git(root, "tag", `ci/green/${second}`, second);
+    const result = await cut("v2");
+    const v2 = result.release;
+
+    // A config-only release: no artifact was built again, and the digests are the previous release's.
+    expect(compiler.built).toEqual([["dev", "shop"]]);
+    expect(result.reused).toEqual([{ component: "shop", from: v1.releaseDigest }]);
+    expect(v2.artifactDigests).toEqual(v1.artifactDigests);
+    expect(v2.commit).toBe(second);
+    expect(v2.releaseDigest).not.toBe(v1.releaseDigest);
+    expect(v2.targets.find((t) => t.env === "prod")!.params).toEqual([{ name: "newCheckout", value: true, source: "flag:new-checkout" }]);
+
+    // The flag change alters prod's change set, and leaves dev's and staging's empty.
+    const part = (env: string) => chantComponentPart({ component: shop, release: v2, env, digest: IMAGE, current: { record: deployed(v1, env), release: v1 } });
+    const prod = part("prod");
+    expect(prod.entries).toHaveLength(1);
+    expect(prod.entries[0]).toMatchObject({ address: "shop", action: "update", scope: "prod" });
+    expect(prod.entries[0].attributes.map((a) => a.path)).toEqual(["template:dist/shop.json", "param:newCheckout"]);
+    expect(prod.entries[0].attributes.find((a) => a.path === "param:newCheckout")).toEqual({ path: "param:newCheckout", before: "false", after: "true" });
+    expect(isEmptyChangeSet(composeChangeSet([prod]))).toBe(false);
+    for (const env of ["dev", "staging"]) expect(isEmptyChangeSet(composeChangeSet([part(env)]))).toBe(true);
+  });
+});

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

@@ -0,0 +1,68 @@
+/**
+ * The join through the release digest (#4043), against a temp repo: two
+ * releases of one commit, and deploys of one release in two environments.
+ * The end-to-end chain, with a real cut, promote and approval, is in
+ * cli/handlers/release-join.e2e.test.ts.
+ */
+import { describe, test, expect } from "vitest";
+import { withTestDir } from "@intentius/chant-test-utils";
+import { spawnSync } from "node:child_process";
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { joinRelease } from "./release-join";
+import { appendCut, makeRelease, persistRelease } from "./release-store";
+import { appendReleaseRecord } from "./release-ledger";
+
+function git(dir: string, ...args: string[]): string {
+  const r = spawnSync("git", args, { cwd: dir, encoding: "utf-8" });
+  if (r.status !== 0) throw new Error(`git ${args.join(" ")}: ${r.stderr}`);
+  return r.stdout.trim();
+}
+
+const subject = (commit: string, digest: string) => ({
+  member: null,
+  commit,
+  artifactDigests: [{ component: "api", kind: "image" as const, path: "api.tar", digest }],
+  targets: [{ env: "dev", templates: [], params: [] }],
+});
+
+describe("joinRelease", () => {
+  test("a commit joins to every release cut from it, each with its own deploys across environments", async () => {
+    await withTestDir(async (dir) => {
+      git(dir, "init", "-q", "-b", "main");
+      git(dir, "config", "user.email", "t@chant.dev");
+      git(dir, "config", "user.name", "T");
+      writeFileSync(join(dir, "README.md"), "x\n");
+      git(dir, "add", ".");
+      git(dir, "commit", "-q", "-m", "init");
+      const sha = git(dir, "rev-parse", "HEAD");
+      const one = makeRelease(subject(sha, "sha256:1"));
+      const two = makeRelease(subject(sha, "sha256:2"));
+      for (const [r, label] of [[one, "v1"], [two, null]] as const) {
+        await persistRelease(r, [], { cwd: dir });
+        await appendCut({ releaseDigest: r.releaseDigest, label, actor: "alice", timestamp: "2026-10-16T10:00:00.000Z", runOrigin: null, signature: null }, { cwd: dir });
+      }
+      const rec = (env: string, runId: string, timestamp: string, releaseDigest?: string) =>
+        appendReleaseRecord({ component: "api", env, digest: "sha256:1", gitSha: sha, runId, timestamp, actor: "ci", ...(releaseDigest ? { releaseDigest } : {}) }, { cwd: dir });
+      await rec("prod", "r3", "2026-10-16T13:00:00.000Z", one.releaseDigest);
+      await rec("dev", "r1", "2026-10-16T11:00:00.000Z", one.releaseDigest);
+      await rec("dev", "r2", "2026-10-16T12:00:00.000Z"); // a deploy of the commit that named no release
+      await rec("dev", "r4", "2026-10-16T14:00:00.000Z", two.releaseDigest);
+
+      const { releases } = await joinRelease({ commit: sha }, { cwd: dir });
+      expect(releases.map((r) => [r.label, r.deploys.map((d) => `${d.env}:${d.runId}`)])).toEqual(
+        expect.arrayContaining([["v1", ["dev:r1", "prod:r3"]], [null, ["dev:r4"]]]),
+      );
+      expect(releases).toHaveLength(2);
+      expect(releases.every((r) => r.commit === sha)).toBe(true);
+      expect(releases.find((r) => r.label === "v1")!.gates).toEqual({ pending: [], resolutions: [] });
+
+      // The unlabelled release is reached by its digest, and the record that named no release joins nowhere.
+      expect((await joinRelease({ release: two.releaseDigest }, { cwd: dir })).releases[0].deploys.map((d) => d.runId)).toEqual(["r4"]);
+      expect((await joinRelease({ deploy: { releaseDigest: undefined } }, { cwd: dir })).releases).toEqual([]);
+      expect((await joinRelease({ release: "nope" }, { cwd: dir })).reason).toMatch(/no release is labelled or digested "nope"/);
+      const ghost = `jcs1-sha256:${"9".repeat(64)}`;
+      expect((await joinRelease({ gate: { releaseDigest: ghost } }, { cwd: dir })).reason).toMatch(/file is not on this checkout/);
+    });
+  });
+});