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

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

@@ -11,13 +11,13 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.12", "3.13"]
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
 
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
 
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v6
+        uses: actions/setup-python@v7
         with:
           python-version: ${{ matrix.python-version }}
 

{fastapi_loopguard-0.6.0 → fastapi_loopguard-0.7.0}/.github/workflows/publish.yml

@@ -13,10 +13,10 @@ jobs:
       id-token: write  # Required for trusted publishing
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
 
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v7
         with:
           python-version: "3.12"
 

fastapi_loopguard-0.7.0/CHANGELOG.md

@@ -0,0 +1,375 @@
+# Changelog
+
+## 0.7.0 (2026-09-11)
+
+Two security fixes, a detection miss that made the most common shape of
+blocking code invisible, and a `loopguard` console script for enforcing the
+gate outside pytest.
+
+### Security
+
+- **Reflected XSS in the strict-mode 503 page.** `_generate_error_html`
+  interpolated the request method and path into HTML with no escaping, and
+  ASGI servers percent-decode the path — so a request for
+  `/%3Cscript%3E...%3C/script%3E` with `Accept: text/html` executed attacker
+  JavaScript on the application's own origin. Because blocking attributes to
+  every request in flight, the attacker only had to have a request in flight
+  while any other request stalled the loop. Both values are now escaped, and
+  the never-called `_generate_warning_banner()` — which had the same hole —
+  is deleted. Present since strict mode shipped; the JSON error body was
+  never affected.
+- **Unbounded Prometheus label cardinality.** With `prometheus_enabled=True`,
+  metrics were labelled by the raw request path. Every distinct URL minted a
+  child metric that is never evicted, so unauthenticated traffic to random
+  paths grew process memory without bound — and ordinary traffic to a route
+  with a path parameter did the same on its own. Requests are now labelled by
+  the matched route template, unmatched requests collapse to `unmatched`,
+  non-standard HTTP verbs to `other`, and the label set is capped at 200
+  pairs. This shipped inert (nothing imported `metrics.py`), so no released
+  version was exploitable.
+- **Log injection through the console banner.** The blocking banner printed
+  the decoded request path to stderr raw, so `%0A` forged lines in any log
+  aggregator reading it. Control characters are now escaped.
+- `docs/CONFIGURATION.md` now says plainly that strict mode must not run in
+  production, and that the diagnostic headers tell any unauthenticated client
+  that the loop stalled while their request was in flight and by how many
+  milliseconds — but never which endpoint caused it, which the sentinel cannot
+  know. What leaks is the timing signal, not an endpoint name.
+
+### Fixed
+
+- **The console banner could raise into the host application.**
+  `_log_console_warning` wrote the banner with an unguarded
+  `print(..., file=sys.stderr)`. A closed, detached, or broken stderr —
+  routine for a daemonised or supervised server — makes `print` raise
+  `ValueError` or `BrokenPipeError`, and all four call sites are on the
+  request path. At the two pre-response ones (warn mode's send wrapper,
+  strict mode's print before the 503) the exception ate the response the
+  client was about to receive, turning a detected stall into a failed
+  request. The write is now guarded in `_log_console_warning` itself, the
+  same `try/except Exception` + `logger.exception` shape `_poll_monitor`
+  and `_record_request` already use, so the operator still learns the
+  banner was lost through any working log handler. The request context was
+  never leaked — every call site sits inside `_handle_http`'s `try`.
+- **A streamed response lost the console banner.** The banner was printed
+  only from the send wrapper, at `http.response.start` — and Starlette's
+  `StreamingResponse` sends that message before its body generator runs. A
+  600 ms stall inside the generator therefore produced the log line and no
+  banner at all, so a warn-mode user who was shown the banner in the quick
+  start and watches for it saw nothing while the stall was real. `"warn"` and
+  `"strict"` now also print it after the handler returns, gated so one
+  request still prints at most one banner. Headers and the strict-mode 503
+  remain undeliverable once the `200` has shipped; `README.md` and
+  `docs/CONFIGURATION.md` say which channels survive.
+- **The fix hints recommended an undeclared package, in a form that does not
+  work.** The console banner, the strict-mode 503 body and the `hints` array
+  in `loopguard.json` all told the reader to rewrite `open(f).read()` as
+  `await aiofiles.open(f)`. `aiofiles` is third-party, is declared in no
+  extra, and that is not how it is used — while `README.md` taught
+  `await asyncio.to_thread(Path(path).read_text)` on the same page.
+  `docs/AI-HARNESS.md` tells agents to apply the `hints` literally, so the
+  harness added a dependency the README avoids. The same list also suggested
+  `await httpx.AsyncClient().get(url)`, which leaks a client per call. Every
+  hint is now defined once, in `src/fastapi_loopguard/hints.py`, rendered by
+  the banner, both 503 bodies and the plugin report, and quoted by the
+  README; each one uses only the standard library or `httpx`, and closes
+  what it opens.
+- **A blocking test failure printed the plugin before the verdict.** The
+  pytest plugin's wrapper is now hidden from the traceback, so
+  `Event loop blocking detected!` is the first line of the failure instead of
+  the last line under ~25 lines of the plugin's own source. An exception
+  raised by the test itself still reports with the test's own frame.
+- **`loopguard report` said "at at".** `json.JSONDecodeError.msg` can already
+  end in "at", and the CLI appended another. The message now reads
+  `invalid JSON (Invalid control character at line 1 column 8)` and names the
+  column.
+- **Blocking that ended without an `await` went unreported.** The sentinel
+  measures a tick by resuming from its own sleep, so a handler — or a test —
+  that blocked and then returned without awaiting left that sleep expired and
+  never measured: strict mode returned 200, warn mode reported
+  `x-blocking-detected: false`, and the pytest harness scored the test clean.
+  This is the ordinary shape of blocking code, so the miss was the common
+  case, not an edge case. `SentinelMonitor.poll()` now takes a synchronous
+  measurement on the response path, and `BlockingDetector.stop()` drains its
+  monitor instead of cancelling it — a bounded drain, and one that no longer
+  lets a monitor exception replace the test's own failure. The monitor loop
+  then reports only the residual of a polled tick, so a stall spanning a
+  response is reported in full and no millisecond is counted twice.
+- **A cancelled or recovering monitor invented blocking.** `poll()` measured
+  against the tick marker even when the monitor task had been cancelled or
+  was inside its error-recovery sleep, reporting a stall that grew with
+  wall-clock time — a 503, in strict mode, for a request that did nothing
+  wrong. Those paths now clear the marker, and `poll()` refuses to measure a
+  tick no live task owns.
+- **The middleware could fail a request it was only observing.** The response
+  path measurement and the request counter both ran unguarded, and the
+  measurement runs before `unregister_request` — so an exception leaked the
+  request context permanently, after which every later blocking event
+  attributed to a request that had long finished. Both now swallow and log.
+- **`prometheus_enabled` now exposes metrics.** Nothing on the detection path
+  imported `metrics.py`, so the flag did nothing at all. The monitor records
+  `loopguard_blocking_total`, `loopguard_lag_seconds`,
+  `loopguard_requests_monitored_total` and `loopguard_threshold_seconds`.
+  Blocking metrics carry an `event_type` label (`single` / `cumulative`) and
+  no route label: the sentinel measures loop lag, not call stacks, so it
+  cannot say which endpoint blocked, and one event is one increment rather
+  than one per in-flight request.
+- **A Prometheus registration failure took the app down.** Only the
+  missing-package case was caught, so a duplicate registration on the
+  process-wide registry failed startup, or the first request on apps without
+  lifespan. Any setup failure — a missing extra included — now logs and
+  leaves metrics off rather than failing the app.
+- **`get_metrics()` could never find an instance.** It looked up the bare
+  prefix while `create_metrics()` stored `prefix` plus registry identity. It
+  now takes the registry and derives the same key.
+- `docs/CONFIGURATION.md` listed two metric names that do not exist. It now
+  documents the four real ones, their labels, and how to serve them.
+
+### Command-line interface
+
+- **New `loopguard` console script.** `loopguard report loopguard.json`
+  reads a report the pytest plugin wrote, prints a one-line summary plus a
+  line per flagged test, and exits `0` when clean, `1` when blocking was
+  detected, `2` when the report is missing, unreadable, or malformed — the
+  ruff/pyright convention. It lets an agent or a CI step enforce the gate
+  outside pytest, without parsing JSON itself. The verdict comes from the
+  top-level `status` key, falling back to `totals.flagged > 0` for a
+  `schema_version` 1 report. `--quiet` gives the exit code alone.
+  `docs/AI-HARNESS.md` documents the exit codes and the CI invocation.
+  No new dependency: `cli.py` is standard-library-only and, deliberately,
+  never imports `pytest_plugin` — that module imports `pytest`, which a
+  production install does not have. (#49)
+- **`loopguard report` now exits `2`, not `0`, for a clean report that
+  instrumented zero tests.** A misconfigured `asyncio_mode`, a missing
+  `pytest-asyncio` install, or a rename that dropped every async test all
+  produce `{"status": "clean", "totals": {"tests": 0, ...}}` — a run that
+  tested nothing, previously read as a passing gate. The CLI now treats
+  that as a setup failure by default and prints a one-line warning to
+  stderr; pass `--allow-empty` to keep the old exit-`0` behavior for the
+  cases where zero tests is genuinely expected.
+
+### Report contract
+
+The `loopguard.json` report contract is now `schema_version` 2 and has a
+published schema:
+
+- The report carries a top-level `"status": "blocked" | "clean"`, so a
+  consuming agent reads one key instead of deriving `totals.flagged > 0`.
+  A run that instrumented no tests is `"clean"` with `totals.tests: 0`;
+  a gate that must also insist the suite was checked reads `totals.tests`
+  alongside it, which is what `loopguard report` now does by default. The
+  change is additive — `totals` is untouched. (#48)
+- `docs/loopguard-report.schema.json` (JSON Schema draft 2020-12) describes
+  the payload, with `additionalProperties: true` throughout because the
+  report grows by adding keys. CI validates the documented example and a
+  freshly generated report against it. (#50)
+
+### Packaging
+
+- The published metadata now carries a full author name and an email
+  (`Author-email: Parham Davari <parham.davarii@gmail.com>`) instead of
+  `Author: Parham` with no address, and `[project.urls]` gained a `Changelog`
+  entry pointing at `CHANGELOG.md`. Note that `pip show` now prints an empty
+  legacy `Author:` line: a PEP 621 author with both a name and an email is
+  emitted as a single `Author-email: Name <address>` field, which is where
+  both values now live. (#71)
+- `LICENSE` now reads `Copyright (c) 2025 Parham Davari`. It carried a short
+  form of the holder's name and a year predating this repository's first
+  commit; the license terms are untouched. (#71)
+- Dropped the `License :: OSI Approved :: MIT License` classifier. PEP 639
+  deprecates license classifiers once `License-Expression` is set, and
+  `license = "MIT"` already emits `License-Expression: MIT`; nothing about the
+  license itself changed. (#71)
+- The `loopguard_threshold_ms` ini option's help text now says the value is in
+  milliseconds and is parsed as a float, and that a value `float()` cannot
+  parse fails every instrumented test. The registered type stays `string` —
+  pytest ini options have no float type, so `pytest -h` will always print
+  `(string)` and the help text has to carry the rest. (#71)
+- **Removed the `structlog` extra.** `pip install fastapi-loopguard[structlog]`
+  installed `structlog` and changed nothing, because no module in `src/` imports
+  it; it was also pulled in by `[all]`. Anyone depending on that extra to
+  install structlog must now depend on `structlog` directly — `[structlog]` is
+  no longer a valid extra name and pip will warn that it does not exist. The
+  alternative, wiring `StructuredFormatter` onto structlog, would have been a
+  new feature rather than a packaging fix. (#51)
+- `enforcement_mode` is typed `Literal["log", "warn", "strict"]` and the alias
+  is exported as `fastapi_loopguard.EnforcementMode`, so a misspelled mode is a
+  type error at the call site instead of a `ValueError` at startup. The runtime
+  validation in `__post_init__` is unchanged. (#44)
+- ruff's `target-version` is no longer pinned; it is derived from
+  `project.requires-python`, so a `ruff --fix` can never rewrite code into
+  syntax newer than the package claims to support. (#45)
+
+### Changed
+
+- **The minimum Python is now 3.11**, down from 3.12. Nothing in the library
+  needed 3.12; the real floor is `asyncio.Task.cancelling()`, which landed in
+  3.11. Python 3.14 is claimed at the other end: CI runs 3.11, 3.12, 3.13 and
+  3.14, and the PyPI classifiers list all four. (#46)
+
+### Documentation
+
+- Every `README.md` link into the repository is now an absolute
+  `https://github.com/.../blob/main/...` URL. The README is the PyPI long
+  description and the wheel ships no docs, so the relative links to
+  `docs/AI-HARNESS.md`, `docs/CONFIGURATION.md`, `FINDINGS.md` and
+  `evals/README.md` resolved under pypi.org and reached nothing. Documentation
+  links track `main` so they reach the current document; the images stay
+  pinned to a tag, so a published page cannot change under a reader.
+- The README now says the detection threshold is measured at startup and
+  usually settles below `fallback_threshold_ms` (10 ms at the defaults, not
+  50) — which is why an idle app can log a sub-50 ms "no active request"
+  event. `docs/CONFIGURATION.md` carries the clamp formula, the lifespan
+  caveat, and how to pin the threshold at the fallback.
+- `docs/CONFIGURATION.md` documents `fastapi_loopguard.logging`:
+  `configure_logging`, its arguments, and the JSON `StructuredFormatter`.
+  The README's log-mode description no longer calls the default output
+  "structured" — it is one plain-text line unless you install that formatter.
+- The enforcement-modes snippet is three self-contained blocks instead of one
+  block that rebound `config` three times and applied only the last, and the
+  strict-mode section says the educational page is HTML only when `Accept`
+  contains `text/html` (JSON otherwise).
+
+### Evals
+
+The `evals/` benchmark and the claims it backs were also corrected;
+`README.md` and `docs/AI-HARNESS.md` now quote the new figures.
+
+- The scorer no longer reports an unmeasured sample as non-blocking. A
+  solution that failed to import, returned empty, or was rejected before the
+  endpoint body was recorded as `non_blocking: true` and kept in the
+  blocked-rate denominator — a bias with only one direction, pointing at the
+  headline number. Verdicts now carry `measured`, and unmeasured samples are
+  excluded from those denominators. 105 of 560 samples were affected.
+- An empty completion from a provider is retried and then raised, instead of
+  being written out as an empty `app.py` and scored as a model failure.
+- Code extraction prefers the last fenced block that parses and defines `app`,
+  and tolerates a language tag glued to the first statement. Previously a
+  response that re-listed `helpers.py` could have that listing saved as the
+  solution.
+- Task prompts are condition-symmetric: `neutral/task.md` and `hinted/task.md`
+  now differ by exactly one added sentence on all eight tasks. Three pairs
+  previously differed by more, including one with different functional specs.
+  Tasks 02, 03 and 04 were regenerated against the corrected prompts.
+- Each task's checks assert the provided helper actually ran, so a hardcoded
+  response cannot score as functional and non-blocking.
+- Request pacing and retry with backoff are in the harness rather than
+  described in prose, so the published run is reproducible from the repository.
+- `python-multipart` and `aiofiles` are declared in `evals/requirements.txt`;
+  without them the judge failed valid solutions at import.
+- New: `python evals/matrix.py --rescore` re-judges every committed solution
+  with no API calls.
+
+## 0.6.1 (2026-08-12)
+
+- The console blocking banner is restyled: a slim rule frame instead of
+  the `=`/`!` walls, with ANSI color hierarchy (headline red, explanation
+  dim, fixes cyan) on real terminals. Redirected streams and `NO_COLOR`
+  environments get identical plain text, so log grep patterns keep
+  working. (#9)
+- The 503 page's BAD/GOOD code examples render each snippet on its own
+  line again: the blocks are now `<pre>` elements; the previous `<div>`s
+  collapsed the newlines. (#10)
+
+## 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.6.0 → fastapi_loopguard-0.7.0}/CLAUDE.md

@@ -27,13 +27,13 @@ python examples/stress_app.py            # stress target on :8000
 python examples/run_stress_test.py --skip-locust   # validation suite against a running :8000
 ```
 
-CI lints and type-checks `src/` and `tests/` only — `examples/` is unchecked and does not satisfy the `ANN` rules the rest of the tree does. `tests/test_metrics.py` skips entirely unless `.[prometheus]` is installed, which is why `metrics.py` reports 0% coverage on a plain `.[dev]` run; the 80% gate still passes at ~88% overall.
+CI lints and type-checks `src/` and `tests/` only — `examples/` is unchecked and does not satisfy the `ANN` rules the rest of the tree does. `tests/test_metrics.py` skips entirely unless `.[prometheus]` is installed (the `dev` extra pulls it in, so a normal dev install runs them); the 80% gate passes at ~97%.
 
 ## Tech Stack (versions verified 2026-08-11)
 
-- Python `>=3.12`; CI matrix is 3.12 and 3.13. mypy is pinned to `python_version = "3.12"` with `strict = true`.
-- **One runtime dependency: `starlette>=0.37.0,<1.0`.** FastAPI is a *dev* dependency — the middleware is pure ASGI and must never import `fastapi` from `src/`. Adding any runtime dependency requires asking first.
-- Extras: `prometheus` (prometheus-client), `structlog`, `all`, `dev`, `stress` (locust + uvicorn). The `structlog` extra is currently declared but unused — nothing imports structlog.
+- Python `>=3.11`; CI matrix is 3.11, 3.12, 3.13 and 3.14. mypy is pinned to `python_version = "3.11"` with `strict = true`. The floor is 3.11 because `asyncio.Task.cancelling()` (used in `monitor.py` and `pytest_plugin.py`) landed there; nothing needs 3.12. ruff's `target-version` is deliberately unset so it derives from `requires-python` and the `UP` rewrites can never outrun the declared floor.
+- **One runtime dependency: `starlette>=0.37.0,<2.0`.** FastAPI is a *dev* dependency — the middleware is pure ASGI and must never import `fastapi` from `src/`. Adding any runtime dependency requires asking first.
+- Extras: `prometheus` (prometheus-client), `all`, `dev`, `stress` (locust + uvicorn). Every extra must make an observable difference once installed — a declared-but-unused `structlog` extra was removed for that reason, and adding an extra nothing imports is the same defect.
 - ruff selects `["E","F","I","N","W","UP","B","C4","SIM","ANN"]`, ignoring only `ANN401`. **`ANN` means every function needs full annotations**, tests and fixtures included. Line length 88, double quotes.
 - Build backend is hatchling; wheel packages `src/fastapi_loopguard`. Publishing triggers on a `v*` tag via PyPI trusted publishing (OIDC) — there is **no version-bump automation**, so `pyproject.toml` must be bumped by hand. `__init__.__version__` is derived from installed package metadata; after bumping, re-run `pip install -e .` or the version tests fail against stale metadata.
 - `.claude/` is git-ignored and excluded from the sdist. Committing anything there needs an explicit `.gitignore` negation.
@@ -44,18 +44,22 @@ CI lints and type-checks `src/` and `tests/` only — `examples/` is unchecked a
 src/fastapi_loopguard/
   config.py         LoopGuardConfig — frozen slotted dataclass + __post_init__ validation
   context.py        RequestContext, RequestRegistry, module-global _registry, free functions
+  hints.py          FIX_HINTS — the one definition of the suggested rewrites
   monitor.py        SentinelMonitor sleep-measure loop, AdaptiveThreshold
   middleware.py     pure-ASGI LoopGuardMiddleware, enforcement modes, HTML/JSON error pages
   logging.py        StructuredFormatter (JSON), configure_logging, log_blocking_event
-  metrics.py        optional Prometheus LoopGuardMetrics (see Known Gaps — not wired in)
+  metrics.py        optional Prometheus LoopGuardMetrics, wired in when prometheus_enabled
   pytest_plugin.py  pytest11 entry point, @pytest.mark.no_blocking, BlockingDetector
+  cli.py            `loopguard` console script — `loopguard report PATH`, exit 0/1/2
 ```
 
-**Layering (strict — a module imports only lower layers):** `config`, `context` → `monitor` → `middleware`. `logging`, `metrics`, and `pytest_plugin` are leaves; nothing on the detection path imports them, and they must not import `middleware`. `middleware.py` imports `LoopGuardConfig` inside `__init__` with an "avoid circular imports" comment — the cycle no longer exists, but the deferred import is harmless and not worth churning.
+**Layering (strict — a module imports only lower layers):** `config`, `context` → `monitor` → `middleware`. `hints` sits below all of them: it imports nothing, so `middleware` (detection path) and `pytest_plugin` (leaf) can both read it. Every surface that suggests a rewrite — console banner, strict-mode 503 HTML and JSON, the plugin's `hints` array — renders `FIX_HINTS`; `README.md` quotes it and is synced by hand. A hint may name only the standard library or a package this project already documents (`httpx`). `logging`, `pytest_plugin`, and `cli` are leaves; nothing on the detection path imports them, and they must not import `middleware`. `metrics` is the one exception: `monitor.__init__` imports it lazily, and only when `prometheus_enabled` is set, so `prometheus_client` stays off the import path of every app that does not ask for it.
+
+`cli.py` is the strictest leaf: it imports **only the standard library**. In particular it must never import `fastapi_loopguard.pytest_plugin`, which imports `pytest` — a dev dependency the console script's users will not have. It consumes the report as data against `docs/loopguard-report.schema.json` rather than importing the writer, and it does not validate against that schema at runtime (that needs `jsonschema`, also dev-only). `tests/test_cli.py` enforces both: an AST check on the import list and a subprocess import with `pytest` absent. `middleware.py` imports `LoopGuardConfig` inside `__init__` with an "avoid circular imports" comment — the cycle no longer exists, but the deferred import is harmless and not worth churning.
 
 `pytest_plugin.py` is registered as a `pytest11` entry point, so it auto-loads for **every** project that installs this package. Treat its hooks as public API and keep them cheap and side-effect-free for unmarked tests.
 
-**Detection flow:** ASGI `lifespan.startup` starts the monitor → `_handle_http` skips `exclude_paths`, then registers a `RequestContext` and writes the id to `scope["state"]["loopguard_request_id"]` → `_monitor_loop` sleeps `monitor_interval_ms` and computes `lag_ms = (elapsed - interval) * 1000` → lag over threshold calls `_handle_blocking`, which calls `record_blocking` on every active context → the send wrapper reads `ctx.blocking_count` / `ctx.total_blocking_ms` and emits headers or a 503 → `finally` unregisters (and stops a lazily started monitor once the registry empties) → any terminal lifespan message (`shutdown.complete`, `shutdown.failed`, `startup.failed`) stops the monitor.
+**Detection flow:** ASGI `lifespan.startup` starts the monitor → `_handle_http` skips `exclude_paths`, then registers a `RequestContext` and writes the id to `scope["state"]["loopguard_request_id"]` → `_monitor_loop` sleeps `monitor_interval_ms` and computes `lag_ms = (elapsed - interval) * 1000` → lag over threshold calls `_handle_blocking`, which calls `record_blocking` on every active context → the send wrapper calls `monitor.poll()`, then reads `ctx.blocking_count` / `ctx.total_blocking_ms` and emits headers or a 503 → `finally` polls once more and unregisters (and stops a lazily started monitor once the registry empties) → any terminal lifespan message (`shutdown.complete`, `shutdown.failed`, `startup.failed`) stops the monitor.
 
 ## Detection Invariants (non-negotiable)
 
@@ -65,13 +69,19 @@ src/fastapi_loopguard/
 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. 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.
+7. **One measured millisecond 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.
 
+9. **Detection must not depend on the app yielding.** `_monitor_loop` measures a tick by resuming from its own `asyncio.sleep`, so a handler that blocks and then returns without awaiting leaves that sleep expired and unmeasured — the stall is real, the response reports zero. `SentinelMonitor.poll()` closes it: a **synchronous** measurement of the in-progress tick against `_tick_start`, called from every send wrapper at `http.response.start` and once more in the `_handle_http` finally (which covers plain `"log"` mode and blocking after the headers are on the wire). It is synchronous on purpose — awaiting would hand control to the monitor task and reintroduce the ordering dependency it removes. `_tick_consumed` and `_tick_reported_ms` keep invariant 7 intact without losing lag: `_monitor_loop` reports only the **residual** (`lag - already reported`) of a polled tick, and feeds that residual, not the raw lag, to `_check_cumulative` and the adaptive window. The two portions are disjoint, so a stall that spans a response is reported as the polled part plus the residual — no millisecond counted twice, none dropped. A stall of 500ms that a `poll()` caught at 100ms is 100 + 400, not 100.
+
+`poll()` refuses to measure when `_tick_start` belongs to a tick no live task owns. `stop()`, the `_monitor_loop` error handler, and the loop's exit all clear `_tick_start`, and `poll()` additionally bails when `_task` is done. Without this a cancelled or backing-off monitor makes `poll()` report a stall that grows with wall-clock time — in strict mode, a 503 for a request that did nothing wrong. **Never gate this on a maximum tick age**: a real 5-second stall is exactly the case the library exists to catch. `BlockingDetector.stop()` in `pytest_plugin.py` has the same problem and the same shape of fix — it clears `_running` and **drains** the monitor task instead of cancelling it, so the expired sleep resumes and records before teardown.
+
 ## Conventions
 
 - **`LoopGuardConfig` is frozen — never mutate it, construct a new one.** All validation lives in `__post_init__` and raises `ValueError` with a message naming the field.
 - Every new config option needs three things: a validation rule in `__post_init__`, a case in `TestLoopGuardConfig`, and a row in `docs/CONFIGURATION.md`. Missing any one of them is an incomplete change.
+- **Everything from the request line is client-controlled.** ASGI servers percent-decode `scope["path"]`, so `ctx.path` and `ctx.method` can contain anything, newlines and HTML included. `html.escape` them before they reach the strict-mode HTML page, `_safe_for_console` them before printing, and never use the raw path as a metric label — `_route_label(scope)` returns the matched route template instead, which the app's route table bounds. The JSON error body is safe because `json.dumps` escapes for it.
+- **Nothing the middleware runs on the request path may raise into the host app.** `_poll_monitor` and `_record_request` both swallow and log. The `finally` poll runs *before* `unregister_request`, so an escaping exception there would break invariant 5 and leak the context forever.
 - **Response headers are lowercase bytes.** Pass-through responses carry `x-request-id`, `x-blocking-count`, `x-blocking-total-ms`, and `x-blocking-detected`, plus `x-loopguard-warning: blocking-detected` in warn mode. The strict 503 built by `_send_strict_error` carries `x-loopguard-enforcement: strict` and **omits `x-blocking-detected`** — a separate header set, not an extension of the first.
 - `request_id` is the first 8 characters of a `uuid4` — short enough to read in a terminal, not a security token.
 - **All internal timing uses `loop.time()` or `time.monotonic()`** — never `datetime` or wall-clock, which jump under NTP.
@@ -79,7 +89,7 @@ src/fastapi_loopguard/
 - Logger name is `"fastapi_loopguard"`, shared by `monitor.py` and `logging.py`. `monitor.py` logs inline with `%`-style lazy formatting; `logging.log_blocking_event()` is a helper for library *users* and is intentionally not called internally.
 - `exclude_paths` is checked before anything else in `_handle_http`, so health checks cost nothing.
 - Backward-compat shims are public API and stay: `get_current_request`, `set_current_request`, `reset_current_request`, `init_metrics`. `get_current_request` returns an arbitrary active context and is only correct for single-request cases — new code uses `get_active_requests()`.
-- `logging`, `metrics`, and `pytest_plugin` are **not** re-exported from `__init__.py`; import them by module path.
+- `logging`, `metrics`, `pytest_plugin`, and `cli` are **not** re-exported from `__init__.py`; import them by module path.
 
 ## Testing
 
@@ -89,15 +99,43 @@ src/fastapi_loopguard/
 - HTTP tests use `httpx.AsyncClient(transport=ASGITransport(app=app))`. Plugin tests use the `pytester` fixture to run generated test files in-process.
 - Each invariant has dedicated coverage: `test_enforcement_mode.py` for modes and dev-mode escalation, `test_monitor.py` for calibration, idempotency, and task cancellation, `test_cumulative_blocking.py` for the window, `test_context.py` for registry lifecycle and `__slots__`, `test_pytest_plugin.py` for the marker.
 - Timing tests are inherently flaky under load. Prefer driving `SentinelMonitor` directly with an `on_blocking` callback (as `test_cumulative_blocking.py` does) over asserting on wall-clock durations.
-
-## Known Gaps (accurate as of 2026-08-11)
-
-Recorded so they are not rediscovered. None are fixed yet; fixing any of them is its own task. The fuller list, including design tensions deferred from the 0.5 correctness pass, is `FINDINGS.md`.
-
-1. **`prometheus_enabled` is inert.** Neither `middleware.py` nor `monitor.py` imports `metrics.py`, so enabling the flag exposes nothing. Wiring it up means calling `record_blocking` / `record_request` / `set_threshold` from the monitor.
-2. **`docs/CONFIGURATION.md` names metrics that do not exist.** It lists `loopguard_blocking_events_total` and `loopguard_blocking_duration_ms`; the real names are `loopguard_blocking_total`, `loopguard_lag_seconds`, `loopguard_requests_monitored_total`, and `loopguard_threshold_seconds`.
-3. **`get_metrics()` can never find an instance.** It reads `_instances[prefix]` while `create_metrics` writes `f"{prefix}:{id(registry)}"`. `tests/test_metrics.py:188` documents the mismatch in a comment instead of failing on it.
-4. **`_generate_warning_banner()` is dead code** — defined in `middleware.py`, never called.
+- **A test that asserts a request came back clean must not run against a tight threshold.** It is asserting that nothing stalled the loop, which is not something a test controls. `TestStrictModeHeaders._blocking_app` uses a 2ms tick and a 5ms threshold, so a request there has ~7ms of uninterrupted loop time before it is called blocked - thinner than an ordinary generational GC pass in this same suite, which measures 4.3-17.8ms on 3.11 under coverage. Where those passes land is a deterministic function of the session's allocation sequence, so adding a test *anywhere* in the suite shifts them, and a margin that small reopens as a 503 for a request that did nothing wrong. That is how `test_clean_strict_response_carries_diagnostic_headers` broke once already. A tight threshold can only cause false positives, so it is free for the tests that assert blocking *is* detected and unaffordable for the one that asserts it is not: the clean-path test builds its own app at the shipped defaults (`_clean_app`). Give a new clean-path assertion its own generous threshold rather than borrowing a detection app's.
+
+## The evals harness (`evals/`)
+
+Not shipped with the package, but it decides what this project publishes about
+other people's models, so it carries its own invariants:
+
+1. **A sample that never ran is never evidence.** `runner.score_task` returns
+   three states, not two: measured-and-clean, measured-and-blocked, and
+   `measured: false` with `non_blocking: None`. Unmeasured samples are dropped
+   from blocked-rate denominators. Folding them into "did not block" is a
+   one-directional bias on the exact number the benchmark advertises, and it
+   is the bug that reached a published table once already.
+2. **Measured means the trap actually executed.** The runner appends a counter
+   to its *copy* of `helpers.py` and requires a non-zero count. The tally is a
+   file, not a module global, because a `ProcessPoolExecutor` answer is correct
+   and runs the helper in a child process.
+3. **The prompt the model sees is the committed fixture, byte for byte.** All
+   instrumentation goes into the temp-dir copy. `neutral/task.md` and
+   `hinted/task.md` must differ by exactly one added line — the hint sentence.
+   Anything else makes the measured gap unattributable. There is a one-line
+   symmetry check in `evals/README.md`; run it after touching any task.
+4. **Changing a prompt invalidates that cell's samples.** `helpers.py`,
+   `app_skeleton.py` and either `task.md` are all part of the prompt. Archive
+   and regenerate the affected cells; do not re-score across a prompt change.
+5. **An empty completion is an API failure, not a model failure.** Adapters
+   retry it and then raise. Never write it out as an empty `app.py`.
+6. **Scoring is free; generation is not.** After any judge change run
+   `python evals/matrix.py --rescore`, which re-judges every committed
+   solution and re-derives `app.py` from the archived raw response. Only a
+   prompt change needs the paid path.
+
+## Known Gaps (accurate as of 2026-09-11)
+
+Recorded so they are not rediscovered. Fixing any of them is its own task.
+
+None currently recorded. `FINDINGS.md` carries the fuller list, including design tensions deferred from the 0.5 correctness pass.
 
 ## Fundamental Guidelines
 

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

@@ -3,6 +3,10 @@
 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.
 
+Linked from the README, so it is checked against the code rather than left to
+rot: every item below was re-verified on 2026-09-11. Items that have since been
+fixed are struck through with a note, not deleted.
+
 ## Detection design
 
 1. ~~**Sub-threshold noise can still inflate the adaptive threshold.**~~
@@ -45,8 +49,9 @@ hardening pass) but deliberately left alone. Each item is its own future task.
 7. **The package could be zero-dependency.**
    `middleware.py` imports only type aliases from `starlette.types`; moving
    that import under `TYPE_CHECKING` removes the runtime dependency entirely
-   (works on Litestar, Quart, Django ASGI, ...). Also, the `<1.0` upper bound
-   on starlette will block installs the day Starlette 1.0 ships.
+   (works on Litestar, Quart, Django ASGI, ...). ~~Also, the `<1.0` upper bound
+   on starlette will block installs the day Starlette 1.0 ships.~~ — the bound
+   was widened to `<2.0` in #4; the `TYPE_CHECKING` move is still open.
 
 8. **`get_current_request()` returns an arbitrary active context.**
    A backward-compat shim that silently gives wrong answers under concurrency.
@@ -54,13 +59,18 @@ hardening pass) but deliberately left alone. Each item is its own future task.
 
 ## Dead / inert code and docs drift
 
-9. **`prometheus_enabled` is inert** (known gap #1): nothing on the detection
-   path imports `metrics.py`. Out of scope here (`metrics.py` untouchable).
+9. ~~**`prometheus_enabled` is inert**~~ — fixed. `monitor.__init__` imports
+   `metrics.py` lazily when the flag is set, and records blocking events,
+   monitored requests and the current threshold.
 
-10. **`_generate_warning_banner()` is dead code** (known gap #4).
+10. ~~**`_generate_warning_banner()` is dead code**~~ — removed. It was also
+    an unescaped-HTML template, so leaving it in the file was an invitation to
+    wire up an XSS hole later.
 
-11. **`docs/CONFIGURATION.md` names metrics that do not exist** (known gap #2)
-    and `get_metrics()` can never find an instance (known gap #3).
+11. ~~**`docs/CONFIGURATION.md` names metrics that do not exist** and
+    `get_metrics()` can never find an instance~~ — both fixed. The docs list
+    the four real metrics with their labels, and `get_metrics()` takes the
+    registry so it derives the same key `create_metrics()` wrote.
 
 12. ~~**`docs/CONFIGURATION.md` describes `fallback_threshold_ms` as "Used if
     calibration is unreliable"**~~ — fixed in the 0.6 pass; the docs now
@@ -69,8 +79,8 @@ hardening pass) but deliberately left alone. Each item is its own future task.
 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).
+14. ~~**The `structlog` extra is declared but nothing imports structlog**~~ —
+    the extra was removed rather than wired in (#51).
 
 ## Repro caveat worth keeping
 

{fastapi_loopguard-0.6.0 → fastapi_loopguard-0.7.0}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 Parham
+Copyright (c) 2025 Parham Davari
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal