feat(build.mcpp): a missing mcpp:: API now says the engine may be too old

A package that adopts a new typed directive cannot be used by an older mcpp,
and until now the only thing the reader saw was

    error: 'runner' is not a member of 'mcpp'

which reads like the package author's typo rather than the reader's engine
being out of date. The wire protocol's own answer (protocol_error names
`mcpp self update`) never reaches this case: it needs the program to have
compiled first.

The package cannot solve it either. Measured:

    if constexpr (requires { mcpp::runner("qemu"); })   // hard error

A requires-expression over a qualified name that does not exist is ill-formed,
not `false`, so there is no in-language feature probe.

So the compile failure carries the hint, matched across all three frontends'
spellings and anchored on our namespace so an ordinary error does not get it.
This covers every future typed-API addition, not just `runner`.

Also corrects docs/07 (both languages), which still claimed an unknown
directive "can only be a typo" within one protocol version — the engine's own
diagnostic was corrected away from that when link-script landed: the protocol
number is stamped by whichever mcpp compiled the program, so two matching
numbers say nothing about whether the key is from the future.

Author: speak-agent

.agents/docs/2026-08-19-baremetal-phase3-usable-plan.md

@@ -132,6 +132,32 @@ mcpp::runner("-kernel");
 ⭐ **决定:先按「什么都不加」发布,并把包级 `requires-mcpp` 作为一个独立探针(P-COMPAT)排在后面。**
 理由:诊断已经可行动,而一个会让老客户端硬失败的新键代价高得多 —— 且这个代价**尚未测过**。
 
+#### ⚠️ 实施时探到的:上表第 2 行「诊断可行动」对**类型化 API 是假的**
+
+那条可行动的诊断(`protocol_error()`,点名 `mcpp self update`)只对**wire 键**生效,
+而它要求程序**先编译得过**。BSP 用的是 `mcpp::runner(...)`,老 mcpp 上根本编不过,
+拿到的是:
+
+```
+error: 'runner' is not a member of 'mcpp'
+```
+
+—— 读起来像**包作者拼错了**,而不是**读者的引擎旧了**。
+
+我先试了在包里做优雅降级,**实测证伪**:
+
+```cpp
+if constexpr (requires { mcpp::runner("qemu"); })   // ✗ 名字不存在 ⇒ 硬错误
+```
+
+`requires` 表达式作用在**不存在的限定名**上是 ill-formed,**不是求值为 `false`**。
+⇒ **语言内没有特性探测**,包侧无路可走。
+
+⭐ **所以补在引擎侧**:`build.mcpp` 编译失败且错误里出现「不是 `mcpp` 的成员」时,
+追加一段点名 `mcpp self update` 并报出当前版本的提示(三个前端三种写法都认)。
+**这对以后每一次类型化 API 新增都生效**,不只是 `runner`。
+判据:`mentions_missing_mcpp_api` 单测钉三种拼写 + 三条不该误报的普通错误。
+
 ### 3.3 收录进 `mcpplibs/mcpp-index`
 
 `pkgs/r/riscv-virt-rt.lua` 与 `pkgs/m/mcpplibs.std.freestanding.lua`。

docs/07-build-mcpp.md

@@ -326,16 +326,44 @@ write it yourself). mcpp uses that two ways:
   with an upgrade hint. Continuing would silently drop directives the build
   depends on — and "the build succeeded but the flag never arrived" is the
   worst class of build bug.
-- Because the two sides then provably agree, an **unrecognized directive is an
-  error** rather than a warning: within one protocol version it can only be a
-  typo.
+- An **unrecognized directive is an error** rather than a warning, and the error
+  names *both* possible causes. It cannot name one: the protocol number is
+  stamped by whichever mcpp **compiled** the program, not carried by the
+  package, so a package written for a newer mcpp arrives at an older one
+  wearing the older engine's number. Two matching numbers therefore say nothing
+  about whether the key came from the future.
 
 A `printf`-style program announces nothing, so it keeps the historical
 warn-and-ignore behaviour. That surface is **frozen at the eleven directives in
 the table above** — it still works and will keep working, but new capabilities
 land only in the typed API. Prefer `import mcpp;` for anything intended to
 maintain.
 
+#### A package that needs a newer mcpp
+
+When a published package calls a typed function this mcpp does not have, the
+compile error naming it is followed by:
+
+```
+       The `mcpp` build module this engine bundles does not have that name.
+       Either the package was written for a newer mcpp (try `mcpp self update`;
+       this is mcpp 2026.8.19.2), or the name is misspelled …
+```
+
+The package cannot handle this itself, and it is worth knowing why — the
+obvious guard does not compile:
+
+```cpp
+if constexpr (requires { mcpp::runner("qemu"); })   // ✗ hard error when absent
+    mcpp::runner("qemu");
+```
+
+A `requires`-expression over a **qualified name that does not exist** is
+ill-formed, not `false`. So there is no in-language feature probe, and a
+package that adopts a new directive states its floor in prose (its README) and
+relies on the diagnostic above. Such a package should name the mcpp version it
+requires.
+
 ### `import std;` (mcpp 2026.8.2.1+)
 
 A `build.mcpp` may `import std;` (and `import std.compat;`), alone or together

