fix(dumpkit): a PCAP trace writes the octets it has, not a truncated record's claimed length (#1541)

[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

Both readers keep a short record as captured. That covers a PCAP record whose incl_len runs past EOF, and a PCAP-NG block whose captured length runs past the block (#1405). The declared length stays in frame_info/cap_len, and packet holds the octets that are actually there. PCAPIO._append_value copied that declared length into the trace. It now writes len(packet), so every trace record holds exactly incl_len octets. A record held whole is written byte-for-byte as before.

• Frame.read now warns, in the same wording as the PCAP-NG reader. Until now, parsing such a record raised no warning at all. Parse then rebuild was already byte-exact, from both info and to_dict(), and stays so.
• On /tmp/r1511/badlen.pcap the trace record now reads incl_len 0x249 (585) and ends at EOF.
• None of the KNOWN_FAILURES rows change, and no sample capture holds a truncated record.

The two new *_1541_unit.py modules fail on main: 6 of 8 tests, with every subtest failing. Ran one at a time, all green: tests/dumpkit, tests/protocols/misc, tests/foundation/traceflow, the five tests/protocols/test_*roundtrip*, tests/project, tests/test_docstring_contract.py and tests/test_tier_guard.py.

Closes #1541

[github-actions]

Coverage: 90.09% (unit tier, Python 3.14, 8f0f504f0, 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	2202	67	710	34	96.26%
pcapkit/dumpkit	258	2	90	2	98.85%
pcapkit/foundation	2650	98	934	42	94.98%
pcapkit/interface	112	7	40	5	92.11%
pcapkit/protocols	17012	229	4576	189	98.04%
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 8f0f504f0. Cross-reviewed on Sonnet; the author ran Opus.

• Fix confirmed: on main, badlen.pcap traces to a record claiming 0x7fffffff octets with 585 present, and tshark rejects it with exit 14. Here the record claims 585 and tshark reads it (exit 0). Over a 185-point truncation sweep (IPv4/IPv6 TCP, IPv4 UDP), main wrote 10 malformed traces and this PR writes none. PCAP-NG EPB overruns are fixed too.
• Whole records are byte-identical: 496 trace files (23 captures × nanosecond × byte order) and 17 whole-capture fout dumps match main.
• Warning: a ProtocolWarning fires exactly once per truncated extraction, and never on the samples, on rebuild or on from_data.
• Merge-check: merged into current main (b6b95bc8e), the new tests plus tests/dumpkit and tests/protocols/misc/pcap give 107 passed. On main with the new tests, 10 fail. I ran both.

Not blocking:

• Undocumented change: a PCAP-to-PCAP fout dump of a tail-cut file now also rewrites incl_len, a 1-octet difference from the malformed source. That is arguably right, but the body mentions only traces.
• cap_len docstring: cap_len still holds the declared length, matching fix(pcapng): an EPB whose captured length runs past the block does not rebuild byte-exactly #1405's PCAP-NG precedent, so the Frame.cap_len docstring ("the number of octets packet holds") is false for a short record. It was already false on main; docs: #719-style prose sweep after the #1090–#1102 defect wave #1103's sweep covers it.
• Huge claims: a claimed length near 4 GiB raises MemoryError only under a tight RLIMIT_AS, at 67 MiB peak RSS. That predates this PR.
• Not checked: dpkt and scapy traces, until fix(engines): write real PCAP traces for dpkt and scapy (#1507) #1511 lands.