@intentius/chant 0.93.0 → 0.95.0

package/src/workspace/kinds.ts

@@ -67,6 +67,16 @@ export type KindOutputs =
   /** The names listed here, plus any the member entry lists in `outputs` (`other`, and kinds from a package). */
   | { from: "declared"; names: string[] };
 
+/**
+ * How `chant workspace graph` reads a member of a package's kind (#2874): a
+ * lexicon, by name, and that lexicon's config namespace for a reader project
+ * chant writes itself. See {@link substituteGraphConfig} for the placeholders.
+ */
+export interface KindGraph {
+  lexicon: string;
+  config: Record<string, unknown>;
+}
+
 export interface MemberKind {
   name: string;
   /** One line for listings and error messages. */
@@ -84,6 +94,10 @@ export interface MemberKind {
   outputs: KindOutputs;
   /** Where the kind comes from: `builtin`, or the package that supplies it. */
   source: string;
+  /** The supplying package's directory, absolute; unset for a built-in kind. */
+  packageDir?: string;
+  /** How `workspace graph` reads a member of this kind (#2874); unset, the member is `kind-not-run`. */
+  graph?: KindGraph;
 }
 
 export interface KindRegistry {
@@ -310,7 +324,7 @@ export function parseKindData(text: string, source: string): KindData {
   const problems: string[] = [];
   const kinds: MemberKind[] = [];
   const seen = new Set<string>();
-  for (const k of (raw as { kinds: { name: string; description: string; precedence: number; probe: FileProbe; outputs?: string[] }[] }).kinds) {
+  for (const k of (raw as { kinds: { name: string; description: string; precedence: number; probe: FileProbe; outputs?: string[]; graph?: KindGraph }[] }).kinds) {
     if (BUILTIN_KIND_NAMES.includes(k.name)) {
       problems.push(`${source}: kind ${k.name} is built in and can't be supplied by a package`);
       continue;
@@ -331,6 +345,7 @@ export function parseKindData(text: string, source: string): KindData {
       shape: "member",
       outputs: { from: "declared", names: [...(k.outputs ?? [])] },
       source,
+      ...(k.graph ? { graph: { lexicon: k.graph.lexicon, config: structuredClone(k.graph.config) } } : {}),
     });
   }
   return { kinds, problems };
@@ -389,7 +404,49 @@ export function readPackageKinds(packageDir: string, source?: string): PackageKi
   } catch {
     return { kinds: [], problems: [`${name}: exports["${KINDS_SUBPATH}"] names ${target}, which does not exist`], file };
   }
-  return { ...parseKindData(text, name), file };
+  const data = parseKindData(text, name);
+  const packageName = typeof pkg.name === "string" ? pkg.name : undefined;
+  for (const k of data.kinds) {
+    k.packageDir = packageDir;
+    if (k.graph && packageName !== lexiconPackageName(k.graph.lexicon)) {
+      data.problems.push(
+        `${name}: kind ${k.name} reads its members with lexicon ${k.graph.lexicon}, which is ${lexiconPackageName(k.graph.lexicon)}, ` +
+          `and this package is ${packageName ?? "unnamed"}; the kind is kept, and workspace graph lists its members with kind-not-run`,
+      );
+      delete k.graph;
+    }
+  }
+  return { ...data, file };
+}
+
+/** The package a lexicon name resolves to. */
+export function lexiconPackageName(lexicon: string): string {
+  return `@intentius/chant-lexicon-${lexicon}`;
+}
+
+/** Where each placeholder in a kind's graph config points (#2874). */
+export interface GraphPlaceholders {
+  /** The member's name. */
+  member: string;
+  /** The member's directory, absolute. */
+  dir: string;
+  /** The workspace root, absolute. */
+  workspace: string;
+}
+
+/**
+ * A kind's graph config with `{member}`, `{dir}` and `{workspace}` replaced
+ * in every string key and value. Other braces are left as they are.
+ */
+export function substituteGraphConfig(config: Record<string, unknown>, at: GraphPlaceholders): Record<string, unknown> {
+  const text = (v: string) => v.replace(/\{(member|dir|workspace)\}/g, (_, key: keyof GraphPlaceholders) => at[key]);
+  const walk = (v: unknown): unknown => {
+    if (typeof v === "string") return text(v);
+    if (Array.isArray(v)) return v.map(walk);
+    if (v !== null && typeof v === "object") return Object.fromEntries(Object.entries(v).map(([k, x]) => [text(k), walk(x)]));
+    return v;
+  };
+  return walk(config) as Record<string, unknown>;
 }
 
 /**

package/src/workspace/member-commands.test.ts

@@ -156,6 +156,21 @@ describe("member command lines", () => {
     expect(memberArgv("audit", unit, args({ failOn: "error" }))).toEqual(["audit", ".", "--format", "json", "--fail-on", "error"]);
     expect(memberArgv("graph", unit, args({ format: "mermaid" }))).toEqual(["graph", ".", "--format", "ir"]);
   });
+
+  test("graph hands each member the live read's flags as they are (#2875)", () => {
+    expect(memberArgv("graph", unit, args({ env: "prod", live: true, overlay: true, traffic: "100 rps, p50" }))).toEqual([
+      "graph", ".", "--format", "ir", "--env", "prod", "--live", "--overlay", "--traffic", "100 rps, p50",
+    ]);
+    expect(memberArgv("graph", unit, args({ env: "prod" }))).toEqual(["graph", ".", "--format", "ir", "--env", "prod"]);
+  });
+
+  test("a reader unit takes --env only with --live, which needs one (#2874, #2875)", () => {
+    const reader = { ...unit, reader: { lexicon: "terraform", config: {}, packageDir: "/p" } } as typeof unit;
+    expect(memberArgv("graph", reader, args({ env: "prod" }))).toEqual(["graph", ".", "--format", "ir"]);
+    expect(memberArgv("graph", reader, args({ env: "prod", live: true, overlay: true }))).toEqual([
+      "graph", ".", "--format", "ir", "--env", "prod", "--live", "--overlay",
+    ]);
+  });
 });
 
 describe("the member-run protocol", () => {

package/src/workspace/member-commands.ts

@@ -9,6 +9,10 @@
  *   Members of kind `other` are never read, and a nested `workspace` member
  *   runs its own workspace commands, so both are listed as skipped with the
  *   reason code `kind-not-run`.
+ * - For `graph` only, members of a pinned package's kind whose kinds file
+ *   says how to read them (#2874, a `graph` block): each runs `chant graph`
+ *   in a reader project chant writes for it (`kind-readers.ts`). Other
+ *   package kinds are `kind-not-run`, as before.
  * - For `build` and `lint` only, every project an example group matches
  *   (ws-051): groups are built and linted, and have no ledger, audit or place
  *   in the graph. On a large repository this is most of the run, so
@@ -38,7 +42,7 @@ import { findWorkspaceRoot } from "../project-root";
 import type { ComposedMember, MemberReason } from "./compose-graph";
 import { mergeAudit, mergeSarif, type MemberOutput } from "./compose-reports";
 import { readDeclaration, resolveGroups, rootExclusions, WorkspaceReadError, type Declaration } from "./declaration";
-import { builtinKindRegistry, type KindRegistry } from "./kinds";
+import { builtinKindRegistry, type KindGraph, type KindRegistry } from "./kinds";
 import { memberReason } from "./ls";
 import { MEMBER_RUN_PROTOCOL, PROTOCOL_PREFIX, type MemberRunLine, type MemberRunRequest } from "./member-run";
 import { workingTree, type WorkspaceTree } from "./tree";
@@ -58,6 +62,12 @@ export interface RunUnit {
   abs: string;
   /** Directories (relative to `dir`) left out of discovery; set for member `.`. */
   exclude: string[];
+  /**
+   * Set for a member read through its kind's `graph` block (#2874). `abs` is
+   * the member's directory until `kind-readers.ts` writes the reader project
+   * and points `abs` at it.
+   */
+  reader?: KindGraph & { packageDir: string };
 }
 
 export interface SkippedEntry {
@@ -189,6 +199,25 @@ export function planMembers(verb: WorkspaceVerb, root: string, options: PlanOpti
       }
       continue;
     }
+    const byKind = verb === "graph" && entry.kind !== "chant" ? kinds.get(entry.kind) : undefined;
+    if (byKind?.graph && byKind.packageDir) {
+      const reason = memberReason(entry, tree, kinds);
+      if (reason) {
+        unreadable.push({ name: entry.name, dir: entry.dir, kind: entry.kind, reason });
+        continue;
+      }
+      units.push({
+        id: entry.name,
+        member: entry.name,
+        kind: entry.kind,
+        group: false,
+        dir: entry.dir,
+        abs: entry.dir === "." ? root : join(root, entry.dir),
+        exclude: [],
+        reader: { ...byKind.graph, packageDir: byKind.packageDir },
+      });
+      continue;
+    }
     if (entry.kind !== "chant") {
       const why =
         entry.kind === "workspace"
@@ -265,8 +294,15 @@ export function memberArgv(verb: WorkspaceVerb, unit: RunUnit, args: ParsedArgs)
     if (args.tier) argv.push("--tier", args.tier);
     if (args.failOn) argv.push("--fail-on", args.failOn);
     if (args.maxFiles !== undefined) argv.push("--max-files", String(args.maxFiles));
-  } else if (args.env) {
-    argv.push("--env", args.env);
+  } else {
+    // graph. A reader project declares no environments, so a source read
+    // leaves --env to the chant members. A live read needs one, and a reader
+    // project with none declared takes any name, so --live carries it (#2875).
+    if (args.env && (!unit.reader || args.live)) argv.push("--env", args.env);
+    // The live read's flags go to every member as they are (#2875).
+    if (args.live) argv.push("--live");
+    if (args.overlay) argv.push("--overlay");
+    if (args.traffic) argv.push("--traffic", args.traffic);
   }
   return argv;
 }
