2026.8.27.1 —— 目标侧被解析出来了,只发给了一个编译单元

⭐ 与 2026.8.25.x / 2026.8.26.1 是同一族的下一层。那两批修的是「谓词问错了」
与「答案没接到决定上」;这一批里,答案接上了一个消费者,而它有五个。

## ⭐⭐ 编译侧的谓词是 2026.8.26.1 在链接侧修掉的那条的孪生兄弟

`hostflags.cppm` 问 `!crossTargetFlag.empty()`——「命令行上有没有 `--target=`」——
而它自己的注释写的是「目标侧来自图」。同机、同编译器、同目标,只差写不写
`--target`,编译线少六个 token:

    --no-default-config  -nostdinc++
    -isystem <payload>/include/c++/v1
    -isystem <payload>/include/<triple>/c++/v1
    -isystem <glibc>/include
    -isystem <linux-headers>/include

⇒ 头文件来自一个库,目标文件链自另一个库。两侧现在读同一个
`plan.targetSide.cAbi.prebuilt()`,由 prepare 记在 `Toolchain` 上供三个生产者共用。

⚠️ `--no-default-config` 从该条件里拆出来无条件发:它不是载荷头文件集合的一部分,
而 cfg 按 post_install.cppm 自己的说法是「per-machine, per-install-path artifact」。
这也解释了报告者那个手写 `<triple>-clang++.cfg` 的 workaround 为什么有效。

⚠️ e2e 295 写的就是这条恒等式,而它只比对 `^ldflags` ⇒ 恒等式在下一行不成立而测试
看不见。现在两条都比,并断言两侧非空。

## ⭐⭐ 载荷目录名是 LLVM 词汇,查找用的是 mcpp 词汇,且失配静默

`include/<triple>/c++/v1` 由 LLVM 的构建写下(`x86_64-unknown-linux-gnu`),
`tc.targetTriple` 是 mcpp 的(`x86_64-linux-gnu`)。两者只在三元组是探测来的时候
恰好相同。查找是 `if (exists) push_back`,找不到就什么也不发生 —— 而那个目录里
只有 `__config_site`,它的缺席产生的报错读起来像载荷坏了。两种拼法都试。

## ⭐⭐ 由图供给的目标侧只到达一个编译单元(mcpp#514 §A)

提供 `mcpp:` 层的包发布的是整个目标编译时所依据的头文件集合,而它以 publicUsage
的形态沿依赖边传播 ⇒ 根与 provider 自己的单元拿得到,兄弟依赖包拿不到。结果是
一次构建里两种口味的 BMI(`reference to 'space' is ambiguous`)。

目标侧解析后,`fromGraph()` 的层的 publicUsage 并入每一个包的 privateBuild;
std 模块的命令行改读同一个集合,不再自己推一遍。

## ⭐⭐ 缓存键描述了编译器,没描述它被指向的头文件集合(mcpp#514 §B)

`driverIdentity` 按设计覆盖不了它 —— `normalize_driver_output` 故意抹掉路径,
好让一个条目能被两个 home 共享。新增 `targetHeaderSet` 轴,取自已解析的
linkmodel,store-相对化。不 bump kCacheEpoch:旧条目是 miss 不是不可用。

## ⭐ home 发现有第四份拷贝,而且会伸到别的 home 去

`active_home_xpkgs()` 自己重推一遍 home(漏掉自包含安装那一档);
`find_sibling_package` 无条件回落 `~/.xlings/data/xpkgs` ⇒ 密闭构建可以从另一棵树
取载荷,结果直接进每条编译命令的 `-isystem`。前者改读 `mcpp::home::root()`,
后者删除 —— 找不到会说话,找错了不会。

## 新增 `[build] private_include_dirs`

指出 include_dirs 中在本包边界处停住的条目。publicUsage 此前整份接过
privateBuild,于是内嵌带内部头覆盖层的库(musl 的 src/include 定义
hidden/weak/weak_alias)会把那些宏发给每个消费者。openkal-musl 的
port/include/features.h 自己写下了这个缺口和它的第一优解。

