@intentius/chant 0.91.0 → 0.94.0

package/src/workspace/decide.ts

@@ -66,6 +66,10 @@ import { policyAtBase, resolveBase } from "./trust/provenance";
 import { emptyPolicy, type TrustPolicy } from "./trust/policy";
 import { AGENT_ROLE } from "./records-cli";
 import type { SourceVia } from "./source-block";
+import type { RecordSource } from "./record-source";
+import { currentStewardTurn } from "../op/steward-turn";
+import { RefCASConflictError } from "../lifecycle/git";
+import { readLedgerAnswers, refreshLedger, withLedgerAnswers, writeLedgerAnswer, type LedgerAnswers } from "./answers-ledger";
 
 /** The version of the write documents `points ask` and `points answer` print. */
 export const POINTS_WRITE_CONTRACT_VERSION = 1;
@@ -93,6 +97,8 @@ export const POINTS_WRITE_ERROR_CODES = [
   "record-not-found",
   "record-closed",
   "record-id-taken",
+  /** The answer was given during a steward's turn (#2749): a steward never answers a question, its own or another's. */
+  "answer-in-steward-turn",
   ...RECORD_REASON_CODES,
 ] as const satisfies readonly ReasonCode[];
 export type PointsWriteErrorCode = (typeof POINTS_WRITE_ERROR_CODES)[number];
@@ -141,12 +147,47 @@ export interface QuestionView {
   answeredBy: string[];
   askedOn: string | null;
   answeredOn: string | null;
+  /**
+   * The steward whose turn asked the question (#2749), and the run it was in,
+   * or null when no steward asked it. The steward waits on the question and
+   * never answers it: a person does, through hud or `points answer`.
+   */
+  askedBy: { steward: string; run: string | null } | null;
+  /**
+   * Where the record is held when it is on the lifecycle ledger rather than
+   * in the working tree (#2786): `chant/lifecycle:<path>`, which `git show`
+   * reads. A question asked in a steward's turn is held there, since a
+   * steward never writes the checkout. null for a record in the tree; `path`
+   * is where the record reads as being either way.
+   */
+  ledger: string | null;
   valid: boolean;
   warnings: RecordWarning[];
 }
 
