@intentius/chant 0.124.27 → 0.124.28

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

@@ -0,0 +1,288 @@
+{
+  "$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. The status sets are closed. 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.",
+          "required": ["type", "wave", "component", "status"],
+          "properties": {
+            "type": { "const": "component-settle" },
+            "wave": { "type": "integer", "minimum": 1 },
+            "component": { "type": "string" },
+            "status": { "$ref": "#/$defs/settleStatus" }
+          }
+        }
+      ]
+    },
+    "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,32 @@ 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("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 +792,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();
+  });
 });

package/src/workspace/status-gates.ts

@@ -25,6 +25,13 @@ import type { GateResolutionRecord, PendingGateRecord } from "../lifecycle/gate-
 import { isPendingGateExpired, latestPendingGate, latestResolutionForPlan, parseGateLedger } from "../lifecycle/gate-ledger";
 import { humanQuorumSince, tallyGateApprovals, type GateApprovalRule } from "../op/gate";
 import type { ReasonCode } from "./reason-codes";
+import { CHANGE_SETS_DIR, changeSetFile } from "../lifecycle/change-set-store";
+
+/** The stored change-set directory beside a gate ledger directory: `<prefix>_change-sets`. */
+function changeSetDirFor(gatesDir: string): string {
+  const at = gatesDir.lastIndexOf("/");
+  return at < 0 ? CHANGE_SETS_DIR : `${gatesDir.slice(0, at)}/${CHANGE_SETS_DIR}`;
+}
 
 /** Why a member's gates can't be listed. Closed: a new code is a contract change. */
 export const GATE_REASON_CODES = [
@@ -58,9 +65,27 @@ export interface StatusGate {
   env: string | null;
   /** The plan the run reached the gate with, or null for a gate that binds no plan. */
   planDigest: string | null;
+  /**
+   * The release the gate binds (#4045), from the pending fact: on a release
+   * gate, the one `chant components promote --release` passes, recorded
+   * under the op `release`. Absent on every other gate and on a fact written
+   * before chant 0.124.28.
+   */
+  releaseDigest?: string;
   state: GateState;
   /** When the run recorded the pending fact the state is read against. */
   recordedAt: string;
+  /** The commit the run reached the gate at (#4020), from the pending fact. Absent on a fact written before chant 0.124.28. */
+  gitSha?: string;
+  /** The run that reached the gate (#4020), from the pending fact: an Op run id, or the CI run id. Absent when the run had none. */
+  runId?: string;
+  /**
+   * The change set the gate binds (#4022): `planDigest`, when a change-set
+   * document is stored under it in the member's `_change-sets/`, read with
+   * `chant change-set show <digest>`. Absent when none is stored, as for a
+   * component gate, which binds a lifecycle-plan digest.
+   */
+  changeSet?: string;
   expiresAt: string;
   /** The approvals that count toward the gate for this plan, oldest first. */
   approvals: StatusGateApproval[];
@@ -113,6 +138,21 @@ function git(cwd: string, args: string[]): string {
   return execFileSync("git", args, { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: 64 * 1024 * 1024 });
 }
 
+/**
+ * Lists the file names in a stored change-set directory on the branch at
+ * `commit`, or an empty set when it doesn't exist or can't be read: a gate
+ * then shows no link, and its state is read the same.
+ */
+export type ChangeSetLister = (dir: string, commit: string, cwd: string) => Promise<Set<string>>;
+
+export const defaultChangeSetLister: ChangeSetLister = async (dir, commit, cwd) => {
+  try {
+    return new Set(git(cwd, ["ls-tree", "--name-only", `${commit}:${dir}`]).split("\n").filter(Boolean));
+  } catch {
+    return new Set();
+  }
+};
+
 export const defaultGateLedgerReader: GateLedgerReader = async (dir, commit, cwd) => {
   try {
     git(cwd, ["rev-parse", "--verify", "--quiet", `${commit}:${dir}`]);
@@ -143,7 +183,10 @@ const approvalOf = (r: GateResolutionRecord): StatusGateApproval => ({ principal
 function decide(component: string, standing: PendingGateRecord, facts: PendingGateRecord[], all: GateResolutionRecord[], now: string, rule: GateApprovalRule | null): StatusGate {
   const gate = standing.gate;
   // #3163: under identity.gates, an unsigned approval, or one from outside the class, doesn't count, as a run reads it.
-  const resolutions = rule === null ? all : all.filter((r) => r.gate !== gate || rule.refuses(r) === null);
+  // #4045: nor does an approval for another release, and an `empty` pass is never an approval.
+  const resolutions = all
+    .filter((r) => r.gate !== gate || (r.empty !== true && r.releaseDigest === standing.releaseDigest))
+    .filter((r) => rule === null || r.gate !== gate || rule.refuses(r) === null);
   const env = standing.environment ?? null;
   const since = standing.timestamp;
   const planDigest = standing.planDigest;
@@ -177,8 +220,11 @@ function decide(component: string, standing: PendingGateRecord, facts: PendingGa
     name: gate,
     env,
     planDigest: planDigest ?? null,
+    ...(standing.releaseDigest !== undefined ? { releaseDigest: standing.releaseDigest } : {}),
     state,
     recordedAt: standing.timestamp,
+    ...(standing.gitSha ? { gitSha: standing.gitSha } : {}),
+    ...(standing.runId ? { runId: standing.runId } : {}),
     expiresAt: standing.expiresAt,
     approvals: approvals.map(approvalOf),
     needed,
@@ -226,6 +272,7 @@ export async function readMemberGates(
   now: string,
   read: GateLedgerReader = defaultGateLedgerReader,
   rules: GateRuleLookup = () => null,
+  listChangeSets: ChangeSetLister = defaultChangeSetLister,
 ): Promise<{ gates: StatusGate[]; ledger: StatusGateLedger }> {
   const ledger: StatusGateLedger = { layout, path: dir, shared: false, malformed: 0, reason: null };
   if (commit === null) {
@@ -247,5 +294,13 @@ export async function readMemberGates(
     gates.push(...read.gates);
     ledger.malformed += read.malformed;
   }
+  // #4022: link each gate to the change set stored under its plan digest,
+  // in the same member's `_change-sets/` beside `_gates/`.
+  if (gates.some((g) => g.planDigest !== null)) {
+    const stored = await listChangeSets(changeSetDirFor(dir), commit, cwd);
+    for (const g of gates) {
+      if (g.planDigest !== null && stored.has(changeSetFile(g.planDigest))) g.changeSet = g.planDigest;
+    }
+  }
   return { gates, ledger };
 }

package/src/workspace/status-stewards.ts

@@ -78,6 +78,10 @@ export interface StatusStewardRun {
   status: OpRunRecord["status"];
   started: string;
   ended: string;
+  /** The commit the run built from (#4020). Absent on a record written before chant 0.124.28. */
+  gitSha?: string;
+  /** The CI run the Op ran in (#4020), when it ran in CI: the shape a release's `runOrigin` has. */
+  runOrigin?: OpRunRecord["runOrigin"];
   /**
    * The gate the run stopped at, for a `gated` run: its name, when the run
    * stopped there, the op it is recorded under (the Op's own, or the
@@ -411,6 +415,8 @@ export async function readMemberStewards(
             status: newest.status,
             started: newest.started,
             ended: newest.ended,
+            ...(newest.gitSha ? { gitSha: newest.gitSha } : {}),
+            ...(newest.runOrigin ? { runOrigin: newest.runOrigin } : {}),
             gate: newest.gate ? gateOf(newest.gate, op.name) : null,
             point: point?.wait ?? null,
             phases: newest.phases.map((p) => ({

package/src/workspace/status.schema.json

@@ -228,6 +228,44 @@
               "message": { "type": "string" }
             }
           }
+        },
+        "promotionOrder": {
+          "description": "The member's promotion order (#4030): the literal entries of the environments array in its chant.config.ts, in order, with a pattern entry such as pr-* left out. A release moves from each step to the next, and components promote --to defaults --from to the step before. Empty when the config declares no environments, and null when it could not be read. canary is declared and shown only; no chant command acts on it yet. Optional: written from chant 0.124.28, absent from older output.",
+          "type": ["array", "null"],
+          "items": {
+            "type": "object",
+            "required": ["name", "canary"],
+            "properties": {
+              "name": { "type": "string" },
+              "canary": { "type": "boolean", "description": "True when the entry sets canary: true." }
+            }
+          }
+        },
+        "releaseCuts": {
+          "description": "The member's release cuts (#4026, ws-104), oldest first, from _releases/cuts.jsonl on the local chant/lifecycle, each with whether its signature verifies (#4031). Empty when none is cut, null when the cuts could not be read. Optional: written from chant 0.124.28, absent from older output.",
+          "type": ["array", "null"],
+          "items": {
+            "type": "object",
+            "required": ["releaseDigest", "label", "commit", "actor", "timestamp", "signature", "signatureCheck"],
+            "properties": {
+              "releaseDigest": { "type": "string", "pattern": "^(jcs1-)?sha256:[0-9a-f]{64}$" },
+              "label": { "type": ["string", "null"] },
+              "commit": { "type": ["string", "null"], "description": "The release's commit, or null when its release file can't be read." },
+              "actor": { "type": "string", "description": "Who cut it." },
+              "timestamp": { "type": "string", "description": "ISO 8601." },
+              "signature": { "type": ["string", "null"], "description": "The cut's armored ssh signature in the chant-release namespace over the release digest, the label (empty for none), the actor and the timestamp, joined by LF. Null for an unsigned cut." },
+              "signatureCheck": {
+                "type": "object",
+                "description": "Whether signature verifies for actor against the signers file at base and, when the declaration at base names a release gate in identity.gates with a class, whether .chant/trust.json at base puts actor in it. Judged on every read.",
+                "required": ["status", "key", "reason"],
+                "properties": {
+                  "status": { "enum": ["verified", "unsigned", "unverified"] },
+                  "key": { "type": ["string", "null"], "description": "The fingerprint of the key in the signature. Reported, never trusted." },
+                  "reason": { "type": "string" }
+                }
+              }
+            }
+          }
         }
       }
     },
@@ -313,6 +351,17 @@
                       "status": { "enum": ["ok", "fail", "gated", "waiting"], "description": "waiting: an activity asked a decision point that is still open (#2749), and the run stopped there." },
                       "started": { "type": "string" },
                       "ended": { "type": "string" },
+                      "gitSha": { "type": "string", "description": "Added in contract 1 by #4020, written by chant 0.124.28 and newer. The commit the run built from. Absent on a record written by an older chant, and when the run knew no commit." },
+                      "runOrigin": {
+                        "type": "object",
+                        "required": ["forge"],
+                        "description": "Added in contract 1 by #4020, written by chant 0.124.28 and newer. The CI run the Op ran in, the shape a release's runOrigin has: the forge (github for GitHub and Forgejo, gitlab), the repo or project, and a link to the run. Absent outside CI.",
+                        "properties": {
+                          "forge": { "enum": ["github", "gitlab", "op", "local"] },
+                          "repo": { "type": "string" },
+                          "url": { "type": "string" }
+                        }
+                      },
                       "gate": {
                         "oneOf": [
                           { "type": "null" },
@@ -828,6 +877,10 @@
           "description": "Read from the newest pending fact for the gate in env, as a run reads it. approved: the approvals recorded since it, for its plan, pass the gate (its quorum, or a policy permit in enforce mode). expired: not approved, and the pending fact is past expiresAt, so the next run records a fresh one. superseded: not approved, and an approval recorded since it names a different plan, so it doesn't count. pending: none of these."
         },
         "recordedAt": { "type": "string", "description": "When the run recorded the pending fact." },
+        "gitSha": { "type": "string", "description": "Added in contract 1 by #4020, written by chant 0.124.28 and newer. The commit the run reached the gate at, from the pending fact. Absent on a fact recorded by an older chant, and when the run knew no commit. It joins the gate to a release's gitSha and to a run's." },
+        "runId": { "type": "string", "description": "Added in contract 1 by #4020, written by chant 0.124.28 and newer. The run that reached the gate: an Op run id, or the CI run id for a component gate that ran in CI. Absent when the run had none." },
+        "changeSet": { "type": "string", "pattern": "^(?:jcs1-)?sha256:[0-9a-f]{64}$", "description": "Added in contract 1 by #4022, written by chant 0.124.28 and newer. The change set the gate binds: planDigest, when a change-set document is stored under it in the member's _change-sets/ on chant/lifecycle, as a pull-request gate's apply and a release gate (#4045) store it. chant change-set show <changeSet> --json prints it, each entry with its graph node. Absent when none is stored, as for a component gate, which binds a lifecycle-plan digest." },
+        "releaseDigest": { "type": "string", "pattern": "^(?:jcs1-)?sha256:[0-9a-f]{64}$", "description": "Added in contract 1 by #4045, written by chant 0.124.28 and newer. The release the gate binds, from the pending fact: set on a release gate, the gate chant components promote --release passes for an environment, whose component is the op release. An approval counts toward it only when it was recorded for this release, environment and planDigest. Absent on every other gate." },
         "expiresAt": { "type": "string" },
         "approvals": {
           "description": "The approvals that count toward the gate for its plan, oldest first.",
@@ -912,12 +965,28 @@
       "required": ["component", "digest", "gitSha", "inputDigest", "runId", "timestamp", "actor", "flags", "plan"],
       "properties": {
         "component": { "type": "string" },
-        "digest": { "type": "string", "description": "The artifact digest the release deployed." },
+        "digest": { "type": "string", "description": "What the deploy record names, as its producer writes it: an artifact digest, a release-plan digest for a runner that records plans (_plans/<digest>.json, ws-055), or a product's own digest such as a schema digest (ws-104 question 3)." },
         "gitSha": { "type": "string", "description": "The commit the artifact was built from." },
         "inputDigest": { "type": ["string", "null"], "description": "The input-side digest when digest is a rendered one. Compare joins on it when present." },
         "runId": { "type": "string" },
         "timestamp": { "type": "string" },
         "actor": { "type": "string" },
+        "approver": { "type": ["string", "null"], "description": "Added in contract 1 by #4020, written by chant 0.124.28 and newer; the ledger has carried it since #1035. Who approved the change at its gate, or null for an ungated release." },
+        "admission": {
+          "description": "Added in contract 1 by #4020, written by chant 0.124.28 and newer. The gate resolution that admitted the release, or null for an ungated release and for one recorded by an older chant. With approver it names the line in the gate ledger.",
+          "oneOf": [
+            { "type": "null" },
+            {
+              "type": "object",
+              "required": ["op", "gate", "resolvedAt"],
+              "properties": {
+                "op": { "type": "string", "description": "The op, or for a component gate the component, whose gate ledger (_gates/<op>.jsonl) holds the resolution." },
+                "gate": { "type": "string", "description": "The gate's name." },
+                "resolvedAt": { "type": "string", "description": "When the resolution was recorded. The newest one, when several approvals counted." }
+              }
+            }
+          ]
+        },
         "flags": { "type": "array", "items": { "enum": ["legacy-digest"] } },
         "plan": {
           "type": ["object", "null"],