@intentius/chant 0.91.0 → 0.94.0

package/src/workspace/work-cli.ts

@@ -1,6 +1,8 @@
 /**
  * `chant workspace work claim|renew|release <id> --holder <name>` (#2732,
- * ws-055): the work lease, who is working on which work item.
+ * ws-055): the work lease, who is working on which work item. And `chant
+ * workspace work history <id>` (#2785): the item's lease history, each claim
+ * and how it ended, a read-contract output (`work-history.schema.json`).
  *
  * The lease itself is `../lifecycle/work-lease.ts`, the operator lease under
  * the key `work/<id>`. This file finds the work item first: in the work kind
@@ -24,6 +26,9 @@ import type { CommandContext } from "../cli/registry";
 import { parseDuration } from "../op/duration";
 import {
   claimWorkLease,
+  leaseHistoryPath,
+  listWorkLeases,
+  readLeaseHistory,
   releaseWorkLease,
   renewWorkLease,
   workLeaseRef,
@@ -32,11 +37,13 @@ import {
   type WorkLeaseRefusal,
   type WorkLeaseResult,
   type LeaseHistoryWrite,
+  type LeaseHistoryRecord,
+  type WorkLeaseState,
 } from "../lifecycle/work-lease";
 import { resolveMemberLedger } from "../lifecycle/member-ledger";
-import { WorkspaceReadError } from "./declaration";
+import { readerVersion, WorkspaceReadError } from "./declaration";
 import { declaredKindFiles, readRecordsFor } from "./records-cli";
-import { loadRecordKind, RecordReadError, type LoadedRecordKind } from "./records";
+import { loadRecordKind, RecordReadError, type LoadedRecordKind, type RecordEntry } from "./records";
 import { gitRoot } from "./record-source";
 import type { ReasonCode } from "./reason-codes";
 
@@ -48,7 +55,10 @@ export const WORK_LEASE_OUTPUT_SCHEMA_ID = "https://intentius.io/chant/schemas/w
 
 export { WORK_LEASE_REFUSALS } from "../lifecycle/work-lease";
 
-const USAGE = "chant workspace work claim|renew|release <id> --holder <name> [--kind <kind file>] [--ttl <seconds|duration>] [--token <token>] [--outcome <text>] [--note <text>] [--json]";
+const USAGE = [
+  "chant workspace work claim|renew|release <id> --holder <name> [--kind <kind file>] [--ttl <seconds|duration>] [--token <token>] [--outcome <text>] [--note <text>] [--json]",
+  "chant workspace work history <id> [--kind <kind file>] [--json]",
+].join("\n");
 
 /** Exit code when the lease was refused rather than the command failing. */
 export const EXIT_LEASE_REFUSED = 2;
@@ -94,7 +104,8 @@ export type WorkLeaseDocument = DocHead &
   | { error: { code: WorkErrorCode; message: string } }
   );
 
