@demlik/tea 0.5.1 → 0.7.0

package/dist/poller/index.d.ts

@@ -1,8 +1,8 @@
 import { DeadlineSub } from '../deadline/index.js';
 import { IdempotencyStore } from '../idempotency/index.js';
-import { C as Cmd, S as Sub } from '../core-JPHsMZVB.js';
+import { C as Cmd, S as Sub } from '../core-Bjc0bS8j.js';
 import { RetryState, AnyRetryPolicy } from '../retry-backoff/index.js';
-import '../types-BMZ7IMrd.js';
+import '../types-D7u9DkH7.js';
 
 /**
  * @demlik/tea/poller — "poll a source every N ms until a predicate holds, with
@@ -203,6 +203,27 @@ type PollerState<R> = (PollerCore<R> & {
 }) | (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
@@ -223,7 +244,7 @@ type PollerSub = DeadlineSub;
  */
 interface Poller<State, R> {
     /** Seed the Model slice. Idle until `start(...)` arms the first tick. */
-    init(): PollerState<R>;
+    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
@@ -234,7 +255,7 @@ interface Poller<State, R> {
      * fires when the deadline crosses `at + everyMs` and the consumer routes
      * `deadline_exceeded` → `tick`.
      */
-    start(state: PollerState<R>, at: number): readonly [PollerState<R>, readonly Cmd[]];
+    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
@@ -274,7 +295,7 @@ interface Poller<State, R> {
      * 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 [PollerState<R>, readonly Cmd[]];
+    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:
@@ -300,7 +321,7 @@ interface Poller<State, R> {
      * 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 [PollerState<R>, readonly Cmd[]];
+    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 `[]`
@@ -327,4 +348,4 @@ interface Poller<State, R> {
  */
 declare function createPoller<State, R>(config: PollerConfig<State, R>, rng?: () => number): Poller<State, R>;
 
-export { type Poller, type PollerConfig, type PollerState, type PollerSub, createPoller };
+export { type Poller, type PollerConfig, type PollerDone, type PollerGaveUp, type PollerPolling, type PollerState, type PollerSub, createPoller };

package/dist/poller/index.js

@@ -1,10 +1,10 @@
-import { deadlineSub } from '../chunk-ASX7PL2K.js';
+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-ZH454CR5.js';
-import '../chunk-O7ED34JH.js';
+import '../chunk-5EHLEUTL.js';
+import '../chunk-B5VXOFMZ.js';
 
 // src/poller/index.ts
 function pollerSubId(atMs) {

package/dist/poller/index.js.map

@@ -1 +1 @@
-{"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 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(): PollerState<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 [PollerState<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 [PollerState<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 [PollerState<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(): PollerState<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 [PollerState<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 [PollerState<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: PollerState<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: PollerState<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 [PollerState<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"]}
+{"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"]}

package/dist/prediction/index.d.ts

@@ -1,4 +1,4 @@
-import { C as Cmd, S as Sub, M as Machine } from '../core-JPHsMZVB.js';
+import { C as Cmd, S as Sub, M as Machine } from '../core-Bjc0bS8j.js';
 
 /**
  * @demlik/tea/prediction — the client-prediction ack primitive (epic #186, facet 2).

package/dist/prediction/index.js

@@ -1,4 +1,4 @@
-export { NO_ACK, ack, initAck, nextSeq, partitionByAck, reconcile, tagSeq } from '../chunk-AZ3NHUPD.js';
-import '../chunk-O7ED34JH.js';
+export { NO_ACK, ack, initAck, nextSeq, partitionByAck, reconcile, tagSeq } from '../chunk-4KTWLPL5.js';
+import '../chunk-B5VXOFMZ.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/pure/index.d.ts

@@ -1,2 +1,2 @@
 export { Ack, AckPartition, NO_ACK, Seq, SeqTagged, ack, initAck, nextSeq, partitionByAck, reconcile, tagSeq } from '../prediction/index.js';
-export { C as Cmd, d as ContextFree, D as DepKeyedSub, e as Dispose, f as Identity, I as Interpret, c as InterpretDetached, M as Machine, N as NoCellError, g as NoCtx, a as Port, P as PortEmitter, R as Reducer, S as Sub, b as SubId, h as Subscribe, i as SyncReturn, T as Transitions, U as UpdateForm, k as detectUpdateForm, l as foldMsgs, m as formOf, s as structuralHash, o as subId } from '../core-JPHsMZVB.js';
+export { C as Cmd, d as ContextFree, D as DepKeyedSub, e as Dispose, f as Identity, I as Interpret, c as InterpretDetached, M as Machine, g as MachineShape, N as NoCellError, h as NoCtx, a as Port, P as PortEmitter, R as Reducer, S as Sub, b as SubId, i as Subscribe, j as SyncReturn, T as Transitions, U as UpdateForm, k as acceptsOf, n as describeMachine, o as detectUpdateForm, p as foldMsgs, r as formOf, t as structuralHash, u as subId } from '../core-Bjc0bS8j.js';

package/dist/pure/index.js

@@ -1,4 +1,4 @@
-export { NO_ACK, ack, initAck, nextSeq, partitionByAck, reconcile, tagSeq } from '../chunk-AZ3NHUPD.js';
-export { Cmd, NoCellError, detectUpdateForm, foldMsgs, formOf, structuralHash, subId } from '../chunk-O7ED34JH.js';
+export { NO_ACK, ack, initAck, nextSeq, partitionByAck, reconcile, tagSeq } from '../chunk-4KTWLPL5.js';
+export { Cmd, NoCellError, acceptsOf, describeMachine, detectUpdateForm, foldMsgs, formOf, structuralHash, subId } from '../chunk-B5VXOFMZ.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/react/index.d.ts

@@ -1,5 +1,6 @@
-import { S as Store, R as Runtime } from '../runtime-types-BbBq4LWo.js';
-import { C as Cmd, S as Sub, M as Machine } from '../core-JPHsMZVB.js';
+import { S as Store, R as Runtime } from '../runtime-types-Bxc637bp.js';
+import { C as Cmd, S as Sub, M as Machine } from '../core-Bjc0bS8j.js';
+import 'better-result';
 
 /**
  * @packageDocumentation

package/dist/react/index.js

@@ -1,5 +1,5 @@
-import { run } from '../chunk-ZH454CR5.js';
-import '../chunk-O7ED34JH.js';
+import { run } from '../chunk-5EHLEUTL.js';
+import '../chunk-B5VXOFMZ.js';
 import { useMemo, useRef, useReducer, useSyncExternalStore, useEffect } from 'react';
 
 function useMachine(machine, opts) {

package/dist/reconciler/index.d.ts

@@ -1,6 +1,6 @@
 import { CircuitConfig, RateLimitConfig, DeadlineConfig, ResilientPorts, RunCmd, FailMsg, SucceedMsg } from '../resilient-call/index.js';
 import { TtlCache } from '../cache/index.js';
-import { C as Cmd } from '../core-JPHsMZVB.js';
+import { C as Cmd } from '../core-Bjc0bS8j.js';
 import { PaginatedWalkState, PaginatedWalkTimerMsg, FetchPageCmd, PageErrMsg, PageOkMsg } from '../paginated-walk/index.js';
 import { RetryPolicy } from '../retry-backoff/index.js';
 import { DeadlineSub } from '../deadline/index.js';
@@ -8,7 +8,7 @@ export { deadlineSub, subscribeDeadline } from '../deadline/index.js';
 import '../circuit-breaker/index.js';
 import '../protocol-B5YmJr0d.js';
 import '../rate-limit/index.js';
-import '../types-BMZ7IMrd.js';
+import '../types-D7u9DkH7.js';
 import '../paginator/index.js';
 
 /**

package/dist/reconciler/index.js

@@ -1,17 +1,17 @@
-import { createPaginatedWalk, PAGE_KEY } from '../chunk-XOAP3LOT.js';
+import { createPaginatedWalk, PAGE_KEY } from '../chunk-I5OV65MS.js';
 import '../chunk-SINXE47Y.js';
-import '../chunk-EC6FO42Q.js';
+import '../chunk-EUF7XOEE.js';
 import '../chunk-JELSZN25.js';
-export { deadlineSub, subscribeDeadline } from '../chunk-ASX7PL2K.js';
+export { deadlineSub, subscribeDeadline } from '../chunk-JGVL3WPL.js';
 import '../chunk-Q2UM7BXU.js';
 import '../chunk-S2EGRPCM.js';
 import '../chunk-UF4MZSLT.js';
-import { initCache, get, set } from '../chunk-WF46FABO.js';
-import '../chunk-2UGTDYOK.js';
+import { initCache, get, set } from '../chunk-7SVIRMC6.js';
+import '../chunk-3JU6657S.js';
 import '../chunk-2YFLOCWX.js';
 import '../chunk-ZJ5AOYBH.js';
-import '../chunk-ZH454CR5.js';
-import '../chunk-O7ED34JH.js';
+import '../chunk-5EHLEUTL.js';
+import '../chunk-B5VXOFMZ.js';
 
 // src/reconciler/index.ts
 function createReconciler(config, rng = Math.random) {

package/dist/recorder/index.d.ts

@@ -1,5 +1,6 @@
-import { B as BootingRuntime } from '../runtime-types-BbBq4LWo.js';
-import '../core-JPHsMZVB.js';
+import { B as BootingRuntime } from '../runtime-types-Bxc637bp.js';
+import 'better-result';
+import '../core-Bjc0bS8j.js';
 
 /**
  * A recorded run, sufficient to reproduce it via `../trace-replay`.

package/dist/resilient-call/index.d.ts

@@ -2,11 +2,11 @@ import { TtlCache } from '../cache/index.js';
 import { CircuitState } from '../circuit-breaker/index.js';
 import { DeadlineExceeded, DeadlineSub } from '../deadline/index.js';
 export { deadlineSub, subscribeDeadline } from '../deadline/index.js';
-import { C as Cmd } from '../core-JPHsMZVB.js';
+import { C as Cmd } from '../core-Bjc0bS8j.js';
 import { M as MsgType } from '../protocol-B5YmJr0d.js';
 import { TokenBucket } from '../rate-limit/index.js';
 import { RetryState, AnyRetryPolicy } from '../retry-backoff/index.js';
-import '../types-BMZ7IMrd.js';
+import '../types-D7u9DkH7.js';
 
 /**
  * @packageDocumentation

package/dist/resilient-call/index.js

@@ -1,14 +1,14 @@
-export { createResilientCall, liftResilience } from '../chunk-EC6FO42Q.js';
+export { createResilientCall, liftResilience } from '../chunk-EUF7XOEE.js';
 import '../chunk-JELSZN25.js';
-export { deadlineSub, subscribeDeadline } from '../chunk-ASX7PL2K.js';
+export { deadlineSub, subscribeDeadline } from '../chunk-JGVL3WPL.js';
 import '../chunk-Q2UM7BXU.js';
 import '../chunk-S2EGRPCM.js';
 import '../chunk-UF4MZSLT.js';
-import '../chunk-WF46FABO.js';
-import '../chunk-2UGTDYOK.js';
+import '../chunk-7SVIRMC6.js';
+import '../chunk-3JU6657S.js';
 import '../chunk-2YFLOCWX.js';
 import '../chunk-ZJ5AOYBH.js';
-import '../chunk-ZH454CR5.js';
-import '../chunk-O7ED34JH.js';
+import '../chunk-5EHLEUTL.js';
+import '../chunk-B5VXOFMZ.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/{runtime-types-BbBq4LWo.d.ts → runtime-types-Bxc637bp.d.ts}

@@ -1,4 +1,5 @@
-import { a as Port, C as Cmd, R as Reducer, S as Sub, M as Machine, T as Transitions, c as InterpretDetached, P as PortEmitter } from './core-JPHsMZVB.js';
+import { Result } from 'better-result';
+import { a as Port, N as NoCellError, C as Cmd, R as Reducer, S as Sub, M as Machine, T as Transitions, U as UpdateForm, c as InterpretDetached, P as PortEmitter } from './core-Bjc0bS8j.js';
 
 /**
  * @demlik/tea runtime interface surface + pure helpers — the public types,
@@ -446,6 +447,56 @@ declare function replay<S, M extends {
 declare function wrapDetached<C extends Cmd, M extends {
     type: string;
 }, Allowed extends M, Ctx>(handler: InterpretDetached<C, Allowed, Ctx>): (cmd: C, ctx: Ctx & PortEmitter, dispatch?: (msg: M) => void) => Promise<void>;
+/**
+ * `applyCell` with the missing-cell case in the return type.
+ *
+ * `Ok` carries the cell's `[nextState, cmds]` verbatim; `Err` carries the same
+ * `NoCellError` (msg.type + state name) `applyCell` would have thrown. Dispatch
+ * inside `run` keeps using the throwing `applyCell` — this is for callers that
+ * step a machine themselves.
+ */
+declare function tryApplyCell<S, M extends {
+    type: string;
+}, C extends Cmd>(machine: {
+    update: object;
+    __form?: UpdateForm;
+}, state: S, msg: M): Result<readonly [S, readonly C[]], NoCellError>;
+/**
+ * The refusal `tryFoldMsgs` reports: WHICH msg in the log had no cell, where.
+ *
+ * A plain record, not a new `Error` subclass — it is a `Result` payload, never
+ * thrown, and the actual error is the existing `NoCellError` it carries. The
+ * package's thrown-error idiom (`class extends Error` + `_tag`, pinned by
+ * `error-idiom.test.ts`) applies to errors raised at the runtime edge; this one
+ * is never raised, so adding a class would state a promise it does not make.
+ */
+interface FoldRefusal<M> {
+    /** Index into the `msgs` array the fold was given. */
+    readonly index: number;
+    /** The offending Msg itself — so the caller can print it, not just point. */
+    readonly msg: M;
+    /** The underlying cell-lookup failure, carrying msg.type + state name. */
+    readonly error: NoCellError;
+}
+/**
+ * `foldMsgs` with the missing-cell case in the return type, INCLUDING which
+ * message failed.
+ *
+ * The motivating use is "this persisted log does not replay — tell the user
+ * where". A bare `Result<S, NoCellError>` cannot: the error names the msg.type
+ * and the state, but a log usually contains that type many times, so the
+ * INDEX is the load-bearing fact. The fold stops at the first refusal (state
+ * past that point is not defined) and returns it.
+ *
+ * Shares `foldMsgs`' dev-mode discipline: `deepFreeze` the input state,
+ * `assertPureResult` the cell's return. Both compile out of production.
+ */
+declare function tryFoldMsgs<S, M extends {
+    type: string;
+}, C extends Cmd>(machine: {
+    update: object;
+    __form?: UpdateForm;
+}, base: S, msgs: readonly M[]): Result<S, FoldRefusal<M>>;
 declare function tryInterpret<C extends Cmd, Ok, M, Ctx>(work: (cmd: C, ctx: Ctx) => Promise<Ok>, onOk: (value: Ok, cmd: C) => M, onErr: (error: unknown, cmd: C) => M): (cmd: C, ctx: Ctx) => Promise<M>;
 
-export { type BootingRuntime as B, type CtxArg as C, DispatchDiscardedError as D, IdentityDropNotice as I, type OnError as O, PortNameCollisionError as P, QuiescenceTimeoutError as Q, type Runtime as R, type Store as S, __resetPortRegistry as _, type Supervision as a, type Branded as b, type DispatchSettle as c, DisposeTimeoutNotice as d, RuntimeDiscardNotice as e, RuntimeDiscardedError as f, type RuntimeErrorContext as g, type RuntimeErrorPhase as h, type RuntimeRef as i, type Schema as j, SubIdCollisionError as k, type SupervisionStrategy as l, absurd as m, asReducer as n, defineMachine as o, definePort as p, noop as q, replay as r, schemaMigrate as s, tryInterpret as t, wrapDetached as w };
+export { type BootingRuntime as B, type CtxArg as C, DispatchDiscardedError as D, type FoldRefusal as F, IdentityDropNotice as I, type OnError as O, PortNameCollisionError as P, QuiescenceTimeoutError as Q, type Runtime as R, type Store as S, __resetPortRegistry as _, type Supervision as a, type Branded as b, type DispatchSettle as c, DisposeTimeoutNotice as d, RuntimeDiscardNotice as e, RuntimeDiscardedError as f, type RuntimeErrorContext as g, type RuntimeErrorPhase as h, type RuntimeRef as i, type Schema as j, SubIdCollisionError as k, type SupervisionStrategy as l, absurd as m, asReducer as n, defineMachine as o, definePort as p, noop as q, replay as r, schemaMigrate as s, tryApplyCell as t, tryFoldMsgs as u, tryInterpret as v, wrapDetached as w };

package/dist/saga/index.d.ts

@@ -1,6 +1,7 @@
-import { C as Cmd } from '../core-JPHsMZVB.js';
+import { C as Cmd } from '../core-Bjc0bS8j.js';
 import { QueueItem } from '../work-queue/index.js';
-import '../runtime-types-BbBq4LWo.js';
+import '../runtime-types-Bxc637bp.js';
+import 'better-result';
 
 /**
  * @packageDocumentation

package/dist/snapshot/index.d.ts

@@ -1,4 +1,4 @@
-import { C as Cmd, I as Interpret } from '../core-JPHsMZVB.js';
+import { C as Cmd, I as Interpret } from '../core-Bjc0bS8j.js';
 
 /**
  * @demlik/tea/snapshot — periodic state checkpoint to a host store (R2/KV-shaped).

package/dist/snapshot/index.js

@@ -1,5 +1,5 @@
-export { createSnapshot, snapshotFailed, snapshotLoadFailed, snapshotLoaded, snapshotSaved } from '../chunk-XMHZ44QC.js';
-import '../chunk-ZH454CR5.js';
-import '../chunk-O7ED34JH.js';
+export { createSnapshot, snapshotFailed, snapshotLoadFailed, snapshotLoaded, snapshotSaved } from '../chunk-7V4EVLZA.js';
+import '../chunk-5EHLEUTL.js';
+import '../chunk-B5VXOFMZ.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/subs/index.d.ts

@@ -1,6 +1,7 @@
-import { S as Sub, a as Port, e as Dispose, D as DepKeyedSub, b as SubId } from '../core-JPHsMZVB.js';
-import { S as SubscribeHandler } from '../types-BMZ7IMrd.js';
-import { R as Runtime } from '../runtime-types-BbBq4LWo.js';
+import { S as Sub, a as Port, e as Dispose, D as DepKeyedSub, b as SubId } from '../core-Bjc0bS8j.js';
+import { S as SubscribeHandler } from '../types-D7u9DkH7.js';
+import { R as Runtime } from '../runtime-types-Bxc637bp.js';
+import 'better-result';
 
 /**
  * The imperative listener target, expressed as the `add`/`remove` pair the

package/dist/subs/index.js

@@ -1,7 +1,7 @@
-export { combineManagedResources, defineListener, defineManagedResource, fromBroadcastChannel, fromEventSource, fromEventTarget, fromInterval, fromPort, fromReconnectingWebSocket, fromTransport, fromWebSocket } from '../chunk-2UGTDYOK.js';
+export { combineManagedResources, defineListener, defineManagedResource, fromBroadcastChannel, fromEventSource, fromEventTarget, fromInterval, fromPort, fromReconnectingWebSocket, fromTransport, fromWebSocket } from '../chunk-3JU6657S.js';
 export { fromTimeout } from '../chunk-2YFLOCWX.js';
 import '../chunk-ZJ5AOYBH.js';
-import '../chunk-ZH454CR5.js';
-import '../chunk-O7ED34JH.js';
+import '../chunk-5EHLEUTL.js';
+import '../chunk-B5VXOFMZ.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/testing/index.d.ts

@@ -1,5 +1,6 @@
-import { C as Cmd, S as Sub, M as Machine } from '../core-JPHsMZVB.js';
-import { R as Runtime } from '../runtime-types-BbBq4LWo.js';
+import { C as Cmd, S as Sub, M as Machine } from '../core-Bjc0bS8j.js';
+import { R as Runtime } from '../runtime-types-Bxc637bp.js';
+import 'better-result';
 
 /**
  * The composed Model shape every `withX` wrapper produces: the base machine's

package/dist/testing/index.js

@@ -1,5 +1,5 @@
-import { replay } from '../chunk-ZH454CR5.js';
-import '../chunk-O7ED34JH.js';
+import { replay } from '../chunk-5EHLEUTL.js';
+import '../chunk-B5VXOFMZ.js';
 import { expect, vi } from 'vitest';
 
 function assertWrapperFaithful(base, makeWrapped, opts) {

package/dist/throttled-input/index.d.ts

@@ -1,10 +1,10 @@
 import { TtlCache } from '../cache/index.js';
 import { DeadlineSub } from '../deadline/index.js';
 export { DeadlineExceeded as ThrottledInputSettled, subscribeDeadline as subscribeThrottledInput, deadlineExceeded as throttledInputSettled } from '../deadline/index.js';
-import { C as Cmd, S as Sub } from '../core-JPHsMZVB.js';
+import { C as Cmd, S as Sub } from '../core-Bjc0bS8j.js';
 export { Debounced, debounce } from '../debounce/index.js';
 export { Throttled, throttle } from '../throttle/index.js';
-import '../types-BMZ7IMrd.js';
+import '../types-D7u9DkH7.js';
 
 /**
  * @demlik/tea/throttled-input — gate a high-frequency input stream into a

package/dist/throttled-input/index.js

@@ -1,13 +1,13 @@
 export { debounce } from '../chunk-J6527VRQ.js';
 export { throttle } from '../chunk-HCEVHFJ7.js';
-import { deadlineSub } from '../chunk-ASX7PL2K.js';
-export { subscribeDeadline as subscribeThrottledInput, deadlineExceeded as throttledInputSettled } from '../chunk-ASX7PL2K.js';
-import { initCache, get, set } from '../chunk-WF46FABO.js';
-import '../chunk-2UGTDYOK.js';
+import { deadlineSub } from '../chunk-JGVL3WPL.js';
+export { subscribeDeadline as subscribeThrottledInput, deadlineExceeded as throttledInputSettled } from '../chunk-JGVL3WPL.js';
+import { initCache, get, set } from '../chunk-7SVIRMC6.js';
+import '../chunk-3JU6657S.js';
 import '../chunk-2YFLOCWX.js';
 import '../chunk-ZJ5AOYBH.js';
-import '../chunk-ZH454CR5.js';
-import '../chunk-O7ED34JH.js';
+import '../chunk-5EHLEUTL.js';
+import '../chunk-B5VXOFMZ.js';
 
 // src/throttled-input/index.ts
 var DEFAULT_SUB_ID = "throttled-input:settle";

package/dist/token-refresh/index.d.ts

@@ -1,4 +1,4 @@
-import { C as Cmd, I as Interpret } from '../core-JPHsMZVB.js';
+import { C as Cmd, I as Interpret } from '../core-Bjc0bS8j.js';
 import { M as MsgType } from '../protocol-B5YmJr0d.js';
 
 /**

package/dist/token-refresh/index.js

@@ -1,6 +1,6 @@
-export { createTokenRefresh, initTokenRefresh, refreshTokenCmd, tokenRefreshFailedMsg, tokenRefreshedMsg } from '../chunk-2KBEIGYP.js';
+export { createTokenRefresh, initTokenRefresh, refreshTokenCmd, tokenRefreshFailedMsg, tokenRefreshedMsg } from '../chunk-TP5UPGLY.js';
 import '../chunk-JELSZN25.js';
-import '../chunk-ZH454CR5.js';
-import '../chunk-O7ED34JH.js';
+import '../chunk-5EHLEUTL.js';
+import '../chunk-B5VXOFMZ.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/trace-replay/index.d.ts

@@ -1,6 +1,7 @@
-import { C as Cmd, S as Sub, M as Machine } from '../core-JPHsMZVB.js';
+import { C as Cmd, S as Sub, M as Machine } from '../core-Bjc0bS8j.js';
 import { Trace } from '../recorder/index.js';
-import '../runtime-types-BbBq4LWo.js';
+import '../runtime-types-Bxc637bp.js';
+import 'better-result';
 
 /**
  * The outcome of {@link replayTrace}.

package/dist/trace-replay/index.js

@@ -1,6 +1,6 @@
-export { deepEqual, replayTrace } from '../chunk-A7USKARI.js';
+export { deepEqual, replayTrace } from '../chunk-SUST46KO.js';
 import '../chunk-EWJP3YYP.js';
-import '../chunk-ZH454CR5.js';
-import '../chunk-O7ED34JH.js';
+import '../chunk-5EHLEUTL.js';
+import '../chunk-B5VXOFMZ.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map