@intentius/chant 0.90.0 → 0.93.0

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`.
@@ -145,6 +190,54 @@ export interface RecordKindDeclaration {
   pointer: string;
 }
 
+/**
+ * A capability a box reaches through a broker (#2726): inference, Fountain,
+ * a third-party API. The broker is runtime (a lobby, a door, a studio) and
+ * holds the credential; the declaration names it and the scope it enforces.
+ */
+export interface BoxCapability {
+  name: string;
+  /** What brokers it, such as `lobby`, or null when the entry names no broker (WSP122). */
+  broker: string | null;
+  /** What of the box's own the broker lets it reach, such as `agent`, `vault`, `conversations`, `sandboxes`. */
+  scope: string[];
+  /** The entry's JSON Pointer in the file, for messages. */
+  pointer: string;
+}
+
+/** A member that is a box, or a box's declarations (#2726). */
+export interface BoxDeclaration {
+  capabilities: BoxCapability[];
+  /** The host and slot of the box's isolation, or null when the block declares none (#2727). The values are derived in `boxes.ts`. */
+  isolation: BoxIsolationDeclaration | null;
+  /** The block's JSON Pointer in the file, for messages. */
+  pointer: string;
+}
+
+/** What a box declares about its isolation (#2727): its identity on a host, and the names of what it needs kept apart. */
+export interface BoxIsolationDeclaration {
+  host: string;
+  slot: number;
+  /** Port name to offset in the box's block, in file order. */
+  ports: Record<string, number>;
+  /** State name to a path relative to the box's state directory, in file order. */
+  state: Record<string, string>;
+  cookies: string[];
+}
+
+/** A host boxes run on (#2727): one machine under one hostname. */
+export interface Host {
+  name: string;
+  ports: { from: number; to: number; perBox: number };
+  /** As written, or null for the default ({@link DEFAULT_STATE_ROOT}). */
+  stateRoot: string | null;
+  /** The entry's JSON Pointer in the file, for messages. */
+  pointer: string;
+}
+
+/** Where boxes keep state when their host names no stateRoot (#2727). */
+export const DEFAULT_STATE_ROOT = "${XDG_STATE_HOME}/chant/boxes";
+
 export interface Member {
   type: "member";
   name: string;
@@ -160,6 +253,10 @@ 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;
   because: string | null;
   suppress: Suppression[];
@@ -202,6 +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;
 }
@@ -414,6 +517,8 @@ 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",
       name: e.name as string,
@@ -424,6 +529,8 @@ 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,
       suppress,
@@ -508,6 +615,29 @@ export function parseDeclaration(text: string, file: string, reader: string = re
     byName.set(r.name, r);
   }
 
+  // A box names each capability once (#2726): a broker reads its scope by name.
+  for (const m of members) {
+    const seen = new Map<string, BoxCapability>();
+    for (const c of m.box?.capabilities ?? []) {
+      const first = seen.get(c.name);
+      if (first) throw new WorkspaceReadError("declaration-invalid", `member ${m.name}'s box lists the capability ${c.name} twice; the first is at ${first.pointer}`, at(`${c.pointer}/name`));
+      seen.set(c.name, c);
+    }
+  }
+
+  // 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) => ({
     package: p.package ?? null,
     version: p.version ?? null,
