@intentius/chant 0.84.0 → 0.86.0

package/src/workspace/ls.schema.json

@@ -43,6 +43,11 @@
                   "integrity": { "type": ["string", "null"] }
                 }
               }
+            },
+            "records": {
+              "description": "Added in contract 1 by #2680. The workspace's own record kinds, from the declaration's top-level records, in file order.",
+              "type": "array",
+              "items": { "$ref": "#/$defs/recordKind" }
             }
           }
         },
@@ -89,6 +94,11 @@
         "upstream": { "type": ["string", "null"] },
         "because": { "type": ["string", "null"] },
         "readable": { "type": "boolean", "description": "True exactly when reason is null." },
+        "records": {
+          "description": "Added in contract 1 by #2680. The record kinds the member declares, in file order. A kind that can't be loaded does not make the member unreadable.",
+          "type": "array",
+          "items": { "$ref": "#/$defs/recordKind" }
+        },
         "reason": {
           "oneOf": [
             { "type": "null" },
@@ -107,6 +117,30 @@
       "then": { "type": "object", "properties": { "reason": { "type": "null" } } },
       "else": { "type": "object", "properties": { "reason": { "type": "object" } } }
     },
+    "recordKind": {
+      "description": "A record kind the declaration names (#2680). chant workspace records and graph --intent read every one of them when --kind is not given.",
+      "type": "object",
+      "required": ["name", "path", "kind", "reason"],
+      "properties": {
+        "name": { "type": ["string", "null"], "description": "The name the declaration gives the kind, else the kind file's own recordKind.name, else null when the file can't be loaded." },
+        "path": { "type": "string", "description": "The kind file, relative to the workspace root, with / separators." },
+        "kind": { "type": ["string", "null"], "description": "The kind file's recordKind.name, or null when it can't be loaded." },
+        "reason": {
+          "description": "Why the kind file can't be loaded, or null. The file is looked for in the tree read, the revision under --at, and loaded from the working tree.",
+          "oneOf": [
+            { "type": "null" },
+            {
+              "type": "object",
+              "required": ["code", "message"],
+              "properties": {
+                "code": { "enum": ["kind-unreadable", "kind-invalid", "schema-unreadable", "schema-id-mismatch"] },
+                "message": { "type": "string" }
+              }
+            }
+          ]
+        }
+      }
+    },
     "group": {
       "type": "object",
       "required": ["name", "kind", "glob", "matches", "skipped", "reason"],

package/src/workspace/ls.ts

@@ -8,6 +8,11 @@
  *
  * The `--json` output is part of the read contract, versioned like
  * `workspace records` and described by `ls.schema.json` beside this file.
+ *
+ * The record kinds the declaration names are listed too, the workspace's own
+ * and each member's, with each kind file's own name when it loads (#2680).
+ * Loading one imports it, so {@link listWorkspace} lists them unloaded and
+ * {@link listWorkspaceWithKinds}, which the command runs, loads them.
  */
 
 import { existsSync } from "node:fs";
@@ -28,6 +33,7 @@ import type { ReasonCode } from "./reason-codes";
 import { loadKindRegistry, probeKind, type KindRegistry } from "./kinds";
 import type { WorkspaceTree } from "./tree";
 import { handToRootChant, locateWorkspace } from "./which-chant";
+import type { DeclaredKindReasonCode } from "./declared-kinds";
 
 /** The version of the `ls` output this chant writes. */
 export const LS_CONTRACT_VERSION = 1;
@@ -58,6 +64,18 @@ export const GROUP_REASON_CODES = [
 ] as const satisfies readonly ReasonCode[];
 export type GroupReasonCode = (typeof GROUP_REASON_CODES)[number];
 
+/** A record kind the declaration names (#2680). */
+export interface LsRecordKind {
+  /** The name the declaration gives it, else the kind file's own, else null when the file wasn't loaded. */
+  name: string | null;
+  /** The kind file from the workspace root. */
+  path: string;
+  /** The kind file's `recordKind.name`, or null when it wasn't loaded. */
+  kind: string | null;
+  /** Why the kind file can't be loaded, or null. */
+  reason: { code: DeclaredKindReasonCode; message: string } | null;
+}
+
 export interface LsMember {
   name: string;
   dir: string;
@@ -67,6 +85,8 @@ export interface LsMember {
   because: string | null;
   readable: boolean;
   reason: { code: MemberReasonCode; message: string } | null;
+  /** The record kinds the member declares, in file order (#2680). */
+  records: LsRecordKind[];
 }
 
 export interface LsGroup {
@@ -92,6 +112,8 @@ export type LsDocument =
         schema: number;
         minReader: string | null;
         pins: Declaration["pins"];
+        /** The workspace's own record kinds, from the top-level `records` (#2680). */
+        records: LsRecordKind[];
       };
       members: LsMember[];
       groups: LsGroup[];
@@ -126,8 +148,36 @@ export function memberReason(member: Member, tree: WorkspaceTree, kinds: KindReg
   return null;
 }
 
-/** Find the workspace, read it and build the document `--json` prints. Never throws a {@link WorkspaceReadError}. */
+/**
+ * Find the workspace, read it and build the document `--json` prints, with
+ * the declared record kinds unloaded: `kind` null and no reason. Never throws
+ * a {@link WorkspaceReadError}.
+ */
 export function listWorkspace(query: LsQuery): LsDocument {
+  return readListing(query).doc;
+}
+
+/** {@link listWorkspace}, with each declared record kind loaded for its name, or the reason it can't be (#2680). */
+export async function listWorkspaceWithKinds(query: LsQuery): Promise<LsDocument> {
+  const { doc, declaration, tree, rootOnDisk } = readListing(query);
+  if (!declaration || "error" in doc) return doc;
+  const { loadDeclaredKinds } = await import("./declared-kinds");
+  const loaded = await loadDeclaredKinds(declaration, tree!, rootOnDisk!);
+  const byPath = new Map(loaded.map((k) => [k.declared.path, k]));
+  const fill = (r: LsRecordKind): LsRecordKind => {
+    const k = byPath.get(r.path)!;
+    return { ...r, name: r.name ?? k.kind, kind: k.kind, reason: k.reason };
+  };
+  return {
+    ...doc,
+    workspace: { ...doc.workspace, records: doc.workspace.records.map(fill) },
+    members: doc.members.map((m) => ({ ...m, records: m.records.map(fill) })),
+  };
+}
+
+const unloaded = (records: Declaration["records"]): LsRecordKind[] => records.map((r) => ({ name: r.name, path: r.path, kind: null, reason: null }));
+
+function readListing(query: LsQuery): { doc: LsDocument; declaration?: Declaration; tree?: WorkspaceTree; rootOnDisk?: string } {
   const chant = readerVersion();
   const head = { $schema: LS_OUTPUT_SCHEMA_ID, contract: LS_CONTRACT_VERSION, chant };
   try {
@@ -149,6 +199,7 @@ export function listWorkspace(query: LsQuery): LsDocument {
         because: m.because,
         readable: reason === null,
         reason,
+        records: unloaded(m.records),
       };
     });
     const lsGroups: LsGroup[] = groups.map((g) => ({
@@ -162,7 +213,7 @@ export function listWorkspace(query: LsQuery): LsDocument {
           ? { code: "no-matches", message: `no directory ${g.group.globs.join(" or ")} matches${tree.label} holds a chant project` }
           : null,
     }));
-    return {
+    const doc: LsDocument = {
       ...head,
       at,
       workspace: {
@@ -172,6 +223,7 @@ export function listWorkspace(query: LsQuery): LsDocument {
         schema: declaration.schema,
         minReader: declaration.minReader,
         pins: declaration.pins,
+        records: unloaded(declaration.records),
       },
       members,
       groups: lsGroups,
@@ -182,9 +234,10 @@ export function listWorkspace(query: LsQuery): LsDocument {
         matches: lsGroups.reduce((n, g) => n + g.matches.length, 0),
       },
     };
+    return { doc, declaration, tree, rootOnDisk };
   } catch (err) {
     if (!(err instanceof WorkspaceReadError)) throw err;
-    return { ...head, error: { code: err.code, message: err.message, location: err.location ?? null } };
+    return { doc: { ...head, error: { code: err.code, message: err.message, location: err.location ?? null } } };
   }
 }
 
@@ -198,7 +251,7 @@ export async function runWorkspaceLs(ctx: CommandContext): Promise<number> {
   // The root's chant reads the declaration (ws-021).
   const handed = await handToRootChant(cwd, args.at);
   if (handed !== undefined) return handed;
-  const doc = listWorkspace({ cwd, at: args.at });
+  const doc = await listWorkspaceWithKinds({ cwd, at: args.at });
   if (args.json) {
     console.log(JSON.stringify(doc, null, 2));
   } else if ("error" in doc) {
@@ -233,6 +286,18 @@ function formatLs(doc: Extract<LsDocument, { members: unknown }>): string {
       if (m.reason) lines.push(`  ${m.reason.code}: ${m.reason.message}`);
     });
   }
+  const kinds = [...w.records.map((r) => ({ owner: "(workspace)", r })), ...doc.members.flatMap((m) => m.records.map((r) => ({ owner: m.name, r })))];
+  if (kinds.length > 0) {
+    lines.push("");
+    const rows = [["RECORDS", "KIND", "MEMBER", "FILE"]];
+    for (const { owner, r } of kinds) rows.push([r.name ?? "-", r.kind ?? "-", owner, r.path]);
+    const rendered = table(rows);
+    lines.push(rendered[0]);
+    kinds.forEach(({ r }, i) => {
+      lines.push(rendered[i + 1]);
+      if (r.reason) lines.push(`  ${r.reason.code}: ${r.reason.message}`);
+    });
+  }
   if (doc.groups.length > 0) {
     lines.push("");
     const rows = [["GROUP", "KIND", "GLOB", "PROJECTS"]];

package/src/workspace/member-commands.ts

@@ -333,9 +333,12 @@ export function parseMemberRunOutput(stdout: string): { chant: string; results:
   return header ? { chant: header.chant, results, stray: stray.join("\n") } : undefined;
 }
 
-async function runGroup(verb: WorkspaceVerb, group: ToolchainGroup, root: string, args: ParsedArgs): Promise<UnitResult[]> {
+/** A command line to run in each member instead of the verb's own, such as `graph --components` (#2662). */
+export type MemberArgv = (unit: RunUnit) => string[];
+
+async function runGroup(verb: WorkspaceVerb, group: ToolchainGroup, root: string, args: ParsedArgs, argvFor?: MemberArgv): Promise<UnitResult[]> {
   const { toolchain, units } = group;
-  const argvs = new Map(units.map((u) => [u.id, memberArgv(verb, u, args)]));
+  const argvs = new Map(units.map((u) => [u.id, argvFor ? argvFor(u) : memberArgv(verb, u, args)]));
   for (const u of units) {
     const o = argvs.get(u.id)!;
     const i = o.indexOf("--output");
@@ -365,9 +368,12 @@ async function runGroup(verb: WorkspaceVerb, group: ToolchainGroup, root: string
   return out;
 }
 
-/** Run every group of the plan, one process per toolchain at a time each, and return the results in plan order. */
-export async function executePlan(plan: MemberPlan, args: ParsedArgs): Promise<UnitResult[]> {
-  const perGroup = await Promise.all(plan.groups.map((g) => runGroup(plan.verb, g, plan.workspace.root, args)));
+/**
+ * Run every group of the plan, one process per toolchain at a time each, and
+ * return the results in plan order. `argvFor` replaces the verb's command line.
+ */
+export async function executePlan(plan: MemberPlan, args: ParsedArgs, argvFor?: MemberArgv): Promise<UnitResult[]> {
+  const perGroup = await Promise.all(plan.groups.map((g) => runGroup(plan.verb, g, plan.workspace.root, args, argvFor)));
   const byId = new Map(perGroup.flat().map((r) => [r.id, r]));
   const order = plan.groups.flatMap((g) => g.units);
   return order.map((u) => byId.get(u.id)!);

package/src/workspace/read-contract.test.ts

@@ -6,8 +6,9 @@
  * `chant` member (`delivery`), three `other` members and decision records.
  * Each read-contract command reads it here, and its output must validate
  * against the command's schema: `ls`, `graph` (running delivery's real
- * `chant graph`), `check`, `status` and `records`, in the working tree and,
- * for `ls`, `graph` and `check`, at `HEAD` through `--at`.
+ * `chant graph`), `graph --composites`, `check`, `status`, `records` and
+ * `records --since`, in the working tree and, for `ls`, `graph` and `check`,
+ * at `HEAD` through `--at`.
  *
  * The schemas themselves are checked here too: each is a draft 2020-12
  * document under `https://intentius.io/chant/schemas/workspace/<command>/v1/`,
@@ -20,6 +21,8 @@ import { pathToFileURL } from "node:url";
 import { describe, expect, test } from "vitest";
 import { contract, git, REPO, validSchema } from "./__fixtures__/contract-repo";
 import checkSchema from "./check.schema.json";
+import { workspaceComposites } from "./composites";
+import compositesSchema from "./composites.schema.json";
 import { workspaceGraph } from "./graph-cli";
 import graphSchema from "./graph.schema.json";
 import { intentGraph } from "./intent";
@@ -31,13 +34,15 @@ import { readerBin, type Toolchain } from "./member-commands";
 import { READ_CONTRACT_FLOOR, READ_CONTRACT_VERSION } from "./reason-codes";
 import { queryRecords } from "./records-cli";
 import recordsSchema from "./records.schema.json";
+import { queryRecordsSince } from "./records-since";
+import recordsSinceSchema from "./records-since.schema.json";
 import { workspaceStatus } from "./status";
 import statusSchema from "./status.schema.json";
 
 const FIXTURE = join(REPO, "reference-workspace");
 const TIMEOUT = 240_000;
 
-const SCHEMAS = { ls: lsSchema, graph: graphSchema, check: checkSchema, status: statusSchema, records: recordsSchema, intent: intentSchema };
+const SCHEMAS = { ls: lsSchema, graph: graphSchema, check: checkSchema, status: statusSchema, records: recordsSchema, "records-since": recordsSinceSchema, intent: intentSchema, composites: compositesSchema };
 
 /** This checkout's chant, started the way the CLI starts it, for members with no toolchain of their own. */
 const reader: Toolchain = {
@@ -131,6 +136,36 @@ describe("every schema against the reference workspace (#2543)", () => {
     }
   });
 
+  test(
+    "graph --composites runs delivery's own component graph, and lists its app with the component that deploys it (#2662)",
+    async () => {
+      const { expectValid } = contract(compositesSchema);
+      for (const at of [undefined, "HEAD"]) {
+        const { doc, failed } = await workspaceComposites({ cwd: FIXTURE, at, reader });
+        expectValid(doc);
+        if ("error" in doc) throw new Error(doc.error.message);
+        expect(failed, JSON.stringify(doc.members)).toBe(false);
+        expect(doc.at).toBe(at ? head : null);
+        expect(doc.members.map((m) => [m.name, m.status])).toEqual([
+          ["app", "skipped"],
+          ["delivery", "read"],
+          ["design-client", "skipped"],
+          ["design", "skipped"],
+        ]);
+        // delivery declares the app as a DockerWebService, and its app component names that kind.
+        expect(doc.composites.map((c) => [c.id, c.kinds, c.components.map((m) => [m.component, m.by, m.via])])).toEqual([
+          ["delivery/app", ["DockerWebService"], [["delivery/app", "composites", "member"]]],
+        ]);
+        expect(doc.components.map((c) => [c.id, c.archetype])).toEqual([["delivery/app", "service"]]);
+        // #2674: the reference config's lexicons host no component runs, so local is the only runtime, read at HEAD too.
+        expect(doc.components[0].runtimes).toEqual([{ name: "local", lexicon: null, default: true, command: "chant run --components app" }]);
+        expect(doc.members.find((m) => m.name === "delivery")!.runtimeReasons).toEqual([]);
+        expect(doc.reasons).toEqual([]);
+      }
+    },
+    TIMEOUT,
+  );
+
   test("records, in the working tree and at HEAD", async () => {
     const { expectValid } = contract(recordsSchema);
     for (const at of [undefined, "HEAD"]) {
@@ -140,5 +175,19 @@ describe("every schema against the reference workspace (#2543)", () => {
       expect(doc.summary.invalid).toBe(0);
       expect(doc.records.map((r) => r.id)).toContain("ref-001");
     }
+    const sessions = await queryRecords({ kind: "design/sessions/session.kind.mjs", cwd: FIXTURE });
+    expectValid(sessions);
+    if ("error" in sessions) throw new Error(sessions.error.message);
+    expect(sessions.summary.invalid).toBe(0);
+  });
+
+  test("records --since HEAD, for decisions and sessions (#2673)", async () => {
+    const { expectValid } = contract(recordsSinceSchema);
+    for (const kind of ["decisions/decision.kind.mjs", "design/sessions/session.kind.mjs"]) {
+      const doc = await queryRecordsSince({ kind, since: "HEAD", cwd: FIXTURE });
+      expectValid(doc);
+      if ("error" in doc) throw new Error(doc.error.message);
+      expect(doc.since).toBe(head);
+    }
   });
 });

package/src/workspace/reason-codes.test.ts

@@ -10,14 +10,20 @@ import { join } from "node:path";
 import { describe, expect, test } from "vitest";
 import { REPO } from "./__fixtures__/contract-repo";
 import { MEMBER_RUN_REASON_CODES } from "./compose-graph";
+import { COMPOSITES_ERROR_CODES, COMPOSITES_REASON_CODES, COMPOSITES_RUNTIME_REASON_CODES } from "./composites";
 import { WORKSPACE_ERROR_CODES } from "./declaration";
 import { GRAPH_ERROR_CODES } from "./graph-cli";
 import { INTENT_ERROR_CODES, INTENT_FINDING_CODES, INTENT_REASON_CODES } from "./intent";
 import { CHECK_CODES, CHECK_ERROR_CODES } from "./lineage-check";
 import { GROUP_REASON_CODES, MEMBER_REASON_CODES } from "./ls";
-import { isReasonCode, REASON_CODES, REASONS } from "./reason-codes";
-import { READ_ERROR_CODES, RECORD_REASON_CODES, RECORD_WARNING_CODES } from "./records";
-import { STATUS_ERROR_CODES, STATUS_REASON_CODES } from "./status";
+import intentSchema from "./intent.schema.json";
+import { isPluginCode, isReasonCode, REASON_CODES, REASONS } from "./reason-codes";
+import { contract } from "./__fixtures__/contract-repo";
+import { READ_ERROR_CODES, RECORD_REASON_CODES, RECORD_WARNING_CODES, REVIEW_REASON_CODES } from "./records";
+import { AMEND_ERROR_CODES, NEW_ERROR_CODES, REVIEW_ERROR_CODES } from "./records-write";
+import { RECORDS_SINCE_ERROR_CODES } from "./records-since";
+import { STATUS_ERROR_CODES, STATUS_GATE_REASON_CODES, STATUS_REASON_CODES } from "./status";
+import { WORK_WARNING_CODES } from "./work";
 
 const HERE = import.meta.dirname;
 
@@ -31,12 +37,22 @@ const PER_COMMAND: Record<string, readonly string[]> = {
   CHECK_ERROR_CODES,
   STATUS_REASON_CODES,
   STATUS_ERROR_CODES,
+  STATUS_GATE_REASON_CODES,
   RECORD_REASON_CODES,
   RECORD_WARNING_CODES,
+  REVIEW_REASON_CODES,
+  WORK_WARNING_CODES,
   READ_ERROR_CODES,
+  NEW_ERROR_CODES,
+  AMEND_ERROR_CODES,
+  REVIEW_ERROR_CODES,
+  RECORDS_SINCE_ERROR_CODES,
   INTENT_ERROR_CODES,
   INTENT_FINDING_CODES,
   INTENT_REASON_CODES,
+  COMPOSITES_ERROR_CODES,
+  COMPOSITES_REASON_CODES,
+  COMPOSITES_RUNTIME_REASON_CODES,
 };
 
 /** Every string in an `enum` under a property named `code`, anywhere in a schema. */
@@ -98,7 +114,7 @@ describe("the closed list of reason codes", () => {
   });
 
   test("no source file emits a code outside the list", () => {
-    const emitted = /(?:\bcode:\s*|(?:WorkspaceReadError|RecordReadError|StatusError|IntentError)\(\s*)"([a-z0-9-]+)"/g;
+    const emitted = /(?:\bcode:\s*|(?:WorkspaceReadError|RecordReadError|RecordWriteError|StatusError|IntentError)\(\s*)"([a-z0-9-]+)"/g;
     let seen = 0;
     for (const file of sourceFiles(HERE)) {
       const text = readFileSync(file, "utf-8");
@@ -111,6 +127,34 @@ describe("the closed list of reason codes", () => {
     expect(seen).toBeGreaterThan(30);
   });
 
+  test("a plugin's finding codes are in its own namespace, outside the list, and the intent schema accepts them (#2656)", () => {
+    expect(isPluginCode("plugin:chud:contract-criteria-changed")).toBe(true);
+    expect(isPluginCode("plugin:chud:contract-criteria-changed", "chud")).toBe(true);
+    expect(isPluginCode("plugin:chud:contract-criteria-changed", "units")).toBe(false);
+    for (const bad of ["plugin:chud", "plugin::x", "plugin:chud:Upper", "plugin:chud:a:b", "intent-commit-bare", 7]) expect(isPluginCode(bad), String(bad)).toBe(false);
+    expect(isReasonCode("plugin:chud:contract-criteria-changed")).toBe(false);
+    const { validate } = contract(intentSchema);
+    const finding = (code: string) => ({ id: `finding:${code}:1`, kind: "finding", code, message: "m", concerns: [] });
+    const doc = (code: string) => ({
+      $schema: intentSchema.$id,
+      contract: 1,
+      chant: "0.0.0",
+      at: null,
+      workspace: { name: "w", root: "." },
+      region: "region:.",
+      history: { rev: null, follows: "directory", shallow: false },
+      kinds: [],
+      nodes: [finding(code)],
+      edges: [],
+      reasons: [],
+      summary: { commits: 0, decisions: 0, artifacts: 0, findings: 1 },
+    });
+    expect(validate(doc("plugin:chud:contract-criteria-changed"))).toBe(true);
+    expect(validate(doc("intent-commit-bare"))).toBe(true);
+    expect(validate(doc("plugin:chud:Nope"))).toBe(false);
+    expect(validate(doc("made-up-code"))).toBe(false);
+  });
+
   test("the read-contract page documents every code", () => {
     const page = readFileSync(join(REPO, "docs", "src", "content", "docs", "reference", "workspace-read-contract.mdx"), "utf-8");
     for (const c of REASON_CODES) expect(page, c).toContain(`| \`${c}\` |`);

package/src/workspace/reason-codes.ts

@@ -53,17 +53,40 @@ export const REASONS = {
   // A ledger status can't fully read.
   "ledger-unreadable": "Reading the ledger failed, so nothing from it is listed.",
   "ledger-malformed": "Some lines of the ledger aren't release records; the rest are listed.",
+  // A member's gates status can't list (status, #2674).
+  "gates-no-ledger": "The checkout has no chant/lifecycle branch, so there is no gate ledger to read.",
+  "gates-no-gate-ledger": "The branch has no gate ledger for the member: no run of it has reached a gate.",
+  "gates-ledger-unreadable": "Reading the member's gate ledger failed, so no gate is listed.",
   // A record that isn't valid (records).
-  "record-unparseable": "No front matter, a YAML error, or a value outside the JSON subset of YAML.",
-  "record-schema-invalid": "The front matter does not match the kind's schema.",
+  "record-unparseable": "No front matter, a YAML error or a value outside the JSON subset of YAML, or for a JSON kind a file that is not one object or repeats a member name.",
+  "record-schema-invalid": "The record's front matter, or its JSON object, does not match the kind's schema.",
   "record-id-duplicate": "Another record earlier in path order has the same id.",
   "record-supersedes-unknown": "A supersedes link names an id no record has.",
   "record-supersedes-conflict": "A second closed record supersedes a record another one already superseded.",
+  // A review session that isn't valid (records, #2673).
+  "session-seal-mismatch": "A closed session's seal is not the digest of its text: the session changed after it closed.",
+  "session-verdict-unknown-record": "A session's verdict names a record that none of the session kind's subject records has.",
   // A record that is valid but warned about (records, #2549).
   "asset-drift": "A file the record pins by hash has changed: its bytes no longer hash to the pinned sha256.",
   "asset-missing": "A file the record pins by hash does not exist in the tree read.",
   "asset-stale": "A file the record pins is unchanged at the hash a record it supersedes pinned: the decision changed and the artifact did not follow.",
   "record-supersedes-pending": "A supersedes link from a record whose state is weaker than the record it names, so the link has no effect yet.",
+  "record-no-evidence": "The record's evidence list is empty: it cites nothing and pins no file. Information for a reviewer, never an error.",
+  "review-undigested": "A verdict names no digest of the text it judged. It still counts, and an amendment does not stop it counting.",
+  // A work record that is valid but warned about (records and graph --intent, #2683).
+  "work-needs-unknown": "A work record's needs list names a work id no record has, so the item stays blocked.",
+  "work-implements-unknown": "A work record's implements list names a decision id no decision has.",
+  "work-needs-cycle": "A work record needs itself through its needs links, so it can never be ready.",
+  "work-implements-undecided": "A work record implements a decision whose state is not approved, such as proposed.",
+  "work-done-unpinned": "A work record is done and its evidence list is empty: nothing shows the work was done.",
+  "work-closed-without-date": "A work record is done or dropped and has no closing date.",
+  "work-done-gap-open": "A work record is done, and the finding it came from still fires on its region. Only graph --intent raises it.",
+  // A verdict the quorum does not count (records, #2671, #2672).
+  "review-decider": "The verdict is the decider's own, and the quorum counts verdicts besides the decider's.",
+  "review-agent": "The reviewer holds the agent role in the trust policy at base.",
+  "review-duplicate": "A later verdict by the same principal replaces this one. Names are compared after NFKC, trimming and lower-casing.",
+  "review-older-digest": "The verdict names a digest other than the record's text now: the record changed after the verdict.",
+  "review-unattested": "An attestation policy is active at base, and the verdict carries no seal.",
   // A records read that fails (records).
   "kind-unreadable": "The record kind file is missing or could not be imported.",
   "kind-invalid": "The record kind file exports no recordKind, or its shape is wrong.",
@@ -71,6 +94,20 @@ export const REASONS = {
   "schema-id-mismatch": "The schema's $id differs from the id the record kind names.",
   "schema-invalid": "The record schema itself does not compile.",
   "location-missing": "The records directory does not exist, in the tree or at the revision.",
+  // A records write that is refused (records new, amend and review, #2670). Nothing is written.
+  "write-usage-invalid": "The command line lacks a value the write needs, or gives one it does not take.",
+  "write-input-invalid": "The fields given with --from or --set can't be read, are not JSON, or are not a JSON object.",
+  "record-not-found": "No record of the kind has the id given.",
+  "record-id-taken": "The id given for a new record is already used, by a record or a file name.",
+  "record-id-unallocatable": "No id was given and none can be allocated: the records share no single prefix and --prefix names none.",
+  "record-path-unmatched": "The file name made from the record's id and title does not match the kind's location.",
+  "record-closed": "The record is in a closed state, so nothing in it changes; a new record supersedes it instead.",
+  "amend-id-immutable": "An amendment changes the record's id, and ids are never renumbered.",
+  "amend-supersede-instead": "The record is approved, and the amendment changes a field the approval rule does not let change in place; a new record supersedes it instead.",
+  "review-unsupported": "The kind's schema has no reviews field, so its records take no review.",
+  "review-note-required": "A dissent was given with no note: a dissent needs a reason.",
+  // records --since that fails (#2673).
+  "since-rev-unknown": "--since names no commit.",
   // The intent graph (graph --intent, #2651): a read that fails.
   "intent-region-invalid": "The region's path, or its line range, does not exist in the tree read.",
   // The intent graph: part of the walk that can't be read. The document is still printed.
@@ -89,6 +126,16 @@ export const REASONS = {
   "intent-evidence-unpinned": "A decision's evidence has no hash: a URL, or a path with no sha256.",
   "intent-trailer-unverified": "A commit carries a trailer a plugin says claims authorship, and the commit is not attested.",
   "intent-region-unconstrained": "No decision constrains the region at any granularity.",
+  "intent-decision-unimplemented": "A decided decision constrains the region, no work item that is not dropped implements it, and no commit falls in its window.",
+  "intent-work-blocked": "A work item constraining the region has commits in its window while a work item it needs is not done.",
+  "intent-work-open-decided-code": "Commits in the region are a decision's own work while the work item implementing that decision is still open.",
+  // Composite instances joined to components (graph --composites, #2662): why the list is empty or has no component.
+  "composites-no-chant-member": "No member of kind chant was read, so nothing declares a composite instance or a component.",
+  "composites-none-declared": "The members read declare no composite instance.",
+  "composites-no-component": "The members read declare no component, so no composite instance has one.",
+  // The runtimes a member's components can deploy on (graph --composites, #2674).
+  "runtimes-config-unreadable": "The member's chant.config.ts could not be read, so only the built-in local runtime is listed.",
+  "runtimes-lexicon-unreadable": "A lexicon the member's config lists could not be loaded, so it is not listed as a runtime.",
   // The lineage lock (check).
   "lock-invalid": "The lineage lock can't be read.",
   "manual-step-open": "A scope in the lineage lock has an open manual step.",
@@ -102,3 +149,21 @@ export const REASON_CODES = Object.keys(REASONS) as ReasonCode[];
 export function isReasonCode(value: unknown): value is ReasonCode {
   return typeof value === "string" && Object.prototype.hasOwnProperty.call(REASONS, value);
 }
+
+/**
+ * A finding code a plugin contributes to the intent graph through its
+ * `commitJoins` (#2656): `plugin:<name>:<code>`, where `<name>` is the kind's
+ * name, or the kind file's `commitJoinsName` when it has one (#2663), and
+ * `<code>` is lower case words joined by dashes. These are outside the
+ * closed list: the plugin owns its namespace, and core only carries them.
+ */
+export type PluginCode = `plugin:${string}:${string}`;
+
+export const PLUGIN_CODE = /^plugin:([^:\s]+):([a-z0-9]+(?:-[a-z0-9]+)*)$/;
+
+/** Whether `value` is a plugin code, and, given `name` (a kind's name or its `commitJoinsName`), one in that namespace. */
+export function isPluginCode(value: unknown, name?: string): value is PluginCode {
+  if (typeof value !== "string") return false;
+  const m = value.match(PLUGIN_CODE);
+  return !!m && (name === undefined || m[1] === name);
+}

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

@@ -17,6 +17,7 @@ import { runChecks } from "./lineage-check";
 import { constraintCovers, isWorkspacePath, memberHolding, WORKSPACE_PATH_PATTERN } from "./record-assets";
 import { pinFile, queryRecords, type RecordsDocument } from "./records-cli";
 import { parseFrontMatter, RECORD_WARNING_CODES } from "./records";
+import { WORK_WARNING_CODES } from "./work";
 import { workspaceGraph } from "./graph-cli";
 import graphSchema from "./graph.schema.json";
 import recordsSchema from "./records.schema.json";
@@ -168,7 +169,8 @@ describe("chant workspace records checks each pin", () => {
   });
 
   test("the schema lists exactly the warning codes", () => {
-    expect(recordsSchema.$defs.warning.properties.code.enum).toEqual([...RECORD_WARNING_CODES]);
+    // A work kind's records carry the work warnings too, except work-done-gap-open, which only graph --intent raises (#2683).
+    expect(recordsSchema.$defs.warning.properties.code.enum).toEqual([...RECORD_WARNING_CODES, ...WORK_WARNING_CODES.filter((c) => c !== "work-done-gap-open")]);
   });
 
   test("records pin <path> prints the entry's path from the workspace root and the file's hash", () => {