@intentius/chant 0.101.0 → 0.102.0

package/src/workspace/kinds.ts

@@ -370,14 +370,15 @@ export interface PackageKinds extends KindData {
 }
 
 /**
- * Where a package's `exports` send `./workspace-kinds`, or undefined when
- * the package doesn't export that subpath. Only the literal key counts: a
- * `./*` pattern maps the subpath to code, which chant never runs for kinds.
+ * Where a package's `exports` send `./workspace-kinds` (or another data
+ * subpath, such as `./workspace-principals`), or undefined when the package
+ * doesn't export it. Only the literal key counts: a `./*` pattern maps the
+ * subpath to code, which chant never runs for plugin data.
  */
-export function kindsExportTarget(pkg: Record<string, unknown>): string | undefined | { problem: string } {
+export function kindsExportTarget(pkg: Record<string, unknown>, subpath: string = KINDS_SUBPATH): string | undefined | { problem: string } {
   const exports = pkg.exports;
   if (!exports || typeof exports !== "object" || Array.isArray(exports)) return undefined;
-  const entry = (exports as Record<string, unknown>)[KINDS_SUBPATH];
+  const entry = (exports as Record<string, unknown>)[subpath];
   if (entry === undefined) return undefined;
   let target: unknown = entry;
   if (target && typeof target === "object" && !Array.isArray(target)) {
@@ -385,10 +386,10 @@ export function kindsExportTarget(pkg: Record<string, unknown>): string | undefi
     target = conditions.default ?? conditions.import ?? conditions.require;
   }
   if (typeof target !== "string") {
-    return { problem: `exports["${KINDS_SUBPATH}"] must name one file, as a string or a "default" condition` };
+    return { problem: `exports["${subpath}"] must name one file, as a string or a "default" condition` };
   }
   if (!target.startsWith("./") || !target.endsWith(".json")) {
-    return { problem: `exports["${KINDS_SUBPATH}"] is ${target}; it must name a .json file inside the package, since chant reads kinds as data and never runs a package's code` };
+    return { problem: `exports["${subpath}"] is ${target}; it must name a .json file inside the package, since chant reads plugin data as data and never runs a package's code` };
   }
   return target;
 }
@@ -499,6 +500,37 @@ export interface LoadedKinds {
   problems: KindLoadProblem[];
 }
 
+/**
+ * The directory a pin's plugin data is read from: an installed package at
+ * the pinned version, looked up from `workspaceRoot`, or a path pin's
+ * directory, checked against its integrity digest when it has one. Null for
+ * a pin that names neither. Shared by the kinds and the principal classes
+ * (#3080), so both read a pin the same way.
+ */
+export function pinnedPackageDir(pin: PinLike, workspaceRoot: string): { dir: string; source: string } | { problem: string } | null {
+  if (pin.package) {
+    const dir = findInstalledPackage(pin.package, workspaceRoot);
+    if (!dir) return { problem: `pinned package ${pin.package} is not installed; install it to read the kinds it supplies` };
+    let installed: unknown;
+    try {
+      installed = (JSON.parse(readFileSync(join(dir, "package.json"), "utf-8")) as { version?: unknown }).version;
+    } catch {
+      installed = undefined;
+    }
+    if (pin.version && installed !== pin.version) return { problem: `${pin.package} is pinned at ${pin.version}, and ${String(installed ?? "an unknown version")} is installed` };
+    return { dir, source: pin.package };
+  }
+  if (pin.path) {
+    const dir = join(workspaceRoot, ...pin.path.split("/"));
+    if (pin.integrity) {
+      const checked = checkPinIntegrity(dir, pin.integrity, pin.path);
+      if (!checked.ok) return { problem: checked.message };
+    }
+    return { dir, source: pin.path };
+  }
+  return null;
+}
+
 /**
  * Build the registry for a workspace: the built-in kinds plus the kinds
  * every pin publishes. `workspaceRoot` is the absolute workspace root; a
@@ -514,38 +546,13 @@ export function loadKindRegistry(pins: readonly PinLike[], workspaceRoot: string
   const owner = new Map<string, string>();
   const clashing = new Set<string>();
   pins.forEach((pin, i) => {
-    let dir: string | undefined;
-    let source: string;
-    if (pin.package) {
-      source = pin.package;
-      dir = findInstalledPackage(pin.package, workspaceRoot);
-      if (!dir) {
-        problems.push({ pin: i, message: `pinned package ${pin.package} is not installed; install it to read the kinds it supplies` });
-        return;
-      }
-      let installed: unknown;
-      try {
-        installed = (JSON.parse(readFileSync(join(dir, "package.json"), "utf-8")) as { version?: unknown }).version;
-      } catch {
-        installed = undefined;
-      }
-      if (pin.version && installed !== pin.version) {
-        problems.push({ pin: i, message: `${pin.package} is pinned at ${pin.version}, and ${String(installed ?? "an unknown version")} is installed` });
-        return;
-      }
-    } else if (pin.path) {
-      source = pin.path;
-      dir = join(workspaceRoot, ...pin.path.split("/"));
-      if (pin.integrity) {
-        const checked = checkPinIntegrity(dir, pin.integrity, pin.path);
-        if (!checked.ok) {
-          problems.push({ pin: i, message: checked.message });
-          return;
-        }
-      }
-    } else {
+    const found = pinnedPackageDir(pin, workspaceRoot);
+    if (found === null) return;
+    if ("problem" in found) {
+      problems.push({ pin: i, message: found.problem });
       return;
     }
+    const { dir, source } = found;
     const read = readPackageKinds(dir, source);
     for (const p of read.problems) problems.push({ pin: i, message: p });
     for (const k of read.kinds) {

package/src/workspace/points-write.schema.json

@@ -473,6 +473,7 @@
                 "answer-not-candidate",
                 "quorum-not-met",
                 "answer-in-steward-turn",
+                "principal-unidentified",
                 "record-not-found",
                 "record-closed",
                 "record-id-taken",

package/src/workspace/principal-classes.test.ts

@@ -0,0 +1,175 @@
+/**
+ * Principal classes a plugin supplies (#3080, ws-079): the data file, the
+ * registry, and how a principal's role grants at base put it in a class.
+ */
+
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { afterAll, describe, expect, test } from "vitest";
+import { cleanScratch, scratchDir } from "./__fixtures__/contract-repo";
+import {
+  CLASS_NAME,
+  classesOf,
+  coreClassRegistry,
+  loadClassRegistry,
+  parseClassData,
+  principalClass,
+  PRINCIPALS_SCHEMA_ID,
+  readPackageClasses,
+  treeFiles,
+  unknownScopeClasses,
+} from "./principal-classes";
+import { emptyPolicy } from "./trust/policy";
+import type { WorkspaceTree } from "./tree";
+
+afterAll(cleanScratch);
+
+const data = (classes: unknown[]) => JSON.stringify({ schema: 1, classes });
+const reviewer = { name: "reviewer", description: "people who review decisions", role: "reviewer" };
+const operator = { name: "operator", description: "people who apply infrastructure", role: "ops" };
+
+/** A plugin package directory on disk, publishing `classes` at ./workspace-principals. */
+function plugin(root: string, dir: string, classes: unknown[], pkg: Record<string, unknown> = {}): void {
+  const abs = join(root, ...dir.split("/"));
+  mkdirSync(abs, { recursive: true });
+  writeFileSync(join(abs, "package.json"), JSON.stringify({ name: dir.replace(/\//g, "-"), version: "1.0.0", exports: { "./workspace-principals": "./principals.json" }, ...pkg }));
+  writeFileSync(join(abs, "principals.json"), data(classes));
+}
+
+describe("the principals file", () => {
+  test("has a versioned schema id and a name grammar shared with writeScope", () => {
+    expect(PRINCIPALS_SCHEMA_ID).toBe("https://intentius.io/chant/schemas/workspace/principals/v1/workspace-principals.schema.json");
+    expect(CLASS_NAME.test("reviewer")).toBe(true);
+    expect(CLASS_NAME.test("x-reviewer")).toBe(false);
+    expect(CLASS_NAME.test("Reviewer")).toBe(false);
+  });
+
+  test("a valid file yields its classes in file order, with the pin as source", () => {
+    expect(parseClassData(data([reviewer, operator]), "plugins/review")).toEqual({
+      classes: [
+        { ...reviewer, source: "plugins/review" },
+        { ...operator, source: "plugins/review" },
+      ],
+      problems: [],
+    });
+  });
+
+  test.each([
+    ["not JSON", "{", /not JSON/],
+    ["a missing role", data([{ name: "reviewer", description: "d" }]), /role/],
+    ["an unknown field", data([{ ...reviewer, members: ["app"] }]), /additional properties/],
+    ["an x- name", data([{ ...reviewer, name: "x-reviewer" }]), /pattern/],
+  ])("refuses %s", (_, text, message) => {
+    const read = parseClassData(text, "p");
+    expect(read.classes).toEqual([]);
+    expect(read.problems.join("\n")).toMatch(message);
+  });
+
+  test("leaves out a core name, a core role, a name twice and a role twice, keeping the rest", () => {
+    const read = parseClassData(
+      data([
+        { name: "human", description: "d", role: "people" },
+        { name: "bots", description: "d", role: "agent" },
+        reviewer,
+        { ...reviewer, role: "other" },
+        { name: "checker", description: "d", role: "reviewer" },
+        operator,
+      ]),
+      "p",
+    );
+    expect(read.classes.map((c) => c.name)).toEqual(["reviewer", "operator"]);
+    expect(read.problems).toEqual([
+      "p: class human is a core class and can't be supplied by a package",
+      "p: class bots names the role agent, which puts a principal in the core agent class",
+      "p: class reviewer is listed twice",
+      "p: class checker names the role reviewer, which another class in the file names; a role puts a principal in one class",
+    ]);
+  });
+});
+
+describe("reading a package's classes", () => {
+  test("a package exporting no ./workspace-principals supplies none, without a problem", () => {
+    const root = scratchDir();
+    plugin(root, "kinds-only", [reviewer], { exports: { "./workspace-kinds": "./kinds.json" } });
+    expect(loadClassRegistry([{ package: null, version: null, path: "kinds-only" }], root)).toMatchObject({ problems: [] });
+  });
+
+  test("the export must name a JSON file inside the package", () => {
+    const files = (pkg: object) => (p: string) => (p === "package.json" ? JSON.stringify(pkg) : undefined);
+    expect(readPackageClasses(files({ exports: { "./workspace-principals": "./index.js" } }), "p").problems[0]).toMatch(/must name a .json file/);
+    expect(readPackageClasses(files({ exports: { "./workspace-principals": "./../x.json" } }), "p").problems[0]).toMatch(/points outside the package/);
+    expect(readPackageClasses(files({ exports: { "./workspace-principals": "./gone.json" } }), "p").problems[0]).toMatch(/does not exist/);
+  });
+
+  test("a path pin is read through a tree when one is given, such as the base revision", () => {
+    const files: Record<string, string> = {
+      "plugins/review/package.json": JSON.stringify({ exports: { "./workspace-principals": "./principals.json" } }),
+      "plugins/review/principals.json": data([reviewer]),
+    };
+    const tree: WorkspaceTree = {
+      label: " at base",
+      stat: (p) => (p in files ? "file" : undefined),
+      list: () => undefined,
+      read: (p) => files[p],
+    };
+    expect(readPackageClasses(treeFiles(tree, "plugins/review"), "plugins/review").classes.map((c) => c.name)).toEqual(["reviewer"]);
+    // The working tree is not consulted: nothing exists on disk at this root.
+    const loaded = loadClassRegistry([{ package: null, version: null, path: "plugins/review" }], "/nonexistent", { tree });
+    expect(loaded.problems).toEqual([]);
+    expect(loaded.registry.names()).toEqual(["human", "agent", "runner", "service", "reviewer"]);
+  });
+
+  test("a class name or a role two pins supply is left out, with a problem on the second pin", () => {
+    const root = scratchDir();
+    plugin(root, "a", [reviewer, operator]);
+    plugin(root, "b", [{ ...reviewer, role: "approver" }]);
+    plugin(root, "c", [{ name: "applier", description: "d", role: "ops" }]);
+    const pins = ["a", "b", "c"].map((path) => ({ package: null, version: null, path }));
+    const { registry, problems } = loadClassRegistry(pins, root);
+    expect(registry.names()).toEqual(["human", "agent", "runner", "service"]);
+    expect(problems).toEqual([
+      { pin: 1, message: "class reviewer is supplied by both a and b; a class name has one source" },
+      { pin: 2, message: "class applier (c) names the role ops, which class operator (a) names; a role puts a principal in one class" },
+    ]);
+  });
+
+  test("a package pin that is not installed is a problem, and a pin naming neither is skipped", () => {
+    const root = scratchDir();
+    const { problems } = loadClassRegistry(
+      [
+        { package: "absent", version: "1.0.0", path: null },
+        { package: null, version: null, path: null },
+      ],
+      root,
+    );
+    expect(problems).toEqual([{ pin: 0, message: "pinned package absent is not installed; install it to read the kinds it supplies" }]);
+  });
+});
+
+describe("a principal's classes", () => {
+  const root = scratchDir();
+  plugin(root, "review", [reviewer, operator]);
+  const { registry } = loadClassRegistry([{ package: null, version: null, path: "review" }], root);
+  const policy = { ...emptyPolicy("x"), roles: { reviewer: ["Rev@example.com", "ci@example.com"], ops: ["rev@example.com"], runner: ["ci@example.com"] } };
+
+  test("come from role grants at base, core first, then the domain classes in order", () => {
+    expect(classesOf(registry, policy, "rev@example.com")).toEqual(["reviewer", "operator"]);
+    expect(classesOf(registry, policy, "ci@example.com")).toEqual(["runner", "reviewer"]);
+    expect(classesOf(registry, policy, "lex00")).toEqual([]);
+    expect(classesOf(registry, policy, null)).toEqual([]);
+  });
+
+  test("write scope judges a principal by the first, and human is the rest", () => {
+    expect(principalClass(policy, "rev@example.com", registry)).toBe("reviewer");
+    expect(principalClass(policy, "ci@example.com", registry)).toBe("runner");
+    expect(principalClass(policy, "lex00", registry)).toBe("human");
+    // Without the plugin's classes, a domain principal is a human (the behaviour before #3080).
+    expect(principalClass(policy, "rev@example.com")).toBe("human");
+  });
+
+  test("a writeScope key no class has is unknown", () => {
+    expect(unknownScopeClasses({ human: {}, reviewer: {}, auditor: {} }, registry)).toEqual(["auditor"]);
+    expect(unknownScopeClasses({ reviewer: {} }, coreClassRegistry())).toEqual(["reviewer"]);
+    expect(unknownScopeClasses(null, registry)).toEqual([]);
+  });
+});

package/src/workspace/principal-classes.ts

@@ -0,0 +1,307 @@
+/**
+ * Principal classes (#2524 D5; #3080, ws-079).
+ *
+ * A principal class names a set of principals so the declaration can scope
+ * what they write. Four are core: `agent`, `runner` and `service`, each the
+ * holders of the role of that name in the trust policy at base, and `human`,
+ * everyone else. A plugin adds domain classes as data, the way it adds member
+ * kinds: a JSON file at its `./workspace-principals` subpath, read through
+ * the package's `package.json` and never imported. Each class it supplies
+ * names the role whose grant puts a principal in it.
+ *
+ * A principal's classes are read only from role grants at base, through
+ * {@link classesOf}. Core classes are tried first, then the domain classes
+ * in pin order and file order; the first that holds is the class write scope
+ * judges the principal as, and `human` is the rest. A gate or a record that
+ * asks whether a principal is in a class (#3163) asks {@link classesOf},
+ * which lists every class the principal's grants put it in.
+ *
+ * A path-pinned plugin's classes are read from the base revision when the
+ * caller has it (write scope does), so a change can't remap a class by
+ * editing its own copy of the plugin. A package pin is read from the
+ * installed package, which must be at the version the base pins.
+ */
+
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { join, posix } from "node:path";
+import { kindsExportTarget, pinnedPackageDir, type KindLoadProblem, type PinLike } from "./kinds";
+import { normalisePrincipal } from "./records";
+import schema from "./workspace-principals.schema.json";
+import type { TrustPolicy } from "./trust/policy";
+import { joinPath, type WorkspaceTree } from "./tree";
+
+export const PRINCIPALS_SCHEMA_ID = schema.$id;
+
+/** The subpath a package publishes its principal classes at. */
+export const PRINCIPALS_SUBPATH = "./workspace-principals";
+
+/** The core classes, in the order a principal's roles are tried; `human` holds no role and is the rest. */
+export const CORE_PRINCIPAL_CLASSES = ["human", "agent", "runner", "service"] as const;
+export type CorePrincipalClass = (typeof CORE_PRINCIPAL_CLASSES)[number];
+
+/** A class name: a core class, or a domain class a pinned package supplies. */
+export type PrincipalClassName = string;
+
+/** The grammar of a class name, as `workspace-principals.schema.json` and the declaration's writeScope keys say it. */
+export const CLASS_NAME = /^(?!x-)[a-z][a-z0-9-]{0,39}$/;
+
+export interface PrincipalClass {
+  name: string;
+  /** One line saying who is in the class. */
+  description: string;
+  /** The role whose grant at base puts a principal in the class, or null for `human`, the rest. */
+  role: string | null;
+  /** `core`, or the pin (package name or path) that supplies the class. */
+  source: string;
+}
+
+export const CORE_CLASSES: readonly PrincipalClass[] = [
+  { name: "human", description: "a principal holding none of the roles of another class", role: null, source: "core" },
+  { name: "agent", description: "a principal holding the agent role, or a write naming an agent session", role: "agent", source: "core" },
+  { name: "runner", description: "a principal holding the runner role, such as a CI job's signing identity", role: "runner", source: "core" },
+  { name: "service", description: "a principal holding the service role", role: "service", source: "core" },
+];
+
+const CORE_ROLES = new Set(CORE_CLASSES.map((c) => c.role).filter((r): r is string => r !== null));
+
+export interface ClassRegistry {
+  get(name: string): PrincipalClass | undefined;
+  /** Every class name, core first, for "unknown class" messages. */
+  names(): string[];
+  /** Every class, core first, then the domain classes in pin order and file order. */
+  all(): readonly PrincipalClass[];
+}
+
+export function createClassRegistry(extra: readonly PrincipalClass[] = []): ClassRegistry {
+  const all = [...CORE_CLASSES, ...extra];
+  const byName = new Map(all.map((c) => [c.name, c]));
+  return {
+    get: (name) => byName.get(name),
+    names: () => all.map((c) => c.name),
+    all: () => all,
+  };
+}
+
+/** The four core classes and nothing else: what a workspace whose pins supply no class has. */
+export function coreClassRegistry(): ClassRegistry {
+  return createClassRegistry();
+}
+
+/**
+ * The role grants a class is read from. Every read of roles for a class goes
+ * through here, so where the grants live (`.chant/trust.json` today,
+ * possibly the declaration, #2547) is decided in one place: the policy.
+ */
+export function roleGrants(policy: TrustPolicy): Record<string, string[]> {
+  return policy.roles;
+}
+
+/**
+ * Every class `principal`'s role grants at base put it in, in registry order
+ * (core first). Empty for a principal in no class but `human`, and for null.
+ * Names compare as {@link normalisePrincipal} folds them.
+ */
+export function classesOf(classes: ClassRegistry, policy: TrustPolicy, principal: string | null): string[] {
+  if (principal === null) return [];
+  const name = normalisePrincipal(principal);
+  const grants = roleGrants(policy);
+  return classes
+    .all()
+    .filter((c) => c.role !== null && (grants[c.role] ?? []).some((p) => normalisePrincipal(p) === name))
+    .map((c) => c.name);
+}
+
+/** The class write scope judges `principal` as: the first class its grants put it in, or `human`. */
+export function principalClass(policy: TrustPolicy, principal: string | null, classes: ClassRegistry = coreClassRegistry()): string {
+  return classesOf(classes, policy, principal)[0] ?? "human";
+}
+
+// ── Reading a plugin's classes ───────────────────────────────────────────────
+
+interface AjvError {
+  instancePath: string;
+  message?: string;
+}
+type Validate = ((data: unknown) => boolean) & { errors?: AjvError[] | null };
+
+let compiled: Validate | undefined;
+function validator(): Validate {
+  if (compiled) return compiled;
+  const require = createRequire(import.meta.url);
+  // ajv is CommonJS; its class is the default export, or that export's own default.
+  const mod = require("ajv/dist/2020") as { default?: unknown };
+  const Ajv = (mod.default ?? mod) as new (opts: object) => { compile(s: object): Validate };
+  compiled = new Ajv({ allErrors: true, strict: true }).compile(schema);
+  return compiled;
+}
+
+export interface ClassData {
+  classes: PrincipalClass[];
+  /** Why some of the data can't be used, one line each. Empty when all of it can. */
+  problems: string[];
+}
+
+/**
+ * Check the text of a principals file against
+ * `workspace-principals.schema.json` and the rules the schema can't say: no
+ * core name or core role, and no name or role twice. `source` names the pin
+ * in the classes and in the messages.
+ */
+export function parseClassData(text: string, source: string): ClassData {
+  let raw: unknown;
+  try {
+    raw = JSON.parse(text);
+  } catch (err) {
+    return { classes: [], problems: [`${source}: the principals file is not JSON (${(err as Error).message})`] };
+  }
+  const validate = validator();
+  if (!validate(raw)) {
+    const problems = (validate.errors ?? []).map((e) => `${source}: ${e.instancePath || "the principals file"} ${e.message ?? "is invalid"}`);
+    return { classes: [], problems: [...new Set(problems)] };
+  }
+  const problems: string[] = [];
+  const classes: PrincipalClass[] = [];
+  const names = new Set<string>();
+  const roles = new Set<string>();
+  for (const c of (raw as { classes: { name: string; description: string; role: string }[] }).classes) {
+    if ((CORE_PRINCIPAL_CLASSES as readonly string[]).includes(c.name)) {
+      problems.push(`${source}: class ${c.name} is a core class and can't be supplied by a package`);
+      continue;
+    }
+    if (CORE_ROLES.has(c.role)) {
+      problems.push(`${source}: class ${c.name} names the role ${c.role}, which puts a principal in the core ${c.role} class`);
+      continue;
+    }
+    if (names.has(c.name)) {
+      problems.push(`${source}: class ${c.name} is listed twice`);
+      continue;
+    }
+    if (roles.has(c.role)) {
+      problems.push(`${source}: class ${c.name} names the role ${c.role}, which another class in the file names; a role puts a principal in one class`);
+      continue;
+    }
+    names.add(c.name);
+    roles.add(c.role);
+    classes.push({ name: c.name, description: c.description, role: c.role, source });
+  }
+  return { classes, problems };
+}
+
+/** A package's files, by a `/`-separated path inside it, or undefined when one is not there. */
+export type PackageFiles = (path: string) => string | undefined;
+
+/** A package directory on disk. */
+export function diskFiles(dir: string): PackageFiles {
+  return (path) => {
+    try {
+      return readFileSync(join(dir, ...path.split("/")), "utf-8");
+    } catch {
+      return undefined;
+    }
+  };
+}
+
+/** A package directory at `dir` in `tree`, such as the workspace at the base revision. */
+export function treeFiles(tree: WorkspaceTree, dir: string): PackageFiles {
+  return (path) => {
+    const full = joinPath(dir, path);
+    if (tree.stat(full) !== "file") return undefined;
+    try {
+      return tree.read(full);
+    } catch {
+      return undefined;
+    }
+  };
+}
+
+/** Read the classes a package publishes at `./workspace-principals`. Reads files only; imports nothing. A package that publishes none supplies none. */
+export function readPackageClasses(files: PackageFiles, source: string): ClassData {
+  const manifest = files("package.json");
+  if (manifest === undefined) return { classes: [], problems: [`${source}: no readable package.json`] };
+  let pkg: Record<string, unknown>;
+  try {
+    pkg = JSON.parse(manifest) as Record<string, unknown>;
+  } catch {
+    return { classes: [], problems: [`${source}: package.json is not JSON`] };
+  }
+  const target = kindsExportTarget(pkg, PRINCIPALS_SUBPATH);
+  if (target === undefined) return { classes: [], problems: [] };
+  if (typeof target !== "string") return { classes: [], problems: [`${source}: ${target.problem}`] };
+  const inside = posix.normalize(target.slice(2));
+  if (inside.startsWith("../") || inside === "..") return { classes: [], problems: [`${source}: exports["${PRINCIPALS_SUBPATH}"] points outside the package`] };
+  const text = files(inside);
+  if (text === undefined) return { classes: [], problems: [`${source}: exports["${PRINCIPALS_SUBPATH}"] names ${target}, which does not exist`] };
+  return parseClassData(text, source);
+}
+
+export interface LoadedClasses {
+  registry: ClassRegistry;
+  problems: KindLoadProblem[];
+}
+
+/**
+ * The classes a workspace knows: the core four plus every class its pins
+ * supply. A package pin is read from the installed package, looked up from
+ * `workspaceRoot`, and must be at the pinned version. A path pin is read
+ * through `tree` when given (the base revision, for write scope), else from
+ * `workspaceRoot` on disk, checked against its integrity digest. A class
+ * name, or a role, two pins both supply is a problem, and every class
+ * involved is left out, so a writeScope entry for it reads as unknown and
+ * fails closed. Never throws.
+ */
+export function loadClassRegistry(pins: readonly PinLike[], workspaceRoot: string, opts: { tree?: WorkspaceTree } = {}): LoadedClasses {
+  const problems: KindLoadProblem[] = [];
+  const extra: PrincipalClass[] = [];
+  const byName = new Map<string, string>();
+  const byRole = new Map<string, string>();
+  const clashing = new Set<string>();
+  pins.forEach((pin, i) => {
+    let files: PackageFiles;
+    let source: string;
+    if (pin.path && opts.tree) {
+      files = treeFiles(opts.tree, pin.path);
+      source = pin.path;
+    } else {
+      const found = pinnedPackageDir(pin, workspaceRoot);
+      if (found === null) return;
+      if ("problem" in found) {
+        problems.push({ pin: i, message: found.problem });
+        return;
+      }
+      files = diskFiles(found.dir);
+      source = found.source;
+    }
+    const read = readPackageClasses(files, source);
+    for (const p of read.problems) problems.push({ pin: i, message: p });
+    for (const c of read.classes) {
+      const named = byName.get(c.name);
+      const roled = byRole.get(c.role!);
+      if (named !== undefined || roled !== undefined) {
+        clashing.add(c.name);
+        if (named !== undefined) {
+          problems.push({ pin: i, message: `class ${c.name} is supplied by both ${named} and ${source}; a class name has one source` });
+        } else {
+          const other = extra.find((e) => e.role === c.role)!;
+          clashing.add(other.name);
+          problems.push({ pin: i, message: `class ${c.name} (${source}) names the role ${c.role}, which class ${other.name} (${roled}) names; a role puts a principal in one class` });
+        }
+        continue;
+      }
+      byName.set(c.name, source);
+      byRole.set(c.role!, source);
+      extra.push(c);
+    }
+  });
+  // A name or role two pins both supply is left out altogether: neither reading is safe.
+  return { registry: createClassRegistry(extra.filter((c) => !clashing.has(c.name))), problems };
+}
+
+/**
+ * The writeScope keys no class in `classes` has, in file order. A writer
+ * judged `human` may be in such a class, since nothing says which role puts
+ * a principal in it, so write scope refuses that writer (fail closed).
+ */
+export function unknownScopeClasses(writeScope: Record<string, unknown> | null, classes: ClassRegistry): string[] {
+  return Object.keys(writeScope ?? {}).filter((name) => classes.get(name) === undefined);
+}

package/src/workspace/reason-codes.test.ts

@@ -14,7 +14,7 @@ import { MEMBER_RUN_REASON_CODES } from "./compose-graph";
 import { COMPOSITES_ENVIRONMENT_REASON_CODES, COMPOSITES_ERROR_CODES, COMPOSITES_REASON_CODES, COMPOSITES_RUNTIME_REASON_CODES } from "./composites";
 import { WORKSPACE_ERROR_CODES } from "./declaration";
 import { GRAPH_ERROR_CODES } from "./graph-cli";
-import { INTENT_ERROR_CODES, INTENT_FINDING_CODES, INTENT_REASON_CODES } from "./intent";
+import { INTENT_ERROR_CODES, INTENT_FINDING_CODES, INTENT_REASON_CODES, INTENT_WHY_CODES } from "./intent";
 import { CHECK_CODES, CHECK_ERROR_CODES } from "./lineage-check";
 import { GROUP_REASON_CODES, MEMBER_REASON_CODES } from "./ls";
 import intentSchema from "./intent.schema.json";
@@ -29,6 +29,7 @@ import { WORK_WARNING_CODES } from "./work";
 import { BOX_FINDING_CODES } from "./checks/boxes";
 import { DIAGRAM_FINDING_CODES } from "./checks/diagrams";
 import { WORK_ERROR_CODES, WORK_HISTORY_ERROR_CODES, WORK_LEASE_REFUSALS } from "./work-cli";
+import { RUNS_ERROR_CODES, RUNS_REASON_CODES, RUNS_WRITE_ERROR_CODES } from "./runs-cli";
 import { WORK_EVIDENCE_ERROR_CODES } from "./work-evidence";
 import { RECORD_FINDING_CODES } from "./checks/records";
 import { ANSWER_WARNING_CODES } from "./points";
@@ -36,7 +37,8 @@ import { POINTS_ERROR_CODES, POINTS_SOURCE_REASON_CODES } from "./points-cli";
 import { POINTS_WRITE_ERROR_CODES } from "./decide";
 import { PATCH_ERROR_CODES } from "./patch";
 import { AGENT_ERROR_CODES } from "./agent-cli";
-import { WRITE_SCOPE_CODES } from "./write-scope";
+import { SCOPE_FINDING_CODES, WRITE_SCOPE_CODES } from "./write-scope";
+import { PLANTABLE_REASON_CODES } from "./box-factory";
 import { ROTATION_REFUSAL_CODES } from "./trust/rotation";
 import { SIGNERS_ERROR_CODES } from "./trust/signers-cli";
 import { EVIDENCE_ERROR_CODES } from "./trust/evidence";
@@ -73,6 +75,7 @@ const PER_COMMAND: Record<string, readonly string[]> = {
   INTENT_ERROR_CODES,
   INTENT_FINDING_CODES,
   INTENT_REASON_CODES,
+  INTENT_WHY_CODES,
   CHANGES_FINDING_CODES,
   CHANGES_ERROR_CODES,
   COMPOSITES_ERROR_CODES,
@@ -82,6 +85,9 @@ const PER_COMMAND: Record<string, readonly string[]> = {
   WORK_ERROR_CODES,
   WORK_HISTORY_ERROR_CODES,
   WORK_LEASE_REFUSALS,
+  RUNS_ERROR_CODES,
+  RUNS_REASON_CODES,
+  RUNS_WRITE_ERROR_CODES,
   WORK_EVIDENCE_ERROR_CODES,
   RECORD_FINDING_CODES,
   ANSWER_WARNING_CODES,
@@ -91,6 +97,8 @@ const PER_COMMAND: Record<string, readonly string[]> = {
   PATCH_ERROR_CODES,
   AGENT_ERROR_CODES,
   WRITE_SCOPE_CODES,
+  SCOPE_FINDING_CODES,
+  PLANTABLE_REASON_CODES,
   ROTATION_REFUSAL_CODES,
   SIGNERS_ERROR_CODES,
   EVIDENCE_ERROR_CODES,
@@ -145,7 +153,7 @@ describe("the closed list of reason codes", () => {
 
   test("the output schemas name exactly these codes", () => {
     const named = new Set<string>();
-    for (const f of readdirSync(HERE).filter((f) => f.endsWith(".schema.json") && !f.startsWith("declaration") && !f.startsWith("workspace-kinds"))) {
+    for (const f of readdirSync(HERE).filter((f) => f.endsWith(".schema.json") && !f.startsWith("declaration") && !f.startsWith("workspace-kinds") && !f.startsWith("workspace-principals"))) {
       for (const c of schemaCodes(JSON.parse(readFileSync(join(HERE, f), "utf-8")))) {
         expect(isReasonCode(c), `${f} names ${c}, which is not in reason-codes.ts`).toBe(true);
         named.add(c);