@intentius/chant 0.124.14 → 0.124.15

package/src/discovery/fold-build-parity.test.ts

@@ -0,0 +1,71 @@
+/**
+ * chant#3612 — `build()` and `foldProject` report the same entities, under the
+ * same names, with the same provenance, for projects that use composites.
+ *
+ * The two share `collectEntities` and `foldProvenanceOfEntities`; what could
+ * still differ is what each hands them. These fixtures are real examples, one
+ * per lexicon whose composites a project calls, built the way `chant build`
+ * builds them (fold on, the plugins' intrinsics, the lexicon names).
+ */
+import { describe, test, expect, beforeAll } from "vitest";
+import { join, resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { build } from "../build";
+import { foldProject, type FoldProvenance } from "../index";
+import { findInfraFiles } from "./files";
+import { loadPlugins, resolveProjectLexicons } from "../cli/plugins";
+import type { LexiconPlugin } from "../lexicon";
+
+const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), "../../../..");
+
+const FIXTURES = [
+  "lexicons/aws/examples/fargate-alb",
+  "lexicons/aws/examples/lambda-function",
+  "lexicons/aws/examples/multi-service-alb",
+  "lexicons/k8s/examples/batch-workers",
+  "lexicons/k8s/examples/web-platform",
+  "lexicons/sql/examples/postgres-composites",
+];
+
+describe("build() and foldProject agree on composite-using projects (chant#3612)", () => {
+  // Loading a lexicon (aws's generated barrel above all) is the slow part, and
+  // it is not what the tests measure, so it happens once, up front.
+  const pluginsOf = new Map<string, LexiconPlugin[]>();
+  beforeAll(async () => {
+    for (const fixture of FIXTURES) {
+      const project = join(repoRoot, fixture);
+      pluginsOf.set(fixture, await loadPlugins(await resolveProjectLexicons(project)));
+    }
+  }, 60_000);
+
+  test.each(FIXTURES)("%s", async (fixture) => {
+    const src = join(repoRoot, fixture, "src");
+    const plugins = pluginsOf.get(fixture)!;
+    const intrinsics = plugins.flatMap((p) => p.intrinsics?.() ?? []);
+    const lexicons = plugins.map((p) => p.name);
+
+    const built = await build(src, plugins.map((p) => p.serializer), undefined, { fold: true, intrinsics, lexicons });
+    expect(built.errors).toEqual([]);
+
+    const files = await findInfraFiles(src);
+    const verdicts = await foldProject(files, intrinsics, { lexicons });
+    // Same verdict per file. A file that runs (a `chant.config.ts` in `src`)
+    // has no fold provenance in foldProject, so it is left out of both sides.
+    const mode = new Map(built.foldDecisions.map((d) => [d.file, d.mode]));
+    const folded: FoldProvenance = {};
+    for (const [file, verdict] of verdicts) {
+      expect({ file, verdict: verdict.verdict }).toEqual({ file, verdict: mode.get(file) });
+      Object.assign(folded, verdict.foldProvenance);
+    }
+    const foldedFiles = new Set(files.filter((file) => verdicts.get(file)!.verdict === "fold"));
+    expect(foldedFiles.size).toBeGreaterThan(0);
+    const fromBuild = Object.fromEntries(
+      Object.entries(built.foldProvenance).filter(([, record]) => foldedFiles.has(record.sourceFile ?? "")),
+    );
+
+    // The fixture has to exercise a composite, or the comparison proves nothing.
+    expect(Object.values(fromBuild).some((record) => record.composite !== undefined)).toBe(true);
+    expect(Object.keys(folded).sort()).toEqual(Object.keys(fromBuild).sort());
+    expect(folded).toEqual(fromBuild);
+  });
+});

package/src/discovery/fold-import.ts

@@ -60,6 +60,7 @@ import {
 import { getInterpolationFields, getProvenance, setPathProvenance, setProvenance } from "../provenance";
 import { foldProvenanceOfEntities, type FoldProvenance } from "../fold-provenance";
 import { collectEntities } from "./collect";
+import { hostCompositeName, markHostCompositeInstance } from "./host-composite";
 import { intrinsicCallFoldsEagerly, intrinsicTagFolds, type IntrinsicDef } from "../lexicon";
 import type { BuildParamValue } from "../build-params";
 
@@ -3056,53 +3057,6 @@ async function interpretCompositeFactory(
   }
 }
 
