Roadmap: post-1.3.0 — performance, platform, typing, proof

[EONRaider]

Successor to #67, which is closed — all eight of its decoder-depth
items shipped in 1.3.0 and the tracker was empty.

This roadmap comes out of measuring the library against its actual
competitors rather than guessing. Five tiers, each mapped to a version.
Tiers are ordered by dependency, not preference.

Release policy (as stated, 2026-09-01): a PyPI release is cut only
at a major version bump. The version labels below are development
milestones, not release promises — intermediate tiers land on
master and ship with the next major. Of the five, only 2.0.0
is a release.

Correction (2026-09-04): this policy was not actually held to.
2.2.0 — a minor version — was also released to PyPI
(v2.2.0,
intentional, confirmed by the maintainer) once its own tier
completed, rather than folding into a later major as the policy
above says intermediate tiers would. In practice: 1.3.1 and 1.4.0's
work shipped folded into 2.0.0; 2.1.0's work shipped folded into
2.2.0; both 2.0.0 and 2.2.0 themselves were released directly. The
table below and README.md/docs/CLAIMS.md reflect this.

Version	Tier	Epic	Theme
1.3.1	0	#102	Hygiene — complete, shipped with 2.0.0
1.4.0	1	#103	Earn the benchmark before publishing one — complete, shipped with 2.0.0
2.0.0	2	#104	From codec to platform — registry, walker, flows · released 2026-09-04
2.1.0	3	#105	Make typing the product — complete (#93, #94, #95, #96), shipped with 2.2.0
2.2.0	4	#106	Proof as the product — complete (#97, #98, #99, #100) · released 2026-09-04
rolling	—	#101	Marketing claims register (docs/CLAIMS.md)

One consequence worth tracking

#80 fixed the layer sub-package exports — from netprotocols.layer7 import DHCP raised ImportError while from netprotocols import DHCP
worked. That fix is on master and, as of 2.0.0, on PyPI. It was
the only user-facing fix in Tier 0; everything else there is
maintainer-facing (CI gates, docs, version guards).

The finding that set the order

Measured on our own 97-frame corpus (CPython 3.12, one machine, against
dpkt 1.9.8 and scapy 2.7.0):

	frames/sec
scapy	17,100
NETProtocols 1.3.0	36,500
dpkt	104,000

We are 2.1× faster than scapy and 2.9× slower than dpkt — the
competitor we actually resemble. Publishing a benchmark table today
would advertise that. Tier 1 fixes three internal mistakes worth
2.4× end to end (a patched scratch copy hits 89,200 f/s and passes
all 698 tests), which is what makes the table worth publishing.

Encoding is already a win nobody has claimed: bytes(header) runs at
1,443,863 ops/s against dpkt's 270,485 — 5.3× faster.

Two gaps no previous plan mentioned

1. No extension point. No registry, no __init_subclass__, no
   hook — nobody can add a protocol without editing library source and
   opening a PR. Fixing it (A public protocol registry #87) is the same commit as the 91×
   dispatch win (Hoist protocol dispatch into module-level tables #82).
2. No structured errors. Strictness is the security story, but
   every exception is a formatted string with no offset or field
   (Structured parse diagnostics on ProtocolError #91). Scapy mostly does not raise; dpkt raises bare UnpackError.
   Nobody offers this.

Positioning this roadmap serves

scapy is GPL-2.0; pypacker GPLv2; both credible new entrants
(stackforge, PyTCP-net_proto) are GPL-3.0. The only other
permissive option is dpkt — last released 2022-08-22, last commit
2024-05-05, no py.typed, still marked Beta after twelve years.

That leaves a sentence we can defend: the only MIT-licensed,
strictly-typed, zero-dependency packet codec still being maintained.

Every claim in this issue is recorded with its evidence and
reproduction in docs/CLAIMS.md (#101), including which ones are
not yet true and which milestone makes them true.

Working agreement

One PR per issue, merged before the next is opened, so nothing
accumulates. Each PR references its issue and updates CHANGELOG.md.

---

Closing the roadmap: comparative claims are embargoed until then

No claim about another library is published until every tier above is
closed. Tier 1 is where that bites hardest: the corpus throughput,
depth, and encoding numbers are all measured and recorded in
docs/CLAIMS.md, but the nine comparative ones sit at
COMPARATIVE — HELD and stay there. The reason is that the roadmap
keeps changing the numbers — Tier 1 alone moved us from 2.9× slower
than dpkt to 1.16× faster — and a table published mid-roadmap would be
wrong within a month.

Two things happen when the last tier closes, in this order:

1. Audit competitors' CI for performance gates before claiming ours is unique #124 — audit competitors' CI for performance gates. Tier 1
   landed a blocking 15% corpus-throughput regression gate in CI. The
   obvious sentence to write about it — no other Python packet
   library gates performance in CI — is one nobody has checked, so
   docs/CLAIMS.md 1.7 deliberately states only the non-comparative
   form. Audit competitors' CI for performance gates before claiming ours is unique #124 audits dpkt, scapy, pypacker, construct, pcapkit,
   dnspython, pyshark, nfstream, stackforge and PyTCP-net_proto for
   an actual gate, records the negatives with citations, and then the
   comparative sentence is either written or struck. It's important
   to be sure at some point — this is that point.
2. Lift the embargo. Re-measure everything (Rule 4), then release
   the nine held claims together with the version and date they were
   measured against.

Ordering matters: the audit is the last piece of evidence the register
is missing, so it runs before the embargo lifts rather than after —
otherwise the first comparative table we ever publish contains the one
claim we never verified.