microsandbox-rb 0.10.0 → 0.11.0

data/ext/microsandbox/src/image.rs

@@ -7,9 +7,11 @@
 
 use magnus::{function, prelude::*, Error, RArray, RHash, RModule, Ruby};
 use microsandbox::image::{Image, ImageDetail, ImageHandle, ImagePruneReport};
+use microsandbox::ImageArchiveFormat;
 
 use crate::backend::with_local_backend;
 use crate::conv;
+use crate::error;
 use crate::runtime::ruby;
 
 fn handle_to_hash(h: &ImageHandle) -> RHash {
@@ -109,6 +111,40 @@ fn prune() -> Result<RHash, Error> {
     Ok(report_to_hash(report))
 }
 
+/// Load images into the cache from a local `docker save` tarball or an OCI
+/// Image Layout archive. `tags` optionally retags what was loaded. Returns an
+/// Array of image-handle Hashes. Mirrors the Python `Image.load` / Node
+/// `imageLoad` added in v0.6.7. (The `"-"` stdin form is spooled to a temp
+/// file by the Ruby layer — the core reads seekable files only.)
+fn load(input_path: String, tags: Vec<String>) -> Result<RArray, Error> {
+    let handles = with_local_backend(async |local| {
+        Image::load_local(local, std::path::Path::new(&input_path), tags).await
+    })?;
+    let arr = ruby().ary_new();
+    for h in handles.iter() {
+        arr.push(handle_to_hash(h))?;
+    }
+    Ok(arr)
+}
+
+/// Save cached image(s) into a local archive. `format` is "docker" (default
+/// shape callers expect from `docker load`) or "oci" (OCI Image Layout).
+/// Mirrors the Python `Image.save` / Node `imageSave` added in v0.6.7.
+fn save(references: Vec<String>, output_path: String, format: String) -> Result<(), Error> {
+    let fmt = match format.as_str() {
+        "docker" => ImageArchiveFormat::Docker,
+        "oci" => ImageArchiveFormat::Oci,
+        other => {
+            return Err(error::base_error(format!(
+                "invalid archive format {other:?}: expected \"docker\" or \"oci\""
+            )))
+        }
+    };
+    with_local_backend(async |local| {
+        Image::save_local(local, &references, std::path::Path::new(&output_path), fmt).await
+    })
+}
+
 pub fn define(ruby: &Ruby, native: &RModule) -> Result<(), Error> {
     let class = native.define_class("Image", ruby.class_object())?;
     class.define_singleton_method("get", function!(get, 1))?;
@@ -116,5 +152,7 @@ pub fn define(ruby: &Ruby, native: &RModule) -> Result<(), Error> {
     class.define_singleton_method("inspect", function!(inspect, 1))?;
     class.define_singleton_method("remove", function!(remove, 2))?;
     class.define_singleton_method("prune", function!(prune, 0))?;
+    class.define_singleton_method("load", function!(load, 2))?;
+    class.define_singleton_method("save", function!(save, 3))?;
     Ok(())
 }

data/ext/microsandbox/src/sandbox.rs

@@ -20,9 +20,9 @@ use microsandbox::logs::{
 use microsandbox::sandbox::{
     AttachOptionsBuilder, DiskImageFormat, EnvVar, FsEntry, FsEntryKind, FsMetadata,
     HostPermissions, Patch, PullPolicy, PullProgress, PullProgressHandle, RlimitResource,
-    SandboxBuilder, SandboxFilter, SandboxHandle, SandboxMetrics, SandboxModificationBuilder,
-    SandboxModificationPatch, SandboxStatus, SandboxStopResult, SecretBuilder,
-    SecretModificationPatch, SecretSource, SecurityProfile, StatVirtualization,
+    RootDiskBuilder, SandboxBuilder, SandboxFilter, SandboxHandle, SandboxMetrics,
+    SandboxModificationBuilder, SandboxModificationPatch, SandboxStatus, SandboxStopResult,
+    SecretBuilder, SecretModificationPatch, SecretSource, SecurityProfile, StatVirtualization,
 };
 use microsandbox::LogLevel;
 use microsandbox::MicrosandboxResult;
@@ -30,7 +30,8 @@ use microsandbox::RegistryAuth;
 use microsandbox_network::builder::ViolationActionBuilder;
 use microsandbox_network::dns::Nameserver;
 use microsandbox_network::policy::{
-    Action, Destination, DestinationGroup, Direction, NetworkPolicy, PortRange, Protocol, Rule,
+    Action, Destination, DestinationGroup, Direction, NetworkPolicy, NetworkProfile, PortRange,
+    Protocol, Rule,
 };
 use tokio::sync::Mutex;
 use tokio::task::JoinHandle;
@@ -166,6 +167,10 @@ impl Sandbox {
             let host_perms = conv::opt_string(m, "host_permissions")?
                 .map(|s| host_permissions_from_str(&s))
                 .transpose()?;
+            // v0.6.7: mount-root symlink protection is on by default; this is
+            // the per-mount opt-out. Valid for bind/named-directory mounts —
+            // the core rejects it elsewhere at build().
+            let follow_root_symlinks = conv::opt::<bool>(m, "follow_root_symlinks")?;
             // bind/named/disk require a source; tmpfs must not have one.
             match kind.as_str() {
                 "bind" | "named" | "disk" if source.is_some() => {}
@@ -218,6 +223,9 @@ impl Sandbox {
                 if let Some(hp) = host_perms {
                     mb = mb.host_permissions(hp);
                 }
+                if let Some(follow) = follow_root_symlinks {
+                    mb = mb.follow_root_symlinks(follow);
+                }
                 mb
             });
         }
@@ -230,18 +238,29 @@ impl Sandbox {
         if let Some(net) = conv::opt_string(opts, "network")? {
             match net.as_str() {
                 "none" | "disabled" | "disable" | "airgapped" => b = b.disable_network(),
-                // Default policy is public-only, so no builder call is needed.
-                "public" | "public_only" | "default" => {}
                 "all" | "allow_all" => b = b.network(|n| n.policy(NetworkPolicy::allow_all())),
-                "non_local" | "nonlocal" => b = b.network(|n| n.policy(NetworkPolicy::non_local())),
                 other => {
                     return Err(error::base_error(format!(
-                        "unknown network mode {other:?} (expected one of \
-                         public_only/none/allow_all/non_local)"
+                        "unknown network mode {other:?} (expected none/allow_all; compose \
+                         public/private/host access via network profiles)"
                     )))
                 }
             }
         }
+        // Composable network profiles (v0.6.7): expanded to the canonical rule
+        // set plus a gateway-DNS allow by the core's
+        // `NetworkPolicy::from_profiles`. The Ruby layer routes
+        // `network: [:public, :host]` (and single-profile sugar) here. An empty
+        // profile set never reaches this key — the Ruby layer sends it as an
+        // explicit empty custom policy, which has identical semantics.
+        let profile_names = conv::opt_string_vec(opts, "network_profiles")?;
+        if !profile_names.is_empty() {
+            let profiles = profile_names
+                .iter()
+                .map(|s| network_profile_from_str(s))
+                .collect::<Result<Vec<_>, Error>>()?;
+            b = b.network(move |n| n.policy(NetworkPolicy::from_profiles(profiles)));
+        }
         // Custom network policy: an ordered allow/deny rule list with per-direction
         // defaults and bulk domain denials. The Ruby layer routes bare presets to
         // the `network` key above and full policies here; mirrors the Python
@@ -261,8 +280,14 @@ impl Sandbox {
         if let Some(policy) = conv::opt_string(opts, "pull_policy")? {
             b = b.pull_policy(pull_policy_from_str(&policy)?);
         }
-        if let Some(mib) = conv::opt_u32(opts, "oci_upper_size")? {
-            b = b.oci_upper_size(mib);
+        // Writable root-disk spec for OCI sandboxes (v0.6.7): Integer = managed
+        // ext4 upper size in MiB (the pre-0.6.7 `oci_upper_size` meaning), Hash =
+        // {kind: managed|tmpfs|disk, size_mib, path, format, fstype}. The Ruby
+        // layer maps the deprecated `oci_upper_size:` kwarg to the managed kind
+        // before it reaches the wire.
+        if let Some(v) = conv::opt::<Value>(opts, "root_disk")? {
+            let spec = parse_root_disk(v)?;
+            b = b.root_disk_with(move |d| spec.apply(d));
         }
         // Registry connection settings, for private / non-default registries:
         // Basic auth (username + password/token), plain-HTTP `insecure`, and
@@ -1258,12 +1283,14 @@ fn parse_tls(t: RHash) -> Result<TlsSpec, Error> {
 /// a core `NetworkPolicy`. Returns `None` when the option is absent (bare
 /// presets travel via the separate `network` key handled in `create`).
 ///
-/// Composition (mirrors the Go SDK's `NetworkConfig`): bulk domain-deny rules
-/// come first (so they outrank later allow rules), then a preset's rules (if a
-/// preset base is given), then the caller's explicit `rules`. Per-direction
-/// defaults come from the explicit `default_egress`/`default_ingress` when set,
-/// else the preset's defaults, else the asymmetric default (deny egress / allow
-/// ingress).
+/// Composition order (first-match-wins per direction): bulk domain-deny rules
+/// come first (so they outrank everything), then the caller's explicit
+/// `rules`, then the profile/preset base's expansion LAST — the same order the
+/// upstream CLI composes `--net` with explicit rules, so a narrower caller
+/// override (e.g. `Rule.deny_dns`) beats the base's allows instead of dying
+/// behind them. Per-direction defaults come from the explicit
+/// `default_egress`/`default_ingress` when set, else the base's defaults, else
+/// the asymmetric default (deny egress / allow ingress).
 fn parse_network_policy(opts: RHash) -> Result<Option<NetworkPolicy>, Error> {
     let Some(np) = conv::opt::<RHash>(opts, "network_policy")? else {
         return Ok(None);
@@ -1284,21 +1311,40 @@ fn parse_network_policy(opts: RHash) -> Result<Option<NetworkPolicy>, Error> {
         rules.push(Rule::deny_egress(Destination::DomainSuffix(suffix)));
     }
 
-    // Optional preset base (its rules and defaults seed the policy).
-    let (preset_egress, preset_ingress) = match conv::opt_string(np, "preset")? {
-        Some(p) => {
-            let mut base = network_preset(&p)?;
+    // Optional base — composable profiles (v0.6.7) or a terminal preset,
+    // mutually exclusive. Its rules and defaults seed the policy.
+    let profile_names = conv::opt_string_vec(np, "profiles")?;
+    let preset = conv::opt_string(np, "preset")?;
+    if !profile_names.is_empty() && preset.is_some() {
+        return Err(error::base_error(
+            "network profiles: and preset: are mutually exclusive",
+        ));
+    }
+    let base = if profile_names.is_empty() {
+        preset.map(|p| network_preset(&p)).transpose()?
+    } else {
+        let profiles = profile_names
+            .iter()
+            .map(|s| network_profile_from_str(s))
+            .collect::<Result<Vec<_>, Error>>()?;
+        Some(NetworkPolicy::from_profiles(profiles))
+    };
+    // Caller's explicit rules go BEFORE the base expansion: under
+    // first-match-wins, appending them after would make any override of a
+    // base-allowed destination silently dead (a more permissive policy than
+    // requested). Mirrors the upstream CLI's `--net` + rules composition.
+    for rd in conv::opt_hash_vec(np, "rules")? {
+        rules.push(parse_rule(rd)?);
+    }
+
+    let (preset_egress, preset_ingress) = match base {
+        Some(mut base) => {
             rules.append(&mut base.rules);
             (Some(base.default_egress), Some(base.default_ingress))
         }
         None => (None, None),
     };
 
-    // Caller's explicit rules come after preset rules.
-    for rd in conv::opt_hash_vec(np, "rules")? {
-        rules.push(parse_rule(rd)?);
-    }
-
     let default_egress = match conv::opt_string(np, "default_egress")? {
         Some(s) => action_from_str(&s)?,
         None => preset_egress.unwrap_or(Action::Deny),
@@ -1318,15 +1364,102 @@ fn parse_network_policy(opts: RHash) -> Result<Option<NetworkPolicy>, Error> {
 fn network_preset(p: &str) -> Result<NetworkPolicy, Error> {
     Ok(match p {
         "none" | "disabled" | "disable" | "airgapped" => NetworkPolicy::none(),
-        "public" | "public_only" | "public-only" | "default" => NetworkPolicy::public_only(),
         "all" | "allow_all" | "allow-all" => NetworkPolicy::allow_all(),
-        "non_local" | "non-local" | "nonlocal" => NetworkPolicy::non_local(),
         other => {
             return Err(error::base_error(format!(
-                "unknown network preset {other:?} (expected one of \
-                 public_only/none/allow_all/non_local)"
+                "unknown network preset {other:?} (expected none/allow_all; the removed \
+                 public_only/non_local presets are replaced by composable profiles)"
+            )))
+        }
+    })
+}
+
+fn network_profile_from_str(s: &str) -> Result<NetworkProfile, Error> {
+    match s {
+        "public" => Ok(NetworkProfile::Public),
+        "private" => Ok(NetworkProfile::Private),
+        "host" => Ok(NetworkProfile::Host),
+        other => Err(error::base_error(format!(
+            "unknown network profile {other:?} (expected public/private/host)"
+        ))),
+    }
+}
+
+/// Parsed `root_disk` create option. Integer shorthand = managed upper of N
+/// MiB (mirrors Python's `root_disk=8192` and the CLI bare-size form); Hash =
+/// explicit kind. Kind/field cross-validation (size on a disk image, etc.)
+/// lives in the Ruby layer and the core builder — this stays a dumb carrier.
+struct RootDiskSpec {
+    kind: RootDiskKindSpec,
+    size_mib: Option<u32>,
+    format: Option<DiskImageFormat>,
+    fstype: Option<String>,
+}
+
+enum RootDiskKindSpec {
+    Managed,
+    Tmpfs,
+    Disk(String),
+}
+
+impl RootDiskSpec {
+    fn apply(self, mut d: RootDiskBuilder) -> RootDiskBuilder {
+        match self.kind {
+            RootDiskKindSpec::Managed => {}
+            RootDiskKindSpec::Tmpfs => d = d.tmpfs(),
+            RootDiskKindSpec::Disk(path) => d = d.disk_image(path),
+        }
+        if let Some(mib) = self.size_mib {
+            d = d.size(mib);
+        }
+        if let Some(f) = self.format {
+            d = d.format(f);
+        }
+        if let Some(ft) = self.fstype {
+            d = d.fstype(ft);
+        }
+        d
+    }
+}
+
+fn parse_root_disk(v: Value) -> Result<RootDiskSpec, Error> {
+    if let Ok(mib) = u32::try_convert(v) {
+        return Ok(RootDiskSpec {
+            kind: RootDiskKindSpec::Managed,
+            size_mib: Some(mib),
+            format: None,
+            fstype: None,
+        });
+    }
+    let Ok(h) = RHash::try_convert(v) else {
+        return Err(error::base_error(
+            "root_disk: expects an Integer (managed size in MiB) or a Hash \
+             (use Microsandbox::RootDisk.managed/tmpfs/disk)",
+        ));
+    };
+    let kind = match conv::opt_string(h, "kind")?.as_deref() {
+        None | Some("managed") => RootDiskKindSpec::Managed,
+        Some("tmpfs") => RootDiskKindSpec::Tmpfs,
+        Some("disk" | "disk-image" | "disk_image") => {
+            let Some(path) = conv::opt_string(h, "path")? else {
+                return Err(error::base_error("root_disk disk kind requires path:"));
+            };
+            RootDiskKindSpec::Disk(path)
+        }
+        Some(other) => {
+            return Err(error::base_error(format!(
+                "unknown root_disk kind {other:?} (expected managed/tmpfs/disk)"
             )))
         }
+    };
+    let format = conv::opt_string(h, "format")?
+        .map(|f| disk_format_from_str(&f))
+        .transpose()?;
+    Ok(RootDiskSpec {
+        kind,
+        size_mib: conv::opt_u32(h, "size_mib")?,
+        format,
+        fstype: conv::opt_string(h, "fstype")?,
     })
 }
 
@@ -2143,17 +2276,13 @@ impl SbHandle {
     /// Snapshot this (stopped) sandbox under a bare name (resolved under the
     /// snapshots directory). Returns the same SnapshotInfo Hash as
     /// `Snapshot.create`. Mirrors the Python/Node `handle.snapshot(name)`.
+    /// (`snapshot_to` was removed upstream in v0.6.7 — use `Snapshot.create`
+    /// with `dest_dir:` for explicit placement.)
     fn snapshot(&self, name: String) -> Result<RHash, Error> {
         let snap = block_on(self.inner.snapshot(&name)).map_err(error::to_ruby)?;
         Ok(crate::snapshot::snapshot_to_hash(&snap))
     }
 
-    /// Snapshot this (stopped) sandbox to an explicit filesystem path.
-    fn snapshot_to(&self, path: String) -> Result<RHash, Error> {
-        let snap = block_on(self.inner.snapshot_to(path)).map_err(error::to_ruby)?;
-        Ok(crate::snapshot::snapshot_to_hash(&snap))
-    }
-
     /// Health-check the guest agent without refreshing the idle timer. A stopped
     /// sandbox raises `SandboxNotRunningError` (the handle does not start it
     /// implicitly). Returns `{ name, latency_secs }`.
@@ -2337,7 +2466,6 @@ pub fn define(ruby: &Ruby, native: &RModule) -> Result<(), Error> {
     )?;
     handle.define_method("config_json", method!(SbHandle::config_json, 0))?;
     handle.define_method("snapshot", method!(SbHandle::snapshot, 1))?;
-    handle.define_method("snapshot_to", method!(SbHandle::snapshot_to, 1))?;
     handle.define_method("ping", method!(SbHandle::ping, 0))?;
     handle.define_method("touch", method!(SbHandle::touch, 0))?;
     handle.define_method("modify", method!(SbHandle::modify, 1))?;

data/ext/microsandbox/src/snapshot.rs

@@ -1,16 +1,21 @@
 //! Snapshot management: `Microsandbox::Native::Snapshot`.
 //!
-//! Snapshots capture a stopped sandbox's upper layer into a portable artifact
+//! Snapshots capture a stopped sandbox's disk state into a portable artifact
 //! that a later `Sandbox.create(from_snapshot:)` can boot from. Exposed as
 //! singleton functions returning plain Hashes/Arrays (shaped into value objects
 //! by the Ruby layer) — there is no long-lived handle to own.
+//!
+//! v0.6.7 descriptor contract: an artifact is identified by its own `name`
+//! (`Snapshot::builder(name).from_sandbox(src)`), lives at `dest_dir/<name>`,
+//! and its descriptor file is `snapshot.json`. `manifest.json` artifacts from
+//! v0.6.6 are auto-migrated by the core on first backend connect.
 
 use std::path::{Path, PathBuf};
 
 use magnus::{function, prelude::*, Error, RArray, RHash, RModule, Ruby};
 use microsandbox::snapshot::{
-    ExportOpts, Snapshot, SnapshotDestination, SnapshotFormat, SnapshotHandle,
-    SnapshotVerifyReport, UpperVerifyStatus,
+    SaveOpts, Snapshot, SnapshotFormat, SnapshotHandle, SnapshotScope, SnapshotVerifyReport,
+    UpperVerifyStatus,
 };
 
 use crate::conv;
@@ -24,6 +29,13 @@ fn format_str(format: SnapshotFormat) -> &'static str {
     }
 }
 
+fn scope_str(scope: SnapshotScope) -> &'static str {
+    match scope {
+        SnapshotScope::Disk => "disk",
+        SnapshotScope::Resumable => "resumable",
+    }
+}
+
 /// Parse a manifest's RFC 3339 `created_at` into epoch-ms (nil if unparseable).
 fn created_at_ms(rfc3339: &str) -> Option<i64> {
     chrono::DateTime::parse_from_rfc3339(rfc3339)
@@ -33,18 +45,31 @@ fn created_at_ms(rfc3339: &str) -> Option<i64> {
 
 /// Convert a fully-opened `Snapshot` into the `SnapshotInfo` Hash. Unlike a
 /// `SnapshotHandle` (a lightweight index row), an opened snapshot carries the
-/// full manifest, so this is the richest shape — `create`/`open`/`list_dir`
-/// and the `SandboxHandle#snapshot`/`#snapshot_to` shortcuts all funnel here.
+/// full descriptor, so this is the richest shape — `create`/`open`/`list_dir`
+/// and the `SandboxHandle#snapshot` shortcut all funnel here. `format`/
+/// `fstype`/`size_bytes` are nil for checkpoint-state snapshots, and the
+/// `checkpoint_*` keys are nil for file-state ones — the two state families
+/// are disjoint by contract.
 pub(crate) fn snapshot_to_hash(snap: &Snapshot) -> RHash {
     let m = snap.manifest();
+    let state = snap.state();
+    let file = state.as_file();
+    let checkpoint = state.as_checkpoint();
     let hash = ruby().hash_new();
     let _ = hash.aset("digest", snap.digest().to_string());
     let _ = hash.aset("path", snap.path().to_string_lossy().into_owned());
     let _ = hash.aset("size_bytes", snap.size_bytes());
+    let _ = hash.aset("scope", scope_str(m.scope));
+    let _ = hash.aset("state_kind", state.kind());
     let _ = hash.aset("image_ref", m.image.reference.clone());
     let _ = hash.aset("image_manifest_digest", m.image.manifest_digest.clone());
-    let _ = hash.aset("format", format_str(m.format));
-    let _ = hash.aset("fstype", m.fstype.clone());
+    let _ = hash.aset("format", file.map(|f| format_str(f.format)));
+    let _ = hash.aset("fstype", file.map(|f| f.fstype.clone()));
+    let _ = hash.aset("checkpoint_id", checkpoint.map(|c| c.checkpoint_id.clone()));
+    let _ = hash.aset(
+        "checkpoint_manifest_digest",
+        checkpoint.map(|c| c.manifest.clone()),
+    );
     let _ = hash.aset("parent_digest", m.parent.clone());
     let _ = hash.aset("created_at_ms", created_at_ms(&m.created_at));
     let _ = hash.aset("source_sandbox", m.source_sandbox.clone());
@@ -56,18 +81,21 @@ pub(crate) fn snapshot_to_hash(snap: &Snapshot) -> RHash {
     hash
 }
 
-/// Create a snapshot of a stopped sandbox. `opts`: name | path (destination),
-/// labels, force, record_integrity. Returns {digest, path, size_bytes}.
-fn create(source_sandbox: String, opts: RHash) -> Result<RHash, Error> {
-    let mut b = Snapshot::builder(source_sandbox);
-    if let Some(name) = conv::opt_string(opts, "name")? {
-        b = b.destination(SnapshotDestination::Name(name));
-    } else if let Some(path) = conv::opt_string(opts, "path")? {
-        b = b.destination(SnapshotDestination::Path(PathBuf::from(path)));
-    } else {
-        return Err(error::base_error(
-            "snapshot create needs a destination: pass name: or path:",
-        ));
+/// Create a snapshot artifact named `name` from a stopped sandbox. `opts`:
+/// from_sandbox (required), dest_dir, labels, force, record_integrity,
+/// resumable. Returns the full SnapshotInfo Hash.
+fn create(name: String, opts: RHash) -> Result<RHash, Error> {
+    let mut b = Snapshot::builder(name);
+    match conv::opt_string(opts, "from_sandbox")? {
+        Some(src) => b = b.from_sandbox(src),
+        None => {
+            return Err(error::base_error(
+                "snapshot create needs from_sandbox: (the source sandbox name)",
+            ));
+        }
+    }
+    if let Some(dir) = conv::opt_string(opts, "dest_dir")? {
+        b = b.dest_dir(PathBuf::from(dir));
     }
     for (k, v) in conv::opt_string_map(opts, "labels")? {
         b = b.label(k, v);
@@ -78,6 +106,9 @@ fn create(source_sandbox: String, opts: RHash) -> Result<RHash, Error> {
     if conv::opt_bool(opts, "record_integrity")? {
         b = b.record_integrity();
     }
+    if conv::opt_bool(opts, "resumable")? {
+        b = b.resumable();
+    }
 
     let snap = block_on(b.create()).map_err(error::to_ruby)?;
     Ok(snapshot_to_hash(&snap))
@@ -92,8 +123,8 @@ fn open(path_or_name: String) -> Result<RHash, Error> {
     Ok(snapshot_to_hash(&snap))
 }
 
-/// Walk `dir` and parse each subdirectory's `manifest.json` without touching the
-/// local index — for enumerating external/un-imported snapshot collections.
+/// Walk `dir` and parse each subdirectory's `snapshot.json` without touching
+/// the local index — for enumerating external/un-imported snapshot collections.
 fn list_dir(dir: String) -> Result<RArray, Error> {
     let snaps = block_on(Snapshot::list_dir(Path::new(&dir))).map_err(error::to_ruby)?;
     let arr = ruby().ary_new();
@@ -140,7 +171,9 @@ fn remove(name_or_path: String, force: bool) -> Result<(), Error> {
 }
 
 /// Verify a snapshot's recorded upper-layer integrity. Returns
-/// {digest, path, upper_status, upper_algorithm?, upper_digest?}.
+/// {digest, path, upper_status, upper_algorithm, upper_digest}. Schema-1
+/// descriptors always record integrity, so the status is always "verified"
+/// on success (mismatches raise SnapshotIntegrityError instead).
 fn verify(name_or_path: String) -> Result<RHash, Error> {
     let snap = block_on(Snapshot::open(&name_or_path)).map_err(error::to_ruby)?;
     let report = block_on(snap.verify()).map_err(error::to_ruby)?;
@@ -149,25 +182,25 @@ fn verify(name_or_path: String) -> Result<RHash, Error> {
 
 /// Bundle a snapshot into a `.tar.zst` (or plain `.tar`) archive. `opts`:
 /// with_parents, with_image, plain_tar.
-fn export(name_or_path: String, out_path: String, opts: RHash) -> Result<(), Error> {
-    let export_opts = ExportOpts {
+fn save(name_or_path: String, out_path: String, opts: RHash) -> Result<(), Error> {
+    let save_opts = SaveOpts {
         with_parents: conv::opt_bool(opts, "with_parents")?,
         with_image: conv::opt_bool(opts, "with_image")?,
         plain_tar: conv::opt_bool(opts, "plain_tar")?,
     };
-    block_on(Snapshot::export(
+    block_on(Snapshot::save(
         &name_or_path,
         std::path::Path::new(&out_path),
-        export_opts,
+        save_opts,
     ))
     .map_err(error::to_ruby)
 }
 
-/// Unpack a snapshot archive into the snapshots dir. Returns the imported
+/// Unpack a snapshot archive into the snapshots dir. Returns the loaded
 /// snapshot's metadata hash. `dest` is an optional explicit directory.
-fn import(archive_path: String, dest: Option<String>) -> Result<RHash, Error> {
+fn load(archive_path: String, dest: Option<String>) -> Result<RHash, Error> {
     let dest_path = dest.map(PathBuf::from);
-    let handle = block_on(Snapshot::import(
+    let handle = block_on(Snapshot::load(
         std::path::Path::new(&archive_path),
         dest_path.as_deref(),
     ))
@@ -180,9 +213,23 @@ fn handle_to_hash(handle: &SnapshotHandle) -> RHash {
     let _ = hash.aset("digest", handle.digest().to_string());
     let _ = hash.aset("name", handle.name().map(str::to_string));
     let _ = hash.aset("parent_digest", handle.parent_digest().map(str::to_string));
+    let _ = hash.aset("scope", scope_str(handle.scope()));
+    let _ = hash.aset("state_kind", handle.state_kind().to_string());
     let _ = hash.aset("image_ref", handle.image_ref().to_string());
-    let _ = hash.aset("format", format_str(handle.format()));
+    let _ = hash.aset("format", handle.format().map(format_str));
+    let _ = hash.aset("fstype", handle.fstype().map(str::to_string));
+    let _ = hash.aset(
+        "checkpoint_manifest_digest",
+        handle.checkpoint_manifest_digest().map(str::to_string),
+    );
     let _ = hash.aset("size_bytes", handle.size_bytes());
+    let _ = hash.aset("locality", handle.locality().to_string());
+    let _ = hash.aset("availability", handle.availability().to_string());
+    let _ = hash.aset("migration_state", handle.migration_state().to_string());
+    let _ = hash.aset(
+        "migration_error_code",
+        handle.migration_error_code().map(str::to_string),
+    );
     let _ = hash.aset("path", handle.path().to_string_lossy().into_owned());
     let _ = hash.aset(
         "created_at_ms",
@@ -196,9 +243,6 @@ fn verify_report_to_hash(report: &SnapshotVerifyReport) -> RHash {
     let _ = hash.aset("digest", report.digest.clone());
     let _ = hash.aset("path", report.path.to_string_lossy().into_owned());
     match &report.upper {
-        UpperVerifyStatus::NotRecorded => {
-            let _ = hash.aset("upper_status", "not_recorded");
-        }
         UpperVerifyStatus::Verified { algorithm, digest } => {
             let _ = hash.aset("upper_status", "verified");
             let _ = hash.aset("upper_algorithm", algorithm.clone());
@@ -218,7 +262,7 @@ pub fn define(ruby: &Ruby, native: &RModule) -> Result<(), Error> {
     class.define_singleton_method("reindex", function!(reindex, 1))?;
     class.define_singleton_method("remove", function!(remove, 2))?;
     class.define_singleton_method("verify", function!(verify, 1))?;
-    class.define_singleton_method("export", function!(export, 3))?;
-    class.define_singleton_method("import", function!(import, 2))?;
+    class.define_singleton_method("save", function!(save, 3))?;
+    class.define_singleton_method("load", function!(load, 2))?;
     Ok(())
 }

data/lib/microsandbox/errors.rb

@@ -62,6 +62,10 @@ module Microsandbox
   define_error(:SnapshotSandboxRunningError, "snapshot-sandbox-running")
   define_error(:SnapshotImageMissingError, "snapshot-image-missing")
   define_error(:SnapshotIntegrityError, "snapshot-integrity")
+  # v0.6.7: the automatic v0.6.6→v0.6.7 snapshot-descriptor migration (run at
+  # backend connect / artifact open) was blocked and needs repair. Mirrors the
+  # Python SDK's SnapshotMigrationError (code "snapshot-migration").
+  define_error(:SnapshotMigrationError, "snapshot-migration")
 
   # Networking / secrets errors ---------------------------------------------
   # NetworkPolicyError now also carries the core's `NetworkBuilder` build/parse

data/lib/microsandbox/image.rb

@@ -107,6 +107,44 @@ module Microsandbox
       def prune
         ImagePruneReport.new(Native::Image.prune)
       end
+
+      # Load images into the cache from a local `docker save` tarball or an
+      # OCI Image Layout archive. Pass `"-"` to read the archive from `$stdin`
+      # (spooled to a temp file first, like the Python SDK — the core reads
+      # seekable files only). Mirrors the Python `Image.load` / Node
+      # `imageLoad` (runtime v0.6.7).
+      # @param input_path [String] archive path (or "-")
+      # @param tag [String, Array<String>, nil] retag the loaded image(s)
+      # @return [Array<ImageInfo>] one entry per loaded image
+      def load(input_path, tag: nil)
+        tags = Array(tag).map(&:to_s)
+        path = input_path.to_s
+        if path == "-"
+          require "tempfile"
+          Tempfile.create(["msb-image-load", ".tar"]) do |tmp|
+            tmp.binmode
+            IO.copy_stream($stdin, tmp)
+            tmp.flush
+            return Native::Image.load(tmp.path, tags).map { |info| ImageInfo.new(info) }
+          end
+        end
+        Native::Image.load(path, tags).map { |info| ImageInfo.new(info) }
+      end
+
+      # Save cached image(s) into a local archive.
+      # Mirrors the Python `Image.save` / Node `imageSave` (runtime v0.6.7).
+      # @param reference [String, Array<String>] image reference(s) to save
+      # @param output_path [String] destination archive path
+      # @param format [:docker, :oci] archive layout (default :docker, the
+      #   shape `docker load` expects)
+      # @return [nil]
+      def save(reference, output_path:, format: :docker)
+        refs = Array(reference).map(&:to_s)
+        raise ArgumentError, "at least one image reference is required" if refs.empty?
+
+        Native::Image.save(refs, output_path.to_s, format.to_s)
+        nil
+      end
     end
   end
 end