@intentius/chant 0.84.0 → 0.86.0

package/src/workspace/records.schema.json

@@ -3,8 +3,44 @@
   "$id": "https://intentius.io/chant/schemas/workspace/records/v1/records.schema.json",
   "title": "chant workspace records output",
   "description": "What `chant workspace records --json` prints, version 1 of the read contract for records (#2536). This is the first-test slice (#2546): records are unsealed and there is no workspace declaration yet. Readers ignore fields they do not know; a field is only ever added within a version. The reason and error codes are closed lists: a new code is a new contract version. Contract version 1 is written by chant 0.81.0 and newer; a reader that needs it refuses output whose `contract` it doesn't know. Every code is in the one closed list of `reason-codes.ts`.",
-  "oneOf": [{ "$ref": "#/$defs/result" }, { "$ref": "#/$defs/failure" }],
+  "oneOf": [{ "$ref": "#/$defs/result" }, { "$ref": "#/$defs/failure" }, { "$ref": "#/$defs/set" }],
   "$defs": {
+    "set": {
+      "description": "Added in contract 1 by #2680. What records prints without --kind when the workspace declaration names record kinds: one result or failure per declared kind, in the declaration's order (the workspace's own kinds, then each member's in member order). Exit code 1 when any kind's read failed; the others are still read and listed.",
+      "type": "object",
+      "required": ["$schema", "contract", "kinds"],
+      "properties": {
+        "$schema": { "const": "https://intentius.io/chant/schemas/workspace/records/v1/records.schema.json" },
+        "contract": { "const": 1 },
+        "kinds": {
+          "type": "array",
+          "items": {
+            "allOf": [
+              { "oneOf": [{ "$ref": "#/$defs/result" }, { "$ref": "#/$defs/failure" }] },
+              {
+                "type": "object",
+                "required": ["declared"],
+                "properties": {
+                  "declared": {
+                    "description": "The declaration's entry for the kind.",
+                    "type": "object",
+                    "required": ["member", "path", "name"],
+                    "properties": {
+                      "member": { "type": ["string", "null"], "description": "The member that declares the kind, or null for the workspace's own." },
+                      "path": { "type": "string", "description": "The kind file from the workspace root, with / separators." },
+                      "name": { "type": ["string", "null"], "description": "The name the declaration gives the kind, or null; kind.name is the kind file's own." }
+                    }
+                  }
+                }
+              }
+            ]
+          }
+        },
+        "kind": false,
+        "records": false,
+        "error": false
+      }
+    },
     "result": {
       "description": "The read worked. Exit code 0, even when some records are invalid.",
       "type": "object",
@@ -18,7 +54,11 @@
           "properties": {
             "name": { "type": "string", "description": "The kind's name, such as \"decision\"." },
             "schema": { "type": "string", "description": "The `$id` of the schema each record was validated against." },
-            "file": { "type": "string", "description": "The kind file, relative to the repository root, with / separators." }
+            "file": { "type": "string", "description": "The kind file, relative to the repository root, with / separators." },
+            "format": {
+              "enum": ["markdown-front-matter", "json"],
+              "description": "Added in contract 1 by #2664 (ws-053). How each record file holds its structured core: the YAML front matter of a Markdown file, or the whole file as one JSON object, read as I-JSON (no repeated member name)."
+            }
           }
         },
         "at": {
@@ -47,16 +87,40 @@
             "invalid": { "type": "integer", "minimum": 0 },
             "superseded": { "type": "integer", "minimum": 0, "description": "Records a closed record supersedes, counted before --current leaves them out." }
           }
+        },
+        "decisions": {
+          "description": "Added in contract 1 by #2683, for a work kind only. Every decision the kind file named in the work kind's work.decisions reads at the same revision, whether or not a work record names it, each with the work records implementing it. A decision with an empty implementedBy has no work item yet.",
+          "type": "array",
+          "items": { "$ref": "#/$defs/decisionWork" }
         }
       }
     },
