@intentius/chant 0.124.28 → 0.124.30

package/dist/workspace/flags.d.ts

@@ -0,0 +1,100 @@
+/**
+ * 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 { type LoadedRecordKind, type ReadRecordsOptions, type RecordEntry } from "./records.js";
+import type { WorkLink } from "./work.js";
+/** Why a flag record carries a warning. Closed, like the record warning codes. */
+export declare const FLAG_WARNING_CODES: readonly ["flag-work-unknown", "flag-stale"];
+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[];
+}
+/**
+ * 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 declare function decisionConfirmed(decision: {
+    state: string | null;
+    supersededBy: string | null;
+} | undefined, closed: ReadonlySet<string>): boolean;
+/**
+ * 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 declare function applyFlags(loaded: LoadedRecordKind, entries: RecordEntry[], options: ReadRecordsOptions): Promise<void>;
+//# sourceMappingURL=flags.d.ts.map

package/dist/workspace/flags.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flags.d.ts","sourceRoot":"","sources":["../../src/workspace/flags.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAIH,OAAO,EAAgD,KAAK,gBAAgB,EAAE,KAAK,kBAAkB,EAAE,KAAK,WAAW,EAAE,MAAM,WAAW,CAAC;AAC3I,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AAEvC,kFAAkF;AAClF,eAAO,MAAM,kBAAkB,8CAKW,CAAC;AAC3C,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC;AAElE,+EAA+E;AAC/E,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAElD,8EAA8E;AAC9E,MAAM,WAAW,YAAa,SAAQ,QAAQ;IAC5C,oEAAoE;IACpE,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,8DAA8D;AAC9D,MAAM,WAAW,SAAS;IACxB,qIAAqI;IACrI,IAAI,EAAE,QAAQ,GAAG,IAAI,CAAC;IACtB,iHAAiH;IACjH,UAAU,EAAE,YAAY,EAAE,CAAC;IAC3B,wHAAwH;IACxH,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,0DAA0D;AAC1D,MAAM,WAAW,aAAa;IAC5B,wCAAwC;IACxC,EAAE,EAAE,MAAM,CAAC;IACX,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,kEAAkE;IAClE,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,wEAAwE;IACxE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IAClC,IAAI,EAAE,QAAQ,GAAG,IAAI,CAAC;IACtB,UAAU,EAAE,YAAY,EAAE,CAAC;IAC3B,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,8DAA8D;AAC9D,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,gFAAgF;IAChF,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,yDAAyD;AACzD,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,aAAa,EAAE,CAAC;IACvB,OAAO,EAAE,WAAW,EAAE,CAAC;CACxB;AAID;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE;IAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GAAG,SAAS,EAAE,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,OAAO,CAEnJ;AAED;;;;GAIG;AACH,wBAAsB,UAAU,CAAC,MAAM,EAAE,gBAAgB,EAAE,OAAO,EAAE,WAAW,EAAE,EAAE,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAuC7H"}

package/dist/workspace/flags.js

@@ -0,0 +1,98 @@
+/**
+ * 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 { loadRecordKind, readRecords, RecordReadError } from "./records.js";
+/** 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",
+];
+const str = (v) => (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, closed) {
+    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, entries, options) {
+    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();
+    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 = (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/dist/workspace/graph-cli.js

@@ -51,7 +51,7 @@ export const GRAPH_OUTPUT_SCHEMA_ID = "https://intentius.io/chant/schemas/worksp
 export const GRAPH_ERROR_CODES = [...WORKSPACE_ERROR_CODES, "live-at-revision"];
 /** Why `--live` and `--at` don't go together (#2875). */
 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]";
