microsandbox-rb 0.9.2 → 0.11.0

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

data/lib/microsandbox/modification.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Microsandbox
+  # The result of {Sandbox#ping} / {SandboxHandle#ping}: a lightweight health
+  # check that confirms the guest agent is reachable without refreshing the
+  # sandbox idle timer. Mirrors the official SDKs' `SandboxPingResult`.
+  #
+  # The native layer reports latency as seconds; {#latency} is the canonical
+  # value and {#latency_ms} the convenience the Python/Node SDKs expose.
+  class PingResult
+    # @return [String] the sandbox name that was pinged
+    attr_reader :name
+    # @return [Float] round-trip latency in seconds
+    attr_reader :latency
+
+    def initialize(data)
+      @name = data["name"]
+      @latency = data["latency_secs"]
+    end
+
+    # @return [Float] round-trip latency in milliseconds
+    def latency_ms
+      @latency * 1000.0
+    end
+
+    def inspect
+      "#<Microsandbox::PingResult name=#{@name.inspect} latency_ms=#{format("%.3f", latency_ms)}>"
+    end
+  end
+
+  # The result of {Sandbox#touch} / {SandboxHandle#touch}: an explicit refresh of
+  # the sandbox idle-activity timer. Mirrors the official SDKs' `SandboxTouchResult`.
+  class TouchResult
+    # @return [String] the sandbox name that was touched
+    attr_reader :name
+    # @return [Integer] the agent activity sequence after this touch was recorded
+    attr_reader :activity_seq
+
+    def initialize(data)
+      @name = data["name"]
+      @activity_seq = data["activity_seq"]
+    end
+
+    def inspect
+      "#<Microsandbox::TouchResult name=#{@name.inspect} activity_seq=#{@activity_seq}>"
+    end
+  end
+
+  # The plan produced by {Sandbox#modify} / {SandboxHandle#modify}: the classified
+  # set of changes a modification requested, and (for a non-dry-run apply) whether
+  # they were applied plus any live-resize convergence outcomes. Mirrors the
+  # official SDKs' `SandboxModificationPlan`.
+  #
+  # The nested collections ({#changes}, {#conflicts}, {#warnings},
+  # {#resize_status}) are frozen Arrays of frozen, symbol-keyed Hashes carrying
+  # the canonical snake_case fields verbatim (e.g. a config change is
+  # `{ kind: "config", field:, change:, before:, after:, disposition:, reason: }`;
+  # a secret change adds `name:`, `before_ref:`, `after_ref:`, `allow_hosts:`).
+  # Enum values stay as the runtime's strings (e.g. a `disposition` of
+  # `"next start"`, a `state` of `"guest-refused"`).
+  class ModificationPlan
+    # @return [String] the sandbox the plan applies to
+    attr_reader :sandbox
+    # @return [String] the sandbox status used to classify the changes
+    attr_reader :status
+    # @return [Symbol] :no_restart, :next_start, or :restart
+    attr_reader :policy
+    # @return [Array<Hash>] the planned changes (config and secret)
+    attr_reader :changes
+    # @return [Array<Hash>] conflicts that must be resolved before applying
+    attr_reader :conflicts
+    # @return [Array<Hash>] non-fatal warnings about the patch
+    attr_reader :warnings
+    # @return [Array<Hash>] live resource-resize outcomes (populated by an apply)
+    attr_reader :resize_status
+
+    def initialize(data)
+      @sandbox = data["sandbox"]
+      @status = data["status"]
+      @applied = data["applied"]
+      @policy = data["policy"]&.to_sym
+      @changes = freeze_items(data["changes"])
+      @conflicts = freeze_items(data["conflicts"])
+      @warnings = freeze_items(data["warnings"])
+      @resize_status = freeze_items(data["resize_status"])
+    end
+
+    # @return [Boolean] whether the changes were applied (false for a dry run)
+    def applied?
+      @applied
+    end
+
+    def inspect
+      "#<Microsandbox::ModificationPlan sandbox=#{@sandbox.inspect} applied=#{@applied} " \
+        "policy=#{@policy} changes=#{@changes.size} conflicts=#{@conflicts.size} " \
+        "warnings=#{@warnings.size}>"
+    end
+
+    private
+
+    # Convert a JSON array of plan entries (string-keyed Hashes) into a frozen
+    # Array of frozen, symbol-keyed Hashes. The entries are shallow (all values
+    # are scalars or string arrays), so a single `transform_keys` suffices.
+    def freeze_items(items)
+      Array(items).map { |item| item.transform_keys(&:to_sym).freeze }.freeze
+    end
+  end
+end