-/**
- * chant#3598 — a host composite instance's own marker. Non-enumerable and
- * symbol-keyed, like provenance, so nothing that serializes or compares the
- * exports sees it. It carries the composite's name, which the members object
- * otherwise has no record of once it is returned.
- */
-const HOST_COMPOSITE_INSTANCE = Symbol.for("chant.fold.hostCompositeInstance");
-
-/**
- * Mark `members` as the instance a host's composite produced, and return it
- * unchanged.
- *
- * chant#3608 — every declarable member, and every member of a nested host
- * instance, is also stamped with the composite, the way `expandComposite`
- * stamps a chant instance's members. A destructured member is never expanded,
- * so this is the only record it has that a composite wrote it, and without
- * it a path the fold did not attribute reads as authored and so `direct`.
- * `setProvenance` keeps the first writer, and a nested instance was marked
- * when its own call returned, so a member keeps its innermost composite.
- */
-function markHostCompositeInstance(members: Record<string, unknown>, compositeName: string): Record<string, unknown> {
-  if (Object.isExtensible(members) && !Object.prototype.hasOwnProperty.call(members, HOST_COMPOSITE_INSTANCE)) {
-    Object.defineProperty(members, HOST_COMPOSITE_INSTANCE, {
-      value: compositeName,
-      enumerable: false,
-      configurable: true,
-    });
-  }
-  stampHostCompositeMembers(members, compositeName);
-  return members;
-}
-
-/** Stamp `composite` on each declarable member of a host instance, descending into nested host instances. */
-function stampHostCompositeMembers(members: Record<string, unknown>, compositeName: string): void {
-  for (const member of Object.values(members)) {
-    if (isDeclarable(member)) setProvenance(member, { composite: compositeName });
-    else if (hostCompositeName(member) !== undefined) stampHostCompositeMembers(member as Record<string, unknown>, compositeName);
-  }
-}
-
-/** The composite name a host composite instance was marked with, or `undefined` for any other value. */
-function hostCompositeName(value: unknown): string | undefined {
-  if (!isIndexableObject(value)) return undefined;
-  const name = (value as Record<symbol, unknown>)[HOST_COMPOSITE_INSTANCE];
-  return typeof name === "string" ? name : undefined;
-}
-
 /** Evaluate an admissible factory body's statements in order, binding each `const`, and return the `return` expression's value. */
 async function interpretFactoryBody(
   fn: ts.ArrowFunction | ts.FunctionExpression,
@@ -5081,7 +5035,7 @@ export async function foldProject(
       const attempt = attempts.get(file);
       return {
         file,
-        exports: attempt?.ok === true ? expandHostCompositeExports(Object.fromEntries(attempt.exportedValues)) : {},
+        exports: attempt?.ok === true ? Object.fromEntries(attempt.exportedValues) : {},
       };
     }),
   );
@@ -5153,71 +5107,6 @@ function foldProvenanceByFile(
   return out;
 }
 
