kobako 0.27.0-aarch64-linux → 0.28.0-aarch64-linux

data/lib/kobako/sandbox_options.rb

@@ -3,52 +3,42 @@
 require_relative "errors"
 
 module Kobako
-  # Kobako::SandboxOptions — immutable Value Object holding the four
-  # per-Sandbox configuration caps and the requested isolation profile.
-  # Built on the +class X < Data.define(...)+ subclass form (the
-  # Steep-friendly shape — see +.rubocop.yml+ for the rationale).
+  # The options a Sandbox was built with, read through Sandbox#options or
+  # directly on the Sandbox, as in Sandbox#timeout. A cap left out takes its
+  # default, and +nil+ switches it off.
   #
-  # The +initialize+ normalises every option 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. +profile+ is the one
-  # non-cap: a Symbol on the PROFILES ladder naming the posture the
-  # runtime builds, which is also the weakest the Host App accepts —
-  # +nil+ is rejected because the weakest posture is requested as an
-  # explicit +:permissive+. Anything that survives +SandboxOptions.new+
-  # is a wire-ready bundle the +Kobako::Runtime+ constructor consumes
-  # as-is. The options also own the ladder comparison
-  # (+#enforce_floor!+) that +Kobako::Sandbox+ delegates its
-  # construction floor check to.
+  # [+timeout+]       Float seconds one invocation may run.
+  # [+memory_limit+]  Integer bytes one invocation may grow guest memory by.
+  # [+stdout_limit+, +stderr_limit+]
+  #                   Integer bytes kept from each output channel.
+  # [+profile+]       The isolation the runtime must provide, one of PROFILES.
+  # [+gvl+]           How an invocation holds Ruby's GVL, one of GVL_MODES.
+  #
+  # Raises ArgumentError for a value outside these shapes, and SetupError
+  # when the runtime provides less isolation than +profile+ asks for.
   class SandboxOptions < Data.define(:timeout, :memory_limit, :stdout_limit, :stderr_limit, :profile, :gvl)
-    # Default wall-clock timeout for a single invocation: 60 seconds.
+    # The default +timeout+: 60 seconds.
     DEFAULT_TIMEOUT_SECONDS = 60.0
 
-    # Default cap on the per-invocation guest linear-memory delta:
-    # 1 MiB. The mruby image's initial allocation and prior invocations'
-    # watermark sit outside this budget.
+    # The default +memory_limit+: 1 MiB of growth past the guest's starting
+    # memory.
     DEFAULT_MEMORY_LIMIT = 1 << 20
 
-    # Default per-channel capture ceiling: 1 MiB.
+    # The default +stdout_limit+ and +stderr_limit+: 1 MiB each.
     DEFAULT_OUTPUT_LIMIT = 1 << 20
 
-    # The isolation ladder, weakest first — index order is rank order,
-    # so a floor check is an index comparison.
+    # The isolation profiles, weakest first. +:hermetic+ denies the guest the
+    # clock and entropy; +:permissive+ leaves them live.
     PROFILES = %i[permissive hermetic].freeze
 
-    # Default isolation profile: the strictest rung — opting down to
-    # +:permissive+ is the Host App's explicit trade.
+    # The default +profile+, the strictest.
     DEFAULT_PROFILE = :hermetic
 
-    # The GVL scheduling modes: +:hold+ keeps Ruby's GVL for the whole
-    # invocation, +:release+ drops it for the guest span so distinct
-    # Sandboxes on distinct Threads run their guest code in parallel.
+    # +:hold+ keeps the GVL through the invocation; +:release+ drops it while
+    # the guest runs, so Sandboxes on different Threads run in parallel.
     GVL_MODES = %i[hold release].freeze
 
-    # Default GVL mode: +:hold+ — holding the GVL matches single-threaded
-    # execution, so +:release+ is the Host App's explicit opt-in for
-    # host-parallel guest execution.
+    # The default +gvl+, +:hold+.
     DEFAULT_GVL = :hold
 
     def initialize(timeout: DEFAULT_TIMEOUT_SECONDS,
@@ -58,22 +48,17 @@ module Kobako
                    profile: DEFAULT_PROFILE,
                    gvl: DEFAULT_GVL)
       timeout = normalize_timeout(timeout)
