[JarryShaw]

• Searched for similar pull requests
• Followed the coding style
• make test passes, and a test case covers the change
• Changelog entry: 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?

• docs — documentation only

---

Description

Part of #1103, round 6: the sixth whole-repo prose pass over pcapkit/foundation/, utilities/, toolkit/, interface/, dumpkit/ and their API pages.

• Stale claims:
  • Extractor._open_output lists the version field the PCAP engine passes.
  • The traceflow TCP end-of-capture finaliser is finish(), not submit(). _finalise also runs on a FIN when tracing one direction.
• fix(foundation): validate a registrar's code before registering it (#2186) #2193: the registry prose matches _check_code, so it is unchanged.
• Change-relative: "no longer", "always yielded", "before design: late duplicate IP fragments, and dpkt/scapy trace_format=pcap fallback #1507", sha markers, past-tense defect notes and "keeps reporting" are stated as behaviour, in the conditional where they describe a defect. This covers the extraction, the engines, reassembly, traceflow, the toolkits, compat and exceptions.
• Timed context: "a current interpreter" becomes "Python 3.12 or newer". "The current requirement" becomes "RFC 1122".
• Grammar: the opening sentences of utilities.exceptions and utilities.warnings, in both the .py and the .rst. "registry" becomes "registries" in register_dumper.
• Scope: comments and docstrings only. With docstrings stripped, every changed file has the same AST as main.
• Tests run: the docs, conventions, tier-guard and docstring-contract selection gives 244 passed. Foundation, utilities, toolkit, interface, reassembly and engines give 283 and 553 passed.

[JarryShaw]

Review: GOOD TO GO at bfe094e55 (Sonnet).

• Traceflow TCP: finish() runs _finalise on every buffered flow, submit() does not, and trace() finalises on a FIN when not bidirectional. Both rewrites are correct.
• "Python 3.12 or newer": matches the measured matrix in engines.rst. Upstream PyPCAP stops at 3.11, because of its Cython 0.29.32 pcap.c.
• _open_output: the PCAP engine passes version=self._vinfo, in the listed order.
• _note_eof_progress: the measurement stays (five of six frames, six unbounded). The 6c3d1b0d9 pin survives in tests/foundation/test_extraction_no_eof.py.
• Conditional rewrites: true as hypotheticals. For example, 8191 × 8 = 65528 octets.
• AST guard: OK on 18 files. No test pins the changed text. The narrow selections give 126 and 78 passed.
• Not blocking: a ragged reflow in the RecordTimestamp docstring.

[JarryShaw]

Ready to merge at bfe094e55. Part of #1103 (round 6).

• Review: Sonnet GOOD TO GO, first round.
• CI: all checks complete, Required checks passed SUCCESS, 0 failed.
• KTLO: 12 legs, no warnings.
• Ordering: merged into main and run. foundation leg: 740 tests, 0 failures.
• Conflicts: none against the current main.

[github-actions]

Coverage: 91.56% (unit tier, Python 3.15, bfe094e55, Unit Tests run success)

Package	Statements	Missed	Branches	Partial	Cover
pcapkit (top level)	104	4	20	2	95.16%
pcapkit/const	19599	881	2618	867	92.11%
pcapkit/corekit	2589	74	816	37	96.51%
pcapkit/dumpkit	282	3	102	3	98.44%
pcapkit/foundation	2994	23	1038	25	98.81%
pcapkit/interface	138	4	52	3	96.32%
pcapkit/protocols	17433	218	4584	185	98.15%
pcapkit/toolkit	869	36	298	10	95.20%
pcapkit/utilities	504	7	146	5	98.15%
pcapkit/vendor	4432	1988	1018	167	51.87%

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