@intentius/chant 0.101.0 → 0.104.0

package/dist/workspace/declaration.schema.json

@@ -104,12 +104,18 @@
         },
         "writeScope": {
             "type": "object",
-            "additionalProperties": false,
-            "description": "Who may write what (#2524 D5, #2548, ws-067): for each principal class, the members whose files it may write and the record kinds it may write, with which verbs. A class with no entry is not restricted. An agent is always bound to its session's member (agents); its entry can only narrow the record kinds and verbs. chant workspace records new, amend, review and close and the MCP record tools refuse a write outside the writer's scope with write-scope-member or write-scope-kind, and chant workspace check --changes reports each commit that writes outside its author's scope, read from the declaration and the trust policy at the range's base. Added in schema 1 by chant 0.101.0, so a declaration that uses it sets minReader to 0.101.0 or newer.",
+            "propertyNames": {
+                "$ref": "#/$defs/className"
+            },
+            "additionalProperties": {
+                "$ref": "#/$defs/classScope",
+                "description": "A domain class a pinned package supplies at its ./workspace-principals subpath (#3080, ws-079): principals holding the role the class names in the trust policy at base, and none of the agent, runner and service roles. A key no pinned package supplies fails chant workspace check with WSP003, and a writer judged human is refused with write-scope-class-unknown, since it may be in that class. Added in schema 1 by chant 0.102.0, so a declaration that uses one sets minReader to 0.102.0 or newer."
+            },
+            "description": "Who may write what (#2524 D5, #2548, ws-067): for each principal class, the members whose files it may write and the record kinds it may write, with which verbs. A class is human, agent, runner or service, or a domain class a pinned package supplies (#3080). A class with no entry is not restricted. An agent is always bound to its session's member (agents); its entry can only narrow the record kinds and verbs. chant workspace records new, amend, review and close and the MCP record tools refuse a write outside the writer's scope with write-scope-member or write-scope-kind, and chant workspace check --changes reports each commit that writes outside its author's scope, read from the declaration and the trust policy at the range's base, and a write to a path the class's protected list covers with write-scope-protected (#3146). Added in schema 1 by chant 0.101.0, so a declaration that uses it sets minReader to 0.101.0 or newer.",
             "properties": {
                 "human": {
                     "$ref": "#/$defs/classScope",
-                    "description": "Principals holding none of the agent, runner and service roles in the trust policy at base."
+                    "description": "Principals holding none of the agent, runner and service roles, and none of the roles a domain class names, in the trust policy at base."
                 },
                 "agent": {
                     "$ref": "#/$defs/agentScope",
@@ -131,6 +137,35 @@
             "items": {
                 "$ref": "#/$defs/agent"
             }
+        },
+        "identity": {
+            "type": "object",
+            "additionalProperties": false,
+            "description": "Who a person-attributed record or gate approval may name, and which gates need a signed approval (#3163, ws-080). Read from the declaration at base, like writeScope, so a change can't loosen its own rule. A person is named by a forge identity (github:<login>, gitlab:<login>, or <forge>@<host>:<login> for forgejo, gitea or a self-hosted github or gitlab) that the surface which signed them in maps their session to, or by a principal .chant/allowed_signers lists at base. chant never authenticates a person: a forge identity is recorded as the surface gives it, and only a seal verified against the signers at base attests it. Added in schema 1 by chant 0.102.0, so a declaration that uses it sets minReader to 0.102.0 or newer.",
+            "properties": {
+                "attribution": {
+                    "enum": ["any", "identified"],
+                    "description": "any (the default): a record's by, decided_by, reviewer or answerer and a gate approval's actor may be any name, such as a roster name. identified: each must be a forge identity, a principal the signers file at base lists, or a principal holding the agent, runner or service role at base or listed by a declared agent session; chant workspace records new and review, points answer and chant approve refuse any other name with principal-unidentified."
+                },
+                "gates": {
+                    "type": "object",
+                    "description": "Gates, by name, that pass only on a signed approval: chant approve --sign with a key the signers file at base lists for the approver. The rule applies to a gate of that name in every member, Op and component. An unsigned approval, or one whose signer is not in class, is recorded nowhere and never counts toward the gate.",
+                    "propertyNames": {
+                        "type": "string",
+                        "minLength": 1
+                    },
+                    "additionalProperties": {
+                        "type": "object",
+                        "additionalProperties": false,
+                        "properties": {
+                            "class": {
+                                "$ref": "#/$defs/className",
+                                "description": "The principal class the signer must be in, read from the role grants at base (#3080, ws-079): human, runner, service, or a domain class a pinned package supplies. A class no pinned package supplies lets no approval through (fail closed). Absent: any signer the signers file lists."
+                            }
+                        }
+                    }
+                }
+            }
         }
     },
     "patternProperties": {
@@ -147,6 +182,11 @@
             "type": "string",
             "pattern": "^[a-z][a-z0-9-]{0,39}$"
         },
+        "className": {
+            "type": "string",
+            "pattern": "^(?!x-)[a-z][a-z0-9-]{0,39}$",
+            "description": "A principal class: human, agent, runner, service, or a domain class a pinned package supplies (#3080)."
+        },
         "version": {
             "type": "string",
             "pattern": "^(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)(-[0-9A-Za-z.-]+)?$"
@@ -329,6 +369,9 @@
                         "$ref": "#/$defs/outputName"
                     }
                 },
