@intentius/chant 0.100.0 → 0.101.0

package/src/workspace/nesting.ts

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

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

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

package/src/workspace/pin-cli.ts

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

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

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

package/src/workspace/pin-integrity.ts

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

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

@@ -483,6 +483,7 @@
                 "record-supersedes-conflict",
                 "record-remediates-unknown",
                 "record-remediates-not-closed",
+                "record-seal-mismatch",
                 "session-seal-mismatch",
                 "session-verdict-unknown-record"
               ]

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

@@ -35,6 +35,11 @@ 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 { WRITE_SCOPE_CODES } from "./write-scope";
+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;
 
@@ -84,6 +89,11 @@ const PER_COMMAND: Record<string, readonly string[]> = {
   POINTS_SOURCE_REASON_CODES,
   POINTS_WRITE_ERROR_CODES,
   PATCH_ERROR_CODES,
+  AGENT_ERROR_CODES,
+  WRITE_SCOPE_CODES,
+  ROTATION_REFUSAL_CODES,
+  SIGNERS_ERROR_CODES,
+  EVIDENCE_ERROR_CODES,
 };
 
 /** Every string in an `enum` under a property named `code`, anywhere in a schema. */

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.",
@@ -105,7 +106,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 +133,10 @@ 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.",
+  "agent-unknown": "CHANT_AGENT, or a commit's Chant-Agent trailer, names an agent session the declaration at base does not declare.",
   // 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.",
@@ -216,6 +221,28 @@ export const REASONS = {
   // 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,9 @@
                 "amend-supersede-instead",
                 "record-sign-failed",
                 "ratify-quorum-not-met",
+                "write-scope-member",
+                "write-scope-kind",
+                "agent-unknown",
                 "record-unparseable",
                 "record-schema-invalid",
                 "record-id-duplicate",
@@ -183,6 +186,7 @@
                 "record-supersedes-conflict",
                 "record-remediates-unknown",
                 "record-remediates-not-closed",
+                "record-seal-mismatch",
                 "session-seal-mismatch",
                 "session-verdict-unknown-record"
               ]