@intentius/chant 0.93.0 → 0.95.0

package/src/workspace/box-intent.test.ts

@@ -0,0 +1,205 @@
+/**
+ * A box's intent (#2850): the decision record the box block names, as
+ * `status --json` reports it, as `check` finds it (WSP126, WSP127) and as
+ * `graph --intent` shows it for the box's files.
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { afterAll, describe, expect, test } from "vitest";
+import { cleanScratch, commitAll, contract, REPO, repo } from "./__fixtures__/contract-repo";
+import { constrainsBox, constrainsWorkspace } from "./box-intent";
+import { runDeclarationChecks } from "./checks";
+import { parseDeclaration } from "./declaration";
+import { intentGraph } from "./intent";
+import { parseFrontMatter } from "./records";
+import { workspaceStatus, type StatusDocument } from "./status";
+import statusSchema from "./status.schema.json";
+
+afterAll(cleanScratch);
+
+const REF = join(REPO, "reference-workspace", "decisions");
+const BASE = (() => {
+  const fm = parseFrontMatter(readFileSync(join(REF, "ref-001-how-the-app-is-deployed.md"), "utf-8"));
+  if (!fm.ok) throw new Error(fm.message);
+  return fm.value as Record<string, unknown>;
+})();
+
+const QUESTION = "What is this box for?";
+const CHOICE = { option: "a", reason: "The person who planted the box answered it." };
+const ANSWER = "a chant project with the docker lexicon";
+
+/** A decision record from ref-001: proposed with no choice, or decided by alex. JSON is YAML, so the front matter is JSON. */
+function decision(id: string, state: "proposed" | "decided", constrains: string[]): string {
+  const data = {
+    ...BASE,
+    id,
+    title: `Intent ${id}`,
+    state,
+    question: QUESTION,
+    choice: state === "decided" ? CHOICE : null,
+    rejected: [],
+    evidence: [],
+    decided_by: state === "decided" ? "alex" : null,
+    decided_on: state === "decided" ? "2026-09-26" : null,
+    constrains,
+  };
+  return `---\n${JSON.stringify(data, null, 2)}\n---\n\n# ${id}\n`;
+}
+
+function workspace(box: Record<string, unknown>, records: Record<string, string>, declareKind = true): string {
+  return repo({
+    "chant.workspace.json": JSON.stringify(
+      {
+        name: "acme",
+        schema: 1,
+        members: [{ name: "app", dir: "app", kind: "other", because: "the box", box }],
+        ...(declareKind ? { records: [{ kind: "decisions/decision.kind.mjs" }] } : {}),
+      },
+      null,
+      2,
+    ),
+    "app/server.mjs": "export const port = 8080;\n",
+    "decisions/decision.kind.mjs": readFileSync(join(REF, "decision.kind.mjs"), "utf-8"),
+    "decisions/decision.schema.json": readFileSync(join(REF, "decision.schema.json"), "utf-8"),
+    ...records,
+  });
+}
+
+/**
+ * A workspace shaped like the studio template (studio#112, #2857): the box
+ * block sits on member `box`, the steward and its Ops, and a separate
+ * member `app` is the app the box runs. `records` overlays the decision
+ * files, keyed the same way `repo()` takes every other file.
+ */
+function studioShapedWorkspace(records: Record<string, string>): string {
+  return repo({
+    "chant.workspace.json": JSON.stringify(
+      {
+        name: "acme",
+        schema: 1,
+        members: [
+          { name: "box", dir: "box", kind: "other", because: "the box's steward and its Ops", box: { intent: "box-001" } },
+          { name: "app", dir: "app", kind: "other", because: "the app the box runs" },
+        ],
+        records: [{ kind: "decisions/decision.kind.mjs" }],
+      },
+      null,
+      2,
+    ),
+    "box/ops.mjs": "export const ops = true;\n",
+    "app/server.mjs": "export const port = 8080;\n",
+    "decisions/decision.kind.mjs": readFileSync(join(REF, "decision.kind.mjs"), "utf-8"),
+    "decisions/decision.schema.json": readFileSync(join(REF, "decision.schema.json"), "utf-8"),
+    ...records,
+  });
+}
+
+const intentFindings = async (root: string) =>
+  (await runDeclarationChecks(root)).diagnostics.filter((d) => d.ruleId === "WSP126" || d.ruleId === "WSP127").map((d) => [d.ruleId, d.severity, d.code, d.entity]);
+
+const status = contract(statusSchema);
+async function boxOf(root: string) {
+  const doc: StatusDocument = await workspaceStatus({ cwd: root, env: "prod" });
+  if ("error" in doc) throw new Error(doc.error.message);
+  status.expectValid(doc);
+  return doc.members[0].box;
+}
+
+describe("the box block's intent", () => {
+  test("is parsed into the box declaration, and is null when the block names none", () => {
+    const parse = (box: unknown) =>
+      parseDeclaration(JSON.stringify({ name: "acme", schema: 1, members: [{ name: "app", dir: "app", kind: "other", because: "x", box }] }), "chant.workspace.json").members[0].box;
+    expect(parse({ intent: "box-001" })?.intent).toBe("box-001");
+    expect(parse({})?.intent).toBeNull();
+  });
+
+  test("covers the box through member:, or a path: at, above or inside its directory", () => {
+    const m = { name: "app", dir: "apps/app" };
+    expect(["member:app", "path:apps/app", "path:apps", "path:apps/app/server.mjs"].map((c) => constrainsBox(c, m))).toEqual([true, true, true, true]);
+    expect(["member:web", "path:apps/application", "path:web", "issue:1"].map((c) => constrainsBox(c, m))).toEqual([false, false, false, false]);
+  });
+
+  test("constrainsWorkspace: an entry names a member or path of the workspace whether or not it's the box's own (#2857)", () => {
+    const members = [
+      { name: "box", dir: "box" },
+      { name: "app", dir: "app" },
+    ];
+    expect(["member:box", "member:app", "path:app", "path:box/ops.mjs"].map((c) => constrainsWorkspace(c, members))).toEqual([true, true, true, true]);
+    expect(["member:web", "path:docs", "issue:1"].map((c) => constrainsWorkspace(c, members))).toEqual([false, false, false]);
+    expect(constrainsWorkspace("member:app", [])).toBe(false);
+  });
+});
+
+describe("a box planted as a question", () => {
+  test("a proposed intent reports its question and no answer, and passes the checks", async () => {
+    const root = workspace({ intent: "box-001" }, { "decisions/box-001-what-app-is-for.md": decision("box-001", "proposed", ["member:app"]) });
+    expect((await boxOf(root))?.intent).toEqual({ id: "box-001", state: "proposed", question: QUESTION, choice: null, answer: null, decided_by: null, decided_on: null });
+    expect(await intentFindings(root)).toEqual([]);
+  });
+
+  test("a decided intent reports the answer and who gave it, and graph --intent shows it for the box's files", async () => {
+    const root = workspace({ intent: "box-001" }, { "decisions/box-001-what-app-is-for.md": decision("box-001", "decided", ["member:app"]) });
+    expect((await boxOf(root))?.intent).toEqual({ id: "box-001", state: "decided", question: QUESTION, choice: CHOICE, answer: ANSWER, decided_by: "alex", decided_on: "2026-09-26" });
+    expect(await intentFindings(root)).toEqual([]);
+    commitAll(root, "plant the box");
+    const { doc } = await intentGraph({ cwd: root, region: "app" });
+    if ("error" in doc) throw new Error(doc.error.message);
+    expect(doc.nodes.filter((n) => n.kind === "decision").map((n) => (n.kind === "decision" ? [n.record, n.state, n.decided_by] : []))).toEqual([["box-001", "decided", "alex"]]);
+  });
+
+  test("a decided intent whose choice names an option not in options[] reports a null answer", async () => {
+    const data = { ...BASE, id: "box-001", title: "Intent box-001", state: "decided", question: QUESTION, choice: { option: "z", reason: "no such option" }, rejected: [], evidence: [], decided_by: "alex", decided_on: "2026-09-26", constrains: ["member:app"] };
+    const record = `---\n${JSON.stringify(data, null, 2)}\n---\n\n# box-001\n`;
+    const root = workspace({ intent: "box-001" }, { "decisions/box-001-what-app-is-for.md": record });
+    expect((await boxOf(root))?.intent?.answer).toBeNull();
+  });
+
+  test("an intent no decision record has fails WSP126, and status reports only its id", async () => {
+    const root = workspace({ intent: "box-009" }, { "decisions/box-001-what-app-is-for.md": decision("box-001", "proposed", ["member:app"]) });
+    expect((await boxOf(root))?.intent).toEqual({ id: "box-009", state: null, question: null, choice: null, answer: null, decided_by: null, decided_on: null });
+    expect(await intentFindings(root)).toEqual([["WSP126", "error", "box-intent-unknown", "app"]]);
+    const [d] = (await runDeclarationChecks(root)).diagnostics.filter((x) => x.ruleId === "WSP126");
+    expect(d.message).toContain("no record of decisions/decision.kind.mjs has that id");
+  });
+
+  test("an intent in a workspace that declares no decision kind fails WSP126", async () => {
+    const root = workspace({ intent: "box-001" }, {}, false);
+    const [d] = (await runDeclarationChecks(root)).diagnostics.filter((x) => x.ruleId === "WSP126");
+    expect(d.message).toContain("the declaration names no record kind called decision");
+  });
+
+  test("an intent whose constrains names no member or path of the workspace warns WSP127", async () => {
+    const root = workspace({ intent: "box-001" }, { "decisions/box-001-what-app-is-for.md": decision("box-001", "proposed", ["path:docs"]) });
+    expect(await intentFindings(root)).toEqual([["WSP127", "warning", "box-intent-unconstrained", "app"]]);
+  });
+
+  test("an intent with empty constrains warns WSP127", async () => {
+    const root = studioShapedWorkspace({ "decisions/box-001-what-app-is-for.md": decision("box-001", "proposed", []) });
+    expect(await intentFindings(root)).toEqual([["WSP127", "warning", "box-intent-unconstrained", "box"]]);
+    const d = (await runDeclarationChecks(root)).diagnostics.find((x) => x.ruleId === "WSP127")!;
+    expect(d.message).toContain("whose constrains is empty");
+    expect(d.message).toContain("add member:<name> for the member the intent is about");
+  });
+
+  test("an intent naming an unknown member warns WSP127", async () => {
+    const root = studioShapedWorkspace({ "decisions/box-001-what-app-is-for.md": decision("box-001", "proposed", ["member:web"]) });
+    expect(await intentFindings(root)).toEqual([["WSP127", "warning", "box-intent-unconstrained", "box"]]);
+  });
+
+  test("an intent that constrains the app a box runs passes WSP127, on a workspace shaped like the studio template (#2857)", async () => {
+    const root = studioShapedWorkspace({ "decisions/box-001-what-app-is-for.md": decision("box-001", "proposed", ["member:app"]) });
+    expect(await intentFindings(root)).toEqual([]);
+  });
+
+  test("an intent with a path: entry inside another member's directory passes WSP127 (#2857)", async () => {
+    const root = studioShapedWorkspace({ "decisions/box-001-what-app-is-for.md": decision("box-001", "proposed", ["path:app/server.mjs"]) });
+    expect(await intentFindings(root)).toEqual([]);
+  });
+
+  test("a box with no intent reports null", async () => {
+    const root = workspace({ capabilities: [] }, {});
+    expect((await boxOf(root))?.intent).toBeNull();
+    expect(await intentFindings(root)).toEqual([]);
+  });
+});

