@intentius/chant 0.124.27 → 0.124.29

package/src/op/commit-run-gate-deploy-join.test.ts

@@ -0,0 +1,117 @@
+/**
+ * A gated deploy leaves four records that name each other (#4020): the run
+ * record, the pending gate fact, the resolution and the release record. From
+ * any one of them, the other three are one lookup away, by the commit sha, the
+ * run id or the gate.
+ */
+import { describe, test, expect, afterEach, vi } from "vitest";
+import type { ActivityFn, ActivityProfile } from "./activity-registry";
+import type { OpConfig } from "./types";
+import { runOpLocally } from "./local-executor";
+import { memoryGateLedgerPort } from "./gate";
+import { resolveGateRunLocator, runOriginOfLocator } from "./gate-run-locator";
+import { admissionOf, resolveRunId, type ReleaseRecord } from "../lifecycle/release-ledger";
+import type { GateResolutionRecord } from "../lifecycle/gate-ledger";
+
+const SHA = "c0ffee".repeat(6) + "c0ff";
+const PROFILES: Record<string, ActivityProfile> = { single: { timeout: "5m", retry: { maximumAttempts: 1 } } };
+const NOW = "2026-10-16T10:00:00.000Z";
+const CI = {
+  GITHUB_ACTIONS: "true",
+  GITHUB_REPOSITORY: "acme/app",
+  GITHUB_RUN_ID: "9001",
+  GITHUB_SERVER_URL: "https://github.example",
+  GITHUB_API_URL: "https://github.example/api/v3",
+};
+
+afterEach(() => vi.unstubAllEnvs());
+
+const config: OpConfig = {
+  name: "ship",
+  overview: "",
+  labels: { Env: "prod" },
+  phases: [
+    { name: "Build", steps: [{ kind: "activity", fn: "build" }] },
+    { name: "Release", steps: [{ kind: "gate", gate: "approve-release" }, { kind: "activity", fn: "release" }] },
+  ],
+};
+const activities = new Map<string, ActivityFn>([
+  ["build", async () => undefined],
+  ["release", async () => undefined],
+]);
+
+describe("a gated deploy: commit, run, gate and deploy record join (#4020)", () => {
+  test("each record names the commit, and the run, gate and deploy name one another", async () => {
+    for (const [k, v] of Object.entries(CI)) vi.stubEnv(k, v);
+    const port = memoryGateLedgerPort();
+
+    // 1. The run reaches the gate and stops. Its record and the pending fact carry the commit.
+    const first = await runOpLocally(config, activities, PROFILES, undefined, { gates: port, now: NOW, commit: SHA });
+    expect(first.status).toBe("gated");
+    const run = first.record;
+    const pending = port.appended[0]!;
+    expect(run.gitSha).toBe(SHA);
+    expect(run.runOrigin).toEqual({ forge: "github", repo: "acme/app", url: "https://github.example/acme/app/actions/runs/9001" });
+    expect(pending.gitSha).toBe(SHA);
+    expect(pending.runId).toBe(run.id);
+
+    // 2. Someone approves. `chant approve` copies the commit and run off the pending fact it answers.
+    const resolution: GateResolutionRecord = {
+      version: 1, op: pending.op, gate: pending.gate, resolvedBy: "alice", timestamp: "2026-10-16T10:05:00.000Z",
+      gitSha: pending.gitSha, runId: pending.runId,
+    };
+    const second = await runOpLocally(config, activities, PROFILES, undefined, {
+      gates: memoryGateLedgerPort({ pending: [pending], resolutions: [resolution] }),
+      now: "2026-10-16T10:06:00.000Z",
+      commit: SHA,
+    });
+    expect(second.status).toBe("ok");
+
+    // 3. The release activity records the deploy, naming the gate that admitted it.
+    const admitted = admissionOf([resolution], { op: "ship", gate: "approve-release" })!;
+    const ci = resolveRunId();
+    const release: ReleaseRecord = {
+      version: 1, component: "site", env: "prod", digest: `sha256:${"d".repeat(64)}`, gitSha: SHA,
+      runId: ci.runId, runOrigin: ci.runOrigin, timestamp: "2026-10-16T10:07:00.000Z", actor: "ci",
+      approver: admitted.approver, admission: admitted.admission,
+    };
+
+    // From the commit: the run, the gate and the deploy.
+    const byCommit = {
+      runs: [run, second.record].filter((r) => r.gitSha === SHA),
+      pending: port.appended.filter((p) => p.gitSha === SHA),
+      resolutions: [resolution].filter((r) => r.gitSha === SHA),
+      releases: [release].filter((r) => r.gitSha === SHA),
+    };
+    expect(byCommit.runs.map((r) => r.id)).toContain(run.id);
+    expect(byCommit.pending).toEqual([pending]);
+    expect(byCommit.resolutions).toEqual([resolution]);
+    expect(byCommit.releases).toEqual([release]);
+
+    // From the run: its gate, by run id, and the CI run it ran in.
+    expect(run.gate).toMatchObject({ name: pending.gate });
+    expect(resolution.runId).toBe(run.id);
+    expect(pending.runId).toBe(run.id);
+
+    // From the deploy: the gate resolution that admitted it, the approver, and the CI run the run was in.
+    expect(release.admission).toEqual({ op: pending.op, gate: pending.gate, resolvedAt: resolution.timestamp });
+    expect(release.approver).toBe(resolution.resolvedBy);
+    expect(release.runOrigin).toEqual(run.runOrigin);
+    expect(release.runId).toBe(runOriginOfLocator(resolveGateRunLocator()!).runId);
+    expect(release.gitSha).toBe(run.gitSha);
+  });
+
+  test("a run outside CI records its commit and no run origin", async () => {
+    for (const k of ["GITHUB_RUN_ID", "CI_PIPELINE_ID"]) vi.stubEnv(k, "");
+    const result = await runOpLocally(config, activities, PROFILES, undefined, { gates: memoryGateLedgerPort(), now: NOW, commit: SHA });
+    expect(result.record.gitSha).toBe(SHA);
+    expect(result.record).not.toHaveProperty("runOrigin");
+  });
+
+  test("admissionOf names the newest of several approvals and joins their approvers", () => {
+    const at = (resolvedBy: string, timestamp: string): GateResolutionRecord => ({ version: 1, op: "ship", gate: "g", resolvedBy, timestamp, planDigest: "p" });
+    expect(admissionOf([at("a", "2026-01-01T00:00:00Z"), at("b", "2026-01-02T00:00:00Z"), at("a", "2026-01-03T00:00:00Z")], { op: "ship", gate: "g", planDigest: "p" }))
+      .toEqual({ approver: "a, b", admission: { op: "ship", gate: "g", resolvedAt: "2026-01-03T00:00:00Z" } });
+    expect(admissionOf([at("a", "2026-01-01T00:00:00Z")], { op: "ship", gate: "g", planDigest: "other" })).toBeUndefined();
+  });
+});

