kobako 0.4.0 → 0.6.0

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

data/lib/kobako/sandbox.rb

@@ -3,29 +3,29 @@
 require "forwardable"
 
 require_relative "capture"
+require_relative "codec"
 require_relative "errors"
-require_relative "handle_table"
-require_relative "invocation"
 require_relative "outcome"
-require_relative "rpc/server"
-require_relative "rpc/envelope"
 require_relative "sandbox_options"
-require_relative "snippet"
 require_relative "usage"
+require_relative "transport"
+require_relative "catalog"
 
 module Kobako
   # Kobako::Sandbox — the user-facing entry point for executing guest mruby
   # scripts inside a wasmtime-hosted Wasm module
   # ({docs/behavior.md B-01}[link:../../docs/behavior.md]).
   #
-  # The Sandbox owns the +Kobako::Wasm::Instance+, the per-Sandbox
-  # +Kobako::HandleTable+ ({docs/behavior.md B-19}[link:../../docs/behavior.md]),
-  # the per-instance RPC Server (which receives the HandleTable by
-  # injection so guest→host dispatch and host→guest auto-wrap share one
-  # allocator), and the per-channel byte caches for guest stdout / stderr
-  # capture. The underlying wasmtime Engine and compiled Module are cached
-  # at process scope by the native ext and never surface to Ruby —
-  # constructing many Sandboxes amortises both costs automatically.
+  # The Sandbox owns the +Kobako::Runtime+, the per-Sandbox
+  # +Kobako::Catalog::Handles+ ({docs/behavior.md B-19}[link:../../docs/behavior.md]),
+  # the per-instance +Kobako::Catalog::Namespaces+ (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=+ ({docs/behavior.md B-12}[link:../../docs/behavior.md]).
+  # The underlying wasmtime Engine and compiled Module are cached at process
+  # scope by the native ext and never surface to Ruby — constructing many
+  # Sandboxes amortises both costs automatically.
   #
   # Output capture policy ({docs/behavior.md B-04}[link:../../docs/behavior.md]): the
   # per-channel cap (+stdout_limit+ / +stderr_limit+) is enforced inside the
@@ -38,9 +38,7 @@ module Kobako
   class Sandbox
     extend Forwardable
 
-    attr_reader :wasm_path, :instance,
-                :options,
-                :services, :snippets
+    attr_reader :wasm_path, :options
 
     # Per-cap accessors forward to the immutable +SandboxOptions+ Value
     # Object so the Host App still reads them off Sandbox directly.
@@ -99,21 +97,22 @@ module Kobako
     def initialize(wasm_path: nil, stdout_limit: nil, stderr_limit: nil,
                    timeout: SandboxOptions::DEFAULT_TIMEOUT_SECONDS,
                    memory_limit: SandboxOptions::DEFAULT_MEMORY_LIMIT)
-      @wasm_path = wasm_path || Kobako::Wasm.default_path
+      @wasm_path = wasm_path || Kobako::Runtime.default_path
       @options = SandboxOptions.new(timeout: timeout, memory_limit: memory_limit, stdout_limit: stdout_limit,
                                     stderr_limit: stderr_limit)
-      @handle_table = HandleTable.new
-      @services = Kobako::RPC::Server.new(handle_table: @handle_table)
-      @snippets = Snippet::Table.new
-      @instance = Kobako::Wasm::Instance.from_path(@wasm_path, @options.timeout, @options.memory_limit,
-                                                   @options.stdout_limit, @options.stderr_limit)
-      @instance.server = @services
+      @handler = Catalog::Handles.new
+      @services = Kobako::Catalog::Namespaces.new(handler: @handler)
+      @snippets = Catalog::Snippets.new
+      @runtime = Kobako::Runtime.from_path(@wasm_path, @options.timeout, @options.memory_limit,
+                                           @options.stdout_limit, @options.stderr_limit)
+      install_dispatch_proc!
       reset_invocation_state!
     end
 
     # Declare or retrieve the Namespace named +name+ on this Sandbox
     # ({docs/behavior.md B-07, B-09, B-10}[link:../../docs/behavior.md]). +name+ must be a
