fastapi-loopguard 0.5.0__tar.gz → 0.6.0__tar.gz

{fastapi_loopguard-0.5.0 → fastapi_loopguard-0.6.0}/.github/workflows/ci.yml

@@ -41,7 +41,7 @@ jobs:
           coverage xml
 
       - name: Upload coverage to Codecov
-        uses: codecov/codecov-action@v5
+        uses: codecov/codecov-action@v7
         if: matrix.python-version == '3.12'
         with:
           files: ./coverage.xml

fastapi_loopguard-0.6.0/CHANGELOG.md

@@ -0,0 +1,104 @@
+# Changelog
+
+## 0.6.0 (2026-08-12)
+
+Detection-core hardening plus the AI test harness. Fixes found by a
+line-by-line audit of the detection path; every item below changes
+observable behavior.
+
+- The adaptive threshold can no longer ratchet itself blind. Recalculation
+  is clamped to the `fallback_threshold_ms` ceiling; previously each raise
+  widened the censor gate that admits the next round of samples, compounding
+  50 -> 241 -> 573ms within seconds on merely-noisy traffic.
+- Cumulative detection no longer counts timer jitter. The window now sums
+  baseline-corrected excess lag (`max(0, lag - baseline)`); raw per-tick
+  platform jitter (~2ms idle on macOS) alone could previously cross the
+  200ms default within one 1000ms window on a completely idle loop.
+- Lazy stop/start race fixed: a request arriving while the monitor was
+  stopping (last request just finished) used to observe stale lifecycle
+  flags and run unmonitored. Flags are now cleared before the stop awaits,
+  so a mid-stop request starts a fresh monitor.
+- `stop()` no longer swallows a cancellation aimed at the calling task.
+  It runs inside request `finally` blocks; the old
+  `suppress(CancelledError)` turned client disconnects and server shutdown
+  into requests that ignored their own cancellation.
+- `stop()` issued during a blocking `start()` calibration now vetoes the
+  loop start instead of being a silent no-op.
+- A lifespan app that raises no longer leaks the monitor tasks.
+- One blocking event now logs exactly one summary line instead of one line
+  per in-flight request (O(N) log formatting on the loop thread right after
+  a stall). The per-context `on_blocking` callback contract is unchanged.
+- New config validation: `fallback_threshold_ms >= monitor_interval_ms`,
+  `adaptive_update_interval_ms >= monitor_interval_ms`, and `exclude_paths`
+  may not be a bare string (it would silently become a substring match).
+- Strict mode's clean-path headers are now computed from the request
+  context instead of hardcoded zero literals.
+- Calibration clamps a negative raw baseline (timers may fire up to
+  clock_resolution early) to 0.
+
+AI test harness (pytest plugin):
+
+- New `loopguard_all_async` mode (ini or `--loopguard-all-async`): every
+  async test is treated as `@pytest.mark.no_blocking`, with a new
+  `@pytest.mark.allow_blocking` opt-out marker. Built for gating
+  AI-generated code without per-test annotations.
+- New `loopguard_report` option (ini or `--loopguard-report=PATH`): writes
+  a JSON verdict file at session end with per-test blocking events and
+  concrete sync->async fix hints. See `docs/AI-HARNESS.md`.
+- The detector is now armed before the test body runs. A test that blocked
+  before its first real await (an ASGI request dispatch does exactly that)
+  was previously invisible to the gate.
+- BREAKING: the `loopguard_detector` fixture was removed. It yielded a
+  detector that was never started, so assertions on its (always empty)
+  `blocking_events` passed unconditionally.
+- `@pytest.mark.no_blocking` on a synchronous test now emits a warning
+  instead of silently doing nothing.
+- The plugin no longer calls `asyncio.iscoroutinefunction` (deprecated on
+  Python 3.14), so downstream suites running `-W error` stay green.
+- `BlockingDetector.stop()` no longer swallows the test's own cancellation.
+
+Also:
+
+- New `evals/` directory: a starter benchmark (5 FastAPI tasks + runner)
+  scoring whether an AI model writes non-blocking async code.
+- `configure_logging()` is idempotent and disables propagation;
+  `StructuredFormatter` preserves `exc_info` tracebacks.
+- `prometheus-client` joined the `dev` extra so the metrics tests run in CI.
+
+## 0.5.0 (2026-08-11)
+
+Correctness release. Every fix below changes externally observable behavior.
+
+- `dev_mode` no longer turns blocking into 503s. Previously, one endpoint's
+  sync block made every concurrent innocent request fail with 503 while the
+  actual culprit returned 200. `dev_mode` now only adds diagnostic headers;
+  a 503 requires explicitly setting `enforcement_mode="strict"`. Docs no
+  longer claim the library identifies which endpoint caused blocking — it
+  reports the requests that were in flight during the stall.
+- A single blocking event is reported once, not twice. A 300ms block used to
+  produce two events summing to ~600ms in headers and logs (single-shot plus
+  a cumulative re-count of the same sample). Cumulative window sums are now
+  recorded separately from individual lag samples.
+- Calibration can no longer be poisoned by the app's own blocking. Background
+  calibration during a busy blocking startup used to raise the detection
+  threshold to ~8x the fallback, after which real blocking went undetected.
+  A calibrated threshold now only ever tightens the fallback.
+- The adaptive threshold no longer chases sustained blocking. ~120 blocks of
+  ~70ms used to yield ~9 detections and a final threshold near 380ms;
+  detection now keeps firing for the whole run.
+- Adaptive mode no longer discards a calibration-tightened threshold. Its
+  floor used to be pinned at the fallback and its first update fired
+  immediately, snapping a calibrated 10ms threshold back to 50ms on the
+  first tick. The floor now follows the calibrated threshold.
+- Responses using ASGI extension messages no longer hang in strict mode:
+  `http.response.pathsend` (Starlette `FileResponse` on Hypercorn/Granian),
+  `http.response.trailers`, and unknown message types now pass through.
+- `"trailers": True` and any other key on `http.response.start` survive
+  header injection instead of being silently dropped.
+- The monitor no longer leaks background tasks when startup fails
+  (`lifespan.startup.failed` / `lifespan.shutdown.failed` now stop it), and a
+  lazily started monitor (apps without lifespan, e.g. tests using
+  `httpx.ASGITransport`) stops when the last in-flight request finishes.
+- `__version__` now matches the installed package metadata (it was hard-coded
+  to 0.3.0 while the package shipped as 0.4.1), and the 503 error page links
+  to the real repository.