data/lib/microsandbox/network.rb

@@ -62,6 +62,24 @@ module Microsandbox
       build("deny", destination, direction, protocol, protocols, port, ports)
     end
 
+    # Allow plain DNS (UDP/53 and TCP/53) to the sandbox gateway — the rule
+    # the composable profiles prepend automatically. Use it in custom policies
+    # that need name resolution. Expands to the same rule as the core's
+    # `Rule::allow_dns` (egress → group :host, udp+tcp, port 53).
+    # @return [Hash]
+    def allow_dns
+      {"action" => "allow", "direction" => "egress",
+       "destination_kind" => "group", "destination" => "host",
+       "protocols" => %w[udp tcp], "ports" => ["53"]}
+    end
+
+    # Deny plain DNS to the sandbox gateway — the deny counterpart of
+    # {allow_dns}, useful as an override placed before profile-generated rules.
+    # @return [Hash]
+    def deny_dns
+      allow_dns.merge("action" => "deny")
+    end
+
     # @api private
     def build(action, destination, direction, protocol, protocols, port, ports)
       rule = {"action" => action, "direction" => direction.to_s}
@@ -84,20 +102,29 @@ module Microsandbox
     end
   end
 
-  # A sandbox network policy: a preset, or a custom set of allow/deny {Rule}s
-  # with per-direction default actions and bulk domain denials.
+  # A sandbox network policy: composed profiles, a terminal preset, or a custom
+  # set of allow/deny {Rule}s with per-direction default actions and bulk
+  # domain denials.
   #
-  # Pass to {Sandbox.create} via `network:` — either a {NetworkPolicy}, a preset
-  # name (String/Symbol), or a plain Hash with the same keys as {custom}.
+  # Pass to {Sandbox.create} via `network:` — a {NetworkPolicy}, an Array of
+  # profile names (`[:public, :host]`), a single profile or preset name
+  # (String/Symbol), or a plain Hash with the same keys as {custom}.
   #
-  # @example presets
-  #   Sandbox.create("b", image: "alpine", network: NetworkPolicy.public_only)
+  # Profiles (runtime v0.6.7) compose: `:public` (public internet), `:private`
+  # (LAN/private ranges), `:host` (the host machine/gateway). Any non-empty
+  # combination automatically allows gateway DNS. The default policy — public
+  # internet only — equals `from_profiles(:public)`.
+  #
+  # @example profiles
+  #   Sandbox.create("b", image: "alpine", network: [:public, :private])
   #   Sandbox.create("b", image: "alpine", network: :none)
+  #   Sandbox.create("b", image: "alpine", network: NetworkPolicy.from_profiles(:host))
   #
   # @example custom
   #   policy = Microsandbox::NetworkPolicy.custom(
   #     default_egress: :deny,
   #     rules: [
+  #       Microsandbox::Rule.allow_dns,
   #       Microsandbox::Rule.allow(destination: "api.openai.com", protocol: :tcp, port: "443"),
   #     ],
   #     deny_domain_suffixes: [".ads.example"],
@@ -106,18 +133,47 @@ module Microsandbox
   #
   # Mirrors `NetworkPolicy` / `Network` in the official Python/Node/Go SDKs.
   class NetworkPolicy