-class WorkError extends Error {
+/** Why a work command could not run, with its code. */
+export class WorkError extends Error {
   constructor(
     readonly code: WorkErrorCode,
     message: string,
@@ -103,8 +114,19 @@ class WorkError extends Error {
   }
 }
 
-/** The work kind holding `id`: the one `kind` names, or the one declared work kind with a record `id`. */
-async function findWorkItem(id: string, cwd: string, kind: string | undefined): Promise<{ loaded: LoadedRecordKind; state: string | null; root: string }> {
+/** A work item found by id: its kind, its state, its record, and the repository root its path is from. */
+export interface FoundWorkItem {
+  loaded: LoadedRecordKind;
+  state: string | null;
+  record: RecordEntry;
+  root: string;
+}
+
+/**
+ * The work kind holding `id`: the one `kind` names, or the one declared work
+ * kind with a record `id`. Throws a {@link WorkError}.
+ */
+export async function findWorkItem(id: string, cwd: string, kind: string | undefined): Promise<FoundWorkItem> {
   let candidates: string[];
   if (kind !== undefined) {
     candidates = [kind];
@@ -116,7 +138,7 @@ async function findWorkItem(id: string, cwd: string, kind: string | undefined):
       throw new WorkError("work-kind-missing", `${err.code}: ${err.describe()}; without --kind, the declaration names the work kind`);
     }
   }
-  const found: { loaded: LoadedRecordKind; state: string | null; root: string }[] = [];
+  const found: FoundWorkItem[] = [];
   let workKinds = 0;
   for (const file of candidates) {
     let loaded: LoadedRecordKind;
@@ -140,7 +162,7 @@ async function findWorkItem(id: string, cwd: string, kind: string | undefined):
       throw err;
     }
     const record = read.result.records.find((r) => r.id === id);
-    if (record) found.push({ loaded, state: record.state, root: read.root });
+    if (record) found.push({ loaded, state: record.state, record, root: read.root });
   }
   if (workKinds === 0) throw new WorkError("work-kind-missing", "the declaration names no work kind; pass --kind <kind file>");
   if (found.length === 0) throw new WorkError("work-item-unknown", `no work record has the id ${id}`);
@@ -199,16 +221,177 @@ function strip(l: WorkLease): Omit<WorkLease, "item"> {
   return { holder: l.holder, token: l.token, acquiredAt: l.acquiredAt, expiresAt: l.expiresAt };
 }
 
+// ── work history (#2785) ────────────────────────────────────────────────────
+
+/** The version of the `work history` output this chant writes: read contract 1. */
+export const WORK_HISTORY_CONTRACT_VERSION = 1;
+
+/** `$id` of the JSON Schema for `work history --json`, shipped beside this file. */
+export const WORK_HISTORY_OUTPUT_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace/work-history/v1/work-history.schema.json";
+
+/** Why `work history` read nothing. Closed. */
+export const WORK_HISTORY_ERROR_CODES = [
+  "kind-unreadable",
+  "work-kind-missing",
+  "work-kind-ambiguous",
+  "work-item-unknown",
+  "not-a-git-repository",
+] as const satisfies readonly ReasonCode[];
+export type WorkHistoryErrorCode = (typeof WORK_HISTORY_ERROR_CODES)[number];
+
+/**
+ * How a claim ended. `released`: its holder, or someone closing out an
+ * expired lease, gave it back, with an outcome when one was given. `held`: it
+ * is the live lease now. `expired`: it ran out and nobody released it or
+ * claimed the item since. `lost`: it ran out unreleased and another claim
+ * took the item.
+ */
+export type ClaimEnd = "released" | "held" | "expired" | "lost";
+
+/** One claim of a work item: one fencing token, from its claim to how it ended. */
+export interface LeaseClaim {
+  token: string;
+  holder: string;
+  acquiredAt: string;
+  /** The expiry its last claim or renew set. */
+  expiresAt: string;
+  renewals: number;
+  ended: ClaimEnd;
+  /** The release, when it was released. */
+  release: { by: string; at: string; outcome: string | null; note: string | null } | null;
+}
+
+/** What `work history --json` prints. */
+export type WorkHistoryDocument =
+  | {
+      $schema: string;
+      contract: number;
+      chant: string;
+      item: string;
+      /** The work kind file, from the repository root. */
+      kind: string;
+      /** The lease ref. */
+      ref: string;
+      /** The history file on the branch, under the member's prefix when the kind's member has one. */
+      ledger: { branch: string; path: string };
+      /** The lease ref's record now, live or expired, or null when there is none. Read from local refs, without fetching. */
+      lease: (Omit<WorkLease, "item"> & { state: "active" | "expired" }) | null;
+      /** Each claim, oldest first. */
+      claims: LeaseClaim[];
+      /** Every line of the history, oldest first. */
+      events: LeaseHistoryRecord[];
+      /** Lines of the history that are not lease events, left out. */
+      malformed: number;
+      summary: { claims: number; released: number; held: number; expired: number; lost: number; outcomes: Record<string, number> };
+    }
+  | { $schema: string; contract: number; chant: string; error: { code: WorkHistoryErrorCode; message: string } };
+
+/** Fold a history into its claims: one per token, in the order they were first seen. */
+export function claimsOf(events: LeaseHistoryRecord[], live: Pick<WorkLeaseState, "token" | "state"> | null): LeaseClaim[] {
+  const byToken = new Map<string, LeaseClaim>();
+  const order: string[] = [];
+  for (const e of events) {
+    let c = byToken.get(e.token);
+    if (!c) {
+      c = { token: e.token, holder: e.holder, acquiredAt: e.acquiredAt, expiresAt: e.expiresAt, renewals: 0, ended: "expired", release: null };
+      byToken.set(e.token, c);
+      order.push(e.token);
+    }
+    if (e.event === "renew") c.renewals++;
+    if (e.event !== "release") c.expiresAt = e.expiresAt;
+    if (e.event === "release") c.release = { by: e.by, at: e.timestamp, outcome: e.outcome ?? null, note: e.note ?? null };
+  }
+  return order.map((token, i) => {
+    const c = byToken.get(token)!;
+    if (c.release) c.ended = "released";
+    else if (live && live.token === token) c.ended = live.state === "active" ? "held" : "expired";
+    else if (i < order.length - 1) c.ended = "lost";
+    else c.ended = "expired";
+    return c;
+  });
+}
+
+/**
+ * Read work item `id`'s lease history (#2785): every claim, renew and release
+ * on `_leases/<id>.jsonl` in the ledger of the member owning the work kind,
+ * folded into claims. Read from the local `chant/lifecycle` branch and lease
+ * refs; it never fetches, like the other read-contract reads.
+ */
+export async function workHistory(req: { id: string; cwd: string; kind?: string }): Promise<WorkHistoryDocument> {
+  const head = { $schema: WORK_HISTORY_OUTPUT_SCHEMA_ID, contract: WORK_HISTORY_CONTRACT_VERSION, chant: readerVersion() };
+  try {
+    if (!WORK_ITEM_ID_PATTERN.test(req.id) || req.id.includes("..")) throw new WorkError("work-item-unknown", `${JSON.stringify(req.id)} is not a work item id`);
+    if (!gitRoot(req.cwd)) throw new WorkError("not-a-git-repository", "a work lease's history is on the chant/lifecycle branch, and this directory is not in a git repository");
+    const { loaded, root } = await findWorkItem(req.id, req.cwd, req.kind);
+    const leaseCwd = dirname(loaded.file);
+    const { prefix } = await resolveMemberLedger(leaseCwd);
+    const { records: events, malformed } = await readLeaseHistory(req.id, { cwd: leaseCwd });
+    const live = (await listWorkLeases({ cwd: leaseCwd, memberPrefix: prefix })).find((l) => l.item === req.id) ?? null;
+    const claims = claimsOf(events, live);
+    const count = (end: ClaimEnd) => claims.filter((c) => c.ended === end).length;
+    const outcomes: Record<string, number> = {};
+    for (const c of claims) if (c.release?.outcome) outcomes[c.release.outcome] = (outcomes[c.release.outcome] ?? 0) + 1;
+    return {
+      ...head,
+      item: req.id,
+      kind: relative(root, loaded.file).split("\\").join("/"),
+      ref: workLeaseRef(req.id, prefix),
+      ledger: { branch: "chant/lifecycle", path: leaseHistoryPath(req.id, prefix) },
+      lease: live ? { holder: live.holder, token: live.token, acquiredAt: live.acquiredAt, expiresAt: live.expiresAt, state: live.state } : null,
+      claims,
+      events,
+      malformed,
+      summary: { claims: claims.length, released: count("released"), held: count("held"), expired: count("expired"), lost: count("lost"), outcomes },
+    };
+  } catch (err) {
+    if (err instanceof WorkError) return { ...head, error: { code: err.code as WorkHistoryErrorCode, message: err.message } };
+    throw err;
+  }
+}
+
+/** The history as lines for a person. */
+export function formatWorkHistory(doc: Extract<WorkHistoryDocument, { claims: unknown }>): string {
+  const lines = [`${doc.item}: ${doc.ledger.branch}:${doc.ledger.path}`];
+  for (const c of doc.claims) {
+    const how = c.release ? `released${c.release.outcome ? ` ${c.release.outcome}` : ""} by ${c.release.by} at ${c.release.at}` : c.ended === "held" ? `held until ${c.expiresAt}` : `${c.ended}, never released (expired ${c.expiresAt})`;
+    lines.push(`  ${c.acquiredAt}  ${c.holder}  token ${c.token}  ${c.renewals} renewal${c.renewals === 1 ? "" : "s"}  ${how}`);
+  }
+  if (doc.claims.length === 0) lines.push("  never claimed");
+  if (doc.malformed > 0) lines.push(`  ${doc.malformed} malformed line${doc.malformed === 1 ? "" : "s"} left out`);
+  return lines.join("\n");
+}
+
+async function runWorkHistory(ctx: CommandContext): Promise<number> {
+  const { args } = ctx;
+  const id = args.extraPositional2;
+  if (!id) {
+    console.error(formatError({ message: "history needs a work item id", hint: USAGE }));
+    return 1;
+  }
+  for (const [flag, v] of [["--holder", args.holder], ["--ttl", args.ttl], ["--token", args.token], ["--outcome", args.outcome], ["--note", args.note]] as const) {
+    if (v !== undefined) {
+      console.error(formatError({ message: `history is a read and takes no ${flag}`, hint: USAGE }));
+      return 1;
+    }
+  }
+  const doc = await workHistory({ id, cwd: process.cwd(), kind: args.kind });
+  if (args.json) console.log(JSON.stringify(doc, null, 2));
+  else if ("error" in doc) console.error(formatError({ message: `${doc.error.code}: ${doc.error.message}`, hint: USAGE }));
+  else console.log(formatWorkHistory(doc));
+  return "error" in doc ? 1 : 0;
+}
+
 export async function runWorkspaceWork(ctx: CommandContext): Promise<number> {
   const { args } = ctx;
   const verb = args.extraPositional;
+  if (verb === "history") return runWorkHistory(ctx);
   const fail = (message: string): number => {
     if (args.json) console.log(JSON.stringify({ $schema: WORK_LEASE_OUTPUT_SCHEMA_ID, contract: WORK_LEASE_CONTRACT_VERSION, error: { code: "write-usage-invalid", message } }, null, 2));
     else console.error(formatError({ message, hint: USAGE }));
     return 1;
   };
   if (verb !== "claim" && verb !== "renew" && verb !== "release") {
-    return fail(verb ? `chant workspace work takes claim, renew or release, not ${verb}` : "chant workspace work needs claim, renew or release");
+    return fail(verb ? `chant workspace work takes claim, renew, release or history, not ${verb}` : "chant workspace work needs claim, renew, release or history");
   }
   const id = args.extraPositional2;
   if (!id) return fail(`${verb} needs a work item id`);

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

@@ -0,0 +1,212 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/chant/schemas/workspace/work-evidence/v1/work-evidence.schema.json",
+  "title": "workEvidence result",
+  "description": "What attachWorkEvidence, which the workEvidence Op activity runs, returns (#2772): the evidence entry it appended to a work item's acceptance criterion, under the run's work lease, or the reason nothing was written. Version 1. The activity returns the result and fails its step with the refusal's code. 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": {
+      "description": "The entry was appended to the record's pins field, through records amend.",
+      "type": "object",
+      "required": [
+        "$schema",
+        "contract",
+        "item",
+        "kind",
+        "path",
+        "evidence",
+        "acceptance"
+      ],
+      "properties": {
+        "$schema": {
+          "const": "https://intentius.io/chant/schemas/workspace/work-evidence/v1/work-evidence.schema.json"
+        },
+        "contract": {
+          "const": 1
+        },
+        "item": {
+          "type": "string",
+          "description": "The work item's id."
+        },
+        "kind": {
+          "type": "string",
+          "description": "The work kind file, from the repository root."
+        },
+        "path": {
+          "type": "string",
+          "description": "The work record, from the repository root."
+        },
+        "evidence": {
+          "type": "object",
+          "description": "The entry appended: a title, a url or a path pinned by sha256, as_of, and the criterion, its verification, the result and by, the lease holder.",
+          "required": [
+            "title",
+            "criterion",
+            "verification",
+            "result",
+            "by"
+          ],
+          "properties": {
+            "title": {
+              "type": "string"
+            },
+            "url": {
+              "type": "string"
+            },
+            "path": {
+              "type": "string"
+            },
+            "sha256": {
+              "type": "string",
+              "pattern": "^[0-9a-f]{64}$"
+            },
+            "as_of": {
+              "type": "string"
+            },
+            "criterion": {
+              "type": "string"
+            },
+            "verification": {
+              "enum": [
+                "unit",
+                "integration",
+                "e2e",
+                "runtime"
+              ],
+              "description": "The criterion's verification. Never manual: a run under the lease is the implementer."
+            },
+            "result": {
+              "enum": [
+                "pass",
+                "fail"
+              ]
+            },
+            "by": {
+              "type": "string",
+              "description": "The lease holder that attached it."
+            }
+          }
+        },
+        "acceptance": {
+          "type": "object",
+          "description": "The record's criteria with the entry counted, as records --json reports them.",
+          "required": [
+            "met",
+            "total",
+            "criteria"
+          ],
+          "properties": {
+            "met": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "total": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "criteria": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "required": [
+                  "id",
+                  "verification",
+                  "met"
+                ],
+                "properties": {
+                  "id": {
+                    "type": "string"
+                  },
+                  "verification": {
+                    "enum": [
+                      "unit",
+                      "integration",
+                      "e2e",
+                      "runtime",
+                      "manual"
+                    ]
+                  },
+                  "met": {
+                    "type": "boolean"
+                  }
+                }
+              }
+            }
+          }
+        },
+        "error": false
+      }
+    },
+    "failure": {
+      "description": "Nothing was written: the input, the item, the criterion or the lease refused it, or records amend did.",
+      "type": "object",
+      "required": [
+        "$schema",
+        "contract",
+        "error"
+      ],
+      "properties": {
+        "$schema": {
+          "const": "https://intentius.io/chant/schemas/workspace/work-evidence/v1/work-evidence.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-not-found",
+                "amend-id-immutable",
+                "record-closed",
+                "amend-supersede-instead",
+                "record-sign-failed",
+                "record-unparseable",
+                "record-schema-invalid",
+                "record-id-duplicate",
+                "record-supersedes-unknown",
+                "record-supersedes-conflict",
+                "session-seal-mismatch",
+                "session-verdict-unknown-record",
+                "work-kind-missing",
+                "work-kind-ambiguous",
+                "work-item-unknown",
+                "work-item-closed",
+                "work-criterion-unknown",
+                "work-acceptance-self-verified",
+                "lease-held",
+                "lease-not-held",
+                "lease-token-mismatch",
+                "not-a-git-repository"
+              ]
+            },
+            "message": {
+              "type": "string"
+            }
+          }
+        },
+        "evidence": false
+      }
+    }
+  }
+}

