@intentius/chant 0.57.0 → 0.59.0

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.ts

@@ -0,0 +1,84 @@
+/**
+ * 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.
+ *
+ * That is the whole forge coupling: one environment variable, appended to
+ * when it is set, and nothing at all when it is not. 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, when the variable is set and the file can be written.
+ *
+ * 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;
+  if (!path) return undefined;
+  try {
+    appendFileSync(path, gatedRunSummaryMarkdown(summary));
+    return path;
+  } catch {
+    return undefined;
+  }
+}

package/src/op/gate.ts

@@ -0,0 +1,155 @@
+/**
+ * Gate-as-fact (#2119, epic #2114) — the one place that decides what happens
+ * when a run reaches a `gate`, shared by the Op executor
+ * (`./local-executor.ts`) and the component driver
+ * (`../components/driver.ts`) so the two can never drift.
+ *
+ * A gate used to be a wait, which meant a runtime that cannot wait had to
+ * refuse the whole op before its first step (`LocalGateUnsupportedError`,
+ * deleted with this). It is a fact now: the run reads the gate ledger
+ * (`../lifecycle/gate-ledger.ts`) for a resolution someone wrote with `chant
+ * approve`, and either walks through carrying the approver, or records a
+ * pending fact and ends. Nothing blocks, nothing is queued, nothing has to be
+ * resumed — the next run re-evaluates from the ledger, which is exactly the
+ * level-triggered shape a converge tick already has.
+ *
+ * The staleness rule is the same one `chant operator status` has applied since
+ * #1485: a resolution counts only if it is newer than the newest pending fact
+ * for that gate. Approving before the gate was ever reached does not
+ * pre-authorize a future run's gate that has since been recorded pending; a
+ * resolution from last month does not answer the fact this run just wrote.
+ *
+ * Ledger access goes through {@link GateLedgerPort} rather than straight to
+ * git, so a test (and the operator's own in-memory paths) can drive the
+ * decision without an orphan branch on disk.
+ */
+
+import {
+  appendPendingGate,
+  isPendingGateExpired,
+  latestPendingGate,
+  latestResolutionSince,
+  readGateLedger,
+  resolveApprovalUrl,
+  DEFAULT_GATE_EXPIRY,
+  type GateResolutionRecord,
+  type PendingGateInput,
+  type PendingGateRecord,
+} from "../lifecycle/gate-ledger";
+import { pushLifecycle } from "../lifecycle/git";
+import { parseDuration } from "./duration";
+
+/** The gate ledger, as the two executors need it: read both kinds of line, append a pending fact. */
+export interface GateLedgerPort {
+  read(op: string): Promise<{ resolutions: GateResolutionRecord[]; pending: PendingGateRecord[] }>;
+  appendPending(input: PendingGateInput): Promise<PendingGateRecord>;
+}
+
+/**
+ * The real port: the `chant/lifecycle` orphan branch. Pushes best-effort after
+ * appending, the same two-step-collapsed-into-one shape `chant approve` uses
+ * (`../cli/handlers/operator.ts` calls `pushLifecycle().catch(...)` right after
+ * its append) — a pending fact that only ever reaches the local branch is still
+ * a correct local answer, so a missing remote never fails the run.
+ */
+export function gitGateLedgerPort(opts?: { cwd?: string }): GateLedgerPort {
+  return {
+    async read(op) {
+      const { resolutions, pending } = await readGateLedger(op, opts);
+      return { resolutions, pending };
+    },
+    async appendPending(input) {
+      const { record } = await appendPendingGate(input, opts);
+      await pushLifecycle(opts).catch(() => undefined);
+      return record;
+    },
+  };
+}
+
+/** A gate ledger held in memory — what a test, or a caller that has already read the ledger, hands {@link evaluateGate}. */
+export function memoryGateLedgerPort(
+  seed: { resolutions?: GateResolutionRecord[]; pending?: PendingGateRecord[] } = {},
+): GateLedgerPort & { appended: PendingGateRecord[] } {
+  const resolutions = [...(seed.resolutions ?? [])];
+  const pending = [...(seed.pending ?? [])];
+  const appended: PendingGateRecord[] = [];
+  return {
+    appended,
+    async read() {
+      return { resolutions: [...resolutions], pending: [...pending] };
+    },
+    async appendPending(input) {
+      const record: PendingGateRecord = { version: 1, kind: "pending", ...input };
+      pending.push(record);
+      appended.push(record);
+      return record;
+    },
+  };
+}
+
+/** What a caller has to say about the gate it just reached. */
+export interface GateCheckInput {
+  /** The op the gate belongs to — the component's name, on the driver. */
+  op: string;
+  /** The gate's signal name. */
+  gate: string;
+  description?: string;
+  /** The gate's authored `timeout`, which becomes the pending fact's expiry. Default {@link DEFAULT_GATE_EXPIRY}. */
+  timeout?: string;
+  /** Identifies the run that reached the gate, when the caller has one. */
+  runId?: string;
+  /** ISO-8601 "now" — supplied by the caller, so the decision is deterministic under test. */
+  now?: string;
+}
+
+/** Either the gate is answered, or it is a standing fact. */
+export type GateCheck =
+  | { satisfied: true; resolution: GateResolutionRecord }
+  | { satisfied: false; pending: PendingGateRecord; recorded: boolean };
+
+/** The beginning of time — the anchor for a gate that has never been recorded pending, so any resolution for it counts. */
+const EPOCH = new Date(0).toISOString();
+
+/**
+ * Decide a gate against the ledger, recording the pending fact when it isn't
+ * answered.
+ *
+ * - A resolution newer than the newest pending fact satisfies the gate.
+ * - Otherwise, a pending fact that hasn't expired stands as it is: the run
+ *   ends `gated` and the ledger is left alone, so an operator ticking every
+ *   minute against an unapproved gate does not append a line a minute.
+ * - Otherwise (no pending fact, or the newest one has expired) a fresh pending
+ *   fact is appended and the run ends `gated`. `recorded` says which of the
+ *   two happened, so a renderer can tell "just recorded" from "still standing".
+ */
+export async function evaluateGate(port: GateLedgerPort, input: GateCheckInput): Promise<GateCheck> {
+  const now = input.now ?? new Date().toISOString();
+  const { resolutions, pending } = await port.read(input.op);
+
+  const standing = latestPendingGate(pending, input.gate);
+  const resolution = latestResolutionSince(resolutions, input.gate, standing?.timestamp ?? EPOCH);
+  if (resolution) return { satisfied: true, resolution };
+
+  if (standing && !isPendingGateExpired(standing, now)) {
+    return { satisfied: false, pending: standing, recorded: false };
+  }
+
+  const url = resolveApprovalUrl();
+  const record = await port.appendPending({
+    op: input.op,
+    gate: input.gate,
+    timestamp: now,
+    expiresAt: new Date(
+      new Date(now).getTime() + parseDuration(input.timeout ?? DEFAULT_GATE_EXPIRY),
+    ).toISOString(),
+    ...(input.description ? { description: input.description } : {}),
+    ...(input.runId ? { runId: input.runId } : {}),
+    ...(url ? { url } : {}),
+  });
+  return { satisfied: false, pending: record, recorded: true };
+}
+
+/** The line every renderer prints to say how a pending gate is cleared. */
+export function approveCommand(op: string, gate: string): string {
+  return `chant approve ${op} ${gate}`;
+}

