@intentius/chant 0.100.0 → 0.102.0

package/src/workspace/nesting.ts

@@ -0,0 +1,37 @@
+/**
+ * The outer workspace never writes inside a nested one (#2524 D2, ws-007,
+ * #2551). A member of kind `workspace` upgrades itself with its own
+ * `chant workspace upgrade`; the outer side only reads it
+ * (./nested-graph.ts).
+ */
+
+import { readDeclaration, WorkspaceReadError } from "./declaration";
+import { workingTree } from "./tree";
+
+/** The nested workspaces `dir` declares, as `{ name, dir }` with `dir` relative to `dir`. Empty without a readable declaration. */
+export function nestedWorkspaces(dir: string): { name: string; dir: string }[] {
+  try {
+    return readDeclaration(workingTree(dir))
+      .members.filter((m) => m.kind === "workspace")
+      .map((m) => ({ name: m.name, dir: m.dir }));
+  } catch (err) {
+    if (err instanceof WorkspaceReadError) return [];
+    throw err;
+  }
+}
+
+/**
+ * The paths, of `paths` (relative to the repository root), that lie inside a
+ * nested workspace of the workspace at `dir`, whose own path from the
+ * repository root is `rel` ("" for the root).
+ */
+export function pathsInsideNested(dir: string, rel: string, paths: readonly string[]): { member: string; path: string }[] {
+  const nested = nestedWorkspaces(dir).map((n) => ({ member: n.name, prefix: `${[rel, n.dir].filter(Boolean).join("/")}/` }));
+  if (nested.length === 0) return [];
+  const out: { member: string; path: string }[] = [];
+  for (const path of paths) {
+    const hit = nested.find((n) => path.startsWith(n.prefix));
+    if (hit) out.push({ member: hit.member, path });
+  }
+  return out;
+}

package/src/workspace/pin-cli.test.ts

