kobako 0.4.0 → 0.5.0

data/lib/kobako/codec/utils.rb

@@ -5,22 +5,21 @@ require_relative "../handle"
 
 module Kobako
   module Codec
-    # Wire-codec helpers shared by the host-side encoders and decoders.
+    # Codec helpers shared by the host-side encoders and decoders.
     # Three concerns live here today:
     #
-    #   - UTF-8 assertion at the wire boundary
+    #   - 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}
     #     when validating the +ext 0x00+ Symbol payload.
-    #   - Wire-boundary +ArgumentError+ translation
-    #     ({wire_boundary}) so the public taxonomy stays
+    #   - +ArgumentError+ translation at the codec boundary
+    #     ({with_boundary}) so the public taxonomy stays
     #     {Kobako::Codec::Error}.
-    #   - Wire-representability predicate ({wire_representable?}) and
-    #     the symmetric host→guest +#run+ argument walk
-    #     ({deep_wrap}) used by +Kobako::Invocation#encode+ to route
-    #     non-wire-representable leaves through the Sandbox's
-    #     +Kobako::HandleTable+
+    #   - Representability predicate ({representable?}) and the symmetric
+    #     host→guest +#run+ argument walk ({deep_wrap}) used by
+    #     +Kobako::Transport::Run#encode+ to route non-representable leaves
+    #     through the Sandbox's +Kobako::Catalog::Handles+
     #     ({docs/behavior.md B-34}[link:../../../docs/behavior.md]).
     #
     # All helpers are pure — they only inspect inputs, never mutate
@@ -38,22 +37,21 @@ module Kobako
         raise InvalidEncoding, "#{label} is not valid UTF-8"
       end
 
-      # Run +block+ at the wire boundary: every wire Value Object
-      # (Handle / Fault / Request / Response / Panic) raises
-      # +ArgumentError+ when an invariant is violated at construction,
-      # and the wire boundary surfaces those violations to callers as
-      # {InvalidType} so the public taxonomy stays
-      # {Kobako::Codec::Error} and never leaks +ArgumentError+ from the
-      # Ruby standard library.
+      # 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
+      # the Ruby standard library.
       #
-      # Wrap any block that constructs a wire Value Object from decoded
-      # bytes with this helper to keep the five decode sites uniform —
-      # Request / Response in +Kobako::RPC+, Panic map in
-      # +Kobako::Outcome+, and the Handle / Fault ext-type unpackers in
-      # {Factory}. Do not use it for general-purpose validation outside
-      # the wire boundary — host-layer +ArgumentError+ values should
-      # propagate unchanged.
-      def wire_boundary
+      # Most construction sites no longer reach for this directly: a value
+      # object built inside a {Decoder.decode} block has its
+      # +ArgumentError+ mapped to {InvalidType} by the decoder's own
+      # rescue. The lone remaining caller is {Factory#unpack_handle}, which
+      # builds +Handle.restore+ from a raw 4-byte fixext payload without a
+      # {Decoder.decode} call. Do not use it for general-purpose validation
+      # outside the codec boundary — host-layer +ArgumentError+ values
+      # should propagate unchanged.
+      def with_boundary
         yield
       rescue ::ArgumentError => e
         raise InvalidType, e.message
@@ -64,43 +62,42 @@ module Kobako
       # unsigned +uint 64+ maximum
       # ({docs/wire-codec.md}[link:../../../docs/wire-codec.md] § Type
       # Mapping #3, the +fixint+ / +int 8..64+ / +uint 8..64+ union).
-      # Anchored as a +Range+ so {primitive_wire_type?} stays a single
-      # dispatch line. This is the codec's wire-encode domain — not to
+      # Anchored as a +Range+ so {primitive_type?} stays a single
+      # dispatch line. This is the codec's encode domain — not to
       # be confused with the Handle id range, which lives on
       # +Kobako::Handle+ as +MIN_ID+ / +MAX_ID+ (1..2^31 − 1) and
       # represents a different concept entirely.
       MSGPACK_INT_RANGE = (-(2**63)..((2**64) - 1))
 