-      memory_limit = normalize_memory_limit(memory_limit)
-      stdout_limit = normalize_output_limit(stdout_limit, "stdout_limit")
-      stderr_limit = normalize_output_limit(stderr_limit, "stderr_limit")
-      profile = normalize_profile(profile)
-      gvl = normalize_gvl(gvl)
+      memory_limit = normalize_byte_limit(memory_limit, "memory_limit")
+      stdout_limit = normalize_byte_limit(stdout_limit, "stdout_limit")
+      stderr_limit = normalize_byte_limit(stderr_limit, "stderr_limit")
+      profile = normalize_choice(profile, PROFILES, "profile")
+      gvl = normalize_choice(gvl, GVL_MODES, "gvl")
       super
     end
 
-    # Enforce the requested +profile+ as the floor against +declared+ —
-    # the posture a runtime reports having built — so a runtime that
-    # cannot honor the request fails construction with
-    # +Kobako::SetupError+ instead of weakening the posture silently.
-    # Both fallbacks fail closed: a declaration off the PROFILES ladder
-    # ranks below every request, and a request off the ladder
-    # (unreachable past +initialize+) refuses every declaration.
-    def enforce_floor!(declared)
+    # Both fallbacks fail closed: an unknown declaration ranks below every
+    # request, and an unknown request refuses every declaration.
+    def enforce_floor!(declared) # :nodoc:
       return if (PROFILES.index(declared) || -1) >= (PROFILES.index(profile) || PROFILES.size)
 
       raise Kobako::SetupError, "runtime declares isolation profile #{declared.inspect}, " \
@@ -82,11 +67,8 @@ module Kobako
 
     private
 
-    # Coerce +timeout+ into the Float seconds the ext expects, or +nil+
-    # to mean the cap is disabled. Any finite non-positive value is
-    # rejected — a zero or negative timeout would either fire instantly
-    # or never, both of which would surprise callers more than an early
-    # +ArgumentError+.
+    # A zero or negative timeout would either fire instantly or never, both
+    # more surprising than an early ArgumentError.
     def normalize_timeout(timeout)
       return nil if timeout.nil?
       raise ArgumentError, "timeout must be Numeric or nil, got #{timeout.class}" unless timeout.is_a?(Numeric)
@@ -97,24 +79,7 @@ module Kobako
       seconds
     end
 
-    # Coerce +memory_limit+ into the byte cap the ext expects, or +nil+
-    # to mean unbounded. Must be a positive Integer when set; Float or
-    # zero/negative values are rejected.
-    def normalize_memory_limit(memory_limit)
-      return nil if memory_limit.nil?
-      unless memory_limit.is_a?(Integer) && memory_limit.positive?
-        raise ArgumentError, "memory_limit must be a positive Integer or nil, got #{memory_limit.inspect}"
-      end
-
-      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)
+    def normalize_byte_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}"
@@ -123,23 +88,12 @@ module Kobako
       limit
     end
 
-    # Validate +profile+ against the PROFILES ladder. Unlike the caps
-    # there is no +nil+ form: the weakest posture is requested as an
-    # explicit +:permissive+, so anything off the ladder — +nil+
-    # included — is rejected.
-    def normalize_profile(profile)
-      return profile if PROFILES.include?(profile)
-
-      raise ArgumentError, "profile must be one of #{PROFILES.map(&:inspect).join(", ")}, got #{profile.inspect}"
-    end
-
-    # Validate +gvl+ against GVL_MODES. Like +profile+ it has no +nil+
-    # form: the scheduling mode is requested as an explicit Symbol, so
-    # anything off the set — +nil+ included — is rejected.
-    def normalize_gvl(gvl)
-      return gvl if GVL_MODES.include?(gvl)
+    # Unlike the caps there is no +nil+ form: every choice, the weakest
+    # included, is requested by name, as in +:permissive+.
+    def normalize_choice(value, choices, name)
+      return value if choices.include?(value)
 
-      raise ArgumentError, "gvl must be one of #{GVL_MODES.map(&:inspect).join(", ")}, got #{gvl.inspect}"
+      raise ArgumentError, "#{name} must be one of #{choices.map(&:inspect).join(", ")}, got #{value.inspect}"
     end
   end
 end

