[Enrique Saurez (esaurez)]

A guest root's assembly took an EROFS image and an ext4 scratch, and mounted the overlay with one fixed option set. This PR lets the caller of nvx::guest::root::assemble name what it assembles, with typed inputs, and the assembly probes nothing:

• The image: Image::Erofs, with the UUID that the caller expects, if any. The enum is non-exhaustive, for the GPT format that the next PR of A3.3 adds.
• The upper: Upper::Scratch, a whole-device ext4 scratch, mounted rw,nosuid,nodev, with the caller's Journal policy, which allows or forbids a journal, checked in the superblock's feature flags before the scratch is mounted; or Upper::Tmpfs, a tmpfs at the kernel's default size, mounted nosuid,nodev, for a VM without a scratch device. The upper and work directories are separate directories of the upper, created 0755 whatever the umask.
• The overlay mode: OverlayMode::TrustedLowers, the default, mounts the overlay with metacopy=on,xino=on, and OverlayMode::UntrustedLowers, for lowers that may carry untrusted overlay xattrs, with metacopy=off,redirect_dir=nofollow. Each mode has one option set: when the kernel refuses it, the assembly fails, with no fallback to another. The merged root is mounted nosuid,nodev.

The kernel has fallbacks of its own, which don't fail the mount: it mounts an overlay read-only when it can't create the work directory, and turns metacopy off and redirect_dir to nofollow when the upper can't hold the overlay's xattrs. So once the overlay is mounted, the assembly reads its options in the kernel's mount table, where an option at its module default doesn't show, and refuses and unmounts an overlay that isn't writable or lacks its mode's options.

The assembly checks everything else before it mounts anything:

• each device's access mode, from sysfs, against its role's, read-only for the image and writable for the scratch, before it flushes the device, so that a device in the wrong role is refused;
• each device's expected size, the image's UUID, and the scratch's journal;
• the runtime directory, which a mount that a failed teardown left refuses, at the image's, the root's, or the aggregate share's mount point, or at either upper's, whichever upper the new root mounts;
• the length of the overlay's options. mount(2) passes a file system one page of options, and the kernel cuts longer ones short, which would drop the last lower directories or the mode's options. The assembly refuses options longer than MOUNT_OPTIONS_LIMIT, 4,095 bytes, instead.

The Root reports what it mounted: its Lower layers, its UpperKind, and its OverlayMode, whose options() are the overlay's. Its teardown unmounts the live shares and mappings in reverse order, the overlay, the layers from the top down, and then the upper, and reports every unmount that fails.

The runtime adapter's layered VMs (tests/runtime-adapter) now assemble the EROFS image over a scratch or a tmpfs, in the overlay mode and with the journal policy that the host names, and probe copy-up, the rename of a lower directory, a full upper, and the guest's disks. The map probe finds the targets that it creates on the overlay in the upper of either kind.

Part of #621. Refs #622 and #535.

Validation

On this branch's head, locally:

• python scripts/nvx.py verify.
• nvx-rs, on Linux with NVX_BUNDLE=skip: cargo clippy --locked --all-targets --all-features -- -D warnings, cargo clippy --locked --lib --no-default-features -- -D warnings, cargo test --locked --all-features (1,103 passed), cargo test --locked (508 passed), cargo doc --locked --no-deps --all-features with RUSTDOCFLAGS=-D warnings, cargo +1.89 check --locked --all-targets --all-features, and check-nvx-rs's macOS check and bundling test; cargo fmt --all --check on Windows.
• Guest binaries: check-guest-binaries, build-guest-binaries and test-guest-binaries (34 passed). The stripped guest binaries are byte-identical before and after this change, and so is the Alpine initramfs: 8,222,829 bytes, 19,707,392 uncompressed.
• tests/runtime-adapter: Clippy, build, tests and the MSRV check in the protocol-only, host and guest configurations on Linux, the guest configuration's MSRV check for the GNU target, and fmt, Clippy, build, tests and the MSRV check in the protocol-only and host configurations on Windows.
• Real VMs, the adapter's ignored tests, cargo test --locked --features host --test vm_layered --test vm_restart -- --ignored: 12 layered scenarios, this PR's 10 and the 2 of the root's mappings, and 2 restart tests pass on MSHV and WHP. They show, per mode: TrustedLowers mounts with redirect_dir=on,uuid=on,xino=on,metacopy=on in effect, copies up a file's metadata alone, and renames a lower directory; UntrustedLowers shows only uuid=on, copies up the data too, and refuses the rename with EXDEV. The tmpfs upper is rw,nosuid,nodev with mode=755 and no size=, with no scratch disk in the guest; a full scratch and a full tmpfs, half of the guest's memory, refuse writes with ENOSPC until the file that filled them is gone.
• NVX's own layered scenarios still pass, unchanged: python scripts/nvx.py test-microvm --backend <mshv|whp> --processors 1 with managed-exec-config, sandbox-lifecycle, sandbox-blocks, scratch-snapshot, snapshot-tiers and managed-lifecycle, on MSHV and WHP, with the Alpine initramfs built from this branch.

