@intentius/chant 0.101.0 → 0.102.0

package/src/workspace/decide.ts

@@ -68,6 +68,8 @@ import { AGENT_ROLE } from "./records-cli";
 import type { SourceVia } from "./source-block";
 import type { RecordSource } from "./record-source";
 import { currentStewardTurn } from "../op/steward-turn";
+import { IdentityError, refuseUnidentified } from "./identity";
+import { scopeSource } from "./write-scope";
 import { RefCASConflictError } from "../lifecycle/git";
 import { readLedgerAnswers, refreshLedger, withLedgerAnswers, writeLedgerAnswer, type LedgerAnswers } from "./answers-ledger";
 
@@ -99,6 +101,8 @@ export const POINTS_WRITE_ERROR_CODES = [
   "record-id-taken",
   /** The answer was given during a steward's turn (#2749): a steward never answers a question, its own or another's. */
   "answer-in-steward-turn",
+  /** An answerer is named by a bare name, and identity.attribution at base is identified (#3163). */
+  "principal-unidentified",
   ...RECORD_REASON_CODES,
 ] as const satisfies readonly ReasonCode[];
 export type PointsWriteErrorCode = (typeof POINTS_WRITE_ERROR_CODES)[number];
@@ -256,7 +260,7 @@ export type PointsWriteDocument =
   | { $schema: string; contract: number; verb: "ask" | "answer"; error: { code: PointsWriteErrorCode; message: string } };
 
 function failure(verb: "ask" | "answer", err: unknown): PointsWriteDocument {
-  if (err instanceof PointsWriteError || err instanceof RecordWriteError || err instanceof RecordReadError) {
+  if (err instanceof PointsWriteError || err instanceof RecordWriteError || err instanceof RecordReadError || err instanceof IdentityError) {
     return { $schema: POINTS_WRITE_SCHEMA_ID, contract: POINTS_WRITE_CONTRACT_VERSION, verb, error: { code: err.code as PointsWriteErrorCode, message: err.message } };
   }
   if (err instanceof WorkspaceReadError) {
@@ -611,6 +615,8 @@ export async function answerPoint(opts: AnswerPointOptions): Promise<PointsWrite
         `this is the steward ${turn.steward}'s turn, and a steward never answers a decision point: a person answers ${opts.id} through hud or \`chant workspace points answer\` at a shell`,
       );
     }
+    // #3163: under identity.attribution "identified" at base, each answerer is a forge identity or a signer.
+    refuseUnidentified(scopeSource(opts.cwd), opts.by, "--by");
     const kinds = await answerKindFiles(opts.cwd, opts.kind);
     if (kinds.length === 0) throw new PointsWriteError("points-undeclared", "no record kind with an answers block is declared: name one with --kind, or declare one in chant.workspace.json");
     let found:

package/src/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.-]+)?$"
@@ -444,7 +484,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), and its listing what the box shows of itself (#3146). 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 +498,12 @@
             "$ref": "#/$defs/boxService"
           }
         },
+        "factory": {
+          "$ref": "#/$defs/boxFactory"
+        },
+        "listing": {
+          "$ref": "#/$defs/boxListing"
+        },
         "capabilities": {
           "type": "array",
           "description": "Each capability the box reaches outside itself, named once. None when omitted.",
@@ -530,6 +576,142 @@
       },
       "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. Which agent builds at which tier is #3152; the tier vocabulary is the work kind's work.tier.tiers (#3147)."
+        },
+        "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
+    },
     "boxService": {
       "type": "object",
       "description": "A service a box runs under its supervisor (#2880).",
@@ -920,6 +1102,39 @@
         }
       }
     },
