docs(changelog,protocols): credit the registry-leak fixes to the right layer

[JarryShaw]

Please follow the guide below

• 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

This is a prose-accuracy change with no behaviour to cover by a new test, so the make test box is left unticked rather than claimed: the full suite exhausts memory on the machine this was prepared on. I ran tests/project/ (268 passed, 1 skipped, 864 subtests), the files covering the edited docstrings (416 passed, 16 skipped, 658 subtests), and tests/protocols/misc/test_pcapng_unit.py (93 passed, 1 skipped, 1773 subtests). CI's matrix is the authority on the rest.

What is the purpose of your pull request?

• 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
• chore — anything else

---

Description of your pull request and other information

Part of #719. Three separate registry-leak defects were fixed at three different layers, and four places credited the wrong pair. Resolved against the API rather than inferred from context:

Issue	Fixed by	Layer
#421 — parsing pollutes the shared __proto__ registry	#426 — "stop next-layer dispatch writing to shared registries"	next-layer dispatch
#425 — option, chunk and block registries leak on lookup miss	#428 — "stop option, chunk and block dispatch writing to shared…"	the option, chunk and block registries
#555 — EnumSchema registries retain every looked-up code	#560	the schema layer

The corrections:

• docs/source/changelog/1.5.0.rst:540 named Option, chunk and block registries leak on lookup miss, the same way __proto__ did #425/protocols: stop option, chunk and block dispatch writing to shared registries #428 as the defect fixed "at this layer" in a passage whose own words are "next layer dispatch resolves a descriptor there on a per-frame path". It now names all three layers, matching what protocols/protocol.py already said correctly.
• protocols/schema/schema.py, twice, called 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 jointly "the protocol-layer __proto__ family". Option, chunk and block registries leak on lookup miss, the same way __proto__ did #425 is the option, chunk and block family — a different registry set. Separated at both sites; the EnumSchema registries retain every looked-up code, so a lookup miss leaks and contaminates later parses #555 citation beside them was already right.
• tests/protocols/schema/test_enum_schema_registry_unit.py carried the same conflation, and tests/protocols/misc/test_pcapng_unit.py called a per-namespace Option.registry[ns][code] leak "the schema-layer form of the Parsing a packet pollutes the shared __proto__ registry, so a later register_* warns about a protocol nobody registered #421/Option, chunk and block registries leak on lookup miss, the same way __proto__ did #425/protocols: stop option, chunk and block dispatch writing to shared registries #428 defect" — the schema layer is EnumSchema registries retain every looked-up code, so a lookup miss leaks and contaminates later parses #555.
• protocols/protocol.py ended "…are all that same defect". That overstated the clause it attaches to: the three issues are about registries retaining a lookup miss, where the sentence is about a memoised resolved class going stale under importlib.reload. Narrowed to name the shared property precisely. The rest of that passage, landed in docs(pep,tests): correct the checksum protocol count and the registry-leak lineage #1007, is untouched.

Deliberately left as they are. test_dispatch_default_resolution_unit.py:33 and :140 say "the #426/#428 symptom" in a next-layer-only test. That is accurate — the symptom is a later register warning about an entry no caller asked for, which both fixes share — and the file header already states the three-way split. Likewise 1.5.0.rst:1605, which cites the pull requests without their issues, and the #425-as-defect-class citations in the HTTP/2, IPv6-extension, MH, PCAP-NG and SCTP tests, since #428 covered all sixteen registries per its own description.

corekit/sentinels.py is in the diff for a reason worth stating. It cited _lookup_next_layer's docstring note, by those three issue numbers, as the evidence that reload staleness is a tracked defect class. Narrowing that note to say the three are a retention defect "of a lookup miss rather than of a resolved class" would have made the two texts contradict each other — a contradiction this change would have introduced, since on main they agreed (both wrong, by this change's own thesis). The pointer now names what the note actually argues, and the reload-staleness evidence rests on test_no_stale_class_survives_a_module_reload, which pins exactly that.

CHANGELOG.md is regenerated and util/changelog_md.py --check reports it in step. No role sits inside **bold**, *italic* or a literal, which renders as literal text with no Sphinx warning. Added lines are at most 74 characters, within every block they sit in.

[JarryShaw]

NEEDS CHANGES at dea7eaa9a — opus cross-review, a different model from the sonnet agent that authored this. Both findings were real, I verified both myself, and both are now fixed at f113c5d76.

1. A fifth site, which this change would have made wrong. corekit/sentinels.py:363-367 cited _lookup_next_layer's docstring note — identified by those three issue numbers — as the evidence that reload staleness is a tracked defect class here. Narrowing that note to say the three are a retention defect "of a lookup miss rather than of a resolved class" makes it deny being about reload staleness, so the two texts would have contradicted each other. On main they agreed; wrong together, by this change's own thesis. That is a contradiction the diff introduced, not one it inherited, and it was missed rather than judged — the file was not in the diff and not in the "deliberately left" list. The pointer now names what the note argues, leaving the reload-staleness evidence on test_no_stale_class_survives_a_module_reload, which pins exactly that.

