@ayepi/rate 0.2.0 → 0.4.0

package/README.md

@@ -49,6 +49,9 @@ retryAfter }`); on exceeded requests the chain short-circuits with the 429.
 - `rateLimit.server(def, opts)` (`@ayepi/rate/server`) — binds the policy. These options
   move here: `key, limit, window, algorithm?, store?, prefix?, countRejected?, status?,
   message?, headers?, alwaysHeaders?, skip?`. Bind it with `implement(api).middleware(...)`.
+  The rule fields — `limit`, `window`, `algorithm`, `countRejected` — each accept a fixed
+  value **or** a per-request `(io) => value`, so limits can differ by caller (e.g.
+  `limit: (io) => io.ctx.user.plan === 'pro' ? 1000 : 100`).
 
 ## Standalone (without middleware)
 
@@ -94,6 +97,16 @@ const doer = rateLimitedDoer({ limit: 100, window: 60_000, algorithm: 'token-buc
 const w = createWork({ work: [sendEmail] as const, doer })   // ≤ 100 sends/min
 ```
 
+**Two-tier limiting.** Add a `groupLimit` (a default, or per task) and a task must clear both
+the global limit **and** its `group`'s limit — e.g. a global API cap plus a per-user/per-model
+cap. A hot group is skipped (not blocking others), groups needn't be known up front (buckets
+auto-evict when idle), and a shared `store`/`groupStore` (Redis) enforces both tiers across a fleet:
+
+```ts
+rateLimitedDoer({ limit: 1000, window: 60_000, groupLimit: 50 })
+  .do(() => callModel(req), { group: `${userId}:${modelId}`, groupLimit: 200 }) // per-request override
+```
+
 ## Algorithms
 
 - `fixed-window` (default) — simple counter per window.

package/ayepi-rate-stores-doer.md

@@ -49,15 +49,26 @@ Memcached, …); only `consume` is required.
 ### `memoryStore` (default, bundled)
 
 ```ts
-function memoryStore(): RateLimitStore
+function memoryStore(opts?: MemoryStoreOptions): RateLimitStore
+
+interface MemoryStoreOptions {
+  /** Sweep expired/idle entries once every this many `consume` calls (default 1000). */
+  readonly sweepEvery?: number;
+  /** Drop an idle token-bucket after this long with no activity (ms, default 10 min). */
+  readonly idleMs?: number;
+}
 ```
 
 An in-process store implementing all three algorithms, zero dependencies. It is the
-default when no `store` is passed. Expired counters and idle token buckets are swept
-lazily (amortized: a sweep runs once per ~1000 `consume` calls; idle buckets are dropped
-after ~10 minutes of inactivity since they refill to full anyway). **Single process only**
-— two server instances each get their own independent budget. Use the Redis store to share
-a limit across pods.
+default when no `store` is passed. **Single process only** — two server instances each get
+their own independent budget; use the Redis store to share a limit across pods.
+
+**Bounded memory for dynamic keys.** Entries are swept lazily, so an unbounded, not-known-in-advance
+key space — e.g. per-user/per-model rate-limit **groups** (see `rateLimitedDoer` below) — doesn't grow
+without bound: a windowed counter is dropped once its window has elapsed, and an idle `token-bucket`
+after `idleMs` (default 10 min; they refill to full anyway). Active keys live long enough to enforce
+the limit; idle ones go away. For high churn, lower `sweepEvery` (tighter memory, a little more scan
+cost) and/or `idleMs`: `memoryStore({ sweepEvery: 200, idleMs: 30_000 })`.
 
 ### `redisStore` — `@ayepi/rate/redis`
 
@@ -111,11 +122,28 @@ distributed store (verified by the integration test). `reset(key)` issues a `DEL
 ## `rateLimitedDoer` — gating task start rate
 
 ```ts
