@intentius/chant 0.95.0 → 0.96.0

package/src/op/run-live.ts

@@ -0,0 +1,305 @@
+/**
+ * The in-flight run record: what an Op run is doing while it runs.
+ *
+ * The run ledger (`../lifecycle/run-ledger.ts`) gets one record when a run
+ * settles, so until then a reader sees the previous run. A run that writes to
+ * the ledger (the executor's `ledger` option) also keeps two files beside the
+ * checkout's git directory, outside the working tree and the lifecycle branch:
+ *
+ * - `<git-common-dir>/chant/runs/<key>.json`, the run's id, steward, work
+ *   item, current phase and step, and the phases it has finished with their
+ *   durations, rewritten whole as the run moves;
+ * - `<git-common-dir>/chant/runs/<key>.activity.jsonl`, lines a step's
+ *   process appends while it works, one per line.
+ *
+ * `<key>` folds the member's ledger prefix, the env and the Op's name into one
+ * file name. Both files are removed once the run's ledger record is written.
+ * A run that died without removing them is recognised by its process: a record
+ * whose host is this one and whose pid is gone is not in flight.
+ *
+ * A step's process finds the activity file in `CHANT_RUN_ACTIVITY`, which the
+ * `shellCmd` activity sets for a run that keeps one, and appends a line to it:
+ * a JSON object `{"at": "<ISO-8601>", "text": "..."}`, or plain text. An
+ * in-process activity calls {@link reportRunActivity}.
+ */
+
+import { AsyncLocalStorage } from "node:async_hooks";
+import { execFile } from "node:child_process";
+import { appendFileSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { hostname } from "node:os";
+import { isAbsolute, join, resolve } from "node:path";
+import { promisify } from "node:util";
+import { resolveMemberLedger } from "../lifecycle/member-ledger";
+
+const execFileAsync = promisify(execFile);
+
+/** The environment variable naming the activity file, for a step's process. */
+export const RUN_ACTIVITY_ENV = "CHANT_RUN_ACTIVITY";
+/** The environment variable naming the run, for a step's process. */
+export const RUN_ID_ENV = "CHANT_RUN_ID";
+
+/** How many activity lines a reader gets by default: the newest ones. */
+export const IN_FLIGHT_ACTIVITY_LINES = 20;
+
+/** A phase the run has finished. */
+export interface InFlightPhase {
+  name: string;
+  status: "ok" | "fail" | "skipped";
+  durationMs: number;
+}
+
+/** The in-flight record as the run writes it. */
+export interface InFlightRecord {
+  version: 1;
+  id: string;
+  op: string;
+  env: string;
+  steward: string | null;
+  /** The work item the run's lease holds, once it is claimed. */
+  item: string | null;
+  started: string;
+  /** When the record was last rewritten. */
+  updated: string;
+  host: string;
+  pid: number;
+  phase: { name: string; started: string } | null;
+  /** The newest step still running: its id when it has one, else its activity. */
+  step: { name: string; fn: string; started: string } | null;
+  phases: InFlightPhase[];
+}
+
+/** One activity line as a reader gets it. `seq` counts from 1 over the run. */
+export interface InFlightActivityLine {
+  seq: number;
+  at: string | null;
+  text: string;
+}
+
+/** The in-flight record with its newest activity lines. */
+export interface InFlightRun extends InFlightRecord {
+  activity: { total: number; lines: InFlightActivityLine[] };
+}
+
+/** The file name a run's record is kept under, the prefix and env folded in. */
+function keyOf(prefix: string, env: string, op: string): string {
+  return `${prefix}${env}/${op}`.replace(/[\/\\]/g, "__").replace(/[^A-Za-z0-9._@-]/g, "_");
+}
+
+/** The checkout's shared git directory (the same for every worktree), or null outside a checkout. */
+async function gitCommonDir(cwd: string): Promise<string | null> {
+  try {
+    const { stdout } = await execFileAsync("git", ["rev-parse", "--git-common-dir"], { cwd });
+    const dir = stdout.trim();
+    return dir === "" ? null : isAbsolute(dir) ? dir : resolve(cwd, dir);
+  } catch {
+    return null;
+  }
+}
+
+/** Where the run of `op` in `env` for the project at `cwd` keeps its files, or null outside a checkout. */
+export async function inFlightPaths(cwd: string, env: string, op: string): Promise<{ record: string; activity: string } | null> {
+  const common = await gitCommonDir(cwd);
+  if (!common) return null;
+  const { prefix } = await resolveMemberLedger(cwd);
+  const base = join(common, "chant", "runs", keyOf(prefix, env, op));
+  return { record: `${base}.json`, activity: `${base}.activity.jsonl` };
+}
+
+function processAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return (err as NodeJS.ErrnoException).code === "EPERM";
+  }
+}
+
+/** One activity line appended to `file`. Never throws: a report is not worth failing a step for. */
+function appendActivity(file: string, text: string): void {
+  const line = text.replace(/\s+/g, " ").trim();
+  if (line === "") return;
+  try {
+    appendFileSync(file, `${JSON.stringify({ at: new Date().toISOString(), text: line })}\n`);
+  } catch {
+    // The run's files are gone or unwritable: the line is dropped.
+  }
+}
+
+/**
+ * A running Op's in-flight record. The executor opens one per run that
+ * writes to the ledger and calls it as the run moves. Every write is
+ * best-effort: a record that can't be written leaves the run as it was.
+ */
+export class LiveRun {
+  private readonly rec: InFlightRecord;
+  private readonly running: InFlightRecord["step"][] = [];
+
+  private constructor(private readonly paths: { record: string; activity: string }, rec: InFlightRecord) {
+    this.rec = rec;
+  }
+
+  /** Open the record for a run starting now, or undefined when the project is not a checkout. */
+  static async open(opts: { cwd: string; env: string; op: string; id: string; started: string; steward?: string }): Promise<LiveRun | undefined> {
+    let paths: Awaited<ReturnType<typeof inFlightPaths>>;
+    try {
+      paths = await inFlightPaths(opts.cwd, opts.env, opts.op);
+    } catch {
+      return undefined;
+    }
+    if (!paths) return undefined;
+    const run = new LiveRun(paths, {
+      version: 1,
+      id: opts.id,
+      op: opts.op,
+      env: opts.env,
+      steward: opts.steward ?? null,
+      item: null,
+      started: opts.started,
+      updated: opts.started,
+      host: hostname(),
+      pid: process.pid,
+      phase: null,
+      step: null,
+      phases: [],
+    });
+    try {
+      mkdirSync(join(paths.record, ".."), { recursive: true });
+      writeFileSync(paths.activity, "");
+    } catch {
+      return undefined;
+    }
+    run.write();
+    return run;
+  }
+
+  /** The file a step's process appends activity lines to. */
+  get activityFile(): string {
+    return this.paths.activity;
+  }
+
+  get id(): string {
+    return this.rec.id;
+  }
+
+  phaseStarted(name: string): void {
+    this.rec.phase = { name, started: new Date().toISOString() };
+    this.write();
+  }
+
+  phaseEnded(name: string, status: InFlightPhase["status"], durationMs: number): void {
+    this.rec.phases.push({ name, status, durationMs });
+    if (this.rec.phase?.name === name) this.rec.phase = null;
+    this.write();
+  }
+
+  /** A step started; the returned function says it ended. */
+  stepStarted(fn: string, id?: string): () => void {
+    const step = { name: id ?? fn, fn, started: new Date().toISOString() };
+    this.running.push(step);
+    this.rec.step = step;
+    this.write();
+    return () => {
+      const at = this.running.indexOf(step);
+      if (at >= 0) this.running.splice(at, 1);
+      this.rec.step = this.running.at(-1) ?? null;
+      this.write();
+    };
+  }
+
+  item(item: string): void {
+    this.rec.item = item;
+    this.write();
+  }
+
+  report(text: string): void {
+    appendActivity(this.paths.activity, text);
+  }
+
+  /** The run has settled and its ledger record is written: remove its files. */
+  close(): void {
+    for (const file of [this.paths.record, this.paths.activity]) {
+      try {
+        rmSync(file, { force: true });
+      } catch {
+        // Left behind; a reader drops it once this process is gone.
+      }
+    }
+  }
+
+  private write(): void {
+    this.rec.updated = new Date().toISOString();
+    const tmp = `${this.paths.record}.${process.pid}.tmp`;
+    try {
+      writeFileSync(tmp, JSON.stringify(this.rec));
+      renameSync(tmp, this.paths.record);
+    } catch {
+      // Best-effort, as the module doc says.
+    }
+  }
+}
+
+const context = new AsyncLocalStorage<LiveRun>();
+
+/** Run `fn` as part of `live`'s run, so the steps under it find it. */
+export function withLiveRun<T>(live: LiveRun | undefined, fn: () => Promise<T>): Promise<T> {
+  return live ? context.run(live, fn) : fn();
+}
+
+/** The run the calling step is part of, when it keeps an in-flight record. */
+export function currentLiveRun(): LiveRun | undefined {
+  return context.getStore();
+}
+
+/** The variables a step's child process gets so it can report activity. Empty outside such a run. */
+export function liveRunEnv(): Record<string, string> {
+  const live = context.getStore();
+  return live ? { [RUN_ACTIVITY_ENV]: live.activityFile, [RUN_ID_ENV]: live.id } : {};
+}
+
+/** Append an activity line to the run the calling activity is part of. A no-op outside one. */
+export function reportRunActivity(text: string): void {
+  context.getStore()?.report(text);
+}
+
+function parseActivity(content: string, limit: number): InFlightRun["activity"] {
+  const raw = content.split("\n").filter((l) => l.trim() !== "");
+  const from = Math.max(0, raw.length - limit);
+  const lines = raw.slice(from).map((line, i): InFlightActivityLine => {
+    const seq = from + i + 1;
+    try {
+      const parsed = JSON.parse(line) as { at?: unknown; text?: unknown };
+      if (parsed && typeof parsed === "object" && typeof parsed.text === "string") {
+        return { seq, at: typeof parsed.at === "string" ? parsed.at : null, text: parsed.text };
+      }
+    } catch {
+      // Plain text.
+    }
+    return { seq, at: null, text: line.trim() };
+  });
+  return { total: raw.length, lines };
+}
+
+/**
+ * The run of `op` in `env` in flight for the project at `cwd`, with its
+ * newest `limit` activity lines, or null when none is. A record left by a
+ * process on this host that is gone is not in flight.
+ */
+export async function readInFlightRun(cwd: string, env: string, op: string, limit = IN_FLIGHT_ACTIVITY_LINES): Promise<InFlightRun | null> {
+  const paths = await inFlightPaths(cwd, env, op);
+  if (!paths || !existsSync(paths.record)) return null;
+  let rec: InFlightRecord;
+  try {
+    rec = JSON.parse(readFileSync(paths.record, "utf8")) as InFlightRecord;
+  } catch {
+    return null;
+  }
+  if (rec.version !== 1 || typeof rec.id !== "string" || typeof rec.started !== "string") return null;
+  if (rec.host === hostname() && typeof rec.pid === "number" && !processAlive(rec.pid)) return null;
+  let content = "";
+  try {
+    content = readFileSync(paths.activity, "utf8");
+  } catch {
+    // No activity yet.
+  }
+  return { ...rec, phases: Array.isArray(rec.phases) ? rec.phases : [], activity: parseActivity(content, limit) };
+}

