@intentius/chant 0.58.0 → 0.60.0

package/src/op/change-signal.ts

@@ -0,0 +1,169 @@
+/**
+ * The wake gate between a substrate's change signal and `chant operator`'s
+ * sleep (#1981, epic #1487).
+ *
+ * A lexicon that implements `subscribeChanges` (`../lexicon.ts`) can say
+ * "something moved". This module is everything the loop does with that: it
+ * shortens the current sleep, at most once per floor. It is deliberately the
+ * only place a signal touches, so the rule that a signal is a trigger and
+ * never a fact is a property of the code rather than a convention. Nothing
+ * here has a parameter, a return value or a field that could carry what
+ * changed.
+ *
+ * ## Backpressure: the floor
+ *
+ * A watch on a busy namespace is not a trickle. A rollout, a Job sweep or a
+ * controller resyncing its whole world produces hundreds of events in a
+ * second, and each one is a truthful "something moved". Waking a tick per
+ * event would turn a convergence loop into a load generator pointed at the
+ * cluster it is meant to be watching.
+ *
+ * So the gate coalesces. Signals are collapsed into a single pending flag, and
+ * a pending flag wakes the sleep no earlier than {@link
+ * ChangeSignalGateOptions.floorMs} after the last round *started*. A storm of
+ * a thousand signals inside one floor window costs exactly one early wake, and
+ * a substrate that never stops sending settles into ticking on the floor
+ * rather than on the interval, which is the fastest the loop is ever allowed
+ * to run.
+ *
+ * The floor is measured from the start of the last round, not from the last
+ * signal, so a steady stream can never push the wake further out (that would
+ * be a debounce, and a debounce starves: the busier the cluster, the later the
+ * tick). Measuring from the round start makes the guarantee a rate limit,
+ * never more than one signal-driven tick per floor, which is the property the
+ * loop actually needs.
+ */
+
+/**
+ * The shortest gap between two rounds a change signal may produce. Signals
+ * arriving inside this window of the last round's start are coalesced into one
+ * wake at the end of it.
+ *
+ * Five seconds: long enough that a rollout's event storm costs one tick rather
+ * than dozens, short enough that "wakes within a second or so of a change"
+ * holds for the quiet case a signal exists for. The timer
+ * (`DEFAULT_OPERATOR_INTERVAL_MS`, 60s) is unchanged and remains the ceiling.
+ */
+export const DEFAULT_SIGNAL_FLOOR_MS = 5_000;
+
+/** Why {@link ChangeSignalGate.wait} returned. */
+export type WakeReason =
+  /** The full interval elapsed. An ordinary timer-driven round. */
+  | "timer"
+  /** A substrate signalled and the floor had passed. An early round. */
+  | "signal"
+  /** The operator is stopping. */
+  | "aborted";
+
+export interface ChangeSignalGateOptions {
+  /** @default DEFAULT_SIGNAL_FLOOR_MS */
+  floorMs?: number;
+  /** Injectable clock, for tests. @default Date.now */
+  now?: () => number;
+}
+
+/**
+ * One operator loop's wake gate. Not reusable across loops: it carries the
+ * time the current loop last started a round, which is what the floor is
+ * measured from.
+ */
+export interface ChangeSignalGate {
+  /**
+   * A substrate said something moved. Takes nothing and returns nothing, and
+   * that is the enforcement of "a trigger, never a fact": there is no
+   * argument for a watch event to ride in on.
+   *
+   * Safe to call at any time, including while no `wait` is in flight (the flag
+   * is remembered and honoured by the next one) and after the loop has
+   * stopped (it does nothing).
+   */
+  signal(): void;
+  /** The loop is starting a round now. Resets the pending flag and the floor. */
+  roundStarted(): void;
+  /**
+   * Sleep up to `intervalMs`, resolving early when a signal has passed the
+   * floor. Resolves rather than throws on abort, like the timer-only sleep it
+   * replaces, so Ctrl-C never surfaces as a loop failure.
+   */
+  wait(intervalMs: number, abortSignal?: AbortSignal): Promise<WakeReason>;
+  /** How many signals have arrived, coalesced or not. Diagnostics and tests. */
+  readonly signalCount: number;
+  /** How many of those actually shortened a sleep. Diagnostics and tests. */
+  readonly wakeCount: number;
+}
+
+export function createChangeSignalGate(options: ChangeSignalGateOptions = {}): ChangeSignalGate {
+  const floorMs = options.floorMs ?? DEFAULT_SIGNAL_FLOOR_MS;
+  const now = options.now ?? (() => Date.now());
+
+  let pending = false;
+  let lastRoundAt = now();
+  let signalCount = 0;
+  let wakeCount = 0;
+  /** Set only while a `wait` is in flight. */
+  let arm: (() => void) | undefined;
+
+  return {
+    get signalCount() {
+      return signalCount;
+    },
+    get wakeCount() {
+      return wakeCount;
+    },
+
+    signal() {
+      signalCount++;
+      pending = true;
+      arm?.();
+    },
+
+    roundStarted() {
+      lastRoundAt = now();
+      pending = false;
+    },
+
+    wait(intervalMs: number, abortSignal?: AbortSignal): Promise<WakeReason> {
+      return new Promise<WakeReason>((resolve) => {
+        if (abortSignal?.aborted) return resolve("aborted");
+
+        let settled = false;
+        let floorTimer: ReturnType<typeof setTimeout> | undefined;
+
+        const finish = (reason: WakeReason) => {
+          if (settled) return;
+          settled = true;
+          clearTimeout(intervalTimer);
+          if (floorTimer) clearTimeout(floorTimer);
+          abortSignal?.removeEventListener("abort", onAbort);
+          arm = undefined;
+          if (reason === "signal") wakeCount++;
+          resolve(reason);
+        };
+
+        const intervalTimer = setTimeout(() => finish("timer"), intervalMs);
+        const onAbort = () => finish("aborted");
+        abortSignal?.addEventListener("abort", onAbort, { once: true });
+
+        // A pending signal wakes the sleep the moment the floor has passed,
+        // and not one moment earlier. `remaining` is measured from the last
+        // round's start, so repeated signals inside the window collapse onto
+        // the same deadline instead of pushing it out.
+        const consider = () => {
+          if (settled || !pending) return;
+          const remaining = lastRoundAt + floorMs - now();
+          if (remaining <= 0) return finish("signal");
+          if (floorTimer) return; // already waiting out this window
+          floorTimer = setTimeout(() => {
+            floorTimer = undefined;
+            consider();
+          }, remaining);
+        };
+
+        arm = consider;
+        // A signal that arrived between rounds, while nothing was sleeping,
+        // is honoured here rather than lost.
+        consider();
+      });
+    },
+  };
+}

