@intentius/chant 0.58.0 → 0.59.0

package/src/cli/plugins.test.ts

@@ -1,6 +1,6 @@
 import { describe, test, expect } from "vitest";
-import { loadPlugin, loadPlugins, resolveLexiconVersions } from "./plugins";
-import { isLexiconPlugin } from "../lexicon";
+import { collectChangeSubscribers, loadPlugin, loadPlugins, resolveLexiconVersions } from "./plugins";
+import { isLexiconPlugin, type LexiconPlugin } from "../lexicon";
 
 describe("loadPlugin", () => {
   test("loads aws plugin with full LexiconPlugin interface", async () => {
@@ -61,3 +61,69 @@ describe("resolveLexiconVersions", () => {
     expect(resolveLexiconVersions([])).toEqual({});
   });
 });
+
+describe("collectChangeSubscribers (#1981)", () => {
+  function fakePlugin(name: string, withSeam: boolean): LexiconPlugin {
+    const plugin = {
+      name,
+      serializer: { name, serialize: () => "" },
+      generate: async () => {},
+      validate: async () => {},
+      coverage: async () => {},
+      package: async () => {},
+    } as unknown as LexiconPlugin;
+    if (withSeam) {
+      plugin.subscribeChanges = async () => ({ close: async () => {} });
+    }
+    return plugin;
+  }
+
+  const entitiesFor = (lexicon: string) =>
+    new Map([[lexicon, new Map([["web", { entityType: "K8s::Apps::Deployment", props: {} }]])]]);
+
+  test("a lexicon without the seam contributes nothing", () => {
+    expect(
+      collectChangeSubscribers([fakePlugin("aws", false)], {
+        environment: "prod",
+        entities: entitiesFor("aws"),
+      }),
+    ).toEqual([]);
+  });
+
+  test("a lexicon with the seam but no declared entities is skipped rather than handed an empty scope", () => {
+    expect(
+      collectChangeSubscribers([fakePlugin("k8s", true)], {
+        environment: "prod",
+        entities: new Map(),
+      }),
+    ).toEqual([]);
+  });
+
+  test("binds the environment, cwd and this lexicon's own entity slice", async () => {
+    const plugin = fakePlugin("k8s", true);
+    let seen: Record<string, unknown> | undefined;
+    plugin.subscribeChanges = async (options) => {
+      seen = options as unknown as Record<string, unknown>;
+      return { close: async () => {} };
+    };
+
+    const entities = new Map([
+      ["k8s", new Map([["web", { entityType: "K8s::Apps::Deployment", props: {} }]])],
+      ["aws", new Map([["bucket", { entityType: "AWS::S3::Bucket", props: {} }]])],
+    ]);
+    const subscribers = collectChangeSubscribers([plugin], { environment: "prod", cwd: "/proj", entities });
+    expect(subscribers).toHaveLength(1);
+    expect(subscribers[0].lexicon).toBe("k8s");
+
+    const controller = new AbortController();
+    const onChange = () => {};
+    const onError = () => {};
+    await subscribers[0].subscribe({ onChange, onError, signal: controller.signal });
+    expect(seen!.environment).toBe("prod");
+    expect(seen!.cwd).toBe("/proj");
+    expect(seen!.onChange).toBe(onChange);
+    expect(seen!.signal).toBe(controller.signal);
+    // This lexicon's slice only: aws's bucket is not in scope for k8s.
+    expect([...(seen!.entities as Map<string, unknown>).keys()]).toEqual(["web"]);
+  });
+});

package/src/cli/plugins.ts

@@ -114,6 +114,45 @@ export function collectBuildRootContributors(
     .map((plugin) => (ctx) => plugin.buildRoots!({ projectRoot, config, entities: ctx?.entities }));
 }
 
+/**
+ * Bind each loaded plugin's `subscribeChanges` seam (#1981) to one environment
+ * and its declared entities, producing the `ChangeSubscriber` list `chant
+ * operator`'s loop takes, in the same extract-then-thread shape
+ * {@link collectBuildRootContributors} uses, and for the same reason: core's
+ * operator must not import plugins.
+ *
+ * Plugins without the seam contribute nothing, so a project whose lexicons all
+ * lack it gets a loop that is exactly the timer it always was. `entities` is
+ * the per-lexicon slice of a build's declared entities, which is the bound on
+ * what a subscription may watch; a lexicon with no declared entities is
+ * skipped rather than handed an empty scope to widen.
+ */
+export function collectChangeSubscribers(
+  plugins: readonly LexiconPlugin[] | undefined,
+  options: {
+    environment: string;
+    cwd?: string;
+    /** Declared entities per lexicon name, from a build. */
+    entities: Map<string, Map<string, { entityType: string; props: Record<string, unknown> }>>;
+  },
+): Array<import("../op/operator").ChangeSubscriber> {
+  return (plugins ?? [])
+    .filter((plugin) => typeof plugin.subscribeChanges === "function")
+    .filter((plugin) => (options.entities.get(plugin.name)?.size ?? 0) > 0)
+    .map((plugin) => ({
+      lexicon: plugin.name,
+      subscribe: (ctx) =>
+        plugin.subscribeChanges!({
+          environment: options.environment,
+          ...(options.cwd ? { cwd: options.cwd } : {}),
+          entities: options.entities.get(plugin.name),
+          onChange: ctx.onChange,
+          onError: ctx.onError,
+          signal: ctx.signal,
+        }),
+    }));
+}
+
 /**
  * Load plugins for all detected lexicon names.
  * Calls `init()` on each plugin if present.

package/src/cli/registry.ts

@@ -40,6 +40,20 @@ export interface ParsedArgs {
   profile?: string;
   /** `chant run` — emit the structured OpRunResult as JSON on stdout. */
   json?: boolean;
+  /**
+   * `chant run <op> --gated-exit <code>` (#2243) — the process exit code a
+   * run that stopped at an unapproved gate returns, instead of the default 3.
+   *
+   * Only the gated outcome is remapped. A run that fails still returns 1 and a
+   * run that completes still returns 0, so `--gated-exit 0` on a CI job means
+   * "a pending approval is not a broken build" and nothing more. The `--json`
+   * payload is untouched by it: the record still says `status: "gated"` and
+   * still carries the gate and the `chant approve` line, so a job that maps the
+   * code to success can still tell the two apart.
+   *
+   * Accepts 0-255 (a POSIX exit status). Anything else is refused by name.
+   */
+  gatedExit?: number;
   /**
    * `chant run --components <name|all> --progress-json` (local executor) —
    * stream one NDJSON `RunProgressEvent` (../../components/run-progress.ts)

package/src/components/README.md

@@ -50,7 +50,7 @@ adopting chant.
   be a nested `Phase`, which is how fan-out (e.g. a Neo4j cluster seeding one
   node then rolling through the rest) is expressed as composition rather than
   orchestrator knowledge.
-- **Gates** — a distinct step shape (`kind: "gate"`, `signalName`) for a human
+- **Gates** — a distinct step shape (`kind: "gate"`, `gate`) for a human
   approval, decided against the gate ledger: a run that reaches one with no
   resolution stops there with status `gated` and the pending fact recorded.
 - **Wiring reference forms**, all resolved by the graph, never by orchestrator
@@ -89,7 +89,7 @@ Lambda function. `component-schema.test.ts` validates every fixture against
 `component.schema.json` with [ajv](https://ajv.js.org/) (`ajv/dist/2020` — the
 draft 2020-12 build) and exercises the schema's negative cases (missing
 required fields, malformed wiring references, an invalid archetype, a gate
-missing `signalName`, and so on).
+naming neither `gate` nor its deprecated `signalName` spelling, and so on).
 
 ## Typed authoring form (`component.ts`, #560)
 

package/src/components/__fixtures__/neo4j-fanout.json

@@ -16,7 +16,7 @@
     {
       "phase": "Node 1",
       "steps": [
-        { "kind": "gate", "signalName": "approve-neo4j-node-1", "description": "Confirm the seed node is healthy before rolling to node 1", "timeout": "24h" },
+        { "kind": "gate", "gate": "approve-neo4j-node-1", "description": "Confirm the seed node is healthy before rolling to node 1", "timeout": "24h" },
         { "kind": "cfn-deploy", "template": "archive:neo4j-1.template.json" },
         { "kind": "code-deploy", "instance": 1, "revision": "@Seed.templateUri" },
         { "kind": "wait-cluster-healthy", "quorum": true }

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

@@ -428,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", () => {
@@ -443,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", () => {
@@ -457,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" });
   });
 });
 
@@ -592,7 +603,7 @@ describe("runComponents", () => {
     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" }] },
       ] };`,
     );

package/src/components/cli-support.ts

@@ -33,11 +33,13 @@ import {
   DependencyCycleError,
   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";
@@ -319,13 +321,16 @@ function toDriverComponent(component: { name: string; dependsOn: string[]; deplo
  * 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]);

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,18 +160,31 @@
       }
     },
 
+    "GateName": {
+      "type": "string",
+      "minLength": 1,
+      "description": "A gate's name, on either of the two keys that may carry it."
+    },
+
     "Gate": {
       "type": "object",
       "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", "signalName"],
+      "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" },
-        "signalName": {
-          "type": "string",
-          "minLength": 1,
+        "gate": {
+          "$ref": "#/$defs/GateName",
           "description": "The gate's name — what `chant approve <component> <gate>` resolves."
         },
+        "signalName": {
+          "$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",
           "description": "Duration string bounding the wait, e.g. \"48h\". Default: \"48h\"."

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` — a human approval decided against the gate ledger; the run stops here with status `gated` until `chant approve` has answered it. */
-export interface Gate {
+/** Everything on a component gate step except the key that names it. */
+export interface GateBase {
   kind: "gate";
-  signalName: string;
   /** 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-
@@ -171,8 +191,8 @@ export function phase(name: string, steps: Array<Step | Gate | Phase>, 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(signalName: string, opts?: { timeout?: string; description?: string }): Gate {
-  return { kind: "gate", signalName, ...opts };
+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", () => {

package/src/components/driver.test.ts

@@ -217,7 +217,7 @@ describe("runComponentDeploy — gate as fact (#2119)", () => {
     name: "neo4j-cluster",
     deploy: [
       { phase: "Prepare", steps: [{ kind: "cfn-deploy" }] },
-      { phase: "Node 1", steps: [{ kind: "gate", signalName: "approve-node-1" }, { kind: "code-deploy" }] },
+      { phase: "Node 1", steps: [{ kind: "gate", gate: "approve-node-1" }, { kind: "code-deploy" }] },
     ],
     rollback: [{ phase: "Undo", steps: [{ kind: "cfn-deploy" }] }],
   });
@@ -259,6 +259,25 @@ describe("runComponentDeploy — gate as fact (#2119)", () => {
     ]);
   });
 
+  // #2202: `signalName` was the key that named a component gate through 0.58.0
+  // and is still read, so a component on the old key gates identically.
+  it("still reads a gate step's deprecated `signalName` key", async () => {
+    const { registry } = registryWithCalls();
+    const legacy: DriverComponent = {
+      name: "neo4j-cluster",
+      deploy: [{ phase: "Node 1", steps: [{ kind: "gate", signalName: "approve-node-1" }, { kind: "code-deploy" }] }],
+    };
+    const port = memoryGateLedgerPort();
+    const result = await runComponentDeploy(
+      legacy, { env: "dev", component: "neo4j-cluster" }, registry, {}, undefined,
+      { port, now: NOW },
+    );
+
+    expect(result.status).toBe("gated");
+    expect(result.gate).toMatchObject({ op: "neo4j-cluster", gate: "approve-node-1" });
+    expect(result.records.map((r) => r.kind)).toEqual(["gate:approve-node-1", "code-deploy"]);
+  });
+
   it("a resolution newer than the pending fact passes the gate and carries the approver", async () => {
     const { registry, calls } = registryWithCalls();
     const port = memoryGateLedgerPort({

package/src/components/driver.ts

@@ -48,6 +48,7 @@
 
 import { topoSort } from "../codegen/topo-sort";
 import { evaluateGate, gitGateLedgerPort, type GateLedgerPort } from "../op/gate";
+import { gateName } from "../op/gate-name";
 import type { PendingGateRecord } from "../lifecycle/gate-ledger";
 import type { CapabilityRegistry, DeployContext } from "./capability";
 import type { RunProgressEvent, RunProgressStatus } from "./run-progress";
@@ -68,10 +69,16 @@ export interface DriverStep {
   [param: string]: unknown;
 }
 
-/** A gate step — a human approval, decided against the gate ledger when the run reaches it (schema `Gate`). */
+/**
+ * A gate step — a human approval, decided against the gate ledger when the run
+ * reaches it (schema `Gate`). The name is on `gate`; `signalName` is the
+ * deprecated spelling (#2202), so read the name through `gateName()`.
+ */
 export interface DriverGate {
   kind: "gate";
-  signalName: string;
+  gate?: string;
+  /** @deprecated Renamed to `gate` in #2202. Accepted through 0.59.0, removed in 0.60.0. */
+  signalName?: string;
   timeout?: string;
   description?: string;
 }
@@ -444,12 +451,12 @@ async function runPhase(
       const start = Date.now();
       const check = await evaluateGate(gates.port, {
         op: ctx.component,
-        gate: gate.signalName,
+        gate: gateName(gate),
         ...(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}` };
+      const base = { component: ctx.component, phase: phaseDef.phase, kind: `gate:${gateName(gate)}` };
       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))) {
@@ -462,7 +469,7 @@ async function runPhase(
         status: "ok" as const,
         durationMs: Date.now() - start,
         approval: {
-          gate: gate.signalName,
+          gate: gateName(gate),
           resolvedBy: check.resolution.resolvedBy,
           timestamp: check.resolution.timestamp,
           ...(check.resolution.url ? { url: check.resolution.url } : {}),

package/src/components/pilots/neo4j-fanout.pilot.ts

@@ -31,7 +31,7 @@ interface Neo4jInstanceConfig {
    */
   health: { size: number } | { quorum: true };
   /** Optional human gate placed before this instance's steps (rolling instances only, never the seed). */
-  approval?: { signalName: string; description: string; timeout: string };
+  approval?: { gate: string; description: string; timeout: string };
 }
 
 const SEED: Neo4jInstanceConfig = {
@@ -55,7 +55,7 @@ const FOLLOWERS: Neo4jInstanceConfig[] = [
     template: "archive:neo4j-1.template.json",
     health: { quorum: true },
     approval: {
-      signalName: "approve-neo4j-node-1",
+      gate: "approve-neo4j-node-1",
       description: "Confirm the seed node is healthy before rolling to node 1",
       timeout: "24h",
     },
@@ -71,7 +71,7 @@ const FOLLOWERS: Neo4jInstanceConfig[] = [
 /** Build one instance's mini-composition phase — the unit that repeats N times for an N-node cluster. */
 function instancePhase(instance: Neo4jInstanceConfig): Phase {
   const steps = [
-    ...(instance.approval ? [gate(instance.approval.signalName, instance.approval)] : []),
+    ...(instance.approval ? [gate(instance.approval.gate, instance.approval)] : []),
     { kind: "cfn-deploy", template: instance.template },
     { kind: "code-deploy", instance: instance.index, revision: "@Seed.templateUri" },
     { kind: "wait-cluster-healthy", ...instance.health },

package/src/components/verbs/run-agent.test.ts

@@ -287,6 +287,25 @@ describe("run() — failed turn: non-zero exit surfaces as status \"failed\", ne
   });
 });
 
+describe("RunAgentTurn[\"status\"] is exactly the two states run() produces (#2072)", () => {
+  it("has no third member: a switch handling only \"completed\" and \"failed\" compiles with no default needed", () => {
+    // Compile-time exhaustiveness check, not a runtime assertion: if a third
+    // member were ever added back to the union (e.g. "interrupted"), this
+    // switch would stop being exhaustive and `tsc` would reject the missing
+    // case, since `identity`'s return type has no branch left to satisfy it.
+    const identity = (status: RunAgentOutput["turn"]["status"]): "completed" | "failed" => {
+      switch (status) {
+        case "completed":
+          return "completed";
+        case "failed":
+          return "failed";
+      }
+    };
+    expect(identity("completed")).toBe("completed");
+    expect(identity("failed")).toBe("failed");
+  });
+});
+
 describe("collectArtifacts — only a \"not found\" read means \"no artifact\"; a genuine infra failure propagates (#1942 review finding 2)", () => {
   it("branch A: readFile rejecting with the sprite-fs \"not found\" shape resolves to empty artifacts.files, not a run() rejection", async () => {
     const { sprites } = makeFakeSprites(succeed); // never writes /work/output — readFile hits the fake's "not found" branch

package/src/components/verbs/run-agent.ts

@@ -149,12 +149,6 @@
  *    snapshot folded into a `BuildArchiveManifest` entry (./build-archive.ts)
  *    remains an open question, as does `artifacts.diff`, which `run()` never
  *    populates (the real Sprites API has no built-in diff endpoint).
- *  - Interrupted turns — `turn.status: "interrupted"` stays in the type but
- *    is unreachable from this implementation: any `sprites.exec` rejection
- *    (including one caused by an aborted signal) propagates as a genuine
- *    `run()` failure rather than being classified as an interrupted turn.
- *    Distinguishing "deadline hit mid-run" from "the sprite backend errored"
- *    well enough to surface `"interrupted"` safely is left for #1944.
  *
  * **#1943 (this revision) resolved the transcript-hash basis and
  * sign/verify-gate interop, closing #1941's open "transcript hash basis"
@@ -285,7 +279,7 @@ export interface RunAgentInput {
 
 /** Mirrors fountain's `Turn` shape (`status`/`exit_code`/`started_at`/`ended_at`), even though the turn itself runs on a chant-owned sprite rather than a fountain-managed `Sandbox`. */
 export interface RunAgentTurn {
-  status: "completed" | "failed" | "interrupted";
+  status: "completed" | "failed";
   exitCode: number | null;
   startedAt: string;
   endedAt: string | null;

package/src/detectLexicon.ts

@@ -1,5 +1,22 @@
 import { readFile } from "node:fs/promises";
 
+/**
+ * The message {@link detectLexicons} throws when a scan of the project's
+ * source files turns up no `@intentius/chant-lexicon-*` import at all.
+ *
+ * Named (chant #2222) because one caller has to tell this failure apart from
+ * every other one: `chant lint` reports a lexicon it cannot resolve as an
+ * error diagnostic, but "this directory declares no lexicon and imports none"
+ * is not that. It is a project that lints under the core rules alone, and it
+ * has always been allowed to. See {@link isNoLexiconDetected}.
+ */
+export const NO_LEXICON_DETECTED_MESSAGE = "No lexicon detected in infrastructure files";
+
+/** Whether `error` is the {@link NO_LEXICON_DETECTED_MESSAGE} failure. */
+export function isNoLexiconDetected(error: unknown): boolean {
+  return error instanceof Error && error.message === NO_LEXICON_DETECTED_MESSAGE;
+}
+
 /**
  * Detects which lexicons are being used by analyzing import statements
  * in the provided infrastructure files. Matches any `@intentius/chant-lexicon-*` package.
@@ -32,7 +49,7 @@ export async function detectLexicons(files: string[]): Promise<string[]> {
 
   // Validate results
   if (detectedLexicons.size === 0) {
-    throw new Error("No lexicon detected in infrastructure files");
+    throw new Error(NO_LEXICON_DETECTED_MESSAGE);
   }
 
   return Array.from(detectedLexicons);

package/src/discovery/fold-import.test.ts

@@ -1276,7 +1276,7 @@ describe("tryFoldFile — registered authoring helpers (#1082)", () => {
               stack: "web",
               inputs: { pVpcId: { stackOutput: { stack: "shared-foundation", name: "oVpcId" } } },
             },
-            { kind: "gate", signalName: "approve", timeout: "24h" },
+            { kind: "gate", gate: "approve", timeout: "24h" },
           ],
         },
       ],

package/src/fold/foldable-helpers.ts

@@ -123,7 +123,7 @@ export const FOLDABLE_AUTHORING_HELPERS: readonly FoldableHelperDef[] = [
   {
     name: "gate",
     module: "components/component.ts, op/builders.ts",
-    note: "Returns a plain `{ kind: 'gate', signalName, ... }` object literal built from its arguments.",
+    note: "Returns a plain `{ kind: 'gate', gate, ... }` object literal built from its arguments.",
   },
   {
     name: "activity",