package/src/op/gate-name.ts

@@ -44,6 +44,16 @@ export const WORKSPACE_UPGRADE_GATE_OP = "workspace-upgrade";
  */
 export const OVERRIDE_GATE_OP = "policy-override";
 
+/**
+ * The op name every release gate is recorded under (#4045): the gates
+ * `chant components promote --release` reaches, `_gates/release.jsonl`, each
+ * named as its composition names it and bound to a release, an environment
+ * and the release's change set. Like a fan-out, it has no `*.op.ts`, and like
+ * the pull-request gate it approves a change to an environment, so it is
+ * never resolved over MCP or ACP.
+ */
+export const RELEASE_GATE_OP = "release";
+
 /**
  * The pull-request loop records its gate under `pr-<number>`, or
  * `pr-<number>-<member>` in a workspace member (`prOp` in `pr-loop.ts`), and
@@ -54,12 +64,12 @@ const PR_GATE_OP = /^pr-\d+(?:-[a-z0-9][a-z0-9-]*)?$/;
 /**
  * Whether gates recorded under this op name are never resolved over MCP or ACP
  * (chant#3485, chant#3513). These are the gate-only names MCP cannot discover:
- * `fan-out`, `workspace-upgrade`, `policy-override` (#3760) and the
- * pull-request gate `pr-<number>`. With
+ * `fan-out`, `workspace-upgrade`, `policy-override` (#3760), `release`
+ * (#4045) and the pull-request gate `pr-<number>`. With
  * no Op config to read `neverOverMcp` from, the pending record carries it.
  */
 export function isNeverOverMcpGateOp(op: string): boolean {
-  return op === FAN_OUT_GATE_OP || op === WORKSPACE_UPGRADE_GATE_OP || op === OVERRIDE_GATE_OP || PR_GATE_OP.test(op);
+  return op === FAN_OUT_GATE_OP || op === WORKSPACE_UPGRADE_GATE_OP || op === OVERRIDE_GATE_OP || op === RELEASE_GATE_OP || PR_GATE_OP.test(op);
 }
 
 /** Either spelling of a gate step's name. `gate` since #2202; `signalName` through 0.59.0. */

