kobako 0.26.0-aarch64-linux → 0.28.0-aarch64-linux

data/lib/kobako/codec/handle_walk.rb

@@ -5,26 +5,11 @@ require_relative "../errors"
 
 module Kobako
   module Codec
-    # Substitutes Capability Handles into and out of a Ruby value tree at
-    # the host↔guest boundary. #deep_wrap allocates a +Kobako::Handle+ for
-    # each non-wire-representable leaf on the host→guest +#run+ argument
-    # path; #deep_restore resolves each wire-decoded Handle back to its
-    # host object on every guest→host value path. #representable? is the
-    # by-value codec-type predicate that decides which leaves #deep_wrap
-    # must wrap: the closed 11-entry wire type set
-    # ({docs/wire/payload-msgpack.md}[link:../../../docs/wire/payload-msgpack.md] § Type
-    # Mapping).
-    #
-    # All helpers are pure except #deep_wrap, whose only side effect is
-    # allocating new Handle ids into the supplied table.
-    module HandleWalk
-      module_function
-
+    module HandleWalk # :nodoc:
       # Inclusive Integer range the msgpack gem encodes without raising
       # +RangeError+ at encode time — signed +int 64+ minimum through
-      # unsigned +uint 64+ maximum
-      # ({docs/wire/payload-msgpack.md}[link:../../../docs/wire/payload-msgpack.md] § Type
-      # Mapping #3, the +fixint+ / +int 8..64+ / +uint 8..64+ union).
+      # unsigned +uint 64+ maximum (docs/wire/payload-msgpack.md § Integer
+      # Range).
       # 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
@@ -32,141 +17,91 @@ module Kobako
       # represents a different concept entirely.
       MSGPACK_INT_RANGE = (-(2**63)..((2**64) - 1))
 
-      # Codec-type predicate
-      # ({docs/wire/payload-msgpack.md}[link:../../../docs/wire/payload-msgpack.md] § Type
-      # Mapping). Returns +true+ when +value+ belongs to the closed
-      # 11-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 UnsupportedTypeError.
-      #
-      # The optional +depth+ bounds the recursive descent at the wire's
-      # structural nesting cap so a self-referential container — reachable
-      # as a cyclic Hash key on the +#run+ argument path — reads as
-      # non-representable rather than looping, letting #deep_wrap_hash
-      # refuse it instead of overflowing this walk.
-      def representable?(value, depth = 0)
+      # Whether +value+ falls in the codec's type set
+      # (docs/wire/payload-msgpack.md § Type Mapping). The +depth+ bound
+      # makes a self-referential container —
+      # reachable as a cyclic Hash key on the +#run+ argument path — read as
+      # non-representable rather than looping.
+      def self.representable?(value, depth = 0)
         return false if depth > MAX_NESTING_DEPTH
 
         primitive_type?(value) || container_representable?(value, depth)
       end
 
-      # Deep-walk Array / Hash containers in +value+ and replace every
-      # leaf that fails #representable? with a +Kobako::Handle+
-      # allocated from +handler+. The
-      # 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. Only Hash *values*
-      # are wrapped: a Hash *key* must already be wire-representable, since a
-      # key is not auto-wrapped the way a value is — a non-representable key
-      # raises +Kobako::SandboxError+ rather than crossing as an opaque token
-      # the guest→host restore walk could not round-trip.
-      #
-      # +value+ may be any Ruby value; +handler+ must respond to
-      # +#alloc(object) -> Kobako::Handle+ (a host-side
-      # +Kobako::Catalog::Handles+). Returns a structurally equivalent value
-      # whose leaves are either representable or +Kobako::Handle+
-      # tokens.
-      #
-      # Recursive calls spell the +HandleWalk.+ receiver so the dispatch
-      # stays valid even when a block is captured and run under a
-      # different +self+ (+module_function+ privatizes the instance copies).
-      def deep_wrap(value, handler, depth = 0)
+      # Only Hash values are wrapped: a non-representable key raises rather
+      # than crossing as a token the guest→host restore walk could not
+      # round-trip.
+      def self.deep_wrap(value, handles, depth = 0)
         guard_nesting!(depth)
         case value
