@intentius/chant 0.84.0 → 0.86.0

package/src/workspace/graph-cli.ts

@@ -7,7 +7,8 @@
  *
  * With `--intent <path[:start-end]>` it prints the intent graph over one
  * region instead (#2651, `intent.ts`), a document of its own in the read
- * contract.
+ * contract. With `--composites` it prints each composite instance with the
+ * components that can deploy it (#2662, `composites.ts`), another.
  *
  * The document is part of the read contract, described by `graph.schema.json`
  * beside this file. It is printed for a failure too, with the error's reason
@@ -48,7 +49,7 @@ export const GRAPH_OUTPUT_SCHEMA_ID = "https://intentius.io/chant/schemas/worksp
 export const GRAPH_ERROR_CODES = WORKSPACE_ERROR_CODES;
 
 const USAGE =
-  "chant workspace graph [dir] [--at <rev>] [--member <name>] [--kind <kind file>] [-o <file>] [--env <env>] [--dry-run] | chant workspace graph --intent <path[:start-end]> [--at <rev>] [--kind <kind file>...] [--json]";
+  "chant workspace graph [dir] [--at <rev>] [--member <name>] [--kind <kind file>] [-o <file>] [--env <env>] [--dry-run] | chant workspace graph --composites [--at <rev>] [--member <name>] [-o <file>] | chant workspace graph --intent <path[:start-end]> [--at <rev>] [--kind <kind file>...] [--json]";
 
 interface Head {
   $schema: string;
@@ -78,12 +79,32 @@ export interface GraphQuery {
    * rows of `links`.
    */
   kind?: string;
+  /**
+   * Also run each member's `chant graph --components --format ir` (#2662),
+   * under the same toolchain and at the same revision, and return the answers
+   * in {@link GraphResult.components}. The document is unchanged.
+   */
+  components?: boolean;
+  /**
+   * Called once the members have run, with the directory they were read from
+   * (the exported tree for `--at`, before it is removed) and the declared
+   * members the read covers. `--composites` reads each member's runtimes
+   * here (#2674).
+   */
+  inTree?: (root: string, members: readonly { name: string; dir: string; kind: string }[]) => Promise<void>;
 }
 
 export interface GraphResult {
   doc: GraphDocument;
   /** A member failed or couldn't be read, or the declaration couldn't be read. */
   failed: boolean;
+  /** With {@link GraphQuery.components}: each member's component graph run, in plan order. */
+  components?: UnitResult[];
+}
+
+/** The command line a member runs for its component graph (#2662). */
+export function componentGraphArgv(args: Partial<ParsedArgs>): string[] {
+  return ["graph", ".", "--components", "--format", "ir", ...(args.env ? ["--env", args.env] : [])];
 }
 
 /**
@@ -179,7 +200,13 @@ export async function workspaceGraph(query: GraphQuery): Promise<GraphResult> {
       exported = exportRevision(located, plan.groups.flatMap((g) => g.units.map((u) => u.dir)));
       plan = planMembers("graph", exported, { only: query.members, reader: query.reader, tree: workingTree(exported) });
     }
-    const results = await executePlan(plan, (query.args ?? {}) as ParsedArgs);
+    const args = (query.args ?? {}) as ParsedArgs;
+    const [results, components] = await Promise.all([
+      executePlan(plan, args),
+      query.components ? executePlan(plan, args, () => componentGraphArgv(args)) : Promise.resolve(undefined),
+    ]);
+    if (query.inTree) await query.inTree(exported ?? located.rootOnDisk, declaration.members.filter((m) => !query.members?.length || query.members.includes(m.name)));
+    for (const r of components ?? []) if (r.stderr.trim() && query.onStderr) query.onStderr(r.stderr.endsWith("\n") ? r.stderr : `${r.stderr}\n`);
     for (const r of results) if (r.stderr.trim() && query.onStderr) query.onStderr(r.stderr.endsWith("\n") ? r.stderr : `${r.stderr}\n`);
     const { inputs, failed } = compose(plan, results, query.members, declaration.members);
     // Links (#2539) resolve against the declaration that was read, the revision's for --at, and the kinds installed now.
@@ -201,7 +228,7 @@ export async function workspaceGraph(query: GraphQuery): Promise<GraphResult> {
         query.onStderr?.(`${formatError({ message: `--kind ${query.kind}: ${err.code}: ${err.message}`, hint: USAGE })}\n`);
       }
     }
-    return { doc: { ...head, at: located.at, ...graph }, failed: failed || recordsFailed };
+    return { doc: { ...head, at: located.at, ...graph }, failed: failed || recordsFailed, ...(components ? { components } : {}) };
   } catch (err) {
     if (!(err instanceof WorkspaceReadError)) throw err;
     return { doc: { ...head, error: { code: err.code, message: err.message, location: err.location ?? null } }, failed: true };
@@ -221,6 +248,15 @@ export async function runWorkspaceGraph(ctx: CommandContext): Promise<number> {
   const handed = await handToRootChant(cwd, args.at);
   if (handed !== undefined) return handed;
 
+  // Composite instances joined to components (#2662) are their own document.
+  if (args.composites) {
+    if (args.intent !== undefined || args.kind !== undefined) {
+      console.error(formatError({ message: "--composites takes neither --intent nor --kind", hint: USAGE }));
+      return 1;
+    }
+    if (!args.dryRun) return (await import("./composites")).runWorkspaceComposites(ctx, cwd);
+  }
+
   // The intent graph over one region (#2651) is its own document.
   if (args.intent !== undefined) return (await import("./intent-cli")).runWorkspaceIntent(ctx, cwd);
 

package/src/workspace/intent-cli.ts

@@ -3,13 +3,16 @@
  * (#2651): the intent graph over one region (`intent.ts`), printed as JSON
  * with `--json` or as a walk, one line per node, in the order of #2650
  * section B: the region, its decisions, their artifacts, the commits, and the
- * findings.
+ * findings. Under each decision come the commits made inside its window, and
+ * when any of them is not the decision's own work, the question #2650 B puts
+ * to the person about it (#2656). Without `--kind`, the walk reads every
+ * record kind the declaration names (#2680).
  */
 
 import { resolve } from "node:path";
 import { formatError } from "../cli/format";
 import type { CommandContext } from "../cli/registry";
-import { intentGraph, type ArtifactNode, type CommitNode, type DecisionNode, type IntentDocument, type IntentEdge, type IntentNode } from "./intent";
+import { intentGraph, type ArtifactNode, type CommitNode, type DecisionNode, type IntentDocument, type IntentEdge, type IntentNode, type WorkNode } from "./intent";
 
 const USAGE = "chant workspace graph --intent <path[:start-end]> [--at <rev>] [--kind <kind file>...] [--json]";
 
@@ -25,6 +28,28 @@ function ofKind<K extends IntentNode["kind"]>(doc: Result, kind: K): Extract<Int
 
 const short = (sha: string | null | undefined) => (sha ? sha.slice(0, 8) : "none");
 
+/** What the walk asks about a commit made inside a decision's window that is not the decision's own work (#2650 B4, step 5). */
+export const IN_WINDOW_QUESTION = "is this drift, a superseding decision nobody wrote down, or the decision being wrong?";
+
+/** The commits inside a decision's window, under its line, then the question once when any is not its own work. */
+function withinLines(doc: Result, d: DecisionNode): string[] {
+  const within = doc.edges.filter((e): e is Extract<IntentEdge, { kind: "within" }> => e.kind === "within" && e.to === d.id);
+  const out: string[] = [];
+  for (const e of within) {
+    const c = doc.nodes.find((n): n is CommitNode => n.kind === "commit" && n.id === e.from);
+    if (!c) continue;
+    const unit = edgesFrom(doc, c.id, "produced-by")
+      .map((p) => doc.nodes.find((n) => n.id === p.to))
+      .map((n) => (n && "ref" in n ? n.ref : undefined))
+      .filter(Boolean);
+    const by = unit.length > 0 ? `unit ${unit.join(", ")}` : "no unit";
+    const label = e.state === "decided" ? "decided " : "within  ";
+    out.push(`  ${label}  ${short(c.sha)} ${c.subject}; ${by}${e.state === "decided" ? `, ${d.record}'s own work` : `, in ${d.record}'s window and not its work`}`);
+  }
+  if (within.some((e) => e.state === "decided-by-window")) out.push(`  ask       ${IN_WINDOW_QUESTION}`);
+  return out;
+}
+
 function decisionLine(d: DecisionNode): string {
   const via = d.constrains.length > 0 ? d.constrains.map((c) => `${c.entry} (${c.granularity})`).join(", ") : "through supersession only";
   const by = d.decided_by ? `, decided by ${d.decided_by}${d.decided_on ? ` on ${d.decided_on}` : ""}` : "";
@@ -33,6 +58,22 @@ function decisionLine(d: DecisionNode): string {
   return `decision  ${d.record} ${d.state ?? "stateless"}${superseded}: ${d.title ?? d.path}; constrains ${via}${by}; ${reviews}; ${d.provenance.level}${d.valid ? "" : `; invalid: ${d.reasons.map((r) => r.code).join(", ")}`}`;
 }
 
+/** A work item, then the commits made inside its window (#2683). */
+function workLines(doc: Result, w: WorkNode): string[] {
+  const via = w.constrains.length > 0 ? w.constrains.map((c) => `${c.entry} (${c.granularity})`).join(", ") : "through a link only";
+  const implemented = w.implements.length > 0 ? `; implements ${w.implements.map((d) => `${d.id} (${d.state ?? "unknown"})`).join(", ")}` : "";
+  const readiness = w.ready ? "; ready" : w.blockedBy.length > 0 ? `; blocked by ${w.blockedBy.map((b) => `${b.id} (${b.state ?? "unknown"})`).join(", ")}` : "";
+  const owner = w.owner ? `, owned by ${w.owner}` : "";
+  const from = w.source ? `; from ${w.source.finding} on ${w.source.region}` : "";
+  const out = [`work      ${w.record} ${w.state ?? "stateless"}${owner}: ${w.title ?? w.path}; constrains ${via}${implemented}${readiness}${from}`];
+  for (const e of doc.edges.filter((x) => x.kind === "within" && x.to === w.id)) {
+    const c = doc.nodes.find((n): n is CommitNode => n.kind === "commit" && n.id === e.from);
+    if (c) out.push(`  worked    ${short(c.sha)} ${c.subject}; in ${w.record}'s window`);
+  }
+  for (const x of w.warnings) out.push(`  warning   ${x.code}: ${x.message}`);
+  return out;
+}
+
 function artifactLine(doc: Result, a: ArtifactNode): string {
   const by = doc.edges
     .filter((e): e is Extract<IntentEdge, { kind: "pins" }> => e.kind === "pins" && e.to === a.id)
@@ -63,17 +104,22 @@ export function formatIntent(doc: Result): string {
   }
   const files = ofKind(doc, "file");
   if (files.length > 0) out.push(`files     ${files.length} under the region, ${files.filter((f) => f.generated).length} generated`);
-  for (const d of ofKind(doc, "decision")) out.push(decisionLine(d));
+  for (const d of ofKind(doc, "decision")) out.push(decisionLine(d), ...withinLines(doc, d));
+  for (const w of ofKind(doc, "work")) out.push(...workLines(doc, w));
   for (const a of ofKind(doc, "artifact")) out.push(artifactLine(doc, a));
   for (const c of ofKind(doc, "commit")) out.push(...commitLine(doc, c));
   for (const l of ofKind(doc, "link")) {
     const r = l.row;
     out.push(`link      ${r.consumer} reads ${"producer" in r ? `${r.producer} ${r.output}` : r.input} (${r.status})`);
   }
-  for (const f of ofKind(doc, "finding")) out.push(`finding   ${f.code}: ${f.message}`);
+  for (const f of ofKind(doc, "finding")) {
+    const by = f.addressedBy && f.addressedBy.length > 0 ? `; addressed by ${f.addressedBy.map((w) => `${w.id} (${w.state ?? "unknown"})`).join(", ")}` : "";
+    out.push(`finding   ${f.code}: ${f.message}${by}`);
+  }
   for (const r of doc.reasons) out.push(`reason    ${r.code}: ${r.message}`);
   const kinds = doc.kinds.length === 0 ? "; no --kind, so no decisions were read" : "";
-  out.push(`${doc.summary.commits} commits, ${doc.summary.decisions} decisions, ${doc.summary.artifacts} artifacts, ${doc.summary.findings} findings${kinds}`);
+  const work = ofKind(doc, "work").length;
+  out.push(`${doc.summary.commits} commits, ${doc.summary.decisions} decisions, ${work > 0 ? `${work} work ${work === 1 ? "item" : "items"}, ` : ""}${doc.summary.artifacts} artifacts, ${doc.summary.findings} findings${kinds}`);
   return out.join("\n");
 }
 
@@ -83,8 +129,9 @@ export async function runWorkspaceIntent(ctx: CommandContext, cwd: string): Prom
     console.error(formatError({ message: "--intent needs a region: a path, path:line or path:start-end", hint: USAGE }));
     return 1;
   }
-  const kinds = args.kinds ?? (args.kind !== undefined ? [args.kind] : []);
-  const { doc, failed } = await intentGraph({ cwd, region: args.intent, at: args.at, kinds: kinds.map((k) => resolve(k)) });
+  // No --kind: undefined, so the walk reads the kinds the declaration names (#2680).
+  const kinds = args.kinds ?? (args.kind !== undefined ? [args.kind] : undefined);
+  const { doc, failed } = await intentGraph({ cwd, region: args.intent, at: args.at, kinds: kinds?.map((k) => resolve(k)) });
   if (args.json) console.log(JSON.stringify(doc, null, 2));
   if ("error" in doc) {
     console.error(formatError({ message: `${doc.error.code}: ${doc.error.message}`, hint: USAGE }));

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

@@ -0,0 +1,60 @@
+/**
+ * The commit-join hook's data form and its export checks, with no git
+ * (#2651, #2663).
+ */
+
+import { describe, expect, test } from "vitest";
+import { joinByData, readCommitJoins, trailerValue, trailerValues, type CommitJoinContext, type IntentCommit } from "./intent-joins";
+
+const commit = (trailers: Record<string, string[]>): IntentCommit => ({ sha: "a".repeat(40), subject: "s", body: "", author: { name: "t", email: "t@example.com" }, date: "2026-09-24T00:00:00Z", trailers });
+
+const files: Record<string, string> = {
+  "evidence/E-1.json": JSON.stringify({ id: "ignored", kind: "test-run" }),
+  "evidence/E-3.json": JSON.stringify({ kind: "review" }),
+  "units/U-1.json": JSON.stringify({ role: "implement" }),
+};
+const context: CommitJoinContext = { read: (p) => files[p], list: () => undefined, at: null };
+
+describe("the data form reads every trailer value (#2663)", () => {
+  test("each value of the evidence trailer, under any case of its key, is one piece of evidence", () => {
+    const data = { trailers: { unit: "Unit", evidence: "Evidence" }, records: { unit: "units/{id}.json", evidence: "evidence/{id}.json" } };
+    const out = joinByData(data, commit({ Unit: ["U-1"], Evidence: ["E-1", " E-2 ", "E-1"], evidence: ["E-3", ""] }), context);
+    expect(out).toEqual({
+      unit: { id: "U-1", role: "implement" },
+      evidence: [
+        { id: "E-1", kind: "test-run" },
+        { id: "E-2" },
+        { id: "E-3", kind: "review" },
+      ],
+    });
+  });
+
+  test("a unit or contract trailer gives its first value, since a commit has one of each", () => {
+    const out = joinByData({ trailers: { unit: "Unit", contract: "Contract" } }, commit({ Unit: ["U-1", "U-2"], contract: ["C-1"], Contract: ["C-2"] }), context);
+    expect(out.unit).toEqual({ id: "U-1" });
+    expect(out.contract?.id).toBe(trailerValue({ contract: ["C-1"], Contract: ["C-2"] }, "Contract"));
+  });
+
+  test("trailerValues keeps git's order, trims, and drops empty values and repeats", () => {
+    expect(trailerValues({ "Chud-Evidence": ["h1", "h2"], "chud-evidence": ["h2", " h3", "  "] }, "CHUD-EVIDENCE")).toEqual(["h1", "h2", "h3"]);
+    expect(trailerValues({}, "X")).toEqual([]);
+    expect(trailerValue({ X: ["  "] }, "x")).toBeUndefined();
+  });
+});
+
+describe("commitJoinsName (#2663)", () => {
+  test("names the findings of either form, and leaves the data form's own keys alone", () => {
+    const join = () => undefined;
+    expect(readCommitJoins({ commitJoins: join, commitJoinsName: "chud" })).toEqual({ form: "function", join, name: "chud" });
+    expect(readCommitJoins({ commitJoins: { trailers: { unit: "Unit" } }, commitJoinsName: "chud" })).toEqual({ form: "data", data: { trailers: { unit: "Unit" } }, name: "chud" });
+    expect(readCommitJoins({ commitJoins: join })).toEqual({ form: "function", join });
+    // A name inside the data form is still a key the data form does not have.
+    expect(readCommitJoins({ commitJoins: { name: "chud", trailers: {} } })).toMatch(/Unrecognized key/);
+  });
+
+  test("a name that can't be a plugin:<name>: segment, or one with no joins, is refused", () => {
+    for (const bad of ["a:b", "a b", "", 7]) expect(readCommitJoins({ commitJoins: () => undefined, commitJoinsName: bad }), String(bad)).toMatch(/^commitJoinsName:/);
+    expect(readCommitJoins({ commitJoinsName: "chud" })).toMatch(/no commitJoins/);
+    expect(readCommitJoins({})).toBeUndefined();
+  });
+});

package/src/workspace/intent-joins.ts

@@ -9,18 +9,41 @@
  *
  * - A function `commitJoins(commit, context)` that returns the unit, contract
  *   and evidence for one commit, or nothing. It is given the commit's sha,
- *   subject, body, author, date and trailers, and a `read` function for files
- *   at the revision read.
+ *   subject, body, author, date and trailers, and a context whose `read(path)`
+ *   returns a file and whose `list(dir)` lists a directory, both in the tree
+ *   read (#2663). With `list` a plugin can find the record that names a
+ *   commit, such as a unit record whose `result.commit` is the commit's sha,
+ *   so the commit needs no trailer at all.
  * - Data, which core interprets with no plugin code: the trailer keys that
  *   name a unit, a contract or evidence, the record paths to read for each
- *   (`units/{id}.json`), and the trailer keys that claim authorship.
+ *   (`units/{id}.json`), and the trailer keys that claim authorship. Every
+ *   value of the evidence trailer is read; a unit or contract trailer gives
+ *   its first value, since a commit has one unit and one contract.
  *
  * Either way core never parses a plugin's own trailer or record format: it
  * reads the trailers git reports and hands them over, and a key means
  * something only because a kind file said so.
+ *
+ * Two parts of a join's answer carry meaning core acts on (#2656). A unit or
+ * contract may list `decisions`, the ids of the decision records it carries
+ * out; a commit whose unit or contract names a decision is that decision's own
+ * work. The function form may also return `findings`, each a code in the
+ * kind's own namespace (`plugin:<name>:<code>`), a message and the refs it is
+ * about, which the graph carries as finding nodes. That is how a plugin says
+ * what it knows and core does not, such as a contract whose criteria changed
+ * in a commit that names no decision.
+ *
+ * `<name>` is the kind's name by default: its record kind's name, or the
+ * file's name without `.kind.mjs`. A kind file may name its findings itself
+ * with a sibling export, `commitJoinsName` (#2663), so joins that live beside
+ * a record kind called `decision` can still report `plugin:chud:<code>`. It is
+ * a sibling export rather than a property because the data form is a closed
+ * object whose keys are all joins, and a function's `name` property is
+ * already its own name.
  */
 
 import { z } from "zod";
+import { isPluginCode } from "./reason-codes";
 
 /** A commit as the hook sees it. */
 export interface IntentCommit {
@@ -37,16 +60,41 @@ export interface IntentCommit {
 export interface CommitJoinContext {
   /** The text of a file from the workspace root, in the tree read; undefined when it is not a file there. */
   read(path: string): string | undefined;
+  /**
+   * The entries directly inside directory `dir`, in the same tree as `read`
+   * (#2663): paths from the workspace root, sorted, a directory's with a
+   * trailing `/`. `""` or `"."` is the workspace root. Undefined when `dir` is
+   * not a directory there.
+   *
+   * The tree is the one the graph reads, the commit `--at` names or the
+   * working tree, and not each joined commit's own tree: a record that names
+   * a commit's sha was written after that commit, so it is only in a later
+   * tree.
+   */
+  list(dir: string): string[] | undefined;
   /** The full commit id read with `--at`, or null for the working tree. */
   at: string | null;
 }
 
-/** A plugin's unit, contract or evidence: an id and whatever fields the plugin records. */
+/**
+ * A plugin's unit, contract or evidence: an id and whatever fields the plugin
+ * records. On a unit or contract, `decisions`, a list of record ids, names the
+ * decisions it carries out (#2656).
+ */
 export interface JoinedEntity {
   id: string;
   [field: string]: unknown;
 }
 
+/** A finding a plugin contributes for one commit (#2656). */
+export interface PluginFinding {
+  /** `plugin:<name>:<code>`, where `<name>` is the kind file's `commitJoinsName`, or else the kind's name. */
+  code: string;
+  message: string;
+  /** What the finding is about: node ids, commit shas, record ids, unit, contract or evidence ids, or paths. */
+  refs?: string[];
+}
+
 /** What a join says about one commit. Every part is optional. */
 export interface CommitJoin {
   /** The unit of work that produced the commit. */
@@ -57,6 +105,8 @@ export interface CommitJoin {
   evidence?: JoinedEntity | JoinedEntity[];
   /** Trailer keys on this commit that claim who wrote it, which the plugin vouches for. */
   authorship?: string[];
+  /** Findings about this commit, in the kind's own code namespace. Function form only. */
+  findings?: PluginFinding[];
 }
 
 export type CommitJoinsFunction = (commit: IntentCommit, context: CommitJoinContext) => CommitJoin | null | undefined | Promise<CommitJoin | null | undefined>;
@@ -78,24 +128,49 @@ export const commitJoinsDataSchema = z
 
 export type CommitJoinsData = z.infer<typeof commitJoinsDataSchema>;
 
-/** A kind file's `commitJoins` export, checked: a function, or data. */
-export type CommitJoins = { form: "function"; join: CommitJoinsFunction } | { form: "data"; data: CommitJoinsData };
+/**
+ * A kind file's `commitJoins` export, checked: a function, or data. `name` is
+ * its `commitJoinsName` export, when it has one: the namespace of its findings.
+ */
+export type CommitJoins = ({ form: "function"; join: CommitJoinsFunction } | { form: "data"; data: CommitJoinsData }) & { name?: string };
+
+/** What a `commitJoinsName` may be: the `<name>` of `plugin:<name>:<code>`. */
+const JOINS_NAME = /^[^:\s]+$/;
 
-/** Read a kind module's `commitJoins` export. Undefined when it has none; a string when it is malformed. */
+/**
+ * Read a kind module's `commitJoins` export and its `commitJoinsName`.
+ * Undefined when it has no `commitJoins`; a string when either is malformed,
+ * or when it names findings it has no joins for.
+ */
 export function readCommitJoins(mod: Record<string, unknown>): CommitJoins | string | undefined {
   const value = mod.commitJoins;
-  if (value === undefined) return undefined;
-  if (typeof value === "function") return { form: "function", join: value as CommitJoinsFunction };
+  const name = mod.commitJoinsName;
+  if (value === undefined) return name === undefined ? undefined : "commitJoinsName: a kind file with no commitJoins has no findings to name";
+  if (name !== undefined && (typeof name !== "string" || !JOINS_NAME.test(name))) return "commitJoinsName: a string with no colon or space, the <name> of plugin:<name>:<code>";
+  const named = name === undefined ? {} : { name: name as string };
+  if (typeof value === "function") return { form: "function", join: value as CommitJoinsFunction, ...named };
   const parsed = commitJoinsDataSchema.safeParse(value);
   if (!parsed.success) return parsed.error.issues.map((i) => `commitJoins${i.path.length ? `.${i.path.join(".")}` : ""}: ${i.message}`).join("; ");
-  return { form: "data", data: parsed.data };
+  return { form: "data", data: parsed.data, ...named };
+}
+
+/** Every value of trailer `key`, trimmed, without empty ones or repeats, compared without case as git does. */
+export function trailerValues(trailers: Record<string, string[]>, key: string): string[] {
+  const want = key.toLowerCase();
+  const out: string[] = [];
+  for (const [k, values] of Object.entries(trailers)) {
+    if (k.toLowerCase() !== want) continue;
+    for (const v of values) {
+      const t = v.trim();
+      if (t && !out.includes(t)) out.push(t);
+    }
+  }
+  return out;
 }
 
 /** The first value of trailer `key`, compared without case as git does. */
 export function trailerValue(trailers: Record<string, string[]>, key: string): string | undefined {
-  const want = key.toLowerCase();
-  for (const [k, values] of Object.entries(trailers)) if (k.toLowerCase() === want && values.length > 0) return values[0].trim() || undefined;
-  return undefined;
+  return trailerValues(trailers, key)[0];
 }
 
 /** Whether the commit carries trailer `key`. */
@@ -122,21 +197,32 @@ function recordFields(template: string | undefined, id: string, context: CommitJ
 /** Interpret the data form for one commit. Throws when a named record can't be read as JSON. */
 export function joinByData(data: CommitJoinsData, commit: IntentCommit, context: CommitJoinContext): CommitJoin {
   const out: CommitJoin = {};
-  for (const part of ["unit", "contract", "evidence"] as const) {
+  const entity = (part: "unit" | "contract" | "evidence", id: string): JoinedEntity => ({ ...recordFields(data.records?.[part], id, context), id });
+  for (const part of ["unit", "contract"] as const) {
     const key = data.trailers[part];
     const id = key ? trailerValue(commit.trailers, key) : undefined;
-    if (!id) continue;
-    const entity: JoinedEntity = { ...recordFields(data.records?.[part], id, context), id };
-    if (part === "evidence") out.evidence = entity;
-    else out[part] = entity;
+    if (id) out[part] = entity(part, id);
   }
+  // Each value of the evidence trailer is one piece of evidence (#2663).
+  const evidence = data.trailers.evidence ? trailerValues(commit.trailers, data.trailers.evidence) : [];
+  if (evidence.length > 0) out.evidence = evidence.map((id) => entity("evidence", id));
   const claimed = (data.authorship ?? []).filter((k) => hasTrailer(commit.trailers, k));
   if (claimed.length > 0) out.authorship = claimed;
   return out;
 }
 
-/** Run a kind's joins for one commit, checking what a function returns. */
-export async function runCommitJoins(joins: CommitJoins, commit: IntentCommit, context: CommitJoinContext): Promise<CommitJoin> {
+/** The record ids a unit or contract says it carries out: its `decisions` field, when that is a list of strings. */
+export function entityDecisions(entity: JoinedEntity | undefined): string[] {
+  const list = entity?.decisions;
+  return Array.isArray(list) ? list.filter((d): d is string => typeof d === "string" && d !== "") : [];
+}
+
+/**
+ * Run a kind's joins for one commit, checking what a function returns.
+ * `name` is the namespace its findings' codes must use: the kind file's
+ * `commitJoinsName`, or else the kind's name.
+ */
+export async function runCommitJoins(joins: CommitJoins, commit: IntentCommit, context: CommitJoinContext, name: string): Promise<CommitJoin> {
   if (joins.form === "data") return joinByData(joins.data, commit, context);
   const result = await joins.join(commit, context);
   if (result === null || result === undefined) return {};
@@ -161,5 +247,16 @@ export async function runCommitJoins(joins: CommitJoins, commit: IntentCommit, c
     if (!Array.isArray(result.authorship) || !result.authorship.every((k) => typeof k === "string")) throw new Error("commitJoins returned authorship that is not a list of trailer keys");
     out.authorship = result.authorship;
   }
+  if (result.findings !== undefined && result.findings !== null) {
+    if (!Array.isArray(result.findings)) throw new Error("commitJoins returned findings that are not a list");
+    out.findings = result.findings.map((f: unknown) => {
+      if (f === null || typeof f !== "object" || Array.isArray(f)) throw new Error("commitJoins returned a finding that is not an object");
+      const { code, message, refs } = f as Record<string, unknown>;
+      if (!isPluginCode(code, name)) throw new Error(`commitJoins returned the finding code ${JSON.stringify(code)}, and a plugin's codes are plugin:${name}:<code>, with <code> in lower case words joined by dashes`);
+      if (typeof message !== "string" || message === "") throw new Error(`commitJoins returned the finding ${code} with no message`);
+      if (refs !== undefined && (!Array.isArray(refs) || !refs.every((r) => typeof r === "string"))) throw new Error(`commitJoins returned the finding ${code} with refs that are not a list of strings`);
+      return { code, message, refs: (refs as string[] | undefined) ?? [] };
+    });
+  }
   return out;
 }