@intentius/chant 0.102.0 → 0.104.1

package/src/workspace/work-cli.ts

@@ -55,6 +55,7 @@ import { declaredKindFiles, readRecordsFor } from "./records-cli";
 import { loadRecordKind, RecordReadError, type LoadedRecordKind, type RecordEntry } from "./records";
 import { gitRoot } from "./record-source";
 import type { ReasonCode } from "./reason-codes";
+import { replicateAfter } from "./wip";
 
 /** The version of the `work` output this chant writes. */
 export const WORK_LEASE_CONTRACT_VERSION = 1;
@@ -223,6 +224,8 @@ export async function workLease(req: WorkLeaseRequest): Promise<WorkLeaseDocumen
       const heldBy = result.heldBy ? strip(result.heldBy) : null;
       return { ...head, refused: { code: result.reason, message: result.message, heldBy } };
     }
+    // #3172: a box's replicate policy may push its work in progress once a lease is released. Best effort; status shows what is behind.
+    if (req.verb === "release") replicateAfter("release", req.cwd);
     return { ...head, lease: strip(result.lease), history: result.history };
   } catch (err) {
     if (err instanceof WorkError) return { ...doc, error: { code: err.code, message: err.message } };

package/src/workspace/work-evidence.schema.json

@@ -182,6 +182,9 @@
                 "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",

package/src/workspace/work-size.test.ts

@@ -0,0 +1,77 @@
+/**
+ * The slice-tier point's sizes and the understand point (#3150): chant
+ * measures a work item the same way for every orchestrator, the decide
+ * activity reads the sizes with the item, and the reference workspace
+ * declares understand.
+ */
+
+import { cpSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { afterAll, describe, expect, test } from "vitest";
+import { readInputs } from "../op/decide-read-inputs";
+import { cleanScratch, git, REPO, scratchDir } from "./__fixtures__/contract-repo";
+import { parsePoints } from "./points";
+import { DEFAULT_TIER_LIMITS, fitsTier, measureWorkItem, sizeFields } from "./work-size";
+
+afterAll(cleanScratch);
+
+const SIZES = ["work-item.criteria", "work-item.files", "work-item.words", "work-item.fits_small", "work-item.fits_medium"];
+
+describe("measuring a work item (#3150)", () => {
+  test("criteria, backticked paths and words from the ask, the body without headings and the criteria", () => {
+    const data = {
+      source: { ask: { said: "Make `app/server.ts` answer on `/healthz` and note it in `README.md`.", by: "alice" } },
+      acceptance: [{ id: "AC-1", text: "`app/server.ts` answers 200" }, { id: "AC-2", text: "the README says so" }],
+    };
+    const body = "# Heading words are not counted\n\nThe body names `app/server.ts` again and `docs/`.\n";
+    const size = measureWorkItem(data, body);
+    // `docs/` and `/healthz` have no part on both sides of a slash, so they are not paths.
+    expect(size).toEqual({ criteria: 2, files: 2, words: 24 });
+    expect(measureWorkItem({ source: { intent: { answer: "a garden planner" } } }, "")).toEqual({ criteria: 0, files: 0, words: 3 });
+    expect(measureWorkItem(null, "")).toEqual({ criteria: 0, files: 0, words: 0 });
+  });
+
+  test("fits_<tier> for each tier with limits, against the defaults or the kind's own", () => {
+    expect(sizeFields({ criteria: 11, files: 2, words: 40 })).toEqual({ criteria: 11, files: 2, words: 40, fits_small: false, fits_medium: true });
+    expect(sizeFields({ criteria: 1, files: 1, words: 400 })).toMatchObject({ fits_small: false, fits_medium: false });
+    expect(sizeFields({ criteria: 1, files: 1, words: 40 }, { tiny: { words: 30 } })).toEqual({ criteria: 1, files: 1, words: 40, fits_tiny: false });
+    expect(fitsTier({ criteria: 10, files: 5, words: 150 }, DEFAULT_TIER_LIMITS.small)).toBe(true);
+    expect(fitsTier({ criteria: 0, files: 0, words: 0 }, undefined)).toBe(false);
+  });
+});
+
+describe("the reference workspace (#3150)", () => {
+  const ref = join(REPO, "reference-workspace");
+
+  test("declares understand: four answers, a table that proceeds on an open item, then people", () => {
+    const points = parsePoints(readFileSync(join(ref, "decisions", "points.json"), "utf-8"), "points.json");
+    const u = points.understand;
+    expect(Object.keys(u.question.criteria ?? {})).toEqual(["proceed", "redraft", "ask", "refuse"]);
+    expect(Object.keys(u.inputs)).toEqual(["work-item.state", "work-item.title", "work-item.source.ask.said", "work-item.source.ask.by", "work-item.source.ask.via", "work-item.acceptance"]);
+    expect(u.deciders.map((d) => d.kind)).toEqual(["table", "quorum"]);
+  });
+
+  test("the decide activity reads a work item's sizes with it, and the work kind's limits win", async () => {
+    const copy = (): string => {
+      const root = scratchDir("chant-work-size-");
+      cpSync(ref, root, { recursive: true, filter: (src) => !/[\\/](node_modules|dist)$/.test(src) });
+      git(root, "init", "-q");
+      git(root, "add", "-A");
+      git(root, "commit", "-q", "-m", "the workspace");
+      return root;
+    };
+    let root = copy();
+    const read = await readInputs(SIZES, { "work-item": "W-001" }, root);
+    expect(read.missing).toEqual([]);
+    expect(read.inputs).toMatchObject({ "work-item.criteria": 2, "work-item.fits_small": true, "work-item.fits_medium": true });
+    expect(typeof read.inputs["work-item.words"]).toBe("number");
+
+    // A fresh copy: a kind file is loaded once per path.
+    root = copy();
+    const kind = join(root, "work", "work.kind.mjs");
+    writeFileSync(kind, readFileSync(kind, "utf-8").replace('tier: { field: "tier", tiers: ["small", "medium", "large"] }', 'tier: { field: "tier", tiers: ["small", "medium", "large"], limits: { small: { criteria: 1 } } }'));
+    const narrow = await readInputs(SIZES, { "work-item": "W-001" }, root);
+    expect(narrow.inputs["work-item.fits_small"]).toBe(false);
+    expect(narrow.missing).toEqual(["work-item.fits_medium"]);
+  });
+});

package/src/workspace/work-size.ts

@@ -0,0 +1,93 @@
+/**
+ * How much a work item holds, for the `slice-tier` decision point (#3150).
+ *
+ * The point picks the smallest builder tier that can build an item, from five
+ * inputs every orchestrator must compute the same way, so chant computes
+ * them. They are read through the `work-item` output like any other field:
+ *
+ *   work-item.criteria      the item's acceptance criteria, counted
+ *   work-item.files         distinct paths the item names in backticks
+ *   work-item.words         words in the item's text
+ *   work-item.fits_<tier>   whether criteria, files and words are each within
+ *                           that tier's limits (`fits_small`, `fits_medium`)
+ *
+ * The item's text is what a person asked (`source.ask.said`, or the answer
+ * to the box's intent, `source.intent.answer`), the record's Markdown body
+ * with its heading lines left out, and each acceptance criterion's text. A
+ * path is a backticked token with a `/` between two parts, such as
+ * `app/server.ts` or `design/screens/`, or a file name with an extension of
+ * one to five letters, such as `README.md`. Words are runs of non-blank
+ * characters.
+ *
+ * The limits are the work kind's `work.tier.limits`, else
+ * {@link DEFAULT_TIER_LIMITS}: small holds at most 10 criteria, 5 files and
+ * 150 words, medium 20, 10 and 300. A tier with no limits, such as large,
+ * has no `fits_` input; an item that fits neither small nor medium is large.
+ * These are the sizing defaults studio's factory used (arugula-salad/studio
+ * `queue.mjs` `sizing()`), so a point's answers keep their meaning.
+ */
+
+/** A field of `value` by dotted path, or undefined. */
+function fieldOf(value: unknown, path: string): unknown {
+  let at: unknown = value;
+  for (const part of path.split(".")) {
+    if (at === null || typeof at !== "object" || !Object.prototype.hasOwnProperty.call(at, part)) return undefined;
+    at = (at as Record<string, unknown>)[part];
+  }
+  return at;
+}
+
+/** What one tier may hold. A limit left out is not checked. */
+export interface TierLimit {
+  criteria?: number;
+  files?: number;
+  words?: number;
+}
+
+/** The limits when the work kind declares none. */
+export const DEFAULT_TIER_LIMITS: Readonly<Record<string, TierLimit>> = Object.freeze({
+  small: { criteria: 10, files: 5, words: 150 },
+  medium: { criteria: 20, files: 10, words: 300 },
+});
+
+export interface WorkItemSize {
+  criteria: number;
+  files: number;
+  words: number;
+}
+
+const HEADING = /^\s*#/;
+const PATH_LIKE = /^[\w@.-]+(\/[\w@.*-]+)+\/?$|^[\w@-][\w@.-]*\.[a-z]{1,5}$/i;
+const str = (v: unknown): string => (typeof v === "string" ? v : "");
+
+/**
+ * Measure a work item from its front matter (`data`) and Markdown body.
+ * `acceptanceField` is the work kind's `work.acceptance.field`, `acceptance`
+ * when it names none.
+ */
+export function measureWorkItem(data: Record<string, unknown> | null, body: string, acceptanceField = "acceptance"): WorkItemSize {
+  const d = data ?? {};
+  const acceptance = Array.isArray(d[acceptanceField]) ? (d[acceptanceField] as unknown[]) : [];
+  const said = str(fieldOf(d, "source.ask.said")) || str(fieldOf(d, "source.intent.answer"));
+  const bodyLines = body.split("\n").filter((l) => !HEADING.test(l));
+  const criteriaText = acceptance.map((c) => (typeof c === "string" ? c : str((c as { text?: unknown } | null)?.text)));
+  const text = [said, ...bodyLines, ...criteriaText].join("\n");
+  const files = new Set([...text.matchAll(/`([^`\s]+)`/g)].map((m) => m[1]).filter((t) => PATH_LIKE.test(t)));
+  return { criteria: acceptance.length, files: files.size, words: text.split(/\s+/).filter(Boolean).length };
+}
+
+/** Whether `size` is within `limit`: each limit given is at least the measure. */
+export function fitsTier(size: WorkItemSize, limit: TierLimit | undefined): boolean {
+  if (!limit) return false;
+  return (["criteria", "files", "words"] as const).every((k) => limit[k] === undefined || size[k] <= limit[k]!);
+}
+
+/**
+ * The slice-tier inputs' fields for a measured item: `criteria`, `files`,
+ * `words` and `fits_<tier>` for each tier `limits` names.
+ */
+export function sizeFields(size: WorkItemSize, limits: Readonly<Record<string, TierLimit>> = DEFAULT_TIER_LIMITS): Record<string, number | boolean> {
+  const out: Record<string, number | boolean> = { criteria: size.criteria, files: size.files, words: size.words };
+  for (const [tier, limit] of Object.entries(limits)) out[`fits_${tier}`] = fitsTier(size, limit);
+  return out;
+}

package/src/workspace/workspace-kinds.schema.json

@@ -75,6 +75,9 @@
         },
         "graph": {
           "$ref": "#/$defs/graph"
+        },
+        "fields": {
+          "$ref": "#/$defs/fields"
         }
       },
       "patternProperties": {
@@ -123,6 +126,34 @@
             }
           },
           "additionalProperties": false
+        },
+        "anyJsonKey": {
+          "type": "object",
+          "description": "The directory passes when a file directly in it, whose name matches one of in, parses as JSON and has a value at one of pointers, each a JSON Pointer such as /scripts/start (#3151). A file that is not JSON is no evidence either way. Added by chant 0.103.0.",
+          "required": [
+            "in",
+            "pointers"
+          ],
+          "properties": {
+            "in": {
+              "type": "array",
+              "minItems": 1,
+              "uniqueItems": true,
+              "items": {
+                "$ref": "#/$defs/fileName"
+              }
+            },
+            "pointers": {
+              "type": "array",
+              "minItems": 1,
+              "uniqueItems": true,
+              "items": {
+                "type": "string",
+                "pattern": "^(/[^/]+)+$"
+              }
+            }
+          },
+          "additionalProperties": false
         }
       },
       "additionalProperties": false
@@ -154,6 +185,97 @@
         "^x-": true
       },
       "additionalProperties": false
+    },
+    "fields": {
+      "type": "object",
+      "description": "The fields a member entry of this kind may set under its own fields block, each with a type and, optionally, a default (#3151). chant workspace check fails a member whose fields name one the kind doesn't declare or give a value of the wrong type (WSP005), and chant workspace status --json prints every declared field with the defaults filled in. Added by chant 0.103.0; an older chant can't read a kinds file that uses it.",
+      "minProperties": 1,
+      "propertyNames": {
+        "$ref": "#/$defs/fieldName"
+      },
+      "additionalProperties": {
+        "oneOf": [
+          {
+            "$ref": "#/$defs/scalarField"
+          },
+          {
+            "$ref": "#/$defs/objectField"
+          }
+        ]
+      }
+    },
+    "fieldName": {
+      "type": "string",
+      "pattern": "^[a-z][A-Za-z0-9]{0,39}$"
+    },
+    "scalarField": {
+      "type": "object",
+      "required": [
+        "type",
+        "description"
+      ],
+      "properties": {
+        "type": {
+          "enum": [
+            "string",
+            "integer",
+            "boolean"
+          ]
+        },
+        "description": {
+          "type": "string",
+          "minLength": 1
+        },
+        "default": {
+          "oneOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "integer"
+            },
+            {
+              "type": "boolean"
+            }
+          ],
+          "description": "The value a member that doesn't set the field gets. Its type is the field's. Without it the field reads as null when unset."
+        },
+        "pattern": {
+          "type": "string",
+          "minLength": 1,
+          "description": "For a string field: a regular expression the value must match."
+        }
+      },
+      "additionalProperties": false
+    },
+    "objectField": {
+      "type": "object",
+      "required": [
+        "type",
+        "description",
+        "properties"
+      ],
+      "properties": {
+        "type": {
+          "const": "object"
+        },
+        "description": {
+          "type": "string",
+          "minLength": 1
+        },
+        "properties": {
+          "type": "object",
+          "minProperties": 1,
+          "propertyNames": {
+            "$ref": "#/$defs/fieldName"
+          },
+          "additionalProperties": {
+            "$ref": "#/$defs/scalarField"
+          },
+          "description": "The object's own fields, each a string, integer or boolean field. A member sets any of them; the rest take their defaults."
+        }
+      },
+      "additionalProperties": false
     }
   }
 }

package/src/workspace/write-lock-cli.ts

@@ -0,0 +1,131 @@
+/**
+ * `chant workspace lock` (#3173, ws-089): the working tree's write lock
+ * (`write-lock.ts`), seen and held from outside chant.
+ *
+ * - `lock` prints who holds it now, or that nobody does.
+ * - `lock acquire --holder <name> [--ttl <duration>]` takes it for a batch of
+ *   writes across several chant calls, waiting for it as a write does, and
+ *   prints the token. Each chant write of the batch runs with
+ *   `CHANT_WRITE_LOCK=<token>` and goes ahead without waiting; every other
+ *   writer waits. The lock lasts until it is released or the ttl passes
+ *   (default 60s, at most 10m), after which any writer may break it.
+ * - `lock release --token <token>` gives it back.
+ *
+ * Each prints one JSON document (`write-lock.schema.json`); a refusal exits 1.
+ * The token is printed only to the caller that took the lock: `lock` never
+ * prints it, so holding the lock can't be taken over by reading who holds it.
+ */
+
+import type { CommandContext } from "../cli/registry";
+import { parseDuration } from "../op/duration";
+import { readerVersion } from "./declaration";
+import {
+  acquireBatchLock,
+  DEFAULT_BATCH_TTL_MS,
+  MAX_BATCH_TTL_MS,
+  releaseLock,
+  writeLockHolder,
+  writeLockPath,
+  WriteLockError,
+  type WriteLockHolder,
+} from "./write-lock";
+import { AGENT_ENV } from "./write-scope";
+
+export const WRITE_LOCK_CONTRACT_VERSION = 1;
+export const WRITE_LOCK_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace/write-lock/v1/write-lock.schema.json";
+
+/** Why a lock command did nothing. Closed. */
+export const WRITE_LOCK_ERROR_CODES = ["write-usage-invalid", "write-lock-timeout", "write-lock-not-held"] as const;
+export type WriteLockErrorCode = (typeof WRITE_LOCK_ERROR_CODES)[number];
+
+/** A holder as the documents show it: everything but the token. */
+export type HolderView = Omit<WriteLockHolder, "token">;
+
+export type WriteLockDocument =
+  | {
+      $schema: string;
+      contract: number;
+      chant: string;
+      verb: "status" | "acquire" | "release";
+      /** The lock directory. */
+      path: string;
+      /** Who holds the lock after the command: the batch for acquire, null after release. */
+      holder: HolderView | null;
+      /** acquire only: the token each write of the batch runs with, as CHANT_WRITE_LOCK. */
+      token?: string;
+    }
+  | { $schema: string; contract: number; chant: string; verb: "status" | "acquire" | "release"; error: { code: WriteLockErrorCode; message: string }; holder: HolderView | null };
+
+const USAGE = "chant workspace lock [acquire --holder <name> [--ttl <duration>] | release --token <token>] [--json]";
+
+function view(h: WriteLockHolder | null): HolderView | null {
+  if (h === null) return null;
+  const { token: _token, ...rest } = h;
+  return rest;
+}
+
+/** Run one lock command and build its document. */
+export async function workspaceLock(req: { cwd: string; verb: string | undefined; holder?: string; ttl?: string; token?: string; agent?: string }): Promise<WriteLockDocument> {
+  const verb = req.verb === undefined || req.verb === "status" ? "status" : req.verb === "acquire" || req.verb === "release" ? req.verb : null;
+  const head = { $schema: WRITE_LOCK_SCHEMA_ID, contract: WRITE_LOCK_CONTRACT_VERSION, chant: readerVersion() };
+  const fail = (v: "status" | "acquire" | "release", code: WriteLockErrorCode, message: string, holder: WriteLockHolder | null = null): WriteLockDocument => ({
+    ...head,
+    verb: v,
+    error: { code, message: code === "write-usage-invalid" ? `${message}\n${USAGE}` : message },
+    holder: view(holder),
+  });
+  if (verb === null) return fail("status", "write-usage-invalid", `lock takes acquire or release, or nothing to say who holds it, not ${req.verb}`);
+  if (verb === "status") {
+    if (req.holder !== undefined || req.ttl !== undefined || req.token !== undefined) return fail(verb, "write-usage-invalid", "lock with no verb only says who holds the lock, and takes no --holder, --ttl or --token");
+    const { path, holder } = writeLockHolder(req.cwd);
+    return { ...head, verb, path, holder: view(holder) };
+  }
+  if (verb === "acquire") {
+    if (!req.holder) return fail(verb, "write-usage-invalid", "lock acquire needs --holder <name>: who holds the lock, as the other writers waiting on it are told");
+    if (req.token !== undefined) return fail(verb, "write-usage-invalid", "lock acquire hands out a token, and takes none");
+    let ttlMs = DEFAULT_BATCH_TTL_MS;
+    if (req.ttl !== undefined) {
+      const ms = /^\d+$/.test(req.ttl) ? Number(req.ttl) * 1000 : parseDurationOrNull(req.ttl);
+      if (ms === null || ms <= 0 || ms > MAX_BATCH_TTL_MS) return fail(verb, "write-usage-invalid", `--ttl takes a duration up to ${MAX_BATCH_TTL_MS / 60_000}m, such as 90s or 5m, not ${JSON.stringify(req.ttl)}`);
+      ttlMs = ms;
+    }
+    try {
+      const { path, holder } = await acquireBatchLock(req.cwd, { verb: "batch", by: req.holder, agent: req.agent ?? null }, ttlMs);
+      return { ...head, verb, path, holder: view(holder), token: holder.token };
+    } catch (err) {
+      if (err instanceof WriteLockError) return fail(verb, err.code, err.message, err.holder);
+      throw err;
+    }
+  }
+  if (!req.token) return fail(verb, "write-usage-invalid", "lock release needs --token <token>, as lock acquire printed it");
+  if (req.holder !== undefined || req.ttl !== undefined) return fail(verb, "write-usage-invalid", "lock release takes only --token");
+  const path = writeLockPath(req.cwd);
+  if (!releaseLock(path, req.token)) {
+    const { holder } = writeLockHolder(req.cwd);
+    return fail(verb, "write-lock-not-held", `the token given does not hold the write lock (${holder ? "another writer holds it" : "nobody holds it"}): it was released already, or it expired`, holder);
+  }
+  return { ...head, verb, path, holder: null };
+}
+
+function parseDurationOrNull(raw: string): number | null {
+  try {
+    return parseDuration(raw);
+  } catch {
+    return null;
+  }
+}
+
+/** `chant workspace lock [acquire|release]`. Prints one JSON document; exits 1 on a refusal. */
+export async function runWorkspaceLock(ctx: CommandContext): Promise<number> {
+  const { args } = ctx;
+  const doc = await workspaceLock({
+    cwd: process.cwd(),
+    verb: args.extraPositional,
+    holder: args.holder,
+    ttl: args.ttl,
+    token: args.token,
+    agent: process.env[AGENT_ENV] || undefined,
+  });
+  console.log(JSON.stringify(doc, null, 2));
+  return "error" in doc ? 1 : 0;
+}

package/src/workspace/write-lock.schema.json

@@ -0,0 +1,172 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/chant/schemas/workspace/write-lock/v1/write-lock.schema.json",
+  "title": "chant workspace lock output",
+  "description": "What `chant workspace lock [acquire --holder <name> [--ttl <duration>] | release --token <token>]` prints (#3173, ws-089): who holds the working tree's write lock, the token of a batch that took it, or the reason the command did nothing. Every chant write to the working tree (records new, amend, review and close, points ask and answer, box listing set) holds this lock from its first read to its last write. A batch holds it across chant calls: each call runs with CHANT_WRITE_LOCK=<token> and goes ahead without waiting while the token holds it. 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`.",
+  "oneOf": [
+    {
+      "$ref": "#/$defs/result"
+    },
+    {
+      "$ref": "#/$defs/failure"
+    }
+  ],
+  "$defs": {
+    "result": {
+      "type": "object",
+      "description": "Exit code 0.",
+      "required": [
+        "$schema",
+        "contract",
+        "chant",
+        "verb",
+        "path",
+        "holder"
+      ],
+      "properties": {
+        "$schema": {
+          "const": "https://intentius.io/chant/schemas/workspace/write-lock/v1/write-lock.schema.json"
+        },
+        "contract": {
+          "const": 1
+        },
+        "chant": {
+          "type": "string",
+          "description": "The chant version that printed it."
+        },
+        "verb": {
+          "enum": [
+            "status",
+            "acquire",
+            "release"
+          ]
+        },
+        "path": {
+          "type": "string",
+          "description": "The lock directory: chant-write.lock in the working tree's git directory, or a directory under the system's temporary directory outside git."
+        },
+        "holder": {
+          "$ref": "#/$defs/holder"
+        },
+        "token": {
+          "type": "string",
+          "pattern": "^[0-9a-f]{32}$",
+          "description": "acquire only: the token each write of the batch runs with, as CHANT_WRITE_LOCK, and lock release takes. Never printed by status."
+        },
+        "error": false
+      }
+    },
+    "failure": {
+      "type": "object",
+      "description": "Nothing was done. Exit code 1.",
+      "required": [
+        "$schema",
+        "contract",
+        "chant",
+        "verb",
+        "error",
+        "holder"
+      ],
+      "properties": {
+        "$schema": {
+          "const": "https://intentius.io/chant/schemas/workspace/write-lock/v1/write-lock.schema.json"
+        },
+        "contract": {
+          "const": 1
+        },
+        "chant": {
+          "type": "string"
+        },
+        "verb": {
+          "enum": [
+            "status",
+            "acquire",
+            "release"
+          ]
+        },
+        "error": {
+          "type": "object",
+          "required": [
+            "code",
+            "message"
+          ],
+          "properties": {
+            "code": {
+              "enum": [
+                "write-usage-invalid",
+                "write-lock-timeout",
+                "write-lock-not-held"
+              ]
+            },
+            "message": {
+              "type": "string"
+            }
+          }
+        },
+        "holder": {
+          "$ref": "#/$defs/holder"
+        },
+        "token": false
+      }
+    },
+    "holder": {
+      "description": "Who holds the lock: everything owner.json in the lock directory says but the token.",
+      "oneOf": [
+        {
+          "type": "null"
+        },
+        {
+          "type": "object",
+          "required": [
+            "pid",
+            "host",
+            "verb",
+            "by",
+            "agent",
+            "acquiredAt",
+            "expiresAt"
+          ],
+          "properties": {
+            "pid": {
+              "type": [
+                "integer",
+                "null"
+              ],
+              "description": "The process holding it, or null for a batch held across chant calls."
+            },
+            "host": {
+              "type": "string",
+              "description": "The host the holder runs on."
+            },
+            "verb": {
+              "type": "string",
+              "description": "What holds it: a write command, such as records amend, or batch."
+            },
+            "by": {
+              "type": [
+                "string",
+                "null"
+              ],
+              "description": "Who the write or batch names: --by, or lock acquire's --holder."
+            },
+            "agent": {
+              "type": [
+                "string",
+                "null"
+              ],
+              "description": "The agent session (CHANT_AGENT), or null."
+            },
+            "acquiredAt": {
+              "type": "string",
+              "description": "When it was taken, as an ISO 8601 time."
+            },
+            "expiresAt": {
+              "type": "string",
+              "description": "When any writer may break it, as an ISO 8601 time."
+            }
+          }
+        }
+      ]
+    }
+  }
+}