kobako 0.13.0 → 0.15.0

data/lib/kobako/codec/utils.rb

@@ -10,18 +10,18 @@ module Kobako
     #   - UTF-8 assertion at the codec 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}
+    #     Decoder when walking +str+ family payloads and by ExtTypes
     #     when validating the +ext 0x00+ Symbol payload.
     #   - +ArgumentError+ translation at the codec boundary
-    #     ({with_boundary}) so the public taxonomy stays
-    #     {Kobako::Codec::Error}.
+    #     (#with_boundary) so the public taxonomy stays
+    #     Kobako::Codec::Error.
     #
     # Both helpers are pure — they only inspect inputs, never mutate them.
-    # The host↔guest Handle substitution walk lives in {HandleWalk}.
+    # The host↔guest Handle substitution walk lives in HandleWalk.
     module Utils
       module_function
 
-      # Raise {InvalidEncoding} unless +string+'s bytes are valid under
+      # 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"+, +"Symbol payload"+).
       def assert_utf8!(string, label)
@@ -32,13 +32,13 @@ module Kobako
 
       # Run +block+ at the codec boundary: a value object raises
       # +ArgumentError+ when an invariant is violated at construction, and
-      # this helper surfaces that as {InvalidType} so the public taxonomy
-      # stays {Kobako::Codec::Error} and never leaks +ArgumentError+ from
+      # this helper surfaces that as InvalidType so the public taxonomy
+      # stays Kobako::Codec::Error and never leaks +ArgumentError+ from
       # the Ruby standard library.
       #
       # Reach for this only where a value object is constructed outside a
-      # {Decoder.decode} block, whose rescue already performs the same
-      # mapping (worked example: {Factory#unpack_handle} building
+      # Decoder.decode block, whose rescue already performs the same
+      # mapping (worked example: ExtTypes#unpack_handle building
       # +Handle.restore+ from a raw fixext payload). Do not use it for
       # general-purpose validation outside the codec boundary —
       # host-layer +ArgumentError+ values should propagate unchanged.

data/lib/kobako/codec.rb

@@ -3,7 +3,8 @@
 require_relative "codec/error"
 require_relative "codec/utils"
 require_relative "codec/handle_walk"
-require_relative "codec/factory"
+require_relative "codec/state"
+require_relative "codec/ext_types"
 require_relative "codec/encoder"
 require_relative "codec/decoder"
 
@@ -18,14 +19,30 @@ module Kobako
   # the kobako root so the codec can register them without depending
   # upward on Transport.
   #
-  # Backed by the official +msgpack+ gem via {Factory}; {Encoder} and
-  # {Decoder} are thin wrappers that register the three kobako-specific
-  # ext types (0x00 Symbol, 0x01 Capability Handle, 0x02 Exception
-  # envelope) on a single +MessagePack::Factory+ instance. The Rust side
+  # Backed by the official +msgpack+ gem: ExtTypes registers the three
+  # kobako-specific ext types (0x00 Symbol, 0x01 Capability Handle,
+  # 0x02 Exception envelope) on one process-wide +MessagePack::Factory+,
+  # and Encoder / Decoder are thin wrappers over it. The Rust side
   # mirrors this layer as the +codec+ module in the +kobako-codec+ crate;
-  # the ext-code constants live as module-private values on {Factory}
+  # the ext-code constants live as module-private values on ExtTypes
   # alongside +codec::EXT_SYMBOL+ / +codec::EXT_HANDLE+ /
   # +codec::EXT_ERRENV+ on that side.
   module Codec
+    # Bracket a decode and return the block's result together with whether
+    # the decoded tree carried an ext 0x01 Capability Handle — the signal a
+    # dispatch path uses to skip an all-identity Handle-resolution walk.
+    # The tracking state is codec-internal; this is its only readout.
+    def self.track_handles(&block)
+      State.current.track_handles(&block)
+    end
+
+    # Bracket a codec operation in a payload position: an ext 0x02 Fault
+    # envelope is only legal in the Response fault field, so the envelope
+    # layers open this bracket around every other encode / decode and the
+    # ext-type conversions refuse the envelope while it is open — a wire
+    # violation on decode, no wire representation on encode.
+    def self.forbid_faults(&block)
+      State.current.forbid_faults(&block)
+    end
   end
 end

