fix: remove module-boundary shapes that crash clang on the MSVC ABI; correct the hook environment

Windows CI (clang 20.1.7, x86_64-pc-windows-msvc) crashed compiling
directives.cppm. The change introduced constructs of the kind src/pack/pack.cppm
records crashing that toolchain: pointers to members of an imported type and a
std::span over an exported constexpr array, plus optional-bearing types in an
exported interface. They are replaced by plain code: `windows_choice_problem`
states the accepted values once for both parsers, the directive check and apply
are per field, `invocation_env` returns a plain struct, ScopedInvocationEnv
keeps plain members, and the hook scope uses six ScopedEnv locals.

tests/e2e/648 measured that a dependency's install hook runs before the
toolchain is resolved, because prepare resolves it after the dependency graph.
The hook therefore receives the build's target and empty toolchain names; the
code comment, docs/22, docs/32, the CHANGELOG and the design record now state
this, and 648 asserts it, including that inherited values do not leak through.

Test fixes: 645 resolves its helper directory before changing directory and
drives `mcpp run` through MCPP_TOOLCHAIN; 647 writes each manifest to its own
package directory.

Author: speak-agent

.agents/docs/2026-09-12-engine-gaps-after-the-sdk-batch.md

@@ -546,7 +546,19 @@ code, and what was built instead.
    rule: the requested triple, or the host triple for a native build. The six
    values are computed by `install_hook_env`, from which the build-program
    environment also takes them, in their existing order, so no build program's
-   re-run key changes.
+   re-run key changes. The toolchain values are empty while a dependency
+   installs, which §2.3 assumed otherwise: `tc` is resolved after the dependency
+   graph, because a package in the graph may supply a target-side layer, so no
+   compiler or standard library has been decided when a dependency's hook runs.
+   Measured with tests/e2e/648, whose hook compiled in an empty `compiler=` and
+   `stdlib=` beside the host's `os=linux`. Resolving the toolchain before
+   installation is the reorder the engine deliberately does not make, and a
+   guessed value would let a hook build the wrong variant, so the variables are
+   emitted empty, which also keeps a value inherited from a parent process out
+   of the hook. Neither §2.4 criterion holds as written: the refusal follows the
+   hook (item 3), and a hook cannot print a resolved `stdlibId`. What holds is
+   that the `c++-abi` refusal names both implementations before compilation, and
+   that the hook sees the build's target and never an inherited toolchain value.
 5. **§3.1, absent and empty on Windows.** The CRT defines `_putenv_s(key, "")` as
    removal, so the Windows branch already produced an absent
    `XLINGS_PROJECT_DIR`, and the two platforms did not disagree about global

CHANGELOG.md

@@ -82,11 +82,12 @@ Emscripten 链接产出的是首行为 `#!/usr/bin/env node` 的 JavaScript 启
   拒绝信息指出包与 feature,并给出满足它的表。依赖自己写的 `[target.<selector>.abi]` 被报告
   (`abi/dependency-table`)且不生效。
 
-### 安装钩子收到已解析的工具链(#613)
+### 安装钩子的环境与 `c++-abi` 的做法(#613)
 
-- 依赖包的安装钩子收到 `MCPP_COMPILER`、`MCPP_CXX_STDLIB`、`MCPP_TARGET`、`MCPP_TARGET_OS`、
-  `MCPP_TARGET_ARCH` 与 `MCPP_TARGET_ENV`,名称与取值同构建程序一致,由同一个函数计算。钩子可以据此拒绝
-  或诊断,但不得把某种变体构建进名称未体现该变体的存储目录。
+- 依赖包的安装钩子收到 `MCPP_TARGET`、`MCPP_TARGET_OS`、`MCPP_TARGET_ARCH` 与 `MCPP_TARGET_ENV`,名称
+  与规则同构建程序一致,由同一个函数计算。`MCPP_COMPILER` 与 `MCPP_CXX_STDLIB` 同样总是写出,但在依赖
+  安装时为空:工具链在依赖图之后才解析,此时没有可陈述的编译器与标准库。每个变量都显式写出,钩子不会读到
+  从父进程继承的值;钩子不得把某种变体构建进名称未体现该变体的存储目录。
 - 从源码构建静态库的包以 `requires = ["mcpp:c++-abi=<stdlib>"]` 声明它所针对的标准库;工具链解析出另一
   实现的工程被拒绝,拒绝信息指出两个实现。docs/06、docs/22 与 docs/32 记录这一做法。
 

