refactor(corekit): merge the two DeferredPacket classes into corekit.packet (#1516)

[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

This merges the two DeferredPacket mixins into pcapkit.corekit.packet.DeferredPacket, as ruled on #1516.

• The two classes had AST-identical method bodies. They differed only in which module's Deferred their isinstance check named. Each subclass now names it in __deferred__, so corekit imports nothing from foundation or protocols.
• __init_subclass__ refuses a subclass that is missing 'packet' in __additional__, or is missing __deferred__. Either omission used to fail silently on the first read.
• ip.Datagram, tcp.Datagram and the traceflow Index now take the mixin from corekit. Both Deferred classes stay where they are.
• DeferredPacket can still be imported from its three old public paths, pcapkit.foundation.reassembly.data and both data.data modules. Each re-exports the one class and keeps it in __all__, and a test pins all three as the same object. pcapkit.corekit does not export it, because corekit/__init__.py belongs to refactor(corekit)!: Info.to_dict() returns an OrderedMultiDict; add MultiInfo and OrderedMultiInfo (#1484) #1523.
• New page: docs/source/pcapkit/corekit/packet.rst. The reassembly and traceflow pages link to it instead of documenting a copy.

Output is byte-identical. I compared canonical to_dict() JSON and every trace file written, for all 23 examples/captures in four passes: pcap with trace_analyse, json, and pcap with the dpkt and scapy engines. That is 588 files, and diff -r against 16fbea054 is clean. Laziness is unchanged: .packet resolves once, and iteration, in and len do not resolve it.

Tests run, all green: the new test, tests/foundation/{reassembly,traceflow,engines}, tests/toolkit/test_engine_pcap_trace_runtime.py, tests/corekit, tests/project, tests/test_docstring_contract.py and tests/test_tier_guard.py. On main all 12 new tests fail. Each of 5 mutations of packet.py makes at least one test fail, and so does dropping a re-export. Rebased over #1511, keeping its FrameRecord.

Refs #1516

[JarryShaw]

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

• AST: all 7 methods are identical to both old classes once Deferred is rewritten as self.__deferred__. __init_subclass__ is the only new method.
• Subclass hook: the library has exactly 3 DeferredPacket subclasses, each naming its own Deferred. ReassemblyData and TraceFlowData don't inherit the mixin. All 486 modules import cleanly.
• Laziness: on 11 captures, 27 object ops and 11 container ops, analyze/submit counts match main; the only difference is dir() now listing __deferred__. http.pcap gives T=1 R=2, as claimed. Pickles cross-load between the two trees.
• Byte identity: 413 to_dict(), json and tree outputs across 10 captures are identical.
• Back-compat: the 3 old import paths resolve to the same class and keep it in __all__. A full Sphinx build produces the same 41 warnings as main.
• Tests: fail-before is 12. 17 of 19 mutants are caught.
• The fix(engines): write real PCAP traces for dpkt and scapy (#1507) #1511 conflict is one hunk in traceflow/data/data.py: drop the old class and keep FrameRecord. On that merge, both PRs' tests pass.

Non-blocking test gap: two mutants survive, __contains__ not delegating and type() is replacing isinstance. One assertIn/assertNotIn pair plus a Deferred-subclass case would catch both.

[github-actions]

Coverage: 90.02% (unit tier, Python 3.14, 9fb7ad06b, Unit Tests run success)

Package	Statements	Missed	Branches	Partial	Cover
pcapkit (top level)	104	4	20	4	93.55%
pcapkit/const	18795	842	2356	756	92.09%
pcapkit/corekit	2240	67	722	34	96.32%
pcapkit/dumpkit	258	2	90	2	98.85%
pcapkit/foundation	2751	127	974	47	94.26%
pcapkit/interface	108	7	36	5	91.67%
pcapkit/protocols	16992	229	4546	190	98.03%
pcapkit/toolkit	635	98	198	5	83.31%
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]

Resolve conflicts

[JarryShaw]

On it. The worker is rebasing onto main (c3d412015) and resolving the traceflow/data/data.py conflict with #1511. It is keeping #1511's FrameRecord.time_epoch and checking for the semantic clash that hit #1511/#1529 earlier. The rebased head gets a delta review.

[JarryShaw]

Verdict: GOOD TO GO at 9fb7ad06b. This was a Sonnet delta review; the author ran Opus. The rebase over #1511 is clean.

• Conflict resolution: the range-diff shows only context changes. Against main, traceflow/data/data.py only gains the corekit.packet import and loses the old DeferredPacket. fix(engines): write real PCAP traces for dpkt and scapy (#1507) #1511's FrameRecord (with time_epoch) and _frame_record are untouched; I re-checked the diff myself.
• No semantic clash: there is no FrameRecord/time_epoch failure of the fix(engines): write real PCAP traces for dpkt and scapy (#1507) #1511/fix(dumpkit): scale a PCAP trace record's fraction to the trace's resolution (#1500) #1529 kind, and no import cycle (corekit/packet.py imports only utilities.exceptions). These all pass:
  • the DeferredPacket unit tests;
  • fix(engines): write real PCAP traces for dpkt and scapy (#1507) #1511's trace tests;
  • tests/foundation/traceflow;
  • tests/foundation/engines, run per file, with skips matching main.
• Byte identity: 1,071 trace files (6 captures × default/dpkt/scapy × PCAP-µs/ns/JSON) and 714 deferred flows (flow.packet, to_dict, trace bytes) are identical to main.