+    "workLink": {
+      "type": "object",
+      "required": ["id", "state"],
+      "properties": {
+        "id": { "type": "string" },
+        "state": { "type": ["string", "null"], "description": "The linked record's state as it writes it, or null when no record has the id." }
+      }
+    },
+    "decisionWork": {
+      "type": "object",
+      "required": ["id", "path", "state", "supersededBy", "implementedBy"],
+      "properties": {
+        "id": { "type": "string" },
+        "path": { "type": "string", "description": "From the repository root, with / separators." },
+        "state": { "type": ["string", "null"] },
+        "supersededBy": { "type": ["string", "null"] },
+        "implementedBy": { "type": "array", "items": { "$ref": "#/$defs/workLink" }, "description": "The work records whose implements list names the decision, in path order." }
+      }
+    },
     "record": {
       "type": "object",
       "required": ["id", "path", "state", "valid", "reasons", "supersededBy", "data"],
       "properties": {
-        "id": { "type": ["string", "null"], "description": "Null when the front matter could not be parsed or has no string id." },
+        "id": { "type": ["string", "null"], "description": "Null when the record could not be parsed or has no string id. For a content-addressed kind (idFrom sha256, added by #2664), the lowercase hex SHA-256 of the file's bytes, the same string a pin of the file carries." },
         "path": { "type": "string", "description": "From the repository root, with / separators." },
-        "state": { "type": ["string", "null"], "description": "The state as the record writes it. Supersession is reported in supersededBy, not here." },
+        "state": { "type": ["string", "null"], "description": "The state as the record writes it. Supersession is reported in supersededBy, not here. Null for every record of a kind without states (#2664)." },
         "valid": { "type": "boolean", "description": "True exactly when reasons is empty." },
         "reasons": { "type": "array", "items": { "$ref": "#/$defs/reason" } },
         "supersededBy": {
@@ -65,18 +129,46 @@
         },
         "data": {
           "type": ["object", "null"],
-          "description": "The front matter as JSON, following the kind's schema when valid is true. Null when it could not be parsed."
+          "description": "The record's structured core as JSON: the front matter, or for a kind of format json the whole file (#2664). It follows the kind's schema when valid is true. Null when it could not be parsed."
         },
         "provenance": { "$ref": "#/$defs/provenance" },
         "assets": {
-          "description": "Added in contract 1 by #2549. Each workspace file the record pins by hash, checked against the tree read: the working tree, or the revision under --at. Empty for a kind that pins nothing.",
+          "description": "Added in contract 1 by #2549. Each workspace file the record pins by hash, checked against the tree read: the working tree, or the revision under --at. Empty for a kind that pins nothing. A record of a content-addressed kind (#2664) whose file name claims a hash other than its bytes' lists itself here as drifted, with sha256 the hash the name claims and actual its id.",
           "type": "array",
           "items": { "$ref": "#/$defs/asset" }
         },
         "warnings": {
-          "description": "Added in contract 1 by #2549. Findings that leave the record valid: a pinned file that changed, went missing or did not follow a superseding decision, or a supersedes link that has no effect yet. valid and --current do not look at them.",
+          "description": "Added in contract 1 by #2549. Findings that leave the record valid: a pinned file that changed, went missing or did not follow a superseding decision, a supersedes link that has no effect yet, (added by #2654) an evidence list that is empty, (added by #2672) a verdict that names no digest, or (added by #2683) a work record's links and dates. A work record never carries record-no-evidence; a done one with no evidence carries work-done-unpinned. valid and --current do not look at them.",
           "type": "array",
           "items": { "$ref": "#/$defs/warning" }
+        },
+        "digest": {
+          "description": "Added in contract 1 by #2672. The lowercase hex SHA-256 of the record file's text, with LF line endings and without the kind's reviews block in the front matter, or for a kind of format json without the top-level reviews member and one comma beside it (#2664). A review verdict names it in its digest field, and stops counting once the record's digest moves on. For a kind with no reviews list, the digest of the whole text.",
+          "type": "string",
+          "pattern": "^[0-9a-f]{64}$"
+        },
+        "quorum": {
+          "description": "Added in contract 1 by #2671, on every record of a kind with a reviews list. Null when the front matter could not be parsed.",
+          "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/quorum" }]
+        },
+        "citedBy": {
+          "description": "Added in contract 1 by #2673, on every record of a session kind and on no other. The review entries of the records the session kind names as its subjects (decisions, for the reference session kind) whose session field names this record's id, in path order and then list order.",
+          "type": "array",
+          "items": { "$ref": "#/$defs/citation" }
+        },
+        "ready": {
+          "description": "Added in contract 1 by #2683, on every parsed record of a work kind. True when the record is valid, not superseded, in the kind's open state, not in a needs cycle, and every work id its needs list names is done.",
+          "type": "boolean"
+        },
+        "blockedBy": {
+          "description": "Added in contract 1 by #2683, on every parsed record of a work kind. Each need that is not done, with its state now; null for an id no record has.",
+          "type": "array",
+          "items": { "$ref": "#/$defs/workLink" }
+        },
+        "implements": {
+          "description": "Added in contract 1 by #2683, on every parsed record of a work kind. Each decision the record implements, with its state now; null for an id no decision has.",
+          "type": "array",
+          "items": { "$ref": "#/$defs/workLink" }
         }
       },
       "allOf": [
@@ -101,10 +193,94 @@
       "type": "object",
       "required": ["code", "message"],
       "properties": {
-        "code": { "enum": ["asset-drift", "asset-missing", "asset-stale", "record-supersedes-pending"] },
+        "code": {
+          "enum": [
+            "asset-drift",
+            "asset-missing",
+            "asset-stale",
+            "record-supersedes-pending",
+            "record-no-evidence",
+            "review-undigested",
+            "work-needs-unknown",
+            "work-implements-unknown",
+            "work-needs-cycle",
+            "work-implements-undecided",
+            "work-done-unpinned",
+            "work-closed-without-date"
+          ]
+        },
         "message": { "type": "string" }
       }
     },