-      # Wire-type predicate
+      # Codec-type predicate
       # ({docs/wire-codec.md}[link:../../../docs/wire-codec.md] § Type
       # Mapping). Returns +true+ when +value+ belongs to the closed
-      # 12-entry wire set — +nil+, +TrueClass+, +FalseClass+, +Integer+
-      # (in the +i64..u64+ value domain), +Float+, +String+, +Symbol+,
-      # +Kobako::Handle+, +Array+ whose every element is itself
-      # wire-representable, or +Hash+ whose every key and value are
-      # wire-representable. Integers outside the codec's signed-64 /
+      # 12-entry codec type set — +nil+, +TrueClass+, +FalseClass+,
+      # +Integer+ (in the +i64..u64+ value domain), +Float+, +String+,
+      # +Symbol+, +Kobako::Handle+, +Array+ whose every element is itself
+      # representable, or +Hash+ whose every key and value are
+      # representable. Integers outside the codec's signed-64 /
       # unsigned-64 union are rejected so the predicate agrees with the
       # msgpack gem's encode-time +RangeError+ behaviour the codec
       # already surfaces as {UnsupportedType}.
-      def wire_representable?(value)
-        primitive_wire_type?(value) || container_wire_representable?(value)
+      def representable?(value)
+        primitive_type?(value) || container_representable?(value)
       end
 
       # Deep-walk Array / Hash containers in +value+ and replace every
-      # leaf that fails {wire_representable?} with a +Kobako::Handle+
-      # allocated from +handle_table+
+      # leaf that fails {representable?} with a +Kobako::Handle+
+      # allocated from +handler+
       # ({docs/behavior.md B-34}[link:../../../docs/behavior.md]). The
-      # walk only descends through wire-representable container shapes
-      # (Array, Hash) one structural level at a time; a non-
-      # wire-representable leaf is wrapped as-is without inspecting its
-      # internal structure. An existing +Kobako::Handle+ is wire-
-      # representable and passes through unchanged — auto-wrap never
-      # re-wraps a Handle.
+      # walk only descends through representable container shapes
+      # (Array, Hash) one structural level at a time; a non-representable
+      # leaf is wrapped as-is without inspecting its internal structure.
+      # An existing +Kobako::Handle+ is representable and passes through
+      # unchanged — auto-wrap never re-wraps a Handle.
       #
-      # +value+ may be any Ruby value; +handle_table+ must respond to
+      # +value+ may be any Ruby value; +handler+ must respond to
       # +#alloc(object) -> Kobako::Handle+ (a host-side
-      # +Kobako::HandleTable+). Returns a structurally equivalent value
-      # whose leaves are either wire-representable or +Kobako::Handle+
+      # +Kobako::Catalog::Handles+). Returns a structurally equivalent value
+      # whose leaves are either representable or +Kobako::Handle+
       # tokens.
       #
       # The block bodies spell +Utils.deep_wrap+ explicitly rather than
@@ -110,20 +107,20 @@ module Kobako
       # (still +Utils+ at definition time, but the qualified form keeps
       # the dispatch readable when the recursive call sits inside a
       # Proc captured from elsewhere).
-      def deep_wrap(value, handle_table)
+      def deep_wrap(value, handler)
         case value
-        when ::Array then value.map { |element| Utils.deep_wrap(element, handle_table) }
-        when ::Hash  then value.transform_values { |val| Utils.deep_wrap(val, handle_table) }
+        when ::Array then value.map { |element| Utils.deep_wrap(element, handler) }
+        when ::Hash  then value.transform_values { |val| Utils.deep_wrap(val, handler) }
         else
-          wire_representable?(value) ? value : handle_table.alloc(value)
+          representable?(value) ? value : handler.alloc(value)
         end
       end
 
