host: prepare checked cold VM launches

nvx-rs/README.md

@@ -124,8 +124,8 @@ changes only when the module's purpose does.
 | [`nvx::Hypervisor`](#nvxhypervisor) | KVM, MSHV, or WHP, with its serde form behind the `serde` feature |
 | [`nvx::exec`](#nvxexec) | The execution engine: the streams, credit, and outcome of an execution's two sides, without I/O, for any framing |
 | [`nvx::host::runtime`](#nvxhostruntime) | `Runtime`: what every launch shares, the runtime's files and their identity, the hypervisor and its probe, and the launch options |
-| [`nvx::host::vm`](#nvxhostvm) | The directory of a VM, private to the current user, with the fixed names of the files and endpoints of its launches |
-| [`nvx::host::snapshot`](#nvxhostsnapshot) | Snapshot compatibility keys, strict manifests, and restore-time eligibility |
+| [`nvx::host::vm`](#nvxhostvm) | A private VM directory and its fixed outputs, and an inspectable cold launch with its opened log and control credential |
+| [`nvx::host::snapshot`](#nvxhostsnapshot) | Snapshot compatibility keys, strict manifests, restore-time eligibility, and the opaque input of a future VM restore |
 | [`nvx::host::config`](#nvxhostconfig) | `VmConfig` and `CaptureConfig`: pure configuration, cold-boot kernel/OpenVMM arguments, portable length checks, and capture identity |
 | [`nvx::host::restore`](#nvxhostrestore) | A caller-driven restore to Ready without I/O or a clock, and its peer-verified restore-ready listener |
 | [`nvx::host::artifacts`](#nvxhostartifacts) | Locating the OpenVMM executable and the guest artifacts that a VM runs, and their runtime identity |
@@ -485,6 +485,32 @@ credential that the host presents at a VM's control endpoint: `as_bytes`
 returns it, and its `Debug` form hides it. The library never writes it to a
 file; a caller that reconnects after a restart keeps it.
 
+`vm::create(&runtime, &config, None, &dir)` creates an inspectable cold
+`Prepared` launch without starting a process or binding a listener. It requires
+`config.boot`, refuses a snapshot input, rechecks the directory's privacy, and
+creates a new private log. Existing log, outcome and Linux endpoint entries
+are refused rather than replaced. Only the log is created before a spawn;
+OpenVMM creates the remaining outputs when it runs. A failed preparation
+closes and removes only its new log, preserving all pre-existing entries and
+caller-owned inputs, and reports a cleanup failure with the original error.
+
+On Linux, the generated control and boot-console socket names must be valid
+Unicode and shorter than 108 bytes both as supplied and with the directory's
+ancestor links resolved. Supplied names must hold no comma or equals sign,
+which OpenVMM's listener options cannot represent literally. Creation refuses
+these names before creating any output, including the log.
+
+`Prepared::capability()` and `outputs()` return what the caller may journal
+before a spawn. `log()` returns the same opened log, without reopening its
+path. `inherit(file)` moves an already opened resource into the preparation's
+inheritance allowlist and keeps it open. `arguments()` returns the whole
+configuration's OpenVMM arguments. Creation checks the complete Windows
+command line with the actual runtime and VM output paths and no reserve,
+including quoting and the terminating NUL, on every host. Callers keep the
+directory and runtime inputs stable through creation and a later spawn.
+Dropping a successful preparation closes its resources but leaves its output
+paths owned by the caller.
+
 ### `nvx::host::snapshot`
 
 `SnapshotKey` and `SnapshotManifest` own the compatibility key and strict
@@ -498,6 +524,10 @@ The key's canonical encoding and identity use the snapshot names and omit
 and no reader or migration of the prior encoding is supported. `CaptureClass`
 still records the legacy capture inputs, including its guest build.
 
+`Snapshot` is an opaque input of a future restore. `vm::create` currently
+refuses `Some(snapshot)` with `ErrorKind::Unsupported`; only cold boots are
+supported.
+
 ### `nvx::host::config`
 
 `VmConfig`: the configuration of a VM as one value, its processors, its memory
@@ -560,9 +590,9 @@ entries. The table's `HostMap` and its wire codecs are accessible through
 command-line budget, including the terminating NUL. The legacy launch checks
 continue to use it.
 
-`VmConfig::openvmm_arguments` renders a cold boot's whole OpenVMM argument list
-from `Runtime` and `VmConfig`. Its borrowed control endpoint, report path, and
-optional boot-console endpoint are already chosen output names, not additional
+The internal whole-config renderer used by `vm::create` renders a cold boot's
+OpenVMM arguments from `Runtime` and `VmConfig`. Its borrowed control endpoint,
+report path, and optional boot-console endpoint are already chosen output names, not additional
 launch settings. It opens no path, allocates no endpoint, and starts no process.
 It renders processors, memory without narrowing it, kernel and initramfs paths,
 the kernel command line, layered-root block devices by path, network and export
@@ -572,8 +602,8 @@ its supplied console name; a disconnected attachment retains the device and
 discards its output. Listener names are nonempty and contain no NUL, comma, or
 equals sign, which OpenVMM's serial options cannot hold literally.
 The renderer emits neither `--microvm-lifecycle` nor
-`--microvm-workload-identity`. The whole-config entry point is temporarily
-public: SL2.8 makes it internal when `host::vm::create` calls it.
+`--microvm-workload-identity`. Callers inspect the complete arguments through
+`Prepared::arguments()`.
 
 Both argument entry points refuse a `Boot` with a capture as `Unsupported`
 rather than silently omit its devices and resource capacities.

nvx-rs/public-api/linux.txt

@@ -1810,7 +1810,6 @@ method nvx::host::config::VmConfig::kernel_command_line
 method nvx::host::config::VmConfig::mapping_table
 field nvx::host::config::VmConfig::memory_mib
 field nvx::host::config::VmConfig::network
-method nvx::host::config::VmConfig::openvmm_arguments
 field nvx::host::config::VmConfig::processors
 field nvx::host::config::VmConfig::root
 field nvx::host::config::VmConfig::view
@@ -2706,6 +2705,7 @@ method nvx::host::snapshot::KeyIdentity::from_bytes
 const nvx::host::snapshot::MANIFEST_NAME
 const nvx::host::snapshot::MAX_DOWNTIME_NS
 const nvx::host::snapshot::MAX_MANIFEST_LEN
+struct nvx::host::snapshot::Snapshot
 struct nvx::host::snapshot::SnapshotKey
 const nvx::host::snapshot::SnapshotKey::MAX_LEN
 const nvx::host::snapshot::SnapshotKey::VERSION
@@ -3353,6 +3353,12 @@ fn nvx::host::template::status_evidence
 mod nvx::host::vm
 struct nvx::host::vm::Capability
 method nvx::host::vm::Capability::as_bytes
+struct nvx::host::vm::Prepared
+method nvx::host::vm::Prepared::arguments
+method nvx::host::vm::Prepared::capability
+method nvx::host::vm::Prepared::inherit
+method nvx::host::vm::Prepared::log
+method nvx::host::vm::Prepared::outputs
 struct nvx::host::vm::VmDir
 method nvx::host::vm::VmDir::open
 method nvx::host::vm::VmDir::path
@@ -3361,6 +3367,7 @@ field nvx::host::vm::VmOutputs::console
 field nvx::host::vm::VmOutputs::endpoint
 field nvx::host::vm::VmOutputs::log
 field nvx::host::vm::VmOutputs::outcome
+fn nvx::host::vm::create
 fn nvx::host::vm::create_private_dir
 mod nvx::net
 struct nvx::net::Cidr

nvx-rs/public-api/windows.txt

@@ -733,7 +733,6 @@ method nvx::host::config::VmConfig::kernel_command_line
 method nvx::host::config::VmConfig::mapping_table
 field nvx::host::config::VmConfig::memory_mib
 field nvx::host::config::VmConfig::network
-method nvx::host::config::VmConfig::openvmm_arguments
 field nvx::host::config::VmConfig::processors
 field nvx::host::config::VmConfig::root
 field nvx::host::config::VmConfig::view
@@ -1629,6 +1628,7 @@ method nvx::host::snapshot::KeyIdentity::from_bytes
 const nvx::host::snapshot::MANIFEST_NAME
 const nvx::host::snapshot::MAX_DOWNTIME_NS
 const nvx::host::snapshot::MAX_MANIFEST_LEN
+struct nvx::host::snapshot::Snapshot
 struct nvx::host::snapshot::SnapshotKey
 const nvx::host::snapshot::SnapshotKey::MAX_LEN
 const nvx::host::snapshot::SnapshotKey::VERSION
@@ -2275,6 +2275,12 @@ fn nvx::host::template::status_evidence
 mod nvx::host::vm
 struct nvx::host::vm::Capability
 method nvx::host::vm::Capability::as_bytes
+struct nvx::host::vm::Prepared
+method nvx::host::vm::Prepared::arguments
+method nvx::host::vm::Prepared::capability
+method nvx::host::vm::Prepared::inherit
+method nvx::host::vm::Prepared::log
+method nvx::host::vm::Prepared::outputs
 struct nvx::host::vm::VmDir
 method nvx::host::vm::VmDir::open
 method nvx::host::vm::VmDir::path
@@ -2283,6 +2289,7 @@ field nvx::host::vm::VmOutputs::console
 field nvx::host::vm::VmOutputs::endpoint
 field nvx::host::vm::VmOutputs::log
 field nvx::host::vm::VmOutputs::outcome
+fn nvx::host::vm::create
 fn nvx::host::vm::create_private_dir
 mod nvx::net
 struct nvx::net::Cidr

nvx-rs/src/host/config/mod.rs

@@ -3,8 +3,9 @@
 //! of it, its [`NetworkConfig`], the host paths that it exports, its [`ConsoleAttachment`], and
 //! what only its cold boot takes, a [`Boot`], with what a capture of the VM adds, a
 //! [`CaptureConfig`], whose [`CaptureIdentity`] names the capture's snapshots.
-//! [`VmConfig::openvmm_arguments`] renders a whole cold launch from that configuration and a
-//! [`Runtime`], with caller-supplied output names, without opening paths or allocating endpoints.
+//! An internal renderer builds a whole cold launch for [`crate::host::vm::create`],
+//! from that configuration and a
+//! [`Runtime`], without opening runtime paths or allocating endpoints.
 
 use std::collections::BTreeMap;
 use std::ffi::{OsStr, OsString};
@@ -447,8 +448,7 @@ impl VmConfig {
     /// contain neither commas nor equals signs, which delimit OpenVMM's serial options.
     /// The caller runs `runtime.openvmm` with these arguments.
     ///
-    /// This whole-config entry point is temporarily public. SL2.8 makes it internal when
-    /// `host::vm::create` calls it. Individual device lowerings stay internal. Neither managed
+    /// [`crate::host::vm::create`] calls this internal whole-config renderer. Neither managed
     /// lifecycle nor workload-identity flags are rendered; the caller owns its guest tokens.
     /// `runtime.windows_breakaway` is process-launch behavior, not an OpenVMM argument.
     ///
@@ -461,7 +461,7 @@ impl VmConfig {
     /// kernel text with double quotes or the standalone `--` delimiter, or a complete command line
     /// beyond the Windows limit.
     /// The complete limit check runs on every host, without a reserve.
-    pub fn openvmm_arguments(
+    pub(crate) fn openvmm_arguments(
         &self,
         runtime: &Runtime,
         endpoint: &str,
@@ -553,8 +553,8 @@ impl VmConfig {
     ///
     /// Like legacy adapter planning, the reserve foresees runtime-file and output names of up to
     /// 260 code units each, Windows' `MAX_PATH`. It does not certify arbitrary runtime paths or
-    /// CPU-profile names: [`openvmm_arguments`](Self::openvmm_arguments) checks the complete
-    /// command line with the actual runtime and output names, without a reserve.
+    /// CPU-profile names: [`crate::host::vm::create`] checks the complete command line with the
+    /// actual runtime and output names, without a reserve.
     /// A listener's backend prefix is counted here; its endpoint name stays in the reserve.
     ///
     /// Fails with [`ErrorKind::Unsupported`](crate::ErrorKind::Unsupported) for a refused

nvx-rs/src/host/mod.rs

@@ -50,7 +50,9 @@
 //!   [`PreparedLaunch`](sandbox::PreparedLaunch) hands the VMM the files that those checks
 //!   opened, which it inherits through the [`supervisor`]'s allowlist.
 //! - [`vm`] holds a caller-owned VM directory, private to the current user, the fixed names of
-//!   its files and endpoints, and its control credential, which the library never writes.
+//!   its files and endpoints, and a checked cold [`Prepared`](vm::Prepared) launch with its
+//!   opened log and control credential, which the library never writes. The opaque
+//!   [`Snapshot`](snapshot::Snapshot) input of a future restore is refused by cold creation.
 //! - [`restore`] orders caller-driven activation to Ready without I/O or a clock, and listens for
 //!   OpenVMM's restore-ready event from the held VM process.
 //! - `cli` (feature `cli`) is the `nvx-rs` command-line interface, which runs microVMs and

nvx-rs/src/host/snapshot.rs

@@ -1,4 +1,4 @@
-//! Snapshot metadata: compatibility keys, strict manifests and restore-time eligibility.
+//! Snapshot metadata and the opaque input of a future VM restore.
 //!
 //! [`SnapshotKey`] derives a compatibility key from a capture's class and manifest.
 //! [`SnapshotManifest::read`] reads the manifest that OpenVMM wrote, and
@@ -36,3 +36,10 @@ pub use self::key::{CaptureClass, ClassIdentity, Invariants, KeyIdentity, Snapsh
 pub use self::manifest::{
     BlockGeometry, HostClock, MANIFEST_NAME, MAX_MANIFEST_LEN, SnapshotManifest, TimeContract,
 };
+
+/// An opaque snapshot input. Creating a VM from a snapshot is not supported yet.
+#[derive(Debug)]
+pub struct Snapshot {
+    /// Reserved for snapshot metadata.
+    pub(crate) _private: (),
+}