+    "quorum": {
+      "description": "Added in contract 1 by #2671. The record's review verdicts counted against the quorum the workspace declares. A met quorum with an open concern is met with objections, never consensus: a reader shows consensus only when met is true and metWithObjections is false.",
+      "type": "object",
+      "required": ["need", "needFrom", "agreed", "counted", "notCounted", "openConcerns", "met", "metWithObjections"],
+      "properties": {
+        "need": { "type": "integer", "minimum": 0, "description": "How many counted agree verdicts, besides the decider's, the record needs: the declaration's quorum, or 2." },
+        "needFrom": { "enum": ["declaration", "default"], "description": "declaration when the workspace declaration in the tree read sets quorum; default otherwise, including when there is no declaration or it can't be read." },
+        "agreed": { "type": "integer", "minimum": 0, "description": "Counted verdicts whose verdict is agree." },
+        "counted": {
+          "description": "The verdicts that count: at most one per principal, the latest, in the order of the reviews list.",
+          "type": "array",
+          "items": { "allOf": [{ "$ref": "#/$defs/verdict" }, { "type": "object", "properties": { "reason": false } }] }
+        },
+        "notCounted": {
+          "description": "The verdicts that don't count, each with a reason.",
+          "type": "array",
+          "items": { "allOf": [{ "$ref": "#/$defs/verdict" }, { "type": "object", "required": ["reason"] }] }
+        },
+        "openConcerns": {
+          "description": "Every dissent with neither addressed_by nor withdrawn_on, counted or not.",
+          "type": "array",
+          "items": { "$ref": "#/$defs/concern" }
+        },
+        "met": { "type": "boolean", "description": "agreed is at least need." },
+        "metWithObjections": { "type": "boolean", "description": "met, and openConcerns is not empty." }
+      }
+    },
+    "verdict": {
+      "type": "object",
+      "required": ["index", "principal", "reviewer", "verdict", "digest"],
+      "properties": {
+        "index": { "type": "integer", "minimum": 0, "description": "The entry's position in the record's reviews list, from 0." },
+        "principal": { "type": "string", "description": "The reviewer after NFKC normalisation, trimming and lower-casing, so alice and \"Alice \" are one principal." },
+        "reviewer": { "type": "string", "description": "The reviewer as the record writes it." },
+        "verdict": { "enum": ["agree", "dissent", "abstain"] },
+        "digest": { "type": ["string", "null"], "description": "The digest the verdict names, or null when it names none (a warning review-undigested on the record)." },
+        "reason": {
+          "description": "Why the verdict does not count. Present exactly on the entries in notCounted.",
+          "type": "object",
+          "required": ["code", "message"],
+          "properties": {
+            "code": { "enum": ["review-decider", "review-agent", "review-duplicate", "review-older-digest", "review-unattested"] },
+            "message": { "type": "string" }
+          }
+        }
+      }
+    },
+    "concern": {
+      "type": "object",
+      "required": ["index", "principal", "reviewer", "note"],
+      "properties": {
+        "index": { "type": "integer", "minimum": 0 },
+        "principal": { "type": "string" },
+        "reviewer": { "type": "string" },
+        "note": { "type": ["string", "null"], "description": "The dissent's reason." },
+        "proposes": { "type": "string", "description": "The proposed decision the dissent opened, when it names one." }
+      }
+    },
+    "citation": {
+      "type": "object",
+      "required": ["id", "path", "index", "reviewer", "verdict"],
+      "properties": {
+        "id": { "type": "string", "description": "The subject record's id." },
+        "path": { "type": "string", "description": "The subject record's path from the repository root, with / separators." },
+        "index": { "type": "integer", "minimum": 0, "description": "The entry's position in the subject's reviews list, from 0." },
+        "reviewer": { "type": ["string", "null"], "description": "The reviewer as the entry writes it, or null when it names none." },
+        "verdict": { "type": ["string", "null"], "description": "The verdict as the entry writes it, or null when it names none." }
+      }
+    },
     "trust": {
       "description": "Added in contract 1 by #2547. Where provenance was judged from: the policy read at the base revision, never the tree read.",
       "type": "object",
@@ -143,7 +319,9 @@
             "record-schema-invalid",
             "record-id-duplicate",
             "record-supersedes-unknown",
-            "record-supersedes-conflict"
+            "record-supersedes-conflict",
+            "session-seal-mismatch",
+            "session-verdict-unknown-record"
           ]
         },
         "message": { "type": "string" }

