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"]

docs/zh/05-mcpp-toml.md

@@ -291,6 +291,15 @@ std::vector<std::string> host_base_flags(const mcpp::toolchain::Toolchain& tc,
     // undefined __cxa_* / __gxx_personality_v0.
     opt.cfgBypass = mcpp::toolchain::HostFlagOptions::CfgBypass::LinuxOnly;
     opt.clangStdlibSelect = true;
+    // ⭐ `cAbiPrebuilt` is left at its default (true), and that is a statement
+    // rather than an omission: `tc` here is always HOST-targeting (see this
+    // function's header), so the helper's C library is the payload's whatever
+    // the project's target side turns out to be.
+    //
+    // ⚠️ It also corrects a latent defect. The predicate this replaced was
+    // `!tc.crossTargetFlag.empty()`, and a host toolchain resolved for a cross
+    // build could carry one — in which case the helper lost the payload's own
+    // headers for a reason that had nothing to do with it.
     // binutils -B so the driver finds ld/as (GCC; musl and MinGW ship their own).
     opt.binutilsPrefix = !mcpp::toolchain::is_musl_target(tc)
                       && !mcpp::toolchain::is_mingw_target(tc);

mcpp.toml

@@ -56,6 +56,7 @@ import mcpp.manifest;
 import mcpp.modgraph.scanner;
 import mcpp.toolchain.detect;
 import mcpp.toolchain.fingerprint;
+import mcpp.toolchain.linkmodel;
 import mcpp.toolchain.triple;
 import mcpp.freestanding.target;   // the flags a bare-metal triple implies
 
@@ -97,6 +98,36 @@ struct BuildAxes {
     // Measured on exactly that upgrade. Empty for hosted targets, so nothing
     // else's key moves.
     std::vector<std::string> targetImpliedFlags;
+    // ⭐⭐ THE HEADER SET THE DRIVER IS POINTED AT — not the driver.
+    //
+    // Everything else on this axis describes the COMPILER. Nothing described
+    // the LIBRARY it compiles against, and the two are separately installed:
+    // one clang payload sits above whichever `xim:glibc` and
+    // `xim:linux-headers` the home happens to carry.
+    //
+    // ⚠️ AND `driverIdentity` CANNOT COVER IT, BY DESIGN.
+    // `normalize_driver_output` deliberately strips `/home/`, `/tmp/` and
+    // `/var/` paths out of `clang --version`, which is what lets one entry be
+    // shared between two homes. Correct — and it means two homes carrying the
+    // same clang above DIFFERENT glibc payloads produce the same
+    // `driver_identity`, the same key, and one entry serving two header sets.
+    //
+    // Measured (mcpp#514 §B, third direction): two host builds resolving glibc
+    // 2.39 and 2.44 hit one entry, and the mixed BMIs then crash the clang
+    // frontend outright — SIGSEGV in
+    // `ASTReader::FindExternalVisibleDeclsByName` during deserialization —
+    // rather than producing a readable diagnostic. BMIs carry no cross-check
+    // against each other.
+    //
+    // ⭐ THE `std` CACHE ON THE SAME MACHINE HAS ALWAYS HAD THIS. Its identity
+    // folds in `std_build_commands`, the whole command line, `-isystem` rows
+    // included. Two caches, one machine, two notions of "the same inputs"; the
+    // dependency one was the short one.
+    //
+    // Store-relative, for the same reason the include dirs below are: the key
+    // must survive a different MCPP_HOME, and what matters is WHICH payloads,
+    // not where the home is.
+    std::vector<std::string> targetHeaderSet;
     std::string stdlibId;
     std::string stdlibVersion;
     // B
@@ -163,7 +194,8 @@ BuildAxes build_axes(const mcpp::toolchain::Toolchain& tc,
                      const mcpp::manifest::Manifest&   rootManifest,
                      std::string_view                  cppStandardFlag,
                      const std::vector<std::string>&   dialectFlags,
-                     std::string_view                  macosDeploymentTarget);
+                     std::string_view                  macosDeploymentTarget,
+                     const std::filesystem::path&      storeRoot = {});
 
 // Axes E from one PackageRoot. `storeRoot` is stripped off absolute include
 // dirs so the key survives a different MCPP_HOME (the payload paths are
@@ -217,6 +249,7 @@ nlohmann::json to_json(const BuildAxes& b, const PackageAxes& p) {
         {"driver_identity", b.driverIdentity},
         {"target_triple", b.targetTriple},
         {"target_implied_flags", b.targetImpliedFlags},
+        {"target_header_set", b.targetHeaderSet},
         {"stdlib", b.stdlibId},
         {"stdlib_version", b.stdlibVersion},
     };
@@ -264,6 +297,7 @@ std::string key_hex(const BuildAxes& b, const PackageAxes& p) {
     put(s, "driver",   b.driverIdentity);
     put(s, "triple",   b.targetTriple);
     put_list(s, "targetflags", b.targetImpliedFlags);
+    put_list(s, "hdrset",      b.targetHeaderSet);
     put(s, "stdlib",   b.stdlibId);
     put(s, "stdlibv",  b.stdlibVersion);
     // B
@@ -302,7 +336,8 @@ BuildAxes build_axes(const mcpp::toolchain::Toolchain& tc,
                      const mcpp::manifest::Manifest&   rootManifest,
                      std::string_view                  cppStandardFlag,
                      const std::vector<std::string>&   dialectFlags,
-                     std::string_view                  macosDeploymentTarget)
+                     std::string_view                  macosDeploymentTarget,
+                     const std::filesystem::path&      storeRoot)
 {
     BuildAxes b;
     b.compilerId      = std::string(tc.compiler_name());
@@ -349,6 +384,36 @@ BuildAxes build_axes(const mcpp::toolchain::Toolchain& tc,
     b.stdlibId        = tc.stdlibId;
     b.stdlibVersion   = tc.stdlibVersion;
 
+    // ⭐ THE HEADER SET, TAKEN FROM THE RESOLVERS THAT PRODUCE THE COMMAND
+    // LINE — not derived a second time.
+    //
+    // `mcpp.toolchain.linkmodel` is already the single answer to "where does
+    // this toolchain's C library and libc++ come from"; every consumer of a
+    // compile line reads it. Asking it here means the key describes the header
+    // set that will actually be used, and cannot drift from it.
+    //
+    // ⚠️ Store-relative. The absolute form names this machine's home, and the
+    // whole point of `normalize_driver_output` stripping paths is that one
+    // entry can serve two homes carrying the same payloads. Leaving these
+    // absolute would undo that; folding them in relative distinguishes
+    // DIFFERENT payloads while still sharing between homes.
+    {
+        const auto storeStr = storeRoot.generic_string();
+        const mcpp::toolchain::PathEscape relativize =
+            [&](const std::filesystem::path& p) -> std::string {
+                auto str = p.generic_string();
+                if (!storeStr.empty() && str.starts_with(storeStr))
+                    return "<store>" + str.substr(storeStr.size());
+                return str;
+            };
+        for (auto& t : mcpp::toolchain::resolve_clang_driver(tc)
+                           .compile_tokens(relativize))
+            b.targetHeaderSet.push_back(t);
+        for (auto& t : mcpp::toolchain::resolve_link_model(tc)
+                           .compile_tokens(relativize))
+            b.targetHeaderSet.push_back(t);
+    }
+
     b.cppStandard     = rootManifest.package.standard;
     b.cppStandardFlag = std::string(cppStandardFlag);
     b.dialectFlags    = dialectFlags;

src/build/build_program.cppm

@@ -593,6 +593,11 @@ CompileFlags compute_flags(const BuildPlan& plan) {
         mcpp::toolchain::HostFlagOptions hopt;
         hopt.cfgBypass = mcpp::toolchain::HostFlagOptions::CfgBypass::Always;
         hopt.macosDeploymentTarget = macosDeploymentTarget;
+        // ⭐ THE SAME EXPRESSION THE LINK SIDE ASKS, twenty lines further down
+        // (`plan.targetSide.cAbi.prebuilt()`). Reading one value at both sites
+        // is what makes it impossible for them to disagree — which they did,
+        // from #511 until now, because only the link side was corrected.
+        hopt.cAbiPrebuilt = plan.targetSide.cAbi.prebuilt();
         compile_toolchain_flags = mcpp::toolchain::render_tokens(
             mcpp::toolchain::host_compile_tokens(plan.toolchain, hopt, ninjaEsc));
     } else {