Skip to content

host: move snapshot metadata to its own names #1345

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Pedro Henrique Penna (ppenna) merged 3 commits into from
Nov 8, 2026
Merged

host: move snapshot metadata to its own names #1345

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
75065ed
host: move snapshot metadata to its own names
Nov 7, 2026
b7f0db5
host: retain template clock parsing across the metadata move
Nov 7, 2026
1106886
host: preserve metadata parser parity and acyclic ownership
Nov 7, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 19 additions & 4 deletions nvx-rs/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -124,6 +124,7 @@ changes only when the module's purpose does.
| [`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::config`](#nvxhostconfig) | `VmConfig`, a VM's configuration as one value, and `CaptureConfig`, what a capture adds and the identity of its snapshots, checked without reading the host |
| [`nvx::host::restore`](#nvxhostrestore) | The restore-ready listener, with native ownership transfer for a caller's own I/O |
| [`nvx::host::artifacts`](#nvxhostartifacts) | Locating the OpenVMM executable and the guest artifacts that a VM runs, and their runtime identity |
Expand All @@ -136,7 +137,7 @@ changes only when the module's purpose does.
| [`nvx::host::nvxs`](#nvxhostnvxs) | `HostConnection`: the host's role of the NVXS session over a platform transport |
| [`nvx::host::process`](#nvxhostprocess) | Verified references to OpenVMM processes, through which callers wait for them and end them |
| [`nvx::host::supervisor`](#nvxhostsupervisor) | The supervisor of a sandbox's VMM, beneath the CLI, `Instance`, and external orchestrators |
| [`nvx::host::template`](#nvxhosttemplate) | Templates, captures of a microVM from which clones are restored: their plans, manifests, keys, and store |
| [`nvx::host::template`](#nvxhosttemplate) | Legacy template capture and clone plans and store, with aliases of the snapshot metadata |
| [`nvx::host::seal`](#nvxhostseal) | `FileSeal`: what the host reports about an open file from its metadata alone, without reading it |
| [`nvx::host::session`, `platform`, `report`](#nvxhostsession-platform-report) | The authenticated control session, Linux and Windows primitives, and OpenVMM's outcome report |
| [`nvx::host::sandbox`](#nvxhostsandbox) | The launch profile of `nvx-rs sandbox`: its plans, live shares, option checks, bindings, and prepared launches |
Expand Down Expand Up @@ -466,6 +467,19 @@ 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.

### `nvx::host::snapshot`

`SnapshotKey` and `SnapshotManifest` own the compatibility key and strict
OpenVMM manifest reader. `SnapshotManifest::time` exposes the capture's
`TimeContract`, whose `eligibility` checks its restore window at a `HostTime`;
`HostTime::now` samples the host's clock and identities. The existing
`host::template` names remain aliases of these same types.

The key's canonical encoding and identity use the snapshot names and omit
`guest_build`. Version 1 changes in place: no snapshot outlives a deployment,
and no reader or migration of the prior encoding is supported. `CaptureClass`
still records the legacy capture inputs, including its guest build.

### `nvx::host::config`

`VmConfig`: the configuration of a VM as one value, its processors, its memory
Expand Down Expand Up @@ -849,8 +863,9 @@ top-level message. Neither silently changes the requested directory.

### `nvx::host::template`

The metadata of templates, captures of a microVM from which independent clones
are restored.
The legacy plans and store of templates, captures of a microVM from which
independent clones are restored. Their metadata names remain aliases of
[`host::snapshot`](#nvxhostsnapshot)'s types.

`TemplatePlan::new` lowers an adapter's `SandboxPlan` into the plan of a
template's capture, without I/O: the placeholder `distro`, which its
Expand Down Expand Up @@ -902,7 +917,7 @@ domain-separated SHA-256 digest is its identity, a `KeyIdentity`, which converts
to and from the `nvx::activation::Identity` by which a clone's lease and durable records
name its template's key, or a `ClassIdentity`; the
[conformance vectors](tests/vectors/README.md) of version 1,
`tests/vectors/template-key-v1.txt`, pin both encodings and identities. The
`tests/vectors/snapshot-key-v1.txt`, pin both encodings and identities. The
key's encoding, version 1, leaves the network policy out, since templates
capture their NIC under the complete deny-all policy, and has not been released,
so a template store that an earlier build created is not supported: delete it
Expand Down
114 changes: 113 additions & 1 deletion nvx-rs/public-api/linux.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2583,6 +2583,119 @@ field nvx::host::session::SessionError::Refused::0
variant nvx::host::session::SessionError::Reset
variant nvx::host::session::SessionError::TimedOut
fn nvx::host::session::connect
mod nvx::host::snapshot
struct nvx::host::snapshot::BlockGeometry
field nvx::host::snapshot::BlockGeometry::length
field nvx::host::snapshot::BlockGeometry::logical_block_size
field nvx::host::snapshot::BlockGeometry::physical_block_size
struct nvx::host::snapshot::CaptureClass
const nvx::host::snapshot::CaptureClass::VERSION
field nvx::host::snapshot::CaptureClass::boot_processors
method nvx::host::snapshot::CaptureClass::check
field nvx::host::snapshot::CaptureClass::cpu_profile
field nvx::host::snapshot::CaptureClass::distro
field nvx::host::snapshot::CaptureClass::guest_build
field nvx::host::snapshot::CaptureClass::hypervisor
method nvx::host::snapshot::CaptureClass::identity
field nvx::host::snapshot::CaptureClass::invariants
field nvx::host::snapshot::CaptureClass::memory
field nvx::host::snapshot::CaptureClass::memory_capacity
field nvx::host::snapshot::CaptureClass::network
field nvx::host::snapshot::CaptureClass::processors
field nvx::host::snapshot::CaptureClass::runtime
field nvx::host::snapshot::CaptureClass::scratch
method nvx::host::snapshot::CaptureClass::to_bytes
struct nvx::host::snapshot::ClassIdentity
method nvx::host::snapshot::ClassIdentity::as_bytes
method nvx::host::snapshot::ClassIdentity::from_bytes
struct nvx::host::snapshot::Downtime
field nvx::host::snapshot::Downtime::nanos
field nvx::host::snapshot::Downtime::source
field nvx::host::snapshot::Downtime::vm_time_nanos
enum nvx::host::snapshot::DowntimeSource
variant nvx::host::snapshot::DowntimeSource::HostMonotonic
variant nvx::host::snapshot::DowntimeSource::Utc
enum nvx::host::snapshot::Eligibility
variant nvx::host::snapshot::Eligibility::Early
field nvx::host::snapshot::Eligibility::Early::before_ns
field nvx::host::snapshot::Eligibility::Early::source
variant nvx::host::snapshot::Eligibility::Eligible
field nvx::host::snapshot::Eligibility::Eligible::0
variant nvx::host::snapshot::Eligibility::Expired
field nvx::host::snapshot::Eligibility::Expired::0
method nvx::host::snapshot::Eligibility::is_eligible
enum nvx::host::snapshot::HostClock
variant nvx::host::snapshot::HostClock::LinuxBoottime
variant nvx::host::snapshot::HostClock::WindowsInterruptTime
method nvx::host::snapshot::HostClock::as_str
struct nvx::host::snapshot::HostTime
field nvx::host::snapshot::HostTime::boot_id
field nvx::host::snapshot::HostTime::clock
field nvx::host::snapshot::HostTime::host_id
field nvx::host::snapshot::HostTime::monotonic_ns
method nvx::host::snapshot::HostTime::now
field nvx::host::snapshot::HostTime::utc_ns
struct nvx::host::snapshot::Invariants
const nvx::host::snapshot::Invariants::MAX_NAME_LEN
const nvx::host::snapshot::Invariants::MAX_SETTINGS
const nvx::host::snapshot::Invariants::MAX_VALUE_LEN
method nvx::host::snapshot::Invariants::get
method nvx::host::snapshot::Invariants::is_empty
method nvx::host::snapshot::Invariants::iter
method nvx::host::snapshot::Invariants::len
method nvx::host::snapshot::Invariants::new
method nvx::host::snapshot::Invariants::with
struct nvx::host::snapshot::KeyIdentity
method nvx::host::snapshot::KeyIdentity::as_bytes
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::SnapshotKey
const nvx::host::snapshot::SnapshotKey::MAX_LEN
const nvx::host::snapshot::SnapshotKey::VERSION
method nvx::host::snapshot::SnapshotKey::boot_processors
method nvx::host::snapshot::SnapshotKey::command_line
method nvx::host::snapshot::SnapshotKey::cpu_profile
method nvx::host::snapshot::SnapshotKey::distro
method nvx::host::snapshot::SnapshotKey::filesystem_tag
method nvx::host::snapshot::SnapshotKey::from_bytes
method nvx::host::snapshot::SnapshotKey::guest_network
method nvx::host::snapshot::SnapshotKey::has_network
method nvx::host::snapshot::SnapshotKey::hypervisor
method nvx::host::snapshot::SnapshotKey::identity
method nvx::host::snapshot::SnapshotKey::invariants
method nvx::host::snapshot::SnapshotKey::memory
method nvx::host::snapshot::SnapshotKey::memory_block_size
method nvx::host::snapshot::SnapshotKey::memory_capacity
method nvx::host::snapshot::SnapshotKey::new
method nvx::host::snapshot::SnapshotKey::processors
method nvx::host::snapshot::SnapshotKey::runtime
method nvx::host::snapshot::SnapshotKey::scratch
method nvx::host::snapshot::SnapshotKey::speaks_current_contracts
method nvx::host::snapshot::SnapshotKey::to_bytes
struct nvx::host::snapshot::SnapshotManifest
method nvx::host::snapshot::SnapshotManifest::created_at
method nvx::host::snapshot::SnapshotManifest::hypervisor
method nvx::host::snapshot::SnapshotManifest::memory_len
method nvx::host::snapshot::SnapshotManifest::openvmm_version
method nvx::host::snapshot::SnapshotManifest::parse
method nvx::host::snapshot::SnapshotManifest::read
method nvx::host::snapshot::SnapshotManifest::state_len
method nvx::host::snapshot::SnapshotManifest::time
struct nvx::host::snapshot::TimeContract
field nvx::host::snapshot::TimeContract::apic_frequency_hz
field nvx::host::snapshot::TimeContract::boot_id
field nvx::host::snapshot::TimeContract::capture_monotonic_ns
field nvx::host::snapshot::TimeContract::capture_tsc
field nvx::host::snapshot::TimeContract::capture_utc_ns
field nvx::host::snapshot::TimeContract::cut_to_anchor_ns
method nvx::host::snapshot::TimeContract::eligibility
field nvx::host::snapshot::TimeContract::host_clock
field nvx::host::snapshot::TimeContract::host_id
field nvx::host::snapshot::TimeContract::lineage
field nvx::host::snapshot::TimeContract::tsc_frequency_hz
field nvx::host::snapshot::TimeContract::tsc_tolerance_ppm
mod nvx::host::store
struct nvx::host::store::ArtifactIdentity
method nvx::host::store::ArtifactIdentity::as_str
Expand Down Expand Up @@ -3124,7 +3237,6 @@ method nvx::host::template::TemplateKey::cpu_profile
method nvx::host::template::TemplateKey::distro
method nvx::host::template::TemplateKey::filesystem_tag
method nvx::host::template::TemplateKey::from_bytes
method nvx::host::template::TemplateKey::guest_build
method nvx::host::template::TemplateKey::guest_network
method nvx::host::template::TemplateKey::has_network
method nvx::host::template::TemplateKey::hypervisor
Expand Down
114 changes: 113 additions & 1 deletion nvx-rs/public-api/windows.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1506,6 +1506,119 @@ field nvx::host::session::SessionError::Refused::0
variant nvx::host::session::SessionError::Reset
variant nvx::host::session::SessionError::TimedOut
fn nvx::host::session::connect
mod nvx::host::snapshot
struct nvx::host::snapshot::BlockGeometry
field nvx::host::snapshot::BlockGeometry::length
field nvx::host::snapshot::BlockGeometry::logical_block_size
field nvx::host::snapshot::BlockGeometry::physical_block_size
struct nvx::host::snapshot::CaptureClass
const nvx::host::snapshot::CaptureClass::VERSION
field nvx::host::snapshot::CaptureClass::boot_processors
method nvx::host::snapshot::CaptureClass::check
field nvx::host::snapshot::CaptureClass::cpu_profile
field nvx::host::snapshot::CaptureClass::distro
field nvx::host::snapshot::CaptureClass::guest_build
field nvx::host::snapshot::CaptureClass::hypervisor
method nvx::host::snapshot::CaptureClass::identity
field nvx::host::snapshot::CaptureClass::invariants
field nvx::host::snapshot::CaptureClass::memory
field nvx::host::snapshot::CaptureClass::memory_capacity
field nvx::host::snapshot::CaptureClass::network
field nvx::host::snapshot::CaptureClass::processors
field nvx::host::snapshot::CaptureClass::runtime
field nvx::host::snapshot::CaptureClass::scratch
method nvx::host::snapshot::CaptureClass::to_bytes
struct nvx::host::snapshot::ClassIdentity
method nvx::host::snapshot::ClassIdentity::as_bytes
method nvx::host::snapshot::ClassIdentity::from_bytes
struct nvx::host::snapshot::Downtime
field nvx::host::snapshot::Downtime::nanos
field nvx::host::snapshot::Downtime::source
field nvx::host::snapshot::Downtime::vm_time_nanos
enum nvx::host::snapshot::DowntimeSource
variant nvx::host::snapshot::DowntimeSource::HostMonotonic
variant nvx::host::snapshot::DowntimeSource::Utc
enum nvx::host::snapshot::Eligibility
variant nvx::host::snapshot::Eligibility::Early
field nvx::host::snapshot::Eligibility::Early::before_ns
field nvx::host::snapshot::Eligibility::Early::source
variant nvx::host::snapshot::Eligibility::Eligible
field nvx::host::snapshot::Eligibility::Eligible::0
variant nvx::host::snapshot::Eligibility::Expired
field nvx::host::snapshot::Eligibility::Expired::0
method nvx::host::snapshot::Eligibility::is_eligible
enum nvx::host::snapshot::HostClock
variant nvx::host::snapshot::HostClock::LinuxBoottime
variant nvx::host::snapshot::HostClock::WindowsInterruptTime
method nvx::host::snapshot::HostClock::as_str
struct nvx::host::snapshot::HostTime
field nvx::host::snapshot::HostTime::boot_id
field nvx::host::snapshot::HostTime::clock
field nvx::host::snapshot::HostTime::host_id
field nvx::host::snapshot::HostTime::monotonic_ns
method nvx::host::snapshot::HostTime::now
field nvx::host::snapshot::HostTime::utc_ns
struct nvx::host::snapshot::Invariants
const nvx::host::snapshot::Invariants::MAX_NAME_LEN
const nvx::host::snapshot::Invariants::MAX_SETTINGS
const nvx::host::snapshot::Invariants::MAX_VALUE_LEN
method nvx::host::snapshot::Invariants::get
method nvx::host::snapshot::Invariants::is_empty
method nvx::host::snapshot::Invariants::iter
method nvx::host::snapshot::Invariants::len
method nvx::host::snapshot::Invariants::new
method nvx::host::snapshot::Invariants::with
struct nvx::host::snapshot::KeyIdentity
method nvx::host::snapshot::KeyIdentity::as_bytes
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::SnapshotKey
const nvx::host::snapshot::SnapshotKey::MAX_LEN
const nvx::host::snapshot::SnapshotKey::VERSION
method nvx::host::snapshot::SnapshotKey::boot_processors
method nvx::host::snapshot::SnapshotKey::command_line
method nvx::host::snapshot::SnapshotKey::cpu_profile
method nvx::host::snapshot::SnapshotKey::distro
method nvx::host::snapshot::SnapshotKey::filesystem_tag
method nvx::host::snapshot::SnapshotKey::from_bytes
method nvx::host::snapshot::SnapshotKey::guest_network
method nvx::host::snapshot::SnapshotKey::has_network
method nvx::host::snapshot::SnapshotKey::hypervisor
method nvx::host::snapshot::SnapshotKey::identity
method nvx::host::snapshot::SnapshotKey::invariants
method nvx::host::snapshot::SnapshotKey::memory
method nvx::host::snapshot::SnapshotKey::memory_block_size
method nvx::host::snapshot::SnapshotKey::memory_capacity
method nvx::host::snapshot::SnapshotKey::new
method nvx::host::snapshot::SnapshotKey::processors
method nvx::host::snapshot::SnapshotKey::runtime
method nvx::host::snapshot::SnapshotKey::scratch
method nvx::host::snapshot::SnapshotKey::speaks_current_contracts
method nvx::host::snapshot::SnapshotKey::to_bytes
struct nvx::host::snapshot::SnapshotManifest
method nvx::host::snapshot::SnapshotManifest::created_at
method nvx::host::snapshot::SnapshotManifest::hypervisor
method nvx::host::snapshot::SnapshotManifest::memory_len
method nvx::host::snapshot::SnapshotManifest::openvmm_version
method nvx::host::snapshot::SnapshotManifest::parse
method nvx::host::snapshot::SnapshotManifest::read
method nvx::host::snapshot::SnapshotManifest::state_len
method nvx::host::snapshot::SnapshotManifest::time
struct nvx::host::snapshot::TimeContract
field nvx::host::snapshot::TimeContract::apic_frequency_hz
field nvx::host::snapshot::TimeContract::boot_id
field nvx::host::snapshot::TimeContract::capture_monotonic_ns
field nvx::host::snapshot::TimeContract::capture_tsc
field nvx::host::snapshot::TimeContract::capture_utc_ns
field nvx::host::snapshot::TimeContract::cut_to_anchor_ns
method nvx::host::snapshot::TimeContract::eligibility
field nvx::host::snapshot::TimeContract::host_clock
field nvx::host::snapshot::TimeContract::host_id
field nvx::host::snapshot::TimeContract::lineage
field nvx::host::snapshot::TimeContract::tsc_frequency_hz
field nvx::host::snapshot::TimeContract::tsc_tolerance_ppm
mod nvx::host::store
struct nvx::host::store::ArtifactIdentity
method nvx::host::store::ArtifactIdentity::as_str
Expand Down Expand Up @@ -2046,7 +2159,6 @@ method nvx::host::template::TemplateKey::cpu_profile
method nvx::host::template::TemplateKey::distro
method nvx::host::template::TemplateKey::filesystem_tag
method nvx::host::template::TemplateKey::from_bytes
method nvx::host::template::TemplateKey::guest_build
method nvx::host::template::TemplateKey::guest_network
method nvx::host::template::TemplateKey::has_network
method nvx::host::template::TemplateKey::hypervisor
Expand Down
14 changes: 7 additions & 7 deletions nvx-rs/src/host/mod.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,13 +29,12 @@
//! with a bounded forced step on request, and reattaches to it after the orchestrator restarts
//! within the same host boot. The private `spawn` module, whose items `supervisor` re-exports,
//! starts the VMM detached, with no other descriptor or handle of the caller's.
//! - [`template`] holds the metadata of templates, captures from which clones are restored: the
//! compatibility key of a template, [`TemplateKey`](template::TemplateKey), which it derives
//! from the [`CaptureClass`](template::CaptureClass) of the capture and the capture's
//! [`TemplateManifest`](template::TemplateManifest), the [`Store`](template::Store) of the
//! generations of templates that a host published, which leases them to clones, and the plan
//! of a template's capture, [`TemplatePlan`](template::TemplatePlan), which it lowers from an
//! adapter's plan.
//! - [`snapshot`] holds the compatibility key, [`SnapshotKey`](snapshot::SnapshotKey), derived
//! from a [`CaptureClass`](snapshot::CaptureClass) and [`SnapshotManifest`](snapshot::SnapshotManifest),
//! the strict manifest reader, and the capture's public time and eligibility information.
//! - [`template`] retains the legacy capture and clone plans, the [`Store`](template::Store) of
//! published generations and their leases, and aliases of the snapshot metadata. Its
//! [`TemplatePlan`](template::TemplatePlan) lowers an adapter's plan for a capture.
//! - [`session`] speaks NVX's control protocol, `NVXC`, over [`nvxs`], which runs the host's role
//! of the NVXS session for it and for any other application protocol, over a platform
//! transport. [`platform`] holds the primitives of Linux and Windows hosts. Other hosts compile
Expand Down Expand Up @@ -92,6 +91,7 @@ pub mod runtime;
pub mod sandbox;
pub mod seal;
pub mod session;
pub mod snapshot;
mod spawn;
pub mod store;
pub mod supervisor;
Expand Down
Loading
Loading