nick2781 · Oct 26, 2026 · Oct 26, 2026 · Oct 26, 2026 · Oct 26, 2026 · Oct 26, 2026
diff --git a/docs/reference/directory-structure.md b/docs/reference/directory-structure.md
@@ -13,7 +13,7 @@ Build artifacts belong to each CMake build directory: `cmake -S . -B out/release
 | `src/core/` | Core headers, implementation and CMake usage requirements |
 | `src/application/` | Application entry point and shutdown request |
 | `src/config/` | Application manifest declarations, shared compiled file/TOML reader and private diagnostics |
-| `src/proto/` | Protocol schemas and codec implementation |
+| `src/proto/` | Protocol schemas and CMake rules for generated Protobuf messages |
 | `src/server/` | Built-in server applications |
 | `src/plugins/<name>/` | All official plugin headers, implementation and assembly |
 | `tests/` | Core, network and private database regressions |

diff --git a/docs/reference/directory-structure_CN.md b/docs/reference/directory-structure_CN.md
@@ -12,7 +12,7 @@ ark 使用 C++20。核心与官方插件放在本仓库，业务插件放在应
 | `src/core/` | 核心头文件、实现与 CMake 使用要求 |
 | `src/application/` | 应用入口与停服请求 |
 | `src/config/` | 应用清单声明、共享的文件／TOML 读取实现与私有诊断 |
-| `src/proto/` | 协议定义与编解码实现 |
+| `src/proto/` | 协议定义与 Protobuf 消息生成的 CMake 规则 |
 | `src/server/` | 内置服务端应用 |
 | `src/plugins/<name>/` | 全部官方插件头文件、实现与装配 |
 | `tests/` | 核心、网络与私有数据库回归测试 |

diff --git a/docs/reference/protobuf.md b/docs/reference/protobuf.md
@@ -1,6 +1,6 @@
 # Protobuf messages and compatibility
 
-Protocol definitions live in `src/proto/proto/`; codec implementation lives in `src/proto/codec/`. Source files, messages, fields and enum identifiers use `snake_case`. The former `AFMsg` package is now `ark.protobuf`, exposed in C++ as `ark::protobuf`. The `consul` and `osslog` packages retain their names.
+Protocol definitions live in `src/proto/proto/`. Source files, messages, fields and enum identifiers use `snake_case`. The former `AFMsg` package is now `ark.protobuf`, exposed in C++ as `ark::protobuf`. The `consul` and `osslog` packages retain their names.
 
 ## Build and include
 
@@ -16,6 +16,12 @@ Generated C++ files remain in the CMake build directory under `src/proto/generat
 
 Use Protobuf, Abseil and utf8_range from one compatible installation prefix. In a manual package selection, align `Protobuf_DIR`, `absl_DIR` and `utf8_range_DIR`; a successful link alone does not validate reflection/JSON behavior.
 
+## Message serialization
+
+Messages use the generated Protobuf API directly. The Bus module's message send paths in `src/plugins/bus/msg_module_impl.cpp` call `SerializeToString` and return `false` if serialization fails. The public `msg_module::decode_protobuf` helper in `<ark/bus/msg_module.hpp>` calls `ParseFromString` on the network message body, returning `false` on a parse failure and copying the actor ID on success. See [Bus](bus.md) for the message and transport boundary.
+
+ark does not provide a pluggable message codec API. The generated messages and these Bus helpers are the existing serialization path.
+
 ## Migration contract
 
 | Preserved | Requires consumer updates |

diff --git a/docs/reference/protobuf_CN.md b/docs/reference/protobuf_CN.md
@@ -1,6 +1,6 @@
 # Protobuf 消息与兼容边界
 
-协议定义位于 `src/proto/proto/`，编解码实现位于 `src/proto/codec/`。源码文件、消息、字段与枚举标识符采用 `snake_case`。原 `AFMsg` package 改为 `ark.protobuf`，C++ 命名空间为 `ark::protobuf`；`consul`、`osslog` 保留既有 package。
+协议定义位于 `src/proto/proto/`。源码文件、消息、字段与枚举标识符采用 `snake_case`。原 `AFMsg` package 改为 `ark.protobuf`，C++ 命名空间为 `ark::protobuf`；`consul`、`osslog` 保留既有 package。
 
 ## 构建与包含
 
@@ -16,6 +16,12 @@ target_link_libraries(my_service PRIVATE ark::core ark::proto)
 
 Protobuf、Abseil 与 utf8_range 应来自同一套兼容安装。手工选择软件包时，同步检查 `Protobuf_DIR`、`absl_DIR` 与 `utf8_range_DIR`；链接成功本身不能证明反射和 JSON 行为正确。
 