package/src/op/generate-pipeline.test.ts

@@ -9,7 +9,9 @@
  */
 
 import { describe, test, expect, vi } from "vitest";
-import { generateOpsPipeline } from "./generate-pipeline";
+import { generateOpsPipeline, withOpSchedules } from "./generate-pipeline";
+import type { DiscoveredOp } from "./discover";
+import type { OpConfig } from "./types";
 import type { ScheduledOpSpec, OpPipelineResult } from "../lexicon";
 
 vi.mock("@intentius/chant-lexicon-gitlab", () => ({
@@ -22,7 +24,12 @@ vi.mock("@intentius/chant-lexicon-gitlab", () => ({
     package: () => "gitlab",
     generateOpPipeline: (ops: ScheduledOpSpec[]): OpPipelineResult => ({
       files: ops.map((o) => ({ name: `${o.name}.yml`, yaml: `# ${o.name} @ ${o.schedule}` })),
-      jobs: ops.map((o) => ({ jobName: o.name, op: o.name, schedule: o.schedule, findingMode: o.findingMode ?? "report" })),
+      jobs: ops.map((o) => ({
+        jobName: o.name,
+        op: o.name,
+        trigger: o.trigger ?? { kind: "cron" as const, schedule: o.schedule! },
+        findingMode: o.findingMode ?? "report",
+      })),
     }),
   },
 }));
@@ -48,6 +55,61 @@ describe("generateOpsPipeline", () => {
     const result = await generateOpsPipeline(specs, "gitlab");
     expect(result.success).toBe(true);
     expect(result.files).toEqual([{ name: "alb-deploy.yml", yaml: "# alb-deploy @ 0 6 * * *" }]);
-    expect(result.jobs).toEqual([{ jobName: "alb-deploy", op: "alb-deploy", schedule: "0 6 * * *", findingMode: "issue" }]);
+    expect(result.jobs).toEqual([
+      { jobName: "alb-deploy", op: "alb-deploy", trigger: { kind: "cron", schedule: "0 6 * * *" }, findingMode: "issue" },
+    ]);
+  });
+
+  // #2084: `trigger` is new and optional — a spec built the old way (`schedule`
+  // only, no `trigger`) must still round-trip through `generateOpsPipeline`
+  // unchanged, since every pre-#2084 caller (`WorkflowAuditOp`,
+  // `PipelineAuditOp`, `ReconcileOp`) only ever sets `schedule`.
+  test("a legacy `{ schedule }` spec with no `trigger` round-trips unchanged", async () => {
+    const specs: ScheduledOpSpec[] = [{ name: "alb-deploy", schedule: "0 6 * * *" }];
+    const result = await generateOpsPipeline(specs, "gitlab");
+    expect(result.success).toBe(true);
+    expect(result.files).toEqual([{ name: "alb-deploy.yml", yaml: "# alb-deploy @ 0 6 * * *" }]);
+    expect(result.jobs).toEqual([
+      { jobName: "alb-deploy", op: "alb-deploy", trigger: { kind: "cron", schedule: "0 6 * * *" }, findingMode: "report" },
+    ]);
+  });
+});
+
+describe("withOpSchedules — the Op's own cadence reaches the CI generator (#2120)", () => {
+  function discovered(entries: Array<[string, OpConfig]>): Map<string, DiscoveredOp> {
+    return new Map(entries.map(([name, config]) => [name, { config, filePath: `${name}.op.ts`, exportName: "default" }]));
+  }
+
+  const scheduled: OpConfig = {
+    name: "prod-watch",
+    overview: "watch prod",
+    phases: [],
+    schedule: { cron: "*/10 * * * *", overlap: "skip" },
+  };
+  const unscheduled: OpConfig = { name: "one-shot", overview: "no cadence", phases: [] };
+
+  test("a scheduled Op's cadence lands on its spec as opSchedule", () => {
+    const [spec] = withOpSchedules([{ name: "prod-watch" }], discovered([["prod-watch", scheduled]]));
+    expect(spec.opSchedule).toEqual({ cron: "*/10 * * * *", overlap: "skip" });
+  });
+
+  test("an Op with no cadence leaves its spec untouched", () => {
+    const input: ScheduledOpSpec[] = [{ name: "one-shot", schedule: "0 6 * * *" }];
+    expect(withOpSchedules(input, discovered([["one-shot", unscheduled]]))).toEqual(input);
+  });
+
+  test("an explicit trigger or schedule on the spec is preserved alongside it — resolveOpTrigger picks", () => {
+    const [spec] = withOpSchedules(
+      [{ name: "prod-watch", trigger: { kind: "push", branches: ["main"] } }],
+      discovered([["prod-watch", scheduled]]),
+    );
+    expect(spec.trigger).toEqual({ kind: "push", branches: ["main"] });
+    expect(spec.opSchedule).toEqual({ cron: "*/10 * * * *", overlap: "skip" });
+  });
+
+  test("the input specs are not mutated", () => {
+    const input: ScheduledOpSpec[] = [{ name: "prod-watch" }];
+    withOpSchedules(input, discovered([["prod-watch", scheduled]]));
+    expect(input[0].opSchedule).toBeUndefined();
   });
 });

