@adaptive-concurrency-toolkit/core 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Igor Savin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,227 @@
+# @adaptive-concurrency-toolkit/core
+
+Core adaptive concurrency algorithms inspired by Netflix's
+[`concurrency-limits`](https://github.com/Netflix/concurrency-limits).
+
+This package gives you `Limit` algorithms that infer a healthy in-flight
+ceiling from observed round-trip latency and drop signals, plus a `Limiter`
+that gates work against the inferred ceiling. Higher-level wrappers (HTTP,
+RPC, queues) live in sibling packages.
+
+## What problem does this solve?
+
+Fixed concurrency limits (semaphores, connection pools) are hard to tune:
+too low and you waste capacity, too high and the downstream collapses under
+queue-induced latency. Adaptive concurrency observes latency and failure
+signals at runtime and adjusts the limit so the system runs at the knee of
+the latency curve - high throughput, low queueing.
+
+The trade-off vs. a fixed semaphore: there is a control loop with state,
+warm-up cost, and parameters to understand. For homogeneous traffic against
+a known dependency, a fixed limit often suffices. For heterogeneous traffic
+or shared dependencies, adaptive limits pay off.
+
+## Quick start
+
+```ts
+import { Gradient2Limit, SimpleLimiter } from '@adaptive-concurrency-toolkit/core';
+
+const limit = new Gradient2Limit({
+  initialLimit: 20,
+  minLimit: 1,
+  maxLimit: 200,
+});
+const limiter = new SimpleLimiter(limit);
+
+async function call(req: Request): Promise<Response> {
+  const listener = limiter.acquire();
+  if (!listener) {
+    // No permit available - shed load. Typical responses: 429, fallback path,
+    // bounded retry queue. The point is to fail fast rather than pile on.
+    return new Response('Too Many Requests', { status: 429 });
+  }
+  try {
+    const res = await fetch(req);
+    // 5xx and timeouts indicate the upstream is overloaded. We report these
+    // as drops so the algorithm contracts. 4xx are caller errors - they
+    // shouldn't influence the limit, so we ignore them.
+    if (res.status >= 500) listener.onDropped();
+    else if (res.status >= 400) listener.onIgnore();
+    else listener.onSuccess();
+    return res;
+  } catch (err) {
+    // Network errors / aborts are also overload signals in most setups.
+    listener.onDropped();
+    throw err;
+  }
+}
+```
+
+Exactly one of `onSuccess` / `onDropped` / `onIgnore` must be called per
+acquired listener. Subsequent calls are no-ops, so it's safe to wrap the
+release in a `finally`.
+
+## Algorithms
+
+All four implement the same `Limit` interface, so you can swap them with one
+line of code.
+
+### `FixedLimit`
+
+Constant ceiling - does not adapt.
+
+**Use when:** you have a known-good limit (e.g. a connection pool size), or
+you're rolling out adaptive concurrency gradually and want a baseline to
+compare against.
+
+**Pros:** zero cognitive overhead, predictable, no warm-up.
+**Cons:** doesn't react to changes in upstream capacity, traffic mix, or
+dependency health.
+
+### `AimdLimit` - Additive Increase, Multiplicative Decrease
+
+Same control loop family as TCP Reno. On every sample:
+
+```
+drop or rtt > timeout  →  limit ← max(min, ⌊limit · backoffRatio⌋)
+success at high util.  →  limit ← min(max, limit + 1)
+otherwise              →  hold
+```
+
+**Use when:** you have a clean drop signal (a request that fails is a clear
+overload indicator - e.g. 5xx, 429, or a strict latency SLA used as
+`rttTimeoutNanos`), and you want a simple, well-understood algorithm.
+
+**Pros:** simple, fast to react to drops, no windowing, easy to reason
+about. Good default when drops dominate the signal.
+**Cons:** no notion of latency gradient - won't preemptively back off when
+RTT is creeping up but requests haven't started failing yet. Increases one
+unit at a time, so warm-up to high concurrency is slow. Per-sample updates
+can be jittery under bursty traffic.
+
+### `VegasLimit` - TCP Vegas-style queue-size estimation
+
+Per window (default 1 s) compute:
+
+```
+queue = limit · (1 − rttNoLoad / windowMinRtt)
+queue ≤ α(limit)  →  limit + log10(limit)
+queue ≥ β(limit)  →  limit − log10(limit)
+otherwise         →  hold
+```
+
+`rttNoLoad` is a rolling minimum RTT (the "no queueing" floor), periodically
+re-probed so it adapts to baseline drift. Drops cause an immediate
+multiplicative back-off.
+
+**Use when:** you care about latency, not just failures - e.g. an upstream
+that silently queues requests instead of rejecting them. Vegas reduces the
+limit as soon as queueing inflates RTT, before drops appear.
+
+**Pros:** reacts to latency, not just drops. Logarithmic step keeps the
+limit stable at high concurrency. Self-calibrates the latency floor.
+**Cons:** needs enough samples per window to be reliable (default 10 per
+1 s). Sensitive to a stuck `rttNoLoad` if the probe interval is too long
+relative to baseline shifts. Math is less intuitive than AIMD.
+
+### `Gradient2Limit` - long/short RTT ratio with queue-size hedge
+
+Per window:
+
+```
+shortRtt  = window min RTT
+longRtt   = EMA over windows of shortRtt
+gradient  = clamp(tolerance · longRtt / shortRtt, minGradient, 1)
+queue     = 4 · √limit                       (configurable)
+newLimit  = limit · gradient + queue
+if newLimit < limit:  smooth toward old limit
+```
+
+The gradient is capped at 1, so `limit · gradient` alone never grows the
+ceiling - growth comes from the queue-size hedge. Decreases are smoothed to
+avoid collapsing on a single bad window.
+
+**Use when:** you want Vegas-style latency sensitivity but smoother behavior
+and a more predictable scaling curve. This is the algorithm Netflix
+recommends as a general-purpose default.
+
+**Pros:** smoother than AIMD/Vegas, scales gracefully across orders of
+magnitude (the `√limit` hedge keeps relative growth steady), tolerant of
+single-window outliers.
+**Cons:** more parameters to understand (`tolerance`, `smoothing`,
+`minGradient`, queue-size function). Warm-up of `longRtt` EMA takes
+~100 windows to stabilize.
+
+## Choosing between them
+
+| Signal you trust most           | Pick                             |
+| ------------------------------- | -------------------------------- |
+| Static, known-good capacity     | `FixedLimit`                     |
+| Drops / failures                | `AimdLimit`                      |
+| Latency, with clear drop signal | `Gradient2Limit` (default)       |
+| Latency, mostly silent queueing | `VegasLimit` or `Gradient2Limit` |
+
+If you're not sure, start with `Gradient2Limit` at `initialLimit ≈ p99
+in-flight from current production`, `maxLimit ≈ 2–4× initial`. Watch the
+limit time series - if it pegs at `maxLimit` continuously, raise the cap; if
+it oscillates wildly, increase `smoothing` or lengthen `windowNanos`.
+
+## Sample semantics
+
+The `Limiter` reports each completed acquisition to its `Limit` algorithm
+via:
+
+```ts
+onSample(startTimeNanos, rttNanos, inflight, didDrop);
+```
+
+- `inflight` is the in-flight count at the moment the permit was issued -
+  algorithms use it to gate growth (don't grow if you weren't using the
+  current limit).
+- `didDrop` is `true` only when the caller called `onDropped()`. A 4xx that
+  ended in `onIgnore()` does not appear as a drop.
+- `onIgnore()` releases the permit but produces no sample - RTT is
+  discarded. This is the right choice for client-side errors, cancellations,
+  and short-circuited paths that don't represent real upstream work.
+
+## Picking parameters
+
+- **`initialLimit`** - start near your current steady-state in-flight.
+  Too low wastes warm-up time; too high risks overshoot on cold caches.
+- **`minLimit`** - should always allow at least one request through so
+  health probes succeed. `1` is a safe default; raise it only if you
+  _know_ the downstream can handle higher concurrency at all times.
+- **`maxLimit`** - a safety cap, not a target. Pick well above your
+  expected steady state but below what would overload a healthy downstream.
+- **`windowNanos`** (Vegas, Gradient2) - long enough to collect a useful
+  RTT distribution (≥ 10 × p99 latency), short enough to react. 1 s is a
+  reasonable default for HTTP-scale latencies.
+- **`backoffRatio`** - 0.9 is gentle, 0.5 is aggressive. Aggressive
+  back-off is appropriate for upstreams that genuinely collapse under
+  load; gentle is better when drops can be transient.
+
+## Performance notes
+
+- Sample reporting is allocation-free on the algorithm's hot path -
+  `onSample` takes positional `number` / `boolean` args.
+- The `Limiter` allocates exactly one `Listener` object per `acquire()`.
+- Time is read once per acquire and once per release via `performance.now()`
+  scaled to nanoseconds (a `number`, not `bigint`, to keep arithmetic fast).
+- No timers, no background tasks. Adjustments happen synchronously when
+  samples cross a window boundary.
+
+## Testing
+
+Use `ManualClock` to drive the algorithms deterministically:
+
+```ts
+import { Gradient2Limit, SimpleLimiter, ManualClock } from '@adaptive-concurrency-toolkit/core';
+
+const clock = new ManualClock();
+const limit = new Gradient2Limit({ initialLimit: 10, windowNanos: 1_000_000_000 });
+const limiter = new SimpleLimiter(limit, { clock });
+
+const l = limiter.acquire()!;
+clock.advanceMillis(50);
+l.onSuccess(); // reports a 50 ms sample
+```

package/dist/clock.d.ts

@@ -0,0 +1,20 @@
+import type { Nanos } from './types.ts';
+/**
+ * Monotonic time source. The default implementation uses
+ * `performance.now()` scaled to nanoseconds — fast, allocation-free, monotonic.
+ *
+ * A custom clock is useful for deterministic tests and for embedding in
+ * environments without `performance` (workers, etc).
+ */
+export interface Clock {
+    nowNanos(): Nanos;
+}
+export declare const defaultClock: Clock;
+export declare class ManualClock implements Clock {
+    private current;
+    constructor(initial?: Nanos);
+    nowNanos(): Nanos;
+    advanceNanos(delta: Nanos): void;
+    advanceMillis(delta: number): void;
+    setNanos(value: Nanos): void;
+}

package/dist/clock.js

@@ -0,0 +1,23 @@
+const NS_PER_MS = 1_000_000;
+export const defaultClock = {
+    nowNanos: () => performance.now() * NS_PER_MS,
+};
+export class ManualClock {
+    current;
+    constructor(initial = 0) {
+        this.current = initial;
+    }
+    nowNanos() {
+        return this.current;
+    }
+    advanceNanos(delta) {
+        this.current += delta;
+    }
+    advanceMillis(delta) {
+        this.current += delta * NS_PER_MS;
+    }
+    setNanos(value) {
+        this.current = value;
+    }
+}
+//# sourceMappingURL=clock.js.map

package/dist/clock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clock.js","sourceRoot":"","sources":["../src/clock.ts"],"names":[],"mappings":"AAaA,MAAM,SAAS,GAAG,SAAS,CAAC;AAE5B,MAAM,CAAC,MAAM,YAAY,GAAU;IACjC,QAAQ,EAAE,GAAG,EAAE,CAAC,WAAW,CAAC,GAAG,EAAE,GAAG,SAAS;CAC9C,CAAC;AAEF,MAAM,OAAO,WAAW;IACd,OAAO,CAAQ;IACvB,YAAY,UAAiB,CAAC;QAC5B,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;IACD,QAAQ;QACN,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;IACD,YAAY,CAAC,KAAY;QACvB,IAAI,CAAC,OAAO,IAAI,KAAK,CAAC;IACxB,CAAC;IACD,aAAa,CAAC,KAAa;QACzB,IAAI,CAAC,OAAO,IAAI,KAAK,GAAG,SAAS,CAAC;IACpC,CAAC;IACD,QAAQ,CAAC,KAAY;QACnB,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC;IACvB,CAAC;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export type { Nanos, Listener, LimitChangeListener, Unsubscribe } from './types.ts';
+export { type Clock, defaultClock, ManualClock } from './clock.ts';
+export type { Limit } from './limit/limit.ts';
+export { FixedLimit, type FixedLimitOptions } from './limit/fixed-limit.ts';
+export { AimdLimit, type AimdLimitOptions } from './limit/aimd-limit.ts';
+export { VegasLimit, type VegasLimitOptions } from './limit/vegas-limit.ts';
+export { Gradient2Limit, type Gradient2LimitOptions } from './limit/gradient2-limit.ts';
+export type { Limiter } from './limiter/limiter.ts';
+export { SimpleLimiter, type SimpleLimiterOptions } from './limiter/simple-limiter.ts';
+export { Ema } from './util/ema.ts';

package/dist/index.js

@@ -0,0 +1,8 @@
+export { defaultClock, ManualClock } from "./clock.js";
+export { FixedLimit } from "./limit/fixed-limit.js";
+export { AimdLimit } from "./limit/aimd-limit.js";
+export { VegasLimit } from "./limit/vegas-limit.js";
+export { Gradient2Limit } from "./limit/gradient2-limit.js";
+export { SimpleLimiter } from "./limiter/simple-limiter.js";
+export { Ema } from "./util/ema.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAc,YAAY,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAGnE,OAAO,EAAE,UAAU,EAA0B,MAAM,wBAAwB,CAAC;AAC5E,OAAO,EAAE,SAAS,EAAyB,MAAM,uBAAuB,CAAC;AACzE,OAAO,EAAE,UAAU,EAA0B,MAAM,wBAAwB,CAAC;AAC5E,OAAO,EAAE,cAAc,EAA8B,MAAM,4BAA4B,CAAC;AAGxF,OAAO,EAAE,aAAa,EAA6B,MAAM,6BAA6B,CAAC;AAEvF,OAAO,EAAE,GAAG,EAAE,MAAM,eAAe,CAAC"}

package/dist/limit/aimd-limit.d.ts

@@ -0,0 +1,51 @@
+import type { LimitChangeListener, Nanos, Unsubscribe } from '../types.ts';
+import type { Limit } from './limit.ts';
+export interface AimdLimitOptions {
+    /** Initial limit. Defaults to 10. */
+    readonly initialLimit?: number;
+    /** Lower bound. Defaults to 1. */
+    readonly minLimit?: number;
+    /** Upper bound. Defaults to 1000. */
+    readonly maxLimit?: number;
+    /**
+     * Multiplicative decrease factor applied to the limit on a drop or RTT
+     * timeout. Defaults to 0.9. Must be in (0, 1).
+     */
+    readonly backoffRatio?: number;
+    /**
+     * RTT (in ns) above which a sample is treated as a drop signal even if the
+     * caller reported success. Defaults to +∞ (never).
+     */
+    readonly rttTimeoutNanos?: number;
+    /**
+     * Fraction of the current limit that must be in flight before additive
+     * increases take effect. Defaults to 0.5 — i.e. we only grow when we are
+     * actually using at least half the headroom.
+     */
+    readonly utilizationThreshold?: number;
+}
+/**
+ * Additive Increase / Multiplicative Decrease.
+ *
+ * Inspired by TCP congestion control:
+ *
+ *  - on drop or `rtt > rttTimeoutNanos`:  limit ← max(minLimit, ⌊limit · backoffRatio⌋)
+ *  - on success while utilization ≥ θ:     limit ← min(maxLimit, limit + 1)
+ *  - otherwise:                            no-op
+ *
+ * Reacts immediately to every sample (no internal windowing); this gives fast
+ * decreases but can be noisy. For smoother behavior prefer {@link Gradient2Limit}.
+ */
+export declare class AimdLimit implements Limit {
+    private _limit;
+    readonly minLimit: number;
+    readonly maxLimit: number;
+    readonly backoffRatio: number;
+    readonly rttTimeoutNanos: number;
+    readonly utilizationThreshold: number;
+    private readonly listeners;
+    constructor(opts?: AimdLimitOptions);
+    get limit(): number;
+    onSample(_start: Nanos, rttNanos: Nanos, inflight: number, didDrop: boolean): void;
+    onChange(listener: LimitChangeListener): Unsubscribe;
+}

package/dist/limit/aimd-limit.js

@@ -0,0 +1,75 @@
+import { ChangeListeners } from "../util/listeners.js";
+/**
+ * Additive Increase / Multiplicative Decrease.
+ *
+ * Inspired by TCP congestion control:
+ *
+ *  - on drop or `rtt > rttTimeoutNanos`:  limit ← max(minLimit, ⌊limit · backoffRatio⌋)
+ *  - on success while utilization ≥ θ:     limit ← min(maxLimit, limit + 1)
+ *  - otherwise:                            no-op
+ *
+ * Reacts immediately to every sample (no internal windowing); this gives fast
+ * decreases but can be noisy. For smoother behavior prefer {@link Gradient2Limit}.
+ */
+export class AimdLimit {
+    _limit;
+    minLimit;
+    maxLimit;
+    backoffRatio;
+    rttTimeoutNanos;
+    utilizationThreshold;
+    listeners = new ChangeListeners();
+    constructor(opts = {}) {
+        const initial = opts.initialLimit ?? 10;
+        const min = opts.minLimit ?? 1;
+        const max = opts.maxLimit ?? 1000;
+        const backoff = opts.backoffRatio ?? 0.9;
+        const utilization = opts.utilizationThreshold ?? 0.5;
+        const timeout = opts.rttTimeoutNanos ?? Number.POSITIVE_INFINITY;
+        if (!(min >= 1) || !Number.isFinite(min)) {
+            throw new RangeError(`minLimit must be >= 1, got ${min}`);
+        }
+        if (!(max >= min)) {
+            throw new RangeError(`maxLimit must be >= minLimit, got ${max} < ${min}`);
+        }
+        if (!(initial >= min && initial <= max)) {
+            throw new RangeError(`initialLimit must be in [${min}, ${max}], got ${initial}`);
+        }
+        if (!(backoff > 0 && backoff < 1)) {
+            throw new RangeError(`backoffRatio must be in (0, 1), got ${backoff}`);
+        }
+        if (!(utilization > 0 && utilization <= 1)) {
+            throw new RangeError(`utilizationThreshold must be in (0, 1], got ${utilization}`);
+        }
+        if (!(timeout > 0)) {
+            throw new RangeError(`rttTimeoutNanos must be > 0, got ${timeout}`);
+        }
+        this._limit = initial;
+        this.minLimit = min;
+        this.maxLimit = max;
+        this.backoffRatio = backoff;
+        this.utilizationThreshold = utilization;
+        this.rttTimeoutNanos = timeout;
+    }
+    get limit() {
+        return this._limit;
+    }
+    onSample(_start, rttNanos, inflight, didDrop) {
+        const current = this._limit;
+        let next = current;
+        if (didDrop || rttNanos > this.rttTimeoutNanos) {
+            next = Math.max(this.minLimit, Math.floor(current * this.backoffRatio));
+        }
+        else if (inflight >= current * this.utilizationThreshold) {
+            next = Math.min(this.maxLimit, current + 1);
+        }
+        if (next !== current) {
+            this._limit = next;
+            this.listeners.emit(next);
+        }
+    }
+    onChange(listener) {
+        return this.listeners.add(listener);
+    }
+}
+//# sourceMappingURL=aimd-limit.js.map

package/dist/limit/aimd-limit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"aimd-limit.js","sourceRoot":"","sources":["../../src/limit/aimd-limit.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AA4BvD;;;;;;;;;;;GAWG;AACH,MAAM,OAAO,SAAS;IACZ,MAAM,CAAS;IACd,QAAQ,CAAS;IACjB,QAAQ,CAAS;IACjB,YAAY,CAAS;IACrB,eAAe,CAAS;IACxB,oBAAoB,CAAS;IACrB,SAAS,GAAG,IAAI,eAAe,EAAE,CAAC;IAEnD,YAAY,OAAyB,EAAE;QACrC,MAAM,OAAO,GAAG,IAAI,CAAC,YAAY,IAAI,EAAE,CAAC;QACxC,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,IAAI,CAAC,CAAC;QAC/B,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC;QAClC,MAAM,OAAO,GAAG,IAAI,CAAC,YAAY,IAAI,GAAG,CAAC;QACzC,MAAM,WAAW,GAAG,IAAI,CAAC,oBAAoB,IAAI,GAAG,CAAC;QACrD,MAAM,OAAO,GAAG,IAAI,CAAC,eAAe,IAAI,MAAM,CAAC,iBAAiB,CAAC;QAEjE,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;YACzC,MAAM,IAAI,UAAU,CAAC,8BAA8B,GAAG,EAAE,CAAC,CAAC;QAC5D,CAAC;QACD,IAAI,CAAC,CAAC,GAAG,IAAI,GAAG,CAAC,EAAE,CAAC;YAClB,MAAM,IAAI,UAAU,CAAC,qCAAqC,GAAG,MAAM,GAAG,EAAE,CAAC,CAAC;QAC5E,CAAC;QACD,IAAI,CAAC,CAAC,OAAO,IAAI,GAAG,IAAI,OAAO,IAAI,GAAG,CAAC,EAAE,CAAC;YACxC,MAAM,IAAI,UAAU,CAAC,4BAA4B,GAAG,KAAK,GAAG,UAAU,OAAO,EAAE,CAAC,CAAC;QACnF,CAAC;QACD,IAAI,CAAC,CAAC,OAAO,GAAG,CAAC,IAAI,OAAO,GAAG,CAAC,CAAC,EAAE,CAAC;YAClC,MAAM,IAAI,UAAU,CAAC,uCAAuC,OAAO,EAAE,CAAC,CAAC;QACzE,CAAC;QACD,IAAI,CAAC,CAAC,WAAW,GAAG,CAAC,IAAI,WAAW,IAAI,CAAC,CAAC,EAAE,CAAC;YAC3C,MAAM,IAAI,UAAU,CAAC,+CAA+C,WAAW,EAAE,CAAC,CAAC;QACrF,CAAC;QACD,IAAI,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC,EAAE,CAAC;YACnB,MAAM,IAAI,UAAU,CAAC,oCAAoC,OAAO,EAAE,CAAC,CAAC;QACtE,CAAC;QAED,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC;QACtB,IAAI,CAAC,QAAQ,GAAG,GAAG,CAAC;QACpB,IAAI,CAAC,QAAQ,GAAG,GAAG,CAAC;QACpB,IAAI,CAAC,YAAY,GAAG,OAAO,CAAC;QAC5B,IAAI,CAAC,oBAAoB,GAAG,WAAW,CAAC;QACxC,IAAI,CAAC,eAAe,GAAG,OAAO,CAAC;IACjC,CAAC;IAED,IAAI,KAAK;QACP,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAED,QAAQ,CAAC,MAAa,EAAE,QAAe,EAAE,QAAgB,EAAE,OAAgB;QACzE,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC;QAC5B,IAAI,IAAI,GAAG,OAAO,CAAC;QAEnB,IAAI,OAAO,IAAI,QAAQ,GAAG,IAAI,CAAC,eAAe,EAAE,CAAC;YAC/C,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,KAAK,CAAC,OAAO,GAAG,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC;QAC1E,CAAC;aAAM,IAAI,QAAQ,IAAI,OAAO,GAAG,IAAI,CAAC,oBAAoB,EAAE,CAAC;YAC3D,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,EAAE,OAAO,GAAG,CAAC,CAAC,CAAC;QAC9C,CAAC;QAED,IAAI,IAAI,KAAK,OAAO,EAAE,CAAC;YACrB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;YACnB,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC5B,CAAC;IACH,CAAC;IAED,QAAQ,CAAC,QAA6B;QACpC,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACtC,CAAC;CACF"}

package/dist/limit/fixed-limit.d.ts

@@ -0,0 +1,17 @@
+import type { LimitChangeListener, Nanos, Unsubscribe } from '../types.ts';
+import type { Limit } from './limit.ts';
+export interface FixedLimitOptions {
+    /** Constant concurrency ceiling. Must be a positive integer. */
+    readonly limit: number;
+}
+/**
+ * Constant {@link Limit}. Useful as a baseline, for tests, and as the default
+ * when adaptive behavior is undesirable.
+ */
+export declare class FixedLimit implements Limit {
+    readonly limit: number;
+    private readonly listeners;
+    constructor(opts: FixedLimitOptions);
+    onSample(_start: Nanos, _rtt: Nanos, _inflight: number, _didDrop: boolean): void;
+    onChange(listener: LimitChangeListener): Unsubscribe;
+}

package/dist/limit/fixed-limit.js

@@ -0,0 +1,22 @@
+import { ChangeListeners } from "../util/listeners.js";
+/**
+ * Constant {@link Limit}. Useful as a baseline, for tests, and as the default
+ * when adaptive behavior is undesirable.
+ */
+export class FixedLimit {
+    limit;
+    listeners = new ChangeListeners();
+    constructor(opts) {
+        if (!Number.isInteger(opts.limit) || opts.limit < 1) {
+            throw new RangeError(`limit must be a positive integer, got ${opts.limit}`);
+        }
+        this.limit = opts.limit;
+    }
+    onSample(_start, _rtt, _inflight, _didDrop) {
+        /* no-op */
+    }
+    onChange(listener) {
+        return this.listeners.add(listener);
+    }
+}
+//# sourceMappingURL=fixed-limit.js.map

package/dist/limit/fixed-limit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fixed-limit.js","sourceRoot":"","sources":["../../src/limit/fixed-limit.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAQvD;;;GAGG;AACH,MAAM,OAAO,UAAU;IACZ,KAAK,CAAS;IACN,SAAS,GAAG,IAAI,eAAe,EAAE,CAAC;IAEnD,YAAY,IAAuB;QACjC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC,KAAK,GAAG,CAAC,EAAE,CAAC;YACpD,MAAM,IAAI,UAAU,CAAC,yCAAyC,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;QAC9E,CAAC;QACD,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;IAC1B,CAAC;IAED,QAAQ,CAAC,MAAa,EAAE,IAAW,EAAE,SAAiB,EAAE,QAAiB;QACvE,WAAW;IACb,CAAC;IAED,QAAQ,CAAC,QAA6B;QACpC,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACtC,CAAC;CACF"}

package/dist/limit/gradient2-limit.d.ts

@@ -0,0 +1,80 @@
+import type { LimitChangeListener, Nanos, Unsubscribe } from '../types.ts';
+import type { Limit } from './limit.ts';
+export interface Gradient2LimitOptions {
+    readonly initialLimit?: number;
+    readonly minLimit?: number;
+    readonly maxLimit?: number;
+    /** Window duration in nanoseconds. Default 1 s. */
+    readonly windowNanos?: number;
+    /** Minimum samples per window. Default 10. */
+    readonly minWindowSamples?: number;
+    /**
+     * Long-window memory in windows. The long RTT EMA acts as the baseline.
+     * Default 100 (i.e. ~100 windows of memory).
+     */
+    readonly longWindowCount?: number;
+    /**
+     * Queue-size hedge as a function of the current limit. Default:
+     * `4·√limit` — the same form Netflix uses, which keeps a small absolute
+     * buffer at low concurrencies and a larger one at high concurrencies.
+     */
+    readonly queueSize?: (limit: number) => number;
+    /**
+     * Multiplier on `longRtt / shortRtt`. Values > 1 make the algorithm
+     * tolerate small latency inflations before reducing the limit. Default 1.5.
+     */
+    readonly tolerance?: number;
+    /**
+     * Smoothing for limit *decreases* — newLimit = α·newLimit + (1−α)·oldLimit.
+     * Prevents single-window spikes from collapsing the limit. Default 0.2.
+     */
+    readonly smoothing?: number;
+    /** Floor for the gradient. Default 0.5 — limit never halves in one step. */
+    readonly minGradient?: number;
+    /** Multiplicative back-off on a drop sample. Default 0.9. */
+    readonly backoffRatio?: number;
+}
+/**
+ * Gradient2 — adaptive limit based on the ratio of long-window RTT baseline to
+ * the current short-window RTT.
+ *
+ * Per window:
+ *
+ *   shortRtt  = window min RTT
+ *   longRtt   = EMA over windows of shortRtt
+ *   gradient  = clamp(tolerance · longRtt / shortRtt, minGradient, 1)
+ *   queue     = queueSize(limit)
+ *   newLimit  = limit · gradient + queue
+ *   if newLimit < limit:  newLimit ← smoothing · newLimit + (1−smoothing) · limit
+ *
+ * The `gradient ≤ 1` constraint means we only grow via the queue-size hedge —
+ * `limit · gradient` alone can never increase the limit. This matches the
+ * intuition that a fast response window is permission to add a probe, not to
+ * scale up multiplicatively.
+ */
+export declare class Gradient2Limit implements Limit {
+    private _limit;
+    readonly minLimit: number;
+    readonly maxLimit: number;
+    readonly windowNanos: number;
+    readonly minWindowSamples: number;
+    readonly tolerance: number;
+    readonly smoothing: number;
+    readonly minGradient: number;
+    readonly backoffRatio: number;
+    private readonly queueSizeFn;
+    private readonly longRtt;
+    private readonly listeners;
+    private windowStartNanos;
+    private windowMinRttNanos;
+    private windowMaxInflight;
+    private windowSamples;
+    private windowDropped;
+    constructor(opts?: Gradient2LimitOptions);
+    get limit(): number;
+    /** Long-window RTT baseline (ns). 0 until the first window commits. */
+    get longRttNanos(): number;
+    onSample(startNanos: Nanos, rttNanos: Nanos, inflight: number, didDrop: boolean): void;
+    onChange(listener: LimitChangeListener): Unsubscribe;
+    private commitWindow;
+}