data/lib/kobako/errors.rb

@@ -4,38 +4,13 @@
 module Kobako
   # Error taxonomy.
   #
-  # Every `Kobako::Sandbox` invocation (`#eval` or `#run`) either returns a value or raises
-  # exactly one of three invocation-outcome classes. Attribution is decided after the
-  # guest binary returns control to the host: first the Wasm-trap layer, then
-  # the outcome-envelope tag.
-  #
-  # Three invocation-outcome branches:
-  #
-  #   * {TrapError}     — Wasm engine layer (trap, OOM, unreachable, or a
-  #                       wire-violation fallback signalling a corrupted
-  #                       guest runtime).
-  #   * {SandboxError}  — sandbox / wire layer (mruby script error,
-  #                       wire-decode failure on an otherwise valid tag,
-  #                       Catalog::Handles exhaustion, output buffer overrun).
-  #   * {ServiceError}  — service / capability layer (a Service capability
-  #                       call that failed and was not rescued inside the
-  #                       script).
-  #
-  # Two further branches sit outside the invocation taxonomy:
-  #
-  #   * {SetupError}    — construction layer. Raised by `Kobako::Sandbox.new`
-  #                       when the wasm runtime cannot be built from the
-  #                       configured +wasm_path+ before any invocation runs.
-  #                       Not an invocation outcome, so it never passes
-  #                       through the two-step attribution decision.
-  #   * {PoolTimeoutError} — pool checkout layer. Raised by `Kobako::Pool#with`
-  #                       when the checkout wait exceeds +checkout_timeout+.
-  #
-  # Named subclasses:
-  #
-  #   * {ModuleNotBuiltError} < {SetupError} — Guest Binary artifact absent
-  #                       at +wasm_path+.
-  #   * {HandleExhaustedError} < {SandboxError} — Handle id cap hit.
+  # Every +Kobako::Sandbox+ invocation (+#eval+ or +#run+) either returns a
+  # value or raises exactly one of TrapError, SandboxError, or ServiceError.
+  # Attribution is decided after the guest binary returns control to the
+  # host: first the Wasm-trap layer, then the outcome-envelope tag.
+  # SetupError and PoolTimeoutError sit outside the invocation taxonomy and
+  # never pass through that attribution decision. Each class below
+  # documents its own layer.
 
   # Base for all kobako-raised errors so callers that want to ignore the
   # taxonomy can rescue a single class.
@@ -48,8 +23,8 @@ module Kobako
   #
   # Two named subclasses cover the configured per-invocation caps:
   #
-  #   * {TimeoutError}     — wall-clock +timeout+ exceeded.
-  #   * {MemoryLimitError} — guest +memory.grow+ would exceed
+  #   * TimeoutError     — wall-clock +timeout+ exceeded.
+  #   * MemoryLimitError — guest +memory.grow+ would exceed
   #                          +memory_limit+.
   #
   # Host Apps that only care about "guest is unrecoverable, discard the
@@ -128,14 +103,14 @@ module Kobako
   class HandleExhaustedError < SandboxError; end
 
   # BytecodeError is the SandboxError subclass raised when a
-  # `#preload(binary:)` snippet fails structural validation during the
-  # first invocation's snippet replay against a fresh `mrb_state` (RITE
+  # +#preload(binary:)+ snippet fails structural validation during the
+  # first invocation's snippet replay against a fresh +mrb_state+ (RITE
   # version mismatch or corrupt body). Bytecode that loads cleanly and
-  # then raises at top level surfaces as plain `SandboxError` with the
+  # then raises at top level surfaces as plain +SandboxError+ with the
   # natural mruby class preserved. Inherits from SandboxError so a single
