@intentius/chant 0.100.0 → 0.102.0

package/src/workspace/principal-classes.ts

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

package/src/workspace/read-contract.test.ts

@@ -110,6 +110,30 @@ describe("every schema against the reference workspace (#2543)", () => {
     TIMEOUT,
   );
 
+  test(
+    "graph from the chant repo expands the nested reference workspace read-only, with outer/inner/id ids (#2551)",
+    async () => {
+      const { expectValid } = contract(graphSchema);
+      const before = git(REPO, "status", "--porcelain", "--untracked-files=all", "--", "reference-workspace");
+      for (const at of [undefined, "HEAD"]) {
+        const { doc, failed } = await workspaceGraph({ cwd: REPO, at, members: ["reference-workspace"], reader });
+        expectValid(doc);
+        if ("error" in doc) throw new Error(doc.error.message);
+        expect(failed, JSON.stringify(doc.members)).toBe(false);
+        const nested = doc.members.find((m) => m.name === "reference-workspace")!;
+        expect(nested).toMatchObject({ kind: "workspace", status: "composed", reason: null });
+        expect(nested.nested?.name).toBe("reference");
+        expect(nested.nested?.members.find((m) => m.name === "delivery")).toMatchObject({ status: "composed", dir: "delivery" });
+        expect(doc.nodes.length).toBeGreaterThan(0);
+        expect(doc.nodes.every((n) => n.id.startsWith("reference-workspace/delivery/") && n.member === "reference-workspace" && n.nested === "delivery")).toBe(true);
+        expect(doc.groups.byMember["reference-workspace"]).toEqual(doc.nodes.map((n) => n.id).sort());
+      }
+      // The outer read never writes inside the nested workspace.
+      expect(git(REPO, "status", "--porcelain", "--untracked-files=all", "--", "reference-workspace")).toBe(before);
+    },
+    TIMEOUT,
+  );
+
   test("check, in the working tree and at HEAD", async () => {
     const { expectValid } = contract(checkSchema);
     for (const at of [undefined, "HEAD"]) {

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

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

package/src/workspace/reason-codes.ts

@@ -70,8 +70,9 @@ export const REASONS = {
   "record-supersedes-conflict": "A second closed record supersedes a record another one already superseded.",
   "record-remediates-unknown": "A remediates link names an id no record has.",
   "record-remediates-not-closed": "A remediates link names a record that isn't closed; a record still open is amended instead.",
+  "record-seal-mismatch": "A closed record's seal is not the whole-file seal of its text now: the record changed after it closed.",
   // A review session that isn't valid (records, #2673).
-  "session-seal-mismatch": "A closed session's seal is not the digest of its text: the session changed after it closed.",
+  "session-seal-mismatch": "A closed session's seal is not the whole-file seal of its text now: the session changed after it closed, or was sealed by the rule before #2546.",
   "session-verdict-unknown-record": "A session's verdict names a record that none of the session kind's subject records has.",
   // A record that is valid but warned about (records, #2549).
   "asset-drift": "A file the record pins by hash has changed: its bytes no longer hash to the pinned sha256.",
@@ -91,6 +92,9 @@ export const REASONS = {
   "work-done-gap-open": "A work record is done, and the finding it came from still fires on its region. graph --intent raises it, and records does by walking that region.",
   "work-acceptance-unmet": "A work record is done, and one of its acceptance criteria has no passing evidence of the verification it expects. check fails on it (WSP117).",
   "work-acceptance-self-verified": "A passing manual verdict on a work record's criterion names the record's implementer, so it does not count: a manual verdict comes from someone else.",
+  "work-contract-unknown": "A work record names a contract that no record of its kind's contract kind has.",
+  "work-contract-undecided": "A work record names a contract whose state is not approved, such as a draft.",
+  "work-tier-unknown": "A work record names a builder tier that its kind's work.tier.tiers does not list.",
   // An answer to a decision point that is valid but warned about (records, points, ws-058, #2739).
   "answer-points-unreadable": "The points file the answer kind names can't be read, or is not valid.",
   "answer-point-unknown": "The answer's point is not declared in the points file the answer kind names.",
@@ -105,7 +109,7 @@ export const REASONS = {
   "seal-missing": "The verdict, or the record, carries no seal.",
   "seal-signer-unlisted": "The reviewer, or the record's author, has no key in the signers file at base, so the seal can't count.",
   "seal-signature-invalid": "The seal is malformed, names a signer other than the reviewer or author, or its signature does not verify over the verdict or record.",
-  "seal-unverifiable": "Nothing here can say whose seal it is: there is no signers file at base, or ssh-keygen is not installed.",
+  "seal-unverifiable": "Nothing here can say whose seal it is: there is no signers file at base, ssh-keygen is not installed, or the record came back in a return sealed by a signer no admission lists yet.",
   // A record whose author seal is not attested under a signers file at base (records, #2688). A warning: the record is still read.
   "record-unattested": "A signers file is active at base, and the record names an author whose seal does not verify: it has none, the author has no key in the file, or the signature fails.",
   // A records read that fails (records).
@@ -132,6 +136,13 @@ export const REASONS = {
   "source-harvest-not-proposed": "A harvested record (source.via harvest) was written in a state other than the kind's first: a harvest proposes, and a person decides.",
   "ratify-quorum-not-met": "The write puts a record in its kind's ratified state (reviews.ratified), and the record's quorum is not met: too few agreeing verdicts count.",
   "record-sign-failed": "--sign was given and no author seal could be made: the record names no author, the key can't be read or used, git names no ssh signing key, or ssh-keygen is not installed.",
+  // Write scope (#2548): a records write that is refused, and a commit check --changes reports, outside the writer's scope.
+  "write-scope-member": "The write is to a file, or to a record kind, of a member outside the writer's scope: an agent session writes only its own member, and writeScope.<class>.members leaves the member out.",
+  "write-scope-kind": "The write is to a record kind writeScope.<class>.records does not list, with a verb it does not list for the kind, or deletes a record.",
+  "write-scope-protected": "The write is to a file writeScope.<class>.protected lists, or one under a directory it lists, outside any top-level keys the entry's except allows (#3146).",
+  "write-scope-class-unknown": "The declaration's writeScope at base names a principal class no pinned package supplies, and the writer is judged human, so it may be in that class; the write is refused until the package is installed at the pinned version or the entry removed (#3080).",
+  "agent-unknown": "CHANT_AGENT, or a commit's Chant-Agent trailer, names an agent session the declaration at base does not declare.",
+  "principal-unidentified": "chant.workspace.json at base sets identity.attribution to identified, and the write names a person by a bare name: --by, an author field or a decision point's answerer must be a forge identity (github:<login>, gitlab:<login>, <forge>@<host>:<login>), a principal the signers file at base lists, or an agent, runner or service principal (#3163).",
   // A review given in a session (records review --session, #2693).
   "session-unknown": "--session names no session of a session kind whose subjects are the record's kind.",
   "session-not-open": "--session names a session in a closed state, which takes no more verdicts.",
@@ -151,12 +162,15 @@ export const REASONS = {
   // The intent graph (graph --intent, #2651): a read that fails.
   "intent-region-invalid": "The region's path, or its line range, does not exist in the tree read.",
   "intent-record-unknown": "graph --intent --record names an id that no record of a decision kind read has.",
+  "intent-symbol-unsupported": "The region names a symbol, path#symbol, in a file no symbol resolver reads; a line range still works.",
+  "intent-symbol-unknown": "The region names a symbol the file does not declare in the tree read.",
+  "intent-symbol-ambiguous": "The region names a symbol that matches more than one declaration in the file; its qualified name picks one.",
   // The intent graph: part of the walk that can't be read. The document is still printed.
   "intent-history-shallow": "The repository is a shallow clone, so the region's history stops at the clone's boundary.",
   "intent-plugin-failed": "A kind file's commitJoins, which joins commits to units, contracts and evidence, failed for a commit.",
   // The intent graph: findings, each a node in the graph.
   "intent-commit-undecided": "A commit changed the region when no decision constrained it at path granularity.",
-  "intent-commit-bare": "A commit names no unit, no pull request and no decision covering the region at its time.",
+  "intent-commit-bare": "A commit names no unit, carries no record through its Chant-Record or Chant-Lease trailer, and has no pull request and no decision covering the region at its time.",
   "intent-pin-drifted": "A decision's pinned artifact no longer hashes to the pin.",
   "intent-pin-missing": "A decision's pinned artifact does not exist in the tree read.",
   "intent-pin-stale": "A current decision pins an artifact at the hash a record it supersedes pinned, and the artifact has not changed since: the decision moved on and the artifact did not.",
@@ -172,6 +186,11 @@ export const REASONS = {
   "intent-decision-unimplemented": "A decided decision constrains the region, no work item that is not dropped implements it, and no commit falls in its window.",
   "intent-work-blocked": "A work item constraining the region has commits in its window while a work item it needs is not done.",
   "intent-work-open-decided-code": "Commits in the region are a decision's own work while the work item implementing that decision is still open.",
+  // The intent graph's answer to why the region is like this (#3034): what it can't account for.
+  "intent-why-no-decision": "No current decision governs the region at any granularity, and none is carried out by the commits or runs that made its current lines.",
+  "intent-why-no-run": "None of the region's current lines was made by a commit an agent run is joined to.",
+  "intent-why-uncommitted": "Some of the region's lines are not committed yet.",
+  "intent-why-run-ambiguous": "Some lines come from a commit several agent runs made, and no run's recorded hunks say which wrote them.",
   // The forward coverage check (check --changes, #2773): findings, one per changed path.
   "change-uncovered": "A path the diff changes is covered by no current decided record and no open work item, by path or by its member.",
   "change-out-of-scope": "A record in hand for the change, such as the work item it is for or a decision that item implements, lists a path the diff changes in its out_of_scope.",
@@ -200,6 +219,9 @@ export const REASONS = {
   // A box's intent, the decision record its box block names (check, #2850). Each is also a WSP finding.
   "box-intent-unknown": "A box block names an intent, and no record of a declared kind named decision has that id.",
   "box-intent-unconstrained": "The decision record a box names as its intent constrains no member or path of this workspace: no member: entry for a declared member and no path: entry at, above or inside one's directory.",
+  // Why a workspace isn't plantable (status and graph, #3146): not a finding, since a workspace need not be.
+  "box-none": "No member's box block declares services, so the workspace has no box for a host to plant.",
+  "box-several": "More than one member's box block declares services, and a planted workspace runs one box.",
   // The work lease (chant workspace work claim|renew|release, #2732): why the command could not run.
   "work-kind-missing": "No work kind to find the item in: --kind names a kind with no work block, or the declaration names no work kind.",
   "work-kind-ambiguous": "More than one declared work kind has a record with the id, so --kind must name one.",
@@ -213,9 +235,37 @@ export const REASONS = {
   "lease-token-mismatch": "The live lease on the work item carries another fencing token than the one given.",
   "lease-race": "Another writer changed the lease between this command's read and its write.",
   "lease-push-rejected": "The remote refused the lease push: another clone claimed the item first, or the remote could not be reached.",
+  // The agent run record (chant workspace runs, #3033): why a write was refused, and what a read could not see. Nothing is written on a refusal.
+  "run-exists": "runs start or runs record was given a run id the ledger already has.",
+  "run-unknown": "runs end names a run the ledger has no start for.",
+  "run-ended": "runs end names a run whose end is already recorded.",
+  "runs-no-ledger": "The checkout has no chant/lifecycle branch, so there are no agent runs to read.",
+  "runs-ledger-malformed": "Some lines of the agent run ledger aren't run events; the rest are read.",
   // A box whose isolation fails (check, #2727). Each is also a WSP finding.
   "box-isolation-collision": "Two boxes on one host resolve to the same port, state path or cookie name, or two ports in one box share an offset.",
   "box-isolation-literal": "A host's stateRoot or a box's state entry is a literal machine path instead of one derived from an environment reference and the box's name.",
+  // The signer set's history (signers and verify, #2553): why a version is not a valid rotation of the one before. Nothing verifies past it.
+  "signers-file-missing": "There is no signers file at the base revision, so there is no signer history to read.",
+  "signers-removed": "The signers file was removed. Commits merged before the removal keep the set they were judged by; nothing after it verifies.",
+  "rotation-unparseable": "The rotation file beside the signers file is not JSON.",
+  "rotation-invalid": "The rotation file does not match its shape: schema 1, a version, the previous set's digest, a threshold and signatures.",
+  "rotation-first-version": "The first signer set's rotation file names a version other than 1, or a previous digest.",
+  "rotation-missing": "The signer set or its threshold changed and no rotation file signed by the set before it came with the change.",
+  "rotation-version-skew": "The rotation names a version other than the one after the set it replaces, as a replayed or skipped rotation does.",
+  "rotation-previous-mismatch": "The rotation names a previous digest other than the set it replaces, as a rollback to an older set does.",
+  "rotation-threshold-unsatisfiable": "The new threshold is more than the number of distinct signers in the new set, so no later rotation could meet it.",
+  "rotation-threshold-not-met": "Fewer distinct signers of the set before signed the rotation, in the chant-signers namespace, than that set's threshold.",
+  // Runner evidence (evidence sign and verify, #2553): why evidence is refused.
+  "trust-policy-unreadable": "The trust policy at base can't be read, or its signer history is broken, so no runner key is trusted.",
+  "envelope-unreadable": "The --envelope file can't be read, or is not JSON.",
+  "envelope-invalid": "The file is not a DSSE envelope: payloadType, payload in canonical base64, and signatures with keyid and sig.",
+  "envelope-untrusted": "No signature in the envelope verifies against a runner key the policy at base lists.",
+  "evidence-payload-type": "The envelope's payload type is not application/vnd.in-toto+json.",
+  "evidence-statement-invalid": "The payload is not an in-toto Statement v1 with chant's runner-evidence predicate, or has a field the predicate does not define.",
+  "evidence-runner-mismatch": "The statement names a runner other than the one whose key signed it.",
+  "runner-key-invalid": "The key given to evidence sign is not an Ed25519 private key in PEM.",
+  "runner-key-is-signer": "The key given to evidence sign is a person's key in the signers file. Evidence is signed by a service or CI identity.",
+  "runner-key-unlisted": "The policy at base lists no runner with the key given to evidence sign.",
   // The lineage lock (check).
   "lock-invalid": "The lineage lock can't be read.",
   "manual-step-open": "A scope in the lineage lock has an open manual step.",

package/src/workspace/record-sessions.ts

@@ -12,7 +12,7 @@
  * `citedBy`. This module only reads; nothing here writes a seal into a file.
  */
 
-import { recordTextDigest, type RecordEntry, type RecordFormat, type RecordKind } from "./records";
+import { recordSeal, type RecordEntry, type RecordFormat, type RecordKind } from "./records";
 
 /** A subject record's review entry that names a session in its `session` field. */
 export interface SessionCitation {
@@ -29,19 +29,15 @@ export interface SessionCitation {
 }
 
 /**
- * The seal of a session record: {@link recordTextDigest} with the seal field
- * in place of the reviews list. That is the lowercase hex SHA-256 of the
- * file's text with LF line endings and without the front-matter line that
- * holds the seal, a quoted string on one line. Every other byte, the `---`
- * lines and the body included, is kept.
- *
- * `awk 'NR==1&&/^---$/{f=1;print;next} f&&/^---$/{f=0} f&&/^closed_digest:/{next} {print}' S-0001.md | shasum -a 256`
- * gives the same value for a file with LF line endings that ends in one.
- * For a session kind of format json (ws-053), the seal member is removed by
- * the JSON rule of {@link recordTextDigest} instead.
+ * The seal of a session record: {@link recordSeal} with the seal field, the
+ * whole-file JCS/SHA-256 every closed record of a sealed kind carries
+ * (#2546, ws-063). Until #2546 it was the SHA-256 of the file's text without
+ * the seal line; a session sealed by that rule holds a bare hex value and
+ * reads as `session-seal-mismatch` now. Null when the front matter can't be
+ * parsed.
  */
-export function sessionSeal(text: string, field: string, format: RecordFormat = "markdown-front-matter"): string {
-  return recordTextDigest(text, field, format);
+export function sessionSeal(text: string, field: string, format: RecordFormat = "markdown-front-matter"): string | null {
+  return recordSeal(text, field, format);
 }
 
 /**
@@ -86,7 +82,9 @@ export function joinSessions(kind: RecordKind, entries: RecordEntry[], texts: Ma
         if (actual !== seal) {
           e.reasons.push({
             code: "session-seal-mismatch",
-            message: `${decl.seal} is ${seal}, but the text hashes to ${actual}: the session changed after it closed`,
+            message: /^[0-9a-f]{64}$/.test(seal)
+              ? `${decl.seal} is ${seal}, a seal by the text rule chant used before #2546, and the session seals to ${actual} now: seal it again by hand, since a closed session is never rewritten by chant`
+              : `${decl.seal} is ${seal}, but the session seals to ${actual}: the session changed after it closed`,
           });
         }
       }

package/src/workspace/records-amend.schema.json

@@ -176,6 +176,11 @@
                 "amend-supersede-instead",
                 "record-sign-failed",
                 "ratify-quorum-not-met",
+                "write-scope-member",
+                "write-scope-kind",
+                "write-scope-class-unknown",
+                "agent-unknown",
+                "principal-unidentified",
                 "record-unparseable",
                 "record-schema-invalid",
                 "record-id-duplicate",
@@ -183,6 +188,7 @@
                 "record-supersedes-conflict",
                 "record-remediates-unknown",
                 "record-remediates-not-closed",
+                "record-seal-mismatch",
                 "session-seal-mismatch",
                 "session-verdict-unknown-record"
               ]