@intentius/chant 0.124.13 → 0.124.14

package/dist/workspace/intent.js

@@ -0,0 +1,1582 @@
+/**
+ * The intent graph over one region: `chant workspace graph --intent
+ * <path[:start-end]|path#symbol>` (#2651; #2650 sections B and C1; #2524 D8,
+ * D15; #3034).
+ *
+ * A person points at some code and asks how it got this way and who decided
+ * it should be this way. This module gathers what the workspace records about
+ * that, as one document of nodes and edges, and decides nothing. It gathers
+ * three sources before it relates any of them, so no one of them frames the
+ * others:
+ *
+ * - The commits that touched the region, from git: `git log -L` for a line
+ *   range, `git log --follow` for a file and `git log -- <dir>` for a
+ *   directory. Each carries its trailers and its provenance level, and a
+ *   plugin may join it to a unit of work, a contract and evidence
+ *   (`intent-joins.ts`).
+ * - The decisions whose `constrains` cover the region: a `path:` entry that
+ *   is the region or a directory above it, the region's `member:`, an issue
+ *   the region's commits name, or a contract a plugin joined. Their
+ *   supersession chains come along.
+ * - The artifacts those decisions pin. Artifacts relate to code only through
+ *   decisions (#2549), so an artifact is in the graph because a decision in
+ *   the graph pins it.
+ *
+ * Every gap the walk finds is a `finding` node with a closed code, never
+ * prose, so a reader can draw it and a test can assert it. A commit made
+ * inside a decision's window is not taken as that decision's work: unless
+ * the decision's own unit made it, it is `decided-by-window`, shown for the
+ * person to judge (#2656). A plugin's `commitJoins` may add findings of its
+ * own, in its own code namespace. Without `kinds`, the walk reads every
+ * record kind the declaration names (#2680), and each one's `commitJoins`
+ * runs for every commit in that order. chant emits the
+ * graph and hud renders it (#2524 D8, D15). Git is read through a local
+ * `git` subprocess only: no fetch, no network, except to follow a squash
+ * when asked (below).
+ *
+ * A region can name a symbol, `path#symbol`, which `symbols.ts` resolves to
+ * its current lines (#3034). For a file region the document also carries
+ * `why`: who made the region's current lines, from `git blame`, the agent run
+ * behind each (narrowed by the hunks a run recorded when several share a
+ * commit), and the decisions governing the region, most relevant first, with
+ * `explained: false` and closed gap codes when nothing accounts for it.
+ *
+ * A commit joins an agent run by its `Chant-Run` trailer or the run's own
+ * list of commits, and, failing both, by content (#3036): a commit whose
+ * `git patch-id --stable` equals one the run recorded, as after a rebase or a
+ * cherry-pick that dropped the trailer. Its `made-by` edge says `patch-id`,
+ * and a commit joined one way whose content matches another run's recorded
+ * commit is `intent-commit-join-conflict`.
+ *
+ * Asked to (`followSquash`, #3035), the walk follows a squash merge to its
+ * pull request's original commits (`squash.ts`): the squash commit node lists
+ * them with their trailers, joins and signatures, carries what their trailers
+ * and plugin joins carry, and joins their runs, marked `squash`. That is the
+ * one part of the walk that may reach the network, to fetch a pull request
+ * ref the clone lacks; a ref that can't be read is `squash-unfollowed` in
+ * `reasons`, and the walk keeps its answer without it.
+ */
+import { execFileSync } from "node:child_process";
+import { realpathSync } from "node:fs";
+import { basename, dirname, relative, resolve, sep } from "node:path";
+import { declaredRecordKinds, readDeclaration, readerVersion, resolveGroups, WORKSPACE_ERROR_CODES, WorkspaceReadError } from "./declaration.js";
+import { declaredKindFile } from "./declared-kinds.js";
+import { isGeneratedPath } from "./generated-files.js";
+import { entityDecisions, hasTrailer, readCommitJoins, runCommitJoins } from "./intent-joins.js";
+import { loadKindRegistry } from "./kinds.js";
+import { resolveLinks } from "./links.js";
+import { sourceMemberHandles } from "./member-handles.js";
+import { constraintCovers, isWorkspacePath, memberHolding } from "./record-assets.js";
+import { importKindModule, loadRecordKind, parseFrontMatter, RecordReadError, supersedesTargets } from "./records.js";
+import { queryRecords } from "./records-cli.js";
+import { isPluginCode } from "./reason-codes.js";
+import { addSquashRuns, RUN_JOIN_ORDER, runsForCommits } from "./runs.js";
+import { followSquashes, squashLineOrigins } from "./squash.js";
+import { memberDirOnDisk, memberSymbolResolvers } from "./lexicon-symbols.js";
+import { resolveSymbol, symbolResolverFor } from "./symbols.js";
+import { readTrailerJoins } from "./trailer-joins.js";
+import { joinPath, skippedDir } from "./tree.js";
+import { activeAttestors } from "./trust/attestor.js";
+import { commitProvenance, policyAtBase, resolveBase } from "./trust/provenance.js";
+import { locateWorkspace } from "./which-chant.js";
+import { idList, isDecided, WORK_WARNING_CODES } from "./work.js";
+/** The version of the `intent` document this chant writes. */
+export const INTENT_CONTRACT_VERSION = 1;
+/** `$id` of the JSON Schema for the document, shipped beside this file. */
+export const INTENT_OUTPUT_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace/intent/v1/intent.schema.json";
+// ── Codes ────────────────────────────────────────────────────────────────────
+/** The finding codes. Closed: a reader may switch on them. */
+export const INTENT_FINDING_CODES = [
+    /** A commit touched the region when no decision constrained it at path granularity. */
+    "intent-commit-undecided",
+    /** A commit has no unit, carries no record through chant's trailers, has no pull request reference and no decision covering the region at its time. */
+    "intent-commit-bare",
+    /** A pinned artifact's bytes no longer hash to the pin. */
+    "intent-pin-drifted",
+    /** A pinned artifact does not exist in the tree read. */
+    "intent-pin-missing",
+    /** A current decision's pin is unchanged at the hash a record it supersedes pinned: the decision moved on and the artifact did not (#2686). */
+    "intent-pin-stale",
+    /** An artifact that decisions in the graph pinned, and that no current decision pins. */
+    "intent-artifact-unpinned",
+    /** Every decision constraining the region is superseded. */
+    "intent-decision-superseded-live",
+    /** The current decisions constraining the region are all in states their kind does not close, such as decided and not ratified. */
+    "intent-decision-provisional",
+    /** A current decision constraining the region has an open concern: a dissent neither addressed nor withdrawn (#2686). */
+    "intent-decision-contested",
+    /** The region is constrained only at member granularity. */
+    "intent-constraint-coarse",
+    /** A decision's path constraint names a path that does not exist. */
+    "intent-constraint-lost",
+    /** A decision's evidence has no hash: a URL, or a path with no sha256. */
+    "intent-evidence-unpinned",
+    /** A commit carries a trailer a plugin says claims authorship, and the commit is not attested. */
+    "intent-trailer-unverified",
+    /** No decision constrains the region at any granularity. */
+    "intent-region-unconstrained",
+    /** A decided decision constrains the region, no work item that is not dropped implements it, and no commit falls in its window (#2683). Only with a work kind read. */
+    "intent-decision-unimplemented",
+    /** A work item constraining the region has commits in its window while its blockedBy is not empty (#2683). */
+    "intent-work-blocked",
+    /** Commits in the region are a decision's own work while the work item implementing it is still open: the code says done and the queue says not (#2683). */
+    "intent-work-open-decided-code",
+    /** A commit joined to an agent run by its trailer or the run's record has the patch-id of a commit another run recorded; the content join is not made (#3036). */
+    "intent-commit-join-conflict",
+];
+/** Why part of the walk could not be read. The read still succeeds. */
+export const INTENT_REASON_CODES = [
+    /** The repository is a shallow clone, so the history is cut. */
+    "intent-history-shallow",
+    /** A plugin's commitJoins failed for a commit. */
+    "intent-plugin-failed",
+    /** A squash commit's pull request ref could not be read or fetched, so its original commits are not followed (#3035). */
+    "squash-unfollowed",
+];
+/** Why the read failed as a whole: the declaration's codes, the record kind's codes, or a region that isn't there. */
+export const INTENT_ERROR_CODES = [
+    ...WORKSPACE_ERROR_CODES,
+    "kind-unreadable",
+    "kind-invalid",
+    "schema-unreadable",
+    "schema-id-mismatch",
+    "schema-invalid",
+    "location-missing",
+    /** The region's path, or its line range, does not exist in the tree read. */
+    "intent-region-invalid",
+    /** --record names an id no record of a decision kind read has. */
+    "intent-record-unknown",
+    /** The region names a symbol in a file no resolver reads (#3034). */
+    "intent-symbol-unsupported",
+    /** The region names a symbol the file does not declare (#3034). */
+    "intent-symbol-unknown",
+    /** The region names a symbol that matches more than one declaration (#3034). */
+    "intent-symbol-ambiguous",
+];
+/** Why `why` can't account for some or all of a region (#3034). Closed. */
+export const INTENT_WHY_CODES = [
+    /** No current decision governs the region, at any granularity, and none is carried out by the commits or runs that made its lines. */
+    "intent-why-no-decision",
+    /** None of the region's current lines was made by a commit an agent run is joined to. */
+    "intent-why-no-run",
+    /** Some of the region's lines are not committed, so nothing made them yet. */
+    "intent-why-uncommitted",
+    /** Some lines come from a commit that several runs made, and no run's recorded hunks say which wrote them. */
+    "intent-why-run-ambiguous",
+];
+export class IntentError extends Error {
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "IntentError";
+    }
+}
+// ── Git ──────────────────────────────────────────────────────────────────────
+function git(top, args, input) {
+    return execFileSync("git", args, { cwd: top, encoding: "utf-8", input, stdio: [input === undefined ? "ignore" : "pipe", "pipe", "pipe"], maxBuffer: 512 * 1024 * 1024 });
+}
+export function tryGit(top, args, input) {
+    try {
+        return git(top, args, input);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The new-side line ranges of each hunk header in a patch. */
+function hunkRanges(patch) {
+    const out = [];
+    for (const m of patch.matchAll(/^@@+ [^@]*\+(\d+)(?:,(\d+))? @@/gm)) {
+        const start = Number(m[1]);
+        const count = m[2] === undefined ? 1 : Number(m[2]);
+        if (count > 0)
+            out.push({ start, end: start + count - 1 });
+    }
+    return out;
+}
+/** The commits that touched the region, newest first, with the lines each changed for a line range. */
+export function regionHistory(top, rev, gitPath, type, lines) {
+    if (lines) {
+        const out = tryGit(top, ["log", `-L${lines.start},${lines.end}:${gitPath}`, "--format=%x00%H", "--no-color", rev]);
+        if (out === undefined)
+            return [];
+        return out
+            .split("\0")
+            .filter(Boolean)
+            .map((chunk) => {
+            const nl = chunk.indexOf("\n");
+            const sha = (nl < 0 ? chunk : chunk.slice(0, nl)).trim();
+            return { sha, lines: hunkRanges(nl < 0 ? "" : chunk.slice(nl + 1)) };
+        });
+    }
+    const args = type === "file" ? ["log", "--follow", "--format=%H", rev, "--", gitPath] : ["log", "--format=%H", rev, "--", gitPath === "" ? "." : gitPath];
+    const out = tryGit(top, args);
+    if (out === undefined)
+        return [];
+    return out
+        .split("\n")
+        .map((s) => s.trim())
+        .filter(Boolean)
+        .map((sha) => ({ sha, lines: null }));
+}
+const ZERO_SHA = /^0+$/;
+/**
+ * `git blame` over a file's lines (#3034): at `rev`, or in the working tree
+ * when `rev` is null, where a line not committed yet has no commit. Undefined
+ * when git can't blame the file, such as one never committed.
+ */
+export function blameLines(top, rev, gitPath, lines) {
+    const out = tryGit(top, ["blame", "--line-porcelain", ...(lines ? [`-L${lines.start},${lines.end}`] : []), ...(rev ? [rev] : []), "--", gitPath]);
+    if (out === undefined)
+        return undefined;
+    const result = [];
+    let current;
+    for (const l of out.split("\n")) {
+        if (l.startsWith("\t")) {
+            if (current)
+                result.push({ line: current.line, sha: ZERO_SHA.test(current.sha) ? null : current.sha, origPath: current.origPath, origLine: current.origLine });
+            current = undefined;
+            continue;
+        }
+        const head = l.match(/^([0-9a-f]{40,64}) (\d+) (\d+)(?: \d+)?$/);
+        if (head) {
+            current = { sha: head[1], origLine: Number(head[2]), line: Number(head[3]), origPath: gitPath };
+            continue;
+        }
+        if (current && l.startsWith("filename "))
+            current.origPath = l.slice("filename ".length);
+    }
+    return result;
+}
+/** Subject, body, author, date and trailers of each commit. */
+export function commitDetails(top, shas) {
+    const out = new Map();
+    if (shas.length === 0)
+        return out;
+    const text = git(top, ["log", "--no-walk=unsorted", "--stdin", "--format=%x00%H%x1f%an%x1f%ae%x1f%aI%x1f%(trailers:only,unfold,separator=%x1e)%x1f%B"], `${shas.join("\n")}\n`);
+    for (const record of text.split("\0")) {
+        if (!record)
+            continue;
+        const [sha, name, email, date, trailerText, ...rest] = record.split("\x1f");
+        const message = rest.join("\x1f").replace(/\n+$/, "");
+        const nl = message.indexOf("\n");
+        const trailers = {};
+        for (const t of (trailerText ?? "").split("\x1e")) {
+            const colon = t.indexOf(":");
+            if (colon <= 0)
+                continue;
+            const key = t.slice(0, colon).trim();
+            (trailers[key] ?? (trailers[key] = [])).push(t.slice(colon + 1).trim());
+        }
+        out.set(sha.trim(), {
+            sha: sha.trim(),
+            subject: nl < 0 ? message : message.slice(0, nl),
+            body: nl < 0 ? "" : message.slice(nl + 1).replace(/^\n+/, ""),
+            author: { name, email },
+            date,
+            trailers,
+        });
+    }
+    return out;
+}
+/** The commit reachable from `rev` that last added `path` (from the repository root), or null. */
+export function addingCommit(top, rev, path) {
+    const out = tryGit(top, ["log", "--diff-filter=A", "-1", "--format=%H", rev, "--", path]);
+    return out?.trim() || null;
+}
+/**
+ * The commit reachable from `rev` that moved the record at `path` into a
+ * closed state and kept it there, or null when the record is not closed at
+ * `rev` (#2683). A record added in a closed state closes in the commit that
+ * added it.
+ */
+export function closingCommit(top, rev, path, stateField, closed) {
+    const out = tryGit(top, ["log", "--format=%H", rev, "--", path]);
+    let closing = null;
+    for (const sha of (out ?? "").split("\n").map((l) => l.trim()).filter(Boolean)) {
+        const text = tryGit(top, ["show", `${sha}:${path}`]);
+        const fm = text === undefined ? undefined : parseFrontMatter(text);
+        const state = fm?.ok ? fm.value[stateField] : undefined;
+        if (typeof state !== "string" || !closed.includes(state))
+            break;
+        closing = sha;
+    }
+    return closing;
+}
+/** The commit a decision record's window opens at: the one that decided it, or, when it is not approved, the one that added it. */
+export function windowOpening(top, rev, view) {
+    return view.decidedIn?.sha ?? addingCommit(top, rev, view.path);
+}
+/** `commit` and every commit between it and `rev` that has it as an ancestor. */
+export function descendants(top, commit, rev) {
+    const out = new Set([commit]);
+    const text = tryGit(top, ["rev-list", "--ancestry-path", `${commit}..${rev}`]);
+    for (const line of (text ?? "").split("\n"))
+        if (line.trim())
+            out.add(line.trim());
+    return out;
+}
+/** `owner/repo` of the `origin` remote, lower case, or null. Read from local config; nothing is fetched. */
+function originRepo(top) {
+    const url = tryGit(top, ["config", "--get", "remote.origin.url"])?.trim();
+    const m = url?.match(/[:/]([^/:]+)\/([^/]+?)(?:\.git)?\/?$/);
+    return m ? `${m[1]}/${m[2]}`.toLowerCase() : null;
+}
+// ── Helpers ──────────────────────────────────────────────────────────────────
+const toPosix = (p) => (sep === "/" ? p : p.split(sep).join("/"));
+function realpathOr(p) {
+    try {
+        return realpathSync(p);
+    }
+    catch {
+        return p;
+    }
+}
+/** Parse `path`, `path:line` or `path:start-end`. */
+export function parseRegion(arg) {
+    const m = arg.match(/^(.+?):(\d+)(?:-(\d+))?$/);
+    if (!m)
+        return { path: arg, lines: null };
+    const start = Number(m[2]);
+    const end = m[3] === undefined ? start : Number(m[3]);
+    if (start < 1 || end < start)
+        return { error: `${arg}: a line range is start-end with 1 <= start <= end` };
+    return { path: m[1], lines: { start, end } };
+}
+function regionId(path, lines, symbol) {
+    if (symbol !== undefined)
+        return `region:${path}#${symbol}`;
+    return `region:${path}${lines ? `:${lines.start}${lines.end === lines.start ? "" : `-${lines.end}`}` : ""}`;
+}
+function filesUnder(tree, dir) {
+    const out = [];
+    const walk = (d) => {
+        for (const e of (tree.list(d) ?? []).sort((a, b) => a.name.localeCompare(b.name))) {
+            const p = joinPath(d, e.name);
+            if (e.type === "dir") {
+                if (!skippedDir(e.name))
+                    walk(p);
+            }
+            else
+                out.push(p);
+        }
+    };
+    walk(dir === "." ? "" : dir);
+    return out;
+}
+function stringOr(v) {
+    return typeof v === "string" ? v : null;
+}
+/** A work record's `source` when it names the gap it came from (#2683), or null. */
+function gapSource(data) {
+    const src = data?.source;
+    if (src === null || typeof src !== "object" || Array.isArray(src))
+        return null;
+    const s = src;
+    if (typeof s.finding !== "string" || typeof s.region !== "string")
+        return null;
+    return {
+        finding: s.finding,
+        region: s.region,
+        ...(typeof s.decision === "string" ? { decision: s.decision } : {}),
+        ...(typeof s.artifact === "string" ? { artifact: s.artifact } : {}),
+    };
+}
+function reviewSummary(data) {
+    const out = { agree: 0, dissent: 0, abstain: 0, openConcerns: 0 };
+    const list = data?.reviews;
+    if (!Array.isArray(list))
+        return out;
+    for (const r of list) {
+        if (r === null || typeof r !== "object")
+            continue;
+        const review = r;
+        if (review.verdict === "agree")
+            out.agree++;
+        else if (review.verdict === "abstain")
+            out.abstain++;
+        else if (review.verdict === "dissent") {
+            out.dissent++;
+            if (review.addressed_by == null && review.withdrawn_on == null)
+                out.openConcerns++;
+        }
+    }
+    return out;
+}
+const SHA256 = /^[0-9a-f]{64}$/;
+const ISSUE = /^([A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+)#([0-9]+)$/;
+const PIN_ORDER = ["missing", "drifted", "stale", "pinned"];
+/** The default node resolver: the member's graph, read as `workspace graph --member` reads it. */
+async function resolveNodeFromGraph(cwd, at, member, id) {
+    const { workspaceGraph } = await import("./graph-cli.js");
+    const { doc } = await workspaceGraph({ cwd, at, members: [member] });
+    if ("error" in doc)
+        return null;
+    const node = doc.nodes.find((n) => n.id === id);
+    if (!node)
+        return null;
+    return node.sourceLoc ? { file: node.sourceLoc.file, line: node.sourceLoc.line ?? null } : { file: ".", line: null };
+}
+export async function loadKinds(query, top) {
+    const out = [];
+    for (const k of query.kinds ?? []) {
+        const file = resolve(query.cwd, k);
+        const display = toPosix(relative(top, realpathOr(file)));
+        let mod;
+        try {
+            mod = await importKindModule(file);
+        }
+        catch (err) {
+            throw new IntentError("kind-unreadable", `kind file ${k} could not be loaded: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        const joins = readCommitJoins(mod);
+        if (typeof joins === "string")
+            throw new IntentError("kind-invalid", `kind file ${k} has a commitJoins export that can't be read: ${joins}`);
+        const kind = { file, display, name: joins?.name ?? basename(file).replace(/(?:\.kind)?\.[cm]?[jt]s$/, ""), ...(joins ? { joins } : {}) };
+        if (mod.recordKind !== undefined) {
+            const doc = await queryRecords({ kind: file, at: query.at, cwd: query.cwd, workGaps: false });
+            if ("error" in doc)
+                throw new IntentError(doc.error.code, doc.error.message);
+            try {
+                kind.records = { loaded: await loadRecordKind(file), views: doc.records, workspaceRoot: doc.workspaceRoot };
+                kind.name = joins?.name ?? kind.records.loaded.kind.name;
+            }
+            catch (err) {
+                if (err instanceof RecordReadError)
+                    throw new IntentError(err.code, err.message);
+                throw err;
+            }
+        }
+        else if (!joins) {
+            throw new IntentError("kind-invalid", `kind file ${k} exports neither recordKind nor commitJoins`);
+        }
+        out.push(kind);
+    }
+    return out;
+}
+async function resolveRegion(query, located, declaration) {
+    const parsed = parseRegion(query.region);
+    if ("error" in parsed)
+        throw new IntentError("intent-region-invalid", parsed.error);
+    const inWorkspace = (p) => {
+        const rel = toPosix(relative(realpathOr(located.rootOnDisk), resolve(realpathOr(query.cwd), p)));
+        const path = rel === "" ? "." : rel;
+        return path === "." || (isWorkspacePath(path) && !path.startsWith("../") && located.tree.stat(path) !== undefined) ? path : undefined;
+    };
+    const path = inWorkspace(parsed.path);
+    if (path !== undefined)
+        return { path, lines: parsed.lines, node: null, symbol: null };
+    // path#symbol (#3034): the symbol's current lines in the tree read.
+    const hash = parsed.lines ? -1 : query.region.lastIndexOf("#");
+    if (hash > 0) {
+        const name = query.region.slice(hash + 1);
+        const file = inWorkspace(query.region.slice(0, hash));
+        if (file !== undefined && name !== "") {
+            if (file === "." || located.tree.stat(file) !== "file")
+                throw new IntentError("intent-region-invalid", `${file} is a directory, and a symbol needs a file`);
+            // A file core's resolver doesn't read may have one from its member's lexicons (#3313).
+            let extra = [];
+            let why = "";
+            if (!symbolResolverFor(file)) {
+                const holder = memberHolding(file, declaration.members);
+                const m = holder ? declaration.members.find((x) => x.name === holder) : undefined;
+                if (m && m.kind === "chant") {
+                    const got = await memberSymbolResolvers(memberDirOnDisk(located.rootOnDisk, m.dir), query.loadLexicon);
+                    extra = got.resolvers;
+                    if (got.problems.length > 0)
+                        why = `; member ${m.name}: ${got.problems.join("; ")}`;
+                }
+            }
+            const r = resolveSymbol(file, located.tree.read(file), name, extra);
+            if (!r.ok)
+                throw new IntentError(r.reason === "unsupported" ? "intent-symbol-unsupported" : r.reason === "ambiguous" ? "intent-symbol-ambiguous" : "intent-symbol-unknown", `${r.message}${r.reason === "unsupported" ? why : ""}${located.tree.label}`);
+            return { path: file, lines: r.declaration.lines, node: null, symbol: { name, qualified: r.declaration.qualified, kind: r.declaration.kind } };
+        }
+    }
+    // A graph node id, <member>/<id>, when no such path exists (#2650 B1).
+    const slash = query.region.indexOf("/");
+    const member = slash > 0 ? declaration.members.find((m) => m.name === query.region.slice(0, slash)) : undefined;
+    if (member && !parsed.lines) {
+        const loc = await (query.resolveNode ?? resolveNodeFromGraph)(query.cwd, query.at, member.name, query.region);
+        if (loc) {
+            const file = joinPath(member.dir, loc.file);
+            return { path: file === "" ? "." : file, lines: loc.line ? { start: loc.line, end: loc.line } : null, node: query.region, symbol: null };
+        }
+    }
+    throw new IntentError("intent-region-invalid", `${query.region} is not a path in the workspace${located.tree.label}, a path#symbol, or a graph node id`);
+}
+/** Build the intent document. Never throws an {@link IntentError}, {@link WorkspaceReadError} or {@link RecordReadError}. */
+export async function intentGraph(query) {
+    const head = { $schema: INTENT_OUTPUT_SCHEMA_ID, contract: INTENT_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, message: err.message } }, failed: true };
+        }
+        throw err;
+    }
+}
+async function walk(query, head) {
+    const located = locateWorkspace(query.cwd, query.at);
+    const top = located.top;
+    if (!top)
+        throw new IntentError("not-a-git-repository", "the intent graph reads git history, and this directory is not in a git repository");
+    const declaration = readDeclaration(located.tree, "", { rootChant: true });
+    const region = await resolveRegion(query, located, declaration);
+    const type = region.path === "." ? "dir" : located.tree.stat(region.path);
+    if (!type)
+        throw new IntentError("intent-region-invalid", `${region.path} does not exist${located.tree.label}`);
+    if (region.lines) {
+        if (type !== "file")
+            throw new IntentError("intent-region-invalid", `${region.path} is a directory, and a line range needs a file`);
+        const count = located.tree.read(region.path).replace(/\n$/, "").split("\n").length;
+        if (region.lines.end > count)
+            throw new IntentError("intent-region-invalid", `${region.path} has ${count} lines${located.tree.label}, so ${region.lines.start}-${region.lines.end} is not in it`);
+    }
+    // Without --kind, the declared record kinds, read from the working tree as a --kind file is (#2680).
+    const kindFiles = query.kinds ?? declaredRecordKinds(declaration).map((d) => declaredKindFile(d, located.rootOnDisk));
+    const kinds = await loadKinds({ ...query, kinds: kindFiles }, top);
+    const nodes = new Map();
+    const edges = [];
+    const reasons = [];
+    const findings = [];
+    const add = (n) => {
+        if (!nodes.has(n.id))
+            nodes.set(n.id, n);
+        return nodes.get(n.id);
+    };
+    const find = (code, message, concerns) => {
+        findings.push({ id: `finding:${code}:${findings.filter((f) => f.code === code).length + 1}`, kind: "finding", code, message, concerns });
+    };
+    // The region, its files and its member.
+    const member = region.path === "." ? (declaration.members.find((m) => m.dir === ".")?.name ?? null) : memberHolding(region.path, declaration.members);
+    const rid = regionId(region.path, region.lines, region.symbol?.name);
+    add({
+        id: rid,
+        kind: "region",
+        path: region.path,
+        lines: region.lines,
+        member,
+        at: located.at,
+        type,
+        generated: type === "file" ? isGeneratedPath(declaration, region.path) : null,
+        node: region.node,
+        symbol: region.symbol,
+    });
+    const files = type === "dir" ? filesUnder(located.tree, region.path) : [];
+    for (const f of files)
+        add({ id: `file:${f}`, kind: "file", path: f, member: memberHolding(f, declaration.members), generated: isGeneratedPath(declaration, f) });
+    const memberNode = (name) => {
+        const m = declaration.members.find((x) => x.name === name);
+        return add({ id: `member:${name}`, kind: "member", name, dir: m?.dir ?? "", memberKind: m?.kind ?? "" });
+    };
+    if (member)
+        memberNode(member);
+    // 1. The region's history.
+    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";
+    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" });
+    const workspacePrefix = located.root === "." ? "" : located.root;
+    const gitPath = joinPath(workspacePrefix, region.path);
+    const touched = rev ? regionHistory(top, rev, gitPath, type, region.lines) : [];
+    // Who last wrote each current line of a file region (#3034). A commit blame
+    // names and the history walk missed, as when a move confuses git log -L,
+    // joins the commits that touched the region.
+    const fileLines = type === "file" ? (region.lines ?? { start: 1, end: Math.max(1, located.tree.read(region.path).replace(/\n$/, "").split("\n").length) }) : null;
+    const blamed = fileLines === null
+        ? []
+        : ((rev ? blameLines(top, located.at, gitPath, region.lines) : undefined) ??
+            // A file git can't blame in the working tree has never been committed: every line is new.
+            (located.at === null ? Array.from({ length: fileLines.end - fileLines.start + 1 }, (_, i) => ({ line: fileLines.start + i, sha: null, origPath: gitPath, origLine: fileLines.start + i })) : []));
+    for (const sha of new Set(blamed.map((b) => b.sha).filter((x) => x !== null))) {
+        if (!touched.some((t) => t.sha === sha))
+            touched.push({ sha, lines: null });
+    }
+    const details = commitDetails(top, touched.map((t) => t.sha));
+    // Squash merges, followed to the pull request's original commits when asked (#3035).
+    const follows = query.followSquash ? followSquashes(top, [...details.values()], { fetchMissing: true }) : new Map();
+    for (const f of follows.values()) {
+        if (f.problem)
+            reasons.push({ code: "squash-unfollowed", message: `${f.sha.slice(0, 8)} squashes pull request #${f.pullRequest}, and ${f.problem}, so its original commits are not followed` });
+    }
+    const originalDetails = commitDetails(top, [...new Set([...follows.values()].flatMap((f) => f.commits))]);
+    const originalsOf = (sha) => (follows.get(sha)?.commits ?? []).map((o) => originalDetails.get(o)).filter((x) => x !== undefined);
+    // Each commit's provenance, judged by the policy at base as records judges a record's (#2547).
+    const policy = policyAtBase(top, resolveBase(top));
+    const attestors = policy.active ? await activeAttestors() : [];
+    const readAt = (path) => {
+        if (!isWorkspacePath(path) || located.tree.stat(path) !== "file")
+            return undefined;
+        return located.tree.read(path);
+    };
+    // The same tree as readAt (#2663): entries directly inside dir, from the workspace root, a directory's with a trailing slash.
+    const listAt = (dir) => {
+        const d = dir === "." ? "" : dir.replace(/\/+$/, "");
+        if (d !== "" && (!isWorkspacePath(d) || located.tree.stat(d) !== "dir"))
+            return undefined;
+        const entries = located.tree.list(d);
+        return entries?.map((e) => `${joinPath(d, e.name)}${e.type === "dir" ? "/" : ""}`).sort();
+    };
+    const joined = new Map();
+    // chant's own trailers on each commit (#3149), with the items their lease tokens name.
+    const trailerJoins = readTrailerJoins(top, [...details.values(), ...originalDetails.values()]);
+    const pluginFindings = [];
+    const signatureOf = (sha) => {
+        if (!policy.active)
+            return { level: "unattested", reason: policy.problems.length ? policy.problems.join("; ") : `no signers file (${policy.signersPath}) at base; attestation is off` };
+        const p = commitProvenance(top, policy, sha, attestors);
+        return { level: p.level, reason: p.reason, ...(p.principal ? { principal: p.principal } : {}) };
+    };
+    const failedPlugins = new Set();
+    for (const t of touched) {
+        const c = details.get(t.sha);
+        if (!c)
+            continue;
+        const signature = signatureOf(c.sha);
+        const pr = c.subject.match(/\(#([0-9]+)\)\s*$/);
+        const cid = `commit:${c.sha}`;
+        const f = follows.get(c.sha);
+        const squash = f
+            ? {
+                pullRequest: f.pullRequest,
+                forge: f.forge,
+                ref: f.ref,
+                head: f.head,
+                fetched: f.fetched,
+                followed: f.followed,
+                commits: originalsOf(c.sha).map((o) => ({ sha: o.sha, subject: o.subject, author: o.author, date: o.date, trailers: o.trailers, signature: signatureOf(o.sha), joins: trailerJoins.get(o.sha).joins })),
+            }
+            : undefined;
+        add({ id: cid, kind: "commit", sha: c.sha, subject: c.subject, author: c.author, date: c.date, trailers: c.trailers, pullRequest: pr ? Number(pr[1]) : null, signature, lines: t.lines, state: null, joins: trailerJoins.get(c.sha).joins, ...(squash ? { squash } : {}) });
+        edges.push({ kind: "touched-by", from: rid, to: cid, lines: t.lines });
+        // 2. Each commit's origin, from the plugins. A followed squash also takes its original commits' (#3035).
+        const entry = { contracts: [], authorship: [], decisions: [], carries: [] };
+        joined.set(c.sha, entry);
+        const pushEdge = (e) => {
+            if (!edges.some((x) => x.kind === e.kind && x.from === e.from && x.to === e.to))
+                edges.push(e);
+        };
+        const subjects = [c, ...originalsOf(c.sha)];
+        for (const k of kinds) {
+            if (!k.joins)
+                continue;
+            for (const subject of subjects) {
+                const original = subject !== c;
+                let result;
+                try {
+                    result = await runCommitJoins(k.joins, subject, { read: readAt, list: listAt, at: located.at }, k.name);
+                }
+                catch (err) {
+                    const message = `${k.display}: commitJoins failed for ${subject.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;
+                }
+                const joinedNode = (kind, e) => {
+                    const { id, ...data } = e;
+                    return add({ id: `${kind}:${id}`, kind, ref: id, plugin: k.display, data }).id;
+                };
+                const unitId = result.unit ? joinedNode("unit", result.unit) : undefined;
+                const contractId = result.contract ? joinedNode("contract", result.contract) : undefined;
+                if (unitId) {
+                    if (original)
+                        entry.unit ?? (entry.unit = unitId);
+                    else
+                        entry.unit = unitId;
+                    pushEdge({ kind: "produced-by", from: cid, to: unitId });
+                    if (contractId)
+                        pushEdge({ kind: "serves", from: unitId, to: contractId });
+                }
+                if (contractId)
+                    entry.contracts.push(result.contract.id);
+                if (unitId)
+                    entry.decisions.push(...entityDecisions(result.unit), ...entityDecisions(result.contract));
+                for (const f of result.findings ?? [])
+                    pluginFindings.push({ commit: cid, plugin: k.display, finding: f });
+                const evidence = result.evidence === undefined ? [] : Array.isArray(result.evidence) ? result.evidence : [result.evidence];
+                for (const e of evidence)
+                    pushEdge({ kind: "cites-evidence", from: unitId ?? contractId ?? cid, to: joinedNode("evidence", e) });
+                // Authorship is checked against the squash's own trailers, so only its own claims count.
+                if (!original)
+                    entry.authorship.push(...(result.authorship ?? []));
+            }
+        }
+    }
+    // The agent runs that made each commit (#3033): the one its Chant-Run names, and any whose record lists it.
+    const runJoins = await runsForCommits(top, located.rootOnDisk, [...new Set([...touched.map((t) => t.sha), ...originalDetails.keys()])].map((sha) => ({ sha, run: trailerJoins.get(sha)?.joins.run ?? null })));
+    // A followed squash joins its original commits' runs (#3035).
+    addSquashRuns(runJoins.refs, follows);
+    for (const t of touched) {
+        if (!nodes.has(`commit:${t.sha}`))
+            continue;
+        for (const ref of runJoins.refs.get(t.sha) ?? []) {
+            const r = runJoins.runs.get(ref.id);
+            const node = add({
+                id: `run:${ref.id}`,
+                kind: "run",
+                run: ref.id,
+                recorded: r !== undefined,
+                state: r?.state ?? null,
+                harness: r?.harness ?? null,
+                model: r?.model ?? null,
+                provider: r?.provider ?? null,
+                by: r?.by ?? null,
+                agent: r?.agent ?? null,
+                unit: r?.unit?.id ?? null,
+                startedAt: r?.startedAt ?? null,
+                endedAt: r?.endedAt ?? null,
+                outcome: r?.outcome ?? null,
+                usage: r?.usage ?? null,
+                cost: r?.cost ?? null,
+                transcript: r?.transcript ?? null,
+                instruction: r?.instruction ?? null,
+                lease: r?.lease ?? null,
+            });
+            edges.push({ kind: "made-by", from: `commit:${t.sha}`, to: node.id, joinedBy: ref.joinedBy, ...(ref.recordedAs ? { recordedAs: ref.recordedAs } : {}), ...(ref.via ? { via: ref.via } : {}) });
+        }
+    }
+    // A commit a trailer or a record joins to one run, with the content of a commit another run recorded (#3036).
+    for (const x of runJoins.conflicts) {
+        if (!nodes.has(`commit:${x.sha}`))
+            continue;
+        const others = x.content.map((m) => `${m.run} (${m.sha.slice(0, 8)})`).join(", ");
+        find("intent-commit-join-conflict", `${x.sha.slice(0, 8)} joins ${x.joined.join(", ")} by its trailer or the run's record, and has the patch-id of a commit ${others} recorded; it is not joined to ${x.content.length === 1 ? "that run" : "those runs"}`, [`commit:${x.sha}`, ...x.joined.map((id) => `run:${id}`)]);
+    }
+    // 3. The decisions whose constrains cover the region, and their chains.
+    const regionFull = region.path === "." ? workspacePrefix : gitPath;
+    const origin = originRepo(top);
+    const commitRefs = new Set();
+    for (const c of details.values())
+        for (const m of c.subject.matchAll(/#([0-9]+)/g))
+            commitRefs.add(m[1]);
+    const contractIds = new Set([...joined.values()].flatMap((j) => j.contracts));
+    const covering = [];
+    const decisionById = new Map();
+    const decisionId = (k, id) => `record:${k.records.loaded.kind.name}/${id}`;
+    const decisionNode = (k, v) => {
+        const kind = k.records.loaded.kind;
+        const supersedes = supersedesTargets(kind, v.data);
+        return add({
+            id: decisionId(k, v.id),
+            kind: "decision",
+            recordKind: kind.name,
+            record: v.id,
+            path: v.path,
+            title: stringOr(v.data?.title),
+            state: v.state,
+            closed: v.state !== null && (kind.closedStates ?? []).includes(v.state),
+            valid: v.valid,
+            reasons: v.reasons,
+            provenance: { level: v.provenance.level, commit: v.provenance.commit, reason: v.provenance.reason },
+            decided_by: stringOr(v.data?.decided_by),
+            decided_on: stringOr(v.data?.decided_on),
+            decidedIn: v.decidedIn ?? null,
+            reviews: reviewSummary(v.data),
+            supersededBy: v.supersededBy,
+            supersedes,
+            constrains: [],
+        });
+    };
+    const fileNodesUnder = (full) => files.filter((f) => constraintCovers(full, joinPath(workspacePrefix, f)));
+    /** The constrains entries of a record that cover the region or a file under it. Decisions and work items match the same way (#2683). */
+    const matchConstrains = (k, v) => {
+        const field = k.records.loaded.kind.constrains?.field;
+        const kindPrefix = k.records.workspaceRoot === "." ? "" : k.records.workspaceRoot;
+        const list = field ? v.data?.[field] : undefined;
+        const matched = [];
+        if (!Array.isArray(list))
+            return matched;
+        for (const entry of list) {
+            if (typeof entry !== "string")
+                continue;
+            if (entry.startsWith("path:")) {
+                const p = entry.slice("path:".length);
+                if (!isWorkspacePath(p))
+                    continue;
+                const full = joinPath(kindPrefix, p);
+                if (regionFull !== "" && constraintCovers(full, regionFull)) {
+                    matched.push({ entry, granularity: "path", to: rid });
+                }
+                else if (type === "dir" && full !== regionFull && (regionFull === "" || full.startsWith(`${regionFull}/`))) {
+                    // A path below a directory region constrains the files under it, not the whole region.
+                    for (const f of fileNodesUnder(full))
+                        matched.push({ entry, granularity: "path", to: `file:${f}` });
+                }
+            }
+            else if (entry.startsWith("member:")) {
+                if (member !== null && entry.slice("member:".length) === member)
+                    matched.push({ entry, granularity: "member", to: rid });
+            }
+            else {
+                const issue = entry.match(ISSUE);
+                if (issue && origin !== null && issue[1].toLowerCase() === origin && commitRefs.has(issue[2]))
+                    matched.push({ entry, granularity: "issue", to: rid });
+                else if (contractIds.has(entry))
+                    matched.push({ entry, granularity: "contract", to: `contract:${entry}` });
+            }
+        }
+        return matched;
+    };
+    for (const k of kinds) {
+        if (!k.records || k.records.loaded.kind.work)
+            continue;
+        for (const v of k.records.views) {
+            if (v.id === null)
+                continue;
+            decisionById.set(`${k.records.loaded.kind.name}/${v.id}`, { view: v, kind: k });
+            const matched = matchConstrains(k, v);
+            if (matched.length === 0)
+                continue;
+            const node = decisionNode(k, v);
+            for (const m of matched) {
+                edges.push({ kind: "constrains", from: node.id, to: m.to, granularity: m.granularity, entry: m.entry });
+                if (m.to === rid || m.granularity === "contract")
+                    node.constrains.push({ entry: m.entry, granularity: m.granularity });
+            }
+            if (node.constrains.length > 0)
+                covering.push({ view: v, kind: k, node });
+        }
+    }
+    // Supersession chains, both ways, as records derives them.
+    const queue = [...nodes.values()].filter((n) => n.kind === "decision");
+    while (queue.length > 0) {
+        const d = queue.shift();
+        const related = [];
+        if (d.supersededBy)
+            related.push(`${d.recordKind}/${d.supersededBy}`);
+        for (const [key, { view }] of decisionById)
+            if (key.startsWith(`${d.recordKind}/`) && view.supersededBy === d.record)
+                related.push(key);
+        for (const key of related) {
+            const hit = decisionById.get(key);
+            if (!hit)
+                continue;
+            const id = decisionId(hit.kind, hit.view.id);
+            if (nodes.has(id))
+                continue;
+            queue.push(decisionNode(hit.kind, hit.view));
+        }
+    }
+    const decisions = [...nodes.values()].filter((n) => n.kind === "decision");
+    for (const d of decisions) {
+        if (d.supersededBy) {
+            const to = `record:${d.recordKind}/${d.supersededBy}`;
+            if (nodes.has(to))
+                edges.push({ kind: "supersedes", from: to, to: d.id });
+        }
+    }
+    // 4. The artifacts those decisions pin, and their evidence entries.
+    const pinsOf = new Map();
+    for (const d of decisions) {
+        const hit = decisionById.get(`${d.recordKind}/${d.record}`);
+        const kind = hit.kind.records.loaded.kind;
+        for (const a of hit.view.assets) {
+            const list = pinsOf.get(a.path) ?? [];
+            list.push({ decision: d, state: a.state, sha256: a.sha256, actual: a.actual });
+            pinsOf.set(a.path, list);
+        }
+        const evidence = kind.pins ? hit.view.data?.[kind.pins.field] : undefined;
+        if (Array.isArray(evidence)) {
+            for (const e of evidence) {
+                if (e === null || typeof e !== "object" || Array.isArray(e))
+                    continue;
+                const entry = e;
+                const hashed = typeof entry.sha256 === "string" && SHA256.test(entry.sha256);
+                if (isWorkspacePath(entry.path)) {
+                    if (hashed)
+                        continue;
+                    const list = pinsOf.get(entry.path) ?? [];
+                    list.push({ decision: d, state: "unpinned", sha256: null, actual: null });
+                    pinsOf.set(entry.path, list);
+                    find("intent-evidence-unpinned", `${d.record} names ${entry.path} as evidence with no sha256, so a later edit can't be told from what was decided on`, [d.id, `artifact:${entry.path}`]);
+                    continue;
+                }
+                if (typeof entry.url !== "string")
+                    continue;
+                const ev = add({
+                    id: `evidence:${entry.url}`,
+                    kind: "evidence",
+                    ref: entry.url,
+                    plugin: null,
+                    data: { title: stringOr(entry.title), url: entry.url, path: null, as_of: stringOr(entry.as_of), sha256: hashed ? entry.sha256 : null },
+                });
+                edges.push({ kind: "cites-evidence", from: d.id, to: ev.id });
+                if (!hashed)
+                    find("intent-evidence-unpinned", `${d.record} cites ${entry.url} with no hash, so what the page said when it was decided can't be checked`, [d.id, ev.id]);
+            }
+        }
+    }
+    for (const [path, pins] of pinsOf) {
+        const aid = `artifact:${path}`;
+        const current = pins.filter((p) => p.decision.supersededBy === null && p.state !== "unpinned");
+        const worst = [...current].sort((a, b) => PIN_ORDER.indexOf(a.state) - PIN_ORDER.indexOf(b.state))[0];
+        add({
+            id: aid,
+            kind: "artifact",
+            path,
+            anchor: null,
+            pinnedSha256: worst?.sha256 ?? null,
+            currentSha256: pins.find((p) => p.state !== "unpinned")?.actual ?? null,
+            pinState: worst?.state ?? "unpinned",
+        });
+        for (const p of pins) {
+            edges.push({ kind: "pins", from: p.decision.id, to: aid, pinnedSha256: p.sha256, pinState: p.state });
+            if (p.state === "drifted")
+                find("intent-pin-drifted", `${path} changed after ${p.decision.record} pinned it: sha256 ${p.sha256?.slice(0, 12)} is pinned, the file hashes to ${p.actual?.slice(0, 12)}`, [p.decision.id, aid]);
+            if (p.state === "missing")
+                find("intent-pin-missing", `${p.decision.record} pins ${path}, which does not exist${located.tree.label}`, [p.decision.id, aid]);
+            // Stale against a current decision constraining the region (#2686): the
+            // record it supersedes pinned the same hash, and the file has not
+            // changed since. A decision in the graph only through supersession
+            // does not govern the region, so its stale pin is not raised here.
+            if (p.state === "stale" && p.decision.supersededBy === null && p.decision.constrains.length > 0) {
+                const old = pins.find((o) => o.decision.supersededBy === p.decision.record && o.decision.recordKind === p.decision.recordKind && o.sha256 === p.sha256);
+                find("intent-pin-stale", `${path} is pinned by ${p.decision.record} at sha256 ${p.sha256?.slice(0, 12)}, the hash ${old ? old.decision.record : "the record it supersedes"} pinned, and it has not changed since: the decision moved on and the artifact did not`, [p.decision.id, aid, ...(old ? [old.decision.id] : [])]);
+            }
+        }
+        if (!worst && pins.some((p) => p.state !== "unpinned")) {
+            find("intent-artifact-unpinned", `${path} was pinned by ${[...new Set(pins.map((p) => p.decision.record))].join(", ")}, and no current decision pins it`, [aid, ...new Set(pins.map((p) => p.decision.id))]);
+        }
+    }
+    // A path constraint that no longer resolves (#2650 A15).
+    for (const d of decisions) {
+        const hit = decisionById.get(`${d.recordKind}/${d.record}`);
+        const field = hit.kind.records.loaded.kind.constrains?.field;
+        const list = field ? hit.view.data?.[field] : undefined;
+        if (!Array.isArray(list))
+            continue;
+        const kindPrefix = hit.kind.records.workspaceRoot === "." ? "" : hit.kind.records.workspaceRoot;
+        for (const entry of list) {
+            if (typeof entry !== "string" || !entry.startsWith("path:"))
+                continue;
+            const p = entry.slice("path:".length);
+            if (!isWorkspacePath(p))
+                continue;
+            const full = joinPath(kindPrefix, p);
+            const inTree = workspacePrefix === "" ? full : full.startsWith(`${workspacePrefix}/`) ? full.slice(workspacePrefix.length + 1) : undefined;
+            if (inTree !== undefined && located.tree.stat(inTree) === undefined) {
+                find("intent-constraint-lost", `${d.record} constrains ${p}, which does not exist${located.tree.label}`, [d.id]);
+            }
+        }
+    }
+    // Which decisions covered the region at each commit's time: from the commit
+    // that decided the record, or added it when it is not approved, until the
+    // commit that opened the window of the record superseding it.
+    const windows = new Map();
+    if (rev) {
+        for (const c of covering) {
+            const opened = windowOpening(top, rev, c.view);
+            const successor = c.view.supersededBy ? decisionById.get(`${c.node.recordKind}/${c.view.supersededBy}`) : undefined;
+            const replaced = successor ? windowOpening(top, rev, successor.view) : null;
+            windows.set(c.node.id, { from: opened ? descendants(top, opened, rev) : new Set(), until: replaced ? descendants(top, replaced, rev) : null });
+        }
+    }
+    const workKinds = kinds.filter((k) => k.records?.loaded.kind.work);
+    const readsWork = workKinds.length > 0;
+    const workAll = [];
+    const workByKey = new Map();
+    for (const k of workKinds) {
+        for (const v of k.records.views) {
+            if (v.id === null)
+                continue;
+            const hit = { view: v, kind: k };
+            workAll.push(hit);
+            const key = `${k.records.loaded.kind.name}/${v.id}`;
+            if (!workByKey.has(key))
+                workByKey.set(key, hit);
+        }
+    }
+    const workSpec = (h) => h.kind.records.loaded.kind.work;
+    const workNode = (h) => {
+        if (h.node)
+            return h.node;
+        const kind = h.kind.records.loaded.kind;
+        const v = h.view;
+        h.node = add({
+            id: `record:${kind.name}/${v.id}`,
+            kind: "work",
+            recordKind: kind.name,
+            record: v.id,
+            path: v.path,
+            title: stringOr(v.data?.title),
+            state: v.state,
+            closed: v.state !== null && (kind.closedStates ?? []).includes(v.state),
+            valid: v.valid,
+            reasons: v.reasons,
+            provenance: { level: v.provenance.level, commit: v.provenance.commit, reason: v.provenance.reason },
+            owner: stringOr(v.data?.owner),
+            ready: v.ready ?? false,
+            blockedBy: v.blockedBy ?? [],
+            implements: v.implements ?? [],
+            needs: idList(v.data, kind.work.needs),
+            source: gapSource(v.data),
+            supersededBy: v.supersededBy,
+            constrains: [],
+            warnings: v.warnings.filter((w) => WORK_WARNING_CODES.includes(w.code)),
+        });
+        return h.node;
+    };
+    /** The decision kind a work kind names, when it is among the kinds read. */
+    const decisionKindOf = (k) => {
+        const file = realpathOr(resolve(dirname(k.records.loaded.file), k.records.loaded.kind.work.decisions));
+        return kinds.find((x) => x.records && !x.records.loaded.kind.work && realpathOr(x.records.loaded.file) === file);
+    };
+    /** The node ids of the decisions a work item implements, among the decisions read. */
+    const implementedIds = (h) => {
+        const dk = decisionKindOf(h.kind);
+        if (!dk)
+            return [];
+        return idList(h.view.data, workSpec(h).implements)
+            .map((d) => decisionById.get(`${dk.records.loaded.kind.name}/${d}`))
+            .filter((x) => x !== undefined)
+            .map((x) => decisionId(x.kind, x.view.id));
+    };
+    /** The work items implementing a decision, leaving out dropped ones: a closed state other than done. */
+    const implementersOf = (d) => workAll.filter((h) => {
+        const kind = h.kind.records.loaded.kind;
+        const dropped = h.view.state !== null && h.view.state !== kind.work.done && (kind.closedStates ?? []).includes(h.view.state);
+        return !dropped && implementedIds(h).includes(d.id);
+    });
+    const workCovering = [];
+    for (const h of workAll) {
+        const matched = matchConstrains(h.kind, h.view);
+        if (matched.length === 0)
+            continue;
+        const node = workNode(h);
+        for (const m of matched) {
+            edges.push({ kind: "constrains", from: node.id, to: m.to, granularity: m.granularity, entry: m.entry });
+            if (m.to === rid || m.granularity === "contract")
+                node.constrains.push({ entry: m.entry, granularity: m.granularity });
+        }
+        if (node.constrains.length > 0)
+            workCovering.push(h);
+    }
+    const workWindows = new Map();
+    if (rev) {
+        for (const h of workCovering) {
+            const kind = h.kind.records.loaded.kind;
+            const added = addingCommit(top, rev, h.view.path);
+            const closing = kind.stateField ? closingCommit(top, rev, h.view.path, kind.stateField, kind.closedStates ?? []) : null;
+            const until = closing ? descendants(top, closing, rev) : null;
+            if (closing)
+                until.delete(closing);
+            workWindows.set(h.node.id, { from: added ? descendants(top, added, rev) : new Set(), until });
+        }
+    }
+    const inWorkWindow = (h, sha) => {
+        const w = workWindows.get(h.node.id);
+        return !!w && w.from.has(sha) && !w.until?.has(sha);
+    };
+    // The records chant's own trailers name (#3149): a Chant-Record of a kind
+    // read, and the work item a Chant-Lease was taken on. The commit carries
+    // each, and is the own work of a decision it names or that a work item it
+    // names implements.
+    const recordKinds = new Map(kinds.filter((k) => k.records).map((k) => [k.records.loaded.kind.name, k]));
+    /** The work item a run worked on and the records it names, among the kinds read, deduplicated. */
+    const runTargets = (r) => {
+        const out = [];
+        const push = (x) => {
+            if (!out.some((o) => o.node === x.node))
+                out.push(x);
+        };
+        if (r.unit) {
+            const named = r.unit.kind ? workKinds.filter((k) => k.records.loaded.kind.name === r.unit.kind) : workKinds;
+            const hits = named.map((k) => workByKey.get(`${k.records.loaded.kind.name}/${r.unit.id}`)).filter((h) => h !== undefined);
+            if (hits.length === 1)
+                push({ node: workNode(hits[0]).id, work: hits[0] });
+        }
+        for (const ref of r.records) {
+            const k = recordKinds.get(ref.kind);
+            if (!k)
+                continue;
+            if (k.records.loaded.kind.work) {
+                const h = workByKey.get(`${ref.kind}/${ref.id}`);
+                if (h)
+                    push({ node: workNode(h).id, work: h });
+                continue;
+            }
+            const hit = decisionById.get(`${ref.kind}/${ref.id}`);
+            if (hit)
+                push({ node: decisionNode(hit.kind, hit.view).id, decision: `${ref.kind}/${ref.id}` });
+        }
+        return out;
+    };
+    for (const t of touched) {
+        const c = nodes.get(`commit:${t.sha}`);
+        const j = joined.get(t.sha);
+        if (!c || !j)
+            continue;
+        const carry = (to) => {
+            if (j.carries.includes(to))
+                return;
+            j.carries.push(to);
+            edges.push({ kind: "carries", from: c.id, to });
+        };
+        const carryWork = (h) => {
+            const node = workNode(h);
+            carry(node.id);
+            j.decisions.push(...implementedIds(h).map((id) => id.slice("record:".length)));
+            return node.id;
+        };
+        // The commit's own trailers, and a followed squash's original commits' (#3035).
+        for (const joins of [c.joins, ...(c.squash?.commits ?? []).map((o) => o.joins)]) {
+            for (const r of joins.records) {
+                const k = recordKinds.get(r.kind);
+                if (!k)
+                    continue;
+                if (k.records.loaded.kind.work) {
+                    const h = workByKey.get(`${r.kind}/${r.id}`);
+                    if (h)
+                        r.node = carryWork(h);
+                    continue;
+                }
+                const hit = decisionById.get(`${r.kind}/${r.id}`);
+                if (!hit)
+                    continue;
+                r.node = decisionNode(hit.kind, hit.view).id;
+                carry(r.node);
+                j.decisions.push(`${r.kind}/${r.id}`);
+            }
+            const item = joins.lease?.item;
+            if (item) {
+                const hits = workKinds.map((k) => workByKey.get(`${k.records.loaded.kind.name}/${item}`)).filter((h) => h !== undefined);
+                if (hits.length === 1)
+                    carryWork(hits[0]);
+            }
+        }
+        // The runs that made the commit (#3034): its run's work item and the
+        // records the run names are carried as a Chant-Lease and a Chant-Record are.
+        for (const ref of runJoins.refs.get(t.sha) ?? []) {
+            const r = runJoins.runs.get(ref.id);
+            if (!r)
+                continue;
+            for (const target of runTargets(r)) {
+                if (target.work)
+                    carryWork(target.work);
+                else if (target.decision) {
+                    carry(target.node);
+                    j.decisions.push(target.decision);
+                }
+            }
+        }
+    }
+    // Each recorded run in the walk to the work item and records it worked on (#3034).
+    for (const n of [...nodes.values()]) {
+        if (n.kind !== "run")
+            continue;
+        const r = runJoins.runs.get(n.run);
+        if (!r)
+            continue;
+        for (const target of runTargets(r))
+            edges.push({ kind: "worked-on", from: n.id, to: target.node });
+    }
+    // Each work item in the graph, those its commits and runs carry included, to the decisions it implements and the items it needs.
+    for (const h of workAll.filter((x) => x.node)) {
+        for (const id of implementedIds(h)) {
+            const hit = decisionById.get(id.slice("record:".length));
+            edges.push({ kind: "implements", from: h.node.id, to: decisionNode(hit.kind, hit.view).id });
+        }
+        for (const n of idList(h.view.data, workSpec(h).needs)) {
+            const hit = workByKey.get(`${h.kind.records.loaded.kind.name}/${n}`);
+            if (hit)
+                edges.push({ kind: "needs", from: h.node.id, to: workNode(hit).id });
+        }
+    }
+    const coveredAt = (sha, granularities) => covering.filter((c) => {
+        if (!c.node.constrains.some((x) => granularities.includes(x.granularity)))
+            return false;
+        const w = windows.get(c.node.id);
+        return !!w && w.from.has(sha) && !w.until?.has(sha);
+    });
+    const readsRecords = kinds.some((k) => k.records);
+    // A decision's own work: a commit whose unit, or that unit's contract, names
+    // the decision, or whose unit serves a contract the decision constrains; or
+    // a commit whose own trailers name the decision, or a work item implementing it.
+    const ownWork = (j, d) => (!!j.unit || j.carries.length > 0) && (j.decisions.some((x) => x === d.record || x === `${d.recordKind}/${d.record}`) || d.constrains.some((x) => x.granularity === "contract" && j.contracts.includes(x.entry)));
+    for (const t of touched) {
+        const c = nodes.get(`commit:${t.sha}`);
+        if (!c)
+            continue;
+        const j = joined.get(t.sha);
+        if (readsRecords) {
+            const inWindow = coveredAt(t.sha, ["path"]);
+            for (const w of inWindow)
+                edges.push({ kind: "within", from: c.id, to: w.node.id, state: ownWork(j, w.node) ? "decided" : "decided-by-window" });
+            c.state = inWindow.length === 0 ? "undecided" : inWindow.some((w) => ownWork(j, w.node)) ? "decided" : "decided-by-window";
+        }
+        // A commit in a work item's window is worked; its own state still comes from decisions (#2683).
+        for (const h of workCovering) {
+            if (h.node.constrains.some((x) => x.granularity === "path") && inWorkWindow(h, t.sha))
+                edges.push({ kind: "within", from: c.id, to: h.node.id, state: "worked" });
+        }
+        if (readsRecords && c.state === "undecided") {
+            find("intent-commit-undecided", `${t.sha.slice(0, 8)} changed the region when no decision constrained ${region.path} by path`, [c.id, rid]);
+        }
+        if (readsRecords && !j.unit && j.carries.length === 0 && c.pullRequest === null && coveredAt(t.sha, ["path", "member", "contract", "issue"]).length === 0) {
+            find("intent-commit-bare", `${t.sha.slice(0, 8)} names no unit, no record, no pull request and no decision`, [c.id]);
+        }
+        const claims = [...new Set(j.authorship)].filter((key) => hasTrailer(c.trailers, key));
+        if (claims.length > 0 && c.signature.level !== "attested") {
+            find("intent-trailer-unverified", `${t.sha.slice(0, 8)} carries ${claims.join(", ")}, and the commit is ${c.signature.level}, so nothing vouches for the trailer`, [c.id]);
+        }
+    }
+    // Findings about the region as a whole.
+    if (readsRecords) {
+        const current = covering.filter((c) => c.node.supersededBy === null);
+        if (covering.length === 0) {
+            find("intent-region-unconstrained", `no decision constrains ${region.path}`, [rid]);
+        }
+        else if (current.length === 0) {
+            find("intent-decision-superseded-live", `every decision constraining ${region.path} is superseded: ${covering.map((c) => `${c.node.record} by ${c.node.supersededBy}`).join(", ")}`, [rid, ...covering.map((c) => c.node.id)]);
+        }
+        else if (current.every((c) => !c.node.closed)) {
+            find("intent-decision-provisional", `the decisions constraining ${region.path} are ${[...new Set(current.map((c) => c.node.state ?? "stateless"))].join(" or ")}, and none is in a closed state`, [rid, ...current.map((c) => c.node.id)]);
+        }
+        // A current decision with a dissent nobody addressed or withdrew (#2686), from its quorum.
+        for (const c of current) {
+            const open = c.view.quorum?.openConcerns ?? [];
+            if (open.length === 0)
+                continue;
+            const principals = [...new Set(open.map((o) => o.principal))];
+            findings.push({
+                id: `finding:intent-decision-contested:${findings.filter((f) => f.code === "intent-decision-contested").length + 1}`,
+                kind: "finding",
+                code: "intent-decision-contested",
+                message: `${c.node.record} constrains ${region.path} and has ${open.length} open ${open.length === 1 ? "concern" : "concerns"}, from ${open.map((o) => o.reviewer).join(", ")}: a dissent neither addressed nor withdrawn`,
+                concerns: [c.node.id, rid],
+                openConcerns: { count: open.length, principals },
+            });
+        }
+        const granularities = new Set(covering.flatMap((c) => c.node.constrains.map((x) => x.granularity)));
+        if (covering.length > 0 && !granularities.has("path") && granularities.has("member")) {
+            find("intent-constraint-coarse", `${region.path} is constrained only through its member, ${member}`, [rid, ...covering.map((c) => c.node.id)]);
+        }
+    }
+    // Findings about work items (#2683).
+    if (readsWork) {
+        for (const c of covering) {
+            if (c.node.supersededBy !== null || !isDecided(c.kind.records.loaded.kind, c.node.state))
+                continue;
+            if (implementersOf(c.node).length > 0)
+                continue;
+            const w = windows.get(c.node.id);
+            if (w && touched.some((t) => w.from.has(t.sha) && !w.until?.has(t.sha)))
+                continue;
+            find("intent-decision-unimplemented", `${c.node.record} is ${c.node.state} and constrains ${region.path}, and no work item that is not dropped implements it, and no commit changed the region in its window`, [c.node.id, rid]);
+        }
+        for (const h of workCovering) {
+            const node = h.node;
+            if (node.blockedBy.length === 0)
+                continue;
+            const worked = touched.filter((t) => inWorkWindow(h, t.sha));
+            if (worked.length === 0)
+                continue;
+            const waiting = node.blockedBy.map((b) => `${b.id} (${b.state ?? "unknown"})`).join(", ");
+            const blockers = node.blockedBy.map((b) => workByKey.get(`${node.recordKind}/${b.id}`)).filter((x) => x !== undefined).map((x) => workNode(x).id);
+            find("intent-work-blocked", `${node.record} has ${worked.length} ${worked.length === 1 ? "commit" : "commits"} in its window while it waits on ${waiting}`, [node.id, ...worked.map((t) => `commit:${t.sha}`), ...blockers]);
+        }
+        for (const d of [...nodes.values()].filter((n) => n.kind === "decision")) {
+            const own = edges.filter((e) => e.kind === "within" && e.to === d.id && e.state === "decided").map((e) => e.from);
+            if (own.length === 0)
+                continue;
+            const impl = implementersOf(d);
+            if (impl.length === 0 || impl.some((h) => h.view.state === workSpec(h).done))
+                continue;
+            find("intent-work-open-decided-code", `${own.length} ${own.length === 1 ? "commit" : "commits"} in ${region.path} ${own.length === 1 ? "is" : "are"} ${d.record}'s own work, and ${impl.map((h) => `${h.view.id} is ${h.view.state ?? "stateless"}`).join(", ")}: the code says done and the queue says not`, [d.id, ...own, ...impl.map((h) => workNode(h).id)]);
+        }
+    }
+    // 5. Links: the declared member links that touch the region's member, read in source.
+    if (member) {
+        let rows = [];
+        try {
+            const groups = resolveGroups(declaration, located.tree);
+            const kindsRegistry = loadKindRegistry(declaration.pins, located.rootOnDisk).registry;
+            rows = resolveLinks(declaration, sourceMemberHandles(declaration, located.tree, groups, kindsRegistry)).filter((r) => r.origin === "declared");
+        }
+        catch (err) {
+            if (!(err instanceof WorkspaceReadError))
+                throw err;
+        }
+        rows.forEach((row, i) => {
+            const producer = "producer" in row ? row.producer : null;
+            if (row.consumer !== member && producer !== member)
+                return;
+            const { pointer: _pointer, ...clean } = row;
+            add({ id: `link:${i + 1}`, kind: "link", row: clean });
+            memberNode(row.consumer);
+            if (producer && declaration.members.some((m) => m.name === producer)) {
+                memberNode(producer);
+                edges.push({ kind: "links", from: `member:${row.consumer}`, to: `member:${producer}` });
+            }
+        });
+    }
+    // Findings last, in the order of the code list, so the same walk always prints the same way.
+    findings.sort((x, y) => INTENT_FINDING_CODES.indexOf(x.code) - INTENT_FINDING_CODES.indexOf(y.code));
+    // Then the plugins' findings, in commit order, each about its commit and the nodes its refs name.
+    const resolveRef = (ref) => {
+        if (nodes.has(ref))
+            return ref;
+        for (const prefix of ["commit", "unit", "contract", "evidence", "artifact", "file", "member"])
+            if (nodes.has(`${prefix}:${ref}`))
+                return `${prefix}:${ref}`;
+        for (const n of nodes.values()) {
+            if (n.kind === "decision" && (ref === n.record || ref === `${n.recordKind}/${n.record}`))
+                return n.id;
+            if (n.kind === "commit" && /^[0-9a-f]{7,}$/.test(ref) && n.sha.startsWith(ref))
+                return n.id;
+        }
+        return undefined;
+    };
+    for (const { commit, plugin, finding } of pluginFindings) {
+        const code = finding.code;
+        const refs = finding.refs ?? [];
+        const concerns = [...new Set([commit, ...refs.map(resolveRef).filter((x) => x !== undefined)])];
+        findings.push({ id: `finding:${code}:${findings.filter((f) => f.code === code).length + 1}`, kind: "finding", code, message: finding.message, concerns, plugin, refs });
+    }
+    // A finding a work item addresses (#2683): the item came from that gap on
+    // this region, or it implements the decision a drifted, missing or stale pin, or a
+    // plugin's finding, is about. A done item whose gap still fires here gets
+    // work-done-gap-open.
+    if (readsWork) {
+        // Implementing a decision closes the gaps between it and the code or its
+        // artifacts, not gaps in the decision record itself (its review, its
+        // granularity, its evidence), so only these findings, and a plugin's,
+        // count as addressed through implements.
+        const CLOSED_BY_IMPLEMENTING = new Set(["intent-pin-drifted", "intent-pin-missing", "intent-pin-stale"]);
+        const fromGap = (h, code) => {
+            const src = gapSource(h.view.data);
+            if (src === null || src.finding !== code)
+                return false;
+            const parsed = parseRegion(src.region);
+            if ("error" in parsed)
+                return false;
+            const kindPrefix = h.kind.records.workspaceRoot === "." ? "" : h.kind.records.workspaceRoot;
+            const full = joinPath(kindPrefix, parsed.path);
+            const contains = (a, b) => a === b || a === "" || b.startsWith(`${a}/`);
+            if (!contains(full, regionFull) && !contains(regionFull, full))
+                return false;
+            if (full === regionFull && parsed.lines && region.lines)
+                return parsed.lines.start <= region.lines.end && region.lines.start <= parsed.lines.end;
+            return true;
+        };
+        for (const f of findings) {
+            const by = [];
+            for (const h of workAll) {
+                const gap = fromGap(h, f.code);
+                const viaDecision = (CLOSED_BY_IMPLEMENTING.has(f.code) || isPluginCode(f.code)) && implementedIds(h).some((id) => f.concerns.includes(id));
+                if (gap || viaDecision)
+                    by.push(h);
+                if (gap && h.view.state === workSpec(h).done) {
+                    const node = workNode(h);
+                    if (!node.warnings.some((w) => w.code === "work-done-gap-open")) {
+                        node.warnings.push({ code: "work-done-gap-open", message: `${node.record} is ${h.view.state}, and ${f.code}, the gap it came from, still fires on ${region.path}` });
+                    }
+                }
+            }
+            f.addressed = by.length > 0;
+            f.addressedBy = by.map((h) => ({ id: h.view.id, state: h.view.state }));
+            for (const h of by)
+                edges.push({ kind: "addressed-by", from: f.id, to: workNode(h).id });
+        }
+    }
+    // Reviews that led to a work item in the graph (#3154, E21): a session's comments[].follow_ups name it.
+    const workNodes = [...nodes.values()].filter((n) => n.kind === "work");
+    if (workNodes.length > 0) {
+        const byRef = new Map(workNodes.map((n) => [`${n.recordKind}:${n.record}`, n]));
+        for (const k of kinds) {
+            const loaded = k.records?.loaded.kind;
+            if (!loaded?.session)
+                continue;
+            for (const v of k.records.views) {
+                if (v.id === null || !v.data)
+                    continue;
+                const hits = new Map();
+                const note = (refs, comment) => {
+                    if (!Array.isArray(refs))
+                        return;
+                    for (const ref of refs) {
+                        const n = typeof ref === "string" ? byRef.get(ref) : undefined;
+                        if (!n)
+                            continue;
+                        const list = hits.get(n) ?? [];
+                        if (comment !== null && !list.includes(comment))
+                            list.push(comment);
+                        hits.set(n, list);
+                    }
+                };
+                note(v.data.follow_ups, null);
+                const comments = Array.isArray(v.data.comments) ? v.data.comments : [];
+                comments.forEach((c, i) => note(c?.follow_ups, i + 1));
+                for (const [n, list] of hits) {
+                    (n.reviews ?? (n.reviews = [])).push({ id: `record:${loaded.name}/${v.id}`, recordKind: loaded.name, record: v.id, path: v.path, state: v.state, comments: list.sort((a, b) => a - b) });
+                }
+            }
+        }
+    }
+    for (const f of findings)
+        nodes.set(f.id, f);
+    const why = explain();
+    const all = [...nodes.values()];
+    return {
+        doc: {
+            ...head,
+            at: located.at,
+            workspace: { name: declaration.name, root: located.root },
+            region: rid,
+            history: { rev, follows: region.lines ? "line-range" : type === "file" ? "file" : "directory", shallow },
+            kinds: kinds.map((k) => ({ file: k.display, name: k.name, records: k.records?.loaded.kind.name ?? null, joins: k.joins?.form ?? null })),
+            nodes: all,
+            edges,
+            reasons,
+            summary: {
+                commits: all.filter((n) => n.kind === "commit").length,
+                decisions: all.filter((n) => n.kind === "decision").length,
+                artifacts: all.filter((n) => n.kind === "artifact").length,
+                findings: findings.length,
+            },
+            why,
+        },
+        failed: reasons.some((r) => r.code === "intent-plugin-failed"),
+    };
+    /** "Why is it like this" over the region (#3034): who made its current lines, and the decisions governing it, most relevant first. */
+    function explain() {
+        const hunksOf = (run, sha) => runJoins.runs.get(run)?.commits.find((c) => c.sha === sha)?.hunks ?? null;
+        const joinOf = (run, sha) => (runJoins.refs.get(sha) ?? []).find((r) => r.id === run)?.joinedBy ?? [];
+        const joinsOf = (runs, shas) => {
+            const all = new Set(runs.flatMap((id) => shas.flatMap((sha) => joinOf(id, sha))));
+            return RUN_JOIN_ORDER.filter((j) => all.has(j));
+        };
+        // For a followed squash (#3035), the original commit behind each of its lines, by blame at the pull request's head.
+        const origins = new Map();
+        const originOf = (sha, path, line) => {
+            const f = follows.get(sha);
+            if (!f?.followed || !f.head)
+                return { squash: false, origin: undefined };
+            const key = `${sha}\0${path}`;
+            if (!origins.has(key))
+                origins.set(key, squashLineOrigins(top, sha, f.head, path, new Set(f.commits)));
+            return { squash: true, origin: origins.get(key)?.get(line) };
+        };
+        // Each current line: its commit, and the runs that wrote it.
+        const who = blamed.map((b) => {
+            if (b.sha === null)
+                return { line: b.line, sha: null, runs: [], narrowedBy: null, via: undefined };
+            const sha = b.sha;
+            const { squash, origin } = originOf(sha, b.origPath, b.origLine);
+            const via = squash ? (origin ? [origin] : []) : undefined;
+            // On a squash line blame at the head traced to one original, a run joined only through the other originals didn't write it.
+            const refs = (runJoins.refs.get(sha) ?? []).filter((r) => !origin || r.joinedBy.some((j) => j !== "squash") || (r.via ?? []).includes(origin)).map((r) => r.id);
+            const withHunks = refs.filter((id) => hunksOf(id, sha) !== null);
+            if (withHunks.length === 0)
+                return { line: b.line, sha, runs: refs, narrowedBy: null, via };
+            const wrote = withHunks.filter((id) => hunksOf(id, sha).some((h) => h.path === b.origPath && h.start <= b.origLine && b.origLine <= h.end));
+            // A run that recorded its hunks and doesn't cover the line didn't write it; a run that recorded none may have.
+            return { line: b.line, sha, runs: wrote.length > 0 ? wrote : refs.filter((id) => !withHunks.includes(id)), narrowedBy: "hunks", via };
+        });
+        const spans = [];
+        for (const w of who) {
+            const last = spans[spans.length - 1];
+            const via = w.via;
+            if (last && last.end === w.line - 1 && last.sha === w.sha && last.narrowedBy === w.narrowedBy && last.runs.join("\0") === w.runs.map((r) => `run:${r}`).join("\0") && last.via?.join("\0") === via?.join("\0")) {
+                last.end = w.line;
+                continue;
+            }
+            spans.push({ start: w.line, end: w.line, commit: w.sha ? `commit:${w.sha}` : null, sha: w.sha, runs: w.runs.map((r) => `run:${r}`), narrowedBy: w.narrowedBy, joinedBy: w.sha ? joinsOf(w.runs, [w.sha]) : [], ...(via ? { via } : {}) });
+        }
+        const ranges = (lines) => {
+            const out = [];
+            for (const l of lines) {
+                const last = out[out.length - 1];
+                if (last && last.end === l - 1)
+                    last.end = l;
+                else
+                    out.push({ start: l, end: l });
+            }
+            return out;
+        };
+        // The decisions, most relevant first.
+        const decisionNodes = [...nodes.values()].filter((n) => n.kind === "decision");
+        const ownLines = (d) => who.filter((w) => w.sha !== null && ownWork(joined.get(w.sha) ?? { contracts: [], authorship: [], decisions: [], carries: [] }, d)).length;
+        const ORDER = ["carried", "path", "contract", "issue", "member", "related"];
+        const ranked = decisionNodes.map((d) => {
+            const lines = ownLines(d);
+            const carried = lines > 0 || (fileLines === null && touched.some((t) => ownWork(joined.get(t.sha) ?? { contracts: [], authorship: [], decisions: [], carries: [] }, d)));
+            const granularities = new Set(d.constrains.map((c) => c.granularity));
+            const relevance = carried ? "carried" : (["path", "contract", "issue", "member"].find((g) => granularities.has(g)) ?? "related");
+            // A narrower path constraint is more specific to the region.
+            const specificity = Math.max(0, ...d.constrains.filter((c) => c.granularity === "path").map((c) => c.entry.length));
+            return { d, entry: { decision: d.id, relevance, current: d.supersededBy === null, closed: d.closed, lines }, specificity };
+        });
+        ranked.sort((a, b) => Number(b.entry.current) - Number(a.entry.current) ||
+            ORDER.indexOf(a.entry.relevance) - ORDER.indexOf(b.entry.relevance) ||
+            b.entry.lines - a.entry.lines ||
+            Number(b.entry.closed) - Number(a.entry.closed) ||
+            b.specificity - a.specificity ||
+            (b.d.decidedIn?.date ?? "").localeCompare(a.d.decidedIn?.date ?? "") ||
+            a.d.id.localeCompare(b.d.id));
+        const decisions = ranked.map((r) => r.entry);
+        // The runs that wrote the current lines, most lines first; for a directory, every run in the walk.
+        const runNodes = [...nodes.values()].filter((n) => n.kind === "run");
+        const runEntry = (n, lines, commits) => {
+            const r = runJoins.runs.get(n.run);
+            const targets = edges.filter((e) => e.kind === "worked-on" && e.from === n.id).map((e) => nodes.get(e.to));
+            const work = r?.unit ? targets.find((t) => t?.kind === "work" && t.record === r.unit.id) : undefined;
+            const carried = new Set();
+            for (const t of targets) {
+                if (t?.kind === "decision")
+                    carried.add(t.id);
+                if (t?.kind === "work")
+                    for (const e of edges)
+                        if (e.kind === "implements" && e.from === t.id)
+                            carried.add(e.to);
+            }
+            const shas = commits.map((c) => c.slice("commit:".length));
+            return { run: n.id, lines, commits, unit: r?.unit ? { id: r.unit.id, kind: r.unit.kind, node: work?.id ?? null } : null, decisions: [...carried], joinedBy: joinsOf([n.run], shas) };
+        };
+        let runs;
+        if (fileLines !== null) {
+            const tally = new Map();
+            for (const w of who) {
+                for (const id of w.runs) {
+                    const t = tally.get(id) ?? tally.set(id, { lines: 0, commits: new Set() }).get(id);
+                    t.lines++;
+                    t.commits.add(`commit:${w.sha}`);
+                }
+            }
+            runs = [...tally]
+                .map(([id, t]) => ({ n: nodes.get(`run:${id}`), t }))
+                .filter((x) => x.n !== undefined)
+                .sort((a, b) => b.t.lines - a.t.lines || (b.n.startedAt ?? "").localeCompare(a.n.startedAt ?? "") || a.n.run.localeCompare(b.n.run))
+                .map((x) => runEntry(x.n, x.t.lines, [...x.t.commits]));
+        }
+        else {
+            runs = runNodes
+                .sort((a, b) => (b.startedAt ?? "").localeCompare(a.startedAt ?? "") || a.run.localeCompare(b.run))
+                .map((n) => runEntry(n, 0, edges.filter((e) => e.kind === "made-by" && e.to === n.id).map((e) => e.from)));
+        }
+        const explained = decisions.some((d) => d.current && d.relevance !== "related");
+        const gaps = [];
+        if (!explained) {
+            gaps.push({
+                code: "intent-why-no-decision",
+                message: readsRecords ? `no current decision governs ${region.path}, and none is carried out by what made its lines` : `no record kind was read, so no decision can account for ${region.path}`,
+            });
+        }
+        const committed = who.filter((w) => w.sha !== null);
+        if (fileLines !== null ? committed.length > 0 && committed.every((w) => w.runs.length === 0) : touched.length > 0 && runNodes.length === 0) {
+            gaps.push({ code: "intent-why-no-run", message: `no agent run is joined to the commits that made ${fileLines !== null ? "the current lines of " : ""}${region.path}` });
+        }
+        const uncommitted = who.filter((w) => w.sha === null).map((w) => w.line);
+        if (uncommitted.length > 0)
+            gaps.push({ code: "intent-why-uncommitted", message: `${uncommitted.length} ${uncommitted.length === 1 ? "line is" : "lines are"} not committed yet`, lines: ranges(uncommitted) });
+        const ambiguous = who.filter((w) => w.runs.length > 1).map((w) => w.line);
+        if (ambiguous.length > 0) {
+            gaps.push({ code: "intent-why-run-ambiguous", message: `${ambiguous.length} ${ambiguous.length === 1 ? "line comes" : "lines come"} from a commit several runs made, and no run's recorded hunks say which wrote ${ambiguous.length === 1 ? "it" : "them"}`, lines: ranges(ambiguous) });
+        }
+        return { lines: fileLines, blame: spans, decisions, runs, explained, gaps };
+    }
+}