@intentius/chant 0.91.0 → 0.93.0

package/src/workspace/chant-migrations.ts

@@ -0,0 +1,164 @@
+/**
+ * Migrations chant ships (#2737).
+ *
+ * A template's own migrations (./lineage-migrations.ts) move a scope between
+ * two versions of that template. Some moves are chant's instead: a part a
+ * template used goes away, and chant knows where each piece of it went. The
+ * first is `chud-lexicon-exit`, which takes a repo made from chud's template
+ * (or the studio kit's copy of it) off `@intentius/chant-lexicon-chud` and
+ * `@intentius/chud-runtime` (ws-056).
+ *
+ * `chant workspace upgrade` asks each one for a plan after the template's own
+ * chain has run in the staging worktree, and before the per-file merge. A
+ * migration plans from what the scope holds, not from a version range, so it
+ * works whatever ref the scope is pinned at. Its plan lists every file it
+ * writes or deletes and why, what it cannot move and where that went, and any
+ * conflict. A plan with a conflict is not applied at all, and the upgrade's
+ * checks fail with it, so the dry run shows the whole plan and the tree is
+ * never left half moved.
+ *
+ * An applied migration's id is added to the lineage's `migrations`, so the
+ * lock records it and a second upgrade does not plan it again. A migration's
+ * plan is also empty once nothing it moves is left, so running it twice
+ * changes nothing either way.
+ *
+ * Files the migration rewrites keep their lineage entry: the lock's hash is
+ * still the template's, so to a later upgrade they are the project's own
+ * edits, merged per file like any other (ws-005). A deleted file keeps its
+ * entry too, so a template version that still has it leaves it deleted.
+ */
+
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import type { Lineage } from "./lineage-lock";
+import { chudLexiconExit } from "./chant-migrations/chud-lexicon-exit";
+import { chudLexiconExitRollback } from "./chant-migrations/chud-lexicon-exit-rollback";
+import { chudLexiconExitShipInputs } from "./chant-migrations/chud-lexicon-exit-ship-inputs";
+import { chudLexiconExitShipPolicy } from "./chant-migrations/chud-lexicon-exit-ship-policy";
+import { chudLexiconExitFlySite } from "./chant-migrations/chud-lexicon-exit-fly-site";
+import { chudLexiconExitLiveNames } from "./chant-migrations/chud-lexicon-exit-live-names";
+
+/** One file a plan writes or deletes, relative to the scope. */
+export interface PlannedChange {
+  path: string;
+  action: "write" | "delete";
+  /** Why, in a few words. */
+  why: string;
+  /** The new content, for a write. */
+  data?: Buffer;
+  /** True when the file had been edited since the template wrote it; the edit stays in git history. */
+  edited?: boolean;
+}
+
+/** A part the migration does not move, and where it went instead. */
+export interface NotMoved {
+  what: string;
+  where: string;
+}
+
+/** Why a plan cannot be applied. */
+export interface PlanConflict {
+  path: string;
+  reason: string;
+}
+
+export interface ChantMigrationPlan {
+  id: string;
+  description: string;
+  changes: PlannedChange[];
+  notMoved: NotMoved[];
+  conflicts: PlanConflict[];
+}
+
+export interface ChantMigrationContext {
+  /** The scope directory (in the staging worktree). */
+  dir: string;
+  lineage: Lineage;
+  /** The chant version doing the upgrade, for dependency ranges. */
+  chantVersion: string;
+}
+
+export interface ChantMigration {
+  id: string;
+  description: string;
+  /** The plan for this scope, or null when there is nothing here for this migration to move. */
+  plan(ctx: ChantMigrationContext): ChantMigrationPlan | null;
+}
+
+/** Every migration chant ships, in the order they are planned. */
+export const CHANT_MIGRATIONS: readonly ChantMigration[] = [
+  chudLexiconExit,
+  chudLexiconExitRollback,
+  chudLexiconExitShipInputs,
+  chudLexiconExitShipPolicy,
+  chudLexiconExitFlySite,
+  chudLexiconExitLiveNames,
+];
+
+/** The plans for a scope: each migration not yet in the lineage that finds something to move. */
+export function planChantMigrations(ctx: ChantMigrationContext, migrations: readonly ChantMigration[] = CHANT_MIGRATIONS): ChantMigrationPlan[] {
+  const applied = new Set(ctx.lineage.migrations);
+  const plans: ChantMigrationPlan[] = [];
+  for (const m of migrations) {
+    if (applied.has(m.id)) continue;
+    const plan = m.plan(ctx);
+    if (plan && (plan.changes.length > 0 || plan.conflicts.length > 0)) plans.push(plan);
+  }
+  return plans;
+}
+
+/**
+ * Plan each migration in order and apply each plan with no conflict before
+ * the next is planned, so a migration planned after another sees the tree
+ * the earlier one left (#2800: `chud-lexicon-exit-rollback` after
+ * `chud-lexicon-exit`). A plan with a conflict is not applied, and the ones
+ * after it plan from the tree as it is.
+ */
+export function runChantMigrations(ctx: ChantMigrationContext, migrations: readonly ChantMigration[] = CHANT_MIGRATIONS): Array<{ plan: ChantMigrationPlan; applied: boolean }> {
+  const out: Array<{ plan: ChantMigrationPlan; applied: boolean }> = [];
+  for (const m of migrations) {
+    if (ctx.lineage.migrations.includes(m.id)) continue;
+    const plan = m.plan(ctx);
+    if (!plan || (plan.changes.length === 0 && plan.conflicts.length === 0)) continue;
+    const applied = plan.conflicts.length === 0;
+    if (applied) applyChantMigration(plan, ctx.dir, ctx.lineage);
+    out.push({ plan, applied });
+  }
+  return out;
+}
+
+/** Apply a plan with no conflicts, and record its id in the lineage. */
+export function applyChantMigration(plan: ChantMigrationPlan, dir: string, lineage: Lineage): void {
+  if (plan.conflicts.length > 0) throw new Error(`${plan.id} has conflicts and cannot be applied`);
+  for (const c of plan.changes) {
+    const abs = join(dir, c.path);
+    if (c.action === "delete") {
+      rmSync(abs, { force: true });
+    } else {
+      mkdirSync(dirname(abs), { recursive: true });
+      writeFileSync(abs, c.data!);
+    }
+  }
+  if (!lineage.migrations.includes(plan.id)) lineage.migrations.push(plan.id);
+}
+
+/** A plan as the upgrade reports it: no file contents. */
+export interface ChantMigrationReport {
+  id: string;
+  description: string;
+  applied: boolean;
+  changes: Array<Omit<PlannedChange, "data">>;
+  notMoved: NotMoved[];
+  conflicts: PlanConflict[];
+}
+
+export function reportPlan(plan: ChantMigrationPlan, applied: boolean): ChantMigrationReport {
+  return {
+    id: plan.id,
+    description: plan.description,
+    applied,
+    changes: plan.changes.map(({ data: _d, ...rest }) => rest),
+    notMoved: plan.notMoved,
+    conflicts: plan.conflicts,
+  };
+}

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

