@intentius/chant 0.91.0 → 0.93.0

package/src/workspace/declaration.schema.json

@@ -63,6 +63,13 @@
         "$ref": "#/$defs/host"
       }
     },
+    "diagrams": {
+      "type": "array",
+      "description": "The workspace's own diagram artifacts (#2764): the diagrams that belong to no one member, such as a diagrams directory at the root. A member names its own in its diagrams. chant workspace ls lists every declared diagram, and chant workspace check reports one whose render is stale for its source when the entry records a sourceHash. Added in schema 1 by chant 0.91.0, so a declaration that uses it sets minReader to 0.91.0 or newer.",
+      "items": {
+        "$ref": "#/$defs/diagram"
+      }
+    },
     "checks": {
       "type": "object",
       "description": "Severity for the declaration checks that allow it, keyed by WSP id (#2535, ws-028): error, warning, info or off. chant workspace check refuses an id it does not know, and one whose severity is fixed.",
@@ -72,6 +79,28 @@
       "additionalProperties": {
         "$ref": "#/$defs/severity"
       }
+    },
+    "changes": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "The forward coverage check, chant workspace check --changes <base>..<head> (#2773): each path a diff changes is mapped to the current records whose constrains cover it. severity says what a finding does: off reports none, warn (the default) reports them and passes, fail reports them and fails. ignore lists globs over files whose changes need no record, such as lockfiles and generated output. Added in schema 1 by chant 0.92.0, so a declaration that uses it sets minReader to 0.92.0 or newer.",
+      "properties": {
+        "severity": {
+          "enum": [
+            "off",
+            "warn",
+            "fail"
+          ],
+          "description": "What a change-uncovered or change-out-of-scope finding does. warn when absent."
+        },
+        "ignore": {
+          "type": "array",
+          "description": "Globs over file paths from the workspace root: * and ? within one segment, ** across segments. A changed path one matches is listed as ignored and never reported.",
+          "items": {
+            "$ref": "#/$defs/fileGlob"
+          }
+        }
+      }
     }
   },
   "patternProperties": {
@@ -276,6 +305,13 @@
             "$ref": "#/$defs/recordKind"
           }
         },
+        "diagrams": {
+          "type": "array",
+          "description": "The diagram artifacts this member holds (#2764). chant workspace ls lists every declared diagram, and chant workspace check reports one whose render is stale for its source when the entry records a sourceHash. Added in schema 1 by chant 0.91.0, so a declaration that uses it sets minReader to 0.91.0 or newer.",
+          "items": {
+            "$ref": "#/$defs/diagram"
+          }
+        },
         "box": {
           "$ref": "#/$defs/box"
         },
