@intentius/chant 0.90.0 → 0.93.0

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

@@ -0,0 +1,349 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/chant/schemas/workspace/work-history/v1/work-history.schema.json",
+  "title": "chant workspace work history output",
+  "description": "What `chant workspace work history <id> --json` prints (#2785): one work item's lease history, read from _leases/<id>.jsonl on chant/lifecycle in the ledger of the member that owns the work kind, folded into claims, one per fencing token, each with how it ended. A runner counts failed attempts from it. It reads the local branch and lease refs and never fetches. Version 1 of the read contract. 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": {
+    "event": {
+      "type": "object",
+      "description": "One line of the history, as written by a claim, renew or release.",
+      "required": [
+        "version",
+        "event",
+        "item",
+        "holder",
+        "by",
+        "token",
+        "acquiredAt",
+        "expiresAt",
+        "timestamp"
+      ],
+      "properties": {
+        "version": {
+          "const": 1
+        },
+        "event": {
+          "enum": [
+            "claim",
+            "renew",
+            "release"
+          ]
+        },
+        "item": {
+          "type": "string"
+        },
+        "holder": {
+          "type": "string",
+          "description": "The lease's holder."
+        },
+        "by": {
+          "type": "string",
+          "description": "Who wrote the line: the holder, or, for the release of an expired lease, whoever closed it out."
+        },
+        "token": {
+          "type": "string",
+          "description": "The fencing token: new on every claim, kept by every renew."
+        },
+        "acquiredAt": {
+          "type": "string"
+        },
+        "expiresAt": {
+          "type": "string",
+          "description": "The lease's expiry after this event; a release keeps the expiry it had."
+        },
+        "timestamp": {
+          "type": "string",
+          "description": "When the event happened, ISO 8601."
+        },
+        "outcome": {
+          "type": "string",
+          "description": "How the work ended, on a release. Free text such as done, not_done, gated or waiting."
+        },
+        "note": {
+          "type": "string"
+        }
+      }
+    },
+    "claim": {
+      "type": "object",
+      "description": "One claim of the item: one fencing token, from its claim to how it ended.",
+      "required": [
+        "token",
+        "holder",
+        "acquiredAt",
+        "expiresAt",
+        "renewals",
+        "ended",
+        "release"
+      ],
+      "properties": {
+        "token": {
+          "type": "string"
+        },
+        "holder": {
+          "type": "string"
+        },
+        "acquiredAt": {
+          "type": "string"
+        },
+        "expiresAt": {
+          "type": "string",
+          "description": "The expiry its last claim or renew set."
+        },
+        "renewals": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "ended": {
+          "enum": [
+            "released",
+            "held",
+            "expired",
+            "lost"
+          ],
+          "description": "released: given back, with release.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 a later claim took the item."
+        },
+        "release": {
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "type": "object",
+              "required": [
+                "by",
+                "at",
+                "outcome",
+                "note"
+              ],
+              "properties": {
+                "by": {
+                  "type": "string"
+                },
+                "at": {
+                  "type": "string"
+                },
+                "outcome": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                },
+                "note": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                }
+              }
+            }
+          ]
+        }
+      }
+    },
+    "result": {
+      "type": "object",
+      "description": "The history was read. Exit code 0. An item never claimed has no claims.",
+      "required": [
+        "$schema",
+        "contract",
+        "chant",
+        "item",
+        "kind",
+        "ref",
+        "ledger",
+        "lease",
+        "claims",
+        "events",
+        "malformed",
+        "summary"
+      ],
+      "properties": {
+        "$schema": {
+          "const": "https://intentius.io/chant/schemas/workspace/work-history/v1/work-history.schema.json"
+        },
+        "contract": {
+          "const": 1
+        },
+        "chant": {
+          "type": "string"
+        },
+        "item": {
+          "type": "string"
+        },
+        "kind": {
+          "type": "string",
+          "description": "The work kind file, from the repository root."
+        },
+        "ref": {
+          "type": "string",
+          "description": "The lease ref: refs/chant/lease/[_members/<member>/]work/<id>."
+        },
+        "ledger": {
+          "type": "object",
+          "required": [
+            "branch",
+            "path"
+          ],
+          "properties": {
+            "branch": {
+              "const": "chant/lifecycle"
+            },
+            "path": {
+              "type": "string",
+              "description": "The history file on the branch: [_members/<member>/]_leases/<id>.jsonl."
+            }
+          }
+        },
+        "lease": {
+          "description": "The lease ref's record now, live or expired, or null when there is none. Read from the local ref and the remote's as last fetched.",
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "type": "object",
+              "required": [
+                "holder",
+                "token",
+                "acquiredAt",
+                "expiresAt",
+                "state"
+              ],
+              "properties": {
+                "holder": {
+                  "type": "string"
+                },
+                "token": {
+                  "type": "string"
+                },
+                "acquiredAt": {
+                  "type": "string"
+                },
+                "expiresAt": {
+                  "type": "string"
+                },
+                "state": {
+                  "enum": [
+                    "active",
+                    "expired"
+                  ]
+                }
+              }
+            }
+          ]
+        },
+        "claims": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/claim"
+          },
+          "description": "Each claim, oldest first."
+        },
+        "events": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/event"
+          },
+          "description": "Every line of the history, oldest first."
+        },
+        "malformed": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Lines that are not lease events, left out."
+        },
+        "summary": {
+          "type": "object",
+          "required": [
+            "claims",
+            "released",
+            "held",
+            "expired",
+            "lost",
+            "outcomes"
+          ],
+          "properties": {
+            "claims": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "released": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "held": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "expired": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "lost": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "outcomes": {
+              "type": "object",
+              "additionalProperties": {
+                "type": "integer",
+                "minimum": 1
+              },
+              "description": "How many released claims gave each outcome."
+            }
+          }
+        }
+      }
+    },
+    "failure": {
+      "type": "object",
+      "description": "The history could not be read. Exit code 1.",
+      "required": [
+        "$schema",
+        "contract",
+        "chant",
+        "error"
+      ],
+      "properties": {
+        "$schema": {
+          "const": "https://intentius.io/chant/schemas/workspace/work-history/v1/work-history.schema.json"
+        },
+        "contract": {
+          "const": 1
+        },
+        "chant": {
+          "type": "string"
+        },
+        "error": {
+          "type": "object",
+          "required": [
+            "code",
+            "message"
+          ],
+          "properties": {
+            "code": {
+              "enum": [
+                "kind-unreadable",
+                "work-kind-missing",
+                "work-kind-ambiguous",
+                "work-item-unknown",
+                "not-a-git-repository"
+              ]
+            },
+            "message": {
+              "type": "string"
+            }
+          }
+        }
+      }
+    }
+  }
+}

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

