@demlik/tea 0.13.0 → 0.15.0

package/dist/index-CA_7I5g9.d.ts

@@ -0,0 +1,806 @@
+import { a as CmdOf, b as CmdDef, i as NoCtx, C as Cmd } from './core-DnzqWy6u.js';
+import { RetryState, AnyRetryPolicy } from './retry-backoff/index.js';
+import { T as TtlCache, D as DeadlineExceeded, a as DeadlineSub, s as subscribeDeadline } from './index-HSYgG2Yt.js';
+
+/**
+ * @packageDocumentation
+ * internal/resilience/circuit-breaker — per-target failure tracking as pure state + ops.
+ *
+ * Same shape as `../../work-queue/ops.ts`, `../rate-limit/`, and
+ * `../../idempotency/`: a state type plus pure transition functions.
+ * Host-agnostic by construction — no `Date.now()`, no timers, no I/O. The
+ * caller injects the clock (`nowMs`) and wires the result into its own reducer
+ * / interpret. This keeps the breaker inside TEA's invariant 2 (transitions are
+ * pure: same inputs → same outputs, no `Date.now`) so a consumer can fold it
+ * through `update` and exercise it with `replay` / the pbt fold without a fake
+ * clock.
+ *
+ * Every op returns a NEW state value and never mutates its input (invariant 1 —
+ * state is a value, not a place). `canPass` returns a `[next, allowed]` tuple so
+ * the caller branches on the decision while threading the advanced state forward
+ * — same convention as `rate-limit`'s `tryConsume` / `record`. `onSuccess` /
+ * `onFailure` are the outcome-recording transitions the caller folds in once the
+ * guarded call resolves.
+ *
+ * ## The phase machine
+ *
+ * A circuit breaker guards a fallible downstream target (an HTTP backend, a DB,
+ * a flaky tool call). Instead of hammering a target that is already failing, it
+ * trips OPEN after enough failures and fast-fails subsequent calls for a
+ * cooldown, then probes with a few trial calls before fully closing again.
+ * Three phases, each carrying ONLY its own data so impossible states are
+ * unrepresentable (pattern 11):
+ *
+ *   - **closed** — the healthy steady state. Calls pass through. Carries
+ *     `failures`: the count of *consecutive* failures since the last success.
+ *     A success resets it to 0; the `failureThreshold`-th failure trips the
+ *     breaker OPEN. Only `closed` has a failure counter — `open` and
+ *     `half_open` don't, because in those phases the count is irrelevant
+ *     (the breaker has already tripped / is already probing).
+ *
+ *   - **open** — the tripped state. All calls fast-fail (no downstream load).
+ *     Carries `openedAtMs`: the clock reading at which the breaker tripped.
+ *     `canPass` compares `nowMs - openedAtMs` against `cooldownMs` to decide
+ *     when to start probing. Only `open` carries a timestamp — neither other
+ *     phase is timing anything.
+ *
+ *   - **half_open** — the probing state. A limited number of trial calls are
+ *     allowed through to test whether the target has recovered. Carries
+ *     `probes`: the count of probes admitted so far this probing round.
+ *     `canPass` admits while `probes < halfOpenMaxProbes`, then fast-fails the
+ *     rest (so a slow target can't be flooded by every queued caller at once).
+ *     A probe success closes the breaker; a probe failure re-opens it (and
+ *     resets the cooldown clock). Only `half_open` counts in-flight probes.
+ *
+ * ### Transition table
+ *
+ * Rows are the current phase; columns are the event. `→` denotes the next
+ * phase; `self` means unchanged. `nowMs` is the injected clock.
+ *
+ * | from \ event | onSuccess      | onFailure                              | canPass (→ allowed?)                                                                 |
+ * | ------------ | -------------- | -------------------------------------- | ------------------------------------------------------------------------------------ |
+ * | closed       | closed(0)      | failures+1; trip → open(nowMs) at thr. | self → true (always)                                                                  |
+ * | open         | self *(¹)*     | self                                   | elapsed ≥ cooldown → half_open(1), true; else self → false                            |
+ * | half_open    | → closed(0)    | → open(nowMs) (probe failed)           | probes < max → half_open(probes+1), true; else self → false                          |
+ *
+ * *(¹)* `onSuccess` on `open` "shouldn't happen": no call was admitted while
+ * open, so no success can be reported for one. We leave the state unchanged
+ * rather than throw — the breaker is a coordination aid, not a correctness
+ * gate, and a spurious success report (e.g. a late-arriving result from before
+ * the trip) must not silently un-trip the breaker. `onFailure` on `open` is
+ * likewise a no-op: the breaker is already tripped; the `open` clock is anchored
+ * at the trip, not bumped by late failures.
+ *
+ * ### The probe-admission asymmetry
+ *
+ * Entering `half_open` happens inside `canPass`, not `onSuccess` / `onFailure`,
+ * because the cooldown is a *time* condition and only `canPass` reads the clock
+ * against `openedAtMs`. The first `canPass` after the cooldown elapses both
+ * transitions the phase AND admits the probe (`[half_open(1), true]`) — one
+ * caller drives the recovery attempt. Subsequent `canPass` calls in the same
+ * round admit up to `halfOpenMaxProbes` total, then fast-fail until a probe
+ * resolves and `onSuccess` / `onFailure` moves the phase out of `half_open`.
+ *
+ * This module is a textbook three-state machine — a clean `/machine-viz` demo.
+ *
+ * Internal to the package (`src/internal/resilience/`), not a published
+ * subpath (#46); same one-shape-per-module rule as `work-queue`, `rate-limit`,
+ * and `idempotency`.
+ */
+/**
+ * Circuit-breaker policy — pure configuration, no mutable state. One policy is
+ * shared across all the calls guarded by one logical breaker (often a
+ * module-scope const). `CircuitState` carries the mutable counts; this carries
+ * the thresholds those counts are compared against.
+ */
+interface CircuitPolicy {
+    /**
+     * Consecutive failures in `closed` that trip the breaker `open`. The
+     * `failureThreshold`-th failure is the one that trips — with a threshold of
+     * 5, the breaker survives 4 failures and opens on the 5th.
+     */
+    readonly failureThreshold: number;
+    /**
+     * How long the breaker stays `open` before `canPass` starts admitting
+     * probes, in milliseconds. Measured from `openedAtMs`; the cutoff is
+     * half-open (`elapsed >= cooldownMs` admits), matching `rate-limit` /
+     * `idempotency` window edges — a breaker opened at `t` first probes at
+     * `t + cooldownMs`.
+     */
+    readonly cooldownMs: number;
+    /**
+     * How many probe calls `half_open` admits before fast-failing the rest of
+     * the round. Caps the load on a recovering target — a single slow probe
+     * can't be joined by every queued caller. The round ends when a probe
+     * resolves: success closes the breaker, failure re-opens it.
+     */
+    readonly halfOpenMaxProbes: number;
+}
+/**
+ * Sensible defaults: trip after 5 consecutive failures, cool down for 30s,
+ * admit a single probe before deciding. Tuned for guarding a network backend;
+ * override per call site rather than mutating this shared const.
+ */
+declare const defaultCircuitPolicy: CircuitPolicy;
+/**
+ * The breaker's phase. A discriminated union on `phase` so each phase carries
+ * ONLY its own data and impossible combinations are unrepresentable (pattern
+ * 11): there is no state with both a failure count AND an open timestamp,
+ * because such a state is meaningless. `phase` is the discriminant; every field
+ * is `readonly` so the whole value is trivially JSON-serializable into a
+ * consumer's `Store<S>` and safe to thread through a pure reducer.
+ *
+ *   - `closed`    carries `failures`   — consecutive failures since last success.
+ *   - `open`      carries `openedAtMs` — clock reading when it tripped.
+ *   - `half_open` carries `probes`     — probes admitted this round.
+ */
+type CircuitState = {
+    readonly phase: "closed";
+    readonly failures: number;
+} | {
+    readonly phase: "open";
+    readonly openedAtMs: number;
+} | {
+    readonly phase: "half_open";
+    readonly probes: number;
+};
+/** The starting state: closed with zero recorded failures. */
+declare function initCircuit(): CircuitState;
+/**
+ * Record a successful guarded call. PURE — returns a new state; the input is
+ * never mutated.
+ *
+ *   - `closed`    → reset `failures` to 0 (a success breaks the consecutive run).
+ *   - `half_open` → the probe succeeded; the target has recovered → `closed`.
+ *   - `open`      → unchanged. A success "shouldn't happen" while open (no call
+ *                   was admitted to produce one); a late/spurious success must
+ *                   not silently un-trip the breaker. See module header note ¹.
+ */
+declare function onSuccess(state: CircuitState, _policy: CircuitPolicy): CircuitState;
+/**
+ * Record a failed guarded call. PURE — returns a new state; the input is never
+ * mutated. `nowMs` is the injected clock, stamped onto the `open` phase when the
+ * breaker trips so `canPass` can measure the cooldown later.
+ *
+ *   - `closed`    → `failures + 1`; if that reaches `failureThreshold`, trip to
+ *                   `open(nowMs)`. The threshold-th failure is the one that trips.
+ *   - `half_open` → the probe failed; the target is still unhealthy →
+ *                   `open(nowMs)`, restarting the cooldown clock so a fresh
+ *                   cooldown elapses before the next probe round.
+ *   - `open`      → unchanged. The breaker is already tripped; the `open` clock
+ *                   is anchored at the original trip, not bumped by late
+ *                   failures. See module header note ¹.
+ */
+declare function onFailure(state: CircuitState, policy: CircuitPolicy, nowMs: number): CircuitState;
+/**
+ * Decide whether a call may pass, advancing the phase as a side effect of the
+ * decision. PURE — returns `[next, allowed]`; the input is never mutated.
+ * Branch on the boolean, thread the state forward regardless:
+ *
+ *   const [c1, allowed] = canPass(state.circuit, policy, nowMs);
+ *   if (!allowed) return [{ ...state, circuit: c1 }, [fastFailCmd]];
+ *   return [{ ...state, circuit: c1 }, [doGuardedCallCmd]];
+ *
+ *   - `closed`    → `[state, true]` — always passes; failures are recorded by
+ *                   `onFailure` once the call resolves, not gated here.
+ *   - `open`      → if `nowMs - openedAtMs >= cooldownMs` the cooldown has
+ *                   elapsed → enter `half_open` and admit this caller as the
+ *                   first probe: `[half_open(1), true]`. Otherwise still cooling
+ *                   down → `[state, false]` (fast-fail, no downstream load).
+ *   - `half_open` → admit while `probes < halfOpenMaxProbes`, incrementing the
+ *                   count: `[half_open(probes+1), true]`. Once the cap is hit →
+ *                   `[state, false]` until a probe resolves and `onSuccess` /
+ *                   `onFailure` moves the phase out of `half_open`.
+ *
+ * Entering `half_open` lives here (not in `onSuccess` / `onFailure`) because the
+ * cooldown is a time condition and only `canPass` reads `nowMs` against
+ * `openedAtMs`. See the module header's probe-admission note.
+ */
+declare function canPass(state: CircuitState, policy: CircuitPolicy, nowMs: number): readonly [CircuitState, boolean];
+
+/**
+ * internal/resilience/rate-limit — two rate limiters as pure state + ops.
+ *
+ * Same shape as `../../work-queue/ops.ts`: a state type plus pure
+ * transition functions. Host-agnostic by construction — no `Date.now()`, no
+ * timers, no I/O. The caller injects the clock (`nowMs`) and wires the result
+ * into its own reducer / interpret. This keeps the limiters inside TEA's
+ * invariant 2 (transitions are pure: same inputs → same outputs, no `Date.now`)
+ * so a consumer can fold them through `update` and exercise them with `replay`
+ * / the pbt fold without a fake clock.
+ *
+ * Every op returns a NEW state value and never mutates its input (invariant 1 —
+ * state is a value, not a place). The `tryConsume` / `record` ops return a
+ * `[next, ok]` tuple so the caller branches on the decision while threading the
+ * advanced state forward; `refill` / `remaining` are read-shaped helpers.
+ *
+ * Two complementary algorithms, picked by the cost the caller wants to pay:
+ *
+ *   - **Token bucket** — O(1) state (four numbers), smooths bursts against a
+ *     steady refill rate. Allows a burst up to `capacity`, then throttles to
+ *     `refillPerSec`. Cheapest; the default choice.
+ *   - **Sliding window log** — O(limit) state (one timestamp per in-window
+ *     hit), exact "no more than `limit` events per `windowMs`". Pay the memory
+ *     for precise window edges when a token bucket's continuous refill would
+ *     let through too many at a boundary.
+ *
+ * Internal to the package (`src/internal/resilience/`), not a published
+ * subpath (#46); same one-shape-per-module rule as `work-queue` and `do`.
+ */
+/**
+ * A token bucket: `tokens` of `capacity` available now, replenished at
+ * `refillPerSec` tokens per second. `lastRefillMs` is the clock reading at
+ * which `tokens` was last computed — `refill` advances it. All four fields are
+ * plain numbers so the whole bucket is trivially JSON-serializable into a
+ * consumer's `Store<S>`.
+ */
+interface TokenBucket {
+    readonly tokens: number;
+    readonly capacity: number;
+    readonly refillPerSec: number;
+    readonly lastRefillMs: number;
+}
+/**
+ * Create a full bucket. Starts at `capacity` tokens (the conventional "a fresh
+ * limiter lets the first burst through" behavior) and stamps `lastRefillMs`
+ * with the caller's clock so the first `refill` measures elapsed time from
+ * boot, not from epoch 0.
+ */
+declare function initBucket(capacity: number, refillPerSec: number, nowMs: number): TokenBucket;
+/**
+ * Add the tokens accrued since `lastRefillMs`, clamped to `capacity`, and
+ * advance `lastRefillMs` to `nowMs`. PURE — returns a new bucket; the input is
+ * untouched.
+ *
+ * A `nowMs` at or before `lastRefillMs` (clock not advanced, or skewed
+ * backwards) adds a non-positive amount; `Math.max(0, …)` floors the elapsed
+ * term so a backwards clock can never *remove* tokens. `lastRefillMs` still
+ * advances to `nowMs` so the bucket tracks the latest reading the caller
+ * presented — the next forward step measures from there, not from a stale
+ * future timestamp.
+ */
+declare function refill(bucket: TokenBucket, nowMs: number): TokenBucket;
+/**
+ * Refill against `nowMs`, then attempt to take `n` tokens (default 1).
+ *
+ * On success returns `[next, true]` with `n` subtracted; on failure returns
+ * `[refilled, false]` — the refilled bucket (so the caller keeps the advanced
+ * clock + accrued tokens) with no tokens spent. Branch on the boolean, thread
+ * the bucket forward regardless:
+ *
+ *   const [b1, ok] = tryConsume(bucket, nowMs);
+ *   return ok ? [{ ...state, bucket: b1 }, [doWork]] : [{ ...state, bucket: b1 }, []];
+ *
+ * PURE — input bucket is never mutated.
+ */
+declare function tryConsume(bucket: TokenBucket, nowMs: number, n?: number): readonly [TokenBucket, boolean];
+/**
+ * A sliding-window log: the timestamps of every hit still inside the trailing
+ * `windowMs`, capped at `limit` events per window. `hits` is `readonly` and
+ * kept oldest-first (pruning slices the stale prefix off the front, recording
+ * appends to the back), so the array is its own sorted index. Exact at the
+ * window edge — unlike a token bucket's continuous refill, a hit leaves the
+ * count the instant it ages past `windowMs`.
+ */
+interface SlidingWindow {
+    readonly hits: readonly number[];
+    readonly windowMs: number;
+    readonly limit: number;
+}
+/** Create an empty window. No hits recorded yet. */
+declare function initWindow(windowMs: number, limit: number): SlidingWindow;
+/**
+ * Prune hits older than `nowMs - windowMs`, then record `nowMs` if there is
+ * room. Returns `[next, true]` with the hit appended when `hits.length < limit`
+ * after pruning, else `[pruned, false]` — the pruned window (capacity recovers
+ * as old hits age out) with nothing appended.
+ *
+ * The cutoff is half-open (see {@link prune}): a hit exactly `windowMs` old is
+ * pruned, so a hit recorded at `t` no longer counts at `t + windowMs`. That
+ * makes the window's capacity fully recover `windowMs` after the last hit, the
+ * behavior tests pin.
+ *
+ * PURE — input window is never mutated; `hits` is rebuilt by `filter` +
+ * spread.
+ */
+declare function record(window: SlidingWindow, nowMs: number): readonly [SlidingWindow, boolean];
+/**
+ * How many more hits `record` would accept at `nowMs` without blocking —
+ * `limit` minus the live (post-prune) hit count, floored at 0. Read-only: it
+ * prunes a local copy to answer but returns no new window. Use it to render a
+ * "N requests remaining" affordance without committing a hit.
+ */
+declare function remaining(window: SlidingWindow, nowMs: number): number;
+
+/** Circuit-breaker knob — only the two numbers a consumer ever tunes. */
+interface CircuitConfig {
+    /** Consecutive failures that trip the breaker open. */
+    readonly threshold: number;
+    /** How long the breaker stays open before admitting a probe, in ms. */
+    readonly cooldownMs: number;
+    /**
+     * Probes admitted in `half_open` before fast-failing the rest of the round.
+     * Defaults to 1 (a single probe decides recovery) — matches the circuit-
+     * breaker module's `defaultCircuitPolicy`.
+     */
+    readonly halfOpenMaxProbes?: number;
+}
+/** Token-bucket rate-limit knob. */
+interface RateLimitConfig {
+    /** Burst size — the bucket starts full at `capacity`. */
+    readonly capacity: number;
+    /** Steady-state refill rate, tokens per second. */
+    readonly refillPerSec: number;
+}
+/** Per-entry TTL cache knob. */
+interface CacheConfig {
+    /** How long a cached success stays fresh, in ms. */
+    readonly ttlMs: number;
+}
+/**
+ * Overall deadline knob — a budget of IN-PROCESS time per in-flight call.
+ *
+ * The budget is charged in elapsed time this process actually observed, not by
+ * a position on the host's wall clock. Time in which no process exists — a DO
+ * eviction, a crash between attempts, a redeploy — is NOT charged: `resume`
+ * re-anchors every live call's charging clock, so downtime lands outside every
+ * segment. A timeout therefore means "the tool took too long", never "the host
+ * was away too long" (#144).
+ */
+interface DeadlineConfig {
+    /** Budget of in-process time from the moment a call starts, in ms. */
+    readonly ms: number;
+}
+/**
+ * The family every unnamed knob speaks: `resilient_run` / `resilient_ok` /
+ * `resilient_err`. Identical to the `MsgType.Resilient*` literals, which stay
+ * the vocabulary of every knob that passes no name.
+ */
+declare const DEFAULT_RESILIENT_NAME = "resilient";
+type DefaultResilientName = typeof DEFAULT_RESILIENT_NAME;
+/** The run Cmd's `type` for the `N` family. */
+type ResilientRunType<N extends string> = `${N}_run`;
+/** The success settle Msg's `type` for the `N` family. */
+type ResilientOkType<N extends string> = `${N}_ok`;
+/** The failure settle Msg's `type` for the `N` family. */
+type ResilientErrType<N extends string> = `${N}_err`;
+/**
+ * The resilience knob. EVERY field is optional: omit a brick and its gate is
+ * skipped entirely (the slice still carries a default brick state so the shape
+ * stays uniform across configs, but the gate is never consulted). An empty
+ * config `{}` is a valid pass-through — a bare effect with no resilience at all.
+ *
+ * `N` is the knob's Msg-name family (see {@link ResilientName}); it is carried on
+ * the config so the run Cmd and the two settle Msgs are named from ONE place.
+ */
+interface ResilientConfig<N extends string = DefaultResilientName> {
+    /**
+     * What this knob's Cmd and settle Msgs are called: `<name>_run`, `<name>_ok`,
+     * `<name>_err`. Omit it and the family is `resilient` — `resilient_run` /
+     * `resilient_ok` / `resilient_err`, exactly as before this parameter existed.
+     *
+     * Name a knob when a machine mounts more than one of the resilient family.
+     * Two unnamed knobs meet in ONE `resilient_ok` cell whose payload is the union
+     * of both results, and the consumer discriminates by hand on `key` — which the
+     * type checker cannot see. Under distinct names each knob settles into its own
+     * cell, already narrowed to its own payload.
+     *
+     * The name is a value AND a type: the settle Msg types are generic in `N`, and
+     * `N` is not inferable from `I` / `R`, so an opted-in knob spells all three
+     * type arguments — `createResilientCall<In, Out, "jev">({ name: "jev", … })`.
+     * The `name` field is typed at `N`, so the two cannot drift apart.
+     */
+    readonly name?: N;
+    /**
+     * The backoff brick. Omit and a failure is terminal (no backoff, no timer).
+     *
+     * Any bound the `../retry-backoff` union admits: a count (`RetryPolicy`), a
+     * wall-clock outage budget (`DurationRetryPolicy`), or explicit
+     * `unbounded: true`. A duration bound needs no extra wiring: every path that
+     * records a failure already holds the instant it was observed as DATA —
+     * `fail`'s `msg.at` (stamped at the interpret boundary) and `gate`'s `at`
+     * (the caller's `attempt` / the retry timer's `atMs`) — so the streak clock
+     * is fed from a Msg, never from a `Date.now()` inside a verb (invariant 2).
+     */
+    readonly retry?: AnyRetryPolicy;
+    readonly circuit?: CircuitConfig;
+    readonly rateLimit?: RateLimitConfig;
+    readonly cache?: CacheConfig;
+    readonly deadline?: DeadlineConfig;
+}
+/**
+ * What is left of one call's deadline budget, and where the currently open
+ * charging segment starts. Plain data, so it persists with the rest of the slice
+ * — but the DURABLE fact is `remainingMs`, a duration, never an instant.
+ *
+ * The accounting has one rule, applied at every transition that carries a clock
+ * (`attempt`'s `at`, a settle Msg's `at`, a timer's `atMs`): charge the segment
+ * that just closed and open a new one at the same instant —
+ * `remainingMs -= at - chargingSinceMs; chargingSinceMs = at`. See {@link charge}.
+ *
+ * `chargingSinceMs` is an IN-PROCESS anchor, not a persisted deadline. It is
+ * meaningful only while the process that wrote it is alive, and `resume` re-bases
+ * it on every live call before anything reads it after a reload — which is what
+ * keeps downtime out of the budget. Nothing derives a timeout from it across a
+ * resume; the only durable answer to "how much budget is left" is `remainingMs`.
+ *
+ * `remainingMs` is `0` when the `deadline` brick is absent, which is also the
+ * "no cap armed" reading `subs` uses — a call with a real budget always has
+ * `remainingMs > 0`, because `gate` settles a call whose budget reached zero
+ * rather than letting it enter `running`.
+ */
+interface CallBudget {
+    /** In-process ms left when the open segment started. `0` = no deadline brick. */
+    readonly remainingMs: number;
+    /** The instant the open segment started, on the clock of the process that opened it. */
+    readonly chargingSinceMs: number;
+}
+/**
+ * Per-key call phase. `key` indexes a logical call; several can be in flight at
+ * once (the generalization of the example's single `url`). Discriminated on
+ * `phase` so each phase carries only its own data (pattern 11):
+ *
+ *   - `idle`          — never attempted, or fully settled and forgotten.
+ *   - `running`       — the effect Cmd is out; awaiting `succeed` / `fail`.
+ *                       Carries the deadline budget ({@link CallBudget}) and the
+ *                       last `input` so a retry can re-issue it.
+ *   - `waiting_retry` — a transient failure backed off; the retry timer is armed
+ *                       for `retryAtMs`. Carries `input` for the re-attempt, and
+ *                       the same budget — backoff is in-process time, so it is
+ *                       charged like an attempt.
+ *   - `circuit_open`  — the breaker fast-failed this attempt. Terminal for this
+ *                       call until the consumer re-attempts after cooldown.
+ *   - `succeeded`     — settled OK. `result` is the value the port produced.
+ *   - `failed`        — settled Err (out of retries, or no retry brick). `error`
+ *                       carries the last failure.
+ */
+type CallPhase<I, R> = {
+    readonly phase: "idle";
+} | {
+    readonly phase: "running";
+    readonly input: I;
+    readonly budget: CallBudget;
+} | {
+    readonly phase: "waiting_retry";
+    readonly input: I;
+    readonly retryAtMs: number;
+    readonly budget: CallBudget;
+} | {
+    readonly phase: "circuit_open";
+} | {
+    readonly phase: "succeeded";
+    readonly result: R;
+} | {
+    readonly phase: "failed";
+    readonly error: unknown;
+};
+/**
+ * The slice. `circuit` / `bucket` are SHARED across keys (one downstream target
+ * → one breaker, one bucket). `retry` and `cache` are PER KEY (each logical call
+ * has its own backoff count + cached result), as is the per-call `CallPhase`.
+ * Every field is plain data → the whole slice serializes into a `Store<S>`.
+ *
+ * `retry` / `cache` keep a default brick value even when the corresponding
+ * config brick is omitted, so the slice shape is identical regardless of which
+ * bricks the consumer enabled — the verbs simply never consult the unused brick.
+ */
+interface ResilientState<I, R> {
+    readonly circuit: CircuitState;
+    readonly bucket: TokenBucket;
+    /**
+     * Per-key backoff counter. Entries minted by `backoff` are `TimedRetryState`s
+     * (they carry the streak's `firstFailureAtMs`, since every failure path holds
+     * the observation instant); the field is typed at the `RetryState` supertype
+     * because a key that has never failed has no streak, and a slice persisted
+     * before the origin existed rehydrates without one. Still plain data.
+     */
+    readonly retry: Readonly<Record<string, RetryState>>;
+    readonly cache: TtlCache<R>;
+    readonly calls: Readonly<Record<string, CallPhase<I, R>>>;
+}
+/**
+ * The one effect this knob emits: "run the port for `key` with `input`". The
+ * consumer's `handlers(ports)` interprets it; it carries no closure — `input`
+ * is plain data (invariant 3).
+ */
+declare function runCmdDef<I, R, N extends string = DefaultResilientName>(name?: N): CmdDef<`${N}_run`, {
+    readonly key: string;
+    readonly input: I;
+}, R, {
+    readonly [detail: string]: unknown;
+    readonly _tag: "deadline_exceeded";
+} | {
+    readonly [detail: string]: unknown;
+    readonly _tag: "port_rejected";
+}, unknown>;
+type RunCmdDef<I, R, N extends string = DefaultResilientName> = ReturnType<typeof runCmdDef<I, R, N>>;
+type RunCmd<I, N extends string = DefaultResilientName> = CmdOf<RunCmdDef<I, unknown, N>>;
+/**
+ * Settle Msgs the `handlers` port dispatches back. `at` is stamped at the
+ * boundary. Both are generic in the knob's name family `N`, so two knobs named
+ * apart land in two `update` cells whose payloads are already narrowed — the
+ * `key` switch a single shared cell forces is gone.
+ */
+type SucceedMsg<R, N extends string = DefaultResilientName> = {
+    readonly type: ResilientOkType<N>;
+    readonly key: string;
+    readonly result: R;
+    readonly at: number;
+};
+type FailMsg<N extends string = DefaultResilientName> = {
+    readonly type: ResilientErrType<N>;
+    readonly key: string;
+    readonly error: unknown;
+    readonly at: number;
+};
+/**
+ * The deadline Msg tag this knob's timers dispatch, derived from its name the
+ * same way `<name>_ok` / `<name>_err` are. The DEFAULT family keeps the bare
+ * `"deadline_exceeded"` literal — that is the tag every machine wired before
+ * the name existed already handles, and `mountResilientCall` still returns a
+ * `deadline_exceeded` cell for an unnamed knob.
+ */
+type ResilientDeadlineType<N extends string = DefaultResilientName> = N extends DefaultResilientName ? "deadline_exceeded" : `${N}_deadline`;
+/**
+ * The name the deadline Sub carries for the `N` family — `undefined` for the
+ * default family (no name at all, so the bare literal is dispatched), the name
+ * itself otherwise. One conditional, so the value and {@link
+ * ResilientDeadlineType} can never disagree about which family is unnamed.
+ */
+type DeadlineNameOf<N extends string = DefaultResilientName> = N extends DefaultResilientName ? undefined : N;
+/**
+ * The retry / deadline timer Msg — a `DeadlineExceeded` whose tag is this
+ * knob's ({@link ResilientDeadlineType}), keyed by the call `key` through the
+ * Sub `id`. Bare `ResilientTimerMsg` is the default family's, so it is the same
+ * `DeadlineExceeded` it has always been.
+ */
+type ResilientTimerMsg<N extends string = DefaultResilientName> = DeadlineExceeded<DeadlineNameOf<N>>;
+/**
+ * The plain-data error a deadline-failed call settles with. A `{_tag, ...}`
+ * sentinel — NEVER a `new Error(...)` — so the slice stays JSON-serializable
+ * (Error objects round-trip to `{}` and carry a stack trace, both of which break
+ * the slice's durability invariant). `id` / `atMs` echo the timer that fired so
+ * a consumer can attribute the failure to its deadline.
+ */
+type DeadlineExceededError = {
+    readonly _tag: "deadline_exceeded";
+    readonly id: string;
+    readonly atMs: number;
+};
+/**
+ * What `handlers(ports)` returns: the interpret cell for this knob's run Cmd,
+ * under that Cmd's own name. A named knob contributes `<name>_run`, so two
+ * knobs' handler records merge into one `interpret` without either shadowing
+ * the other.
+ */
+type ResilientHandlers<I, R, N extends string = DefaultResilientName> = {
+    readonly [K in ResilientRunType<N>]: (cmd: RunCmd<I, N>, ctx: NoCtx) => Promise<SucceedMsg<R, N> | FailMsg<N>>;
+};
+/** Ports the consumer supplies to `handlers`. */
+interface ResilientPorts<I, R> {
+    /** The fallible work this knob wraps. Throws on failure → routed to `fail`. */
+    readonly run: (input: I, key: string) => Promise<R>;
+}
+/**
+ * Build a resilient-call knob from `config`. `rng` is injected for retry
+ * jitter — pass a fixed `() => 0.5` in tests to pin backoff; defaults to
+ * `Math.random` (read at the verb boundary, never inside a brick op). It is
+ * curried onto the factory rather than threaded through every verb so callers
+ * spell the determinism choice once.
+ *
+ * Returns the uniform L2 knob contract. `I` is the port input type, `R` the
+ * port result type. Consumers outside the package reach this through
+ * `withResilience` (`../with-resilience`) — see the migration map at the top
+ * of this module.
+ */
+declare function createResilientCall<I, R, N extends string = DefaultResilientName>(config: ResilientConfig<N>, rng?: () => number): {
+    name: N;
+    init: () => ResilientState<I, R>;
+    attempt: (s: ResilientState<I, R>, key: string, input: I, at: number) => readonly [ResilientState<I, R>, readonly RunCmd<I, N>[]];
+    resume: (s: ResilientState<I, R>, at: number) => ResilientState<I, R>;
+    succeed: (s: ResilientState<I, R>, key: string, msg: SucceedMsg<R, N>) => readonly [ResilientState<I, R>, readonly RunCmd<I, N>[]];
+    fail: (s: ResilientState<I, R>, key: string, msg: FailMsg<N>) => readonly [ResilientState<I, R>, readonly RunCmd<I, N>[]];
+    settleFailed: (s: ResilientState<I, R>, key: string, error: unknown) => readonly [ResilientState<I, R>, readonly RunCmd<I, N>[]];
+    onTimer: (s: ResilientState<I, R>, msg: ResilientTimerMsg) => readonly [ResilientState<I, R>, readonly RunCmd<I, N>[]];
+    subs: (s: ResilientState<I, R>) => readonly DeadlineSub<DeadlineNameOf<N>>[];
+    handlers: (ports: ResilientPorts<I, R>) => ResilientHandlers<I, R, N>;
+};
+/**
+ * Lift a knob result `[slice, cmds]` into a host `[State, cmds]` where the
+ * slice lives at `state.resilience`. A convenience for the common single-slice
+ * host; consumers with a differently-named field spread by hand. Pure — a thin
+ * record rebuild, no clock / RNG. Under `withResilience` the wrapper owns
+ * `model.$resilience`, so there is nothing to lift; this is for the embedded
+ * slice consumers only.
+ *
+ * The record rebuild itself is `liftSlice` from the root door (#231) — this
+ * stays as the named, pre-keyed convenience for the `state.resilience` field,
+ * unchanged in name, signature and subpath.
+ */
+declare function liftResilience<S extends {
+    resilience: ResilientState<I, R>;
+}, I, R, C extends Cmd>(state: S, result: readonly [ResilientState<I, R>, readonly C[]]): readonly [S, readonly C[]];
+/** What every verb of a knob in this family hands back. */
+type Settle<I, R> = readonly [
+    ResilientState<I, R>,
+    readonly RunCmd<I>[]
+];
+/**
+ * The part of a resilient-call knob {@link mountResilientCall} needs. This knob
+ * satisfies it, and so does every knob that delegates these verbs to it —
+ * `internal/jev/ask` and `internal/llm-call` both do, which is why the mount is
+ * written against the shape rather than against either door.
+ *
+ * `OkMsg` / `ErrMsg` are parameters rather than {@link SucceedMsg} /
+ * {@link FailMsg} because an inheriting knob narrows them: jev-ask's `fail`
+ * takes a `JevFailMsg` whose `error` is a typed `JevAskErr`, and a mount that
+ * fixed the supertype would hand that verb a widened Msg.
+ */
+interface MountableKnob<I, R, OkMsg, ErrMsg, Handlers, N extends string = DefaultResilientName> {
+    /**
+     * The Msg-name family this knob settles into — `<name>_ok` / `<name>_err`
+     * (#229). The mount reads it rather than assuming `resilient_*`, so a named
+     * knob mounts into the cells it actually emits; an unnamed one is
+     * `resilient`, so nothing a machine already spread changes.
+     */
+    readonly name: N;
+    init(): ResilientState<I, R>;
+    succeed(s: ResilientState<I, R>, key: string, msg: OkMsg): Settle<I, R>;
+    fail(s: ResilientState<I, R>, key: string, msg: ErrMsg): Settle<I, R>;
+    onTimer(s: ResilientState<I, R>, msg: ResilientTimerMsg<N>): Settle<I, R>;
+    subs(s: ResilientState<I, R>): readonly DeadlineSub<DeadlineNameOf<N>>[];
+    handlers(): Handlers;
+}
+/**
+ * The consumer's half of a settle cell: fold the settled answer into the
+ * machine's own Model.
+ *
+ * It is handed the Model the inherited verb ALREADY settled — the slice at
+ * `slice` is the post-`succeed` / post-`fail` one — so the ordering that wedges
+ * a call at `running` is not something this callback can express. It returns
+ * the repo's universal cell shape so a fold that needs to chain an effect
+ * (book the answer, then write it somewhere) returns that Cmd like any other
+ * reducer cell would.
+ */
+type SettleFold<Model, M, C extends Cmd> = (model: Model, msg: M) => readonly [Model, readonly C[]];
+/** One cell of the update fragment {@link mountResilientCall} returns. */
+type MountedCell<Model, M, I, C extends Cmd> = (model: Model, msg: M) => readonly [Model, readonly (RunCmd<I> | C)[]];
+/**
+ * What to mount, and where. `slice` names the Model field the knob's state
+ * lives on — a plain, readable field, per
+ * [ADR 0015](../../../../.decisions/0015-hide-the-wiring-never-the-state.md):
+ * the mount absorbs the assembly and hides none of the durable state.
+ */
+interface MountConfig<Model, Slice extends string, I, R, AttemptType extends string, AttemptMsg, OkMsg, ErrMsg, C extends Cmd, N extends string = DefaultResilientName> {
+    /** The Model field carrying the knob's slice. */
+    readonly slice: Slice;
+    /**
+     * The cell that starts a call. Its shape is the one wiring point the mount
+     * cannot supply: each door's `attempt` takes its own arguments (jev-ask reads
+     * a key, a state and an instant; llm-call reads a request), and only the
+     * consumer knows which Msg field carries each. `run` is that one line.
+     */
+    readonly attempt: {
+        /** The Msg type that starts a call — the key the cell lands on. */
+        readonly on: AttemptType;
+        readonly run: (slice: ResilientState<I, R>, msg: AttemptMsg) => Settle<I, R>;
+    };
+    /** Fold a settled success into the Model. Omit and only the slice advances. */
+    readonly onOk?: SettleFold<Model, OkMsg, C>;
+    /** Fold a settled failure into the Model. Omit and only the slice advances. */
+    readonly onErr?: SettleFold<Model, ErrMsg, C>;
+    /**
+     * Fold a call the TIMER settled into the Model. This is the third failure
+     * class, and it never reaches {@link MountConfig.onErr}: a deadline fire
+     * settles `failed` inside the slice and emits no settle Msg, so without this
+     * callback a call that dies on its budget advances the slice and folds
+     * nothing — the shape that used to be a documented caveat.
+     *
+     * It runs once per call the knob's deadline cell moved INTO `failed`:
+     * the deadline fire itself, and the resumed retry whose gate found the
+     * budget spent. A plain backoff tick, a stale fire and an already-`failed`
+     * call fold nothing. `error` is the slice's own settled error — a
+     * {@link DeadlineExceededError} on the deadline path.
+     *
+     * Omit and only the slice advances, exactly as the other two do.
+     */
+    readonly onDeadline?: SettleFold<Model, DeadlineSettled<N>, C>;
+}
+/**
+ * What {@link MountConfig.onDeadline} is handed: the one call the timer cell
+ * just settled `failed`, named by its `key`, carrying the error the slice
+ * settled with and the timer Msg that produced it. It is not a Msg the reducer
+ * ever sees — no settle Msg exists for this failure class, which is the whole
+ * reason the callback is here.
+ */
+interface DeadlineSettled<N extends string = DefaultResilientName> {
+    /** The call key that settled. */
+    readonly key: string;
+    /** The error now on the slice — a {@link DeadlineExceededError} on the deadline path. */
+    readonly error: unknown;
+    /**
+     * The timer Msg whose fire settled it — this knob's own tag, so a fold on a
+     * knob named `jev` is handed a `jev_deadline` and one on an unnamed knob a
+     * `deadline_exceeded`.
+     */
+    readonly msg: ResilientTimerMsg<N>;
+}
+/**
+ * The four fragments a consumer spreads into `defineMachine`. Together with
+ * `init` they are the eight wiring points; none of them is optional at the type
+ * level, so a consumer that mounts cannot omit `subscribe` (a backed-off retry
+ * that never fires) or re-implement `interpret` as a dispatching handler.
+ */
+interface MountedResilientCall<Model, Slice extends string, I, R, AttemptType extends string, AttemptMsg, OkMsg, ErrMsg, C extends Cmd, Handlers, N extends string = DefaultResilientName> {
+    /** The starting slice under its field name — spread into the machine's `init`. */
+    init(): {
+        readonly [K in Slice]: ResilientState<I, R>;
+    };
+    /**
+     * The three settle cells plus the attempt cell, to spread into `update`.
+     *
+     * The two settle keys are the knob's OWN Msg names (#229), so a knob built as
+     * `name: "jev"` mounts into `jev_ok` / `jev_err` and two named knobs in one
+     * machine spread into four distinct cells instead of colliding on one. An
+     * unnamed knob is `resilient`, so the keys read `resilient_ok` /
+     * `resilient_err` exactly as they always have.
+     *
+     * The deadline cell is keyed the same way (#238). A knob's deadline Sub
+     * carries its name, so a knob built as `name: "jev"` dispatches
+     * `jev_deadline` and mounts into a `jev_deadline` cell; an unnamed knob still
+     * dispatches and mounts `deadline_exceeded`. Before that, both mounts wrote
+     * the one unqualified `deadline_exceeded` key and the last spread silently
+     * dropped the other knob's deadline fold. The cell folds through
+     * {@link MountConfig.onDeadline}, since a call the timer settles emits no
+     * settle Msg and so reaches no `onErr`.
+     */
+    readonly update: Readonly<Record<AttemptType, MountedCell<Model, AttemptMsg, I, C>>> & {
+        readonly [K in ResilientOkType<N>]: MountedCell<Model, OkMsg, I, C>;
+    } & {
+        readonly [K in ResilientErrType<N>]: MountedCell<Model, ErrMsg, I, C>;
+    } & {
+        readonly [K in ResilientDeadlineType<N>]: MountedCell<Model, ResilientTimerMsg<N>, I, C>;
+    };
+    subscriptions(model: Model): readonly DeadlineSub<DeadlineNameOf<N>>[];
+    readonly subscribe: {
+        readonly deadline: typeof subscribeDeadline;
+    };
+    readonly interpret: Handlers;
+}
+/**
+ * Pre-assemble a resilient-call knob into the fragments a machine definition
+ * spreads, so mounting one is a spread instead of eight hand-spliced points.
+ *
+ * The three points that used to fail only at runtime are gone at the type
+ * level rather than documented:
+ *
+ *   - The settle cells run the inherited `succeed` / `fail` verb and hand the
+ *     already-settled Model to {@link SettleFold}. There is no cell for a
+ *     consumer to write in the wrong order.
+ *   - `interpret` is `knob.handlers()` — the form that RETURNS the settle Msg
+ *     so it re-enters the reducer. A consumer that spreads the fragment cannot
+ *     substitute a dispatching handler for it.
+ *   - `subscribe` carries `subscribeDeadline`, so the retry timer is armed by
+ *     construction rather than by remembering.
+ *
+ * A deadline-exceeded call settles inside the slice and emits no settle Msg, so
+ * it reaches no `onErr`. {@link MountConfig.onDeadline} is that failure class's
+ * fold — omit it and the slice still advances, exactly as omitting `onErr`
+ * does.
+ *
+ * Nothing is taken away. The slice stays a plain field at `slice` that the
+ * consumer reads, `replay` sees and the journal prints, and every verb the
+ * fragments call is still exported and callable by hand — a consumer that
+ * wants a settle cell this shape cannot express writes that one cell itself and
+ * spreads the rest. PURE: a record of closures over `knob` and `config`, no
+ * clock and no RNG.
+ */
+declare function mountResilientCall<Slice extends string, I, R, Model extends {
+    readonly [K in Slice]: ResilientState<I, R>;
+}, AttemptType extends string, AttemptMsg, OkMsg extends {
+    readonly key: string;
+}, ErrMsg extends {
+    readonly key: string;
+}, Handlers, C extends Cmd = never, N extends string = DefaultResilientName>(knob: MountableKnob<I, R, OkMsg, ErrMsg, Handlers, N>, config: MountConfig<Model, Slice, I, R, AttemptType, AttemptMsg, OkMsg, ErrMsg, C, N>): MountedResilientCall<Model, Slice, I, R, AttemptType, AttemptMsg, OkMsg, ErrMsg, C, Handlers, N>;
+
+export { type SettleFold as A, type SlidingWindow as B, type CircuitConfig as C, type DeadlineConfig as D, canPass as E, type FailMsg as F, createResilientCall as G, defaultCircuitPolicy as H, initBucket as I, initCircuit as J, initWindow as K, liftResilience as L, type MountConfig as M, onFailure as N, onSuccess as O, record as P, refill as Q, type RunCmd as R, type SucceedMsg as S, type TokenBucket as T, remaining as U, runCmdDef as V, tryConsume as W, type ResilientState as a, type RateLimitConfig as b, type ResilientPorts as c, type ResilientHandlers as d, type ResilientConfig as e, type ResilientTimerMsg as f, type CacheConfig as g, type CallBudget as h, type CallPhase as i, type CircuitPolicy as j, type CircuitState as k, DEFAULT_RESILIENT_NAME as l, mountResilientCall as m, type DeadlineExceededError as n, type DeadlineNameOf as o, type DeadlineSettled as p, type DefaultResilientName as q, type MountableKnob as r, type MountedCell as s, type MountedResilientCall as t, type ResilientDeadlineType as u, type ResilientErrType as v, type ResilientOkType as w, type ResilientRunType as x, type RunCmdDef as y, type Settle as z };