pq-verify: Independent verification for ML-KEM / ML-DSA implementations

Abstract

Fixed --vector-dir was ignored for every bundled file. The loader consulted the pinned bundle first by file name, so a caller-supplied vector directory was never read for any file pq-verify also ships, while the report named that directory as the source. A directory with a corrupted expected answer reported 240/240; it now reports 239/240. The same loader serves prompt_dir and the prompt/response path. The bundle now answers only for pq-verify's own vectors directory, and a file missing from a supplied directory is an error rather than a silent fallback to the bundle. Added Vendor audits run in CI, pinned. tools/vendor_audits.json pins each audited third-party ML-KEM library to an exact commit with the result pq-verify must reproduce; tools/vendor_audit.py rebuilds every row and re-runs --audit-kem on each change to pq-verify and weekly. With the library, the vectors and the reference implementations all pinned, a failure can only mean pq-verify changed. Reintroducing the 2.8.0 symbol-resolution bug fails it on all three mlkem-native rows. Rows are only added, so the table records when a library's behaviour changes, and a test holds AUDITS.md equal to it. Results name the reference implementation that computed them. Next to the pinned vector revision, each ACVP run prints and records the version of the library that answered it (reference: kyber-py 1.2.0), in the console and in the JSON report's suites. The vectors were pinned; the software answering them was whatever happened to be installed, and nothing said which. CI pins those versions (constraints-reference.txt), so a CI result changes only when pq-verify's code does. Bumping one is its own PR. Users are not held to the pins, and tools/doctor.py warns when an environment differs from them. tools/doctor.py — the checks a NIST re-pin must pass. In the style of the syndicate-genesis and Dharmapala doctors: statuses ok / DECIDE / WARN / BLOCK, each finding with a next: command, --json for agents, and a token hashing what was examined and found. Offline it checks that the pinned bundle is sound: manifest coverage, NIST commit per file, watcher coverage, and FIPS 203 length of every key-check key. With --candidate it fetches NIST's changed files and runs, side by side with the pinned bundle: the same length checks, a negative control (a length-only checker must be fooled by every invalid key), every ACVP suite, a 14-day stability rule and provenance. --apply re-pins deterministically (byte-identical to the 2.8.1 re-pin done by hand) and is refused while the candidate BLOCKs. Replayed on history, it BLOCKs the vectors 2.8.0 shipped, which the ACVP suite scored 240/240. REPINNING.md — the procedure from watcher alert to release. The watcher's issue now names the doctor commands, and CI runs the doctor offline on every change. Verifying this release gh attestation verify pq_verify-2.8.2-py3-none-any.whl \ --repo bigDSanalyst/pq-verify Built by .github/workflows/release.yml from commit e6d6ba02c6ea19dcd976a2f8229c54b4eeb917e8, after the full suite and all 855 NIST ACVP vectors passed on Python 3.9 through 3.13. An SPDX SBOM is attached and attested.