fix(e2e,backend): fixture path spelling, a check that could only fail, and a guard

Three things the local suite and a read-through caught:

* 255/257/259 interpolated `$(host_path …)` straight into a manifest heredoc.
  00_fixture_path_hygiene requires the value to come from a named `*_HOST`
  variable, and the rule is Windows': a shell-spelled /tmp path is read by a
  native mcpp.exe as "root of the current drive".
* 259 tested `[[ -f "$pkg/lib/"*"/libmathkit.dylib" ]]`. `[[ ]]` does not
  path-expand, so that compares against a literal string containing an asterisk
  and is false for every real package — a check that can only fail, which on
  macOS-only coverage would have looked like a product bug.
* the import-library flag substituted `{}` without checking it is there. Both
  dialect rows have one; a row without it would have thrown at `replace(npos)`
  instead of simply not emitting a flag.

Also documents, in docs/12 (+ zh), how much of this is verified and where —
including the row that is honest rather than flattering: the REAL old-client
check has been run by hand and not by CI, because the boot entry each job
bootstraps from is an xvm shim that answers "not installed" under the e2e
environment.

Local suite after this: 236 passed, 1 failed, 14 skipped. The remaining failure
is 22_doctor_cache_publish, and the previous RELEASE binary fails it identically
on this machine — a local environment fact, not a regression.

Author: speak-agent

docs/12-binary-distribution.md

@@ -333,3 +333,50 @@ warning: secret.cppm is an implementation partition, and the published interface
 > Build order was unconstrained: GCC and macOS clang recovered through their own
 > dependency scan, Windows clang failed with `failed to read compiled module`.
 > If you have been avoiding implementation partitions on Windows, that was why.
+
+### A partition mcpp cannot classify
+
+`[scan_overrides."<glob>"]` says which modules a file provides and has nowhere to
+say whether the declaration carries `export`; a P1689 scanner may omit
+`is-interface`. Either way the source is published — the consumer cannot build the
+BMI without it — and `mcpp pack` says which of the two situations you are in:
+
+```
+warning: secret.cppm provides a module PARTITION and mcpp cannot tell which kind:
+         the unit is declared in `[scan_overrides]`, which has nowhere to say
+         whether the declaration carries `export`, …
+```
+
+> Until 2026.8.17.2 that arrived as "it is an interface" — the answer that
+> produces **no** warning — so an implementation partition declared that way was
+> published in silence. Publishing too few sources fails the consumer's compile
+> and names the module; publishing too many ships private source and nothing
+> fails at all. Unknown has to be loud.
+
+## How much of this is verified, and where
+
+The e2e suite gates each test on host capabilities, so "the suite is green" and
+"this ran" are different statements. What runs where:
+
+| claim | linux | macOS | windows |
+|---|---|---|---|
+| layout, both interface modes, closure, the two gates, workspace root, named target, `sources = []`, bare-triple predicate | ✅ | ✅ | ✅ |
+| fat package, two legs one artifact name (`gnu` + `musl`) | ✅ | *impossible* | — |
+| fat package, two legs **two** artifact names (`msvc` + `mingw`) | — | *impossible* | ✅ |
+| fat package crossing an OS boundary (a PE leg) | ✅ | — | — |
+| `lib.exe /REMOVE:` really removing | — | — | ✅ |
+| PE shared library: build, pack, link, run | ✅ (wine) | — | — |
+| Mach-O shared library relocating out of its build tree | — | ✅ | — |
+| MSVC refusing `kind = "shared"` for the export reason | — | — | ✅ |
+| a released mcpp consuming a package this one produced | local only | local only | local only |
+
+*impossible* is not a gap: a macOS host can serve exactly one target
+(`host_can_serve`, `registry.cppm`), so a package with two legs cannot be produced
+there at all.
+
+The last row is honest about a real hole: each CI job bootstraps from a released
+mcpp, but that entry is an xvm **shim**, and under the e2e suite's environment it
+answers "not installed". So the static half of the old-client check (the generated
+manifest uses no section a previous mcpp cannot read) runs everywhere, and the
+real half — build against the package with the previous release — has been run by
+hand, not by CI.

