@intentius/chant 0.124.13 → 0.124.14

package/dist/workspace/work-lease.schema.json

@@ -0,0 +1,246 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/chant/schemas/workspace/work-lease/v1/work-lease.schema.json",
+  "title": "chant workspace work output",
+  "description": "What `chant workspace work claim|renew|release <id> --holder <name> --json` prints (#2732, ws-055): the work lease it wrote, the reason it was refused, or the reason the command could not run. Version 1 of the write contract for work leases. The lease is the ref refs/chant/lease/[_members/<member>/]work/<id>; each write also appends to _leases/<id>.jsonl on chant/lifecycle. Readers ignore fields they do not know; a field is only ever added within a version. The refusal and error codes are closed lists, each in the one closed list of `reason-codes.ts`. A release's --outcome is one of the closed list `$defs/outcome` (#3147); any other value is refused with write-usage-invalid.",
+  "oneOf": [
+    {
+      "$ref": "#/$defs/result"
+    },
+    {
+      "$ref": "#/$defs/refusal"
+    },
+    {
+      "$ref": "#/$defs/failure"
+    }
+  ],
+  "$defs": {
+    "outcome": {
+      "description": "How a work lease ended, as a release records it on _leases/<id>.jsonl (#3147). Closed: a new outcome is a contract change. done: the work was finished. not_done: a build ran and did not finish, or the run failed; counts as an attempt. abandoned: an expired lease closed out by someone other than its holder; counts as an attempt. gated: the run stopped at a gate. waiting: the run stopped on a decision point's open question. dropped: the item was dropped, such as by a refuse at the understand point. redraft and ask: the understand point sent the item back to its author. Only not_done and abandoned count toward an item's attempt limit.",
+      "enum": [
+        "done",
+        "not_done",
+        "abandoned",
+        "gated",
+        "waiting",
+        "dropped",
+        "redraft",
+        "ask"
+      ]
+    },
+    "lease": {
+      "type": "object",
+      "required": [
+        "holder",
+        "token",
+        "acquiredAt",
+        "expiresAt"
+      ],
+      "properties": {
+        "holder": {
+          "type": "string",
+          "description": "Who holds the lease, as --holder gave it."
+        },
+        "token": {
+          "type": "string",
+          "description": "The fencing token: new on every claim, kept by every renew."
+        },
+        "acquiredAt": {
+          "type": "string",
+          "description": "When the lease was claimed, ISO 8601."
+        },
+        "expiresAt": {
+          "type": "string",
+          "description": "When the lease expires unless renewed, ISO 8601."
+        }
+      }
+    },
+    "result": {
+      "description": "The lease was written. Exit code 0.",
+      "type": "object",
+      "required": [
+        "$schema",
+        "contract",
+        "item",
+        "event",
+        "kind",
+        "ref",
+        "lease",
+        "history"
+      ],
+      "properties": {
+        "$schema": {
+          "const": "https://intentius.io/chant/schemas/workspace/work-lease/v1/work-lease.schema.json"
+        },
+        "contract": {
+          "const": 1
+        },
+        "item": {
+          "type": "string",
+          "description": "The work item's id."
+        },
+        "event": {
+          "enum": [
+            "claim",
+            "renew",
+            "release"
+          ]
+        },
+        "kind": {
+          "type": "string",
+          "description": "The work kind file, relative to the repository root, with / separators."
+        },
+        "ref": {
+          "type": "string",
+          "description": "The lease ref, in the ledger of the member owning the work kind."
+        },
+        "lease": {
+          "description": "The lease after a claim or renew; the lease that was given back after a release.",
+          "$ref": "#/$defs/lease"
+        },
+        "history": {
+          "type": "object",
+          "required": [
+            "path",
+            "commit",
+            "pushed"
+          ],
+          "properties": {
+            "path": {
+              "type": "string",
+              "description": "The history file on chant/lifecycle, _leases/<id>.jsonl under the member's prefix."
+            },
+            "commit": {
+              "type": "string",
+              "description": "The chant/lifecycle commit that appended the line."
+            },
+            "pushed": {
+              "type": "boolean",
+              "description": "Whether chant/lifecycle reached the remote. False with no remote, and when the remote refused it; the lease stands either way."
+            }
+          }
+        },
+        "refused": false,
+        "error": false
+      }
+    },
+    "refusal": {
+      "description": "The lease was refused. Exit code 2. Nothing was written.",
+      "type": "object",
+      "required": [
+        "$schema",
+        "contract",
+        "item",
+        "event",
+        "kind",
+        "ref",
+        "refused"
+      ],
+      "properties": {
+        "$schema": {
+          "const": "https://intentius.io/chant/schemas/workspace/work-lease/v1/work-lease.schema.json"
+        },
+        "contract": {
+          "const": 1
+        },
+        "item": {
+          "type": "string",
+          "description": "The work item's id."
+        },
+        "event": {
+          "enum": [
+            "claim",
+            "renew",
+            "release"
+          ]
+        },
+        "kind": {
+          "type": "string",
+          "description": "The work kind file, relative to the repository root, with / separators."
+        },
+        "ref": {
+          "type": "string",
+          "description": "The lease ref, in the ledger of the member owning the work kind."
+        },
+        "refused": {
+          "type": "object",
+          "required": [
+            "code",
+            "message",
+            "heldBy"
+          ],
+          "properties": {
+            "code": {
+              "enum": [
+                "lease-held",
+                "lease-not-held",
+                "lease-token-mismatch",
+                "lease-race",
+                "lease-push-rejected"
+              ]
+            },
+            "message": {
+              "type": "string",
+              "description": "Names the holder when someone holds the lease."
+            },
+            "heldBy": {
+              "description": "The live lease, when there is one.",
+              "oneOf": [
+                {
+                  "type": "null"
+                },
+                {
+                  "$ref": "#/$defs/lease"
+                }
+              ]
+            }
+          }
+        },
+        "lease": false,
+        "error": false
+      }
+    },
+    "failure": {
+      "description": "The command could not run. Exit code 1. Nothing was written.",
+      "type": "object",
+      "required": [
+        "$schema",
+        "contract",
+        "error"
+      ],
+      "properties": {
+        "$schema": {
+          "const": "https://intentius.io/chant/schemas/workspace/work-lease/v1/work-lease.schema.json"
+        },
+        "contract": {
+          "const": 1
+        },
+        "error": {
+          "type": "object",
+          "required": [
+            "code",
+            "message"
+          ],
+          "properties": {
+            "code": {
+              "enum": [
+                "write-usage-invalid",
+                "kind-unreadable",
+                "work-kind-missing",
+                "work-kind-ambiguous",
+                "work-item-unknown",
+                "work-item-closed",
+                "not-a-git-repository"
+              ]
+            },
+            "message": {
+              "type": "string"
+            }
+          }
+        },
+        "lease": false,
+        "refused": false
+      }
+    }
+  }
+}