package/src/workspace/box-intent.ts

@@ -0,0 +1,159 @@
+/**
+ * A box's intent (#2850): the decision record its box block names.
+ *
+ * A new box starts as a question, and the first answer to it is what the box
+ * is for. That answer is a decision record, so the intent graph, hud and a
+ * box's runtime all read the same thing. The box block names the record's
+ * id in `intent`; the record is looked for among the records of every
+ * declared kind named `decision` (the entry's `name`, or the kind file's
+ * `recordKind.name`), read from the working tree through the same reader as
+ * `chant workspace records`.
+ *
+ * `chant workspace status --json` reports the record's state and answer
+ * under the member's `box.intent`, and `chant workspace check` fails when no
+ * decision record has the id (WSP126) and warns when the record constrains
+ * no member or path of this workspace at all (WSP127, #2857): the member it
+ * names need not be the box's own, since a decision naming another member
+ * can be what the box is for, such as the app it runs.
+ */
+
+import { loadDeclaredKinds, type DeclaredKind } from "./declared-kinds";
+import type { Declaration, Member } from "./declaration";
+import { constraintCovers, isWorkspacePath } from "./record-assets";
+import { workingTree } from "./tree";
+
+/** The declared kind name a box's intent is looked for in. */
+export const INTENT_KIND_NAME = "decision";
+
+/** A box's intent as `status --json` reports it: the record's id, state and answer. */
+export interface BoxIntent {
+  id: string;
+  /** The record's state, such as proposed or decided, or null when no decision record has the id. */
+  state: string | null;
+  question: string | null;
+  /** The record's choice as written, such as `{ option, reason }`, or null while it is proposed. */
+  choice: unknown;
+  /** The chosen option's label, from `options[]`, or null while no option is chosen. */
+  answer: string | null;
+  decided_by: string | null;
+  decided_on: string | null;
+}
+
+/** The decision record a box's intent names, as the checks read it. */
+export interface ResolvedBoxIntent {
+  member: string;
+  id: string;
+  /** The `intent` field's JSON Pointer in the declaration. */
+  pointer: string;
+  /** The record, or null when no decision record has the id. */
+  record: {
+    /** The kind file that holds it, from the workspace root. */
+    kind: string;
+    /** The record file, from the repository root. */
+    path: string;
+    /** The record's constrains entries, as written. */
+    constrains: string[];
+    intent: BoxIntent;
+  } | null;
+  /** Why no record was found when none was, such as no declared decision kind. Empty when one was found. */
+  why: string;
+}
+
+const str = (v: unknown): string | null => (typeof v === "string" ? v : null);
+
+/** The label of `options[]`'s entry whose id is `choice.option`, or null when no option is chosen. */
+function answerOf(choice: unknown, options: unknown): string | null {
+  const chosen = choice && typeof choice === "object" ? (choice as { option?: unknown }).option : null;
+  if (typeof chosen !== "string" || !Array.isArray(options)) return null;
+  const found = options.find((o): o is { id: unknown; label: unknown } => !!o && typeof o === "object" && (o as { id?: unknown }).id === chosen);
+  return found && typeof found.label === "string" ? found.label : null;
+}
+
+/** The intent of `id` with no record: every field but the id null. */
+export function unresolvedIntent(id: string): BoxIntent {
+  return { id, state: null, question: null, choice: null, answer: null, decided_by: null, decided_on: null };
+}
+
+/**
+ * Resolve the intent of every box that names one, reading the records of each
+ * declared decision kind once. `kinds` are the declared kinds already loaded,
+ * when the caller has them. Only the working tree is read.
+ */
+export async function resolveBoxIntents(declaration: Declaration, root: string, kinds?: readonly DeclaredKind[]): Promise<ResolvedBoxIntent[]> {
+  const boxes = declaration.members.filter((m): m is Member & { box: NonNullable<Member["box"]> & { intent: string } } => m.box?.intent != null);
+  if (boxes.length === 0) return [];
+  const loaded = kinds ?? (await loadDeclaredKinds(declaration, workingTree(root), root));
+  const decisionKinds = loaded.filter((k) => (k.declared.name ?? k.kind) === INTENT_KIND_NAME);
+  const found = new Map<string, NonNullable<ResolvedBoxIntent["record"]>>();
+  const problems: string[] = [];
+  const { readRecordsFor } = await import("./records-cli");
+  const { RecordReadError } = await import("./records");
+  for (const k of decisionKinds) {
+    if (k.reason) {
+      problems.push(`${k.declared.path} can't be loaded: ${k.reason.message}`);
+      continue;
+    }
+    try {
+      const read = await readRecordsFor({ kind: k.file, cwd: root, workGaps: false });
+      const field = read.loaded.kind.constrains?.field ?? "constrains";
+      for (const r of read.result.records) {
+        if (r.id === null || found.has(r.id)) continue;
+        const data = r.data ?? {};
+        const constrains = Array.isArray(data[field]) ? (data[field] as unknown[]).filter((c): c is string => typeof c === "string") : [];
+        found.set(r.id, {
+          kind: k.declared.path,
+          path: r.path,
+          constrains,
+          intent: {
+            id: r.id,
+            state: r.state,
+            question: str(data.question),
+            choice: data.choice ?? null,
+            answer: answerOf(data.choice, data.options),
+            decided_by: str(data.decided_by),
+            decided_on: str(data.decided_on),
+          },
+        });
+      }
+    } catch (err) {
+      if (!(err instanceof RecordReadError)) throw err;
+      problems.push(`${k.declared.path} can't be read: ${err.message}`);
+    }
+  }
+  const why =
+    decisionKinds.length === 0
+      ? `the declaration names no record kind called ${INTENT_KIND_NAME}`
+      : `no record of ${decisionKinds.map((k) => k.declared.path).join(" or ")} has that id` + (problems.length > 0 ? ` (${problems.join("; ")})` : "");
+  return boxes.map((m) => {
+    const record = found.get(m.box.intent) ?? null;
+    return { member: m.name, id: m.box.intent, pointer: `${m.box.pointer}/intent`, record, why: record ? "" : why };
+  });
+}
+
+/**
+ * Whether a constrains entry covers something of the box: `member:<name>`, or
+ * a `path:` entry that is the member's directory, a directory above it or a
+ * path inside it.
+ */
+export function constrainsBox(entry: string, member: { name: string; dir: string }): boolean {
+  if (entry === `member:${member.name}`) return true;
+  if (!entry.startsWith("path:")) return false;
+  const path = entry.slice("path:".length);
+  if (!isWorkspacePath(path)) return false;
+  // The root member holds every path.
+  if (member.dir === ".") return true;
+  return constraintCovers(path, member.dir) || constraintCovers(member.dir, path);
+}
+
+/**
+ * Whether a constrains entry names a member or path of this workspace at
+ * all: `member:<name>` for any declared member, or a `path:` entry that is
+ * some member's directory, a directory above it or a path inside it. An
+ * intent's constrains can govern a member other than the one whose box
+ * names it (a box run by one member can be what a decision about another
+ * member's app is for), so this asks only whether the entry is real, not
+ * whether it reaches a particular member.
+ */
+export function constrainsWorkspace(entry: string, members: readonly { name: string; dir: string }[]): boolean {
+  return members.some((m) => constrainsBox(entry, m));
+}