package/src/op/runtime.ts

@@ -66,6 +66,8 @@ export interface OpRunPhaseRecord {
   name: string;
   /** `fail` if any step failed, `skipped` if every step was skipped, else `ok`. */
   status: "ok" | "fail" | "skipped";
+  /** The phase's wall-clock time, for a phase that ran. Absent on records written before it was kept, and for a phase skipped whole. */
+  durationMs?: number;
   steps: OpRunStepRecord[];
 }
 

package/src/op/steward-points.test.ts

@@ -17,6 +17,7 @@ import { workspacePoints } from "../workspace/points-cli";
 import type { WireAnswer } from "../workspace/points";
 import { readMemberStewards } from "../workspace/status-stewards";
 import { readRunLedger } from "../lifecycle/run-ledger";
+import { acquireLease, releaseLease } from "../lifecycle/lease";
 import type { ActivityFn, ActivityProfile } from "./activity-registry";
 import { runOpLocally } from "./local-executor";
 import { createBesideState, formatRoundLine, runOperatorRound, waitForBesideRuns } from "./operator";
@@ -422,3 +423,83 @@ describe("a waiting run of an Op beside the steward's turns (#2861)", () => {
     expect((await readMemberStewards(root, "local", "2027-01-01T00:11:00Z")).stewards.find((s) => s.name === "build-steward")!.waiting).toEqual([]);
   });
 });
