fix(manifest): 保留前缀内的未知层名,从依赖来是版本差而不是拼写错

⚠️ 这条由生态 CI 实测暴露,而它让层名词表**对已发布的包永远不可扩展**。

`openkal-llvm-runtime` 声明本次新命名的那一层,被上一版引擎读到:

    error: dependency 'openkal-llvm-runtime': mcpp.toml: error:
           `provides = ["mcpp:compiler-runtime=compiler-rt"]` names no
           capability mcpp knows.

保留前缀是闭集,为的是让**拼写错误成为错误而不是一个被静默禁用的行为**。
在解析期直接拒绝,让这个闭集在第二个、没人打算要的意义上也闭上了:
一个声明了「读者发布之后才被命名的层」的包,**整份清单加载不了**。

── 谁的清单决定答案 ──────────────────────────────────────

* **根工程**的清单里出现未知层名 ⇒ **错误**。那是作者自己的拼写,
  而他正看着这次构建。
* **依赖**的清单里出现未知层名 ⇒ **警告并忽略该层**。那份清单是对着一个更新的
  引擎写的,而「忽略未知的并说出来」正是本引擎对其它每一种未知键已有的做法
  (`warn_unknown_xpkg_keys` 的注释:should not fail outright, only tell the
  user what it ignored)。

⚠️ 警告放在扫描**全部包**的那个循环里,不放在 `warn_unknown_xpkg_keys`:
后者只走到经索引解析的依赖,而 path / git 依赖自带清单,先前一条警告都收不到。

⚠️ 这条规定只对**此后的**引擎生效。一个包若要声明某个层名,其使用者的引擎仍须
不早于该层名被引入的版本 —— 本次修的是「从今往后可扩展」,不是追溯。

test: e2e 281 增两格(依赖声明未知层 ⇒ 构建成功且点名被忽略的层;
      根工程拼错 ⇒ 报错并列出五个层名);unit 93 passed。
spec: SPEC-002 §5.1 拆成两条;docs/14 中英同步。

Author: speak-agent

docs/14-target-side.md

@@ -288,6 +288,12 @@ The toolchain family spelling `openkal-llvm` normalises to `llvm`. It named the
 same payload and carried a fact about the target side, which the model above
 resolves from what packages declare.
 
-An unknown name inside the reserved prefix is an error; an unknown key elsewhere
-in a manifest is ignored. A published package therefore continues to load under
-an engine predating a key it carries.
+An unknown name inside the reserved prefix is an error in the root project's own
+manifest and a warning in a dependency's. The first is a misspelling the author
+is looking at; the second is a manifest written against a newer engine, and
+refusing it would mean the layer vocabulary could never be extended by a
+published package. An unknown key elsewhere in a manifest is ignored.
+
+That provision governs future engines only. A package declaring a layer name
+still requires its consumers to run an engine no older than the release that
+introduced the name.

docs/spec/target-side.md

