@intentius/chant 0.100.0 → 0.102.0

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

@@ -165,6 +165,11 @@
                 "source-harvest-not-proposed",
                 "record-state-not-initial",
                 "ratify-quorum-not-met",
+                "write-scope-member",
+                "write-scope-kind",
+                "write-scope-class-unknown",
+                "agent-unknown",
+                "principal-unidentified",
                 "record-unparseable",
                 "record-schema-invalid",
                 "record-id-duplicate",
@@ -172,6 +177,7 @@
                 "record-supersedes-conflict",
                 "record-remediates-unknown",
                 "record-remediates-not-closed",
+                "record-seal-mismatch",
                 "session-seal-mismatch",
                 "session-verdict-unknown-record"
               ]

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

@@ -259,6 +259,11 @@
                 "review-sign-failed",
                 "session-unknown",
                 "session-not-open",
+                "write-scope-member",
+                "write-scope-kind",
+                "write-scope-class-unknown",
+                "agent-unknown",
+                "principal-unidentified",
                 "record-unparseable",
                 "record-schema-invalid",
                 "record-id-duplicate",
@@ -266,6 +271,7 @@
                 "record-supersedes-conflict",
                 "record-remediates-unknown",
                 "record-remediates-not-closed",
+                "record-seal-mismatch",
                 "session-seal-mismatch",
                 "session-verdict-unknown-record"
               ]

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

@@ -5,9 +5,10 @@
  * decision reviews that cite it.
  */
 
