kobako 0.3.0 → 0.4.0

data/lib/kobako/handle_table.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require_relative "handle"
+
+module Kobako
+  # Host-side mapping from opaque integer Handle IDs to Ruby objects.
+  # The table is owned by +Kobako::Sandbox+ ({docs/behavior.md B-19}[link:../../docs/behavior.md])
+  # and injected into the per-Sandbox +Kobako::RPC::Server+ so guest→host
+  # RPC dispatch resolves Handle targets and arguments against the same
+  # table that host→guest wire encoding allocates into
+  # ({docs/behavior.md B-14, B-34}[link:../../docs/behavior.md]).
+  #
+  # Lifecycle invariants ({docs/behavior.md}[link:../../docs/behavior.md]):
+  #
+  #   - {docs/behavior.md B-15}[link:../../docs/behavior.md] — Handle IDs are
+  #     allocated by a monotonically increasing counter scoped to a single
+  #     invocation. The first ID issued in an invocation is 1; ID 0 is reserved
+  #     as the invalid sentinel and is never returned by +#alloc+.
+  #
+  #   - {docs/behavior.md B-19}[link:../../docs/behavior.md] — At every
+  #     invocation boundary (via +#reset!+), every Handle issued under the
+  #     old state becomes invalid. Reset applies uniformly regardless of
+  #     allocation source (B-14 Service return or B-34 host-injected
+  #     argument).
+  #
+  #   - {docs/behavior.md B-21}[link:../../docs/behavior.md] — The cap is
+  #     +0x7fff_ffff+ (2³¹ − 1). Allocation beyond the cap raises immediately
+  #     — no silent truncation, no wrap, no ID reuse.
+  class HandleTable
+    # Build a fresh, empty HandleTable. +next_id+ is an internal seam that
+    # sets the starting value of the monotonic counter (defaults to 1 per
+    # B-15); tests pass a value near +Kobako::Handle::MAX_ID+ to exercise
+    # the cap-exhaustion path without 2³¹ allocations.
+    def initialize(next_id: 1)
+      @entries = {} # : Hash[Integer, untyped]
+      @next_id = next_id
+    end
+
+    # Bind +object+ in the table and return a +Kobako::Handle+ token
+    # 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::HandleTableExhausted+ 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
+    # ({docs/behavior.md B-21}[link:../../docs/behavior.md]).
+    #
+    # Returning a Handle (rather than a bare Integer id) keeps the
+    # allocator's output a domain entity; +Kobako::Handle.from_wire+
+    # is reserved for the codec's wire-decode path, where the id is
+    # the only thing the bytes carry.
+    def alloc(object)
+      id = @next_id
+      cap = Kobako::Handle::MAX_ID
+      if id > cap
+        raise HandleTableExhausted,
+              "Handle id space exhausted: allocation would assign id #{id}, exceeding the cap (#{cap})"
+      end
+
+      @entries[id] = object
+      @next_id = id + 1
+      Kobako::Handle.from_wire(id)
+    end
+
+    # Resolve a Handle ID to its bound object. +id+ is a Handle ID previously
+    # returned by +#alloc+. Returns the bound object. Raises
+    # +Kobako::HandleTableError+ if +id+ is not currently bound.
+    def fetch(id)
+      require_bound!(id)
+      @entries[id]
+    end
+
+    # Remove and return the binding for +id+. +id+ is the Handle ID to
+    # release. Returns the previously-bound object. Raises
+    # +Kobako::HandleTableError+ if +id+ is not currently bound.
+    def release(id)
+      require_bound!(id)
+      @entries.delete(id)
+    end
+
+    # Clear all entries AND reset the counter to 1. Called at the per-invocation
+    # boundary by +Kobako::Sandbox+ — see
+    # {docs/behavior.md B-19}[link:../../docs/behavior.md]. Returns +self+.
+    def reset!
+      @entries.clear
+      @next_id = 1
+      self
+    end
+
+    # Mark the entry at +id+ as disconnected (ABA protection). +id+ is the
+    # Handle ID to poison; silently ignored if +id+ is not currently bound.
+    # Returns +self+ for chainability, matching the convention of +#reset!+.
+    def mark_disconnected(id)
+      @entries[id] = :disconnected if @entries.key?(id)
+      self
+    end
+
+    # Returns the number of currently-bound entries.
+    def size
+      @entries.size
+    end
+
+    # Returns +true+ when +id+ is currently bound, +false+ otherwise.
+    def include?(id)
+      @entries.key?(id)
+    end
+
+    private
+
+    # Single source of truth for the "unknown Handle id" raise shared by
+    # {#fetch} and {#release}. Returns +nil+ on success; raises
+    # +Kobako::HandleTableError+ when +id+ is not currently bound.
+    def require_bound!(id)
+      return if @entries.key?(id)
+
+      raise HandleTableError, "unknown Handle id: #{id.inspect}"
+    end
+  end
+end

