feat(xlings): provision [xlings] deps on first build, at global scope

[Sunrisepeak]

Scope note — "where is the SubOS environment half?"

It is already in mcpp, and has been since #352. subos_info.cppm parses the
envs block, runtime_binding.cppm collects it into binding.environment,
execute.cppm::compute_subos_env() injects it into mcpp run / mcpp test
children with ${subosdir} expanded and prepend applied — and
tests/e2e/200_subos_env_reaches_program.sh already asserts exactly that
("one selected RuntimeBinding snapshot must reach full-path and cached
mcpp run without an environment/CLI override").

Nothing about that was missing. What was missing is a payload in the
SubOS mcpp reads, and that is this PR. The design note had also planned a
"layer the project SubOS over the toolchain SubOS" change (B3); measurement
showed it unnecessary once provisioning installs at the right scope, so it is
deliberately not here — see below.

---

[xlings] deps was declared and never installed. ensure_project_index_dir wrote it into .mcpp/.xlings.json verbatim and stopped there, so a manifest saying deps = ["xim:mesa"] produced a file naming mesa, no payload anywhere, and:

fatal error: gbm.h: No such file or directory

The declaration looked accepted and did nothing — the worst shape a config key can have. [toolchain] has had declare it and mcpp provisions it on first use all along (the "First run — no toolchain configured … installing … as default" block); a build environment should not have two grades of declaration.

Global scope, and the scope is the whole point

The obvious implementation — install_packages against make_project_xlings_env — installs at project scope, and measurably does not work. On a fresh MCPP_HOME the headers land in <proj>/.mcpp/.xlings/subos/_/usr/include while --sysroot names <MCPP_HOME>/registry/subos/default: two SubOS views, payload in the one the compiler does not read, #include <gbm.h> still failing with the dependency installed and declared.

make_xlings_env is the global env, so the payload lands in the registry whose SubOS is the sysroot — the same place [toolchain] installs into.

That single choice is what removes the need for any sysroot-layering machinery. Nothing in linkmodel.cppm, plan.runtimeSearch or link_line.cppm is touched — those carry ordering invariants whose own comments say "a mutable view that outranks either of them lets a later install silently change which library an ALREADY LINKED artifact loads. That is not hypothetical — it is the defect this module was created for."

Why install_packages and not resolve_xpkg_path

resolve_xpkg_path requires <name>@<version> and rejects a bare name — verified:

invalid xpkg target 'xim:mesa': expected `<name>@<version>`

A manifest is entitled to name a package without pinning it. install_packages resolves the version itself, and reports an ambiguous name with its candidates.

(Noted in passing: the toolchain path's (void)fetcher.resolve_xpkg_path(dep, …) for xim:glibc / xim:linux-headers discards its result, so the same rejection there would be silent. Not changed here.)

Declared deps only

Provisioning uses runtimeOwnerManifest.xlings.deps, not penv.deps. A cross-compilation target sysroot is appended to the latter a few lines up, and provisioning it would change behaviour for projects that never asked: a name that does not resolve would turn a build that used to proceed into a hard failure. The contract is what you declared gets installed; the sysroot entry is mcpp's inference, not the author's declaration.

Ordering is load-bearing

Provisioning runs before the runtime binding resolves, because a named [xlings] subos that does not exist yet is a hard error —

selected SubOS '_' does not exist at …; create/bootstrap that environment

— and provisioning is what creates it. Placed next to the custom-index sync, both first-use steps sit in one place.

Idempotent by content

A stamp records the dep list, so editing the list re-provisions and an unchanged list costs no xlings round-trip. Verified: a second mcpp run emits no Provisioning line.

Verified end to end on a fresh MCPP_HOME

A project with no mcpp-index dependency at all:

[xlings]
deps = ["xim:mesa"]

[build]
ldflags = ["-lgbm"]

src/main.cpp containing only #include <gbm.h> and a gbm_format_get_name call:

Provisioning [xlings] deps (xim:mesa)
   Compiling nopkg v0.1.0 (.)
     Running `target/.../bin/nopkg`
XR24 | GBM_BACKENDS_PATH=<registry>/subos/default/usr/lib/gbm

Compile, link, run and environment all close — the environment via the pre-existing compute_subos_env path, now that there is something in the SubOS for it to read. The GBM_BACKENDS_PATH declaration itself comes from openxlings/xim-pkgindex#713; before that PR the same run leaves it unset while everything else works.

Tested with bare (xim:mesa) and pinned (xim:mesa@25.0.7.2) spellings.

Tests

mcpp test — 96 passed, 0 failed (1 skipped: the non-Linux boundary, as always on a Linux runner). The SubOS-env axis keeps its existing coverage in tests/e2e/200_subos_env_reaches_program.sh.

Design note: mcpp-index .agents/docs/2026-08-30-gbm-cross-repo-closed-loop-plan.md §9 and §12 — §12.1 records the three measurements that retired B3.