-      # Predicate split out of {wire_representable?} for cyclomatic
+      # Predicate split out of {representable?} for cyclomatic
       # budget — the closed-set non-container branch. Returns +true+ for
-      # the wire scalar leaves and an existing Handle. Not part of the
-      # public surface; reach for {wire_representable?} instead.
-      def primitive_wire_type?(value)
+      # the scalar leaves and an existing Handle. Not part of the
+      # public surface; reach for {representable?} instead.
+      def primitive_type?(value)
         case value
         when ::NilClass, ::TrueClass, ::FalseClass, ::Float, ::String, ::Symbol, Kobako::Handle then true
         when ::Integer then MSGPACK_INT_RANGE.cover?(value)
@@ -131,15 +128,15 @@ module Kobako
         end
       end
 
-      # Predicate split out of {wire_representable?} for cyclomatic
+      # Predicate split out of {representable?} for cyclomatic
       # budget — the container branch. Recurses into Array elements and
-      # Hash key+value pairs through the public {wire_representable?}.
-      # Not part of the public surface; reach for {wire_representable?}
+      # Hash key+value pairs through the public {representable?}.
+      # Not part of the public surface; reach for {representable?}
       # instead.
-      def container_wire_representable?(value)
+      def container_representable?(value)
         case value
-        when ::Array then value.all? { |element| Utils.wire_representable?(element) }
-        when ::Hash  then value.all? { |key, val| Utils.wire_representable?(key) && Utils.wire_representable?(val) }
+        when ::Array then value.all? { |element| Utils.representable?(element) }
+        when ::Hash  then value.all? { |key, val| Utils.representable?(key) && Utils.representable?(val) }
         else false
         end
       end

data/lib/kobako/codec.rb

@@ -6,9 +6,12 @@ module Kobako
   # Host-side MessagePack codec for the kobako wire contract — the
   # byte-level layer ({docs/wire-codec.md}[link:../../docs/wire-codec.md]).
   # Two consumers sit on top:
-  # +Kobako::RPC+ pins the RPC framing (Request / Response)
-  # and +Kobako::Outcome+ owns the per-+#run+ outcome envelope (Result
-  # body / Panic map).
+  # +Kobako::Transport+ pins the host↔guest framing (Request / Response /
+  # Run / Yield) and +Kobako::Outcome+ owns the per-+#run+ outcome
+  # envelope (Result body / Panic map). The ext-type leaves this layer
+  # carries — +Kobako::Handle+ (0x01) and +Kobako::Fault+ (0x02) — live at
+  # 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

data/lib/kobako/errors.rb

@@ -2,29 +2,39 @@
 
 # Top-level Kobako namespace.
 module Kobako
-  # Three-class error taxonomy (docs/behavior.md § Error Scenarios).
+  # Error taxonomy (docs/behavior.md § Error Scenarios).
   #
   # Every `Kobako::Sandbox` invocation (`#eval` or `#run`) either returns a value or raises
-  # exactly one of these three classes. Attribution is decided after the
+  # exactly one of three invocation-outcome classes. Attribution is decided after the
   # guest binary returns control to the host (docs/behavior.md
   # "Step 1 — Wasm trap" then "Step 2 — Outcome envelope tag").
   #
-  # Three top-level branches:
+  # 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,
-  #                       HandleTable exhaustion, output buffer overrun).
-  #   * {ServiceError}  — service / capability layer (a Service RPC that
-  #                       failed and was not rescued inside the script).
+  #                       Catalog::Handles exhaustion, output buffer overrun).
+  #   * {ServiceError}  — service / capability layer (a Service capability
+  #                       call that failed and was not rescued inside the
+  #                       script).
+  #
+  # A fourth branch sits 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
+  #                       (docs/behavior.md E-40 / E-41). Not an invocation
+  #                       outcome, so it never passes through the two-step
+  #                       attribution decision.
   #
   # Subclasses pinned by docs/behavior.md Error Classes:
   #
