kobako 0.12.0 → 0.12.2

data/ext/kobako/src/snapshot.rs

@@ -1,64 +1,39 @@
-//! `Kobako::Snapshot` — per-invocation observable bundle.
+//! `Kobako::Snapshot` — the Ruby-facing per-invocation observable bundle.
 //!
-//! Every successful `Kobako::Runtime#eval` / `#run` returns one of these.
-//! It carries every observable the host needs to surface after a guest
-//! invocation: the OUTCOME_BUFFER bytes (`return_bytes`), the captured
-//! stdout / stderr byte slices with their truncation flags, and
-//! the wall-clock + memory-peak figures from `Kobako::Usage`.
-//!
-//! Ruby callers see the seven raw readers registered below; the helper
-//! methods that pack them into `Kobako::Capture` / `Kobako::Usage`
-//! (`Kobako::Snapshot#stdout` / `#stderr` / `#usage`) live in
+//! The success-path view of the engine-neutral snapshot: the outcome bytes
+//! and the two captured output channels, exposed through five raw readers.
+//! The helper methods that pack them into `Kobako::Capture`
+//! (`Kobako::Snapshot#stdout` / `#stderr`) live in
 //! `lib/kobako/snapshot.rb`. The split keeps the ext side a pure value
-//! carrier and lets Ruby own the convenience surface.
-
-use std::cell::Cell;
-use std::time::Duration;
+//! carrier and lets Ruby own the convenience surface. Usage is not on the
+//! Snapshot — `Sandbox#usage` reads it from `Kobako::Runtime#usage`, which
+//! survives the trap path where no `Kobako::Snapshot` is produced.
 
 use magnus::{method, prelude::*, Error as MagnusError, RModule, RString, Ruby};
 
+use kobako_runtime::snapshot::Capture;
+
 /// Per-invocation snapshot value. Magnus wraps it so a single ext call
