design: #514 recorded two rulings it never implemented — the Base/public collapse and the enforcing @final

[JarryShaw]

#514 closed with "nothing added" — the maintainer ruled the custom-versus-builtin registration check is not wanted. But two substantial rulings were recorded on it before it closed, neither implemented and neither tracked anywhere now that it is shut. This issue exists so they are not lost.

(b) Collapse each XXXBase/public pair, and make name-registration opt-in by keyword. Five pairs: Protocol/ProtocolBase, Engine/EngineBase, Reassembly/ReassemblyBase, TraceFlow/TraceFlowBase, and the Schema pair. Blast radius measured on #514: ≈390 edit points, five PRs. Three hazards no issubclass sweep finds, all verified there:

• tests/test_base_class_contract.py:75-80 imports both halves of all five pairs, so it does not fail — it fails to import. A rewrite or a deletion, and it is the one file every family touches.
• tests/_support.py:337 defines a fake class ProtocolBase and injects it into sys.modules['pcapkit.protocols.protocol'] at :354, consumed via protochain.py:72,158. Rename the real one and the fake stops being found; tests/test_support_helpers.py:413 then AttributeErrors.
• The split is today a runtime-enforced final substitute: ProtocolBase.__init_subclass__ rejects the registration keyword, so a library-style subclass cannot opt in at all. Collapsing to one class downgrades that guarantee to "do not pass the keyword".

The enforcing @final. Recorded ruling: subclassing a FINAL class raises rather than warns, in Info.__init_subclass__ (corekit/infoclass.py:244) and Schema.__init_subclass__ (protocols/schema/schema.py:1065); re-decorating an already-FINAL class raises too. Key it on __finalised__ == FINAL in the class's own __dict__, not a new flag — getattr is wrong because typing.final's __final__ inherits, so every descendant reads final. Measured additive: Info 486 descendants / 453 FINAL / 0 subclassed; Schema 445 / 408 / 0.

These are one decision, not two. (b) is safe with the runtime @final and lossy without it, because the @final is what replaces the guarantee the collapse removes.

Also blocks #682 — the registry is keyed on __name__.upper() (foundation/registry/protocols.py:219), so a user class named HTTP still displaces the built-in, and two distinct HTTP classes are already live in the ProtocolBase descendant tree. Opt-in-by-keyword registration makes that displacement explicit instead of automatic, which is the cheapest available fix for #682.

Needed from the maintainer

Did closing #514 with "nothing added" drop (b) and the @final enforcement as well, or only the custom-versus-builtin check? The rulings above read as decided in principle, but they were recorded on an issue that then closed with nothing added, so I will not start ≈390 edit points on that reading. One of:

1. Both still wanted — I sequence them together as one programme, five PRs, @final first so the collapse is not lossy.
2. @final enforcement only — cheap, additive, 0 in-tree breakage, and it does not touch the public API. register_protocol's key space is still not unique: the three HTTP classes share one key (follow-up to #675) #682 then stays open on its own merits.
3. Both dropped — I close this and register_protocol's key space is still not unique: the three HTTP classes share one key (follow-up to #675) #682 records the __name__.upper() displacement as accepted residual risk.

Nothing else is blocked on the answer, so this is a quiet hold rather than a stall.

[JarryShaw]

All is still wanted. And the custom/builtin check part has been moved to the @final implementation i believe.

[JarryShaw]

Recorded, in your words: "All is still wanted. And the custom/builtin check part has been moved to the @final implementation i believe."

So this is option 1: both the enforcing @final and ruling (b)'s XXXBase/public collapse, sequenced as one programme with the @final first — (b) is lossy without it, since the runtime guarantee it removes is the thing the @final replaces. Taking needs: decision off and starting on the @final half, which is the additive one: Info 486 descendants / 453 FINAL / 0 subclassed, Schema 445 / 408 / 0.

One scope caveat on the second sentence, measured rather than assumed. The @final machinery is FinalisedState and __finalised__ in pcapkit/corekit/infoclass.py:34,225 (with info_final's existing warn at :67 and the BASE/FINAL assignments at :137,140) plus the Schema hook — it governs Info/Schema subclassing and re-decoration. #682's defect is a different mechanism: pcapkit/foundation/registry/protocols.py:219 keys the protocol registry on protocol.__name__.upper(), so a user class named HTTP displaces the built-in. That path is not a FINAL-subclass violation and the @final hooks never see it; :217 already raises RegistryError for a non-ProtocolBase argument, which is the only custom-versus-builtin gate there today.

So #682 stays blocked on (b)'s opt-in-by-keyword registration, not on the @final. If you meant the @final to subsume #682 as well, say so and I will look again at how — but on the current code I cannot see the connection, and I would rather flag that than quietly treat #682 as covered.

Next: a worker on the @final enforcement, keyed on __finalised__ == FINAL in the class's own __dict__ (not getattr, since typing.final's __final__ inherits and would read final on every descendant), raising from pcapkit.utilities.exceptions. (b)'s ≈390 edit points follow in five PRs once that lands.

[JarryShaw]

the @final we discussed was to check typing.final's added final dunder value in __init_subclass and to raise when subclassing the @final class - turning it from a pure typing guard into a runtime guard.

[JarryShaw]

Recorded, in your words: "the @final we discussed was to check typing.final's added __final__ dunder value in __init_subclass and to raise when subclassing the @final class - turning it from a pure typing guard into a runtime guard."

That corrects me, and I have re-briefed the worker. I had it keying on __finalised__ == FinalisedState.FINAL — following #514's recorded note that a new __final__ flag would duplicate FinalisedState — when the mechanism you want is typing.final's own dunder. Withdrawn.

Verified on fe80b8525, and the wiring is already there: pcapkit/corekit/infoclass.py:17 imports final from typing and info_final ends return final(cls) at :142; pcapkit/protocols/schema/schema.py:9 imports it and schema_final ends return final(cls) at :132. So every finalised class already carries __final__ = True. And grep -rn '__final__' pcapkit/ finds nothing — the dunder is set and never read, which is exactly the "pure typing guard" you are describing. Its only appearance anywhere is tests/protocols/test_construction_keyword_check_unit.py:761-764, which asserts it and documents the inheritance caveat.

So the change is small and additive: read __final__ from each base's own __dict__ in Info.__init_subclass__ and Schema.__init_subclass__, and raise from pcapkit.utilities.exceptions. Own-dict matters because typing.final sets an ordinary class attribute, so getattr(B, '__final__') is True for class B(A) with A final — a getattr check would reject every legitimate subclass in the tree.

One open sub-question the worker will answer with a test rather than a guess: __bases__ versus walking the MRO, which differ for a diamond and for a subclass-of-a-subclass. It will say which it chose and why.

Still standing from my earlier comment, and not addressed by this one: I do not see how the @final runtime guard reaches #682, whose defect is protocol.__name__.upper() keying at pcapkit/foundation/registry/protocols.py:219 — a user class named HTTP displacing the built-in is not a subclassing event, so __init_subclass__ never fires for it. #682 stays blocked on (b)'s opt-in-by-keyword registration unless you tell me otherwise.