# `tests/perf/` — relative-baseline perf regression pins (PF-01..08)

> **Charter:** the home for `@pytest.mark.perf` regression pins. Each pin
> measures a hot-path metric and compares it to a **recorded baseline**
> (`baselines.json`), with a tier tag and a numeric failure message — never an
> absolute wall-clock budget (PF-01 / PAPER-50). Excluded from the default
> gate (`-m 'not perf'`); run on a tagged hardware tier.

## Files

| File | What |
|---|---|
| `test_hmac_verifier_latency.py` | PC-02 — `HmacWebhookVerifier.verify` per-body-size latency (catches O(n²) regressions) |
| `test_ipallowlist_scan_cost.py` | PC-05 — 100-CIDR `IpAllowlist` worst-case scan cost |
| `test_exception_lookup_cost.py` | PC-06 — `ExceptionTranslationMiddleware._lookup_status` MRO walk |
| `test_bearer_session_wrapper.py` | PC-03 — `bearer_session` dependency wrapper overhead (verifier mocked away) |
| `test_request_id_middleware.py` | PC-01 — `RequestIdMiddleware` net per-request overhead (with-minus-without) |
| `test_lifespan_startup.py` | PC-04 — `setup_lifespan` enter+exit cost |
| `conftest.py` | the `bench` (measure) + `baselines` (assert/record) fixtures — the PF-01/03/04/07 harness (copied from mgf-common) |
| `baselines.json` | the recorded baselines (value/units/recorded_at/recorded_commit/threshold_pct/hw_tier). **Generated, never hand-edited.** |
| `hw_tiers.md` | the hardware-tier definitions (PF-08) |

## Running

```sh
pytest tests/perf -m perf -o addopts=        # run the pins against the baseline
MGF_PERF_REBASELINE=1 pytest tests/perf -m perf -o addopts=   # re-record ALL baselines (PF-04)
mgf-fed bench rebaseline                      # federation re-baseline verb (same effect)
mgf-fed bench rebaseline <metric>             # re-record one metric
```

A re-baseline is a **deliberate, separate commit** whose body explains *why*
the baseline moved (PF-04) — never folded into a feature change.