-  # `rescue Kobako::SandboxError` covers both source and bytecode
+  # +rescue Kobako::SandboxError+ covers both source and bytecode
   # snippet failures while callers wanting bytecode-specific handling
-  # can `rescue Kobako::BytecodeError` directly.
+  # can +rescue Kobako::BytecodeError+ directly.
   class BytecodeError < SandboxError; end
 
   # Pool checkout layer. Raised by +Kobako::Pool#with+ when the checkout

data/lib/kobako/fault.rb

@@ -5,7 +5,7 @@ module Kobako
   #
   # Top-level shared wire primitive: like +Kobako::Handle+ (ext 0x01),
   # +Fault+ is a MessagePack ext-type leaf registered by
-  # +Kobako::Codec::Factory+ and rides nested inside other envelopes (a
+  # +Kobako::Codec::ExtTypes+ and rides nested inside other envelopes (a
   # +Kobako::Transport::Response+ error payload, or another Fault's
   # +details+). It lives at the kobako root rather than under +Transport+
   # because the Codec layer must register it, and Codec must not depend

data/lib/kobako/handle.rb

@@ -14,9 +14,11 @@ module Kobako
   # 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 {.restore}, which exists at exactly two call
-  # sites: +Kobako::Codec::Factory#unpack_handle+ (wire decode) and
+  # fields on raised error objects. +#with+ — Data's copy-with-changes
+  # constructor — is removed for the same reason: a legitimate Handle
+  # must not derive a sibling with a caller-chosen id. The Host Gem itself constructs
+  # Handles through +.restore+, which exists at exactly two call
+  # sites: +Kobako::Codec::ExtTypes#unpack_handle+ (wire decode) and
   # +Kobako::Codec::HandleWalk.deep_wrap+ / +Kobako::Transport::Dispatcher#wrap_as_handle+
   # (allocator paths). Both live inside +lib/kobako/+ and are not part
   # of any public surface.
@@ -41,6 +43,7 @@ module Kobako
     end
 
     private_class_method :new
+    undef_method :with
 
     # Host Gem–internal factory. Allocates the Data instance through
     # +Class#allocate+ and dispatches +#initialize+ explicitly so the

data/lib/kobako/outcome.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative "codec"
 require_relative "outcome/panic"
 require_relative "transport/error"
 
@@ -69,7 +70,9 @@ module Kobako
     # "Symbol payload must be …" wording, but operators triaging a
     # corrupted Sandbox runtime still need it.
     def decode_value(body)
