feat(host): add namespaced snapshot metadata

Signed-off-by: Ludvig Liljenberg <4257730+ludfjig@users.noreply.github.com>

Author: ludfjig

CHANGELOG.md

@@ -5,6 +5,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 ## [Prerelease] - Unreleased
 
 ### Added
+* Namespaced application metadata on immutable snapshots.
 * Per-direction virtqueue configuration through `SandboxConfiguration` and
   `SandboxBuilder`, with allocations included in scratch sizing.
 * Shared virtqueue framing with a 12-byte `MsgHeader` and external byte values.

docs/snapshot-oci-format.md

@@ -35,8 +35,8 @@ Four blob kinds per tag:
 * **config** (`application/vnd.hyperlight.snapshot.config.v3+json`). The
   snapshot descriptor: arch, hypervisor, CPU vendor, ABI version,
   resume address and captured registers, memory and transport layout,
-  registered host functions, and snapshot generation counter. Loaded
-  eagerly and fully parsed.
+  registered host functions, snapshot generation counter, and namespaced
+  application metadata. Loaded eagerly and fully parsed.
 * **layer / memory** (`application/vnd.hyperlight.snapshot.memory.v1`).
   The raw guest memory image, exactly `memory_size` bytes. mmap'd on
   restore.
@@ -51,6 +51,18 @@ The runtime queue protocol and canonical checkpoint are described in
 Blob filenames are the sha256 of the blob bytes, so identical blobs
 across tags are stored once.
 
+## Application metadata
+
+`Snapshot::with_metadata` creates a snapshot that shares the source snapshot's
+sandbox state and stores a serializable value under an application-owned
+namespace. `Snapshot::metadata` deserializes the value for that namespace.
+The source snapshot remains unchanged.
+
+Metadata is stored in the config blob as a JSON object with namespaces as
+keys. Snapshots without metadata omit the field. The loader treats a missing
+field as an empty map, so snapshots written before metadata support remain
+loadable. Metadata counts toward the config blob size limit.
+
 ## Transport framing
 
 The transport layer is at most 2 MiB. Integers are unsigned and little-endian.

docs/snapshot-versioning.md

@@ -50,6 +50,9 @@ The config blob also records `hyperlight_version`, the `CARGO_PKG_VERSION`
 of the host crate at write time. This is informational only. The loader
 records it for diagnostics and does not gate loading on it.
 
+The optional `metadata` field stores application-owned values by namespace.
+Writers omit an empty map, and readers treat a missing field as empty.
+
 ## Compatibility cleanup
 
 Record compatibility paths here when a future hard snapshot break can remove

src/hyperlight_host/src/sandbox/snapshot/file/config.rs

@@ -1,6 +1,8 @@
 // SPDX-License-Identifier: Apache-2.0
 // Copyright 2025 The Hyperlight Authors.
 
+use std::collections::BTreeMap;
+
 use hyperlight_common::flatbuffer_wrappers::function_types::{ParameterType, ReturnType};
 use hyperlight_common::flatbuffer_wrappers::host_function_definition::HostFunctionDefinition;
 use hyperlight_common::vmem::PAGE_SIZE;
@@ -199,6 +201,9 @@ pub(super) struct OciSnapshotConfig {
     /// `SCRATCH_TOP_SNAPSHOT_GENERATION_OFFSET` is continuous across
     /// save/load.
     pub(super) snapshot_generation: u64,
+    /// Application-owned metadata keyed by namespace.
+    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
+    pub(super) metadata: BTreeMap<String, serde_json::Value>,
 }
 
 /// Sizes and permissions of the regions inside the snapshot blob,
@@ -847,6 +852,7 @@ mod tests {
             memory_size: PAGE_SIZE as u64,
             host_functions: Vec::new(),
             snapshot_generation: 0,
+            metadata: BTreeMap::new(),
         }
     }
 

src/hyperlight_host/src/sandbox/snapshot/file/mod.rs

@@ -653,6 +653,7 @@ impl Snapshot {
             memory_size: self.state.memory.mem_size() as u64,
             host_functions,
             snapshot_generation: self.state.snapshot_generation,
+            metadata: self.metadata.clone(),
         })
     }
 
@@ -965,6 +966,7 @@ impl Snapshot {
                 host_functions,
                 virtq: Some(virtq),
             }),
+            metadata: cfg.metadata,
         })
     }
 }

src/hyperlight_host/src/sandbox/snapshot/file_tests.rs

