@intentius/chant 0.124.27 → 0.124.29

package/src/workspace/commit-links.test.ts

@@ -0,0 +1,279 @@
+/**
+ * Which work item a commit belongs to (#4029): the one judgement, and where
+ * `workspace check --changes`, `ci list` and `ci tick` report it.
+ *
+ * - c0 declares the workspace, the decision s-001 and the work items W-001
+ *   and W-002, and a ci.green block.
+ * - c1 carries Chant-Record: work:W-001.
+ * - c2 carries only a Chant-Lease, whose token the lease history of W-002
+ *   on chant/lifecycle names.
+ * - c3 carries nothing.
+ * - c4 names work:W-999, which no record has.
+ * - c5 names decision:s-001, a record of a kind that is not the work kind.
+ * - c6 carries a Chant-Lease no lease history names.
+ * - c7 carries a Chant-Record that is not <kind>:<id>.
+ * - c8 names decision:s-001 and work:W-002, so the decision beside the work
+ *   item changes nothing.
+ * - m is a merge of a branch whose commit is not on the first-parent line.
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { writeBlobToPath } from "../lifecycle/git";
+import { cleanScratch, contract, git, REPO, repo, scratchDir, writeFiles } from "./__fixtures__/contract-repo";
+import { checkChanges, type ChangesDocument } from "./changes";
+import { formatChanges } from "./changes-cli";
+import changesSchema from "./changes.schema.json";
+import { judgeCommitLink, type WorkIndex } from "./commit-links";
+import { ciList, ciTick, formatList, formatTick, whyWorkUnknown, type CiListDocument } from "./ci-green";
+import type { CiForge } from "./ci-green-forge";
+import ciListSchema from "./ci-list.schema.json";
+import { parseFrontMatter } from "./records";
+
+const REF = join(REPO, "reference-workspace");
+const DECISION = (() => {
+  const fm = parseFrontMatter(readFileSync(join(REF, "decisions", "ref-001-how-the-app-is-deployed.md"), "utf-8"));
+  if (!fm.ok) throw new Error(fm.message);
+  return fm.value;
+})();
+
+const decision = (id: string) => `---\n${JSON.stringify({ ...DECISION, id, title: `Decision ${id}`, state: "decided", supersedes: [], evidence: [], constrains: ["path:app"] }, null, 2)}\n---\n\n# ${id}\n`;
+const work = (id: string) => `---\n${JSON.stringify({ schema: 1, id, title: `Work ${id}`, state: "open", implements: [], needs: [], constrains: ["path:app"], evidence: [], opened_on: "2026-10-01", source: { kind: "workspace", member: "app" }, supersedes: [] }, null, 2)}\n---\n\n# ${id}\n`;
+
+const TOKEN = "7a1e5c90-lease-token";
+const NOW = new Date("2026-10-01T13:00:00Z");
+const changes = contract(changesSchema);
+const list = contract(ciListSchema);
+type Result = Exclude<ChangesDocument, { error: unknown }>;
+type Listed = Extract<CiListDocument, { branch: string }>;
+
+let root: string;
+let origin: string;
+const sha: Record<string, string> = {};
+let tick = 0;
+
+function commit(message: string[]): string {
+  const date = `2026-10-01T12:00:${String(tick++).padStart(2, "0")}Z`;
+  process.env.GIT_AUTHOR_DATE = date;
+  process.env.GIT_COMMITTER_DATE = date;
+  try {
+    git(root, "add", "-A");
+    git(root, "commit", "-q", ...message.flatMap((m) => ["-m", m]));
+  } finally {
+    delete process.env.GIT_AUTHOR_DATE;
+    delete process.env.GIT_COMMITTER_DATE;
+  }
+  return git(root, "rev-parse", "HEAD");
+}
+
+function edit(name: string, message: string[]): string {
+  writeFiles(root, { "app/main.js": `export const n = ${tick};\n` });
+  return (sha[name] = commit(message));
+}
+
+beforeAll(async () => {
+  root = repo({
+    "chant.workspace.json": JSON.stringify({
+      name: "links",
+      schema: 1,
+      members: [{ name: "app", dir: "app", kind: "other", because: "the app" }],
+      records: [{ kind: "decisions/decision.kind.mjs" }, { kind: "work/work.kind.mjs" }],
+      ci: { green: { branch: "main", phases: { lint: ["lint"] }, require: ["lint"] } },
+    }),
+    "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"),
+    "decisions/s-001-app.md": decision("s-001"),
+    "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"),
+    "work/W-001-one.md": work("W-001"),
+    "work/W-002-two.md": work("W-002"),
+    "app/main.js": "export const n = 0;\n",
+  });
+  git(root, "symbolic-ref", "HEAD", "refs/heads/main");
+  sha.c0 = commit(["the workspace"]);
+  edit("c1", ["one", "Chant-Record: work:W-001"]);
+  edit("c2", ["two", `Chant-Lease: ${TOKEN}`]);
+  edit("c3", ["three"]);
+  edit("c4", ["four", "Chant-Record: work:W-999"]);
+  edit("c5", ["five", "Chant-Record: decision:s-001"]);
+  edit("c6", ["six", "Chant-Lease: no-such-token"]);
+  edit("c7", ["seven", "Chant-Record: nonsense"]);
+  edit("c8", ["eight", "Chant-Record: decision:s-001\nChant-Record: work:W-002"]);
+  git(root, "checkout", "-q", "-b", "side");
+  writeFiles(root, { "app/side.js": "export const side = 1;\n" });
+  commit(["on a side branch"]);
+  git(root, "checkout", "-q", "main");
+  process.env.GIT_AUTHOR_DATE = process.env.GIT_COMMITTER_DATE = "2026-10-01T12:30:00Z";
+  try {
+    git(root, "merge", "-q", "--no-ff", "-m", "Merge side", "side");
+  } finally {
+    delete process.env.GIT_AUTHOR_DATE;
+    delete process.env.GIT_COMMITTER_DATE;
+  }
+  sha.m = git(root, "rev-parse", "HEAD");
+  const line = { version: 1, event: "claim", item: "W-002", holder: "factory", by: "factory", token: TOKEN, acquiredAt: "2026-10-01T12:00:00Z", expiresAt: "2026-10-01T12:10:00Z", timestamp: "2026-10-01T12:00:00Z" };
+  await writeBlobToPath("_leases", "W-002.jsonl", JSON.stringify(line), "Work lease claim: W-002", { cwd: root });
+});
+afterAll(cleanScratch);
+
+const RANGE = () => `${sha.c0}..${sha.m}`;
+
+async function check(severity?: "off" | "warn" | "fail"): Promise<{ doc: Result; failed: boolean }> {
+  const { doc, failed } = await checkChanges({ cwd: root, range: RANGE(), ...(severity ? { severity } : {}) });
+  changes.expectValid(doc);
+  if ("error" in doc) throw new Error(`${doc.error.code}: ${doc.error.message}`);
+  return { doc, failed };
+}
+
+describe("judging one commit's trailers", () => {
+  const index: WorkIndex = { kinds: new Map([["work", new Set(["W-1", "W-2"])]]), ledger: true };
+  const none = { records: [], lease: null };
+
+  test("a Chant-Record of a work kind with that record links, whatever else the commit names", () => {
+    expect(judgeCommitLink({ "Chant-Record": ["work:W-1"] }, { records: [{ kind: "work", id: "W-1" }], lease: null }, index)).toEqual({ state: "linked", ids: ["work:W-1"], problems: [] });
+    const both = judgeCommitLink({ "chant-record": ["decision:d-1", "work:W-2", "work:W-404"] }, { records: [{ kind: "decision", id: "d-1" }, { kind: "work", id: "W-2" }, { kind: "work", id: "W-404" }], lease: null }, index);
+    expect(both).toEqual({ state: "linked", ids: ["work:W-2"], problems: [] });
+  });
+
+  test("a Chant-Lease links through the work item its history names", () => {
+    expect(judgeCommitLink({ "Chant-Lease": ["t"] }, { records: [], lease: { token: "t", item: "W-2" } }, index)).toMatchObject({ state: "linked", ids: ["work:W-2"] });
+    expect(judgeCommitLink({ "Chant-Lease": ["t"] }, { records: [], lease: { token: "t", item: "W-404" } }, index)).toMatchObject({ state: "wrong" });
+    expect(judgeCommitLink({ "Chant-Lease": ["t"] }, { records: [], lease: { token: "t", item: null } }, index)).toMatchObject({ state: "wrong" });
+  });
+
+  test("a lease is not judged where the lease histories are not there to read", () => {
+    const link = judgeCommitLink({ "Chant-Lease": ["t"] }, { records: [], lease: { token: "t", item: null } }, { ...index, ledger: false });
+    expect(link).toEqual({ state: "linked", ids: [], problems: [] });
+  });
+
+  test("a commit with no trailer is unlinked, and a window match is not a trailer", () => {
+    expect(judgeCommitLink({}, none, index)).toEqual({ state: "unlinked", ids: [], problems: [] });
+    expect(judgeCommitLink({ "Chant-Agent": ["factory"], "Chant-Run": ["r-1"] }, none, index).state).toBe("unlinked");
+  });
+
+  test("each wrongly linked case says which trailer and why", () => {
+    const wrong = (value: string, ref: { kind: string; id: string } | null) => judgeCommitLink({ "Chant-Record": [value] }, { records: ref ? [ref] : [], lease: null }, index);
+    expect(wrong("work:W-9", { kind: "work", id: "W-9" })).toEqual({ state: "wrong", ids: [], problems: [{ trailer: "Chant-Record: work:W-9", message: "the work kind has no record W-9" }] });
+    expect(wrong("decision:d-1", { kind: "decision", id: "d-1" }).problems[0].message).toBe("decision is not a work kind (the work kinds are work)");
+    expect(wrong("nonsense", null).problems[0]).toEqual({ trailer: "Chant-Record: nonsense", message: "nonsense is not <kind>:<id>" });
+  });
+});
+
+describe("workspace check --changes (#4029)", () => {
+  test("judges the first-parent commits of the range, merges left out", async () => {
+    const { doc, failed } = await check();
+    expect(failed).toBe(false);
+    expect(doc.links!.kinds).toEqual(["work"]);
+    expect(doc.links!.commits.map((c) => [c.commit, c.state, c.ids])).toEqual([
+      [sha.c1, "linked", ["work:W-001"]],
+      [sha.c2, "linked", ["work:W-002"]],
+      [sha.c3, "unlinked", []],
+      [sha.c4, "wrong", []],
+      [sha.c5, "wrong", []],
+      [sha.c6, "wrong", []],
+      [sha.c7, "wrong", []],
+      [sha.c8, "linked", ["work:W-002"]],
+    ]);
+    expect(doc.links!.commits.find((c) => c.commit === sha.c4)!.problems).toEqual([{ trailer: "Chant-Record: work:W-999", message: "the work kind has no record W-999" }]);
+    expect(doc.links!.commits.find((c) => c.commit === sha.c5)!.problems[0].message).toContain("decision is not a work kind");
+    expect(doc.links!.commits.find((c) => c.commit === sha.c6)!.problems).toEqual([{ trailer: "Chant-Lease: no-such-token", message: "no lease history on chant/lifecycle names this token" }]);
+    expect(doc.links!.commits.find((c) => c.commit === sha.c7)!.problems[0].trailer).toBe("Chant-Record: nonsense");
+  });
+
+  test("reports an unlinked commit and each wrongly linked one with a fix line, at warn by default", async () => {
+    const { doc } = await check();
+    expect(doc.links!.findings.map((f) => [f.code, f.commit, f.severity])).toEqual([
+      ["commit-unlinked", sha.c3, "warn"],
+      ["commit-wrongly-linked", sha.c4, "warn"],
+      ["commit-wrongly-linked", sha.c5, "warn"],
+      ["commit-wrongly-linked", sha.c6, "warn"],
+      ["commit-wrongly-linked", sha.c7, "warn"],
+    ]);
+    expect(doc.links!.findings[0].id).toBe(`finding:commit-unlinked:${sha.c3}`);
+    expect(doc.links!.findings.every((f) => f.fix.includes("Chant-Record"))).toBe(true);
+    expect(doc.ok).toBe(true);
+    const text = formatChanges(doc);
+    expect(text).toContain("links     8 commits: 3 name a work item, 1 do not, 4 name one that is not there; work kinds: work");
+    expect(text).toContain(`warning   commit-unlinked: ${sha.c3.slice(0, 8)} "three" carries no Chant-Record trailer of a work kind and no Chant-Lease trailer`);
+    expect(text).toContain("          fix: add a `Chant-Record: work:<id>` trailer");
+    expect(text).toContain(`commit-wrongly-linked: ${sha.c4.slice(0, 8)} "four" names no work item that exists: Chant-Record: work:W-999 (the work kind has no record W-999)`);
+  });
+
+  test("--severity sets the level: fail fails the check, off reports no finding", async () => {
+    const fail = await check("fail");
+    expect(fail.failed).toBe(true);
+    expect(fail.doc.ok).toBe(false);
+    expect(fail.doc.links!.findings.every((f) => f.severity === "fail")).toBe(true);
+    expect(formatChanges(fail.doc)).toContain("error     commit-unlinked");
+    const off = await check("off");
+    expect(off.failed).toBe(false);
+    expect(off.doc.links!.findings).toEqual([]);
+    expect(off.doc.links!.commits).toHaveLength(8);
+  });
+
+  test("a range whose commits all name a work item has no finding", async () => {
+    const { doc } = await checkChanges({ cwd: root, range: `${sha.c0}..${sha.c2}` });
+    changes.expectValid(doc);
+    expect((doc as Result).links!.findings).toEqual([]);
+  });
+});
+
+describe("ci list and ci tick (#4029)", () => {
+  test("ci list --json marks each commit with its link, and merges as merge", async () => {
+    const doc = (await ciList({ cwd: root, now: NOW })) as Listed;
+    list.expectValid(doc);
+    const byCommit = Object.fromEntries(doc.commits.map((c) => [c.sha, c.work]));
+    expect(byCommit[sha.c1]).toEqual({ state: "linked", ids: ["work:W-001"], problems: [] });
+    expect(byCommit[sha.c2]).toMatchObject({ state: "linked", ids: ["work:W-002"] });
+    expect(byCommit[sha.c3]).toEqual({ state: "unlinked", ids: [], problems: [] });
+    expect(byCommit[sha.c4]).toMatchObject({ state: "wrong" });
+    expect(byCommit[sha.m]).toEqual({ state: "merge", ids: [], problems: [] });
+  });
+
+  test("ci list text gives the reason a commit's work item is unknown", async () => {
+    const doc = (await ciList({ cwd: root, now: NOW })) as Listed;
+    const text = formatList(doc).split("\n");
+    const line = (s: string) => text.find((l) => l.includes(s.slice(0, 12)))!;
+    expect(line(sha.c3)).toContain("; why unknown: no Chant-Record or Chant-Lease trailer names a work item");
+    expect(line(sha.c4)).toContain("; why unknown: the work item named is not there: Chant-Record: work:W-999");
+    expect(line(sha.c1)).not.toContain("why unknown");
+    expect(line(sha.m)).not.toContain("why unknown");
+  });
+
+  test("the field is null where the workspace declares no work kind", async () => {
+    const plain = scratchDir("chant-links-plain-");
+    git(plain, "init", "-q");
+    git(plain, "symbolic-ref", "HEAD", "refs/heads/main");
+    writeFiles(plain, {
+      "chant.workspace.json": JSON.stringify({ name: "plain", schema: 1, members: [{ name: "app", dir: "app", kind: "other", because: "x" }], ci: { green: { branch: "main", phases: { lint: ["lint"] }, require: ["lint"] } } }),
+      "app/a.txt": "a\n",
+    });
+    git(plain, "add", "-A");
+    git(plain, "-c", "user.name=t", "-c", "user.email=t@example.com", "commit", "-q", "-m", "one");
+    const doc = (await ciList({ cwd: plain })) as Listed;
+    list.expectValid(doc);
+    expect(doc.commits.map((c) => c.work)).toEqual([null]);
+    expect(formatList(doc)).not.toContain("why unknown");
+  });
+
+  test("ci tick shows an unlinked commit with why unknown", async () => {
+    origin = scratchDir("chant-links-origin-");
+    git(origin, "init", "-q", "--bare");
+    git(root, "remote", "add", "origin", origin);
+    git(root, "push", "-q", "origin", "main");
+    const forge: CiForge = { kind: "github", checkRuns: async () => [] };
+    const result = await ciTick({ cwd: root, forge, now: NOW, dryRun: true });
+    const text = formatTick(result, true);
+    const line = (s: string) => text.split("\n").find((l) => l.includes(s.slice(0, 12)))!;
+    expect(line(sha.c3)).toMatch(/undecided: lint; why unknown: no Chant-Record or Chant-Lease trailer names a work item/);
+    expect(line(sha.c1)).not.toContain("why unknown");
+  });
+
+  test("whyWorkUnknown names nothing for a linked commit, a merge or no field", () => {
+    expect(whyWorkUnknown(null)).toBeUndefined();
+    expect(whyWorkUnknown(undefined)).toBeUndefined();
+    expect(whyWorkUnknown({ state: "linked", ids: ["work:W-1"], problems: [] })).toBeUndefined();
+    expect(whyWorkUnknown({ state: "merge", ids: [], problems: [] })).toBeUndefined();
+  });
+});

package/src/workspace/commit-links.ts

@@ -0,0 +1,183 @@
+/**
+ * Which work item a commit belongs to (#4029).
+ *
+ * A work item implements a decision, and a trunk commit says which work item
+ * it carries out in one of two ways:
+ *
+ * - a `Chant-Record: <kind>:<id>` trailer, where `<kind>` is a work kind the
+ *   declaration names (conventionally `work`) and the kind has a record `<id>`;
+ * - a `Chant-Lease` trailer whose token a lease history on `chant/lifecycle`
+ *   names a work item for, and that item is a record of a work kind.
+ *
+ * A window match (the intent graph's `worked` bucket) does not link a commit:
+ * the commit never said so itself. A commit is wrongly linked when it names a
+ * work record that does not exist, a record of a kind that is not a work
+ * kind, a lease that resolves to nothing, or a `Chant-Record` value that is
+ * not `<kind>:<id>`, and no trailer of it links to a work item.
+ *
+ * This is the one place that judgement is made. `workspace check --changes`
+ * reports it, `ci list` and `ci tick` show it, and later readers share
+ * {@link judgeCommitLink}. It reads trailers through `readTrailerJoins`,
+ * which `graph --intent` joins commits with, so both resolve a Chant-Record
+ * and a Chant-Lease the same way. Everything here reads local git.
+ */
+
+import { execFileSync } from "node:child_process";
+import { declaredRecordKinds, readDeclaration, WorkspaceReadError } from "./declaration";
+import { declaredKindFile } from "./declared-kinds";
+import { trailerValues } from "./intent-joins";
+import { commitDetails } from "./intent";
+import { loadRecordKind, RecordReadError } from "./records";
+import { readRecordsFor } from "./records-cli";
+import { readTrailerJoins } from "./trailer-joins";
+import { parseRecordRef, RECORD_TRAILER, LEASE_TRAILER } from "./trailers";
+import { locateWorkspace } from "./which-chant";
+
+/** `linked`, `unlinked` (no trailer names a work item), `wrong` (trailers name one that is not there), or `merge` (a merge commit carries no work of its own). */
+export type CommitLinkState = "linked" | "unlinked" | "wrong" | "merge";
+
+/** One trailer that does not link the commit, with why. */
+export interface CommitLinkProblem {
+  /** The trailer as written, such as `Chant-Record: decision:ws-075`. */
+  trailer: string;
+  message: string;
+}
+
+/** What {@link judgeCommitLink} says about one commit. */
+export interface CommitLink {
+  state: CommitLinkState;
+  /** The work records the commit's trailers name, as `<kind>:<id>`. Empty unless `linked`; also empty for a lease that could not be checked. */
+  ids: string[];
+  /** The trailers that do not link. Empty unless `wrong`. */
+  problems: CommitLinkProblem[];
+}
+
+/** The work records a revision has, by work kind. */
+export interface WorkIndex {
+  /** Each work kind's name, with the ids of its records. */
+  kinds: Map<string, Set<string>>;
+  /** Whether lease histories can be read: the local `chant/lifecycle` branch exists. Without it a lease is not judged. */
+  ledger: boolean;
+}
+
+/** The fix line for each state a check reports. */
+export const COMMIT_UNLINKED_FIX = "add a `Chant-Record: work:<id>` trailer when the commit is made (git commit --trailer \"Chant-Record: work:<id>\"), naming the work item the commit carries out";
+
+function workKindList(index: WorkIndex): string {
+  return [...index.kinds.keys()].join(", ") || "none";
+}
+
+/**
+ * Judge one commit from its trailers.
+ *
+ * `trailers` are the commit's parsed trailers, `joins` what
+ * `readTrailerJoins` made of them, and `index` the work records of the
+ * revision judged against. A commit is `linked` when any trailer names a
+ * work record; another trailer that names a decision or a typo beside it
+ * does not make it wrong.
+ */
+export function judgeCommitLink(trailers: Record<string, string[]>, joins: { records: { kind: string; id: string }[]; lease: { token: string; item: string | null } | null }, index: WorkIndex): CommitLink {
+  const ids: string[] = [];
+  const problems: CommitLinkProblem[] = [];
+  let unchecked = false;
+  const add = (id: string) => {
+    if (!ids.includes(id)) ids.push(id);
+  };
+  for (const value of trailerValues(trailers, RECORD_TRAILER)) {
+    const trailer = `${RECORD_TRAILER}: ${value}`;
+    const ref = parseRecordRef(value);
+    if (!ref) {
+      problems.push({ trailer, message: `${value} is not <kind>:<id>` });
+      continue;
+    }
+    const known = index.kinds.get(ref.kind);
+    if (!known) problems.push({ trailer, message: `${ref.kind} is not a work kind (the work kinds are ${workKindList(index)})` });
+    else if (!known.has(ref.id)) problems.push({ trailer, message: `the ${ref.kind} kind has no record ${ref.id}` });
+    else add(`${ref.kind}:${ref.id}`);
+  }
+  if (joins.lease) {
+    const trailer = `${LEASE_TRAILER}: ${joins.lease.token}`;
+    const item = joins.lease.item;
+    if (item === null) {
+      if (index.ledger) problems.push({ trailer, message: "no lease history on chant/lifecycle names this token" });
+      else unchecked = true;
+    } else {
+      const hits = [...index.kinds].filter(([, found]) => found.has(item)).map(([kind]) => kind);
+      if (hits.length === 1) add(`${hits[0]}:${item}`);
+      else problems.push({ trailer, message: hits.length === 0 ? `the lease was taken on ${item}, which no work kind has a record for` : `the lease was taken on ${item}, which ${hits.join(" and ")} both have, so it names no one work item` });
+    }
+  }
+  if (ids.length > 0 || unchecked) return { state: "linked", ids, problems: [] };
+  return problems.length > 0 ? { state: "wrong", ids: [], problems } : { state: "unlinked", ids: [], problems: [] };
+}
+
+/**
+ * Judge each commit by its own trailers. A commit in `merges` is `merge`:
+ * its work is the commits it brings. Reads the lease histories on the local
+ * `chant/lifecycle` branch once, and never fetches.
+ */
+export function judgeCommits(top: string, shas: string[], index: WorkIndex, merges: ReadonlySet<string> = new Set()): Map<string, CommitLink> {
+  const details = commitDetails(top, shas);
+  const joined = readTrailerJoins(
+    top,
+    shas.map((sha) => ({ sha, trailers: details.get(sha)?.trailers ?? {} })),
+  );
+  const out = new Map<string, CommitLink>();
+  for (const sha of shas) {
+    if (merges.has(sha)) {
+      out.set(sha, { state: "merge", ids: [], problems: [] });
+      continue;
+    }
+    out.set(sha, judgeCommitLink(details.get(sha)?.trailers ?? {}, joined.get(sha)!.joins, index));
+  }
+  return out;
+}
+
+/** Whether the lease histories can be read from this repository: the local `chant/lifecycle` branch exists. */
+export function hasLeaseLedger(top: string): boolean {
+  try {
+    execFileSync("git", ["rev-parse", "--verify", "--quiet", "refs/heads/chant/lifecycle"], { cwd: top, stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Which of `shas` are merge commits. */
+export function mergeCommits(top: string, shas: string[]): Set<string> {
+  const out = new Set<string>();
+  if (shas.length === 0) return out;
+  const text = execFileSync("git", ["log", "--no-walk=unsorted", "--stdin", "--format=%H %P"], { cwd: top, encoding: "utf-8", input: `${shas.join("\n")}\n`, maxBuffer: 256 * 1024 * 1024 });
+  for (const line of text.split("\n")) {
+    const [sha, ...parents] = line.trim().split(" ");
+    if (sha && parents.length > 1) out.add(sha);
+  }
+  return out;
+}
+
+/**
+ * The work records the declaration's work kinds hold at `at` (a revision, or
+ * the working tree without one). Null when `cwd` is in no workspace, the
+ * declaration names no work kind, or a kind can't be read: the question
+ * "which work item" has no answer there.
+ */
+export async function readWorkIndex(cwd: string, top: string, at?: string): Promise<WorkIndex | null> {
+  try {
+    const located = locateWorkspace(cwd, at);
+    const declaration = readDeclaration(located.tree);
+    const kinds = new Map<string, Set<string>>();
+    for (const d of declaredRecordKinds(declaration)) {
+      const file = declaredKindFile(d, located.rootOnDisk);
+      const loaded = await loadRecordKind(file, cwd);
+      if (!loaded.kind.work) continue;
+      const read = await readRecordsFor({ kind: file, cwd, ...(at !== undefined ? { at } : {}) });
+      const ids = (kinds.get(loaded.kind.name) ?? new Set<string>());
+      for (const r of read.result.records) if (r.id !== null) ids.add(r.id);
+      kinds.set(loaded.kind.name, ids);
+    }
+    return kinds.size === 0 ? null : { kinds, ledger: hasLeaseLedger(top) };
+  } catch (err) {
+    if (err instanceof WorkspaceReadError || err instanceof RecordReadError) return null;
+    throw err;
+  }
+}

package/src/workspace/declaration.schema.json

@@ -179,6 +179,58 @@
           "$ref": "#/$defs/ciGreen"
         }
       }
+    },
+    "retention": {
+      "type": "object",
+      "additionalProperties": false,
+      "patternProperties": {
+        "^x-": true
+      },
+      "description": "How long chant lifecycle gc keeps each kind of stored record (#4036). A kind or field left out keeps its default: changeSets 14 days; releases 14 days and the newest 10 of each member; runEvents 14 days and the newest 100. Whatever the policy, gc never prunes a release an environment runs, what a pending gate binds, or a change set a gate names with a kept release. Read from the declaration at base. Added in schema 1 by chant 0.124.29, so a declaration that uses it sets minReader to 0.124.29 or newer.",
+      "properties": {
+        "changeSets": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "Stored change sets, _change-sets/<digest>.json on chant/lifecycle.",
+          "properties": {
+            "days": { "$ref": "#/$defs/retentionDays" }
+          }
+        },
+        "releases": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "Releases, _releases/<digest>.json on chant/lifecycle, with the template bytes only they name. A release stays promotable for days after its newest cut, and the newest keep releases of each member stay promotable at any age, unless their commit is revoked.",
+          "properties": {
+            "days": { "$ref": "#/$defs/retentionDays" },
+            "keep": { "$ref": "#/$defs/retentionKeep" }
+          }
+        },
+        "runEvents": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "Run event files, <git-common-dir>/chant/run-events/<run>.jsonl on each host. A file is kept for days after its last write, and the newest keep files at any age.",
+          "properties": {
+            "days": { "$ref": "#/$defs/retentionDays" },
+            "keep": { "$ref": "#/$defs/retentionKeep" }
+          }
+        }
+      }
+    },
+    "metrics": {
+      "type": "object",
+      "additionalProperties": false,
+      "patternProperties": {
+        "^x-": true
+      },
+      "description": "How chant workspace metrics counts the DORA metrics (#4039). Added in schema 1 by chant 0.124.29, so a declaration that uses it sets minReader to 0.124.29 or newer.",
+      "properties": {
+        "failureWindowDays": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 365,
+          "description": "A deploy counts as failed when, within this many days after it, the commit it deployed is revoked or the environment is rolled back from it. The default is 7."
+        }
+      }
     }
   },
   "patternProperties": {
@@ -186,6 +238,18 @@
   },
   "additionalProperties": false,
   "$defs": {
+    "retentionDays": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 36500,
+      "description": "Days a record is kept past its last write or use. 0 lets every record go that no never-prune rule keeps."
+    },
+    "retentionKeep": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 100000,
+      "description": "How many of the newest are kept at any age."
+    },
     "name": {
       "type": "string",
       "pattern": "^[a-z0-9][a-z0-9-]{0,39}$",
@@ -1450,6 +1514,18 @@
           "items": {
             "$ref": "#/$defs/ciPhaseName"
           }
+        },
+        "signedSince": {
+          "type": "string",
+          "pattern": "^[0-9a-f]{40}([0-9a-f]{24})?$",
+          "description": "Added by #4031, read by chant 0.124.28 and newer. The full sha of the first commit on branch whose ci/green and ci/revoked tags must carry a DSSE statement in their annotation, signed by a key .chant/trust.json at base lists under runners for a principal holding the runner role. A tag on a strict first-parent ancestor of this commit counts unsigned, so existing tags keep working; a tag on any other commit, this one included, needs a statement. Position in history decides, never a date, which whoever makes a commit or a tag sets. A reader refuses a sha that names no commit in its clone with declaration-invalid. Absent, no tag needs a statement."
+        },
+        "source": {
+          "enum": [
+            "checks",
+            "runs"
+          ],
+          "description": "Added by #4044, read by chant 0.124.28 and newer, so a declaration that sets it sets minReader to 0.124.28 or newer. Where chant ci tick reads each phase's results. checks (the default): the forge's check runs, whose names the phases' patterns match. runs: chant's own Op runs, read from the run ledger on chant/lifecycle, for a project whose pipelines run as chant Ops, such as one on GitLab or Forgejo. A phase's patterns then match Op names, a run counts for the commit its record names as gitSha, and the latest run of each Op decides. A run counts only when its record carries a statement signed by a key .chant/trust.json at base lists under runners for a principal holding the runner role; the tick ignores and reports any other. A tick from runs signs every tag it makes, so it needs a runner key."
         }
       },
       "patternProperties": {

package/src/workspace/declaration.test.ts

@@ -421,3 +421,31 @@ describe("diagram artifacts (#2764)", () => {
     expect(failure(base([member([diagram({ render: "../out.svg" })])])).code).toBe("declaration-invalid");
   });
 });
