@intentius/chant 0.124.27 → 0.124.29

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/);
+    });
+  });
+});

package/src/lifecycle/release-join.ts

@@ -0,0 +1,182 @@
+/**
+ * Join a commit, a release, its gates and its deploy records through the
+ * release digest (#4043, ws-104).
+ *
+ * The records already name one another. A release file holds its `commit`; a
+ * release gate's pending fact and resolution hold the `releaseDigest`; a deploy
+ * record holds the `releaseDigest` when the deploy was made from a release.
+ * From any one of the four, the others are one lookup away:
+ *
+ *   commit  to releases      `_releases/*.json` `commit`
+ *   release to gates         `releaseDigest` on the records of `_gates/release.jsonl`
+ *   release to deploys       `releaseDigest` on the records of every `<env>/releases.jsonl`
+ *
+ * This is the one place that does it, for the readers that need the chain
+ * (the why chain of #4023, behold). Release plus a deploy record's `env`
+ * names the release target.
+ *
+ * Read-only. Reads the local `chant/lifecycle` branch; fetch it first for the
+ * remote's records. A release digest or commit that nothing recorded joins to
+ * an empty list rather than an error.
+ */
+
+import { RELEASE_GATE_OP } from "../op/gate-name";
+import { readGateLedger, type GateResolutionRecord, type PendingGateRecord } from "./gate-ledger";
+import { listReleaseEnvironments, readReleaseLedger, type ReleaseRecord } from "./release-ledger";
+import { labelsByDigest, readAllReleases, readCuts, type Release, type ReleaseCut } from "./release-store";
+import type { LedgerLocation } from "./git";
+
+/** Where a join starts. Each names the others one lookup away. */
+export type ReleaseJoinStart =
+  /** A full commit sha, or a prefix of at least 7 characters. Joins to every release cut from it. */
+  | { commit: string }
+  /**
+   * Several full commit shas, or prefixes of at least 7 characters. Joins to
+   * every release cut from any of them, reading the ledgers once (#4023).
+   */
+  | { commits: readonly string[] }
+  /** A release's label or its `releaseDigest`. */
+  | { release: string }
+  /**
+   * A deploy record. It joins through its `releaseDigest`; a record with none
+   * but an admission by the release gate joins through the resolution that
+   * admission names.
+   */
+  | { deploy: Pick<ReleaseRecord, "releaseDigest" | "admission"> }
+  /** A release gate's pending fact or resolution. */
+  | { gate: Pick<PendingGateRecord | GateResolutionRecord, "releaseDigest"> };
+
+/** One release with everything the digest joins to it. */
+export interface JoinedRelease {
+  releaseDigest: string;
+  /** The label of the release, or null when it was cut with none. */
+  label: string | null;
+  /** The green commit the release was cut from. */
+  commit: string;
+  release: Release;
+  /** Every cut of the release, oldest first. */
+  cuts: ReleaseCut[];
+  /** The release gate's facts for this release (`_gates/release.jsonl`), oldest first. */
+  gates: { pending: PendingGateRecord[]; resolutions: GateResolutionRecord[] };
+  /** Every deploy record that names the release, across environments, oldest first: by its `releaseDigest`, or, without one, by the release gate resolution its admission names. Each record's `env` with the release names the target. */
+  deploys: ReleaseRecord[];
+}
+
+/** What {@link joinRelease} returns. */
+export interface ReleaseJoin {
+  /** The releases the starting point joins to: one for a release, a gate or a deploy, any number for a commit. */
+  releases: JoinedRelease[];
+  /** Why `releases` is empty, when the starting point could not be followed. Absent otherwise. */
+  reason?: string;
+}
+
+/** The version of the shape above, for a reader that stores it. Chant 0.124.29 and newer. */
+export const RELEASE_JOIN_VERSION = 1;
+
+const MIN_COMMIT_PREFIX = 7;
+
+/**
+ * Follow one record to the rest of its chain. Never throws for an unknown
+ * starting point; a ledger that can't be read does throw, as those readers do.
+ */
+export async function joinRelease(from: ReleaseJoinStart, loc: LedgerLocation = {}): Promise<ReleaseJoin> {
+  const { releases } = await readAllReleases(loc);
+  const { cuts } = await readCuts(loc);
+  const labels = labelsByDigest(cuts);
+
+  let digests: string[];
+  let reason: string | undefined;
+  if ("commit" in from) {
+    const sha = from.commit.toLowerCase();
+    if (sha.length < MIN_COMMIT_PREFIX) {
+      return { releases: [], reason: `a commit needs at least ${MIN_COMMIT_PREFIX} characters to join on` };
+    }
+    digests = releases.filter((r) => r.commit.toLowerCase().startsWith(sha)).map((r) => r.releaseDigest);
+    if (digests.length === 0) reason = `no release was cut from commit ${from.commit}`;
+  } else if ("commits" in from) {
+    const shas = from.commits.map((c) => c.toLowerCase());
+    if (shas.some((sha) => sha.length < MIN_COMMIT_PREFIX)) {
+      return { releases: [], reason: `a commit needs at least ${MIN_COMMIT_PREFIX} characters to join on` };
+    }
+    digests = releases.filter((r) => shas.some((sha) => r.commit.toLowerCase().startsWith(sha))).map((r) => r.releaseDigest);
+    if (digests.length === 0) reason = shas.length === 0 ? "no commit was given to join on" : `no release was cut from ${shas.length === 1 ? `commit ${from.commits[0]}` : `any of ${shas.length} commits`}`;
+  } else if ("release" in from) {
+    const ref = from.release;
+    const byDigest = releases.find((r) => r.releaseDigest === ref);
+    const byLabel = [...labels].find(([, label]) => label === ref)?.[0];
+    const found = byDigest?.releaseDigest ?? byLabel;
+    digests = found ? [found] : [];
+    if (digests.length === 0) reason = `no release is labelled or digested "${ref}"`;
+  } else if ("deploy" in from) {
+    const digest = from.deploy.releaseDigest ?? (await releaseOfAdmission(from.deploy.admission, loc));
+    digests = digest ? [digest] : [];
+    if (digests.length === 0) reason = "the deploy record names no release: it was not made from one";
+  } else {
+    const digest = from.gate.releaseDigest;
+    digests = digest ? [digest] : [];
+    if (digests.length === 0) reason = "the gate binds no release: it is not a release gate";
+  }
+
+  const known = new Map(releases.map((r) => [r.releaseDigest, r]));
+  const wanted = [...new Set(digests)].filter((d) => known.has(d));
+  if (digests.length > 0 && wanted.length === 0) reason = `release ${digests[0]} is named but its file is not on this checkout's chant/lifecycle`;
+  if (wanted.length === 0) return { releases: [], ...(reason ? { reason } : {}) };
+
+  const gateLedger = await readGateLedger(RELEASE_GATE_OP, loc);
+  // A record names its release by `releaseDigest`, or, with none, through the
+  // release gate resolution its admission names (#4045), as releaseOfDeploy reads it.
+  const records: { record: ReleaseRecord; digest: string }[] = [];
+  for (const env of await listReleaseEnvironments(loc)) {
+    for (const record of (await readReleaseLedger(env, loc)).records) {
+      const digest = releaseOfDeploy(record, gateLedger.resolutions);
+      if (digest !== undefined && wanted.includes(digest)) records.push({ record, digest });
+    }
+  }
+  const byTime = (a: { timestamp: string }, b: { timestamp: string }): number => (a.timestamp < b.timestamp ? -1 : a.timestamp > b.timestamp ? 1 : 0);
+
+  return {
+    releases: wanted.map((digest) => {
+      const release = known.get(digest)!;
+      return {
+        releaseDigest: digest,
+        label: labels.get(digest) ?? null,
+        commit: release.commit,
+        release,
+        cuts: cuts.filter((c) => c.releaseDigest === digest),
+        gates: {
+          pending: gateLedger.pending.filter((p) => p.releaseDigest === digest),
+          resolutions: gateLedger.resolutions.filter((r) => r.releaseDigest === digest),
+        },
+        deploys: records.filter((r) => r.digest === digest).map((r) => r.record).sort(byTime),
+      };
+    }),
+  };
+}
+
+/**
+ * The release a deploy record's admission names, when the record itself has no
+ * `releaseDigest`: the resolution it points at, in the release gate's ledger,
+ * carries one (#4045).
+ */
+async function releaseOfAdmission(admission: ReleaseRecord["admission"], loc: LedgerLocation): Promise<string | undefined> {
+  if (!admission || admission.op !== RELEASE_GATE_OP) return undefined;
+  const { resolutions } = await readGateLedger(RELEASE_GATE_OP, loc);
+  return releaseOfDeploy({ admission }, resolutions);
+}
+
+/**
+ * The release a deploy record names, over the release gate's resolutions
+ * already read: its own `releaseDigest`, else the one on the resolution its
+ * admission names. Undefined when it was not made from a release. The rule
+ * {@link joinRelease} follows, for a reader that holds the ledgers already,
+ * such as retention's garbage collection (#4036).
+ */
+export function releaseOfDeploy(
+  record: Pick<ReleaseRecord, "releaseDigest" | "admission">,
+  releaseGateResolutions: readonly Pick<GateResolutionRecord, "gate" | "timestamp" | "releaseDigest">[],
+): string | undefined {
+  if (record.releaseDigest !== undefined) return record.releaseDigest;
+  const admission = record.admission;
+  if (!admission || admission.op !== RELEASE_GATE_OP) return undefined;
+  return releaseGateResolutions.find((r) => r.gate === admission.gate && r.timestamp === admission.resolvedAt && r.releaseDigest !== undefined)?.releaseDigest;
+}

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

