@intentius/chant 0.124.46 → 0.124.49

package/src/workspace/declaration.schema.json

@@ -30,6 +30,13 @@
       "$ref": "#/$defs/version",
       "description": "The oldest chant that may read this declaration. An older chant refuses it with reader-too-old."
     },
+    "scope": {
+      "enum": [
+        "repo",
+        "org"
+      ],
+      "description": "What the workspace spans (#3168). repo, the default, is one repository's workspace. org is an org-level workspace: it holds only members of kind repo, each a reference to another repository's workspace, and chant workspace check fails any other member (WSP013). A warden generates an org workspace from its policy, or checks one against the forge's repository list with chant workspace check --forge-repos. Added in schema 1 by chant 0.124.47, so a declaration that uses it sets minReader to 0.124.47 or newer."
+    },
     "members": {
       "type": "array",
       "description": "Members and example groups, in the order readers list them.",
@@ -161,6 +168,33 @@
               "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."
+              },
+              "quorum": {
+                "description": "The approval rules an Op gate of this name takes (#4324), in place of the Op's own approval.quorum: one rule or a list, each with count, and optionally targets globs over the run's environment and roles from .chant/trust.json at base. Read at base, so a change can't lower the quorum its own run needs. notAuthor is refused: an Op gate has no pull request to read the author from. Added in schema 1 by chant 0.124.47, so a declaration that uses it sets minReader to 0.124.47 or newer.",
+                "oneOf": [
+                  { "$ref": "#/$defs/gateQuorumRule" },
+                  { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/gateQuorumRule" } }
+                ]
+              },
+              "policy": {
+                "$ref": "#/$defs/gatePolicyRef",
+                "description": "The policy set an Op gate of this name takes (#4404), in place of the Op's own approval.policy. Read at base, so a change can't swap in a permissive policy for its own run. Build the object with the owning lexicon's helper (the cedar lexicon's gatePolicy()) and paste it here. Added in schema 1 by chant 0.124.49, so a declaration that uses it sets minReader to 0.124.49 or newer."
+              },
+              "mode": {
+                "enum": ["log-only", "enforce"],
+                "description": "Whether the policy's decision binds the gate (#4404), in place of the Op's own approval.mode: log-only records it next to the approval, enforce passes the gate only on a permit. Read at base, so a change can't switch its own gate to a mode that passes it. Added in schema 1 by chant 0.124.49, so a declaration that uses it sets minReader to 0.124.49 or newer."
+              },
+              "context": {
+                "type": "object",
+                "description": "Plan attributes handed to the policy (#4404), over the Op's own approval.context, key by key: a change can't edit a key declared here, and a key only the Op declares still reaches the policy. A value is a plain one, since a step output reference is resolved at run time and a declaration can't hold one. plan is reserved. Added in schema 1 by chant 0.124.49, so a declaration that uses it sets minReader to 0.124.49 or newer.",
+                "additionalProperties": {
+                  "oneOf": [
+                    { "type": "string" },
+                    { "type": "number" },
+                    { "type": "boolean" },
+                    { "type": "array", "items": { "type": "string" } }
+                  ]
+                }
               }
             }
           }
@@ -446,6 +480,31 @@
       "type": "string",
       "pattern": "^[a-z][a-z0-9-]{0,39}$"
     },