docs/zh/07-build-mcpp.md

@@ -290,13 +290,36 @@ mcpp 会播下一个带着该声明的占位文件,使 prepare 期的扫描与
 
 - 程序声明的协议**高于** mcpp 所理解的 → **拒绝执行**,并给出升级提示。继续跑会
   静默丢掉构建依赖的指令,而「构建成功了但那个 flag 根本没到」是最难查的一类问题。
-- 既然双方已被证明一致,**未知指令就是错误**而不是警告:在同一个协议版本内,
-  它只可能是拼写错误。
+- **未知指令是错误**而不是警告,而且这条错误会把**两种可能的原因都说出来**。
+  它没法只说一种:协议号是由**编译**该程序的那个 mcpp 现场打上的,并不由包本身携带
+  —— 于是一个写给新 mcpp 的包到了老 mcpp 手里,身上戴的是老引擎的号。
+  **两个号一致因此完全不能说明这个键是不是来自未来。**
 
 `printf` 风格的程序什么都不声明,因此保留历史上的「警告并忽略」行为。这一面
 **冻结在上表的 11 条指令**上——它仍然能用、也会继续能用,但新能力只在类型化 API 里
 落地。**要长期维护的程序请用 `import mcpp;`。**
 
+#### 一个需要更新 mcpp 的包
+
+当已发布的包调用了当前 mcpp 没有的类型化函数时,点名的编译错误之后会跟着:
+
+```
+       The `mcpp` build module this engine bundles does not have that name.
+       Either the package was written for a newer mcpp (try `mcpp self update`;
+       this is mcpp 2026.8.19.2), or the name is misspelled …
+```
+
+**包自己处理不了这件事**,而原因值得知道 —— 最直觉的那道防护编译不过:
+
+```cpp
+if constexpr (requires { mcpp::runner("qemu"); })   // ✗ 名字不存在时是硬错误
+    mcpp::runner("qemu");
+```
+
+`requires` 表达式作用在一个**不存在的限定名**上时是 ill-formed,而**不是求值为
+`false`**。所以语言内没有特性探测这条路:采用了新指令的包只能在自己的 README 里
+用文字写明版本下限,并依赖上面那条诊断。**这类包应当写清楚它需要哪个版本的 mcpp。**
+
 ### `import std;`(mcpp 2026.8.2.1+)
 
 `build.mcpp` 可以 `import std;`(以及 `import std.compat;`),单用或与

src/build/build_program.cppm

@@ -28,6 +28,7 @@ import mcpp.toolchain.registry;      // archive_tool
 import mcpp.toolchain.stdmod;        // ensure_built — the SAME std BMI the main build uses
 import mcpp.toolchain.triple;        // host_triple (MCPP_HOST contract value)
 import mcpp.ui;
