fix(runtime): SubOS 缺声明降级,不再让构建失效 (openxlings/xlings#543)

Windows 上 xlings 不写 subos_info 块,而 mcpp 把「缺声明」当成错误返回,
prepare 无平台条件地把它变成 std::unexpected —— 于是每一次 mcpp build / mcpp test
都停在一条讲 GL 驱动的消息上,在一台没有 ELF、没有 PT_INTERP、没有私有 libc 的机器上。

  error: selected SubOS 'default' cannot provide a RuntimeBinding: …
         does not describe itself … a GL application will not find its drivers

回归窗口已核:git log -S 只命中 PR #400(它把返回 string 的软函数换成了 expected),
且该 commit 在 2026.8.8.4 的 bump 之后 ⇒ 首次随 2026.8.10.2 发布。与报告
「降级到 2026.8.8.4 就能跑」逐字吻合。

判据改为一句话:矛盾报错,缺席降级。

  点名的 SubOS 不存在   → 仍是硬错误。该请求无法被满足,换一个环境会让同一份
                          mcpp.toml 在不同机器上意味着不同 ABI。
  SubOS 没有描述自己    → declared=false + 一条调用方必须打印的 note,构建继续。
                          runtime 规则报 inconclusive 而不是给出判决。

同一位置的第二颗雷一并拆掉:schema 检查是 !=,而它的读取器 subos_info::read 明写着
「更高的 schema 照读,取我们认识的字段」。xlings 写出 schema 2 的那天,全平台所有
构建会同时停摆 —— 这是 index-floor 事故的第二次转生。改为上限语义:发布数据不得
使读它的程序失效。

诚实的边界:Linux 上降级 binding 确实拿不到 payload(mcpp 拒绝猜一个 libc 版本),
所以链接会回落宿主并被 hermeticity 检查如实拦下。note 现在把这句话说出来,而不是
承诺「构建不受影响」—— e2e 221 断言的正是这个:失败可以,但必须是关于 C 运行时的
失败,不能是关于 binding 的失败。

e2e 221 刻意不声明任何能力。带 `# requires: elf` 或 `gcc` 会让它在唯一需要它的平台
上被跳过 —— 与 217 从未在 Windows/macOS 跑过是同一形状。

RuntimeBinding 同时新增 searchDirs 字段(SubOS 库视图),本 commit 内无消费者。

Author: speak-agent

src/build/prepare.cppm

@@ -46,10 +46,11 @@ import mcpp.build.backend;      // BuildOptions for the tool sub-build
 import mcpp.build.ninja;        // make_ninja_backend — driving that sub-build
 import mcpp.lockfile;
 import mcpp.config;
-import mcpp.xlings;
-import mcpp.xlings.subos_info;
-import mcpp.xlings.runtime_selection;
+import mcpp.platform.xlings;
+import mcpp.platform.xlings.subos_info;
+import mcpp.platform.xlings.runtime_selection;
 import mcpp.platform.runtime_binding;
+import mcpp.platform.runtime_search;
 import mcpp.toolchain.post_install;
 import mcpp.platform;
 import mcpp.fetcher;
@@ -1293,6 +1294,12 @@ prepare_build(bool print_fingerprint,
             runtimeSelection, {}, **cfgRuntime);
         if (!resolved) return std::unexpected(resolved.error());
         runtimeBindingSnapshot = std::move(*resolved);
+        // A degradation that nobody prints is indistinguishable from no
+        // degradation, which is the failure this whole area keeps paying for.
+        // A note is not a warning: nothing is wrong with the build, some facts
+        // are simply unavailable — so it is reported once, at info level.
+        if (!runtimeBindingSnapshot.note.empty())
+            mcpp::ui::info("Runtime", runtimeBindingSnapshot.note);
     }
     const auto runtimePayload = runtimeBindingSnapshot.libc.value_or("");
     const auto runtimeLibDir = runtimeBindingSnapshot.libraryDirs.empty()
