dynamic-throttled-queue 3.0.0-rc.1d87d99 → 3.0.0-rc.ea3019c

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "dynamic-throttled-queue",
-  "version": "3.0.0-rc.1d87d99",
+  "version": "3.0.0-rc.ea3019c",
   "type": "module",
   "description": "Dynamically throttles arbitrary code to execute between a minimum and maximum number of times per interval. Best for making throttled API requests.",
   "files": [
-    "dist"
+    "dist",
+    "skills/configure-throttled-queue"
   ],
   "zshy": {
     "exports": {
@@ -22,7 +23,8 @@
     "queue",
     "throttle",
     "throttled",
-    "request"
+    "request",
+    "tanstack-intent"
   ],
   "author": "Adrian Elton-Browning <gingacodemonkey@gmail.com>",
   "license": "MIT",
@@ -33,6 +35,7 @@
     "@commitlint/cli": "21.2.3",
     "@commitlint/config-conventional": "20.0.0",
     "@gingacodemonkey/config": "^0.0.38",
+    "@tanstack/intent": "0.5.0",
     "@types/node": "^24.13.3",
     "@varlock/bumpy": "^1.18.1",
     "eslint": "^9.39.5",
@@ -72,6 +75,7 @@
     "lint:e18e": "pnpm dlx @e18e/cli analyze",
     "preinstall": "only-allow pnpm",
     "bump": "bumpy add",
-    "bump:status": "bumpy status"
+    "bump:status": "bumpy status",
+    "skills:check": "intent maintainer check"
   }
 }

package/skills/configure-throttled-queue/SKILL.md