+import mcpp.version;         // MCPP_VERSION — the hint names the engine the reader is on
 
 export namespace mcpp::build {
 
@@ -94,6 +95,30 @@ inline std::string xpkg_env_var(std::string_view ns, std::string_view name) {
     return out;
 }
 
+// Does a compiler's output say the program asked for something the bundled
+// `mcpp` module does not have?
+//
+// ⚠️ This is the ONLY place an engine-too-old situation can be caught for the
+// TYPED api, and it exists because the in-language probe does not:
+//
+//     if constexpr (requires { mcpp::runner("x"); })      // ← hard error,
+//         mcpp::runner("x");                              //   measured
+//
+// A requires-expression over a qualified name that does not exist is
+// ill-formed, not `false`, so a package CANNOT degrade gracefully across mcpp
+// versions the way it could across, say, a header's feature macro. The wire
+// protocol has its own answer for this (protocol_error() names `mcpp self
+// update` for an unknown `mcpp:` key), but that answer needs the program to
+// have COMPILED — and a package written against a newer mcpp does not get
+// that far. So the raw compiler error is the message, and on its own it says
+// only `'runner' is not a member of 'mcpp'`, which reads like the author's
+// typo instead of the reader's out-of-date engine.
+//
+// Deliberately spelling-based, and deliberately broad across the three
+// frontends (they phrase it three ways). A false positive costs one extra
+// hint line under a genuine typo; a false negative costs a user an afternoon.
+bool mentions_missing_mcpp_api(std::string_view compilerOutput);
+
 // Compile + run `<root>/build.mcpp` (if present) with `hostCompiler` (the resolved
 // HOST frontend — under a cross --target the caller resolves a host toolchain;
 // the program always compiles AND runs on the host) and apply its directives to
@@ -128,6 +153,28 @@ bool glob_inputs_stale(const std::filesystem::path& projectRoot);
 
 namespace mcpp::build {
 
+// See the declaration for why this exists at all.
+//
+// Three frontends, three spellings of the same fact — and MSVC's does not even
+// contain the word "member" in the same order, so each is matched literally
+// rather than by a shared substring:
+//
+//   gcc    error: 'runner' is not a member of 'mcpp'
+//   clang  error: no member named 'runner' in namespace 'mcpp'
+//   cl.exe error C2039: 'runner': is not a member of 'mcpp'
+//
+// The trailing `'mcpp'` is what keeps this off unrelated failures: a package's
+// own missing symbol names its own namespace, not ours.
+bool mentions_missing_mcpp_api(std::string_view out) {
+    static constexpr std::string_view kNeedles[] = {
+        "is not a member of 'mcpp'",       // gcc, and cl.exe's tail
+        "in namespace 'mcpp'",             // clang
+    };
+    for (auto n : kNeedles)
+        if (out.find(n) != std::string_view::npos) return true;
+    return false;
+}
+
 namespace {
 
 namespace fs = std::filesystem;
@@ -778,8 +825,21 @@ std::expected<void, std::string> run_build_program(
     auto cres = mcpp::platform::process::capture_exec(compileArgv, compileEnv,
                                                      compileCwd);
     if (cres.exit_code != 0) {
-        return std::unexpected(std::format(
-            "build.mcpp failed to compile (exit {}):\n{}", cres.exit_code, cres.output));
+        std::string msg = std::format("build.mcpp failed to compile (exit {}):\n{}",
+                                      cres.exit_code, cres.output);
+        if (mentions_missing_mcpp_api(cres.output)) {
+            msg += std::format(
+                "\n       The `mcpp` build module this engine bundles does not have "
+                "that name.\n"
+                "       Either the package was written for a newer mcpp (try "
+                "`mcpp self update`;\n"
+                "       this is mcpp {}), or the name is misspelled — the compiler "
+                "cannot tell\n"
+                "       the two apart, because the module is generated by whichever "
+                "mcpp is running.",
+                mcpp::MCPP_VERSION);
+        }
+        return std::unexpected(std::move(msg));
     }
 
     // ── Run it; capture stdout(+stderr) and parse directives ────────────────

tests/unit/test_freestanding.cpp

@@ -228,6 +228,35 @@ TEST(XpkgEnvVar, BothSpellingsAreDerivedFromOneSanitizer) {
               "MCPP_XPKG_PICOLIBC_RISCV_DIR");
 }
 
+// ── engine floor: a package that needs a newer mcpp ─────────────────────────
+
+TEST(BuildProgramCompatHint, RecognisesAllThreeFrontendSpellings) {
+    using mcpp::build::mentions_missing_mcpp_api;
+    // ⚠️ Measured, not assumed: `if constexpr (requires { mcpp::runner("x"); })`
+    // is a HARD ERROR when the name is absent, so a package cannot probe for a
+    // newer API in-language. The compiler's error IS the compat channel, and
+    // these are the three ways it arrives.
+    EXPECT_TRUE(mentions_missing_mcpp_api(
+        "build.mcpp:57:11: error: 'runner' is not a member of 'mcpp'"));          // gcc
+    EXPECT_TRUE(mentions_missing_mcpp_api(
+        "build.mcpp:57:11: error: no member named 'runner' in namespace 'mcpp'"));// clang
+    EXPECT_TRUE(mentions_missing_mcpp_api(
+        "build.mcpp(57): error C2039: 'runner': is not a member of 'mcpp'"));     // cl.exe
+}
+
+TEST(BuildProgramCompatHint, StaysOffFailuresThatAreNotAboutOurApi) {
+    using mcpp::build::mentions_missing_mcpp_api;
+    // The hint says "your mcpp may be too old". Attaching that to an ordinary
+    // compile error would send the reader to the wrong place, so the match is
+    // anchored on OUR namespace — a package's own missing symbol names its own.
+    EXPECT_FALSE(mentions_missing_mcpp_api(
+        "build.mcpp:12:5: error: 'runner' is not a member of 'board'"));
+    EXPECT_FALSE(mentions_missing_mcpp_api(
+        "build.mcpp:3:1: error: expected ';' after top level declarator"));
+    EXPECT_FALSE(mentions_missing_mcpp_api(
+        "build.mcpp:9:9: error: use of undeclared identifier 'mcpp_runner'"));
+}
+
 // ── artifact set ───────────────────────────────────────────────────────────
 
 TEST(FreestandingArtifacts, SizeOutputIsParsedNotPassedThrough) {