+                "fields": {
+                    "$ref": "#/$defs/memberFields"
+                },
                 "links": {
                     "type": "array",
                     "description": "Member links (#2524 D6, #2539): the outputs of other members this member reads. A link is stated once, here on the consumer, and matched exactly against the producer's outputs. chant workspace check resolves it in source.",
@@ -398,6 +441,23 @@
                 ]
             }
         },
+        "memberFields": {
+            "type": "object",
+            "description": "Values for the fields the member's kind declares (#3151), such as an app member's scripts, env and health. Each is a string, integer or boolean, or an object of those for a field the kind declares as an object. chant workspace check fails when the kind declares no such field or a value is of the wrong type (WSP005), and chant workspace status --json prints every field the kind declares with its defaults filled in. Added in schema 1 by chant 0.103.0, so a declaration that uses it sets minReader to 0.103.0 or newer.",
+            "propertyNames": { "pattern": "^[a-z][A-Za-z0-9]{0,39}$" },
+            "additionalProperties": {
+                "oneOf": [
+                    { "type": "string" },
+                    { "type": "integer" },
+                    { "type": "boolean" },
+                    {
+                        "type": "object",
+                        "propertyNames": { "pattern": "^[a-z][A-Za-z0-9]{0,39}$" },
+                        "additionalProperties": { "oneOf": [{ "type": "string" }, { "type": "integer" }, { "type": "boolean" }] }
+                    }
+                ]
+            }
+        },
         "group": {
             "type": "object",
             "description": "An example group (ws-051): every directory the glob matches that holds a chant project is built and linted. A group has no ledger, releases or links, and its matches are never members. A match may sit inside a member's directory; that member leaves it to the group.",
@@ -444,7 +504,7 @@
         },
         "box": {
             "type": "object",
-            "description": "The member is a box, or holds a box's declarations (#2726). A box holds no credential: each capability it needs outside itself is reached through a broker, a runtime such as a lobby or a door, which holds the credential and enforces the scope. chant workspace check fails when a file in the member's directory carries a literal secret (WSP121) and when a capability names no broker (WSP122). chant workspace status --json lists the capabilities, so a broker can read the scopes. Its host, slot, ports, state and cookies state the box's isolation (#2727): chant derives each value from the box's identity, its host, the member's name and its slot, and prints them in chant workspace status --json, so a runtime reads them instead of choosing its own. chant workspace check fails when two boxes on a host resolve to the same value (WSP123) and when a box hard-codes a machine path (WSP124). A member that builds the fountain lexicon's Box declares the callback token fountain gives its persistent sandbox as the capability fountain-callback, brokered by fountain, with scope owner, or chant workspace check fails (WSP125, #2780). Its intent names the decision record that says what the box is for (#2850): chant workspace status --json reports the record's state and answer, and chant workspace check fails when no decision record has the id (WSP126) and warns when the record constrains no member or path of this workspace (WSP127, #2857). Its services list what the box runs under its supervisor (#2880), which the fly lexicon observes, restarts and applies through sprite-env, and which chant workspace status --json prints. Added in schema 1 by chant 0.91.0, so a declaration that uses it sets minReader to 0.91.0 or newer.",
+            "description": "The member is a box, or holds a box's declarations (#2726). A box holds no credential: each capability it needs outside itself is reached through a broker, a runtime such as a lobby or a door, which holds the credential and enforces the scope. chant workspace check fails when a file in the member's directory carries a literal secret (WSP121) and when a capability names no broker (WSP122). chant workspace status --json lists the capabilities, so a broker can read the scopes. Its host, slot, ports, state and cookies state the box's isolation (#2727): chant derives each value from the box's identity, its host, the member's name and its slot, and prints them in chant workspace status --json, so a runtime reads them instead of choosing its own. chant workspace check fails when two boxes on a host resolve to the same value (WSP123) and when a box hard-codes a machine path (WSP124). A member that builds the fountain lexicon's Box declares the callback token fountain gives its persistent sandbox as the capability fountain-callback, brokered by fountain, with scope owner, or chant workspace check fails (WSP125, #2780). Its intent names the decision record that says what the box is for (#2850): chant workspace status --json reports the record's state and answer, and chant workspace check fails when no decision record has the id (WSP126) and warns when the record constrains no member or path of this workspace (WSP127, #2857). Its services list what the box runs under its supervisor (#2880), which the fly lexicon observes, restarts and applies through sprite-env, and which chant workspace status --json prints. Its factory declares what the box builds, how a build is checked, which member declares the builder agents and where a finished build is published (#3146, ws-077), its listing what the box shows of itself (#3146), and its replicate where the box's work in progress is pushed so a lost box loses none of it (#3172, ws-085). Added in schema 1 by chant 0.91.0, so a declaration that uses it sets minReader to 0.91.0 or newer.",
             "properties": {
                 "intent": {
                     "type": "string",
@@ -458,6 +518,24 @@
                         "$ref": "#/$defs/boxService"
                     }
                 },
+                "factory": {
+                    "$ref": "#/$defs/boxFactory"
+                },
+                "listing": {
+                    "$ref": "#/$defs/boxListing"
+                },
+                "publisher": {
+                    "type": "string",
+                    "minLength": 1,
+                    "pattern": "\\S",
+                    "description": "The command that publishes the box's work (#3165, ws-088): it applies a built work item to the box's checkout and, when factory.publish names a target, pushes it and opens the pull request, and it sends the records a person kept uncommitted. It is run from the workspace root by chant workspace box publish, split into words as a shell splits plain words (quotes group, a backslash escapes) but never given to a shell, with a JSON request on stdin; box-publish.schema.json says what it reads and prints. An orchestrator such as studio supplies it. chant workspace status --json prints it under the member's box, so a surface offers a publish only when a box names one. Added in schema 1 by chant 0.103.0, so a declaration that uses it sets minReader to 0.103.0 or newer."
+                },
+                "replicate": {
+                    "$ref": "#/$defs/boxReplicate"
+                },
+                "ship": {
+                    "$ref": "#/$defs/boxShip"
+                },
                 "capabilities": {
                     "type": "array",
                     "description": "Each capability the box reaches outside itself, named once. None when omitted.",
@@ -530,6 +608,259 @@
             },
             "additionalProperties": false
         },
