Add a reproducible benchmark harness and an advisory CI gate

[EONRaider]

Summary

Closes Tier 1. There was no benchmark anywhere in the repo, and the tier is worth ~3× end to end with nothing to stop it silently regressing.

• scripts/benchmark.py — walks the 97-frame corpus, reports frames/sec. Frames the library rejects are counted rather than skipped, so a change that "speeds things up" by decoding less shows up.
• --compare — times dpkt and scapy on the same frames. Both live in a new bench dependency group, so the package keeps zero runtime dependencies.
• benchmarks/baseline.json + --check — regression comparison, wired into CI.

One command

uv run --group bench python scripts/benchmark.py --compare

Measured (post-Tier-1, CPython 3.12.3, x86-64 Linux, best of 9)

	frames/sec	vs. us
netprotocols	121,945	—
dpkt 1.9.8	105,292	0.86×
scapy 2.7.0	19,657	0.16×

v1.3.0 measured 2.9× slower than dpkt. docs/CLAIMS.md claim 1.2 was gated on #82/#83/#84 and is now measured, with caveats attached (below) and the README wording deliberately left to you.

The CI job is advisory, on purpose

continue-on-error: true. Throughput on a shared runner is noisy, and a threshold I picked here without runner data would start failing pull requests that changed nothing — the one failure mode that costs you time rather than me. The job measures, compares and writes a job summary; setting a real threshold is your call once there are runner numbers to look at. This PR's own run will produce the first of them.

Two limits found while building it

Both are handled in code rather than hidden, and are the reason the numbers above are worth anything:

1. Calibration sizing. Absolute throughput is a property of the machine, so each run also times a fixed calibration workload and reports a normalized figure — that collapses the gap between two interpreters on one machine from 5.5% to 0.8%. But my first version ran the calibration for barely a millisecond, which timed the scheduler and put 24% of noise straight into the gate. It now runs a fixed 1000 passes, sized to tens of milliseconds, independent of --repetitions.
2. Normalization does not cancel the interpreter. The same code and machine normalize to 6.8 on CPython 3.12 and 7.6 on 3.13. A baseline belongs to the Python that recorded it: --check re-measures with the baseline's own settings, warns on a version mismatch, and the CI job pins 3.12 to match baseline.json.

Fairness caveats ship with the output

The issue's premise is that every published benchmark in this space is unusable, so the harness prints, under every comparison:

• The libraries are not asked for identical work — on the DNS-over-TCP frames dpkt stops at TCP and leaves the payload as raw bytes where netprotocols continues into DNSOverTCP → DNS. Where the depths differ, we are doing more.
• Each materializes a different amount per frame (frozen dataclasses vs. lazy attributes vs. forced .layers()).
• One machine, one corpus, one CPython — quote the machine with the number.

Verification

• uv run ruff check / ruff format --check / mypy clean; uv run pytest — 757 passed
• Workflow YAML parses; benchmark job present, continue-on-error: true, Python pinned to 3.12
• CHANGELOG.md entry under ## [Unreleased]

Closes#86.

🤖 Generated with Claude Code

https://claude.ai/code/session_01QJnVMNGwTRDktC4rkABtgt

---

Generated by Claude Code