[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. Narrow runs only, listed below.

• 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

Part of #1103, the whole-repository prose sweep, for the foundation slice. It follows the #719 rules: prose only, accuracy first, no churn and no timed context.

Version directives (38, all 1.5.0, citing issues rather than PRs):

• versionchanged on Extractor, extract(), reassemble(), trace() and
  follow_tcp_stream() for the new parameters, timeout and tracing mode;
  on Engine, Reassembly, TraceFlow and Dumper for opt-in registration;
  on the IP, IPv6 and TCP reassemblers, make_dumper, PCAPIO,
  register_apptype, register_mh_extension, the dpkt reassembly adapters
  and pyshark tcp_traceflow.
• logging, warnings and BaseError: import-time handler, one report per
  channel, silent quiet errors; three "up to v1.4.1" page admonitions
  become the matching directives.
• versionadded on HoleDescriptor, Deferred, EnumKeyError and four logging
  functions; versionremoved for HoleDiscriptor, utilities.decorators and
  utilities.warnings.DEVMODE.
  Accuracy: traceflow TCP drops *args/**kwargs it does not take; return
  types and reassemble()'s strict match the code; follow_tcp_stream's
  PyShark note; a PR citation becomes its issue.
  Render: raw literals in two literal blocks, unresolved FileNotFound
  references, a duplicate BufferID entry. Prose: timed wording on the
  logging pages; grammar in the reassembly and IP docstrings.

Checks:

• An AST guard holds on every changed .py: code is identical once docstrings are blanked.
• tests/project and every test that reads the edited paths pass.
• A merged Sphinx build of all nine slices adds no new warnings.
• A Sonnet cross-review returned GOOD TO GO.

Not covered here; a round-2 PR follows: the engine and toolkit bodies, plus the parts of reassembly, traceflow, registry and utilities that were only partly read.

Refs #1103

[JarryShaw]

Verdict: GOOD TO GO at 832662c06. A Sonnet cross-review checked it (author: Opus).

• Scope: 27 files, all inside the slice.
• AST guard: all 22 changed .py files are identical once docstrings are blanked, and every changed line falls inside a docstring or a comment.
• Directives: all 38 are 1.5.0 (27 versionchanged, 7 versionadded, 4 versionremoved), checked by importing v1.4.1.post2 and comparing it with the head.
  • The 4 removed names all shipped in 1.4.x and are absent now.
  • The 7 added names are all absent from 1.4.1.post2.
  • Every :issue: number resolves to an issue.
• Accuracy: 34 prose and directive edits were checked against the code, with no wrong claim.
• Render: the merged build has no new warnings.
• Round 2: the engine and toolkit bodies.

[github-actions]

Coverage: 89.59% (unit tier, Python 3.15, 832662c06, Unit Tests run success)

Package	Statements	Missed	Branches	Partial	Cover
pcapkit (top level)	104	3	20	3	95.16%
pcapkit/const	18862	954	2368	868	91.06%
pcapkit/corekit	2461	69	780	35	96.54%
pcapkit/dumpkit	276	3	100	3	98.40%
pcapkit/foundation	2915	164	1016	34	93.59%
pcapkit/interface	138	7	52	5	93.68%
pcapkit/protocols	17184	224	4574	189	98.08%
pcapkit/toolkit	872	177	298	8	77.18%
pcapkit/utilities	512	2	158	4	99.10%
pcapkit/vendor	4417	2342	1010	157	43.38%

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