@intentius/chant 0.101.0 → 0.104.0

package/src/workspace/reason-codes.test.ts

@@ -14,7 +14,7 @@ import { MEMBER_RUN_REASON_CODES } from "./compose-graph";
 import { COMPOSITES_ENVIRONMENT_REASON_CODES, COMPOSITES_ERROR_CODES, COMPOSITES_REASON_CODES, COMPOSITES_RUNTIME_REASON_CODES } from "./composites";
 import { WORKSPACE_ERROR_CODES } from "./declaration";
 import { GRAPH_ERROR_CODES } from "./graph-cli";
-import { INTENT_ERROR_CODES, INTENT_FINDING_CODES, INTENT_REASON_CODES } from "./intent";
+import { INTENT_ERROR_CODES, INTENT_FINDING_CODES, INTENT_REASON_CODES, INTENT_WHY_CODES } from "./intent";
 import { CHECK_CODES, CHECK_ERROR_CODES } from "./lineage-check";
 import { GROUP_REASON_CODES, MEMBER_REASON_CODES } from "./ls";
 import intentSchema from "./intent.schema.json";
@@ -29,6 +29,8 @@ import { WORK_WARNING_CODES } from "./work";
 import { BOX_FINDING_CODES } from "./checks/boxes";
 import { DIAGRAM_FINDING_CODES } from "./checks/diagrams";
 import { WORK_ERROR_CODES, WORK_HISTORY_ERROR_CODES, WORK_LEASE_REFUSALS } from "./work-cli";
+import { RUN_STATEMENT_ERROR_CODES, RUNS_ERROR_CODES, RUNS_REASON_CODES, RUNS_WRITE_ERROR_CODES } from "./runs-cli";
+import { RUN_STATEMENT_FAILURE_CODES } from "./trust/run-statement";
 import { WORK_EVIDENCE_ERROR_CODES } from "./work-evidence";
 import { RECORD_FINDING_CODES } from "./checks/records";
 import { ANSWER_WARNING_CODES } from "./points";
@@ -36,7 +38,12 @@ import { POINTS_ERROR_CODES, POINTS_SOURCE_REASON_CODES } from "./points-cli";
 import { POINTS_WRITE_ERROR_CODES } from "./decide";
 import { PATCH_ERROR_CODES } from "./patch";
 import { AGENT_ERROR_CODES } from "./agent-cli";
-import { WRITE_SCOPE_CODES } from "./write-scope";
+import { SCOPE_FINDING_CODES, WRITE_SCOPE_CODES } from "./write-scope";
+import { PLANTABLE_REASON_CODES } from "./box-factory";
+import { BOX_LISTING_ERROR_CODES } from "./box-listing";
+import { BOX_PUBLISH_ERROR_CODES } from "./box-publish";
+import { WRITE_LOCK_ERROR_CODES } from "./write-lock-cli";
+import { WIP_ERROR_CODES, WIP_WRITE_ERROR_CODES } from "./wip";
 import { ROTATION_REFUSAL_CODES } from "./trust/rotation";
 import { SIGNERS_ERROR_CODES } from "./trust/signers-cli";
 import { EVIDENCE_ERROR_CODES } from "./trust/evidence";
