feat(pm): index.toml version contract — floor check at the index-open choke point

An index tree may carry index.toml ([index] spec / min_mcpp / latest_mcpp).
The contract travels WITH the tree, so ONE check in
read_identity_verified_xpkg_lua — the choke point every transport
converges on (artifact snapshot, git clone, [indices] path, CI-restored
cache) — covers all of them, offline included. own < min_mcpp → loud
E0006 with the upgrade one-liner, once per index per process, then the
resolve fails with the cause already printed. Missing index.toml → no
constraint (back-compat, third-party indices). Malformed versions never
brick a client. Escape hatch: MCPP_INDEX_FLOOR=ignore.

Deviation from design D3 noted: staged-unpack + atomic swap for the
artifact refresh lives in vendored xlings (separate codebase) — the
open-time check is the mcpp-side enforcement; staging is a follow-up
there.

Verified: 3 unit tests (ordering incl. 0.0.90>0.0.85, malformed/absent
tolerance, TOML round-trip); e2e on mcpp-index: min_mcpp=9.9.9 → E0006 +
resolve stop; =0.0.84 → builds; MCPP_INDEX_FLOOR=ignore bypasses.

Design: .agents/docs/2026-07-08-index-version-semantics-and-descriptor-
grammar-design.md D3.

Author: Sunrisepeak

src/doctor.cppm

@@ -377,6 +377,12 @@ export int explain_code(std::string_view code) {
          "A cached BMI file referenced by manifest.txt is missing on disk. Run\n"
          "`mcpp cache prune --older-than 0d` to drop stale entries; the next build\n"
          "will repopulate."},
+        {"E0006", "index requires a newer mcpp",
+         "The package index declares (index.toml [index].min_mcpp) that its\n"
+         "descriptors need a newer mcpp than this binary — parsing them would\n"
+         "silently misbehave, so resolution stops instead. Upgrade mcpp:\n"
+         "  curl -fsSL https://github.com/mcpp-community/mcpp/releases/latest/download/install.sh | bash\n"
+         "To bypass for debugging only: MCPP_INDEX_FLOOR=ignore mcpp build"},
     };
     for (auto& e : table) {
         if (e.code == code) {
@@ -387,7 +393,7 @@ export int explain_code(std::string_view code) {
         }
     }
     std::println(stderr, "error: unknown error code '{}'", code);
-    std::println(stderr, "       known codes: E0001..E0005");
+    std::println(stderr, "       known codes: E0001..E0006");
     return 2;
 }
 

src/pm/index_contract.cppm

@@ -0,0 +1,114 @@
+// mcpp.pm.index_contract — the index→client version contract.
+//
+// An index tree (a directory containing pkgs/) may carry an `index.toml`
+// at its root:
+//
+//     [index]
+//     spec        = "1"        # index layout spec
+//     min_mcpp    = "0.0.85"   # oldest mcpp able to parse every descriptor
+//     latest_mcpp = "0.0.85"   # optional: newest known-good mcpp (hint)
+//
+// The contract travels WITH the tree (git checkout, unpacked artifact,
+// CI-restored cache, `[indices] path =` local dir), so one check at the
+// index-open choke point covers every transport, offline included.
+// Missing index.toml → no constraint (back-compat, third-party indices).
+//
+// Escape hatch: MCPP_INDEX_FLOOR=ignore (debugging).
+// Design: .agents/docs/2026-07-08-index-version-semantics-and-descriptor-
+// grammar-design.md (D3).
+
+export module mcpp.pm.index_contract;
+
+import std;
+import mcpp.libs.toml;
+import mcpp.version_req;
+import mcpp.toolchain.fingerprint;   // MCPP_VERSION
+
+export namespace mcpp::pm {
+
+struct IndexContract {
+    std::string spec;         // index layout spec ("1")
+    std::string minMcpp;      // floor: oldest client able to parse the tree
+    std::string latestMcpp;   // optional upgrade hint
+};
+
+// Read <indexRoot>/index.toml. nullopt when absent or unreadable
+// (absence is not an error — it simply means "no contract").
+std::optional<IndexContract>
+read_index_contract(const std::filesystem::path& indexRoot);
+
+// Pure floor predicate: does `ownVersion` satisfy `minMcpp`?
+// Returns the violation message when it does not; nullopt when fine
+// (including unparsable versions — the contract must never brick a
+// client by being malformed).
+std::optional<std::string>
+floor_violation(std::string_view minMcpp, std::string_view ownVersion);
+
+// Open-time check for an index tree. Combines read + floor + escape
+// hatch + once-per-root deduplication of the (expensive to spam) error.
+// Returns the violation message the FIRST time a too-new tree is opened;
+// nullopt otherwise.
+std::optional<std::string>
+check_index_floor(const std::filesystem::path& indexRoot);
+
+} // namespace mcpp::pm
+
+namespace mcpp::pm {
+
+std::optional<IndexContract>
+read_index_contract(const std::filesystem::path& indexRoot)
+{
+    std::error_code ec;
+    auto file = indexRoot / "index.toml";
+    if (!std::filesystem::exists(file, ec)) return std::nullopt;
+
+    std::ifstream is{file};
+    if (!is) return std::nullopt;
+    std::string body{std::istreambuf_iterator<char>(is), {}};
+
+    auto doc = mcpp::libs::toml::parse(body);
+    if (!doc) return std::nullopt;
+
+    IndexContract c;
+    if (auto v = doc->get_string("index.spec"))        c.spec       = *v;
+    if (auto v = doc->get_string("index.min_mcpp"))    c.minMcpp    = *v;
+    if (auto v = doc->get_string("index.latest_mcpp")) c.latestMcpp = *v;
+    return c;
+}
+
+std::optional<std::string>
+floor_violation(std::string_view minMcpp, std::string_view ownVersion)
+{
+    if (minMcpp.empty()) return std::nullopt;
+    auto need = mcpp::version_req::parse_version(minMcpp);
+    auto have = mcpp::version_req::parse_version(ownVersion);
+    if (!need || !have) return std::nullopt;   // malformed contract never bricks
+    if (*have >= *need) return std::nullopt;
+    return std::format(
+        "index requires mcpp >= {} but this is mcpp {} [E0006]\n"
+        "  Upgrade:  curl -fsSL https://github.com/mcpp-community/mcpp/"
+        "releases/latest/download/install.sh | bash\n"
+        "  Details:  mcpp explain E0006   "
+        "(override for debugging: MCPP_INDEX_FLOOR=ignore)",
+        minMcpp, ownVersion);
+}
+
+std::optional<std::string>
+check_index_floor(const std::filesystem::path& indexRoot)
+{
+    if (const char* v = std::getenv("MCPP_INDEX_FLOOR");
+        v && std::string_view(v) == "ignore")
+        return std::nullopt;
+
+    // Once per root per process: the same index is opened many times in a
+    // single resolve; report the violation once, stay quiet after.
+    static std::set<std::filesystem::path> reported;
+    auto c = read_index_contract(indexRoot);
+    if (!c) return std::nullopt;
+    auto violation = floor_violation(c->minMcpp, mcpp::toolchain::MCPP_VERSION);
+    if (!violation) return std::nullopt;
+    if (!reported.insert(indexRoot).second) return std::nullopt;
+    return violation;
+}
+
+} // namespace mcpp::pm

