first commit

docs/foundation/flow/streams-chunk-queue/src/rate-limiter/adapter.md

@@ -0,0 +1,86 @@
+# rate-limiter / adapter
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+Normalises the `@suaveplan/rate-limiter` `TokenBucket` API onto
+the `ChunkRateLimiter` interface used internally by the streaming chunk
+queue. The `TokenBucket` does NOT throw on denial — it returns
+`{ allowed: boolean, retryAfter?: number }`. This adapter encodes the
+denial branch into the canonical `{ allowed: false, delay }` shape the
+queue understands, with a configurable fallback when `retryAfter` is
+missing.
+
+## Features
+
+- Wraps any structurally compatible `TokenBucketLike`.
+- Returns `{ allowed: true, delay: 0 }` on admission.
+- Returns `{ allowed: false, delay }` on denial, using `retryAfter` when
+  positive or a configurable fallback (default 100 ms) otherwise.
+- Stateless beyond the bucket reference — safe to share across queues.
+
+## Usage: Basic
+
+```ts
+import { TokenBucket } from "@suaveplan/rate-limiter";
+import { TokenBucketRateLimiterAdapter } from "@suaveplan/streams-chunk-queue";
+
+const bucket = new TokenBucket({ capacity: 1024 * 1024, refillRate: 1024 });
+const limiter = new TokenBucketRateLimiterAdapter(bucket);
+```
+
+## Usage: Advanced
+
+```ts
+// Aggressive fallback for tightly-bound real-time streams.
+const limiter = new TokenBucketRateLimiterAdapter(bucket, 25);
+```
+
+## API Reference
+
+### `ChunkRateLimiter`
+
+```ts
+interface ChunkRateLimiter {
+    consume(bytes: number): { allowed: boolean; delay: number };
+}
+```
+
+### `TokenBucketLike`
+
+Structural subset of the `TokenBucket`:
+
+```ts
+interface TokenBucketLike {
+    consume(tokens?: number): { allowed: boolean; retryAfter?: number };
+}
+```
+
+### `TokenBucketRateLimiterAdapter`
+
+```ts
+new TokenBucketRateLimiterAdapter(
+    bucket: TokenBucketLike,
+    fallbackDelayMs?: number, // default 100
+)
+```
+
+`consume(bytes)` calls `bucket.consume(bytes)` and normalises the
+result. The fallback delay is used only when the bucket denies AND
+omits / zeroes `retryAfter`.
+
+### `DEFAULT_RATE_LIMIT_DELAY_MS`
+
+The constant `100`. Exposed for callers who want to reuse the default
+in their own diagnostics.
+
+## Implementation Notes
+
+The structural `TokenBucketLike` keeps `@suaveplan/rate-limiter` an
+optional peer concern at the type boundary — tests inject a fake
+bucket and never need to spin up the real one. The adapter does not
+sleep itself; the queue is in charge of timing because it owns the
+`onRateLimit` hook and the `rate:limited` event.