-    # Symbol or String in constant form. Returns the +Kobako::RPC::Namespace+.
+    # Symbol or String in constant form. Returns the
+    # +Kobako::Namespace+.
     #
     # Raises +ArgumentError+ when called after the first invocation, or
     # when +name+ does not match the constant-name pattern.
@@ -160,17 +159,19 @@ module Kobako
 
     # Dispatch into a preloaded entrypoint constant
     # ({docs/behavior.md B-31}[link:../../docs/behavior.md]). Delegates host
-    # pre-flight (E-24 / E-25 / E-29 / E-30) and wire encoding to
-    # +Kobako::Invocation+ / +Kobako::Invocation#encode+; the guest
-    # resolves +target+ as a top-level constant, calls +#call+ on it
-    # with +args+ / +kwargs+, and returns the deserialized result. The
-    # first invocation seals the Service registry and snippet table
-    # (B-07 / B-33). Runtime errors follow the same three-class taxonomy
-    # as +#eval+.
+    # pre-flight and wire encoding to +Kobako::Transport::Run+ /
+    # +Kobako::Transport::Run#encode+: a non-Symbol/String +target+ raises
+    # +TypeError+ (E-24), while a +target+ failing the constant pattern
+    # (E-25), a forged +Kobako::Handle+ in +args+ / +kwargs+ (E-29), or a
+    # non-Symbol +kwargs+ key (E-30) raise +ArgumentError+. The guest
+    # resolves +target+ as a top-level constant, calls +#call+ on it with
+    # +args+ / +kwargs+, and returns the deserialized result. The first
+    # invocation seals the Service registry and snippet table (B-07 /
+    # B-33). Runtime errors follow the same three-class taxonomy as +#eval+.
     def run(target, *args, **kwargs)
-      invocation = Invocation.new(entrypoint: target, args: args, kwargs: kwargs)
+      run_envelope = Transport::Run.new(entrypoint: target, args: args, kwargs: kwargs)
       invoke!(:run) do
-        @instance.run(@services.encoded_preamble, @snippets.encode, invocation.encode(@handle_table))
+        @runtime.run(@services.encode, @snippets.encode, run_envelope.encode(@handler))
       end
     end
 
@@ -201,23 +202,38 @@ module Kobako
       raise SandboxError, "code must be a String, got #{code.class}" unless code.is_a?(String)
 
       invoke!(:eval) do
-        @instance.eval(@services.encoded_preamble, code.b, @snippets.encode)
+        @runtime.eval(@services.encode, code.b, @snippets.encode)
       end
     end
 
     private
 
+    # Configure the +Runtime+'s host↔guest dispatch wiring
+    # ({docs/behavior.md B-12}[link:../../docs/behavior.md]). Builds a
+    # lambda that re-enters the guest via
+    # +Runtime#yield_to_active_invocation+ (B-24) and a dispatch +Proc+
+    # that routes guest→host calls through the stateless
+    # +Transport::Dispatcher+, capturing +@services+ / +@handler+ in the
+    # closure. Both are registered on the +Runtime+ once at construction
+    # time so the wasm ext callback can fire without further setup.
+    def install_dispatch_proc!
+      yield_to_guest = ->(args_bytes) { @runtime.yield_to_active_invocation(args_bytes) }
+      @runtime.on_dispatch = lambda do |request_bytes|
+        Transport::Dispatcher.dispatch(request_bytes, @services, @handler, yield_to_guest)
+      end
+    end
+
     # Per-invocation prologue ({docs/behavior.md B-03 / B-07 /
     # B-33}[link:../../docs/behavior.md]). Seals the Service / snippet
     # registries on first call (idempotent) and zeros the per-invocation
     # capability state — capture buffers, truncation predicates, and the