-      Kobako::Codec::Decoder.decode(body)
+      # The Result envelope is a payload position: an ext 0x02 Fault in it
+      # is a wire violation routed into the invalid-result rescue below.
+      Kobako::Codec.forbid_faults { Kobako::Codec::Decoder.decode(body) }
     rescue Kobako::Codec::Error => e
       raise build_transport_error(
         "Sandbox produced an invalid result value",
@@ -98,13 +101,17 @@ module Kobako
     # through the decoder boundary; the message itself is never user-
     # facing — it lands in +details+ via the rescue chain above.
     def build_panic_record(body)
-      Kobako::Codec::Decoder.decode(body) do |map|
-        raise Kobako::Codec::InvalidType, "panic body must be a map, got #{map.class}" unless map.is_a?(Hash)
+      # The Panic envelope is a payload position: an ext 0x02 Fault in its
+      # +details+ is a wire violation routed into the invalid-panic rescue.
+      Kobako::Codec.forbid_faults do
+        Kobako::Codec::Decoder.decode(body) do |map|
+          raise Kobako::Codec::InvalidType, "panic body must be a map, got #{map.class}" unless map.is_a?(Hash)
 
-        Panic.new(
-          origin: map["origin"], klass: map["class"], message: map["message"],
-          backtrace: map["backtrace"] || [], details: map["details"]
-        )
+          Panic.new(
+            origin: map["origin"], klass: map["class"], message: map["message"],
+            backtrace: map["backtrace"] || [], details: map["details"]
+          )
+        end
       end
     end
 

data/lib/kobako/pool.rb

@@ -24,7 +24,7 @@ module Kobako
     # seconds (+nil+ waits indefinitely); every other keyword is
     # forwarded verbatim to +Kobako::Sandbox.new+. The optional block
     # runs exactly once per constructed Sandbox — it is the setup window
-    # for +#define+ / +#preload+ before that Sandbox's first checkout.
+    # for +#bind+ / +#preload+ before that Sandbox's first checkout.
     # No Sandbox is constructed here. Raises +ArgumentError+ for an
     # invalid +slots+ / +checkout_timeout+.
     def initialize(slots:, checkout_timeout: DEFAULT_CHECKOUT_TIMEOUT_SECONDS, **sandbox_options, &setup)

data/lib/kobako/sandbox.rb

@@ -17,7 +17,7 @@ module Kobako
   #
   # The Sandbox owns the +Kobako::Runtime+, the per-Sandbox
   # +Kobako::Catalog::Handles+, the per-instance
-  # +Kobako::Catalog::Namespaces+ (which receives the +Catalog::Handles+ by
+  # +Kobako::Catalog::Services+ (which receives the +Catalog::Handles+ by
   # injection so guest→host dispatch and host→guest auto-wrap share one
   # allocator), and the dispatch +Proc+ / +yield_to_guest+ lambda installed
   # on the Runtime via +Runtime#on_dispatch=+. The underlying wasmtime Engine
@@ -100,27 +100,33 @@ module Kobako
       @wasm_path = wasm_path || Kobako::Runtime.default_path
       @options = SandboxOptions.new(**)
       @handler = Catalog::Handles.new
-      @services = Kobako::Catalog::Namespaces.new(handler: @handler)
+      @services = Kobako::Catalog::Services.new(handler: @handler)
       @snippets = Catalog::Snippets.new
       @runtime = build_runtime!
       install_dispatch_proc!
       reset_invocation_state!
     end
 
-    # Declare or retrieve the Namespace named +name+ on this Sandbox. +name+
-    # must be a Symbol or String in constant form. Returns the
-    # +Kobako::Namespace+.
+    # Bind +object+ as the Service reachable at +path+ — a Symbol or
+    # String of one or more +::+-separated constant-form segments
+    # (+"MyService::KV"+ or a top-level +"File"+). Returns +self+ for
+    # chaining.
     #
-    # Raises +ArgumentError+ when called after the first invocation, or
-    # when +name+ does not match the constant-name pattern.
-    def define(name)
-      @services.define(name)
+    # Raises +ArgumentError+ when a segment is malformed, when +path+
+    # collides with an existing binding (a name is a bound Service or a
+    # grouping prefix, never both), or when called after the first
+    # invocation has sealed Service registration.
+    def bind(path, object)
+      @services.bind(path, object)
+      self
     end
 
     # Register a snippet on this Sandbox in one of two forms:
     #
     #   * +preload(code: source, name: Name)+ — +source+ is mruby source
-    #     as a +String+ and +Name+ matches +/\A[A-Z]\w*\z/+. The +name+
+    #     as a +String+ and +Name+ matches +/\A[A-Z]\w*\z/+. Compile
+    #     failures surface as +Kobako::SandboxError+ on the first
+    #     invocation's replay. The +name+
     #     becomes the snippet's +(snippet:Name)+ backtrace filename and
     #     is the dedupe key that rejects a duplicate +code:+ snippet.
     #   * +preload(binary: bytes)+ — +bytes+ is precompiled RITE
@@ -173,15 +179,15 @@ module Kobako
     #
     # Source delivery uses the WASI stdin three-frame protocol
     # ({docs/wire-codec.md Invocation channels}[link:../../docs/wire-codec.md]):
-    # Frame 1 carries the msgpack-encoded preamble (Namespace / Member
-    # registry snapshot), Frame 2 carries the user source UTF-8 bytes, and
+    # Frame 1 carries the msgpack-encoded preamble (Service registry
+    # snapshot), Frame 2 carries the user source UTF-8 bytes, and
     # Frame 3 carries the snippet table registered via +#preload+.
     # Each frame is prefixed by a 4-byte big-endian u32 length; Frame 3 is
     # mandatory-presence — an empty snippet table sends an empty msgpack
     # array, never an absent frame.
     #
     # The first invocation seals the Service registry and snippet table;
-    # subsequent +#define+ / +#preload+ calls raise +ArgumentError+.
+    # subsequent +#bind+ / +#preload+ calls raise +ArgumentError+.
     #
     # Raises +Kobako::TrapError+ on a Wasm trap or wire-violation fallback;
     # +Kobako::SandboxError+ when the guest ran to completion but failed
@@ -216,7 +222,7 @@ module Kobako
     # runtime that cannot honor the request never runs guest code.
     def build_runtime!
       runtime = Kobako::Runtime.from_path(@wasm_path, @options.timeout, @options.memory_limit,
-                                          @options.stdout_limit, @options.stderr_limit, profile)
+                                          @options.stdout_limit, @options.stderr_limit, @options.profile)
       @options.enforce_floor!(runtime.profile)
       runtime
     end
