refactor(corekit)!: move decorators into corekit (#1735)

[JarryShaw]

Please follow the guide below

• You will be asked some questions, please read them carefully and answer honestly

• Put an x into all the boxes [ ] relevant to your pull request (like that [x])

• Use Preview tab to see how your pull request will actually look like

• 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. Narrow runs only, listed below.

• Added a changelog entry under docs/source/changelog/ and regenerated CHANGELOG.md, if the change is user-visible: 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?

Tick the commit type your subject line carries.

• fix — corrects a defect
• feat — adds a feature
• perf — changes performance, not behaviour
• refactor — changes neither behaviour nor performance
• test — tests only
• docs — documentation only
• ci — workflows or build tooling
• release — bumps the version or rolls up a distribution
• chore — anything else

---

Closes #1735. This applies option A from #1712: utilities holds services that import nothing from pcapkit outside utilities. It follows the no-re-export rule from #1715.

• Move. pcapkit/utilities/decorators.py is now pcapkit/corekit/decorators.py. protocol.py, internet.py, ipv6.py and schema.py import from the new path, and so do the docs, tests and examples.
• Breaking.
  • Importing pcapkit.utilities.decorators now raises ModuleNotFoundError.
  • seekset, beholder and prepare are no longer available from pcapkit.utilities.
  • The logger is now named pcapkit.corekit.decorators.
• Rule. A new conventions page, utilities-or-corekit, states the rule. tests/project/test_utilities_import_boundary_1735_unit.py parses every module under pcapkit/utilities/ and fails on any import from elsewhere in pcapkit, whether at top level, inside a function or under TYPE_CHECKING.
• Tests.
  • On origin/main the new tests give 5 failed, 3 passed; the guard flags decorators.py:28,29,130,132.
  • The touched suites pass on 3.8, 3.10, 3.11 and 3.14.
  • Sphinx warnings are unchanged at 63.
  • test_decorators.py moves to tests/corekit, which is not a plain-unittest leg; this follows the refactor(corekit)!: move the byte-order field helpers into corekit (#1711) #1715 precedent.

[JarryShaw]

Verdict: GOOD TO GO at 8cd589ed2. A Sonnet cross-review checked it (author: Opus).

• No reference to the old path remains outside the migration note and the two new tests. utilities/__init__.py re-exports nothing.
• Imports have no cycle: I imported 14 modules first in fresh interpreters, 28 runs across 3.14 and 3.8.
• The guard fails on origin/main at exactly decorators.py:28,29,130,132. A module I planted under pcapkit/utilities/ was flagged for a TYPE_CHECKING import, a function-level import, a relative import, and an importlib literal.
• Sphinx shows 63 warnings on both trees, and the two warning sets are identical.
• My own re-run, in the PR's tree: 44 passed, 476 subtests passed across the two new tests, test_decorators, test_public_api and test_all_exports_unit.
• Non-blocking: one line on the new conventions page is not wrapped to match its neighbours, and the toctree order differs from the preamble's.

[github-actions]

Coverage: 89.65% (unit tier, Python 3.15, 8cd589ed2, Unit Tests run success)

Package	Statements	Missed	Branches	Partial	Cover
pcapkit (top level)	104	3	20	3	95.16%
pcapkit/const	18860	954	2368	868	91.06%
pcapkit/corekit	2455	69	780	35	96.54%
pcapkit/dumpkit	275	3	100	3	98.40%
pcapkit/foundation	2885	144	1010	34	94.20%
pcapkit/interface	138	7	52	5	93.68%
pcapkit/protocols	17172	225	4588	189	98.08%
pcapkit/toolkit	1015	173	372	10	80.89%
pcapkit/utilities	436	2	140	4	98.96%
pcapkit/vendor	4417	2342	1010	157	43.38%

Per-file detail: the coverage-html artifact of this run.