microsandbox-rb 0.11.0 → 0.13.0

data/ext/microsandbox/src/sandbox.rs

@@ -18,11 +18,11 @@ use microsandbox::logs::{
     LogCursor, LogEntry, LogOptions, LogSource, LogStreamOptions, LogStreamStart,
 };
 use microsandbox::sandbox::{
-    AttachOptionsBuilder, DiskImageFormat, EnvVar, FsEntry, FsEntryKind, FsMetadata,
+    AttachOptionsBuilder, DiskImageFormat, EnvVar, FlatClone, FsEntry, FsEntryKind, FsMetadata,
     HostPermissions, Patch, PullPolicy, PullProgress, PullProgressHandle, RlimitResource,
-    RootDiskBuilder, SandboxBuilder, SandboxFilter, SandboxHandle, SandboxMetrics,
-    SandboxModificationBuilder, SandboxModificationPatch, SandboxStatus, SandboxStopResult,
-    SecretBuilder, SecretModificationPatch, SecretSource, SecurityProfile, StatVirtualization,
+    RootDiskBuilder, SandboxBuilder, SandboxHandle, SandboxMetrics, SandboxModificationBuilder,
+    SandboxModificationPatch, SandboxStatus, SandboxStopResult, SecretBuilder,
+    SecretModificationPatch, SecretSource, SecurityProfile, StatVirtualization,
 };
 use microsandbox::LogLevel;
 use microsandbox::MicrosandboxResult;
@@ -128,13 +128,41 @@ impl Sandbox {
         for (k, v) in conv::opt_string_map(opts, "scripts")? {
             b = b.script(k, v);
         }
-        let entrypoint = conv::opt_string_vec(opts, "entrypoint")?;
-        if !entrypoint.is_empty() {
+        // entrypoint/cmd: presence-keyed, NOT non-emptiness-keyed — an
+        // explicitly *empty* array is meaningful for both (it clears the
+        // image's ENTRYPOINT / CMD, blocking the image-config merge), exactly
+        // like the Python binding. Keying on non-emptiness silently resurrects
+        // the image ENTRYPOINT and runs the wrong command under
+        // `exec_default`/`attach_default`.
+        if let Some(entrypoint) = conv::opt::<Vec<String>>(opts, "entrypoint")? {
             b = b.entrypoint(entrypoint);
         }
+        if let Some(cmd) = conv::opt::<Vec<String>>(opts, "cmd")? {
+            b = b.cmd(cmd);
+        }
         for (host, guest) in conv::opt_port_map(opts, "ports")? {
             b = b.port(host, guest);
         }
+        // vsock: host Unix sockets exposed on guest-to-host vsock ports
+        // (v0.6.9). Each route is normalized by the Ruby layer to a
+        // string-keyed Hash {host_socket:, port:, socket_type: "stream"|"dgram"}.
+        for route in conv::opt_hash_vec(opts, "vsock")? {
+            let Some(host_socket) = conv::opt_string(route, "host_socket")? else {
+                return Err(error::base_error("vsock route requires host_socket:"));
+            };
+            let Some(port) = conv::opt_u32(route, "port")? else {
+                return Err(error::base_error("vsock route requires port:"));
+            };
+            match conv::opt_string(route, "socket_type")?.as_deref() {
+                None | Some("stream") => b = b.vsock(host_socket, port),
+                Some("dgram") => b = b.vsock_dgram(host_socket, port),
+                Some(other) => {
+                    return Err(error::base_error(format!(
+                        "unknown vsock socket_type {other:?} (expected stream/dgram)"
+                    )))
+                }
+            }
+        }
         // volumes: each mount is normalized by the Ruby layer to a string-keyed
         // Hash — guest (req), kind ("bind"/"named"/"tmpfs"/"disk"), source
         // (bind/named/disk), size_mib (tmpfs/disk), format + fstype (disk),
@@ -413,6 +441,28 @@ impl Sandbox {
                 n
             });
         }
