[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 pyshark. It removes the pyshark code that exists only to match the default engine.

• Reverted, newest first: fix(toolkit): pyshark reads frames to the 64-layer bound and past tshark's 802.1Q limit, and keys its fallback by the header (#1609, #1671) #1686, fix(toolkit): pyshark traces no TCP inside encapsulations the default engine leaves raw (#1639) #1670 and fix(toolkit): pyshark traces TCP behind an IPv4 extension header as the default engine does (#1625) #1642, which brought in the second tshark pass over a frame's octets, the link type read from the capture file, the 64-layer bound, reading past tshark's 802.1Q limit, and ip.cur_rt keying. Also fix(toolkit): pyshark skips partial TCP headers and traces first fragments (#1611, #1612) #1613's OVERRIDE_PREFS, with its assertion in test_runtime_engines.py and its sentence in the engines index (docs/source/pcapkit/foundation/engines/index.rst), both back to their pre-fix(toolkit): pyshark skips partial TCP headers and traces first fragments (#1611, #1612) #1613 text. engines/pyshark.py now matches its pre-fix(toolkit): pyshark skips partial TCP headers and traces first fragments (#1611, #1612) #1613 version, and toolkit/pyshark.py its pre-fix(toolkit): pyshark traces TCP behind an IPv4 extension header as the default engine does (#1625) #1642 version, apart from one guard.
• Kept: fix(toolkit): pyshark skips partial TCP headers and traces first fragments (#1611, #1612) #1613's _has_fixed_header (fix(toolkit): one undissectable TCP header aborts a whole pyshark extraction #1611) and fix(toolkit): key tunnelled TCP by the innermost IP header (#1581) #1605's keying by the carrying IP header.
• Re-landed: fix(toolkit): pyshark's fallback ends the extraction when tshark reports no ip.dst, and keys a source-routed segment by the route's last hop #1671's crash fix, as _has_addresses. A TCP layer whose IP layer has no src or dst is skipped. Before, it raised AttributeError.
• Tests: the three modules added by fix(toolkit): pyshark traces TCP behind an IPv4 extension header as the default engine does (#1625) #1642, fix(toolkit): pyshark traces no TCP inside encapsulations the default engine leaves raw (#1639) #1670 and fix(toolkit): pyshark reads frames to the 64-layer bound and past tshark's 802.1Q limit, and keys its fallback by the header (#1609, #1671) #1686 are deleted, because every test in them pins reverted code or compares pyshark with the default engine. In test_pyshark_unit.py, the fix(toolkit): the pyshark engine traces fragmented TCP at the last fragment, not the first #1612 tests and agree() are gone. The fix(toolkit): one undissectable TCP header aborts a whole pyshark extraction #1611 tshark test and the new fix(toolkit): pyshark's fallback ends the extraction when tshark reports no ip.dst, and keys a source-routed segment by the route's last hop #1671 tests assert constants. Removing either guard makes its tests fail.
• Behaviour changes, all expected. A probe over the 23 sample captures plus hand-built ones found the 23 samples unchanged:
  • a fragmented segment is traced at its last fragment, not its first;
  • a live LSRR/SSRR segment is keyed by the route's last hop;
  • TCP past 20 802.1Q tags, or behind Mobility or HIP in IPv4, is not traced;
  • TCP the default engine leaves raw is traced as tshark dissects it: inside GRE, VXLAN, MPLS, PPPoE, L2TP, LLC/SNAP, ISL, Teredo, SLL and link types 12 and 14, behind Shim6, or past 64 layers.
• Not from this PR: an occasional TSharkCrashException (retcode 255), 7 on this branch and 4 on main over 10 runs of 73 captures each, a different capture each time. The 255 is asyncio's code for a child process already reaped, not tshark's: tshark alone exits 0 in 1460 of 1460 runs.

Runs (3.11 with tshark 4.6.9, then 3.14): pyshark modules, test_runtime_engines.py and test_engine_runtime.py: 59 passed and 1 skipped, then 58 passed and 4 skipped. test_tier_guard.py and test_docstring_contract.py: 117 passed on both. --collect-only over tests/foundation tests/integration tests/toolkit collects 853 on both. Sphinx: no new warnings.

Part of #1708

[JarryShaw]

Verdict: GOOD TO GO at 810477fe2. A Sonnet cross-review checked two rounds.

• Reverted: fix(toolkit): pyshark reads frames to the 64-layer bound and past tshark's 802.1Q limit, and keys its fallback by the header (#1609, #1671) #1686, fix(toolkit): pyshark traces no TCP inside encapsulations the default engine leaves raw (#1639) #1670 and fix(toolkit): pyshark traces TCP behind an IPv4 extension header as the default engine does (#1625) #1642, plus fix(toolkit): pyshark skips partial TCP headers and traces first fragments (#1611, #1612) #1613's tshark-defragmentation preferences. engines/pyshark.py now equals its pre-fix(toolkit): pyshark skips partial TCP headers and traces first fragments (#1611, #1612) #1613 file, and toolkit/pyshark.py its pre-fix(toolkit): pyshark traces TCP behind an IPv4 extension header as the default engine does (#1625) #1642 file apart from the re-landed guard.
• Kept, own job: the fix(toolkit): pyshark's fallback ends the extraction when tshark reports no ip.dst, and keys a source-routed segment by the route's last hop #1671 ip.dst guard (_has_addresses; stubbing it out reproduces 8 AttributeErrors), fix(toolkit): one undissectable TCP header aborts a whole pyshark extraction #1611's _has_fixed_header, and fix(toolkit): key tunnelled TCP by the innermost IP header (#1581) #1605's keying by the carrying IP header.
• Sample captures: the 23 captures trace identically to main.
• Behaviour changes, as the ruling intends: the four are listed in the body (fragments, live source routes, more than 20 802.1Q tags, deep nesting).
• Tests: on 3.11 with tshark, 59 pass. The guards pass, collection finds 853, and Sphinx shows no new warnings.
• Probe crashes: the TSharkCrashException seen in the probes is a pyshark/asyncio child-process race that also happens on main, not this change.

[github-actions]

Coverage: 89.41% (unit tier, Python 3.15, 810477fe2, 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	2887	144	1012	34	94.20%
pcapkit/interface	138	7	52	5	93.68%
pcapkit/protocols	17166	226	4580	190	98.07%
pcapkit/toolkit	1313	280	532	5	75.88%
pcapkit/utilities	494	4	146	4	98.75%
pcapkit/vendor	4417	2342	1010	157	43.38%

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