@intentius/chant 0.124.12 → 0.124.14

package/dist/workspace/records-close.js

@@ -0,0 +1,116 @@
+/**
+ * `chant workspace records close <session id>` (#2693): close a review
+ * session in one write. It sets the session's state to its kind's closed
+ * state, the time it closed and the commit it closed at (the fields the
+ * kind's `session` block names in `closedOn` and `closedRev`), and then the
+ * seal by chant's whole-file rule ({@link sessionSeal}, #2546), so a UI never
+ * computes a seal.
+ *
+ * Like `new`, `amend` and `review`, it reads the records again with the file
+ * in place and writes only when the session comes back valid: a verdict
+ * naming a record the subjects lack is refused with
+ * `session-verdict-unknown-record`. A session already closed is
+ * `record-closed`. It writes one file or none and never commits. Like them
+ * it holds the working tree's write lock, and takes `--expect <digest>`
+ * (#3173).
+ */
+import { sessionSeal } from "./record-sessions.js";
+import { RECORD_REASON_CODES } from "./records.js";
+import { abs, failure, findRecord, LOAD_ERROR_CODES, open, openedRevFill, readAll, RECORDS_WRITE_CONTRACT_VERSION, RecordWriteError, refuseOutOfScope, refuseStale, replaceFields, stableJson, validatedEntry, writeWho, } from "./records-write.js";
+import { noteWrites, withWriteLock, writeFileAtomic, WRITE_LOCK_CODES } from "./write-lock.js";
+import { headCommit } from "./session-kinds.js";
+import { WRITE_SCOPE_CODES } from "./write-scope.js";
+export const RECORDS_CLOSE_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace/records-close/v1/records-close.schema.json";
+/** Why `records close` wrote nothing. Closed. */
+export const CLOSE_ERROR_CODES = [
+    ...LOAD_ERROR_CODES,
+    "write-usage-invalid",
+    "record-not-found",
+    "record-closed",
+    "record-conflict",
+    ...WRITE_LOCK_CODES,
+    ...WRITE_SCOPE_CODES,
+    ...RECORD_REASON_CODES,
+];
+/** An ISO 8601 time in UTC to the second, as the reference session schema's dateTime takes it. */
+function isoSeconds(d) {
+    return d.toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+/** `records close`: close one open session and seal it, holding the write lock (#3173). */
+export async function closeRecord(opts) {
+    try {
+        if (opts.expect !== undefined && !/^[0-9a-f]{64}$/.test(opts.expect)) {
+            throw new RecordWriteError("write-usage-invalid", `--expect takes a record's digest, 64 lowercase hex digits as records --json prints it, not ${JSON.stringify(opts.expect)}`);
+        }
+        return await withWriteLock(opts.cwd, writeWho("records close", opts), opts.dryRun, () => closeRecordLocked(opts));
+    }
+    catch (err) {
+        return failure(RECORDS_CLOSE_SCHEMA_ID, err);
+    }
+}
+async function closeRecordLocked(opts) {
+    try {
+        const o = await open(opts.kind, opts.cwd);
+        refuseOutOfScope(o, "close", opts.cwd, opts);
+        const { kind } = o.loaded;
+        const decl = kind.session;
+        if (!decl || kind.stateField === undefined) {
+            throw new RecordWriteError("write-usage-invalid", `the ${kind.name} kind has no session block, and records close closes a review session; amend sets the state of other records`);
+        }
+        const closedState = (kind.closedStates ?? [])[0];
+        if (closedState === undefined)
+            throw new RecordWriteError("write-usage-invalid", `the ${kind.name} kind lists no closed state, so a session of it can't close`);
+        const before = await readAll(o, o.source);
+        const target = findRecord(before, opts.id, kind.name);
+        refuseStale(o, target, opts.id, opts.expect);
+        if (target.state !== null && (kind.closedStates ?? []).includes(target.state)) {
+            throw new RecordWriteError("record-closed", `${opts.id} is already ${target.state}, and a closed session is sealed and stays as it is`);
+        }
+        if (target.data === null)
+            throw new RecordWriteError("record-unparseable", `${target.path} can't be read, so it can't be closed`);
+        const old = target.data;
+        const closedRev = headCommit(o.root);
+        const set = {
+            ...openedRevFill(kind, old, o.root),
+            [kind.stateField]: closedState,
+            ...(decl.closedOn ? { [decl.closedOn]: isoSeconds(opts.now ?? new Date()) } : {}),
+            ...(decl.closedRev ? { [decl.closedRev]: closedRev } : {}),
+        };
+        // The seal is written last, into text that already holds everything else: the whole-file seal of the session without its seal field (#2546).
+        const merged = { ...old, ...set };
+        delete merged[decl.seal];
+        const unsealed = replaceFields(o.source.read(target.path), set, merged);
+        if (unsealed === undefined)
+            throw new RecordWriteError("record-unparseable", `${target.path}: its fields can't be rewritten in place without changing the rest of the file`);
+        const digest = sessionSeal(unsealed, decl.seal, kind.format);
+        if (digest === null)
+            throw new RecordWriteError("record-unparseable", `${target.path} can't be read, so it can't be sealed`);
+        const text = replaceFields(unsealed, { [decl.seal]: digest }, { ...merged, [decl.seal]: digest });
+        if (text === undefined || sessionSeal(text, decl.seal, kind.format) !== digest) {
+            throw new RecordWriteError("record-unparseable", `${target.path}: the ${decl.seal} line can't be added without changing the text it seals`);
+        }
+        const entry = await validatedEntry(o, before, target.path, text);
+        if (!opts.dryRun) {
+            writeFileAtomic(abs(o, target.path), text);
+            noteWrites(o.root, [{ path: target.path, text }], writeWho("records close", opts));
+        }
+        const written = { ...merged, [decl.seal]: digest };
+        return {
+            $schema: RECORDS_CLOSE_SCHEMA_ID,
+            contract: RECORDS_WRITE_CONTRACT_VERSION,
+            kind: o.view,
+            path: target.path,
+            id: opts.id,
+            changed: Object.keys(written).filter((k) => stableJson(old[k]) !== stableJson(written[k])),
+            seal: { field: decl.seal, digest },
+            closedRev,
+            dryRun: !!opts.dryRun,
+            warnings: entry.warnings,
+            digest: entry.digest,
+            ...(opts.dryRun ? { text } : {}),
+        };
+    }
+    catch (err) {
+        return failure(RECORDS_CLOSE_SCHEMA_ID, err);
+    }
+}

package/dist/workspace/records-close.schema.json

@@ -0,0 +1,278 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/chant/schemas/workspace/records-close/v1/records-close.schema.json",
+  "title": "chant workspace records close output",
+  "description": "What `chant workspace records close <session id> [--kind <session kind file>]` prints (#2693): the session's path and id, the fields the close set (the state, and the close time and closing revision when the session kind names fields for them), the seal written and the commit the session closed at, 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.88.0 and newer; an older chant refuses the close verb.",
+  "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",
+        "changed",
+        "seal",
+        "closedRev",
+        "dryRun",
+        "warnings"
+      ],
+      "properties": {
+        "$schema": {
+          "const": "https://intentius.io/chant/schemas/workspace/records-close/v1/records-close.schema.json"
+        },
+        "contract": {
+          "const": 1
+        },
+        "kind": {
+          "type": "object",
+          "required": [
+            "name",
+            "schema",
+            "file"
+          ],
+          "properties": {
+            "name": {
+              "type": "string",
+              "description": "The kind's name, such as \"session\"."
+            },
+            "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."
+        },
+        "changed": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "The top-level fields whose value differs from the session as it was: its state, the close time, the closing revision and the seal, and the opening revision when it was null and the repository now has a commit."
+        },
+        "seal": {
+          "type": "object",
+          "required": [
+            "field",
+            "digest"
+          ],
+          "properties": {
+            "field": {
+              "type": "string",
+              "description": "The seal field, as the session kind's session.seal names it, such as closed_digest."
+            },
+            "digest": {
+              "type": "string",
+              "pattern": "^sha256:[0-9a-f]{64}$",
+              "description": "The seal written: sha256: and the lowercase hex SHA-256 of the JCS form of the whole session without its seal field (its front matter as core and the text below it as body, line endings LF), which records checks on every read (session-seal-mismatch). Before #2546 it was the bare hex SHA-256 of the file's text without the seal line."
+            }
+          }
+        },
+        "closedRev": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "pattern": "^[0-9a-f]{40,64}$",
+          "description": "The full commit id HEAD named at the close, or null outside git or before the first commit. It is written to the field session.closedRev names, when the kind names one. The caller commits the close, so the commit that carries it comes after this one."
+        },
+        "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"
+          }
+        },
+        "digest": {
+          "type": "string",
+          "pattern": "^[0-9a-f]{64}$",
+          "description": "Added in contract 1 by #3173. The record's digest after the write, as chant workspace records --json reports it (with --dry-run, the digest it would have). Pass it as --expect to the next amend, review or close of the record, so that write is refused with record-conflict if someone else wrote the record in between."
+        },
+        "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",
+            "source-transcript-drift"
+          ]
+        },
+        "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-close/v1/records-close.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",
+                "record-closed",
+                "record-conflict",
+                "write-lock-timeout",
+                "write-lock-not-held",
+                "write-scope-member",
+                "write-scope-kind",
+                "write-scope-class-unknown",
+                "agent-unknown",
+                "record-unparseable",
+                "record-schema-invalid",
+                "record-id-duplicate",
+                "record-supersedes-unknown",
+                "record-supersedes-conflict",
+                "record-remediates-unknown",
+                "record-remediates-not-closed",
+                "record-seal-mismatch",
+                "session-seal-mismatch",
+                "session-verdict-unknown-record"
+              ]
+            },
+            "message": {
+              "type": "string",
+              "description": "What was wrong, and what to do instead when there is something. A session already closed is record-closed; a verdict naming a record the session kind's subjects lack is session-verdict-unknown-record."
+            }
+          }
+        },
+        "conflict": {
+          "type": "object",
+          "description": "Added in contract 1 by #3173. With record-conflict only: the record as it is now. Re-read it, and write again with --expect set to digest if the change still stands.",
+          "required": [
+            "id",
+            "path",
+            "expected",
+            "digest",
+            "lastWrite"
+          ],
+          "properties": {
+            "id": {
+              "type": "string"
+            },
+            "path": {
+              "type": "string",
+              "description": "The record file, from the repository root."
+            },
+            "expected": {
+              "type": "string",
+              "description": "The digest given with --expect."
+            },
+            "digest": {
+              "type": "string",
+              "pattern": "^[0-9a-f]{64}$",
+              "description": "The record's digest now."
+            },
+            "lastWrite": {
+              "description": "The last chant write of the record file, from the write journal in the git directory, while the file still holds the text it left; null when the journal does not know it.",
+              "oneOf": [
+                {
+                  "type": "null"
+                },
+                {
+                  "type": "object",
+                  "required": [
+                    "verb",
+                    "by",
+                    "agent",
+                    "at"
+                  ],
+                  "properties": {
+                    "verb": {
+                      "type": "string",
+                      "description": "The write command, such as records amend or points answer."
+                    },
+                    "by": {
+                      "type": [
+                        "string",
+                        "null"
+                      ],
+                      "description": "The principal the write named, or null when it named none."
+                    },
+                    "agent": {
+                      "type": [
+                        "string",
+                        "null"
+                      ],
+                      "description": "The agent session it was made in (CHANT_AGENT), or null."
+                    },
+                    "at": {
+                      "type": "string",
+                      "description": "When, as an ISO 8601 time."
+                    }
+                  }
+                }
+              ]
+            }
+          }
+        },
+        "path": false
+      }
+    }
+  }
+}

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