+        // rate_limiter: per-sandbox egress/ingress token-bucket limits
+        // (v0.6.9). The Ruby layer normalizes the option to a string-keyed
+        // Hash {egress:, ingress:} of {bandwidth:, ops:} buckets
+        // {size:, refill_time_ms:, one_time_burst:}; mirrors the Python SDK's
+        // `NetworkRateLimiter`. Applied via the network builder, accumulating
+        // on top of any configuration above.
+        if let Some(spec) = conv::opt::<RHash>(opts, "rate_limiter")?
+            .map(parse_rate_limiter)
+            .transpose()?
+        {
+            b = b.network(move |n| {
+                n.rate_limiter(move |mut r| {
+                    if let Some(egress) = spec.egress {
+                        r = r.egress(move |rl| egress.apply(rl));
+                    }
+                    if let Some(ingress) = spec.ingress {
+                        r = r.ingress(move |rl| ingress.apply(rl));
+                    }
+                    r
+                })
+            });
+        }
         // init: hand guest PID 1 to an init system. The Ruby layer normalizes
         // `init:` to a Hash { cmd:, args?:, env?: }. `init_with` with empty
         // args/env builds the same HandoffInit as the plain `init(cmd)`, so route
@@ -477,29 +527,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)?;
-        let arr = ruby().ary_new();
-        for h in handles {
-            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)?;
+    /// 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)
+        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.
@@ -545,6 +610,29 @@ impl Sandbox {
         Ok(ExecHandle::from_core(handle))
     }
 
+    /// Run the image's resolved OCI ENTRYPOINT and CMD (the default workload,
+    /// v0.6.9) and wait for completion. `create` is strictly boot-only, so this
+    /// is how the image's own command is executed. `opts` matches `exec` minus
+    /// the command: cwd, user, env, timeout, tty, stdin, rlimits. Raises
+    /// NoDefaultCommandError when the image resolves no executable command.
+    fn exec_default(&self, opts: RHash) -> Result<RHash, Error> {
+        let parsed = ExecOpts::parse(Vec::new(), opts)?;
+        let output = block_on(self.inner.exec_default_with(move |b| parsed.apply(b)))
+            .map_err(error::to_ruby)?;
+        exec_output_to_hash(output)
+    }
+
+    /// Streaming default-workload execution. Returns an ExecHandle.
+    fn exec_default_stream(&self, opts: RHash) -> Result<ExecHandle, Error> {
+        let parsed = ExecOpts::parse(Vec::new(), opts)?;
+        let handle = block_on(
+            self.inner
+                .exec_default_stream_with(move |b| parsed.apply(b)),
+        )
+        .map_err(error::to_ruby)?;
+        Ok(ExecHandle::from_core(handle))
+    }
+
     /// Streaming shell execution.
     fn shell_stream(&self, script: String, opts: RHash) -> Result<ExecHandle, Error> {
         let parsed = ExecOpts::parse(Vec::new(), opts)?;
@@ -838,6 +926,14 @@ impl Sandbox {
     fn attach_shell(&self) -> Result<i32, Error> {
         block_on(self.inner.attach_shell()).map_err(error::to_ruby)
     }
+
+    /// Attach an interactive terminal to the image's resolved OCI ENTRYPOINT
+    /// and CMD (the default workload, v0.6.9); returns its exit code. `opts`:
+    /// cwd, user, env, detach_keys, rlimits.
+    fn attach_default(&self, opts: RHash) -> Result<i32, Error> {
+        let parsed = AttachOpts::parse(Vec::new(), opts)?;
+        block_on(self.inner.attach_default_with(move |b| parsed.apply(b))).map_err(error::to_ruby)
+    }
 }
 
 //--------------------------------------------------------------------------------------------------
@@ -1253,6 +1349,83 @@ fn parse_dns(d: RHash) -> Result<DnsSpec, Error> {
     })
 }
 
