docs(architecture): record framework audit decisions

Document the justanyproject comparison, query-command-event boundaries, reversible mod registry rules, package validation gates, and verified EventBus 2.0 state.

DESIGN.md

@@ -45,11 +45,26 @@ ShrinkSDK 是以 Unity Package Manager 包为发布边界的 SDK 单仓库，不
 - 服务器模板文件由哈希清单管理。重新生成前先验证全部现有文件仍等于上次生成版本；任何人工修改都会让整个复制阶段在写入前中止。
 - 业务扩展应放在非生成文件或独立模块中，不通过修改生成产物维持。
 
+### 2.6 查询、命令与事实事件分离
+
+- 查询方只依赖完成当前读取所需的窄契约；只读消费者不取得包含写操作的完整服务对象。
+- 改变状态的跨模块操作使用 Command、RPC 或明确的应用 facade，并返回成功、失败、拒绝、取消等结构化结果。
+- EventBus 负责广播已发生的事实、通知或具有明确结果合同的异步事件，不用无结果事件绕开权限、错误和调用顺序。
+- 静态 facade 只能转发到显式绑定的实例；绑定和解绑必须按实例配对，不能退化为任意类型的全局 Service Locator。
+
+### 2.7 架构约束进入自动化门禁
+
+- 包版本、依赖方向、asmdef 可见性、生成内容所有权和卸载回滚等约束必须尽量由测试或验证脚本执行。
+- 优先检查编译期类型、Cecil/程序集元数据、`package.json`/asmdef 依赖图和真实 UPM 消费结果。
+- `Tools/UpmConsumerValidation/Validate-UpmConsumer.ps1 -GraphOnly` 必须拒绝内部包循环、版本漂移以及普通主包反向依赖 `*-integration-*`；Starter 可作为显式组合根聚合 Integration 包。
+- 源码字符串断言只用于短期迁移门禁；稳定规则不得长期依赖格式、局部变量名或实现文本。
+- 任何测试通过都必须标明验证层级；源码审计、CLI 编译、Unity Test Runner、Play Mode 和 Player Build 不能互相替代。
+
 ## 3. 仓库结构
 
 ```text
 ShrinkSDK/
-|-- Assets/Modules/                 19 个根仓库直接跟踪的 UPM 包
+|-- Assets/Modules/                 20 个根仓库直接跟踪的 UPM 包
 |-- Assets/Scenes/                  示例与验收场景
 |-- Assets/Resources/               当前应用配置与组合 Profile
 |-- GeneratedServers/               独立 .NET 宿主、生成合同与烟测工程
@@ -66,17 +81,18 @@ ShrinkSDK/
 
 | 包 | 版本 | 职责 |
 |---|---:|---|
-| `com.cneicy.shrink-eventbus` | 1.3.0 | 类型安全事件总线、优先级派发、编译期自动注册 |
+| `com.cneicy.shrink-eventbus` | 2.0.0 | 单一事件模型、多 Bus、生成特性订阅、UniTask 调度与零 GC 热路径 |
+| `com.cneicy.shrink-eventbus-entities` | 0.1.0 | ShrinkEventBus 的 ECS/Burst NativeQueue writer 与 playback 适配 |
 | `com.cneicy.shrink-datasaver` | 2.2.0 | 多槽位存档、设置、迁移、加密、原子写入与备份 |
 | `com.cneicy.shrink-command` | 0.2.0 | 路径式命令、权限与同步/异步执行 |
 | `com.cneicy.shrink-network` | 0.2.0 | 消息、RPC、权限、诊断、TCP/KCP/Loopback 与服务器生成 |
-| `com.cneicy.shrink-mod-framework` | 0.1.0 | 模组发现、依赖、生命周期、外部 DLL revision 与 Harmony lease |
+| `com.cneicy.shrink-mod-framework` | 0.2.0 | 模组发现、依赖、可逆生命周期、命名空间内容覆盖、外部 DLL revision 与 Harmony lease |
 | `com.cneicy.shrink-tutorial` | 0.1.0 | 数据驱动引导、遮罩、锚点、触发与持久化 |
 | `com.cneicy.shrink-context-core` | 0.1.0 | 可逆效应、coeffect、fiber、声明式 loader 与诊断 |
 | `com.cneicy.shrink-app-core` | 0.1.1 | App 设置、服务门面、ClassicHost 兼容面与宿主协议 |
 | `com.cneicy.shrink-app-starter-basic` | 0.1.0 | 默认 Context 组合根、配置资产和示例入口 |
 | `com.cneicy.shrink-context-app-adapter` | 0.1.0 | ContextLoader 宿主、Profile/JSON、诊断与基准 |
-| `com.cneicy.shrink-context-eventbus-adapter` | 0.1.0 | EventBus 注册/订阅的可逆效应包装 |
+| `com.cneicy.shrink-context-eventbus-adapter` | 0.1.0 | EventBus 生成绑定的可逆 EffectAttach 包装 |
 | `com.cneicy.shrink-datasaver-integration-eventbus` | 2.1.0 | DataSaver 事件桥 |
 | `com.cneicy.shrink-datasaver-integration-app` | 0.1.0 | DataSaver App installer/原生 Context 组件 |
 | `com.cneicy.shrink-command-integration-eventbus` | 0.1.1 | 命令请求与生命周期事件桥 |
@@ -145,7 +161,7 @@ Cordis 迁移的阶段 0 至阶段 5 已进入当前架构，不再是待办计
 
 ### 7.1 EventBus
 
-静态 `EventBus` 委托给 `IShrinkEventBus` 实例。监听按 phase 和数字优先级稳定归并；订阅句柄可单独释放，实例注册可整体撤销。Context 适配器把二者登记为效应，保证 fiber 卸载自动退订。
+静态 `EventBus` 委托给命名 `IShrinkEventBus` 实例。Bus Key 表达 Game/Scene/Mod/World/Server 所有权，Bus Options 固定 Inline/MainThread/DedicatedThread/TaskPool 调度。事件只实现 `IShrinkEvent`，取消和结果由能力接口声明；注册只允许 `[ShrinkEventSubscriber]` / `[ShrinkSubscribe]` 生成绑定与 `Attach/Dispose` 生命周期。Context 适配器把绑定登记为可逆效应，保证 fiber 卸载自动退订。
 
 ### 7.2 DataSaver
 
@@ -172,13 +188,15 @@ Cordis 迁移的阶段 0 至阶段 5 已进入当前架构，不再是待办计
 
 `ShrinkModContextHost` 将模组生命周期纳入 Context apply。热替换单位是 `ModId + revision`；外部 DLL 用 SHA-256 标识 revision，失败或损坏 revision 不会成为 current，旧组合会恢复。Harmony、Registry 与 Network handler 使用可逆 lease 清理。
 
+`ShrinkModRegistry<T>` 的基础项只能通过 `<ownerModId>:<localKey>` namespace 注册；覆盖必须指向已有基础项，按显式优先级选出 winner，同目标同优先级直接拒绝。基础项和覆盖项都记录 owner，卸载时自动撤回并恢复下一个覆盖或基础值。注册表不采用全局冻结，因为 revision 热替换与事务回滚要求状态可撤回。
+
 Mono 中已加载程序集不能真正卸载。系统只回滚组件实例与效应，并通过 `ShrinkModDiagnostics` 暴露 current/history、累计载入字节和软阈值，达到阈值时建议 Domain Reload 或进程重启。
 
 ## 8. 编译期注册与服务器生成
 
 ### 8.1 Unity 运行时注册
 
-`ShrinkShared.CodeGen/Editor/ShrinkRegistryILPostProcessor.cs` 为引用方程序集生成 EventBus、Command、Network 和 App 注册信息。运行时只消费程序集级注册表；外部 DLL 和运行时对象使用实例注册入口。核心程序集自身不被共享织入器回写，避免程序集自引用。
+`ShrinkEventBus/CodeGen/Editor/EventBusILPostProcessor.cs` 为引用方程序集生成实例直接调用绑定和静态模块初始化注册，不运行时枚举方法。`ShrinkShared.CodeGen/Editor/ShrinkRegistryILPostProcessor.cs` 继续负责 Command、Network 和 App 注册表。外部 Mod DLL 必须携带 EventBus 生成合同；没有合同的生产 DLL 不自动反射注册。
 
 ### 8.2 独立服务器生成
 
@@ -200,10 +218,10 @@ Mono 中已加载程序集不能真正卸载。系统只回滚组件实例与效
 
 一次涉及包边界、生成器或组合根的变更至少经过：
 
-1. 内部版本一致性检查：全部 `com.cneicy.*` 依赖等于仓库包版本。
+1. 内部包图检查：全部 `com.cneicy.*` 依赖版本一致、无循环，普通主包不反向依赖 Integration 包。
 2. Unity 编译：目标 asmdef 和根项目无编译错误。
 3. EditMode 测试：功能测试、Context 生命周期、语义扫描和模板覆写保护。
-4. 真实 UPM 消费：`Tools/UpmConsumerValidation/Validate-UpmConsumer.ps1` 创建仓库外形态的临时 Unity 工程，通过 `file:` 安装全部 19 个包，启用 testables，验证包注册、程序集加载并运行 EditMode 测试。
+4. 真实 UPM 消费：`Tools/UpmConsumerValidation/Validate-UpmConsumer.ps1` 创建仓库外形态的临时 Unity 工程，通过 `file:` 安装全部 20 个包，启用 testables，验证包注册、程序集加载并运行 EditMode 测试。
 5. 独立宿主：生成工程与 RuntimeSmoke 按变更范围构建或运行。
 6. 涉及真实生命周期时，仍需在目标场景执行 Play Mode 验收；源码检查和 EditMode 不能替代该路径。
 
@@ -218,6 +236,17 @@ Mono 中已加载程序集不能真正卸载。系统只回滚组件实例与效
 
 ## 11. 文档治理
 
+### 11.1 外部架构审计与 EventBus 统一模型
+
+- `Docs/JustAnyProjectArchitectureAudit.md` 记录 `D:\UnityBuilds\justanyproject` 的当前框架组织、可迁移经验、不可复制部分和证据边界；其结论已收敛为本文 2.6、2.7 与 Mod registry 约束。
+- ShrinkEventBus 采用一个事件模型、多个命名 Bus 实例；Bus Key 负责生命周期与隔离，Bus Options 负责 Inline/MainThread/DedicatedThread/TaskPool 调度。
+- Unity 中可用 UniTask 时，EventBus 异步调度和 handler 优先使用 UniTask；纯 .NET 使用 ValueTask/同步实现。
+- 生产注册为特性声明 + 生成强类型绑定；旧 EventBase/Register/Subscribe/Trigger 与反射 handler 通道已删除。
+- ECS/Burst 通过 NativeQueue writer/playback 进入对应 World Bus，不直接调用托管事件 handler。
+- EventBus 调试窗口使用 UI Toolkit，以按需详细采样记录全局 Bus 的调度、线程、结果和耗时；窗口暂停或关闭时观测回调为空，独立 Host 始终不被全局诊断或 Network bridge 捕获。
+- 2026-08-24 Unity Play Mode 最终三轮中位数：8 handler class 25.32M、8 handler struct 35.02M、30 handler 10.82M ops/s，同步 struct Post 为 0 B/10,000,000 次；详见包 README。
+- Windows x64 Development IL2CPP Player 已完成构建验证；Standalone 脚本后端随后恢复为 Mono。
+
 - 当前架构只更新本文。
 - 包级使用方式和 API 示例放在各包 README。
 - `NETWORK_PITFALLS.md` 记录实现经验，不描述当前模块清单。