docs/zh/12-binary-distribution.md

@@ -301,3 +301,44 @@ warning: secret.cppm is an implementation partition, and the published interface
 > 的单元」到「定义分区的单元」的边,构建顺序无约束:GCC 与 macOS clang 靠各自的
 > 依赖扫描兜住了,**Windows clang 以 `failed to read compiled module` 失败**。
 > 如果你一直在 Windows 上回避实现分区,原因就是这个。
+
+### mcpp 判不出类别的分区
+
+`[scan_overrides."<glob>"]` 说的是文件提供哪些模块,**没有地方能说**那条声明是否
+带 `export`;P1689 扫描器也可能省略 `is-interface`。两种情况下源码都会被发布 ——
+消费者没有它就编不出 BMI —— 而 `mcpp pack` 会告诉你你处在哪一种:
+
+```
+warning: secret.cppm provides a module PARTITION and mcpp cannot tell which kind:
+         the unit is declared in `[scan_overrides]`, which has nowhere to say
+         whether the declaration carries `export`, …
+```
+
+> 在 2026.8.17.2 之前,这种情况以「它是接口」到达 —— 那个**不产生任何警告**的答案 ——
+> 于是这样声明的实现分区被一声不响地发布了。**发布得太少**会让消费者编译失败并点名
+> 模块;**发布得太多**会把私有源码发出去,而什么都不会失败。未知必须出声。
+
+## 这些说法验证到哪一步、在哪台机器上
+
+e2e 套件按宿主能力给每条测试开门,所以「套件是绿的」和「这条跑了」是两句不同的话。
+实际跑在哪里:
+
+| 说法 | linux | macOS | windows |
+|---|---|---|---|
+| 布局、两种接口模式、闭包、两道闸门、workspace 根、指名 target、`sources = []`、裸三元组谓词 | ✅ | ✅ | ✅ |
+| 胖包,两条腿**同一个**产物名(`gnu` + `musl`) | ✅ | *不可能* | — |
+| 胖包,两条腿**两个**产物名(`msvc` + `mingw`) | — | *不可能* | ✅ |
+| 跨 OS 边界的胖包(一条 PE 腿) | ✅ | — | — |
+| `lib.exe /REMOVE:` 真的删掉了 | — | — | ✅ |
+| PE 共享库:产出、打包、链接、运行 | ✅(wine) | — | — |
+| Mach-O 共享库离开构建树仍可加载 | — | ✅ | — |
+| MSVC 以「导出」为理由拒绝 `kind = "shared"` | — | — | ✅ |
+| 已发布的 mcpp 消费本版产出的包 | 仅本机 | 仅本机 | 仅本机 |
+
+*不可能* 不是缺口:macOS 宿主只能服务一个 target(`host_can_serve`,
+`registry.cppm`),那里根本产不出两条腿的包。
+
+最后一行如实记录一个真的洞:每个 CI job 都从一份已发布的 mcpp 自举,但那个入口是
+xvm 的 **shim**,在 e2e 套件改过的环境里它回答「未安装」。所以老客户端检查的
+**静态那半**(生成的 manifest 不含任何旧 mcpp 读不了的段)到处都跑,而**真实那半** ——
+用上一版发布的 mcpp 去构建这个包 —— 是**手工跑的,不是 CI 跑的**。

src/build/ninja_backend.cppm

