kobako 0.2.1 → 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

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require_relative "handle"
+require_relative "codec"
+
+module Kobako
+  # Host-side value object for a single +Sandbox#run+ invocation
+  # ({docs/wire-codec.md Invocation channels}[link:../../docs/wire-codec.md];
+  # {docs/behavior.md B-31}[link:../../docs/behavior.md]).
+  #
+  # An Invocation captures the host-layer concept of "a single +#run+
+  # call": the entrypoint constant name plus its positional and keyword
+  # arguments. Host pre-flight (E-24 / E-25 / E-29 / E-30) is enforced at
+  # construction so the Value Object is the single source of truth —
+  # 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); 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+).
+  class Invocation < Data.define(:entrypoint, :args, :kwargs)
+    # Ruby constant-name pattern enforced on the +entrypoint+ Symbol
+    # ({docs/behavior.md E-25}[link:../../docs/behavior.md]). Parallel to
+    # +Kobako::Snippet::Table::NAME_PATTERN+; the two constants name the
+    # same regex but cover distinct surfaces (snippet identity vs.
+    # entrypoint resolution) so a future divergence stays local.
+    NAME_PATTERN = /\A[A-Z]\w*\z/
+
+    # steep:ignore:start
+    def initialize(entrypoint:, args: [], kwargs: {})
+      super(
+        entrypoint: normalize_entrypoint(entrypoint),
+        args: validate_args!(args),
+        kwargs: validate_kwargs!(kwargs)
+      )
+    end
+    # steep:ignore:end
+
+    # 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]).
+    # 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" => Codec::Utils.deep_wrap(args, handle_table),
+        "kwargs" => Codec::Utils.deep_wrap(kwargs, handle_table)
+      )
+    end
+
+    private
+
+    # steep:ignore:start
+    # E-24: target must be a Symbol or String (TypeError, not
+    # ArgumentError — the wrong-type case is a Host App programming
+    # error before the invocation reaches the guest). E-25: after
+    # +.to_s+ the value must match NAME_PATTERN (ArgumentError),
+    # rejecting +::+-segmented names and any non-constant form.
+    def normalize_entrypoint(target)
+      unless target.is_a?(Symbol) || target.is_a?(String)
+        raise TypeError, "Invocation entrypoint must be a Symbol or String, got #{target.class}"
+      end
+
+      target_str = target.to_s
+      unless NAME_PATTERN.match?(target_str)
+        raise ArgumentError,
+              "Invocation entrypoint must match #{NAME_PATTERN.inspect} (got #{target.inspect})"
+      end
+
+      target_str.to_sym
+    end
+
+    # 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, forged_handle_message("args") if args.any?(Kobako::Handle)
+
+      args
+    end
+
+    # 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)
+
+      bad_keys = kwargs.each_key.grep_v(Symbol)
+      unless bad_keys.empty?
+        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/panic.rb

@@ -2,8 +2,8 @@
 
 module Kobako
   module Outcome
-    # SPEC.md → Outcome Envelope → Panic envelope ({SPEC.md Outcome
-    # Envelope}[link:../../../SPEC.md]). Wire-shaped failure record
+    # Wire-contract Outcome Envelope → Panic envelope ({docs/wire-contract.md
+    # Outcome Envelope}[link:../../../docs/wire-contract.md]). Wire-shaped failure record
     # carried in the OUTCOME_BUFFER when the guest run terminates with
     # an uncaught top-level exception.
     #

data/lib/kobako/outcome.rb

@@ -1,13 +1,14 @@
 # frozen_string_literal: true
 
 require_relative "outcome/panic"
+require_relative "rpc/wire_error"
 
 module Kobako
   # Host-facing boundary for the OUTCOME_BUFFER produced by
-  # +__kobako_run+. Takes raw outcome bytes — a one-byte tag followed by
+  # +__kobako_eval+. Takes raw outcome bytes — a one-byte tag followed by
   # the msgpack-encoded body — and maps them to either the unwrapped
   # mruby return value or a raised three-layer
