fix(manifest): 不认识的依赖键降级而不是让整份 manifest 加载失败

`reexport` 要写进**已发布包**的 manifest(grpc 的 [feature-deps.codegen]),
于是冒出一个此前没人问过的问题:比它旧的 mcpp 读到会怎样?

答案曾经是整份加载失败,而且报错误导 —— `reexport = true` 被告知
「must be a string, inline dep table, or nested table」。

根因是**一个谓词兼任两职**:`looks_like_inline_dep_spec` 既判定「内联 spec 还是
嵌套命名空间表」,又枚举「哪些键有意义」。不认识的键因此走不到「未知选项」那条
路上 —— 表直接判不出是 spec,被当成命名空间。

后果不是提示不友好,而是**任何已发布包都永远无法采用新键**。这与 #349 确立的
是同一条性质:数据不得决定程序是否可用。

判据换轴:内联 spec 的判定是「它是否指名了一个来源」(path/version/git/workspace)。
嵌套命名空间表的键是**包名**,不会有包叫 `version`,所以不会误判。识别为 spec
之后,不认识的键记为降级(--strict 仍拒绝),与 xpkg 读取器的 xpkgUnknownKeys
「record rather than swallow」同一条纪律。

救不了已经发布出去的旧客户端,但从这一版起这类问题不再复发。

Author: speak-agent

.agents/docs/2026-08-06-provisions-and-build-inputs.md

@@ -177,6 +177,30 @@ feature 存在的全部理由。
 
 这与索引解析裸包名的阶梯(`(mcpplibs,X) → (compat,X) → (∅,X)`)是同一条规则的同一次应用;第 3 级是必需的补充,否则 `grpc.grpc-plugin` 这类非默认命名空间的包连裸名都拿不到(grpc-m 现在写的正是 `dep_bin("grpc-plugin", ...)`)。`dep_dir()` 沿用同一套。
 
+### D1.4 发布一个新键不能让旧客户端加载失败
+
+`reexport` 要写进**已发布包**的 manifest(grpc 的 `[feature-deps.codegen]`),
+于是冒出一个此前没人问过的问题:比它旧的 mcpp 读到这份 manifest 会怎样?
+
+答案曾经是**整份加载失败**,而且报错是误导性的:
+`reexport = true` 被告知「must be a string, inline dep table, or nested table」。
+
+根因是**一个谓词兼任两职**:`looks_like_inline_dep_spec` 既判定「这是内联依赖
+spec 还是嵌套命名空间表」,又枚举「哪些键有意义」。于是「不认识的键」不会走到
+「未知选项」那条路上——表直接判不出是 spec,被当成命名空间。
+
+后果不是提示不友好,而是**任何已发布包都永远无法采用新键**。这与 #349 确立的
+性质是同一条:**数据不得决定程序是否可用**。
+
+判据换轴:**内联 spec 的判定是「它是否指名了一个来源」**(`path` / `version` /
+`git` / `workspace`)。嵌套命名空间表的键是**包名**,不会有包叫 `version`,所以
+这个判据不会误判。识别为 spec 之后,不认识的键**记为降级**(`--strict` 仍拒
+绝),而不是让整份 manifest 加载失败——与 xpkg 读取器的 `xpkgUnknownKeys`
+(「record rather than swallow」)同一条纪律。
+
+这不能救**已经发布出去的**旧客户端(它们的解析器就是那样),但从这一版起,
+这类问题不再复发。
+
 ### D2. 输入种类进表,指纹由种类决定
 
 新增一种输入:**glob**。

docs/05-mcpp-toml.md

@@ -1122,6 +1122,19 @@ int main() { return grpcgen::generate_all() ? 0 : 1; }
   unnamespaced `<x>`, else the single remaining candidate — and when it is
   contested mcpp says so instead of picking silently.
 
+##### Older mcpp reading a manifest that uses this
+
+An unrecognized dependency key is reported as a **degradation** and ignored
+(mcpp 2026.8.6.2+), so a package written for a newer mcpp still loads and the
+parts this reader understands still apply. Before that release it was a hard
+load failure with a misleading message, which is why a published package could
+not adopt a new key at all — the same property the index floor establishes:
+data must not decide whether the program works.
+
+Consequently a package that *relies* on `reexport` for its ergonomics still
+needs a client new enough to implement it; what changed is that everything else
+about that package keeps working on an older one.
+
 ##### Scoping a provision per platform
 
 A package may declare a `bin` target on some platforms only. Because the

docs/zh/05-mcpp-toml.md

