@intentius/chant 0.85.0 → 0.87.0

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

@@ -0,0 +1,158 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/chant/schemas/workspace/records-new/v1/records-new.schema.json",
+  "title": "chant workspace records new output",
+  "description": "What `chant workspace records new <kind file> --from <file|->` prints (#2670): the path and id of the record it wrote, or would write with --dry-run, or the reason it wrote nothing. Version 1 of the write contract for records. The command writes one file or none and never commits. Readers ignore fields they do not know; a field is only ever added within a version. The error codes are a closed list, each in the one closed list of `reason-codes.ts`. Contract version 1 of this document is written by chant 0.86.0 and newer.",
+  "oneOf": [
+    {
+      "$ref": "#/$defs/result"
+    },
+    {
+      "$ref": "#/$defs/failure"
+    }
+  ],
+  "$defs": {
+    "result": {
+      "description": "The record was written, or would be with --dry-run. Exit code 0.",
+      "type": "object",
+      "required": [
+        "$schema",
+        "contract",
+        "kind",
+        "path",
+        "id",
+        "dryRun",
+        "warnings"
+      ],
+      "properties": {
+        "$schema": {
+          "const": "https://intentius.io/chant/schemas/workspace/records-new/v1/records-new.schema.json"
+        },
+        "contract": {
+          "const": 1
+        },
+        "kind": {
+          "type": "object",
+          "required": [
+            "name",
+            "schema",
+            "file"
+          ],
+          "properties": {
+            "name": {
+              "type": "string",
+              "description": "The kind's name, such as \"decision\"."
+            },
+            "schema": {
+              "type": "string",
+              "description": "The `$id` of the schema the record was validated against."
+            },
+            "file": {
+              "type": "string",
+              "description": "The kind file, relative to the repository root, with / separators."
+            }
+          }
+        },
+        "path": {
+          "type": "string",
+          "description": "The record file, relative to the repository root (the working directory outside git), with / separators."
+        },
+        "id": {
+          "type": "string",
+          "description": "The record's id."
+        },
+        "dryRun": {
+          "type": "boolean",
+          "description": "True when --dry-run was given and nothing was written."
+        },
+        "warnings": {
+          "type": "array",
+          "description": "The written record's warnings, as chant workspace records reports them. A warning never refuses a write.",
+          "items": {
+            "$ref": "#/$defs/warning"
+          }
+        },
+        "text": {
+          "type": "string",
+          "description": "With --dry-run only: the whole text of the file the command would write."
+        },
+        "error": false
+      }
+    },
+    "warning": {
+      "type": "object",
+      "required": [
+        "code",
+        "message"
+      ],
+      "properties": {
+        "code": {
+          "enum": [
+            "asset-drift",
+            "asset-missing",
+            "asset-stale",
+            "record-supersedes-pending",
+            "record-no-evidence",
+            "review-undigested"
+          ]
+        },
+        "message": {
+          "type": "string"
+        }
+      }
+    },
+    "failure": {
+      "description": "Nothing was written. Exit code 1.",
+      "type": "object",
+      "required": [
+        "$schema",
+        "contract",
+        "error"
+      ],
+      "properties": {
+        "$schema": {
+          "const": "https://intentius.io/chant/schemas/workspace/records-new/v1/records-new.schema.json"
+        },
+        "contract": {
+          "const": 1
+        },
+        "error": {
+          "type": "object",
+          "required": [
+            "code",
+            "message"
+          ],
+          "properties": {
+            "code": {
+              "enum": [
+                "kind-unreadable",
+                "kind-invalid",
+                "schema-unreadable",
+                "schema-id-mismatch",
+                "schema-invalid",
+                "location-missing",
+                "write-usage-invalid",
+                "write-input-invalid",
+                "record-id-taken",
+                "record-id-unallocatable",
+                "record-path-unmatched",
+                "record-unparseable",
+                "record-schema-invalid",
+                "record-id-duplicate",
+                "record-supersedes-unknown",
+                "record-supersedes-conflict",
+                "session-seal-mismatch",
+                "session-verdict-unknown-record"
+              ]
+            },
+            "message": {
+              "type": "string",
+              "description": "What was wrong, and what to do instead when there is something, such as writing a new record that supersedes this one."
+            }
+          }
+        },
+        "path": false
+      }
+    }
+  }
+}

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

