fix(platform): #254 host and target platform axes become distinct types; xpkg per-OS sections key on the target

mcpp resolves "which platform?" along two axes that coincide only for a
native build: the host (where mcpp runs — correct for toolchain payloads and
other host tools) and the target (where the produced binaries run — correct
for anything compiled INTO the user's build).

Both were std::string_view, so mixing them cost nothing and read identically,
and they had drifted apart: every xpkg per-OS splice and every xpm
version/asset table keyed on `mcpp::platform::xpkg_platform`, a COMPILE-TIME
HOST constant, while `[target.'cfg(...)']` was evaluated against the resolved
target. The same decision, derived two different ways. Cross-compiling
therefore spliced the host's section into a dependency being built for the
target: its per-OS sources, flags, deps and prebuilt asset all came from the
wrong leg. Native builds cannot observe this, which is why three-platform CI
never caught it.

Introduces mcpp.platform.axis: HostPlatform and TargetPlatform, with no
conversion between them and no constructor from a bare string. APIs take the
common PlatformKey base, so a function states which axis it accepts and a
call site must NAME the axis it supplies. `synthesize_from_xpkg_lua`'s
platform parameter loses its host default and becomes required — a silent
default is precisely how this bug survived. The triple-vs-xpkg vocabulary
translation ("macos" vs "macosx") moves into TargetPlatform::for_os so no
call site has to remember it.

The type change and the behaviour fix land together because they are the
same edit: once the parameter is required, every call site must decide, and
those decisions ARE the fix. Classified per site:

  prepare.cppm dep manifest synthesis (3), pm/resolver version+asset
  selection  -> TARGET; these are code compiled into the user's build.
  toolchain/lifecycle version listing -> HOST; a toolchain payload runs on
  this machine. Its existing comment already said so.
  cmd_xpkg --all-os -> for_lint_of(); neither axis, and named awkwardly on
  purpose so that reads as deliberate at the call site.
  scaffold `mcpp add` and the legacy resolver overloads -> HOST, stated
  explicitly rather than inherited from a default.

Tests: static_asserts that the axes are mutually inconvertible and neither is
constructible from a string; per-OS splice selects each target's own section
and none of the others; and a native-build guard asserting host == target
produces an identical splice, which is the safety net for every existing
platform's behaviour.

Author: Sunrisepeak

src/build/prepare.cppm

@@ -11,6 +11,7 @@ export module mcpp.build.prepare;
 
 import std;
 import mcpp.diag;
+import mcpp.platform.axis;
 import mcpp.libs.json;
 import mcpp.log;
 import mcpp.manifest;
@@ -595,6 +596,15 @@ prepare_build(bool print_fingerprint,
         return std::unexpected("no mcpp.toml found in current directory or any parent");
     }
 
+    // #254: everything compiled INTO this build is resolved for the TARGET —
+    // an xpkg descriptor's per-OS sections (sources, flags, deps) and its xpm
+    // asset/version table all describe code that will run on the target, not
+    // on the machine building it. This used to be a compile-time host
+    // constant, which is invisible natively (host == target) and picks the
+    // wrong leg under --target.
+    const auto targetPlatform = mcpp::platform::TargetPlatform::for_os(
+        cfgpred::context_for(overrides.target_triple).os);
+
     auto m = mcpp::manifest::load(*root / "mcpp.toml");
     if (!m) return std::unexpected(m.error().format());
 
@@ -1395,7 +1405,7 @@ prepare_build(bool print_fingerprint,
         // 0.0.10+: use structured namespace from DependencySpec.
         auto resolved = mcpp::pm::resolve_semver(
             s.namespace_, s.shortName.empty() ? depName : s.shortName,
-            s.version, fetcher);
+            s.version, fetcher, targetPlatform);
         if (!resolved) return std::unexpected(resolved.error());
         mcpp::ui::info("Resolved",
             std::format("{} {} → v{}", depName, s.version, *resolved));
@@ -1587,7 +1597,7 @@ prepare_build(bool print_fingerprint,
             }
             if (field.kind == mcpp::manifest::McppField::TableBody) {
                 auto dm = mcpp::manifest::synthesize_from_xpkg_lua(
-                    *luaContent, depName, version);
+                    *luaContent, depName, version, targetPlatform);
                 if (!dm) return false;
                 for (auto const& [generatedPath, _] : dm->buildConfig.generatedFiles) {
                     if (!generatedPath.empty()) return true;
@@ -1635,7 +1645,7 @@ prepare_build(bool print_fingerprint,
                 auto field = mcpp::manifest::extract_mcpp_field(*luaContent);
                 if (field.kind == mcpp::manifest::McppField::TableBody) {
                     auto depManifest = mcpp::manifest::synthesize_from_xpkg_lua(
-                        *luaContent, depName, version);
+                        *luaContent, depName, version, targetPlatform);
                     if (!depManifest) {
                         return std::unexpected(std::format(
                             "dependency '{}': {}", depName, depManifest.error().format()));
@@ -1811,7 +1821,8 @@ prepare_build(bool print_fingerprint,
                 "(expected exactly one)", depName, field.value, matches.size()));
             if (auto r = loadFrom(matches.front()); !r) return std::unexpected(r.error());
         } else if (field.kind == mcpp::manifest::McppField::TableBody) {
-            auto dm = mcpp::manifest::synthesize_from_xpkg_lua(*luaContent, depName, version);
+            auto dm = mcpp::manifest::synthesize_from_xpkg_lua(
+                *luaContent, depName, version, targetPlatform);
             if (!dm) return std::unexpected(std::format(
                 "dependency '{}': {}", depName, dm.error().format()));
             warn_unknown_xpkg_keys(*dm, depName);
@@ -2396,7 +2407,7 @@ prepare_build(bool print_fingerprint,
                     key.ns, key.shortName,
                     it->second.constraint,
                     item.originalConstraint,
-                    fetcher);
+                    fetcher, targetPlatform);
                 if (!merged) {
                     // Level 1 fallback: multi-version mangling. Two
                     // versions can't be reconciled by SemVer, but they

src/cli/cmd_xpkg.cppm

@@ -18,6 +18,7 @@ export module mcpp.cli.cmd_xpkg;
 import std;
 import mcpplibs.cmdline;
 import mcpp.manifest;
+import mcpp.platform.axis;
 import mcpp.ui;
 
 namespace mcpp::cli {
@@ -90,7 +91,8 @@ export int cmd_xpkg_parse(const mcpplibs::cmdline::ParsedArgs& parsed) {
     std::map<std::string, std::vector<std::string>> versions;
     std::string anyVersion;
     for (auto plat : kPlatforms) {
-        auto v = mcpp::manifest::list_xpkg_versions(lua, plat);
+        auto v = mcpp::manifest::list_xpkg_versions(
+            lua, mcpp::platform::TargetPlatform::for_lint_of(plat));
         if (!v.empty() && anyVersion.empty()) anyVersion = v.front();
         versions.emplace(std::string(plat), std::move(v));
     }
@@ -130,7 +132,8 @@ export int cmd_xpkg_parse(const mcpplibs::cmdline::ParsedArgs& parsed) {
                 continue;
             }
             auto pm = mcpp::manifest::synthesize_from_xpkg_lua(
-                lua, fqn, anyVersion, plat);
+                lua, fqn, anyVersion,
+                mcpp::platform::TargetPlatform::for_lint_of(plat));
             if (!pm) {
                 mcpp::ui::error(std::format("{} [{}]: {}", file, plat,
                                             pm.error().format()));
@@ -153,7 +156,10 @@ export int cmd_xpkg_parse(const mcpplibs::cmdline::ParsedArgs& parsed) {
     }
 
     // The parse users get at build time — same function, same grammar.
-    auto m = mcpp::manifest::synthesize_from_xpkg_lua(lua, fqn, anyVersion);
+    // Host axis here: `mcpp xpkg parse` with no --all-os is inspecting what
+    // THIS machine would read, which is a diagnostic question about the host.
+    auto m = mcpp::manifest::synthesize_from_xpkg_lua(
+        lua, fqn, anyVersion, mcpp::platform::HostPlatform::current());
     if (!m) {
         mcpp::ui::error(std::format("{}: {}", file, m.error().format()));
         return 1;

src/manifest/xpkg.cppm

@@ -8,6 +8,7 @@ import std;
 import mcpp.pm.dep_spec;
 import mcpp.pm.dependency_selector;
 import mcpp.platform;
+import mcpp.platform.axis;
 
 export namespace mcpp::manifest {
 
@@ -24,7 +25,8 @@ McppField extract_mcpp_field(std::string_view luaContent);
 // "windows") from an xpkg .lua's xpm.<platform> = { ["X.Y.Z"] = {...}, ... }.
 // Returns an empty vector if the platform table is missing or has no entries.
 std::vector<std::string>
-list_xpkg_versions(std::string_view luaContent, std::string_view platform);
+list_xpkg_versions(std::string_view luaContent,
+                   const mcpp::platform::PlatformKey& platform);
 // Extract the `namespace` field from an xpkg .lua's `package = { ... }` block.
 // Returns empty string if the field is absent (legacy descriptors).
 std::string extract_xpkg_namespace(std::string_view luaContent);
@@ -92,16 +94,22 @@ bool xpkg_lua_identity_matches(std::string_view luaContent,
 // The resulting Manifest is in-memory only; sourcePath is set to the
 // supplied package name + version so error messages can refer to it.
 //
-// `osOverride` selects which per-OS section (linux/macosx/windows) is
-// spliced into the parse instead of the running host's — the seam behind
-// `mcpp xpkg parse --all-os`, which validates the sections a host build
-// never reads (they are skip-tabled, so a typo in the `windows` block is
-// otherwise invisible on linux CI). Empty = host platform (build path).
+// `platform` selects which per-OS section (linux/macosx/windows) is spliced
+// into the parse. It is REQUIRED and axis-typed (#254): the per-OS sections
+// carry sources, flags, deps and the xpm asset table, so a package compiled
+// into the user's build must be spliced for the TARGET, while a host tool
+// wants the HOST. Before #254 this defaulted to a compile-time host
+// constant, which silently gave cross builds the wrong leg.
+//
+// TargetPlatform::for_lint_of() is the seam behind `mcpp xpkg parse
+// --all-os`, which validates the sections a build never reads (they are
+// skip-tabled, so a typo in the `windows` block is otherwise invisible on
+// linux CI).
 std::expected<Manifest, ManifestError>
 synthesize_from_xpkg_lua(std::string_view luaContent,
                          std::string_view packageName,
                          std::string_view packageVersion,
-                         std::string_view osOverride = {});
+                         const mcpp::platform::PlatformKey& platform);
 
 // mcpp#237: the mcpp-segment key vocabulary is a CLOSED whitelist (the parse
 // loop's else-if chain). An unrecognised key is collected into
@@ -708,7 +716,9 @@ bool xpkg_lua_identity_matches(std::string_view luaContent,
 }
 
 std::vector<std::string>
-list_xpkg_versions(std::string_view luaContent, std::string_view platform) {
+list_xpkg_versions(std::string_view luaContent,
+                   const mcpp::platform::PlatformKey& platformAxis) {
+    const std::string_view platform = platformAxis.key();
     // Locate `xpm = { ... <platform> = { ["X.Y.Z"] = {...}, ... } ... }`.
     // We work on a sanitized copy so quoted version keys remain locatable
     // by their offsets in the original text.
@@ -873,7 +883,7 @@ std::expected<Manifest, ManifestError>
 synthesize_from_xpkg_lua(std::string_view luaContent,
                          std::string_view packageName,
                          std::string_view packageVersion,
-                         std::string_view osOverride)
+                         const mcpp::platform::PlatformKey& platform)
 {
     auto body = extract_mcpp_segment_body(luaContent);
     if (body.empty()) {
@@ -885,8 +895,7 @@ synthesize_from_xpkg_lua(std::string_view luaContent,
             std::format("xpkg-lua of {}@{}", packageName, packageVersion),
             0, 0});
     }
-    const std::string_view osKey =
-        osOverride.empty() ? mcpp::platform::xpkg_platform : osOverride;
+    const std::string_view osKey = platform.key();
     if (auto platformBody = top_level_table_body_for_key(body, osKey);
         !platformBody.empty()) {
         body += "\n";

src/platform/axis.cppm

@@ -0,0 +1,89 @@
+// mcpp.platform.axis — the host/target platform axes, as distinct types.
+//
+// mcpp resolves "which platform?" along TWO axes that are equal only for a
+// native build:
+//
+//   host   — the machine mcpp is running on. Correct for host TOOLS: the
+//            toolchain payload, ninja, patchelf.
+//   target — the platform the produced binaries will run on. Correct for
+//            anything compiled INTO the user's build: a dependency's
+//            sources, flags, deps, and the prebuilt asset chosen for it.
+//
+// Both are spelled in the xpkg descriptor vocabulary (linux | macosx |
+// windows) and both were plain std::string_view, so mixing them cost
+// nothing and read identically. #254: every xpkg per-OS section and every
+// xpm version table was keyed on a compile-time HOST constant, while
+// `[target.'cfg(...)']` was evaluated against the RESOLVED TARGET — the same
+// decision derived two different ways. Cross-compiling therefore spliced the
+// host's section into a dependency built for the target. Native builds hide
+// it, because there the two axes coincide, which is why three-platform CI
+// never caught it.
+//
+// Making them separate types means an API states which axis it wants, and a
+// call site must name the axis it is supplying. There is deliberately no
+// conversion between them and no constructor from a bare string: the
+// interesting bugs here are all "the wrong axis was passed", and a string
+// parameter cannot express the difference.
+
+export module mcpp.platform.axis;
+
+import std;
+import mcpp.platform;
+
+export namespace mcpp::platform {
+
+// A resolved xpkg platform key. Only obtainable through one of the axis
+// types below, so possession of one implies somebody decided which axis it
+// came from.
+class PlatformKey {
+public:
+    std::string_view key() const { return key_; }
+
+    bool operator==(const PlatformKey& other) const { return key_ == other.key_; }
+
+protected:
+    explicit PlatformKey(std::string key) : key_(std::move(key)) {}
+
+private:
+    std::string key_;
+};
+
+// The machine mcpp itself is running on.
+class HostPlatform : public PlatformKey {
+public:
+    static HostPlatform current() {
+        return HostPlatform(std::string(mcpp::platform::xpkg_platform));
+    }
+
+private:
+    explicit HostPlatform(std::string key) : PlatformKey(std::move(key)) {}
+};
+
+// The platform the artifacts being produced will run on.
+class TargetPlatform : public PlatformKey {
+public:
+    // From a resolved triple's `os` token. The triple vocabulary says
+    // "macos" where xpkg descriptors say "macosx"; that translation lives
+    // here so no caller has to remember it.
+    static TargetPlatform for_os(std::string_view tripleOs) {
+        if (tripleOs == "macos" || tripleOs == "macosx") return TargetPlatform("macosx");
+        if (tripleOs == "windows")                       return TargetPlatform("windows");
+        if (tripleOs == "linux")                         return TargetPlatform("linux");
+        // Unknown/absent os token: fall back to the host, which is what the
+        // whole code base did unconditionally before #254.
+        return TargetPlatform(std::string(mcpp::platform::xpkg_platform));
+    }
+
+    // For tooling that walks platforms it is not running on and is not
+    // building for — `mcpp xpkg parse --all-os` lints every per-OS section.
+    // Named awkwardly on purpose: it should be obvious at the call site that
+    // this is neither axis.
+    static TargetPlatform for_lint_of(std::string_view xpkgKey) {
+        return TargetPlatform(std::string(xpkgKey));
+    }
+
+private:
+    explicit TargetPlatform(std::string key) : PlatformKey(std::move(key)) {}
+};
+
+} // namespace mcpp::platform

src/pm/resolver.cppm

@@ -18,6 +18,7 @@ export module mcpp.pm.resolver;
 import std;
 import mcpp.manifest;
 import mcpp.platform;
+import mcpp.platform.axis;
 import mcpp.pm.compat;
 import mcpp.pm.package_fetcher;
 import mcpp.version_req;
@@ -44,15 +45,17 @@ bool is_version_constraint(std::string_view v);
 std::expected<std::string, std::string>
 resolve_semver(std::string_view ns, std::string_view shortName,
                std::string_view constraint,
-               mcpp::pm::Fetcher& fetcher);
+               mcpp::pm::Fetcher& fetcher,
+               const mcpp::platform::PlatformKey& platform);
 
 // Try to AND-merge two version constraints and resolve to a single
 // concrete version satisfying both. Uses structured (ns, shortName).
 std::expected<std::string, std::string>
 try_merge_semver(std::string_view ns, std::string_view shortName,
                  std::string_view a,
                  std::string_view b,
-                 mcpp::pm::Fetcher& fetcher);
+                 mcpp::pm::Fetcher& fetcher,
+                 const mcpp::platform::PlatformKey& platform);
 
 // ─── Legacy overloads (COMPAT, remove in 1.0.0) ─────────────────────
 
@@ -85,7 +88,8 @@ bool is_version_constraint(std::string_view v) {
 std::expected<std::string, std::string>
 resolve_semver(std::string_view ns, std::string_view shortName,
                std::string_view constraint,
-               mcpp::pm::Fetcher& fetcher)
+               mcpp::pm::Fetcher& fetcher,
+               const mcpp::platform::PlatformKey& platform)
 {
     namespace vr = mcpp::version_req;
     auto qname = mcpp::pm::compat::qualified_name(ns, shortName);
@@ -105,11 +109,11 @@ resolve_semver(std::string_view ns, std::string_view shortName,
             qname, constraint, req.error()));
     }
 
-    auto rawVersions = mcpp::manifest::list_xpkg_versions(*luaContent, kXpkgPlatform);
+    auto rawVersions = mcpp::manifest::list_xpkg_versions(*luaContent, platform);
     if (rawVersions.empty()) {
         return std::unexpected(std::format(
             "dependency '{}': index entry has no versions for platform '{}'",
-            qname, kXpkgPlatform));
+            qname, platform.key()));
     }
 
     std::vector<vr::Version> parsed;
@@ -141,7 +145,8 @@ std::expected<std::string, std::string>
 try_merge_semver(std::string_view ns, std::string_view shortName,
                  std::string_view a,
                  std::string_view b,
-                 mcpp::pm::Fetcher& fetcher)
+                 mcpp::pm::Fetcher& fetcher,
+                 const mcpp::platform::PlatformKey& platform)
 {
     auto canon = [](std::string_view v) -> std::string {
         if (v.empty() || v == "*") return std::string{};
@@ -157,7 +162,7 @@ try_merge_semver(std::string_view ns, std::string_view shortName,
     else if (!cb.empty())            merged = cb;
     else                              merged = "*";
 
-    return resolve_semver(ns, shortName, merged, fetcher);
+    return resolve_semver(ns, shortName, merged, fetcher, platform);
 }
 
 // ─── Legacy overloads (COMPAT, remove in 1.0.0) ─────────────────────
@@ -168,8 +173,11 @@ resolve_semver(std::string_view name,
                mcpp::pm::Fetcher& fetcher)
 {
     auto resolved = mcpp::pm::compat::resolve_package_name(name, "");
+    // Legacy overload: no target is threaded through it, so it names the host
+    // axis explicitly rather than inheriting a silent default (#254).
     return resolve_semver(resolved.namespace_, resolved.shortName,
-                          constraint, fetcher);
+                          constraint, fetcher,
+                          mcpp::platform::HostPlatform::current());
 }
 
 std::expected<std::string, std::string>
@@ -179,8 +187,10 @@ try_merge_semver(std::string_view name,
                  mcpp::pm::Fetcher& fetcher)
 {
     auto resolved = mcpp::pm::compat::resolve_package_name(name, "");
+    // Legacy overload — see the resolve_semver note above.
     return try_merge_semver(resolved.namespace_, resolved.shortName,
-                            a, b, fetcher);
+                            a, b, fetcher,
+                            mcpp::platform::HostPlatform::current());
 }
 
 } // namespace mcpp::pm

src/scaffold/create.cppm

@@ -14,6 +14,7 @@ import mcpp.fetcher;
 import mcpp.fetcher.progress;
 import mcpp.manifest;
 import mcpp.pm.compat;
+import mcpp.platform.axis;
 import mcpp.pm.resolver;
 import mcpp.scaffold;
 import mcpp.ui;
@@ -67,7 +68,10 @@ fetch_template_package(const mcpp::scaffold::TemplateSpec& spec) {
 
     std::string version = spec.version;
     if (version.empty()) {
-        auto v = mcpp::pm::resolve_semver(ns, shortName, "*", fetcher);
+        // `mcpp add` has no target concept — the axis it means is the host,
+        // named explicitly rather than inherited from a default (#254).
+        auto v = mcpp::pm::resolve_semver(ns, shortName, "*", fetcher,
+                                          mcpp::platform::HostPlatform::current());
         if (!v) return std::unexpected(v.error());
         version = *v;
     }