[JarryShaw]

Please follow the guide below

• 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. Targeted selections only; see below.
• Added a changelog entry: 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?

• fix — corrects a defect

---

Description of your pull request and other information

This follows #1575. The pypcapfile toolkit now reads these headers as the default engine does. All the changes are in pcapkit/toolkit/pypcapfile.py.

• fix(toolkit): the pypcapfile engine reads a TCP Data Offset below 5 as a 20-octet header #1590: a TCP Data Offset below 5 words gives no TCP input.
• fix(toolkit): the pypcapfile engine accepts an IPv4 IHL that runs past the packet #1591: an IPv4 IHL that runs past the captured octets gives no IPv4 input.
• fix(toolkit): the pypcapfile engine accepts IPv4 headers whose options the default engine rejects #1596: IPv4 options are checked by the default engine's own IPv4 parser. It gets the header alone, only when the header has options.
• fix(toolkit): the pypcapfile engine never finds IPv4 carried in IPv6 (4in6) #1592: ipv4_reassembly finds IPv4 inside IPv6, behind extension headers or 6in6, because the default engine takes a frame's first IPv4 layer. TCP inside it is still a tunnel and still warns.
• fix(toolkit): the pypcapfile engine silently drops TCP behind an IPv4 AH header #1593, fix(toolkit): the pypcapfile engine drops TCP behind an IPv6 extension header carried in IPv4 #1597: TCP behind AH (51) is read past it inside IPv4, and so is TCP behind the IPv6 headers the default engine dispatches there. Those are Hop-by-Hop (0), Routing (43), Fragment (44), Destination Options (60), Mobility (135) and HIP (139). Each of these is checked by its own default parser. ESP and Shim6 are not walked: ESP's Next Header is encrypted, and Shim6's parser refuses IPv4. Behind any of them, the TCP header must be one the default TCP parser accepts, because the fix(engines): TCP trace flows disagree between engines on snapped frames and on IPv4 total_length=0 #1518 raw fallback does not apply there. A tunnel behind them gets the tunnel warning.

Trade-off. Judging options with the default engine's parsers costs about 200 µs per frame that has them. 10k Router Alert frames take 2.61 s, against 0.49 s before. Each frame is parsed once across the three adapters, and frames without options are never parsed. A header the default parsers reject logs the same CRITICAL ProtocolError the default engine logs, once per distinct header since results are cached. A header rejected on length alone (Data Offset below 5, IHL past the packet, AH Payload Length 0, truncated TCP) logs nothing, where the default engine logs one. The warnings filters and the logger level are left as they were.

Tests (3.11 parity venv / 3.14 repo venv):

• The pypcapfile toolkit files give 75 passed on 3.11 and 51 passed, 24 skipped on 3.14.
• Reverting each fix on its own fails that fix's tests.
• The agreement table has the same 207 pypcapfile outcomes as on main.
• Coverage of pypcapfile.py stays at 100% on 3.11 and goes from 98.5% to 98.9% on 3.14.
• A fuzz of 3 × 2,500 frames (options, IHL, Data Offset, AH, extension-header chains, 4in6) shows no input differences. Tunnelled TCP is excluded, since it is left out on purpose.

Closes #1590
Closes #1591
Closes #1592
Closes #1593
Closes #1596
Closes #1597

[JarryShaw]

Verdict: GOOD TO GO at a532960cc. This was a Sonnet cross-review; the author ran on Opus.

• Repros: all six reproduce on main and agree on the head, across 62 crafted frames. A fuzz of 5 seeds × 2,500 frames gives 0 differences, against 592 on main. Option-kind sweeps over 2,560 frames give identical inputs, warnings and logs.
• No global state changes: warnings.filters, showwarning and the logger levels and handlers are unchanged after an extract. simplefilter('error') is honoured as on the default engine.
• Dispatch: the walk covers 0, 43, 44, 51, 60, 135 and 139, which matches Internet.__proto__. ESP and Shim6 stop it.
• Fail-before: the new tests fail on main. Narrow runs pass on 3.11 and 3.14, and the agreement module's outcomes are identical to main's.
• Cost: frames without options take the same time. A frame with options costs about 170–290 µs.

Non-blocking:

• PR body corrected. Headers rejected on length alone (Data Offset below 5, IHL past the packet, AH Payload Length 0, truncated TCP) log no CRITICAL, where the default engine logs one. Repeated identical headers log once, because results are cached.
• Long extension-header chains. With roughly 80 or more extension headers chained, the default engine finds no TCP: on 3.14, 80 still parses and 100 does not. pypcapfile walks iteratively and does find it. The divergence is the default engine's, filed as fix(protocols): a chain of ~80+ IPv6 extension headers exhausts recursion and leaves the payload undissected #1604.
• Cost of long chains. Each header costs one parse, so 3 frames of 7,990 headers take 3.2 s on pypcapfile, against 0.04 s on the default engine.

[github-actions]

Coverage: 89.72% (unit tier, Python 3.14, a532960cc, Unit Tests run success)

Package	Statements	Missed	Branches	Partial	Cover
pcapkit (top level)	104	3	20	3	95.16%
pcapkit/const	18858	956	2366	870	91.04%
pcapkit/corekit	2366	67	760	35	96.48%
pcapkit/dumpkit	275	3	100	3	98.40%
pcapkit/foundation	2855	154	1004	42	93.57%
pcapkit/interface	138	7	52	5	93.68%
pcapkit/protocols	16996	227	4540	192	98.04%
pcapkit/toolkit	843	96	296	6	87.88%
pcapkit/utilities	494	4	146	4	98.75%
pcapkit/vendor	4409	2342	1006	157	43.25%

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