microsandbox-rb 0.10.0 → 0.12.0

data/ext/microsandbox/src/sandbox.rs

@@ -20,7 +20,7 @@ use microsandbox::logs::{
 use microsandbox::sandbox::{
     AttachOptionsBuilder, DiskImageFormat, EnvVar, FsEntry, FsEntryKind, FsMetadata,
     HostPermissions, Patch, PullPolicy, PullProgress, PullProgressHandle, RlimitResource,
-    SandboxBuilder, SandboxFilter, SandboxHandle, SandboxMetrics, SandboxModificationBuilder,
+    RootDiskBuilder, SandboxBuilder, SandboxHandle, SandboxMetrics, SandboxModificationBuilder,
     SandboxModificationPatch, SandboxStatus, SandboxStopResult, SecretBuilder,
     SecretModificationPatch, SecretSource, SecurityProfile, StatVirtualization,
 };
@@ -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
@@ -452,29 +477,44 @@ impl Sandbox {
         Ok(SbHandle::from_inner(handle))
     }
 
-    /// All sandboxes as controllable handles.
-    fn list() -> Result<RArray, Error> {
-        let handles = block_on(microsandbox::Sandbox::list()).map_err(error::to_ruby)?;
+    /// Convert one `SandboxPage` into a `{ "sandboxes" => [SbHandle], "next_cursor" => String|nil }`
+    /// Ruby Hash (v0.6.8 paginated listing contract).
+    fn page_to_hash(page: microsandbox::sandbox::SandboxPage) -> Result<RHash, Error> {
         let arr = ruby().ary_new();
-        for h in handles {
+        for h in page.sandboxes {
             arr.push(SbHandle::from_inner(h))?;
         }
-        Ok(arr)
-    }
-
-    /// Sandboxes filtered by required `key=value` labels (AND-matched), as
-    /// controllable handles. `opts` carries a string→string `labels` map.
-    fn list_with(opts: RHash) -> Result<RArray, Error> {
-        let mut filter = SandboxFilter::new();
-        for (k, v) in conv::opt_string_map(opts, "labels")? {
-            filter = filter.label(k, v);
-        }
-        let handles = block_on(microsandbox::Sandbox::list_with(filter)).map_err(error::to_ruby)?;
-        let arr = ruby().ary_new();
-        for h in handles {
-            arr.push(SbHandle::from_inner(h))?;
-        }
-        Ok(arr)
+        let hash = ruby().hash_new();
+        hash.aset("sandboxes", arr)?;
+        hash.aset("next_cursor", page.next_cursor)?;
+        Ok(hash)
+    }
+
+    /// First page of sandboxes (default page size), as a page Hash of
+    /// controllable handles.
+    fn list() -> Result<RHash, Error> {
+        let page = block_on(microsandbox::Sandbox::list()).map_err(error::to_ruby)?;
+        Self::page_to_hash(page)
+    }
+
+    /// One configured page of sandboxes as a page Hash. `opts` carries an
+    /// optional string→string `labels` map (AND-matched), an optional `limit`
+    /// (1..=100) and an optional opaque `cursor` from a previous page.
+    fn list_with(opts: RHash) -> Result<RHash, Error> {
+        let labels = conv::opt_string_map(opts, "labels")?;
+        let limit = conv::opt_u32(opts, "limit")?;
+        let cursor = conv::opt_string(opts, "cursor")?;
+        let page = block_on(microsandbox::Sandbox::list_with(move |mut b| {
+            if let Some(limit) = limit {
+                b = b.limit(limit);
+            }
+            if let Some(cursor) = cursor {
+                b = b.cursor(cursor);
+            }
+            b.labels(labels)
+        }))
+        .map_err(error::to_ruby)?;
+        Self::page_to_hash(page)
     }
 
     /// Remove a (stopped) sandbox by name.
@@ -1258,12 +1298,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 +1326,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,18 +1379,105 @@ 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")?,
+    })
+}
+
 fn action_from_str(s: &str) -> Result<Action, Error> {
     match s {
         "allow" => Ok(Action::Allow),
@@ -2143,17 +2291,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 +2481,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/ext/microsandbox/src/volume.rs

@@ -9,7 +9,6 @@ use magnus::{function, method, prelude::*, Error, RArray, RHash, RModule, RStrin
 use microsandbox::volume::VolumeHandle;
 use microsandbox::Backend;
 
-use crate::backend::local_backend;
 use crate::conv;
 use crate::error;
 use crate::runtime::{block_on, ruby};
@@ -108,10 +107,13 @@ pub struct VolumeFs {
 }
 
 impl VolumeFs {
-    /// Resolve the (local) backend once and bind it to `name`.
+    /// Resolve the ambient backend once and bind it to `name`. As of v0.6.8
+    /// every `VolumeFs` op dispatches through the backend's `VolumeBackend`
+    /// trait, which yields precise per-operation `Unsupported` errors on
+    /// backends that can't serve it — no local-only downcast needed here.
     fn for_volume(name: String) -> Result<VolumeFs, Error> {
         Ok(VolumeFs {
-            backend: local_backend().map_err(error::to_ruby)?,
+            backend: microsandbox::default_backend(),
             name,
         })
     }

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
@@ -86,4 +90,16 @@ module Microsandbox
   # cloud backend) is distinct from `UnsupportedOperationError` above.
   define_error(:CloudHttpError, "cloud-http")
   define_error(:UnsupportedError, "unsupported")
+
+  # As of runtime v0.6.8 the core keys Unsupported errors by a structured
+  # (operation, reason) pair. The native layer renders both into the message
+  # ("sandbox.kill is not supported by this backend: ...") and also attaches
+  # them here as structured attributes, mirroring the Python SDK's
+  # `UnsupportedError.operation` / `.hint`.
+  class UnsupportedError
+    # @return [String, nil] the rejected API in Ruby rendering, e.g. "sandbox.kill"
+    attr_reader :operation
+    # @return [String, nil] why it was rejected / what to use instead
+    attr_reader :hint
+  end
 end