{fastapi_loopguard-0.5.0 → fastapi_loopguard-0.6.0}/CLAUDE.md

@@ -22,7 +22,7 @@ ruff format --check src/ tests/          # CI verifies formatting; drop --check
 coverage run -m pytest tests/ && coverage report --fail-under=80   # the CI gate
 
 pip install -e ".[stress]"               # everything under examples/ needs uvicorn + locust
-python examples/demo_app.py              # demo on :8765 — /api/users returns 503 (dev_mode)
+python examples/demo_app.py              # demo on :8765 — /api/users returns 503 (strict mode)
 python examples/stress_app.py            # stress target on :8000
 python examples/run_stress_test.py --skip-locust   # validation suite against a running :8000
 ```
@@ -62,11 +62,11 @@ src/fastapi_loopguard/
 1. **Pure ASGI — never `BaseHTTPMiddleware`.** It is deprecated, breaks contextvars, and leaks memory. `__call__` dispatches on `scope["type"]`; WebSocket and every other type pass through untouched, with no context registered.
 2. **Blocking attributes to ALL active requests.** The sentinel measures loop lag, not call stacks, so it cannot know which request blocked. `_handle_blocking` iterates every context from `get_active_requests()` and records the same lag on each. This over-reports under concurrency **by design** — narrowing it is a redesign, not a bug fix.
 3. **The registry needs no locks.** asyncio is single-threaded, so `RequestRegistry` is a plain dict keyed by `request_id`. Never add a lock, a `threading` primitive, or thread-safety without first changing that premise and saying so.
-4. **Calibration never blocks the first request, and can only tighten.** `start_with_background_calibration()` starts `_monitor_loop` immediately on `fallback_threshold_ms` and calibrates in a named background task. Baseline is the **minimum** of `calibration_iterations` samples (the idle floor — robust to contamination from live traffic), and the calibrated threshold is clamped to `[monitor_interval_ms, fallback_threshold_ms]`: it may lower the fallback, never raise it. The adaptive window is censored (only sub-threshold samples admitted) and its floor follows the calibrated threshold, so neither calibration nor adaptation can be poisoned upward by the app's own blocking. A failed or cancelled calibration keeps the fallback threshold and must never raise into startup.
+4. **Calibration never blocks the first request, and can only tighten.** `start_with_background_calibration()` starts `_monitor_loop` immediately on `fallback_threshold_ms` and calibrates in a named background task. Baseline is the **minimum** of `calibration_iterations` samples (the idle floor — robust to contamination from live traffic), and the calibrated threshold is clamped to `[monitor_interval_ms, fallback_threshold_ms]`: it may lower the fallback, never raise it. The adaptive window is censored (only sub-threshold samples admitted), its floor follows the calibrated threshold, and its recalculated value is clamped to the `fallback_threshold_ms` ceiling — without the ceiling each raise widens the censor gate and the threshold ratchets upward unboundedly. So neither calibration nor adaptation can be poisoned upward by the app's own blocking or its noise. A failed or cancelled calibration keeps the fallback threshold and must never raise into startup. Config guarantees `fallback_threshold_ms >= monitor_interval_ms`, so the clamp can never invert.
 5. **Unregister always runs.** `_handle_http` wraps dispatch in `try/finally: unregister_request(request_id)`. An exception from the wrapped app must never leak a context into the registry — a leak makes every later blocking event attribute to a dead request forever.
 6. **`dev_mode` is headers-only; a 503 requires explicit strict mode.** `_get_effective_enforcement_mode()` always returns `enforcement_mode` — `dev_mode` never changes it. Because blocking is attributed to ALL in-flight requests (invariant 2), a status change punishes innocent bystanders, so it must stay opt-in via `enforcement_mode="strict"`. No text anywhere may claim the library identifies WHICH endpoint blocked — it narrows it to the requests in flight during the stall.
-7. **One blocking event is reported exactly once.** A sample that fires the single-shot detection is never appended to `_lag_history`, within one `_monitor_loop` iteration a single-lag trigger suppresses the cumulative one, and `_lag_history` is cleared after a cumulative fire so a window reports at most once. Cumulative window sums are recorded in `RequestContext.cumulative_events`, separate from the individual-lag `blocking_events` list; `blocking_count` / `total_blocking_ms` sum both.
-8. **Lifecycle calls are idempotent, and lazy monitors stop when idle.** `start()`, `start_with_background_calibration()`, and `stop()` all return early when already in the target state. `_handle_http` lazily starts the monitor for apps that run without ASGI lifespan and stops it when the last in-flight request unregisters (so `httpx.ASGITransport` tests leak no tasks); lifespan-managed monitors persist between requests. Double-start must stay a no-op. Consequence: in lazy mode background calibration rarely completes and the fallback threshold governs.
+7. **One blocking event is reported exactly once.** A sample that fires the single-shot detection is never appended to `_lag_history`, within one `_monitor_loop` iteration a single-lag trigger suppresses the cumulative one, and `_lag_history` is cleared after a cumulative fire so a window reports at most once. The window stores **baseline-corrected excess lag** (`max(0, lag - baseline)`), never raw lag — raw per-tick timer jitter alone would sum past the default cumulative threshold on an idle loop. Cumulative window sums are recorded in `RequestContext.cumulative_events`, separate from the individual-lag `blocking_events` list; `blocking_count` / `total_blocking_ms` sum both. One event also emits exactly **one log line** (a summary across in-flight requests), never one line per context — no O(N) work on the loop thread right after a stall.
+8. **Lifecycle calls are idempotent, race-free, and cancellation-safe; lazy monitors stop when idle.** `start()`, `start_with_background_calibration()`, and `stop()` all return early when already in the target state. `start()` marks `_running` **before** its blocking calibration so a concurrent `stop()` vetoes the loop start. `_stop_monitor` clears `_started`/`_lazy_started`/`_monitor` **before** awaiting the monitor's stop — that await yields, and a request arriving mid-stop must see `_started=False` and start a fresh monitor rather than run unmonitored. `stop()` awaits cancelled tasks via `_cancel_and_wait`, which re-raises when the *calling* task has a pending cancellation (it runs inside request `finally` blocks; a bare `suppress(CancelledError)` would make requests ignore their own cancellation). A lifespan app that raises gets the monitor stopped in the `except` path, not leaked. `_handle_http` lazily starts the monitor for apps that run without ASGI lifespan and stops it when the last in-flight request unregisters (so `httpx.ASGITransport` tests leak no tasks); lifespan-managed monitors persist between requests. Double-start must stay a no-op. Consequence: in lazy mode background calibration rarely completes and the fallback threshold governs.
 
 ## Conventions
 

{fastapi_loopguard-0.5.0 → fastapi_loopguard-0.6.0}/FINDINGS.md

@@ -1,21 +1,24 @@
-# Findings not fixed in the 0.5 pass
+# Findings not fixed in the 0.5/0.6 passes
 
-Everything noticed while fixing the 0.5 correctness defects but deliberately
-left alone. Each item is its own future task.
+Everything noticed while fixing the 0.5 correctness defects (and the 0.6
+hardening pass) but deliberately left alone. Each item is its own future task.
 
 ## Detection design
 
-1. **Sub-threshold noise can still inflate the adaptive threshold.**
-   The 0.5 fix censors detected-blocking samples out of the window, but
-   samples just below the threshold are admitted by design, and
-   `P95 x threshold_multiplier` of ~40ms noise still produces a ~230ms
-   threshold that would mask a later 100ms block. Per the forensics guidance,
-   median+MAD over the censored window would be more robust than a percentile.
+1. ~~**Sub-threshold noise can still inflate the adaptive threshold.**~~
+   **Fixed in the 0.6 pass:** the adaptive threshold is now clamped to the
+   `fallback_threshold_ms` ceiling, closing both the one-step inflation and
+   the compounding ratchet (each raise widened the censor gate). Median+MAD
+   over the censored window remains a possible refinement below the ceiling.
 
 2. **Strict mode cannot fail a response after `http.response.start` has passed.**
    If blocking is first detected mid-stream, the 200 and its headers are
    already on the wire and the body keeps streaming; the response then claims
-   no blocking. Inherent to header-based reporting; worth documenting.
+   no blocking. Inherent to header-based reporting. Documented by test
+   (`test_enforcement_mode.py::TestStrictModeStreaming`). Related accepted
+   behavior, also documented by test: if the app raises after strict mode
+   swallowed its `http.response.start`, the exception wins — the client gets
+   the server's 500, not LoopGuard's 503.
 
 3. **Explicit strict mode still 503s all in-flight requests.**
    The sentinel cannot name the culprit, so strict mode punishes bystanders
@@ -59,11 +62,12 @@ left alone. Each item is its own future task.
 11. **`docs/CONFIGURATION.md` names metrics that do not exist** (known gap #2)
     and `get_metrics()` can never find an instance (known gap #3).
 
-12. **`docs/CONFIGURATION.md` describes `fallback_threshold_ms` as "Used if
-    calibration is unreliable"**; since 0.5 it is also the hard ceiling for
-    the calibrated threshold.
+12. ~~**`docs/CONFIGURATION.md` describes `fallback_threshold_ms` as "Used if
+    calibration is unreliable"**~~ — fixed in the 0.6 pass; the docs now
+    describe it as the hard ceiling.
 
-13. **`_handle_lifespan` locals `started` / `shutdown_complete` are write-only.**
+13. ~~**`_handle_lifespan` locals `started` / `shutdown_complete` are
+    write-only.**~~ — removed in the 0.6 pass.
 
 14. **The `structlog` extra is declared but nothing imports structlog**
     (already noted in CLAUDE.md).
@@ -75,6 +79,23 @@ left alone. Each item is its own future task.
     old `max(..., fallback)` floor masked the bug. The fix removes the
     mechanism either way, but tests that "prove" poisoning need dense blocking.
 
+## Accepted in the 0.6 hardening pass (documented, not fixed)
+
+16. **Installing the middleware twice injects duplicate `x-*` headers.**
+    Nothing marks a scope as already instrumented; two instances register two
+    contexts per request and both send wrappers extend the headers. Low
+    priority — a doubled middleware is a user configuration error.
+
+17. **`Accept` negotiation is a bare substring test with last-header-wins.**
+    Duplicate `Accept` headers collapse via `dict()`, and q-values are
+    ignored, so `text/html;q=0.1, application/json;q=0.9` still gets the HTML
+    page. Cosmetic: only chooses the error-page format.
+
+18. **8-hex-char request ids (32 bits) can collide silently.** A collision
+    overwrites the registry entry and the first unregister removes the second
+    request's context. Birthday bound is ~77k concurrent in-flight requests;
+    accepted as unrealistic, noted here so it is a known trade.
+
 ## Fixed since the first draft
 
 - Adaptive mode discarding the calibrated threshold (floor pinned at the

{fastapi_loopguard-0.5.0 → fastapi_loopguard-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: fastapi-loopguard
-Version: 0.5.0
+Version: 0.6.0
 Summary: Detect event-loop blocking in FastAPI/Starlette with per-request attribution
 Project-URL: Homepage, https://github.com/parhamdavari/fastapi-loopguard
 Project-URL: Documentation, https://github.com/parhamdavari/fastapi-loopguard#readme
@@ -22,7 +22,7 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Topic :: System :: Monitoring
 Classifier: Typing :: Typed
 Requires-Python: >=3.12
-Requires-Dist: starlette<1.0,>=0.37.0
+Requires-Dist: starlette<2.0,>=0.37.0
 Provides-Extra: all
 Requires-Dist: prometheus-client>=0.19.0; extra == 'all'
 Requires-Dist: structlog>=24.1.0; extra == 'all'
@@ -31,6 +31,7 @@ Requires-Dist: coverage>=7.4.0; extra == 'dev'
 Requires-Dist: fastapi>=0.110.0; extra == 'dev'
 Requires-Dist: httpx>=0.27.0; extra == 'dev'
 Requires-Dist: mypy>=1.8.0; extra == 'dev'
+Requires-Dist: prometheus-client>=0.19.0; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
 Requires-Dist: pytest>=8.0.0; extra == 'dev'
 Requires-Dist: ruff>=0.3.0; extra == 'dev'
@@ -57,6 +58,10 @@ Description-Content-Type: text/markdown
   <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
 </p>
 
+<p align="center">
+  <img src="assets/demo.gif" alt="LoopGuard demo: a fast endpoint passes, a blocking endpoint fails with a 503, and the console banner explains why" width="800" />
+</p>
+
 ---
 
 When something blocks your event loop (via `time.sleep()`, blocking I/O, or CPU work), LoopGuard detects it **and narrows it down to the requests that were in flight when the loop stalled**. The sentinel measures loop lag, so it cannot name the single guilty handler — it reports every request that was active during the stall.
@@ -106,7 +111,7 @@ app.add_middleware(LoopGuardMiddleware, config=config)
 Returns an educational 503 page that explains what went wrong and how to fix it:
 
 <p align="center">
-  <img src="assets/error-page-screenshot.png" alt="Strict mode error page" width="600" />
+  <img src="assets/error-page.gif" alt="Strict mode error page" width="600" />
 </p>
 
 ---
@@ -129,6 +134,21 @@ Writes structured logs listing the requests that were in flight:
 
 ---
 
+## Testing AI-Generated Code
+
+AI agents write plausible async code that quietly blocks the event loop. The bundled pytest plugin turns that into a red test and a machine-readable report the agent can fix from — no per-test annotations:
+
+```ini
+# pytest.ini
+[pytest]
+loopguard_all_async = true          # every async test fails on blocking
+loopguard_report = loopguard.json   # verdicts + fix hints for the agent
+```
+
+See [docs/AI-HARNESS.md](docs/AI-HARNESS.md) for the report schema, the `no_blocking` / `allow_blocking` markers, and a drop-in snippet for your project's agent instructions.
+
+---
+
 <p align="center">
   <a href="docs/CONFIGURATION.md"><strong>Full Configuration Reference</strong></a>
 </p>

{fastapi_loopguard-0.5.0 → fastapi_loopguard-0.6.0}/README.md

@@ -12,6 +12,10 @@
   <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
 </p>
 
+<p align="center">
+  <img src="assets/demo.gif" alt="LoopGuard demo: a fast endpoint passes, a blocking endpoint fails with a 503, and the console banner explains why" width="800" />
+</p>
+
 ---
 
 When something blocks your event loop (via `time.sleep()`, blocking I/O, or CPU work), LoopGuard detects it **and narrows it down to the requests that were in flight when the loop stalled**. The sentinel measures loop lag, so it cannot name the single guilty handler — it reports every request that was active during the stall.
@@ -61,7 +65,7 @@ app.add_middleware(LoopGuardMiddleware, config=config)
 Returns an educational 503 page that explains what went wrong and how to fix it:
 
 <p align="center">
-  <img src="assets/error-page-screenshot.png" alt="Strict mode error page" width="600" />
+  <img src="assets/error-page.gif" alt="Strict mode error page" width="600" />
 </p>
 
 ---
@@ -84,6 +88,21 @@ Writes structured logs listing the requests that were in flight:
 
 ---
 
+## Testing AI-Generated Code
+
+AI agents write plausible async code that quietly blocks the event loop. The bundled pytest plugin turns that into a red test and a machine-readable report the agent can fix from — no per-test annotations:
+
+```ini
+# pytest.ini
+[pytest]
+loopguard_all_async = true          # every async test fails on blocking
+loopguard_report = loopguard.json   # verdicts + fix hints for the agent
+```
+
+See [docs/AI-HARNESS.md](docs/AI-HARNESS.md) for the report schema, the `no_blocking` / `allow_blocking` markers, and a drop-in snippet for your project's agent instructions.
+
+---
+
 <p align="center">
   <a href="docs/CONFIGURATION.md"><strong>Full Configuration Reference</strong></a>
 </p>

fastapi_loopguard-0.6.0/assets/demo.tape

@@ -0,0 +1,59 @@
+# VHS tape for assets/demo.gif — reproduce with:
+#   brew install vhs
+#   pip install -e ".[stress]"   (needs uvicorn; run from the repo root)
+#   vhs assets/demo.tape
+#
+# Story: pain -> catch -> install.
+#   1. baseline: the async app answers in ~0.1s
+#   2. one request runs blocking code -> EVERY request freezes with it
+#      (the hang is real: /api/items stalls ~2s on screen, then the
+#      blocking request comes back 503)
+#   3. the LoopGuard console banner explains the fix + install CTA
+
+Output assets/demo.gif
+
+Set Shell bash
+Set FontSize 14
+Set Width 800
+Set Height 540
+Set Padding 12
+Set TypingSpeed 20ms
+Set Theme "Catppuccin Mocha"
+Set WindowBar Colorful
+Set BorderRadius 8
+
+Hide
+Type "source .venv/bin/activate && python examples/demo_app.py >/tmp/loopguard-demo.log 2>&1 & sleep 2; TIMEFORMAT='  took %Rs'; clear"
+Enter
+Sleep 2.5s
+Show
+
+Type "# a healthy async app"
+Enter
+Type "time curl -s localhost:8765/api/items"
+Enter
+Sleep 2s
+
+Ctrl+L
+Type "# one request runs blocking code - every request freezes with it"
+Enter
+Type "(curl -so /dev/null -w 'culprit -> %{http_code}\n' localhost:8765/api/users &)"
+Enter
+Type "time curl -s localhost:8765/api/items"
+Enter
+Sleep 4.5s
+
+Ctrl+L
+Type "# the server console explains what happened"
+Enter
+Type "grep -B 2 -A 18 'LOOPGUARD' /tmp/loopguard-demo.log"
+Enter
+Sleep 2.5s
+Type "# pip install fastapi-loopguard  ->  app.add_middleware(LoopGuardMiddleware)"
+Enter
+Sleep 2.5s
+
+Hide
+Type "kill %1"
+Enter
+Sleep 500ms

fastapi_loopguard-0.6.0/docs/AI-HARNESS.md

@@ -0,0 +1,111 @@
+# LoopGuard as a Test Harness for AI-Generated Code
+
+AI coding agents write plausible async code that quietly blocks the event
+loop — `requests` instead of `httpx`, `open().read()` in a handler, a sync
+SDK call inside `async def`. The type checker passes, the tests pass, and
+the app freezes under load.
+
+LoopGuard's pytest plugin turns that failure mode into a red test with a
+machine-readable explanation the agent can fix from — no per-test
+annotations required.
+
+## Quick start
+
+```ini
+# pytest.ini (or [tool.pytest.ini_options] in pyproject.toml)
+[pytest]
+asyncio_mode = auto
+loopguard_all_async = true          # every async test is a blocking gate
+loopguard_report = loopguard.json   # verdicts for the agent to read
+loopguard_threshold_ms = 50
+```
+
+Run the suite as usual:
+
+```bash
+pytest
+```
+
+Any async test whose execution blocks the event loop past the threshold
+fails, and `loopguard.json` records what happened. Both settings also
+exist as CLI flags: `--loopguard-all-async`, `--loopguard-report=PATH`.
+
+## Options
+
+| Option | Where | Default | Meaning |
+|--------|-------|---------|---------|
+| `loopguard_threshold_ms` | ini | `50` | Lag beyond this fails the test |
+| `loopguard_all_async` | ini / `--loopguard-all-async` | off | Treat every async test as `@pytest.mark.no_blocking` |
+| `loopguard_report` | ini / `--loopguard-report=PATH` | off | Write the JSON verdict file |
+| `@pytest.mark.no_blocking` | marker | — | Gate one test explicitly (works without all-async mode) |
+| `@pytest.mark.allow_blocking` | marker | — | Exempt one test from all-async mode |
+
+Exit semantics are plain pytest: flagged tests fail, so any CI that runs
+pytest is already enforcing the gate.
+
+## The report
+
+```json
+{
+  "schema_version": 1,
+  "threshold_ms": 50.0,
+  "totals": {"tests": 42, "flagged": 1},
+  "tests": [
+    {
+      "nodeid": "tests/test_api.py::test_upload",
+      "verdict": "blocked",
+      "events": [{"lag_ms": 180.24, "threshold_ms": 50.0}],
+      "hints": [
+        "time.sleep(n) -> await asyncio.sleep(n)",
+        "requests.get(url) -> await httpx.AsyncClient().get(url)",
+        "open(f).read() -> await aiofiles.open(f)",
+        "subprocess.run(...) -> await asyncio.create_subprocess_exec(...)",
+        "CPU-bound work -> await asyncio.to_thread(func)"
+      ]
+    },
+    {
+      "nodeid": "tests/test_api.py::test_list",
+      "verdict": "clean",
+      "events": [],
+      "hints": []
+    }
+  ]
+}
+```
+
+Only instrumented tests appear (`totals.tests` counts them). A `blocked`
+verdict means the loop lagged past the threshold while that test ran; the
+sentinel measures lag, not call stacks, so the culprit is in the code that
+test executed — usually the endpoint it called.
+
+## Interpreting the strict 503 (runtime harness)
+
+For integration tests that drive a live app, run the middleware with
+`LoopGuardConfig(enforcement_mode="strict")`: blocking requests fail with
+a 503 whose JSON body carries the same shape of diagnosis
+(`error: "event_loop_blocked"`, blocking count and total ms, and the same
+fix suggestions under `help.common_causes`).
+
+## Drop-in snippet for a consumer project's CLAUDE.md / agents.md
+
+```markdown
+## Async discipline (enforced)
+
+This project gates async code with fastapi-loopguard. `pytest` fails any
+async test that blocks the event loop for >50ms and writes verdicts to
+`loopguard.json`.
+
+When a test fails with "Event loop blocking detected":
+1. Read `loopguard.json`; find the `blocked` entry for that test.
+2. The blocking call is in the code path that test exercises. Replace
+   sync calls with the async equivalents listed under `hints`.
+3. Never widen `loopguard_threshold_ms` or add `allow_blocking` to make
+   a test pass — fix the blocking call instead.
+```
+
+## Scoring models instead of guarding CI
+
+The same gate scores whether a model writes non-blocking async code: run
+each generated solution against a functional test file plus the plugin,
+and read `totals.flagged` from the report. A ready-made task set lives in
+`evals/` at the repository root.

{fastapi_loopguard-0.5.0 → fastapi_loopguard-0.6.0}/docs/CONFIGURATION.md

@@ -52,7 +52,9 @@ config = LoopGuardConfig(
 | `monitor_interval_ms` | float | `10.0` | Sentinel check frequency (ms) |
 | `threshold_multiplier` | float | `5.0` | Blocking detected when lag > baseline × this |
 | `calibration_iterations` | int | `100` | Samples during startup calibration |
-| `fallback_threshold_ms` | float | `50.0` | Used if calibration is unreliable |
+| `fallback_threshold_ms` | float | `50.0` | Threshold before/without calibration, and the hard ceiling a calibrated or adaptive threshold can never exceed. Must be ≥ `monitor_interval_ms` (lag below the sampling interval cannot be resolved). |
+
+**Validation:** `exclude_paths` must be a collection of paths — a bare string is rejected (it would silently become a substring match).
 
 ---
 
@@ -68,6 +70,8 @@ Catches "death by a thousand cuts" - many small blocks that add up.
 
 **Example:** With defaults, alerts if blocking totals >200ms within any 1-second window.
 
+Only lag **in excess of the calibrated baseline** counts toward the window sum, so platform timer jitter on an idle loop cannot accumulate into a false positive.
+
 ---
 
 ## Adaptive Threshold
@@ -80,7 +84,9 @@ Dynamically adjusts threshold based on observed latency. Useful for high-concurr
 | `adaptive_window_size` | int | `1000` | Samples in sliding window |
 | `adaptive_percentile` | float | `0.95` | Percentile for baseline (0.5-0.99) |
 | `adaptive_min_samples` | int | `100` | Min samples before activation |
-| `adaptive_update_interval_ms` | float | `1000.0` | Recalculation frequency (ms) |
+| `adaptive_update_interval_ms` | float | `1000.0` | Recalculation frequency (ms). Must be ≥ `monitor_interval_ms`. |
+
+The adaptive threshold is clamped to `[calibrated threshold, fallback_threshold_ms]`: adaptation may tighten detection but can never raise the threshold above the fallback, so a noisy loop cannot ratchet the detector blind.
 
 ---
 

fastapi_loopguard-0.6.0/evals/README.md

@@ -0,0 +1,64 @@
+# LoopGuard Evals
+
+A small benchmark that scores whether an AI model writes **non-blocking**
+async FastAPI code. Each task ships a prompt, a provided `helpers.py`, and
+functional checks; LoopGuard's pytest plugin is the judge.
+
+The trap is always the same shape: `helpers.py` offers a slow synchronous
+function (and sometimes an async variant). A correct solution keeps the
+event loop free — by using the async variant or wrapping the sync one in
+`asyncio.to_thread` — while a naive solution calls the sync helper directly
+and blocks the loop for 100–200 ms, which the plugin flags deterministically
+against the 50 ms threshold.
+
+## Layout
+
+```
+evals/
+  runner.py                     score one solution against one task
+  tasks/<name>/
+    task.md                     the prompt to give the model
+    app_skeleton.py             starting file the model completes
+    helpers.py                  provided API (contains the trap)
+    checks.py                   functional pytest checks
+    reference/clean.py          known-good solution (ground truth)
+    reference/blocking.py       known-blocking solution (ground truth)
+```
+
+`reference/` is ground truth for validating the harness — exclude it from
+any context you give the model under test.
+
+## Running
+
+```bash
+pip install -e ".[dev]"      # from the repository root
+
+python evals/runner.py \
+  --task evals/tasks/01-user-lookup \
+  --solution path/to/model_output.py
+```
+
+Output (also written with `--out scores.json`):
+
+```json
+{
+  "task": "01-user-lookup",
+  "functional": true,
+  "non_blocking": false,
+  "score": 0,
+  "flagged": ["test_checks.py::test_returns_user"],
+  "detail": "1 test(s) blocked the event loop"
+}
+```
+
+`score` is 1 only when every check passes **and** nothing blocked the loop.
+To benchmark a model, generate one solution per task from `task.md` (plus
+`app_skeleton.py` and `helpers.py` as context) and sum the scores.
+
+## Scoring semantics
+
+| exit | blocked verdicts | functional | non_blocking | score |
+|------|------------------|------------|--------------|-------|
+| 0    | none             | true       | true         | 1     |
+| ≠0   | ≥1               | unknown    | false        | 0     |
+| ≠0   | none             | false      | true         | 0     |