data/lib/kobako/snippet/binary.rb

@@ -2,22 +2,7 @@
 
 module Kobako
   module Snippet
-    # Kobako::Snippet::Binary — value object representing a single
-    # +#preload(binary:)+ entry held by +Kobako::Catalog::Snippets+.
-    #
-    # The +body+ is RITE bytecode (as emitted by +mrbc+) carried as an
-    # +ASCII_8BIT+ String so msgpack-ruby encodes it as +bin+ family on
-    # the wire ({docs/wire-codec.md Invocation channels}[link:../../../docs/wire-codec.md]).
-    # The host treats the bytes as opaque — the snippet's canonical
-    # name, when present, lives in the bytecode's embedded +debug_info+
-    # and is resolved by the guest at load time; structural validation
-    # is deferred to the first invocation's guest replay.
-    #
-    # The class is a +Data.define+ subclass — frozen and value-equal.
-    # Callers (chiefly +Catalog::Snippets+) construct instances via keyword
-    # form +Binary.new(body: ...)+. Wire-form construction is the
-    # registry's responsibility.
-    class Binary < Data.define(:body)
+    class Binary < Data.define(:body) # :nodoc:
       # Names the snippet form the guest replays this entry as. The wire's
       # discriminant byte is assigned by the core envelope, not here.
       KIND = :bytecode

data/lib/kobako/snippet/source.rb

@@ -2,22 +2,7 @@
 
 module Kobako
   module Snippet
-    # Kobako::Snippet::Source — value object representing a single
-    # +#preload(code:, name:)+ entry held by +Kobako::Catalog::Snippets+.
-    #
-    # +name+ is the canonical +Symbol+ identity baked into the loaded
-    # IREP's +debug_info+; backtrace frames originating in this snippet
-    # surface as +(snippet:Name):line+. +body+ is the UTF-8 mruby source
-    # detached from the caller's reference at +Catalog::Snippets#register+
-    # time so later mutation of the original String cannot bleed through.
-    #
-    # The class is a +Data.define+ subclass — frozen, value-equal, and
-    # carries no mutation API. Callers (chiefly +Catalog::Snippets+)
-    # construct instances via keyword form +Source.new(name: ..., body: ...)+.
-    # Wire-form construction is the registry's responsibility: as a leaf
-    # carrier this Source stays pure and +Catalog::Snippets#entries+ reads
-    # its attributes off the outside rather than asking it to project itself.
-    class Source < Data.define(:name, :body)
+    class Source < Data.define(:name, :body) # :nodoc:
       # Names the snippet form the guest replays this entry as. The wire's
       # discriminant byte is assigned by the core envelope, not here.
       KIND = :source

data/lib/kobako/snippet.rb

@@ -4,14 +4,6 @@ require_relative "snippet/binary"
 require_relative "snippet/source"
 
 module Kobako
-  # Kobako::Snippet — value-object family for preloaded snippet entries
-  # held by +Kobako::Catalog::Snippets+.
-  #
-  # +Source+ represents a single +#preload(code:, name:)+ entry; +Binary+
-  # represents a single +#preload(binary:)+ entry. Both are plain value
-  # objects with no dependency on the +Catalog::Snippets+ registry that
-  # holds them — the registry reads their attributes externally into the
-  # tuples the native side frames.
-  module Snippet
+  module Snippet # :nodoc:
   end
 end

data/lib/kobako/transport/call.rb

@@ -2,20 +2,7 @@
 
 module Kobako
   module Transport
-    # One guest-initiated dispatch, as the native side decoded it off the
-    # core envelope. The routing fields arrive already decoded — a String
-    # for a bound constant's path, an Integer for a Capability Handle id —
-    # so the host resolves a target without interpreting a payload byte.
-    #
-    # +payload+ stays bytes here on purpose: routing never interprets a
-    # payload byte, and the one place that does — the Dispatcher — must
-    # decode it inside the Codec bracket that records whether a Handle
-    # crossed.
-    #
-    # Built on the +class X < Data.define(...)+ subclass form so the class
-    # body is fully Steep-visible; see +.rubocop.yml+ for the
-    # rationale.
-    class Call < Data.define(:target, :method_name, :block_given, :payload)
+    class Call < Data.define(:target, :method_name, :block_given, :payload) # :nodoc:
     end
   end
 end