-/// from `Runtime::eval` / `Runtime::run` returns the whole bundle —
-/// the Sandbox layer can decompose it without round-tripping into ext
-/// again. All fields are private; the seven public methods registered
-/// in `init` read them out one by one. The wall-clock duration is
-/// held as a `Cell<Duration>` only because magnus' `#[magnus::wrap]`
-/// macro requires interior mutability — every field is set once at
-/// construction time and never mutated again.
+/// from `Runtime::eval` / `Runtime::run` returns the whole bundle — the
+/// Sandbox layer decomposes it without round-tripping into ext again. The
+/// fields are set once at construction and never mutated; the five public
+/// methods registered in `init` read them out one by one.
 #[magnus::wrap(class = "Kobako::Snapshot", free_immediately, size)]
 pub(crate) struct Snapshot {
     return_bytes: Vec<u8>,
-    stdout_bytes: Vec<u8>,
-    stdout_truncated: bool,
-    stderr_bytes: Vec<u8>,
-    stderr_truncated: bool,
-    wall_time: Cell<Duration>,
-    memory_peak: usize,
+    stdout: Capture,
+    stderr: Capture,
 }
 
 impl Snapshot {
-    /// Construct a fresh Snapshot from the per-invocation data the
-    /// Runtime has just collected. Called from
-    /// `crate::runtime::Runtime::build_snapshot` once the
-    /// guest export has returned, the OUTCOME_BUFFER has been drained,
-    /// and the capture pipes have been clipped to their caps.
-    pub(crate) fn new(
-        return_bytes: Vec<u8>,
-        stdout_bytes: Vec<u8>,
-        stdout_truncated: bool,
-        stderr_bytes: Vec<u8>,
-        stderr_truncated: bool,
-        wall_time: Duration,
-        memory_peak: usize,
-    ) -> Self {
+    /// Bundle the success outputs the Runtime collected once the guest
+    /// export returned with an outcome: the drained OUTCOME_BUFFER bytes
+    /// and the capture pipes clipped to their caps.
+    pub(crate) fn new(return_bytes: Vec<u8>, stdout: Capture, stderr: Capture) -> Self {
         Self {
             return_bytes,
-            stdout_bytes,
-            stdout_truncated,
-            stderr_bytes,
-            stderr_truncated,
-            wall_time: Cell::new(wall_time),
-            memory_peak,
+            stdout,
+            stderr,
         }
     }
 
@@ -69,32 +44,24 @@ impl Snapshot {
 
     fn stdout_bytes(&self) -> RString {
         let ruby = Ruby::get().expect("Ruby thread");
-        ruby.str_from_slice(&self.stdout_bytes)
+        ruby.str_from_slice(&self.stdout.bytes)
     }
 
     fn stdout_truncated(&self) -> bool {
-        self.stdout_truncated
+        self.stdout.truncated
     }
 
     fn stderr_bytes(&self) -> RString {
         let ruby = Ruby::get().expect("Ruby thread");
-        ruby.str_from_slice(&self.stderr_bytes)
+        ruby.str_from_slice(&self.stderr.bytes)
     }
 
     fn stderr_truncated(&self) -> bool {
-        self.stderr_truncated
-    }
-
-    fn wall_time(&self) -> f64 {
-        self.wall_time.get().as_secs_f64()
-    }
-
-    fn memory_peak(&self) -> usize {
-        self.memory_peak
+        self.stderr.truncated
     }
 }
 
-/// Register `Kobako::Snapshot` plus its seven raw readers under the
+/// Register `Kobako::Snapshot` plus its five raw readers under the
 /// `Kobako` module. Called from `crate::init` after `Kobako::Runtime`
 /// is registered so the magnus wrap macro can resolve the class name.
 pub(crate) fn init(ruby: &Ruby, kobako: RModule) -> Result<(), MagnusError> {
@@ -104,7 +71,5 @@ pub(crate) fn init(ruby: &Ruby, kobako: RModule) -> Result<(), MagnusError> {
     snapshot.define_method("stdout_truncated", method!(Snapshot::stdout_truncated, 0))?;
     snapshot.define_method("stderr_bytes", method!(Snapshot::stderr_bytes, 0))?;
     snapshot.define_method("stderr_truncated", method!(Snapshot::stderr_truncated, 0))?;
-    snapshot.define_method("wall_time", method!(Snapshot::wall_time, 0))?;
-    snapshot.define_method("memory_peak", method!(Snapshot::memory_peak, 0))?;
     Ok(())
 }

data/lib/kobako/catalog/handles.rb

@@ -38,7 +38,7 @@ module Kobako
       # for it. +object+ is any host-side Ruby object to bind. Returns a
       # freshly-allocated +Kobako::Handle+ whose +#id+ falls in
       # +[Kobako::Handle::MIN_ID, Kobako::Handle::MAX_ID]+. Raises
-      # +Kobako::HandlerExhaustedError+ if the next ID would exceed the
+      # +Kobako::HandleExhaustedError+ if the next ID would exceed the
       # cap. The cap is anchored on +Kobako::Handle+ — the wire codec
       # and the allocator share the same invariant.
       #
@@ -96,12 +96,12 @@ module Kobako
       end
 
       # Guard {#alloc} against issuing an ID past the cap. Returns +nil+
-      # on success; raises +Kobako::HandlerExhaustedError+ at exhaustion.
+      # on success; raises +Kobako::HandleExhaustedError+ at exhaustion.
       def ensure_capacity!
         cap = Kobako::Handle::MAX_ID
         return unless @next_id > cap
 
-        raise HandlerExhaustedError,
+        raise HandleExhaustedError,
               "Out of handle allocations: too many host objects were referenced " \
               "in a single invocation (limit #{cap})"
       end

data/lib/kobako/catalog/namespaces.rb

@@ -82,6 +82,10 @@ module Kobako
       # first invocation, so the preamble is exactly the bindings that
       # existed at that moment — a bind reaching a +Kobako::Namespace+
       # after the seal raises +ArgumentError+ and never alters Frame 1.
+      # The memo is gated on the seal rather than dropped per mutation (the
+      # +Catalog::Snippets#encode+ approach) because a +Member+ bind lands
+      # on a child +Kobako::Namespace+, invisible to this collection; only
+      # the seal guarantees nothing further can change.
       def encode
         return @encoded if @encoded
 

data/lib/kobako/catalog/snippets.rb

@@ -44,6 +44,10 @@ module Kobako
       # The bytes are memoized — the table is replayed verbatim on every
       # invocation after sealing, so Frame 3 never changes between
       # encodes; {#register} drops the memo while the table is still open.
+      # Unlike +Catalog::Namespaces#encode+, which gates its memo on the
+      # seal, this one can fill eagerly and invalidate in +#register+
+      # because every mutation funnels through that single method — there is
+      # no out-of-sight child object to change the result behind its back.
       def encode
         return @encoded if @encoded
 

data/lib/kobako/codec/encoder.rb

@@ -26,7 +26,11 @@ module Kobako
       # mapping is a closed set, and anything outside it is rejected by
       # the msgpack gem itself (arbitrary objects raise +NoMethodError+
       # from missing +to_msgpack+, integers outside i64..u64 raise
-      # +RangeError+).
+      # +RangeError+). The +NoMethodError+ catch is deliberately broad:
+      # MessagePack signals "no wire representation" only through that error,
+      # so there is no narrower discriminator — a packer-internal
+      # +NoMethodError+ is likewise reported as +UnsupportedType+ rather than
+      # propagating.
       def self.encode(value)
         Factory.dump(value)
       rescue ::RangeError, ::NoMethodError => e

data/lib/kobako/codec/factory.rb

@@ -48,6 +48,16 @@ module Kobako
       EXT_ERRENV = 0x02
       private_constant :EXT_SYMBOL, :EXT_HANDLE, :EXT_ERRENV
 
+      # An ext 0x02 (Fault) envelope nests through its +details+ field, and
+      # each level re-enters the codec with a fresh +MessagePack+ unpacker
+      # whose built-in stack guard resets — so ext-envelope depth is tracked
+      # here instead. The cap matches the wire's overall nesting bound and
+      # keeps a nested chain from exhausting the native stack: an over-deep
+      # chain fails as a clean wire error, never a stack-level trap.
+      MAX_EXT_DEPTH = 128
+      EXT_DEPTH_KEY = :__kobako_codec_ext_depth__
+      private_constant :MAX_EXT_DEPTH, :EXT_DEPTH_KEY
+
       # Instance-level pass-through onto the wrapped +MessagePack::Factory+.
       # Spelled +def_instance_delegators+ rather than +def_delegators+ because
       # the class also extends +SingleForwardable+ (see the +extend+ block
@@ -129,9 +139,13 @@ module Kobako
       # Encode the inner ext-0x02 map via {Encoder} (not +factory.dump+) so
       # the embedded payload flows through the same boundary as a top-level
       # encode — nested kobako values (Handle, nested Fault) reach the
-      # registered ext-type packers via the cached singleton.
+      # registered ext-type packers via the cached singleton. A +details+
+      # chain nested past {MAX_EXT_DEPTH} has no wire representation and
+      # surfaces as +UnsupportedType+.
       def pack_fault(fault)
-        Encoder.encode("type" => fault.type, "message" => fault.message, "details" => fault.details)
+        within_ext_frame(UnsupportedType) do
+          Encoder.encode("type" => fault.type, "message" => fault.message, "details" => fault.details)
+        end
       end
 
       # Peel the embedded msgpack map and hand it to +Kobako::Fault.new+
@@ -139,19 +153,33 @@ module Kobako
       # +ArgumentError+ invariants surface as +InvalidType+ through the
       # decoder boundary. Inner decode goes through {Decoder} (not
       # +factory.load+) so the embedded +str+ payloads flow through the
-      # same UTF-8 validation as a top-level decode.
-      #
-      # This establishes a runtime cycle Factory → Decoder → Factory: the
-      # singleton instance feeds +Decoder.decode+, which re-enters this
-      # method when a nested ext 0x02 appears inside +details+. The recursion
-      # is bounded by msgpack nesting depth — identical to nested Array /
-      # Hash payloads — so no extra guard is needed. Do not switch back to
-      # +factory.load+ to "simplify": that path bypasses UTF-8 validation.
+      # same UTF-8 validation as a top-level decode. A nested ext 0x02 in
+      # +details+ re-enters this method, so {#within_ext_frame} bounds the
+      # chain depth to keep it from exhausting the native stack.
       def unpack_fault(payload)
-        Decoder.decode(payload) do |map|
-          raise InvalidType, "Fault payload must be a map" unless map.is_a?(Hash)
+        within_ext_frame(InvalidType) do
+          Decoder.decode(payload) do |map|
+            raise InvalidType, "Fault payload must be a map" unless map.is_a?(Hash)
+
+            Kobako::Fault.new(type: map["type"], message: map["message"], details: map["details"])
+          end
+        end
+      end
 
-          Kobako::Fault.new(type: map["type"], message: map["message"], details: map["details"])
+      # Track ext-envelope re-entry depth and refuse a chain past
+      # {MAX_EXT_DEPTH}, raising +over_limit+ so the failure lands in the
+      # caller's existing wire-error class. The counter is thread-scoped and
+      # balanced by the +ensure+, so a raise mid-chain still unwinds it to
+      # its entry value.
+      def within_ext_frame(over_limit)
+        depth = (Thread.current[EXT_DEPTH_KEY] || 0) + 1
+        raise over_limit, "ext envelope nesting exceeds #{MAX_EXT_DEPTH} levels" if depth > MAX_EXT_DEPTH
+
+        Thread.current[EXT_DEPTH_KEY] = depth
+        begin
+          yield
+        ensure
+          Thread.current[EXT_DEPTH_KEY] = depth - 1
         end
       end
     end

data/lib/kobako/codec/handle_walk.rb

@@ -8,8 +8,7 @@ module Kobako
     # 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
+    # host object on every guest→host value path. {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
@@ -82,11 +81,11 @@ module Kobako
       # +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.
+      # Handles back to their objects wherever a guest→host payload carries
+      # one — an invocation result, a yield-block result, or a dispatch
+      # argument. 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
@@ -98,6 +97,10 @@ module Kobako
         case value
         when ::Array then value.map { |element| HandleWalk.deep_restore(element, handler) }
         when ::Hash
+          # Rebuilt with each key restored: two distinct Handle keys that
+          # resolve to equal host objects collapse to the later pair, as in
+          # any Ruby Hash. The guest authored this payload, so that collapse
+          # is its own concern, not a fidelity guarantee the host owes it.
           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

data/lib/kobako/errors.rb

@@ -35,7 +35,7 @@ module Kobako
   #
   #   * {ModuleNotBuiltError} < {SetupError} — Guest Binary artifact absent
   #                       at +wasm_path+.
-  #   * {HandlerExhaustedError} < {SandboxError} — Handle id cap hit.
+  #   * {HandleExhaustedError} < {SandboxError} — Handle id cap hit.
 
   # Base for all kobako-raised errors so callers that want to ignore the
   # taxonomy can rescue a single class.
@@ -89,10 +89,13 @@ module Kobako
   # +ModuleNotBuiltError+ first.
   class ModuleNotBuiltError < SetupError; end
 
-  # Sandbox / wire layer. Raised when the guest ran to completion but
-  # execution failed due to a mruby script error, a protocol fault, or a
-  # host-side wire decode failure on an otherwise valid outcome tag.
-  class SandboxError < Error
+  # The structured attribution the two invocation-failure classes carry
+  # from a decoded guest exception — its +origin+, original +klass+,
+  # +backtrace_lines+, and +details+ — so a Host App can inspect a failure
+  # beyond its message. Mixed into both rather than promoted to a shared
+  # superclass because +SandboxError+ and +ServiceError+ sit in distinct
+  # branches of the invocation-outcome taxonomy under +Kobako::Error+.
+  module StructuredError
     attr_reader :origin, :klass, :backtrace_lines, :details
 
     def initialize(message, origin: nil, klass: nil, backtrace_lines: nil, details: nil)
@@ -104,26 +107,25 @@ module Kobako
     end
   end
 
+  # Sandbox / wire layer. Raised when the guest ran to completion but
+  # execution failed due to a mruby script error, a protocol fault, or a
+  # host-side wire decode failure on an otherwise valid outcome tag.
+  class SandboxError < Error
+    include StructuredError
+  end
+
   # Service layer. Raised when a Service capability call inside a mruby
   # script reported an application-level failure that the script did not
   # rescue.
   class ServiceError < Error
-    attr_reader :origin, :klass, :backtrace_lines, :details
-
-    def initialize(message, origin: nil, klass: nil, backtrace_lines: nil, details: nil)
-      super(message)
-      @origin = origin
-      @klass = klass
-      @backtrace_lines = backtrace_lines
-      @details = details
-    end
+    include StructuredError
   end
 
-  # HandlerExhaustedError is the canonical SandboxError subclass for the
+  # HandleExhaustedError is the canonical SandboxError subclass for the
   # id-cap-hit path. Raised when the per-invocation Handle ID counter in
   # Catalog::Handles reaches +0x7fff_ffff+ (2³¹ − 1) and further
   # allocation would exceed the cap.
-  class HandlerExhaustedError < SandboxError; end
+  class HandleExhaustedError < SandboxError; end
 
   # BytecodeError is the SandboxError subclass raised when a
   # `#preload(binary:)` snippet fails structural validation during the

data/lib/kobako/sandbox.rb

@@ -89,7 +89,9 @@ module Kobako
     # normalisation. The constructed +SandboxOptions+ is exposed as
     # +#options+ and the four caps remain readable directly on Sandbox via
     # +Forwardable+ delegation.
-    def initialize(wasm_path: nil, stdout_limit: nil, stderr_limit: nil,
+    def initialize(wasm_path: nil,
+                   stdout_limit: SandboxOptions::DEFAULT_OUTPUT_LIMIT,
+                   stderr_limit: SandboxOptions::DEFAULT_OUTPUT_LIMIT,
                    timeout: SandboxOptions::DEFAULT_TIMEOUT_SECONDS,
                    memory_limit: SandboxOptions::DEFAULT_MEMORY_LIMIT)
       @wasm_path = wasm_path || Kobako::Runtime.default_path
@@ -207,17 +209,17 @@ module Kobako
 
     private
 
-    # Configure the +Runtime+'s host↔guest dispatch wiring. Builds a
-    # lambda that re-enters the guest via
-    # +Runtime#yield_to_active_invocation+ and a dispatch +Proc+ that routes
-    # guest→host calls through the stateless +Transport::Dispatcher+,
-    # capturing +@services+ / +@handler+ in the closure. Both are registered
-    # on the +Runtime+ once at construction time so the wasm ext callback can
-    # fire without further setup.
+    # Configure the +Runtime+'s host↔guest dispatch wiring. Registers a
+    # dispatch +Proc+ that routes guest→host calls through the stateless
+    # +Transport::Dispatcher+, capturing +@services+ / +@handler+ in the
+    # closure. The ext hands the +Proc+ a per-dispatch +guest_yielder+ — a
+    # +String → String+ callable that re-enters the in-flight guest to run a
+    # yielded block — which the +Dispatcher+ forwards to the +Transport::Yielder+
+    # it builds for the call. Registered once at construction time so the
+    # wasm ext callback can fire without further setup.
     def install_dispatch_proc!
-      yield_to_guest = ->(args_bytes) { @runtime.yield_to_active_invocation(args_bytes) }
-      @runtime.on_dispatch = lambda do |request_bytes|
-        Transport::Dispatcher.dispatch(request_bytes, @services, @handler, yield_to_guest)
+      @runtime.on_dispatch = lambda do |request_bytes, guest_yielder|
+        Transport::Dispatcher.dispatch(request_bytes, @services, @handler, guest_yielder)
       end
     end
 
@@ -226,8 +228,7 @@ module Kobako
     # state — capture buffers, truncation predicates, and the
     # +Catalog::Handles+ counter — before the guest runs. The
     # +Catalog::Handles+ itself is held as +@handler+ and never exposed
-    # beyond this class: SPEC.md Terminology pins it as "Not exposed to the
-    # Host App".
+    # beyond this class — it is not part of the Host App's surface.
     def begin_invocation!
       @services.seal!
       @handler.reset!
@@ -239,9 +240,10 @@ module Kobako
     # the +invoke!+ +ensure+ block so the usage record is populated on
     # every outcome — value return, +Kobako::TrapError+ (including
     # +TimeoutError+ / +MemoryLimitError+), +Kobako::SandboxError+,
-    # and +Kobako::ServiceError+. On the success path the same figures
-    # already arrive via +Snapshot#usage+; on the trap path the Snapshot
-    # never reaches Ruby so the ext readout here is the only source.
+    # and +Kobako::ServiceError+. +Runtime#usage+ is the single source for
+    # both paths: the figures are stashed in the ext on every outcome, so
+    # unlike the +Snapshot+ (built only on success) the readout here also
+    # covers the trap path.
     #
     # The ext returns a positional 2-tuple +[wall_time, memory_peak]+
     # whose order matches the +Kobako::Usage+ field order; the
@@ -272,8 +274,8 @@ module Kobako
     # TrapError message so the failing export is identifiable.
     #
     # The yielded block must return a +Kobako::Snapshot+ — i.e. the
-    # value of +Runtime#eval+ / +#run+ (SPEC.md Internal Concepts →
-    # Snapshot). The success path unpacks +#stdout+ / +#stderr+ into
+    # value of +Runtime#eval+ / +#run+. The success path unpacks
+    # +#stdout+ / +#stderr+ into
     # +Capture+ and feeds +#return_bytes+ to +Outcome.decode+; usage is
     # populated by the +ensure+ readout ({#read_usage!}) on every outcome.
     # The rescue chain is the single trap-translation boundary —

data/lib/kobako/sandbox_options.rb

@@ -6,11 +6,13 @@ module Kobako
   # Data.define(...)+ subclass form (the Steep-friendly shape — see
   # +lib/kobako/outcome/panic.rb+).
   #
-  # The +initialize+ method does double duty: it applies DEFAULT fallback
-  # for absent values and normalises (timeout to Float seconds,
-  # memory_limit to positive Integer bytes) before delegating to Data's
-  # +super+. Anything that survives +SandboxOptions.new+ is a wire-ready
-  # cap bundle the +Kobako::Runtime+ constructor consumes as-is.
+  # The +initialize+ normalises every cap before delegating to Data's
+  # +super+: +timeout+ to Float seconds, +memory_limit+ / +stdout_limit+ /
+  # +stderr_limit+ to positive Integer bytes. Each cap is +nil+-disablable
+  # (an absent argument takes its DEFAULT; an explicit +nil+ leaves the
+  # bound off), so all four behave uniformly. Anything that survives
+  # +SandboxOptions.new+ is a wire-ready cap bundle the +Kobako::Runtime+
+  # constructor consumes as-is.
   class SandboxOptions < Data.define(:timeout, :memory_limit, :stdout_limit, :stderr_limit)
     # Default wall-clock timeout for a single invocation: 60 seconds.
     DEFAULT_TIMEOUT_SECONDS = 60.0
@@ -25,12 +27,12 @@ module Kobako
 
     def initialize(timeout: DEFAULT_TIMEOUT_SECONDS,
                    memory_limit: DEFAULT_MEMORY_LIMIT,
-                   stdout_limit: nil,
-                   stderr_limit: nil)
+                   stdout_limit: DEFAULT_OUTPUT_LIMIT,
+                   stderr_limit: DEFAULT_OUTPUT_LIMIT)
       timeout = normalize_timeout(timeout)
       memory_limit = normalize_memory_limit(memory_limit)
-      stdout_limit ||= DEFAULT_OUTPUT_LIMIT
-      stderr_limit ||= DEFAULT_OUTPUT_LIMIT
+      stdout_limit = normalize_output_limit(stdout_limit, "stdout_limit")
+      stderr_limit = normalize_output_limit(stderr_limit, "stderr_limit")
       super
     end
 
@@ -62,5 +64,19 @@ module Kobako
 
       memory_limit
     end
+
+    # Coerce a per-channel output cap (+stdout_limit+ / +stderr_limit+)
+    # into the byte cap the ext expects, or +nil+ to leave the channel
+    # uncapped. Same shape as +normalize_memory_limit+: a positive Integer
+    # when set, Float / zero / negative rejected. +name+ tags the
+    # +ArgumentError+ with the offending keyword.
+    def normalize_output_limit(limit, name)
+      return nil if limit.nil?
+      unless limit.is_a?(Integer) && limit.positive?
+        raise ArgumentError, "#{name} must be a positive Integer or nil, got #{limit.inspect}"
+      end
+
+      limit
+    end
   end
 end

data/lib/kobako/snapshot.rb

@@ -1,19 +1,19 @@
 # frozen_string_literal: true
 
 require_relative "capture"
-require_relative "usage"
 
 module Kobako
   # Kobako::Snapshot — per-invocation observable bundle returned from
   # +Kobako::Runtime#eval+ and +#run+.
   #
-  # The magnus class (see ext/kobako/src/snapshot.rs) carries seven raw
+  # The magnus class (see ext/kobako/src/snapshot.rs) carries five raw
   # readers: +return_bytes+, +stdout_bytes+, +stdout_truncated+,
-  # +stderr_bytes+, +stderr_truncated+, +wall_time+, +memory_peak+. This
-  # file reopens the class to add the Ruby-side helpers that pack those
-  # raw fields into the user-facing value objects +Kobako::Capture+ and
-  # +Kobako::Usage+ — the same shape +Kobako::Sandbox+ exposes to the
-  # Host App.
+  # +stderr_bytes+, +stderr_truncated+. This file reopens the class to add
+  # the Ruby-side helpers that pack those raw fields into the user-facing
+  # value object +Kobako::Capture+ — the same shape +Kobako::Sandbox+
+  # exposes to the Host App. Usage is not on the Snapshot; +Sandbox#usage+
+  # reads it from +Kobako::Runtime#usage+, which also covers the trap path
+  # where no Snapshot is produced.
   class Snapshot
     # Wrap the stdout capture pair (+stdout_bytes+, +stdout_truncated+)
     # as a +Kobako::Capture+ value object. The byte content never carries
@@ -28,11 +28,5 @@ module Kobako
     def stderr
       Capture.new(bytes: stderr_bytes, truncated: stderr_truncated)
     end
-
-    # Wrap the per-last-invocation usage pair (+wall_time+,
-    # +memory_peak+) as a +Kobako::Usage+ value object.
-    def usage
-      Usage.new(wall_time: wall_time, memory_peak: memory_peak)
-    end
   end
 end

data/lib/kobako/transport/dispatcher.rb

@@ -72,8 +72,8 @@ module Kobako
       # closure so the Dispatcher stays stateless and the registry doesn't
       # need to publish accessors for the Sandbox-owned +Catalog::Handles+
       # or +Runtime+. +yield_to_guest+ is a +String → String+ callable
-      # (typically +Runtime#yield_to_active_invocation+ bound as a lambda)
-      # used only when the Request carries +block_given: true+. Always
+      # (the ext's per-dispatch +Kobako::Runtime::GuestYielder+) used only
+      # when the Request carries +block_given: true+. Always
       # returns a binary String — every failure path is reified as a
       # Response.error envelope so the guest sees a transport error rather
       # than a wasm trap.
@@ -170,12 +170,14 @@ module Kobako
         raise UndefinedTargetError, "method #{name.inspect} is not exposed to the guest"
       end
 
-      # A Kobako::Handle arriving as a positional or keyword
-      # argument identifies a host-side object previously allocated by a prior
-      # transport call's Handle wrap. Resolve it back to the Ruby object before
-      # the dispatch reaches +public_send+.
+      # Resolve every Kobako::Handle in an argument — bare or nested in an
+      # Array / Hash — back to its host object before the dispatch reaches
+      # +public_send+, symmetric with the guest→host return path. A Handle id
+      # with no live entry surfaces as an unrecognized target.
       def resolve_arg(value, handler)
-        value.is_a?(Kobako::Handle) ? require_live_object!(value.id, handler) : value
+        Kobako::Codec::HandleWalk.deep_restore(value, handler)
+      rescue Kobako::SandboxError => e
+        raise UndefinedTargetError, e.message
       end
 
       # Resolve a Request target to the Ruby object the registry (or
@@ -190,7 +192,7 @@ module Kobako
         when String
           resolve_path(target, namespaces)
         when Kobako::Handle
-          resolve_handle(target, handler)
+          require_live_object!(target.id, handler)
         end
       end
 
@@ -200,10 +202,6 @@ module Kobako
         raise UndefinedTargetError, e.message
       end
 
-      def resolve_handle(handle, handler)
-        require_live_object!(handle.id, handler)
-      end
-
       # Resolve +id+ through the Catalog::Handles. An unknown id
       # surfaces as UndefinedTargetError.
       def require_live_object!(id, handler)

data/lib/kobako/transport/response.rb

@@ -38,20 +38,6 @@ module Kobako
         new(status: STATUS_ERROR, payload: fault)
       end
 
-      # Decode +bytes+ into a {Response}. Raises +Codec::InvalidType+ when the
-      # envelope is not the expected 2-element msgpack array, or when the
-      # Value Object's construction invariants reject the decoded fields.
-      def self.decode(bytes)
-        Codec::Decoder.decode(bytes) do |arr|
-          unless arr.is_a?(Array) && arr.length == 2
-            raise Codec::InvalidType, "Response envelope is malformed (expected a 2-element array)"
-          end
-
-          status, payload = arr
-          new(status: status, payload: payload)
-        end
-      end
-
       def initialize(status:, payload:)
         unless [STATUS_OK, STATUS_ERROR].include?(status)
           raise ArgumentError, "Response status must be 0 (ok) or 1 (error), got #{status.inspect}"
@@ -71,6 +57,20 @@ module Kobako
       def encode
         Codec::Encoder.encode([status, payload])
       end
+
+      # Decode +bytes+ into a {Response}. Raises +Codec::InvalidType+ when the
+      # envelope is not the expected 2-element msgpack array, or when the
+      # Value Object's construction invariants reject the decoded fields.
+      def self.decode(bytes)
+        Codec::Decoder.decode(bytes) do |arr|
+          unless arr.is_a?(Array) && arr.length == 2
+            raise Codec::InvalidType, "Response envelope is malformed (expected a 2-element array)"
+          end
+
+          status, payload = arr
+          new(status: status, payload: payload)
+        end
+      end
     end
   end
 end