+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|member/node|sha> [--at <rev>] [--kind <kind file>...] [--follow-squash] [--json]";
 /** The command line a member runs for its component graph (#2662). */
 export function componentGraphArgv(args) {
     return ["graph", ".", "--components", "--format", "ir", ...(args.env ? ["--env", args.env] : [])];

package/dist/workspace/intent-cli.d.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,10 +7,13 @@
  * 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 type { CommandContext } from "../cli/registry.js";
 import { type IntentRecordDocument } from "./intent-record.js";
+import type { IntentTrace } from "./intent-trace.js";
 import { type IntentDocument, type WhyAnswer } from "./intent.js";
 type Result = Exclude<IntentDocument, {
     error: unknown;
@@ -22,6 +25,12 @@ type RecordResult = Exclude<IntentRecordDocument, {
 export declare const IN_WINDOW_QUESTION = "is this drift, a superseding decision nobody wrote down, or the decision being wrong?";
 /** Why the region is like this (#3034): the decisions most relevant first, then who made each span of its current lines, then the gaps. */
 export declare function whyLines(doc: Result, why: WhyAnswer): string[];
+/**
+ * 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 declare function traceLines(trace: IntentTrace): string[];
 /** The walk as text, one line each, in the order of #2650 section B. */
 export declare function formatIntent(doc: Result): string;
 /** The record walk as text: the record, its window, then each commit with its bucket, and the counts. */

package/dist/workspace/intent-cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"intent-cli.d.ts","sourceRoot":"","sources":["../../src/workspace/intent-cli.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,EAAgB,KAAK,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAC1E,OAAO,EAAsE,KAAK,cAAc,EAAkD,KAAK,SAAS,EAAiB,MAAM,UAAU,CAAC;AAKlM,KAAK,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE;IAAE,KAAK,EAAE,OAAO,CAAA;CAAE,CAAC,CAAC;AAC1D,KAAK,YAAY,GAAG,OAAO,CAAC,oBAAoB,EAAE;IAAE,KAAK,EAAE,OAAO,CAAA;CAAE,CAAC,CAAC;AAYtE,gIAAgI;AAChI,eAAO,MAAM,kBAAkB,0FAA0F,CAAC;AAwG1H,2IAA2I;AAC3I,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,SAAS,GAAG,MAAM,EAAE,CAsB9D;AAED,wEAAwE;AACxE,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CA6BhD;AAED,yGAAyG;AACzG,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,YAAY,GAAG,MAAM,CAwB5D;AAcD,wBAAsB,kBAAkB,CAAC,GAAG,EAAE,cAAc,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAuB1F"}
+{"version":3,"file":"intent-cli.d.ts","sourceRoot":"","sources":["../../src/workspace/intent-cli.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,EAAgB,KAAK,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAC1E,OAAO,KAAK,EAAE,WAAW,EAAa,MAAM,gBAAgB,CAAC;AAC7D,OAAO,EAAsE,KAAK,cAAc,EAAkD,KAAK,SAAS,EAAiB,MAAM,UAAU,CAAC;AAKlM,KAAK,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE;IAAE,KAAK,EAAE,OAAO,CAAA;CAAE,CAAC,CAAC;AAC1D,KAAK,YAAY,GAAG,OAAO,CAAC,oBAAoB,EAAE;IAAE,KAAK,EAAE,OAAO,CAAA;CAAE,CAAC,CAAC;AAYtE,gIAAgI;AAChI,eAAO,MAAM,kBAAkB,0FAA0F,CAAC;AAwG1H,2IAA2I;AAC3I,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,SAAS,GAAG,MAAM,EAAE,CAsB9D;AAKD;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,EAAE,CA0BvD;AAED,wEAAwE;AACxE,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CA+BhD;AAED,yGAAyG;AACzG,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,YAAY,GAAG,MAAM,CAwB5D;AAcD,wBAAsB,kBAAkB,CAAC,GAAG,EAAE,cAAc,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAuB1F"}

package/dist/workspace/intent-cli.js

@@ -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,13 +7,15 @@
  * 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.js";
 import { intentRecord } from "./intent-record.js";
 import { intentGraph } from "./intent.js";
-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]";
 function edgesFrom(doc, from, kind) {
     return doc.edges.filter((e) => e.from === from && e.kind === kind);
@@ -157,6 +159,48 @@ export function whyLines(doc, why) {
         out.push(`  gap       ${g.code}: ${g.message}${g.lines ? ` (lines ${g.lines.map(span).join(", ")})` : ""}`);
     return out;
 }
+const gateLabel = (g) => `${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) {
+    const out = [];
+    const label = (digest) => trace.releases.find((r) => r.releaseDigest === digest)?.label ?? digest.slice(0, 24);
+    for (const c of trace.commits) {
+        const parts = [];
+        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) {
     const out = [];
@@ -165,7 +209,10 @@ export function formatIntent(doc) {
         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)
@@ -190,6 +237,8 @@ export function formatIntent(doc) {
         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}`);
@@ -245,7 +294,7 @@ export async function runWorkspaceIntent(ctx, cwd) {
         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/dist/workspace/intent-trace.d.ts

@@ -0,0 +1,219 @@
+/**
+ * The why chain of a region (#4023): for each commit the intent walk read,
+ * the work item it names, its ci tag, the release that shipped it, the gate
+ * resolutions that admitted that release and the deploy records per
+ * environment. "Who asked for this, and who let it ship" in one read.
+ *
+ * Every link is made by a record that already exists, and each one states
+ * that record in `source`, so a reader can follow it:
+ *
+ * - work item: a `Chant-Record` or `Chant-Lease` trailer, judged as #4029's
+ *   `judgeCommitLink` judges it. A commit in a work item's window (the
+ *   intent graph's `worked` bucket) is listed apart, as a window match, and
+ *   never links it.
+ * - ci tag: `ci/green/<sha>` or `ci/revoked/<sha>`, judged as `release cut`
+ *   judges it (#4031, `judgedCiTags`).
+ * - release: `_releases/<digest>.json`, whose `commit` is the commit itself
+ *   (`cut-from`) or one that has it in its history (`contains`).
+ * - gates and deploys: `joinRelease` (#4043), and a deploy's `admission`
+ *   read back to the resolution in `_gates/<op>.jsonl` (#4020).
+ * - the plan a gate bound: the change set stored under its `planDigest`
+ *   (#4022), and a deploy's release plan in `_plans/` (ws-055).
+ *
+ * A commit is "contained" by a later commit when that commit has it as an
+ * ancestor in the history read. For each commit the chain names the releases
+ * cut from it, or failing those the first release cut after it, and the first
+ * deploy per environment that shipped it, so the document stays the size of
+ * the walk. Everything is read from local git: the tags and the local
+ * `chant/lifecycle` branch. Nothing is fetched.
+ */
+import type { RunOrigin } from "../lifecycle/release-ledger.js";
+import type { ReleasePlan } from "../lifecycle/plan-ledger.js";
+import type { IgnoredCiTag, RevokedTagView } from "./ci-green.js";
+import type { CommitLinkProblem, CommitLinkState, WorkIndex } from "./commit-links.js";
+import type { CiGreen } from "./declaration.js";
+import type { CommitTrailerJoins } from "./trailer-joins.js";
+/** Where a link comes from: the record (`ref`), and the field of it whose `value` made the join. */
+export interface TraceSource {
+    /** A commit sha, a tag ref (`refs/tags/...`), a record file, or a path on `chant/lifecycle` (`chant/lifecycle:<path>`). */
+    ref: string;
+    /** The trailer, field or edge that joins, such as `Chant-Record`, `commit`, `releaseDigest`, `admission` or `window`. */
+    field: string;
+    /** Its value, as the record holds it. */
+    value: string;
+}
+/** A work item a commit links to, or falls in the window of. */
+export interface TraceWork {
+    /** `<kind>:<id>`. */
+    id: string;
+    /** The work node in `nodes`, or null when no kind read has the record. */
+    node: string | null;
+    source: TraceSource;
+}
+export interface TraceTagView {
+    tag: string;
+    tagged: string | null;
+    /** The runner whose statement the tag carries, or null for a tag that counts unsigned (#4031). */
+    signer: string | null;
+    source: TraceSource;
+}
+/** A commit's ci tags as readers count them (#4031, ws-103). */
+export interface TraceTag {
+    /** `revoked` when a revoked tag counts, else `green` when a green tag counts, else `none`. */
+    state: "green" | "revoked" | "none";
+    green: TraceTagView | null;
+    revoked: (TraceTagView & Pick<RevokedTagView, "phase" | "run">) | null;
+    /** Tags on the commit that exist and don't count. */
+    ignored: IgnoredCiTag[];
+}
+/** One gate resolution: who let it through, on which channel, when, and for which plan. */
+export interface TraceGate {
+    op: string;
+    gate: string;
+    environment: string | null;
+    resolvedBy: string;
+    relayedBy: string | null;
+    /** `cli`, `mcp` or `acp`, the channel the resolution was authored on (#2384), or null when the record doesn't say. */
+    channel: string | null;
+    at: string;
+    planDigest: string | null;
+    /** `planDigest`, when a change set is stored under it (#4022): `chant change-set show <changeSet>` prints it. */
+    changeSet: string | null;
+    changeSetSource: TraceSource | null;
+    /** A pass over an empty change set, written by the promote itself (#4045). */
+    empty: boolean;
+    /** Whether the approval carries an ssh seal (`chant approve --sign`, #3163). `status` judges it against the signers at base. */
+    sealed: boolean;
+    url: string | null;
+    source: TraceSource;
+}
+/** A release that shipped a commit of the walk. */
+export interface TraceRelease {
+    releaseDigest: string;
+    label: string | null;
+    member: string | null;
+    /** The green commit it was cut from. */
+    commit: string;
+    /** That commit's ci tags. */
+    tag: TraceTag;
+    source: TraceSource;
+    cuts: {
+        label: string | null;
+        actor: string;
+        timestamp: string;
+        signed: boolean;
+        runOrigin: RunOrigin | null;
+        source: TraceSource;
+    }[];
+    /** The release gate's resolutions for it, oldest first. */
+    gates: TraceGate[];
+    /** The ids of its deploy records in `deploys`, oldest first. */
+    deploys: string[];
+}
+/** A deploy record (`ReleaseRecord` in `<env>/releases.jsonl`). */
+export interface TraceDeploy {
+    /** `deploy:<member>/<env>/<component>/<runId>@<timestamp>`, with `.` for a ledger of no member. */
+    id: string;
+    member: string | null;
+    env: string;
+    component: string;
+    timestamp: string;
+    actor: string;
+    approver: string | null;
+    runId: string;
+    runOrigin: RunOrigin | null;
+    gitSha: string;
+    digest: string;
+    /** The release it was made from, by its `releaseDigest` or through the release gate resolution its admission names (#4043), or null. */
+    release: string | null;
+    releaseSource: TraceSource | null;
+    /** The gate resolution its `admission` names (#4020), or null for an ungated deploy, one recorded before 0.124.28, or one whose resolution is not on the branch. */
+    admittedBy: TraceGate | null;
+    /** The release plan its `digest` names in `_plans/` (ws-055), or null when none is stored. */
+    plan: {
+        document: ReleasePlan;
+        source: TraceSource;
+    } | null;
+    source: TraceSource;
+}
+export interface TraceCommit {
+    /** The commit node. */
+    commit: string;
+    sha: string;
+    /**
+     * The work items the commit names, judged as `check --changes` judges it
+     * (#4029): `linked`, `unlinked`, `wrong` or `merge`. Null when no work kind
+     * was read.
+     */
+    work: {
+        state: CommitLinkState;
+        items: TraceWork[];
+        problems: CommitLinkProblem[];
+    } | null;
+    /** The work items whose window holds the commit (the `worked` within edges). They don't link it. */
+    windowMatches: TraceWork[];
+    tag: TraceTag;
+    /** The releases cut from the commit, or when none, the first release cut from a commit that has it in its history. */
+    releases: {
+        release: string;
+        link: "cut-from" | "contains";
+        source: TraceSource;
+    }[];
+    /** Per environment, the first deploy record built from the commit or a commit that has it in its history. */
+    deploys: {
+        deploy: string;
+        env: string;
+        link: "built-from" | "contains";
+        source: TraceSource;
+    }[];
+}
+export type TraceReasonCode = "ledger-unreadable" | "declaration-invalid";
+/** The why chain (#4023): commits in walk order, then the releases and deploys they name. */
+export interface IntentTrace {
+    commits: TraceCommit[];
+    releases: TraceRelease[];
+    deploys: TraceDeploy[];
+    /** Parts of the chain that could not be read: the ci tags (`declaration-invalid`) or a ledger (`ledger-unreadable`). The rest stands. */
+    reasons: {
+        code: TraceReasonCode;
+        message: string;
+    }[];
+}
+export interface TraceInput {
+    top: string;
+    /** The commits of the walk, in its order. */
+    commits: {
+        id: string;
+        sha: string;
+        trailers: Record<string, string[]>;
+        joins: CommitTrailerJoins;
+    }[];
+    /** The work records the walk read, by work kind, and their nodes by `<kind>:<id>`. Null when no work kind was read. */
+    work: {
+        index: Omit<WorkIndex, "ledger">;
+        nodes: Map<string, string>;
+    } | null;
+    /** The work items whose window holds each commit, by sha. */
+    windows: Map<string, {
+        id: string;
+        node: string;
+        path: string;
+    }[]>;
+    /**
+     * The ledgers to read, each as the directory `chant/lifecycle` stores
+     * resolve it from. `within` is a path part every ledger of the member has,
+     * `_members/<name>/`, so a member with nothing on the branch is skipped
+     * unread; null when it can't be told, as for a member at the root.
+     */
+    ledgers: {
+        member: string | null;
+        cwd: string;
+        within: string | null;
+    }[];
+    green: CiGreen | null;
+    /** Whether `later` is `sha` or has it as an ancestor, in the history read. */
+    contains: (sha: string, later: string) => boolean;
+}
+/** Build the chain. Never throws for a ledger or tag it can't read: that is a reason. */
+export declare function buildTrace(input: TraceInput): Promise<IntentTrace>;
+//# sourceMappingURL=intent-trace.d.ts.map

package/dist/workspace/intent-trace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"intent-trace.d.ts","sourceRoot":"","sources":["../../src/workspace/intent-trace.ts"],"names":[],"mappings":"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"}