@intentius/chant 0.124.27 → 0.124.29

package/src/workspace/flags.test.ts

@@ -0,0 +1,141 @@
+/**
+ * Feature flags as workspace records (#4024): the flag kind's records on
+ * read, the stale-flag check WSP118, the flags of a member by parameter, and
+ * `status --json`'s `featureFlags`, on the fixture in
+ * `__fixtures__/flag-workspace.ts`.
+ */
+
+import { join } from "node:path";
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { cleanScratch, contract } from "./__fixtures__/contract-repo";
+import { flagWorkspace, flagRecord } from "./__fixtures__/flag-workspace";
+import { runDeclarationChecks } from "./checks";
+import { memberFlagBindings, readWorkspaceFlags } from "./flags-read";
+import { loadRecordKind } from "./records";
+import { queryRecords } from "./records-cli";
+import recordsSchema from "./records.schema.json";
+import { workspaceStatus } from "./status";
+import statusSchema from "./status.schema.json";
+
+let root: string;
+beforeAll(() => {
+  root = flagWorkspace();
+});
+afterAll(cleanScratch);
+
+const KIND = "flags/flag.kind.mjs";
+
+describe("the flag kind (#4024)", () => {
+  test("the canonical kind chant ships loads, with its flag block and schema", async () => {
+    const loaded = await loadRecordKind(join(import.meta.dirname, "reference-kinds", "flag", "flag.kind.mjs"));
+    expect(loaded.kind.name).toBe("flag");
+    expect(loaded.kind.flag).toEqual({ member: "member", param: "param", owner: "owner", values: "values", work: { field: "work", kind: "../work/work.kind.mjs" } });
+    expect(loaded.schema.$id).toBe("urn:intentius:chant:flag:1");
+  });
+
+  test("a kind with a flag block and no idField is refused", async () => {
+    const dir = flagWorkspace({
+      [KIND]: `export const recordKind = { name: "flag", location: { dir: ".", match: "^x$" }, format: "json", schema: { id: "urn:intentius:chant:flag:1", path: "flag.schema.json" }, idFrom: "sha256", flag: { member: "m", param: "p", owner: "o", values: "v", work: { field: "w", kind: "../work/work.kind.mjs" } } };\n`,
+    });
+    await expect(loadRecordKind(join(dir, KIND))).rejects.toThrow(/a flag kind names its id with idField/);
+  });
+
+  test("records gives each flag its work item, the decisions it implements, and whether it is stale", async () => {
+    const doc = await queryRecords({ kind: join(root, KIND), cwd: root, workGaps: false });
+    contract(recordsSchema).expectValid(doc);
+    if ("error" in doc || !("records" in doc)) throw new Error(JSON.stringify(doc));
+    const byId = new Map(doc.records.map((r) => [r.id, r]));
+    expect(byId.get("old-banner")).toMatchObject({
+      valid: true,
+      flag: { work: { id: "W-001", state: "done" }, implements: [{ id: "d-001", state: "confirmed", confirmed: true }], stale: true },
+    });
+    expect(byId.get("old-banner")!.warnings.map((w) => w.code)).toEqual(["flag-stale"]);
+    expect(byId.get("new-checkout")).toMatchObject({
+      valid: true,
+      flag: { work: { id: "W-002", state: "in-progress" }, implements: [{ id: "d-002", state: "decided", confirmed: false }], stale: false },
+    });
+    expect(byId.get("new-checkout")!.warnings).toEqual([]);
+  });
+
+  test("a flag that names no known work item is warned flag-work-unknown and is never stale", async () => {
+    const dir = flagWorkspace({ "flags/ghost.flag.md": flagRecord("ghost", { work: "W-404", member: "shop", param: "ghost", values: {} }) });
+    const doc = await queryRecords({ kind: join(dir, KIND), cwd: dir, workGaps: false });
+    if ("error" in doc || !("records" in doc)) throw new Error(JSON.stringify(doc));
+    const ghost = doc.records.find((r) => r.id === "ghost")!;
+    expect(ghost.flag).toEqual({ work: { id: "W-404", state: null }, implements: [], stale: false });
+    expect(ghost.warnings.map((w) => w.code)).toEqual(["flag-work-unknown"]);
+  });
+
+  test("a superseded decision is not confirmed, so its flag is not stale", async () => {
+    const dir = flagWorkspace({
+      "decisions/d-001-the-banner.md": `---\nid: "d-001"\nstate: "confirmed"\nsupersedes: []\n---\n`,
+      "decisions/d-003-a-new-banner.md": `---\nid: "d-003"\nstate: "confirmed"\nsupersedes: ["d-001"]\n---\n`,
+    });
+    const { flags } = await readWorkspaceFlags(dir);
+    expect(flags.find((f) => f.id === "old-banner")).toMatchObject({ implements: [{ id: "d-001", confirmed: false }], stale: false });
+  });
+});
+
+describe("WSP118, the stale-flag check (#4024)", () => {
+  test("reports the flag whose work item's decisions are all confirmed, on its record, as a warning", async () => {
+    const result = await runDeclarationChecks(root);
+    const found = result.diagnostics.filter((d) => d.ruleId === "WSP118");
+    expect(found).toHaveLength(1);
+    expect(found[0]).toMatchObject({ severity: "warning", code: "flag-stale", file: "flags/old-banner.flag.md" });
+    expect(found[0].message).toMatch(/^flag old-banner is due for removal: its work item W-001 implements d-001 \(confirmed\)/);
+  });
+
+  test("reports nothing once the stale flag is removed", async () => {
+    const dir = flagWorkspace({ "flags/old-banner.flag.md": null });
+    const result = await runDeclarationChecks(dir);
+    expect(result.diagnostics.filter((d) => d.ruleId === "WSP118")).toEqual([]);
+  });
+});
+
+describe("a member's flags by parameter", () => {
+  test("names the flag and its value in the environment, and none where the record gives none", async () => {
+    expect(await memberFlagBindings(root, join(root, "shop"), "prod")).toEqual({
+      member: "shop",
+      byParam: { newCheckout: { flag: "new-checkout", value: false } },
+      errors: [],
+    });
+    expect((await memberFlagBindings(root, join(root, "shop"), "staging"))!.byParam).toEqual({ newCheckout: { flag: "new-checkout", value: undefined } });
+  });
+
+  test("is null for a directory no member holds", async () => {
+    expect(await memberFlagBindings(root, join(root, "flags"), "prod")).toBeNull();
+  });
+
+  test("two flags for one parameter, and an invalid flag record naming the member, are errors", async () => {
+    const dir = flagWorkspace({
+      "flags/twin.flag.md": flagRecord("twin", { work: "W-002", member: "shop", param: "newCheckout", values: { prod: true } }),
+      "flags/broken.flag.md": `---\nschema: 1\nid: "broken"\nmember: "shop"\n---\n`,
+    });
+    const bindings = await memberFlagBindings(dir, join(dir, "shop"), "prod");
+    expect(bindings!.errors.join("\n")).toMatch(/flags new-checkout and twin both set build parameter "newCheckout" of member shop/);
+    expect(bindings!.errors.join("\n")).toMatch(/flag record flags\/broken\.flag\.md is not valid/);
+  });
+});
+
+describe("status --json lists featureFlags per member (#4024)", () => {
+  test("each flag with its values per environment, its work item and whether it is stale", async () => {
+    const doc = await workspaceStatus({ cwd: root, env: "prod", readLedger: async () => ({ records: [], malformed: 0 }), readPromotionOrder: async () => [] });
+    contract(statusSchema).expectValid(doc);
+    if ("error" in doc) throw new Error(JSON.stringify(doc));
+    const shop = doc.members.find((m) => m.name === "shop")!;
+    expect(shop.featureFlags).toEqual([
+      {
+        id: "new-checkout",
+        param: "newCheckout",
+        owner: "alice",
+        values: { dev: true, prod: false },
+        work: { id: "W-002", state: "in-progress" },
+        implements: [{ id: "d-002", state: "decided", confirmed: false }],
+        stale: false,
+        kind: "flags/flag.kind.mjs",
+        path: "flags/new-checkout.flag.md",
+      },
+    ]);
+    expect(doc.members.find((m) => m.name === "blog")!.featureFlags!.map((f) => [f.id, f.stale])).toEqual([["old-banner", true]]);
+  });
+});

