@demlik/tea 0.14.0 → 0.16.0

package/dist/{index-q0hXFeZ0.d.ts → index-Xufl55W8.d.ts}

@@ -1,161 +1,21 @@
-import { S as Sub, c as SubId } from './core-CTzMJ82M.js';
-import { S as SubscribeHandler } from './types-DP3f5NIl.js';
-
-/**
- * internal/resilience/cache — a TTL cache as pure state, PLUS a periodic eviction Sub.
- *
- * Same pure-state-ops shape as `../../idempotency/` and
- * `../../work-queue/ops.ts`: a state type plus pure transition functions. Host-
- * agnostic by construction — no `Date.now()`, no timers, no I/O inside the ops.
- * The caller injects the clock (`nowMs`) and folds the result through its own
- * reducer, keeping the store inside TEA's invariant 2 (transitions are pure:
- * same inputs → same outputs) so a consumer can exercise it with `replay`
- * without a fake clock.
- *
- * Every op returns a NEW cache value and never mutates its input (invariant 1 —
- * state is a value, not a place). `get` / `has` are read-shaped; `set` /
- * `remove` / `evictExpired` return a new cache.
- *
- * **Distinct from `/idempotency`.** Both are TTL-bounded key maps, but they
- * answer different questions and so carry different shapes:
- *
- *   - `/idempotency` is DEDUPE-focused — "have I already processed this key?"
- *     TTL is a single store-level policy (`ttlMs`), each entry stores the
- *     `atMs` it was remembered at, and expiry is derived (`now - atMs >=
- *     ttlMs`). It carries an `order` ledger + `capacity` because the use case
- *     (webhook receivers, retried messages) needs bounded LRU eviction.
- *   - `/cache` is RETRIEVAL-focused — "what is the value for this key right
- *     now?" TTL is set PER ENTRY at write time: `set(key, value, nowMs,
- *     ttlMs)` bakes the absolute `expiresAtMs = nowMs + ttlMs` into the entry.
- *     Different keys can carry different lifetimes (a hot key cached for 1s, a
- *     cold one for 1h) — the dimension idempotency's single store-level
- *     `ttlMs` cannot express. No `order`, no `capacity`: a cache bounds itself
- *     by TTL + periodic eviction, not by LRU count.
- *
- * The eviction Sub is the "eviction is a Msg" half: a `setInterval`-shaped Sub
- * (composed directly on `fromInterval`, from `src/subs/`) that periodically
- * dispatches a `cache_evict` Msg the consumer's reducer handles by calling
- * `evictExpired`. Time still never enters the reducer — the Sub fires the Msg,
- * the reducer reads `nowMs` off the Msg (the consumer stamps it at the Sub
- * boundary), and `evictExpired` does the pure drop.
- *
- * Internal to the package (`src/internal/resilience/`), not a published
- * subpath (#46); same one-shape-per-module rule as `work-queue`, `idempotency`,
- * and `rate-limit`.
- */
-
-/**
- * A cached entry: the `value` and the absolute clock reading `expiresAtMs` it
- * expires at. Unlike `/idempotency`'s entry (which stores `atMs` and derives
- * expiry from a store-level `ttlMs`), the expiry instant is baked in at write
- * time — so per-entry TTLs are a first-class capability. Both fields are plain
- * data so the whole cache is trivially JSON-serializable into a consumer's
- * `Store<S>`.
- */
-interface CacheEntry<V> {
-    readonly value: V;
-    readonly expiresAtMs: number;
-}
-/**
- * The cache: a map of `key → entry`. No `order` ledger and no `capacity` (cf.
- * `/idempotency`) — a TTL cache bounds itself by expiry + periodic eviction,
- * not by LRU count. Each entry carries its own `expiresAtMs`, so the cache
- * needs no store-level TTL policy field.
- */
-interface TtlCache<V> {
-    readonly entries: Readonly<Record<string, CacheEntry<V>>>;
-}
-/** Create an empty cache. */
-declare function initCache<V>(): TtlCache<V>;
-/**
- * The cached `value` for `key` iff present AND unexpired at `nowMs`, else
- * `undefined`. An expired entry reads as absent even though it is physically
- * still in `entries` until the next `evictExpired` (or an overwriting `set`)
- * drops it. PURE — reads only, never mutates.
- */
-declare function get<V>(cache: TtlCache<V>, key: string, nowMs: number): V | undefined;
-/**
- * True iff `key` is present AND unexpired at `nowMs`. The boolean sibling of
- * `get` for callers that only need presence, not the value. PURE.
- */
-declare function has<V>(cache: TtlCache<V>, key: string, nowMs: number): boolean;
-/**
- * Write `key → value` with an absolute expiry of `nowMs + ttlMs`. Re-`set`ting
- * an existing key overwrites both the value and the expiry — the TTL clock
- * restarts from the new `nowMs`. PURE — returns a new cache; the input is
- * untouched (a fresh shallow copy of `entries`).
- */
-declare function set<V>(cache: TtlCache<V>, key: string, value: V, nowMs: number, ttlMs: number): TtlCache<V>;
-/**
- * Drop `key` regardless of expiry. PURE — returns a new cache; the input is
- * untouched. Removing an absent key returns an equivalent cache (the shallow
- * copy still happens, but no entry is dropped).
- */
-declare function remove<V>(cache: TtlCache<V>, key: string): TtlCache<V>;
-/**
- * Physically drop every entry expired at `nowMs` (`nowMs >= expiresAtMs`).
- * Returns a NEW cache with the survivors. This is the pure work the eviction
- * Sub's `cache_evict` Msg triggers — `get` / `has` already treat expired
- * entries as absent, so eviction is purely a memory-reclaim pass, not a
- * correctness one. PURE — the input cache is never mutated.
- */
-declare function evictExpired<V>(cache: TtlCache<V>, nowMs: number): TtlCache<V>;
-/**
- * The Msg the eviction Sub dispatches each tick. `id` is the Sub's own id so a
- * consumer with multiple caches can route the tick to the matching cache. The
- * reducer reads `Date.now()`-free time by stamping `nowMs` itself at the Sub
- * boundary if needed; the canonical reducer cell is
- * `cache_evict: (s) => [{ ...s, cache: evictExpired(s.cache, nowMs) }, []]`.
- */
-interface CacheEvictMsg {
-    readonly type: "cache_evict";
-    readonly id: string;
-}
-/** Construct a `cache_evict` Msg for the cache identified by `id`. */
-declare function cacheEvictMsg(id: string): CacheEvictMsg;
-/**
- * The Sub shape the eviction factory installs: a `setInterval`-shaped Sub
- * carrying its tick period (`intervalMs`) per the substrate's
- * reconcile-by-id-with-data-on-the-Sub contract. `type: "cache"` is the
- * lowercase source-noun Sub convention (canon §2.5 / naming-style).
- */
-type CacheEvictionSub = Sub<"cache"> & {
-    readonly intervalMs: number;
-};
-/**
- * Declare an eviction Sub for the cache identified by `id`, ticking every
- * `everyMs`. Drop the result into `subscriptions(state)`:
- *
- *   subscriptions: (s) => [cacheEvictionSub("session-cache", 30_000)]
- *
- * Same id ⇒ same running interval across transitions (no reconcile churn);
- * changing `everyMs` alone will NOT re-arm the timer (the substrate leaves a
- * same-id Sub running) — change the `id` too if the period must change. This
- * mirrors `fromInterval`'s data-on-the-Sub tradeoff exactly.
- */
-declare function cacheEvictionSub(id: string, everyMs: number): CacheEvictionSub;
-/**
- * The `subscribe` cell for the eviction Sub. Assign it to
- * `machine.subscribe.cache`:
- *
- *   subscribe: { cache: cacheEvictionSubscribe }
- *
- * Composed directly on `fromInterval` — it owns the `setInterval` /
- * `clearInterval` lifecycle; this cell only pins the Msg the tick dispatches
- * (`cacheEvictMsg(sub.id)`). The cleanup `fromInterval` returns stops the
- * interval when the Sub is reconciled out (the cache's state exits the phase
- * that declared it).
- */
-declare const cacheEvictionSubscribe: SubscribeHandler<CacheEvictionSub, CacheEvictMsg, unknown>;
+import { n as SubId, S as Sub, o as DepKeyedSub, h as Dispose, T as TimerDeps } from './core-BbgtiXdg.js';
+import { S as SubscribeHandler } from './types-LxZxGYda.js';
 
 /**
  * internal/resilience/deadline — a one-shot Sub that fires when an ABSOLUTE wall-clock
  * deadline is reached.
  *
  * Generalizes the recurring "auto-fail a machine at T+N" / "15-minute stale
- * guard" pattern: a Sub whose `subscriptions(state)` returns it only while the
- * deadline should be armed, and which dispatches a single `DeadlineExceeded`
- * Msg when the wall clock crosses `atMs`.
+ * guard" pattern: a deadline a battery lists only while it should be armed,
+ * which dispatches a single `DeadlineExceeded` Msg when the wall clock crosses
+ * `atMs`.
+ *
+ * A battery's `subs(slice)` returns its deadlines as a LIST (`DeadlineSub[]`,
+ * one per retry timer, say). A machine declares that list as ONE Sub of type
+ * `"deadline"` whose `deps` is the list (`deadlinesSub(select)`), and the
+ * `deadline` runner arms every deadline in it. A change to the list restarts
+ * the runner, which re-arms each deadline for its REMAINING time — `atMs` is
+ * absolute, so a restart never moves a deadline.
  *
  * Difference from `fromTimeout` (relative — "fire after N ms"): a deadline is
  * an ABSOLUTE target. The delay is computed at subscribe time as
@@ -168,10 +28,9 @@ declare const cacheEvictionSubscribe: SubscribeHandler<CacheEvictionSub, CacheEv
  * reconcile pass — the substrate must finish wiring all subs before any Msg
  * lands).
  *
- * Composition over reinvention: the timer lifecycle is `fromTimeout`'s, not
- * redrawn here. `deadlineSub` produces the Sub literal carrying `atMs`; the
- * `subscribe` handler (`subscribeDeadline`) translates `atMs` → a relative delay
- * and delegates the `setTimeout` / `clearTimeout` to `fromTimeout`. The clock
+ * `deadlineSub` produces one deadline literal carrying `atMs`; the runner
+ * (`subscribeDeadline`) translates each `atMs` → a relative delay and arms a
+ * `setTimeout` / `clearTimeout` pair per deadline. The clock
  * read (`Date.now()`) lives only in the subscribe handler — never in a reducer
  * (invariant 2) — and is exercised in tests via vitest fake timers, matching
  * the no-injection convention of the `fromTimeout` / `fromInterval` exemplars.
@@ -198,19 +57,38 @@ declare const cacheEvictionSubscribe: SubscribeHandler<CacheEvictionSub, CacheEv
  */
 
 /**
- * The Sub variant a deadline produces. `atMs` is the absolute target — epoch
+ * One deadline, as a battery lists it. `atMs` is the absolute target — epoch
  * milliseconds (the `Date.now()` / `Date.parse(...)` scale), NOT a relative
- * delay. It rides on the Sub so the reconcile pass keys identity by `id`
- * alone: the same `id` across transitions means the same armed timer, even if
- * a later `subscriptions(state)` recomputes the literal.
+ * delay. `id` names the deadline inside its list: it rides on the dispatched
+ * Msg so a reducer can tell WHICH deadline fired, and a registry-backed timer
+ * (a DO alarm slot) keys its entry on it.
  *
- * Lowercase `"deadline"` discriminant per the Sub naming convention (a source
- * noun that doubles as the SubId family); same shape family as the
- * `TimeoutSubData` the `fromTimeout` factory consumes.
+ * It is plain data — it becomes part of the `deadline` Sub's `deps`, which the
+ * engine hashes — and is not itself a running Sub.
  */