data/lib/kobako/transport/dispatcher.rb

@@ -8,39 +8,20 @@ require_relative "reflection"
 require_relative "yielder"
 
 module Kobako
-  # See lib/kobako/transport.rb for the umbrella module doc; this file
-  # owns the pure-function dispatcher that answers a routed Call.
   module Transport
-    # Pure-function dispatcher for guest-initiated Calls. The native side
-    # has already decoded the core envelope, so this resolves the target
-    # through the per-invocation path +resolver+ (the +Context+, whose
-    # +#lookup+ layers per-invocation providers over the static bindings)
-    # or Catalog::Handles, decodes only the payload, invokes the method,
-    # and answers +[ok, bytes]+ — which the native side puts on the
-    # Reply's ok or fault arm. It never raises.
-    #
-    # The module is stateless — all mutable state is threaded through
-    # arguments so Dispatcher has no instance variables and no side
-    # effects beyond mutating the Catalog::Handles via +alloc+ when a
-    # non-wire-representable return value must be wrapped.
-    module Dispatcher
+    # Answers a routed Call with +[true, body, nil]+ or
+    # +[false, message, fault_type]+ and never raises, so every failure
+    # reaches the guest as a fault.
+    module Dispatcher # :nodoc:
       # Throw tag for the Yielder's break unwind back to the
       # dispatcher's +catch+ frame. +private_constant+ is a
       # convention boundary — not a defence.
       BREAK_THROW = :__kobako_break__
       private_constant :BREAK_THROW
 
-      module_function
+      class UndefinedTargetError < StandardError; end # :nodoc:
 
-      # Internal sentinel raised when target resolution fails. Becomes a
-      # Fault with type="undefined". Contained at the wire boundary —
-      # not part of the public Kobako error taxonomy.
-      class UndefinedTargetError < StandardError; end
-
-      # The codec fault of a request that never became a call, restated in
-      # the vocabulary the guest can act on while staying inside the codec
-      # taxonomy the fault boundary sorts on.
-      class UnreadableRequestError < Kobako::Codec::Error; end
+      class UnreadableRequestError < Kobako::Codec::Error; end # :nodoc:
 
       # The category kobako's own refusals answer under, keyed by the class
       # each is raised as and ordered most specific first. A class absent
@@ -55,30 +36,18 @@ module Kobako
         UndefinedTargetError => "undefined",
         ArgumentError => "argument",
         YieldValueError => "runtime",
+        UnsupportedError => "runtime",
         Kobako::Codec::Error => "internal",
         Kobako::SandboxError => "runtime"
       }.freeze
       private_constant :OWN_FAULTS
 
-      # Answer a single routed Call with +[ok, bytes]+, which the native
-      # side puts on the Reply's ok or fault arm. Invoked from the
-      # per-invocation dispatch Proc that
-      # +Kobako::Context+ hands to +Runtime#eval+ / +#run+; +resolver+,
-      # +handler+, and +yield_to_guest+ are captured in that Proc's
-      # closure so the Dispatcher stays stateless and neither the resolver
-      # nor the Context needs to publish accessors for the per-invocation
-      # +Catalog::Handles+ or +Runtime+. +yield_to_guest+ is a +String → String+ callable
-      # (the ext's per-dispatch +Kobako::Runtime::GuestYielder+) used only
-      # when the Call carries +block_given: true+. Never raises — every
-      # failure path takes the fault arm instead, so the guest sees a
-      # transport error rather than a wasm trap.
-      #
-      # The decode runs inside +Codec.track_handles+ so #resolve_call_args
-      # can skip the argument walk when no Capability Handle crossed the
-      # wire.
-      def dispatch(call, resolver, handler, yield_to_guest)
-        yielder = Yielder.new(yield_to_guest, BREAK_THROW, handler) if call.block_given
-        [true, encode_ok(run(call, resolver, handler, yielder), handler), nil] # : [bool, String, String?]
+      # The per-invocation state arrives as arguments so the Dispatcher
+      # stays stateless and neither the resolver nor the Context publishes
+      # accessors for it.
+      def self.dispatch(call, resolver, handles, guest_yielder)
+        yielder = Yielder.new(guest_yielder, BREAK_THROW, handles) if call.block_given
+        [true, encode_ok(run(call, resolver, handles, yielder), handles), nil] # : [bool, String, String?]
       # StandardError is the boundary by intent: a Service method's
       # application fault folds into a guest-rescuable fault, while a
       # host-process failure (NoMemoryError, SignalException, a bare Exception)
