@demlik/tea 0.13.0 → 0.14.0

package/dist/throttled-input/index.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../../src/throttled-input/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * @demlik/tea/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 * Consumers reach it via the `@demlik/tea/throttled-input` subpath; the L1\n * escape hatch is those sibling subpaths threaded by hand. NOT exported from the\n * package root — same one-shape-per-package rule as `batch-window` and `poller`.\n */\n\nimport {\n  get as cacheGet,\n  set as cacheSet,\n  initCache,\n  type TtlCache,\n} from \"../cache\";\nimport { type DeadlineSub, deadlineSub } from \"../deadline\";\nimport type { Cmd, Sub } from \"../index\";\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 \"../deadline\";\n"]}

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

@@ -1,216 +0,0 @@
-import { C as Cmd, I as Interpret } from '../core-Co0LWkIA.js';
-import { M as MsgType } from '../protocol-B5YmJr0d.js';
-import 'zod';
-
-/**
- * @demlik/tea/token-refresh — a credential's lifecycle as pure state + verbs,
- * with the actual token fetch deferred to a single injected port.
- *
- * This is the L1 brick `authed-call` (#10 in the composition specs) stacks on:
- * a token slice `{ token, stale }` plus pure transitions that decide *when* a
- * credential must be re-minted, and one `handlers(ports)` splice that performs
- * the re-mint. It follows the uniform knob contract every composition wears —
- * `createTokenRefresh(config) → { init, <verbs>, handlers }` — so a consumer
- * spreads ~3 hooks into their machine instead of hand-wiring the refresh dance.
- *
- * It is a LEAF module in the same mold as `@demlik/tea/retry-backoff`: it
- * depends only on the core (`../index`), never on a sibling brick. The two
- * non-negotiables of every knob hold here by construction:
- *
- *   - **Durable** — the token slice is plain JSON-serializable data, so it
- *     survives a Durable Object eviction / page reload. A rehydrated machine
- *     resumes knowing exactly which token it holds and whether it is stale.
- *   - **Replayable** — every transition is a pure verb returning
- *     `readonly [State, Cmd[]]`. No verb reads the wall clock or performs I/O,
- *     so `replay` reconstructs the slice exactly. Time enters ONLY as an `at`
- *     parameter the caller stamps; the network fetch enters ONLY at the
- *     `handlers` boundary. This keeps the substrate's purity invariants intact
- *     (invariant 2: pure transitions; invariant 4: I/O is an effect, not a
- *     reducer body).
- *
- * ## The staleness model — two independent reasons to refresh
- *
- * A token becomes unusable for two unrelated reasons, and the slice tracks both
- * without conflating them:
- *
- *   1. **Expiry** — the token has a known `expiresAt` (epoch ms). It is "near
- *      expiry" once `at >= expiresAt - skewMs`. The `skewMs` skew refreshes
- *      *ahead* of the hard deadline so an in-flight call never races a token
- *      that expires mid-request. This is the proactive, time-driven reason and
- *      is computed purely from the injected `at` — no clock in the verb.
- *
- *   2. **Server rejection (401)** — the server rejected a request the client
- *      believed was still valid (clock skew, a server-side revocation, an early
- *      rotation). `on401` flips a `stale` flag regardless of `expiresAt`. This
- *      is the reactive reason: the client's belief about validity was wrong, so
- *      the next `needsRefresh` returns true even though the clock says the
- *      token is fine.
- *
- * `needsRefresh` is the union of the two (plus "no token at all"). One source
- * of truth for "should I fetch a fresh credential before the next call?", read
- * by the consumer's reducer at the call boundary.
- *
- * Typical wiring (inside a consumer machine):
- *
- *   const tr = createTokenRefresh({ skewMs: 30_000 });
- *
- *   // in init:
- *   init: (loaded) => [loaded ?? { auth: tr.init() }, Cmd.none],
- *
- *   // in a reducer cell that is about to make an authed call:
- *   before_call: (s, msg) => {
- *     const [auth, cmds] = tr.ensureFresh(s.auth, msg.at);
- *     return [{ ...s, auth }, cmds]; // emits a refresh Cmd iff a refresh is due
- *   },
- *
- *   // on a 401 from a guarded call:
- *   got_401: (s) => [{ ...s, auth: tr.on401(s.auth) }, []],
- *
- *   // when the refresh port resolves:
- *   token_refreshed: (s, msg) => [{ ...s, auth: tr.refreshed(s.auth, msg.token) }, []],
- *
- *   // splice the I/O:
- *   interpret: { ...tr.handlers({ refresh: () => mySdk.mintToken() }) },
- *
- * NOT a substrate primitive: from `../index` it reuses only the `Cmd` /
- * `Interpret` types and the `tryInterpret` Railway helper (a runtime function,
- * not a type) that every effectful brick uses — and no sibling brick. It is a
- * leaf utility consumers reach via the `@demlik/tea/token-refresh` subpath.
- */
-
-/**
- * A minted credential: the opaque `value` to send on the wire, and the absolute
- * `expiresAt` (epoch milliseconds — the `Date.now()` scale) the issuer stamped
- * it with. Both fields are plain data so a `Token` is trivially serializable
- * into a consumer's `Store<S>`.
- *
- * `value` is `string` because that is the universal shape of a bearer token /
- * API key / session cookie on the wire. A consumer whose refresh port yields a
- * richer object can JSON-encode it into `value`, or keep this module's slice as
- * the "is it fresh?" gate and hold the richer object elsewhere in their Model.
- */
-interface Token {
-    /** The opaque credential to present on each request (bearer token, API key). */
-    readonly value: string;
-    /** Absolute expiry instant, epoch milliseconds. The `Date.now()` scale. */
-    readonly expiresAt: number;
-}
-/**
- * Pure configuration — the knob's only field. Carries no mutable state;
- * `TokenState` does. One config is shared across all the refreshes of one
- * logical credential (often a module-scope const).
- */
-interface TokenRefreshConfig {
-    /**
-     * Refresh-ahead skew, in milliseconds. A token is treated as needing a
-     * refresh once `at >= expiresAt - skewMs`, i.e. `skewMs` BEFORE its hard
-     * expiry. This buys headroom so a call that starts just under the wire never
-     * races a token that lapses mid-flight, and absorbs small client/server clock
-     * disagreement. `0` means "refresh exactly at expiry"; a negative value is
-     * clamped to `0` (a skew that pushes the trigger past expiry is meaningless).
-     *
-     * @default 0
-     */
-    readonly skewMs?: number;
-}
-/**
- * The token slice this knob owns — the Model field a consumer spreads in via
- * `init()`. A two-field record rather than a phase union because the two
- * dimensions are orthogonal: a token can be present-and-fresh, present-but-stale
- * (a 401 came back), absent, or absent-and-stale (cleared after a failed
- * refresh). Every combination is meaningful, so neither field implies the
- * other's value and a discriminated union would only manufacture impossible
- * arms.
- *
- *   - `token` — the currently held credential, or `null` when none has been
- *     minted yet (fresh boot) or the last refresh failed.
- *   - `stale` — set by `on401` when the server rejected a request the client
- *     believed valid. Forces the next `needsRefresh` to true regardless of
- *     `expiresAt`; cleared by `refreshed` once a new credential lands.
- *
- * Both fields `readonly` so the whole slice threads safely through a pure
- * reducer and serializes into a `Store<S>`.
- */
-interface TokenState {
-    /** The held credential, or `null` if none is available (boot / failed refresh). */
-    readonly token: Token | null;
-    /** Whether a 401 has marked the held token unusable ahead of its `expiresAt`. */
-    readonly stale: boolean;
-}
-/**
- * The starting slice: no token held, not stale. The first `needsRefresh` after
- * this returns `true` (no token), so a consumer's first guarded call mints a
- * credential before going out.
- */
-declare function initTokenRefresh(): TokenState;
-/**
- * The Cmd this knob emits to ask the runtime to mint a fresh token. Plain data
- * (no closure — invariant 1) carrying nothing: the refresh port takes no input,
- * and the slice the result installs is read off the follow-up Msg, not this
- * Cmd. The consumer unions this into their machine's Cmd type and lets
- * `handlers` interpret it.
- */
-interface RefreshTokenCmd extends Cmd<"refresh_token"> {
-}
-/** Construct a `refresh_token` Cmd. */
-declare function refreshTokenCmd(): RefreshTokenCmd;
-/**
- * The Msg the refresh port dispatches on success — carries the freshly minted
- * `Token`. The consumer unions this into their Msg type and handles it by
- * folding `refreshed(state, msg.token)` into the slice.
- */
-interface TokenRefreshedMsg {
-    readonly type: typeof MsgType.TokenRefreshed;
-    readonly token: Token;
-}
-/** Construct a `token_refreshed` Msg carrying the new token. */
-declare function tokenRefreshedMsg(token: Token): TokenRefreshedMsg;
-/**
- * The Msg the refresh port dispatches on failure — carries the rejection so the
- * consumer's reducer can decide whether to back off, surface an error, or give
- * up (errors are data: it is dispatched, never swallowed). The slice itself is
- * left untouched by a failed refresh — the held token (if any) stays held and
- * stale stays set, so the consumer can retry; clearing it is the consumer's
- * policy, expressed in their reducer.
- */
-interface TokenRefreshFailedMsg {
-    readonly type: typeof MsgType.TokenRefreshFailed;
-    readonly error: unknown;
-}
-/** Construct a `token_refresh_failed` Msg carrying the rejection. */
-declare function tokenRefreshFailedMsg(error: unknown): TokenRefreshFailedMsg;
-/** The two Msgs the refresh port can produce. Union for a consumer's Msg type. */
-type TokenRefreshMsg = TokenRefreshedMsg | TokenRefreshFailedMsg;
-/** The ports this knob's `handlers` splice needs — the single refresh DI seam. */
-interface TokenRefreshPorts {
-    /**
-     * Mint a fresh credential. Called ONLY from the `refresh_token` interpret
-     * handler — never from a verb — so the network I/O and any clock the issuer
-     * reads stay at the effect boundary. May reject; the rejection is routed to
-     * `token_refresh_failed` (errors are data), never thrown into the runtime.
-     */
-    readonly refresh: () => Promise<Token>;
-}
-/**
- * The knob: hand it a config, get back the slice initializer, the pure verbs,
- * and the `handlers` splice. Mirrors every L2 composition's uniform contract so
- * the call sites read identically across bricks.
- *
- * @example
- *   const tr = createTokenRefresh({ skewMs: 30_000 });
- *   const s0 = tr.init();
- *   const [s1, cmds] = tr.ensureFresh(s0, Date.now()); // cmds = [refreshTokenCmd()]
- */
-declare function createTokenRefresh(config?: TokenRefreshConfig): {
-    /** The slice initializer — spread into the consumer's `init`. */
-    init: typeof initTokenRefresh;
-    needsRefresh: (state: TokenState, at: number) => boolean;
-    on401: (state: TokenState) => TokenState;
-    refreshed: (state: TokenState, token: Token) => TokenState;
-    ensureFresh: (state: TokenState, at: number) => readonly [TokenState, readonly Cmd[]];
-    handlers: (ports: TokenRefreshPorts) => Interpret<TokenRefreshMsg, RefreshTokenCmd, unknown>;
-};
-/** The shape `createTokenRefresh` returns — useful for typing a held knob. */
-type TokenRefresh = ReturnType<typeof createTokenRefresh>;
-
-export { type RefreshTokenCmd, type Token, type TokenRefresh, type TokenRefreshConfig, type TokenRefreshFailedMsg, type TokenRefreshMsg, type TokenRefreshPorts, type TokenRefreshedMsg, type TokenState, createTokenRefresh, initTokenRefresh, refreshTokenCmd, tokenRefreshFailedMsg, tokenRefreshedMsg };

