@intentius/chant 0.91.0 → 0.93.0

package/src/workspace/status-gates.ts

@@ -103,9 +103,14 @@ export const defaultGateLedgerReader: GateLedgerReader = async (dir, commit, cwd
   return files;
 };
 
-/** The exact `chant approve` line for a gate. */
-export function approveCommand(component: string, gate: string, env: string | null): string {
-  return `chant approve ${component} ${gate}${env !== null ? ` --env ${env}` : ""}`;
+/**
+ * The exact `chant approve` line for a gate. A gate bound to a plan (#2300)
+ * gets `--plan <digest>` too (#2832), so running the line back approves the
+ * plan this read showed and not whatever happens to be pending by the time
+ * someone runs it.
+ */
+export function approveCommand(component: string, gate: string, env: string | null, planDigest?: string | null): string {
+  return `chant approve ${component} ${gate}${env !== null ? ` --env ${env}` : ""}${planDigest ? ` --plan ${planDigest}` : ""}`;
 }
 
 const approvalOf = (r: GateResolutionRecord): StatusGateApproval => ({ principal: r.resolvedBy, channel: r.origin ?? null, at: r.timestamp });
@@ -150,7 +155,7 @@ function decide(component: string, standing: PendingGateRecord, resolutions: Gat
     expiresAt: standing.expiresAt,
     approvals: approvals.map(approvalOf),
     needed,
-    approve: approveCommand(component, gate, env),
+    approve: approveCommand(component, gate, env, planDigest),
   };
 }
 

package/src/workspace/status-stewards.ts

@@ -14,6 +14,9 @@
  * - 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`;
+ * - `waiting` lists the open decision points the steward waits on (#2749):
+ *   each Op whose newest run is the steward's own and stopped on a question,
+ *   as the run ledger records it. The question's state now is `points`'s;
  * - `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;
@@ -27,6 +30,7 @@ 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 { readConvergeLedger, type ConvergeTickRecord } from "../lifecycle/converge-ledger";
 import { leaseRef } from "../lifecycle/lease";
 import { readBlobBySha, readRefSha } from "../lifecycle/git";
 import { resolveMemberLedger } from "../lifecycle/member-ledger";
@@ -34,6 +38,7 @@ 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 { approveCommand } from "./status-gates";
 import type { ReasonCode } from "./reason-codes";
 
 /** Why a member's stewards can't be fully listed. Closed: a new code is a contract change. */
@@ -42,7 +47,7 @@ export const STEWARD_REASON_CODES = [
   "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. */
+  /** Reading an Op's run ledger, or a ConvergeOp's converge ledger, failed, so its last run or last tick is null. */
   "steward-runs-unreadable",
 ] as const satisfies readonly ReasonCode[];
 export type StewardReasonCode = (typeof STEWARD_REASON_CODES)[number];