-        when ::Array then value.map { |element| HandleWalk.deep_wrap(element, handler, depth + 1) }
-        when ::Hash  then HandleWalk.deep_wrap_hash(value, handler, depth)
+        when ::Array then value.map { |element| deep_wrap(element, handles, depth + 1) }
+        when ::Hash  then deep_wrap_hash(value, handles, depth)
         else
-          representable?(value) ? value : handler.alloc(value)
-        end
-      end
-
-      # Refuse a wrap walk that has descended past the wire's structural
-      # nesting bound — a reference cycle necessarily trips it — so a +#run+
-      # argument fails as a clean +Kobako::SandboxError+ rather than an
-      # unbounded host recursion.
-      def guard_nesting!(depth)
-        return unless depth > MAX_NESTING_DEPTH
-
-        raise Kobako::SandboxError,
-              "a #run argument nests deeper than #{MAX_NESTING_DEPTH} levels within the Run payload and " \
-              "cannot cross the sandbox boundary (possible reference cycle)"
-      end
-
-      # Wrap a Hash on the host→guest argument path: each value's
-      # non-representable leaves become Handles, while each key must be
-      # wire-representable as-is. A stateful object may cross the boundary as
-      # a Hash value but not as a key — the one deliberate asymmetry with the
-      # guest→host restore walk, which resolves Handle keys the guest built.
-      def deep_wrap_hash(hash, handler, depth)
-        wrapped = {} # : Hash[untyped, untyped]
-        hash.each do |key, val|
-          unless HandleWalk.representable?(key, depth + 1)
-            raise Kobako::SandboxError,
-                  "a Hash passed to #run has a key that cannot cross the sandbox boundary " \
-                  "(#{key.class}); only wire-representable values may be Hash keys"
-          end
-          wrapped[key] = HandleWalk.deep_wrap(val, handler, depth + 1)
+          representable?(value) ? value : handles.alloc(value)
         end
-        wrapped
       end
 
-      # Deep-walk Array / Hash containers in +value+ and replace every
-      # +Kobako::Handle+ leaf with the host-side object +handler+ resolves
-      # it to. The symmetric inverse of #deep_wrap: that walk allocates objects
-      # into Handles on the host→guest argument path; this walk resolves
-      # Handles back to their objects wherever a guest→host payload carries
-      # one — an invocation result, a yield-block result, or a dispatch
-      # argument. The walk descends through Array elements and Hash keys and
-      # values one structural level at a time; any non-Handle leaf passes
-      # through unchanged.
-      #
-      # +value+ is a decoded Ruby value (a Handle here is a wire-decoded
-      # +Kobako::Handle+, never a guest-forged one); +handler+ must
-      # respond to +#fetch(id) -> object+ (a host-side
-      # +Kobako::Catalog::Handles+). +handler.fetch+ raises
-      # +Kobako::SandboxError+ for an id with no live binding, the
-      # corrupted-runtime fallback.
-      def deep_restore(value, handler)
+      # The inverse of #deep_wrap. A Handle here was decoded off the wire,
+      # never forged by the guest, and +handles.fetch+ refuses an id with no
+      # live binding.
+      def self.deep_restore(value, handles)
         case value
-        when ::Array then value.map { |element| HandleWalk.deep_restore(element, handler) }
+        when ::Array then value.map { |element| deep_restore(element, handles) }
         when ::Hash
           # Rebuilt with each key restored: two distinct Handle keys that
           # resolve to equal host objects collapse to the later pair, as in
           # any Ruby Hash. The guest authored this payload, so that collapse
           # is its own concern, not a fidelity guarantee the host owes it.
-          value.to_h { |key, val| [HandleWalk.deep_restore(key, handler), HandleWalk.deep_restore(val, handler)] }
-        when Kobako::Handle then handler.fetch(value.id)
+          value.to_h { |key, val| [deep_restore(key, handles), deep_restore(val, handles)] }
+        when Kobako::Handle then handles.fetch(value.id)
         else value
         end
       end
 
-      # The non-container branch of #representable?: returns +true+ for
-      # 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)
-        else false
+      class << self
+        private
+
+        # A reference cycle necessarily trips the nesting bound, so a +#run+
+        # argument fails as a clean +Kobako::SandboxError+ rather than an
+        # unbounded host recursion.
+        def guard_nesting!(depth)
+          return unless depth > MAX_NESTING_DEPTH
+
+          raise Kobako::SandboxError,
+                "a #run argument nests deeper than #{MAX_NESTING_DEPTH} levels within the Run payload and " \
+                "cannot cross the sandbox boundary (possible reference cycle)"
         end