package/src/op/gate-release.test.ts

@@ -0,0 +1,126 @@
+/**
+ * A release gate (#4045, ws-104 question 2) binds the release, the
+ * environment and the change-set document digest; an approval counts only
+ * when all three match. An `empty` pass (question 6) counts only once the
+ * stored document reads back empty. Decided against an in-memory ledger.
+ */
+
+import { describe, expect, test } from "vitest";
+import { evaluateGate, memoryGateLedgerPort } from "./gate";
+import type { GateResolutionRecord } from "../lifecycle/gate-ledger";
+
+const sha = (c: string) => `jcs1-sha256:${c.repeat(64)}`;
+const RELEASE_A = sha("a");
+const RELEASE_B = sha("b");
+const DOC = sha("d");
+const NOW = "2026-10-16T12:00:00.000Z";
+const LATER = "2026-10-16T13:00:00.000Z";
+
+const gateInput = (over: Partial<Parameters<typeof evaluateGate>[1]> = {}) => ({
+  op: "release",
+  gate: "prod-release",
+  environment: "prod",
+  planDigest: DOC,
+  releaseDigest: RELEASE_A,
+  now: NOW,
+  ...over,
+});
+
+const approval = (over: Partial<GateResolutionRecord> = {}): GateResolutionRecord => ({
+  version: 1,
+  op: "release",
+  gate: "prod-release",
+  resolvedBy: "alice",
+  timestamp: "2026-10-16T12:30:00.000Z",
+  planDigest: DOC,
+  environment: "prod",
+  releaseDigest: RELEASE_A,
+  ...over,
+});
+
+describe("a release gate binds the release, the environment and the change set", () => {
+  test("the pending fact names the release it waits on", async () => {
+    const port = memoryGateLedgerPort();
+    const check = await evaluateGate(port, gateInput());
+    expect(check.satisfied).toBe(false);
+    expect(port.appended[0]).toMatchObject({ op: "release", gate: "prod-release", environment: "prod", planDigest: DOC, releaseDigest: RELEASE_A });
+  });
+
+  test("an approval for the release, environment and change set passes, and names the release it admitted", async () => {
+    const port = memoryGateLedgerPort({ resolutions: [approval()] });
+    const check = await evaluateGate(port, gateInput({ now: LATER }));
+    expect(check.satisfied).toBe(true);
+    if (check.satisfied) expect(check.resolution.releaseDigest).toBe(RELEASE_A);
+  });
+
+  test("an approval for one release can't be used by another, even for the same change-set digest", async () => {
+    const port = memoryGateLedgerPort({ resolutions: [approval()] });
+    const check = await evaluateGate(port, gateInput({ releaseDigest: RELEASE_B, now: LATER }));
+    expect(check.satisfied).toBe(false);
+    if (!check.satisfied) {
+      expect(check.mismatch).toMatchObject({ resolvedBy: "alice", approved: DOC, planned: DOC, environment: "prod" });
+      expect(check.pending.releaseDigest).toBe(RELEASE_B);
+    }
+  });
+
+  test("an approval for one environment can't be used for another", async () => {
+    const port = memoryGateLedgerPort({ resolutions: [approval({ environment: "staging" })] });
+    const check = await evaluateGate(port, gateInput({ now: LATER }));
+    expect(check.satisfied).toBe(false);
+    if (!check.satisfied) expect(check.pending.environment).toBe("prod");
+  });
+
+  test("an approval for another change set of the same release doesn't pass", async () => {
+    const port = memoryGateLedgerPort({ resolutions: [approval({ planDigest: sha("e") })] });
+    const check = await evaluateGate(port, gateInput({ now: LATER }));
+    expect(check.satisfied).toBe(false);
+    if (!check.satisfied) expect(check.mismatch?.approved).toBe(sha("e"));
+  });
+
+  test("a gate that binds no release counts no approval recorded for one", async () => {
+    const port = memoryGateLedgerPort({ resolutions: [approval()] });
+    const check = await evaluateGate(port, gateInput({ releaseDigest: undefined, now: LATER }));
+    expect(check.satisfied).toBe(false);
+  });
+
+  test("a standing fact for another release is recorded again for this one", async () => {
+    const port = memoryGateLedgerPort();
+    await evaluateGate(port, gateInput());
+    const again = await evaluateGate(port, gateInput({ releaseDigest: RELEASE_B, now: "2026-10-16T12:01:00.000Z" }));
+    expect(again.satisfied).toBe(false);
+    if (!again.satisfied) expect(again.recorded).toBe(true);
+    expect(port.appended.map((p) => p.releaseDigest)).toEqual([RELEASE_A, RELEASE_B]);
+  });
+});
+
+describe("an empty pass", () => {
+  const pass = approval({ resolvedBy: "bob", empty: true, timestamp: "2026-10-16T11:59:00.000Z" });
+
+  test("passes the gate once the stored change set reads back empty", async () => {
+    const asked: string[] = [];
+    const port = memoryGateLedgerPort({ resolutions: [pass] });
+    const check = await evaluateGate(port, gateInput({ verifyEmpty: async (d) => (asked.push(d), true) }));
+    expect(check).toMatchObject({ satisfied: true, via: "empty", resolution: { resolvedBy: "bob", empty: true, releaseDigest: RELEASE_A } });
+    expect(asked).toEqual([DOC]);
+    expect(port.appended).toEqual([]);
+  });
+
+  test("doesn't pass when the stored change set is not empty", async () => {
+    const port = memoryGateLedgerPort({ resolutions: [pass] });
+    const check = await evaluateGate(port, gateInput({ verifyEmpty: async () => false }));
+    expect(check.satisfied).toBe(false);
+  });
+
+  test("is never an approval: without a verifier, or on a gate without a plan, it counts for nothing", async () => {
+    const port = memoryGateLedgerPort({ resolutions: [pass] });
+    expect((await evaluateGate(port, gateInput())).satisfied).toBe(false);
+    const plain = memoryGateLedgerPort({ resolutions: [{ ...pass, planDigest: undefined, releaseDigest: undefined }] });
+    expect((await evaluateGate(plain, { op: "release", gate: "prod-release", now: NOW })).satisfied).toBe(false);
+  });
+
+  test("for another release it doesn't pass", async () => {
+    const port = memoryGateLedgerPort({ resolutions: [pass] });
+    const check = await evaluateGate(port, gateInput({ releaseDigest: RELEASE_B, verifyEmpty: async () => true }));
+    expect(check.satisfied).toBe(false);
+  });
+});

