@intentius/chant 0.85.0 → 0.87.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, a supersedes link that has no effect yet, or (added by #2654) an evidence list that is empty. 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,109 @@
       "type": "object",
       "required": ["code", "message"],
       "properties": {
-        "code": { "enum": ["asset-drift", "asset-missing", "asset-stale", "record-supersedes-pending", "record-no-evidence"] },
+        "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",
+            "work-done-gap-open"
+          ]
+        },
         "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)." },
+        "attested": {
+          "type": ["boolean", "null"],
+          "description": "Added in contract 1 by #2687. true when the verdict's seal verifies for its reviewer against the signers file at base. false when a signers file is active at base and the verdict has no seal, or when a seal fails, with or without one. null when nothing here can say: no seal and no signers file, a seal checked with no signers file (its signature is intact, and nothing says whose key it is), or no ssh-keygen. Under an active signers file only true counts."
+        },
+        "attestation": {
+          "description": "Added in contract 1 by #2687. What the verdict's seal establishes, and why when it is not attested.",
+          "type": "object",
+          "required": ["message"],
+          "properties": {
+            "code": { "enum": ["seal-missing", "seal-signer-unlisted", "seal-signature-invalid", "seal-unverifiable"], "description": "Absent exactly when attested is true." },
+            "message": { "type": "string" },
+            "key": { "type": "string", "description": "The fingerprint of the key that made the signature, when the signature was checked." }
+          }
+        },
+        "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 +334,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" }