docs: LRU eviction resets budgets; createSlowQueryDetector mutates sinks (#25)

- README + budget.md: eviction clears per-requestId counters; same id can
  violate again after re-insertion
- README: document sinks array mutation when LoggerSink is appended
- GitHub Pages: short footnote mirroring the above

Fixes #17
Fixes #18

Author: oleg-koval

README.md

@@ -186,6 +186,8 @@ Why not benchmark only against DB in Docker?
 - **`wrapTaggedTemplate`** — tagged template `(strings, ...values) => Promise<unknown>` (e.g. **postgres.js** `sql`, same literal shape as Prisma `$queryRaw`).
 - **`extractQueryInfo`** — build `$1…$n` SQL + params from a `TemplateStringsArray` if you wire a custom executor.
 
+**`createSlowQueryDetector`** appends a default **`LoggerSink`** with **`Array#push`** when your `sinks` array does not already include one, so the array you pass is **mutated**. Pass an array you own, or copy first (`sinks: [...existing]`), if immutability matters.
+
 ### postgres.js (tagged template + request scope)
 
 Use **`runWithDbContext`** so each HTTP request (or job) gets a stable **`requestId`**; **`createSlowQueryDetector`** defaults `contextProvider` to **`getDbContext()`**, so you usually do **not** pass `contextProvider` unless you merge ALS with your own source.
@@ -249,6 +251,7 @@ Set `requestBudget.maxQueries` and/or `requestBudget.maxTotalDurationMs` to catc
 
 - **Successful and failed** `executeQuery` completions both increment the budget (every round-trip attempt counts).
 - The first time a limit is exceeded for a `requestId`, sinks receive one **`db.request.budget`** event (`LoggerSink` → **warn**). A second violation for the same id is only possible after that id falls out of the LRU (e.g. many concurrent requests with unique ids).
+- **LRU eviction resets counters:** when a `requestId` is evicted, its budget state is dropped. If that same id string appears again later, totals start from zero and another **`db.request.budget`** can fire for a new burst.
 - **`requestBudget.maxTrackedRequests`** bounds memory (default **5000**); non-finite or `< 1` values are normalized.
 
 **Custom sinks:** `IEventSink.handle` receives **`DetectorEvent`** (`QueryEvent | RequestBudgetViolationEvent`). Branch on `event.event === "db.request.budget"` before assuming `sql` / `subtype` exist.

docs/budget.md

@@ -22,7 +22,7 @@ Behavior (see [README § Request budgets](../README.md#request-budgets-per-reque
 
 1. Budgets apply only when **`requestId`** is set on context (e.g. via `runWithDbContext`). With **`createSlowQueryDetector`**, the default `contextProvider` reads that context; custom detectors must supply one (see [README](../README.md#request-budgets-per-requestid)).
 2. Each query completion increments **count** and adds **duration** to that `requestId`.
-3. The **first** time either limit is exceeded, sinks receive **one** `RequestBudgetViolationEvent` (`event: "db.request.budget"`). Further violations for the same id only happen after that id is evicted from the LRU map.
+3. The **first** time either limit is exceeded, sinks receive **one** `RequestBudgetViolationEvent` (`event: "db.request.budget"`). Further violations for the same id only happen after that id is evicted from the LRU map. **Eviction removes the entry:** the same `requestId` string seen again later gets **fresh counters**, so another `db.request.budget` is possible after a subsequent burst.
 4. **`LoggerSink`** logs budget events at **warn** level (see `LoggerSink` in source).
 
 This design targets **query storms**: many fast queries that never cross a single-query `warnThresholdMs`, but still hurt latency, CPU, and pool usage.

docs/index.html

@@ -646,6 +646,10 @@ <h3>Explain the worst</h3>
         </div>
       </section>
 
+      <p class="footnote wrap">
+        Request budgets: LRU eviction resets per-<code>requestId</code> counters (same id string can violate again after re-insertion).
+        <code>createSlowQueryDetector</code> may <code>push</code> onto your <code>sinks</code> array — see README.
+      </p>
       <p class="footnote wrap">
         MIT licensed ·
         <a href="https://github.com/oleg-koval/slow-query-detector">oleg-koval/slow-query-detector</a>