+/// One token bucket of the `rate_limiter` create option (v0.6.9):
+/// `(size, refill_time_ms, one_time_burst)`. Size is bytes for bandwidth
+/// buckets, frames for ops buckets.
+type TokenBucketSpec = (u64, u64, u64);
+
+/// One direction of the `rate_limiter` create option.
+struct RateLimiterSpec {
+    bandwidth: Option<TokenBucketSpec>,
+    ops: Option<TokenBucketSpec>,
+}
+
+/// Parsed `rate_limiter` create option (v0.6.9, mirrors the Python SDK's
+/// `NetworkRateLimiter`): per-direction bandwidth/ops token buckets. Parsed up
+/// front because the network builder closure cannot return an error.
+struct NetworkRateLimiterSpec {
+    egress: Option<RateLimiterSpec>,
+    ingress: Option<RateLimiterSpec>,
+}
+
+fn parse_token_bucket(b: RHash, dir: &str, dim: &str) -> Result<TokenBucketSpec, Error> {
+    let Some(size) = conv::opt::<u64>(b, "size")? else {
+        return Err(error::base_error(format!(
+            "rate_limiter {dir} {dim} bucket requires size:"
+        )));
+    };
+    let Some(refill) = conv::opt::<u64>(b, "refill_time_ms")? else {
+        return Err(error::base_error(format!(
+            "rate_limiter {dir} {dim} bucket requires refill_time_ms:"
+        )));
+    };
+    let burst = conv::opt::<u64>(b, "one_time_burst")?.unwrap_or(0);
+    Ok((size, refill, burst))
+}
+
+fn parse_rate_limiter_direction(h: RHash, dir: &str) -> Result<RateLimiterSpec, Error> {
+    Ok(RateLimiterSpec {
+        bandwidth: conv::opt::<RHash>(h, "bandwidth")?
+            .map(|b| parse_token_bucket(b, dir, "bandwidth"))
+            .transpose()?,
+        ops: conv::opt::<RHash>(h, "ops")?
+            .map(|b| parse_token_bucket(b, dir, "ops"))
+            .transpose()?,
+    })
+}
+
+fn parse_rate_limiter(h: RHash) -> Result<NetworkRateLimiterSpec, Error> {
+    Ok(NetworkRateLimiterSpec {
+        egress: conv::opt::<RHash>(h, "egress")?
+            .map(|d| parse_rate_limiter_direction(d, "egress"))
+            .transpose()?,
+        ingress: conv::opt::<RHash>(h, "ingress")?
+            .map(|d| parse_rate_limiter_direction(d, "ingress"))
+            .transpose()?,
+    })
+}
+
+impl RateLimiterSpec {
+    fn apply(
+        self,
+        mut rl: microsandbox_network::builder::RateLimiterBuilder,
+    ) -> microsandbox_network::builder::RateLimiterBuilder {
+        if let Some((size, refill_ms, burst)) = self.bandwidth {
+            rl = rl.bandwidth(size, Duration::from_millis(refill_ms));
+            if burst > 0 {
+                rl = rl.bandwidth_burst(burst);
+            }
+        }
+        if let Some((count, refill_ms, burst)) = self.ops {
+            rl = rl.ops(count, Duration::from_millis(refill_ms));
+            if burst > 0 {
+                rl = rl.ops_burst(burst);
+            }
+        }
+        rl
+    }
+}
+
 struct TlsSpec {
     bypass: Vec<String>,
     verify_upstream: Option<bool>,
@@ -1394,12 +1567,14 @@ struct RootDiskSpec {
     size_mib: Option<u32>,
     format: Option<DiskImageFormat>,
     fstype: Option<String>,
+    clone: Option<FlatClone>,
 }
 
 enum RootDiskKindSpec {
     Managed,
     Tmpfs,
     Disk(String),
+    Flat,
 }
 
 impl RootDiskSpec {
@@ -1408,6 +1583,7 @@ impl RootDiskSpec {
             RootDiskKindSpec::Managed => {}
             RootDiskKindSpec::Tmpfs => d = d.tmpfs(),
             RootDiskKindSpec::Disk(path) => d = d.disk_image(path),
+            RootDiskKindSpec::Flat => d = d.flat(),
         }
         if let Some(mib) = self.size_mib {
             d = d.size(mib);
@@ -1418,6 +1594,9 @@ impl RootDiskSpec {
         if let Some(ft) = self.fstype {
             d = d.fstype(ft);
         }
+        if let Some(c) = self.clone {
+            d = d.clone_strategy(c);
+        }
         d
     }
 }
@@ -1429,12 +1608,13 @@ fn parse_root_disk(v: Value) -> Result<RootDiskSpec, Error> {
             size_mib: Some(mib),
             format: None,
             fstype: None,
+            clone: 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)",
+             (use Microsandbox::RootDisk.managed/tmpfs/disk/flat)",
         ));
     };
     let kind = match conv::opt_string(h, "kind")?.as_deref() {
@@ -1446,20 +1626,35 @@ fn parse_root_disk(v: Value) -> Result<RootDiskSpec, Error> {
             };
             RootDiskKindSpec::Disk(path)
         }
