release: 2026.9.5.2

The version annotations in the manual said 2026.9.6 while the release lands
today, so they name the version that actually carries them. `mcpp.toml` and
`MCPP_VERSION` move together, as `01_help_and_version.sh` requires.

The CHANGELOG's Unreleased section described the doctor's `nvcc --dryrun`
check as a shipped feature. That check left the engine in this same batch — the
reading was right and the place was wrong — so the entry is rewritten to say
where it went rather than to announce something the release does not contain.

Author: speak-agent

CHANGELOG.md

@@ -5,22 +5,98 @@
 
 ## [Unreleased]
 
-### `mcpp self doctor` 报出设备编译器够不到自己的后端
-
-一个 CUDA 工具包可以安装完整、就在 `PATH` 上,而设备代码仍然在第一个阶段失败。
-nvcc 以裸名调用 `cicc`、`cudafe++`、`ptxas`、`fatbinary`,依赖的是它自己从紧邻
-其二进制的 `nvcc.profile` 前置进来的一条 `PATH`。Debian 系打包把那个 profile
-做成指向 `/etc` 的符号链接,于是任何替换了 `/etc` 的容器或沙箱都会移除它,
-nvcc 沿用环境原有的 `PATH` 并报出 `sh: 1: cicc: not found` —— 这条消息既不提
-nvcc 也不提 profile,而工具包一样不缺,所以显而易见的检查全部通过。
-
-判据取自 nvcc 自己:`--dryrun` 打印它将要运行的各个阶段与它将要使用的 `PATH`,
-而不编译任何东西。mcpp 解析这份计划,逐个解析其中的裸名,报出第一个解析不到的。
-一次没有产生计划的 dryrun(没有 nvcc,或输出不是一份计划)不产生任何结论 ——
-与宿主编译器上界那条检查同一条原则:一个够不到答案的探测不应当发明一个。
-
-这是本轮把发布物放进沙箱验证时暴露出来的:示例在宿主上跑通,在 `--sandbox`
-里失败,而唯一的差别就是那条 `PATH`。
+## [2026.9.5.2] — 2026-09-05
+
+### ⭐⭐ 在编译任何东西之前比较机器的下界
+
+有些机器事实**限定**了能为它构建什么,而忽略它们时,失败到得很晚。本轮的样本:
+设备运行时不得新于它将运行其上的驱动;当它更新时,构建与链接都干净通过,程序在
+第一次分配处失败,消息里既不提工具包也不提驱动。
+
+两个数字在编译任何东西之前都是可知的。mcpp 不去问厂商的工具要它们 ——
+`tests/unit/test_runtime_contract` 禁止 `src/` 里出现厂商探针,而且这条规则是对的:
+一个学会跑一家厂商探针的引擎会学会跑四家。所以数字以**声明**抵达:
+
+```toml
+[[runtime.requirements]]
+kind  = "version-floor"
+value = "cuda.driver >= 12.0"
+```
+
+`mcpp.build.version_floor` 只做比较,**这个文件里不出现任何厂商名字**:
+`cuda.driver` 是流经的数据。第二种后端不需要改动它。
+
+### ⭐ 探针通道:`mcpp::fact` / `mcpp::floor`(协议 v7)
+
+构建程序陈述它**测得**的事实与它**需要**的下界,引擎比较并在不满足时给出两侧取值
+(`version-floor-unmet`)。这是让 CUDA 探针得以整体离开 `src/` 的那条通道 ——
+同样的读数现在由规则包产出,而它知道自己在跑哪个工具。
+
+因此 **`mcpp self doctor` 的设备一节与 `mcpp.toolchain.devicehost` 一并删除**。
+它读得对(载荷优先于宿主、`crt/host_config.h` 的宿主编译器上界、`nvcc --dryrun`
+的不可达阶段),但它不属于引擎。新增 `tests/unit/test_core_vendor_probes`
+在剥掉注释的源码上陈述这条性质,并自带分母:枚举到的文件太少即判失败。
+
+### 逐 glob 的加速器约束
+
+`[build] sources` 的条目可以带上它面向的加速器:
+
+```toml
+sources = [
+  "src/*.cppm",
+  { glob = "src/kernels/**/*.cu", accel = "cuda12.9+{sm_89}" },
+]
+```
+
+构建按它收窄;`--no-accel` 整条排除;不覆盖它的 `--accel` 被拒并点名两侧
+(`accel-mismatch`);匹配为空的约束被拒并点名该 glob —— 空匹配是笔误或搬走了的
+目录,而不是空操作。
+
+### `--accel` / `--no-accel` 现在也挂在 `run` 与 `test` 上
+
+此前只有 `build` 有,实测后果是一个工程的 CPU-only 变体**能构建却不能运行**。
+两个动词接受同样的两个开关,给出任一个都绕开各自的快路径 —— 缓存的产物是按上一次
+构建的轴产的。
+
+### 第二个编译器需要的两个答案
+
+`MCPP_TOOLCHAIN_SYSROOT` 与 `MCPP_TOOLCHAIN_BINUTILS_DIR` 陈述 mcpp 传给**它自己**
+那个编译器的 `--sysroot` 与 `-B`。规则包驱动一个 mcpp 并未解析的编译器时,那个
+编译器对环境一无所知:sub-OS 里 C 库不在 `/usr/include`,汇编器不在 `/usr/bin`,
+于是它遇到的第一个 `#include` 就失败。`hipcc`、`-fsycl-host-compiler`、任何会编译
+自己产物的生成器都有同一个缺口。
+
+`gcc::binutils_prefix_dir` 把 `-B` 的守卫收敛到一处,此前有三份副本,其中一份的
+注释写着它是另一份的镜像。
+
+### Linux 上的动态构建程序 helper 改用 `DT_RPATH`
+
+RUNPATH 只对 helper **自己**的 needed 生效,于是一个在运行期打开宿主库的构建程序
+在下一跳失败:实测 `dlopen("<sentinel>/lib/libcuda.so.1")` 报
+`libdl.so.2: cannot open shared object file`,而持有它的目录就在 helper 的 RUNPATH 里。
+mcpp 链接的产物早就因为这个原因带 DT_RPATH。链接策略进 helper 的缓存身份,
+旧 helper 会被重建而不是被重放。
+
+### `--offline` 跳过首次使用的沙箱引导
+
+`--offline` 承诺不碰网络,而 `load_or_init` 在空 home 里克隆索引、经 xlings 装
+ninja 与 patchelf。实测:空 home 下 26 秒 / 126 MB → 0.3 秒。
+
+### `examples/09-cuda-kernel` 走两条路线,并拒绝它不能配的对
+
+主路线是 clang(`-x cuda`):工程自己的编译器编设备单元,没有第二个宿主编译器、
+没有宿主编译器上界、没有 CUDA 的宿主头挡路。nvcc 是备用路线,并按名拒绝两对:
+宿主编译器超出 `crt/host_config.h` 所述上界(实测 gcc 16 + nvcc 12.9 即便加了
+`-allow-unsupported-compiler` 也死在 gcc 自己的 `<type_traits>` 里),以及工具包
+旧于 C 库(12.9 的 `crt/math_functions.h` 为宿主重声明 C23 的
+`cospi`/`sinpi`/`rsqrt` 不带 `noexcept`,而 glibc 2.41+ 带)。
+
+同一个缝下还有一份 CPU 实现,由 `cfg(not(accelerator = "cuda"))` 选中,于是
+`mcpp build --no-accel` 编它、`mcpp build` 编 `.cu`,两侧都不需要手写条件。
+
+实测(RTX 4080,驱动 550.144.03 报 CUDA 12.4,LLVM 22.1.8):`mcpp run` 与
+`mcpp run --no-accel` 都打印 `12 24 36 48`,来自不同的产物目录,后者不含
+`cudaMalloc`。
 
 ## [2026.9.5.1] — 2026-09-05
 