@@ -0,0 +1,156 @@
+/**
+ * #2785 — `chant workspace work history <id>`: a work item's lease history,
+ * each claim with how it ended, from the ledger of the member that owns the
+ * work kind, so a runner counts failed builds without reading git itself.
+ */
+
+import { readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { cleanScratch, contract, git, REPO, repo } from "./__fixtures__/contract-repo";
+import { claimWorkLease, releaseWorkLease, renewWorkLease, type LeaseHistoryRecord } from "../lifecycle/work-lease";
+import { claimsOf, formatWorkHistory, workHistory, type WorkHistoryDocument } from "./work-cli";
+import historySchema from "./work-history.schema.json";
+
+const REF = join(REPO, "reference-workspace");
+const { expectValid } = contract(historySchema);
+
+function work(id: string): string {
+  const data = { schema: 1, id, title: `Work ${id}`, state: "open", implements: [], needs: [], constrains: ["path:app/server.mjs"], evidence: [], opened_on: "2026-09-25", source: { kind: "workspace", member: "app" }, supersedes: [] };
+  return `---\n${JSON.stringify(data, null, 2)}\n---\n\n# ${id}\n`;
+}
+
+let root: string;
+let kindDir: string;
+
+beforeAll(() => {
+  // The work kind sits in the design member, so its leases are in that member's ledger.
+  root = repo({
+    "chant.workspace.json": JSON.stringify(
+      {
+        name: "studio",
+        schema: 1,
+        members: [
+          { name: "app", dir: "app", kind: "other", because: "a plain Node server" },
+          { name: "design", dir: "design", kind: "other", because: "records only" },
+        ],
+        records: [{ kind: "design/decisions/decision.kind.mjs" }, { kind: "design/work/work.kind.mjs" }],
+      },
+      null,
+      2,
+    ),
+    "app/server.mjs": "export const port = 8080;\n",
+    "design/decisions/decision.kind.mjs": readFileSync(join(REF, "decisions", "decision.kind.mjs"), "utf-8"),
+    "design/decisions/decision.schema.json": readFileSync(join(REF, "decisions", "decision.schema.json"), "utf-8"),
+    "design/work/work.kind.mjs": readFileSync(join(REF, "work", "work.kind.mjs"), "utf-8"),
+    "design/work/work.schema.json": readFileSync(join(REF, "work", "work.schema.json"), "utf-8"),
+    "design/work/W-001-one.md": work("W-001"),
+    "design/work/W-002-two.md": work("W-002"),
+  });
+  git(root, "config", "user.name", "History Test");
+  git(root, "config", "user.email", "history@example.com");
+  git(root, "add", "-A");
+  git(root, "commit", "-q", "-m", "the queue");
+  kindDir = join(root, "design", "work");
+});
+afterAll(cleanScratch);
+
+const at = (min: number) => () => new Date(Date.UTC(2020, 0, 1, 12, min));
+
+describe("workspace work history (#2785)", () => {
+  test("each claim with its token and holder, and how it ended: released with an outcome, lost, expired or held", async () => {
+    const opts = (min: number) => ({ cwd: kindDir, now: at(min), ttlMs: 10 * 60_000 });
+    // A build that ended not_done.
+    const first = await claimWorkLease("W-001", "steward/dispatch@1", opts(0));
+    if (!first.ok) throw new Error(first.message);
+    await renewWorkLease("W-001", "steward/dispatch@1", { ...opts(3), token: first.lease.token });
+    await releaseWorkLease("W-001", "steward/dispatch@1", { cwd: kindDir, now: at(5), token: first.lease.token, outcome: "not_done" });
+    // A build whose lease ran out unreleased, and another worker then claimed the item.
+    const second = await claimWorkLease("W-001", "steward/dispatch@2", opts(10));
+    if (!second.ok) throw new Error(second.message);
+    const third = await claimWorkLease("W-001", "steward/dispatch@3", opts(30));
+    if (!third.ok) throw new Error(third.message);
+
+    const doc = await workHistory({ id: "W-001", cwd: root });
+    expectValid(doc);
+    if ("error" in doc) throw new Error(doc.error.message);
+    expect(doc).toMatchObject({
+      item: "W-001",
+      kind: "design/work/work.kind.mjs",
+      ref: "refs/chant/lease/_members/design/work/W-001",
+      ledger: { branch: "chant/lifecycle", path: "_members/design/_leases/W-001.jsonl" },
+      malformed: 0,
+    });
+    expect(doc.claims.map((c) => [c.holder, c.token, c.ended, c.renewals, c.release?.outcome ?? null])).toEqual([
+      ["steward/dispatch@1", first.lease.token, "released", 1, "not_done"],
+      ["steward/dispatch@2", second.lease.token, "lost", 0, null],
+      ["steward/dispatch@3", third.lease.token, "expired", 0, null],
+    ]);
+    expect(doc.events.map((e) => e.event)).toEqual(["claim", "renew", "release", "claim", "claim"]);
+    expect(doc.summary).toEqual({ claims: 3, released: 1, held: 0, expired: 1, lost: 1, outcomes: { not_done: 1 } });
+    // The history file is where git would find it, under the member's prefix.
+    expect(git(root, "show", `chant/lifecycle:${doc.ledger.path}`).split("\n")).toHaveLength(5);
+    expect(formatWorkHistory(doc)).toContain("released not_done by steward/dispatch@1");
+  });
+
+  test("a live claim is held, and a done release is counted by outcome", async () => {
+    const now = () => new Date();
+    const done = await claimWorkLease("W-002", "worker-a", { cwd: kindDir, now });
+    if (!done.ok) throw new Error(done.message);
+    await releaseWorkLease("W-002", "worker-a", { cwd: kindDir, now, token: done.lease.token, outcome: "done" });
+    const live = await claimWorkLease("W-002", "worker-b", { cwd: kindDir, now });
+    if (!live.ok) throw new Error(live.message);
+
+    const doc = await workHistory({ id: "W-002", cwd: kindDir, kind: join(kindDir, "work.kind.mjs") });
+    expectValid(doc);
+    if ("error" in doc) throw new Error(doc.error.message);
+    expect(doc.claims.map((c) => c.ended)).toEqual(["released", "held"]);
+    expect(doc.lease).toMatchObject({ holder: "worker-b", token: live.lease.token, state: "active" });
+    expect(doc.summary.outcomes).toEqual({ done: 1 });
+  });
+
+  test("an item never claimed has no claims; an unknown item is an error", async () => {
+    const W3 = join(kindDir, "W-003-three.md");
+    writeFileSync(W3, work("W-003"));
+    try {
+      const none = await workHistory({ id: "W-003", cwd: root });
+      expectValid(none);
+      expect(none).toMatchObject({ claims: [], events: [], lease: null, summary: { claims: 0 } });
+    } finally {
+      rmSync(W3);
+    }
+    const unknown = await workHistory({ id: "W-404", cwd: root });
+    expectValid(unknown);
+    expect(unknown).toMatchObject({ error: { code: "work-item-unknown" } });
+    const bad = await workHistory({ id: "../x", cwd: root });
+    expect((bad as Extract<WorkHistoryDocument, { error: unknown }>).error.code).toBe("work-item-unknown");
+  });
+});
+
+describe("claimsOf", () => {
+  const e = (event: LeaseHistoryRecord["event"], token: string, extra: Partial<LeaseHistoryRecord> = {}): LeaseHistoryRecord => ({
+    version: 1,
+    event,
+    item: "W",
+    holder: `h-${token}`,
+    by: `h-${token}`,
+    token,
+    acquiredAt: "2026-09-25T00:00:00.000Z",
+    expiresAt: "2026-09-25T00:10:00.000Z",
+    timestamp: "2026-09-25T00:00:00.000Z",
+    ...extra,
+  });
+
+  test("a release by someone closing out an expired lease keeps the holder and records who released it", () => {
+    const claims = claimsOf([e("claim", "a"), e("release", "a", { by: "janitor", outcome: "expired" })], null);
+    expect(claims).toEqual([
+      { token: "a", holder: "h-a", acquiredAt: "2026-09-25T00:00:00.000Z", expiresAt: "2026-09-25T00:10:00.000Z", renewals: 0, ended: "released", release: { by: "janitor", at: "2026-09-25T00:00:00.000Z", outcome: "expired", note: null } },
+    ]);
+  });
+
+  test("the live ref decides between held and expired for the newest claim", () => {
+    expect(claimsOf([e("claim", "a")], { token: "a", state: "active" })[0].ended).toBe("held");
+    expect(claimsOf([e("claim", "a")], { token: "a", state: "expired" })[0].ended).toBe("expired");
+    expect(claimsOf([e("claim", "a"), e("claim", "b")], { token: "b", state: "active" }).map((c) => c.ended)).toEqual(["lost", "held"]);
+  });
+});