@@ -858,6 +858,16 @@ int main() { return grpcgen::generate_all() ? 0 : 1; }
   依次绑定到 `mcpplibs.<x>`、`compat.<x>`、无命名空间的 `<x>`,最后才是「剩下
   的唯一候选」——存在争用时 mcpp 会说出来,而不是默默选一个。
 
+##### 旧版 mcpp 读到用了这些键的 manifest
+
+不认识的依赖键会被**记为降级**并忽略(mcpp 2026.8.6.2+),因此一份为更新的
+mcpp 写的包仍然能加载,这个读取器认识的部分照常生效。在那之前它是**整份加载
+失败**且报错误导,这正是「已发布的包永远无法采用新键」的原因——与索引下限确立
+的是同一条性质:**数据不得决定程序是否可用**。
+
+因此,一个**依赖** `reexport` 才有那套人机工程的包,仍然需要足够新的客户端;
+变化在于该包的其余部分在旧客户端上不再一起失效。
+
 ##### 按平台裁剪提供物
 
 一个包可能只在部分平台声明 `bin` 目标。既然现在是**库**决定请求什么,无条件的

src/manifest/toml.cppm

@@ -537,11 +537,7 @@ std::expected<Manifest, ManifestError> parse_string(std::string_view content,
     // namespaces (so existing fetcher / lockfile lookups by composite name
     // keep working) and the bare `<name>` for the default namespace (so the
     // common case stays unchanged).
-    // MUST list every key `fill_inline_spec` below reads. The two are one
-    // decision in two places: this predicate also distinguishes an inline dep
-    // spec from a NESTED namespace table, so a key missing here does not read
-    // as "unknown option" — the table is taken for a namespace and the user is
-    // told their value "must be a string, inline dep table, or nested table".
+    // MUST list every key `fill_inline_spec` below reads.
     // `Manifest.EveryDependencySpecKeyIsAccepted` holds the two in sync.
     auto is_dep_spec_key = [](std::string_view k) {
         return k == "path"   || k == "version" || k == "git"
@@ -551,19 +547,49 @@ std::expected<Manifest, ManifestError> parse_string(std::string_view content,
             || k == "backend"  || k == "tools"
             || k == "host-module" || k == "reexport";
     };
-    auto looks_like_inline_dep_spec = [&](const t::Table& sub) {
+    // What makes a table an inline dep spec is that it names a SOURCE. This
+    // used to be "every key is known", which quietly coupled two unrelated
+    // things: the discriminator (spec vs nested namespace table) and the
+    // vocabulary (which keys mean something).
+    //
+    // The coupling is a compatibility hazard, not a style problem. A manifest
+    // using a key introduced after the reader was built did not get "unknown
+    // option" — the table failed the discriminator, was taken for a NAMESPACE,
+    // and the user was told their `reexport = true` "must be a string, inline
+    // dep table, or nested table". Worse, a published package cannot adopt a
+    // new key at all, because every older client fails to load it outright
+    // rather than ignoring what it does not understand. That is the same
+    // property #349 established for the index floor: data must not be able to
+    // decide whether the program works.
+    //
+    // An identity key is an unambiguous discriminator: a nested namespace
+    // table's keys are PACKAGE names, and no package is named `version` /
+    // `path` / `git` / `workspace`.
+    auto looks_like_inline_dep_spec = [](const t::Table& sub) {
         if (sub.empty()) return false;
-        for (auto& [sk, sv] : sub) {
-            if (!is_dep_spec_key(sk)) return false;
-        }
-        return true;
+        for (auto& [sk, sv] : sub)
+            if (sk == "path" || sk == "version" || sk == "git" || sk == "workspace")
+                return true;
+        return false;
     };
 
     auto fill_inline_spec = [&](DependencySpec& spec,
                                 std::string_view section,
                                 std::string_view fqName,
                                 const t::Table& sub) -> std::expected<void, ManifestError>
     {
+        // Now that the discriminator no longer doubles as the vocabulary, an
+        // unrecognized key can be REPORTED — as a degradation, so `--strict`
+        // still refuses it, while an ordinary build of a package written for a
+        // newer mcpp proceeds with the part this one understands. Same
+        // discipline as the xpkg reader's `xpkgUnknownKeys`: record rather
+        // than swallow, and never fail the whole load over it.
+        for (auto& [sk, sv] : sub) {
+            if (is_dep_spec_key(sk)) continue;
+            m.schemaWarnings.push_back(std::format(
+                "[{}.\"{}\"] has unrecognized key '{}' (ignored). It may be a "
+                "typo, or a field a newer mcpp understands.", section, fqName, sk));
+        }
         if (auto it = sub.find("path");    it != sub.end() && it->second.is_string()) spec.path    = it->second.as_string();
         if (auto it = sub.find("version"); it != sub.end() && it->second.is_string()) spec.version = it->second.as_string();
         if (auto it = sub.find("git");     it != sub.end() && it->second.is_string()) spec.git     = it->second.as_string();
@@ -664,9 +690,10 @@ std::expected<Manifest, ManifestError> parse_string(std::string_view content,
             auto& sub = value.as_table();
             if (!looks_like_inline_dep_spec(sub)) {
                 return std::unexpected(error(origin, std::format(
-                    "[{}.{}] must be a version string or table of "
-                    "(path/version/git/rev/tag/branch/features/default-features/"
-                    "visibility/backend/workspace/tools/host-module/reexport)",
+                    "[{}.{}] must be a version string, or a table naming a "
+                    "source (one of path/version/git/workspace) alongside any "
+                    "of rev/tag/branch/features/default-features/visibility/"
+                    "backend/tools/host-module/reexport",
                     section, key)));
             }
             if (auto r = fill_inline_spec(spec, section, key, sub); !r) return r;

tests/unit/test_manifest.cpp

@@ -3160,3 +3160,76 @@ bypath     = { path = "../sibling" }
     EXPECT_NE(std::find(all->features.begin(), all->features.end(), "backend-openblas"),
               all->features.end());
 }
+
+// #359: a manifest written for a NEWER mcpp must still load.
+//
+// What made this impossible was that one predicate served two purposes: it
+// decided "inline dep spec vs nested namespace table" AND enumerated the
+// vocabulary. A key the reader did not know therefore did not read as an
+// unknown option — the table failed the discriminator, was taken for a
+// namespace, and the user was told their `reexport = true` "must be a string,
+// inline dep table, or nested table". A published package could consequently
+// never adopt a new key: every older client failed to load it outright.
+//
+// The discriminator is now "does it name a source", which a namespace table
+// cannot accidentally satisfy, and an unrecognized key is a recorded
+// degradation (--strict still refuses it).
+TEST(Manifest, UnknownDependencyKeyDegradesInsteadOfFailingTheLoad) {
+    auto tmp = std::filesystem::temp_directory_path() / "mcpp_dep_future_key";
+    std::filesystem::create_directories(tmp);
+    auto path = tmp / "mcpp.toml";
+    {
+        std::ofstream os(path);
+        os << R"(
+[package]
+name = "futurekey"
+version = "0.1.0"
+
+[dependencies]
+zlib = { version = "1.3.1", some-future-field = true }
+)";
+    }
+    auto m = mcpp::manifest::load(path);
+    ASSERT_TRUE(m) << (m ? "" : m.error().message);
+
+    const mcpp::pm::DependencySpec* z = nullptr;
+    for (auto const& [k, spec] : m->dependencies)
+        if (spec.shortName == "zlib") z = &spec;
+    ASSERT_NE(z, nullptr);
+    EXPECT_EQ(z->version, "1.3.1");   // the part this reader understands still applies
+
+    bool warned = false;
+    for (auto const& w : m->schemaWarnings)
+        if (w.find("some-future-field") != std::string::npos) warned = true;
+    EXPECT_TRUE(warned) << "the ignored key must be reported, not swallowed";
+}
+
+// The discriminator must not mistake a namespace subtable for an inline spec.
+// `[dependencies.compat] zlib = "1.3.1"` has one key, `zlib`, which names no
+// source — so it is a namespace, and the entry below it is the dependency.
+TEST(Manifest, NamespaceSubtableIsNotMistakenForAnInlineSpec) {
+    auto tmp = std::filesystem::temp_directory_path() / "mcpp_ns_vs_spec";
+    std::filesystem::create_directories(tmp);
+    auto path = tmp / "mcpp.toml";
+    {
+        std::ofstream os(path);
+        os << R"(
+[package]
+name = "nsvsspec"
+version = "0.1.0"
+
+[dependencies.compat]
+zlib = "1.3.1"
+gtest = { version = "1.15.2", features = ["main"] }
+)";
+    }
+    auto m = mcpp::manifest::load(path);
+    ASSERT_TRUE(m) << (m ? "" : m.error().message);
+    std::set<std::string> got;
+    for (auto const& [k, spec] : m->dependencies) {
+        got.insert(spec.shortName);
+        EXPECT_EQ(spec.namespace_, "compat") << spec.shortName;
+    }
+    EXPECT_TRUE(got.contains("zlib"));
+    EXPECT_TRUE(got.contains("gtest"));
+}