@intentius/chant 0.90.0 → 0.93.0

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), 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": {
@@ -45,6 +45,16 @@
           "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" }
+        },
+        "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"],
@@ -61,13 +71,39 @@
         }
       }
     },
+    "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"],
+      "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 +121,300 @@
         },
         "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", "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." },
+        "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", "lastTick", "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", "point"],
+                    "properties": {
+                      "id": { "type": "string" },
+                      "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" },
+                              "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"] }
+                              }
+                            }
+                          }
+                        ]
+                      }
+                    }
+                  }
+                ]
+              },
+              "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"] }
+                          }
+                        }
+                      }
+                    }
+                  }
+                ]
+              }
+            }
+          }
+        },
+        "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"],
+      "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" }
         }
       }
     },
@@ -149,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": {
@@ -191,7 +517,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 +526,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": {