docs/22-target-side.md

@@ -238,12 +238,12 @@ requires = ["mcpp:c++-abi=libstdc++"]
 ```
 
 A project whose toolchain resolves another `c++-abi` is then refused, naming
-both implementations, instead of failing at the link. The check follows the
-installation of the graph, so the install hook also receives the resolved values
-as `MCPP_CXX_STDLIB` and `MCPP_COMPILER` ([32 — Authoring a
-Payload](32-authoring-a-payload.md)) and can refuse before it compiles anything.
-It must not build a different variant into the same store directory, because
-the first consumer would then decide the variant for every later one.
+both implementations, instead of failing at the link. The check runs once the
+toolchain is resolved, which is after the dependency graph is installed, so the
+install hook has already run; the hook receives the build's target but no
+toolchain values ([32 — Authoring a Payload](32-authoring-a-payload.md)). It
+must not build a different variant into the same store directory, because the
+first consumer would then decide the variant for every later one.
 
 ### Standard Library Module Sources
 

docs/32-authoring-a-payload.md

@@ -72,27 +72,30 @@ those two doing more.
 ### The environment an install hook receives (mcpp 2026.9.12.2+)
 
 When mcpp installs a package a project depends on, the package's `install()`
-runs with the resolved toolchain and target in its environment, under the names
-and with the values a build program receives ([build.mcpp](30-build-mcpp.md)):
+runs with the build's target in its environment, under the names and by the rule
+a build program uses ([build.mcpp](30-build-mcpp.md)): every variable is present,
+and empty when it has no value, so a hook never reads a value inherited from the
+process that started mcpp.
 
-| Variable | Value |
+| Variable | Value while a dependency installs |
 |---|---|
-| `MCPP_COMPILER` | `gcc`, `clang` or `msvc` |
-| `MCPP_CXX_STDLIB` | `libstdc++`, `libc++` or `msvc-stl` |
 | `MCPP_TARGET` | the target triple the build was asked for, or the host triple for a native build |
 | `MCPP_TARGET_OS`, `MCPP_TARGET_ARCH`, `MCPP_TARGET_ENV` | the segments of that triple |
+| `MCPP_COMPILER`, `MCPP_CXX_STDLIB` | empty |
 
-A value is empty when it does not apply. On Windows an empty variable is an
-absent one, and `os.getenv` answers `nil` for it. The hook of a toolchain payload
-receives none of these variables, because no toolchain has been resolved while it
-installs.
+The toolchain values are empty because the toolchain is resolved after the
+dependency graph: a package in the graph may supply a target-side layer, so no
+compiler or standard library has been decided when a dependency installs, and a
+hook that guessed one could build the wrong variant. On Windows an empty variable
+is an absent one, and `os.getenv` answers `nil` for it. The hook of a toolchain
+payload receives none of these variables.
 
-A hook may use the values to refuse or to diagnose. It must not build a variant
+A hook may use the target to refuse or to diagnose. It must not build a variant
 into a store directory whose name does not state the variant: the store is keyed
 by package and version, so the first consumer would decide the variant for every
-later one. A package compiled against one C++ standard library declares that
-instead, with `requires = ["mcpp:c++-abi=libstdc++"]`
-([22 — The Target Side](22-target-side.md)).
+later one. A package compiled against one C++ standard library states that with
+`requires = ["mcpp:c++-abi=libstdc++"]`, which is checked once the toolchain is
+resolved ([22 — The Target Side](22-target-side.md)).
 
 ## The four things a descriptor must get right
 

docs/zh/22-target-side.md

@@ -202,8 +202,8 @@ requires = ["mcpp:c++-abi=libstdc++"]
 ```
 
 工具链解析出另一个 `c++-abi` 的工程随后会被拒绝,拒绝信息同时指出两个实现,而不是在链接时失败。这项检查
