docs(contributing): record the const-vendor pairing ruling

Author: JarryShaw

docs/source/contributing/conventions/const-vendor-pairing.rst

@@ -0,0 +1,33 @@
+.. _const-vendor-pairing:
+
+Const-Vendor Pairing
+---------------------
+
+**Every module under** :mod:`pcapkit.const` **is generated by a matching crawler
+under** :mod:`pcapkit.vendor`. A registry copied from an IANA, IETF or similar
+web-published table is never hand-maintained -- the crawler re-scrapes the source and
+regenerates the module, so a hand edit to the generated file is silently discarded on
+the next run. :issue:`2441`, raised in cross-review and knowingly deferred rather than
+fixed.
+
+The Exception
+~~~~~~~~~~~~~
+
+**A source that is not a web-crawlable table is the one legitimate reason to hand-write
+a const module.** :class:`~pcapkit.const.linux.arphrd.ARPHRD`'s source is the Linux
+kernel header ``<linux/if_arp.h>``, not an IANA page, and its docstring says so plainly
+-- *"Only the values that pcapkit names are listed"* -- rather than claiming full
+coverage from a registry :mod:`pcapkit.vendor` could crawl. The ``EnumRegistry`` shape
+it was moved to on :pr:`2443` is a structural decision for API uniformity with every
+other registry, not a claim that a crawler produces the file.
+
+Known Violation
+~~~~~~~~~~~~~~~
+
+:class:`~pcapkit.const.tls.content_type.ContentType` and
+:class:`~pcapkit.const.tls.handshake_type.HandshakeType` (:pr:`2441`) both cite a live
+IANA registry and claim to name every value IANA assigns, with no
+:mod:`pcapkit.vendor` crawler behind either one -- no ``pcapkit/vendor/tls/``
+directory exists, and neither class appears in :data:`pcapkit.vendor.__all__`. This
+was flagged in that PR's own review and merged anyway on the stated reasoning that the
+crawler would follow later. Tracked as :issue:`2495`.

docs/source/contributing/conventions/index.rst

@@ -27,7 +27,9 @@ House Conventions
      :mod:`pcapkit.corekit` a support module belongs in;
    * :ref:`reassembly-integration` -- :mod:`pcapkit.foundation.reassembly` and what a
      new engine there needs from :mod:`pcapkit.toolkit` and
-     :mod:`pcapkit.foundation.analysis`.
+     :mod:`pcapkit.foundation.analysis`;
+   * :ref:`const-vendor-pairing` -- :mod:`pcapkit.const` and the
+     :mod:`pcapkit.vendor` crawler each module needs.
 
    **A ruling that stays in its thread is a ruling that gets rediscovered.** So
    when a question is answered in a way the code cannot express on its own -- a
@@ -52,3 +54,4 @@ House Conventions
    test-coverage
    utilities-or-corekit
    reassembly-integration
+   const-vendor-pairing

tests/project/test_conventions_doc_claims.py

@@ -121,6 +121,7 @@
     'test-coverage',
     'utilities-or-corekit',
     'reassembly-integration',
+    'const-vendor-pairing',
 )
 
 #: Each anchor's own file, one-to-one -- there is no shared page to slice between