kobako 0.3.0 → 0.4.0

data/ext/kobako/src/wasm/instance.rs

@@ -119,7 +119,7 @@ impl Instance {
             Some(secs) => {
                 return Err(wasm_err(
                     &ruby,
-                    format!("timeout_seconds must be > 0 and finite, got {secs}"),
+                    format!("timeout must be > 0 and finite, got {secs} seconds"),
                 ));
             }
         };
@@ -161,10 +161,17 @@ impl Instance {
         // `Instance::eval`. The closure pulls a `&mut WasiP1Ctx` out of
         // HostState; the panic semantics live inside `HostState::wasi_mut`
         // so the wiring stays honest about its precondition.
-        p1::add_to_linker_sync(&mut linker, |state: &mut HostState| state.wasi_mut())
-            .map_err(|e| wasm_err(&ruby, format!("add WASI p1 to linker: {}", e)))?;
+        p1::add_to_linker_sync(&mut linker, |state: &mut HostState| state.wasi_mut()).map_err(
+            |e| {
+                wasm_err(
+                    &ruby,
+                    format!("failed to wire WASI runtime into Sandbox: {}", e),
+                )
+            },
+        )?;
 
-        // `__kobako_dispatch` host import. Signature per SPEC Wire ABI:
+        // `__kobako_dispatch` host import. Signature per docs/wire-codec.md
+        // § ABI Signatures:
         //   (req_ptr: i32, req_len: i32) -> i64
         // Decodes the Request bytes, dispatches via the Ruby-side
         // `Kobako::RPC::Server` (set per-run via `set_server`), allocates a
@@ -180,7 +187,12 @@ impl Instance {
                     dispatch::handle(&mut caller, req_ptr, req_len)
                 },
             )
-            .map_err(|e| wasm_err(&ruby, format!("define __kobako_dispatch: {}", e)))?;
+            .map_err(|e| {
+                wasm_err(
+                    &ruby,
+                    format!("failed to register host RPC dispatch import: {}", e),
+                )
+            })?;
 
         let instance = {
             let mut store_ref = store_cell.borrow_mut();
@@ -268,7 +280,7 @@ impl Instance {
             eval.call(store_ref.as_context_mut(), ())
         };
         self.disarm_caps();
-        result.map_err(|e| call_err(&ruby, "__kobako_eval", e))
+        result.map_err(|e| call_err(&ruby, e))
     }
 
     /// Execute one entrypoint dispatch (`__kobako_run`).
@@ -296,7 +308,7 @@ impl Instance {
             run.call(store_ref.as_context_mut(), (env_ptr, env_len))
         };
         self.disarm_caps();
-        result.map_err(|e| call_err(&ruby, "__kobako_run", e))
+        result.map_err(|e| call_err(&ruby, e))
     }
 
     /// Return the stdout capture from the most recent run as a Ruby
@@ -333,6 +345,39 @@ impl Instance {
         Ok(ruby.str_from_slice(&bytes))
     }
 