+
+describe("status lists a wait only while its question is open (studio box, 0.95.1)", () => {
+  const stewardShape = () =>
+    contract({ $schema: statusSchema.$schema, $id: `urn:test:status-steward-open-${Math.random()}`, $defs: statusSchema.$defs, $ref: "#/$defs/steward" });
+
+  /** A waiting run of `op` recorded as `steward`'s, and its ledger record. */
+  async function waitingRun(steward: string, op: OpConfig, release: string) {
+    const acts = new Map<string, ActivityFn>([
+      ...shipActivities([]),
+      ["askShip", async (args) => (await askPointInRun({ cwd: root, point: "ship-now", inputs: { release: args.release }, subject: release, on })).answer],
+    ]);
+    process.env[STEWARD_ENV] = steward;
+    try {
+      expect((await runOpLocally(op, acts, PROFILES, undefined, { ledger: { cwd: root } })).status).toBe("waiting");
+    } finally {
+      resetStewardTurn();
+    }
+    return (await readRunLedger("local", op.name, { cwd: root })).records.at(-1)!;
+  }
+
+  function declare(name: string, beside: OpConfig) {
+    const steward = declareSteward({ name, ops: [], beside: [{ op: beside, ready: { kind: "activity", fn: "readyShip", args: {} } }], capabilities: ["inference"] });
+    mkdirSync(join(root, "ops"), { recursive: true });
+    writeFileSync(join(root, "chant.config.json"), "{}\n");
+    writeFileSync(join(root, "ops", `${name}.op.ts`), `export const steward = ${JSON.stringify(steward)};\n`);
+  }
+
+  const entryOf = async (name: string) =>
+    (await readMemberStewards(root, "local", new Date().toISOString())).stewards.find((s) => s.name === name)!;
+
+  test("an open question is listed; once answered it is not, and lastRun.point has its state now", async () => {
+    const op = shipOp("open-dispatch", "r-40");
+    declare("open-steward", op);
+    const run = await waitingRun("open-steward", op, "r-40");
+    const question = run.point!.id;
+
+    const open = await entryOf("open-steward");
+    stewardShape().expectValid(open);
+    expect(open.waiting).toEqual([
+      { op: "open-dispatch", run: run.id, id: question, point: "ship-now", state: "escalated", path: run.point!.path, subject: "r-40", since: run.point!.since },
+    ]);
+
+    // A person answers; no run of the Op has started since, so the ledger's newest record still says waiting.
+    expect("error" in (await answerPoint({ cwd: root, id: question, answer: "yes", by: ["alice"], on }))).toBe(false);
+    expect((await readRunLedger("local", "open-dispatch", { cwd: root })).records.at(-1)).toMatchObject({ id: run.id, status: "waiting", point: { state: "escalated" } });
+    const answered = await entryOf("open-steward");
+    stewardShape().expectValid(answered);
+    expect(answered.waiting).toEqual([]);
+    expect(answered.ops[0].lastRun).toMatchObject({ id: run.id, status: "waiting", point: { id: question, state: "answered" } });
+  });
+
+  test("a newer run in flight, holding the Op's lease since the waiting run ended, drops the wait", async () => {
+    const op = shipOp("busy-dispatch", "r-41");
+    declare("busy-steward", op);
+    const run = await waitingRun("busy-steward", op, "r-41");
+    expect((await entryOf("busy-steward")).waiting.map((w) => w.run)).toEqual([run.id]);
+
+    // The next run takes the Op's lease and is still going: it has no ledger record yet.
+    const lease = await acquireLease("busy-dispatch", "busy-steward/busy-dispatch@box", { cwd: root });
+    expect(lease.acquired).toBe(true);
+    const busy = await entryOf("busy-steward");
+    stewardShape().expectValid(busy);
+    expect(busy.ops[0].beside!.lease).toMatchObject({ holder: "busy-steward/busy-dispatch@box", live: true });
+    expect(busy.ops[0].lastRun).toMatchObject({ id: run.id, status: "waiting", point: { state: "escalated" } });
+    expect(busy.waiting).toEqual([]);
+
+    // Once it lets go without a record, the question is still open and waited on again.
+    await releaseLease("busy-dispatch", "busy-steward/busy-dispatch@box", lease.lease!.token, { cwd: root });
+    expect((await entryOf("busy-steward")).waiting.map((w) => w.run)).toEqual([run.id]);
+  });
+
+  test("when the questions can't be read, the run ledger's state stands and the wait is listed", async () => {
+    const op = shipOp("blind-dispatch", "r-42");
+    declare("blind-steward", op);
+    const run = await waitingRun("blind-steward", op, "r-42");
+    expect("error" in (await answerPoint({ cwd: root, id: run.point!.id, answer: "yes", by: ["alice"], on }))).toBe(false);
+    const entry = (await readMemberStewards(root, "local", new Date().toISOString(), "chant", null, { readQuestions: async () => null })).stewards.find((s) => s.name === "blind-steward")!;
+    expect(entry.waiting).toMatchObject([{ run: run.id, state: "escalated" }]);
+  });
+});