-/**
- * chant#3598 — a file's exports with every host composite instance replaced by
- * its members, for {@link foldProvenanceByFile} only.
- *
- * A host's registration form (chant#2442) returns the members object the
- * factory built, not a chant `CompositeInstance`, because wrapping it would run
- * chant's member validation against the host's own entities. `collectEntities`
- * expands only chant's instances, so an instance exported whole
- * (`export const store = Store({...})`) contributed no entity and therefore no
- * record, while a destructured member, a plain declarable export, did.
- *
- * The members are named and stamped the way `expandComposite` names and stamps
- * a chant instance: `${exportName}${Member}`, with a whole-entity `composite`
- * origin under the paths the fold already attributed. That origin is written
- * before `collectEntities` adds its `authored` one, and the first writer wins,
- * so a path the fold did not attribute is `unknown` rather than `direct`.
- *
- * Only a top-level export is expanded. A host instance nested in another
- * composite's body or placed in an array does not fold today, so its file is
- * `run` and has no record to give.
- *
- * The exports a caller receives in the verdict are the originals.
- */
-function expandHostCompositeExports(exports: Record<string, unknown>): Record<string, unknown> {
-  const out: Record<string, unknown> = {};
-  for (const [name, value] of Object.entries(exports)) {
-    if (hostCompositeName(value) === undefined) {
-      out[name] = value;
-      continue;
-    }
-    expandHostCompositeInstance(name, value as Record<string, unknown>, name, out);
-  }
-  return out;
-}
-
-/**
- * chant#3608 — one host instance's members into `out`, a nested host instance
- * expanded in place under its member's name (`siteMainBucket`), as
- * `expandComposite` expands a nested chant instance. Every member belongs to
- * the top-level `instance`; its composite is the innermost one, which
- * {@link markHostCompositeInstance} already stamped, so the whole-entity
- * origin names that composite too.
- */
-function expandHostCompositeInstance(
-  prefix: string,
-  members: Record<string, unknown>,
-  instance: string,
-  out: Record<string, unknown>,
-): void {
-  const compositeName = hostCompositeName(members) as string;
-  for (const [memberName, member] of Object.entries(members)) {
-    if (memberName.length === 0) continue;
-    const fullName = `${prefix}${memberName[0].toUpperCase()}${memberName.slice(1)}`;
-    if (hostCompositeName(member) !== undefined) {
-      expandHostCompositeInstance(fullName, member as Record<string, unknown>, instance, out);
-      continue;
-    }
-    if (!isDeclarable(member)) continue;
-    setProvenance(member, { composite: compositeName, compositeInstance: instance });
-    const composite = getProvenance(member)?.composite ?? compositeName;
-    setPathProvenance(member, "", { kind: "composite", composite, instance });
-    out[fullName] = member;
-  }
-}
-
 /** The deepest directory every one of `files` sits under. */
 function commonDirectory(files: readonly string[]): string {
   const split = files.map((file) => dirname(resolvePath(file)).split(sep));

package/src/discovery/fold-project-provenance.test.ts

@@ -394,11 +394,15 @@ describe("foldProject provenance for host composites (chant#3608)", () => {
     expect(provenance.bucket.composite).toBe("Archive");
     expect(provenance.bucket.fields).toEqual({ name: unknown, versioned: unknown });
 
-    // build() does not expand a host instance exported whole, so the
-    // destructured member is the one it can be held to.
-    const built = await build(join(root, "archive"), [namesSerializer], undefined, { fold: true });
+    // chant#3612 — build() expands the whole instance too, and agrees on every record.
+    const built = await build(join(root, "archive"), [namesSerializer], undefined, {
+      fold: true,
+      lexiconPackages: ["@tsad/shapes-3608"],
+      sandbox: true,
+    });
     expect(built.errors).toEqual([]);
-    expect(built.foldProvenance.bucket).toEqual(provenance.bucket);
+    expect([...built.entities.keys()].sort()).toEqual(["archiveBucket", "bucket"]);
+    expect(built.foldProvenance).toEqual(provenance);
   });
 
   test("a whole instance's nested composite members have records, and the innermost composite wins", async () => {
@@ -458,6 +462,19 @@ describe("foldProject provenance for host composites (chant#3608)", () => {
     expect(provenance.mainBucket.fields).toMatchObject({ name: innerName("main"), tier: innerTier("main") });
     expect(provenance.fixedBucket.fields).toMatchObject({ name: innerName("fixed"), tier: innerTier("fixed") });
     expect(provenance.side.fields.name).toMatchObject({ kind: "composite-parameter", composite: "Outer", parameters: ["name"] });
+
+    // chant#3612 — build() given the same host package reports the same
+    // entities and the same records. Before, it emitted nothing for `site`
+    // and, with the host off the allowlist, ran the file and read `side` as direct.
+    const built = await build(join(root, "site"), [namesSerializer], undefined, {
+      fold: true,
+      lexiconPackages: ["@tsad/shapes-3608"],
+      sandbox: true,
+    });
+    expect(built.errors).toEqual([]);
+    expect(built.foldDecisions.map((d) => d.mode)).toEqual(["fold"]);
+    expect([...built.entities.keys()].sort()).toEqual(Object.keys(provenance).sort());
+    expect(built.foldProvenance).toEqual(provenance);
   });
 });
 

package/src/discovery/host-composite.ts

@@ -0,0 +1,101 @@
+import { isDeclarable, type Declarable } from "../declarable";
+import { getProvenance, setPathProvenance, setProvenance } from "../provenance";
+
+/**
+ * chant#3598 — a host composite instance's own marker. Non-enumerable and
+ * symbol-keyed, like provenance, so nothing that serializes or compares the
+ * exports sees it. It carries the composite's name, which the members object
+ * otherwise has no record of once it is returned.
+ *
+ * Only the fold path sets it: a host's registration form (chant#2442) returns
+ * the members object the factory built, not a chant `CompositeInstance`, and
+ * chant knows the object came from a composite only because the fold resolved
+ * the call. A file that runs instead has no such knowledge.
+ */
+const HOST_COMPOSITE_INSTANCE = Symbol.for("chant.fold.hostCompositeInstance");
+
+function isPlainIndexable(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Mark `members` as the instance a host's composite produced, and return it
+ * unchanged.
+ *
+ * chant#3608 — every declarable member, and every member of a nested host
+ * instance, is also stamped with the composite, the way `expandComposite`
+ * stamps a chant instance's members. A destructured member is never expanded,
+ * so this is the only record it has that a composite wrote it, and without
+ * it a path the fold did not attribute reads as authored and so `direct`.
+ * `setProvenance` keeps the first writer, and a nested instance was marked
+ * when its own call returned, so a member keeps its innermost composite.
+ */
+export function markHostCompositeInstance(
+  members: Record<string, unknown>,
+  compositeName: string,
+): Record<string, unknown> {
+  if (Object.isExtensible(members) && !Object.prototype.hasOwnProperty.call(members, HOST_COMPOSITE_INSTANCE)) {
+    Object.defineProperty(members, HOST_COMPOSITE_INSTANCE, {
+      value: compositeName,
+      enumerable: false,
+      configurable: true,
+    });
+  }
+  stampHostCompositeMembers(members, compositeName);
+  return members;
+}
+
+/** Stamp `composite` on each declarable member of a host instance, descending into nested host instances. */
+function stampHostCompositeMembers(members: Record<string, unknown>, compositeName: string): void {
+  for (const member of Object.values(members)) {
+    if (isDeclarable(member)) setProvenance(member, { composite: compositeName });
+    else if (hostCompositeName(member) !== undefined) stampHostCompositeMembers(member as Record<string, unknown>, compositeName);
+  }
+}
+
+/** The composite name a host composite instance was marked with, or `undefined` for any other value. */
+export function hostCompositeName(value: unknown): string | undefined {
+  if (!isPlainIndexable(value)) return undefined;
+  const name = (value as Record<symbol, unknown>)[HOST_COMPOSITE_INSTANCE];
+  return typeof name === "string" ? name : undefined;
+}
+
+/**
+ * chant#3598, chant#3612 — a host composite instance's members as entities,
+ * for `collectEntities`.
+ *
+ * `collectEntities` is the one place `build()` and `foldProject` turn exports
+ * into entities, so expanding here is what makes the two report the same set:
+ * `export const archive = Archive({...})` gives `archiveBucket` to both.
+ *
+ * The members are named and stamped the way `expandComposite` names and stamps
+ * a chant instance: `${exportName}${Member}`, a nested host instance expanded
+ * in place under its member's name (`siteMainBucket`), with a whole-entity
+ * `composite` origin under the paths the fold already attributed. That origin
+ * is written before `collectEntities` adds its own record, and the first
+ * writer wins, so a path the fold did not attribute is `unknown` rather than
+ * `direct`. Every member belongs to the top-level `instance`; its composite is
+ * the innermost one, which {@link markHostCompositeInstance} already stamped.
+ */
+export function expandHostComposite(
+  prefix: string,
+  members: Record<string, unknown>,
+  instance: string = prefix,
+): Array<[string, Declarable]> {
+  const out: Array<[string, Declarable]> = [];
+  const compositeName = hostCompositeName(members) as string;
+  for (const [memberName, member] of Object.entries(members)) {
+    if (memberName.length === 0) continue;
+    const fullName = `${prefix}${memberName[0].toUpperCase()}${memberName.slice(1)}`;
+    if (hostCompositeName(member) !== undefined) {
+      out.push(...expandHostComposite(fullName, member as Record<string, unknown>, instance));
+      continue;
+    }
+    if (!isDeclarable(member)) continue;
+    setProvenance(member, { composite: compositeName, compositeInstance: instance });
+    const composite = getProvenance(member)?.composite ?? compositeName;
+    setPathProvenance(member, "", { kind: "composite", composite, instance });
+    out.push([fullName, member]);
+  }
+  return out;
+}

package/src/discovery/index.ts

@@ -143,6 +143,16 @@ export interface DiscoveryOptions {
    */
   lexicons?: readonly string[];
 
+  /**
+   * chant#3612 — package specifiers to follow a bare import into, verbatim,
+   * alongside whatever {@link lexicons} names. The same allowlist
+   * `FoldProjectOptions.lexiconPackages` gives `foldProject` (chant#2438), so
+   * a build over a host of its own folds the files `foldProject` folds. A
+   * chant project never needs it: its packages are `lexicons`. Only
+   * meaningful when {@link fold} is set. Default: none.
+   */
+  lexiconPackages?: readonly string[];
+
   /**
    * chant #1045 Phase 2 — opt-in: whatever would otherwise reach the
    * in-process `importModule` step (every file, when {@link fold} isn't set;
@@ -289,7 +299,7 @@ export async function discover(path: string, options?: DiscoveryOptions): Promis
         buildParamValuesMap,
         options.lexicons,
         options.sandbox === true,
-        [],
+        options.lexiconPackages ?? [],
         options.executing === true,
         files,
       )

package/src/gate-decision-bundle.test.ts

@@ -6,7 +6,7 @@
  * rule because `@intentius/chant/op/gate` pulls in zod and the git ledger
  * code. `@intentius/chant/gate-decision` holds the decision for a plan digest
  * under `ledger`, `pr-review` and `sealed`, the seal check over
- * node:crypto, and the `identity.gates` rule with its class check (#3862). This bundles it the way terragucci would and reads esbuild's
+ * node:crypto, and the `identity.gates` rule with its class check (#3862), reading the classes pinned packages supply as data, without ajv (#3888). This bundles it the way terragucci would and reads esbuild's
  * own list of what went in.
  */
 
@@ -15,7 +15,7 @@ import { build } from "esbuild";
 import { describe, expect, test } from "vitest";
 import { REPO } from "./workspace/__fixtures__/contract-repo";
 
-const FORBIDDEN = [/node_modules\//, /\/src\/fold\//, /\/src\/lint\//, /\/src\/codegen\//, /\/src\/lifecycle\/git\.ts$/, /\/src\/lifecycle\/gate-ledger\.ts$/];
+const FORBIDDEN = [/node_modules\//, /\/src\/workspace\/(kinds|principal-classes|pin-integrity)\.ts$/, /\/src\/fold\//, /\/src\/lint\//, /\/src\/codegen\//, /\/src\/lifecycle\/git\.ts$/, /\/src\/lifecycle\/gate-ledger\.ts$/];
 
 describe("the gate-decision bundle", () => {
   test("holds the decision, the seal check and the plan digest, and no package or git code", async () => {
@@ -46,13 +46,14 @@ describe("the gate-decision bundle", () => {
       "packages/core/src/notify.ts",
       "packages/core/src/op/gate-point.ts",
       "packages/core/src/op/op-waves.ts",
+      "packages/core/src/workspace/class-data.ts",
       "packages/core/src/workspace/identity-gate-rule.ts",
       "packages/core/src/workspace/jsonc.ts",
       "packages/core/src/workspace/trust/gate-seal.ts",
       "packages/core/src/workspace/trust/trust-files.ts",
     ]);
-    // About 27 KB today.
+    // About 43 KB unminified today, 7 KB of it the pinned classes read as data (#3888).
     const bytes = result.outputFiles.reduce((n, f) => n + f.contents.byteLength, 0);
-    expect(bytes).toBeLessThan(40 * 1024);
+    expect(bytes).toBeLessThan(48 * 1024);
   });
 });

package/src/gate-decision-identity.test.ts

@@ -139,18 +139,71 @@ describe.skipIf(!hasSshKeygen)("identity.gates read at base, as chant reads it",
     expect(judgeBoth(invalid.r, invalid.base, invalid.approvals).ship![1]).toMatch(/no signers file/);
   });
 
-  test("a domain class the caller read from a pin, and a pin this reader does not load", () => {
-    const { r, base, approvals } = setup(
-      (k) => ({ ".chant/allowed_signers": `alice ${k.alice.pub}\n`, ".chant/trust.json": JSON.stringify({ schema: 1, roles: { operator: ["alice"] } }) }),
-      { pins: [{ package: "@acme/ops-classes", version: "1.0.0" }] },
+  /** A plugin publishing `classes` at ./workspace-principals, as files under `dir`. */
+  const plugin = (dir: string, classes: unknown[], version = "1.0.0"): Record<string, string> => ({
+    [`${dir}/package.json`]: JSON.stringify({ name: "@acme/ops-classes", version, exports: { "./workspace-principals": "./principals.json" } }),
+    [`${dir}/principals.json`]: JSON.stringify({ schema: 1, classes }),
+  });
+  const OPERATOR = { name: "operator", description: "people who apply infrastructure", role: "operator" };
+  const operatorPolicy = (k: Record<string, Key>) => ({
+    ".chant/allowed_signers": `alice ${k.alice.pub}\nbob ${k.bob.pub}\n`,
+    ".chant/trust.json": JSON.stringify({ schema: 1, roles: { operator: ["alice"], runner: ["bob"] } }),
+  });
+  const install = (r: TestRepo, files: Record<string, string>) => {
+    for (const [path, text] of Object.entries(files)) r.write(path, text);
+  };
+
+  test("a class only a pinned package supplies, read from the installed package as chant reads it (#3888)", () => {
+    const { r, base, approvals } = setup(operatorPolicy, { pins: [{ package: "@acme/ops-classes", version: "1.0.0" }] });
+    install(r, plugin("node_modules/@acme/ops-classes", [OPERATOR]));
+    const ours = judgeBoth(r, base, approvals);
+    // alice holds the operator role at base, so she is an operator and no longer human.
+    expect(ours.ops![1]).toBeNull();
+    expect(ours.ops![2]).toBe("BOB  is not in the class operator that gate ops needs: no role grant at base puts them there");
+    expect(ours.deploy![1]).toMatch(/^alice is not in the class human that gate deploy needs/);
+
+    // A bare clone holds no node_modules; the caller names where the packages are installed.
+    const bare = `${r.dir}.git`;
+    r.git(["clone", "-q", "--bare", r.dir, bare]);
+    const fromBare = identityGateAdmissionAt(bare, base, "ops", { packages: r.dir })!;
+    expect(approvals("ops").map((a) => fromBare.refuses(a))).toEqual(ours.ops);
+  });
+
+  test("a path pin's class is read at base, so the change being applied can't remap it", () => {
+    const { r, base, approvals } = setup((k) => ({ ...operatorPolicy(k), ...plugin("plugins/ops", [OPERATOR]) }), { pins: [{ path: "plugins/ops" }] });
+    // After base the plugin moves the operator class to bob's role; base still says operator.
+    install(r, plugin("plugins/ops", [{ ...OPERATOR, role: "runner-ops" }]));
+    r.commit("remaps operator");
+    const ours = judgeBoth(r, base, approvals);
+    expect(ours.ops![1]).toBeNull();
+  });
+
+  test("a pin it cannot read refuses a gate whose class the pin could change, and says why", () => {
+    const { r, base, approvals } = setup(operatorPolicy, { pins: [{ package: "@acme/ops-classes", version: "1.0.0" }] });
+    const missing = identityGateAdmissionAt(r.dir, base, "ops")!;
+    expect(missing.refuses(approvals("ops")[1])).toBe(
+      `identity.gates.ops names the class operator, and the pins in chant.workspace.json at base could not all be read, so no approval can show it is in that class: @acme/ops-classes is not installed under ${r.dir}`,
     );
-    const unread = identityGateAdmissionAt(r.dir, base, "ops")!;
-    expect(unread.refuses(approvals("ops")[1])).toMatch(/is not a core class, and this reader does not load the classes the pinned packages in chant\.workspace\.json at base supply/);
+    // human is everyone in no other class, so an unread pin leaves it unknown too; runner and no class are not affected.
+    expect(identityGateAdmissionAt(r.dir, base, "deploy")!.refuses(approvals("deploy")[1])).toMatch(/names the class human, and the pins .* could not all be read/);
+    expect(identityGateAdmissionAt(r.dir, base, "release")!.refuses(approvals("release")[2])).toBeNull();
+    expect(identityGateAdmissionAt(r.dir, base, "ship")!.refuses(approvals("ship")[1])).toBeNull();
+
+    install(r, plugin("node_modules/@acme/ops-classes", [OPERATOR], "2.0.0"));
+    expect(identityGateAdmissionAt(r.dir, base, "ops")!.refuses(approvals("ops")[1])).toMatch(/: @acme\/ops-classes is pinned at 1\.0\.0, and 2\.0\.0 is installed under /);
+
+    // A class the caller read stands for the pins, as before.
     const read = identityGateAdmissionAt(r.dir, base, "ops", { classes: [{ name: "operator", role: "operator" }] })!;
     expect(read.refuses(approvals("ops")[1])).toBeNull();
     expect(read.refuses(approvals("ops")[0])).toMatch(/not signed/);
   });
 
+  test("an installed package that supplies no such class refuses as chant does", () => {
+    const { r, base, approvals } = setup(operatorPolicy, { pins: [{ package: "@acme/ops-classes", version: "1.0.0" }] });
+    install(r, plugin("node_modules/@acme/ops-classes", [{ ...OPERATOR, name: "deployer" }]));
+    expect(judgeBoth(r, base, approvals).ops![1]).toMatch(/names the class operator, which no pinned package supplies, .*known classes: human, agent, runner, service, deployer/);
+  });
+
   test("passed to decideGateApproval as refuses, it counts what chant's wave gate counts", async () => {
     const { r, base, approvals } = setup((k) => ({
       ".chant/allowed_signers": `alice ${k.alice.pub}\nbob ${k.bob.pub}\n`,

package/src/gate-decision.ts

@@ -18,8 +18,9 @@
  *
  * A gate the declaration at base names under `identity.gates` counts only a
  * sealed approval from its class: {@link identityGateAdmissionAt} reads that
- * rule from a bare clone at base and judges by `admitApprover`, the function
- * chant's `gateAdmission` judges by (#3862); pass its `refuses` to
+ * rule from a bare clone at base, with the principal classes the pinned
+ * packages supply read as data (#3888), and judges by `admitApprover`, the
+ * function chant's `gateAdmission` judges by (#3862); pass its `refuses` to
  * {@link decideGateApproval}.
  *
  * With `spend` (#3784), an approval a wave already applied under is spent and
@@ -27,14 +28,17 @@
  * the lines of `_gates/<op>/applied.jsonl` ({@link parseAppliedGateLines}).
  *
  * The module reads the ledger lines and the review it is handed; reading
- * them is the caller's. It imports no TypeScript, esbuild, zod, lint, fold or
- * codegen module, and none of chant's git ledger code, which
+ * them is the caller's. It imports no TypeScript, esbuild, zod, ajv, lint,
+ * fold or codegen module, no package's code, and none of chant's git ledger
+ * code, which
  * `gate-decision-bundle.test.ts` holds it to. Its rules are chant's own:
  * `./lifecycle/gate-ledger-select.ts` is what `evaluateGate` decides by, and
  * `gate-decision.test.ts` decides the same ledgers both ways.
  */
 
 import { spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { join, posix } from "node:path";
 import {
   isPendingGateExpired,
   latestPendingGate,
@@ -50,7 +54,8 @@ import {
   trustConfigProblems,
 } from "./workspace/trust/trust-files";
 import { parseJsonText } from "./workspace/jsonc";
-import { CORE_CLASSES, admitApprover, type ClassGrant, type GateAdmissionRule } from "./workspace/identity-gate-rule";
+import { CORE_CLASSES, admitApprover, type ClassGrant, type GateAdmissionRule, type PrincipalClass } from "./workspace/identity-gate-rule";
+import { diskFiles, findInstalledPackage, mergePinClasses, parseClassDataByHand, readClassFiles, type PinClassRead } from "./workspace/class-data";
 import type { GateResolutionRecord, PendingGateRecord } from "./lifecycle/gate-ledger";
 import type { MergedReview } from "./op/gate-review";
 import type { GateApprovalSource } from "./op/op-waves";
@@ -207,6 +212,56 @@ export interface IdentityGateAdmission {
   refuses(approval: SealedGateApproval): string | null;
 }
 
+/** The domain classes the pins of the declaration at base supply, as chant's `loadClassRegistry` reads them, and the pins that could not be read. */
+interface PinnedClasses {
+  classes: PrincipalClass[];
+  /** Pins whose classes are not known, one line each: a package pin that is not installed, or not at its pinned version. */
+  unread: string[];
+}
+
+/**
+ * Read the classes each pin supplies, as chant's `gateAdmission(cwd, gate,
+ * base)` reads them: a path pin's `./workspace-principals` file from `base`
+ * itself, so a change can't remap a class by editing its own copy of the
+ * plugin; a package pin's from the package installed under `packages` (its
+ * `node_modules` or a parent's), which must be at the pinned version. Reads
+ * data only and imports no package.
+ */
+function pinnedClassesAt(repo: string, base: string, pins: unknown, packages: string): PinnedClasses {
+  const reads: PinClassRead[] = [];
+  const unread: string[] = [];
+  (Array.isArray(pins) ? pins : []).forEach((raw: unknown, i) => {
+    const pin = (raw !== null && typeof raw === "object" ? raw : {}) as { package?: unknown; version?: unknown; path?: unknown };
+    if (typeof pin.path === "string" && pin.path) {
+      const dir = posix.normalize(pin.path);
+      const files = (path: string) => showAt(repo, base, dir === "." ? path : posix.join(dir, path));
+      reads.push({ pin: i, source: pin.path, read: readClassFiles(files, pin.path, parseClassDataByHand) });
+      return;
+    }
+    if (typeof pin.package !== "string" || !pin.package) return;
+    const dir = findInstalledPackage(pin.package, packages);
+    if (!dir) {
+      unread.push(`${pin.package} is not installed under ${packages}`);
+      return;
+    }
+    let installed: unknown;
+    try {
+      installed = (JSON.parse(readFileSync(join(dir, "package.json"), "utf-8")) as { version?: unknown }).version;
+    } catch {
+      installed = undefined;
+    }
+    if (typeof pin.version === "string" && pin.version && installed !== pin.version) {
+      unread.push(`${pin.package} is pinned at ${pin.version}, and ${String(installed ?? "an unknown version")} is installed under ${packages}`);
+      return;
+    }
+    reads.push({ pin: i, source: pin.package, read: readClassFiles(diskFiles(dir), pin.package, parseClassDataByHand) });
+  });
+  return { classes: mergePinClasses(reads).classes, unread };
+}
+
+/** The core classes whose members no domain class can change: every one but `human`, which is the principals in no other class. */
+const PIN_FREE = new Set(CORE_CLASSES.filter((c) => c.role !== null).map((c) => c.name));
+
 /**
  * The `identity.gates` rule for `gate` at `base`, or null when the
  * declaration there names none: what chant's `gateAdmission(cwd, gate, base)`
@@ -215,34 +270,39 @@ export interface IdentityGateAdmission {
  * class, the role grants in `.chant/trust.json` at base put the approver in
  * it. Both judge with the same function ({@link admitApprover}).
  *
- * The classes are the four core ones, then `classes`, the domain classes the
- * caller read from the pinned packages (`./workspace-principals`), in pin
- * order. This reader loads no package. A gate whose class is in neither
- * refuses every approval, and when the declaration at base pins anything the
- * reason says the pins were not read, since one of them may supply it.
+ * The classes are the four core ones, then the domain classes the
+ * declaration's pins supply, in pin order (#3888), read as chant reads them:
+ * a path pin's `./workspace-principals` file at `base`, and a package pin's
+ * from the package installed under `packages` (default `repo`) at the
+ * pinned version. A bare clone has no `node_modules`, so a caller that reads
+ * one passes the directory its packages are installed under. Only data is
+ * read; no package is imported. `classes`, when given, stands for every
+ * domain class instead and no pin is read.
+ *
+ * When a pin can't be read (its package is not installed, or not at the
+ * pinned version), a gate whose class it could change (a domain class, or
+ * `human`) refuses every approval and says which pins were not read; a gate
+ * naming `agent`, `runner` or `service`, or no class, is judged as usual.
  * Throws when the declaration at base cannot be parsed.
  */
 export function identityGateAdmissionAt(
   repo: string,
   base: string,
   gate: string,
-  opts: { classes?: readonly ClassGrant[] } = {},
+  opts: { classes?: readonly ClassGrant[]; packages?: string } = {},
 ): IdentityGateAdmission | null {
   const declaration = declarationAt(repo, base);
   const requirement = declaration === null ? undefined : identityGatesOf(declaration.value).find((g) => g.gate === gate);
   if (!requirement) return null;
   const { signers, roles } = trustAt(repo, base);
   const pins = (declaration!.value as { pins?: unknown }).pins;
-  const rule: GateAdmissionRule = {
-    gate,
-    class: requirement.class,
-    signers,
-    roles,
-    classes: [...CORE_CLASSES, ...(opts.classes ?? [])],
-    ...(Array.isArray(pins) && pins.length > 0
-      ? { unknownClass: `is not a core class, and this reader does not load the classes the pinned packages in ${declaration!.file} at base supply` }
-      : {}),
-  };
+  const pinned = opts.classes ? { classes: opts.classes, unread: [] } : pinnedClassesAt(repo, base, pins, opts.packages ?? repo);
+  const want = requirement.class;
+  if (want !== null && !PIN_FREE.has(want) && pinned.unread.length > 0) {
+    const reason = `identity.gates.${gate} names the class ${want}, and the pins in ${declaration!.file} at base could not all be read, so no approval can show it is in that class: ${pinned.unread.join("; ")}`;
+    return { requirement, refuses: () => reason };
+  }
+  const rule: GateAdmissionRule = { gate, class: want, signers, roles, classes: [...CORE_CLASSES, ...pinned.classes] };
   return { requirement, refuses: (a) => admitApprover(rule, a) };
 }