docs: harvest every settled design ruling into the convention docs, and split them per category

[JarryShaw]

Filed on the owner's ask. Verbatim, in two parts:

Another ask, sweep all closed or open issues and PRs and find those cases where we made a design decision to become a house convention. Those items should be documented to the Sphinx docs - and like I mentioned in #913, as there are more conventions settled, we might consider splitting the convention doc into multiple files under a folder, instead of one giant file for all.

And any future conventions to be settled - document them as well.

Why this is its own issue rather than part of #719

#719 is the prose concision-and-accuracy sweep and is held to merge last with #657. This is a different job — harvesting rulings out of issue history and turning them into reference documentation — and it should not wait on the changelog.

Part 1: harvest the settled conventions

Sweep every closed and open issue and PR for a design decision that has become a house rule, and record each in docs/source/contributing/conventions/. The bar is the one the existing page already sets: a ruling that is not derivable from the code, that a future maintainer or automated contributor would otherwise rediscover by reading a closed thread. Each entry names where it was settled and quotes the maintainer.

Known already-documented, for calibration — these are the shape to match, not the scope:

• the mint-versus-unmint criterion (fix(ipx): order Socket._missing_ range branches narrowest-first #847, Registries mint a permanent member for every unrecognised value: 1,169 extend_enum sites across 113 registries #775)
• <SENTINEL>Type naming, and why the instance casing is deliberately free (fix(corekit): export only the sentinel objects, not their types #911)
• where the registry protocol lives, and the two-limb case-sensitivity test (const: generalise register_alias from AppType to every pcapkit.const enum #842, test(const): audit every registry case sensitivity against its source specification #903)

Candidates visible from this session's threads, each to be verified against its own thread before being written down: ESP double-inheriting because IANA marks it an extension header (#891); one commit per changelog entry as an audit trail (#657); breaking meaning a pack-path or public-contract change; every open issue carrying wip/blocked/needs: decision; the @classmethod requirement for any get override that delegates to the base (#908, #915); all meaning core addons only (#910). That list is a starting set, not the answer — the sweep is the work.

Part 2: split the convention doc

docs/source/contributing/conventions.rst is ~440 lines carrying three unrelated rulings, so a reader wanting the sentinel rule reads past two hundred lines on enum minting. Split it into one file per existing .. _label: anchor, which already marks the natural seams:

docs/source/contributing/conventions/index.rst          toctree + the .. important:: preamble
                                     mint-criterion.rst
                                     sentinel-convention.rst
                                     registry-protocol.rst

Every existing :ref: and :doc: target must keep resolving — the anchors are referenced from tests/ and from pcapkit/ docstrings, so a move that breaks them is a regression even though Sphinx will not fail the build without -W.

Part 3: a standing rule, going forward

And any future conventions to be settled - document them as well.

Recorded as an ongoing obligation, not a one-off: when a ruling settles a question that is not derivable from the code, it gets written into the convention docs in the same change that implements it — not left in the issue thread.

Sequencing

Part 2 conflicts with any open PR touching conventions.rst. #913 and #916 both do and are awaiting merge, so the split waits for both. Part 1's harvest can begin immediately, since it is research rather than edits.

gh pr view 913 -R JarryShaw/PyPCAPKit --json state -q .state
gh pr view 916 -R JarryShaw/PyPCAPKit --json state -q .state

[JarryShaw]

Blocked on #911, and the blocker is checkable. This issue has two halves and both want docs/source/contributing/conventions.rst, which is being rewritten right now.

The harvest half — sweeping closed and open issues and PRs for design decisions that became house conventions — can be researched at any time, but it lands as new sections in that same file. The split half cannot start until the file stops moving.

#911 is the blocker: the sentinel housing move rewrites the "Naming a sentinel" section of conventions.rst to describe one module for all four sentinels rather than four separate homes, per the ruling "Okay one module for all four it is." Starting here now would mean two edits to one file with no way to reconcile them except by hand.

Unblocks when #911 merges. #919 is a second, smaller claim on the file's neighbourhood — it adds docs/source/pcapkit/corekit/enum.rst and fixes five stale :file: references to this file's pre-move path — so the clean start point is after both.

[JarryShaw]

Unblocked — #911 merged as c7342cac1. docs/source/contributing/conventions.rst is no longer held by an open PR, so both halves of this issue can start.

Three rulings settled today belong in the harvest, quoted as given:

1. On sentinel housing — "Okay one module for all four it is."
2. On extension-header subclassing — "if the IPv6 extension header is only usable as an extension header, then it only inherit from IPv6_Ext, like IPv6_Frag; but if it is useable as a standalone protocol itself, then it herit from both IPv6_Ext and Internet (or IPsec), like ESP."
3. On enum exception provenance — "Either ValueError or KeyError, that's depending on how stdlib's Enum would raise on these circumstances. And we should raise one from pcapkit.utilities.exceptions rather builtin exceptions."

The second is the one that most needs writing down, because it took an RFC census to apply and the classification is not derivable from the code: IPv4.__proto__ is Internet.__proto__ is True, so every extension header is reachable as an IPv4 payload in this library's dispatch, which makes the registry useless as evidence. The operative test is whether the RFCs put the header under IPv4 — and on that, AH, ESP and HIP qualify while MH and Shim6 do not. That reasoning is currently only in #924's comments and in a #: comment on STANDALONE_MEMBERS.

The third is not yet implemented — it is #923 — so record it as a settled direction rather than as current behaviour.

Removing blocked.

[JarryShaw]

Blocked on #923, which is now in flight. Both halves of this issue want docs/source/contributing/conventions.rst, and #923 changes the exception contract its registry-protocol section documents.

I told #923's worker explicitly not to touch that file and to report what needs changing there instead, so the prose change lands here with the full picture rather than being split across two PRs that would then conflict on it — which is exactly what happened between #919 and #922 earlier today.

Unblocks when #923's PR merges. The three rulings to harvest are recorded in the comment above and do not change.

[JarryShaw]

Unblocked — #923 closed and #927 merged as 4f3d43df7. docs/source/contributing/conventions.rst is no longer held by an open PR, so both halves of this issue can start.

Verified on the merged tree: EnumKeyError derives KeyError, Criticality.get is gone, TransportProtocol.get('TCP') still resolves, and a name miss is caught as a plain KeyError while being an EnumKeyError.

What #927 deliberately left for this issue, quoted from its own hand-back so it is not rediscovered:

• Line 628 — FEATCode.get('ZZ-NOT-REAL') is documented as raising :exc:KeyError``; it should name EnumKeyError.
• Lines 348-355 — the _validate_value bullet should add that with no usable default the rejection propagates unwrapped, so an override's own message survives and logs once.
• The two-tier section should record that get raises EnumKeyError / EnumValueError from pcapkit.utilities.exceptions while keeping stdlib's shape — name miss KeyError-derived, value miss ValueError-derived.
• The "Case Sensitivity" section should note TransportProtocol.get is now only a case-folding override, and Criticality.get no longer exists.
• Lines 362-368 — the .. note:: claiming design: should the non-registry helper enums share a lookup interface, or be made strictly immutable? #877 phase 2 "has not happened yet" is stale from fix(corekit): reparent the unblocked non-registry enums onto EnumLookup (#877) #921.

Five settled rulings to harvest, verbatim, the last two new since this issue was filed:

1. "Okay one module for all four it is." — sentinel housing.
2. "if the IPv6 extension header is only usable as an extension header, then it only inherit from IPv6_Ext, like IPv6_Frag; but if it is useable as a standalone protocol itself, then it herit from both IPv6_Ext and Internet (or IPsec), like ESP."
3. "Either ValueError or KeyError, that's depending on how stdlib's Enum would raise on these circumstances. And we should raise one from pcapkit.utilities.exceptions rather builtin exceptions."
4. "No more IPv6_GenericExt name. Its an intermediate state and never released."
5. ESP is an extension header per IANA, yet cannot short-circuit — :rfc:4303 puts its Next Header inside the encrypted trailer, so the chain walk cannot continue past it. Settled on fix(esp): the extension= keyword is accepted, stored and never read #895; the reason is already written at pcapkit/protocols/internet/ipv6.py:90-100.

Number 2 is the one that most needs writing down, because applying it took an RFC census and the classification is not derivable from the code: IPv4.__proto__ is Internet.__proto__ is True, so every extension header is IPv4-reachable in this library's dispatch, which makes the registry useless as evidence. Removing blocked, dispatching.

[JarryShaw]

Half 1 landed — #929 merged as af2324522. The five settled rulings are harvested and the five stale passages corrected; docs/source/contributing/conventions.rst went 639 → 942 lines, with tests/project/test_conventions_doc_claims.py pinning the factual claims against runtime introspection rather than against the page's own prose.

Half 2 — the split — stays open, with a concrete blocker rather than a preference. tests/corekit/test_sentinel_exports_unit.py slices the page by text.index('.. _sentinel-convention:') → text.index('.. _registry-protocol:', start). Separating those two anchors into different files raises ValueError — not a wrong answer, an exception. A split additionally wants the index.rst toctree entry and seven prose citations of the path updated.

So it is a pure-move commit with a test change, and it should be reviewable as exactly that. Landing it underneath +300 lines of new prose would have made both unreviewable, which is why #929 correctly declined it.

One thing #929 did do: retitled the page Registry Conventions → House Conventions, because it now carries a protocol-class ruling and the old preamble — "design rulings for pcapkit.const" — had become false. No anchor moved.

Correcting my own earlier comment on this issue, since it is second-hand and was wrong in three places: the #877 phase-2 note was wrong in both directions rather than merely stale (#921 landed 17 of 24, seven remained, now tracked as #930); "Criticality.get no longer exists" is true of the method but the class is alive at pcapkit/protocols/application/ngap.py:218; and Shim6 has no class in this tree at all, so the extension-header family is eight, not nine. Ruling 1 was also already documented at :162-169 since #922 and needed no harvesting.

Leaving open for the split. Removing wip — no PR covers the remainder.

[JarryShaw]

Blocked on #930 — and this one is my doing, so worth stating.

When #929 merged I removed wip from this issue, which left it with no state label. The split half is not idle, though: it is blocked, on file contention I created myself.

docs/source/contributing/conventions.rst is being edited right now by #930's work. #929 landed prose at :392, :401 and :680 stating that seven enumerations remain outside EnumLookup, plus two tests in tests/project/test_conventions_doc_claims.py that derive that count from a live pkgutil.walk_packages and regex-match the numeral out of the page. #930 re-parents exactly those seven, so the walk will return zero while the page still says seven — the test fails on main, for the right reason. I have asked #930 to fold the page update into the same commit rather than leave main broken between merges.

So the split cannot start until that settles. Two PRs rewriting the same 942-line page, one moving anchors between files and the other correcting figures inside them, is the collision #919 × #922 already taught me to avoid.

Unblocks when #930 merges. The blocker for the split itself is unchanged and still the real constraint: tests/corekit/test_sentinel_exports_unit.py slices this page by text.index('.. _sentinel-convention:') → text.index('.. _registry-protocol:', start), so separating those two anchors raises ValueError. The split is a pure-move commit plus that test change, and it should be reviewable as exactly that.