adaptive-concurrency 0.12.0 → 0.12.1

package/dist/Limiter.d.ts

@@ -73,7 +73,8 @@ export interface AllotmentUnavailableStrategy<ContextT> {
      */
     onLimitChanged?(oldLimit: number, newLimit: number): MaybePromise<void>;
 }
-export interface LimiterOptions<ContextT> {
+type AnyTimerHandle = NodeJS.Timeout | number;
+export interface LimiterOptions<ContextT, TimerHandle extends AnyTimerHandle = AnyTimerHandle> {
     limit?: AdaptiveLimit;
     /**
      * Clock function returning the current time in fractional milliseconds
@@ -104,6 +105,44 @@ export interface LimiterOptions<ContextT> {
      * heterogeneous workloads. When omitted, no operation name is provided.
      */
     operationNameFor?: (context: ContextT) => string | undefined;
+    /**
+     * Configuration for the recovery probe used to nudge the limit back above
+     * 0 when the underlying strategy has fallen there and there are no
+     * inflight requests left to produce samples.
+     *
+     * The limiter relies on the strategy itself to declare a base interval
+     * (via {@link AdaptiveLimit.probeFromZeroInterval}) which is grown
+     * exponentially across consecutive failed probes; the options here cap
+     * and jitter that interval. Strategies that do not implement the probe
+     * methods (e.g. {@link FixedLimit}, {@link VegasLimit}) get no recovery
+     * probing regardless of these options.
+     */
+    recoveryProbe?: {
+        /**
+         * Soft ceiling on a single probe's unjittered wait time, in
+         * milliseconds. The strategy-derived base interval is clamped to this
+         * value, then symmetric jitter is applied — so realized waits stay
+         * symmetric around `min(base, maxMs)` rather than being biased downward
+         * near the cap. Realized waits can therefore exceed `maxMs` by up to
+         * `jitter` (e.g. 20% with the default jitter). Default: 30_000.
+         */
+        maxMs?: number;
+        /**
+         * Symmetric jitter fraction applied to each probe interval (e.g. 0.2
+         * means `interval * uniform(0.8, 1.2)`). Must be in [0, 0.5).
+         * Default: 0.2.
+         */
+        jitter?: number;
+    };
+    /**
+     * Timer functions used to schedule recovery probes. Defaults to the
+     * environment's global `setTimeout` / `clearTimeout`. Tests can supply a
+     * fake to drive the probe state machine deterministically.
+     */
+    timer?: {
+        setTimeout(fn: () => void, ms: number): TimerHandle;
+        clearTimeout(handle: TimerHandle): void;
+    };
 }
 /**
  * Concurrency limiter with pluggable strategies for gating decisions and
@@ -111,7 +150,7 @@ export interface LimiterOptions<ContextT> {
  *
  * @typeParam ContextT Request context type (e.g. partition key).
  */
-export declare class Limiter<Context = void> {
+export declare class Limiter<Context = void, TimerHandle extends AnyTimerHandle = AnyTimerHandle> implements Disposable {
     private _inflight;
     private _limit;
     private readonly clock;
@@ -120,7 +159,38 @@ export declare class Limiter<Context = void> {
     private readonly rejectionStrategy;
     private readonly bypassResolver;
     private readonly operationNameFor;
-    private readonly acquireBypassedAllotment;
+    private readonly recoveryProbeMaxMs;
+    private readonly recoveryProbeJitter;
+    private readonly timer;
+    /**
+     * Number of consecutive recovery-probe *fires* since the last confirming
+     * success sample. Read by {@link maybeArmRecoveryProbe} to compute the
+     * exponentially-growing wait between probes:
+     *
+     *   `interval(n) = limitAlgorithm.probeFromZeroInterval(n)`
+     *
+     * Incremented inside the probe-timer callback (right after
+     * `applyProbeFromZero` runs), and reset only on a successful (non-drop,
+     * non-ignored) sample in `releaseAndRecordSuccess`.
+     *
+     * Note: this is "consecutive probe fires without a confirming success",
+     * **not** "consecutive failed probes". A probe firing successfully raises
+     * the limit to 1, but until traffic actually flows through and produces
+     * a non-drop sample, we have no evidence the system is healthy. Resetting
+     * on the limit-rise alone would cause the failure ladder to collapse to
+     * the base interval forever in a flapping-downstream scenario (probe →
+     * raise → drop → 0 → probe → ...), defeating the purpose of the
+     * exponential backoff.
+     *
+     * The downside is a benign quirk: after a probe successfully raises the
+     * limit, if no traffic arrives for a long time and then the limit later
+     * drops to 0 again, the next probe waits at `interval(N+1)` instead of
+     * `interval(0)`. This errs on the side of caution and is acceptable.
+     */
+    private probeFailures;
+    private probeTimerHandle;
+    private disposed;
+    private readonly unsubscribeFromLimit;
     private readonly successCounter;
     private readonly droppedCounter;
     private readonly ignoredCounter;
@@ -131,12 +201,67 @@ export declare class Limiter<Context = void> {
     private readonly acquireTimeOnSuccessDistribution;
     private readonly acquireTimeOnUnavailableDistribution;
     static makeDefaultLimit(): AdaptiveLimit;
-    constructor(options?: LimiterOptions<Context>);
+    constructor(options?: LimiterOptions<Context, TimerHandle>);
     acquire(options?: AcquireOptions<Context>): AcquireResult;
     private tryAcquireCore;
     private createAllotment;
+    private safeReadClockWithFallback;
+    /**
+     * Builds a per-acquire allotment for a bypassed request. Mirrors the
+     * one-shot `releaseStarted` semantics of {@link createAllotment} so that
+     * bypassed and non-bypassed allotments behave consistently when callers
+     * accidentally invoke a release method more than once.
+     *
+     * Bypassed acquires deliberately do not affect `_inflight` or the limit
+     * algorithm — `addSample` is never called — but they still emit the
+     * standard CALL_NAME counter, tagged with `operationNameFor` so per-
+     * operation dashboards include bypassed traffic.
+     */
+    private createBypassedAllotment;
     getLimit(): number;
     getInflight(): number;
+    /**
+     * Cancels any pending recovery-probe timer and unsubscribes from the
+     * underlying limit algorithm. Useful for clean shutdown in long-lived
+     * processes, especially when the underlying `AdaptiveLimit` outlives
+     * (or is shared across) limiters. Safe to call multiple times.
+     *
+     * Also exposed via `Symbol.dispose`, so a `Limiter` can be used with the
+     * `using` declaration:
+     * ```ts
+     * using limiter = new Limiter({ ... });
+     * ```
+     */
+    dispose(): void;
+    [Symbol.dispose](): void;
+    /**
+     * True when the limit has collapsed to 0 and there are no inflight
+     * requests left to produce samples. In this state, no future
+     * `addSample` call will ever arrive on its own, so the limiter has no
+     * way to climb back without an external nudge — i.e. a recovery probe.
+     */
+    private isStarvedForSamples;
+    private shouldArmRecoveryProbe;
+    /**
+     * Schedules a recovery probe if (and only if) the limiter is starved for
+     * samples (see {@link isStarvedForSamples}), the strategy supports
+     * probing, and no probe is already armed.
+     *
+     * Never throws. Errors from the limit algorithm's
+     * {@link AdaptiveLimit.probeFromZeroInterval}, the timer, or
+     * {@link AdaptiveLimit.applyProbeFromZero} are swallowed so callers in
+     * the release path / subscribe callback / constructor don't have to
+     * wrap each invocation. A failed probe arming simply means recovery
+     * may take longer; the next limit transition to 0 will re-attempt
+     * through the normal hooks.
+     */
+    private maybeArmRecoveryProbe;
+    /**
+     * Cancels the currently-armed recovery probe, if any. Idempotent and
+     * never throws (errors from the timer's `clearTimeout` are swallowed so
+     * callers don't have to wrap each invocation).
+     */
+    private cancelProbe;
 }
 export type RunCallbackArgs<ContextT> = {
     context: ContextT | undefined;
@@ -161,4 +286,5 @@ export interface LimitedFunction<ContextT> {
  * - Callback receives `{ context, signal }` from acquire options.
  */
 export declare function withLimiter<ContextT>(limiter: Limiter<ContextT>): LimitedFunction<ContextT>;
+export {};
 //# sourceMappingURL=Limiter.d.ts.map

package/dist/Limiter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Limiter.d.ts","sourceRoot":"","sources":["../src/Limiter.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Limiter.d.ts","sourceRoot":"","sources":["../src/Limiter.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE1D,OAAO,KAAK,EAIV,cAAc,EACf,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAGL,iBAAiB,EACjB,KAAK,SAAS,EACf,MAAM,gBAAgB,CAAC;AAExB,MAAM,MAAM,YAAY,CAAC,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;AAE7C;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC,CAAC;AAEhE,MAAM,WAAW,cAAc,CAAC,QAAQ,GAAG,IAAI;IAC7C,OAAO,CAAC,EAAE,QAAQ,CAAC;IACnB,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;CAClC;AAMD;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe,CAAC,QAAQ;IACvC;;;;OAIG;IACH,mBAAmB,CACjB,OAAO,EAAE,QAAQ,EACjB,KAAK,EAAE,YAAY,GAClB,YAAY,CAAC,OAAO,CAAC,CAAC;IAEzB;;;OAGG;IACH,mBAAmB,CAAC,OAAO,EAAE,QAAQ,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IAE3D;;;OAGG;IACH,cAAc,CAAC,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3D;AAED;;;;;GAKG;AACH,MAAM,WAAW,4BAA4B,CAAC,QAAQ;IACpD;;;;;;;;;;OAUG;IACH,sBAAsB,CACpB,OAAO,EAAE,QAAQ,EACjB,KAAK,EAAE,CAAC,OAAO,EAAE,QAAQ,KAAK,aAAa,EAC3C,MAAM,CAAC,EAAE,WAAW,GACnB,aAAa,CAAC;IAEjB;;;OAGG;IACH,mBAAmB,IAAI,YAAY,CAAC,IAAI,CAAC,CAAC;IAE1C;;;;OAIG;IACH,cAAc,CAAC,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;CACzE;AAOD,KAAK,cAAc,GAAG,MAAM,CAAC,OAAO,GAAG,MAAM,CAAC;AAE9C,MAAM,WAAW,cAAc,CAC7B,QAAQ,EACR,WAAW,SAAS,cAAc,GAAG,cAAc;IAEnD,KAAK,CAAC,EAAE,aAAa,CAAC;IAEtB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,MAAM,CAAC;IAErB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,cAAc,CAAC,EAAE,cAAc,CAAC;IAEhC;;;;OAIG;IACH,cAAc,CAAC,EAAE,CAAC,OAAO,EAAE,QAAQ,KAAK,OAAO,CAAC;IAEhD;;;OAGG;IACH,eAAe,CAAC,EAAE,eAAe,CAAC,QAAQ,CAAC,CAAC;IAE5C;;;OAGG;IACH,4BAA4B,CAAC,EAAE,4BAA4B,CAAC,QAAQ,CAAC,CAAC;IAEtE;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,CAAC,OAAO,EAAE,QAAQ,KAAK,MAAM,GAAG,SAAS,CAAC;IAE7D;;;;;;;;;;;OAWG;IACH,aAAa,CAAC,EAAE;QACd;;;;;;;WAOG;QACH,KAAK,CAAC,EAAE,MAAM,CAAC;QAEf;;;;WAIG;QACH,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,CAAC;IAEF;;;;OAIG;IACH,KAAK,CAAC,EAAE;QACN,UAAU,CAAC,EAAE,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,GAAG,WAAW,CAAC;QACpD,YAAY,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,CAAC;KACzC,CAAC;CACH;AAED;;;;;GAKG;AACH,qBAAa,OAAO,CAClB,OAAO,GAAG,IAAI,EACd,WAAW,SAAS,cAAc,GAAG,cAAc,CACnD,YAAW,UAAU;IACrB,OAAO,CAAC,SAAS,CAAK;IACtB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAe;IACrC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAgB;IAC/C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAA2B;IAC3D,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAEpB;IAEd,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA8C;IAC7E,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAEnB;IAEd,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAS;IAC5C,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAS;IAC7C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAGpB;IACF;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,gBAAgB,CAA6B;IACrD,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAa;IAElD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAU;IACzC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAU;IACzC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAU;IAEzC,OAAO,CAAC,QAAQ,CAAC,uBAAuB,CAAU;IAClD,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAU;IAC/C,OAAO,CAAC,QAAQ,CAAC,sBAAsB,CAAU;IAEjD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAQ;IACnC,OAAO,CAAC,QAAQ,CAAC,gCAAgC,CAAqB;IACtE,OAAO,CAAC,QAAQ,CAAC,oCAAoC,CAAqB;IAE1E,MAAM,CAAC,gBAAgB,IAAI,aAAa;gBAI5B,OAAO,GAAE,cAAc,CAAC,OAAO,EAAE,WAAW,CAAM;IAiIxD,OAAO,CAAC,OAAO,CAAC,EAAE,cAAc,CAAC,OAAO,CAAC,GAAG,aAAa;YAwFjD,cAAc;YAuBd,eAAe;IA2I7B,OAAO,CAAC,yBAAyB;IAQjC;;;;;;;;;;OAUG;IACH,OAAO,CAAC,uBAAuB;IAsC/B,QAAQ,IAAI,MAAM;IAIlB,WAAW,IAAI,MAAM;IAIrB;;;;;;;;;;;OAWG;IACH,OAAO,IAAI,IAAI;IAOf,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI;IAIxB;;;;;OAKG;IACH,OAAO,CAAC,mBAAmB;IAI3B,OAAO,CAAC,sBAAsB;IAU9B;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,qBAAqB;IA4D7B;;;;OAIG;IACH,OAAO,CAAC,WAAW;CAQpB;AAED,MAAM,MAAM,eAAe,CAAC,QAAQ,IAAI;IACtC,OAAO,EAAE,QAAQ,GAAG,SAAS,CAAC;IAC9B,MAAM,EAAE,WAAW,GAAG,SAAS,CAAC;CACjC,CAAC;AACF,MAAM,WAAW,eAAe,CAAC,QAAQ;IACvC,CAAC,CAAC,EAAE,CAAC,SAAS,KAAK,GAAG,KAAK,EACzB,EAAE,EAAE,CACF,IAAI,EAAE,eAAe,CAAC,QAAQ,CAAC,KAC5B,CAAC,GAAG,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GACtD,OAAO,CAAC,CAAC,GAAG,OAAO,iBAAiB,CAAC,CAAC;IAEzC,CAAC,CAAC,EAAE,CAAC,SAAS,KAAK,GAAG,KAAK,EACzB,OAAO,EAAE,cAAc,CAAC,QAAQ,CAAC,EACjC,EAAE,EAAE,CACF,IAAI,EAAE,eAAe,CAAC,QAAQ,CAAC,KAC5B,CAAC,GAAG,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GACtD,OAAO,CAAC,CAAC,GAAG,OAAO,iBAAiB,CAAC,CAAC;CAC1C;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAClC,OAAO,EAAE,OAAO,CAAC,QAAQ,CAAC,GACzB,eAAe,CAAC,QAAQ,CAAC,CAqE3B"}

package/dist/Limiter.js

@@ -21,7 +21,38 @@ export class Limiter {
     rejectionStrategy;
     bypassResolver;
     operationNameFor;
-    acquireBypassedAllotment;
+    recoveryProbeMaxMs;
+    recoveryProbeJitter;
+    timer;
+    /**
+     * Number of consecutive recovery-probe *fires* since the last confirming
+     * success sample. Read by {@link maybeArmRecoveryProbe} to compute the
+     * exponentially-growing wait between probes:
+     *
+     *   `interval(n) = limitAlgorithm.probeFromZeroInterval(n)`
+     *
+     * Incremented inside the probe-timer callback (right after
+     * `applyProbeFromZero` runs), and reset only on a successful (non-drop,
+     * non-ignored) sample in `releaseAndRecordSuccess`.
+     *
+     * Note: this is "consecutive probe fires without a confirming success",
+     * **not** "consecutive failed probes". A probe firing successfully raises
+     * the limit to 1, but until traffic actually flows through and produces
+     * a non-drop sample, we have no evidence the system is healthy. Resetting
+     * on the limit-rise alone would cause the failure ladder to collapse to
+     * the base interval forever in a flapping-downstream scenario (probe →
+     * raise → drop → 0 → probe → ...), defeating the purpose of the
+     * exponential backoff.
+     *
+     * The downside is a benign quirk: after a probe successfully raises the
+     * limit, if no traffic arrives for a long time and then the limit later
+     * drops to 0 again, the next probe waits at `interval(N+1)` instead of
+     * `interval(0)`. This errs on the side of caution and is acceptable.
+     */
+    probeFailures = 0;
+    probeTimerHandle;
+    disposed = false;
+    unsubscribeFromLimit;
     successCounter;
     droppedCounter;
     ignoredCounter;
@@ -43,12 +74,57 @@ export class Limiter {
         this.acquireStrategy =
             options.acquireStrategy ?? new SemaphoreStrategy(this._limit);
         this.rejectionStrategy = options.allotmentUnavailableStrategy;
-        this.limitAlgorithm.subscribe((newLimit) => {
+        this.recoveryProbeMaxMs = options.recoveryProbe?.maxMs ?? 30_000;
+        this.recoveryProbeJitter = options.recoveryProbe?.jitter ?? 0.2;
+        if (!Number.isFinite(this.recoveryProbeMaxMs) ||
+            this.recoveryProbeMaxMs <= 0) {
+            // Reject NaN / ±Infinity along with non-positive values so a misconfigured
+            // probe interval can't silently degrade into a near-busy-loop (Node coerces
+            // NaN to ~1ms in `setTimeout(fn, NaN)`) or a non-finite wait.
+            throw new RangeError("recoveryProbe.maxMs must be a finite number > 0");
+        }
+        if (!Number.isFinite(this.recoveryProbeJitter) ||
+            this.recoveryProbeJitter < 0 ||
+            this.recoveryProbeJitter >= 0.5) {
+            throw new RangeError("recoveryProbe.jitter must be a finite number in [0, 0.5)");
+        }
+        this.timer = options.timer ?? {
+            setTimeout: (fn, ms) => globalThis.setTimeout(fn, ms),
+            clearTimeout: (handle) => globalThis.clearTimeout(handle),
+        };
+        this.unsubscribeFromLimit = this.limitAlgorithm.subscribe((newLimit) => {
             const oldLimit = this._limit;
-            this._limit = newLimit;
-            this.limitGauge.record(newLimit);
+            // Notify the acquire strategy FIRST. If it throws atomically (i.e.
+            // refuses without mutating its own state), we want `_limit`, the
+            // gauge, the rejection strategy, and the recovery probe to all stay
+            // pinned to the old value — there's no partial-commit to clean up.
+            //
+            // If the strategy throws after partially mutating its state, the
+            // limiter and strategy are inconsistent either way; we still don't
+            // commit `_limit` here, since we'd just be guessing at the strategy's
+            // post-throw state. The error propagates to whatever drove the limit
+            // change (caller-visible from `setLimit`, swallowed by the release-
+            // path `try { addSample }` wrapper from `releaseAndRecord*`).
             this.acquireStrategy.onLimitChanged?.(oldLimit, newLimit);
-            void this.rejectionStrategy?.onLimitChanged?.(oldLimit, newLimit);
+            this._limit = newLimit;
+            try {
+                this.limitGauge.record(newLimit);
+            }
+            catch {
+                // Best-effort metric recording; a misbehaving registry must not
+                // prevent recovery probe arming below.
+            }
+            // `onLimitChanged` may return a rejecting Promise; using `void` would
+            // surface it as an unhandled rejection (process-terminating in modern
+            // Node by default). Wrap in `fireAndForget` so any rejection is
+            // swallowed consistently with the release-path try/catch idiom.
+            void fireAndForget(() => this.rejectionStrategy?.onLimitChanged?.(oldLimit, newLimit));
+            if (newLimit === 0) {
+                this.maybeArmRecoveryProbe();
+            }
+            else {
+                this.cancelProbe();
+            }
         });
         const registry = options.metricRegistry ?? NoopMetricRegistry;
         const limiterName = options.name ?? `unnamed-${++idCounter}`;
@@ -72,27 +148,25 @@ export class Limiter {
         this.acquireBypassedCounter = registry.counter(MetricIds.ACQUIRE_ATTEMPT_NAME, { id: limiterName, status: "bypassed" });
         this.acquireTimeOnSuccessDistribution = registry.distribution(MetricIds.ACQUIRE_TIME_NAME, { id: limiterName, status: "success" });
         this.acquireTimeOnUnavailableDistribution = registry.distribution(MetricIds.ACQUIRE_TIME_NAME, { id: limiterName, status: "unavailable" });
-        this.acquireBypassedAllotment = {
-            releaseAndRecordSuccess: async () => {
-                this.successCounter.add(1);
-            },
-            releaseAndIgnore: async () => {
-                this.ignoredCounter.add(1);
-            },
-            releaseAndRecordDropped: async () => {
-                this.droppedCounter.add(1);
-            },
-        };
         // Emit metric for initial limit.
         this.limitGauge.record(this._limit);
+        // If the underlying strategy starts at 0 (e.g.
+        // `new AIMDLimit({ initialLimit: 0, minLimit: 0 })` or a deserialized
+        // snapshot), the limiter is born starved-for-samples. The subscription
+        // and release-path hooks only fire on transitions, so without this we'd
+        // be stuck at 0 forever — no acquires can land while limit is 0, and no
+        // samples can arrive without acquires.
+        this.maybeArmRecoveryProbe();
     }
     async acquire(options) {
         if (options?.signal?.aborted)
             return undefined;
         const ctx = (options?.context ?? undefined);
         if (this.bypassResolver?.(ctx)) {
-            this.acquireBypassedCounter.add(1);
-            return this.acquireBypassedAllotment;
+            void fireAndForget(() => {
+                this.acquireBypassedCounter.add(1);
+            });
+            return this.createBypassedAllotment(ctx);
         }
         const acquireStart = this.clock();
         const state = {
@@ -117,17 +191,35 @@ export class Limiter {
                 }
                 return this.tryAcquireCore(retryCtx);
             }, options?.signal);
-            const distribution = result
-                ? this.acquireTimeOnSuccessDistribution
-                : this.acquireTimeOnUnavailableDistribution;
-            distribution.addSample(this.clock() - acquireStart);
+            try {
+                const distribution = result
+                    ? this.acquireTimeOnSuccessDistribution
+                    : this.acquireTimeOnUnavailableDistribution;
+                distribution.addSample(this.clock() - acquireStart);
+            }
+            catch {
+                // Best-effort metric update: do not fail the acquire path after
+                // capacity has already been acquired via the rejection strategy.
+            }
+            if (result && options?.signal?.aborted) {
+                // The rejection strategy may have acquired via retry just before the
+                // signal aborted. Return the caller's capacity to the limiter.
+                await result.releaseAndIgnore();
+                return undefined;
+            }
             return result;
         }
-        this.acquireSucceededCounter.add(1);
-        const allotment = this.createAllotment(ctx);
-        // Record the acquire time as a success, since we did actually succeed even
-        // if we abort below.
-        this.acquireTimeOnSuccessDistribution.addSample(this.clock() - acquireStart);
+        const allotment = await this.createAllotment(ctx);
+        try {
+            this.acquireSucceededCounter.add(1);
+            // Record the acquire time as a success, since we did actually succeed even
+            // if we abort below.
+            this.acquireTimeOnSuccessDistribution.addSample(this.clock() - acquireStart);
+        }
+        catch {
+            // Best-effort metric update: do not fail the acquire path after
+            // capacity has already been reserved and an allotment created.
+        }
         if (options?.signal?.aborted) {
             // here, we did acquire, so we need to try to cleanup.
             await allotment.releaseAndIgnore();
@@ -144,13 +236,37 @@ export class Limiter {
             this.acquireFailedCounter.add(1);
             return undefined;
         }
-        this.acquireSucceededCounter.add(1);
-        return this.createAllotment(ctx);
+        // increment counter only after we've successfully acquired the allotment
+        const allotment = await this.createAllotment(ctx);
+        try {
+            this.acquireSucceededCounter.add(1);
+        }
+        catch {
+            // Best-effort metric update: do not fail the acquire path after
+            // capacity has already been reserved and an allotment created.
+        }
+        return allotment;
     }
-    createAllotment(ctx) {
-        const startTime = this.clock();
+    async createAllotment(ctx) {
+        // Capture quantities derived from user-supplied callbacks BEFORE
+        // touching `_inflight`. If `clock()` or `operationNameFor()` throws,
+        // the strategy has already reserved a slot in `tryAcquireAllotment`
+        // and we must roll that reservation back — otherwise the permit is
+        // permanently leaked and concurrent admission silently degrades.
+        let startTime;
+        let operationName;
+        try {
+            startTime = this.clock();
+            operationName = this.operationNameFor?.(ctx);
+        }
+        catch (err) {
+            // Best-effort release of the strategy reservation. We're about to
+            // throw to the caller of `acquire()`, who will not get an allotment
+            // to release manually.
+            await fireAndForget(() => this.acquireStrategy.onAllotmentReleased(ctx));
+            throw err;
+        }
         const currentInflight = ++this._inflight;
-        const operationName = this.operationNameFor?.(ctx);
         const incrementTags = operationName
             ? { [MetricIds.OPERATION_NAME_TAG]: operationName }
             : {};
@@ -164,10 +280,24 @@ export class Limiter {
                 if (releaseStarted)
                     return;
                 releaseStarted = true;
-                const endTime = this.clock();
+                // Every interaction with user-supplied code (metrics, clock, the
+                // limit algorithm, the strategies) is wrapped in try/catch so that
+                // a single misbehaving collaborator can't leave the strategy with
+                // a leaked permit or stall queued waiters in a blocking rejection
+                // strategy. This release method must never throw or reject (per
+                // `LimitAllotment` contract).
+                const endTime = this.safeReadClockWithFallback(startTime);
                 const rtt = endTime - startTime;
                 this._inflight--;
-                this.successCounter.add(1, incrementTags);
+                void fireAndForget(() => {
+                    this.successCounter.add(1, incrementTags);
+                });
+                // A successful sample is our signal that requests are flowing
+                // again: clear any pending probe and reset the failure ladder.
+                // (See the docstring on `probeFailures` for why neither is reset
+                // on the limit-rise from `applyProbeFromZero` itself.)
+                this.probeFailures = 0;
+                this.cancelProbe();
                 // If one onAllotmentReleased call fails, hard to know what to do here.
                 // We're in some kind of inconsistent state, but we probably have to
                 // soldier on.
@@ -183,13 +313,23 @@ export class Limiter {
                     await this.rejectionStrategy?.onAllotmentReleased();
                 }
                 catch { }
+                // Needed because some limit implementations could keep the limit at 0
+                // even after a successful sample (e.g., a GradientLimit where the
+                // successful sample's RTT was slow), so we need to re-arm the probe in
+                // that case (and won't get a limit subscription callback).
+                this.maybeArmRecoveryProbe();
             },
             releaseAndIgnore: async () => {
                 if (releaseStarted)
                     return;
                 releaseStarted = true;
                 this._inflight--;
-                this.ignoredCounter.add(1, incrementTags);
+                void fireAndForget(() => {
+                    this.ignoredCounter.add(1, incrementTags);
+                });
+                // Decrementing inflight above, possibly to 0, means we might need to
+                // arm the probe now.
+                this.maybeArmRecoveryProbe();
                 // If one onAllotmentReleased call fails, hard to know what to do here.
                 // We're in some kind of inconsistent state, but we probably have to
                 // soldier on.
@@ -206,10 +346,14 @@ export class Limiter {
                 if (releaseStarted)
                     return;
                 releaseStarted = true;
-                const endTime = this.clock();
+                const endTime = this.safeReadClockWithFallback(startTime);
                 const rtt = endTime - startTime;
                 this._inflight--;
-                this.droppedCounter.add(1, incrementTags);
+                void fireAndForget(() => {
+                    this.droppedCounter.add(1, incrementTags);
+                });
+                // Needed after the inflight decrement like in releaseAndIgnore.
+                this.maybeArmRecoveryProbe();
                 // If one onAllotmentReleased call fails, hard to know what to do here.
                 // We're in some kind of inconsistent state, but we probably have to
                 // soldier on.
@@ -228,12 +372,191 @@ export class Limiter {
             },
         };
     }
+    safeReadClockWithFallback(fallback) {
+        try {
+            return this.clock();
+        }
+        catch {
+            return fallback;
+        }
+    }
+    /**
+     * Builds a per-acquire allotment for a bypassed request. Mirrors the
+     * one-shot `releaseStarted` semantics of {@link createAllotment} so that
+     * bypassed and non-bypassed allotments behave consistently when callers
+     * accidentally invoke a release method more than once.
+     *
+     * Bypassed acquires deliberately do not affect `_inflight` or the limit
+     * algorithm — `addSample` is never called — but they still emit the
+     * standard CALL_NAME counter, tagged with `operationNameFor` so per-
+     * operation dashboards include bypassed traffic.
+     */
+    createBypassedAllotment(ctx) {
+        let operationName;
+        try {
+            operationName = this.operationNameFor?.(ctx);
+        }
+        catch {
+            // A misbehaving `operationNameFor` shouldn't break the bypass path;
+            // just emit untagged metrics in that case.
+        }
+        const incrementTags = operationName
+            ? { [MetricIds.OPERATION_NAME_TAG]: operationName }
+            : {};
+        let releaseStarted = false;
+        return {
+            releaseAndRecordSuccess: async () => {
+                if (releaseStarted)
+                    return;
+                releaseStarted = true;
+                void fireAndForget(() => {
+                    this.successCounter.add(1, incrementTags);
+                });
+            },
+            releaseAndIgnore: async () => {
+                if (releaseStarted)
+                    return;
+                releaseStarted = true;
+                void fireAndForget(() => {
+                    this.ignoredCounter.add(1, incrementTags);
+                });
+            },
+            releaseAndRecordDropped: async () => {
+                if (releaseStarted)
+                    return;
+                releaseStarted = true;
+                void fireAndForget(() => {
+                    this.droppedCounter.add(1, incrementTags);
+                });
+            },
+        };
+    }
     getLimit() {
         return this._limit;
     }
     getInflight() {
         return this._inflight;
     }
+    /**
+     * Cancels any pending recovery-probe timer and unsubscribes from the
+     * underlying limit algorithm. Useful for clean shutdown in long-lived
+     * processes, especially when the underlying `AdaptiveLimit` outlives
+     * (or is shared across) limiters. Safe to call multiple times.
+     *
+     * Also exposed via `Symbol.dispose`, so a `Limiter` can be used with the
+     * `using` declaration:
+     * ```ts
+     * using limiter = new Limiter({ ... });
+     * ```
+     */
+    dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        this.cancelProbe();
+        this.unsubscribeFromLimit();
+    }
+    [Symbol.dispose]() {
+        this.dispose();
+    }
+    /**
+     * True when the limit has collapsed to 0 and there are no inflight
+     * requests left to produce samples. In this state, no future
+     * `addSample` call will ever arrive on its own, so the limiter has no
+     * way to climb back without an external nudge — i.e. a recovery probe.
+     */
+    isStarvedForSamples() {
+        return this._limit === 0 && this._inflight === 0;
+    }
+    shouldArmRecoveryProbe() {
+        return (!this.disposed &&
+            this.probeTimerHandle === undefined &&
+            this.isStarvedForSamples() &&
+            typeof this.limitAlgorithm.probeFromZeroInterval === "function" &&
+            typeof this.limitAlgorithm.applyProbeFromZero === "function");
+    }
+    /**
+     * Schedules a recovery probe if (and only if) the limiter is starved for
+     * samples (see {@link isStarvedForSamples}), the strategy supports
+     * probing, and no probe is already armed.
+     *
+     * Never throws. Errors from the limit algorithm's
+     * {@link AdaptiveLimit.probeFromZeroInterval}, the timer, or
+     * {@link AdaptiveLimit.applyProbeFromZero} are swallowed so callers in
+     * the release path / subscribe callback / constructor don't have to
+     * wrap each invocation. A failed probe arming simply means recovery
+     * may take longer; the next limit transition to 0 will re-attempt
+     * through the normal hooks.
+     */
+    maybeArmRecoveryProbe() {
+        try {
+            if (!this.shouldArmRecoveryProbe()) {
+                return;
+            }
+            // not-null assertion is safe because of the shouldArmRecoveryProbe()
+            // guard, but hard to prove to TS.
+            const raw = this.limitAlgorithm.probeFromZeroInterval(this.probeFailures);
+            // Cap before the finite check so that an exponential backoff that
+            // overflows to Infinity is clamped to recoveryProbeMaxMs instead of
+            // silently disabling recovery probing.
+            const capped = Math.min(this.recoveryProbeMaxMs, raw);
+            if (!Number.isFinite(capped) || capped <= 0)
+                return;
+            const jitterFactor = 1 + (Math.random() * 2 - 1) * this.recoveryProbeJitter;
+            const ms = capped * jitterFactor;
+            this.probeTimerHandle = this.timer.setTimeout(() => {
+                this.probeTimerHandle = undefined;
+                if (this.disposed)
+                    return;
+                if (this._limit !== 0) {
+                    // For the strategies in this package the limit should be unable to
+                    // climb back from 0 without a sample, and samples can't arrive while
+                    // we're starved, so this branch *seems* unreachable. It isn't,
+                    // though: a custom `AdaptiveLimit` (or `WindowedLimit` wrapping one)
+                    // could mutate its limit from a timer of its own or via an external
+                    // `setLimit`-style hook; tests / harnesses can call `addSample`
+                    // directly; and a maintainer could add a non-completing path that
+                    // injects samples. None of those should crash the process, so we
+                    // simply abandon the probe — the next limit transition to 0 will
+                    // re-arm it through the normal hooks.
+                    return;
+                }
+                try {
+                    // not-null assertion is safe because of the shouldArmRecoveryProbe()
+                    // guard, but hard to prove to TS.
+                    this.limitAlgorithm.applyProbeFromZero();
+                    // Increment *after* the apply (and the synchronous subscription it
+                    // triggers): see the docstring on `probeFailures`. Notably we do NOT
+                    // reset on the limit-rise caused by `applyProbeFromZero`, because
+                    // the rise alone doesn't confirm any traffic actually flowed
+                    // through. A confirming success sample in `releaseAndRecordSuccess`
+                    // is what eventually clears this.
+                    this.probeFailures++;
+                }
+                catch {
+                    // Ignore — see the method docstring. Future samples will re-trigger
+                    // probe arming through the normal hooks.
+                }
+            }, ms);
+        }
+        catch {
+            // Ignore — see the method docstring.
+        }
+    }
+    /**
+     * Cancels the currently-armed recovery probe, if any. Idempotent and
+     * never throws (errors from the timer's `clearTimeout` are swallowed so
+     * callers don't have to wrap each invocation).
+     */
+    cancelProbe() {
+        if (this.probeTimerHandle === undefined)
+            return;
+        const handle = this.probeTimerHandle;
+        this.probeTimerHandle = undefined;
+        void fireAndForget(() => {
+            this.timer.clearTimeout(handle);
+        });
+    }
 }
 /**
  * Creates a helper that runs callbacks under acquired limiter allotments.
@@ -262,7 +585,7 @@ export function withLimiter(limiter) {
             return QuotaNotAvailable;
         }
         const [result] = await Promise.allSettled([
-            fn({ context: options?.context, signal: options?.signal }),
+            Promise.resolve().then(() => fn({ context: options?.context, signal: options?.signal })),
         ]);
         if (result.status === "rejected") {
             if (isAdaptiveTimeoutError(result.reason)) {
@@ -293,3 +616,11 @@ export function withLimiter(limiter) {
     }
     return limited;
 }
+async function fireAndForget(fn) {
+    try {
+        await fn();
+    }
+    catch {
+        // Ignore errors
+    }
+}

package/dist/limit/AIMDLimit.d.ts

@@ -27,6 +27,18 @@ export interface AIMDLimitOptions {
      * Must be in [0, 0.05]. Default: 0.02.
      */
     backoffJitter?: number;
+    /**
+     * Configuration for the limiter's recovery probe when the limit reaches 0.
+     * See {@link AdaptiveLimit.probeFromZeroInterval}.
+     */
+    recoveryProbe?: {
+        /**
+         * Base interval in milliseconds between probes. The probe interval grows
+         * as `baseMs * 2^failedProbes`, then is jittered and capped by the
+         * limiter. Default: the configured `timeout`.
+         */
+        baseMs?: number;
+    };
 }
 export declare class AIMDLimit implements AdaptiveLimit {
     private _limit;
@@ -36,7 +48,10 @@ export declare class AIMDLimit implements AdaptiveLimit {
     private readonly minLimit;
     private readonly maxLimit;
     private readonly backoffJitter;
+    private readonly recoveryProbeBaseMs;
     constructor(options?: AIMDLimitOptions);
+    probeFromZeroInterval(failedProbes: number): number;
+    applyProbeFromZero(): void;
     addSample(_startTime: number, rtt: number, inflight: number, didDrop: boolean, _operationName?: string): void;
     get currentLimit(): number;
     private applyNewLimit;

package/dist/limit/AIMDLimit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AIMDLimit.d.ts","sourceRoot":"","sources":["../../src/limit/AIMDLimit.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;;;;;;OAQG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,qBAAa,SAAU,YAAW,aAAa;IAC7C,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAqB;IAEpD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;gBAE3B,OAAO,GAAE,gBAAqB;IA0B1C,SAAS,CACP,UAAU,EAAE,MAAM,EAClB,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,OAAO,EAChB,cAAc,CAAC,EAAE,MAAM,GACtB,IAAI;IAuBP,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED,OAAO,CAAC,aAAa;IAOrB,SAAS,CACP,QAAQ,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,EACpC,OAAO,GAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAO,GACrC,MAAM,IAAI;IAIb,QAAQ,IAAI,MAAM;CAGnB"}
+{"version":3,"file":"AIMDLimit.d.ts","sourceRoot":"","sources":["../../src/limit/AIMDLimit.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;;;;;;OAQG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB;;;OAGG;IACH,aAAa,CAAC,EAAE;QACd;;;;WAIG;QACH,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,CAAC;CACH;AAED,qBAAa,SAAU,YAAW,aAAa;IAC7C,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAqB;IAEpD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAS;gBAEjC,OAAO,GAAE,gBAAqB;IA8B1C,qBAAqB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM;IAInD,kBAAkB,IAAI,IAAI;IAI1B,SAAS,CACP,UAAU,EAAE,MAAM,EAClB,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,OAAO,EAChB,cAAc,CAAC,EAAE,MAAM,GACtB,IAAI;IAuBP,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED,OAAO,CAAC,aAAa;IAOrB,SAAS,CACP,QAAQ,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,EACpC,OAAO,GAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAO,GACrC,MAAM,IAAI;IAIb,QAAQ,IAAI,MAAM;CAGnB"}

package/dist/limit/AIMDLimit.js

@@ -7,6 +7,7 @@ export class AIMDLimit {
     minLimit;
     maxLimit;
     backoffJitter;
+    recoveryProbeBaseMs;
     constructor(options = {}) {
         const initialLimit = options.initialLimit ?? 20;
         this._limit = initialLimit;
@@ -15,18 +16,28 @@ export class AIMDLimit {
         this.minLimit = options.minLimit ?? 20;
         this.maxLimit = options.maxLimit ?? 200;
         this.backoffJitter = options.backoffJitter ?? 0.02;
+        this.recoveryProbeBaseMs = options.recoveryProbe?.baseMs ?? this.timeout;
         if (this.backoffRatio >= 1.0 || this.backoffRatio < 0.5) {
-            throw new Error("Backoff ratio must be in the range [0.5, 1.0)");
+            throw new RangeError("Backoff ratio must be in the range [0.5, 1.0)");
         }
         if (this.timeout <= 0) {
-            throw new Error("Timeout must be positive");
+            throw new RangeError("Timeout must be positive");
         }
         if (this.backoffJitter < 0 || this.backoffJitter > 0.05) {
-            throw new Error("backoffJitter must be in the range [0, 0.05]");
+            throw new RangeError("backoffJitter must be in the range [0, 0.05]");
         }
         if (this.backoffRatio + this.backoffJitter >= 1.0) {
-            throw new Error("backoffRatio + backoffJitter must be < 1.0 to guarantee the limit decreases on drop");
+            throw new RangeError("backoffRatio + backoffJitter must be < 1.0 to guarantee the limit decreases on drop");
         }
+        if (!(this.recoveryProbeBaseMs > 0)) {
+            throw new RangeError("recoveryProbe.baseMs must be > 0");
+        }
+    }
+    probeFromZeroInterval(failedProbes) {
+        return this.recoveryProbeBaseMs * Math.pow(2, failedProbes);
+    }
+    applyProbeFromZero() {
+        this.applyNewLimit(1);
     }
     addSample(_startTime, rtt, inflight, didDrop, _operationName) {
         let currentLimit = this._limit;

package/dist/limit/GradientLimit.d.ts

@@ -80,6 +80,19 @@ export interface Gradient2LimitOptions {
      * Default: 600
      */
     longWindow?: number;
+    /**
+     * Configuration for the limiter's recovery probe when the limit reaches 0.
+     * See {@link AdaptiveLimit.probeFromZeroInterval}.
+     */
+    recoveryProbe?: {
+        /**
+         * Fallback base interval in milliseconds between probes, used when the
+         * algorithm has no usable RTT estimate (e.g. before any sample has been
+         * recorded). When an RTT estimate is available the probe interval is
+         * derived from `longRtt * 5`. Default: 1000.
+         */
+        baseMs?: number;
+    };
     metricRegistry?: MetricRegistry;
 }
 export declare class GradientLimit implements AdaptiveLimit {
@@ -104,11 +117,14 @@ export declare class GradientLimit implements AdaptiveLimit {
     private readonly queueSize;
     private readonly smoothing;
     private readonly tolerance;
+    private readonly recoveryProbeBaseMs;
     private readonly longRttSampleListener;
     private readonly shortRttSampleListener;
     private readonly queueSizeSampleListener;
     constructor(options?: Gradient2LimitOptions);
     addSample(_startTime: number, rtt: number, inflight: number, _didDrop: boolean, _operationName?: string): void;
+    probeFromZeroInterval(failedProbes: number): number;
+    applyProbeFromZero(): void;
     get currentLimit(): number;
     private applyNewLimit;
     subscribe(consumer: (newLimit: number) => void, options?: {

package/dist/limit/GradientLimit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GradientLimit.d.ts","sourceRoot":"","sources":["../../src/limit/GradientLimit.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAsB,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAI/E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,MAAM,WAAW,qBAAqB;IACpC,qDAAqD;IACrD,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,WAAW,EAAE,MAAM,KAAK,MAAM,CAAC,CAAC;IAEvD;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,cAAc,CAAC,EAAE,cAAc,CAAC;CACjC;AAED,qBAAa,aAAc,YAAW,aAAa;IACjD,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAqB;IAEpD,yDAAyD;IACzD,OAAO,CAAC,cAAc,CAAS;IAE/B;;;OAGG;IACH,OAAO,CAAC,OAAO,CAAK;IAEpB;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqB;IAE7C,8DAA8D;IAC9D,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAElC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAkC;IAC5D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IAEnC,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAAqB;IAC3D,OAAO,CAAC,QAAQ,CAAC,sBAAsB,CAAqB;IAC5D,OAAO,CAAC,QAAQ,CAAC,uBAAuB,CAAqB;gBAEjD,OAAO,GAAE,qBAA0B;IA4B/C,SAAS,CACP,UAAU,EAAE,MAAM,EAClB,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,OAAO,EACjB,cAAc,CAAC,EAAE,MAAM,GACtB,IAAI;IASP,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED,OAAO,CAAC,aAAa;IAOrB,SAAS,CACP,QAAQ,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,EACpC,OAAO,GAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAO,GACrC,MAAM,IAAI;IAIb,OAAO,CAAC,yBAAyB;IA0CjC,UAAU,IAAI,MAAM;IAIpB,YAAY,IAAI,MAAM;IAItB,QAAQ,IAAI,MAAM;CAGnB"}
+{"version":3,"file":"GradientLimit.d.ts","sourceRoot":"","sources":["../../src/limit/GradientLimit.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAsB,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAI/E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,MAAM,WAAW,qBAAqB;IACpC,qDAAqD;IACrD,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,WAAW,EAAE,MAAM,KAAK,MAAM,CAAC,CAAC;IAEvD;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,aAAa,CAAC,EAAE;QACd;;;;;WAKG;QACH,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,CAAC;IAEF,cAAc,CAAC,EAAE,cAAc,CAAC;CACjC;AAED,qBAAa,aAAc,YAAW,aAAa;IACjD,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAqB;IAEpD,yDAAyD;IACzD,OAAO,CAAC,cAAc,CAAS;IAE/B;;;OAGG;IACH,OAAO,CAAC,OAAO,CAAK;IAEpB;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqB;IAE7C,8DAA8D;IAC9D,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAElC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAkC;IAC5D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAS;IAE7C,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAAqB;IAC3D,OAAO,CAAC,QAAQ,CAAC,sBAAsB,CAAqB;IAC5D,OAAO,CAAC,QAAQ,CAAC,uBAAuB,CAAqB;gBAEjD,OAAO,GAAE,qBAA0B;IAgC/C,SAAS,CACP,UAAU,EAAE,MAAM,EAClB,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,OAAO,EACjB,cAAc,CAAC,EAAE,MAAM,GACtB,IAAI;IASP,qBAAqB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM;IAMnD,kBAAkB,IAAI,IAAI;IAK1B,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED,OAAO,CAAC,aAAa;IAOrB,SAAS,CACP,QAAQ,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,EACpC,OAAO,GAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAO,GACrC,MAAM,IAAI;IAIb,OAAO,CAAC,yBAAyB;IA0CjC,UAAU,IAAI,MAAM;IAIpB,YAAY,IAAI,MAAM;IAItB,QAAQ,IAAI,MAAM;CAGnB"}

package/dist/limit/GradientLimit.js

@@ -24,6 +24,7 @@ export class GradientLimit {
     queueSize;
     smoothing;
     tolerance;
+    recoveryProbeBaseMs;
     longRttSampleListener;
     shortRttSampleListener;
     queueSizeSampleListener;
@@ -36,8 +37,12 @@ export class GradientLimit {
         this.smoothing = options.smoothing ?? 0.2;
         this.tolerance = options.rttTolerance ?? 1.5;
         this.longRtt = new ExpMovingAverage(options.longWindow ?? 600, 10);
+        this.recoveryProbeBaseMs = options.recoveryProbe?.baseMs ?? 1000;
         if (options.rttTolerance !== undefined && options.rttTolerance < 1.0) {
-            throw new Error("Tolerance must be >= 1.0");
+            throw new RangeError("Tolerance must be >= 1.0");
+        }
+        if (!(this.recoveryProbeBaseMs > 0)) {
+            throw new RangeError("recoveryProbe.baseMs must be > 0");
         }
         const qs = options.queueSize ?? 4;
         this.queueSize = typeof qs === "number" ? () => qs : qs;
@@ -52,6 +57,15 @@ export class GradientLimit {
         const newLimit = Math.floor(newLimitNoFloor);
         this.applyNewLimit(newLimit);
     }
+    probeFromZeroInterval(failedProbes) {
+        const longRtt = this.longRtt.currentValue;
+        const base = longRtt > 0 ? longRtt * 5 : this.recoveryProbeBaseMs;
+        return base * Math.pow(2, failedProbes);
+    }
+    applyProbeFromZero() {
+        this.estimatedLimit = 1;
+        this.applyNewLimit(1);
+    }
     get currentLimit() {
         return this._limit;
     }

package/dist/limit/GroupAwareLimit.d.ts

@@ -41,6 +41,7 @@ export declare class GroupAwareLimit implements AdaptiveLimit {
     private readonly recentRttWindow;
     private readonly minGroupSamples;
     private readonly clock;
+    private readonly recoveryProbeBaseMs;
     private readonly registry;
     private readonly congestionSignalGauge;
     private readonly warmedGroupsCountGauge;
@@ -59,9 +60,24 @@ export declare class GroupAwareLimit implements AdaptiveLimit {
         minGroupSamples?: number;
         clock?: () => number;
         metricRegistry?: MetricRegistry;
+        /**
+         * Configuration for the limiter's recovery probe when the limit reaches
+         * 0. See {@link AdaptiveLimit.probeFromZeroInterval}.
+         */
+        recoveryProbe?: {
+            /**
+             * Fallback base interval in milliseconds between probes, used when no
+             * group is warmed up enough to provide a recent RTT estimate. When
+             * warmed groups are available, the probe interval is derived from
+             * their weighted-mean recent RTT × 5. Default: 1000.
+             */
+            baseMs?: number;
+        };
     });
     addSample(_startTime: number, rtt: number, inflight: number, didDrop: boolean, operationName?: string): void;
     get currentLimit(): number;
+    probeFromZeroInterval(failedProbes: number): number;
+    applyProbeFromZero(): void;
     subscribe(consumer: (newLimit: number) => void, options?: {
         signal?: AbortSignal;
     }): () => void;

package/dist/limit/GroupAwareLimit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GroupAwareLimit.d.ts","sourceRoot":"","sources":["../../src/limit/GroupAwareLimit.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAS,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAKlE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AA6DzD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBAAa,eAAgB,YAAW,aAAa;IACnD,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA0C;IACzE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkD;IAEzE,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA8C;IACvE,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAe;IAErC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAiB;IAC1C,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAAQ;IAC9C,OAAO,CAAC,QAAQ,CAAC,sBAAsB,CAAQ;IAC/C,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAQ;gBAE/B,OAAO,CAAC,EAAE;QACpB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,KAAK,MAAM,CAAC;QACvD,gBAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,gBAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,eAAe,CAAC,EAAE,MAAM,CAAC;QACzB,eAAe,CAAC,EAAE,MAAM,CAAC;QACzB,KAAK,CAAC,EAAE,MAAM,MAAM,CAAC;QACrB,cAAc,CAAC,EAAE,cAAc,CAAC;KACjC;IA0BD,SAAS,CACP,UAAU,EAAE,MAAM,EAClB,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,OAAO,EAChB,aAAa,CAAC,EAAE,MAAM,GACrB,IAAI;IAgDP,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED,SAAS,CACP,QAAQ,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,EACpC,OAAO,GAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAO,GACrC,MAAM,IAAI;IAIb,OAAO,CAAC,uBAAuB;IA8C/B,OAAO,CAAC,KAAK;IAIb,OAAO,CAAC,aAAa;IAOrB,QAAQ,IAAI,MAAM;CAGnB;AAED,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,IAAI;QACZ,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,KAAK,MAAM,CAAC;KACpD;CACF"}
+{"version":3,"file":"GroupAwareLimit.d.ts","sourceRoot":"","sources":["../../src/limit/GroupAwareLimit.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAS,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAKlE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AA6DzD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBAAa,eAAgB,YAAW,aAAa;IACnD,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA0C;IACzE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkD;IAEzE,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA8C;IACvE,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAe;IACrC,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAS;IAE7C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAiB;IAC1C,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAAQ;IAC9C,OAAO,CAAC,QAAQ,CAAC,sBAAsB,CAAQ;IAC/C,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAQ;gBAE/B,OAAO,CAAC,EAAE;QACpB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,KAAK,MAAM,CAAC;QACvD,gBAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,gBAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,eAAe,CAAC,EAAE,MAAM,CAAC;QACzB,eAAe,CAAC,EAAE,MAAM,CAAC;QACzB,KAAK,CAAC,EAAE,MAAM,MAAM,CAAC;QACrB,cAAc,CAAC,EAAE,cAAc,CAAC;QAChC;;;WAGG;QACH,aAAa,CAAC,EAAE;YACd;;;;;eAKG;YACH,MAAM,CAAC,EAAE,MAAM,CAAC;SACjB,CAAC;KACH;IA8BD,SAAS,CACP,UAAU,EAAE,MAAM,EAClB,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,OAAO,EAChB,aAAa,CAAC,EAAE,MAAM,GACrB,IAAI;IAgDP,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED,qBAAqB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM;IAiCnD,kBAAkB,IAAI,IAAI;IAI1B,SAAS,CACP,QAAQ,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,EACpC,OAAO,GAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAO,GACrC,MAAM,IAAI;IAIb,OAAO,CAAC,uBAAuB;IA+C/B,OAAO,CAAC,KAAK;IAIb,OAAO,CAAC,aAAa;IAOrB,QAAQ,IAAI,MAAM;CAGnB;AAED,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,IAAI;QACZ,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,KAAK,MAAM,CAAC;KACpD;CACF"}

package/dist/limit/GroupAwareLimit.js

@@ -1,3 +1,4 @@
+import { sumBy } from "es-toolkit";
 import lruPkg from "lru_map";
 const { LRUMap } = lruPkg;
 import { ListenerSet } from "../ListenerSet.js";
@@ -94,6 +95,7 @@ export class GroupAwareLimit {
     recentRttWindow;
     minGroupSamples;
     clock;
+    recoveryProbeBaseMs;
     registry;
     congestionSignalGauge;
     warmedGroupsCountGauge;
@@ -111,6 +113,10 @@ export class GroupAwareLimit {
         this.recentRttWindow = options?.recentRttWindow ?? 100;
         this.minGroupSamples = options?.minGroupSamples ?? 20;
         this.clock = options?.clock ?? (() => performance.now());
+        this.recoveryProbeBaseMs = options?.recoveryProbe?.baseMs ?? 1000;
+        if (!(this.recoveryProbeBaseMs > 0)) {
+            throw new RangeError("recoveryProbe.baseMs must be > 0");
+        }
         this.registry = options?.metricRegistry ?? NoopMetricRegistry;
         this.congestionSignalGauge = this.registry.gauge(MetricIds.CONGESTION_SIGNAL_NAME);
         this.warmedGroupsCountGauge = this.registry.gauge(MetricIds.WARMED_GROUPS_COUNT_NAME);
@@ -156,6 +162,29 @@ export class GroupAwareLimit {
     get currentLimit() {
         return this._limit;
     }
+    probeFromZeroInterval(failedProbes) {
+        const now = this.clock();
+        const entries = [
+            ...this.groups.entries(),
+        ];
+        const warmedGroupInfos = entries.flatMap(([, groupState]) => {
+            const activity = groupState.activityCount(now);
+            const recentRtt = groupState.recentRtt.currentValue;
+            const validRecentRtt = Number.isFinite(recentRtt) && recentRtt > 0;
+            return validRecentRtt && activity >= this.minGroupSamples
+                ? [{ recentRtt, weight: Math.sqrt(activity) }]
+                : [];
+        });
+        const totalWeight = sumBy(warmedGroupInfos, ({ weight }) => weight);
+        const weightedRatioSum = sumBy(warmedGroupInfos, ({ weight, recentRtt }) => weight * recentRtt);
+        const base = totalWeight > 0
+            ? (weightedRatioSum / totalWeight) * 5
+            : this.recoveryProbeBaseMs;
+        return base * Math.pow(2, failedProbes);
+    }
+    applyProbeFromZero() {
+        this.applyNewLimit(1);
+    }
     subscribe(consumer, options = {}) {
         return this.limitListeners.subscribe(consumer, options);
     }
@@ -184,7 +213,7 @@ export class GroupAwareLimit {
         const totalWeight = sum(warmedGroupInfos.map(({ weight }) => weight));
         if (totalWeight <= 0)
             return undefined;
-        const weightedRatioSum = sum(warmedGroupInfos.map(({ weight, ratio }) => weight * ratio));
+        const weightedRatioSum = sumBy(warmedGroupInfos, ({ weight, ratio }) => weight * ratio);
         return {
             signal: weightedRatioSum / totalWeight,
             warmedGroupInfos,

package/dist/limit/StreamingLimit.d.ts

@@ -24,5 +24,30 @@ export interface AdaptiveLimit {
      *   used by group-aware limits to distinguish heterogeneous workloads.
      */
     addSample(startTime: number, rtt: number, inflight: number, didDrop: boolean, operationName?: string): void;
+    /**
+     * Returns the recommended interval, in milliseconds, between recovery
+     * probes when the limit has fallen to 0 and there are no inflight requests
+     * left to produce samples. The {@link Limiter} uses this to schedule a
+     * probe that bumps the limit back to 1 so a single request can flow and
+     * generate a fresh sample.
+     *
+     * @param failedProbes The number of consecutive probes that have already
+     *   fired without producing a non-drop sample since the limit last
+     *   recovered. Implementations typically use this to grow the interval
+     *   exponentially (e.g. `base * 2^failedProbes`).
+     *
+     * Strategies that cannot reach a limit of 0 (e.g. {@link VegasLimit}) or
+     * are intentionally inert (e.g. {@link FixedLimit}) may omit this method;
+     * the limiter will then skip recovery probing for them.
+     */
+    probeFromZeroInterval?(failedProbes: number): number;
+    /**
+     * Atomically raises the limit to (at least) 1 so a single request can get
+     * through, allowing the sample to be used to probe recovery. Called by the
+     * limiter when its probe timer fires while the limit is at 0.
+     *
+     * Must be implemented if and only if {@link probeFromZeroInterval} is.
+     */
+    applyProbeFromZero?(): void;
 }
 //# sourceMappingURL=StreamingLimit.d.ts.map

package/dist/limit/StreamingLimit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"StreamingLimit.d.ts","sourceRoot":"","sources":["../../src/limit/StreamingLimit.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,2CAA2C;IAC3C,IAAI,YAAY,IAAI,MAAM,CAAC;IAE3B;;;;;OAKG;IACH,SAAS,CACP,QAAQ,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,EACpC,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GACjC,MAAM,IAAI,CAAC;IAEd;;;;;;;;OAQG;IACH,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7G"}
+{"version":3,"file":"StreamingLimit.d.ts","sourceRoot":"","sources":["../../src/limit/StreamingLimit.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,2CAA2C;IAC3C,IAAI,YAAY,IAAI,MAAM,CAAC;IAE3B;;;;;OAKG;IACH,SAAS,CACP,QAAQ,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,EACpC,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GACjC,MAAM,IAAI,CAAC;IAEd;;;;;;;;OAQG;IACH,SAAS,CACP,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,OAAO,EAChB,aAAa,CAAC,EAAE,MAAM,GACrB,IAAI,CAAC;IAER;;;;;;;;;;;;;;;OAeG;IACH,qBAAqB,CAAC,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAAC;IAErD;;;;;;OAMG;IACH,kBAAkB,CAAC,IAAI,IAAI,CAAC;CAC7B"}

package/dist/limit/WindowedLimit.d.ts

@@ -45,6 +45,16 @@ export declare class WindowedLimit implements AdaptiveLimit {
     private readonly sampleWindowFactory;
     /** Object tracking stats for the current sample window */
     private sample;
+    /**
+     * Set when `applyProbeFromZero` fires so the very next `addSample` bypasses
+     * windowing and is forwarded directly to the delegate. Without this, a
+     * single dropped probe sample never reaches the delegate (the window
+     * requires `windowSize` samples to become ready), so the delegate stays at
+     * limit 1 and the exponential backoff never re-arms.
+     */
+    private probeActive;
+    readonly probeFromZeroInterval?: (failedProbes: number) => number;
+    readonly applyProbeFromZero?: () => void;
     constructor(delegate: AdaptiveLimit, options?: WindowedLimitOptions);
     addSample(startTime: number, rtt: number, inflight: number, didDrop: boolean, operationName?: string): void;
     get currentLimit(): number;

package/dist/limit/WindowedLimit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"WindowedLimit.d.ts","sourceRoot":"","sources":["../../src/limit/WindowedLimit.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAS7D,MAAM,WAAW,oBAAoB;IACnC;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,6EAA6E;IAC7E,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAE3B,+EAA+E;IAC/E,mBAAmB,CAAC,EAAE,MAAM,YAAY,CAAC;CAC1C;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,aAAc,YAAW,aAAa;IACjD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAgB;IAEzC,kFAAkF;IAClF,OAAO,CAAC,cAAc,CAAK;IAE3B,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAqB;IAEzD,0DAA0D;IAC1D,OAAO,CAAC,MAAM,CAAe;gBAEjB,QAAQ,EAAE,aAAa,EAAE,OAAO,GAAE,oBAAyB;IAwBvE,SAAS,CACP,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,OAAO,EAChB,aAAa,CAAC,EAAE,MAAM,GACrB,IAAI;IAsCP,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED,SAAS,CACP,QAAQ,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,EACpC,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GACjC,MAAM,IAAI;CAGd"}
+{"version":3,"file":"WindowedLimit.d.ts","sourceRoot":"","sources":["../../src/limit/WindowedLimit.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAS7D,MAAM,WAAW,oBAAoB;IACnC;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,6EAA6E;IAC7E,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAE3B,+EAA+E;IAC/E,mBAAmB,CAAC,EAAE,MAAM,YAAY,CAAC;CAC1C;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,aAAc,YAAW,aAAa;IACjD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAgB;IAEzC,kFAAkF;IAClF,OAAO,CAAC,cAAc,CAAK;IAE3B,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAqB;IAEzD,0DAA0D;IAC1D,OAAO,CAAC,MAAM,CAAe;IAE7B;;;;;;OAMG;IACH,OAAO,CAAC,WAAW,CAAS;IAK5B,QAAQ,CAAC,qBAAqB,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,MAAM,CAAC;IAClE,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,IAAI,CAAC;gBAE7B,QAAQ,EAAE,aAAa,EAAE,OAAO,GAAE,oBAAyB;IAoCvE,SAAS,CACP,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,OAAO,EAChB,aAAa,CAAC,EAAE,MAAM,GACrB,IAAI;IA4CP,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED,SAAS,CACP,QAAQ,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,EACpC,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GACjC,MAAM,IAAI;CAGd"}

package/dist/limit/WindowedLimit.js

@@ -28,8 +28,30 @@ export class WindowedLimit {
     sampleWindowFactory;
     /** Object tracking stats for the current sample window */
     sample;
+    /**
+     * Set when `applyProbeFromZero` fires so the very next `addSample` bypasses
+     * windowing and is forwarded directly to the delegate. Without this, a
+     * single dropped probe sample never reaches the delegate (the window
+     * requires `windowSize` samples to become ready), so the delegate stays at
+     * limit 1 and the exponential backoff never re-arms.
+     */
+    probeActive = false;
+    // Forward recovery-probe support to the delegate when supported. Both
+    // methods are provided iff the delegate provides them, so the limiter's
+    // "both methods present" check works correctly.
+    probeFromZeroInterval;
+    applyProbeFromZero;
     constructor(delegate, options = {}) {
         this.delegate = delegate;
+        const { probeFromZeroInterval, applyProbeFromZero } = delegate;
+        if (typeof probeFromZeroInterval === "function" &&
+            typeof applyProbeFromZero === "function") {
+            this.probeFromZeroInterval = probeFromZeroInterval.bind(delegate);
+            this.applyProbeFromZero = () => {
+                this.probeActive = true;
+                applyProbeFromZero.call(delegate);
+            };
+        }
         this.minWindowTime = options.minWindowTimeMs ?? DEFAULT_MIN_WINDOW_TIME;
         this.maxWindowTime = options.maxWindowTimeMs ?? DEFAULT_MAX_WINDOW_TIME;
         this.windowSize = options.windowSize ?? DEFAULT_WINDOW_SIZE;
@@ -38,17 +60,22 @@ export class WindowedLimit {
         this.sampleWindowFactory =
             options.sampleWindowFactory ?? makeAverageSampleWindow;
         if (this.minWindowTime < 100) {
-            throw new Error("minWindowTime must be >= 100 ms");
+            throw new RangeError("minWindowTime must be >= 100 ms");
         }
         if (this.maxWindowTime < 100) {
-            throw new Error("maxWindowTime must be >= 100 ms");
+            throw new RangeError("maxWindowTime must be >= 100 ms");
         }
         if (this.windowSize < 10) {
-            throw new Error("Window size must be >= 10");
+            throw new RangeError("Window size must be >= 10");
         }
         this.sample = this.sampleWindowFactory();
     }
     addSample(startTime, rtt, inflight, didDrop, operationName) {
+        if (this.probeActive) {
+            this.probeActive = false;
+            this.delegate.addSample(startTime, rtt, inflight, didDrop);
+            return;
+        }
         const endTime = startTime + rtt;
         if (rtt < this.minRttThreshold) {
             return;

package/dist/limit/window/PercentileSampleWindow.js

@@ -76,7 +76,7 @@ class ImmutablePercentileSampleWindow {
  */
 export function createPercentileSampleWindow(percentile, windowSize) {
     if (percentile <= 0 || percentile >= 1) {
-        throw new Error("Percentile should belong to (0, 1.0)");
+        throw new RangeError("Percentile should belong to (0, 1.0)");
     }
     return new ImmutablePercentileSampleWindow({ percentile, windowSize });
 }

package/dist/limiter/acquire-strategies/PartitionedStrategy.js

@@ -59,7 +59,7 @@ export class PartitionedStrategy {
             throw new Error("No partitions specified");
         }
         if (totalPercent > 1) {
-            throw new Error("Sum of partition percentages must be <= 1.0");
+            throw new RangeError("Sum of partition percentages must be <= 1.0");
         }
         this.partitionResolver = options.partitionResolver;
         this.knownPartitions = new Map(partitionEntries.map(([name, cfg]) => [
@@ -139,7 +139,7 @@ class Partition {
     _limitAtGlobalSaturation;
     constructor(init) {
         if (init.percent < 0 || init.percent > 1) {
-            throw new Error("Partition percentage must be in the range [0.0, 1.0]");
+            throw new RangeError("Partition percentage must be in the range [0.0, 1.0]");
         }
         this.name = init.name;
         this.percent = init.percent;
@@ -147,7 +147,7 @@ class Partition {
         this._limitAtGlobalSaturation = init.initialLimitAtGlobalSaturation;
         if (this.burstMode.kind === "capped" &&
             this.burstMode.maxBurstMultiplier < 1.0) {
-            throw new Error("maxBurstMultiplier must be >= 1.0");
+            throw new RangeError("maxBurstMultiplier must be >= 1.0");
         }
         const registry = init.registry;
         this.inflightDistribution = registry.distribution(MetricIds.INFLIGHT_NAME, {

package/dist/limiter/allocation-unavailable-strategies/DelayedRejectStrategy.js

@@ -13,7 +13,7 @@ export class DelayedRejectStrategy {
         this.delayMsForContext = options.delayMsForContext;
         const max = options.maxConcurrentDelays ?? 100;
         if (max < 1 || !Number.isFinite(max)) {
-            throw new Error("maxConcurrentDelays must be a finite number >= 1");
+            throw new RangeError("maxConcurrentDelays must be a finite number >= 1");
         }
         this.maxConcurrentDelays = max;
     }

package/dist/statistics/DecayingHistogram.js

@@ -25,10 +25,10 @@ export class DecayingHistogram {
     constructor(options) {
         const { halfLife, minValue = 0.1, maxValue = 100_000, binsPerDecade = 5, logWarning, } = options;
         if (halfLife <= 0) {
-            throw new Error("halfLife must be positive");
+            throw new RangeError("halfLife must be positive");
         }
         if (minValue <= 0 || maxValue <= minValue) {
-            throw new Error("Must have 0 < minValue < maxValue");
+            throw new RangeError("Must have 0 < minValue < maxValue");
         }
         this.lambda = Math.LN2 / halfLife;
         this.minValue = minValue;

package/package.json

@@ -9,7 +9,7 @@
     "dynamic rate limiting"
   ],
   "author": "Ethan Resnick <ethan.resnick@gmail.com>",
-  "version": "0.12.0",
+  "version": "0.12.1",
   "type": "module",
   "exports": {
     ".": {
@@ -33,6 +33,7 @@
     "typescript": "^6.0.2"
   },
   "dependencies": {
+    "es-toolkit": "^1.46.1",
     "lru_map": "^0.4.1"
   }
 }