package/src/workspace/records.test.ts

@@ -93,6 +93,49 @@ describe("readRecords", () => {
     expect(r.data).not.toBeNull();
   });
 
+  describe("a dissent needs a reason (#2652)", () => {
+    const withReviews = (reviews: string) => decision("ws-001").replace(/^reviews: \[\]$/m, `reviews:\n${reviews}`);
+    const review = (verdict: string, extra = "") => `  - reviewer: "ana"\n    verdict: "${verdict}"\n    on: "2026-09-24"\n${extra}`;
+
+    for (const [label, note] of [
+      ["null", "    note: null\n"],
+      ["empty", '    note: ""\n'],
+      ["blank", '    note: "  "\n'],
+      ["missing", ""],
+    ] as const) {
+      test(`a dissent with a ${label} note is record-schema-invalid, naming the reviewer`, async () => {
+        write("ws-001-a.md", withReviews(review("dissent", note)));
+        const [r] = (await read()).records;
+        expect(r.valid).toBe(false);
+        expect(codes(r)).toEqual(["record-schema-invalid"]);
+        expect(r.reasons[0].message).toBe("/reviews/0 A dissent needs a reason: the dissent by ana has no note.");
+      });
+    }
+
+    test("a dissent with a note is valid, and so are agree and abstain without one", async () => {
+      write(
+        "ws-001-a.md",
+        withReviews(
+          review("dissent", '    note: "the seal should cover the lockfile too"\n') +
+            review("agree") +
+            review("abstain", "    note: null\n"),
+        ),
+      );
+      const [r] = (await read()).records;
+      expect(r.reasons).toEqual([]);
+      expect(r.valid).toBe(true);
+    });
+
+    test("a dissent carries its concern's lifecycle; another verdict cannot", async () => {
+      write("ws-001-a.md", withReviews(review("dissent", '    note: "why"\n    addressed_by: "INTENTIUS/chant#2652"\n    withdrawn_on: "2026-09-25"\n')));
+      expect((await read()).records[0].valid).toBe(true);
+      write("ws-001-a.md", withReviews(review("agree", '    addressed_by: "ws-002"\n')));
+      const [r] = (await read()).records;
+      expect(codes(r)).toEqual(["record-schema-invalid"]);
+      expect(r.reasons[0].message).toBe("/reviews/0 Only a dissent is a concern: the agree by ana cannot carry addressed_by or withdrawn_on.");
+    });
+  });
+
   test("a supersedes link to a missing id is record-supersedes-unknown", async () => {
     write("ws-002-b.md", decision("ws-002", "decided", ["ws-404"]));
     const [r] = (await read()).records;
@@ -199,6 +242,56 @@ describe("readRecords", () => {
   });
 });
 