package/src/workspace/checks/diagrams.test.ts

@@ -123,6 +123,30 @@ describe("diagram-render-drift (WSP133)", () => {
     expect(d[0].message).toContain(`recorded sourceHash ${HASH.slice(0, 12)}`);
   });
 
+  test("a mermaid diagram with no render: WSP132 has nothing to check, and a recorded sourceHash pins the source", async () => {
+    const mermaid = (extra: Record<string, unknown> = {}) => ({ name: "flow", title: "Flow", source: "docs/diagrams/flow.mmd", renderer: { tool: "mermaid", version: "11.4.1" }, ...extra });
+    const pinned = repo({ "chant.workspace.json": declaration([mermaid({ sourceHash: HASH })]), "docs/diagrams/flow.mmd": SOURCE });
+    expect(await found(pinned)).toEqual([]);
+    const edited = repo({ "chant.workspace.json": declaration([mermaid({ sourceHash: HASH })]), "docs/diagrams/flow.mmd": "flowchart LR\n  a --> b\n" });
+    const d = await found(edited);
+    expect(d.map((x) => [x.ruleId, x.code])).toEqual([["WSP133", "diagram-render-drift"]]);
+    expect(d[0].message).toContain("source docs/diagrams/flow.mmd changed since its sourceHash was recorded");
+    expect(d[0].message).toMatch(/; update sourceHash$/);
+    const missing = repo({ "chant.workspace.json": declaration([mermaid()]), "docs/README.md": "" });
+    expect((await found(missing)).map((x) => x.ruleId)).toEqual(["WSP131"]);
+  });
+
+  test("an excalidraw diagram's sourceHash pins its JSON, and an exported SVG it names must exist", async () => {
+    const scene = JSON.stringify({ type: "excalidraw", version: 2, source: "hud", elements: [], appState: {}, files: {} });
+    const hash = sha256Hex(Buffer.from(scene, "utf-8"));
+    const sketch = (extra: Record<string, unknown> = {}) => ({ name: "sketch", title: "Sketch", source: "docs/diagrams/sketch.excalidraw", renderer: { tool: "excalidraw", version: "0.18.0" }, sourceHash: hash, ...extra });
+    expect(await found(repo({ "chant.workspace.json": declaration([sketch()]), "docs/diagrams/sketch.excalidraw": scene }))).toEqual([]);
+    const moved = await found(repo({ "chant.workspace.json": declaration([sketch()]), "docs/diagrams/sketch.excalidraw": scene.replace("[]", '[{"id":"a"}]') }));
+    expect(moved.map((x) => x.ruleId)).toEqual(["WSP133"]);
+    const noSvg = await found(repo({ "chant.workspace.json": declaration([sketch({ render: "docs/diagrams/sketch.svg" })]), "docs/diagrams/sketch.excalidraw": scene }));
+    expect(noSvg.map((x) => x.ruleId)).toEqual(["WSP132"]);
+  });
+
   test("a missing source is left to WSP131; WSP133 finds nothing to compare", async () => {
     const root = repo({
       "chant.workspace.json": declaration([diagram({ sourceHash: HASH })]),

package/src/workspace/checks/diagrams.ts

@@ -13,6 +13,11 @@
  * | WSP132 | `diagram-render-missing` | a diagram's render does not exist in the tree read |
  * | WSP133 | `diagram-render-drift` | a diagram records a `sourceHash`, and the source's bytes now hash to something else |
  *
+ * A mermaid or excalidraw diagram may name no render (a reader such as hud
+ * draws it from its source, with the pinned library): WSP132 then has nothing to
+ * check, and WSP133, when the entry records a sourceHash, pins the source
+ * itself, so an edit to it fails until the hash is updated.
+ *
  * WSP133 is opt-in per diagram: without a recorded `sourceHash` there is
  * nothing to compare, so the entry is silently not checked for drift. A
  * declaration records one by hashing the source when it commits a fresh
@@ -66,13 +71,13 @@ export const DIAGRAM_CHECKS: readonly WorkspaceCheck[] = [
   {
     id: WSP_DIAGRAM_RENDER_MISSING,
     name: "diagram-render-missing",
-    description: "A diagram's render exists in the tree read.",
+    description: "A diagram's render, when it names one, exists in the tree read. Only a mermaid or excalidraw diagram may name none.",
     severity: "error",
     configurable: true,
     check(ctx: WorkspaceCheckContext) {
       const out: WorkspaceDiagnostic[] = [];
       for (const d of declaredDiagrams(ctx.declaration)) {
-        if (ctx.tree.stat(d.render) === "file") continue;
+        if (d.render === null || ctx.tree.stat(d.render) === "file") continue;
         out.push(diagramFinding(this, d, "render", "diagram-render-missing", `${where(d)} diagram ${d.name} names the render ${d.render}, which does not exist${ctx.tree.label}`));
       }
       return out;
@@ -92,13 +97,15 @@ export const DIAGRAM_CHECKS: readonly WorkspaceCheck[] = [
         const bytes = ctx.tree.bytes ? ctx.tree.bytes(d.source) : Buffer.from(ctx.tree.read(d.source), "utf-8");
         const actual = sha256Hex(bytes);
         if (actual === d.sourceHash) continue;
+        const since = d.render === null ? "its sourceHash was recorded" : `${d.render} was rendered from it`;
+        const fix = d.render === null ? "update sourceHash" : "rerun the renderer and commit the result, or update sourceHash";
         out.push(
           diagramFinding(
             this,
             d,
             "sourceHash",
             "diagram-render-drift",
-            `${where(d)} diagram ${d.name}'s source ${d.source} changed since ${d.render} was rendered from it: recorded sourceHash ${d.sourceHash.slice(0, 12)} does not match the source's current hash ${actual.slice(0, 12)}${ctx.tree.label}; rerun the renderer and commit the result, or update sourceHash`,
+            `${where(d)} diagram ${d.name}'s source ${d.source} changed since ${since}: recorded sourceHash ${d.sourceHash.slice(0, 12)} does not match the source's current hash ${actual.slice(0, 12)}${ctx.tree.label}; ${fix}`,
           ),
         );
       }

package/src/workspace/declaration.schema.json

@@ -592,13 +592,53 @@
     },
     "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.",
+      "description": "A diagram artifact the workspace declares (#2764): a rendered image with a source, pinned to the renderer that made it. A mermaid or excalidraw diagram may name no render: a reader draws it from its source. chant never runs the renderer.",
       "required": [
         "name",
         "title",
-        "render",
         "renderer"
       ],
+      "if": {
+        "type": "object",
+        "properties": {
+          "renderer": {
+            "type": "object",
+            "properties": {
+              "tool": {
+                "enum": ["mermaid", "excalidraw"]
+              }
+            },
+            "required": [
+              "tool"
+            ]
+          }
+        },
+        "required": [
+          "renderer"
+        ]
+      },
+      "then": {
+        "type": "object",
+        "properties": {
+          "source": {
+            "$ref": "#/$defs/path"
+          }
+        },
+        "required": [
+          "source"
+        ]
+      },
+      "else": {
+        "type": "object",
+        "properties": {
+          "render": {
+            "$ref": "#/$defs/path"
+          }
+        },
+        "required": [
+          "render"
+        ]
+      },
       "properties": {
         "name": {
           "$ref": "#/$defs/name",
@@ -617,8 +657,11 @@
           "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."
+          "oneOf": [
+            { "$ref": "#/$defs/path" },
+            { "type": "null" }
+          ],
+          "description": "The rendered image, from the workspace root, with / separators. Required for d2 and graphviz. A mermaid or excalidraw diagram needs a source instead and may leave render out or null, from chant 0.96.0: a reader such as hud draws it from the source (an excalidraw diagram may still commit an exported SVG for docs)."
         },
         "renderer": {
           "$ref": "#/$defs/diagramRenderer"
@@ -626,7 +669,7 @@
         "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."
+          "description": "sha256 hex of the source's bytes when render was last produced from it, or for a mermaid or excalidraw diagram without a render, when the source was last pinned. 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": {
@@ -643,11 +686,11 @@
       ],
       "properties": {
         "tool": {
-          "enum": ["d2", "mermaid", "graphviz"]
+          "enum": ["d2", "mermaid", "graphviz", "excalidraw"]
         },
         "version": {
           "$ref": "#/$defs/version",
-          "description": "The exact release the render was made with, such as 0.9.0."
+          "description": "The exact release the render was made with, such as 0.9.0. For mermaid or excalidraw, the release of the library a reader draws the source with, such as 11.4.1."
         },
         "args": {
           "type": "array",

package/src/workspace/declaration.test.ts

@@ -392,6 +392,24 @@ describe("diagram artifacts (#2764)", () => {
     expect(failure(base([member([{ name: "a", title: "A", source: null, render: "a.svg" }])])).message).toContain('missing required field "renderer"');
   });
 
+  test("a mermaid diagram needs a source and may name no render; d2 and graphviz still need a render", () => {
+    const mermaid = { tool: "mermaid", version: "11.4.1" };
+    const d = parse(base([member([{ name: "flow", title: "Flow", source: "docs/diagrams/flow.mmd", renderer: mermaid }])]));
+    expect(d.members[0].diagrams[0]).toMatchObject({ source: "docs/diagrams/flow.mmd", render: null, renderer: { ...mermaid, args: [] } });
+    expect(parse(base([member([{ name: "flow", title: "Flow", source: "flow.mmd", render: null, renderer: mermaid }])])).members[0].diagrams[0].render).toBeNull();
+    expect(parse(base([member([{ name: "flow", title: "Flow", source: "flow.mmd", render: "flow.svg", renderer: mermaid }])])).members[0].diagrams[0].render).toBe("flow.svg");
+    expect(failure(base([member([{ name: "flow", title: "Flow", renderer: mermaid }])])).message).toContain('missing required field "source"');
+    expect(failure(base([member([{ name: "flow", title: "Flow", source: null, renderer: mermaid }])])).code).toBe("declaration-invalid");
+    expect(failure(base([member([{ name: "a", title: "A", source: "a.d2", render: null, renderer }])])).code).toBe("declaration-invalid");
+  });
+
+  test("an excalidraw diagram, like mermaid, needs a source and may name no render or an exported SVG", () => {
+    const excalidraw = { tool: "excalidraw", version: "0.18.0" };
+    expect(parse(base([member([{ name: "sketch", title: "Sketch", source: "docs/diagrams/sketch.excalidraw", renderer: excalidraw }])])).members[0].diagrams[0]).toMatchObject({ render: null, renderer: { ...excalidraw, args: [] } });
+    expect(parse(base([member([{ name: "sketch", title: "Sketch", source: "sketch.excalidraw", render: "sketch.svg", renderer: excalidraw }])])).members[0].diagrams[0].render).toBe("sketch.svg");
+    expect(failure(base([member([{ name: "sketch", title: "Sketch", renderer: excalidraw }])])).message).toContain('missing required field "source"');
+  });
+
   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);

package/src/workspace/declaration.ts

@@ -140,13 +140,13 @@ export interface LinkDeclaration {
 }
 
 /** 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 const DIAGRAM_TOOLS = ["d2", "mermaid", "graphviz", "excalidraw"] 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". */
+  /** The exact release the render was made with, such as "0.9.0". For mermaid or excalidraw, the release of the library a reader draws the source with. */
   version: string;
   /** Passed before the input and output paths, in order. */
   args: string[];
@@ -162,10 +162,10 @@ export interface DiagramDeclaration {
   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;
+  /** From the workspace root, with / separators. Null only for a mermaid or excalidraw diagram, which a reader draws from its source. */
+  render: string | null;
   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. */
+  /** sha256 hex of the source's bytes when the render was last produced (a mermaid or excalidraw diagram without a render: when the source was last pinned), 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;
@@ -725,13 +725,13 @@ function recordKindsOf(raw: unknown, dir: string, member: string | null, pointer
 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 }[]
+      | { name: string; title: string; source?: string | null; render?: string | null; 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,
+    render: d.render ?? null,
     renderer: { tool: d.renderer.tool, version: d.renderer.version, args: [...(d.renderer.args ?? [])] },
     sourceHash: d.sourceHash ?? null,
     member,