-  #   * {HandleTableExhausted} < {SandboxError}    — id cap hit (B-21).
-  #   * {ServiceError::Disconnected} < {ServiceError} — `:disconnected`
-  #                       sentinel hit on the HandleTable (E-14).
+  #   * {ModuleNotBuiltError} < {SetupError} — Guest Binary artifact absent
+  #                       at +wasm_path+ (E-40).
+  #   * {HandlerExhaustedError} < {SandboxError} — Handle id cap hit (B-21).
 
   # Base for all kobako-raised errors so callers that want to ignore the
   # taxonomy can rescue a single class.
@@ -59,6 +69,27 @@ module Kobako
   # point; discard and recreate before another execution.
   class MemoryLimitError < TrapError; end
 
+  # Construction-layer error raised by +Kobako::Sandbox.new+ /
+  # +Kobako::Runtime.from_path+ when the wasm runtime cannot be built
+  # from the configured +wasm_path+ before any invocation runs —
+  # an unreadable artifact, bytes that are not a valid Wasm module, or
+  # engine / linker / instantiation setup failure
+  # ({docs/behavior.md E-41}[link:../../docs/behavior.md]). Construction
+  # is not an invocation, so +SetupError+ sits beside the invocation
+  # taxonomy under +Kobako::Error+ rather than under +TrapError+: no
+  # Sandbox is produced, so the +TrapError+ "discard and recreate"
+  # recovery contract does not apply.
+  class SetupError < Error; end
+
+  # The named +SetupError+ subclass for the common, actionable case:
+  # the Guest Binary artifact is absent at +wasm_path+ — the pre-build
+  # state on a fresh clone before +bundle exec rake compile+
+  # ({docs/behavior.md E-40}[link:../../docs/behavior.md]). Host Apps
+  # that only need "the Sandbox could not be set up" rescue +SetupError+;
+  # those wanting to special-case the unbuilt-artifact state rescue
+  # +ModuleNotBuiltError+ first.
+  class ModuleNotBuiltError < SetupError; end
+
   # Sandbox / wire layer. Raised when the guest ran to completion but
   # execution failed due to a mruby script error, a protocol fault, or a
   # host-side wire decode failure on an otherwise valid outcome tag.
@@ -87,27 +118,13 @@ module Kobako
       @backtrace_lines = backtrace_lines
       @details = details
     end
-
-    # docs/behavior.md Error Classes: ServiceError::Disconnected is raised
-    # when the RPC target Handle resolves to the `:disconnected` sentinel
-    # in the HandleTable (ABA protection rule — id exists but entry was
-    # invalidated). E-14.
-    class Disconnected < ServiceError; end
   end
 
-  # HandleTable lookup-failure error (unknown id passed to #fetch /
-  # #release). A SandboxError subclass: per the wire-layer rule, an
-  # unknown Handle id surfaces as a `type="undefined"` Response.error
-  # envelope inside RpcDispatcher and never reaches the Host App
-  # directly; outside that path (e.g. tests poking the HandleTable
-  # directly), it surfaces as a SandboxError.
-  class HandleTableError < SandboxError; end
-
-  # docs/behavior.md Error Classes: HandleTableExhausted is the canonical
-  # SandboxError subclass for the id-cap-hit path (B-21). Inherits from
-  # HandleTableError so a single `rescue Kobako::HandleTableError` covers
-  # both lookup-failure and cap-exhaustion paths.
-  class HandleTableExhausted < HandleTableError; end
+  # docs/behavior.md Error Classes: HandlerExhaustedError is the canonical
+  # SandboxError subclass for the id-cap-hit path (B-21). Raised when the
+  # per-invocation Handle ID counter in Catalog::Handles reaches
+  # +0x7fff_ffff+ (2³¹ − 1) and further allocation would exceed the cap.
+  class HandlerExhaustedError < SandboxError; end
 
   # docs/behavior.md Error Classes: BytecodeError is the SandboxError
   # subclass raised when a `#preload(binary:)` snippet fails structural