package/src/workspace/box-services.test.ts

@@ -0,0 +1,129 @@
+/**
+ * #2880: a box block declares its services. The declaration reads them, a
+ * `needs` naming no service of the block or forming a cycle, a name given
+ * twice and a second httpPort each fail the read (declaration-invalid), so
+ * `chant workspace check` fails with WSP001, and `readBoxServices` gives the
+ * list of the member a process runs in.
+ */
+
+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 { parseDeclaration, WorkspaceReadError } from "./declaration";
+import { readBoxServices } from "./box-services";
+
+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-services-")));
+  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 declaration = (services: unknown[]) =>
+  JSON.stringify(
+    {
+      name: "acme",
+      schema: 1,
+      members: [
+        { name: "app", dir: "app", kind: "other", because: "the app" },
+        { name: "box", dir: "box", kind: "other", because: "the box's steward and its Ops", box: { services } },
+      ],
+    },
+    null,
+    2,
+  );
+
+const parse = (services: unknown[]) => parseDeclaration(declaration(services), "chant.workspace.json");
+
+/** The error a declaration's read fails with, as its code and message. */
+function readFailure(services: unknown[]): { code: string; message: string; line: number | undefined } {
+  try {
+    parse(services);
+  } catch (err) {
+    if (err instanceof WorkspaceReadError) return { code: err.code, message: err.message, line: err.location?.line };
+    throw err;
+  }
+  throw new Error("the declaration read");
+}
+
+const TWO = [
+  { name: "app", cmd: "${HOME}/box/run-app.sh", duration: "3s", health: "http://127.0.0.1:5173/health" },
+  { name: "hud", cmd: "${HOME}/box/run-daemon.sh", needs: ["app"], httpPort: 8080 },
+];
+
+describe("the services of a box block (#2880)", () => {
+  test("two services, one needing the other, read with every field", () => {
+    expect(parse(TWO).members[1].box?.services).toEqual([
+      { name: "app", cmd: "${HOME}/box/run-app.sh", needs: [], httpPort: null, duration: "3s", health: "http://127.0.0.1:5173/health", optional: false, pointer: "/members/1/box/services/0" },
+      { name: "hud", cmd: "${HOME}/box/run-daemon.sh", needs: ["app"], httpPort: 8080, duration: null, health: null, optional: false, pointer: "/members/1/box/services/1" },
+    ]);
+    expect(parseDeclaration(JSON.stringify({ name: "a", schema: 1, members: [{ name: "b", dir: "b", kind: "other", because: "x", box: {} }] }), "chant.workspace.json").members[0].box?.services).toEqual([]);
+  });
+
+  test("a needs naming no service of the block is declaration-invalid, at the entry", () => {
+    const f = readFailure([TWO[0], { ...TWO[1], needs: ["api"] }]);
+    expect(f.code).toBe("declaration-invalid");
+    expect(f.message).toBe(`member box's box service hud needs "api", which the block does not declare; declared services: app, hud`);
+  });
+
+  test("needs that form a cycle are declaration-invalid, and so is a service that needs itself", () => {
+    const cycle = readFailure([
+      { name: "a", cmd: "a", needs: ["c"] },
+      { name: "b", cmd: "b", needs: ["a"] },
+      { name: "c", cmd: "c", needs: ["b"] },
+    ]);
+    expect(cycle).toMatchObject({ code: "declaration-invalid", message: "member box's box services need each other in a cycle: a -> c -> b -> a" });
+    expect(readFailure([{ name: "a", cmd: "a", needs: ["a"] }]).message).toMatch(/cycle: a -> a$/);
+  });
+
+  test("a name given twice, and a second httpPort, are declaration-invalid", () => {
+    expect(readFailure([TWO[0], { ...TWO[0], cmd: "other" }])).toMatchObject({ code: "declaration-invalid", message: expect.stringMatching(/declares the service app twice; the first is at \/members\/1\/box\/services\/0/) });
+    expect(readFailure([{ ...TWO[0], httpPort: 5173 }, TWO[1]]).message).toMatch(/gives both app \(port 5173\) and hud \(port 8080\) an httpPort/);
+  });
+
+  test("the schema refuses a service with no cmd, an unknown field, a malformed duration or a health that is no URL", () => {
+    expect(readFailure([{ name: "app" }]).code).toBe("declaration-invalid");
+    expect(readFailure([{ ...TWO[0], restart: "always" }]).message).toMatch(/unknown field "restart"/);
+    expect(readFailure([{ ...TWO[0], duration: "3 seconds" }]).code).toBe("declaration-invalid");
+    expect(readFailure([{ ...TWO[0], health: "/health" }]).code).toBe("declaration-invalid");
+  });
+
+  test("chant workspace check passes the valid block and fails the invalid one with WSP001 declaration-invalid", async () => {
+    const good = repo({ "chant.workspace.json": declaration(TWO), "app/.keep": "", "box/.keep": "" });
+    expect((await runDeclarationChecks(good)).diagnostics.filter((d) => d.ruleId === "WSP001")).toEqual([]);
+    const bad = repo({ "chant.workspace.json": declaration([TWO[0], { ...TWO[1], needs: ["api"] }]), "app/.keep": "", "box/.keep": "" });
+    const found = (await runDeclarationChecks(bad)).diagnostics;
+    expect(found.map((d) => [d.ruleId, d.severity, d.code])).toEqual([["WSP001", "error", "declaration-invalid"]]);
+    expect(found[0].message).toMatch(/needs "api", which the block does not declare/);
+  });
+});
+
+describe("readBoxServices (#2880)", () => {
+  test("reads the services of the member whose directory holds the working directory", () => {
+    const root = repo({ "chant.workspace.json": declaration(TWO), "app/.keep": "", "box/ops/.keep": "" });
+    const read = readBoxServices(join(root, "box", "ops"));
+    expect(read.member).toBe("box");
+    expect(read.root).toBe(root);
+    expect(read.services.map((s) => [s.name, s.needs])).toEqual([["app", []], ["hud", ["app"]]]);
+  });
+
+  test("a member with no box block, a directory no member holds, and no workspace are errors", () => {
+    const root = repo({ "chant.workspace.json": declaration(TWO), "app/.keep": "", "box/.keep": "", "elsewhere/.keep": "" });
+    expect(() => readBoxServices(join(root, "app"))).toThrow(/member app \(app\) has no box block/);
+    expect(() => readBoxServices(join(root, "elsewhere"))).toThrow(/no member of the workspace/);
+    const none = repo({ "x/.keep": "" });
+    expect(() => readBoxServices(join(none, "x"))).toThrow(/no chant.workspace.json/);
+  });
+});