-  # ({SPEC.md "Error Scenarios"}[link:../../SPEC.md]) exception.
+  # ({docs/behavior.md Error Scenarios}[link:../../docs/behavior.md]) exception.
   #
   # Self-contained: this module owns the wire framing (tag bytes,
   # body decoding), and the +Panic+ wire record lives at
@@ -24,7 +25,7 @@ module Kobako
   module Outcome
     # First byte of the OUTCOME_BUFFER for the success branch — body is
     # the bare msgpack encoding of the returned value
-    # ({SPEC.md Outcome Envelope}[link:../../SPEC.md]).
+    # ({docs/wire-contract.md Outcome Envelope}[link:../../docs/wire-contract.md]).
     TYPE_VALUE = 0x01
     # First byte of the OUTCOME_BUFFER for the failure branch — body is
     # the msgpack Panic map.
@@ -45,12 +46,20 @@ module Kobako
     end
 
     # TrapError for unknown or absent tag
-    # ({SPEC.md ABI Signatures}[link:../../SPEC.md]: len=0 and unknown-tag
-    # both walk the trap path).
+    # ({docs/wire-codec.md ABI Signatures}[link:../../docs/wire-codec.md]:
+    # 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(
@@ -100,7 +121,7 @@ module Kobako
     # Ruby exception. +origin == "service"+ → ServiceError (with the
     # +::Disconnected+ subclass selected when the panic carries the
     # disconnected sentinel —
-    # {SPEC "Error Classes"}[link:../../SPEC.md]); everything else
+    # {docs/behavior.md Error Classes}[link:../../docs/behavior.md]); everything else
     # → SandboxError.
     def build_panic_error(panic)
       panic_target_class(panic).new(
@@ -112,21 +133,37 @@ module Kobako
       )
     end
 
-    # {SPEC "Error Classes"}[link:../../SPEC.md]: when
-    # +origin="service"+ and the panic +class+ field names
-    # +ServiceError::Disconnected+, surface that subclass so callers can
-    # rescue the disconnected path specifically (E-14).
+    # {docs/behavior.md Error Classes}[link:../../docs/behavior.md]: map
+    # the panic +class+ field to the matching Ruby exception subclass so
+    # callers can rescue specific failure paths. +origin="service"+ plus
+    # +class="Kobako::ServiceError::Disconnected"+ selects the
+    # +Disconnected+ subclass (E-14); +origin="sandbox"+ plus
+    # +class="Kobako::BytecodeError"+ selects the +BytecodeError+
+    # subclass (E-37 / E-38). Everything else falls back to the base
+    # class for the origin.
     def panic_target_class(panic)
-      return SandboxError unless panic.origin == Panic::ORIGIN_SERVICE
-
-      panic.klass == "Kobako::ServiceError::Disconnected" ? ServiceError::Disconnected : ServiceError
+      case panic.origin
+      when Panic::ORIGIN_SERVICE
+        panic.klass == "Kobako::ServiceError::Disconnected" ? ServiceError::Disconnected : ServiceError
+      else
+        panic.klass == "Kobako::BytecodeError" ? BytecodeError : SandboxError
+      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

@@ -10,7 +10,7 @@ module Kobako
     # The module is stateless — all mutable state is threaded through the
     # +server+ argument so Dispatcher has no instance variables and no side
     # effects beyond mutating the HandleTable via +alloc+ when a non-wire-
-    # representable return value must be wrapped ({SPEC.md B-14}[link:../../../SPEC.md]).
+    # representable return value must be wrapped ({docs/behavior.md B-14}[link:../../../docs/behavior.md]).
     #
     # Entry point:
     #
@@ -22,34 +22,35 @@ module Kobako
       # Internal sentinel raised when target resolution fails. Mapped to
       # Response.error with type="undefined". Contained at the wire boundary —
       # not part of the public Kobako error taxonomy
-      # ({SPEC.md E-xx}[link:../../../SPEC.md]).
+      # ({docs/behavior.md E-xx}[link:../../../docs/behavior.md]).
       class UndefinedTargetError < StandardError; end
 
       # Internal sentinel raised when a Handle target resolves to the
       # +:disconnected+ sentinel in the HandleTable (ABA protection,