@@ -1826,10 +1826,17 @@ std::string emit_ninja_string(const BuildPlan& plan) {
         // agrees with — the name belongs to plan.cppm's import_library_for, and
         // this is how it gets to the command. The SPELLING belongs to the
         // dialect table, same as `archiveRemoveArg`.
-        if (!lu.importLibrary.empty() && !dial.sharedImportLibArg.empty()) {
+        if (!lu.importLibrary.empty()) {
             std::string arg{ dial.sharedImportLibArg };
-            arg.replace(arg.find("{}"), 2, escape_ninja_path(lu.importLibrary));
-            out_line += "  implib_flag = " + arg + "\n";
+            // `{}` or nothing: a row without the placeholder cannot say WHERE to
+            // write, so emitting its bare text would hand the linker a flag with
+            // no argument. Skipping is the honest reading of an empty row, and
+            // the implicit output above then fails loudly as a missing file
+            // rather than quietly linking against a stale one.
+            if (auto at = arg.find("{}"); at != std::string::npos) {
+                arg.replace(at, 2, escape_ninja_path(lu.importLibrary));
+                out_line += "  implib_flag = " + arg + "\n";
+            }
         }
         {
             // Per-unit C++ runtime link, by ROLE. The kind→role map is the

tests/e2e/255_pack_library_msvc_archiver.sh

@@ -119,12 +119,13 @@ EOF
 # outright. That is a real limitation of the generated manifest (recorded in
 # docs/12), and it is NOT what this test is about — pinning cl here would make
 # 255 fail for a reason that has nothing to do with the archiver.
+PKG_HOST="$(host_path "$TMP/mathkit/$pkg")"
 cat > app/mcpp.toml <<EOF
 [package]
 name    = "app"
 version = "0.1.0"
 [dependencies]
-mathkit = { path = "$(host_path "$TMP/mathkit/$pkg")" }
+mathkit = { path = "$PKG_HOST" }
 [targets.app]
 kind = "bin"
 main = "src/main.cpp"

tests/e2e/257_shared_library_pe.sh

@@ -98,12 +98,13 @@ cat > app/src/main.cpp <<'EOF'
 import mathkit;
 int main(){ std::printf("ok=%d\n", mk::answer()); return 0; }
 EOF
+PKG_HOST="$(host_path "$pkg")"
 cat > app/mcpp.toml <<EOF
 [package]
 name    = "app"
 version = "0.1.0"
 [dependencies]
-mathkit = { path = "$(host_path "$pkg")" }
+mathkit = { path = "$PKG_HOST" }
 [targets.app]
 kind = "bin"
 main = "src/main.cpp"

tests/e2e/259_shared_library_macho.sh

@@ -80,8 +80,11 @@ pkgrel="$(find target/dist -maxdepth 1 -type d -name 'mathkit-0.1.0*' | head -1)
 # OUT of the producer's tree, so the next step can delete that tree entirely.
 pkg="$TMP/pkg"
 cp -R "$TMP/mathkit/$pkgrel" "$pkg"
-[[ -f "$pkg/lib/"*"/libmathkit.dylib" ]] 2>/dev/null || {
-    find "$pkg" -type f -o -type l
+# `find`, not `[[ -f "$pkg/lib/"*"/libmathkit.dylib" ]]`: inside `[[ ]]` the `*`
+# is not path-expanded, so that form tests a literal string containing an
+# asterisk and is false for every real package — a check that can only fail.
+[[ -n "$(find "$pkg/lib" -name 'libmathkit.dylib' | head -1)" ]] || {
+    find "$pkg" \( -type f -o -type l \)
     echo "FAIL: no dylib in the package"; exit 1; }
 
 # ── 4. the producer's build tree is deleted, then the consumer runs ──────
@@ -97,12 +100,13 @@ cat > app/src/main.cpp <<'EOF'
 import mathkit;
 int main(){ std::printf("ok=%d\n", mk::answer()); return 0; }
 EOF
+PKG_HOST="$(host_path "$pkg")"
 cat > app/mcpp.toml <<EOF
 [package]
 name    = "app"
 version = "0.1.0"
 [dependencies]
-mathkit = { path = "$(host_path "$pkg")" }
+mathkit = { path = "$PKG_HOST" }
 [targets.app]
 kind = "bin"
 main = "src/main.cpp"