-      end
 
-      # The container branch of #representable?: recurses into Array
-      # elements and Hash key+value pairs through the public
-      # #representable?. Not part of the public surface; reach for
-      # #representable? instead.
-      def container_representable?(value, depth)
-        case value
-        when ::Array then value.all? { |element| HandleWalk.representable?(element, depth + 1) }
-        when ::Hash  then value.all? { |pair| pair.all? { |member| HandleWalk.representable?(member, depth + 1) } }
-        else false
+        # A stateful object may cross the boundary as a Hash value but not as
+        # a key — the one deliberate asymmetry with the guest→host restore
+        # walk, which resolves Handle keys the guest built.
+        def deep_wrap_hash(hash, handles, depth)
+          wrapped = {} # : Hash[untyped, untyped]
+          hash.each do |key, val|
+            unless representable?(key, depth + 1)
+              raise Kobako::SandboxError,
+                    "a Hash passed to #run has a key that cannot cross the sandbox boundary " \
+                    "(#{key.class}); only wire-representable values may be Hash keys"
+            end
+            wrapped[key] = deep_wrap(val, handles, depth + 1)
+          end
+          wrapped
+        end
+
+        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)
+          else false
+          end
+        end
+
+        def container_representable?(value, depth)
+          case value
+          when ::Array then value.all? { |element| representable?(element, depth + 1) }
+          when ::Hash  then value.all? { |pair| pair.all? { |member| representable?(member, depth + 1) } }
+          else false
+          end
         end
       end
     end

data/lib/kobako/codec/nesting.rb

@@ -4,14 +4,9 @@ require_relative "error"
 
 module Kobako
   module Codec
-    # The structural nesting bound
-    # ({docs/wire/payload-msgpack.md}[link:../../../docs/wire/payload-msgpack.md]
-    # § Structural Nesting Depth), checked before a value reaches the
-    # packer. The packer takes no depth limit and walks a list or map in
-    # frames that carry no stack guard, so a value it cannot finish — a
-    # reference cycle necessarily is one — must be refused before it is
-    # handed over.
-    module Nesting
+    # Refuses a value nested past the wire's bound before the packer sees it,
+    # since the packer walks without a stack guard and a cycle never ends.
+    module Nesting # :nodoc:
       # Raise InvalidTypeError when +value+ nests past MAX_NESTING_DEPTH; a
       # value nested exactly to the bound passes.
       def self.assert_within_bound!(value, depth = 0)

data/lib/kobako/codec/state.rb

@@ -2,11 +2,9 @@
 
 module Kobako
   module Codec
-    # Codec-internal, per-thread state of the operation in flight: whether
-    # a Capability Handle crossed the current decode. Thread scoping is
-    # what makes plain instance variables sound — host codec calls run
-    # synchronously on their owning thread.
-    class State
+    # Whether a Capability Handle crossed the decode in flight, kept per
+    # thread so plain instance variables stay sound.
+    class State # :nodoc:
       # Thread-local slot holding the calling thread's State.
       STATE_KEY = :__kobako_codec_state__
       private_constant :STATE_KEY
@@ -22,12 +20,8 @@ module Kobako
         @carried_handle = false
       end
 
-      # Bracket a decode and return the block's result together with
-      # whether the decoded tree carried an ext 0x01 Capability Handle.
       # ExtTypes#unpack_handle is the sole chokepoint every Handle passes
-      # through, so one decode pass records the whole tree and a caller
-      # can skip an all-identity Handle-resolution walk when none was
-      # present.
+      # through, so one decode pass records the whole tree.
       def track_handles
         @carried_handle = false
         result = yield

data/lib/kobako/codec/utils.rb

@@ -4,45 +4,17 @@ require_relative "error"
 
 module Kobako
   module Codec