@@ -146,6 +146,20 @@ describe("release-ledger", () => {
       });
     });
 
+    test("records the gate resolution that admitted the deploy, and an older record without it still reads (#4020)", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        const admission = { op: "search-service", gate: "approve-prod", resolvedAt: "2026-01-01T00:05:00.000Z" };
+        await appendReleaseRecord(makeInput({ timestamp: "2026-01-01T00:06:00.000Z", approver: "alice@corp", admission }), { cwd: dir });
+        await appendReleaseRecord(makeInput({ component: "worker", timestamp: "2026-01-01T00:07:00.000Z" }), { cwd: dir });
+        const { records, malformed } = await readReleaseLedger("prod", { cwd: dir });
+        expect(malformed).toBe(0);
+        expect(records[0].admission).toEqual(admission);
+        expect(records[0].approver).toBe("alice@corp");
+        expect(records[1].admission).toBeUndefined();
+      });
+    });
+
     test("approver is absent for an ungated change (#1035)", async () => {
       await withTestDir(async (dir) => {
         await initRepo(dir);

package/src/lifecycle/release-ledger.ts

@@ -32,6 +32,7 @@ import { sortedJsonReplacer } from "../utils";
 import { warnOnLegacyDigests, withoutReadFlags, type LegacyDigestFlag } from "./legacy-digest";
 import { appendReleaseRecordLine, readReleaseLedgerLines, listLedgerEnvironments as gitListLedgerEnvironments, type LedgerLocation } from "./git";
 import { parseReleaseLedger, validateReleaseRecord } from "./release-read";
+import type { GateResolutionRecord } from "./gate-ledger";
 
 // The pure readers live apart, so a bundle can import them without git (#3865).
 export { validateReleaseRecord, parseReleaseLedger, releaseLedgerLines, readReleaseRecords, listReleaseEnvironmentsOn } from "./release-read";
@@ -56,6 +57,40 @@ export interface RunOrigin {
   url?: string;
 }
 
+/**
+ * The gate resolution that admitted a deploy (#4020): the gate's address in the
+ * gate ledger (`_gates/<op>.jsonl`, `op` and `gate`) and when the resolution
+ * was recorded. With `approver` on the same record it names the line a reader
+ * opens to see what was approved. Chant 0.124.28 and newer write it.
+ */
+export interface ReleaseAdmission {
+  /** The op, or for a component gate the component, whose gate ledger holds the resolution. */
+  op: string;
+  /** The gate's name. */
+  gate: string;
+  /** ISO-8601 time the resolution was recorded (`GateResolutionRecord.timestamp`). When several approvals counted, the newest one. */
+  resolvedAt: string;
+}
+
+/**
+ * The approver and admission a release records for the resolutions of its gate
+ * (#4020): those of `gate` on `op` bound to `planDigest`. The approver is the
+ * distinct `resolvedBy` names, comma joined, as `approver` has always been
+ * written by the release activities; `resolvedAt` is the newest one's time.
+ * Undefined when no resolution is bound to the plan.
+ */
+export function admissionOf(
+  resolutions: readonly GateResolutionRecord[],
+  at: { op: string; gate: string; planDigest?: string },
+): { approver: string; admission: ReleaseAdmission } | undefined {
+  const bound = resolutions.filter((r) => r.gate === at.gate && r.planDigest === at.planDigest);
+  if (bound.length === 0) return undefined;
+  return {
+    approver: [...new Set(bound.map((r) => r.resolvedBy))].join(", "),
+    admission: { op: at.op, gate: at.gate, resolvedAt: bound.map((r) => r.timestamp).sort().at(-1)! },
+  };
+}
+
 /**
  * Points at one earlier release record (#2530, #2531, #2604). A record has no id of its own,
  * so it is named by the environment whose ledger holds it plus the run id and
@@ -126,6 +161,13 @@ export interface ReleaseRecord {
    * the one who triggered the deploy (separation of duties).
    */
   approver?: string;
+  /**
+   * The gate resolution that admitted this deploy (#4020), for a gated change:
+   * which gate (`op` and `gate`) and when it was resolved. The approver is
+   * `approver`. Optional and omitted for an ungated change and for a record
+   * written before 0.124.28, whose gate cannot be recovered from the record.
+   */
+  admission?: ReleaseAdmission;
   /** Optional: the archive's own manifest digest (../components/verbs/build-archive.ts's `manifestDigest`), when the caller has it — lets a reader recover full build contents/provenance, not just the promoted image digest. */
   manifestDigest?: string;
   /**
@@ -175,6 +217,13 @@ export interface ReleaseRecord {
    * partway. Absent on every other record.
    */
   redeploys?: ReleaseRef;
+  /**
+   * Optional: the release this deploy came from (#4026, ws-104), the
+   * `releaseDigest` of `_releases/<releaseDigest>.json`. Written by
+   * `chant components promote --release` since 0.124.28. Absent on every
+   * deploy that was not made from a release.
+   */
+  releaseDigest?: string;
 }
 
 /** Thrown by `appendReleaseRecord` when the record is missing a required field — a release record can never be recorded partially, since it is never editable afterward. */
@@ -213,29 +262,48 @@ export function resolveRunId(
   explicit?: string,
   env: NodeJS.ProcessEnv = process.env,
 ): { runId: string; runOrigin?: RunOrigin } {
-  const githubOrigin = (id: string): RunOrigin => ({
-    forge: "github",
-    ...(env.GITHUB_REPOSITORY ? { repo: env.GITHUB_REPOSITORY } : {}),
-    ...(env.GITHUB_SERVER_URL && env.GITHUB_REPOSITORY
-      ? { url: `${env.GITHUB_SERVER_URL}/${env.GITHUB_REPOSITORY}/actions/runs/${id}` }
-      : {}),
-  });
-  const gitlabOrigin = (): RunOrigin => ({
-    forge: "gitlab",
-    ...(env.CI_PROJECT_PATH ? { repo: env.CI_PROJECT_PATH } : {}),
-    ...(env.CI_PIPELINE_URL ? { url: env.CI_PIPELINE_URL } : {}),
-  });
-
+  const ci = resolveCiRun(env);
   if (explicit) {
-    if (env.GITHUB_RUN_ID && explicit === env.GITHUB_RUN_ID) return { runId: explicit, runOrigin: githubOrigin(explicit) };
-    if (env.CI_PIPELINE_ID && explicit === env.CI_PIPELINE_ID) return { runId: explicit, runOrigin: gitlabOrigin() };
+    if (ci && explicit === ci.runId) return ci;
     return { runId: explicit };
   }
-  if (env.GITHUB_RUN_ID) return { runId: env.GITHUB_RUN_ID, runOrigin: githubOrigin(env.GITHUB_RUN_ID) };
-  if (env.CI_PIPELINE_ID) return { runId: env.CI_PIPELINE_ID, runOrigin: gitlabOrigin() };
+  if (ci) return ci;
   return { runId: `local-${Date.now()}`, runOrigin: { forge: "local" } };
 }
 
+/**
+ * The CI run the environment names, with the origin that locates it, or
+ * undefined outside CI (#4020). `resolveRunId` takes its CI branches from
+ * here, and an Op run record takes its `runOrigin` from here, so a run and the
+ * deploy it made name the run the same way.
+ */
+export function resolveCiRun(env: NodeJS.ProcessEnv = process.env): { runId: string; runOrigin: RunOrigin } | undefined {
+  if (env.GITHUB_RUN_ID) {
+    const id = env.GITHUB_RUN_ID;
+    return {
+      runId: id,
+      runOrigin: {
+        forge: "github",
+        ...(env.GITHUB_REPOSITORY ? { repo: env.GITHUB_REPOSITORY } : {}),
+        ...(env.GITHUB_SERVER_URL && env.GITHUB_REPOSITORY
+          ? { url: `${env.GITHUB_SERVER_URL}/${env.GITHUB_REPOSITORY}/actions/runs/${id}` }
+          : {}),
+      },
+    };
+  }
+  if (env.CI_PIPELINE_ID) {
+    return {
+      runId: env.CI_PIPELINE_ID,
+      runOrigin: {
+        forge: "gitlab",
+        ...(env.CI_PROJECT_PATH ? { repo: env.CI_PROJECT_PATH } : {}),
+        ...(env.CI_PIPELINE_URL ? { url: env.CI_PIPELINE_URL } : {}),
+      },
+    };
+  }
+  return undefined;
+}
+
 /**
  * Append one immutable release record to the `<env>` ledger on the
  * `chant/lifecycle` orphan branch. Throws `InvalidReleaseRecordError` before

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

@@ -0,0 +1,225 @@
+/**
+ * #4027: `chant release publish`'s contract. It refuses a release no cut
+ * names, a revoked one, and one with no verified signature (#4049; under
+ * identity.gates.release even with --allow-unsigned); it warns when the run has no OIDC token; and with no
+ * publish target declared it has nothing to publish. With a target (#4047)
+ * it reads them from release.publish and refuses a checkout that is not the
+ * release's commit with a clean tree.
+ */
+
+import { afterAll, describe, expect, test } from "vitest";
+import { rmSync } from "node:fs";
+import { dirname } from "node:path";
+import { cutRelease } from "./release-cut";
+import { detectProvenance, preparePublish, type PublishPlan, type PublishRefusal } from "./release-publish";
+import type { ReleaseArtifact } from "./release-store";
+import type { CompiledTarget, TargetCompiler } from "../components/release-compile";
+import { hasSshKeygen, TestRepo, type Key } from "../workspace/trust/test-repo";
+
+const repos: TestRepo[] = [];
+afterAll(() => {
+  for (const r of repos) rmSync(dirname(r.dir), { recursive: true, force: true });
+});
+
+const compiler: TargetCompiler = {
+  async compile(env): Promise<CompiledTarget> {
+    return {
+      env,
+      params: [],
+      components: ["api"],
+      buildSteps: {},
+      buildInputs: {},
+      componentFiles: { api: "api.component.ts" },
+      templates: [{ component: "api", path: "dist/api.json", content: `{"env":"${env}"}\n` }],
+    };
+  },
+  async buildArtifacts(): Promise<ReleaseArtifact[]> {
+    return [];
+  },
+};
+
+/** A project, a workspace member when `declaration` is given, with alice and bob as signers and alice a releaser. */
+function setup(declaration: Record<string, unknown> | null, opts: { signers?: boolean } = {}): { r: TestRepo; alice: Key; bob: Key; head: string } {
+  const r = new TestRepo("release-publish");
+  repos.push(r);
+  const alice = r.key("alice");
+  const bob = r.key("bob");
+  if (declaration) {
+    r.write("chant.workspace.json", JSON.stringify({ name: "acme", schema: 1, members: [{ name: "root", dir: ".", kind: "other", because: "the publish fixture" }], ...declaration }, null, 2));
+    r.write(".chant/allowed_signers", `alice ${alice.pub}\nbob ${bob.pub}\n`);
+  } else if (opts.signers) {
+    // A plain project with a signers file and no workspace declaration (#4049).
+    r.write(".chant/allowed_signers", `alice ${alice.pub}\n`);
+  }
+  r.write("chant.config.ts", `export default { environments: ["dev", "prod"] };\n`);
+  r.write("api.component.ts", "export const api = {};\n");
+  const head = r.commit("init");
+  r.git(["tag", `ci/green/${head}`]);
+  return { r, alice, bob, head };
+}
+
+const cut = (r: TestRepo, label: string, sign?: Key, actor = "alice") =>
+  cutRelease({ cwd: r.dir, compiler, label, actor, env: {}, now: () => new Date("2026-10-17T10:00:00.000Z"), ...(sign ? { sign: sign.file } : {}) });
+const refusal = (p: PublishPlan | { refusal: PublishRefusal }): PublishRefusal | null => ("refusal" in p ? p.refusal : null);
+const WORKSTATION: NodeJS.ProcessEnv = { PATH: process.env.PATH };
+
+describe("provenance", () => {
+  test("GitHub Actions has OIDC with id-token: write, GitLab with an ID token, a workstation never", () => {
+    expect(detectProvenance({})).toEqual({ oidc: false, ci: null, reason: "this run is not in CI, and a workstation has no OIDC token" });
+    expect(detectProvenance({ GITHUB_ACTIONS: "true" })).toMatchObject({ oidc: false, ci: "github", reason: expect.stringMatching(/id-token: write/) });
+    expect(detectProvenance({ GITHUB_ACTIONS: "true", ACTIONS_ID_TOKEN_REQUEST_URL: "https://x", ACTIONS_ID_TOKEN_REQUEST_TOKEN: "t" })).toMatchObject({ oidc: true, ci: "github" });
+    expect(detectProvenance({ GITLAB_CI: "true" })).toMatchObject({ oidc: false, ci: "gitlab", reason: expect.stringMatching(/id_tokens/) });
+    expect(detectProvenance({ GITLAB_CI: "true", SIGSTORE_ID_TOKEN: "t" })).toMatchObject({ oidc: true, ci: "gitlab" });
+    // A CI variable alone is not a token.
+    expect(detectProvenance({ CI: "true", GITHUB_RUN_ID: "1" }).oidc).toBe(false);
+  });
+});
+
+describe("chant release publish", () => {
+  test("warns on a workstation that what it publishes carries no provenance, and has no target to publish to", async () => {
+    const { r } = setup(null);
+    await cut(r, "v1");
+    const plan = await preparePublish({ cwd: r.dir, ref: "v1", env: WORKSTATION, allowUnsigned: true });
+    expect(refusal(plan)).toBeNull();
+    const p = plan as PublishPlan;
+    expect(p.label).toBe("v1");
+    expect(p.signature.status).toBe("unsigned");
+    expect(p.provenance.oidc).toBe(false);
+    expect(p.warning).toBe(
+      "this publish runs without OIDC, so what it publishes carries no provenance: this run is not in CI, and a workstation has no OIDC token. Publish from CI to get provenance.",
+    );
+    expect(p.targets).toEqual([]);
+    expect(p.releaseTag).toBe("release/v1");
+
+    const inCi = (await preparePublish({
+      cwd: r.dir,
+      ref: p.release.releaseDigest,
+      env: { GITHUB_ACTIONS: "true", ACTIONS_ID_TOKEN_REQUEST_URL: "https://x", ACTIONS_ID_TOKEN_REQUEST_TOKEN: "t" },
+      allowUnsigned: true,
+    })) as PublishPlan;
+    expect(inCi.warning).toBeNull();
+    expect(inCi.label).toBe("v1");
+  });
+
+  test("refuses a release no cut names, and one cut from a revoked commit", async () => {
+    const { r, head } = setup(null);
+    await cut(r, "v1");
+    expect(refusal(await preparePublish({ cwd: r.dir, ref: "v9", env: WORKSTATION }))?.code).toBe("release-not-found");
+    r.git(["tag", `ci/revoked/${head}`]);
+    const revoked = refusal(await preparePublish({ cwd: r.dir, ref: "v1", env: WORKSTATION }));
+    expect(revoked?.code).toBe("release-revoked");
+    expect(revoked?.message).toMatch(new RegExp(`ci/revoked/${head}`));
+  });
+
+  test.skipIf(!hasSshKeygen)("under identity.gates.release, refuses an unsigned cut and publishes a signed one", async () => {
+    const gate = { identity: { gates: { release: {} } } };
+    const { r, alice } = setup(gate);
+    // Cut before the gate applies to the cut, as an older chant or another branch could: write it through the store's own path.
+    const { appendCut, makeRelease, persistRelease } = await import("./release-store");
+    const head = r.head();
+    const unsigned = makeRelease({ member: "root", commit: head, artifactDigests: [], targets: [{ env: "dev", params: [], templates: [] }] });
+    await persistRelease(unsigned, [], { cwd: r.dir });
+    await appendCut({ releaseDigest: unsigned.releaseDigest, label: "v0", actor: "alice", timestamp: "2026-10-17T09:00:00.000Z", runOrigin: null }, { cwd: r.dir });
+    const refused = refusal(await preparePublish({ cwd: r.dir, ref: "v0", env: WORKSTATION }));
+    expect(refused?.code).toBe("release-unsigned");
+    expect(refused?.fix).toMatch(/chant release cut v0 --sign --yes/);
+
+    await cut(r, "v1", alice);
+    const signed = (await preparePublish({ cwd: r.dir, ref: "v1", env: WORKSTATION })) as PublishPlan;
+    expect(refusal(signed)).toBeNull();
+    expect(signed.signature).toMatchObject({ status: "verified", actor: "alice", key: expect.stringMatching(/^SHA256:/) });
+  });
+
+  test.skipIf(!hasSshKeygen)("under identity.gates.release, refuses a cut whose signature does not verify for its actor", async () => {
+    const { r, bob } = setup({ identity: { gates: { release: {} } } });
+    const { appendCut, makeRelease, persistRelease } = await import("./release-store");
+    const { sealReleaseCut } = await import("../workspace/trust/seal");
+    const release = makeRelease({ member: "root", commit: r.head(), artifactDigests: [], targets: [{ env: "dev", params: [], templates: [] }] });
+    await persistRelease(release, [], { cwd: r.dir });
+    // Signed by bob's key, in alice's name.
+    const line = { releaseDigest: release.releaseDigest, label: "v2", actor: "alice", timestamp: "2026-10-17T09:00:00.000Z" };
+    const signature = sealReleaseCut(bob.file, line).signature;
+    await appendCut({ ...line, runOrigin: null, signature }, { cwd: r.dir });
+    const refused = refusal(await preparePublish({ cwd: r.dir, ref: "v2", env: WORKSTATION }));
+    expect(refused?.code).toBe("release-signature-unverified");
+    // --allow-unsigned never overrides the release gate.
+    expect(refusal(await preparePublish({ cwd: r.dir, ref: "v2", env: WORKSTATION, allowUnsigned: true }))?.code).toBe("release-signature-unverified");
+  });
+
+  test("refuses an unsigned release with no release gate, and publishes it under --allow-unsigned with a warning", async () => {
+    const { r } = setup(null);
+    await cut(r, "v1");
+    const refused = refusal(await preparePublish({ cwd: r.dir, ref: "v1", env: WORKSTATION }));
+    expect(refused?.code).toBe("release-unsigned");
+    expect(refused?.message).toBe("v1 has no signed cut, and chant release publish publishes only a release signed by a key in .chant/allowed_signers");
+    expect(refused?.fix).toContain("chant release cut v1 --sign --yes");
+    expect(refused?.fix).toContain("--allow-unsigned");
+
+    const allowed = (await preparePublish({ cwd: r.dir, ref: "v1", env: WORKSTATION, allowUnsigned: true })) as PublishPlan;
+    expect(refusal(allowed)).toBeNull();
+    expect(allowed.signatureWarning).toBe("v1 has no signed cut; publishing it anyway under --allow-unsigned, so chant release verify v1 will fail for it");
+    expect(allowed.cut).toMatchObject({ actor: "alice", label: "v1", signature: null });
+  });
+
+  test.skipIf(!hasSshKeygen)("with no release gate, publishes a release signed by a listed key and refuses one signed by a key the signers file does not list", async () => {
+    const { r, alice, bob } = setup(null, { signers: true });
+    await cut(r, "v1", alice);
+    const signed = (await preparePublish({ cwd: r.dir, ref: "v1", env: WORKSTATION })) as PublishPlan;
+    expect(refusal(signed)).toBeNull();
+    expect(signed.signature).toMatchObject({ status: "verified", actor: "alice" });
+    expect(signed.signatureWarning).toBeNull();
+    expect(signed.cut?.signature).toMatch(/^-----BEGIN SSH SIGNATURE-----/);
+
+    // bob signs in his own name, and the signers file lists only alice.
+    r.write("later.txt", "x\n");
+    const later = r.commit("later");
+    r.git(["tag", `ci/green/${later}`]);
+    await cut(r, "v2", bob, "bob");
+    const unlisted = refusal(await preparePublish({ cwd: r.dir, ref: "v2", env: WORKSTATION }));
+    expect(unlisted?.code).toBe("release-signature-unverified");
+    expect(unlisted?.message).toMatch(/bob has no key in \.chant\/allowed_signers at base/);
+  });
+
+  test("--require-provenance refuses a run with no OIDC token and passes one in CI", async () => {
+    const { r } = setup(null);
+    await cut(r, "v1");
+    const refused = refusal(await preparePublish({ cwd: r.dir, ref: "v1", env: WORKSTATION, allowUnsigned: true, requireProvenance: true }));
+    expect(refused?.code).toBe("publish-provenance-missing");
+    expect(refused?.message).toMatch(/a workstation has no OIDC token/);
+    const ci = { GITHUB_ACTIONS: "true", ACTIONS_ID_TOKEN_REQUEST_URL: "https://x", ACTIONS_ID_TOKEN_REQUEST_TOKEN: "t" };
+    expect(refusal(await preparePublish({ cwd: r.dir, ref: "v1", env: ci, allowUnsigned: true, requireProvenance: true }))).toBeNull();
+  });
+
+  test("reads the targets release.publish declares, and with one refuses a checkout that is not the release's commit or has changes", async () => {
+    const { r } = setup(null);
+    r.write("chant.config.ts", `export default { environments: ["dev"], release: { publish: [{ type: "npm", packages: ["pkg"] }, { type: "oci", image: "img", repository: "ghcr.io/acme/api" }] } };\n`);
+    const head = r.commit("declare targets");
+    r.git(["tag", `ci/green/${head}`]);
+    await cut(r, "v1");
+    const p = (await preparePublish({ cwd: r.dir, ref: "v1", env: WORKSTATION, allowUnsigned: true })) as PublishPlan;
+    expect(refusal(p)).toBeNull();
+    expect(p.targets.map((t) => [t.kind, t.name, t.destination])).toEqual([
+      ["npm", "npm (1 package)", "npm the registry npm's config names"],
+      ["oci", "oci ghcr.io/acme/api", "ghcr.io/acme/api"],
+    ]);
+    expect(p.targets[1]!.credentialEnv).toEqual(["OCI_PASSWORD"]);
+
+    r.write("untracked.txt", "x\n");
+    expect(refusal(await preparePublish({ cwd: r.dir, ref: "v1", env: WORKSTATION, allowUnsigned: true }))?.code).toBe("release-worktree-dirty");
+    rmSync(`${r.dir}/untracked.txt`);
+    r.commit("later");
+    const moved = refusal(await preparePublish({ cwd: r.dir, ref: "v1", env: WORKSTATION, allowUnsigned: true }));
+    expect(moved?.code).toBe("release-head-mismatch");
+    expect(moved?.fix).toContain(`git checkout ${head}`);
+  });
+
+  test("refuses a release.publish block that does not validate, before anything is read", async () => {
+    const { r } = setup(null);
+    await cut(r, "v1");
+    r.write("chant.config.ts", `export default { environments: ["dev"], release: { publish: [{ type: "npm", packages: [] }] } };\n`);
+    const refused = refusal(await preparePublish({ cwd: r.dir, ref: "v1", env: WORKSTATION, allowUnsigned: true }));
+    expect(refused?.code).toBe("publish-config-invalid");
+    expect(refused?.message).toMatch(/release\.publish\.0\.packages/);
+  });
+});
+