package/src/workspace/box-services.ts

@@ -0,0 +1,51 @@
+/**
+ * The services a box declares, read for the process that runs in the box
+ * (#2880).
+ *
+ * A box member's block in the declaration lists the services the box runs
+ * under its supervisor (`BoxService` in `declaration.ts`). The fly lexicon's
+ * `spriteServicesObserve`, `spriteServiceRestart` and `spriteApplyServices`
+ * take `box: true` to read that list instead of one passed to them: the list
+ * of the member whose directory holds the working directory. They import
+ * this module when they run, so it stays small: it finds the workspace root,
+ * reads the declaration from the working tree and picks the member.
+ */
+
+import { realpathSync } from "node:fs";
+import { relative } from "node:path";
+import { findWorkspaceRoot } from "../project-root";
+import { ownerOf, readDeclaration, WorkspaceReadError, type BoxService } from "./declaration";
+import { workingTree } from "./tree";
+
+export type { BoxService } from "./declaration";
+
+/** The box block's services, and whose they are. */
+export interface DeclaredBoxServices {
+  /** The workspace root, absolute. */
+  root: string;
+  /** The member whose directory holds the working directory. */
+  member: string;
+  /** In file order. */
+  services: BoxService[];
+}
+
+/**
+ * The services of the box block of the member whose directory holds `cwd`.
+ * Throws a {@link WorkspaceReadError} when there is no workspace or its
+ * declaration can't be read, and an Error when no member holds `cwd` or the
+ * member has no box block. A block with no `services` gives an empty list.
+ */
+export function readBoxServices(cwd: string = process.cwd()): DeclaredBoxServices {
+  const found = findWorkspaceRoot(cwd);
+  if (!found) {
+    throw new WorkspaceReadError("declaration-missing", `no chant.workspace.json or .jsonc between ${cwd} and the git root, so there is no box block to read services from`);
+  }
+  const root = realpathSync(found.dir);
+  const declaration = readDeclaration(workingTree(root));
+  const path = relative(root, realpathSync(cwd)).split("\\").join("/") || ".";
+  const owner = ownerOf(declaration, [], path);
+  if (!owner || !("member" in owner)) throw new Error(`no member of the workspace at ${root} holds ${cwd}, so there is no box block to read services from`);
+  const m = owner.member;
+  if (!m.box) throw new Error(`member ${m.name} (${m.dir}) has no box block in ${declaration.file}, so it declares no services`);
+  return { root, member: m.name, services: m.box.services };
+}

