@intentius/chant 0.102.0 → 0.104.1

package/src/workspace/decision-points.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://intentius.io/chant/schemas/workspace/decision-points/v1/decision-points.schema.json",
   "title": "Decision points",
-  "description": "A workspace's decision points (ws-058, #2738): the recurring questions it asks of its own graph, declared as data in a JSON file that an answer record kind names in `answers.points`. Each point is a typed question (`noul`, `choice` with 2 to 255 options, or `score` with 2 to 10 ordered levels, the question types of the POST /v1/systemone wire format, #2491), the inputs it reads, each named as a read-contract output, and an ordered chain of deciders: `table` rows, `model` deciders with a backend, a pinned model id and a threshold, and a `quorum` of people, always last. What JSON Schema cannot say is checked in code (`points.ts`): an input's output is one the read contract has, a table row tests declared inputs and answers a candidate, a field belongs to its decider's kind, a model id is pinned rather than an alias, and the chain ends in its one quorum. Unknown fields are refused, except fields whose names start with x-.",
+  "description": "A workspace's decision points (ws-058, #2738): the recurring questions it asks of its own graph, declared as data in a JSON file that an answer record kind names in `answers.points`. Each point is a typed question (`noul`, `choice` with 2 to 255 options, or `score` with 2 to 10 ordered levels, the question types of the POST /v1/systemone wire format, #2491), the inputs it reads, each named as a read-contract output, and an ordered chain of deciders: `table` rows, `model` deciders with a backend, a pinned model id and a threshold, and a `quorum` of people, always last. What JSON Schema cannot say is checked in code (`points.ts`): an input's output is one the read contract has, a table row tests declared inputs and answers a candidate, a field belongs to its decider's kind, a model id is pinned rather than an alias, and the chain ends in its one quorum. A point declared `adhoc` (#3403) leaves out its question's criteria: the question's text and candidates come with each ask (`points ask --candidates`), and its chain is one quorum. Unknown fields are refused, except fields whose names start with x-.",
   "type": "object",
   "required": ["points"],
   "properties": {
@@ -23,10 +23,14 @@
       "required": ["title", "question", "inputs", "deciders"],
       "properties": {
         "title": { "$ref": "#/$defs/text" },
+        "adhoc": {
+          "type": "boolean",
+          "description": "An ad-hoc point (#3403): the question declares its type and what the asks are for, and no criteria. Each ask gives the question's text and its candidates, and the answer record keeps them, so people's answer is checked against them. Its chain is one quorum."
+        },
         "question": { "$ref": "#/$defs/question" },
         "inputs": {
           "type": "object",
-          "description": "The state the deciders see, input name to description. A name is a read-contract output (record, decision, work-item, finding, region, commit, member, gate, release, environment, component), optionally followed by dotted field names, such as work-item.fits_small: a field of that output, or a value the caller derives from it. The caller supplies the values; a table row can only test these names.",
+          "description": "The state the deciders see, input name to description. A name is a read-contract output (record, decision, work-item, finding, region, commit, node, member, gate, release, environment, component, ask), optionally followed by dotted field names, such as work-item.fits_small: a field of that output, or a value the caller derives from it. The caller supplies the values; a table row can only test these names.",
           "minProperties": 1,
           "propertyNames": { "pattern": "^[A-Za-z_][A-Za-z0-9_-]*(\\.[A-Za-z_][A-Za-z0-9_]*)*$" },
           "additionalProperties": { "type": "string" }
@@ -38,11 +42,14 @@
         }
       },
       "patternProperties": { "^x-": true },
-      "additionalProperties": false
+      "additionalProperties": false,
+      "if": { "properties": { "adhoc": { "const": true } }, "required": ["adhoc"] },
+      "then": { "properties": { "question": { "not": { "required": ["criteria"] } } } },
+      "else": { "properties": { "question": { "required": ["criteria"] } } }
     },
     "question": {
       "type": "object",
-      "required": ["type", "instructions", "criteria"],
+      "required": ["type", "instructions"],
       "properties": {
         "type": { "enum": ["noul", "choice", "score"] },
         "instructions": { "$ref": "#/$defs/text" },

package/src/workspace/declaration.schema.json

@@ -369,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.",
@@ -438,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.",
@@ -484,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. 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.",
+      "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",
@@ -504,6 +524,18 @@
         "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.",
@@ -634,7 +666,41 @@
         },
         "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)."
+          "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",
@@ -712,6 +778,89 @@
       },
       "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).",