package/src/op/generate-pipeline.ts

@@ -16,7 +16,7 @@
  * `resolveComponentGraph`; each `ScheduledOpSpec` is generated independently.
  */
 
-import { discoverOps } from "./discover";
+import { discoverOps, type DiscoveredOp } from "./discover";
 import {
   isLexiconPlugin,
   type LexiconPlugin,
@@ -46,6 +46,23 @@ async function loadLexiconPlugin(name: string): Promise<LexiconPlugin | null> {
   return null;
 }
 
+/**
+ * Copy each discovered Op's own `schedule` (#2120) onto its spec, so a CI
+ * generator can render the cron the Op already declares — `WatchOp({ name,
+ * schedule })` then needs no second cron in the `generateOpsPipeline` call.
+ * The spec's own `trigger`/`schedule` still win; `resolveOpTrigger` reads
+ * `opSchedule` last. Specs for Ops with no cadence pass through untouched.
+ */
+export function withOpSchedules(
+  specs: ScheduledOpSpec[],
+  discovered: Map<string, DiscoveredOp>,
+): ScheduledOpSpec[] {
+  return specs.map((spec) => {
+    const schedule = discovered.get(spec.name)?.config.schedule;
+    return schedule ? { ...spec, opSchedule: schedule } : spec;
+  });
+}
+
 /** Result of generating scheduled CI for a set of Ops (generate mode's Op counterpart, #927). */
 export interface GenerateOpsPipelineResult {
   success: boolean;
@@ -94,6 +111,6 @@ export async function generateOpsPipeline(
     };
   }
 
-  const { files, jobs } = plugin.generateOpPipeline(ops, options);
+  const { files, jobs } = plugin.generateOpPipeline(withOpSchedules(ops, discovered.ops), options);
   return { success: true, files, jobs };
 }

