@intentius/chant 0.124.27 → 0.124.29

package/src/workspace/releases.test.ts

@@ -0,0 +1,108 @@
+/**
+ * The `releases` read (#4026, ws-104): releases with their targets, cuts and
+ * the environments that run them, held to `releases.schema.json`.
+ */
+
+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 { contract } from "./__fixtures__/contract-repo";
+import releasesSchema from "./releases.schema.json";
+import { releasesDocument, RELEASES_SCHEMA_ID } from "./releases";
+import { appendCut, makeRelease, persistRelease } from "../lifecycle/release-store";
+import { appendReleaseRecord } from "../lifecycle/release-ledger";
+import { writeLedgerFiles } from "../lifecycle/git";
+
+const { expectValid } = contract(releasesSchema);
+
+function initRepo(dir: string): void {
+  for (const args of [["init", "-q", "-b", "main"], ["config", "user.email", "t@chant.dev"], ["config", "user.name", "T"]]) spawnSync("git", args, { cwd: dir });
+  writeFileSync(join(dir, "README.md"), "x\n");
+  spawnSync("git", ["add", "."], { cwd: dir });
+  spawnSync("git", ["commit", "-q", "-m", "init"], { cwd: dir });
+}
+
+const release = (commit: string) =>
+  makeRelease({
+    member: null,
+    commit,
+    artifactDigests: [{ component: "api", kind: "image", path: "api.tar", digest: `sha256:${"a".repeat(64)}` }],
+    targets: [
+      { env: "staging", templates: [{ component: "api", path: "t.json", digest: `sha256:${"b".repeat(64)}` }], params: [{ name: "tier", value: "small", source: "default" }] },
+      { env: "prod", templates: [{ component: "api", path: "t.json", digest: `sha256:${"c".repeat(64)}` }], params: [{ name: "tier", value: "large", source: "default" }] },
+    ],
+  });
+
+const deploy = (env: string, component: string, releaseDigest?: string, timestamp = "2026-10-16T12:00:00.000Z") =>
+  appendReleaseRecord({ component, env, digest: `sha256:${"a".repeat(64)}`, gitSha: "1".repeat(40), runId: "r", timestamp, actor: "ci", ...(releaseDigest ? { releaseDigest } : {}) }, { cwd: dirOf.current });
+const dirOf = { current: "" };
+
+describe("releasesDocument", () => {
+  test("lists each release with its targets, cuts and the environments whose latest deploy names it", async () => {
+    await withTestDir(async (dir) => {
+      dirOf.current = dir;
+      initRepo(dir);
+      const r1 = release("1".repeat(40));
+      const r2 = release("2".repeat(40));
+      await persistRelease(r1, [], { cwd: dir });
+      await persistRelease(r2, [], { cwd: dir });
+      await appendCut({ releaseDigest: r1.releaseDigest, label: "v1", actor: "alice", timestamp: "2026-10-16T10:00:00.000Z", runOrigin: null }, { cwd: dir });
+      await appendCut({ releaseDigest: r2.releaseDigest, label: "v2", actor: "bob", timestamp: "2026-10-16T11:00:00.000Z", runOrigin: { forge: "github", repo: "o/r" } }, { cwd: dir });
+      await deploy("staging", "api", r2.releaseDigest);
+      await deploy("prod", "api", r1.releaseDigest);
+      await deploy("staging", "web");
+
+      const doc = await releasesDocument({ cwd: dir });
+      expectValid(doc);
+      if ("error" in doc) throw new Error(doc.error.message);
+      expect(doc).toMatchObject({ $schema: RELEASES_SCHEMA_ID, contract: 1, member: null, reason: null });
+      expect(doc.releases.map((r) => [r.label, r.environments])).toEqual([
+        ["v2", [{ env: "staging", components: ["api"] }]],
+        ["v1", [{ env: "prod", components: ["api"] }]],
+      ]);
+      expect(doc.releases[0]).toMatchObject({
+        releaseDigest: r2.releaseDigest,
+        commit: "2".repeat(40),
+        artifactDigests: r2.artifactDigests,
+        targets: r2.targets,
+        cuts: [{ label: "v2", actor: "bob", timestamp: "2026-10-16T11:00:00.000Z", runOrigin: { forge: "github", repo: "o/r" }, signature: null }],
+      });
+    });
+  });
+
+  test("a release file that is not a release and a cut line that is not a cut are left out under ledger-malformed", async () => {
+    await withTestDir(async (dir) => {
+      dirOf.current = dir;
+      initRepo(dir);
+      const r = release("3".repeat(40));
+      await persistRelease(r, [], { cwd: dir });
+      await writeLedgerFiles(
+        [
+          { path: `_releases/jcs1-sha256_${"9".repeat(64)}.json`, content: "{not json" },
+          { path: "_releases/cuts.jsonl", content: `{"version":1}\n` },
+        ],
+        "broken",
+        { cwd: dir },
+      );
+      const doc = await releasesDocument({ cwd: dir });
+      expectValid(doc);
+      if ("error" in doc) throw new Error(doc.error.message);
+      expect(doc.releases.map((x) => x.releaseDigest)).toEqual([r.releaseDigest]);
+      expect(doc.reason).toEqual({ code: "ledger-malformed", message: "1 release file(s) and 1 cut line(s) could not be read and are left out" });
+    });
+  });
+
+  test("an empty ledger lists no releases, and outside git the read fails with not-a-git-repository", async () => {
+    await withTestDir(async (dir) => {
+      const outside = await releasesDocument({ cwd: dir });
+      expectValid(outside);
+      expect(outside).toMatchObject({ error: { code: "not-a-git-repository" } });
+      initRepo(dir);
+      const empty = await releasesDocument({ cwd: dir });
+      expectValid(empty);
+      expect(empty).toMatchObject({ releases: [], reason: null });
+    });
+  });
+});