-      # {SPEC.md E-14}[link:../../../SPEC.md]). Mapped to Response.error with
+      # {docs/behavior.md E-14}[link:../../../docs/behavior.md]). Mapped to Response.error with
       # type="disconnected". Contained at the wire boundary.
       class DisconnectedTargetError < StandardError; end
 
       # 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
-      # ({SPEC.md B-12}[link:../../../SPEC.md]).
-      def dispatch(request_bytes, server)
+      # 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, 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
@@ -57,15 +58,16 @@ module Kobako
       # Map an error caught at the dispatch boundary to a +Response.error+
       # envelope. +error+ is the +StandardError+ caught by {#dispatch}'s
       # rescue. Returns a msgpack-encoded Response envelope (binary). Four
-      # error buckets ({SPEC.md B-12}[link:../../../SPEC.md]):
-      # +Kobako::Codec::Error+ → type="runtime" (wire decode failed);
+      # error buckets ({docs/behavior.md B-12}[link:../../../docs/behavior.md]):
+      # +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
 
-      # {SPEC.md B-16}[link:../../../SPEC.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
@@ -139,24 +141,24 @@ module Kobako
       end
 
       # Encode +value+ as a +Response.ok+ envelope. When the value is not
-      # wire-representable per {SPEC.md B-13}[link:../../../SPEC.md]'s type
+      # wire-representable per {docs/behavior.md B-13}[link:../../../docs/behavior.md]'s type
       # mapping, the +UnsupportedType+ rescue routes it through the
       # HandleTable via {#wrap_as_handle} and re-encodes with the Capability
-      # Handle in place ({SPEC.md B-14}[link:../../../SPEC.md]). The happy
+      # 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+
-      # that the wire codec can carry ({SPEC.md B-14}[link:../../../SPEC.md]).
+      # 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"
 
@@ -8,7 +8,7 @@ module Kobako
   # See lib/kobako/rpc.rb for the umbrella module doc; this file owns the
   # Request / Response value objects and their encode/decode helpers.
   module RPC
-    # ---------------- Response status bytes (SPEC.md Response Shape) ---
+    # ---------------- Response status bytes (docs/wire-contract.md § Response Shape) ---
 
     # Response variant marker for the success branch.
     STATUS_OK    = 0
@@ -16,7 +16,7 @@ module Kobako
     STATUS_ERROR = 1
 
     # Value object for a single guest-initiated RPC Request
-    # ({SPEC.md Wire Codec → Request}[link:../../../SPEC.md]).
+    # ({docs/wire-codec.md Envelope Encoding → Request}[link:../../../docs/wire-codec.md]).
     #
     # 4-element msgpack array: +[target, method, args, kwargs]+. +target+
     # is either a +String+ (+"Namespace::Member"+) or a {Handle}. SPEC pins
@@ -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
@@ -66,7 +66,7 @@ module Kobako
     end
 
     # Value object for a single host-side RPC Response
-    # ({SPEC.md Wire Codec → Response}[link:../../../SPEC.md]).
+    # ({docs/wire-codec.md Envelope Encoding → Response}[link:../../../docs/wire-codec.md]).
     #
     # 2-element msgpack array: +[status, value-or-fault]+. +status+ is 0
     # (success) or 1 (fault). For success the second element is the return
@@ -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

@@ -4,8 +4,9 @@ module Kobako
   module RPC
     # Wire-level value object for an ext-0x02 Exception envelope.
     #
-    # SPEC pins the payload (Wire Codec → Ext Types → ext 0x02) to a
-    # msgpack map with exactly three keys:
+    # SPEC pins the payload
+    # ({docs/wire-codec.md}[link:../../../docs/wire-codec.md] § Ext Types
+    # → ext 0x02) to a msgpack map with exactly three keys:
     #   * "type"    — one of "runtime", "argument", "disconnected", "undefined"
     #   * "message" — human-readable string
     #   * "details" — any wire-legal value, or nil when absent
@@ -22,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