package/src/op/gate-run-locator.test.ts

@@ -0,0 +1,110 @@
+import { describe, test, expect } from "vitest";
+import { ciCommitFromEnv, ciRunIdFromEnv, resolveGateRunLocator, runOriginOfLocator } from "./gate-run-locator";
+import { resolveCiRun, resolveRunId } from "../lifecycle/release-ledger";
+
+const GITHUB = {
+  GITHUB_ACTIONS: "true",
+  GITHUB_REPOSITORY: "acme/app",
+  GITHUB_RUN_ID: "9001",
+  GITHUB_RUN_ATTEMPT: "2",
+  GITHUB_SERVER_URL: "https://github.example",
+  GITHUB_API_URL: "https://github.example/api/v3",
+  GITHUB_SHA: "a".repeat(40),
+};
+const GITLAB = {
+  GITLAB_CI: "true",
+  CI_API_V4_URL: "https://gitlab.example/api/v4",
+  CI_PROJECT_ID: "77",
+  CI_PROJECT_PATH: "acme/app",
+  CI_PIPELINE_ID: "5150",
+  CI_PIPELINE_URL: "https://gitlab.example/acme/app/-/pipelines/5150",
+  CI_JOB_ID: "31",
+  CI_JOB_NAME: "deploy",
+  CI_JOB_URL: "https://gitlab.example/acme/app/-/jobs/31",
+  CI_COMMIT_SHA: "b".repeat(40),
+};
+const FORGEJO = {
+  ...GITHUB,
+  FORGEJO_ACTIONS: "true",
+  GITHUB_WORKFLOW_REF: "acme/app/.forgejo/workflows/deploy.yml@refs/heads/main",
+  GITHUB_REF_NAME: "main",
+  GITHUB_SERVER_URL: "https://forgejo.example",
+  GITHUB_API_URL: "https://forgejo.example/api/v1",
+};
+
+describe("runOriginOfLocator (#4020)", () => {
+  test("a GitHub locator maps to forge github, with its repo and run page, and the run as the run id", () => {
+    const locator = resolveGateRunLocator(GITHUB)!;
+    expect(runOriginOfLocator(locator)).toEqual({
+      runId: "9001",
+      runOrigin: { forge: "github", repo: "acme/app", url: "https://github.example/acme/app/actions/runs/9001" },
+    });
+  });
+
+  test("a Forgejo locator maps to forge github, since the url names the host", () => {
+    const locator = resolveGateRunLocator(FORGEJO)!;
+    expect(locator.forge).toBe("forgejo");
+    expect(runOriginOfLocator(locator)).toEqual({
+      runId: "9001",
+      runOrigin: { forge: "github", repo: "acme/app", url: "https://forgejo.example/acme/app/actions/runs/9001" },
+    });
+  });
+
+  test("a GitLab locator stays gitlab, with the project id as repo and the pipeline id as the run id", () => {
+    const locator = resolveGateRunLocator(GITLAB)!;
+    expect(runOriginOfLocator(locator)).toEqual({
+      runId: "5150",
+      runOrigin: { forge: "gitlab", repo: "77", url: "https://gitlab.example/acme/app/-/jobs/31" },
+    });
+  });
+
+  test("the API base, attempt, job and workflow fields do not reach the origin", () => {
+    const { runOrigin } = runOriginOfLocator(resolveGateRunLocator(GITHUB)!);
+    expect(Object.keys(runOrigin).sort()).toEqual(["forge", "repo", "url"]);
+  });
+
+  test("a locator without a url maps to an origin without one", () => {
+    const { api, repo, run } = resolveGateRunLocator(GITHUB)!;
+    expect(runOriginOfLocator({ forge: "github", api, repo, run })).toEqual({ runId: "9001", runOrigin: { forge: "github", repo: "acme/app" } });
+  });
+});
+
+describe("a GateRunLocator and the RunOrigin written for the same CI job name the same run (#4020)", () => {
+  test.each([
+    ["GitHub", GITHUB, "github"],
+    ["Forgejo", FORGEJO, "github"],
+    ["GitLab", GITLAB, "gitlab"],
+  ] as const)("%s", (_name, env, forge) => {
+    const locator = resolveGateRunLocator(env)!;
+    const fromLocator = runOriginOfLocator(locator);
+    const written = resolveCiRun(env);
+    // A deploy record's run id is the one resolveRunId gives, and the gate's is the CI run id.
+    expect(resolveRunId(undefined, env).runId).toBe(fromLocator.runId);
+    expect(ciRunIdFromEnv(env)).toBe(fromLocator.runId);
+    expect(written?.runId).toBe(fromLocator.runId);
+    expect(written?.runOrigin.forge).toBe(forge);
+    expect(fromLocator.runOrigin.forge).toBe(written?.runOrigin.forge);
+  });
+
+  test("on GitHub and Forgejo the two origins are the same object, repo and url included", () => {
+    for (const env of [GITHUB, FORGEJO]) {
+      expect(runOriginOfLocator(resolveGateRunLocator(env)!).runOrigin).toEqual(resolveCiRun(env)!.runOrigin);
+    }
+  });
+
+  test("on GitLab the locator keeps the project id and the job page where the origin keeps the path and the pipeline page", () => {
+    expect(runOriginOfLocator(resolveGateRunLocator(GITLAB)!).runOrigin).toEqual({ forge: "gitlab", repo: "77", url: GITLAB.CI_JOB_URL });
+    expect(resolveCiRun(GITLAB)!.runOrigin).toEqual({ forge: "gitlab", repo: "acme/app", url: GITLAB.CI_PIPELINE_URL });
+  });
+});
+
+describe("the CI environment helpers", () => {
+  test("the commit is GITHUB_SHA or CI_COMMIT_SHA, and none outside CI", () => {
+    expect(ciCommitFromEnv(GITHUB)).toBe("a".repeat(40));
+    expect(ciCommitFromEnv(GITLAB)).toBe("b".repeat(40));
+    expect(ciCommitFromEnv({})).toBeUndefined();
+  });
+  test("the run id is none outside CI", () => {
+    expect(ciRunIdFromEnv({})).toBeUndefined();
+  });
+});