+## 消息序列化
+
+消息直接使用 Protobuf 生成的 API。Bus 模块在 `src/plugins/bus/msg_module_impl.cpp` 的消息发送流程中调用 `SerializeToString`，序列化失败时返回 `false`。`<ark/bus/msg_module.hpp>` 中的公开辅助接口 `msg_module::decode_protobuf` 对网络消息体调用 `ParseFromString`，解析失败时返回 `false`，成功时复制 actor ID。消息与传输的边界见 [Bus](bus_CN.md)。
+
+ark 不提供可替换的消息 codec API。现有序列化流程使用生成的消息与上述 Bus 辅助接口。
+
 ## 命名迁移约定
 
 | 保持不变 | 调用方需要调整 |

diff --git a/docs/reference/utility.md b/docs/reference/utility.md
@@ -76,6 +76,15 @@ tail mixing, result word order and the existing public signatures are unchanged;
 `murmur_hash3_x86_128` remains an instance method, and the other variants remain
 static. MurmurHash2 retains its fixed seed zero.
 
+The Murmur header itself uses only standard C++20 headers. It does not include
+`ark/macros.hpp` or `ark/platform.hpp`; callers using their declarations or macros
+must include those headers explicitly. Public macro definitions are unchanged.
+This header independence does not change `ark::core` or its CMake package's
+dependency requirements. `check-murmur-hash-header` compiles the logical public
+header with an isolated include directory and no SDK target dependencies; it is
+also included in `check-core`. See [core regressions](../../tests/core/README.md)
+for the standalone check commands.
+
 ### Digest compatibility and legacy access
 
 **Breaking change:** default MurmurHash3 now reads full blocks as little endian

diff --git a/docs/reference/utility_CN.md b/docs/reference/utility_CN.md
@@ -68,6 +68,12 @@ MurmurHash3 使用 C++20 `std::rotl`，旋转次数保持不变。种子、尾
 原有公开签名不变；`murmur_hash3_x86_128` 仍为实例方法，其余变体仍为静态方法。
 MurmurHash2 保留固定种子零。
 
+Murmur 头文件自身仅使用标准 C++20 头文件，不再包含 `ark/macros.hpp` 或
+`ark/platform.hpp`。调用方若使用其中的声明或宏，须显式包含对应头文件；公开宏定义
+保持不变。头文件独立性不改变 `ark::core` 或其 CMake 包的依赖要求。
+`check-murmur-hash-header` 仅通过隔离的包含目录编译逻辑公开头文件，不依赖 SDK
+目标，并纳入 `check-core`。独立检查命令见[核心回归](../../tests/core/README_CN.md)。
+
 ### 摘要兼容性与旧结果入口
 
 **不兼容变更：** 默认 MurmurHash3 现在在所有支持的平台上按小端方式读取完整块，

diff --git a/src/core/container/consistent_hash.hpp b/src/core/container/consistent_hash.hpp
@@ -23,6 +23,7 @@
 #include "ark/dep.hpp"
 #include "ark/hash/crc.hpp"
 #include "ark/hash/murmur_hash.hpp"
