refactor(toolkit): revert pypcapfile's agreement-only code (#1708)

[JarryShaw]

Please follow the guide below

• You will be asked some questions, please read them carefully and answer honestly

• Put an x into all the boxes [ ] relevant to your pull request (like that [x])

• Use Preview tab to see how your pull request will actually look like

• Searched for similar pull requests

• Followed the coding style (make pylint, make mypy, make isort)

• make test passes, and a test case covers the change. Narrow runs only, listed below.

• Added a changelog entry under docs/source/changelog/ and regenerated CHANGELOG.md, if the change is user-visible: N/A — centralised in docs(changelog): shared 1.5.0 changelog — long-lived, merges last (#610, #616, #617, #618, #620) #657

What is the purpose of your pull request?

Tick the commit type your subject line carries.

• fix — corrects a defect
• feat — adds a feature
• perf — changes performance, not behaviour
• refactor — changes neither behaviour nor performance
• test — tests only
• docs — documentation only
• ci — workflows or build tooling
• release — bumps the version or rolls up a distribution
• chore — anything else

---

Description of your pull request and other information

Phase 2 of #1708, for pypcapfile: the code that exists only to match the default engine comes out, per the plan on #1687.

• Reverted: fix(toolkit): pypcapfile reads IP over loopback and raw-IP link types, up to the frame layer bound (#1609, #1667) #1682, fix(toolkit): pypcapfile checks IPv4 and TCP headers as the default engine does (#1590, #1591, #1592, #1593, #1596, #1597) #1600, fix(toolkit): pypcapfile TCP reads past VLAN tags, warns of tunnels, skips later fragments and padding (#1537, #1576, #1577) #1575 and fix(toolkit): the pypcapfile engine warns that it leaves TCP over IPv6 out (#1513) #1535, plus the pypcapfile hunks of fix(toolkit): dpkt reads IPv6 in IPv4, and nothing behind MPLS or Cisco ISL (#1637, #1638, #1646) #1655, fix(protocols): bound the IPv6 extension-header chain at 32 headers (#1604) #1608 and fix(toolkit): key tunnelled TCP by the innermost IP header (#1581) #1605. That removes the loopback and raw-IP link types, the frame layer bound, the VLAN and tunnel walks, the innermost-header TCP keying, the AH and extension-header stepping, and the option checks against the default engine's parsers.
• Re-landed as guards whose tests assert constants:
  • fix(toolkit): the pypcapfile engine parses a later IPv4 fragment's data as a TCP header #1576, fix(toolkit): the pypcapfile engine's TCP payload includes the frame's Ethernet padding #1577, fix(toolkit): the pypcapfile engine reads a TCP Data Offset below 5 as a 20-octet header #1590 and fix(toolkit): the pypcapfile engine accepts an IPv4 IHL that runs past the packet #1591;
  • fix(toolkit): pypcapfile engine silently leaves TCP over IPv6 out of reassembly and tracing #1513's once-per-capture warning for TCP straight over IPv6;
  • fix(toolkit): the pypcapfile engine hands no TCP or IPv4 input over on the NULL, LOOP, RAW, IPV4 and IPV6 link types #1667's packet2dict fix.
• Kept:
  • fix(engines): the pypcapfile engine reads the PCAP records pypcapfile drops (#1512) #1569's record reader and fix(toolkit): dpkt and pypcapfile hand over the correctly rounded timestamp (#1668) #1690's packet2timestamp;
  • the helpers the dpkt and scapy adapters still import, until their own reverts drop them.
• Now silent: TCP behind a VLAN tag, in a tunnel, or behind an extension header (an IPv6 one, or AH in IPv4) is left out without a warning. The docs say so everywhere they mention it.
• Tests: tests/toolkit 235 passed and tests/foundation/engines 146 passed, on 3.14 against current main. tests/toolkit also passes on 3.11 with pypcapfile 0.12.0 (245 passed).

[JarryShaw]

Verdict: GOOD TO GO at a176728e5. Sonnet cross-reviews checked six rounds of this change, the last one at a4d7ff4dc. a176728e5 is that same commit rebased onto main after #1718 merged, and git range-diff shows the patch unchanged.

• Prose: every statement about pypcapfile in pcapkit/ and docs/source was swept and matches the reverted code.
• Probe: ten probe cases confirm the docs. Only TCP straight over IPv6 on Ethernet warns; VLAN, AH, hop-by-hop, 4in4 and 6in4 drop the TCP silently.
• Guards: every re-landed guard's test fails when its guard is removed.
• Sphinx: the warning count is unchanged.
• Non-blocking: an IPv6 header cut below 40 octets also gets no warning, and "an IPv6 one, or AH in IPv4" leaves out IPv6 extension headers carried inside IPv4.

[github-actions]

Coverage: 89.35% (unit tier, Python 3.15, a176728e5, Unit Tests run success)

Package	Statements	Missed	Branches	Partial	Cover
pcapkit (top level)	104	3	20	3	95.16%
pcapkit/const	18860	954	2368	868	91.06%
pcapkit/corekit	2372	67	762	35	96.49%
pcapkit/dumpkit	275	3	100	3	98.40%
pcapkit/foundation	2885	144	1010	34	94.20%
pcapkit/interface	138	7	52	5	93.68%
pcapkit/protocols	17181	226	4590	190	98.07%
pcapkit/toolkit	1148	290	450	10	71.21%
pcapkit/utilities	500	4	150	4	98.77%
pcapkit/vendor	4417	2342	1010	157	43.38%

Per-file detail: the coverage-html artifact of this run.