@intentius/chant 0.85.0 → 0.86.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant",
-  "version": "0.85.0",
+  "version": "0.86.0",
   "description": "Declarative infrastructure-as-code toolkit — TypeScript on Node.js",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",
@@ -50,6 +50,16 @@
       "default": "./src/cli/index.ts"
     },
     "./workspace/*.schema.json": "./src/workspace/*.schema.json",
+    "./workspace/conformance": {
+      "development": "./src/workspace/conformance/index.ts",
+      "types": "./dist/workspace/conformance/index.d.ts",
+      "default": "./src/workspace/conformance/index.mjs"
+    },
+    "./workspace/conformance/vitest": {
+      "development": "./src/workspace/conformance/vitest.ts",
+      "types": "./dist/workspace/conformance/vitest.d.ts",
+      "default": "./src/workspace/conformance/vitest.ts"
+    },
     "./cli/*": {
       "development": "./src/cli/*.ts",
       "types": "./dist/cli/*.d.ts",
@@ -104,6 +114,14 @@
   "devDependencies": {
     "@cdktn/hcl2json": "^0.24.0"
   },
+  "peerDependencies": {
+    "vitest": ">=2"
+  },
+  "peerDependenciesMeta": {
+    "vitest": {
+      "optional": true
+    }
+  },
   "overrides": {
     "esbuild": "^0.28.1"
   }

package/src/cli/main.ts

@@ -375,6 +375,26 @@ export function parseArgs(args: string[]): ParsedArgs {
       if (!result.intent || result.intent.startsWith("-")) throw new Error("--intent needs a region: --intent <path[:start-end]>");
     } else if (arg === "--current") {
       result.current = true;
+    } else if (arg === "--set") {
+      // `chant workspace records amend <id> --set <file|->` (#2670)
+      result.set = args[++i];
+      if (!result.set || (result.set.startsWith("-") && result.set !== "-")) throw new Error("--set needs a JSON file, or - for standard input: --set <file|->");
+    } else if (arg === "--verdict") {
+      // `chant workspace records review <id> --verdict agree|dissent|abstain` (#2670)
+      result.verdict = args[++i];
+      if (!result.verdict || result.verdict.startsWith("-")) throw new Error("--verdict needs agree, dissent or abstain");
+    } else if (arg === "--by") {
+      // `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 === "--session") {
+      // `chant workspace records review <id> --session <id>` (#2670)
+      result.session = args[++i];
+      if (!result.session || result.session.startsWith("-")) throw new Error("--session needs a session id: --session <id>");
+    } else if (arg === "--prefix") {
+      // `chant workspace records new <kind> --prefix <prefix>` (#2670): the id prefix to allocate under.
+      result.prefix = args[++i];
+      if (!result.prefix || result.prefix.startsWith("-")) throw new Error("--prefix needs an id prefix: --prefix <prefix>");
     } else if (arg === "--require") {
       // `chant workspace records|verify --require attested` (#2547)
       result.require = args[++i];
@@ -721,8 +741,9 @@ Workspace (level 1, #2524):
                         beside it and marks the members whose digests differ.
                         Read only; never fetches. --json prints the
                         read-contract document
-  workspace records --kind <kind file> [--current] [--at <rev>] [--base <rev>] [--require attested] [--json]
-                        Read the records a record kind locates, validated
+  workspace records [--kind <kind file>] [--current] [--at <rev>] [--base <rev>] [--require attested] [--json]
+                        Without --kind, every record kind the declaration
+                        names. Read the records a record kind locates, validated
                         against its schema, with reason codes for invalid
                         ones. --current leaves out superseded records; --at
                         reads a commit's git objects. Needs no workspace file.
@@ -731,9 +752,32 @@ 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]
+                        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
   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]
+                        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]
+                        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
+                        {path, id, changed}
+  workspace records review <id> [--kind <kind file>] --verdict agree|dissent|abstain --by <principal> [--note <text>] [--session <id>] [--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}
   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
