@intentius/chant 0.124.13 → 0.124.15

package/dist/workspace/status.schema.json

@@ -0,0 +1,998 @@
+{
+  "$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), 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": {
+    "boxShip": {
+      "type": "object",
+      "patternProperties": { "^x-": { "description": "Added in contract 1 by #3595. An x- key the declaration holds on this object, with its value as written." } },
+      "additionalProperties": false,
+      "required": ["op", "gate", "env", "bookkeeping", "serving", "pending"],
+      "properties": {
+        "op": { "type": "string", "description": "The Op in the box member that commits the staged tree and releases it." },
+        "gate": { "type": "string", "description": "The gate the Op stops at for a person's approval." },
+        "env": { "type": "string", "description": "The environment whose release ledger, under the box member, the Op records each release in." },
+        "bookkeeping": { "type": "array", "items": { "type": "string" }, "description": "Path prefixes from the workspace root whose changes never count as waiting to ship." },
+        "serving": {
+          "description": "The latest release in env's ledger, the commit the box's site serves, or null when nothing has shipped or the ledger can't be read.",
+          "oneOf": [
+            { "type": "null" },
+            {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["commit", "digest", "component", "at", "actor"],
+              "properties": {
+                "commit": { "type": "string" },
+                "digest": { "type": "string" },
+                "component": { "type": "string" },
+                "at": { "type": "string" },
+                "actor": { "type": ["string", "null"] }
+              }
+            }
+          ]
+        },
+        "pending": {
+          "description": "What is waiting to ship: the files that differ between serving.commit and the working tree, tracked or untracked and not ignored, bookkeeping left out. paths is sorted and lists at most 200. Null when nothing has shipped or the serving commit isn't in this checkout.",
+          "oneOf": [
+            { "type": "null" },
+            {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["files", "paths"],
+              "properties": {
+                "files": { "type": "integer", "minimum": 0 },
+                "paths": { "type": "array", "items": { "type": "string" }, "maxItems": 200 }
+              }
+            }
+          ]
+        }
+      }
+    },
+    "result": {
+      "description": "The declaration was read. Exit code 0, even when some ledgers can't be read or members differ.",
+      "type": "object",
+      "required": ["$schema", "contract", "chant", "env", "compareTo", "lifecycle", "workspace", "members", "summary"],
+      "properties": {
+        "$schema": { "const": "https://intentius.io/chant/schemas/workspace/status/v1/status.schema.json" },
+        "contract": { "const": 1 },
+        "chant": { "type": "string", "description": "The version of the chant that read the ledgers." },
+        "env": { "$ref": "#/$defs/env" },
+        "compareTo": {
+          "description": "The environment given to --compare-to, or null.",
+          "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/env" }]
+        },
+        "error": false,
+        "lifecycle": {
+          "type": "object",
+          "required": ["ref", "commit"],
+          "properties": {
+            "ref": { "const": "chant/lifecycle" },
+            "commit": {
+              "description": "The local branch tip the ledgers were read at, or null when the checkout has no such branch. The command never fetches it.",
+              "type": ["string", "null"],
+              "pattern": "^[0-9a-f]{40,64}$"
+            }
+          }
+        },
+        "checkout": {
+          "description": "Added in contract 1 by #3160. The branch, head and base of the checkout status ran in. records --uncommitted --json lists the records that working tree holds modified or new against head.",
+          "type": "object",
+          "required": ["branch", "head", "base", "baseFrom"],
+          "properties": {
+            "branch": { "type": ["string", "null"], "description": "The checked-out branch's short name, such as chant/work/w-12, or null when HEAD is detached." },
+            "head": { "type": ["string", "null"], "pattern": "^[0-9a-f]{40,64}$", "description": "The full commit id HEAD names, or null before the first commit." },
+            "base": {
+              "type": ["string", "null"],
+              "pattern": "^[0-9a-f]{40,64}$",
+              "description": "The merge base of head and the target branch tip (origin/HEAD, else main, else master), the commit the branch forked from. Null without a head, a target, or common history."
+            },
+            "baseFrom": { "enum": ["origin/HEAD", "main", "master", null], "description": "Where the target branch was found; null when there is none." }
+          }
+        },
+        "replication": {
+          "description": "Added in contract 1 by #3172. When a box block declares replicate (ws-085), where each ref it names (work branches, kept attempts, work-in-progress snapshots, the ledger branch) stands against the remote: replicated, or how many commits ahead. Read from the local refs and what chant recorded at its last push or fetch under refs/chant/replica/<remote>/; the command never fetches. chant workspace wip --json prints the same, with each branch's snapshots. null when no box declares replicate.",
+          "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/replication" }]
+        },
+        "plantable": {
+          "description": "Added in contract 1 by #3146. Whether a host such as a studio's planter can plant the workspace as one box: exactly one member's box block declares services. Not a check: a records-only or infra workspace is valid and simply not plantable.",
+          "$ref": "#/$defs/plantable"
+        },
+        "workspace": {
+          "type": "object",
+          "required": ["name", "root", "file"],
+          "properties": {
+            "name": { "type": "string" },
+            "root": { "type": "string", "description": "The workspace root relative to the git root, with / separators, \".\" for the git root itself." },
+            "file": { "enum": ["chant.workspace.json", "chant.workspace.jsonc"] }
+          }
+        },
+        "members": {
+          "description": "Every member, in declaration order. Example groups have no ledger and are not listed.",
+          "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"],
+          "properties": {
+            "members": { "type": "integer", "minimum": 0 },
+            "released": { "type": "integer", "minimum": 0, "description": "Members with at least one release in env." },
+            "unreadable": { "type": "integer", "minimum": 0, "description": "Members with a reason in any environment." },
+            "differing": {
+              "type": ["integer", "null"],
+              "minimum": 0,
+              "description": "Members whose compare differs, or null without --compare-to."
+            }
+          }
+        }
+      }
+    },
+    "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",
+      "patternProperties": { "^x-": { "description": "Added in contract 1 by #3595. An x- key the declaration holds on this object, with its value as written." } },
+      "required": ["name", "dir", "kind", "fields", "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." },
+        "kind": { "type": "string" },
+        "fields": {
+          "description": "The fields the member's kind declares (#3151), each set from the entry or its default, null when it has neither. Null when the kind declares no fields or no pinned package supplies it. A value of the wrong type reads as the default, and chant workspace check reports it (WSP005). Added in contract 1 by chant 0.103.0.",
+          "type": ["object", "null"],
+          "additionalProperties": {
+            "oneOf": [
+              { "type": "string" },
+              { "type": "integer" },
+              { "type": "boolean" },
+              { "type": "null" },
+              { "type": "object", "additionalProperties": { "oneOf": [{ "type": "string" }, { "type": "integer" }, { "type": "boolean" }, { "type": "null" }] } }
+            ]
+          }
+        },
+        "environments": {
+          "description": "env first, then compareTo when it is given and differs from env.",
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 2,
+          "items": { "$ref": "#/$defs/environment" }
+        },
+        "compare": {
+          "description": "Null without --compare-to.",
+          "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/compare" }]
+        },
+        "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: its turns' Ops, then those it runs beside its turns (#2861).",
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["name", "schedule", "env", "lastRun", "inFlight", "lastTick", "changesCheckout", "workLease", "beside"],
+            "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", "phases"],
+                    "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 decision point a waiting run stopped on (#2749), or null. Its state is the question's now, as `points` reads it: `answered` once a person has answered it. When the questions can't be read, or the answer record is gone, it is the state the run ledger recorded.",
+                        "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/stewardWait" }]
+                      },
+                      "phases": {
+                        "description": "Each phase of the run in execution order, with its verdict and its wall-clock time in milliseconds. For a record written before chant kept phase times, durationMs is the sum of its steps' times. A phase skipped whole has 0. Added by chant 0.96.0.",
+                        "type": "array",
+                        "items": { "$ref": "#/$defs/runPhase" }
+                      }
+                    }
+                  }
+                ]
+              },
+              "inFlight": {
+                "description": "The run of the Op in flight now, or null when none is. A run that writes to the run ledger keeps a record beside the checkout's git directory while it runs and removes it once its ledger record is written; a record whose process on this host is gone is not in flight. phase and step are what it is doing now (step is the newest step still running, named by its id, or its activity when it has none), phases the phases it has finished, and activity the newest lines its steps reported (a shell step appends them to the file in CHANT_RUN_ACTIVITY), with seq counting from 1 over the run and total the count so far. item is the work item its lease holds, once claimed. Added by chant 0.96.0.",
+                "oneOf": [
+                  { "type": "null" },
+                  {
+                    "type": "object",
+                    "required": ["id", "started", "updated", "steward", "item", "phase", "step", "phases", "activity"],
+                    "properties": {
+                      "id": { "type": "string", "description": "The run's id: the id its ledger record will have." },
+                      "started": { "type": "string" },
+                      "updated": { "type": "string", "description": "When the run last changed its record." },
+                      "steward": { "type": ["string", "null"] },
+                      "item": { "type": ["string", "null"] },
+                      "phase": {
+                        "oneOf": [
+                          { "type": "null" },
+                          { "type": "object", "required": ["name", "started"], "properties": { "name": { "type": "string" }, "started": { "type": "string" } } }
+                        ]
+                      },
+                      "step": {
+                        "oneOf": [
+                          { "type": "null" },
+                          {
+                            "type": "object",
+                            "required": ["name", "fn", "started"],
+                            "properties": { "name": { "type": "string" }, "fn": { "type": "string" }, "started": { "type": "string" } }
+                          }
+                        ]
+                      },
+                      "phases": { "type": "array", "items": { "$ref": "#/$defs/runPhase" } },
+                      "activity": {
+                        "type": "object",
+                        "required": ["total", "lines"],
+                        "properties": {
+                          "total": { "type": "integer" },
+                          "lines": {
+                            "type": "array",
+                            "items": {
+                              "type": "object",
+                              "required": ["seq", "at", "text"],
+                              "properties": { "seq": { "type": "integer" }, "at": { "type": ["string", "null"] }, "text": { "type": "string" } }
+                            }
+                          }
+                        }
+                      }
+                    }
+                  }
+                ]
+              },
+              "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"] }
+                          }
+                        }
+                      }
+                    }
+                  }
+                ]
+              },
+              "beside": {
+                "description": "For an Op the steward runs beside its turns (#2861), in a process of its own under the Op's own lease: ready is whether a ready step says when the operator starts it, and lease is the Op's lease ref (refs/chant/lease/<op>), held by a run of it while it runs (holder <steward>/<op>@<operator> for a run the operator started), read locally and never fetched, or null when none has held it. live is false once expiresAt has passed. Null for an Op the steward runs as one of its turns.",
+                "oneOf": [
+                  { "type": "null" },
+                  {
+                    "type": "object",
+                    "required": ["ready", "lease"],
+                    "properties": {
+                      "ready": { "type": "boolean" },
+                      "lease": {
+                        "oneOf": [
+                          { "type": "null" },
+                          {
+                            "type": "object",
+                            "required": ["holder", "acquiredAt", "expiresAt", "live"],
+                            "properties": {
+                              "holder": { "type": "string" },
+                              "acquiredAt": { "type": "string" },
+                              "expiresAt": { "type": "string" },
+                              "live": { "type": "boolean" }
+                            }
+                          }
+                        ]
+                      }
+                    }
+                  }
+                ]
+              }
+            }
+          }
+        },
+        "waiting": {
+          "description": "The open decision points the steward waits on (#2749): one for each Op whose newest run is the steward's own (its ledger record names the steward) and stopped on a question that is still open: the steward's own Ops in ops order, then any other Op of the member, such as one the steward's process starts itself (studio#137), by name. The state is the question's now, as `chant workspace points --open` reads it, where hud asks a person. A question answered since, or whose answer record is gone, is not listed, and nor is one whose Op has a newer run in flight: the Op's lease or one of its work leases was taken after the waiting run ended and is still held. When the questions can't be read, the run ledger's state stands. The steward never answers one, and runs an Op it lists again on the first round after it is answered (an Op beside its turns, in a process of its own, #2861).",
+          "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." }, "state": { "enum": ["escalated", "proposed"] } }
+              }
+            ]
+          }
+        }
+      }
+    },
+    "runPhase": {
+      "type": "object",
+      "required": ["name", "status", "durationMs"],
+      "properties": {
+        "name": { "type": "string" },
+        "status": { "enum": ["ok", "fail", "skipped"] },
+        "durationMs": { "type": "number" }
+      }
+    },
+    "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", "answered"], "description": "The question's state now, as `points` reads it, or the state the run ledger recorded when the questions can't be read or the record is gone. Never `answered` in a steward's `waiting`." },
+        "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." }
+      }
+    },
+    "intent": {
+      "type": "object",
+      "required": ["id", "state", "question", "choice", "answer", "decided_by", "decided_on"],
+      "properties": {
+        "id": { "type": "string", "description": "The record's id, as the box block names it." },
+        "state": { "type": ["string", "null"], "description": "The record's state as written, such as proposed or decided, or null when no decision record has the id." },
+        "question": { "type": ["string", "null"], "description": "The question the record answers." },
+        "choice": { "description": "The record's choice as written, such as { option, reason }, or null while the record is proposed." },
+        "answer": { "type": ["string", "null"], "description": "The chosen option's label, from options[]'s entry whose id is choice.option, or null while no option is chosen (#2855). Added by chant 0.94.0." },
+        "decided_by": { "type": ["string", "null"], "description": "Who decided it, or null while it is proposed." },
+        "decided_on": { "type": ["string", "null"], "description": "The day it was decided, or null while it is proposed." },
+        "approved": {
+          "type": "boolean",
+          "description": "Added in contract 1 by #3609. Whether the record's state counts as approved: the decision kind's approval rank for that state is above 0, the rule the factory's pick holds dispatch with. With chant's decision kind, decided, ratified and superseded are approved, and proposed and withdrawn are not. False when no decision record has the id, and for a kind that declares no approval ranks."
+        }
+      }
+    },
+    "replication": {
+      "type": "object",
+      "required": ["policy", "remoteConfigured", "replicated", "refs"],
+      "properties": {
+        "policy": {
+          "type": "object",
+          "required": ["box", "remote", "refs", "on", "every"],
+          "properties": {
+            "box": { "type": "string", "description": "The member whose box block declares the policy." },
+            "remote": { "type": "string" },
+            "refs": { "type": "array", "items": { "enum": ["work", "kept", "wip", "ledger"] } },
+            "on": { "type": "array", "items": { "enum": ["save", "release"] } },
+            "every": { "type": ["string", "null"] }
+          }
+        },
+        "remoteConfigured": { "type": "boolean", "description": "Whether the checkout has a git remote of the policy's name." },
+        "replicated": { "type": "boolean", "description": "True when every ref listed is on the remote as it is locally." },
+        "refs": {
+          "type": "array",
+          "description": "Every local ref the policy names, sorted by ref.",
+          "items": {
+            "type": "object",
+            "required": ["ref", "class", "commit", "replica", "replicated", "ahead"],
+            "properties": {
+              "ref": { "type": "string", "description": "Such as refs/heads/chant/work/W-001, refs/chant/kept/W-001/<token>, refs/chant/wip/chant/work/W-001 or refs/heads/chant/lifecycle." },
+              "class": { "enum": ["work", "kept", "wip", "ledger"] },
+              "commit": { "type": "string", "pattern": "^[0-9a-f]{40,64}$" },
+              "replica": { "type": ["string", "null"], "pattern": "^[0-9a-f]{40,64}$", "description": "What the remote held of the ref as chant last saw it (or, for a branch, git's remote-tracking ref), or null when unknown." },
+              "replicated": { "type": "boolean" },
+              "ahead": { "type": "integer", "minimum": 0, "description": "Commits reachable from commit that nothing known to be on the remote reaches; 0 when replicated." }
+            }
+          }
+        }
+      }
+    },
+    "box": {
+      "type": "object",
+      "patternProperties": { "^x-": { "description": "Added in contract 1 by #3595. An x- key the declaration holds on this object, with its value as written." } },
+      "required": ["capabilities", "isolation", "intent", "services"],
+      "properties": {
+        "factory": {
+          "description": "Added in contract 1 by #3146. What the box builds and how (ws-077), with every default filled in, or null when the block declares no factory. At most one member's box has one.",
+          "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/factory" }]
+        },
+        "listing": {
+          "description": "Added in contract 1 by #3146. What the box shows of itself on a home site, or null when the block declares no listing.",
+          "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/listing" }]
+        },
+        "publisher": {
+          "description": "Added in contract 1 by #3165. The command that publishes the box's work, as the box block declares it (ws-088), or null when it names none. A surface offers a publish only when it is set, and asks for one with chant workspace box publish rather than running it.",
+          "type": ["string", "null"]
+        },
+        "ship": {
+          "description": "Added in contract 1 by ws-100. How the box ships its staged work to its own site, with defaults filled in, the release its site serves and what is waiting to ship, or null when the box block declares no ship. A surface offers Ship only when it is set: it runs chant run <op> in the member's directory with the person in CHANT_SHIP_BY and approves <gate> as for any Op.",
+          "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/boxShip" }]
+        },
+        "replicate": {
+          "description": "Added in contract 1 by #3172. Where the box's work in progress is replicated (ws-085), with every default filled in, or null when the block declares no policy. At most one member's box has one; the top-level replication says how far each ref is from the remote.",
+          "oneOf": [
+            { "type": "null" },
+            {
+              "type": "object",
+              "required": ["remote", "refs", "on", "every"],
+              "properties": {
+                "remote": { "type": "string", "description": "The git remote, by name; origin when the block names none." },
+                "refs": { "type": "array", "items": { "enum": ["work", "kept", "wip", "ledger"] }, "description": "What is replicated, in this order; all four when the block names none." },
+                "on": { "type": "array", "items": { "enum": ["save", "release"] }, "description": "When chant pushes on its own; both when the block names none." },
+                "every": { "type": ["string", "null"], "description": "The interval at which the host runs chant workspace wip push, or null." }
+              }
+            }
+          ]
+        },
+        "services": {
+          "description": "The services the box block declares (#2880), in declaration order, or empty when it declares none. A reader has them before any converge tick; a steward's ConvergeOp's lastTick carries each one's verdict. cmd is as declared: its ${VAR} references are left for the process that applies it to expand. Added by chant 0.95.0.",
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["name", "cmd", "needs", "httpPort", "duration", "health", "optional"],
+            "properties": {
+              "name": { "type": "string" },
+              "cmd": { "type": "string", "description": "The command the supervisor runs, as declared." },
+              "needs": { "type": "array", "items": { "type": "string" }, "description": "Services of the same box that start first. Empty when none." },
+              "httpPort": { "type": ["integer", "null"], "description": "The port the supervisor routes the sprite's URL to, or null." },
+              "duration": { "type": ["string", "null"], "description": "How long the service must stay up after a create or start, such as 3s, or null for the supervisor's default." },
+              "health": { "type": ["string", "null"], "description": "A URL that answers 200 while the service works, or null when the supervisor's state decides." },
+              "optional": { "type": "boolean", "description": "True for a service something else creates by name, such as a site a release makes." }
+            }
+          }
+        },
+        "intent": {
+          "description": "The decision record the box block names as the box's intent (#2850), or null when it names none. A box starts as a question: the record is proposed with a null choice, and decided when the person who answered it amends it. Read from the working tree, from the declared record kinds named decision. When no decision record has the id, every field but id is null and chant workspace check fails (WSP126). Added by chant 0.94.0.",
+          "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/intent" }]
+        },
+        "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." }
+            }
+          }
+        }
+      }
+    },
+    "plantable": {
+      "type": "object",
+      "required": ["plantable", "box", "reason"],
+      "properties": {
+        "plantable": { "type": "boolean" },
+        "box": { "type": ["string", "null"], "description": "The member whose box block declares services, or null when the workspace isn't plantable." },
+        "reason": {
+          "description": "Why the workspace isn't plantable, or null when it is.",
+          "oneOf": [
+            { "type": "null" },
+            {
+              "type": "object",
+              "required": ["code", "message"],
+              "properties": {
+                "code": { "enum": ["box-none", "box-several"] },
+                "message": { "type": "string" }
+              }
+            }
+          ]
+        }
+      }
+    },
+    "factory": {
+      "type": "object",
+      "patternProperties": { "^x-": { "description": "Added in contract 1 by #3595. An x- key the declaration holds on this object, with its value as written." } },
+      "required": ["builds", "check", "checks", "builders", "tiers", "builderFor", "publish"],
+      "properties": {
+        "builds": { "type": "array", "minItems": 1, "items": { "type": "string" }, "description": "The members the factory builds, in declaration order. A work item a person asks for constrains member:<the first>." },
+        "check": {
+          "description": "The verdict command, run from the workspace root, and what it is; null when none is declared.",
+          "oneOf": [
+            { "type": "null" },
+            {
+              "type": "object",
+              "required": ["run", "kind"],
+              "properties": {
+                "run": { "type": "string" },
+                "kind": { "enum": ["test", "build", "lint", "plan", "conformance"] }
+              }
+            }
+          ]
+        },
+        "checks": { "type": ["string", "null"], "description": "Where a work item's builder writes its check, from the workspace root, or null for the orchestrator's choice." },
+        "builders": { "type": ["string", "null"], "description": "The member that declares the builder agents, or null." },
+        "tiers": {"type": "array", "items": {"type": "object", "required": ["tier", "agent", "kinds", "session"], "properties": {"tier": {"type": "string"}, "agent": {"type": "string"}, "kinds": {"oneOf": [{"type": "null"}, {"type": "array", "items": {"type": "string"}}]}, "session": {"type": ["string", "null"]}}}, "description": "Which builder agent builds at which tier, as declared (#3152, ws-094), each { tier, agent, kinds, session } with kinds and session null when not declared; empty when none is. Added in contract 1 by chant 0.103.0."},
+        "builderFor": {"type": "object", "additionalProperties": {"type": "object", "additionalProperties": {"type": "object", "required": ["agent", "session"], "properties": {"agent": {"type": "string"}, "session": {"type": ["string", "null"]}}}}, "description": "The builder for each member the factory builds, by tier (#3152): member name, then tier, then { agent, session }. For a member the entry naming its kind is used, else the tier's entry with no kinds; a tier with neither is left out. Added in contract 1 by chant 0.103.0."},
+        "publish": {
+          "description": "Where a finished build is published, or null when the factory doesn't publish past the box.",
+          "oneOf": [
+            { "type": "null" },
+            {
+              "type": "object",
+              "required": ["forge", "repo", "base", "branchPrefix", "head"],
+              "properties": {
+                "forge": { "const": "github" },
+                "repo": { "type": "string", "description": "owner/name: where the pull request is opened." },
+                "base": { "type": ["string", "null"], "description": "The branch the pull request targets, or null for the repository's default branch." },
+                "branchPrefix": { "type": "string", "description": "What the published branch's name starts with, before the work item's id. chant/work/ unless declared." },
+                "head": { "type": ["string", "null"], "description": "owner/name of the fork the branch is pushed to, or null to push to repo." }
+              }
+            }
+          ]
+        }
+      }
+    },
+    "listing": {
+      "type": "object",
+      "patternProperties": { "^x-": { "description": "Added in contract 1 by #3595. An x- key the declaration holds on this object, with its value as written." } },
+      "required": ["published", "title", "line", "cover"],
+      "properties": {
+        "published": { "type": "boolean", "description": "Whether the box is listed; true unless declared otherwise." },
+        "title": { "type": "string", "description": "Empty when not declared: a reader shows a name of its own." },
+        "line": { "type": "string", "description": "Empty when not declared." },
+        "cover": {
+          "description": "The cover image, or null when none is declared.",
+          "oneOf": [
+            { "type": "null" },
+            {
+              "type": "object",
+              "required": ["path", "sha256"],
+              "properties": {
+                "path": { "type": "string", "description": "From the workspace root." },
+                "sha256": { "type": ["string", "null"], "pattern": "^[0-9a-f]{64}$", "description": "The sha256 of the file's bytes in the working tree, or null when it can't be read." }
+              }
+            }
+          ]
+        }
+      }
+    },
+    "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" }
+        }
+      }
+    },
+    "gateLedger": {
+      "type": "object",
+      "required": ["layout", "path", "shared", "malformed", "reason"],
+      "properties": {
+        "layout": {
+          "enum": ["members", "flat"],
+          "description": "members: _members/<member>/_gates. flat: _gates. Chosen as for the member's release ledger."
+        },
+        "path": { "type": "string", "description": "The gate ledger directory on chant/lifecycle. Each file in it is <component>.jsonl, or <op>.jsonl for a gate an Op run reached." },
+        "shared": { "type": "boolean", "description": "True when more than one member in this output reads the flat _gates directory, so they list the same gates." },
+        "malformed": { "type": "integer", "minimum": 0, "description": "Lines that are neither a pending fact nor an approval. They are skipped." },
+        "reason": {
+          "oneOf": [
+            { "type": "null" },
+            {
+              "type": "object",
+              "required": ["code", "message"],
+              "properties": {
+                "code": { "enum": ["gates-no-ledger", "gates-no-gate-ledger", "gates-ledger-unreadable"] },
+                "message": { "type": "string" }
+              }
+            }
+          ]
+        }
+      }
+    },
+    "gate": {
+      "type": "object",
+      "required": ["component", "name", "env", "planDigest", "state", "recordedAt", "expiresAt", "approvals", "needed", "signed", "approve"],
+      "properties": {
+        "component": { "type": "string", "description": "The ledger file's key: the component, or the op for a gate an Op run reached." },
+        "name": { "type": "string", "description": "The gate's name." },
+        "env": {
+          "description": "The environment the run reached the gate in, or null for a gate that records none.",
+          "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/env" }]
+        },
+        "planDigest": { "type": ["string", "null"], "description": "The plan the run reached the gate with (#2300), or null for a gate that binds no plan. An approval counts only for this plan." },
+        "state": {
+          "enum": ["pending", "approved", "expired", "superseded"],
+          "description": "Read from the newest pending fact for the gate in env, as a run reads it. approved: the approvals recorded since it, for its plan, pass the gate (its quorum, or a policy permit in enforce mode). expired: not approved, and the pending fact is past expiresAt, so the next run records a fresh one. superseded: not approved, and an approval recorded since it names a different plan, so it doesn't count. pending: none of these."
+        },
+        "recordedAt": { "type": "string", "description": "When the run recorded the pending fact." },
+        "expiresAt": { "type": "string" },
+        "approvals": {
+          "description": "The approvals that count toward the gate for its plan, oldest first.",
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["principal", "channel", "relayedBy", "at"],
+            "properties": {
+              "principal": { "type": "string", "description": "Who recorded it." },
+              "channel": { "type": ["string", "null"], "description": "The channel it was recorded on, such as cli or mcp, or null for a record older than chant#2384." },
+              "relayedBy": { "type": ["string", "null"], "description": "Added in contract 1 by #3402. Who carried the approval to chant for principal (chant approve --relayed-by), such as a follower relaying a person's approval; a seal covers it. Null when nobody relayed it." },
+              "at": { "type": "string" }
+            }
+          }
+        },
+        "needed": { "type": "integer", "minimum": 1, "description": "The human approvals the gate needs: its quorum's count, 1 without one." },
+        "signed": {
+          "description": "Added in contract 1 by #3163. The declaration's rule for the gate, read at base (identity.gates, ws-080): only an approval sealed with chant approve --sign by a key the signers file at base lists for its approver counts, and when class is not null, only one whose approver the role grants at base put in that class. Approvals that don't meet it are left out of approvals and state. Null when any approval counts.",
+          "oneOf": [
+            { "type": "null" },
+            {
+              "type": "object",
+              "required": ["class"],
+              "properties": {
+                "class": { "type": ["string", "null"], "description": "The principal class the signer must be in, or null for any listed signer." }
+              }
+            }
+          ]
+        },
+        "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, and --sign when signed is not null (#3163). The caller adds --actor <principal>. For a gate that asks a decision point (#3170), the chant workspace points answer line for the question in answer." },
+        "answer": {
+          "type": "object",
+          "description": "The open question the gate waits on, when it asks a decision point (#3170): absent on a gate chant approve passes. Answered with chant workspace points answer <id>; the run that passes the gate then cites the answer record on the ledger.",
+          "required": ["point", "id", "path"],
+          "properties": {
+            "point": { "type": "string" },
+            "id": { "type": "string", "description": "The answer record's id." },
+            "path": { "type": "string", "description": "The answer record, from the repository root." }
+          }
+        }
+      }
+    },
+    "environment": {
+      "type": "object",
+      "required": ["env", "ledger", "releases", "reason"],
+      "properties": {
+        "env": { "$ref": "#/$defs/env" },
+        "ledger": {
+          "type": "object",
+          "required": ["layout", "path", "shared"],
+          "properties": {
+            "layout": {
+              "enum": ["members", "flat"],
+              "description": "members: _members/<member>/<env>/releases.jsonl (#2538). flat: <env>/releases.jsonl, for the root member and for a member with no _members/<member>/ directory yet."
+            },
+            "path": { "type": "string", "description": "The ledger's path on chant/lifecycle." },
+            "shared": { "type": "boolean", "description": "True when more than one member in this output reads the same flat ledger, so they list the same records." }
+          }
+        },
+        "releases": {
+          "description": "The latest release of each component in the ledger, sorted by component. Empty when the ledger has none.",
+          "type": "array",
+          "items": { "$ref": "#/$defs/release" }
+        },
+        "reason": {
+          "oneOf": [
+            { "type": "null" },
+            {
+              "type": "object",
+              "required": ["code", "message"],
+              "properties": {
+                "code": { "enum": ["ledger-unreadable", "ledger-malformed"] },
+                "message": { "type": "string" }
+              }
+            }
+          ]
+        }
+      }
+    },
+    "release": {
+      "type": "object",
+      "required": ["component", "digest", "gitSha", "inputDigest", "runId", "timestamp", "actor", "flags", "plan"],
+      "properties": {
+        "component": { "type": "string" },
+        "digest": { "type": "string", "description": "The artifact digest the release deployed." },
+        "gitSha": { "type": "string", "description": "The commit the artifact was built from." },
+        "inputDigest": { "type": ["string", "null"], "description": "The input-side digest when digest is a rendered one. Compare joins on it when present." },
+        "runId": { "type": "string" },
+        "timestamp": { "type": "string" },
+        "actor": { "type": "string" },
+        "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": {
+      "type": "object",
+      "required": ["differs", "components"],
+      "properties": {
+        "differs": { "type": "boolean", "description": "True when any component is not same." },
+        "components": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["component", "state", "digest", "compareDigest"],
+            "properties": {
+              "component": { "type": "string" },
+              "state": {
+                "enum": ["same", "differs", "only-env", "only-compare"],
+                "description": "same: both environments have the same digest (the input digest when there is one). only-env and only-compare: the component has a release in one of them."
+              },
+              "digest": { "type": ["string", "null"] },
+              "compareDigest": { "type": ["string", "null"] }
+            }
+          }
+        }
+      }
+    },
+    "failure": {
+      "description": "The declaration could not be read, or an environment name can't be one. Exit code 1.",
+      "type": "object",
+      "required": ["$schema", "contract", "chant", "error"],
+      "properties": {
+        "$schema": { "const": "https://intentius.io/chant/schemas/workspace/status/v1/status.schema.json" },
+        "contract": { "const": 1 },
+        "chant": { "type": "string" },
+        "error": {
+          "type": "object",
+          "required": ["code", "message", "location"],
+          "properties": {
+            "code": {
+              "enum": [
+                "declaration-missing",
+                "declaration-ambiguous",
+                "declaration-unparseable",
+                "declaration-invalid",
+                "placement-invalid",
+                "reader-too-old",
+                "root-chant-required",
+                "not-a-git-repository",
+                "environment-invalid"
+              ]
+            },
+            "message": { "type": "string" },
+            "location": {
+              "oneOf": [
+                { "type": "null" },
+                {
+                  "type": "object",
+                  "required": ["file", "line", "column"],
+                  "properties": {
+                    "file": { "type": "string" },
+                    "line": { "type": "integer", "minimum": 1 },
+                    "column": { "type": "integer", "minimum": 1 }
+                  }
+                }
+              ]
+            }
+          }
+        },
+        "members": false,
+        "workspace": false
+      }
+    }
+  }
+}