-    # HandleTable counter — before the guest runs. The HandleTable
-    # itself is held as +@handle_table+ and never exposed beyond
+    # +Catalog::Handles+ counter — before the guest runs. The
+    # +Catalog::Handles+ itself is held as +@handler+ and never exposed beyond
     # this class: SPEC.md Terminology pins it as "Not exposed to the
     # Host App" (B-19 / B-20 / E-29).
     def begin_invocation!
       @services.seal!
-      @handle_table.reset!
+      @handler.reset!
       reset_invocation_state!
     end
 
@@ -235,66 +251,66 @@ module Kobako
       @usage = Usage::EMPTY
     end
 
-    # Read the per-channel capture pairs (+[bytes, truncated]+) from the
-    # ext after an invocation completes and wrap each as a +Capture+ value
-    # object. The ext clips +bytes+ to the configured cap and sets
-    # +truncated+ when the guest produced strictly more than +cap+ bytes
-    # ({docs/behavior.md B-04}[link:../../docs/behavior.md]). Mirror of
-    # {#reset_invocation_state!} at the post-invocation boundary.
-    def read_captures!
-      out_bytes, out_truncated = @instance.stdout
-      err_bytes, err_truncated = @instance.stderr
-      @stdout_capture = Capture.from_ext(out_bytes, out_truncated)
-      @stderr_capture = Capture.from_ext(err_bytes, err_truncated)
-    end
-
     # Read the per-last-invocation +wall_time+ and +memory_peak+ from
     # the ext and wrap them as a +Kobako::Usage+ value object
     # ({docs/behavior.md B-35}[link:../../docs/behavior.md]). Runs in
     # the +invoke!+ +ensure+ block so the usage record is populated on
     # every outcome — value return, +Kobako::TrapError+ (including
     # +TimeoutError+ / +MemoryLimitError+), +Kobako::SandboxError+,
-    # and +Kobako::ServiceError+.
+    # and +Kobako::ServiceError+. On the success path the same figures
+    # already arrive via +Snapshot#usage+; on the trap path the Snapshot
+    # never reaches Ruby so the ext readout here is the only source.
     #
     # 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, mirroring
-    # +#read_captures!+'s +Capture.from_ext(bytes, truncated)+ shape.
+    # positional→keyword conversion point.
     def read_usage!
-      wall_time, memory_peak = @instance.usage
+      wall_time, memory_peak = @runtime.usage
       @usage = Usage.new(wall_time: wall_time, memory_peak: memory_peak)
     end
 
-    # Map a wasmtime trap class to the matching three-layer Ruby
-    # exception class. Cap-trap subclasses
+    # Pick the +TrapError+ subclass to re-raise based on +err+'s actual
+    # class. Cap-trap subclasses
     # ({docs/behavior.md E-19 / E-20}[link:../../docs/behavior.md])
-    # select their named +TrapError+ subclass; everything else
-    # collapses to the base +Kobako::TrapError+.
+    # preserve their named identity; everything else collapses to the
+    # base +Kobako::TrapError+. The ext already raises the right subclass
+    # directly, so this is a pure re-attribution that lets +#invoke!+
+    # add the verb prefix without erasing +TimeoutError+ /
+    # +MemoryLimitError+.
     def trap_class_for(err)
       case err
-      when Kobako::Wasm::TimeoutError     then TimeoutError
-      when Kobako::Wasm::MemoryLimitError then MemoryLimitError
+      when TimeoutError     then TimeoutError
+      when MemoryLimitError then MemoryLimitError
       else TrapError
       end
     end
 
     # Shared prologue / epilogue + trap-class translator for both
     # invocation verbs. +verb+ is +:eval+ or +:run+; it tags the