docs/05-mcpp-toml.md

@@ -215,7 +215,7 @@ the package/feature boundary, not on an individual target.
 > mcpp 2026.8.18.1 the two were byte-identical, so there was no spelling for
 > "nothing" and any file left under `src/` was swept in.
 
-> **A `sources` entry may carry the accelerator it is for** (2026.9.6+):
+> **A `sources` entry may carry the accelerator it is for** (2026.9.5.2+):
 > `{ glob = "src/kernels/**/*.cu", accel = "cuda12.9+{sm_89}" }`. The glob
 > joins the list like any other; the constraint decides whether it applies to a
 > given build. It must match at least one file (an empty match is refused: it

docs/07-build-mcpp.md

@@ -55,8 +55,8 @@ is ignored, so diagnostics may be logged freely.
 | `mcpp:runner=<token>` *(2026.8.19.2+)* | one argv token of the command that EXECUTES this build's artifact, when the host cannot. Emitted once per token, in order; the artifact path is appended (or substituted for `{}`). Reaches the **consumer**. ⚠️ Emit the executable as an ABSOLUTE path, and only **one** dependency may supply it |
 | `mcpp:link-script=<path>` *(2026.8.19+)* | link with this **linker script** (`-T`; relative resolves against the package root, and the emitted path is absolute because the link runs in the build directory). Reaches the **consumer**, unlike `include-dir` — a board's memory layout is the one thing a consumer cannot write for itself |
 | `mcpp:warning=<text>` *(2026.8.21.2+)* | say something to the user and **keep going**. The one directive that changes no compile line, no link line and no source set. Survives the build cache — see below |
-| `mcpp:fact=<name>=<version>` *(2026.9.6+)* | state something the program **established about the machine** (`cuda.driver=12.4`). Compared against floors before anything is compiled; see below |
-| `mcpp:floor=<name> >= <version>` *(2026.9.6+)* | state what this package **needs** of that quantity. Unmet ⇒ the build is refused with both values (`version-floor-unmet`); a floor nobody stated a fact for is silent |
+| `mcpp:fact=<name>=<version>` *(2026.9.5.2+)* | state something the program **established about the machine** (`cuda.driver=12.4`). Compared against floors before anything is compiled; see below |
+| `mcpp:floor=<name> >= <version>` *(2026.9.5.2+)* | state what this package **needs** of that quantity. Unmet ⇒ the build is refused with both values (`version-floor-unmet`); a floor nobody stated a fact for is silent |
 | `mcpp:rerun-if-changed=<path>`     | re-run `build.mcpp` when this file changes |
 | `mcpp:rerun-if-env-changed=<VAR>`  | re-run `build.mcpp` when this env var changes |
 
@@ -152,7 +152,7 @@ there is nothing to do the build never reaches the `build.mcpp` stage — it als
 does not report which target it built or which sources it inferred. Touch a
 source and the advisory returns.
 
-### The probe channel: `fact` / `floor` (2026.9.6+)
+### The probe channel: `fact` / `floor` (2026.9.5.2+)
 
 A rule package is the thing that knows how to ask a machine what it has —
 which library to open, which function to call — and the engine is the thing
@@ -235,7 +235,7 @@ package whose content is implementation-neutral. Asking follows whatever
 the compiler payload or through the runtime binding, and nothing has to look
 for it.
 
-### Driving a second compiler: `toolchain_sysroot` / `toolchain_binutils_dir` (2026.9.6+)
+### Driving a second compiler: `toolchain_sysroot` / `toolchain_binutils_dir` (2026.9.5.2+)
 
 ```cpp
 const char* sr = mcpp::toolchain_sysroot();        // the `--sysroot` mcpp passes, or ""
@@ -561,10 +561,10 @@ The running program receives the build context as `MCPP_*` variables
 | `MCPP_TARGET_ENV` *(0.0.100+)* | `mcpp::target_env()` | the target's env segment (`gnu`/`musl`/`msvc`); empty string when the triple has none (macOS) |
 | `MCPP_HOST` | `mcpp::host()` | the host triple |
 | `MCPP_PROFILE` | `mcpp::profile()` | effective profile name (`dev`/`release`/…) |
-| `MCPP_TOOLCHAIN_SYSROOT` *(2026.9.6+)* | `mcpp::toolchain_sysroot()` | the `--sysroot` mcpp passes to its own compiler; empty when it passes none. For a rule package that runs a **second** compiler — see "Driving a second compiler" above |
-| `MCPP_TOOLCHAIN_BINUTILS_DIR` *(2026.9.6+)* | `mcpp::toolchain_binutils_dir()` | the directory mcpp names with `-B`; empty when it names none (a musl or MinGW payload brings its own assembler and linker) |
-| `MCPP_ACCEL` *(2026.9.6+)* | `mcpp::accel()` | the device axis of this build, resolved — `--accel` / `--no-accel` over `[build] accel` — in the wire form `cuda12.9+{sm_89} ptx>=89`; empty when the build asks for no accelerator. A rule package derives its own flags (`-gencode`, `--offload-arch`) from it, so the architecture set is written once, in the manifest. The same value feeds the `cfg(accelerator = "…")` layer key |
-| `MCPP_DEVICE_SOURCES` *(2026.9.6+)* | `mcpp::device_sources()` | the device-kind sources (`.cu`, `.hip`, …) the package's effective `sources` match, package-root-relative, one per line; empty when there are none. The engine compiles none of them — the rule package this program imports turns each into an `mcpp::action`. Already narrowed: a `{ glob, accel }` entry the build does not cover contributes nothing, so `--no-accel` yields an empty list |
+| `MCPP_TOOLCHAIN_SYSROOT` *(2026.9.5.2+)* | `mcpp::toolchain_sysroot()` | the `--sysroot` mcpp passes to its own compiler; empty when it passes none. For a rule package that runs a **second** compiler — see "Driving a second compiler" above |
+| `MCPP_TOOLCHAIN_BINUTILS_DIR` *(2026.9.5.2+)* | `mcpp::toolchain_binutils_dir()` | the directory mcpp names with `-B`; empty when it names none (a musl or MinGW payload brings its own assembler and linker) |
+| `MCPP_ACCEL` *(2026.9.5.2+)* | `mcpp::accel()` | the device axis of this build, resolved — `--accel` / `--no-accel` over `[build] accel` — in the wire form `cuda12.9+{sm_89} ptx>=89`; empty when the build asks for no accelerator. A rule package derives its own flags (`-gencode`, `--offload-arch`) from it, so the architecture set is written once, in the manifest. The same value feeds the `cfg(accelerator = "…")` layer key |
+| `MCPP_DEVICE_SOURCES` *(2026.9.5.2+)* | `mcpp::device_sources()` | the device-kind sources (`.cu`, `.hip`, …) the package's effective `sources` match, package-root-relative, one per line; empty when there are none. The engine compiles none of them — the rule package this program imports turns each into an `mcpp::action`. Already narrowed: a `{ glob, accel }` entry the build does not cover contributes nothing, so `--no-accel` yields an empty list |
 | `MCPP_OUT_DIR` | `mcpp::out_dir()` | a writable scratch/output dir owned by mcpp |
 | `MCPP_MANIFEST_DIR` | `mcpp::manifest_dir()` | the package root (= CWD) |
 | `MCPP_FEATURE_<NAME>` | `mcpp::has_feature("name")` | set to `1` per active feature (same `<NAME>` sanitization as the `MCPP_FEATURE_` compile macro) |

docs/20-accelerators.md

@@ -232,7 +232,7 @@ combinators.
 ## Two boundaries worth stating
 
 **`--accel` and `--no-accel` are `build`, `run` and `test` options** (run and
-test from 2026.9.6), as `--target` and `--profile` are. `pack` reads
+test from 2026.9.5.2), as `--target` and `--profile` are. `pack` reads
 `[build] accel` from the manifest like every other build input. The flag was a
 `build`-only option at first, and the measured consequence was a project whose
 CPU-only variant could be built and not run: `mcpp build --no-accel` produced

docs/zh/05-mcpp-toml.md

@@ -201,7 +201,7 @@ mcpp 刻意不在一次构建里把同一个共享源编译成两份:一个源
 > `src/` 下剩下的任何文件都会被扫进来。
 
 
-> **`sources` 的条目可以带上它所面向的加速器**(2026.9.6+):
+> **`sources` 的条目可以带上它所面向的加速器**(2026.9.5.2+):
 > `{ glob = "src/kernels/**/*.cu", accel = "cuda12.9+{sm_89}" }`。glob 与其它条目一样
 > 进入列表;约束决定它是否适用于某一次构建。它必须至少匹配一个文件(空匹配会被拒绝:
 > 那会让这个设备无东西可编,而只在链接时才说话)。`--no-accel` 下该 glob 被排除,

docs/zh/07-build-mcpp.md

@@ -52,8 +52,8 @@ mcpp build      # 编译 + 运行 build.mcpp,然后构建工程
 | `mcpp:runner=<token>` *(2026.8.19.2+)* | 执行本次构建产物的命令的**一个 argv token**(宿主跑不了它时)。一个 token 一次调用、按顺序;产物路径会被追加(或替换 `{}`)。**到达消费者**。⚠️ 可执行文件要发**绝对路径**,且**只能有一个**依赖提供它 |
 | `mcpp:link-script=<path>` *(2026.8.19+)* | 用这个**链接脚本**链接(`-T`;相对路径按包根解析,发出的是绝对路径,因为链接是在构建目录里跑的)。与 `include-dir` 不同,它**到达消费者** —— 板子的内存布局恰恰是消费者写不出来的那一项 |
 | `mcpp:warning=<text>` *(2026.8.21.2+)* | 对用户说一句话并**继续**。唯一一条不改变编译行、链接行与源码集的指令。它**穿过构建缓存** —— 见下 |
-| `mcpp:fact=<name>=<version>` *(2026.9.6+)* | 陈述程序**测得的机器事实**(`cuda.driver=12.4`)。在编译任何东西之前与 floor 比较;见下 |
-| `mcpp:floor=<name> >= <version>` *(2026.9.6+)* | 陈述本包对该量的**下界**。不满足 ⇒ 构建被拒并给出两侧取值(`version-floor-unmet`);没有人陈述事实的下界保持沉默 |
+| `mcpp:fact=<name>=<version>` *(2026.9.5.2+)* | 陈述程序**测得的机器事实**(`cuda.driver=12.4`)。在编译任何东西之前与 floor 比较;见下 |
+| `mcpp:floor=<name> >= <version>` *(2026.9.5.2+)* | 陈述本包对该量的**下界**。不满足 ⇒ 构建被拒并给出两侧取值(`version-floor-unmet`);没有人陈述事实的下界保持沉默 |
 | `mcpp:rerun-if-changed=<path>`     | 该文件变化时重跑 `build.mcpp` |
 | `mcpp:rerun-if-env-changed=<VAR>`  | 该环境变量变化时重跑 `build.mcpp` |
 
@@ -139,7 +139,7 @@ mcpp 在每次命中时重放它。
 `build.mcpp` 阶段 —— 它同样不会报告构建了哪个目标、推断了哪些源码。touch 一下源码,提示
 就回来了。
 
-### 探针通道:`fact` / `floor`(2026.9.6+)
+### 探针通道:`fact` / `floor`(2026.9.5.2+)
 
 规则包是知道「怎么问机器它有什么」的那一方 —— 打开哪个库、调用哪个函数;
 引擎则是不该知道的那一方。于是由包来**测量**,由引擎来**比较**:
@@ -205,7 +205,7 @@ const char* sr = mcpp::sysroot_dir();     // 目标的 C 库根目录,没有则
 
 宿主目标上 `sysroot_dir()` 为空:那里 C 库随编译器载荷或运行时绑定而来,没人需要找它。
 
-### 驱动第二个编译器:`toolchain_sysroot` / `toolchain_binutils_dir`(2026.9.6+)
+### 驱动第二个编译器:`toolchain_sysroot` / `toolchain_binutils_dir`(2026.9.5.2+)
 
 ```cpp
 const char* sr = mcpp::toolchain_sysroot();        // mcpp 传的 `--sysroot`,没有则为 ""
@@ -487,10 +487,10 @@ mcpp 会把它自己构建时用的**同一份** std 模块暂存过来,缓存
 | `MCPP_TARGET_ENV` *(0.0.100+)* | `mcpp::target_env()` | 目标的 env 段(`gnu`/`musl`/`msvc`);三元组无 env 段(macOS)时为空串 |
 | `MCPP_HOST` | `mcpp::host()` | 宿主三元组 |
 | `MCPP_PROFILE` | `mcpp::profile()` | 生效 profile 名(`dev`/`release`/…) |
-| `MCPP_TOOLCHAIN_SYSROOT` *(2026.9.6+)* | `mcpp::toolchain_sysroot()` | mcpp 传给自己那个编译器的 `--sysroot`;不传时为空串。供运行**第二个**编译器的规则包使用 —— 见上文「驱动第二个编译器」 |
-| `MCPP_TOOLCHAIN_BINUTILS_DIR` *(2026.9.6+)* | `mcpp::toolchain_binutils_dir()` | mcpp 用 `-B` 指的目录;不指时为空串(musl 与 MinGW 载荷自带汇编器与链接器) |
-| `MCPP_ACCEL` *(2026.9.6+)* | `mcpp::accel()` | 本次构建的设备轴,已解析 —— `--accel` / `--no-accel` 优先于 `[build] accel` —— 线上形态 `cuda12.9+{sm_89} ptx>=89`;不要加速器时为空串。规则包从它推导自己的开关(`-gencode`、`--offload-arch`),架构集合因此只在 manifest 写一次。同一个值也喂给 `cfg(accelerator = "…")` 这个 layer 键 |
-| `MCPP_DEVICE_SOURCES` *(2026.9.6+)* | `mcpp::device_sources()` | 本包有效 `sources` 匹配到的设备类源文件(`.cu`、`.hip`…),相对包根,一行一个;没有时为空串。引擎一个都不编译 —— 由本程序引入的规则包把每一个变成一条 `mcpp::action`。已经过收窄:构建未覆盖的 `{ glob, accel }` 条目贡献为空,因此 `--no-accel` 得到空列表 |
+| `MCPP_TOOLCHAIN_SYSROOT` *(2026.9.5.2+)* | `mcpp::toolchain_sysroot()` | mcpp 传给自己那个编译器的 `--sysroot`;不传时为空串。供运行**第二个**编译器的规则包使用 —— 见上文「驱动第二个编译器」 |
+| `MCPP_TOOLCHAIN_BINUTILS_DIR` *(2026.9.5.2+)* | `mcpp::toolchain_binutils_dir()` | mcpp 用 `-B` 指的目录;不指时为空串(musl 与 MinGW 载荷自带汇编器与链接器) |
+| `MCPP_ACCEL` *(2026.9.5.2+)* | `mcpp::accel()` | 本次构建的设备轴,已解析 —— `--accel` / `--no-accel` 优先于 `[build] accel` —— 线上形态 `cuda12.9+{sm_89} ptx>=89`;不要加速器时为空串。规则包从它推导自己的开关(`-gencode`、`--offload-arch`),架构集合因此只在 manifest 写一次。同一个值也喂给 `cfg(accelerator = "…")` 这个 layer 键 |
+| `MCPP_DEVICE_SOURCES` *(2026.9.5.2+)* | `mcpp::device_sources()` | 本包有效 `sources` 匹配到的设备类源文件(`.cu`、`.hip`…),相对包根,一行一个;没有时为空串。引擎一个都不编译 —— 由本程序引入的规则包把每一个变成一条 `mcpp::action`。已经过收窄:构建未覆盖的 `{ glob, accel }` 条目贡献为空,因此 `--no-accel` 得到空列表 |
 | `MCPP_OUT_DIR` | `mcpp::out_dir()` | mcpp 提供的可写输出/暂存目录 |
 | `MCPP_MANIFEST_DIR` | `mcpp::manifest_dir()` | 包根(= CWD) |
 | `MCPP_FEATURE_<NAME>` | `mcpp::has_feature("name")` | 每个活跃 feature 置 `1`(`<NAME>` 消毒规则与 `MCPP_FEATURE_` 编译宏一致) |