package/dist/token-refresh/index.js

@@ -1,6 +0,0 @@
-export { createTokenRefresh, initTokenRefresh, refreshTokenCmd, tokenRefreshFailedMsg, tokenRefreshedMsg } from '../chunk-CLM6ERNO.js';
-import '../chunk-JELSZN25.js';
-import '../chunk-ZSUUOEPL.js';
-import '../chunk-OOYD44JI.js';
-//# sourceMappingURL=index.js.map
-//# sourceMappingURL=index.js.map

package/dist/token-refresh/index.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}

package/dist/trace-replay/index.js

@@ -1,6 +0,0 @@
-export { deepEqual, replayTrace } from '../chunk-D62FDQKE.js';
-import '../chunk-ZSUUOEPL.js';
-import '../chunk-OOYD44JI.js';
-import '../chunk-EWJP3YYP.js';
-//# sourceMappingURL=index.js.map
-//# sourceMappingURL=index.js.map

package/dist/trace-replay/index.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}

package/dist/with-deadline/index.d.ts

@@ -1,197 +0,0 @@
-import { C as Cmd, S as Sub, M as Machine } from '../core-Co0LWkIA.js';
-import 'zod';
-
-/**
- * @demlik/tea/with-deadline — auto-fail a wrapped machine at T+N, re-arm on
- * progress. A **pure function over machine data**: `withDeadline(base, config)`
- * takes any `Machine<S, M, C, U, Ctx>` and returns a NEW `Machine` over the
- * composed Model `{ base, $deadline }`. You `run()` / `replay()` the result
- * exactly like any other machine — there is no new runtime, no privileged
- * interception path.
- *
- * ## What it does
- *
- * The wrapper watches the base Msg stream. While the deadline is `armed`, a
- * RELATIVE timeout Sub counts down `config.ms`. Every base Msg the
- * `config.progress` predicate accepts (default: every base Msg) is treated as
- * activity: the wrapper bumps a numeric `seq`, which CHANGES the timer Sub's id,
- * so the substrate's reconcile pass retires the old countdown and starts a fresh
- * one — "re-arm on progress". If `config.ms` elapses with NO accepted progress,
- * the timeout Sub dispatches `$deadline:exceeded`; the merged `update` folds it
- * by flipping `phase` to `exceeded`, and from then on `subscriptions` returns no
- * timer (the machine has auto-failed). The expiry is a slice transition visible
- * in the Msg log — the auto-fail is never an off-ledger side effect.
- *
- * This is an OBSERVE-ONLY wrapper in the same sense as `withTelemetry`: it never
- * intercepts a base Cmd and never gates a base Msg. `state.base` after wrapping
- * is BYTE-IDENTICAL to running the base alone, so the shared
- * `assertWrapperFaithful` gate passes with the deadline bolted on.
- *
- * ## The 5 rules it satisfies (from the wrapper-tier contract)
- *
- *   1. **Named, serializable slice.** Wrapper state lives at `model.$deadline`,
- *      a plain `{ phase, seq }` — JSON-serializable, never a closure. There is
- *      NO absolute timestamp in the slice: the clock is never read in `update`.
- *   2. **Retag-and-re-emit, never swallow.** The merged `update` runs the base
- *      reducer, passes its Cmds through UNCHANGED, and APPENDS its own
- *      `$deadline:rearm` / `$deadline:expire` decision Cmd. No base Cmd ever
- *      vanishes; nothing is gated.
- *   3. **Every decision is a Msg/Cmd.** Re-arm is a `$deadline:rearm` Cmd; the
- *      auto-fail expiry is the `$deadline:exceeded` Msg the Sub delivers, folded
- *      into the slice and echoed as a `$deadline:expire` Cmd. "Why did this
- *      fire" is answerable from reducer + log alone.
- *   4. **Subs merge by id.** `subscriptions = [...base, ...deadlineSubs]`; the
- *      timeout id is `$deadline:timeout:{seq}`, so a progress bump (seq+1)
- *      yields a NEW id — the substrate retires the old timer and arms a fresh
- *      one. When `exceeded`, no deadline sub is returned.
- *   5. **Clock out of update.** The countdown is a relative-timeout Sub; the
- *      clock is read at subscribe time inside the Sub (`setTimeout`), NEVER in a
- *      verb. The slice carries `seq`, not a deadline timestamp.
- *
- * ## Typical wiring
- *
- *   const guarded = withDeadline(baseMachine, {
- *     ms: 900_000, // auto-fail after 15 minutes of inactivity
- *     progress: (msg) => msg.type !== "heartbeat", // heartbeats don't re-arm
- *   });
- *   const runtime = run(guarded, { ctx: baseCtx });
- */
-
-/**
- * The wrapper's Model slice. `phase` is the lifecycle (`armed` while the
- * countdown runs, `exceeded` once the deadline fired); `seq` is the monotonic
- * re-arm counter that keys the timer Sub's id so each accepted progress Msg
- * retires the old timer and starts a fresh one.
- *
- * PURE and SERIALIZABLE: there is deliberately NO absolute timestamp here. A
- * deadline timestamp would force the merged `update` to read the wall clock to
- * compute it, which the conformance gate (property 2 — two replays under
- * distinct ambient clocks) is built to catch. Instead, the timer arms a fresh
- * full `ms` countdown per generation; no remaining-delay computation and no
- * clock read occur in the slice or `update` — the only clock is `setTimeout`
- * inside the Sub.
- */
-interface DeadlineSlice {
-    /** `armed` while the countdown is live; `exceeded` once the deadline fired. */
-    readonly phase: "armed" | "exceeded";
-    /**
-     * Monotonic re-arm counter. Starts at 0; each accepted progress Msg (while
-     * armed) bumps it by one. Folds into the timer Sub's id, so a bump = a new id
-     * = the substrate retires the old timer and arms a fresh `ms` countdown.
-     */
-    readonly seq: number;
-}
-/**
- * The composed Model. The base machine's state is nested under `base`; the
- * wrapper's state lives in the NAMED `$deadline` slice — never hidden in a
- * closure. Both fields are plain data, so the whole composed Model round-trips
- * through `JSON.parse(JSON.stringify(...))` iff the base state does.
- */
-interface DeadlineModel<S> {
-    readonly base: S;
-    readonly $deadline: DeadlineSlice;
-}
-/**
- * The relative-timeout Sub the wrapper arms while `phase === "armed"`. `delayMs`
- * is the window `config.ms`; the id is `$deadline:timeout:{seq}`, so each
- * progress bump produces a distinct id and the reconcile pass churns the timer.
- * Same `delayMs`-on-the-Sub shape `fromTimeout` consumes.
- */
-type DeadlineTimeoutSub = Sub<"$deadline:timeout"> & {
-    readonly delayMs: number;
-};
-/**
- * The Msg the timeout Sub dispatches when `config.ms` elapses with no accepted
- * progress. `seq` echoes the re-arm generation the timer was armed against, so a
- * stale timer's Msg (one whose id was already retired) is identifiable; the
- * merged `update` only honors it when it matches the current slice `seq`.
- */
-interface DeadlineExceededMsg {
-    readonly type: "$deadline:exceeded";
-    /** The re-arm generation this timer was armed against. */
-    readonly seq: number;
-}
-/**
- * Construct the deadline-exceeded Msg. Exported so the subscribe cell and tests
- * share one constructor rather than two literals that can drift.
- */
-declare function deadlineExceededMsg(seq: number): DeadlineExceededMsg;
-/**
- * The fire-and-forget decision Cmd the merged `update` appends on every
- * transition, so the wrapper's choice is visible in the replayed Cmd log
- * (rule 3) — `rearm` when an accepted progress Msg bumped `seq`, `expire` when
- * the deadline-exceeded Msg flipped the phase, `idle` otherwise (a non-progress
- * Msg, or a Msg after the machine already auto-failed). Plain data; its
- * interpret handler is a no-op (the decision is the Cmd's presence in the log,
- * not a side effect).
- */
-type DeadlineDecisionCmd = Cmd<"$deadline:decision"> & {
-    readonly decision: "rearm" | "expire" | "idle";
-    /** The slice `seq` AFTER this transition (the re-arm generation now armed). */
-    readonly seq: number;
-};
-/**
- * A predicate over a Msg that decides whether it re-arms the deadline.
- *
- * The argument is `Readonly<M>` and the result is `boolean`: this is the
- * STRONGEST purity TS can express here. `Readonly<M>` removes the most common
- * impurity at compile time — the predicate cannot reassign the Msg's own
- * fields — and `boolean` pins the return so a side-effecting `(msg) => { … }`
- * with an implicit `undefined`/`void` return is rejected.
- *
- * What the type system CANNOT encode (TS has no effect tracking): observational
- * purity. A body that reads `Date.now()`, calls `Math.random()`, performs IO,
- * or closes over and mutates external state still type-checks. Those remain a
- * CONVENTION enforced by review, not the compiler — the predicate runs inside
- * the pure merged `update` (invariant 2), so it must be a pure function of the
- * Msg alone: no clock, no RNG, no IO, no captured mutable state.
- */
-type ProgressPredicate<M extends {
-    type: string;
-}> = (msg: Readonly<M>) => boolean;
-/**
- * The deadline knob. `ms` is the inactivity window; `progress` is an OPTIONAL
- * predicate picking which base Msgs count as activity (default: EVERY base Msg
- * re-arms). The predicate runs INSIDE the pure merged `update`, so it must be a
- * pure function of the Msg — see {@link ProgressPredicate} for what the type
- * enforces vs. what stays a convention.
- */
-interface DeadlineConfig<M extends {
-    type: string;
-}> {
-    /** The inactivity window in milliseconds. Auto-fail after `ms` with no progress. */
-    readonly ms: number;
-    /**
-     * Predicate picking which base Msgs re-arm the timer. Default: every base Msg
-     * counts as progress. Pure — a function of the Msg alone (see
-     * {@link ProgressPredicate}).
-     */
-    readonly progress?: ProgressPredicate<M>;
-}
-/**
- * Wrap `base` with an inactivity deadline. Returns a NEW `Machine` over the
- * composed Model `{ base, $deadline }`, with the base's Msgs/Cmds/Subs extended
- * by the wrapper's own (`$deadline:exceeded` Msg, `$deadline:decision` Cmd,
- * `$deadline:timeout` Sub).
- *
- * The composed machine:
- *   - `init` rehydrates the base (honoring the `[loaded, []]` contract) and
- *     seeds `$deadline: { phase: "armed", seq: 0 }`. Base init Cmds pass
- *     through unchanged.
- *   - `update` (Reducer form) runs the base reducer for base Msgs — base Cmds
- *     pass through UNCHANGED — and on an accepted progress Msg bumps `seq`
- *     (re-arm). The `$deadline:exceeded` Msg cell flips `phase` to `exceeded`.
- *     Every transition appends a `$deadline:decision` marker Cmd.
- *   - `subscriptions` is the base's, plus a `$deadline:timeout` Sub keyed on
- *     `seq` while `phase === "armed"`.
- *   - `subscribe` is the base's, plus the `$deadline:timeout` cell.
- *   - `interpret` is the base's, plus a no-op `$deadline:decision` handler.
- *
- * @param base   any `Machine<S, M, C, U, Ctx>`.
- * @param config the deadline knob (`ms` window + optional `progress` predicate).
- */
-declare function withDeadline<S, M extends {
-    type: string;
-}, C extends Cmd, U extends Sub, Ctx>(base: Machine<S, M, C, U, Ctx>, config: DeadlineConfig<M>): Machine<DeadlineModel<S>, M | DeadlineExceededMsg, C | DeadlineDecisionCmd, U | DeadlineTimeoutSub, Ctx>;
-
-export { type DeadlineConfig, type DeadlineDecisionCmd, type DeadlineExceededMsg, type DeadlineModel, type DeadlineSlice, type DeadlineTimeoutSub, type ProgressPredicate, deadlineExceededMsg, withDeadline };