@@ -6394,12 +6401,29 @@ prepare_build(bool print_fingerprint,
         const bool macho = triple.find("darwin") != std::string::npos
                         || triple.find("apple") != std::string::npos;
         std::string format = pe ? "pe" : macho ? "macho" : "elf";
+        // The ORDERED run-time search closure with provenance. Order is
+        // semantics here, not presentation: it is what the loader will walk,
+        // and the mutable SubOS farm sitting last is the invariant that keeps
+        // libc resolving from the pinned payload. Recorded so "why does my GL
+        // program find its driver" is answerable without readelf, and so a
+        // regression in the ordering is visible to CI and to `mcpp why`.
+        nlohmann::json closure = nlohmann::json::array();
+        for (auto const& dir : ctx.plan.runtimeSearch) {
+            closure.push_back({
+                {"path", dir.path.generic_string()},
+                {"origin", std::string(
+                    mcpp::platform::search::to_string(dir.origin))},
+                {"machine_local",
+                    mcpp::platform::search::is_machine_local(dir.origin)},
+            });
+        }
         nlohmann::json search = {
             {"format", format},
             {"link_library", pe ? "libpath" : "library_path"},
             {"transitive_needed", format == "elf" ? "rpath_link" : "none"},
             {"runtime", format == "pe" ? "deploy"
                          : format == "macho" ? "loader_rpath" : "runpath"},
+            {"closure", closure},
         };
         j["runtime"] = {
             {"library_dirs", dirs},

src/platform/runtime_binding.cppm

@@ -11,8 +11,8 @@ import std;
 import mcpp.config;
 import mcpp.libs.json;
 import mcpp.platform;
-import mcpp.xlings.runtime_selection;
-import mcpp.xlings.subos_info;
+import mcpp.platform.xlings.runtime_selection;
+import mcpp.platform.xlings.subos_info;
 
 export namespace mcpp::platform::runtime {
 
@@ -28,7 +28,17 @@ struct RuntimeBinding {
     std::optional<std::filesystem::path> loader;
     std::optional<std::string> libc;
     std::optional<std::string> hostLibc;
+    // IMMUTABLE payload directories (`<store>/xim-x-glibc/2.39/lib64`).
     std::vector<std::filesystem::path> libraryDirs;
+    // The SubOS symlink farm (`<subos>/lib`) — a union view of everything
+    // installed into this environment, rewritten on every re-resolution.
+    //
+    // Deliberately a SECOND field rather than more entries in `libraryDirs`:
+    // merging them discards the immutability distinction, and that
+    // distinction is the whole of `mcpp.platform.runtime_search`'s ordering
+    // rule. A payload directory and a farm directory are not interchangeable
+    // even when they currently resolve to the same file.
+    std::vector<std::filesystem::path> searchDirs;
     std::vector<mcpp::xlings::subos::EnvDecl> environment;
     std::vector<std::string> providerBindings;
     std::vector<std::string> capabilities;
@@ -37,6 +47,32 @@ struct RuntimeBinding {
     std::string provenance;
     std::filesystem::path subosDir;
     mcpp::xlings::runtime::RuntimeSelection selection;
+
+    // Did the SubOS describe itself (does it carry a `subos_info` block)?
+    //
+    // FALSE IS NOT AN ERROR. A SubOS that says nothing leaves some facts
+    // unknown — rules A/B become inconclusive, declared environment is
+    // unavailable — and leaves everything else working. Treating absence as a
+    // failure is what stopped every `mcpp build` and `mcpp test` on Windows
+    // (openxlings/xlings#543), on a machine where the missing facts describe
+    // concepts (ELF, PT_INTERP, a private libc) that do not exist there.
+    //
+    // A CONTRADICTION still fails: naming a SubOS that is not present cannot
+    // be satisfied, so it is reported rather than degraded.
+    bool declared = false;
+
+    // Why something degraded. Non-empty ⇒ the caller MUST surface it. Never
+    // an error: "it did not happen" and "it succeeded" producing identical
+    // output is the property that made mcpp#352 expensive.
+    std::string note;
+
+    // Does this artifact run under a PRIVATE loader?
+    //
+    // The predicate the closure resolver needs: when PT_INTERP points into a
+    // payload, the HOST loader's built-in default directories are not part of
+    // the search path, and modelling them is how a binary that cannot start
+    // was reported as valid.
+    bool hermetic() const { return loader.has_value(); }
 };
 
 namespace detail {
@@ -80,6 +116,14 @@ std::string canonical_contract(const RuntimeBinding& binding) {
     append_field(out, binding.hostLibc.value_or(""));
     for (auto const& p : binding.libraryDirs)
         append_field(out, p.generic_string());
+    // The farm participates in the hash because it participates in the
+    // artifact: it lands in DT_RPATH, so a build made against one farm is not
+    // interchangeable with a build made against another. `declared` is in for
+    // the same reason — a SubOS that gains self-description changes what the
+    // build knows, and the fast path must not reuse the older answer.
+    append_field(out, binding.declared ? "declared" : "undeclared");
+    for (auto const& p : binding.searchDirs)
+        append_field(out, p.generic_string());
     for (auto const& provider : binding.providerBindings)
         append_field(out, provider);
     for (auto const& d : binding.environment) {
@@ -213,22 +257,51 @@ resolve_runtime_binding(
             selection.subosName, out.subosDir.string()));
     }
 
+    // CONTRADICTION vs ABSENCE. The check above is a contradiction: the user
+    // named a SubOS that is not there, and no amount of degrading makes that
+    // request satisfiable. Everything below is absence — some facts are
+    // unavailable, the rest of the build is unaffected — so it degrades.
+    //
+    // The distinction is not academic. Collapsing it is what made every
+    // `mcpp build` and `mcpp test` on Windows fail with a message about GL
+    // drivers (openxlings/xlings#543), and it is the same shape as the index
+    // floor incident: DATA THAT IS MISSING OR NEWER MUST NOT INVALIDATE THE
+    // PROGRAM THAT READS IT.
+    auto note = [&](std::string message) {
+        if (!out.note.empty()) out.note += "\n";
+        out.note += std::move(message);
+    };
+
     auto info = mcpp::xlings::subos::read(out.subosDir);
+    out.declared = info.present;
     if (!info.present) {
-        return std::unexpected(std::format(
-            "selected SubOS '{}' cannot provide a RuntimeBinding: {}",
-            selection.subosName, info.note));
-    }
-    if (info.schema != mcpp::xlings::subos::kSupportedSchema) {
-        return std::unexpected(std::format(
-            "selected SubOS '{}' uses runtime contract schema {}, but this "
-            "mcpp requires schema {}; update xlings/mcpp before building",
+        note(std::format(
+            "SubOS '{}' does not describe itself: {}\n"
+            "       Runtime facts (identity, loader, declared environment) are "
+            "unavailable: runtime rules report `inconclusive` rather than a "
+            "verdict, and a program launched from here gets no environment this "
+            "SubOS declares.\n"
+            "       Where the C runtime comes from a payload, there is now no "
+            "declared runtime to bind to — mcpp declines to guess a version, so "
+            "the link falls back to the host and the hermeticity check will say "
+            "so. `xlings self update` writes the block.",
+            selection.subosName,
+            info.note.empty() ? "no `subos_info` block" : info.note));
+    } else if (info.schema > mcpp::xlings::subos::kSupportedSchema) {
+        // Mirrors `subos_info::read`, which already reads a HIGHER schema and
+        // says so. A consumer stricter than its own reader is a time bomb:
+        // the day xlings writes schema 2, an equality check stops every build
+        // on every platform.
+        note(std::format(
+            "SubOS '{}' declares runtime contract schema {}, newer than the {} "
+            "this mcpp understands; using the fields it knows",
             selection.subosName, info.schema,
             mcpp::xlings::subos::kSupportedSchema));
     }
-    if (info.runtime.empty()) {
-        return std::unexpected(std::format(
-            "selected SubOS '{}' has no runtime identity in subos_info.runtime",
+    if (info.present && info.runtime.empty()) {
+        note(std::format(
+            "SubOS '{}' has no runtime identity in subos_info.runtime; runtime "
+            "rules cannot be evaluated for artifacts built here",
             selection.subosName));
     }
 
@@ -247,11 +320,27 @@ resolve_runtime_binding(
         out.libc = info.runtime;
         if (!info.hostGlibc.empty()) out.hostLibc = info.hostGlibc;
 
-        // Resolve the selected SubOS VIEW to its immutable payload.  The view
-        // already embodies RuntimeSelection, so following these exact links is
-        // not payload discovery and cannot choose another installed version.
+        // ONE traversal, TWO answers.
+        //
+        //   searchDirs   the view directory itself — the farm, where every
+        //                library this environment installed is reachable by
+        //                SONAME (`-lGL` already resolves here, because
+        //                `--sysroot=<subos>` makes it the linker's default).
+        //   libraryDirs  the immutable payload the view's libc RESOLVES to.
+        //
+        // Deriving both here rather than in two places is the point: the
+        // layout knowledge (`lib64` before `lib`) exists exactly once.
+        //
+        // The view already embodies RuntimeSelection, so following these exact
+        // links is not payload discovery and cannot choose another installed
+        // version.
         std::vector<std::filesystem::path> candidates{
             out.subosDir / "lib64", out.subosDir / "lib"};
+        for (auto const& candidate : candidates) {
+            std::error_code fec;
+            if (std::filesystem::is_directory(candidate, fec))
+                out.searchDirs.push_back(candidate.lexically_normal());
+        }
         for (auto const& candidate : candidates) {
             std::error_code lec;
             auto libc = candidate / "libc.so.6";
@@ -322,6 +411,11 @@ std::string serialize_runtime_binding(const RuntimeBinding& binding) {
     j["library_dirs"] = nlohmann::json::array();
     for (auto const& path : binding.libraryDirs)
         j["library_dirs"].push_back(path.generic_string());
+    j["declared"] = binding.declared;
+    j["note"] = binding.note;
+    j["search_dirs"] = nlohmann::json::array();
+    for (auto const& path : binding.searchDirs)
+        j["search_dirs"].push_back(path.generic_string());
     j["environment"] = nlohmann::json::array();
     for (auto const& decl : binding.environment)
         j["environment"].push_back({
@@ -391,6 +485,11 @@ deserialize_runtime_binding(std::string_view encoded) {
         if (auto it = j.find("library_dirs"); it != j.end() && it->is_array())
             for (auto const& v : *it) if (v.is_string())
                 out.libraryDirs.emplace_back(v.get<std::string>());
+        out.declared = j.value("declared", false);
+        out.note = j.value("note", "");
+        if (auto it = j.find("search_dirs"); it != j.end() && it->is_array())
+            for (auto const& v : *it) if (v.is_string())
+                out.searchDirs.emplace_back(v.get<std::string>());
         if (auto it = j.find("environment"); it != j.end() && it->is_array()) {
             for (auto const& v : *it) {
                 if (!v.is_object()) continue;
@@ -456,8 +555,15 @@ deserialize_runtime_binding(std::string_view encoded) {
             : mcpp::xlings::runtime::RuntimeSelection::Source::DefaultPolicy;
         out.selection.subosName = s.value("name", "default");
         out.selection.ownerRoot = s.value("owner_root", "");
-        if (out.schema == 0 || out.runtimeId.empty()
-            || out.contractHash.empty() || out.subosDir.empty())
+        // Completeness is conditional on `declared`. An UNDECLARED binding
+        // legitimately has schema 0 and no runtime identity — that is what
+        // "the SubOS said nothing" looks like — so demanding those fields
+        // would make every cached degraded binding undecodable and send the
+        // build back down the slow path forever. The hash still has to match,
+        // which is what actually proves the record was not tampered with.
+        if (out.contractHash.empty() || out.subosDir.empty())
+            return std::unexpected("cached RuntimeBinding is incomplete");
+        if (out.declared && (out.schema == 0 || out.runtimeId.empty()))
             return std::unexpected("cached RuntimeBinding is incomplete");
         if (detail::hash_contract(detail::canonical_contract(out))
             != out.contractHash)