@intentius/chant 0.85.0 → 0.87.0

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

@@ -0,0 +1,217 @@
+/**
+ * The two gaps a work item could not name before #2686, a stale pin and an
+ * open dissent, and `work-done-gap-open` on a records read, on a workspace
+ * built in a throwaway git repository:
+ *
+ * - c1 adds the app, the screen spec `design/screens/home.json`, and dec-001,
+ *   which constrains the spec's path and pins it by hash.
+ * - c2 adds dec-002, which supersedes dec-001, constrains the same path and
+ *   pins the spec at the same hash, so its pin is stale; dec-003, which
+ *   constrains `app/server.mjs` and has one open dissent (bob's), one
+ *   withdrawn and one addressed; and the work items:
+ *   W-001 (open, from intent-pin-stale on the spec), W-002 (open, from
+ *   intent-decision-contested on the server), W-003 (done, from
+ *   intent-decision-contested on the server, which still fires), W-004
+ *   (done, from intent-pin-drifted on the spec, which does not fire) and
+ *   W-005 (open, implements dec-002 and dec-003, no gap source).
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { sha256Hex } from "../content-digest";
+import { cleanScratch, contract, git, REPO, repo, writeFiles } from "./__fixtures__/contract-repo";
+import { intentGraph, type FindingNode, type IntentDocument, type WorkNode } from "./intent";
+import intentSchema from "./intent.schema.json";
+import { parseFrontMatter } from "./records";
+import { queryRecords } from "./records-cli";
+import recordsSchema from "./records.schema.json";
+
+const REF = join(REPO, "reference-workspace");
+const BASE = (() => {
+  const fm = parseFrontMatter(readFileSync(join(REF, "decisions", "ref-001-how-the-app-is-deployed.md"), "utf-8"));
+  if (!fm.ok) throw new Error(fm.message);
+  return fm.value;
+})();
+
+const HOME = `${JSON.stringify({ route: "/", regions: ["header"] }, null, 2)}\n`;
+const pin = { title: "The home screen spec", path: "design/screens/home.json", sha256: sha256Hex(Buffer.from(HOME)), as_of: "2026-09-24T12:00:00Z" };
+
+function decision(id: string, fields: Record<string, unknown>): string {
+  const data = { ...BASE, id, title: `Decision ${id}`, state: "decided", supersedes: [], evidence: [], reviews: [], ...fields };
+  return `---\n${JSON.stringify(data, null, 2)}\n---\n\n# ${id}\n`;
+}
+
+function work(id: string, fields: Record<string, unknown>): string {
+  const data = { schema: 1, id, title: `Work ${id}`, state: "open", implements: [], needs: [], constrains: ["path:app/server.mjs"], evidence: [], opened_on: "2026-09-24", supersedes: [], ...fields };
+  return `---\n${JSON.stringify(data, null, 2)}\n---\n\n# ${id}\n\nWhat the work is.\n`;
+}
+
+const done = { state: "done", closed_on: "2026-09-25", evidence: [{ title: "The review", url: "https://example.com/review" }] };
+const KIND_FILES = {
+  "decisions/decision.kind.mjs": readFileSync(join(REF, "decisions", "decision.kind.mjs"), "utf-8"),
+  "decisions/decision.schema.json": readFileSync(join(REF, "decisions", "decision.schema.json"), "utf-8"),
+  "work/work.kind.mjs": readFileSync(join(REF, "work", "work.kind.mjs"), "utf-8"),
+  "work/work.schema.json": readFileSync(join(REF, "work", "work.schema.json"), "utf-8"),
+};
+const DECLARATION = JSON.stringify({
+  name: "studio",
+  schema: 1,
+  members: [
+    { name: "app", dir: "app", kind: "other", because: "a plain Node server" },
+    { name: "design", dir: "design", kind: "other", because: "the screen specs" },
+  ],
+});
+
+const DEC_003 = decision("dec-003", {
+  constrains: ["path:app/server.mjs"],
+  reviews: [
+    { reviewer: "Bob", verdict: "dissent", note: "The port is wrong.", on: "2026-09-24" },
+    { reviewer: "carol", verdict: "dissent", note: "Too early.", on: "2026-09-24", withdrawn_on: "2026-09-25" },
+    { reviewer: "dave", verdict: "dissent", note: "Needs a test.", on: "2026-09-24", addressed_by: "acme/studio#7" },
+    { reviewer: "erin", verdict: "agree", on: "2026-09-24" },
+  ],
+});
+
+let root: string;
+
+function commit(message: string): void {
+  git(root, "add", "-A");
+  git(root, "commit", "-q", "-m", message);
+}
+
+beforeAll(() => {
+  root = repo({
+    "chant.workspace.json": DECLARATION,
+    "app/server.mjs": "export const port = 8080;\n",
+    "design/screens/home.json": HOME,
+    ...KIND_FILES,
+    "decisions/dec-001-spec.md": decision("dec-001", { constrains: ["path:design/screens/home.json"], evidence: [pin] }),
+  });
+  commit("the app, the spec and dec-001");
+  writeFiles(root, {
+    "decisions/dec-002-spec-again.md": decision("dec-002", { constrains: ["path:design/screens/home.json"], evidence: [pin], supersedes: [{ decision: "dec-001" }] }),
+    "decisions/dec-003-server.md": DEC_003,
+    "work/W-001-stale.md": work("W-001", { constrains: ["path:design/screens/home.json"], source: { finding: "intent-pin-stale", region: "design/screens/home.json", decision: "dec-002" } }),
+    "work/W-002-contested.md": work("W-002", { source: { finding: "intent-decision-contested", region: "app/server.mjs", decision: "dec-003" } }),
+    "work/W-003-contested-done.md": work("W-003", { ...done, source: { finding: "intent-decision-contested", region: "app/server.mjs", decision: "dec-003" } }),
+    "work/W-004-drift-done.md": work("W-004", { ...done, constrains: ["path:design/screens/home.json"], source: { finding: "intent-pin-drifted", region: "design/screens/home.json" } }),
+    "work/W-005-carry-out.md": work("W-005", { implements: ["dec-002", "dec-003"] }),
+  });
+  commit("dec-002 supersedes dec-001, dec-003 is contested, and the work");
+});
+afterAll(cleanScratch);
+
+const intent = contract(intentSchema);
+const records = contract(recordsSchema);
+type Result = Exclude<IntentDocument, { error: unknown }>;
+
+async function walk(region: string): Promise<Result> {
+  const { doc } = await intentGraph({ cwd: root, region, kinds: ["decisions/decision.kind.mjs", "work/work.kind.mjs"].map((k) => join(root, k)) });
+  intent.expectValid(doc);
+  if ("error" in doc) throw new Error(`${doc.error.code}: ${doc.error.message}`);
+  return doc;
+}
+
+const findingsOf = (doc: Result, code: string) => doc.nodes.filter((n): n is FindingNode => n.kind === "finding" && n.code === code);
+
+describe("intent-pin-stale (#2686)", () => {
+  test("a current decision pinning the artifact at the hash the record it supersedes pinned is stale, beside drifted and missing", async () => {
+    const doc = await walk("design/screens/home.json");
+    expect(doc.nodes.find((n) => n.id === "artifact:design/screens/home.json")).toMatchObject({ pinState: "stale" });
+    const stale = findingsOf(doc, "intent-pin-stale");
+    expect(stale).toHaveLength(1);
+    expect(stale[0].concerns).toEqual(["record:decision/dec-002", "artifact:design/screens/home.json", "record:decision/dec-001"]);
+    expect(stale[0].message).toContain("dec-001");
+    expect(findingsOf(doc, "intent-pin-drifted")).toEqual([]);
+    expect(findingsOf(doc, "intent-pin-missing")).toEqual([]);
+  });
+
+  test("it is addressed by the item that came from it and by the item implementing the decision", async () => {
+    const doc = await walk("design/screens/home.json");
+    const [stale] = findingsOf(doc, "intent-pin-stale");
+    expect(stale).toMatchObject({ addressed: true, addressedBy: [{ id: "W-001", state: "open" }, { id: "W-005", state: "open" }] });
+    expect(doc.edges).toContainEqual({ kind: "addressed-by", from: stale.id, to: "record:work/W-001" });
+    expect(doc.edges).toContainEqual({ kind: "addressed-by", from: stale.id, to: "record:work/W-005" });
+  });
+
+  test("a stale pin on a decision in the graph only through supersession is not raised", async () => {
+    // app/server.mjs brings in no decision pinning the spec.
+    const doc = await walk("app/server.mjs");
+    expect(findingsOf(doc, "intent-pin-stale")).toEqual([]);
+  });
+});
+
+describe("intent-decision-contested (#2686)", () => {
+  test("a current decision constraining the region with a dissent neither addressed nor withdrawn is contested, with the count and principals", async () => {
+    const doc = await walk("app/server.mjs");
+    const contested = findingsOf(doc, "intent-decision-contested");
+    expect(contested).toHaveLength(1);
+    expect(contested[0]).toMatchObject({ concerns: ["record:decision/dec-003", "region:app/server.mjs"], openConcerns: { count: 1, principals: ["bob"] } });
+    expect(contested[0].message).toContain("1 open concern, from Bob");
+  });
+
+  test("it is addressed by the items that came from it, and not through implements", async () => {
+    const doc = await walk("app/server.mjs");
+    const [contested] = findingsOf(doc, "intent-decision-contested");
+    expect(contested.addressedBy).toEqual([
+      { id: "W-002", state: "open" },
+      { id: "W-003", state: "done" },
+    ]);
+    expect(doc.edges).toContainEqual({ kind: "addressed-by", from: contested.id, to: "record:work/W-002" });
+    const w003 = doc.nodes.find((n): n is WorkNode => n.kind === "work" && n.record === "W-003");
+    expect(w003!.warnings.map((w) => w.code)).toEqual(["work-done-gap-open"]);
+  });
+
+  test("a decision whose dissents are all addressed or withdrawn is not contested", async () => {
+    writeFiles(root, { "decisions/dec-003-server.md": DEC_003.replace(`"note": "The port is wrong.",`, `"note": "The port is wrong.", "addressed_by": "acme/studio#8",`) });
+    try {
+      const doc = await walk("app/server.mjs");
+      expect(findingsOf(doc, "intent-decision-contested")).toEqual([]);
+    } finally {
+      writeFiles(root, { "decisions/dec-003-server.md": DEC_003 });
+    }
+  });
+});
+
+describe("work-done-gap-open in records (#2686)", () => {
+  test("records --json warns on a done item whose gap still fires, and not on one whose gap closed", async () => {
+    const doc = await queryRecords({ kind: "work/work.kind.mjs", cwd: root });
+    records.expectValid(doc);
+    if ("error" in doc) throw new Error(doc.error.message);
+    const warned = Object.fromEntries(doc.records.map((r) => [r.id, r.warnings.map((w) => w.code)]));
+    expect(warned).toEqual({ "W-001": [], "W-002": [], "W-003": ["work-done-gap-open"], "W-004": [], "W-005": [] });
+    expect(doc.records.find((r) => r.id === "W-003")!.warnings[0].message).toContain("intent-decision-contested");
+  });
+
+  test("the warning follows the revision read: under --at c1 there is no work, and under --at HEAD W-003 is warned", async () => {
+    const c1 = git(root, "rev-parse", "HEAD~1");
+    const doc = await queryRecords({ kind: "work/work.kind.mjs", cwd: root, at: c1 });
+    records.expectValid(doc);
+    if ("error" in doc) throw new Error(doc.error.message);
+    expect(doc.records).toEqual([]);
+    const head = await queryRecords({ kind: "work/work.kind.mjs", cwd: root, at: "HEAD" });
+    if ("error" in head) throw new Error(head.error.message);
+    expect(head.records.find((r) => r.id === "W-003")!.warnings.map((w) => w.code)).toEqual(["work-done-gap-open"]);
+  });
+
+  test("without a workspace declaration the walk can't be made, so the record is left as it was", async () => {
+    const bare = repo({
+      "app/server.mjs": "export const port = 8080;\n",
+      ...KIND_FILES,
+      "decisions/dec-003-server.md": DEC_003,
+      "work/W-003-contested-done.md": work("W-003", { ...done, source: { finding: "intent-decision-contested", region: "app/server.mjs" } }),
+    });
+    git(bare, "add", "-A");
+    git(bare, "commit", "-q", "-m", "one");
+    const doc = await queryRecords({ kind: "work/work.kind.mjs", cwd: bare });
+    if ("error" in doc) throw new Error(doc.error.message);
+    expect(doc.records[0].warnings).toEqual([]);
+  });
+
+  test("the intent graph reads its kinds without asking records for the warning, so it is raised once", async () => {
+    const doc = await walk("app/server.mjs");
+    const w003 = doc.nodes.find((n): n is WorkNode => n.kind === "work" && n.record === "W-003");
+    expect(w003!.warnings.filter((w) => w.code === "work-done-gap-open")).toHaveLength(1);
+  });
+});

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,11 +9,16 @@
  *
  * - 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
@@ -27,6 +32,14 @@
  * 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";
@@ -47,6 +60,18 @@ 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;
 }
@@ -63,7 +88,7 @@ export interface JoinedEntity {
 
 /** A finding a plugin contributes for one commit (#2656). */
 export interface PluginFinding {
-  /** `plugin:<name>:<code>`, where `<name>` is the kind's name. */
+  /** `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. */
@@ -103,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`. */
@@ -147,14 +197,15 @@ 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;
@@ -168,7 +219,8 @@ export function entityDecisions(entity: JoinedEntity | undefined): string[] {
 
 /**
  * Run a kind's joins for one commit, checking what a function returns.
- * `name` is the kind's name, the namespace its findings' codes must use.
+ * `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);