@intentius/chant 0.86.0 → 0.88.0

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

@@ -154,6 +154,17 @@
             "type": "string",
             "minLength": 1
           },
+          "seal": {
+            "description": "The reviewer's ssh signature over the verdict (#2687): the bytes <id>\\n<digest>\\n<verdict>\\n<reviewer>\\n<on>, in the ssh-keygen namespace chant-review. chant workspace records review --sign writes it. Once a signers file is active at base, a verdict counts toward the quorum only when its seal verifies for its reviewer against that file. A seal needs a digest.",
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["signer", "key", "signature"],
+            "properties": {
+              "signer": { "description": "Who signed: the reviewer, 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" }
+            }
+          },
           "proposes": {
             "description": "With a dissent, the id of a new proposed decision the reviewer opened.",
             "$ref": "#/definitions/decisionId"
@@ -172,6 +183,7 @@
             "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$"
           }
         },
+        "dependencies": { "seal": ["digest"] },
         "if": {
           "required": ["verdict"],
           "properties": { "verdict": { "const": "dissent" } }
@@ -187,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}`}` }));
+}