+    /// Return the docs/behavior.md B-35 per-last-invocation usage as a
+    /// Ruby 2-tuple `[wall_time, memory_peak]`. The element order
+    /// matches the `Kobako::Usage` field order declared in
+    /// `lib/kobako/usage.rb`; reorder both sides together if the field
+    /// list ever grows.
+    ///
+    ///   * `wall_time` (Float seconds) — the wall-clock duration the
+    ///     most recent invocation spent inside the guest export call.
+    ///     Bracket opens in [`Instance::prime_caps`] and closes in
+    ///     [`Instance::disarm_caps`], so the value mirrors the
+    ///     `timeout` deadline accounting and excludes everything that
+    ///     runs after the guest export returns — the post-export
+    ///     `OUTCOME_BUFFER` fetch and decode, plus stdout / stderr
+    ///     capture readout. `0.0` before the first invocation.
+    ///   * `memory_peak` (Integer bytes) — the high-water mark of the
+    ///     per-invocation `memory.grow` delta past the linear-memory
+    ///     size captured at invocation entry. `0` before the first
+    ///     invocation.
+    ///
+    /// Packing both readers into one ext call mirrors the
+    /// [`Instance::stdout`] / [`Instance::stderr`] pattern: one
+    /// `store.borrow()` per readout and a single magnus binding to
+    /// extend when B-35's field list grows past two.
+    pub(crate) fn usage(&self) -> Result<RArray, MagnusError> {
+        let ruby = Ruby::get().expect("Ruby thread");
+        let state = self.store.borrow();
+        let data = state.data();
+        let arr = ruby.ary_new_capa(2);
+        arr.push(data.wall_time().as_secs_f64())?;
+        arr.push(data.memory_peak())?;
+        Ok(arr)
+    }
+
     // -----------------------------------------------------------------
     // Private helpers.
     // -----------------------------------------------------------------