-    # Byte-boundary helpers shared by the host-side encoder and decoder.
-    # Two concerns live here:
-    #
-    #   - 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 ExtTypes
-    #     when validating the +ext 0x00+ Symbol payload.
-    #   - +ArgumentError+ translation at the codec boundary
-    #     (#with_boundary) so the public taxonomy stays
-    #     Kobako::Codec::Error.
-    #
-    # Both helpers are pure — they only inspect inputs, never mutate them.
-    # The host↔guest Handle substitution walk lives in HandleWalk.
-    module Utils
-      module_function
-
-      # Raise InvalidEncodingError unless +string+'s bytes are valid under
-      # its current encoding tag. +label+ is the caller-supplied prefix
-      # for the error message (e.g. +"str payload"+, +"Symbol payload"+).
-      def assert_utf8!(string, label)
+    module Utils # :nodoc:
+      def self.assert_utf8!(string, label)
         return if string.valid_encoding?
 
         raise InvalidEncodingError, "#{label} is not valid UTF-8"
       end
 
-      # Run +block+ at the codec boundary: a value object raises
-      # +ArgumentError+ when an invariant is violated at construction, and
-      # this helper surfaces that as InvalidTypeError so the public taxonomy
-      # stays Kobako::Codec::Error and never leaks +ArgumentError+ from
-      # the Ruby standard library.
-      #
-      # Reach for this only where a value object is constructed outside a
-      # Decoder.decode block, whose rescue already performs the same
-      # mapping (worked example: ExtTypes#unpack_handle building
-      # +Handle.restore+ from a raw fixext payload). Do not use it for
-      # general-purpose validation outside the codec boundary —
-      # host-layer +ArgumentError+ values should propagate unchanged.
-      def with_boundary
+      # Only for a value object built outside a Decoder.decode block, whose
+      # rescue already maps the same way; a host-layer +ArgumentError+
+      # elsewhere should propagate unchanged.
+      def self.with_boundary
         yield
       rescue ::ArgumentError => e
         raise InvalidTypeError, e.message

data/lib/kobako/codec.rb

@@ -10,24 +10,7 @@ require_relative "codec/encoder"
 require_relative "codec/decoder"
 
 module Kobako
-  # Host-side MessagePack codec for the kobako wire contract — the
-  # byte-level layer ({docs/wire-codec.md}[link:../../docs/wire-codec.md]).
-  # This is the payload codec: the core envelope is framed natively, so
-  # what reaches here is one codec document — an invocation's arguments
-  # (+Kobako::Payload::Arguments+), a dispatch or yield value, or an
-  # invocation's value and a Panic's diagnostics
-  # (+Kobako::Outcome+). The ext-type leaves this layer
-  # carries — +Kobako::Handle+ (0x01) — lives at the kobako root so the
-  # codec can register it without depending upward on Transport.
-  #
-  # Backed by the official +msgpack+ gem: ExtTypes registers the two
-  # kobako-specific ext types (0x00 Symbol, 0x01 Capability Handle) on
-  # one process-wide +MessagePack::Factory+,
-  # and Encoder / Decoder are thin wrappers over it. The Rust side
-  # mirrors this layer as the +codec+ module in the +kobako-codec+ crate;
-  # the ext-code constants live as module-private values on ExtTypes
-  # alongside +codec::EXT_SYMBOL+ / +codec::EXT_HANDLE+ on that side.
-  module Codec
+  module Codec # :nodoc:
     # The maximum structural nesting depth the wire represents (the
     # MessagePack ecosystem's bound), shared with the guest +kobako_codec+
     # so both sides cap identically. The host refuses a value nesting past
@@ -35,10 +18,8 @@ module Kobako
     # packer.
     MAX_NESTING_DEPTH = 128
 
-    # Bracket a decode and return the block's result together with whether
-    # the decoded tree carried an ext 0x01 Capability Handle — the signal a
-    # dispatch path uses to skip an all-identity Handle-resolution walk.
-    # The tracking state is codec-internal; this is its only readout.
+    # Answers the block's result with whether the decode carried a
+    # Capability Handle, so a caller can skip an all-identity restore walk.
     def self.track_handles(&block)
       State.current.track_handles(&block)
     end

data/lib/kobako/constant_name.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Kobako
+  # A bind-path segment, a snippet name and a #run entrypoint all take the
+  # constant-name form, so they are refused alike. The guest interns each
+  # one, and mruby holds a symbol of at most 65534 bytes.
+  CONSTANT_NAME = /\A[A-Z]\w{0,65533}\z/ # :nodoc:
+end

data/lib/kobako/context.rb

@@ -11,41 +11,30 @@ require_relative "transport"
 require_relative "catalog"
 
 module Kobako