package/dist/with-deadline/index.js

@@ -1,111 +0,0 @@
-import { fromTimeout } from '../chunk-2YFLOCWX.js';
-import '../chunk-ZSUUOEPL.js';
-import { msgKeysOf, applyCell, subId } from '../chunk-OOYD44JI.js';
-
-// src/with-deadline/index.ts
-function deadlineExceededMsg(seq) {
-  return { type: "$deadline:exceeded", seq };
-}
-function withDeadline(base, config) {
-  const windowMs = config.ms;
-  const isProgress = config.progress;
-  const update = {};
-  const baseMsgKeys = msgKeysOf(base);
-  for (const key of baseMsgKeys) {
-    if (key.startsWith("$deadline:")) {
-      throw new Error(
-        `withDeadline: the base machine declares a reserved "${key}" update cell \u2014 the wrapper owns the "$deadline:" Msg namespace. Rename the base Msg.`
-      );
-    }
-  }
-  for (const key of baseMsgKeys) {
-    update[key] = (state, msg) => {
-      const [nextBase, baseCmds] = applyCell(
-        base,
-        state.base,
-        msg
-      );
-      const armed = state.$deadline.phase === "armed";
-      const counts = armed && (isProgress === void 0 || isProgress(msg));
-      const $deadline = counts ? { phase: "armed", seq: state.$deadline.seq + 1 } : state.$deadline;
-      const next = { base: nextBase, $deadline };
-      const decision = {
-        type: "$deadline:decision",
-        decision: counts ? "rearm" : "idle",
-        seq: $deadline.seq
-      };
-      return [next, [...baseCmds, decision]];
-    };
-  }
-  update["$deadline:exceeded"] = (state, msg) => {
-    const m = msg;
-    const fires = state.$deadline.phase === "armed" && m.seq === state.$deadline.seq;
-    const $deadline = fires ? { phase: "exceeded", seq: state.$deadline.seq } : state.$deadline;
-    const next = { base: state.base, $deadline };
-    const decision = {
-      type: "$deadline:decision",
-      decision: fires ? "expire" : "idle",
-      seq: $deadline.seq
-    };
-    return [next, [decision]];
-  };
-  const baseInterpret = base.interpret ?? {};
-  if (Object.hasOwn(baseInterpret, "$deadline:decision")) {
-    throw new Error(
-      'withDeadline: the base machine declares a reserved "$deadline:decision" interpret handler \u2014 the wrapper owns the "$deadline:" Cmd namespace. Rename the base handler.'
-    );
-  }
-  const interpret = {
-    ...baseInterpret,
-    "$deadline:decision": async () => {
-    }
-  };
-  const baseSubscriptions = base.subscriptions;
-  const subscriptions = (state) => {
-    const baseSubs = baseSubscriptions ? baseSubscriptions(state.base) : [];
-    if (state.$deadline.phase !== "armed") return baseSubs;
-    const timeout = {
-      id: subId(`$deadline:timeout:${state.$deadline.seq}`),
-      type: "$deadline:timeout",
-      delayMs: windowMs
-    };
-    return [...baseSubs, timeout];
-  };
-  const baseSubscribe = base.subscribe ?? {};
-  if (Object.hasOwn(baseSubscribe, "$deadline:timeout")) {
-    throw new Error(
-      'withDeadline: the base machine declares a reserved "$deadline:timeout" subscribe handler \u2014 the wrapper owns the "$deadline:" Sub namespace. Rename the base handler.'
-    );
-  }
-  const timeoutCell = fromTimeout(
-    (sub) => {
-      const seq = Number(sub.id.slice(sub.id.lastIndexOf(":") + 1));
-      return deadlineExceededMsg(seq);
-    }
-  );
-  const subscribe = {
-    ...baseSubscribe,
-    "$deadline:timeout": timeoutCell
-  };
-  return {
-    init: (loaded, ctx) => {
-      if (loaded !== null) {
-        return [loaded, []];
-      }
-      const [base0, cmds] = base.init(null, ctx);
-      const model = {
-        base: base0,
-        $deadline: { phase: "armed", seq: 0 }
-      };
-      return [model, cmds];
-    },
-    update,
-    subscriptions,
-    subscribe,
-    interpret
-  };
-}
-
-export { deadlineExceededMsg, withDeadline };
-//# sourceMappingURL=index.js.map
-//# sourceMappingURL=index.js.map