package/src/workspace/flags.ts

@@ -0,0 +1,157 @@
+/**
+ * Feature flags as workspace records (#4024, decided in #4016).
+ *
+ * A flag is a record of a kind with a `flag` block (`records.ts`). It names a
+ * member, one of that member's declared build-time parameters, an owner, the
+ * work item the flag hides and a value per environment. The member's build
+ * reads it as that parameter (`../flag-params.ts`), so turning a flag on in
+ * an environment is a commit that changes the record, and the release cut
+ * from that commit carries the new value as a `params` entry whose `source`
+ * is `flag:<id>` (ws-104).
+ *
+ * This module and `./flags-read.ts` do three things:
+ *
+ * - {@link applyFlags}: on a `records` read of a flag kind, gives each record
+ *   its work item with that item's state, the decisions the item implements,
+ *   and whether the flag is due for removal, with the warnings
+ *   `flag-work-unknown` and `flag-stale`.
+ * - `readWorkspaceFlags` (`./flags-read.ts`): every flag of every flag kind
+ *   the declaration names, for `workspace status` (`featureFlags`) and the
+ *   build.
+ * - `memberFlagBindings` (`./flags-read.ts`): the flags of the member holding
+ *   a directory, by parameter, for one environment.
+ *
+ * The readers live apart so that `records.ts`, which loads this module for a
+ * flag kind, never reaches `records-cli.ts` and what it imports.
+ *
+ * A flag is due for removal when its work item implements at least one
+ * decision and every decision it implements is confirmed: in one of its
+ * kind's closed states and superseded by nothing. For chant's decision kind
+ * that is `ratified` (a superseded decision has a superseder). The work is
+ * then settled, and the flag that hid it is dead weight.
+ */
+
+import { dirname } from "node:path";
+import type { ReasonCode } from "./reason-codes";
+import { loadRecordKind, readRecords, RecordReadError, type LoadedRecordKind, type ReadRecordsOptions, type RecordEntry } from "./records";
+import type { WorkLink } from "./work";
+
+/** Why a flag record carries a warning. Closed, like the record warning codes. */
+export const FLAG_WARNING_CODES = [
+  /** The flag names a work item no record of its kind's work kind has. */
+  "flag-work-unknown",
+  /** Every decision the flag's work item implements is confirmed, so the flag is due for removal. `check` reports it (WSP118). */
+  "flag-stale",
+] as const satisfies readonly ReasonCode[];
+export type FlagWarningCode = (typeof FLAG_WARNING_CODES)[number];
+
+/** A flag's value in one environment: what a build-time parameter can hold. */
+export type FlagValue = string | number | boolean;
+
+/** A decision a flag's work item implements, with whether it is confirmed. */
+export interface FlagDecision extends WorkLink {
+  /** In one of its kind's closed states and superseded by nothing. */
+  confirmed: boolean;
+}
+
+/** What a read of a flag kind adds to each record (#4024). */
+export interface FlagState {
+  /** The work item the flag hides, with its state, or null when the record names none. The state is null when no record has the id. */
+  work: WorkLink | null;
+  /** Each decision the work item implements, with its state. Empty when the item is unknown or implements none. */
+  implements: FlagDecision[];
+  /** True when the work item implements at least one decision and every one is confirmed: the flag is due for removal. */
+  stale: boolean;
+}
+
+/** A flag as `workspace status` and the build read it. */
+export interface WorkspaceFlag {
+  /** The flag's name, its record's id. */
+  id: string;
+  /** The kind file from the workspace root. */
+  kind: string;
+  /** The record file from the workspace root, with / separators. */
+  path: string;
+  member: string;
+  param: string;
+  owner: string;
+  /** The value per environment, as the record writes it, in key order. */
+  values: Record<string, FlagValue>;
+  work: WorkLink | null;
+  implements: FlagDecision[];
+  stale: boolean;
+}
+
+/** A flag record that is not valid, so no build trusts it. */
+export interface InvalidFlag {
+  kind: string;
+  path: string;
+  /** The member the record names, or null when it names none that can be read. */
+  member: string | null;
+  message: string;
+}
+
+/** Every flag a workspace's declared flag kinds hold. */
+export interface WorkspaceFlags {
+  flags: WorkspaceFlag[];
+  invalid: InvalidFlag[];
+}
+
+const str = (v: unknown): string | null => (typeof v === "string" && v !== "" ? v : null);
+
+/**
+ * Whether a decision is confirmed: in one of its kind's `closed` states and
+ * superseded by nothing. An unknown decision is not. The overlap report
+ * (#4025) shares it: a work item is in flight while any decision it
+ * implements is not confirmed.
+ */
+export function decisionConfirmed(decision: { state: string | null; supersededBy: string | null } | undefined, closed: ReadonlySet<string>): boolean {
+  return decision !== undefined && decision.state !== null && closed.has(decision.state) && decision.supersededBy === null;
+}
+
+/**
+ * Give each record of a flag kind its {@link FlagState} and warnings, in
+ * place. Throws a `RecordReadError` when the work kind it names can't be read
+ * or is not a work kind.
+ */
+export async function applyFlags(loaded: LoadedRecordKind, entries: RecordEntry[], options: ReadRecordsOptions): Promise<void> {
+  const flag = loaded.kind.flag!;
+  const workKind = await loadRecordKind(flag.work.kind, dirname(loaded.file));
+  if (!workKind.kind.work) {
+    throw new RecordReadError("kind-invalid", `flag kind ${loaded.kind.name} names ${flag.work.kind} as its work kind, and that kind has no work block`);
+  }
+  const decisionKind = await loadRecordKind(workKind.kind.work.decisions, dirname(workKind.file));
+  const read = await readRecords(workKind, { root: options.root, source: options.source });
+  const items = new Map<string, RecordEntry>();
+  for (const r of read.records) if (r.id !== null && !items.has(r.id)) items.set(r.id, r);
+  const decisions = new Map((read.decisions ?? []).map((d) => [d.id, d]));
+  const closed = new Set(decisionKind.kind.closedStates ?? []);
+
+  for (const e of entries) {
+    if (e.data === null) continue;
+    const named = str(e.data[flag.work.field]);
+    if (named === null) {
+      e.flag = { work: null, implements: [], stale: false };
+      continue;
+    }
+    const item = items.get(named);
+    if (!item) {
+      e.flag = { work: { id: named, state: null }, implements: [], stale: false };
+      e.warnings.push({ code: "flag-work-unknown", message: `hides the work item ${named}, which no record in ${flag.work.kind} has` });
+      continue;
+    }
+    const implementsList: FlagDecision[] = (item.implements ?? []).map((d) => {
+      const decision = decisions.get(d.id);
+      return { ...d, confirmed: decisionConfirmed(decision, closed) };
+    });
+    const stale = implementsList.length > 0 && implementsList.every((d) => d.confirmed);
+    e.flag = { work: { id: named, state: item.state }, implements: implementsList, stale };
+    if (stale) {
+      e.warnings.push({
+        code: "flag-stale",
+        message: `is due for removal: its work item ${named} implements ${implementsList.map((d) => `${d.id} (${d.state})`).join(", ")}, and every one is confirmed`,
+      });
+    }
+  }
+}
+