data/lib/kobako/invocation.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative "rpc/handle"
+require_relative "handle"
 require_relative "codec"
 
 module Kobako
@@ -15,13 +15,21 @@ module Kobako
   # anything that passes +Invocation.new+ is safe to encode and ship to
   # the guest.
   #
-  # Invocation sits at top level, not under +Kobako::RPC+: RPC in SPEC is
-  # the guest→host capability channel (Server / Client / Request /
-  # Response / Handle); Invocation is the opposite direction (host→guest
-  # entrypoint dispatch) and structurally rejects Handles (E-29), so it
-  # has no relationship with the HandleTable. The +#encode+ output is the
-  # "Invocation envelope" that ships through the +__kobako_run+ command
-  # buffer.
+  # Invocation sits at top level, not under +Kobako::RPC+: RPC in SPEC
+  # is the guest→host capability channel (Server / Client / Request /
+  # Response); Invocation is the opposite direction (host→guest
+  # entrypoint dispatch). +#encode+ takes the Sandbox's HandleTable
+  # and routes any non-wire-representable +args+ / +kwargs+ leaf
+  # through it as a +Kobako::Handle+
+  # ({docs/behavior.md B-34}[link:../../docs/behavior.md]) — the
+  # symmetric counterpart of the guest→host wrap path in
+  # +Kobako::RPC::Dispatcher#wrap_as_handle+ (B-14). A
+  # +Kobako::Handle+ that arrives **already constructed** in the
+  # caller's +args+ / +kwargs+ is rejected at construction (E-29):
+  # legitimate Handles only enter Host App code through error fields,
+  # so a Handle reaching the call site is by definition smuggled in.
+  # The +#encode+ output is the "Invocation envelope" that ships
+  # through the +__kobako_run+ command buffer.
   #
   # Built on the +class X < Data.define(...)+ subclass form (the
   # Steep-friendly shape — see +lib/kobako/outcome/panic.rb+).
@@ -46,15 +54,22 @@ module Kobako
     # Encode this Invocation to the msgpack bytes the guest's
     # +__kobako_run+ entry point consumes as its command-buffer payload
     # ({docs/wire-codec.md Invocation channels}[link:../../docs/wire-codec.md]).
-    # The Value Object's own invariants are the contract; this method
-    # does not re-check the shape. Layout: msgpack map with string keys
-    # +"entrypoint"+ (Symbol via ext 0x00), +"args"+ (Array), +"kwargs"+
-    # (Map with Symbol keys).
-    def encode
+    # Walks +args+ / +kwargs+ through {Codec::Utils.deep_wrap} so any
+    # non-wire-representable leaf is allocated into +handle_table+ and
+    # replaced with a +Kobako::Handle+
+    # ({docs/behavior.md B-34}[link:../../docs/behavior.md]); the
+    # +handle_table+ argument is the Sandbox's table, sharing the same
+    # allocator the guest→host return path (B-14) uses.
+    #
+    # Layout: msgpack map with string keys +"entrypoint"+ (Symbol via
+    # ext 0x00), +"args"+ (Array), +"kwargs"+ (Map with Symbol keys);
+    # any wrapped leaf rides as ext 0x01 in its original position
+    # (docs/wire-codec.md § ext 0x01 position rules).
+    def encode(handle_table)
       Codec::Encoder.encode(
         "entrypoint" => entrypoint,
-        "args" => args,
-        "kwargs" => kwargs
+        "args" => Codec::Utils.deep_wrap(args, handle_table),
+        "kwargs" => Codec::Utils.deep_wrap(kwargs, handle_table)
       )
     end
 