-在依赖图安装之后进行,因此安装钩子还会通过 `MCPP_CXX_STDLIB` 与 `MCPP_COMPILER` 收到解析结果
-([32 —— 编写载荷](32-authoring-a-payload.md)),可以在编译任何东西之前拒绝。钩子不得把另一种变体构建进
+在工具链解析之后进行,而工具链在依赖图安装之后才解析,因此检查时安装钩子已经运行过;钩子收到本次构建的
+目标,但收不到工具链的取值([32 —— 编写载荷](32-authoring-a-payload.md))。钩子不得把另一种变体构建进
 同一个存储目录,否则第一个消费者就会替之后所有消费者决定变体。
 
 ### 标准库模块源

docs/zh/32-authoring-a-payload.md

@@ -66,22 +66,24 @@ end
 
 ### 安装钩子收到的环境(mcpp 2026.9.12.2+)
 
-mcpp 安装工程所依赖的包时,该包的 `install()` 在环境中收到已解析的工具链与目标,变量名与取值同构建程序
-收到的一致([build.mcpp](30-build-mcpp.md)):
+mcpp 安装工程所依赖的包时,该包的 `install()` 在环境中收到本次构建的目标,变量名与规则同构建程序一致
+([build.mcpp](30-build-mcpp.md)):每个变量都显式写出,没有取值时为空,因此钩子不会读到从启动 mcpp 的
+进程继承来的值。
 
-| 变量 | 取值 |
+| 变量 | 依赖安装时的取值 |
 |---|---|
-| `MCPP_COMPILER` | `gcc`、`clang` 或 `msvc` |
-| `MCPP_CXX_STDLIB` | `libstdc++`、`libc++` 或 `msvc-stl` |
 | `MCPP_TARGET` | 本次构建所请求的目标三元组;原生构建时为宿主三元组 |
 | `MCPP_TARGET_OS`、`MCPP_TARGET_ARCH`、`MCPP_TARGET_ENV` | 该三元组的各段 |
+| `MCPP_COMPILER`、`MCPP_CXX_STDLIB` | 空 |
 
-不适用的取值为空。在 Windows 上空变量即不存在的变量,`os.getenv` 对它返回 `nil`。工具链载荷的钩子不会
-收到这些变量,因为它安装时尚未解析出任何工具链。
+工具链的取值为空,因为工具链在依赖图之后才解析:依赖图中的包可能提供目标侧的层,所以依赖安装时编译器与
+标准库都尚未确定,而猜测一个取值的钩子可能构建出错误的变体。在 Windows 上空变量即不存在的变量,
+`os.getenv` 对它返回 `nil`。工具链载荷的钩子不会收到这些变量。
 
-钩子可以用这些值来拒绝或给出诊断,但不得把某种变体构建进名称未体现该变体的存储目录:存储目录按包名与版本
-区分,否则第一个消费者就会替之后所有消费者决定变体。针对某一个 C++ 标准库编译的包应改为声明这一点,即
-`requires = ["mcpp:c++-abi=libstdc++"]`([22 —— 目标侧](22-target-side.md))。
+钩子可以用目标来拒绝或给出诊断,但不得把某种变体构建进名称未体现该变体的存储目录:存储目录按包名与版本
+区分,否则第一个消费者就会替之后所有消费者决定变体。针对某一个 C++ 标准库编译的包应以
+`requires = ["mcpp:c++-abi=libstdc++"]` 陈述这一点,该需求在工具链解析之后检查
+([22 —— 目标侧](22-target-side.md))。
 
 ## 描述符必须做对的四件事
 

modules/buildmcpp/src/directives.cppm

