@intentius/chant 0.124.26 → 0.124.28

package/src/lifecycle/gate-change-set.e2e.test.ts

@@ -0,0 +1,122 @@
+/**
+ * Stored change sets mapped onto a real graph (#4022).
+ *
+ * The estate is the aws source `__fixtures__/change-set/lifecycle-v2.ts.txt`
+ * as a workspace member, and the change set is
+ * `__fixtures__/change-set/lifecycle-plan.floci.json`, chant's real plan of
+ * that source against floci (see `../change-set.test.ts`). The graph is the
+ * member's own `chant graph --format ir`, run by `storeGateChangeSet` as a
+ * pull-request apply runs it, and the ids are checked against `chant
+ * workspace graph`, which is what behold reads. The stored document is then
+ * read back through `chant change-set show --json`, and the gate that binds
+ * it through `workspace status`'s gate reader.
+ */
+
+import { spawnSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { composeChangeSet, lifecyclePlanPart } from "../change-set";
+import type { ChangeSet as LifecycleChangeSet } from "./change-set";
+import { storeGateChangeSet } from "./gate-change-set";
+import { appendPendingGate } from "./gate-ledger";
+import { clearMemberLedgerCache } from "./member-ledger";
+import { readMemberGates } from "../workspace/status-gates";
+
+const REPO = realpathSync(join(import.meta.dirname, "..", "..", "..", ".."));
+const LOADER = join(REPO, "node_modules", "tsx", "dist", "loader.mjs");
+const MAIN = join(REPO, "packages", "core", "src", "cli", "main.ts");
+const FIXTURES = join(import.meta.dirname, "..", "__fixtures__", "change-set");
+const TIMEOUT = 240_000;
+
+function chant(cwd: string, ...args: string[]): { code: number | null; stdout: string; stderr: string } {
+  const r = spawnSync(process.execPath, ["--import", `file://${LOADER}`, MAIN, ...args], { cwd, encoding: "utf8", maxBuffer: 64 * 1024 * 1024 });
+  return { code: r.status, stdout: r.stdout, stderr: r.stderr };
+}
+
+describe("a change set stored by a gate, on a real estate's graph", () => {
+  let root: string;
+  let member: string;
+  const git = (...a: string[]) => {
+    const r = spawnSync("git", a, { cwd: root, encoding: "utf8" });
+    if (r.status !== 0) throw new Error(`git ${a.join(" ")}: ${r.stderr}`);
+    return r.stdout.trim();
+  };
+  const plan = JSON.parse(readFileSync(join(FIXTURES, "lifecycle-plan.floci.json"), "utf8")) as LifecycleChangeSet;
+  const doc = composeChangeSet([lifecyclePlanPart({ member: "queues", plan })]);
+
+  beforeAll(() => {
+    root = realpathSync(mkdtempSync(join(tmpdir(), "chant-change-set-graph-")));
+    member = join(root, "delivery");
+    mkdirSync(member);
+    symlinkSync(join(REPO, "node_modules"), join(root, "node_modules"));
+    writeFileSync(join(root, "chant.workspace.json"), JSON.stringify({ name: "acme", schema: 1, members: [{ name: "delivery", dir: "delivery", kind: "chant" }] }));
+    writeFileSync(join(member, "chant.config.json"), JSON.stringify({ lexicons: ["aws"] }));
+    writeFileSync(join(member, "queues.ts"), readFileSync(join(FIXTURES, "lifecycle-v2.ts.txt"), "utf8"));
+    writeFileSync(join(root, ".gitignore"), "node_modules\n");
+    git("init", "-q", "-b", "main");
+    git("config", "user.email", "ci@example.test");
+    git("config", "user.name", "ci");
+    git("add", "-A");
+    git("commit", "-qm", "queues");
+    clearMemberLedgerCache();
+  });
+
+  afterAll(() => {
+    if (root) rmSync(root, { recursive: true, force: true });
+  });
+
+  test("each entry carries the node chant workspace graph gives its address", async () => {
+    const head = git("rev-parse", "HEAD");
+    const stored = await storeGateChangeSet({ doc, cwd: member, at: head });
+    expect(stored.warning).toBeUndefined();
+    expect(stored).toMatchObject({ digest: doc.digest, written: true, graph: { member: "delivery", at: head } });
+
+    const graph = chant(root, "workspace", "graph");
+    expect(graph.code, graph.stderr).toBe(0);
+    const nodeIds = new Set((JSON.parse(graph.stdout) as { nodes: Array<{ id: string }> }).nodes.map((n) => n.id));
+
+    const shown = chant(member, "change-set", "show", doc.digest, "--json");
+    expect(shown.code, shown.stderr).toBe(0);
+    const out = JSON.parse(shown.stdout);
+    expect(out).toMatchObject({ contract: 1, member: "delivery", digest: doc.digest, reason: null });
+    expect(out.changeSet.digest).toBe(doc.digest);
+    expect(out.changeSet.graph).toEqual({ member: "delivery", at: head });
+    const nodes = Object.fromEntries((out.changeSet.entries as Array<{ address: string; node: string | null }>).map((e) => [e.address, e.node]));
+    // jobs, events and dlq are declared; alerts is a live topic v2 no longer declares, so it has no node.
+    expect(nodes).toEqual({ alerts: null, dlq: "delivery/dlq", events: "delivery/events", jobs: "delivery/jobs" });
+    for (const node of Object.values(nodes)) if (node !== null) expect(nodeIds.has(node), node).toBe(true);
+
+    // From the workspace root, by --member.
+    const fromRoot = chant(root, "change-set", "show", doc.digest, "--member", "delivery", "--json");
+    expect(JSON.parse(fromRoot.stdout)).toEqual(out);
+
+    // Without --json: the grouped summary, then each change on its node.
+    const text = chant(member, "change-set", "show", doc.digest);
+    expect(text.code, text.stderr).toBe(0);
+    expect(text.stdout).toContain(`Nodes from the graph of delivery at ${head.slice(0, 12)}:`);
+    expect(text.stdout).toMatch(/create\s+queues {2}dlq {2}delivery\/dlq/);
+  }, TIMEOUT);
+
+  test("the gate that binds it links to it in workspace status", async () => {
+    const now = new Date().toISOString();
+    const later = new Date(Date.now() + 3_600_000).toISOString();
+    await appendPendingGate({ op: "pr-7-delivery", gate: "pr-apply", planDigest: doc.digest, timestamp: now, expiresAt: later }, { cwd: member });
+    const { gates } = await readMemberGates("_members/delivery/_gates", "members", git("rev-parse", "chant/lifecycle"), [], root, now);
+    expect(gates).toEqual([expect.objectContaining({ component: "pr-7-delivery", state: "pending", planDigest: doc.digest, changeSet: doc.digest })]);
+
+    const status = chant(root, "workspace", "status", "dev", "--json");
+    expect(status.stdout, status.stderr).not.toBe("");
+    const gate = (JSON.parse(status.stdout).members as Array<{ name: string; gates?: Array<{ component: string; changeSet?: string }> }>)
+      .find((m) => m.name === "delivery")
+      ?.gates?.find((g) => g.component === "pr-7-delivery");
+    expect(gate?.changeSet, status.stderr).toBe(doc.digest);
+  }, TIMEOUT);
+
+  test("a digest nothing is stored under shows no change set and exits 1", () => {
+    const missing = chant(member, "change-set", "show", `jcs1-sha256:${"0".repeat(64)}`, "--json");
+    expect(missing.code).toBe(1);
+    expect(JSON.parse(missing.stdout)).toMatchObject({ member: "delivery", changeSet: null, reason: null });
+  }, TIMEOUT);
+});

package/src/lifecycle/gate-change-set.ts

@@ -0,0 +1,133 @@
+/**
+ * Store the change set a gate binds (#4022), mapped onto the member's graph.
+ *
+ * {@link storeGateChangeSet} is what a gate that binds a change-set document's
+ * digest calls before it decides the gate: `components pr-apply`, and
+ * `components promote --release` before it decides a release gate or writes
+ * an `empty` resolution (#4045). It reads the member's
+ * graph the way `chant workspace graph` reads it, from the member's own
+ * `chant graph --format ir`, maps each entry onto a node
+ * (`../change-set-graph.ts`), and stores the document under its digest
+ * (`./change-set-store.ts`).
+ *
+ * The graph is read only when the digest is not stored yet. A graph that
+ * can't be read never stops the gate: the document is stored with `graph:
+ * null` and every `node` null, and the caller gets a warning to print.
+ */
+
+import { spawn } from "node:child_process";
+import { mapChangeSetToGraph, type ChangeSetGraphNodes } from "../change-set-graph";
+import type { ChangeSetDocument, ChangeSetGraph } from "../change-set";
+import { persistChangeSet, readStoredChangeSet } from "./change-set-store";
+import { resolveMemberLedger } from "./member-ledger";
+
+/** Reads the node ids of the graph of the project at `projectDir`. */
+export type GraphIdReader = (projectDir: string) => Promise<{ ids: string[] } | { error: string }>;
+
+const GRAPH_TIMEOUT_MS = 300_000;
+
+/**
+ * The node ids of `chant graph --format ir` in `projectDir`, run under the
+ * chant that directory resolves (its own `node_modules/.bin/chant`, else this
+ * one), as `chant workspace graph` runs each member. `args` are passed after
+ * `graph --format ir`, such as the run's `--param` flags.
+ */
+export async function readGraphIds(projectDir: string, args: readonly string[] = []): Promise<{ ids: string[] } | { error: string }> {
+  const { readerToolchain, resolveToolchain } = await import("../workspace/member-commands");
+  const { readMemberIr } = await import("../workspace/compose-graph");
+  const { findWorkspaceRoot } = await import("../project-root");
+  const root = findWorkspaceRoot(projectDir)?.dir ?? projectDir;
+  const toolchain = resolveToolchain(projectDir, root, readerToolchain());
+  const [command, ...pre] = toolchain.command;
+  const out = await new Promise<{ code: number | null; stdout: string; stderr: string }>((resolveRun) => {
+    const child = spawn(command, [...pre, "graph", "--format", "ir", ...args], { cwd: projectDir, stdio: ["ignore", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+    const timer = setTimeout(() => child.kill("SIGKILL"), GRAPH_TIMEOUT_MS);
+    child.stdout.on("data", (d) => (stdout += d));
+    child.stderr.on("data", (d) => (stderr += d));
+    child.on("error", (err) => {
+      clearTimeout(timer);
+      resolveRun({ code: null, stdout, stderr: err.message });
+    });
+    child.on("close", (code) => {
+      clearTimeout(timer);
+      resolveRun({ code, stdout, stderr });
+    });
+  });
+  if (out.code !== 0) {
+    const line = out.stderr.split("\n").map((l) => l.trim()).find(Boolean);
+    return { error: `chant graph --format ir exited ${out.code ?? "on a signal"}${line ? `: ${line}` : ""}` };
+  }
+  const read = readMemberIr(out.stdout);
+  if ("reason" in read) return { error: read.reason.message };
+  return { ids: read.ir.nodes.map((n) => n.id) };
+}
+
+let graphReaderOverride: GraphIdReader | undefined;
+
+/**
+ * Replace how a gate reads the graph wherever the default is taken, such as
+ * in `components pr-apply`; `undefined` restores {@link readGraphIds}. For
+ * tests that drive a gate and read node ids in process, so they don't start a
+ * `chant graph` child process (`gate-change-set.e2e.test.ts` covers that one).
+ */
+export function setGraphIdReader(reader: GraphIdReader | undefined): void {
+  graphReaderOverride = reader;
+}
+
+/** The graph reader a gate uses: the one {@link setGraphIdReader} set, else {@link readGraphIds} with `args`. */
+export function gateGraphReader(args: readonly string[] = []): GraphIdReader {
+  return graphReaderOverride ?? ((dir) => readGraphIds(dir, args));
+}
+
+export interface StoreGateChangeSetInput {
+  /** The document whose `digest` the gate binds. */
+  doc: ChangeSetDocument;
+  /** The member's directory: where the graph is read and whose ledger it is stored in. */
+  cwd: string;
+  /** The commit the document was planned at, recorded as the graph's `at`. */
+  at?: string | null;
+  /** How to read the graph. Defaults to {@link gateGraphReader}. */
+  readGraph?: GraphIdReader;
+}
+
+export interface StoreGateChangeSetResult {
+  digest: string;
+  /** True when this call wrote the document; false when it was stored already. */
+  written: boolean;
+  /** The graph the stored document's nodes come from, null when none could be read. Absent when it was stored already. */
+  graph?: ChangeSetGraph | null;
+  /** Why no graph was read, when none was. */
+  warning?: string;
+}
+
+/**
+ * Store `doc` under its digest in the member's ledger at `cwd`, mapped onto
+ * the member's graph, unless it is stored already. Does not push; the gate's
+ * pending fact or resolution pushes the branch after it.
+ */
+export async function storeGateChangeSet(input: StoreGateChangeSetInput): Promise<StoreGateChangeSetResult> {
+  const { doc, cwd } = input;
+  const loc = { cwd };
+  if ((await readStoredChangeSet(doc.digest, loc)).status !== "missing") return { digest: doc.digest, written: false };
+  const ledger = await resolveMemberLedger(cwd);
+  const member = ledger.members.length > 0 ? ledger.members.join("/") : null;
+  let nodes: ChangeSetGraphNodes | null = null;
+  let warning: string | undefined;
+  try {
+    const read = await (input.readGraph ?? gateGraphReader())(cwd);
+    if ("error" in read) warning = read.error;
+    else nodes = { member, at: input.at ?? null, ids: read.ids };
+  } catch (err) {
+    warning = err instanceof Error ? err.message : String(err);
+  }
+  const mapped = mapChangeSetToGraph(doc, nodes);
+  const { written } = await persistChangeSet(mapped, loc);
+  return {
+    digest: doc.digest,
+    written,
+    graph: mapped.graph ?? null,
+    ...(warning ? { warning: `the change set is stored without graph nodes: ${warning}` } : {}),
+  };
+}

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

@@ -503,3 +503,36 @@ describe("pending fact wave and heldBy (#3886, #3887)", () => {
     expect(pending[0]!.heldBy).toBeUndefined();
   });
 });
+
+describe("commit and run on gate records (#4020)", () => {
+  const base = { version: 1, op: "tg", gate: "g", timestamp: "2026-10-01T00:00:00Z" };
+  const parse = (...lines: Record<string, unknown>[]) => parseGateLedger(lines.map((l) => JSON.stringify(l)).join("\n"));
+  test("a pending fact and a resolution read back with their commit and run", () => {
+    const { pending, resolutions, malformed } = parse(
+      { ...base, kind: "pending", expiresAt: "2026-10-02T00:00:00Z", gitSha: "a".repeat(40), runId: "9001" },
+      { ...base, resolvedBy: "alice", gitSha: "a".repeat(40), runId: "9001" },
+    );
+    expect(malformed).toBe(0);
+    expect(pending[0]).toMatchObject({ gitSha: "a".repeat(40), runId: "9001" });
+    expect(resolutions[0]).toMatchObject({ gitSha: "a".repeat(40), runId: "9001" });
+  });
+  test("lines written before the fields existed still read, with neither", () => {
+    const { pending, resolutions, malformed } = parse(
+      { ...base, kind: "pending", expiresAt: "2026-10-02T00:00:00Z" },
+      { ...base, resolvedBy: "alice" },
+    );
+    expect(malformed).toBe(0);
+    expect(pending[0]).not.toHaveProperty("gitSha");
+    expect(resolutions[0]).not.toHaveProperty("runId");
+  });
+  test("a commit or run of the wrong type is dropped and the line is kept", () => {
+    const { pending, resolutions, malformed } = parse(
+      { ...base, kind: "pending", expiresAt: "2026-10-02T00:00:00Z", gitSha: 7, runId: { id: 1 } },
+      { ...base, resolvedBy: "alice", gitSha: ["x"] },
+    );
+    expect(malformed).toBe(0);
+    expect(pending[0]!.gitSha).toBeUndefined();
+    expect(pending[0]!.runId).toBeUndefined();
+    expect(resolutions[0]!.gitSha).toBeUndefined();
+  });
+});

package/src/lifecycle/gate-ledger.ts

@@ -138,6 +138,16 @@ export interface GateResolutionRecord {
    * such a record proves is that somebody approved *something*.
    */
   planDigest?: string;
+  /**
+   * The commit the gate was waiting on (#4020), copied off the pending fact the
+   * approval answers, or the run's own commit for a resolution a run writes
+   * itself (a decision point's answer, a review, a carried approval). It is not
+   * the approver's checkout, and a seal does not cover it. Absent on a
+   * resolution written before 0.124.28 and when no commit was known.
+   */
+  gitSha?: string;
+  /** The run the gate was waiting on (#4020), copied the same way as {@link GateResolutionRecord.gitSha}. */
+  runId?: string;
   /**
    * The checkpoint this approval lets a run resume from (#3947), copied off
    * the pending fact it answers. Set only on an approval of a gate that
@@ -151,6 +161,26 @@ export interface GateResolutionRecord {
    * recorded for its own environment and plan.
    */
   environment?: string;
+  /**
+   * The release this approval is for (#4045, ws-104 question 2), copied off
+   * the pending fact it answers. Set on a release gate, the gate `chant
+   * components promote --release` passes for an environment. A release gate
+   * counts only a resolution recorded for its own release, environment and
+   * change-set document digest (`planDigest`), so it names the release it
+   * admitted. Absent on every other gate, and on a resolution written before
+   * 0.124.28.
+   */
+  releaseDigest?: string;
+  /**
+   * The resolution passes a release gate over an empty change set (#4045,
+   * ws-104 question 6): the promote wrote it itself, with the actor running
+   * it in `resolvedBy`, because the change set its `planDigest` names changes
+   * nothing. A gate counts it only after it reads the stored document under
+   * `planDigest` and finds it empty, and neither a quorum nor a signing rule
+   * applies to it. It never counts as a person's approval. Absent on every
+   * other resolution.
+   */
+  empty?: true;
   /**
    * The channel this resolution was authored on (chant#2384) — set by the
    * writer, never by the caller. `chant approve` records `"cli"`, the
@@ -292,8 +322,19 @@ export interface PendingGateRecord {
   gate: string;
   /** The gate's human-readable description, when it declared one — what `chant operator status` shows a reader who wasn't there for the run. */
   description?: string;
-  /** The run that reached the gate, when the caller identifies its runs. */
+  /**
+   * The run that reached the gate. An Op run records its own id; a run with no
+   * id of its own (a component gate) records the CI run id when it ran in CI
+   * (#4020). Absent outside CI for a run that mints none.
+   */
   runId?: string;
+  /**
+   * The commit the run reached the gate at (#4020): the checkout's `HEAD`, else
+   * the commit the CI job started for. It is the commit the gate waits on, and
+   * `chant approve` copies it onto the resolution. Absent on a record written
+   * before 0.124.28 and when the run knew no commit.
+   */
+  gitSha?: string;
   /** ISO-8601 timestamp, caller-supplied (library code never calls `Date.now()` internally). */
   timestamp: string;
   /** ISO-8601 expiry, from the gate's `timeout` (default {@link DEFAULT_GATE_EXPIRY}). Past it, the fact is stale and a run re-records it. */
@@ -334,6 +375,13 @@ export interface PendingGateRecord {
    * can pick one.
    */
   environment?: string;
+  /**
+   * The release the run reached this gate for (#4045): on a release gate, the
+   * `releaseDigest` of the release `chant components promote --release`
+   * deploys. `chant approve` copies it onto the approval with the plan.
+   * Absent on every other gate, and on a fact written before 0.124.28.
+   */
+  releaseDigest?: string;
   /**
    * The channel the run that reached this gate was driven from (chant#2384).
    *
@@ -519,12 +567,29 @@ export function parseGateLedger(
         malformed++;
         continue;
       }
+      // #4045: and for the release a release gate approval is bound to.
+      const rawRelease: unknown = (parsed as { releaseDigest?: unknown }).releaseDigest;
+      if (rawRelease !== undefined && typeof rawRelease !== "string") {
+        malformed++;
+        continue;
+      }
+      // #4045: an `empty` that is not a boolean can't be told from a pass or an approval.
+      const rawEmpty: unknown = (parsed as { empty?: unknown }).empty;
+      if (rawEmpty !== undefined && typeof rawEmpty !== "boolean") {
+        malformed++;
+        continue;
+      }
       // #3947: and for the checkpoint an approval lets a run resume from.
       const rawCheckpoint: unknown = (parsed as { checkpointDigest?: unknown }).checkpointDigest;
       if (rawCheckpoint !== undefined && typeof rawCheckpoint !== "string") {
         malformed++;
         continue;
       }
+      // #4020: a commit or run id of the wrong type is dropped, so a reader can trust the type without losing the line.
+      for (const key of ["gitSha", "runId"] as const) {
+        const v: unknown = (parsed as Record<string, unknown>)[key];
+        if (v !== undefined && typeof v !== "string") delete (parsed as Record<string, unknown>)[key];
+      }
       if (parsed.kind === "pending") {
         if (typeof parsed.expiresAt !== "string") {
           malformed++;

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

@@ -0,0 +1,180 @@
+/**
+ * #4031: who may cut a release, and the cut's signature. The declaration's
+ * `identity.gates.release` names the class that may cut; a cut is signed
+ * with the actor's ssh key over the release digest, label, actor and time,
+ * and `release list` and `workspace status` verify it on every read. With
+ * `ci.green.signedSince`, a hand-pushed green tag cuts nothing.
+ */
+
+import { spawnSync } from "node:child_process";
+import { afterAll, describe, expect, test } from "vitest";
+import { cutRelease, ReleaseCutError } from "./release-cut";
+import { readCuts, type ReleaseArtifact } from "./release-store";
+import type { CompiledTarget, TargetCompiler } from "../components/release-compile";
+import { hasSshKeygen, TestRepo, type Key } from "../workspace/trust/test-repo";
+import { releasesDocument } from "../workspace/releases";
+import { workspaceStatus, type StatusDocument } from "../workspace/status";
+import { checkReleaseSignature, type GateAdmissionRule } from "../workspace/identity-gate-rule";
+import { contract } from "../workspace/__fixtures__/contract-repo";
+import releasesSchema from "../workspace/releases.schema.json";
+import statusSchema from "../workspace/status.schema.json";
+import { rmSync } from "node:fs";
+import { dirname } from "node:path";
+
+const repos: TestRepo[] = [];
+afterAll(() => {
+  for (const r of repos) rmSync(dirname(r.dir), { recursive: true, force: true });
+});
+
+function compiler(): TargetCompiler {
+  return {
+    async compile(env): Promise<CompiledTarget> {
+      return {
+        env,
+        params: [],
+        components: ["api"],
+        buildSteps: { api: [{ kind: "docker-build", context: "api", into: "api.tar" }] },
+        buildInputs: { api: ["api"] },
+        componentFiles: { api: "api.component.ts" },
+        templates: [{ component: "api", path: "dist/api.json", content: `{"env":"${env}"}\n` }],
+      };
+    },
+    async buildArtifacts(_env, components): Promise<ReleaseArtifact[]> {
+      return components.map((c) => ({ component: c, kind: "image" as const, path: `${c}.tar`, digest: `sha256:${"b".repeat(64)}` }));
+    },
+  };
+}
+
+/** A domain class, `releaser`, from a path pin, granted by the `releaser` role. */
+const PLUGIN = {
+  "classes/package.json": JSON.stringify({ name: "@acme/classes", version: "1.0.0", exports: { "./workspace-principals": "./principals.json" } }),
+  "classes/principals.json": JSON.stringify({ schema: 1, classes: [{ name: "releaser", description: "people who may cut a release", role: "releaser" }] }),
+};
+
+/**
+ * A workspace whose root member is a chant project with three environments,
+ * signed by alice and bob, with alice holding the releaser role. `extra`
+ * goes into the declaration.
+ */
+function setup(extra: Record<string, unknown>): { r: TestRepo; alice: Key; bob: Key; head: string } {
+  const r = new TestRepo("release-cut");
+  repos.push(r);
+  const alice = r.key("alice");
+  const bob = r.key("bob");
+  r.write("chant.workspace.json", JSON.stringify({ name: "acme", schema: 1, pins: [{ path: "classes" }], members: [{ name: "root", dir: ".", kind: "other", because: "the release fixture" }], ...extra }, null, 2));
+  for (const [path, text] of Object.entries(PLUGIN)) r.write(path, text);
+  r.write(".chant/allowed_signers", `alice ${alice.pub}\nbob ${bob.pub}\n`);
+  r.write(".chant/trust.json", JSON.stringify({ schema: 1, roles: { releaser: ["alice"] } }));
+  r.write("chant.config.ts", `export default { environments: ["dev", "prod"] };\n`);
+  r.write("api.component.ts", "export const api = {};\n");
+  r.write("api/Dockerfile", "FROM scratch\n");
+  const head = r.commit("init");
+  return { r, alice, bob, head };
+}
+
+const NOW = () => new Date("2026-10-16T10:00:00.000Z");
+const cut = (r: TestRepo, actor: string, sign?: Key, label: string | null = "v1.0.0") =>
+  cutRelease({ cwd: r.dir, compiler: compiler(), label, actor, env: {}, now: NOW, ...(sign ? { sign: sign.file } : {}) });
+const code = async (p: Promise<unknown>) => ((await p.catch((e: unknown) => e)) as ReleaseCutError).code;
+const noLedger = (r: TestRepo) => spawnSync("git", ["rev-parse", "--verify", "--quiet", "refs/heads/chant/lifecycle"], { cwd: r.dir }).status !== 0;
+
+describe.skipIf(!hasSshKeygen)("who may cut a release (#4031)", () => {
+  const RELEASE_GATE = { identity: { gates: { release: { class: "releaser" } } } };
+
+  test("cutting as someone outside the release gate's class is refused, and nothing is written", async () => {
+    const { r, bob } = setup(RELEASE_GATE);
+    r.git(["tag", `ci/green/${r.git(["rev-parse", "HEAD"]).trim()}`]);
+    const err = await cut(r, "bob", bob).catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(ReleaseCutError);
+    expect((err as ReleaseCutError).code).toBe("release-signer-refused");
+    expect((err as ReleaseCutError).message).toMatch(/bob is not in the class releaser that gate release needs/);
+    expect(noLedger(r)).toBe(true);
+  });
+
+  test("an unsigned cut, or one signed with another signer's key, is refused under the gate", async () => {
+    const { r, alice, bob } = setup(RELEASE_GATE);
+    r.git(["tag", `ci/green/${r.git(["rev-parse", "HEAD"]).trim()}`]);
+    expect(await code(cut(r, "alice"))).toBe("release-unsigned");
+    const forged = await cut(r, "alice", bob).catch((e: unknown) => e);
+    expect((forged as ReleaseCutError).code).toBe("release-signer-refused");
+    expect((forged as ReleaseCutError).message).toMatch(/does not verify for alice/);
+    expect(noLedger(r)).toBe(true);
+    expect(alice.name).toBe("alice");
+  });
+
+  test("a cut by a releaser carries a signature that release list and workspace status verify", async () => {
+    const { r, alice } = setup(RELEASE_GATE);
+    const head = r.git(["rev-parse", "HEAD"]).trim();
+    r.git(["tag", `ci/green/${head}`]);
+    const result = await cut(r, "alice", alice);
+    expect(result.cut?.signature).toMatch(/^-----BEGIN SSH SIGNATURE-----/);
+    const { cuts } = await readCuts({ cwd: r.dir });
+    expect(cuts).toHaveLength(1);
+    expect(cuts[0]).toMatchObject({ label: "v1.0.0", actor: "alice", signature: result.cut!.signature });
+
+    const list = await releasesDocument({ cwd: r.dir });
+    contract(releasesSchema).expectValid(list);
+    const entry = (list as Extract<typeof list, { releases: unknown }>).releases[0];
+    expect(entry.cuts[0].signatureCheck).toMatchObject({ status: "verified", key: expect.stringMatching(/^SHA256:/), reason: "signed by alice, in the class releaser" });
+
+    const status = (await workspaceStatus({ cwd: r.dir, env: "dev" })) as Extract<StatusDocument, { members: unknown }>;
+    contract(statusSchema).expectValid(status);
+    expect(status.members[0].releaseCuts).toEqual([
+      {
+        releaseDigest: result.release.releaseDigest,
+        label: "v1.0.0",
+        commit: head,
+        actor: "alice",
+        timestamp: "2026-10-16T10:00:00.000Z",
+        signature: result.cut!.signature,
+        signatureCheck: { status: "verified", key: entry.cuts[0].signatureCheck.key, reason: "signed by alice, in the class releaser" },
+      },
+    ]);
+
+    // A cut line edited after the fact no longer verifies: the label is signed.
+    const rule: GateAdmissionRule = { gate: "release", class: null, signers: { signersPath: ".chant/allowed_signers", active: true, signers: [{ principal: "alice", key: alice.pub, line: 1 }] }, roles: {}, classes: [] };
+    expect(checkReleaseSignature(rule, { ...cuts[0] }).status).toBe("verified");
+    expect(checkReleaseSignature(rule, { ...cuts[0], label: "v9.9.9" })).toMatchObject({ status: "unverified", reason: expect.stringMatching(/does not verify for alice/) });
+    expect(checkReleaseSignature(rule, { ...cuts[0], signature: null }).status).toBe("unsigned");
+  });
+
+  test("without a release gate a cut may be unsigned, and a signed one is still verified on read", async () => {
+    const { r, bob } = setup({});
+    r.git(["tag", `ci/green/${r.git(["rev-parse", "HEAD"]).trim()}`]);
+    const plain = await cut(r, "carol", undefined, "v1");
+    expect(plain.cut?.signature).toBeNull();
+    r.write("README.md", "next\n");
+    const next = r.commit("next");
+    r.git(["tag", `ci/green/${next}`]);
+    const signed = await cut(r, "bob", bob, "v2");
+    expect(signed.cut?.signature).toMatch(/BEGIN SSH SIGNATURE/);
+    const list = (await releasesDocument({ cwd: r.dir })) as Extract<Awaited<ReturnType<typeof releasesDocument>>, { releases: unknown }>;
+    // Both cuts share one time, so the list's order between them is the digests'.
+    expect(list.releases.map((x) => [x.label, x.cuts[0].signatureCheck.status]).sort()).toEqual([
+      ["v1", "unsigned"],
+      ["v2", "verified"],
+    ]);
+  });
+
+  test("with ci.green.signedSince, a hand-pushed green tag cuts nothing", async () => {
+    const green = { branch: "main", phases: { test: ["test"] }, require: ["test"] };
+    const { r, alice, head: pivot } = setup({ ...RELEASE_GATE, ci: { green } });
+    // Tags on commits from the pivot on need a statement; the declaration says so in the next commit.
+    const decl = JSON.parse(r.git(["show", "HEAD:chant.workspace.json"]));
+    r.write("chant.workspace.json", JSON.stringify({ ...decl, ci: { green: { ...green, signedSince: pivot } } }, null, 2));
+    const head = r.commit("require signed ci tags");
+    r.git(["tag", "-a", "-m", "ci: by hand", `ci/green/${head}`, head]);
+    const err = await cut(r, "alice", alice).catch((e: unknown) => e);
+    expect((err as ReleaseCutError).code).toBe("release-commit-not-green");
+    expect((err as ReleaseCutError).message).toMatch(/no ci\/green tag that counts.*ignored: ci\/green\/[0-9a-f]+ \(unsigned\)/);
+    expect(noLedger(r)).toBe(true);
+
+    // A signedSince that names no commit here refuses the cut.
+    r.write("chant.workspace.json", JSON.stringify({ ...decl, ci: { green: { ...green, signedSince: "f".repeat(40) } } }, null, 2));
+    const broken = r.commit("a signedSince from another clone");
+    r.git(["tag", `ci/green/${broken}`, broken]);
+    const refused = await cut(r, "alice", alice).catch((e: unknown) => e);
+    expect((refused as ReleaseCutError).code).toBe("declaration-invalid");
+    expect(noLedger(r)).toBe(true);
+  });
+});