@intentius/chant 0.101.0 → 0.102.0

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

@@ -0,0 +1,320 @@
+/**
+ * #3146, ws-077: the factory and listing on a box block, the protected paths
+ * in writeScope, and whether a workspace is plantable.
+ *
+ * The declaration reads the fields with their defaults filled in, and a
+ * factory that names an undeclared member, or a second factory, fails the
+ * read (declaration-invalid, so check fails with WSP001). Everything is
+ * opt-in: a records-only workspace and an infra workspace that declares a
+ * factory with no box services both read and check cleanly. `status --json`
+ * and `graph --json` print the factory, the listing (with the cover's hash)
+ * and `plantable`; `check --changes` reports a write to a protected path with
+ * write-scope-protected, unless the entry's except allows the change.
+ */
+
+import { createHash } from "node:crypto";
+import { writeFileSync } from "node:fs";
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { cleanScratch, commitAll, contract, git, repo, writeFiles } from "./__fixtures__/contract-repo";
+import { agentSession } from "./agent-cli";
+import agentSchema from "./agent.schema.json";
+import { plantability } from "./box-factory";
+import { checkChanges, type ChangesDocument } from "./changes";
+import changesSchema from "./changes.schema.json";
+import { runDeclarationChecks } from "./checks";
+import { parseDeclaration, WorkspaceReadError, type Declaration } from "./declaration";
+import { workspaceGraph } from "./graph-cli";
+import graphSchema from "./graph.schema.json";
+import { workspaceStatus } from "./status";
+import statusSchema from "./status.schema.json";
+import { judgePath, onlyKeysChanged, protectedEntry, resolveWriter } from "./write-scope";
+import { emptyPolicy } from "./trust/policy";
+
+afterAll(cleanScratch);
+
+type Json = Record<string, unknown>;
+
+const FACTORY = {
+  builds: ["studio"],
+  check: "npm run --silent check && npm test --silent",
+  checks: "checks",
+  builders: "steward",
+  publish: { repo: "arugula-salad/studio", branchPrefix: "box/" },
+};
+
+const SERVICES = [{ name: "app", cmd: "node app.mjs", health: "http://127.0.0.1:5173/health" }];
+
+function declaration(over: { box?: Json; members?: Json[]; writeScope?: Json; agents?: Json[] } = {}): Json {
+  return {
+    name: "studio",
+    schema: 1,
+    members: over.members ?? [
+      { name: "studio", dir: ".", kind: "other", because: "the repo itself" },
+      { name: "steward", dir: "steward", kind: "other", because: "the box's steward", box: over.box ?? { services: SERVICES, factory: FACTORY } },
+    ],
+    ...(over.writeScope ? { writeScope: over.writeScope } : {}),
+    ...(over.agents ? { agents: over.agents } : {}),
+  };
+}
+
+const parse = (doc: Json): Declaration => parseDeclaration(JSON.stringify(doc, null, 2), "chant.workspace.json");
+
+/** The error a declaration's read fails with, and the line of the file it points at. */
+function readFailure(doc: Json): { code: string; message: string; at: string | undefined } {
+  const text = JSON.stringify(doc, null, 2);
+  try {
+    parseDeclaration(text, "chant.workspace.json");
+  } catch (err) {
+    if (err instanceof WorkspaceReadError) return { code: err.code, message: err.message, at: err.location ? text.split("\n")[err.location.line - 1]?.trim() : undefined };
+    throw err;
+  }
+  throw new Error("the declaration read");
+}
+
+describe("the factory on a box block (#3146)", () => {
+  test("reads with its defaults filled in", () => {
+    const box = parse(declaration()).members[1].box!;
+    expect(box.factory).toEqual({
+      builds: ["studio"],
+      check: { run: "npm run --silent check && npm test --silent", kind: "test" },
+      checks: "checks",
+      builders: "steward",
+      publish: { forge: "github", repo: "arugula-salad/studio", base: null, branchPrefix: "box/", head: null },
+      pointer: "/members/1/box/factory",
+    });
+    expect(box.listing).toBeNull();
+  });
+
+  test("a check says what it is, a publish target names a base and a fork, and the branch prefix defaults to the work branch", () => {
+    const f = parse(
+      declaration({
+        box: { factory: { builds: ["studio", "steward"], check: { run: "chant build && chant lint", kind: "lint" }, publish: { repo: "acme/infra", base: "main", head: "alex/infra" } } },
+      }),
+    ).members[1].box!.factory!;
+    expect(f.builds).toEqual(["studio", "steward"]);
+    expect(f.check).toEqual({ run: "chant build && chant lint", kind: "lint" });
+    expect(f.publish).toEqual({ forge: "github", repo: "acme/infra", base: "main", branchPrefix: "chant/work/", head: "alex/infra" });
+    expect(f.checks).toBeNull();
+    expect(f.builders).toBeNull();
+  });
+
+  test("builds must name a declared member", () => {
+    const failure = readFailure(declaration({ box: { factory: { builds: ["app"] } } }));
+    expect(failure.code).toBe("declaration-invalid");
+    expect(failure.message).toContain('the factory builds "app", which is not a declared member');
+    expect(failure.at).toBe('"app"');
+  });
+
+  test("builders must name a declared member", () => {
+    const failure = readFailure(declaration({ box: { factory: { builds: ["studio"], builders: "delivery" } } }));
+    expect(failure.message).toContain('the factory\'s builders names "delivery"');
+    expect(failure.at).toBe('"builders": "delivery"');
+  });
+
+  test("a workspace has one factory", () => {
+    const failure = readFailure(
+      declaration({
+        members: [
+          { name: "a", dir: "a", kind: "other", because: "a", box: { factory: { builds: ["a"] } } },
+          { name: "b", dir: "b", kind: "other", because: "b", box: { factory: { builds: ["b"] } } },
+        ],
+      }),
+    );
+    expect(failure.message).toContain("members a and b both declare a factory");
+    expect(failure.at).toBe('"factory": {');
+  });
+
+  test("the schema refuses a factory without builds, an unknown check kind, a bad repo and an unknown field", () => {
+    expect(readFailure(declaration({ box: { factory: {} } })).code).toBe("declaration-invalid");
+    expect(readFailure(declaration({ box: { factory: { builds: ["studio"], check: { run: "x", kind: "smoke" } } } })).code).toBe("declaration-invalid");
+    expect(readFailure(declaration({ box: { factory: { builds: ["studio"], publish: { repo: "not a repo" } } } })).code).toBe("declaration-invalid");
+    expect(readFailure(declaration({ box: { factory: { builds: ["studio"], app: "studio" } } })).message).toContain('unknown field "app"');
+    // An x- field is still allowed, so a runtime can carry its own knobs beside chant's.
+    expect(parse(declaration({ box: { factory: { builds: ["studio"], "x-studio": { budget: 3 } } } })).members[1].box!.factory!.builds).toEqual(["studio"]);
+  });
+});
+
+describe("the listing on a box block (#3146)", () => {
+  test("reads with its defaults: listed, empty title and line, no cover", () => {
+    expect(parse(declaration({ box: { listing: {} } })).members[1].box!.listing).toEqual({ published: true, title: "", line: "", cover: null });
+    expect(parse(declaration({ box: { listing: { published: false, title: "Fern", line: "A garden planner", cover: "steward/cover.png" } } })).members[1].box!.listing).toEqual({
+      published: false,
+      title: "Fern",
+      line: "A garden planner",
+      cover: "steward/cover.png",
+    });
+  });
+
+  test("a title over 60 characters, a line over 140 and a control character are refused", () => {
+    expect(readFailure(declaration({ box: { listing: { title: "x".repeat(61) } } })).code).toBe("declaration-invalid");
+    expect(readFailure(declaration({ box: { listing: { line: "x".repeat(141) } } })).code).toBe("declaration-invalid");
+    expect(readFailure(declaration({ box: { listing: { title: "two\nlines" } } })).code).toBe("declaration-invalid");
+  });
+});
+
+describe("plantable (#3146)", () => {
+  test("exactly one member's box block declares services", () => {
+    expect(plantability(parse(declaration()))).toEqual({ plantable: true, box: "steward", reason: null });
+  });
+
+  test("an infra workspace with a factory and no box services reads and checks cleanly, and isn't plantable (#3174)", async () => {
+    const doc = declaration({
+      members: [
+        { name: "estate", dir: "estate", kind: "other", because: "terraform" },
+        { name: "ops", dir: "ops", kind: "other", because: "the steward", box: { factory: { builds: ["estate"], check: { run: "terraform plan", kind: "plan" }, publish: { repo: "acme/estate" } } } },
+      ],
+    });
+    const d = parse(doc);
+    expect(plantability(d)).toMatchObject({ plantable: false, box: null, reason: { code: "box-none" } });
+    const root = repo({ "chant.workspace.json": JSON.stringify(doc), "estate/main.tf": "", "ops/README.md": "" });
+    const { diagnostics } = await runDeclarationChecks(root);
+    expect(diagnostics.filter((x) => x.severity === "error")).toEqual([]);
+  });
+
+  test("a records-only workspace isn't plantable, and two boxes with services aren't either", () => {
+    expect(plantability(parse({ name: "notes", schema: 1, members: [] }))).toMatchObject({ plantable: false, reason: { code: "box-none" } });
+    const two = declaration({
+      members: [
+        { name: "a", dir: "a", kind: "other", because: "a", box: { services: SERVICES } },
+        { name: "b", dir: "b", kind: "other", because: "b", box: { services: SERVICES } },
+      ],
+    });
+    expect(plantability(parse(two))).toMatchObject({ plantable: false, box: null, reason: { code: "box-several", message: expect.stringContaining("a, b") } });
+  });
+});
+
+describe("protected paths in writeScope (#3146)", () => {
+  const scope = {
+    agent: {
+      protected: ["ops", "decisions/**", { path: "chant.workspace.json", except: ["diagrams"] }],
+    },
+  };
+  const d = parse(declaration({ writeScope: scope, agents: [{ name: "builder", member: "studio" }] }));
+  const writer = resolveWriter(d, emptyPolicy(null), { agent: "builder" });
+
+  test("read in file order, with except empty for a glob", () => {
+    expect(d.writeScope!.agent!.protected).toEqual([
+      { path: "ops", except: [] },
+      { path: "decisions/**", except: [] },
+      { path: "chant.workspace.json", except: ["diagrams"] },
+    ]);
+  });
+
+  test("an entry covers the files it matches and everything under a directory it matches", () => {
+    expect(protectedEntry(d.writeScope!.agent!.protected, "ops/factory/guard.mjs")?.path).toBe("ops");
+    expect(protectedEntry(d.writeScope!.agent!.protected, "decisions/ws-001.md")?.path).toBe("decisions/**");
+    expect(protectedEntry(d.writeScope!.agent!.protected, "opsy.md")).toBeNull();
+  });
+
+  test("a write to a protected path is out of scope, even in the session's own member", () => {
+    expect(judgePath(d, writer, "src/server.mjs")).toEqual({ ok: true });
+    expect(judgePath(d, writer, "ops/factory/guard.mjs")).toMatchObject({ ok: false, code: "write-scope-protected", message: expect.stringContaining("writeScope.agent.protected lists ops") });
+  });
+
+  test("except lets a JSON file change only in the keys it names", () => {
+    const before = JSON.stringify({ name: "studio", diagrams: [] });
+    const onlyDiagrams = JSON.stringify({ name: "studio", diagrams: [{ name: "flow" }] });
+    const alsoName = JSON.stringify({ name: "other", diagrams: [{ name: "flow" }] });
+    expect(onlyKeysChanged(before, onlyDiagrams, ["diagrams"])).toBe(true);
+    expect(onlyKeysChanged(before, alsoName, ["diagrams"])).toBe(false);
+    expect(onlyKeysChanged(null, onlyDiagrams, ["diagrams"])).toBe(false);
+    expect(onlyKeysChanged("not json", onlyDiagrams, ["diagrams"])).toBe(false);
+    expect(judgePath(d, writer, "chant.workspace.json", { before: () => before, after: () => onlyDiagrams })).toEqual({ ok: true });
+    expect(judgePath(d, writer, "chant.workspace.json", { before: () => before, after: () => alsoName })).toMatchObject({
+      ok: false,
+      code: "write-scope-protected",
+      message: expect.stringContaining("outside the top-level keys it allows (diagrams)"),
+    });
+    // Without the change in hand, an except entry can't be satisfied.
+    expect(judgePath(d, writer, "chant.workspace.json")).toMatchObject({ ok: false, code: "write-scope-protected" });
+  });
+});
+
+describe("the read contract: status, graph, agent and check --changes (#3146)", () => {
+  const status = contract(statusSchema);
+  const graph = contract(graphSchema);
+  const agent = contract(agentSchema);
+  const changes = contract(changesSchema);
+  const cover = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 1, 2, 3]);
+  const doc = declaration({
+    box: { services: SERVICES, factory: FACTORY, listing: { title: "Studio", line: "Where boxes are planted", cover: "steward/cover.png" } },
+    writeScope: { agent: { protected: ["ops", { path: "chant.workspace.json", except: ["diagrams"] }] } },
+    agents: [{ name: "builder", member: "studio" }],
+  });
+  let root: string;
+
+  beforeAll(() => {
+    root = repo({ "chant.workspace.json": `${JSON.stringify(doc, null, 2)}\n`, "steward/README.md": "the steward\n", "ops/guard.mjs": "export {};\n", "server.mjs": "export {};\n" });
+    writeFileSync(`${root}/steward/cover.png`, cover);
+    git(root, "add", "-A");
+    git(root, "commit", "-q", "-m", "the workspace");
+    git(root, "branch", "-M", "main");
+  });
+
+  test("status --json prints the factory, the listing with the cover's hash, and plantable", async () => {
+    const out = await workspaceStatus({ cwd: root, env: "prod" });
+    status.expectValid(out);
+    if ("error" in out) throw new Error(out.error.message);
+    expect(out.plantable).toEqual({ plantable: true, box: "steward", reason: null });
+    const box = out.members.find((m) => m.name === "steward")!.box!;
+    expect(box.factory).toEqual({
+      builds: ["studio"],
+      check: { run: "npm run --silent check && npm test --silent", kind: "test" },
+      checks: "checks",
+      builders: "steward",
+      publish: { forge: "github", repo: "arugula-salad/studio", base: null, branchPrefix: "box/", head: null },
+    });
+    expect(box.listing).toEqual({
+      published: true,
+      title: "Studio",
+      line: "Where boxes are planted",
+      cover: { path: "steward/cover.png", sha256: createHash("sha256").update(cover).digest("hex") },
+    });
+  });
+
+  test("graph --json prints them too, at a revision with --at", async () => {
+    const head = git(root, "rev-parse", "HEAD");
+    for (const at of [undefined, head]) {
+      const { doc: out } = await workspaceGraph({ cwd: root, at });
+      graph.expectValid(out);
+      if ("error" in out) throw new Error(out.error.message);
+      expect(out.plantable).toMatchObject({ plantable: true, box: "steward" });
+      const byName = Object.fromEntries(out.members.map((m) => [m.name, m.box]));
+      expect(byName.studio).toBeNull();
+      expect(byName.steward?.factory?.builds).toEqual(["studio"]);
+      expect(byName.steward?.listing?.cover?.sha256).toBe(createHash("sha256").update(cover).digest("hex"));
+    }
+  });
+
+  test("workspace agent lists the protected paths", async () => {
+    const out = await agentSession({ cwd: root, name: "builder" });
+    agent.expectValid(out);
+    if ("error" in out) throw new Error(out.error.message);
+    expect(out.scope.protected).toEqual([
+      { path: "ops", except: [] },
+      { path: "chant.workspace.json", except: ["diagrams"] },
+    ]);
+  });
+
+  test("check --changes reports a write to a protected path, and lets an excepted key change", async () => {
+    git(root, "checkout", "-q", "-b", "work");
+    const trailer = "\n\nChant-Agent: builder";
+    writeFiles(root, { "server.mjs": "export const port = 1;\n" });
+    const ok = commitAll(root, `app: a port${trailer}`);
+    writeFiles(root, { "chant.workspace.json": `${JSON.stringify({ ...doc, diagrams: [] }, null, 2)}\n` });
+    const excepted = commitAll(root, `a diagram${trailer}`);
+    writeFiles(root, { "ops/guard.mjs": "export const off = true;\n" });
+    const guard = commitAll(root, `the steward${trailer}`);
+    writeFiles(root, { "chant.workspace.json": `${JSON.stringify({ ...doc, name: "renamed", diagrams: [] }, null, 2)}\n` });
+    const renamed = commitAll(root, `rename${trailer}`);
+    const { doc: out } = (await checkChanges({ cwd: root, range: "main..work" })) as { doc: Exclude<ChangesDocument, { error: unknown }> };
+    changes.expectValid(out);
+    const found = out.scope!.findings.map((f) => [f.commit, f.code, f.path]);
+    expect(found).toEqual([
+      [guard, "write-scope-protected", "ops/guard.mjs"],
+      [renamed, "write-scope-protected", "chant.workspace.json"],
+    ]);
+    expect(found.map(([c]) => c)).not.toContain(ok);
+    expect(found.map(([c]) => c)).not.toContain(excepted);
+  });
+});