@@ -0,0 +1,71 @@
+import { mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { afterEach, describe, expect, test, vi } from "vitest";
+import type { CommandContext } from "../cli/registry";
+import { runWorkspacePin } from "./pin-cli";
+import { integrityOf } from "./pin-integrity";
+
+const cwd = process.cwd();
+const scratch: string[] = [];
+afterEach(() => {
+  process.chdir(cwd);
+  vi.restoreAllMocks();
+  for (const d of scratch.splice(0)) rmSync(d, { recursive: true, force: true });
+});
+
+function workspace(integrity?: string): string {
+  const root = realpathSync(mkdtempSync(join(tmpdir(), "chant-pin-cli-")));
+  scratch.push(root);
+  const files: Record<string, string> = {
+    "plugins/tf/package.json": JSON.stringify({ name: "tf" }),
+    "plugins/tf/k.json": "{}",
+    "chant.workspace.json": JSON.stringify({ name: "w", schema: 1, pins: [{ path: "plugins/tf", ...(integrity ? { integrity } : {}) }], members: [{ name: "w", dir: ".", kind: "other", because: "test" }] }),
+  };
+  for (const [p, t] of Object.entries(files)) {
+    mkdirSync(dirname(join(root, p)), { recursive: true });
+    writeFileSync(join(root, p), t);
+  }
+  return root;
+}
+
+async function pin(root: string, path: string | undefined, json = false) {
+  process.chdir(root);
+  const out: string[] = [];
+  const err: string[] = [];
+  vi.spyOn(console, "log").mockImplementation((s: string) => void out.push(s));
+  vi.spyOn(console, "error").mockImplementation((s: string) => void err.push(s));
+  const code = await runWorkspacePin({ args: { extraPositional: path, json } } as unknown as CommandContext);
+  return { code, out: out.join("\n"), err: err.join("\n") };
+}
+
+describe("chant workspace pin (#2547)", () => {
+  test("prints the integrity value, and says an unpinned path pin needs it", async () => {
+    const root = workspace();
+    const r = await pin(root, "plugins/tf");
+    expect(r.code).toBe(0);
+    expect(r.out).toBe(integrityOf(join(root, "plugins/tf")).integrity);
+    expect(r.err).toContain('is a path pin with no integrity; add "integrity"');
+  });
+
+  test("--json names the path, the value, the file count and whether the declared pin matches", async () => {
+    const root = workspace();
+    const { integrity } = integrityOf(join(root, "plugins/tf"));
+    const matching = workspace(integrity);
+    const r = await pin(matching, "plugins/tf", true);
+    expect(JSON.parse(r.out)).toEqual({ path: "plugins/tf", integrity: integrityOf(join(matching, "plugins/tf")).integrity, files: 2, pin: "matches" });
+  });
+
+  test("exits 1 when the declared pin no longer matches", async () => {
+    const root = workspace("sha256-AAAA");
+    const r = await pin(root, "plugins/tf");
+    expect(r.code).toBe(1);
+    expect(r.err).toContain("does not match the integrity its pin states (sha256-AAAA)");
+  });
+
+  test("refuses a path outside the workspace, and a missing argument", async () => {
+    const root = workspace();
+    expect((await pin(root, "../elsewhere")).code).toBe(1);
+    expect((await pin(root, undefined)).code).toBe(1);
+  });
+});

package/src/workspace/pin-cli.ts

@@ -0,0 +1,57 @@
+/**
+ * `chant workspace pin <path> [--json]` (#2547, ws-065): print the `integrity`
+ * value that pins the plugin at `path`, a directory or file inside the
+ * workspace. What the hash covers is in ./pin-integrity.ts. The command reads
+ * files only, and says whether a path pin the declaration already has for
+ * that path matches.
+ */
+
+import { relative, resolve, sep } from "node:path";
+import { formatError } from "../cli/format";
+import type { CommandContext } from "../cli/registry";
+import { readDeclaration, WorkspaceReadError } from "./declaration";
+import { integrityOf, PinHashError } from "./pin-integrity";
+import { locateWorkspace } from "./which-chant";
+
+const USAGE = "chant workspace pin <path> [--json]";
+
+export async function runWorkspacePin(ctx: CommandContext): Promise<number> {
+  const { args } = ctx;
+  const given = args.extraPositional;
+  if (!given) {
+    console.error(formatError({ message: "chant workspace pin needs the plugin's path", hint: USAGE }));
+    return 1;
+  }
+  try {
+    const located = locateWorkspace(process.cwd());
+    const declaration = readDeclaration(located.tree, "", { rootChant: true });
+    const abs = resolve(process.cwd(), given);
+    const rel = relative(located.rootOnDisk, abs).split(sep).join("/");
+    if (rel === "" || rel.startsWith("../") || rel === "..") {
+      console.error(formatError({ message: `${given} is not inside the workspace`, hint: USAGE }));
+      return 1;
+    }
+    const { integrity, files } = integrityOf(abs);
+    const declared = declaration.pins.find((p) => p.path === rel);
+    const state = declared === undefined ? "undeclared" : declared.integrity === null ? "declared-unpinned" : declared.integrity === integrity ? "matches" : "differs";
+    if (args.json) {
+      console.log(JSON.stringify({ path: rel, integrity, files, pin: state }, null, 2));
+    } else {
+      console.log(integrity);
+      const note = {
+        undeclared: `${rel} is not a path pin in ${declaration.file}; add { "path": "${rel}", "integrity": "${integrity}" } to pins`,
+        "declared-unpinned": `${rel} is a path pin with no integrity; add "integrity": "${integrity}" to it`,
+        matches: `${rel} matches the integrity its pin states`,
+        differs: `${rel} does not match the integrity its pin states (${declared?.integrity}); update the pin if the change is intended`,
+      }[state];
+      console.error(`${files} file${files === 1 ? "" : "s"} hashed. ${note}`);
+    }
+    return state === "differs" ? 1 : 0;
+  } catch (err) {
+    if (err instanceof WorkspaceReadError || err instanceof PinHashError) {
+      console.error(formatError({ message: `${given}: ${err.message}`, hint: USAGE }));
+      return 1;
+    }
+    throw err;
+  }
+}

package/src/workspace/pin-integrity.test.ts

@@ -0,0 +1,121 @@
+import { createHash } from "node:crypto";
+import { mkdirSync, mkdtempSync, realpathSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { afterAll, describe, expect, test } from "vitest";
+import { loadKindRegistry } from "./kinds";
+import { checkPinIntegrity, integrityOf, parseIntegrity, pinnedFiles } from "./pin-integrity";
+
+const scratch: string[] = [];
+afterAll(() => {
+  for (const d of scratch) rmSync(d, { recursive: true, force: true });
+});
+function dir(files: Record<string, string>): string {
+  const root = realpathSync(mkdtempSync(join(tmpdir(), "chant-pin-")));
+  scratch.push(root);
+  for (const [path, text] of Object.entries(files)) {
+    mkdirSync(dirname(join(root, path)), { recursive: true });
+    writeFileSync(join(root, path), text);
+  }
+  return root;
+}
+
+const tf = { name: "terraform", description: "a Terraform root module", precedence: 400, probe: { anyFile: ["main.tf"] } };
+const plugin = (): Record<string, string> => ({
+  "plugins/tf/package.json": JSON.stringify({ name: "tf", exports: { "./workspace-kinds": "./k.json" } }),
+  "plugins/tf/k.json": JSON.stringify({ schema: 1, kinds: [tf] }),
+});
+
+describe("integrityOf", () => {
+  test("a file is its bytes' SRI digest", () => {
+    const root = dir({ "a.txt": "hello\n" });
+    const expected = `sha256-${createHash("sha256").update("hello\n").digest("base64")}`;
+    expect(integrityOf(join(root, "a.txt"))).toEqual({ integrity: expected, files: 1 });
+  });
+
+  test("a directory is the digest of a manifest of each file's own digest and path, sorted by path", () => {
+    const root = dir({ "d/b.txt": "B", "d/a/z.txt": "Z" });
+    const h = (s: string) => createHash("sha256").update(s).digest("hex");
+    const manifest = `${h("Z")} a/z.txt\n${h("B")} b.txt\n`;
+    expect(integrityOf(join(root, "d"))).toEqual({
+      integrity: `sha256-${createHash("sha256").update(manifest).digest("base64")}`,
+      files: 2,
+    });
+  });
+
+  test("it does not depend on the order files were written, and it follows a changed byte, a rename and an added file", () => {
+    const base = integrityOf(join(dir({ "d/a": "1", "d/b": "2" }), "d")).integrity;
+    expect(integrityOf(join(dir({ "d/b": "2", "d/a": "1" }), "d")).integrity).toBe(base);
+    expect(integrityOf(join(dir({ "d/a": "1", "d/b": "3" }), "d")).integrity).not.toBe(base);
+    expect(integrityOf(join(dir({ "d/a": "1", "d/c": "2" }), "d")).integrity).not.toBe(base);
+    expect(integrityOf(join(dir({ "d/a": "1", "d/b": "2", "d/e": "" }), "d")).integrity).not.toBe(base);
+  });
+
+  test("node_modules and .git are left out, and a symbolic link is refused", () => {
+    const root = dir({ "d/a": "1", "d/node_modules/x/index.js": "x", "d/.git/HEAD": "ref" });
+    expect(pinnedFiles(join(root, "d"))).toEqual(["a"]);
+    symlinkSync("/etc/hosts", join(root, "d", "link"));
+    expect(() => integrityOf(join(root, "d"))).toThrow(/link is a symbolic link/);
+  });
+
+  test("sha384 and sha512 are taken with that algorithm", () => {
+    const root = dir({ "d/a": "1" });
+    expect(integrityOf(join(root, "d"), "sha512").integrity).toMatch(/^sha512-/);
+    expect(integrityOf(join(root, "d"), "sha384").integrity).toMatch(/^sha384-/);
+  });
+});
+
+describe("parseIntegrity", () => {
+  test("takes the three SRI algorithms and nothing else", () => {
+    expect(parseIntegrity("sha256-AAAA")).toEqual({ algorithm: "sha256", digest: "AAAA" });
+    expect(parseIntegrity("md5-AAAA")).toBeUndefined();
+    expect(parseIntegrity("sha256:AAAA")).toBeUndefined();
+  });
+});
+
+describe("a path pin's integrity when kinds are loaded (#2547)", () => {
+  test("a matching integrity loads the plugin's kinds", () => {
+    const root = dir(plugin());
+    const { integrity } = integrityOf(join(root, "plugins/tf"));
+    const { registry, problems } = loadKindRegistry([{ package: null, version: null, path: "plugins/tf", integrity }], root);
+    expect(problems).toEqual([]);
+    expect(registry.get("terraform")?.source).toBe("plugins/tf");
+  });
+
+  test("a changed plugin is refused with the expected and actual hash, and none of its kinds load", () => {
+    const root = dir(plugin());
+    const { integrity } = integrityOf(join(root, "plugins/tf"));
+    writeFileSync(join(root, "plugins/tf/k.json"), JSON.stringify({ schema: 1, kinds: [{ ...tf, name: "evil" }] }));
+    const { registry, problems } = loadKindRegistry([{ package: null, version: null, path: "plugins/tf", integrity }], root);
+    expect(registry.get("evil")).toBeUndefined();
+    expect(registry.get("terraform")).toBeUndefined();
+    expect(problems).toHaveLength(1);
+    expect(problems[0].pin).toBe(0);
+    expect(problems[0].message).toContain("plugins/tf: integrity mismatch, so nothing is read from it");
+    expect(problems[0].message).toContain(`The pin says ${integrity} and the plugin hashes to sha256-`);
+    expect(problems[0].message).toContain("chant workspace pin plugins/tf");
+  });
+
+  test("an added file is a mismatch too", () => {
+    const root = dir(plugin());
+    const { integrity } = integrityOf(join(root, "plugins/tf"));
+    writeFileSync(join(root, "plugins/tf/extra.js"), "x");
+    const checked = checkPinIntegrity(join(root, "plugins/tf"), integrity, "plugins/tf");
+    expect(checked.ok).toBe(false);
+  });
+
+  test("a pin with no integrity loads as before", () => {
+    const root = dir(plugin());
+    const { registry, problems } = loadKindRegistry([{ package: null, version: null, path: "plugins/tf", integrity: null }], root);
+    expect(problems).toEqual([]);
+    expect(registry.get("terraform")).toBeDefined();
+  });
+
+  test("a missing plugin and a malformed integrity are problems, not throws", () => {
+    const root = dir(plugin());
+    const missing = loadKindRegistry([{ package: null, version: null, path: "plugins/none", integrity: "sha256-AAAA" }], root);
+    expect(missing.problems[0].message).toMatch(/can't check its integrity, it does not exist/);
+    const bad = checkPinIntegrity(join(root, "plugins/tf"), "nope", "plugins/tf");
+    expect(bad).toEqual({ ok: false, message: expect.stringContaining("is not sha256-, sha384- or sha512-") });
+  });
+});

package/src/workspace/pin-integrity.ts

@@ -0,0 +1,104 @@
+/**
+ * Content hashes for plugins a declaration loads by path (#2547, ws-065).
+ *
+ * A pin of `{ "path": "plugins/kinds", "integrity": "sha256-..." }` says the
+ * plugin directory must hash to that value before chant reads anything from
+ * it. `chant workspace pin <path>` prints the value to put there.
+ *
+ * `integrity` is a Subresource Integrity string: `sha256-`, `sha384-` or
+ * `sha512-`, then the base64 of the digest. A directory has no single byte
+ * stream to hash, so its digest is taken over a manifest that names every
+ * file by its path and its own digest, and a file path is hashed directly:
+ *
+ * - The files are every regular file under the directory, at any depth, except
+ *   anything inside a `node_modules` or `.git` directory.
+ * - Each file's digest is the chosen algorithm over its bytes, as they are on
+ *   disk: no line-ending change, so a checkout that rewrites line endings
+ *   hashes differently from one that does not.
+ * - The manifest is one line per file, `<hex digest> <path>\n`, in order of
+ *   the path's UTF-16 code units, with `/` as the separator and the path
+ *   relative to the directory. The pin is the algorithm over those bytes.
+ * - A symbolic link anywhere in the directory is refused: it can point
+ *   outside the plugin, and what it points at is not what was pinned.
+ *
+ * The hash covers the working tree. Build output and untracked files inside
+ * the directory change it, so pin a directory that holds only committed files.
+ */
+
+import { createHash } from "node:crypto";
+import { lstatSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+export type IntegrityAlgorithm = "sha256" | "sha384" | "sha512";
+
+const INTEGRITY = /^(sha(?:256|384|512))-([A-Za-z0-9+/]+={0,2})$/;
+
+/** The algorithm and base64 digest of an `integrity` value, or undefined when it is not one. */
+export function parseIntegrity(value: string): { algorithm: IntegrityAlgorithm; digest: string } | undefined {
+  const m = INTEGRITY.exec(value);
+  return m ? { algorithm: m[1] as IntegrityAlgorithm, digest: m[2] } : undefined;
+}
+
+/** Directories a plugin hash never looks inside. */
+const SKIPPED_DIRS = new Set(["node_modules", ".git"]);
+
+/** Thrown when a path can't be hashed: it is missing, or holds a symbolic link. */
+export class PinHashError extends Error {}
+
+function walk(dir: string, prefix: string, out: string[]): void {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const rel = prefix === "" ? entry.name : `${prefix}/${entry.name}`;
+    if (entry.isSymbolicLink()) throw new PinHashError(`${rel} is a symbolic link, which a pinned plugin may not contain`);
+    if (entry.isDirectory()) {
+      if (!SKIPPED_DIRS.has(entry.name)) walk(join(dir, entry.name), rel, out);
+    } else if (entry.isFile()) {
+      out.push(rel);
+    }
+  }
+}
+
+/** The files a directory's hash covers, as paths relative to it, in hash order. */
+export function pinnedFiles(dir: string): string[] {
+  const files: string[] = [];
+  walk(dir, "", files);
+  return files.sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+}
+
+/** The `integrity` value for the plugin at `abs`: a directory by its manifest, a file by its bytes. */
+export function integrityOf(abs: string, algorithm: IntegrityAlgorithm = "sha256"): { integrity: string; files: number } {
+  let stat;
+  try {
+    stat = lstatSync(abs);
+  } catch {
+    throw new PinHashError("it does not exist");
+  }
+  if (stat.isSymbolicLink()) throw new PinHashError("it is a symbolic link, which a pinned plugin may not be");
+  if (stat.isFile()) {
+    return { integrity: `${algorithm}-${createHash(algorithm).update(readFileSync(abs)).digest("base64")}`, files: 1 };
+  }
+  const files = pinnedFiles(abs);
+  const manifest = files.map((f) => `${createHash(algorithm).update(readFileSync(join(abs, ...f.split("/")))).digest("hex")} ${f}\n`).join("");
+  return { integrity: `${algorithm}-${createHash(algorithm).update(manifest, "utf8").digest("base64")}`, files: files.length };
+}
+
+export type IntegrityCheck = { ok: true } | { ok: false; message: string };
+
+/** Compare the plugin at `abs` with the `integrity` a pin states. `label` names the plugin in the message. */
+export function checkPinIntegrity(abs: string, integrity: string, label: string): IntegrityCheck {
+  const parsed = parseIntegrity(integrity);
+  if (!parsed) return { ok: false, message: `${label}: integrity ${JSON.stringify(integrity)} is not sha256-, sha384- or sha512- and a base64 digest` };
+  let actual: string;
+  try {
+    actual = integrityOf(abs, parsed.algorithm).integrity;
+  } catch (err) {
+    if (!(err instanceof PinHashError)) throw err;
+    return { ok: false, message: `${label}: can't check its integrity, ${err.message}` };
+  }
+  if (actual === integrity) return { ok: true };
+  return {
+    ok: false,
+    message:
+      `${label}: integrity mismatch, so nothing is read from it. The pin says ${integrity} and the plugin hashes to ${actual}. ` +
+      `If the change is intended, run \`chant workspace pin ${label}\` and put the value it prints in the pin; otherwise restore the plugin`,
+  };
+}

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",
@@ -483,6 +484,7 @@
                 "record-supersedes-conflict",
                 "record-remediates-unknown",
                 "record-remediates-not-closed",
+                "record-seal-mismatch",
                 "session-seal-mismatch",
                 "session-verdict-unknown-record"
               ]

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([]);
+  });
+});