@@ -90,172 +59,120 @@ module Kobako
         yielder&.invalidate!
       end
 
-      # Decode the payload, resolve the receiver, and run the method inside
-      # the +catch+ frame a guest +break+ unwinds to. Split from #dispatch
-      # so the reply-shaping and the failure boundary stay one glance wide.
-      def run(call, resolver, handler, yielder)
-        arguments, carried_handle = decode_arguments(call.payload)
-        exposure = resolve_target(call.target, resolver, handler)
-        args, kwargs = resolve_call_args(arguments, handler, carried_handle)
-        catch(BREAK_THROW) { invoke(exposure, call.method_name, args, kwargs, yielder) }
-      end
-
-      # Decode the Call's payload into its arguments, reporting whether any
-      # Capability Handle crossed. A codec fault here is a request that
-      # never became a call, restated so it cannot read as an unwritable
-      # reply — the same restatement #encode_ok makes in the other
-      # direction.
-      def decode_arguments(payload)
-        Kobako::Codec.track_handles { Payload::Arguments.decode(payload) }
-      rescue Kobako::Codec::Error => e
-        raise UnreadableRequestError, "Sandbox could not read the request: #{e.message}"
-      end
-
-      # Resolve positional and keyword arguments off the decoded payload in
-      # one step. +carried_handle+ reports whether the decode carried any
-      # Capability Handle; when it did not, every argument resolves to
-      # itself, so the decoded values pass straight through and the walk is
-      # skipped entirely. Otherwise both go through #resolve_arg so Handles
-      # round-trip back to the host-side Ruby object before the call reaches
-      # +public_send+.
-      def resolve_call_args(arguments, handler, carried_handle)
-        return [arguments.args, arguments.kwargs] unless carried_handle
+      class << self
+        private
 
-        [arguments.args.map { |v| resolve_arg(v, handler) },
-         arguments.kwargs.transform_values { |v| resolve_arg(v, handler) }]
-      end
+        def run(call, resolver, handles, yielder)
+          arguments, carried_handle = decode_arguments(call.payload)
+          exposure = resolve_target(call.target, resolver, handles)
+          args, kwargs = resolve_call_args(arguments, handles, carried_handle)
+          catch(BREAK_THROW) { invoke(exposure, call.method_name, args, kwargs, yielder) }
+        end
 
-      # Map an error caught at the dispatch boundary to the message and the
-      # category the native side frames into the Reply's fault arm. +error+
-      # is the +StandardError+ caught by #dispatch's rescue; the category
-      # tells the guest which kind of failure it was so it can raise the
-      # matching proxy-side error.
-      #
-      # The class prefix marks a Service's own exception and nothing else:
-      # it is the +<class>: <message>+ shape a Host App is told to keep
-      # secrets out of, so wearing it says the Service raised. kobako's own
-      # refusals answer under their own wording instead of borrowing that
-      # shape.
-      #
-      # The guest's own block failing is not the Service's to report at
-      # all, so the Yielder that raised it is asked first — it recognises
-      # its own by identity and words the failure the guest's way.
-      def caught_fault(error, yielder)
-        block_failure = yielder&.fault_text(error)
-        return fault("block", block_failure) if block_failure
+        # A codec fault here is a request that never became a call, restated
+        # so it cannot read as an unwritable reply.
+        def decode_arguments(payload)
+          Kobako::Codec.track_handles { Payload::Arguments.decode(payload) }
+        rescue Kobako::Codec::Error => e
+          raise UnreadableRequestError, "Sandbox could not read the request: #{e.message}"
+        end
 