package/src/workspace/box-factory.ts

@@ -0,0 +1,103 @@
+/**
+ * The factory and listing on a box block, and whether a workspace is
+ * plantable (#3146, ws-077), as `chant workspace status --json` and
+ * `chant workspace graph --json` print them.
+ *
+ * Every field here is opt-in (#3174): a workspace with no box, or a box with
+ * no `factory` or `listing`, reads as `null` for each, and plantability is a
+ * fact about the declaration, never a check that fails. A records-only
+ * workspace and an infra workspace with a factory and no box services both
+ * read and check cleanly; they just aren't plantable.
+ */
+
+import { createHash } from "node:crypto";
+import type { BoxFactory, BoxListing, Declaration, FactoryCheckKind } from "./declaration";
+import type { ReasonCode } from "./reason-codes";
+import type { WorkspaceTree } from "./tree";
+
+/** Why a workspace isn't plantable. Closed. */
+export const PLANTABLE_REASON_CODES = ["box-none", "box-several"] as const satisfies readonly ReasonCode[];
+export type PlantableReasonCode = (typeof PLANTABLE_REASON_CODES)[number];
+
+/**
+ * Whether a host such as a studio's planter can plant the workspace as one
+ * box: exactly one member's box block declares services. `box` names that
+ * member, and is null when the workspace isn't plantable.
+ */
+export interface Plantable {
+  plantable: boolean;
+  box: string | null;
+  reason: { code: PlantableReasonCode; message: string } | null;
+}
+
+/** A box's factory as the read contract prints it: every field present, defaults filled in. */
+export interface FactoryView {
+  builds: string[];
+  check: { run: string; kind: FactoryCheckKind } | null;
+  checks: string | null;
+  builders: string | null;
+  publish: { forge: "github"; repo: string; base: string | null; branchPrefix: string; head: string | null } | null;
+}
+
+/** A box's listing as the read contract prints it, with the cover's hash when the file is there. */
+export interface ListingView {
+  published: boolean;
+  title: string;
+  line: string;
+  /** The cover file from the workspace root and the sha256 of its bytes, null when the file can't be read; null when none is declared. */
+  cover: { path: string; sha256: string | null } | null;
+}
+
+/** Whether the declaration is plantable (#3146): exactly one member's box block declares services. */
+export function plantability(declaration: Declaration): Plantable {
+  const boxes = declaration.members.filter((m) => (m.box?.services.length ?? 0) > 0);
+  if (boxes.length === 1) return { plantable: true, box: boxes[0].name, reason: null };
+  if (boxes.length === 0) {
+    return { plantable: false, box: null, reason: { code: "box-none", message: "no member's box block declares services, so there is no box to plant" } };
+  }
+  return {
+    plantable: false,
+    box: null,
+    reason: { code: "box-several", message: `members ${boxes.map((m) => m.name).join(", ")} each declare box services, and a planted workspace runs one box` },
+  };
+}
+
+export function factoryView(f: BoxFactory | null): FactoryView | null {
+  if (f === null) return null;
+  return {
+    builds: [...f.builds],
+    check: f.check === null ? null : { ...f.check },
+    checks: f.checks,
+    builders: f.builders,
+    publish: f.publish === null ? null : { ...f.publish },
+  };
+}
+
+/** The listing, hashing the cover through `read` (bytes, or null when the file can't be read). */
+export function listingView(l: BoxListing | null, read: (path: string) => Uint8Array | null): ListingView | null {
+  if (l === null) return null;
+  let cover: ListingView["cover"] = null;
+  if (l.cover !== null) {
+    const bytes = read(l.cover);
+    cover = { path: l.cover, sha256: bytes === null ? null : createHash("sha256").update(bytes).digest("hex") };
+  }
+  return { published: l.published, title: l.title, line: l.line, cover };
+}
+
+/** A reader of a file's bytes in `tree` for {@link listingView}: null when the file can't be read. */
+export function treeBytes(tree: WorkspaceTree): (path: string) => Uint8Array | null {
+  return (path) => {
+    try {
+      if (tree.stat(path) !== "file") return null;
+      return tree.bytes ? tree.bytes(path) : new TextEncoder().encode(tree.read(path));
+    } catch {
+      return null;
+    }
+  };
+}
+
+/** The box fields the graph prints on a member (#3146): its factory and listing, or null when the member's box declares neither. */
+export function graphBox(box: { factory: BoxFactory | null; listing: BoxListing | null } | null, tree: WorkspaceTree): { factory: FactoryView | null; listing: ListingView | null } | null {
+  if (box === null || (box.factory === null && box.listing === null)) return null;
+  return { factory: factoryView(box.factory), listing: listingView(box.listing, treeBytes(tree)) };
+}

