@demlik/tea 0.12.0 → 0.14.0

package/dist/poller/index.d.ts

@@ -1,351 +0,0 @@
-import { DeadlineSub } from '../deadline/index.js';
-import { IdempotencyStore } from '../idempotency/index.js';
-import { C as Cmd, S as Sub } from '../core-Bjc0bS8j.js';
-import { RetryState, AnyRetryPolicy } from '../retry-backoff/index.js';
-import '../types-D7u9DkH7.js';
-
-/**
- * @demlik/tea/poller — "poll a source every N ms until a predicate holds, with
- * backoff on failure" as a TEA knob: one config object + a few pre-wired hooks
- * you spread into your machine.
- *
- * The recipe (which bricks it composes):
- *
- *   - `../deadline`        — the recurring tick is an ABSOLUTE-deadline Sub.
- *                            Each successful tick computes the NEXT absolute
- *                            fire time (`at + everyMs`) and the knob re-arms a
- *                            deadline against it. Absolute (not relative) so a
- *                            poller resumed after a DO eviction / page reload
- *                            fires at the correct wall-clock moment, not
- *                            `everyMs` after the reload (`../deadline`'s late-
- *                            subscribe property).
- *   - `../retry-backoff`   — a failed tick does NOT reschedule on the steady
- *                            cadence; it backs off. The next attempt is armed
- *                            `nextDelayMs(retry, policy)` from now, the retry
- *                            counter advances, and `shouldRetry` decides whether
- *                            the poller keeps trying or gives up. The bound may
- *                            be a COUNT or a wall-clock OUTAGE DURATION — see
- *                            `PollerConfig.retry`; `tickErr`'s `at` is the
- *                            streak clock, so both flow through unchanged.
- *   - `../idempotency`     — successive ticks against a flaky source can deliver
- *                            the SAME observation twice (a retried fetch, a
- *                            duplicate webhook the poll re-reads). `dedupeKey`
- *                            lets the consumer key each tick result; a duplicate
- *                            key is recorded but emits no fresh `onTick` follow-
- *                            up Cmd, so the side effect runs once per distinct
- *                            observation.
- *
- * Typical wiring (spread the knob's hooks into your machine):
- *
- *   const poll = createPoller<MyState, MyResult>({
- *     everyMs: 5_000,
- *     until: (s) => s.poll.lastResult?.status === "ready",
- *     onTick: () => ({ type: "fetch_status" }),
- *     retry: { ...defaultRetryPolicy, maxAttempts: 4 },
- *   });
- *
- *   // Model slice:
- *   init: (loaded) => [loaded ?? { poll: poll.init(), ... }, []],
- *
- *   // The deadline Sub fires `deadline_exceeded` on the cadence/backoff target;
- *   // route it to `tick`, the ONLY place the `onTick` fetch is emitted:
- *   deadline_exceeded: (s) => {
- *     const [slice, cmds] = poll.tick(s.poll);
- *     return [{ ...s, poll: slice }, cmds];
- *   },
- *
- *   // update cells (thread `at` in from the firing Msg / the runtime clock):
- *   poll_result: (s, m) => {
- *     const untilHeld = config.until({ ...s, ...folded });
- *     const [slice, cmds] = poll.tickResult(s.poll, m.result, m.at, untilHeld);
- *     return [{ ...s, poll: slice }, cmds];
- *   },
- *   poll_error: (s, m) => {
- *     const [slice, cmds] = poll.tickErr(s.poll, m.error, m.at);
- *     return [{ ...s, poll: slice }, cmds];
- *   },
- *
- *   // Subs — the knob owns the interval/backoff deadline:
- *   subscriptions: (s) => poll.subs(s.poll),
- *
- * The cadence has exactly ONE source: the `everyMs` deadline Sub. `start`,
- * `tickResult`, and `tickErr` only RE-ARM the deadline (they emit no cadence
- * Cmd); the fetch fires solely from `tick`, which the consumer routes the
- * deadline's `deadline_exceeded` Msg to. No verb performs an immediate
- * "fire now" observation, so the poller never polls faster than `everyMs`.
- *
- * The two non-negotiables every knob preserves hold here:
- *   - **Durable** — `tick`, `lastResult`, `retry`, and the next-fire target all
- *     live in the Model slice, so a poller survives eviction and resumes its
- *     cadence from the persisted target.
- *   - **Replayable** — every transition is a pure verb returning new state; the
- *     clock is never read inside a verb (the firing Msg carries `at`), and the
- *     retry RNG is injected ONCE at `createPoller` and threaded internally (no
- *     verb body names the global RNG). `replay` reconstructs a poll run exactly.
- *
- * NOT a substrate primitive: it depends only on sibling subpaths
- * (`../deadline`, `../retry-backoff`, `../idempotency`) and the core `Cmd` /
- * `Sub` types. Consumers reach it via the `@demlik/tea/poller` subpath; the L1
- * escape hatch is those three sibling subpaths threaded by hand.
- */
-
-/**
- * The poller knob's config — the single object you hand `createPoller`.
- *
- * `State` is the consumer's WHOLE Model (so `until` can read any field), `R` is
- * the shape of one tick observation (`lastResult` carries it forward).
- */
-interface PollerConfig<State, R> {
-    /**
-     * The steady cadence, in milliseconds, between successful ticks. The next
-     * tick is armed at the absolute target `at + everyMs` (computed from the
-     * `at` the prior tick's Msg carried), NOT `everyMs` from when the Sub
-     * happens to be reconciled — so the cadence does not drift across resumes.
-     */
-    readonly everyMs: number;
-    /**
-     * The stop predicate, read against the consumer's whole Model. When it
-     * returns `true`, the poller is DONE: `subs` returns `[]` (the timer
-     * disarms) and no further tick is scheduled. Pure — it must not read the
-     * clock or mutate; the substrate calls it inside `subscriptions(state)`.
-     */
-    readonly until: (state: State) => boolean;
-    /**
-     * The effect to run on each tick — the actual "go observe the source" Cmd
-     * (a fetch, a status read, a list call). The knob returns it from
-     * `tickResult` when the run continues; the consumer's `interpret` performs
-     * it and routes the observation back as the next tick-result Msg.
-     *
-     * Nullary by contract: a tick carries no per-call argument (the poller
-     * re-reads the same source every cadence). Capture any target in the Cmd
-     * literal the consumer's `onTick` returns.
-     */
-    readonly onTick: () => Cmd;
-    /**
-     * Backoff policy for FAILED ticks. Omit to use `defaultRetryPolicy`
-     * (full-jitter, 5 attempts). A success resets the retry counter, so the
-     * policy only governs consecutive failures.
-     *
-     * Any bound the `../retry-backoff` union admits: a count (`RetryPolicy`), a
-     * wall-clock outage budget (`DurationRetryPolicy`), or explicit
-     * `unbounded: true`. The duration bound needs no extra wiring here — every
-     * failure already arrives through `tickErr(state, error, at)` carrying the
-     * instant it was observed, so the streak clock is fed from the Msg's own
-     * data and the poller never reads a clock of its own (invariant 2).
-     */
-    readonly retry?: AnyRetryPolicy;
-    /**
-     * Optional dedupe key derived from a tick result. When provided, a result
-     * whose key was already `seen` records the observation but emits NO fresh
-     * `onTick` follow-up — the side effect runs once per distinct observation.
-     * Omit to treat every tick result as fresh (no dedupe). The dedupe store is
-     * bounded by `dedupeTtlMs` if set; otherwise it grows with distinct keys.
-     */
-    readonly dedupeKey?: (result: R) => string;
-    /**
-     * TTL for the dedupe store, in milliseconds. Only meaningful when
-     * `dedupeKey` is set. An observation older than `dedupeTtlMs` is forgotten,
-     * so a key seen long ago is treated as fresh again. Omit for an unbounded
-     * dedupe window (every distinct key remembered for the poller's lifetime).
-     */
-    readonly dedupeTtlMs?: number;
-}
-/**
- * The bookkeeping every poller phase carries in common, split out so each arm of
- * the `PollerState` discriminated union names only what it adds (`nextAtMs` on
- * `polling`) — the same discipline the sibling `PaginatorState` uses.
- *
- * - `tick`       — count of ticks recorded so far (success or failure). Doubles
- *                  as an observability cursor and a stable per-tick discriminant.
- * - `lastResult` — the most recent successful observation, or `undefined`
- *                  before the first success. `until` typically reads it (via the
- *                  consumer's Model), but the knob never interprets it.
- * - `retry`      — the `../retry-backoff` counter for consecutive failures.
- *                  Reset to `initRetry()` on every success. Once a failure has
- *                  been recorded it is a `TimedRetryState` (it carries the
- *                  streak's `firstFailureAtMs`, minted from `tickErr`'s `at`);
- *                  the field is typed at the `RetryState` supertype because a
- *                  poller that has never failed has no streak, and a slice
- *                  persisted before the origin existed rehydrates without one.
- * - `dedupe`     — the `../idempotency` store backing `dedupeKey`. An empty,
- *                  unbounded store when `dedupeKey` is unset (never written).
- */
-interface PollerCore<R> {
-    readonly tick: number;
-    readonly lastResult?: R;
-    readonly retry: RetryState;
-    readonly dedupe: IdempotencyStore<true>;
-}
-/**
- * The Model field the poller knob owns — its visible slice (the knob principle:
- * managed state lives in the Model, never a closure, so it is durable and
- * replayable). A discriminated union on `phase` so the armed-timer target lives
- * ONLY where it is meaningful and impossible combinations are unrepresentable
- * (pattern 11), the sibling `PaginatorState` idiom:
- *
- * - `polling`  — ticks are scheduled. Carries `nextAtMs`, the ABSOLUTE target
- *                the interval/backoff timer is armed against (persisted so a
- *                resumed poller re-arms the same moment), or `null` before the
- *                first `start` primes it.
- * - `done`     — `until` held; the poll is finished. Carries NO `nextAtMs` — a
- *                finished poll can never sit on an armed target.
- * - `gave_up`  — backoff exhausted `maxAttempts`. Carries NO `nextAtMs` either.
- *
- * Because only `polling` carries `nextAtMs`, `subs` guards on `phase` alone to
- * decide whether a timer is desired — a `done`/`gave_up` state with a live target
- * (the old flat record's hazard) simply cannot be built.
- */
-type PollerState<R> = (PollerCore<R> & {
-    readonly phase: "polling";
-    readonly nextAtMs: number | null;
-}) | (PollerCore<R> & {
-    readonly phase: "done";
-}) | (PollerCore<R> & {
-    readonly phase: "gave_up";
-});
-/**
- * The three arms, named — so a verb can DECLARE the phases it can actually
- * reach instead of the whole union.
- *
- * A verb whose return type is the full `PollerState<R>` tells a caller nothing
- * about where the poller went, and a caller that needs to know (a chart
- * declaring an edge's fan-out; an exhaustive `switch`) has to re-derive it by
- * reading the verb's body. Every one of these narrowings is already true of the
- * implementation — `start` only ever builds a `polling` arm, `tickResult` never
- * builds `gave_up`, `tickErr` never builds `done` — so naming them costs
- * nothing at runtime and moves a fact out of the source and into the signature.
- */
-type PollerPolling<R> = Extract<PollerState<R>, {
-    phase: "polling";
-}>;
-type PollerDone<R> = Extract<PollerState<R>, {
-    phase: "done";
-}>;
-type PollerGaveUp<R> = Extract<PollerState<R>, {
-    phase: "gave_up";
-}>;
-/**
- * The poller Sub type — a `../deadline` Sub under a fixed id family. One id per
- * knob instance keeps the reconcile pass from churning the timer: the same id
- * across transitions means "same armed deadline", even as `nextAtMs` advances.
- */
-type PollerSub = DeadlineSub;
-/**
- * The knob handle returned by `createPoller`. Spread its hooks into your
- * machine: `init()` seeds the slice, `start(...)` arms the first tick,
- * `tickResult` / `tickErr` are the two update verbs, and `subs(...)` returns the
- * timer Sub while the poller is live.
- *
- * Pure-ops + subs module: there is no `handlers(ports)` cell. The poller's I/O
- * is the consumer's own `onTick` Cmd run by the consumer's `interpret` — the
- * knob never owns a port. (Compare `../deadline`, which ships a `subscribe`
- * cell; the poller reuses `../deadline`'s, so it has nothing of its own to
- * splice into `interpret`.)
- */
-interface Poller<State, R> {
-    /** Seed the Model slice. Idle until `start(...)` arms the first tick. */
-    init(): PollerPolling<R>;
-    /**
-     * Arm the first tick. `at` is the current clock (carried in from the Msg /
-     * runtime that kicks the poller off — never read inside the verb). Returns
-     * the slice with the first deadline target set to `at + everyMs` and emits NO
-     * Cmd. The cadence has ONE source — the deadline Sub — so `start` does not
-     * perform the first observation itself (an immediate `onTick` here would race
-     * the timer and poll as fast as the source responds). The first observation
-     * fires when the deadline crosses `at + everyMs` and the consumer routes
-     * `deadline_exceeded` → `tick`.
-     */
-    start(state: PollerState<R>, at: number): readonly [PollerPolling<R>, readonly Cmd[]];
-    /**
-     * Perform one observation — the cadence verb. The consumer routes the
-     * deadline Sub's `deadline_exceeded` Msg here; `tick` emits the single
-     * `config.onTick()` Cmd that goes and reads the source. This is the ONLY
-     * next-tick mechanism: the timer fires, the consumer calls `tick`, the fetch
-     * runs, and the observation comes back through `tickResult` / `tickErr`
-     * (which re-arm the next deadline). A no-op on a finished poller — a stale
-     * deadline fire racing a terminal transition the reconcile pass has not yet
-     * retired emits nothing.
-     *
-     * Takes no `at`: `tick` does not touch the schedule (the just-fired deadline
-     * is exhausted; the next target is set when the result lands), so it needs no
-     * clock — keeping it trivially pure.
-     */
-    tick(state: PollerState<R>): readonly [PollerState<R>, readonly Cmd[]];
-    /**
-     * Record a successful tick observation at clock `at`.
-     *
-     * - Resets the retry counter (a success clears consecutive-failure state).
-     * - Stores `result` as `lastResult` and bumps `tick`.
-     * - Re-arms the next tick at the absolute target `at + everyMs` (the steady
-     *   cadence). It emits NO cadence `onTick` — the next observation fires from
-     *   the deadline Sub via `tick`, never immediately from a result.
-     * - Dedupe (opt-in, orthogonal to cadence): when `dedupeKey` is set, a FRESH
-     *   observation emits one `onTick` FOLLOW-UP (the consumer's "run the
-     *   downstream side effect once per distinct observation" hook) and a
-     *   DUPLICATE key records the sighting but suppresses the follow-up. With no
-     *   `dedupeKey`, `tickResult` emits nothing — the cadence `tick` is the only
-     *   `onTick`, so an unconfigured poller never double-fetches.
-     * - UNLESS `untilHeld` is `true` (the consumer evaluated `config.until`
-     *   against the post-result Model) — then the poller enters `"done"`,
-     *   disarms (`nextAtMs: null`), and emits no Cmd, dedupe or otherwise.
-     *
-     * `untilHeld` is passed in rather than computed here because `until` reads
-     * the consumer's WHOLE Model, which this verb does not hold — the consumer
-     * evaluates it at the call site after folding `result` into its Model and
-     * passes the boolean. (`subs` re-checks `phase` to decide arming, so a
-     * mis-passed `untilHeld` cannot leave a "done" poller arming timers.)
-     */
-    tickResult(state: PollerState<R>, result: R, at: number, untilHeld: boolean): readonly [PollerPolling<R> | PollerDone<R>, readonly Cmd[]];
-    /**
-     * Record a FAILED tick at clock `at`. Backs off instead of holding the
-     * steady cadence:
-     *
-     * - Advances the retry counter (`recordFailure`).
-     * - If `shouldRetry` still permits another attempt, arms the next tick at
-     *   `at + nextDelayMs(retry, policy)` (the backoff curve) and emits NO Cmd —
-     *   the retry observation fires when that backoff deadline crosses and the
-     *   consumer routes `deadline_exceeded` → `tick`. The timer is the single
-     *   next-tick mechanism, on the backoff curve here instead of `everyMs`.
-     * - If backoff is exhausted (`!shouldRetry`), enters `"gave_up"`, disarms
-     *   (`nextAtMs: null`), and emits no Cmd.
-     *
-     * `at` is both the backoff anchor AND the streak clock: it is passed to
-     * `recordFailure` (starting / preserving `firstFailureAtMs`) and to
-     * `shouldRetry`, so a `DurationRetryPolicy` on `config.retry` is honoured
-     * with no extra wiring. Under a duration bound the poller keeps retrying
-     * however many attempts the outage takes, and stops at the declared
-     * wall-clock budget measured from the streak's FIRST failure.
-     *
-     * The backoff jitter uses the `rng` injected ONCE at `createPoller` (default
-     * `Math.random` at the effect boundary, a fixed value in tests); the verb
-     * body never names the global RNG, so a poller built with a fixed `rng`
-     * replays a failure-and-backoff run bit-for-bit.
-     */
-    tickErr(state: PollerState<R>, error: unknown, at: number): readonly [PollerPolling<R> | PollerGaveUp<R>, readonly Cmd[]];
-    /**
-     * The pre-wired subscriptions cell. Returns the single tick-deadline Sub
-     * while the poller is `"polling"` with an armed `nextAtMs`; returns `[]`
-     * once `"done"` / `"gave_up"` (the timer disarms) or before `start`. Assign
-     * directly: `subscriptions: (s) => poll.subs(s.poll)`.
-     *
-     * The `DeadlineSub` it returns is consumed by `../deadline`'s
-     * `subscribeDeadline` cell, which the consumer wires into `subscribe` —
-     * the poller does not redraw the timer lifecycle.
-     */
-    subs(state: PollerState<R>): readonly Sub[];
-}
-/**
- * Build a poller knob from `config`. Returns the hook bag to spread into a
- * machine (see the module doc-comment for the wiring). Pure factory — no clock
- * read, no timer; everything happens when the consumer calls the returned
- * verbs / `subs` with an injected `at`.
- *
- * `rng` is injected ONCE here (default `Math.random` at the effect boundary, a
- * fixed value in tests) and threaded internally into the backoff jitter. No
- * verb body ever names the global RNG, so a poller built with a fixed `rng`
- * replays a failure-and-backoff run bit-for-bit (invariant 2: the verbs are
- * pure given the injected `rng`).
- */
-declare function createPoller<State, R>(config: PollerConfig<State, R>, rng?: () => number): Poller<State, R>;
-
-export { type Poller, type PollerConfig, type PollerDone, type PollerGaveUp, type PollerPolling, type PollerState, type PollerSub, createPoller };

