@intentius/chant 0.101.0 → 0.104.0

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,133 @@ 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 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;
+}
+
+/** 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;
+  /** 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";
+  /** 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. */
@@ -313,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). */
@@ -375,6 +537,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;
 }
@@ -598,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,
@@ -699,6 +864,18 @@ 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));
+  // 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");
@@ -714,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,
@@ -738,21 +917,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 +944,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 +955,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 +1047,22 @@ 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;
+      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.
@@ -875,10 +1081,109 @@ 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,
+            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
+                : {
+                    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 },
+    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,
   };
 }
 
+/**
+ * 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` };
+  }
+  // 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;
+}
+
 /**
  * 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/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}`}` };
+  });
 }

package/src/workspace/factory-rules.test.ts

@@ -0,0 +1,62 @@
+/**
+ * The factory's rules (#3406, ws-087): readiness, understand, retry, done
+ * and the implements proposals, as pure functions. The Op that runs them is
+ * tested in ../op/factory.e2e.test.ts.
+ */
+
+import { describe, expect, test } from "vitest";
+import { isAsk, pickable, retryState, doneVerdict, proposeImplements, understandOutcome, type FactoryContext, type FactoryItem } from "./factory-rules";
+
+describe("the factory's rules", () => {
+  const base: FactoryItem = { id: "W-1", state: "open", openState: "open", proposedState: "proposed", ready: true, data: {}, tier: null, contract: null, warnings: [], answers: [], leased: false };
+  const ctx: FactoryContext = { intentDecided: null, claims: [], attempts: { exhausted: false }, branch: null, questions: { tier: null, understand: null } };
+  const hold = (i: Partial<FactoryItem>, c: Partial<FactoryContext> = {}) => {
+    const v = pickable({ ...base, ...i }, { ...ctx, ...c });
+    return v.ok ? "ok" : v.hold;
+  };
+
+  test("readiness", () => {
+    expect(hold({})).toBe("ok");
+    expect(hold({}, { intentDecided: false })).toBe("intent-undecided");
+    expect(hold({ ready: false })).toBe("not-ready");
+    expect(hold({ ready: false, state: "proposed", data: { source: { ask: { said: "x", by: "a" } } } })).toBe("ok");
+    expect(hold({ contract: { id: "C-1", state: "draft" }, warnings: ["work-contract-undecided"] })).toBe("contract-not-approved");
+    expect(hold({}, { branch: { state: "done", applied: false } })).toBe("built-not-applied");
+    expect(hold({}, { branch: { state: "done", applied: true } })).toBe("ok");
+    expect(hold({}, { branch: { state: "dropped", applied: false } })).toBe("dropped-on-branch");
+    expect(hold({}, { attempts: { exhausted: true } })).toBe("attempts-exhausted");
+    const failed = { claims: [{ token: "t1", ended: "released", outcome: "not_done", attempt: true }] };
+    expect(hold({}, failed)).toBe("awaiting-retry");
+    expect(hold({ data: { retry: { after: "t1", by: "alice" } } }, failed)).toBe("ok");
+    expect(hold({ data: { retry: { after: "t0", by: "alice" } } }, failed)).toBe("awaiting-retry");
+    expect(hold({}, { questions: { tier: { state: "escalated", answer: null }, understand: null } })).toBe("question-open");
+    expect(hold({ tier: "large" }, { questions: { tier: { state: "escalated", answer: null }, understand: null } })).toBe("ok");
+    const ask = { data: { source: { ask: { said: "x", by: "a" } } } };
+    expect(hold(ask, { questions: { tier: null, understand: { state: "answered", answer: "redraft" } } })).toBe("redraft-or-ask");
+    expect(hold({ leased: true })).toBe("leased");
+  });
+
+  test("understand, retry, done and implements", () => {
+    expect(isAsk({ source: { intent: { answer: "x" } } })).toBe(true);
+    expect([understandOutcome("proceed"), understandOutcome("refuse"), understandOutcome("redraft"), understandOutcome("ask")]).toEqual([null, "dropped", "redraft", "ask"]);
+    const claims = [{ token: "t1", ended: "released", outcome: "not_done", attempt: true }];
+    expect(retryState({}, claims, { exhausted: false }, false)).toEqual({ possible: true, after: "t1", asked: false });
+    expect(retryState({ retry: { after: "t1", by: "a" } }, claims, { exhausted: false }, false)).toMatchObject({ asked: true });
+    expect(retryState({}, claims, { exhausted: true }, false)).toMatchObject({ possible: false, reason: "attempts-exhausted" });
+    expect(retryState({}, [], { exhausted: false }, false)).toMatchObject({ possible: false, reason: "no-failed-build" });
+    const unit = { id: "AC-1", verification: "unit", met: true };
+    expect(doneVerdict({ finished: true, reverted: [] }, { ran: true, ok: true }, [unit])).toEqual({ done: true });
+    expect(doneVerdict({ finished: true, reverted: [] }, { ran: true, ok: true }, [unit, { id: "AC-2", verification: "manual", met: false }])).toMatchObject({ done: false });
+    expect(doneVerdict({ finished: true, reverted: ["x"] }, { ran: true, ok: true }, [unit])).toMatchObject({ done: false });
+    expect(doneVerdict({ finished: true, reverted: [] }, { ran: true, ok: false }, [unit])).toMatchObject({ done: false });
+    expect(
+      proposeImplements(
+        [
+          { path: "a.ts", decisions: [{ id: "d-1", state: "decided", granularity: "path" }, { id: "d-2", state: "decided", granularity: "member" }, { id: "d-3", state: "proposed", granularity: "path" }] },
+          { path: "b.ts", decisions: [{ id: "d-1", state: "decided", granularity: "path" }, { id: "d-4", state: "ratified", granularity: "path" }] },
+        ],
+        ["d-4"],
+      ),
+    ).toEqual([{ decision: "d-1", paths: ["a.ts", "b.ts"] }]);
+  });
+});