package/src/workspace/changes.schema.json

@@ -498,14 +498,9 @@
         "restricted": {
           "type": "array",
           "items": {
-            "enum": [
-              "human",
-              "agent",
-              "runner",
-              "service"
-            ]
+            "$ref": "#/$defs/principalClass"
           },
-          "description": "The principal classes with a writeScope entry, and agent when any agent session is declared."
+          "description": "The principal classes with a writeScope entry, and agent when any agent session is declared: the core classes first, then domain classes in pin order, then any class writeScope names that no pinned package supplies."
         },
         "agents": {
           "type": "array",
@@ -528,6 +523,11 @@
         }
       }
     },
+    "principalClass": {
+      "type": "string",
+      "pattern": "^(?!x-)[a-z][a-z0-9-]{0,39}$",
+      "description": "A principal class: human, agent, runner or service, or a domain class a pinned package supplies at its ./workspace-principals subpath (#3080). A reader that knows only the core classes treats any other name as a domain class."
+    },
     "scopeCommit": {
       "type": "object",
       "required": [
@@ -556,12 +556,7 @@
           "description": "Whether principal is an attested signer."
         },
         "class": {
-          "enum": [
-            "human",
-            "agent",
-            "runner",
-            "service"
-          ],
+          "$ref": "#/$defs/principalClass",
           "description": "agent for a commit naming a session with a Chant-Agent trailer or by a principal a session lists; otherwise the class the principal's role grants at base give."
         },
         "agent": {
@@ -599,6 +594,8 @@
           "enum": [
             "write-scope-member",
             "write-scope-kind",
+            "write-scope-class-unknown",
+            "write-scope-protected",
             "agent-unknown"
           ]
         },
@@ -611,18 +608,13 @@
             "string",
             "null"
           ],