@@ -784,7 +828,8 @@ Workspace (level 1, #2524):
   workspace graph --intent <path[:start-end]> [--at <rev>] [--kind <kind file>...] [--json]
                         The intent graph over one region: the commits that
                         touched it, the decisions whose constrains cover it,
-                        the artifacts they pin, and findings with closed codes
+                        the artifacts they pin, and findings with closed codes.
+                        Without --kind, every record kind the declaration names
 
 Lifecycle (alias: lc):
   lifecycle snapshot <env>  Query API, save metadata to orphan branch

package/src/cli/registry.ts

@@ -291,6 +291,16 @@ export interface ParsedArgs {
   intent?: string;
   /** `chant workspace records --current` (#2546): leave out records a closed record supersedes. */
   current?: boolean;
+  /** `chant workspace records amend <id> --set <file|->` (#2670): the JSON fields to set. */
+  set?: string;
+  /** `chant workspace records review <id> --verdict <v>` (#2670): agree, dissent or abstain. */
+  verdict?: string;
+  /** `chant workspace records review <id> --by <principal>` (#2670): the reviewer, as the caller names them. */
+  by?: string;
+  /** `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. */
+  prefix?: string;
   /** `chant workspace records|verify --require attested` (#2547): the provenance level a gate requires. */
   require?: string;
   /**
@@ -416,7 +426,7 @@ export interface ParsedArgs {
   plan?: string;
   /** `chant operator log --op <name>` (#2029) — restrict the tick history to one ConvergeOp by name. Omitted, every discovered ConvergeOp's ticks are merged into one timeline. */
   op?: string;
-  /** `chant operator log --since <iso>` (#2029) — only entries at or after this ISO-8601 instant. */
+  /** `chant operator log --since <iso>` (#2029) — only entries at or after this ISO-8601 instant. `chant workspace records --since <rev>` (#2673) — the revision to compare the records with. */
   since?: string;
   /** `chant operator log --limit <n>` (#2029) — keep only the newest n entries (still printed oldest-first). */
   limit?: number;

package/src/lifecycle/gate-ledger.ts

@@ -47,6 +47,9 @@ import type { GateApprover, GatePolicyDecision, ResolvedGateApproval } from "../
 import { readBlobFromPath, readPathSha, readBlobBySha, writeBlobToPath, RefCASConflictError } from "./git";
 
 const DIR = "_gates";
+
+/** The directory on the `chant/lifecycle` branch that holds gate ledgers, under a member's prefix when it has one. */
+export const GATES_DIR = DIR;
 const APPEND_RETRY_ATTEMPTS = 5;
 
 /**
@@ -350,7 +353,18 @@ export async function readGateLedger(
 ): Promise<{ resolutions: GateResolutionRecord[]; pending: PendingGateRecord[]; malformed: number }> {
   const content = await readBlobFromPath(DIR, filename(op), opts);
   if (!content) return { resolutions: [], pending: [], malformed: 0 };
+  return parseGateLedger(content);
+}
 
+/**
+ * Split the text of one gate ledger file into its two kinds of line, oldest
+ * first, the way {@link readGateLedger} reads it. Exported for a reader that
+ * fetches the file itself, such as `chant workspace status` (#2674), which
+ * reads every member's ledger by its full path from the workspace root.
+ */
+export function parseGateLedger(
+  content: string,
+): { resolutions: GateResolutionRecord[]; pending: PendingGateRecord[]; malformed: number } {
   const lines = content.split("\n").map((l) => l.trim()).filter(Boolean);
   const resolutions: GateResolutionRecord[] = [];
   const pending: PendingGateRecord[] = [];

package/src/workspace/__fixtures__/sessions.ts

@@ -0,0 +1,66 @@
+/**
+ * A repository with the reference workspace's decisions and design member,
+ * and helpers that write sessions and review entries into it, for the
+ * session and records --since tests (#2673).
+ */
+
+import { cpSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { sessionSeal } from "../record-sessions";
+import { commitAll, git, REPO, scratchDir } from "./contract-repo";
+
+export const SESSIONS_KIND = "design/sessions/session.kind.mjs";
+export const DECISIONS_KIND = "decisions/decision.kind.mjs";
+
+/** A git repository holding a copy of the reference workspace's decisions and design member. */
+export function sessionsRepo(): string {
+  const root = scratchDir("chant-sessions-");
+  for (const d of ["decisions", "design"]) cpSync(join(REPO, "reference-workspace", d), join(root, d), { recursive: true });
+  git(root, "init", "-q");
+  commitAll(root, "reference");
+  return root;
+}
+
+/** A session file's text, sealed when it is closed. */
+export function sessionText(s: { id: string; state: "open" | "closed"; verdicts?: { record: string; principal: string; verdict: string }[]; agenda?: string[] }): string {
+  const lines = [
+    "---",
+    "schema: 1",
+    `id: "${s.id}"`,
+    `title: "Session ${s.id}"`,
+    `state: "${s.state}"`,
+    "agenda:",
+    ...(s.agenda ?? ["ref-001"]).map((r) => `  - record: "${r}"`),
+    "attendance:",
+    '  - principal: "lex00"',
+    '    class: "person"',
+    '  - principal: "alice"',
+    '    class: "person"',
+    '  - principal: "helper"',
+    '    class: "agent"',
+    'opened: "2026-09-24T18:00:00Z"',
+    `closed: ${s.state === "closed" ? '"2026-09-24T19:00:00Z"' : "null"}`,
+    ...(s.verdicts?.length
+      ? ["verdicts:", ...s.verdicts.flatMap((v) => [`  - record: "${v.record}"`, `    principal: "${v.principal}"`, `    verdict: "${v.verdict}"`])]
+      : ["verdicts: []"]),
+    ...(s.state === "closed" ? ['closed_digest: "SEAL"'] : []),
+    "---",
+    "",
+    `# Session ${s.id}`,
+    "",
+  ];
+  const text = lines.join("\n");
+  return s.state === "closed" ? text.replace('"SEAL"', `"${sessionSeal(text, "closed_digest")}"`) : text;
+}
+
+/** Rewrite ref-001 with the given review entries, each naming `session`. */
+export function reviewed(root: string, reviewers: string[], session: string, state = "decided"): void {
+  const file = join(root, "decisions", "ref-001-how-the-app-is-deployed.md");
+  const reviews = reviewers.map((r) => `  - reviewer: "${r}"\n    verdict: "agree"\n    on: "2026-09-24"\n    session: "${session}"`).join("\n");
+  writeFileSync(
+    file,
+    readFileSync(file, "utf-8")
+      .replace(/^state: .*$/m, `state: "${state}"`)
+      .replace(/^reviews: .*$/m, reviewers.length ? `reviews:\n${reviews}` : "reviews: []"),
+  );
+}

package/src/workspace/checks/records.ts

@@ -13,6 +13,7 @@
  * | WSP112 | a pinned file that does not exist |
  * | WSP113 | a pinned file that a superseding record pins at the old hash: the artifact did not follow the decision |
  * | WSP114 | the records of `--kind` can't be read (fixed) |
+ * | WSP115 | a record kind the declaration names is missing or does not load as one (fixed, #2680) |
  */
 
 import type { WorkspaceCheck, WorkspaceDiagnostic } from "../checks";
@@ -80,4 +81,22 @@ export const RECORD_CHECKS: readonly WorkspaceCheck[] = [
       return [{ checkId: this.id, severity: this.severity, message: `--kind ${facts.kind}: ${facts.error.code}: ${facts.error.message}`, pointer: "" }];
     },
   },
+  {
+    id: "WSP115",
+    name: "record-kind-unloadable",
+    description: "Every record kind the declaration names is a file that exports a valid recordKind, with the schema it names.",
+    severity: "error",
+    configurable: false,
+    check(ctx) {
+      return (ctx.facts?.declaredKinds ?? [])
+        .filter((k) => k.reason !== null)
+        .map((k) => ({
+          checkId: this.id,
+          severity: this.severity,
+          message: `${k.declared.member === null ? "the workspace" : `member ${k.declared.member}`} declares the record kind ${k.declared.kind}, which can't be loaded: ${k.reason!.code}: ${k.reason!.message}`,
+          ...(k.declared.member !== null ? { entity: k.declared.member } : {}),
+          pointer: `${k.declared.pointer}/kind`,
+        }));
+    },
+  },
 ];

package/src/workspace/checks.test.ts

@@ -58,6 +58,8 @@ describe("the WSP catalog", () => {
       "link-kind-unknown",
       // --kind names a record kind, and records that can't be read check nothing (#2549).
       "records-unreadable",
+      // A declared record kind that doesn't load breaks every reader's default (#2680).
+      "record-kind-unloadable",
     ]);
   });
 

package/src/workspace/checks.ts

@@ -27,6 +27,7 @@
  * | WSP091 to WSP097 | member links (#2539) |
  * | WSP101 to WSP106 | generated files |
  * | WSP111 to WSP114 | records read with `--kind` (#2549) |
+ * | WSP115 | the record kinds the declaration names (#2680) |
  */
 
 import { realpathSync } from "node:fs";
@@ -44,6 +45,7 @@ import { gatherGeneratedFacts, GENERATED_CHECKS, type GeneratedFileFacts } from
 import { gatherLedgerFacts, LEDGER_CHECKS, type MemberLedgerFacts } from "./checks/ledgers";
 import { gatherPipelineFacts, PIPELINE_CHECKS, type MemberPipelineFacts } from "./checks/pipelines";
 import { RECORD_CHECKS, type RecordFacts } from "./checks/records";
+import { loadDeclaredKinds, type DeclaredKind } from "./declared-kinds";
 
 /**
  * What the checks beyond the declaration read, gathered from the checkout
@@ -59,6 +61,8 @@ export interface WorkspaceFacts {
   generated?: readonly GeneratedFileFacts[];
   /** The records of the kind named with `--kind`, with their pins checked (#2549). */
   records?: RecordFacts;
+  /** The record kinds the declaration names, each loaded, or only looked for under `--at` (#2680). */
+  declaredKinds?: readonly DeclaredKind[];
 }
 
 /** What every declaration check reads. */
@@ -444,7 +448,9 @@ export async function runDeclarationChecks(
   }
   const { registry, problems } = loadKindRegistry(declaration.pins, root);
   const gathered = options.gather === false || options.tree ? {} : await gatherWorkspaceFacts(root, declaration, options);
-  const facts: WorkspaceFacts = options.records ? { ...gathered, records: options.records } : gathered;
+  // The declared record kinds load from the working tree; under --at only whether each exists at the revision is checked (#2680).
+  const declaredKinds = options.gather === false ? undefined : await loadDeclaredKinds(declaration, tree, root, { load: !options.tree });
+  const facts: WorkspaceFacts = { ...gathered, ...(options.records ? { records: options.records } : {}), ...(declaredKinds ? { declaredKinds } : {}) };
   const ctx: WorkspaceCheckContext = { declaration, tree, groups, kinds: registry, kindProblems: problems, facts };
   const findings = runWorkspaceChecks(ctx);
   const { active, suppressed } = applyCheckSettings(declaration, findings);

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. 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). Every code is in the one closed list of `reason-codes.ts`.",
   "oneOf": [
     {
       "$ref": "#/$defs/result"
@@ -130,7 +130,8 @@
         "kind",
         "status",
         "reason",
-        "chant"
+        "chant",
+        "runtimeReasons"
       ],
       "properties": {
         "name": {
@@ -187,6 +188,28 @@
             "null"
           ],
           "description": "The chant version the member's toolchain reported, or null when a chant older than member-run read it."
+        },
+        "runtimeReasons": {
+          "description": "Why the runtimes of the member's components leave something out: its chant.config.ts, or a lexicon it lists, could not be read. Empty for a member not of kind chant, and when nothing was left out.",
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": [
+              "code",
+              "message"
+            ],
+            "properties": {
+              "code": {
+                "enum": [
+                  "runtimes-config-unreadable",
+                  "runtimes-lexicon-unreadable"
+                ]
+              },
+              "message": {
+                "type": "string"
+              }
+            }
+          }
         }
       },
       "if": {
@@ -327,7 +350,8 @@
         "member",
         "archetype",
         "composites",
-        "file"
+        "file",
+        "runtimes"
       ],
       "properties": {
         "id": {
@@ -368,6 +392,14 @@
             "null"
           ],
           "description": "The component's file from the workspace root, when the member's chant names it."
+        },
+        "runtimes": {
+          "description": "The runtimes the component can deploy on, the list chant run --components --on accepts in its member: local first, then each lexicon the member's chant.config.ts lists whose opRuntime hosts component runs, in config order.",
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "$ref": "#/$defs/runtime"
+          }
         }
       }
     },