package/src/op/index.ts

@@ -3,18 +3,34 @@ export { Op, phase, activity, gate, effect, build, kubectlApply, helmInstall, he
          k3sInstall, k3sUninstall, flociUp, flociDown,
          flociAzUp, flociAzDown, flociGcpUp, flociGcpDown, httpCheck,
          azGroupEnsure, azGroupDelete, azApply, azDelete, awsApply, awsDelete, gcpApply, gcpDelete, policyGate,
+         guardValidate,
          spriteCreate, spriteExec, spriteCheckpoint, spriteRestore, listCheckpoints, spriteDestroy,
          spriteWriteFile, spriteReadFile, spriteListDir, spriteRemove,
          spriteApplyNetworkPolicy, spriteApplyServices,
          spriteTaskCreate, spriteTaskRefresh, spriteTaskRelease,
          spritesUp, spritesDown } from "./builders";
 export { OpResource } from "./resource";
-export { safeHeartbeat, sleep } from "./activity-runtime";
+export { sleep } from "./activity-runtime";
 export { emulatorLifecycle, emulatorsOf, endpointEnvVars } from "./emulator-lifecycle";
 export type { EmulatorSpec, EmulatorCapability, EmulatorDeclaration, EmulatorUpArgs, EmulatorLifecycle } from "./emulator-lifecycle";
 export { checkFreshness, compare, formatResult, latestRelease, parseVersion, unpinned } from "./emulator-freshness";
 export type { FreshnessResult } from "./emulator-freshness";
