@intentius/chant 0.124.28 → 0.124.30

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/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).

package/src/workspace/intent-trace.test.ts

@@ -0,0 +1,173 @@
+/**
+ * The why chain of `graph --intent` (#4023), over a workspace in a throwaway
+ * git repository whose `chant/lifecycle` ledgers are written through the
+ * library, so the test needs no deploy. The end-to-end chain, with a real
+ * cut, a gated `components promote --release` and an approval, is in
+ * cli/handlers/intent-trace.e2e.test.ts.
+ *
+ * - c1 adds the workspace, the work kind, W-001 (constrains app/server.mjs)
+ *   and the server.
+ * - c2 changes the server with `Chant-Record: work:W-001`: linked, green, and
+ *   release v1 is cut from it and deployed to prod through the release gate.
+ * - c3 changes the server with no trailer: unlinked, in W-001's window, and
+ *   revoked. A plain deploy of it reaches dev through a component gate, with
+ *   a release plan in `_plans/`.
+ * - c4 changes the README: green, release v2 is cut from it, so v2 contains
+ *   c2 and c3. Its staging deploy names no releaseDigest and joins v2
+ *   through its release gate admission.
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { appendGateResolution } from "../lifecycle/gate-ledger";
+import { persistReleasePlan } from "../lifecycle/plan-ledger";
+import { appendReleaseRecord } from "../lifecycle/release-ledger";
+import { appendCut, makeRelease, persistRelease, type Release } from "../lifecycle/release-store";
+import { cleanScratch, contract, git, REPO, repo, writeFiles } from "./__fixtures__/contract-repo";
+import { intentGraph, type IntentDocument } from "./intent";
+import intentSchema from "./intent.schema.json";
+import { traceLines } from "./intent-cli";
+
+const REF = join(REPO, "reference-workspace");
+const KIND_FILES = {
+  "work/work.kind.mjs": readFileSync(join(REF, "work", "work.kind.mjs"), "utf-8"),
+  "work/work.schema.json": readFileSync(join(REF, "work", "work.schema.json"), "utf-8"),
+  "decisions/decision.kind.mjs": readFileSync(join(REF, "decisions", "decision.kind.mjs"), "utf-8"),
+  "decisions/decision.schema.json": readFileSync(join(REF, "decisions", "decision.schema.json"), "utf-8"),
+};
+const W001 = `---\n${JSON.stringify({ schema: 1, id: "W-001", title: "Serve on 8081", state: "open", implements: [], needs: [], constrains: ["path:app/server.mjs"], evidence: [], opened_on: "2026-10-16", supersedes: [] }, null, 2)}\n---\n\n# W-001\n`;
+const DECLARATION = JSON.stringify({ name: "shop", schema: 1, members: [{ name: "app", dir: "app", kind: "other", because: "a plain Node server" }] });
+const PLAN = `jcs1-sha256:${"b".repeat(64)}`;
+const DEV_PLAN = `sha256:${"0123456789abcdef".repeat(4)}`;
+
+let root: string;
+let app: string;
+const sha: Record<string, string> = {};
+let v1: Release;
+let v2: Release;
+
+function commit(name: string, message: string): void {
+  git(root, "add", "-A");
+  git(root, "commit", "-q", "-m", message);
+  sha[name] = git(root, "rev-parse", "HEAD");
+}
+
+const subject = (commitSha: string) => ({ member: "app", commit: commitSha, artifactDigests: [{ component: "api", kind: "image" as const, path: "api.tar", digest: `sha256:${commitSha.slice(0, 8).padEnd(64, "0")}` }], targets: [{ env: "prod", templates: [], params: [] }] });
+
+beforeAll(async () => {
+  root = repo({ "chant.workspace.json": DECLARATION, "app/server.mjs": "export const port = 8080;\n", "README.md": "shop\n", "work/W-001-port.md": W001, ...KIND_FILES });
+  app = join(root, "app");
+  commit("c1", "the shop and W-001");
+  writeFiles(root, { "app/server.mjs": "export const port = 8081;\n" });
+  commit("c2", "serve on 8081\n\nChant-Record: work:W-001");
+  writeFiles(root, { "app/server.mjs": "export const port = 8081;\nexport const host = '0.0.0.0';\n" });
+  commit("c3", "listen on every interface");
+  writeFiles(root, { "README.md": "shop, on 8081\n" });
+  commit("c4", "say the port");
+  git(root, "tag", `ci/green/${sha.c2}`, sha.c2);
+  git(root, "tag", `ci/revoked/${sha.c3}`, sha.c3);
+  git(root, "tag", `ci/green/${sha.c4}`, sha.c4);
+
+  const loc = { cwd: app };
+  v1 = makeRelease(subject(sha.c2));
+  v2 = makeRelease(subject(sha.c4));
+  for (const [r, label, at] of [[v1, "v1", "2026-10-16T10:00:00.000Z"], [v2, "v2", "2026-10-16T12:00:00.000Z"]] as const) {
+    await persistRelease(r, [], loc);
+    await appendCut({ releaseDigest: r.releaseDigest, label, actor: "alice", timestamp: at, runOrigin: null }, loc);
+  }
+  await appendGateResolution({ op: "release", gate: "prod-release", resolvedBy: "bob", origin: "cli", timestamp: "2026-10-16T10:30:00.000Z", planDigest: PLAN, environment: "prod", releaseDigest: v1.releaseDigest }, loc);
+  await appendGateResolution({ op: "release", gate: "staging-release", resolvedBy: "carol", origin: "mcp", timestamp: "2026-10-16T12:30:00.000Z", planDigest: PLAN, environment: "staging", releaseDigest: v2.releaseDigest }, loc);
+  await appendGateResolution({ op: "api", gate: "dev-gate", resolvedBy: "dave", timestamp: "2026-10-16T11:00:00.000Z", planDigest: DEV_PLAN, environment: "dev" }, loc);
+  await persistReleasePlan({ digest: DEV_PLAN, work: ["W-001"] }, loc);
+  const deploy = (env: string, gitSha: string, runId: string, timestamp: string, extra: Record<string, unknown>) =>
+    appendReleaseRecord({ component: "api", env, digest: DEV_PLAN, gitSha, runId, timestamp, actor: "ci", ...extra }, loc);
+  await deploy("prod", sha.c2, "run-1", "2026-10-16T10:40:00.000Z", { releaseDigest: v1.releaseDigest, approver: "bob", admission: { op: "release", gate: "prod-release", resolvedAt: "2026-10-16T10:30:00.000Z" } });
+  await deploy("dev", sha.c3, "run-2", "2026-10-16T11:10:00.000Z", { approver: "dave", admission: { op: "api", gate: "dev-gate", resolvedAt: "2026-10-16T11:00:00.000Z" } });
+  await deploy("staging", sha.c4, "run-3", "2026-10-16T12:40:00.000Z", { approver: "carol", admission: { op: "release", gate: "staging-release", resolvedAt: "2026-10-16T12:30:00.000Z" } });
+}, 30_000);
+afterAll(cleanScratch);
+
+const intent = contract(intentSchema);
+type Result = Exclude<IntentDocument, { error: unknown }>;
+
+async function walk(region: string): Promise<Result> {
+  const { doc } = await intentGraph({ cwd: root, region, kinds: ["work/work.kind.mjs", "decisions/decision.kind.mjs"].map((k) => join(root, k)) });
+  intent.expectValid(doc);
+  if ("error" in doc) throw new Error(`${doc.error.code}: ${doc.error.message}`);
+  return doc;
+}
+
+describe("the why chain (#4023)", () => {
+  test("a file region walks each commit to its work item, tag, release, gate and deploys, each link with its source", async () => {
+    const doc = await walk("app/server.mjs");
+    const trace = doc.trace!;
+    expect(trace.reasons).toEqual([]);
+    expect(trace.commits.map((c) => c.sha)).toEqual([sha.c3, sha.c2, sha.c1]);
+    const [c3, c2] = trace.commits;
+
+    // Who asked for it: the trailer links c2 to W-001; c3 only falls in its window.
+    expect(c2.work).toEqual({ state: "linked", items: [{ id: "work:W-001", node: "record:work/W-001", source: { ref: sha.c2, field: "Chant-Record", value: "work:W-001" } }], problems: [] });
+    expect(c3.work).toMatchObject({ state: "unlinked", items: [] });
+    expect(c3.windowMatches).toEqual([{ id: "work:W-001", node: "record:work/W-001", source: { ref: "work/W-001-port.md", field: "window", value: "worked" } }]);
+
+    // The ci tags.
+    expect(c2.tag).toMatchObject({ state: "green", green: { tag: `ci/green/${sha.c2}`, source: { ref: `refs/tags/ci/green/${sha.c2}` } }, revoked: null });
+    expect(c3.tag).toMatchObject({ state: "revoked", revoked: { tag: `ci/revoked/${sha.c3}` } });
+
+    // The release cut from c2, and the first release that contains c3.
+    expect(c2.releases).toEqual([{ release: v1.releaseDigest, link: "cut-from", source: { ref: `chant/lifecycle:_members/app/_releases/${v1.releaseDigest.replace(/:/g, "_")}.json`, field: "commit", value: sha.c2 } }]);
+    expect(c3.releases).toEqual([expect.objectContaining({ release: v2.releaseDigest, link: "contains", source: expect.objectContaining({ value: sha.c4 }) })]);
+
+    // The first deploy per environment that shipped each commit.
+    expect(c2.deploys.map((d) => [d.env, d.link])).toEqual([["dev", "contains"], ["prod", "built-from"], ["staging", "contains"]]);
+    expect(c3.deploys.map((d) => [d.env, d.link])).toEqual([["dev", "built-from"], ["staging", "contains"]]);
+
+    // Who let it ship: the release gate's resolution, with resolver, channel, time and plan.
+    const r1 = trace.releases.find((r) => r.releaseDigest === v1.releaseDigest)!;
+    expect(r1).toMatchObject({ label: "v1", commit: sha.c2, tag: { state: "green" }, cuts: [{ label: "v1", actor: "alice", signed: false }] });
+    expect(r1.gates).toEqual([
+      expect.objectContaining({ op: "release", gate: "prod-release", environment: "prod", resolvedBy: "bob", channel: "cli", at: "2026-10-16T10:30:00.000Z", planDigest: PLAN, changeSet: null, source: { ref: "chant/lifecycle:_members/app/_gates/release.jsonl", field: "releaseDigest", value: v1.releaseDigest } }),
+    ]);
+    const prod = trace.deploys.find((d) => d.env === "prod")!;
+    expect(r1.deploys).toEqual([prod.id]);
+    expect(prod).toMatchObject({ release: v1.releaseDigest, releaseSource: { field: "releaseDigest" }, admittedBy: { gate: "prod-release", resolvedBy: "bob" }, source: { ref: "chant/lifecycle:_members/app/prod/releases.jsonl", field: "runId", value: "run-1" } });
+
+    // A deploy with no releaseDigest joins its release through its release gate admission (#4043).
+    const staging = trace.deploys.find((d) => d.env === "staging")!;
+    expect(staging).toMatchObject({ release: v2.releaseDigest, releaseSource: { field: "admission", value: "staging-release@2026-10-16T12:30:00.000Z" }, admittedBy: { resolvedBy: "carol", channel: "mcp" } });
+    expect(trace.releases.find((r) => r.releaseDigest === v2.releaseDigest)!.deploys).toEqual([staging.id]);
+
+    // A plain deploy names no release, and its component gate and release plan (ws-055) are read back.
+    const dev = trace.deploys.find((d) => d.env === "dev")!;
+    expect(dev).toMatchObject({ release: null, admittedBy: { op: "api", gate: "dev-gate", resolvedBy: "dave", planDigest: DEV_PLAN }, plan: { document: { digest: DEV_PLAN, work: ["W-001"] }, source: { field: "digest" } } });
+
+    expect(traceLines(trace)).toEqual(
+      expect.arrayContaining([
+        expect.stringMatching(new RegExp(`^trace     ${sha.c2.slice(0, 8)} work work:W-001 \\(Chant-Record\\); in the window of work:W-001; green; released as v1; dev since`)),
+        expect.stringMatching(/^release   v1 from .*green; cut by alice/),
+        expect.stringMatching(/^  gate      release\/prod-release prod: bob on cli at 2026-10-16T10:30:00.000Z/),
+        expect.stringMatching(/^deploy    dev api .* no release; admitted by api\/dev-gate dev: dave/),
+      ]),
+    );
+  });
+
+  test("a commit sha is a region: the chain of that one commit, from the files it changed", async () => {
+    const doc = await walk(sha.c2.slice(0, 10));
+    expect(doc.region).toBe(`region:commit:${sha.c2}`);
+    expect(doc.nodes[0]).toMatchObject({ kind: "region", type: "commit", path: ".", commit: sha.c2, member: "app" });
+    expect(doc.history.follows).toBe("commit");
+    expect(doc.trace!.commits.map((c) => [c.sha, c.work?.state, c.tag.state, c.releases.map((r) => r.link)])).toEqual([[sha.c2, "linked", "green", ["cut-from"]]]);
+    // W-001 constrains a file the commit changed, so the work node is there and the commit falls in its window.
+    expect(doc.trace!.commits[0].windowMatches.map((w) => w.id)).toEqual(["work:W-001"]);
+  });
+
+  test("a commit no release was cut from is shipped by the first release that contains it", async () => {
+    const doc = await walk("README.md");
+    expect(doc.trace!.commits.map((c) => [c.sha, c.work?.state, c.tag.state, c.releases.map((r) => [r.release, r.link])])).toEqual([
+      [sha.c4, "unlinked", "green", [[v2.releaseDigest, "cut-from"]]],
+      [sha.c1, "unlinked", "none", [[v1.releaseDigest, "contains"]]],
+    ]);
+    expect(doc.trace!.commits[1].deploys.map((d) => [d.env, d.link])).toEqual([["dev", "contains"], ["prod", "contains"], ["staging", "contains"]]);
+  });
+});