package/src/workspace/releases.ts

@@ -0,0 +1,133 @@
+/**
+ * The `releases` read (#4026, ws-104): every release of one member with its
+ * targets, its cuts, and the environments that run it.
+ *
+ * `chant release list --json` prints this document. It reads the local
+ * `chant/lifecycle` branch and never fetches. An environment runs a release
+ * for the components whose latest deploy record there names the release in
+ * `releaseDigest`. A promote under a release writes that field; deploys made
+ * any other way do not name a release yet (#4043), so they list nowhere.
+ *
+ * Each release carries `revoked` (#4033, ws-105): the `ci/revoked/<sha>` tag
+ * on its commit, judged as `release cut` judges it, or null. It is read from
+ * local tags at read time; nothing records it. When the tags can't be judged
+ * (a `ci.green.signedSince` naming no commit here) every release reads null,
+ * and `chant workspace check` reports the declaration.
+ *
+ * Each cut carries `signatureCheck` (#4031): whether its signature verifies
+ * for its actor against the signers at base, and, when the declaration names
+ * a `release` gate with a class, whether the actor is in it.
+ *
+ * A release file that is not a release, or whose content does not hash to its
+ * digest, and a cut line that is not a cut, are left out and counted under
+ * `reason` with `ledger-malformed`; the rest are listed. A read that fails
+ * outright is the failure `ledger-unreadable`.
+ */
+
+import { execFileSync } from "node:child_process";
+import { latestPerComponent, listReleaseEnvironments, readReleaseLedger } from "../lifecycle/release-ledger";
+import { readAllReleases, readCuts, type Release, type ReleaseCut } from "../lifecycle/release-store";
+import { resolveMemberLedger } from "../lifecycle/member-ledger";
+import { readerVersion } from "./declaration";
+import { checkReleaseSignature, type GateAdmissionRule, type ReleaseSignatureCheck } from "./identity-gate-rule";
+import { readRevokedCommits, revocationOf, type ReleaseRevocation } from "../lifecycle/release-revocation";
+
+export const RELEASES_CONTRACT_VERSION = 1;
+export const RELEASES_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace/releases/v1/releases.schema.json";
+
+/** Why the read stopped. Closed; each code is in `reason-codes.ts`. */
+export const RELEASES_ERROR_CODES = ["not-a-git-repository", "ledger-unreadable"] as const;
+/** Why some entries were left out. */
+export const RELEASES_REASON_CODES = ["ledger-malformed"] as const;
+
+/** One release as the document lists it. */
+export interface ReleaseEntry extends Omit<Release, "version"> {
+  /** The label its cuts gave it, or null. */
+  label: string | null;
+  /** Its cuts, oldest first, each with whether its signature verifies against the signers at base (#4031). */
+  cuts: Array<Omit<ReleaseCut, "version" | "releaseDigest"> & { signatureCheck: ReleaseSignatureCheck }>;
+  /** The environments that run it, and in each the components whose latest deploy names it. Sorted by env. */
+  environments: Array<{ env: string; components: string[] }>;
+  /** The revoked tag on its commit (#4033), or null when the commit is not revoked. */
+  revoked: ReleaseRevocation | null;
+}
+
+export type ReleasesDocument =
+  | {
+      $schema: string;
+      contract: number;
+      chant: string;
+      /** The member read, its path of names joined with `/`, or null for a project outside a workspace. */
+      member: string | null;
+      /** Newest cut first; a release with no cut comes last. */
+      releases: ReleaseEntry[];
+      reason: { code: (typeof RELEASES_REASON_CODES)[number]; message: string } | null;
+    }
+  | { $schema: string; contract: number; chant: string; error: { code: (typeof RELEASES_ERROR_CODES)[number]; message: string } };
+
+/**
+ * The rule a cut's signature is judged by (#4031): the declaration's
+ * `identity.gates.release` and the signers and role grants, all read at base.
+ */
+export async function releaseRule(cwd: string): Promise<GateAdmissionRule> {
+  const { scopeSource } = await import("./write-scope");
+  const { releaseRuleFrom } = await import("./identity");
+  return releaseRuleFrom(scopeSource(cwd)).rule;
+}
+
+/** Read the releases of the member at `cwd`. */
+export async function releasesDocument(req: { cwd: string }): Promise<ReleasesDocument> {
+  const head = { $schema: RELEASES_SCHEMA_ID, contract: RELEASES_CONTRACT_VERSION, chant: readerVersion() };
+  try {
+    execFileSync("git", ["rev-parse", "--git-dir"], { cwd: req.cwd, stdio: "ignore" });
+  } catch {
+    return { ...head, error: { code: "not-a-git-repository", message: "releases are read from the chant/lifecycle branch, and this directory is not in a git repository" } };
+  }
+  try {
+    const ledger = await resolveMemberLedger(req.cwd);
+    const loc = { cwd: req.cwd };
+    const { releases, malformed: badReleases } = await readAllReleases(loc);
+    const { cuts, malformed: badCuts } = await readCuts(loc);
+
+    const running = new Map<string, Map<string, string[]>>();
+    for (const env of await listReleaseEnvironments(loc)) {
+      const { records } = await readReleaseLedger(env, loc);
+      for (const record of latestPerComponent(records).values()) {
+        const digest = (record as { releaseDigest?: unknown }).releaseDigest;
+        if (typeof digest !== "string") continue;
+        const envs = running.get(digest) ?? new Map<string, string[]>();
+        envs.set(env, [...(envs.get(env) ?? []), record.component].sort());
+        running.set(digest, envs);
+      }
+    }
+
+    const rule = await releaseRule(req.cwd);
+    const revoked = await readRevokedCommits(req.cwd).catch(() => new Map<string, ReleaseRevocation>());
+    const entries: ReleaseEntry[] = releases.map(({ version: _v, ...release }) => {
+      const own = cuts.filter((c) => c.releaseDigest === release.releaseDigest);
+      return {
+        ...release,
+        label: own.find((c) => c.label !== null)?.label ?? null,
+        cuts: own.map(({ version: _cv, releaseDigest: _d, ...cut }) => ({ ...cut, signatureCheck: checkReleaseSignature(rule, { releaseDigest: release.releaseDigest, ...cut }) })),
+        environments: [...(running.get(release.releaseDigest) ?? new Map<string, string[]>())]
+          .map(([env, components]) => ({ env, components }))
+          .sort((a, b) => (a.env < b.env ? -1 : 1)),
+        revoked: revocationOf(release, revoked),
+      };
+    });
+    const latest = (e: ReleaseEntry): string => e.cuts.map((c) => c.timestamp).sort().at(-1) ?? "";
+    entries.sort((a, b) => (latest(b) !== latest(a) ? (latest(b) < latest(a) ? -1 : 1) : a.releaseDigest < b.releaseDigest ? -1 : 1));
+
+    const bad = badReleases + badCuts;
+    return {
+      ...head,
+      member: ledger.members.length > 0 ? ledger.members.join("/") : null,
+      releases: entries,
+      reason: bad > 0
+        ? { code: "ledger-malformed", message: `${badReleases} release file(s) and ${badCuts} cut line(s) could not be read and are left out` }
+        : null,
+    };
+  } catch (err) {
+    return { ...head, error: { code: "ledger-unreadable", message: `reading the releases failed: ${err instanceof Error ? err.message : String(err)}` } };
+  }
+}

