@intentius/chant 0.87.0 → 0.89.0

package/src/workspace/composites.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://intentius.io/chant/schemas/workspace/composites/v1/composites.schema.json",
   "title": "chant workspace graph --composites output",
-  "description": "What `chant workspace graph --composites` prints: each composite instance the workspace's members declare, joined to the components whose contract can deploy it (#2662). Each member of kind chant is read through its own `chant graph --format ir` and `chant graph --components --format ir`, under its own toolchain. An instance with no component is listed with an empty `components` array. chant supplies the rows and never picks one: each match says how it was made and how it crosses members. Readers ignore fields they do not know; a field is only ever added within a version. The reason and error codes are closed lists. Contract version 1 is written by chant 0.81.0 and newer, and this document was added to it by #2662; a chant without --composites refuses the flag. Each component lists the runtimes it can deploy on, read from its member's chant.config.ts (#2674). Every code is in the one closed list of `reason-codes.ts`.",
+  "description": "What `chant workspace graph --composites` prints: each composite instance the workspace's members declare, joined to the components whose contract can deploy it (#2662). Each member of kind chant is read through its own `chant graph --format ir` and `chant graph --components --format ir`, under its own toolchain. An instance with no component is listed with an empty `components` array. chant supplies the rows and never picks one: each match says how it was made and how it crosses members. Readers ignore fields they do not know; a field is only ever added within a version. The reason and error codes are closed lists. Contract version 1 is written by chant 0.81.0 and newer, and this document was added to it by #2662; a chant without --composites refuses the flag. Each component lists the runtimes it can deploy on, read from its member's chant.config.ts (#2674), and the environments it may deploy to, from that config and the member's release ledger on chant/lifecycle (#2695). Every code is in the one closed list of `reason-codes.ts`.",
   "oneOf": [
     {
       "$ref": "#/$defs/result"
@@ -131,7 +131,8 @@
         "status",
         "reason",
         "chant",
-        "runtimeReasons"
+        "runtimeReasons",
+        "environmentReasons"
       ],
       "properties": {
         "name": {
@@ -210,6 +211,30 @@
               }
             }
           }
+        },
+        "environmentReasons": {
+          "description": "Why the environments of the member's components are only local, or leave out one its ledger has: its chant.config.ts could not be read (the same read and code as runtimeReasons), declares no environments, or doesn't cover an environment the ledger has, or the ledger couldn't be listed. Empty for a member not of kind chant, and when nothing needs saying.",
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": [
+              "code",
+              "message"
+            ],
+            "properties": {
+              "code": {
+                "enum": [
+                  "runtimes-config-unreadable",
+                  "environments-none-declared",
+                  "environments-ledger-undeclared",
+                  "environments-ledger-unreadable"
+                ]
+              },
+              "message": {
+                "type": "string"
+              }
+            }
+          }
         }
       },
       "if": {
@@ -351,7 +376,8 @@
         "archetype",
         "composites",
         "file",
-        "runtimes"
+        "runtimes",
+        "environments"
       ],
       "properties": {
         "id": {
@@ -400,6 +426,14 @@
           "items": {
             "$ref": "#/$defs/runtime"
           }
+        },
+        "environments": {
+          "description": "The environments the component may deploy to with chant run --components --env in its member: local first, the default, then each name the member's chant.config.ts declares in environments (patterns left out), in config order, then each environment with a release ledger for the member on chant/lifecycle that the config covers, sorted. The component contract declares no environments.",
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "$ref": "#/$defs/environment"
+          }
         }
       }
     },
@@ -528,6 +562,37 @@
           "description": "The command that deploys the component on this runtime, run in the member's directory: chant run --components <name>, with --on <runtime> for any runtime but local."
         }
       }
+    },
+    "environment": {
+      "type": "object",
+      "required": [
+        "name",
+        "default",
+        "source",
+        "command"
+      ],
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "What --env takes."
+        },
+        "default": {
+          "type": "boolean",
+          "description": "True for the environment chant run --components deploys to without --env. That is local, since chant.config.ts names no default environment."
+        },
+        "source": {
+          "enum": [
+            "config",
+            "ledger",
+            "builtin"
+          ],
+          "description": "Where the name came from, the first of these that names it: config for the member's chant.config.ts environments, ledger for a release ledger on chant/lifecycle, builtin for local when neither names it."
+        },
+        "command": {
+          "type": "string",
+          "description": "The command that deploys the component to this environment on its default runtime, run in the member's directory: chant run --components <name>, with --on <runtime> when the default runtime isn't local, and --env <env> for any environment but the default."
+        }
+      }
     }
   }
 }