@@ -257,10 +263,8 @@ module Kobako
     # the readout here also covers the trap path, where +Runtime#eval+ /
     # +#run+ raise instead of returning outcome bytes.
     #
-    # The ext returns a positional 2-tuple +[wall_time, memory_peak]+
-    # whose order matches the +Kobako::Usage+ field order; the
-    # destructure-then-kwargs handoff below is the explicit
-    # positional→keyword conversion point.
+    # The ext-side contract is positional: +Runtime#usage+ yields
+    # +[wall_time, memory_peak]+ in +Kobako::Usage+ field order.
     def read_usage!
       wall_time, memory_peak = @runtime.usage
       @usage = Usage.new(wall_time: wall_time, memory_peak: memory_peak)
@@ -283,16 +287,14 @@ module Kobako
 
     # Read the per-last-invocation output captures from the ext and wrap
     # them as +Kobako::Capture+ value objects. Runs in the +invoke!+
-    # +ensure+ block next to {#read_usage!} for the same reason: the ext
+    # +ensure+ block next to #read_usage! for the same reason: the ext
     # stashes the captures on every outcome, so the readout also covers
     # the trap path, where +Runtime#eval+ / +#run+ raise instead of
     # returning outcome bytes — +#stdout+ / +#stderr+ keep the guest's
     # partial output readable after a rescue.
     #
-    # The ext returns a positional 4-tuple
-    # +[stdout_bytes, stdout_truncated, stderr_bytes, stderr_truncated]+;
-    # the destructure-then-kwargs handoff below is the explicit
-    # positional→keyword conversion point.
+    # The ext-side contract is positional: +Runtime#captures+ yields
+    # +[stdout_bytes, stdout_truncated, stderr_bytes, stderr_truncated]+.
     def read_captures!
       stdout_bytes, stdout_truncated, stderr_bytes, stderr_truncated = @runtime.captures
       @stdout_capture = Capture.new(bytes: stdout_bytes, truncated: stdout_truncated)
@@ -306,7 +308,7 @@ module Kobako
     # The yielded block must return the invocation's raw outcome bytes —
     # i.e. the value of +Runtime#eval+ / +#run+ — which the success path
     # feeds to +Outcome.decode+. Captures and usage are populated by the
-    # +ensure+ readouts ({#read_usage!} / {#read_captures!}) on every
+    # +ensure+ readouts (#read_usage! / #read_captures!) on every
     # outcome, so +#stdout+ / +#stderr+ / +#usage+ stay readable after a
     # rescued trap.
     # The rescue chain is the single trap-translation boundary —
@@ -320,7 +322,10 @@ module Kobako
       # token; restore it to the host object the guest referenced before
       # handing the value to the Host App. @handler still holds this
       # invocation's table — reset only happens at the next #begin_invocation!.