package/dist/poller/index.js

@@ -1,115 +0,0 @@
-import { deadlineSub } from '../chunk-JGVL3WPL.js';
-import { asRng, defaultRetryPolicy, initRetry, recordFailure, shouldRetry, nextDelayMs } from '../chunk-Q2UM7BXU.js';
-import { idempotencyMemory } from '../chunk-BYQUGDD3.js';
-import '../chunk-K575PT4S.js';
-import '../chunk-2YFLOCWX.js';
-import '../chunk-5EHLEUTL.js';
-import '../chunk-B5VXOFMZ.js';
-
-// src/poller/index.ts
-function pollerSubId(atMs) {
-  return `poller:tick:${atMs}`;
-}
-function createPoller(config, rng = Math.random) {
-  const rngBranded = asRng(rng);
-  const policy = config.retry ?? defaultRetryPolicy;
-  const memory = idempotencyMemory();
-  function init() {
-    return {
-      phase: "polling",
-      tick: 0,
-      retry: initRetry(),
-      nextAtMs: null,
-      // The dedupe store is created regardless; it is only WRITTEN when
-      // `dedupeKey` is set, so an unconfigured poller carries an inert empty
-      // store (no per-op cost, JSON-serializable, durable like the rest of
-      // the slice).
-      dedupe: memory.init({ ttlMs: config.dedupeTtlMs })
-    };
-  }
-  function start(state, at) {
-    return [
-      {
-        phase: "polling",
-        tick: state.tick,
-        lastResult: state.lastResult,
-        retry: state.retry,
-        nextAtMs: at + config.everyMs,
-        dedupe: state.dedupe
-      },
-      []
-    ];
-  }
-  function tick(state) {
-    if (state.phase !== "polling") return [state, []];
-    return [state, [config.onTick()]];
-  }
-  function tickResult(state, result, at, untilHeld) {
-    const tick2 = state.tick + 1;
-    if (untilHeld) {
-      return [
-        {
-          phase: "done",
-          tick: tick2,
-          lastResult: result,
-          retry: initRetry(),
-          dedupe: state.dedupe
-        },
-        []
-      ];
-    }
-    const next = {
-      phase: "polling",
-      tick: tick2,
-      lastResult: result,
-      retry: initRetry(),
-      nextAtMs: at + config.everyMs,
-      dedupe: state.dedupe
-    };
-    if (!config.dedupeKey) return [next, []];
-    const key = config.dedupeKey(result);
-    const suppress = memory.isSeen(next.dedupe, key, at);
-    const deduped = {
-      ...next,
-      dedupe: memory.remember(next.dedupe, key, true, at)
-    };
-    return [deduped, suppress ? [] : [config.onTick()]];
-  }
-  function tickErr(state, error, at) {
-    const retry = recordFailure(state.retry, error, at);
-    const tick2 = state.tick + 1;
-    if (!shouldRetry(retry, policy, at)) {
-      return [
-        {
-          phase: "gave_up",
-          tick: tick2,
-          lastResult: state.lastResult,
-          retry,
-          dedupe: state.dedupe
-        },
-        []
-      ];
-    }
-    const delayMs = nextDelayMs(retry, policy, rngBranded);
-    return [
-      {
-        phase: "polling",
-        tick: tick2,
-        lastResult: state.lastResult,
-        retry,
-        nextAtMs: at + delayMs,
-        dedupe: state.dedupe
-      },
-      []
-    ];
-  }
-  function subs(state) {
-    if (state.phase !== "polling" || state.nextAtMs === null) return [];
-    return [deadlineSub(pollerSubId(state.nextAtMs), state.nextAtMs)];
-  }
-  return { init, start, tick, tickResult, tickErr, subs };
-}
-
-export { createPoller };
-//# sourceMappingURL=index.js.map
-//# sourceMappingURL=index.js.map