⚠️ 它是 include_dirs 的子集而不是第二个列表:两类目录的相对顺序是承重的,
而两个 TOML 数组表达不了一个顺序。

## 判据

- 单元 93 passed / 0 failed(新增 3 条,均确认真的在跑,非 SKIP)
- e2e 295 扩到 cxxflags:修复后两工具链四条全绿;未修二进制上退出码 1 并列出六个丢失 token
- e2e 304(新):目标侧到达兄弟依赖包 —— 未修二进制上变红
- e2e 305(新):编译用/发布用分开 —— 未修二进制上变红
- 三条 e2e 均带分母(CDB 行数),空 CDB 不会假绿

Closes #514

Author: speak-agent

.agents/docs/2026-08-27-openkal-ecosystem-design-plan.md

@@ -3,6 +3,80 @@
 > 本文件追踪 `mcpp-community/mcpp` 公开仓的版本演进。
 > 格式参考 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)。
 
+## [2026.8.27.1] — 2026-08-27
+
+目标侧被解析出来了,只发给了一个编译单元。完整分析见
+[`.agents/docs/2026-08-27-openkal-native-path-three-issues.md`](.agents/docs/2026-08-27-openkal-native-path-three-issues.md)。
+
+⭐ **与 `2026.8.25.x`/`2026.8.26.1` 是同一族的下一层。** 那两批修的是「谓词问错了」
+与「答案没接到决定上」;这一批里,答案**接上了一个消费者,而它有五个**。
+
+### 修复
+
+- **⭐⭐ 编译侧的谓词,是 `2026.8.26.1` 在链接侧修掉的那条的孪生兄弟。**
+
+  `hostflags.cppm` 问的是 `!crossTargetFlag.empty()` ——「命令行上有没有
+  `--target=`」——而它的注释写的是「目标侧来自图」。同一台机器、同一个编译器、
+  同一个目标,只差写不写 `--target`,编译线少了**六个 token**:
+
+  ```
+  --no-default-config  -nostdinc++
+  -isystem <payload>/include/c++/v1
+  -isystem <payload>/include/<triple>/c++/v1
+  -isystem <glibc>/include
+  -isystem <linux-headers>/include
+  ```
+
+  ⇒ 头文件来自一个库,目标文件链自另一个库。两侧现在读同一个
+  `plan.targetSide.cAbi.prebuilt()`。⚠️ `--no-default-config` 从这个条件里
+  **拆了出来无条件发** —— 它不是载荷头文件集合的一部分,而 cfg 文件按
+  `post_install.cppm` 自己的说法是「per-machine, per-install-path artifact」。
+
+  ⚠️ `e2e 295` 写的就是这条恒等式,而它只比对 `^ldflags`,所以恒等式在**下一行**
+  不成立而测试看不见。现在两条都比。
+
+- **⭐⭐ 载荷目录名是 LLVM 词汇,而查找用的是 mcpp 词汇 —— 而且失配是静默的。**
+
+  `include/<triple>/c++/v1` 与 `lib/<triple>` 由 LLVM 的构建写下,带的是
+  `x86_64-unknown-linux-gnu`;`tc.targetTriple` 是 mcpp 的
+  `x86_64-linux-gnu`。两者只在三元组是**探测来的**时候恰好相同。查找是
+  `if (exists) push_back`,所以找不到就什么也不发生 —— 而那个目录里只有一个文件,
+  `__config_site`,它的缺席产生的报错读起来像载荷坏了。两种拼法现在都试。
+
+- **⭐⭐ 由图供给的目标侧,只到达了一个编译单元(mcpp#514 §A)。**
+
+  提供 `mcpp:` 层的包发布的是**整个目标**编译时所依据的头文件集合,而它今天以
+  `publicUsage` 的形态**沿依赖边**传播。于是根与 provider 自己的单元拿得到,而
+  **兄弟依赖包**拿不到 —— `nlohmann.json` 不在 `openkal-llvm-runtime` 的下游,
+  它在它旁边。结果是一次构建里两种口味的 BMI,任何同时导入两者的 TU 在第一个
+  模板实例化处炸掉(`reference to 'space' is ambiguous`)。
+
+  ⭐ 目标侧解析之后,`fromGraph()` 的层的 `publicUsage` 并入**每一个**包的
+  `privateBuild`;`std` 模块的命令行也改读同一个集合,不再自己推一遍。
+
+- **⭐⭐ 缓存键描述了编译器,没有描述它被指向的头文件集合(mcpp#514 §B)。**
+
+  A 轴上的每一项都在描述**编译器**,没有一项描述它编译时所依据的**库** ——
+  而两者是分开安装的。`driverIdentity` 按设计也覆盖不了它:
+  `normalize_driver_output` **故意**抹掉路径,好让一个条目能被两个 home 共享。
+  新增 `targetHeaderSet` 轴,取自已经解析好的 `linkmodel`,并 store-相对化。
+  ⚠️ 不 bump `kCacheEpoch` —— 旧条目是 miss 而不是不可用。
+
+- **⭐ home 发现有第四份拷贝,而且会伸到别的 home 里去。**
+
+  `active_home_xpkgs()` 自己重推了一遍 home(漏掉自包含安装那一档);
+  `find_sibling_package` 找不到时**无条件回落** `~/.xlings/data/xpkgs`。
+  后者意味着一次密闭构建可以从**另一棵树**取载荷,而结果直接进每条编译命令的
+  `-isystem`。前者改为 `mcpp::home::root()`,后者删除 —— 找不到会说话,找错了不会。
+
+### 新增
+
+- **`[build] private_include_dirs`** —— 指出 `include_dirs` 中在本包边界处停住的
+  条目。`publicUsage` 此前整份接过 `privateBuild` 的目录,于是一个内嵌了带内部头
+  覆盖层的库(musl 的 `src/include` 定义 `hidden`/`weak`/`weak_alias`)会把那些宏
+  发给每一个消费者。⚠️ 它是 `include_dirs` 的**子集**而不是第二个列表:两类目录的
+  相对顺序是承重的,而两个 TOML 数组表达不了一个顺序。
+
 ## [2026.8.26.2] — 2026-08-26
 
 已经解析出的答案,没有被用来做决定。完整分析见

.agents/docs/2026-08-27-openkal-native-path-three-issues.md

@@ -176,6 +176,7 @@ module_extensions = [".ixx"]      # Extra extensions used by module INTERFACES (
 build_program_timeout = 1800      # Seconds a build.mcpp may run; 0 = no limit (§ below)
 include_dirs = ["include", "third_party/include"]  # Header search paths
 include_dirs_after = ["*"]         # Header dirs searched AFTER system dirs (-idirafter)
+private_include_dirs = ["vendor/src/include"]  # Of `include_dirs`, the ones a consumer must NOT get
 c_standard   = "c11"              # Standard for C source files (default c11)
 cflags       = ["-DFOO=1"]        # Extra C compile flags
 cxxflags     = ["-DBAR=2"]        # Extra C++ compile flags (do not put -std=... here)
@@ -190,6 +191,34 @@ jobs         = "auto"             # Concurrent compiles: a positive number, or "
 bmi_schedule = "auto"             # Module-edge scheduling: auto (= off) | on | off (§ below)
 ```
 
+`private_include_dirs` names the entries **of `include_dirs`** that stop at this
+package's own boundary: this package compiles with them, and a consumer never
+receives them.
+
+Almost every package publishes exactly the set it is built from, which is why
+`include_dirs` alone was enough for a long time. The shape where the two differ
+is a package that vendors a library with an *internal header overlay*. musl
+reaches its own declarations through `src/include`, whose headers define
+`hidden`, `weak` and `weak_alias` — names that mean something only to musl's own
+sources. Publishing that directory hands those macros to every consumer, and a
+consumer that uses `hidden` as an ordinary identifier stops compiling for a
+reason it has no way to see.
+
+```toml
+[build]
+# ⚠️ The relative ORDER of the two kinds is load-bearing: the internal overlay
+# must precede the public headers for this package's own build. That is why
+# this is a SUBSET of `include_dirs` rather than a second list — two arrays
+# cannot express one order.
+include_dirs         = ["port/include", "musl/src/include", "musl/include"]
+private_include_dirs = ["musl/src/include"]
+```
+
+Entries take the same `*` glob convention as `include_dirs`, and are matched
+after expansion — so a glob may name exactly the directories it expands to. An
+entry that is not among this package's `include_dirs` withholds nothing and is
+reported as such rather than passing in silence.
+
 `include_dirs_after` (#249) lists header directories that are searched **after**
 the toolchain's system directories (emitted as `-idirafter` on GCC/Clang, as
 trailing `/I` under the MSVC dialect, and as plain `-I` for NASM

CHANGELOG.md

@@ -166,6 +166,7 @@ module_extensions = [".ixx"]      # 模块**接口**额外使用的扩展名(见
 build_program_timeout = 1800      # build.mcpp 的运行上限(秒);0 = 不限(见下节)
 include_dirs = ["include", "third_party/include"]  # 头文件搜索路径
 include_dirs_after = ["*"]         # 排在系统目录之后搜索的头文件目录(-idirafter)
+private_include_dirs = ["vendor/src/include"]  # `include_dirs` 中不发布给消费者的那些
 c_standard   = "c11"              # C 源文件的标准(默认 c11)
 cflags       = ["-DFOO=1"]        # 额外 C 编译参数
 cxxflags     = ["-DBAR=2"]        # 额外 C++ 编译参数(不要放 -std=...)
@@ -178,6 +179,28 @@ jobs         = "auto"             # 并发编译数:正整数,或 "auto"(见下
 bmi_schedule = "auto"             # 模块边调度:auto(= 关)| on | off(见下节)
 ```
 
+`private_include_dirs` 指出 **`include_dirs` 中**在本包边界处停住的那些条目:
+本包用它们编译,消费者永远收不到。
+
+绝大多数包发布的就是它编译时用的那一套,所以长期以来只有 `include_dirs` 就够了。
+两者不同的形状只有一种 —— 一个包**内嵌了带内部头覆盖层的库**。musl 通过
+`src/include` 到达它自己的声明,而那些头定义了 `hidden`、`weak`、`weak_alias`,
+这些名字只对 musl 自己的源码有意义。把那个目录发布出去,等于把这些宏交给每一个
+消费者;而一个把 `hidden` 当普通标识符用的消费者会编不过,且看不出原因。
+
+```toml
+[build]
+# ⚠️ 两类目录的**相对顺序**是承重的:本包自己构建时,内部覆盖层必须排在公共头之前。
+# 这正是它被设计成 `include_dirs` 的**子集**而不是第二个列表的原因 ——
+# 两个数组表达不了一个顺序。
+include_dirs         = ["port/include", "musl/src/include", "musl/include"]
+private_include_dirs = ["musl/src/include"]
+```
+
+条目支持与 `include_dirs` 相同的 `*` glob 约定,并在**展开之后**比对 ——
+所以一个 glob 可以恰好指名它展开出的那些目录。若某条目不在本包的 `include_dirs`
+里,它什么也没扣下,mcpp 会把这件事说出来而不是让它悄悄通过。
+
 `include_dirs_after`(#249)列出**排在工具链系统目录之后**搜索的头文件目录
 (GCC/Clang 发射为 `-idirafter`;MSVC 方言退化为排在末尾的 `/I`,NASM 汇编
 单元退化为普通 `-I`——两者都没有对应 flag,也都没有需要保护的系统头搜索链)。当目录是解压后的源码 tarball 根目录、且其中的文件名会与标准头冲突时,

docs/05-mcpp-toml.md

@@ -1,6 +1,6 @@
 [package]
 name        = "mcpp"
-version = "2026.8.26.2"
+version = "2026.8.27.1"
 description = "Modern C++ build & package management tool"
 license     = "Apache-2.0"
 authors     = ["mcpp-community"]