@@ -349,6 +394,12 @@ impl Instance {
     /// mark left by prior invocations on the same Sandbox are folded
     /// into the baseline rather than the budget — only `memory.grow`
     /// past +baseline+ counts against `memory_limit`.
+    ///
+    /// Also stamps the wall-clock entry instant for the
+    /// docs/behavior.md B-35 `wall_time` measurement. The bracket
+    /// closes in [`Instance::disarm_caps`] so it matches the
+    /// `timeout` deadline window and excludes `OUTCOME_BUFFER`
+    /// decoding and stdout / stderr capture readout.
     fn prime_caps(&self) {
         let mut store_ref = self.store.borrow_mut();
         match self.timeout {
@@ -367,14 +418,19 @@ impl Instance {
             _ => 0,
         };
         store_ref.data_mut().arm_memory_cap(baseline);
+        store_ref.data_mut().start_wall_clock();
     }
 
     /// Drop the memory cap as soon as the guest call returns so that
     /// any post-run host bookkeeping (e.g. fetching the OUTCOME_BUFFER,
     /// which can grow guest memory transiently) is not attributed to
-    /// the user script. Paired with [`Instance::prime_caps`].
+    /// the user script. Also closes the docs/behavior.md B-35
+    /// `wall_time` bracket opened by [`Instance::prime_caps`]. Paired
+    /// with [`Instance::prime_caps`].
     fn disarm_caps(&self) {
-        self.store.borrow_mut().data_mut().disarm_memory_cap();
+        let mut store_ref = self.store.borrow_mut();
+        store_ref.data_mut().stop_wall_clock();
+        store_ref.data_mut().disarm_memory_cap();
     }
 
     /// Allocate a +len+-byte buffer in guest linear memory via
@@ -390,17 +446,20 @@ impl Instance {
         let alloc: TypedFunc<u32, u32> = self
             .inner
             .get_typed_func(store_ref.as_context_mut(), "__kobako_alloc")
-            .map_err(|_| wasm_err(ruby, "guest does not export __kobako_alloc"))?;
+            .map_err(|_| wasm_err(ruby, SANDBOX_RUNTIME_MISSING_HOOKS))?;
         let ptr = alloc
             .call(store_ref.as_context_mut(), bytes.len() as u32)
-            .map_err(|e| wasm_err(ruby, format!("__kobako_alloc(): {}", e)))?;
+            .map_err(|e| wasm_err(ruby, format!("failed to allocate input buffer: {}", e)))?;
         if ptr == 0 {
-            return Err(wasm_err(ruby, "__kobako_alloc returned 0 (out of memory)"));
+            return Err(wasm_err(
+                ruby,
+                "could not allocate input buffer (out of memory)",
+            ));
         }
 
         let memory: Memory = match self.inner.get_export(store_ref.as_context_mut(), "memory") {
             Some(Extern::Memory(m)) => m,
-            _ => return Err(wasm_err(ruby, "guest does not export 'memory'")),
+            _ => return Err(wasm_err(ruby, SANDBOX_RUNTIME_NOT_KOBAKO)),
         };
         let data = memory.data_mut(store_ref.as_context_mut());
         let range = guest_buffer_range(ptr as usize, bytes.len(), data.len())
@@ -456,42 +515,64 @@ impl Instance {
         let mut store_ref = self.store.borrow_mut();
         let packed = take
             .call(store_ref.as_context_mut(), ())
-            .map_err(|e| wasm_err(ruby, format!("__kobako_take_outcome(): {}", e)))?;
+            .map_err(|e| wasm_err(ruby, format!("failed to read invocation result: {}", e)))?;
         let (ptr, len) = unpack_outcome_packed(packed);
 
         let mem: Memory = match self.inner.get_export(store_ref.as_context_mut(), "memory") {
             Some(Extern::Memory(m)) => m,
-            _ => return Err(wasm_err(ruby, "guest does not export 'memory'")),
+            _ => return Err(wasm_err(ruby, SANDBOX_RUNTIME_NOT_KOBAKO)),
         };
         let data = mem.data(store_ref.as_context_mut());
-        let range = guest_buffer_range(ptr, len, data.len())
-            .map_err(|msg| wasm_err(ruby, format!("outcome: {}", msg)))?;
+        let range = guest_buffer_range(ptr, len, data.len()).map_err(|msg| {
+            wasm_err(ruby, format!("invocation 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 = "Sandbox runtime does not export linear memory; \
+     this is not a Kobako-compatible Wasm module";
+
 /// Return the cached +TypedFunc+ for an ABI export, or raise
 /// +Kobako::Wasm::Error+ when the option is +None+. The run-path
 /// methods (+#eval+, +#run+, +#outcome!+) all share the same
 /// "missing export → Ruby error" boilerplate; this helper collapses
-/// the three sites onto one safe entry.
+/// the three sites onto one safe entry. The +_name+ argument is
+/// retained for future operator-side logging but is deliberately not
+/// spliced into the user-facing message (see
+/// [`SANDBOX_RUNTIME_MISSING_HOOKS`]).
 fn require_export<'a, Params, Results>(
     ruby: &Ruby,
     export: Option<&'a TypedFunc<Params, Results>>,
-    name: &str,
+    _name: &str,
 ) -> Result<&'a TypedFunc<Params, Results>, MagnusError>
 where
     Params: wasmtime::WasmParams,
     Results: wasmtime::WasmResults,
 {
-    export.ok_or_else(|| wasm_err(ruby, format!("guest does not export {}", name)))
+    export.ok_or_else(|| wasm_err(ruby, SANDBOX_RUNTIME_MISSING_HOOKS))
 }
 
 /// Validate the invocation envelope length and return it as +i32+ — the
-/// signed wasm wire-ABI parameter type for `__kobako_run`. Rejects sizes
-/// above +i32::MAX+ so the downstream cast cannot silently wrap.
+/// signed wasm ABI parameter type for the guest-run entrypoint.
+/// Rejects sizes above +i32::MAX+ (2 GiB) so the downstream cast cannot
+/// silently wrap.
 fn envelope_len_to_i32(len: usize) -> Result<i32, &'static str> {
-    i32::try_from(len).map_err(|_| "invocation envelope exceeds i32::MAX bytes")
+    i32::try_from(len).map_err(|_| "invocation payload exceeds 2 GiB")
 }
 
 /// Compute the half-open range `[ptr, ptr + len)` for a guest linear-memory
@@ -505,7 +586,7 @@ fn guest_buffer_range(
 ) -> Result<core::ops::Range<usize>, &'static str> {
     let end = ptr.checked_add(len).ok_or("ptr + len overflow")?;
     if end > mem_size {
-        return Err("range exceeds guest memory size");
+        return Err("range exceeds Sandbox memory size");
     }
     Ok(ptr..end)
 }
@@ -603,16 +684,37 @@ fn classify_trap(err: &wasmtime::Error) -> TrapClass {
 }
 
 /// Map a wasmtime call error to the right `Kobako::Wasm::*` Ruby
-/// exception class. `__kobako_eval` / `__kobako_run` traps are routed
-/// through [`classify_trap`]; +export+ is the failing export name and
-/// appears in the trap message so the Sandbox layer can attribute the
-/// fault to the right verb.
-fn call_err(ruby: &Ruby, export: &str, err: wasmtime::Error) -> MagnusError {
-    let msg = format!("{}(): {}", export, err);
+/// exception class. The ABI export symbol (`__kobako_eval` /
+/// `__kobako_run`) is deliberately omitted from the message — the
+/// Sandbox layer attaches the user-facing verb (`Sandbox#eval` /
+/// `Sandbox#run`) so the message reads in caller vocabulary rather
+/// than ABI vocabulary.
+///
+/// For the configured-cap paths ([`TrapClass::Timeout`] /
+/// [`TrapClass::MemoryLimit`]) the trap's own [`std::fmt::Display`]
+/// carries the user-facing reason (`"wall-clock deadline exceeded"`,
+/// `"linear memory growth exceeded memory_limit: ..."`). The wasmtime
+/// outer wrapper at `format!("{}", err)` would otherwise surface only
+/// the `"error while executing at wasm backtrace: ..."` framing, which
+/// is operator noise on a cap trap. For [`TrapClass::Other`] the
+/// wasmtime wrapper IS the diagnostic (real script trap) so it stays.
+fn call_err(ruby: &Ruby, err: wasmtime::Error) -> MagnusError {
     match classify_trap(&err) {
-        TrapClass::Timeout => timeout_err(ruby, msg),
-        TrapClass::MemoryLimit => memory_limit_err(ruby, msg),
-        TrapClass::Other => wasm_err(ruby, msg),
+        TrapClass::Timeout => {
+            let msg = err
+                .downcast_ref::<TimeoutTrap>()
+                .map(|t| t.to_string())
+                .unwrap_or_else(|| format!("{}", err));
+            timeout_err(ruby, msg)
+        }
+        TrapClass::MemoryLimit => {
+            let msg = err
+                .downcast_ref::<MemoryLimitTrap>()
+                .map(|t| t.to_string())
+                .unwrap_or_else(|| format!("{}", err));
+            memory_limit_err(ruby, msg)
+        }
+        TrapClass::Other => wasm_err(ruby, format!("{}", err)),
     }
 }
 

data/ext/kobako/src/wasm.rs

@@ -120,6 +120,7 @@ pub fn init(ruby: &Ruby, kobako: RModule) -> Result<(), MagnusError> {
     instance.define_method("stdout", method!(Instance::stdout, 0))?;
     instance.define_method("stderr", method!(Instance::stderr, 0))?;
     instance.define_method("outcome!", method!(Instance::outcome, 0))?;
+    instance.define_method("usage", method!(Instance::usage, 0))?;
 
     Ok(())
 }

data/lib/kobako/codec/decoder.rb

@@ -38,8 +38,6 @@ module Kobako
       # buffer edge.
       rescue ::MessagePack::UnpackError, ::EOFError => e
         raise Truncated, e.message
-      rescue ::EncodingError => e
-        raise InvalidEncoding, e.message
       end
 
       # SPEC pins +str+ family payloads to UTF-8

data/lib/kobako/codec/factory.rb

@@ -6,7 +6,7 @@ require "msgpack"
 
 require_relative "error"
 require_relative "utils"
-require_relative "../rpc/handle"
+require_relative "../handle"
 require_relative "../rpc/fault"
 
 module Kobako
@@ -89,16 +89,18 @@ module Kobako
       # binary-encoding fallback that msgpack-gem's default unpacker
       # would otherwise apply. The re-tag step lives here because the
       # msgpack ext-type unpacker hands us binary bytes; the assertion
-      # itself is shared with {Decoder} via {Utils.assert_utf8!}.
+      # itself is shared with {Decoder} via {Utils.assert_utf8!}. The
+      # +"Symbol"+ label keeps the error message in Ruby vocabulary
+      # rather than wire-ext-code vocabulary.
       def unpack_symbol(payload)
         name = payload.b.force_encoding(Encoding::UTF_8)
-        Utils.assert_utf8!(name, "ext 0x00 payload")
+        Utils.assert_utf8!(name, "Symbol payload")
         name.to_sym
       end
 
       def register_handle
         @factory.register_type(
-          EXT_HANDLE, RPC::Handle,
+          EXT_HANDLE, Kobako::Handle,
           packer: ->(handle) { [handle.id].pack("N") },
           unpacker: ->(payload) { unpack_handle(payload) }
         )
@@ -112,17 +114,18 @@ module Kobako
         )
       end
 
-      # Peel off the fixext-4 frame, hand the bytes to +RPC::Handle.new+, and
-      # translate the +ArgumentError+ raised by Handle's invariants into
-      # a wire-layer +InvalidType+ via {Codec::Utils.wire_boundary}.
+      # Peel off the fixext-4 frame, hand the bytes to the
+      # Host-Gem-internal +Kobako::Handle.from_wire+ factory, and
+      # translate the +ArgumentError+ raised by Handle's invariants
+      # into a wire-layer +InvalidType+ via {Codec::Utils.wire_boundary}.
       # The Value Object owns the id-range contract; this method only
       # owns the frame shape.
       def unpack_handle(payload)
         bytes = payload.b
-        raise InvalidType, "ext 0x01 payload must be 4 bytes, got #{bytes.bytesize}" unless bytes.bytesize == 4
+        raise InvalidType, "Handle payload must be 4 bytes, got #{bytes.bytesize}" unless bytes.bytesize == 4
 
         id = bytes.unpack1("N") # : Integer
-        Codec::Utils.wire_boundary { RPC::Handle.new(id) }
+        Codec::Utils.wire_boundary { Kobako::Handle.from_wire(id) }
       end
 
       # Encode the inner ext-0x02 map via {Encoder} (not +factory.dump+) so
@@ -148,7 +151,7 @@ module Kobako
       # and re-opens the Decoder's special case for Fault (removed in M5).
       def unpack_fault(payload)
         map = Decoder.decode(payload)
-        raise InvalidType, "ext 0x02 payload must be a map" unless map.is_a?(Hash)
+        raise InvalidType, "Fault payload must be a map" unless map.is_a?(Hash)
 
         Codec::Utils.wire_boundary do
           RPC::Fault.new(type: map["type"], message: map["message"], details: map["details"])

data/lib/kobako/codec/utils.rb

@@ -1,30 +1,37 @@
 # frozen_string_literal: true
 
 require_relative "error"
+require_relative "../handle"
 
 module Kobako
   module Codec
     # Wire-codec helpers shared by the host-side encoders and decoders.
-    # The single concern today is UTF-8 assertion at the wire boundary
-    # ({docs/wire-codec.md}[link:../../../docs/wire-codec.md] § str/bin
-    # Encoding Rules and § Ext Types → ext 0x00). Two call sites lean on
-    # this:
+    # Three concerns live here today:
     #
-    #   - {Decoder} validates +str+ family payloads as it walks the
-    #     decoded value tree.
-    #   - {Factory} validates the +ext 0x00+ Symbol payload after
-    #     re-tagging the binary bytes as UTF-8.
+    #   - UTF-8 assertion at the wire boundary
+    #     ({docs/wire-codec.md}[link:../../../docs/wire-codec.md]
+    #     § str/bin Encoding Rules and § Ext Types → ext 0x00). Used by
+    #     {Decoder} when walking +str+ family payloads and by {Factory}
+    #     when validating the +ext 0x00+ Symbol payload.
+    #   - Wire-boundary +ArgumentError+ translation
+    #     ({wire_boundary}) so the public taxonomy stays
+    #     {Kobako::Codec::Error}.
+    #   - Wire-representability predicate ({wire_representable?}) and
+    #     the symmetric host→guest +#run+ argument walk
+    #     ({deep_wrap}) used by +Kobako::Invocation#encode+ to route
+    #     non-wire-representable leaves through the Sandbox's
+    #     +Kobako::HandleTable+
+    #     ({docs/behavior.md B-34}[link:../../../docs/behavior.md]).
     #
-    # Encoding setup (re-tagging binary as UTF-8 when needed) stays at
-    # the caller — only the assertion shape is shared. The helper does
-    # not mutate +string+; it only inspects +String#valid_encoding?+
-    # against +string+'s current encoding tag.
+    # All helpers are pure — they only inspect inputs, never mutate
+    # them — except {deep_wrap}, whose only side effect is allocating
+    # new Handle ids into the supplied table.
     module Utils
       module_function
 
       # Raise {InvalidEncoding} unless +string+'s bytes are valid under
       # its current encoding tag. +label+ is the caller-supplied prefix
-      # for the error message (e.g. +"str payload"+, +"ext 0x00 payload"+).
+      # for the error message (e.g. +"str payload"+, +"Symbol payload"+).
       def assert_utf8!(string, label)
         return if string.valid_encoding?
 
@@ -51,6 +58,91 @@ module Kobako
       rescue ::ArgumentError => e
         raise InvalidType, e.message
       end
+
+      # 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_wire_type?} stays a single
+      # dispatch line. This is the codec's wire-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))
+
+      # Wire-type predicate
+      # ({docs/wire-codec.md}[link:../../../docs/wire-codec.md] § Type
+      # Mapping). Returns +true+ when +value+ belongs to the closed
+      # 12-entry wire set — +nil+, +TrueClass+, +FalseClass+, +Integer+
+      # (in the +i64..u64+ value domain), +Float+, +String+, +Symbol+,
+      # +Kobako::Handle+, +Array+ whose every element is itself
+      # wire-representable, or +Hash+ whose every key and value are
+      # wire-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 wire_representable?(value)
+        primitive_wire_type?(value) || container_wire_representable?(value)
+      end
+
+      # Deep-walk Array / Hash containers in +value+ and replace every
+      # leaf that fails {wire_representable?} with a +Kobako::Handle+
+      # allocated from +handle_table+
+      # ({docs/behavior.md B-34}[link:../../../docs/behavior.md]). The
+      # walk only descends through wire-representable container shapes
+      # (Array, Hash) one structural level at a time; a non-
+      # wire-representable leaf is wrapped as-is without inspecting its
+      # internal structure. An existing +Kobako::Handle+ is wire-
+      # representable and passes through unchanged — auto-wrap never
+      # re-wraps a Handle.
+      #
+      # +value+ may be any Ruby value; +handle_table+ must respond to
+      # +#alloc(object) -> Kobako::Handle+ (a host-side
+      # +Kobako::HandleTable+). Returns a structurally equivalent value
+      # whose leaves are either wire-representable or +Kobako::Handle+
+      # tokens.
+      #
+      # The block bodies spell +Utils.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 +Utils+ 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, handle_table)
+        case value
+        when ::Array then value.map { |element| Utils.deep_wrap(element, handle_table) }
+        when ::Hash  then value.transform_values { |val| Utils.deep_wrap(val, handle_table) }
+        else
+          wire_representable?(value) ? value : handle_table.alloc(value)
+        end
+      end
+
+      # Predicate split out of {wire_representable?} for cyclomatic
+      # budget — the closed-set non-container branch. Returns +true+ for
+      # the wire scalar leaves and an existing Handle. Not part of the
+      # public surface; reach for {wire_representable?} instead.
+      def primitive_wire_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
+
+      # Predicate split out of {wire_representable?} for cyclomatic
+      # budget — the container branch. Recurses into Array elements and
+      # Hash key+value pairs through the public {wire_representable?}.
+      # Not part of the public surface; reach for {wire_representable?}
+      # instead.
+      def container_wire_representable?(value)
+        case value
+        when ::Array then value.all? { |element| Utils.wire_representable?(element) }
+        when ::Hash  then value.all? { |key, val| Utils.wire_representable?(key) && Utils.wire_representable?(val) }
+        else false
+        end
+      end
     end
   end
 end

data/lib/kobako/handle.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Kobako
+  # Wire-level value object for an ext-0x01 Capability Handle, used in both
+  # directions across the Sandbox boundary: as a Service method's return
+  # value (guest→host return path; {docs/behavior.md B-14}[link:../../docs/behavior.md])
+  # and as a +#run+ argument auto-wrapped by the host
+  # ({docs/behavior.md B-34}[link:../../docs/behavior.md]).
+  #
+  # SPEC pins the binary layout to fixext 4 with a 4-byte big-endian u32
+  # payload ({docs/wire-codec.md}[link:../../docs/wire-codec.md]
+  # § Ext Types → ext 0x01). ID 0 is reserved as the invalid sentinel;
+  # the maximum valid ID is 0x7fff_ffff (2^31 - 1).
+  #
+  # The constructor is internal to the Host Gem. +Kobako::Handle.new+ is
+  # privatised so Host App code cannot fabricate a Handle from a bare
+  # integer; legitimate Handle instances enter Host App code only as
+  # fields on raised error objects. The Host Gem itself constructs
+  # Handles through {.from_wire}, which exists at exactly two call
+  # sites: +Kobako::Codec::Factory#unpack_handle+ (wire decode) and
+  # +Kobako::Codec::Utils.deep_wrap+ / +Kobako::RPC::Dispatcher#wrap_as_handle+
+  # (allocator paths). Both live inside +lib/kobako/+ and are not part
+  # of any public surface.
+  #
+  # The mruby counterpart +Kobako::Handle+ lives inside the Wasm guest
+  # under the same canonical name and shares neither code nor instances
+  # with this host-side class.
+  class Handle < Data.define(:id)
+    # Inclusive lower bound on the wire Handle ID. ID 0 is reserved as
+    # the invalid sentinel and is never allocated.
+    MIN_ID = 1
+    # Inclusive upper bound on the wire Handle ID. The cap matches the
+    # u32 signed-positive range so Handle IDs fit in a signed integer
+    # on either side of the wire without re-encoding.
+    MAX_ID = 0x7fff_ffff
+
+    # steep:ignore:start
+    def initialize(id:)
+      raise ArgumentError, "Handle id must be Integer" unless id.is_a?(Integer)
+      raise ArgumentError, "Handle id #{id} out of range [#{MIN_ID}, #{MAX_ID}]" unless id.between?(MIN_ID, MAX_ID)
+
+      super
+    end
+    # steep:ignore:end
+
+    private_class_method :new
+
+    # Host Gem–internal factory. Allocates the Data instance through
+    # +Class#allocate+ and dispatches +#initialize+ explicitly so the
+    # invariant checks still run, while keeping the public +.new+
+    # privatised against Host App callers.
+    #
+    # Two collaborators call this: the codec when an ext 0x01 frame is
+    # decoded off the wire, and the allocator paths when a host-side
+    # Ruby object is registered into the Sandbox's +HandleTable+. Both
+    # paths live inside +lib/kobako/+ and treat this method as a
+    # package-private constructor.
+    def self.from_wire(id)
+      allocate.tap { |handle| handle.send(:initialize, id: id) }
+    end
+  end
+end