@intentius/chant 0.94.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/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.",

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)!,

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}"`),

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

@@ -164,6 +164,7 @@
                 "record-sign-failed",
                 "source-harvest-not-proposed",
                 "record-state-not-initial",
+                "ratify-quorum-not-met",
                 "record-unparseable",
                 "record-schema-invalid",
                 "record-id-duplicate",

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

@@ -14,7 +14,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterEach, beforeEach, describe, expect, test } from "vitest";
 import { workingTreeSource } from "./record-source";
-import { computeQuorum, DEFAULT_QUORUM, loadRecordKind, normalisePrincipal, readRecords, recordTextDigest, type QuorumOptions, type RecordEntry } from "./records";
+import { computeQuorum, DEFAULT_QUORUM, loadRecordKind, normalisePrincipal, readRecords, recordTextDigest as rawDigest, type QuorumOptions, type RecordEntry } from "./records";
 
 const REPO = join(import.meta.dirname, "..", "..", "..", "..");
 const DECISIONS = join(REPO, "docs", "design", "decisions");
@@ -34,6 +34,13 @@ function review(reviewer: string, verdict: string, extra: Record<string, string>
     .join("\n");
 }
 
+/**
+ * A decision's digest: the decision kind names a ratified state, so its
+ * state line leaves the digest with the reviews and seal blocks (#2873).
+ * The rule tests below hold for that list as for the reviews block alone.
+ */
+const recordTextDigest = (text: string, fields: string | readonly string[] | null = ["reviews", "seal", "state"]) => rawDigest(text, fields);
+
 const BARE = recordTextDigest(SAMPLE);
 
 describe("recordTextDigest", () => {
@@ -41,7 +48,7 @@ describe("recordTextDigest", () => {
     expect(BARE).toMatch(/^[0-9a-f]{64}$/);
     const lines = SAMPLE.split("\n");
     const without = lines.filter((l) => l !== "reviews: []").join("\n");
-    expect(recordTextDigest(SAMPLE)).toBe(recordTextDigest(without, null));
+    expect(rawDigest(SAMPLE)).toBe(rawDigest(without, null));
   });
 
   test("does not move when a verdict is added, changed or removed", () => {
@@ -78,7 +85,7 @@ describe("recordTextDigest", () => {
       const file = join(dir, "ws-003.md");
       writeFileSync(file, withReviews(`${review("alice", "agree")}\n${review("bob", "dissent")}`));
       // The recipe in docs/src/content/docs/cli/workspace-records.mdx.
-      const awk = `awk 'NR==1&&$0=="---"{fm=1;print;next} fm&&$0=="---"{fm=0;skip=0;print;next} fm&&/^reviews[ \\t]*:/{skip=1;next} fm&&skip&&/^([ \\t#-]|$)/{next} {skip=0;print}' "${file}" | shasum -a 256`;
+      const awk = `awk 'NR==1&&$0=="---"{fm=1;print;next} fm&&$0=="---"{fm=0;skip=0;print;next} fm&&/^(reviews|seal|state)[ \\t]*:/{skip=1;next} fm&&skip&&/^([ \\t#-]|$)/{next} {skip=0;print}' "${file}" | shasum -a 256`;
       const out = execFileSync("sh", ["-c", awk], { encoding: "utf-8" });
       expect(out.split(" ")[0]).toBe(BARE);
     } finally {

package/src/workspace/records-sessions-write.test.ts

@@ -164,7 +164,8 @@ describe("records review --session (#2693)", () => {
     const root = declared();
     const { path } = await opened(root);
     const decision = join(root, "decisions", "ref-001-how-the-app-is-deployed.md");
-    const digest = recordTextDigest(readFileSync(decision, "utf-8"));
+    // The decision kind names a ratified state, so the state leaves the digest too (#2873).
+    const digest = recordTextDigest(readFileSync(decision, "utf-8"), ["reviews", "seal", "state"]);
 
     const dry = await reviewRecord({ kind: DECISIONS_KIND, id: "ref-001", verdict: "agree", by: "alice", session: "S-0002", dryRun: true, cwd: root });
     review.expectValid(dry);

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

@@ -10,7 +10,8 @@ import { cpSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, realpathSync
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterEach, beforeEach, describe, expect, test } from "vitest";
-import { parseFrontMatter, recordTextDigest } from "./records";
+import { parseFrontMatter, recordTextDigest as textDigest } from "./records";
+import { queryRecords } from "./records-cli";
 import { allocateId, amendRecord, newRecord, renderRecord, reviewRecord, toYaml } from "./records-write";
 
 const REPO = join(import.meta.dirname, "..", "..", "..", "..");
@@ -19,6 +20,9 @@ const KIND = "decisions/decision.kind.mjs";
 
 type Data = Record<string, unknown>;
 
+/** The digest of a decision: the kind names a ratified state, so the state leaves the digest with the reviews and seal (#2873). */
+const recordTextDigest = (text: string) => textDigest(text, ["reviews", "seal", "state"]);
+
 const SAMPLE = (() => {
   const fm = parseFrontMatter(readFileSync(join(DECISIONS, "ws-003-seal-scope.md"), "utf-8"));
   if (!fm.ok) throw new Error(fm.message);
@@ -282,6 +286,7 @@ describe("records amend", () => {
   test("a decided record may be ratified, re-pin its evidence and take reviews, but not move down", async () => {
     const evidence = [{ title: "A spec", url: "https://example.com/spec" }];
     expect(await amendRecord({ kind: KIND, id: "ws-001", fields: fields({ evidence }), cwd: dir })).toMatchObject({ changed: ["evidence"] });
+    for (const by of ["alice", "bob"]) await reviewRecord({ kind: KIND, id: "ws-001", verdict: "agree", by, cwd: dir });
     expect(await amendRecord({ kind: KIND, id: "ws-001", fields: fields({ state: "ratified" }), cwd: dir })).toMatchObject({ changed: ["state"] });
     put("ws-006-six.md", decision({ id: "ws-006", title: "Six" }));
     expect(code(await amendRecord({ kind: KIND, id: "ws-006", fields: fields({ state: "withdrawn" }), cwd: dir }))).toBe("amend-supersede-instead");
@@ -319,6 +324,101 @@ describe("records amend", () => {
   });
 });
 
+describe("ratifying against the quorum (#2873)", () => {
+  const ratify = (id = "ws-001") => amendRecord({ kind: KIND, id, fields: fields({ state: "ratified" }), cwd: dir });
+  const agree = (by: string, id = "ws-001") => reviewRecord({ kind: KIND, id, verdict: "agree", by, cwd: dir });
+  async function quorumOf(id: string) {
+    const doc = await queryRecords({ kind: KIND, cwd: dir });
+    if ("error" in doc) throw new Error(doc.error.message);
+    return doc.records.find((r) => r.id === id)!.quorum!;
+  }
+
+  test("below the quorum, ratified is refused with the count and what did not count, and nothing is written", async () => {
+    expect(SAMPLE.decided_by).toBe("lex00");
+    let before = snapshot();
+    let doc = await ratify();
+    expect(code(doc)).toBe("ratify-quorum-not-met");
+    expect("error" in doc && doc.error.message).toMatch(/^ws-001 can't be ratified yet: its quorum needs 2 agreeing verdicts that count, and it has 0\. Add verdicts with chant workspace records review ws-001/);
+    expect(touched(before, snapshot())).toEqual([]);
+    // One agreement and the decider's own: one counts.
+    await agree("alice");
+    await agree("lex00");
+    before = snapshot();
+    doc = await ratify();
+    expect("error" in doc && doc.error.message).toMatch(/it has 1 \(not counted: lex00, review-decider\)/);
+    expect(touched(before, snapshot())).toEqual([]);
+  });
+
+  test("at the quorum, ratified is taken, and the verdicts still count on the ratified record", async () => {
+    await agree("alice");
+    await agree("bob");
+    const judged = recordTextDigest(text("ws-001-one.md"));
+    expect(await ratify()).toMatchObject({ changed: ["state"] });
+    expect(data("ws-001-one.md").state).toBe("ratified");
+    expect(recordTextDigest(text("ws-001-one.md"))).toBe(judged);
+    expect(await quorumOf("ws-001")).toMatchObject({ need: 2, agreed: 2, met: true, notCounted: [] });
+  });
+
+  test("a met quorum with an open concern ratifies, and the concern stays listed", async () => {
+    await agree("alice");
+    await agree("bob");
+    await reviewRecord({ kind: KIND, id: "ws-001", verdict: "dissent", by: "carol", note: "It leaves out X.", cwd: dir });
+    expect(code(await ratify())).toBe("ok");
+    expect(await quorumOf("ws-001")).toMatchObject({ met: true, metWithObjections: true, openConcerns: [{ reviewer: "carol" }] });
+  });
+
+  test("verdicts on text an amendment changed do not count toward ratifying", async () => {
+    await agree("alice");
+    await agree("bob");
+    await amendRecord({ kind: KIND, id: "ws-001", fields: fields({ evidence: [] }), cwd: dir });
+    const doc = await ratify();
+    expect("error" in doc && doc.error.message).toMatch(/it has 0 \(not counted: alice, review-older-digest; bob, review-older-digest\)/);
+  });
+
+  test("the amendment that ratifies is checked as written, with its own changes to the reviews and pins", async () => {
+    await agree("alice");
+    const digest = recordTextDigest(text("ws-001-one.md"));
+    const reviews = [...(data("ws-001-one.md").reviews as Data[]), { reviewer: "bob", verdict: "agree", on: "2026-09-26", digest }];
+    expect(await amendRecord({ kind: KIND, id: "ws-001", fields: fields({ state: "ratified", reviews }), cwd: dir })).toMatchObject({ changed: ["state", "reviews"] });
+    put("ws-006-six.md", decision({ id: "ws-006", title: "Six" }));
+    await agree("alice", "ws-006");
+    await agree("bob", "ws-006");
+    // Re-pinning in the same write moves the digest, so the verdicts no longer match what would be ratified.
+    const doc = await amendRecord({ kind: KIND, id: "ws-006", fields: fields({ state: "ratified", evidence: [] }), cwd: dir });
+    expect(code(doc)).toBe("ratify-quorum-not-met");
+  });
+
+  test("records new refuses a record that opens ratified below its quorum", async () => {
+    const fresh = decision({ title: "Straight in", state: "ratified" });
+    delete fresh.id;
+    const before = snapshot();
+    expect(code(await newRecord({ kind: KIND, fields: fields(fresh), cwd: dir }))).toBe("ratify-quorum-not-met");
+    expect(touched(before, snapshot())).toEqual([]);
+    expect(code(await newRecord({ kind: KIND, fields: fields({ ...fresh, state: "decided" }), cwd: dir }))).toBe("ok");
+  });
+
+  test("a kind without reviews.ratified, or without reviews, takes ratified with no quorum, and its digest keeps the state", async () => {
+    const kindFile = join(dir, "decisions", "decision.kind.mjs");
+    const withRatified = readFileSync(kindFile, "utf-8");
+    expect(withRatified).toContain('reviews: { field: "reviews", decider: "decided_by", ratified: "ratified" },');
+    writeFileSync(kindFile, withRatified.replace(', ratified: "ratified" }', " }"));
+    const judged = textDigest(text("ws-001-one.md"), ["reviews", "seal"]);
+    expect(await ratify()).toMatchObject({ changed: ["state"] });
+    expect(textDigest(text("ws-001-one.md"), ["reviews", "seal"])).not.toBe(judged);
+    writeFileSync(kindFile, withRatified.replace('  reviews: { field: "reviews", decider: "decided_by", ratified: "ratified" },\n', ""));
+    put("ws-006-six.md", decision({ id: "ws-006", title: "Six" }));
+    expect(await ratify("ws-006")).toMatchObject({ changed: ["state"] });
+  });
+
+  test("a kind whose reviews.ratified is not one of its states is refused", async () => {
+    const kindFile = join(dir, "decisions", "decision.kind.mjs");
+    writeFileSync(kindFile, readFileSync(kindFile, "utf-8").replace('ratified: "ratified" }', 'ratified: "approved" }'));
+    const doc = await ratify();
+    expect(code(doc)).toBe("kind-invalid");
+    expect("error" in doc && doc.error.message).toMatch(/reviews\.ratified must be one of states/);
+  });
+});
+
 describe("records review", () => {
   test("appends a dated verdict bound to the digest of the text it judged", async () => {
     const judged = recordTextDigest(text("ws-001-one.md"));