+        "boxFactory": {
+            "type": "object",
+            "description": "What the box builds and how (#3146, ws-077), replacing studio's x-factory. Opt-in: a box block without it declares no factory, and nothing here is required of a workspace that doesn't build with agents (#3174). At most one box block in a declaration declares a factory. builds and builders name declared members, or the declaration can't be read (declaration-invalid). chant workspace status --json and chant workspace graph --json print it under the member's box. The factory need not build an app: builds may name any member kind, such as chant or terraform, and the check may be a plan, a lint or a conformance run. Added in schema 1 by chant 0.102.0, so a declaration that uses it sets minReader to 0.102.0 or newer.",
+            "required": [
+                "builds"
+            ],
+            "properties": {
+                "builds": {
+                    "type": "array",
+                    "minItems": 1,
+                    "uniqueItems": true,
+                    "description": "The members the factory builds, each a declared member of any kind. A work item a person asks for here constrains member:<the first>.",
+                    "items": {
+                        "$ref": "#/$defs/name"
+                    }
+                },
+                "check": {
+                    "description": "The command whose exit code is a build's verdict, run from the workspace root after the work item's own checks: a command, or { run, kind } saying what it is. kind is test when omitted.",
+                    "oneOf": [
+                        {
+                            "type": "string",
+                            "minLength": 1
+                        },
+                        {
+                            "type": "object",
+                            "required": [
+                                "run"
+                            ],
+                            "properties": {
+                                "run": {
+                                    "type": "string",
+                                    "minLength": 1,
+                                    "description": "The command, run from the workspace root."
+                                },
+                                "kind": {
+                                    "enum": [
+                                        "test",
+                                        "build",
+                                        "lint",
+                                        "plan",
+                                        "conformance"
+                                    ],
+                                    "description": "What the command is: an app's tests, a build, a lint, a lifecycle plan or a conformance run. test when omitted."
+                                }
+                            },
+                            "patternProperties": {
+                                "^x-": true
+                            },
+                            "additionalProperties": false
+                        }
+                    ]
+                },
+                "checks": {
+                    "$ref": "#/$defs/path",
+                    "description": "The directory, from the workspace root, where a work item's builder writes the check for its item. When omitted the orchestrator chooses, such as <the first member of builds>/checks."
+                },
+                "builders": {
+                    "$ref": "#/$defs/name",
+                    "description": "The member that declares the builder agents, such as the one whose agents/ holds them. tiers says which of them builds at which tier (#3152)."
+                },
+                "tiers": {
+                    "type": "array",
+                    "minItems": 1,
+                    "description": "Which builder agent builds at which tier (#3152, ws-094), replacing studio's studio/role and studio/tier Agent metadata. Each entry names a tier, in the vocabulary of the work kind's work.tier.tiers (#3147), and an agent the builders member declares, by its name. An entry with kinds builds only members of those kinds, so an infra builder and an app builder can share a tier; an entry without kinds builds the tier for every other kind. A tier has at most one entry without kinds and at most one per kind, tiers needs builders, and a session names a declared agent session, or the declaration can't be read (declaration-invalid). chant workspace status --json prints builderFor, the agent for each built member and tier. Added in schema 1 by chant 0.103.0, so a declaration that uses it sets minReader to 0.103.0 or newer.",
+                    "items": {
+                        "type": "object",
+                        "required": ["tier", "agent"],
+                        "properties": {
+                            "tier": {
+                                "$ref": "#/$defs/kindName",
+                                "description": "The tier, such as small, medium or large: a word of the work kind's work.tier.tiers, which a work item's tier or the slice-tier decision point answers."
+                            },
+                            "agent": {
+                                "type": "string",
+                                "minLength": 1,
+                                "pattern": "^[^\\u0000-\\u001f]+$",
+                                "description": "The builder agent's name, as the builders member declares it (such as an Agent of the fountain lexicon in its agents/)."
+                            },
+                            "kinds": {
+                                "type": "array",
+                                "minItems": 1,
+                                "uniqueItems": true,
+                                "items": { "$ref": "#/$defs/kindName" },
+                                "description": "The member kinds this agent builds at the tier, such as app or terraform. Without it, every kind no other entry of the tier names."
+                            },
+                            "session": {
+                                "$ref": "#/$defs/name",
+                                "description": "The declared agent session (agents) the builder writes as, so its write scope is that session's. Optional: without it the orchestrator chooses."
+                            }
+                        },
+                        "patternProperties": { "^x-": true },
+                        "additionalProperties": false
+                    }
+                },
+                "publish": {
+                    "type": "object",
+                    "description": "Where a finished build is published: its branch is pushed and a pull request opened against repo's base. The repo is the record, so an orchestrator reads this instead of being told the target in its environment.",
+                    "required": [
+                        "repo"
+                    ],
+                    "properties": {
+                        "forge": {
+                            "enum": [
+                                "github"
+                            ],
+                            "description": "The forge repo is on. github when omitted."
+                        },
+                        "repo": {
+                            "type": "string",
+                            "pattern": "^[A-Za-z0-9][A-Za-z0-9-]{0,38}/[A-Za-z0-9._-]{1,100}$",
+                            "description": "The repository the pull request is opened on, as owner/name."
+                        },
+                        "base": {
+                            "type": "string",
+                            "minLength": 1,
+                            "description": "The branch the pull request targets. The repository's default branch when omitted."
+                        },
+                        "branchPrefix": {
+                            "type": "string",
+                            "minLength": 1,
+                            "pattern": "^[A-Za-z0-9._/-]+$",
+                            "description": "What the published branch's name starts with; the work item's id follows, as in box/ and then box/work-012. chant/work/ when omitted, the work lease's own branch."
+                        },
+                        "head": {
+                            "type": "string",
+                            "pattern": "^[A-Za-z0-9][A-Za-z0-9-]{0,38}/[A-Za-z0-9._-]{1,100}$",
+                            "description": "The repository the branch is pushed to when it isn't repo, as owner/name: a fork, so the pull request comes from <head owner>:<branch>. A runtime that publishes for one contributor's fork supplies that per contributor instead (arugula-salad/studio#242); this names a fork the whole workspace publishes from."
+                        }
+                    },
+                    "patternProperties": {
+                        "^x-": true
+                    },
+                    "additionalProperties": false
+                }
+            },
+            "patternProperties": {
+                "^x-": true
+            },
+            "additionalProperties": false
+        },
+        "boxListing": {
+            "type": "object",
+            "description": "What the box shows of itself on a home site that lists boxes (#3146, #3154): whether it is listed, its title and one line, and a cover image kept as a file in the repo. A box's listing is configuration, so changing it is a reviewed change (ws-074). chant workspace status --json and chant workspace graph --json print it under the member's box, with the cover's sha256. Added in schema 1 by chant 0.102.0, so a declaration that uses it sets minReader to 0.102.0 or newer.",
+            "properties": {
+                "published": {
+                    "type": "boolean",
+                    "description": "Whether the box is listed. true when omitted: a box is listed unless its owner takes it out."
+                },
+                "title": {
+                    "type": "string",
+                    "maxLength": 60,
+                    "pattern": "^[^\\u0000-\\u001f\\u007f-\\u009f]*$",
+                    "description": "The box's title, one line of at most 60 characters. Empty when omitted, and a reader then shows a name of its own."
+                },
+                "line": {
+                    "type": "string",
+                    "maxLength": 140,
+                    "pattern": "^[^\\u0000-\\u001f\\u007f-\\u009f]*$",
+                    "description": "One line saying what the box is, at most 140 characters. Empty when omitted."
+                },
+                "cover": {
+                    "$ref": "#/$defs/path",
+                    "description": "A PNG, JPEG or WebP picture of the box, as a file from the workspace root. None when omitted."
+                }
+            },
+            "patternProperties": {
+                "^x-": true
+            },
+            "additionalProperties": false
+        },
+        "boxReplicate": {
+            "type": "object",
+            "description": "Where the box's work in progress is replicated, so a box that is lost, reclaimed or corrupted before anyone commits loses nothing (#3172, ws-085). Work in progress is the work branches (chant/work/...), the kept attempts (refs/chant/kept/..., #3147), the snapshots chant workspace wip save takes of each branch's working tree, uncommitted records included (refs/chant/wip/<branch>), and the ledger branch, chant/lifecycle. chant pushes them to remote under their own names and never forces a push. Opt-in: a box block without it replicates nothing. At most one box block in a declaration declares one, or the declaration can't be read (declaration-invalid). chant workspace status --json prints it under the member's box, with every default filled in, and reports in replication how far each ref is from the remote. Added in schema 1 by chant 0.103.0, so a declaration that uses it sets minReader to 0.103.0 or newer.",
+            "properties": {
+                "remote": {
+                    "type": "string",
+                    "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$",
+                    "description": "The git remote to push to, by name: the repository's own remote, such as origin, or a mirror the host adds to the box's checkout with its credential, since a box holds none (#2726). origin when omitted."
+                },
+                "refs": {
+                    "type": "array",
+                    "minItems": 1,
+                    "uniqueItems": true,
+                    "description": "What is replicated: work (the branches under chant/work/), kept (the kept attempts under refs/chant/kept/), wip (the snapshots under refs/chant/wip/) and ledger (the chant/lifecycle branch). All four when omitted.",
+                    "items": {
+                        "enum": [
+                            "work",
+                            "kept",
+                            "wip",
+                            "ledger"
+                        ]
+                    }
+                },
+                "on": {
+                    "type": "array",
+                    "uniqueItems": true,
+                    "description": "When chant pushes on its own: save, after each chant workspace wip save, and release, after a work lease is released (chant workspace work release, or a run of an Op under a work lease ending, which is when a kept attempt is written). Both when omitted; an empty list leaves every push to chant workspace wip push. A record write never pushes, because chant's record writes never run git (ws-074).",
+                    "items": {
+                        "enum": [
+                            "save",
+                            "release"
+                        ]
+                    }
+                },
+                "every": {
+                    "type": "string",
+                    "pattern": "^[1-9][0-9]*(s|m|h)$",
+                    "description": "How often the host runs chant workspace wip push on a schedule of its own, such as 10m, beside the pushes on save and release. chant runs no scheduler; it only states the interval. None when omitted."
+                }
+            },
+            "patternProperties": {
+                "^x-": true
+            },
+            "additionalProperties": false
+        },
+        "boxShip": {
+            "type": "object",
+            "description": "How the box ships its staged work to its own site (ws-100): the people working on a box see the working tree at once, everyone else sees the last release, and a person ships. op is the Op in the box member that does it: its own steps commit the staged tree as one commit by the person shipping (named to it in CHANT_SHIP_BY) with a Chant-Record trailer for each work item it lands, then release that commit to the box's site, stopping at gate, and record the release in env's release ledger. chant runs none of it; a surface runs chant run <op> in the member's directory and approves the gate as for any Op. chant workspace status --json prints it under the member's box with the commit the site serves (the latest release in env's ledger) and what is waiting to ship (the files changed between that commit and the working tree, bookkeeping left out). Added in schema 1 by chant 0.104.0, so a declaration that uses it sets minReader to 0.104.0 or newer.",
+            "required": [
+                "op"
+            ],
+            "properties": {
+                "op": {
+                    "type": "string",
+                    "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$",
+                    "description": "The name of the Op in the box member that ships, as chant run takes it."
+                },
+                "gate": {
+                    "type": "string",
+                    "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$",
+                    "description": "The gate the Op stops at for a person's approval. ship when omitted."
+                },
+                "env": {
+                    "type": "string",
+                    "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$",
+                    "description": "The environment whose release ledger, under the box member, the Op records each release in. box when omitted."
+                },
+                "bookkeeping": {
+                    "type": "array",
+                    "uniqueItems": true,
+                    "description": "Path prefixes from the workspace root whose changes are bookkeeping, such as the record directories, and never count as waiting to ship. None when omitted.",
+                    "items": {
+                        "type": "string",
+                        "minLength": 1,
+                        "pattern": "^(?!/)(?!.*(^|/)\\.\\.(/|$))[^\\n]+$"
+                    }
+                }
+            },
+            "patternProperties": {
+                "^x-": true
+            },
+            "additionalProperties": false
+        },
         "boxService": {
             "type": "object",
             "description": "A service a box runs under its supervisor (#2880).",
@@ -920,6 +1251,39 @@
                 }
             }
         },