@@ -366,7 +402,7 @@
     },
     "box": {
       "type": "object",
-      "description": "The member is a box, or holds a box's declarations (#2726). A box holds no credential: each capability it needs outside itself is reached through a broker, a runtime such as a lobby or a door, which holds the credential and enforces the scope. chant workspace check fails when a file in the member's directory carries a literal secret (WSP121) and when a capability names no broker (WSP122). chant workspace status --json lists the capabilities, so a broker can read the scopes. Its host, slot, ports, state and cookies state the box's isolation (#2727): chant derives each value from the box's identity, its host, the member's name and its slot, and prints them in chant workspace status --json, so a runtime reads them instead of choosing its own. chant workspace check fails when two boxes on a host resolve to the same value (WSP123) and when a box hard-codes a machine path (WSP124). Added in schema 1 by chant 0.91.0, so a declaration that uses it sets minReader to 0.91.0 or newer.",
+      "description": "The member is a box, or holds a box's declarations (#2726). A box holds no credential: each capability it needs outside itself is reached through a broker, a runtime such as a lobby or a door, which holds the credential and enforces the scope. chant workspace check fails when a file in the member's directory carries a literal secret (WSP121) and when a capability names no broker (WSP122). chant workspace status --json lists the capabilities, so a broker can read the scopes. Its host, slot, ports, state and cookies state the box's isolation (#2727): chant derives each value from the box's identity, its host, the member's name and its slot, and prints them in chant workspace status --json, so a runtime reads them instead of choosing its own. chant workspace check fails when two boxes on a host resolve to the same value (WSP123) and when a box hard-codes a machine path (WSP124). A member that builds the fountain lexicon's Box declares the callback token fountain gives its persistent sandbox as the capability fountain-callback, brokered by fountain, with scope owner, or chant workspace check fails (WSP125, #2780). Added in schema 1 by chant 0.91.0, so a declaration that uses it sets minReader to 0.91.0 or newer.",
       "properties": {
         "capabilities": {
           "type": "array",
@@ -493,6 +529,78 @@
       },
       "additionalProperties": false
     },
+    "diagram": {
+      "type": "object",
+      "description": "A diagram artifact the workspace declares (#2764): a rendered image with a source, pinned to the renderer that made it. chant never runs the renderer.",
+      "required": [
+        "name",
+        "title",
+        "render",
+        "renderer"
+      ],
+      "properties": {
+        "name": {
+          "$ref": "#/$defs/name",
+          "description": "Unique across the declaration."
+        },
+        "title": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Shown above the diagram."
+        },
+        "source": {
+          "oneOf": [
+            { "$ref": "#/$defs/path" },
+            { "type": "null" }
+          ],
+          "description": "The source file, from the workspace root, with / separators. Null for an SVG with no source. Default null."
+        },
+        "render": {
+          "$ref": "#/$defs/path",
+          "description": "The rendered image, from the workspace root, with / separators."
+        },
+        "renderer": {
+          "$ref": "#/$defs/diagramRenderer"
+        },
+        "sourceHash": {
+          "type": ["string", "null"],
+          "pattern": "^[0-9a-f]{64}$",
+          "description": "sha256 hex of the source's bytes when render was last produced from it. chant workspace check compares this against the source in the tree read and reports drift (WSP133) on a mismatch; without it, or without a source, the render is never checked for drift. Default null."
+        }
+      },
+      "patternProperties": {
+        "^x-": true
+      },
+      "additionalProperties": false
+    },
+    "diagramRenderer": {
+      "type": "object",
+      "description": "The renderer a diagram's render was made with. chant records the pin; it never installs or runs the renderer (ws-052).",
+      "required": [
+        "tool",
+        "version"
+      ],
+      "properties": {
+        "tool": {
+          "enum": ["d2", "mermaid", "graphviz"]
+        },
+        "version": {
+          "$ref": "#/$defs/version",
+          "description": "The exact release the render was made with, such as 0.9.0."
+        },
+        "args": {
+          "type": "array",
+          "description": "Passed before the input and output paths, in order, such as [\"--layout=elk\", \"--theme=0\", \"--pad=40\", \"--omit-version\"]. Empty when absent.",
+          "items": {
+            "type": "string"
+          }
+        }
+      },
+      "patternProperties": {
+        "^x-": true
+      },
+      "additionalProperties": false
+    },
     "generatedFile": {
       "type": "object",
       "description": "One generated file of a member (#2524 D14, #2541).",
@@ -641,6 +749,11 @@
       "type": "integer",
       "minimum": 1,
       "maximum": 65535
+    },
+    "fileGlob": {
+      "type": "string",
+      "description": "A glob over file paths, relative to the workspace root: * and ? within one segment, ** across segments, [...] classes and {a,b} alternatives. No leading /, no . or .. segments.",
+      "pattern": "^(?!\\.\\.?(/|$))[^/\\\\]+(/(?!\\.\\.?(/|$))[^/\\\\]+)*$"
     }
   }
 }

package/src/workspace/declaration.test.ts

@@ -6,6 +6,7 @@ import { afterAll, describe, expect, test } from "vitest";
 import {
   compareVersions,
   DECLARATION_SCHEMA_ID,
+  declaredDiagrams,
   ownerOf,
   parseDeclaration,
   readDeclaration,
@@ -345,3 +346,60 @@ describe("generated files (#2541)", () => {
     expect(failure(base([{ name: "g", kind: "examples", glob: "examples/*", generated: [] }])).message).toContain('unknown field "generated"');
   });
 });