-type DeadlineSub = Sub<"deadline"> & {
+type DeadlineSub<N extends string | undefined = undefined> = {
+    readonly id: SubId;
+    readonly type: "deadline";
     readonly atMs: number;
-} & DeadlineOpts;
+} & DeadlineOpts<N>;
+/**
+ * The running `"deadline"` Sub: its `deps` is the non-empty list of deadlines
+ * to arm. Name it in `types.sub` for a machine that arms deadlines.
+ */
+type DeadlinesSub<N extends string | undefined = undefined> = Sub<"deadline", readonly DeadlineSub<N>[]>;
+/**
+ * The `deps` of a `deadline` Sub: the list, or `null` when it is empty — an
+ * empty list is a Sub with nothing to arm, and an off Sub is not a live one
+ * (`driveToDone` reads live Subs to tell a waiting machine from a stalled one).
+ */
+declare function deadlines<N extends string | undefined = undefined>(list: readonly DeadlineSub<N>[]): readonly DeadlineSub<N>[] | null;
+/**
+ * The `subs` entry that arms whatever deadlines `select` lists at a state:
+ *
+ *   subs: [deadlinesSub((s: State) => rc.subs(s.resilience))],
+ *   // run(machine, { subscribe: { deadline: subscribeDeadline } })
+ */
+declare function deadlinesSub<S, N extends string | undefined = undefined>(select: (state: S) => readonly DeadlineSub<N>[]): DepKeyedSub<S, DeadlinesSub<N>>;
 /**
  * Additive options the `deadlineSub` factory folds onto the Sub literal. This
  * is the extension seam (invariant 5 — composition by reduction): future fields
@@ -221,10 +99,24 @@ type DeadlineSub = Sub<"deadline"> & {
  * they ask for what they need by name, never positionally, so a shape extension
  * never rewrites the ~13 `deadlineSub(id, atMs)` call sites.
  *
- * Empty today on purpose — the seam exists before the first extension does, so
- * the first field is a one-line additive change, not a 13-site migration.
+ * The first field to land here is {@link DeadlineOpts.name} — the knob name the
+ * dispatched Msg tag is derived from — and it landed exactly that way: one
+ * optional member, zero rewritten call sites.
  */
