Stabilize Coverity Scan triage and document known false positives

Pin Cython in the Coverity Scan workflow (only) so the generated
mklrand.cpp is byte-stable between scans. Coverity derives CIDs from a
hash of the analyzed code, so an unpinned Cython bump regenerates the
file, resets every CID, and silently discards prior triage on the
Cython-boilerplate false positives. Production builds keep Cython
unpinned in pyproject.toml, so this does not affect shipped wheels or
Python support.

Add coverity/README.md recording the known false-positive families in
generated code (DEADCODE / UNUSED_VALUE / CHECKED_RETURN / OUT_OF_BOUNDS),
the verification of the High-severity _seed_impl OOB finding, the real
INTEGER_OVERFLOW fix (gh-156), and a review checklist that keeps
first-party src/*.cpp and __pyx_pf_* bodies in scope rather than
blanket-excluding the generated unit.

Author: antonwolfy

.github/workflows/coverity.yml

@@ -50,7 +50,14 @@ jobs:
           architecture: x64
 
       - name: Install build dependencies
-        run: pip install meson-python ninja cmake cython "numpy>=2" mkl-devel
+        # Cython is pinned here (and ONLY here) so the generated mklrand.cpp is
+        # byte-stable between scans. Coverity assigns CIDs from a hash of the
+        # analyzed code, so an unpinned Cython bump regenerates the file and
+        # resets every CID -- silently discarding all prior triage on the
+        # Cython-boilerplate false positives (see coverity/README.md). Production
+        # builds intentionally leave Cython unpinned in pyproject.toml. Bump this
+        # deliberately, and expect to re-triage the boilerplate afterwards.
+        run: pip install meson-python ninja cmake "cython==3.2.9" "numpy>=2" mkl-devel
 
       - name: Download Coverity Build Tool
         timeout-minutes: 15

CHANGELOG.md

@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 ### Changed
+* Pinned Cython in the Coverity Scan workflow so generated code stays byte-stable between scans (keeping CIDs and their triage from resetting on Cython releases), and added `coverity/README.md` documenting the known Cython-boilerplate false positives and the scan review checklist
 
 ### Fixed
 

coverity/README.md

@@ -0,0 +1,129 @@
+# Coverity triage policy
+
+Static analysis for `mkl_random` runs on the free [Coverity Scan](https://scan.coverity.com)
+service via [`.github/workflows/coverity.yml`](../.github/workflows/coverity.yml)
+(weekly, plus `workflow_dispatch`). Analysis happens on Black Duck's servers;
+triage (Classification / Action / Comment) is done in the Coverity Scan web UI
+and is keyed by **CID**.
+
+This document exists because the extension is built with **Cython**, and the vast
+majority of Coverity findings are in the **generated** `mklrand.cpp` translation
+unit, not in code we maintain. Those findings are boilerplate artifacts that
+recur on every scan. This file records which families are known false positives,
+how to triage them once, and — importantly — where the *real* signal lives so it
+never gets lost in the noise.
+
+## Where findings come from
+
+The build has three C/C++ translation units captured by `cov-build`:
+
+| Source | Nature | Who owns it |
+| --- | --- | --- |
+| `mkl_random/mklrand.pyx` → generated `mklrand.cpp` | machine-generated by Cython | Cython (regenerated every build) |
+| `mkl_random/src/mkl_distributions.cpp` | hand-written C++ | us |
+| `mkl_random/src/*.cpp` (other src files) | hand-written C++ | us |
+
+Within the generated `mklrand.cpp`, two kinds of functions appear:
+
+- **`__Pyx_*`, `__pyx_pw_*`, `__pyx_tp_*`, `__pyx_mdef_*`** — Cython runtime
+  boilerplate and Python-level wrappers. Findings here are ~always false
+  positives (see families below). **Not editable** — regenerated on every build.
+- **`__pyx_pf_*`** — the C translation of the *bodies* of our `.pyx` functions.
+  A genuine logic bug in `mklrand.pyx` could in principle surface here, so these
+  are **not** blanket-dismissed — but in practice every `__pyx_pf_*` finding to
+  date has also been a false positive, because Coverity cannot see Python-level
+  invariants (dtype sizes ≥ 0, fixed-length return tuples, etc.).
+
+## CID stability and the Cython pin
+
+Coverity derives a CID from a hash of the analyzed code. When Cython regenerates
+`mklrand.cpp` differently — which a new Cython release does — **every CID in the
+generated unit changes**, and all prior triage is silently lost. This is exactly
+what happened when the scan picked up a new Cython release: a fresh batch of
+identical boilerplate reappeared under new CID numbers, plus one new
+High-severity finding that needed a look (it was benign — see below).
+
+To keep triage durable, **Cython is pinned in `coverity.yml` only**
+(`cython==3.2.9`). Production builds leave Cython unpinned in `pyproject.toml`,
+so this does not constrain shipped wheels or future Python support. Bumping the
+pin is a deliberate act; expect to re-triage the boilerplate afterwards using the
+table below.
+
+## Known false-positive families (triage as `False Positive` / `Ignore`)
+
+All of these are in generated `mklrand.cpp`. Root cause and example CIDs from the
+scans reviewed on 2026-08-24:
+
+| Family | Checker | Why it's a false positive |
+| --- | --- | --- |
+| `__pyx_tp_traverse_*`, `__Pyx_CyFunction_traverse` | DEADCODE | `__Pyx_call_type_traverse` expands to the constant-`0` macro on standard-CPython builds, so `if (e) return e;` is dead. Guard is live only in the Limited-API build variant. (e.g. CID 652704, 652707) |
+| `__Pyx_VectorcallBuilder_AddArg`, `__Pyx_PyCode_New`, `__Pyx_CallSlotAsVectorcallUnpackDict` | DEADCODE | `__Pyx_PyTuple_SET_ITEM` expands to the void `PyTuple_SET_ITEM` yielding constant `0`, so `if (... != 0)` is dead. Guard is live only in the Limited-API variant. (e.g. CID 652697, 652705) |
+| `__Pyx_AddTraceback` | DEADCODE | `c_line` is fixed at `0` unless the optional `CYTHON_CLINE_IN_TRACEBACK` feature is enabled, making the `-c_line` branch dead by default. (e.g. CID 652698) |
+| `__Pyx_ParseKeywordDict` | DEADCODE | In the CPython < 3.13 branch `found` is only ever 0/1, so `if (found < 0)` is dead; the guard serves the ≥ 3.13 `PyDict_GetItemRef` path. (e.g. CID 652703) |
+| `__Pyx_PyLong_As_*` (npy_int16/uint8/int32/uint32/npy_bool/int/uint16/unsigned_int/npy_int8/irk_brng_t, …) | DEADCODE | Per-C-type integer-conversion helper templates; dead branches are compile-time-selected version/overflow guards. |
+| `sanity_check_for_cython` | DEADCODE | Cython/meson build sanity-check stub. |
+| `__pyx_pf_*` bodies with temp cleanup (e.g. `choice`, `multivariate_normal`) | UNUSED_VALUE | `__pyx_t_N = 0;` nulls a temporary after its reference is transferred (`__Pyx_DECREF_SET` / assignment), guarding the error path against a double-DECREF. Dead only on the straight-line path. (e.g. CID 652699, 652700) |
+| `__pyx_pw_*` keyword wrappers (`rand`, `randn`, …) | CHECKED_RETURN | `PyDict_Size` (via `__Pyx_NumKwargs_VARARGS`) is captured into `__pyx_kwds_len` and checked on the *next* line (`if (__pyx_kwds_len < 0) return NULL;`). The statistical heuristic misfires because the check is one line from the call, not inline. (e.g. CID 652972, 652973) |
+
+### Verified: CID 653949 (OUT_OF_BOUNDS in `_seed_impl`) — false positive
+
+Flagged High. The tuple unpack `brng_token, stream_id = _parse_brng_argument(brng)`
+(`mklrand.pyx:1571`) generates `PyTuple_GET_ITEM(sequence, 1)`. It is guarded by
+the generated `if (unlikely(size != 2)) { … __PYX_ERR(...) }` check, so the
+index-1 read is only reached when `size == 2`. Independently,
+`_parse_brng_argument` always returns a fixed 2-tuple (`mklrand.pyx:1533`).
+Coverity does not tie the `ob_item[1]` access back to the `size != 2` guard
+across the macro. No out-of-bounds access is possible.
+
+## Real findings fixed
+
+- **CID 652701** (INTEGER_OVERFLOW, `irk_rand_uint32_vec`, hand-written
+  `mkl_distributions.cpp`): `npy_int32 shift = (npy_uint32)INT_MAX + 1` = 2**31
+  overflowed the signed type. Fixed by declaring `shift` as `npy_uint32`
+  (behavior unchanged; all uses are modulo-2**32). See gh-156.
+
+This is the only real defect the scans surfaced so far, and it was in
+**hand-written** code — consistent with the guidance below.
+
+## Review checklist for each new scan
+
+Do **not** blanket-ignore the generated unit — that could hide a genuine
+`.pyx`-logic bug. Instead, prioritise:
+
+1. **Any finding in `mkl_random/src/*.cpp`** (hand-written C++). This is where the
+   only real defect so far lived. Review every one.
+2. **Any High/Medium finding in a `__pyx_pf_*` function** (our translated logic).
+   Verify against the `.pyx` source; if it reduces to a Python-level invariant
+   Coverity can't see (dtype size, fixed tuple length, guarded index), mark it
+   `False Positive` with a one-line reason.
+3. **Everything matching the boilerplate families above** — triage
+   `False Positive` / `Ignore` in bulk, referencing this file.
+
+## Optional: component grouping in the Scan UI
+
+If the Scan project's settings expose a component map, add a component that
+isolates the generated unit so the noise can be filtered in one click. Suggested
+file-path regex (matches the meson build output seen in the reports,
+`/build/cpXXX/mklrand.cpython-XXX-…`):
+
+```
+.*/mklrand\.cpython-[0-9]+.*\.(c|cpp)$
+```
+
+Hand-written first-party code stays outside this component and remains the
+default review target.
+
+## Optional: dropping the generated unit entirely
+
+If the boilerplate ever outweighs its value, the generated translation unit can
+be removed from analysis *before upload* (repo-side, durable, path-based) by
+inserting this after the `cov-build` step in `coverity.yml`:
+
+```bash
+cov-manage-emit --dir cov-int --tu-pattern "file('.*mklrand.*\\.cpp')" delete
+```
+
+This is the "hard exclude" — it also drops the `__pyx_pf_*` bodies, so it trades
+away the (so-far theoretical) chance of catching a `.pyx`-logic bug for zero
+boilerplate noise. Left disabled by default in favour of the review checklist
+above.