-      Codec::HandleWalk.deep_restore(Outcome.decode(return_bytes), @handler)
+      # A Handle-free result resolves to itself, so the restoration walk is
+      # skipped when the decode carried none.
+      value, carried_handle = Codec.track_handles { Outcome.decode(return_bytes) }
+      carried_handle ? Codec::HandleWalk.deep_restore(value, @handler) : value
     rescue Kobako::TrapError => e
       raise trap_class_for(e), "Sandbox##{verb} failed: #{e.message}"
     ensure

data/lib/kobako/transport/dispatcher.rb

@@ -13,7 +13,7 @@ module Kobako
   module Transport
     # Pure-function dispatcher for guest-initiated transport calls.
     # Decodes a msgpack-encoded Request envelope, resolves the target
-    # object through the Catalog::Namespaces (path lookup) or
+    # object through the Catalog::Services (path lookup) or
     # Catalog::Handles (Handle lookup), invokes the method, and returns
     # a msgpack-encoded Response envelope.
     #
@@ -24,10 +24,10 @@ module Kobako
     #
     # Entry point:
     #
-    #   Kobako::Transport::Dispatcher.dispatch(request_bytes, namespaces, handler, yield_to_guest)
+    #   Kobako::Transport::Dispatcher.dispatch(request_bytes, services, handler, yield_to_guest)
     #   # => msgpack-encoded Response bytes (never raises)
     module Dispatcher
-      # Throw tag for the {Yielder}'s break unwind back to the
+      # 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__
@@ -54,12 +54,12 @@ module Kobako
       # Callable gadget types whose own public methods are reflection surface
       # (+Proc#binding+ reaches +Binding#eval+, +Method#receiver+ / +#unbind+
       # hand back the underlying object) rather than Service behaviour. Only
-      # {CALLABLE_ALLOW} is reachable on a target of these types; a bound
+      # CALLABLE_ALLOW is reachable on a target of these types; a bound
       # lambda stays invocable, its reflective surface does not.
       GADGET_OWNERS = [Proc, Method, UnboundMethod, Binding].freeze
       private_constant :GADGET_OWNERS
 
-      # The sole methods reachable on a {GADGET_OWNERS} target: invoking it
+      # The sole methods reachable on a GADGET_OWNERS target: invoking it
       # (+call+ / +[]+ / +yield+) and the harmless +arity+ / +lambda?+
       # describers that aid guest-side debugging.
       CALLABLE_ALLOW = %i[call [] yield arity lambda?].freeze
@@ -67,7 +67,7 @@ module Kobako
 
       # Dispatch a single transport request and return the encoded
       # Response bytes. Invoked from the +Runtime#on_dispatch+ Proc that
-      # +Kobako::Sandbox#initialize+ installs on the ext side; +namespaces+,
+      # +Kobako::Sandbox#initialize+ installs on the ext side; +services+,
       # +handler+, and +yield_to_guest+ are captured in that Proc's
       # closure so the Dispatcher stays stateless and the registry doesn't
       # need to publish accessors for the Sandbox-owned +Catalog::Handles+
@@ -77,31 +77,38 @@ module Kobako
       # 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.
-      def dispatch(request_bytes, namespaces, handler, yield_to_guest)
-        request = Kobako::Transport::Request.decode(request_bytes)
-        target = resolve_target(request.target, namespaces, handler)
-        args, kwargs = resolve_call_args(request, handler)
+      #
+      # 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(request_bytes, services, handler, yield_to_guest)
+        request, carried_handle = Kobako::Codec.track_handles { Kobako::Transport::Request.decode(request_bytes) }
+        target = resolve_target(request.target, services, handler)
+        args, kwargs = resolve_call_args(request, handler, carried_handle)
         yielder = Yielder.new(yield_to_guest, BREAK_THROW, handler) if request.block_given
-        value = catch(BREAK_THROW) { invoke(target, request.method_name, args, kwargs, yielder) }
-        encode_ok(value, handler)
+        encode_ok(catch(BREAK_THROW) { invoke(target, request.method_name, args, kwargs, yielder) }, handler)
       rescue StandardError => e
         encode_caught_error(e)
       ensure
         yielder&.invalidate!
       end
 