-    # TrapError message so the failing export is identifiable. The
-    # rescue chain is the single trap-translation boundary — wasmtime /
-    # wire failures from the guest call and from the subsequent
-    # +Instance#outcome!+ read both flow through here, so an
-    # OUTCOME_BUFFER read failure attributes to the same export name as
-    # the guest call itself. Configured-cap paths
-    # ({docs/behavior.md E-19 / E-20}[link:../../docs/behavior.md]) surface as
-    # named TrapError subclasses.
+    # TrapError message so the failing export is identifiable.
+    #
+    # The yielded block must return a +Kobako::Snapshot+ — i.e. the
+    # value of +Runtime#eval+ / +#run+ (SPEC.md Internal Concepts →
+    # Snapshot). The success path unpacks every observable from the
+    # Snapshot in one go: +#stdout+ / +#stderr+ pack into +Capture+,
+    # +#usage+ packs into +Usage+, +#return_bytes+ feeds +Outcome.decode+.
+    # The rescue chain is the single trap-translation boundary —
+    # configured-cap paths
+    # ({docs/behavior.md E-19 / E-20}[link:../../docs/behavior.md])
+    # surface as named TrapError subclasses; everything else surfaces as
+    # the base +TrapError+.
     def invoke!(verb)
       begin_invocation!
-      yield
-      read_captures!
-      Outcome.decode(@instance.outcome!)
-    rescue Kobako::Wasm::Error => e
+      snapshot = yield
+      @stdout_capture = snapshot.stdout
+      @stderr_capture = snapshot.stderr
+      # A Capability Handle in the result is decoded as a Kobako::Handle
+      # token; restore it to the host object the guest referenced before
+      # handing the value to the Host App (B-37). @handler still holds this
+      # invocation's table — reset only happens at the next #begin_invocation!.
+      Codec::Utils.deep_restore(Outcome.decode(snapshot.return_bytes), @handler)
+    rescue Kobako::TrapError => e
       raise trap_class_for(e), "Sandbox##{verb} failed: #{e.message}"
     ensure
       read_usage!

data/lib/kobako/sandbox_options.rb

@@ -11,7 +11,7 @@ module Kobako
   # for absent values and normalises (timeout to Float seconds,
   # memory_limit to positive Integer bytes) before delegating to Data's
   # +super+. Anything that survives +SandboxOptions.new+ is a wire-ready
-  # cap bundle the +Kobako::Wasm::Instance+ constructor consumes as-is.
+  # cap bundle the +Kobako::Runtime+ constructor consumes as-is.
   class SandboxOptions < Data.define(:timeout, :memory_limit, :stdout_limit, :stderr_limit)
     # Default wall-clock timeout for a single invocation: 60 seconds
     # ({docs/behavior.md B-01}[link:../../docs/behavior.md]).
@@ -27,17 +27,15 @@ module Kobako
     # ({docs/behavior.md B-01}[link:../../docs/behavior.md]).
     DEFAULT_OUTPUT_LIMIT = 1 << 20
 
-    # steep:ignore:start
     def initialize(timeout: DEFAULT_TIMEOUT_SECONDS,
                    memory_limit: DEFAULT_MEMORY_LIMIT,
                    stdout_limit: nil,
                    stderr_limit: nil)
-      super(
-        timeout: normalize_timeout(timeout),
-        memory_limit: normalize_memory_limit(memory_limit),
-        stdout_limit: stdout_limit || DEFAULT_OUTPUT_LIMIT,
-        stderr_limit: stderr_limit || DEFAULT_OUTPUT_LIMIT
-      )
+      timeout = normalize_timeout(timeout)
+      memory_limit = normalize_memory_limit(memory_limit)
+      stdout_limit ||= DEFAULT_OUTPUT_LIMIT
+      stderr_limit ||= DEFAULT_OUTPUT_LIMIT
+      super
     end
 
     private
@@ -68,6 +66,5 @@ module Kobako
 
       memory_limit
     end
-    # steep:ignore:end
   end
 end