package/src/op/gate-run-locator.ts

@@ -7,6 +7,7 @@
  */
 
 import type { ForgeKind } from "../pr-forge";
+import type { RunOrigin } from "../lifecycle/release-ledger";
 
 /** Where the job that recorded a pending fact runs, and what its forge needs to start it again. */
 export interface GateRunLocator {
@@ -103,3 +104,37 @@ export function isGateRunLocator(value: unknown): value is GateRunLocator {
   if (v.forge === "forgejo") return typeof v.workflow === "string" && typeof v.ref === "string";
   return false;
 }
+
+/**
+ * The CI run a {@link GateRunLocator} names, in the shape a run and a deploy
+ * record carry (#4020). `runId` is the locator's `run`. Forge `github` and
+ * `forgejo` both become `github`, as `RunOrigin.forge` documents (the `url`
+ * names the host), and `gitlab` stays `gitlab`. `repo` and `url` carry over.
+ * The API base, attempt, job and workflow fields stay on the locator, which
+ * exists to start the job again.
+ */
+export function runOriginOfLocator(locator: GateRunLocator): { runId: string; runOrigin: RunOrigin } {
+  return {
+    runId: locator.run,
+    runOrigin: {
+      forge: locator.forge === "gitlab" ? "gitlab" : "github",
+      repo: locator.repo,
+      ...(locator.url ? { url: locator.url } : {}),
+    },
+  };
+}
+
+/**
+ * The id of the CI run this process is in, or undefined outside CI: the
+ * GitHub (and Forgejo) run id, else the GitLab pipeline id. The same
+ * precedence `resolveRunId` (../lifecycle/release-ledger.ts) uses for a
+ * deploy record, so a gate and a deploy name the run alike.
+ */
+export function ciRunIdFromEnv(env: Record<string, string | undefined> = process.env): string | undefined {
+  return env.GITHUB_RUN_ID || env.CI_PIPELINE_ID || undefined;
+}
+
+/** The commit the CI job was started for: `GITHUB_SHA` (GitHub and Forgejo) or `CI_COMMIT_SHA` (GitLab). Undefined outside CI. */
+export function ciCommitFromEnv(env: Record<string, string | undefined> = process.env): string | undefined {
+  return env.GITHUB_SHA || env.CI_COMMIT_SHA || undefined;
+}

package/src/op/gate.ts

@@ -53,7 +53,8 @@ import { sortedJsonReplacer } from "../utils";
 import { gateContextDigest, type GateApprover, type ResolvedGateApproval } from "./gate-approval";
 import { pushLifecycleReport, readBlobBySha, readBlobFromPath, readPathSha, requireLifecycleLedger, writeBlobToPath, RefCASConflictError } from "../lifecycle/git";
 import { parseDuration } from "./duration";
-import { resolveGateRunLocator } from "./gate-run-locator";
+import { ciRunIdFromEnv, resolveGateRunLocator } from "./gate-run-locator";
+import { resolveCommitSha } from "../lifecycle/commit-sha";
 import { refuseGateWithoutRecording } from "../lifecycle/no-record";
 import { gateCheckpointDigest, gateCheckpointText, readGateCheckpointText, writeGateCheckpoint, type GateCheckpoint } from "../lifecycle/gate-checkpoint";
 import type { ResolvedGateAlias } from "./gate-alias";
@@ -258,8 +259,10 @@ export interface GateCheckInput {
   description?: string;
   /** The gate's authored `timeout`, which becomes the pending fact's expiry. Default {@link DEFAULT_GATE_EXPIRY}. */
   timeout?: string;
-  /** Identifies the run that reached the gate, when the caller has one. */
+  /** Identifies the run that reached the gate, when the caller has one. Absent, a run in CI records the CI run id (#4020). */
   runId?: string;
+  /** The commit the run is at (#4020). Absent, the checkout's `HEAD`, else the commit the CI job started for. */
+  gitSha?: string;
   /**
    * The plan this run reached the gate with (#2300) — `computePlanDigest`'s
    * output (`../lifecycle/plan-digest.ts`), from the Plan phase that ran a
@@ -321,6 +324,25 @@ export interface GateCheckInput {
    * carried earlier counts only while its alias is still declared.
    */
   aliases?: readonly ResolvedGateAlias[];
+  /**
+   * The release this gate binds (#4045, ws-104 question 2): set on a release
+   * gate, the gate `chant components promote --release` passes for an
+   * environment, with `planDigest` the change-set document's digest and
+   * `environment` the environment. Set, a resolution counts only when it was
+   * recorded for this release as well as this plan and environment, and the
+   * pending fact it records carries it. Absent, a resolution recorded for a
+   * release never counts.
+   */
+  releaseDigest?: string;
+  /**
+   * Whether the change set stored under a digest is empty (#4045, ws-104
+   * question 6): read back from `chant/lifecycle` and recomputed, never
+   * taken from the resolution. Given, an `empty: true` resolution for this
+   * gate, environment, release and plan passes the gate when this says its
+   * document is empty; quorum and approval rules don't apply to it. Absent,
+   * no `empty` resolution counts.
+   */
+  verifyEmpty?: (planDigest: string) => Promise<boolean>;
 }
 
 /**
@@ -386,14 +408,18 @@ export type GateCheck =
        * Set on a gate that declares `approval` (#2508). `"quorum"` when enough
        * human approvals were recorded, `"policy"` when an `enforce`-mode permit
        * passed it on its own. `"alias"` (#3949) when an approval recorded
-       * under one of the gate's aliases counted, on any gate.
+       * under one of the gate's aliases counted, on any gate. `"empty"`
+       * (#4045) when a release gate passed over an empty change set, on the
+       * `empty: true` resolution the promote wrote, after the stored
+       * document was read back and found empty.
        */
-      via?: "quorum" | "policy" | "alias";
+      via?: "quorum" | "policy" | "alias" | "empty";
       /** Every approval that counted toward the quorum. Set with `via`. */
       approvals?: GateResolutionRecord[];
       /** The approvals this run carried from an alias and wrote under the gate's name (#3949). Set when `via` is `"alias"`. */
       carried?: GateResolutionRecord[];
     }