@@ -8,6 +8,7 @@
 use std::sync::Arc;
 
 use hyperlight_testing::{c_simple_guest_as_pathbuf, simple_guest_as_pathbuf};
+use serde::{Deserialize, Serialize};
 use serde_json::Value;
 use sha2::{Digest as _, Sha256};
 
@@ -51,6 +52,12 @@ fn create_snapshot() -> Arc<Snapshot> {
     sbox.snapshot().unwrap()
 }
 
+#[derive(Debug, PartialEq, Eq, Serialize, Deserialize)]
+struct TestMetadata {
+    format_version: u32,
+    runtime: String,
+}
+
 /// `Result::unwrap_err` requires `T: Debug`, but `Snapshot` is not
 /// `Debug`. This wrapper is the test-side equivalent.
 #[track_caller]
@@ -144,6 +151,45 @@ fn from_snapshot_in_memory_pre_init() {
     assert_eq!(result, 0);
 }
 
+#[test]
+fn snapshot_metadata_is_immutable_and_shares_state() {
+    let snapshot = create_snapshot();
+    let metadata = TestMetadata {
+        format_version: 1,
+        runtime: "test".to_string(),
+    };
+
+    let with_metadata = snapshot
+        .with_metadata("snapshot-metadata-namespace-v1", &metadata)
+        .unwrap();
+
+    assert!(Arc::ptr_eq(&snapshot.state, &with_metadata.state));
+    assert_eq!(
+        snapshot
+            .metadata::<TestMetadata>("snapshot-metadata-namespace-v1")
+            .unwrap(),
+        None
+    );
+    assert_eq!(
+        with_metadata
+            .metadata::<TestMetadata>("snapshot-metadata-namespace-v1")
+            .unwrap(),
+        Some(metadata)
+    );
+}
+
+#[test]
+fn snapshot_metadata_namespaces_are_independent() {
+    let snapshot = create_snapshot();
+    let first = snapshot.with_metadata("first", &1_u32).unwrap();
+    let second = first.with_metadata("second", &2_u32).unwrap();
+    let replaced = second.with_metadata("first", &3_u32).unwrap();
+
+    assert_eq!(second.metadata::<u32>("first").unwrap(), Some(1));
+    assert_eq!(replaced.metadata::<u32>("first").unwrap(), Some(3));
+    assert_eq!(replaced.metadata::<u32>("second").unwrap(), Some(2));
+}
+
 // Round-trip via OCI layout on disk.
 
 #[test]
@@ -164,6 +210,59 @@ fn round_trip_save_load_call() {
     assert_eq!(result, "hello\n");
 }
 
+#[test]
+fn snapshot_metadata_round_trip() {
+    let metadata = TestMetadata {
+        format_version: 1,
+        runtime: "test".to_string(),
+    };
+    let snapshot = create_snapshot()
+        .with_metadata("snapshot-metadata-namespace-v1", &metadata)
+        .unwrap();
+    let dir = tempfile::tempdir().unwrap();
+    let path = dir.path().join("metadata");
+
+    snapshot
+        .save(&path, &OciTag::new("latest").unwrap())
+        .unwrap();
+    let config: Value =
+        serde_json::from_slice(&std::fs::read(find_config_blob(&path)).unwrap()).unwrap();
+    assert_eq!(
+        config["metadata"],
+        serde_json::json!({
+            "snapshot-metadata-namespace-v1": {
+                "format_version": 1,
+                "runtime": "test",
+            }
+        })
+    );
+    let loaded = Snapshot::checked_load(&path, OciTag::new("latest").unwrap()).unwrap();
+
+    assert_eq!(
+        loaded
+            .metadata::<TestMetadata>("snapshot-metadata-namespace-v1")
+            .unwrap(),
+        Some(metadata)
+    );
+}
+
+#[test]
+fn snapshot_without_metadata_omits_config_field() {
+    let snapshot = create_snapshot();
+    let dir = tempfile::tempdir().unwrap();
+    let path = dir.path().join("metadata");
+
+    snapshot
+        .save(&path, &OciTag::new("latest").unwrap())
+        .unwrap();
+    let config: Value =
+        serde_json::from_slice(&std::fs::read(find_config_blob(&path)).unwrap()).unwrap();
+    let loaded = Snapshot::checked_load(&path, OciTag::new("latest").unwrap()).unwrap();
+
+    assert!(config.get("metadata").is_none());
+    assert_eq!(loaded.metadata::<Value>("missing").unwrap(), None);
+}
+
 /// A pre-existing snapshot blob with the right length but wrong
 /// bytes (corruption, partial copy, foreign tool) must be detected
 /// and replaced by `save`, not silently trusted.

