docs(protocols): state the rulings behind mh, vendor and exceptions in our own words

[JarryShaw]

• 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 -- 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

Refs #987, #719. Group C of the quotation-to-statement conversion: nine quoted rulings in three files become statements with the reason and the issue cited, in the locative form (a ruling given in review of the work for #NNN).

• pcapkit/protocols/internet/mh.py (4 passages, 6 quotes): fix(mh): two kept get overrides advertise the base default argument and reject it with TypeError #935 — both get overrides deleted rather than widened; what that bought.
• pcapkit/vendor/__main__.py (1 passage, 2 quotes): python -m pcapkit.vendor exits 0 when a crawler raises, so a no-op regeneration looks like success #872 — snapshot-and-revert, keep zero-exited targets.
• pcapkit/utilities/exceptions.py (1 passage): stdlib-shaped exceptions, carried out by fix(corekit,utilities): raise pcapkit exceptions from EnumLookup.get, following stdlib Enum's shape #923.

Docstrings only: token streams are identical before and after with string literals masked. tests/protocols/internet/test_mh_unit.py 52 passed / 499 subtests; tests/utilities/ 121 passed.

[JarryShaw]

NEEDS CHANGES at eb00cd9 — opus cross-review. One blocking provenance error; everything else held under independent measurement.

Blocker: mh.py:584-585 and :706-707 attribute the lean to a review that did not exist yet. Both read that a ruling given in review of the work for #935 first leaned toward the widening and then reversed. I verified the provenance myself:

• the lean is comment 5901325827 on issue fix(mh): two kept get overrides advertise the base default argument and reject it with TypeError #935, 2026-09-29T23:57:26Z — given on the issue, not in any review;
• the reversal is comment 5902590532 on PR fix(protocols): widen the two kept get overrides in mh.py to accept default #940, 2026-09-30T02:00:58Z;
• fix(protocols): widen the two kept get overrides in mh.py to accept default #940's earliest comment of any kind is 2026-09-30T01:45:20Z, 1h47m48s after the lean.

So the lean predates #940 entirely and is what caused it to be opened as a widening attempt — it cannot have been given in review of it. The text also contradicts the sentence before it, which says the first attempt already widened. This pull request already carries the right form 260 lines later at :853/:932, an earlier lean on the issue; the fix is to use it at both #935 sites. It is the defect class #987 exists to remove, which is why it blocks rather than being a nit.

Non-blocking, going in with it: a dangling modifier at :853/:932 where the trailing clause can attach to either verb and only one is true; two imprecisions at exceptions.py:719-720, where "carried out by #923" sits against the #877 re-parenting that #921 actually carried out as its phase 2; and two re-wrap artefacts at mh.py:593 and :715.

Confirmed otherwise. Prose-only in all three files, and checked harder than by counts alone: masked-token sequences are byte-identical and the only six differing string tokens are each a class's or function's first statement, so no __all__ entry, format string, error message or default argument moved. Both get overrides and their type: ignore[override] suppressions really are gone. Line length unchanged. Tests reproduce exactly: 52 passed / 499 subtests, and 121 passed / 104 subtests.

Two things the pull request under-claimed and should get credit for: the old prose mislabelled the discard instruction as the ruling's option (b), which was a different cron-workflow option, and it merged two rulings 2h19m apart into one.

Also folding in a pre-existing defect in a file this already edits: vendor/__main__.py:105 cross-references Vendor._write_atomic, which exists nowhere in pcapkit/vendor/ on this branch or on main, while the same sentence says it was deleted.

The verdict carries over from 31a0adc: the update-branch merge brought main in without touching any of the three files.

[JarryShaw]

Fixed and pushed as ba49e0f94 — all four review items plus the pre-existing dangling target.

The fix author independently confirmed the provenance table before writing: the lean is comment 5901325827 on issue #935 at 23:57:26Z, the reversal is 5902590532 on the widening attempt at 02:00:58Z, and that attempt's earliest comment of any kind is 5902430148 at 01:45:20Z. The passage now reads as an earlier lean on the issue overtaken by a later ruling in review of the attempt, matching the form this file already used 260 lines further down.

