@intentius/chant 0.57.0 → 0.59.0

package/src/op/builders.ts

@@ -2,7 +2,17 @@ import { OpResource } from "./resource";
 import type { OpConfig, PhaseDefinition, StepDefinition, ActivityStep, GateStep, EffectStep } from "./types";
 import { isEffectReceipt, type EffectReceiptDeclaration } from "../effect-receipt";
 import { receiptCheckInput } from "./receipt-store";
-import { makeOutProxy, type StepOutputRef } from "./step-output-ref";
+import { makeOutProxy, type StepOutputRef, type WithStepRefs } from "./step-output-ref";
+import type { ChantBuildArgs } from "./activities/build";
+import type { ShellCmdArgs } from "./activities/shell";
+import type { WaitForStackArgs } from "./activities/wait";
+import type { LifecycleSnapshotArgs } from "./activities/lifecycle";
+import type { ChantTeardownArgs } from "./activities/teardown";
+import type { EnvTeardownArgs } from "./activities/env-teardown";
+import type { HttpCheckArgs } from "./activities/http-check";
+import type { PolicyGateArgs } from "./activities/policy";
+import type { GuardValidateArgs } from "./activities/guard-validate";
+import { isValidCronExpression, cronSyntaxMessage } from "./cron";
 
 /** An `activity()` result — the plain `ActivityStep` shape plus the `.out` reference sugar (#1290). */
 export interface NamedActivityStep extends ActivityStep {
@@ -18,7 +28,7 @@ export interface NamedActivityStep extends ActivityStep {
 // ── Core builders ─────────────────────────────────────────────────────────────
 
 /**
- * Declare a named, phased Temporal workflow.
+ * Declare a named, phased Op.
  *
  * @example
  * ```ts
@@ -31,8 +41,15 @@ export interface NamedActivityStep extends ActivityStep {
  *   ],
  * });
  * ```
+ *
+ * A `schedule` may be supplied for an Op that runs on a cadence (#2120); its
+ * cron is validated here, at construction, so a typo fails on `chant build`
+ * rather than becoming a schedule that silently never fires.
  */
 export function Op(config: OpConfig): InstanceType<typeof OpResource> {
+  if (config.schedule && !isValidCronExpression(config.schedule.cron)) {
+    throw new Error(`Op "${config.name}": ${cronSyntaxMessage(config.schedule.cron)}`);
+  }
   return new OpResource(config as unknown as Record<string, unknown>);
 }
 
@@ -85,14 +102,19 @@ export function activity(
   return step;
 }
 
-/** Insert a human gate — the workflow pauses until the named signal is received. */
+/**
+ * Insert a human gate. A gate is a fact on the gate ledger, not a wait: a run
+ * that reaches this step with no resolution newer than its pending fact
+ * records the pending fact and ends `gated`. `chant approve <op> <gate>`
+ * writes the resolution, and the next run walks through carrying the approver.
+ */
 export function gate(
-  signalName: string,
+  name: string,
   opts?: { timeout?: string; description?: string },
 ): GateStep {
   return {
     kind: "gate",
-    signalName,
+    gate: name,
     ...(opts?.timeout ? { timeout: opts.timeout } : {}),
     ...(opts?.description ? { description: opts.description } : {}),
   };
@@ -113,9 +135,10 @@ export function gate(
  * would sever the step from the declaration that lint, plan, and the lexicon
  * row all key on.
  *
- * A gate authored inside `steps` pauses only when the effect will fire (the
- * matched path never reaches it). The receipt-store activities (`receiptRead`,
- * `receiptWrite`) are provided by the receipt row's lexicon (#1835, aws).
+ * A gate authored inside `steps` is reached only when the effect will fire
+ * (the matched path never reaches it). The receipt-store activities
+ * (`receiptRead`, `receiptWrite`) are provided by the receipt row's lexicon
+ * (#1835, aws).
  *
  * @example
  * ```ts
@@ -190,10 +213,25 @@ export function takeProfileAndId(
   return { args, profile, id };
 }
 
-/** Run an npm build script in the given project directory. `opts.script` selects the script (default `build`, e.g. `build:aws`); `opts.env` adds env vars. */
-export const build = (path: string, opts?: Record<string, unknown>): ActivityStep => {
-  const { args, profile } = takeProfile(opts);
-  return activity("chantBuild", { path, ...args }, profile);
+/**
+ * Extra opts every typed base-activity wrapper below accepts alongside its
+ * activity's own fields: the step's `profile` override and its `id` (which
+ * routes to the step, never into args, so `.out` works — chant #1290).
+ */
+type StepOpts = { profile?: ActivityStep["profile"]; id?: string };
+
+/**
+ * Run an npm build script in the given project directory. `opts` is
+ * {@link ChantBuildArgs} itself, minus the positional `path` — `script`
+ * selects the npm script (default `build`, e.g. `build:aws`), `env` adds
+ * env vars.
+ */
+export const build = (
+  path: string,
+  opts?: WithStepRefs<Omit<ChantBuildArgs, "path">> & StepOpts,
+): NamedActivityStep => {
+  const { args, profile, id } = takeProfileAndId(opts as Record<string, unknown> | undefined);
+  return activity("chantBuild", { path, ...args }, { ...(profile ? { profile } : {}), ...(id ? { id } : {}) });
 };
 
 /** Run `kubectl apply -f <manifest>`. Defaults to the `longInfra` profile (override via `opts.profile`). */
@@ -228,10 +266,17 @@ export const helmInstallPinned = (
   return activity("helmInstall", { name, contentDigest, ...args }, profile ?? "longInfra");
 };
 
-/** Poll for stack readiness (kubectl rollout, CloudFormation complete, etc). Defaults to the `k8sWait` profile (override via `opts.profile`). */
-export const waitForStack = (name: string, opts?: Record<string, unknown>): ActivityStep => {
-  const { args, profile } = takeProfile(opts);
-  return activity("waitForStack", { name, ...args }, profile ?? "k8sWait");
+/**
+ * Poll until a Kubernetes Deployment/StatefulSet is fully rolled out. `opts` is
+ * {@link WaitForStackArgs} itself, minus the positional `name`. Defaults to the
+ * `k8sWait` profile (override via `opts.profile`).
+ */
+export const waitForStack = (
+  name: string,
+  opts?: WithStepRefs<Omit<WaitForStackArgs, "name">> & StepOpts,
+): NamedActivityStep => {
+  const { args, profile, id } = takeProfileAndId(opts as Record<string, unknown> | undefined);
+  return activity("waitForStack", { name, ...args }, { profile: profile ?? "k8sWait", ...(id ? { id } : {}) });
 };
 
 /** Poll any operator-backed Kubernetes resource until it reports ready, driven by a data-only readiness spec (CRD-aware; #365). Defaults to the `k8sWait` profile (override via `opts.profile`). */
@@ -246,20 +291,26 @@ export const gitlabPipeline = (name: string, opts?: Record<string, unknown>): Ac
   return activity("gitlabPipeline", { name, ...args }, profile ?? "longInfra");
 };
 
-/** Take a chant lifecycle snapshot for the given environment. */
-export const lifecycleSnapshot = (env: string): ActivityStep =>
-  activity("lifecycleSnapshot", { env });
+/**
+ * Take a chant lifecycle snapshot for the given environment.
+ * {@link LifecycleSnapshotArgs} has only `env`, which is positional here, so
+ * `opts` carries nothing but the step's `id` (for `.out`).
+ */
+export const lifecycleSnapshot = (env: string, opts?: { id?: string }): NamedActivityStep =>
+  activity("lifecycleSnapshot", { env } satisfies LifecycleSnapshotArgs, opts?.id ? { id: opts.id } : undefined);
 
 /**
  * Run an arbitrary shell command. Tag long-running commands with a `profile`
  * (e.g. `longInfra` for a multi-GB image push) so they get the right
- * start-to-close timeout under both the local executor and Temporal.
+ * start-to-close timeout on whichever runtime hosts the run.
  */
 export const shell = (
   cmd: string,
-  opts?: { env?: Record<string, string>; profile?: ActivityStep["profile"] },
-): ActivityStep =>
-  activity("shellCmd", { cmd, ...(opts?.env ? { env: opts.env } : {}) }, opts?.profile);
+  opts?: WithStepRefs<Omit<ShellCmdArgs, "cmd">> & StepOpts,
+): NamedActivityStep => {
+  const { args, profile, id } = takeProfileAndId(opts as Record<string, unknown> | undefined);
+  return activity("shellCmd", { cmd, ...args }, { ...(profile ? { profile } : {}), ...(id ? { id } : {}) });
+};
 
 /**
  * Ensure a `generated-once` secret exists in the target store (#1829, epic
@@ -283,9 +334,17 @@ export const ensureSecret = (
   return activity("ensureSecret", { name, keys, ...args }, profile);
 };
 
-/** Run `chant teardown` in the given project directory. Uses `longInfra` profile. */
-export const teardown = (path: string): ActivityStep =>
-  activity("chantTeardown", { path }, "longInfra");
+/**
+ * Run `chant teardown` in the given project directory. Fixed `longInfra`
+ * profile (not overridable). {@link ChantTeardownArgs} has only `path`
+ * (positional), so `opts` is just the step's `id` (for `.out`).
+ */
+export const teardown = (path: string, opts?: { id?: string }): NamedActivityStep =>
+  activity(
+    "chantTeardown",
+    { path } satisfies ChantTeardownArgs,
+    { profile: "longInfra", ...(opts?.id ? { id: opts.id } : {}) },
+  );
 
 /**
  * Tear down one environment's marker-owned resources — the durable form of
@@ -309,13 +368,16 @@ export const teardown = (path: string): ActivityStep =>
  * ]),
  * ```
  *
- * `opts` also accepts `path` (the chant project directory, default the
- * worker's cwd). Defaults to the `longInfra` profile (override via
+ * `opts` also accepts `path` (the chant project directory, default the chant
+ * process's cwd). Defaults to the `longInfra` profile (override via
  * `opts.profile`).
  */
-export const envTeardown = (env: string, opts?: Record<string, unknown>): ActivityStep => {
-  const { args, profile } = takeProfile(opts);
-  return activity("envTeardown", { env, ...args }, profile ?? "longInfra");
+export const envTeardown = (
+  env: string,
+  opts?: WithStepRefs<Omit<EnvTeardownArgs, "env">> & StepOpts,
+): NamedActivityStep => {
+  const { args, profile, id } = takeProfileAndId(opts as Record<string, unknown> | undefined);
+  return activity("envTeardown", { env, ...args }, { profile: profile ?? "longInfra", ...(id ? { id } : {}) });
 };
 
 /**
@@ -455,9 +517,12 @@ export const flociGcpDown = (opts?: Record<string, unknown>): ActivityStep => {
  * Defaults to the `fastIdempotent` profile. `opts` accepts `method`, `status`
  * (default any 2xx), `contains` (body substring), `retries`, `intervalMs`.
  */
-export const httpCheck = (url: string, opts?: Record<string, unknown>): ActivityStep => {
-  const { args, profile } = takeProfile(opts);
-  return activity("httpCheck", { url, ...args }, profile ?? "fastIdempotent");
+export const httpCheck = (
+  url: string,
+  opts?: WithStepRefs<Omit<HttpCheckArgs, "url">> & StepOpts,
+): NamedActivityStep => {
+  const { args, profile, id } = takeProfileAndId(opts as Record<string, unknown> | undefined);
+  return activity("httpCheck", { url, ...args }, { profile: profile ?? "fastIdempotent", ...(id ? { id } : {}) });
 };
 
 /**
@@ -546,7 +611,7 @@ export const gcpDelete = (manifestPath: string, opts?: Record<string, unknown>):
 // The builder and the executor-side activity function share a name (e.g.
 // `spriteCreate`), and that is intentional: the builder here returns an
 // `activity("spriteCreate", ...)` step; `loadActivities` loads the function of
-// the same name from the temporal lexicon to run the HTTP. They live in
+// the same name from the fly lexicon to run the HTTP. They live in
 // different modules and are both exported — exactly how `flapsUp`/`flapsDown`
 // already work. Op files import these builders; the executor resolves the
 // function by name. Endpoint override + bearer are read by the activity from
@@ -806,14 +871,33 @@ export const spritesDown = (args: {
 
 /**
  * Gate an apply on organizational policy: build the project and run its
- * `lint.policies` over the resolved resources, blocking the workflow on any
- * violation. Place it before the apply phase. `env` (or `ownership.env`) lets a
+ * `lint.policies` over the resolved resources, failing the step on any
+ * violation so no later phase runs. Place it before the apply phase. `env` (or `ownership.env`) lets a
  * policy branch on environment. Single-attempt (`policyCheck` profile) — a
  * deterministic violation is not retried.
  */
-export const policyGate = (opts?: { env?: string; path?: string }): ActivityStep =>
-  activity(
+export const policyGate = (opts?: WithStepRefs<PolicyGateArgs> & { id?: string }): NamedActivityStep => {
+  const path = (opts?.path as PolicyGateArgs["path"] | undefined) ?? ".";
+  const env = opts?.env;
+  return activity(
     "policyGate",
-    { path: opts?.path ?? ".", ...(opts?.env ? { env: opts.env } : {}) },
-    "policyCheck",
+    { path, ...(env !== undefined ? { env } : {}) },
+    { profile: "policyCheck", ...(opts?.id ? { id: opts.id } : {}) },
   );
+};
+
+/**
+ * Run an external CloudFormation Guard rules pack against the project's built
+ * CloudFormation template (chant #522). `opts` is {@link GuardValidateArgs}
+ * itself, minus the positional `rules`; `template` defaults (inside the
+ * activity) to `<path>/template.json`. Fixed `policyCheck` profile — same
+ * reasoning as {@link policyGate}: a deterministic policy check is
+ * single-attempt — and not overridable.
+ */
+export const guardValidate = (
+  rules: string,
+  opts?: WithStepRefs<Omit<GuardValidateArgs, "rules">> & { id?: string },
+): NamedActivityStep => {
+  const { id, ...rest } = (opts ?? {}) as Omit<GuardValidateArgs, "rules"> & { id?: string };
+  return activity("guardValidate", { rules, ...rest }, { profile: "policyCheck", ...(id ? { id } : {}) });
+};

package/src/op/change-signal.test.ts

@@ -0,0 +1,117 @@
+/**
+ * The wake gate (#1981): coalescing, the floor, and abort.
+ *
+ * Real timers with small floors rather than fake ones: the gate is nothing but
+ * two `setTimeout`s racing, and a fake-timer test of that asserts the mock
+ * rather than the behaviour.
+ */
+import { describe, test, expect } from "vitest";
+import { createChangeSignalGate, DEFAULT_SIGNAL_FLOOR_MS } from "./change-signal";
+
+describe("createChangeSignalGate", () => {
+  test("no signal: the wait runs the full interval and reports the timer", async () => {
+    const gate = createChangeSignalGate({ floorMs: 10 });
+    gate.roundStarted();
+    const started = Date.now();
+    expect(await gate.wait(60)).toBe("timer");
+    expect(Date.now() - started).toBeGreaterThanOrEqual(45);
+    expect(gate.wakeCount).toBe(0);
+  });
+
+  test("a signal past the floor wakes the sleep early", async () => {
+    const gate = createChangeSignalGate({ floorMs: 0 });
+    gate.roundStarted();
+    const started = Date.now();
+    const waiting = gate.wait(5_000);
+    setTimeout(() => gate.signal(), 10);
+    expect(await waiting).toBe("signal");
+    expect(Date.now() - started).toBeLessThan(2_000);
+    expect(gate.wakeCount).toBe(1);
+  });
+
+  test("a signal inside the floor waits the floor out rather than waking at once", async () => {
+    const gate = createChangeSignalGate({ floorMs: 120 });
+    gate.roundStarted();
+    const started = Date.now();
+    const waiting = gate.wait(5_000);
+    gate.signal();
+    expect(await waiting).toBe("signal");
+    // Woken by the signal, but not before the floor had passed.
+    expect(Date.now() - started).toBeGreaterThanOrEqual(100);
+  });
+
+  test("a storm of signals inside one floor window costs exactly one wake", async () => {
+    const gate = createChangeSignalGate({ floorMs: 60 });
+    gate.roundStarted();
+    const waiting = gate.wait(5_000);
+    for (let i = 0; i < 500; i++) gate.signal();
+    expect(await waiting).toBe("signal");
+    expect(gate.signalCount).toBe(500);
+    expect(gate.wakeCount).toBe(1);
+  });
+
+  test("the floor is measured from the round, so a steady stream cannot starve the tick", async () => {
+    const gate = createChangeSignalGate({ floorMs: 80 });
+    gate.roundStarted();
+    const started = Date.now();
+    const waiting = gate.wait(5_000);
+    // A signal every 10ms. A debounce would push the deadline out forever.
+    const drip = setInterval(() => gate.signal(), 10);
+    const reason = await waiting;
+    clearInterval(drip);
+    expect(reason).toBe("signal");
+    expect(Date.now() - started).toBeLessThan(1_000);
+  });
+
+  test("a signal arriving between rounds is honoured by the next wait, not lost", async () => {
+    const gate = createChangeSignalGate({ floorMs: 0 });
+    gate.roundStarted();
+    gate.signal(); // nothing is sleeping yet
+    expect(await gate.wait(5_000)).toBe("signal");
+  });
+
+  test("roundStarted clears the pending flag, so one signal never wakes two rounds", async () => {
+    const gate = createChangeSignalGate({ floorMs: 0 });
+    gate.roundStarted();
+    gate.signal();
+    expect(await gate.wait(5_000)).toBe("signal");
+    gate.roundStarted();
+    expect(await gate.wait(40)).toBe("timer");
+    expect(gate.wakeCount).toBe(1);
+  });
+
+  test("abort resolves rather than throwing, before and during a wait", async () => {
+    const gate = createChangeSignalGate({ floorMs: 0 });
+    const already = new AbortController();
+    already.abort();
+    expect(await gate.wait(5_000, already.signal)).toBe("aborted");
+
+    const controller = new AbortController();
+    const waiting = gate.wait(5_000, controller.signal);
+    setTimeout(() => controller.abort(), 10);
+    expect(await waiting).toBe("aborted");
+  });
+
+  test("a signal after abort does nothing", async () => {
+    const gate = createChangeSignalGate({ floorMs: 0 });
+    const controller = new AbortController();
+    const waiting = gate.wait(5_000, controller.signal);
+    controller.abort();
+    expect(await waiting).toBe("aborted");
+    gate.signal();
+    expect(gate.wakeCount).toBe(0);
+  });
+
+  test("signal() carries no payload: the type has no argument and the call ignores one", () => {
+    const gate = createChangeSignalGate();
+    expect(gate.signal.length).toBe(0);
+    // A caller that fabricates an event has nowhere to put it: the extra
+    // argument is dropped, and the gate's only state is a boolean.
+    (gate.signal as (...args: unknown[]) => void)({ kind: "Deployment", name: "fabricated" });
+    expect(gate.signalCount).toBe(1);
+  });
+
+  test("the documented floor is a real, positive default", () => {
+    expect(DEFAULT_SIGNAL_FLOOR_MS).toBe(5_000);
+  });
+});

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();
+      });
+    },
+  };
+}