package/src/workspace/composites.test.ts

@@ -7,7 +7,8 @@
  * (`read-contract.test.ts`).
  */
 
-import { mkdirSync, writeFileSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { afterAll, describe, expect, test } from "vitest";
 import type { GraphIR, IRNode } from "../graph-ir";
@@ -15,6 +16,7 @@ import { cleanScratch, commitAll, contract, declaration, FAKE_FILE_GRAPH_CHANT,
 import { MEMBER_RUN_REASON_CODES } from "./compose-graph";
 import {
   COMPOSITES_CONTRACT_VERSION,
+  COMPOSITES_ENVIRONMENT_REASON_CODES,
   COMPOSITES_ERROR_CODES,
   COMPOSITES_OUTPUT_SCHEMA_ID,
   COMPOSITES_REASON_CODES,
@@ -58,6 +60,9 @@ const componentIr = (components: { name: string; composites?: string[]; archetyp
 /** The built-in runtime every component has. */
 const local = (name: string) => ({ name: "local", lexicon: null, default: true, command: `chant run --components ${name}` });
 
+/** The default environment, named by nothing but chant itself. */
+const localEnv = (name: string) => ({ name: "local", default: true, source: "builtin", command: `chant run --components ${name}` });
+
 /**
  * app declares three instances and exports ImageUri; delivery links to it and
  * declares two components; jobs declares an instance and a component of its
@@ -111,6 +116,7 @@ describe("composites output schema", () => {
     expect(COMPOSITES_ERROR_CODES).toEqual(GRAPH_ERROR_CODES);
     expect(schema.$defs.member.properties.reason.oneOf[1].properties!.code.enum).toEqual([...MEMBER_RUN_REASON_CODES]);
     expect(schema.$defs.member.properties.runtimeReasons.items.properties.code.enum).toEqual([...COMPOSITES_RUNTIME_REASON_CODES]);
+    expect(schema.$defs.member.properties.environmentReasons.items.properties.code.enum).toEqual([...COMPOSITES_ENVIRONMENT_REASON_CODES]);
   });
 });
 
@@ -122,7 +128,7 @@ describe("the join", () => {
       { ...composite("a/billingTable", "Table", "a/billing"), member: "a" },
     ],
   });
-  const component = (member: string, name: string, composites: string[] | null = null): ComponentEntry => ({ id: `${member}/${name}`, name, member, archetype: null, composites, file: null, runtimes: [] });
+  const component = (member: string, name: string, composites: string[] | null = null): ComponentEntry => ({ id: `${member}/${name}`, name, member, archetype: null, composites, file: null, runtimes: [], environments: [] });
 
   test("an instance carries every kind and lexicon of its nodes", () => {
     expect(instances.map((i) => [i.id, i.instance, i.kinds, i.lexicons])).toEqual([
@@ -165,9 +171,9 @@ describe("chant workspace graph --composites on a built workspace", () => {
       ["docs", "skipped", "kind-not-run"],
     ]);
     expect(g.components).toEqual([
-      { id: "delivery/edge", name: "edge", member: "delivery", archetype: "infra", composites: ["StaticSite"], file: "delivery/src/edge.component.ts", runtimes: [local("edge")] },
-      { id: "delivery/loom-backend", name: "loom-backend", member: "delivery", archetype: "service", composites: null, file: "delivery/src/loom-backend.component.ts", runtimes: [local("loom-backend")] },
-      { id: "jobs/queue-runner", name: "queue-runner", member: "jobs", archetype: null, composites: ["WorkQueue", "CacheCluster"], file: "jobs/src/queue-runner.component.ts", runtimes: [local("queue-runner")] },
+      { id: "delivery/edge", name: "edge", member: "delivery", archetype: "infra", composites: ["StaticSite"], file: "delivery/src/edge.component.ts", runtimes: [local("edge")], environments: [localEnv("edge")] },
+      { id: "delivery/loom-backend", name: "loom-backend", member: "delivery", archetype: "service", composites: null, file: "delivery/src/loom-backend.component.ts", runtimes: [local("loom-backend")], environments: [localEnv("loom-backend")] },
+      { id: "jobs/queue-runner", name: "queue-runner", member: "jobs", archetype: null, composites: ["WorkQueue", "CacheCluster"], file: "jobs/src/queue-runner.component.ts", runtimes: [local("queue-runner")], environments: [localEnv("queue-runner")] },
     ]);
     const rows = Object.fromEntries(g.composites.map((c) => [c.id, c]));
     expect(Object.keys(rows)).toEqual(["app/backend", "app/cache", "app/site", "jobs/queue"]);
@@ -332,3 +338,111 @@ describe("the runtimes each component can deploy on (#2674)", () => {
     ]);
   });
 });
+
+/**
+ * Write `files` as the whole tree of a `chant/lifecycle` commit, the way the
+ * lifecycle code stores ledgers, without touching the working tree or index.
+ */
+function lifecycle(root: string, files: Record<string, string>): void {
+  const index = join(root, ".git", "composites-test-index");
+  const run = (args: string[], input?: string) =>
+    execFileSync("git", ["-c", "user.name=t", "-c", "user.email=t@example.com", ...args], {
+      cwd: root,
+      encoding: "utf-8",
+      input,
+      env: { ...process.env, GIT_INDEX_FILE: index },
+    }).trim();
+  rmSync(index, { force: true });
+  for (const [path, text] of Object.entries(files)) run(["update-index", "--add", "--cacheinfo", `100644,${run(["hash-object", "-w", "--stdin"], text)},${path}`]);
+  run(["update-ref", "refs/heads/chant/lifecycle", run(["commit-tree", run(["write-tree"]), "-m", "ledger"])]);
+  rmSync(index, { force: true });
+}
+
+/** One release line; the environment list reads only which ledgers exist. */
+const release = (component: string, env: string) => `${JSON.stringify({ version: 1, component, env, digest: `sha256:${"a".repeat(64)}`, gitSha: "b".repeat(40), runId: "r1", timestamp: "2026-09-24T00:00:00.000Z", actor: "t" })}\n`;
+
+describe("the environments each component may deploy to (#2695)", () => {
+  /** jobs declares staging, prod and the pattern pr-*; its ledger has releases in staging, pr-42 and retired. */
+  function declared(): string {
+    const root = fixture();
+    writeFileSync(join(root, "jobs", "chant.config.ts"), 'export default { environments: ["staging", { name: "prod", endpoint: "https://prod.example" }, "pr-*"] };\n');
+    lifecycle(root, {
+      "_members/jobs/staging/releases.jsonl": release("queue-runner", "staging"),
+      "_members/jobs/pr-42/releases.jsonl": release("queue-runner", "pr-42"),
+      "_members/jobs/retired/releases.jsonl": release("queue-runner", "retired"),
+      "_members/jobs/_gates/queue-runner.jsonl": "",
+      "_members/jobs/notes/README.md": "not a ledger\n",
+      "staging/releases.jsonl": release("edge", "staging"),
+    });
+    return root;
+  }
+
+  test("local is the default, then the config's names in order, then the ledger's, each with its --env line", async () => {
+    const g = result((await workspaceComposites({ cwd: declared() })).doc);
+    expectValid(g);
+    expect(g.components.find((c) => c.id === "jobs/queue-runner")!.environments).toEqual([
+      { name: "local", default: true, source: "builtin", command: "chant run --components queue-runner" },
+      { name: "staging", default: false, source: "config", command: "chant run --components queue-runner --env staging" },
+      { name: "prod", default: false, source: "config", command: "chant run --components queue-runner --env prod" },
+      // The pattern pr-* is no environment by itself, and it covers the ledger's pr-42.
+      { name: "pr-42", default: false, source: "ledger", command: "chant run --components queue-runner --env pr-42" },
+    ]);
+    const jobs = g.members.find((m) => m.name === "jobs")!;
+    expect(jobs.environmentReasons).toEqual([{ code: "environments-ledger-undeclared", message: expect.stringContaining("retired") }]);
+    expect(jobs.runtimeReasons).toEqual([]);
+  });
+
+  test("a member with no _members directory reads the flat ledger, and a config that declares none says so", async () => {
+    const g = result((await workspaceComposites({ cwd: declared() })).doc);
+    // delivery has no _members/delivery, so the flat staging ledger is its; its config declares nothing, so anything goes.
+    expect(g.components.find((c) => c.id === "delivery/edge")!.environments).toEqual([
+      localEnv("edge"),
+      { name: "staging", default: false, source: "ledger", command: "chant run --components edge --env staging" },
+    ]);
+    expect(g.members.find((m) => m.name === "delivery")!.environmentReasons.map((r) => r.code)).toEqual(["environments-none-declared"]);
+    expect(g.members.find((m) => m.name === "docs")!.environmentReasons).toEqual([]);
+  });
+
+  test("with no chant/lifecycle branch, the config's names are the list", async () => {
+    const root = fixture();
+    writeFileSync(join(root, "jobs", "chant.config.ts"), 'export default { environments: ["local", "prod"] };\n');
+    const g = result((await workspaceComposites({ cwd: root })).doc);
+    expectValid(g);
+    expect(g.components.find((c) => c.id === "jobs/queue-runner")!.environments).toEqual([
+      { name: "local", default: true, source: "config", command: "chant run --components queue-runner" },
+      { name: "prod", default: false, source: "config", command: "chant run --components queue-runner --env prod" },
+    ]);
+    expect(g.members.find((m) => m.name === "jobs")!.environmentReasons).toEqual([]);
+  });
+
+  test("a config that can't be read lists local and the ledger's, with the runtimes' code", async () => {
+    const root = declared();
+    writeFileSync(join(root, "jobs", "chant.config.ts"), 'throw new Error("no config here");\nexport default {};\n');
+    const g = result((await workspaceComposites({ cwd: root })).doc);
+    expectValid(g);
+    const jobs = g.members.find((m) => m.name === "jobs")!;
+    expect(jobs.environmentReasons).toEqual([{ code: "runtimes-config-unreadable", message: expect.stringContaining("no config here") }]);
+    expect(g.components.find((c) => c.id === "jobs/queue-runner")!.environments.map((e) => [e.name, e.source])).toEqual([
+      ["local", "builtin"],
+      ["pr-42", "ledger"],
+      ["retired", "ledger"],
+      ["staging", "ledger"],
+    ]);
+  });
+
+  test("a ledger that can't be listed says so, and the config's names are still listed", async () => {
+    const root = fixture();
+    writeFileSync(join(root, "jobs", "chant.config.ts"), 'export default { environments: ["prod"] };\n');
+    const g = result(
+      (
+        await workspaceComposites({
+          cwd: root,
+          readLedgerEnvironments: (m) => (m.name === "jobs" ? { envs: [], reason: { code: "environments-ledger-unreadable", message: "boom" } } : { envs: [], reason: null }),
+        })
+      ).doc,
+    );
+    expectValid(g);
+    expect(g.members.find((m) => m.name === "jobs")!.environmentReasons).toEqual([{ code: "environments-ledger-unreadable", message: "boom" }]);
+    expect(g.components.find((c) => c.id === "jobs/queue-runner")!.environments.map((e) => e.name)).toEqual(["local", "prod"]);
+  });
+});

package/src/workspace/composites.ts

@@ -32,6 +32,11 @@
  * Each component also lists the runtimes it can deploy on (#2674,
  * `runtimes.ts`): `local`, and each lexicon its member configures that hosts
  * `chant run --components`, with the command line for each.
+ *
+ * And each component lists the environments it may deploy to (#2695,
+ * `environments.ts`): `local`, the environments its member's config declares,
+ * and those with a release in the member's ledger on `chant/lifecycle`, with
+ * the command line for each.
  */
 
 import { formatError } from "../cli/format";
@@ -44,6 +49,7 @@ import type { LinkRow } from "./links";
 import { emitDocument, type UnitResult } from "./member-commands";
 import { readerVersion, type ErrorLocation, type WorkspaceErrorCode } from "./declaration";
 import type { ReasonCode } from "./reason-codes";
+import { componentEnvironments, ENVIRONMENT_REASON_CODES, memberEnvironments, readLedgerEnvironments, type ComponentEnvironment, type EnvironmentReason, type LedgerEnvironmentReader, type MemberEnvironments } from "./environments";
 import { componentRuntimes, readRuntimesIn, RUNTIME_REASON_CODES, type ComponentRuntime, type MemberRuntimes, type PluginLoader, type RuntimeReason } from "./runtimes";
 
 /** `$id` of the JSON Schema for the document, shipped beside this file. */
@@ -69,6 +75,9 @@ export type CompositesReasonCode = (typeof COMPOSITES_REASON_CODES)[number];
 /** Why a member's runtimes are only `local`, or leave out a lexicon its config lists (#2674). Closed. */
 export const COMPOSITES_RUNTIME_REASON_CODES = RUNTIME_REASON_CODES;
 
+/** Why a member's environments are only `local`, or leave out one its ledger has (#2695). Closed. */
+export const COMPOSITES_ENVIRONMENT_REASON_CODES = ENVIRONMENT_REASON_CODES;
+
 export interface CompositesMember {
   name: string;
   dir: string;
@@ -79,6 +88,8 @@ export interface CompositesMember {
   chant: string | null;
   /** Why its components' runtimes leave something out: its config, or a lexicon, couldn't be read. Empty for a member not of kind chant. */
   runtimeReasons: RuntimeReason[];
+  /** Why its components' environments are only `local`, or leave one out. Empty for a member not of kind chant. */
+  environmentReasons: EnvironmentReason[];
 }
 
 export interface ComponentEntry {
@@ -94,6 +105,8 @@ export interface ComponentEntry {
   file: string | null;
   /** The runtimes it can deploy on: `local` first, then each hosting lexicon its member configures. */
   runtimes: ComponentRuntime[];
+  /** The environments it may deploy to: `local` first, then the config's, then the ledger's. */
+  environments: ComponentEnvironment[];
 }
 
 export interface ComponentMatch {
@@ -145,7 +158,7 @@ export interface CompositesResult {
 }
 
 /** Read one member's component graph run into components, or the reason it can't be read. */
-function readComponents(member: string, dir: string, run: UnitResult, runtimes: MemberRuntimes | undefined): { components: ComponentEntry[] } | { reason: MemberReason } {
+function readComponents(member: string, dir: string, run: UnitResult, runtimes: MemberRuntimes | undefined, environments: MemberEnvironments | undefined): { components: ComponentEntry[] } | { reason: MemberReason } {
   if (run.exitCode !== 0) {
     const tail = run.stderr.trim().split("\n").slice(-5).join("\n");
     return { reason: { code: "command-failed", message: `chant graph --components exited ${run.exitCode}${tail ? `: ${tail}` : ""}` } };
@@ -166,6 +179,7 @@ function readComponents(member: string, dir: string, run: UnitResult, runtimes:
       composites: composites && composites.length > 0 ? composites : null,
       file: file ? (dir === "." ? file : `${dir}/${file}`) : null,
       runtimes: componentRuntimes(n.id, runtimes),
+      environments: componentEnvironments(n.id, environments, runtimes?.default),
     });
   }
   return { components };
@@ -233,17 +247,19 @@ export function joinComponents(instances: CompositeInstanceRow[], components: Co
   });
 }
 
-function memberEntry(m: ComposedMember, componentReason: MemberReason | null, runtimes: MemberRuntimes | undefined): CompositesMember {
+function memberEntry(m: ComposedMember, componentReason: MemberReason | null, runtimes: MemberRuntimes | undefined, environments: MemberEnvironments | undefined): CompositesMember {
   const reason = m.reason ?? componentReason;
   const status = m.status === "composed" ? (componentReason ? "failed" : "read") : m.status;
-  return { name: m.name, dir: m.dir, kind: m.kind, status, reason, chant: m.chant, runtimeReasons: runtimes?.reasons ?? [] };
+  return { name: m.name, dir: m.dir, kind: m.kind, status, reason, chant: m.chant, runtimeReasons: runtimes?.reasons ?? [], environmentReasons: environments?.reasons ?? [] };
 }
 
 /** Read the workspace's composites and components, and build the document. Never throws a `WorkspaceReadError`. */
-export async function workspaceComposites(query: Omit<GraphQuery, "kind" | "components" | "inTree"> & { loadPlugin?: PluginLoader }): Promise<CompositesResult> {
+export async function workspaceComposites(
+  query: Omit<GraphQuery, "kind" | "components" | "inTree"> & { loadPlugin?: PluginLoader; readLedgerEnvironments?: LedgerEnvironmentReader },
+): Promise<CompositesResult> {
   const head: Head = { $schema: COMPOSITES_OUTPUT_SCHEMA_ID, contract: COMPOSITES_CONTRACT_VERSION, chant: readerVersion() };
   let runtimes = new Map<string, MemberRuntimes>();
-  const { loadPlugin, ...graphQuery } = query;
+  const { loadPlugin, readLedgerEnvironments: readLedger = readLedgerEnvironments, ...graphQuery } = query;
   const { doc: graph, failed, components: runs } = await workspaceGraph({
     ...graphQuery,
     components: true,
@@ -259,15 +275,18 @@ export async function workspaceComposites(query: Omit<GraphQuery, "kind" | "comp
   let componentsFailed = false;
   for (const m of graph.members) {
     const run = m.status === "composed" ? byMember.get(m.name) : undefined;
+    // The ledger is the local chant/lifecycle branch, read from the working tree even with --at, as workspace status reads it.
+    const memberRuntimes = runtimes.get(m.name);
+    const environments = memberRuntimes ? memberEnvironments(memberRuntimes, readLedger(m, query.cwd)) : undefined;
     let reason: MemberReason | null = null;
     if (run) {
-      const read = readComponents(m.name, m.dir, run, runtimes.get(m.name));
+      const read = readComponents(m.name, m.dir, run, memberRuntimes, environments);
       if ("reason" in read) {
         reason = read.reason;
         componentsFailed = true;
       } else components.push(...read.components);
     }
-    members.push(memberEntry(m, reason, runtimes.get(m.name)));
+    members.push(memberEntry(m, reason, memberRuntimes, environments));
   }
   components.sort((a, b) => a.id.localeCompare(b.id));
 

package/src/workspace/conformance/__fixture__/decisions/decision.schema.json

@@ -199,6 +199,17 @@
         }
       }
     },
+    "seal": {
+      "description": "The author's ssh signature over the record (#2688): the bytes <id>\\n<digest>\\n<decided_by>\\n<state>, in the ssh-keygen namespace chant-record, where digest is the record's digest, which leaves this field and reviews out. chant workspace records new --sign and amend --sign write it, and an amendment without --sign removes it. Optional: under a signers file at base, a record with decided_by and no seal that verifies is read with the warning record-unattested.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["signer", "key", "signature"],
+      "properties": {
+        "signer": { "description": "Who signed: decided_by, as the signers file names them.", "type": "string", "minLength": 1 },
+        "key": { "description": "The signing key's fingerprint. Reported, never trusted: the signature is the proof.", "type": "string", "pattern": "^SHA256:[A-Za-z0-9+/]+=*$" },
+        "signature": { "description": "The armored ssh signature, as ssh-keygen -Y sign prints it.", "type": "string", "pattern": "^-----BEGIN SSH SIGNATURE-----\\n" }
+      }
+    },
     "constrains": {
       "description": "What this decision governs: issues (owner/repo#n), other decisions (their ids), workspace members (member:<name>) or files and directories in the workspace (path:<path>, the grammar of an evidence path, #2549). At least one entry: a decision that governs nothing is refused.",
       "type": "array",

package/src/workspace/environments.ts

@@ -0,0 +1,165 @@
+/**
+ * The environments a member's components may deploy to, for `chant workspace
+ * graph --composites` (#2695), so a reader such as hud can offer staging or
+ * prod beside the default without guessing a name.
+ *
+ * Each environment comes from one of three places, and says which:
+ *
+ * - `config`: a name the member's `chant.config.ts` declares in
+ *   `environments`. A pattern such as `pr-*` names no environment by itself
+ *   and is not listed, but it legalizes the ledger's `pr-42`.
+ * - `ledger`: an environment with a release ledger for the member on
+ *   `chant/lifecycle` (`_members/<member>/<env>/releases.jsonl`, or the flat
+ *   `<env>/releases.jsonl`, read the way `workspace status` reads it).
+ * - `builtin`: `local`, which `chant run --components` uses without `--env`
+ *   (`../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.
+ *
+ * `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
+ * default is `local`: `chant.config.ts` has no default environment, and
+ * `chant run` without `--env` deploys to `local` even when the config's
+ * `environments` leaves it out.
+ *
+ * The config is the one `runtimes.ts` loads, in the working tree or the tree
+ * `--at` exported. The ledger is always the local `chant/lifecycle` branch,
+ * as for `workspace status`, and is never fetched.
+ */
+
+import { execFileSync } from "node:child_process";
+import { environmentName, isEnvironmentPattern, matchesDeclaredEnvironment } from "../config";
+import type { ReasonCode } from "./reason-codes";
+import { LOCAL_RUNTIME, type MemberRuntimes } from "./runtimes";
+import { ENV_PATTERN, LIFECYCLE_REF, MEMBERS_DIR } from "./status";
+
+/** The environment `chant run --components` deploys to without `--env`. */
+export const LOCAL_ENVIRONMENT = "local";
+
+/** Why a member's environments are only `local`, or leave out one the ledger has. Closed: part of the read contract. */
+export const ENVIRONMENT_REASON_CODES = [
+  /** The member's chant.config.ts could not be read: the same read and the same code as its runtimes. */
+  "runtimes-config-unreadable",
+  /** The config declares no environments, so only local and the ledger's environments are listed. */
+  "environments-none-declared",
+  /** The ledger has releases in an environment the config's environments no longer cover, so chant run --env would refuse it. */
+  "environments-ledger-undeclared",
+  /** The chant/lifecycle branch exists and the member's ledger directories could not be listed. */
+  "environments-ledger-unreadable",
+] as const satisfies readonly ReasonCode[];
+export type EnvironmentReasonCode = (typeof ENVIRONMENT_REASON_CODES)[number];
+
+export interface EnvironmentReason {
+  code: EnvironmentReasonCode;
+  message: string;
+}
+
+/** One environment a component may deploy to. */
+export interface ComponentEnvironment {
+  /** What `--env` takes. */
+  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. */
+  command: string;
+}
+
+/** The environments a member's ledger has, or why they couldn't be listed. */
+export interface LedgerEnvironments {
+  envs: string[];
+  reason: EnvironmentReason | null;
+}
+
+/** Lists one member's ledger environments; git unless a test swaps it. */
+export type LedgerEnvironmentReader = (member: { name: string; dir: string }, cwd: string) => LedgerEnvironments;
+
+/** What one member's config and ledger say about environments. */
+export interface MemberEnvironments {
+  /** Each environment in list order, without the per-component command. */
+  environments: Omit<ComponentEnvironment, "command">[];
+  reasons: EnvironmentReason[];
+}
+
+function git(cwd: string, args: string[], input?: string): string {
+  return execFileSync("git", args, { cwd, encoding: "utf-8", input, stdio: [input === undefined ? "ignore" : "pipe", "pipe", "pipe"] });
+}
+
+function exists(cwd: string, spec: string): boolean {
+  try {
+    git(cwd, ["rev-parse", "--verify", "--quiet", spec]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The environments with a release ledger for `member` on the local
+ * `chant/lifecycle` branch: the directories under `_members/<member>/` when it
+ * exists (the root member never has one), else the flat layout's top-level
+ * directories, that hold a `releases.jsonl`.
+ */
+export const readLedgerEnvironments: LedgerEnvironmentReader = (member, cwd) => {
+  if (!exists(cwd, `refs/heads/${LIFECYCLE_REF}`)) return { envs: [], reason: null };
+  const own = member.dir !== "." && exists(cwd, `refs/heads/${LIFECYCLE_REF}:${MEMBERS_DIR}/${member.name}`);
+  const base = own ? `${MEMBERS_DIR}/${member.name}/` : "";
+  try {
+    const dirs = git(cwd, ["ls-tree", "--full-tree", `refs/heads/${LIFECYCLE_REF}:${base}`])
+      .split("\n")
+      .map((line) => line.match(/^\d+ tree [0-9a-f]+\t(.+)$/)?.[1])
+      .filter((name): name is string => !!name && ENV_PATTERN.test(name));
+    if (dirs.length === 0) return { envs: [], reason: null };
+    const checked = git(cwd, ["cat-file", "--batch-check"], dirs.map((d) => `refs/heads/${LIFECYCLE_REF}:${base}${d}/releases.jsonl\n`).join(""))
+      .split("\n")
+      .filter(Boolean);
+    return { envs: dirs.filter((_, i) => checked[i] !== undefined && !checked[i].endsWith(" missing")).sort(), reason: null };
+  } catch (err) {
+    const message = (err instanceof Error ? err.message : String(err)).split("\n")[0];
+    return { envs: [], reason: { code: "environments-ledger-unreadable", message: `${LIFECYCLE_REF}:${base || "."}: ${message}` } };
+  }
+};
+
+/** Join a member's config and ledger into its environment list, `local` first, then config order, then the ledger's. */
+export function memberEnvironments(runtimes: MemberRuntimes | undefined, ledger: LedgerEnvironments | undefined): MemberEnvironments {
+  const reasons: EnvironmentReason[] = [];
+  const declared = runtimes?.environments ?? null;
+  if (runtimes && declared === null) {
+    const unreadable = runtimes.reasons.find((r) => r.code === "runtimes-config-unreadable");
+    reasons.push({ code: "runtimes-config-unreadable", message: unreadable?.message ?? "chant.config.ts could not be read" });
+  } else if (declared && declared.length === 0) {
+    reasons.push({ code: "environments-none-declared", message: "chant.config.ts declares no environments, so only local and the environments in the ledger are listed" });
+  }
+  if (ledger?.reason) reasons.push(ledger.reason);
+
+  const literals = (declared ?? []).map(environmentName).filter((n) => !isEnvironmentPattern(n));
+  const ledgerEnvs = ledger?.envs ?? [];
+  const covered = (env: string): boolean => !declared || declared.length === 0 || matchesDeclaredEnvironment(declared, env);
+  const undeclared = ledgerEnvs.filter((e) => e !== LOCAL_ENVIRONMENT && !covered(e));
+  if (undeclared.length > 0) {
+    reasons.push({
+      code: "environments-ledger-undeclared",
+      message: `the ledger has releases in ${undeclared.join(", ")}, which chant.config.ts's environments don't cover, so chant run --env refuses ${undeclared.length === 1 ? "it" : "them"}`,
+    });
+  }
+
+  const out: MemberEnvironments["environments"] = [];
+  const add = (name: string, source: ComponentEnvironment["source"]) => {
+    if (!out.some((e) => e.name === name)) out.push({ name, default: name === LOCAL_ENVIRONMENT, source });
+  };
+  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 };
+}
+
+/** 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}`}` }));
+}

package/src/workspace/read-contract.test.ts

@@ -160,6 +160,9 @@ describe("every schema against the reference workspace (#2543)", () => {
         // #2674: the reference config's lexicons host no component runs, so local is the only runtime, read at HEAD too.
         expect(doc.components[0].runtimes).toEqual([{ name: "local", lexicon: null, default: true, command: "chant run --components app" }]);
         expect(doc.members.find((m) => m.name === "delivery")!.runtimeReasons).toEqual([]);
+        // #2695: the reference config declares no environments, so the app deploys to local only.
+        expect(doc.components[0].environments).toEqual([{ name: "local", default: true, source: "builtin", command: "chant run --components app" }]);
+        expect(doc.members.find((m) => m.name === "delivery")!.environmentReasons.map((r) => r.code)).toEqual(["environments-none-declared"]);
         expect(doc.reasons).toEqual([]);
       }
     },

package/src/workspace/reason-codes.test.ts

@@ -10,7 +10,7 @@ import { join } from "node:path";
 import { describe, expect, test } from "vitest";
 import { REPO } from "./__fixtures__/contract-repo";
 import { MEMBER_RUN_REASON_CODES } from "./compose-graph";
-import { COMPOSITES_ERROR_CODES, COMPOSITES_REASON_CODES, COMPOSITES_RUNTIME_REASON_CODES } from "./composites";
+import { COMPOSITES_ENVIRONMENT_REASON_CODES, COMPOSITES_ERROR_CODES, COMPOSITES_REASON_CODES, COMPOSITES_RUNTIME_REASON_CODES } from "./composites";
 import { WORKSPACE_ERROR_CODES } from "./declaration";
 import { GRAPH_ERROR_CODES } from "./graph-cli";
 import { INTENT_ERROR_CODES, INTENT_FINDING_CODES, INTENT_REASON_CODES } from "./intent";
@@ -19,9 +19,10 @@ import { GROUP_REASON_CODES, MEMBER_REASON_CODES } from "./ls";
 import intentSchema from "./intent.schema.json";
 import { isPluginCode, isReasonCode, REASON_CODES, REASONS } from "./reason-codes";
 import { contract } from "./__fixtures__/contract-repo";
-import { READ_ERROR_CODES, RECORD_REASON_CODES, RECORD_WARNING_CODES, REVIEW_REASON_CODES, SEAL_REASON_CODES } from "./records";
+import { READ_ERROR_CODES, RECORD_REASON_CODES, RECORD_WARNING_CODES, REVIEW_REASON_CODES, SEAL_REASON_CODES, SEAL_WARNING_CODES } from "./records";
 import { AMEND_ERROR_CODES, NEW_ERROR_CODES, REVIEW_ERROR_CODES } from "./records-write";
-import { RECORDS_SINCE_ERROR_CODES } from "./records-since";
+import { CLOSE_ERROR_CODES } from "./records-close";
+import { RECORDS_SINCE_ERROR_CODES, RECORDS_SINCE_REASON_CODES } from "./records-since";
 import { STATUS_ERROR_CODES, STATUS_GATE_REASON_CODES, STATUS_REASON_CODES } from "./status";
 import { WORK_WARNING_CODES } from "./work";
 
@@ -42,18 +43,22 @@ const PER_COMMAND: Record<string, readonly string[]> = {
   RECORD_WARNING_CODES,
   REVIEW_REASON_CODES,
   SEAL_REASON_CODES,
+  SEAL_WARNING_CODES,
   WORK_WARNING_CODES,
   READ_ERROR_CODES,
   NEW_ERROR_CODES,
   AMEND_ERROR_CODES,
   REVIEW_ERROR_CODES,
+  CLOSE_ERROR_CODES,
   RECORDS_SINCE_ERROR_CODES,
+  RECORDS_SINCE_REASON_CODES,
   INTENT_ERROR_CODES,
   INTENT_FINDING_CODES,
   INTENT_REASON_CODES,
   COMPOSITES_ERROR_CODES,
   COMPOSITES_REASON_CODES,
   COMPOSITES_RUNTIME_REASON_CODES,
+  COMPOSITES_ENVIRONMENT_REASON_CODES,
 };
 
 /** Every string in an `enum` under a property named `code`, anywhere in a schema. */