src/hyperlight_host/src/sandbox/snapshot/mod.rs

@@ -59,6 +59,8 @@ pub enum NextAction {
 /// An immutable snapshot of sandbox state.
 pub struct Snapshot {
     state: Arc<SnapshotState>,
+    // Stable key order keeps config bytes deterministic.
+    metadata: BTreeMap<String, serde_json::Value>,
 }
 
 /// Immutable sandbox state held by a snapshot.
@@ -409,6 +411,7 @@ impl Snapshot {
                 },
                 virtq: None,
             }),
+            metadata: BTreeMap::new(),
         })
     }
 
@@ -601,9 +604,98 @@ impl Snapshot {
                 host_functions,
                 virtq,
             }),
+            metadata: BTreeMap::new(),
         })
     }
 
+    /// Deserializes the metadata stored under `namespace` as `T`.
+    ///
+    /// Returns `None` if the namespace has no metadata.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if the JSON metadata cannot be deserialized as `T`.
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// # use std::sync::Arc;
+    /// # use hyperlight_host::sandbox::snapshot::Snapshot;
+    /// # use serde::{Deserialize, Serialize};
+    /// #
+    /// #[derive(Debug, PartialEq, Serialize, Deserialize)]
+    /// struct Metadata {
+    ///     version: u32,
+    /// }
+    ///
+    /// # fn example(snapshot: Arc<Snapshot>) -> Result<(), Box<dyn std::error::Error>> {
+    /// let snapshot =
+    ///     snapshot.with_metadata("snapshot-metadata-namespace-v1", &Metadata { version: 1 })?;
+    /// let metadata = snapshot
+    ///     .metadata::<Metadata>("snapshot-metadata-namespace-v1")?
+    ///     .expect("metadata should exist");
+    /// assert_eq!(metadata, Metadata { version: 1 });
+    /// # Ok(())
+    /// # }
+    /// ```
+    pub fn metadata<T>(&self, namespace: &str) -> Result<Option<T>>
+    where
+        T: serde::de::DeserializeOwned,
+    {
+        self.metadata
+            .get(namespace)
+            .cloned()
+            .map(serde_json::from_value)
+            .transpose()
+            .map_err(Into::into)
+    }
+
+    /// Adds `metadata` to this snapshot and returns the result as a new
+    /// snapshot. Metadata already stored under `namespace` is replaced.
+    ///
+    /// This snapshot remains unchanged.
+    /// Metadata is saved and loaded with the snapshot.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if `metadata` cannot be serialized as JSON.
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// # use std::sync::Arc;
+    /// # use hyperlight_host::sandbox::snapshot::Snapshot;
+    /// # use serde::{Deserialize, Serialize};
+    /// #
+    /// #[derive(Debug, PartialEq, Serialize, Deserialize)]
+    /// struct Metadata {
+    ///     version: u32,
+    /// }
+    ///
+    /// # fn example(snapshot: Arc<Snapshot>) -> Result<(), Box<dyn std::error::Error>> {
+    /// let snapshot =
+    ///     snapshot.with_metadata("snapshot-metadata-namespace-v1", &Metadata { version: 1 })?;
+    /// let metadata = snapshot
+    ///     .metadata::<Metadata>("snapshot-metadata-namespace-v1")?
+    ///     .expect("metadata should exist");
+    /// assert_eq!(metadata, Metadata { version: 1 });
+    /// # Ok(())
+    /// # }
+    /// ```
+    pub fn with_metadata<T>(&self, namespace: impl Into<String>, metadata: &T) -> Result<Arc<Self>>
+    where
+        T: serde::Serialize,
+    {
+        let namespace = namespace.into();
+        let metadata = serde_json::to_value(metadata)?;
+        let mut metadata_by_namespace = self.metadata.clone();
+        metadata_by_namespace.insert(namespace, metadata);
+        Ok(Arc::new(Self {
+            state: Arc::clone(&self.state),
+            metadata: metadata_by_namespace,
+        }))
+    }
+
     /// Generation number assigned to this snapshot when it was taken.
     pub(crate) fn snapshot_generation(&self) -> u64 {
         self.state.snapshot_generation