@intentius/chant 0.100.0 → 0.102.0

package/src/workspace/records.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$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`.",
+  "description": "What `chant workspace records --json` prints, version 1 of the read contract for records (#2536). A closed record of a kind that declares seal carries a whole-file seal, checked on every read (#2546). 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" }, { "$ref": "#/$defs/set" }],
   "$defs": {
     "decidedIn": {
@@ -47,6 +47,43 @@
             ]
           }
         },
+        "spec": {
+          "description": "Added in contract 1 by #2546 (#2524 D20). With --current only: the workspace's spec, the current records of each declared kind marked spec: true, each with the workspace files it pins. A kind whose read failed is left out, and is listed under kinds with its error.",
+          "type": "object",
+          "required": ["kinds", "records"],
+          "properties": {
+            "kinds": {
+              "type": "array",
+              "description": "The spec kinds, as the declaration names them, in its order.",
+              "items": {
+                "type": "object",
+                "required": ["member", "path", "name"],
+                "properties": {
+                  "member": { "type": ["string", "null"] },
+                  "path": { "type": "string" },
+                  "name": { "type": ["string", "null"] }
+                }
+              }
+            },
+            "records": {
+              "type": "array",
+              "description": "Every current record of the spec kinds, in the order of kinds and then path. Invalid records are listed with valid false, as under kinds.",
+              "items": {
+                "type": "object",
+                "required": ["kind", "id", "path", "state", "valid", "digest", "assets"],
+                "properties": {
+                  "kind": { "type": "string", "description": "The kind's name, such as decision." },
+                  "id": { "type": ["string", "null"] },
+                  "path": { "type": "string" },
+                  "state": { "type": ["string", "null"] },
+                  "valid": { "type": "boolean" },
+                  "digest": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
+                  "assets": { "type": "array", "items": { "$ref": "#/$defs/asset" } }
+                }
+              }
+            }
+          }
+        },
         "kind": false,
         "records": false,
         "error": false
@@ -69,6 +106,10 @@
             "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)."
+            },
+            "spec": {
+              "type": "boolean",
+              "description": "Added in contract 1 by #2546. true when the kind file marks the kind spec: true, so its current records and the files they pin are part of the workspace's spec (#2524 D20)."
             }
           }
         },
@@ -83,6 +124,14 @@
         },
         "error": false,
         "current": { "type": "boolean", "description": "Whether superseded records were left out (--current)." },
+        "uncommitted": {
+          "type": "boolean",
+          "description": "Added in contract 1 by #3160. Whether only the records HEAD doesn't hold were listed (--uncommitted): each record's worktree is then modified or new, checkout is present, and summary's total, valid and invalid count the records listed. Absent from documents written before #3160, which read as false."
+        },
+        "checkout": {
+          "description": "Added in contract 1 by #3160, on a read of the working tree in a git repository; absent under --at and outside git. The branch, head and base the working tree is on, and the records of the kind it has deleted.",
+          "$ref": "#/$defs/checkout"
+        },
         "trust": { "$ref": "#/$defs/trust" },
         "records": {
           "description": "One entry per file the kind locates, sorted by path.",
@@ -104,6 +153,42 @@
           "type": "array",
           "items": { "$ref": "#/$defs/decisionWork" }
         }
+      },
+      "allOf": [
+        {
+          "if": { "properties": { "uncommitted": { "const": true } }, "required": ["uncommitted"] },
+          "then": {
+            "required": ["checkout"],
+            "properties": {
+              "checkout": true,
+              "at": { "type": "null" },
+              "records": { "type": "array", "items": { "type": "object", "required": ["worktree"], "properties": { "worktree": { "enum": ["modified", "new"] } } } }
+            }
+          }
+        }
+      ]
+    },
+    "checkout": {
+      "type": "object",
+      "required": ["branch", "head", "base", "baseFrom", "deleted"],
+      "properties": {
+        "branch": { "type": ["string", "null"], "description": "The checked-out branch's short name, such as chant/work/w-12, or null when HEAD is detached." },
+        "head": {
+          "type": ["string", "null"],
+          "pattern": "^[0-9a-f]{40,64}$",
+          "description": "The full commit id HEAD names, or null before the first commit (every record is then new). Each record's worktree is judged against it."
+        },
+        "base": {
+          "type": ["string", "null"],
+          "pattern": "^[0-9a-f]{40,64}$",
+          "description": "The merge base of head and the target branch tip, the commit the branch forked from: what applying the branch would be measured against. The target is --base when given, else origin/HEAD, main or master, as for trust. Null without a head, a target, or common history."
+        },
+        "baseFrom": { "enum": ["flag", "origin/HEAD", "main", "master", null], "description": "Where the target branch was found; null when there is none." },
+        "deleted": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Record files of the kind that head holds and the working tree no longer has, staged or not, from the repository root with / separators, sorted. A renamed record is here under its old name and in records as new."
+        }
       }
     },
     "workLink": {
@@ -114,6 +199,17 @@
         "state": { "type": ["string", "null"], "description": "The linked record's state as it writes it, or null when no record has the id." }
       }
     },
+    "workAnswer": {
+      "type": "object",
+      "required": ["id", "point", "state", "answer", "answeredBy"],
+      "properties": {
+        "id": { "type": "string", "description": "The answer record's id: the point's name and the first 12 hex digits of its inputs hash." },
+        "point": { "type": ["string", "null"], "description": "The decision point it answers." },
+        "state": { "type": ["string", "null"], "description": "escalated, proposed or answered." },
+        "answer": { "oneOf": [{ "type": "string" }, { "type": "boolean" }, { "type": "null" }], "description": "The answer, or null while there is none." },
+        "answeredBy": { "type": "array", "items": { "type": "string" }, "description": "The people who answered or confirmed it; empty when a table or a model answered." }
+      }
+    },
     "decisionWork": {
       "type": "object",
       "required": ["id", "path", "state", "supersededBy", "implementedBy"],
@@ -158,12 +254,12 @@
           "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, (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, or (added by #2688) a record whose author seal is not attested under a signers file at base, or (added by #2772) a work record's acceptance criteria unmet when it is done, or met by a manual verdict from its implementer. 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.",
+          "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, or (added by #2688) a record whose author seal is not attested under a signers file at base, or (added by #2772) a work record's acceptance criteria unmet when it is done, or met by a manual verdict from its implementer, or (added by #3147) a work record's contract that no record has or nobody approved, or a builder tier its kind does not list. 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 and its top-level seal block (#2688) in the front matter, or for a kind of format json without the top-level reviews and seal members, each with one comma beside it (#2664). A record with no seal hashes as it did before #2688. A review verdict names it in its digest field, and stops counting once the record's digest moves on; a record's author seal signs it. For a kind with no reviews list, the digest of the whole text.",
+          "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 and its top-level seal block (#2688) in the front matter, or for a kind of format json without the top-level reviews and seal members, each with one comma beside it (#2664). A record with no seal hashes as it did before #2688. A review verdict names it in its digest field, and stops counting once the record's digest moves on; a record's author seal signs it. A kind that declares seal (#2546) also leaves out the field holding the whole-file seal, and a kind with reviews.ratified its state line (#2873). For a kind with no reviews list, the digest of the whole text. It is not the record's seal: the seal covers the whole file (#2546, ws-063).",
           "type": "string",
           "pattern": "^[0-9a-f]{64}$"
         },
@@ -202,6 +298,19 @@
           "description": "Added in contract 1 by #2772, on every parsed record of a work kind whose work block names acceptance criteria. How many of the record's criteria passing evidence meets: evidence naming the criterion, with result pass and the criterion's verification, and for a manual criterion a by other than the implementer. Null when the record lists no criteria, so a record without them reads as before.",
           "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/workAcceptance" }]
         },
+        "worktree": {
+          "enum": ["committed", "modified", "new"],
+          "description": "Added in contract 1 by #3160, on every record of a read of the working tree in a git repository; absent under --at and outside git. committed when the file is as HEAD holds it, modified when it differs from HEAD, new when HEAD doesn't hold it, staged or not. modified and new are the records a person has kept and not yet committed or applied."
+        },
+        "contract": {
+          "description": "Added in contract 1 by #3147, on every parsed record of a work kind whose work block names a contract kind. The contract record the item builds, by the id in the work block's contract field, with that record's state now; state is null when no record of the contract kind has the id. Null when the item names no contract.",
+          "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/workLink" }]
+        },
+        "answers": {
+          "description": "Added in contract 1 by #3147, on every record with an id of a work kind whose work block names an answer kind. The decision-point answers about the item: each answer record whose constrains names the item's id, in path order, joined by id and never copied onto the item. Read at the same revision; in the working tree, with the answers a steward keeps on the lifecycle ledger laid over it. Absent when the answer kind can't be read.",
+          "type": "array",
+          "items": { "$ref": "#/$defs/workAnswer" }
+        },
         "lease": {
           "description": "Added in contract 1 by #2732, on every record of a work kind with an id, read in the working tree (absent under --at). The item's active work lease (chant workspace work claim), or null when nobody holds one live. Read from the local lease refs, refs/chant/lease/[_members/<member>/]work/<id> and the remote's as last fetched, of the ledger owning the work kind file; records never fetches.",
           "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/workLease" }]
@@ -278,6 +387,9 @@
             "work-done-gap-open",
             "work-acceptance-unmet",
             "work-acceptance-self-verified",
+            "work-contract-unknown",
+            "work-contract-undecided",
+            "work-tier-unknown",
             "answer-points-unreadable",
             "answer-point-unknown",
             "answer-point-changed",
@@ -405,7 +517,17 @@
         "attestor": { "type": "string", "description": "The attestor that answered, such as ssh-commit." },
         "principal": { "type": "string", "description": "The signer, when attested." },
         "key": { "type": "string", "description": "The signing key's fingerprint, when known." },
-        "reason": { "type": "string" }
+        "reason": { "type": "string" },
+        "returned": {
+          "description": "Added in contract 1 by #2552. Set when the record's bytes came back in a return that carries the commit they were made in: level, principal and key then judge that commit, with the signers at base plus those admitted for the return, and commit is the commit here that holds the bytes. A signer neither lists reads as attested-unverifiable-here until an admin admits it.",
+          "type": "object",
+          "required": ["id", "importedIn"],
+          "properties": {
+            "id": { "type": "string", "pattern": "^ret-[0-9a-f]{12}$", "description": "The return, .chant/returns/<id>.json at the workspace root." },
+            "commit": { "type": "string", "pattern": "^[0-9a-f]{40,64}$", "description": "The commit in the returned copy that last changed the file." },
+            "importedIn": { "type": ["string", "null"], "pattern": "^[0-9a-f]{40,64}$", "description": "The commit here that holds the returned bytes." }
+          }
+        }
       }
     },
     "reason": {
@@ -421,6 +543,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.ts

@@ -13,15 +13,18 @@
  *
  * A record that fails any of that is still returned, with reason codes, and the
  * read succeeds. Only a failure to read the kind, its schema or the revision is
- * an error. Seals, attestation and the workspace declaration come later (#2546,
- * #2534); nothing here needs a `chant.workspace.json`.
+ * an error. A closed record of a kind that declares `seal` is checked against
+ * its whole-file seal ({@link recordSeal}, #2546); author and verdict seals
+ * are checked by `records-cli.ts` against the policy at base. Nothing here
+ * needs a `chant.workspace.json`.
  *
  * Everything under `workspace/` loads only when a `chant workspace` command
  * runs. The level-0 goldens (#2526) fail if a level-0 command loads it.
  */
 
 import { createHash } from "node:crypto";
-import { sha256Hex } from "../content-digest";
+import { contentDigest, sha256Hex } from "../content-digest";
+import { canonicalJson } from "../effect-receipt";
 import { readFileSync, statSync } from "node:fs";
 import { dirname, posix, relative, resolve, sep } from "node:path";
 import yaml from "js-yaml";
@@ -57,6 +60,8 @@ export const RECORD_REASON_CODES = [
   "record-remediates-unknown",
   /** A `remediates` link names a record that isn't closed: a record still open is amended instead (#2774). */
   "record-remediates-not-closed",
+  /** A closed record's seal is not the whole-file seal of its text now: it changed after it closed (#2546, ws-063). */
+  "record-seal-mismatch",
   /** A closed session's seal is not the digest of its text: it changed after it closed (#2673). */
   "session-seal-mismatch",
   /** A session's verdict names a record the kind's subject records do not have (#2673). */
@@ -171,13 +176,21 @@ export const RECORD_SEAL_FIELD = "seal";
  * moving a record to that state keeps the verdicts that ratified it
  * counting.
  */
-export function digestFields(kind: Pick<RecordKind, "reviews" | "stateField">): string[] | null {
+export function digestFields(kind: Pick<RecordKind, "reviews" | "stateField" | "seal">): string[] | null {
   if (!kind.reviews) return null;
   const fields = [kind.reviews.field, RECORD_SEAL_FIELD];
   if (kind.reviews.ratified !== undefined && kind.stateField !== undefined) fields.push(kind.stateField);
+  // The whole-file seal is written when the record closes (#2546, ws-063), so
+  // the verdicts that ratified it keep counting on the sealed record.
+  if (kind.seal !== undefined) fields.push(kind.seal.field);
   return fields;
 }
 
+/** The field holding a closed record's whole-file seal: the kind's `seal.field`, or a session kind's `session.seal` (#2546, #2673). */
+export function sealFieldOf(kind: Pick<RecordKind, "seal" | "session">): string | undefined {
+  return kind.seal?.field ?? kind.session?.seal;
+}
+
 /** What a verdict's seal establishes (#2687). See `trust/seal.ts`. */
 export interface VerdictAttestation {
   /** Why the verdict is not attested. Absent when its seal verified. */
@@ -406,6 +419,23 @@ export const recordKindSchema = z
      * done record with a criterion that no passing evidence meets is warned
      * `work-acceptance-unmet`, which `check` fails on (WSP117). Optional, and
      * a record without the list is read as before.
+     *
+     * #3147 adds four, each optional:
+     *
+     * - `contract`: the front-matter field naming the contract record the
+     *   item builds, and the kind file of those records (relative to this
+     *   kind file). Each record gets `contract` with that record's state,
+     *   warned `work-contract-unknown` or `work-contract-undecided`.
+     * - `tier`: the field holding the item's builder tier, and the tiers the
+     *   workspace allows, declared once here. A tier outside them is warned
+     *   `work-tier-unknown`.
+     * - `attempts`: the field holding an item's own attempt limit, and the
+     *   default `max` for items without one. `work history` counts attempts
+     *   against it.
+     * - `answers`: the answer kind file (relative to this kind file) whose
+     *   records answer decision points about an item. Each record gets
+     *   `answers`, the answers whose `constrains` names its id, joined by id
+     *   rather than copied onto the item.
      */
     work: z
       .object({
@@ -416,6 +446,14 @@ export const recordKindSchema = z
         done: z.string().min(1),
         closedOn: z.string().min(1),
         acceptance: z.object({ field: z.string().min(1), implementer: z.string().min(1) }).strict().optional(),
+        contract: z.object({ field: z.string().min(1), kind: z.string().min(1) }).strict().optional(),
+        tier: z
+          .object({ field: z.string().min(1), tiers: z.array(z.string().min(1)).min(1) })
+          .strict()
+          .refine((t) => new Set(t.tiers).size === t.tiers.length, { message: "work.tier.tiers lists each tier once", path: ["tiers"] })
+          .optional(),
+        attempts: z.object({ field: z.string().min(1), max: z.number().int().min(1) }).strict().optional(),
+        answers: z.string().min(1).optional(),
       })
       .strict()
       .optional(),
@@ -430,8 +468,32 @@ export const recordKindSchema = z
      * Optional.
      */
     answers: z.object({ points: z.string().min(1) }).strict().optional(),
+    /**
+     * The top-level field that holds a closed record's seal (#2546, ws-003,
+     * ws-063): {@link recordSeal}, the whole-file JCS/SHA-256 of the record
+     * without that field. `records amend` and `records new` write it when a
+     * record enters one of `closedStates`, and `records` reports a closed
+     * record whose seal does not match as `record-seal-mismatch`. Requires
+     * states. A session kind's `session.seal` names the same field for a
+     * session, and when both are given they must agree. Optional.
+     */
+    seal: z.object({ field: z.string().min(1) }).strict().optional(),
+    /**
+     * The kind's current records, with the files they pin, are part of the
+     * workspace's spec (#2524 D20): `chant workspace records --current
+     * --json` lists them under `spec`. Optional, and false when left out.
+     */
+    spec: z.boolean().optional(),
   })
   .strict()
+  .refine((k) => k.states !== undefined || k.seal === undefined, {
+    message: "a kind without states cannot have seal: a record is sealed when it enters a closed state",
+    path: ["seal"],
+  })
+  .refine((k) => k.seal === undefined || k.session === undefined || k.seal.field === k.session.seal, {
+    message: "seal.field and session.seal name the field that holds a closed session's seal, and must be the same",
+    path: ["seal"],
+  })
   .refine((k) => (k.idField === undefined) !== (k.idFrom === undefined), {
     message: "a kind names its id with exactly one of idField and idFrom",
     path: ["idField"],
@@ -748,7 +810,9 @@ function nonJson(v: unknown, at: string, seen: Set<object>): string | undefined
  * record's author seal (#2688; {@link digestFields}), so sealing a record
  * leaves its digest where it was too. A record with no `seal` hashes exactly
  * as it did before author seals existed. A kind with `reviews.ratified` adds
- * its state field (#2873).
+ * its state field (#2873), and a kind with `seal` its seal field (#2546), so
+ * the whole-file seal written at the close moves no digest. The digest is not
+ * that seal: {@link recordSeal} covers the whole record.
  *
  * The rule, which a hand-editor can follow with a text editor and
  * `sha256sum`:
@@ -776,6 +840,50 @@ export function recordTextDigest(text: string, field: string | readonly string[]
   return createHash("sha256").update(kept, "utf8").digest("hex");
 }
 
+// ── Record seal ──────────────────────────────────────────────────────────────
+
+/**
+ * The seal of a closed record (#2546, ws-003, ws-063): `sha256:` and the
+ * lowercase hex SHA-256 of the RFC 8785 (JCS) form of the whole record, with
+ * only the field that holds the seal left out. It is a separate hash from
+ * {@link recordTextDigest}, which a review verdict names: the digest leaves
+ * out the reviews, the author seal and the state so verdicts keep counting,
+ * and the seal covers all of them.
+ *
+ * 1. Line endings become LF (CRLF and a lone CR each become one LF).
+ * 2. The structured core is parsed as the kind's format says: the front
+ *    matter, as the JSON subset of YAML, or the whole JSON object. The
+ *    top-level member `field` is removed from it.
+ * 3. For a Markdown record the value hashed is the object
+ *    `{"body": <the text after the closing --- line>, "core": <the core>}`;
+ *    for a JSON record it is the core itself.
+ * 4. That value is written in JCS (keys sorted by UTF-16 code units, no
+ *    whitespace, ECMAScript number and string forms) and hashed as UTF-8.
+ *
+ * So every value in the record and every byte of its body is sealed, the
+ * reviews, the author seal and the state included, while the key order,
+ * quoting and indentation of the front matter are not: the same record
+ * written another way has the same seal. A YAML comment in the front matter
+ * is not part of the record, so it is not sealed either (#3066). Returns null when
+ * the core can't be parsed.
+ */
+export function recordSeal(text: string, field: string, format: RecordFormat = "markdown-front-matter"): string | null {
+  const lf = text.replace(/\r\n?/g, "\n");
+  const parsed = parseRecord(format, lf);
+  if (!parsed.ok) return null;
+  const core = { ...parsed.value };
+  delete core[field];
+  const sealed = format === "json" ? core : { body: bodyText(lf), core };
+  return contentDigest(canonicalJson(sealed));
+}
+
+/** The text below a Markdown file's front matter, with LF line endings: everything after the closing `---` line. */
+export function bodyText(text: string): string {
+  const normalised = text.replace(/\r\n?/g, "\n");
+  const m = normalised.match(/^---\n[\s\S]*?\n---(?:\n|$)/);
+  return m ? normalised.slice(m[0].length) : "";
+}
+
 /**
  * `text` with the top-level member `field` removed from a JSON record, by the
  * rule a hand-editor follows for a JSON record (ws-053). With several fields
@@ -1065,6 +1173,8 @@ export interface RecordEntry {
   implements?: WorkLink[];
   /** For a work kind with acceptance criteria (#2772): how many of the record's criteria passing evidence meets, or null when it lists none. */
   acceptance?: WorkAcceptance | null;
+  /** For a work kind with a contract link (#3147): the contract record the item builds, with its state, or null when it names none. */
+  contract?: WorkLink | null;
 }
 
 export interface ReadRecordsOptions {
@@ -1282,6 +1392,14 @@ export async function readRecords(loaded: LoadedRecordKind, options: ReadRecords
         if (drift) entry.warnings.push({ code: "source-transcript-drift", message: drift });
       }
     }
+    if (kind.seal && !kind.session && entry.state !== null && (kind.closedStates ?? []).includes(entry.state)) {
+      // A closed record's whole-file seal (#2546, ws-063). A session's is checked with its verdicts (#2673).
+      const seal = fm.value[kind.seal.field];
+      const actual = typeof seal === "string" ? recordSeal(text, kind.seal.field, kind.format) : null;
+      if (typeof seal === "string" && actual !== seal) {
+        entry.reasons.push({ code: "record-seal-mismatch", message: `${kind.seal.field} is ${seal}, but the record seals to ${actual}: it changed after it closed` });
+      }
+    }
     if (kind.pins) {
       const cited = fm.value[kind.pins.field];
       if (Array.isArray(cited) && cited.length === 0) {