MSHV ran as root and with --cpu-profile host, since its test host can't present a built-in CPU profile. KVM and the full backend matrix are left to CI.

[Copilot]

🔵 Needs a closer look

Privileged mount assembly and kernel-dependent validation require human review, with an unresolved stale-mount check when switching upper kinds.

1 open issue

• Check both upper mounts during occupancy validation · New

What changed in this PR

Extends NVX’s guest root library with typed image, upper, and overlay-mode inputs, advancing the shared layered sandbox runtime in #621.

Changes:

• Supports EROFS roots over ext4 scratch or tmpfs, with caller-selected journal and overlay policies.
• Validates device roles, mount-option length, and effective overlay options; exposes mounted layers and upper kind.
• Extends the runtime adapter’s configuration, probes, documentation, and tests for the new combinations.

File	Description
tests/​runtime-adapter/​tests/​vm_layered.rs	Adds upper/mode combinations and full-upper scenarios.
tests/​runtime-adapter/​tests/​layered_launch.rs	Tests rejection of invalid policy options.
tests/​runtime-adapter/​tests/​guest_session.rs	Tests RAM assembly and conflicting configuration.
tests/​runtime-adapter/​src/​worker/​probes.rs	Adds copy-up, rename, capacity, and disk probes.
tests/​runtime-adapter/​src/​worker.rs	Passes typed root settings to guest assembly.
tests/​runtime-adapter/​src/​root.rs	Encodes and validates overlay and journal policies.
tests/​runtime-adapter/​src/​bin/​runtime-adapter-host.rs	Adds overlay-mode and journal-policy arguments.
tests/​runtime-adapter/​README.md	Documents configuration, probes, and scenarios.
tests/​runtime-adapter/​Cargo.toml	Enables filesystem calls for capacity probes.
nvx-rs/​src/​guest/​root/​tests.rs	Covers upper modes, validation, and teardown failures.
nvx-rs/​src/​guest/​root/​kernel.rs	Reads effective mount options and extends the fake kernel.
nvx-rs/​src/​guest/​root/​block.rs	Checks device access and ext4 journal flags.
nvx-rs/​src/​guest/​root.rs	Implements typed assembly, tmpfs uppers, and overlay validation.
nvx-rs/​README.md	Updates the guest root API description.

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

Privileged mount lifecycle changes and security-sensitive, kernel-dependent overlay checks warrant human review alongside the remaining backend CI results.

No open issues 🎉

1 resolved since last review

• Check both upper mounts during occupancy validation

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

Privileged mount-policy enforcement and teardown changes warrant human sign-off with the KVM and full backend CI results.

No open issues 🎉

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

Security-sensitive overlay enforcement and privileged mount lifecycle changes warrant human review and confirmation of the full backend CI results.

No open issues 🎉

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

Security-sensitive mount lifecycle changes and kernel-dependent overlay validation warrant human review alongside the full backend CI results.

No open issues 🎉

_{Review effort: Balanced}