@intentius/chant 0.124.27 → 0.124.29

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"]]);
+  });
+});

package/src/workspace/intent-trace.ts

@@ -0,0 +1,484 @@
+/**
+ * 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 { execFileSync } from "node:child_process";
+import type { GateResolutionRecord } from "../lifecycle/gate-ledger";
+import type { ReleaseRecord, RunOrigin } from "../lifecycle/release-ledger";
+import type { JoinedRelease } from "../lifecycle/release-join";
+import type { ReleasePlan } from "../lifecycle/plan-ledger";
+import type { Release, ReleaseCut } from "../lifecycle/release-store";
+import type { CiTags, CountedCiTag, IgnoredCiTag, RevokedTagView } from "./ci-green";
+import type { CommitLinkProblem, CommitLinkState, WorkIndex } from "./commit-links";
+import type { CiGreen } from "./declaration";
+import type { CommitTrailerJoins } from "./trailer-joins";
+
+/** 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;
+}
+
+function tryGit(top: string, args: string[]): string | undefined {
+  try {
+    return execFileSync("git", args, { cwd: top, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: 256 * 1024 * 1024 });
+  } catch {
+    return undefined;
+  }
+}
+
+const fileOf = (digest: string): string => `${digest.replace(/:/g, "_")}.json`;
+const onBranch = (path: string): string => `chant/lifecycle:${path}`;
+const byTime = (a: string, b: string): number => (a < b ? -1 : a > b ? 1 : 0);
+
+type RevokedView = (sha: string, r: CountedCiTag) => RevokedTagView;
+
+function tagOf(sha: string, tags: CiTags | null, revokedView: RevokedView): TraceTag {
+  const green = tags?.green.get(sha);
+  const revoked = tags?.revoked.get(sha);
+  const view = (kind: "green" | "revoked", t: CountedCiTag): TraceTagView => ({
+    tag: `ci/${kind}/${sha}`,
+    tagged: t.tagged,
+    signer: t.signer,
+    source: { ref: `refs/tags/ci/${kind}/${sha}`, field: "name", value: sha },
+  });
+  return {
+    state: revoked ? "revoked" : green ? "green" : "none",
+    green: green ? view("green", green) : null,
+    revoked: revoked ? { ...view("revoked", revoked), phase: revokedView(sha, revoked).phase, run: revokedView(sha, revoked).run } : null,
+    ignored: tags?.ignored.get(sha) ?? [],
+  };
+}
+
+/** Build the chain. Never throws for a ledger or tag it can't read: that is a reason. */
+export async function buildTrace(input: TraceInput): Promise<IntentTrace> {
+  const { top } = input;
+  const reasons: IntentTrace["reasons"] = [];
+  const shas = input.commits.map((c) => c.sha);
+
+  // The ci tags, judged as release cut judges them.
+  let tags: CiTags | null = null;
+  const { revokedTagView } = await import("./ci-green");
+  try {
+    const { judgedCiTags } = await import("../lifecycle/release-revocation");
+    tags = await judgedCiTags(top, input.green);
+  } catch (err) {
+    reasons.push({ code: "declaration-invalid", message: `the ci tags could not be judged: ${err instanceof Error ? err.message : String(err)}` });
+  }
+
+  // The work item each commit names (#4029).
+  const { judgeCommitLink, hasLeaseLedger, mergeCommits } = await import("./commit-links");
+  const index: WorkIndex | null = input.work ? { ...input.work.index, ledger: hasLeaseLedger(top) } : null;
+  const merges = index ? mergeCommits(top, shas) : new Set<string>();
+  const workNode = (id: string) => input.work?.nodes.get(id) ?? null;
+
+  // The ledgers on the local chant/lifecycle branch.
+  const branch = tryGit(top, ["rev-parse", "--verify", "--quiet", "refs/heads/chant/lifecycle"]) !== undefined;
+  interface Ledger {
+    member: string | null;
+    loc: { cwd: string };
+    prefix: string;
+    releases: Release[];
+    deploys: { env: string; record: ReleaseRecord }[];
+  }
+  const ledgers: Ledger[] = [];
+  // One listing of the branch, so a ledger that holds no release and no deploy costs nothing more.
+  const paths = branch ? (tryGit(top, ["ls-tree", "-r", "--name-only", "--full-tree", "refs/heads/chant/lifecycle"]) ?? "").split("\n").filter(Boolean) : [];
+  const holds = (prefix: string) =>
+    paths.some((p) => p.startsWith(prefix) && (p.startsWith(`${prefix}_releases/`) || /^[^/_][^/]*\/releases\.jsonl$/.test(p.slice(prefix.length))));
+  if (branch) {
+    const { resolveMemberLedger } = await import("../lifecycle/member-ledger");
+    const { readAllReleases } = await import("../lifecycle/release-store");
+    const { listReleaseEnvironments, readReleaseLedger } = await import("../lifecycle/release-ledger");
+    for (const l of input.ledgers) {
+      if (l.within !== null && !paths.some((p) => p.includes(l.within!))) continue;
+      const loc = { cwd: l.cwd };
+      try {
+        const prefix = (await resolveMemberLedger(l.cwd)).prefix;
+        if (ledgers.some((x) => x.prefix === prefix) || !holds(prefix)) continue;
+        const { releases } = await readAllReleases(loc);
+        const deploys: Ledger["deploys"] = [];
+        for (const env of await listReleaseEnvironments(loc)) {
+          for (const record of (await readReleaseLedger(env, loc)).records) deploys.push({ env, record });
+        }
+        ledgers.push({ member: l.member, loc, prefix, releases, deploys });
+      } catch (err) {
+        reasons.push({ code: "ledger-unreadable", message: `${l.member ?? "the workspace"}'s ledger on chant/lifecycle: ${err instanceof Error ? err.message.split("\n")[0] : String(err)}` });
+      }
+    }
+  }
+
+  // Each commit to the releases and deploys that shipped it.
+  const firstCut = new Map<string, string>();
+  const releaseHits = new Map<Ledger, Set<string>>();
+  const deployHits = new Map<string, { ledger: Ledger; env: string; record: ReleaseRecord }>();
+  const deployId = (l: Ledger, env: string, r: ReleaseRecord) => `deploy:${l.member ?? "."}/${env}/${r.component}/${r.runId}@${r.timestamp}`;
+  const perCommit = new Map<string, { releases: TraceCommit["releases"]; deploys: TraceCommit["deploys"] }>();
+  if (ledgers.some((l) => l.releases.length > 0)) {
+    const { readCuts } = await import("../lifecycle/release-store");
+    for (const l of ledgers) {
+      if (l.releases.length === 0) continue;
+      try {
+        for (const c of (await readCuts(l.loc)).cuts) if (!firstCut.has(c.releaseDigest) || byTime(c.timestamp, firstCut.get(c.releaseDigest)!) < 0) firstCut.set(c.releaseDigest, c.timestamp);
+      } catch {
+        // A release with no readable cut sorts last; its file still joins.
+      }
+    }
+  }
+  for (const sha of shas) {
+    const releases: TraceCommit["releases"] = [];
+    const deploys: TraceCommit["deploys"] = [];
+    for (const l of ledgers) {
+      const releaseSource = (r: Release): TraceSource => ({ ref: onBranch(`${l.prefix}_releases/${fileOf(r.releaseDigest)}`), field: "commit", value: r.commit });
+      const cut = l.releases.filter((r) => r.commit === sha);
+      const chosen: { r: Release; link: "cut-from" | "contains" }[] = cut.map((r) => ({ r, link: "cut-from" as const }));
+      if (chosen.length === 0) {
+        const later = l.releases.filter((r) => input.contains(sha, r.commit)).sort((a, b) => byTime(firstCut.get(a.releaseDigest) ?? "￿", firstCut.get(b.releaseDigest) ?? "￿") || byTime(a.releaseDigest, b.releaseDigest));
+        if (later.length > 0) chosen.push({ r: later[0], link: "contains" });
+      }
+      for (const { r, link } of chosen) {
+        releases.push({ release: r.releaseDigest, link, source: releaseSource(r) });
+        (releaseHits.get(l) ?? releaseHits.set(l, new Set()).get(l)!).add(r.releaseDigest);
+      }
+      const first = new Map<string, { env: string; record: ReleaseRecord; link: "built-from" | "contains" }>();
+      for (const d of l.deploys) {
+        const link = d.record.gitSha === sha ? "built-from" : input.contains(sha, d.record.gitSha) ? "contains" : null;
+        if (!link) continue;
+        const had = first.get(d.env);
+        if (!had || byTime(d.record.timestamp, had.record.timestamp) < 0) first.set(d.env, { ...d, link });
+      }
+      for (const [env, d] of [...first].sort(([a], [b]) => byTime(a, b))) {
+        const id = deployId(l, env, d.record);
+        deployHits.set(id, { ledger: l, env, record: d.record });
+        deploys.push({ deploy: id, env, link: d.link, source: { ref: onBranch(`${l.prefix}${env}/releases.jsonl`), field: "gitSha", value: d.record.gitSha } });
+      }
+    }
+    perCommit.set(sha, { releases, deploys });
+  }
+
+  // The releases, through joinRelease, with their gates and deploys.
+  const { joinRelease } = await import("../lifecycle/release-join");
+  const { readGateLedger } = await import("../lifecycle/gate-ledger");
+  const { readStoredChangeSet, changeSetFile, CHANGE_SETS_DIR } = await import("../lifecycle/change-set-store");
+  const gateLedgers = new Map<string, Promise<GateResolutionRecord[]>>();
+  const resolutionsOf = (l: Ledger, op: string) => {
+    const key = `${l.prefix}\0${op}`;
+    let hit = gateLedgers.get(key);
+    if (!hit) {
+      hit = readGateLedger(op, l.loc).then(
+        (g) => g.resolutions,
+        () => [],
+      );
+      gateLedgers.set(key, hit);
+    }
+    return hit;
+  };
+  const changeSets = new Map<string, Promise<boolean>>();
+  const gateOf = async (l: Ledger, r: GateResolutionRecord): Promise<TraceGate> => {
+    let stored: Promise<boolean> | undefined;
+    if (r.planDigest) {
+      const key = `${l.prefix}\0${r.planDigest}`;
+      stored = changeSets.get(key);
+      if (!stored) {
+        stored = readStoredChangeSet(r.planDigest, l.loc).then(
+          (x) => x.status === "found",
+          () => false,
+        );
+        changeSets.set(key, stored);
+      }
+    }
+    const has = stored ? await stored : false;
+    return {
+      op: r.op,
+      gate: r.gate,
+      environment: r.environment ?? null,
+      resolvedBy: r.resolvedBy,
+      relayedBy: r.relayedBy ?? null,
+      channel: r.origin ?? null,
+      at: r.timestamp,
+      planDigest: r.planDigest ?? null,
+      changeSet: has ? r.planDigest! : null,
+      changeSetSource: has ? { ref: onBranch(`${l.prefix}${CHANGE_SETS_DIR}/${changeSetFile(r.planDigest!)}`), field: "planDigest", value: r.planDigest! } : null,
+      empty: r.empty === true,
+      sealed: r.seal !== undefined,
+      url: r.url ?? null,
+      source: { ref: onBranch(`${l.prefix}_gates/${r.op}.jsonl`), field: r.releaseDigest ? "releaseDigest" : "gate", value: r.releaseDigest ?? r.gate },
+    };
+  };
+
+  const releases: TraceRelease[] = [];
+  const joinedDeploys = new Map<string, { ledger: Ledger; env: string; record: ReleaseRecord; release: JoinedRelease }>();
+  for (const l of ledgers) {
+    const wanted = releaseHits.get(l);
+    if (!wanted || wanted.size === 0) continue;
+    const commits = [...new Set(l.releases.filter((r) => wanted.has(r.releaseDigest)).map((r) => r.commit))];
+    let joined: JoinedRelease[];
+    try {
+      joined = (await joinRelease({ commits }, l.loc)).releases;
+    } catch (err) {
+      reasons.push({ code: "ledger-unreadable", message: `joining ${l.member ?? "the workspace"}'s releases: ${err instanceof Error ? err.message.split("\n")[0] : String(err)}` });
+      continue;
+    }
+    for (const j of joined) {
+      for (const d of j.deploys) joinedDeploys.set(deployId(l, d.env, d), { ledger: l, env: d.env, record: d, release: j });
+      releases.push({
+        releaseDigest: j.releaseDigest,
+        label: j.label,
+        member: j.release.member,
+        commit: j.commit,
+        tag: tagOf(j.commit, tags, revokedTagView),
+        source: { ref: onBranch(`${l.prefix}_releases/${fileOf(j.releaseDigest)}`), field: "releaseDigest", value: j.releaseDigest },
+        cuts: j.cuts.map((c: ReleaseCut) => ({
+          label: c.label,
+          actor: c.actor,
+          timestamp: c.timestamp,
+          signed: c.signature !== null,
+          runOrigin: c.runOrigin,
+          source: { ref: onBranch(`${l.prefix}_releases/cuts.jsonl`), field: "releaseDigest", value: c.releaseDigest },
+        })),
+        gates: await Promise.all([...j.gates.resolutions].sort((a, b) => byTime(a.timestamp, b.timestamp)).map((r) => gateOf(l, r))),
+        deploys: j.deploys.map((d) => deployId(l, d.env, d)),
+      });
+    }
+  }
+
+  // The deploys: those a commit names and those of each release, oldest first.
+  const { readReleasePlan } = await import("../lifecycle/plan-ledger");
+  const plans = new Map<string, Promise<ReleasePlan | null>>();
+  const all = new Map<string, { ledger: Ledger; env: string; record: ReleaseRecord; release?: JoinedRelease }>([...deployHits, ...joinedDeploys]);
+  const releaseResolutions = new Map<Ledger, GateResolutionRecord[]>();
+  const deploys: TraceDeploy[] = [];
+  for (const [id, d] of [...all].sort(([, a], [, b]) => byTime(a.record.timestamp, b.record.timestamp) || byTime(a.env, b.env))) {
+    const r = d.record;
+    const l = d.ledger;
+    let release: string | null = r.releaseDigest ?? null;
+    let releaseSource: TraceSource | null = release ? { ref: onBranch(`${l.prefix}${d.env}/releases.jsonl`), field: "releaseDigest", value: release } : null;
+    if (!release && r.admission?.op === "release") {
+      if (!releaseResolutions.has(l)) releaseResolutions.set(l, await resolutionsOf(l, "release"));
+      const { releaseOfDeploy } = await import("../lifecycle/release-join");
+      release = releaseOfDeploy(r, releaseResolutions.get(l)!) ?? null;
+      if (release) releaseSource = { ref: onBranch(`${l.prefix}${d.env}/releases.jsonl`), field: "admission", value: `${r.admission.gate}@${r.admission.resolvedAt}` };
+    }
+    let admittedBy: TraceGate | null = null;
+    if (r.admission) {
+      const found = (await resolutionsOf(l, r.admission.op)).find((x) => x.gate === r.admission!.gate && x.timestamp === r.admission!.resolvedAt);
+      if (found) admittedBy = await gateOf(l, found);
+    }
+    const planKey = `${l.prefix}\0${r.digest}`;
+    let plan = plans.get(planKey);
+    if (!plan) {
+      plan = readReleasePlan(r.digest, l.loc).catch(() => null);
+      plans.set(planKey, plan);
+    }
+    const document = await plan;
+    deploys.push({
+      id,
+      member: l.member,
+      env: d.env,
+      component: r.component,
+      timestamp: r.timestamp,
+      actor: r.actor,
+      approver: r.approver ?? null,
+      runId: r.runId,
+      runOrigin: r.runOrigin ?? null,
+      gitSha: r.gitSha,
+      digest: r.digest,
+      release,
+      releaseSource,
+      admittedBy,
+      plan: document ? { document, source: { ref: onBranch(`${l.prefix}_plans/${fileOf(r.digest)}`), field: "digest", value: r.digest } } : null,
+      source: { ref: onBranch(`${l.prefix}${d.env}/releases.jsonl`), field: "runId", value: r.runId },
+    });
+  }
+
+  const commits: TraceCommit[] = input.commits.map((c) => {
+    let work: TraceCommit["work"] = null;
+    if (index) {
+      const judged = merges.has(c.sha) ? { state: "merge" as const, ids: [], problems: [] } : judgeCommitLink(c.trailers, c.joins, index);
+      const items: TraceWork[] = judged.ids.map((id) => {
+        const named = c.joins.records.some((r) => `${r.kind}:${r.id}` === id);
+        return {
+          id,
+          node: workNode(id),
+          source: named ? { ref: c.sha, field: "Chant-Record", value: id } : { ref: c.sha, field: "Chant-Lease", value: c.joins.lease?.token ?? "" },
+        };
+      });
+      work = { state: judged.state, items, problems: judged.problems };
+    }
+    const windowMatches: TraceWork[] = (input.windows.get(c.sha) ?? []).map((w) => ({ id: w.id, node: w.node, source: { ref: w.path, field: "window", value: "worked" } }));
+    const hit = perCommit.get(c.sha) ?? { releases: [], deploys: [] };
+    return { commit: c.id, sha: c.sha, work, windowMatches, tag: tagOf(c.sha, tags, revokedTagView), releases: hit.releases, deploys: hit.deploys };
+  });
+
+  return { commits, releases, deploys, reasons };
+}