+        "protectedPath": {
+            "description": "A protected path: a glob from the workspace root, or { path, except } for a JSON file whose listed top-level keys, or the values JSON Pointers name, may still change.",
+            "oneOf": [
+                {
+                    "$ref": "#/$defs/fileGlob"
+                },
+                {
+                    "type": "object",
+                    "required": [
+                        "path"
+                    ],
+                    "properties": {
+                        "path": {
+                            "$ref": "#/$defs/fileGlob"
+                        },
+                        "except": {
+                            "type": "array",
+                            "minItems": 1,
+                            "uniqueItems": true,
+                            "description": "What a write may change in the JSON file: a top-level key, or, for an entry starting with /, the values a JSON Pointer matches, where a * token matches every key or array index at its level, such as /members/*/box/listing for every box's listing (#3308). A change anywhere else in the file, or to a file that doesn't parse as a JSON object before and after, is still outside the scope.",
+                            "items": {
+                                "type": "string",
+                                "minLength": 1
+                            }
+                        }
+                    },
+                    "patternProperties": {
+                        "^x-": true
+                    },
+                    "additionalProperties": false
+                }
+            ]
+        },
         "classScope": {
             "type": "object",
             "description": "A principal class's write scope.",
@@ -939,6 +1303,13 @@
                         }
                     ]
                 },