-  # Kobako::Context — the per-invocation driver behind a single +Sandbox#eval+
-  # / +#run+. Each Context owns a fresh +Catalog::Handles+ table and drives one
-  # guest invocation: it builds the dispatch handler, runs the guest, records
-  # the run's captures and usage, and decodes the outcome. One Context per
-  # invocation owns all per-invocation state, so the reusable +Sandbox+ holds
-  # none and overlapping evals never touch each other's state.
+  # One invocation, as the block given to Sandbox#eval or Sandbox#run sees it.
+  # The block runs before the guest does, so it can choose the objects this
+  # invocation alone reaches:
+  #
+  #   sandbox.eval("Req::Current.user_id") { |ctx| ctx.bind("Req::Current", request) }
   class Context
-    # Build a Context over the Sandbox-owned config — the +Runtime+, the
-    # sealed +Catalog::Services+ / +Catalog::Snippets+ registries, and the
-    # +Catalog::Extensions+ whose callable backends this Context resolves for
-    # its own run. The +Catalog::Handles+ table is this invocation's own, so
-    # guest→host dispatch and host→guest auto-wrap share one allocator scoped
-    # to the run; the resolved provider map is likewise per-invocation, so
-    # concurrent invocations never share mutable state.
-    def initialize(runtime:, services:, snippets:, extensions:)
+    def initialize(runtime:, services:, snippets:, flags:, extensions:) # :nodoc:
       @runtime = runtime
       @services = services
       @snippets = snippets
+      @flags = flags
       @extensions = extensions
       @resolved = {} # : Hash[String, Transport::Exposure]
       @overrides = {} # : Hash[String, Transport::Exposure]
-      @spent = false
-      @handler = Catalog::Handles.new
+      @handles = Catalog::Handles.new
       @stdout_capture = @stderr_capture = Capture::EMPTY
       @usage = Usage::EMPTY
     end
 
-    # Override the object bound at an already-declared +path+ for this
-    # invocation only — the per-eval hook the +#eval+ / +#run+ block uses to
-    # fill a fillable or shadow any static / per-invocation binding. +path+
-    # must name a declared (Frame 1) binding; overriding an undeclared path
-    # raises +ArgumentError+ so the Frame 1 key set stays fixed. Valid only
-    # while the block runs — the Context is spent once the block returns, so a
-    # captured +ctx+ used afterward raises +ArgumentError+ too, putting both
-    # misuses on one rescuable channel. Returns +self+.
+    # Use +object+ for the Service at +path+ during this invocation only,
+    # filling a fillable Service or shadowing a bound one. Returns +self+.
+    #
+    # Raises ArgumentError when +path+ was never bound on the Sandbox, or when
+    # called after the block has returned.
     def bind(path, object)
       raise ArgumentError, "Kobako::Context is spent; ctx.bind is only valid inside the #eval / #run block" if @spent
 
@@ -56,16 +45,9 @@ module Kobako
       self
     end
 
-    # Resolve a Service +path+ to the Exposure backing it this invocation,
-    # layering the per-eval +ctx.bind+ overrides over this Context's
-    # per-invocation provider results over the Sandbox's static base bindings.
-    # An unbound path raises +KeyError+; a fillable left unfilled resolves to
-    # +Kobako::Unresolved+ and is reported the same way, so an unresolved
-    # capability fails closed as an undefined target rather than dispatching to
-    # the sentinel. The Dispatcher maps either +KeyError+ to an
-    # undefined-target wire fault. Internal — the per-invocation dispatch
-    # handler is the sole caller.
-    def lookup(path)
+    # A fillable left unfilled raises like an unbound path, so the guest's
+    # call fails closed instead of reaching the sentinel.
+    def lookup(path) # :nodoc:
       key = path.to_s
       exposure = @overrides.fetch(key) { @resolved.fetch(key) { @services.lookup(path) } }
       raise KeyError, "service #{path} is declared but unresolved this invocation" if Unresolved.equal?(exposure.object)
@@ -73,136 +55,93 @@ module Kobako
       exposure
     end
 
-    # Execute a guest mruby source string in a fresh +mrb_state+ and return the
-    # decoded last expression. A given +block+ runs first, receiving this
-    # Context to collect +ctx.bind+ overrides before the guest drives.
-    def eval(code, &block)
+    def eval(code, &block) # :nodoc:
       collect_overrides(&block) if block
       invoke!(:eval) do