@@ -0,0 +1,202 @@
+{
+  "$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."
+        },
+        "seal": {
+          "type": "object",
+          "description": "Added in contract 1 by #2688. With --sign only: the author seal written into the record's top-level seal field, an ssh signature by the key given (or git's user.signingkey) over <id>\\n<digest>\\n<author>\\n<state>, in the ssh-keygen namespace chant-record. The author is the kind's reviews.decider field (decided_by for decisions), and the digest is the record's digest by the digest rule, which leaves the seal field out. The write does not check the key against the signers file; chant workspace records reports whether the seal verifies.",
+          "required": [
+            "signer",
+            "key",
+            "signature"
+          ],
+          "properties": {
+            "signer": {
+              "type": "string",
+              "description": "The record's author, as its reviews.decider field names them."
+            },
+            "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"
+          }
+        },
+        "digest": {
+          "type": "string",
+          "pattern": "^[0-9a-f]{64}$",
+          "description": "Added in contract 1 by #3173. The record's digest after the write, as chant workspace records --json reports it (with --dry-run, the digest it would have). Pass it as --expect to the next amend, review or close of the record, so that write is refused with record-conflict if someone else wrote the record in between."
+        },
+        "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",
+            "source-transcript-drift"
+          ]
+        },
+        "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-sign-failed",
+                "source-harvest-not-proposed",
+                "record-state-not-initial",
+                "ratify-quorum-not-met",
+                "write-lock-timeout",
+                "write-lock-not-held",
+                "write-scope-member",
+                "write-scope-kind",
+                "write-scope-class-unknown",
+                "agent-unknown",
+                "principal-unidentified",
+                "record-unparseable",
+                "record-schema-invalid",
+                "record-id-duplicate",
+                "record-supersedes-unknown",
+                "record-supersedes-conflict",
+                "record-remediates-unknown",
+                "record-remediates-not-closed",
+                "record-seal-mismatch",
+                "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
+      }
+    }
+  }
+}