-    # Canonical preset names keyed by every accepted alias.
+    # Composable profile names (runtime v0.6.7).
+    PROFILES = %w[public private host].freeze
+
+    # Canonical preset names keyed by every accepted alias. Only the terminal
+    # presets survive v0.6.7; the removed ones get migration guidance in
+    # {canonical_preset}.
     PRESET_ALIASES = {
       "none" => "none", "disabled" => "none", "disable" => "none", "airgapped" => "none",
-      "public" => "public_only", "public_only" => "public_only", "public-only" => "public_only",
-      "default" => "public_only",
-      "all" => "allow_all", "allow_all" => "allow_all", "allow-all" => "allow_all",
-      "non_local" => "non_local", "non-local" => "non_local", "nonlocal" => "non_local"
+      "all" => "allow_all", "allow_all" => "allow_all", "allow-all" => "allow_all"
+    }.freeze
+
+    # Removed v0.6.6 preset spellings → the exact profile replacement, used to
+    # build actionable migration errors. (`public_only` expanded to precisely
+    # `from_profiles(:public)`, `non_local` to `from_profiles(:public, :private)` —
+    # the replacements are rule-for-rule equivalent.)
+    REMOVED_PRESETS = {
+      "public_only" => "network: [:public] (or NetworkPolicy.from_profiles(:public); " \
+        "this is still the default policy)",
+      "public-only" => "network: [:public]",
+      "non_local" => "network: [:public, :private] " \
+        "(or NetworkPolicy.from_profiles(:public, :private))",
+      "non-local" => "network: [:public, :private]",
+      "nonlocal" => "network: [:public, :private]"
     }.freeze
 
     class << self
-      # @return [NetworkPolicy] allow only public internet (the default)
-      def public_only = preset("public_only")
+      # Compose a policy from network profiles (`:public`, `:private`, `:host`).
+      # Order and duplicates don't matter — the runtime expands the set into a
+      # canonical rule list plus a gateway-DNS allow. An empty set is a valid
+      # deny-egress/allow-ingress policy with no rules (and no DNS).
+      # @return [NetworkPolicy]
+      def from_profiles(*profiles)
+        list = normalize_profiles(profiles)
+        if list.empty?
+          # Same semantics as the runtime's from_profiles([]) — expressed as an
+          # explicit empty custom policy so the wire needs no empty-array case.
+          custom(default_egress: :deny, default_ingress: :allow, rules: [])
+        else
+          new("profiles" => list)
+        end
+      end
 
       # @return [NetworkPolicy] block all network access
       def none = preset("none")
@@ -125,19 +181,17 @@ module Microsandbox
       # @return [NetworkPolicy] permit all traffic
       def allow_all = preset("allow_all")
 
-      # @return [NetworkPolicy] allow public internet plus private/LAN egress
-      def non_local = preset("non_local")
-
-      # @return [NetworkPolicy] a bare preset policy
+      # @return [NetworkPolicy] a bare preset policy (:none or :allow_all)
       def preset(name)
         new("preset" => canonical_preset(name))
       end
 
       # Build a custom policy — an ordered rule list with per-direction default
-      # actions. A custom policy stands on its own (no preset); to start from a
-      # preset, use the preset factories (optionally with `deny_domains:` via the
-      # Hash form passed to {Sandbox.create}). `preset:` and custom rules/defaults
-      # are mutually exclusive, mirroring the official SDKs.
+      # actions. A custom policy stands on its own; to start from a profile
+      # base, use the Hash form passed to {Sandbox.create} (`profiles:` composes
+      # with `rules:`/deny lists). A terminal `preset:` stays exclusive with
+      # custom rules/defaults, mirroring the official SDKs. Custom policies
+      # need an explicit {Rule.allow_dns} if the sandbox should resolve names.
       #
       # @param default_egress [:deny, :allow, nil] fall-through for unmatched
       #   outbound traffic (default :deny)
@@ -163,26 +217,64 @@ module Microsandbox
       def coerce(network)
         case network
         when NetworkPolicy then network.to_h
-        when String, Symbol then {"preset" => canonical_preset(network)}
+        when Array then from_profiles(*network).to_h
+        when String, Symbol then coerce_name(network)
         when Hash then from_hash(network)
         else
           raise ArgumentError,
-            "network: expects a preset name, a Microsandbox::NetworkPolicy, or a Hash " \
+            "network: expects profile(s) (:public/:private/:host, or an Array of them), " \
+            "a preset (:none/:allow_all), a Microsandbox::NetworkPolicy, or a Hash " \
             "(got #{network.class})"
         end
       end
 
       private
 