@@ -62,7 +62,7 @@
 mcpp:<层名>[=<实现名>]
 ```
 
-`<层名>` **必须**属于 §1.1 的闭集;不属于时引擎**必须**报错。
+`<层名>` **必须**属于 §1.1 的闭集;不属于时的处置见 §5.1(根工程报错、依赖警告)。
 不以 `mcpp:` 开头的条目属于特性系统,引擎**必须**原样透传。
 
 省略 `=<实现名>` 时,该层的实现名取包名。
@@ -159,9 +159,26 @@ mcpp:<层名>[=<实现名>]
 
 ### 5.1 未知名字 ✅ 已实现
 
-`mcpp:` 前缀内的未知层名,引擎**必须**报错。
+⚠️ **谁的清单决定答案。**
+
+- 出现在**根工程**清单中的未知层名,引擎**必须**报错。
+  这是作者自己的拼写,而他正看着这次构建。
+- 出现在**依赖**清单中的未知层名,引擎**禁止**据此使构建失败;
+  **必须**警告并忽略该层。该清单是对着一个更新的引擎写的。
+
 清单中其它位置的未知键,引擎**禁止**据此使整份清单加载失败;**应当**警告并忽略。
 
+⚠️ 第二条来自一次实测。在其落地之前,一个声明了新层名的包
+**在该层被命名之前发布的每一个引擎上都无法加载**,因此层名词表对已发布的包
+永远不可扩展:
+
+    error: dependency 'openkal-llvm-runtime': mcpp.toml: error:
+           `provides = ["mcpp:compiler-runtime=compiler-rt"]` names no
+           capability mcpp knows.
+
+⚠️ 这条规定只在**未来**的引擎上生效。一个包若要声明某个层名,
+其使用者的引擎仍须不早于该层名被引入的版本。
+
 ### 5.2 既有拼写 ✅ 已实现
 
 - 能力名 `hosted-standard-library` **必须**继续表示 `c++-abi` 层;

docs/zh/14-target-side.md

@@ -245,5 +245,10 @@ include_dirs = ["config/picolibc"]
 工具链族拼写 `openkal-llvm` 归一为 `llvm`。它命名同一份载荷,
 并携带一条关于目标侧的事实,而上述模型从包的声明中解析该事实。
 
-保留前缀内的未知名字是错误;清单中其它位置的未知键被忽略。
-因此一个已发布的包在早于其所携带的键的引擎下仍能加载。
+保留前缀内的未知名字,在根工程自己的清单中是错误,在依赖的清单中是警告。
+前者是作者正看着的一处拼写错误;后者是一份对着更新引擎写成的清单,
+拒绝它将意味着层名词表永远不能被一个已发布的包扩展。
+清单中其它位置的未知键被忽略。
+
+该规定只约束此后的引擎。一个包若声明某个层名,
+其使用者仍须运行不早于该层名被引入的那个版本。

src/build/prepare.cppm

@@ -99,6 +99,22 @@ namespace mcpp::build {
 // should not fail outright, only tell the user what it ignored.
 inline void warn_unknown_xpkg_keys(const mcpp::manifest::Manifest& dm,
                                    std::string_view depLabel) {
+    // ⚠️ A LAYER NAME THIS ENGINE DOES NOT KNOW IS A VERSION GAP, NOT A TYPO,
+    // WHEN IT ARRIVES FROM A DEPENDENCY.
+    //
+    // The reserved `mcpp:` prefix is a closed set so a misspelling cannot
+    // silently disable a behaviour. Refusing a DEPENDENCY's manifest for it made
+    // the set closed in a second sense nobody intended: a published package
+    // could never declare a layer named after the reader was released.
+    // Ignoring the layer and saying so is what this engine already does for
+    // every other unknown key, and it is the only response that lets the
+    // vocabulary grow.
+    for (auto const& cap : dm.unknownCapabilities) {
+        mcpp::ui::warning(std::format(
+            "dependency '{}': `{}` names a target-side layer this mcpp does not "
+            "know — ignored. A newer mcpp may resolve it; this build proceeds "
+            "without that layer.", depLabel, cap));
+    }
     for (auto const& key : dm.xpkgUnknownKeys) {
         auto suggestion = mcpp::manifest::closest_known_xpkg_key(key);
         if (suggestion.empty())
@@ -923,6 +939,21 @@ prepare_build(bool print_fingerprint,
         : mcpp::manifest::load(*root / "mcpp.toml");
     if (!m) return std::unexpected(m.error().format());
 
+    // ⚠️ AND ONLY FOR THE ROOT. A layer name this engine does not know is a
+    // typo in the manifest the author is looking at, and a version gap in a
+    // dependency's. The reserved `mcpp:` prefix exists so the first is an error
+    // rather than a silently disabled behaviour; refusing the second as well
+    // meant the layer vocabulary could never be extended by a published package
+    // (`warn_unknown_xpkg_keys` carries that half).
+    if (!m->unknownCapabilities.empty()) {
+        auto const& cap = m->unknownCapabilities.front();
+        auto why = mcpp::targetside::parse_capability(cap);
+        return std::unexpected(std::format(
+            "{}: {}", (*root / "mcpp.toml").string(),
+            why ? std::format("`{}` names no capability mcpp knows.", cap)
+                : why.error()));
+    }
+
     // A DISTRIBUTION package is not a source tree, and building "in" one is a
     // failure that looks like a success: `interface/` holds declarations whose
     // definitions are in the prebuilt archive, so the build compiles the
@@ -5563,6 +5594,20 @@ prepare_build(bool print_fingerprint,
                 : std::format("{}@{}", pkg.manifest.package.name,
                               pkg.manifest.package.version);
 
+            // ⚠️ EVERY PACKAGE KIND, NOT ONLY THE ONES WITH AN XPKG
+            // DESCRIPTOR. `warn_unknown_xpkg_keys` reaches a dependency
+            // resolved through the index; a path or git dependency carries a
+            // manifest of its own and reached no warning at all, so a layer
+            // this engine does not know went by in silence. This loop sees
+            // every package in the graph.
+            for (auto const& cap : pkg.manifest.unknownCapabilities) {
+                if (&pkg == &packages.front()) continue;   // root: already refused
+                mcpp::ui::warning(std::format(
+                    "package '{}': `{}` names a target-side layer this mcpp does "
+                    "not know — ignored. A newer mcpp may resolve it; this build "
+                    "proceeds without that layer.", pkgId, cap));
+            }
+
             for (auto const& entry : pkg.manifest.provides) {
                 std::optional<tsd::CapDecl> decl;
                 if (auto parsed = tsd::parse_capability(entry); parsed && *parsed)
@@ -5610,10 +5655,10 @@ prepare_build(bool print_fingerprint,
             // one is: a typo would otherwise disable a check silently.
             for (auto const& entry : pkg.manifest.requires_) {
                 auto parsed = tsd::parse_capability(entry);
-                if (!parsed)
-                    return std::unexpected(std::format(
-                        "package '{}': {}", pkgId, parsed.error()));
-                if (!*parsed) continue;      // not in mcpp's namespace
+                // An unknown layer name is reported where the manifest was
+                // read — as an error for the root and a warning for a
+                // dependency — so it is skipped rather than refused twice.
+                if (!parsed || !*parsed) continue;
                 requirements.push_back({ pkgId, (*parsed)->layer,
                                          (*parsed)->interfaceName });
             }

src/manifest/toml.cppm

@@ -471,15 +471,15 @@ std::expected<Manifest, ManifestError> parse_string(std::string_view content,
     if (auto v = doc->get_string_array("package.provides")) {
         for (auto const& entry : *v)
             if (auto cap = mcpp::targetside::parse_capability(entry); !cap)
-                return std::unexpected(error(origin, cap.error()));
+                m.unknownCapabilities.push_back(entry);
         m.provides = *v;
     }
     // [package] requires — validated exactly like `provides`: names under the
     // reserved prefix are a closed set, everything else passes through.
     if (auto v = doc->get_string_array("package.requires")) {
         for (auto const& entry : *v)
             if (auto cap = mcpp::targetside::parse_capability(entry); !cap)
-                return std::unexpected(error(origin, cap.error()));
+                m.unknownCapabilities.push_back(entry);
         m.requires_ = *v;
     }
     // std-module / std-compat-module / std-module-flags.

src/manifest/types.cppm

@@ -890,6 +890,29 @@ struct Manifest {
     // schema evolution is loud in lint instead of invisible.
     std::vector<std::string>    xpkgUnknownKeys;
 
+    // ⚠️ CAPABILITY NAMES INSIDE THE RESERVED `mcpp:` PREFIX THAT THIS ENGINE
+    // DOES NOT KNOW, AND WHY THEY ARE RECORDED RATHER THAN REFUSED HERE.
+    //
+    // The reserved prefix is a closed set so that a misspelled layer name is an
+    // error instead of a silently disabled behaviour. Refusing at PARSE time
+    // made the set closed in a second, unintended sense: a package declaring a
+    // layer added after the reader was released failed to load AT ALL, so the
+    // vocabulary could never be extended by a published package.
+    //
+    // Measured 2026-08-24, `openkal-llvm-runtime` declaring the newly named
+    // compiler-runtime layer, read by the release before it:
+    //
+    //   error: dependency 'openkal-llvm-runtime': mcpp.toml: error:
+    //          `provides = ["mcpp:compiler-runtime=compiler-rt"]` names no
+    //          capability mcpp knows.
+    //
+    // Whose manifest it is decides the answer. A name in the ROOT project's own
+    // manifest is the author's to fix and they are looking at the build — an
+    // error. A name in a DEPENDENCY's manifest was written against a newer
+    // engine, and the correct response is to ignore the layer and say so, which
+    // is what this engine already does for every other unknown key.
+    std::vector<std::string>    unknownCapabilities;
+
     Package                     package;
     Language                    language;
     Modules                     modules;

tests/e2e/281_target_side_rules.sh

@@ -131,4 +131,62 @@ out="$("$MCPP" build 2>&1)" || rc=$?
 grep -q "not a layer a package can supply" <<< "$out" || {
     echo "the refusal does not say why:"; echo "$out"; exit 1; }
 
+# ── The layer vocabulary must be extensible by a published package ──────────
+#
+# ⚠️ This one comes from a measurement, and the behaviour it replaces made the
+# vocabulary permanently un-extendable:
+#
+#     error: dependency 'openkal-llvm-runtime': mcpp.toml: error:
+#            `provides = ["mcpp:compiler-runtime=compiler-rt"]` names no
+#            capability mcpp knows.
+#
+# A package declaring a newly named layer failed to load under every engine
+# released before that layer was named. Whose manifest it is decides the
+# answer: the root's is a misspelling the author is looking at, a dependency's
+# is a manifest written against a newer engine.
+cd ..
+mkdir -p future app4/src
+cat > future/mcpp.toml <<'TOML'
+[package]
+namespace = "probe"
+name      = "from-the-future"
+version   = "0.1.0"
+provides  = ["mcpp:quantum-abi=spooky"]
+
+[build]
+sources = []
+TOML
+cat > app4/mcpp.toml <<'TOML'
+[package]
+name    = "app4"
+version = "0.1.0"
+
+[dependencies]
+from-the-future = { path = "../future" }
+TOML
+printf 'int main(){ return 0; }\n' > app4/src/main.cpp
+cd app4
+rc=0
+out="$("$MCPP" build 2>&1)" || rc=$?
+[[ "$rc" -eq 0 ]] || {
+    echo "a dependency naming a layer this engine does not know must not fail the build:"
+    echo "$out"; exit 1; }
+grep -q "quantum-abi" <<< "$out" || {
+    echo "the ignored layer must be named:"; echo "$out"; exit 1; }
+
+# And the same name in the ROOT's own manifest is the author's to fix.
+cat > mcpp.toml <<'TOML'
+[package]
+name     = "app4"
+version  = "0.1.0"
+provides = ["mcpp:quantum-abi=spooky"]
+TOML
+rc=0
+out="$("$MCPP" build 2>&1)" || rc=$?
+[[ "$rc" -ne 0 ]] || {
+    echo "a misspelled layer name in the root manifest must be an error:"
+    echo "$out"; exit 1; }
+grep -q "names no capability mcpp knows" <<< "$out" || {
+    echo "the refusal does not say what is wrong:"; echo "$out"; exit 1; }
+
 echo "OK"