@intentius/chant 0.85.0 → 0.87.0

package/src/workspace/ls.ts

@@ -8,6 +8,11 @@
  *
  * The `--json` output is part of the read contract, versioned like
  * `workspace records` and described by `ls.schema.json` beside this file.
+ *
+ * The record kinds the declaration names are listed too, the workspace's own
+ * and each member's, with each kind file's own name when it loads (#2680).
+ * Loading one imports it, so {@link listWorkspace} lists them unloaded and
+ * {@link listWorkspaceWithKinds}, which the command runs, loads them.
  */
 
 import { existsSync } from "node:fs";
@@ -28,6 +33,7 @@ import type { ReasonCode } from "./reason-codes";
 import { loadKindRegistry, probeKind, type KindRegistry } from "./kinds";
 import type { WorkspaceTree } from "./tree";
 import { handToRootChant, locateWorkspace } from "./which-chant";
+import type { DeclaredKindReasonCode } from "./declared-kinds";
 
 /** The version of the `ls` output this chant writes. */
 export const LS_CONTRACT_VERSION = 1;
@@ -58,6 +64,18 @@ export const GROUP_REASON_CODES = [
 ] as const satisfies readonly ReasonCode[];
 export type GroupReasonCode = (typeof GROUP_REASON_CODES)[number];
 
+/** A record kind the declaration names (#2680). */
+export interface LsRecordKind {
+  /** The name the declaration gives it, else the kind file's own, else null when the file wasn't loaded. */
+  name: string | null;
+  /** The kind file from the workspace root. */
+  path: string;
+  /** The kind file's `recordKind.name`, or null when it wasn't loaded. */
+  kind: string | null;
+  /** Why the kind file can't be loaded, or null. */
+  reason: { code: DeclaredKindReasonCode; message: string } | null;
+}
+
 export interface LsMember {
   name: string;
   dir: string;
@@ -67,6 +85,8 @@ export interface LsMember {
   because: string | null;
   readable: boolean;
   reason: { code: MemberReasonCode; message: string } | null;
+  /** The record kinds the member declares, in file order (#2680). */
+  records: LsRecordKind[];
 }
 
 export interface LsGroup {
@@ -92,6 +112,8 @@ export type LsDocument =
         schema: number;
         minReader: string | null;
         pins: Declaration["pins"];
+        /** The workspace's own record kinds, from the top-level `records` (#2680). */
+        records: LsRecordKind[];
       };
       members: LsMember[];
       groups: LsGroup[];
@@ -126,8 +148,36 @@ export function memberReason(member: Member, tree: WorkspaceTree, kinds: KindReg
   return null;
 }
 
-/** Find the workspace, read it and build the document `--json` prints. Never throws a {@link WorkspaceReadError}. */
+/**
+ * Find the workspace, read it and build the document `--json` prints, with
+ * the declared record kinds unloaded: `kind` null and no reason. Never throws
+ * a {@link WorkspaceReadError}.
+ */
 export function listWorkspace(query: LsQuery): LsDocument {
+  return readListing(query).doc;
+}
+
+/** {@link listWorkspace}, with each declared record kind loaded for its name, or the reason it can't be (#2680). */
+export async function listWorkspaceWithKinds(query: LsQuery): Promise<LsDocument> {
+  const { doc, declaration, tree, rootOnDisk } = readListing(query);
+  if (!declaration || "error" in doc) return doc;
+  const { loadDeclaredKinds } = await import("./declared-kinds");
+  const loaded = await loadDeclaredKinds(declaration, tree!, rootOnDisk!);
+  const byPath = new Map(loaded.map((k) => [k.declared.path, k]));
+  const fill = (r: LsRecordKind): LsRecordKind => {
+    const k = byPath.get(r.path)!;
+    return { ...r, name: r.name ?? k.kind, kind: k.kind, reason: k.reason };
+  };
+  return {
+    ...doc,
+    workspace: { ...doc.workspace, records: doc.workspace.records.map(fill) },
+    members: doc.members.map((m) => ({ ...m, records: m.records.map(fill) })),
+  };
+}
+
+const unloaded = (records: Declaration["records"]): LsRecordKind[] => records.map((r) => ({ name: r.name, path: r.path, kind: null, reason: null }));
+
+function readListing(query: LsQuery): { doc: LsDocument; declaration?: Declaration; tree?: WorkspaceTree; rootOnDisk?: string } {
   const chant = readerVersion();
   const head = { $schema: LS_OUTPUT_SCHEMA_ID, contract: LS_CONTRACT_VERSION, chant };
   try {
@@ -149,6 +199,7 @@ export function listWorkspace(query: LsQuery): LsDocument {
         because: m.because,
         readable: reason === null,
         reason,
+        records: unloaded(m.records),
       };
     });
     const lsGroups: LsGroup[] = groups.map((g) => ({
@@ -162,7 +213,7 @@ export function listWorkspace(query: LsQuery): LsDocument {
           ? { code: "no-matches", message: `no directory ${g.group.globs.join(" or ")} matches${tree.label} holds a chant project` }
           : null,
     }));
-    return {
+    const doc: LsDocument = {
       ...head,
       at,
       workspace: {
@@ -172,6 +223,7 @@ export function listWorkspace(query: LsQuery): LsDocument {
         schema: declaration.schema,
         minReader: declaration.minReader,
         pins: declaration.pins,
+        records: unloaded(declaration.records),
       },
       members,
       groups: lsGroups,
@@ -182,9 +234,10 @@ export function listWorkspace(query: LsQuery): LsDocument {
         matches: lsGroups.reduce((n, g) => n + g.matches.length, 0),
       },
     };
+    return { doc, declaration, tree, rootOnDisk };
   } catch (err) {
     if (!(err instanceof WorkspaceReadError)) throw err;
-    return { ...head, error: { code: err.code, message: err.message, location: err.location ?? null } };
+    return { doc: { ...head, error: { code: err.code, message: err.message, location: err.location ?? null } } };
   }
 }
 
@@ -198,7 +251,7 @@ export async function runWorkspaceLs(ctx: CommandContext): Promise<number> {
   // The root's chant reads the declaration (ws-021).
   const handed = await handToRootChant(cwd, args.at);
   if (handed !== undefined) return handed;
-  const doc = listWorkspace({ cwd, at: args.at });
+  const doc = await listWorkspaceWithKinds({ cwd, at: args.at });
   if (args.json) {
     console.log(JSON.stringify(doc, null, 2));
   } else if ("error" in doc) {
@@ -233,6 +286,18 @@ function formatLs(doc: Extract<LsDocument, { members: unknown }>): string {
       if (m.reason) lines.push(`  ${m.reason.code}: ${m.reason.message}`);
     });
   }
+  const kinds = [...w.records.map((r) => ({ owner: "(workspace)", r })), ...doc.members.flatMap((m) => m.records.map((r) => ({ owner: m.name, r })))];
+  if (kinds.length > 0) {
+    lines.push("");
+    const rows = [["RECORDS", "KIND", "MEMBER", "FILE"]];
+    for (const { owner, r } of kinds) rows.push([r.name ?? "-", r.kind ?? "-", owner, r.path]);
+    const rendered = table(rows);
+    lines.push(rendered[0]);
+    kinds.forEach(({ r }, i) => {
+      lines.push(rendered[i + 1]);
+      if (r.reason) lines.push(`  ${r.reason.code}: ${r.reason.message}`);
+    });
+  }
   if (doc.groups.length > 0) {
     lines.push("");
     const rows = [["GROUP", "KIND", "GLOB", "PROJECTS"]];

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

@@ -6,9 +6,9 @@
  * `chant` member (`delivery`), three `other` members and decision records.
  * Each read-contract command reads it here, and its output must validate
  * against the command's schema: `ls`, `graph` (running delivery's real
- * `chant graph`), `graph --composites`, `check`, `status` and `records`, in
- * the working tree and, for `ls`, `graph` and `check`, at `HEAD` through
- * `--at`.
+ * `chant graph`), `graph --composites`, `check`, `status`, `records` and
+ * `records --since`, in the working tree and, for `ls`, `graph` and `check`,
+ * at `HEAD` through `--at`.
  *
  * The schemas themselves are checked here too: each is a draft 2020-12
  * document under `https://intentius.io/chant/schemas/workspace/<command>/v1/`,
@@ -34,13 +34,15 @@ import { readerBin, type Toolchain } from "./member-commands";
 import { READ_CONTRACT_FLOOR, READ_CONTRACT_VERSION } from "./reason-codes";
 import { queryRecords } from "./records-cli";
 import recordsSchema from "./records.schema.json";
+import { queryRecordsSince } from "./records-since";
+import recordsSinceSchema from "./records-since.schema.json";
 import { workspaceStatus } from "./status";
 import statusSchema from "./status.schema.json";
 
 const FIXTURE = join(REPO, "reference-workspace");
 const TIMEOUT = 240_000;
 
-const SCHEMAS = { ls: lsSchema, graph: graphSchema, check: checkSchema, status: statusSchema, records: recordsSchema, intent: intentSchema, composites: compositesSchema };
+const SCHEMAS = { ls: lsSchema, graph: graphSchema, check: checkSchema, status: statusSchema, records: recordsSchema, "records-since": recordsSinceSchema, intent: intentSchema, composites: compositesSchema };
 
 /** This checkout's chant, started the way the CLI starts it, for members with no toolchain of their own. */
 const reader: Toolchain = {
@@ -135,7 +137,7 @@ describe("every schema against the reference workspace (#2543)", () => {
   });
 
   test(
-    "graph --composites runs delivery's own component graph, and says why the list is empty (#2662)",
+    "graph --composites runs delivery's own component graph, and lists its app with the component that deploys it (#2662)",
     async () => {
       const { expectValid } = contract(compositesSchema);
       for (const at of [undefined, "HEAD"]) {
@@ -150,10 +152,15 @@ describe("every schema against the reference workspace (#2543)", () => {
           ["design-client", "skipped"],
           ["design", "skipped"],
         ]);
-        // delivery has a docker Service and no composite or component.
-        expect(doc.composites).toEqual([]);
-        expect(doc.components).toEqual([]);
-        expect(doc.reasons.map((r) => r.code)).toEqual(["composites-none-declared", "composites-no-component"]);
+        // delivery declares the app as a DockerWebService, and its app component names that kind.
+        expect(doc.composites.map((c) => [c.id, c.kinds, c.components.map((m) => [m.component, m.by, m.via])])).toEqual([
+          ["delivery/app", ["DockerWebService"], [["delivery/app", "composites", "member"]]],
+        ]);
+        expect(doc.components.map((c) => [c.id, c.archetype])).toEqual([["delivery/app", "service"]]);
+        // #2674: the reference config's lexicons host no component runs, so local is the only runtime, read at HEAD too.
+        expect(doc.components[0].runtimes).toEqual([{ name: "local", lexicon: null, default: true, command: "chant run --components app" }]);
+        expect(doc.members.find((m) => m.name === "delivery")!.runtimeReasons).toEqual([]);
+        expect(doc.reasons).toEqual([]);
       }
     },
     TIMEOUT,
@@ -168,5 +175,19 @@ describe("every schema against the reference workspace (#2543)", () => {
       expect(doc.summary.invalid).toBe(0);
       expect(doc.records.map((r) => r.id)).toContain("ref-001");
     }
+    const sessions = await queryRecords({ kind: "design/sessions/session.kind.mjs", cwd: FIXTURE });
+    expectValid(sessions);
+    if ("error" in sessions) throw new Error(sessions.error.message);
+    expect(sessions.summary.invalid).toBe(0);
+  });
+
+  test("records --since HEAD, for decisions and sessions (#2673)", async () => {
+    const { expectValid } = contract(recordsSinceSchema);
+    for (const kind of ["decisions/decision.kind.mjs", "design/sessions/session.kind.mjs"]) {
+      const doc = await queryRecordsSince({ kind, since: "HEAD", cwd: FIXTURE });
+      expectValid(doc);
+      if ("error" in doc) throw new Error(doc.error.message);
+      expect(doc.since).toBe(head);
+    }
   });
 });

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

@@ -10,7 +10,7 @@ import { join } from "node:path";
 import { describe, expect, test } from "vitest";
 import { REPO } from "./__fixtures__/contract-repo";
 import { MEMBER_RUN_REASON_CODES } from "./compose-graph";
-import { COMPOSITES_ERROR_CODES, COMPOSITES_REASON_CODES } from "./composites";
+import { COMPOSITES_ERROR_CODES, COMPOSITES_REASON_CODES, COMPOSITES_RUNTIME_REASON_CODES } from "./composites";
 import { WORKSPACE_ERROR_CODES } from "./declaration";
 import { GRAPH_ERROR_CODES } from "./graph-cli";
 import { INTENT_ERROR_CODES, INTENT_FINDING_CODES, INTENT_REASON_CODES } from "./intent";
@@ -19,8 +19,11 @@ import { GROUP_REASON_CODES, MEMBER_REASON_CODES } from "./ls";
 import intentSchema from "./intent.schema.json";
 import { isPluginCode, isReasonCode, REASON_CODES, REASONS } from "./reason-codes";
 import { contract } from "./__fixtures__/contract-repo";
-import { READ_ERROR_CODES, RECORD_REASON_CODES, RECORD_WARNING_CODES } from "./records";
-import { STATUS_ERROR_CODES, STATUS_REASON_CODES } from "./status";
+import { READ_ERROR_CODES, RECORD_REASON_CODES, RECORD_WARNING_CODES, REVIEW_REASON_CODES, SEAL_REASON_CODES } from "./records";
+import { AMEND_ERROR_CODES, NEW_ERROR_CODES, REVIEW_ERROR_CODES } from "./records-write";
+import { RECORDS_SINCE_ERROR_CODES } from "./records-since";
+import { STATUS_ERROR_CODES, STATUS_GATE_REASON_CODES, STATUS_REASON_CODES } from "./status";
+import { WORK_WARNING_CODES } from "./work";
 
 const HERE = import.meta.dirname;
 
@@ -34,14 +37,23 @@ const PER_COMMAND: Record<string, readonly string[]> = {
   CHECK_ERROR_CODES,
   STATUS_REASON_CODES,
   STATUS_ERROR_CODES,
+  STATUS_GATE_REASON_CODES,
   RECORD_REASON_CODES,
   RECORD_WARNING_CODES,
+  REVIEW_REASON_CODES,
+  SEAL_REASON_CODES,
+  WORK_WARNING_CODES,
   READ_ERROR_CODES,
+  NEW_ERROR_CODES,
+  AMEND_ERROR_CODES,
+  REVIEW_ERROR_CODES,
+  RECORDS_SINCE_ERROR_CODES,
   INTENT_ERROR_CODES,
   INTENT_FINDING_CODES,
   INTENT_REASON_CODES,
   COMPOSITES_ERROR_CODES,
   COMPOSITES_REASON_CODES,
+  COMPOSITES_RUNTIME_REASON_CODES,
 };
 
 /** Every string in an `enum` under a property named `code`, anywhere in a schema. */
@@ -103,7 +115,7 @@ describe("the closed list of reason codes", () => {
   });
 
   test("no source file emits a code outside the list", () => {
-    const emitted = /(?:\bcode:\s*|(?:WorkspaceReadError|RecordReadError|StatusError|IntentError)\(\s*)"([a-z0-9-]+)"/g;
+    const emitted = /(?:\bcode:\s*|(?:WorkspaceReadError|RecordReadError|RecordWriteError|StatusError|IntentError)\(\s*)"([a-z0-9-]+)"/g;
     let seen = 0;
     for (const file of sourceFiles(HERE)) {
       const text = readFileSync(file, "utf-8");

package/src/workspace/reason-codes.ts

@@ -53,18 +53,45 @@ export const REASONS = {
   // A ledger status can't fully read.
   "ledger-unreadable": "Reading the ledger failed, so nothing from it is listed.",
   "ledger-malformed": "Some lines of the ledger aren't release records; the rest are listed.",
+  // A member's gates status can't list (status, #2674).
+  "gates-no-ledger": "The checkout has no chant/lifecycle branch, so there is no gate ledger to read.",
+  "gates-no-gate-ledger": "The branch has no gate ledger for the member: no run of it has reached a gate.",
+  "gates-ledger-unreadable": "Reading the member's gate ledger failed, so no gate is listed.",
   // A record that isn't valid (records).
-  "record-unparseable": "No front matter, a YAML error, or a value outside the JSON subset of YAML.",
-  "record-schema-invalid": "The front matter does not match the kind's schema.",
+  "record-unparseable": "No front matter, a YAML error or a value outside the JSON subset of YAML, or for a JSON kind a file that is not one object or repeats a member name.",
+  "record-schema-invalid": "The record's front matter, or its JSON object, does not match the kind's schema.",
   "record-id-duplicate": "Another record earlier in path order has the same id.",
   "record-supersedes-unknown": "A supersedes link names an id no record has.",
   "record-supersedes-conflict": "A second closed record supersedes a record another one already superseded.",
+  // 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-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.",
   "asset-missing": "A file the record pins by hash does not exist in the tree read.",
   "asset-stale": "A file the record pins is unchanged at the hash a record it supersedes pinned: the decision changed and the artifact did not follow.",
   "record-supersedes-pending": "A supersedes link from a record whose state is weaker than the record it names, so the link has no effect yet.",
   "record-no-evidence": "The record's evidence list is empty: it cites nothing and pins no file. Information for a reviewer, never an error.",
+  "review-undigested": "A verdict names no digest of the text it judged. It still counts, and an amendment does not stop it counting.",
+  // A work record that is valid but warned about (records and graph --intent, #2683).
+  "work-needs-unknown": "A work record's needs list names a work id no record has, so the item stays blocked.",
+  "work-implements-unknown": "A work record's implements list names a decision id no decision has.",
+  "work-needs-cycle": "A work record needs itself through its needs links, so it can never be ready.",
+  "work-implements-undecided": "A work record implements a decision whose state is not approved, such as proposed.",
+  "work-done-unpinned": "A work record is done and its evidence list is empty: nothing shows the work was done.",
+  "work-closed-without-date": "A work record is done or dropped and has no closing date.",
+  "work-done-gap-open": "A work record is done, and the finding it came from still fires on its region. graph --intent raises it, and records does by walking that region.",
+  // A verdict the quorum does not count (records, #2671, #2672).
+  "review-decider": "The verdict is the decider's own, and the quorum counts verdicts besides the decider's.",
+  "review-agent": "The reviewer holds the agent role in the trust policy at base.",
+  "review-duplicate": "A later verdict by the same principal replaces this one. Names are compared after NFKC, trimming and lower-casing.",
+  "review-older-digest": "The verdict names a digest other than the record's text now: the record changed after the verdict.",
+  "review-unattested": "An attestation policy is active at base, and the verdict carries no seal that verifies for its reviewer.",
+  // A verdict's seal that is not attested (records, #2687). Every verdict reports one of these in its attestation, unless its seal verified.
+  "seal-missing": "The verdict carries no seal.",
+  "seal-signer-unlisted": "The reviewer 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 its signature does not verify over the verdict.",
+  "seal-unverifiable": "Nothing here can say whose seal it is: there is no signers file at base, or ssh-keygen is not installed.",
   // A records read that fails (records).
   "kind-unreadable": "The record kind file is missing or could not be imported.",
   "kind-invalid": "The record kind file exports no recordKind, or its shape is wrong.",
@@ -72,6 +99,21 @@ export const REASONS = {
   "schema-id-mismatch": "The schema's $id differs from the id the record kind names.",
   "schema-invalid": "The record schema itself does not compile.",
   "location-missing": "The records directory does not exist, in the tree or at the revision.",
+  // A records write that is refused (records new, amend and review, #2670). Nothing is written.
+  "write-usage-invalid": "The command line lacks a value the write needs, or gives one it does not take.",
+  "write-input-invalid": "The fields given with --from or --set can't be read, are not JSON, or are not a JSON object.",
+  "record-not-found": "No record of the kind has the id given.",
+  "record-id-taken": "The id given for a new record is already used, by a record or a file name.",
+  "record-id-unallocatable": "No id was given and none can be allocated: the records share no single prefix and --prefix names none.",
+  "record-path-unmatched": "The file name made from the record's id and title does not match the kind's location.",
+  "record-closed": "The record is in a closed state, so nothing in it changes; a new record supersedes it instead.",
+  "amend-id-immutable": "An amendment changes the record's id, and ids are never renumbered.",
+  "amend-supersede-instead": "The record is approved, and the amendment changes a field the approval rule does not let change in place; a new record supersedes it instead.",
+  "review-unsupported": "The kind's schema has no reviews field, so its records take no review.",
+  "review-note-required": "A dissent was given with no note: a dissent needs a reason.",
+  "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.",
+  // records --since that fails (#2673).
+  "since-rev-unknown": "--since names no commit.",
   // The intent graph (graph --intent, #2651): a read that fails.
   "intent-region-invalid": "The region's path, or its line range, does not exist in the tree read.",
   // The intent graph: part of the walk that can't be read. The document is still printed.
@@ -82,18 +124,26 @@ export const REASONS = {
   "intent-commit-bare": "A commit names no unit, no pull request and no decision covering the region at its time.",
   "intent-pin-drifted": "A decision's pinned artifact no longer hashes to the pin.",
   "intent-pin-missing": "A decision's pinned artifact does not exist in the tree read.",
+  "intent-pin-stale": "A current decision pins an artifact at the hash a record it supersedes pinned, and the artifact has not changed since: the decision moved on and the artifact did not.",
   "intent-artifact-unpinned": "An artifact decisions in the graph pinned, which no current decision pins.",
   "intent-decision-superseded-live": "Every decision constraining the region is superseded.",
   "intent-decision-provisional": "The current decisions constraining the region are all in states their kind does not close, such as decided.",
+  "intent-decision-contested": "A current decision constraining the region has an open concern: a dissent neither addressed nor withdrawn.",
   "intent-constraint-coarse": "The region is constrained only through its member, not by path.",
   "intent-constraint-lost": "A decision's path constraint names a path that does not exist in the tree read.",
   "intent-evidence-unpinned": "A decision's evidence has no hash: a URL, or a path with no sha256.",
   "intent-trailer-unverified": "A commit carries a trailer a plugin says claims authorship, and the commit is not attested.",
   "intent-region-unconstrained": "No decision constrains the region at any granularity.",
+  "intent-decision-unimplemented": "A decided decision constrains the region, no work item that is not dropped implements it, and no commit falls in its window.",
+  "intent-work-blocked": "A work item constraining the region has commits in its window while a work item it needs is not done.",
+  "intent-work-open-decided-code": "Commits in the region are a decision's own work while the work item implementing that decision is still open.",
   // Composite instances joined to components (graph --composites, #2662): why the list is empty or has no component.
   "composites-no-chant-member": "No member of kind chant was read, so nothing declares a composite instance or a component.",
   "composites-none-declared": "The members read declare no composite instance.",
   "composites-no-component": "The members read declare no component, so no composite instance has one.",
+  // The runtimes a member's components can deploy on (graph --composites, #2674).
+  "runtimes-config-unreadable": "The member's chant.config.ts could not be read, so only the built-in local runtime is listed.",
+  "runtimes-lexicon-unreadable": "A lexicon the member's config lists could not be loaded, so it is not listed as a runtime.",
   // 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.",
@@ -111,14 +161,15 @@ export function isReasonCode(value: unknown): value is ReasonCode {
 /**
  * A finding code a plugin contributes to the intent graph through its
  * `commitJoins` (#2656): `plugin:<name>:<code>`, where `<name>` is the kind's
- * name and `<code>` is lower case words joined by dashes. These are outside the
+ * name, or the kind file's `commitJoinsName` when it has one (#2663), and
+ * `<code>` is lower case words joined by dashes. These are outside the
  * closed list: the plugin owns its namespace, and core only carries them.
  */
 export type PluginCode = `plugin:${string}:${string}`;
 
 export const PLUGIN_CODE = /^plugin:([^:\s]+):([a-z0-9]+(?:-[a-z0-9]+)*)$/;
 
-/** Whether `value` is a plugin code, and, given `name`, one in that kind's namespace. */
+/** Whether `value` is a plugin code, and, given `name` (a kind's name or its `commitJoinsName`), one in that namespace. */
 export function isPluginCode(value: unknown, name?: string): value is PluginCode {
   if (typeof value !== "string") return false;
   const m = value.match(PLUGIN_CODE);

package/src/workspace/record-assets.test.ts

@@ -17,6 +17,7 @@ import { runChecks } from "./lineage-check";
 import { constraintCovers, isWorkspacePath, memberHolding, WORKSPACE_PATH_PATTERN } from "./record-assets";
 import { pinFile, queryRecords, type RecordsDocument } from "./records-cli";
 import { parseFrontMatter, RECORD_WARNING_CODES } from "./records";
+import { WORK_WARNING_CODES } from "./work";
 import { workspaceGraph } from "./graph-cli";
 import graphSchema from "./graph.schema.json";
 import recordsSchema from "./records.schema.json";
@@ -168,7 +169,8 @@ describe("chant workspace records checks each pin", () => {
   });
 
   test("the schema lists exactly the warning codes", () => {
-    expect(recordsSchema.$defs.warning.properties.code.enum).toEqual([...RECORD_WARNING_CODES]);
+    // A work kind's records carry the work warnings too (#2683), work-done-gap-open included since records walks a done item's region (#2686).
+    expect(recordsSchema.$defs.warning.properties.code.enum).toEqual([...RECORD_WARNING_CODES, ...WORK_WARNING_CODES]);
   });
 
   test("records pin <path> prints the entry's path from the workspace root and the file's hash", () => {

package/src/workspace/record-sessions.ts

@@ -0,0 +1,105 @@
+/**
+ * Review sessions (#2673, #2650 C10): a record kind whose records are the
+ * sessions a group reviewed records in. A session kind names, in its
+ * `session` declaration, the list of verdicts a session produced, the field
+ * that seals it once closed, and the kind file of the records its verdicts
+ * name (the subjects, such as decisions).
+ *
+ * On read, a closed session's seal has to match its text
+ * (`session-seal-mismatch`), and each verdict has to name a subject record
+ * that exists (`session-verdict-unknown-record`). Each session also lists the
+ * subjects' review entries that name it in their `session` field, as
+ * `citedBy`. This module only reads; nothing here writes a seal into a file.
+ */
+
+import { recordTextDigest, 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 {
+  /** The subject record's id. */
+  id: string;
+  /** The subject record's path, from the repository root. */
+  path: string;
+  /** The entry's position in the subject's reviews list, from 0. */
+  index: number;
+  /** The reviewer as the entry writes it, or null when it names none. */
+  reviewer: string | null;
+  /** The verdict as the entry writes it, or null when it names none. */
+  verdict: string | null;
+}
+
+/**
+ * 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.
+ */
+export function sessionSeal(text: string, field: string, format: RecordFormat = "markdown-front-matter"): string {
+  return recordTextDigest(text, field, format);
+}
+
+/**
+ * Check each session in `entries` against its seal and the subject records,
+ * and fill in `citedBy`. `texts` holds each entry's file text by path.
+ * `subjects` holds the subject records and the name of their reviews list;
+ * it is null when they were not read, and then no verdict is checked.
+ */
+export function joinSessions(kind: RecordKind, entries: RecordEntry[], texts: Map<string, string>, subjects: { records: RecordEntry[]; reviews: string } | null): void {
+  const decl = kind.session;
+  if (!decl) return;
+  const closed = new Set(kind.closedStates);
+  const subjectIds = new Set(subjects?.records.map((s) => s.id).filter((id): id is string => id !== null) ?? []);
+  const citations = new Map<string, SessionCitation[]>();
+  for (const s of subjects?.records ?? []) {
+    if (s.id === null) continue;
+    const reviews = s.data?.[subjects!.reviews];
+    if (!Array.isArray(reviews)) continue;
+    reviews.forEach((r, index) => {
+      if (r === null || typeof r !== "object") return;
+      const entry = r as Record<string, unknown>;
+      if (typeof entry.session !== "string") return;
+      const list = citations.get(entry.session) ?? [];
+      list.push({
+        id: s.id!,
+        path: s.path,
+        index,
+        reviewer: typeof entry.reviewer === "string" ? entry.reviewer : null,
+        verdict: typeof entry.verdict === "string" ? entry.verdict : null,
+      });
+      citations.set(entry.session, list);
+    });
+  }
+  for (const e of entries) {
+    e.citedBy = e.id === null ? [] : (citations.get(e.id) ?? []);
+    if (e.data === null) continue;
+    if (e.state !== null && closed.has(e.state)) {
+      const seal = e.data[decl.seal];
+      const text = texts.get(e.path);
+      if (typeof seal === "string" && text !== undefined) {
+        const actual = sessionSeal(text, decl.seal, kind.format);
+        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`,
+          });
+        }
+      }
+    }
+    if (subjects === null) continue;
+    const verdicts = e.data[decl.verdicts];
+    if (!Array.isArray(verdicts)) continue;
+    verdicts.forEach((v, i) => {
+      if (v === null || typeof v !== "object") return;
+      const record = (v as Record<string, unknown>).record;
+      if (typeof record === "string" && !subjectIds.has(record)) {
+        e.reasons.push({ code: "session-verdict-unknown-record", message: `${decl.verdicts}[${i}] names ${record}, which no ${decl.subjects.kind} record has` });
+      }
+    });
+  }
+}

package/src/workspace/record-source.ts

@@ -16,6 +16,8 @@ export interface RecordSource {
   list(dir: string): string[] | undefined;
   /** The text of a file listed by `list`. */
   read(path: string): string;
+  /** The bytes of a file listed by `list`, for a content-addressed id (ws-053). */
+  bytes(path: string): Uint8Array;
 }
 
 /** Records in the working tree under `root`. */
@@ -34,6 +36,9 @@ export function workingTreeSource(root: string): RecordSource {
     read(path) {
       return readFileSync(join(root, path), "utf-8");
     },
+    bytes(path) {
+      return readFileSync(join(root, path));
+    },
   };
 }
 
@@ -68,7 +73,12 @@ export function resolveRevision(root: string, rev: string): string {
 
 /** Records as they were at `commit`, read from the object store of the repository at `root`. */
 export function gitRevisionSource(root: string, commit: string): RecordSource {
-  const blobs = new Map<string, string>();
+  const blobs = new Map<string, Buffer>();
+  const blob = (path: string): Buffer => {
+    const bytes = blobs.get(path);
+    if (bytes === undefined) throw new Error(`${path} was not listed at ${commit}`);
+    return bytes;
+  };
   return {
     label: ` at ${commit.slice(0, 8)}`,
     list(dir) {
@@ -102,16 +112,15 @@ export function gitRevisionSource(root: string, commit: string): RecordSource {
           const nl = out.indexOf(0x0a, at);
           const size = Number(out.subarray(at, nl).toString("utf-8").split(" ")[2]);
           const start = nl + 1;
-          blobs.set(dir === "." ? e.name : `${dir}/${e.name}`, out.subarray(start, start + size).toString("utf-8"));
+          blobs.set(dir === "." ? e.name : `${dir}/${e.name}`, out.subarray(start, start + size));
           at = start + size + 1;
         }
       }
       return entries.map((e) => e.name);
     },
     read(path) {
-      const text = blobs.get(path);
-      if (text === undefined) throw new Error(`${path} was not listed at ${commit}`);
-      return text;
+      return blob(path).toString("utf-8");
     },
+    bytes: blob,
   };
 }