package/dist/workspace/work-size.js

@@ -0,0 +1,77 @@
+/**
+ * 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, path) {
+    let at = value;
+    for (const part of path.split(".")) {
+        if (at === null || typeof at !== "object" || !Object.prototype.hasOwnProperty.call(at, part))
+            return undefined;
+        at = at[part];
+    }
+    return at;
+}
+/** The limits when the work kind declares none. */
+export const DEFAULT_TIER_LIMITS = Object.freeze({
+    small: { criteria: 10, files: 5, words: 150 },
+    medium: { criteria: 20, files: 10, words: 300 },
+});
+const HEADING = /^\s*#/;
+const PATH_LIKE = /^[\w@.-]+(\/[\w@.*-]+)+\/?$|^[\w@-][\w@.-]*\.[a-z]{1,5}$/i;
+const str = (v) => (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, body, acceptanceField = "acceptance") {
+    const d = data ?? {};
+    const acceptance = Array.isArray(d[acceptanceField]) ? d[acceptanceField] : [];
+    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?.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, limit) {
+    if (!limit)
+        return false;
+    return ["criteria", "files", "words"].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, limits = DEFAULT_TIER_LIMITS) {
+    const out = { 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/dist/workspace/work.js

@@ -0,0 +1,283 @@
+/**
+ * Work items on read (#2683): a record kind with a `work` block.
+ *
+ * A work item is a record in the workspace, a git-tracked file with its
+ * dependencies written inside it, that people and agents share as one queue
+ * with no server. Most work items come from a gap the intent graph already
+ * reports (`source.finding`), given an id, an owner and a lifecycle.
+ *
+ * `records.ts` calls {@link applyWork} after it has read a work kind's
+ * records, before it sets `valid` and applies `--current`. This module reads
+ * the decision kind the work kind names, at the same revision, and gives each
+ * work record:
+ *
+ * - `ready`: its state is the kind's open state, every need is done, and the
+ *   record is valid and not superseded;
+ * - `blockedBy`: each need that is not done, with its state;
+ * - `implements`: each decision it names, with that decision's state;
+ * - `acceptance`, for a kind with acceptance criteria (#2772): how many of the
+ *   record's criteria passing evidence of the expected verification meets;
+ * - `contract`, for a kind with a contract link (#3147): the contract record
+ *   the item builds, with its state, read from the contract kind at the same
+ *   revision;
+ *
+ * and each decision `implementedBy`, the work records naming it. The
+ * warnings are closed codes. `work-done-gap-open` is not raised here: it
+ * takes a walk of the item's region, which `graph --intent` makes and
+ * `records` asks it for (#2686). It never writes a record.
+ */
+import { dirname } from "node:path";
+import { loadRecordKind, normalisePrincipal, readRecords } from "./records.js";
+/** Why a work record carries a warning. Closed, like the record warning codes. */
+export const WORK_WARNING_CODES = [
+    /** A `needs` entry names a work id no record has. */
+    "work-needs-unknown",
+    /** An `implements` entry names a decision id no decision has. */
+    "work-implements-unknown",
+    /** The record needs itself through its `needs` links, so it can never be ready. */
+    "work-needs-cycle",
+    /** The record implements a decision whose state is not approved, such as proposed or withdrawn. */
+    "work-implements-undecided",
+    /** The record is done and its evidence list is empty: nothing shows the work was done. */
+    "work-done-unpinned",
+    /** The record is in a closed state and has no closing date. */
+    "work-closed-without-date",
+    /** The record is done, and the finding it came from (`source.finding`) still fires on its region. Raised by `graph --intent`, and by `records` through a walk of that region (#2686). */
+    "work-done-gap-open",
+    /** The record is done, and an acceptance criterion has no passing evidence of the verification it expects (#2772). `check` fails on it (WSP117). */
+    "work-acceptance-unmet",
+    /** A passing `manual` verdict on a criterion names the record's implementer, so it does not count: a manual verdict comes from someone else (#2772). */
+    "work-acceptance-self-verified",
+    /** The record names a contract no record of the kind's contract kind has (#3147). */
+    "work-contract-unknown",
+    /** The record names a contract whose state is not approved, such as a draft (#3147). */
+    "work-contract-undecided",
+    /** The record names a builder tier its kind's `work.tier.tiers` does not list (#3147). */
+    "work-tier-unknown",
+];
+/**
+ * The answers about each work item: every answer record whose `constrains`
+ * names the item's id, in path order, by item id.
+ */
+export function workAnswers(answerRecords, ids) {
+    const out = new Map();
+    for (const id of ids)
+        out.set(id, []);
+    for (const a of answerRecords) {
+        if (a.id === null || a.data === null)
+            continue;
+        for (const target of idList(a.data, "constrains")) {
+            const list = out.get(target);
+            if (!list || list.some((x) => x.id === a.id))
+                continue;
+            const answer = a.data.answer;
+            list.push({
+                id: a.id,
+                point: typeof a.data.point === "string" ? a.data.point : null,
+                state: a.state,
+                answer: typeof answer === "string" || typeof answer === "boolean" ? answer : null,
+                answeredBy: idList(a.data, "answered_by"),
+            });
+        }
+    }
+    return out;
+}
+/** How a criterion is to be verified (#2772): by a unit, integration or end-to-end test, by the running system, or by a person. */
+export const VERIFICATION_TYPES = ["unit", "integration", "e2e", "runtime", "manual"];
+/** The results a piece of evidence for a criterion can carry. */
+export const EVIDENCE_RESULTS = ["pass", "fail"];
+/** The acceptance criteria a record lists in `field`, leaving out entries without a string id and a known verification (the schema reports those). */
+export function acceptanceCriteria(data, field) {
+    const v = data?.[field];
+    if (!Array.isArray(v))
+        return [];
+    return v.filter((c) => c !== null && typeof c === "object" && typeof c.id === "string" && typeof c.text === "string" && VERIFICATION_TYPES.includes(c.verification));
+}
+/**
+ * Which of a record's criteria its evidence meets. Evidence meets a criterion
+ * when it names the criterion, its result is `pass` and its verification is
+ * the criterion's. A `manual` verdict also names who gave it in `by`, and
+ * counts only when that is not the record's implementer; one that is lands in
+ * `selfVerified`. `acceptance` is null when the record lists no criteria.
+ */
+export function workAcceptance(data, spec, pinsField) {
+    if (!Array.isArray(data?.[spec.field]))
+        return { acceptance: null, selfVerified: [] };
+    const criteria = acceptanceCriteria(data, spec.field);
+    const implementer = typeof data?.[spec.implementer] === "string" ? normalisePrincipal(data[spec.implementer]) : null;
+    const evidence = Array.isArray(data?.[pinsField]) ? data[pinsField] : [];
+    const selfVerified = [];
+    const states = criteria.map((c) => {
+        let met = false;
+        for (const e of evidence) {
+            if (e === null || typeof e !== "object")
+                continue;
+            const ev = e;
+            if (ev.criterion !== c.id || ev.result !== "pass" || ev.verification !== c.verification)
+                continue;
+            if (c.verification === "manual") {
+                if (typeof ev.by !== "string")
+                    continue;
+                if (implementer !== null && normalisePrincipal(ev.by) === implementer) {
+                    if (!selfVerified.includes(c.id))
+                        selfVerified.push(c.id);
+                    continue;
+                }
+            }
+            met = true;
+        }
+        return { id: c.id, verification: c.verification, met };
+    });
+    return { acceptance: { met: states.filter((c) => c.met).length, total: states.length, criteria: states }, selfVerified };
+}
+/** The strings of a front-matter list, or none. */
+export function idList(data, field) {
+    const v = data?.[field];
+    return Array.isArray(v) ? v.filter((x) => typeof x === "string") : [];
+}
+/**
+ * Whether `state` counts as decided in the decision kind: ranked above 0 by
+ * its approval ranks, or, for a kind without them, closed.
+ */
+export function isDecided(kind, state) {
+    if (state === null)
+        return false;
+    return kind.approval ? (kind.approval[state] ?? 0) > 0 : (kind.closedStates ?? []).includes(state);
+}
+/**
+ * Give each work record its links, ready and blockedBy, and its warnings, in
+ * place. Throws a `RecordReadError` when the decision kind can't be read.
+ */
+export async function applyWork(loaded, entries, options) {
+    const { kind } = loaded;
+    const work = kind.work;
+    const decisionsKind = await loadRecordKind(work.decisions, dirname(loaded.file));
+    const decisionRead = await readRecords(decisionsKind, { root: options.root, source: options.source });
+    const decisionById = new Map();
+    for (const d of decisionRead.records)
+        if (d.id !== null && !decisionById.has(d.id))
+            decisionById.set(d.id, d);
+    const byId = new Map();
+    for (const e of entries)
+        if (e.id !== null && !byId.has(e.id))
+            byId.set(e.id, e);
+    const closed = new Set(kind.closedStates);
+    // The contract kind a work item names its contract in (#3147), read at the same revision.
+    let contracts;
+    if (work.contract) {
+        const contractKind = await loadRecordKind(work.contract.kind, dirname(loaded.file));
+        const contractRead = await readRecords(contractKind, { root: options.root, source: options.source });
+        const contractById = new Map();
+        for (const c of contractRead.records)
+            if (c.id !== null && !contractById.has(c.id))
+                contractById.set(c.id, c);
+        contracts = { kind: contractKind, byId: contractById };
+    }
+    // Records in a needs cycle: those that reach themselves.
+    const inCycle = new Set();
+    for (const start of byId.keys()) {
+        const seen = new Set();
+        const stack = [...idList(byId.get(start).data, work.needs)];
+        while (stack.length > 0) {
+            const id = stack.pop();
+            if (id === start) {
+                inCycle.add(start);
+                break;
+            }
+            if (seen.has(id))
+                continue;
+            seen.add(id);
+            stack.push(...idList(byId.get(id)?.data ?? null, work.needs));
+        }
+    }
+    const implementedBy = new Map();
+    for (const e of entries) {
+        if (e.data === null)
+            continue;
+        const needs = idList(e.data, work.needs);
+        const implementsIds = idList(e.data, work.implements);
+        e.blockedBy = needs.filter((n) => byId.get(n)?.state !== work.done).map((n) => ({ id: n, state: byId.get(n)?.state ?? null }));
+        e.implements = implementsIds.map((d) => ({ id: d, state: decisionById.get(d)?.state ?? null }));
+        e.ready = e.state === work.open && e.blockedBy.length === 0 && e.reasons.length === 0 && e.supersededBy === null && !(e.id !== null && inCycle.has(e.id));
+        // An open item has no proof yet, so the kind's empty-evidence warning is
+        // replaced by work-done-unpinned, which only a done item gets.
+        e.warnings = e.warnings.filter((w) => w.code !== "record-no-evidence");
+        const unknownNeeds = needs.filter((n) => !byId.has(n));
+        if (unknownNeeds.length > 0) {
+            e.warnings.push({ code: "work-needs-unknown", message: `needs ${unknownNeeds.join(", ")}, which no work record has, so the item stays blocked` });
+        }
+        const unknownDecisions = implementsIds.filter((d) => !decisionById.has(d));
+        if (unknownDecisions.length > 0) {
+            e.warnings.push({ code: "work-implements-unknown", message: `implements ${unknownDecisions.join(", ")}, which no decision in ${work.decisions} has` });
+        }
+        if (e.id !== null && inCycle.has(e.id)) {
+            e.warnings.push({ code: "work-needs-cycle", message: `${e.id} needs itself through its needs links, so it can never be ready` });
+        }
+        const undecided = e.implements.filter((d) => d.state !== null && !isDecided(decisionsKind.kind, d.state));
+        if (undecided.length > 0) {
+            e.warnings.push({
+                code: "work-implements-undecided",
+                message: `implements ${undecided.map((d) => `${d.id}, which is ${d.state}`).join("; ")}: the work may carry out a choice nobody has made`,
+            });
+        }
+        const evidence = kind.pins ? e.data[kind.pins.field] : undefined;
+        if (e.state === work.done && kind.pins && !(Array.isArray(evidence) && evidence.length > 0)) {
+            e.warnings.push({ code: "work-done-unpinned", message: `${e.id ?? e.path} is ${work.done} and ${kind.pins.field} is empty or missing: nothing shows the work was done` });
+        }
+        if (work.acceptance && kind.pins) {
+            const { acceptance, selfVerified } = workAcceptance(e.data, work.acceptance, kind.pins.field);
+            e.acceptance = acceptance;
+            if (selfVerified.length > 0) {
+                e.warnings.push({
+                    code: "work-acceptance-self-verified",
+                    message: `the manual verdict on ${selfVerified.join(", ")} is by ${String(e.data[work.acceptance.implementer])}, the implementer, so it does not count: a manual verdict comes from someone else`,
+                });
+            }
+            const unmet = acceptance?.criteria.filter((c) => !c.met) ?? [];
+            if (e.state === work.done && unmet.length > 0) {
+                e.warnings.push({
+                    code: "work-acceptance-unmet",
+                    message: `${e.id ?? e.path} is ${work.done}, and no passing evidence meets ${unmet.map((c) => `${c.id} (${c.verification})`).join(", ")}`,
+                });
+            }
+        }
+        if (contracts && work.contract) {
+            const named = e.data[work.contract.field];
+            if (typeof named === "string" && named !== "") {
+                const c = contracts.byId.get(named);
+                e.contract = { id: named, state: c?.state ?? null };
+                if (!c) {
+                    e.warnings.push({ code: "work-contract-unknown", message: `names the contract ${named}, which no record in ${work.contract.kind} has` });
+                }
+                else if (!isDecided(contracts.kind.kind, c.state)) {
+                    e.warnings.push({ code: "work-contract-undecided", message: `names the contract ${named}, which is ${c.state ?? "in no state"}: the work may build a contract nobody approved` });
+                }
+            }
+            else {
+                e.contract = null;
+            }
+        }
+        if (work.tier) {
+            const tier = e.data[work.tier.field];
+            if (typeof tier === "string" && !work.tier.tiers.includes(tier)) {
+                e.warnings.push({ code: "work-tier-unknown", message: `names the builder tier ${tier}, which the kind's tiers (${work.tier.tiers.join(", ")}) do not list` });
+            }
+        }
+        if (e.state !== null && closed.has(e.state) && typeof e.data[work.closedOn] !== "string") {
+            e.warnings.push({ code: "work-closed-without-date", message: `${e.id ?? e.path} is ${e.state} and has no ${work.closedOn}` });
+        }
+        if (e.id !== null && byId.get(e.id) === e) {
+            for (const d of implementsIds) {
+                const list = implementedBy.get(d) ?? [];
+                if (!list.some((x) => x.id === e.id))
+                    list.push({ id: e.id, state: e.state });
+                implementedBy.set(d, list);
+            }
+        }
+    }
+    return {
+        decisions: decisionRead.records
+            .filter((d) => d.id !== null && decisionById.get(d.id) === d)
+            .map((d) => ({ id: d.id, path: d.path, state: d.state, supersededBy: d.supersededBy, implementedBy: implementedBy.get(d.id) ?? [] })),
+    };
+}