@@ -11,6 +11,8 @@ import { afterAll, describe, expect, test } from "vitest";
 import { cleanScratch, commitAll, contract, declaration, git, REPO, repo, scratchDir, validSchema } from "./__fixtures__/contract-repo";
 import schema from "./check.schema.json";
 import { BOX_FINDING_CODES } from "./checks/boxes";
+import { RECORD_FINDING_CODES } from "./checks/records";
+import { DIAGRAM_FINDING_CODES } from "./checks/diagrams";
 import { WORKSPACE_ERROR_CODES } from "./declaration";
 import { CHECK_CODES, CHECK_CONTRACT_VERSION, CHECK_ERROR_CODES, CHECK_OUTPUT_SCHEMA_ID, runChecks, type CheckDocument } from "./lineage-check";
 
@@ -36,8 +38,8 @@ describe("check output schema", () => {
   test("lists exactly the codes the code can return", () => {
     expect(schema.$defs.lockFinding.properties.code.enum).toEqual([...CHECK_CODES]);
     expect(schema.$defs.failure.properties.error.properties.code.enum).toEqual([...CHECK_ERROR_CODES]);
-    expect(schema.$defs.diagnostic.properties.code.enum).toEqual([...WORKSPACE_ERROR_CODES, ...BOX_FINDING_CODES]);
-    expect(schema.$defs.suppressed.properties.code.enum).toEqual([...WORKSPACE_ERROR_CODES, ...BOX_FINDING_CODES]);
+    expect(schema.$defs.diagnostic.properties.code.enum).toEqual([...WORKSPACE_ERROR_CODES, ...BOX_FINDING_CODES, ...RECORD_FINDING_CODES, ...DIAGRAM_FINDING_CODES]);
+    expect(schema.$defs.suppressed.properties.code.enum).toEqual([...WORKSPACE_ERROR_CODES, ...BOX_FINDING_CODES, ...RECORD_FINDING_CODES, ...DIAGRAM_FINDING_CODES]);
   });
 });
 