@@ -526,10 +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) => ({
@@ -541,6 +680,99 @@ 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;
+  const b = raw as {
+    capabilities?: { name: string; broker?: string; scope?: string[] }[];
+    host?: string;
+    slot?: number;
+    ports?: Record<string, number>;
+    state?: Record<string, string>;
+    cookies?: string[];
+  };
+  return {
+    capabilities: (b.capabilities ?? []).map((c, i) => ({ name: c.name, broker: c.broker ?? null, scope: [...(c.scope ?? [])], pointer: `${pointer}/capabilities/${i}` })),
+    // The schema requires host and slot together, and host for ports, state and cookies.
+    isolation:
+      b.host === undefined
+        ? null
+        : { host: b.host, slot: b.slot!, ports: { ...(b.ports ?? {}) }, state: { ...(b.state ?? {}) }, cookies: [...(b.cookies ?? [])] },
+    pointer,
+  };
+}
+
+/**
+ * The hosts, already validated, with the rules the schema can't say (#2727):
+ * host names are unique, a box's host is declared, its slot's block fits the
+ * host's range and its offsets fit the block. What two boxes resolve to is
+ * `chant workspace check`'s question (WSP123), not a read error.
+ */
+function hostsOf(obj: Record<string, unknown>, members: Member[], at: (pointer: string, key?: boolean) => ErrorLocation): Host[] {
+  const hosts = ((obj.hosts as Record<string, unknown>[] | undefined) ?? []).map((h, i): Host => ({
+    name: h.name as string,
+    ports: { ...(h.ports as Host["ports"]) },
+    stateRoot: (h.stateRoot as string | undefined) ?? null,
+    pointer: `/hosts/${i}`,
+  }));
+  const invalid = (message: string, pointer: string) => new WorkspaceReadError("declaration-invalid", message, at(pointer));
+  const byName = new Map<string, Host>();
+  for (const h of hosts) {
+    const first = byName.get(h.name);
+    if (first) throw invalid(`the host name ${JSON.stringify(h.name)} is already used by the host at ${first.pointer}`, `${h.pointer}/name`);
+    byName.set(h.name, h);
+    if (h.ports.from > h.ports.to) throw invalid(`host ${h.name}'s port range starts at ${h.ports.from}, after its end ${h.ports.to}`, `${h.pointer}/ports`);
+  }
+  for (const m of members) {
+    const iso = m.box?.isolation;
+    if (!iso) continue;
+    const box = m.box!.pointer;
+    const host = byName.get(iso.host);
+    if (!host) {
+      const known = hosts.map((h) => h.name).join(", ") || "none are declared";
+      throw invalid(`member ${m.name}'s box names the host ${JSON.stringify(iso.host)}, which hosts does not declare; declared hosts: ${known}`, `${box}/host`);
+    }
+    const { from, to, perBox } = host.ports;
+    const last = from + (iso.slot + 1) * perBox - 1;
+    if (last > to) {
+      const slots = Math.floor((to - from + 1) / perBox);
+      throw invalid(
+        `member ${m.name}'s box has slot ${iso.slot} on host ${host.name}, which needs ports ${from + iso.slot * perBox} to ${last}, past the end of the host's range (${to}); the range holds ${slots} slot${slots === 1 ? "" : "s"}`,
+        `${box}/slot`,
+      );
+    }
+    for (const [port, offset] of Object.entries(iso.ports)) {
+      if (offset >= perBox) {
+        throw invalid(`member ${m.name}'s box gives port ${port} offset ${offset}, and host ${host.name} gives each box ${perBox} port${perBox === 1 ? "" : "s"} (offsets 0 to ${perBox - 1})`, `${box}/ports/${pointerToken(port)}`);
+      }
+    }
+  }
+  return hosts;
+}
+
 /**
  * Every record kind the declaration names (#2680), in the order readers use
  * them: the workspace's own first, then each member's, members in file order
@@ -550,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

@@ -13,7 +13,7 @@
  * kind file.
  */
 
-import { join } from "node:path";
+import { dirname, join, relative, resolve, sep } from "node:path";
 import { declaredRecordKinds, type Declaration, type RecordKindDeclaration } from "./declaration";
 import type { ReasonCode } from "./reason-codes";
 import type { WorkspaceTree } from "./tree";
@@ -30,6 +30,31 @@ export interface DeclaredKind {
   kind: string | null;
   /** Why it can't be loaded, or null. */
   reason: { code: DeclaredKindReasonCode; message: string } | null;
+  /**
+   * For an answer kind (ws-058, #2738): its points file from the workspace
+   * root, and what is wrong with it, empty when nothing is. Absent for any
+   * 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`. */
@@ -47,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 [];
@@ -65,7 +90,13 @@ export async function loadDeclaredKinds(
     }
     try {
       const loaded = await records.loadRecordKind(file);
-      out.push({ declared: d, file, kind: loaded.kind.name, reason: null });
+      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;
       // loadRecordKind names the file as it was given, here an absolute path: name it from the workspace root instead.
@@ -74,3 +105,40 @@ 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("/");
+  if (file.startsWith("../")) return { file, problems: [{ field: null, message: "is outside the workspace" }] };
+  if (tree.stat(file) !== "file") return { file, problems: [{ field: null, message: `does not exist${tree.label}` }] };
+  const { parsePoints, PointsError } = await import("./points");
+  try {
+    parsePoints(tree.read(file), file);
+    return { file, problems: [] };
+  } catch (err) {
+    if (err instanceof PointsError) return { file, problems: err.problems };
+    throw err;
+  }
+}

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": {
@@ -940,7 +944,12 @@
                   "work-implements-undecided",
                   "work-done-unpinned",
                   "work-closed-without-date",
-                  "work-done-gap-open"
+                  "work-done-gap-open",
+                  "work-acceptance-unmet",
+                  "work-acceptance-self-verified",
+                  "answer-points-unreadable",
+                  "answer-point-unknown",
+                  "answer-point-changed"
                 ]
               },
               "message": {

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 ?? "" });