+#include "ark/macros.hpp"
 
 namespace ark {
 

diff --git a/src/core/hash/murmur_hash.hpp b/src/core/hash/murmur_hash.hpp
@@ -28,9 +28,6 @@
 #include <cstring>
 #include <type_traits>
 
-#include "ark/macros.hpp"
-#include "ark/platform.hpp"
-
 namespace ark {
 
 class murmur_hash
@@ -289,8 +286,8 @@ class murmur_hash
         uint64_t h1 = seed;
         uint64_t h2 = seed;
 
-        const uint64_t c1 = BIG_CONSTANT(0x87c37b91114253d5);
-        const uint64_t c2 = BIG_CONSTANT(0x4cf5ad432745937f);
+        const uint64_t c1 = 0x87c37b91114253d5ULL;
+        const uint64_t c2 = 0x4cf5ad432745937fULL;
 
         //----------
         // body
@@ -492,9 +489,9 @@ class murmur_hash
 
     static uint64_t fmix(uint64_t k) {
         k ^= k >> 33;
-        k *= BIG_CONSTANT(0xff51afd7ed558ccd);
+        k *= 0xff51afd7ed558ccdULL;
         k ^= k >> 33;
-        k *= BIG_CONSTANT(0xc4ceb9fe1a85ec53);
+        k *= 0xc4ceb9fe1a85ec53ULL;
         k ^= k >> 33;
 
         return k;

diff --git a/src/proto/codec/codec.hpp b/src/proto/codec/codec.hpp
diff --git a/src/proto/codec/protobuf_codec.cpp b/src/proto/codec/protobuf_codec.cpp
diff --git a/src/proto/codec/protobuf_codec.hpp b/src/proto/codec/protobuf_codec.hpp
diff --git a/tests/core/CMakeLists.txt b/tests/core/CMakeLists.txt
@@ -4,11 +4,13 @@ add_library(ark_core_header_checks OBJECT headers/queue.cpp headers/guid128.cpp
     headers/object_vector.cpp headers/error_code.cpp headers/logger.cpp headers/murmur_hash.cpp)
 target_link_libraries(ark_core_header_checks PRIVATE ark::core)
 
+add_subdirectory(hash_header)
+
 add_executable(ark_core_tests main.cpp strings.cpp containers.cpp templates.cpp callbacks.cpp
     header_regressions.cpp cxx20_language.cpp concurrency.cpp plugin_manager_startup.cpp data_strings.cpp node_data_storage.cpp
     object_vectors.cpp plugin_construction.cpp module_factory.cpp random_generator.cpp xxtea.cpp murmur_hash.cpp)
 target_link_libraries(ark_core_tests PRIVATE ark::core ark::kernel ark::utility)
-add_dependencies(ark_core_tests ark_core_header_checks)
+add_dependencies(ark_core_tests ark_core_header_checks ark_murmur_hash_standalone_check)
 add_library(ark_construction_header_checks OBJECT headers/module_base.cpp headers/plugin_base.cpp)
 set_property(TARGET ark_construction_header_checks PROPERTY LINK_LIBRARIES ark::core)
 add_dependencies(ark_core_tests ark_construction_header_checks)

diff --git a/tests/core/README.md b/tests/core/README.md
@@ -30,6 +30,19 @@ See [Murmur compatibility](../../docs/reference/utility.md#core-murmur-hashes)
 for canonical little-endian output and the explicit legacy MSVC migration path. AddressSanitizer and
 UndefinedBehaviorSanitizer builds exercise overread and alignment checks.
 
+The existing mapped public-header check remains. An additional compile-only check
+stages just `<ark/hash/murmur_hash.hpp>` and uses C++20 without project, platform,
+spdlog or Boost include paths or SDK target dependencies. It is part of
+`check-core` and can also run without configuring the full dependency graph:
+
+```sh
+cmake -S tests/core/hash_header -B hash-header-build -G Ninja
+cmake --build hash-header-build --target check-murmur-hash-header
+```
+
+Header independence does not remove the dependencies required by `ark::core` or
+its CMake package.
+
 With `ARK_BUILD_PROTO=ON`, additional cases verify Protobuf parse failures, actor
 identity, binary messages, legacy wire payloads and external JSON field names.
 They also exercise the new `ark::protobuf` descriptor and enum names.

diff --git a/tests/core/README_CN.md b/tests/core/README_CN.md
@@ -27,6 +27,17 @@ Murmur 回归包含独立的上游 SMHasher 验证常量、旧版完整块交换
 [Murmur 兼容性说明](../../docs/reference/utility_CN.md#core-murmur-哈希)。
 AddressSanitizer 和 UndefinedBehaviorSanitizer 构建可检查越界读取和无效对齐。
 
+现有公开头映射检查继续保留。新增的纯编译检查仅映射 `<ark/hash/murmur_hash.hpp>`，
+使用 C++20，不引入项目、平台、spdlog 或 Boost 包含路径，也不依赖 SDK 目标。
+该检查纳入 `check-core`，也可独立运行，无需配置完整依赖图：
+
+```sh
+cmake -S tests/core/hash_header -B hash-header-build -G Ninja
+cmake --build hash-header-build --target check-murmur-hash-header
+```
+
+头文件独立性不改变 `ark::core` 或其 CMake 包所需的依赖。
+
 公共头检查将 `<ark/error_code.hpp>` 放在首个包含位置，并重复包含两次；编译期断言
 验证其无符号 32 位底层类型及所有已声明的错误值。
 

diff --git a/tests/core/hash_header/CMakeLists.txt b/tests/core/hash_header/CMakeLists.txt
@@ -0,0 +1,16 @@
+cmake_minimum_required(VERSION 3.21)
+project(ark_murmur_hash_header_check LANGUAGES CXX)
+
+# Only this logical public header is available; no project or third-party SDK.
+set(hash_include_dir "${CMAKE_CURRENT_BINARY_DIR}/include")
+configure_file("${CMAKE_CURRENT_LIST_DIR}/../../../src/core/hash/murmur_hash.hpp"
+    "${hash_include_dir}/ark/hash/murmur_hash.hpp" COPYONLY)
+add_library(ark_murmur_hash_standalone_check OBJECT ../headers/murmur_hash.cpp)
+# Drop the parent project's directory-wide ark::ark link and include paths.
+set_target_properties(ark_murmur_hash_standalone_check PROPERTIES
+    LINK_LIBRARIES ""
+    INCLUDE_DIRECTORIES "${hash_include_dir}"
+    CXX_STANDARD 20
+    CXX_STANDARD_REQUIRED ON
+    CXX_EXTENSIONS OFF)
+add_custom_target(check-murmur-hash-header DEPENDS ark_murmur_hash_standalone_check)