@@ -73,6 +80,7 @@ const PER_COMMAND: Record<string, readonly string[]> = {
   INTENT_ERROR_CODES,
   INTENT_FINDING_CODES,
   INTENT_REASON_CODES,
+  INTENT_WHY_CODES,
   CHANGES_FINDING_CODES,
   CHANGES_ERROR_CODES,
   COMPOSITES_ERROR_CODES,
@@ -82,6 +90,11 @@ const PER_COMMAND: Record<string, readonly string[]> = {
   WORK_ERROR_CODES,
   WORK_HISTORY_ERROR_CODES,
   WORK_LEASE_REFUSALS,
+  RUNS_ERROR_CODES,
+  RUNS_REASON_CODES,
+  RUNS_WRITE_ERROR_CODES,
+  RUN_STATEMENT_ERROR_CODES,
+  RUN_STATEMENT_FAILURE_CODES,
   WORK_EVIDENCE_ERROR_CODES,
   RECORD_FINDING_CODES,
   ANSWER_WARNING_CODES,
@@ -91,6 +104,13 @@ const PER_COMMAND: Record<string, readonly string[]> = {
   PATCH_ERROR_CODES,
   AGENT_ERROR_CODES,
   WRITE_SCOPE_CODES,
+  SCOPE_FINDING_CODES,
+  PLANTABLE_REASON_CODES,
+  BOX_LISTING_ERROR_CODES,
+  BOX_PUBLISH_ERROR_CODES,
+  WRITE_LOCK_ERROR_CODES,
+  WIP_ERROR_CODES,
+  WIP_WRITE_ERROR_CODES,
   ROTATION_REFUSAL_CODES,
   SIGNERS_ERROR_CODES,
   EVIDENCE_ERROR_CODES,
@@ -145,7 +165,7 @@ describe("the closed list of reason codes", () => {
 
   test("the output schemas name exactly these codes", () => {
     const named = new Set<string>();
-    for (const f of readdirSync(HERE).filter((f) => f.endsWith(".schema.json") && !f.startsWith("declaration") && !f.startsWith("workspace-kinds"))) {
+    for (const f of readdirSync(HERE).filter((f) => f.endsWith(".schema.json") && !f.startsWith("declaration") && !f.startsWith("workspace-kinds") && !f.startsWith("workspace-principals"))) {
       for (const c of schemaCodes(JSON.parse(readFileSync(join(HERE, f), "utf-8")))) {
         expect(isReasonCode(c), `${f} names ${c}, which is not in reason-codes.ts`).toBe(true);
         named.add(c);

package/src/workspace/reason-codes.ts

@@ -92,6 +92,9 @@ export const REASONS = {
   "work-done-gap-open": "A work record is done, and the finding it came from still fires on its region. graph --intent raises it, and records does by walking that region.",
   "work-acceptance-unmet": "A work record is done, and one of its acceptance criteria has no passing evidence of the verification it expects. check fails on it (WSP117).",
   "work-acceptance-self-verified": "A passing manual verdict on a work record's criterion names the record's implementer, so it does not count: a manual verdict comes from someone else.",
+  "work-contract-unknown": "A work record names a contract that no record of its kind's contract kind has.",
+  "work-contract-undecided": "A work record names a contract whose state is not approved, such as a draft.",
+  "work-tier-unknown": "A work record names a builder tier that its kind's work.tier.tiers does not list.",
   // An answer to a decision point that is valid but warned about (records, points, ws-058, #2739).
   "answer-points-unreadable": "The points file the answer kind names can't be read, or is not valid.",
   "answer-point-unknown": "The answer's point is not declared in the points file the answer kind names.",
@@ -133,10 +136,17 @@ export const REASONS = {
   "source-harvest-not-proposed": "A harvested record (source.via harvest) was written in a state other than the kind's first: a harvest proposes, and a person decides.",
   "ratify-quorum-not-met": "The write puts a record in its kind's ratified state (reviews.ratified), and the record's quorum is not met: too few agreeing verdicts count.",
   "record-sign-failed": "--sign was given and no author seal could be made: the record names no author, the key can't be read or used, git names no ssh signing key, or ssh-keygen is not installed.",
+  // Concurrent writers in one working tree (#3173, ws-089): a write that is refused rather than overwrite another's.
+  "record-conflict": "--expect named a digest the record no longer has: another write changed it after the caller read it. The refusal names the digest it has now; re-read the record and write again.",
+  "write-lock-timeout": "Another write held the working tree's write lock for longer than the write waits (CHANT_WRITE_LOCK_WAIT_MS); the refusal names the holder. Run the write again.",
+  "write-lock-not-held": "CHANT_WRITE_LOCK names a batch's lock token that no longer holds the working tree's write lock: the batch released it, or it expired and another writer took it.",
   // Write scope (#2548): a records write that is refused, and a commit check --changes reports, outside the writer's scope.
   "write-scope-member": "The write is to a file, or to a record kind, of a member outside the writer's scope: an agent session writes only its own member, and writeScope.<class>.members leaves the member out.",
   "write-scope-kind": "The write is to a record kind writeScope.<class>.records does not list, with a verb it does not list for the kind, or deletes a record.",
+  "write-scope-protected": "The write is to a file writeScope.<class>.protected lists, or one under a directory it lists, outside the top-level keys or JSON Pointers the entry's except allows (#3146, #3308).",
+  "write-scope-class-unknown": "The declaration's writeScope at base names a principal class no pinned package supplies, and the writer is judged human, so it may be in that class; the write is refused until the package is installed at the pinned version or the entry removed (#3080).",
   "agent-unknown": "CHANT_AGENT, or a commit's Chant-Agent trailer, names an agent session the declaration at base does not declare.",
+  "principal-unidentified": "chant.workspace.json at base sets identity.attribution to identified, and the write names a person by a bare name: --by, an author field or a decision point's answerer must be a forge identity (github:<login>, gitlab:<login>, <forge>@<host>:<login>), a principal the signers file at base lists, or an agent, runner or service principal (#3163).",
   // A review given in a session (records review --session, #2693).
   "session-unknown": "--session names no session of a session kind whose subjects are the record's kind.",
   "session-not-open": "--session names a session in a closed state, which takes no more verdicts.",
@@ -149,6 +159,9 @@ export const REASONS = {
   "answer-not-candidate": "The people's answer is not one of the question's candidates.",
   "quorum-not-met": "Too few of the people who answered count toward the point's quorum: distinct, not holding the agent role, not the steward that asked, and holding one of its roles when it names any.",
   "answer-in-steward-turn": "The answer was given during a steward's turn, or by a process it started: a steward never answers a decision point, and a person answers it through hud or at a shell.",
+  "answer-not-answered": "points retract names a question that has no answer to retract: it is escalated or proposed, and people answer it instead (#3351).",
+  "answer-field-unsupported": "The answer kind's copy of point-answer.schema.json predates a field the write needs, a note, a relay, a retraction or an ad-hoc question's asked: copy the schema anew to turn it on (#3351, #3402, #3403).",
+  "point-candidates-invalid": "points ask names an ad-hoc point without --candidates, a declared point with them, or candidates that are not a question and criteria of the point's question type (#3403).",
   // records --since that fails (#2673).
   "since-rev-unknown": "--since names no commit, or a session with no opening revision and no commit that added it.",
   "since-session-unknown": "--since has the shape of a session id and names no commit, and no session the kind or the declaration reads has that id.",
@@ -156,12 +169,16 @@ export const REASONS = {
   // The intent graph (graph --intent, #2651): a read that fails.
   "intent-region-invalid": "The region's path, or its line range, does not exist in the tree read.",
   "intent-record-unknown": "graph --intent --record names an id that no record of a decision kind read has.",
+  "intent-symbol-unsupported": "The region names a symbol, path#symbol, in a file no symbol resolver reads; a line range still works.",
+  "intent-symbol-unknown": "The region names a symbol the file does not declare in the tree read.",
+  "intent-symbol-ambiguous": "The region names a symbol that matches more than one declaration in the file; its qualified name picks one.",
   // The intent graph: part of the walk that can't be read. The document is still printed.
   "intent-history-shallow": "The repository is a shallow clone, so the region's history stops at the clone's boundary.",
   "intent-plugin-failed": "A kind file's commitJoins, which joins commits to units, contracts and evidence, failed for a commit.",
+  "squash-unfollowed": "A squash commit's pull request ref (refs/pull/<n>/head) is not in the clone and could not be fetched from origin, so its original commits are not followed; the read keeps its answer without them.",
   // The intent graph: findings, each a node in the graph.
   "intent-commit-undecided": "A commit changed the region when no decision constrained it at path granularity.",
-  "intent-commit-bare": "A commit names no unit, no pull request and no decision covering the region at its time.",
+  "intent-commit-bare": "A commit names no unit, carries no record through its Chant-Record or Chant-Lease trailer, and has no pull request and no decision covering the region at its time.",
   "intent-pin-drifted": "A decision's pinned artifact no longer hashes to the pin.",
   "intent-pin-missing": "A decision's pinned artifact does not exist in the tree read.",
   "intent-pin-stale": "A current decision pins an artifact at the hash a record it supersedes pinned, and the artifact has not changed since: the decision moved on and the artifact did not.",
@@ -177,6 +194,12 @@ export const REASONS = {
   "intent-decision-unimplemented": "A decided decision constrains the region, no work item that is not dropped implements it, and no commit falls in its window.",
   "intent-work-blocked": "A work item constraining the region has commits in its window while a work item it needs is not done.",
   "intent-work-open-decided-code": "Commits in the region are a decision's own work while the work item implementing that decision is still open.",
+  "intent-commit-join-conflict": "A commit joined to an agent run by its Chant-Run trailer or the run's record has the patch-id of a commit another run recorded, so it is not joined to that run by content.",
+  // The intent graph's answer to why the region is like this (#3034): what it can't account for.
+  "intent-why-no-decision": "No current decision governs the region at any granularity, and none is carried out by the commits or runs that made its current lines.",
+  "intent-why-no-run": "None of the region's current lines was made by a commit an agent run is joined to.",
+  "intent-why-uncommitted": "Some of the region's lines are not committed yet.",
+  "intent-why-run-ambiguous": "Some lines come from a commit several agent runs made, and no run's recorded hunks say which wrote them.",
   // The forward coverage check (check --changes, #2773): findings, one per changed path.
   "change-uncovered": "A path the diff changes is covered by no current decided record and no open work item, by path or by its member.",
   "change-out-of-scope": "A record in hand for the change, such as the work item it is for or a decision that item implements, lists a path the diff changes in its out_of_scope.",
@@ -193,6 +216,7 @@ export const REASONS = {
   "environments-none-declared": "The member's chant.config.ts declares no environments, so only local and the environments in its ledger are listed.",
   "environments-ledger-undeclared": "The member's ledger has releases in an environment its config's environments don't cover, so chant run --env would refuse it and it is not listed.",
   "environments-ledger-unreadable": "The chant/lifecycle branch exists and the member's ledger environments could not be listed.",
+  "environments-component-undeclared": "A component declares an environment its member's chant.config.ts environments don't cover, so chant run --env would refuse it and it is not listed (#3153).",
   // A declared diagram's source or render (check, #2764). Each is also a WSP finding.
   "diagram-source-missing": "A declared diagram's source file does not exist in the tree read.",
   "diagram-render-missing": "A declared diagram's render file does not exist in the tree read.",
@@ -205,6 +229,9 @@ export const REASONS = {
   // A box's intent, the decision record its box block names (check, #2850). Each is also a WSP finding.
   "box-intent-unknown": "A box block names an intent, and no record of a declared kind named decision has that id.",
   "box-intent-unconstrained": "The decision record a box names as its intent constrains no member or path of this workspace: no member: entry for a declared member and no path: entry at, above or inside one's directory.",
+  // Why a workspace isn't plantable (status and graph, #3146): not a finding, since a workspace need not be.
+  "box-none": "No member's box block declares services, so the workspace has no box for a host to plant.",
+  "box-several": "More than one member's box block declares services, and a planted workspace runs one box.",
   // The work lease (chant workspace work claim|renew|release, #2732): why the command could not run.
   "work-kind-missing": "No work kind to find the item in: --kind names a kind with no work block, or the declaration names no work kind.",
   "work-kind-ambiguous": "More than one declared work kind has a record with the id, so --kind must name one.",
@@ -218,6 +245,36 @@ export const REASONS = {
   "lease-token-mismatch": "The live lease on the work item carries another fencing token than the one given.",
   "lease-race": "Another writer changed the lease between this command's read and its write.",
   "lease-push-rejected": "The remote refused the lease push: another clone claimed the item first, or the remote could not be reached.",
+  // The agent run record (chant workspace runs, #3033): why a write was refused, and what a read could not see. Nothing is written on a refusal.
+  "run-exists": "runs start or runs record was given a run id the ledger already has.",
+  "run-unknown": "runs end names a run the ledger has no start for.",
+  "run-ended": "runs end names a run whose end is already recorded.",
+  "runs-no-ledger": "The checkout has no chant/lifecycle branch, so there are no agent runs to read.",
+  "runs-ledger-malformed": "Some lines of the agent run ledger aren't run events; the rest are read.",
+  // The agent-run statement (runs sign, statement and verify, #3192): why a statement is refused or does not verify.
+  "run-not-ended": "runs sign or runs statement names a run with no end recorded. A statement is signed over the run's whole record.",
+  "run-statement-invalid": "The envelope's payload is not an in-toto Statement v1 with chant's agent-run predicate, or has a field the predicate does not define.",
+  "run-statement-signer-mismatch": "The statement names a signer other than the runner whose key signed it.",
+  "run-statement-mismatch": "A listed runner key signed the statement, and it does not match the run's record: another run, a record that hashes differently, or another unit, harness, model, provider or principal.",
+  // A box's listing written through chant (box listing set, #3308): why the write was refused. Nothing is written.
+  "listing-member-unknown": "box listing set names a member the declaration does not declare.",
+  "listing-box-missing": "box listing set names a member whose entry declares no box block, so it has no listing.",
+  "listing-cover-invalid": "The cover can't be read, is not a PNG, JPEG or WebP picture, is larger than 5 MiB, has a path outside the workspace, or has an extension other than its picture format's.",
+  // A box's work published through chant (box publish, #3165, ws-088): why the call printed no result.
+  "publish-member-unknown": "box publish names a member the declaration does not declare.",
+  "publish-none": "box publish names a member whose box block names no publisher, or which declares no box block.",
+  "publish-refused": "The box's publisher refused (it exited 2): nothing was published, and its message says why.",
+  "publish-failed": "The box's publisher could not be run, failed (a nonzero exit other than 2) or ran out of time; its message says what it had done.",
+  "publish-answer-invalid": "The box's publisher exited 0 and printed no JSON object, or one box-publish.schema.json does not allow.",
+  "publish-unrecorded": "The commit the publisher named is not in the repository, or lacks the apply record of ws-075: Chant-Applied-By naming --by, Chant-Applied-At, Chant-Applied-Commit and a Chant-Record for the item, or a Chant-Record for each record sent.",
+  // Work in progress under refs/chant/wip/<branch> and its replication (wip save|restore|push|fetch, #3172): why the write was refused. Nothing is written.
+  "wip-no-branch": "HEAD is detached, or names a branch with no commit yet, so there is no branch to keep work in progress for.",
+  "wip-none": "wip restore was given no snapshot, and the branch has none under refs/chant/wip/<branch>.",
+  "wip-snapshot-unknown": "wip restore names something that is not a work-in-progress snapshot chant took.",
+  "wip-branch-other": "wip restore names a snapshot taken on another branch than the one checked out.",
+  "wip-race": "Another writer moved refs/chant/wip/<branch> between this command's read and its write.",
+  "wip-policy-none": "wip push or wip fetch was run, and no box block declares replicate, so there is no remote.",
+  "wip-remote-unknown": "The replicate policy names a git remote the checkout does not have; the host adds it, with its credential, before chant pushes.",
   // A box whose isolation fails (check, #2727). Each is also a WSP finding.
   "box-isolation-collision": "Two boxes on one host resolve to the same port, state path or cookie name, or two ports in one box share an offset.",
   "box-isolation-literal": "A host's stateRoot or a box's state entry is a literal machine path instead of one derived from an environment reference and the box's name.",
@@ -240,9 +297,9 @@ export const REASONS = {
   "evidence-payload-type": "The envelope's payload type is not application/vnd.in-toto+json.",
   "evidence-statement-invalid": "The payload is not an in-toto Statement v1 with chant's runner-evidence predicate, or has a field the predicate does not define.",
   "evidence-runner-mismatch": "The statement names a runner other than the one whose key signed it.",
-  "runner-key-invalid": "The key given to evidence sign is not an Ed25519 private key in PEM.",
-  "runner-key-is-signer": "The key given to evidence sign is a person's key in the signers file. Evidence is signed by a service or CI identity.",
-  "runner-key-unlisted": "The policy at base lists no runner with the key given to evidence sign.",
+  "runner-key-invalid": "The key given to evidence sign or runs sign is not an Ed25519 private key in PEM.",
+  "runner-key-is-signer": "The key given to evidence sign or runs sign is a person's key in the signers file. Evidence and run statements are signed by a service or CI identity.",
+  "runner-key-unlisted": "The policy at base lists no runner with the key given to evidence sign or runs sign.",
   // The lineage lock (check).
   "lock-invalid": "The lineage lock can't be read.",
   "manual-step-open": "A scope in the lineage lock has an open manual step.",

package/src/workspace/record-sessions.ts

@@ -12,7 +12,7 @@
  * `citedBy`. This module only reads; nothing here writes a seal into a file.
  */
 
-import { recordSeal, type RecordEntry, type RecordFormat, type RecordKind } from "./records";
+import { recordSeal, sessionSubjectKinds, type RecordEntry, type RecordFormat, type RecordKind, type SessionSubjects } from "./records";
 
 /** A subject record's review entry that names a session in its `session` field. */
 export interface SessionCitation {
@@ -43,18 +43,19 @@ export function sessionSeal(text: string, field: string, format: RecordFormat =
 /**
  * Check each session in `entries` against its seal and the subject records,
  * and fill in `citedBy`. `texts` holds each entry's file text by path.
- * `subjects` holds the subject records and the name of their reviews list;
- * it is null when they were not read, and then no verdict is checked.
+ * `subjects` holds the records of each subject kind and the name of their
+ * reviews list; it is null when they were not read, and then no verdict is
+ * checked.
  */
-export function joinSessions(kind: RecordKind, entries: RecordEntry[], texts: Map<string, string>, subjects: { records: RecordEntry[]; reviews: string } | null): void {
+export function joinSessions(kind: RecordKind, entries: RecordEntry[], texts: Map<string, string>, subjects: SessionSubjects[] | null): void {
   const decl = kind.session;
   if (!decl) return;
   const closed = new Set(kind.closedStates);
-  const subjectIds = new Set(subjects?.records.map((s) => s.id).filter((id): id is string => id !== null) ?? []);
+  const subjectIds = new Set((subjects ?? []).flatMap((k) => k.records.map((s) => s.id)).filter((id): id is string => id !== null));
   const citations = new Map<string, SessionCitation[]>();
-  for (const s of subjects?.records ?? []) {
+  for (const { s, reviewsField } of (subjects ?? []).flatMap((k) => k.records.map((s) => ({ s, reviewsField: k.reviews })))) {
     if (s.id === null) continue;
-    const reviews = s.data?.[subjects!.reviews];
+    const reviews = s.data?.[reviewsField];
     if (!Array.isArray(reviews)) continue;
     reviews.forEach((r, index) => {
       if (r === null || typeof r !== "object") return;
@@ -96,7 +97,7 @@ export function joinSessions(kind: RecordKind, entries: RecordEntry[], texts: Ma
       if (v === null || typeof v !== "object") return;
       const record = (v as Record<string, unknown>).record;
       if (typeof record === "string" && !subjectIds.has(record)) {
-        e.reasons.push({ code: "session-verdict-unknown-record", message: `${decl.verdicts}[${i}] names ${record}, which no ${decl.subjects.kind} record has` });
+        e.reasons.push({ code: "session-verdict-unknown-record", message: `${decl.verdicts}[${i}] names ${record}, which no ${sessionSubjectKinds(decl).join(" or ")} record has` });
       }
     });
   }

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

@@ -108,6 +108,11 @@
             "$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."
@@ -176,9 +181,14 @@
                 "amend-supersede-instead",
                 "record-sign-failed",
                 "ratify-quorum-not-met",
+                "record-conflict",
+                "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",
@@ -197,6 +207,76 @@
             }
           }
         },
+        "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/src/workspace/records-checkout.ts

@@ -0,0 +1,106 @@
+/**
+ * The checkout a working-tree read is made in, and which records in it are
+ * uncommitted (#3160).
+ *
+ * Work in progress lives as uncommitted files in a work branch's working tree
+ * (#3158, #3145). A reader such as hud or studio shows "kept, not yet
+ * applied" from `records --json` alone: each record says whether it is
+ * committed, modified or new against `HEAD`, and the document names the
+ * branch, the commit `HEAD` names and the base that branch forked from. The
+ * reader never diffs git itself.
+ *
+ * Every git call here reads. None takes the index lock or refreshes the
+ * index (`--no-optional-locks`), so a read leaves the checkout as it was,
+ * `.git` included, which the reader conformance suite checks.
+ */
+
+import { execFileSync } from "node:child_process";
+import { resolveBase, type BaseSource } from "./trust/provenance";
+
+/** Where a record's file stands against `HEAD`. */
+export type WorktreeState = "committed" | "modified" | "new";
+
+/** The branch, head and base of a checkout (#3160). `records` and `status` both print it. */
+export interface CheckoutHead {
+  /** The checked-out branch's short name, such as `chant/work/w-12`, or null when `HEAD` is detached. */
+  branch: string | null;
+  /** The commit `HEAD` names, or null before the first commit. Each record's `worktree` is judged against it. */
+  head: string | null;
+  /** The merge base of `head` and the target branch tip: the commit the branch forked from. Null without a head, a target, or common history. */
+  base: string | null;
+  /** Where the target branch was found: `flag` for `--base`, else `origin/HEAD`, `main` or `master`. Null when there is none. */
+  baseFrom: BaseSource | null;
+}
+
+/** {@link CheckoutHead} for one record kind, with the record files `HEAD` has and the working tree does not. */
+export interface CheckoutView extends CheckoutHead {
+  /** Record files of the kind at `head` that the working tree no longer has, from the repository root, sorted. */
+  deleted: string[];
+}
+
+function git(top: string, args: string[]): string {
+  return execFileSync("git", ["--no-optional-locks", "--literal-pathspecs", ...args], {
+    cwd: top,
+    encoding: "utf-8",
+    stdio: ["ignore", "pipe", "pipe"],
+    maxBuffer: 256 * 1024 * 1024,
+  });
+}
+
+function tryGit(top: string, args: string[]): string | undefined {
+  try {
+    return git(top, args);
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * The branch, head and base of the checkout at `top`. `explicitBase` is
+ * `--base`, as the trust policy takes it; otherwise the target branch is the
+ * one the policy is read at (`origin/HEAD`, then `main`, then `master`).
+ */
+export function readCheckoutHead(top: string, explicitBase?: string): CheckoutHead {
+  const branch = tryGit(top, ["symbolic-ref", "--quiet", "--short", "HEAD"])?.trim() || null;
+  const head = tryGit(top, ["rev-parse", "--verify", "--quiet", "HEAD^{commit}"])?.trim() || null;
+  const target = resolveBase(top, explicitBase);
+  const base = head && target.commit ? tryGit(top, ["merge-base", head, target.commit])?.trim() || null : null;
+  return { branch, head, base, baseFrom: target.from };
+}
+
+/** NUL-separated git output as a list. */
+function zList(out: string | undefined): string[] {
+  return (out ?? "").split("\0").filter(Boolean);
+}
+
+/**
+ * Each of `paths` (record files directly in `dir`, from the repository root)
+ * as committed, modified or new against `head`, and the files directly in
+ * `dir` at `head` whose names `match` and that `paths` leaves out: the
+ * records deleted in the working tree. With no head every path is new.
+ *
+ * Staged and unstaged changes count alike: anything `HEAD` does not hold is
+ * uncommitted. A rename is a new record and a deleted one.
+ */
+export function worktreeStates(
+  top: string,
+  head: string | null,
+  dir: string,
+  paths: readonly string[],
+  match: RegExp,
+): { states: Map<string, WorktreeState>; deleted: string[] } {
+  const states = new Map<string, WorktreeState>();
+  if (head === null) {
+    for (const p of paths) states.set(p, "new");
+    return { states, deleted: [] };
+  }
+  const prefix = dir === "." ? "" : `${dir}/`;
+  const direct = (p: string) => p.startsWith(prefix) && !p.slice(prefix.length).includes("/");
+  const spec = dir === "." ? "." : dir;
+  const atHead = new Set(zList(tryGit(top, ["ls-tree", "-r", "-z", "--name-only", head, "--", spec])).filter(direct));
+  const changed = new Set(zList(tryGit(top, ["diff", "--name-only", "-z", "--no-renames", head, "--", spec])));
+  for (const p of paths) states.set(p, !atHead.has(p) ? "new" : changed.has(p) ? "modified" : "committed");
+  const present = new Set(paths);
+  const deleted = [...atHead].filter((p) => !present.has(p) && match.test(p.slice(prefix.length))).sort();
+  return { states, deleted };
+}