-import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
 import { readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import yaml from "js-yaml";
 import { afterAll, describe, expect, test } from "vitest";
 import { cleanScratch, commitAll, contract, REPO } from "./__fixtures__/contract-repo";
 import { reviewed, sessionText, SESSIONS_KIND as SESSIONS, sessionsRepo as fixture } from "./__fixtures__/sessions";
@@ -34,14 +35,30 @@ describe("the session kind (#2673)", () => {
     expect(doc.records[0].citedBy).toEqual([]);
   });
 
-  test("the seal is the awk recipe the docs give", () => {
+  test("the seal is the whole-file JCS rule the docs give (#2546)", () => {
     const file = join(REPO, "reference-workspace", "design", "sessions", "S-0001-first-walk-of-the-reference-decisions.md");
-    const awk = execFileSync("sh", ["-c", `awk 'NR==1&&/^---$/{f=1;print;next} f&&/^---$/{f=0} f&&/^closed_digest:/{next} {print}' "$1" | shasum -a 256`, "sh", file], { encoding: "utf-8" });
     const text = readFileSync(file, "utf-8");
-    expect(awk.split(" ")[0]).toBe(sessionSeal(text, "closed_digest"));
-    expect(text).toContain(`closed_digest: "${sessionSeal(text, "closed_digest")}"`);
+    // The rule worked by hand: the front matter as JSON without closed_digest, the text below it, keys sorted, no whitespace.
+    const [, front, body] = /^---\n([\s\S]*?)\n---\n([\s\S]*)$/.exec(text)!;
+    const { closed_digest: _seal, ...core } = yaml.load(front, { schema: yaml.JSON_SCHEMA }) as Record<string, unknown>;
+    const sorted = (v: unknown): unknown =>
+      v === null || typeof v !== "object" ? v : Array.isArray(v) ? v.map(sorted) : Object.fromEntries(Object.keys(v).sort().map((k) => [k, sorted((v as Record<string, unknown>)[k])]));
+    const byHand = `sha256:${createHash("sha256").update(JSON.stringify(sorted({ body, core })), "utf8").digest("hex")}`;
+    expect(sessionSeal(text, "closed_digest")).toBe(byHand);
+    expect(text).toContain(`closed_digest: "${byHand}"`);
     // CRLF line endings hash as LF.
-    expect(sessionSeal(text.replace(/\n/g, "\r\n"), "closed_digest")).toBe(sessionSeal(text, "closed_digest"));
+    expect(sessionSeal(text.replace(/\n/g, "\r\n"), "closed_digest")).toBe(byHand);
+  });
+
+  test("a session sealed by the text rule before #2546 reads as session-seal-mismatch, naming the old rule", async () => {
+    const root = fixture();
+    const file = join(root, "design", "sessions", "S-0001-first-walk-of-the-reference-decisions.md");
+    const text = readFileSync(file, "utf-8");
+    const old = createHash("sha256").update(text.replace(/^closed_digest: .*\n/m, ""), "utf8").digest("hex");
+    writeFileSync(file, text.replace(/^closed_digest: .*$/m, `closed_digest: "${old}"`));
+    const s1 = (await read(root)).records[0];
+    expect(s1.reasons.map((r) => r.code)).toContain("session-seal-mismatch");
+    expect(s1.reasons.find((r) => r.code === "session-seal-mismatch")!.message).toMatch(/the text rule chant used before #2546/);
   });
 
   test("a closed session edited after it closed is session-seal-mismatch", async () => {

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

@@ -0,0 +1,171 @@
+/**
+ * Uncommitted records in the read contract (#3160): each record of a
+ * working-tree read says whether HEAD holds it as it is, the document names
+ * the branch, head and base, and `--uncommitted` lists only what HEAD
+ * doesn't hold. The documents validate against records.schema.json.
+ */
+
+import { execFileSync } from "node:child_process";
+import { cpSync, mkdtempSync, readFileSync, realpathSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import Ajv2020 from "ajv/dist/2020";
+import { afterAll, describe, expect, test } from "vitest";
+import { CONFORMANCE_FIXTURE_DIR, UNCOMMITTED_DECISION } from "./conformance";
+import { queryRecords, type RecordsDocument } from "./records-cli";
+import schema from "./records.schema.json";
+
+const validate = new Ajv2020({ strict: true, allErrors: true }).compile(schema);
+const KIND = "decisions/decision.kind.mjs";
+
+type Result = Extract<RecordsDocument, { records: unknown }>;
+
+function result(doc: RecordsDocument): Result {
+  expect(validate(doc), JSON.stringify(validate.errors, null, 2)).toBe(true);
+  if ("error" in doc) throw new Error(`${doc.error.code}: ${doc.error.message}`);
+  return doc;
+}
+
+const scratch: string[] = [];
+afterAll(() => {
+  for (const d of scratch) rmSync(d, { recursive: true, force: true });
+});
+
+const GIT_ENV = { ...process.env, GIT_CONFIG_GLOBAL: "/dev/null", GIT_CONFIG_NOSYSTEM: "1" };
+function git(cwd: string, ...args: string[]): string {
+  return execFileSync("git", ["-c", "user.name=t", "-c", "user.email=t@localhost", "-c", "commit.gpgsign=false", ...args], { cwd, env: GIT_ENV, encoding: "utf-8" }).trim();
+}
+
+const DECIDED = readFileSync(join(CONFORMANCE_FIXTURE_DIR, "decisions", "fix-001-how-the-app-is-deployed.md"), "utf-8");
+/** A decided record with id `fix-<n>`. */
+const decided = (n: string) => DECIDED.replace('id: "fix-001"', `id: "fix-${n}"`);
+/** A proposed record with id `fix-<n>`. */
+const proposed = (n: string) => UNCOMMITTED_DECISION.text.replace('id: "fix-002"', `id: "fix-${n}"`);
+const file = (n: string) => `decisions/fix-${n}-a-record.md`;
+
+/** A directory with the decision kind and its schema, and no records. */
+function kindDir(): string {
+  const root = realpathSync(mkdtempSync(join(tmpdir(), "chant-records-uncommitted-")));
+  scratch.push(root);
+  cpSync(join(CONFORMANCE_FIXTURE_DIR, "decisions"), join(root, "decisions"), { recursive: true, filter: (src) => !src.endsWith(".md") });
+  return root;
+}
+
+/** A repository whose main holds fix-001, fix-003 and fix-005, on a work branch one commit past main. */
+function repository(): { root: string; main: string } {
+  const root = kindDir();
+  for (const n of ["001", "003", "005"]) writeFileSync(join(root, file(n)), decided(n));
+  git(root, "init", "--quiet", "--initial-branch=main");
+  git(root, "add", "-A");
+  git(root, "commit", "--quiet", "-m", "records");
+  const main = git(root, "rev-parse", "HEAD");
+  git(root, "checkout", "--quiet", "-b", "chant/work/w-1");
+  writeFileSync(join(root, "notes.txt"), "work\n");
+  git(root, "add", "notes.txt");
+  git(root, "commit", "--quiet", "-m", "work");
+  return { root, main };
+}
+
+describe("records in the working tree (#3160)", () => {
+  test("each record is committed, modified or new against HEAD, and the checkout names its branch, head, base and deleted records", async () => {
+    const { root, main } = repository();
+    writeFileSync(join(root, file("001")), `${decided("001")}\nA line kept in the working tree.\n`);
+    writeFileSync(join(root, file("002")), proposed("002"));
+    writeFileSync(join(root, file("004")), proposed("004"));
+    git(root, "add", file("004"));
+    unlinkSync(join(root, file("003")));
+    const head = git(root, "rev-parse", "HEAD");
+
+    const doc = result(await queryRecords({ kind: KIND, cwd: root }));
+    expect(doc.uncommitted).toBe(false);
+    expect(doc.records.map((r) => [r.id, r.worktree])).toEqual([
+      ["fix-001", "modified"],
+      ["fix-002", "new"],
+      ["fix-004", "new"],
+      ["fix-005", "committed"],
+    ]);
+    expect(doc.checkout).toEqual({ branch: "chant/work/w-1", head, base: main, baseFrom: "main", deleted: [file("003")] });
+
+    const only = result(await queryRecords({ kind: KIND, cwd: root, uncommitted: true }));
+    expect(only.uncommitted).toBe(true);
+    expect(only.records.map((r) => [r.id, r.worktree])).toEqual([
+      ["fix-001", "modified"],
+      ["fix-002", "new"],
+      ["fix-004", "new"],
+    ]);
+    expect(only.checkout).toEqual(doc.checkout);
+    expect(only.summary).toEqual({ total: 3, valid: 3, invalid: 0, superseded: 0 });
+  });
+
+  test("a record changed back to what HEAD holds, or touched without a change, is committed, and the read leaves the index alone", async () => {
+    const { root } = repository();
+    const path = join(root, file("001"));
+    writeFileSync(path, decided("001"));
+    const index = join(root, ".git", "index");
+    const before = { bytes: readFileSync(index), mtime: statSync(index).mtimeMs };
+    const doc = result(await queryRecords({ kind: KIND, cwd: root, uncommitted: true }));
+    expect(doc.records).toEqual([]);
+    expect(doc.checkout?.deleted).toEqual([]);
+    expect(readFileSync(index).equals(before.bytes)).toBe(true);
+    expect(statSync(index).mtimeMs).toBe(before.mtime);
+  });
+
+  test("--base names the target the base is forked from", async () => {
+    const { root } = repository();
+    const head = git(root, "rev-parse", "HEAD");
+    const doc = result(await queryRecords({ kind: KIND, cwd: root, base: "HEAD" }));
+    expect(doc.checkout).toMatchObject({ head, base: head, baseFrom: "flag" });
+  });
+
+  test("a detached HEAD has no branch, and a repository with no commits has no head and only new records", async () => {
+    const { root } = repository();
+    git(root, "checkout", "--quiet", "--detach");
+    expect(result(await queryRecords({ kind: KIND, cwd: root })).checkout?.branch).toBeNull();
+
+    const empty = kindDir();
+    writeFileSync(join(empty, file("001")), decided("001"));
+    git(empty, "init", "--quiet", "--initial-branch=main");
+    const doc = result(await queryRecords({ kind: KIND, cwd: empty, uncommitted: true }));
+    expect(doc.checkout).toEqual({ branch: "main", head: null, base: null, baseFrom: null, deleted: [] });
+    expect(doc.records.map((r) => r.worktree)).toEqual(["new"]);
+  });
+
+  test("a read at a revision has no checkout and no worktree", async () => {
+    const { root } = repository();
+    writeFileSync(join(root, file("002")), proposed("002"));
+    const doc = result(await queryRecords({ kind: KIND, cwd: root, at: "HEAD" }));
+    expect(doc.checkout).toBeUndefined();
+    expect(doc.records.every((r) => r.worktree === undefined)).toBe(true);
+    await expect(queryRecords({ kind: KIND, cwd: root, at: "HEAD", uncommitted: true })).rejects.toThrow(/takes no --at/);
+  });
+
+  test("outside git a read has no checkout, and --uncommitted fails with not-a-git-repository", async () => {
+    const root = kindDir();
+    writeFileSync(join(root, file("001")), decided("001"));
+    const doc = result(await queryRecords({ kind: KIND, cwd: root }));
+    expect(doc.checkout).toBeUndefined();
+    expect(doc.records[0].worktree).toBeUndefined();
+    const failed = await queryRecords({ kind: KIND, cwd: root, uncommitted: true });
+    expect(validate(failed)).toBe(true);
+    expect(failed).toMatchObject({ error: { code: "not-a-git-repository" } });
+  });
+
+  test("the schema holds an --uncommitted document to its promise", () => {
+    const head = "a".repeat(40);
+    const doc = {
+      $schema: schema.$id,
+      contract: 1,
+      kind: { name: "decision", schema: "urn:x", file: KIND },
+      at: null,
+      current: false,
+      uncommitted: true,
+      checkout: { branch: "main", head, base: head, baseFrom: "main", deleted: [] },
+      records: [{ id: "fix-001", path: file("001"), state: "decided", valid: true, reasons: [], supersededBy: null, remediatedBy: [], data: {}, worktree: "new" }],
+      summary: { total: 1, valid: 1, invalid: 0, superseded: 0 },
+    };
+    expect(validate(doc)).toBe(true);
+    expect(validate({ ...doc, records: [{ ...doc.records[0], worktree: "committed" }] })).toBe(false);
+    const { checkout: _checkout, ...noCheckout } = doc;
+    expect(validate(noCheckout)).toBe(false);
+  });
+});

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

@@ -10,7 +10,7 @@ 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 as textDigest } from "./records";
+import { parseFrontMatter, recordSeal, recordTextDigest as textDigest } from "./records";
 import { queryRecords } from "./records-cli";
 import { allocateId, amendRecord, newRecord, renderRecord, reviewRecord, toYaml } from "./records-write";
 
@@ -21,7 +21,7 @@ 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 recordTextDigest = (text: string) => textDigest(text, ["reviews", "seal", "state", "closed_digest"]);
 
 const SAMPLE = (() => {
   const fm = parseFrontMatter(readFileSync(join(DECISIONS, "ws-003-seal-scope.md"), "utf-8"));
@@ -287,7 +287,7 @@ describe("records amend", () => {
     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"] });
+    expect(await amendRecord({ kind: KIND, id: "ws-001", fields: fields({ state: "ratified" }), cwd: dir })).toMatchObject({ changed: ["state", "closed_digest"] });
     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");
   });
@@ -353,12 +353,43 @@ describe("ratifying against the quorum (#2873)", () => {
     await agree("alice");
     await agree("bob");
     const judged = recordTextDigest(text("ws-001-one.md"));
-    expect(await ratify()).toMatchObject({ changed: ["state"] });
+    expect(await ratify()).toMatchObject({ changed: ["state", "closed_digest"] });
     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("ratifying writes the whole-file seal, which covers the reviews and the state the digest leaves out (#2546)", async () => {
+    await agree("alice");
+    await agree("bob");
+    const judged = textDigest(text("ws-001-one.md"), ["reviews", "seal", "state", "closed_digest"]);
+    await ratify();
+    const sealed = text("ws-001-one.md");
+    expect(data("ws-001-one.md").closed_digest).toMatch(/^sha256:[0-9a-f]{64}$/);
+    expect(data("ws-001-one.md").closed_digest).toBe(recordSeal(sealed, "closed_digest"));
+    // The closed_digest line goes last in the front matter, and the digest leaves it out.
+    expect(sealed).toMatch(/\nclosed_digest: "sha256:[0-9a-f]{64}"\n---\n/);
+    expect(textDigest(sealed, ["reviews", "seal", "state", "closed_digest"])).toBe(judged);
+    const read = async () => (await queryRecords({ kind: KIND, cwd: dir })) as { records: { id: string; valid: boolean; reasons: { code: string; message: string }[] }[] };
+    expect((await read()).records.find((r) => r.id === "ws-001")).toMatchObject({ valid: true, reasons: [] });
+    // A verdict, a state or a byte of the body edited by hand after the close breaks the seal.
+    for (const edit of [
+      (t: string) => t.replace('verdict: "agree"', 'verdict: "dissent"\n    note: "no"'),
+      (t: string) => t.replace('state: "ratified"', 'state: "superseded"'),
+      (t: string) => `${t}\nAn afterthought.\n`,
+    ]) {
+      writeFileSync(join(dir, "decisions", "ws-001-one.md"), edit(sealed));
+      const r = (await read()).records.find((x) => x.id === "ws-001")!;
+      expect(r.reasons.map((x) => x.code)).toContain("record-seal-mismatch");
+    }
+    // CRLF line endings, or a value quoted another way, leave the seal as it was.
+    writeFileSync(join(dir, "decisions", "ws-001-one.md"), sealed.replace('area: "D4"', "area: 'D4'").replace(/\n/g, "\r\n"));
+    expect((await read()).records.find((r) => r.id === "ws-001")).toMatchObject({ valid: true });
+    // And a closed record is never written again, so the seal can't be set by hand either.
+    writeFileSync(join(dir, "decisions", "ws-001-one.md"), sealed);
+    expect(code(await amendRecord({ kind: KIND, id: "ws-002", fields: fields({ closed_digest: `sha256:${"0".repeat(64)}` }), cwd: dir }))).toBe("write-input-invalid");
+  });
+
   test("a met quorum with an open concern ratifies, and the concern stays listed", async () => {
     await agree("alice");
     await agree("bob");
@@ -379,7 +410,7 @@ describe("ratifying against the quorum (#2873)", () => {
     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"] });
+    expect(await amendRecord({ kind: KIND, id: "ws-001", fields: fields({ state: "ratified", reviews }), cwd: dir })).toMatchObject({ changed: ["state", "reviews", "closed_digest"] });
     put("ws-006-six.md", decision({ id: "ws-006", title: "Six" }));
     await agree("alice", "ws-006");
     await agree("bob", "ws-006");
@@ -403,11 +434,11 @@ describe("ratifying against the quorum (#2873)", () => {
     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);
+    expect(await ratify()).toMatchObject({ changed: ["state", "closed_digest"] });
+    expect(textDigest(text("ws-001-one.md"), ["reviews", "seal", "closed_digest"])).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"] });
+    expect(await ratify("ws-006")).toMatchObject({ changed: ["state", "closed_digest"] });
   });
 
   test("a kind whose reviews.ratified is not one of its states is refused", async () => {
@@ -417,6 +448,32 @@ describe("ratifying against the quorum (#2873)", () => {
     expect(code(doc)).toBe("kind-invalid");
     expect("error" in doc && doc.error.message).toMatch(/reviews\.ratified must be one of states/);
   });
+
+  test("on a copy of the chant repo's own decisions, verdicts count through ratifying and sealing (#2555, ws-063)", async () => {
+    for (const f of readdirSync(join(dir, "decisions"))) if (f.endsWith(".md")) rmSync(join(dir, "decisions", f));
+    for (const f of readdirSync(DECISIONS)) if (/^ws-\d{3}-.+\.md$/.test(f)) cpSync(join(DECISIONS, f), join(dir, "decisions", f));
+    const read = async () => {
+      const doc = await queryRecords({ kind: KIND, cwd: dir });
+      if ("error" in doc) throw new Error(doc.error.message);
+      return doc.records;
+    };
+    const decided = (await read()).filter((r) => r.state === "decided");
+    expect(decided.length).toBeGreaterThan(50);
+    // Every sixth one, and the last, keeps the test inside the unit-test budget (#2817).
+    const sample = decided.filter((_, i) => i % 6 === 0 || i === decided.length - 1);
+    const judged = new Map(sample.map((r) => [r.id!, r.digest]));
+    for (const id of judged.keys()) {
+      await agree("alice", id);
+      await agree("Bob ", id);
+      expect(await ratify(id)).toMatchObject({ changed: ["state", "closed_digest"] });
+    }
+    for (const r of (await read()).filter((x) => judged.has(x.id!))) {
+      expect(r, r.id!).toMatchObject({ state: "ratified", valid: true, reasons: [], digest: judged.get(r.id!) });
+      expect(r.quorum, r.id!).toMatchObject({ agreed: 2, met: true, notCounted: [] });
+      expect(r.quorum!.counted.map((c) => c.principal), r.id!).toEqual(["alice", "bob"]);
+      expect(r.data?.closed_digest, r.id!).toBe(recordSeal(readFileSync(join(dir, r.path), "utf-8"), "closed_digest"));
+    }
+  });
 });
 
 describe("records review", () => {

package/src/workspace/records-write.ts

@@ -20,7 +20,9 @@
  * `records close` is in `records-close.ts`.
  *
  * `new --sign` and `amend --sign` seal the record's author (#2688), and
- * `review --sign` seals a verdict (#2687): see `trust/seal.ts`.
+ * `review --sign` seals a verdict (#2687): see `trust/seal.ts`. A record of
+ * a kind that declares `seal` gets its whole-file seal when `new` or `amend`
+ * writes it into a closed state (#2546, ws-063).
  */
 
 import { readFileSync, statSync, writeFileSync } from "node:fs";
@@ -37,6 +39,7 @@ import {
   RecordReadError,
   RECORD_SEAL_FIELD,
   digestFields,
+  recordSeal,
   recordTextDigest,
   type LoadedRecordKind,
   type RecordEntry,
@@ -47,6 +50,9 @@ import { policyAtBase, resolveBase } from "./trust/provenance";
 import { WorkspaceReadError } from "./declaration";
 import { findSessionKinds, headCommit, sessionKindsFor } from "./session-kinds";
 import { workingTree } from "./tree";
+import { AGENT_ENV, refuseRecordWrite, WRITE_SCOPE_CODES, WriteScopeError, type ScopeSource } from "./write-scope";
+import { IDENTITY_CODES, IdentityError, refuseUnidentified } from "./identity";
+import type { WriteVerb } from "./declaration";
 
 // ── Contract ─────────────────────────────────────────────────────────────────
 
@@ -72,6 +78,8 @@ export const NEW_ERROR_CODES = [
   "source-harvest-not-proposed",
   "record-state-not-initial",
   "ratify-quorum-not-met",
+  ...WRITE_SCOPE_CODES,
+  ...IDENTITY_CODES,
   ...RECORD_REASON_CODES,
 ] as const satisfies readonly ReasonCode[];
 
@@ -86,6 +94,8 @@ export const AMEND_ERROR_CODES = [
   "amend-supersede-instead",
   "record-sign-failed",
   "ratify-quorum-not-met",
+  ...WRITE_SCOPE_CODES,
+  ...IDENTITY_CODES,
   ...RECORD_REASON_CODES,
 ] as const satisfies readonly ReasonCode[];
 
@@ -100,6 +110,8 @@ export const REVIEW_ERROR_CODES = [
   "review-sign-failed",
   "session-unknown",
   "session-not-open",
+  ...WRITE_SCOPE_CODES,
+  ...IDENTITY_CODES,
   ...RECORD_REASON_CODES,
 ] as const satisfies readonly ReasonCode[];
 
@@ -348,6 +360,31 @@ export async function open(kind: string, cwd: string): Promise<Opened> {
   };
 }
 
+/**
+ * Refuse a write outside the writer's scope (#2548): the kind `o` opened,
+ * written with `verb`, by the session `agent` names (`CHANT_AGENT`) or the
+ * principal `by` names. Throws a {@link WriteScopeError}.
+ */
+export function refuseOutOfScope(o: Opened, verb: WriteVerb, cwd: string, writer: { agent?: string; by?: string }): ScopeSource {
+  const source = refuseRecordWrite(cwd, { kindName: o.loaded.kind.name, kindFile: o.loaded.file, recordsDir: o.loaded.dir, verb, agent: writer.agent, principal: writer.by });
+  // #3163: under identity.attribution "identified" at base, --by names a forge identity or a signer.
+  if (writer.by !== undefined) refuseUnidentified(source, [writer.by], "--by", { agent: writer.agent });
+  return source;
+}
+
+/**
+ * Refuse author fields (the kind's reviews.decider and proposedBy fields)
+ * that name a person by a bare name, under identity.attribution
+ * "identified" at base (#3163). `flag` is where the fields came from.
+ */
+function refuseUnidentifiedAuthors(source: ScopeSource, kind: Opened["loaded"]["kind"], fields: Record<string, unknown>, flag: string, agent?: string): void {
+  const names = [kind.reviews?.decider, kind.proposedBy?.field]
+    .filter((f): f is string => f !== undefined)
+    .map((f) => fields[f])
+    .filter((v): v is string => typeof v === "string" && v.trim() !== "");
+  refuseUnidentified(source, names, `${flag} author`, { agent });
+}
+
 /**
  * The kind's records as `records` reads them from `source`. A session kind's
  * subject records are read from the same source (#2693), so a write is
@@ -460,6 +497,33 @@ function refuseSealField(o: Opened, fields: Record<string, unknown>, flag: strin
   if (o.loaded.kind.reviews && RECORD_SEAL_FIELD in fields) {
     throw new RecordWriteError("write-input-invalid", `the fields given with ${flag} set ${RECORD_SEAL_FIELD}, and only --sign writes a record's seal`);
   }
+  const closed = o.loaded.kind.seal?.field;
+  if (closed !== undefined && !o.loaded.kind.session && closed in fields) {
+    throw new RecordWriteError("write-input-invalid", `the fields given with ${flag} set ${closed}, and chant writes it when the record closes`);
+  }
+}
+
+/**
+ * `text`, the record `data` holds, with its whole-file seal written into the
+ * kind's `seal.field` when the record is in a closed state (#2546, ws-063).
+ * The seal goes last, after the author seal, so it covers every other value
+ * and the body. `text` is returned as it is for a kind without `seal`, a
+ * session kind (whose seal `records close` writes), or an open record.
+ */
+function sealClosed(o: Opened, text: string, data: Record<string, unknown>, id: string): { text: string; data: Record<string, unknown> } {
+  const { kind } = o.loaded;
+  if (!kind.seal || kind.session || kind.stateField === undefined) return { text, data };
+  const state = data[kind.stateField];
+  if (typeof state !== "string" || !(kind.closedStates ?? []).includes(state)) return { text, data };
+  const field = kind.seal.field;
+  const seal = recordSeal(text, field, kind.format);
+  if (seal === null) throw new RecordWriteError("record-unparseable", `${id} can't be read, so it can't be sealed`);
+  const sealedData = { ...data, [field]: seal };
+  const sealed = replaceFields(text, { [field]: seal }, sealedData);
+  if (sealed === undefined || recordSeal(sealed, field, kind.format) !== seal) {
+    throw new RecordWriteError("record-unparseable", `the ${field} field can't be written into ${id} without changing the text it seals`);
+  }
+  return { text: sealed, data: sealedData };
 }
 
 /**
@@ -584,7 +648,7 @@ function today(): string {
 }
 
 export function failure<C>(schema: string, err: unknown): WriteFailure<C> {
-  if (err instanceof RecordWriteError || err instanceof RecordReadError) {
+  if (err instanceof RecordWriteError || err instanceof RecordReadError || err instanceof WriteScopeError || err instanceof IdentityError) {
     return { $schema: schema, contract: RECORDS_WRITE_CONTRACT_VERSION, error: { code: err.code as C, message: err.message } };
   }
   throw err;
@@ -644,6 +708,8 @@ export interface NewRecordOptions {
    * `reviews.decider` field, which the fields must set.
    */
   sign?: string | true;
+  /** The agent session the write is made in (`CHANT_AGENT`, #2548), which its write scope binds. */
+  agent?: string;
 }
 
 /**
@@ -727,8 +793,10 @@ export async function newRecord(opts: NewRecordOptions & ChannelOptions): Promis
       throw new RecordWriteError("write-usage-invalid", `--prefix takes letters and digits, starting with a letter, not ${JSON.stringify(opts.prefix)}`);
     }
     const o = await open(opts.kind, opts.cwd);
+    const scope = refuseOutOfScope(o, "new", opts.cwd, opts);
     const fields = applyChannel(o, parseFields(opts.fields, "--from"), opts, true, "--from");
     const { kind, schema } = o.loaded;
+    refuseUnidentifiedAuthors(scope, kind, fields, "--from", opts.agent);
     refuseSealField(o, fields, "--from");
     refuseRevisionFields(kind, fields, {}, "--from");
     const idField = kind.idField!;
@@ -758,6 +826,7 @@ export async function newRecord(opts: NewRecordOptions & ChannelOptions): Promis
     let text = renderRecord(data, title ? `\n# ${title}\n` : "");
     let seal: AuthorSeal | undefined;
     if (opts.sign !== undefined) ({ text, seal } = await sealAuthor(o, text, data, id, opts.sign, opts.cwd));
+    ({ text } = sealClosed(o, text, seal ? { ...data, [RECORD_SEAL_FIELD]: seal } : data, id));
     const written = await validatedEntry(o, before, path, text);
     await refuseRatifyBelowQuorum(o, written, id);
     const warnings = written.warnings;
@@ -789,6 +858,8 @@ export interface AmendRecordOptions {
   cwd: string;
   /** Seal the amended record's author, as `records new` does (#2688). */
   sign?: string | true;
+  /** The agent session the write is made in (#2548). */
+  agent?: string;
 }
 
 /**
@@ -808,8 +879,10 @@ export interface AmendRecordOptions {
 export async function amendRecord(opts: AmendRecordOptions & ChannelOptions): Promise<AmendDocument> {
   try {
     const o = await open(opts.kind, opts.cwd);
+    const scope = refuseOutOfScope(o, "amend", opts.cwd, opts);
     const given = applyChannel(o, parseFields(opts.fields, "--set"), opts, false, "--set");
     const { kind } = o.loaded;
+    refuseUnidentifiedAuthors(scope, kind, given, "--set", opts.agent);
     refuseSealField(o, given, "--set");
     const before = await readAll(o, o.source);
     const target = findRecord(before, opts.id, kind.name);
@@ -871,6 +944,12 @@ export async function amendRecord(opts: AmendRecordOptions & ChannelOptions): Pr
       sealDropped = `${opts.id} was sealed${typeof signer === "string" ? ` by ${signer}` : ""}, and the amendment moves its digest or its state, so the seal was removed: seal it again with records amend ${opts.id} --sign`;
     }
     if (stableJson(old[RECORD_SEAL_FIELD]) !== stableJson(merged[RECORD_SEAL_FIELD])) changed.push(RECORD_SEAL_FIELD);
+    // Entering a closed state seals the whole record, last (#2546, ws-063).
+    if (changed.length > 0 && kind.seal && !kind.session) {
+      const closedSeal = sealClosed(o, text, merged, opts.id);
+      text = closedSeal.text;
+      if (stableJson(old[kind.seal.field]) !== stableJson(closedSeal.data[kind.seal.field])) changed.push(kind.seal.field);
+    }
     let warnings = target.warnings;
     if (changed.length > 0) {
       const written = await validatedEntry(o, before, target.path, text);
@@ -916,6 +995,8 @@ export interface ReviewRecordOptions {
    * git's `user.signingkey`. Without it the verdict is written unsealed.
    */
   sign?: string | true;
+  /** The agent session the write is made in (#2548). */
+  agent?: string;
 }
 
 /**
@@ -932,6 +1013,7 @@ export async function reviewRecord(opts: ReviewRecordOptions): Promise<ReviewDoc
     if (opts.by.trim() === "") throw new RecordWriteError("write-usage-invalid", "--by needs the reviewer's name");
     if (opts.session !== undefined && opts.session === "") throw new RecordWriteError("write-usage-invalid", "--session needs a session id");
     const o = await open(opts.kind, opts.cwd);
+    refuseOutOfScope(o, "review", opts.cwd, opts);
     const { kind } = o.loaded;
     if (!kind.reviews) {
       throw new RecordWriteError("review-unsupported", `the ${kind.name} kind declares no reviews field, so its records take no review`);
@@ -946,6 +1028,8 @@ export async function reviewRecord(opts: ReviewRecordOptions): Promise<ReviewDoc
       throw new RecordWriteError("review-note-required", `a dissent needs a reason: pass --note <text> with the concern`);
     }
     const inSession = opts.session !== undefined ? await openSession(o, opts.session, opts.cwd) : undefined;
+    // The verdict is appended to the session too, so the session's kind must be in scope as well.
+    if (inSession) refuseOutOfScope(inSession.so, "review", opts.cwd, opts);
     const reviews = target.data[field] ?? [];
     if (!Array.isArray(reviews)) throw new RecordWriteError("record-schema-invalid", `${target.path}: ${field} is not a list`);
     const current = o.source.read(target.path);
@@ -1129,6 +1213,8 @@ export async function runRecordsWrite(ctx: CommandContext): Promise<number> {
   const { args } = ctx;
   const cwd = process.cwd();
   const verb = args.extraPositional;
+  // The agent session the write is made in (#2548): set by the harness that runs the agent.
+  const agent = process.env[AGENT_ENV] || undefined;
   const print = (doc: object): number => {
     console.log(JSON.stringify(doc, null, 2));
     return "error" in doc ? 1 : 0;
@@ -1140,7 +1226,7 @@ export async function runRecordsWrite(ctx: CommandContext): Promise<number> {
     if (!id) return print(usage(RECORDS_CLOSE_SCHEMA_ID, "close needs the session's id"));
     const kind = args.kind !== undefined ? resolveWriteKind(args.kind, cwd) : await declaredSessionKind(RECORDS_CLOSE_SCHEMA_ID, cwd);
     if (typeof kind !== "string") return print(kind);
-    return print(await closeRecord({ kind, id, dryRun: args.dryRun, cwd }));
+    return print(await closeRecord({ kind, id, dryRun: args.dryRun, cwd, agent }));
   }
   if (verb === "new") {
     const named = args.extraPositional2 ?? args.kind;
@@ -1148,7 +1234,7 @@ export async function runRecordsWrite(ctx: CommandContext): Promise<number> {
     if (typeof kind !== "string") return print(kind);
     const input = readInput(RECORDS_NEW_SCHEMA_ID, "--from", args.migrateFrom, cwd);
     if (typeof input !== "string") return print(input);
-    return print(await newRecord({ kind, fields: input, prefix: args.prefix, by: args.by, sign: args.sign, dryRun: args.dryRun, cwd }));
+    return print(await newRecord({ kind, fields: input, prefix: args.prefix, by: args.by, sign: args.sign, dryRun: args.dryRun, cwd, agent }));
   }
   const schema = verb === "amend" ? RECORDS_AMEND_SCHEMA_ID : RECORDS_REVIEW_SCHEMA_ID;
   const id = args.extraPositional2;
@@ -1159,11 +1245,11 @@ export async function runRecordsWrite(ctx: CommandContext): Promise<number> {
     if (args.by !== undefined) return print(usage(schema, "--by is not taken by amend: set decided_by, or a kind's proposedBy field, with --set"));
     const input = readInput(schema, "--set", args.set, cwd);
     if (typeof input !== "string") return print(input);
-    return print(await amendRecord({ kind, id, fields: input, sign: args.sign, dryRun: args.dryRun, cwd }));
+    return print(await amendRecord({ kind, id, fields: input, sign: args.sign, dryRun: args.dryRun, cwd, agent }));
   }
   if (args.verdict === undefined) return print(usage(schema, "--verdict agree|dissent|abstain is required"));
   if (args.by === undefined) return print(usage(schema, "--by <principal> is required"));
   return print(
-    await reviewRecord({ kind, id, verdict: args.verdict, by: args.by, note: args.note, session: args.session, sign: args.sign, dryRun: args.dryRun, cwd }),
+    await reviewRecord({ kind, id, verdict: args.verdict, by: args.by, note: args.note, session: args.session, sign: args.sign, dryRun: args.dryRun, cwd, agent }),
   );
 }