@intentius/chant 0.57.0 → 0.59.0

package/src/components/auto-release.test.ts

@@ -22,7 +22,6 @@ vi.mock("../lifecycle/release-ledger", async () => {
 const {
   maybeRecordAutoRelease,
   extractRunDigest,
-  extractRunDigestFromPhaseOutputs,
 } = await import("./auto-release");
 
 function publishRecord(digest: string): DriverStepRecord {
@@ -64,21 +63,6 @@ describe("extractRunDigest", () => {
   });
 });
 
-describe("extractRunDigestFromPhaseOutputs", () => {
-  test("finds the digest across phase outputs (Temporal workflow result shape)", () => {
-    expect(extractRunDigestFromPhaseOutputs({ Publish: { digest: "sha256:abc", uri: "repo@sha256:abc" }, Apply: { ok: true } })).toBe("sha256:abc");
-  });
-
-  test("returns undefined for undefined/empty phaseOutputs", () => {
-    expect(extractRunDigestFromPhaseOutputs(undefined)).toBeUndefined();
-    expect(extractRunDigestFromPhaseOutputs({})).toBeUndefined();
-  });
-
-  test("ignores a phase output carrying only a content digest (SBOM, #665)", () => {
-    expect(extractRunDigestFromPhaseOutputs({ Sbom: { digest: "sha256:sbombytes" } })).toBeUndefined();
-  });
-});
-
 describe("maybeRecordAutoRelease", () => {
   beforeEach(() => {
     getHeadCommitMock.mockReset().mockResolvedValue("abc123headsha");
@@ -111,19 +95,19 @@ describe("maybeRecordAutoRelease", () => {
     expect(pushLifecycleMock).toHaveBeenCalledTimes(1);
   });
 
-  test("a pre-resolved digest (Temporal path) takes precedence and is used directly", async () => {
+  test("a pre-resolved digest takes precedence and is used directly", async () => {
     appendReleaseRecordMock.mockResolvedValue({
       commit: "b".repeat(40),
-      record: { version: 1, component: "svc", env: "prod", digest: "sha256:temporal", gitSha: "x", runId: "r", timestamp: "t", actor: "a" },
+      record: { version: 1, component: "svc", env: "prod", digest: "sha256:preresolved", gitSha: "x", runId: "r", timestamp: "t", actor: "a" },
     });
 
     await maybeRecordAutoRelease(
-      { component: "svc", env: "prod", success: true, digest: "sha256:temporal", records: [publishRecord("sha256:ignored")], runId: "run-1" },
+      { component: "svc", env: "prod", success: true, digest: "sha256:preresolved", records: [publishRecord("sha256:ignored")], runId: "run-1" },
       { actor: "alice" },
     );
 
     const [input] = appendReleaseRecordMock.mock.calls[0];
-    expect(input.digest).toBe("sha256:temporal");
+    expect(input.digest).toBe("sha256:preresolved");
   });
 
   test("failure (run.success = false) -> writes nothing", async () => {

package/src/components/auto-release.ts

@@ -4,23 +4,19 @@
  * release ledger (../lifecycle/release-ledger.ts) was only populated by the
  * standalone `chant components release <env>` command — a deploy that never
  * called it left the ledger silently empty. This module makes recording
- * happen *by construction*: the CLI post-run step for both the local
- * executor (`runOpComponents`) and the durable Temporal path
- * (`runComponentTemporal`) calls `maybeRecordAutoRelease` after the run
- * reports success.
+ * happen *by construction*: the CLI's post-run step (`runOpComponents`)
+ * calls `maybeRecordAutoRelease` after the run reports success.
  *
  * Deliberately CLI-side, not driver-side or workflow-side:
  *  - `../components/driver.ts` stays capability-agnostic — it already
  *    resists per-component/per-capability branching, and "write to git"
  *    is exactly the kind of side effect that doesn't belong in a step
  *    dispatcher tests exercise against a bare `CapabilityRegistry`.
- *  - The Temporal workflow (lexicons/temporal/src/component-op/) must stay
- *    deterministic and replay-safe. A ledger write is a non-idempotent git
- *    push with real-world side effects (network, `Date.now()`, file writes
- *    outside workflow state) — precisely what Temporal workflow code must
- *    never do directly. It happens in the CLI, after `handle.describe()`
- *    reports a terminal COMPLETED status, the same place `runOpTemporal`
- *    already writes its deployment report post-run.
+ *  - A ledger write is a non-idempotent git push with real-world side
+ *    effects (network, `Date.now()`, file writes) — the kind of thing that
+ *    belongs at the edge of a run rather than inside a step a retry may run
+ *    a second time. It happens in the CLI, once the run has reported a
+ *    terminal outcome.
  *
  * Reuses ../lifecycle/release-ledger.ts's `appendReleaseRecord` verbatim —
  * this module only decides *whether* to call it and *what digest* to record,
@@ -72,27 +68,6 @@ export function extractRunDigest(records: DriverStepRecord[]): string | undefine
   return found;
 }
 
-/**
- * Same digest extraction as `extractRunDigest`, but over a component
- * Temporal workflow's returned `phaseOutputs` (`{ [phase]: output }`) instead
- * of a `DriverStepRecord[]` — the shape `handle.result()` resolves to for a
- * COMPLETED component workflow (see lexicons/temporal/src/component-op/
- * serializer.ts's generated `return { phaseOutputs, componentOutputs }`).
- * Used by the `--temporal` CLI path, which never sees individual step
- * records (those exist only inside the workflow/activities).
- */
-export function extractRunDigestFromPhaseOutputs(
-  phaseOutputs: Record<string, Record<string, unknown>> | undefined,
-): string | undefined {
-  let found: string | undefined;
-  for (const output of Object.values(phaseOutputs ?? {})) {
-    if (isPromotedArtifact(output) && typeof output.digest === "string") {
-      found = output.digest;
-    }
-  }
-  return found;
-}
-
 /** Explicit reasons `maybeRecordAutoRelease` declined to write a record — never a thrown error, since "nothing to record" (or "opted out") is an expected, common outcome. */
 export type AutoReleaseSkipReason =
   | "opted-out"
@@ -105,19 +80,19 @@ export type AutoReleaseResult =
   | { recorded: false; reason: AutoReleaseSkipReason; detail?: string }
   | { recorded: false; reason: "error"; error: string };
 
-/** Input describing one component's completed run, common to both the local-executor and Temporal-durable CLI paths. */
+/** Input describing one component's completed run. */
 export interface AutoReleaseRunInfo {
   component: string;
   env: string;
-  /** Whether the run reported overall success — `DriverRunResult.ok` (local) or a terminal `COMPLETED` Temporal status. A caller must not call this for a non-terminal/in-progress run. */
+  /** Whether the run reported overall success (`DriverRunResult.ok`). A caller must not call this for a non-terminal/in-progress run. */
   success: boolean;
   /** The component's step records (local executor), used to locate the published digest via `extractRunDigest`. Mutually exclusive with `digest` — pass whichever the caller already has. */
   records?: DriverStepRecord[];
-  /** A digest already resolved by the caller (e.g. the `--temporal` path, via `extractRunDigestFromPhaseOutputs` over the workflow's `handle.result()`). Takes precedence over `records` when both are given. */
+  /** A digest the caller already resolved by its own means. Takes precedence over `records` when both are given. */
   digest?: string;
-  /** Orchestrator run identifier — a Temporal `runId`, or a locally generated id for the local executor (mirrors `runComponentsReleaseRecord`'s `--run-id` default). */
+  /** Orchestrator run identifier — a hosting runtime's own run id, or a locally generated one (mirrors `runComponentsReleaseRecord`'s `--run-id` default). */
   runId: string;
-  /** The id space `runId` lives in (#2045) — `{ forge: "op" }` for a Temporal run, `{ forge: "local" }` for a local-executor mint. Recorded verbatim as the release record's `runOrigin`. */
+  /** The id space `runId` lives in (#2045) — `{ forge: "op" }` for a hosted run, `{ forge: "local" }` for a local-executor mint. Recorded verbatim as the release record's `runOrigin`. */
   runOrigin?: RunOrigin;
   /** The bypassed capability-profile divergences, when the caller deliberately overrode a deploy-time profile assertion (chant #1244) — recorded verbatim as the release record's `profileOverride`. */
   profileOverride?: string;
@@ -142,11 +117,11 @@ function resolveActor(override?: string): string | undefined {
 }
 
 /**
- * After a successful `chant run --components <name> --env <env>` (local or
- * `--temporal`), append exactly one immutable release record to the ledger
- * and push it — or explain, without throwing, why it didn't. Never called
- * for a failed run (`run.success` must be true before the caller invokes
- * this at all; see `runOpComponents`/`runComponentTemporal`) — a failed
+ * After a successful `chant run --components <name> --env <env>`, append
+ * exactly one immutable release record to the ledger and push it — or
+ * explain, without throwing, why it didn't. Never called for a failed run
+ * (`run.success` must be true before the caller invokes this at all; see
+ * `runOpComponents`) — a failed
  * deploy writes nothing, by construction, since this function is simply
  * never reached on that path.
  *

package/src/components/capability.ts

@@ -50,10 +50,10 @@ export interface Capability<In = unknown, Out = unknown> {
    * returned (#1944, epic #1564 phase 4) — a serializable identity channel a
    * capability can use to recover state `rollback` needs when it cannot rely
    * on in-process object identity between its `run`/`rollback` calls. The
-   * local interpret driver (../driver.ts) always threads it through; the
-   * durable Temporal path (lexicons/temporal/src/component-op/*.ts) threads
-   * it across the Activity boundary as plain JSON, which is exactly the case
-   * this exists for — see ./verbs/run-agent.ts's "Rollback identity" doc
+   * local interpret driver (../driver.ts) always threads it through; a
+   * hosting runtime that splits a run across process boundaries threads it
+   * across as plain JSON, which is exactly the case this exists for — see
+   * ./verbs/run-agent.ts's "Rollback identity" doc
    * comment for the motivating gap (a fresh sprite's checkpoint id, recorded
    * only in an in-process `WeakMap` keyed by `run()`'s `input` object, never
    * survives to a `rollback()` call that runs as a separate Activity with its

package/src/components/cli-support.test.ts

@@ -25,6 +25,7 @@ import {
   generateComponentsPipeline,
 } from "./cli-support";
 import { CapabilityRegistry, type DeployContext } from "./capability";
+import { memoryGateLedgerPort } from "../op/gate";
 import type { DriverComponent, RunProgressEvent } from "./driver";
 
 // A minimal stand-in for the real gitlab lexicon plugin, satisfying
@@ -427,9 +428,9 @@ describe("findComponentGate", () => {
     const component: DriverComponent = {
       name: "svc",
       dependsOn: [],
-      deploy: [{ phase: "Approve", steps: [{ kind: "gate", signalName: "release-approval" }] }],
+      deploy: [{ phase: "Approve", steps: [{ kind: "gate", gate: "release-approval" }] }],
     };
-    expect(findComponentGate(component)).toEqual({ kind: "gate", signalName: "release-approval" });
+    expect(findComponentGate(component)).toEqual({ gate: "release-approval" });
   });
 
   test("finds a gate nested inside a fan-out phase", () => {
@@ -442,13 +443,13 @@ describe("findComponentGate", () => {
           steps: [
             {
               phase: "instance-2",
-              steps: [{ kind: "gate", signalName: "instance-2-approval" }],
+              steps: [{ kind: "gate", gate: "instance-2-approval" }],
             },
           ],
         },
       ],
     };
-    expect(findComponentGate(component)?.signalName).toBe("instance-2-approval");
+    expect(findComponentGate(component)?.gate).toBe("instance-2-approval");
   });
 
   test("finds a gate in a component's rollback phases", () => {
@@ -456,9 +457,20 @@ describe("findComponentGate", () => {
       name: "svc",
       dependsOn: [],
       deploy: [{ phase: "Apply", steps: [{ kind: "deploy-thing" }] }],
-      rollback: [{ phase: "Rollback", steps: [{ kind: "gate", signalName: "rollback-approval" }] }],
+      rollback: [{ phase: "Rollback", steps: [{ kind: "gate", gate: "rollback-approval" }] }],
+    };
+    expect(findComponentGate(component)?.gate).toBe("rollback-approval");
+  });
+
+  // #2202: the name comes back on `gate` whichever key the component spelled
+  // it with, so no caller has to know about the deprecated one.
+  test("normalizes a gate step's deprecated `signalName` key onto `gate`", () => {
+    const component = {
+      name: "svc",
+      dependsOn: [],
+      deploy: [{ phase: "Approve", steps: [{ kind: "gate", signalName: "release-approval" }] }],
     };
-    expect(findComponentGate(component)?.signalName).toBe("rollback-approval");
+    expect(findComponentGate(component)).toEqual({ gate: "release-approval" });
   });
 });
 
@@ -587,11 +599,11 @@ describe("runComponents", () => {
     expect(result.error).toContain("svc");
   });
 
-  test("a gate in the selected component is rejected before any step runs", async () => {
+  test("a gate in the selected component ends the run pending approval (#2119)", async () => {
     await writeFile(
       join(testDir, "svc.component.ts"),
       `export const svc = { name: "svc", dependsOn: [], deploy: [
-        { phase: "Approve", steps: [{ kind: "gate", signalName: "release-approval" }] },
+        { phase: "Approve", steps: [{ kind: "gate", gate: "release-approval" }] },
         { phase: "Apply", steps: [{ kind: "deploy-thing" }] },
       ] };`,
     );
@@ -600,11 +612,15 @@ describe("runComponents", () => {
     const registry = new CapabilityRegistry();
     registry.register(capability);
 
-    const result = await runComponents(testDir, "svc", { registry });
+    const gates = memoryGateLedgerPort();
+    const result = await runComponents(testDir, "svc", { registry, gates });
 
     expect(result.success).toBe(false);
-    expect(result.gateUnsupported).toEqual({ component: "svc", signalName: "release-approval" });
-    // Pre-flighted: the deploy-thing step after the gate never ran.
+    expect(result.gated?.component).toBe("svc");
+    expect(result.gated?.gate.gate).toBe("release-approval");
+    expect(result.run?.status).toBe("gated");
+    expect(gates.appended).toHaveLength(1);
+    // Nothing after the gate ran.
     expect(capability.calls).toHaveLength(0);
   });
 
@@ -844,7 +860,7 @@ describe("resolveComponentTargets — buildParams (chant #1108)", () => {
     await rm(testDir, { recursive: true, force: true });
   });
 
-  test("forwards buildParams into discovery — the durable (--temporal) path's entrypoint", async () => {
+  test("forwards buildParams into discovery — the selector-resolution entrypoint", async () => {
     await writeFile(
       join(testDir, "svc.component.ts"),
       `

package/src/components/cli-support.ts

@@ -31,12 +31,15 @@ import {
   runComponentDeploy,
   UnknownDependencyError,
   DependencyCycleError,
-  DriverGateUnsupportedError,
   DriverRunFailure,
   type DriverComponent,
+  type DriverGate,
   type DriverPhase,
   type DriverRunResult,
 } from "./driver";
+import type { PendingGateRecord } from "../lifecycle/gate-ledger";
+import type { 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";
@@ -313,18 +316,21 @@ function toDriverComponent(component: { name: string; dependsOn: string[]; deplo
 
 /**
  * Find the first `gate` step anywhere in a component's `deploy`/`rollback`
- * composition (including nested fan-out phases), mirroring
- * `../op/local-executor.ts`'s `findGate`. Used as a pre-flight check so
- * `chant run --components` fails before any step runs — matching
- * `runOpLocal`'s behavior for Ops — rather than only failing mid-run when the
- * driver itself reaches the gated phase (`DriverGateUnsupportedError`).
+ * composition (including nested fan-out phases).
+ *
+ * A declaration-time question, not a pre-flight refusal: since #2119 the
+ * driver decides a gate against the ledger when it reaches one, so nothing
+ * needs to know up front that a component has one.
+ *
+ * The name comes back on `gate` whichever key the component spelled it with,
+ * so a caller never has to know about the deprecated `signalName` (#2202).
  */
-export function findComponentGate(component: DriverComponent): { signalName: string } | undefined {
-  const search = (phases: DriverPhase[] | undefined): { signalName: string } | undefined => {
+export function findComponentGate(component: DriverComponent): { gate: string } | undefined {
+  const search = (phases: DriverPhase[] | undefined): { gate: string } | undefined => {
     for (const phaseDef of phases ?? []) {
       for (const entry of phaseDef.steps) {
         if ((entry as { kind?: unknown }).kind === "gate") {
-          return entry as unknown as { signalName: string };
+          return { gate: gateName(entry as DriverGate) };
         }
         if (typeof (entry as DriverPhase).phase === "string" && Array.isArray((entry as DriverPhase).steps)) {
           const nested = search([entry as DriverPhase]);
@@ -406,6 +412,8 @@ export interface RunComponentsOptions {
    * every test in `cli-support.test.ts`) that doesn't supply this.
    */
   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;
 }
 
 /** Result of `chant run --components <name|all>`. */
@@ -416,8 +424,8 @@ export interface RunComponentsResult {
   /** Component names actually dispatched to the driver, in run order. */
   selected: string[];
   error?: string;
-  /** Set when a selected component (or one of its `deploy`/`rollback` phases) contains a `gate` the local executor cannot run. */
-  gateUnsupported?: { component: string; signalName: string };
+  /** Set when the run stopped at a `gate` nobody has approved (#2119): the component it stopped at and the pending fact recorded for it. */
+  gated?: { component: string; gate: PendingGateRecord };
   /** This run's resolved build-time parameters (chant #1108) — the component-driver counterpart of `../cli/commands/build.ts`'s `BuildResult.buildParams`. Present only once the run actually reached dispatch (mirrors `BuildResult.buildParams`, which is likewise absent on an early-error return). */
   buildParams?: BuildParamProvenance[];
 }
@@ -428,8 +436,7 @@ export interface RunComponentsResult {
  * local in-process executor — the CLI entrypoint the driver never had (#585,
  * follow-up to #556). Discovers the full component set first, then either:
  *  - `selector === "all"`: resolves the whole set's dependency order/waves
- *    and dispatches every component through `runInterpretDriver`, matching
- *    what the generated orchestrator Op will eventually do — the same
+ *    and dispatches every component through `runInterpretDriver`, in the same
  *    order `chant graph --components` reports.
  *  - a single name: dispatches just that component via `runComponentDeploy`,
  *    without requiring the rest of its `dependsOn` graph to be present in
@@ -441,14 +448,12 @@ export interface RunComponentsResult {
  *    infra outside the discovered set (e.g. a shared stack, per the
  *    `search-service` pilot), which is exactly the common case.
  *
- * Pre-flights every selected component for a `gate` step and fails before any
- * step runs (`gateUnsupported`), matching `runOpLocal`'s pre-flight
- * `findGate` check for Ops — gated components need a durable (Temporal)
- * backend, which is out of scope here (issue #585 scopes Temporal-backed
- * component execution to what already exists for Ops; the epic tracks
- * graduating a gated component to `--temporal` separately).
+ * A `gate` no longer refuses the run up front (#2119). The driver decides each
+ * one against the gate ledger as it reaches it; a gate nobody has approved
+ * stops the run there with `gated` set, which the CLI turns into exit code 3
+ * and the `chant approve` line.
  */
-/** Result of resolving a `<name|all>` selector against discovered components — shared by the local (`runComponents`) and durable (Temporal codegen, #589) entrypoints. */
+/** Result of resolving a `<name|all>` selector against discovered components. */
 export interface ResolvedComponentTargets {
   success: boolean;
   targets: DriverComponent[];
@@ -459,10 +464,8 @@ export interface ResolvedComponentTargets {
  * Discover every component under `path` and resolve `selector` (`"all"` or a
  * single component name) to the `DriverComponent`(s) to run, with no gate
  * check and no dispatch — just discovery + selection, factored out of
- * `runComponents` so the durable Temporal entrypoint (`chant run --components
- * <name> --temporal`, #589) can reuse the exact same selection semantics
- * without also inheriting the local executor's pre-flight gate rejection
- * (gates are exactly what the durable path exists to support).
+ * `runComponents` so another entrypoint can reuse the exact same selection
+ * semantics without inheriting the run itself.
  */
 export async function resolveComponentTargets(
   path: string,
@@ -526,17 +529,6 @@ export async function runComponents(
   }
   const targets = resolved.targets;
 
-  for (const component of targets) {
-    const gate = findComponentGate(component);
-    if (gate) {
-      return {
-        success: false,
-        selected: targets.map((c) => c.name),
-        gateUnsupported: { component: component.name, signalName: gate.signalName },
-      };
-    }
-  }
-
   // (#629) Resolve `chant.config.ts`'s `sbom`/`signing`/`vulnPolicy` sections
   // and fill their defaults into every recognized step (`generate-sbom`,
   // `sign`/`attest-provenance`, `verify`, `vuln-gate`) that didn't already
@@ -563,10 +555,25 @@ export async function runComponents(
   const seedOutputs = options.componentOutputs ?? {};
   const { onProgress } = options;
 
+  const gates = options.gates;
+
   try {
     if (selector === "all") {
-      const run = await runInterpretDriver(resolvedTargets, registry, { env, componentOutputs: seedOutputs, onProgress });
-      return { success: true, run, selected, buildParams: options.buildParams };
+      const run = await runInterpretDriver(resolvedTargets, registry, {
+        env,
+        componentOutputs: seedOutputs,
+        onProgress,
+        ...(gates ? { gates } : {}),
+      });
+      return {
+        success: run.status === "ok",
+        run,
+        selected,
+        buildParams: options.buildParams,
+        ...(run.status === "gated" && run.gate
+          ? { gated: { component: run.gatedComponent ?? selected[0], gate: run.gate } }
+          : {}),
+      };
     }
 
     // Single-component invocation: run just this component, bypassing
@@ -592,8 +599,9 @@ export async function runComponents(
       registry,
       componentOutputs,
       onProgress,
+      gates ? { port: gates } : undefined,
     );
-    const status: "ok" | "failed" = componentResult.ok ? "ok" : "failed";
+    const status = componentResult.status === "fail" ? "failed" : componentResult.status;
     onProgress?.({ type: "component-done", wave: 1, component: componentName, status });
     onProgress?.({ type: "wave-done", wave: 1, status });
     onProgress?.({ type: "run-done", status });
@@ -602,21 +610,26 @@ export async function runComponents(
       waves: [selected],
       results: [componentResult],
       ok: componentResult.ok,
-      failedComponent: componentResult.ok ? undefined : componentResult.component,
+      status: componentResult.status,
+      failedComponent: componentResult.status === "fail" ? componentResult.component : undefined,
+      ...(componentResult.status === "gated"
+        ? { gatedComponent: componentResult.component, gate: componentResult.gate }
+        : {}),
       componentOutputs,
     };
-    return { success: componentResult.ok, run, selected, buildParams: options.buildParams };
+    return {
+      success: componentResult.ok,
+      run,
+      selected,
+      buildParams: options.buildParams,
+      ...(componentResult.status === "gated" && componentResult.gate
+        ? { gated: { component: componentResult.component, gate: componentResult.gate } }
+        : {}),
+    };
   } catch (err) {
     if (err instanceof DriverRunFailure) {
       return { success: false, run: err.result, selected, error: err.message };
     }
-    if (err instanceof DriverGateUnsupportedError) {
-      return {
-        success: false,
-        selected,
-        gateUnsupported: { component: err.component, signalName: err.signalName },
-      };
-    }
     if (err instanceof UnknownDependencyError || err instanceof DependencyCycleError) {
       return { success: false, selected, error: err.message };
     }

package/src/components/component-schema.test.ts

@@ -192,14 +192,14 @@ describe("Component JSON Schema", () => {
       deploy: [
         {
           phase: "Approve",
-          steps: [{ kind: "gate", signalName: "approve-gated", description: "confirm", timeout: "24h" }],
+          steps: [{ kind: "gate", gate: "approve-gated", description: "confirm", timeout: "24h" }],
         },
       ],
     };
     expect(validate(withGate)).toBe(true);
   });
 
-  it("rejects a gate step missing signalName", () => {
+  it("rejects a gate step naming neither `gate` nor `signalName`", () => {
     const invalid = {
       name: "gated",
       dependsOn: [],
@@ -208,6 +208,22 @@ describe("Component JSON Schema", () => {
     expect(validate(invalid)).toBe(false);
   });
 
+  // The gate step's name key was renamed from `signalName` to `gate` in #2202.
+  // The schema takes either one and exactly one, through 0.59.0.
+  const gated = (step: Record<string, unknown>): Record<string, unknown> => ({
+    name: "gated",
+    dependsOn: [],
+    deploy: [{ phase: "Approve", steps: [step] }],
+  });
+
+  it("still accepts the deprecated `signalName` key on a gate step", () => {
+    expect(validate(gated({ kind: "gate", signalName: "approve-gated" }))).toBe(true);
+  });
+
+  it("rejects a gate step carrying both `gate` and `signalName`", () => {
+    expect(validate(gated({ kind: "gate", gate: "approve-gated", signalName: "approve-gated" }))).toBe(false);
+  });
+
   it("accepts a stackOutput cross-stack reference", () => {
     const withStackOutput = {
       name: "svc",

package/src/components/component.schema.json

@@ -160,17 +160,30 @@
       }
     },
 
+    "GateName": {
+      "type": "string",
+      "minLength": 1,
+      "description": "A gate's name, on either of the two keys that may carry it."
+    },
+
     "Gate": {
       "type": "object",
-      "description": "Pauses the composition for an external signal (typically human approval) before continuing. A gate in a component's composition requires the durable (Temporal) execution backend; it cannot run on the local in-process executor.",
-      "required": ["kind", "signalName"],
+      "description": "Ends the run pending human approval. The driver decides a gate against the gate ledger when it reaches one; a gate nobody has approved stops the run there, and `chant approve <component> <gate>` records the resolution the next run reads.",
+      "required": ["kind"],
+      "oneOf": [
+        { "required": ["gate"], "properties": { "gate": { "$ref": "#/$defs/GateName" } } },
+        { "required": ["signalName"], "properties": { "signalName": { "$ref": "#/$defs/GateName" } } }
+      ],
       "additionalProperties": false,
       "properties": {
         "kind": { "type": "string", "const": "gate" },
+        "gate": {
+          "$ref": "#/$defs/GateName",
+          "description": "The gate's name — what `chant approve <component> <gate>` resolves."
+        },
         "signalName": {
-          "type": "string",
-          "minLength": 1,
-          "description": "Signal name the generated workflow waits for before continuing."
+          "$ref": "#/$defs/GateName",
+          "description": "Deprecated spelling of `gate` (chant #2202), accepted through 0.59.0 and removed in 0.60.0. Exactly one of `gate` and `signalName` may be present."
         },
         "timeout": {
           "type": "string",

package/src/components/component.test.ts

@@ -37,13 +37,13 @@ describe("phase()", () => {
 
 describe("gate()", () => {
   it("builds a minimal Gate", () => {
-    expect(gate("approve-x")).toEqual({ kind: "gate", signalName: "approve-x" });
+    expect(gate("approve-x")).toEqual({ kind: "gate", gate: "approve-x" });
   });
 
   it("carries optional timeout/description", () => {
     expect(gate("approve-x", { timeout: "24h", description: "confirm" })).toEqual({
       kind: "gate",
-      signalName: "approve-x",
+      gate: "approve-x",
       timeout: "24h",
       description: "confirm",
     });

package/src/components/component.ts

@@ -77,16 +77,36 @@ export interface Step {
   [param: string]: unknown;
 }
 
-/** Mirrors `$defs.Gate` — pauses the composition for an external signal (typically human approval). */
-export interface Gate {
+/** Everything on a component gate step except the key that names it. */
+export interface GateBase {
   kind: "gate";
-  signalName: string;
-  /** Duration string bounding the wait, e.g. "48h". Default: "48h". */
+  /** How long a recorded pending gate stays valid, as a duration string. Default: "48h". */
   timeout?: string;
   /** Human-readable description of the action required to unblock this gate. */
   description?: string;
 }
 
+/**
+ * Mirrors `$defs.Gate` — a human approval decided against the gate ledger; the
+ * run stops here with status `gated` until `chant approve` has answered it.
+ * The name lives on `gate`; `signalName` is the key it carried through 0.58.0
+ * and is still accepted (#2202). Read both through `gateName()`.
+ */
+export type Gate = GateBase &
+  (
+    | {
+        /** The gate's name — what `chant approve <component> <gate>` resolves. */
+        gate: string;
+        /** @deprecated Renamed to `gate` in #2202. Accepted through 0.59.0, removed in 0.60.0. */
+        signalName?: string;
+      }
+    | {
+        gate?: undefined;
+        /** @deprecated Renamed to `gate` in #2202. Accepted through 0.59.0, removed in 0.60.0. */
+        signalName: string;
+      }
+  );
+
 /**
  * Mirrors `$defs.Phase` — one named phase of a deploy composition. A step may
  * itself be a nested `Phase`, which is how a fan-out unit becomes a mini-
@@ -170,9 +190,9 @@ export function phase(name: string, steps: Array<Step | Gate | Phase>, opts?: {
   return { phase: name, steps, ...(opts?.parallel ? { parallel: true } : {}) };
 }
 
-/** Author a gate step — pauses the composition for an external signal (typically human approval). */
-export function gate(signalName: string, opts?: { timeout?: string; description?: string }): Gate {
-  return { kind: "gate", signalName, ...opts };
+/** Author a gate step — a human approval the driver decides against the gate ledger, stopping the run `gated` when nothing has answered it. */
+export function gate(name: string, opts?: { timeout?: string; description?: string }): Gate {
+  return { kind: "gate", gate: name, ...opts };
 }
 
 /**

package/src/components/config-defaults.test.ts

@@ -257,11 +257,11 @@ describe("applyConfigDefaults", () => {
   test("leaves gate steps untouched", () => {
     const config: ChantConfig = { sbom: { format: "cyclonedx" } };
     const comp = component([
-      { phase: "Approve", steps: [{ kind: "gate", signalName: "release-approval" }] },
+      { phase: "Approve", steps: [{ kind: "gate", gate: "release-approval" }] },
     ]);
 
     const result = applyConfigDefaults(comp, config);
-    expect(result.deploy[0]!.steps[0]).toEqual({ kind: "gate", signalName: "release-approval" });
+    expect(result.deploy[0]!.steps[0]).toEqual({ kind: "gate", gate: "release-approval" });
   });
 
   test("applies defaults to rollback phases too", () => {