-      # Resolve positional and keyword arguments off +request+ in one
-      # step. Both pass through {#resolve_arg} so Capability Handles
-      # round-trip back to the host-side Ruby object before the call
-      # reaches +public_send+.
-      def resolve_call_args(request, handler)
+      # Resolve positional and keyword arguments off +request+ 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(request, handler, carried_handle)
+        return [request.args, request.kwargs] unless carried_handle
+
         [request.args.map { |v| resolve_arg(v, handler) },
          request.kwargs.transform_values { |v| resolve_arg(v, handler) }]
       end
 
       # Map an error caught at the dispatch boundary to a +Response.error+
       # envelope (binary msgpack). +error+ is the +StandardError+ caught by
-      # {#dispatch}'s rescue; the +type+ field tells the guest which kind
+      # #dispatch's rescue; the +type+ field tells the guest which kind
       # of failure it was so it can raise the matching proxy-side error.
       def encode_caught_error(error)
         case error
@@ -119,8 +126,8 @@ module Kobako
       # 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}
+      # +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.
@@ -137,8 +144,8 @@ module Kobako
       end
 
       # Guard the +public_send+ below against ambient reflection methods.
-      # A public method whose owner is a {META_OWNERS} or {GADGET_OWNERS} module is
-      # rejected, except {CALLABLE_ALLOW} on a gadget target (a bound lambda
+      # A public method whose owner is a META_OWNERS or GADGET_OWNERS module is
+      # rejected, except CALLABLE_ALLOW on a gadget target (a bound lambda
       # stays invocable). A name with no concrete public method is allowed
       # only when the target opts into it via +respond_to?+ (dynamic
       # +method_missing+ Services), since the dangerous methods are all
@@ -159,7 +166,7 @@ module Kobako
       # Consult the target's opt-in narrowing predicate. A bound object
       # may define a private +respond_to_guest?(name)+ to restrict which of its
       # methods the guest reaches; a falsy answer rejects the dispatch.
-      # The predicate composes beneath {#reject_meta_method!} — it only narrows,
+      # The predicate composes beneath #reject_meta_method! — it only narrows,
       # never re-opening the reflection surface the floor rejects — and is
       # consulted with the private surface included so the guest's +public_send+
       # dispatch can never reach +respond_to_guest?+ itself.
@@ -187,17 +194,17 @@ module Kobako
       # Target type is already validated by +Transport::Request.decode+
       # before this method is reached, so no else-branch is needed here —
       # the wire layer is the system boundary that enforces the invariant.
-      def resolve_target(target, namespaces, handler)
+      def resolve_target(target, services, handler)
         case target
         when String
-          resolve_path(target, namespaces)
+          resolve_path(target, services)
         when Kobako::Handle
           require_live_object!(target.id, handler)
         end
       end
 
-      def resolve_path(path, namespaces)
-        namespaces.lookup(path)
+      def resolve_path(path, services)
+        services.lookup(path)
       rescue KeyError => e
         raise UndefinedTargetError, e.message
       end
@@ -213,7 +220,7 @@ module Kobako
       # Encode +value+ as a +Response.ok+ envelope. When the value is not
       # wire-representable per the codec's type mapping, the
       # +UnsupportedType+ rescue routes it through the
-      # Catalog::Handles via {#wrap_as_handle} and re-encodes with the Capability
+      # Catalog::Handles via #wrap_as_handle and re-encodes with the Capability
       # Handle in place. The happy path encodes exactly once.
       def encode_ok(value, handler)
         response = Kobako::Transport::Response.ok(value)
@@ -224,15 +231,18 @@ module Kobako
 
       # 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.
+      # #encode_ok when +value+ has no wire representation.
       def wrap_as_handle(value, handler)
         handler.alloc(value)
       end
 
+      # +message+ folds to UTF-8 first: Ruby core builds some exception
+      # messages as ASCII-8BIT (the arity ArgumentError, for one), and
+      # the codec would ride those as bin — a shape the guest refuses.
       def encode_error(type, message)