src/pm/package_fetcher.cppm

@@ -18,6 +18,8 @@ import mcpp.log;
 import mcpp.manifest;        // xpkg_lua_identity_matches — descriptor identity gate
 import mcpp.pm.compat;
 import mcpp.pm.dep_spec;
+import mcpp.pm.index_contract;   // index.toml floor check (E0006)
+import mcpp.ui;
 import mcpp.pm.index_spec;
 import mcpp.xlings;
 import mcpp.libs.toml;       // re-used for tiny JSON-ish parsing? no — stick with manual
@@ -431,6 +433,16 @@ read_identity_verified_xpkg_lua(const std::filesystem::path& pkgsDir,
                                 const std::vector<std::string>& filenames,
                                 std::string_view indexDefaultNs = {})
 {
+    // Index→client version contract: the tree carries its own floor
+    // (<indexRoot>/index.toml min_mcpp). Checked here — the single choke
+    // point every transport converges on (artifact snapshot, git clone,
+    // [indices] path, CI-restored cache). Loud once per index; the
+    // resolve then fails as not-found with the cause already printed.
+    if (auto violation = mcpp::pm::check_index_floor(pkgsDir.parent_path())) {
+        mcpp::ui::error(*violation);
+        return std::nullopt;
+    }
+
     std::error_code ec;
     if (!std::filesystem::exists(pkgsDir, ec)) return std::nullopt;
     for (auto& fname : filenames) {

tests/unit/test_index_contract.cpp

@@ -0,0 +1,37 @@
+#include <gtest/gtest.h>
+
+import std;
+import mcpp.pm.index_contract;
+
+TEST(IndexContract, FloorViolationOrdering) {
+    using mcpp::pm::floor_violation;
+    EXPECT_FALSE(floor_violation("0.0.85", "0.0.85").has_value());
+    EXPECT_FALSE(floor_violation("0.0.85", "0.0.90").has_value());
+    EXPECT_FALSE(floor_violation("0.0.85", "1.0.0").has_value());
+    auto v = floor_violation("0.0.85", "0.0.84");
+    ASSERT_TRUE(v.has_value());
+    EXPECT_NE(v->find("E0006"), std::string::npos);
+    EXPECT_NE(v->find("0.0.85"), std::string::npos);
+}
+
+TEST(IndexContract, EmptyOrMalformedNeverBricks) {
+    using mcpp::pm::floor_violation;
+    EXPECT_FALSE(floor_violation("", "0.0.84").has_value());
+    EXPECT_FALSE(floor_violation("not-a-version", "0.0.84").has_value());
+}
+
+TEST(IndexContract, ReadContractRoundTrip) {
+    auto dir = std::filesystem::temp_directory_path() / "mcpp_ic_test";
+    std::filesystem::create_directories(dir);
+    {
+        std::ofstream os(dir / "index.toml");
+        os << "[index]\nspec = \"1\"\nmin_mcpp = \"0.0.85\"\nlatest_mcpp = \"0.0.86\"\n";
+    }
+    auto c = mcpp::pm::read_index_contract(dir);
+    ASSERT_TRUE(c.has_value());
+    EXPECT_EQ(c->spec, "1");
+    EXPECT_EQ(c->minMcpp, "0.0.85");
+    EXPECT_EQ(c->latestMcpp, "0.0.86");
+    std::filesystem::remove_all(dir);
+    EXPECT_FALSE(mcpp::pm::read_index_contract(dir).has_value());
+}