-type DeadlineOpts = {};
+type DeadlineOpts<N extends string | undefined = undefined> = {
+    /**
+     * The knob this deadline belongs to. Present → the dispatched Msg's tag is
+     * `` `${name}_deadline` ``; absent → the tag stays the bare
+     * `"deadline_exceeded"` every machine wired before this field is already
+     * handling. `N` is the name as a TYPE as well as a value, so a consumer's
+     * cell key and the Msg type are derived from one place and cannot drift.
+     *
+     * Name a deadline when a machine arms more than one family of them. The Sub
+     * *id* was already scoped (`` `${name}:deadline:${key}` ``); this scopes the
+     * Msg the Sub dispatches, which is what a reducer cell keys off.
+     */
+    readonly name?: N;
+};
 /**
  * The Msg the deadline dispatches when the wall clock crosses `atMs`. Exported
  * as a tagged shape so consumers can union it into their machine's Msg type and
@@ -238,25 +130,31 @@ type DeadlineOpts = {};
  * they prefer — `deadlineExceeded(...)` only fixes the wire shape, not the
  * consumer's local dialect.
  */
-type DeadlineExceeded = {
-    readonly type: "deadline_exceeded";
+type DeadlineExceeded<N extends string | undefined = undefined> = {
+    readonly type: DeadlineMsgType<N>;
     readonly id: string;
     readonly atMs: number;
 };
 /**
- * Build a deadline Sub literal. Pure data — no clock read, no timer; the timer
- * is armed later by the `subscribe` cell. `id` is branded via `subId(...)` so
+ * The dispatched Msg's tag, derived from the deadline's optional name. A named
+ * deadline speaks `` `${N}_deadline` ``; an unnamed one speaks the bare
+ * `"deadline_exceeded"` literal, which is what `DeadlineExceeded` with no type
+ * argument still means — so every machine wired before the name existed keeps
+ * the exact type it had.
+ */
+type DeadlineMsgType<N extends string | undefined> = N extends string ? `${N}_deadline` : "deadline_exceeded";
+/**
+ * Build a deadline literal. Pure data — no clock read, no timer; the timer
+ * is armed later by the `deadline` runner. `id` is branded via `subId(...)` so
  * accidental raw-string drift fails at the type level (invariant 7).
  *
- * Return the result directly from `subscriptions(state)` while the deadline
- * should be armed; drop it (return `[]`, or stop returning this id) to disarm —
- * the reconcile pass calls the cleanup, clearing the pending timer before it
- * fires. That is the "cancel on state exit" lifecycle, identical to
- * `fromTimeout`'s.
+ * List it from a battery's `subs(slice)` while the deadline should be armed;
+ * drop it to disarm — the engine restarts the `deadline` Sub, whose cleanup
+ * clears the pending timer before it fires. That is the "cancel on state exit"
+ * lifecycle.
  *
- * @param id   Stable identity for this deadline. Same `id` across transitions =
- *             same armed timer (no churn). Use distinct ids for distinct
- *             deadlines on the same machine.
+ * @param id   Identity for this deadline, echoed on the Msg it fires. Use
+ *             distinct ids for distinct deadlines on the same machine.
  * @param atMs Absolute target in epoch milliseconds (e.g. `Date.now() + 900_000`
  *             for a 15-minute guard, or a persisted `expiresAt`).
  * @param opts Optional additive fields folded onto the Sub literal (see
@@ -265,17 +163,16 @@ type DeadlineExceeded = {
  *             optionality is the future-proofing seam — extending the shape
  *             never breaks an existing `deadlineSub(id, atMs)` call site.
  */
-declare function deadlineSub(id: string, atMs: number, opts?: DeadlineOpts): DeadlineSub;
+declare function deadlineSub<N extends string | undefined = undefined>(id: string, atMs: number, opts?: DeadlineOpts<N>): DeadlineSub<N>;
 /**
  * The host-plugged timer backing. Given the deadline's stable `id`, its
  * absolute `atMs`, and the Msg to fire, arm the platform-appropriate timer
  * (DO alarm registry, `setTimeout`, fake timer) and return a cleanup that
  * cancels the pending fire.
  *
- * `id` is the Sub's reconcile id — a registry-backed host (the DO alarm slot)
- * keys its entry on `id` so the cleanup deletes the EXACT entry the substrate
- * reconciled. A `setTimeout`-backed host ignores `id` (the closure holds the
- * handle).
+ * `id` is the deadline's own id — a registry-backed host (the DO alarm slot)
+ * keys its entry on `id` so the cleanup deletes the EXACT entry it armed. A
+ * `setTimeout`-backed host ignores `id` (the closure holds the handle).
  *
  * The host computes the gap itself: `atMs - Date.now()` is the REMAINING time.
  * On a host that just rehydrated after hibernation that gap is the shrunken
@@ -285,61 +182,235 @@ declare function deadlineSub(id: string, atMs: number, opts?: DeadlineOpts): Dea
  */
 type ArmTimer<M> = (id: SubId, atMs: number, msg: M, dispatch: (msg: M) => void) => () => void;
 /**
- * Build the `subscribe["deadline"]` cell from a host-plugged `armTimer`. This
- * module owns the Sub shape, the anchor, and the Msg; the HOST owns what backs
- * the timer. The returned handler reads `id` + `atMs` off the Sub, builds the
- * `deadlineExceeded(...)` Msg, and hands all three to `armTimer`.
+ * Build the `deadline` runner from a host-plugged `armTimer`. This module owns
+ * the deadline shape, the anchor, and the Msg; the HOST owns what backs the
+ * timer. The runner arms every deadline in the Sub's `deps` list — reading
+ * `id` + `atMs`, building the `deadlineExceeded(...)` Msg and handing all three
+ * to `armTimer` — and its cleanup cancels them all.
  *
  * Use it when `setTimeout` is the wrong backing — most concretely a Durable
  * Object, which hibernates and must register a `do_alarm` instead:
  *
- *   subscribe: {
- *     deadline: subscribeWith((id, atMs, msg, dispatch) =>
- *       alarms.register(id, atMs, () => dispatch(msg)),
- *     ),
- *   }
+ *   run(machine, {
+ *     subscribe: {
+ *       deadline: subscribeWith((id, atMs, msg, dispatch) =>
+ *         alarms.register(id, atMs, () => dispatch(msg)),
+ *       ),
+ *     },
+ *   })
  *
  * For the `setTimeout` default, use {@link subscribeDeadline} — it is exactly
  * `subscribeWith(setTimeoutArmTimer())`, so there is one deadline surface and
  * one anchor, not a second one per host.
  */
-declare function subscribeWith(armTimer: ArmTimer<DeadlineExceeded>): SubscribeHandler<DeadlineSub, DeadlineExceeded, unknown>;
+declare function subscribeWith<N extends string | undefined = undefined>(armTimer: ArmTimer<DeadlineExceeded<N>>): (sub: DeadlinesSub<N>, ctx: unknown, dispatch: (msg: DeadlineExceeded<N>) => void) => Dispose;
 /**
  * The `setTimeout` timer backing — for node / browser / any host whose timer is
  * a plain `setTimeout`. Arms for the REMAINING time (`max(0, atMs - Date.now())`,
  * floored at 0 so an already-past deadline fires on the NEXT tick rather than
  * synchronously inside the reconcile pass), so a deadline re-derived after a
- * rehydrate fires at the original instant, not a fresh full window.
- *
- * Composes on `fromTimeout` rather than redrawing `setTimeout` /
- * `clearTimeout`: this package has ONE timer lifecycle, and the arm-timer seam
- * plugs into it instead of forking it. A hibernating host does NOT use this —
- * it plugs its own `armTimer` (a `do_alarm` registration) into
- * {@link subscribeWith}.
+ * rehydrate — or re-armed by a restart — fires at the original instant, not a
+ * fresh full window. A hibernating host does NOT use this — it plugs its own
+ * `armTimer` (a `do_alarm` registration) into {@link subscribeWith}.
  */
-declare function setTimeoutArmTimer(): ArmTimer<DeadlineExceeded>;
+declare function setTimeoutArmTimer<N extends string | undefined = undefined>(): ArmTimer<DeadlineExceeded<N>>;
 /**
- * The `subscribe["deadline"]` handler for the DEFAULT `setTimeout` backing. Arms a
- * one-shot timer for the remaining delay `max(0, atMs - Date.now())` and
- * dispatches `deadlineExceeded(...)` when it fires; returns a cleanup that
- * clears the pending timer.
+ * The `deadline` runner for the DEFAULT `setTimeout` backing. Arms a one-shot
+ * timer per listed deadline for its remaining delay `max(0, atMs - Date.now())`
+ * and dispatches `deadlineExceeded(...)` when each fires; the cleanup clears
+ * every pending timer.
  *
  * It is `subscribeWith(setTimeoutArmTimer())` — the default backing named, not
  * a separate implementation, so the host-plugged path and the default path can
  * never disagree about the anchor.
  *
- * Assign directly to a `Subscribe` handler:
+ *   run(machine, { subscribe: { deadline: subscribeDeadline } })
  *
- *   subscribe: {
- *     deadline: subscribeDeadline,
- *   }
+ * Generic in the deadline's name so ONE runner serves every knob in a machine:
+ * the tag it dispatches is read off each deadline's own `name`, so a machine
+ * listing a named knob's deadlines beside an unnamed one's wires this once.
  */
-declare const subscribeDeadline: SubscribeHandler<DeadlineSub, DeadlineExceeded, unknown>;
+declare const subscribeDeadline: <N extends string | undefined = undefined>(sub: DeadlinesSub<N>, ctx: unknown, dispatch: (msg: DeadlineExceeded<N>) => void) => Dispose;
 /**
  * Construct the Msg the deadline dispatches. Exported so consumers can build /
- * assert the same shape (and so the subscribe cell and tests share one
+ * assert the same shape (and so the runner and tests share one
  * constructor rather than two literals that can drift).
  */
-declare function deadlineExceeded(id: string, atMs: number): DeadlineExceeded;
+declare function deadlineExceeded<N extends string | undefined = undefined>(id: string, atMs: number, name?: N): DeadlineExceeded<N>;
+/**
+ * The one place the named tag is spelled. `undefined` → the bare
+ * `"deadline_exceeded"` literal; a name → `` `${name}_deadline` ``. Exported so
+ * a consumer keying a reducer cell off a named deadline derives the key from
+ * the same function the Sub dispatches through, instead of re-spelling the
+ * template and drifting.
+ */
+declare function deadlineMsgType<N extends string | undefined>(name?: N): DeadlineMsgType<N>;
+/**
+ * The built-in `timer` Sub's deps for the SOONEST deadline in `list`, counted
+ * from `nowMs`; `null` when the list is empty (no timer armed).
+ *
+ * This is how a battery arms a whole deadline list through the engine's
+ * built-in `timer` instead of a `deadline` runner: a machine declares ONE
+ * `{ type: "timer", deps: (s) => nextTimer(list(s), clock(s)) }` entry. The
+ * timer fires the soonest deadline's `DeadlineExceeded` Msg; the transition it
+ * causes drops that deadline from the list, and the next soonest is armed.
+ *
+ * `nowMs` is the instant the list was last computed against — the battery's
+ * own record of its latest transition, never a clock read (invariant 2). The
+ * countdown is `atMs - nowMs`, clamped at `0`, and because `ms` is part of the
+ * deps, every new `nowMs` restarts the countdown from that instant. PURE.
+ */
+declare function nextTimer<N extends string | undefined = undefined>(list: readonly DeadlineSub<N>[], nowMs: number): TimerDeps<DeadlineExceeded<N>> | null;
+
+/**
+ * internal/resilience/cache — a TTL cache as pure state, PLUS a periodic eviction Sub.
+ *
+ * Same pure-state-ops shape as `../../idempotency/` and
+ * `../../work-queue/ops.ts`: a state type plus pure transition functions. Host-
+ * agnostic by construction — no `Date.now()`, no timers, no I/O inside the ops.
+ * The caller injects the clock (`nowMs`) and folds the result through its own
+ * reducer, keeping the store inside TEA's invariant 2 (transitions are pure:
+ * same inputs → same outputs) so a consumer can exercise it with `replay`
+ * without a fake clock.
+ *
+ * Every op returns a NEW cache value and never mutates its input (invariant 1 —
+ * state is a value, not a place). `get` / `has` are read-shaped; `set` /
+ * `remove` / `evictExpired` return a new cache.
+ *
+ * **Distinct from `/idempotency`.** Both are TTL-bounded key maps, but they
+ * answer different questions and so carry different shapes:
+ *
+ *   - `/idempotency` is DEDUPE-focused — "have I already processed this key?"
+ *     TTL is a single store-level policy (`ttlMs`), each entry stores the
+ *     `atMs` it was remembered at, and expiry is derived (`now - atMs >=
+ *     ttlMs`). It carries an `order` ledger + `capacity` because the use case
+ *     (webhook receivers, retried messages) needs bounded LRU eviction.
+ *   - `/cache` is RETRIEVAL-focused — "what is the value for this key right
+ *     now?" TTL is set PER ENTRY at write time: `set(key, value, nowMs,
+ *     ttlMs)` bakes the absolute `expiresAtMs = nowMs + ttlMs` into the entry.
+ *     Different keys can carry different lifetimes (a hot key cached for 1s, a
+ *     cold one for 1h) — the dimension idempotency's single store-level
+ *     `ttlMs` cannot express. No `order`, no `capacity`: a cache bounds itself
+ *     by TTL + periodic eviction, not by LRU count.
+ *
+ * The eviction Sub is the "eviction is a Msg" half: a `setInterval`-shaped Sub
+ * (composed directly on `fromInterval`, from `src/subs/`) that periodically
+ * dispatches a `cache_evict` Msg the consumer's reducer handles by calling
+ * `evictExpired`. Time still never enters the reducer — the Sub fires the Msg,
+ * the reducer reads `nowMs` off the Msg (the consumer stamps it at the Sub
+ * boundary), and `evictExpired` does the pure drop.
+ *
+ * Internal to the package (`src/internal/resilience/`), not a published
+ * subpath (#46); same one-shape-per-module rule as `work-queue`, `idempotency`,
+ * and `rate-limit`.
+ */
+
+/**
+ * A cached entry: the `value` and the absolute clock reading `expiresAtMs` it
+ * expires at. Unlike `/idempotency`'s entry (which stores `atMs` and derives
+ * expiry from a store-level `ttlMs`), the expiry instant is baked in at write
+ * time — so per-entry TTLs are a first-class capability. Both fields are plain
+ * data so the whole cache is trivially JSON-serializable into a consumer's
+ * `Store<S>`.
+ */
+interface CacheEntry<V> {
+    readonly value: V;
+    readonly expiresAtMs: number;
+}
+/**
+ * The cache: a map of `key → entry`. No `order` ledger and no `capacity` (cf.
+ * `/idempotency`) — a TTL cache bounds itself by expiry + periodic eviction,
+ * not by LRU count. Each entry carries its own `expiresAtMs`, so the cache
+ * needs no store-level TTL policy field.
+ */
+interface TtlCache<V> {
+    readonly entries: Readonly<Record<string, CacheEntry<V>>>;
+}
+/** Create an empty cache. */
+declare function initCache<V>(): TtlCache<V>;
+/**
+ * The cached `value` for `key` iff present AND unexpired at `nowMs`, else
+ * `undefined`. An expired entry reads as absent even though it is physically
+ * still in `entries` until the next `evictExpired` (or an overwriting `set`)
+ * drops it. PURE — reads only, never mutates.
+ */
+declare function get<V>(cache: TtlCache<V>, key: string, nowMs: number): V | undefined;
+/**
+ * True iff `key` is present AND unexpired at `nowMs`. The boolean sibling of
+ * `get` for callers that only need presence, not the value. PURE.
+ */
+declare function has<V>(cache: TtlCache<V>, key: string, nowMs: number): boolean;
+/**
+ * Write `key → value` with an absolute expiry of `nowMs + ttlMs`. Re-`set`ting
+ * an existing key overwrites both the value and the expiry — the TTL clock
+ * restarts from the new `nowMs`. PURE — returns a new cache; the input is
+ * untouched (a fresh shallow copy of `entries`).
+ */
+declare function set<V>(cache: TtlCache<V>, key: string, value: V, nowMs: number, ttlMs: number): TtlCache<V>;
+/**
+ * Drop `key` regardless of expiry. PURE — returns a new cache; the input is
+ * untouched. Removing an absent key returns an equivalent cache (the shallow
+ * copy still happens, but no entry is dropped).
+ */
+declare function remove<V>(cache: TtlCache<V>, key: string): TtlCache<V>;
+/**
+ * Physically drop every entry expired at `nowMs` (`nowMs >= expiresAtMs`).
+ * Returns a NEW cache with the survivors. This is the pure work the eviction
+ * Sub's `cache_evict` Msg triggers — `get` / `has` already treat expired
+ * entries as absent, so eviction is purely a memory-reclaim pass, not a
+ * correctness one. PURE — the input cache is never mutated.
+ */
+declare function evictExpired<V>(cache: TtlCache<V>, nowMs: number): TtlCache<V>;
+/**
+ * The Msg the eviction Sub dispatches each tick. `id` is the cache's name so a
+ * consumer with multiple caches can route the tick to the matching cache. The
+ * reducer reads `Date.now()`-free time by stamping `nowMs` itself at the Sub
+ * boundary if needed; the canonical reducer cell is
+ * `cache_evict: (s) => [{ ...s, cache: evictExpired(s.cache, nowMs) }, []]`.
+ */
+interface CacheEvictMsg {
+    readonly type: "cache_evict";
+    readonly id: string;
+}
+/** Construct a `cache_evict` Msg for the cache identified by `id`. */
+declare function cacheEvictMsg(id: string): CacheEvictMsg;
+/**
+ * The `deps` of an eviction Sub: which cache it ticks for (`name`, echoed as
+ * the Msg's `id`) and the tick period (`intervalMs`, which `fromInterval`
+ * reads).
+ */
+type CacheEvictionDeps = {
+    readonly name: string;
+    readonly intervalMs: number;
+};
+/**
+ * The running eviction Sub: a `setInterval`-shaped Sub whose `deps` carry the
+ * cache's name and tick period. `type: "cache"` is the lowercase source-noun
+ * Sub convention (canon §2.5 / naming-style).
+ */
+type CacheEvictionSub = Sub<"cache", CacheEvictionDeps>;
+/**
+ * The `subs` entry for an eviction tick on the cache named `name`, every
+ * `everyMs`. It is on for the machine's life:
+ *
+ *   subs: [cacheEvictionSub("session-cache", 30_000)],
+ *   // run(machine, { subscribe: { cache: cacheEvictionSubscribe } })
+ *
+ * The engine keys the Sub on its `deps`, so a machine that declares the same
+ * name and period keeps one running interval, and a changed period restarts
+ * it at the new one.
+ */
+declare function cacheEvictionSub(name: string, everyMs: number): DepKeyedSub<unknown, CacheEvictionSub>;
+/**
+ * The `cache` runner for the eviction Sub. Hand it to `run`:
+ *
+ *   run(machine, { subscribe: { cache: cacheEvictionSubscribe } })
+ *
+ * Composed directly on `fromInterval` — it owns the `setInterval` /
+ * `clearInterval` lifecycle; this runner only pins the Msg the tick dispatches
+ * (`cacheEvictMsg(sub.deps.name)`). The cleanup `fromInterval` returns stops
+ * the interval when the Sub stops.
+ */
+declare const cacheEvictionSubscribe: SubscribeHandler<CacheEvictionSub, CacheEvictMsg, unknown>;
 
-export { type ArmTimer as A, type CacheEvictionSub as C, type DeadlineExceeded as D, type TtlCache as T, type DeadlineSub as a, deadlineSub as b, type CacheEvictMsg as c, deadlineExceeded as d, type CacheEntry as e, type DeadlineOpts as f, cacheEvictMsg as g, cacheEvictionSub as h, cacheEvictionSubscribe as i, evictExpired as j, get as k, has as l, initCache as m, set as n, setTimeoutArmTimer as o, subscribeWith as p, remove as r, subscribeDeadline as s };
+export { type ArmTimer as A, type CacheEvictionSub as C, type DeadlineExceeded as D, type TtlCache as T, type DeadlineSub as a, type DeadlinesSub as b, deadlineSub as c, deadlineExceeded as d, deadlinesSub as e, type CacheEvictMsg as f, type CacheEntry as g, type CacheEvictionDeps as h, type DeadlineMsgType as i, type DeadlineOpts as j, cacheEvictMsg as k, cacheEvictionSub as l, cacheEvictionSubscribe as m, deadlineMsgType as n, deadlines as o, evictExpired as p, get as q, has as r, subscribeDeadline as s, initCache as t, nextTimer as u, remove as v, set as w, setTimeoutArmTimer as x, subscribeWith as y };