[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

---

Cross-references:

• point TraceFlow.finish/index/dump, register_tcp/udp/sctp, Reassembly.expire and
  the class name properties at their documented targets; qualify Completion,
  Deferred, Index, Extractor and LinkType so they resolve from any module
• document the per-protocol timeout and TCP window hooks, and the public
  dpkt timestamp and buffer helpers the adapters cite

Rendered output:

• move each toolkit adapter's reassembly condition into the body and keep Returns
  to one paragraph, which drops the empty paragraph Returns opened with
• reword first lines napoleon split as a type, drop a python: prefix and a raw
  type prefix, hide the PyShark table reprs, drop a duplicated BufferID entry

Counts: remove counted numbers from living prose; spec quantities, constants and
measurements stay

Accuracy and wording: Raises and Warns for TraceFlowBase.register_dumper, the
output value shape, the MH registrar parameters, trace()'s protocol, the IPv6
overlap note, the traceflow packet shape, make_dumper's return, the PCAP-NG
Context summary, timed "this tree" wording, and typos and grammar

Non-prose check: ast.dump is unchanged on every .py file once docstrings are blanked. Narrow test runs are green.

Refs #1103

[JarryShaw]

Verdict: NEEDS CHANGES at 13041bef6. A Sonnet cross-review (author: Opus) confirmed:

• every changed cross-reference target, against the base objects.inv;
• the new __timeout__/__window__ hook descriptions and where each is read;
• register_dumper's RegistryError/RegistryWarning conditions;
• the __output__, MH registrar, trace(), IPv6 overlap (RFC 8200 §4.5), traceflow packet, make_dumper and PCAP-NG Context rewordings;
• that the dropped BufferID entry was a :no-index: duplicate;
• AST identity with docstrings blanked.

Blocking, all re-checked:

• exceptions.py:719-724 (EnumKeyError): "the in-library call sites that catch … -- and every one of them keeps catching" has no predicate;
• config.rst:28-30: "read by pcapkit.vendor.default, PCAPKIT_VENDOR_RETRY and PCAPKIT_CI_MODE with the readers" now lists environment variables as readers;
• the body says Completion now resolves, but Completion is documented nowhere and is absent from a clean build's inventory. The PR adds two more Completion.COMPLETE references (data/ip.py:98, data/tcp.py:92).

A worker is adding a fix commit to this branch.

[JarryShaw]

Verdict: NEEDS CHANGES at 6db91b69e. A Sonnet re-review confirmed that all four earlier findings are fixed:

• EnumKeyError has its predicate;
• config.rst matches vendor/default.py: read_limit/read_flag for the first two variables, os.getenv for the proxies;
• Completion is documented, and every claim in its docstring was checked at runtime;
• __output__ now targets TraceFlow.__output__.

Rendering Completion exposes two dead cross-references in its own docstring, both checked against a clean build's inventory:

• data.py:80 targets ReassemblyBase.timeout, which is not documented; Reassembly.timeout is;
• data.py:44,57 target pcapkit.utilities.compat.StrEnum, which is documented only as a module.

A worker is adding a commit.

[JarryShaw]

Verdict: GOOD TO GO at af77aaceb. A Sonnet re-review of the cross-reference commit confirmed:

• every role in the newly rendered Completion, __bool__, #: comments and EnumKeyError text resolves: it is in a clean build's inventory, is one of Completion's own members, or goes to the standard library;
• the 3.11 qualification, by running it: on 3.14, compat.StrEnum is enum.StrEnum and issubclass(TLSKeyLabel, compat.StrEnum) is False, and compat.py:153 takes aenum below 3.11;
• the Method.get rewording, by running it;
• AST identity, and that napoleon plus docutils report nothing on the changed docstrings.

[github-actions]

Coverage: 90.05% (unit tier, Python 3.15, af77aaceb, Unit Tests run success)

Package	Statements	Missed	Branches	Partial	Cover
pcapkit (top level)	104	2	20	2	96.77%
pcapkit/const	19595	881	2618	867	92.11%
pcapkit/corekit	2462	69	780	35	96.55%
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	17408	224	4580	189	98.10%
pcapkit/toolkit	872	177	298	8	77.18%
pcapkit/utilities	512	2	158	4	99.10%
pcapkit/vendor	4407	2342	1010	157	43.27%

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