docs(plan): 沙箱抓到的第五处 —— 生成的头不能被单独 include

设计文档 §10 补一节。纯文档,已发布于 mcpp:plugins 0.2.6 并由沙箱对着已发布物复验。

「两个编译器产出等价的头」正是 rules-spirv 可以在它们之间选择的前提,而「等价」必须
包括「能被单独 include」。此前每个能用的消费者都在它前面放了一个 Vulkan 头,所以一个
不完整的头读起来一直像是好的 —— 只有一台干净机器上的沙箱会第一个 include 它。

Author: speak-agent

.agents/docs/2026-09-07-heterogeneous-cross-platform-ecosystem.md

@@ -374,9 +374,31 @@ macOS 与 Windows 上的构建都成功了 —— 规则供给了 `xim:shaderc@2
 是消息不是状态。于是这条判据在「只产出 header」的那条路上永远失败,而失败的原因与被测
 的性质无关。正确写法是逐个文件测。
 
+### 10.4d 沙箱抓到的第五处:生成的头不能被单独 include
+
+沙箱夹具里的程序把生成的 SPIR-V 头放在第一行,结果:
+
+    tri_vert.h:3:7: error: 'uint32_t' does not name a type
+
+glslc 那条路早就是自包含的(它发初始化列表,规则本来就要在外面写声明,顺手写了
+`#pragma once` 与 `#include <cstdint>`);glslang 那条路发的是**完整的 C 声明**,于是
+规则什么都不写,而那个文件点名 `uint32_t` 却什么都不 include。
+
+**「两个编译器产出等价的头」正是这条规则可以在它们之间选择的前提**,而「等价」
+必须包括这一条。此前每个能用的消费者都在它前面放了一个 Vulkan 头,所以一个不完整的头
+读起来一直像是好的 —— 直到有人第一个 include 它。**只有一台干净机器上的沙箱会第一个
+include 它。**
+
+修法:两条路同一个形状,编译器写 `<base>.inc`、规则写 `<base>.h`。判据是把生成的头放在
+**第一个** include 且不在它前面放 `<cstdint>` —— 放在前面就是替这个头满足了编译器。
+已发布于 mcpp:plugins 0.2.6,并由沙箱对着**已发布物**复验(section G)。
+
+同一版还给「每条规则都为本宿主编译过」那个夹具补了它自己的分母:它断言的是「每一条」,
+而「每一条」是它 carry 的一张清单。
+
 ### 10.5 一条留下的不一致,以及它什么时候消失
 
-`mcpp:plugins` 0.2.5 里 `xim:shaderc` 在 macOS 与 Windows 上是**精确版本**,而
+`mcpp:plugins` 0.2.5/0.2.6 里 `xim:shaderc` 在 macOS 与 Windows 上是**精确版本**,而
 Linux 上的 `xim:glslang` 是**下界**。这不是形态判断的差异,是 10.3 第 3 条的后果:
 发布中的引擎(2026.9.6.6)传不过去一个 `>`。引擎修复发布之后,那两处改回
 `>=2026.3`,而**那时 plugins 的 Windows job 就是这个引擎修复的端到端判据** ——