data/lib/kobako/fault.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Kobako
+  # Wire-level value object for an ext-0x02 Exception envelope.
+  #
+  # 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::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
+  # upward on Transport.
+  #
+  # 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", "undefined"
+  #   * "message" — human-readable string
+  #   * "details" — any wire-legal value, or nil when absent
+  #
+  # This object holds the *encoded* form. Reifying the corresponding Ruby
+  # exception class (RuntimeError, ArgumentError, Kobako::ServiceError, ...)
+  # is the responsibility of the dispatch layer, not the codec.
+  #
+  # Built on the +class X < Data.define(...)+ subclass form so the
+  # class body is fully Steep-visible; ruby/rbs upstream documents
+  # this as the Steep-friendly shape and the +Style/DataInheritance+
+  # cop is disabled on that basis (see +.rubocop.yml+).
+  class Fault < Data.define(:type, :message, :details)
+    VALID_TYPES = %w[runtime argument undefined].freeze
+
+    def initialize(type:, message:, details: nil)
+      raise ArgumentError, "type must be String"    unless type.is_a?(String)
+      raise ArgumentError, "message must be String" unless message.is_a?(String)
+      raise ArgumentError, "type=#{type.inspect} not one of #{VALID_TYPES.inspect}" unless VALID_TYPES.include?(type)
+
+      super
+    end
+  end
+end

data/lib/kobako/handle.rb

@@ -16,9 +16,9 @@ module Kobako
   # 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 {.from_wire}, which exists at exactly two call
+  # Handles through {.restore}, which exists at exactly two call
   # sites: +Kobako::Codec::Factory#unpack_handle+ (wire decode) and
-  # +Kobako::Codec::Utils.deep_wrap+ / +Kobako::RPC::Dispatcher#wrap_as_handle+
+  # +Kobako::Codec::Utils.deep_wrap+ / +Kobako::Transport::Dispatcher#wrap_as_handle+
   # (allocator paths). Both live inside +lib/kobako/+ and are not part
   # of any public surface.
   #
@@ -34,14 +34,12 @@ module Kobako
     # on either side of the wire without re-encoding.
     MAX_ID = 0x7fff_ffff
 
-    # steep:ignore:start
     def initialize(id:)
       raise ArgumentError, "Handle id must be Integer" unless id.is_a?(Integer)
       raise ArgumentError, "Handle id #{id} out of range [#{MIN_ID}, #{MAX_ID}]" unless id.between?(MIN_ID, MAX_ID)
 
       super
     end
-    # steep:ignore:end
 
     private_class_method :new
 
@@ -52,10 +50,10 @@ module Kobako
     #
     # Two collaborators call this: the codec when an ext 0x01 frame is
     # decoded off the wire, and the allocator paths when a host-side
-    # Ruby object is registered into the Sandbox's +HandleTable+. Both
+    # Ruby object is registered into the Sandbox's +Catalog::Handles+. Both
     # paths live inside +lib/kobako/+ and treat this method as a
     # package-private constructor.
-    def self.from_wire(id)
+    def self.restore(id)
       allocate.tap { |handle| handle.send(:initialize, id: id) }
     end
   end