-function rateLimitedDoer(opts: RateLimitedDoerOptions): Doer
+function rateLimitedDoer(opts: RateLimitedDoerOptions): RateLimitedDoer
 
 interface RateLimitedDoerOptions extends LimiterOptions {
-  /** Limit key — a single shared bucket by default (`'doer'`), or derived per task. */
+  /** Limit key for the GLOBAL bucket — a single shared bucket by default (`'doer'`), or derived per task. */
   readonly key?: string | ((opts: DoerTaskOptions) => string);
+
+  // ── two-tier: an optional per-`group` limit on top of the global one ──
+  /** Default group limit (a second gate bucketed by a task's `group`). Per-task `groupLimit` overrides it; omit for global-only. */
+  readonly groupLimit?: number;
+  /** Derive a task's group bucket key (default `opts.group`). Return `undefined` to skip the group gate for a task. */
+  readonly groupKey?: (opts: DoerTaskOptions) => string | undefined;
+  /** Store for the group buckets (default: the global `store`). A distributed store limits groups across a fleet. */
+  readonly groupStore?: RateLimitStore;
+
+  // ── sustained-backlog watch (observational) ──
+  /** Fire while the pending queue stays continuously non-empty past `backlogAfterMs`. Must not throw. */
+  readonly onBacklog?: (info: RateLimitedBacklogInfo) => void;
+  /** How long the queue must stay non-empty before `onBacklog` first fires (ms). */
+  readonly backlogAfterMs?: number;
+  /** Re-fire `onBacklog` every this many ms while still backed up (omit to fire once). */
+  readonly backlogEveryMs?: number;
+
   /** Floor on the re-check delay for deferred tasks (ms, default 50). */
   readonly retryFloor?: number;
   /** Clock injection (default `Date.now`). */
@@ -123,6 +151,23 @@ interface RateLimitedDoerOptions extends LimiterOptions {
   /** The doer that actually runs admitted tasks (default `unlimitedDoer`). Compose policies. */
   readonly doer?: Doer;
 }
+
+/** Per-task options — DoerTaskOptions (`group`/`priority`/`createdAt`) plus a per-request group-limit override. */
+interface RateTaskOptions extends DoerTaskOptions {
+  readonly groupLimit?: number;      // overrides the configured default; enables the group gate for this task
+  readonly groupWindow?: number;     // default: the global `window`
+  readonly groupAlgorithm?: Algorithm; // default: the global `algorithm`
+}
+
+/** A Doer whose `do` accepts RateTaskOptions (assignable to Doer). */
+interface RateLimitedDoer extends Doer {
+  do(task: () => Promise<void>, opts?: RateTaskOptions): void;
+}
+
+interface RateLimitedBacklogInfo {
+  readonly pending: number;         // tasks waiting on the rate limit
+  readonly nonEmptyForMs: number;   // how long the queue has been continuously non-empty
+}
 ```
 
 (`RateLimitedDoerOptions` extends `LimiterOptions` — see `ayepi-rate.md` for
@@ -135,8 +180,50 @@ A `Doer` (from `@ayepi/core/doer`) that caps the **start rate** of tasks using t
 policy. Excess tasks wait, **oldest-first**; with a distributed store this rate-limits
 **across a fleet**.
 
-A `Doer` exposes `available()`, `do(task, opts?)`, and `done()` — see the doer section of
-the core docs. `rateLimitedDoer`'s `available()` is `min(limit − pending, inner.available())`.
+A `Doer` exposes `available()`, `do(task, opts?)`, and `done()` — see the doer section
+below. `rateLimitedDoer`'s `available()` is `min(limit − pending, inner.available())`.
+
+### Two-tier: a global limit + a per-group limit
+
+Set a `groupLimit` (a configured default, or per task via `RateTaskOptions`) and a task must
+clear **both** the global limit and its `group`'s limit to be admitted — e.g. a global API cap
+plus a per-user / per-model / per-model-family cap. `group` and `groupLimit` are read at
+**admission time**, so groups need not be known up front.
+
+```ts
+import { rateLimitedDoer } from '@ayepi/rate'
+
+const doer = rateLimitedDoer({
+  limit: 1000, window: 60_000, algorithm: 'token-bucket', // global cap
+  groupLimit: 50,                                          // default per-group cap
+})
+
+// per-request override — the limit known at request time (e.g. a plan tier):
+doer.do(() => callModel(req), { group: `${userId}:${modelId}`, groupLimit: tier === 'pro' ? 200 : 20 })
+```
+
+Semantics:
+
+- **Both gates, group first.** The group gate is checked before the global. A denied check
+  consumes nothing (the group rule forces `countRejected: false`), so a task whose group is at
+  its limit is **skipped**, not admitted — and no global token is spent on it.
+- **Head-of-line avoidance.** A skipped (group-capped) task is left pending while **other
+  groups' tasks proceed**, so a hot user/model can't block everyone. Within a group, oldest-first.
+- **Global exhaustion stops the round.** When the shared global bucket is out, nothing more is
+  admitted this pass. Edge case: a task that cleared its group but then hits an exhausted global
+  had its group token spent (bounded, self-corrects on retry) — only when global is the bottleneck.
+- **Global-only when no group.** A task with no `group`, or no group limit in scope, passes straight to the global gate.
+- **Fleet-shared, bounded memory.** Point `groupStore` (and `store`) at `@ayepi/rate/redis` to
+  share both tiers across pods. The dynamic group key space is auto-evicted (memory sweep / Redis
+  TTL), so it doesn't grow without bound — see `memoryStore` above.
+
+### Sustained-backlog watch
+
+`onBacklog` fires with `{ pending, nonEmptyForMs }` once the pending queue has stayed
+continuously non-empty past `backlogAfterMs` (repeating every `backlogEveryMs`, or once if
+omitted) — a signal that the rate limit can't admit fast enough. Purely observational
+(alerting/autoscaling), a throw is ignored, and the timer is `unref`'d and cleared when the
+queue drains.
 
 ### Example — cap an `@ayepi/work` engine
 
@@ -177,6 +264,33 @@ With a static `key` string (or the default `'doer'`) all tasks share one bucket.
 
 ---
 
+## The core `Doer` (`@ayepi/core/doer`)
+
+`rateLimitedDoer` builds on the runtime-agnostic `Doer` primitive:
+
+```ts
+interface Doer {
+  available(): number;                                   // how many tasks it will accept right now
+  do(task: () => Promise<void>, opts?: DoerTaskOptions): void; // fire-and-forget (swallows errors)
+  done(): Promise<void>;                                 // resolves when all accepted tasks settle
+}
+interface DoerTaskOptions { group?: string; priority?: number; createdAt?: number }
+```
+
+Bundled policies: **`unlimitedDoer`** (no cap), **`balancedDoer`** (cap N; fair-share across
+`group`s, then priority, then age), **`priorityDoer`** (cap N; highest priority first), **`ageDoer`**
+(cap N; oldest first). The three bounded doers share `BoundedDoerOptions` (`max`, `buffer?`, `now?`).
+
+- **`doWith(doer, fn, opts?)`** — submit a task and get its **result** back (`Promise<T>`), the
+  result-returning counterpart to the fire-and-forget `do` (which returns void and swallows the
+  error). Use it when a doer governs request-scoped work: `const user = await doWith(apiDoer, () => fetchUser(id), { group: tenantId })`.
+- **Sustained-backlog watch** — the bounded doers accept `onBacklog: (info) => void` with
+  `backlogAfterMs` / `backlogEveryMs`, firing `{ pending, running, nonEmptyForMs }` once the pending
+  queue stays continuously non-empty past the threshold (the doer analogue of `rateLimitedDoer`'s
+  `onBacklog`). Purely observational; one `unref`'d timer, only while backed up.
+
+---
+
 ## How it works under the hood
 
 ### The three algorithms
@@ -240,18 +354,21 @@ limiter's dependency middleware run first and their context is available — see
 
 ### The doer abstraction
 
-`rateLimitedDoer` keeps a `pending` queue. On each `drain`:
-
-- if the inner doer has no capacity (`inner.available() <= 0`), it arms a short re-check
-  timer and stops;
-- otherwise it picks the **oldest** pending task (by `createdAt`, then submission `seq`),
-  calls `limiter.check(keyOf(task), now())`;
-- if denied, it arms a timer for `max(retryFloor, retryAfter)` and stops (drains again when
-  the limiter would allow);
-- if admitted, it removes the task and calls `inner.do(task.run, task.opts)`.
-
-`done()` resolves once `pending` is empty **and** the inner doer's `done()` resolves. The
-re-check timer is `unref`'d, so it won't keep a process alive on its own.
+`rateLimitedDoer` keeps a `pending` queue. Each `drain` scans it **oldest-first** and admits
+every task that clears its gates, skipping (not blocking on) group-capped ones:
+
+- if the inner doer has no capacity (`inner.available() <= 0`), it records a short re-check and stops;
+- for the oldest not-yet-skipped task, it checks the **group gate first** (when a `group` + group
+  limit apply): a denied group check consumes nothing, so the task is **skipped** (left pending) and
+  the scan continues to other groups — recording that group's `retryAfter`;
+- then the **global gate** (`limiter.check(key, now)`): if denied, the shared bucket is out, so no
+  further task can be admitted this round and the scan stops (recording the global `retryAfter`);
+- if both allow, it removes the task and calls `inner.do(task.run, task.opts)`.
+
+After the scan, if tasks remain it arms **one** timer for the **soonest** recorded re-check
+(`max(retryFloor, soonest)`), so it drains again exactly when the earliest gate would allow. A
+store error on either gate is reported to `onError` and backs the round off by `retryFloor`. `done()`
+resolves once `pending` is empty **and** the inner doer's `done()` resolves. All timers are `unref`'d.
 
 ---
 

package/ayepi-rate.md

@@ -96,8 +96,8 @@ Everything below is exported. `@internal` symbols are intentionally omitted.
 | `limiter` | function | Standalone limiter primitive (`check`/`reset`/`rule`). |
 | `rateLimitResponse` | function | Build a 429 `Response` from limiter info. |
 | `rateLimitHeaders` | function | Compute the `RateLimit-*` header map from limiter info. |
-| `memoryStore` | function | The bundled in-process store (all three algorithms). |
-| `rateLimitedDoer` | function | A `Doer` that caps task **start rate**. |
+| `memoryStore` | function | The bundled in-process store (all three algorithms); `memoryStore(opts?)` — tunable eviction (`sweepEvery`/`idleMs`). |
+| `rateLimitedDoer` | function | A `Doer` that caps task **start rate** — global + optional **per-group** limit, plus a backlog watch. |
 | `Algorithm` | type | `'fixed-window' \| 'sliding-window' \| 'token-bucket'`. |
 | `RateLimitInfo` | interface | Limiter state exposed to handlers + headers. |
 | `RateLimitResult` | interface | `RateLimitInfo` + `allowed`. |
@@ -107,7 +107,11 @@ Everything below is exported. `@internal` symbols are intentionally omitted.
 | `LimiterOptions` | interface | Base config (`limit`/`window`/`algorithm`/`store`/`prefix`). |
 | `RateLimitResponseOptions` | interface | `status`/`message`/`headers` for `rateLimitResponse`. |
 | `RateLimitDefOptions` | interface | Options for the `rateLimit` def (`name`/`requires`). |
-| `RateLimitedDoerOptions` | interface | Options for `rateLimitedDoer`. |
+| `RateLimitedDoerOptions` | interface | Options for `rateLimitedDoer` (global + group limits, backlog watch). |
+| `RateLimitedDoer` | interface | The doer `rateLimitedDoer` returns (a `Doer` whose `do` takes `RateTaskOptions`). |
+| `RateTaskOptions` | interface | Per-task options — `DoerTaskOptions` + `groupLimit`/`groupWindow`/`groupAlgorithm`. |
+| `RateLimitedBacklogInfo` | interface | `{ pending, nonEmptyForMs }` passed to the doer's `onBacklog`. |
+| `MemoryStoreOptions` | interface | `{ sweepEvery?, idleMs? }` — tune `memoryStore` eviction. |
 | `Limiter` | interface | The object `limiter()` returns. |
 
 ### Server subpath `@ayepi/rate/server`
@@ -115,7 +119,8 @@ Everything below is exported. `@internal` symbols are intentionally omitted.
 | Export | Kind | Purpose |
 | --- | --- | --- |
 | `rateLimit` | function | Same name, **augmented with `.server(def, opts)`** to bind the policy. |
-| `RateLimitServerOptions` | interface | The policy options for `.server` (extends `LimiterOptions`). |
+| `RateLimitServerOptions` | interface | The policy options for `.server` (rule fields accept a static value or a per-request `(io) => T`). |
+| `RateKeyFn` / `Dynamic` | type | Helpers: `RateKeyFn<M, T> = (io) => T`; `Dynamic<M, T> = T \| RateKeyFn<M, T>` — the shape of every per-request option. |
 
 ### Redis subpath `@ayepi/rate/redis`
 
@@ -158,10 +163,10 @@ it in another middleware's `requires` (see `ayepi-core-middleware.md`).
 ### The impl (`@ayepi/rate/server`)
 
 ```ts
-rateLimit.server: <const R extends readonly AnyMiddleware[]>(
-  def: RateLimitDef<{ ratelimit: RateLimitInfo }, R>,
-  opts: RateLimitServerOptions<StackCtx<R>, R>,
-) => BoundMiddleware  // pass to implement(api).middleware(...)
+rateLimit.server: <M extends AnyMiddleware>(
+  def: M,                              // a RateLimitDef — its `requires` types `io.ctx`
+  opts: RateLimitServerOptions<M>,
+) => BoundMiddleware<M>  // pass to implement(api).middleware(...)
 ```
 
 `.server` binds the policy and returns the bound pair. It composes with the chainable
@@ -170,20 +175,35 @@ rateLimit.server: <const R extends readonly AnyMiddleware[]>(
 ### `RateLimitServerOptions`
 
 ```ts
-interface RateLimitServerOptions<Ctx extends object, R extends readonly AnyMiddleware[]>
-  extends LimiterOptions {
+// A rule field is either a fixed value or resolved per request from the key `io`.
+type RateKeyFn<M, T> = (io: RateKeyIO<StackCtx<ReqOf<M>>>) => T;
+type Dynamic<M, T>   = T | RateKeyFn<M, T>;
+
+interface RateLimitServerOptions<M extends AnyMiddleware> {
   /** Derive the rate-limit key from the request context (e.g. `io.ctx.user.id`). */
-  readonly key: (io: RateKeyIO<Ctx>) => string;
+  readonly key: RateKeyFn<M, string>;
+  /** Max requests (or token-bucket capacity) per window — fixed, or per request. */
+  readonly limit: Dynamic<M, number>;
+  /** Window length in ms (also the token refill period) — fixed, or per request. */
+  readonly window: Dynamic<M, number>;
+  /** Algorithm (default `'fixed-window'`) — fixed, or per request. */
+  readonly algorithm?: Dynamic<M, Algorithm>;
+  /** Count rejected (over-limit) requests against the limit (default `false`) — fixed, or per request. */
+  readonly countRejected?: Dynamic<M, boolean>;
+  /** Backend store (default an in-process `memoryStore`). */
+  readonly store?: RateLimitStore;
+  /** Key prefix/namespace (default `'rl:'`). */
+  readonly prefix?: string;
   /** Over-limit status code (default `429`). */
   readonly status?: number;
   /** Over-limit body — string, JSON value, or a function of (info, io). */
-  readonly message?: string | Json | ((info: RateLimitInfo, io: RateKeyIO<Ctx>) => string | Json);
+  readonly message?: string | Json | ((info: RateLimitInfo, io: RateKeyIO<StackCtx<ReqOf<M>>>) => string | Json);
   /** Response headers (see `RateLimitResponseOptions`). */
   readonly headers?: boolean | ((info: RateLimitInfo) => Record<string, string>);
   /** Also emit the `RateLimit-*` headers on allowed/skipped responses (default `false`). */
   readonly alwaysHeaders?: boolean;
   /** Bypass the limiter for some requests (e.g. an allow-list). */
-  readonly skip?: (io: RateKeyIO<Ctx>) => boolean;
+  readonly skip?: RateKeyFn<M, boolean>;
   /** Serve through (as allowed) when the **store** errors, instead of failing the request. Default `false` (fail-closed). */
   readonly failOpen?: boolean;
   /** Observe a store error (e.g. Redis down). Fires regardless of `failOpen`. Off by default; must not throw. */
@@ -191,30 +211,24 @@ interface RateLimitServerOptions<Ctx extends object, R extends readonly AnyMiddl
 }
 ```
 
+> **Dynamic policy.** `limit`, `window`, `algorithm`, and `countRejected` each accept a plain
+> value **or** a `(io) => value` resolved per request — so different callers get different
+> limits (e.g. a higher `limit` for a premium plan, a longer `window` for a trusted key). `io`
+> is the same `{ req, ctx }` `key`/`skip` receive, with `io.ctx` typed from the def's `requires`.
+> Resolve `window`/`algorithm` from a **stable** property of the identity (a given key should
+> always map to the same window/algorithm) — the store buckets its per-key state by them, so
+> varying them for one key across requests gives inconsistent accounting. Varying only `limit`
+> is always safe.
+
 > **Store errors.** By default the limiter is **fail-closed**: if the store (e.g. a Redis
 > outage) throws, the error propagates and the request is rejected — a store outage doesn't
 > silently lift the limit. Set `failOpen: true` to serve such requests through instead, and/or
 > `onError` to observe the failure (it fires either way). `rateLimitedDoer` takes an `onError`
 > too: a store error there is reported and admission retried — it never strands pending tasks.
 
-…plus everything from `LimiterOptions`:
-
-```ts
-interface LimiterOptions {
-  /** Max requests (or token-bucket capacity) per window. */
-  readonly limit: number;
-  /** Window length in milliseconds (also the token refill period). */
-  readonly window: number;
-  /** Algorithm (default `'fixed-window'`). */
-  readonly algorithm?: Algorithm;
-  /** Backend store (default an in-process `memoryStore`). */
-  readonly store?: RateLimitStore;
-  /** Key prefix/namespace (default `'rl:'`). */
-  readonly prefix?: string;
-  /** Count requests that are themselves rejected (over-limit) against the limit (default `false`). */
-  readonly countRejected?: boolean;
-}
-```
+> The standalone `limiter()` primitive (and `rateLimitedDoer`) takes a **static**
+> `LimiterOptions` (`limit`/`window`/`algorithm`/`store`/`prefix`/`countRejected`) — dynamic
+> resolution is a middleware feature, since only the request path carries an `io`.
 
 Notes grounded in the source:
 
@@ -304,6 +318,24 @@ const app = implement(api)
   .server()
 ```
 
+### Example — per-caller limits (dynamic `limit`)
+
+```ts
+// shared.ts — auth provides { user: { id, plan } }
+const limit = rateLimit({ requires: [auth] })
+// server.ts
+rateLimit.server(limit, {
+  key: (io) => io.ctx.user.id,
+  limit: (io) => (io.ctx.user.plan === 'pro' ? 1_000 : 100), // premium callers get more
+  window: 60_000,                                            // keep window/algorithm stable per key
+  algorithm: 'sliding-window',
+})
+```
+
+Any of `limit` / `window` / `algorithm` / `countRejected` can be a `(io) => value`. Derive
+`window`/`algorithm` from a stable identity attribute (plan, tenant) — not from time or the
+request path — so a given key always maps to the same bucketing.
+
 ### Example — per-IP limiting without `requires`
 
 ```ts

package/dist/index.cjs

@@ -66,10 +66,10 @@ function limiter(opts) {
 	const rule = {
 		limit: opts.limit,
 		window: opts.window,
-		algorithm: opts.algorithm ?? DEFAULT_ALGORITHM,
+		algorithm: opts.algorithm ?? "fixed-window",
 		countRejected: opts.countRejected ?? false
 	};
-	const prefix = opts.prefix ?? DEFAULT_PREFIX;
+	const prefix = opts.prefix ?? "rl:";
 	return {
 		rule,
 		check: (key, now) => store.consume(prefix + key, rule, now ?? Date.now()),
@@ -151,18 +151,78 @@ const DOER_RETRY_FLOOR = 50;
 * const doer = rateLimitedDoer({ limit: 100, window: 60_000, algorithm: 'token-bucket' })
 * const w = createWork({ work: [sendEmail] as const, doer })
 * ```
+*
+* **Two-tier limiting.** Set a `groupLimit` (default, or per task via {@link RateTaskOptions}) and a
+* task must clear both the global limit **and** its `group`'s limit — e.g. a global API cap plus a
+* per-user / per-model cap. The group gate is checked first (a denied group check consumes nothing),
+* so a task whose group is at its limit is **skipped** rather than blocking other groups, and the
+* shared global bucket isn't spent on it. `group`/`groupLimit` are read at admission time.
 */
 function rateLimitedDoer(opts) {
-	const lim = limiter(opts);
+	const store = opts.store ?? memoryStore();
+	const lim = limiter({
+		...opts,
+		store
+	});
 	const inner = opts.doer ?? (0, _ayepi_core_doer.unlimitedDoer)();
 	const now = opts.now ?? Date.now;
 	const floor = opts.retryFloor ?? DOER_RETRY_FLOOR;
 	const keyOf = (o) => typeof opts.key === "function" ? opts.key(o ?? {}) : opts.key ?? "doer";
+	const groupStore = opts.groupStore ?? store;
+	const groupPrefix = (opts.prefix ?? "rl:") + "grp:";
+	const groupKeyOf = (o) => opts.groupKey ? opts.groupKey(o ?? {}) : o?.group;
+	const groupRuleFor = (o) => {
+		const limit = o?.groupLimit ?? opts.groupLimit;
+		if (limit === void 0) return;
+		return {
+			limit,
+			window: o?.groupWindow ?? opts.window,
+			algorithm: o?.groupAlgorithm ?? opts.algorithm ?? "fixed-window",
+			countRejected: false
+		};
+	};
+	const report = (err) => {
+		try {
+			opts.onError?.(err);
+		} catch {}
+	};
 	const pending = [];
 	const idle = [];
 	let seq = 0;
 	let draining = false;
 	let timer = null;
+	const backlogWatch = opts.onBacklog !== void 0 && opts.backlogAfterMs !== void 0;
+	let nonEmptySince = null;
+	let backlogTimer = null;
+	const armBacklog = (ms) => {
+		backlogTimer = setTimeout(fireBacklog, ms);
+		backlogTimer.unref?.();
+	};
+	function fireBacklog() {
+		try {
+			opts.onBacklog({
+				pending: pending.length,
+				nonEmptyForMs: now() - nonEmptySince
+			});
+		} catch {}
+		if (opts.backlogEveryMs !== void 0) armBacklog(opts.backlogEveryMs);
+		else backlogTimer = null;
+	}
+	const syncBacklog = () => {
+		if (!backlogWatch) return;
+		if (pending.length > 0) {
+			if (nonEmptySince === null) {
+				nonEmptySince = now();
+				armBacklog(opts.backlogAfterMs);
+			}
+		} else {
+			nonEmptySince = null;
+			if (backlogTimer) {
+				clearTimeout(backlogTimer);
+				backlogTimer = null;
+			}
+		}
+	};
 	const arm = (ms) => {
 		if (timer) return;
 		timer = setTimeout(() => {
@@ -171,40 +231,67 @@ function rateLimitedDoer(opts) {
 		}, Math.max(floor, ms));
 		timer.unref?.();
 	};
+	/**
+	* The oldest pending task not skipped this round (a fresh scan, so tasks queued mid-drain are
+	* seen). `pending` is in insertion (seq) order, so equal `createdAt` ties keep the earliest.
+	*/
+	const nextPending = (skipped) => {
+		let best;
+		for (const t of pending) {
+			if (skipped.has(t)) continue;
+			if (!best || t.createdAt < best.createdAt) best = t;
+		}
+		return best;
+	};
 	const drain = async () => {
 		if (draining) return;
 		draining = true;
 		try {
-			while (pending.length > 0) {
+			const skipped = /* @__PURE__ */ new Set();
+			let soonest = Infinity;
+			for (;;) {
 				if (inner.available() <= 0) {
-					arm(floor);
+					soonest = Math.min(soonest, floor);
 					break;
 				}
-				let best = 0;
-				for (let i = 1; i < pending.length; i++) {
-					const a = pending[i];
-					const b = pending[best];
-					if (a.createdAt < b.createdAt || a.createdAt === b.createdAt && a.seq < b.seq) best = i;
+				const task = nextPending(skipped);
+				if (!task) break;
+				const o = task.opts;
+				const groupRule = groupRuleFor(o);
+				const gk = groupKeyOf(o);
+				if (groupRule && gk !== void 0) {
+					let gr;
+					try {
+						gr = await groupStore.consume(groupPrefix + gk, groupRule, now());
+					} catch (err) {
+						report(err);
+						soonest = Math.min(soonest, floor);
+						break;
+					}
+					if (!gr.allowed) {
+						soonest = Math.min(soonest, gr.retryAfter);
+						skipped.add(task);
+						continue;
+					}
 				}
-				const task = pending[best];
 				let res;
 				try {
-					res = await lim.check(keyOf(task.opts), now());
+					res = await lim.check(keyOf(o), now());
 				} catch (err) {
-					try {
-						opts.onError?.(err);
-					} catch {}
-					arm(floor);
+					report(err);
+					soonest = Math.min(soonest, floor);
 					break;
 				}
 				if (!res.allowed) {
-					arm(res.retryAfter);
+					soonest = Math.min(soonest, res.retryAfter);
 					break;
 				}
-				pending.splice(best, 1);
+				pending.splice(pending.indexOf(task), 1);
 				inner.do(task.run, task.opts);
 			}
 			if (pending.length === 0) for (const r of idle.splice(0)) r();
+			else arm(soonest);
+			syncBacklog();
 		} finally {
 			draining = false;
 		}
@@ -218,6 +305,7 @@ function rateLimitedDoer(opts) {
 				createdAt: o?.createdAt ?? now(),
 				seq: seq++
 			});
+			syncBacklog();
 			drain();
 		},
 		done: () => pending.length === 0 ? inner.done() : new Promise((r) => idle.push(() => void inner.done().then(r)))
@@ -298,19 +386,26 @@ function tokenBucket(buckets, key, rule, now) {
 	};
 }
 /**
-* An in-process {@link RateLimitStore} implementing all three algorithms. The
-* default store — fine for a single instance; use a distributed store (e.g.
-* `@ayepi/rate/redis`) to share limits across pods. Expired entries are swept
-* lazily.
+* An in-process {@link RateLimitStore} implementing all three algorithms. The default store — fine
+* for a single instance; use a distributed store (e.g. `@ayepi/rate/redis`, which sets key TTLs) to
+* share limits across pods.
+*
+* **Bounded memory for dynamic keys.** Entries are swept lazily so an unbounded, not-known-in-advance
+* key space (per-user/per-model rate-limit **groups**) doesn't grow without bound: a windowed counter
+* is dropped once its window elapses, and an idle token-bucket after {@link MemoryStoreOptions.idleMs}.
+* Active keys live long enough to enforce the limit; idle ones go away. Tune {@link MemoryStoreOptions}
+* for high churn.
 */
-function memoryStore() {
+function memoryStore(opts = {}) {
+	const sweepEvery = opts.sweepEvery ?? SWEEP_EVERY;
+	const idleMs = opts.idleMs ?? BUCKET_IDLE_MS;
 	const counters = /* @__PURE__ */ new Map();
 	const buckets = /* @__PURE__ */ new Map();
 	let ops = 0;
 	const sweep = (now) => {
-		if (++ops % SWEEP_EVERY !== 0) return;
+		if (++ops % sweepEvery !== 0) return;
 		for (const [k, e] of counters) if (e.reset <= now) counters.delete(k);
-		for (const [k, b] of buckets) if (now - b.ts > BUCKET_IDLE_MS) buckets.delete(k);
+		for (const [k, b] of buckets) if (now - b.ts > idleMs) buckets.delete(k);
 	};
 	return {
 		consume(key, rule, now) {
@@ -329,6 +424,8 @@ function memoryStore() {
 	};
 }
 //#endregion
+exports.DEFAULT_ALGORITHM = DEFAULT_ALGORITHM;
+exports.DEFAULT_PREFIX = DEFAULT_PREFIX;
 exports.limiter = limiter;
 exports.memoryStore = memoryStore;
 exports.rateLimit = rateLimit;