@intentius/chant 0.90.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

@@ -10,6 +10,9 @@ import { join } from "node:path";
 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";
 
@@ -35,7 +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]);
+    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, and WSP001, a declaration that can't be read, also carries the declaration's reason code. 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"
@@ -210,7 +210,7 @@
         },
         "entity": {
           "type": "string",
-          "description": "The member or group the finding is about."
+          "description": "The member or group the finding is about. For a box check, the box member."
         },
         "code": {
           "enum": [
@@ -222,9 +222,18 @@
             "reader-too-old",
             "root-chant-required",
             "not-a-git-repository",
-            "revision-unknown"
+            "revision-unknown",
+            "box-credential-declared",
+            "box-capability-unbrokered",
+            "box-isolation-collision",
+            "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."
+          "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)."
         }
       }
     },
@@ -277,7 +286,7 @@
         },
         "entity": {
           "type": "string",
-          "description": "The member or group the finding is about."
+          "description": "The member or group the finding is about. For a box check, the box member."
         },
         "code": {
           "enum": [
@@ -289,9 +298,18 @@
             "reader-too-old",
             "root-chant-required",
             "not-a-git-repository",
-            "revision-unknown"
+            "revision-unknown",
+            "box-credential-declared",
+            "box-capability-unbrokered",
+            "box-isolation-collision",
+            "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."
+          "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/box-isolation.ts

@@ -0,0 +1,68 @@
+/**
+ * The box isolation checks, WSP123 and WSP124 (#2727).
+ *
+ * | Id | Code | Fails when |
+ * |---|---|---|
+ * | WSP123 | `box-isolation-collision` | two boxes on one host, or two ports in one box, resolve to the same port, state path or cookie name |
+ * | WSP124 | `box-isolation-literal` | a host's state root or a box's state entry is a literal machine path |
+ *
+ * Both are fixed errors. A collision means one box signs another's people out
+ * or reads another's identity (arugula-salad/studio#39), and a literal path
+ * means the declaration only holds on one machine. Neither has a case where
+ * turning the check down is the fix.
+ */
+
+import type { WorkspaceCheck } from "../checks";
+import { boxCollisions, boxLiterals } from "../box-isolation";
+
+export const WSP_BOX_COLLISION = "WSP123";
+export const WSP_BOX_LITERAL = "WSP124";
+
+const WHAT = { port: "port", state: "state path", cookie: "cookie name" } as const;
+
+export const BOX_ISOLATION_CHECKS: readonly WorkspaceCheck[] = [
+  {
+    id: WSP_BOX_COLLISION,
+    name: "box-isolation-collision",
+    description: "No two boxes on one host resolve to the same port, state path or cookie name, and no two ports in one box share an offset.",
+    severity: "error",
+    configurable: false,
+    check(ctx) {
+      return boxCollisions(ctx.declaration).map((c) => {
+        const [first, ...rest] = c.holders;
+        const names = c.holders.map((h) => `${h.box}.${h.name}`).join(" and ");
+        const hint =
+          c.what === "port"
+            ? new Set(c.holders.map((h) => h.box)).size > 1
+              ? "; give each box on a host its own slot"
+              : "; give each port in a box its own offset"
+            : "";
+        return {
+          checkId: this.id,
+          severity: this.severity,
+          code: "box-isolation-collision" as const,
+          message: `box-isolation-collision: ${names} on host ${c.host} resolve to the same ${WHAT[c.what]} ${c.value}${hint}`,
+          entity: rest.find((h) => h.box !== first.box)?.box ?? first.box,
+          pointer: (rest[0] ?? first).pointer,
+        };
+      });
+    },
+  },
+  {
+    id: WSP_BOX_LITERAL,
+    name: "box-isolation-literal",
+    description: "No host's state root and no box's state entry is a literal machine path: state paths derive from an environment reference and the member's name.",
+    severity: "error",
+    configurable: false,
+    check(ctx) {
+      return boxLiterals(ctx.declaration).map((l) => ({
+        checkId: this.id,
+        severity: this.severity,
+        code: "box-isolation-literal" as const,
+        message: `box-isolation-literal: ${l.message}`,
+        ...(l.box !== null ? { entity: l.box } : {}),
+        pointer: l.pointer,
+      }));
+    },
+  },
+];

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

@@ -0,0 +1,276 @@
+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 * as ts from "typescript";
+import { afterAll, describe, expect, test } from "vitest";
+import { runDeclarationChecks } from "../checks";
+import { parseDeclaration, WorkspaceReadError } from "../declaration";
+import { gitTree } from "../tree";
+import { fountainBoxCall, isCredentialKey, isSecretReference, literalSecretsInCode, literalSecretsInText } from "./boxes";
+
+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-box-")));
+  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;
+}
+
+// Built at run time so no credential-shaped literal sits in this file.
+const ANTHROPIC_KEY = ["sk", "ant", "api03", "A".repeat(40)].join("-");
+const GITHUB_TOKEN = ["ghp", "B".repeat(36)].join("_");
+
+const BROKERED = { capabilities: [{ name: "inference", broker: "lobby", scope: ["agent", "vault", "conversations", "sandboxes"] }] };
+
+const declaration = (box: unknown, extra: Record<string, unknown> = {}) =>
+  JSON.stringify({ name: "acme", schema: 1, members: [{ name: "spec", dir: "spec", kind: "other", because: "the box's declarations", box, ...extra }] }, null, 2);
+
+/** A chaff-style box declaration: a service whose env has `apiKey`. */
+const spec = (apiKey: string) => `import { Service, Capability } from "@intentius/chant-lexicon-chaff";
+
+export const app = new Service({
+  start: ["node", "app/server.mjs"],
+  env: {
+    HUD_SRC: "\${HOME}/alecraso/hud-live",
+    ANTHROPIC_API_KEY: ${JSON.stringify(apiKey)},
+  },
+});
+
+export const inference = new Capability({ provider: "brokered", credential: "$INFERENCE_TOKEN", endpoint: "$INFERENCE_URL" });
+`;
+
+/** 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("box-credential-declared (WSP121)", () => {
+  test("a literal API key in a service's env fails the box", async () => {
+    const root = repo({ "chant.workspace.json": declaration(BROKERED), "spec/box.ts": spec(ANTHROPIC_KEY) });
+    const d = await found(root);
+    expect(d.map((x) => [x.ruleId, x.code, x.entity, x.file, x.line])).toEqual([["WSP121", "box-credential-declared", "spec", "spec/box.ts", 7]]);
+    expect(d[0].message).toContain("an Anthropic API key");
+    // The message names what was found, never the value.
+    expect(d[0].message).not.toContain(ANTHROPIC_KEY);
+  });
+
+  test("the same box with the key as a reference and the capability brokered passes", async () => {
+    for (const ref of ["${ANTHROPIC_API_KEY}", "$ANTHROPIC_API_KEY", "op://box/anthropic/key", "bws://0f5b/anthropic", "infisical:///dev/ANTHROPIC_API_KEY"]) {
+      const root = repo({ "chant.workspace.json": declaration(BROKERED), "spec/box.ts": spec(ref) });
+      expect(await found(root), ref).toEqual([]);
+    }
+  });
+
+  test("a literal of no known shape under a credential key fails, and so does a vault secret's literal value", async () => {
+    const root = repo({
+      "chant.workspace.json": declaration(BROKERED),
+      "spec/box.ts": `export const box = Box({
+  envVars: { GITHUB_TOKEN: "hunter2hunter2" },
+  vault: { secrets: [{ key: "STUDIO_SECRET", value: "plain-text" }, { key: "OK", value: "\${STUDIO_SECRET}" }] },
+  repo: { url: "https://github.com/x/y", secretKey: "GIT_TOKEN" },
+  names: { credential: "INFERENCE_TOKEN", tokenPath: "/run/secrets/t", token: "~/box/llm-token", endpoint: { apiKey: "https://broker.local/key" } },
+  process: { token: process.env.TOKEN! },
+});
+`,
+    });
+    const d = await found(root);
+    expect(d.map((x) => `${x.line}: ${x.message.split(" holds ")[1].split(", and")[0]}`)).toEqual([
+      "2: a literal value for GITHUB_TOKEN",
+      "3: a literal vault secret value for STUDIO_SECRET",
+    ]);
+  });
+
+  test("an env file and a shell script in the box's directory are read too; prose only for credential shapes", async () => {
+    const root = repo({
+      "chant.workspace.json": declaration(BROKERED),
+      "spec/.env": `FOUNTAIN_API_KEY=abc123def456\nPORT=8080\nGIT_TOKEN=\${CHUD_GIT_TOKEN}\n`,
+      "spec/run.sh": `#!/bin/sh\nexport GITHUB_TOKEN=${GITHUB_TOKEN}\necho "password=$GIT_TOKEN"\nTOKEN=$1\ntoken=~/box/llm-token\nSECRET=/run/secrets/x\n`,
+      "spec/README.md": `Token: rotate it monthly.\n`,
+      "spec/node_modules/pkg/index.js": `export const k = ${JSON.stringify(ANTHROPIC_KEY)};\n`,
+    });
+    const d = await found(root);
+    expect(d.map((x) => `${x.file}:${x.line}`)).toEqual(["spec/.env:1", "spec/run.sh:2"]);
+  });
+
+  test("a member without a box block is not read, and a box's finding can't be suppressed", async () => {
+    const plain = repo({
+      "chant.workspace.json": JSON.stringify({ name: "acme", schema: 1, members: [{ name: "spec", dir: "spec", kind: "other", because: "x" }] }),
+      "spec/box.ts": spec(ANTHROPIC_KEY),
+    });
+    expect(await found(plain)).toEqual([]);
+    const suppressed = repo({
+      "chant.workspace.json": declaration(BROKERED, { suppress: [{ check: "WSP121", because: "a test key" }] }),
+      "spec/box.ts": spec(ANTHROPIC_KEY),
+    });
+    expect((await found(suppressed)).map((x) => x.ruleId).sort()).toEqual(["WSP011", "WSP121"]);
+  });
+
+  test("under --at the revision's files are read", async () => {
+    const root = repo({ "chant.workspace.json": declaration(BROKERED), "spec/box.ts": spec(ANTHROPIC_KEY) });
+    execFileSync("git", ["add", "-A"], { cwd: root });
+    execFileSync("git", ["-c", "user.email=t@t", "-c", "user.name=t", "commit", "-qm", "box"], { cwd: root });
+    const commit = execFileSync("git", ["rev-parse", "HEAD"], { cwd: root, encoding: "utf8" }).trim();
+    writeFileSync(join(root, "spec/box.ts"), spec("${ANTHROPIC_API_KEY}"));
+    expect(await found(root)).toEqual([]);
+    const at = await runDeclarationChecks(root, (f) => f, { tree: gitTree(root, commit) });
+    expect(at.diagnostics.map((x) => x.ruleId).filter((id) => id !== "WSP009")).toEqual(["WSP121"]);
+  });
+});
+
+describe("box-capability-unbrokered (WSP122)", () => {
+  test("a capability with no broker fails, at the capability", async () => {
+    const root = repo({
+      "chant.workspace.json": declaration({ capabilities: [{ name: "fountain", broker: "lobby", scope: ["agent"] }, { name: "inference" }] }),
+      "spec/box.ts": spec("${ANTHROPIC_API_KEY}"),
+    });
+    const d = await found(root);
+    expect(d.map((x) => [x.ruleId, x.code, x.entity])).toEqual([["WSP122", "box-capability-unbrokered", "spec"]]);
+    expect(d[0].message).toContain("needs inference and names no broker");
+  });
+
+  test("it can be turned down, since a box may be moving to a broker", async () => {
+    const root = repo({
+      "chant.workspace.json": JSON.stringify({
+        name: "acme",
+        schema: 1,
+        checks: { WSP122: "warning" },
+        members: [{ name: "spec", dir: "spec", kind: "other", because: "x", box: { capabilities: [{ name: "inference" }] } }],
+      }),
+      "spec/box.ts": "",
+    });
+    const report = await runDeclarationChecks(root, (f) => f, { gather: false });
+    expect(report.ok).toBe(true);
+    expect(report.diagnostics.filter((x) => x.ruleId !== "WSP009").map((x) => `${x.ruleId}:${x.severity}`)).toEqual(["WSP122:warning"]);
+  });
+});
+
+describe("the box block in the declaration", () => {
+  test("parses, with the broker null and the scope empty when left out", () => {
+    const d = parseDeclaration(declaration({ capabilities: [{ name: "fountain", broker: "lobby", scope: ["agent", "vault"] }, { name: "inference" }] }), "chant.workspace.json");
+    expect(d.members[0].box).toEqual({
+      pointer: "/members/0/box",
+      isolation: null,
+      capabilities: [
+        { name: "fountain", broker: "lobby", scope: ["agent", "vault"], pointer: "/members/0/box/capabilities/0" },
+        { name: "inference", broker: null, scope: [], pointer: "/members/0/box/capabilities/1" },
+      ],
+    });
+    expect(parseDeclaration(JSON.stringify({ name: "a", schema: 1, members: [{ name: "m", dir: "m", kind: "chant" }] }), "chant.workspace.json").members[0].box).toBeNull();
+  });
+
+  test("a capability named twice, or an unknown field, is declaration-invalid", () => {
+    const twice = () => parseDeclaration(declaration({ capabilities: [{ name: "fountain", broker: "lobby" }, { name: "fountain", broker: "door" }] }), "chant.workspace.json");
+    expect(twice).toThrow(WorkspaceReadError);
+    expect(twice).toThrow(/lists the capability fountain twice/);
+    expect(() => parseDeclaration(declaration({ capabilities: [{ name: "fountain", credential: "x" }] }), "chant.workspace.json")).toThrow(/unknown field "credential"/);
+  });
+});
+
+describe("what counts as a literal secret", () => {
+  test("references are not secrets", () => {
+    for (const v of ["${X}", "${HOME}/.config", "$X", "$1", "$(cat f)", "op://v/i/f", "bws://id", "infisical:///dev/X", "{{chant:name}}", ""]) {
+      expect(isSecretReference(v), v).toBe(true);
+    }
+    for (const v of ["hunter2", "abc${", "sk-live"]) expect(isSecretReference(v), v).toBe(v === "abc${");
+  });
+
+  test("keys that name a credential, and keys that name where one is", () => {
+    for (const k of ["API_KEY", "ANTHROPIC_API_KEY", "GITHUB_TOKEN", "apiKey", "token", "credential", "password", "AWS_SECRET_ACCESS_KEY", "authToken", "clientSecret"]) {
+      expect(isCredentialKey(k), k).toBe(true);
+    }
+    for (const k of ["secretKey", "secret_key", "TOKEN_FILE", "tokenHash", "HUD_IDENTITY_PATH", "CHAFF_AGENT_VAULT", "key", "value", "maxTokens"]) {
+      expect(isCredentialKey(k), k).toBe(false);
+    }
+  });
+
+  test("a credential shape is found anywhere in code, and not in a template with a substitution", () => {
+    const code = `const a = [${JSON.stringify(GITHUB_TOKEN)}];\nconst b = \`\${prefix}${"x".repeat(3)}\`;\n`;
+    expect(literalSecretsInCode(code, "a.ts", ts.ScriptKind.TS).map((s) => [s.line, s.what])).toEqual([[1, "a GitHub token"]]);
+    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();
+  });
+});