data/lib/kobako/snapshot.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative "capture"
+require_relative "usage"
+
+module Kobako
+  # Kobako::Snapshot — per-invocation observable bundle returned from
+  # +Kobako::Runtime#eval+ and +#run+.
+  #
+  # The magnus class (see ext/kobako/src/snapshot.rs) carries seven raw
+  # readers: +return_bytes+, +stdout_bytes+, +stdout_truncated+,
+  # +stderr_bytes+, +stderr_truncated+, +wall_time+, +memory_peak+. This
+  # file reopens the class to add the Ruby-side helpers that pack those
+  # raw fields into the user-facing value objects +Kobako::Capture+ and
+  # +Kobako::Usage+ — the same shape +Kobako::Sandbox+ exposes to the
+  # Host App.
+  class Snapshot
+    # Wrap the stdout capture pair (+stdout_bytes+, +stdout_truncated+)
+    # as a +Kobako::Capture+ value object. {docs/behavior.md
+    # B-04}[link:../../docs/behavior.md] — the byte content never carries
+    # a truncation sentinel; +#truncated?+ is the only way to observe
+    # that the cap was hit.
+    def stdout
+      Capture.new(bytes: stdout_bytes, truncated: stdout_truncated)
+    end
+
+    # Wrap the stderr capture pair as a +Kobako::Capture+ value object.
+    # Mirror of +#stdout+.
+    def stderr
+      Capture.new(bytes: stderr_bytes, truncated: stderr_truncated)
+    end
+
+    # Wrap the per-last-invocation usage pair (+wall_time+,
+    # +memory_peak+) as a +Kobako::Usage+ value object
+    # ({docs/behavior.md B-35}[link:../../docs/behavior.md]).
+    def usage
+      Usage.new(wall_time: wall_time, memory_peak: memory_peak)
+    end
+  end
+end

data/lib/kobako/snippet/binary.rb

@@ -3,23 +3,22 @@
 module Kobako
   module Snippet
     # Kobako::Snippet::Binary — value object representing a single
-    # +#preload(binary:)+ entry held by +Kobako::Snippet::Table+
+    # +#preload(binary:)+ entry held by +Kobako::Catalog::Snippets+
     # ({docs/behavior.md B-32}[link:../../../docs/behavior.md]).
     #
     # The +body+ is RITE bytecode (as emitted by +mrbc+) carried as an
     # +ASCII_8BIT+ String so msgpack-ruby encodes it as +bin+ family on
     # the wire ({docs/wire-codec.md Invocation channels}[link:../../../docs/wire-codec.md]).
     # The host treats the bytes as opaque — the snippet's canonical
-    # name, when present, lives in the bytecode's embedded
-    # +debug_info+ and is resolved by the guest at load time;
-    # structural validation
+    # name, when present, lives in the bytecode's embedded +debug_info+
+    # and is resolved by the guest at load time; structural validation
     # ({docs/behavior.md E-37 / E-38}[link:../../../docs/behavior.md])
     # is deferred to the first invocation's guest replay.
     #
     # The class is a +Data.define+ subclass — frozen and value-equal.
-    # Callers (chiefly +Table+) construct instances via keyword form
-    # +Binary.new(body: ...)+. Wire-form construction is the +Table+'s
-    # responsibility.
+    # Callers (chiefly +Catalog::Snippets+) construct instances via keyword
+    # form +Binary.new(body: ...)+. Wire-form construction is the
+    # registry's responsibility.
     class Binary < Data.define(:body)
       # The +kind+ field value carried by bytecode snippets in their
       # Frame 3 wire envelope entry

data/lib/kobako/snippet/source.rb

@@ -3,21 +3,21 @@
 module Kobako
   module Snippet
     # Kobako::Snippet::Source — value object representing a single
-    # +#preload(code:, name:)+ entry held by +Kobako::Snippet::Table+
+    # +#preload(code:, name:)+ entry held by +Kobako::Catalog::Snippets+
     # ({docs/behavior.md B-32}[link:../../../docs/behavior.md]).
     #
     # +name+ is the canonical +Symbol+ identity baked into the loaded
     # IREP's +debug_info+; backtrace frames originating in this snippet
     # surface as +(snippet:Name):line+. +body+ is the UTF-8 mruby source
-    # detached from the caller's reference at +Table#register+ time so
-    # later mutation of the original String cannot bleed through.
+    # detached from the caller's reference at +Catalog::Snippets#register+
+    # time so later mutation of the original String cannot bleed through.
     #
     # The class is a +Data.define+ subclass — frozen, value-equal, and