@@ -0,0 +1,196 @@
+/**
+ * A record's digest and its quorum (#2671, #2672).
+ *
+ * `recordTextDigest` hashes a record's text without its reviews block, so a
+ * verdict can name the text it judged and stop counting after an amendment.
+ * `computeQuorum` lists which verdicts count toward the quorum and why the
+ * others don't. The end-to-end reads through `records --json` are in
+ * records-contract.test.ts.
+ */
+
+import { execFileSync } from "node:child_process";
+import { cpSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+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";
+
+const REPO = join(import.meta.dirname, "..", "..", "..", "..");
+const DECISIONS = join(REPO, "docs", "design", "decisions");
+const SAMPLE = readFileSync(join(DECISIONS, "ws-003-seal-scope.md"), "utf-8");
+
+/** ws-003 with its reviews list replaced. `reviews` is the YAML under `reviews:`, or null for `reviews: []`. */
+function withReviews(reviews: string | null, text = SAMPLE): string {
+  return text.replace(/^reviews: \[\]$/m, reviews === null ? "reviews: []" : `reviews:\n${reviews.replace(/\n$/, "")}`);
+}
+
+/** One review entry as YAML. */
+function review(reviewer: string, verdict: string, extra: Record<string, string> = {}): string {
+  const note = verdict === "dissent" && !extra.note ? { note: "it misses a case" } : {};
+  const fields = { reviewer, verdict, on: "2026-09-24", ...note, ...extra };
+  return Object.entries(fields)
+    .map(([k, v], i) => `${i === 0 ? "  - " : "    "}${k}: ${JSON.stringify(v)}`)
+    .join("\n");
+}
+
+const BARE = recordTextDigest(SAMPLE);
+
+describe("recordTextDigest", () => {
+  test("is the sha256 hex of the text with the reviews block taken out", () => {
+    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));
+  });
+
+  test("does not move when a verdict is added, changed or removed", () => {
+    const one = withReviews(review("alice", "agree"));
+    const two = withReviews(`${review("alice", "agree", { digest: BARE })}\n${review("bob", "dissent", { note: "no" })}`);
+    expect(recordTextDigest(one)).toBe(BARE);
+    expect(recordTextDigest(two)).toBe(BARE);
+    // The compact form, with the list at column 0, and comments and blank lines inside the block.
+    const compact = SAMPLE.replace(/^reviews: \[\]$/m, `reviews:\n# first review\n- reviewer: "alice"\n  verdict: "agree"\n\n  on: "2026-09-24"`);
+    expect(recordTextDigest(compact)).toBe(BARE);
+    // A quoted key is the same key.
+    expect(recordTextDigest(SAMPLE.replace(/^reviews: \[\]$/m, `"reviews": []`))).toBe(BARE);
+  });
+
+  test("moves with any other edit, in the front matter or the body", () => {
+    expect(recordTextDigest(SAMPLE.replace(/^title: .*$/m, 'title: "Seal scope, amended"'))).not.toBe(BARE);
+    expect(recordTextDigest(`${SAMPLE}\nOne more line.\n`)).not.toBe(BARE);
+    // The line after the block is kept: removal stops at the next key.
+    expect(recordTextDigest(SAMPLE.replace(/^constrains:$/m, "constrains: # the scope"))).not.toBe(BARE);
+  });
+
+  test("reads CRLF and LF alike", () => {
+    expect(recordTextDigest(SAMPLE.replace(/\n/g, "\r\n"))).toBe(BARE);
+  });
+
+  test("hashes text with no front matter as it is", () => {
+    expect(recordTextDigest("reviews: []\nbody\n")).toBe(recordTextDigest("reviews: []\nbody\n", null));
+    expect(recordTextDigest("---\nreviews: []\nno closing line\n")).toBe(recordTextDigest("---\nreviews: []\nno closing line\n", null));
+  });
+
+  test("a hand-editor gets the same digest with awk and sha256sum", () => {
+    const dir = realpathSync(mkdtempSync(join(tmpdir(), "chant-digest-")));
+    try {
+      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 out = execFileSync("sh", ["-c", awk], { encoding: "utf-8" });
+      expect(out.split(" ")[0]).toBe(BARE);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});
+
+describe("normalisePrincipal", () => {
+  test("trims and case-folds", () => {
+    expect(normalisePrincipal("Alice ")).toBe("alice");
+    expect(normalisePrincipal(" ALICE")).toBe(normalisePrincipal("alice"));
+    expect(normalisePrincipal("ａｌｉｃｅ")).toBe("alice");
+  });
+});
+
+describe("computeQuorum", () => {
+  let dir: string;
+  beforeEach(() => {
+    dir = realpathSync(mkdtempSync(join(tmpdir(), "chant-quorum-")));
+    mkdirSync(join(dir, "decisions"));
+    cpSync(join(DECISIONS, "decision.kind.mjs"), join(dir, "decisions", "decision.kind.mjs"));
+    cpSync(join(DECISIONS, "decision.schema.json"), join(dir, "decisions", "decision.schema.json"));
+  });
+  afterEach(() => rmSync(dir, { recursive: true, force: true }));
+
+  const OPTIONS: QuorumOptions = { need: DEFAULT_QUORUM, needFrom: "default", agents: new Set(), attestation: false };
+
+  async function quorumOf(text: string, options: Partial<QuorumOptions> = {}) {
+    writeFileSync(join(dir, "decisions", "ws-003-seal-scope.md"), text);
+    const loaded = await loadRecordKind(join(dir, "decisions", "decision.kind.mjs"));
+    const { records } = await readRecords(loaded, { root: dir, source: workingTreeSource(dir) });
+    const record = records[0] as RecordEntry;
+    expect(record.reasons).toEqual([]);
+    return { record, quorum: computeQuorum(loaded.kind, record, { ...OPTIONS, ...options })! };
+  }
+
+  const principals = (list: Array<{ principal: string; reason?: { code: string } }>) => list.map((v) => (v.reason ? `${v.principal}:${v.reason.code}` : v.principal));
+
+  test("alice and 'Alice ' count once: the later verdict stands, the earlier is a duplicate", async () => {
+    const { quorum } = await quorumOf(withReviews(`${review("alice", "agree", { digest: BARE })}\n${review("Alice ", "agree", { digest: BARE })}`));
+    expect(principals(quorum.counted)).toEqual(["alice"]);
+    expect(quorum.counted[0].reviewer).toBe("Alice ");
+    expect(principals(quorum.notCounted)).toEqual(["alice:review-duplicate"]);
+    expect(quorum).toMatchObject({ need: 2, agreed: 1, met: false, metWithObjections: false });
+  });
+
+  test("a review by the decider is listed as not counted", async () => {
+    const { quorum } = await quorumOf(withReviews(`${review("Lex00", "agree", { digest: BARE })}\n${review("bob", "agree", { digest: BARE })}`));
+    expect(principals(quorum.notCounted)).toEqual(["lex00:review-decider"]);
+    expect(principals(quorum.counted)).toEqual(["bob"]);
+  });
+
+  test("amending the record after one agree drops the count from 1 to 0, with review-older-digest", async () => {
+    const reviewed = withReviews(review("alice", "agree", { digest: BARE }));
+    const before = await quorumOf(reviewed);
+    expect(before.quorum.agreed).toBe(1);
+    const after = await quorumOf(reviewed.replace(/^question: .*$/m, 'question: "What does a seal cover, now?"'));
+    expect(after.record.digest).not.toBe(BARE);
+    expect(after.quorum.counted).toEqual([]);
+    expect(after.quorum.agreed).toBe(0);
+    expect(principals(after.quorum.notCounted)).toEqual(["alice:review-older-digest"]);
+    expect(after.quorum.notCounted[0].reason!.message).toContain(BARE.slice(0, 12));
+  });
+
+  test("a verdict with no digest counts, and the record carries review-undigested", async () => {
+    const { record, quorum } = await quorumOf(withReviews(`${review("alice", "agree")}\n${review("bob", "agree", { digest: BARE })}`));
+    expect(principals(quorum.counted)).toEqual(["alice", "bob"]);
+    expect(quorum.counted[0].digest).toBeNull();
+    expect(quorum).toMatchObject({ agreed: 2, met: true, metWithObjections: false });
+    expect(record.warnings.map((w) => w.code)).toEqual(["review-undigested"]);
+    expect(record.warnings[0].message).toContain("alice");
+    expect(record.warnings[0].message).not.toContain("bob");
+  });
+
+  test("a met count with an open concern is met with objections, never consensus", async () => {
+    const reviews = [review("alice", "agree", { digest: BARE }), review("bob", "agree", { digest: BARE }), review("carol", "dissent", { digest: BARE, proposes: "ws-900" })];
+    const { quorum } = await quorumOf(withReviews(reviews.join("\n")));
+    expect(quorum).toMatchObject({ agreed: 2, met: true, metWithObjections: true });
+    expect(quorum.openConcerns).toEqual([{ index: 2, principal: "carol", reviewer: "carol", note: "it misses a case", proposes: "ws-900" }]);
+  });
+
+  test("an addressed or withdrawn dissent is no open concern", async () => {
+    const reviews = [
+      review("alice", "agree", { digest: BARE }),
+      review("bob", "agree", { digest: BARE }),
+      review("carol", "dissent", { digest: BARE, addressed_by: "ws-001" }),
+      review("dan", "dissent", { digest: BARE, withdrawn_on: "2026-09-25" }),
+    ];
+    const { quorum } = await quorumOf(withReviews(reviews.join("\n")));
+    expect(quorum.openConcerns).toEqual([]);
+    expect(quorum).toMatchObject({ met: true, metWithObjections: false });
+  });
+
+  test("an agent's verdict is not counted, and under an attestation policy an unsealed one is not either", async () => {
+    const text = withReviews(`${review("Bot-1", "agree", { digest: BARE })}\n${review("alice", "agree", { digest: BARE })}`);
+    const agents = await quorumOf(text, { agents: new Set(["bot-1"]) });
+    expect(principals(agents.quorum.notCounted)).toEqual(["bot-1:review-agent"]);
+    const attested = await quorumOf(text, { attestation: true });
+    expect(principals(attested.quorum.notCounted)).toEqual(["bot-1:review-unattested", "alice:review-unattested"]);
+    expect(attested.quorum.counted).toEqual([]);
+  });
+
+  test("the declared need applies, and a need of 0 is met with no verdict", async () => {
+    const { quorum } = await quorumOf(SAMPLE, { need: 0, needFrom: "declaration" });
+    expect(quorum).toMatchObject({ need: 0, needFrom: "declaration", agreed: 0, met: true, counted: [], notCounted: [], openConcerns: [] });
+  });
+
+  test("a kind with no reviews list has no quorum", async () => {
+    const loaded = await loadRecordKind(join(DECISIONS, "decision.kind.mjs"));
+    const { reviews: _drop, ...kind } = loaded.kind;
+    expect(computeQuorum(kind, { data: {}, digest: BARE }, OPTIONS)).toBeNull();
+    expect(computeQuorum(loaded.kind, { data: null, digest: BARE }, OPTIONS)).toBeNull();
+  });
+});

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

@@ -0,0 +1,227 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/chant/schemas/workspace/records-review/v1/records-review.schema.json",
+  "title": "chant workspace records review output",
+  "description": "What `chant workspace records review <id> --kind <kind file> --verdict <verdict> --by <principal>` prints (#2670): the record's path and id and the review entry appended, or the reason it wrote nothing. Version 1 of the write contract for records. The command writes one file or none and never commits. Readers ignore fields they do not know; a field is only ever added within a version. The error codes are a closed list, each in the one closed list of `reason-codes.ts`. Contract version 1 of this document is written by chant 0.86.0 and newer.",
+  "oneOf": [
+    {
+      "$ref": "#/$defs/result"
+    },
+    {
+      "$ref": "#/$defs/failure"
+    }
+  ],
+  "$defs": {
+    "result": {
+      "description": "The record was written, or would be with --dry-run. Exit code 0.",
+      "type": "object",
+      "required": [
+        "$schema",
+        "contract",
+        "kind",
+        "path",
+        "id",
+        "review",
+        "dryRun",
+        "warnings"
+      ],
+      "properties": {
+        "$schema": {
+          "const": "https://intentius.io/chant/schemas/workspace/records-review/v1/records-review.schema.json"
+        },
+        "contract": {
+          "const": 1
+        },
+        "kind": {
+          "type": "object",
+          "required": [
+            "name",
+            "schema",
+            "file"
+          ],
+          "properties": {
+            "name": {
+              "type": "string",
+              "description": "The kind's name, such as \"decision\"."
+            },
+            "schema": {
+              "type": "string",
+              "description": "The `$id` of the schema the record was validated against."
+            },
+            "file": {
+              "type": "string",
+              "description": "The kind file, relative to the repository root, with / separators."
+            }
+          }
+        },
+        "path": {
+          "type": "string",
+          "description": "The record file, relative to the repository root (the working directory outside git), with / separators."
+        },
+        "id": {
+          "type": "string",
+          "description": "The record's id."
+        },
+        "review": {
+          "type": "object",
+          "description": "The entry appended to the record's reviews, as written.",
+          "required": [
+            "reviewer",
+            "verdict",
+            "on",
+            "digest"
+          ],
+          "properties": {
+            "reviewer": {
+              "type": "string",
+              "minLength": 1,
+              "description": "The principal given with --by, as given. The write does not check who it is. With --sign, the seal lets chant workspace records check it against the signers file at base (#2687)."
+            },
+            "verdict": {
+              "enum": [
+                "agree",
+                "dissent",
+                "abstain"
+              ]
+            },
+            "note": {
+              "type": "string",
+              "description": "The note given with --note. Absent when none was given; a dissent always has one."
+            },
+            "on": {
+              "type": "string",
+              "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$",
+              "description": "The date of the verdict, in UTC."
+            },
+            "digest": {
+              "type": "string",
+              "pattern": "^[0-9a-f]{64}$",
+              "description": "The digest of the record text the verdict judged: the lowercase hex SHA-256 of the file with LF line endings and without its reviews block (#2672), as records prints it for the record. The command changes only the reviews block, so the record keeps this digest."
+            },
+            "session": {
+              "type": "string",
+              "minLength": 1,
+              "description": "The session given with --session. Absent when none was given."
+            },
+            "seal": {
+              "type": "object",
+              "description": "Added in contract 1 by #2687. With --sign only: an ssh signature by the key given (or git's user.signingkey) over <id>\\n<digest>\\n<verdict>\\n<reviewer>\\n<on>, in the ssh-keygen namespace chant-review. The write does not check the key against the signers file; chant workspace records reports whether the seal counts.",
+              "required": [
+                "signer",
+                "key",
+                "signature"
+              ],
+              "properties": {
+                "signer": {
+                  "type": "string",
+                  "description": "The reviewer given with --by."
+                },
+                "key": {
+                  "type": "string",
+                  "pattern": "^SHA256:[A-Za-z0-9+/]+=*$",
+                  "description": "The fingerprint of the key that signed, read back from the signature."
+                },
+                "signature": {
+                  "type": "string",
+                  "description": "The armored ssh signature."
+                }
+              }
+            }
+          }
+        },
+        "dryRun": {
+          "type": "boolean",
+          "description": "True when --dry-run was given and nothing was written."
+        },
+        "warnings": {
+          "type": "array",
+          "description": "The written record's warnings, as chant workspace records reports them. A warning never refuses a write.",
+          "items": {
+            "$ref": "#/$defs/warning"
+          }
+        },
+        "text": {
+          "type": "string",
+          "description": "With --dry-run only: the whole text of the file the command would write."
+        },
+        "error": false
+      }
+    },
+    "warning": {
+      "type": "object",
+      "required": [
+        "code",
+        "message"
+      ],
+      "properties": {
+        "code": {
+          "enum": [
+            "asset-drift",
+            "asset-missing",
+            "asset-stale",
+            "record-supersedes-pending",
+            "record-no-evidence",
+            "review-undigested"
+          ]
+        },
+        "message": {
+          "type": "string"
+        }
+      }
+    },
+    "failure": {
+      "description": "Nothing was written. Exit code 1.",
+      "type": "object",
+      "required": [
+        "$schema",
+        "contract",
+        "error"
+      ],
+      "properties": {
+        "$schema": {
+          "const": "https://intentius.io/chant/schemas/workspace/records-review/v1/records-review.schema.json"
+        },
+        "contract": {
+          "const": 1
+        },
+        "error": {
+          "type": "object",
+          "required": [
+            "code",
+            "message"
+          ],
+          "properties": {
+            "code": {
+              "enum": [
+                "kind-unreadable",
+                "kind-invalid",
+                "schema-unreadable",
+                "schema-id-mismatch",
+                "schema-invalid",
+                "location-missing",
+                "write-usage-invalid",
+                "record-not-found",
+                "review-unsupported",
+                "record-closed",
+                "review-note-required",
+                "review-sign-failed",
+                "record-unparseable",
+                "record-schema-invalid",
+                "record-id-duplicate",
+                "record-supersedes-unknown",
+                "record-supersedes-conflict",
+                "session-seal-mismatch",
+                "session-verdict-unknown-record"
+              ]
+            },
+            "message": {
+              "type": "string",
+              "description": "What was wrong, and what to do instead when there is something, such as writing a new record that supersedes this one."
+            }
+          }
+        },
+        "path": false
+      }
+    }
+  }
+}