@demlik/tea 0.13.0 → 0.15.0

package/dist/resilience/index.d.ts

@@ -0,0 +1,744 @@
+import { a as CmdOf, b as CmdDef, C as Cmd, I as Interpret, l as CmdValue, g as PortEmitter, i as NoCtx, S as Sub, M as Machine } from '../core-DnzqWy6u.js';
+import { M as MsgType } from '../protocol-D8VbH-VH.js';
+import { e as ResilientConfig, a as ResilientState, R as RunCmd, S as SucceedMsg, F as FailMsg, f as ResilientTimerMsg, c as ResilientPorts } from '../index-CA_7I5g9.js';
+export { g as CacheConfig, h as CallBudget, i as CallPhase, C as CircuitConfig, j as CircuitPolicy, k as CircuitState, l as DEFAULT_RESILIENT_NAME, n as DeadlineExceededError, o as DeadlineNameOf, p as DeadlineSettled, q as DefaultResilientName, M as MountConfig, r as MountableKnob, s as MountedCell, t as MountedResilientCall, b as RateLimitConfig, D as ResilientCallDeadlineConfig, u as ResilientDeadlineType, v as ResilientErrType, d as ResilientHandlers, w as ResilientOkType, x as ResilientRunType, y as RunCmdDef, z as Settle, A as SettleFold, B as SlidingWindow, T as TokenBucket, E as canPass, G as createResilientCall, H as defaultCircuitPolicy, I as initBucket, J as initCircuit, K as initWindow, L as liftResilience, m as mountResilientCall, N as onFailure, O as onSuccess, P as record, Q as refill, U as remaining, V as runCmdDef, W as tryConsume } from '../index-CA_7I5g9.js';
+import { a as DeadlineSub } from '../index-HSYgG2Yt.js';
+export { A as ArmTimer, e as CacheEntry, c as CacheEvictMsg, C as CacheEvictionSub, D as DeadlineExceeded, f as DeadlineMsgType, g as DeadlineOpts, T as TtlCache, h as cacheEvictMsg, i as cacheEvictionSub, j as cacheEvictionSubscribe, d as deadlineExceeded, k as deadlineMsgType, b as deadlineSub, l as evictExpired, m as get, n as has, o as initCache, r as remove, p as set, q as setTimeoutArmTimer, s as subscribeDeadline, t as subscribeWith } from '../index-HSYgG2Yt.js';
+import { Rng, RetryPolicy } from '../retry-backoff/index.js';
+import 'zod';
+import '../types-BseNPIhr.js';
+
+/**
+ * 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.
+ */
+declare const refreshToken: CmdDef<"refresh_token", Record<string, never>, Token, {
+    readonly [detail: string]: unknown;
+    readonly _tag: "token_refresh_failed";
+}, unknown>;
+type RefreshTokenCmd = CmdOf<typeof refreshToken>;
+/** 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>;
+
+/**
+ * The authed-call knob. It is `ResilientConfig` widened by the token dimension:
+ *
+ *   - `refresh` — the ONLY required field: the port that mints a fresh `Token`.
+ *     Identical to token-refresh's `TokenRefreshPorts.refresh`; it is hoisted
+ *     onto the config (not the ports) so the consumer spells the credential
+ *     source once, the same way `rng` is curried onto the factory.
+ *   - `skewMs` — token-refresh's refresh-ahead skew (optional, defaults to 0).
+ *   - every `ResilientConfig` field (`retry` / `circuit` / `rateLimit` /
+ *     `cache` / `deadline`) — passed straight through to the resilient-call
+ *     knob, each still optional, each still "omit a brick → omit its gate".
+ */
+interface AuthedConfig extends ResilientConfig, TokenRefreshConfig {
+    /** Mint a fresh credential. The single DI seam the auth dimension adds. */
+    readonly refresh: () => Promise<Token>;
+}
+/**
+ * The composed slice. Three plain-data fields, no closures:
+ *
+ *   - `resilience` — resilient-call's entire slice (circuit, bucket, retry,
+ *     cache, calls). Owned and mutated only via resilient-call's verbs.
+ *   - `auth` — token-refresh's `{ token, stale }` slice. Owned and mutated only
+ *     via token-refresh's verbs.
+ *   - `authRetry` — per-key count of auth-retries (401 → refresh → retry) spent
+ *     on a call. Caps the dance at one retry per call so a credential the server
+ *     keeps rejecting cannot spin forever. A key absent from the record has
+ *     spent zero. Cleared when a call settles or a fresh `attempt` starts.
+ *
+ * `pendingAuthRetry` carries the inputs of calls parked waiting for the refresh
+ * to land, keyed so `onRefreshed` can re-issue exactly those calls. Plain data —
+ * `input` is the same payload the call was issued with.
+ */
+interface AuthedState<I, R> {
+    readonly resilience: ResilientState<I, R>;
+    readonly auth: TokenState;
+    readonly authRetry: Readonly<Record<string, number>>;
+    readonly pendingAuthRetry: Readonly<Record<string, I>>;
+}
+/** The two effects this knob emits: resilient-call's run, token-refresh's mint. */
+type AuthedCmd<I> = RunCmd<I> | RefreshTokenCmd;
+/**
+ * Every Msg the knob's verbs fold. Resilient-call's settle + timer Msgs, token-
+ * refresh's refresh-result Msgs, and the 401 trigger the consumer dispatches
+ * when a guarded call comes back unauthorized.
+ */
+type Unauthorized = {
+    readonly type: typeof MsgType.Unauthorized;
+    readonly key: string;
+    readonly at: number;
+};
+/**
+ * The plain-data error a 401 we cannot fix settles with. A `{_tag, ...}`
+ * sentinel — NEVER a `new Error(...)` — so the slice stays JSON-serializable
+ * (an Error object round-trips to `{}` under JSON and carries a stack trace,
+ * both of which break the slice's durability invariant once it is persisted
+ * into a `Store<S>` and reloaded). Mirrors resilient-call's `DeadlineExceededError`
+ * sentinel discipline. `key` echoes the call that was rejected so a consumer can
+ * attribute the failure.
+ */
+type UnauthorizedError = {
+    readonly _tag: "unauthorized";
+    readonly key: string;
+};
+/** Ports `handlers` needs — resilient-call's run port AND token-refresh's refresh port. */
+interface AuthedPorts<I, R> extends ResilientPorts<I, R> {
+    /** Mint a fresh credential. Mirrors `AuthedConfig.refresh` for symmetry at the splice site. */
+    readonly refresh: () => Promise<Token>;
+}
+/**
+ * Build an authed-call knob from `config`. `rng` is injected for retry jitter
+ * and threaded straight into the underlying resilient-call knob — pass a fixed
+ * `() => 0.5` in tests to pin backoff; defaults to `Math.random` (read only at
+ * the verb boundary inside resilient-call, never in a brick op).
+ *
+ * Returns the uniform L2 knob contract, widened by the auth verbs (`on401`,
+ * `onRefreshed`, `installToken`). `I` is the port input type, `R` the result.
+ */
+declare function createAuthedCall<I, R>(config: AuthedConfig, rng?: () => number): {
+    init: () => AuthedState<I, R>;
+    attempt: (s: AuthedState<I, R>, key: string, input: I, at: number) => readonly [AuthedState<I, R>, readonly AuthedCmd<I>[]];
+    succeed: (s: AuthedState<I, R>, key: string, msg: SucceedMsg<R>) => readonly [AuthedState<I, R>, readonly AuthedCmd<I>[]];
+    fail: (s: AuthedState<I, R>, key: string, msg: FailMsg) => readonly [AuthedState<I, R>, readonly AuthedCmd<I>[]];
+    on401: (s: AuthedState<I, R>, key: string, at: number) => readonly [AuthedState<I, R>, readonly AuthedCmd<I>[]];
+    installToken: (s: AuthedState<I, R>, token: Token) => AuthedState<I, R>;
+    onRefreshed: (s: AuthedState<I, R>, at: number) => readonly [AuthedState<I, R>, readonly AuthedCmd<I>[]];
+    onTimer: (s: AuthedState<I, R>, msg: ResilientTimerMsg) => readonly [AuthedState<I, R>, readonly AuthedCmd<I>[]];
+    /** token-refresh's call-boundary verb, re-exposed for proactive expiry refresh. */
+    needsRefresh: (s: AuthedState<I, R>, at: number) => boolean;
+    subs: (s: AuthedState<I, R>) => readonly DeadlineSub[];
+    handlers: (ports: AuthedPorts<I, R>) => {
+        refresh_token: (cmd: CmdValue<"refresh_token", Record<string, never>, {
+            readonly [detail: string]: unknown;
+            readonly _tag: "token_refresh_failed";
+        }, unknown>, ctx: PortEmitter, dispatch?: ((msg: TokenRefreshMsg) => void) | undefined) => Promise<void | TokenRefreshMsg>;
+        resilient_run: (cmd: CmdValue<"resilient_run", {
+            readonly key: string;
+            readonly input: I;
+        }, {
+            readonly [detail: string]: unknown;
+            readonly _tag: "deadline_exceeded";
+        } | {
+            readonly [detail: string]: unknown;
+            readonly _tag: "port_rejected";
+        }, unknown>, ctx: NoCtx) => Promise<SucceedMsg<R, "resilient"> | FailMsg<"resilient">>;
+    };
+};
+/** The shape `createAuthedCall` returns — useful for typing a held knob. */
+type AuthedCall<I, R> = ReturnType<typeof createAuthedCall<I, R>>;
+/**
+ * Lift a knob result `[slice, cmds]` into a host `[State, cmds]` where the slice
+ * lives at `state.authed`. 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.
+ */
+declare function liftAuthed<S extends {
+    authed: AuthedState<I, R>;
+}, I, R, C extends Cmd>(state: S, [slice, cmds]: readonly [AuthedState<I, R>, readonly C[]]): readonly [S, readonly C[]];
+
+/**
+ * internal/resilience/retry-to-success — run a fallible async port through BOUNDED
+ * retry + exponential backoff to success-or-terminal-give-up, and hand the
+ * caller a `Promise<R>` that resolves on the first success or REJECTS with a
+ * checkable {@link RetryExhaustedError} the moment the retry bound is hit.
+ *
+ * This is the retry-side parallel to `./await-terminal`. `runToTerminal` gives a
+ * caller with a one-shot decision *machine* a fire-and-await `Promise<State>`
+ * without wiring `observe`; this gives a caller with a one-shot fallible *port*
+ * a fire-and-await `Promise<R>` without either hand-folding the
+ * `./retry-backoff` primitives (`recordFailure` / `shouldRetry` / `nextDelayMs`)
+ * into their own reducer each time, or standing up the full `./resilient-call`
+ * verb contract (`init` + `attempt`/`succeed`/`fail`/`onTimer` + `subs` +
+ * `handlers`) when they want retry only and none of cache / circuit / rate-limit
+ * / deadline.
+ *
+ * It adds NO new runtime capability and NO new backoff math — the whole retry
+ * decision is `./retry-backoff` exactly as `resilient-call`'s `backoff` verb
+ * wires it:
+ *   - `initRetry()` seeds the per-call attempt counter.
+ *   - `recordFailure(retry, error)` folds each thrown failure (attempt++).
+ *   - `shouldRetry(retry, policy)` is the terminal-at-`maxAttempts` bound — the
+ *     `maxAttempts`-th recorded failure refuses another attempt (attempts
+ *     `0 .. maxAttempts-1` run; the port is invoked at most `maxAttempts` times).
+ *   - `nextDelayMs(retry, policy, rng)` is the exp+jitter+cap delay before the
+ *     next attempt, computed on the incremented state — same call order as
+ *     `resilient-call`.
+ *
+ * Where the clock / RNG live: injected, never read on the module's own behalf,
+ * mirroring `retry-backoff`'s purity discipline. `rng` is an {@link Rng} (branded
+ * `[0, 1)` via `asRng` at the caller boundary) threaded straight into
+ * `nextDelayMs`; the wait itself is a `sleep(ms)` port defaulting to a real
+ * `setTimeout`, injectable so a test can drive the backoff schedule
+ * deterministically without touching wall-clock timers.
+ *
+ * Exhaustion is NEVER a silent swallow: at the bound the returned promise
+ * rejects with {@link RetryExhaustedError} (carrying the attempt count and the
+ * final failure), the retry-side dialect of `await-terminal`'s
+ * `TerminalTimeoutError` — a distinct `instanceof`- and `_tag`-checkable
+ * rejection.
+ *
+ * NOT a substrate primitive: it depends on nothing from `../index`, only on the
+ * leaf `retry-backoff` utility. Internal to the package
+ * (`src/internal/resilience/`, #46), not a published subpath.
+ */
+
+/**
+ * Raised when `retryToSuccess` exhausts the retry bound without a success — the
+ * `maxAttempts`-th recorded failure refuses another attempt. Follows the tea
+ * error dialect (`override readonly name`) and carries a `_tag` discriminant, so
+ * a caller can branch on it by `instanceof` or on the tag. It carries the number
+ * of attempts made and the final failure (`lastError`) so the terminal give-up
+ * is a distinct, checkable rejection — never a silent resolve, and never a
+ * swallowed error.
+ */
+declare class RetryExhaustedError extends Error {
+    /** How many times the port was invoked before giving up (= `policy.maxAttempts`). */
+    readonly attempts: number;
+    /** The failure the final attempt threw — carried, never interpreted. */
+    readonly lastError: unknown;
+    readonly name = "RetryExhaustedError";
+    readonly _tag: "RetryExhaustedError";
+    constructor(
+    /** How many times the port was invoked before giving up (= `policy.maxAttempts`). */
+    attempts: number, 
+    /** The failure the final attempt threw — carried, never interpreted. */
+    lastError: unknown);
+}
+/** Options for {@link retryToSuccess}. */
+interface RetryToSuccessOptions {
+    /**
+     * The `[0, 1)` jitter source threaded into `nextDelayMs`, branded via
+     * `asRng` at construction (a raw `() => number` is rejected by the type).
+     * Injected for deterministic backoff in tests; defaults to `defaultRng`
+     * (`Math.random`), read only at the delay boundary — never inside the loop's
+     * decision.
+     */
+    readonly rng?: Rng;
+    /**
+     * The wait between attempts, given the backoff delay in ms. Injectable so a
+     * test can drive the retry schedule without wall-clock timers (and assert the
+     * exact delays); defaults to a real `setTimeout`. The delay value is always
+     * `./retry-backoff`'s `nextDelayMs` — this port only realizes the wait.
+     */
+    readonly sleep?: (ms: number) => Promise<void>;
+}
+/**
+ * Fire-and-await bounded retry: invoke the fallible `port`, and on each thrown
+ * failure fold it through `./retry-backoff` — record it, and if the policy
+ * still permits an attempt, back off `nextDelayMs` and retry; otherwise REJECT
+ * with {@link RetryExhaustedError}. Resolves with the port's value on the first
+ * success.
+ *
+ * The port is invoked at most `policy.maxAttempts` times (attempts
+ * `0 .. maxAttempts-1`); the `maxAttempts`-th failure is terminal. Every failure
+ * is either retried or surfaced on the rejection's `lastError` — none is
+ * swallowed.
+ *
+ * @param port   the fallible work — throws on failure, resolves with `R` on success.
+ * @param policy the bounded-retry curve (`baseMs` / `factor` / `capMs` /
+ *               `maxAttempts` / `jitter`) from `./retry-backoff`.
+ * @param opts   optional injected `rng` (jitter) and `sleep` (the wait) — see
+ *               {@link RetryToSuccessOptions}.
+ */
+declare function retryToSuccess<R>(port: () => Promise<R>, policy: RetryPolicy, opts?: RetryToSuccessOptions): Promise<R>;
+
+/**
+ * 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).
+ */
+declare const deadlineDecision: CmdDef<"$deadline:decision", {
+    decision: "idle" | "rearm" | "expire";
+    seq: number;
+}, void, never, unknown>;
+type DeadlineDecisionCmd = CmdOf<typeof deadlineDecision>;
+/**
+ * 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>;
+
+/**
+ * The `withResilience` knob. Extends resilient-call's `ResilientConfig` (every
+ * brick optional — omit a brick, omit its gate) with the two fields the wrapper
+ * needs that the bare knob does not:
+ *
+ *   - `target` — the `Cmd.type` discriminant of the ONE base Cmd this wrapper
+ *     hardens. Every other base Cmd passes through untouched.
+ *   - `keyOf` — OPTIONAL. Derives the per-call resilience `key` from the target
+ *     base Cmd, so distinct logical calls (distinct urls, distinct ids) get
+ *     independent retry / cache state. Pure — it runs inside the merged
+ *     `update`, so it must NOT read the clock / RNG. Defaults to a single
+ *     shared key (`target`), i.e. one logical call at a time.
+ */
+interface ResilienceConfig<TC extends Cmd, TM extends {
+    type: string;
+}> extends ResilientConfig {
+    /** The base `Cmd.type` to make resilient. */
+    readonly target: TC["type"];
+    /** Optional per-call key deriver. Pure. Defaults to the target type itself. */
+    readonly keyOf?: (cmd: TC) => string;
+    /**
+     * Extracts the real wall-clock time (ms) the TRIGGERING base Msg carries as
+     * data — the time-as-data convention `resilient-call` expects on `attempt`.
+     *
+     * The merged `update` is PURE: it cannot read `Date.now()` (rule 5). The COLD
+     * attempt's gate (the very first `attempt` for a target Cmd in a transition)
+     * still needs a real instant — the breaker compares `at` against its recorded
+     * `openedAtMs`, the cache against its write `at`, the bucket against its last
+     * refill `at`, and the deadline cap anchors at `at + deadline.ms`. Fabricating
+     * `at = 0` is the betrayal: a cold attempt after a real-time breaker trip then
+     * computes cooldown = `0 - realTripTime < 0` forever, so the breaker NEVER
+     * recovers, and a `0`-anchored deadline brick fires immediately.
+     *
+     * So the base Msg that drove this transition MUST carry its own wall time as
+     * data, and `at` reads it off that Msg. The merged update passes
+     * `at(currentBaseMsg)` into `rc.attempt` for every target Cmd that transition
+     * emitted — real time enters the cold gate as Msg data, never `0`.
+     *
+     * REQUIRED whenever any time-sensitive brick (`circuit`, `rateLimit`, `cache`,
+     * `deadline`) is configured — `withResilience` THROWS at construction if such
+     * a brick is set and `at` is absent (errors are data: the cold gate needs real
+     * time, refuse to build a breaker that can never recover). OPTIONAL when only
+     * `retry` is configured: retry backoff reads its time off the result / timer
+     * Msgs (`$resilience:err.at`, `$resilience:timer.atMs`), never the cold attempt
+     * — so a `0` cold `at` is harmless there. Pure: it runs inside the merged
+     * `update`, so it must NOT read the clock / RNG.
+     */
+    readonly at?: (msg: TM) => number;
+}
+/**
+ * The composed Model. The base machine's state nests under `base`; the wrapper
+ * owns the NAMED `$resilience` slice — resilient-call's `ResilientState` keyed
+ * by the per-call `key`, with `I = TC` (the original target base Cmd is the
+ * port input) and `R = unknown` (the base interpret handler's resolution — the
+ * wrapper never inspects it; it routes Ok/Err and delivers a Msg to the base).
+ * Plain data → round-trips through `JSON.parse(JSON.stringify(...))` iff the
+ * base state does.
+ */
+interface ResilienceModel<S, TC extends Cmd> {
+    readonly base: S;
+    readonly $resilience: ResilientState<TC, unknown>;
+}
+/**
+ * The carrier Cmd the wrapper emits when the gate ADMITS a target base Cmd. It
+ * RETAGS the original base Cmd into `input` — the base Cmd is plain data, so no
+ * closure (invariant 3). The interpret handler unwraps `input` and runs it
+ * through the BASE interpret for that Cmd type. `key` indexes the resilient
+ * call this run belongs to.
+ */
+declare function resilienceRunCmdDef<TC extends Cmd, TM>(): CmdDef<"$resilience:run", {
+    readonly key: string;
+    /** The ORIGINAL base Cmd, retagged — never swallowed. */
+    readonly input: TC;
+}, void | TM, {
+    readonly [detail: string]: unknown;
+    readonly _tag: "deadline_exceeded";
+} | {
+    readonly [detail: string]: unknown;
+    readonly _tag: "base_rejected";
+}, unknown>;
+type ResilienceRunCmd<TC extends Cmd> = CmdOf<ReturnType<typeof resilienceRunCmdDef<TC, unknown>>>;
+/**
+ * The success Msg the `$resilience:run` handler dispatches back when the base
+ * interpret resolved OK. Routes to `succeed`, then `result` — the base
+ * handler's follow-up, when it is a Msg — is folded through the base reducer.
+ * `at` is stamped at the interpret boundary (the one permitted clock read).
+ */
+type ResilienceOkMsg = {
+    readonly type: "$resilience:ok";
+    readonly key: string;
+    readonly result: unknown;
+    readonly at: number;
+};
+/**
+ * The error Msg the `$resilience:run` handler dispatches back when the base
+ * interpret threw / rejected. Routes to `fail` (trip the breaker, then back off
+ * or settle). `at` is stamped at the interpret boundary.
+ */
+type ResilienceErrMsg = {
+    readonly type: "$resilience:err";
+    readonly key: string;
+    readonly error: unknown;
+    readonly at: number;
+};
+/**
+ * The retry / deadline timer Msg the `$resilience:timer` Sub dispatches when
+ * the wall clock crosses the armed instant. Routes to `onTimer`. `id` is the
+ * `$resilience:`-namespaced timer id; `atMs` is the fire instant (Msg data, the
+ * clock that drove it lives in the Sub).
+ */
+type ResilienceTimerMsg = {
+    readonly type: "$resilience:timer";
+    readonly id: string;
+    readonly atMs: number;
+};
+/** Every Msg the wrapper adds to the base's Msg union. */
+type ResilienceMsg = ResilienceOkMsg | ResilienceErrMsg | ResilienceTimerMsg;
+/** Every Cmd the wrapper adds to the base's Cmd union. */
+type ResilienceCmd<TC extends Cmd> = ResilienceRunCmd<TC>;
+/** The Sub the wrapper adds — a deadline-style timer in the `$resilience` family. */
+type ResilienceTimerSub = Sub<"$resilience:timer"> & {
+    readonly atMs: number;
+};
+/**
+ * Wrap `base` so its `config.target` Cmd is run through the resilient-call
+ * concern (cache → circuit → rate-limit → retry, deadline-capped). Returns a
+ * NEW `Machine` over the composed Model `{ base, $resilience }`, with the
+ * base's Msgs/Cmds/Subs/Ctx extended by the wrapper's own.
+ *
+ * @param base   any `Machine<S, M, C, U, Ctx>`.
+ * @param config the resilience knob: `target`, the optional bricks, `keyOf`.
+ * @param rng    injected backoff jitter source. Pass a fixed `() => 0.5` in
+ *               tests to pin retry delays; defaults to `Math.random` (read only
+ *               at the verb boundary, never inside the merged `update`).
+ */
+declare function withResilience<S, M extends {
+    type: string;
+}, C extends Cmd, U extends Sub, Ctx>(base: Machine<S, M, C, U, Ctx>, config: ResilienceConfig<C, M>, rng?: () => number): Machine<ResilienceModel<S, C>, M | ResilienceMsg, C | ResilienceCmd<C>, U | ResilienceTimerSub, Ctx>;
+
+/**
+ * The datum handed to the sink. The default projector emits `{ seq, msgType }`;
+ * a custom `event` projector may return any extra fields. `at` is OPTIONAL and
+ * plain data — it is stamped at the interpret boundary by the `clock` port, not
+ * inside the (pure, clock-free) merged `update`. Every field is JSON-round-trip
+ * serializable so a recorded telemetry stream stays durable.
+ */
+interface TelemetryEvent {
+    /** Monotonic event counter — equals `$telemetry.seq` after the transition. */
+    readonly seq: number;
+    /** The `Msg.type` discriminant that drove this transition. */
+    readonly msgType: string;
+    /**
+     * Wall-clock instant the event was emitted, ms since epoch. Absent until the
+     * interpret boundary stamps it (the `clock` port). Optional because the
+     * merged `update` is clock-free — a verb must never read `Date.now()`.
+     */
+    readonly at?: number;
+}
+/**
+ * The wrapper's Model slice. A monotonic event counter — minimal but real, so
+ * the named-slice mechanism is exercised for the richer-slice wrappers that
+ * follow. `seq` equals the number of base Msgs folded so far: after replaying
+ * `N` msgs, `$telemetry.seq === N`. Plain data → serializes into a `Store<S>`.
+ */
+interface TelemetrySlice {
+    readonly seq: number;
+}
+/**
+ * The composed Model. The base machine's state is nested under `base`; the
+ * wrapper's state lives in the NAMED `$telemetry` 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 TelemetryModel<S> {
+    readonly base: S;
+    readonly $telemetry: TelemetrySlice;
+}
+/**
+ * The fire-and-forget Cmd the merged `update` appends after every base
+ * transition. It carries the projected `event` as plain data (invariant 3 —
+ * no closure). The interpret handler hands `event` to the sink and dispatches
+ * NOTHING back, so there is no feedback loop.
+ */
+declare const telemetryEmit: CmdDef<"$telemetry:emit", {
+    event: TelemetryEvent;
+}, void, never, TelemetryPorts>;
+type TelemetryEmitCmd = CmdOf<typeof telemetryEmit>;
+/**
+ * The side-effecting ports the wrapper adds to `Ctx`. The sink (PostHog / Sentry
+ * bridge) lives at the interpret boundary, never in a verb. `clock` is the
+ * optional wall-clock source used to stamp `event.at` at that same boundary —
+ * pass `Date.now` in production, a fixed `() => 1000` in tests; omit it to leave
+ * `at` unset.
+ */
+interface TelemetryPorts {
+    /** The side-effecting sink. Fire-and-forget — its result is never awaited into a Msg. */
+    readonly telemetrySink: (event: TelemetryEvent) => void | Promise<void>;
+    /** Optional clock for stamping `event.at` at the interpret boundary. */
+    readonly clock?: () => number;
+}
+/**
+ * The telemetry knob. `event` is an OPTIONAL projector mapping
+ * `(msg, prev, next)` to a `TelemetryEvent`; omit it and the default emits
+ * `{ seq, msgType }` where `seq` is the post-transition counter. The projector
+ * runs INSIDE the pure merged `update`, so it must not read the clock — stamp
+ * `at` at the sink boundary via the `clock` port instead.
+ */
+interface TelemetryConfig<S, M extends {
+    type: string;
+}> {
+    readonly event?: (msg: M, prev: TelemetryModel<S>, next: TelemetryModel<S>) => TelemetryEvent;
+}
+/**
+ * Wrap `base` with observe-only telemetry. Returns a NEW `Machine` over the
+ * composed Model `{ base, $telemetry }`, with the base's Msgs/Cmds/Subs/Ctx
+ * extended by the wrapper's own.
+ *
+ * The composed machine:
+ *   - `init` rehydrates the base (honoring the `[loaded, []]` contract) and
+ *     seeds `$telemetry: { seq: 0 }`. Base init Cmds pass through unchanged.
+ *   - `update` (Reducer form, keyed by every base `Msg.type`) runs the base
+ *     reducer, increments `seq`, and appends a `$telemetry:emit` Cmd carrying
+ *     the projected event. Base Cmds pass through UNCHANGED — the observe-only
+ *     property.
+ *   - `subscriptions` / `subscribe` are the base's, verbatim (no timers).
+ *   - `interpret` is `{ ...base.interpret, "$telemetry:emit": sink-handler }`.
+ *
+ * @param base   any `Machine<S, M, C, U, Ctx>`.
+ * @param config the telemetry knob (optional `event` projector).
+ */
+declare function withTelemetry<S, M extends {
+    type: string;
+}, C extends Cmd, U extends Sub, Ctx>(base: Machine<S, M, C, U, Ctx>, config?: TelemetryConfig<S, M>): Machine<TelemetryModel<S>, M, C | TelemetryEmitCmd, U, Ctx & TelemetryPorts>;
+
+export { type AuthedCall, type AuthedCmd, type AuthedConfig, type AuthedPorts, type AuthedState, type DeadlineConfig, type DeadlineDecisionCmd, type DeadlineExceededMsg, type DeadlineModel, type DeadlineSlice, DeadlineSub, type DeadlineTimeoutSub, FailMsg, type ProgressPredicate, type RefreshTokenCmd, type ResilienceCmd, type ResilienceConfig, type ResilienceErrMsg, type ResilienceModel, type ResilienceMsg, type ResilienceOkMsg, type ResilienceRunCmd, type ResilienceTimerMsg, type ResilienceTimerSub, ResilientConfig, ResilientPorts, ResilientState, ResilientTimerMsg, RetryExhaustedError, type RetryToSuccessOptions, RunCmd, SucceedMsg, type TelemetryConfig, type TelemetryEmitCmd, type TelemetryEvent, type TelemetryModel, type TelemetryPorts, type TelemetrySlice, type Token, type TokenRefresh, type TokenRefreshConfig, type TokenRefreshFailedMsg, type TokenRefreshMsg, type TokenRefreshPorts, type TokenRefreshedMsg, type TokenState, type Unauthorized, type UnauthorizedError, createAuthedCall, createTokenRefresh, deadlineDecision, deadlineExceededMsg, initTokenRefresh, liftAuthed, refreshToken, refreshTokenCmd, resilienceRunCmdDef, retryToSuccess, telemetryEmit, tokenRefreshFailedMsg, tokenRefreshedMsg, withDeadline, withResilience, withTelemetry };