@@ -0,0 +1,340 @@
+---
+name: configure-throttled-queue
+description: >
+  Use when creating, configuring, or debugging a dynamic-throttled-queue
+  (createThrottledQueue): pacing calls to a rate-limited API, choosing
+  min_rpi/max_rpi/interval/concurrency, adapting the rate to errors or HTTP
+  429s, retrying failed work, honoring Retry-After, getting results back with
+  submit() and cancelling them, or pausing, stopping, aborting, and draining
+  the queue.
+metadata:
+  purpose: >
+    Teach agents to configure dynamic-throttled-queue correctly: start-rate
+    pacing versus async concurrency, adaptive-rate outcome classification
+    versus retry eligibility, server-directed cooldowns, task handles, and the
+    pause/resume/stop/abort/failed lifecycle semantics.
+  type: core
+  library: dynamic-throttled-queue
+  library_version: 2.2.0
+sources:
+  - src/*.ts
+  - src/__tests__/*.test.ts
+  - tests/skills/configure-throttled-queue/*
+  - README.md
+---
+
+# Configure a dynamic-throttled-queue
+
+`createThrottledQueue(options)` returns a function that enqueues callbacks, plus
+control methods. Work through the steps in order; each ends with a check.
+
+## Setup
+
+```ts
+import { createThrottledQueue } from "dynamic-throttled-queue";
+
+// At most 5 request starts per second, spread evenly (one every 200 ms).
+const queue = createThrottledQueue({ min_rpi: 5, interval: 1000 });
+
+queue(async ({ signal }) => {
+  const response = await fetch("https://api.example.com/data", { signal });
+  if (!response.ok) return false; // fire-and-forget failure signal
+});
+```
+
+The package is ESM-only and requires Node.js 24 or later.
+
+## 1. Pick the start rate
+
+The rate counts **callback starts per `interval` milliseconds**. It says nothing
+about how long a callback runs.
+
+| Option | Meaning | Rule |
+| --- | --- | --- |
+| `min_rpi` | Lowest starts per interval | Required positive integer |
+| `max_rpi` | Highest starts per interval | Integer `>= min_rpi`; defaults to `min_rpi` |
+| `interval` | Window length in ms | Required positive number |
+| `evenly_spaced` | `true` (default): one start every `interval / rate` ms. `false`: up to `rate` starts at once per interval | |
+
+- A provider limit of "100 requests per minute" is `{ min_rpi: 100, interval: 60_000 }`.
+  Use `evenly_spaced: false` only when bursts are allowed.
+- With `max_rpi === min_rpi` the rate is fixed. With a range, the queue starts at
+  `Math.ceil((min_rpi + max_rpi) / 2)` and adapts between the bounds (step 3).
+- Set `max_rpi` to the provider's documented ceiling, never above it: the default
+  strategy raises the rate after every clean interval that has pending work.
+
+Check: `createThrottledQueue` throws synchronously on invalid numbers, and
+`queue.getState().rate` shows the starting rate.
+
+## 2. Bound in-flight work separately
+
+`concurrency` caps callbacks still awaiting asynchronous settlement. It is
+independent of the start rate; omitting it allows unlimited in-flight work.
+Use both when the provider limits requests per window **and** simultaneous
+connections:
+
+```ts
+import { createThrottledQueue } from "dynamic-throttled-queue";
+
+const queue = createThrottledQueue({
+  min_rpi: 10,
+  interval: 1000,
+  concurrency: 3, // never more than 3 unsettled callbacks
+  maxQueueSize: 1000, // bound accepted, not-yet-terminal work
+});
+```
+
+When `maxQueueSize` is reached, `queue(...)` and `submit(...)` **throw
+synchronously** (`Cannot enqueue work: maxQueueSize has been reached`). Capacity covers
+pending, active, and retrying work until each item is terminal.
+
+Check: `getState().active` never exceeds `concurrency`.
+
+## 3. Decide which failures adapt the rate
+
+A failure is a callback that returns `false`, throws, or rejects. By default
+every failure counts toward `errors_per_interval` (default `5`). When the count
+reaches the threshold, the default `linear` strategy lowers the rate by 1; an
+interval with zero errors and pending work raises it by 1. `back_off: true`
+also skips one full interval after the threshold is hit.
+
+Count only capacity signals with `rateOutcomeClassifier`. It receives
+`{ kind: "returned-false" }`, `{ kind: "thrown", error }`, or
+`{ kind: "rejected", error }` and returns whether the failure reduces the rate:
+
+```ts
+import { createThrottledQueue, type FailureOutcome } from "dynamic-throttled-queue";
+
+class HttpError extends Error {
+  constructor(readonly status: number) {
+    super(`HTTP ${status}`);
+  }
+}
+
+function isCapacitySignal(outcome: FailureOutcome): boolean {
+  if (outcome.kind === "returned-false") return false;
+  const { error } = outcome;
+  return error instanceof HttpError && (error.status === 429 || error.status >= 500);
+}
+
+const queue = createThrottledQueue({
+  min_rpi: 1,
+  max_rpi: 20,
+  interval: 1000,
+  errors_per_interval: 3,
+  back_off: true,
+  rateOutcomeClassifier: isCapacitySignal,
+  onRateChange: rate => console.log(`rate is now ${rate}/s`),
+});
+```
+
+If the classifier throws, the failure counts as rate-reducing. To change how
+the rate moves (for example AIMD), read
+[rate strategies and timing](references/rate-strategies.md).
+
+Check: `getState().rateDecreases` grows only for the failures you classify as
+capacity signals.
+
+## 4. Configure retries independently
+
+`retry` is the hard cap on extra attempts (default `0`). `retryClassifier`
+decides eligibility per failure and must return literal `true` to retry.
+`retryBackoff` delays retries; without it they are immediate.
+
+```ts
+import { createThrottledQueue } from "dynamic-throttled-queue";
+
+const queue = createThrottledQueue({
+  min_rpi: 5,
+  interval: 1000,
+  retry: 3,
+  retryClassifier: (outcome, attempt) => outcome.kind !== "returned-false" && attempt <= 3,
+  retryBackoff: { strategy: "exponential", baseDelay: 250, maxDelay: 10_000, jitter: 0.2 },
+});
+```
+
+Retry and rate decisions are separate: a failure can be retryable,
+rate-reducing, both, or neither. Every retry is a new attempt that obeys normal
+pacing. For backoff formulas and validation, read
+[retry details](references/retries.md).
+
+Check: `getState().retried` counts scheduled retries; the callback's
+`attempt` (1-based) counts up across retries.
+
+## 5. Honor server cooldowns
+
+When a server says when capacity returns (HTTP 429 with `Retry-After`), call
+`cooldownFor(ms)`. The queue starts nothing new until then, keeps pending
+work, and makes no rate decision meanwhile. It does not retry or lower the rate
+on its own; combine it with steps 3 and 4.
+
+```ts
+import { createThrottledQueue } from "dynamic-throttled-queue";
+
+const queue = createThrottledQueue({ min_rpi: 1, max_rpi: 10, interval: 1000, retry: 2, maxCooldown: 60_000 });
+
+const task = queue.submit(async ({ signal }) => {
+  const response = await fetch("https://api.example.com/data", { signal });
+  if (response.status === 429) {
+    const seconds = Number(response.headers.get("Retry-After"));
+    if (Number.isFinite(seconds) && seconds >= 0) queue.cooldownFor(seconds * 1000);
+    throw new Error("rate limited");
+  }
+  return response.json() as Promise<unknown>;
+});
+```
+
+Convert the header yourself and clamp past dates to `0`: `NaN`, negative, and
+infinite delays throw `RangeError`. Delays above `maxCooldown` are clamped. A
+later deadline replaces an earlier one; overlapping hints do not add up.
+
+Check: `getState().cooldownRemaining` is non-zero during the cooldown.
+
+## 6. Get results with task handles
+
+Use `submit()` when the caller needs the value. Its semantics differ from the
+fire-and-forget form:
+
+- Every returned value, **including `false`**, is a successful result. Only a
+  throw or rejection fails, retries, and counts for the rate.
+- `result` settles once: the final value, the last attempt's error, or the
+  cancel reason.
+- `cancel(reason?)` rejects `result` immediately (an `AbortError` by default).
+  A pending item is removed; an active one has only its own signal aborted and
+  keeps its concurrency slot until the callback returns. Cancelled work never
+  retries and never counts as success, failure, or a rate error.
+
+```ts
+import { createThrottledQueue } from "dynamic-throttled-queue";
+
+const queue = createThrottledQueue({ min_rpi: 5, interval: 1000, retry: 2 });
+
+const task = queue.submit(async ({ signal, attempt }) => {
+  const response = await fetch("https://api.example.com/item", { signal });
+  if (!response.ok) throw new Error(`HTTP ${response.status} on attempt ${attempt}`);
+  return (await response.json()) as { id: string };
+});
+
+setTimeout(() => task.cancel(), 5000);
+const item = await task.result.catch(() => undefined);
+```
+
+Check: every `result` you cancel or abort has a rejection handler.
+
+## 7. Control the lifecycle
+
+| Call | Effect | Reversible |
+| --- | --- | --- |
+| `pause()` | No new starts; keeps work; active callbacks finish | `resume()` |
+| `stop()` | Clears timers; keeps work | The next enqueue restarts it |
+| `abort()` | Discards pending work, aborts the shared signal, later enqueues throw | No |
+
+A throwing or malformed `rateStrategy` moves the queue to `failed`: terminal,
+pending work discarded, enqueues throw the strategy error, and `waitForIdle()`
+promises reject with it.
+Create a new queue to continue. For per-state rules, read
+[lifecycle details](references/lifecycle.md) before writing shutdown,
+pause, or error-recovery code.
+
+Drain and inspect:
+
+```ts
+import { createThrottledQueue } from "dynamic-throttled-queue";
+
+const queue = createThrottledQueue({ min_rpi: 5, interval: 1000 });
+for (const id of ["a", "b", "c"]) {
+  queue(async ({ signal }) => {
+    await fetch(`https://api.example.com/items/${id}`, { signal });
+  });
+}
+
+await queue.waitForIdle(); // pending, active, and delayed retries all terminal
+const { succeeded, failed, state } = queue.getState();
+console.log({ succeeded, failed, state });
+```
+
+For every `getState()` field and `waitForIdle()` edge case, read
+[state and idle](references/state-and-idle.md).
+
+Check: `waitForIdle()` resolves and `getState().pending` and `.active` are `0`.
+
+## Common Mistakes
+
+### CRITICAL: Ignoring the signal and expecting abort or cancel to stop work
+
+```ts
+import { createThrottledQueue } from "dynamic-throttled-queue";
+
+const queue = createThrottledQueue({ min_rpi: 5, interval: 1000 });
+// Wrong: abort() cannot stop this request
+queue(async () => { await fetch("https://api.example.com/data"); });
+// Right
+queue(async ({ signal }) => { await fetch("https://api.example.com/data", { signal }); });
+```
+
+Cancellation is cooperative. A callback that ignores `signal` keeps running
+after `abort()` or `cancel()`; only its outcome is discarded. Source: README
+"Lifecycle"; `src/scheduler.ts`.
+
+### CRITICAL: Starting a promise without returning or awaiting it
+
+```ts
+import { createThrottledQueue } from "dynamic-throttled-queue";
+
+const queue = createThrottledQueue({ min_rpi: 5, interval: 1000, concurrency: 2, retry: 2 });
+// Wrong: the queue sees a synchronous success; no retry, no concurrency slot
+queue(({ signal }) => { void fetch("https://api.example.com/data", { signal }).catch(() => {}); });
+// Right: return (or await) the work
+queue(({ signal }) => fetch("https://api.example.com/data", { signal }));
+```
+
+The queue only tracks what the callback returns. An unreturned promise cannot
+fail, retry, hold a `concurrency` slot, or delay `waitForIdle()`. Source: README
+"Queuing work".
+
+### HIGH: Using the rate to limit simultaneous requests
+
+`min_rpi: 3` allows 3 starts per interval; slow callbacks pile up without
+bound. Add `concurrency` for an in-flight cap. Source: `ThrottleOptions.concurrency`.
+
+### HIGH: Returning `false` from `submit()` to signal failure
+
+In `submit()`, `false` is a successful result: no retry, no rate reduction.
+Throw instead. Fire-and-forget callbacks still treat `false` as failure; any
+other returned value is success. Source: `TaskCallback` and `ThrottleCallback`
+in `src/scheduler.ts`.
+
+### HIGH: Expecting `retryClassifier` or cooldowns to change the rate
+
+Retry eligibility, rate counting (`rateOutcomeClassifier`), and `cooldownFor`
+are three independent decisions. Configure each one you need. Source: README
+"Failure classification" and "Server-directed cooldown".
+
+### HIGH: Unhandled rejections from cancelled or aborted tasks
+
+`cancel()` and `abort()` reject `task.result`. Attach a handler such as
+`task.result.catch(() => {})` if you do not await it.
+
+### MEDIUM: Treating `stop()` as shutdown
+
+`stop()` keeps pending work and the next enqueue restarts processing. Use
+`abort()` for terminal shutdown.
+
+### MEDIUM: Catching the `maxQueueSize` overflow as a return value
+
+A full queue throws from `queue(...)` and `submit(...)`. Wrap enqueue
+calls in `try`/`catch` when `maxQueueSize` is set.
+
+## Completion
+
+The configuration is complete when:
+
+1. The start rate matches the provider limit and `max_rpi` does not exceed it.
+2. `concurrency` is set when the provider limits simultaneous requests.
+3. Each failure type is deliberately classified for rate reduction and retry.
+4. Every async callback passes `signal` to its I/O.
+5. Every `submit()` result is awaited or has a rejection handler.
+6. Shutdown uses `abort()` or `waitForIdle()`, not `stop()`.
+
+If the queue reports `state: "failed"`, fix the custom `rateStrategy` and
+create a new queue.

package/skills/configure-throttled-queue/references/lifecycle.md

@@ -0,0 +1,46 @@
+# Lifecycle details
+
+Read this before writing shutdown, pause/resume, or error-recovery code, or
+when a queue stops starting work unexpectedly.
+
+| State | Pending work and enqueue | Active work | Lifecycle calls |
+| --- | --- | --- | --- |
+| `running` | Starts normally; enqueues accepted | Runs | `pause()` retains work and stops starts. `stop()` retains work and clears timers. `abort()` is terminal. A strategy failure moves to `failed`. |
+| `paused` | Pending work, new enqueues, and retries are kept but do not start | Continues and settles | `resume()` restarts pacing at the current rate with a fresh observation window. `pause()` is idempotent. `stop()` clears the paused state. |
+| `stopped` | Pending work kept; the next enqueue restarts scheduling | Continues and settles | `pause()` and `resume()` do nothing. `stop()` is idempotent. |
+| `aborted` | Pending work discarded; enqueues throw | Receives the aborted shared signal and may finish cooperatively | Nothing restarts scheduling. `abort()` is idempotent. |
+| `failed` | Pending work and delayed retries discarded; enqueues throw the strategy error | Continues and settles without retries or accounting; the shared signal is **not** aborted | Terminal. All lifecycle calls do nothing. |
+
+## Rules that are easy to miss
+
+- While paused, outcomes do not adjust the rate. A failure can still create a
+  retry, which waits for `resume()`.
+- `stop()` cannot cancel an active callback, and that callback settling does not
+  restart scheduling. Only a new enqueue does, and it also resumes frozen
+  delayed retries.
+- `abort()` aborts one shared signal for fire-and-forget callbacks; `submit()`
+  callbacks get a per-item signal that `abort()` also aborts. Late outcomes are
+  discarded and never retry.
+- On `failed`, the strategy error is rethrown where the decision ran: as an
+  uncaught exception from the adaptive-rate timer, or as an unhandled rejection
+  when a slow async callback completes a settled-timing window. Pending and
+  later `waitForIdle()` calls reject with it. Create a new queue to resume.
+
+## Cooldown interaction
+
+- `pause()` and `cooldownFor()` are separate. A cooldown keeps elapsing while
+  paused, its end does not resume a paused queue, and `resume()` does not end it.
+- `stop()` clears the cooldown timer but keeps the deadline, so the restarting
+  enqueue still waits for it.
+- `abort()` and a strategy failure clear the cooldown; later valid
+  `cooldownFor()` calls do nothing, but invalid delays still throw `RangeError`.
+- A cooldown replaces any adaptive-rate backoff in progress. Failures that
+  settle during a cooldown count toward the first decision after it.
+
+## Task handles across the lifecycle
+
+- `pause()` and `stop()` leave `result` pending.
+- `abort()` rejects every unsettled `result` with the queue signal's
+  `AbortError`; a strategy failure rejects them with the strategy error.
+- `submit()` throws synchronously and returns no handle when the queue is full,
+  aborted, or failed.

package/skills/configure-throttled-queue/references/rate-strategies.md

@@ -0,0 +1,68 @@
+# Rate strategies and adjustment timing
+
+Read this when the default one-step `linear` adaptation is too slow or too
+fast, when writing a custom `RateStrategy`, or when slow callbacks make rate
+decisions land in the wrong interval.
+
+## Built-in strategies
+
+| Strategy | Threshold reached | Clean interval with pending work | Otherwise |
+| --- | --- | --- | --- |
+| `linear` (default) | `currentRate - 1`, request backoff | `currentRate + 1` | hold |
+| `aimd({ increaseBy = 1, decreaseFactor = 0.5 })` | `Math.floor(currentRate * decreaseFactor)`, request backoff | `currentRate + increaseBy` | hold |
+
+A backoff request (`shouldBackOff: true`) skips an interval only when the queue
+has `back_off: true`.
+
+"Clean" means zero counted errors and the previous window was not a backoff.
+Partial-error, empty, and immediately-post-backoff windows hold the rate. The
+queue clamps every `nextRate` to `[min_rpi, max_rpi]`. `aimd()` throws unless
+`increaseBy` is a positive integer and `0 < decreaseFactor < 1`.
+
+```ts
+import { aimd, createThrottledQueue } from "dynamic-throttled-queue";
+
+const queue = createThrottledQueue({
+  min_rpi: 1,
+  max_rpi: 100,
+  interval: 1000,
+  rateStrategy: aimd({ increaseBy: 2, decreaseFactor: 0.5 }),
+});
+```
+
+## Custom strategies
+
+A `RateStrategy` is a pure function. It receives a frozen observation
+`{ currentRate, minRate, maxRate, errorCount, errorThreshold, hasPendingWork, wasBackedOff }`
+and returns `{ nextRate, shouldBackOff }`.
+
+```ts
+import { createThrottledQueue, type RateStrategy } from "dynamic-throttled-queue";
+
+const decreaseOnly: RateStrategy = ({ currentRate, minRate, errorCount, errorThreshold }) => ({
+  nextRate: errorCount >= errorThreshold ? Math.max(minRate, currentRate - 1) : currentRate,
+  shouldBackOff: errorCount >= errorThreshold,
+});
+
+const queue = createThrottledQueue({ min_rpi: 1, max_rpi: 10, interval: 1000, rateStrategy: decreaseOnly });
+```
+
+- `nextRate` must be a finite integer and `shouldBackOff` a boolean. Anything
+  else, or a thrown error, **fails the queue permanently** (see
+  [lifecycle](lifecycle.md)). Never return `NaN`, fractions, or `undefined`.
+- `shouldBackOff` only pauses scheduling when the queue has `back_off: true`.
+
+## Adjustment timing
+
+- `adjustmentTiming: "interval"` (default): each interval decides from the
+  outcomes that have settled so far. A slow callback can settle after its start
+  interval and affect a later decision.
+- `adjustmentTiming: "settled"`: a window holds every attempt started during one
+  interval. When collection closes, no further callbacks start until every
+  attempt in the window settles, then exactly one decision is made. Use it when
+  callbacks run longer than `interval` and decisions must reflect complete
+  windows. A callback that never settles blocks later windows until it settles
+  or the queue is aborted, so give callbacks timeouts.
+
+While paused, settled outcomes do not count toward the rate. In settled timing,
+`pause()` discards the open window.

package/skills/configure-throttled-queue/references/retries.md

@@ -0,0 +1,52 @@
+# Retry details
+
+Read this when choosing a `retryBackoff` policy, when `createThrottledQueue`
+rejects retry options, or when retry counts in `getState()` look wrong.
+
+## Eligibility
+
+1. A failure (`false` in fire-and-forget form, a throw, or a rejection) is
+   eligible only while `retry` budget remains. `retry` must be a non-negative
+   integer.
+2. If `retryClassifier` is set, it is called with the normalized outcome and the
+   one-based attempt that just failed. Only literal `true` retries; any other
+   value makes the failure permanent. It is not called once the budget is spent.
+3. If the classifier throws, the queue retries within the remaining budget.
+
+Cancelled tasks, and outcomes that settle after `abort()` or a strategy
+failure, never retry.
+
+## Backoff
+
+`retryBackoff` is
+`{ strategy: "fixed" | "linear" | "exponential"; baseDelay: number; maxDelay?: number; jitter?: number; random?: () => number }`.
+
+For retry index `n` (first retry is `1`):
+
+| Strategy | Delay before cap |
+| --- | --- |
+| `fixed` | `baseDelay` |
+| `linear` | `baseDelay × n` |
+| `exponential` | `baseDelay × 2^(n - 1)` |
+
+The delay is capped at `maxDelay`, symmetric percentage `jitter` (`0`–`1`) is
+applied, then it is capped again. `baseDelay` and `maxDelay` must be finite and
+non-negative; an unknown `strategy` throws. Pass `random` to make jitter
+deterministic in tests; a throwing or out-of-range `random` falls back to no
+jitter.
+
+Backoff starts when the failed attempt settles. It is independent of the
+adaptive-rate `back_off` option.
+
+## Scheduling
+
+Delayed retries count as pending work and occupy `maxQueueSize` capacity. When
+due, they rejoin the tail of the queue and obey normal pacing; equal due times
+keep their scheduling order. While paused or stopped, their remaining delay
+freezes. `abort()` discards them.
+
+## Counters
+
+`started`, `succeeded`, and `failed` count attempts: a failure is counted even
+when a later retry succeeds. `retried` increments only when another attempt is
+actually scheduled.

package/skills/configure-throttled-queue/references/state-and-idle.md

@@ -0,0 +1,38 @@
+# State and idle
+
+Read this when reporting queue metrics, asserting on queue state in tests, or
+waiting for work to finish.
+
+## `getState()`
+
+Returns a frozen snapshot; mutating it does not affect the queue.
+
+| Field | Meaning |
+| --- | --- |
+| `rate` | Current starts per interval |
+| `pending` | Queued items plus delayed retries |
+| `active` | Callbacks currently executing |
+| `state` | `"running"`, `"paused"`, `"stopped"`, `"aborted"`, or `"failed"` |
+| `cooldownRemaining` | Ms until the cooldown ends, rounded up; `0` when none |
+| `started`, `succeeded`, `failed` | Attempts; a retry is a new attempt |
+| `retried` | Retries actually scheduled |
+| `canceled` | Submitted items whose `result` `cancel()` rejected |
+| `rateIncreases`, `rateDecreases` | Applied rate changes; match `onRateChange` calls exactly |
+| `cooldowns`, `cooldownTotal` | `cooldownFor()` calls that moved the deadline later, and the ms they added |
+
+Counters are monotonic and stop changing after `abort()` or a strategy failure.
+A cancelled active attempt counts as neither succeeded nor failed.
+
+## `waitForIdle()`
+
+Resolves once pending work, active callbacks, and delayed retries are all
+terminal; immediately if already idle.
+
+- One-shot: a later enqueue does not affect a resolved promise. Concurrent
+  callers resolve together.
+- A failure that schedules a retry never produces a transient idle.
+- After `stop()`, waiters stay pending until a later enqueue lets the work
+  finish. Do not use `stop()` + `waitForIdle()` as shutdown.
+- After `abort()`, waiters resolve as soon as no callback is active.
+- While paused, waiters resolve only when pending and active are both `0`.
+- On `failed`, every waiter rejects with the strategy error at once.