package/dist/poller/index.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../../src/poller/index.ts"],"names":["tick"],"mappings":"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","file":"index.js","sourcesContent":["/**\n * @demlik/tea/poller — \"poll a source every N ms until a predicate holds, with\n * backoff on failure\" as a TEA knob: one config object + a few pre-wired hooks\n * you spread into your machine.\n *\n * The recipe (which bricks it composes):\n *\n *   - `../deadline`        — the recurring tick is an ABSOLUTE-deadline Sub.\n *                            Each successful tick computes the NEXT absolute\n *                            fire time (`at + everyMs`) and the knob re-arms a\n *                            deadline against it. Absolute (not relative) so a\n *                            poller resumed after a DO eviction / page reload\n *                            fires at the correct wall-clock moment, not\n *                            `everyMs` after the reload (`../deadline`'s late-\n *                            subscribe property).\n *   - `../retry-backoff`   — a failed tick does NOT reschedule on the steady\n *                            cadence; it backs off. The next attempt is armed\n *                            `nextDelayMs(retry, policy)` from now, the retry\n *                            counter advances, and `shouldRetry` decides whether\n *                            the poller keeps trying or gives up. The bound may\n *                            be a COUNT or a wall-clock OUTAGE DURATION — see\n *                            `PollerConfig.retry`; `tickErr`'s `at` is the\n *                            streak clock, so both flow through unchanged.\n *   - `../idempotency`     — successive ticks against a flaky source can deliver\n *                            the SAME observation twice (a retried fetch, a\n *                            duplicate webhook the poll re-reads). `dedupeKey`\n *                            lets the consumer key each tick result; a duplicate\n *                            key is recorded but emits no fresh `onTick` follow-\n *                            up Cmd, so the side effect runs once per distinct\n *                            observation.\n *\n * Typical wiring (spread the knob's hooks into your machine):\n *\n *   const poll = createPoller<MyState, MyResult>({\n *     everyMs: 5_000,\n *     until: (s) => s.poll.lastResult?.status === \"ready\",\n *     onTick: () => ({ type: \"fetch_status\" }),\n *     retry: { ...defaultRetryPolicy, maxAttempts: 4 },\n *   });\n *\n *   // Model slice:\n *   init: (loaded) => [loaded ?? { poll: poll.init(), ... }, []],\n *\n *   // The deadline Sub fires `deadline_exceeded` on the cadence/backoff target;\n *   // route it to `tick`, the ONLY place the `onTick` fetch is emitted:\n *   deadline_exceeded: (s) => {\n *     const [slice, cmds] = poll.tick(s.poll);\n *     return [{ ...s, poll: slice }, cmds];\n *   },\n *\n *   // update cells (thread `at` in from the firing Msg / the runtime clock):\n *   poll_result: (s, m) => {\n *     const untilHeld = config.until({ ...s, ...folded });\n *     const [slice, cmds] = poll.tickResult(s.poll, m.result, m.at, untilHeld);\n *     return [{ ...s, poll: slice }, cmds];\n *   },\n *   poll_error: (s, m) => {\n *     const [slice, cmds] = poll.tickErr(s.poll, m.error, m.at);\n *     return [{ ...s, poll: slice }, cmds];\n *   },\n *\n *   // Subs — the knob owns the interval/backoff deadline:\n *   subscriptions: (s) => poll.subs(s.poll),\n *\n * The cadence has exactly ONE source: the `everyMs` deadline Sub. `start`,\n * `tickResult`, and `tickErr` only RE-ARM the deadline (they emit no cadence\n * Cmd); the fetch fires solely from `tick`, which the consumer routes the\n * deadline's `deadline_exceeded` Msg to. No verb performs an immediate\n * \"fire now\" observation, so the poller never polls faster than `everyMs`.\n *\n * The two non-negotiables every knob preserves hold here:\n *   - **Durable** — `tick`, `lastResult`, `retry`, and the next-fire target all\n *     live in the Model slice, so a poller survives eviction and resumes its\n *     cadence from the persisted target.\n *   - **Replayable** — every transition is a pure verb returning new state; the\n *     clock is never read inside a verb (the firing Msg carries `at`), and the\n *     retry RNG is injected ONCE at `createPoller` and threaded internally (no\n *     verb body names the global RNG). `replay` reconstructs a poll run exactly.\n *\n * NOT a substrate primitive: it depends only on sibling subpaths\n * (`../deadline`, `../retry-backoff`, `../idempotency`) and the core `Cmd` /\n * `Sub` types. Consumers reach it via the `@demlik/tea/poller` subpath; the L1\n * escape hatch is those three sibling subpaths threaded by hand.\n */\n\nimport { type DeadlineSub, deadlineSub } from \"../deadline\";\nimport type { IdempotencyStore } from \"../idempotency\";\nimport { idempotencyMemory } from \"../idempotency/adapter\";\nimport type { Cmd, Sub } from \"../index\";\nimport {\n  type AnyRetryPolicy,\n  asRng,\n  defaultRetryPolicy,\n  initRetry,\n  nextDelayMs,\n  type RetryState,\n  recordFailure,\n  shouldRetry,\n} from \"../retry-backoff\";\n\n/**\n * The poller knob's config — the single object you hand `createPoller`.\n *\n * `State` is the consumer's WHOLE Model (so `until` can read any field), `R` is\n * the shape of one tick observation (`lastResult` carries it forward).\n */\nexport interface PollerConfig<State, R> {\n  /**\n   * The steady cadence, in milliseconds, between successful ticks. The next\n   * tick is armed at the absolute target `at + everyMs` (computed from the\n   * `at` the prior tick's Msg carried), NOT `everyMs` from when the Sub\n   * happens to be reconciled — so the cadence does not drift across resumes.\n   */\n  readonly everyMs: number;\n  /**\n   * The stop predicate, read against the consumer's whole Model. When it\n   * returns `true`, the poller is DONE: `subs` returns `[]` (the timer\n   * disarms) and no further tick is scheduled. Pure — it must not read the\n   * clock or mutate; the substrate calls it inside `subscriptions(state)`.\n   */\n  readonly until: (state: State) => boolean;\n  /**\n   * The effect to run on each tick — the actual \"go observe the source\" Cmd\n   * (a fetch, a status read, a list call). The knob returns it from\n   * `tickResult` when the run continues; the consumer's `interpret` performs\n   * it and routes the observation back as the next tick-result Msg.\n   *\n   * Nullary by contract: a tick carries no per-call argument (the poller\n   * re-reads the same source every cadence). Capture any target in the Cmd\n   * literal the consumer's `onTick` returns.\n   */\n  readonly onTick: () => Cmd;\n  /**\n   * Backoff policy for FAILED ticks. Omit to use `defaultRetryPolicy`\n   * (full-jitter, 5 attempts). A success resets the retry counter, so the\n   * policy only governs consecutive failures.\n   *\n   * Any bound the `../retry-backoff` union admits: a count (`RetryPolicy`), a\n   * wall-clock outage budget (`DurationRetryPolicy`), or explicit\n   * `unbounded: true`. The duration bound needs no extra wiring here — every\n   * failure already arrives through `tickErr(state, error, at)` carrying the\n   * instant it was observed, so the streak clock is fed from the Msg's own\n   * data and the poller never reads a clock of its own (invariant 2).\n   */\n  readonly retry?: AnyRetryPolicy;\n  /**\n   * Optional dedupe key derived from a tick result. When provided, a result\n   * whose key was already `seen` records the observation but emits NO fresh\n   * `onTick` follow-up — the side effect runs once per distinct observation.\n   * Omit to treat every tick result as fresh (no dedupe). The dedupe store is\n   * bounded by `dedupeTtlMs` if set; otherwise it grows with distinct keys.\n   */\n  readonly dedupeKey?: (result: R) => string;\n  /**\n   * TTL for the dedupe store, in milliseconds. Only meaningful when\n   * `dedupeKey` is set. An observation older than `dedupeTtlMs` is forgotten,\n   * so a key seen long ago is treated as fresh again. Omit for an unbounded\n   * dedupe window (every distinct key remembered for the poller's lifetime).\n   */\n  readonly dedupeTtlMs?: number;\n}\n\n/**\n * The bookkeeping every poller phase carries in common, split out so each arm of\n * the `PollerState` discriminated union names only what it adds (`nextAtMs` on\n * `polling`) — the same discipline the sibling `PaginatorState` uses.\n *\n * - `tick`       — count of ticks recorded so far (success or failure). Doubles\n *                  as an observability cursor and a stable per-tick discriminant.\n * - `lastResult` — the most recent successful observation, or `undefined`\n *                  before the first success. `until` typically reads it (via the\n *                  consumer's Model), but the knob never interprets it.\n * - `retry`      — the `../retry-backoff` counter for consecutive failures.\n *                  Reset to `initRetry()` on every success. Once a failure has\n *                  been recorded it is a `TimedRetryState` (it carries the\n *                  streak's `firstFailureAtMs`, minted from `tickErr`'s `at`);\n *                  the field is typed at the `RetryState` supertype because a\n *                  poller that has never failed has no streak, and a slice\n *                  persisted before the origin existed rehydrates without one.\n * - `dedupe`     — the `../idempotency` store backing `dedupeKey`. An empty,\n *                  unbounded store when `dedupeKey` is unset (never written).\n */\ninterface PollerCore<R> {\n  readonly tick: number;\n  readonly lastResult?: R;\n  readonly retry: RetryState;\n  readonly dedupe: IdempotencyStore<true>;\n}\n\n/**\n * The Model field the poller knob owns — its visible slice (the knob principle:\n * managed state lives in the Model, never a closure, so it is durable and\n * replayable). A discriminated union on `phase` so the armed-timer target lives\n * ONLY where it is meaningful and impossible combinations are unrepresentable\n * (pattern 11), the sibling `PaginatorState` idiom:\n *\n * - `polling`  — ticks are scheduled. Carries `nextAtMs`, the ABSOLUTE target\n *                the interval/backoff timer is armed against (persisted so a\n *                resumed poller re-arms the same moment), or `null` before the\n *                first `start` primes it.\n * - `done`     — `until` held; the poll is finished. Carries NO `nextAtMs` — a\n *                finished poll can never sit on an armed target.\n * - `gave_up`  — backoff exhausted `maxAttempts`. Carries NO `nextAtMs` either.\n *\n * Because only `polling` carries `nextAtMs`, `subs` guards on `phase` alone to\n * decide whether a timer is desired — a `done`/`gave_up` state with a live target\n * (the old flat record's hazard) simply cannot be built.\n */\nexport type PollerState<R> =\n  | (PollerCore<R> & {\n      readonly phase: \"polling\";\n      readonly nextAtMs: number | null;\n    })\n  | (PollerCore<R> & { readonly phase: \"done\" })\n  | (PollerCore<R> & { readonly phase: \"gave_up\" });\n\n/**\n * The three arms, named — so a verb can DECLARE the phases it can actually\n * reach instead of the whole union.\n *\n * A verb whose return type is the full `PollerState<R>` tells a caller nothing\n * about where the poller went, and a caller that needs to know (a chart\n * declaring an edge's fan-out; an exhaustive `switch`) has to re-derive it by\n * reading the verb's body. Every one of these narrowings is already true of the\n * implementation — `start` only ever builds a `polling` arm, `tickResult` never\n * builds `gave_up`, `tickErr` never builds `done` — so naming them costs\n * nothing at runtime and moves a fact out of the source and into the signature.\n */\nexport type PollerPolling<R> = Extract<PollerState<R>, { phase: \"polling\" }>;\nexport type PollerDone<R> = Extract<PollerState<R>, { phase: \"done\" }>;\nexport type PollerGaveUp<R> = Extract<PollerState<R>, { phase: \"gave_up\" }>;\n\n/**\n * The poller Sub type — a `../deadline` Sub under a fixed id family. One id per\n * knob instance keeps the reconcile pass from churning the timer: the same id\n * across transitions means \"same armed deadline\", even as `nextAtMs` advances.\n */\nexport type PollerSub = DeadlineSub;\n\n/**\n * The Sub id the poller arms its tick deadline under, keyed on the absolute\n * target. The id ROTATES per target because a one-shot deadline timer is\n * exhausted once it fires and the substrate reconciles subs by `id` alone: a\n * fixed id would leave the fired timer registered and never re-arm, so the\n * cadence would die after exactly one tick. Encoding `atMs` in the id makes each\n * cadence/backoff target a distinct identity — the reconcile pass retires the\n * spent timer and arms the next — while a resumed poller re-arms the SAME id\n * from its persisted `nextAtMs` (eviction is idempotent).\n *\n * A single poller machine arms exactly one tick timer at a time; a consumer\n * running several pollers on one machine namespaces them by composing the knob\n * under distinct slices (a future multi-poller config would thread a prefix).\n */\nfunction pollerSubId(atMs: number): string {\n  return `poller:tick:${atMs}`;\n}\n\n/**\n * The knob handle returned by `createPoller`. Spread its hooks into your\n * machine: `init()` seeds the slice, `start(...)` arms the first tick,\n * `tickResult` / `tickErr` are the two update verbs, and `subs(...)` returns the\n * timer Sub while the poller is live.\n *\n * Pure-ops + subs module: there is no `handlers(ports)` cell. The poller's I/O\n * is the consumer's own `onTick` Cmd run by the consumer's `interpret` — the\n * knob never owns a port. (Compare `../deadline`, which ships a `subscribe`\n * cell; the poller reuses `../deadline`'s, so it has nothing of its own to\n * splice into `interpret`.)\n */\nexport interface Poller<\n  // State is a phantom-style parameter — present so consumers can spell\n  // `Poller<MyState, MyResult>` matching `createPoller<State, R>`. It is\n  // consumed by the config's `until` predicate, not by any handle method, so\n  // it does not appear in the interface body. Same discipline as\n  // `BoundMachine`'s `Ctx`.\n  // biome-ignore lint/correctness/noUnusedVariables: phantom type parameter (see above)\n  State,\n  R,\n> {\n  /** Seed the Model slice. Idle until `start(...)` arms the first tick. */\n  init(): PollerPolling<R>;\n  /**\n   * Arm the first tick. `at` is the current clock (carried in from the Msg /\n   * runtime that kicks the poller off — never read inside the verb). Returns\n   * the slice with the first deadline target set to `at + everyMs` and emits NO\n   * Cmd. The cadence has ONE source — the deadline Sub — so `start` does not\n   * perform the first observation itself (an immediate `onTick` here would race\n   * the timer and poll as fast as the source responds). The first observation\n   * fires when the deadline crosses `at + everyMs` and the consumer routes\n   * `deadline_exceeded` → `tick`.\n   */\n  start(\n    state: PollerState<R>,\n    at: number,\n  ): readonly [PollerPolling<R>, readonly Cmd[]];\n  /**\n   * Perform one observation — the cadence verb. The consumer routes the\n   * deadline Sub's `deadline_exceeded` Msg here; `tick` emits the single\n   * `config.onTick()` Cmd that goes and reads the source. This is the ONLY\n   * next-tick mechanism: the timer fires, the consumer calls `tick`, the fetch\n   * runs, and the observation comes back through `tickResult` / `tickErr`\n   * (which re-arm the next deadline). A no-op on a finished poller — a stale\n   * deadline fire racing a terminal transition the reconcile pass has not yet\n   * retired emits nothing.\n   *\n   * Takes no `at`: `tick` does not touch the schedule (the just-fired deadline\n   * is exhausted; the next target is set when the result lands), so it needs no\n   * clock — keeping it trivially pure.\n   */\n  tick(state: PollerState<R>): readonly [PollerState<R>, readonly Cmd[]];\n  /**\n   * Record a successful tick observation at clock `at`.\n   *\n   * - Resets the retry counter (a success clears consecutive-failure state).\n   * - Stores `result` as `lastResult` and bumps `tick`.\n   * - Re-arms the next tick at the absolute target `at + everyMs` (the steady\n   *   cadence). It emits NO cadence `onTick` — the next observation fires from\n   *   the deadline Sub via `tick`, never immediately from a result.\n   * - Dedupe (opt-in, orthogonal to cadence): when `dedupeKey` is set, a FRESH\n   *   observation emits one `onTick` FOLLOW-UP (the consumer's \"run the\n   *   downstream side effect once per distinct observation\" hook) and a\n   *   DUPLICATE key records the sighting but suppresses the follow-up. With no\n   *   `dedupeKey`, `tickResult` emits nothing — the cadence `tick` is the only\n   *   `onTick`, so an unconfigured poller never double-fetches.\n   * - UNLESS `untilHeld` is `true` (the consumer evaluated `config.until`\n   *   against the post-result Model) — then the poller enters `\"done\"`,\n   *   disarms (`nextAtMs: null`), and emits no Cmd, dedupe or otherwise.\n   *\n   * `untilHeld` is passed in rather than computed here because `until` reads\n   * the consumer's WHOLE Model, which this verb does not hold — the consumer\n   * evaluates it at the call site after folding `result` into its Model and\n   * passes the boolean. (`subs` re-checks `phase` to decide arming, so a\n   * mis-passed `untilHeld` cannot leave a \"done\" poller arming timers.)\n   */\n  tickResult(\n    state: PollerState<R>,\n    result: R,\n    at: number,\n    untilHeld: boolean,\n  ): readonly [PollerPolling<R> | PollerDone<R>, readonly Cmd[]];\n  /**\n   * Record a FAILED tick at clock `at`. Backs off instead of holding the\n   * steady cadence:\n   *\n   * - Advances the retry counter (`recordFailure`).\n   * - If `shouldRetry` still permits another attempt, arms the next tick at\n   *   `at + nextDelayMs(retry, policy)` (the backoff curve) and emits NO Cmd —\n   *   the retry observation fires when that backoff deadline crosses and the\n   *   consumer routes `deadline_exceeded` → `tick`. The timer is the single\n   *   next-tick mechanism, on the backoff curve here instead of `everyMs`.\n   * - If backoff is exhausted (`!shouldRetry`), enters `\"gave_up\"`, disarms\n   *   (`nextAtMs: null`), and emits no Cmd.\n   *\n   * `at` is both the backoff anchor AND the streak clock: it is passed to\n   * `recordFailure` (starting / preserving `firstFailureAtMs`) and to\n   * `shouldRetry`, so a `DurationRetryPolicy` on `config.retry` is honoured\n   * with no extra wiring. Under a duration bound the poller keeps retrying\n   * however many attempts the outage takes, and stops at the declared\n   * wall-clock budget measured from the streak's FIRST failure.\n   *\n   * The backoff jitter uses the `rng` injected ONCE at `createPoller` (default\n   * `Math.random` at the effect boundary, a fixed value in tests); the verb\n   * body never names the global RNG, so a poller built with a fixed `rng`\n   * replays a failure-and-backoff run bit-for-bit.\n   */\n  tickErr(\n    state: PollerState<R>,\n    error: unknown,\n    at: number,\n  ): readonly [PollerPolling<R> | PollerGaveUp<R>, readonly Cmd[]];\n  /**\n   * The pre-wired subscriptions cell. Returns the single tick-deadline Sub\n   * while the poller is `\"polling\"` with an armed `nextAtMs`; returns `[]`\n   * once `\"done\"` / `\"gave_up\"` (the timer disarms) or before `start`. Assign\n   * directly: `subscriptions: (s) => poll.subs(s.poll)`.\n   *\n   * The `DeadlineSub` it returns is consumed by `../deadline`'s\n   * `subscribeDeadline` cell, which the consumer wires into `subscribe` —\n   * the poller does not redraw the timer lifecycle.\n   */\n  subs(state: PollerState<R>): readonly Sub[];\n}\n\n/**\n * Build a poller knob from `config`. Returns the hook bag to spread into a\n * machine (see the module doc-comment for the wiring). Pure factory — no clock\n * read, no timer; everything happens when the consumer calls the returned\n * verbs / `subs` with an injected `at`.\n *\n * `rng` is injected ONCE here (default `Math.random` at the effect boundary, a\n * fixed value in tests) and threaded internally into the backoff jitter. No\n * verb body ever names the global RNG, so a poller built with a fixed `rng`\n * replays a failure-and-backoff run bit-for-bit (invariant 2: the verbs are\n * pure given the injected `rng`).\n */\nexport function createPoller<State, R>(\n  config: PollerConfig<State, R>,\n  rng: () => number = Math.random,\n): Poller<State, R> {\n  // Re-affirm the `[0, 1)` contract at the seam where the injected generator\n  // enters the backoff math (brand from `../retry-backoff`). The factory's\n  // public param stays a plain `() => number` so transitive callers are\n  // unchanged; `asRng` is the single point where it's branded for `nextDelayMs`.\n  const rngBranded = asRng(rng);\n  const policy: AnyRetryPolicy = config.retry ?? defaultRetryPolicy;\n\n  // The dedupe store seam, bound once. The poller delegates its dedupe-window\n  // reads (`memory.isSeen`) and the per-sighting touch (`memory.remember`) to\n  // the verbs, so the `IdempotencyStore` shape stays insulated.\n  const memory = idempotencyMemory<true>();\n\n  function init(): PollerPolling<R> {\n    return {\n      phase: \"polling\",\n      tick: 0,\n      retry: initRetry(),\n      nextAtMs: null,\n      // The dedupe store is created regardless; it is only WRITTEN when\n      // `dedupeKey` is set, so an unconfigured poller carries an inert empty\n      // store (no per-op cost, JSON-serializable, durable like the rest of\n      // the slice).\n      dedupe: memory.init({ ttlMs: config.dedupeTtlMs }),\n    };\n  }\n\n  function start(\n    state: PollerState<R>,\n    at: number,\n  ): readonly [PollerPolling<R>, readonly Cmd[]] {\n    // Arm the first deadline at `at + everyMs` and emit NOTHING. The cadence has\n    // ONE source — the `everyMs` deadline Sub. `start` does not perform the\n    // first observation itself: that would be a second, immediate next-tick\n    // mechanism racing the timer (it would fire as fast as the source responds,\n    // never honoring `everyMs`). The first observation fires when the deadline\n    // crosses `at + everyMs` and the consumer routes `deadline_exceeded` → the\n    // `tick` verb (which emits `onTick`). No drift, no double-fire. Build the\n    // `polling` arm explicitly so a (re)start from a terminal state adopts a live\n    // target rather than spreading a terminal arm that never had one.\n    return [\n      {\n        phase: \"polling\",\n        tick: state.tick,\n        lastResult: state.lastResult,\n        retry: state.retry,\n        nextAtMs: at + config.everyMs,\n        dedupe: state.dedupe,\n      },\n      [],\n    ];\n  }\n\n  function tick(\n    state: PollerState<R>,\n  ): readonly [PollerState<R>, readonly Cmd[]] {\n    // The deadline fired. Perform the observation — this is the ONLY place the\n    // `onTick` Cmd is emitted, so the timer is the single next-tick mechanism.\n    // No schedule change here: the just-fired deadline is exhausted, and the\n    // NEXT target is re-armed when the observation lands (`tickResult` /\n    // `tickErr`). A no-op on a finished poller (a stale fire racing a terminal\n    // transition the reconcile pass has not yet retired).\n    if (state.phase !== \"polling\") return [state, []];\n    return [state, [config.onTick()]];\n  }\n\n  function tickResult(\n    state: PollerState<R>,\n    result: R,\n    at: number,\n    untilHeld: boolean,\n  ): readonly [PollerPolling<R> | PollerDone<R>, readonly Cmd[]] {\n    // A success always clears consecutive-failure state and records the datum.\n    // The next arm is built explicitly (not spread from `state`) so `done`\n    // carries no `nextAtMs` — a finished poll can never sit on an armed target.\n    const tick = state.tick + 1;\n\n    // Stop condition first: if the consumer's `until` held against the\n    // post-result Model, we are DONE — disarm and emit nothing, regardless of\n    // dedupe (the final observation is still recorded as `lastResult`).\n    if (untilHeld) {\n      return [\n        {\n          phase: \"done\",\n          tick,\n          lastResult: result,\n          retry: initRetry(),\n          dedupe: state.dedupe,\n        },\n        [],\n      ];\n    }\n\n    // Re-arm the steady cadence: the next observation fires when THIS deadline\n    // (`at + everyMs`) crosses and the consumer routes `deadline_exceeded` →\n    // `tick`. `tickResult` itself never emits the cadence `onTick` — the timer\n    // is the single next-tick mechanism (recording a result is not a reason to\n    // immediately re-fetch; that would poll as fast as the source responds).\n    const next: PollerPolling<R> = {\n      phase: \"polling\",\n      tick,\n      lastResult: result,\n      retry: initRetry(),\n      nextAtMs: at + config.everyMs,\n      dedupe: state.dedupe,\n    };\n\n    // Dedupe is an OPT-IN follow-up, orthogonal to the cadence above. When\n    // `dedupeKey` is set, a FRESH observation emits one `onTick` follow-up (the\n    // consumer's \"run the downstream side effect once per distinct observation\"\n    // hook); a DUPLICATE key records the sighting but suppresses that follow-up.\n    // With no `dedupeKey` there is no follow-up at all — the cadence `tick` is\n    // the only `onTick`, so an unconfigured poller never double-fetches.\n    if (!config.dedupeKey) return [next, []];\n\n    const key = config.dedupeKey(result);\n    const suppress = memory.isSeen(next.dedupe, key, at);\n    // `remember` refreshes the key's TTL clock on every sighting (the\n    // idempotency \"touch\" semantics), so a steadily-repeating observation never\n    // ages out mid-poll. The stored value is the unit `true` — the poller only\n    // needs presence, not a payload.\n    const deduped: PollerPolling<R> = {\n      ...next,\n      dedupe: memory.remember(next.dedupe, key, true, at),\n    };\n    return [deduped, suppress ? [] : [config.onTick()]];\n  }\n\n  function tickErr(\n    state: PollerState<R>,\n    error: unknown,\n    at: number,\n  ): readonly [PollerPolling<R> | PollerGaveUp<R>, readonly Cmd[]] {\n    // `at` is the failure's OBSERVATION instant, already carried in from the\n    // Msg — so it doubles as the streak clock a duration bound is measured\n    // against. The first failure of a streak sets `firstFailureAtMs`; every\n    // later one preserves it, and a success resets to `initRetry()` (dropping\n    // the origin with it). Nothing here reads a clock: `at` is Msg data,\n    // exactly as `rng` is factory-injected data (invariant 2).\n    const retry = recordFailure(state.retry, error, at);\n    const tick = state.tick + 1;\n\n    // Backoff exhausted → give up: emit nothing. `shouldRetry` reads the\n    // just-advanced `retry`, so under a count bound the (maxAttempts)-th\n    // failure is the one that stops the poller, and under a duration bound the\n    // first failure observed at or past `firstFailureAtMs + maxElapsedMs` is.\n    // The `gave_up` arm carries no `nextAtMs` — there is no next attempt to arm.\n    if (!shouldRetry(retry, policy, at)) {\n      return [\n        {\n          phase: \"gave_up\",\n          tick,\n          lastResult: state.lastResult,\n          retry,\n          dedupe: state.dedupe,\n        },\n        [],\n      ];\n    }\n\n    // Back off: arm the next attempt at `at + backoff(retry)` rather than the\n    // steady cadence, and emit NOTHING. The retry observation fires when this\n    // backoff deadline crosses and the consumer routes `deadline_exceeded` →\n    // `tick` — the timer is the single next-tick mechanism, on the backoff\n    // curve here instead of `everyMs`. `rng` is the value injected once at\n    // `createPoller`; the verb body never names the global RNG, so a fixed\n    // `rng` makes the backoff target replay bit-for-bit.\n    const delayMs = nextDelayMs(retry, policy, rngBranded);\n    return [\n      {\n        phase: \"polling\",\n        tick,\n        lastResult: state.lastResult,\n        retry,\n        nextAtMs: at + delayMs,\n        dedupe: state.dedupe,\n      },\n      [],\n    ];\n  }\n\n  function subs(state: PollerState<R>): readonly Sub[] {\n    // Arm the tick deadline only while live. `phase` is the authority (so a\n    // mis-passed `untilHeld` into `tickResult` cannot resurrect a finished\n    // poller); `nextAtMs` is the absolute target `../deadline` translates to a\n    // remaining delay at subscribe time — a resumed poller re-arms the exact\n    // persisted moment.\n    if (state.phase !== \"polling\" || state.nextAtMs === null) return [];\n    // The Sub id ROTATES with the target. A one-shot deadline timer is\n    // exhausted once it fires, and the substrate's reconcile pass keys identity\n    // by `id` alone — a fixed id would leave the fired timer in the registry and\n    // NEVER re-arm for the next cadence (cadence dies after one tick). Folding\n    // `nextAtMs` into the id makes each successive target a distinct identity:\n    // the reconcile pass retires the spent timer (old id absent from the desired\n    // set) and arms the next one (new id). A resumed poller re-arms the SAME id\n    // from its persisted `nextAtMs`, so eviction is idempotent.\n    return [deadlineSub(pollerSubId(state.nextAtMs), state.nextAtMs)];\n  }\n\n  return { init, start, tick, tickResult, tickErr, subs };\n}\n"]}