-        own = OWN_FAULTS.find { |klass, _| error.is_a?(klass) }
-        return fault(own.last, error.message) if own
+        def resolve_call_args(arguments, handles, carried_handle)
+          return [arguments.args, arguments.kwargs] unless carried_handle
 
-        fault("runtime", "#{error.class}: #{error.message}")
-      end
+          [arguments.args.map { |v| resolve_arg(v, handles) },
+           arguments.kwargs.transform_values { |v| resolve_arg(v, handles) }]
+        end
 
-      # Dispatch +method+ on the object behind +exposure+, once the Exposure
-      # the guest's reference carries permits it. +kwargs+ is already
-      # Symbol-keyed (the +Payload::Arguments+ invariant pins it). The
-      # empty-kwargs branch omits the +**+ splat so Ruby 3.x's strict kwargs
-      # separation does not reject calls to no-kwarg methods when the wire
-      # carries the uniform empty-map shape.
-      #
-      # +yielder+ is the host-side Yielder materialised when the guest
-      # call site supplied a block; its Yielder#to_proc
-      # rides the +&block+ slot. +&nil+ is a no-op block argument in Ruby,
-      # so the same call site handles both cases without an explicit
-      # conditional.
-      def invoke(exposure, method, args, kwargs, yielder = nil)
-        name = method.to_sym
-        reject_unreachable!(exposure, name)
-        target = exposure.object
-        block = yielder&.to_proc
-        if kwargs.empty?
-          target.public_send(name, *args, &block)
-        else
-          target.public_send(name, *args, **kwargs, &block)
+        # The class prefix marks a Service's own exception and nothing else:
+        # it is the +<class>: <message>+ shape a Host App is told to keep
+        # secrets out of, so wearing it says the Service raised. kobako's own
+        # refusals answer under their own wording instead of borrowing that
+        # shape.
+        #
+        # The guest's own block failing is not the Service's to report at
+        # all, so the Yielder that raised it is asked first — it recognises
+        # its own by identity and words the failure the guest's way.
+        def caught_fault(error, yielder)
+          block_failure = yielder&.fault_text(error)
+          return fault("block", block_failure) if block_failure
+
+          own = OWN_FAULTS.find { |klass, _| error.is_a?(klass) }
+          return fault(own.last, error.message) if own
+
+          fault("runtime", "#{error.class}: #{error.message}")
         end
-      end
 
-      # Guard the +public_send+ below: Reflection decides what counts as
-      # Service behaviour through this reference, and its refusal reason
-      # becomes the guest's +undefined+ fault. Both the ambient-surface
-      # floor and the reference's Exposure answer through it, so a rejected
-      # name discloses nothing about which of the two refused.
-      def reject_unreachable!(exposure, name)
-        reason = Reflection.refusal(exposure, name)
-        raise UndefinedTargetError, reason if reason
-      end
+        # The wire always carries a keyword map, so an empty one is left
+        # unsplatted for methods that take no keywords.
+        def invoke(exposure, method, args, kwargs, yielder)
+          name = method.to_sym
+          reject_unreachable!(exposure, name)
+          target = exposure.object
+          block = yielder&.to_proc
+          if kwargs.empty?
+            target.public_send(name, *args, &block)
+          else
+            target.public_send(name, *args, **kwargs, &block)
+          end
+        end
 
-      # 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)
-        Kobako::Codec::HandleWalk.deep_restore(value, handler)
-      rescue Kobako::SandboxError => e
-        raise UndefinedTargetError, e.message
-      end
+        # Both the ambient-surface floor and the reference's Exposure answer
+        # through Reflection, so a rejected name discloses nothing about
+        # which of the two refused.
+        def reject_unreachable!(exposure, name)
+          reason = Reflection.refusal(exposure, name)
+          raise UndefinedTargetError, reason if reason
+        end
 
-      # Resolve a Call target to the Exposure the path +resolver+ (or
-      # Catalog::Handles) holds for it. The native side already
-      # discriminated the two forms off the core envelope's +kind+ tag: a
-      # String is a bound constant's path, an Integer is a Capability Handle
-      # id. No else-branch is needed — the envelope layer is the system
-      # boundary that enforces the invariant.
-      def resolve_target(target, resolver, handler)
-        case target
-        when String
-          resolve_path(target, resolver)
-        when Integer
-          resolve_handle(target, handler)
+        def resolve_arg(value, handles)
+          Kobako::Codec::HandleWalk.deep_restore(value, handles)
+        rescue Kobako::SandboxError => e
+          raise UndefinedTargetError, e.message
         end