package/src/workspace/run-event.schema.json

@@ -0,0 +1,295 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/chant/schemas/workspace/run-event/v1/run-event.schema.json",
+  "title": "chant run event",
+  "description": "One event of a run's stream (#4019, behold #678): one JSON object per line, written by writeRunEvent and createRunEventWriter in src/run-event.ts. It covers Op runs, component runs and pipeline runs alike. Every event names the run, what it ran, the commit it built from and the runtime it ran on, so a reader shows a run the same way wherever it happened. A run's stream opens with run-start and ends with run-settle, whose status is the run's verdict; seq counts the events from 0. Version 1 of the read contract. Readers ignore fields they do not know; a field is only ever added within a version. A status set gains a value only as an addition within a version, which the read contract lists with the chant that first writes it; a reader treats a status it does not know as a settle it cannot classify and reads on. Contract version 1 of this document is written by chant 0.124.28 and newer; the read contract as a whole by chant 0.81.0 and newer.",
+  "oneOf": [
+    { "$ref": "#/$defs/run-start" },
+    { "$ref": "#/$defs/run-settle" },
+    { "$ref": "#/$defs/wave-start" },
+    { "$ref": "#/$defs/wave-settle" },
+    { "$ref": "#/$defs/component-start" },
+    { "$ref": "#/$defs/component-settle" },
+    { "$ref": "#/$defs/phase-start" },
+    { "$ref": "#/$defs/phase-settle" },
+    { "$ref": "#/$defs/step-start" },
+    { "$ref": "#/$defs/step-settle" },
+    { "$ref": "#/$defs/gate-waiting" },
+    { "$ref": "#/$defs/gate-resolved" }
+  ],
+  "$defs": {
+    "envelope": {
+      "type": "object",
+      "description": "What every event carries.",
+      "required": ["$schema", "contract", "chant", "seq", "at", "type", "runId", "kind", "name", "gitSha", "runtime", "runOrigin"],
+      "properties": {
+        "$schema": { "const": "https://intentius.io/chant/schemas/workspace/run-event/v1/run-event.schema.json" },
+        "contract": { "const": 1 },
+        "chant": { "type": "string", "description": "The version of the chant that wrote the event." },
+        "seq": { "type": "integer", "minimum": 0, "description": "The event's place in its run's stream: 0 for run-start, one more for each event after it." },
+        "at": { "type": "string", "description": "When the event happened, ISO-8601." },
+        "type": { "type": "string" },
+        "runId": { "type": "string", "minLength": 1, "description": "The run's own id: an Op run's id, a component run's id (the id its release records carry, the CI run id in CI, else one minted locally), or the CI run id for a pipeline run. runOrigin says where it ran, which for an Op run in CI is the CI run, not the id space of runId." },
+        "kind": { "enum": ["op", "component", "pipeline"], "description": "What ran: an Op, a component selection (chant run --components), or a CI pipeline." },
+        "name": { "type": "string", "description": "The Op's name, the component selection as given, or the pipeline's name." },
+        "gitSha": {
+          "type": ["string", "null"],
+          "pattern": "^[0-9a-f]{40,64}$",
+          "description": "The commit the run built from, the same field a release record carries. Null when the run did not start in a git checkout."
+        },
+        "runtime": {
+          "enum": ["local", "steward", "ci"],
+          "description": "Where the run happened: in the process that started it, on a steward, or in a forge's CI."
+        },
+        "runOrigin": { "$ref": "#/$defs/runOrigin" }
+      }
+    },
+    "runOrigin": {
+      "type": "object",
+      "description": "Where the run ran and how to reach it: RunOrigin from lifecycle/release-ledger.ts, the shape a release record's runOrigin has. For an Op run in CI it locates the CI run, as the Op's run record does (#4020), while runId stays the Op run's own id.",
+      "required": ["forge"],
+      "properties": {
+        "forge": {
+          "enum": ["github", "gitlab", "op", "local"],
+          "description": "github: a GitHub Actions run, also the spelling Forgejo Actions uses. gitlab: a CI pipeline. op: a steward's run, named by its Op run id. local: a run on the machine that started it, outside CI."
+        },
+        "repo": { "type": "string", "description": "The repository or project slug on the forge, when the environment named one." },
+        "url": { "type": "string", "description": "A link to the run, when the environment gave enough to build one." }
+      }
+    },
+    "settleStatus": {
+      "enum": ["ok", "failed", "gated", "waiting"],
+      "description": "How a run, wave, component or phase settled. gated: it stopped at a gate nobody has approved. waiting: it stopped at a decision point nobody has answered. Neither is a failure."
+    },
+    "stepIndex": { "type": "integer", "minimum": 0, "description": "The step's place in its phase as authored, counting from 0, so two steps of one phase that share a name stay apart. Optional, added within contract 1 by chant 0.124.28 (#4041). A writer leaves it out for a step it has no authored place for, and a reader without it pairs a step-start with its step-settle by component, phase and step in stream order." },
+    "component": {
+      "type": ["string", "null"],
+      "description": "The component whose composition the phase or step belongs to in a component run, and null in an Op or pipeline run."
+    },
+    "run-start": {
+      "allOf": [
+        { "$ref": "#/$defs/envelope" },
+        {
+          "type": "object",
+          "description": "The run is about to start.",
+          "required": ["type", "waves"],
+          "properties": {
+            "type": { "const": "run-start" },
+            "waves": {
+              "type": ["array", "null"],
+              "items": { "type": "array", "items": { "type": "string" } },
+              "description": "In a component run, the waves of components the run will attempt, in order; wave numbers in later events count from 1 into this list. Null in an Op or pipeline run."
+            }
+          }
+        }
+      ]
+    },
+    "run-settle": {
+      "allOf": [
+        { "$ref": "#/$defs/envelope" },
+        {
+          "type": "object",
+          "description": "The run settled. The last event of the stream, and its verdict.",
+          "required": ["type", "status", "durationMs"],
+          "properties": {
+            "type": { "const": "run-settle" },
+            "status": { "$ref": "#/$defs/settleStatus" },
+            "durationMs": { "type": ["integer", "null"], "minimum": 0, "description": "From run-start to now, or null when the writer did not time it." },
+            "error": { "type": "string", "description": "With status failed, what failed, when the writer knows." }
+          }
+        }
+      ]
+    },
+    "wave-start": {
+      "allOf": [
+        { "$ref": "#/$defs/envelope" },
+        {
+          "type": "object",
+          "description": "A wave of a component run is about to start. Its components may run at the same time.",
+          "required": ["type", "wave", "components"],
+          "properties": {
+            "type": { "const": "wave-start" },
+            "wave": { "type": "integer", "minimum": 1 },
+            "components": { "type": "array", "items": { "type": "string" } }
+          }
+        }
+      ]
+    },
+    "wave-settle": {
+      "allOf": [
+        { "$ref": "#/$defs/envelope" },
+        {
+          "type": "object",
+          "description": "A wave settled. failed if any component in it failed, which stops the run before the next wave.",
+          "required": ["type", "wave", "status"],
+          "properties": {
+            "type": { "const": "wave-settle" },
+            "wave": { "type": "integer", "minimum": 1 },
+            "status": { "$ref": "#/$defs/settleStatus" }
+          }
+        }
+      ]
+    },
+    "component-start": {
+      "allOf": [
+        { "$ref": "#/$defs/envelope" },
+        {
+          "type": "object",
+          "description": "A component in a wave is about to start its deploy composition.",
+          "required": ["type", "wave", "component"],
+          "properties": {
+            "type": { "const": "component-start" },
+            "wave": { "type": "integer", "minimum": 1 },
+            "component": { "type": "string" }
+          }
+        }
+      ]
+    },
+    "component-settle": {
+      "allOf": [
+        { "$ref": "#/$defs/envelope" },
+        {
+          "type": "object",
+          "description": "A component's composition settled, after any rollback the run did for it. A component the run did not start settles too, with no component-start before it: blocked when a dependency failed or stopped at a gate, already-applied when an earlier attempt the run resumed applied it.",
+          "required": ["type", "wave", "component", "status"],
+          "properties": {
+            "type": { "const": "component-settle" },
+            "wave": { "type": "integer", "minimum": 1 },
+            "component": { "type": "string" },
+            "status": {
+              "enum": ["ok", "failed", "gated", "waiting", "blocked", "already-applied"],
+              "description": "The settle statuses of a run, wave or phase, and two more for a component the run did not start, added within contract version 1 by #4007 and written by chant 0.124.29 and newer. blocked: a dependency failed or stopped at a gate, so it never ran; blockedBy names the dependency. already-applied: an earlier attempt the run resumed applied it, so it did not run again; its wave is the wave it had in that attempt's derivation. A reader that knows only the four settle statuses can read either as a component that did not run in this run."
+            },
+            "blockedBy": {
+              "type": "string",
+              "description": "With blocked: the failed or gated component the run reached this one from. Added within contract version 1 by #4007, written by chant 0.124.29 and newer."
+            }
+          }
+        }
+      ]
+    },
+    "phase-start": {
+      "allOf": [
+        { "$ref": "#/$defs/envelope" },
+        {
+          "type": "object",
+          "description": "A phase is about to run its steps: an Op's phase, a component composition's phase, or a pipeline's stage.",
+          "required": ["type", "component", "phase"],
+          "properties": {
+            "type": { "const": "phase-start" },
+            "component": { "$ref": "#/$defs/component" },
+            "phase": { "type": "string" }
+          }
+        }
+      ]
+    },
+    "phase-settle": {
+      "allOf": [
+        { "$ref": "#/$defs/envelope" },
+        {
+          "type": "object",
+          "description": "A phase settled: ok when every step in it settled ok, skipped or cached.",
+          "required": ["type", "component", "phase", "status"],
+          "properties": {
+            "type": { "const": "phase-settle" },
+            "component": { "$ref": "#/$defs/component" },
+            "phase": { "type": "string" },
+            "status": { "$ref": "#/$defs/settleStatus" }
+          }
+        }
+      ]
+    },
+    "step-start": {
+      "allOf": [
+        { "$ref": "#/$defs/envelope" },
+        {
+          "type": "object",
+          "description": "A step is about to run: an Op or composition step, or a pipeline's job. A step that never started, such as one an earlier failure stopped, has a step-settle and no step-start.",
+          "required": ["type", "component", "phase", "step"],
+          "properties": {
+            "type": { "const": "step-start" },
+            "component": { "$ref": "#/$defs/component" },
+            "phase": { "type": "string" },
+            "step": { "type": "string", "description": "The step's activity, gate:<name> for a gate, effect:<name> for an effect, or the job's name." },
+            "index": { "$ref": "#/$defs/stepIndex" }
+          }
+        }
+      ]
+    },
+    "step-settle": {
+      "allOf": [
+        { "$ref": "#/$defs/envelope" },
+        {
+          "type": "object",
+          "description": "A step settled.",
+          "required": ["type", "component", "phase", "step", "status", "durationMs"],
+          "properties": {
+            "type": { "const": "step-settle" },
+            "component": { "$ref": "#/$defs/component" },
+            "phase": { "type": "string" },
+            "step": { "type": "string" },
+            "index": { "$ref": "#/$defs/stepIndex" },
+            "status": {
+              "enum": ["ok", "failed", "skipped", "cached", "gated", "waiting"],
+              "description": "ok: it ran and succeeded. failed: it ran and failed. skipped: it did not run, and skip says why. cached: a cache hit stood in for running it (#4015). gated: it stopped the run at a gate nobody has approved. waiting: it stopped the run at a decision point nobody has answered."
+            },
+            "skip": {
+              "enum": ["receipt", "resumed", "refused", "not-run", null],
+              "description": "With status skipped. receipt: the effect's receipt matched, so it had already applied. resumed: the run resumed at a later gate and carried this step's output from an earlier run. refused: it declined to go on, and message says why. not-run: an earlier step failed or stopped the run. Null when the writer does not know."
+            },
+            "durationMs": { "type": ["integer", "null"], "minimum": 0, "description": "How long it ran, or null when the writer did not time it." },
+            "error": { "type": "string", "description": "With status failed, what failed." },
+            "message": { "type": "string", "description": "Why a step skipped, gated or waited, for a person." }
+          }
+        }
+      ]
+    },
+    "gate-waiting": {
+      "allOf": [
+        { "$ref": "#/$defs/envelope" },
+        {
+          "type": "object",
+          "description": "The run stopped and waits on a person: a gate nobody has approved, or a decision point nobody has answered. The step settles gated or waiting next.",
+          "required": ["type", "component", "phase", "step", "op", "gate", "point"],
+          "properties": {
+            "type": { "const": "gate-waiting" },
+            "component": { "$ref": "#/$defs/component" },
+            "phase": { "type": "string" },
+            "step": { "type": "string" },
+            "index": { "$ref": "#/$defs/stepIndex" },
+            "op": { "type": "string", "description": "The op the gate is recorded under, which chant approve takes. It differs from name when a step's command stopped at a gate of its own." },
+            "gate": { "type": ["string", "null"], "description": "The gate's name, or null when the step waits on a decision point alone." },
+            "point": { "type": ["string", "null"], "description": "The answer record id of the open question, which points answer takes, or null." },
+            "message": { "type": "string", "description": "Why the gate did not pass, such as an approval for a different plan." }
+          }
+        }
+      ]
+    },
+    "gate-resolved": {
+      "allOf": [
+        { "$ref": "#/$defs/envelope" },
+        {
+          "type": "object",
+          "description": "A gate the run reached was approved, so its step goes on.",
+          "required": ["type", "component", "phase", "step", "op", "gate", "resolvedBy", "resolvedAt", "via"],
+          "properties": {
+            "type": { "const": "gate-resolved" },
+            "component": { "$ref": "#/$defs/component" },
+            "phase": { "type": "string" },
+            "step": { "type": "string" },
+            "index": { "$ref": "#/$defs/stepIndex" },
+            "op": { "type": "string" },
+            "gate": { "type": "string" },
+            "resolvedBy": { "type": "string", "description": "Who approved it." },
+            "resolvedAt": { "type": "string", "description": "When the approval was recorded, ISO-8601." },
+            "via": {
+              "enum": ["quorum", "policy", "point", "alias", "empty", null],
+              "description": "How the approval passed when it was more than one person's approval of this gate: a quorum, a policy permit, a decision point's answer, or an approval recorded under one of the gate's aliases. empty (added within contract 1 by #4045, chant 0.124.28 and newer): a release gate passed over an empty change set with no approval, on the resolution the promote wrote, whose resolvedBy is the actor running it."
+            },
+            "url": { "type": "string", "description": "Where the approval was made, when known." }
+          }
+        }
+      ]
+    }
+  }
+}