data/lib/kobako/namespace.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Kobako
+  # A named grouping of Members for one Sandbox
+  # ({docs/behavior.md B-07..B-11}[link:../../docs/behavior.md]).
+  # Returned by +Sandbox#define+. Each instance owns a flat name→object
+  # table of Members; member binding is validated against {NAME_PATTERN}.
+  class Namespace
+    # Ruby constant-name pattern shared by Namespace and Member names
+    # ({docs/behavior.md B-07/B-08 Notes}[link:../../docs/behavior.md]).
+    NAME_PATTERN = /\A[A-Z]\w*\z/
+
+    attr_reader :name
+
+    # Build a new Namespace. +name+ is an already-validated Namespace
+    # name (must satisfy {NAME_PATTERN}; validation is the caller's
+    # responsibility).
+    def initialize(name)
+      @name = name
+      @members = {} # : Hash[String, untyped]
+    end
+
+    # Bind +object+ under +member+ inside this Namespace. +member+ is a
+    # constant-form name as a +Symbol+ or +String+. +object+ is any Ruby
+    # object that responds to the methods guest code will invoke. Returns
+    # +self+ for chaining. Raises +ArgumentError+ when +member+ does not
+    # match the constant pattern, or a Member of the same name is already
+    # bound ({docs/behavior.md B-11}[link:../../docs/behavior.md]).
+    def bind(member, object)
+      member_str = validate_member_name!(member)
+      raise ArgumentError, "Member #{@name}::#{member_str} is already bound" if @members.key?(member_str)
+
+      @members[member_str] = object
+      self
+    end
+
+    # Member lookup; raises +KeyError+ when no Member is registered
+    # under +member+.
+    def fetch(member)
+      member_str = member.to_s
+      unless @members.key?(member_str)
+        raise KeyError,
+              "no member named #{member_str.inspect} in namespace #{@name.inspect}"
+      end
+
+      @members[member_str]
+    end
+
+    # Structured description for the guest preamble (Frame 1). Returns a
+    # two-element array +[name, member_keys]+ suitable for msgpack encoding.
+    def to_preamble
+      [@name, @members.keys]
+    end
+
+    private
+
+    def validate_member_name!(member)
+      member_str = member.to_s
+      unless NAME_PATTERN.match?(member_str)
+        raise ArgumentError,
+              "MemberName must match #{NAME_PATTERN.inspect} (got #{member.inspect})"
+      end
+
+      member_str
+    end
+  end
+end

data/lib/kobako/outcome.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "outcome/panic"
-require_relative "rpc/wire_error"
+require_relative "transport/error"
 
 module Kobako
   # Host-facing boundary for the OUTCOME_BUFFER produced by
@@ -14,7 +14,7 @@ module Kobako
   # body decoding), and the +Panic+ wire record lives at
   # +Kobako::Outcome::Panic+. The byte-level msgpack codec at
   # +Kobako::Codec+ is invoked for the body itself; otherwise
-  # nothing in +RPC+ participates.
+  # nothing in +Transport+ participates.
   #
   #   * tag 0x01, decode OK                 → return decoded value
   #   * tag 0x01, decode fails              → SandboxError (E-09)
@@ -73,16 +73,16 @@ module Kobako
 
     # Decode failure on the success tag is a SandboxError (E-09): the
     # framing was fine, but the carried value is unrepresentable. The
-    # specific codec fault is stashed in +details[:wire_error]+ rather
+    # specific codec fault is stashed in +details+ 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(
+      raise build_transport_error(
         "Sandbox produced an invalid result value",
-        wire_error: e.message
+        detail: e.message
       )
     end
 
@@ -91,25 +91,25 @@ module Kobako
     # layer exception via +build_panic_error+ and raised; on wire-decode
     # failure the rescue path raises the wire-violation +SandboxError+.
     def decode_panic(body)
-      raise build_panic_error(parse_panic(body))
+      raise build_panic_error(build_panic_record(body))
     rescue Kobako::Codec::Error => e