@@ -80,22 +95,25 @@ module Kobako
       target_str.to_sym
     end
 
-    # E-29: +args+ must not contain a +Kobako::RPC::Handle+. Handles
-    # are per-invocation and cannot enter the next invocation through
-    # a control-plane channel; a guest that needs to call into a
-    # stateful host object must obtain a fresh Handle through a
-    # Service RPC inside the dispatched entrypoint.
+    # E-29: +args+ must not contain a +Kobako::Handle+. The Handle
+    # allocator lives inside the Host Gem; legitimate paths surface
+    # Handle objects only through raised error fields, so a Handle
+    # reaching +args+ is a forged or smuggled token. Non-wire-
+    # representable arguments that are not Handles are handled by
+    # auto-wrap inside +#encode+ (B-34) — the reject path is reserved
+    # for Handle objects specifically.
     def validate_args!(args)
       raise ArgumentError, "Invocation args must be Array" unless args.is_a?(Array)
-      raise ArgumentError, "Invocation args must not contain a Kobako::RPC::Handle" if args.any?(Kobako::RPC::Handle)
+      raise ArgumentError, forged_handle_message("args") if args.any?(Kobako::Handle)
 
       args
     end
 
-    # E-30: +kwargs+ keys must be Symbols, mirroring the wire codec's
-    # Request kwargs rule. Validation lives here (not in the codec) so
-    # the Host App sees the host-side error message before any encode
-    # / decode boundary.
+    # E-30 covers the non-Symbol kwargs-key case; E-29 also rejects a
+    # +Kobako::Handle+ arriving as a kwargs value (same forged-token
+    # principle as the +args+ branch). Both checks live here so the
+    # Host App sees the host-side error message before any encode /
+    # decode boundary.
     def validate_kwargs!(kwargs)
       raise ArgumentError, "Invocation kwargs must be Hash" unless kwargs.is_a?(Hash)
 
@@ -104,9 +122,22 @@ module Kobako
         raise ArgumentError,
               "Invocation kwargs keys must be Symbols (got #{bad_keys.inspect})"
       end
+      raise ArgumentError, forged_handle_message("kwargs values") if kwargs.each_value.any?(Kobako::Handle)
 
       kwargs
     end
+
+    # Single source of truth for the E-29 reject message so the args
+    # and kwargs branches stay phrased identically. Message stays in
+    # caller vocabulary: it names the affected slot and the reason
+    # without leaking SPEC anchor identifiers (B-xx / E-xx live in
+    # source comments, not user-visible errors) or self-referential
+    # architecture terms — the error is raised BY kobako, so saying
+    # "allocated by the Host Gem" reads as third-person about self.
+    def forged_handle_message(slot)
+      "Invocation #{slot} must not contain a Kobako::Handle — " \
+        "Kobako::Handle instances are internal wire tokens, not caller-constructible"
+    end
     # steep:ignore:end
   end
 end

data/lib/kobako/outcome.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "outcome/panic"
+require_relative "rpc/wire_error"
 
 module Kobako
   # Host-facing boundary for the OUTCOME_BUFFER produced by
@@ -46,11 +47,19 @@ module Kobako
 
     # TrapError for unknown or absent tag
     # ({docs/wire-codec.md ABI Signatures}[link:../../docs/wire-codec.md]:
-    # len=0 and unknown-tag both walk the trap path).
+    # zero-length output and unrecognised first byte both walk the trap
+    # path). The user-facing message stays in caller vocabulary — the
+    # raw tag byte (or absence) belongs in +details+ for operators, not
+    # in the message a caller sees.
     def build_trap_error(tag)