-export type { OpConfig, PhaseDefinition, StepDefinition, ActivityStep, GateStep, EffectStep } from "./types";
+export type { OpConfig, OpSchedule, PhaseDefinition, StepDefinition, ActivityStep, GateStep, EffectStep, OutcomeAttribute } from "./types";
+export { outcomeAttributesOf } from "./types";
+export { isValidCronExpression, cronSyntaxMessage, cronMatches, cronDueBetween } from "./cron";
+export {
+  WatchOp, ReconcileOp, ApplyOp, ConvergeOp,
+  WorkflowAuditOp, PipelineAuditOp, LexiconUpgradeOp, IN_SCOPE_LEXICONS,
+} from "./composites";
+export type {
+  WatchOpConfig, WatchOpResources,
+  ReconcileOpConfig, ReconcileOpResources,
+  ApplyOpConfig, ApplyOpResources,
+  ConvergeOpConfig, ConvergeOpResources, ConvergeDial,
+  WorkflowAuditOpConfig, WorkflowAuditOpResources,
+  PipelineAuditOpConfig, PipelineAuditOpResources,
+  LexiconUpgradeOpConfig, LexiconUpgradeOpResources,
+} from "./composites";
 export { receiptActivities, receiptCheckInput } from "./receipt-store";
 export type {
   ReceiptStore, EffectReceiptRef, ReceiptCheckInput, ReceiptActivities, ReceiptActivityOptions,
@@ -23,12 +39,31 @@ export type {
 } from "./receipt-store";
 export { discoverOps } from "./discover";
 export type { DiscoveredOp, OpDiscoveryResult } from "./discover";
-export { generateOpsPipeline } from "./generate-pipeline";
+export { generateOpsPipeline, withOpSchedules } from "./generate-pipeline";
 export type { GenerateOpsPipelineResult } from "./generate-pipeline";
 export { loadActivities, loadProfiles, resolveActivity } from "./activity-registry";
-export type { ActivityFn, ActivityProfile } from "./activity-registry";
-export { runOpLocally, parseDuration, findGate, LocalGateUnsupportedError, OpRunFailure } from "./local-executor";
-export type { StepRecord, OpRunResult } from "./local-executor";
+export type { ActivityFn } from "./activity-registry";
+export { loadActivityContracts, mergeActivityContracts } from "./activity-contract-registry";
+export type { LexiconActivityContractContributor } from "./activity-contract-registry";
+export { ACTIVITY_PROFILES, ACTIVITY_PROFILE_NAMES } from "./activity-profiles";
+export type { ActivityProfile, ActivityProfileName } from "./activity-profiles";
+export { NonRetryableActivityError, nonRetryableFailure } from "./activity-failure";
+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 {
+  OpRuntimeProvider, OpRunHandle, OpRunStartOptions, OpRunState, OpRunStatus,
+  OpRunRecord, OpRunRecordInput, OpRunPhaseRecord, OpRunStepRecord,
+} from "./runtime";
+export { buildOpIR, serializeOpIR, opConfigFromIR, OP_IR_FORMAT_VERSION } from "./op-ir";
+export type {
+  OpIR, OpIRPhase, OpIRStep, OpIRActivityStep, OpIRGateStep, OpIREffectStep, OpIRActivityContract,
+} from "./op-ir";
 export { renderHuman, renderJson } from "./local-output";
 export {
   activityContract, isActivityContract, collectActivityContracts, validateActivitySteps, KNOWN_ACTIVITY_PROFILES,
@@ -52,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,
+  ChangeSubscriber, OperatorSignalEvent,
 } from "./operator";
-export type { OperatorTickEvent, OperatorRoundOptions, OperatorLoopOptions } 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";