@@ -466,6 +498,36 @@
         },
         "composites": false
       }
+    },
+    "runtime": {
+      "type": "object",
+      "required": [
+        "name",
+        "lexicon",
+        "default",
+        "command"
+      ],
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "What --on takes: local, or the lexicon's name."
+        },
+        "lexicon": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "The lexicon that hosts the runtime, or null for local."
+        },
+        "default": {
+          "type": "boolean",
+          "description": "True for the runtime chant run --components uses without --on. That is local until chant.config.ts can name a default."
+        },
+        "command": {
+          "type": "string",
+          "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."
+        }
+      }
     }
   }
 }

package/src/workspace/composites.test.ts

@@ -7,7 +7,7 @@
  * (`read-contract.test.ts`).
  */
 
-import { writeFileSync } from "node:fs";
+import { mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { afterAll, describe, expect, test } from "vitest";
 import type { GraphIR, IRNode } from "../graph-ir";
@@ -18,6 +18,7 @@ import {
   COMPOSITES_ERROR_CODES,
   COMPOSITES_OUTPUT_SCHEMA_ID,
   COMPOSITES_REASON_CODES,
+  COMPOSITES_RUNTIME_REASON_CODES,
   compositeInstances,
   joinComponents,
   workspaceComposites,
@@ -54,6 +55,9 @@ const componentIr = (components: { name: string; composites?: string[]; archetyp
     { groups: { byWave: { "wave-1": components.map((c) => c.name) } } },
   );
 
+/** The built-in runtime every component has. */
+const local = (name: string) => ({ name: "local", lexicon: null, default: true, 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
@@ -106,6 +110,7 @@ describe("composites output schema", () => {
     expect(schema.$defs.failure.properties.error.properties.code.enum).toEqual([...COMPOSITES_ERROR_CODES]);
     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]);
   });
 });
 
@@ -117,7 +122,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 });
+  const component = (member: string, name: string, composites: string[] | null = null): ComponentEntry => ({ id: `${member}/${name}`, name, member, archetype: null, composites, file: null, runtimes: [] });
 
   test("an instance carries every kind and lexicon of its nodes", () => {
     expect(instances.map((i) => [i.id, i.instance, i.kinds, i.lexicons])).toEqual([
@@ -160,9 +165,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" },
-      { id: "delivery/loom-backend", name: "loom-backend", member: "delivery", archetype: "service", composites: null, file: "delivery/src/loom-backend.component.ts" },
-      { id: "jobs/queue-runner", name: "queue-runner", member: "jobs", archetype: null, composites: ["WorkQueue", "CacheCluster"], file: "jobs/src/queue-runner.component.ts" },
+      { 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")] },
     ]);
     const rows = Object.fromEntries(g.composites.map((c) => [c.id, c]));
     expect(Object.keys(rows)).toEqual(["app/backend", "app/cache", "app/site", "jobs/queue"]);
@@ -242,3 +247,88 @@ describe("why the list is empty", () => {
     expect("error" in doc && doc.error.code).toBe("declaration-missing");
   });
 });
+
+/** A lexicon module: a LexiconPlugin export, with `opRuntime` when `runtime` says what it hosts. */
+function lexiconModule(name: string, runtime: "components" | "ops" | "none"): string {
+  const opRuntime =
+    runtime === "none"
+      ? ""
+      : `opRuntime: { name: ${JSON.stringify(name)}, start: async () => { throw new Error("stub"); }${runtime === "components" ? ", runComponents: async () => ({ success: true })" : ""} },`;
+  return `const noop = async () => {};
+export const plugin = { name: ${JSON.stringify(name)}, serializer: {}, generate: noop, validate: noop, coverage: noop, package: noop, ${opRuntime} };
+`;
+}
+
+describe("the runtimes each component can deploy on (#2674)", () => {
+  /** delivery configures four lexicons: one hosts component runs, one hosts only Op runs, one hosts nothing, one can't load. */
+  function hosting(): string {
+    const root = fixture();
+    writeFileSync(
+      join(root, "delivery", "chant.config.ts"),
+      `export default {
+  lexicons: [
+    { name: "fleet", module: "./lexicons/fleet.ts" },
+    { name: "oponly", module: "./lexicons/oponly.ts" },
+    { name: "plain", module: "./lexicons/plain.ts" },
+    { name: "gone", module: "./lexicons/gone.ts" },
+  ],
+};
+`,
+    );
+    mkdirSync(join(root, "delivery", "lexicons"));
+    writeFileSync(join(root, "delivery", "lexicons", "fleet.ts"), lexiconModule("fleet", "components"));
+    writeFileSync(join(root, "delivery", "lexicons", "oponly.ts"), lexiconModule("oponly", "ops"));
+    writeFileSync(join(root, "delivery", "lexicons", "plain.ts"), lexiconModule("plain", "none"));
+    return root;
+  }
+
+  test("local is the default, and a configured lexicon whose opRuntime hosts component runs is listed with its --on line", async () => {
+    const g = result((await workspaceComposites({ cwd: hosting() })).doc);
+    expectValid(g);
+    const edge = g.components.find((c) => c.id === "delivery/edge")!;
+    expect(edge.runtimes).toEqual([
+      { name: "local", lexicon: null, default: true, command: "chant run --components edge" },
+      { name: "fleet", lexicon: "fleet", default: false, command: "chant run --components edge --on fleet" },
+    ]);
+    expect(g.components.find((c) => c.id === "delivery/loom-backend")!.runtimes.map((r) => r.command)).toEqual([
+      "chant run --components loom-backend",
+      "chant run --components loom-backend --on fleet",
+    ]);
+    // jobs configures no lexicon, so only local.
+    expect(g.components.find((c) => c.id === "jobs/queue-runner")!.runtimes).toEqual([local("queue-runner")]);
+    const delivery = g.members.find((m) => m.name === "delivery")!;
+    expect(delivery.runtimeReasons.map((r) => r.code)).toEqual(["runtimes-lexicon-unreadable"]);
+    expect(delivery.runtimeReasons[0].message).toContain('lexicon "gone"');
+    expect(g.members.find((m) => m.name === "docs")!.runtimeReasons).toEqual([]);
+  });
+
+  test("a member whose config can't be read lists local only, with a reason", async () => {
+    const root = fixture();
+    writeFileSync(join(root, "jobs", "chant.config.ts"), 'throw new Error("no config here");\nexport default {};\n');
+    const { doc, failed } = await workspaceComposites({ cwd: root, loadPlugin: async () => { throw new Error("not called"); } });
+    const g = result(doc);
+    expectValid(g);
+    expect(failed).toBe(false);
+    const jobs = g.members.find((m) => m.name === "jobs")!;
+    expect(jobs.runtimeReasons).toEqual([{ code: "runtimes-config-unreadable", message: expect.stringContaining("no config here") }]);
+    expect(g.components.find((c) => c.id === "jobs/queue-runner")!.runtimes).toEqual([local("queue-runner")]);
+  });
+
+  test("the plugin loader decides from opRuntime.runComponents alone", async () => {
+    const root = fixture();
+    writeFileSync(join(root, "jobs", "chant.config.ts"), 'export default { lexicons: ["hosted", "bare"] };\n');
+    const g = result(
+      (
+        await workspaceComposites({
+          cwd: root,
+          loadPlugin: async (name) => (name === "hosted" ? { opRuntime: { runComponents: () => undefined } } : {}),
+        })
+      ).doc,
+    );
+    expectValid(g);
+    expect(g.components.find((c) => c.id === "jobs/queue-runner")!.runtimes.map((r) => [r.name, r.lexicon, r.default])).toEqual([
+      ["local", null, true],
+      ["hosted", "hosted", false],
+    ]);
+  });
+});