The mechanical item took two rounds. The first attempt moved the raggedness rather than removing it, leaving widen them, so at 22 characters mid-sentence. It is re-flowed now at 29-76 characters, and I checked every remaining short line is forced by a following role too long to fit — line 722 is followed by a 62-character fully-qualified :class: role, where the sibling passage uses the short form and fits in the same space.

Verified by me rather than relayed: masked-token sequences identical in all three files, every differing string token is a docstring, and the AST with docstrings blanked compares equal. Maximum line length unchanged at 190 / 99 / 102. Tests reproduce: 52 passed / 499 subtests, and 121 passed / 104 subtests.

One residual imprecision I am accepting rather than papering over, with the reasoning raised on #987: "#877's phase-2 re-parenting" does not uniquely identify where the ruling was reviewed, because phase 2 has two halves — #921 covered 17 of the 24 non-registry enumerations and #930 the remaining seven, and #930's half is cited two files away. Pinning it would mean naming the pull request, which the convention forbids.

Label back to review: pending; a fresh cross-review is running against ba49e0f94.

[JarryShaw]

GOOD TO GO at ba49e0f94 — opus cross-review, round 2. No blocking finding. It also caught two errors of mine, both confirmed, so those first.

My duration figure was wrong. I said the lean predates #940's earliest comment by 1h47m48s, here and in the commit message. From 2026-09-29T23:57:26Z to 2026-09-30T01:45:20Z is 1:47:54. The conclusion is unaffected — the lean still precedes the pull request it caused — but the number as published was not the number I measured.

My "every remaining short line is token-forced" claim was overbroad. True for mh.py, where all nine changed lines are forced at the 76-column fill. False for two: vendor/__main__.py:114 joins to exactly 76 and exceptions.py:720 to 75, so both could absorb their successor. I verified one line and generalised from it — the same move I blocked #990 for an hour ago. Neither is worth a revision: absorbing -type would split the literal mid-flag, and absorbing whichever would cascade a re-wrap through an untouched paragraph to shrink a two-line diff. The defensible version of what I meant is the reviewer's: at 76 columns the re-flowed lines are better packed than the unchanged prose around them, which still has 34, 2 and 11 absorbable lines respectively.

Independently verified at this head, beyond what I had: all three token counts reproduced exactly (31432 / 1146 / 556), sequences identical, ASTs equal with docstrings blanked, and every differing string token confirmed a docstring by position. The role multiset is unchanged except the intended one-for-one _write_atomic swap, and the split literal was pushed through docutils — zero system messages, and it renders as one space across the break. The measured claims were checked by import rather than from the threads: __members__ and list(cls) really do agree at 6 and at 4, none of the seven classes mints an alias, and all seven converge on EnumValueError. Tests 173 passed / 603 subtests, matching 52+121 and 499+104.

Two residual items, neither blocking and neither in this pull request's file set to fix:

• exceptions.py:719-720 — under nearest-antecedent reading, "carried out by GitHub issue fix(corekit,utilities): raise pcapkit exceptions from EnumLookup.get, following stdlib Enum's shape #923" attaches to the re-parenting, which fix(corekit,utilities): raise pcapkit exceptions from EnumLookup.get, following stdlib Enum's shape #923 did not do. The structure is pre-existing on main, context rescues it, and fixing it would cost another full review round on a two-line diff. Folding it into docs: sweep all prose for concision and accuracy, and drop timed context outside the changelog #719's prose sweep instead.
• The same dangling _write_atomic role survives at tests/vendor/test_vendor_snapshot_restore_unit.py:14 and :58, and the method exists nowhere in the tree. tests/ is outside the Sphinx tree so it emits no warning. Fixing that separately as test-only.

Labelling review: good-to-go. Unpublished and unmerged — yours to merge.