package/src/workspace/status-contract.test.ts

@@ -113,7 +113,7 @@ function fixture(build: () => string): () => string {
 
 let n = 0;
 /** One ledger line. */
-function release(component: string, env: string, digest: string, gitSha: string, extra: Record<string, string> = {}): string {
+function release(component: string, env: string, digest: string, gitSha: string, extra: Record<string, unknown> = {}): string {
   n++;
   return JSON.stringify({
     version: 1,
@@ -452,6 +452,61 @@ const gated = fixture(() => {
   return root;
 });
 
+describe("commit, run and gate on the records status --json lists (#4020)", () => {
+  test("a release names the gate that admitted it, a gate its commit and run, and an older record gives null", async () => {
+    const root = twoLayouts();
+    const sha = "a".repeat(40);
+    const admission = { op: "web", gate: "deploy", resolvedAt: "2026-09-20T01:00:00.000Z" };
+    lifecycle(root, {
+      "_members/web/staging/releases.jsonl": jsonl(release("web", "staging", D("a"), sha, { approver: "alice", admission })),
+      "_members/web/_gates/web.jsonl": jsonl(
+        pending("web", "deploy", "2026-09-20T00:00:00.000Z", { environment: "staging", planDigest: D("1"), gitSha: sha, runId: "9001" }),
+        approval("web", "deploy", "alice", "2026-09-20T01:00:00.000Z", { environment: "staging", planDigest: D("1"), gitSha: sha, runId: "9001" }),
+        pending("web", "old", "2026-09-20T00:00:00.000Z", { environment: "staging", planDigest: D("2") }),
+      ),
+      "staging/releases.jsonl": jsonl(release("api", "staging", D("b"), "b".repeat(40))),
+    });
+    const doc = result(await workspaceStatus({ cwd: root, env: "staging", now: NOW }));
+    expectValid(doc);
+    const [, web, api] = doc.members;
+    expect(web.environments[0].releases[0]).toMatchObject({ gitSha: sha, approver: "alice", admission });
+    expect(api.environments[0].releases[0]).toMatchObject({ approver: null, admission: null });
+    const [deploy, old] = web.gates;
+    expect(deploy).toMatchObject({ name: "deploy", gitSha: sha, runId: "9001" });
+    expect(old).not.toHaveProperty("gitSha");
+    expect(old).not.toHaveProperty("runId");
+  });
+});
+
+describe("the release a deploy was made from, on the records status --json lists (#4043)", () => {
+  test("a release item carries the releaseDigest and the label it was cut with, and null when there is none", async () => {
+    const root = twoLayouts();
+    const rd = `jcs1-sha256:${"e".repeat(64)}`;
+    const cut = JSON.stringify({ version: 1, releaseDigest: rd, label: "v1.2.0", actor: "alice", timestamp: "2026-09-19T00:00:00.000Z", runOrigin: null, signature: null });
+    lifecycle(root, {
+      "_members/web/staging/releases.jsonl": jsonl(release("web", "staging", D("a"), "a".repeat(40), { releaseDigest: rd })),
+      "_members/web/_releases/cuts.jsonl": `${cut}\n`,
+      "staging/releases.jsonl": jsonl(release("api", "staging", D("b"), "b".repeat(40))),
+    });
+    const doc = result(await workspaceStatus({ cwd: root, env: "staging", now: NOW }));
+    expectValid(doc);
+    const [, web, api] = doc.members;
+    expect(web.environments[0].releases[0]).toMatchObject({ releaseDigest: rd, releaseLabel: "v1.2.0" });
+    expect(api.environments[0].releases[0]).toMatchObject({ releaseDigest: null, releaseLabel: null });
+  });
+
+  test("a release with no cut line keeps its digest and has no label", async () => {
+    const root = twoLayouts();
+    const rd = `jcs1-sha256:${"e".repeat(64)}`;
+    lifecycle(root, {
+      "_members/web/staging/releases.jsonl": jsonl(release("web", "staging", D("a"), "a".repeat(40), { releaseDigest: rd })),
+    });
+    const doc = result(await workspaceStatus({ cwd: root, env: "staging", now: NOW }));
+    expectValid(doc);
+    expect(doc.members[1].environments[0].releases[0]).toMatchObject({ releaseDigest: rd, releaseLabel: null });
+  });
+});
+
 describe("gate state in chant workspace status --json (#2674)", () => {
   test("each member lists its gates with state, approvals, quorum and the approve line", async () => {
     const doc = result(await workspaceStatus({ cwd: gated(), env: "staging", compareTo: "prod", now: NOW }));
@@ -766,4 +821,29 @@ describe("stewards in chant workspace status --json (#2731)", () => {
     expect(doc.members[0].stewards.map((s) => s.name)).toEqual(["box-steward"]);
     expect(doc.members[0].stewardReasons.map((r) => r.code)).toEqual(["stewards-unreadable"]);
   });
+
+  test("a member lists its promotion order from the environments array (#4030)", async () => {
+    const root = stewarded();
+    writeFileSync(
+      join(root, "box", "chant.config.ts"),
+      'export default { environments: ["dev", { name: "staging", canary: true }, "prod", "pr-*"] };\n',
+    );
+    const doc = result(await workspaceStatus({ cwd: root, env: "minimal" }));
+    expectValid(doc);
+    expect(doc.members[0].promotionOrder).toEqual([
+      { name: "dev", canary: false },
+      { name: "staging", canary: true },
+      { name: "prod", canary: false },
+    ]);
+    // A member with no chant.config.ts declares none.
+    expect(doc.members[1].promotionOrder).toEqual([]);
+  });
+
+  test("a promotion order the config can't give is null (#4030)", async () => {
+    const root = stewarded();
+    writeFileSync(join(root, "box", "chant.config.ts"), "throw new Error(\"broken\");\n");
+    const doc = result(await workspaceStatus({ cwd: root, env: "minimal" }));
+    expectValid(doc);
+    expect(doc.members[0].promotionOrder).toBeNull();
+  });
 });