@demlik/tea 0.13.0 → 0.15.0

package/dist/resilient-call/index.d.ts

@@ -1,320 +0,0 @@
-import { TtlCache } from '../cache/index.js';
-import { CircuitState } from '../circuit-breaker/index.js';
-import { DeadlineExceeded, DeadlineSub } from '../deadline/index.js';
-export { deadlineSub, subscribeDeadline } from '../deadline/index.js';
-import { C as Cmd } from '../core-Co0LWkIA.js';
-import { M as MsgType } from '../protocol-B5YmJr0d.js';
-import { TokenBucket } from '../rate-limit/index.js';
-import { RetryState, AnyRetryPolicy } from '../retry-backoff/index.js';
-import '../types-XS_miRnB.js';
-import 'zod';
-
-/**
- * @packageDocumentation
- *
- * @deprecated `@demlik/tea/resilient-call` is deprecated in favor of
- * `@demlik/tea/with-resilience` — the higher-order `withResilience(base,
- * config)` wrapper (TEA-idiomatic: it wraps any existing machine instead of
- * forcing a bespoke embedded slice; epic consolidation verdict, survivor
- * `with-resilience`). The APIs are NOT drop-in; migration map:
- *
- *   - `createResilientCall(config, rng)` + hand-wiring `init` / the verbs /
- *     `subs` / `handlers` into your machine → `withResilience(base, { target,
- *     ...bricks }, rng)`. Nothing is wired by hand anymore: the wrapper
- *     intercepts the `target` base Cmd and routes it through the gate.
- *   - `ResilientConfig` bricks (`retry` / `circuit` / `rateLimit` / `cache` /
- *     `deadline`) → unchanged; `ResilienceConfig` extends the same knob and
- *     adds `target` (required), `keyOf?` (per-call key — was `attempt`'s `key`
- *     argument), and `at?` (time-as-data reader — REQUIRED with any
- *     time-sensitive brick; `withResilience` throws at construction without it).
- *   - The slice at your chosen Model field + `liftResilience` → the wrapper
- *     owns `model.$resilience`; there is nothing to lift.
- *   - Verbs `attempt` / `succeed` / `fail` / `onTimer` → internal to the
- *     wrapper; results route as `$resilience:ok` / `$resilience:err` /
- *     `$resilience:timer` Msgs through the merged `update` (the old
- *     `resilient_run` / `resilient_ok` / `resilient_err` vocabulary is renamed
- *     into the `$resilience:` namespace).
- *   - `settleFailed` → NO equivalent. It exists for embedded-slice consumers
- *     (`authed-call`, `paginated-walk`) that settle a call without touching the
- *     breaker; the wrapper exposes no caller-facing settle verb.
- *   - `handlers(ports)` / `subs(state)` / the `subscribeDeadline` re-export →
- *     handled by the wrapper; run the returned machine like any other.
- *
- * Removal window ("deprecate, don't delete"): the `./resilient-call` subpath
- * export survives one minor release after this deprecation ships, then is
- * removed. Internal sibling modules (`with-resilience` itself, `agent`,
- * `llm-call`, `authed-call`, `reconciler`, `paginated-walk`) intentionally keep
- * importing `../resilient-call` — the deprecation targets the PUBLISHED export,
- * not the module's internal role.
- *
- * @demlik/tea/resilient-call — the ROOT composition: a single resilience knob
- * that bundles cache → circuit-breaker → rate-limit → exponential-backoff retry
- * (with a deadline-driven retry timer) around any fallible `(input) => Promise`
- * port.
- *
- * This is `examples/resilient-fetch.ts`'s hand-wired `attempt()` generalized:
- *
- *   - It is **keyed**. The example tracked one URL at a time; this tracks N
- *     concurrent logical calls, each under a string `key`. The cache, the
- *     waiting-retry bookkeeping, and the retry timers are all per-key, while the
- *     circuit breaker and token bucket are shared (one downstream target, one
- *     breaker / one bucket — the example's implicit single-target assumption
- *     made explicit).
- *   - It is **config-driven**, not hand-wired. You hand `createResilientCall`
- *     a `ResilientConfig` and get back the uniform knob contract every L2
- *     composition exposes: `init()`, the four verbs (`attempt` / `succeed` /
- *     `fail` / `onTimer`), `subs(state)`, and `handlers(ports)`.
- *   - Every brick is **optional**. Omit `cache` and the cache gate disappears
- *     (`get` is never consulted); omit `circuit` and every call passes the
- *     breaker; omit `rateLimit` and the bucket never throttles; omit `retry`
- *     and a failure is terminal (no backoff, no timer); omit `deadline` and no
- *     overall wall-clock cap is armed. "Omit a brick → omit its gate" is the
- *     whole config story — there are no other modes.
- *
- * Four later compositions (`llm-call`, `paginated-walk`, `authed-call`,
- * `reconciler`) inherit THIS slice + verb shape, so the contract here is
- * load-bearing: the slice is a flat record of brick states, every verb returns
- * `readonly [State, Cmd[]]`, time is always an `at` / `now` parameter, and the
- * RNG used for jitter is injected on the config (never read inside a verb).
- *
- * ## The two non-negotiables (canon)
- *
- *   - **Durable** — the slice is a plain-data Model field (brick states are all
- *     JSON-serializable), so it survives DO eviction / reload.
- *   - **Replayable** — every transition is a verb returning new state + Cmds;
- *     `replay` reconstructs it exactly. Nothing here closes over time or RNG.
- *
- * ## Where the clock / RNG live
- *
- * Inside the verbs: nowhere. Time arrives as `at` on `attempt` / `onTimer` and
- * is carried on the result / timer Msgs the consumer dispatches. Jitter RNG is
- * injected once at `createResilientCall(config, rng)` and threaded into
- * `nextDelayMs` at the verb boundary — deterministic in tests, `Math.random`
- * by default. The ONLY clock read is `Date.now()` inside the `handlers` port
- * (the effect boundary), exactly as `resilient-fetch.ts` stamps its result Msgs.
- *
- * That same `at` is what makes a DURATION-bounded retry budget reachable here:
- * `recordFailure` / `shouldRetry` are fed the failure's observation instant,
- * so `config.retry` accepts any `AnyRetryPolicy` — a count, a wall-clock outage
- * budget (`maxElapsedMs`), or explicit `unbounded: true` — with no new argument
- * on any verb and no clock read inside one.
- *
- * ## Typical wiring
- *
- *   const rc = createResilientCall<string, Result>({
- *     cache: { ttlMs: 60_000 },
- *     circuit: { threshold: 5, cooldownMs: 30_000 },
- *     rateLimit: { capacity: 10, refillPerSec: 5 },
- *     retry: defaultRetryPolicy,
- *     deadline: { ms: 5_000 },
- *   });
- *
- *   // in the machine:
- *   init: () => [{ resilience: rc.init() }, []],
- *   update: {
- *     fetch:   (s, m) => lift(s, rc.attempt(s.resilience, m.key, m.input, m.at)),
- *     call_ok: (s, m) => lift(s, rc.succeed(s.resilience, m.key, m)),
- *     call_err:(s, m) => lift(s, rc.fail(s.resilience, m.key, m)),
- *     retry_due:(s, m) => lift(s, rc.onTimer(s.resilience, m)),
- *   },
- *   subscriptions: (s) => rc.subs(s.resilience),
- *   subscribe: { deadline: subscribeDeadline },
- *   interpret: rc.handlers({ run: ctx.call }),
- */
-
-/** 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 wall-clock deadline knob — an absolute cap per in-flight call. */
-interface DeadlineConfig {
-    /** Budget from the moment a call starts, in ms. */
-    readonly ms: number;
-}
-/**
- * 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.
- */
-interface ResilientConfig {
-    /**
-     * 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;
-}
-/**
- * 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 `deadlineAtMs` (absolute cap, `0` if no deadline
- *                       brick) 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.
- *   - `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 deadlineAtMs: number;
-} | {
-    readonly phase: "waiting_retry";
-    readonly input: I;
-    readonly retryAtMs: number;
-    readonly deadlineAtMs: number;
-} | {
-    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).
- */
-type RunCmd<I> = Cmd<typeof MsgType.ResilientRun> & {
-    readonly key: string;
-    readonly input: I;
-};
-/** Settle Msgs the `handlers` port dispatches back. `at` is stamped at the boundary. */
-type SucceedMsg<R> = {
-    readonly type: typeof MsgType.ResilientOk;
-    readonly key: string;
-    readonly result: R;
-    readonly at: number;
-};
-type FailMsg = {
-    readonly type: typeof MsgType.ResilientErr;
-    readonly key: string;
-    readonly error: unknown;
-    readonly at: number;
-};
-/** The retry / deadline timer Msg — `DeadlineExceeded`, keyed by the call `key`. */
-type ResilientTimerMsg = DeadlineExceeded;
-/**
- * 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;
-};
-/** 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.
- *
- * @deprecated Use `withResilience` from `@demlik/tea/with-resilience` — not
- * drop-in; see the migration map at the top of this module.
- */
-declare function createResilientCall<I, R>(config: ResilientConfig, rng?: () => number): {
-    init: () => ResilientState<I, R>;
-    attempt: (s: ResilientState<I, R>, key: string, input: I, at: number) => readonly [ResilientState<I, R>, readonly RunCmd<I>[]];
-    succeed: (s: ResilientState<I, R>, key: string, msg: SucceedMsg<R>) => readonly [ResilientState<I, R>, readonly RunCmd<I>[]];
-    fail: (s: ResilientState<I, R>, key: string, msg: FailMsg) => readonly [ResilientState<I, R>, readonly RunCmd<I>[]];
-    settleFailed: (s: ResilientState<I, R>, key: string, error: unknown) => readonly [ResilientState<I, R>, readonly RunCmd<I>[]];
-    onTimer: (s: ResilientState<I, R>, msg: ResilientTimerMsg) => readonly [ResilientState<I, R>, readonly RunCmd<I>[]];
-    subs: (s: ResilientState<I, R>) => readonly DeadlineSub[];
-    handlers: (ports: ResilientPorts<I, R>) => {
-        resilient_run: (cmd: RunCmd<I>, ctx: Readonly<Record<never, never>>) => Promise<FailMsg | SucceedMsg<R>>;
-    };
-};
-/**
- * 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.
- *
- * @deprecated Use `withResilience` from `@demlik/tea/with-resilience` — the
- * wrapper owns `model.$resilience`, so there is nothing to lift; see the
- * migration map at the top of this module.
- */
-declare function liftResilience<S extends {
-    resilience: ResilientState<I, R>;
-}, I, R, C extends Cmd>(state: S, [slice, cmds]: readonly [ResilientState<I, R>, readonly C[]]): readonly [S, readonly C[]];
-
-export { type CacheConfig, type CallPhase, type CircuitConfig, type DeadlineConfig, DeadlineExceeded, type DeadlineExceededError, DeadlineSub, type FailMsg, type RateLimitConfig, type ResilientConfig, type ResilientPorts, type ResilientState, type ResilientTimerMsg, type RunCmd, type SucceedMsg, createResilientCall, liftResilience };

package/dist/resilient-call/index.js

@@ -1,14 +0,0 @@
-export { createResilientCall, liftResilience } from '../chunk-4KLG43GY.js';
-import '../chunk-JELSZN25.js';
-import '../chunk-RH5EFRVJ.js';
-export { deadlineSub, subscribeDeadline } from '../chunk-DGE4PV4A.js';
-import '../chunk-Q2UM7BXU.js';
-import '../chunk-S2EGRPCM.js';
-import '../chunk-UF4MZSLT.js';
-import '../chunk-VYFAZN3F.js';
-import '../chunk-2YFLOCWX.js';
-import '../chunk-ZJ5AOYBH.js';
-import '../chunk-ZSUUOEPL.js';
-import '../chunk-OOYD44JI.js';
-//# sourceMappingURL=index.js.map
-//# sourceMappingURL=index.js.map

package/dist/resilient-call/index.js.map

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

package/dist/retry-to-success/index.d.ts

@@ -1,109 +0,0 @@
-import { Rng, RetryPolicy } from '../retry-backoff/index.js';
-
-/**
- * @demlik/tea/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. Callers reach it via the
- * `@demlik/tea/retry-to-success` 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>;
-
-export { RetryExhaustedError, type RetryToSuccessOptions, retryToSuccess };

package/dist/retry-to-success/index.js

@@ -1,37 +0,0 @@
-import { defaultRng, initRetry, recordFailure, shouldRetry, nextDelayMs } from '../chunk-Q2UM7BXU.js';
-
-// src/retry-to-success/index.ts
-var RetryExhaustedError = class extends Error {
-  constructor(attempts, lastError) {
-    super(
-      `@demlik/tea: retryToSuccess gave up after ${attempts} attempt(s) \u2014 the bounded retry reached maxAttempts without a success. See .lastError for the final failure.`
-    );
-    this.attempts = attempts;
-    this.lastError = lastError;
-  }
-  attempts;
-  lastError;
-  name = "RetryExhaustedError";
-  _tag = "RetryExhaustedError";
-};
-var defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
-async function retryToSuccess(port, policy, opts = {}) {
-  const rng = opts.rng ?? defaultRng;
-  const sleep = opts.sleep ?? defaultSleep;
-  let retry = initRetry();
-  for (; ; ) {
-    try {
-      return await port();
-    } catch (error) {
-      retry = recordFailure(retry, error);
-      if (!shouldRetry(retry, policy)) {
-        throw new RetryExhaustedError(retry.attempt, error);
-      }
-      await sleep(nextDelayMs(retry, policy, rng));
-    }
-  }
-}
-
-export { RetryExhaustedError, retryToSuccess };
-//# sourceMappingURL=index.js.map
-//# sourceMappingURL=index.js.map

package/dist/retry-to-success/index.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../../src/retry-to-success/index.ts"],"names":[],"mappings":";;;AAiEO,IAAM,mBAAA,GAAN,cAAkC,KAAA,CAAM;AAAA,EAG7C,WAAA,CAEkB,UAEA,SAAA,EAChB;AACA,IAAA,KAAA;AAAA,MACE,6CAA6C,QAAQ,CAAA,iHAAA;AAAA,KAGvD;AARgB,IAAA,IAAA,CAAA,QAAA,GAAA,QAAA;AAEA,IAAA,IAAA,CAAA,SAAA,GAAA,SAAA;AAAA,EAOlB;AAAA,EATkB,QAAA;AAAA,EAEA,SAAA;AAAA,EANA,IAAA,GAAO,qBAAA;AAAA,EAChB,IAAA,GAAO,qBAAA;AAalB;AAGA,IAAM,YAAA,GAAe,CAAC,EAAA,KACpB,IAAI,OAAA,CAAQ,CAAC,OAAA,KAAY,UAAA,CAAW,OAAA,EAAS,EAAE,CAAC,CAAA;AAuClD,eAAsB,cAAA,CACpB,IAAA,EACA,MAAA,EACA,IAAA,GAA8B,EAAC,EACnB;AACZ,EAAA,MAAM,GAAA,GAAM,KAAK,GAAA,IAAO,UAAA;AACxB,EAAA,MAAM,KAAA,GAAQ,KAAK,KAAA,IAAS,YAAA;AAI5B,EAAA,IAAI,QAAQ,SAAA,EAAU;AACtB,EAAA,WAAS;AACP,IAAA,IAAI;AACF,MAAA,OAAO,MAAM,IAAA,EAAK;AAAA,IACpB,SAAS,KAAA,EAAO;AAId,MAAA,KAAA,GAAQ,aAAA,CAAc,OAAO,KAAK,CAAA;AAClC,MAAA,IAAI,CAAC,WAAA,CAAY,KAAA,EAAO,MAAM,CAAA,EAAG;AAG/B,QAAA,MAAM,IAAI,mBAAA,CAAoB,KAAA,CAAM,OAAA,EAAS,KAAK,CAAA;AAAA,MACpD;AACA,MAAA,MAAM,KAAA,CAAM,WAAA,CAAY,KAAA,EAAO,MAAA,EAAQ,GAAG,CAAC,CAAA;AAAA,IAC7C;AAAA,EACF;AACF","file":"index.js","sourcesContent":["/**\n * @demlik/tea/retry-to-success — run a fallible async port through BOUNDED\n * retry + exponential backoff to success-or-terminal-give-up, and hand the\n * caller a `Promise<R>` that resolves on the first success or REJECTS with a\n * checkable {@link RetryExhaustedError} the moment the retry bound is hit.\n *\n * This is the retry-side parallel to `./await-terminal`. `runToTerminal` gives a\n * caller with a one-shot decision *machine* a fire-and-await `Promise<State>`\n * without wiring `observe`; this gives a caller with a one-shot fallible *port*\n * a fire-and-await `Promise<R>` without either hand-folding the\n * `./retry-backoff` primitives (`recordFailure` / `shouldRetry` / `nextDelayMs`)\n * into their own reducer each time, or standing up the full `./resilient-call`\n * verb contract (`init` + `attempt`/`succeed`/`fail`/`onTimer` + `subs` +\n * `handlers`) when they want retry only and none of cache / circuit / rate-limit\n * / deadline.\n *\n * It adds NO new runtime capability and NO new backoff math — the whole retry\n * decision is `./retry-backoff` exactly as `resilient-call`'s `backoff` verb\n * wires it:\n *   - `initRetry()` seeds the per-call attempt counter.\n *   - `recordFailure(retry, error)` folds each thrown failure (attempt++).\n *   - `shouldRetry(retry, policy)` is the terminal-at-`maxAttempts` bound — the\n *     `maxAttempts`-th recorded failure refuses another attempt (attempts\n *     `0 .. maxAttempts-1` run; the port is invoked at most `maxAttempts` times).\n *   - `nextDelayMs(retry, policy, rng)` is the exp+jitter+cap delay before the\n *     next attempt, computed on the incremented state — same call order as\n *     `resilient-call`.\n *\n * Where the clock / RNG live: injected, never read on the module's own behalf,\n * mirroring `retry-backoff`'s purity discipline. `rng` is an {@link Rng} (branded\n * `[0, 1)` via `asRng` at the caller boundary) threaded straight into\n * `nextDelayMs`; the wait itself is a `sleep(ms)` port defaulting to a real\n * `setTimeout`, injectable so a test can drive the backoff schedule\n * deterministically without touching wall-clock timers.\n *\n * Exhaustion is NEVER a silent swallow: at the bound the returned promise\n * rejects with {@link RetryExhaustedError} (carrying the attempt count and the\n * final failure), the retry-side dialect of `await-terminal`'s\n * `TerminalTimeoutError` — a distinct `instanceof`- and `_tag`-checkable\n * rejection.\n *\n * NOT a substrate primitive: it depends on nothing from `../index`, only on the\n * leaf `../retry-backoff` utility. Callers reach it via the\n * `@demlik/tea/retry-to-success` subpath.\n */\n\nimport {\n  defaultRng,\n  initRetry,\n  nextDelayMs,\n  type RetryPolicy,\n  type Rng,\n  recordFailure,\n  shouldRetry,\n} from \"../retry-backoff\";\n\n/**\n * Raised when `retryToSuccess` exhausts the retry bound without a success — the\n * `maxAttempts`-th recorded failure refuses another attempt. Follows the tea\n * error dialect (`override readonly name`) and carries a `_tag` discriminant, so\n * a caller can branch on it by `instanceof` or on the tag. It carries the number\n * of attempts made and the final failure (`lastError`) so the terminal give-up\n * is a distinct, checkable rejection — never a silent resolve, and never a\n * swallowed error.\n */\nexport class RetryExhaustedError extends Error {\n  override readonly name = \"RetryExhaustedError\";\n  readonly _tag = \"RetryExhaustedError\" as const;\n  constructor(\n    /** How many times the port was invoked before giving up (= `policy.maxAttempts`). */\n    public readonly attempts: number,\n    /** The failure the final attempt threw — carried, never interpreted. */\n    public readonly lastError: unknown,\n  ) {\n    super(\n      `@demlik/tea: retryToSuccess gave up after ${attempts} attempt(s) — the ` +\n        `bounded retry reached maxAttempts without a success. See .lastError ` +\n        `for the final failure.`,\n    );\n  }\n}\n\n/** Default wait: a real `setTimeout(ms)`, the sole clock read this module makes. */\nconst defaultSleep = (ms: number): Promise<void> =>\n  new Promise((resolve) => setTimeout(resolve, ms));\n\n/** Options for {@link retryToSuccess}. */\nexport interface RetryToSuccessOptions {\n  /**\n   * The `[0, 1)` jitter source threaded into `nextDelayMs`, branded via\n   * `asRng` at construction (a raw `() => number` is rejected by the type).\n   * Injected for deterministic backoff in tests; defaults to `defaultRng`\n   * (`Math.random`), read only at the delay boundary — never inside the loop's\n   * decision.\n   */\n  readonly rng?: Rng;\n  /**\n   * The wait between attempts, given the backoff delay in ms. Injectable so a\n   * test can drive the retry schedule without wall-clock timers (and assert the\n   * exact delays); defaults to a real `setTimeout`. The delay value is always\n   * `./retry-backoff`'s `nextDelayMs` — this port only realizes the wait.\n   */\n  readonly sleep?: (ms: number) => Promise<void>;\n}\n\n/**\n * Fire-and-await bounded retry: invoke the fallible `port`, and on each thrown\n * failure fold it through `./retry-backoff` — record it, and if the policy\n * still permits an attempt, back off `nextDelayMs` and retry; otherwise REJECT\n * with {@link RetryExhaustedError}. Resolves with the port's value on the first\n * success.\n *\n * The port is invoked at most `policy.maxAttempts` times (attempts\n * `0 .. maxAttempts-1`); the `maxAttempts`-th failure is terminal. Every failure\n * is either retried or surfaced on the rejection's `lastError` — none is\n * swallowed.\n *\n * @param port   the fallible work — throws on failure, resolves with `R` on success.\n * @param policy the bounded-retry curve (`baseMs` / `factor` / `capMs` /\n *               `maxAttempts` / `jitter`) from `./retry-backoff`.\n * @param opts   optional injected `rng` (jitter) and `sleep` (the wait) — see\n *               {@link RetryToSuccessOptions}.\n */\nexport async function retryToSuccess<R>(\n  port: () => Promise<R>,\n  policy: RetryPolicy,\n  opts: RetryToSuccessOptions = {},\n): Promise<R> {\n  const rng = opts.rng ?? defaultRng;\n  const sleep = opts.sleep ?? defaultSleep;\n\n  // The retry counter folds over `./retry-backoff` exactly as resilient-call's\n  // `backoff` verb does — no local attempt bookkeeping, no local backoff math.\n  let retry = initRetry();\n  for (;;) {\n    try {\n      return await port();\n    } catch (error) {\n      // Fold the failure first (attempt++), then consult the bound on the\n      // incremented state — same order as resilient-call so the semantics of\n      // `maxAttempts` are identical across both surfaces.\n      retry = recordFailure(retry, error);\n      if (!shouldRetry(retry, policy)) {\n        // Terminal give-up at the bound: reject, never swallow. `retry.attempt`\n        // is the number of failures = the number of port invocations made.\n        throw new RetryExhaustedError(retry.attempt, error);\n      }\n      await sleep(nextDelayMs(retry, policy, rng));\n    }\n  }\n}\n"]}