@intentius/chant 0.86.0 → 0.88.0

package/dist/workspace/trust/seal.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Sealed verdicts (#2687, part of #2547): a review entry signed by the
+ * principal it names, so the quorum counts it only when that principal
+ * signed it.
+ *
+ * A seal is a detached ssh signature, the same mechanism as the ssh-commit
+ * attestor (./ssh-commit.ts): `ssh-keygen -Y sign` to make it, and
+ * `ssh-keygen -Y verify` against the signers read at base to check it. It is
+ * made in its own namespace, `chant-review`, so neither a commit signature
+ * nor a signer-set signature can stand in for one.
+ *
+ * The signed bytes are the record id, the verdict's digest, the verdict, the
+ * reviewer and the date, each on its own line with no final newline. The
+ * digest is the record's text digest (`recordTextDigest`), so the seal binds
+ * the verdict to the text it judged. The seal lives inside the reviews block,
+ * which the digest leaves out, so sealing a verdict never moves the digest.
+ *
+ * A record's author seal (#2688) works the same way, in its own namespace,
+ * `chant-record`. It sits in the record's top-level `seal` field, which the
+ * digest also leaves out, and signs the record id, the digest, the author
+ * (the kind's `reviews.decider` field, `decided_by` for decisions) and the
+ * state. An amendment moves the digest, so it has to be signed again.
+ */
+import type { SealCode } from "../records.js";
+import { type TrustPolicy } from "./policy.js";
+/** The ssh signature namespace of a verdict seal. */
+export declare const REVIEW_SEAL_NAMESPACE = "chant-review";
+/** The ssh signature namespace of a record's author seal (#2688). */
+export declare const RECORD_SEAL_NAMESPACE = "chant-record";
+/** A seal as a review entry holds it. */
+export interface VerdictSeal {
+    /** The principal who signed: the reviewer, as the signers file names them. */
+    signer: string;
+    /** The signing key's fingerprint, such as `SHA256:...`. Reported, never trusted: the signature is the proof. */
+    key: string;
+    /** The armored ssh signature. */
+    signature: string;
+}
+/** What a verdict's seal establishes. */
+export interface SealCheck {
+    /** true: the seal verifies for the reviewer against the signers at base. false: it is missing under an active policy, or it fails. null: nothing here can say. */
+    attested: boolean | null;
+    /** Why it is not attested. Absent when `attested` is true. */
+    code?: SealCode;
+    message: string;
+    /** The fingerprint of the key that made the signature, when the signature was checked. */
+    key?: string;
+}
+/** The verdict a seal covers. */
+export interface SealedVerdict {
+    record: string | null;
+    reviewer: string;
+    verdict: string;
+    on: unknown;
+    digest: string | null;
+    seal: unknown;
+}
+/** The bytes a verdict seal signs. */
+export declare function reviewSealPayload(record: string, digest: string, verdict: string, reviewer: string, on: string): Buffer;
+/**
+ * The bytes a record's author seal signs (#2688): the id, the digest, the
+ * author and the state, joined by LF with no final newline. A kind without
+ * states signs an empty last line.
+ */
+export declare function recordSealPayload(record: string, digest: string, author: string, state: string | null): Buffer;
+/** The record an author seal covers (#2688). */
+export interface SealedRecord {
+    record: string | null;
+    digest: string;
+    /** The author as the record names them, or null when it names none. */
+    author: string | null;
+    /** The kind's field that names the author, for messages. */
+    authorField: string;
+    state: string | null;
+    seal: unknown;
+}
+/**
+ * Check a verdict's seal. With a signers file active at base, it verifies
+ * against the keys listed there for the reviewer. With none, a seal present
+ * is checked for integrity only (`ssh-keygen -Y check-novalidate`): nothing
+ * says whose key it is.
+ */
+export declare function checkVerdictSeal(policy: TrustPolicy, v: SealedVerdict): SealCheck;
+/**
+ * Check a record's author seal (#2688), as a verdict's is checked, over
+ * {@link recordSealPayload} in the `chant-record` namespace. A record that
+ * names no author and carries no seal is `seal-missing` with `attested`
+ * null even under an active policy: it claims no author to attest.
+ */
+export declare function checkRecordSeal(policy: TrustPolicy, r: SealedRecord): SealCheck;
+/** Why a seal could not be made. */
+export declare class SealError extends Error {
+    constructor(message: string);
+}
+/**
+ * The key `--sign` names: the file given, or with none, git's
+ * `user.signingkey` when `gpg.format` is `ssh`, as `git commit -S` reads it.
+ * A literal public key (`key::ssh-...`, or `ssh-...`) signs through the ssh
+ * agent holding its private half. Returns the file to pass to ssh-keygen,
+ * and a cleanup for a temporary one.
+ */
+export declare function resolveSigningKey(sign: string | true, cwd: string): {
+    file: string;
+    cleanup: () => void;
+};
+/**
+ * Seal a verdict with the key in `keyFile` (a private key, or a public key
+ * whose private half the ssh agent holds). Throws a {@link SealError}.
+ */
+export declare function sealVerdict(keyFile: string, v: {
+    record: string;
+    digest: string;
+    verdict: string;
+    reviewer: string;
+    on: string;
+}): VerdictSeal;
+/**
+ * Seal a record's author (#2688) with the key in `keyFile`, over
+ * {@link recordSealPayload}. Throws a {@link SealError}.
+ */
+export declare function sealRecord(keyFile: string, r: {
+    record: string;
+    digest: string;
+    author: string;
+    state: string | null;
+}): VerdictSeal;
+//# sourceMappingURL=seal.d.ts.map

package/dist/workspace/trust/seal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"seal.d.ts","sourceRoot":"","sources":["../../../src/workspace/trust/seal.ts"],"names":[],"mappings":"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"}

package/dist/workspace/trust/ssh-commit.d.ts

@@ -25,6 +25,13 @@ export interface SignedCommit {
  * continuation lines, to get the bytes it signed.
  */
 export declare function splitSignedCommit(raw: Buffer, header?: string): SignedCommit;
+/** Run ssh-keygen; `missing` is true when it is not installed. Shared with the verdict seals (./seal.ts). */
+export declare function sshKeygen(args: string[], input?: Buffer): {
+    status: number | null;
+    stdout: string;
+    stderr: string;
+    missing: boolean;
+};
 /**
  * Check a detached ssh signature over `payload` in `namespace` against
  * `signers`. Shared with the rotation check (#2553), which signs signer sets

package/dist/workspace/trust/ssh-commit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ssh-commit.d.ts","sourceRoot":"","sources":["../../../src/workspace/trust/ssh-commit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAMH,OAAO,KAAK,EAAsC,cAAc,EAAE,MAAM,YAAY,CAAC;AACrF,OAAO,EAAwB,KAAK,MAAM,EAAE,MAAM,UAAU,CAAC;AAI7D,uEAAuE;AACvE,MAAM,WAAW,YAAY;IAC3B,sFAAsF;IACtF,OAAO,EAAE,MAAM,CAAC;IAChB,uEAAuE;IACvE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,SAAW,GAAG,YAAY,CAsB9E;AAmBD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,MAAM,EAAE,EACjB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,GAChB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAuBjG;AAED,eAAO,MAAM,iBAAiB,EAAE,cAW/B,CAAC"}
+{"version":3,"file":"ssh-commit.d.ts","sourceRoot":"","sources":["../../../src/workspace/trust/ssh-commit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAMH,OAAO,KAAK,EAAsC,cAAc,EAAE,MAAM,YAAY,CAAC;AACrF,OAAO,EAAwB,KAAK,MAAM,EAAE,MAAM,UAAU,CAAC;AAI7D,uEAAuE;AACvE,MAAM,WAAW,YAAY;IAC3B,sFAAsF;IACtF,OAAO,EAAE,MAAM,CAAC;IAChB,uEAAuE;IACvE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,SAAW,GAAG,YAAY,CAsB9E;AAUD,6GAA6G;AAC7G,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG;IAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAIrI;AAID;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,MAAM,EAAE,EACjB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,GAChB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAuBjG;AAED,eAAO,MAAM,iBAAiB,EAAE,cAW/B,CAAC"}

package/dist/workspace/work.d.ts

@@ -17,9 +17,9 @@
  * - `implements`: each decision it names, with that decision's state;
  *
  * and each decision `implementedBy`, the work records naming it. The
- * warnings are closed codes. `work-done-gap-open` is not raised here: only
- * `graph --intent` walks a region, so only it can tell whether the finding a
- * done item came from still fires. It never writes a record.
+ * warnings are closed codes. `work-done-gap-open` is not raised here: it
+ * takes a walk of the item's region, which `graph --intent` makes and
+ * `records` asks it for (#2686). It never writes a record.
  */
 import { type LoadedRecordKind, type ReadRecordsOptions, type RecordEntry } from "./records.js";
 /** Why a work record carries a warning. Closed, like the record warning codes. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant",
-  "version": "0.86.0",
+  "version": "0.88.0",
   "description": "Declarative infrastructure-as-code toolkit — TypeScript on Node.js",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",

package/src/cli/handlers/misc.ts

@@ -11,16 +11,8 @@ import { homedir } from "os";
 import type { ResourceSelector } from "../../lexicon";
 import { formatError, formatSuccess, formatWarning, formatBold } from "../format";
 import type { CommandContext } from "../registry";
-import { createRequire } from "module";
 import { listComponents, describeComponent } from "../../components/cli-support";
-
-const CHANT_VERSION: string = (() => {
-  try {
-    return createRequire(import.meta.url)("../../../package.json").version ?? "0.0.0";
-  } catch {
-    return "0.0.0";
-  }
-})();
+import { CHANT_VERSION } from "../version";
 
 const AUDIT_FORMATS: AuditFormat[] = ["stylish", "json", "sarif", "markdown", "html"];
 const AUDIT_TIERS: AuditTier[] = ["merge-worthy", "all"];

package/src/cli/main.ts

@@ -387,6 +387,12 @@ export function parseArgs(args: string[]): ParsedArgs {
       // `chant workspace records review <id> --by <principal>` (#2670): whoever the caller says.
       result.by = args[++i];
       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;
     } else if (arg === "--session") {
       // `chant workspace records review <id> --session <id>` (#2670)
       result.session = args[++i];
@@ -752,32 +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>] [--dry-run]
+  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. The principal is not checked; attestation is
-                        the seal's job. Prints {path, id, review}
+                        --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. 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,6 +297,11 @@ 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.
+   * 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;
   /** `chant workspace records new <kind> --prefix <prefix>` (#2670): the id prefix to allocate under. */

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."
+        }
+      }
     }
   }
 }