Audit competitor CI for performance gates, lift the comparative-claims embargo

[EONRaider]

Summary

Closes the last two pieces of the post-1.3.0 roadmap (#107):

1. #124 — audited ten comparable Python packet libraries (dpkt, scapy, pypacker, construct, pcapkit, dnspython, pyshark, nfstream, stackforge, PyTCP-net_proto) for whether they actually gate CI builds on a performance regression — not just run a benchmark and print a number. None of the ten do. Two ship real benchmark code that CI never invokes (construct disables it with --benchmark-disable; stackforge's Criterion benches are never called from its workflow). Every finding is cited to a file:line or workflow, dated 2026-09-04. docs/CLAIMS.md 1.7's comparative claim — "no other Python packet library in this comparison set gates performance in CI" — is now stated with that evidence.
2. The embargo lift. Audit competitors' CI for performance gates before claiming ours is unique #124 was the last piece of evidence docs/CLAIMS.md was missing before its COMPARATIVE — HELD sections could publish. All eleven are re-measured against the current tree (post Tiers 2-4, not the Tier 1 tree the numbers on file were last taken from) and published.

One PR covers both: #124's table and the embargo lift touch the same CLAIMS.md sections in an interleaved way that doesn't split cleanly, and the embargo lift can't honestly start before #124's evidence lands (#107's own ordering).

One finding moved against this project, and is reported as such rather than smoothed over: decode throughput vs. dpkt reversed from 1.16× faster (measured after Tier 1) to roughly 11% slower (measured now). Three tiers of added surface since — the registry-backed dispatch table (#87), the shipped chain walker (#88), structured per-raise-site error context (#91) chief among them — cost more than Tier 1's dispatch win banked. Still comfortably inside the 15% band claim 1.2 names, just no longer ahead. This reversal is exactly the kind of volatility the embargo existed to avoid publishing mid-flight — Rule 5 in CLAIMS.md is updated to say so.

Other re-measured numbers moved too, generally down from their Tier-1-era highs as the library grew: 5.6× faster than scapy on decode (was 6.2×), 4.5× faster than dpkt on encoding (was 5.3×), 8.5× faster to import (was implied ~14-21×), ~30× smaller wheel (was ~46×). All still strong, wide margins — reported honestly rather than cherry-picked.

README.md gains a "Why NETProtocols" section drawing the newly-cleared claims into the project's front door, in the tone docs/CLAIMS.md 4.2 sets for writing about competitors (facts with dates/versions, no editorializing, credit where due).

What's included

• docs/CLAIMS.md: Audit competitors' CI for performance gates before claiming ours is unique #124's audit table under 1.7; every HELD section (1.1-1.6, 2.1-2.3, 3.1, 4.1) re-measured, banner dropped, dated "Published 2026-09-04"; top-of-file embargo notice and Rule 5 updated to reflect the lift; three non-HELD sections (5.5, 5.7, 5.9) reworded so they no longer reference a "standing embargo" that no longer exists — they stay unpublished because they were never audited, not because Roadmap: post-1.3.0 — performance, platform, typing, proof #107 was open; the section-6 "faster than dpkt" entry corrected to match the new number.
• README.md: new "Why NETProtocols" section (comparative bullets, the mypy --strict snippet, browser/Pyodide and match/case claims); Roadmap section updated to reflect Roadmap: post-1.3.0 — performance, platform, typing, proof #107's completion.
• scripts/benchmark_encode.py (new): reproduction script for the encoding-throughput claim (1.3), which previously had none — Rule 1 requires one.
• scripts/benchmark_import.py (new): reproduction script for the import-time claim (1.4), same reasoning.
• CHANGELOG.md: entry under ## [Unreleased].

Verification

• uv run --frozen ruff check . and uv run --frozen ruff format --check . are clean
• uv run --frozen mypy is clean (strict) — 31 source files
• uv run --frozen pytest passes locally — 1088 passed
• uv run --frozen python scripts/benchmark.py --check --threshold 15 — within threshold (-8.5% vs. the v1.3.0 baseline on file)
• CHANGELOG.md has an entry under ## [Unreleased]

No src/ changes — this is docs/tooling only, as expected for a research-and-publish issue pair.

Notes

• #107 itself is a tracking issue with no fixed completion state a PR can close automatically; it'll be closed directly with a summary comment once this merges, matching how prior tiers' closing sweeps handled it.
• #101 (the rolling claims-register issue) will get a comment noting this work advanced both its unchecked acceptance criteria, without closing it — it's explicitly rolling.
• The dpkt-vs-netprotocols reversal (1.16× faster → ~11% slower) is real and reproducible (re-run three times during this session, consistent within ~5 percentage points each time). It is not a regression to fix in this PR — it's a measurement to publish honestly; whether to invest in closing that gap is a separate, future decision.

Closes #124.

🤖 Generated with Claude Code

https://claude.ai/code/session_0143tMFpiopxYLf6A2EeDyo9

---

Generated by Claude Code