-          "description": "From the workspace root; null for agent-unknown, a finding on the whole commit."
+          "description": "From the workspace root; null for agent-unknown and write-scope-class-unknown, findings on the whole commit."
         },
         "principal": {
           "type": "string"
         },
         "class": {
-          "enum": [
-            "human",
-            "agent",
-            "runner",
-            "service"
-          ]
+          "$ref": "#/$defs/principalClass"
         },
         "agent": {
           "type": [

package/src/workspace/changes.ts

@@ -44,6 +44,7 @@ import { declaredRecordKinds, readDeclaration, readerVersion, WORKSPACE_ERROR_CO
 import { declaredKindFile } from "./declared-kinds";
 import { isGeneratedPath } from "./generated-files";
 import { parseRegion } from "./intent";
+import { loadClassRegistry } from "./principal-classes";
 import { constraintCovers, isWorkspacePath, memberHolding } from "./record-assets";
 import { loadRecordKind, RecordReadError, type LoadedRecordKind, type RecordEntry } from "./records";
 import { readRecordsFor } from "./records-cli";
@@ -529,7 +530,9 @@ async function writeScopeAtBase(query: ChangesQuery, top: string, range: { base:
       format: kind.format,
     });
   }
-  return checkWriteScope({ top, base: range.base, head: range.head, prefix, declaration, kinds });
+  // The principal classes the pins supply, a path pin read at the base too (#3080).
+  const classes = loadClassRegistry(declaration.pins, located.rootOnDisk, { tree: located.tree }).registry;
+  return checkWriteScope({ top, base: range.base, head: range.head, prefix, declaration, kinds, classes });
 }
 
 function finding(code: ChangesFindingCode, p: ChangedPath, severity: "warn" | "fail", message: string, records: string[]): ChangeFinding {

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

@@ -158,6 +158,8 @@ describe("the box block in the declaration", () => {
       isolation: null,
       intent: null,
       services: [],
+      factory: null,
+      listing: 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" },

package/src/workspace/checks.ts

@@ -46,6 +46,7 @@ import { readDeclaration, resolveGroups, WorkspaceReadError, type Declaration, t
 import type { ReasonCode } from "./reason-codes";
 import { parseJsonText, pointerToken, type TextLocation } from "./jsonc";
 import { loadKindRegistry, probeKind, resolveKind, type KindLoadProblem, type KindRegistry } from "./kinds";
+import { coreClassRegistry, loadClassRegistry, unknownScopeClasses, type ClassRegistry } from "./principal-classes";
 import { gitTop, workingTree, type WorkspaceTree } from "./tree";
 import { LINK_CHECKS, linkTable } from "./checks/links";
 import type { LinkRow, LinkTableRow } from "./links";
@@ -89,6 +90,10 @@ export interface WorkspaceCheckContext {
   kinds: KindRegistry;
   /** Why some pinned kinds could not be read. */
   kindProblems: KindLoadProblem[];
+  /** The principal classes: the core four and those the pins supply (#3080). Without it, the core four. */
+  classes?: ClassRegistry;
+  /** Why some pinned principal classes could not be read (#3080). */
+  classProblems?: KindLoadProblem[];
   /** The facts gathered before the checks ran. */
   facts?: WorkspaceFacts;
 }
@@ -182,23 +187,41 @@ export const WORKSPACE_CHECKS: readonly WorkspaceCheck[] = [
   {
     id: "WSP002",
     name: "kinds-unreadable",
-    description: "Every pinned package's kinds can be read: it is installed at the pinned version, and its ./workspace-kinds file is valid kind data.",
+    description: "Every pinned package's kinds and principal classes can be read: it is installed at the pinned version, its ./workspace-kinds file is valid kind data, and its ./workspace-principals file is valid class data.",
     severity: "error",
     configurable: false,
     check(ctx) {
-      return ctx.kindProblems.map((p) => ({ checkId: this.id, severity: this.severity, message: p.message, pointer: `/pins/${p.pin}` }));
+      // A pin that can't be read is a problem for both loaders; report it once.
+      const seen = new Set<string>();
+      return [...ctx.kindProblems, ...(ctx.classProblems ?? [])]
+        .filter((p) => {
+          const key = `${p.pin}\0${p.message}`;
+          if (seen.has(key)) return false;
+          seen.add(key);
+          return true;
+        })
+        .map((p) => ({ checkId: this.id, severity: this.severity, message: p.message, pointer: `/pins/${p.pin}` }));
     },
   },
   {
     id: "WSP003",
     name: "kind-unknown",
-    description: "Every member's kind is built in or supplied by a pinned package. Unknown kinds fail closed.",
+    description: "Every member's kind is built in or supplied by a pinned package, and so is every principal class writeScope names (#3080). Unknown kinds and classes fail closed.",
     severity: "error",
     configurable: false,
     check(ctx) {
-      return ctx.declaration.members
+      const members = ctx.declaration.members
         .filter((m) => ctx.kinds.get(m.kind) === undefined)
         .map((m) => entryFinding(this, m, "kind", `member ${m.name} has kind ${m.kind}, which no built-in kind or pinned package supplies; known kinds: ${ctx.kinds.names().join(", ")}`));
+      const classes = ctx.classes ?? coreClassRegistry();
+      const scope = unknownScopeClasses(ctx.declaration.writeScope, classes).map((c) => ({
+        checkId: this.id,
+        severity: this.severity,
+        message: `writeScope names the principal class ${c}, which no core class or pinned package supplies, so a writer judged human is refused with write-scope-class-unknown; known classes: ${classes.names().join(", ")}`,
+        entity: c,
+        pointer: `/writeScope/${pointerToken(c)}`,
+      }));
+      return [...members, ...scope];
     },
   },
   {
@@ -484,6 +507,7 @@ export async function runDeclarationChecks(
     return { file: display(location.file), diagnostics: [diagnostic], suppressed: [], links: [], ok: false };
   }
   const { registry, problems } = loadKindRegistry(declaration.pins, root);
+  const classes = loadClassRegistry(declaration.pins, root, { tree });
   const gathered = options.gather === false || options.tree ? {} : await gatherWorkspaceFacts(root, declaration, options);
   // The declared record kinds load from the working tree; under --at only whether each exists at the revision is checked (#2680).
   // A declared work kind's acceptance criteria are counted in the working tree too (#2772).
@@ -497,7 +521,7 @@ export async function runDeclarationChecks(
     ...(boxIntents ? { boxIntents } : {}),
     ...(options.live && !options.tree ? { live: await gatherLiveLinkFacts(root, declaration, registry, options.live.env, options.live.onStderr) } : {}),
   };
-  const ctx: WorkspaceCheckContext = { declaration, tree, groups, kinds: registry, kindProblems: problems, facts };
+  const ctx: WorkspaceCheckContext = { declaration, tree, groups, kinds: registry, kindProblems: problems, classes: classes.registry, classProblems: classes.problems, facts };
   const findings = runWorkspaceChecks(ctx);
   const { active, suppressed } = applyCheckSettings(declaration, findings);
 

package/src/workspace/compose-graph.ts

@@ -29,6 +29,7 @@
  * `chant graph` itself is untouched: this is the only place members compose.
  */
 
+import type { FactoryView, ListingView } from "./box-factory";
 import type { Declaration } from "./declaration";
 import type { KindRegistry } from "./kinds";
 import { graphLinks, type LinkTableRow } from "./links";
@@ -93,6 +94,12 @@ export interface ComposedMember {
    * the outer `nodes` with `outer/inner/id` ids.
    */
   nested?: NestedWorkspace;
+  /**
+   * The factory and listing the member's box block declares (#3146, ws-077),
+   * read from the declaration at the revision read. Set by
+   * `chant workspace graph` on every member; null when the box declares neither.
+   */
+  box?: { factory: FactoryView | null; listing: ListingView | null } | null;
   /** Whole-read facts the member's IR carried (`meta`, `pipeline`), kept apart from the composed sections. */
   meta?: Record<string, unknown>;
   pipeline?: unknown;

package/src/workspace/conformance/__writer_fixture__/answers/answer.kind.mjs

@@ -0,0 +1,27 @@
+// The answers to the workspace's decision points (ws-058, #2739), data only:
+// no imports, no code.
+//
+// chant workspace points --open --json
+// chant workspace points ask slice-tier --inputs inputs.json --subject W-002
+// chant workspace points answer <id> --answer medium --by <name>
+//
+// The points are declared in ../decisions/points.json: typed questions, the
+// read-contract outputs they read, and a table, model and quorum chain. Each
+// answer is one record here, named for the point and its inputs' hash, so the
+// same question is answered once. A table's answer is answered, a model's is
+// proposed until a person confirms it, and a question nobody before the
+// quorum answered is escalated to people. answer.schema.json is a copy of the
+// one @intentius/chant ships as workspace/point-answer.schema.json.
+export const recordKind = {
+  name: "answer",
+  location: { dir: ".", match: "^[a-z][a-z0-9-]*-[0-9a-f]{12}\\.md$" },
+  format: "markdown-front-matter",
+  schema: { id: "urn:intentius:chant:point-answer:1", path: "answer.schema.json" },
+  idField: "id",
+  stateField: "state",
+  states: ["escalated", "proposed", "answered"],
+  closedStates: ["answered"],
+  constrains: { field: "constrains" },
+  source: { field: "source" },
+  answers: { points: "../decisions/points.json" },
+};