package/src/workspace/check.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://intentius.io/chant/schemas/workspace/check/v1/check.schema.json",
   "title": "chant workspace check output",
-  "description": "What `chant workspace check --format json` prints, version 1 of the read contract for checking a workspace (#2524 D9, D15, D16, #2535, #2536). The lineage lock findings carry reason codes; the declaration findings carry WSP ids from the check catalog, WSP001, a declaration that can't be read, also carries the declaration's reason code, and the box checks WSP121 to WSP124 carry theirs. Readers ignore fields they do not know; a field is only ever added within a version. The reason and error codes are closed lists: a new code is a new contract version. Contract version 1 is written by chant 0.81.0 and newer; a reader that needs it refuses output whose `contract` it doesn't know. Every code is in the one closed list of `reason-codes.ts`.",
+  "description": "What `chant workspace check --format json` prints, version 1 of the read contract for checking a workspace (#2524 D9, D15, D16, #2535, #2536). The lineage lock findings carry reason codes; the declaration findings carry WSP ids from the check catalog, WSP001, a declaration that can't be read, also carries the declaration's reason code, and the box checks WSP121 to WSP125 carry theirs. Readers ignore fields they do not know; a field is only ever added within a version. The reason and error codes are closed lists: a new code is a new contract version. Contract version 1 is written by chant 0.81.0 and newer; a reader that needs it refuses output whose `contract` it doesn't know. Every code is in the one closed list of `reason-codes.ts`.",
   "oneOf": [
     {
       "$ref": "#/$defs/result"
@@ -226,9 +226,14 @@
             "box-credential-declared",
             "box-capability-unbrokered",
             "box-isolation-collision",
-            "box-isolation-literal"
+            "box-isolation-literal",
+            "box-fountain-callback-undeclared",
+            "work-acceptance-unmet",
+            "diagram-source-missing",
+            "diagram-render-missing",
+            "diagram-render-drift"
           ],
-          "description": "For WSP001: why the declaration can't be read. For WSP121 to WSP124, the box finding (#2726, #2727)."
+          "description": "For WSP001: why the declaration can't be read. For WSP121 to WSP125, the box finding (#2726, #2727, #2780). For WSP117, work-acceptance-unmet (#2772). For WSP131 to WSP133, the diagram finding (#2764)."
         }
       }
     },
@@ -297,9 +302,14 @@
             "box-credential-declared",
             "box-capability-unbrokered",
             "box-isolation-collision",
-            "box-isolation-literal"
+            "box-isolation-literal",
+            "box-fountain-callback-undeclared",
+            "work-acceptance-unmet",
+            "diagram-source-missing",
+            "diagram-render-missing",
+            "diagram-render-drift"
           ],