-      return TrapError.new("guest exited without writing an outcome (len=0)") if tag.nil?
-
-      TrapError.new(format("unknown outcome tag 0x%<tag>02x", tag: tag))
+      if tag.nil?
+        TrapError.new("Sandbox exited without producing a result")
+      else
+        TrapError.new(
+          "Sandbox produced an unrecognised result; the runtime is corrupted, " \
+          "discard this Sandbox before another invocation"
+        )
+      end
     end
 
     def split_tag(bytes)
@@ -63,11 +72,18 @@ module Kobako
     end
 
     # Decode failure on the success tag is a SandboxError (E-09): the
-    # framing was fine, but the carried value is unrepresentable.
+    # framing was fine, but the carried value is unrepresentable. The
+    # specific codec fault is stashed in +details[:wire_error]+ rather
+    # than spliced into the message — callers cannot act on the inner
+    # "Symbol payload must be …" wording, but operators triaging a
+    # corrupted Sandbox runtime still need it.
     def decode_value(body)
       Kobako::Codec::Decoder.decode(body)
     rescue Kobako::Codec::Error => e
-      raise build_wire_violation_error("result envelope decode failed: #{e.message}")
+      raise build_wire_violation_error(
+        "Sandbox produced an invalid result value",
+        wire_error: e.message
+      )
     end
 
     # Decode failure on the panic tag is a SandboxError (E-08). Either
@@ -77,16 +93,21 @@ module Kobako
     def decode_panic(body)
       raise build_panic_error(parse_panic(body))
     rescue Kobako::Codec::Error => e
-      raise build_wire_violation_error("panic envelope decode failed: #{e.message}")
+      raise build_wire_violation_error(
+        "Sandbox produced an invalid panic record",
+        wire_error: e.message
+      )
     end
 
     # Build a +Panic+ value object from the msgpack-decoded body. Raises
     # +Kobako::Codec::InvalidType+ when the body is not a map or
     # when required keys are missing — both routed by +decode_panic+ to
-    # +build_wire_violation_error+.
+    # +build_wire_violation_error+. The +InvalidType+ message itself is
+    # never user-facing; it lands in +details[:wire_error]+ via the
+    # rescue chain above.
     def parse_panic(body)
       map = Kobako::Codec::Decoder.decode(body)
