fix(dumpkit): scale a PCAP trace record's fraction to the trace's resolution (#1500)

[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

PCAPIO wrote frame_info.ts_usec unscaled, so a trace at the other resolution was 1000× off. frame_info doesn't record its resolution, so the new PCAPIO._make_timestamp works it out from time_epoch: the fraction is in whichever resolution truncates the frame's offset into its second to exactly ts_usec.

• Same resolution as the file, or neither fits (a hand-built frame): written as is, so the bytes don't change.
• The other resolution: recomputed from time_epoch. µs → ns is ×1000. ns → µs divides by 1000 and truncates, like block2frame, Frame.make and libpcap's sf-pcap.c, so 999,999,999 ns stays in its second. A fraction of a second or more carries into ts_sec.
• PCAP-NG had the same defect: block2frame converts at the interface's resolution. It also keeps the exact timestamp_epoch, though, so this fixes PCAP-NG too and leaves engines/pcapng.py alone.
• Deletes the Gap(1500) rows: 32 unit cases and many_interfaces.pcapng.

The new tests/dumpkit/test_pcap_trace_resolution_unit.py fails on main: 12 failures, and every cross-resolution subtest fails. With the Gap rows gone, the traceflow modules fail on main too, with 33 failures. Ran one at a time, all green: tests/dumpkit, tests/foundation/traceflow, tests/project, tests/test_docstring_contract.py and tests/test_tier_guard.py.

Closes #1500

[JarryShaw]

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

Verified:

• Inference is exact for every frame pcapkit builds. time_epoch is a Decimal there, and a fraction fits both resolutions only when it is 0. 24,000 boundary frames gave 0 mismatches.
• Same-resolution traces are byte-identical; cross-resolution traces are corrected. Over 11 captures, 4,708 records and 132 synthetic PCAP-NG records across 11 interfaces were all 0 bad, against 2,354 and 58 bad on main.
• ns→µs truncation matches upstream. It agrees with both editcap -F pcap and libpcap 1.11.0 read at MICRO precision.
• No overflow. The carry and 32-bit bounds hold.
• Tests. Fail-before reproduces at 12 + 33. Rounding, a dropped carry and a swapped resolution are each caught by the new tests.
• Cost. About 1.5 µs per frame, which is within noise end to end.

Non-blocking:

• A float time_epoch makes the inference heuristic. The library never produces one, but the annotation suggests it does.
• A frame where neither resolution fits is written unchanged without a word; a logger.debug there would make it visible.

Merge-order note: #1511 gives the dpkt and scapy engines real PCAP traces. After the second of the two merges, I will re-run a cross-resolution dpkt/scapy trace against this inference.

[github-actions]

Coverage: 90.09% (unit tier, Python 3.14, 7b0e244c4, Unit Tests run success)

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	2161	66	700	33	96.26%
pcapkit/dumpkit	258	2	90	2	98.85%
pcapkit/foundation	2665	98	934	42	95.00%
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.