+        Some("flat") => RootDiskKindSpec::Flat,
         Some(other) => {
             return Err(error::base_error(format!(
-                "unknown root_disk kind {other:?} (expected managed/tmpfs/disk)"
+                "unknown root_disk kind {other:?} (expected managed/tmpfs/disk/flat)"
             )))
         }
     };
     let format = conv::opt_string(h, "format")?
         .map(|f| disk_format_from_str(&f))
         .transpose()?;
+    // clone: flat-only private-disk clone strategy (v0.6.9). Validated here
+    // (unknown values error) but kind cross-validation stays in the core
+    // builder, matching the other fields.
+    let clone = conv::opt_string(h, "clone")?
+        .map(|c| match c.as_str() {
+            "auto" => Ok(FlatClone::Auto),
+            "copy" => Ok(FlatClone::Copy),
+            "reflink" => Ok(FlatClone::Reflink),
+            other => Err(error::base_error(format!(
+                "unknown root_disk clone strategy {other:?} (expected auto/copy/reflink)"
+            ))),
+        })
+        .transpose()?;
     Ok(RootDiskSpec {
         kind,
         size_mib: conv::opt_u32(h, "size_mib")?,
         format,
         fstype: conv::opt_string(h, "fstype")?,
+        clone,
     })
 }
 
@@ -1954,9 +2149,9 @@ fn run_modify(builder: SandboxModificationBuilder, opts: RHash) -> Result<String
 
 /// Build the canonical `SandboxModificationPatch` from the modify Hash. Env and
 /// label pairs are sorted so repeated calls with the same arguments produce the
-/// same patch (and plan) ordering, mirroring the Python binding. `oci_upper_size`
-/// is deliberately not surfaced (CLI-only upstream; the Python/Node SDKs omit it
-/// too), so it stays unset via `..Default::default()`.
+/// same patch (and plan) ordering, mirroring the Python binding. As of v0.6.9
+/// every patch field is surfaced (`root_disk_size` covers what the deprecated
+/// CLI-only `oci_upper_size` used to mean).
 fn build_modify_patch(opts: RHash) -> Result<SandboxModificationPatch, Error> {
     let mut env_pairs = conv::opt_string_map(opts, "env")?;
     env_pairs.sort();
@@ -1968,6 +2163,10 @@ fn build_modify_patch(opts: RHash) -> Result<SandboxModificationPatch, Error> {
         max_cpus: conv::opt_u8(opts, "max_cpus")?,
         memory_mib: conv::opt_u32(opts, "memory")?,
         max_memory_mib: conv::opt_u32(opts, "max_memory")?,
+        // v0.6.9 ("root disk resizing in every SDK"): grow the sandbox-owned
+        // layered upper or flat root disk. Restart/next-start semantics and
+        // backing-specific limits are enforced by the core.
+        root_disk_size_mib: conv::opt_u32(opts, "root_disk_size")?,
         env: env_pairs
             .into_iter()
             .map(|(k, v)| EnvVar::new(k, v))
@@ -1978,7 +2177,6 @@ fn build_modify_patch(opts: RHash) -> Result<SandboxModificationPatch, Error> {
         workdir: conv::opt_string(opts, "workdir")?,
         secrets: parse_modify_secrets(opts)?,
         secrets_remove: conv::opt_string_vec(opts, "remove_secrets")?,
-        ..Default::default()
     })
 }
 
