@intentius/chant 0.124.32 → 0.124.33

package/src/lifecycle/merge-record.ts

@@ -0,0 +1,154 @@
+/**
+ * Merge records (#4168 step 1): what landed on the target branch, keyed by
+ * the commit, kept on `chant/lifecycle` so a release can say which changes
+ * it carries and whether each was approved.
+ *
+ *   _merges/<commit>.json    one record per commit, rewritten when the record job runs again
+ *
+ * A merge never deploys. The record job (`chant components pr-record`)
+ * plans the members the change reaches on the merged commit, stores the
+ * change set (../lifecycle/change-set-store.ts) and writes this record. It
+ * applies nothing and refuses nothing: a plan that differs from the
+ * approved one is recorded, and the job sets a failing `chant/record`
+ * status (#4168 decision 1).
+ *
+ * The record names where the change came from (#4168 4.4): the pull request
+ * that merged it, the work items its `Chant-Record: work:<id>` trailers name,
+ * or a direct push. A workspace member's record sits under
+ * `_members/<member>/_merges/` through the same `ledgerDir` prefix the gate
+ * ledger uses.
+ */
+
+import { execFileSync } from "node:child_process";
+import { sortedJsonReplacer } from "../utils";
+import { parseRecordRef, RECORD_TRAILER, type RecordRef } from "../workspace/trailers";
+import { ledgerDir, readBlobFromPath, readPathSha, RefCASConflictError, writeLedgerFiles, type LedgerLocation } from "./git";
+
+/** The directory on `chant/lifecycle` that holds merge records. */
+export const MERGES_DIR = "_merges";
+
+export const MERGE_RECORD_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace/merge-record/v1/merge-record.schema.json";
+export const MERGE_RECORD_CONTRACT = 1;
+
+/** Where the change came from. */
+export type MergeSource =
+  /** The pull or merge request that merged the commit. */
+  | { kind: "pull-request"; pr: number }
+  /** No pull request merged it; its `Chant-Record` trailers name the work items it carries out. */
+  | { kind: "work-item"; records: RecordRef[] }
+  /** No pull request merged it and its message names no work item. */
+  | { kind: "direct-push" };
+
+/**
+ * How the planned change set compares with the approval. `approved`: an
+ * approval stands for this digest. `changed`: one stands for another digest,
+ * so the plan moved after review. `unapproved`: none stands. `nothing`: no
+ * component deploys what the change touches. `plan-failed`: a member failed
+ * to plan, so there is no digest to compare.
+ */
+export type MergePlanStatus = "approved" | "changed" | "unapproved" | "nothing" | "plan-failed";
+
+export interface MergeRecord {
+  $schema: typeof MERGE_RECORD_SCHEMA_ID;
+  contract: typeof MERGE_RECORD_CONTRACT;
+  /** The merged commit. */
+  commit: string;
+  /** The commit the change is measured from. */
+  base: string;
+  env: string;
+  /** The workspace member whose pipeline recorded it. */
+  member?: string;
+  source: MergeSource;
+  /** The pull request's gate op (`pr-<n>`), or null without a pull request. */
+  op: string | null;
+  gate: string;
+  /** The change-set digest planned on the merged commit, or null when nothing was planned. */
+  digest: string | null;
+  plan: MergePlanStatus;
+  /** With `changed`: the digest the approval stands for. */
+  approvedDigest?: string;
+  /** Who approved the planned digest, with `approved`. */
+  approvedBy: string[];
+  /**
+   * Approvers who wrote the change: the pull request's author, or an author
+   * or committer of one of its commits (#4000). Read only with a forge. An
+   * approval by its author counts toward nothing under the review-rules
+   * group; the record keeps it so a release gate can say so.
+   */
+  authorApproved?: string[];
+  /** The components the change selects, in plan order. */
+  components: string[];
+  /** ISO 8601. */
+  recordedAt: string;
+}
+
+/**
+ * Where `commit` came from: the pull request `pr` when one merged it, else
+ * the work items its `Chant-Record: work:<id>` trailers name, else a direct
+ * push. A commit git can't read names no work item.
+ */
+export function mergeSourceOf(cwd: string, commit: string, pr: number | null): MergeSource {
+  if (pr !== null) return { kind: "pull-request", pr };
+  let text = "";
+  try {
+    text = execFileSync("git", ["log", "-1", `--format=%(trailers:key=${RECORD_TRAILER},valueonly,separator=%x1e)`, commit], { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+  } catch {
+    text = "";
+  }
+  const records: RecordRef[] = [];
+  for (const value of text.split("\x1e").map((v) => v.trim()).filter(Boolean)) {
+    const ref = parseRecordRef(value);
+    if (ref && ref.kind === "work" && !records.some((r) => r.id === ref.id)) records.push(ref);
+  }
+  return records.length > 0 ? { kind: "work-item", records } : { kind: "direct-push" };
+}
+
+/** The file a commit's record is stored in, inside {@link MERGES_DIR}. */
+export function mergeRecordFile(commit: string): string {
+  return `${commit}.json`;
+}
+
+/**
+ * Write `record` under its commit and return whether anything changed. A
+ * record already there with the same content is left alone; another is
+ * replaced, since the record job may run again on the same commit. Does not
+ * push: call `pushLifecycleReport` (./git.ts) after.
+ */
+export async function writeMergeRecord(record: MergeRecord, opts?: LedgerLocation): Promise<{ commit: string | null; written: boolean }> {
+  const file = mergeRecordFile(record.commit);
+  const content = `${JSON.stringify(record, sortedJsonReplacer)}\n`;
+  for (let attempt = 0; attempt < 3; attempt++) {
+    const prior = await readPathSha(MERGES_DIR, file, opts);
+    if (prior !== null) {
+      const text = await readBlobFromPath(MERGES_DIR, file, opts);
+      if (text !== null && sameRecord(text, record)) return { commit: null, written: false };
+    }
+    const dir = await ledgerDir(MERGES_DIR, opts);
+    try {
+      const commit = await writeLedgerFiles([{ path: `${dir}/${file}`, content, expectPriorSha: prior }], `Merge record ${record.commit}`, opts);
+      return { commit, written: true };
+    } catch (err) {
+      if (!(err instanceof RefCASConflictError)) throw err;
+    }
+  }
+  throw new Error(`could not write the merge record for ${record.commit}: chant/lifecycle kept moving`);
+}
+
+/** The same record, ignoring when it was written. */
+function sameRecord(text: string, record: MergeRecord): boolean {
+  try {
+    const { recordedAt: _a, ...had } = JSON.parse(text) as MergeRecord;
+    const { recordedAt: _b, ...now } = record;
+    return JSON.stringify(had, sortedJsonReplacer) === JSON.stringify(now, sortedJsonReplacer);
+  } catch {
+    return false;
+  }
+}
+
+/** The record of `commit`, or null when none is stored. Reads the local `chant/lifecycle` and never fetches. */
+export async function readMergeRecord(commit: string, opts?: LedgerLocation): Promise<MergeRecord | null> {
+  const text = await readBlobFromPath(MERGES_DIR, mergeRecordFile(commit), opts);
+  if (text === null) return null;
+  const doc = JSON.parse(text) as MergeRecord;
+  return doc?.$schema === MERGE_RECORD_SCHEMA_ID ? doc : null;
+}

package/src/lifecycle/publish-attachments.ts

@@ -30,7 +30,7 @@ import { existsSync, readFileSync, realpathSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { sortedJsonReplacer } from "../utils";
 import { writeBom } from "../components/verbs/bom-writer";
-import { parseNpmPackageLock, parsePomXml } from "../components/verbs/lockfile-sbom-generator";
+import { LOCKFILE_NAMES, LOCKFILE_PARSERS } from "../components/verbs/lockfile-sbom-generator";
 import { SBOM_MEDIA_TYPES } from "../components/verbs/sbom-generator";
 import { bytesDigest, checkReleaseDigest, memberFile } from "./publish-targets";
 import { PublishTargetError, type PublishContext } from "./release-publish";
@@ -104,18 +104,25 @@ function invalid(where: string): PublishTargetError {
   return new PublishTargetError("publish-sbom-invalid", `${where} is not an SPDX or CycloneDX JSON document`, "Point sbom at the SPDX or CycloneDX JSON the build writes.");
 }
 
-/** The lockfile nearest the member: `package-lock.json` or `pom.xml` in `cwd` or a directory above it inside its repository (only `cwd` outside one). */
-function nearestLockfile(cwd: string): { kind: "npm" | "maven"; path: string } | null {
+/**
+ * The lockfile nearest the member: `package-lock.json`, `pom.xml` or
+ * `Cargo.lock` in `cwd` or a directory above it inside its repository (only
+ * `cwd` outside one). A member whose directory holds a `Cargo.toml` is a
+ * Rust member, so its `Cargo.lock` comes first (#4168 decision 12); for any
+ * other, the order is npm, Maven, Cargo.
+ */
+function nearestLockfile(cwd: string): { kind: "npm" | "maven" | "cargo"; path: string } | null {
   let top: string | null = null;
   try {
     top = realpathSync(execFileSync("git", ["rev-parse", "--show-toplevel"], { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] }).trim());
   } catch {
     top = null;
   }
+  const order = existsSync(join(cwd, "Cargo.toml")) ? (["cargo", "npm", "maven"] as const) : (["npm", "maven", "cargo"] as const);
   let dir = realpathSync(cwd);
   for (;;) {
-    for (const [kind, file] of [["npm", "package-lock.json"], ["maven", "pom.xml"]] as const) {
-      if (existsSync(join(dir, file))) return { kind, path: join(dir, file) };
+    for (const kind of order) {
+      if (existsSync(join(dir, LOCKFILE_NAMES[kind]))) return { kind, path: join(dir, LOCKFILE_NAMES[kind]) };
     }
     const up = dirname(dir);
     if (top === null || dir === top || up === dir || !up.startsWith(top)) return null;
@@ -127,8 +134,9 @@ function nearestLockfile(cwd: string): { kind: "npm" | "maven"; path: string } |
  * The SBOM a target attaches, for an OCI image or a forge release: the file
  * `declared` names (relative to the member, checked against the release's
  * digest when the release records it), else one written from the member's
- * lockfile for `subject`. Null when `declared` is `false`. Throws
- * `publish-sbom-missing` when there is neither.
+ * lockfile for `subject`. Null when `declared` is `false`, and when there is
+ * neither and `ctx.requireSbom` is not set (#4168). Throws
+ * `publish-sbom-missing` when there is neither under `supply-chain`.
  */
 export function memberSbom(ctx: PublishContext, declared: string | false | undefined, subject: string, target: string): Attachment | null {
   if (declared === false) return null;
@@ -142,18 +150,19 @@ export function memberSbom(ctx: PublishContext, declared: string | false | undef
   }
   const lock = nearestLockfile(ctx.cwd);
   if (!lock) {
+    if (!ctx.requireSbom) return null;
     throw new PublishTargetError(
       "publish-sbom-missing",
-      `${target} attaches an SBOM to what it publishes, and its declaration names none and there is no package-lock.json or pom.xml in ${ctx.cwd} or above it to write one from`,
+      `${target} attaches an SBOM to what it publishes, and its declaration names none and there is no package-lock.json, pom.xml or Cargo.lock in ${ctx.cwd} or above it to write one from`,
       "Set sbom in the declaration to the SPDX or CycloneDX file the build writes, or sbom: false to publish without one.",
     );
   }
   const content = readFileSync(lock.path, "utf-8");
-  const packages = lock.kind === "npm" ? parseNpmPackageLock(content) : parsePomXml(content);
+  const packages = LOCKFILE_PARSERS[lock.kind](content);
   const at = new Date(ctx.cut?.timestamp ?? 0);
   const doc = writeBom(
     "spdx",
-    { subjectName: subject, subjectId: ctx.release.releaseDigest, packages, generator: `chant-lockfile-sbom/${lock.kind === "npm" ? "package-lock.json" : "pom.xml"}` },
+    { subjectName: subject, subjectId: ctx.release.releaseDigest, packages, generator: `chant-lockfile-sbom/${LOCKFILE_NAMES[lock.kind]}` },
     () => (Number.isNaN(at.getTime()) ? new Date(0) : at),
   );
   return attachment("sbom", GENERATED_SBOM_FILE, doc.mediaType, new Uint8Array(Buffer.from(doc.bytes, "utf-8")));
@@ -162,11 +171,13 @@ export function memberSbom(ctx: PublishContext, declared: string | false | undef
 /**
  * The SBOM an npm package carries at its root: the file `declared` names, else
  * the first of {@link PACKAGE_SBOM_FILES} it holds, in a package directory or
- * under `package/` in a packed `.tgz`. Null when `declared` is `false`.
- * Throws `publish-sbom-missing` when the package has none, and
+ * under `package/` in a packed `.tgz`. Null when `declared` is `false`, and
+ * when the package has none and `required` is false (#4168). Throws
+ * `publish-sbom-missing` when it has none and `required` is set (the
+ * `supply-chain` group) or `declared` names a file, and
  * `publish-sbom-invalid` when it is not SPDX or CycloneDX JSON.
  */
-export function packageSbom(abs: string, isDirectory: boolean, path: string, name: string, declared: string | false | undefined): { file: string; digest: string } | null {
+export function packageSbom(abs: string, isDirectory: boolean, path: string, name: string, declared: string | false | undefined, required = false): { file: string; digest: string } | null {
   if (declared === false) return null;
   const candidates = declared !== undefined ? [declared] : [...PACKAGE_SBOM_FILES];
   let listed: Set<string> | null = null;
@@ -188,6 +199,7 @@ export function packageSbom(abs: string, isDirectory: boolean, path: string, nam
     if (!sbomMediaType(bytes)) throw invalid(`${file} in ${path}`);
     return { file, digest: bytesDigest(bytes) };
   }
+  if (!required && declared === undefined) return null;
   throw new PublishTargetError(
     "publish-sbom-missing",
     `${name} (${path}) carries no SBOM: npm keeps no file beside a package, so its SBOM goes in it, and ${declared !== undefined ? declared : `none of ${PACKAGE_SBOM_FILES.join(", ")}`} is at its root`,

package/src/lifecycle/publish-npm.ts

@@ -35,8 +35,9 @@
  * Each package carries its SBOM (#4049): npm keeps no file beside a package,
  * so the SBOM is a file at the package's root, the one `sbom` names or the
  * first of `sbom.spdx.json`, `sbom.cdx.json`, `sbom.cyclonedx.json` it holds,
- * such as `npm sbom` writes. A package with none is refused
- * (`publish-sbom-missing`) unless the declaration says `sbom: false`. Moving a dist-tag over
+ * such as `npm sbom` writes. A package with none publishes without one,
+ * except under the `supply-chain` group (#4168) or when `sbom` names a file,
+ * where it is refused (`publish-sbom-missing`). Moving a dist-tag over
  * OIDC needs "Allow npm dist-tag" on the package's trusted-publisher record.
  * npm makes the first version of a new package `latest` whatever tag it is
  * published under, so a package's first release is visible when it stages.
@@ -100,7 +101,7 @@ function readPackage(ctx: PublishContext, path: string, sbom: NpmPublishDeclarat
   if (pkg.private === true) {
     throw new PublishTargetError("publish-npm-private", `${pkg.name} (${path}) is private, and npm refuses to publish it`, "Remove it from release.publish, or remove private: true.");
   }
-  const carried = packageSbom(abs, directory, path, pkg.name, sbom);
+  const carried = packageSbom(abs, directory, path, pkg.name, sbom, ctx.requireSbom === true);
   return { path, abs, name: pkg.name, version: pkg.version, ...(digest ? { digest } : {}), ...(carried ? { sbom: carried.file } : {}) };
 }
 

package/src/lifecycle/publish-targets.test.ts

@@ -17,6 +17,7 @@ import { join } from "node:path";
 import { createRedactor, REDACTED } from "./publish-credentials";
 import { PublishDeclarationSchema } from "./publish-declaration";
 import { createPublishTargets } from "./publish-targets";
+import { memberSbom } from "./publish-attachments";
 import { parseRepository } from "./publish-oci";
 import { PublishTargetError, type PublishContext, type PublishTarget, type PublishedTarget } from "./release-publish";
 import { makeRelease, type ReleaseArtifact } from "./release-store";
@@ -396,7 +397,7 @@ describe("forge release assets", () => {
 describe("SBOMs and provenance (#4049)", () => {
   const CUT = { actor: "alice", label: "v1.4.0", timestamp: "2026-10-17T10:00:00.000Z", runId: "local-1", signature: "-----BEGIN SSH SIGNATURE-----\nU1NIU0lH\n-----END SSH SIGNATURE-----\n" };
 
-  test("npm: a package carries its SBOM, one with none or with one that is not SPDX or CycloneDX is refused, and sbom: false publishes without", async () => {
+  test("npm: a package carries its SBOM; under supply-chain one with none is refused; one that is not SPDX or CycloneDX is refused; sbom: false publishes without", async () => {
     const dir = temp();
     writePackage(join(dir, "with"), "@acme/with", "1.0.0");
     writePackage(join(dir, "without"), "@acme/without", "1.0.0", false);
@@ -406,9 +407,11 @@ describe("SBOMs and provenance (#4049)", () => {
     writeFileSync(join(dir, "cdx", "package", "bom.json"), JSON.stringify({ bomFormat: "CycloneDX", specVersion: "1.5" }));
     execFileSync("tar", ["-czf", join(dir, "cdx.tgz"), "-C", join(dir, "cdx"), "package"], { stdio: "ignore" });
     const npm = writeFakeNpm(join(dir, "bin"), join(dir, "npm.log"));
-    const plan = async (d: Record<string, unknown>) => (await createPublishTargets([decl({ type: "npm", ...d })], { npm }))[0]!.plan(context(dir));
+    const plan = async (d: Record<string, unknown>, requireSbom = true) => (await createPublishTargets([decl({ type: "npm", ...d })], { npm }))[0]!.plan(context(dir, { requireSbom }));
 
     expect((await plan({ packages: ["with"] }))[0]!.sbom).toBe("sbom.spdx.json");
+    // #4168: outside supply-chain a package with none publishes without one, quietly.
+    expect((await plan({ packages: ["without"] }, false))[0]!.sbom).toBeUndefined();
     const missing = await refused(plan({ packages: ["without"] }));
     expect(missing.code).toBe("publish-sbom-missing");
     expect(missing.message).toBe("@acme/without (without) carries no SBOM: npm keeps no file beside a package, so its SBOM goes in it, and none of sbom.spdx.json, sbom.cdx.json, sbom.cyclonedx.json is at its root");
@@ -471,14 +474,15 @@ describe("SBOMs and provenance (#4049)", () => {
     }
   });
 
-  test("forge: with no declared SBOM and no lockfile the target is refused; a declared SBOM goes on the release by its own name", async () => {
+  test("forge: with no declared SBOM and no lockfile the target is refused under supply-chain and attaches none otherwise; a declared SBOM goes on the release by its own name", async () => {
     const dir = temp();
     writeFileSync(join(dir, "api.tar.gz"), "bytes");
     const api = "https://api.github.test";
     const forge = startFakeForge("github", api, "acme/api");
     const make = async (over: Record<string, unknown> = {}) => (await createPublishTargets([decl({ type: "forge", forge: "github", repo: "acme/api", api, assets: ["api.tar.gz"], ...over })], { fetch: forge.fetch }))[0]!;
     const ctx = context(dir, { env: { GITHUB_TOKEN: "ghs_x" }, cut: CUT });
-    const err = await refused((await make()).plan(ctx));
+    expect((await (await make()).plan(ctx)).map((i) => i.attachment ?? null)).not.toContain("sbom");
+    const err = await refused((await make()).plan({ ...ctx, requireSbom: true }));
     expect(err.code).toBe("publish-sbom-missing");
     expect(err.fix).toContain("sbom: false");
 
@@ -492,3 +496,29 @@ describe("SBOMs and provenance (#4049)", () => {
     expect(statement.predicate.cut.signature).toBe(CUT.signature);
   });
 });
+
+describe("the Cargo.lock SBOM source (#4168 decision 12)", () => {
+  const CARGO_LOCK = '# This file is automatically @generated by Cargo.\nversion = 4\n\n[[package]]\nname = "app"\nversion = "0.1.0"\ndependencies = [\n "serde",\n]\n\n[[package]]\nname = "serde"\nversion = "1.0.210"\nsource = "registry+https://github.com/rust-lang/crates.io-index"\nchecksum = "abc"\n';
+  const NPM_LOCK = JSON.stringify({ name: "web", lockfileVersion: 3, packages: { "": { name: "web" }, "node_modules/left-pad": { version: "1.3.0" } } });
+
+  test("a member with a Cargo.toml writes its SBOM from Cargo.lock, ahead of a package-lock.json beside it", () => {
+    const dir = temp();
+    writeFileSync(join(dir, "Cargo.toml"), "[package]\nname = \"app\"\n");
+    writeFileSync(join(dir, "Cargo.lock"), CARGO_LOCK);
+    writeFileSync(join(dir, "package-lock.json"), NPM_LOCK);
+    const sbom = memberSbom(context(dir), undefined, "app", "forge release assets")!;
+    const text = Buffer.from(sbom.bytes).toString("utf-8");
+    expect(text).toContain("pkg:cargo/serde@1.0.210");
+    expect(text).toContain("chant-lockfile-sbom/Cargo.lock");
+    expect(text).not.toContain("left-pad");
+  });
+
+  test("any other member reads package-lock.json first", () => {
+    const dir = temp();
+    writeFileSync(join(dir, "Cargo.lock"), CARGO_LOCK);
+    writeFileSync(join(dir, "package-lock.json"), NPM_LOCK);
+    const text = Buffer.from(memberSbom(context(dir), undefined, "web", "forge release assets")!.bytes).toString("utf-8");
+    expect(text).toContain("left-pad");
+    expect(text).not.toContain("pkg:cargo/");
+  });
+});

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

@@ -0,0 +1,48 @@
+/**
+ * `release cut --at` (#4168 4.2): the commit is checked out in a temporary
+ * worktree with the checkout's node_modules linked in, and removed after.
+ */
+
+import { describe, test, expect } from "vitest";
+import { withTestDir } from "@intentius/chant-test-utils";
+import { spawnSync } from "node:child_process";
+import { existsSync, lstatSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { checkoutCommit, CutAtError, resolveCutCommit } from "./release-at";
+
+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();
+}
+
+describe("checkoutCommit", () => {
+  test("checks the commit out detached, links node_modules at the top and the member, and removes it", async () => {
+    await withTestDir(async (dir) => {
+      for (const args of [["init", "-q", "-b", "main"], ["config", "user.email", "t@chant.dev"], ["config", "user.name", "T"]]) git(dir, ...args);
+      mkdirSync(join(dir, "members", "api"), { recursive: true });
+      writeFileSync(join(dir, ".gitignore"), "node_modules/\n");
+      writeFileSync(join(dir, "members", "api", "f.txt"), "old");
+      git(dir, "add", ".");
+      git(dir, "commit", "-q", "-m", "one");
+      const one = git(dir, "rev-parse", "HEAD");
+      writeFileSync(join(dir, "members", "api", "f.txt"), "new");
+      git(dir, "commit", "-q", "-am", "two");
+      mkdirSync(join(dir, "node_modules"));
+      mkdirSync(join(dir, "members", "api", "node_modules"));
+
+      expect(resolveCutCommit(dir, "HEAD~1")).toBe(one);
+      expect(() => resolveCutCommit(dir, "nope")).toThrow(CutAtError);
+
+      const co = checkoutCommit(dir, join(dir, "members", "api"), one);
+      expect(readFileSync(join(co.memberDir, "f.txt"), "utf-8")).toBe("old");
+      expect(lstatSync(join(co.dir, "node_modules")).isSymbolicLink()).toBe(true);
+      expect(lstatSync(join(co.memberDir, "node_modules")).isSymbolicLink()).toBe(true);
+      expect(git(co.dir, "rev-parse", "HEAD")).toBe(one);
+      co.remove();
+      co.remove();
+      expect(existsSync(co.dir)).toBe(false);
+      expect(git(dir, "worktree", "list").split("\n")).toHaveLength(1);
+    });
+  });
+});

package/src/lifecycle/release-at.ts

@@ -0,0 +1,100 @@
+/**
+ * `release cut --at <sha>` (#4168 4.2): cut from a chosen commit of trunk,
+ * not the checkout's `HEAD`. The commit is checked out in a temporary
+ * detached worktree, as `chant rollback` works in one (./rollback.ts), so the
+ * caller's branch and working tree are never touched and need not be clean.
+ * The cut then runs in the member's directory inside that worktree, with the
+ * same refusals a cut at `HEAD` has: a commit that is not green, a revoked
+ * one, and build steps that differ by environment.
+ *
+ * Refs are shared between worktrees, so the release and the cut the cut
+ * writes to `chant/lifecycle`, the tags it reads and the tag it makes are the
+ * repository's own. The checkout's `node_modules` are linked in, so the
+ * compile resolves the packages the checkout already installed; a commit
+ * whose lockfile differs from the checkout's would need its own install
+ * (inferred, as the cut can't tell).
+ */
+
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdtempSync, realpathSync, rmSync, symlinkSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, relative, resolve, sep } from "node:path";
+
+export type CutAtCode = "release-at-unknown";
+
+export class CutAtError extends Error {
+  constructor(
+    readonly code: CutAtCode,
+    message: string,
+    readonly fix?: string,
+  ) {
+    super(message);
+    this.name = "CutAtError";
+  }
+}
+
+function git(cwd: string, args: string[]): string {
+  return execFileSync("git", args, { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"] }).trim();
+}
+
+/** The full sha `ref` names in the repository at `top`, or a {@link CutAtError}. */
+export function resolveCutCommit(top: string, ref: string): string {
+  try {
+    return git(top, ["rev-parse", "--verify", "--quiet", `${ref}^{commit}`]);
+  } catch {
+    throw new CutAtError(
+      "release-at-unknown",
+      `--at ${ref} names no commit this clone has`,
+      "Fetch it first (git fetch origin --tags), or name a sha `chant release candidates` lists.",
+    );
+  }
+}
+
+/** A checkout of one commit for the cut, and the member's directory inside it. */
+export interface CommitCheckout {
+  /** The worktree's top. */
+  dir: string;
+  /** The member's directory inside it, the cut's `cwd`. */
+  memberDir: string;
+  /** Remove the worktree. Safe to call twice. */
+  remove(): void;
+}
+
+/**
+ * Check `commit` out in a temporary detached worktree of the repository at
+ * `top`, with the checkout's `node_modules` linked at the top and at each
+ * directory down to `cwd`, the member's directory in the caller's checkout.
+ */
+export function checkoutCommit(top: string, cwd: string, commit: string): CommitCheckout {
+  const realTop = realpathSync(top);
+  const rel = relative(realTop, realpathSync(cwd));
+  const dir = mkdtempSync(join(tmpdir(), `chant-cut-${commit.slice(0, 12)}-`));
+  git(realTop, ["worktree", "add", "--detach", "--quiet", dir, commit]);
+  let removed = false;
+  const remove = (): void => {
+    if (removed) return;
+    removed = true;
+    try {
+      git(realTop, ["worktree", "remove", "--force", dir]);
+    } catch {
+      rmSync(dir, { recursive: true, force: true });
+      try {
+        git(realTop, ["worktree", "prune"]);
+      } catch {
+        // Nothing left to prune.
+      }
+    }
+  };
+  try {
+    const levels = rel === "" ? [""] : ["", ...rel.split(sep).map((_, i, parts) => parts.slice(0, i + 1).join(sep))];
+    for (const level of levels) {
+      const from = join(realTop, level, "node_modules");
+      const to = join(dir, level, "node_modules");
+      if (existsSync(from) && !existsSync(to) && existsSync(dirname(to))) symlinkSync(from, to, "dir");
+    }
+  } catch (err) {
+    remove();
+    throw err;
+  }
+  return { dir, memberDir: resolve(dir, rel), remove };
+}

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

@@ -20,6 +20,7 @@ import {
   readReleaseTemplate,
   ReleaseLabelError,
   resolveRelease,
+  templateBytesDigest,
   verifyReleaseDigest,
   type ReleaseArtifact,
 } from "./release-store";
@@ -114,6 +115,14 @@ describe("the release digest", () => {
     expect(computeReleaseDigest({ ...subject, member: "api" })).not.toBe(digest);
   });
 
+  test("a target without trees or encodings hashes as before #4155; trees and an encoding are in the digest", () => {
+    const digest = computeReleaseDigest(subject);
+    const t = subject.targets[0];
+    expect(computeReleaseDigest({ ...subject, targets: [{ ...t, trees: [] }] })).not.toBe(digest);
+    expect(computeReleaseDigest({ ...subject, targets: [{ ...t, trees: [{ component: "api", path: "chart" }] }] })).not.toBe(computeReleaseDigest({ ...subject, targets: [{ ...t, trees: [] }] }));
+    expect(computeReleaseDigest({ ...subject, targets: [{ ...t, templates: [{ ...t.templates[0], encoding: "base64" as const }] }] })).not.toBe(digest);
+  });
+
   test("verifyReleaseDigest catches a release whose content no longer matches its digest", () => {
     const release = makeRelease(subject);
     expect(verifyReleaseDigest(release)).toBe(true);
@@ -122,6 +131,38 @@ describe("the release digest", () => {
 });
 
 describe("cutRelease", () => {
+  test("records a directory's files and a file that is not UTF-8, which read back by digest (#4155)", async () => {
+    await withTestDir(async (dir) => {
+      const sha = initRepo(dir);
+      green(dir, sha);
+      const tgz = Buffer.from([0x1f, 0x8b, 0xff]).toString("base64");
+      const base = fixtureCompiler();
+      const compiler: TargetCompiler = {
+        ...base,
+        async compile(env) {
+          const t = await base.compile(env);
+          return {
+            ...t,
+            templates: [
+              ...t.templates,
+              { component: "api", path: "chart/Chart.yaml", content: "name: api\n" },
+              { component: "api", path: "chart/charts/dep.tgz", content: tgz, encoding: "base64" },
+            ],
+            trees: [{ component: "api", path: "chart" }],
+          };
+        },
+      };
+      const { release } = await cut(dir, compiler, null);
+      const prod = release.targets.find((t) => t.env === "prod")!;
+      expect(prod.trees).toEqual([{ component: "api", path: "chart" }]);
+      const bin = prod.templates.find((t) => t.path === "chart/charts/dep.tgz")!;
+      expect(bin).toMatchObject({ encoding: "base64", digest: templateBytesDigest(tgz, "base64") });
+      expect(await readReleaseTemplate(bin.digest, { cwd: dir }, "base64")).toBe(tgz);
+      expect(await readReleaseTemplate(bin.digest, { cwd: dir })).toBeNull();
+      expect((await readRelease(release.releaseDigest, { cwd: dir }))?.targets.find((t) => t.env === "prod")?.trees).toEqual([{ component: "api", path: "chart" }]);
+    });
+  });
+
   test("cuts a release from a green commit and stores it apart from the deploy records", async () => {
     await withTestDir(async (dir) => {
       const sha = initRepo(dir);

package/src/lifecycle/release-cut.ts

@@ -37,7 +37,6 @@ import { execFileSync } from "node:child_process";
 import { realpathSync } from "node:fs";
 import { relative, resolve } from "node:path";
 import { canonicalJson } from "../effect-receipt";
-import { contentDigest } from "../content-digest";
 import { getHeadCommit } from "./git";
 import { resolveMemberLedger } from "./member-ledger";
 import { resolveCiRun } from "./release-ledger";
@@ -55,6 +54,7 @@ import {
   type ReleaseArtifact,
   type ReleaseCut,
   type ReleaseTarget,
+  templateBytesDigest,
   type TemplateContent,
 } from "./release-store";
 import type { CompiledTarget, TargetCompiler } from "../components/release-compile";
@@ -322,18 +322,29 @@ async function prepare(req: CutRequest): Promise<Prepared> {
   };
 }
 
-/** The targets and template bytes of a compile, each template by its content digest. */
+/**
+ * The targets and template bytes of a compile, each template by its content
+ * digest. A compile of components names its directories in `trees` (#4155),
+ * an empty list when it has none, which marks the target as one that records
+ * every deploy input. A project with no components has no deploy step to
+ * name one, and its targets have no `trees`.
+ */
 function targetsOf(compiled: readonly CompiledTarget[]): { targets: ReleaseTarget[]; templates: TemplateContent[] } {
   const templates: TemplateContent[] = [];
-  const targets: ReleaseTarget[] = compiled.map((t) => ({
-    env: t.env,
-    params: t.params,
-    templates: t.templates.map((tpl) => {
-      const digest = contentDigest(tpl.content);
-      templates.push({ digest, content: tpl.content });
-      return { component: tpl.component, path: tpl.path, digest };
-    }),
-  }));
+  const targets: ReleaseTarget[] = compiled.map((t) => {
+    const seen = new Set<string>();
+    const recorded: ReleaseTarget["templates"] = [];
+    for (const tpl of t.templates) {
+      // A file named twice, as a values file inside a recorded chart, is recorded once.
+      const key = `${tpl.component ?? ""}\u0000${tpl.path}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      const digest = templateBytesDigest(tpl.content, tpl.encoding);
+      templates.push({ digest, content: tpl.content, ...(tpl.encoding ? { encoding: tpl.encoding } : {}) });
+      recorded.push({ component: tpl.component, path: tpl.path, digest, ...(tpl.encoding ? { encoding: tpl.encoding } : {}) });
+    }
+    return { env: t.env, params: t.params, templates: recorded, ...(t.trees ? { trees: t.trees } : {}) };
+  });
   return { targets, templates };
 }