+        message = message.encode(Encoding::UTF_8, invalid: :replace, undef: :replace)
         fault = Kobako::Fault.new(type: type, message: message)
-        response = Kobako::Transport::Response.error(fault)
-        response.encode
+        Kobako::Transport::Response.error(fault).encode
       end
     end
   end

data/lib/kobako/transport/request.rb

@@ -12,8 +12,8 @@ module Kobako
     #
     # 5-element msgpack array:
     # +[target, method_name, args, kwargs, block_given]+. +target+ is
-    # either a +String+ (+"<Namespace>::<Member>"+, e.g. +"MyService::KV"+)
-    # or a {Handle}. SPEC pins +kwargs+ map keys to ext 0x00 Symbol;
+    # either a +String+ (+"MyService::KV"+, e.g. +"MyService::KV"+)
+    # or a Handle. SPEC pins +kwargs+ map keys to ext 0x00 Symbol;
     # enforced at construction so the Value Object is the single source of
     # truth. +block_given+ is a Boolean signalling whether the guest call
     # site supplied a block; the block body itself never crosses the
@@ -43,17 +43,22 @@ module Kobako
         Codec::Encoder.encode([target, method_name, args, kwargs, block_given])
       end
 
-      # Decode +bytes+ into a {Request}. Raises +Codec::InvalidType+ when the
-      # envelope is not the expected 5-element msgpack array, or when the
-      # Value Object's construction invariants reject the decoded fields.
+      # Decode +bytes+ into a Request. Raises +Codec::InvalidType+ when the
+      # envelope is not the expected 5-element msgpack array, when any
+      # position carries an ext 0x02 Fault envelope (a Request is a payload
+      # position; the Response fault field is the envelope's only home), 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 == 5
-            raise Codec::InvalidType, "Request envelope is malformed (expected a 5-element array)"
-          end
+        Codec.forbid_faults do
+          Codec::Decoder.decode(bytes) do |arr|
+            unless arr.is_a?(Array) && arr.length == 5
+              raise Codec::InvalidType, "Request envelope is malformed (expected a 5-element array)"
+            end
 
-          target, method_name, args, kwargs, block_given = arr
-          new(target: target, method_name: method_name, args: args, kwargs: kwargs, block_given: block_given)
+            target, method_name, args, kwargs, block_given = arr
+            new(target: target, method_name: method_name, args: args, kwargs: kwargs, block_given: block_given)
+          end
         end
       end
 

data/lib/kobako/transport/response.rb

@@ -20,7 +20,7 @@ module Kobako
     #
     # 2-element msgpack array: +[status, value-or-fault]+. +status+ is 0
     # (success) or 1 (fault). For success the second element is the return
-    # value; for fault it is a {Fault} (ext 0x02 envelope).
+    # value; for fault it is a Fault (ext 0x02 envelope).
     #
     # Built on the +class X < Data.define(...)+ subclass form so the
     # class body is fully Steep-visible; see +lib/kobako/outcome/panic.rb+
@@ -53,12 +53,19 @@ module Kobako
       def error? = status == STATUS_ERROR
 
       # Encode this Response to msgpack bytes as the 2-element
-      # +[status, payload]+ array.
+      # +[status, payload]+ array. The ok variant's value is a payload
+      # position, so a +Kobako::Fault+ inside it has no wire
+      # representation and surfaces as +UnsupportedType+ — the
+      # Dispatcher's auto-wrap rescue turns it into a Capability Handle.
+      # The error variant carries the Fault envelope in its one legal
+      # position and encodes it plainly.
       def encode
-        Codec::Encoder.encode([status, payload])
+        return Codec::Encoder.encode([status, payload]) if error?
+
+        Codec.forbid_faults { Codec::Encoder.encode([status, payload]) }
       end
 
-      # Decode +bytes+ into a {Response}. Raises +Codec::InvalidType+ when the
+      # 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)