@intentius/chant 0.87.0 → 0.88.0

package/src/cli/main.ts

@@ -389,6 +389,7 @@ export function parseArgs(args: string[]): ParsedArgs {
       if (!result.by || result.by.startsWith("-")) throw new Error("--by needs the reviewer: --by <principal>");
     } else if (arg === "--sign") {
       // `chant workspace records review <id> --sign [<key file>]` (#2687): seal the verdict.
+      // `records new` and `records amend` take it too, to seal the record's author (#2688).
       // With no key file, git's user.signingkey, as `git commit -S` reads it.
       const next = args[i + 1];
       result.sign = next !== undefined && !next.startsWith("-") ? args[++i] : true;
@@ -757,34 +758,45 @@ Workspace (level 1, #2524):
                         --require attested exits 2 if any record is not
                         attested. A pinned file that changed is a warning,
                         asset-drift or asset-missing
-  workspace records [--kind <kind file>] --since <rev> [--at <rev>] [--json]
+  workspace records [--kind <kind file>] --since <rev|session id> [--at <rev>] [--json]
                         What changed in the records between <rev> and --at
                         (default: the working tree): new and removed records,
                         state transitions, new verdicts, new supersessions
-                        and changed pins
+                        and changed pins. A session id compares the commits
+                        the session opened and closed at
   workspace records pin <path>
                         Print the path from the workspace root and the
                         sha256 of a file, for a decision's evidence pin
-  workspace records new [<kind file>] --from <file|-> [--prefix <prefix>] [--dry-run]
+  workspace records new [<kind file>] --from <file|-> [--prefix <prefix>] [--sign [<key file>]] [--dry-run]
                         Write one new record in the kind's directory from
                         the JSON fields given, after validating them as
                         records would read them. Without a kind file, the one
                         kind the declaration names. Allocates the next id when
-                        the fields hold none. Prints {path, id} as JSON and
-                        never commits
-  workspace records amend <id> [--kind <kind file>] --set <file|-> [--dry-run]
+                        the fields hold none. --sign seals the record's author
+                        (decided_by for decisions) with an ssh key. Prints
+                        {path, id} as JSON and never commits
+  workspace records amend <id> [--kind <kind file>] --set <file|-> [--sign [<key file>]] [--dry-run]
                         Set top-level fields of one record. A closed record
                         never changes, and an approved one changes only its
                         state (upward), pins and reviews; anything else is
-                        refused with amend-supersede-instead. Prints
+                        refused with amend-supersede-instead. --sign seals
+                        the author again; without it an amendment removes
+                        the author seal and says so. Prints
                         {path, id, changed}
   workspace records review <id> [--kind <kind file>] --verdict agree|dissent|abstain --by <principal> [--note <text>] [--session <id>] [--sign [<key file>]] [--dry-run]
                         Append a review to one record, dated and bound to
                         the digest of the record text. A dissent needs
                         --note. --sign seals it with an ssh key (git's
                         user.signingkey without a file); under a signers
-                        file at base only a sealed verdict counts. Prints
+                        file at base only a sealed verdict counts. With
+                        --session, the session must be open, and the verdict
+                        is appended to its verdicts too. Prints
                         {path, id, review}
+  workspace records close <session id> [--kind <session kind file>] [--dry-run]
+                        Close an open review session: its state, close time,
+                        closing commit and seal, in one write. Without
+                        --kind, the one session kind the declaration names.
+                        Prints {path, id, changed, seal, closedRev}
   workspace verify [--base <rev>] [--head <rev>] [--require attested]
                         Check the commits in base..head against the signers
                         and roles read from base. A change to the signers file

package/src/cli/mcp/server.test.ts

@@ -1,11 +1,15 @@
 import { describe, test, expect, beforeEach, afterEach } from "vitest";
 import { McpServer } from "./server";
+import { readFileSync } from "node:fs";
 import { mkdir, rm, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 import type { LexiconPlugin } from "../../lexicon";
 import type { Serializer } from "../../serializer";
 
+/** The version in `packages/core/package.json`, read here apart from the code under test. */
+const CORE_VERSION: string = JSON.parse(readFileSync(join(import.meta.dirname, "..", "..", "..", "package.json"), "utf-8")).version;
+
 function createMockPlugin(overrides?: Partial<LexiconPlugin>): LexiconPlugin {
   return {
     name: "mock",
@@ -51,7 +55,16 @@ describe("McpServer", () => {
       expect(result.protocolVersion).toBe("2026-07-28");
       expect(result.capabilities).toBeDefined();
       expect((result.serverInfo as Record<string, unknown>).name).toBe("chant");
-      expect((result.serverInfo as Record<string, unknown>).version).toBe("0.1.0");
+      expect((result.serverInfo as Record<string, unknown>).version).toBe(CORE_VERSION);
+    });
+
+    test("server info names the installed chant's version, from core's package.json (#2689)", async () => {
+      expect(CORE_VERSION).toMatch(/^\d+\.\d+\.\d+/);
+      expect(CORE_VERSION).not.toBe("0.1.0");
+      for (const params of [{}, { protocolVersion: "2024-11-05" }]) {
+        const response = await server.handleRequest({ jsonrpc: "2.0", id: 1, method: "initialize", params });
+        expect(((response.result as Record<string, unknown>).serverInfo as Record<string, unknown>).version).toBe(CORE_VERSION);
+      }
     });
 
     test("capabilities include tools and resources", async () => {

package/src/cli/mcp/server.ts

@@ -13,6 +13,7 @@ import { createSnapshotTool, createDiffTool } from "./lifecycle-tools";
 import { setGateOrigin } from "../../lifecycle/gate-origin";
 import { createOpListTool, createOpRunTool, createOpStatusTool, createOpApproveTool, createOpReportTool } from "./op-tools";
 import { buildResourcesList, handleResourcesRead } from "./resource-handlers";
+import { CHANT_VERSION } from "../version";
 
 /**
  * Protocol versions this server understands, newest first. `initialize` and
@@ -223,7 +224,8 @@ export class McpServer {
     return {
       protocolVersion: negotiateProtocolVersion(protocolVersion),
       capabilities: { tools: {}, resources: {} },
-      serverInfo: { name: "chant", version: "0.1.0" },
+      // The installed chant's version, so a client can tell which chant it talks to (#2689).
+      serverInfo: { name: "chant", version: CHANT_VERSION },
     };
   }
 

package/src/cli/registry.ts

@@ -297,7 +297,10 @@ export interface ParsedArgs {
   verdict?: string;
   /** `chant workspace records review <id> --by <principal>` (#2670): the reviewer, as the caller names them. */
   by?: string;
-  /** `chant workspace records review <id> --sign [<key file>]` (#2687): the key that seals the verdict, or true for git's user.signingkey. */
+  /**
+   * `chant workspace records review <id> --sign [<key file>]` (#2687): the key that seals the verdict, or true for git's user.signingkey.
+   * On `records new` and `records amend`, the key that seals the record's author (#2688).
+   */
   sign?: string | true;
   /** `chant workspace records review <id> --session <id>` (#2670): the review session the verdict was given in. */
   session?: string;

package/src/cli/version.ts

@@ -0,0 +1,15 @@
+import { createRequire } from "node:module";
+
+/**
+ * The installed chant's version, read from `@intentius/chant`'s own
+ * package.json, or "0.0.0" when it can't be read. The path is the same from
+ * `src/cli/` and `dist/cli/`, so it holds whether chant runs from source or
+ * from its build.
+ */
+export const CHANT_VERSION: string = (() => {
+  try {
+    return (createRequire(import.meta.url)("../../package.json") as { version?: string }).version ?? "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+})();

package/src/workspace/__fixtures__/sessions.ts

@@ -64,3 +64,44 @@ export function reviewed(root: string, reviewers: string[], session: string, sta
       .replace(/^reviews: .*$/m, reviewers.length ? `reviews:\n${reviews}` : "reviews: []"),
   );
 }
+
+/**
+ * Declare the fixture's two kinds in a chant.workspace.json (#2693): the
+ * decisions at the root and the session kind in the design member, as the
+ * reference workspace declares them, so review --session, close and
+ * --since <session id> find the session kind.
+ */
+export function declareSessions(root: string): void {
+  writeFileSync(
+    join(root, "chant.workspace.json"),
+    `${JSON.stringify(
+      {
+        name: "sessions",
+        schema: 1,
+        members: [{ name: "design", dir: "design", kind: "other", because: "the session fixture", records: [{ kind: "sessions/session.kind.mjs" }] }],
+        records: [{ kind: DECISIONS_KIND }],
+        pins: [],
+      },
+      null,
+      2,
+    )}\n`,
+  );
+}
+
+/** The fields of a new open session, as a UI sends them to records new. */
+export function newSessionFields(over: Record<string, unknown> = {}): string {
+  return JSON.stringify({
+    schema: 1,
+    title: "Second walk",
+    state: "open",
+    agenda: [{ record: "ref-001" }, { record: "ref-002" }],
+    attendance: [
+      { principal: "lex00", class: "person" },
+      { principal: "alice", class: "person" },
+    ],
+    opened: "2026-09-25T09:00:00Z",
+    closed: null,
+    verdicts: [],
+    ...over,
+  });
+}

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",