@intentius/chant 0.89.0 → 0.91.0

package/src/workspace/status-stewards.ts

@@ -0,0 +1,225 @@
+/**
+ * Stewards in `chant workspace status --json` (#2731): which steward runs a
+ * member's operational work, the form it takes in the environment asked for,
+ * its Ops with their schedules, and each Op's last run.
+ *
+ * The steward itself is read from its declaration, the same `*.op.ts` files
+ * `chant operator --steward` reads (`../op/discover.ts`), and only for a member
+ * of kind `chant` that is a chant project of its own (a `chant.config.ts` or
+ * `.json` in its directory), so a member never lists a parent project's
+ * steward. Everything
+ * else is read from the local `chant/lifecycle` branch and refs, never
+ * fetched, as the rest of status is:
+ *
+ * - each Op's last run is the newest record in its run ledger,
+ *   `<env>/runs__<op>.jsonl` under the member's ledger prefix, where `<env>`
+ *   is the Op's own `labels.Env` or `local`;
+ * - `lease` is the local steward's own lease ref
+ *   (`refs/chant/lease/[<prefix>]_stewards/<name>`), present while a
+ *   `chant operator --steward` holds it or until it expires;
+ * - an Op's `workLease.held` is the work leases its turns hold (#2748): those
+ *   whose holder is `<steward>/<op>@...` (`stewardWorkHolder`), read from the
+ *   ledger of the Op's work kind, or the member's own.
+ */
+
+import { existsSync, realpathSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { discoverStewards } from "../op/discover";
+import { stewardFormFor, stewardLeaseName, type StewardForm } from "../op/steward";
+import { readRunLedger, runEnvOf } from "../lifecycle/run-ledger";
+import { leaseRef } from "../lifecycle/lease";
+import { readBlobBySha, readRefSha } from "../lifecycle/git";
+import { resolveMemberLedger } from "../lifecycle/member-ledger";
+import { listWorkLeases } from "../lifecycle/work-lease";
+import { stewardWorkHolder } from "../op/work-lease-run";
+import type { OpConfig } from "../op/types";
+import type { OpRunRecord } from "../op/runtime";
+import type { ReasonCode } from "./reason-codes";
+
+/** Why a member's stewards can't be fully listed. Closed: a new code is a contract change. */
+export const STEWARD_REASON_CODES = [
+  /** An `*.op.ts` file could not be imported, so a steward it declares may be missing. */
+  "stewards-unreadable",
+  /** A steward was dropped: its name, or an Op it lists, belongs to another steward. */
+  "stewards-conflict",
+  /** Reading an Op's run ledger failed, so its last run is null. */
+  "steward-runs-unreadable",
+] as const satisfies readonly ReasonCode[];
+export type StewardReasonCode = (typeof STEWARD_REASON_CODES)[number];
+
+export interface StatusStewardRun {
+  id: string;
+  status: OpRunRecord["status"];
+  started: string;
+  ended: string;
+  /** The gate the run stopped at, for a `gated` run. */
+  gate: { name: string; since: string } | null;
+}
+
+export interface StatusStewardOp {
+  name: string;
+  /** The Op's cadence, or null for an Op the steward runs only when asked. */
+  schedule: { cron: string; overlap: "skip" } | null;
+  /** The environment its runs are recorded under: its `labels.Env`, or `local`. */
+  env: string;
+  /** The newest run in its run ledger, or null when it has none. */
+  lastRun: StatusStewardRun | null;
+  /** Whether the Op changes the checkout, and so runs under a work lease on a branch of its own (#2748). */
+  changesCheckout: boolean;
+  /**
+   * The Op's work lease (#2748), or null when it declares none: the work kind
+   * file whose ledger holds it (null for the member's own), and the leases
+   * the steward's turns of this Op hold, a live one while a turn runs.
+   */
+  workLease: { kind: string | null; held: StatusStewardWorkLease[] } | null;
+}
+
+/** A work lease a steward's turn holds (#2748). */
+export interface StatusStewardWorkLease {
+  item: string;
+  holder: string;
+  token: string;
+  acquiredAt: string;
+  expiresAt: string;
+  state: "active" | "expired";
+}
+
+export interface StatusSteward {
+  name: string;
+  /** The `*.op.ts` file declaring it, relative to the member's directory. */
+  file: string;
+  /** Its form in the environment status was asked for. */
+  form: StewardForm;
+  /** The declared form: a default and the environments that differ from it. */
+  forms: { default: StewardForm; environments: Record<string, StewardForm> };
+  /** The vault the steward holds on Fountain, by name, or null. */
+  vault: string | null;
+  /**
+   * The box capabilities the steward reaches through a broker (#2726), joined
+   * with the member's box block: `broker` is the block's, and `declared` is
+   * false when the block doesn't list the capability (or there is no block).
+   */
+  capabilities: { name: string; broker: string | null; declared: boolean }[];
+  /** The local steward's own lease, or null when no local operator has held it. */
+  lease: { holder: string; acquiredAt: string; expiresAt: string; live: boolean } | null;
+  ops: StatusStewardOp[];
+}
+
+export interface MemberStewards {
+  stewards: StatusSteward[];
+  reasons: { code: StewardReasonCode; message: string }[];
+}
+
+/** Whether a directory is a chant project of its own. */
+function isChantProject(dir: string): boolean {
+  return existsSync(join(dir, "chant.config.ts")) || existsSync(join(dir, "chant.config.json"));
+}
+
+async function readStewardLease(name: string, memberDir: string, now: string): Promise<StatusSteward["lease"]> {
+  try {
+    const { prefix } = await resolveMemberLedger(memberDir);
+    const sha = await readRefSha(leaseRef(stewardLeaseName(name), prefix), { cwd: memberDir });
+    if (!sha) return null;
+    const record = JSON.parse((await readBlobBySha(sha, { cwd: memberDir })) ?? "") as Record<string, unknown>;
+    if (typeof record.holder !== "string" || typeof record.expiresAt !== "string" || typeof record.acquiredAt !== "string") return null;
+    return {
+      holder: record.holder,
+      acquiredAt: record.acquiredAt,
+      expiresAt: record.expiresAt,
+      live: new Date(record.expiresAt).getTime() > new Date(now).getTime(),
+    };
+  } catch {
+    return null;
+  }
+}
+
+/** The work leases `steward`'s turns of `op` hold, from the ledger of the Op's kind or the member's. */
+async function readHeldWorkLeases(steward: string, op: OpConfig, memberDir: string, now: string): Promise<StatusStewardWorkLease[]> {
+  try {
+    const kind = op.workLease?.kind;
+    const cwd = kind ? dirname(resolve(memberDir, kind)) : memberDir;
+    const { prefix } = await resolveMemberLedger(cwd);
+    const mine = stewardWorkHolder(steward, op.name, "");
+    return (await listWorkLeases({ cwd, memberPrefix: prefix, now: new Date(now) }))
+      .filter((l) => l.holder.startsWith(mine))
+      .map((l) => ({ item: l.item, holder: l.holder, token: l.token, acquiredAt: l.acquiredAt, expiresAt: l.expiresAt, state: l.state }));
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * The stewards declared in one member, for `env`. `memberDir` is absolute.
+ * Only a member of kind `chant` with a config of its own is read.
+ */
+export async function readMemberStewards(
+  memberDir: string,
+  env: string,
+  now: string,
+  kind = "chant",
+  box: { capabilities: { name: string; broker: string | null }[] } | null = null,
+): Promise<MemberStewards> {
+  const reasons: MemberStewards["reasons"] = [];
+  if (kind !== "chant" || !isChantProject(memberDir)) return { stewards: [], reasons };
+
+  let discovered: Awaited<ReturnType<typeof discoverStewards>>;
+  try {
+    discovered = await discoverStewards({ cwd: memberDir });
+  } catch (err) {
+    reasons.push({ code: "stewards-unreadable", message: err instanceof Error ? err.message.split("\n")[0] : String(err) });
+    return { stewards: [], reasons };
+  }
+  const { stewards: found, errors, conflicts } = discovered;
+  for (const message of errors) reasons.push({ code: "stewards-unreadable", message });
+  for (const message of conflicts) reasons.push({ code: "stewards-conflict", message });
+
+  const stewards: StatusSteward[] = [];
+  for (const { declaration, filePath } of [...found.values()].sort((a, b) => a.declaration.name.localeCompare(b.declaration.name))) {
+    const ops: StatusStewardOp[] = [];
+    for (const op of declaration.ops) {
+      const opEnv = runEnvOf(op);
+      let lastRun: StatusStewardRun | null = null;
+      try {
+        const newest = (await readRunLedger(opEnv, op.name, { cwd: memberDir })).records.at(-1);
+        if (newest) {
+          lastRun = {
+            id: newest.id,
+            status: newest.status,
+            started: newest.started,
+            ended: newest.ended,
+            gate: newest.gate ? { name: newest.gate.name, since: newest.gate.since } : null,
+          };
+        }
+      } catch (err) {
+        reasons.push({
+          code: "steward-runs-unreadable",
+          message: `${opEnv}/runs__${op.name}.jsonl: ${err instanceof Error ? err.message.split("\n")[0] : String(err)}`,
+        });
+      }
+      ops.push({
+        name: op.name,
+        schedule: op.schedule ? { cron: op.schedule.cron, overlap: "skip" } : null,
+        env: opEnv,
+        lastRun,
+        changesCheckout: op.changesCheckout === true,
+        workLease: op.workLease
+          ? { kind: op.workLease.kind ?? null, held: await readHeldWorkLeases(declaration.name, op, memberDir, now) }
+          : null,
+      });
+    }
+    stewards.push({
+      name: declaration.name,
+      file: relative(realpathSync(memberDir), realpathSync(filePath)).split("\\").join("/"),
+      form: stewardFormFor(declaration, env),
+      forms: { default: declaration.form.default, environments: { ...declaration.form.environments } },
+      vault: typeof declaration.vault === "string" ? declaration.vault : null,
+      capabilities: (Array.isArray(declaration.capabilities) ? declaration.capabilities : []).map((name) => {
+        const declared = box?.capabilities.find((c) => c.name === name);
+        return { name, broker: declared?.broker ?? null, declared: declared !== undefined };
+      }),
+      lease: await readStewardLease(declaration.name, memberDir, now),
+      ops,
+    });
+  }
+  return { stewards, reasons };
+}

package/src/workspace/status.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://intentius.io/chant/schemas/workspace/status/v1/status.schema.json",
   "title": "chant workspace status output",
-  "description": "What `chant workspace status <env> --json` prints, version 1 of the read contract for releases across members (#2524 D15, D19, #2544). Readers ignore fields they do not know; a field is only ever added within a version. The reason and error codes are closed lists: a new code is a new contract version. Contract version 1 is written by chant 0.81.0 and newer; a reader that needs it refuses output whose `contract` it doesn't know. Every code is in the one closed list of `reason-codes.ts`. Each member's gates, read from its gate ledger on the same branch, are in the JSON only (#2674).",
+  "description": "What `chant workspace status <env> --json` prints, version 1 of the read contract for releases across members (#2524 D15, D19, #2544). Readers ignore fields they do not know; a field is only ever added within a version. The reason and error codes are closed lists: a new code is a new contract version. Contract version 1 is written by chant 0.81.0 and newer; a reader that needs it refuses output whose `contract` it doesn't know. Every code is in the one closed list of `reason-codes.ts`. Each member's gates, read from its gate ledger on the same branch, are in the JSON only (#2674), and so is each member's box block, from the declaration (#2726), with its isolation resolved (#2727). So are its stewards, their Ops and each Op's last run (#2731), and the work lease each Op's turn holds (#2748).",
   "oneOf": [{ "$ref": "#/$defs/result" }, { "$ref": "#/$defs/failure" }],
   "$defs": {
     "result": {
@@ -45,6 +45,11 @@
           "type": "array",
           "items": { "$ref": "#/$defs/member" }
         },
+        "leases": {
+          "description": "Added in contract 1 by #2732. Every work lease (chant workspace work claim) in the flat ledger and each member's, active and expired, by member (flat first) and then item. Read from the local lease refs, refs/chant/lease/[_members/<member>/]work/<id> and the remote's as last fetched; the command never fetches. A released lease has no ref and is not listed; its history is _leases/<id>.jsonl on chant/lifecycle.",
+          "type": "array",
+          "items": { "$ref": "#/$defs/lease" }
+        },
         "summary": {
           "type": "object",
           "required": ["members", "released", "unreadable", "differing"],
@@ -61,13 +66,27 @@
         }
       }
     },
+    "lease": {
+      "type": "object",
+      "required": ["item", "member", "ref", "holder", "token", "acquiredAt", "expiresAt", "state"],
+      "properties": {
+        "item": { "type": "string", "description": "The work item's id." },
+        "member": { "type": ["string", "null"], "description": "The member whose ledger holds the lease: the one owning the work kind file, or null for the flat ledger." },
+        "ref": { "type": "string", "description": "The lease ref, refs/chant/lease/work/<id> or refs/chant/lease/_members/<member>/work/<id>." },
+        "holder": { "type": "string" },
+        "token": { "type": "string", "description": "The fencing token: new on every claim, kept by every renew." },
+        "acquiredAt": { "type": "string" },
+        "expiresAt": { "type": "string" },
+        "state": { "enum": ["active", "expired"], "description": "expired once expiresAt has passed: the item can be claimed again, with a new token." }
+      }
+    },
     "env": {
       "type": "string",
       "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$"
     },
     "member": {
       "type": "object",
-      "required": ["name", "dir", "kind", "environments", "compare", "readable", "gateLedger", "gates"],
+      "required": ["name", "dir", "kind", "environments", "compare", "readable", "gateLedger", "gates", "box", "stewards", "stewardReasons"],
       "properties": {
         "name": { "type": "string" },
         "dir": { "type": "string", "description": "Relative to the workspace root, with / separators; \".\" is the root member." },
@@ -85,10 +104,213 @@
         },
         "readable": { "type": "boolean", "description": "True exactly when no environment has a reason. A gate ledger reason doesn't change it." },
         "gateLedger": { "$ref": "#/$defs/gateLedger" },
+        "box": {
+          "description": "The member's box block from the declaration (#2726), or null when it declares none. A broker reads the scopes it enforces here, and chant workspace check fails on a capability with a null broker (WSP122).",
+          "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/box" }]
+        },
         "gates": {
           "description": "Each gate the member's gate ledger records, one per gate and environment, for env and compareTo. A gate that records no environment (an Op gate) is listed whatever the environment. Sorted by component, then gate. Empty when gateLedger has a reason.",
           "type": "array",
           "items": { "$ref": "#/$defs/gate" }
+        },
+        "stewards": {
+          "description": "The stewards the member declares in its *.op.ts files (#2731), sorted by name. Empty for a member that is not of kind chant, or has no chant.config.ts or .json in its own directory.",
+          "type": "array",
+          "items": { "$ref": "#/$defs/steward" }
+        },
+        "stewardReasons": {
+          "description": "Why a steward or an Op's last run may be missing from stewards. Empty when every one was read.",
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["code", "message"],
+            "properties": {
+              "code": { "enum": ["stewards-unreadable", "stewards-conflict", "steward-runs-unreadable"] },
+              "message": { "type": "string" }
+            }
+          }
+        }
+      }
+    },
+    "stewardForm": { "enum": ["local", "fountain"] },
+    "steward": {
+      "type": "object",
+      "required": ["name", "file", "form", "forms", "vault", "capabilities", "lease", "ops"],
+      "properties": {
+        "name": { "type": "string", "description": "The steward's name; on Fountain, its Agent's and Teammate's." },
+        "file": { "type": "string", "description": "The *.op.ts file that declares it, relative to the member's directory." },
+        "form": { "$ref": "#/$defs/stewardForm", "description": "Its form in env: fountain (the fountain lexicon's Agent and Teammate) or local (chant operator --steward in the box)." },
+        "forms": {
+          "type": "object",
+          "required": ["default", "environments"],
+          "properties": {
+            "default": { "$ref": "#/$defs/stewardForm" },
+            "environments": {
+              "description": "The environments whose form differs from default.",
+              "type": "object",
+              "additionalProperties": { "$ref": "#/$defs/stewardForm" }
+            }
+          }
+        },
+        "vault": { "type": ["string", "null"], "description": "The vault the steward holds on Fountain, by name, or null. Never set when capabilities is non-empty." },
+        "capabilities": {
+          "description": "The box capabilities the steward reaches through a broker (#2726), in declaration order, joined with the member's box block. broker is the block's; declared is false when the block doesn't list the capability or the member has no block.",
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["name", "broker", "declared"],
+            "properties": {
+              "name": { "type": "string" },
+              "broker": { "type": ["string", "null"] },
+              "declared": { "type": "boolean" }
+            }
+          }
+        },
+        "lease": {
+          "description": "The local steward's own lease ref, read locally and never fetched, or null when no local operator has held it. live is false once expiresAt has passed.",
+          "oneOf": [
+            { "type": "null" },
+            {
+              "type": "object",
+              "required": ["holder", "acquiredAt", "expiresAt", "live"],
+              "properties": {
+                "holder": { "type": "string" },
+                "acquiredAt": { "type": "string" },
+                "expiresAt": { "type": "string" },
+                "live": { "type": "boolean" }
+              }
+            }
+          ]
+        },
+        "ops": {
+          "description": "The Ops it runs, in declaration order.",
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["name", "schedule", "env", "lastRun", "changesCheckout", "workLease"],
+            "properties": {
+              "name": { "type": "string" },
+              "schedule": {
+                "description": "The Op's cadence, or null for an Op the steward runs only when asked.",
+                "oneOf": [
+                  { "type": "null" },
+                  {
+                    "type": "object",
+                    "required": ["cron", "overlap"],
+                    "properties": { "cron": { "type": "string" }, "overlap": { "const": "skip" } }
+                  }
+                ]
+              },
+              "env": { "type": "string", "description": "The environment its runs are recorded under: its labels.Env, or local." },
+              "lastRun": {
+                "description": "The newest record in the Op's run ledger on chant/lifecycle, or null when it has none.",
+                "oneOf": [
+                  { "type": "null" },
+                  {
+                    "type": "object",
+                    "required": ["id", "status", "started", "ended", "gate"],
+                    "properties": {
+                      "id": { "type": "string" },
+                      "status": { "enum": ["ok", "fail", "gated"] },
+                      "started": { "type": "string" },
+                      "ended": { "type": "string" },
+                      "gate": {
+                        "oneOf": [
+                          { "type": "null" },
+                          { "type": "object", "required": ["name", "since"], "properties": { "name": { "type": "string" }, "since": { "type": "string" } } }
+                        ]
+                      }
+                    }
+                  }
+                ]
+              },
+              "changesCheckout": { "type": "boolean", "description": "Whether the Op changes the checkout, and so runs under a work lease on a branch of its own, chant/work/<item> (#2748)." },
+              "workLease": {
+                "description": "The Op's work lease (#2748), or null when it declares none. kind is the work kind file whose ledger holds it, relative to the member, or null for the member's own ledger. held is the work leases the steward's turns of this Op hold (holder <steward>/<op>@<process>), read locally and never fetched: an active one while a turn runs, an expired one left by a turn that stopped renewing.",
+                "oneOf": [
+                  { "type": "null" },
+                  {
+                    "type": "object",
+                    "required": ["kind", "held"],
+                    "properties": {
+                      "kind": { "type": ["string", "null"] },
+                      "held": {
+                        "type": "array",
+                        "items": {
+                          "type": "object",
+                          "required": ["item", "holder", "token", "acquiredAt", "expiresAt", "state"],
+                          "properties": {
+                            "item": { "type": "string" },
+                            "holder": { "type": "string" },
+                            "token": { "type": "string" },
+                            "acquiredAt": { "type": "string" },
+                            "expiresAt": { "type": "string" },
+                            "state": { "enum": ["active", "expired"] }
+                          }
+                        }
+                      }
+                    }
+                  }
+                ]
+              }
+            }
+          }
+        }
+      }
+    },
+    "box": {
+      "type": "object",
+      "required": ["capabilities", "isolation"],
+      "properties": {
+        "isolation": {
+          "description": "The box's isolation resolved from its identity, its host, the member's name and its slot (#2727), or null when the block declares no host. A runtime that plants or starts the box sets these values instead of choosing its own. The same for every environment.",
+          "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/isolation" }]
+        },
+        "capabilities": {
+          "description": "Each capability the box reaches through a broker, in declaration order.",
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["name", "broker", "scope"],
+            "properties": {
+              "name": { "type": "string", "description": "The capability, such as inference or fountain." },
+              "broker": { "type": ["string", "null"], "description": "What brokers it, such as lobby, or null when the declaration names none." },
+              "scope": { "type": "array", "items": { "type": "string" }, "description": "What of the box's own the broker lets it reach, such as agent, vault, conversations and sandboxes. Empty when none is declared." }
+            }
+          }
+        }
+      }
+    },
+    "isolation": {
+      "type": "object",
+      "required": ["host", "slot", "portRange", "ports", "stateDir", "state", "cookies"],
+      "properties": {
+        "host": { "type": "string", "description": "The host the box runs on. Boxes on different hosts share nothing." },
+        "slot": { "type": "integer", "minimum": 0 },
+        "portRange": {
+          "type": "object",
+          "description": "The box's block of its host's range, inclusive: from + slot * perBox to from + (slot + 1) * perBox - 1.",
+          "required": ["from", "to"],
+          "properties": {
+            "from": { "type": "integer", "minimum": 1, "maximum": 65535 },
+            "to": { "type": "integer", "minimum": 1, "maximum": 65535 }
+          }
+        },
+        "ports": {
+          "type": "object",
+          "description": "Each declared port's number: the block's first port plus the port's offset.",
+          "additionalProperties": { "type": "integer", "minimum": 1, "maximum": 65535 }
+        },
+        "stateDir": { "type": "string", "description": "<stateRoot>/<member name>. Its environment reference, such as ${XDG_STATE_HOME}, is left for the runtime to expand." },
+        "state": {
+          "type": "object",
+          "description": "Each declared state entry's path under stateDir, keyed as declared, such as HUD_IDENTITY_PATH.",
+          "additionalProperties": { "type": "string" }
+        },
+        "cookies": {
+          "type": "object",
+          "description": "Each declared cookie's name for this box: <cookie>_<member name>.",
+          "additionalProperties": { "type": "string" }
         }
       }
     },
@@ -191,7 +413,7 @@
     },
     "release": {
       "type": "object",
-      "required": ["component", "digest", "gitSha", "inputDigest", "runId", "timestamp", "actor", "flags"],
+      "required": ["component", "digest", "gitSha", "inputDigest", "runId", "timestamp", "actor", "flags", "plan"],
       "properties": {
         "component": { "type": "string" },
         "digest": { "type": "string", "description": "The artifact digest the release deployed." },
@@ -200,7 +422,11 @@
         "runId": { "type": "string" },
         "timestamp": { "type": "string" },
         "actor": { "type": "string" },
-        "flags": { "type": "array", "items": { "enum": ["legacy-digest"] } }
+        "flags": { "type": "array", "items": { "enum": ["legacy-digest"] } },
+        "plan": {
+          "type": ["object", "null"],
+          "description": "The release plan digest names, read from _plans/<digest>.json on chant/lifecycle (ws-055, #2733): the work items and evidence this release shipped. Null when this checkout has no plan stored under that digest — most releases carry no plan, and a plan not yet fetched also reads null."
+        }
       }
     },
     "compare": {