+
+describe("diagram artifacts (#2764)", () => {
+  const renderer = { tool: "d2", version: "0.9.0", args: ["--layout=elk", "--theme=0", "--pad=40", "--omit-version"] };
+  const diagram = (extra: Record<string, unknown> = {}) => ({
+    name: "architecture",
+    title: "Studio architecture",
+    source: "docs/diagrams/architecture.d2",
+    render: "docs/diagrams/architecture.svg",
+    renderer,
+    ...extra,
+  });
+  const member = (diagrams: unknown[], extra: Record<string, unknown> = {}) => ({ name: "docs", dir: "docs", kind: "other", because: "the docs site", diagrams, ...extra });
+
+  test("a member's diagram is read with the workspace-relative source and render, and a null source is the default", () => {
+    const d = parse(base([member([diagram()])]));
+    expect(d.members[0].diagrams).toEqual([
+      { name: "architecture", title: "Studio architecture", source: "docs/diagrams/architecture.d2", render: "docs/diagrams/architecture.svg", renderer, sourceHash: null, member: "docs", pointer: "/members/0/diagrams/0" },
+    ]);
+    const noSource = parse(base([member([diagram({ source: undefined })])]));
+    expect(noSource.members[0].diagrams[0].source).toBeNull();
+  });
+
+  test("the workspace's own diagrams are in the top-level diagrams, with member null", () => {
+    const d = parse(base([{ name: "x", dir: "x", kind: "chant" }], { diagrams: [diagram({ name: "boundary" })] }));
+    expect(d.diagrams).toEqual([{ ...diagram({ name: "boundary" }), sourceHash: null, member: null, pointer: "/diagrams/0" }]);
+    expect(declaredDiagrams(d)).toEqual(d.diagrams);
+  });
+
+  test("declaredDiagrams lists the workspace's own first, then each member's, in file order", () => {
+    const d = parse(base([member([diagram()]), { name: "app", dir: "app", kind: "chant" }], { diagrams: [diagram({ name: "boundary", render: "docs/diagrams/boundary.svg" })] }));
+    expect(declaredDiagrams(d).map((x) => x.name)).toEqual(["boundary", "architecture"]);
+  });
+
+  test("a diagram name is unique across the declaration, workspace and members together", () => {
+    const clash = failure(base([member([diagram()])], { diagrams: [diagram()] }));
+    expect(clash.code).toBe("declaration-invalid");
+    expect(clash.message).toContain('the diagram name "architecture" is already used by the diagram at /diagrams/0');
+  });
+
+  test("renderer.tool is a closed list, and title, render and renderer are required", () => {
+    expect(failure(base([member([diagram({ renderer: { tool: "mscgen", version: "1.0.0" } })])])).code).toBe("declaration-invalid");
+    expect(failure(base([member([{ name: "a", source: null, render: "a.svg", renderer }])])).message).toContain('missing required field "title"');
+    expect(failure(base([member([{ name: "a", title: "A", source: null, renderer }])])).message).toContain('missing required field "render"');
+    expect(failure(base([member([{ name: "a", title: "A", source: null, render: "a.svg" }])])).message).toContain('missing required field "renderer"');
+  });
+
+  test("a sourceHash is a 64-character lowercase hex string, or absent", () => {
+    const hash = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855";
+    expect(parse(base([member([diagram({ sourceHash: hash })])])).members[0].diagrams[0].sourceHash).toBe(hash);
+    expect(failure(base([member([diagram({ sourceHash: "not-a-hash" })])])).code).toBe("declaration-invalid");
+  });
+
+  test("source and render stay inside the workspace, like every other path", () => {
+    expect(failure(base([member([diagram({ source: "/etc/passwd" })])])).code).toBe("declaration-invalid");
+    expect(failure(base([member([diagram({ render: "../out.svg" })])])).code).toBe("declaration-invalid");
+  });
+});

package/src/workspace/declaration.ts