package/src/workspace/work-evidence.ts

@@ -0,0 +1,169 @@
+/**
+ * Evidence attached to a work item's acceptance criterion by the run that
+ * holds its lease (#2772).
+ *
+ * A work kind with acceptance criteria (`work.acceptance` in the kind, read in
+ * `./work.ts`) lists what done means on the record: each criterion has an id,
+ * its text and the verification it expects. Evidence in the kind's pins field
+ * meets a criterion when it names it, carries `result: pass` and has the
+ * criterion's verification. {@link attachWorkEvidence} appends one such entry
+ * for a run under the item's work lease (an Op with `workLease`, #2748, such
+ * as a steward's), through `records amend`, so the record is written the way
+ * a person's amendment writes it.
+ *
+ * It writes only for the lease's holder, under the token the run was given:
+ * a run whose lease expired or went to someone else is refused, as a renewal
+ * would be. It refuses a criterion the record doesn't list, and a `manual`
+ * one: the run holding the lease is the item's implementer, and a manual
+ * verdict comes from someone else. A person records that verdict with
+ * `records amend`, naming themselves in `by`.
+ */
+
+import { relative, sep } from "node:path";
+import { activeWorkLeases } from "../lifecycle/work-lease";
+import type { ReasonCode } from "./reason-codes";
+import { pinFile } from "./records-cli";
+import { AMEND_ERROR_CODES, amendRecord } from "./records-write";
+import { acceptanceCriteria, EVIDENCE_RESULTS, workAcceptance, type EvidenceResult, type VerificationType, type WorkAcceptance } from "./work";
+import { findWorkItem, WorkError } from "./work-cli";
+
+/** Why evidence was not attached. Closed. Nothing is written with any of them. */
+export const WORK_EVIDENCE_ERROR_CODES = [
+  ...AMEND_ERROR_CODES,
+  "work-kind-missing",
+  "work-kind-ambiguous",
+  "work-item-unknown",
+  "work-item-closed",
+  "work-criterion-unknown",
+  "work-acceptance-self-verified",
+  "lease-held",
+  "lease-not-held",
+  "lease-token-mismatch",
+  "not-a-git-repository",
+] as const satisfies readonly ReasonCode[];
+export type WorkEvidenceErrorCode = (typeof WORK_EVIDENCE_ERROR_CODES)[number];
+
+export interface AttachWorkEvidenceRequest {
+  /** Where the workspace is found, and what `path` and `kind` resolve against. */
+  cwd: string;
+  /** The work item. */
+  item: string;
+  /** The work kind file, when the declaration names more than one with the item. */
+  kind?: string;
+  /** The lease the run holds: its holder and fencing token. */
+  holder: string;
+  token: string;
+  /** The criterion the evidence is for, by id. */
+  criterion: string;
+  result: EvidenceResult;
+  title: string;
+  /** A public link, or */
+  url?: string;
+  /** a workspace file, pinned by the hash of its bytes now. */
+  path?: string;
+  /** When the evidence was taken, as an ISO 8601 timestamp. Now by default. */
+  asOf?: string;
+}
+
+/** The version of the attach document this chant writes. */
+export const WORK_EVIDENCE_CONTRACT_VERSION = 1;
+
+/** `$id` of the JSON Schema for the attach document, shipped beside this file. */
+export const WORK_EVIDENCE_OUTPUT_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace/work-evidence/v1/work-evidence.schema.json";
+
+interface DocHead {
+  $schema: string;
+  contract: number;
+}
+
+/** What {@link attachWorkEvidence} returns: the entry written, or why nothing was. */
+export type WorkEvidenceDocument = DocHead &
+  (
+    | {
+        item: string;
+        /** The work kind file, from the repository root. */
+        kind: string;
+        /** The record, from the repository root. */
+        path: string;
+        /** The entry appended to the kind's pins field. */
+        evidence: Record<string, unknown>;
+        /** The record's criteria with the new entry counted. */
+        acceptance: WorkAcceptance;
+      }
+    | { error: { code: WorkEvidenceErrorCode; message: string } }
+  );
+
+class EvidenceError extends Error {
+  constructor(
+    readonly code: WorkEvidenceErrorCode,
+    message: string,
+  ) {
+    super(message);
+  }
+}
+
+/** Append one piece of evidence for a criterion to a leased work item. Never throws for a refusal. */
+export async function attachWorkEvidence(req: AttachWorkEvidenceRequest): Promise<WorkEvidenceDocument> {
+  const head = { $schema: WORK_EVIDENCE_OUTPUT_SCHEMA_ID, contract: WORK_EVIDENCE_CONTRACT_VERSION };
+  try {
+    if (typeof req.criterion !== "string" || req.criterion === "") throw new EvidenceError("write-usage-invalid", "the evidence names no criterion");
+    if (!(EVIDENCE_RESULTS as readonly string[]).includes(req.result)) {
+      throw new EvidenceError("write-usage-invalid", `result is pass or fail, not ${JSON.stringify(req.result)}`);
+    }
+    if (typeof req.title !== "string" || req.title.trim() === "") throw new EvidenceError("write-usage-invalid", "the evidence has no title");
+    if ((req.url === undefined) === (req.path === undefined)) throw new EvidenceError("write-usage-invalid", "the evidence is a url or a path, exactly one of them");
+    if (req.url !== undefined && !req.url.startsWith("https://")) throw new EvidenceError("write-input-invalid", `evidence links are https://, not ${JSON.stringify(req.url)}`);
+
+    const found = await findWorkItem(req.item, req.cwd, req.kind);
+    const { kind } = found.loaded;
+    const data = found.record.data;
+    if (found.state !== null && (kind.closedStates ?? []).includes(found.state)) {
+      throw new EvidenceError("work-item-closed", `${req.item} is ${found.state}, a closed state, so no evidence is added to it`);
+    }
+
+    // The lease, as the local refs hold it: the run claimed it here, so they are current.
+    const lease = (await activeWorkLeases(found.loaded.file)).get(req.item);
+    if (!lease) throw new EvidenceError("lease-not-held", `nobody holds a live lease on ${req.item}: it expired, was released or was never claimed`);
+    if (lease.holder !== req.holder) throw new EvidenceError("lease-held", `${lease.holder} holds the lease on ${req.item}, not ${req.holder}`);
+    if (lease.token !== req.token) throw new EvidenceError("lease-token-mismatch", `the lease on ${req.item} carries another token than the one given: it changed hands`);
+
+    const spec = kind.work?.acceptance;
+    if (!spec || !kind.pins) throw new EvidenceError("work-criterion-unknown", `the ${kind.name} kind has no acceptance criteria, so evidence can't name ${req.criterion}`);
+    const criterion = acceptanceCriteria(data, spec.field).find((c) => c.id === req.criterion);
+    if (!criterion) throw new EvidenceError("work-criterion-unknown", `${req.item} lists no acceptance criterion ${req.criterion}`);
+    if (criterion.verification === "manual") {
+      throw new EvidenceError(
+        "work-acceptance-self-verified",
+        `${req.criterion} is verified by a person, and ${req.holder} holds ${req.item}'s lease, so it is the implementer: a manual verdict comes from someone else, with records amend`,
+      );
+    }
+
+    let pin: Record<string, unknown>;
+    if (req.path !== undefined) {
+      const pinned = pinFile(req.path, req.cwd);
+      if ("error" in pinned) throw new EvidenceError("write-input-invalid", pinned.error);
+      pin = { path: pinned.path, sha256: pinned.sha256 };
+    } else {
+      pin = { url: req.url };
+    }
+    const entry: Record<string, unknown> = {
+      title: req.title,
+      ...pin,
+      as_of: req.asOf ?? new Date().toISOString(),
+      criterion: criterion.id,
+      verification: criterion.verification as VerificationType,
+      result: req.result,
+      by: req.holder,
+    };
+    const before = Array.isArray(data?.[kind.pins.field]) ? (data![kind.pins.field] as unknown[]) : [];
+    const evidence = [...before, entry];
+    const amended = await amendRecord({ kind: found.loaded.file, id: req.item, fields: JSON.stringify({ [kind.pins.field]: evidence }), cwd: req.cwd });
+    if ("error" in amended) throw new EvidenceError(amended.error.code, amended.error.message);
+    const { acceptance } = workAcceptance({ ...data, [kind.pins.field]: evidence }, spec, kind.pins.field);
+    const kindPath = relative(found.root, found.loaded.file).split(sep).join("/");
+    return { ...head, item: req.item, kind: kindPath, path: amended.path, evidence: entry, acceptance: acceptance! };
+  } catch (err) {
+    if (err instanceof EvidenceError || err instanceof WorkError) return { ...head, error: { code: err.code, message: err.message } };
+    throw err;
+  }
+}