@@ -879,17 +879,21 @@ void apply(mcpp::manifest::Manifest& m, const Directives& d) {
     // A named executable's subsystem and entry. `target_directive_error` has
     // refused every value that names no executable, so the conditions below
     // only keep this function total.
-    for (auto [slot, member] : {
-             std::pair{Slot::WindowsSubsystem, &mcpp::manifest::Target::windowsSubsystem},
-             std::pair{Slot::WindowsEntry,     &mcpp::manifest::Target::windowsEntry}}) {
-        for (auto const& entry : d.at(slot)) {
-            auto sep = entry.rfind(':');
-            if (sep == std::string::npos) continue;
-            const auto name = entry.substr(0, sep);
-            for (auto& t : m.targets)
-                if (t.name == name && t.kind == mcpp::manifest::Target::Binary)
-                    t.*member = entry.substr(sep + 1);
-        }
+    for (auto const& entry : d.at(Slot::WindowsSubsystem)) {
+        const auto sep = entry.rfind(':');
+        if (sep == std::string::npos) continue;
+        const auto name = entry.substr(0, sep);
+        for (auto& t : m.targets)
+            if (t.name == name && t.kind == mcpp::manifest::Target::Binary)
+                t.windowsSubsystem = entry.substr(sep + 1);
+    }
+    for (auto const& entry : d.at(Slot::WindowsEntry)) {
+        const auto sep = entry.rfind(':');
+        if (sep == std::string::npos) continue;
+        const auto name = entry.substr(0, sep);
+        for (auto& t : m.targets)
+            if (t.name == name && t.kind == mcpp::manifest::Target::Binary)
+                t.windowsEntry = entry.substr(sep + 1);
     }
 
     // Build-graph nodes. Decoded here rather than at parse time so the cache
@@ -931,72 +935,71 @@ std::optional<mcpp::manifest::BuildAction> decode_action(std::string_view payloa
     }
 }
 
-std::string target_directive_error(const mcpp::manifest::Manifest& m, const Directives& d) {
-    struct Field {
-        Slot                              slot;
-        std::string_view                  wire;
-        std::string_view                  key;
-        std::span<const std::string_view> accepted;
-        std::string mcpp::manifest::Target::* member;
-    };
-    const Field fields[] = {
-        {Slot::WindowsSubsystem, "windows-subsystem", "windows_subsystem",
-         mcpp::manifest::kWindowsSubsystems, &mcpp::manifest::Target::windowsSubsystem},
-        {Slot::WindowsEntry, "windows-entry", "windows_entry",
-         mcpp::manifest::kWindowsEntries, &mcpp::manifest::Target::windowsEntry},
-    };
-    for (auto const& f : fields) {
-        std::map<std::string, std::string> stated;   // target name -> value
-        for (auto const& entry : d.at(f.slot)) {
-            auto sep = entry.rfind(':');
-            if (sep == std::string::npos || sep == 0 || sep + 1 == entry.size())
-                return std::format(
-                    "build.mcpp emitted `mcpp:{}={}`, which is not `<target>:<value>`.",
-                    f.wire, entry);
-            const std::string name  = entry.substr(0, sep);
-            const std::string value = entry.substr(sep + 1);
-            if (std::ranges::find(f.accepted, std::string_view(value)) == f.accepted.end()) {
-                std::string list;
-                for (auto a : f.accepted)
-                    list += (list.empty() ? "" : ", ") + std::format("\"{}\"", a);
-                return std::format(
-                    "build.mcpp emitted `mcpp:{}={}`, and \"{}\" is not one of {}.",
-                    f.wire, entry, value, list);
-            }
-            const mcpp::manifest::Target* target = nullptr;
+// One of the two named-target directives; `subsystem` selects the field.
+static std::string named_target_error(const mcpp::manifest::Manifest& m,
+                                      const std::vector<std::string>& entries,
+                                      std::string_view wire, std::string_view key,
+                                      bool subsystem) {
+    std::map<std::string, std::string> stated;   // target name -> value
+    for (auto const& entry : entries) {
+        const auto sep = entry.rfind(':');
+        if (sep == std::string::npos || sep == 0 || sep + 1 == entry.size())
+            return std::format(
+                "build.mcpp emitted `mcpp:{}={}`, which is not `<target>:<value>`.",
+                wire, entry);
+        const std::string name  = entry.substr(0, sep);
+        const std::string value = entry.substr(sep + 1);
+        if (auto list = mcpp::manifest::windows_choice_problem(subsystem, value);
+            !list.empty())
+            return std::format(
+                "build.mcpp emitted `mcpp:{}={}`, and \"{}\" is not one of {}.",
+                wire, entry, value, list);
+        const mcpp::manifest::Target* target = nullptr;
+        for (auto const& t : m.targets)
+            if (t.name == name) { target = &t; break; }
+        if (target == nullptr) {
+            std::string names;
             for (auto const& t : m.targets)
-                if (t.name == name) { target = &t; break; }
-            if (!target) {
-                std::string names;
-                for (auto const& t : m.targets)
-                    names += (names.empty() ? "" : ", ") + t.name;
-                return std::format(
-                    "build.mcpp emitted `mcpp:{}={}`, and package `{}` declares no "
-                    "target named `{}` (its targets: {}).",
-                    f.wire, entry, m.package.name, name, names.empty() ? "none" : names);
-            }
-            if (target->kind != mcpp::manifest::Target::Binary)
-                return std::format(
-                    "build.mcpp emitted `mcpp:{}={}`, and `{}` applies to an executable "
-                    "(`kind = \"bin\"`); target `{}` is not one.",
-                    f.wire, entry, f.key, name);
-            if (const std::string& declared = target->*f.member;
-                !declared.empty() && declared != value)
-                return std::format(
-                    "build.mcpp emitted `mcpp:{}={}`, and mcpp.toml declares "
-                    "`[targets.{}] {} = \"{}\"`. One of the two has to change.",
-                    f.wire, entry, name, f.key, declared);
-            if (auto [it, fresh] = stated.try_emplace(name, value);
-                !fresh && it->second != value)
-                return std::format(
-                    "build.mcpp emitted `mcpp:{}` twice for target `{}`, as \"{}\" and "
-                    "as \"{}\".",
-                    f.wire, name, it->second, value);
+                names += (names.empty() ? "" : ", ") + t.name;
+            return std::format(
+                "build.mcpp emitted `mcpp:{}={}`, and package `{}` declares no "
+                "target named `{}` (its targets: {}).",
+                wire, entry, m.package.name, name,
+                names.empty() ? std::string("none") : names);
         }
+        if (target->kind != mcpp::manifest::Target::Binary)
+            return std::format(
+                "build.mcpp emitted `mcpp:{}={}`, and `{}` applies to an executable "
+                "(`kind = \"bin\"`); target `{}` is not one.",
+                wire, entry, key, name);
+        const std::string& declared =
+            subsystem ? target->windowsSubsystem : target->windowsEntry;
+        if (!declared.empty() && declared != value)
+            return std::format(
+                "build.mcpp emitted `mcpp:{}={}`, and mcpp.toml declares "
+                "`[targets.{}] {} = \"{}\"`. One of the two has to change.",
+                wire, entry, name, key, declared);
+        auto found = stated.find(name);
+        if (found == stated.end())
+            stated.emplace(name, value);
+        else if (found->second != value)
+            return std::format(
+                "build.mcpp emitted `mcpp:{}` twice for target `{}`, as \"{}\" and "
+                "as \"{}\".",
+                wire, name, found->second, value);
     }
     return {};
 }
 
+std::string target_directive_error(const mcpp::manifest::Manifest& m, const Directives& d) {
+    if (auto e = named_target_error(m, d.at(Slot::WindowsSubsystem),
+                                    "windows-subsystem", "windows_subsystem", true);
+        !e.empty())
+        return e;
+    return named_target_error(m, d.at(Slot::WindowsEntry),
+                              "windows-entry", "windows_entry", false);
+}
+
 std::string action_error(const Directives& d) {
     for (auto const& payload : d.at(Slot::Actions)) {
         // The typed API sets this when an argv did not fit its fixed buffer.