-      # A `network:` Hash is either a preset (`preset:` + optional deny lists) or
-      # a custom policy (`default_egress:`/`default_ingress:`/`rules:` + optional
-      # deny lists). The two are mutually exclusive: a preset already defines its
-      # rules and defaults, so layering custom rules/defaults on top would silently
-      # override them (and diverge from the official SDKs, where preset and custom
-      # are separate paths). A bare preset (only `preset:`, no deny lists) is
-      # routed to the preset path by {Sandbox.create}, so its own defaults apply.
+      # A bare String/Symbol names a single profile (`:public`/`:private`/
+      # `:host`) or a terminal preset (`:none`/`:allow_all` and aliases).
+      # `"default"` stays accepted and means the default policy, which is
+      # exactly the `:public` profile.
+      def coerce_name(name)
+        key = name.to_s.downcase
+        return {"profiles" => [key]} if PROFILES.include?(key)
+        return {"profiles" => ["public"]} if key == "default"
+
+        {"preset" => canonical_preset(key)}
+      end
+
+      # Validate + stringify a profile list. Removed-preset spellings get the
+      # same migration guidance here as in {canonical_preset}, since
+      # `network: [:non_local]` is a plausible mis-migration.
+      def normalize_profiles(profiles)
+        Array(profiles).flatten.map do |p|
+          key = p.to_s.downcase
+          next key if PROFILES.include?(key)
+
+          if (replacement = REMOVED_PRESETS[key])
+            raise ArgumentError,
+              "#{p.inspect} is a removed v0.6.6 network preset, not a profile; use #{replacement}"
+          end
+          raise ArgumentError,
+            "unknown network profile #{p.inspect} (expected :public/:private/:host)"
+        end
+      end
+
+      # A `network:` Hash is composed profiles (`profiles:` + optional rules/
+      # defaults/deny lists), a terminal preset (`preset:` + optional deny
+      # lists), or a custom policy (`default_egress:`/`default_ingress:`/
+      # `rules:` + optional deny lists). Profiles compose with everything —
+      # they expand to an ordinary rule base that explicit rules append to —
+      # but a preset stays exclusive with rules/defaults: it already defines
+      # its rules and defaults, so layering more on top would silently override
+      # them. A bare preset or bare profile list is routed to its dedicated
+      # wire key by {Sandbox.create}, so the runtime's own expansion applies.
       def from_hash(hash)
         sym = hash.transform_keys(&:to_sym)
+        profiles = sym.key?(:profiles) ? normalize_profiles(sym[:profiles]) : nil
+        if profiles && sym.key?(:preset)
+          raise ArgumentError, "network profiles: and preset: are mutually exclusive"
+        end
+
         if sym.key?(:preset)
           if sym.key?(:rules) || sym.key?(:default_egress) || sym.key?(:default_ingress)
             raise ArgumentError,
@@ -193,6 +285,18 @@ module Microsandbox
           h = {"preset" => canonical_preset(sym[:preset])}
           add_deny_lists(h, sym[:deny_domains], sym[:deny_domain_suffixes])
           h
+        elsif profiles
+          h = {}
+          h["profiles"] = profiles unless profiles.empty?
+          h["default_egress"] = action_str(sym[:default_egress]) if sym[:default_egress]
+          h["default_ingress"] = action_str(sym[:default_ingress]) if sym[:default_ingress]
+          rules = Array(sym[:rules]).map { |r| normalize_rule(r) }
+          h["rules"] = rules unless rules.empty?
+          add_deny_lists(h, sym[:deny_domains], sym[:deny_domain_suffixes])
+          # `profiles: []` alone is the runtime's empty composed policy:
+          # deny-egress/allow-ingress with no rules (and no DNS).
+          h = {"default_egress" => "deny", "default_ingress" => "allow", "rules" => []} if h.empty?
+          h
         elsif sym.key?(:rules) || sym.key?(:default_egress) || sym.key?(:default_ingress)
           # An explicit custom policy: the caller chose the rule list and/or the
           # fall-through defaults (which default to :deny / :allow).
@@ -231,10 +335,14 @@ module Microsandbox
 
       def canonical_preset(name)
         key = name.to_s.downcase
+        if (replacement = REMOVED_PRESETS[key])
+          raise ArgumentError,
+            "the #{name.inspect} network preset was removed in runtime v0.6.7; use #{replacement}"
+        end
         PRESET_ALIASES[key] ||
           raise(ArgumentError,
             "unknown network preset #{name.inspect} " \
-            "(expected one of public_only/none/allow_all/non_local)")
+            "(expected none/allow_all, or profiles :public/:private/:host)")
       end
 
       def action_str(action)