+    "gatePolicyRef": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "lexicon", "name", "version", "text"],
+      "description": "A gate policy set a lexicon rendered (#2508), as plain data.",
+      "properties": {
+        "kind": { "const": "gate-policy" },
+        "lexicon": { "type": "string", "minLength": 1, "description": "The lexicon whose gate-policy module evaluates text." },
+        "name": { "type": "string", "minLength": 1, "description": "A name for the policy set, carried into every recorded decision." },
+        "version": { "type": "string", "minLength": 1, "description": "sha256: and the hex digest of text. A recorded permit counts only under the version it was evaluated against." },
+        "text": { "type": "string", "minLength": 1, "description": "The policy set, in the lexicon's own language." }
+      }
+    },
+    "gateQuorumRule": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["count"],
+      "description": "One approval rule (#4290): count distinct human approvers, from roles when it names them.",
+      "properties": {
+        "targets": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 }, "description": "Globs over the run's environment: * within one / segment, ** across segments, ? one character. Absent: every run. A rule with targets never covers a run with no environment." },
+        "count": { "type": "integer", "minimum": 1, "description": "Distinct human approvers the rule needs." },
+        "roles": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 }, "description": "Only an approver .chant/trust.json at base gives one of these roles counts, and only with an approval sealed by a signer listed at base." },
+        "notAuthor": { "type": "boolean", "description": "Refused on an Op gate, which has no author to judge by." }
+      }
+    },
     "className": {
       "type": "string",
       "pattern": "^(?!x-)[a-z][a-z0-9-]{0,39}$",
@@ -573,7 +632,6 @@
       "description": "A member (#2524 D2). Its directory leaves the root project, and it gets its own build, lint and ledger.",
       "required": [
         "name",
-        "dir",
         "kind"
       ],
       "properties": {
@@ -586,7 +644,10 @@
         },
         "kind": {
           "$ref": "#/$defs/kindName",
-          "description": "How to read the member: chant, workspace, other, or a kind a pinned plugin supplies (#2535)."
+          "description": "How to read the member: chant, workspace, repo, other, or a kind a pinned plugin supplies (#2535). Every kind but repo needs dir; a repo member has repo instead (#3168)."
+        },
+        "repo": {
+          "$ref": "#/$defs/repoRef"
         },
         "roles": {
           "type": "array",
@@ -685,6 +746,10 @@
           "type": "boolean",
           "description": "Whether the member goes with an export (#2524 D10, #2552). chant workspace export writes only members that set travel to true into the export member, and refuses to name one that does not. Added in schema 1 by chant 0.101.0, so a declaration that uses it sets minReader to 0.101.0 or newer."
         },
+        "acceptWorkspaceGates": {
+          "type": "boolean",
+          "description": "Whether an approval of a workspace gate may stand in for this member's own gates (#2554, ws-039). It does only when the approval's digest covers the plan the member's run reached its gate with, and only when the declaration at base sets this to true; a working-tree change never opts a member in. Absent or false, a workspace gate never satisfies this member's gates. Added in schema 1 by chant 0.124.47, so a declaration that uses it sets minReader to 0.124.47 or newer."
+        },
         "security": {
           "type": "array",
           "uniqueItems": true,
@@ -706,28 +771,91 @@
         "^x-": true
       },
       "additionalProperties": false,
-      "if": {
-        "type": "object",
-        "properties": {
-          "kind": {
-            "const": "other"
+      "allOf": [
+        {
+          "if": {
+            "type": "object",
+            "properties": {
+              "kind": {
+                "const": "other"
+              }
+            },
+            "required": [
+              "kind"
+            ]
+          },
+          "then": {
+            "type": "object",
+            "properties": {
+              "because": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "because"
+            ]
           }
         },
-        "required": [
-          "kind"
-        ]
-      },
-      "then": {
-        "type": "object",
-        "properties": {
-          "because": {
-            "type": "string"
+        {
+          "if": {
+            "type": "object",
+            "properties": {
+              "kind": {
+                "const": "repo"
+              }
+            },
+            "required": [
+              "kind"
+            ]
+          },
+          "then": {
+            "required": [
+              "repo"
+            ],
+            "properties": {
+              "repo": true,
+              "dir": false
+            }
+          },
+          "else": {
+            "required": [
+              "dir"
+            ],
+            "properties": {
+              "dir": true,
+              "repo": false
+            }
           }
+        }
+      ]
+    },
+    "repoRef": {
+      "type": "object",
+      "description": "Another repository's workspace, named by URL and pinned revision (#3168). A member of kind repo carries it and has no dir. chant reads that workspace read-only through the other repository's own read contract, its chant workspace graph at the revision, the way it reads a nested workspace member, and never writes there. Added in schema 1 by chant 0.124.47, so a declaration that uses it sets minReader to 0.124.47 or newer.",
+      "required": [
+        "url",
+        "rev"
+      ],
+      "properties": {
+        "url": {
+          "type": "string",
+          "pattern": "^[^\\s]+$",
+          "description": "Where git fetches the repository from: an https, ssh or file URL, a local path, or an scp-style git@host:org/repo. A URL that carries a password or token is refused when it is read."
         },
-        "required": [
-          "because"
-        ]
-      }
+        "rev": {
+          "type": "string",
+          "pattern": "^([0-9a-f]{40}|[0-9a-f]{64})$",
+          "description": "The pinned revision, a full commit id. A branch or tag is not a pin."
+        },
+        "workspace": {
+          "$ref": "#/$defs/dir",
+          "description": "The workspace root inside that repository, relative to its git root. Defaults to \".\"."
+        }
+      },
+      "patternProperties": {
+        "^x-": true
+      },
+      "additionalProperties": false
     },
     "memberFields": {
       "type": "object",
@@ -1696,10 +1824,24 @@
       ],
       "properties": {
         "branch": {
-          "type": "string",
-          "minLength": 1,
-          "pattern": "^[^\\s~^:?*\\[\\\\]+$",
-          "description": "The branch whose commits are tagged, such as main. Only its first-parent commits count."
+          "oneOf": [
+            {
+              "type": "string",
+              "minLength": 1,
+              "pattern": "^[^\\s~^:?*\\[\\\\]+$"
+            },
+            {
+              "type": "array",
+              "minItems": 1,
+              "uniqueItems": true,
+              "items": {
+                "type": "string",
+                "minLength": 1,
+                "pattern": "^[^\\s~^:?*\\[\\\\]+$"
+              }
+            }
+          ],
+          "description": "The branch whose commits are tagged, such as main. Only its first-parent commits count. A list judges each branch, so a branch ci.branches routes members to gets a green verdict and can release (#4325); the first is the trunk that readers use when they are not told a branch. A string reads as it always did."
         },
         "window": {
           "type": "string",

package/src/workspace/declaration.ts

@@ -22,7 +22,7 @@ import schema from "./declaration.schema.json" with { type: "json" };
 import { routeConflicts } from "./ci-branches";
 import { cloudIdentityProblems, CLOUDS, type CloudIdentityDeclaration } from "../ci-identity";
 import { expandGlob } from "./glob";
-import { EXAMPLES_KIND, holdsChantProject } from "./kinds";
+import { EXAMPLES_KIND, holdsChantProject, REPO_KIND } from "./kinds";
 import { parseJsonText, pointerToken, type TextLocation } from "./jsonc";
 import type { ReasonCode } from "./reason-codes";
 import type { SecurityGroup } from "./security";
@@ -30,6 +30,8 @@ import { joinPath, type WorkspaceTree } from "./tree";
 import { loadAjv2020 } from "./ajv2020";
 import { readChantPackageVersion } from "../package-version";
 import { assertPrLoopHooks, type OpWaveHooks } from "../op/op-waves";
+import { quorumProblems, type GateQuorumSpec } from "../op/gate-quorum";
+import { gateBaseApprovalProblems, type GateApprovalMode, type GatePolicyRef } from "../op/gate-approval";
 import { assertGatePolicySettings, type GatePolicySettings } from "../gate-policy";
 
 export const DECLARATION_SCHEMA_ID = schema.$id;
@@ -159,6 +161,19 @@ 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;
+  /**
+   * The approval rules an Op gate of this name takes (#4324): one rule or a
+   * list, as an Op's `approval.quorum`. Read here, at base, a change can't
+   * lower the quorum its own run needs. Null when the entry sets none, and
+   * the Op's own `approval.quorum` then applies.
+   */
+  quorum: GateQuorumSpec | null;
+  /** The policy an Op gate of this name takes in place of its own `approval.policy` (#4404). Null when the entry sets none. */
+  policy: GatePolicyRef | null;
+  /** The mode an Op gate of this name runs its policy in, in place of its own `approval.mode` (#4404). Null when the entry sets none. */
+  mode: GateApprovalMode | null;
+  /** The context an Op gate of this name hands its policy, in place of its own `approval.context` (#4404). Null when the entry sets none. */
+  context: Record<string, string | number | boolean | string[]> | null;
   pointer: string;
 }
 
@@ -212,13 +227,24 @@ export interface CiPhase {
   pointer: string;
 }
 
+/** Every branch `ci.green` judges (#4325): `branches` when the declaration names several, else `branch`. */
+export function greenBranches(green: Pick<CiGreen, "branch" | "branches">): string[] {
+  return green.branches ?? [green.branch];
+}
+
 /** The default `ci.green.window`. */
 export const DEFAULT_CI_WINDOW = "24h";
 
 /** The declaration's `ci.green` block (#3573, ws-103), with its defaults. */
 export interface CiGreen {
-  /** The branch whose first-parent commits are tagged. */
+  /** The branch whose first-parent commits are tagged. With several (#4325), the first one declared. */
   branch: string;
+  /**
+   * Every branch whose first-parent commits are tagged (#4325), in declaration
+   * order, the first being `branch`. Present only when the declaration names
+   * more than one, so a one-branch declaration reads as it always did.
+   */
+  branches?: string[];
   /** How far back a tick looks, such as `24h`. */
   window: string;
   /** The phases, in file order. */
@@ -638,9 +664,16 @@ export const DEFAULT_STATE_ROOT = "${XDG_STATE_HOME}/chant/boxes";
 export interface Member {
   type: "member";
   name: string;
-  /** Relative to the workspace root; `"."` is the root member. */
+  /**
+   * Relative to the workspace root; `"."` is the root member. A member of kind
+   * `repo` has no directory here: its `dir` is {@link repoMemberDir}, which
+   * names no directory of this repository, and every reader that looks at
+   * member directories leaves it out by its kind (#3168).
+   */
   dir: string;
   kind: string;
+  /** For a member of kind `repo`, the other repository's workspace it names (#3168); null for every other kind. */
+  repo: RepoRef | null;
   roles: MemberRole[];
   /** Declared generated files, in file order. The implicit ones are not listed here (see `generated-files.ts`). */
   generated: GeneratedFile[];
@@ -660,6 +693,12 @@ export interface Member {
   because: string | null;
   /** Whether `chant workspace export` takes the member (#2552, D10). False when the entry does not say. */
   travel: boolean;
+  /**
+   * Whether a workspace gate's approval may stand in for this member's own
+   * gates (#2554, ws-039), when its digest covers the member's plan. Read
+   * from the declaration at base. Set only when the entry says true.
+   */
+  acceptWorkspaceGates?: true;
   /** The security groups this member adds to the declaration's top-level `security` (#4168 step 7), in file order; empty when it names none. */
   security: SecurityGroup[];
   /** The member's own `ci.workflow` (#4168 step 6), which wins over the top level's; null when it names none. */
@@ -691,10 +730,26 @@ export interface Pin {
   integrity: string | null;
 }
 
+/** Another repository's workspace, by URL and pinned revision (#3168). */
+export interface RepoRef {
+  url: string;
+  /** A full commit id. */
+  rev: string;
+  /** The workspace root inside that repository, relative to its git root; `"."` when the entry doesn't say. */
+  workspace: string;
+}
+
+/** The `dir` a `repo` member reads as (#3168): a marker, never a directory of this repository. */
+export function repoMemberDir(name: string): string {
+  return `@repo/${name}`;
+}
+
 export interface Declaration {
   name: string;
   schema: number;
   minReader: string | null;
+  /** `org` for an org-level workspace, which holds only `repo` members; `repo` otherwise, the default (#3168). */
+  scope: "repo" | "org";
   /** Members and groups, in file order. */
   entries: Entry[];
   members: Member[];
@@ -817,9 +872,13 @@ function explain(e: AjvError, value: unknown): string {
     const missing = String(e.params.missingProperty);
     if (missing === "because" && e.instancePath.endsWith("/handWritten")) return `a hand-written generated file needs "because", saying why it is kept by hand`;
     if (missing === "because") return `a member of kind other needs "because", saying why it is there`;
+    if (missing === "repo") return `a member of kind repo needs "repo", the other repository's url and pinned rev`;
     return `missing required field ${JSON.stringify(missing)}`;
   }
   if (e.keyword === "const" && e.instancePath === "/schema") return `schema must be 1, the only declaration format this chant reads`;
+  // A repo member has repo and no dir; every other member has dir and no repo (#3168).
+  if (e.keyword === "false schema" && e.instancePath.endsWith("/dir")) return `a member of kind repo has no dir: it names another repository's workspace with repo`;
+  if (e.keyword === "false schema" && e.instancePath.endsWith("/repo")) return `only a member of kind repo has repo`;
   return e.message ?? "is invalid";
 }
 
@@ -942,14 +1001,17 @@ export function parseDeclaration(text: string, file: string, reader: string = re
       protocol: l.protocol ?? null,
       pointer: `${pointer}/links/${j}`,
     }));
-    const records = recordKindsOf(e.records, e.dir as string, e.name as string, `${pointer}/records`);
+    const repoRaw = e.repo as { url: string; rev: string; workspace?: string } | undefined;
+    const dir = e.kind === REPO_KIND ? repoMemberDir(e.name as string) : (e.dir as string);
+    const records = recordKindsOf(e.records, dir, e.name as string, `${pointer}/records`);
     const diagrams = diagramsOf(e.diagrams, e.name as string, `${pointer}/diagrams`);
     const box = boxOf(e.box, `${pointer}/box`);
     return {
       type: "member",
       name: e.name as string,
-      dir: e.dir as string,
+      dir,
       kind: e.kind as string,
+      repo: repoRaw ? { url: repoRaw.url, rev: repoRaw.rev, workspace: repoRaw.workspace ?? "." } : null,
       roles,
       generated,
       outputs: e.outputs === undefined ? null : [...(e.outputs as string[])],
@@ -961,6 +1023,7 @@ export function parseDeclaration(text: string, file: string, reader: string = re
       upstream: (e.upstream as string | undefined) ?? null,
       because: (e.because as string | undefined) ?? null,
       travel: e.travel === true,
+      ...(e.acceptWorkspaceGates === true ? { acceptWorkspaceGates: true as const } : {}),
       security: [...((e.security as SecurityGroup[] | undefined) ?? [])],
       ciWorkflow: ((e.ci as { workflow?: CiWorkflow } | undefined)?.workflow) ?? null,
       ciHooks: ciHooksOf((e.ci as { hooks?: unknown } | undefined)?.hooks, `${pointer}/ci/hooks`, at),
@@ -986,8 +1049,10 @@ export function parseDeclaration(text: string, file: string, reader: string = re
   // Placement (#2524 D2): one root member at most, no two members in one
   // directory, and only the root member contains other members.
   const members = entries.filter((e): e is Member => e.type === "member");
+  // A repo member has no directory here (#3168), so it takes no part in placement.
+  const placed = members.filter((m) => m.kind !== REPO_KIND);
   const byDir = new Map<string, Member>();
-  for (const m of members) {
+  for (const m of placed) {
     const other = byDir.get(m.dir);
     if (other) {
       throw new WorkspaceReadError(
@@ -998,8 +1063,8 @@ export function parseDeclaration(text: string, file: string, reader: string = re
     }
     byDir.set(m.dir, m);
   }
-  for (const m of members) {
-    const outer = members.find((o) => o !== m && o.dir !== "." && isInside(m.dir, o.dir));
+  for (const m of placed) {
+    const outer = placed.find((o) => o !== m && o.dir !== "." && isInside(m.dir, o.dir));
     if (outer) {
       throw new WorkspaceReadError(
         "placement-invalid",
@@ -1109,6 +1174,7 @@ export function parseDeclaration(text: string, file: string, reader: string = re
     name: obj.name as string,
     schema: obj.schema as number,
     minReader: (obj.minReader as string | undefined) ?? null,
+    scope: obj.scope === "org" ? "org" : "repo",
     entries,
     members,
     groups: entries.filter((e): e is Group => e.type === "group"),
@@ -1121,7 +1187,7 @@ 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),
+    identity: identityOf(obj.identity, at),
     ci,
     retention: retentionOf(obj.retention),
     metrics: metricsOf(obj.metrics),
@@ -1181,13 +1247,32 @@ function writeScopeOf(raw: unknown, members: Member[], at: (pointer: string, key
  * (#2548, ws-101): names are unique, every member a session names is 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 {
+/**
+ * The `identity` block, already validated by the schema (#3163), with the
+ * quorum rules the schema can't say (#4324): `notAuthor` is refused, since an
+ * Op gate has no pull request to read the author from.
+ */
+function identityOf(raw: unknown, at: (pointer: string, key?: boolean) => ErrorLocation): IdentityPolicy | null {
   if (raw === undefined) return null;
-  const block = raw as { attribution?: "any" | "identified"; gates?: Record<string, { class?: string }> };
+  const block = raw as { attribution?: "any" | "identified"; gates?: Record<string, { class?: string; quorum?: GateQuorumSpec; policy?: GatePolicyRef; mode?: GateApprovalMode; context?: Record<string, string | number | boolean | 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")}` };
+    const pointer = `/identity/gates/${gate.replace(/~/g, "~0").replace(/\//g, "~1")}`;
+    if (entry.quorum !== undefined) {
+      const [problem] = quorumProblems(entry.quorum, `identity.gates.${gate}.quorum`, { notAuthor: false });
+      if (problem) throw new WorkspaceReadError("declaration-invalid", problem.replace(/`/g, ""), at(`${pointer}/quorum`));
+    }
+    const [rest] = gateBaseApprovalProblems(entry, `identity.gates.${gate}`);
+    if (rest) throw new WorkspaceReadError("declaration-invalid", rest.replace(/`/g, ""), at(pointer));
+    gates[gate] = {
+      gate,
+      class: entry.class ?? null,
+      quorum: entry.quorum !== undefined ? structuredClone(entry.quorum) : null,
+      policy: entry.policy !== undefined ? structuredClone(entry.policy) : null,
+      mode: entry.mode ?? null,
+      context: entry.context !== undefined ? structuredClone(entry.context) : null,
+      pointer,
+    };
   }
   return { attribution: block.attribution ?? "any", gates };
 }
@@ -1266,7 +1351,7 @@ function cloudIdentityOf(raw: CloudIdentityDeclaration, at: (pointer: string, ke
 
 function ciOf(raw: unknown, at: (pointer: string, key?: boolean) => ErrorLocation): CiDeclaration | null {
   if (raw === undefined) return null;
-  const block = raw as { reportUrl?: string; workflow?: CiWorkflow; hooks?: unknown; identity?: { cloud?: CloudIdentityDeclaration }; branches?: Record<string, string[]>; labels?: Record<string, string[]>; locks?: CiLocks; policy?: unknown; prEnvironment?: { template: string; ttl?: string; teardown?: { name?: string; command: string[]; lexicons?: string[] } }; green?: { branch: string; window?: string; phases: Record<string, string[] | { runs: string[]; skipped?: CiSkipped; build?: CiBuild }>; require: string[]; preMerge?: string[]; signedSince?: string; source?: CiSource } };
+  const block = raw as { reportUrl?: string; workflow?: CiWorkflow; hooks?: unknown; identity?: { cloud?: CloudIdentityDeclaration }; branches?: Record<string, string[]>; labels?: Record<string, string[]>; locks?: CiLocks; policy?: unknown; prEnvironment?: { template: string; ttl?: string; teardown?: { name?: string; command: string[]; lexicons?: string[] } }; green?: { branch: string | string[]; window?: string; phases: Record<string, string[] | { runs: string[]; skipped?: CiSkipped; build?: CiBuild }>; require: string[]; preMerge?: string[]; signedSince?: string; source?: CiSource } };
   const hooks = ciHooksOf(block.hooks, "/ci/hooks", at);
   const policy = ciPolicyOf(block.policy, at);
   const workflow = {
@@ -1327,7 +1412,8 @@ function ciOf(raw: unknown, at: (pointer: string, key?: boolean) => ErrorLocatio
       at(`/ci/green/preMerge/${i}`),
     );
   }
-  return { green: { branch: g.branch, window: g.window ?? DEFAULT_CI_WINDOW, phases, require: [...g.require], ...(g.preMerge !== undefined ? { preMerge: [...g.preMerge] } : {}), signedSince: g.signedSince ?? null, source: g.source ?? "checks", pointer: "/ci/green" }, ...workflow, reportUrl };
+  const judged = Array.isArray(g.branch) ? g.branch : [g.branch];
+  return { green: { branch: judged[0]!, ...(judged.length > 1 ? { branches: [...judged] } : {}), window: g.window ?? DEFAULT_CI_WINDOW, phases, require: [...g.require], ...(g.preMerge !== undefined ? { preMerge: [...g.preMerge] } : {}), signedSince: g.signedSince ?? null, source: g.source ?? "checks", pointer: "/ci/green" }, ...workflow, reportUrl };
 }
 
 function agentsOf(raw: unknown, members: Member[], at: (pointer: string, key?: boolean) => ErrorLocation): AgentDeclaration[] {

package/src/workspace/environments.ts

@@ -23,6 +23,13 @@
  * would take it, or left out with `environments-component-undeclared` when
  * the config's environments don't cover it.
  *
+ * Each environment also names its `executor` (#4402): the forge and committed
+ * workflow that deploys it, as the member's config declares on the
+ * environment's entry (`{ name: "prod", executor: { forge: "github",
+ * workflow: "deploy-prod.yml" } }`), a literal entry before a pattern. When
+ * none is declared, `forge` and `workflow` are null and `reason` says why.
+ * chant never derives it from a generated workflow's name.
+ *
  * `chant run --env` refuses a name the config's `environments` doesn't cover
  * whenever it declares any (`unknownEnvError` in `../env.ts`), so a ledger
  * environment the config no longer covers is left out, with a reason. The
@@ -36,7 +43,7 @@
  */
 
 import { execFileSync } from "node:child_process";
-import { environmentName, isEnvironmentPattern, matchesDeclaredEnvironment, type EnvironmentDeclaration } from "../config";
+import { environmentExecutor, environmentName, isEnvironmentPattern, matchesDeclaredEnvironment, type EnvironmentDeclaration, type EnvironmentExecutor } from "../config";
 import type { ComponentEnvironmentDeclaration } from "../components/component";
 import type { ReasonCode } from "./reason-codes";
 import { LOCAL_RUNTIME, type MemberRuntimes } from "./runtimes";
@@ -60,6 +67,23 @@ export const ENVIRONMENT_REASON_CODES = [
 ] as const satisfies readonly ReasonCode[];
 export type EnvironmentReasonCode = (typeof ENVIRONMENT_REASON_CODES)[number];
 
+/** Why an environment names no executor (#4402). Closed: part of the read contract. */
+export const EXECUTOR_REASON_CODES = [
+  /** The member's chant.config.ts declares no executor for the environment, so nothing says which forge workflow deploys it. */
+  "executor-none-declared",
+  /** The member's chant.config.ts could not be read, so whether a forge workflow deploys the environment is unknown. */
+  "executor-config-unreadable",
+] as const satisfies readonly ReasonCode[];
+export type ExecutorReasonCode = (typeof EXECUTOR_REASON_CODES)[number];
+
+/** The forge workflow that deploys an environment (#4402), or why none is named. */
+export interface ComponentExecutor {
+  forge: EnvironmentExecutor["forge"] | null;
+  workflow: string | null;
+  /** Null when `forge` and `workflow` are set. */
+  reason: { code: ExecutorReasonCode; message: string } | null;
+}
+
 export interface EnvironmentReason {
   code: EnvironmentReasonCode;
   message: string;
@@ -75,6 +99,8 @@ export interface ComponentEnvironment {
   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 forge and committed workflow that deploys this environment, from the member's config (#4402). */
+  executor: ComponentExecutor;
   /** 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;
 }
@@ -99,7 +125,7 @@ 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 site and command. */
-  environments: Omit<ComponentEnvironment, "command" | "site">[];
+  environments: Omit<ComponentEnvironment, "command" | "site" | "executor">[];
   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;
@@ -177,6 +203,16 @@ export function memberEnvironments(runtimes: MemberRuntimes | undefined, ledger:
   return { environments: out, reasons, declared };
 }
 
+/** The executor the member's config declares for `env`, or why there is none. */
+export function executorFor(env: string, member: MemberEnvironments | undefined): ComponentExecutor {
+  if (member && member.declared === null) {
+    return { forge: null, workflow: null, reason: { code: "executor-config-unreadable", message: `chant.config.ts could not be read, so no executor is known for ${env}` } };
+  }
+  const found = environmentExecutor(member?.declared ?? undefined, env);
+  if (found) return { forge: found.forge, workflow: found.workflow, reason: null };
+  return { forge: null, workflow: null, reason: { code: "executor-none-declared", message: `chant.config.ts declares no executor for ${env}` } };
+}
+
 /**
  * The environments one component may deploy to, each with its command line.
  * `declared` is what the component's contract says (#3153): an environment
@@ -194,7 +230,7 @@ export function componentEnvironments(
   hosts: readonly string[] = [],
   reasons: EnvironmentReason[] = [],
 ): ComponentEnvironment[] {
-  const list: Omit<ComponentEnvironment, "command" | "site">[] = [...(member?.environments ?? [{ name: LOCAL_ENVIRONMENT, default: true, source: "builtin" as const }])];
+  const list: Omit<ComponentEnvironment, "command" | "site" | "executor">[] = [...(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>();
@@ -212,6 +248,6 @@ export function componentEnvironments(
   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}`}` };
+    return { ...e, site, executor: executorFor(e.name, member), command: `chant run --components ${component}${on === LOCAL_RUNTIME ? "" : ` --on ${on}`}${e.default ? "" : ` --env ${e.name}`}` };
   });
 }