// mcpp.runtime.binding — immutable runtime contract snapshot.

//

// RuntimeSelection decides WHICH local development OS is authoritative. This

// module reads that exact SubOS once and turns its xlings contract into a value

// carried by the build plan, fingerprint and fast-path cache. No later phase

// is allowed to follow `current`, inspect an active shell, or re-read the file.

export module mcpp.runtime.binding;

import std;

// NOT `mcpp.config`. This module needs ONE path out of it, and importing the

// whole thing put the platform layer above configuration, xlings and the

// package manager -- which is what kept `src/platform` from being a package of

// its own. The caller passes the path; see subos_path.

import mcpp.libs.json;

import mcpp.platform;

import mcpp.provider;

import mcpp.provider.select;

import mcpp.provider.runtime_selection;

export namespace mcpp::platform::runtime {

struct RuntimeBinding {

int schema = 0;

std::string providerId;

std::string platform;

std::string arch;

// Provider-native runtime identity (`glibc@...`, `macos_sdk@...`,

// `ucrt@...`). Only Linux additionally projects this into `libc`.

//

// THE PROVIDERS ARE NOT ISOMORPHIC, and treating them as such is the

// mistake this note exists to prevent:

//

// glibc@2.39 binds a PAYLOAD. The headers and the .so are both in it,

// and patchelf makes the artifact actually run on that

// copy. It is a runtime BINDING.

// ucrt@10.0… declares a FLOOR. `ucrtbase.dll` is an OS component from

// Win10 on; it cannot be swapped and should not be

// shipped, so mcpp's `windows-sdk` payload deliberately

// carries only half of ucrt (headers + import libraries)

// and no `Universal CRT Redistributable`. The identity

// says which API surface was compiled against, not which

// binary will be loaded.

//

// Both belong in this field — they are the same QUESTION ("which C

// runtime is this artifact built for") answered by different providers —

// but a consumer that assumes the glibc shape will try to resolve a

// payload that was never supposed to exist. Ask `runtime_provider()`

// before acting on the value.

std::string runtimeId;

std::string contractHash;

std::optional<std::filesystem::path> loader;

// Empty means absent. Plain strings rather than `std::optional<std::string>`:

// that member type does not copy under clang with the MSVC STL once the

// importers' module graph changes (see `TargetEntry::sysroot`).

std::string libc;

std::string hostLibc;

// IMMUTABLE payload directories (`<store>/xim-x-glibc/2.39/lib64`).

std::vector<std::filesystem::path> libraryDirs;

// The SubOS symlink farm (`<subos>/lib`) — a union view of everything

// installed into this environment, rewritten on every re-resolution.

//

// Deliberately a SECOND field rather than more entries in `libraryDirs`:

// merging them discards the immutability distinction, and that

// distinction is the whole of `mcpp.platform.runtime_search`'s ordering

// rule. A payload directory and a farm directory are not interchangeable

// even when they currently resolve to the same file.

std::vector<std::filesystem::path> searchDirs;

std::vector<mcpp::provider::runtime_info::EnvDecl> environment;

std::vector<std::string> providerBindings;

std::vector<std::string> capabilities;

std::vector<mcpp::provider::runtime_info::CapabilityProvider> runtimeProviders;

std::vector<mcpp::provider::runtime_info::RuntimeArtifact> runtimeArtifacts;

std::string provenance;

std::filesystem::path subosDir;

mcpp::provider::runtime::RuntimeSelection selection;

// Did the SubOS describe itself (does it carry a `subos_info` block)?

//

// FALSE IS NOT AN ERROR. A SubOS that says nothing leaves some facts

// unknown — rules A/B become inconclusive, declared environment is

// unavailable — and leaves everything else working. Treating absence as a

// failure is what stopped every `mcpp build` and `mcpp test` on Windows

// (openxlings/xlings#543), on a machine where the missing facts describe

// concepts (ELF, PT_INTERP, a private libc) that do not exist there.

//

// A CONTRADICTION still fails: naming a SubOS that is not present cannot

// be satisfied, so it is reported rather than degraded.

bool declared = false;

// Why something degraded. Non-empty ⇒ the caller MUST surface it. Never

// an error: "it did not happen" and "it succeeded" producing identical

// output is the property that made mcpp#352 expensive.

std::string note;

// Does this artifact run under a PRIVATE loader?

//

// The predicate the closure resolver needs: when PT_INTERP points into a

// payload, the HOST loader's built-in default directories are not part of

// the search path, and modelling them is how a binary that cannot start

// was reported as valid.

bool hermetic() const { return loader.has_value(); }

};

// The PROVIDER half of a runtime identity: "glibc" from "glibc@2.39", "ucrt"

// from "ucrt@10.0.26100.0". Empty when there is no identity at all.

//

// Exists so consumers DISPATCH instead of pattern-matching. Every reader of

// `runtimeId` used to spell `starts_with("glibc@")`, which reads as "is this

// glibc" and behaves as "is this the only provider I have ever seen" — so the

// day a second provider appeared, each of those sites silently classified it

// as "no runtime identity" rather than "an identity with no rules here". The

// two are not the same thing, and only one of them is worth reporting.

std::string_view runtime_provider(std::string_view runtimeId) {

auto at = runtimeId.find('@');

if (at == std::string_view::npos) return {};

return runtimeId.substr(0, at);

}

// Attach the Windows C runtime identity to an already-resolved snapshot, and

// re-derive the contract hash so it takes effect.

//

// WHY IT IS A SECOND STEP rather than part of resolve_runtime_binding(): the

// SDK version is a property of the TOOLCHAIN, and the binding is deliberately

// resolved BEFORE any toolchain — the post-install fixup is itself a consumer

// of the binding, so resolving a toolchain first would let directory order

// choose a libc and only then discover what the project selected (#392).

// Windows is the one platform where a fact flows the other way, so it flows

// back explicitly instead of reordering the two.

//

// WHAT IT BUYS: the SDK version enters `contractHash`, which is part of the

// toolchain fingerprint, which keys the build cache. Two SDKs produce two

// caches. Without this the version axis simply stopped existing one layer

// below the compiler — the exact defect this identity was added to close.

//

// Idempotent, and a no-op for an empty version: a Windows box with no SDK

// found still builds (selection UX must work there), it just has nothing to

// declare.

void bind_windows_ucrt(RuntimeBinding& binding, std::string_view sdkVersion);

namespace detail {

std::string hash_contract(std::string_view data) {

std::uint64_t h = 0xcbf29ce484222325ull;

for (unsigned char c : data) {

h ^= c;

h *= 0x100000001b3ull;

}

static constexpr char hex[] = "0123456789abcdef";

char buf[16];

for (int i = 15; i >= 0; --i) {

buf[i] = hex[h & 0xf];

h >>= 4;

}

return std::string(buf, sizeof(buf));

}

void append_field(std::string& out, std::string_view value) {

out += std::to_string(value.size());

out.push_back(':');

out.append(value);

out.push_back(';');

}

std::string canonical_contract(const RuntimeBinding& binding) {

std::string out;

append_field(out, std::to_string(binding.schema));

append_field(out, binding.providerId);

append_field(out, binding.platform);

append_field(out, binding.arch);

append_field(out, binding.runtimeId);

append_field(out, binding.selection.mode

== mcpp::provider::runtime::RuntimeSelection::Mode::McppDefault

? "mcpp-default" : "named");

append_field(out, binding.selection.subosName);

append_field(out, binding.provenance);

append_field(out, binding.loader ? binding.loader->generic_string() : "");

append_field(out, binding.libc);

append_field(out, binding.hostLibc);

for (auto const& p : binding.libraryDirs)

append_field(out, p.generic_string());

// A payload reinstalled under the same version with changed content is a

// different runtime (openxlings/xlings#620), so its packaging revision is

// part of the contract. Revision 0 contributes nothing: a payload installed

// before revisions existed keeps the contract, and the output directory,

// it had.

for (auto const& p : binding.libraryDirs)

if (const int r = mcpp::provider::revision_of(p.parent_path())

.value_or(0); r > 0)

append_field(out, std::format("revision={}", r));

// The farm participates in the hash because it participates in the

// artifact: it lands in DT_RPATH, so a build made against one farm is not

// interchangeable with a build made against another. `declared` is in for

// the same reason — a SubOS that gains self-description changes what the

// build knows, and the fast path must not reuse the older answer.

append_field(out, binding.declared ? "declared" : "undeclared");

for (auto const& p : binding.searchDirs)

append_field(out, p.generic_string());

for (auto const& provider : binding.providerBindings)

append_field(out, provider);

for (auto const& d : binding.environment) {

append_field(out, d.var);

append_field(out, d.op);

append_field(out, d.value);

}

for (auto const& capability : binding.capabilities)

append_field(out, capability);

for (auto const& provider : binding.runtimeProviders) {

append_field(out, provider.capability);

append_field(out, provider.provider.namespace_);

append_field(out, provider.provider.name);

append_field(out, provider.provider.version);

append_field(out, provider.provider.source);

}

for (auto const& artifact : binding.runtimeArtifacts) {

append_field(out, artifact.role);

append_field(out, artifact.provider.namespace_);

append_field(out, artifact.provider.name);

append_field(out, artifact.provider.version);

append_field(out, artifact.provider.source);

append_field(out, artifact.path.generic_string());

append_field(out, artifact.provenance);

append_field(out, artifact.abi);

append_field(out, artifact.digest);

append_field(out, artifact.hostFingerprint);

}

return out;

}

std::filesystem::path subos_path(

const mcpp::provider::runtime::RuntimeSelection& selection,

const std::filesystem::path& xlingsHome) {

using Mode = mcpp::provider::runtime::RuntimeSelection::Mode;

const auto& layout = mcpp::provider::layout();

if (selection.mode == Mode::McppDefault || selection.subosName == "default")

return layout.environment(xlingsHome, "default");

return layout.environment(layout.project_home(selection.ownerRoot), selection.subosName);

}

// `subos_info.runtime` is the provider's declared identity, while the SubOS

// view is the provider's resolved result. Older xlings states can retain the

// declaration after a package transaction has atomically repointed the view

// (observed in CI as runtime=glibc@2.39 with libc.so.6 resolving to the managed

// 2.44 payload). When the physical target can be proven to be one exact

// provider payload, use that immutable identity. This is not directory

// discovery: the selected SubOS link supplies the one path, and mcpp merely

// canonicalizes its provenance.

std::optional<std::string> managed_glibc_identity(

const std::filesystem::path& libraryDir,

const std::filesystem::path& xlingsRoot) {

std::error_code bec, lec;

const auto& layout = mcpp::provider::layout();

auto base = std::filesystem::weakly_canonical(

layout.tool_in(layout.store_of_home(xlingsRoot), "glibc"), bec);

auto real = std::filesystem::weakly_canonical(libraryDir, lec);

if (bec || lec || base.empty() || real.empty()) return std::nullopt;

auto relative = real.lexically_relative(base);

if (relative.empty() || relative.is_absolute()) return std::nullopt;

std::vector<std::string> parts;

for (auto const& part : relative) parts.push_back(part.string());

if (parts.size() != 2 || (parts[1] != "lib" && parts[1] != "lib64"))

return std::nullopt;

auto const& version = parts[0];

if (version.empty() || version == "." || version == ".."

|| version.find('@') != std::string::npos

|| version.find('/') != std::string::npos

|| version.find('\\') != std::string::npos)

return std::nullopt;

return "glibc@" + version;

}

struct ManagedGlibcPayload {

std::filesystem::path libraryDir;

std::filesystem::path loader;

};

std::optional<ManagedGlibcPayload> exact_declared_glibc_payload(

std::string_view runtimeId,

const std::filesystem::path& xlingsRoot) {

constexpr std::string_view prefix = "glibc@";

if (!runtimeId.starts_with(prefix)) return std::nullopt;

auto version = runtimeId.substr(prefix.size());

if (version.empty() || version == "." || version == ".."

|| version.find('@') != std::string_view::npos

|| version.find('/') != std::string_view::npos

|| version.find('\\') != std::string_view::npos)

return std::nullopt;

const auto& layout = mcpp::provider::layout();

auto payload = layout.tool_in(layout.store_of_home(xlingsRoot), "glibc")

/ std::string(version);

for (auto const& leaf : {"lib64", "lib"}) {

auto lib = payload / leaf;

std::error_code ec;

if (!std::filesystem::is_regular_file(lib / "libc.so.6", ec))

continue;

std::vector<std::filesystem::path> loaders;

ec.clear();

for (auto it = std::filesystem::directory_iterator(lib, ec);

!ec && it != std::filesystem::directory_iterator{};

it.increment(ec)) {

auto name = it->path().filename().string();

if (name.starts_with("ld-linux-") && name.find(".so") != std::string::npos

&& it->is_regular_file(ec))

loaders.push_back(it->path());

}

std::sort(loaders.begin(), loaders.end());

if (loaders.size() == 1)

return ManagedGlibcPayload{lib, loaders.front()};

}

return std::nullopt;

}

} // namespace detail

std::expected<RuntimeBinding, std::string>

resolve_runtime_binding(

const mcpp::provider::runtime::RuntimeSelection& selection,

const std::filesystem::path& /*compiler*/,

const std::filesystem::path& xlingsHome) {

RuntimeBinding out;

out.selection = selection;

out.subosDir = detail::subos_path(selection, xlingsHome).lexically_normal();

std::error_code ec;

if (!std::filesystem::is_directory(out.subosDir, ec)) {

return std::unexpected(std::format(

"selected SubOS '{}' does not exist at {}; create/bootstrap that "

"environment instead of falling back to active/default",

selection.subosName, out.subosDir.string()));

}

// CONTRADICTION vs ABSENCE. The check above is a contradiction: the user

// named a SubOS that is not there, and no amount of degrading makes that

// request satisfiable. Everything below is absence — some facts are

// unavailable, the rest of the build is unaffected — so it degrades.

//

// The distinction is not academic. Collapsing it is what made every

// `mcpp build` and `mcpp test` on Windows fail with a message about GL

// drivers (openxlings/xlings#543), and it is the same shape as the index

// floor incident: DATA THAT IS MISSING OR NEWER MUST NOT INVALIDATE THE

// PROGRAM THAT READS IT.

auto note = [&](std::string message) {

if (!out.note.empty()) out.note += "\n";

out.note += std::move(message);

};

auto info = mcpp::provider::layout().runtime_info(out.subosDir);

out.declared = info.present;

if (!info.present) {

note(std::format(

"SubOS '{}' does not describe itself: {}\n"

" Runtime facts (identity, loader, declared environment) are "

"unavailable: runtime rules report `inconclusive` rather than a "

"verdict, and a program launched from here gets no environment this "

"SubOS declares.\n"

" Where the C runtime comes from a payload, there is now no "

"declared runtime to bind to — mcpp declines to guess a version, so "

"the link falls back to the host and the hermeticity check will say "

"so. Run `xlings self doctor --fix` from inside this SubOS to have "

"it described (openxlings/xlings#547).",

selection.subosName,

info.note.empty() ? "no `subos_info` block" : info.note));

} else if (info.schema > mcpp::provider::runtime_info::kSupportedSchema) {

// Mirrors `subos_info::read`, which already reads a HIGHER schema and

// says so. A consumer stricter than its own reader is a time bomb:

// the day xlings writes schema 2, an equality check stops every build

// on every platform.

note(std::format(

"SubOS '{}' declares runtime contract schema {}, newer than the {} "

"this mcpp understands; using the fields it knows",

selection.subosName, info.schema,

mcpp::provider::runtime_info::kSupportedSchema));

}

if (info.present && info.runtime.empty()) {

note(std::format(

"SubOS '{}' has no runtime identity in subos_info.runtime; runtime "

"rules cannot be evaluated for artifacts built here",

selection.subosName));

}

out.schema = info.schema;

out.providerId = "xlings";

out.platform = std::string(mcpp::platform::name);

out.arch = std::string(mcpp::platform::host_arch);

out.runtimeId = info.runtime;

out.provenance = selection.mode

== mcpp::provider::runtime::RuntimeSelection::Mode::McppDefault

? "mcpp_default" : "named_subos";

// libc/ELF are Linux concepts. macOS and Windows still carry the same

// provider/environment contract without inventing a glibc field.

if constexpr (mcpp::platform::is_linux) {

out.libc = info.runtime;

if (!info.hostGlibc.empty()) out.hostLibc = info.hostGlibc;

// ONE traversal, TWO answers.

//

// searchDirs the view directory itself — the farm, where every

// library this environment installed is reachable by

// SONAME (`-lGL` already resolves here, because

// `--sysroot=<subos>` makes it the linker's default).

// libraryDirs the immutable payload the view's libc RESOLVES to.

//

// Deriving both here rather than in two places is the point: the

// layout knowledge (`lib64` before `lib`) exists exactly once.

//

// The view already embodies RuntimeSelection, so following these exact

// links is not payload discovery and cannot choose another installed

// version.

std::vector<std::filesystem::path> candidates{

out.subosDir / "lib64", out.subosDir / "lib"};

for (auto const& candidate : candidates) {

std::error_code fec;

if (std::filesystem::is_directory(candidate, fec))

out.searchDirs.push_back(candidate.lexically_normal());

}

for (auto const& candidate : candidates) {

std::error_code lec;

auto libc = candidate / "libc.so.6";

if (!std::filesystem::is_regular_file(libc, lec)) continue;

auto realLibc = std::filesystem::canonical(libc, lec);

auto libDir = lec ? candidate.lexically_normal()

: realLibc.parent_path();

out.libraryDirs.push_back(libDir);

if (auto physical = detail::managed_glibc_identity(

libDir, out.subosDir.parent_path().parent_path())) {

out.runtimeId = *physical;

out.libc = *physical;

}

std::vector<std::filesystem::path> loaders;

lec.clear();

for (auto it = std::filesystem::directory_iterator(candidate, lec);

!lec && it != std::filesystem::directory_iterator{};

it.increment(lec)) {

auto name = it->path().filename().string();

if (name.starts_with("ld-linux-") && name.find(".so") != std::string::npos)

loaders.push_back(it->path());

}

std::sort(loaders.begin(), loaders.end());

if (loaders.size() == 1) {

auto realLoader = std::filesystem::canonical(loaders.front(), lec);

out.loader = lec ? loaders.front().lexically_normal() : realLoader;

}

break;

}

if (out.libraryDirs.empty()) {

if (auto exact = detail::exact_declared_glibc_payload(

out.runtimeId, out.subosDir.parent_path().parent_path())) {

out.libraryDirs.push_back(exact->libraryDir);

out.loader = exact->loader;

}

}

}

for (auto const& provider : info.providers) {

out.providerBindings.push_back(provider.binding);

for (auto const& decl : provider.decls)

out.environment.push_back(decl);

}

out.runtimeProviders = info.runtimeProviders;

out.runtimeArtifacts = info.runtimeArtifacts;

for (auto const& provider : out.runtimeProviders)

out.capabilities.push_back(provider.capability);

std::sort(out.capabilities.begin(), out.capabilities.end());

out.capabilities.erase(

std::unique(out.capabilities.begin(), out.capabilities.end()),

out.capabilities.end());

out.contractHash = detail::hash_contract(detail::canonical_contract(out));

return out;

}

void bind_windows_ucrt(RuntimeBinding& binding, std::string_view sdkVersion) {

if (sdkVersion.empty()) return;

auto identity = std::format("ucrt@{}", sdkVersion);

if (binding.runtimeId == identity) return; // idempotent

binding.runtimeId = std::move(identity);

// Deliberately NOT projected into `libc`: that field is the Linux-only

// private-libc payload, read by the loader/patchelf machinery, and there

// is no ucrt payload for it to name. `runtime_binding.cppm`'s own comment

// on `libc` says "Only Linux additionally projects this" — this is that

// sentence being true rather than merely written down.

binding.contractHash =

detail::hash_contract(detail::canonical_contract(binding));

}

std::string serialize_runtime_binding(const RuntimeBinding& binding) {

nlohmann::json j;

j["schema"] = binding.schema;

j["provider_id"] = binding.providerId;

j["platform"] = binding.platform;

j["arch"] = binding.arch;

j["runtime_id"] = binding.runtimeId;

j["contract_hash"] = binding.contractHash;

j["loader"] = binding.loader ? binding.loader->generic_string() : "";

j["libc"] = binding.libc;

j["host_libc"] = binding.hostLibc;

j["library_dirs"] = nlohmann::json::array();

for (auto const& path : binding.libraryDirs)

j["library_dirs"].push_back(path.generic_string());

j["declared"] = binding.declared;

j["note"] = binding.note;

j["search_dirs"] = nlohmann::json::array();

for (auto const& path : binding.searchDirs)

j["search_dirs"].push_back(path.generic_string());

j["environment"] = nlohmann::json::array();

for (auto const& decl : binding.environment)

j["environment"].push_back({

{"var", decl.var}, {"op", decl.op}, {"value", decl.value}});

j["provider_bindings"] = binding.providerBindings;

j["capabilities"] = binding.capabilities;

j["runtime_providers"] = nlohmann::json::array();

for (auto const& provider : binding.runtimeProviders) {

j["runtime_providers"].push_back({

{"capability", provider.capability},

{"provider", {

{"namespace", provider.provider.namespace_},

{"name", provider.provider.name},

{"version", provider.provider.version},

{"source", provider.provider.source},

}},

});

}

j["runtime_artifacts"] = nlohmann::json::array();

for (auto const& artifact : binding.runtimeArtifacts) {

j["runtime_artifacts"].push_back({

{"role", artifact.role},

{"provider", {

{"namespace", artifact.provider.namespace_},

{"name", artifact.provider.name},

{"version", artifact.provider.version},

{"source", artifact.provider.source},

}},

{"path", artifact.path.generic_string()},

{"provenance", artifact.provenance},

{"abi", artifact.abi},

{"digest", artifact.digest},

{"host_fingerprint", artifact.hostFingerprint},

});

}

j["provenance"] = binding.provenance;

j["subos_dir"] = binding.subosDir.generic_string();

j["selection"] = {

{"mode", binding.selection.mode

== mcpp::provider::runtime::RuntimeSelection::Mode::McppDefault

? "mcpp_default" : "named_subos"},

{"source", binding.selection.source

== mcpp::provider::runtime::RuntimeSelection::Source::DefaultPolicy

? "default_policy" : "manifest"},

{"name", binding.selection.subosName},

{"owner_root", binding.selection.ownerRoot.generic_string()},

};

return j.dump();

}

std::expected<RuntimeBinding, std::string>

deserialize_runtime_binding(std::string_view encoded) {

auto j = nlohmann::json::parse(encoded, nullptr, false);

if (j.is_discarded() || !j.is_object())

return std::unexpected("cached RuntimeBinding is not valid JSON");

try {

RuntimeBinding out;

out.schema = j.value("schema", 0);

out.providerId = j.value("provider_id", "");

out.platform = j.value("platform", "");

out.arch = j.value("arch", "");

out.runtimeId = j.value("runtime_id", "");

out.contractHash = j.value("contract_hash", "");

if (auto v = j.value("loader", ""); !v.empty()) out.loader = v;

if (auto v = j.value("libc", ""); !v.empty()) out.libc = v;

if (auto v = j.value("host_libc", ""); !v.empty()) out.hostLibc = v;

if (auto it = j.find("library_dirs"); it != j.end() && it->is_array())

for (auto const& v : *it) if (v.is_string())

out.libraryDirs.emplace_back(v.get<std::string>());

out.declared = j.value("declared", false);

out.note = j.value("note", "");

if (auto it = j.find("search_dirs"); it != j.end() && it->is_array())

for (auto const& v : *it) if (v.is_string())

out.searchDirs.emplace_back(v.get<std::string>());

if (auto it = j.find("environment"); it != j.end() && it->is_array()) {

for (auto const& v : *it) {

if (!v.is_object()) continue;

mcpp::provider::runtime_info::EnvDecl decl;

decl.var = v.value("var", "");

decl.op = v.value("op", "");

decl.value = v.value("value", "");

if (!decl.var.empty() && (decl.op == "set" || decl.op == "prepend"))

out.environment.push_back(std::move(decl));

}

}

out.providerBindings = j.value(

"provider_bindings", std::vector<std::string>{});

out.capabilities = j.value(

"capabilities", std::vector<std::string>{});

auto read_identity = [](const nlohmann::json& value) {

mcpp::provider::runtime_info::PackageIdentity id;

if (!value.is_object()) return id;

id.namespace_ = value.value("namespace", "");

id.name = value.value("name", "");

id.version = value.value("version", "");

id.source = value.value("source", "");

return id;

};

if (auto it = j.find("runtime_providers");

it != j.end() && it->is_array()) {

for (auto const& value : *it) {

if (!value.is_object()) continue;

mcpp::provider::runtime_info::CapabilityProvider provider;

provider.capability = value.value("capability", "");

if (auto identity = value.find("provider"); identity != value.end())

provider.provider = read_identity(*identity);

if (!provider.capability.empty() && !provider.provider.name.empty())

out.runtimeProviders.push_back(std::move(provider));

}

}

if (auto it = j.find("runtime_artifacts");

it != j.end() && it->is_array()) {

for (auto const& value : *it) {

if (!value.is_object()) continue;

mcpp::provider::runtime_info::RuntimeArtifact artifact;

artifact.role = value.value("role", "");

if (auto identity = value.find("provider"); identity != value.end())

artifact.provider = read_identity(*identity);

artifact.path = value.value("path", "");

artifact.provenance = value.value("provenance", "");

artifact.abi = value.value("abi", "");

artifact.digest = value.value("digest", "");

artifact.hostFingerprint = value.value("host_fingerprint", "");

if (!artifact.role.empty() && !artifact.provider.name.empty()

&& !artifact.path.empty() && !artifact.provenance.empty())

out.runtimeArtifacts.push_back(std::move(artifact));

}

}

out.provenance = j.value("provenance", "");

out.subosDir = j.value("subos_dir", "");

auto s = j.at("selection");

out.selection.mode = s.value("mode", "") == "named_subos"

? mcpp::provider::runtime::RuntimeSelection::Mode::NamedSubos

: mcpp::provider::runtime::RuntimeSelection::Mode::McppDefault;

out.selection.source = s.value("source", "") == "manifest"

? mcpp::provider::runtime::RuntimeSelection::Source::Manifest

: mcpp::provider::runtime::RuntimeSelection::Source::DefaultPolicy;

out.selection.subosName = s.value("name", "default");

out.selection.ownerRoot = s.value("owner_root", "");

// Completeness is conditional on `declared`. An UNDECLARED binding

// legitimately has schema 0 and no runtime identity — that is what

// "the SubOS said nothing" looks like — so demanding those fields

// would make every cached degraded binding undecodable and send the

// build back down the slow path forever. The hash still has to match,

// which is what actually proves the record was not tampered with.

if (out.contractHash.empty() || out.subosDir.empty())

return std::unexpected("cached RuntimeBinding is incomplete");

if (out.declared && (out.schema == 0 || out.runtimeId.empty()))

return std::unexpected("cached RuntimeBinding is incomplete");

if (detail::hash_contract(detail::canonical_contract(out))

!= out.contractHash)

return std::unexpected("cached RuntimeBinding contract hash does not match payload");

return out;

} catch (const std::exception& e) {

return std::unexpected(std::format(

"cached RuntimeBinding cannot be decoded: {}", e.what()));

}

}

std::vector<std::pair<std::string, std::string>>

resolve_runtime_environment(

const RuntimeBinding& binding,

const std::function<std::optional<std::string>(std::string_view)>& ambient = {}) {

mcpp::provider::runtime_info::Info info;

info.present = true;

mcpp::provider::runtime_info::Declarer snapshot;

snapshot.binding = "runtime-binding-snapshot";

snapshot.decls = binding.environment;

info.providers.push_back(std::move(snapshot));

return mcpp::provider::resolve_env(info, binding.subosDir, ambient);

}

} // namespace mcpp::platform::runtime