-      end
 
-      def resolve_path(path, resolver)
-        resolver.lookup(path)
-      rescue KeyError => e
-        raise UndefinedTargetError, e.message
-      end
+        # The envelope already discriminated the two target forms, so no
+        # else-branch is needed.
+        def resolve_target(target, resolver, handles)
+          case target
+          when String
+            resolve_path(target, resolver)
+          when Integer
+            resolve_handle(target, handles)
+          end
+        end
 
-      # Resolve +id+ to the Exposure its Handle was minted with. An unknown
-      # id surfaces as UndefinedTargetError.
-      def resolve_handle(id, handler)
-        handler.exposure(id)
-      rescue Kobako::SandboxError => e
-        raise UndefinedTargetError, e.message
-      end
+        def resolve_path(path, resolver)
+          resolver.lookup(path)
+        rescue KeyError => e
+          raise UndefinedTargetError, e.message
+        end
 
-      # Encode +value+ as the body of a Reply's ok arm — the value alone,
-      # since the envelope's tag already carries the success. A value that
-      # is not wire-representable per the codec's type mapping raises
-      # +UnsupportedTypeError+; the rescue routes it through the
-      # Catalog::Handles via #wrap_as_handle and re-encodes with the
-      # Capability Handle in place. The happy path encodes exactly once.
-      #
-      # Any other codec fault is the answer failing to encode rather than the
-      # request failing to decode, and a Service is the only side that can
-      # change what it returns — so it is named here, where the direction is
-      # known, instead of falling to the boundary's codec floor and reporting
-      # as an exchange that produced no Service outcome.
-      def encode_ok(value, handler)
-        Kobako::Codec::Nesting.assert_within_bound!(value)
-        Kobako::Codec::Encoder.encode(value)
-      rescue Kobako::Codec::UnsupportedTypeError
-        encode_ok(wrap_as_handle(value, handler), handler)
-      rescue Kobako::Codec::Error => e
-        raise Kobako::SandboxError, "Sandbox could not write the Service's answer: #{e.message}"
-      end
+        def resolve_handle(id, handles)
+          handles.exposure(id)
+        rescue Kobako::SandboxError => e
+          raise UndefinedTargetError, e.message
+        end
 
-      # Allocate +value+ in the Sandbox's Catalog::Handles and return a +Handle+
-      # that the wire codec can carry. Used as the fallback path of
-      # #encode_ok when +value+ has no wire representation.
-      def wrap_as_handle(value, handler)
-        handler.alloc(value)
-      end
+        # A value with no wire form goes back as a Capability Handle. Any
+        # other codec fault is the answer failing to encode, which only the
+        # Service can change — so it is named here, where the direction is
+        # known, instead of falling to the boundary's codec floor.
+        def encode_ok(value, handles)
+          Kobako::Codec::Nesting.assert_within_bound!(value)
+          Kobako::Codec::Encoder.encode(value)
+        rescue Kobako::Codec::UnsupportedTypeError
+          encode_ok(handles.alloc(value), handles)
+        rescue Kobako::Codec::Error => e
+          raise Kobako::SandboxError, "Sandbox could not write the Service's answer: #{e.message}"
+        end
 
-      # +message+ folds to UTF-8 first: Ruby core builds some exception
-      # messages as ASCII-8BIT (the arity ArgumentError, for one), and
-      # the envelope requires UTF-8 of the text fields it frames.
-      def fault(type, message)
-        [message.encode(Encoding::UTF_8, invalid: :replace, undef: :replace), type] # : [String, String]
+        # Ruby core builds some exception messages as ASCII-8BIT (the arity
+        # ArgumentError, for one), and the envelope requires UTF-8 of the
+        # text fields it frames.
+        def fault(type, message)
+          [message.encode(Encoding::UTF_8, invalid: :replace, undef: :replace), type] # : [String, String]
+        end
       end
     end
   end