[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?

• fix — bug fix

---

Description

Closes #2308, per the ruling (take the recommendation).

• Root cause: hold_warnings.__exit__ replayed held warnings on any Exception exit and ignored discard. So a short trial parse in _parse_next_layer that raised reported its warnings before beholder replaced the layer with Raw.
• Fix:
  • hold_warnings honours discard on an Exception exit too.
  • beholder sets a _beholding context variable, and a trial that raises discards its warnings only while a beholder will replace the layer. With no beholder on the stack, the error and its warnings still reach the caller.
• Tests: test_trial_parse_raises_2308_unit.py covers the repro on both the warnings and the logger channels, the error filter, a cut Hop-by-Hop header, and two controls (a kept Shim6 header still warns, and no beholder still warns). The docs(logging,pcap): per-frame logging note and Frame.read suite claim are false #2236 and fix(protocols): a trial next-layer parse that is replaced by Raw still emits its SchemaWarnings #1580 tests that pinned the leak are updated.
• Fail-without-fix: on origin/main, 5 failed. On the head, 23 passed.
• Left out: a layer captured at least as long as its hint is parsed without holding. If it then raises and becomes Raw, its warnings still show. That is pinned in test_layer_that_cannot_be_replaced_holds_nothing.

[JarryShaw]

Review: GOOD TO GO at 9970fa305 (Sonnet).

• hold_warnings: it drops on discard for any exit. A successful trial is unchanged, and _parse_next_layer is the only caller.
• _beholding: set and reset in try/finally, and the token handles nesting. It behaves correctly in a fresh thread and under copy_context().run. With no beholder, ProtocolError is raised and its SchemaWarnings are still reported. pypcapfile's direct call keeps reporting.
• Repro: a 10-octet IPv4 header gives Raw with the header-length error, and no SchemaWarnings on either channel.
• Edited tests: a mutation of cap_len to len fails the docs(logging,pcap): per-frame logging note and Frame.read suite claim are false #2236 spy (154 != 24), so it pins cap_len. The fix(protocols): a trial next-layer parse that is replaced by Raw still emits its SchemaWarnings #1580 kept-layer guard moved to a Shim6 header that is genuinely kept.
• Fail-without-fix: 5 failed on origin/main across the changed files (3 in the new file; its 2 controls pass). On the head, 581 passed.

[github-actions]

Coverage: 91.56% (unit tier, Python 3.15, 9970fa305, 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	2594	74	816	37	96.51%
pcapkit/dumpkit	282	3	102	3	98.44%
pcapkit/foundation	3023	23	1044	25	98.82%
pcapkit/interface	138	4	52	3	96.32%
pcapkit/protocols	17441	218	4586	185	98.15%
pcapkit/toolkit	869	36	298	10	95.20%
pcapkit/utilities	502	7	144	5	98.14%
pcapkit/vendor	4432	1988	1018	167	51.87%

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

[JarryShaw]

Should we promote _beholding to beholding to match house convention since it's cross referenced in the library - does not have to become a public API tho.

[JarryShaw]

Recommendation: keep _beholding private.

pcapkit/protocols/protocol.py already has the same shape — a module-level, private ContextVar (_rebuilding) that internet.py imports and reads across module boundaries, with no promotion and no Sphinx entry. _beholding is the same kind of thing: an implementation-internal coordination flag, not part of the constructed-object contract that the "document the contract, hide the recipe" convention surfaces. I'd leave it private and undocumented, matching _rebuilding.