package/src/workspace/graph-cli.ts

@@ -60,7 +60,7 @@ export type GraphErrorCode = (typeof GRAPH_ERROR_CODES)[number];
 const LIVE_AT_REVISION = "--live reads the account as it stands now, and --at reads the source at a revision; chant workspace graph takes one of them";
 
 const USAGE =
-  "chant workspace graph [dir] [--at <rev>] [--member <name>] [--kind <kind file>] [-o <file>] [--env <env>] [--live [--overlay] [--traffic <level>]] [--no-cache] [--dry-run] | chant workspace graph --composites [--at <rev>] [--member <name>] [-o <file>] | chant workspace graph --intent <path[:start-end]|path#symbol> [--at <rev>] [--kind <kind file>...] [--follow-squash] [--json]";
+  "chant workspace graph [dir] [--at <rev>] [--member <name>] [--kind <kind file>] [-o <file>] [--env <env>] [--live [--overlay] [--traffic <level>]] [--no-cache] [--dry-run] | chant workspace graph --composites [--at <rev>] [--member <name>] [-o <file>] | chant workspace graph --intent <path[:start-end]|path#symbol|member/node|sha> [--at <rev>] [--kind <kind file>...] [--follow-squash] [--json]";
 
 interface Head {
   $schema: string;

package/src/workspace/identity-gate-rule.ts

@@ -14,7 +14,7 @@
  * else: no zod, no ajv, no package loading, so it bundles small.
  */
 
-import { GATE_SEAL_NAMESPACE, gateSealPayload, namespaceAllowed, verifySshSignatureWith, type SealedGateApproval } from "./trust/gate-seal";
+import { GATE_SEAL_NAMESPACE, gateSealPayload, namespaceAllowed, sshKeyFingerprint, sshSignatureKey, verifySshSignatureWith, type SealedGateApproval } from "./trust/gate-seal";
 import type { Signer } from "./trust/trust-files";
 
 /** The core classes, in the order a principal's roles are tried; `human` holds no role and is the rest. */
@@ -78,17 +78,101 @@ export function grantedClasses(classes: readonly ClassGrant[], roles: Readonly<R
  */
 export function admitApprover(rule: GateAdmissionRule, a: SealedGateApproval): string | null {
   const { gate, signers } = rule;
-  const want = rule.class;
-  if (want !== null && !rule.classes.some((c) => c.name === want)) {
-    return `identity.gates.${gate} names the class ${want}, which ${rule.unknownClass ?? "no pinned package supplies"}, so no approval can show it is in that class (known classes: ${rule.classes.map((c) => c.name).join(", ")})`;
-  }
+  const unknown = unknownClassRefusal(rule, "approval");
+  if (unknown !== null) return unknown;
   if (!signers.active) return `gate ${gate} needs a signed approval, and there is no signers file (${signers.signersPath}) at base to check one against`;
   const seal = sealRefusal(gate, signers, a);
   if (seal !== null) return seal;
+  return classRefusal(rule, a.resolvedBy);
+}
+
+/** Why no signature can show a principal is in the rule's class: the class is one the rule does not know. Null otherwise. */
+function unknownClassRefusal(rule: GateAdmissionRule, what: string): string | null {
+  const want = rule.class;
+  if (want === null || rule.classes.some((c) => c.name === want)) return null;
+  return `identity.gates.${rule.gate} names the class ${want}, which ${rule.unknownClass ?? "no pinned package supplies"}, so no ${what} can show it is in that class (known classes: ${rule.classes.map((c) => c.name).join(", ")})`;
+}
+
+/** Why `principal` is not in the rule's class, or null when it is or the rule names none. */
+function classRefusal(rule: GateAdmissionRule, principal: string): string | null {
+  const want = rule.class;
   if (want === null) return null;
-  const granted = grantedClasses(rule.classes, rule.roles, a.resolvedBy);
+  const granted = grantedClasses(rule.classes, rule.roles, principal);
   const inClass = want === "human" ? granted.length === 0 : granted.includes(want);
-  return inClass ? null : `${a.resolvedBy} is not in the class ${want} that gate ${gate} needs: no role grant at base puts them there`;
+  return inClass ? null : `${principal} is not in the class ${want} that gate ${rule.gate} needs: no role grant at base puts them there`;
+}
+
+// ── release cuts (#4031) ─────────────────────────────────────────────────
+
+/** The gate whose `identity.gates` entry says who may cut a release (#4031). */
+export const RELEASE_GATE = "release";
+
+/** The ssh signature namespace of a release cut's signature (#4031), so no other signature can stand in for one. */
+export const RELEASE_SEAL_NAMESPACE = "chant-release";
+
+/** A cut line's fields its signature covers (#4031), and the signature. */
+export interface SignedReleaseCut {
+  releaseDigest: string;
+  label: string | null;
+  actor: string;
+  timestamp: string;
+  /** The armored ssh signature, or null for an unsigned cut. */
+  signature: string | null;
+}
+
+/**
+ * The bytes a release cut's signature signs (#4031): the release digest,
+ * the label (empty for none), the actor who cut it and the cut's time,
+ * joined by LF with no final newline.
+ */
+export function releaseSealPayload(cut: Omit<SignedReleaseCut, "signature">): Buffer {
+  return Buffer.from(`${cut.releaseDigest}\n${cut.label ?? ""}\n${cut.actor}\n${cut.timestamp}`, "utf-8");
+}
+
+/** Why the cut's signature does not verify for its actor against the signers at base, or null when it does. */
+function releaseSignatureRefusal(signers: GateAdmissionRule["signers"], cut: SignedReleaseCut): string | null {
+  if (cut.signature === null) return `the cut by ${cut.actor} is not signed`;
+  if (!signers.active) return `there is no signers file (${signers.signersPath}) at base to check the cut's signature against`;
+  const where = `${signers.signersPath} at base`;
+  const listed = signers.signers.filter((s) => normalise(s.principal) === normalise(cut.actor));
+  if (listed.length === 0) return `${cut.actor} has no key in ${where}, so the cut's signature can't count`;
+  const keys = listed.filter((s) => namespaceAllowed(s.namespaces, RELEASE_SEAL_NAMESPACE)).map((s) => Buffer.from(s.key.split(" ")[1] ?? "", "base64"));
+  const r = verifySshSignatureWith(cut.signature, releaseSealPayload(cut), RELEASE_SEAL_NAMESPACE, keys);
+  return r.ok ? null : `the cut's signature does not verify for ${cut.actor} against ${where}: ${r.reason}`;
+}
+
+/**
+ * Why `cut` may not be made under the `release` gate's rule, or null when
+ * it may (#4031): its signature verifies for its actor against the signers
+ * at base and, when the gate names a class, the role grants at base put the
+ * actor in it. The same rule {@link admitApprover} applies to an approval,
+ * over the cut's own signed bytes.
+ */
+export function admitReleaseCut(rule: GateAdmissionRule, cut: SignedReleaseCut): string | null {
+  const unknown = unknownClassRefusal(rule, "cut");
+  if (unknown !== null) return unknown;
+  const seal = releaseSignatureRefusal(rule.signers, cut);
+  if (seal !== null) return `${seal}; identity.gates.${rule.gate} needs a release cut signed with chant release cut --sign`;
+  return classRefusal(rule, cut.actor);
+}
+
+/** Whether a cut's signature verifies, as `release list` and `workspace status` report it (#4031). */
+export interface ReleaseSignatureCheck {
+  /** `verified`: it verifies for the actor, who is in the release gate's class when it names one. `unsigned`: the cut has none. `unverified`: it does not, and `reason` says why. */
+  status: "verified" | "unsigned" | "unverified";
+  /** The fingerprint of the key in the signature, or null for an unsigned cut or one that can't be read. */
+  key: string | null;
+  reason: string;
+}
+
+/** Judge a stored cut's signature against `rule`, read at base. A rule with no class checks the signature alone. */
+export function checkReleaseSignature(rule: GateAdmissionRule, cut: SignedReleaseCut): ReleaseSignatureCheck {
+  if (cut.signature === null) return { status: "unsigned", key: null, reason: "the cut carries no signature" };
+  const blob = sshSignatureKey(cut.signature);
+  const key = blob ? sshKeyFingerprint(blob) : null;
+  const why = unknownClassRefusal(rule, "cut") ?? releaseSignatureRefusal(rule.signers, cut) ?? classRefusal(rule, cut.actor);
+  if (why !== null) return { status: "unverified", key, reason: why };
+  return { status: "verified", key, reason: `signed by ${cut.actor}${rule.class !== null ? `, in the class ${rule.class}` : ""}` };
 }
 
 /** The seal step, worded as `checkGateSeal` (`./trust/seal.ts`) words it against an active signers file at base. */

package/src/workspace/identity.ts

@@ -26,7 +26,7 @@
  */
 
 import type { Declaration, SignedGate } from "./declaration";
-import { admitApprover } from "./identity-gate-rule";
+import { admitApprover, RELEASE_GATE, type GateAdmissionRule } from "./identity-gate-rule";
 import { classesOf, coreClassRegistry, roleGrants, type ClassRegistry } from "./principal-classes";
 import type { ReasonCode } from "./reason-codes";
 import { normalisePrincipal } from "./records";
@@ -165,6 +165,19 @@ export function gateAdmissionFrom(source: GateRuleSource, gate: string): GateAdm
   return { requirement, refuses: (a) => admitApprover(rule, a) };
 }
 
+/**
+ * The rule a release cut is judged by (#4031): the declaration's
+ * `identity.gates.release` entry with its class, read at base, or, when the
+ * declaration names no `release` gate, a rule with no class, which checks a
+ * cut's signature alone. `requirement` is null in that case, and a cut may
+ * then be made unsigned.
+ */
+export function releaseRuleFrom(source: GateRuleSource): { requirement: SignedGate | null; rule: GateAdmissionRule } {
+  const requirement = source.declaration?.identity?.gates[RELEASE_GATE] ?? null;
+  const { policy, classes } = source;
+  return { requirement, rule: { gate: RELEASE_GATE, class: requirement?.class ?? null, signers: policy, roles: roleGrants(policy), classes: classes.all() } };
+}
+
 /**
  * The rule for `gate` in the workspace holding `cwd`, read at base (the
  * target branch tip), or null when there is no declaration or it names none.

package/src/workspace/intent-cli.ts

@@ -1,5 +1,5 @@
 /**
- * `chant workspace graph --intent <path[:start-end]|path#symbol> [--at <rev>] [--kind <kind file>...] [--follow-squash] [--json]`
+ * `chant workspace graph --intent <path[:start-end]|path#symbol|member/node|sha> [--at <rev>] [--kind <kind file>...] [--follow-squash] [--json]`
  * (#2651, #3034): the intent graph over one region (`intent.ts`), printed as JSON
  * with `--json` or as a walk, one line per node, in the order of #2650
  * section B: the region, its decisions, their artifacts, the commits, and the
@@ -7,16 +7,19 @@
  * the decisions governing it, most relevant first. Under each decision come the commits made inside its window, and
  * when any of them is not the decision's own work, the question #2650 B puts
  * to the person about it (#2656). Without `--kind`, the walk reads every
- * record kind the declaration names (#2680).
+ * record kind the declaration names (#2680). Last comes the why chain (#4023):
+ * each commit's work item, ci tag and release, and each release's gates and
+ * deploys.
  */
 
 import { resolve } from "node:path";
 import { formatError } from "../cli/format";
 import type { CommandContext } from "../cli/registry";
 import { intentRecord, type IntentRecordDocument } from "./intent-record";
+import type { IntentTrace, TraceGate } from "./intent-trace";
 import { intentGraph, type ArtifactNode, type CommitNode, type DecisionNode, type IntentDocument, type IntentEdge, type IntentNode, type RunNode, type WhyAnswer, type WorkNode } from "./intent";
 
-const USAGE = "chant workspace graph --intent <path[:start-end]|path#symbol> [--at <rev>] [--kind <kind file>...] [--follow-squash] [--json]";
+const USAGE = "chant workspace graph --intent <path[:start-end]|path#symbol|member/node|sha> [--at <rev>] [--kind <kind file>...] [--follow-squash] [--json]";
 const RECORD_USAGE = "chant workspace graph --intent --record <id> [--at <rev>] [--kind <kind file>...] [--follow-squash] [--json]";
 
 type Result = Exclude<IntentDocument, { error: unknown }>;
@@ -162,6 +165,42 @@ export function whyLines(doc: Result, why: WhyAnswer): string[] {
   return out;
 }
 
+const gateLabel = (g: TraceGate) =>
+  `${g.op}/${g.gate}${g.environment ? ` ${g.environment}` : ""}: ${g.empty ? "passed over an empty change set" : `${g.resolvedBy}${g.relayedBy ? ` relayed by ${g.relayedBy}` : ""}`}${g.channel ? ` on ${g.channel}` : ""} at ${g.at}${g.planDigest ? `, plan ${g.planDigest.slice(0, 24)}${g.changeSet ? " (change set stored)" : ""}` : ""}${g.sealed ? ", sealed" : ""}`;
+
+/**
+ * The why chain (#4023), in its order: for each commit that names a work item
+ * or was tagged, released or deployed, a line; then each release with its
+ * cuts, gates and deploys, and the deploys of no release.
+ */
+export function traceLines(trace: IntentTrace): string[] {
+  const out: string[] = [];
+  const label = (digest: string) => trace.releases.find((r) => r.releaseDigest === digest)?.label ?? digest.slice(0, 24);
+  for (const c of trace.commits) {
+    const parts: string[] = [];
+    if (c.work && c.work.state !== "unlinked") parts.push(c.work.state === "linked" ? `work ${c.work.items.map((w) => `${w.id} (${w.source.field})`).join(", ") || "by a lease not checked"}` : `work ${c.work.state}`);
+    if (c.windowMatches.length > 0) parts.push(`in the window of ${c.windowMatches.map((w) => w.id).join(", ")}`);
+    if (c.tag.state !== "none") parts.push(c.tag.state);
+    for (const r of c.releases) parts.push(`${r.link === "cut-from" ? "released as" : "shipped in"} ${label(r.release)}`);
+    for (const d of c.deploys) parts.push(`${d.env} since ${trace.deploys.find((x) => x.id === d.deploy)?.timestamp ?? "?"}`);
+    if (parts.length > 0) out.push(`trace     ${short(c.sha)} ${parts.join("; ")}`);
+  }
+  for (const r of trace.releases) {
+    const cut = r.cuts[0];
+    out.push(`release   ${r.label ?? r.releaseDigest.slice(0, 24)} from ${short(r.commit)}, ${r.tag.state}${cut ? `; cut by ${cut.actor} at ${cut.timestamp}${cut.signed ? ", signed" : ""}` : ""}`);
+    for (const g of r.gates) out.push(`  gate      ${gateLabel(g)}`);
+    for (const id of r.deploys) {
+      const d = trace.deploys.find((x) => x.id === id);
+      if (d) out.push(`  deploy    ${d.env} ${d.component} at ${d.timestamp} by ${d.actor}${d.admittedBy ? `, admitted by ${d.admittedBy.op}/${d.admittedBy.gate} (${d.admittedBy.resolvedBy})` : ""}`);
+    }
+  }
+  for (const d of trace.deploys.filter((x) => x.release === null)) {
+    out.push(`deploy    ${d.env} ${d.component} at ${d.timestamp} by ${d.actor} from ${short(d.gitSha)}, no release${d.admittedBy ? `; admitted by ${gateLabel(d.admittedBy)}` : ""}${d.plan ? `; plan ${d.plan.document.digest.slice(0, 24)}` : ""}`);
+  }
+  for (const x of trace.reasons) out.push(`reason    ${x.code}: ${x.message}`);
+  return out;
+}
+
 /** The walk as text, one line each, in the order of #2650 section B. */
 export function formatIntent(doc: Result): string {
   const out: string[] = [];
@@ -170,7 +209,8 @@ export function formatIntent(doc: Result): string {
     const lines = region.lines ? `:${region.lines.start}${region.lines.end === region.lines.start ? "" : `-${region.lines.end}`}` : "";
     const where = doc.at ? `at ${short(doc.at)}` : "in the working tree";
     const symbol = region.symbol ? `#${region.symbol.name} (${region.symbol.kind} ${region.symbol.qualified}, lines ${region.lines ? span(region.lines) : "none"})` : lines;
-    out.push(`region    ${region.path}${symbol} (${region.type}, member ${region.member ?? "none"}${region.generated ? ", generated" : ""}) ${where}${region.node ? `, from node ${region.node}` : ""}`);
+    if (region.commit) out.push(`region    commit ${short(region.commit)} (member ${region.member ?? "none"}) ${doc.at ? `at ${short(doc.at)}` : "in the working tree"}`);
+    else out.push(`region    ${region.path}${symbol} (${region.type}, member ${region.member ?? "none"}${region.generated ? ", generated" : ""}) ${where}${region.node ? `, from node ${region.node}` : ""}`);
   }
   const files = ofKind(doc, "file");
   if (files.length > 0) out.push(`files     ${files.length} under the region, ${files.filter((f) => f.generated).length} generated`);
@@ -188,6 +228,7 @@ export function formatIntent(doc: Result): string {
   }
   for (const r of doc.reasons) out.push(`reason    ${r.code}: ${r.message}`);
   if (doc.why) out.push(...whyLines(doc, doc.why));
+  if (doc.trace) out.push(...traceLines(doc.trace));
   const kinds = doc.kinds.length === 0 ? "; no --kind, so no decisions were read" : "";
   const work = ofKind(doc, "work").length;
   out.push(`${doc.summary.commits} commits, ${doc.summary.decisions} decisions, ${work > 0 ? `${work} work ${work === 1 ? "item" : "items"}, ` : ""}${doc.summary.artifacts} artifacts, ${doc.summary.findings} findings${kinds}`);
@@ -243,7 +284,7 @@ export async function runWorkspaceIntent(ctx: CommandContext, cwd: string): Prom
     return runRecord(ctx, cwd, args.kinds ?? (args.kind !== undefined ? [args.kind] : undefined));
   }
   if (!args.intent) {
-    console.error(formatError({ message: "--intent needs a region: a path, path:line, path:start-end or path#symbol", hint: USAGE }));
+    console.error(formatError({ message: "--intent needs a region: a path, path:line, path:start-end, path#symbol, a graph node id or a commit sha", hint: USAGE }));
     return 1;
   }
   // No --kind: undefined, so the walk reads the kinds the declaration names (#2680).