-      raise build_wire_violation_error(
+      raise build_transport_error(
         "Sandbox produced an invalid panic record",
-        wire_error: e.message
+        detail: 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+. 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 body must be a map, got #{map.class}" unless map.is_a?(Hash)
+    # +Kobako::Codec::InvalidType+ when the body is not a map or when
+    # required keys are missing — both routed by +decode_panic+ to
+    # +build_transport_error+. The decode runs in block form so
+    # +Panic.new+'s +ArgumentError+ invariants surface as +InvalidType+
+    # 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)
 
-      Kobako::Codec::Utils.wire_boundary do
         Panic.new(
           origin: map["origin"], klass: map["class"], message: map["message"],
           backtrace: map["backtrace"] || [], details: map["details"]
@@ -118,11 +118,8 @@ module Kobako
     end
 
     # Map a decoded Panic record into the corresponding three-layer
-    # Ruby exception. +origin == "service"+ → ServiceError (with the
-    # +::Disconnected+ subclass selected when the panic carries the
-    # disconnected sentinel —
-    # {docs/behavior.md Error Classes}[link:../../docs/behavior.md]); everything else
-    # → SandboxError.
+    # Ruby exception. +origin == "service"+ → ServiceError; everything
+    # else → SandboxError.
     def build_panic_error(panic)
       panic_target_class(panic).new(
         panic.message,
@@ -133,37 +130,36 @@ module Kobako
       )
     end
 
-    # {docs/behavior.md Error Classes}[link:../../docs/behavior.md]: map
+    # {docs/behavior.md Error Scenarios}[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
+    # callers can rescue specific failure paths. +origin="service"+ →
+    # +ServiceError+; +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)
       case panic.origin
       when Panic::ORIGIN_SERVICE
-        panic.klass == "Kobako::ServiceError::Disconnected" ? ServiceError::Disconnected : ServiceError
+        ServiceError
       else
         panic.klass == "Kobako::BytecodeError" ? BytecodeError : SandboxError
       end
     end
 
     # Lift the wire-violation fallback to the real
-    # +Kobako::RPC::WireError+ class so callers can +rescue+ it
+    # +Kobako::Transport::Error+ 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(
+    # +detail+ carries the inner codec / framing message, stashed
+    # directly into +details+ for operator diagnosis without polluting
+    # the user-facing +#message+.
+    def build_transport_error(message, detail: nil)
+      Kobako::Transport::Error.new(
         message,
         origin: Panic::ORIGIN_SANDBOX,
-        klass: "Kobako::RPC::WireError",
-        details: wire_error.nil? ? nil : { wire_error: wire_error }
+        klass: "Kobako::Transport::Error",
+        details: detail
       )
     end
   end

data/lib/kobako/runtime.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Kobako
+  # Host-side wasmtime runtime, surfaced as a Ruby class by the native ext
+  # (see ext/kobako/src/runtime.rs). The +Kobako::Runtime+ class wraps the
+  # wasmtime engine + compiled module + Store; it is the only Ruby-visible
+  # wasmtime type and the foundational binding layer for +Kobako::Sandbox+.
+  #
+  # This file reopens the magnus-defined class only to add the pure-Ruby
+  # +.default_path+ helper. Every other method (+#from_path+ singleton,
+  # +#eval+ / +#run+, capture and usage readers) is registered from Rust
+  # at ext load time.
+  class Runtime
+    # Absolute path to the gem-bundled +data/kobako.wasm+ artifact. Computed
+    # from this file's location so it works for both +bundle exec+ (running
+    # from the repo) and an installed gem (running from the gem dir).
+    #
+    # Returns a String regardless of whether the file currently exists —
+    # call sites that need the file to be present should pass this through
+    # +Kobako::Runtime.from_path+, which raises
+    # +Kobako::ModuleNotBuiltError+ with a clear remediation message.
+    # Raises +Kobako::SetupError+ if +__dir__+ is unavailable so that
+    # +rescue Kobako::SetupError+ around +Kobako::Sandbox.new+ catches every
+    # construction-layer failure uniformly, including this path-resolution one.
+    def self.default_path
+      dir = __dir__ or raise Kobako::SetupError, "Kobako::Runtime.default_path requires __dir__"
+      File.expand_path("../../data/kobako.wasm", dir)
+    end
+  end
+end