package/src/op/composites/apply-op.ts

@@ -30,7 +30,7 @@
  *   env: "prod",
  *   target: "kubectl",
  *   delete: "gated",
- *   gate: { signalName: "approve-apply", description: "Approve prod apply with deletes" },
+ *   gate: { gate: "approve-apply", description: "Approve prod apply with deletes" },
  * });
  * ```
  *
@@ -38,6 +38,7 @@
  */
 
 import { Op, phase, activity, gate } from "../builders";
+import { gateName } from "../gate-name";
 import type { OpResource } from "../resource";
 import { defaultOutput, hasNativeRollback, type ApplyTarget, type DeleteMode } from "../activities/apply";
 
@@ -69,11 +70,20 @@ export interface ApplyOpConfig {
   effects?: "gated";
   /**
    * Approval gate before the apply. Implied when `delete: "gated"`; may also be
-   * set explicitly. Omit `signalName` to default to `approve-<name>`. The gate
+   * set explicitly. Omit `gate` to default to `approve-<name>`. The gate
    * is resolved by `chant approve` on the ledger (#2119), which the next run
    * reads; nothing waits in the meantime.
+   *
+   * `signalName` is the key `gate` carried through 0.58.0 (#2202): still read,
+   * removed in 0.60.0.
    */
-  gate?: { signalName?: string; timeout?: string; description?: string };
+  gate?: {
+    gate?: string;
+    /** @deprecated Renamed to `gate` in #2202. Accepted through 0.59.0, removed in 0.60.0. */
+    signalName?: string;
+    timeout?: string;
+    description?: string;
+  };
   /**
    * Saga-style rollback on partial apply failure, run as an `onFailure` phase.
    *
@@ -129,7 +139,7 @@ export function ApplyOp(config: ApplyOpConfig): ApplyOpResources {
   if (gated) {
     phases.push(
       phase("Approve", [
-        gate(config.gate?.signalName ?? `approve-${config.name}`, {
+        gate(gateName(config.gate ?? {}) || `approve-${config.name}`, {
           ...(config.gate?.timeout ? { timeout: config.gate.timeout } : {}),
           description:
             config.gate?.description ??

package/src/op/composites/composites.test.ts

@@ -165,21 +165,34 @@ describe("ApplyOp: gating + deletes", () => {
     expect(phases.map((p) => p.name)).toEqual(["Build", "Plan", "Approve", "Apply"]);
     const gateStep = (phases[2].steps as Array<Record<string, unknown>>)[0];
     expect(gateStep.kind).toBe("gate");
-    expect(gateStep.signalName).toBe("approve-p");
+    expect(gateStep.gate).toBe("approve-p");
   });
 
   test("explicit gate config is honored", () => {
     const { op } = ApplyOp({
       name: "p",
       env: "prod",
-      gate: { signalName: "go", description: "ship it" },
+      gate: { gate: "go", description: "ship it" },
     });
     const phases = getProps(op).phases as Array<Record<string, unknown>>;
     const gateStep = (phases[2].steps as Array<Record<string, unknown>>)[0];
-    expect(gateStep.signalName).toBe("go");
+    expect(gateStep.gate).toBe("go");
     expect(gateStep.description).toBe("ship it");
   });
 
+  // #2202: the gate config's key is `gate`; `signalName` is read through 0.59.0.
+  test("the deprecated `signalName` key on the gate config still names the gate", () => {
+    const { op } = ApplyOp({
+      name: "p",
+      env: "prod",
+      gate: { signalName: "go", description: "ship it" },
+    });
+    const phases = getProps(op).phases as Array<Record<string, unknown>>;
+    const gateStep = (phases[2].steps as Array<Record<string, unknown>>)[0];
+    expect(gateStep.gate).toBe("go");
+    expect(gateStep.signalName).toBeUndefined();
+  });
+
   test("deleteMode flows into the nativeApply step", () => {
     const { op } = ApplyOp({ name: "p", env: "prod", delete: "owned-only" });
     const phases = getProps(op).phases as Array<Record<string, unknown>>;
@@ -301,7 +314,7 @@ describe("ApplyOp: effects gated (#1834, #1703 decision 6)", () => {
     expect(phases.map((p) => p.name)).toEqual(["Build", "Plan", "Approve", "Apply"]);
     const gateStep = (phases[2].steps as Array<Record<string, unknown>>)[0];
     expect(gateStep.kind).toBe("gate");
-    expect(gateStep.signalName).toBe("approve-p");
+    expect(gateStep.gate).toBe("approve-p");
     expect(gateStep.description).toBe("Approve apply to prod (delete mode: never, effects: gated)");
   });
 

package/src/op/composites/reconcile-op.ts

@@ -60,15 +60,18 @@ export function ReconcileOp(config: ReconcileOpConfig): ReconcileOpResources {
   const onDrift = config.onDrift ?? "pull-request";
   const owned = config.scope?.owned ?? false;
 
-  // The reconcile's headline output is the opened PR (or issue) URL. Expose it as
-  // an outcome attribute so it prints in `chant run` and lands on the ledger.
-  // `report` mode opens nothing, so it has no URL outcome.
+  // The reconcile's headline output is the opened PR (or issue, or the comment
+  // it posted on the triggering pull request) URL. Expose it as an outcome
+  // attribute so it prints in `chant run` and lands on the ledger. `report`
+  // mode opens nothing, so it has no URL outcome.
   const reconcileOutcome =
     onDrift === "pull-request"
       ? { name: "PR", from: "prUrl" }
       : onDrift === "issue"
         ? { name: "Issue", from: "issueUrl" }
-        : undefined;
+        : onDrift === "comment"
+          ? { name: "Comment", from: "commentUrl" }
+          : undefined;
 
   const op = Op({
     name: config.name,

package/src/op/effect-step.test.ts

@@ -58,7 +58,7 @@ describe("effect() builder", () => {
       inputs: { file: "seed.sql", version: 3 },
     });
     expect(s.expectation).toBe(receiptExpectation(seeded));
-    expect(s.steps.map((n) => (n.kind === "activity" ? n.fn : n.signalName))).toEqual(["shellCmd"]);
+    expect(s.steps.map((n) => (n.kind === "activity" ? n.fn : n.gate))).toEqual(["shellCmd"]);
   });
 
   test("existence receipts always get the constant expectation, reference inputs or not", () => {
@@ -83,7 +83,7 @@ describe("effect() builder", () => {
 
   test("preserves authored order and nested gates", () => {
     const s = effect(seeded, [
-      { kind: "gate", signalName: "approve-seed" },
+      { kind: "gate", gate: "approve-seed" },
       step("shellCmd", { cmd: "seed" }),
     ]);
     expect(s.steps.map((n) => n.kind)).toEqual(["gate", "activity"]);
@@ -288,7 +288,7 @@ describe("runOpLocally — effect steps", () => {
       name: "gated",
       overview: "",
       phases: [
-        phase("Seed", [effect(seeded, [{ kind: "gate", signalName: "approve-seed" }, step("runSeed")])]),
+        phase("Seed", [effect(seeded, [{ kind: "gate", gate: "approve-seed" }, step("runSeed")])]),
       ],
     };
     const { store } = memStore();

package/src/op/gate-name.test.ts

@@ -0,0 +1,65 @@
+/**
+ * The `signalName` -> `gate` rename (#2202) and the one-version bridge that
+ * keeps the old key readable through 0.59.0.
+ */
+import { describe, it, expect } from "vitest";
+import { gateName, usesDeprecatedGateKey, opUsesDeprecatedGateKey } from "./gate-name";
+import type { OpConfig } from "./types";
+
+describe("gateName", () => {
+  it("reads the new key", () => {
+    expect(gateName({ gate: "approve-prod" })).toBe("approve-prod");
+  });
+
+  it("falls back to the deprecated key", () => {
+    expect(gateName({ signalName: "approve-prod" })).toBe("approve-prod");
+  });
+
+  it("prefers the new key when a step somehow carries both", () => {
+    expect(gateName({ gate: "new", signalName: "old" })).toBe("new");
+  });
+});
+
+describe("usesDeprecatedGateKey", () => {
+  it("is true only when the new key is absent", () => {
+    expect(usesDeprecatedGateKey({ signalName: "old" })).toBe(true);
+    expect(usesDeprecatedGateKey({ gate: "new" })).toBe(false);
+    expect(usesDeprecatedGateKey({ gate: "new", signalName: "old" })).toBe(false);
+    expect(usesDeprecatedGateKey({})).toBe(false);
+  });
+});
+
+describe("opUsesDeprecatedGateKey", () => {
+  const op = (phases: OpConfig["phases"], onFailure?: OpConfig["phases"]): OpConfig =>
+    ({ name: "x", overview: "x", phases, ...(onFailure ? { onFailure } : {}) }) as OpConfig;
+
+  it("finds a gate on the old key in a plain phase", () => {
+    expect(opUsesDeprecatedGateKey(op([{ name: "Approve", steps: [{ kind: "gate", signalName: "go" }] }]))).toBe(true);
+  });
+
+  it("finds one nested inside an effect step", () => {
+    const config = op([
+      {
+        name: "Seed",
+        steps: [
+          {
+            kind: "effect",
+            receipt: { name: "seeded", effect: "db-seed", flavor: "hash", inputs: { file: "seed.sql" } },
+            steps: [{ kind: "gate", signalName: "go" }],
+          },
+        ],
+      },
+    ]);
+    expect(opUsesDeprecatedGateKey(config)).toBe(true);
+  });
+
+  it("finds one in an onFailure phase", () => {
+    expect(
+      opUsesDeprecatedGateKey(op([{ name: "Apply", steps: [] }], [{ name: "Undo", steps: [{ kind: "gate", signalName: "go" }] }])),
+    ).toBe(true);
+  });
+
+  it("is false for an Op on the new key", () => {
+    expect(opUsesDeprecatedGateKey(op([{ name: "Approve", steps: [{ kind: "gate", gate: "go" }] }]))).toBe(false);
+  });
+});

package/src/op/gate-name.ts

@@ -0,0 +1,60 @@
+/**
+ * The gate step's name field, and the one-version bridge for the key it used
+ * to carry (chant #2202).
+ *
+ * A gate is a fact on the gate ledger, not a channel: since #2119 nothing is
+ * running and nothing is signalled, so the field that names a gate is called
+ * `gate` — the same word `chant approve <op> <gate>` takes on the command
+ * line. It was called `signalName` through 0.58.0.
+ *
+ * `signalName` is still read, on `GateStep`, on the component `Gate` step and
+ * on the composites' gate options, and a build that sees only the old key
+ * warns once. It goes away in 0.60.0: delete this module's
+ * {@link DEPRECATED_GATE_KEY_WARNING}, {@link usesDeprecatedGateKey}, the
+ * `signalName` branch of {@link gateName}, the optional `signalName` fields
+ * that call it, and the schema's `oneOf` once that release is out, leaving
+ * `gate` as the only key.
+ */
+
+import type { OpConfig, PhaseDefinition, StepDefinition } from "./types";
+
+/** Either spelling of a gate step's name. `gate` since #2202; `signalName` through 0.59.0. */
+export interface GateNamed {
+  gate?: string;
+  /** @deprecated Renamed to `gate` in #2202. Accepted through 0.59.0, removed in 0.60.0. */
+  signalName?: string;
+}
+
+/**
+ * The gate's name, from whichever key carries it. One place reads the old key,
+ * so removing the bridge is a one-file edit rather than a sweep.
+ */
+export function gateName(step: GateNamed): string {
+  return step.gate ?? step.signalName ?? "";
+}
+
+/** True when a step names its gate only with the deprecated key. */
+export function usesDeprecatedGateKey(step: GateNamed): boolean {
+  return step.gate === undefined && typeof step.signalName === "string";
+}
+
+/** What a build prints once when it finds a gate step still using the old key. */
+export const DEPRECATED_GATE_KEY_WARNING =
+  'Gate steps still using "signalName": the key is now "gate" (chant #2202). ' +
+  '"signalName" is accepted through 0.59.0 and removed in 0.60.0.';
+
+/**
+ * True when any gate step in an Op's phases (main or `onFailure`, at any
+ * nesting depth inside an `effect()`) names itself only with the deprecated
+ * key. `chant build` calls this to warn once per build.
+ */
+export function opUsesDeprecatedGateKey(config: OpConfig): boolean {
+  const inStep = (step: StepDefinition): boolean => {
+    if (step.kind === "gate") return usesDeprecatedGateKey(step);
+    if (step.kind === "effect") return step.steps.some(inStep);
+    return false;
+  };
+  const inPhases = (phases: PhaseDefinition[] | undefined): boolean =>
+    (phases ?? []).some((p) => p.steps.some(inStep));
+  return inPhases(config.phases) || inPhases(config.onFailure);
+}

package/src/op/gate-summary.test.ts

@@ -0,0 +1,62 @@
+/**
+ * The pending-gate block a CI run leaves where people actually look (#2243),
+ * and the second surface GitLab needs for it (#2256).
+ *
+ * GitHub Actions, Forgejo Actions and Gitea all hand a step a markdown
+ * scratchpad through `GITHUB_STEP_SUMMARY`. GitLab CI has no equivalent at
+ * all — a job's surfaces are its log and its artifacts — so `CHANT_GATE_SUMMARY`
+ * names a path the generated GitLab job also declares under `artifacts:`. One
+ * more environment variable, the same block, still no API call and no token.
+ */
+
+import { mkdtempSync, readFileSync, existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, test, expect } from "vitest";
+import { gatedRunSummaryMarkdown, writeGatedRunSummary } from "./gate-summary";
+
+const summary = { op: "app-apply", gate: "approve-app-apply", expiresAt: "2026-09-08T00:00:00Z" };
+
+function tempPath(name: string): string {
+  return join(mkdtempSync(join(tmpdir(), "chant-gate-")), name);
+}
+
+describe("gatedRunSummaryMarkdown (#2243)", () => {
+  test("names the gate, the exact approve command and the ledger path", () => {
+    const md = gatedRunSummaryMarkdown(summary);
+    expect(md).toContain("Waiting on gate `approve-app-apply`");
+    expect(md).toContain("chant approve app-apply approve-app-apply --approver <you>");
+    expect(md).toContain("_gates/app-apply.jsonl");
+  });
+});
+
+describe("writeGatedRunSummary surfaces (#2243, #2256)", () => {
+  test("writes to GITHUB_STEP_SUMMARY where the forge sets one", () => {
+    const path = tempPath("step-summary.md");
+    expect(writeGatedRunSummary(summary, { GITHUB_STEP_SUMMARY: path })).toBe(path);
+    expect(readFileSync(path, "utf8")).toContain("approve-app-apply");
+  });
+
+  test("writes to CHANT_GATE_SUMMARY where the forge sets none — GitLab's artifact path", () => {
+    const path = tempPath("chant-gate-app-apply.md");
+    expect(writeGatedRunSummary(summary, { CHANT_GATE_SUMMARY: path })).toBe(path);
+    expect(readFileSync(path, "utf8")).toContain("chant approve app-apply approve-app-apply");
+  });
+
+  test("the forge's own variable wins when both are set", () => {
+    const forge = tempPath("step-summary.md");
+    const artifact = tempPath("chant-gate-app-apply.md");
+    expect(
+      writeGatedRunSummary(summary, { GITHUB_STEP_SUMMARY: forge, CHANT_GATE_SUMMARY: artifact }),
+    ).toBe(forge);
+    expect(existsSync(artifact)).toBe(false);
+  });
+
+  test("a run with neither variable writes nothing and reports nothing", () => {
+    expect(writeGatedRunSummary(summary, {})).toBeUndefined();
+  });
+
+  test("an unwritable path is swallowed: a decided run does not change outcome over a scratchpad", () => {
+    expect(writeGatedRunSummary(summary, { CHANT_GATE_SUMMARY: "/no/such/dir/gate.md" })).toBeUndefined();
+  });
+});

package/src/op/gate-summary.ts

@@ -0,0 +1,96 @@
+/**
+ * The pending-gate block a CI run leaves where people actually look (#2243).
+ *
+ * A gated run already prints the gate, the approve command and the expiry to
+ * stderr (`./local-output.ts`'s `renderHuman`). In CI that lands in a log
+ * nobody opens unless the run is red, which is exactly the run this stops
+ * being red. GitHub Actions, Forgejo Actions and Gitea all give a step a
+ * markdown scratchpad through `GITHUB_STEP_SUMMARY`, rendered at the top of
+ * the run page; anything else that sets the variable gets the same block.
+ *
+ * GitLab CI sets no such variable and has no step summary at all: a job's
+ * surfaces are its log and its artifacts (#2256). So `CHANT_GATE_SUMMARY`
+ * names a second path, which the generated GitLab job sets to a file it also
+ * declares under `artifacts:`. Same block, same rule, one more variable.
+ *
+ * That is the whole forge coupling: two environment variables, appended to
+ * whichever is set, and nothing at all when neither is. No API call, no
+ * token, no flag to turn it on.
+ */
+
+import { appendFileSync } from "node:fs";
+import { gateLedgerPath } from "../lifecycle/gate-ledger";
+import { approveCommand } from "./gate";
+
+/** What a gated run knows about the gate it stopped on. */
+export interface GatedRunSummary {
+  /** The Op (or component) the gate belongs to. */
+  op: string;
+  /** The gate's name — the second argument to `chant approve`. */
+  gate: string;
+  /** The gate's authored description, when it has one. */
+  description?: string;
+  /** ISO-8601 instant the pending fact ages out at. */
+  expiresAt?: string;
+  /** The approval surface the run resolved, when it knew one. */
+  url?: string;
+}
+
+/**
+ * The markdown block itself. Pure, so a test reads what CI would render
+ * without touching a file: op, gate, the exact `chant approve` line, and the
+ * ledger path the pending fact was appended to.
+ */
+export function gatedRunSummaryMarkdown(summary: GatedRunSummary): string {
+  const lines = [
+    `### Waiting on gate \`${summary.gate}\``,
+    "",
+    `Op \`${summary.op}\` reached a gate nobody has approved, recorded the pending fact, and stopped. Nothing failed.`,
+    "",
+  ];
+  if (summary.description) {
+    lines.push(summary.description, "");
+  }
+  lines.push(
+    "Approve it, then re-run this workflow:",
+    "",
+    "```",
+    `${approveCommand(summary.op, summary.gate)} --approver <you>`,
+    "```",
+    "",
+    `Ledger: \`${gateLedgerPath(summary.op)}\` on the \`chant/lifecycle\` branch.`,
+  );
+  if (summary.expiresAt) lines.push(`Expires: ${summary.expiresAt}`);
+  if (summary.url) lines.push(`Approve at: ${summary.url}`);
+  lines.push("");
+  return lines.join("\n");
+}
+
+/**
+ * Append {@link gatedRunSummaryMarkdown} to the file `GITHUB_STEP_SUMMARY`
+ * names, or, where the forge sets no such variable, the one
+ * `CHANT_GATE_SUMMARY` names (#2256) — when it is set and the file can be
+ * written.
+ *
+ * The forge's own variable wins where both are set: a step summary is
+ * rendered on the run page, an artifact has to be downloaded, and writing
+ * both would put the same block in two places on a forge that already shows
+ * one of them.
+ *
+ * Returns the path written, or `undefined` when there was nothing to write to.
+ * A write that fails is swallowed: a run that already decided its outcome must
+ * not turn into a different one because a CI scratchpad was read-only.
+ */
+export function writeGatedRunSummary(
+  summary: GatedRunSummary,
+  env: NodeJS.ProcessEnv = process.env,
+): string | undefined {
+  const path = env.GITHUB_STEP_SUMMARY || env.CHANT_GATE_SUMMARY;
+  if (!path) return undefined;
+  try {
+    appendFileSync(path, gatedRunSummaryMarkdown(summary));
+    return path;
+  } catch {
+    return undefined;
+  }
+}