@@ -52,8 +57,48 @@ export interface StatusStewardRun {
   status: OpRunRecord["status"];
   started: string;
   ended: string;
-  /** The gate the run stopped at, for a `gated` run. */
-  gate: { name: string; since: string } | null;
+  /**
+   * The gate the run stopped at, for a `gated` run: its name, when the run
+   * stopped there, the op it is recorded under (the Op's own, or the
+   * command's for a step whose command stopped at its own gate, #2779, such
+   * as `workspace-upgrade`), and the command that approves it.
+   */
+  gate: { name: string; since: string; op: string; approve: string } | null;
+  /** The open decision point the run stopped on, for a `waiting` run (#2749). */
+  point: StatusStewardWait | null;
+}
+
+/** An open decision point a steward's run stopped on (#2749), as the run ledger records it. */
+export interface StatusStewardWait {
+  /** The answer record's id: what `points --open` lists and `points answer` names. */
+  id: string;
+  point: string;
+  /** The question's state when the run stopped. */
+  state: "escalated" | "proposed";
+  path: string;
+  subject: string | null;
+  since: string;
+}
+
+/** A ConvergeOp's newest tick on the converge ledger (#2778). */
+export interface StatusStewardTick {
+  /** The tick's id, or null for a tick recorded before ticks had ids. */
+  id: string | null;
+  timestamp: string;
+  /** The tick's one log line. */
+  log: string;
+  /** Every rule that fired. */
+  firedRuleIds: string[];
+  /** What each fired rule did, and for which resource on a ConvergeOp with an observer step. */
+  outcomes: {
+    ruleId: string;
+    action: ConvergeTickRecord["outcomes"][number]["action"];
+    op: string | null;
+    resource: string | null;
+    reason: string | null;
+  }[];
+  /** What the observer step reported, or null for a ConvergeOp that observes a lexicon environment. */
+  resources: { name: string; status: "in-sync" | "drifted" | "unknown"; detail: string | null }[] | null;
 }
 
 export interface StatusStewardOp {
@@ -64,6 +109,8 @@ export interface StatusStewardOp {
   env: string;
   /** The newest run in its run ledger, or null when it has none. */
   lastRun: StatusStewardRun | null;
+  /** For a ConvergeOp, its newest tick on the converge ledger (#2778); null for any other Op, or before its first tick. */
+  lastTick: StatusStewardTick | null;
   /** Whether the Op changes the checkout, and so runs under a work lease on a branch of its own (#2748). */
   changesCheckout: boolean;
   /**
@@ -103,6 +150,11 @@ export interface StatusSteward {
   /** 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[];
+  /**
+   * The open decision points the steward waits on (#2749): each Op whose
+   * newest run is the steward's own and stopped on a question.
+   */
+  waiting: (StatusStewardWait & { op: string; run: string })[];
 }
 
 export interface MemberStewards {
@@ -110,6 +162,39 @@ export interface MemberStewards {
   reasons: { code: StewardReasonCode; message: string }[];
 }
 
+function waitOf(p: NonNullable<OpRunRecord["point"]>): StatusStewardWait {
+  return {
+    id: p.id,
+    point: p.point,
+    state: p.state === "proposed" ? "proposed" : "escalated",
+    path: p.path,
+    subject: p.subject ?? null,
+    since: p.since,
+  };
+}
+
+function gateOf(g: NonNullable<OpRunRecord["gate"]>, opName: string): NonNullable<StatusStewardRun["gate"]> {
+  const op = g.op ?? opName;
+  return { name: g.name, since: g.since, op, approve: approveCommand(op, g.name, null) };
+}
+
+function tickOf(t: ConvergeTickRecord): StatusStewardTick {
+  return {
+    id: t.id ?? null,
+    timestamp: t.timestamp,
+    log: t.log,
+    firedRuleIds: [...t.firedRuleIds],
+    outcomes: t.outcomes.map((o) => ({
+      ruleId: o.ruleId,
+      action: o.action,
+      op: o.op ?? null,
+      resource: o.resource ?? null,
+      reason: o.reason ?? null,
+    })),
+    resources: t.resources ? t.resources.map((r) => ({ name: r.name, status: r.status, detail: r.detail ?? null })) : null,
+  };
+}
+
 /** 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"));
@@ -176,6 +261,7 @@ export async function readMemberStewards(
   const stewards: StatusSteward[] = [];
   for (const { declaration, filePath } of [...found.values()].sort((a, b) => a.declaration.name.localeCompare(b.declaration.name))) {
     const ops: StatusStewardOp[] = [];
+    const waiting: StatusSteward["waiting"] = [];
     for (const op of declaration.ops) {
       const opEnv = runEnvOf(op);
       let lastRun: StatusStewardRun | null = null;
@@ -187,8 +273,12 @@ export async function readMemberStewards(
             status: newest.status,
             started: newest.started,
             ended: newest.ended,
-            gate: newest.gate ? { name: newest.gate.name, since: newest.gate.since } : null,
+            gate: newest.gate ? gateOf(newest.gate, op.name) : null,
+            point: newest.point ? waitOf(newest.point) : null,
           };
+          if (newest.status === "waiting" && lastRun.point && newest.steward === declaration.name) {
+            waiting.push({ op: op.name, run: newest.id, ...lastRun.point });
+          }
         }
       } catch (err) {
         reasons.push({
@@ -196,11 +286,24 @@ export async function readMemberStewards(
           message: `${opEnv}/runs__${op.name}.jsonl: ${err instanceof Error ? err.message.split("\n")[0] : String(err)}`,
         });
       }
+      let lastTick: StatusStewardTick | null = null;
+      if (op.labels?.Converge === "true") {
+        try {
+          const newest = (await readConvergeLedger(opEnv, { cwd: memberDir })).records.filter((r) => r.op === op.name).at(-1);
+          if (newest) lastTick = tickOf(newest);
+        } catch (err) {
+          reasons.push({
+            code: "steward-runs-unreadable",
+            message: `${opEnv}/converge.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,
+        lastTick,
         changesCheckout: op.changesCheckout === true,
         workLease: op.workLease
           ? { kind: op.workLease.kind ?? null, held: await readHeldWorkLeases(declaration.name, op, memberDir, now) }
@@ -219,6 +322,7 @@ export async function readMemberStewards(
       }),
       lease: await readStewardLease(declaration.name, memberDir, now),
       ops,
+      waiting,
     });
   }
   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), 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).",
+  "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), the work lease each Op's turn holds (#2748), and the open decision points a steward waits on (#2749).",
   "oneOf": [{ "$ref": "#/$defs/result" }, { "$ref": "#/$defs/failure" }],
   "$defs": {
     "result": {
@@ -50,6 +50,11 @@
           "type": "array",
           "items": { "$ref": "#/$defs/lease" }
         },
+        "acceptance": {
+          "description": "Added in contract 1 by #2772. Each current work item of a declared work kind whose work block names acceptance criteria, when the item lists some, by declared kind and then item, read in the working tree: how many of its criteria passing evidence meets. Empty when no declared work kind has criteria. A done item with a criterion unmet is what chant workspace check fails on (WSP117).",
+          "type": "array",
+          "items": { "$ref": "#/$defs/acceptance" }
+        },
         "summary": {
           "type": "object",
           "required": ["members", "released", "unreadable", "differing"],
@@ -66,6 +71,18 @@
         }
       }
     },
+    "acceptance": {
+      "type": "object",
+      "required": ["member", "kind", "item", "state", "met", "total"],
+      "properties": {
+        "member": { "type": ["string", "null"], "description": "The member that declares the work kind, or null for the workspace's own." },
+        "kind": { "type": "string", "description": "The work kind file, from the workspace root." },
+        "item": { "type": "string", "description": "The work item's id." },
+        "state": { "type": ["string", "null"], "description": "The item's state." },
+        "met": { "type": "integer", "minimum": 0, "description": "Criteria met by evidence naming them, with result pass and the criterion's verification; a manual verdict counts only from someone other than the implementer." },
+        "total": { "type": "integer", "minimum": 0, "description": "Criteria the item lists." }
+      }
+    },
     "lease": {
       "type": "object",
       "required": ["item", "member", "ref", "holder", "token", "acquiredAt", "expiresAt", "state"],
@@ -135,7 +152,7 @@
     "stewardForm": { "enum": ["local", "fountain"] },
     "steward": {
       "type": "object",
-      "required": ["name", "file", "form", "forms", "vault", "capabilities", "lease", "ops"],
+      "required": ["name", "file", "form", "forms", "vault", "capabilities", "lease", "ops", "waiting"],
       "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." },
@@ -187,7 +204,7 @@
           "type": "array",
           "items": {
             "type": "object",
-            "required": ["name", "schedule", "env", "lastRun", "changesCheckout", "workLease"],
+            "required": ["name", "schedule", "env", "lastRun", "lastTick", "changesCheckout", "workLease"],
             "properties": {
               "name": { "type": "string" },
               "schedule": {
@@ -208,16 +225,77 @@
                   { "type": "null" },
                   {
                     "type": "object",
-                    "required": ["id", "status", "started", "ended", "gate"],
+                    "required": ["id", "status", "started", "ended", "gate", "point"],
                     "properties": {
                       "id": { "type": "string" },
-                      "status": { "enum": ["ok", "fail", "gated"] },
+                      "status": { "enum": ["ok", "fail", "gated", "waiting"], "description": "waiting: an activity asked a decision point that is still open (#2749), and the run stopped there." },
                       "started": { "type": "string" },
                       "ended": { "type": "string" },
                       "gate": {
                         "oneOf": [
                           { "type": "null" },
-                          { "type": "object", "required": ["name", "since"], "properties": { "name": { "type": "string" }, "since": { "type": "string" } } }
+                          {
+                            "type": "object",
+                            "required": ["name", "since"],
+                            "properties": {
+                              "name": { "type": "string" },
+                              "since": { "type": "string" },
+                              "op": { "type": "string", "description": "The op the gate is recorded under: the Op's own, or the command's when a step's command stopped at a gate of its own (#2779), such as workspace-upgrade." },
+                              "approve": { "type": "string", "description": "The command that approves the gate, run in the member's directory." }
+                            }
+                          }
+                        ]
+                      },
+                      "point": {
+                        "description": "The open decision point a waiting run stopped on (#2749), as the run ledger records it, or null.",
+                        "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/stewardWait" }]
+                      }
+                    }
+                  }
+                ]
+              },
+              "lastTick": {
+                "description": "For a ConvergeOp, its newest tick on the converge ledger (#2778): the rules that fired, what each did and for which resource, and what its observer step reported. null for any other Op, or before its first tick.",
+                "oneOf": [
+                  { "type": "null" },
+                  {
+                    "type": "object",
+                    "required": ["id", "timestamp", "log", "firedRuleIds", "outcomes", "resources"],
+                    "properties": {
+                      "id": { "type": ["string", "null"] },
+                      "timestamp": { "type": "string" },
+                      "log": { "type": "string" },
+                      "firedRuleIds": { "type": "array", "items": { "type": "string" } },
+                      "outcomes": {
+                        "type": "array",
+                        "items": {
+                          "type": "object",
+                          "required": ["ruleId", "action", "op", "resource", "reason"],
+                          "properties": {
+                            "ruleId": { "type": "string" },
+                            "action": { "enum": ["ran", "reported", "skipped-budget", "skipped-flap", "gated"] },
+                            "op": { "type": ["string", "null"] },
+                            "resource": { "type": ["string", "null"], "description": "The resource the rule fired for, on a ConvergeOp with an observer step." },
+                            "reason": { "type": ["string", "null"] }
+                          }
+                        }
+                      },
+                      "resources": {
+                        "description": "What the observer step reported, or null for a ConvergeOp that observes a lexicon environment.",
+                        "oneOf": [
+                          { "type": "null" },
+                          {
+                            "type": "array",
+                            "items": {
+                              "type": "object",
+                              "required": ["name", "status", "detail"],
+                              "properties": {
+                                "name": { "type": "string" },
+                                "status": { "enum": ["in-sync", "drifted", "unknown"] },
+                                "detail": { "type": ["string", "null"] }
+                              }
+                            }
+                          }
                         ]
                       }
                     }
@@ -255,9 +333,35 @@
               }
             }
           }
+        },
+        "waiting": {
+          "description": "The open decision points the steward waits on (#2749): one for each of its Ops whose newest run is the steward's own and stopped on a question, in ops order. The state is the question's when the run stopped; `chant workspace points --open` has its state now, and hud asks a person there. The steward never answers one, and runs the Op again on the first round after it is answered.",
+          "type": "array",
+          "items": {
+            "allOf": [
+              { "$ref": "#/$defs/stewardWait" },
+              {
+                "type": "object",
+                "required": ["op", "run"],
+                "properties": { "op": { "type": "string" }, "run": { "type": "string", "description": "The waiting run's id." } }
+              }
+            ]
+          }
         }
       }
     },
+    "stewardWait": {
+      "type": "object",
+      "required": ["id", "point", "state", "path", "subject", "since"],
+      "properties": {
+        "id": { "type": "string", "description": "The answer record's id, as `points` lists the question and `points answer` names it." },
+        "point": { "type": "string" },
+        "state": { "enum": ["escalated", "proposed"] },
+        "path": { "type": "string", "description": "The answer record, from the repository root." },
+        "subject": { "type": ["string", "null"] },
+        "since": { "type": "string", "description": "When the run stopped on it." }
+      }
+    },
     "box": {
       "type": "object",
       "required": ["capabilities", "isolation"],
@@ -371,7 +475,7 @@
           }
         },
         "needed": { "type": "integer", "minimum": 1, "description": "The human approvals the gate needs: its quorum's count, 1 without one." },
-        "approve": { "type": "string", "description": "The chant approve line for the gate, run in the member's directory: chant approve <component> <gate>, with --env <env> when env is not null." }
+        "approve": { "type": "string", "description": "The chant approve line for the gate, run in the member's directory: chant approve <component> <gate>, with --env <env> when env is not null and --plan <planDigest> when planDigest is not null (#2832), so the line approves the plan this read showed." }
       }
     },
     "environment": {

package/src/workspace/status.ts

@@ -43,7 +43,7 @@ import { readReleasePlan, type ReleasePlan } from "../lifecycle/plan-ledger";
 import { listWorkLeases, type WorkLeaseState } from "../lifecycle/work-lease";
 import { findWorkspaceRoot } from "../project-root";
 import { resolveBoxes, type ResolvedIsolation } from "./box-isolation";
-import { readDeclaration, readerVersion, WorkspaceReadError, type ErrorLocation, type Member } from "./declaration";
+import { declaredRecordKinds, readDeclaration, readerVersion, WorkspaceReadError, type Declaration, type ErrorLocation, type Member } from "./declaration";
 import type { ReasonCode } from "./reason-codes";
 import { GATE_REASON_CODES, readMemberGates, type GateLedgerReader, type StatusGate, type StatusGateLedger } from "./status-gates";
 import { STEWARD_REASON_CODES, readMemberStewards, type StatusSteward, type StewardReasonCode } from "./status-stewards";
@@ -190,6 +190,21 @@ export interface StatusLease extends Omit<WorkLeaseState, "ref"> {
   ref: string;
 }
 
+/**
+ * One work item's acceptance criteria, counted (#2772): each current record
+ * of a declared work kind with acceptance criteria that lists some.
+ */
+export interface StatusAcceptance {
+  /** The member that declares the work kind, or null for the workspace's own. */
+  member: string | null;
+  /** The work kind file, from the workspace root. */
+  kind: string;
+  item: string;
+  state: string | null;
+  met: number;
+  total: number;
+}
+
 export type StatusDocument =
   | {
       $schema: string;
@@ -202,6 +217,8 @@ export type StatusDocument =
       members: StatusMember[];
       /** Every work lease in the workspace's ledgers, active and expired, by member then item (#2732). A released lease has no ref and is not listed. */
       leases: StatusLease[];
+      /** Each work item's acceptance criteria, met of total, by declared kind then item (#2772). Empty when no declared work kind has criteria. */
+      acceptance: StatusAcceptance[];
       summary: { members: number; released: number; unreadable: number; differing: number | null };
     }
   | {
@@ -395,6 +412,7 @@ export async function workspaceStatus(query: StatusQuery): Promise<StatusDocumen
     for (const m of members) m.gateLedger.shared = m.gateLedger.layout === "flat" && flatGates > 1;
 
     const leases = await readWorkspaceLeases(declaration.members, found.dir, new Date(now));
+    const acceptance = await readWorkspaceAcceptance(declaration, found.dir);
 
     return {
       ...head,
@@ -404,6 +422,7 @@ export async function workspaceStatus(query: StatusQuery): Promise<StatusDocumen
       workspace: { name: declaration.name, root: rootDir === "" ? "." : rootDir, file: declaration.file },
       members,
       leases,
+      acceptance,
       summary: {
         members: members.length,
         released: members.filter((m) => m.environments[0].releases.length > 0).length,
@@ -436,6 +455,16 @@ async function readWorkspaceLeases(members: Member[], cwd: string, now: Date): P
   return out;
 }
 
+/** The acceptance counts of every declared work kind with criteria (#2772), read in the working tree. */
+async function readWorkspaceAcceptance(declaration: Declaration, root: string): Promise<StatusAcceptance[]> {
+  if (declaredRecordKinds(declaration).length === 0) return [];
+  const { loadDeclaredKinds } = await import("./declared-kinds");
+  const kinds = await loadDeclaredKinds(declaration, workingTree(root), root, { acceptance: true });
+  return kinds.flatMap((k) =>
+    (k.acceptance ?? []).map((a) => ({ member: k.declared.member, kind: k.declared.path, item: a.item, state: a.state, met: a.met, total: a.total })),
+  );
+}
+
 export async function runWorkspaceStatus(ctx: CommandContext): Promise<number> {
   const { args } = ctx;
   const env = args.extraPositional;
@@ -525,6 +554,12 @@ export function formatStatus(doc: Extract<StatusDocument, { members: unknown }>)
     for (const l of doc.leases) rows.push([l.member ? `${l.member}/${l.item}` : l.item, l.holder, l.expiresAt, l.state]);
     lines.push(...table(rows));
   }
+  if (doc.acceptance.length > 0) {
+    lines.push("");
+    const rows: string[][] = [["WORK ITEM", "STATE", "CRITERIA MET"]];
+    for (const a of doc.acceptance) rows.push([a.member ? `${a.member}/${a.item}` : a.item, a.state ?? "-", `${a.met}/${a.total}`]);
+    lines.push(...table(rows));
+  }
   const boxes = doc.members.filter((m) => m.box?.isolation);
   if (boxes.length > 0) {
     lines.push("");