+                "protected": {
+                    "type": "array",
+                    "description": "Paths the class may not write, even inside a member it may (#3146, ws-077): each a glob from the workspace root, or { path, except } for a JSON file the class may change only in the top-level keys except names. An entry protects the files it matches and everything under a directory it matches. A record file is judged by records, not here. Added in schema 1 by chant 0.102.0, so a declaration that uses it sets minReader to 0.102.0 or newer.",
+                    "items": {
+                        "$ref": "#/$defs/protectedPath"
+                    }
+                },
                 "records": {
                     "$ref": "#/$defs/recordScope",
                     "description": "The record kinds the class may write, and how. Without it, every kind in reach, with every verb. A kind a member declares is in reach when that member is; the workspace's own kinds always are."
@@ -951,8 +1322,15 @@
         },
         "agentScope": {
             "type": "object",
-            "description": "The agent class's write scope. Its members are always its session's one member, so only the record kinds can be set.",
+            "description": "The agent class's write scope. Its members are always its session's one member, so only the record kinds and the protected paths can be set.",
             "properties": {
+                "protected": {
+                    "type": "array",
+                    "description": "Paths the class may not write, even inside a member it may (#3146, ws-077): each a glob from the workspace root, or { path, except } for a JSON file the class may change only in the top-level keys except names. An entry protects the files it matches and everything under a directory it matches. A record file is judged by records, not here. Added in schema 1 by chant 0.102.0, so a declaration that uses it sets minReader to 0.102.0 or newer.",
+                    "items": {
+                        "$ref": "#/$defs/protectedPath"
+                    }
+                },
                 "records": {
                     "$ref": "#/$defs/recordScope",
                     "description": "The record kinds an agent may write, and how. Without it, every kind in reach of its member, with every verb."

package/dist/workspace/environments.d.ts

@@ -15,8 +15,13 @@
  *   (`../cli/handlers/run.ts`), when neither the config nor the ledger names
  *   it.
  *
- * The component contract declares no environments, so every component of a
- * member lists the member's environments.
+ * A component may also declare environments of its own (#3153, ws-095),
+ * each with the site a release goes to there: the runtime that hosts it, its
+ * URL, a custom domain and the git remote its lifecycle records are pushed
+ * to. Each declared environment the member already lists carries that site,
+ * and one it doesn't is added with source `component` when `chant run --env`
+ * would take it, or left out with `environments-component-undeclared` when
+ * the config's environments don't cover it.
  *
  * `chant run --env` refuses a name the config's `environments` doesn't cover
  * whenever it declares any (`unknownEnvError` in `../env.ts`), so a ledger
@@ -29,11 +34,13 @@
  * `--at` exported. The ledger is always the local `chant/lifecycle` branch,
  * as for `workspace status`, and is never fetched.
  */
+import { type EnvironmentDeclaration } from "../config.js";
+import type { ComponentEnvironmentDeclaration } from "../components/component.js";
 import { type MemberRuntimes } from "./runtimes.js";
 /** The environment `chant run --components` deploys to without `--env`. */
 export declare const LOCAL_ENVIRONMENT = "local";
 /** Why a member's environments are only `local`, or leave out one the ledger has. Closed: part of the read contract. */
-export declare const ENVIRONMENT_REASON_CODES: readonly ["runtimes-config-unreadable", "environments-none-declared", "environments-ledger-undeclared", "environments-ledger-unreadable"];
+export declare const ENVIRONMENT_REASON_CODES: readonly ["runtimes-config-unreadable", "environments-none-declared", "environments-ledger-undeclared", "environments-ledger-unreadable", "environments-component-undeclared"];
 export type EnvironmentReasonCode = (typeof ENVIRONMENT_REASON_CODES)[number];
 export interface EnvironmentReason {
     code: EnvironmentReasonCode;
@@ -45,11 +52,20 @@ export interface ComponentEnvironment {
     name: string;
     /** True for the environment `chant run --components` deploys to without `--env`. */
     default: boolean;
-    /** Where the name came from; the first of config, ledger and builtin that names it. */
-    source: "config" | "ledger" | "builtin";
-    /** The command that deploys the component there on the default runtime, run in the member's directory. */
+    /** Where the name came from; the first of config, ledger, builtin and the component's own environments that names it. */
+    source: "config" | "ledger" | "builtin" | "component";
+    /** Where a release of the component goes in this environment, as the component declares it (#3153), or null when it declares nothing for it. */
+    site: ComponentSite | null;
+    /** The command that deploys the component there, on the site's runtime when the member hosts it and else the default runtime, run in the member's directory. */
     command: string;
 }
+/** A component's declared site in one environment (#3153): every field present, null when not declared. */
+export interface ComponentSite {
+    runtime: string | null;
+    url: string | null;
+    domain: string | null;
+    lifecycle: string | null;
+}
 /** The environments a member's ledger has, or why they couldn't be listed. */
 export interface LedgerEnvironments {
     envs: string[];
@@ -62,9 +78,11 @@ export type LedgerEnvironmentReader = (member: {
 }, cwd: string) => LedgerEnvironments;
 /** What one member's config and ledger say about environments. */
 export interface MemberEnvironments {
-    /** Each environment in list order, without the per-component command. */
-    environments: Omit<ComponentEnvironment, "command">[];
+    /** Each environment in list order, without the per-component site and command. */
+    environments: Omit<ComponentEnvironment, "command" | "site">[];
     reasons: EnvironmentReason[];
+    /** The config's environments, for whether `chant run --env` takes a name: null when the config couldn't be read, `[]` when it declares none. */
+    declared?: EnvironmentDeclaration[] | null;
 }
 /**
  * The environments with a release ledger for `member` on the local
@@ -75,6 +93,14 @@ export interface MemberEnvironments {
 export declare const readLedgerEnvironments: LedgerEnvironmentReader;
 /** Join a member's config and ledger into its environment list, `local` first, then config order, then the ledger's. */
 export declare function memberEnvironments(runtimes: MemberRuntimes | undefined, ledger: LedgerEnvironments | undefined): MemberEnvironments;
-/** The environments one component may deploy to, each with its command line on the member's default runtime. */
-export declare function componentEnvironments(component: string, member: MemberEnvironments | undefined, runtime?: string): ComponentEnvironment[];
+/**
+ * The environments one component may deploy to, each with its command line.
+ * `declared` is what the component's contract says (#3153): an environment
+ * the member lists takes its site, and one it doesn't is added after the
+ * member's when `chant run --env` takes it. `reasons` collects the declared
+ * environments left out because the config's environments don't cover them.
+ * `hosts` are the runtimes the member configures; a site's runtime is used
+ * for the command only when it is one of them.
+ */
+export declare function componentEnvironments(component: string, member: MemberEnvironments | undefined, runtime?: string, declared?: readonly ComponentEnvironmentDeclaration[], hosts?: readonly string[], reasons?: EnvironmentReason[]): ComponentEnvironment[];
 //# sourceMappingURL=environments.d.ts.map

package/dist/workspace/environments.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"environments.d.ts","sourceRoot":"","sources":["../../src/workspace/environments.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAKH,OAAO,EAAiB,KAAK,cAAc,EAAE,MAAM,YAAY,CAAC;AAGhE,2EAA2E;AAC3E,eAAO,MAAM,iBAAiB,UAAU,CAAC;AAEzC,wHAAwH;AACxH,eAAO,MAAM,wBAAwB,2IASK,CAAC;AAC3C,MAAM,MAAM,qBAAqB,GAAG,CAAC,OAAO,wBAAwB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE9E,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,qBAAqB,CAAC;IAC5B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,iDAAiD;AACjD,MAAM,WAAW,oBAAoB;IACnC,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,oFAAoF;IACpF,OAAO,EAAE,OAAO,CAAC;IACjB,uFAAuF;IACvF,MAAM,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;IACxC,0GAA0G;IAC1G,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,8EAA8E;AAC9E,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,MAAM,EAAE,iBAAiB,GAAG,IAAI,CAAC;CAClC;AAED,0EAA0E;AAC1E,MAAM,MAAM,uBAAuB,GAAG,CAAC,MAAM,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,EAAE,GAAG,EAAE,MAAM,KAAK,kBAAkB,CAAC;AAEjH,kEAAkE;AAClE,MAAM,WAAW,kBAAkB;IACjC,yEAAyE;IACzE,YAAY,EAAE,IAAI,CAAC,oBAAoB,EAAE,SAAS,CAAC,EAAE,CAAC;IACtD,OAAO,EAAE,iBAAiB,EAAE,CAAC;CAC9B;AAeD;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,EAAE,uBAkBpC,CAAC;AAEF,wHAAwH;AACxH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,cAAc,GAAG,SAAS,EAAE,MAAM,EAAE,kBAAkB,GAAG,SAAS,GAAG,kBAAkB,CA8BnI;AAED,gHAAgH;AAChH,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,kBAAkB,GAAG,SAAS,EAAE,OAAO,SAAgB,GAAG,oBAAoB,EAAE,CAIhJ"}
+{"version":3,"file":"environments.d.ts","sourceRoot":"","sources":["../../src/workspace/environments.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAGH,OAAO,EAAqE,KAAK,sBAAsB,EAAE,MAAM,WAAW,CAAC;AAC3H,OAAO,KAAK,EAAE,+BAA+B,EAAE,MAAM,yBAAyB,CAAC;AAE/E,OAAO,EAAiB,KAAK,cAAc,EAAE,MAAM,YAAY,CAAC;AAGhE,2EAA2E;AAC3E,eAAO,MAAM,iBAAiB,UAAU,CAAC;AAEzC,wHAAwH;AACxH,eAAO,MAAM,wBAAwB,gLAWK,CAAC;AAC3C,MAAM,MAAM,qBAAqB,GAAG,CAAC,OAAO,wBAAwB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE9E,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,qBAAqB,CAAC;IAC5B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,iDAAiD;AACjD,MAAM,WAAW,oBAAoB;IACnC,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,oFAAoF;IACpF,OAAO,EAAE,OAAO,CAAC;IACjB,yHAAyH;IACzH,MAAM,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,WAAW,CAAC;IACtD,gJAAgJ;IAChJ,IAAI,EAAE,aAAa,GAAG,IAAI,CAAC;IAC3B,gKAAgK;IAChK,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,2GAA2G;AAC3G,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,8EAA8E;AAC9E,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,MAAM,EAAE,iBAAiB,GAAG,IAAI,CAAC;CAClC;AAED,0EAA0E;AAC1E,MAAM,MAAM,uBAAuB,GAAG,CAAC,MAAM,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,EAAE,GAAG,EAAE,MAAM,KAAK,kBAAkB,CAAC;AAEjH,kEAAkE;AAClE,MAAM,WAAW,kBAAkB;IACjC,kFAAkF;IAClF,YAAY,EAAE,IAAI,CAAC,oBAAoB,EAAE,SAAS,GAAG,MAAM,CAAC,EAAE,CAAC;IAC/D,OAAO,EAAE,iBAAiB,EAAE,CAAC;IAC7B,gJAAgJ;IAChJ,QAAQ,CAAC,EAAE,sBAAsB,EAAE,GAAG,IAAI,CAAC;CAC5C;AAeD;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,EAAE,uBAkBpC,CAAC;AAEF,wHAAwH;AACxH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,cAAc,GAAG,SAAS,EAAE,MAAM,EAAE,kBAAkB,GAAG,SAAS,GAAG,kBAAkB,CA8BnI;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,kBAAkB,GAAG,SAAS,EACtC,OAAO,SAAgB,EACvB,QAAQ,GAAE,SAAS,+BAA+B,EAAO,EACzD,KAAK,GAAE,SAAS,MAAM,EAAO,EAC7B,OAAO,GAAE,iBAAiB,EAAO,GAChC,oBAAoB,EAAE,CAqBxB"}