package/src/op/index.ts

@@ -52,6 +52,8 @@ export { runOpLocally, parseDuration, OpRunFailure } from "./local-executor";
 export type { StepRecord, OpRunResult, RunOpOptions } from "./local-executor";
 export { evaluateGate, gitGateLedgerPort, memoryGateLedgerPort, approveCommand } from "./gate";
 export type { GateLedgerPort, GateCheck, GateCheckInput } from "./gate";
+export { gateName, usesDeprecatedGateKey, DEPRECATED_GATE_KEY_WARNING } from "./gate-name";
+export type { GateNamed } from "./gate-name";
 export { createLocalOpRuntime } from "./runtimes/local";
 export { runStateOf } from "./runtime";
 export type {
@@ -85,9 +87,14 @@ export type {
 } from "./converge-rule";
 export {
   discoverConvergeOps, runOperatorRound, runOperatorForever, formatRoundLine,
-  DEFAULT_OPERATOR_INTERVAL_MS,
+  formatSignalLine, DEFAULT_OPERATOR_INTERVAL_MS,
 } from "./operator";
-export type { OperatorTickEvent, OperatorRoundOptions, OperatorLoopOptions } from "./operator";
+export type {
+  OperatorTickEvent, OperatorRoundOptions, OperatorLoopOptions,
+  ChangeSubscriber, OperatorSignalEvent,
+} from "./operator";
+export { createChangeSignalGate, DEFAULT_SIGNAL_FLOOR_MS } from "./change-signal";
+export type { ChangeSignalGate, ChangeSignalGateOptions, WakeReason } from "./change-signal";
 export { classifyOpVerbClass, isGated } from "./op-verb-class";
 export type { OpVerbClass } from "./op-verb-class";
 export { takeProfileAndId } from "./builders";

package/src/op/local-executor.test.ts

@@ -284,7 +284,7 @@ describe("runOpLocally — gate as fact (#2119)", () => {
       phases: [
         { name: "P1", steps: [
           { kind: "activity", fn: "before" },
-          { kind: "gate", signalName: "approve-prod", description: "release manager signs off", timeout: "24h" },
+          { kind: "gate", gate: "approve-prod", description: "release manager signs off", timeout: "24h" },
           { kind: "activity", fn: "after" },
         ] },
         { name: "P2", steps: [{ kind: "activity", fn: "later" }] },
@@ -324,6 +324,21 @@ describe("runOpLocally — gate as fact (#2119)", () => {
     ]);
   });
 
+  // #2202: the gate step's name key is `gate`; `signalName` is read through
+  // 0.59.0, so a step still spelling it that way reaches the same ledger entry.
+  test("a gate step still using the deprecated `signalName` key names the same gate", async () => {
+    const { activities } = tracked();
+    const legacy = op({
+      phases: [{ name: "P1", steps: [{ kind: "gate", signalName: "approve-prod" }] }],
+    });
+    const port = memoryGateLedgerPort();
+    const result = await runOpLocally(legacy, activities, PROFILES, undefined, { gates: port, now: NOW });
+
+    expect(result.status).toBe("gated");
+    expect(result.gate).toMatchObject({ op: "test-op", gate: "approve-prod" });
+    expect(result.records.map((r) => r.fn)).toEqual(["gate:approve-prod"]);
+  });
+
   test("onFailure phases do not run on a gated run", async () => {
     const { calls, activities } = tracked();
     await runOpLocally(gatedOp(), activities, PROFILES, undefined, { gates: memoryGateLedgerPort(), now: NOW });