package/src/workspace/chant-migrations.ts

@@ -26,6 +26,11 @@
  * 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.
+ *
+ * chant itself carries no chud lexicon or chud-shaped code (#2830, once
+ * #2715's proof passed): `chud-lexicon-exit` and its follow-ons are the
+ * retirement tool, not a remaining dependency. They stay until no known repo
+ * still depends on chud, and are removed only in a major version.
  */
 
 import { mkdirSync, rmSync, writeFileSync } from "node:fs";

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 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`.",
+  "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 WSP127 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"
@@ -228,12 +228,14 @@
             "box-isolation-collision",
             "box-isolation-literal",
             "box-fountain-callback-undeclared",
+            "box-intent-unknown",
+            "box-intent-unconstrained",
             "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 WSP125, the box finding (#2726, #2727, #2780). For WSP117, work-acceptance-unmet (#2772). For WSP131 to WSP133, the diagram finding (#2764)."
+          "description": "For WSP001: why the declaration can't be read. For WSP121 to WSP127, the box finding (#2726, #2727, #2780, #2850). For WSP117, work-acceptance-unmet (#2772). For WSP131 to WSP133, the diagram finding (#2764)."
         }
       }
     },
@@ -304,12 +306,14 @@
             "box-isolation-collision",
             "box-isolation-literal",
             "box-fountain-callback-undeclared",
+            "box-intent-unknown",
+            "box-intent-unconstrained",
             "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 WSP125, the box finding (#2726, #2727, #2780). For WSP117, work-acceptance-unmet (#2772). For WSP131 to WSP133, the diagram finding (#2764)."
+          "description": "For WSP001: why the declaration can't be read. For WSP121 to WSP127, the box finding (#2726, #2727, #2780, #2850). For WSP117, work-acceptance-unmet (#2772). For WSP131 to WSP133, the diagram finding (#2764)."
         },
         "reason": {
           "type": "string"

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

@@ -89,7 +89,7 @@ describe("box-credential-declared (WSP121)", () => {
   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/.env": `FOUNTAIN_API_KEY=abc123def456\nPORT=8080\nGIT_TOKEN=\${ACME_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`,
@@ -156,6 +156,8 @@ describe("the box block in the declaration", () => {
     expect(d.members[0].box).toEqual({
       pointer: "/members/0/box",
       isolation: null,
+      intent: null,
+      services: [],
       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" },