-        @runtime.eval(dispatch_handler, @services.paths, code.b, @snippets.entries)
+        @runtime.eval(dispatch_handler, @services.paths, @snippets.entries, @flags.entries, code.b)
       end
     end
 
-    # Dispatch a +Transport::Run+ into a preloaded entrypoint and return the
-    # decoded result. A given +block+ runs first, receiving this Context to
-    # collect +ctx.bind+ overrides before the guest drives.
-    def run(request, &block)
+    def run(request, &block) # :nodoc:
       collect_overrides(&block) if block
       invoke!(:run, entrypoint: request.entrypoint) do
-        @runtime.run(dispatch_handler, @services.paths, @snippets.entries,
-                     request.entrypoint.to_s, request.payload(@handler))
+        @runtime.run(dispatch_handler, @services.paths, @snippets.entries, @flags.entries,
+                     request.entrypoint.to_s, request.payload(@handles))
       end
     end
 
     private
 
-    # Run the per-eval override +block+, handing it this Context so it can call
-    # +ctx.bind+, then spend the Context so a captured +ctx+ used after the
-    # block raises. A block that raises propagates before the guest drives, so
-    # the guest never runs and no Execution is produced.
+    # The Context is spent once the block returns, so a captured +ctx+ used
+    # later raises. A block that raises propagates before the guest drives,
+    # so the guest never runs and no Execution is produced.
     def collect_overrides
       yield self
     ensure
       @spent = true
     end
 
-    # Build this invocation's guest→host dispatch handler — a +Proc+ routing
-    # each guest→host call through the stateless +Transport::Dispatcher+,
-    # capturing this Context as the path resolver (its +#lookup+ layers the
-    # per-invocation providers over the static bindings) plus +@handler+. Handed to
-    # +Runtime#eval+ / +#run+ as a call argument, so the Runtime holds no
-    # dispatch state and the +Proc+ stays GC-rooted as a live argument for the
-    # synchronous call. The ext hands the +Proc+ a per-dispatch +guest_yielder+
-    # — a +String → String+ callable that re-enters the in-flight guest to run
-    # a yielded block — which the +Dispatcher+ forwards to the
-    # +Transport::Yielder+ it builds for the call.
+    # Handed to the Runtime as a call argument, so the Runtime holds no
+    # dispatch state and the Proc stays GC-rooted for the synchronous call.
     def dispatch_handler
       lambda do |target, method_name, block_given, payload, guest_yielder|
         call = Transport::Call.new(target: target, method_name: method_name,
                                    block_given: block_given, payload: payload)
-        Transport::Dispatcher.dispatch(call, self, @handler, guest_yielder)
+        Transport::Dispatcher.dispatch(call, self, @handles, guest_yielder)
       end
     end
 
-    # Record this invocation's usage and both output captures from the ext
-    # +Snapshot+. Every Snapshot carries them — value return or trap alike — so
-    # +#usage+ / +#stdout+ / +#stderr+ stay readable after a rescued trap.
+    # Every Snapshot carries usage and captures, trap or not, so they stay
+    # readable after a rescued trap.
     def populate_observability!(snapshot)
       @usage = Usage.new(wall_time: snapshot.wall_time, memory_peak: snapshot.memory_peak)
       @stdout_capture = Capture.new(bytes: snapshot.stdout, truncated: snapshot.stdout_truncated?)
       @stderr_capture = Capture.new(bytes: snapshot.stderr, truncated: snapshot.stderr_truncated?)
     end
 
-    # Pick the +TrapError+ subclass to re-raise based on +err+'s actual class.
-    # Cap-trap subclasses (+TimeoutError+ / +MemoryLimitError+) preserve their
-    # named identity; everything else collapses to the base +Kobako::TrapError+,
-    # so #invoke! can add the verb prefix without erasing the named subclass.
-    def trap_class_for(err)
-      case err
-      when TimeoutError     then TimeoutError
-      when MemoryLimitError then MemoryLimitError
-      else TrapError
-      end
-    end
-
-    # Build the +TrapError+-family exception for a trapped +Snapshot+ from its
-    # neutral trap kind, tagged with the verb — the cap subclasses
-    # (+TimeoutError+ / +MemoryLimitError+) keep their identity, every other
-    # engine fault is the base +TrapError+.
-    def trap_error_for(snapshot, verb)
-      klass = case snapshot.trap_kind
-              when :timeout      then TimeoutError
-              when :memory_limit then MemoryLimitError
-              else TrapError
-              end
-      klass.new("Sandbox##{verb} failed: #{snapshot.trap_message}")
+    # Every TrapError leaving an invocation names the verb that ran it; the
+    # cap subclasses keep their identity through the rebuild.
+    def with_verb(err, verb)
+      err.class.new("Sandbox##{verb} failed: #{err.message}")
     end
 
