@intentius/chant 0.124.14 → 0.124.15

package/src/op/op-waves-run.ts

@@ -130,7 +130,7 @@ export interface OpWavePlansFile {
 /** Pending-fact keys chant writes itself, which a plans file's `pending` may not set (#3821). */
 export const OP_WAVE_PENDING_RESERVED = [
   "version", "kind", "op", "gate", "timestamp", "expiresAt", "planDigest", "runId", "url", "resume",
-  "environment", "origin", "neverOverMcp", "approval", "approvalMode", "answer",
+  "environment", "origin", "neverOverMcp", "approval", "approvalMode", "answer", "wave", "heldBy",
 ] as const;
 
 /** What chant writes to `{runs}` for a wave-level command or a hook (#3762). */
@@ -835,6 +835,7 @@ interface HooksOutcome {
 interface OtherGateHold {
   label: string;
   name: string;
+  moment: OpWaveHookMoment;
   target?: string;
   argv: string[];
   env: Record<string, string>;
@@ -914,7 +915,7 @@ function runHookList(
         out.outcomes.push({ ...base, outcome: "held" });
         const request = readHoldRequest(join(cwd, holdPath), log, label);
         if (request) {
-          out.otherGates.push({ label, name, ...(call.target ? { target: call.target } : {}), argv: call.argv, env: call.env, request });
+          out.otherGates.push({ label, name, moment, ...(call.target ? { target: call.target } : {}), argv: call.argv, env: call.env, request });
           log(`${label} exited ${code} and holds wave ${k} (${waveName}) on gate ${request.op ?? specName} / ${request.gate}, digest ${request.digest}`);
           continue;
         }
@@ -1068,7 +1069,7 @@ async function settleOtherGate(ctx: WaveContext, hold: OtherGateHold): Promise<O
     description: hold.request.description ?? `wave ${k} (${wave.name}) of ${spec.name} is held on it by ${hold.label}`,
     now,
     // #3839: the wave a hold belongs to, as a field, whatever the hook's own description says.
-    fields: { ...hold.request.pending, approvalMode: rules.approval, wave: { number: k, name: wave.name, op: spec.name } },
+    fields: { ...hold.request.pending, approvalMode: rules.approval, wave: { number: k, name: wave.name, op: spec.name }, heldBy: { hook: hold.name, moment: hold.moment, ...(hold.target ? { target: hold.target } : {}) } },
     ...(neverOverMcp ? { neverOverMcp: true } : {}),
   });
   const base = { op, gate: hold.request.gate, digest: hold.request.digest, hook: hold.label };

package/src/op/op-waves.test.ts

@@ -910,6 +910,8 @@ describe("gates and holds a product's wave needs (#3821)", () => {
     expect(gates.appended[0]).toMatchObject({ op: "tf-migrate", gate: "split-queues", planDigest: digest("m"), members: [] });
     // #3839: the hold names its wave as a field, even when the hook wrote the description.
     expect(gates.appended[0]).toMatchObject({ description: "move the queues", wave: { number: 1, name: expect.any(String), op: tg.name } });
+    // #3886: and the hook that holds it, as a field.
+    expect(gates.appended[0]).toMatchObject({ heldBy: { hook: "migrate", moment: expect.any(String) } });
     expect(h.calls.some((c) => c.startsWith("tg plan"))).toBe(false);
     expect(h.envs.find((e) => e.CHANT_HOOK === "after-gate")).toMatchObject({ CHANT_GATE_STATUS: "waiting", CHANT_GATE_OP: "tf-migrate", CHANT_GATE: "split-queues" });
     h.done();

package/src/op/work-lease-run.test.ts

@@ -4,7 +4,7 @@
  * when it ends, and a lost lease stopping the run. An Op that changes the
  * checkout runs its leased steps in a worktree of its own.
  */
-import { describe, test, expect } from "vitest";
+import { describe, test, expect, vi } from "vitest";
 import { withTestDir } from "@intentius/chant-test-utils";
 import { spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
@@ -230,6 +230,11 @@ describe("a run under a work lease", () => {
   }, 30_000);
 
   test("a lease lost mid-step stops the step and the run, which fails lease-lost and releases nothing", async () => {
+    // The heartbeat is the only timer faked: the test fires its beat itself
+    // once the thief holds the lease, instead of waiting a wall-clock second
+    // for a renewal that a loaded machine can delay past any fixed bound.
+    vi.useFakeTimers({ toFake: ["setInterval", "clearInterval"] });
+    try {
     await withTestDir(async (dir) => {
       await initRepo(dir);
       const log: string[] = [];
@@ -241,9 +246,9 @@ describe("a run under a work lease", () => {
             // The lease runs out from under this run and another worker takes it.
             await releaseWorkLease(lease.item, lease.holder, { cwd: dir, token: lease.token });
             expect((await claimWorkLease(lease.item, "thief", { cwd: dir, ttlMs: 60_000 })).ok).toBe(true);
-            await new Promise<void>((resolve, reject) => {
-              const t = setTimeout(() => reject(new Error("never stopped")), 20_000);
-              signal?.addEventListener("abort", () => { clearTimeout(t); log.push("stopped"); reject(new Error("aborted")); }, { once: true });
+            await new Promise<void>((_resolve, reject) => {
+              signal?.addEventListener("abort", () => { log.push("stopped"); reject(new Error("aborted")); }, { once: true });
+              void vi.advanceTimersByTimeAsync(1_000);
             });
             return {};
           },
@@ -270,6 +275,9 @@ describe("a run under a work lease", () => {
       expect((await listWorkLeases({ cwd: dir, memberPrefix: "" }))[0]).toMatchObject({ holder: "thief", state: "active" });
       expect((await readRunLedger("local", "dispatch", { cwd: dir })).records.at(-1)?.status).toBe("fail");
     });
+    } finally {
+      vi.useRealTimers();
+    }
   }, 30_000);
 
   test("a run whose lease was lost before it is recorded is never recorded as done", async () => {

package/src/workspace/__fixtures__/contract-repo.ts

@@ -4,7 +4,7 @@
  */
 
 import { execFileSync } from "node:child_process";
-import { chmodSync, mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { chmodSync, cpSync, existsSync, mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import Ajv2020 from "ajv/dist/2020";
@@ -56,6 +56,22 @@ export function repo(files: Record<string, string | { text: string; mode: number
   return root;
 }
 
+/**
+ * Build a fixture repository once per test file and hand each caller a copy of
+ * it. A repo costs a dozen git processes (init, add, commit, config), and a
+ * file copy none, so a file whose tests each start from the same repo builds
+ * it once (#3880). The template is rebuilt if {@link cleanScratch} removed it.
+ */
+export function repoFixture(build: () => string, prefix = "chant-contract-copy-"): () => string {
+  let template: string | undefined;
+  return () => {
+    if (template === undefined || !existsSync(template)) template = build();
+    const root = scratchDir(prefix);
+    cpSync(template, root, { recursive: true });
+    return root;
+  };
+}
+
 export function commitAll(root: string, message = "next"): string {
   git(root, "add", "-A");
   git(root, "commit", "-q", "-m", message);

package/src/workspace/__fixtures__/sessions.ts

@@ -7,19 +7,19 @@
 import { cpSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { sessionSeal } from "../record-sessions";
-import { commitAll, git, REPO, scratchDir } from "./contract-repo";
+import { commitAll, git, REPO, repoFixture, scratchDir } from "./contract-repo";
 
 export const SESSIONS_KIND = "design/sessions/session.kind.mjs";
 export const DECISIONS_KIND = "decisions/decision.kind.mjs";
 
 /** A git repository holding a copy of the reference workspace's decisions and design member. */
-export function sessionsRepo(): string {
+export const sessionsRepo = repoFixture(() => {
   const root = scratchDir("chant-sessions-");
   for (const d of ["decisions", "design"]) cpSync(join(REPO, "reference-workspace", d), join(root, d), { recursive: true });
   git(root, "init", "-q");
   commitAll(root, "reference");
   return root;
-}
+}, "chant-sessions-");
 
 /** A session file's text, sealed when it is closed. */
 export function sessionText(s: { id: string; state: "open" | "closed"; verdicts?: { record: string; principal: string; verdict: string }[]; agenda?: string[] }): string {

package/src/workspace/change-set.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://intentius.io/chant/schemas/workspace/change-set/v1/change-set.schema.json",
   "title": "change-set document",
-  "description": "One change set across planners (#3181): what a combined run's chant, terraform, tofu, choudoufu and warden members will change, a summary, and the digest a gate binds. Written by the composeChangeSet Op activity and by composeChangeSet in @intentius/chant/change-set. Version 1 of the workspace read contract. Readers ignore fields they do not know; a field is only ever added within a version.",
+  "description": "One change set across planners (#3181): what a combined run's chant, terraform, tofu, choudoufu, warden and sql members will change, a summary, and the digest a gate binds. Written by the composeChangeSet Op activity and by composeChangeSet in @intentius/chant/change-set. Version 1 of the workspace read contract. Readers ignore fields they do not know; a field is only ever added within a version.",
   "type": "object",
   "required": [
     "$schema",
@@ -87,7 +87,8 @@
             "tofu",
             "choudoufu",
             "chant",
-            "warden"
+            "warden",
+            "sql"
           ]
         },
         "scope": {
@@ -171,7 +172,8 @@
             "tofu",
             "choudoufu",
             "chant",
-            "warden"
+            "warden",
+            "sql"
           ]
         },
         "address": {

package/src/workspace/ci-green-workflow.test.ts

@@ -124,15 +124,15 @@ describe("the token the tick pushes its tags with (#3573)", () => {
     expect(steps[2].env.GITHUB_TOKEN).toBe("${{ github.token }}");
   });
 
-  test("--token-secret checks out with the secret, so the push uses it, and nothing else changes", () => {
+  test("--token-secret checks out with the secret, or the Actions token where it is unset (#3624), and nothing else changes", () => {
     const plain = renderCiGreenWorkflow(base);
     const text = renderCiGreenWorkflow({ ...base, push: { secret: "CI_GREEN_TOKEN" } });
     const steps = (parseYAMLDocument(text) as Yaml).jobs.tick.steps;
-    expect(steps[0]).toEqual({ uses: "actions/checkout@v6", with: { ref: "main", "fetch-depth": 0, token: "${{ secrets.CI_GREEN_TOKEN }}" } });
+    expect(steps[0]).toEqual({ uses: "actions/checkout@v6", with: { ref: "main", "fetch-depth": 0, token: "${{ secrets.CI_GREEN_TOKEN || github.token }}" } });
     // Check runs are still read with the Actions token: a fine-grained token can't call the Checks API.
     expect(steps[2].env.GITHUB_TOKEN).toBe("${{ github.token }}");
     expect((parseYAMLDocument(text) as Yaml).permissions).toEqual({ contents: "write", checks: "read" });
-    expect(text.replace("          token: ${{ secrets.CI_GREEN_TOKEN }}\n", "")).toBe(plain);
+    expect(text.replace("          token: ${{ secrets.CI_GREEN_TOKEN || github.token }}\n", "")).toBe(plain);
   });
 
   test("--app-id-var and --app-key-secret mint an App token before the checkout and check out with it", () => {
@@ -228,7 +228,7 @@ describe("chant ci workflow (#3573)", () => {
       const withToken = readFileSync(file, "utf-8");
       expect(withToken.split("\n")[0]).toBe(`# ${GENERATED_MARKER}. Regenerate with: chant ci workflow --token-secret CI_GREEN_TOKEN (in the workspace root)`);
       const steps = (parseYAMLDocument(withToken) as Yaml).jobs.tick.steps;
-      expect(steps[0].with.token).toBe("${{ secrets.CI_GREEN_TOKEN }}");
+      expect(steps[0].with.token).toBe("${{ secrets.CI_GREEN_TOKEN || github.token }}");
       expect(steps[2].env.GITHUB_TOKEN).toBe("${{ github.token }}");
 
       const app = { args: { ciAppIdVar: "CI_GREEN_APP_ID", ciAppKeySecret: "CI_GREEN_APP_KEY" } } as unknown as CommandContext;

package/src/workspace/ci-green-workflow.ts

@@ -27,7 +27,9 @@
  * commit whose workflow files differ from the default branch's as an update
  * to those workflows, and the Actions token can never hold the `workflows`
  * permission, so it is refused there. `--token-secret <NAME>` checks out
- * with `secrets.<NAME>` instead, and `--app-id-var <VAR> --app-key-secret
+ * with `secrets.<NAME>` instead, falling back to the Actions token where the
+ * secret is unset (#3624), so a fork or a fresh clone still tags the commits
+ * that change no workflow file; and `--app-id-var <VAR> --app-key-secret
  * <NAME>` mints a GitHub App token first and checks out with that. The
  * tick's own `GITHUB_TOKEN`, which reads check runs, stays the Actions token:
  * a fine-grained personal access token can't call the Checks API.
@@ -44,6 +46,7 @@ import { GENERATED_MARKER } from "../discovery/files";
 import { parseYAMLDocument } from "../yaml";
 import type { CiGreen } from "./declaration";
 import { matchesCheckRun } from "./ci-green";
+import { githubSecretOrJobToken } from "../ci-jobs";
 
 /** Where the workflow goes, relative to the repository root. */
 export const CI_GREEN_WORKFLOW_FILE = ".github/workflows/chant-ci-green.yml";
@@ -185,7 +188,7 @@ export function renderCiGreenWorkflow(input: WorkflowInput): string {
           `          private-key: \${{ secrets.${push.appKeySecret} }}`,
         ]
       : [];
-  const token = !push ? [] : ["secret" in push ? `          token: \${{ secrets.${push.secret} }}` : "          token: ${{ steps.app-token.outputs.token }}"];
+  const token = !push ? [] : ["secret" in push ? `          token: ${githubSecretOrJobToken(push.secret)}` : "          token: ${{ steps.app-token.outputs.token }}"];
   const lines = [
     `name: ${CI_GREEN_WORKFLOW_NAME}`,
     "",

package/src/workspace/class-data.test.ts

@@ -0,0 +1,64 @@
+/**
+ * #3888: the principals file read by hand, for the gate-decision bundle,
+ * accepts and refuses what chant's ajv-checked `parseClassData` does.
+ */
+
+import { describe, expect, test } from "vitest";
+import { classDataShapeProblems, parseClassDataByHand } from "./class-data";
+import { parseClassData } from "./principal-classes";
+
+const ok = { name: "operator", description: "people who apply infrastructure", role: "ops" };
+
+const FILES: unknown[] = [
+  { schema: 1, classes: [ok] },
+  { $schema: "x", $comment: "y", "x-note": 3, schema: 1, classes: [{ ...ok, "x-extra": true }] },
+  { schema: 1, classes: [ok, { name: "reviewer", description: "r", role: "reviewer" }] },
+  { schema: 1, classes: [ok, { ...ok, role: "other" }] },
+  { schema: 1, classes: [{ ...ok, name: "agent" }] },
+  { schema: 1, classes: [{ ...ok, role: "runner" }] },
+  { schema: 1, classes: [ok, { ...ok, name: "other" }] },
+  { schema: 2, classes: [ok] },
+  { schema: "1", classes: [ok] },
+  { classes: [ok] },
+  { schema: 1 },
+  { schema: 1, classes: [] },
+  { schema: 1, classes: {} },
+  { schema: 1, classes: [ok], extra: 1 },
+  { $schema: 3, schema: 1, classes: [ok] },
+  { $comment: null, schema: 1, classes: [ok] },
+  { schema: 1, classes: [{ ...ok, other: 1 }] },
+  { schema: 1, classes: [{ name: ok.name, role: ok.role }] },
+  { schema: 1, classes: [{ name: ok.name, description: ok.description }] },
+  { schema: 1, classes: [{ description: ok.description, role: ok.role }] },
+  { schema: 1, classes: [{ ...ok, name: "Operator" }] },
+  { schema: 1, classes: [{ ...ok, name: "x-operator" }] },
+  { schema: 1, classes: [{ ...ok, name: "a".repeat(40) }] },
+  { schema: 1, classes: [{ ...ok, name: "a".repeat(41) }] },
+  { schema: 1, classes: [{ ...ok, name: "1op" }] },
+  { schema: 1, classes: [{ ...ok, name: 7 }] },
+  { schema: 1, classes: [{ ...ok, description: "" }] },
+  { schema: 1, classes: [{ ...ok, description: 1 }] },
+  { schema: 1, classes: [{ ...ok, role: "Ops" }] },
+  { schema: 1, classes: [{ ...ok, role: "ops role" }] },
+  { schema: 1, classes: [{ ...ok, role: "op-s2" }] },
+  { schema: 1, classes: [null] },
+  { schema: 1, classes: ["operator"] },
+  [],
+  null,
+  "text",
+];
+
+describe("the principals file read without ajv", () => {
+  test.each(FILES.map((f) => [JSON.stringify(f), f]))("%s reads to the classes ajv's check gives", (_, file) => {
+    const text = JSON.stringify(file);
+    const byAjv = parseClassData(text, "@acme/p");
+    const byHand = parseClassDataByHand(text, "@acme/p");
+    expect(byHand.classes).toEqual(byAjv.classes);
+    expect(byHand.problems.length > 0).toBe(byAjv.problems.length > 0);
+    expect(classDataShapeProblems(file, "@acme/p").length === 0).toBe(byAjv.classes.length > 0 || byAjv.problems.every((p) => /core|twice|another class/.test(p)));
+  });
+
+  test("text that is not JSON", () => {
+    expect(parseClassDataByHand("{", "@acme/p")).toEqual(parseClassData("{", "@acme/p"));
+  });
+});

package/src/workspace/class-data.ts

@@ -0,0 +1,236 @@
+/**
+ * Reading the principal classes a pinned package supplies, without ajv or
+ * any package code (#3888).
+ *
+ * `./principal-classes.ts` reads a package's `./workspace-principals` file
+ * for chant, validating it with ajv against
+ * `workspace-principals.schema.json`. `@intentius/chant/gate-decision` reads
+ * the same files from a bare clone and must bundle without ajv, so the rules
+ * both share live here: where a package's export points, where an installed
+ * package is, what a file must hold beyond its schema, and how classes from
+ * several pins merge. {@link classDataShapeProblems} is the schema written
+ * out by hand for the bundle; `class-data.test.ts` holds it to ajv's answer.
+ *
+ * The module imports node:fs and node:path and nothing else.
+ */
+
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { dirname, join, posix, resolve } from "node:path";
+import { CORE_CLASSES, CORE_PRINCIPAL_CLASSES, type PrincipalClass } from "./identity-gate-rule";
+
+/** The subpath a package publishes its principal classes at. */
+export const PRINCIPALS_SUBPATH = "./workspace-principals";
+
+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[];
+}
+
+/** 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;
+    }
+  };
+}
+
+/**
+ * The directory of an installed package `name`, found the way Node finds a
+ * bare import: `node_modules/<name>` in `fromDir` and each directory above it.
+ * It looks for the directory, not for an entry point, so it works for a
+ * package whose `exports` don't expose `package.json`.
+ */
+export function findInstalledPackage(name: string, fromDir: string): string | undefined {
+  for (let dir = resolve(fromDir); ; dir = dirname(dir)) {
+    const candidate = join(dir, "node_modules", ...name.split("/"));
+    try {
+      if (statSync(candidate).isDirectory() && existsSync(join(candidate, "package.json"))) return candidate;
+    } catch {
+      // Not here; keep walking.
+    }
+    if (dirname(dir) === dir) return undefined;
+  }
+}
+
+/**
+ * The file a package's `exports[subpath]` names: undefined when it names
+ * none, a problem when it is not one `.json` file inside the package.
+ */
+export function dataExportTarget(pkg: Record<string, unknown>, subpath: string): 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>)[subpath];
+  if (entry === undefined) return undefined;
+  let target: unknown = entry;
+  if (target && typeof target === "object" && !Array.isArray(target)) {
+    const conditions = target as Record<string, unknown>;
+    target = conditions.default ?? conditions.import ?? conditions.require;
+  }
+  if (typeof target !== "string") {
+    return { problem: `exports["${subpath}"] must name one file, as a string or a "default" condition` };
+  }
+  if (!target.startsWith("./") || !target.endsWith(".json")) {
+    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;
+}
+
+// ── The file ─────────────────────────────────────────────────────────────────
+
+const NAME = /^(?!x-)[a-z][a-z0-9-]{0,39}$/u;
+const ROLE = /^[a-z][a-z0-9-]*$/u;
+const isObject = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null && !Array.isArray(v);
+const extra = (key: string, known: readonly string[]) => !known.includes(key) && !key.startsWith("x-");
+
+/**
+ * What `workspace-principals.schema.json` refuses in `raw`, one line each,
+ * written out by hand so the gate-decision bundle needs no ajv. Empty when
+ * the schema accepts it.
+ */
+export function classDataShapeProblems(raw: unknown, source: string): string[] {
+  const p: string[] = [];
+  const say = (where: string, what: string) => p.push(`${source}: ${where || "the principals file"} ${what}`);
+  if (!isObject(raw)) {
+    say("", "must be object");
+    return p;
+  }
+  for (const key of Object.keys(raw)) if (extra(key, ["$schema", "$comment", "schema", "classes"])) say("", `must NOT have additional property ${key}`);
+  for (const key of ["$schema", "$comment"]) if (key in raw && typeof raw[key] !== "string") say(`/${key}`, "must be string");
+  if (!("schema" in raw)) say("", "must have required property 'schema'");
+  else if (raw.schema !== 1) say("/schema", "must be equal to constant 1");
+  if (!("classes" in raw)) say("", "must have required property 'classes'");
+  else if (!Array.isArray(raw.classes)) say("/classes", "must be array");
+  else {
+    if (raw.classes.length < 1) say("/classes", "must NOT have fewer than 1 items");
+    raw.classes.forEach((c: unknown, i: number) => {
+      const at = `/classes/${i}`;
+      if (!isObject(c)) return say(at, "must be object");
+      for (const key of Object.keys(c)) if (extra(key, ["name", "description", "role"])) say(at, `must NOT have additional property ${key}`);
+      for (const key of ["name", "description", "role"]) if (!(key in c)) say(at, `must have required property '${key}'`);
+      if ("name" in c && (typeof c.name !== "string" || !NAME.test(c.name))) say(`${at}/name`, "must be a class name");
+      if ("description" in c && (typeof c.description !== "string" || [...c.description].length < 1)) say(`${at}/description`, "must be a non-empty string");
+      if ("role" in c && (typeof c.role !== "string" || !ROLE.test(c.role))) say(`${at}/role`, "must be a role name");
+    });
+  }
+  return [...new Set(p)];
+}
+
+const CORE_ROLES = new Set(CORE_CLASSES.map((c) => c.role).filter((r): r is string => r !== null));
+
+/**
+ * The classes in a principals file the schema accepts, under 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 checkClassData(valid: { classes: { name: string; description: string; role: string }[] }, source: string): ClassData {
+  const problems: string[] = [];
+  const classes: PrincipalClass[] = [];
+  const names = new Set<string>();
+  const roles = new Set<string>();
+  for (const c of valid.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 principals file's text read with {@link classDataShapeProblems} for the schema: what chant's ajv-checked `parseClassData` reads, by the same rules. */
+export function parseClassDataByHand(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 problems = classDataShapeProblems(raw, source);
+  return problems.length > 0 ? { classes: [], problems } : checkClassData(raw as Parameters<typeof checkClassData>[0], source);
+}
+
+/** Read the classes a package publishes at `./workspace-principals` through `files`, checking the file with `parse`. Imports nothing. A package that publishes none supplies none. */
+export function readClassFiles(files: PackageFiles, source: string, parse: (text: string, source: string) => ClassData): 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 = dataExportTarget(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 parse(text, source);
+}
+
+/** One pin's classes, as read. */
+export interface PinClassRead {
+  /** The pin's index in the declaration's `pins`. */
+  pin: number;
+  source: string;
+  read: ClassData;
+}
+
+/**
+ * The domain classes of every pin, in pin order and file order. A class
+ * name, or a role, two pins both supply is a problem, and every class
+ * involved is left out, so a rule naming it reads it as unknown and fails
+ * closed.
+ */
+export function mergePinClasses(reads: readonly PinClassRead[]): { classes: PrincipalClass[]; problems: { pin: number; message: string }[] } {
+  const problems: { pin: number; message: string }[] = [];
+  const extra: PrincipalClass[] = [];
+  const byName = new Map<string, string>();
+  const byRole = new Map<string, string>();
+  const clashing = new Set<string>();
+  for (const { pin: i, source, read } of reads) {
+    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 { classes: extra.filter((c) => !clashing.has(c.name)), problems };
+}

package/src/workspace/kinds.ts

@@ -17,13 +17,14 @@
  * fails ({@link resolveKind}).
  */
 
-import { existsSync, readFileSync, statSync } from "node:fs";
+import { readFileSync } from "node:fs";
 import { createRequire } from "node:module";
-import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { isAbsolute, join, relative, resolve } from "node:path";
 import schema from "./workspace-kinds.schema.json" with { type: "json" };
 import type { WorkspaceTree } from "./tree";
 import { joinPath, skippedDir } from "./tree";
 import { checkPinIntegrity } from "./pin-integrity";
+import { dataExportTarget, findInstalledPackage } from "./class-data";
 
 export const KINDS_SCHEMA_ID = schema.$id;
 
@@ -428,22 +429,7 @@ export interface PackageKinds extends KindData {
  * subpath to code, which chant never runs for plugin data.
  */
 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>)[subpath];
-  if (entry === undefined) return undefined;
-  let target: unknown = entry;
-  if (target && typeof target === "object" && !Array.isArray(target)) {
-    const conditions = target as Record<string, unknown>;
-    target = conditions.default ?? conditions.import ?? conditions.require;
-  }
-  if (typeof target !== "string") {
-    return { problem: `exports["${subpath}"] must name one file, as a string or a "default" condition` };
-  }
-  if (!target.startsWith("./") || !target.endsWith(".json")) {
-    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;
+  return dataExportTarget(pkg, subpath);
 }
 
 /** Read the kinds a package directory publishes. Reads files only; imports nothing. */
@@ -515,23 +501,8 @@ export function substituteGraphConfig(config: Record<string, unknown>, at: Graph
   return walk(config) as Record<string, unknown>;
 }
 
-/**
- * The directory of an installed package `name`, found the way Node finds a
- * bare import: `node_modules/<name>` in `fromDir` and each directory above it.
- * It looks for the directory, not for an entry point, so it works for a
- * package whose `exports` don't expose `package.json`.
- */
-export function findInstalledPackage(name: string, fromDir: string): string | undefined {
-  for (let dir = resolve(fromDir); ; dir = dirname(dir)) {
-    const candidate = join(dir, "node_modules", ...name.split("/"));
-    try {
-      if (statSync(candidate).isDirectory() && existsSync(join(candidate, "package.json"))) return candidate;
-    } catch {
-      // Not here; keep walking.
-    }
-    if (dirname(dir) === dir) return undefined;
-  }
-}
+/** Where an installed package is, as Node finds a bare import (`./class-data.ts`, so the gate-decision bundle shares it). */
+export { findInstalledPackage };
 
 export interface PinLike {
   package: string | null;