-    # carries no mutation API. Callers (chiefly +Table+) construct
-    # instances via keyword form +Source.new(name: ..., body: ...)+.
-    # Wire-form construction is the +Table+'s responsibility, mirroring
-    # +Kobako::RPC.encode_request+'s pattern of reading attributes off a
-    # carrier rather than asking the carrier to self-describe.
+    # carries no mutation API. Callers (chiefly +Catalog::Snippets+)
+    # construct instances via keyword form +Source.new(name: ..., body: ...)+.
+    # Wire-form construction is the registry's responsibility: as a leaf
+    # carrier this Source stays pure and +Catalog::Snippets#encode+ reads
+    # its attributes off the outside rather than asking it to self-encode.
     class Source < Data.define(:name, :body)
       # The +kind+ field value carried by source snippets in their Frame
       # 3 wire envelope entry

data/lib/kobako/snippet.rb

@@ -2,19 +2,17 @@
 
 require_relative "snippet/binary"
 require_relative "snippet/source"
-require_relative "snippet/table"
 
 module Kobako
-  # Kobako::Snippet — namespace for the per-Sandbox preloaded snippet
-  # registry and its entry value objects
+  # Kobako::Snippet — value-object family for preloaded snippet entries
+  # held by +Kobako::Catalog::Snippets+
   # ({docs/behavior.md B-32 / B-33}[link:../../docs/behavior.md]).
   #
-  # The +Table+ owns insertion-ordered storage and seal-coordination with
-  # the owning Sandbox; +Source+ is the value object representing a single
-  # +#preload(code:, name:)+ entry. Entry types live as siblings under
-  # this module rather than nested under +Table+ so they remain plain
-  # value objects with no implicit dependency on the registry that holds
-  # them.
+  # +Source+ represents a single +#preload(code:, name:)+ entry; +Binary+
+  # represents a single +#preload(binary:)+ entry. Both are plain value
+  # objects with no dependency on the +Catalog::Snippets+ registry that
+  # holds them — the registry reads their attributes externally when
+  # encoding the wire envelope.
   module Snippet
   end
 end

data/lib/kobako/transport/dispatcher.rb