package/src/workspace/lineage-check.ts

@@ -16,6 +16,9 @@
  *
  * `chant workspace upgrade` runs the same checks in its staging worktree
  * before it reaches its gate.
+ *
+ * `--changes <base>..<head>` runs the forward coverage check instead
+ * (`changes-cli.ts`, #2773), which prints a document of its own.
  */
 
 import { realpathSync } from "node:fs";
@@ -84,7 +87,8 @@ export function findingKey(f: CheckFinding): string {
   return `${f.code}\0${f.scope ?? ""}\0${f.path ?? ""}`;
 }
 
-const USAGE = "chant workspace check [--at <rev>] [--json] [--format stylish|json|sarif] [--generated] [--kind <kind file>]";
+const USAGE =
+  "chant workspace check [--at <rev>] [--json] [--format stylish|json|sarif] [--generated] [--kind <kind file>]\n       chant workspace check --changes <base>..<head> [--work <id>] [--severity off|warn|fail] [--kind <kind file>...] [--json]";
 const FORMATS = ["stylish", "json", "sarif"] as const;
 
 /** A lock finding as a lint diagnostic, for `--format json` and `--format sarif`. */
@@ -223,6 +227,17 @@ export async function runWorkspaceCheck(ctx: CommandContext): Promise<number> {
     console.error(formatError({ message: `chant workspace check takes no argument (got ${ctx.args.extraPositional})`, hint: USAGE }));
     return 1;
   }
+  // The forward coverage check (#2773) is its own document.
+  if (ctx.args.changes !== undefined) {
+    if (ctx.args.at !== undefined) {
+      console.error(formatError({ message: "--changes reads the records at the range's head, so it takes no --at", hint: USAGE }));
+      return 1;
+    }
+    const { handToRootChant } = await import("./which-chant");
+    const handed = await handToRootChant(root, undefined);
+    if (handed !== undefined) return handed;
+    return (await import("./changes-cli")).runWorkspaceChanges(ctx, root);
+  }
   const format = (ctx.args.format || "stylish") as (typeof FORMATS)[number];
   if (!FORMATS.includes(format)) {
     console.error(formatError({ message: `--format ${format} is not a check format; use stylish, json or sarif`, hint: USAGE }));

package/src/workspace/lineage-upgrade-cli.ts

@@ -71,7 +71,7 @@ export async function upgradeCommand(opts: UpgradeCommandOptions): Promise<Upgra
         }),
       );
     }
-    if (!staged.changed) {
+    if (!staged.changed && staged.checksOk) {
       if (!opts.json) console.error(formatSuccess(`scope "${staged.scope}" is already at ${staged.to ?? "its source"}; nothing to upgrade`));
       return report("up-to-date", 0);
     }