docs(pep,tests): correct the checksum protocol count and the registry-leak lineage

[JarryShaw]

Please follow the guide below

• Searched for similar pull requests
• Followed the coding style
• make test passes, and a test case covers the change — prose only, no assertion or logic touched
• Added a 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 of your pull request and other information

Two accuracy fixes for #719, both measured rather than inferred.

1. docs/source/contributing/pep.rst:744 undercounted by two. It said eight protocols parse a checksum or CRC field. Measured on main by matching field declarations named checksum/chksum/crc across pcapkit/protocols/{data,schema}/: ten — the list was missing IPX (ipx.chksum) and MH (mh.chksum). The "exactly one of them checks whether the value is right" claim still holds: checksum_valid exists only on SCTP, so "the other seven" becomes "the other nine".

2. The lineage in tests/protocols/test_dispatch_default_resolution_unit.py:8 named the wrong reporter for this layer. #1006 fixed the issue-versus-pull-request kinds there but left #425 credited with the defect these tests actually pin. Established from the PR bodies and git log -S:

• Parsing a packet pollutes the shared __proto__ registry, so a later register_* warns about a protocol nobody registered #421 (issue) reported the __proto__ next-layer registry pollution; protocols: stop next-layer dispatch writing to shared registries, and fix two transport defects #426 (PR) closes it and is the commit that introduced the if proto in registry guard at this layer (209eabb19).
• Option, chunk and block registries leak on lookup miss, the same way __proto__ did #425 (issue) reported the sibling option/chunk/block family; protocols: stop option, chunk and block dispatch writing to shared registries #428 (PR) closes it and introduced _lookup_registry (f137a5b5a), extending the pattern to those registries.
• fix(schema): stop EnumSchema.registry from retaining a lookup miss (#555) #560 (PR) fixed the schema layer, closing EnumSchema registries retain every looked-up code, so a lookup miss leaks and contaminates later parses #555.

The sentence now reads: #421 reported, #426 fixed at this layer, #428 extended to the option, chunk and block registries, #560 fixed the schema layer. The paragraph is re-wrapped to ~80 columns, which is why that hunk is larger than the edit.

Correcting my own note on #719: I wrote there that #428 added the guard at this layer. It did not — git log -S'if proto in registry' attributes that to #426; #428 added _lookup_registry.

The sweep also checked ~40 other counting claims across docs/source/** and pcapkit/** docstrings against the code — registry counts, enum members, subclass counts, workflow and job counts, the "48 of the 52 resolutions" in this very docstring — and every one of them already matched. Prose only: ast.dump with docstrings blanked is identical to main, docs build warning sets identical at 53 each, and 0 roles nested inside inline markup.

[JarryShaw]

NEEDS CHANGES at 82785e827 — opus cross-review, a different model from the sonnet agent that wrote the diff. Every one of the seven claims it checked held, including both of mine. The defect is completeness: correcting the test docstring leaves the identical mis-attribution in the production source, so the tree now contradicts itself.

pcapkit/protocols/protocol.py:1744 — inside _lookup_next_layer, the __proto__ path these very tests call — reads :issue:`425` at this layer and :issue:`555` at the schema layer. By this PR's own corrected lineage, this layer's defect is #421. Being fixed, along with pcapkit/corekit/sentinels.py:366, which relays that note as "#425 and #555" and has to track it.

docs/source/changelog/1.5.0.rst:540 carries the pre-PR wording verbatim ("the defect #425/#428 fixed at this layer"). That file belongs to #657 and is deliberately out of scope here; I am recording it there rather than widening this change.

The review also settled the question my brief could not: all three tests call Dummy._lookup_next_layer(Dummy.__proto__, 99), and git log -S'_lookup_next_layer' returns only 209eabb19 (#426) while _lookup_registry returns only f137a5b5a (#428). So #421/#426 is this layer and the old #425/#428 was wrong.

On the checksum count it derived ten independently with a stricter method — ast class attributes at any depth named checksum/chksum/cksum/crc — and widened the search to fcs|crc32|digest|hmac|icv|mic|integrity, finding no eleventh: AH.icv/ESP.icv are cryptographic MACs, and pcapng's fcs_len/crc_error are metadata and a flag. It also inverted one of my worries usefully: IPX.chksum and MH.chksum are protocol-header fields, whereas hopopt and ipv6_opts reach the list only through CALIPSOOption.checksum — so the two additions are the list's most defensible members.

One claim I will not repeat: the PR body says the docs build warning sets are identical at 53 each. The reviewer measured 61 in its own environment, the difference being three pcapfile guarded-import warnings plus env-dependent ref.python ambiguity counts, and it did not build the base. The load-bearing part does hold — zero warnings or errors cite pep.rst or contributing/ — but treat 53 as environment-specific rather than a property of the change.

[JarryShaw]

Fixed at 237b15f62 (was 82785e827). The delta touches only the two source files, 6 insertions / 4 deletions, and I verified it is nothing else; the whole change is now 4 files, +15/−10, still one commit on 79fce29c5.

pcapkit/protocols/protocol.py:1744, in _lookup_next_layer:

-stale; :issue:`425` at this layer and :issue:`555` at the schema layer are all that same defect.
+stale; :issue:`421` at this layer, :issue:`425` for the option, chunk and block registries
+beside it, and :issue:`555` at the schema layer are all that same defect.

and pcapkit/corekit/sentinels.py:366 now relays all three.

Naming all three rather than swapping one token was the right call, and it is the answer to the ambiguity I flagged. The sentence asserts that these are the same defect class — writing a registry miss or a resolved class into a class-level store — and that is true of #421, #425 and #555 alike. #421 is the precise citation for this function, since git log -S'_lookup_next_layer' returns only #426's commit, but dropping #425 would have narrowed the "same defect" claim and hidden the sibling registries. Each role is now named explicitly.

Two added lines run to 88 and 81 characters. Nothing in the repo lints line length, and both are inside docstrings that reST reflows, so I am not spending a CI round on it.

Label back to review: pending — the head moved, so the earlier verdict no longer tracks it. A delta review is running.

[JarryShaw]

GOOD TO GO at 237b15f62 — opus delta round. The completeness gap is closed and all seven items confirmed, several on stronger evidence than I had.

• The EnumSchema registries retain every looked-up code, so a lookup miss leaks and contaminates later parses #555 generalisation survived an attempt to refute it. pcapkit/protocols/schema/schema.py:1049 defines _EnumRegistry(collections.defaultdict) overriding __missing__ to return the default without inserting — literally the same mechanism as the protocol-layer fix, not a similar symptom.
• Naming all three was not merely defensible, it was necessary for consistency: schema.py:1067 on main already cites both Parsing a packet pollutes the shared __proto__ registry, so a later register_* warns about a protocol nobody registered #421 and Option, chunk and block registries leak on lookup miss, the same way __proto__ did #425 for the protocol-layer family, so swapping Option, chunk and block registries leak on lookup miss, the same way __proto__ did #425 out would have desynced protocol.py from schema.py.
• No fourth site. The sweep grepped bare numerals rather than the :issue: role, and that choice matters: searching :issue:425`` finds 4 sites where the bare numeral appears 60 times, so a role-only grep would have badly under-reported. Of the 12 surviving 425 sites outside `changelog/`, every one is either fixed here, the two correct schema-layer citations, or an allow-listed per-registry test reference. It also checked the four files that relay the `_lookup_next_layer` note and found none of them carries a citation at all.

One non-blocking nuance, which I verified and which pre-dates this change. The sentence ends "…are all that same defect", and the clause immediately before it is about a class that importlib.reload makes stale. Against that narrower framing the generalisation does not reach #425, because those registries hold a method-name string or a (parser, constructor) tuple rather than a class — pcapkit/protocols/transport/tcp.py:744-750 branches on isinstance(name, str) and otherwise takes name[0] — and a reload cannot make a string stale. Against insertion-on-miss, which the preceding paragraph establishes explicitly and which all three issue bodies describe, it holds for all three. The framing and the matching wording in sentinels.py both pre-date this delta, which only changed which issues are named, so it is a strict improvement on the base and not worth another round.

On line length we agree: no max-line-length or E501 config exists anywhere in the repo, and protocol.py already carries 256 lines over 79 (max 164), so 88 and 81 are inside house norms.

Not ready to merge yet — 6 CheckRun legs still in flight, 0 failures.

[JarryShaw]

Ready to merge at 237b15f62 — closing the "not yet" on the verdict above. CI is complete: 69 CheckRun legs green, 3 skipped, 0 failures, 0 in flight, mergeStateStatus CLEAN. The opus delta verdict stands at this head; nothing has been pushed since.

Yours to merge. Two things left out of this change and recorded rather than dropped: the third copy of the old lineage at docs/source/changelog/1.5.0.rst:540 is noted on #657, and the wording imprecision I described above — "that same defect" reading against the reload-staleness clause rather than against insertion-on-miss — pre-dates this change and is unaltered by it.