2. A width claim of mine that was false. test_enum_schema_registry_unit.py:8 went from 59 to 96 characters, the widest line in a file whose docstring block runs 42-79. I had asserted no added line was an outlier, but I measured against an absolute 100 rather than against each block's own width — the wrong test, and it passed for the wrong reason. Reflowed; added lines now peak at 74. Worth noting make pylint could never have caught this: PYLINT_FLAGS sets --max-line-length=120.

Also took its style note and dropped the mannered "there" from the protocol.py clause.

What it confirmed by its own derivation, from the issues' and PRs' bodies rather than from my summary: #425's body states outright that #421 covered the __proto__ next-layer registries and that the option/chunk/block family "was out of scope for the fix in #426"; #555's body notes #428's review acknowledged the schema layer needed the same treatment and that no issue was ever filed for it. So the three layers are disjoint by registry set and the split is better evidenced than I had claimed. It also checked the sixteen-registry basis for the citations left alone — #428's body says "16 registries across 39 read sites in 8 files" and its table sums to exactly that — and found none of those sites wrong. It falsified the --check gate rather than trusting it, perturbing one character to confirm the check fails, and used docutils role-parsing to show 6 roles written and 6 parsed, none swallowed.

One residual imprecision it recorded and did not ask me to change: describing #425/#428 as "the option, chunk and block registries" is the issue title's shorthand and under-describes the sixteen registries #428 shipped, while this same change leans on that broader scope to justify keeping the HTTP/2 and PCAP-NG citations. It matches existing house wording, so I left it. It did not build the docs, so the rendered appearance of the three-item aside at 1.5.0.rst:540-542 is unverified by either of us.

[JarryShaw]

Any updates?

[JarryShaw]

CI is clean at f113c5d76 — 69 CheckRun legs green, 0 failed, 0 running, 3 skipped by design, mergeStateStatus=CLEAN. What is missing is the cross-review verdict on this head, and the honest reason is that the machine restarted while it was running, so it never reported.

Where things stand:

• The round-1 cross-review returned NEEDS CHANGES at dea7eaa9a, with two findings I verified myself and fixed at f113c5d76 — the fifth site in corekit/sentinels.py that this change would otherwise have left contradicting itself, and an overlong docstring line in test_enum_schema_registry_unit.py where my own width claim had been false.
• I asked for a delta-only re-review of those fixes. That is the run the restart killed. It is re-dispatched now, confined to the three changed files, and also checking whether any file other than sentinels.py cross-references the narrowed note — one missed site means my grep for others is not trustworthy on its own.

So the label stays review: pending rather than good-to-go, because the verdict has to track this head and no verdict exists for it yet. Tests I ran locally on f113c5d76: tests/project/ plus both edited test files, 284 passed, 1 skipped, 864 subtests; util/changelog_md.py --check reports CHANGELOG.md in step.

I will post the verdict here as soon as it lands. If you would rather not wait on it, the diff is six files of prose with CI green and the round-1 findings already addressed — but I would not call it ready over my own signature until something has looked at the fixes.

[JarryShaw]

GOOD TO GO — opus delta re-review, a different model from the sonnet agent that authored this. Both round-1 findings are properly fixed and neither fix introduced anything.

On the sentinels.py fix it checked each pointer against its referent rather than against the shape of the sentence: _lookup_next_layer's note gives reload staleness as its stated reason for declining to memoise (protocol.py:1741-1744), and test_no_stale_class_survives_a_module_reload pins it by execution, covering both reload idioms. So the category error is gone rather than relocated — the old text identified the note by the three numbers the note now assigns to a different defect class, which is why it contradicted its own referent. It recorded one honest asymmetry: "tracked" means a documented rationale for the first pointer and a regression test for the second, both legitimate.

On the reflow it proved render-identity instead of assuming it — folding whitespace over the whole docstring from both commits gives byte-identical text, so the mid-sentence break after "cover" changes nothing. And it swept for further sites by a method that does not depend on the issue numbers, since the numbers are what missed sentinels.py in the first place: every prose reference to _lookup_next_layer and _lookup_registry, then every prose mention of reload. Four other pointers all cite the note for miss-retention, correctly; corekit/module.py:75-83 discusses staleness but attaches no issue numbers to it. My grep's conclusion held — it really was one site.

Two bookkeeping corrections it made to my own notes, both verified and both mine. CHANGELOG.md is not in the delta — byte-unchanged, correctly, since the delta does not touch 1.5.0.rst; my wording implied otherwise. And the figure 284 is 268 from tests/project/ plus 16, with the 864 subtests being tests/project/'s alone — it does not include test_pcapng_unit.py.

That second one was wrong in the commit message, which said "both edited test files". I have amended the message to carry the accurate per-file numbers. The new head is a2801562c and the tree is byte-identical — same tree object 9e3f487e25527c8f03fa8372c5eab803f96b901e, git diff f113c5d76 a2801562c empty — so this verdict carries forward on content unchanged; only the message differs. CI is re-running on the new sha and I will confirm when it is green.

[JarryShaw]

Ready to merge at a2801562c. CI is complete and clean — 69 CheckRun legs green, 0 failed, 0 still running, 3 skipped by design, mergeStateStatus=CLEAN. That is the same 69/3 result the tree produced at f113c5d76, which is expected since the amend changed only the commit message and the tree object is identical.

The GOOD TO GO verdict above is the opus delta re-review, and it stands at this head on that tree identity rather than by assumption.

Unpublished and unmerged, awaiting you.