@@ -96,6 +96,17 @@ export interface Suppression {
 /** What `checks` may set a declaration check's severity to. */
 export type CheckSeverity = "error" | "warning" | "info" | "off";
 
+/** How `chant workspace check --changes` treats its findings (#2773): not at all, as warnings, or as failures. */
+export type ChangeSeverity = "off" | "warn" | "fail";
+
+/** The declaration's `changes` block (#2773): the severity of the forward coverage check, and the paths it never reports. */
+export interface ChangesPolicy {
+  /** Absent from the declaration, `warn`. */
+  severity: ChangeSeverity;
+  /** Globs over files, relative to the workspace root, whose changes need no record: lockfiles, generated output. */
+  ignore: string[];
+}
+
 export interface MemberRole {
   name: string;
   /** Relative to the member's directory, or null for the whole member. */
@@ -128,6 +139,40 @@ export interface LinkDeclaration {
   pointer: string;
 }
 
+/** A renderer a diagram is pinned to (#2764): a closed list of tools chant does not run. */
+export const DIAGRAM_TOOLS = ["d2", "mermaid", "graphviz"] as const;
+export type DiagramTool = (typeof DIAGRAM_TOOLS)[number];
+
+/** The renderer a diagram's render was made with (#2764). chant never runs it; it is recorded so a reader can. */
+export interface DiagramRenderer {
+  tool: DiagramTool;
+  /** The exact release the render was made with, such as "0.9.0". */
+  version: string;
+  /** Passed before the input and output paths, in order. */
+  args: string[];
+}
+
+/**
+ * A diagram artifact the declaration names (#2764): the workspace's own, in
+ * the top-level `diagrams`, or a member's, in that member's `diagrams`. A
+ * name is given once across the declaration, like a record kind's.
+ */
+export interface DiagramDeclaration {
+  name: string;
+  title: string;
+  /** From the workspace root, with / separators. Null for an SVG with no source. */
+  source: string | null;
+  /** From the workspace root, with / separators. */
+  render: string;
+  renderer: DiagramRenderer;
+  /** sha256 hex of the source's bytes when the render was last produced, for `chant workspace check`'s drift finding. Null when not recorded, or when source is null: the render is then never checked for drift. */
+  sourceHash: string | null;
+  /** The member that declares it, or null for the workspace's own. */
+  member: string | null;
+  /** The entry's JSON Pointer in the file, for messages. */
+  pointer: string;
+}
+
 /**
  * A record kind the declaration names (#2680): the workspace's own, in the
  * top-level `records`, or a member's, in that member's `records`.
@@ -208,6 +253,8 @@ export interface Member {
   links: LinkDeclaration[];
   /** The record kinds this member declares, in file order (#2680). */
   records: RecordKindDeclaration[];
+  /** The diagram artifacts this member declares, in file order (#2764). */
+  diagrams: DiagramDeclaration[];
   /** The member's box block, or null when it declares none (#2726). */
   box: BoxDeclaration | null;
   upstream: string | null;
@@ -252,8 +299,12 @@ export interface Declaration {
   quorum: number | null;
   /** The workspace's own record kinds, from the top-level `records`, in file order (#2680). A member's are on the member. */
   records: RecordKindDeclaration[];
+  /** The workspace's own diagram artifacts, from the top-level `diagrams`, in file order (#2764). A member's are on the member. */
+  diagrams: DiagramDeclaration[];
   /** The hosts boxes run on, in file order (#2727). */
   hosts: Host[];
+  /** The forward coverage check's policy (#2773), or null when the declaration has no `changes` block. */
+  changes: ChangesPolicy | null;
   /** The file, relative to the workspace root's tree (`chant.workspace.json` or `.jsonc`). */
   file: string;
 }
@@ -466,6 +517,7 @@ export function parseDeclaration(text: string, file: string, reader: string = re
       pointer: `${pointer}/links/${j}`,
     }));
     const records = recordKindsOf(e.records, e.dir as string, e.name as string, `${pointer}/records`);