+
   | {
       satisfied: false;
       pending: PendingGateRecord;
@@ -593,6 +619,7 @@ export function carriedApproval(r: GateResolutionRecord, op: string, gate: strin
     ...(r.url ? { url: r.url } : {}),
     ...(r.planDigest !== undefined ? { planDigest: r.planDigest } : {}),
     ...(r.environment !== undefined ? { environment: r.environment } : {}),
+    ...(r.releaseDigest !== undefined ? { releaseDigest: r.releaseDigest } : {}),
     ...(r.origin ? { origin: r.origin } : {}),
     ...(r.sameOriginOverride ? { sameOriginOverride: true } : {}),
     approver: approverOf(r),
@@ -650,6 +677,16 @@ async function aliasApprovals(
   return out.sort((a, b) => at(a.timestamp) - at(b.timestamp));
 }
 
+/**
+ * The commit and run a gate record names (#4020): the input's own, else the
+ * checkout's commit and, in CI, the CI run id. Fields nobody knows are left out.
+ */
+async function runStamp(input: { runId?: string; gitSha?: string }): Promise<{ runId?: string; gitSha?: string }> {
+  const runId = input.runId ?? ciRunIdFromEnv();
+  const gitSha = input.gitSha ?? (await resolveCommitSha());
+  return { ...(runId ? { runId } : {}), ...(gitSha ? { gitSha } : {}) };
+}
+
 /** Whether two resolved approval blocks are the same, so a standing pending fact still describes this gate. */
 function sameApproval(a: ResolvedGateApproval | undefined, b: ResolvedGateApproval | undefined): boolean {
   return JSON.stringify(a ?? null, sortedJsonReplacer) === JSON.stringify(b ?? null, sortedJsonReplacer);
@@ -692,20 +729,48 @@ export async function evaluateGate(port: GateLedgerPort, input: GateCheckInput):
   // a mismatch with a message instead of silently not counting.
   const env = input.environment;
   const pending = env === undefined ? ledger.pending : ledger.pending.filter((p) => p.environment === env);
+  // #4045: an approval is for one release. On this gate, a resolution for
+  // another release (or for one, on a gate that binds none) never counts; the
+  // newest one since the standing fact comes back as a mismatch instead.
+  const forOtherRelease = (r: GateResolutionRecord) => r.gate === input.gate && r.releaseDigest !== input.releaseDigest;
   // #3163: a gate the workspace's identity.gates names counts only signed approvals from its class.
   const rule = (await port.approvalRule?.(input.gate)) ?? null;
   const standing = latestPendingGate(pending, input.gate);
   const since = standing?.timestamp ?? EPOCH;
+
+  // #4045: a pass over an empty change set. The promote wrote it, and it
+  // counts only once the document stored under its plan reads back empty.
+  const envResolutions = env === undefined ? ledger.resolutions : ledger.resolutions.filter((r) => r.environment === env);
+  if (input.verifyEmpty && input.planDigest !== undefined) {
+    const passes = envResolutions
+      .filter(
+        (r) =>
+          r.empty === true && r.gate === input.gate && !forOtherRelease(r) && samePlanDigest(r.planDigest, input.planDigest) &&
+          new Date(r.timestamp).getTime() >= new Date(since).getTime() &&
+          (input.spent === undefined || !isApprovalSpent(input.spent, r)),
+      )
+      .sort((a, b) => new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime());
+    const pass = passes[passes.length - 1];
+    if (pass && (await input.verifyEmpty(input.planDigest))) return { satisfied: true, resolution: pass, via: "empty" };
+  }
   // #3949: aliases admit only approvals of this run's plan, and carrying one writes a line.
   const aliases = input.planDigest !== undefined && port.appendResolution ? (input.aliases ?? []) : [];
   const aliased = (from: { op: string; gate: string }) => aliases.some((a) => a.op === from.op && a.gate === from.gate);
   // #3841: an approval of this plan the rule refuses is named, so a wait says why.
   const refused: GateRefusedApproval[] = [];
+  const otherRelease: GateResolutionRecord[] = [];
   const resolutions = (
     env === undefined
       ? ledger.resolutions
       : ledger.resolutions.filter((r) => r.environment === undefined || r.environment === env)
   )
+    // #4045: an `empty` pass is never an approval; it counts only above.
+    .filter((r) => r.empty !== true)
+    .filter((r) => {
+      if (!forOtherRelease(r)) return true;
+      otherRelease.push(r);
+      return false;
+    })
     // #3949: a carried approval counts only while the gate still names its alias.
     .filter((r) => r.gate !== input.gate || r.carriedFrom === undefined || aliased(r.carriedFrom))
     .filter((r) => input.spent === undefined || r.gate !== input.gate || !isApprovalSpent(input.spent, r))
@@ -722,7 +787,10 @@ export async function evaluateGate(port: GateLedgerPort, input: GateCheckInput):
   // #3949: write the approvals that counted from an alias under this gate.
   const carry = async (records: readonly GateResolutionRecord[]): Promise<GateResolutionRecord[]> => {
     const written: GateResolutionRecord[] = [];
-    for (const r of records) written.push((await port.appendResolution!(carriedApproval(r, input.op, input.gate, now))).record);
+    if (records.length === 0) return written;
+    // #4020: a carried approval is for this run's gate, so it names this run's commit and run.
+    const at = await runStamp(input);
+    for (const r of records) written.push((await port.appendResolution!({ ...carriedApproval(r, input.op, input.gate, now), ...at })).record);
     return written;
   };
 
@@ -775,6 +843,16 @@ export async function evaluateGate(port: GateLedgerPort, input: GateCheckInput):
     mismatched = found.mismatched;
   }
 
+  // #4045: an approval of this gate for another release stands as a mismatch
+  // when nothing closer does, so the refusal says an approval exists.
+  if (!mismatched && input.planDigest !== undefined) {
+    const sinceMs = new Date(since).getTime();
+    mismatched = otherRelease
+      .filter((r) => new Date(r.timestamp).getTime() >= sinceMs)
+      .sort((a, b) => new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime())
+      .at(-1);
+  }
+
   // `input.planDigest` is defined whenever `mismatched` is — `latestResolutionForPlan`
   // returns a mismatch only on the plan-bound path.
   const mismatch: GateDigestMismatch | undefined = mismatched
@@ -800,6 +878,7 @@ export async function evaluateGate(port: GateLedgerPort, input: GateCheckInput):
   // that already carries a checkpoint stands: an approval copies that one.
   if (
     standing && !isPendingGateExpired(standing, now) && samePlanDigest(standing.planDigest, input.planDigest) &&
+    standing.releaseDigest === input.releaseDigest &&
     sameApproval(standing.approval, input.approval) &&
     (input.checkpoint === undefined || port.writeCheckpoint === undefined || standing.checkpointDigest !== undefined)
   ) {
@@ -817,6 +896,8 @@ export async function evaluateGate(port: GateLedgerPort, input: GateCheckInput):
   const url = resolveApprovalUrl();
   // #3683: in CI, where this job runs, so an approval can start it again.
   const resume = resolveGateRunLocator();
+  // #4020: the commit and run the gate waits on, so a reader can join it to both.
+  const stamp = await runStamp(input);
   const { record, pushed, pushWarning } = await port.appendPending({
     ...(input.fields as Partial<PendingGateInput> | undefined),
     op: input.op,
@@ -826,12 +907,13 @@ export async function evaluateGate(port: GateLedgerPort, input: GateCheckInput):
       new Date(now).getTime() + parseDuration(input.timeout ?? DEFAULT_GATE_EXPIRY),
     ).toISOString(),
     ...(input.description ? { description: input.description } : {}),
-    ...(input.runId ? { runId: input.runId } : {}),
+    ...stamp,
     ...(url ? { url } : {}),
     ...(resume ? { resume } : {}),
     ...(input.planDigest !== undefined ? { planDigest: input.planDigest } : {}),
     ...(checkpointDigest !== undefined ? { checkpointDigest } : {}),
     ...(env !== undefined ? { environment: env } : {}),
+    ...(input.releaseDigest !== undefined ? { releaseDigest: input.releaseDigest } : {}),
     ...(input.approval ? { approval: input.approval } : {}),
     ...(input.neverOverMcp ? { neverOverMcp: true as const } : {}),
   });