@@ -1103,7 +1252,7 @@
       }
     },
     "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.",
+      "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"
@@ -1121,7 +1270,7 @@
               "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.",
+              "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

package/src/workspace/declaration.ts

@@ -295,6 +295,63 @@ export interface BoxDeclaration {
   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 command that publishes the box's work (#3165, ws-088), as declared,
+   * or null when the block names none. `chant workspace box publish` runs it
+   * (`box-publish.ts`).
+   */
+  publisher: string | null;
+  /** Where the box's work in progress is replicated (#3172, ws-085), or null when the block declares no policy. */
+  replicate: BoxReplicate | null;
+  /** How the box ships its staged work to its own site (ws-100), or null when the block declares none. */
+  ship: BoxShip | null;
+  /** The block's JSON Pointer in the file, for messages. */
+  pointer: string;
+}
+
+/** The gate a ship Op stops at when the block names none (ws-100). */
+export const DEFAULT_SHIP_GATE = "ship";
+/** The environment a ship Op records its releases in when the block names none (ws-100). */
+export const DEFAULT_SHIP_ENV = "box";
+
+/**
+ * How a box ships its staged work (ws-100): the Op in the box member that
+ * commits the staged tree and releases it to the box's own site, the gate
+ * it stops at, the environment whose release ledger it records each
+ * release in, and the paths that are bookkeeping rather than the app (left
+ * out of what is pending). Defaults are filled in.
+ */
+export interface BoxShip {
+  op: string;
+  gate: string;
+  env: string;
+  /** Path prefixes from the workspace root, in file order, whose changes never count as waiting to ship. */
+  bookkeeping: string[];
+  /** The block's JSON Pointer in the file, for messages. */
+  pointer: string;
+}
+
+/** What a replicate policy pushes (#3172): work branches, kept attempts, work-in-progress snapshots and the ledger branch. */
+export const REPLICATE_REF_CLASSES = ["work", "kept", "wip", "ledger"] as const;
+export type ReplicateRefClass = (typeof REPLICATE_REF_CLASSES)[number];
+
+/** When chant pushes on its own under a replicate policy (#3172). */
+export const REPLICATE_TRIGGERS = ["save", "release"] as const;
+export type ReplicateTrigger = (typeof REPLICATE_TRIGGERS)[number];
+
+/** The remote a replicate policy pushes to when it names none. */
+export const DEFAULT_REPLICATE_REMOTE = "origin";
+
+/**
+ * Where a box's work in progress is replicated (#3172, ws-085), with the
+ * defaults filled in: the git remote, which refs, and when chant pushes on
+ * its own. `every` is an interval for the host's own scheduler.
+ */
+export interface BoxReplicate {
+  remote: string;
+  refs: ReplicateRefClass[];
+  on: ReplicateTrigger[];
+  every: string | null;
   /** The block's JSON Pointer in the file, for messages. */
   pointer: string;
 }
