[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

• 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

The foundation slice of #1202, test-only (unit modules feed extract an in-memory io.BytesIO, which #1509 made possible): reassembly recovers the payload, traceflow output re-reads to exactly its frames, every offline engine agrees with default, and override→restore through the 36 public pcapkit.foundation.registry registrars is symmetric (class-level registrars without a wrapper are out of scope). Failures sit in per-module KNOWN_FAILURES, checked in both directions.

Module (tests/foundation/…)	Subtests	Time	RSS
reassembly/test_reassembly_payload_roundtrip_unit.py	432	6.3s	125 MiB
traceflow/test_traceflow_reread_roundtrip_unit.py	100	3.1s	124 MiB
traceflow/test_traceflow_reread_roundtrip_runtime.py	23	3.9s	180 MiB
engines/test_engine_agreement_runtime.py	414 run, 828 skipped (670 run with pyshark + pypcapfile)	17.7s	292 MiB
registry/test_registry_symmetry_unit.py	190	2.4s	124 MiB

Gaps: #1500, #1501, #1520 (dpkt engine drops PCAP-NG SPBs), #1502, #1503, #1504, #1505, #1507 (dpkt/scapy/pypcapfile JSON trace), #1512 (pypcapfile reads no big-endian PCAP), #1513 (pypcapfile drops TCP over IPv6), #1514 (pyshark int('True') on TCP flags), #1515 (pyshark counts a journal export block as a frame). The late duplicate IP fragment is asserted as PARTIAL per the #1507 ruling.

Ran sequentially under a 200 MiB file cap after make_samples.py: the five modules, tests/foundation, tests/project, tests/test_tier_guard.py, tests/test_docstring_contract.py and util/run_unittest_leg.py foundation, all passing; the engine module also passes in a Python 3.11 venv with Scapy, DPKT, PyShark and PyPCAPFile (PyPCAP would not build: no pcap.h).

Refs #1202

[github-actions]

Coverage: 90.07% (unit tier, Python 3.14, cfed47a6d, Unit Tests run failure)

Package	Statements	Missed	Branches	Partial	Cover
pcapkit (top level)	104	4	20	4	93.55%
pcapkit/const	18795	843	2356	756	92.08%
pcapkit/corekit	2125	66	686	33	96.19%
pcapkit/dumpkit	242	2	88	2	98.79%
pcapkit/foundation	2648	97	930	41	95.03%
pcapkit/interface	112	7	40	5	92.11%
pcapkit/protocols	17086	238	4628	190	97.98%
pcapkit/toolkit	539	74	168	3	84.58%
pcapkit/utilities	431	4	124	4	98.56%
pcapkit/vendor	4409	2342	1006	157	43.25%

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

[JarryShaw]

Verdict: GOOD TO GO at 4775b2c93. Cross-reviewed on Sonnet; the author ran Opus.

• Both-ways enforcement works. A broken passing case was caught: 104 failures after skewing reassembly/ip.py:185. Gap'd cases made to pass were also caught: the 16 usec-to-nsec cases (fix(dumpkit): a nanosecond trace of a microsecond PCAP keeps the fraction unscaled #1500), and the dpkt big_endian_nanosecond case (fix(engines): the dpkt engine passes a Decimal timestamp for nanosecond PCAP #1501).
• design: late duplicate IP fragments, and dpkt/scapy trace_format=pcap fallback #1507 late duplicate is asserted as COMPLETE plus a separate PARTIAL, strict and loose, on IPv4 and IPv6, per the ruling.
• Coverage is real. There are 36 public registrars, and 23 captures × 6 engines × 8 aspects reconcile (586 run + 518 skipped). Every engine skip is keyed on a documented refusal or a fallback warning, and no disagreement was hidden. No temp-file or repo leaks.

Follow-ups being applied, so this will need one more push:

• The design: late duplicate IP fragments, and dpkt/scapy trace_format=pcap fallback #1507 row cites extraction.py:1367; on main the format swap is at :1440-1444.
• Gap(1361) points at a closed docs issue, so no fix would ever delete it. The reader that drops SPBs is pcapkit's own, so this is now fix(engines): the dpkt engine's own PCAPNGReader drops Simple Packet Blocks #1520.
• The pyshark/pypcapfile records skip says frames expose no timestamp, but both do. Compare the timestamps rather than skip.
• The docstring should name pcap_ct among the PCAP-NG refusers, and register_protocol_code among the excused registrars.
• test_builders_carry_the_payload counts runs, not octets, for strict PARTIAL streams.

I corrected the #1515 body: CI hit the harness bug first, so the parity jobs decide that row.

[JarryShaw]

Verdict: GOOD TO GO at f2cb71f33. A Sonnet delta review covered the five follow-ups and the rebase onto 5f4da2301 (range-diff =).

• fix(engines): the dpkt engine's own PCAPNGReader drops Simple Packet Blocks #1520: forcing the dpkt reader to yield SPBs made the moved timestamps/octets rows report "came back OK", so the moved gap patterns still catch a fix in both directions.
• Skewed dpkt input: this was caught as 22 timestamps and 22 octets failures.
• pyshark .004 vs .005: this is fix(engines): pyshark engine counts a systemd Journal Export Block as a frame #1515's frame shift, not a float artefact. Frame 5 is the systemd_journal block, and frames 1–4 are decimal-exact.
• Rerun: 23 captures × 6 engines × 9 aspects = 1242 cases, of which 670 ran and 572 were skipped.

Non-blocking:

• The pyshark octets skip reason overstates the limit. The engine opens FileCapture without include_raw, but pyshark itself can return raw octets.
• One full-module run hit an intermittent TSharkCrashException (retcode 255); four other runs did not.
• The pyshark and parity CI legs decide the tshark-4.2.2 rows (fix(toolkit): pyshark TCP trace crashes because tshark 4.x reports flags as 'True'/'False' #1514, fix(engines): pyshark engine counts a systemd Journal Export Block as a frame #1515).