Marketing claims register — verified positioning statements for the README

[EONRaider]

Target: rolling (feeds every release)

The competitive analysis behind the 1.3.1 → 2.2.0 roadmap produced a
set of positioning claims that are worth putting in the README — but
several of them are not true yet. They become true as specific
issues land, and publishing one early would be a self-inflicted wound.

docs/CLAIMS.md is the register: every claim, its evidence, how to
reproduce it, and whether it is safe to publish today or gated on a
roadmap item.

Why a register rather than just writing the README

Three of the strongest claims are conditional:

• "Within 15% of dpkt on decode" is false today — we are 2.9× slower
  on the corpus. It becomes true when Hoist protocol dispatch into module-level tables #82–Cache DNS section parsing instead of re-serializing per access #85 land.
• "Runs in a browser" is true but untested until Prove the browser claim with a Pyodide/WASM CI job #99.
• "5× faster than dpkt at encoding" is true now and nobody has
  ever said it.

Keeping the evidence next to the claim means the README can be updated
from a source that says what has been measured and when, rather than
from memory.

Rules for the register

1. No claim without a reproduction command or a file:line citation.
2. Every claim carries a status: VERIFIED, GATED ON #nn, or
   NEEDS RE-MEASUREMENT.
3. Comparative numbers name the competitor's exact version and the
   Python version they were measured under.
4. Re-measure before quoting in a release; hardware and upstream
   versions move.

Acceptance criteria

• docs/CLAIMS.md exists and is populated from the current
  analysis.
• README updates draw from it, and claims land only when their
  gating issue closes.
• Numbers are re-measured at each release that quotes them.

[EONRaider]

Closing out the roadmap (#107, via #144) substantially advanced both of this issue's open acceptance criteria, as a byproduct rather than separate work — noting it here rather than closing this issue, since it's explicitly rolling and has no fixed completion state (mirroring how #106 named #97 "already closed and merged" without re-doing it).

• "README updates draw from [CLAIMS.md], and claims land only when their gating issue closes." README.md gained a "Why NETProtocols" section built directly from docs/CLAIMS.md's newly-published claims — decode/encode throughput, import time, wheel size, the mypy --strict comparison, Pyodide/browser support, match/case exclusivity, and the licence wedge. Every one of them was gated on Roadmap: post-1.3.0 — performance, platform, typing, proof #107 closing, and none landed before it did.
• "Numbers are re-measured at each release that quotes them." All eleven previously-held comparative sections were re-measured against the current tree (not the Tier-1-era numbers that had been sitting in the file) before publication. Two claims that had no checked-in reproduction command — encoding throughput and import time — now have one (scripts/benchmark_encode.py, scripts/benchmark_import.py), closing a real gap against Rule 1.

Both criteria remain open by design — they describe an ongoing discipline ("draw from it", "at each release"), not a one-time task, so there's nothing here to check off permanently. The register keeps doing its job at the next release that quotes a number.

---

Generated by Claude Code