kobako 0.11.1 → 0.12.0

data/ext/kobako/src/runtime.rs

@@ -42,16 +42,15 @@ mod cache;
 mod capture;
 mod config;
 mod dispatch;
+mod errors;
 mod exports;
+mod frames;
 mod guest_mem;
 mod instance_pre;
 mod invocation;
 mod trap;
 
-use magnus::value::Lazy;
-use magnus::{
-    function, method, prelude::*, Error as MagnusError, ExceptionClass, RModule, RString, Ruby,
-};
+use magnus::{function, method, prelude::*, Error as MagnusError, RModule, RString, Ruby};
 
 use std::cell::Cell;
 use std::path::Path;
@@ -61,11 +60,8 @@ use magnus::{gc, typed_data::DataTypeFunctions, value::Opaque, RArray, TypedData
 
 use crate::snapshot::Snapshot;
 use wasmtime::{
-    AsContextMut, InstancePre as WtInstancePre, Memory, ResourceLimiter, Store as WtStore,
-    TypedFunc,
+    AsContextMut, InstancePre as WtInstancePre, ResourceLimiter, Store as WtStore, TypedFunc,
 };
-use wasmtime_wasi::p2::pipe::{MemoryInputPipe, MemoryOutputPipe};
-use wasmtime_wasi::WasiCtxBuilder;
 
 use self::cache::shared_engine;
 use self::config::Config;
@@ -93,94 +89,6 @@ pub(crate) fn rstring_to_vec(s: RString) -> Vec<u8> {
     unsafe { s.as_slice() }.to_vec()
 }
 
-// ---------------------------------------------------------------------------
-// Error classes (lazy-resolved from Ruby once the top-level Kobako error
-// hierarchy is loaded by `lib/kobako/errors.rb`). The ext raises directly
-// into the invocation-outcome taxonomy (`TrapError` and its subclasses)
-// for run-path failures and into the construction-layer `SetupError`
-// (and its `ModuleNotBuiltError` subclass) for `from_path` setup failures
-// — no engine-specific intermediate layer; the Sandbox layer adds the
-// verb prefix and lets the subclass identity flow through unchanged.
-// ---------------------------------------------------------------------------
-
-/// Resolve `Kobako::<name>` as an `ExceptionClass` — the shared body of
-/// every error-class `Lazy` below, which differ only in the constant
-/// name. The constants are guaranteed present by the time any of these
-/// lazies first resolve (`lib/kobako/errors.rb` loads the hierarchy before
-/// the ext raises into it), so a missing constant is a build / wiring bug
-/// and the `unwrap` is the correct fail-fast.
-fn kobako_error_class(ruby: &Ruby, name: &str) -> ExceptionClass {
-    let kobako: RModule = ruby.class_object().const_get("Kobako").unwrap();
-    kobako.const_get(name).unwrap()
-}
-
-pub(crate) static SETUP_ERROR: Lazy<ExceptionClass> =
-    Lazy::new(|ruby| kobako_error_class(ruby, "SetupError"));
-
-pub(crate) static MODULE_NOT_BUILT_ERROR: Lazy<ExceptionClass> =
-    Lazy::new(|ruby| kobako_error_class(ruby, "ModuleNotBuiltError"));
-
-pub(crate) static TRAP_ERROR: Lazy<ExceptionClass> =
-    Lazy::new(|ruby| kobako_error_class(ruby, "TrapError"));
-
-pub(crate) static TIMEOUT_ERROR: Lazy<ExceptionClass> =
-    Lazy::new(|ruby| kobako_error_class(ruby, "TimeoutError"));
-
-pub(crate) static MEMORY_LIMIT_ERROR: Lazy<ExceptionClass> =
-    Lazy::new(|ruby| kobako_error_class(ruby, "MemoryLimitError"));
-
-pub(crate) static SANDBOX_ERROR: Lazy<ExceptionClass> =
-    Lazy::new(|ruby| kobako_error_class(ruby, "SandboxError"));
-
-/// Build a `MagnusError` in `class` carrying `msg` — the shared body of
-/// the named `*_err` constructors below, which differ only in which
-/// error-class `Lazy` they target.
-fn error_in(ruby: &Ruby, class: &Lazy<ExceptionClass>, msg: impl Into<String>) -> MagnusError {
-    MagnusError::new(ruby.get_inner(class), msg.into())
-}
-
-/// Construct a `Kobako::TrapError` magnus error. Used for every
-/// invocation-time wasmtime engine failure that is not a configured-cap
-/// trap — missing exports, allocation faults, memory write/read failures.
-/// Construction-time setup failures use `setup_err`, not this.
-pub(crate) fn trap_err(ruby: &Ruby, msg: impl Into<String>) -> MagnusError {
-    error_in(ruby, &TRAP_ERROR, msg)
-}
-
-/// Construct a `Kobako::SetupError` magnus error. Used for every
-/// construction-time failure on the `Runtime.from_path` path before any
-/// invocation runs — unreadable artifact, bytes that are not a valid Wasm
-/// module, or engine / linker / instantiation setup failure. The
-/// `ModuleNotBuiltError` subclass (artifact absent) is
-/// raised through `MODULE_NOT_BUILT_ERROR` directly.
-pub(crate) fn setup_err(ruby: &Ruby, msg: impl Into<String>) -> MagnusError {
-    error_in(ruby, &SETUP_ERROR, msg)
-}
-
-/// Construct a `Kobako::TimeoutError` magnus error. Surfaces the
-/// wall-clock cap path with the verb prefix added
-/// by `Kobako::Sandbox#invoke!`.
-pub(crate) fn timeout_err(ruby: &Ruby, msg: impl Into<String>) -> MagnusError {
-    error_in(ruby, &TIMEOUT_ERROR, msg)
-}
-
-/// Construct a `Kobako::MemoryLimitError` magnus error. Surfaces the
-/// linear-memory cap path with the verb prefix
-/// added by `Kobako::Sandbox#invoke!`.
-pub(crate) fn memory_limit_err(ruby: &Ruby, msg: impl Into<String>) -> MagnusError {
-    error_in(ruby, &MEMORY_LIMIT_ERROR, msg)
-}
-
-/// Construct a `Kobako::SandboxError` magnus error. Used for the
-/// host-side pre-call faults the SPEC attributes to the sandbox / wire
-/// layer rather than the Wasm engine — currently the `#run` invocation
-/// envelope reservation failure (`__kobako_alloc` returns 0).
-/// The runtime is intact, so this must not be a
-/// `TrapError`: no discard-and-recreate recovery is owed to the caller.
-pub(crate) fn sandbox_err(ruby: &Ruby, msg: impl Into<String>) -> MagnusError {
-    error_in(ruby, &SANDBOX_ERROR, msg)
-}
-
 // ---------------------------------------------------------------------------
 // Ruby init
 // ---------------------------------------------------------------------------
@@ -327,7 +235,7 @@ impl Runtime {
     /// `Invocation::wasi_mut`.
     fn probe_abi_version(&self, ruby: &Ruby) -> Result<(), MagnusError> {
         let mut store = self.new_store()?;
-        install_wasi_frames(&mut store, &self.config, &[])?;
+        frames::install_wasi_frames(&mut store, &self.config, &[])?;
         let instance = self
             .instance_pre
             .instantiate(store.as_context_mut())
@@ -335,7 +243,7 @@ impl Runtime {
         let probe = instance
             .get_typed_func::<(), u32>(store.as_context_mut(), "__kobako_abi_version")
             .map_err(|_| {
-                setup_err(
+                errors::setup_err(
                     ruby,
                     format!(
                         "the Guest Binary does not export __kobako_abi_version; \
@@ -344,13 +252,13 @@ impl Runtime {
                 )
             })?;
         let reported = probe.call(store.as_context_mut(), ()).map_err(|e| {
-            setup_err(
+            errors::setup_err(
                 ruby,
                 format!("failed to read the Guest Binary's ABI version: {e}"),
             )
         })?;
         if reported != ABI_VERSION {
-            return Err(setup_err(
+            return Err(errors::setup_err(
                 ruby,
                 format!(
                     "the Guest Binary reports ABI version {reported}, but this host \
@@ -396,14 +304,14 @@ impl Runtime {
 
         let bytes = rstring_to_vec(args_bytes);
         let Some(caller) = dispatch::current_caller() else {
-            return Err(trap_err(
+            return Err(errors::trap_err(
                 &ruby,
                 "yield_to_active_invocation called outside an active Sandbox dispatch frame",
             ));
         };
 
         let resp_bytes =
-            guest_mem::drive_yield(caller, &bytes).map_err(|msg| trap_err(&ruby, msg))?;
+            guest_mem::drive_yield(caller, &bytes).map_err(|msg| errors::trap_err(&ruby, msg))?;
         Ok(ruby.str_from_slice(&resp_bytes))
     }
 
@@ -438,7 +346,7 @@ impl Runtime {
     ) -> Result<Snapshot, MagnusError> {
         let ruby = Ruby::get().expect("Ruby thread");
         let mut store = self.new_store()?;
-        install_wasi_frames(
+        frames::install_wasi_frames(
             &mut store,
             &self.config,
             &[
@@ -448,7 +356,7 @@ impl Runtime {
             ],
         )?;
         let exports = self.instantiate(&ruby, &mut store)?;
-        let eval = require_export(&ruby, exports.eval.as_ref())?;
+        let eval = frames::require_export(&ruby, exports.eval.as_ref())?;
         self.call_with_caps(&mut store, &exports, eval, ())
             .map_err(|e| trap::call_err(&ruby, e))?;
         self.build_snapshot(&ruby, &mut store, &exports)
@@ -472,14 +380,14 @@ impl Runtime {
     ) -> Result<Snapshot, MagnusError> {
         let ruby = Ruby::get().expect("Ruby thread");
         let mut store = self.new_store()?;
-        install_wasi_frames(
+        frames::install_wasi_frames(
             &mut store,
             &self.config,
             &[rstring_to_vec(preamble), rstring_to_vec(snippets)],
         )?;
         let exports = self.instantiate(&ruby, &mut store)?;
-        let run = require_export(&ruby, exports.run.as_ref())?;
-        let (env_ptr, env_len) = write_envelope(&ruby, &mut store, &exports, envelope)?;
+        let run = frames::require_export(&ruby, exports.run.as_ref())?;
+        let (env_ptr, env_len) = frames::write_envelope(&ruby, &mut store, &exports, envelope)?;
         self.call_with_caps(&mut store, &exports, run, (env_ptr, env_len))
             .map_err(|e| trap::call_err(&ruby, e))?;
         self.build_snapshot(&ruby, &mut store, &exports)
@@ -544,7 +452,7 @@ impl Runtime {
             .instance_pre
             .instantiate(store.as_context_mut())
             .map_err(|e| {
-                trap_err(
+                errors::trap_err(
                     ruby,
                     format!("failed to instantiate the Sandbox runtime: {e}"),
                 )
@@ -630,7 +538,7 @@ impl Runtime {
         store: &mut WtStore<Invocation>,
         exports: &Exports,
     ) -> Result<Snapshot, MagnusError> {
-        let return_bytes = fetch_outcome_bytes(ruby, store, exports)?;
+        let return_bytes = frames::fetch_outcome_bytes(ruby, store, exports)?;
         let data = store.data();
         let (stdout_raw, stderr_raw, wall_time, memory_peak) = (
             data.stdout_bytes(),
@@ -666,170 +574,3 @@ fn disarm_caps(store: &mut WtStore<Invocation>) {
     store.data_mut().stop_wall_clock();
     store.data_mut().disarm_memory_cap();
 }
-
-/// Return the resolved `memory` export handle, or raise
-/// `Kobako::TrapError` when the loaded module exports no linear
-/// memory — the "not a Kobako-shaped runtime" failure mode
-/// (`SANDBOX_RUNTIME_NOT_KOBAKO`).
-fn require_memory(ruby: &Ruby, exports: &Exports) -> Result<Memory, MagnusError> {
-    exports
-        .memory
-        .ok_or_else(|| trap_err(ruby, SANDBOX_RUNTIME_NOT_KOBAKO))
-}
-
-/// Allocate a `len`-byte buffer in guest linear memory via
-/// `__kobako_alloc`, copy `envelope` into it, and return `(ptr, len)`
-/// as `i32` values matching the `__kobako_run(env_ptr, env_len)` ABI.
-/// Raises `Kobako::TrapError` when the allocation hook is missing or
-/// itself traps, and `Kobako::SandboxError` when the hook runs but
-/// cannot reserve the buffer (`__kobako_alloc` returns 0) — an
-/// intact runtime, not an engine fault.
-fn write_envelope(
-    ruby: &Ruby,
-    store: &mut WtStore<Invocation>,
-    exports: &Exports,
-    envelope: RString,
-) -> Result<(i32, i32), MagnusError> {
-    let bytes = rstring_to_vec(envelope);
-    let len_i32 = guest_mem::checked_payload_len(bytes.len()).map_err(|msg| trap_err(ruby, msg))?;
-
-    let alloc = require_export(ruby, exports.alloc.as_ref())?;
-    let memory = require_memory(ruby, exports)?;
-
-    let ptr = alloc
-        .call(store.as_context_mut(), bytes.len() as u32)
-        .map_err(|e| trap_err(ruby, format!("failed to allocate input buffer: {}", e)))?;
-    if ptr == 0 {
-        return Err(sandbox_err(
-            ruby,
-            "could not allocate input buffer (out of memory)",
-        ));
-    }
-    let data = memory.data_mut(store.as_context_mut());
-    let range = guest_mem::guest_buffer_range(ptr as usize, bytes.len(), data.len())
-        .map_err(|msg| trap_err(ruby, msg))?;
-    data[range].copy_from_slice(&bytes);
-
-    Ok((ptr as i32, len_i32))
-}
-
-/// Build the per-invocation WASI context with stdin carrying every frame
-/// in `frames` (each prefixed by its 4-byte big-endian u32 length —
-/// docs/wire-codec.md § Invocation channels) plus fresh stdout / stderr
-/// pipes, and install it on the invocation's Store. `#eval` passes three
-/// frames (preamble, source, snippets), `#run` passes two (preamble,
-/// snippets — the invocation envelope arrives via linear memory
-/// instead). Each output pipe is sized at `cap + 1` so
-/// `capture::clip_capture` can distinguish "wrote exactly cap bytes"
-/// from "exceeded cap"; uncapped channels fall back to `usize::MAX` and
-/// rely on `memory_limit` for the real ceiling.
-/// Raises `Kobako::TrapError` when any frame exceeds the 16 MiB cap that
-/// keeps its `u32` length prefix from wrapping.
-fn install_wasi_frames(
-    store: &mut WtStore<Invocation>,
-    config: &Config,
-    frames: &[Vec<u8>],
-) -> Result<(), MagnusError> {
-    let ruby = Ruby::get().expect("Ruby thread");
-    // Every frame carries the same 16 MiB cap as the `#run` envelope
-    // (`write_envelope`): the length prefix is a `u32`, so a frame past
-    // the cap would silently wrap and corrupt the stdin frame stream.
-    for frame in frames {
-        guest_mem::checked_payload_len(frame.len()).map_err(|msg| trap_err(&ruby, msg))?;
-    }
-
-    let total: usize = frames.iter().map(|f| 4 + f.len()).sum();
-    let mut stdin_content: Vec<u8> = Vec::with_capacity(total);
-    for frame in frames {
-        stdin_content.extend_from_slice(&(frame.len() as u32).to_be_bytes());
-        stdin_content.extend_from_slice(frame);
-    }
-
-    let stdin_pipe = MemoryInputPipe::new(stdin_content);
-    let stdout_pipe = MemoryOutputPipe::new(capture::pipe_capacity(config.stdout_limit_bytes));
-    let stderr_pipe = MemoryOutputPipe::new(capture::pipe_capacity(config.stderr_limit_bytes));
-
-    let mut builder = WasiCtxBuilder::new();
-    builder.stdin(stdin_pipe);
-    builder.stdout(stdout_pipe.clone());
-    builder.stderr(stderr_pipe.clone());
-    // Deny the preview1 ambient-authority imports the guest never legitimately
-    // reaches but the WASI layer would otherwise grant (see `ambient`).
-    builder.wall_clock(ambient::FrozenWallClock);
-    builder.monotonic_clock(ambient::FrozenMonotonicClock);
-    builder.secure_random(ambient::deterministic_rng());
-    let wasi = builder.build_p1();
-
-    store
-        .data_mut()
-        .install_wasi(wasi, stdout_pipe, stderr_pipe);
-    Ok(())
-}
-
-/// Invoke `__kobako_take_outcome`, decode the packed `(ptr<<32)|len`
-/// u64, and copy the OUTCOME_BUFFER slice out of guest memory. Raises
-/// `Kobako::TrapError` when the export is missing, `len` exceeds the
-/// 16 MiB single-dispatch cap, the `ptr`/`len` arithmetic overflows,
-/// the slice falls outside live memory, or the `memory` export itself
-/// is absent.
-fn fetch_outcome_bytes(
-    ruby: &Ruby,
-    store: &mut WtStore<Invocation>,
-    exports: &Exports,
-) -> Result<Vec<u8>, MagnusError> {
-    let take = require_export(ruby, exports.take_outcome.as_ref())?;
-    let mem = require_memory(ruby, exports)?;
-
-    let packed = take
-        .call(store.as_context_mut(), ())
-        .map_err(|e| trap_err(ruby, format!("failed to read the Sandbox result: {}", e)))?;
-    let (ptr, len) = guest_mem::unpack_outcome_packed(packed);
-    if len > guest_mem::MAX_DISPATCH_PAYLOAD {
-        return Err(trap_err(ruby, "result payload exceeds the 16 MiB limit"));
-    }
-
-    let data = mem.data(store.as_context_mut());
-    let range = guest_mem::guest_buffer_range(ptr, len, data.len()).map_err(|msg| {
-        trap_err(
-            ruby,
-            format!("the Sandbox result is out of bounds: {}", msg),
-        )
-    })?;
-    Ok(data[range].to_vec())
-}
-
-/// User-facing message for the "Sandbox runtime is missing one of the
-/// internal Kobako hooks" failure mode. Phrased in caller vocabulary —
-/// the underlying ABI symbol names (`__kobako_alloc`, `__kobako_eval`,
-/// `__kobako_take_outcome`) are not actionable to callers, and the
-/// gem itself raises this error so a self-reference like "matches the
-/// kobako gem version" reads as third-person. The actionable
-/// diagnosis is "your data/kobako.wasm is out of sync; rebuild it".
-const SANDBOX_RUNTIME_MISSING_HOOKS: &str = "Sandbox runtime is missing required hooks; \
-     rebuild data/kobako.wasm against the installed version";
-
-/// User-facing message for the "the loaded Wasm module is not a
-/// Kobako-shaped runtime at all" failure mode (no linear memory
-/// export). Same phrasing philosophy as
-/// `SANDBOX_RUNTIME_MISSING_HOOKS`.
-const SANDBOX_RUNTIME_NOT_KOBAKO: &str =
-    "the loaded Wasm module is not a Kobako-compatible runtime";
-
-/// Return the resolved `TypedFunc` for an ABI export, or raise
-/// `Kobako::TrapError` when the option is `None`. Both run-path
-/// methods (`#eval`, `#run`) plus the `build_snapshot` readout that
-/// drains `OUTCOME_BUFFER` share the same "missing export → Ruby
-/// error" boilerplate; this helper collapses those sites onto one
-/// safe entry. The user-facing message is intentionally export-
-/// agnostic (see `SANDBOX_RUNTIME_MISSING_HOOKS`) — the ABI symbol
-/// name is not actionable to callers, so it is not threaded in.
-fn require_export<'a, Params, Results>(
-    ruby: &Ruby,
-    export: Option<&'a TypedFunc<Params, Results>>,
-) -> Result<&'a TypedFunc<Params, Results>, MagnusError>
-where
-    Params: wasmtime::WasmParams,
-    Results: wasmtime::WasmResults,
-{
-    export.ok_or_else(|| trap_err(ruby, SANDBOX_RUNTIME_MISSING_HOOKS))
-}

data/lib/kobako/catalog/handles.rb

@@ -43,9 +43,9 @@ module Kobako
       # and the allocator share the same invariant.
       #
       # Returning a Handle (rather than a bare Integer id) keeps the
-      # allocator's output a domain entity; +Kobako::Handle.restore+
-      # is reserved for the codec's wire-decode path, where the id is
-      # the only thing the bytes carry.
+      # allocator's output a domain entity. An id is the Handle's only
+      # content, so the same internal +Kobako::Handle.restore+ constructor
+      # serves both this allocator and the codec's wire-decode path.
       def alloc(object)
         reject_unwrappable!(object)
         ensure_capacity!
@@ -72,7 +72,7 @@ module Kobako
       end
 
       # Number of currently-bound entries. Used by tests of the Dispatcher
-      # and Codec::Utils#deep_wrap to observe whether each path allocates
+      # and Codec::HandleWalk#deep_wrap to observe whether each path allocates
       # exactly the Handle entries it should — the +Handles+ table itself never
       # consults its own size, but the surrounding code's allocation
       # contract is part of the observable boundary.

data/lib/kobako/codec/handle_walk.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require_relative "../handle"
+
+module Kobako
+  module Codec
+    # Substitutes Capability Handles into and out of a Ruby value tree at
+    # the host↔guest boundary. {deep_wrap} allocates a +Kobako::Handle+ for
+    # each non-wire-representable leaf on the host→guest +#run+ argument
+    # path; {deep_restore} resolves each wire-decoded Handle back to its
+    # host object on every guest→host value path — the +#eval+ / +#run+
+    # result and the yield-block result alike. {representable?} is the
+    # by-value codec-type predicate that decides which leaves {deep_wrap}
+    # must wrap: the closed 12-entry wire type set
+    # ({docs/wire-codec.md}[link:../../../docs/wire-codec.md] § Type
+    # Mapping).
+    #
+    # All helpers are pure except {deep_wrap}, whose only side effect is
+    # allocating new Handle ids into the supplied table.
+    module HandleWalk
+      module_function
+
+      # Inclusive Integer range the msgpack gem encodes without raising
+      # +RangeError+ at encode time — signed +int 64+ minimum through
+      # unsigned +uint 64+ maximum
+      # ({docs/wire-codec.md}[link:../../../docs/wire-codec.md] § Type
+      # Mapping #3, the +fixint+ / +int 8..64+ / +uint 8..64+ union).
+      # Anchored as a +Range+ so {primitive_type?} stays a single
+      # dispatch line. This is the codec's encode domain — not to
+      # be confused with the Handle id range, which lives on
+      # +Kobako::Handle+ as +MIN_ID+ / +MAX_ID+ (1..2^31 − 1) and
+      # represents a different concept entirely.
+      MSGPACK_INT_RANGE = (-(2**63)..((2**64) - 1))
+
+      # Codec-type predicate
+      # ({docs/wire-codec.md}[link:../../../docs/wire-codec.md] § Type
+      # Mapping). Returns +true+ when +value+ belongs to the closed
+      # 12-entry codec type set — +nil+, +TrueClass+, +FalseClass+,
+      # +Integer+ (in the +i64..u64+ value domain), +Float+, +String+,
+      # +Symbol+, +Kobako::Handle+, +Array+ whose every element is itself
+      # representable, or +Hash+ whose every key and value are
+      # representable. Integers outside the codec's signed-64 /
+      # unsigned-64 union are rejected so the predicate agrees with the
+      # msgpack gem's encode-time +RangeError+ behaviour the codec
+      # already surfaces as {UnsupportedType}.
+      def representable?(value)
+        primitive_type?(value) || container_representable?(value)
+      end
+
+      # Deep-walk Array / Hash containers in +value+ and replace every
+      # leaf that fails {representable?} with a +Kobako::Handle+
+      # allocated from +handler+. The
+      # walk only descends through representable container shapes
+      # (Array, Hash) one structural level at a time; a non-representable
+      # leaf is wrapped as-is without inspecting its internal structure.
+      # An existing +Kobako::Handle+ is representable and passes through
+      # unchanged — auto-wrap never re-wraps a Handle.
+      #
+      # +value+ may be any Ruby value; +handler+ must respond to
+      # +#alloc(object) -> Kobako::Handle+ (a host-side
+      # +Kobako::Catalog::Handles+). Returns a structurally equivalent value
+      # whose leaves are either representable or +Kobako::Handle+
+      # tokens.
+      #
+      # The block bodies spell +HandleWalk.deep_wrap+ explicitly rather
+      # than the unqualified +deep_wrap+ because +module_function+ makes
+      # the instance copy of these helpers private; an implicit receiver
+      # inside a block would resolve against the enclosing +self+
+      # (still +HandleWalk+ at definition time, but the qualified form
+      # keeps the dispatch readable when the recursive call sits inside a
+      # Proc captured from elsewhere).
+      def deep_wrap(value, handler)
+        case value
+        when ::Array then value.map { |element| HandleWalk.deep_wrap(element, handler) }
+        when ::Hash  then value.transform_values { |val| HandleWalk.deep_wrap(val, handler) }
+        else
+          representable?(value) ? value : handler.alloc(value)
+        end
+      end
+
+      # Deep-walk Array / Hash containers in +value+ and replace every
+      # +Kobako::Handle+ leaf with the host-side object +handler+ resolves
+      # it to. The symmetric inverse of {deep_wrap}: that walk allocates objects
+      # into Handles on the host→guest argument path; this walk resolves
+      # Handles back to their objects on every guest→host value path — the
+      # +#eval+ / +#run+ result and the yield-block result alike. The walk
+      # descends through Array elements and Hash keys and values one
+      # structural level at a time; any non-Handle leaf passes through
+      # unchanged.
+      #
+      # +value+ is a decoded Ruby value (a Handle here is a wire-decoded
+      # +Kobako::Handle+, never a guest-forged one); +handler+ must
+      # respond to +#fetch(id) -> object+ (a host-side
+      # +Kobako::Catalog::Handles+). +handler.fetch+ raises
+      # +Kobako::SandboxError+ for an id with no live binding, the
+      # corrupted-runtime fallback.
+      def deep_restore(value, handler)
+        case value
+        when ::Array then value.map { |element| HandleWalk.deep_restore(element, handler) }
+        when ::Hash
+          value.to_h { |key, val| [HandleWalk.deep_restore(key, handler), HandleWalk.deep_restore(val, handler)] }
+        when Kobako::Handle then handler.fetch(value.id)
+        else value
+        end
+      end
+
+      # The non-container branch of {representable?}: returns +true+ for
+      # the scalar leaves and an existing Handle. Not part of the
+      # public surface; reach for {representable?} instead.
+      def primitive_type?(value)
+        case value
+        when ::NilClass, ::TrueClass, ::FalseClass, ::Float, ::String, ::Symbol, Kobako::Handle then true
+        when ::Integer then MSGPACK_INT_RANGE.cover?(value)
+        else false
+        end
+      end
+
+      # The container branch of {representable?}: recurses into Array
+      # elements and Hash key+value pairs through the public
+      # {representable?}. Not part of the public surface; reach for
+      # {representable?} instead.
+      def container_representable?(value)
+        case value
+        when ::Array then value.all? { |element| HandleWalk.representable?(element) }
+        when ::Hash  then value.all? { |key, val| HandleWalk.representable?(key) && HandleWalk.representable?(val) }
+        else false
+        end
+      end
+    end
+  end
+end