-      raise Kobako::Codec::InvalidType, "Panic envelope must be a map, got #{map.class}" unless map.is_a?(Hash)
+      raise Kobako::Codec::InvalidType, "panic body must be a map, got #{map.class}" unless map.is_a?(Hash)
 
       Kobako::Codec::Utils.wire_boundary do
         Panic.new(
@@ -129,11 +150,20 @@ module Kobako
       end
     end
 
-    def build_wire_violation_error(message)
-      SandboxError.new(
+    # Lift the wire-violation fallback to the real
+    # +Kobako::RPC::WireError+ class so callers can +rescue+ it
+    # specifically instead of pattern-matching on +error.klass+. The
+    # +klass+ field is still populated so existing operator-side
+    # tooling that greps on the string continues to work.
+    # +wire_error+ carries the inner codec / framing message for
+    # operator diagnosis without polluting the user-facing
+    # +#message+.
+    def build_wire_violation_error(message, wire_error: nil)
+      Kobako::RPC::WireError.new(
         message,
         origin: Panic::ORIGIN_SANDBOX,
-        klass: "Kobako::RPC::WireError"
+        klass: "Kobako::RPC::WireError",
+        details: wire_error.nil? ? nil : { wire_error: wire_error }
       )
     end
   end

data/lib/kobako/rpc/dispatcher.rb

@@ -34,22 +34,23 @@ module Kobako
       # Dispatch a single RPC request and return the encoded response bytes.
       # Called by +Kobako::RPC::Server#dispatch+ which is invoked from the
       # Rust ext inside +__kobako_dispatch+. +request_bytes+ is the
-      # msgpack-encoded Request envelope. +server+ is the live Server for
-      # this run, used to resolve path-based targets via +#lookup+ and to
-      # access the +#handle_table+ for Handle-based targets and return-value
-      # wrapping. Always returns a binary String — never raises. Any failure
-      # during decode, lookup, or method invocation is reified as a
-      # Response.error envelope so the guest sees the failure as a normal RPC
-      # error rather than a wasm trap
+      # msgpack-encoded Request envelope. +server+ resolves path-based
+      # Member targets via +#lookup+. +handle_table+ is the Sandbox's
+      # HandleTable, injected separately so Dispatcher does not depend
+      # on Server publishing a Handle accessor — Handle is a
+      # Sandbox-level domain entity (B-19) and the dispatcher is its
+      # only consumer here. Always returns a binary String — never
+      # raises. Any failure during decode, lookup, or method invocation
+      # is reified as a Response.error envelope so the guest sees the
+      # failure as a normal RPC error rather than a wasm trap
       # ({docs/behavior.md B-12}[link:../../../docs/behavior.md]).
-      def dispatch(request_bytes, server)
+      def dispatch(request_bytes, server, handle_table)
         request = Kobako::RPC.decode_request(request_bytes)
-        handle_table = server.handle_table
         target = resolve_target(request.target, server, handle_table)
         args = request.args.map { |v| resolve_arg(v, handle_table) }
         kwargs = request.kwargs.transform_values { |v| resolve_arg(v, handle_table) }
         value = invoke(target, request.method_name, args, kwargs)
-        encode_ok(value, server)
+        encode_ok(value, handle_table)
       rescue StandardError => e
         encode_caught_error(e)
       end
@@ -58,14 +59,15 @@ module Kobako
       # envelope. +error+ is the +StandardError+ caught by {#dispatch}'s
       # rescue. Returns a msgpack-encoded Response envelope (binary). Four
       # error buckets ({docs/behavior.md B-12}[link:../../../docs/behavior.md]):
-      # +Kobako::Codec::Error+ → type="runtime" (wire decode failed);
+      # +Kobako::Codec::Error+ → type="runtime" (malformed RPC request);
       # +DisconnectedTargetError+ → type="disconnected" (E-14);
       # +UndefinedTargetError+ → type="undefined" (E-13); +ArgumentError+ →
       # type="argument" (B-12 arity mismatch); everything else →
       # type="runtime".
       def encode_caught_error(error)
         case error
-        when Kobako::Codec::Error then encode_error("runtime", "wire decode failed: #{error.message}")
+        when Kobako::Codec::Error then encode_error("runtime",
+                                                    "Sandbox received a malformed RPC request: #{error.message}")
         when DisconnectedTargetError then encode_error("disconnected", error.message)
         when UndefinedTargetError    then encode_error("undefined", error.message)
         when ArgumentError           then encode_error("argument", error.message)
@@ -86,7 +88,7 @@ module Kobako
         end
       end
 
-      # {docs/behavior.md B-16}[link:../../../docs/behavior.md] — An RPC::Handle arriving as a positional or keyword
+      # {docs/behavior.md B-16}[link:../../../docs/behavior.md] — An Kobako::Handle arriving as a positional or keyword
       # argument identifies a host-side object previously allocated by a prior
       # RPC's Handle wrap (B-14). Resolve it back to the Ruby object before
       # the dispatch reaches +public_send+. A Handle whose entry is the
@@ -94,7 +96,7 @@ module Kobako
       # the dispatcher emits a Response.error with type="disconnected".
       def resolve_arg(value, handle_table)
         case value
-        when Kobako::RPC::Handle
+        when Kobako::Handle
           require_live_object!(value.id, handle_table)
         else
           value
@@ -112,7 +114,7 @@ module Kobako
         case target
         when String
           resolve_path(target, server)
-        when Kobako::RPC::Handle
+        when Kobako::Handle
           resolve_handle(target, handle_table)
         end
       end
@@ -144,19 +146,19 @@ module Kobako
       # HandleTable via {#wrap_as_handle} and re-encodes with the Capability
       # Handle in place ({docs/behavior.md B-14}[link:../../../docs/behavior.md]). The happy
       # path encodes exactly once.
-      def encode_ok(value, server)
+      def encode_ok(value, handle_table)
         response = Kobako::RPC::Response.ok(value)
         Kobako::RPC.encode_response(response)
       rescue Kobako::Codec::UnsupportedType
-        encode_ok(wrap_as_handle(value, server), server)
+        encode_ok(wrap_as_handle(value, handle_table), handle_table)
       end
 
-      # Allocate +value+ in the Server's HandleTable and return a +Handle+
+      # Allocate +value+ in the Sandbox's HandleTable and return a +Handle+
       # that the wire codec can carry ({docs/behavior.md B-14}[link:../../../docs/behavior.md]).
       # Used as the fallback path of {#encode_ok} when +value+ has no wire
       # representation.
-      def wrap_as_handle(value, server)
-        Kobako::RPC::Handle.new(server.handle_table.alloc(value))
+      def wrap_as_handle(value, handle_table)
+        handle_table.alloc(value)
       end
 
       def encode_error(type, message)

data/lib/kobako/rpc/envelope.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative "handle"
+require_relative "../handle"
 require_relative "fault"
 require_relative "../codec"
 
@@ -25,8 +25,8 @@ module Kobako
     Request = Data.define(:target, :method_name, :args, :kwargs) do
       # steep:ignore:start
       def initialize(target:, method:, args: [], kwargs: {})
-        unless target.is_a?(String) || target.is_a?(Kobako::RPC::Handle)
-          raise ArgumentError, "Request target must be String or Kobako::RPC::Handle, got #{target.class}"
+        unless target.is_a?(String) || target.is_a?(Kobako::Handle)
+          raise ArgumentError, "Request target must be String or Kobako::Handle, got #{target.class}"
         end
         raise ArgumentError, "Request method must be String" unless method.is_a?(String)
         raise ArgumentError, "Request args must be Array"    unless args.is_a?(Array)
@@ -56,7 +56,7 @@ module Kobako
     def self.decode_request(bytes)
       arr = Codec::Decoder.decode(bytes)
       unless arr.is_a?(Array) && arr.length == 4
-        raise Codec::InvalidType, "Request must be a 4-element array, got #{arr.inspect}"
+        raise Codec::InvalidType, "Request envelope is malformed (expected a 4-element array)"
       end
 
       target, method_name, args, kwargs = arr
@@ -87,10 +87,10 @@ module Kobako
 
       def initialize(status:, payload:)
         unless [STATUS_OK, STATUS_ERROR].include?(status)
-          raise ArgumentError, "Response status must be 0 or 1, got #{status.inspect}"
+          raise ArgumentError, "Response status must be 0 (ok) or 1 (error), got #{status.inspect}"
         end
         if status == STATUS_ERROR && !payload.is_a?(Kobako::RPC::Fault)
-          raise ArgumentError, "Response status=1 payload must be Kobako::RPC::Fault"
+          raise ArgumentError, "Response with error status must carry a Kobako::RPC::Fault payload"
         end
 
         super
@@ -108,7 +108,7 @@ module Kobako
     def self.decode_response(bytes)
       arr = Codec::Decoder.decode(bytes)
       unless arr.is_a?(Array) && arr.length == 2
-        raise Codec::InvalidType, "Response must be a 2-element array, got #{arr.inspect}"
+        raise Codec::InvalidType, "Response envelope is malformed (expected a 2-element array)"
       end
 
       status, payload = arr

data/lib/kobako/rpc/fault.rb

@@ -23,7 +23,7 @@ module Kobako
       # Reach it through +self.class::VALID_TYPES+ — Data.define's block
       # scope resolves bare constants against the enclosing +Wire+ module,
       # so a bare +VALID_TYPES+ would raise +NameError+. Same pattern as
-      # +RPC::Handle+.
+      # +Kobako::Handle+.
       # steep:ignore:start
       def initialize(type:, message:, details: nil)
         valid_types = self.class::VALID_TYPES

data/lib/kobako/rpc/server.rb

@@ -4,7 +4,7 @@ require "msgpack"
 require_relative "../errors"
 require_relative "envelope"
 require_relative "namespace"
-require_relative "handle_table"
+require_relative "../handle_table"
 require_relative "dispatcher"
 
 module Kobako
@@ -24,10 +24,11 @@ module Kobako
     #
     # Namespaces live at +Kobako::RPC::Namespace+
     # (lib/kobako/rpc/namespace.rb). The opaque Handle allocator lives at
-    # +Kobako::RPC::HandleTable+
-    # (lib/kobako/rpc/handle_table.rb). Dispatch helpers live at
-    # +Kobako::RPC::Dispatcher+
-    # (lib/kobako/rpc/dispatcher.rb).
+    # +Kobako::HandleTable+ (lib/kobako/handle_table.rb) and is owned by
+    # the Sandbox — the Server only holds an injected reference so RPC
+    # dispatch resolves against the same table the wire layer allocates
+    # into (docs/behavior.md B-19). Dispatch helpers live at
+    # +Kobako::RPC::Dispatcher+ (lib/kobako/rpc/dispatcher.rb).
     class Server
       # Build a fresh Server. +handle_table+ is an internal seam that
       # injects a pre-configured +HandleTable+; tests pass one whose +next_id+
@@ -76,11 +77,6 @@ module Kobako
         !namespace.nil? && !member_name.nil? && !namespace[member_name].nil?
       end
 
-      # Returns all declared +Kobako::RPC::Namespace+ instances as an +Array+.
-      def namespaces
-        @namespaces.values
-      end
-
       # Returns the number of declared namespaces as an +Integer+.
       def size
         @namespaces.size
@@ -122,27 +118,19 @@ module Kobako
         @sealed
       end
 
-      # Reset the HandleTable for a new invocation boundary. Called by
-      # +Sandbox+ before each invocation
-      # ({docs/behavior.md B-19}[link:../../../docs/behavior.md]).
-      def reset_handles!
-        @handle_table.reset!
-      end
-
       # Dispatch a single RPC request and return the encoded response bytes
       # ({docs/behavior.md B-12}[link:../../../docs/behavior.md]). +request_bytes+ is a
       # msgpack-encoded Request envelope. Called by the Rust ext from inside
       # +__kobako_dispatch+. Always returns a binary +String+ — never raises.
-      # Delegates to +Dispatcher.dispatch+ which reifies any failure as a
-      # +Response.error+ envelope so the guest sees the failure as a normal RPC
-      # error rather than a wasm trap.
+      # Forwards both the Server (for namespace lookup) and the injected
+      # +HandleTable+ (for Handle resolution / return-value wrapping) to
+      # +Dispatcher.dispatch+. The Server holds the HandleTable as an
+      # injected reference, not an owned resource — the Sandbox owns it
+      # (B-19) — so the table is not exposed via accessors.
       def dispatch(request_bytes)
-        Dispatcher.dispatch(request_bytes, self)
+        Dispatcher.dispatch(request_bytes, self, @handle_table)
       end
 
-      # Expose the +HandleTable+ for tests and wire-layer Handle wrapping.
-      attr_reader :handle_table
-
       private
 
       # Split +target+ on the +::+ separator and resolve the namespace half.

data/lib/kobako/rpc/wire_error.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require_relative "../errors"
+
+module Kobako
+  module RPC
+    # +Kobako::SandboxError+ subclass raised when the host detects a
+    # structural violation of the wire contract while decoding bytes
+    # produced by the guest (a malformed Outcome envelope, a result body
+    # that fails msgpack decode, a Panic envelope missing required
+    # fields). Distinct from a Wasm trap (engine signalled the guest
+    # runtime is unrecoverable) and from a normal sandbox-layer failure
+    # (the script raised but the protocol was respected): a +WireError+
+    # always indicates the guest runtime is corrupted — the only safe
+    # recovery is to discard the Sandbox and start a new invocation.
+    #
+    # Inherits from +Kobako::SandboxError+ so a single
+    # +rescue Kobako::SandboxError+ still catches it; callers that want
+    # to distinguish wire-violation paths from script failures can
+    # +rescue Kobako::RPC::WireError+ directly.
+    class WireError < Kobako::SandboxError; end
+  end
+end