+
+describe("retention (#4036)", () => {
+  test("the block is read as written, without x- keys, and is null when absent", () => {
+    expect(parse(base([])).retention).toBeNull();
+    const d = parse(base([], { minReader: "0.80.0", retention: { changeSets: { days: 30 }, releases: { keep: 3 }, runEvents: { days: 2, keep: 5 }, "x-why": "audits" } }));
+    expect(d.retention).toEqual({ changeSets: { days: 30 }, releases: { keep: 3 }, runEvents: { days: 2, keep: 5 } });
+  });
+
+  test("an unknown kind or field, a negative or fractional number, and keep on changeSets are refused", () => {
+    for (const retention of [{ plans: { days: 1 } }, { releases: { days: -1 } }, { releases: { days: 1.5 } }, { changeSets: { keep: 2 } }, { runEvents: { hours: 2 } }]) {
+      expect(failure(base([], { retention })).code).toBe("declaration-invalid");
+    }
+  });
+});
+
+describe("metrics (#4039)", () => {
+  test("failureWindowDays is read as written, without x- keys, and the block is null when absent", () => {
+    expect(parse(base([])).metrics).toBeNull();
+    expect(parse(base([], { minReader: "0.80.0", metrics: { failureWindowDays: 14, "x-why": "weekly" } })).metrics).toEqual({ failureWindowDays: 14 });
+    expect(parse(base([], { metrics: {} })).metrics).toEqual({});
+  });
+
+  test("an unknown field, 0, a fraction and more than a year are refused", () => {
+    for (const metrics of [{ window: 7 }, { failureWindowDays: 0 }, { failureWindowDays: 1.5 }, { failureWindowDays: 366 }]) {
+      expect(failure(base([], { metrics })).code).toBe("declaration-invalid");
+    }
+  });
+});