-          "description": "For WSP001: why the declaration can't be read. For WSP121 to WSP124, the box finding (#2726, #2727)."
+          "description": "For WSP001: why the declaration can't be read. For WSP121 to WSP125, the box finding (#2726, #2727, #2780). For WSP117, work-acceptance-unmet (#2772). For WSP131 to WSP133, the diagram finding (#2764)."
         },
         "reason": {
           "type": "string"

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

@@ -7,7 +7,7 @@ import { afterAll, describe, expect, test } from "vitest";
 import { runDeclarationChecks } from "../checks";
 import { parseDeclaration, WorkspaceReadError } from "../declaration";
 import { gitTree } from "../tree";
-import { isCredentialKey, isSecretReference, literalSecretsInCode, literalSecretsInText } from "./boxes";
+import { fountainBoxCall, isCredentialKey, isSecretReference, literalSecretsInCode, literalSecretsInText } from "./boxes";
 
 const scratch: string[] = [];
 afterAll(() => {
@@ -195,3 +195,82 @@ describe("what counts as a literal secret", () => {
     expect(literalSecretsInText(`# nothing\nkey: ${GITHUB_TOKEN}\n`).map((s) => s.line)).toEqual([2]);
   });
 });
+
+describe("box-fountain-callback-undeclared (WSP125, #2780)", () => {
+  /** A studio-style fountain Box declaration. */
+  const fountainBox = `import { readFileSync } from "node:fs";
+import { Box } from "@intentius/chant-lexicon-fountain";
+
+export const { environment, agent } = Box({
+  name: "studio-box",
+  setupScript: readFileSync("box/setup.sh", "utf8"),
+  model: "anthropic/claude-sonnet-4-6",
+  permissionPolicy: { default: "auto_allow" },
+});
+`;
+  const CALLBACK = { name: "fountain-callback", broker: "fountain", scope: ["owner"] };
+
+  test("a box member that builds a fountain Box and does not declare the callback token fails, at the Box call", async () => {
+    const root = repo({ "chant.workspace.json": declaration(BROKERED), "spec/box.ts": fountainBox });
+    const d = await found(root);
+    expect(d.map((x) => [x.ruleId, x.code, x.entity, x.file, x.line])).toEqual([
+      ["WSP125", "box-fountain-callback-undeclared", "spec", "spec/box.ts", 4],
+    ]);
+    expect(d[0].message).toContain("callback token scoped to its owner (FOUNTAIN_TOKEN); the member's box block does not declare it");
+    expect(d[0].message).toContain('{ "name": "fountain-callback", "broker": "fountain", "scope": ["owner"] }');
+  });
+
+  test("declaring fountain-callback, brokered by fountain with scope owner, passes, beside a fountain capability a lobby brokers", async () => {
+    const root = repo({
+      "chant.workspace.json": declaration({
+        capabilities: [...BROKERED.capabilities, { name: "fountain", broker: "lobby", scope: ["agent", "conversations"] }, CALLBACK],
+      }),
+      "spec/box.ts": fountainBox,
+    });
+    expect(await found(root)).toEqual([]);
+  });
+
+  test("fountain-callback behind another broker, or without owner in its scope, fails", async () => {
+    const lobby = repo({
+      "chant.workspace.json": declaration({ capabilities: [{ name: "fountain-callback", broker: "lobby", scope: ["conversations"] }] }),
+      "spec/box.ts": fountainBox,
+    });
+    const d = await found(lobby);
+    expect(d.map((x) => [x.ruleId, x.file])).toEqual([["WSP125", "spec/box.ts"]]);
+    expect(d[0].message).toContain("names the broker lobby, but fountain hands this token to the sandbox itself");
+    const narrow = repo({
+      "chant.workspace.json": declaration({ capabilities: [{ name: "fountain-callback", broker: "fountain", scope: ["conversations"] }] }),
+      "spec/box.ts": fountainBox,
+    });
+    expect((await found(narrow))[0].message).toContain("has scope [conversations], not owner");
+  });
+
+  test("a box member that builds no fountain Box, and a member with no box block, are not flagged", async () => {
+    const other = repo({ "chant.workspace.json": declaration(BROKERED), "spec/box.ts": spec("${ANTHROPIC_API_KEY}") });
+    expect(await found(other)).toEqual([]);
+    const plain = repo({
+      "chant.workspace.json": JSON.stringify({ name: "acme", schema: 1, members: [{ name: "spec", dir: "spec", kind: "other", because: "x" }] }),
+      "spec/box.ts": fountainBox,
+    });
+    expect(await found(plain)).toEqual([]);
+  });
+
+  test("it can be turned down while fountain has no way to drop the token (managoat/fountain#2497)", async () => {
+    const root = repo({
+      "chant.workspace.json": declaration(BROKERED, { suppress: [{ check: "WSP125", because: "waiting on fountain" }] }),
+      "spec/box.ts": fountainBox,
+    });
+    expect((await found(root)).filter((x) => x.ruleId === "WSP125")).toEqual([]);
+  });
+
+  test("fountainBoxCall finds the composite imported by name, aliased or through a namespace, and nothing else", () => {
+    const at = (text: string) => fountainBoxCall(text, "box.ts", ts.ScriptKind.TS);
+    expect(at(fountainBox)).toEqual({ line: 4, column: 39 });
+    expect(at(`import { Box as FBox } from "@intentius/chant-lexicon-fountain";\nFBox({});\n`)).toEqual({ line: 2, column: 1 });
+    expect(at(`import * as fountain from "@intentius/chant-lexicon-fountain";\nfountain.Box({});\n`)).toEqual({ line: 2, column: 1 });
+    // Imported but never called, another package's Box, or a Box of one's own.
+    expect(at(`import { Box } from "@intentius/chant-lexicon-fountain";\nexport { Box };\n`)).toBeUndefined();
+    expect(at(`import { Box } from "@intentius/chant-lexicon-chaff";\nBox({});\n`)).toBeUndefined();
+    expect(at(`const Box = (o: object) => o;\nBox({}); // @intentius/chant-lexicon-fountain\n`)).toBeUndefined();
+  });
+});

package/src/workspace/checks/boxes.ts

@@ -26,6 +26,17 @@
  *
  * WSP123 and WSP124, box isolation (#2727), are in `./box-isolation.ts` and
  * listed here after these two.
+ *
+ * WSP125 (`box-fountain-callback-undeclared`, #2780) is the one credential a
+ * box gets without asking. fountain v0.21.0 gives every persistent sandbox a
+ * callback token scoped to its owner (`FOUNTAIN_TOKEN`, `sandbox_api_access:
+ * owner`), and a fountain `Box` is always persistent, so its member's block
+ * has to say so: the capability `fountain-callback`, brokered by `fountain`,
+ * with scope `owner`. It is named apart from `fountain`, the API access a
+ * lobby may broker for the same box. A member builds a Box when one of its TypeScript or JavaScript files
+ * imports `Box` from `@intentius/chant-lexicon-fountain` and calls it, read as
+ * syntax and never run. Upstream, managoat/fountain#2497 asks for a way to run
+ * a persistent agent with no callback token.
  */
 
 import * as ts from "typescript";
@@ -36,10 +47,77 @@ import { joinPath, skippedDir, type WorkspaceTree } from "../tree";
 import { BOX_ISOLATION_CHECKS } from "./box-isolation";
 
 /** The read contract's codes for the box findings, carried as `code` on each. */
-export const BOX_FINDING_CODES = ["box-credential-declared", "box-capability-unbrokered", "box-isolation-collision", "box-isolation-literal"] as const satisfies readonly ReasonCode[];
+export const BOX_FINDING_CODES = [
+  "box-credential-declared",
+  "box-capability-unbrokered",
+  "box-isolation-collision",
+  "box-isolation-literal",
+  "box-fountain-callback-undeclared",
+] as const satisfies readonly ReasonCode[];
 
 export const WSP_BOX_CREDENTIAL = "WSP121";
 export const WSP_BOX_UNBROKERED = "WSP122";
+export const WSP_BOX_FOUNTAIN_CALLBACK = "WSP125";
+
+/** The fountain lexicon's package, whose `Box` composite runs a persistent sandbox. */
+const FOUNTAIN_LEXICON = "@intentius/chant-lexicon-fountain";
+
+/**
+ * The capability a box block declares for fountain's callback token (#2780).
+ * The fountain lexicon exports the same value as `BOX_FOUNTAIN_CALLBACK_CAPABILITY`.
+ */
+export const FOUNTAIN_CALLBACK_CAPABILITY = { name: "fountain-callback", broker: "fountain", scope: ["owner"] } as const;
+
+/** Where a file calls the fountain lexicon's `Box`, 1-based. */
+export interface FountainBoxCall {
+  line: number;
+  column: number;
+}
+
+/**
+ * The first call of the fountain lexicon's `Box` in a TypeScript or
+ * JavaScript file, read as syntax and never run: `Box` imported by name
+ * (aliased or not) and called, or called through a namespace import. Any
+ * other `Box` is not the composite.
+ */
+export function fountainBoxCall(text: string, file: string, kind: ts.ScriptKind): FountainBoxCall | undefined {
+  if (!text.includes(FOUNTAIN_LEXICON)) return undefined;
+  const source = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true, kind);
+  const names = new Set<string>();
+  const namespaces = new Set<string>();
+  for (const stmt of source.statements) {
+    if (!ts.isImportDeclaration(stmt) || !ts.isStringLiteral(stmt.moduleSpecifier)) continue;
+    const from = stmt.moduleSpecifier.text;
+    if (from !== FOUNTAIN_LEXICON && !from.startsWith(`${FOUNTAIN_LEXICON}/`)) continue;
+    const bindings = stmt.importClause?.namedBindings;
+    if (!bindings) continue;
+    if (ts.isNamespaceImport(bindings)) namespaces.add(bindings.name.text);
+    else for (const el of bindings.elements) if ((el.propertyName ?? el.name).text === "Box") names.add(el.name.text);
+  }
+  if (names.size === 0 && namespaces.size === 0) return undefined;
+  let found: ts.Node | undefined;
+  const visit = (node: ts.Node) => {
+    if (found) return;
+    if (ts.isCallExpression(node)) {
+      const callee = node.expression;
+      if (
+        (ts.isIdentifier(callee) && names.has(callee.text)) ||
+        (ts.isPropertyAccessExpression(callee) &&
+          callee.name.text === "Box" &&
+          ts.isIdentifier(callee.expression) &&
+          namespaces.has(callee.expression.text))
+      ) {
+        found = node;
+        return;
+      }
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(source);
+  if (!found) return undefined;
+  const { line, character } = source.getLineAndCharacterOfPosition(found.getStart(source));
+  return { line: line + 1, column: character + 1 };
+}
 
 /** Values whose shape alone says they are a credential. The list FTN001 uses, plus Anthropic keys. */
 export const CREDENTIAL_SHAPES: readonly { pattern: RegExp; label: string }[] = [
@@ -304,4 +382,61 @@ export const BOX_CHECKS: readonly WorkspaceCheck[] = [
   },
   // Box isolation (#2727), WSP123 and WSP124.
   ...BOX_ISOLATION_CHECKS,
+  {
+    id: WSP_BOX_FOUNTAIN_CALLBACK,
+    name: "box-fountain-callback-undeclared",
+    description:
+      "A box member that builds a fountain Box declares the callback token fountain gives its persistent sandbox: the fountain-callback capability, brokered by fountain, with scope owner.",
+    severity: "error",
+    configurable: true,
+    check(ctx) {
+      const out: WorkspaceDiagnostic[] = [];
+      const want = FOUNTAIN_CALLBACK_CAPABILITY;
+      const expected = `{ "name": "${want.name}", "broker": "${want.broker}", "scope": ["${want.scope[0]}"] }`;
+      for (const m of boxMembers(ctx)) {
+        const dir = m.dir === "." ? "" : m.dir;
+        if (ctx.tree.stat(dir) !== "dir") continue;
+        let at: { path: string; call: FountainBoxCall } | undefined;
+        for (const path of filesUnder(ctx.tree, dir)) {
+          const kind = CODE_EXTENSIONS[extension(path)];
+          if (kind === undefined || kind === ts.ScriptKind.JSON) continue;
+          let text: string;
+          try {
+            text = ctx.tree.read(path);
+          } catch {
+            continue;
+          }
+          if (text.length > MAX_FILE_BYTES) continue;
+          const call = fountainBoxCall(text, path, kind);
+          if (call) {
+            at = { path, call };
+            break;
+          }
+        }
+        if (!at) continue;
+        const declared = m.box!.capabilities.find((c) => c.name === want.name);
+        if (declared && declared.broker === want.broker && declared.scope.includes(want.scope[0])) continue;
+        const why = !declared
+          ? "the member's box block does not declare it"
+          : declared.broker !== want.broker
+            ? `the box block's ${want.name} capability names the broker ${declared.broker ?? "(none)"}, but fountain hands this token to the sandbox itself`
+            : `the box block's ${want.name} capability has scope [${declared.scope.join(", ")}], not ${want.scope[0]}`;
+        out.push({
+          checkId: this.id,
+          severity: this.severity,
+          code: "box-fountain-callback-undeclared",
+          message:
+            `box-fountain-callback-undeclared: member ${m.name} builds a fountain Box (${at.path}), and fountain v0.21.0 gives a persistent box's sandbox ` +
+            `a callback token scoped to its owner (FOUNTAIN_TOKEN); ${why}. Declare ${expected} in the box block ` +
+            `(managoat/fountain#2497 tracks running without it)`,
+          entity: m.name,
+          pointer: declared?.pointer ?? m.box!.pointer,
+          treeFile: at.path,
+          line: at.call.line,
+          column: at.call.column,
+        });
+      }
+      return out;
+    },
+  },
 ];

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

@@ -0,0 +1,134 @@
+/**
+ * The diagram checks, WSP131 to WSP133 (#2764).
+ */
+
+import { execFileSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { afterAll, describe, expect, test } from "vitest";
+import { runDeclarationChecks } from "../checks";
+import { sha256Hex } from "../../content-digest";
+
+const scratch: string[] = [];
+afterAll(() => {
+  for (const d of scratch) rmSync(d, { recursive: true, force: true });
+});
+function repo(files: Record<string, string>): string {
+  const root = realpathSync(mkdtempSync(join(tmpdir(), "chant-diagrams-")));
+  scratch.push(root);
+  execFileSync("git", ["init", "-q"], { cwd: root });
+  for (const [path, text] of Object.entries(files)) {
+    mkdirSync(dirname(join(root, path)), { recursive: true });
+    writeFileSync(join(root, path), text);
+  }
+  return root;
+}
+
+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 declaration = (diagrams: unknown[], extra: Record<string, unknown> = {}) =>
+  JSON.stringify({ name: "acme", schema: 1, members: [{ name: "docs", dir: "docs", kind: "other", because: "the docs site", diagrams }], ...extra }, null, 2);
+
+/** The findings, less WSP009, which every member of kind other gets. */
+const found = async (root: string) => (await runDeclarationChecks(root, (f) => f, { gather: false })).diagnostics.filter((d) => d.ruleId !== "WSP009");
+
+describe("diagram-source-missing (WSP131) and diagram-render-missing (WSP132)", () => {
+  test("both files present passes", async () => {
+    const root = repo({
+      "chant.workspace.json": declaration([diagram()]),
+      "docs/diagrams/architecture.d2": "x -> y",
+      "docs/diagrams/architecture.svg": "<svg></svg>",
+    });
+    expect(await found(root)).toEqual([]);
+  });
+
+  test("a missing source fails WSP131, and a missing render fails WSP132, each once", async () => {
+    const root = repo({
+      "chant.workspace.json": declaration([diagram()]),
+      "docs/diagrams/architecture.svg": "<svg></svg>",
+    });
+    const d = await found(root);
+    expect(d.map((x) => [x.ruleId, x.code, x.entity])).toEqual([["WSP131", "diagram-source-missing", "docs"]]);
+    expect(d[0].message).toContain("member docs's diagram architecture names the source docs/diagrams/architecture.d2, which does not exist");
+  });
+
+  test("no source (an SVG with none) is never checked for a source", async () => {
+    const root = repo({
+      "chant.workspace.json": declaration([diagram({ source: null })]),
+      "docs/diagrams/architecture.svg": "<svg></svg>",
+    });
+    expect(await found(root)).toEqual([]);
+  });
+
+  test("a missing render fails WSP132", async () => {
+    const root = repo({
+      "chant.workspace.json": declaration([diagram()]),
+      "docs/diagrams/architecture.d2": "x -> y",
+    });
+    const d = await found(root);
+    expect(d.map((x) => [x.ruleId, x.code])).toEqual([["WSP132", "diagram-render-missing"]]);
+  });
+
+  test("the top-level (workspace's own) diagrams are checked too, reported with no entity", async () => {
+    const root = repo({ "chant.workspace.json": declaration([], { diagrams: [diagram({ name: "boundary" })] }), "docs/README.md": "" });
+    const d = await found(root);
+    expect(d.map((x) => [x.ruleId, x.entity])).toEqual([
+      ["WSP131", undefined],
+      ["WSP132", undefined],
+    ]);
+    expect(d[0].message).toContain("the workspace's own diagram boundary names the source");
+  });
+});
+
+describe("diagram-render-drift (WSP133)", () => {
+  const SOURCE = "x -> y\n";
+  const HASH = sha256Hex(Buffer.from(SOURCE, "utf-8"));
+
+  test("no recorded sourceHash: never checked for drift, even when the source changed", async () => {
+    const root = repo({
+      "chant.workspace.json": declaration([diagram()]),
+      "docs/diagrams/architecture.d2": "something else entirely",
+      "docs/diagrams/architecture.svg": "<svg></svg>",
+    });
+    expect(await found(root)).toEqual([]);
+  });
+
+  test("a recorded sourceHash that matches the source passes", async () => {
+    const root = repo({
+      "chant.workspace.json": declaration([diagram({ sourceHash: HASH })]),
+      "docs/diagrams/architecture.d2": SOURCE,
+      "docs/diagrams/architecture.svg": "<svg></svg>",
+    });
+    expect(await found(root)).toEqual([]);
+  });
+
+  test("a source that changed since the recorded hash fails WSP133, without running any renderer", async () => {
+    const root = repo({
+      "chant.workspace.json": declaration([diagram({ sourceHash: HASH })]),
+      "docs/diagrams/architecture.d2": "x -> y -> z\n",
+      "docs/diagrams/architecture.svg": "<svg></svg>",
+    });
+    const d = await found(root);
+    expect(d.map((x) => [x.ruleId, x.code])).toEqual([["WSP133", "diagram-render-drift"]]);
+    expect(d[0].message).toContain("source docs/diagrams/architecture.d2 changed since docs/diagrams/architecture.svg was rendered from it");
+    expect(d[0].message).toContain(`recorded sourceHash ${HASH.slice(0, 12)}`);
+  });
+
+  test("a missing source is left to WSP131; WSP133 finds nothing to compare", async () => {
+    const root = repo({
+      "chant.workspace.json": declaration([diagram({ sourceHash: HASH })]),
+      "docs/diagrams/architecture.svg": "<svg></svg>",
+    });
+    const d = await found(root);
+    expect(d.map((x) => x.ruleId)).toEqual(["WSP131"]);
+  });
+});