@@ -0,0 +1,195 @@
+# frozen_string_literal: true
+
+require_relative "../codec"
+require_relative "request"
+require_relative "response"
+require_relative "yield"
+require_relative "yielder"
+
+module Kobako
+  # See lib/kobako/transport.rb for the umbrella module doc; this file
+  # owns the pure-function dispatcher that decodes guest-initiated
+  # Requests and produces encoded Responses.
+  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
+    # Catalog::Handles (Handle lookup), invokes the method, and returns
+    # a msgpack-encoded Response envelope.
+    #
+    # The module is stateless — all mutable state is threaded through
+    # arguments so Dispatcher has no instance variables and no side
+    # effects beyond mutating the Catalog::Handles via +alloc+ when a
+    # non-wire-representable return value must be wrapped
+    # ({docs/behavior.md B-14}[link:../../../docs/behavior.md]).
+    #
+    # Entry point:
+    #
+    #   Kobako::Transport::Dispatcher.dispatch(request_bytes, namespaces, handler, yield_to_guest)
+    #   # => msgpack-encoded Response bytes (never raises)
+    module Dispatcher
+      # Throw tag for the {Yielder}'s break unwind back to the
+      # dispatcher's +catch+ frame (B-25). +private_constant+ is a
+      # convention boundary — not a defence.
+      BREAK_THROW = :__kobako_break__
+      private_constant :BREAK_THROW
+
+      module_function
+
+      # 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
+      # ({docs/behavior.md E-12}[link:../../../docs/behavior.md]).
+      class UndefinedTargetError < StandardError; end
+
+      # Dispatch a single transport request and return the encoded
+      # Response bytes ({docs/behavior.md B-12}[link:../../../docs/behavior.md]).
+      # Invoked from the +Runtime#on_dispatch+ Proc that
+      # +Kobako::Sandbox#initialize+ installs on the ext side; +namespaces+,
+      # +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+
+      # or +Runtime+. +yield_to_guest+ is a +String → String+ callable
+      # (typically +Runtime#yield_to_active_invocation+ bound as a lambda)
+      # used only when the Request carries +block_given: true+. Always
+      # 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)
+        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)
+      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)
+        args = request.args.map { |v| resolve_arg(v, handler) }
+        kwargs = request.kwargs.transform_values { |v| resolve_arg(v, handler) }
+        [args, kwargs]
+      end
+
+      # 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). Three
+      # error buckets ({docs/behavior.md B-12}[link:../../../docs/behavior.md]):
+      # +Kobako::Codec::Error+ → type="runtime" (malformed request);
+      # +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",
+                                                    "Sandbox received a malformed request: #{error.message}")
+        when UndefinedTargetError then encode_error("undefined", error.message)
+        when ArgumentError        then encode_error("argument", error.message)
+        else                           encode_error("runtime", "#{error.class}: #{error.message}")
+        end
+      end
+
+      # Dispatch +method+ on +target+. +kwargs+ is already Symbol-keyed
+      # (the +Request+ invariant pins it). The empty-kwargs branch omits
+      # the +**+ splat so Ruby 3.x's strict kwargs separation does not
+      # reject calls to no-kwarg methods when the wire carries the
+      # uniform empty-map shape.
+      #
+      # +yielder+ is the host-side {Yielder} materialised when the guest
+      # call site supplied a block ({docs/behavior.md
+      # B-23}[link:../../../docs/behavior.md]); its {Yielder#to_proc}
+      # rides the +&block+ slot. +&nil+ is a no-op block argument in Ruby,
+      # so the same call site handles both cases without an explicit
+      # conditional.
+      def invoke(target, method, args, kwargs, yielder = nil)
+        block = yielder&.to_proc
+        if kwargs.empty?
+          target.public_send(method.to_sym, *args, &block)
+        else
+          target.public_send(method.to_sym, *args, **kwargs, &block)
+        end
+      end
+
+      # {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
+      # transport call's Handle wrap (B-14). Resolve it back to the Ruby object before
+      # the dispatch reaches +public_send+.
+      def resolve_arg(value, handler)
+        case value
+        when Kobako::Handle
+          require_live_object!(value.id, handler)
+        else
+          value
+        end
+      end
+
+      # Resolve a Request target to the Ruby object the registry (or
+      # Catalog::Handles) holds. String targets go through the registry;
+      # Handle targets (ext 0x01) go through the Catalog::Handles.
+      #
+      # 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)
+        case target
+        when String
+          resolve_path(target, namespaces)
+        when Kobako::Handle
+          resolve_handle(target, handler)
+        end
+      end
+
+      def resolve_path(path, namespaces)
+        namespaces.lookup(path)
+      rescue KeyError => e
+        raise UndefinedTargetError, e.message
+      end
+
+      def resolve_handle(handle, handler)
+        require_live_object!(handle.id, handler)
+      end
+
+      # Resolve +id+ through the Catalog::Handles. An unknown id (E-13)
+      # surfaces as UndefinedTargetError.
+      def require_live_object!(id, handler)
+        handler.fetch(id)
+      rescue Kobako::SandboxError => e
+        raise UndefinedTargetError, e.message
+      end
+
+      # Encode +value+ as a +Response.ok+ envelope. When the value is not
+      # wire-representable per {docs/behavior.md B-13}[link:../../../docs/behavior.md]'s type
+      # mapping, the +UnsupportedType+ rescue routes it through the
+      # Catalog::Handles 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, handler)
+        response = Kobako::Transport::Response.ok(value)
+        response.encode
+      rescue Kobako::Codec::UnsupportedType
+        encode_ok(wrap_as_handle(value, handler), handler)
+      end
+
+      # Allocate +value+ in the Sandbox's Catalog::Handles 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, handler)
+        handler.alloc(value)
+      end
+
+      def encode_error(type, message)
+        fault = Kobako::Fault.new(type: type, message: message)
+        response = Kobako::Transport::Response.error(fault)
+        response.encode
+      end
+    end
+  end
+end