+    "protectedPath": {
+      "description": "A protected path: a glob from the workspace root, or { path, except } for a JSON file whose listed top-level keys may still change.",
+      "oneOf": [
+        {
+          "$ref": "#/$defs/fileGlob"
+        },
+        {
+          "type": "object",
+          "required": [
+            "path"
+          ],
+          "properties": {
+            "path": {
+              "$ref": "#/$defs/fileGlob"
+            },
+            "except": {
+              "type": "array",
+              "minItems": 1,
+              "uniqueItems": true,
+              "description": "Top-level keys of the JSON file a write may change. 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 +1154,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 +1173,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/src/workspace/declaration.ts

@@ -107,9 +107,11 @@ export interface ChangesPolicy {
   ignore: string[];
 }
 
-/** The core principal classes (#2524 D5). */
+/** The core principal classes (#2524 D5). A pinned package may supply domain classes too (#3080, `principal-classes.ts`). */
 export const PRINCIPAL_CLASSES = ["human", "agent", "runner", "service"] as const;
-export type PrincipalClass = (typeof PRINCIPAL_CLASSES)[number];
+export type CorePrincipalClass = (typeof PRINCIPAL_CLASSES)[number];
+/** A class name: a core class, or a domain class a pinned package supplies (#3080). */
+export type PrincipalClass = string;
 
 /** How a record is written, as the records commands name it (#2548). */
 export const WRITE_VERBS = ["new", "amend", "review", "close"] as const;
@@ -121,11 +123,46 @@ export interface ClassScope {
   members: string[] | null;
   /** Kind name to the verbs the class may write it with, or null for every kind in reach with every verb. */
   records: Record<string, WriteVerb[]> | null;
+  /** Paths the class may not write even inside a member it may (#3146, ws-077), in file order. Empty when the entry lists none. */
+  protected: ProtectedPath[];
   pointer: string;
 }
 
-/** The declaration's `writeScope` block: an entry per restricted class. A class with no entry is not restricted. */
-export type WriteScope = Partial<Record<PrincipalClass, ClassScope>>;
+/**
+ * A protected path in a write scope (#3146, ws-077): a glob from the
+ * workspace root. It protects the files it matches and everything under a
+ * directory it matches. `except` names top-level keys of a JSON file a write
+ * may still change; empty when the entry allows none.
+ */
+export interface ProtectedPath {
+  path: string;
+  except: string[];
+}
+
+/**
+ * The declaration's `writeScope` block: an entry per restricted class, in
+ * file order. A class with no entry is not restricted. A key may name a
+ * domain class a pinned package supplies (#3080); whether one does is known
+ * only once the pins are read, so an unknown key is judged where the scope
+ * is applied, not here.
+ */
+export type WriteScope = Record<PrincipalClass, ClassScope>;
+
+/** A gate the declaration's `identity.gates` names (#3163, ws-080): it passes only on a signed approval. */
+export interface SignedGate {
+  gate: string;
+  /** The class the signer must be in, or null for any signer the signers file at base lists. */
+  class: PrincipalClass | null;
+  pointer: string;
+}
+
+/** The declaration's `identity` block (#3163, ws-080), read at base. */
+export interface IdentityPolicy {
+  /** `identified`: a person-attributed write must name a forge identity, a signer at base, or an agent, runner or service principal. */
+  attribution: "any" | "identified";
+  /** By gate name. */
+  gates: Record<string, SignedGate>;
+}
 
 /** An agent session the declaration names (#2524 D20, #2548): bound to one member. */
 export interface AgentDeclaration {
@@ -254,10 +291,63 @@ export interface BoxDeclaration {
    * `spriteApplyServices` read them with `box: true`.
    */
   services: BoxService[];
+  /** What the box builds and how (#3146, ws-077), or null when the block declares no factory. */
+  factory: BoxFactory | null;
+  /** What the box shows of itself on a home site (#3146), or null when the block declares no listing. */
+  listing: BoxListing | null;
+  /** The block's JSON Pointer in the file, for messages. */
+  pointer: string;
+}
+
+/** What a check command is (#3146). */
+export const FACTORY_CHECK_KINDS = ["test", "build", "lint", "plan", "conformance"] as const;
+export type FactoryCheckKind = (typeof FACTORY_CHECK_KINDS)[number];
+
+/**
+ * A box's factory (#3146, ws-077): what it builds, how a build is checked,
+ * which member declares the builder agents and where a finished build is
+ * published. Defaults are filled in, so a reader never guesses one.
+ */
+export interface BoxFactory {
+  /** The members the factory builds, in file order; at least one. */
+  builds: string[];
+  /** The verdict command, run from the workspace root, or null when none is declared. */
+  check: { run: string; kind: FactoryCheckKind } | null;
+  /** Where a work item's builder writes its check, from the workspace root, or null for the orchestrator's choice. */
+  checks: string | null;
+  /** The member that declares the builder agents, or null when none is named. */
+  builders: string | null;
+  /** Where a finished build is published, or null when the factory doesn't publish past the box. */
+  publish: FactoryPublish | null;
   /** The block's JSON Pointer in the file, for messages. */
   pointer: string;
 }
 
+/** Where a finished build goes (#3146): its branch is pushed and a pull request opened against `repo`'s `base`. */
+export interface FactoryPublish {
+  forge: "github";
+  /** owner/name. */
+  repo: string;
+  /** The branch the pull request targets, or null for the repository's default branch. */
+  base: string | null;
+  /** What the published branch's name starts with, before the work item's id. */
+  branchPrefix: string;
+  /** The repository the branch is pushed to when it isn't `repo` (a fork), as owner/name, or null. */
+  head: string | null;
+}
+
+/** The branch prefix a publish target uses when it names none: the work lease's own branch. */
+export const DEFAULT_PUBLISH_BRANCH_PREFIX = "chant/work/";
+
+/** What a box shows of itself (#3146, #3154). */
+export interface BoxListing {
+  published: boolean;
+  title: string;
+  line: string;
+  /** The cover image, from the workspace root, or null. */
+  cover: string | null;
+}
+
 /** A service a box runs under its supervisor (#2880). */
 export interface BoxService {
   /** Unique in the box. */
@@ -375,6 +465,8 @@ export interface Declaration {
   writeScope: WriteScope | null;
   /** The agent sessions, in file order (#2548). */
   agents: AgentDeclaration[];
+  /** Who a person-attributed write may name, and which gates need a signed approval (#3163), or null when the declaration has no `identity` block. */
+  identity: IdentityPolicy | null;
   /** The file, relative to the workspace root's tree (`chant.workspace.json` or `.jsonc`). */
   file: string;
 }
@@ -699,6 +791,9 @@ export function parseDeclaration(text: string, file: string, reader: string = re
     const problem = m.box ? boxServicesProblem(m.name, m.box.services) : null;
     if (problem) throw new WorkspaceReadError("declaration-invalid", problem.message, at(problem.pointer));
   }
+  // One factory, building and naming declared members (#3146).
+  const factory = factoryProblem(members);
+  if (factory) throw new WorkspaceReadError("declaration-invalid", factory.message, at(factory.pointer));
 
   // A diagram name is given once across the declaration (#2764): a reader keys diagrams by name.
   const ownDiagrams = diagramsOf(obj.diagrams, null, "/diagrams");
@@ -738,21 +833,21 @@ export function parseDeclaration(text: string, file: string, reader: string = re
     changes: changesOf(obj.changes as Record<string, unknown> | undefined),
     writeScope,
     agents,
+    identity: identityOf(obj.identity),
     file,
   };
 }
 
 /**
  * The `writeScope` block, already validated, with the rule the schema can't
- * say (#2548): a member it names is a declared member.
+ * say (#2548): a member it names is a declared member. Its keys are kept in
+ * file order: the core classes and any domain class (#3080).
  */
 function writeScopeOf(raw: unknown, members: Member[], at: (pointer: string, key?: boolean) => ErrorLocation): WriteScope | null {
   if (raw === undefined) return null;
-  const block = raw as Partial<Record<PrincipalClass, { members?: "*" | string[]; records?: Record<string, WriteVerb[]> }>>;
+  const block = raw as Record<PrincipalClass, { members?: "*" | string[]; records?: Record<string, WriteVerb[]>; protected?: (string | { path: string; except?: string[] })[] }>;
   const out: WriteScope = {};
-  for (const cls of PRINCIPAL_CLASSES) {
-    const entry = block[cls];
-    if (entry === undefined) continue;
+  for (const [cls, entry] of Object.entries(block)) {
     const pointer = `/writeScope/${cls}`;
     const list = entry.members === undefined || entry.members === "*" ? null : [...entry.members];
     for (const [i, name] of (list ?? []).entries()) {
@@ -765,7 +860,8 @@ function writeScopeOf(raw: unknown, members: Member[], at: (pointer: string, key
       }
     }
     const records = entry.records === undefined ? null : Object.fromEntries(Object.entries(entry.records).map(([k, v]) => [k, [...v]]));
-    out[cls] = { members: list, records, pointer };
+    const guarded = (entry.protected ?? []).map((p) => (typeof p === "string" ? { path: p, except: [] } : { path: p.path, except: [...(p.except ?? [])] }));
+    out[cls] = { members: list, records, protected: guarded, pointer };
   }
   return out;
 }
@@ -775,6 +871,17 @@ function writeScopeOf(raw: unknown, members: Member[], at: (pointer: string, key
  * (#2548): names are unique, each names a declared member, and a principal
  * is listed by one session at most.
  */
+/** The `identity` block, already validated by the schema (#3163). */
+function identityOf(raw: unknown): IdentityPolicy | null {
+  if (raw === undefined) return null;
+  const block = raw as { attribution?: "any" | "identified"; gates?: Record<string, { class?: string }> };
+  const gates: Record<string, SignedGate> = {};
+  for (const [gate, entry] of Object.entries(block.gates ?? {})) {
+    gates[gate] = { gate, class: entry.class ?? null, pointer: `/identity/gates/${gate.replace(/~/g, "~0").replace(/\//g, "~1")}` };
+  }
+  return { attribution: block.attribution ?? "any", gates };
+}
+
 function agentsOf(raw: unknown, members: Member[], at: (pointer: string, key?: boolean) => ErrorLocation): AgentDeclaration[] {
   const agents = ((raw as { name: string; member: string; principals?: string[] }[] | undefined) ?? []).map((a, i) => ({
     name: a.name,
@@ -856,7 +963,17 @@ function boxOf(raw: unknown, pointer: string): BoxDeclaration | null {
     cookies?: string[];
     intent?: string;
     services?: { name: string; cmd: string; needs?: string[]; httpPort?: number; duration?: string; health?: string; optional?: boolean }[];
+    factory?: {
+      builds: string[];
+      check?: string | { run: string; kind?: FactoryCheckKind };
+      checks?: string;
+      builders?: string;
+      publish?: { forge?: "github"; repo: string; base?: string; branchPrefix?: string; head?: string };
+    };
+    listing?: { published?: boolean; title?: string; line?: string; cover?: string };
   };
+  const f = b.factory;
+  const l = b.listing;
   return {
     capabilities: (b.capabilities ?? []).map((c, i) => ({ name: c.name, broker: c.broker ?? null, scope: [...(c.scope ?? [])], pointer: `${pointer}/capabilities/${i}` })),
     // The schema requires host and slot together, and host for ports, state and cookies.
@@ -875,10 +992,57 @@ function boxOf(raw: unknown, pointer: string): BoxDeclaration | null {
       optional: s.optional ?? false,
       pointer: `${pointer}/services/${i}`,
     })),
+    factory:
+      f === undefined
+        ? null
+        : {
+            builds: [...f.builds],
+            check: f.check === undefined ? null : typeof f.check === "string" ? { run: f.check, kind: "test" } : { run: f.check.run, kind: f.check.kind ?? "test" },
+            checks: f.checks ?? null,
+            builders: f.builders ?? null,
+            publish:
+              f.publish === undefined
+                ? null
+                : {
+                    forge: f.publish.forge ?? "github",
+                    repo: f.publish.repo,
+                    base: f.publish.base ?? null,
+                    branchPrefix: f.publish.branchPrefix ?? DEFAULT_PUBLISH_BRANCH_PREFIX,
+                    head: f.publish.head ?? null,
+                  },
+            pointer: `${pointer}/factory`,
+          },
+    listing: l === undefined ? null : { published: l.published ?? true, title: l.title ?? "", line: l.line ?? "", cover: l.cover ?? null },
     pointer,
   };
 }
 
+/**
+ * The rules the schema can't say about the factories (#3146, ws-077): at most
+ * one box block declares one, and the members its builds and builders name
+ * are declared members.
+ */
+function factoryProblem(members: readonly Member[]): { message: string; pointer: string } | null {
+  const declaring = members.filter((m) => m.box?.factory);
+  if (declaring.length > 1) {
+    return {
+      message: `members ${declaring[0].name} and ${declaring[1].name} both declare a factory in their box block; a workspace has one factory, so an orchestrator reads one`,
+      pointer: declaring[1].box!.factory!.pointer,
+    };
+  }
+  const factory = declaring[0]?.box?.factory;
+  if (!factory) return null;
+  const known = () => members.map((m) => m.name).join(", ");
+  const j = factory.builds.findIndex((name) => !members.some((m) => m.name === name));
+  if (j >= 0) {
+    return { message: `the factory builds ${JSON.stringify(factory.builds[j])}, which is not a declared member; declared members: ${known()}`, pointer: `${factory.pointer}/builds/${j}` };
+  }
+  if (factory.builders !== null && !members.some((m) => m.name === factory.builders)) {
+    return { message: `the factory's builders names ${JSON.stringify(factory.builders)}, which is not a declared member; declared members: ${known()}`, pointer: `${factory.pointer}/builders` };
+  }
+  return null;
+}
+
 /**
  * The rules the schema can't say about a box's services (#2880), as a
  * message and the pointer to show, or null when they hold: each name is

package/src/workspace/graph-cli.ts

@@ -30,6 +30,7 @@ import { tmpdir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { formatError } from "../cli/format";
 import type { CommandContext, ParsedArgs } from "../cli/registry";
+import { graphBox, plantability, type Plantable } from "./box-factory";
 import { composeWorkspaceGraph, readMemberIr, type ComposedMember, type ComposeInput, type WorkspaceGraph } from "./compose-graph";
 import { openGraphCache, splitCached, storeReads, withoutUnits } from "./graph-cache";
 import { readDeclaration, readerVersion, WORKSPACE_ERROR_CODES, WorkspaceReadError, type ErrorLocation } from "./declaration";
@@ -67,7 +68,7 @@ interface Head {
 }
 
 export type GraphDocument =
-  | (Head & { at: string | null } & WorkspaceGraph)
+  | (Head & { at: string | null; plantable: Plantable } & WorkspaceGraph)
   | (Head & { error: { code: GraphErrorCode; message: string; location: ErrorLocation | null } });
 
 export interface GraphQuery {
@@ -258,6 +259,8 @@ export async function workspaceGraph(query: GraphQuery): Promise<GraphResult> {
     }
     // Links (#2539) resolve against the declaration that was read, the revision's for --at, and the kinds installed now.
     const graph = composeWorkspaceGraph({ name: declaration.name, root: located.root }, inputs, { declaration, kinds });
+    // The box's factory and listing (#3146), from the declaration read, so --at gives them at that revision.
+    for (const member of graph.members) member.box = graphBox(declaration.members.find((m) => m.name === member.name)?.box ?? null, located.tree);
     // Nested workspaces (#2551, ws-071): read-only, through their own chant workspace graph.
     const nestedFailed = await expandNested(graph, declaration.members, query, located.rootOnDisk, located.at);
     let recordsFailed = false;
@@ -276,7 +279,7 @@ export async function workspaceGraph(query: GraphQuery): Promise<GraphResult> {
         query.onStderr?.(`${formatError({ message: `--kind ${query.kind}: ${err.code}: ${err.message}`, hint: USAGE })}\n`);
       }
     }
-    return { doc: { ...head, at: located.at, ...graph }, failed: failed || recordsFailed || nestedFailed, ...(components ? { components } : {}) };
+    return { doc: { ...head, at: located.at, plantable: plantability(declaration), ...graph }, failed: failed || recordsFailed || nestedFailed, ...(components ? { components } : {}) };
   } catch (err) {
     if (!(err instanceof WorkspaceReadError)) throw err;
     return { doc: { ...head, error: { code: err.code, message: err.message, location: err.location ?? null } }, failed: true };