@intentius/chant 0.57.0 → 0.58.0

package/src/components/driver.test.ts

@@ -5,17 +5,17 @@
  * implementations are a separate later issue (#557). These tests exercise the
  * driver's generic behavior only: dependency ordering + parallel-safe waves,
  * sequential vs parallel step execution, `onFailure`/saga rollback in reverse
- * order, output wiring (`@Phase.field` and `@<component>.publish.*`), and that
- * a `gate` errors on the local executor. Several cases replay the real pilot
+ * order, output wiring (`@Phase.field` and `@<component>.publish.*`), and
+ * gate-as-fact on the local executor (#2119). Several cases replay the real pilot
  * declarations (../pilots/*.pilot.ts) as realistic inputs.
  */
 
 import { describe, expect, it } from "vitest";
 import { CapabilityRegistry, type DeployContext } from "./capability";
 import { stubCapability } from "./verbs/stub";
+import { memoryGateLedgerPort } from "../op/gate";
 import {
   DependencyCycleError,
-  DriverGateUnsupportedError,
   DriverRunFailure,
   UnknownDependencyError,
   accumulateComponentOutputs,
@@ -210,32 +210,102 @@ describe("runComponentDeploy — sequential vs parallel", () => {
   });
 });
 
-describe("runComponentDeploy — gate on the local executor", () => {
-  it("throws DriverGateUnsupportedError when a phase contains a gate", async () => {
+describe("runComponentDeploy — gate as fact (#2119)", () => {
+  const NOW = "2026-09-05T12:00:00.000Z";
+
+  const gatedComponent = (): DriverComponent => ({
+    name: "neo4j-cluster",
+    deploy: [
+      { phase: "Prepare", steps: [{ kind: "cfn-deploy" }] },
+      { phase: "Node 1", steps: [{ kind: "gate", signalName: "approve-node-1" }, { kind: "code-deploy" }] },
+    ],
+    rollback: [{ phase: "Undo", steps: [{ kind: "cfn-deploy" }] }],
+  });
+
+  function registryWithCalls() {
     const registry = new CapabilityRegistry();
-    const component: DriverComponent = {
-      name: "neo4j-cluster",
-      deploy: [
-        {
-          phase: "Node 1",
-          steps: [{ kind: "gate", signalName: "approve-node-1" }, { kind: "cfn-deploy" }],
-        },
-      ],
-    };
-    await expect(
-      runComponentDeploy(component, { env: "dev", component: "neo4j-cluster" }, registry, {}),
-    ).rejects.toThrow(DriverGateUnsupportedError);
+    const calls: string[] = [];
+    const rolledBack: string[] = [];
+    for (const kind of ["cfn-deploy", "code-deploy"]) {
+      registry.register(
+        fakeCapability(kind, {
+          run: () => { calls.push(kind); return { ok: true }; },
+          rollback: () => { rolledBack.push(kind); },
+        }).capability,
+      );
+    }
+    return { registry, calls, rolledBack };
+  }
+
+  it("ends gated, records the pending fact, and runs nothing after the gate", async () => {
+    const { registry, calls, rolledBack } = registryWithCalls();
+    const port = memoryGateLedgerPort();
+    const result = await runComponentDeploy(
+      gatedComponent(), { env: "dev", component: "neo4j-cluster" }, registry, {}, undefined,
+      { port, now: NOW },
+    );
+
+    expect(result.status).toBe("gated");
+    expect(result.ok).toBe(false);
+    expect(result.gate).toMatchObject({ op: "neo4j-cluster", gate: "approve-node-1" });
+    expect(port.appended).toHaveLength(1);
+    expect(calls).toEqual(["cfn-deploy"]);
+    // A gate is not a failure: nothing unwinds and no `rollback` phase runs.
+    expect(rolledBack).toEqual([]);
+    expect(result.records.map((r) => [r.kind, r.status])).toEqual([
+      ["cfn-deploy", "ok"],
+      ["gate:approve-node-1", "skipped"],
+      ["code-deploy", "skipped"],
+    ]);
   });
 
-  it("the neo4j pilot's gated Node 1 phase errors locally (matches chant's local-executor behavior)", async () => {
+  it("a resolution newer than the pending fact passes the gate and carries the approver", async () => {
+    const { registry, calls } = registryWithCalls();
+    const port = memoryGateLedgerPort({
+      pending: [{
+        version: 1, kind: "pending", op: "neo4j-cluster", gate: "approve-node-1",
+        timestamp: "2026-09-05T10:00:00.000Z", expiresAt: "2026-09-07T10:00:00.000Z",
+      }],
+      resolutions: [{
+        version: 1, op: "neo4j-cluster", gate: "approve-node-1",
+        resolvedBy: "alex", timestamp: "2026-09-05T11:00:00.000Z",
+      }],
+    });
+    const result = await runComponentDeploy(
+      gatedComponent(), { env: "dev", component: "neo4j-cluster" }, registry, {}, undefined,
+      { port, now: NOW },
+    );
+
+    expect(result.status).toBe("ok");
+    expect(calls).toEqual(["cfn-deploy", "code-deploy"]);
+    expect(result.records.find((r) => r.kind === "gate:approve-node-1")?.approval)
+      .toEqual({ gate: "approve-node-1", resolvedBy: "alex", timestamp: "2026-09-05T11:00:00.000Z" });
+  });
+
+  it("the neo4j pilot's gated Node 1 phase ends the run pending approval", async () => {
     const registry = new CapabilityRegistry();
     for (const kind of ["cfn-deploy", "code-deploy", "wait-cluster-healthy"]) {
       registry.register(fakeCapability(kind, { run: () => ({ ok: true }) }).capability);
     }
     const json = projectToJson(neo4jCluster) as unknown as DriverComponent;
-    await expect(runComponentDeploy(json, { env: "dev", component: "neo4j-cluster" }, registry, {})).rejects.toThrow(
-      /gate "approve-neo4j-node-1" is not supported/,
+    const result = await runComponentDeploy(
+      json, { env: "dev", component: "neo4j-cluster" }, registry, {}, undefined,
+      { port: memoryGateLedgerPort(), now: NOW },
     );
+    expect(result.status).toBe("gated");
+    expect(result.gate?.gate).toBe("approve-neo4j-node-1");
+  });
+
+  it("a gated component stops the whole interpret run without throwing", async () => {
+    const { registry } = registryWithCalls();
+    const run = await runInterpretDriver([gatedComponent()], registry, {
+      env: "dev",
+      gates: memoryGateLedgerPort(),
+      now: NOW,
+    });
+    expect(run.status).toBe("gated");
+    expect(run.gatedComponent).toBe("neo4j-cluster");
+    expect(run.gate?.gate).toBe("approve-node-1");
   });
 });
 
@@ -415,7 +485,7 @@ describe("runComponentDeploy — output wiring", () => {
 
 describe("collectComponentOutputs / accumulateComponentOutputs — the shared accumulator (#700)", () => {
   // Exported so the durable path's `accumulateComponentOutputs` activity
-  // (lexicons/temporal/src/component-op/activities.ts) captures outputs via
+  // (a hosting runtime's own step executor) captures outputs via
   // the same function `runComponentDeploy` does — the accumulation twin of
   // the already-shared `resolveStepInput`.
   const phaseOutputs = {
@@ -446,7 +516,7 @@ describe("collectComponentOutputs / accumulateComponentOutputs — the shared ac
       publish: { uri: "repo@sha256:abc", digest: "sha256:abc" },
     });
     expect(out.other).toEqual({ x: 1 });
-    // Plain data throughout — survives the Temporal activity JSON boundary unchanged.
+    // Plain data throughout — survives an out-of-process JSON boundary unchanged.
     expect(JSON.parse(JSON.stringify(out))).toEqual(out);
   });
 

package/src/components/driver.ts

@@ -11,11 +11,18 @@
  * component.schema.json (`@Phase.field` prior-step references,
  * `@<component>.publish.<field>` cross-component artifact references, and
  * passes through `$env.*`/`stackOutput` values as opaque env config), runs
- * `parallel` phases concurrently, rejects a `gate` locally (matching
- * ../op/local-executor.ts's `LocalGateUnsupportedError`), and on terminal
- * failure unwinds every executed step in reverse via that step's capability
- * `rollback`, then runs `onFailure` phases in reverse order (best-effort),
- * mirroring the Op local executor's saga semantics.
+ * `parallel` phases concurrently, decides a `gate` against the gate ledger
+ * (#2119 — the same `../op/gate.ts` the Op executor uses, so `chant run
+ * --components` and `chant run <op>` can never disagree about what a gate
+ * means), and on terminal failure unwinds every executed step in reverse via
+ * that step's capability `rollback`, then runs `onFailure` phases in reverse
+ * order (best-effort), mirroring the Op local executor's saga semantics.
+ *
+ * A gate nobody has approved is not a failure: the component stops there with
+ * status `gated`, the pending fact is on the ledger, and no rollback and no
+ * `onFailure` phase runs — nothing failed and the steps that did run are the
+ * steps the author meant to run before the approval. The next run re-reads the
+ * ledger and continues past the gate if `chant approve` has answered it.
  *
  * A step whose capability declares no `rollback` is never silently passed
  * over during unwind: it gets a `"rollback-opted-out"` record (see
@@ -25,15 +32,13 @@
  * already requires at author time — the driver reports the same fact the
  * lint rule already made a component author state.
  *
- * This unwind runs entirely in-process: if the process crashes mid-rollback
- * on the local executor, nothing resumes it — there is no persisted run state
- * to resume from. That is the documented Temporal boundary (see
- * docs/components/orchestration.mdx#rollback-comes-free and
- * docs/guide/local-vs-temporal.mdx): the *mechanism* (reverse-order unwind
- * calling each capability's `rollback`) is capability-agnostic and works
- * identically on both executors, but *durable resume of a rollback already in
- * progress* is Temporal-only, the same boundary that already applies to
- * forward `onFailure` compensation on an Op.
+ * This unwind runs entirely in-process: if the process crashes mid-rollback,
+ * nothing resumes it — there is no persisted run state to resume from (see
+ * docs/components/orchestration.mdx#rollback-comes-free). The *mechanism*
+ * (reverse-order unwind calling each capability's `rollback`) is
+ * capability-agnostic; *durable resume of a rollback already in progress*
+ * would be a hosting runtime's to offer, the same boundary that already
+ * applies to forward `onFailure` compensation on an Op.
  *
  * Contains zero per-component logic: nothing in this module branches on a
  * component or capability `kind`/name. All behavior is either generic
@@ -42,8 +47,10 @@
  */
 
 import { topoSort } from "../codegen/topo-sort";
+import { evaluateGate, gitGateLedgerPort, type GateLedgerPort } from "../op/gate";
+import type { PendingGateRecord } from "../lifecycle/gate-ledger";
 import type { CapabilityRegistry, DeployContext } from "./capability";
-import type { RunProgressEvent } from "./run-progress";
+import type { RunProgressEvent, RunProgressStatus } from "./run-progress";
 
 export type { RunProgressEvent } from "./run-progress";
 
@@ -61,7 +68,7 @@ export interface DriverStep {
   [param: string]: unknown;
 }
 
-/** A gate step — pauses for an external signal; unsupported on the local executor (schema `Gate`). */
+/** A gate step — a human approval, decided against the gate ledger when the run reaches it (schema `Gate`). */
 export interface DriverGate {
   kind: "gate";
   signalName: string;
@@ -96,20 +103,6 @@ function isPhaseStep(step: DriverStep | DriverGate | DriverPhase): step is Drive
 
 // ── Errors ────────────────────────────────────────────────────────────────
 
-/** Thrown when a component's composition contains a `gate` — gates need a durable runtime, matching chant's Op local executor. */
-export class DriverGateUnsupportedError extends Error {
-  constructor(
-    public readonly component: string,
-    public readonly signalName: string,
-  ) {
-    super(
-      `component "${component}": gate "${signalName}" is not supported on the local executor — ` +
-        `gates need a durable runtime. Re-run with a durable (Temporal) backend.`,
-    );
-    this.name = "DriverGateUnsupportedError";
-  }
-}
-
 /** Thrown when a dependency cycle is found among `dependsOn` edges. */
 export class DependencyCycleError extends Error {
   constructor(public readonly cycle: string[]) {
@@ -147,12 +140,18 @@ export interface DriverStepRecord {
   durationMs: number;
   output?: unknown;
   error?: string;
+  /** Set on a `gate` step that passed (#2119): who resolved it, when, and at what address. */
+  approval?: { gate: string; resolvedBy: string; timestamp: string; url?: string };
 }
 
 export interface DriverComponentResult {
   component: string;
   ok: boolean;
+  /** Three-state outcome (#2119) — `gated` is `ok: false` without being a failure: the component stopped at a gate awaiting `chant approve`, and nothing was rolled back. */
+  status: "ok" | "fail" | "gated";
   records: DriverStepRecord[];
+  /** Present when `status === "gated"`: the pending fact this component stopped on. */
+  gate?: PendingGateRecord;
 }
 
 export interface DriverRunResult {
@@ -162,8 +161,14 @@ export interface DriverRunResult {
   waves: string[][];
   results: DriverComponentResult[];
   ok: boolean;
+  /** Three-state outcome (#2119), matching `OpRunResult.status`. */
+  status: "ok" | "fail" | "gated";
   /** Name of the component that terminated the run, if any. */
   failedComponent?: string;
+  /** Name of the component the run stopped at for approval, when `status === "gated"`. */
+  gatedComponent?: string;
+  /** The pending fact the run stopped on, when `status === "gated"`. */
+  gate?: PendingGateRecord;
   /**
    * The accumulated cross-component/cross-stack outputs after the run — each
    * component's `publish` output and, for an applied stack, its `cfn-deploy`
@@ -285,12 +290,11 @@ export function resolveWiring(
  * Deep-walk an object, resolving every string/stackOutput wiring value found.
  * Arrays and nested objects are walked too.
  *
- * Exported (not just used internally) so the durable Temporal path
- * (`@intentius/chant-lexicon-temporal`'s component workflow codegen, see
- * epic #551 #589) can resolve a step's wiring the same way inside a Temporal
- * *activity* — the workflow itself only accumulates `phaseOutputs`/
- * `componentOutputs` and passes them through; resolution logic stays in one
- * place so local and durable execution can never silently diverge.
+ * Exported (not just used internally) so a hosting runtime that runs steps
+ * out of process can resolve a step's wiring the same way — the orchestrator
+ * only accumulates `phaseOutputs`/`componentOutputs` and passes them through;
+ * resolution logic stays in one place so local and hosted execution can never
+ * silently diverge.
  */
 export function resolveStepInput(
   input: Record<string, unknown>,
@@ -338,6 +342,29 @@ class StepFailure extends Error {
   }
 }
 
+/** Internal: a phase stopped at an unapproved gate (#2119). Carries what ran before it, so the records survive; not a failure, so no unwind follows. */
+class GateStop extends Error {
+  constructor(
+    public readonly records: DriverStepRecord[],
+    public readonly executed: ExecutedStep[],
+    public readonly pending: PendingGateRecord,
+  ) {
+    super(`gate "${pending.gate}" is pending approval`);
+    this.name = "GateStop";
+  }
+}
+
+/** A result status as the progress stream spells it — the only difference is `fail` vs `failed`, which the two vocabularies have always disagreed on. */
+function progressStatus(status: DriverComponentResult["status"]): RunProgressStatus {
+  return status === "fail" ? "failed" : status;
+}
+
+/** How a component's run reaches the gate ledger — see `../op/gate.ts`. */
+export interface GateContext {
+  port: GateLedgerPort;
+  now?: string;
+}
+
 /** Run a single capability step. Never throws for a capability-run failure; returns a fail record instead. */
 async function runCapabilityStep(
   step: DriverStep,
@@ -381,11 +408,16 @@ async function runCapabilityStep(
 }
 
 /**
- * Run a phase's steps. A step may be a `Gate` (rejected — local executor has
- * no durable wait) or a nested `Phase` (a fan-out unit; recursed into,
- * inheriting `parallel` from its own definition, not its parent's). Steps run
- * sequentially unless `phase.parallel` is set, in which case they run via
- * `Promise.all`, matching ../op/local-executor.ts's phase semantics.
+ * Run a phase's steps. A step may be a `Gate` (decided against the gate
+ * ledger, in authored order — a resolution newer than the gate's newest
+ * pending fact lets it pass carrying the approver, anything else records the
+ * fact and stops the component) or a nested `Phase` (a fan-out unit; recursed
+ * into, inheriting `parallel` from its own definition, not its parent's).
+ * Steps run sequentially unless `phase.parallel` is set, in which case they run
+ * via `Promise.all`, matching ../op/local-executor.ts's phase semantics — and
+ * as there, a gate in a parallel phase is decided before the fan-out, since a
+ * gate is a read of the ledger rather than work, and starting activities a
+ * pending gate is about to strand defeats the point of stopping at it.
  *
  * `onProgress`, when supplied, is called with a `phase-start` event before any
  * step runs, a `step` event around each capability invocation (`"running"`
@@ -402,22 +434,60 @@ async function runPhase(
   registry: CapabilityRegistry,
   phaseOutputs: Record<string, Record<string, unknown>>,
   componentOutputs: Record<string, Record<string, unknown>>,
+  gates: GateContext,
   onProgress?: (event: RunProgressEvent) => void,
 ): Promise<{ records: DriverStepRecord[]; executed: ExecutedStep[] }> {
-  const gate = phaseDef.steps.find(isGateStep);
-  if (gate) throw new DriverGateUnsupportedError(ctx.component, gate.signalName);
+  /** Decide this phase's gates against the ledger, in authored order, before any of its work starts. Throws `GateStop` at the first one nobody has approved. */
+  const decideGates = async (): Promise<DriverStepRecord[]> => {
+    const gateRecords: DriverStepRecord[] = [];
+    for (const gate of phaseDef.steps.filter(isGateStep)) {
+      const start = Date.now();
+      const check = await evaluateGate(gates.port, {
+        op: ctx.component,
+        gate: gate.signalName,
+        ...(gate.description ? { description: gate.description } : {}),
+        ...(gate.timeout ? { timeout: gate.timeout } : {}),
+        ...(gates.now ? { now: gates.now } : {}),
+      });
+      const base = { component: ctx.component, phase: phaseDef.phase, kind: `gate:${gate.signalName}` };
+      if (!check.satisfied) {
+        gateRecords.push({ ...base, status: "skipped" as const, durationMs: Date.now() - start });
+        for (const skipped of phaseDef.steps.filter((s): s is DriverStep | DriverPhase => !isGateStep(s))) {
+          gateRecords.push(skippedRecord(skipped));
+        }
+        throw new GateStop(gateRecords, [], check.pending);
+      }
+      gateRecords.push({
+        ...base,
+        status: "ok" as const,
+        durationMs: Date.now() - start,
+        approval: {
+          gate: gate.signalName,
+          resolvedBy: check.resolution.resolvedBy,
+          timestamp: check.resolution.timestamp,
+          ...(check.resolution.url ? { url: check.resolution.url } : {}),
+        },
+      });
+    }
+    return gateRecords;
+  };
 
   const entries = phaseDef.steps.filter((s): s is DriverStep | DriverPhase => !isGateStep(s));
 
   const runEntry = async (
     entry: DriverStep | DriverPhase,
-  ): Promise<{ records: DriverStepRecord[]; executed: ExecutedStep[]; failed: boolean }> => {
+  ): Promise<{ records: DriverStepRecord[]; executed: ExecutedStep[]; failed: boolean; pending?: PendingGateRecord }> => {
     if (isPhaseStep(entry)) {
       try {
-        const nested = await runPhase(entry, ctx, registry, phaseOutputs, componentOutputs, onProgress);
+        const nested = await runPhase(entry, ctx, registry, phaseOutputs, componentOutputs, gates, onProgress);
         return { ...nested, failed: false };
       } catch (err) {
         if (err instanceof StepFailure) return { records: err.records, executed: err.executed, failed: true };
+        // A nested fan-out phase's gate stops the whole component, but the
+        // records it produced before the gate still belong in the run.
+        if (err instanceof GateStop) {
+          return { records: err.records, executed: err.executed, failed: false, pending: err.pending };
+        }
         throw err;
       }
     }
@@ -448,32 +518,38 @@ async function runPhase(
     };
   };
 
+  const skippedRecord = (entry: DriverStep | DriverPhase): DriverStepRecord => ({
+    component: ctx.component,
+    phase: phaseDef.phase,
+    kind: isPhaseStep(entry) ? entry.phase : (entry as DriverStep).kind,
+    status: "skipped",
+    durationMs: 0,
+  });
+
   const runEntries = async (): Promise<{ records: DriverStepRecord[]; executed: ExecutedStep[] }> => {
+    const gateRecords = await decideGates();
     if (phaseDef.parallel) {
       const results = await Promise.all(entries.map(runEntry));
-      const records = results.flatMap((r) => r.records);
+      const records = gateRecords.concat(results.flatMap((r) => r.records));
       const executed = results.flatMap((r) => r.executed);
+      const pending = results.find((r) => r.pending)?.pending;
+      if (pending) throw new GateStop(records, executed, pending);
       if (results.some((r) => r.failed)) throw new StepFailure(records, executed);
       return { records, executed };
     }
 
-    const records: DriverStepRecord[] = [];
+    const records: DriverStepRecord[] = [...gateRecords];
     const executed: ExecutedStep[] = [];
     for (let i = 0; i < entries.length; i++) {
       const result = await runEntry(entries[i]);
       records.push(...result.records);
       executed.push(...result.executed);
+      if (result.pending) {
+        for (const skipped of entries.slice(i + 1)) records.push(skippedRecord(skipped));
+        throw new GateStop(records, executed, result.pending);
+      }
       if (result.failed) {
-        for (const skipped of entries.slice(i + 1)) {
-          const skippedKind = isPhaseStep(skipped) ? skipped.phase : (skipped as DriverStep).kind;
-          records.push({
-            component: ctx.component,
-            phase: phaseDef.phase,
-            kind: skippedKind,
-            status: "skipped",
-            durationMs: 0,
-          });
-        }
+        for (const skipped of entries.slice(i + 1)) records.push(skippedRecord(skipped));
         throw new StepFailure(records, executed);
       }
     }
@@ -486,7 +562,9 @@ async function runPhase(
     onProgress?.({ type: "phase-done", component: ctx.component, phase: phaseDef.phase, status: "ok" });
     return result;
   } catch (err) {
-    if (err instanceof StepFailure) {
+    if (err instanceof GateStop) {
+      onProgress?.({ type: "phase-done", component: ctx.component, phase: phaseDef.phase, status: "gated" });
+    } else if (err instanceof StepFailure) {
       onProgress?.({ type: "phase-done", component: ctx.component, phase: phaseDef.phase, status: "failed" });
     }
     throw err;
@@ -577,6 +655,7 @@ export async function runComponentDeploy(
   registry: CapabilityRegistry,
   componentOutputs: Record<string, Record<string, unknown>>,
   onProgress?: (event: RunProgressEvent) => void,
+  gates: GateContext = { port: gitGateLedgerPort() },
 ): Promise<DriverComponentResult> {
   const phaseOutputs: Record<string, Record<string, unknown>> = {};
   const records: DriverStepRecord[] = [];
@@ -584,11 +663,20 @@ export async function runComponentDeploy(
 
   try {
     for (const phaseDef of component.deploy) {
-      const result = await runPhase(phaseDef, ctx, registry, phaseOutputs, componentOutputs, onProgress);
+      const result = await runPhase(phaseDef, ctx, registry, phaseOutputs, componentOutputs, gates, onProgress);
       records.push(...result.records);
       allExecuted.push(...result.executed);
     }
   } catch (err) {
+    // A pending gate stops the component where it stands (#2119): no saga
+    // unwind and no `rollback` phase. The steps before the gate ran on
+    // purpose and are meant to survive the wait for an approval — undoing
+    // them would make every gated run a no-op with a rollback attached.
+    if (err instanceof GateStop) {
+      records.push(...err.records);
+      return { component: component.name, ok: false, status: "gated", records, gate: err.pending };
+    }
+
     if (err instanceof StepFailure) {
       records.push(...err.records);
       allExecuted.push(...err.executed);
@@ -600,24 +688,24 @@ export async function runComponentDeploy(
 
     for (const phaseDef of [...(component.rollback ?? [])].reverse()) {
       try {
-        const result = await runPhase(phaseDef, ctx, registry, phaseOutputs, componentOutputs, onProgress);
+        const result = await runPhase(phaseDef, ctx, registry, phaseOutputs, componentOutputs, gates, onProgress);
         records.push(...result.records);
       } catch (compErr) {
-        if (compErr instanceof StepFailure) records.push(...compErr.records);
+        if (compErr instanceof StepFailure || compErr instanceof GateStop) records.push(...compErr.records);
         else throw compErr;
       }
     }
 
-    return { component: component.name, ok: false, records };
+    return { component: component.name, ok: false, status: "fail", records };
   }
 
   // Publish-family and stack outputs become this component's entry in
-  // `componentOutputs` — through the same exported accumulator the durable
-  // path's `accumulateComponentOutputs` activity calls (#700), so local and
-  // Temporal runs can never diverge on what downstream references see.
+  // `componentOutputs` — through the same exported accumulator a hosted
+  // runtime calls (#700), so local and hosted runs can never diverge on what
+  // downstream references see.
   accumulateComponentOutputs(componentOutputs, component.name, phaseOutputs);
 
-  return { component: component.name, ok: true, records };
+  return { component: component.name, ok: true, status: "ok", records };
 }
 
 /**
@@ -641,9 +729,8 @@ export async function runComponentDeploy(
  * the driver free of per-capability branching. Returns `undefined` when the
  * component exposed nothing.
  *
- * Exported, like `resolveStepInput`, so the durable Temporal path
- * (lexicons/temporal/src/component-op/activities.ts) accumulates outputs via
- * this exact function rather than re-deriving it (#700). The resolver and the
+ * Exported, like `resolveStepInput`, so a hosting runtime accumulates outputs
+ * via this exact function rather than re-deriving it (#700). The resolver and the
  * accumulator are the two halves of one contract; sharing only the resolver
  * is how the cross-stack gap #699 closed locally could reopen durably.
  */
@@ -659,11 +746,11 @@ export function collectComponentOutputs(
 /**
  * Record a finished component's outputs (`collectComponentOutputs`) into the
  * shared `componentOutputs` map under the component's own name, merging over
- * any seeded entry (`--seed-outputs`, or a durable parent workflow's
- * thread-through). Mutates and returns `componentOutputs`, so a Temporal
- * activity can hand the updated map back to its workflow over the JSON
- * boundary — every value in it is plain activity-result data, so the map is
- * serializable by construction. A no-op when the component exposed nothing.
+ * any seeded entry (`--seed-outputs`, or a parent orchestrator's
+ * thread-through). Mutates and returns `componentOutputs`, so an out-of-process
+ * step can hand the updated map back over a JSON boundary — every value in it
+ * is plain result data, so the map is serializable by construction. A no-op
+ * when the component exposed nothing.
  */
 export function accumulateComponentOutputs(
   componentOutputs: Record<string, Record<string, unknown>>,
@@ -736,6 +823,10 @@ export interface InterpretRunOptions {
    * byte-for-byte the same as before this option existed.
    */
   onProgress?: (event: RunProgressEvent) => void;
+  /** 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;
+  /** ISO-8601 "now" for gate decisions, so a test is deterministic. */
+  now?: string;
 }
 
 /**
@@ -748,6 +839,11 @@ export interface InterpretRunOptions {
  * a result with `ok: false`; throws `DriverRunFailure` carrying that result
  * so callers can choose to inspect or propagate it.
  *
+ * A component that stops at an unapproved gate (#2119) ends the run the same
+ * way, with `status: "gated"` and the pending fact on `gate` — but it is
+ * *returned*, never thrown, because nothing failed. Downstream waves do not
+ * run: a gate is the author saying a human decides before the rest happens.
+ *
  * Zero per-component logic: this function and everything it calls dispatches
  * purely on the generic `Component`/`Phase`/`Step` shapes and the registry —
  * no branch anywhere names a specific component or capability.
@@ -761,11 +857,16 @@ export async function runInterpretDriver(
   const byName = new Map(components.map((c) => [c.name, c]));
   const componentOutputs: Record<string, Record<string, unknown>> = { ...(options.componentOutputs ?? {}) };
   const { onProgress } = options;
+  const gates: GateContext = {
+    port: options.gates ?? gitGateLedgerPort(),
+    ...(options.now ? { now: options.now } : {}),
+  };
 
   onProgress?.({ type: "run-start", waves });
 
   const results: DriverComponentResult[] = [];
   let failedComponent: string | undefined;
+  let gated: DriverComponentResult | undefined;
 
   waveLoop: for (const [waveIndex, wave] of waves.entries()) {
     const waveNum = waveIndex + 1;
@@ -780,23 +881,32 @@ export async function runInterpretDriver(
           registry,
           componentOutputs,
           onProgress,
+          gates,
         );
-        onProgress?.({ type: "component-done", wave: waveNum, component: component.name, status: result.ok ? "ok" : "failed" });
+        onProgress?.({ type: "component-done", wave: waveNum, component: component.name, status: progressStatus(result.status) });
         return result;
       }),
     );
     results.push(...waveResults);
-    const failed = waveResults.find((r) => !r.ok);
-    onProgress?.({ type: "wave-done", wave: waveNum, status: failed ? "failed" : "ok" });
-    if (failed) {
-      failedComponent = failed.component;
+    const stopped = waveResults.find((r) => r.status !== "ok");
+    onProgress?.({ type: "wave-done", wave: waveNum, status: progressStatus(stopped?.status ?? "ok") });
+    if (stopped) {
+      // A failure in the same wave outranks a gate: something is actually
+      // broken, and reporting the run as "waiting on a human" would hide it.
+      const failure = waveResults.find((r) => r.status === "fail");
+      if (failure) failedComponent = failure.component;
+      else gated = stopped;
       break waveLoop;
     }
   }
 
-  const ok = failedComponent === undefined;
-  onProgress?.({ type: "run-done", status: ok ? "ok" : "failed" });
-  const result: DriverRunResult = { order, waves, results, ok, failedComponent, componentOutputs };
-  if (!ok) throw new DriverRunFailure(result);
+  const status: DriverRunResult["status"] = failedComponent ? "fail" : gated ? "gated" : "ok";
+  const ok = status === "ok";
+  onProgress?.({ type: "run-done", status: progressStatus(status) });
+  const result: DriverRunResult = {
+    order, waves, results, ok, status, failedComponent, componentOutputs,
+    ...(gated ? { gatedComponent: gated.component, gate: gated.gate } : {}),
+  };
+  if (status === "fail") throw new DriverRunFailure(result);
   return result;
 }