refactor(protocols): align ProtocolBase.__registry__ handling and entry layout with the other registry maps

What
Owner questions after #2770: does ProtocolBase.__registry__ follow the handling the other registry maps use (lock, read-only copy, register_protocol checks)? And should its built-in entries be grouped by layer? Audit at 3c4b30e2b, read-only, with key claims re-checked by me:

Matches the other maps:
- _shipped_registry is a MappingProxyType(dict(...)) snapshot, built the same way as the Extraction/TraceFlow _shipped_* maps, and used for the same restore.
- register_protocol raises the same RegistryError type checks as register, the wrapper also validates (as registry-protocol.rst has both sides do), and both return None.
- The clash warning is a RegistryWarning in the same shape.
- The docs (#:, Warns:, the # NOTE: tag) match.
Differs:
1. Lock: _registry_lock is the first lock on any registry map. It serialises only get_protocol's first resolution (refactor(protocols)!: replace the pcapkit.protocols.__proto__ dict with an auto-registering Registry class #2763, an import deadlock). register_protocol, the __init_subclass__ setdefault and _release_name all write without it, as every other map does.
2. Restore path: _release_name (foundation.registry.protocols) writes lease.displaced straight into the map instead of going through register_protocol.
3. Descriptors: register_protocol takes a class only, where register/register_option also take a ModuleDescriptor. This follows from registering a class by its own name.
4. Keys: keys are upper-case, inherited from the old __proto__ dict, while the other string-keyed maps use lower-case.
Layer grouping: no registry dict in the tree uses layer comments; only protocols/__init__.py's __all__ does. protocol-member-order.rst orders maps "alphabetically by key where there is no enum". The guard does not check __registry__ (it skips string-keyed dunder maps).

Decision needed.

Lock scope:
- (a) Keep it as is: resolution only, and writes stay unlocked like every other map.
- (b) Widen it to cover every write.
- (c) Drop it once fix(utilities): concurrent first access to lazy protocol exports deadlocks the import system #2771 serialises first resolution in lazy_exports, which removes the deadlock it guards against.
Rec: (c) once fix(utilities): concurrent first access to lazy protocol exports deadlocks the import system #2771 lands, otherwise (a). A single lock in the shared lazy-import helper is the established place, and no other map locks.
Restore path:
- (a) Keep _release_name's direct write, which restores exactly what was displaced.
- (b) Route it through register_protocol.
Rec: (a), with a one-line comment saying why.
Grouping by layer:
- (A) Keep sorting by key: it follows the page, and each entry's module path already shows its layer.
- (B) Group by layer (# Link Layer, …, # Miscellaneous for Frame/Header/IP_Pseudo/NoPayload), alphabetical within each group, and amend the page in one sentence.
- (C) Group without any order rule.
Rec: (A). If you prefer (B), it is a comment-only edit plus the page amendment. (C) would drift unguarded.
Guard gap: the member-order guard doesn't check string-keyed maps, so "alphabetically by key" is unenforced. Rec: extend the guard as part of whichever option you choose for 3.

take (c); and i dont think we used this in other registry mappings. so maybe over engineering.
take the path other registry mappings taken. it's not necessary to preserve. also maybe over engineering.
take (B)
yes

Reconciled. Every answer is now settled.

(c): the registry lock goes. No other registry map uses one, and fix(utilities): concurrent first access to lazy protocol exports deadlocks the import system #2771's fix covers the import deadlock it guarded against. _registry_lock and its use in get_protocol are removed in fix(utilities): concurrent first access to lazy protocol exports deadlocks the import system #2771's PR, once its shared lazy_exports lock is in place.
Restore follows the other maps. _release_name restores through the same path the other registry maps' restores use, and there is no need to bring back exactly the displaced object. The special-casing goes.
(B): entries grouped by layer. __registry__'s built-in entries get layer comments (# Link Layer, # Internet Layer, # Transport Layer, # Application Layer, # Miscellaneous), alphabetical within each group. protocol-member-order.rst gets a one-sentence amendment.
Yes: the guard checks string-keyed maps. That covers the alphabetical rule, and for __registry__ it is applied group by group.

Items 2–4 go in one PR together with #2772, because both edit protocol-member-order.rst and the member-order guard. Item 1 goes in #2771's PR. Each PR is marked "Part of #2773", and this issue closes when both have merged.

docs(registry): plain-sentence _release_name docstring; pin the name …

docs(conventions): settle the member-order page wording and align the…

fix(utilities): serialise first resolution of lazy exports and module…

Both parts have landed, so this is closed. #2779 covered items 2–4: the restore path, the layer grouping, and the guard for string-keyed maps. #2781 covered item 1, removing _registry_lock now that the shared import_lock guards first resolution.

Navigation Menu

refactor(protocols): align ProtocolBase.registry handling and entry layout with the other registry maps #2773

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

refactor(protocols): align ProtocolBase.__registry__ handling and entry layout with the other registry maps #2773

Description

Activity

JarryShaw commented on Nov 4, 2026

JarryShaw commented on Nov 4, 2026

JarryShaw commented on Nov 4, 2026

JarryShaw commented on Nov 4, 2026

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions

refactor(protocols): align ProtocolBase.registry handling and entry layout with the other registry maps #2773