@@ -2407,6 +2605,11 @@ pub fn define(ruby: &Ruby, native: &RModule) -> Result<(), Error> {
     class.define_method("shell", method!(Sandbox::shell, 2))?;
     class.define_method("exec_stream", method!(Sandbox::exec_stream, 3))?;
     class.define_method("shell_stream", method!(Sandbox::shell_stream, 2))?;
+    class.define_method("exec_default", method!(Sandbox::exec_default, 1))?;
+    class.define_method(
+        "exec_default_stream",
+        method!(Sandbox::exec_default_stream, 1),
+    )?;
     class.define_method("stop", method!(Sandbox::stop, 0))?;
     class.define_method("stop_and_wait", method!(Sandbox::stop_and_wait, 0))?;
     class.define_method("kill", method!(Sandbox::kill, 0))?;
@@ -2446,6 +2649,7 @@ pub fn define(ruby: &Ruby, native: &RModule) -> Result<(), Error> {
     )?;
 
     class.define_method("attach", method!(Sandbox::attach, 3))?;
+    class.define_method("attach_default", method!(Sandbox::attach_default, 1))?;
     class.define_method("attach_shell", method!(Sandbox::attach_shell, 0))?;
 
     let handle = native.define_class("SandboxHandle", ruby.class_object())?;

data/ext/microsandbox/src/snapshot.rs

@@ -171,9 +171,10 @@ 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}. Schema-1
-/// descriptors always record integrity, so the status is always "verified"
-/// on success (mismatches raise SnapshotIntegrityError instead).
+/// {digest, path, upper_status, upper_algorithm, upper_digest}. As of v0.6.9
+/// payload integrity is opt-in at create time: opted-in snapshots verify to
+/// "verified" (mismatches raise SnapshotIntegrityError), snapshots without
+/// recorded integrity report "not_recorded" with no algorithm/digest keys.
 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)?;
@@ -248,6 +249,12 @@ fn verify_report_to_hash(report: &SnapshotVerifyReport) -> RHash {
             let _ = hash.aset("upper_algorithm", algorithm.clone());
             let _ = hash.aset("upper_digest", digest.clone());
         }
+        // v0.6.9 (#1346): payload integrity is opt-in at create time
+        // (`record_integrity`); a snapshot without it verifies structurally
+        // but has no content digest to check.
+        UpperVerifyStatus::NotRecorded => {
+            let _ = hash.aset("upper_status", "not_recorded");
+        }
     }
     hash
 }

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};
@@ -19,6 +18,7 @@ fn handle_to_hash(h: &VolumeHandle) -> RHash {
     let hash = ruby().hash_new();
     let _ = hash.aset("name", h.name().to_string());
     let _ = hash.aset("kind", h.kind().as_str().to_string());
+    let _ = hash.aset("default", h.is_default());
     let _ = hash.aset("quota_mib", h.quota_mib());
     let _ = hash.aset("used_bytes", h.used_bytes());
     let _ = hash.aset("capacity_bytes", h.capacity_bytes());
@@ -84,6 +84,13 @@ fn get(name: String) -> Result<RHash, Error> {
     Ok(handle_to_hash(&handle))
 }
 
+/// The backend's default volume (v0.6.9). Cloud-backend only — the local
+/// backend rejects it (Unsupported) to avoid accidental host access.
+fn get_default() -> Result<RHash, Error> {
+    let handle = block_on(microsandbox::Volume::get_default()).map_err(error::to_ruby)?;
+    Ok(handle_to_hash(&handle))
+}
+
 fn list() -> Result<RArray, Error> {
     let handles = block_on(microsandbox::Volume::list()).map_err(error::to_ruby)?;
     let arr = ruby().ary_new();
@@ -108,10 +115,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,
         })
     }
