@intentius/chant 0.102.0 → 0.104.1

package/src/cli/mcp/workspace-tools.ts

@@ -15,8 +15,9 @@
  *   read to the workspace root's pinned chant included (ws-021), and keeps
  *   anything a command prints away from the protocol on stdout.
  * - The writes (`records-new`, `records-amend`, `records-review`,
- *   `records-close`, `points-answer`) call the functions `chant workspace
- *   records new|amend|review|close` and `points answer` call, and return the
+ *   `records-close`, `points-answer`, `points-retract`) call the functions
+ *   `chant workspace records new|amend|review|close` and `points
+ *   answer|retract` call, and return the
  *   same JSON result. They keep every rule
  *   the CLI keeps: the kind's schema, a closed record never changing, an
  *   approved one changing only as its approval rule allows, a dissent needing
@@ -112,6 +113,7 @@ export const workspaceReadTools: ToolDefinition[] = [
           description: "Record kind files whose records join the graph (--kind). The plain graph takes one; intent takes several.",
         },
         intent: { type: "string", description: "The region for the intent graph: a workspace path, path:line, path:start-end, or path#symbol for a TypeScript or JavaScript declaration such as src/server.ts#createApp (--intent). The document's why answers why the region is like this." },
+        followSquash: { type: "boolean", description: "With intent: follow squash merges to their pull requests' original commits (--follow-squash, #3035), fetching a pull request ref the clone lacks from origin. Off by default, so a read never reaches the network." },
         composites: { type: "boolean", description: "The composites document instead (--composites). Takes no kind or intent." },
         at: atProp,
       },
@@ -204,6 +206,7 @@ export const workspaceReadTools: ToolDefinition[] = [
         decision: { type: "string", description: "Only the runs that carried out this decision, by id or <kind>/<id> (--decision)." },
         by: { type: "string", description: "Only the runs made for this principal (--by)." },
         since: { type: "string", description: "Only the runs that made a commit after this revision, or started after it (--since)." },
+        followSquash: { type: "boolean", description: "Join each squash merge on HEAD to the runs its pull request's original commits joined (--follow-squash, #3035), fetching a pull request ref the clone lacks from origin." },
       },
     },
   },
@@ -286,7 +289,7 @@ export const workspaceWriteTools: ToolDefinition[] = [
   {
     name: "points-answer",
     description:
-      "Record people's answer to an open decision point question, or confirm a model's proposal: chant workspace points answer. Refused unless the point's quorum is met: distinct people, none holding the agent role, each holding one of the quorum's roles when it names any. An answered question never changes. " +
+      "Record people's answer to an open decision point question, or confirm a model's proposal: chant workspace points answer. Refused unless the point's quorum is met: distinct people, none holding the agent role, each holding one of the quorum's roles when it names any. An answered question never changes in place: points-retract takes it back. " +
       PROTOCOL,
     inputSchema: {
       type: "object",
@@ -294,12 +297,31 @@ export const workspaceWriteTools: ToolDefinition[] = [
         id: { type: "string", description: "The question's id, as workspace-points lists it." },
         answer: { type: ["string", "boolean"], description: "One of the question's candidates; for a noul, true or false." },
         by: { type: "array", items: { type: "string" }, description: "Each person who answered (--by)." },
+        note: { type: "string", description: "What the people who answered say with it, kept on the answer (--note)." },
+        relayedBy: { type: "string", description: "Who relayed the answer for the people in by, such as a follower; recorded as relayed_by and not counted toward the quorum (--relayed-by)." },
         kind: { type: "string", description: "The answer kind file. Without it, the declared answer kinds." },
         dryRun: dryRunProp,
       },
       required: ["id", "answer", "by"],
     },
   },
+  {
+    name: "points-retract",
+    description:
+      "Take back people's answer to a decision point question: chant workspace points retract. The question is escalated to people again, and the answer, who gave it and its note stay in the record's retractions with who retracted it, when and why. Refused unless the point's quorum is met, counted as for an answer. " +
+      PROTOCOL,
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "string", description: "The question's id, as workspace-points lists it." },
+        by: { type: "array", items: { type: "string" }, description: "Each person who takes the answer back (--by)." },
+        note: { type: "string", description: "Why, kept on the retraction (--note)." },
+        kind: { type: "string", description: "The answer kind file. Without it, the declared answer kinds." },
+        dryRun: dryRunProp,
+      },
+      required: ["id", "by"],
+    },
+  },
 ];
 
 /** A tool call that can't be made as given: the client gets it as an error result, and nothing runs. */