@@ -286,6 +322,8 @@ export interface UnitResult extends MemberOutput {
   chant: string | null;
   /** How the member ran: inside its toolchain's shared process, or in a level-0 process of its own. */
   mode: "member-run" | "per-member";
+  /** When the member's command finished, as an ISO time (#2875). */
+  finishedAt?: string;
 }
 
 interface Spawned {
@@ -349,13 +387,15 @@ async function runGroup(verb: WorkspaceVerb, group: ToolchainGroup, root: string
     units: units.map((u) => ({ id: u.id, dir: u.abs, argv: argvs.get(u.id)!, ...(u.exclude.length ? { exclude: u.exclude } : {}) })),
   };
   const answer = await run(toolchain.command, ["workspace", "member-run"], root, JSON.stringify(request));
+  const ended = new Date().toISOString();
   const parsed = parseMemberRunOutput(answer.stdout);
   if (parsed) {
     if (parsed.stray) process.stderr.write(`${parsed.stray}\n`);
     return units.map((unit) => {
       const r = parsed.results.get(unit.id);
       const base = { unit, toolchain, chant: parsed.chant, mode: "member-run" as const, id: unit.id, member: unit.member, dir: unit.dir, exclude: unit.exclude };
-      if (r) return { ...base, exitCode: r.exitCode, stdout: r.stdout, stderr: r.stderr };
+      // A member-run from before #2875 names no time; the group's end is the closest one.
+      if (r) return { ...base, exitCode: r.exitCode, stdout: r.stdout, stderr: r.stderr, finishedAt: r.finishedAt ?? ended };
       return { ...base, exitCode: answer.exitCode || 1, stdout: "", stderr: `the member-run process for ${toolchain.identity} ended before running this member\n${answer.stderr}` };
     });
   }
@@ -363,7 +403,7 @@ async function runGroup(verb: WorkspaceVerb, group: ToolchainGroup, root: string
   const out: UnitResult[] = [];
   for (const unit of units) {
     const r = await run(toolchain.command, argvs.get(unit.id)!, unit.abs);
-    out.push({ unit, toolchain, chant: null, mode: "per-member", id: unit.id, member: unit.member, dir: unit.dir, exclude: unit.exclude, ...r });
+    out.push({ unit, toolchain, chant: null, mode: "per-member", id: unit.id, member: unit.member, dir: unit.dir, exclude: unit.exclude, ...r, finishedAt: new Date().toISOString() });
   }
   return out;
 }
@@ -385,7 +425,7 @@ const USAGE: Record<WorkspaceVerb, string> = {
   build: "chant workspace build [dir] [--member <name>] [-o <dir>] [--format json|yaml] [--env <env>] [--param k=v] [--dry-run]",
   lint: "chant workspace lint [dir] [--member <name>] [--format stylish|json|sarif] [-o <file>] [--fix] [--dry-run]",
   audit: "chant workspace audit [dir] [--member <name>] [--format stylish|json] [-o <file>] [--tier <tier>] [--fail-on <level>] [--dry-run]",
-  graph: "chant workspace graph [dir] [--member <name>] [--kind <kind file>] [-o <file>] [--env <env>] [--dry-run]",
+  graph: "chant workspace graph [dir] [--member <name>] [--kind <kind file>] [-o <file>] [--env <env>] [--live [--overlay] [--traffic <level>]] [--no-cache] [--dry-run]",
 };
 
 export function describePlan(plan: MemberPlan): string {
@@ -461,7 +501,7 @@ function formatAuditText(doc: ReturnType<typeof mergeAudit>, plan: MemberPlan):
 }
 
 export function memberStatus(name: string, dir: string, kind: string, status: ComposedMember["status"], reason: MemberReason | null, chant: string | null): ComposedMember {
-  return { name, dir, kind, status, reason, chant, irVersion: null };
+  return { name, dir, kind, status, reason, chant, irVersion: null, live: false };
 }
 
 export async function runWorkspaceMembers(ctx: CommandContext, verb: WorkspaceVerb): Promise<number> {

package/src/workspace/member-run.ts

@@ -49,7 +49,15 @@ export interface MemberRunUnit {
 
 export type MemberRunLine =
   | { type: "header"; protocol: number; chant: string }
-  | { type: "result"; id: string; exitCode: number; stdout: string; stderr: string };
+  | {
+      type: "result";
+      id: string;
+      exitCode: number;
+      stdout: string;
+      stderr: string;
+      /** When the member's command finished, as an ISO time (#2875). A member-run from before it leaves this out. */
+      finishedAt?: string;
+    };
 
 /** A `process.exit` inside a command, turned into a value. */
 class ExitRequest extends Error {
@@ -125,7 +133,7 @@ export async function runMemberUnits(request: MemberRunRequest, run: (argv: stri
     if (startEnv === undefined) delete process.env[ENV_VAR];
     else process.env[ENV_VAR] = startEnv;
     process.chdir(startDir);
-    emit({ type: "result", id: unit.id, ...result });
+    emit({ type: "result", id: unit.id, ...result, finishedAt: new Date().toISOString() });
   }
   return 0;
 }

package/src/workspace/points-cli.ts

@@ -71,6 +71,8 @@ export interface PointView {
   questionType: string;
   instructions: string;
   candidates: (string | boolean)[];
+  /** What each candidate means, as the points file declares it: an object of strings for noul and choice, an array for score. */
+  criteria: Record<string, string> | string[];
   /** Each input: its name, the read-contract output it names, and its description. */
   inputs: { name: string; output: string; description: string }[];
   deciders: Decider[];
@@ -163,6 +165,7 @@ export async function workspacePoints(query: PointsQuery): Promise<PointsDocumen
           questionType: p.question.type,
           instructions: p.question.instructions,
           candidates: candidates(p.question),
+          criteria: p.question.criteria,
           inputs: Object.entries(p.inputs).map(([n, description]) => ({ name: n, output: inputOutput(n), description })),
           deciders: p.deciders,
           quorum: quorumOf(p),

package/src/workspace/points.schema.json

@@ -191,6 +191,7 @@
         "questionType",
         "instructions",
         "candidates",
+        "criteria",
         "inputs",
         "deciders",
         "quorum"
@@ -236,6 +237,23 @@
             ]
           }
         },
+        "criteria": {
+          "description": "What each candidate means, as the points file declares it: noul and choice give an object of strings keyed by candidate, score an array of ordered level descriptions.",
+          "oneOf": [
+            {
+              "type": "object",
+              "additionalProperties": {
+                "type": "string"
+              }
+            },
+            {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
+          ]
+        },
         "inputs": {
           "type": "array",
           "items": {

package/src/workspace/points.test.ts

@@ -24,10 +24,11 @@ import {
 } from "./points";
 
 /**
- * chud's points, as template/delivery/decisions/points.yaml declares them at
- * jhgaylor/chud@43afcf1, as JSON.
+ * Points shaped like an externally authored template's decisions file
+ * (ported from chud, jhgaylor/chud@43afcf1's
+ * template/delivery/decisions/points.yaml), as JSON.
  */
-const CHUD = {
+const IMPORTED = {
   points: {
     "slice-tier": {
       title: "Which builder tier builds this contract",
@@ -63,7 +64,7 @@ const CHUD = {
     "ship-skip": {
       title: "May this release skip the human gate",
       question: {
-        type: "boolean",
+        type: "noul",
         instructions: "May this release pass the ship gate without a person approving it? The state is what the release plan would change.",
         criteria: {
           true: "An agent may pass the gate for this release (only in enforce mode).",
@@ -86,9 +87,9 @@ const CHUD = {
   },
 };
 
-/** chud's points with each input named as a read-contract output: the slice tier reads a work item, the ship gate a release. */
-function renamed(): typeof CHUD {
-  const copy = JSON.parse(JSON.stringify(CHUD)) as typeof CHUD;
+/** The imported points with each input named as a read-contract output: the slice tier reads a work item, the ship gate a release. */
+function renamed(): typeof IMPORTED {
+  const copy = JSON.parse(JSON.stringify(IMPORTED)) as typeof IMPORTED;
   const prefix: Record<string, string> = { "slice-tier": "work-item", "ship-skip": "release" };
   for (const [name, point] of Object.entries(copy.points) as [string, { inputs: Record<string, string>; deciders: { rows?: { when: Record<string, unknown> }[] }[] }][]) {
     const to = (k: string) => `${prefix[name]}.${k}`;
@@ -123,14 +124,14 @@ describe("the decision points schema (#2738)", () => {
     }
   });
 
-  test("chud's slice-tier and ship-skip validate unchanged, apart from the input names", () => {
-    // As chud declares them, only the input names are refused: each names no read-contract output.
-    const found = problems(CHUD);
+  test("the imported slice-tier and ship-skip validate unchanged, apart from the input names", () => {
+    // As the template declares them, only the input names are refused: each names no read-contract output.
+    const found = problems(IMPORTED);
     expect(found.length).toBeGreaterThan(0);
     for (const p of found) expect(p.message).toMatch(/is not a read-contract output|is not one of this point's inputs/);
     expect(found.filter((p) => p.message.includes("read-contract output")).map((p) => p.field)).toEqual([
-      ...Object.keys(CHUD.points["slice-tier"].inputs).map((k) => `points.slice-tier.inputs.${k}`),
-      ...Object.keys(CHUD.points["ship-skip"].inputs).map((k) => `points.ship-skip.inputs.${k}`),
+      ...Object.keys(IMPORTED.points["slice-tier"].inputs).map((k) => `points.slice-tier.inputs.${k}`),
+      ...Object.keys(IMPORTED.points["ship-skip"].inputs).map((k) => `points.ship-skip.inputs.${k}`),
     ]);
     // With the inputs renamed, nothing else changes and both validate.
     const points = parsePoints(text(renamed()), "points.json");
@@ -156,7 +157,7 @@ describe("the decision points schema (#2738)", () => {
 
   test("a point with an unknown input is refused, and so is a row testing an undeclared one", () => {
     const v = renamed() as unknown as { points: Record<string, { inputs: Record<string, string>; deciders: { rows?: { when: Record<string, unknown> }[] }[] }> };
-    v.points["slice-tier"].inputs["contract.size"] = "chud's contract, which the read contract has no output for";
+    v.points["slice-tier"].inputs["contract.size"] = "a contract, which the read contract has no output for";
     expect(problems(v)).toEqual([
       {
         field: "points.slice-tier.inputs.contract.size",
@@ -168,7 +169,7 @@ describe("the decision points schema (#2738)", () => {
     expect(problems(w)).toEqual([{ field: "points.slice-tier.deciders.0.rows.0.when.work-item.tier", message: expect.stringContaining("is not one of this point's inputs") }]);
   });
 
-  test("the schema and the code refuse the rest of what chud refused, and an alias model id", () => {
+  test("the schema and the code refuse the rest of what an imported points file can get wrong, and an alias model id", () => {
     const cases: [(p: Record<string, unknown>) => void, RegExp][] = [
       [(p) => ((p.deciders as Record<string, unknown>[])[1].model = "jev-latest"), /is an alias/],
       [(p) => ((p.deciders as Record<string, unknown>[])[1].count = 2), /is only for a quorum decider/],

package/src/workspace/points.ts

@@ -20,7 +20,7 @@
  * runtime's decider or a test's stub supplies. Without one, a model decider is
  * not asked and the chain moves on.
  *
- * Taken from chud's `packages/runtime/src/decide.mjs` at 43afcf1: the chain,
+ * Ported from chud's `packages/runtime/src/decide.mjs` at 43afcf1: the chain,
  * the observation rule, the point version and the inputs hash. The records
  * are chant records: `decide.ts` writes them, and {@link applyAnswers} warns
  * about them on read.
@@ -71,7 +71,6 @@ export function inputOutput(name: string): string {
 export type QuestionType = "noul" | "choice" | "score";
 
 export interface Question {
-  /** `boolean` in a points file is read as `noul`. */
   type: QuestionType;
   instructions: string;
   criteria: Record<string, string> | string[];
@@ -220,20 +219,9 @@ export function schemaProblems(data: unknown): PointProblem[] {
   return out;
 }
 
-/** `boolean` read as `noul`. The declaration is otherwise kept as written. */
-function normalise(points: Record<string, Point>): Record<string, Point> {
-  const out: Record<string, Point> = {};
-  for (const [name, p] of Object.entries(points)) {
-    const type = (p.question.type as string) === "boolean" ? "noul" : p.question.type;
-    out[name] = { ...p, question: { ...p.question, type } };
-  }
-  return out;
-}
-
 /**
- * Parse and validate a points file's text. Returns its points, with
- * `boolean` read as `noul`. Throws a {@link PointsError} naming the file and
- * each field.
+ * Parse and validate a points file's text. Returns its points. Throws a
+ * {@link PointsError} naming the file and each field.
  */
 export function parsePoints(text: string, file: string): Record<string, Point> {
   let data: unknown;
@@ -244,7 +232,7 @@ export function parsePoints(text: string, file: string): Record<string, Point> {
   }
   const problems = schemaProblems(data);
   if (problems.length > 0) throw new PointsError(file, problems);
-  const points = normalise((data as { points: Record<string, Point> }).points);
+  const points = (data as { points: Record<string, Point> }).points;
   const more = pointProblems(points);
   if (more.length > 0) throw new PointsError(file, more);
   return points;

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

@@ -193,6 +193,14 @@ describe("every schema against the reference workspace (#2543)", () => {
       expectValid(doc);
       if ("error" in doc) throw new Error(doc.error.message);
       expect(doc.points.map((p) => p.name)).toEqual(["slice-tier", "ship-skip", "finding-triage", "needs-a-decision"]);
+      const sliceTier = doc.points.find((p) => p.name === "slice-tier")!;
+      expect(sliceTier.criteria).toEqual({
+        small: "A haiku-class builder. The work item fits the small limits.",
+        medium: "A mid-size builder. The work item fits the medium limits.",
+        large: "The largest builder. The work item is bigger than the medium limits.",
+      });
+      const shipSkip = doc.points.find((p) => p.name === "ship-skip")!;
+      expect(shipSkip.criteria).toEqual({ true: "An agent may pass the gate for this release.", false: "A person approves the release at the gate." });
     }
     const open = await workspacePoints({ cwd: FIXTURE, open: true });
     expectValid(open);

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

@@ -157,11 +157,11 @@ describe("the closed list of reason codes", () => {
   });
 
   test("a plugin's finding codes are in its own namespace, outside the list, and the intent schema accepts them (#2656)", () => {
-    expect(isPluginCode("plugin:chud:contract-criteria-changed")).toBe(true);
-    expect(isPluginCode("plugin:chud:contract-criteria-changed", "chud")).toBe(true);
-    expect(isPluginCode("plugin:chud:contract-criteria-changed", "units")).toBe(false);
-    for (const bad of ["plugin:chud", "plugin::x", "plugin:chud:Upper", "plugin:chud:a:b", "intent-commit-bare", 7]) expect(isPluginCode(bad), String(bad)).toBe(false);
-    expect(isReasonCode("plugin:chud:contract-criteria-changed")).toBe(false);
+    expect(isPluginCode("plugin:acme:contract-criteria-changed")).toBe(true);
+    expect(isPluginCode("plugin:acme:contract-criteria-changed", "acme")).toBe(true);
+    expect(isPluginCode("plugin:acme:contract-criteria-changed", "units")).toBe(false);
+    for (const bad of ["plugin:acme", "plugin::x", "plugin:acme:Upper", "plugin:acme:a:b", "intent-commit-bare", 7]) expect(isPluginCode(bad), String(bad)).toBe(false);
+    expect(isReasonCode("plugin:acme:contract-criteria-changed")).toBe(false);
     const { validate } = contract(intentSchema);
     const finding = (code: string) => ({ id: `finding:${code}:1`, kind: "finding", code, message: "m", concerns: [] });
     const doc = (code: string) => ({
@@ -178,9 +178,9 @@ describe("the closed list of reason codes", () => {
       reasons: [],
       summary: { commits: 0, decisions: 0, artifacts: 0, findings: 1 },
     });
-    expect(validate(doc("plugin:chud:contract-criteria-changed"))).toBe(true);
+    expect(validate(doc("plugin:acme:contract-criteria-changed"))).toBe(true);
     expect(validate(doc("intent-commit-bare"))).toBe(true);
-    expect(validate(doc("plugin:chud:Nope"))).toBe(false);
+    expect(validate(doc("plugin:acme:Nope"))).toBe(false);
     expect(validate(doc("made-up-code"))).toBe(false);
   });
 

package/src/workspace/reason-codes.ts

@@ -38,6 +38,7 @@ export const REASONS = {
   // --at and git.
   "not-a-git-repository": "--at, or a ledger read, needs a git repository and there is none.",
   "revision-unknown": "--at names no commit.",
+  "live-at-revision": "graph was given --live and --at: a live read is of the account now, not of a revision.",
   // status.
   "environment-invalid": "An environment name that can't name a ledger directory.",
   // A member or group that can't be read (ls, graph).
@@ -47,7 +48,7 @@ export const REASONS = {
   "no-matches": "An example group matches no directory holding a chant project.",
   // A member graph leaves out (graph, and the other per-member commands).
   "kind-not-run": "The member's kind is one the per-member commands don't run, such as other.",
-  "command-failed": "The member's own command exited with a failure.",
+  "command-failed": "The member's own command exited with a failure, or the lexicon that reads the member through its kind's graph block isn't installed where the workspace resolves its pin.",
   "output-unreadable": "The member's command printed something that isn't the document asked for.",
   "ir-version-unsupported": "The member's IR has a version this chant can't read.",
   // A ledger status can't fully read.
@@ -129,6 +130,7 @@ export const REASONS = {
   "review-sign-failed": "--sign was given and no seal could be made: the key can't be read or used, git names no ssh signing key, or ssh-keygen is not installed.",
   "record-state-not-initial": "A record written through chant serve mcp gives a state other than the kind's first: a new record opens proposed, and a person moves it on.",
   "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.",
   // 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.",
@@ -192,6 +194,9 @@ export const REASONS = {
   "box-capability-unbrokered": "A capability in a member's box block names no broker, so the box would hold its credential.",
   // The credential fountain itself hands a persistent box (check, #2780). Also a WSP finding.
   "box-fountain-callback-undeclared": "A box member builds a fountain Box, whose persistent sandbox fountain gives a callback token scoped to its owner, and the member's box block does not declare the fountain-callback capability brokered by fountain with scope owner.",
+  // 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.",
   // 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.",

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

@@ -175,6 +175,7 @@
                 "record-closed",
                 "amend-supersede-instead",
                 "record-sign-failed",
+                "ratify-quorum-not-met",
                 "record-unparseable",
                 "record-schema-invalid",
                 "record-id-duplicate",

package/src/workspace/records-cli.ts

@@ -38,6 +38,7 @@ import {
   RecordReadError,
   type LoadedRecordKind,
   type Quorum,
+  type QuorumOptions,
   type ReadErrorCode,
   type ReadRecordsResult,
   type RecordEntry,
@@ -210,6 +211,24 @@ function declaredQuorum(tree: WorkspaceTree): { need: number; needFrom: "declara
   return { need: DEFAULT_QUORUM, needFrom: "default" };
 }
 
+/**
+ * The options a kind's quorum is computed with, or undefined when the kind
+ * has no reviews list: the need from the declaration in the tree read, and
+ * the agents, whether verdicts need a seal, and the keys a seal verifies
+ * against, all from the policy at base (#2671, #2687). `records` and the
+ * ratified check of `records new` and `amend` (#2873) both use it.
+ */
+export async function quorumOptionsFor(loaded: LoadedRecordKind, tree: WorkspaceTree, policy: TrustPolicy): Promise<QuorumOptions | undefined> {
+  if (!loaded.kind.reviews) return undefined;
+  const { checkVerdictSeal } = await import("./trust/seal");
+  return {
+    ...declaredQuorum(tree),
+    agents: new Set((policy.roles[AGENT_ROLE] ?? []).map(normalisePrincipal)),
+    attestation: policy.active,
+    verifySeal: (v: SealInput) => checkVerdictSeal(policy, v),
+  };
+}
+
 /**
  * Where a kind's pinned paths resolve: the workspace whose declaration sits
  * nearest above the kind file, when it is inside the repository, or else the
@@ -300,19 +319,8 @@ export async function queryRecords(query: RecordsQuery): Promise<RecordsDocument
       paths: result.records.map((r) => r.path),
       attestors: policy.active ? await activeAttestors() : [],
     });
-    // The quorum: the need from the declaration in the tree read, agents,
-    // whether verdicts need a seal, and the keys a seal verifies against,
-    // all from the policy at base (#2671, #2687).
     const seals = loaded.kind.reviews ? await import("./trust/seal") : undefined;
-    const checkVerdictSeal = seals?.checkVerdictSeal;
-    const quorumOptions = checkVerdictSeal
-      ? {
-          ...declaredQuorum(tree),
-          agents: new Set((policy.roles[AGENT_ROLE] ?? []).map(normalisePrincipal)),
-          attestation: policy.active,
-          verifySeal: (v: SealInput) => checkVerdictSeal(policy, v),
-        }
-      : undefined;
+    const quorumOptions = await quorumOptionsFor(loaded, tree, policy);
     const records: RecordView[] = result.records.map((r) => ({
       ...r,
       provenance: provenance.get(r.path)!,
@@ -510,6 +518,14 @@ export async function runWorkspaceRecords(ctx: CommandContext): Promise<number>
  * names, or, when it names none or there is no declaration, the error it has
  * always been. A kind whose read fails is listed with its error, the others
  * are still read, and the exit code is 1.
+ *
+ * Locating the declaration itself can fail before any kind is known. For
+ * `not-a-git-repository` and `revision-unknown`, the codes a single kind's
+ * read can also fail with (#2860), `--json` prints the same
+ * `{ $schema, contract, error: { code, message } }` document that read
+ * failure would, so a reader of `--json` never sees a silent exit 1. A
+ * declaration-level code the schema doesn't carry (`declaration-invalid` and
+ * the rest of `WorkspaceErrorCode`) still prints text on stderr only.
  */
 async function runDeclaredRecords(args: CommandContext["args"]): Promise<number> {
   if (args.require !== undefined && args.require !== "attested") {
@@ -521,7 +537,12 @@ async function runDeclaredRecords(args: CommandContext["args"]): Promise<number>
     declared = declaredKindFiles(process.cwd(), args.at);
   } catch (err) {
     if (!(err instanceof WorkspaceReadError)) throw err;
-    console.error(formatError({ message: `${err.code}: ${err.describe()}; without --kind, the declaration names the record kinds`, hint: USAGE }));
+    const message = `${err.describe()}; without --kind, the declaration names the record kinds`;
+    if (args.json && (err.code === "not-a-git-repository" || err.code === "revision-unknown")) {
+      console.log(JSON.stringify({ $schema: RECORDS_OUTPUT_SCHEMA_ID, contract: RECORDS_CONTRACT_VERSION, error: { code: err.code, message } }, null, 2));
+    } else {
+      console.error(formatError({ message: `${err.code}: ${message}`, hint: USAGE }));
+    }
     return 1;
   }
   if (declared.length === 0) {

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

@@ -116,7 +116,8 @@ describe("records output schema", () => {
       JSON.stringify({ name: "w", schema: 1, quorum: 1, members: [{ name: "docs", dir: "docs", kind: "other", because: "decisions only" }] }),
     );
     const base = readFileSync(join(dir, "ws-003-seal-scope.md"), "utf-8").replace(/^id: .*$/m, 'id: "ws-900"');
-    const digest = recordTextDigest(base);
+    // The decision kind names a ratified state, so the state leaves the digest too (#2873).
+    const digest = recordTextDigest(base, ["reviews", "seal", "state"]);
     const entry = (reviewer: string, verdict: string, extra = "") => `  - reviewer: "${reviewer}"\n    verdict: "${verdict}"\n    on: "2026-09-24"${extra}`;
     const reviews = [
       entry("alice", "agree", `\n    digest: "${digest}"`),