@@ -194,6 +204,7 @@ pub fn define(ruby: &Ruby, native: &RModule) -> Result<(), Error> {
     let class = native.define_class("Volume", ruby.class_object())?;
     class.define_singleton_method("create", function!(create, 2))?;
     class.define_singleton_method("get", function!(get, 1))?;
+    class.define_singleton_method("get_default", function!(get_default, 0))?;
     class.define_singleton_method("list", function!(list, 0))?;
     class.define_singleton_method("remove", function!(remove, 1))?;
     class.define_singleton_method("fs", function!(fs, 1))?;

data/lib/microsandbox/backend_info.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Microsandbox
+  # Secret-safe description of the active default backend, from
+  # {Microsandbox.default_backend_info} (runtime v0.6.9). Describes what
+  # selected the backend and where it points — never its credential: the API
+  # key is deliberately absent.
+  class BackendInfo
+    # @return [String, nil] effective cloud API endpoint (nil for local)
+    attr_reader :api_url
+    # @return [String, nil] the selected profile name, when a profile chose
+    #   the backend
+    attr_reader :profile
+
+    def initialize(data)
+      @kind = data["kind"]
+      @api_url = data["api_url"]
+      @source = data["source"]
+      @profile = data["profile"]
+    end
+
+    # @return [Symbol] :local or :cloud
+    def kind
+      @kind.to_sym
+    end
+
+    # What selected this backend: `:programmatic` (an SDK setter),
+    # `:MSB_BACKEND` / `:MSB_API_KEY` / `:MSB_PROFILE` (environment),
+    # `:profile` (an explicit SDK profile constructor), `:active_profile`
+    # (the SDK config file), or `:default` (the final local fallback).
+    # @return [Symbol]
+    def source
+      @source.to_sym
+    end
+
+    def local? = kind == :local
+
+    def cloud? = kind == :cloud
+
+    def inspect
+      "#<Microsandbox::BackendInfo kind=#{@kind} source=#{@source.inspect}" \
+        "#{" api_url=#{@api_url.inspect}" if @api_url}" \
+        "#{" profile=#{@profile.inspect}" if @profile}>"
+    end
+  end
+end

data/lib/microsandbox/errors.rb

@@ -39,6 +39,10 @@ module Microsandbox
   # Execution errors --------------------------------------------------------
   define_error(:ExecTimeoutError, "exec-timeout")
   define_error(:ExecFailedError, "exec-failed")
+  # v0.6.9: `exec_default`/`attach_default` on an image whose resolved
+  # ENTRYPOINT+CMD provide no executable command. Mirrors the Python SDK's
+  # NoDefaultCommandError.
+  define_error(:NoDefaultCommandError, "no-default-command")
 
   # Filesystem errors -------------------------------------------------------
   define_error(:FilesystemError, "filesystem-error")
@@ -90,4 +94,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

data/lib/microsandbox/root_disk.rb

@@ -13,12 +13,18 @@ module Microsandbox
   # - {disk} — a user-supplied disk image attached writable as the upper. The
   #   file determines its own size; the runtime never creates, resizes, or
   #   deletes it. Cannot be snapshotted or patched.
+  # - {flat} — a single complete ext4 root disk materialized directly from the
+  #   OCI image (runtime v0.6.9), skipping the layered EROFS+OverlayFS stack at
+  #   runtime. Content-addressed and cached across sandboxes; resizable.
+  #   Pre-materialize with `msb pull IMAGE --materialize flat`.
   #
   # @example
   #   Sandbox.create("worker", image: "python", root_disk: 8192)
   #   Sandbox.create("ci", image: "python", root_disk: Microsandbox::RootDisk.tmpfs(2048))
   #   Sandbox.create("warm", image: "python",
   #     root_disk: Microsandbox::RootDisk.disk("./scratch.img", fstype: "ext4"))
+  #   Sandbox.create("fast", image: "python",
+  #     root_disk: Microsandbox::RootDisk.flat(8192, clone: :reflink))
   #
   # Mirrors the `RootDisk` factory in the official Python/Node/Go SDKs.
   module RootDisk
@@ -54,5 +60,23 @@ module Microsandbox
       h["fstype"] = fstype.to_s if fstype
       h
     end
+
+    # A complete, microsandbox-owned root disk materialized from the OCI image
+    # (runtime v0.6.9).
+    # @param size_mib [Integer, nil] resizable ext4 size in MiB
+    # @param fstype [String, nil] generated filesystem type (default "ext4")
+    # @param clone [Symbol, String, nil] how each sandbox's private disk is
+    #   created from the cached artifact: `:auto` (CoW clone when the host
+    #   filesystem supports it, else a sparse copy — the default), `:copy`
+    #   (always an independent sparse copy), or `:reflink` (require a CoW
+    #   clone; fail where unsupported)
+    # @return [Hash]
+    def flat(size_mib = nil, fstype: nil, clone: nil)
+      h = {"kind" => "flat"}
+      h["size_mib"] = Integer(size_mib) if size_mib
+      h["fstype"] = fstype.to_s if fstype
+      h["clone"] = clone.to_s if clone
+      h
+    end
   end
 end