+/**
+ * A decision made in the workspace (#2654): the workspace source form with no
+ * issue, and no evidence. `constrains` replaces ws-003's.
+ */
+function workspaceDecision(id: string, constrains: string[] = ["member:app"]): string {
+  const list = constrains.length === 0 ? "constrains: []\n" : `constrains:\n${constrains.map((c) => `  - "${c}"\n`).join("")}`;
+  return decision(id)
+    .replace(/^source:\n(?:  .*\n)*/m, 'source:\n  kind: "workspace"\n  member: "app"\n')
+    .replace(/^evidence:\n(?:  .*\n)*/m, "evidence: []\n")
+    .replace(/^constrains:\n(?:  .*\n)*/m, list);
+}
+
+describe("a decision that originates in the workspace (#2654)", () => {
+  test("validates with no issue and no evidence, is current, and carries record-no-evidence", async () => {
+    write("ws-001-a.md", workspaceDecision("ws-001"));
+    const current = await read({ current: true });
+    expect(current.records.map((r) => [r.id, r.valid, r.reasons, r.warnings.map((w) => w.code)])).toEqual([
+      ["ws-001", true, [], ["record-no-evidence"]],
+    ]);
+    expect(current.records[0].data?.source).toEqual({ kind: "workspace", member: "app" });
+  });
+
+  test("takes a session and an issue, and nothing else", async () => {
+    const base = workspaceDecision("ws-001");
+    write("ws-001-a.md", base.replace('  member: "app"\n', '  member: "app"\n  session: "S-0001"\n  issue: "jhgaylor/chud#77"\n'));
+    write("ws-002-b.md", base.replace('id: "ws-001"', 'id: "ws-002"').replace('  member: "app"\n', '  member: "app"\n  session: null\n'));
+    write("ws-003-c.md", base.replace('id: "ws-001"', 'id: "ws-003"').replace('  member: "app"\n', '  member: "app"\n  row: "Sort order"\n'));
+    write("ws-004-d.md", base.replace('id: "ws-001"', 'id: "ws-004"').replace('  member: "app"\n', ""));
+    const records = (await read()).records;
+    expect(records.map((r) => [r.id, codes(r)])).toEqual([
+      ["ws-001", []],
+      ["ws-002", []],
+      ["ws-003", ["record-schema-invalid"]],
+      ["ws-004", ["record-schema-invalid"]],
+    ]);
+  });
+
+  test("a record with evidence carries no record-no-evidence warning", async () => {
+    write("ws-001-a.md", decision("ws-001"));
+    expect((await read()).records[0].warnings).toEqual([]);
+  });
+
+  test("a record that constrains nothing is refused", async () => {
+    write("ws-001-a.md", workspaceDecision("ws-001", []));
+    const [r] = (await read()).records;
+    expect(codes(r)).toEqual(["record-schema-invalid"]);
+    expect(r.reasons[0].message).toMatch(/constrains/);
+  });
+});
+
 describe("loadRecordKind", () => {
   const load = () => loadRecordKind(join(dir, "decisions", "decision.kind.mjs"));