@demlik/tea 0.14.0 → 0.16.0

package/dist/timing/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/internal/timing/throttle/index.ts","../../src/internal/timing/throttled-input/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * internal/timing/throttle — a timer-based call transformer that caps invocation\n * to at most once per `ms` window.\n *\n * Sibling of `../debounce` — the two share a SYMMETRIC surface\n * (`Throttled<A>` / `Debounced<A>`, both callable + `.cancel()` + `.flush()`,\n * both `{ leading?, trailing? }`) so they read as a pair. They are kept in\n * separate files with NO cross-import: each is a self-contained timer, and the\n * coalesce-vs-drop policies differ enough that sharing code would hide the\n * distinction. The contrast IS the lesson:\n *\n *   - **debounce** waits for quiet — fires once AFTER a burst settles.\n *   - **throttle** enforces a rate — fires AT MOST once per `ms` while the\n *     burst is ongoing, dropping the calls in between.\n *\n * Layering with `../throttled-input`: `throttle` and `debounce` are\n * the two host-boundary PRIMITIVES — two distinct algorithms\n * (at-most-once-per-window vs collapse-a-burst) behind one signature shape.\n * `throttled-input` is NOT a third primitive: it is a TEA machine composed\n * OVER them (the same semantics, reimplemented as pure, durable Model state)\n * that re-exports both. Wrapping a raw host event → these primitives; durable, replayable\n * gating inside a machine → `throttled-input` (see its module doc for the full\n * layering map).\n *\n * WHAT THIS IS NOT — and why it lives outside `update`:\n *\n *   - NOT a reducer / Transitions cell. Reducers are PURE (invariant 2 — same\n *     inputs → same outputs, no `Date.now`, no timers). A throttle holds a live\n *     `setTimeout` handle and a window cursor; folding it into `update` would\n *     smuggle a timer into the pure core.\n *   - NOT a Sub. A Sub is a continuous SOURCE of Msgs the substrate reconciles\n *     by id every transition (invariant 4). A throttle is a SINK transformer:\n *     it wraps a `void`-returning handler (the canonical one is\n *     `Runtime.dispatch`) so a high-frequency HOST event is rate-limited BEFORE\n *     it ever becomes a Msg.\n *\n * It is a higher-order function at the host boundary (pattern 14 — TEA owns\n * state, JS owns timing). The host attaches the wrapped function to a\n * high-frequency event source (`mousemove`, `scroll`, `pointermove`, a game\n * loop) and the substrate downstream only ever sees the rate-limited Msg:\n *\n *   const onMoved = throttle(\n *     (e: PointerEvent) =>\n *       runtime.dispatch({ type: \"UserMovedCursor\", x: e.clientX, y: e.clientY }),\n *     16, // ~60fps cap\n *   );\n *   window.addEventListener(\"pointermove\", onMoved);\n *   // cleanup: onMoved.cancel(); window.removeEventListener(\"pointermove\", onMoved);\n *\n * Internal since #47 — not published on any subpath; reached from inside the\n * package as `internal/timing/throttle`. Same one-shape-per-package rule as\n * `rate-limit`, `deadline`, and `work-queue`.\n *\n * Uses the universal `setTimeout` / `clearTimeout` timer idiom (same discipline\n * as `subs/from-timeout.ts`): exactly one live handle at a time, the window\n * timer clears itself on expiry, `cancel` / `flush` clear and null it so a\n * stale callback can never run.\n */\n\n/**\n * A throttled wrapper around `fn`. Callable with the SAME argument tuple as\n * `fn` — `(...args: A) => void` — plus two control methods that share names and\n * shapes with `Debounced<A>` so the two modules read as a symmetric pair.\n */\nexport interface Throttled<A extends readonly unknown[]> {\n  /** Invoke `fn` if the window is open, else record args for the trailing fire. */\n  (...args: A): void;\n  /**\n   * Drop any pending trailing fire WITHOUT invoking `fn`, and close the active\n   * window. Clears the timer, forgets the captured trailing args, and resets\n   * the cursor so the next call fires immediately on the leading edge (if\n   * `leading` is enabled). Idempotent.\n   *\n   * The host-cleanup partner of `removeEventListener`: cancel the pending fire\n   * when the component unmounts / the listener detaches, so a queued\n   * `dispatch` can't land after teardown.\n   */\n  cancel(): void;\n  /**\n   * Fire any pending trailing call IMMEDIATELY with its latest captured args,\n   * then close the window. No-op when nothing is pending. Use to force the last\n   * dropped call out early — e.g. flush the final cursor position when a drag\n   * ends, so the rest state isn't a stale mid-drag sample.\n   */\n  flush(): void;\n}\n\n/**\n * Wrap `fn` so it runs AT MOST once per `ms` window, no matter how often it is\n * called.\n *\n * Leading + trailing (the default): the first call fires `fn` IMMEDIATELY (the\n * leading edge) and opens a `ms` window. Calls during the window are dropped\n * from immediate firing but their args are remembered; when the window closes,\n * `fn` fires ONCE more with the LATEST dropped args (the trailing edge) and a\n * new window opens. A call after the window has already closed leads a fresh\n * window immediately. Spacing every call at least `ms` apart therefore fires\n * each one on its own leading edge.\n *\n * @param fn   The handler to rate-limit. Typically `(...) => runtime.dispatch(...)`,\n *             but any `(...args: A) => void` works. The return value is\n *             ignored — throttle is a fire transformer, not a value pipe.\n * @param ms   Window length in milliseconds. `fn` fires at most once per `ms`.\n * @param opts.leading   Fire on the FIRST call of a window (the leading edge),\n *             immediately. Default `true`.\n * @param opts.trailing  Fire once at window END with the latest args dropped\n *             during the window. Default `true`.\n *\n * Edge combinations (matching lodash's settled semantics, the de-facto\n * standard the ecosystem rediscovered):\n *\n *   - `{ leading: true, trailing: true }` (default): immediate fire + a\n *     trailing fire per window while calls keep arriving. The trailing fire is\n *     SUPPRESSED when no extra call arrived during the window (a lone call\n *     already fired on the leading edge — no stale trailing double-fire).\n *   - `{ leading: true, trailing: false }`: only the immediate fire; everything\n *     in the window is dropped with no catch-up at the end.\n *   - `{ leading: false, trailing: true }`: no immediate fire; the FIRST call\n *     opens a window and `fn` fires at the window's end with the latest args.\n *     Steady \"sample every `ms`\" behavior with no instant response.\n *   - `{ leading: false, trailing: false }`: never fires. Degenerate but legal;\n *     we don't throw — the caller asked for a no-op transformer.\n *\n * WHY a default of leading + trailing both `true`: a throttle's job is \"respond\n * now, then keep responding at a steady rate.\" Leading gives the instant\n * response (the first `mousemove` updates immediately); trailing guarantees the\n * FINAL sample of a window isn't lost (the cursor ends where the user actually\n * left it, not one window-width behind). Dropping either loses one of those two\n * guarantees, so both default on.\n */\nexport function throttle<A extends readonly unknown[]>(\n  fn: (...args: A) => void,\n  ms: number,\n  opts?: { leading?: boolean; trailing?: boolean },\n): Throttled<A> {\n  const leading = opts?.leading ?? true;\n  const trailing = opts?.trailing ?? true;\n\n  // Exactly one live handle at a time (the from-timeout discipline). `null`\n  // when no window is open — the single source of truth for \"is a window\n  // active?\". The window timer arms on a fire and clears itself on expiry; the\n  // call path never stacks overlapping timers.\n  let handle: ReturnType<typeof setTimeout> | null = null;\n  // The latest args seen DURING an open window, held for the trailing fire.\n  // Overwritten by every dropped call (the trailing edge fires with the LAST\n  // args), cleared the instant we fire / cancel. `null` (not `undefined`) is\n  // the empty sentinel because `A` may itself contain `undefined` elements — a\n  // present-but-empty tuple is still a pending call, distinct from \"nothing\n  // pending\".\n  let pendingArgs: A | null = null;\n\n  function clearHandle(): void {\n    if (handle !== null) {\n      clearTimeout(handle);\n      handle = null;\n    }\n  }\n\n  // Window expiry: the `ms` window just closed. If a call arrived during the\n  // window (`pendingArgs !== null`) and trailing is enabled, fire it now and\n  // open a FRESH window so the rate cap continues across a sustained burst.\n  // If nothing was dropped, let the window close (handle → null) so the next\n  // call leads a new window immediately.\n  function onWindowExpired(): void {\n    if (trailing && pendingArgs !== null) {\n      const args = pendingArgs;\n      pendingArgs = null;\n      // Re-arm BEFORE firing so a re-entrant call from inside `fn` sees an open\n      // window (and is correctly dropped/queued) rather than leading a second\n      // window — keeps the \"at most once per `ms`\" invariant under re-entry.\n      handle = setTimeout(onWindowExpired, ms);\n      fn(...args);\n    } else {\n      // No trailing fire owed — close the window.\n      handle = null;\n    }\n  }\n\n  const throttled = (...args: A): void => {\n    if (handle === null) {\n      // Window is closed → this call leads a new window.\n      if (leading) {\n        fn(...args);\n      } else if (trailing) {\n        // No leading fire, but trailing wants the first call's args so the\n        // window's end has something to fire. Without this, a leading:false\n        // throttle would swallow a lone call entirely.\n        pendingArgs = args;\n      }\n      handle = setTimeout(onWindowExpired, ms);\n    } else if (trailing) {\n      // Window is open → drop this call from immediate firing, but remember its\n      // args as the latest candidate for the trailing edge.\n      pendingArgs = args;\n    }\n    // Window open + trailing disabled → pure drop, nothing to remember.\n  };\n\n  throttled.cancel = (): void => {\n    clearHandle();\n    pendingArgs = null;\n  };\n\n  throttled.flush = (): void => {\n    // Force the pending trailing fire out now and close the window. Mirrors\n    // `onWindowExpired`'s fire branch but is caller-driven, so it tears the\n    // timer down rather than re-arming.\n    if (pendingArgs !== null) {\n      const args = pendingArgs;\n      pendingArgs = null;\n      clearHandle();\n      fn(...args);\n    } else {\n      // Nothing pending — still close a lingering window so a post-flush call\n      // leads cleanly.\n      clearHandle();\n    }\n  };\n\n  return throttled;\n}\n","/**\n * internal/timing/throttled-input — gate a high-frequency input stream into a\n * SETTLED, RATE-CAPPED, optionally DEDUPED sequence of emits, as a TEA knob: one\n * config object + a few pre-wired hooks you spread into your machine.\n *\n * Layering (the throttle-family map): `../throttle` and `../debounce` are the\n * two host-boundary PRIMITIVES — two distinct algorithms\n * (at-most-once-per-window vs collapse-a-burst) behind one signature shape.\n * THIS module is the third name but NOT a third primitive: a TEA machine\n * composed OVER them that re-exports both. Three exports, one layering — not\n * duplication. The reuse list below spells out composition vs reimplemented\n * semantic per sibling.\n *\n * What it reuses, and HOW (composition vs. reimplemented semantic — the two are\n * not the same, so this list keeps them apart):\n *\n *   - `../cache` — COMPOSED directly. The DEDUPE / memoize layer is `../cache`'s\n *     `TtlCache` plus its `get` / `set` / `initCache` ops, called at runtime —\n *     not reinvented. While `cacheTtlMs` is set, an input whose `cacheKey` is\n *     already cached and unexpired is served from the cache and emits NOTHING\n *     (the downstream effect ran once for that key within its TTL); a fresh emit\n *     writes the value into the cache so the next identical input within\n *     `cacheTtlMs` is suppressed. The optional eviction Sub is the consumer's to\n *     wire if they want memory reclaim (this knob's correctness needs only TTL\n *     reads).\n *   - `../deadline` — COMPOSED directly. The settle timer IS a `../deadline`\n *     Sub: `subsFor` builds it via `deadlineSub`, and the subscribe cell +\n *     Msg constructor are RE-EXPORTS of `../deadline`'s own (`subscribeDeadline`\n *     → `subscribeThrottledInput`, `deadlineExceeded` → `throttledInputSettled`).\n *     The timer lifecycle stays owned by `../deadline`; this knob redraws none\n *     of it.\n *   - `../throttle` / `../debounce` — TYPE + SEMANTIC reuse only, NOT composed.\n *     Those siblings are host-boundary SINK transformers that hold a live\n *     `setTimeout`; a `setTimeout` in a closure is exactly what a durable,\n *     replayable knob must NOT hold. So their CODE is never called here. Instead\n *     the RATE-cap semantic (\"at most once per `ms`\", leading-edge) and the\n *     SETTLE semantic (\"wait until quiet\", trailing-edge) are REIMPLEMENTED as\n *     pure Model state: `lastAt` is the durable rate cursor (half-open cutoff\n *     `at - lastAt >= throttleMs`), and `pending` + the `../deadline` Sub realize\n *     the debounce window inside `update`. The `throttle` / `debounce`\n *     transformers themselves are RE-EXPORTED (the only reuse of their actual\n *     code) so a consumer can pre-throttle / pre-coalesce a genuinely bursty\n *     HOST event at the boundary BEFORE it ever becomes an `input` Msg — a\n *     separate, optional escape hatch, not part of this knob's gates.\n *\n * \"Omit a brick, omit its gate\" (the resilient-call config rule): every gate\n * field is optional. Omit `throttleMs` → no rate cap (every input passes the\n * rate gate). Omit `debounceMs` → no settle wait (an input that clears the rate\n * gate emits IMMEDIATELY rather than being held). Omit `cacheTtlMs` → no cache\n * slice at all (the `cache` field is absent; no dedupe). A config with all three\n * omitted is a pass-through: `input` always emits.\n *\n * Why this is a knob and not hand-wired logic: the managed state (`lastAt`,\n * `pending`, `cache`) lives in the Model, so it survives DO eviction / reload\n * (durable) and every transition is still a Msg through `update` (replayable). A\n * closure holding a `setTimeout` and a mutable \"last value\" would break both —\n * banned. `input` / `onFlush` are PURE: time arrives as an `at` parameter, never\n * `Date.now()`; they return NEW slice values, never mutate.\n *\n * Typical wiring (combinator form):\n *\n *   const search = createThrottledInput<string, Msg>({\n *     debounceMs: 200,        // wait for the user to stop typing\n *     throttleMs: 1_000,      // but never fire more than 1/s during a long burst\n *     cacheTtlMs: 30_000,     // skip a query repeated within 30s\n *     cacheKey: (q) => q,\n *     emit: (q) => ({ type: \"RunSearch\", query: q }),\n *   });\n *\n *   // Model:        { search: ThrottledInput<string>, ... }\n *   // init:         (loaded) => [loaded ?? { search: search.init(), ... }, []]\n *   // update cells:\n *   //   QueryTyped:   (s, m) => mapInput(s, search.input(s.search, m.value, m.at))\n *   //   SettleFired:  (s, m) => mapInput(s, search.onFlush(s.search, m.atMs))\n *   // subscriptions: (s) => search.subs(s.search)\n *   // subscribe:     { ...search.handlers() }\n *\n * where `mapInput(s, [slice, cmds]) => [{ ...s, search: slice }, cmds]` lifts the\n * slice transition into the consumer's Model. The `RunSearch` Cmd's interpret\n * handler is the consumer's — it is where the settled input meets I/O.\n *\n * NOT a substrate primitive: it depends only on sibling subpaths (`../throttle`,\n * `../debounce`, `../cache`, `../deadline`) and the core `Cmd` / `Sub` types.\n * Internal since #47 — reached from inside the package as\n * `internal/timing/throttled-input`; the L1 escape hatch is those siblings\n * threaded by hand. Same one-shape-per-package rule as `batch-window` and `poller`.\n */\n\nimport type { Cmd, Sub } from \"../../../index\";\nimport {\n  get as cacheGet,\n  set as cacheSet,\n  initCache,\n  type TtlCache,\n} from \"../../resilience/cache\";\nimport { type DeadlineSub, deadlineSub } from \"../../resilience/deadline\";\n\n// `../throttle` + `../debounce` — host-boundary pre-transformers (see file\n// header). Re-exported so a consumer that wants to throttle/debounce a bursty\n// HOST source BEFORE it becomes an `input` Msg reaches them from the same\n// import as the durable gate.\nexport { type Debounced, debounce } from \"../debounce\";\nexport { type Throttled, throttle } from \"../throttle\";\n\n/**\n * The gate fields every throttled-input config shares, regardless of whether\n * dedupe is on. The two dedupe variants below extend this with mutually\n * exclusive cache fields.\n *\n * `emit` is a pure Cmd CONSTRUCTOR, not a closure-with-state: it maps a settled\n * value to the single Cmd the runtime performs when the gates let a value\n * through. Keeping it `(value) => Cmd` (not `(value) => void`) is what keeps the\n * trigger replayable — the emit is a Cmd in the transition's output, never a\n * side effect inside the verb (mirrors `batch-window`'s `flush`).\n */\ninterface ThrottledInputGates<V, C extends Cmd> {\n  /**\n   * Rate cap, in milliseconds. An input that lands within `throttleMs` of the\n   * last EMIT (`at - lastAt < throttleMs`) is dropped from immediate firing —\n   * the leading-edge \"at most once per `throttleMs`\" rate-cap rule, applied to\n   * emits. The half-open cutoff (`>=` passes) matches `../throttle` and\n   * `../cache`'s window-edge convention. Omit for no rate cap.\n   *\n   * Interacts with `debounceMs`: when both are set, a rate-blocked input is\n   * still HELD as `pending` (so the settle timer eventually trails it out at a\n   * legal moment) rather than silently dropped — the trailing-edge guarantee\n   * that the FINAL sample of a window is never lost.\n   */\n  readonly throttleMs?: number;\n  /**\n   * Settle wait, in milliseconds. An input that clears the rate gate is not\n   * emitted immediately; it is held as `pending` and a debounce deadline is\n   * armed at `pendingAt + debounceMs`. A fresh input re-arms (slides) the\n   * window. `onFlush` emits the pending value when the window finally expires.\n   * Omit for no settle wait — a passing input emits on arrival.\n   */\n  readonly debounceMs?: number;\n  /**\n   * Map a settled value to the single Cmd the runtime performs. Called with the\n   * value the gates let through; the returned Cmd is what `input` / `onFlush`\n   * emit. PURE constructor — no I/O, no clock; the I/O happens later in the\n   * consumer's interpret handler for the returned Cmd.\n   */\n  readonly emit: (value: V) => C;\n}\n\n/**\n * Configuration for a throttled input — the knob. Pure config, no mutable state\n * (the `ThrottledInput<V>` slice carries that). One config object is shared\n * across every input of one logical stream (often a module-scope const).\n *\n * A DISCRIMINATED UNION on the presence of dedupe, so the type system makes a\n * cache-key collision UNREPRESENTABLE (\"omit a brick, omit its gate\"):\n *\n *   - **No dedupe** (`ThrottledInputNoCache`): `cacheTtlMs` absent ⇒ no cache\n *     slice, no dedupe. `cacheKey` is statically forbidden here (`never`) — a\n *     key with no cache to feed is dead config, so the type rejects it rather\n *     than silently ignoring it.\n *   - **Dedupe** (`ThrottledInputWithCache`): `cacheTtlMs` set ⇒ `cacheKey` is\n *     REQUIRED. There is no `String(value)` default to fall back to, so a\n *     structured value can NEVER collapse two distinct values to one slot (the\n *     `\"[object Object]\"` collision). The consumer must state the identity that\n *     keys the cache; a primitive stream still trivially passes `(v) => v` /\n *     `String`, but it does so EXPLICITLY.\n */\nexport type ThrottledInputConfig<V, C extends Cmd> =\n  | ThrottledInputNoCache<V, C>\n  | ThrottledInputWithCache<V, C>;\n\n/**\n * The no-dedupe config variant: gates only, no cache. `cacheTtlMs` is absent\n * and `cacheKey` is statically `never` so a stray key (which would feed no\n * cache) is a type error, not a silently-ignored field.\n */\nexport interface ThrottledInputNoCache<V, C extends Cmd>\n  extends ThrottledInputGates<V, C> {\n  readonly cacheTtlMs?: undefined;\n  readonly cacheKey?: never;\n}\n\n/**\n * The dedupe config variant: a per-entry TTL plus a REQUIRED `cacheKey`. An\n * input whose `cacheKey` is already cached and unexpired emits NOTHING (the\n * downstream effect ran once for that key within its TTL); a fresh emit writes\n * the value into the cache.\n *\n * `cacheKey` is required (no `String(value)` default) precisely so a structured\n * value cannot silently collide — the consumer names the identity, the cache\n * keys on exactly that.\n */\nexport interface ThrottledInputWithCache<V, C extends Cmd>\n  extends ThrottledInputGates<V, C> {\n  /**\n   * Dedupe / memoize TTL, in milliseconds. An input whose `cacheKey` is already\n   * cached and unexpired emits NOTHING; a fresh emit writes the value into the\n   * cache so the next identical input within `cacheTtlMs` is suppressed.\n   */\n  readonly cacheTtlMs: number;\n  /**\n   * Key a value for the dedupe cache. REQUIRED whenever `cacheTtlMs` is set:\n   * there is no `String(value)` fallback, so a structured value's identity is\n   * always the consumer's explicit choice and two distinct values can never\n   * collapse to one slot. A primitive stream passes `(v) => v` / `String`.\n   */\n  readonly cacheKey: (value: V) => string;\n}\n\n/**\n * The Model slice a throttled input owns — its visible slice (the knob\n * principle: managed state lives in the Model, never a closure, so it is durable\n * and replayable).\n *\n * - `lastAt`  — the `at` of the most recent EMIT, or `null` before the first\n *               emit. The `../throttle` rate cap measures against it: an input\n *               within `throttleMs` of `lastAt` is rate-blocked. Persisted so a\n *               resumed gate keeps its rate cursor.\n * - `pending` — the value HELD for the settle (debounce) window, paired with the\n *               `at` it was held (the anchor the deadline targets), or `null`\n *               when nothing is waiting. The single source of truth for \"is a\n *               settle window open?\" — the debounce timer Sub arms iff this is\n *               non-null.\n * - `cache`   — the `../cache` TTL store backing dedupe, present IFF\n *               `cacheTtlMs` is configured. Absent (the field omitted) for a\n *               gate with no dedupe — no per-op cost, nothing to serialize.\n */\nexport interface ThrottledInput<V> {\n  readonly lastAt: number | null;\n  readonly pending: PendingInput<V> | null;\n  readonly cache?: TtlCache<V>;\n}\n\n/**\n * A value held for the settle window: the `value` itself and the `at` it was\n * held (the anchor the debounce deadline targets, `at + debounceMs`). A distinct\n * type (not a bare `V`) because `V` may itself be `null` — a present-but-null\n * value is still a real pending input, distinct from \"nothing pending\", exactly\n * the `null`-sentinel discipline `../throttle` / `../debounce` use for their\n * `pendingArgs`.\n */\nexport interface PendingInput<V> {\n  readonly value: V;\n  readonly at: number;\n}\n\n/**\n * The Sub variant a throttled input's settle timer produces — a `../deadline`\n * Sub (so the window fires at the correct ABSOLUTE moment even after a late\n * subscribe / rehydrate, and so a consumer running several gates routes each by\n * `id`). `atMs` is the absolute settle-by instant (`pendingAt + debounceMs`).\n */\nexport type ThrottledInputSub = DeadlineSub;\n\n/**\n * The stable Sub id the gate arms its settle deadline under. A single gate arms\n * exactly one settle timer at a time, so one id suffices; a consumer running\n * several gates on one machine namespaces them by composing the knob under\n * distinct slices with distinct ids (the `subs(state, id)` parameter).\n */\nconst DEFAULT_SUB_ID = \"throttled-input:settle\";\n\n/**\n * The starting slice: no prior emit, nothing pending. The `cache` field is\n * seeded only when `cacheTtlMs` is configured (see `createThrottledInput`); the\n * free `initThrottledInput` leaves it absent (the no-dedupe shape).\n */\nexport function initThrottledInput<V>(): ThrottledInput<V> {\n  return { lastAt: null, pending: null };\n}\n\n/**\n * Resolve a value's cache key under a DEDUPE config. PURE. Takes the narrowed\n * `ThrottledInputWithCache` (not the union) because `cacheKey` is only present —\n * and only meaningful — when dedupe is on; there is no `String(value)` default\n * to fall back to, so a structured value's identity is always the consumer's\n * explicit choice and two distinct values can never collapse to one slot.\n */\nfunction keyOf<V, C extends Cmd>(\n  config: ThrottledInputWithCache<V, C>,\n  value: V,\n): string {\n  return config.cacheKey(value);\n}\n\n/**\n * Narrow `config` to its dedupe variant iff a cache slice is actually wired —\n * `cacheTtlMs` set AND a `cache` store present. Returns the narrowed config\n * (carrying the required `cacheKey`) paired with the resolved `cache` store, or\n * `null` when no dedupe is configured. The single place the union is\n * discriminated, so `isCacheHit` / `commitEmit` share one narrowing — and reuse\n * the resolved `cache` — rather than re-deriving the predicate and re-narrowing\n * `state.cache`.\n */\nfunction cacheConfig<V, C extends Cmd>(\n  config: ThrottledInputConfig<V, C>,\n  state: ThrottledInput<V>,\n): {\n  readonly config: ThrottledInputWithCache<V, C>;\n  readonly cache: TtlCache<V>;\n} | null {\n  return config.cacheTtlMs !== undefined && state.cache !== undefined\n    ? { config, cache: state.cache }\n    : null;\n}\n\n/**\n * Whether `value` is a cache HIT under `config` at `at` — present and unexpired.\n * PURE — reads only. Always `false` when `cacheTtlMs` is unset or no `cache`\n * slice exists (no dedupe configured), so the dedupe gate is a no-op for an\n * unconfigured gate.\n */\nfunction isCacheHit<V, C extends Cmd>(\n  config: ThrottledInputConfig<V, C>,\n  state: ThrottledInput<V>,\n  value: V,\n  at: number,\n): boolean {\n  const cached = cacheConfig(config, state);\n  if (cached === null) return false;\n  return cacheGet(cached.cache, keyOf(cached.config, value), at) !== undefined;\n}\n\n/**\n * Emit `value` at clock `at`: bump the rate cursor, refresh the dedupe cache,\n * and clear any pending hold. PURE. The single place an emit's bookkeeping\n * lives, shared by `input` (immediate emit) and `onFlush` (trailing emit) so the\n * two paths can never drift on what an emit updates.\n *\n * - `lastAt` advances to `at` — the next input is rate-measured against this\n *   emit, the `../throttle` window cursor.\n * - `cache` (when configured) records `value` under its key with `cacheTtlMs`\n *   from `at` — so the next identical input within the TTL is suppressed.\n * - `pending` clears — the value just went out; nothing is waiting.\n */\nfunction commitEmit<V, C extends Cmd>(\n  config: ThrottledInputConfig<V, C>,\n  state: ThrottledInput<V>,\n  value: V,\n  at: number,\n): readonly [ThrottledInput<V>, readonly C[]] {\n  const cached = cacheConfig(config, state);\n  const cache =\n    cached !== null\n      ? cacheSet(\n          cached.cache,\n          keyOf(cached.config, value),\n          value,\n          at,\n          cached.config.cacheTtlMs,\n        )\n      : state.cache;\n  const next: ThrottledInput<V> = {\n    ...state,\n    lastAt: at,\n    pending: null,\n    ...(cache !== undefined ? { cache } : {}),\n  };\n  return [next, [config.emit(value)]];\n}\n\n/**\n * Feed a new input `value` arriving at clock `at` through the gates. PURE.\n *\n * The gate order is DEDUPE → RATE → SETTLE (each skipped when its config field\n * is omitted), the same cache-first-then-gate order `resilient-call` uses (a hit\n * short-circuits before the expensive path):\n *\n *   1. **Dedupe** (`cacheTtlMs` set): if `value`'s key is cached and unexpired,\n *      suppress — return the slice UNCHANGED (no emit, no pending, no re-arm).\n *      The downstream effect already ran for this key within its TTL.\n *   2. **Rate** (`throttleMs` set): if `at` is within `throttleMs` of the last\n *      emit (`at - lastAt < throttleMs`), this input is rate-blocked.\n *        - With `debounceMs` set → HOLD it as `pending` (the trailing edge: the\n *          settle timer will emit it at a legal moment, so the final sample is\n *          never lost). The deadline `subs` arms targets `at + debounceMs`.\n *        - Without `debounceMs` → DROP it (pure rate cap, no catch-up).\n *   3. **Settle** (`debounceMs` set): the input cleared the rate gate. HOLD it\n *      as `pending` and let the debounce window slide; `onFlush` emits it once\n *      the window expires. A fresh input before expiry overwrites `pending` (the\n *      trailing edge fires with the LAST value, the `../debounce` default).\n *   4. **Pass-through**: no `debounceMs`, cleared the rate gate → EMIT now.\n *\n * @param config the knob (the three optional gates + `emit`)\n * @param state  the current slice\n * @param value  the input value\n * @param at     the arrival instant (epoch ms) — the caller stamps it; the verb\n *               never reads the clock\n */\nexport function input<V, C extends Cmd>(\n  config: ThrottledInputConfig<V, C>,\n  state: ThrottledInput<V>,\n  value: V,\n  at: number,\n): readonly [ThrottledInput<V>, readonly C[]] {\n  // 1. Dedupe gate — a cached, unexpired key short-circuits everything.\n  if (isCacheHit(config, state, value, at)) {\n    return [state, []];\n  }\n\n  // 2. Rate gate — half-open cutoff (`>=` passes). `lastAt === null` (no prior\n  // emit) always passes: the first input is never rate-blocked. Shared with\n  // `onFlush` via `rateBlockedAt` so the arrival and trailing-edge paths agree\n  // on the window.\n  if (rateBlockedAt(config, state, at)) {\n    // With a settle window, a rate-blocked input is HELD (trailing edge) so it\n    // emits at the next legal moment; without one, it is a pure drop.\n    if (config.debounceMs !== undefined) {\n      return [{ ...state, pending: { value, at } }, []];\n    }\n    return [state, []];\n  }\n\n  // 3. Settle gate — passed the rate gate; if a debounce window is configured,\n  // hold the value and (re)arm the settle deadline rather than emit now.\n  if (config.debounceMs !== undefined) {\n    return [{ ...state, pending: { value, at } }, []];\n  }\n\n  // 4. Pass-through — no settle wait, cleared the rate gate: emit immediately.\n  return commitEmit(config, state, value, at);\n}\n\n/**\n * Whether emitting at clock `at` would breach the rate cap — `at` lands within\n * `throttleMs` of the last emit (`at - lastAt < throttleMs`). PURE — reads only.\n * Always `false` when `throttleMs` is unset (no rate cap) or before the first\n * emit (`lastAt === null`), so an unconfigured / never-fired gate never holds on\n * the rate gate. The single rate-gate predicate, shared by `input` (drop / hold\n * on arrival) and `onFlush` (re-hold a still-early trailing edge) so the two\n * paths can never drift on what \"within the rate window\" means.\n */\nfunction rateBlockedAt<V, C extends Cmd>(\n  config: ThrottledInputConfig<V, C>,\n  state: ThrottledInput<V>,\n  at: number,\n): boolean {\n  return (\n    config.throttleMs !== undefined &&\n    state.lastAt !== null &&\n    at - state.lastAt < config.throttleMs\n  );\n}\n\n/**\n * Emit the pending value because the settle (debounce) window closed. PURE.\n *\n * - Pending present, rate gate CLEAR → emit `config.emit(pending.value)`,\n *   advance the rate cursor (`lastAt = at`), refresh the dedupe cache, and clear\n *   `pending`. The trailing edge of `../debounce` realized as a Model transition.\n * - Pending present, rate gate STILL BLOCKED → re-HOLD: return the slice with\n *   `pending` intact and NO Cmds. A settle Msg can fire at `pending.at +\n *   debounceMs`, which may still be inside the rate window (`lastAt +\n *   throttleMs`) — emitting then would breach the headline \"at most once per\n *   `throttleMs`\" cap. Re-holding keeps the value waiting; `subs` re-arms the\n *   deadline at `max(pending.at + debounceMs, lastAt + throttleMs)` so the next\n *   timer fires at a LEGAL moment and the trailing edge is deferred, never lost.\n * - Pending absent → no-op: return the same slice and no Cmds. Guards the race\n *   where an `input` already emitted (or a dedupe hit cleared interest) before\n *   the settle timer's Msg lands — a stale `onFlush` must NOT emit. Symmetric\n *   with `batch-window`'s closed-window guard.\n *\n * `at` is the firing instant the settle Msg carried (the caller stamps it; the\n * verb never reads the clock). It becomes the new rate cursor and the cache\n * write's `nowMs`, so a settled emit rate-blocks subsequent inputs from its\n * actual fire moment, not the moment the value was first held.\n *\n * @param config the knob (`throttleMs`, `emit`, cache config)\n * @param state  the current slice\n * @param at     the settle-timer firing instant (epoch ms)\n */\nexport function onFlush<V, C extends Cmd>(\n  config: ThrottledInputConfig<V, C>,\n  state: ThrottledInput<V>,\n  at: number,\n): readonly [ThrottledInput<V>, readonly C[]] {\n  // No pending value = an immediate emit already fired, or a dedupe hit cleared\n  // interest. A stale timer Msg must not emit — return the slice untouched.\n  if (state.pending === null) return [state, []];\n  // Rate gate re-check: a settle Msg can land before the rate window opens (its\n  // naive deadline is pending.at + debounceMs, which `subs` lifts to a legal\n  // target — but a stale / early timer can still arrive). Emitting now would\n  // breach \"at most once per throttleMs\", so re-hold and let `subs` re-arm at\n  // the legal moment. The value stays pending; nothing is dropped.\n  if (rateBlockedAt(config, state, at)) return [state, []];\n  return commitEmit(config, state, state.pending.value, at);\n}\n\n/**\n * The settle timer Sub, derived from the slice. PURE.\n *\n * Returns the single `../deadline` Sub while a value is held AND a settle window\n * is configured, or `[]` otherwise. The deadline target is the LATER of two\n * constraints (so the timer never fires before BOTH are satisfied):\n *\n *   - `pending.at + debounceMs` — the settle (debounce) deadline: the value has\n *     stopped sliding, the burst has gone quiet.\n *   - `lastAt + throttleMs` — the rate cap: emitting earlier would breach \"at\n *     most once per `throttleMs`\". Only applies once a prior emit exists\n *     (`lastAt !== null`) and a rate cap is configured (`throttleMs` set).\n *\n * `max(settleAt, rateAt)` is the earliest LEGAL trailing-edge moment. Anchoring\n * the timer here — rather than the naive `pending.at + debounceMs` — is what\n * keeps the rate cap intact across the trailing edge: a value held while still\n * inside the rate window arms its timer at `lastAt + throttleMs`, so `onFlush`\n * fires at a moment the rate gate already permits. (`onFlush` re-checks the gate\n * anyway and re-holds if an early/stale timer slips through, so the cap holds\n * even if a timer fires ahead of this target.)\n *\n * The substrate's reconcile pass arms the timer when the array gains the Sub and\n * disarms it (clearing the pending `setTimeout`) when the array loses it — so an\n * `onFlush` (or a dedupe hit) that clears `pending` auto-cancels the now-stale\n * settle timer on the next transition, and a sliding input that re-stamps\n * `pending.at` re-arms a fresh absolute target.\n *\n * `debounceMs` undefined ⇒ no settle window ⇒ `[]` even with a `pending` value\n * (an unconfigured settle never holds, but the guard keeps `subs` total).\n *\n * @param config the knob (`debounceMs`, `throttleMs`)\n * @param state  the current slice\n * @param id     stable identity for this gate's settle timer (default\n *               `\"throttled-input:settle\"`); pass a distinct id per gate when a\n *               machine runs several so the dispatched Msg routes distinctly.\n */\nexport function subsFor<V, C extends Cmd>(\n  config: ThrottledInputConfig<V, C>,\n  state: ThrottledInput<V>,\n  id = DEFAULT_SUB_ID,\n): readonly ThrottledInputSub[] {\n  if (config.debounceMs === undefined || state.pending === null) return [];\n  const settleAt = state.pending.at + config.debounceMs;\n  // The rate floor: the earliest moment the rate cap permits an emit. Absent\n  // when no rate cap is configured or no prior emit set a cursor — then the\n  // settle deadline alone governs.\n  const rateAt =\n    config.throttleMs !== undefined && state.lastAt !== null\n      ? state.lastAt + config.throttleMs\n      : settleAt;\n  return [deadlineSub(id, Math.max(settleAt, rateAt))];\n}\n\n/**\n * The bound knob returned by `createThrottledInput`. `init` + the two pure verbs\n * + `subs`, all closing over one `ThrottledInputConfig`. The verbs return\n * `readonly [ThrottledInput<V>, readonly C[]]`: the next slice and the Cmds to\n * emit (one `emit` Cmd when a value passes, none while held / dropped / deduped).\n *\n * Pure-ops + subs module: there is no `handlers(ports)` cell. The settle timer's\n * subscribe cell IS `../deadline`'s `subscribeDeadline` (re-exported below) —\n * the consumer wires it into `subscribe` directly; the knob redraws no timer\n * lifecycle of its own. (Compare `poller`, identical: it too reuses\n * `../deadline`'s cell and ships no `handlers`.)\n */\nexport interface ThrottledInputKnob<V, C extends Cmd> {\n  /** Seed the Model slice (with a cache iff `cacheTtlMs` is configured). */\n  init(): ThrottledInput<V>;\n  /**\n   * Feed a new input through the dedupe → rate → settle gates. See `input`.\n   */\n  input(\n    state: ThrottledInput<V>,\n    value: V,\n    at: number,\n  ): readonly [ThrottledInput<V>, readonly C[]];\n  /**\n   * Emit the held value because the settle window closed. See `onFlush`.\n   */\n  onFlush(\n    state: ThrottledInput<V>,\n    at: number,\n  ): readonly [ThrottledInput<V>, readonly C[]];\n  /**\n   * The settle timer Sub, armed only while a value is held. See `subsFor`.\n   * `id` keys the deadline so several gates on one machine route distinctly.\n   */\n  subs(state: ThrottledInput<V>, id?: string): readonly Sub[];\n}\n\n/**\n * Build a throttled-input knob from `config`. Combinator form (the default L2\n * ergonomic): hand it the config, splice the returned hooks into your machine.\n * The pure verbs (`input` / `onFlush`) close over the config so the consumer's\n * reducer cells stay a uniform `(state, ...args)` shape; `subs` pre-wires the\n * settle timer.\n *\n * `init()` seeds a `cache` slice IFF `cacheTtlMs` is configured — an unconfigured\n * gate carries no cache field (nothing to serialize, no dedupe). Pure factory —\n * no clock read, no timer; everything happens when the consumer calls the\n * returned verbs / `subs` with an injected `at`.\n *\n * @typeParam V the input value type\n * @typeParam C the Cmd type `config.emit` returns\n */\nexport function createThrottledInput<V, C extends Cmd>(\n  config: ThrottledInputConfig<V, C>,\n): ThrottledInputKnob<V, C> {\n  function init(): ThrottledInput<V> {\n    const base = initThrottledInput<V>();\n    // Seed the cache only when dedupe is configured — an unconfigured gate\n    // carries no cache field at all (the no-dedupe shape).\n    return config.cacheTtlMs !== undefined\n      ? { ...base, cache: initCache<V>() }\n      : base;\n  }\n\n  return {\n    init,\n    input: (state, value, at) => input(config, state, value, at),\n    onFlush: (state, at) => onFlush(config, state, at),\n    subs: (state, id) => subsFor(config, state, id),\n  };\n}\n\n/**\n * The settle-timer wiring, RE-EXPORTED from `../deadline` (not redrawn) so the\n * timer lifecycle stays owned there. Consolidated into one `export ... from`:\n *\n *   - `subscribeThrottledInput` (= `../deadline`'s `subscribeDeadline`) — the\n *     `subscribe[\"deadline\"]` cell. Arms a one-shot timer for `max(0, atMs -\n *     now)`, dispatches the deadline Msg, returns a cleanup that clears it. The\n *     consumer assigns it: `subscribe: { deadline: subscribeThrottledInput }`.\n *   - `throttledInputSettled` (= `../deadline`'s `deadlineExceeded`) +\n *     `ThrottledInputSettled` (= `DeadlineExceeded`) — the settle-timer Msg\n *     constructor and type the consumer handles via `onFlush`. Sharing one\n *     constructor with the subscribe cell keeps the two from drifting; the\n *     reducer reads `msg.atMs` as the `at` it threads into `onFlush`.\n */\nexport {\n  type DeadlineExceeded as ThrottledInputSettled,\n  deadlineExceeded as throttledInputSettled,\n  subscribeDeadline as subscribeThrottledInput,\n} from \"../../resilience/deadline\";\n"]}
+{"version":3,"sources":["../../src/internal/timing/throttle/index.ts","../../src/internal/timing/throttled-input/index.ts"],"names":[],"mappings":";;;;;;;AAkIO,SAAS,QAAA,CACd,EAAA,EACA,EAAA,EACA,IAAA,EACc;AACd,EAAA,MAAM,OAAA,GAAU,MAAM,OAAA,IAAW,IAAA;AACjC,EAAA,MAAM,QAAA,GAAW,MAAM,QAAA,IAAY,IAAA;AAMnC,EAAA,IAAI,MAAA,GAA+C,IAAA;AAOnD,EAAA,IAAI,WAAA,GAAwB,IAAA;AAE5B,EAAA,SAAS,WAAA,GAAoB;AAC3B,IAAA,IAAI,WAAW,IAAA,EAAM;AACnB,MAAA,YAAA,CAAa,MAAM,CAAA;AACnB,MAAA,MAAA,GAAS,IAAA;AAAA,IACX;AAAA,EACF;AAOA,EAAA,SAAS,eAAA,GAAwB;AAC/B,IAAA,IAAI,QAAA,IAAY,gBAAgB,IAAA,EAAM;AACpC,MAAA,MAAM,IAAA,GAAO,WAAA;AACb,MAAA,WAAA,GAAc,IAAA;AAId,MAAA,MAAA,GAAS,UAAA,CAAW,iBAAiB,EAAE,CAAA;AACvC,MAAA,EAAA,CAAG,GAAG,IAAI,CAAA;AAAA,IACZ,CAAA,MAAO;AAEL,MAAA,MAAA,GAAS,IAAA;AAAA,IACX;AAAA,EACF;AAEA,EAAA,MAAM,SAAA,GAAY,IAAI,IAAA,KAAkB;AACtC,IAAA,IAAI,WAAW,IAAA,EAAM;AAEnB,MAAA,IAAI,OAAA,EAAS;AACX,QAAA,EAAA,CAAG,GAAG,IAAI,CAAA;AAAA,MACZ,WAAW,QAAA,EAAU;AAInB,QAAA,WAAA,GAAc,IAAA;AAAA,MAChB;AACA,MAAA,MAAA,GAAS,UAAA,CAAW,iBAAiB,EAAE,CAAA;AAAA,IACzC,WAAW,QAAA,EAAU;AAGnB,MAAA,WAAA,GAAc,IAAA;AAAA,IAChB;AAAA,EAEF,CAAA;AAEA,EAAA,SAAA,CAAU,SAAS,MAAY;AAC7B,IAAA,WAAA,EAAY;AACZ,IAAA,WAAA,GAAc,IAAA;AAAA,EAChB,CAAA;AAEA,EAAA,SAAA,CAAU,QAAQ,MAAY;AAI5B,IAAA,IAAI,gBAAgB,IAAA,EAAM;AACxB,MAAA,MAAM,IAAA,GAAO,WAAA;AACb,MAAA,WAAA,GAAc,IAAA;AACd,MAAA,WAAA,EAAY;AACZ,MAAA,EAAA,CAAG,GAAG,IAAI,CAAA;AAAA,IACZ,CAAA,MAAO;AAGL,MAAA,WAAA,EAAY;AAAA,IACd;AAAA,EACF,CAAA;AAEA,EAAA,OAAO,SAAA;AACT;;;ACuCA,IAAM,cAAA,GAAiB,wBAAA;AAOhB,SAAS,kBAAA,GAA2C;AACzD,EAAA,OAAO,EAAE,MAAA,EAAQ,IAAA,EAAM,OAAA,EAAS,IAAA,EAAK;AACvC;AASA,SAAS,KAAA,CACP,QACA,KAAA,EACQ;AACR,EAAA,OAAO,MAAA,CAAO,SAAS,KAAK,CAAA;AAC9B;AAWA,SAAS,WAAA,CACP,QACA,KAAA,EAIO;AACP,EAAA,OAAO,MAAA,CAAO,UAAA,KAAe,MAAA,IAAa,KAAA,CAAM,KAAA,KAAU,MAAA,GACtD,EAAE,MAAA,EAAQ,KAAA,EAAO,KAAA,CAAM,KAAA,EAAM,GAC7B,IAAA;AACN;AAQA,SAAS,UAAA,CACP,MAAA,EACA,KAAA,EACA,KAAA,EACA,EAAA,EACS;AACT,EAAA,MAAM,MAAA,GAAS,WAAA,CAAY,MAAA,EAAQ,KAAK,CAAA;AACxC,EAAA,IAAI,MAAA,KAAW,MAAM,OAAO,KAAA;AAC5B,EAAA,OAAO,GAAA,CAAS,OAAO,KAAA,EAAO,KAAA,CAAM,OAAO,MAAA,EAAQ,KAAK,CAAA,EAAG,EAAE,CAAA,KAAM,MAAA;AACrE;AAcA,SAAS,UAAA,CACP,MAAA,EACA,KAAA,EACA,KAAA,EACA,EAAA,EAC4C;AAC5C,EAAA,MAAM,MAAA,GAAS,WAAA,CAAY,MAAA,EAAQ,KAAK,CAAA;AACxC,EAAA,MAAM,KAAA,GACJ,WAAW,IAAA,GACP,GAAA;AAAA,IACE,MAAA,CAAO,KAAA;AAAA,IACP,KAAA,CAAM,MAAA,CAAO,MAAA,EAAQ,KAAK,CAAA;AAAA,IAC1B,KAAA;AAAA,IACA,EAAA;AAAA,IACA,OAAO,MAAA,CAAO;AAAA,MAEhB,KAAA,CAAM,KAAA;AACZ,EAAA,MAAM,IAAA,GAA0B;AAAA,IAC9B,GAAG,KAAA;AAAA,IACH,MAAA,EAAQ,EAAA;AAAA,IACR,OAAA,EAAS,IAAA;AAAA,IACT,GAAI,KAAA,KAAU,MAAA,GAAY,EAAE,KAAA,KAAU;AAAC,GACzC;AACA,EAAA,OAAO,CAAC,IAAA,EAAM,CAAC,OAAO,IAAA,CAAK,KAAK,CAAC,CAAC,CAAA;AACpC;AA8BO,SAAS,KAAA,CACd,MAAA,EACA,KAAA,EACA,KAAA,EACA,EAAA,EAC4C;AAE5C,EAAA,IAAI,UAAA,CAAW,MAAA,EAAQ,KAAA,EAAO,KAAA,EAAO,EAAE,CAAA,EAAG;AACxC,IAAA,OAAO,CAAC,KAAA,EAAO,EAAE,CAAA;AAAA,EACnB;AAMA,EAAA,IAAI,aAAA,CAAc,MAAA,EAAQ,KAAA,EAAO,EAAE,CAAA,EAAG;AAGpC,IAAA,IAAI,MAAA,CAAO,eAAe,MAAA,EAAW;AACnC,MAAA,OAAO,CAAC,EAAE,GAAG,KAAA,EAAO,OAAA,EAAS,EAAE,KAAA,EAAO,EAAA,EAAG,EAAE,EAAG,EAAE,CAAA;AAAA,IAClD;AACA,IAAA,OAAO,CAAC,KAAA,EAAO,EAAE,CAAA;AAAA,EACnB;AAIA,EAAA,IAAI,MAAA,CAAO,eAAe,MAAA,EAAW;AACnC,IAAA,OAAO,CAAC,EAAE,GAAG,KAAA,EAAO,OAAA,EAAS,EAAE,KAAA,EAAO,EAAA,EAAG,EAAE,EAAG,EAAE,CAAA;AAAA,EAClD;AAGA,EAAA,OAAO,UAAA,CAAW,MAAA,EAAQ,KAAA,EAAO,KAAA,EAAO,EAAE,CAAA;AAC5C;AAWA,SAAS,aAAA,CACP,MAAA,EACA,KAAA,EACA,EAAA,EACS;AACT,EAAA,OACE,MAAA,CAAO,eAAe,MAAA,IACtB,KAAA,CAAM,WAAW,IAAA,IACjB,EAAA,GAAK,KAAA,CAAM,MAAA,GAAS,MAAA,CAAO,UAAA;AAE/B;AA6BO,SAAS,OAAA,CACd,MAAA,EACA,KAAA,EACA,EAAA,EAC4C;AAG5C,EAAA,IAAI,MAAM,OAAA,KAAY,IAAA,SAAa,CAAC,KAAA,EAAO,EAAE,CAAA;AAM7C,EAAA,IAAI,aAAA,CAAc,QAAQ,KAAA,EAAO,EAAE,GAAG,OAAO,CAAC,KAAA,EAAO,EAAE,CAAA;AACvD,EAAA,OAAO,WAAW,MAAA,EAAQ,KAAA,EAAO,KAAA,CAAM,OAAA,CAAQ,OAAO,EAAE,CAAA;AAC1D;AAuCO,SAAS,OAAA,CACd,MAAA,EACA,KAAA,EACA,EAAA,GAAK,cAAA,EACyB;AAC9B,EAAA,IAAI,OAAO,UAAA,KAAe,MAAA,IAAa,MAAM,OAAA,KAAY,IAAA,SAAa,EAAC;AACvE,EAAA,MAAM,QAAA,GAAW,KAAA,CAAM,OAAA,CAAQ,EAAA,GAAK,MAAA,CAAO,UAAA;AAI3C,EAAA,MAAM,MAAA,GACJ,MAAA,CAAO,UAAA,KAAe,MAAA,IAAa,KAAA,CAAM,WAAW,IAAA,GAChD,KAAA,CAAM,MAAA,GAAS,MAAA,CAAO,UAAA,GACtB,QAAA;AACN,EAAA,OAAO,CAAC,YAAY,EAAA,EAAI,IAAA,CAAK,IAAI,QAAA,EAAU,MAAM,CAAC,CAAC,CAAA;AACrD;AAuDO,SAAS,qBACd,MAAA,EAC0B;AAC1B,EAAA,SAAS,IAAA,GAA0B;AACjC,IAAA,MAAM,OAAO,kBAAA,EAAsB;AAGnC,IAAA,OAAO,MAAA,CAAO,eAAe,MAAA,GACzB,EAAE,GAAG,IAAA,EAAM,KAAA,EAAO,SAAA,EAAa,EAAE,GACjC,IAAA;AAAA,EACN;AAEA,EAAA,OAAO;AAAA,IACL,IAAA;AAAA,IACA,KAAA,EAAO,CAAC,KAAA,EAAO,KAAA,EAAO,OAAO,KAAA,CAAM,MAAA,EAAQ,KAAA,EAAO,KAAA,EAAO,EAAE,CAAA;AAAA,IAC3D,SAAS,CAAC,KAAA,EAAO,OAAO,OAAA,CAAQ,MAAA,EAAQ,OAAO,EAAE,CAAA;AAAA,IACjD,MAAM,CAAC,KAAA,EAAO,OAAO,OAAA,CAAQ,MAAA,EAAQ,OAAO,EAAE;AAAA,GAChD;AACF","file":"index.js","sourcesContent":["/**\n * internal/timing/throttle — a timer-based call transformer that caps invocation\n * to at most once per `ms` window.\n *\n * Sibling of `../debounce` — the two share a SYMMETRIC surface\n * (`Throttled<A>` / `Debounced<A>`, both callable + `.cancel()` + `.flush()`,\n * both `{ leading?, trailing? }`) so they read as a pair. They are kept in\n * separate files with NO cross-import: each is a self-contained timer, and the\n * coalesce-vs-drop policies differ enough that sharing code would hide the\n * distinction. The contrast IS the lesson:\n *\n *   - **debounce** waits for quiet — fires once AFTER a burst settles.\n *   - **throttle** enforces a rate — fires AT MOST once per `ms` while the\n *     burst is ongoing, dropping the calls in between.\n *\n * Layering with `../throttled-input`: `throttle` and `debounce` are\n * the two host-boundary PRIMITIVES — two distinct algorithms\n * (at-most-once-per-window vs collapse-a-burst) behind one signature shape.\n * `throttled-input` is NOT a third primitive: it is a TEA machine composed\n * OVER them (the same semantics, reimplemented as pure, durable Model state)\n * that re-exports both. Wrapping a raw host event → these primitives; durable, replayable\n * gating inside a machine → `throttled-input` (see its module doc for the full\n * layering map).\n *\n * WHAT THIS IS NOT — and why it lives outside `update`:\n *\n *   - NOT a reducer / Transitions cell. Reducers are PURE (invariant 2 — same\n *     inputs → same outputs, no `Date.now`, no timers). A throttle holds a live\n *     `setTimeout` handle and a window cursor; folding it into `update` would\n *     smuggle a timer into the pure core.\n *   - NOT a Sub. A Sub is a continuous SOURCE of Msgs the substrate reconciles\n *     by id every transition (invariant 4). A throttle is a SINK transformer:\n *     it wraps a `void`-returning handler (the canonical one is\n *     `Runtime.dispatch`) so a high-frequency HOST event is rate-limited BEFORE\n *     it ever becomes a Msg.\n *\n * It is a higher-order function at the host boundary (pattern 14 — TEA owns\n * state, JS owns timing). The host attaches the wrapped function to a\n * high-frequency event source (`mousemove`, `scroll`, `pointermove`, a game\n * loop) and the substrate downstream only ever sees the rate-limited Msg:\n *\n *   const onMoved = throttle(\n *     (e: PointerEvent) =>\n *       runtime.dispatch({ type: \"UserMovedCursor\", x: e.clientX, y: e.clientY }),\n *     16, // ~60fps cap\n *   );\n *   window.addEventListener(\"pointermove\", onMoved);\n *   // cleanup: onMoved.cancel(); window.removeEventListener(\"pointermove\", onMoved);\n *\n * Internal since #47 — not published on any subpath; reached from inside the\n * package as `internal/timing/throttle`. Same one-shape-per-package rule as\n * `rate-limit`, `deadline`, and `work-queue`.\n *\n * Uses the universal `setTimeout` / `clearTimeout` timer idiom (same discipline\n * as `subs/from-timeout.ts`): exactly one live handle at a time, the window\n * timer clears itself on expiry, `cancel` / `flush` clear and null it so a\n * stale callback can never run.\n */\n\n/**\n * A throttled wrapper around `fn`. Callable with the SAME argument tuple as\n * `fn` — `(...args: A) => void` — plus two control methods that share names and\n * shapes with `Debounced<A>` so the two modules read as a symmetric pair.\n */\nexport interface Throttled<A extends readonly unknown[]> {\n  /** Invoke `fn` if the window is open, else record args for the trailing fire. */\n  (...args: A): void;\n  /**\n   * Drop any pending trailing fire WITHOUT invoking `fn`, and close the active\n   * window. Clears the timer, forgets the captured trailing args, and resets\n   * the cursor so the next call fires immediately on the leading edge (if\n   * `leading` is enabled). Idempotent.\n   *\n   * The host-cleanup partner of `removeEventListener`: cancel the pending fire\n   * when the component unmounts / the listener detaches, so a queued\n   * `dispatch` can't land after teardown.\n   */\n  cancel(): void;\n  /**\n   * Fire any pending trailing call IMMEDIATELY with its latest captured args,\n   * then close the window. No-op when nothing is pending. Use to force the last\n   * dropped call out early — e.g. flush the final cursor position when a drag\n   * ends, so the rest state isn't a stale mid-drag sample.\n   */\n  flush(): void;\n}\n\n/**\n * Wrap `fn` so it runs AT MOST once per `ms` window, no matter how often it is\n * called.\n *\n * Leading + trailing (the default): the first call fires `fn` IMMEDIATELY (the\n * leading edge) and opens a `ms` window. Calls during the window are dropped\n * from immediate firing but their args are remembered; when the window closes,\n * `fn` fires ONCE more with the LATEST dropped args (the trailing edge) and a\n * new window opens. A call after the window has already closed leads a fresh\n * window immediately. Spacing every call at least `ms` apart therefore fires\n * each one on its own leading edge.\n *\n * @param fn   The handler to rate-limit. Typically `(...) => runtime.dispatch(...)`,\n *             but any `(...args: A) => void` works. The return value is\n *             ignored — throttle is a fire transformer, not a value pipe.\n * @param ms   Window length in milliseconds. `fn` fires at most once per `ms`.\n * @param opts.leading   Fire on the FIRST call of a window (the leading edge),\n *             immediately. Default `true`.\n * @param opts.trailing  Fire once at window END with the latest args dropped\n *             during the window. Default `true`.\n *\n * Edge combinations (matching lodash's settled semantics, the de-facto\n * standard the ecosystem rediscovered):\n *\n *   - `{ leading: true, trailing: true }` (default): immediate fire + a\n *     trailing fire per window while calls keep arriving. The trailing fire is\n *     SUPPRESSED when no extra call arrived during the window (a lone call\n *     already fired on the leading edge — no stale trailing double-fire).\n *   - `{ leading: true, trailing: false }`: only the immediate fire; everything\n *     in the window is dropped with no catch-up at the end.\n *   - `{ leading: false, trailing: true }`: no immediate fire; the FIRST call\n *     opens a window and `fn` fires at the window's end with the latest args.\n *     Steady \"sample every `ms`\" behavior with no instant response.\n *   - `{ leading: false, trailing: false }`: never fires. Degenerate but legal;\n *     we don't throw — the caller asked for a no-op transformer.\n *\n * WHY a default of leading + trailing both `true`: a throttle's job is \"respond\n * now, then keep responding at a steady rate.\" Leading gives the instant\n * response (the first `mousemove` updates immediately); trailing guarantees the\n * FINAL sample of a window isn't lost (the cursor ends where the user actually\n * left it, not one window-width behind). Dropping either loses one of those two\n * guarantees, so both default on.\n */\nexport function throttle<A extends readonly unknown[]>(\n  fn: (...args: A) => void,\n  ms: number,\n  opts?: { leading?: boolean; trailing?: boolean },\n): Throttled<A> {\n  const leading = opts?.leading ?? true;\n  const trailing = opts?.trailing ?? true;\n\n  // Exactly one live handle at a time (the from-timeout discipline). `null`\n  // when no window is open — the single source of truth for \"is a window\n  // active?\". The window timer arms on a fire and clears itself on expiry; the\n  // call path never stacks overlapping timers.\n  let handle: ReturnType<typeof setTimeout> | null = null;\n  // The latest args seen DURING an open window, held for the trailing fire.\n  // Overwritten by every dropped call (the trailing edge fires with the LAST\n  // args), cleared the instant we fire / cancel. `null` (not `undefined`) is\n  // the empty sentinel because `A` may itself contain `undefined` elements — a\n  // present-but-empty tuple is still a pending call, distinct from \"nothing\n  // pending\".\n  let pendingArgs: A | null = null;\n\n  function clearHandle(): void {\n    if (handle !== null) {\n      clearTimeout(handle);\n      handle = null;\n    }\n  }\n\n  // Window expiry: the `ms` window just closed. If a call arrived during the\n  // window (`pendingArgs !== null`) and trailing is enabled, fire it now and\n  // open a FRESH window so the rate cap continues across a sustained burst.\n  // If nothing was dropped, let the window close (handle → null) so the next\n  // call leads a new window immediately.\n  function onWindowExpired(): void {\n    if (trailing && pendingArgs !== null) {\n      const args = pendingArgs;\n      pendingArgs = null;\n      // Re-arm BEFORE firing so a re-entrant call from inside `fn` sees an open\n      // window (and is correctly dropped/queued) rather than leading a second\n      // window — keeps the \"at most once per `ms`\" invariant under re-entry.\n      handle = setTimeout(onWindowExpired, ms);\n      fn(...args);\n    } else {\n      // No trailing fire owed — close the window.\n      handle = null;\n    }\n  }\n\n  const throttled = (...args: A): void => {\n    if (handle === null) {\n      // Window is closed → this call leads a new window.\n      if (leading) {\n        fn(...args);\n      } else if (trailing) {\n        // No leading fire, but trailing wants the first call's args so the\n        // window's end has something to fire. Without this, a leading:false\n        // throttle would swallow a lone call entirely.\n        pendingArgs = args;\n      }\n      handle = setTimeout(onWindowExpired, ms);\n    } else if (trailing) {\n      // Window is open → drop this call from immediate firing, but remember its\n      // args as the latest candidate for the trailing edge.\n      pendingArgs = args;\n    }\n    // Window open + trailing disabled → pure drop, nothing to remember.\n  };\n\n  throttled.cancel = (): void => {\n    clearHandle();\n    pendingArgs = null;\n  };\n\n  throttled.flush = (): void => {\n    // Force the pending trailing fire out now and close the window. Mirrors\n    // `onWindowExpired`'s fire branch but is caller-driven, so it tears the\n    // timer down rather than re-arming.\n    if (pendingArgs !== null) {\n      const args = pendingArgs;\n      pendingArgs = null;\n      clearHandle();\n      fn(...args);\n    } else {\n      // Nothing pending — still close a lingering window so a post-flush call\n      // leads cleanly.\n      clearHandle();\n    }\n  };\n\n  return throttled;\n}\n","/**\n * internal/timing/throttled-input — gate a high-frequency input stream into a\n * SETTLED, RATE-CAPPED, optionally DEDUPED sequence of emits, as a TEA knob: one\n * config object + a few pre-wired hooks you spread into your machine.\n *\n * Layering (the throttle-family map): `../throttle` and `../debounce` are the\n * two host-boundary PRIMITIVES — two distinct algorithms\n * (at-most-once-per-window vs collapse-a-burst) behind one signature shape.\n * THIS module is the third name but NOT a third primitive: a TEA machine\n * composed OVER them that re-exports both. Three exports, one layering — not\n * duplication. The reuse list below spells out composition vs reimplemented\n * semantic per sibling.\n *\n * What it reuses, and HOW (composition vs. reimplemented semantic — the two are\n * not the same, so this list keeps them apart):\n *\n *   - `../cache` — COMPOSED directly. The DEDUPE / memoize layer is `../cache`'s\n *     `TtlCache` plus its `get` / `set` / `initCache` ops, called at runtime —\n *     not reinvented. While `cacheTtlMs` is set, an input whose `cacheKey` is\n *     already cached and unexpired is served from the cache and emits NOTHING\n *     (the downstream effect ran once for that key within its TTL); a fresh emit\n *     writes the value into the cache so the next identical input within\n *     `cacheTtlMs` is suppressed. The optional eviction Sub is the consumer's to\n *     wire if they want memory reclaim (this knob's correctness needs only TTL\n *     reads).\n *   - `../deadline` — COMPOSED directly. The settle timer IS a `../deadline`\n *     deadline: `subsFor` builds it via `deadlineSub`, and the runner +\n *     Msg constructor are RE-EXPORTS of `../deadline`'s own (`subscribeDeadline`\n *     → `subscribeThrottledInput`, `deadlineExceeded` → `throttledInputSettled`).\n *     The timer lifecycle stays owned by `../deadline`; this knob redraws none\n *     of it.\n *   - `../throttle` / `../debounce` — TYPE + SEMANTIC reuse only, NOT composed.\n *     Those siblings are host-boundary SINK transformers that hold a live\n *     `setTimeout`; a `setTimeout` in a closure is exactly what a durable,\n *     replayable knob must NOT hold. So their CODE is never called here. Instead\n *     the RATE-cap semantic (\"at most once per `ms`\", leading-edge) and the\n *     SETTLE semantic (\"wait until quiet\", trailing-edge) are REIMPLEMENTED as\n *     pure Model state: `lastAt` is the durable rate cursor (half-open cutoff\n *     `at - lastAt >= throttleMs`), and `pending` + the `../deadline` timer realize\n *     the debounce window inside `update`. The `throttle` / `debounce`\n *     transformers themselves are RE-EXPORTED (the only reuse of their actual\n *     code) so a consumer can pre-throttle / pre-coalesce a genuinely bursty\n *     HOST event at the boundary BEFORE it ever becomes an `input` Msg — a\n *     separate, optional escape hatch, not part of this knob's gates.\n *\n * \"Omit a brick, omit its gate\" (the resilient-call config rule): every gate\n * field is optional. Omit `throttleMs` → no rate cap (every input passes the\n * rate gate). Omit `debounceMs` → no settle wait (an input that clears the rate\n * gate emits IMMEDIATELY rather than being held). Omit `cacheTtlMs` → no cache\n * slice at all (the `cache` field is absent; no dedupe). A config with all three\n * omitted is a pass-through: `input` always emits.\n *\n * Why this is a knob and not hand-wired logic: the managed state (`lastAt`,\n * `pending`, `cache`) lives in the Model, so it survives DO eviction / reload\n * (durable) and every transition is still a Msg through `update` (replayable). A\n * closure holding a `setTimeout` and a mutable \"last value\" would break both —\n * banned. `input` / `onFlush` are PURE: time arrives as an `at` parameter, never\n * `Date.now()`; they return NEW slice values, never mutate.\n *\n * Typical wiring (combinator form):\n *\n *   const search = createThrottledInput<string, Msg>({\n *     debounceMs: 200,        // wait for the user to stop typing\n *     throttleMs: 1_000,      // but never fire more than 1/s during a long burst\n *     cacheTtlMs: 30_000,     // skip a query repeated within 30s\n *     cacheKey: (q) => q,\n *     emit: (q) => ({ type: \"RunSearch\", query: q }),\n *   });\n *\n *   // Model:        { search: ThrottledInput<string>, ... }\n *   // init:         (loaded) => [loaded ?? { search: search.init(), ... }, []]\n *   // update cells:\n *   //   QueryTyped:   (s, m) => mapInput(s, search.input(s.search, m.value, m.at))\n *   //   SettleFired:  (s, m) => mapInput(s, search.onFlush(s.search, m.atMs))\n *   // types.sub:    {} as DeadlinesSub\n *   // subs:         [deadlinesSub((s: Model) => search.subs(s.search))]\n *   // at run:       run(machine, { interpret, subscribe: { deadline: subscribeThrottledInput } })\n *\n * where `mapInput(s, [slice, cmds]) => [{ ...s, search: slice }, cmds]` lifts the\n * slice transition into the consumer's Model. The `RunSearch` Cmd's interpret\n * handler is the consumer's — it is where the settled input meets I/O.\n *\n * NOT a substrate primitive: it depends only on sibling subpaths (`../throttle`,\n * `../debounce`, `../cache`, `../deadline`) and the core `Cmd` type.\n * Internal since #47 — reached from inside the package as\n * `internal/timing/throttled-input`; the L1 escape hatch is those siblings\n * threaded by hand. Same one-shape-per-package rule as `batch-window` and `poller`.\n */\n\nimport type { Cmd } from \"../../../index\";\nimport {\n  get as cacheGet,\n  set as cacheSet,\n  initCache,\n  type TtlCache,\n} from \"../../resilience/cache\";\nimport { type DeadlineSub, deadlineSub } from \"../../resilience/deadline\";\n\n// `../throttle` + `../debounce` — host-boundary pre-transformers (see file\n// header). Re-exported so a consumer that wants to throttle/debounce a bursty\n// HOST source BEFORE it becomes an `input` Msg reaches them from the same\n// import as the durable gate.\nexport { type Debounced, debounce } from \"../debounce\";\nexport { type Throttled, throttle } from \"../throttle\";\n\n/**\n * The gate fields every throttled-input config shares, regardless of whether\n * dedupe is on. The two dedupe variants below extend this with mutually\n * exclusive cache fields.\n *\n * `emit` is a pure Cmd CONSTRUCTOR, not a closure-with-state: it maps a settled\n * value to the single Cmd the runtime performs when the gates let a value\n * through. Keeping it `(value) => Cmd` (not `(value) => void`) is what keeps the\n * trigger replayable — the emit is a Cmd in the transition's output, never a\n * side effect inside the verb (mirrors `batch-window`'s `flush`).\n */\ninterface ThrottledInputGates<V, C extends Cmd> {\n  /**\n   * Rate cap, in milliseconds. An input that lands within `throttleMs` of the\n   * last EMIT (`at - lastAt < throttleMs`) is dropped from immediate firing —\n   * the leading-edge \"at most once per `throttleMs`\" rate-cap rule, applied to\n   * emits. The half-open cutoff (`>=` passes) matches `../throttle` and\n   * `../cache`'s window-edge convention. Omit for no rate cap.\n   *\n   * Interacts with `debounceMs`: when both are set, a rate-blocked input is\n   * still HELD as `pending` (so the settle timer eventually trails it out at a\n   * legal moment) rather than silently dropped — the trailing-edge guarantee\n   * that the FINAL sample of a window is never lost.\n   */\n  readonly throttleMs?: number;\n  /**\n   * Settle wait, in milliseconds. An input that clears the rate gate is not\n   * emitted immediately; it is held as `pending` and a debounce deadline is\n   * armed at `pendingAt + debounceMs`. A fresh input re-arms (slides) the\n   * window. `onFlush` emits the pending value when the window finally expires.\n   * Omit for no settle wait — a passing input emits on arrival.\n   */\n  readonly debounceMs?: number;\n  /**\n   * Map a settled value to the single Cmd the runtime performs. Called with the\n   * value the gates let through; the returned Cmd is what `input` / `onFlush`\n   * emit. PURE constructor — no I/O, no clock; the I/O happens later in the\n   * consumer's interpret handler for the returned Cmd.\n   */\n  readonly emit: (value: V) => C;\n}\n\n/**\n * Configuration for a throttled input — the knob. Pure config, no mutable state\n * (the `ThrottledInput<V>` slice carries that). One config object is shared\n * across every input of one logical stream (often a module-scope const).\n *\n * A DISCRIMINATED UNION on the presence of dedupe, so the type system makes a\n * cache-key collision UNREPRESENTABLE (\"omit a brick, omit its gate\"):\n *\n *   - **No dedupe** (`ThrottledInputNoCache`): `cacheTtlMs` absent ⇒ no cache\n *     slice, no dedupe. `cacheKey` is statically forbidden here (`never`) — a\n *     key with no cache to feed is dead config, so the type rejects it rather\n *     than silently ignoring it.\n *   - **Dedupe** (`ThrottledInputWithCache`): `cacheTtlMs` set ⇒ `cacheKey` is\n *     REQUIRED. There is no `String(value)` default to fall back to, so a\n *     structured value can NEVER collapse two distinct values to one slot (the\n *     `\"[object Object]\"` collision). The consumer must state the identity that\n *     keys the cache; a primitive stream still trivially passes `(v) => v` /\n *     `String`, but it does so EXPLICITLY.\n */\nexport type ThrottledInputConfig<V, C extends Cmd> =\n  | ThrottledInputNoCache<V, C>\n  | ThrottledInputWithCache<V, C>;\n\n/**\n * The no-dedupe config variant: gates only, no cache. `cacheTtlMs` is absent\n * and `cacheKey` is statically `never` so a stray key (which would feed no\n * cache) is a type error, not a silently-ignored field.\n */\nexport interface ThrottledInputNoCache<V, C extends Cmd>\n  extends ThrottledInputGates<V, C> {\n  readonly cacheTtlMs?: undefined;\n  readonly cacheKey?: never;\n}\n\n/**\n * The dedupe config variant: a per-entry TTL plus a REQUIRED `cacheKey`. An\n * input whose `cacheKey` is already cached and unexpired emits NOTHING (the\n * downstream effect ran once for that key within its TTL); a fresh emit writes\n * the value into the cache.\n *\n * `cacheKey` is required (no `String(value)` default) precisely so a structured\n * value cannot silently collide — the consumer names the identity, the cache\n * keys on exactly that.\n */\nexport interface ThrottledInputWithCache<V, C extends Cmd>\n  extends ThrottledInputGates<V, C> {\n  /**\n   * Dedupe / memoize TTL, in milliseconds. An input whose `cacheKey` is already\n   * cached and unexpired emits NOTHING; a fresh emit writes the value into the\n   * cache so the next identical input within `cacheTtlMs` is suppressed.\n   */\n  readonly cacheTtlMs: number;\n  /**\n   * Key a value for the dedupe cache. REQUIRED whenever `cacheTtlMs` is set:\n   * there is no `String(value)` fallback, so a structured value's identity is\n   * always the consumer's explicit choice and two distinct values can never\n   * collapse to one slot. A primitive stream passes `(v) => v` / `String`.\n   */\n  readonly cacheKey: (value: V) => string;\n}\n\n/**\n * The Model slice a throttled input owns — its visible slice (the knob\n * principle: managed state lives in the Model, never a closure, so it is durable\n * and replayable).\n *\n * - `lastAt`  — the `at` of the most recent EMIT, or `null` before the first\n *               emit. The `../throttle` rate cap measures against it: an input\n *               within `throttleMs` of `lastAt` is rate-blocked. Persisted so a\n *               resumed gate keeps its rate cursor.\n * - `pending` — the value HELD for the settle (debounce) window, paired with the\n *               `at` it was held (the anchor the deadline targets), or `null`\n *               when nothing is waiting. The single source of truth for \"is a\n *               settle window open?\" — the debounce timer Sub arms iff this is\n *               non-null.\n * - `cache`   — the `../cache` TTL store backing dedupe, present IFF\n *               `cacheTtlMs` is configured. Absent (the field omitted) for a\n *               gate with no dedupe — no per-op cost, nothing to serialize.\n */\nexport interface ThrottledInput<V> {\n  readonly lastAt: number | null;\n  readonly pending: PendingInput<V> | null;\n  readonly cache?: TtlCache<V>;\n}\n\n/**\n * A value held for the settle window: the `value` itself and the `at` it was\n * held (the anchor the debounce deadline targets, `at + debounceMs`). A distinct\n * type (not a bare `V`) because `V` may itself be `null` — a present-but-null\n * value is still a real pending input, distinct from \"nothing pending\", exactly\n * the `null`-sentinel discipline `../throttle` / `../debounce` use for their\n * `pendingArgs`.\n */\nexport interface PendingInput<V> {\n  readonly value: V;\n  readonly at: number;\n}\n\n/**\n * The deadline a throttled input's settle timer lists — a `../deadline` entry\n * (so the window fires at the correct ABSOLUTE moment even after a late\n * subscribe / rehydrate, and so a consumer running several gates routes each by\n * `id`). `atMs` is the absolute settle-by instant (`pendingAt + debounceMs`).\n */\nexport type ThrottledInputSub = DeadlineSub;\n\n/**\n * The stable id the gate arms its settle deadline under. A single gate arms\n * exactly one settle timer at a time, so one id suffices; a consumer running\n * several gates on one machine namespaces them by composing the knob under\n * distinct slices with distinct ids (the `subs(state, id)` parameter).\n */\nconst DEFAULT_SUB_ID = \"throttled-input:settle\";\n\n/**\n * The starting slice: no prior emit, nothing pending. The `cache` field is\n * seeded only when `cacheTtlMs` is configured (see `createThrottledInput`); the\n * free `initThrottledInput` leaves it absent (the no-dedupe shape).\n */\nexport function initThrottledInput<V>(): ThrottledInput<V> {\n  return { lastAt: null, pending: null };\n}\n\n/**\n * Resolve a value's cache key under a DEDUPE config. PURE. Takes the narrowed\n * `ThrottledInputWithCache` (not the union) because `cacheKey` is only present —\n * and only meaningful — when dedupe is on; there is no `String(value)` default\n * to fall back to, so a structured value's identity is always the consumer's\n * explicit choice and two distinct values can never collapse to one slot.\n */\nfunction keyOf<V, C extends Cmd>(\n  config: ThrottledInputWithCache<V, C>,\n  value: V,\n): string {\n  return config.cacheKey(value);\n}\n\n/**\n * Narrow `config` to its dedupe variant iff a cache slice is actually wired —\n * `cacheTtlMs` set AND a `cache` store present. Returns the narrowed config\n * (carrying the required `cacheKey`) paired with the resolved `cache` store, or\n * `null` when no dedupe is configured. The single place the union is\n * discriminated, so `isCacheHit` / `commitEmit` share one narrowing — and reuse\n * the resolved `cache` — rather than re-deriving the predicate and re-narrowing\n * `state.cache`.\n */\nfunction cacheConfig<V, C extends Cmd>(\n  config: ThrottledInputConfig<V, C>,\n  state: ThrottledInput<V>,\n): {\n  readonly config: ThrottledInputWithCache<V, C>;\n  readonly cache: TtlCache<V>;\n} | null {\n  return config.cacheTtlMs !== undefined && state.cache !== undefined\n    ? { config, cache: state.cache }\n    : null;\n}\n\n/**\n * Whether `value` is a cache HIT under `config` at `at` — present and unexpired.\n * PURE — reads only. Always `false` when `cacheTtlMs` is unset or no `cache`\n * slice exists (no dedupe configured), so the dedupe gate is a no-op for an\n * unconfigured gate.\n */\nfunction isCacheHit<V, C extends Cmd>(\n  config: ThrottledInputConfig<V, C>,\n  state: ThrottledInput<V>,\n  value: V,\n  at: number,\n): boolean {\n  const cached = cacheConfig(config, state);\n  if (cached === null) return false;\n  return cacheGet(cached.cache, keyOf(cached.config, value), at) !== undefined;\n}\n\n/**\n * Emit `value` at clock `at`: bump the rate cursor, refresh the dedupe cache,\n * and clear any pending hold. PURE. The single place an emit's bookkeeping\n * lives, shared by `input` (immediate emit) and `onFlush` (trailing emit) so the\n * two paths can never drift on what an emit updates.\n *\n * - `lastAt` advances to `at` — the next input is rate-measured against this\n *   emit, the `../throttle` window cursor.\n * - `cache` (when configured) records `value` under its key with `cacheTtlMs`\n *   from `at` — so the next identical input within the TTL is suppressed.\n * - `pending` clears — the value just went out; nothing is waiting.\n */\nfunction commitEmit<V, C extends Cmd>(\n  config: ThrottledInputConfig<V, C>,\n  state: ThrottledInput<V>,\n  value: V,\n  at: number,\n): readonly [ThrottledInput<V>, readonly C[]] {\n  const cached = cacheConfig(config, state);\n  const cache =\n    cached !== null\n      ? cacheSet(\n          cached.cache,\n          keyOf(cached.config, value),\n          value,\n          at,\n          cached.config.cacheTtlMs,\n        )\n      : state.cache;\n  const next: ThrottledInput<V> = {\n    ...state,\n    lastAt: at,\n    pending: null,\n    ...(cache !== undefined ? { cache } : {}),\n  };\n  return [next, [config.emit(value)]];\n}\n\n/**\n * Feed a new input `value` arriving at clock `at` through the gates. PURE.\n *\n * The gate order is DEDUPE → RATE → SETTLE (each skipped when its config field\n * is omitted), the same cache-first-then-gate order `resilient-call` uses (a hit\n * short-circuits before the expensive path):\n *\n *   1. **Dedupe** (`cacheTtlMs` set): if `value`'s key is cached and unexpired,\n *      suppress — return the slice UNCHANGED (no emit, no pending, no re-arm).\n *      The downstream effect already ran for this key within its TTL.\n *   2. **Rate** (`throttleMs` set): if `at` is within `throttleMs` of the last\n *      emit (`at - lastAt < throttleMs`), this input is rate-blocked.\n *        - With `debounceMs` set → HOLD it as `pending` (the trailing edge: the\n *          settle timer will emit it at a legal moment, so the final sample is\n *          never lost). The deadline `subs` arms targets `at + debounceMs`.\n *        - Without `debounceMs` → DROP it (pure rate cap, no catch-up).\n *   3. **Settle** (`debounceMs` set): the input cleared the rate gate. HOLD it\n *      as `pending` and let the debounce window slide; `onFlush` emits it once\n *      the window expires. A fresh input before expiry overwrites `pending` (the\n *      trailing edge fires with the LAST value, the `../debounce` default).\n *   4. **Pass-through**: no `debounceMs`, cleared the rate gate → EMIT now.\n *\n * @param config the knob (the three optional gates + `emit`)\n * @param state  the current slice\n * @param value  the input value\n * @param at     the arrival instant (epoch ms) — the caller stamps it; the verb\n *               never reads the clock\n */\nexport function input<V, C extends Cmd>(\n  config: ThrottledInputConfig<V, C>,\n  state: ThrottledInput<V>,\n  value: V,\n  at: number,\n): readonly [ThrottledInput<V>, readonly C[]] {\n  // 1. Dedupe gate — a cached, unexpired key short-circuits everything.\n  if (isCacheHit(config, state, value, at)) {\n    return [state, []];\n  }\n\n  // 2. Rate gate — half-open cutoff (`>=` passes). `lastAt === null` (no prior\n  // emit) always passes: the first input is never rate-blocked. Shared with\n  // `onFlush` via `rateBlockedAt` so the arrival and trailing-edge paths agree\n  // on the window.\n  if (rateBlockedAt(config, state, at)) {\n    // With a settle window, a rate-blocked input is HELD (trailing edge) so it\n    // emits at the next legal moment; without one, it is a pure drop.\n    if (config.debounceMs !== undefined) {\n      return [{ ...state, pending: { value, at } }, []];\n    }\n    return [state, []];\n  }\n\n  // 3. Settle gate — passed the rate gate; if a debounce window is configured,\n  // hold the value and (re)arm the settle deadline rather than emit now.\n  if (config.debounceMs !== undefined) {\n    return [{ ...state, pending: { value, at } }, []];\n  }\n\n  // 4. Pass-through — no settle wait, cleared the rate gate: emit immediately.\n  return commitEmit(config, state, value, at);\n}\n\n/**\n * Whether emitting at clock `at` would breach the rate cap — `at` lands within\n * `throttleMs` of the last emit (`at - lastAt < throttleMs`). PURE — reads only.\n * Always `false` when `throttleMs` is unset (no rate cap) or before the first\n * emit (`lastAt === null`), so an unconfigured / never-fired gate never holds on\n * the rate gate. The single rate-gate predicate, shared by `input` (drop / hold\n * on arrival) and `onFlush` (re-hold a still-early trailing edge) so the two\n * paths can never drift on what \"within the rate window\" means.\n */\nfunction rateBlockedAt<V, C extends Cmd>(\n  config: ThrottledInputConfig<V, C>,\n  state: ThrottledInput<V>,\n  at: number,\n): boolean {\n  return (\n    config.throttleMs !== undefined &&\n    state.lastAt !== null &&\n    at - state.lastAt < config.throttleMs\n  );\n}\n\n/**\n * Emit the pending value because the settle (debounce) window closed. PURE.\n *\n * - Pending present, rate gate CLEAR → emit `config.emit(pending.value)`,\n *   advance the rate cursor (`lastAt = at`), refresh the dedupe cache, and clear\n *   `pending`. The trailing edge of `../debounce` realized as a Model transition.\n * - Pending present, rate gate STILL BLOCKED → re-HOLD: return the slice with\n *   `pending` intact and NO Cmds. A settle Msg can fire at `pending.at +\n *   debounceMs`, which may still be inside the rate window (`lastAt +\n *   throttleMs`) — emitting then would breach the headline \"at most once per\n *   `throttleMs`\" cap. Re-holding keeps the value waiting; `subs` re-arms the\n *   deadline at `max(pending.at + debounceMs, lastAt + throttleMs)` so the next\n *   timer fires at a LEGAL moment and the trailing edge is deferred, never lost.\n * - Pending absent → no-op: return the same slice and no Cmds. Guards the race\n *   where an `input` already emitted (or a dedupe hit cleared interest) before\n *   the settle timer's Msg lands — a stale `onFlush` must NOT emit. Symmetric\n *   with `batch-window`'s closed-window guard.\n *\n * `at` is the firing instant the settle Msg carried (the caller stamps it; the\n * verb never reads the clock). It becomes the new rate cursor and the cache\n * write's `nowMs`, so a settled emit rate-blocks subsequent inputs from its\n * actual fire moment, not the moment the value was first held.\n *\n * @param config the knob (`throttleMs`, `emit`, cache config)\n * @param state  the current slice\n * @param at     the settle-timer firing instant (epoch ms)\n */\nexport function onFlush<V, C extends Cmd>(\n  config: ThrottledInputConfig<V, C>,\n  state: ThrottledInput<V>,\n  at: number,\n): readonly [ThrottledInput<V>, readonly C[]] {\n  // No pending value = an immediate emit already fired, or a dedupe hit cleared\n  // interest. A stale timer Msg must not emit — return the slice untouched.\n  if (state.pending === null) return [state, []];\n  // Rate gate re-check: a settle Msg can land before the rate window opens (its\n  // naive deadline is pending.at + debounceMs, which `subs` lifts to a legal\n  // target — but a stale / early timer can still arrive). Emitting now would\n  // breach \"at most once per throttleMs\", so re-hold and let `subs` re-arm at\n  // the legal moment. The value stays pending; nothing is dropped.\n  if (rateBlockedAt(config, state, at)) return [state, []];\n  return commitEmit(config, state, state.pending.value, at);\n}\n\n/**\n * The settle timer deadline, derived from the slice. PURE.\n *\n * Returns the single `../deadline` entry while a value is held AND a settle window\n * is configured, or `[]` otherwise. The deadline target is the LATER of two\n * constraints (so the timer never fires before BOTH are satisfied):\n *\n *   - `pending.at + debounceMs` — the settle (debounce) deadline: the value has\n *     stopped sliding, the burst has gone quiet.\n *   - `lastAt + throttleMs` — the rate cap: emitting earlier would breach \"at\n *     most once per `throttleMs`\". Only applies once a prior emit exists\n *     (`lastAt !== null`) and a rate cap is configured (`throttleMs` set).\n *\n * `max(settleAt, rateAt)` is the earliest LEGAL trailing-edge moment. Anchoring\n * the timer here — rather than the naive `pending.at + debounceMs` — is what\n * keeps the rate cap intact across the trailing edge: a value held while still\n * inside the rate window arms its timer at `lastAt + throttleMs`, so `onFlush`\n * fires at a moment the rate gate already permits. (`onFlush` re-checks the gate\n * anyway and re-holds if an early/stale timer slips through, so the cap holds\n * even if a timer fires ahead of this target.)\n *\n * Fed through `deadlinesSub`, the engine arms the timer when the list gains the\n * deadline and disarms it (clearing the pending `setTimeout`) when the list\n * loses it — so an\n * `onFlush` (or a dedupe hit) that clears `pending` auto-cancels the now-stale\n * settle timer on the next transition, and a sliding input that re-stamps\n * `pending.at` re-arms a fresh absolute target.\n *\n * `debounceMs` undefined ⇒ no settle window ⇒ `[]` even with a `pending` value\n * (an unconfigured settle never holds, but the guard keeps `subs` total).\n *\n * @param config the knob (`debounceMs`, `throttleMs`)\n * @param state  the current slice\n * @param id     stable identity for this gate's settle timer (default\n *               `\"throttled-input:settle\"`); pass a distinct id per gate when a\n *               machine runs several so the dispatched Msg routes distinctly.\n */\nexport function subsFor<V, C extends Cmd>(\n  config: ThrottledInputConfig<V, C>,\n  state: ThrottledInput<V>,\n  id = DEFAULT_SUB_ID,\n): readonly ThrottledInputSub[] {\n  if (config.debounceMs === undefined || state.pending === null) return [];\n  const settleAt = state.pending.at + config.debounceMs;\n  // The rate floor: the earliest moment the rate cap permits an emit. Absent\n  // when no rate cap is configured or no prior emit set a cursor — then the\n  // settle deadline alone governs.\n  const rateAt =\n    config.throttleMs !== undefined && state.lastAt !== null\n      ? state.lastAt + config.throttleMs\n      : settleAt;\n  return [deadlineSub(id, Math.max(settleAt, rateAt))];\n}\n\n/**\n * The bound knob returned by `createThrottledInput`. `init` + the two pure verbs\n * + `subs`, all closing over one `ThrottledInputConfig`. The verbs return\n * `readonly [ThrottledInput<V>, readonly C[]]`: the next slice and the Cmds to\n * emit (one `emit` Cmd when a value passes, none while held / dropped / deduped).\n *\n * Pure-ops + subs module: there is no `handlers(ports)` cell. The settle timer's\n * runner IS `../deadline`'s `subscribeDeadline` (re-exported below) — the\n * consumer passes it to `run` as `subscribe.deadline`; the knob redraws no timer\n * lifecycle of its own. (Compare `poller`, identical: it too reuses\n * `../deadline`'s runner and ships no `handlers`.)\n */\nexport interface ThrottledInputKnob<V, C extends Cmd> {\n  /** Seed the Model slice (with a cache iff `cacheTtlMs` is configured). */\n  init(): ThrottledInput<V>;\n  /**\n   * Feed a new input through the dedupe → rate → settle gates. See `input`.\n   */\n  input(\n    state: ThrottledInput<V>,\n    value: V,\n    at: number,\n  ): readonly [ThrottledInput<V>, readonly C[]];\n  /**\n   * Emit the held value because the settle window closed. See `onFlush`.\n   */\n  onFlush(\n    state: ThrottledInput<V>,\n    at: number,\n  ): readonly [ThrottledInput<V>, readonly C[]];\n  /**\n   * The settle timer deadline, listed only while a value is held. See\n   * `subsFor`. `id` keys the deadline so several gates on one machine route\n   * distinctly.\n   */\n  subs(state: ThrottledInput<V>, id?: string): readonly ThrottledInputSub[];\n}\n\n/**\n * Build a throttled-input knob from `config`. Combinator form (the default L2\n * ergonomic): hand it the config, splice the returned hooks into your machine.\n * The pure verbs (`input` / `onFlush`) close over the config so the consumer's\n * reducer cells stay a uniform `(state, ...args)` shape; `subs` pre-wires the\n * settle timer.\n *\n * `init()` seeds a `cache` slice IFF `cacheTtlMs` is configured — an unconfigured\n * gate carries no cache field (nothing to serialize, no dedupe). Pure factory —\n * no clock read, no timer; everything happens when the consumer calls the\n * returned verbs / `subs` with an injected `at`.\n *\n * @typeParam V the input value type\n * @typeParam C the Cmd type `config.emit` returns\n */\nexport function createThrottledInput<V, C extends Cmd>(\n  config: ThrottledInputConfig<V, C>,\n): ThrottledInputKnob<V, C> {\n  function init(): ThrottledInput<V> {\n    const base = initThrottledInput<V>();\n    // Seed the cache only when dedupe is configured — an unconfigured gate\n    // carries no cache field at all (the no-dedupe shape).\n    return config.cacheTtlMs !== undefined\n      ? { ...base, cache: initCache<V>() }\n      : base;\n  }\n\n  return {\n    init,\n    input: (state, value, at) => input(config, state, value, at),\n    onFlush: (state, at) => onFlush(config, state, at),\n    subs: (state, id) => subsFor(config, state, id),\n  };\n}\n\n/**\n * The settle-timer wiring, RE-EXPORTED from `../deadline` (not redrawn) so the\n * timer lifecycle stays owned there. Consolidated into one `export ... from`:\n *\n *   - `subscribeThrottledInput` (= `../deadline`'s `subscribeDeadline`) — the\n *     `deadline` runner. Arms a one-shot timer per listed deadline for\n *     `max(0, atMs - now)`, dispatches the deadline Msg, returns a cleanup that\n *     clears them. The consumer passes it to `run`:\n *     `subscribe: { deadline: subscribeThrottledInput }`.\n *   - `throttledInputSettled` (= `../deadline`'s `deadlineExceeded`) +\n *     `ThrottledInputSettled` (= `DeadlineExceeded`) — the settle-timer Msg\n *     constructor and type the consumer handles via `onFlush`. Sharing one\n *     constructor with the runner keeps the two from drifting; the\n *     reducer reads `msg.atMs` as the `at` it threads into `onFlush`.\n */\nexport {\n  type DeadlineExceeded as ThrottledInputSettled,\n  deadlineExceeded as throttledInputSettled,\n  subscribeDeadline as subscribeThrottledInput,\n} from \"../../resilience/deadline\";\n"]}

package/dist/{types-DP3f5NIl.d.ts → types-LxZxGYda.d.ts}

@@ -1,5 +1,5 @@
-import { S as Sub } from './core-CTzMJ82M.js';
+import { S as Sub, h as Dispose } from './core-BbgtiXdg.js';
 
-type SubscribeHandler<S extends Sub, M, Ctx> = (sub: S, ctx: Ctx, dispatch: (msg: M) => void) => () => void;
+type SubscribeHandler<S extends Sub, M, Ctx> = (sub: S, ctx: Ctx, dispatch: (msg: M) => void) => Dispose;
 
 export type { SubscribeHandler as S };

package/dist/work-queue/index.d.ts

@@ -1,9 +1,8 @@
-import { Q as QueueItem } from '../index-DJWIER_3.js';
-export { E as EnqueueInput, a as QueueItemStatus, c as createQueue } from '../index-DJWIER_3.js';
-import '../runtime-types-LWDoi943.js';
-import 'better-result';
-import '../core-CTzMJ82M.js';
-import 'zod';
+import { Q as QueueItem } from '../index-7vV8xmsD.js';
+export { E as EnqueueInput, a as QueueItemStatus, c as createQueue } from '../index-7vV8xmsD.js';
+import '../runtime-types-CiVpC0HN.js';
+import '../core-BbgtiXdg.js';
+import '@standard-schema/spec';
 
 /**
  * internal/work-queue/adapter — the verb seam over the pure queue ops.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@demlik/tea",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "description": "TEA-faithful state machine substrate — one package, every host adapter. Core + subs + testing, plus React, Durable Object, Chrome extension, Node, in-memory, devtools, and property-testing modules as subpaths.",
   "keywords": [
     "tea",
@@ -31,6 +31,14 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
+    "./promise": {
+      "types": "./dist/promise/index.d.ts",
+      "import": "./dist/promise/index.js"
+    },
+    "./effect": {
+      "types": "./dist/effect/index.d.ts",
+      "import": "./dist/effect/index.js"
+    },
     "./do": {
       "types": "./dist/do/index.d.ts",
       "import": "./dist/do/index.js"
@@ -115,10 +123,10 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "better-result": "^2.5.2",
-    "zod": "^4.5.4"
+    "@standard-schema/spec": "^1.1.0"
   },
   "peerDependencies": {
+    "effect": "^4.0.0-rc.0",
     "fast-check": "^3 || ^4",
     "react": "^18 || ^19",
     "react-dom": "^18 || ^19",
@@ -126,6 +134,9 @@
     "ws": "^8"
   },
   "peerDependenciesMeta": {
+    "effect": {
+      "optional": true
+    },
     "fast-check": {
       "optional": true
     },
@@ -147,13 +158,14 @@
     "@biomejs/biome": "2.3.14",
     "@changesets/cli": "^2.27.11",
     "@cloudflare/workers-types": "4.20260312.1",
-    "@kampus/fabrika-cli": "0.5.0",
+    "@kampus/fabrika-cli": "0.7.1",
     "@types/chrome": "^0.1.42",
     "@types/node": "^22",
     "@types/react": "19.0.8",
     "@types/react-dom": "19.0.3",
     "@types/ws": "8.5.14",
     "ai": "^7.0.93",
+    "effect": "4.0.0-rc.117",
     "fast-check": "^3.23.0",
     "happy-dom": "^20.9.0",
     "react": "19.0.0",
@@ -163,7 +175,8 @@
     "typescript": "5.7.3",
     "vite": "^8.2.1",
     "vitest": "~3.0.7",
-    "ws": "8.18.1"
+    "ws": "8.18.1",
+    "zod": "^4.5.4"
   },
   "publishConfig": {
     "access": "public"

package/dist/chunk-AQ6ZIMEA.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/protocol.ts","../src/internal/resilience/circuit-breaker/index.ts","../src/internal/resilience/rate-limit/index.ts","../src/internal/resilience/resilient-call/index.ts"],"names":[],"mappings":"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","file":"chunk-AQ6ZIMEA.js","sourcesContent":["// ===========================================================================\n// Protocol — the ONE typed source of truth for the cross-module Msg/Cmd\n// discriminant strings (issue #60).\n// ===========================================================================\n//\n// The resilient/agent/auth plumbing speaks a small fixed vocabulary of\n// discriminant strings on `{ type: ... }` Msgs and Cmds. Before this module\n// those literals were retyped inline across ~8 modules — `resilient_ok` alone\n// appeared as a hand-written `\"resilient_ok\"` in resilient-call, with-resilience,\n// llm-call, agent, do/host, paginated-walk, reconciler. Adding a variant or\n// renaming one was shotgun surgery with no compiler to catch a missed site.\n//\n// `MsgType` is that vocabulary, declared ONCE `as const`. Each entry is BOTH:\n//   - a value — `MsgType.ResilientOk` is the string `\"resilient_ok\"`, used at\n//     construction sites (`{ type: MsgType.ResilientOk, ... }`), reducer keys\n//     (`[MsgType.ResilientOk]: ...`), and switch labels (`case MsgType.ResilientOk:`).\n//   - a type — `typeof MsgType.ResilientOk` is the literal type `\"resilient_ok\"`,\n//     used in the `readonly type:` field of every Msg/Cmd interface.\n//\n// Because the value and the type both derive from the single `as const`\n// declaration, a new variant or a rename is a ONE-LINE change here that\n// propagates with full exhaustiveness — not an 8-file edit.\n//\n// This module is BEHAVIOR-PRESERVING: every string is byte-identical to the\n// literal it replaces. It is internal plumbing vocabulary, NOT a public event\n// surface — `resilient_ok` / `agent_tool_ok` stay PRIVATE (the agent's\n// `agentEvents` projector is the ONE place they are read; #47). Centralizing\n// the literal here does NOT re-expose them to consumers.\n\n/**\n * The closed set of cross-module Msg/Cmd discriminant strings. Declared `as\n * const` so each entry is usable as both a value (construction / reducer keys /\n * switch labels) and, via `typeof MsgType.X`, a literal type (`readonly type:`\n * fields). The single source of truth for issue #60.\n */\nexport const MsgType = {\n  // --- resilient-call: the run Cmd + its two settle Msgs -------------------\n  /** The \"run the port for `key`\" effect Cmd resilient-call emits. */\n  ResilientRun: \"resilient_run\",\n  /** PRIVATE success settle Msg (read only by `agentEvents`, #47). */\n  ResilientOk: \"resilient_ok\",\n  /** Failure settle Msg — routed to the `fail` verb (back off via retry). */\n  ResilientErr: \"resilient_err\",\n\n  // --- agent: the wired machine's own entry-point Msgs ---------------------\n  /** Begin a run. */\n  AgentStart: \"agent_start\",\n  /** PRIVATE tool-fan-out success settle Msg (read only by `agentEvents`, #47). */\n  AgentToolOk: \"agent_tool_ok\",\n  /** Tool-fan-out failure settle Msg. */\n  AgentToolErr: \"agent_tool_err\",\n  /**\n   * Re-fire the one outstanding effect on rehydrate (the do↔agent seam). Fired\n   * by `do/host`'s `autoBoot` via the typed `agentBootMsg` constructor, matched\n   * by the agent reducer — see `AgentBootPort` in `../agent`.\n   */\n  AgentBoot: \"agent_boot\",\n  /**\n   * Stop the run from outside and settle it `cancelled` — what an `AbortSignal`\n   * handed to `driveToDone` / a defined agent's `run` dispatches on abort. A\n   * transition, never a throw: the outcome lands in the Model, so a reload reads\n   * a run that ended rather than one to resume.\n   */\n  AgentCancel: \"agent_cancel\",\n\n  // --- agent: the context-compaction round-trip (#85) ----------------------\n  /**\n   * The \"summarize the oldest N turns\" effect Cmd the agent emits when its\n   * `CompactionPolicy` asks to compact before a brain call. A DEDICATED\n   * round-trip (design B1), distinct from the brain call's `resilient_run`, so\n   * compaction is its own honest `Awaiting` state — see `../agent`.\n   */\n  CompactRun: \"compact_run\",\n  /** Compaction round-trip resolved — carries the summary text the fold-back folds. */\n  CompactOk: \"compact_ok\",\n  /** Compaction round-trip failed (exhausted retry) — surfaced as data, not a stall. */\n  CompactErr: \"compact_err\",\n\n  // --- token-refresh: the two refresh-result Msgs --------------------------\n  /** Refresh port resolved — carries the fresh `Token`. */\n  TokenRefreshed: \"token_refreshed\",\n  /** Refresh port rejected — carries the rejection (errors are data). */\n  TokenRefreshFailed: \"token_refresh_failed\",\n\n  // --- authed-call: the 401 trigger ----------------------------------------\n  /** The 401 the consumer dispatches when a guarded call comes back unauthorized. */\n  Unauthorized: \"unauthorized\",\n} as const;\n\n/** The union of every discriminant string in the protocol. */\nexport type MsgTypeValue = (typeof MsgType)[keyof typeof MsgType];\n","/**\n * @packageDocumentation\n * internal/resilience/circuit-breaker — per-target failure tracking as pure state + ops.\n *\n * Same shape as `../../work-queue/ops.ts`, `../rate-limit/`, and\n * `../../idempotency/`: a state type plus pure transition functions.\n * Host-agnostic by construction — no `Date.now()`, no timers, no I/O. The\n * caller injects the clock (`nowMs`) and wires the result into its own reducer\n * / interpret. This keeps the breaker inside TEA's invariant 2 (transitions are\n * pure: same inputs → same outputs, no `Date.now`) so a consumer can fold it\n * through `update` and exercise it with `replay` / the pbt fold without a fake\n * clock.\n *\n * Every op returns a NEW state value and never mutates its input (invariant 1 —\n * state is a value, not a place). `canPass` returns a `[next, allowed]` tuple so\n * the caller branches on the decision while threading the advanced state forward\n * — same convention as `rate-limit`'s `tryConsume` / `record`. `onSuccess` /\n * `onFailure` are the outcome-recording transitions the caller folds in once the\n * guarded call resolves.\n *\n * ## The phase machine\n *\n * A circuit breaker guards a fallible downstream target (an HTTP backend, a DB,\n * a flaky tool call). Instead of hammering a target that is already failing, it\n * trips OPEN after enough failures and fast-fails subsequent calls for a\n * cooldown, then probes with a few trial calls before fully closing again.\n * Three phases, each carrying ONLY its own data so impossible states are\n * unrepresentable (pattern 11):\n *\n *   - **closed** — the healthy steady state. Calls pass through. Carries\n *     `failures`: the count of *consecutive* failures since the last success.\n *     A success resets it to 0; the `failureThreshold`-th failure trips the\n *     breaker OPEN. Only `closed` has a failure counter — `open` and\n *     `half_open` don't, because in those phases the count is irrelevant\n *     (the breaker has already tripped / is already probing).\n *\n *   - **open** — the tripped state. All calls fast-fail (no downstream load).\n *     Carries `openedAtMs`: the clock reading at which the breaker tripped.\n *     `canPass` compares `nowMs - openedAtMs` against `cooldownMs` to decide\n *     when to start probing. Only `open` carries a timestamp — neither other\n *     phase is timing anything.\n *\n *   - **half_open** — the probing state. A limited number of trial calls are\n *     allowed through to test whether the target has recovered. Carries\n *     `probes`: the count of probes admitted so far this probing round.\n *     `canPass` admits while `probes < halfOpenMaxProbes`, then fast-fails the\n *     rest (so a slow target can't be flooded by every queued caller at once).\n *     A probe success closes the breaker; a probe failure re-opens it (and\n *     resets the cooldown clock). Only `half_open` counts in-flight probes.\n *\n * ### Transition table\n *\n * Rows are the current phase; columns are the event. `→` denotes the next\n * phase; `self` means unchanged. `nowMs` is the injected clock.\n *\n * | from \\ event | onSuccess      | onFailure                              | canPass (→ allowed?)                                                                 |\n * | ------------ | -------------- | -------------------------------------- | ------------------------------------------------------------------------------------ |\n * | closed       | closed(0)      | failures+1; trip → open(nowMs) at thr. | self → true (always)                                                                  |\n * | open         | self *(¹)*     | self                                   | elapsed ≥ cooldown → half_open(1), true; else self → false                            |\n * | half_open    | → closed(0)    | → open(nowMs) (probe failed)           | probes < max → half_open(probes+1), true; else self → false                          |\n *\n * *(¹)* `onSuccess` on `open` \"shouldn't happen\": no call was admitted while\n * open, so no success can be reported for one. We leave the state unchanged\n * rather than throw — the breaker is a coordination aid, not a correctness\n * gate, and a spurious success report (e.g. a late-arriving result from before\n * the trip) must not silently un-trip the breaker. `onFailure` on `open` is\n * likewise a no-op: the breaker is already tripped; the `open` clock is anchored\n * at the trip, not bumped by late failures.\n *\n * ### The probe-admission asymmetry\n *\n * Entering `half_open` happens inside `canPass`, not `onSuccess` / `onFailure`,\n * because the cooldown is a *time* condition and only `canPass` reads the clock\n * against `openedAtMs`. The first `canPass` after the cooldown elapses both\n * transitions the phase AND admits the probe (`[half_open(1), true]`) — one\n * caller drives the recovery attempt. Subsequent `canPass` calls in the same\n * round admit up to `halfOpenMaxProbes` total, then fast-fail until a probe\n * resolves and `onSuccess` / `onFailure` moves the phase out of `half_open`.\n *\n * This module is a textbook three-state machine — a clean `/machine-viz` demo.\n *\n * Internal to the package (`src/internal/resilience/`), not a published\n * subpath (#46); same one-shape-per-module rule as `work-queue`, `rate-limit`,\n * and `idempotency`.\n */\n\n/**\n * Circuit-breaker policy — pure configuration, no mutable state. One policy is\n * shared across all the calls guarded by one logical breaker (often a\n * module-scope const). `CircuitState` carries the mutable counts; this carries\n * the thresholds those counts are compared against.\n */\nexport interface CircuitPolicy {\n  /**\n   * Consecutive failures in `closed` that trip the breaker `open`. The\n   * `failureThreshold`-th failure is the one that trips — with a threshold of\n   * 5, the breaker survives 4 failures and opens on the 5th.\n   */\n  readonly failureThreshold: number;\n  /**\n   * How long the breaker stays `open` before `canPass` starts admitting\n   * probes, in milliseconds. Measured from `openedAtMs`; the cutoff is\n   * half-open (`elapsed >= cooldownMs` admits), matching `rate-limit` /\n   * `idempotency` window edges — a breaker opened at `t` first probes at\n   * `t + cooldownMs`.\n   */\n  readonly cooldownMs: number;\n  /**\n   * How many probe calls `half_open` admits before fast-failing the rest of\n   * the round. Caps the load on a recovering target — a single slow probe\n   * can't be joined by every queued caller. The round ends when a probe\n   * resolves: success closes the breaker, failure re-opens it.\n   */\n  readonly halfOpenMaxProbes: number;\n}\n\n/**\n * Sensible defaults: trip after 5 consecutive failures, cool down for 30s,\n * admit a single probe before deciding. Tuned for guarding a network backend;\n * override per call site rather than mutating this shared const.\n */\nexport const defaultCircuitPolicy: CircuitPolicy = {\n  failureThreshold: 5,\n  cooldownMs: 30_000,\n  halfOpenMaxProbes: 1,\n};\n\n/**\n * The breaker's phase. A discriminated union on `phase` so each phase carries\n * ONLY its own data and impossible combinations are unrepresentable (pattern\n * 11): there is no state with both a failure count AND an open timestamp,\n * because such a state is meaningless. `phase` is the discriminant; every field\n * is `readonly` so the whole value is trivially JSON-serializable into a\n * consumer's `Store<S>` and safe to thread through a pure reducer.\n *\n *   - `closed`    carries `failures`   — consecutive failures since last success.\n *   - `open`      carries `openedAtMs` — clock reading when it tripped.\n *   - `half_open` carries `probes`     — probes admitted this round.\n */\nexport type CircuitState =\n  | { readonly phase: \"closed\"; readonly failures: number }\n  | { readonly phase: \"open\"; readonly openedAtMs: number }\n  | { readonly phase: \"half_open\"; readonly probes: number };\n\n/** The starting state: closed with zero recorded failures. */\nexport function initCircuit(): CircuitState {\n  return { phase: \"closed\", failures: 0 };\n}\n\n/**\n * Record a successful guarded call. PURE — returns a new state; the input is\n * never mutated.\n *\n *   - `closed`    → reset `failures` to 0 (a success breaks the consecutive run).\n *   - `half_open` → the probe succeeded; the target has recovered → `closed`.\n *   - `open`      → unchanged. A success \"shouldn't happen\" while open (no call\n *                   was admitted to produce one); a late/spurious success must\n *                   not silently un-trip the breaker. See module header note ¹.\n */\nexport function onSuccess(\n  state: CircuitState,\n  _policy: CircuitPolicy,\n): CircuitState {\n  switch (state.phase) {\n    case \"closed\":\n      // Already closed at 0 → return the same shape (cheap; the consumer's\n      // store only re-persists on a real change if it dedupes).\n      return state.failures === 0 ? state : { phase: \"closed\", failures: 0 };\n    case \"half_open\":\n      return { phase: \"closed\", failures: 0 };\n    case \"open\":\n      return state;\n  }\n}\n\n/**\n * Record a failed guarded call. PURE — returns a new state; the input is never\n * mutated. `nowMs` is the injected clock, stamped onto the `open` phase when the\n * breaker trips so `canPass` can measure the cooldown later.\n *\n *   - `closed`    → `failures + 1`; if that reaches `failureThreshold`, trip to\n *                   `open(nowMs)`. The threshold-th failure is the one that trips.\n *   - `half_open` → the probe failed; the target is still unhealthy →\n *                   `open(nowMs)`, restarting the cooldown clock so a fresh\n *                   cooldown elapses before the next probe round.\n *   - `open`      → unchanged. The breaker is already tripped; the `open` clock\n *                   is anchored at the original trip, not bumped by late\n *                   failures. See module header note ¹.\n */\nexport function onFailure(\n  state: CircuitState,\n  policy: CircuitPolicy,\n  nowMs: number,\n): CircuitState {\n  switch (state.phase) {\n    case \"closed\": {\n      const failures = state.failures + 1;\n      // `>=` not `===`: a threshold of 0 (or any already-exceeded count from a\n      // policy change) trips immediately rather than over-counting forever.\n      return failures >= policy.failureThreshold\n        ? { phase: \"open\", openedAtMs: nowMs }\n        : { phase: \"closed\", failures };\n    }\n    case \"half_open\":\n      // A failed probe re-opens and resets the cooldown clock to nowMs.\n      return { phase: \"open\", openedAtMs: nowMs };\n    case \"open\":\n      return state;\n  }\n}\n\n/**\n * Decide whether a call may pass, advancing the phase as a side effect of the\n * decision. PURE — returns `[next, allowed]`; the input is never mutated.\n * Branch on the boolean, thread the state forward regardless:\n *\n *   const [c1, allowed] = canPass(state.circuit, policy, nowMs);\n *   if (!allowed) return [{ ...state, circuit: c1 }, [fastFailCmd]];\n *   return [{ ...state, circuit: c1 }, [doGuardedCallCmd]];\n *\n *   - `closed`    → `[state, true]` — always passes; failures are recorded by\n *                   `onFailure` once the call resolves, not gated here.\n *   - `open`      → if `nowMs - openedAtMs >= cooldownMs` the cooldown has\n *                   elapsed → enter `half_open` and admit this caller as the\n *                   first probe: `[half_open(1), true]`. Otherwise still cooling\n *                   down → `[state, false]` (fast-fail, no downstream load).\n *   - `half_open` → admit while `probes < halfOpenMaxProbes`, incrementing the\n *                   count: `[half_open(probes+1), true]`. Once the cap is hit →\n *                   `[state, false]` until a probe resolves and `onSuccess` /\n *                   `onFailure` moves the phase out of `half_open`.\n *\n * Entering `half_open` lives here (not in `onSuccess` / `onFailure`) because the\n * cooldown is a time condition and only `canPass` reads `nowMs` against\n * `openedAtMs`. See the module header's probe-admission note.\n */\nexport function canPass(\n  state: CircuitState,\n  policy: CircuitPolicy,\n  nowMs: number,\n): readonly [CircuitState, boolean] {\n  switch (state.phase) {\n    case \"closed\":\n      return [state, true];\n    case \"open\": {\n      const elapsed = nowMs - state.openedAtMs;\n      // Half-open cutoff: elapsed exactly == cooldownMs admits the first probe,\n      // matching the >= edge `rate-limit` / `idempotency` use for their windows.\n      if (elapsed >= policy.cooldownMs) {\n        return [{ phase: \"half_open\", probes: 1 }, true];\n      }\n      return [state, false];\n    }\n    case \"half_open\":\n      if (state.probes < policy.halfOpenMaxProbes) {\n        return [{ phase: \"half_open\", probes: state.probes + 1 }, true];\n      }\n      return [state, false];\n  }\n}\n","/**\n * internal/resilience/rate-limit — two rate limiters as pure state + ops.\n *\n * Same shape as `../../work-queue/ops.ts`: a state type plus pure\n * transition functions. Host-agnostic by construction — no `Date.now()`, no\n * timers, no I/O. The caller injects the clock (`nowMs`) and wires the result\n * into its own reducer / interpret. This keeps the limiters inside TEA's\n * invariant 2 (transitions are pure: same inputs → same outputs, no `Date.now`)\n * so a consumer can fold them through `update` and exercise them with `replay`\n * / the pbt fold without a fake clock.\n *\n * Every op returns a NEW state value and never mutates its input (invariant 1 —\n * state is a value, not a place). The `tryConsume` / `record` ops return a\n * `[next, ok]` tuple so the caller branches on the decision while threading the\n * advanced state forward; `refill` / `remaining` are read-shaped helpers.\n *\n * Two complementary algorithms, picked by the cost the caller wants to pay:\n *\n *   - **Token bucket** — O(1) state (four numbers), smooths bursts against a\n *     steady refill rate. Allows a burst up to `capacity`, then throttles to\n *     `refillPerSec`. Cheapest; the default choice.\n *   - **Sliding window log** — O(limit) state (one timestamp per in-window\n *     hit), exact \"no more than `limit` events per `windowMs`\". Pay the memory\n *     for precise window edges when a token bucket's continuous refill would\n *     let through too many at a boundary.\n *\n * Internal to the package (`src/internal/resilience/`), not a published\n * subpath (#46); same one-shape-per-module rule as `work-queue` and `do`.\n */\n\n// ===========================================================================\n// Token bucket\n// ===========================================================================\n\n/**\n * A token bucket: `tokens` of `capacity` available now, replenished at\n * `refillPerSec` tokens per second. `lastRefillMs` is the clock reading at\n * which `tokens` was last computed — `refill` advances it. All four fields are\n * plain numbers so the whole bucket is trivially JSON-serializable into a\n * consumer's `Store<S>`.\n */\nexport interface TokenBucket {\n  readonly tokens: number;\n  readonly capacity: number;\n  readonly refillPerSec: number;\n  readonly lastRefillMs: number;\n}\n\n/**\n * Create a full bucket. Starts at `capacity` tokens (the conventional \"a fresh\n * limiter lets the first burst through\" behavior) and stamps `lastRefillMs`\n * with the caller's clock so the first `refill` measures elapsed time from\n * boot, not from epoch 0.\n */\nexport function initBucket(\n  capacity: number,\n  refillPerSec: number,\n  nowMs: number,\n): TokenBucket {\n  return {\n    tokens: capacity,\n    capacity,\n    refillPerSec,\n    lastRefillMs: nowMs,\n  };\n}\n\n/**\n * Add the tokens accrued since `lastRefillMs`, clamped to `capacity`, and\n * advance `lastRefillMs` to `nowMs`. PURE — returns a new bucket; the input is\n * untouched.\n *\n * A `nowMs` at or before `lastRefillMs` (clock not advanced, or skewed\n * backwards) adds a non-positive amount; `Math.max(0, …)` floors the elapsed\n * term so a backwards clock can never *remove* tokens. `lastRefillMs` still\n * advances to `nowMs` so the bucket tracks the latest reading the caller\n * presented — the next forward step measures from there, not from a stale\n * future timestamp.\n */\nexport function refill(bucket: TokenBucket, nowMs: number): TokenBucket {\n  const elapsedSec = Math.max(0, nowMs - bucket.lastRefillMs) / 1000;\n  const replenished = bucket.tokens + elapsedSec * bucket.refillPerSec;\n  return {\n    ...bucket,\n    tokens: Math.min(bucket.capacity, replenished),\n    lastRefillMs: nowMs,\n  };\n}\n\n/**\n * Refill against `nowMs`, then attempt to take `n` tokens (default 1).\n *\n * On success returns `[next, true]` with `n` subtracted; on failure returns\n * `[refilled, false]` — the refilled bucket (so the caller keeps the advanced\n * clock + accrued tokens) with no tokens spent. Branch on the boolean, thread\n * the bucket forward regardless:\n *\n *   const [b1, ok] = tryConsume(bucket, nowMs);\n *   return ok ? [{ ...state, bucket: b1 }, [doWork]] : [{ ...state, bucket: b1 }, []];\n *\n * PURE — input bucket is never mutated.\n */\nexport function tryConsume(\n  bucket: TokenBucket,\n  nowMs: number,\n  n = 1,\n): readonly [TokenBucket, boolean] {\n  const refilled = refill(bucket, nowMs);\n  if (refilled.tokens >= n) {\n    return [{ ...refilled, tokens: refilled.tokens - n }, true];\n  }\n  return [refilled, false];\n}\n\n// ===========================================================================\n// Sliding window log\n// ===========================================================================\n\n/**\n * A sliding-window log: the timestamps of every hit still inside the trailing\n * `windowMs`, capped at `limit` events per window. `hits` is `readonly` and\n * kept oldest-first (pruning slices the stale prefix off the front, recording\n * appends to the back), so the array is its own sorted index. Exact at the\n * window edge — unlike a token bucket's continuous refill, a hit leaves the\n * count the instant it ages past `windowMs`.\n */\nexport interface SlidingWindow {\n  readonly hits: readonly number[];\n  readonly windowMs: number;\n  readonly limit: number;\n}\n\n/** Create an empty window. No hits recorded yet. */\nexport function initWindow(windowMs: number, limit: number): SlidingWindow {\n  return { hits: [], windowMs, limit };\n}\n\n/**\n * The window-edge rule, in one place: keep only the hits still live at `nowMs`.\n * The cutoff is half-open — a hit exactly `windowMs` old is dropped (`> cutoff`,\n * not `>=`), so a hit recorded at `t` no longer counts at `t + windowMs` and the\n * window's capacity fully recovers `windowMs` after the last hit. `record` (the\n * writer) and `remaining` (the read helper) both prune through here so a change\n * to the edge semantics can't leave the reader disagreeing with the writer.\n */\nfunction prune(window: SlidingWindow, nowMs: number): readonly number[] {\n  const cutoff = nowMs - window.windowMs;\n  return window.hits.filter((t) => t > cutoff);\n}\n\n/**\n * Prune hits older than `nowMs - windowMs`, then record `nowMs` if there is\n * room. Returns `[next, true]` with the hit appended when `hits.length < limit`\n * after pruning, else `[pruned, false]` — the pruned window (capacity recovers\n * as old hits age out) with nothing appended.\n *\n * The cutoff is half-open (see {@link prune}): a hit exactly `windowMs` old is\n * pruned, so a hit recorded at `t` no longer counts at `t + windowMs`. That\n * makes the window's capacity fully recover `windowMs` after the last hit, the\n * behavior tests pin.\n *\n * PURE — input window is never mutated; `hits` is rebuilt by `filter` +\n * spread.\n */\nexport function record(\n  window: SlidingWindow,\n  nowMs: number,\n): readonly [SlidingWindow, boolean] {\n  const pruned = prune(window, nowMs);\n  if (pruned.length < window.limit) {\n    return [{ ...window, hits: [...pruned, nowMs] }, true];\n  }\n  return [{ ...window, hits: pruned }, false];\n}\n\n/**\n * How many more hits `record` would accept at `nowMs` without blocking —\n * `limit` minus the live (post-prune) hit count, floored at 0. Read-only: it\n * prunes a local copy to answer but returns no new window. Use it to render a\n * \"N requests remaining\" affordance without committing a hit.\n */\nexport function remaining(window: SlidingWindow, nowMs: number): number {\n  const live = prune(window, nowMs).length;\n  return Math.max(0, window.limit - live);\n}\n","/**\n * @packageDocumentation\n *\n * Internal to the package (`src/internal/resilience/`, #46). The published\n * `./resilient-call` door is closed; the consumer-facing shape is the\n * higher-order `withResilience(base, config)` wrapper in `../with-resilience`\n * (TEA-idiomatic: it wraps any existing machine instead of forcing a bespoke\n * embedded slice), and this module is its implementation. The APIs are NOT\n * drop-in; migration map, for the in-tree embedded-slice consumers:\n *\n *   - `createResilientCall(config, rng)` + hand-wiring `init` / the verbs /\n *     `subs` / `handlers` into your machine → `withResilience(base, { target,\n *     ...bricks }, rng)`. Nothing is wired by hand anymore: the wrapper\n *     intercepts the `target` base Cmd and routes it through the gate.\n *   - `ResilientConfig` bricks (`retry` / `circuit` / `rateLimit` / `cache` /\n *     `deadline`) → unchanged; `ResilienceConfig` extends the same knob and\n *     adds `target` (required), `keyOf?` (per-call key — was `attempt`'s `key`\n *     argument), and `at?` (time-as-data reader — REQUIRED with any\n *     time-sensitive brick; `withResilience` throws at construction without it).\n *   - The slice at your chosen Model field + `liftResilience` → the wrapper\n *     owns `model.$resilience`; there is nothing to lift.\n *   - Verbs `attempt` / `succeed` / `fail` / `onTimer` → internal to the\n *     wrapper; results route as `$resilience:ok` / `$resilience:err` /\n *     `$resilience:timer` Msgs through the merged `update` (the old\n *     `resilient_run` / `resilient_ok` / `resilient_err` vocabulary is renamed\n *     into the `$resilience:` namespace).\n *   - `settleFailed` → NO equivalent. It exists for embedded-slice consumers\n *     (`authed-call`, `paginated-walk`) that settle a call without touching the\n *     breaker; the wrapper exposes no caller-facing settle verb.\n *   - `handlers(ports)` / `subs(state)` / the `subscribeDeadline` re-export →\n *     handled by the wrapper; run the returned machine like any other.\n *\n * The in-tree modules that embed the slice (`with-resilience` itself, `agent`,\n * `llm-call`, `authed-call`, `reconciler`, `paginated-walk`) import this module\n * directly — that is its role.\n *\n * internal/resilience/resilient-call — the ROOT composition: a single resilience knob\n * that bundles cache → circuit-breaker → rate-limit → exponential-backoff retry\n * (with a deadline-driven retry timer) around any fallible `(input) => Promise`\n * port.\n *\n * This is `examples/resilient-fetch.ts`'s hand-wired `attempt()` generalized:\n *\n *   - It is **keyed**. The example tracked one URL at a time; this tracks N\n *     concurrent logical calls, each under a string `key`. The cache, the\n *     waiting-retry bookkeeping, and the retry timers are all per-key, while the\n *     circuit breaker and token bucket are shared (one downstream target, one\n *     breaker / one bucket — the example's implicit single-target assumption\n *     made explicit).\n *   - It is **config-driven**, not hand-wired. You hand `createResilientCall`\n *     a `ResilientConfig` and get back the uniform knob contract every L2\n *     composition exposes: `init()`, the four verbs (`attempt` / `succeed` /\n *     `fail` / `onTimer`), `subs(state)`, and `handlers(ports)`.\n *   - Every brick is **optional**. Omit `cache` and the cache gate disappears\n *     (`get` is never consulted); omit `circuit` and every call passes the\n *     breaker; omit `rateLimit` and the bucket never throttles; omit `retry`\n *     and a failure is terminal (no backoff, no timer); omit `deadline` and no\n *     overall time budget is armed. \"Omit a brick → omit its gate\" is the\n *     whole config story — there are no other modes.\n *\n * Four later compositions (`llm-call`, `paginated-walk`, `authed-call`,\n * `reconciler`) inherit THIS slice + verb shape, so the contract here is\n * load-bearing: the slice is a flat record of brick states, every verb returns\n * `readonly [State, Cmd[]]`, time is always an `at` / `now` parameter, and the\n * RNG used for jitter is injected on the config (never read inside a verb).\n *\n * ## The two non-negotiables (canon)\n *\n *   - **Durable** — the slice is a plain-data Model field (brick states are all\n *     JSON-serializable), so it survives DO eviction / reload.\n *   - **Replayable** — every transition is a verb returning new state + Cmds;\n *     `replay` reconstructs it exactly. Nothing here closes over time or RNG.\n *\n * ## Where the clock / RNG live\n *\n * Inside the verbs: nowhere. Time arrives as `at` on `attempt` / `onTimer` and\n * is carried on the result / timer Msgs the consumer dispatches. Jitter RNG is\n * injected once at `createResilientCall(config, rng)` and threaded into\n * `nextDelayMs` at the verb boundary — deterministic in tests, `Math.random`\n * by default. The ONLY clock read is `Date.now()` inside the `handlers` port\n * (the effect boundary), exactly as `resilient-fetch.ts` stamps its result Msgs.\n *\n * That same `at` is what makes a DURATION-bounded retry budget reachable here:\n * `recordFailure` / `shouldRetry` are fed the failure's observation instant,\n * so `config.retry` accepts any `AnyRetryPolicy` — a count, a wall-clock outage\n * budget (`maxElapsedMs`), or explicit `unbounded: true` — with no new argument\n * on any verb and no clock read inside one.\n *\n * ## Typical wiring\n *\n *   const rc = createResilientCall<string, Result>({\n *     cache: { ttlMs: 60_000 },\n *     circuit: { threshold: 5, cooldownMs: 30_000 },\n *     rateLimit: { capacity: 10, refillPerSec: 5 },\n *     retry: defaultRetryPolicy,\n *     deadline: { ms: 5_000 },\n *   });\n *\n *   // in the machine:\n *   init: () => [{ resilience: rc.init() }, []],\n *   update: {\n *     fetch:   (s, m) => lift(s, rc.attempt(s.resilience, m.key, m.input, m.at)),\n *     call_ok: (s, m) => lift(s, rc.succeed(s.resilience, m.key, m)),\n *     call_err:(s, m) => lift(s, rc.fail(s.resilience, m.key, m)),\n *     retry_due:(s, m) => lift(s, rc.onTimer(s.resilience, m)),\n *   },\n *   subscriptions: (s) => rc.subs(s.resilience),\n *   subscribe: { deadline: subscribeDeadline },\n *   interpret: rc.handlers({ run: ctx.call }),\n */\n\nimport { z } from \"zod\";\nimport { Cmd, type CmdOf, type NoCtx, tryInterpret } from \"../../../index\";\nimport { MsgType } from \"../../../protocol\";\nimport { without } from \"../../../pure/core\";\nimport {\n  type AnyRetryPolicy,\n  asRng,\n  initRetry,\n  nextDelayMs,\n  type RetryState,\n  recordFailure,\n  shouldRetry,\n} from \"../../../retry-backoff\";\nimport {\n  get as cacheGet,\n  set as cacheSet,\n  initCache,\n  type TtlCache,\n} from \"../cache\";\nimport {\n  type CircuitState,\n  canPass,\n  initCircuit,\n  onFailure,\n  onSuccess,\n} from \"../circuit-breaker\";\nimport {\n  type DeadlineExceeded,\n  type DeadlineSub,\n  deadlineSub,\n  subscribeDeadline,\n} from \"../deadline\";\nimport { initBucket, type TokenBucket, tryConsume } from \"../rate-limit\";\n\n// ===========================================================================\n// Config — the knob. Every brick optional; omit a brick → omit its gate.\n// ===========================================================================\n\n/** Circuit-breaker knob — only the two numbers a consumer ever tunes. */\nexport interface CircuitConfig {\n  /** Consecutive failures that trip the breaker open. */\n  readonly threshold: number;\n  /** How long the breaker stays open before admitting a probe, in ms. */\n  readonly cooldownMs: number;\n  /**\n   * Probes admitted in `half_open` before fast-failing the rest of the round.\n   * Defaults to 1 (a single probe decides recovery) — matches the circuit-\n   * breaker module's `defaultCircuitPolicy`.\n   */\n  readonly halfOpenMaxProbes?: number;\n}\n\n/** Token-bucket rate-limit knob. */\nexport interface RateLimitConfig {\n  /** Burst size — the bucket starts full at `capacity`. */\n  readonly capacity: number;\n  /** Steady-state refill rate, tokens per second. */\n  readonly refillPerSec: number;\n}\n\n/** Per-entry TTL cache knob. */\nexport interface CacheConfig {\n  /** How long a cached success stays fresh, in ms. */\n  readonly ttlMs: number;\n}\n\n/**\n * Overall deadline knob — a budget of IN-PROCESS time per in-flight call.\n *\n * The budget is charged in elapsed time this process actually observed, not by\n * a position on the host's wall clock. Time in which no process exists — a DO\n * eviction, a crash between attempts, a redeploy — is NOT charged: `resume`\n * re-anchors every live call's charging clock, so downtime lands outside every\n * segment. A timeout therefore means \"the tool took too long\", never \"the host\n * was away too long\" (#144).\n */\nexport interface DeadlineConfig {\n  /** Budget of in-process time from the moment a call starts, in ms. */\n  readonly ms: number;\n}\n\n/**\n * The resilience knob. EVERY field is optional: omit a brick and its gate is\n * skipped entirely (the slice still carries a default brick state so the shape\n * stays uniform across configs, but the gate is never consulted). An empty\n * config `{}` is a valid pass-through — a bare effect with no resilience at all.\n */\nexport interface ResilientConfig {\n  /**\n   * The backoff brick. Omit and a failure is terminal (no backoff, no timer).\n   *\n   * Any bound the `../retry-backoff` union admits: a count (`RetryPolicy`), a\n   * wall-clock outage budget (`DurationRetryPolicy`), or explicit\n   * `unbounded: true`. A duration bound needs no extra wiring: every path that\n   * records a failure already holds the instant it was observed as DATA —\n   * `fail`'s `msg.at` (stamped at the interpret boundary) and `gate`'s `at`\n   * (the caller's `attempt` / the retry timer's `atMs`) — so the streak clock\n   * is fed from a Msg, never from a `Date.now()` inside a verb (invariant 2).\n   */\n  readonly retry?: AnyRetryPolicy;\n  readonly circuit?: CircuitConfig;\n  readonly rateLimit?: RateLimitConfig;\n  readonly cache?: CacheConfig;\n  readonly deadline?: DeadlineConfig;\n}\n\n// ===========================================================================\n// Slice — the Model field this knob owns. A flat record of brick states.\n// ===========================================================================\n\n/**\n * What is left of one call's deadline budget, and where the currently open\n * charging segment starts. Plain data, so it persists with the rest of the slice\n * — but the DURABLE fact is `remainingMs`, a duration, never an instant.\n *\n * The accounting has one rule, applied at every transition that carries a clock\n * (`attempt`'s `at`, a settle Msg's `at`, a timer's `atMs`): charge the segment\n * that just closed and open a new one at the same instant —\n * `remainingMs -= at - chargingSinceMs; chargingSinceMs = at`. See {@link charge}.\n *\n * `chargingSinceMs` is an IN-PROCESS anchor, not a persisted deadline. It is\n * meaningful only while the process that wrote it is alive, and `resume` re-bases\n * it on every live call before anything reads it after a reload — which is what\n * keeps downtime out of the budget. Nothing derives a timeout from it across a\n * resume; the only durable answer to \"how much budget is left\" is `remainingMs`.\n *\n * `remainingMs` is `0` when the `deadline` brick is absent, which is also the\n * \"no cap armed\" reading `subs` uses — a call with a real budget always has\n * `remainingMs > 0`, because `gate` settles a call whose budget reached zero\n * rather than letting it enter `running`.\n */\nexport interface CallBudget {\n  /** In-process ms left when the open segment started. `0` = no deadline brick. */\n  readonly remainingMs: number;\n  /** The instant the open segment started, on the clock of the process that opened it. */\n  readonly chargingSinceMs: number;\n}\n\n/**\n * Per-key call phase. `key` indexes a logical call; several can be in flight at\n * once (the generalization of the example's single `url`). Discriminated on\n * `phase` so each phase carries only its own data (pattern 11):\n *\n *   - `idle`          — never attempted, or fully settled and forgotten.\n *   - `running`       — the effect Cmd is out; awaiting `succeed` / `fail`.\n *                       Carries the deadline budget ({@link CallBudget}) and the\n *                       last `input` so a retry can re-issue it.\n *   - `waiting_retry` — a transient failure backed off; the retry timer is armed\n *                       for `retryAtMs`. Carries `input` for the re-attempt, and\n *                       the same budget — backoff is in-process time, so it is\n *                       charged like an attempt.\n *   - `circuit_open`  — the breaker fast-failed this attempt. Terminal for this\n *                       call until the consumer re-attempts after cooldown.\n *   - `succeeded`     — settled OK. `result` is the value the port produced.\n *   - `failed`        — settled Err (out of retries, or no retry brick). `error`\n *                       carries the last failure.\n */\nexport type CallPhase<I, R> =\n  | { readonly phase: \"idle\" }\n  | {\n      readonly phase: \"running\";\n      readonly input: I;\n      readonly budget: CallBudget;\n    }\n  | {\n      readonly phase: \"waiting_retry\";\n      readonly input: I;\n      readonly retryAtMs: number;\n      readonly budget: CallBudget;\n    }\n  | { readonly phase: \"circuit_open\" }\n  | { readonly phase: \"succeeded\"; readonly result: R }\n  | { readonly phase: \"failed\"; readonly error: unknown };\n\n/**\n * The slice. `circuit` / `bucket` are SHARED across keys (one downstream target\n * → one breaker, one bucket). `retry` and `cache` are PER KEY (each logical call\n * has its own backoff count + cached result), as is the per-call `CallPhase`.\n * Every field is plain data → the whole slice serializes into a `Store<S>`.\n *\n * `retry` / `cache` keep a default brick value even when the corresponding\n * config brick is omitted, so the slice shape is identical regardless of which\n * bricks the consumer enabled — the verbs simply never consult the unused brick.\n */\nexport interface ResilientState<I, R> {\n  readonly circuit: CircuitState;\n  readonly bucket: TokenBucket;\n  /**\n   * Per-key backoff counter. Entries minted by `backoff` are `TimedRetryState`s\n   * (they carry the streak's `firstFailureAtMs`, since every failure path holds\n   * the observation instant); the field is typed at the `RetryState` supertype\n   * because a key that has never failed has no streak, and a slice persisted\n   * before the origin existed rehydrates without one. Still plain data.\n   */\n  readonly retry: Readonly<Record<string, RetryState>>;\n  readonly cache: TtlCache<R>;\n  readonly calls: Readonly<Record<string, CallPhase<I, R>>>;\n}\n\n// ===========================================================================\n// Cmds + Msgs the knob speaks. Generic over the port input `I`.\n// ===========================================================================\n\n/**\n * The one effect this knob emits: \"run the port for `key` with `input`\". The\n * consumer's `handlers(ports)` interprets it; it carries no closure — `input`\n * is plain data (invariant 3).\n */\nexport function runCmdDef<I, R>() {\n  return Cmd.define(MsgType.ResilientRun, {\n    input: z.custom<{ readonly key: string; readonly input: I }>(),\n    ok: z.custom<R>(),\n    err: [\"port_rejected\", \"deadline_exceeded\"],\n  });\n}\nexport type RunCmdDef<I, R> = ReturnType<typeof runCmdDef<I, R>>;\nexport type RunCmd<I> = CmdOf<RunCmdDef<I, unknown>>;\n\n/** Settle Msgs the `handlers` port dispatches back. `at` is stamped at the boundary. */\nexport type SucceedMsg<R> = {\n  readonly type: typeof MsgType.ResilientOk;\n  readonly key: string;\n  readonly result: R;\n  readonly at: number;\n};\nexport type FailMsg = {\n  readonly type: typeof MsgType.ResilientErr;\n  readonly key: string;\n  readonly error: unknown;\n  readonly at: number;\n};\n\n/** The retry / deadline timer Msg — `DeadlineExceeded`, keyed by the call `key`. */\nexport type ResilientTimerMsg = DeadlineExceeded;\n\n/**\n * The plain-data error a deadline-failed call settles with. A `{_tag, ...}`\n * sentinel — NEVER a `new Error(...)` — so the slice stays JSON-serializable\n * (Error objects round-trip to `{}` and carry a stack trace, both of which break\n * the slice's durability invariant). `id` / `atMs` echo the timer that fired so\n * a consumer can attribute the failure to its deadline.\n */\nexport type DeadlineExceededError = {\n  readonly _tag: \"deadline_exceeded\";\n  readonly id: string;\n  readonly atMs: number;\n};\n\n/** Ports the consumer supplies to `handlers`. */\nexport interface ResilientPorts<I, R> {\n  /** The fallible work this knob wraps. Throws on failure → routed to `fail`. */\n  readonly run: (input: I, key: string) => Promise<R>;\n}\n\n// ===========================================================================\n// Internal brick-policy derivation — config → the L1 policy shapes.\n// ===========================================================================\n\n// A circuit policy is only built when the brick is configured; absence is\n// represented as `null` so the gate can short-circuit to \"always pass\".\nfunction circuitPolicy(config: ResilientConfig) {\n  if (config.circuit === undefined) return null;\n  return {\n    failureThreshold: config.circuit.threshold,\n    cooldownMs: config.circuit.cooldownMs,\n    halfOpenMaxProbes: config.circuit.halfOpenMaxProbes ?? 1,\n  };\n}\n\n/**\n * Close the open charging segment at `at` and open the next one there: the ONE\n * place a {@link CallBudget} is debited. Every caller holds `at` as data (a\n * verb's argument, a Msg's stamp), so the budget advances without any verb\n * reading a clock. PURE.\n *\n * A budget with no deadline brick (`remainingMs` 0) is left alone — there is\n * nothing to spend, and debiting it would push it negative and read as \"spent\".\n * `at` before the anchor cannot happen on a monotonic feed, but a clamped charge\n * keeps a skewed one from CREDITING budget back.\n */\nfunction charge(budget: CallBudget, at: number): CallBudget {\n  if (budget.remainingMs <= 0) return { ...budget, chargingSinceMs: at };\n  const elapsed = Math.max(0, at - budget.chargingSinceMs);\n  return { remainingMs: budget.remainingMs - elapsed, chargingSinceMs: at };\n}\n\n// Sub-id families. Each call's retry timer is a deadline keyed by `key`, so a\n// machine running many concurrent calls reconciles each independently.\nfunction retryTimerId(key: string): string {\n  return `resilient:retry:${key}`;\n}\nfunction deadlineTimerId(key: string): string {\n  return `resilient:deadline:${key}`;\n}\n\n// ===========================================================================\n// The knob factory.\n// ===========================================================================\n\n/**\n * Build a resilient-call knob from `config`. `rng` is injected for retry\n * jitter — pass a fixed `() => 0.5` in tests to pin backoff; defaults to\n * `Math.random` (read at the verb boundary, never inside a brick op). It is\n * curried onto the factory rather than threaded through every verb so callers\n * spell the determinism choice once.\n *\n * Returns the uniform L2 knob contract. `I` is the port input type, `R` the\n * port result type. Consumers outside the package reach this through\n * `withResilience` (`../with-resilience`) — see the migration map at the top\n * of this module.\n */\nexport function createResilientCall<I, R>(\n  config: ResilientConfig,\n  rng: () => number = Math.random,\n) {\n  const cPolicy = circuitPolicy(config);\n  // Re-affirm the `[0, 1)` contract at the seam where the injected generator\n  // feeds 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 it's branded for `nextDelayMs`.\n  const rngBranded = asRng(rng);\n  const runCmd = runCmdDef<I, R>();\n\n  /** The starting slice. Bricks not in `config` still get a default value. */\n  function init(): ResilientState<I, R> {\n    return {\n      circuit: initCircuit(),\n      // The bucket carries a default value even without the rateLimit brick so\n      // the slice shape is uniform, but the rate-limit GATE is skipped entirely\n      // when the brick is absent (see `gate`) — the bucket is simply never\n      // consulted. A `0/0` placeholder bucket would be touched by `tryConsume`;\n      // a `1-cap` default is harmless because the gate never calls it.\n      bucket: config.rateLimit\n        ? initBucket(\n            config.rateLimit.capacity,\n            config.rateLimit.refillPerSec,\n            0,\n          )\n        : initBucket(1, 1, 0),\n      retry: {},\n      cache: initCache<R>(),\n      calls: {},\n    };\n  }\n\n  /** Read this key's retry state, defaulting to a fresh one. */\n  function retryOf(s: ResilientState<I, R>, key: string): RetryState {\n    return s.retry[key] ?? initRetry();\n  }\n\n  /** A fresh full budget for a call starting at `at` (`remainingMs` 0 = no cap). */\n  function freshBudget(at: number): CallBudget {\n    return {\n      remainingMs: config.deadline ? config.deadline.ms : 0,\n      chargingSinceMs: at,\n    };\n  }\n\n  /**\n   * The budget a call already live under `key` carries forward, charged up to\n   * `at`; a fresh full budget when the key has no live call. This is what makes a\n   * re-attempt share ONE budget with the attempts before it rather than buying a\n   * new one — the in-process invariant the deadline brick has always had.\n   */\n  function budgetFor(\n    s: ResilientState<I, R>,\n    key: string,\n    at: number,\n  ): CallBudget {\n    const call = s.calls[key];\n    if (call?.phase === \"running\" || call?.phase === \"waiting_retry\") {\n      return charge(call.budget, at);\n    }\n    return freshBudget(at);\n  }\n\n  /**\n   * The shared decision: budget → cache → rate-limit → circuit gate, then either\n   * emit the effect or schedule a retry. `budget` is threaded so a re-attempt\n   * (from `onTimer`) keeps the ORIGINAL overall budget rather than restarting it.\n   * PURE — `at` is the only clock; `rng` is the injected jitter source.\n   *\n   * ## Why the budget is checked BEFORE the effect is emitted\n   *\n   * The check is step 0 and it settles rather than dispatches. A call whose\n   * budget is spent must not reach the port at all: the port is a real side\n   * effect, and re-issuing an attempt only to settle `deadline_exceeded` when it\n   * returns spends that effect for an answer nobody reads. This is exactly the\n   * resume path's shape — a process that comes back to a spent budget settles\n   * here, with zero further port calls (#144).\n   *\n   * Used by both `attempt` (fresh call) and `onTimer` (retry timer fired) so\n   * the gate logic lives in exactly one place — the example's shared `attempt`\n   * helper, lifted to a keyed knob.\n   *\n   * ## Why rate-limit is gated BEFORE the circuit probe\n   *\n   * The circuit-breaker's `canPass` is not a passive read: in `half_open` it\n   * *consumes* a probe slot (advancing `probes`), and the consumed slot is only\n   * released when a probe RESOLVES via `onSuccess` / `onFailure`. So a probe\n   * slot may only be taken when this attempt is actually going to reach the\n   * backend (i.e. emit the `resilient_run` Cmd). The rate-limit gate can reject\n   * an attempt and return a backoff WITHOUT any Cmd — no backend call, so no\n   * settle Msg ever comes back. If the circuit probe were consumed first, that\n   * rate-limited attempt would burn the half-open probe budget on a call that\n   * never happened, wedging the breaker `half_open` at its probe cap forever\n   * (nothing moves it out of `half_open` but a resolved probe). Running the\n   * rate-limit gate first means the circuit probe is consumed ONLY on the path\n   * that emits the effect.\n   */\n  function gate(\n    s: ResilientState<I, R>,\n    key: string,\n    input: I,\n    at: number,\n    budget: CallBudget,\n  ): readonly [ResilientState<I, R>, readonly RunCmd<I>[]] {\n    // 0) Budget gate. Skipped without the deadline brick (`remainingMs` stays 0\n    // and never moves). A spent budget settles here — before the cache read, the\n    // token spend and the circuit probe, none of which a dead call should touch.\n    if (config.deadline !== undefined && budget.remainingMs <= 0) {\n      return [\n        setCall(s, key, {\n          phase: \"failed\",\n          error: {\n            _tag: \"deadline_exceeded\",\n            id: deadlineTimerId(key),\n            atMs: at,\n          } satisfies DeadlineExceededError,\n        }),\n        [],\n      ];\n    }\n\n    // 1) Serve from cache if fresh — no effect at all. Skipped when no cache brick.\n    if (config.cache !== undefined) {\n      const cached = cacheGet(s.cache, key, at);\n      if (cached !== undefined) {\n        return [setCall(s, key, { phase: \"succeeded\", result: cached }), []];\n      }\n    }\n\n    // 2) Rate-limit gate FIRST — it may reject with no Cmd, so it must run\n    // before any circuit probe is consumed (see header note). Skipped entirely\n    // when no rateLimit brick — the bucket is never consulted, so the default\n    // placeholder bucket stays untouched.\n    let bucket = s.bucket;\n    if (config.rateLimit !== undefined) {\n      const [next, hasToken] = tryConsume(bucket, at);\n      bucket = next;\n      if (!hasToken) {\n        // Rate-limited: treat as a transient failure and back off via retry.\n        // The circuit is untouched — no probe is spent on a call that never ran.\n        return backoff(\n          { ...s, bucket },\n          key,\n          input,\n          \"rate_limited\",\n          at,\n          budget,\n        );\n      }\n    }\n\n    // 3) Circuit-breaker gate. `null` policy → no breaker → always pass. Reached\n    // only once a token is secured, so a half-open probe is consumed exclusively\n    // on the path that emits the effect below.\n    let circuit = s.circuit;\n    if (cPolicy !== null) {\n      const [next, ok] = canPass(circuit, cPolicy, at);\n      circuit = next;\n      if (!ok) {\n        return [\n          { ...setCall(s, key, { phase: \"circuit_open\" }), bucket, circuit },\n          [],\n        ];\n      }\n    }\n\n    // 4) All gates passed — emit the effect as data.\n    return [\n      {\n        ...setCall(s, key, { phase: \"running\", input, budget }),\n        circuit,\n        bucket,\n      },\n      [runCmd({ key, input })],\n    ];\n  }\n\n  /**\n   * Back off after a transient failure: record it, and if `retry` permits\n   * another attempt, enter `waiting_retry` with the retry timer armed; else\n   * settle `failed`. When no `retry` brick is configured the call fails on the\n   * first failure (no backoff, no timer). PURE.\n   *\n   * `at` is both the backoff anchor AND the streak clock: it is passed to\n   * `recordFailure` (which starts `firstFailureAtMs` on the streak's first\n   * failure and preserves it on every later one) and to `shouldRetry`, so a\n   * `DurationRetryPolicy` on `config.retry` is honoured with no extra wiring.\n   * A success drops `retry[key]` entirely, which drops the origin with it —\n   * only an unbroken run of failures grows toward a duration budget.\n   */\n  function backoff(\n    s: ResilientState<I, R>,\n    key: string,\n    input: I,\n    error: unknown,\n    at: number,\n    budget: CallBudget,\n  ): readonly [ResilientState<I, R>, readonly RunCmd<I>[]] {\n    if (config.retry === undefined) {\n      return [setCall(s, key, { phase: \"failed\", error }), []];\n    }\n    const retry = recordFailure(retryOf(s, key), error, at);\n    const withRetry = { ...s, retry: { ...s.retry, [key]: retry } };\n    if (!shouldRetry(retry, config.retry, at)) {\n      return [setCall(withRetry, key, { phase: \"failed\", error }), []];\n    }\n    const retryAtMs = at + nextDelayMs(retry, config.retry, rngBranded);\n    return [\n      setCall(withRetry, key, {\n        phase: \"waiting_retry\",\n        input,\n        retryAtMs,\n        budget,\n      }),\n      [],\n    ];\n  }\n\n  // Set the phase for one key, leaving every other field untouched.\n  function setCall(\n    s: ResilientState<I, R>,\n    key: string,\n    phase: CallPhase<I, R>,\n  ): ResilientState<I, R> {\n    return { ...s, calls: { ...s.calls, [key]: phase } };\n  }\n\n  // === Verb: attempt =======================================================\n\n  /**\n   * Start (or restart) the call for `key` with `input` at time `at`. Runs the\n   * cache → circuit → rate-limit gate and either emits the `resilient_run`\n   * effect, schedules a retry, fast-fails (circuit open), or serves the cache.\n   * PURE.\n   *\n   * A key already live keeps the budget it is under (charged up to `at`) rather\n   * than being handed a fresh one, so re-issuing an in-flight call — the boot\n   * path's move — cannot silently extend its deadline. Only a key with no live\n   * call starts a full budget.\n   */\n  function attempt(\n    s: ResilientState<I, R>,\n    key: string,\n    input: I,\n    at: number,\n  ): readonly [ResilientState<I, R>, readonly RunCmd<I>[]] {\n    return gate(s, key, input, at, budgetFor(s, key, at));\n  }\n\n  // === Verb: resume ========================================================\n\n  /**\n   * Re-anchor every live call's charging clock to `at`: the verb a host calls\n   * once on the boot path, before any Sub is armed or any attempt re-issued.\n   *\n   * This is what keeps DOWNTIME out of the budget. `chargingSinceMs` is an\n   * instant on the clock of the process that wrote it; after an eviction, a crash\n   * or a redeploy, the gap between it and now is time in which no attempt ran and\n   * no port was called, so charging it would time a call out on the host's\n   * absence rather than on the tool's slowness. `remainingMs` — the durable half\n   * of the budget — is left exactly as the last live transition set it. PURE.\n   */\n  function resume(s: ResilientState<I, R>, at: number): ResilientState<I, R> {\n    const calls: Record<string, CallPhase<I, R>> = { ...s.calls };\n    for (const [key, call] of Object.entries(calls)) {\n      if (call.phase !== \"running\" && call.phase !== \"waiting_retry\") continue;\n      calls[key] = {\n        ...call,\n        budget: { ...call.budget, chargingSinceMs: at },\n      };\n    }\n    return { ...s, calls };\n  }\n\n  // === Verb: succeed =======================================================\n\n  /**\n   * Record a success for `key`: close the breaker, fill the cache (if a cache\n   * brick exists), reset this key's retry count, and settle `succeeded`. PURE —\n   * `msg.at` is the cache write clock.\n   */\n  function succeed(\n    s: ResilientState<I, R>,\n    key: string,\n    msg: SucceedMsg<R>,\n  ): readonly [ResilientState<I, R>, readonly RunCmd<I>[]] {\n    const circuit =\n      cPolicy !== null ? onSuccess(s.circuit, cPolicy) : s.circuit;\n    const cache =\n      config.cache !== undefined\n        ? cacheSet(s.cache, key, msg.result, msg.at, config.cache.ttlMs)\n        : s.cache;\n    // Drop this key's retry counter — a success ends the retry run.\n    const retry = without(s.retry, key);\n    return [\n      {\n        ...setCall(s, key, { phase: \"succeeded\", result: msg.result }),\n        circuit,\n        cache,\n        retry,\n      },\n      [],\n    ];\n  }\n\n  // === Verb: fail ==========================================================\n\n  /**\n   * Record a failure for `key`: trip the breaker (it may open), then back off —\n   * schedule a retry if `retry` permits, else settle `failed`. PURE — `msg.at`\n   * stamps the breaker trip + the retry delay base. Re-issues from the call's\n   * remembered `input` and carries the original budget forward, charged up to\n   * `msg.at` — the attempt that just failed spent in-process time, and a retry\n   * ladder shares ONE budget across its attempts rather than getting a fresh one\n   * per attempt.\n   */\n  function fail(\n    s: ResilientState<I, R>,\n    key: string,\n    msg: FailMsg,\n  ): readonly [ResilientState<I, R>, readonly RunCmd<I>[]] {\n    const circuit =\n      cPolicy !== null ? onFailure(s.circuit, cPolicy, msg.at) : s.circuit;\n    const withCircuit = { ...s, circuit };\n    const call = s.calls[key];\n    const input = call?.phase === \"running\" ? call.input : undefined;\n    const budget = budgetFor(s, key, msg.at);\n    // No remembered input (e.g. a stray fail for a key not running) → just\n    // settle failed after tripping the breaker; nothing to re-issue.\n    if (input === undefined) {\n      return [\n        setCall(withCircuit, key, { phase: \"failed\", error: msg.error }),\n        [],\n      ];\n    }\n    return backoff(withCircuit, key, input, msg.error, msg.at, budget);\n  }\n\n  // === Verb: settleFailed ==================================================\n\n  /**\n   * Settle `key` to terminal `failed` with `error` WITHOUT touching the circuit\n   * breaker or this key's retry counter. PURE.\n   *\n   * This is the verb for a failure that is NOT a downstream-health signal: the\n   * call must end now, but the breaker must not trip and the backoff run must\n   * not advance. `fail` is the opposite — it records the failure against the\n   * breaker (it may open) and feeds the retry policy (it may back off). Use\n   * `settleFailed` when the *reason* the call cannot proceed has nothing to do\n   * with downstream health:\n   *\n   *   - `authed-call` settles a 401 it cannot fix (e.g. the refresh budget is\n   *     spent): a bad token is the caller's problem, not the backend's —\n   *     tripping the breaker on it would punish a healthy target, and backing\n   *     off would just retry a request that will 401 again.\n   *   - `paginated-walk` settles a terminal walk error (e.g. a malformed page\n   *     the consumer rejects) that should stop the walk without poisoning the\n   *     shared breaker the next page fetch passes through.\n   *\n   * Because it leaves `circuit` and `retry[key]` untouched, the breaker keeps\n   * its health view of the actual backend and a later `attempt` for this key\n   * starts a fresh retry run. Both sibling knobs previously hand-rolled this by\n   * splicing `calls` directly; this verb gives them one named, tested entry\n   * point so the slice's settle invariants live in exactly one place.\n   */\n  function settleFailed(\n    s: ResilientState<I, R>,\n    key: string,\n    error: unknown,\n  ): readonly [ResilientState<I, R>, readonly RunCmd<I>[]] {\n    return [setCall(s, key, { phase: \"failed\", error }), []];\n  }\n\n  // === Verb: onTimer =======================================================\n\n  /**\n   * A timer fired for some key. Two kinds, disambiguated by the Sub id:\n   *\n   *   - retry timer    → re-run the gate for that key's remembered input,\n   *                      re-checking the circuit + bucket at THIS time.\n   *   - deadline timer → the overall budget elapsed → settle `failed` with a\n   *                      deadline error, no matter the current phase.\n   *\n   * A timer for a key no longer `waiting_retry` (retry) / no longer in flight\n   * (deadline) is a no-op — the reconcile pass races the result; the verb must\n   * tolerate a stale fire. PURE.\n   */\n  function onTimer(\n    s: ResilientState<I, R>,\n    msg: ResilientTimerMsg,\n  ): readonly [ResilientState<I, R>, readonly RunCmd<I>[]] {\n    for (const [key, call] of Object.entries(s.calls)) {\n      if (msg.id === retryTimerId(key)) {\n        if (call.phase !== \"waiting_retry\") return [s, []];\n        // The backoff wait was in-process time, so it is charged before the gate\n        // reads the budget — and the gate settles rather than dispatching when\n        // that leaves nothing, which is how a resumed ladder ends without one\n        // more port call.\n        return gate(\n          s,\n          key,\n          call.input,\n          msg.atMs,\n          charge(call.budget, msg.atMs),\n        );\n      }\n      if (msg.id === deadlineTimerId(key)) {\n        // Deadline only fires for a still-active call. A settled call has no\n        // armed deadline Sub, but tolerate a stale fire defensively.\n        if (call.phase !== \"running\" && call.phase !== \"waiting_retry\")\n          return [s, []];\n        // Plain-data sentinel, NOT a `new Error(...)`: an Error object is not\n        // JSON-serializable (it round-trips to `{}`) and captures a stack trace,\n        // both of which break the slice's durability invariant once it is\n        // persisted into a `Store<S>` and reloaded. A `{_tag, ...}` record keeps\n        // the slice round-trip-equal under JSON.parse(JSON.stringify(...)).\n        return [\n          setCall(s, key, {\n            phase: \"failed\",\n            error: {\n              _tag: \"deadline_exceeded\",\n              id: msg.id,\n              atMs: msg.atMs,\n            } satisfies DeadlineExceededError,\n          }),\n          [],\n        ];\n      }\n    }\n    return [s, []];\n  }\n\n  // === Subs ================================================================\n\n  /**\n   * Pre-wired subscriptions: a retry timer for every `waiting_retry` call, and\n   * (when the `deadline` brick is configured) an overall deadline timer for\n   * every still-active call. Both are `DeadlineSub`s reconciled by id, so a\n   * phase change cancels the matching timer automatically — no manual\n   * `clearTimeout`. Wire `subscribe: { deadline: subscribeDeadline }`.\n   */\n  function subs(s: ResilientState<I, R>): readonly DeadlineSub[] {\n    const out: DeadlineSub[] = [];\n    for (const [key, call] of Object.entries(s.calls)) {\n      if (call.phase === \"waiting_retry\") {\n        out.push(deadlineSub(retryTimerId(key), call.retryAtMs));\n      }\n      if (\n        config.deadline !== undefined &&\n        (call.phase === \"running\" || call.phase === \"waiting_retry\") &&\n        call.budget.remainingMs > 0\n      ) {\n        // The absolute instant the timer arms at is DERIVED here, from the open\n        // segment's anchor plus what is left — it is never persisted, so a slice\n        // that came back from storage arms off the anchor `resume` just re-based\n        // rather than off a stamp the downtime ran past.\n        out.push(\n          deadlineSub(\n            deadlineTimerId(key),\n            call.budget.chargingSinceMs + call.budget.remainingMs,\n          ),\n        );\n      }\n    }\n    return out;\n  }\n\n  // === Handlers ============================================================\n\n  /**\n   * Pre-wired interpret handler for `resilient_run`. Wraps the consumer's\n   * `run` port via `tryInterpret` (Railway): success → `resilient_ok`, failure\n   * → `resilient_err`, each stamped with `Date.now()` at the effect boundary —\n   * the ONE permitted clock read (interpret is impure; the reducer never reads\n   * the clock). Assign to the machine's `interpret`:\n   *\n   *   interpret: rc.handlers({ run: (input, key) => ctx.callBackend(input) })\n   */\n  function handlers(ports: ResilientPorts<I, R>) {\n    return {\n      resilient_run: tryInterpret<\n        RunCmd<I>,\n        R,\n        SucceedMsg<R> | FailMsg,\n        // The work fn reads nothing from ctx — it forwards `cmd.input` to the\n        // consumer-supplied `run` port. `NoCtx` (not `unknown`) marks this as a\n        // DELIBERATE context-free seam, so callers see intent, not looseness.\n        NoCtx\n      >(\n        (cmd) => ports.run(cmd.input, cmd.key),\n        (result, cmd): SucceedMsg<R> => ({\n          type: MsgType.ResilientOk,\n          key: cmd.key,\n          result,\n          at: Date.now(),\n        }),\n        (error, cmd): FailMsg => ({\n          type: MsgType.ResilientErr,\n          key: cmd.key,\n          error,\n          at: Date.now(),\n        }),\n      ),\n    };\n  }\n\n  return {\n    init,\n    attempt,\n    resume,\n    succeed,\n    fail,\n    settleFailed,\n    onTimer,\n    subs,\n    handlers,\n  };\n}\n\n/**\n * Lift a knob result `[slice, cmds]` into a host `[State, cmds]` where the\n * slice lives at `state.resilience`. A convenience for the common single-slice\n * host; consumers with a differently-named field spread by hand. Pure — a thin\n * record rebuild, no clock / RNG. Under `withResilience` the wrapper owns\n * `model.$resilience`, so there is nothing to lift; this is for the embedded\n * slice consumers only.\n */\nexport function liftResilience<\n  S extends { resilience: ResilientState<I, R> },\n  I,\n  R,\n  C extends Cmd,\n>(\n  state: S,\n  [slice, cmds]: readonly [ResilientState<I, R>, readonly C[]],\n): readonly [S, readonly C[]] {\n  return [{ ...state, resilience: slice }, cmds];\n}\n\n/**\n * Re-export the deadline Sub primitives so consumers (and tests) wire one\n * import: `subscribeDeadline` is the `subscribe` cell, `deadlineSub` builds the\n * Sub literal this knob's `subs` emits.\n */\nexport { subscribeDeadline, deadlineSub };\nexport type { DeadlineSub, DeadlineExceeded };\n"]}

package/dist/chunk-F2US5BW6.js

@@ -1,72 +0,0 @@
-import { fromInterval, subId, fromTimeout } from './chunk-RQULHGYH.js';
-
-// src/internal/resilience/deadline/index.ts
-function deadlineSub(id, atMs, opts) {
-  return { ...opts, id: subId(id), type: "deadline", atMs };
-}
-function subscribeWith(armTimer) {
-  return (sub, _ctx, dispatch) => armTimer(sub.id, sub.atMs, deadlineExceeded(sub.id, sub.atMs), dispatch);
-}
-function setTimeoutArmTimer() {
-  return (id, atMs, msg, dispatch) => {
-    const delayMs = Math.max(0, atMs - Date.now());
-    return fromTimeout(
-      () => msg
-    )({ id, type: "deadline", delayMs }, void 0, dispatch);
-  };
-}
-var subscribeDeadline = subscribeWith(setTimeoutArmTimer());
-function deadlineExceeded(id, atMs) {
-  return { type: "deadline_exceeded", id, atMs };
-}
-
-// src/internal/resilience/cache/index.ts
-function initCache() {
-  return { entries: {} };
-}
-function isExpired(entry, nowMs) {
-  return nowMs >= entry.expiresAtMs;
-}
-function get(cache, key, nowMs) {
-  const entry = cache.entries[key];
-  if (entry === void 0 || isExpired(entry, nowMs)) return void 0;
-  return entry.value;
-}
-function has(cache, key, nowMs) {
-  const entry = cache.entries[key];
-  if (entry === void 0) return false;
-  return !isExpired(entry, nowMs);
-}
-function set(cache, key, value, nowMs, ttlMs) {
-  const nextEntries = { ...cache.entries };
-  nextEntries[key] = { value, expiresAtMs: nowMs + ttlMs };
-  return { ...cache, entries: nextEntries };
-}
-function remove(cache, key) {
-  const nextEntries = { ...cache.entries };
-  delete nextEntries[key];
-  return { ...cache, entries: nextEntries };
-}
-function evictExpired(cache, nowMs) {
-  const nextEntries = {};
-  for (const [key, entry] of Object.entries(cache.entries)) {
-    if (isExpired(entry, nowMs)) continue;
-    nextEntries[key] = entry;
-  }
-  return { ...cache, entries: nextEntries };
-}
-function cacheEvictMsg(id) {
-  return { type: "cache_evict", id };
-}
-function cacheEvictionSub(id, everyMs) {
-  return {
-    id,
-    type: "cache",
-    intervalMs: everyMs
-  };
-}
-var cacheEvictionSubscribe = fromInterval((sub) => cacheEvictMsg(sub.id));
-
-export { cacheEvictMsg, cacheEvictionSub, cacheEvictionSubscribe, deadlineExceeded, deadlineSub, evictExpired, get, has, initCache, remove, set, setTimeoutArmTimer, subscribeDeadline, subscribeWith };
-//# sourceMappingURL=chunk-F2US5BW6.js.map
-//# sourceMappingURL=chunk-F2US5BW6.js.map