@intentius/chant 0.124.26 → 0.124.28

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/discover-root.test.ts

@@ -170,3 +170,42 @@ describe("discoverOps: an Op may be exported by name (#2171)", () => {
     expect(errors[0]).toContain(`Duplicate Op name "twice" declared twice in`);
   });
 });
+
+/**
+ * #3976. Reading the project's `exclude`/`include` evaluates its config,
+ * which registers tsx, so discovery reads them only when an Op file could be
+ * found. An `exclude` that is not a list is an error whenever the config is
+ * read, which is how these tests tell whether it was.
+ */
+describe("discoverOps reads the config's globs only when there is an Op file (#3976)", () => {
+  let checkout: string;
+  beforeEach(() => {
+    checkout = realpathSync(mkdtempSync(join(tmpdir(), "chant-op-globs-")));
+    fakeGitRoot = checkout;
+    mkdirSync(join(checkout, "src"), { recursive: true });
+    writeFileSync(join(checkout, "src", "infra.ts"), "export const x = 1;\n");
+  });
+  afterEach(() => rmSync(checkout, { recursive: true, force: true }));
+
+  test("a project with no Op file has its config left unread", async () => {
+    writeFileSync(join(checkout, "chant.config.json"), JSON.stringify({ lexicons: ["aws"], exclude: 42 }));
+    const { ops, errors } = await discoverOps({ cwd: checkout });
+    expect(errors).toEqual([]);
+    expect([...ops.keys()]).toEqual([]);
+  });
+
+  test("with an Op file the config is read", async () => {
+    writeFileSync(join(checkout, "chant.config.json"), JSON.stringify({ lexicons: ["aws"], exclude: 42 }));
+    writeFileSync(join(checkout, "src", "run.op.ts"), OP_FILE("run"));
+    await expect(discoverOps({ cwd: checkout })).rejects.toThrow(/exclude/);
+  });
+
+  test("an Op file only `include` re-admits is still found", async () => {
+    writeFileSync(join(checkout, "chant.config.json"), JSON.stringify({ lexicons: ["aws"], include: [".ops"] }));
+    mkdirSync(join(checkout, ".ops"));
+    writeFileSync(join(checkout, ".ops", "hidden.op.ts"), OP_FILE("hidden"));
+    const { ops, errors } = await discoverOps({ cwd: checkout });
+    expect(errors).toEqual([]);
+    expect([...ops.keys()]).toEqual(["hidden"]);
+  });
+});

package/src/op/discover.ts

@@ -57,22 +57,29 @@ async function findDiscoveryRoot(cwd?: string): Promise<string> {
   return gitRoot;
 }
 
+const isOpFile = (name: string, full: string): boolean =>
+  name.endsWith(".op.ts") && !name.endsWith(".test.ts") && !name.endsWith(".spec.ts") && !hasDiscoveryMarkerSync(full);
+
 /**
  * Every `*.op.ts` file below the Op root, through the one discovery walk
  * (`../discovery/walk.ts`, #2527). The walk down stops at child projects
  * whatever the root is, so a configless layout whose Op root is the git root
  * no longer collects its sibling projects' Ops. The project's
  * `exclude`/`include` globs and the skip marker apply.
+ *
+ * The globs come from evaluating the project config, which registers tsx
+ * (#3976), so they are resolved only when an Op file could be found. A walk
+ * that includes `**` first reaches every path any `include` could re-admit,
+ * and stops at the first Op file. When it finds none, no globs could find
+ * one either.
  */
 async function collectOpFiles(root: string): Promise<string[]> {
-  return walkDiscovery({
-    walker: "ops",
-    root,
-    globs: await resolveDiscoveryGlobs(root),
-    excludeDirs: await workspaceMemberDirs(root),
-    accept: (name, full) =>
-      name.endsWith(".op.ts") && !name.endsWith(".test.ts") && !name.endsWith(".spec.ts") && !hasDiscoveryMarkerSync(full),
-  });
+  const excludeDirs = await workspaceMemberDirs(root);
+  // A limit of 0 ends the walk at the first file it accepts.
+  const any = { max: 0, truncated: false };
+  walkDiscovery({ walker: "ops", root, globs: { root, exclude: [], include: ["**"] }, excludeDirs, limit: any, accept: isOpFile });
+  if (!any.truncated) return [];
+  return walkDiscovery({ walker: "ops", root, globs: await resolveDiscoveryGlobs(root), excludeDirs, accept: isOpFile });
 }
 
 /** The `OpConfig` behind an exported value, or `undefined` when the value is not an Op. An Op entity carries its config on `.props` (`./resource.ts`); `name` and `phases` are what every consumer of a discovered Op reads. */

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