@intentius/chant 0.95.1 → 0.96.0

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

@@ -0,0 +1,257 @@
+/**
+ * The commit that decided a record, and the intent walk for one record, on a
+ * workspace shaped like the studio's: a root member, a smoke member with a
+ * member nested in it, a docs member, decisions that constrain a member and a
+ * file at once, a work item, and a plugin that joins commits to units.
+ *
+ * - c0 adds the workspace, smoke/run.sh, docs/claims.md and s-001, proposed,
+ *   which constrains member:smoke and path:docs/claims.md, and s-004,
+ *   proposed, which constrains the root member.
+ * - c1 edits docs/claims.md while s-001 is proposed.
+ * - c2 decides s-001: its window opens here.
+ * - c3 edits smoke/run.sh from unit U-0001, whose record names s-001: own work.
+ * - c4 adds W-001, open and implementing s-001, and edits smoke/lib.sh: worked.
+ * - c5 closes W-001 and adds s-002, decided, which constrains path:docs.
+ * - c6 edits docs/claims.md: inside s-002's window too.
+ * - c7 edits README.md, in the root member: outside s-001's region.
+ * - c8 edits smoke/run.sh with nothing to account for it.
+ * - c9 adds s-003, which supersedes s-001: s-001's window closes here.
+ * - c10 edits smoke/run.sh after the window.
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { cleanScratch, contract, git, REPO, repo, writeFiles } from "./__fixtures__/contract-repo";
+import { intentGraph, type CommitNode, type DecisionNode } from "./intent";
+import { formatIntentRecord } from "./intent-cli";
+import { intentRecord, type IntentRecordDocument } from "./intent-record";
+import intentRecordSchema from "./intent-record.schema.json";
+import intentSchema from "./intent.schema.json";
+import { parseFrontMatter } from "./records";
+import { queryRecords } from "./records-cli";
+import recordsSchema from "./records.schema.json";
+
+const REF = join(REPO, "reference-workspace");
+const BASE = (() => {
+  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;
+})();
+
+function decision(id: string, fields: Record<string, unknown>): string {
+  const data = { ...BASE, id, title: `Decision ${id}`, state: "decided", supersedes: [], evidence: [], reviews: [], ...fields };
+  return `---\n${JSON.stringify(data, null, 2)}\n---\n\n# ${id}\n`;
+}
+
+function work(id: string, fields: Record<string, unknown>): string {
+  const data = { schema: 1, id, title: `Work ${id}`, state: "open", implements: [], needs: [], constrains: [], evidence: [], opened_on: "2026-09-24", supersedes: [], ...fields };
+  return `---\n${JSON.stringify(data, null, 2)}\n---\n\n# ${id}\n\nWhat the work is.\n`;
+}
+
+const PLUGIN = `
+export function commitJoins(commit, context) {
+  const id = commit.trailers["Unit"]?.[0];
+  if (!id) return undefined;
+  const unit = JSON.parse(context.read(\`units/\${id}.json\`));
+  return { unit: { id, decisions: unit.decisions }, contract: { id: unit.contract } };
+}
+`;
+
+const S001 = { constrains: ["member:smoke", "path:docs/claims.md"] };
+
+let root: string;
+const sha: Record<string, string> = {};
+let tick = 0;
+
+function commit(message: string[]): string {
+  // One second apart, so commit dates order the history.
+  const date = `2026-09-26T12: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");
+}
+
+const KINDS = ["decisions/decision.kind.mjs", "work/work.kind.mjs", "plugins/units.kind.mjs"];
+
+beforeAll(() => {
+  root = repo({
+    "chant.workspace.json": JSON.stringify({
+      name: "studio",
+      schema: 1,
+      members: [
+        { name: "studio", dir: ".", kind: "other", because: "the repo itself" },
+        { name: "smoke", dir: "smoke", kind: "other", because: "the smoke test" },
+        { name: "docs", dir: "docs", kind: "other", because: "prose" },
+      ],
+    }),
+    "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"),
+    "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"),
+    "plugins/units.kind.mjs": PLUGIN,
+    "units/U-0001.json": JSON.stringify({ contract: "C-001", decisions: ["s-001"] }),
+    "README.md": "The studio.\n",
+    "smoke/run.sh": "echo run\n",
+    "docs/claims.md": "# Claims\n",
+    "decisions/s-001-smoke.md": decision("s-001", { ...S001, state: "proposed" }),
+    "decisions/s-004-root.md": decision("s-004", { constrains: ["member:studio"], state: "proposed" }),
+  });
+  sha.c0 = commit(["the workspace, and s-001 proposed"]);
+  writeFiles(root, { "docs/claims.md": "# Claims\n\nOne.\n" });
+  sha.c1 = commit(["a claim while s-001 is proposed"]);
+  writeFiles(root, { "decisions/s-001-smoke.md": decision("s-001", S001) });
+  sha.c2 = commit(["decide s-001"]);
+  writeFiles(root, { "smoke/run.sh": "echo run twice\n" });
+  sha.c3 = commit(["run twice", "Unit: U-0001"]);
+  writeFiles(root, { "work/W-001-lib.md": work("W-001", { implements: ["s-001"] }), "smoke/lib.sh": "echo lib\n" });
+  sha.c4 = commit(["W-001 and the lib"]);
+  writeFiles(root, {
+    "work/W-001-lib.md": work("W-001", { implements: ["s-001"], state: "done", closed_on: "2026-09-26", evidence: [{ title: "The run", url: "https://example.com/run" }] }),
+    "decisions/s-002-docs.md": decision("s-002", { constrains: ["path:docs"] }),
+  });
+  sha.c5 = commit(["W-001 done, and s-002 for the docs"]);
+  writeFiles(root, { "docs/claims.md": "# Claims\n\nOne.\nTwo.\n" });
+  sha.c6 = commit(["a second claim"]);
+  writeFiles(root, { "README.md": "The studio, again.\n" });
+  sha.c7 = commit(["the readme"]);
+  writeFiles(root, { "smoke/run.sh": "echo run three times\n" });
+  sha.c8 = commit(["run three times"]);
+  writeFiles(root, { "decisions/s-003-smoke.md": decision("s-003", { ...S001, supersedes: [{ decision: "s-001" }] }) });
+  sha.c9 = commit(["s-003 supersedes s-001"]);
+  writeFiles(root, { "smoke/run.sh": "echo run four times\n" });
+  sha.c10 = commit(["run four times"]);
+});
+afterAll(cleanScratch);
+
+const recordContract = contract(intentRecordSchema);
+type RecordResult = Exclude<IntentRecordDocument, { error: unknown }>;
+
+async function walkRecord(record: string, options: { kinds?: string[]; at?: string } = {}): Promise<RecordResult> {
+  const { doc } = await intentRecord({ cwd: root, record, at: options.at, kinds: (options.kinds ?? KINDS).map((k) => join(root, k)) });
+  recordContract.expectValid(doc);
+  if ("error" in doc) throw new Error(`${doc.error.code}: ${doc.error.message}`);
+  return doc;
+}
+
+describe("the commit that decided a record", () => {
+  test("records --json names it: the commit that moved the record into an approved state, not the one that added it", async () => {
+    const doc = await queryRecords({ kind: join(root, "decisions/decision.kind.mjs"), cwd: root });
+    contract(recordsSchema).expectValid(doc);
+    if ("error" in doc) throw new Error(doc.error.message);
+    const decided = Object.fromEntries(doc.records.map((r) => [r.id, r.decidedIn?.sha ?? null]));
+    expect(decided).toEqual({ "s-001": sha.c2, "s-002": sha.c5, "s-003": sha.c9, "s-004": null });
+    expect(doc.records.find((r) => r.id === "s-001")!.decidedIn).toEqual({ sha: sha.c2, date: "2026-09-26T12:00:02Z", subject: "decide s-001" });
+  });
+
+  test("a proposed record, or one read before it was decided, has none; a work kind carries no decidedIn", async () => {
+    const before = await queryRecords({ kind: join(root, "decisions/decision.kind.mjs"), cwd: root, at: sha.c1 });
+    if ("error" in before) throw new Error(before.error.message);
+    expect(before.records.map((r) => [r.id, r.decidedIn])).toEqual([
+      ["s-001", null],
+      ["s-004", null],
+    ]);
+    const w = await queryRecords({ kind: join(root, "work/work.kind.mjs"), cwd: root });
+    if ("error" in w) throw new Error(w.error.message);
+    expect(w.records.every((r) => !("decidedIn" in r))).toBe(true);
+  });
+
+  test("graph --intent carries it on the decision node, and the window opens there: the edit made while s-001 was proposed is outside it", async () => {
+    const { doc } = await intentGraph({ cwd: root, region: "docs/claims.md", kinds: KINDS.map((k) => join(root, k)) });
+    contract(intentSchema).expectValid(doc);
+    if ("error" in doc) throw new Error(doc.error.message);
+    const s001 = doc.nodes.find((n): n is DecisionNode => n.kind === "decision" && n.record === "s-001")!;
+    expect(s001.decidedIn).toEqual({ sha: sha.c2, date: "2026-09-26T12:00:02Z", subject: "decide s-001" });
+    const state = (s: string) => doc.nodes.find((n): n is CommitNode => n.kind === "commit" && n.sha === s)!.state;
+    expect(state(sha.c1)).toBe("undecided");
+    expect(state(sha.c6)).toBe("decided-by-window");
+    expect(doc.edges.filter((e) => e.kind === "within" && e.from === `commit:${sha.c6}`).map((e) => e.to)).toEqual(["record:decision/s-001", "record:decision/s-002"]);
+  });
+});
+
+describe("graph --intent --record", () => {
+  test("walks every path and member entry once, keeps the commits in the window, and buckets each against the record", async () => {
+    const doc = await walkRecord("s-001");
+    expect(doc.record).toEqual({
+      id: "record:decision/s-001",
+      recordKind: "decision",
+      record: "s-001",
+      path: "decisions/s-001-smoke.md",
+      title: "Decision s-001",
+      state: "decided",
+      supersededBy: "s-003",
+      decidedIn: { sha: sha.c2, date: "2026-09-26T12:00:02Z", subject: "decide s-001" },
+      constrains: [
+        { entry: "member:smoke", granularity: "member", path: "smoke", exists: true, walked: true },
+        { entry: "path:docs/claims.md", granularity: "path", path: "docs/claims.md", exists: true, walked: true },
+      ],
+    });
+    expect(doc.window).toEqual({ from: sha.c2, until: sha.c9 });
+    expect(doc.commits.map((c) => [c.sha, c.bucket, c.files, c.entries])).toEqual([
+      [sha.c8, "unexplained", ["smoke/run.sh"], ["member:smoke"]],
+      [sha.c6, "within-other", ["docs/claims.md"], ["path:docs/claims.md"]],
+      [sha.c4, "worked", ["smoke/lib.sh"], ["member:smoke"]],
+      [sha.c3, "own", ["smoke/run.sh"], ["member:smoke"]],
+    ]);
+    const by = Object.fromEntries(doc.commits.map((c) => [c.sha, { unit: c.unit, workedBy: c.workedBy, alsoWithin: c.alsoWithin }]));
+    expect(by[sha.c3]).toEqual({ unit: "U-0001", workedBy: [], alsoWithin: [] });
+    expect(by[sha.c4]).toEqual({ unit: null, workedBy: [{ recordKind: "work", record: "W-001", state: "done" }], alsoWithin: [] });
+    expect(by[sha.c6]).toEqual({ unit: null, workedBy: [], alsoWithin: [{ recordKind: "decision", record: "s-002", state: "decided" }] });
+    // c0, c1 and c10 changed the region outside the window; c7 changed only the root member.
+    expect(doc.counts).toEqual({ commits: 4, own: 1, worked: 1, withinOther: 1, unexplained: 1, outsideWindow: 3 });
+    expect(doc.reasons).toEqual([]);
+  });
+
+  test("the text walk prints the record, its window, each commit with its bucket, and the counts", async () => {
+    const text = formatIntentRecord(await walkRecord("decision/s-001"));
+    expect(text.split("\n")[0]).toBe("record    s-001 decided, superseded by s-003: Decision s-001");
+    expect(text).toContain(`window    from ${sha.c2.slice(0, 8)} until ${sha.c9.slice(0, 8)}; decided in ${sha.c2.slice(0, 8)}`);
+    expect(text).toContain(`own          ${sha.c3.slice(0, 8)} 2026-09-26 run twice; unit U-0001; smoke/run.sh`);
+    expect(text).toContain(`worked       ${sha.c4.slice(0, 8)} 2026-09-26 W-001 and the lib; worked by W-001; smoke/lib.sh`);
+    expect(text).toContain(`within-other ${sha.c6.slice(0, 8)} 2026-09-26 a second claim; within s-002; docs/claims.md`);
+    expect(text.split("\n").at(-1)).toBe("4 commits in the window: 1 own, 1 worked, 1 within another record's window, 1 unexplained; 3 outside it");
+  });
+
+  test("a current record's window runs to the revision read; --at reads the history as it was", async () => {
+    const s003 = await walkRecord("s-003");
+    expect(s003.window).toEqual({ from: sha.c9, until: null });
+    expect(s003.commits.map((c) => [c.sha, c.bucket])).toEqual([[sha.c10, "unexplained"]]);
+    const early = await walkRecord("s-001", { at: sha.c4 });
+    expect(early.window).toEqual({ from: sha.c2, until: null });
+    expect(early.commits.map((c) => [c.sha, c.bucket])).toEqual([
+      [sha.c4, "worked"],
+      [sha.c3, "own"],
+    ]);
+  });
+
+  test("the root member's history leaves out the members inside it, and a proposed record's window opens where it was added", async () => {
+    const doc = await walkRecord("s-004");
+    expect(doc.record.decidedIn).toBeNull();
+    expect(doc.window).toEqual({ from: sha.c0, until: null });
+    expect(doc.commits.map((c) => c.sha)).toEqual([sha.c9, sha.c7, sha.c5, sha.c4, sha.c2, sha.c0]);
+    expect(doc.commits.flatMap((c) => c.files).filter((f) => f.startsWith("smoke/") || f.startsWith("docs/"))).toEqual([]);
+    expect(doc.commits.find((c) => c.sha === sha.c7)!.files).toEqual(["README.md"]);
+  });
+
+  test("without the plugin nothing joins c3 to a unit, so it is unexplained; without the work kind c4 is too", async () => {
+    const doc = await walkRecord("s-001", { kinds: ["decisions/decision.kind.mjs"] });
+    expect(doc.commits.map((c) => c.bucket)).toEqual(["unexplained", "within-other", "unexplained", "unexplained"]);
+    expect(doc.counts).toMatchObject({ own: 0, worked: 0, withinOther: 1, unexplained: 3 });
+  });
+
+  test("an id no decision has is intent-record-unknown, and so is a work item's", async () => {
+    for (const id of ["s-404", "W-001"]) {
+      const { doc, failed } = await intentRecord({ cwd: root, record: id, kinds: KINDS.map((k) => join(root, k)) });
+      recordContract.expectValid(doc);
+      expect(failed).toBe(true);
+      expect("error" in doc && doc.error.code).toBe("intent-record-unknown");
+    }
+  });
+});

package/src/workspace/intent-record.ts

@@ -0,0 +1,371 @@
+/**
+ * The intent walk for one record: `chant workspace graph --intent --record
+ * <id>`.
+ *
+ * `graph --intent <path>` answers for one region. A decision's `constrains`
+ * may list several `path:` and `member:` entries, and a reader drawing the
+ * decision's drift wants every commit that changed any of them while the
+ * decision stood. This walk reads the history of each entry the way the
+ * region walk does (`git log --follow` for a file, `git log` for a
+ * directory, and for a member, its directory less the members nested in it),
+ * keeps each commit once, and keeps the commits inside the record's window:
+ * from the commit that decided it, or added it when it is not approved
+ * (`record-decided.ts`), until the commit that opened the window of the
+ * record superseding it.
+ *
+ * Each commit gets one bucket, relative to this record, in this order:
+ *
+ * - `own`: the record's own work, as the region walk judges it: a commit a
+ *   plugin joins to a unit whose unit or contract names the record, or that
+ *   serves a contract the record constrains.
+ * - `worked`: inside the window of a work item that is not dropped and that
+ *   implements the record, or whose `path:` entries cover a file the commit
+ *   changed in the record's region.
+ * - `within-other`: inside the window of another decision whose `path:`
+ *   entries cover a file the commit changed in the record's region.
+ * - `unexplained`: none of these.
+ *
+ * `workedBy` and `alsoWithin` list every work item and other decision that
+ * matched, whatever the bucket. `issue` and `contract` entries are listed and
+ * not walked: they name no path. Git is read through a local `git`
+ * subprocess only: no fetch, no network.
+ */
+
+import { declaredRecordKinds, readDeclaration, readerVersion, WorkspaceReadError } from "./declaration";
+import { declaredKindFile } from "./declared-kinds";
+import { entityDecisions, runCommitJoins } from "./intent-joins";
+import {
+  addingCommit,
+  closingCommit,
+  commitDetails,
+  descendants,
+  IntentError,
+  loadKinds,
+  regionHistory,
+  tryGit,
+  windowOpening,
+  type IntentErrorCode,
+  type IntentReason,
+  type LoadedKind,
+} from "./intent";
+import { constraintCovers, isWorkspacePath, memberHolding } from "./record-assets";
+import type { DecidedIn } from "./record-decided";
+import { RecordReadError } from "./records";
+import type { RecordView } from "./records-cli";
+import { joinPath } from "./tree";
+import { locateWorkspace } from "./which-chant";
+import { idList } from "./work";
+
+/** The version of the `intent-record` document this chant writes. */
+export const INTENT_RECORD_CONTRACT_VERSION = 1;
+
+/** `$id` of the JSON Schema for the document, shipped beside this file. */
+export const INTENT_RECORD_OUTPUT_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace/intent-record/v1/intent-record.schema.json";
+
+export const INTENT_RECORD_BUCKETS = ["own", "worked", "within-other", "unexplained"] as const;
+export type IntentRecordBucket = (typeof INTENT_RECORD_BUCKETS)[number];
+
+export interface RecordConstraint {
+  entry: string;
+  granularity: "path" | "member" | "contract" | "issue";
+  /** For a path entry, from the workspace root; for a member entry, the member's directory. Null otherwise. */
+  path: string | null;
+  /** For a path entry, whether the path is in the tree read; for a member entry, whether the declaration names the member. Null for an entry that is not walked. */
+  exists: boolean | null;
+  /** Whether its history was read. */
+  walked: boolean;
+}
+
+export interface RecordRef {
+  recordKind: string;
+  record: string;
+  state: string | null;
+}
+
+export interface RecordCommit {
+  sha: string;
+  subject: string;
+  author: { name: string; email: string };
+  date: string;
+  trailers: Record<string, string[]>;
+  pullRequest: number | null;
+  /** The unit a plugin joined the commit to, or null. */
+  unit: string | null;
+  /** The record's constrains entries whose history listed the commit. */
+  entries: string[];
+  /** The files the commit changed in the record's region, from the workspace root. Empty when git lists none, as for a merge that changed nothing against its first parent there. */
+  files: string[];
+  bucket: IntentRecordBucket;
+  /** Every work item whose window holds the commit and that implements the record or covers one of its files by path. */
+  workedBy: RecordRef[];
+  /** Every other decision whose window holds the commit and whose path entries cover one of its files. */
+  alsoWithin: RecordRef[];
+}
+
+interface Head {
+  $schema: string;
+  contract: number;
+  chant: string;
+}
+
+export type IntentRecordDocument =
+  | (Head & {
+      at: string | null;
+      workspace: { name: string; root: string };
+      record: {
+        id: string;
+        recordKind: string;
+        record: string;
+        path: string;
+        title: string | null;
+        state: string | null;
+        supersededBy: string | null;
+        decidedIn: DecidedIn | null;
+        constrains: RecordConstraint[];
+      };
+      history: { rev: string | null; shallow: boolean };
+      /** The commit the window opens at, and the one it closes at (the superseding record's opening), or null. */
+      window: { from: string | null; until: string | null };
+      kinds: { file: string; name: string; records: string | null; joins: "function" | "data" | null }[];
+      commits: RecordCommit[];
+      counts: { commits: number; own: number; worked: number; withinOther: number; unexplained: number; outsideWindow: number };
+      reasons: IntentReason[];
+    })
+  | (Head & { error: { code: IntentErrorCode; message: string } });
+
+export interface IntentRecordQuery {
+  cwd: string;
+  /** The record's id, or `<kind name>/<id>`. */
+  record: string;
+  at?: string;
+  kinds?: string[];
+}
+
+export interface IntentRecordResult {
+  doc: IntentRecordDocument;
+  failed: boolean;
+}
+
+const stringOr = (v: unknown): string | null => (typeof v === "string" ? v : null);
+
+/** Build the document. Never throws an {@link IntentError}, {@link WorkspaceReadError} or {@link RecordReadError}. */
+export async function intentRecord(query: IntentRecordQuery): Promise<IntentRecordResult> {
+  const head: Head = { $schema: INTENT_RECORD_OUTPUT_SCHEMA_ID, contract: INTENT_RECORD_CONTRACT_VERSION, chant: readerVersion() };
+  try {
+    return await walk(query, head);
+  } catch (err) {
+    if (err instanceof IntentError || err instanceof WorkspaceReadError || err instanceof RecordReadError) {
+      return { doc: { ...head, error: { code: err.code as IntentErrorCode, message: err.message } }, failed: true };
+    }
+    throw err;
+  }
+}
+
+async function walk(query: IntentRecordQuery, head: Head): Promise<IntentRecordResult> {
+  const located = locateWorkspace(query.cwd, query.at);
+  const top = located.top;
+  if (!top) throw new IntentError("not-a-git-repository", "the intent walk reads git history, and this directory is not in a git repository");
+  const declaration = readDeclaration(located.tree, "", { rootChant: true });
+  const kindFiles = query.kinds ?? declaredRecordKinds(declaration).map((d) => declaredKindFile(d, located.rootOnDisk));
+  const kinds = await loadKinds({ cwd: query.cwd, region: "", at: query.at, kinds: kindFiles }, top);
+  const workspacePrefix = located.root === "." ? "" : located.root;
+  const kindPrefix = (k: LoadedKind) => (k.records!.workspaceRoot === "." ? "" : k.records!.workspaceRoot);
+  const fromWorkspace = (full: string) => (workspacePrefix === "" ? full : full.startsWith(`${workspacePrefix}/`) ? full.slice(workspacePrefix.length + 1) : full === workspacePrefix ? "." : full);
+
+  // The record, among the decision kinds read.
+  const slash = query.record.indexOf("/");
+  const [wantKind, wantId] = slash > 0 ? [query.record.slice(0, slash), query.record.slice(slash + 1)] : [null, query.record];
+  const decisionKinds = kinds.filter((k) => k.records && !k.records.loaded.kind.work);
+  const hit = decisionKinds
+    .filter((k) => wantKind === null || k.records!.loaded.kind.name === wantKind)
+    .flatMap((k) => k.records!.views.filter((v) => v.id === wantId).map((v) => ({ kind: k, view: v })))[0];
+  if (!hit) {
+    const kindsRead = decisionKinds.map((k) => k.records!.loaded.kind.name);
+    throw new IntentError("intent-record-unknown", `no record of ${kindsRead.length > 0 ? `the decision kinds read (${kindsRead.join(", ")})` : "a decision kind: none was read"} has the id ${query.record}`);
+  }
+  const kind = hit.kind.records!.loaded.kind;
+  const view = hit.view;
+
+  const rev = located.at ?? (tryGit(top, ["rev-parse", "--verify", "--quiet", "HEAD^{commit}"])?.trim() || null);
+  const shallow = tryGit(top, ["rev-parse", "--is-shallow-repository"])?.trim() === "true";
+  const reasons: IntentReason[] = [];
+  if (shallow) reasons.push({ code: "intent-history-shallow", message: "this is a shallow clone, so the history stops at its boundary and the oldest commit listed may stand for many" });
+
+  // Each constrains entry, and the commits its history lists.
+  const constrains: RecordConstraint[] = [];
+  const pathEntries: { entry: string; full: string }[] = [];
+  const memberEntries: { entry: string; name: string }[] = [];
+  const listed = new Map<string, string[]>();
+  const list = kind.constrains?.field ? view.data?.[kind.constrains.field] : undefined;
+  for (const entry of Array.isArray(list) ? list : []) {
+    if (typeof entry !== "string") continue;
+    if (entry.startsWith("path:")) {
+      const p = entry.slice("path:".length);
+      if (!isWorkspacePath(p)) {
+        constrains.push({ entry, granularity: "path", path: null, exists: null, walked: false });
+        continue;
+      }
+      const full = joinPath(kindPrefix(hit.kind), p);
+      const type = located.tree.stat(fromWorkspace(full));
+      constrains.push({ entry, granularity: "path", path: fromWorkspace(full), exists: type !== undefined, walked: rev !== null });
+      pathEntries.push({ entry, full });
+      if (!rev) continue;
+      for (const t of regionHistory(top, rev, full, type === "file" ? "file" : "dir", null)) (listed.get(t.sha) ?? listed.set(t.sha, []).get(t.sha)!).push(entry);
+    } else if (entry.startsWith("member:")) {
+      const name = entry.slice("member:".length);
+      const m = declaration.members.find((x) => x.name === name);
+      constrains.push({ entry, granularity: "member", path: m ? m.dir : null, exists: !!m, walked: !!m && rev !== null });
+      if (!m) continue;
+      memberEntries.push({ entry, name });
+      if (!rev) continue;
+      // The member's directory, less the members nested inside it.
+      const dir = joinPath(workspacePrefix, m.dir);
+      const nested = declaration.members.filter((x) => x.name !== m.name && x.dir !== m.dir && (m.dir === "." || x.dir.startsWith(`${m.dir}/`))).map((x) => `:(exclude)${joinPath(workspacePrefix, x.dir)}`);
+      const out = tryGit(top, ["log", "--format=%H", rev, "--", dir === "" ? "." : dir, ...nested]);
+      for (const sha of (out ?? "").split("\n").map((s) => s.trim()).filter(Boolean)) (listed.get(sha) ?? listed.set(sha, []).get(sha)!).push(entry);
+    } else {
+      constrains.push({ entry, granularity: /^[^/\s]+\/[^/\s]+#[0-9]+$/.test(entry) ? "issue" : "contract", path: null, exists: null, walked: false });
+    }
+  }
+
+  // The record's window, and each other decision's, opened the same way.
+  const decisionIndex = new Map<string, { kind: LoadedKind; view: RecordView }>();
+  for (const k of decisionKinds) for (const v of k.records!.views) if (v.id !== null) decisionIndex.set(`${k.records!.loaded.kind.name}/${v.id}`, { kind: k, view: v });
+  const decisionWindow = (k: LoadedKind, v: RecordView) => {
+    const from = rev ? windowOpening(top, rev, v) : null;
+    const successor = v.supersededBy ? decisionIndex.get(`${k.records!.loaded.kind.name}/${v.supersededBy}`) : undefined;
+    const until = rev && successor ? windowOpening(top, rev, successor.view) : null;
+    return { from, until, fromSet: from && rev ? descendants(top, from, rev) : new Set<string>(), untilSet: until && rev ? descendants(top, until, rev) : null };
+  };
+  const inWindow = (w: { fromSet: Set<string>; untilSet: Set<string> | null }, sha: string) => w.fromSet.has(sha) && !w.untilSet?.has(sha);
+  const own = decisionWindow(hit.kind, view);
+  const shas = [...listed.keys()].filter((sha) => inWindow(own, sha));
+  const details = commitDetails(top, shas);
+  // Newest first by commit date, as git log lists them.
+  const order = (shas.length > 0 ? tryGit(top, ["rev-list", "--no-walk=sorted", "--stdin"], `${shas.join("\n")}\n`) : "")?.split("\n").map((s) => s.trim()).filter(Boolean) ?? shas;
+  shas.sort((a, b) => order.indexOf(a) - order.indexOf(b));
+
+  // The files each commit changed in the record's region.
+  const inRegion = (f: string) => pathEntries.some((p) => constraintCovers(p.full, f)) || memberEntries.some((m) => memberHolding(fromWorkspace(f), declaration.members) === m.name);
+  const files = new Map<string, string[]>();
+  if (shas.length > 0) {
+    const text = tryGit(top, ["log", "--no-walk=unsorted", "--stdin", "--format=%x00%H", "--name-only", "--no-renames", "--diff-merges=first-parent"], `${shas.join("\n")}\n`) ?? "";
+    for (const chunk of text.split("\0")) {
+      if (!chunk) continue;
+      const [sha, ...names] = chunk.split("\n").map((s) => s.trim());
+      files.set(sha, [...new Set(names.filter((f) => f !== "" && inRegion(f)))].map(fromWorkspace));
+    }
+  }
+
+  // Other decisions with path entries, and work items, with their windows, read once each.
+  const pathsOf = (k: LoadedKind, v: RecordView): string[] => {
+    const field = k.records!.loaded.kind.constrains?.field;
+    const entries = field ? v.data?.[field] : undefined;
+    return (Array.isArray(entries) ? entries : []).filter((e): e is string => typeof e === "string" && e.startsWith("path:") && isWorkspacePath(e.slice(5))).map((e) => joinPath(kindPrefix(k), e.slice(5)));
+  };
+  const allFiles = [...new Set([...files.values()].flat())].map((f) => joinPath(workspacePrefix, f));
+  const others: { ref: RecordRef; paths: string[]; window: ReturnType<typeof decisionWindow> }[] = [];
+  for (const [, o] of decisionIndex) {
+    if (o.view === view) continue;
+    const paths = pathsOf(o.kind, o.view);
+    if (!paths.some((p) => allFiles.some((f) => constraintCovers(p, f)))) continue;
+    others.push({ ref: { recordKind: o.kind.records!.loaded.kind.name, record: o.view.id!, state: o.view.state }, paths, window: decisionWindow(o.kind, o.view) });
+  }
+  const works: { ref: RecordRef; paths: string[]; implementsRecord: boolean; window: { fromSet: Set<string>; untilSet: Set<string> | null } }[] = [];
+  for (const k of kinds.filter((x) => x.records?.loaded.kind.work)) {
+    const wk = k.records!.loaded.kind;
+    for (const v of k.records!.views) {
+      if (v.id === null) continue;
+      const dropped = v.state !== null && v.state !== wk.work!.done && (wk.closedStates ?? []).includes(v.state);
+      if (dropped) continue;
+      const implementsRecord = idList(v.data, wk.work!.implements).includes(view.id!);
+      const paths = pathsOf(k, v);
+      if (!implementsRecord && !paths.some((p) => allFiles.some((f) => constraintCovers(p, f)))) continue;
+      const added = rev ? addingCommit(top, rev, v.path) : null;
+      const closing = rev && wk.stateField ? closingCommit(top, rev, v.path, wk.stateField, wk.closedStates ?? []) : null;
+      const untilSet = closing && rev ? descendants(top, closing, rev) : null;
+      if (closing) untilSet!.delete(closing);
+      works.push({ ref: { recordKind: wk.name, record: v.id, state: v.state }, paths, implementsRecord, window: { fromSet: added && rev ? descendants(top, added, rev) : new Set(), untilSet } });
+    }
+  }
+
+  // Each commit's origin, from the plugins, and its bucket.
+  const readAt = (path: string): string | undefined => (isWorkspacePath(path) && located.tree.stat(path) === "file" ? located.tree.read(path) : undefined);
+  const listAt = (dir: string): string[] | undefined => {
+    const d = dir === "." ? "" : dir.replace(/\/+$/, "");
+    if (d !== "" && (!isWorkspacePath(d) || located.tree.stat(d) !== "dir")) return undefined;
+    return located.tree.list(d)?.map((e) => `${joinPath(d, e.name)}${e.type === "dir" ? "/" : ""}`).sort();
+  };
+  const failedPlugins = new Set<string>();
+  const constrainedContracts = constrains.filter((c) => c.granularity === "contract").map((c) => c.entry);
+  const commits: RecordCommit[] = [];
+  for (const sha of shas) {
+    const c = details.get(sha);
+    if (!c) continue;
+    let unit: string | null = null;
+    let isOwn = false;
+    for (const k of kinds) {
+      if (!k.joins) continue;
+      let result;
+      try {
+        result = await runCommitJoins(k.joins, c, { read: readAt, list: listAt, at: located.at }, k.name);
+      } catch (err) {
+        const message = `${k.display}: commitJoins failed for ${sha.slice(0, 8)}: ${err instanceof Error ? err.message : String(err)}`;
+        if (!failedPlugins.has(message)) reasons.push({ code: "intent-plugin-failed", message });
+        failedPlugins.add(message);
+        continue;
+      }
+      if (!result.unit) continue;
+      unit ??= result.unit.id;
+      const named = [...entityDecisions(result.unit), ...entityDecisions(result.contract)];
+      if (named.some((x) => x === view.id || x === `${kind.name}/${view.id}`)) isOwn = true;
+      if (result.contract && constrainedContracts.includes(result.contract.id)) isOwn = true;
+    }
+    const changed = (files.get(sha) ?? []).map((f) => joinPath(workspacePrefix, f));
+    const covers = (paths: string[]) => paths.some((p) => changed.some((f) => constraintCovers(p, f)));
+    const workedBy = works.filter((w) => inWindow(w.window, sha) && (w.implementsRecord || covers(w.paths))).map((w) => w.ref);
+    const alsoWithin = others.filter((o) => inWindow(o.window, sha) && covers(o.paths)).map((o) => o.ref);
+    const pr = c.subject.match(/\(#([0-9]+)\)\s*$/);
+    commits.push({
+      sha,
+      subject: c.subject,
+      author: c.author,
+      date: c.date,
+      trailers: c.trailers,
+      pullRequest: pr ? Number(pr[1]) : null,
+      unit,
+      entries: listed.get(sha)!,
+      files: files.get(sha) ?? [],
+      bucket: isOwn ? "own" : workedBy.length > 0 ? "worked" : alsoWithin.length > 0 ? "within-other" : "unexplained",
+      workedBy,
+      alsoWithin,
+    });
+  }
+
+  const count = (b: IntentRecordBucket) => commits.filter((c) => c.bucket === b).length;
+  return {
+    doc: {
+      ...head,
+      at: located.at,
+      workspace: { name: declaration.name, root: located.root },
+      record: {
+        id: `record:${kind.name}/${view.id}`,
+        recordKind: kind.name,
+        record: view.id!,
+        path: view.path,
+        title: stringOr(view.data?.title),
+        state: view.state,
+        supersededBy: view.supersededBy,
+        decidedIn: view.decidedIn ?? null,
+        constrains,
+      },
+      history: { rev, shallow },
+      window: { from: own.from, until: own.until },
+      kinds: kinds.map((k) => ({ file: k.display, name: k.name, records: k.records?.loaded.kind.name ?? null, joins: k.joins?.form ?? null })),
+      commits,
+      counts: { commits: commits.length, own: count("own"), worked: count("worked"), withinOther: count("within-other"), unexplained: count("unexplained"), outsideWindow: listed.size - shas.length },
+      reasons,
+    },
+    failed: reasons.some((r) => r.code === "intent-plugin-failed"),
+  };
+}