[Enrique Saurez (esaurez)]

Part of #822: PR 1 of 11, staging and the adapter plan.

What changed

• runtime-adapter-host stage STORE --distro FORMAT:PATH --distro-identity UUID [--upper scratch:PATH] verifies the image with DistroBinding::verify, which hashes it only when a manifest is beside it, and checks the binding from metadata as a launch does. It binds the scratch image with ScratchBinding::bind, and records both bindings, with the absolute paths at which it staged them, in runtime-adapter-staged.json in the sandbox's store. Staging is where hashing belongs: a launch never hashes. Staging also refuses images that no launch could attach, as the plan checks them.
• The record of the staged images, Staged and StagedFile, has a module of its own, staged, and its tests are in tests/staged_images.rs.
• A layered launch plans with SandboxPlan::adapter instead of SandboxPlan::new(..., SandboxSettings::default()), so no workload identity, entrypoint, hostname, or limit reaches OpenVMM or the kernel command line. The launch passes nvx_sandbox=1 as its own token, so that NVX's /init still hands the VM to the init agent, which the guest agent replaces.
• The layered launch drops --microvm-lifecycle managed: OpenVMM only checks its arguments and labels the outcome report with it, and only NVX's init agent reads its token. Blockless launches keep it.
• --distro-identity is required with --distro, since a binding names the identity, and LayeredLaunch::new takes the image's format and a Uuid.
• The launch record gains bindings: the staged bindings of the launch's image and scratch image, found by path, each null when the store stages none. The record stays at format 1. Nothing reads a launch record that another build wrote, so the adapter keeps no backward compatibility. The next PR of runtime adapter: run cold sandboxes end to end on KVM, MSHV and WHP #822 checks the bindings before spawn and requires them.
• The adapter's README and module docs describe staging, the adapter's plan, and the record.

Validation

Rebased onto dev at 50577c9, after #830, without conflicts; git range-diff shows the three commits unchanged. At 2168525, on Windows (AMD EPYC 7763 VM), as CI's actions run them:

• scripts/nvx.py verify.
• nvx-rs: rustfmt; Clippy with -D warnings for all features, and for the library without default features; tests with all features, with the defaults, and of the library without default features; artifact bundling; rustdoc with -D warnings; and the 1.89 check. The two CLI tests that failed on dev since nvx-rs: retire the egress policy fixture and read policies as strict JSON #828, egress::egress_compile_prints_the_library_lowering and validation::validation_errors_exit_1_before_any_side_effect, pass since nvx-rs: retire the golden CLI scenarios #830.
• The runtime adapter's protocol-only and host-only configurations: rustfmt, Clippy, build, tests, and the 1.89 check; and Clippy with -D warnings of its protocol-only, host-only, and guest-only configurations for x86_64-unknown-linux-gnu.
• scripts/check_markdown_links.py.
• VM scenarios on WHP, with the guest artifacts, OpenVMM, and musl guest agent that CI built at 2d3497a, whose OpenVMM pin and guest inputs this head keeps: vm_layered (22 of 22) and vm_restart (2 of 2).

At 2d3497a, the same commits on fcc7199, these also passed: on Linux, nvx-rs's macOS check and guest binaries, aci_edge_sandboxes and its macOS check, and the runtime adapter's guest-only x86_64-unknown-linux-musl configuration; and vm_layered and vm_restart on WHP (Core i9-12900K) and on MSHV (Genoa VM, --cpu-profile host, as root), with the guest artifacts and OpenVMM of v0.1.0-dev.3e80c7c74520. KVM and MSHV at this head, and its Linux-only gates, are left to CI.

[Copilot]

🔵 Needs a closer look

Layered VM boot arguments change, and validation on KVM, MSHV, and WHP remains pending.

No open issues 🎉

What changed in this PR

This PR adds image staging and adapter-specific launch planning to the in-repository runtime adapter, completing the first step of #822. Checked image handoff before VM spawn remains deferred to the next PR.

Changes:

• Adds a stage command to verify distro images, bind optional scratch images, and persist their bindings.
• Switches layered launches to SandboxPlan::adapter, requires image identity, and removes managed-lifecycle arguments while preserving the init-agent handoff token.
• Updates launch records to format 2 with staged bindings, with corresponding tests and documentation.

File	Description
tests/​runtime-adapter/​tests/​vm_layered.rs	Updates VM record assertions for adapter plans and format 2.
tests/​runtime-adapter/​tests/​layered_launch.rs	Tests staging, bindings, launch arguments, records, and CLI validation.
tests/​runtime-adapter/​src/​lib.rs	Updates module documentation for staging and adapter planning.
tests/​runtime-adapter/​src/​layered.rs	Implements staged bindings, adapter plans, and revised launch records.
tests/​runtime-adapter/​src/​bin/​runtime-adapter-host.rs	Adds staging commands and loads staged bindings during launch.
tests/​runtime-adapter/​README.md	Documents staging, launch behavior, record formats, and tests.

_{Review effort: Balanced}

[Copilot]

🟡 Changes recommended

Launch records still declare format 1 despite the required migration to format 2 for the binding-bearing schema.

1 open issue

• Bump launch record format to 2 for bindings · New

_{Review effort: Balanced}

[Copilot]

🟢 Approval recommended

No blocking issues remain in the scoped staging and adapter-plan changes, and the updated tests cover their intended behavior.

No open issues 🎉

1 resolved since last review

• Bump launch record format to 2 for bindings

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

The layered boot contract changes across three hypervisors, and compatibility with the pinned OpenVMM revision remains unverified.

No open issues 🎉

_{Review effort: Balanced}