+    const diagrams = diagramsOf(e.diagrams, e.name as string, `${pointer}/diagrams`);
     const box = boxOf(e.box, `${pointer}/box`);
     return {
       type: "member",
@@ -477,6 +529,7 @@ export function parseDeclaration(text: string, file: string, reader: string = re
       outputs: e.outputs === undefined ? null : [...(e.outputs as string[])],
       links,
       records,
+      diagrams,
       box,
       upstream: (e.upstream as string | undefined) ?? null,
       because: (e.because as string | undefined) ?? null,
@@ -572,6 +625,17 @@ export function parseDeclaration(text: string, file: string, reader: string = re
     }
   }
 
+  // A diagram name is given once across the declaration (#2764): a reader keys diagrams by name.
+  const ownDiagrams = diagramsOf(obj.diagrams, null, "/diagrams");
+  const byDiagramName = new Map<string, DiagramDeclaration>();
+  for (const d of [...ownDiagrams, ...members.flatMap((m) => m.diagrams)]) {
+    const first = byDiagramName.get(d.name);
+    if (first) {
+      throw new WorkspaceReadError("declaration-invalid", `the diagram name ${JSON.stringify(d.name)} is already used by the diagram at ${first.pointer}`, at(`${d.pointer}/name`));
+    }
+    byDiagramName.set(d.name, d);
+  }
+
   const hosts = hostsOf(obj, members, at);
 
   const pins = ((obj.pins as Record<string, string>[] | undefined) ?? []).map((p) => ({
@@ -592,11 +656,19 @@ export function parseDeclaration(text: string, file: string, reader: string = re
     checks: { ...((obj.checks as Record<string, CheckSeverity> | undefined) ?? {}) },
     quorum: typeof obj.quorum === "number" ? obj.quorum : null,
     records: ownRecords,
+    diagrams: ownDiagrams,
     hosts,
+    changes: changesOf(obj.changes as Record<string, unknown> | undefined),
     file,
   };
 }
 
+/** The `changes` block, already validated, with its defaults (#2773). */
+function changesOf(block: Record<string, unknown> | undefined): ChangesPolicy | null {
+  if (block === undefined) return null;
+  return { severity: (block.severity as ChangeSeverity | undefined) ?? "warn", ignore: [...((block.ignore as string[] | undefined) ?? [])] };
+}
+
 /** The `records` list at `pointer`, already validated, with each kind file's path from the workspace root. */
 function recordKindsOf(raw: unknown, dir: string, member: string | null, pointer: string): RecordKindDeclaration[] {
   return ((raw as { kind: string; name?: string }[] | undefined) ?? []).map((r, i) => ({
@@ -608,6 +680,29 @@ function recordKindsOf(raw: unknown, dir: string, member: string | null, pointer
   }));
 }
 
+/**
+ * The `diagrams` list at `pointer`, already validated. `source` and `render`
+ * are workspace-root-relative as written: unlike a generated file or a
+ * record kind, a diagram's files need not sit inside the declaring member's
+ * directory, so there is no member-relative form to resolve (#2764).
+ */
+function diagramsOf(raw: unknown, member: string | null, pointer: string): DiagramDeclaration[] {
+  return (
+    (raw as
+      | { name: string; title: string; source?: string | null; render: string; renderer: { tool: DiagramTool; version: string; args?: string[] }; sourceHash?: string | null }[]
+      | undefined) ?? []
+  ).map((d, i) => ({
+    name: d.name,
+    title: d.title,
+    source: d.source ?? null,
+    render: d.render,
+    renderer: { tool: d.renderer.tool, version: d.renderer.version, args: [...(d.renderer.args ?? [])] },
+    sourceHash: d.sourceHash ?? null,
+    member,
+    pointer: `${pointer}/${i}`,
+  }));
+}
+
 /** The `box` block at `pointer`, already validated, or null when there is none (#2726, #2727). */
 function boxOf(raw: unknown, pointer: string): BoxDeclaration | null {
   if (raw === undefined) return null;
@@ -687,6 +782,15 @@ export function declaredRecordKinds(declaration: Declaration): RecordKindDeclara
   return [...declaration.records, ...declaration.members.flatMap((m) => m.records)];
 }
 
+/**
+ * Every diagram artifact the declaration names (#2764), in the order readers
+ * use them: the workspace's own first, then each member's, members in file
+ * order and each list in its own order.
+ */
+export function declaredDiagrams(declaration: Declaration): DiagramDeclaration[] {
+  return [...declaration.diagrams, ...declaration.members.flatMap((m) => m.diagrams)];
+}
+
 /** Whether `path` is `dir` or sits under it. Both are tree-relative; `"."` is the root. */
 export function isInside(path: string, dir: string): boolean {
   if (dir === ".") return true;

package/src/workspace/declared-kinds.test.ts

@@ -111,20 +111,20 @@ describe("workspace ls lists the declared kinds (#2680)", () => {
     ]);
     const doc = result(await listWorkspaceWithKinds({ cwd: root }));
     expect(doc.contract).toBe(1);
-    expect(doc.workspace.records).toEqual([{ name: "decision", path: "decisions/decision.kind.mjs", kind: "decision", reason: null }]);
+    expect(doc.workspace.records).toEqual([{ name: "decision", path: "decisions/decision.kind.mjs", kind: "decision", reason: null, acceptance: null }]);
     const design = doc.members.find((m) => m.name === "design")!;
     expect(design.readable).toBe(true);
     expect(design.records).toEqual([
-      { name: "notes", path: "design/notes/note.kind.mjs", kind: "note", reason: null },
-      { name: null, path: "design/gone.kind.mjs", kind: null, reason: { code: "kind-unreadable", message: "kind file design/gone.kind.mjs does not exist" } },
-      { name: null, path: "design/broken.kind.mjs", kind: null, reason: { code: "kind-invalid", message: "kind file design/broken.kind.mjs is not a record kind: it has no recordKind export" } },
+      { name: "notes", path: "design/notes/note.kind.mjs", kind: "note", reason: null, acceptance: null },
+      { name: null, path: "design/gone.kind.mjs", kind: null, reason: { code: "kind-unreadable", message: "kind file design/gone.kind.mjs does not exist" }, acceptance: null },
+      { name: null, path: "design/broken.kind.mjs", kind: null, reason: { code: "kind-invalid", message: "kind file design/broken.kind.mjs is not a record kind: it has no recordKind export" }, acceptance: null },
     ]);
     expect(doc.members.find((m) => m.name === "app")!.records).toEqual([]);
   });
 
   test("listWorkspace lists them unloaded, and a workspace that names none lists empty arrays", async () => {
     const doc = result(listWorkspace({ cwd: workspace() }));
-    expect(doc.workspace.records).toEqual([{ name: null, path: "decisions/decision.kind.mjs", kind: null, reason: null }]);
+    expect(doc.workspace.records).toEqual([{ name: null, path: "decisions/decision.kind.mjs", kind: null, reason: null, acceptance: null }]);
     const none = result(await listWorkspaceWithKinds({ cwd: repo({ "chant.workspace.json": decl(members()), "app/x": "", "design/x": "" }) }));
     expect(none.workspace.records).toEqual([]);
     expect(none.members.map((m) => m.records)).toEqual([[], []]);

package/src/workspace/declared-kinds.ts

@@ -36,6 +36,25 @@ export interface DeclaredKind {
    * other kind, and when the kind wasn't loaded.
    */
   points?: { file: string; problems: { field: string | null; message: string }[] };
+  /**
+   * For a work kind with acceptance criteria (#2772), read with
+   * `acceptance: true`: each current record that lists criteria, with how
+   * many are met. Absent for any other kind, when the kind wasn't loaded,
+   * and when its records can't be read (`records` reports why).
+   */
+  acceptance?: DeclaredAcceptance[];
+}
+
+/** One work record's acceptance criteria, counted, as `ls`, `status` and `check` read them (#2772). */
+export interface DeclaredAcceptance {
+  item: string;
+  state: string | null;
+  met: number;
+  total: number;
+  /** The record file on disk, absolute. */
+  file: string;
+  /** The record's `work-acceptance-unmet` warning, when it is done with a criterion unmet; null otherwise. */
+  unmet: string | null;
 }
 
 /** The kind file of `declared` on disk, under the workspace root `rootOnDisk`. */
@@ -53,7 +72,7 @@ export async function loadDeclaredKinds(
   declaration: Declaration,
   tree: WorkspaceTree,
   rootOnDisk: string,
-  options: { load?: boolean } = {},
+  options: { load?: boolean; acceptance?: boolean; at?: string } = {},
 ): Promise<DeclaredKind[]> {
   const declared = declaredRecordKinds(declaration);
   if (declared.length === 0) return [];
@@ -73,6 +92,10 @@ export async function loadDeclaredKinds(
       const loaded = await records.loadRecordKind(file);
       const entry: DeclaredKind = { declared: d, file, kind: loaded.kind.name, reason: null };
       if (loaded.kind.answers) entry.points = await checkPoints(resolve(dirname(file), loaded.kind.answers.points), rootOnDisk, tree);
+      if (loaded.kind.work?.acceptance && options.acceptance) {
+        const counted = await countAcceptance(file, rootOnDisk, options.at);
+        if (counted) entry.acceptance = counted;
+      }
       out.push(entry);
     } catch (err) {
       if (!(err instanceof records.RecordReadError)) throw err;
@@ -83,6 +106,28 @@ export async function loadDeclaredKinds(
   return out;
 }
 
+/** The acceptance counts of a work kind's current records, or undefined when they can't be read. */
+async function countAcceptance(file: string, rootOnDisk: string, at: string | undefined): Promise<DeclaredAcceptance[] | undefined> {
+  const { readRecordsFor } = await import("./records-cli");
+  const { RecordReadError } = await import("./records");
+  try {
+    const read = await readRecordsFor({ kind: file, cwd: rootOnDisk, current: true, ...(at !== undefined ? { at } : {}) });
+    return read.result.records
+      .filter((r): r is typeof r & { id: string; acceptance: NonNullable<typeof r.acceptance> } => r.id !== null && r.acceptance != null)
+      .map((r) => ({
+        item: r.id,
+        state: r.state,
+        met: r.acceptance.met,
+        total: r.acceptance.total,
+        file: join(read.root, ...r.path.split("/")),
+        unmet: r.warnings.find((w) => w.code === "work-acceptance-unmet")?.message ?? null,
+      }));
+  } catch (err) {
+    if (err instanceof RecordReadError) return undefined;
+    throw err;
+  }
+}
+
 /** An answer kind's points file (ws-058), read from `tree` and validated as `points ask` reads it. */
 async function checkPoints(abs: string, rootOnDisk: string, tree: WorkspaceTree): Promise<NonNullable<DeclaredKind["points"]>> {
   const file = relative(rootOnDisk, abs).split(sep).join("/");

package/src/workspace/generated-files.ts

@@ -22,6 +22,7 @@
 import { relative, resolve, sep } from "node:path";
 import { findWorkspaceRoot } from "../project-root";
 import { isInside, readDeclaration, type Declaration } from "./declaration";
+import { memberHolding } from "./record-assets";
 import { workingTree } from "./tree";
 
 /** What `chant update` rewrites, registered as implicit generated entries. */
@@ -79,6 +80,19 @@ export function declaredFilesUnder(declaration: Declaration, dir: string): Map<s
   return out;
 }
 
+/**
+ * Whether a workspace path (from the workspace root) is a generated file:
+ * declared in its member's `generated` entries, or one core registers. The
+ * `generated` of `graph --intent`'s region and file nodes and of `check
+ * --changes`'s paths.
+ */
+export function isGeneratedPath(declaration: Declaration, path: string): boolean {
+  const m = declaration.members.find((x) => x.name === memberHolding(path, declaration.members));
+  const dir = m?.dir ?? ".";
+  const rel = dir === "." ? path : path.slice(dir.length + 1);
+  return classifyFile(rel, declaredFilesUnder(declaration, dir)).class === "generated";
+}
+
 /**
  * The declared generated files for the absolute directory `absDir`, from the
  * nearest `chant.workspace.json` above it. Empty when there is none, which is

package/src/workspace/graph-cli.ts

@@ -220,7 +220,7 @@ export async function workspaceGraph(query: GraphQuery): Promise<GraphResult> {
       try {
         const read = await readRecordsFor({ kind: query.kind, cwd: query.cwd, at: query.at });
         const name = read.loaded.kind.name;
-        graph.records = read.result.records.map((r) => ({ kind: name, id: r.id, path: r.path, state: r.state, valid: r.valid, supersededBy: r.supersededBy }));
+        graph.records = read.result.records.map((r) => ({ kind: name, id: r.id, path: r.path, state: r.state, valid: r.valid, supersededBy: r.supersededBy, remediatedBy: r.remediatedBy }));
         graph.links.push(...recordLinkRows(name, read.result.records, read.loaded.kind.constrains?.field, located.tree, declaration.members));
       } catch (err) {
         if (!(err instanceof RecordReadError)) throw err;

package/src/workspace/graph.schema.json

@@ -752,7 +752,8 @@
         "path",
         "state",
         "valid",
-        "supersededBy"
+        "supersededBy",
+        "remediatedBy"
       ],
       "properties": {
         "kind": {
@@ -784,6 +785,13 @@
             "string",
             "null"
           ]
+        },
+        "remediatedBy": {
+          "description": "Added in contract 1 by #2774. The ids of records whose remediates link names this one.",
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
         }
       }
     }

package/src/workspace/intent.schema.json

@@ -600,7 +600,9 @@
                   "record-schema-invalid",
                   "record-id-duplicate",
                   "record-supersedes-unknown",
-                  "record-supersedes-conflict"
+                  "record-supersedes-conflict",
+                  "record-remediates-unknown",
+                  "record-remediates-not-closed"
                 ]
               },
               "message": {
@@ -794,7 +796,9 @@
                   "record-schema-invalid",
                   "record-id-duplicate",
                   "record-supersedes-unknown",
-                  "record-supersedes-conflict"
+                  "record-supersedes-conflict",
+                  "record-remediates-unknown",
+                  "record-remediates-not-closed"
                 ]
               },
               "message": {
@@ -941,6 +945,8 @@
                   "work-done-unpinned",
                   "work-closed-without-date",
                   "work-done-gap-open",
+                  "work-acceptance-unmet",
+                  "work-acceptance-self-verified",
                   "answer-points-unreadable",
                   "answer-point-unknown",
                   "answer-point-changed"

package/src/workspace/intent.ts

@@ -38,7 +38,7 @@ import { realpathSync } from "node:fs";
 import { basename, dirname, relative, resolve, sep } from "node:path";
 import { declaredRecordKinds, readDeclaration, readerVersion, resolveGroups, WORKSPACE_ERROR_CODES, WorkspaceReadError, type Declaration } from "./declaration";
 import { declaredKindFile } from "./declared-kinds";
-import { classifyFile, declaredFilesUnder } from "./generated-files";
+import { isGeneratedPath } from "./generated-files";
 import { entityDecisions, hasTrailer, readCommitJoins, runCommitJoins, type CommitJoins, type IntentCommit, type JoinedEntity, type PluginFinding } from "./intent-joins";
 import { loadKindRegistry } from "./kinds";
 import { resolveLinks, type LinkTableRow } from "./links";
@@ -541,13 +541,6 @@ function filesUnder(tree: WorkspaceTree, dir: string): string[] {
   return out;
 }
 
-function isGenerated(declaration: Declaration, path: string): boolean {
-  const m = declaration.members.find((x) => x.name === memberHolding(path, declaration.members));
-  const dir = m?.dir ?? ".";
-  const rel = dir === "." ? path : path.slice(dir.length + 1);
-  return classifyFile(rel, declaredFilesUnder(declaration, dir)).class === "generated";
-}
-
 function stringOr(v: unknown): string | null {
   return typeof v === "string" ? v : null;
 }
@@ -707,9 +700,9 @@ async function walk(query: IntentQuery, head: Head): Promise<IntentResult> {
   // 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);
-  add<RegionNode>({ id: rid, kind: "region", path: region.path, lines: region.lines, member, at: located.at, type, generated: type === "file" ? isGenerated(declaration, region.path) : null, node: region.node });
+  add<RegionNode>({ 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 });
   const files = type === "dir" ? filesUnder(located.tree, region.path) : [];
-  for (const f of files) add<FileNode>({ id: `file:${f}`, kind: "file", path: f, member: memberHolding(f, declaration.members), generated: isGenerated(declaration, f) });
+  for (const f of files) add<FileNode>({ id: `file:${f}`, kind: "file", path: f, member: memberHolding(f, declaration.members), generated: isGeneratedPath(declaration, f) });
   const memberNode = (name: string) => {
     const m = declaration.members.find((x) => x.name === name);
     return add<MemberNode>({ id: `member:${name}`, kind: "member", name, dir: m?.dir ?? "", memberKind: m?.kind ?? "" });