@@ -317,12 +374,25 @@ export interface BoxFactory {
   checks: string | null;
   /** The member that declares the builder agents, or null when none is named. */
   builders: string | null;
+  /** Which builder agent builds at which tier, and for which member kinds (#3152, ws-094), in file order; empty when none is declared. */
+  tiers: FactoryTier[];
   /** 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;
 }
 
+/** One builder agent at one tier (#3152): `kinds` null means every kind no other entry of the tier names. */
+export interface FactoryTier {
+  tier: string;
+  /** The agent's name, as the builders member declares it. */
+  agent: string;
+  /** The member kinds it builds at this tier, or null for the tier's default. */
+  kinds: string[] | null;
+  /** The declared agent session it writes as, or null for the orchestrator's choice. */
+  session: string | null;
+}
+
 /** Where a finished build goes (#3146): its branch is pushed and a pull request opened against `repo`'s `base`. */
 export interface FactoryPublish {
   forge: "github";
@@ -403,6 +473,8 @@ export interface Member {
   generated: GeneratedFile[];
   /** Outputs the entry lists as link targets, or null when it lists none (#2539). */
   outputs: string[] | null;
+  /** The values the entry sets for its kind's fields (#3151), as written, or null when it sets none. Checked against the kind by `resolveMemberFields`. */
+  fields: Record<string, unknown> | null;
   /** The links this member states as a consumer, in file order (#2539). */
   links: LinkDeclaration[];
   /** The record kinds this member declares, in file order (#2680). */
@@ -690,6 +762,7 @@ export function parseDeclaration(text: string, file: string, reader: string = re
       roles,
       generated,
       outputs: e.outputs === undefined ? null : [...(e.outputs as string[])],
+      fields: e.fields === undefined ? null : structuredClone(e.fields as Record<string, unknown>),
       links,
       records,
       diagrams,
@@ -794,6 +867,15 @@ export function parseDeclaration(text: string, file: string, reader: string = re
   // One factory, building and naming declared members (#3146).
   const factory = factoryProblem(members);
   if (factory) throw new WorkspaceReadError("declaration-invalid", factory.message, at(factory.pointer));
+  // One replicate policy (#3172): the checkout is the whole repository's, so one remote takes its work in progress.
+  const replicating = members.filter((m) => m.box?.replicate);
+  if (replicating.length > 1) {
+    throw new WorkspaceReadError(
+      "declaration-invalid",
+      `members ${replicating[0].name} and ${replicating[1].name} both declare replicate in their box block; a checkout's work in progress goes to one remote, so a workspace has one replicate policy`,
+      at(replicating[1].box!.replicate!.pointer),
+    );
+  }
 
   // A diagram name is given once across the declaration (#2764): a reader keys diagrams by name.
   const ownDiagrams = diagramsOf(obj.diagrams, null, "/diagrams");
@@ -809,6 +891,8 @@ export function parseDeclaration(text: string, file: string, reader: string = re
   const hosts = hostsOf(obj, members, at);
   const writeScope = writeScopeOf(obj.writeScope, members, at);
   const agents = agentsOf(obj.agents, members, at);
+  const tierSession = factoryTierSessionProblem(members, agents);
+  if (tierSession) throw new WorkspaceReadError("declaration-invalid", tierSession.message, at(tierSession.pointer));
 
   const pins = ((obj.pins as Record<string, string>[] | undefined) ?? []).map((p) => ({
     package: p.package ?? null,
@@ -968,12 +1052,17 @@ function boxOf(raw: unknown, pointer: string): BoxDeclaration | null {
       check?: string | { run: string; kind?: FactoryCheckKind };
       checks?: string;
       builders?: string;
+      tiers?: { tier: string; agent: string; kinds?: string[]; session?: string }[];
       publish?: { forge?: "github"; repo: string; base?: string; branchPrefix?: string; head?: string };
     };
     listing?: { published?: boolean; title?: string; line?: string; cover?: string };
+    publisher?: string;
+    replicate?: { remote?: string; refs?: ReplicateRefClass[]; on?: ReplicateTrigger[]; every?: string };
+    ship?: { op: string; gate?: string; env?: string; bookkeeping?: string[] };
   };
   const f = b.factory;
   const l = b.listing;
+  const r = b.replicate;
   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.
@@ -1000,6 +1089,7 @@ function boxOf(raw: unknown, pointer: string): BoxDeclaration | null {
             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,
+            tiers: (f.tiers ?? []).map((t) => ({ tier: t.tier, agent: t.agent, kinds: t.kinds === undefined ? null : [...t.kinds], session: t.session ?? null })),
             publish:
               f.publish === undefined
                 ? null
@@ -1013,6 +1103,28 @@ function boxOf(raw: unknown, pointer: string): BoxDeclaration | null {
             pointer: `${pointer}/factory`,
           },
     listing: l === undefined ? null : { published: l.published ?? true, title: l.title ?? "", line: l.line ?? "", cover: l.cover ?? null },
+    publisher: b.publisher ?? null,
+    ship:
+      b.ship === undefined
+        ? null
+        : {
+            op: b.ship.op,
+            gate: b.ship.gate ?? DEFAULT_SHIP_GATE,
+            env: b.ship.env ?? DEFAULT_SHIP_ENV,
+            bookkeeping: (b.ship.bookkeeping ?? []).map((p) => p.replace(/^\.\//, "").replace(/\/+$/, "")),
+            pointer: `${pointer}/ship`,
+          },
+    replicate:
+      r === undefined
+        ? null
+        : {
+            remote: r.remote ?? DEFAULT_REPLICATE_REMOTE,
+            // In the order the closed lists give, so a reader compares them without sorting.
+            refs: REPLICATE_REF_CLASSES.filter((c) => (r.refs ?? REPLICATE_REF_CLASSES).includes(c)),
+            on: REPLICATE_TRIGGERS.filter((t) => (r.on ?? REPLICATE_TRIGGERS).includes(t)),
+            every: r.every ?? null,
+            pointer: `${pointer}/replicate`,
+          },
     pointer,
   };
 }
@@ -1040,6 +1152,35 @@ function factoryProblem(members: readonly Member[]): { message: string; pointer:
   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` };
   }
+  // Builder tiers (#3152): their agents are the builders member's, and one entry answers each tier and kind.
+  if (factory.tiers.length > 0 && factory.builders === null) {
+    return { message: "the factory declares tiers and no builders; tiers name agents the builders member declares, so name it", pointer: `${factory.pointer}/tiers` };
+  }
+  const answered = new Map<string, number>();
+  for (const [i, t] of factory.tiers.entries()) {
+    for (const kind of t.kinds ?? [null]) {
+      const key = `${t.tier}\0${kind ?? ""}`;
+      const first = answered.get(key);
+      if (first !== undefined) {
+        const which = kind === null ? "with no kinds" : `for kind ${kind}`;
+        return { message: `tiers/${first} and tiers/${i} both name a builder at tier ${t.tier} ${which}; a tier has one builder per kind, so one entry answers it`, pointer: `${factory.pointer}/tiers/${i}` };
+      }
+      answered.set(key, i);
+    }
+  }
+  return null;
+}
+
+/** The rule the schema can't say about the factory's tiers once the sessions are read (#3152): a session is a declared agent session. */
+function factoryTierSessionProblem(members: readonly Member[], agents: readonly AgentDeclaration[]): { message: string; pointer: string } | null {
+  const factory = members.find((m) => m.box?.factory)?.box?.factory;
+  if (!factory) return null;
+  for (const [i, t] of factory.tiers.entries()) {
+    if (t.session !== null && !agents.some((a) => a.name === t.session)) {
+      const known = agents.map((a) => a.name).join(", ") || "none";
+      return { message: `tiers/${i} names the session ${JSON.stringify(t.session)}, which is not a declared agent session; declared sessions: ${known}`, pointer: `${factory.pointer}/tiers/${i}/session` };
+    }
+  }
   return null;
 }
 

package/src/workspace/environments.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
@@ -31,7 +36,8 @@
  */
 
 import { execFileSync } from "node:child_process";
-import { environmentName, isEnvironmentPattern, matchesDeclaredEnvironment } from "../config";
+import { environmentName, isEnvironmentPattern, matchesDeclaredEnvironment, type EnvironmentDeclaration } from "../config";
+import type { ComponentEnvironmentDeclaration } from "../components/component";
 import type { ReasonCode } from "./reason-codes";
 import { LOCAL_RUNTIME, type MemberRuntimes } from "./runtimes";
 import { ENV_PATTERN, LIFECYCLE_REF, MEMBERS_DIR } from "./status";
@@ -49,6 +55,8 @@ export const ENVIRONMENT_REASON_CODES = [
   "environments-ledger-undeclared",
   /** The chant/lifecycle branch exists and the member's ledger directories could not be listed. */
   "environments-ledger-unreadable",
+  /** A component declares an environment the config's environments don't cover, so chant run --env would refuse it (#3153). */
+  "environments-component-undeclared",
 ] as const satisfies readonly ReasonCode[];
 export type EnvironmentReasonCode = (typeof ENVIRONMENT_REASON_CODES)[number];
 
@@ -63,12 +71,22 @@ 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[];
@@ -80,9 +98,11 @@ export type LedgerEnvironmentReader = (member: { name: string; dir: string }, cw
 
 /** 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;
 }
 
 function git(cwd: string, args: string[], input?: string): string {
@@ -154,12 +174,44 @@ export function memberEnvironments(runtimes: MemberRuntimes | undefined, ledger:
   add(LOCAL_ENVIRONMENT, literals.includes(LOCAL_ENVIRONMENT) ? "config" : ledgerEnvs.includes(LOCAL_ENVIRONMENT) ? "ledger" : "builtin");
   for (const name of literals) add(name, "config");
   for (const name of ledgerEnvs) if (covered(name)) add(name, "ledger");
-  return { environments: out, reasons };
+  return { environments: out, reasons, declared };
 }
 
-/** The environments one component may deploy to, each with its command line on the member's default runtime. */
-export function componentEnvironments(component: string, member: MemberEnvironments | undefined, runtime = LOCAL_RUNTIME): ComponentEnvironment[] {
-  const list = member?.environments ?? [{ name: LOCAL_ENVIRONMENT, default: true, source: "builtin" as const }];
-  const on = runtime === LOCAL_RUNTIME ? "" : ` --on ${runtime}`;
-  return list.map((e) => ({ ...e, command: `chant run --components ${component}${on}${e.default ? "" : ` --env ${e.name}`}` }));
+/**
+ * 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 function componentEnvironments(
+  component: string,
+  member: MemberEnvironments | undefined,
+  runtime = LOCAL_RUNTIME,
+  declared: readonly ComponentEnvironmentDeclaration[] = [],
+  hosts: readonly string[] = [],
+  reasons: EnvironmentReason[] = [],
+): ComponentEnvironment[] {
+  const list: Omit<ComponentEnvironment, "command" | "site">[] = [...(member?.environments ?? [{ name: LOCAL_ENVIRONMENT, default: true, source: "builtin" as const }])];
+  const config = member?.declared;
+  const takes = (env: string): boolean => !config || config.length === 0 || matchesDeclaredEnvironment(config, env);
+  const sites = new Map<string, ComponentSite>();
+  for (const d of declared) {
+    sites.set(d.name, { runtime: d.runtime ?? null, url: d.url ?? null, domain: d.domain ?? null, lifecycle: d.lifecycle ?? null });
+    if (list.some((e) => e.name === d.name)) continue;
+    if (takes(d.name)) list.push({ name: d.name, default: false, source: "component" });
+    else {
+      reasons.push({
+        code: "environments-component-undeclared",
+        message: `component ${component} declares environment ${d.name}, which chant.config.ts's environments don't cover, so chant run --env refuses it`,
+      });
+    }
+  }
+  return list.map((e) => {
+    const site = sites.get(e.name) ?? null;
+    const on = site?.runtime && (site.runtime === LOCAL_RUNTIME || hosts.includes(site.runtime)) ? site.runtime : runtime;
+    return { ...e, site, command: `chant run --components ${component}${on === LOCAL_RUNTIME ? "" : ` --on ${on}`}${e.default ? "" : ` --env ${e.name}`}` };
+  });
 }