-    # Freeze this run's observables plus +value+ (+nil+ on a failed run) into
-    # the read-only +Execution+ the caller receives or the error carries.
-    # +failed+ records the two apart so a +nil+ +value+ from a successful run
-    # stays distinct from a failed one.
+    # +failed+ keeps a +nil+ value from a successful run apart from a failed
+    # run.
     def build_execution(value, failed:)
       Execution.new(value: value, usage: @usage, stdout: @stdout_capture, stderr: @stderr_capture, failed: failed)
     end
 
-    # Settle a completed run's outcome into its +Execution+. A Capability
-    # Handle in the result is restored to its host object first. The settle
-    # sits in the rescue so a wire-violation trap or a Panic both attach this
-    # run's Execution, just like a guest-call trap does. +entrypoint+ is the
-    # name +#run+ asked for, which the host knows and the wire never carries,
-    # so an unresolved one names itself on the error it raises.
+    # The settle sits in the rescue so a wire-violation trap or a Panic both
+    # attach this run's Execution, just like a guest-call trap does.
+    # +entrypoint+ is known to the host and never carried by the wire, so an
+    # unresolved one names itself on the error it raises.
     def settle_outcome(snapshot, verb, entrypoint)
-      kind, payload, panic = snapshot.outcome
-      value, carried = Codec.track_handles { Outcome.reify(kind, payload, panic, entrypoint: entrypoint) }
-      value = Codec::HandleWalk.deep_restore(value, @handler) if carried
+      payload, panic = snapshot.outcome
+      value, carried = Codec.track_handles { Outcome.reify(payload, panic, entrypoint: entrypoint) }
+      value = Codec::HandleWalk.deep_restore(value, @handles) if carried
       build_execution(value, failed: false)
     rescue Kobako::TrapError => e
-      raise trap_class_for(e).new("Sandbox##{verb} failed: #{e.message}").with_execution(build_execution(nil,
-                                                                                                         failed: true))
+      raise with_verb(e, verb).with_execution(build_execution(nil, failed: true))
     rescue Kobako::SandboxError, Kobako::ServiceError => e
       raise e.with_execution(build_execution(nil, failed: true))
     end
 
-    # Drive one invocation and settle it into a frozen +Execution+. +verb+
-    # tags the TrapError message so the failing export is identifiable. This
-    # invocation's callable Extension backends are resolved first — before the
-    # guest runs — so a provider that raises propagates unwrapped and leaves
-    # the guest unrun. Usage and captures are recorded before the trap check,
-    # so a trapped Snapshot's error carries them just like a completed run's
-    # return value. A could-not-start fault ran no invocation at all, so it
-    # carries no Execution and gains only the verb prefix.
+    # Extension backends are resolved before the guest runs, so a provider
+    # that raises propagates unwrapped and leaves the guest unrun. A
+    # could-not-start fault ran no invocation at all, so it carries no
+    # Execution and gains only the verb prefix.
     def invoke!(verb, entrypoint: nil)
       @resolved = @extensions.resolve.transform_values { |object| Transport::Exposure.of(object) }
       begin
         snapshot = yield
       rescue Kobako::TrapError => e
-        raise trap_class_for(e), "Sandbox##{verb} failed: #{e.message}"
+        raise with_verb(e, verb)
       end
       populate_observability!(snapshot)
-      return settle_outcome(snapshot, verb, entrypoint) unless snapshot.trapped?
+      trap = snapshot.trap_error
+      return settle_outcome(snapshot, verb, entrypoint) unless trap
 
-      raise trap_error_for(snapshot, verb).with_execution(build_execution(nil, failed: true))
+      raise with_verb(trap, verb).with_execution(build_execution(nil, failed: true))
     end
   end
 end