@@ -355,7 +377,7 @@ export function readArgv(tool: string, params: Record<string, unknown>): string[
       const composites = bool(params, "composites");
       const kindArgs = kinds(params).flatMap((k) => ["--kind", k]);
       if (composites) return ["workspace", "graph", "--composites", ...kindArgs, ...(intent !== undefined ? ["--intent", intent] : []), ...atArgs, "--json"];
-      if (intent !== undefined) return ["workspace", "graph", "--intent", intent, ...kindArgs, ...atArgs, "--json"];
+      if (intent !== undefined) return ["workspace", "graph", "--intent", intent, ...kindArgs, ...atArgs, ...(bool(params, "followSquash") ? ["--follow-squash"] : []), "--json"];
       return ["workspace", "graph", ...kindArgs, ...atArgs, "--json"];
     }
     case "workspace-changes": {
@@ -388,7 +410,7 @@ export function readArgv(tool: string, params: Record<string, unknown>): string[
         const v = str(params, f);
         return v !== undefined ? [`--${f}`, v] : [];
       });
-      return ["workspace", "runs", ...flags, "--json"];
+      return ["workspace", "runs", ...flags, ...(bool(params, "followSquash") ? ["--follow-squash"] : []), "--json"];
     }
     case "workspace-points": {
       const kind = str(params, "kind");
@@ -547,7 +569,13 @@ export function createWorkspaceTools(options: WorkspaceToolsOptions): WorkspaceT
       if (typeof answer !== "string" && typeof answer !== "boolean") throw new ToolInputError("answer must be a string, or true or false");
       const by = params.by;
       if (!Array.isArray(by) || by.length === 0 || !by.every((b) => typeof b === "string" && b.trim() !== "")) throw new ToolInputError("by must list each person who answered");
-      return answerPoint({ cwd, id: str(params, "id", true)!, answer, by: by as string[], kind: str(params, "kind"), dryRun: bool(params, "dryRun") });
+      return answerPoint({ cwd, id: str(params, "id", true)!, answer, by: by as string[], note: str(params, "note"), relayedBy: str(params, "relayedBy"), kind: str(params, "kind"), dryRun: bool(params, "dryRun") });
+    },
+    "points-retract": async (params) => {
+      const { retractAnswer } = await import("../../workspace/decide");
+      const by = params.by;
+      if (!Array.isArray(by) || by.length === 0 || !by.every((b) => typeof b === "string" && b.trim() !== "")) throw new ToolInputError("by must list each person who takes the answer back");
+      return retractAnswer({ cwd, id: str(params, "id", true)!, by: by as string[], note: str(params, "note"), kind: str(params, "kind"), dryRun: bool(params, "dryRun") });
     },
     "records-close": async (params) => {
       const w = await write();

package/src/cli/registry.ts

@@ -9,6 +9,8 @@ export interface ParsedArgs {
   path: string;
   extraPositional?: string;
   extraPositional2?: string;
+  /** Every positional after the command word, in order (#3308): for a command with more than three, such as `workspace box listing set <member>`. */
+  positionals?: string[];
   output?: string;
   format: string;
   force?: boolean;
@@ -238,6 +240,42 @@ export interface ParsedArgs {
    * ungated. A component's own authored gates are unaffected either way.
    */
   gate?: string;
+  /**
+   * `chant components fan-out --wave-gate <name>` (#3049) — one gate per wave
+   * instead of one over the set. Wave `n` waits on `<name>-wave-<n>`, bound to
+   * that wave's set digest, and is planned only once the waves before it
+   * applied. Also `chant build --components --generate <lexicon> --wave-gate
+   * <name>`, which generates one CI job per wave.
+   */
+  waveGate?: string;
+  /** `chant components fan-out --wave <n>` (#3049) — run wave `n` of a `--wave-gate` fan-out and no other. */
+  wave?: number;
+  /** `chant components fan-out --canary <component>` (#3049), repeatable — components that form wave 1. */
+  canary?: string[];
+  /**
+   * `chant components pr-plan|pr-apply --pr <n>` (#3183) — the pull or merge
+   * request the plan belongs to. Its gate is recorded under op `pr-<n>`.
+   * pr-apply finds it from the commit through `--forge` when omitted.
+   */
+  pr?: number;
+  /**
+   * `chant components pr-plan|pr-apply --forge github|gitlab|forgejo` (#3183)
+   * — post the note and the commit status on this forge, with the client
+   * read from the CI job's environment.
+   */
+  forge?: string;
+  /**
+   * `chant components pr-apply --require-review` (#3183) — count an approval
+   * only when its approver has a standing approving review on the pull
+   * request. Needs `--forge`.
+   */
+  requireReview?: boolean;
+  /**
+   * `chant build --components --generate <lexicon> --pr-loop` (#3183) —
+   * generate the pull-request pipeline: plan on the pull request, apply on
+   * merge bound to the approved digest.
+   */
+  prLoop?: boolean;
   /**
    * `chant components fan-out --resume <file>` (#2420) — the attempt record
    * this fan-out reads before it starts and writes when it finishes. Repeating
@@ -303,8 +341,10 @@ export interface ParsedArgs {
   bys?: string[];
   /** `chant workspace points --open` (#2739): only the questions still open. */
   open?: boolean;
-  /** `chant workspace points ask <point> --inputs <file|->` (#2739): the inputs, as a JSON object. */
+  /** `chant workspace points ask <point> --inputs <file|-|json>` (#2739): the inputs, as a JSON object. */
   inputs?: string;
+  /** `chant workspace points ask <point> --candidates <file|-|json>` (#3403): an ad-hoc point's question and candidates. */
+  candidates?: string;
   /** `chant workspace points ask <point> --response <file>` (#2739): a POST /v1/systemone response the caller got from a backend. */
   response?: string;
   /** `chant workspace points ask <point> --subject <id>` (#2739): what the question is about. */
@@ -317,6 +357,8 @@ export interface ParsedArgs {
   composites?: boolean;
   /** `chant workspace graph --intent <path[:start-end]|path#symbol>` (#2651): the region the intent graph is over. Empty with `--record`. */
   intent?: string;
+  /** `chant workspace graph --intent` and `chant workspace runs` (#3035): follow squash merges to their pull requests' original commits, fetching missing pull request refs. */
+  followSquash?: boolean;
   /** `chant workspace graph --intent --record <id>`: walk one decision record over every entry its constrains lists. */
   record?: string;
   /** `chant workspace patch <range> --path <p>`: only these paths, from the workspace root. Repeatable. */
@@ -335,8 +377,20 @@ export interface ParsedArgs {
   uncommitted?: boolean;
   /** `chant workspace records amend <id> --set <file|->` (#2670): the JSON fields to set. */
   set?: string;
+  /** `chant workspace records amend|review|close <id> --expect <digest>` (#3173): the record's digest the caller last read; the write is refused with record-conflict when it has moved on. */
+  expect?: string;
   /** `chant workspace records review <id> --verdict <v>` (#2670): agree, dissent or abstain. */
   verdict?: string;
+  /** `chant workspace box listing set <member> --cover <image>` (#3308): a PNG, JPEG or WebP picture to copy in as the box's cover. */
+  cover?: string;
+  /** `chant workspace box listing set <member> --cover <image> --cover-path <path>` (#3308): where the cover goes, from the workspace root. */
+  coverPath?: string;
+  /** `chant workspace box publish <member> --records` (#3165): publish the records kept uncommitted instead of a work item. */
+  records?: boolean;
+  /** `chant workspace wip save --label <text>` (#3172): what the caller calls the snapshot, such as a turn id. */
+  label?: string;
+  /** `chant workspace wip --branch <branch>` (#3172): list one branch's snapshots. */
+  branch?: string;
   /**
    * `chant workspace records review <id> --by <principal>` (#2670): the
    * reviewer, as the caller names them. Also `chant workspace records new
@@ -351,6 +405,12 @@ export interface ParsedArgs {
    * On `chant approve` and `chant run approve`, the key that seals the gate approval (#3163).
    */
   sign?: string | true;
+  /**
+   * `chant approve <op> <gate> --relayed-by <principal>` and `chant workspace
+   * points answer <id> --relayed-by <principal>` (#3402): the principal that
+   * carried the approval or answer to chant on behalf of the person it names.
+   */
+  relayedBy?: 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. */
@@ -365,6 +425,8 @@ export interface ParsedArgs {
   claim?: string;
   /** `chant workspace evidence sign --environment <file>` (#2553): the runner environment, hashed into the evidence. */
   environment?: string;
+  /** `chant workspace runs statement <id> --signer <principal>` (#3192): the runner principal that will sign. */
+  signer?: string;
   /** `chant workspace evidence verify --envelope <file>` (#2553). */
   envelope?: string;
   /** `chant workspace signers rotate --threshold <n>` (#2553). */

package/src/components/auto-release.ts

@@ -41,7 +41,7 @@ import type { DriverStepRecord } from "./driver";
  * driver's own `collectComponentOutputs` stays looser (uri/digest/key) because it
  * only feeds `@<component>.publish.*` wiring, where a false positive is harmless.
  */
-function isPromotedArtifact(output: unknown): output is { uri: string; digest?: string } {
+export function isPromotedArtifact(output: unknown): output is { uri: string; digest?: string } {
   return !!output && typeof output === "object" && "uri" in output && typeof (output as { uri?: unknown }).uri === "string";
 }
 

package/src/components/capability.ts

@@ -12,6 +12,9 @@
  * Cloud implementations are a later phase (see epic #551, issue #554).
  */
 
+import type { ReleaseIdentity } from "../telemetry-attribution";
+import type { ChangeSetPart } from "../change-set";
+
 /**
  * Ambient information a capability's `run`/`rollback` receives, independent of
  * its typed `input`. Deliberately minimal for this phase: the orchestrator
@@ -27,6 +30,42 @@ export interface DeployContext {
   component: string;
   /** Arbitrary environment config resolved by the orchestrator (registry URLs, cluster names, ...). */
   vars?: Record<string, unknown>;
+  /**
+   * The release this run deploys (#3061, ws-081): the commit, set by the
+   * caller, and the digest of the artifact a publish step has promoted so
+   * far in this component's run, set by the driver. A deploy step passes it
+   * to the workload with `releaseEnvironment()`. Absent outside
+   * `chant run --components`.
+   */
+  release?: ReleaseIdentity;
+  /**
+   * What this component's steps planned before its wave's gate was decided
+   * (#3049), keyed by {@link CapabilityPlan.member}. Set by a gated-wave
+   * fan-out and by a pull request's apply (#3183). A capability whose `run`
+   * finds its own member here applies that plan, the one the approver
+   * approved, instead of planning again.
+   */
+  plans?: Record<string, unknown>;
+}
+
+/**
+ * What a capability's `plan` produced (#3049): the member it planned, that
+ * plan's digest, and whatever `run` needs to apply exactly that plan.
+ */
+export interface CapabilityPlan {
+  /** The member's name in a wave's set digest. For a terraform-family step, the root. */
+  member: string;
+  /** The digest a gate on this member alone would bind (#2300). */
+  planDigest: string;
+  /** Handed back to `run` as `DeployContext.plans[member]`. Opaque to the runner. */
+  artifact?: unknown;
+  /**
+   * The member's part of a change-set document (#3181): every change the
+   * plan proposes. A pull request's plan (#3183) composes the parts into the
+   * document whose grouped summary the PR note shows. Without it the member
+   * still counts toward the digest, with no entries.
+   */
+  changeSet?: ChangeSetPart;
 }
 
 /**
@@ -61,6 +100,22 @@ export interface Capability<In = unknown, Out = unknown> {
    * never needs it (most of them) simply ignores the third parameter.
    */
   rollback?(ctx: DeployContext, input: In, output?: Out): Promise<void>;
+  /**
+   * Optional: say what `run` would change, without changing it (#3049). A
+   * gated-wave fan-out calls this for every step of every component in a
+   * wave, once the waves before it have applied, and binds the wave's gate
+   * to the set digest of the results. `run` then receives the result's
+   * `artifact` through `DeployContext.plans`. A capability without `plan`
+   * is covered by its component's composition digest instead.
+   */
+  plan?(ctx: DeployContext, input: In): Promise<CapabilityPlan>;
+  /**
+   * Optional: the outputs `run` exposed when it last ran, read without
+   * changing anything (#3183). A pull request's plan reads them for each
+   * component a planned one depends on, so a `stackOutput()` wiring resolves
+   * to the value standing now. The shape is `run`'s `outputs` field.
+   */
+  outputs?(ctx: DeployContext, input: In): Promise<Record<string, unknown>>;
   /**
    * How this verb relates to rollback, for the COMP003 composition check.
    * Usually derivable and left unset: a capability with a `rollback` method is

package/src/components/changed-files.ts

@@ -0,0 +1,66 @@
+/**
+ * The files a change touched, and the units lexicons own that those files
+ * belong to (#3183).
+ *
+ * `lifecycle affected` judges chant source by diffing what it builds. A unit
+ * that is not chant source, such as a hand-written Terraform root, never
+ * shows in that diff, so a lexicon that owns such units answers from the
+ * changed paths instead (`LexiconPlugin.changedUnits`).
+ */
+
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import type { LexiconPlugin } from "../lexicon";
+
+const execFileAsync = promisify(execFile);
+
+async function git(cwd: string, args: string[]): Promise<string> {
+  const { stdout } = await execFileAsync("git", args, { cwd, maxBuffer: 64 * 1024 * 1024 });
+  return stdout;
+}
+
+/**
+ * The commit a change is measured from: the merge base of `base` and `head`.
+ * A pull request's head that branched before `base` moved is measured from
+ * where it branched, so the other changes on `base` are not counted as its
+ * own; a merge commit's first parent is its own merge base.
+ */
+export async function resolveMergeBase(cwd: string, base: string, head = "HEAD"): Promise<string> {
+  try {
+    return (await git(cwd, ["merge-base", base, head])).trim();
+  } catch (err) {
+    const detail = (err as { stderr?: string }).stderr?.trim();
+    throw new Error(
+      `cannot find where ${head} and ${base} meet${detail ? `: ${detail}` : ""}. ` +
+        "Is the base fetched? A CI checkout needs the history (fetch-depth: 0, GIT_DEPTH: 0).",
+    );
+  }
+}
+
+/** The full commit `ref` names. */
+export async function resolveCommit(cwd: string, ref: string): Promise<string> {
+  return (await git(cwd, ["rev-parse", "--verify", `${ref}^{commit}`])).trim();
+}
+
+/**
+ * Files changed between `base` and `head`, relative to `cwd` and limited to
+ * it, with `/` separators. A rename counts as its old and its new path.
+ */
+export async function changedFilesBetween(cwd: string, base: string, head = "HEAD"): Promise<string[]> {
+  const out = await git(cwd, ["diff", "--name-only", "-z", "--no-renames", "--relative", base, head]);
+  return out.split("\0").filter(Boolean).sort();
+}
+
+/** The union of every plugin's `changedUnits` answer, sorted. */
+export async function lexiconChangedUnits(
+  plugins: readonly Pick<LexiconPlugin, "changedUnits">[],
+  ctx: { projectRoot: string; config: Record<string, unknown>; changedFiles: string[] },
+): Promise<string[]> {
+  if (ctx.changedFiles.length === 0) return [];
+  const units = new Set<string>();
+  for (const plugin of plugins) {
+    if (!plugin.changedUnits) continue;
+    for (const unit of await plugin.changedUnits(ctx)) units.add(unit);
+  }
+  return [...units].sort();
+}

package/src/components/cli-support.ts

@@ -22,11 +22,13 @@
  *    executor, the CLI entrypoint the driver (#556) never had.
  */
 
+import { UnknownCanaryError } from "../gated-waves";
 import { lexiconModulePath, lexiconNames, importLexiconPackage } from "../lexicon-module";
 import { discoverComponents } from "./discover";
 import type { BuildParamProvenance } from "../provenance";
-import { inferArchetype, projectToJson, type Archetype } from "./component";
+import { inferArchetype, projectToJson, type Archetype, type ComponentEnvironmentDeclaration } from "./component";
 import {
+  deployContext,
   resolveComponentGraph,
   runInterpretDriver,
   runComponentDeploy,
@@ -43,7 +45,9 @@ import type { GateDigestMismatch, GateLedgerPort } from "../op/gate";
 import { gateName } from "../op/gate-name";
 import { isLexiconPlugin, type LexiconPlugin, type ComponentPipelineOptions } from "../lexicon";
 import type { RunProgressEvent } from "./run-progress";
-import { relative } from "node:path";
+import { dirname, relative } from "node:path";
+import { existsSync, statSync } from "node:fs";
+import { getHeadCommit } from "../lifecycle/git";
 import { buildCapabilityRegistry } from "./capability-plugin-loader";
 import type { CapabilityRegistry } from "./capability";
 import { applyConfigDefaults } from "./config-defaults";
@@ -156,6 +160,8 @@ export interface ComponentGraphResult {
    * (`inferArchetype`), so a reader can label a component without its source
    * (#2662). */
   archetypes?: Record<string, Archetype>;
+  /** Component name → the environments it declares (#3153), present only for components that declared them. */
+  environments?: Record<string, ComponentEnvironmentDeclaration[]>;
   error?: string;
 }
 
@@ -192,7 +198,10 @@ export async function computeComponentGraph(
   // that declared them — no identity fallback (see ComponentGraphResult doc).
   const composites: Record<string, string[]> = {};
   const archetypes: Record<string, Archetype> = {};
+  const environments: Record<string, ComponentEnvironmentDeclaration[]> = {};
   for (const [name, discovered] of result.components) {
+    const declaredEnvironments = discovered.component.environments;
+    if (declaredEnvironments && declaredEnvironments.length > 0) environments[name] = declaredEnvironments.map((e) => ({ ...e }));
     archetypes[name] = discovered.component.archetype ?? inferArchetype(discovered.component);
     files[name] = relative(path, discovered.filePath);
     const declared = discovered.component.liveNames;
@@ -207,7 +216,7 @@ export async function computeComponentGraph(
     for (const c of driverComponents) {
       for (const dep of c.dependsOn ?? []) edges.push({ from: c.name, to: dep });
     }
-    return { success: true, order, waves, edges, files, liveNames, composites, archetypes };
+    return { success: true, order, waves, edges, files, liveNames, composites, archetypes, environments };
   } catch (err) {
     if (err instanceof UnknownDependencyError || err instanceof DependencyCycleError) {
       return { success: false, order: [], waves: [], edges: [], error: err.message };
@@ -302,7 +311,7 @@ export async function generateComponentsPipeline(
     const { yaml, stages, jobs, env } = plugin.generateComponentPipeline(driverComponents, options);
     return { success: true, yaml, stages, jobs, ...(env ? { env } : {}), buildParams };
   } catch (err) {
-    if (err instanceof UnknownDependencyError || err instanceof DependencyCycleError) {
+    if (err instanceof UnknownDependencyError || err instanceof DependencyCycleError || err instanceof UnknownCanaryError) {
       return { success: false, error: err.message };
     }
     throw err;
@@ -421,6 +430,12 @@ export interface RunComponentsOptions {
   buildParams?: BuildParamProvenance[];
   /** Where a `gate` step's facts are read and written (#2119). Defaults to the `chant/lifecycle` orphan branch; a test passes `memoryGateLedgerPort()` from `../op/gate.ts`. */
   gates?: GateLedgerPort;
+  /**
+   * The commit the run deploys, for the workloads' `vcs.ref.head.revision`
+   * (#3061). Default: `git rev-parse HEAD` in the project, or nothing outside
+   * a checkout. `null` passes none.
+   */
+  revision?: string | null;
 }
 
 /** Result of `chant run --components <name|all>`. */
@@ -571,11 +586,19 @@ export async function runComponents(
   const { onProgress } = options;
 
   const gates = options.gates;
+  // #3061: the commit this run deploys, for the workloads' vcs.ref.head.revision. The digest comes
+  // from the run's own publish step. Best effort: outside a git checkout nothing is passed.
+  const revision =
+    options.revision !== undefined
+      ? options.revision ?? undefined
+      : await getHeadCommit({ cwd: existsSync(path) && statSync(path).isDirectory() ? path : dirname(path) }).catch(() => undefined);
+  const releaseIdentity = () => (revision ? { revision } : {});
 
   try {
     if (selector === "all") {
       const run = await runInterpretDriver(resolvedTargets, registry, {
         env,
+        releaseIdentity,
         componentOutputs: seedOutputs,
         onProgress,
         ...(gates ? { gates } : {}),
@@ -618,7 +641,7 @@ export async function runComponents(
     onProgress?.({ type: "component-start", wave: 1, component: componentName });
     const componentResult = await runComponentDeploy(
       resolvedTargets[0],
-      { env, component: componentName },
+      deployContext({ env, releaseIdentity }, componentName),
       registry,
       componentOutputs,
       onProgress,

package/src/components/component.schema.json

@@ -60,6 +60,23 @@
       "description": "Optional: the composite kind name(s) this component's deployed resources come from, when a consumer cannot infer it from `name` (#1492). Without this, a consumer joining a composite graph to the component DAG guesses by kebab-casing each composite's kind and matching it against this component's `name`, which only holds when a component maps 1:1 to a composite named for it. Omitted entirely (the default), the naming convention stays in effect with no behavior change. A component built from several composites may list them all.",
       "items": { "type": "string", "minLength": 1 },
       "minItems": 1
+    },
+    "environments": {
+      "type": "array",
+      "description": "Optional: where a release of this component goes, by environment (#3153). Each names an environment --env takes and, for it, the runtime that hosts the release, the URL it answers on, a custom domain attached to it, and the git remote its lifecycle records are pushed to. chant workspace graph --composites lists them first among the component's environments, with source component. Omitted, the component's environments are its member's.",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["name"],
+        "additionalProperties": false,
+        "properties": {
+          "name": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,62}$", "description": "The environment's name, as --env takes it." },
+          "runtime": { "type": "string", "minLength": 1, "description": "The runtime that hosts a release here, such as local or fly." },
+          "url": { "type": "string", "pattern": "^https?://", "description": "Where the released component answers." },
+          "domain": { "type": "string", "minLength": 1, "description": "A custom domain the release attaches to it." },
+          "lifecycle": { "type": "string", "minLength": 1, "description": "The git remote this environment's approvals, effect receipts and ledger records are pushed to." }
+        }
+      }
     }
   },
   "$defs": {

package/src/components/component.ts

@@ -183,6 +183,31 @@ export interface Component {
    * default and nothing changes.
    */
   composites?: string[];
+  /**
+   * Optional: where a release of this component goes, by environment
+   * (#3153, ws-095). Each names an environment `--env` takes and, for that
+   * environment, the runtime that hosts the release, the URL its health
+   * answers on, a custom domain attached to it, and the git remote its
+   * approvals, effect receipts and ledger records are pushed to. `chant
+   * workspace graph --composites` lists them first among the component's
+   * environments, with source `component`. Omitted, the component's
+   * environments are its member's, as before.
+   */
+  environments?: ComponentEnvironmentDeclaration[];
+}
+
+/** One environment a component declares it deploys to (#3153). */
+export interface ComponentEnvironmentDeclaration {
+  /** The environment's name, as `--env` takes it. */
+  name: string;
+  /** The runtime that hosts a release here, such as `local` or a lexicon's runtime (`fly`). */
+  runtime?: string;
+  /** Where the released component answers, such as its health endpoint's origin. */
+  url?: string;
+  /** A custom domain the release attaches to it. */
+  domain?: string;
+  /** The git remote this environment's approvals, effect receipts and ledger records are pushed to. */
+  lifecycle?: string;
 }
 
 /** Author a named phase. `steps` may mix capability `Step`s, `Gate`s, and nested `Phase`s (fan-out). */

package/src/components/deploy-units.ts

@@ -56,6 +56,9 @@ export const DEPLOY_UNIT_RULES: readonly DeployUnitRule[] = [
   { kind: "argo-app", field: "stack", lexicon: "k8s" },
   { kind: "flux-reconcile", field: "stack", lexicon: "k8s" },
   { kind: "helm-upgrade", field: "release", lexicon: "helm" },
+  // A Terraform-family root (#3049). Its unit is the root's name in
+  // `terraform.roots`, which is also the member a gated wave's digest names.
+  { kind: "terraform-apply", field: "root", lexicon: "terraform" },
 ];
 
 /** One resolved unit a component's deploy composition targets. */

package/src/components/driver.test.ts

@@ -1069,3 +1069,55 @@ describe("capabilities are consumed exactly as the registry provides them", () =
     expect(failed?.error).toMatch(/capability "some-future-verb" is not implemented/);
   });
 });
+
+describe("the release a deploy step sees (#3061, ws-081)", () => {
+  function setup() {
+    const registry = new CapabilityRegistry();
+    registry.register(fakeCapability("publish-image", { run: () => ({ uri: "ghcr.io/acme/api@sha256:abc", digest: "sha256:abc" }) }).capability);
+    registry.register(fakeCapability("generate-sbom", { run: () => ({ digest: "sha256:sbom" }) }).capability);
+    const deploy = fakeCapability("deploy");
+    registry.register(deploy.capability);
+    return { registry, deploy };
+  }
+
+  it("carries the caller's revision and the digest a publish step promoted, not an SBOM's", async () => {
+    const { registry, deploy } = setup();
+    const api: DriverComponent = {
+      name: "api",
+      dependsOn: [],
+      deploy: [
+        { phase: "Publish", steps: [{ kind: "publish-image" }, { kind: "generate-sbom" }] },
+        { phase: "Deploy", steps: [{ kind: "deploy" }] },
+      ],
+    };
+    const result = await runInterpretDriver([api], registry, { env: "prod", releaseIdentity: () => ({ revision: "0123abc" }) });
+    expect(result.ok).toBe(true);
+    expect(deploy.calls[0]!.ctx.release).toEqual({ revision: "0123abc", version: "sha256:abc" });
+  });
+
+  it("keeps each component's release its own, and passes none without releaseIdentity", async () => {
+    const { registry, deploy } = setup();
+    const api: DriverComponent = { name: "api", dependsOn: [], deploy: [{ phase: "P", steps: [{ kind: "publish-image" }, { kind: "deploy" }] }] };
+    const worker: DriverComponent = { name: "worker", dependsOn: ["api"], deploy: [{ phase: "D", steps: [{ kind: "deploy" }] }] };
+    await runInterpretDriver([api, worker], registry, { env: "prod", releaseIdentity: () => ({ revision: "r1" }) });
+    expect(deploy.calls.map((c) => [c.ctx.component, c.ctx.release])).toEqual([
+      ["api", { revision: "r1", version: "sha256:abc" }],
+      ["worker", { revision: "r1" }],
+    ]);
+    const plain = setup();
+    await runInterpretDriver([{ ...worker, dependsOn: [] }], plain.registry, { env: "prod" });
+    expect(plain.deploy.calls[0]!.ctx.release).toBeUndefined();
+  });
+
+  it("a promote's recorded digest is the version when no step publishes one", async () => {
+    const { registry, deploy } = setup();
+    const api: DriverComponent = { name: "api", dependsOn: [], deploy: [{ phase: "D", steps: [{ kind: "deploy" }] }] };
+    await runInterpretDriver([api], registry, {
+      env: "prod",
+      gates: memoryGateLedgerPort(),
+      releases: new Map([["api", "sha256:recorded"]]),
+      releaseIdentity: () => ({ revision: "r0" }),
+    });
+    expect(deploy.calls[0]!.ctx.release).toEqual({ revision: "r0", version: "sha256:recorded" });
+  });
+});