-/** One answer record as a {@link QuestionView}, or null when its front matter can't be read. `point` is its point as declared now, when there is one. */
-export function questionView(entry: RecordEntry, point: Point | undefined): QuestionView | null {
+/** The harness a steward's question names in its source block (#2749). */
+export const STEWARD_HARNESS = "chant-steward";
+
+/** The steward that asked, from a record's source block, or null. */
+export function askedByOf(data: Record<string, unknown>): QuestionView["askedBy"] {
+  const source = data.source;
+  if (source === null || typeof source !== "object" || Array.isArray(source)) return null;
+  const s = source as Record<string, unknown>;
+  if (s.harness !== STEWARD_HARNESS) return null;
+  const client = s.client as Record<string, unknown> | undefined;
+  const steward = client && typeof client.name === "string" ? client.name : null;
+  if (steward === null) return null;
+  const session = s.session as Record<string, unknown> | string | undefined;
+  const run = typeof session === "string" ? session : session && typeof session === "object" && typeof session.id === "string" ? session.id : null;
+  return { steward, run };
+}
+
+/**
+ * One answer record as a {@link QuestionView}, or null when its front matter
+ * can't be read. `point` is its point as declared now, when there is one, and
+ * `ledger` where the record is held when it is on the lifecycle ledger.
+ */
+export function questionView(entry: RecordEntry, point: Point | undefined, ledger: string | null = null): QuestionView | null {
   const d = entry.data;
   if (d === null || entry.id === null) return null;
   const str = (v: unknown): string | null => (typeof v === "string" ? v : null);
@@ -187,6 +228,8 @@ export function questionView(entry: RecordEntry, point: Point | undefined): Ques
     answeredBy: Array.isArray(d.answered_by) ? d.answered_by.filter((b): b is string => typeof b === "string") : [],
     askedOn: str(d.asked_on),
     answeredOn: str(d.answered_on),
+    askedBy: askedByOf(d),
+    ledger,
     valid: entry.valid,
     warnings: entry.warnings,
   };
@@ -276,6 +319,21 @@ export interface AskPointOptions {
   via?: SourceVia;
   /** The client that asked, for its source block. */
   client?: { name: string; version?: string };
+  /**
+   * The steward whose turn asks (#2749), and its run. Recorded in the source
+   * block (harness `chant-steward`, the steward as the client, the run as the
+   * session), so the question says who is waiting on it and `points answer`
+   * never counts the steward toward its quorum. Takes the place of `client`.
+   */
+  steward?: { name: string; run?: string };
+  /**
+   * Where a new record goes: the answer kind's directory in the working tree,
+   * or the lifecycle ledger (#2786). Defaults to the ledger in a steward's
+   * turn (`steward` given, or this process a steward's turn), since a steward
+   * never writes the checkout, and to the tree otherwise. A question already
+   * held on the ledger is rewritten there whatever this says.
+   */
+  store?: "tree" | "ledger";
   /** The date written as asked_on, and answered_on for a table's answer, YYYY-MM-DD. Defaults to today, in UTC. */
   on?: string;
   dryRun?: boolean;
@@ -319,9 +377,34 @@ function checkInputs(name: string, point: Point, inputs: unknown): Record<string
   return inputs as Record<string, unknown>;
 }
 
-/** Write `data` as the record at `path`, after reading it back with every other record. */
-async function write(o: Opened, before: RecordEntry[], path: string, text: string, create: boolean, dryRun: boolean): Promise<RecordWarning[]> {
-  const warnings = await validateWrite(o, before, path, text);
+/** Where a write goes: the working tree, or the lifecycle ledger (#2786). */
+interface WriteTarget {
+  /** The records as read: the tree with the ledger's answers laid over it. */
+  source: RecordSource;
+  ledger: LedgerAnswers;
+  /** Write to the ledger rather than the tree. */
+  onLedger: boolean;
+  message: string;
+}
+
+/**
+ * Write `text` as the record at `path`, after reading it back with every
+ * other record: into the working tree, or onto the ledger. Returns the
+ * record's warnings and, for a ledger write, where it went.
+ */
+async function write(o: Opened, before: RecordEntry[], path: string, text: string, create: boolean, dryRun: boolean, target: WriteTarget): Promise<{ warnings: RecordWarning[]; ledger: string | null }> {
+  const warnings = await validateWrite(o, before, path, text, target.source);
+  const held = target.ledger.byPath.get(path);
+  if (target.onLedger) {
+    if (dryRun) return { warnings, ledger: held?.ledger ?? null };
+    try {
+      const { ledger } = await writeLedgerAnswer(target.ledger, path, text, target.message, held?.sha ?? null);
+      return { warnings, ledger };
+    } catch (err) {
+      if (err instanceof RefCASConflictError) throw new PointsWriteError("record-id-taken", `${path} was written on chant/lifecycle by another ask or answer at the same time: ask again to read it`);
+      throw err;
+    }
+  }
   if (!dryRun) {
     try {
       writeFileSync(abs(o, path), text, create ? { flag: "wx" } : undefined);
@@ -330,7 +413,14 @@ async function write(o: Opened, before: RecordEntry[], path: string, text: strin
       throw err;
     }
   }
-  return warnings;
+  return { warnings, ledger: null };
+}
+
+/** The kind's answers on the ledger, and its records read with them laid over the tree. */
+async function readWithLedger(o: Opened): Promise<{ ledger: LedgerAnswers; source: RecordSource; before: RecordEntry[] }> {
+  const ledger = await readLedgerAnswers({ file: o.loaded.file, name: o.loaded.kind.name, dirRel: o.dirRel });
+  const source = withLedgerAnswers(o.source, ledger);
+  return { ledger, source, before: await readAll(o, source) };
 }
 
 function recordData(o: Opened, fields: Record<string, unknown>): Record<string, unknown> {
@@ -355,15 +445,21 @@ function resultFields(result: ChainResult): Record<string, unknown> {
  */
 export async function askPoint(opts: AskPointOptions): Promise<PointsWriteDocument> {
   try {
+    // A steward's turn (#2749): named by the caller, or this process's, as when an Op shells out to `points ask`.
+    const turn = opts.steward ? undefined : currentStewardTurn();
+    const steward = opts.steward ?? (turn ? { name: turn.steward, ...(turn.run ? { run: turn.run } : {}) } : undefined);
+    const toLedger = opts.store !== undefined ? opts.store === "ledger" : steward !== undefined;
     const kinds = await answerKindFiles(opts.cwd, opts.kind);
     const { o, point } = await findPoint(kinds, opts.point, opts.cwd);
     const inputs = checkInputs(opts.point, point, opts.inputs);
     const version = pointVersion(point);
     const hash = inputsHash(opts.point, version, inputs);
     const id = answerId(opts.point, hash);
-    const before = await readAll(o, o.source);
+    if (toLedger && !opts.dryRun) await refreshLedger(o.loaded.file);
+    const { ledger, source: read, before } = await readWithLedger(o);
     const existing = before.find((e) => e.id === id);
-    const done = (entry: RecordEntry, extra: { reused: boolean; written: boolean; text?: string }): PointsWriteDocument => ({
+    const heldAt = (entry: RecordEntry): string | null => ledger.byPath.get(entry.path)?.ledger ?? null;
+    const done = (entry: RecordEntry, extra: { reused: boolean; written: boolean; text?: string; ledger?: string | null }): PointsWriteDocument => ({
       $schema: POINTS_WRITE_SCHEMA_ID,
       contract: POINTS_WRITE_CONTRACT_VERSION,
       verb: "ask",
@@ -373,7 +469,7 @@ export async function askPoint(opts: AskPointOptions): Promise<PointsWriteDocume
       reused: extra.reused,
       written: extra.written,
       dryRun: !!opts.dryRun,
-      question: questionView(entry, point)!,
+      question: questionView(entry, point, extra.ledger !== undefined ? extra.ledger : heldAt(entry))!,
       ...(extra.text !== undefined ? { text: extra.text } : {}),
     });
     if (existing && existing.data !== null && (existing.state === "answered" || existing.state === "proposed")) return done(existing, { reused: true, written: false });
@@ -393,7 +489,14 @@ export async function askPoint(opts: AskPointOptions): Promise<PointsWriteDocume
     const answer = result.status === "escalated" ? undefined : result.answer;
     const title = titleFor(point, opts.subject, state, answer);
     const modelId = result.status === "proposed" ? result.decider.model : undefined;
-    const source = { via: opts.via ?? "cli", ...(opts.client ? { client: opts.client } : {}), ...(modelId ? { model: modelId } : {}) };
+    const client = steward ? { name: steward.name } : opts.client;
+    const source = {
+      via: opts.via ?? "cli",
+      ...(steward ? { harness: STEWARD_HARNESS } : {}),
+      ...(client ? { client } : {}),
+      ...(modelId ? { model: modelId } : {}),
+      ...(steward?.run ? { session: { id: steward.run } } : {}),
+    };
     const data = recordData(o, {
       id,
       title,
@@ -411,16 +514,19 @@ export async function askPoint(opts: AskPointOptions): Promise<PointsWriteDocume
     });
     const path = existing ? existing.path : o.dirRel === "." ? `${id}.md` : `${o.dirRel}/${id}.md`;
     const text = renderRecord(data, body(point, title));
-    const warnings = await write(o, before, path, text, !existing, !!opts.dryRun);
-    const entry: RecordEntry = { ...(existing ?? emptyEntry(path)), id, path, state, data, valid: true, reasons: [], warnings };
-    return done(entry, { reused: false, written: !opts.dryRun, ...(opts.dryRun ? { text } : {}) });
+    // A steward's question goes on the ledger, and one already held there stays there (#2786).
+    const onLedger = toLedger || ledger.byPath.has(path);
+    const message = `Decision point ${opts.point}: ${state}${opts.subject ? ` (${opts.subject})` : ""}${steward ? `, asked by ${steward.name}` : ""}`;
+    const wrote = await write(o, before, path, text, !existing, !!opts.dryRun, { source: read, ledger, onLedger, message });
+    const entry: RecordEntry = { ...(existing ?? emptyEntry(path)), id, path, state, data, valid: true, reasons: [], warnings: wrote.warnings };
+    return done(entry, { reused: false, written: !opts.dryRun, ledger: wrote.ledger, ...(opts.dryRun ? { text } : {}) });
   } catch (err) {
     return failure("ask", err);
   }
 }
 
 function emptyEntry(path: string): RecordEntry {
-  return { id: null, path, state: null, valid: true, reasons: [], supersededBy: null, data: null, assets: [], warnings: [], digest: "" };
+  return { id: null, path, state: null, valid: true, reasons: [], supersededBy: null, remediatedBy: [], data: null, assets: [], warnings: [], digest: "" };
 }
 
 // ── points answer ────────────────────────────────────────────────────────────
@@ -453,9 +559,16 @@ function policyFor(root: string): TrustPolicy {
  * leaving out anyone holding the agent role in the trust policy at base, and,
  * when the quorum names roles, anyone holding none of them.
  */
-export function tallyQuorum(by: string[], quorum: { count: number; roles?: string[] }, policy: TrustPolicy): { counted: string[]; left: { name: string; why: string }[]; met: boolean } {
+export function tallyQuorum(
+  by: string[],
+  quorum: { count: number; roles?: string[] },
+  policy: TrustPolicy,
+  /** The steward that asked the question (#2749): it never counts toward the answer. */
+  steward?: string,
+): { counted: string[]; left: { name: string; why: string }[]; met: boolean } {
   const holders = (role: string) => new Set((policy.roles[role] ?? []).map(normalisePrincipal));
   const agents = holders(AGENT_ROLE);
+  const asker = steward !== undefined ? normalisePrincipal(steward) : undefined;
   const counted: string[] = [];
   const seen = new Set<string>();
   const left: { name: string; why: string }[] = [];
@@ -463,6 +576,10 @@ export function tallyQuorum(by: string[], quorum: { count: number; roles?: strin
     const p = normalisePrincipal(name);
     if (p === "" || seen.has(p)) continue;
     seen.add(p);
+    if (asker !== undefined && p === asker) {
+      left.push({ name, why: "is the steward that asked" });
+      continue;
+    }
     if (agents.has(p)) {
       left.push({ name, why: "holds the agent role" });
       continue;
@@ -484,20 +601,34 @@ export function tallyQuorum(by: string[], quorum: { count: number; roles?: strin
  */
 export async function answerPoint(opts: AnswerPointOptions): Promise<PointsWriteDocument> {
   try {
+    // A steward waits on a question and never answers one (#2749), as it never
+    // clears a gate: the answer has to come from a person, through hud or a
+    // shell, not from the steward's own turn or a process it started.
+    const turn = currentStewardTurn();
+    if (turn) {
+      throw new PointsWriteError(
+        "answer-in-steward-turn",
+        `this is the steward ${turn.steward}'s turn, and a steward never answers a decision point: a person answers ${opts.id} through hud or \`chant workspace points answer\` at a shell`,
+      );
+    }
     const kinds = await answerKindFiles(opts.cwd, opts.kind);
     if (kinds.length === 0) throw new PointsWriteError("points-undeclared", "no record kind with an answers block is declared: name one with --kind, or declare one in chant.workspace.json");
-    let found: { opened: OpenedPoints; before: RecordEntry[]; target: RecordEntry & { data: Record<string, unknown> } } | undefined;
+    let found:
+      | { opened: OpenedPoints; before: RecordEntry[]; read: Awaited<ReturnType<typeof readWithLedger>>; target: RecordEntry & { data: Record<string, unknown> } }
+      | undefined;
     for (const k of kinds) {
       const opened = await openAnswers(k, opts.cwd);
-      const before = await readAll(opened.o, opened.o.source);
-      const target = before.find((e) => e.id === opts.id);
+      // A question a steward asked is on the ledger (#2786), and people's answer goes back there.
+      const read = await readWithLedger(opened.o);
+      const target = read.before.find((e) => e.id === opts.id);
       if (target && target.data !== null) {
-        found = { opened, before, target: target as RecordEntry & { data: Record<string, unknown> } };
+        found = { opened, before: read.before, read, target: target as RecordEntry & { data: Record<string, unknown> } };
         break;
       }
     }
     if (!found) throw new PointsWriteError("record-not-found", `no answer record has id ${opts.id}`);
     const { opened, before, target } = found;
+    const ledger = found.read.ledger;
     const { o } = opened;
     const d = target.data;
     if (target.state === "answered") throw new PointsWriteError("record-closed", `${opts.id} is answered, and an answer never changes: ask again with other inputs, or change the point, which asks the question anew`);
@@ -511,7 +642,7 @@ export async function answerPoint(opts: AnswerPointOptions): Promise<PointsWrite
       throw new PointsWriteError("answer-not-candidate", `${opts.id} takes one of ${allowed.map((c) => JSON.stringify(c)).join(", ")}, not ${JSON.stringify(opts.answer)}`);
     }
     const quorum = quorumOf(point);
-    const tally = tallyQuorum(opts.by, quorum, policyFor(o.root));
+    const tally = tallyQuorum(opts.by, quorum, policyFor(o.root), askedByOf(d)?.steward);
     if (!tally.met) {
       const got = tally.counted.length;
       const left = tally.left.length ? `; not counted: ${tally.left.map((l) => `${l.name}, who ${l.why}`).join("; ")}` : "";
@@ -555,8 +686,10 @@ export async function answerPoint(opts: AnswerPointOptions): Promise<PointsWrite
     fields.title = titleFor(point, subject, "answered", value);
     const data = recordData(o, fields);
     const text = renderRecord(data, body(point, String(fields.title)));
-    const warnings = await write(o, before, target.path, text, false, !!opts.dryRun);
-    const entry: RecordEntry = { ...target, state: "answered", data, valid: true, reasons: [], warnings };
+    const onLedger = ledger.byPath.has(target.path);
+    const message = `Decision point ${name}: answered ${show(value, type)} by ${tally.counted.join(", ")}`;
+    const wrote = await write(o, before, target.path, text, false, !!opts.dryRun, { source: found.read.source, ledger, onLedger, message });
+    const entry: RecordEntry = { ...target, state: "answered", data, valid: true, reasons: [], warnings: wrote.warnings };
     return {
       $schema: POINTS_WRITE_SCHEMA_ID,
       contract: POINTS_WRITE_CONTRACT_VERSION,
@@ -567,7 +700,7 @@ export async function answerPoint(opts: AnswerPointOptions): Promise<PointsWrite
       reused: false,
       written: !opts.dryRun,
       dryRun: !!opts.dryRun,
-      question: questionView(entry, point)!,
+      question: questionView(entry, point, onLedger ? (wrote.ledger ?? ledger.byPath.get(target.path)?.ledger ?? null) : null)!,
       ...(opts.dryRun ? { text } : {}),
     };
   } catch (err) {

package/src/workspace/decision-points.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://intentius.io/chant/schemas/workspace/decision-points/v1/decision-points.schema.json",
   "title": "Decision points",
-  "description": "A workspace's decision points (ws-058, #2738): the recurring questions it asks of its own graph, declared as data in a JSON file that an answer record kind names in `answers.points`. Each point is a typed question (`noul`, `choice` with 2 to 255 options, or `score` with 2 to 10 ordered levels, the question types of the POST /v1/systemone wire format, #2491), the inputs it reads, each named as a read-contract output, and an ordered chain of deciders: `table` rows, `model` deciders with a backend, a pinned model id and a threshold, and a `quorum` of people, always last. Taken from chud's decision-points.schema.json; `boolean` is read as `noul`. What JSON Schema cannot say is checked in code (`points.ts`): an input's output is one the read contract has, a table row tests declared inputs and answers a candidate, a field belongs to its decider's kind, a model id is pinned rather than an alias, and the chain ends in its one quorum. Unknown fields are refused, except fields whose names start with x-.",
+  "description": "A workspace's decision points (ws-058, #2738): the recurring questions it asks of its own graph, declared as data in a JSON file that an answer record kind names in `answers.points`. Each point is a typed question (`noul`, `choice` with 2 to 255 options, or `score` with 2 to 10 ordered levels, the question types of the POST /v1/systemone wire format, #2491), the inputs it reads, each named as a read-contract output, and an ordered chain of deciders: `table` rows, `model` deciders with a backend, a pinned model id and a threshold, and a `quorum` of people, always last. What JSON Schema cannot say is checked in code (`points.ts`): an input's output is one the read contract has, a table row tests declared inputs and answers a candidate, a field belongs to its decider's kind, a model id is pinned rather than an alias, and the chain ends in its one quorum. Unknown fields are refused, except fields whose names start with x-.",
   "type": "object",
   "required": ["points"],
   "properties": {
@@ -44,7 +44,7 @@
       "type": "object",
       "required": ["type", "instructions", "criteria"],
       "properties": {
-        "type": { "enum": ["noul", "boolean", "choice", "score"], "description": "boolean is chud's name for noul, read as noul." },
+        "type": { "enum": ["noul", "choice", "score"] },
         "instructions": { "$ref": "#/$defs/text" },
         "criteria": {
           "description": "The candidates. noul: {true, false} descriptions. choice: option to description, 2 to 255 options. score: 2 to 10 ordered levels.",
@@ -54,7 +54,7 @@
       "additionalProperties": false,
       "allOf": [
         {
-          "if": { "properties": { "type": { "enum": ["noul", "boolean"] } } },
+          "if": { "properties": { "type": { "const": "noul" } } },
           "then": {
             "properties": {
               "criteria": {

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,8 +402,13 @@
     },
     "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). Its intent names the decision record that says what the box is for (#2850): chant workspace status --json reports the record's state and answer, and chant workspace check fails when no decision record has the id (WSP126) and warns when the record constrains no member or path of this workspace (WSP127, #2857). Added in schema 1 by chant 0.91.0, so a declaration that uses it sets minReader to 0.91.0 or newer.",
       "properties": {
+        "intent": {
+          "type": "string",
+          "minLength": 1,
+          "description": "The id of the decision record that says what the box is for (#2850), a record of a declared kind named decision. A new box starts as a question: the record is proposed with a null choice until the person who answers it decides it. The record constrains a member or path of this workspace, with member:<a member's name> or a path: entry at, above or inside a member's directory. It need not be this member: the intent can constrain the app the box runs when that app is another member (#2857). When it constrains this member, chant workspace graph --intent shows it for the box's files. Added by chant 0.94.0, so a declaration that uses it sets minReader to 0.94.0 or newer."
+        },
         "capabilities": {
           "type": "array",
           "description": "Each capability the box reaches outside itself, named once. None when omitted.",
@@ -493,6 +534,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 +754,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");
+  });
+});