meta: add Genesis namespace alias bridge

Author: 129s

docs/architecture/proposals/meta/namespace-strategy.md

@@ -1,11 +1,24 @@
 # Proposal · 命名空间统一方案（2025-10）
-
-> 目标：明确 GenesisEngine 代码库的命名空间标准，为后续逐步迁移提供依据。
-
-## 现状与问题
-- 核心模块沿用小写 `genesis::core / genesis::worldgen / Genesis::Runtime`，Sandbox GUI 也已调整为 `genesis::sandbox::gui`，而 Style 子系统仍保持首字母大写的 `Genesis::Style`，不同约定并存。
-- 调用方在不同模块间切换时需要频繁添加双重 `namespace` 别名，降低可读性并增加出错概率。
-- 文档与示例代码在引用命名空间时缺乏一致标准，阻碍团队对外输出和未来重构。
+
+> 目标：明确 GenesisEngine 代码库的命名空间标准，为后续逐步迁移提供依据。
+
+## 已落地（Phase 1：过渡别名）
+当前仓库已加入 **namespace alias 过渡层**，以便新代码/工具可以统一使用 `Genesis::` 写法，同时保持 ABI 与实现命名空间不变：
+- 头文件：`include/genesis/NamespaceAliases.hpp`
+- 约定：仅引入 alias，不进行 `namespace genesis::x` → `namespace Genesis::X` 的破坏性重命名。
+
+示例：
+```cpp
+#include "genesis/NamespaceAliases.hpp"
+#include "genesis/agents/Needs.hpp"
+
+Genesis::Agents::NeedType t = Genesis::Agents::NeedType::Hunger;
+```
+
+## 现状与问题
+- 核心模块沿用小写 `genesis::core / genesis::worldgen / Genesis::Runtime`，Sandbox GUI 也已调整为 `genesis::sandbox::gui`，而 Style 子系统仍保持首字母大写的 `Genesis::Style`，不同约定并存。
+- 调用方在不同模块间切换时需要频繁添加双重 `namespace` 别名，降低可读性并增加出错概率。
+- 文档与示例代码在引用命名空间时缺乏一致标准，阻碍团队对外输出和未来重构。
 
 ## 统一规范
 - 采用首字母大写的 `Genesis::` 作为唯一根命名空间。

include/genesis/NamespaceAliases.hpp

@@ -0,0 +1,35 @@
+#pragma once
+
+// 目的：为后续逐步迁移到 `Genesis::` 根命名空间提供过渡层。
+// 原则：仅提供 namespace alias；不重命名实现命名空间，避免破坏性变更。
+
+namespace genesis {
+namespace agents {}
+namespace base {}
+namespace core {}
+namespace diagnostics {}
+namespace messaging {}
+namespace sandbox {}
+namespace simulation {}
+namespace telemetry {}
+namespace tests {}
+namespace world {}
+namespace worldgen {}
+} // namespace genesis
+
+namespace Genesis {
+
+namespace Agents = ::genesis::agents;
+namespace Base = ::genesis::base;
+namespace Core = ::genesis::core;
+namespace Diagnostics = ::genesis::diagnostics;
+namespace Messaging = ::genesis::messaging;
+namespace Sandbox = ::genesis::sandbox;
+namespace Simulation = ::genesis::simulation;
+namespace Telemetry = ::genesis::telemetry;
+namespace Testing = ::genesis::tests;
+namespace World = ::genesis::world;
+namespace Worldgen = ::genesis::worldgen;
+
+} // namespace Genesis
+

tests/CMakeLists.txt

@@ -86,6 +86,7 @@ endif()
 # --- Runtime tests ---
 add_executable(genesis_runtime_tests
     test_contract_docs_schema_versions.cpp
+    test_namespace_aliases.cpp
     test_runtime_events.cpp
     test_runtime_simulation_service.cpp
     test_runtime_e2e_smoke.cpp

tests/test_namespace_aliases.cpp

@@ -0,0 +1,16 @@
+#include <gtest/gtest.h>
+
+#include <type_traits>
+
+#include "genesis/NamespaceAliases.hpp"
+#include "genesis/agents/Needs.hpp"
+#include "genesis/telemetry/TelemetryBuffer.hpp"
+#include "genesis/world/WorldTypes.hpp"
+
+TEST(NamespaceAliases, ExposesGenesisAliases) {
+    static_assert(std::is_same_v<Genesis::Agents::NeedType, genesis::agents::NeedType>);
+    static_assert(std::is_same_v<Genesis::World::MapId, genesis::world::MapId>);
+    static_assert(std::is_same_v<Genesis::Telemetry::TickTelemetry, genesis::telemetry::TickTelemetry>);
+    EXPECT_TRUE(true);
+}
+