kobako 0.23.0 → 0.26.0

data/lib/kobako/codec/encoder.rb

@@ -31,23 +31,14 @@ module Kobako
       # same error: an integer outside i64..u64 (+RangeError+) and any
       # packer-internal +NoMethodError+.
       #
-      # A value that nests without bound — a reference cycle necessarily
-      # does — exhausts the packer's own recursion instead, which Ruby
-      # reports outside +StandardError+. Mapping it keeps an unwritable
-      # value a wire violation the dispatch boundary can answer, rather than
-      # one that escapes every caller's rescue and traps the invocation.
-      #
-      # The refusal is spent once per thread: a thread that has absorbed one
-      # such overflow aborts on the next instead of raising, and a Hash cycle
-      # never reaches Ruby at all — the packer walks a Hash through C frames
-      # that carry no stack guard. Bounding the walk before the packer is
-      # handed the value is what would make the refusal repeatable.
+      # The caller bounds +value+'s nesting first (Nesting): the packer takes
+      # no depth limit and walks a list or map in frames that carry no stack
+      # guard, so a value nesting without end — a reference cycle necessarily
+      # does — exhausts the machine stack instead of raising.
       def self.encode(value)
         FACTORY.dump(value)
       rescue ::RangeError, ::NoMethodError => e
         raise UnsupportedTypeError, e.message
-      rescue ::SystemStackError
-        raise InvalidTypeError, "value nests deeper than this host can write (a reference cycle necessarily does)"
       end
     end
   end

data/lib/kobako/codec/handle_walk.rb

@@ -95,7 +95,7 @@ module Kobako
         return unless depth > MAX_NESTING_DEPTH
 
         raise Kobako::SandboxError,
-              "a #run argument nests deeper than #{MAX_NESTING_DEPTH} levels and " \
+              "a #run argument nests deeper than #{MAX_NESTING_DEPTH} levels within the Run payload and " \
               "cannot cross the sandbox boundary (possible reference cycle)"
       end
 

data/lib/kobako/codec/nesting.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+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
+      # 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)
+        case value
+        when ::Array then assert_members_within_bound!(value, depth)
+        when ::Hash
+          assert_members_within_bound!(value.keys, depth)
+          assert_members_within_bound!(value.values, depth)
+        end
+      end
+
+      # Measure the members of one container at +depth+, each sitting one
+      # level deeper. A member is matched by class rather than asked about
+      # itself — it may be a BasicObject — and only one that could be a
+      # container is walked into.
+      def self.assert_members_within_bound!(members, depth)
+        return if members.empty?
+        if depth >= MAX_NESTING_DEPTH
+          raise InvalidTypeError,
+                "value nests deeper than #{MAX_NESTING_DEPTH} levels (a reference cycle necessarily does)"
+        end
+        return unless members.any?(::Enumerable)
+
+        members.grep(::Enumerable) { |member| assert_within_bound!(member, depth + 1) }
+      end
+      private_class_method :assert_members_within_bound!
+    end
+  end
+end

data/lib/kobako/codec.rb

@@ -3,6 +3,7 @@
 require_relative "codec/error"
 require_relative "codec/utils"
 require_relative "codec/handle_walk"
+require_relative "codec/nesting"
 require_relative "codec/state"
 require_relative "codec/ext_types"
 require_relative "codec/encoder"
@@ -29,8 +30,9 @@ module Kobako
   module Codec
     # 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→guest wrap walk refuses a
-    # +#run+ argument nesting past it — a reference cycle necessarily does.
+    # so both sides cap identically. The host refuses a value nesting past
+    # it — a reference cycle necessarily does — before handing it to the
+    # packer.
     MAX_NESTING_DEPTH = 128
 
     # Bracket a decode and return the block's result together with whether

data/lib/kobako/context.rb

@@ -30,8 +30,8 @@ module Kobako
       @services = services
       @snippets = snippets
       @extensions = extensions
-      @resolved = {} # : Hash[String, untyped]
-      @overrides = {} # : Hash[String, untyped]
+      @resolved = {} # : Hash[String, Transport::Exposure]
+      @overrides = {} # : Hash[String, Transport::Exposure]
       @spent = false
       @handler = Catalog::Handles.new
       @stdout_capture = @stderr_capture = Capture::EMPTY
@@ -52,11 +52,11 @@ module Kobako
       key = path.to_s
       raise ArgumentError, "cannot override undeclared path #{key.inspect}" unless @services.bound?(key)
 
-      @overrides[key] = object
+      @overrides[key] = Transport::Exposure.of(object)
       self
     end
 
-    # Resolve a Service +path+ to the object backing it this invocation,
+    # 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
@@ -67,10 +67,10 @@ module Kobako
     # handler is the sole caller.
     def lookup(path)
       key = path.to_s
-      object = @overrides.fetch(key) { @resolved.fetch(key) { @services.lookup(path) } }
-      raise KeyError, "service #{path} is declared but unresolved this invocation" if Unresolved.equal?(object)
+      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)
 
-      object
+      exposure
     end
 
     # Execute a guest mruby source string in a fresh +mrb_state+ and return the
@@ -193,7 +193,7 @@ module Kobako
     # return value. 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
+      @resolved = @extensions.resolve.transform_values { |object| Transport::Exposure.of(object) }
       begin
         snapshot = yield
       rescue Kobako::TrapError => e

data/lib/kobako/handle.rb

@@ -1,38 +1,16 @@
 # frozen_string_literal: true
 
 module Kobako
-  # Wire-level value object for an ext-0x01 Capability Handle, used in both
-  # directions across the Sandbox boundary: as a Service method's return
-  # value (guest→host return path) and as a +#run+ argument auto-wrapped
-  # by the host.
-  #
-  # SPEC pins the binary layout to fixext 4 with a 4-byte big-endian u32
-  # payload ({docs/wire-codec.md}[link:../../docs/wire-codec.md]
-  # § Ext Types → ext 0x01). ID 0 is reserved as the invalid sentinel;
-  # the maximum valid ID is 0x7fff_ffff (2^31 - 1).
-  #
-  # The constructor is internal to the Host Gem. +Kobako::Handle.new+ is
-  # 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. +#with+ — Data's copy-with-changes
-  # constructor — is removed for the same reason: a legitimate Handle
-  # must not derive a sibling with a caller-chosen id. The Host Gem itself constructs
-  # Handles through +.restore+, which exists at exactly two call
-  # sites: +Kobako::Codec::ExtTypes#unpack_handle+ (wire decode) and
-  # +Kobako::Codec::HandleWalk.deep_wrap+ / +Kobako::Transport::Dispatcher#wrap_as_handle+
-  # (allocator paths). Both live inside +lib/kobako/+ and are not part
-  # of any public surface.
-  #
-  # The mruby counterpart +Kobako::Handle+ lives inside the Wasm guest
-  # under the same canonical name and shares neither code nor instances
-  # with this host-side class.
+  # A Capability Handle as it crosses the wire (ext 0x01, laid out in
+  # {docs/wire-codec.md}[link:../../docs/wire-codec.md]), in either
+  # direction. Host App code cannot construct one: +.new+ is private and
+  # +#with+ removed, so no Handle is ever made from a caller-chosen id.
+  # The guest's +Kobako::Handle+ shares only the name.
   class Handle < Data.define(:id)
-    # Inclusive lower bound on the wire Handle ID. ID 0 is reserved as
-    # the invalid sentinel and is never allocated.
+    # ID 0 is the invalid sentinel and is never allocated.
     MIN_ID = 1
-    # Inclusive upper bound on the wire Handle ID. The cap matches the
-    # u32 signed-positive range so Handle IDs fit in a signed integer
-    # on either side of the wire without re-encoding.
+    # The positive half of a signed 32-bit integer, so an id fits either
+    # side of the wire unchanged.
     MAX_ID = 0x7fff_ffff
 
     def initialize(id:)
@@ -45,16 +23,8 @@ module Kobako
     private_class_method :new
     undef_method :with
 
-    # Host Gem–internal factory. Allocates the Data instance through
-    # +Class#allocate+ and dispatches +#initialize+ explicitly so the
-    # invariant checks still run, while keeping the public +.new+
-    # privatised against Host App callers.
-    #
-    # 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 +Catalog::Handles+. Both
-    # paths live inside +lib/kobako/+ and treat this method as a
-    # package-private constructor.
+    # The Host Gem's own constructor, for the wire decoder and the Handle
+    # allocator; it runs the same id checks +.new+ would.
     def self.restore(id)
       allocate.tap { |handle| handle.send(:initialize, id: id) }
     end

data/lib/kobako/sandbox.rb

@@ -66,6 +66,11 @@ module Kobako
     # (+"MyService::KV"+ or a top-level +"File"+). Returns +self+ for
     # chaining.
     #
+    # The guest reaches the public methods +object+'s own class and +object+
+    # itself define in source, fixed at this call — nothing inherited, mixed
+    # in, or built into the platform. An +object+ defining a private
+    # +respond_to_guest?(name)+ decides instead, asked on every call.
+    #
     # Called with only a +path+, it declares a fillable Service:
     # +bind(path)+ reserves the path for +Kobako::Unresolved+, so the guest
     # sees the constant while the host defers the object it stands for. A

data/lib/kobako/transport/dispatcher.rb

@@ -95,9 +95,9 @@ module Kobako
       # so the reply-shaping and the failure boundary stay one glance wide.
       def run(call, resolver, handler, yielder)
         arguments, carried_handle = decode_arguments(call.payload)
-        receiver = resolve_target(call.target, resolver, handler)
+        exposure = resolve_target(call.target, resolver, handler)
         args, kwargs = resolve_call_args(arguments, handler, carried_handle)
-        catch(BREAK_THROW) { invoke(receiver, call.method_name, args, kwargs, yielder) }
+        catch(BREAK_THROW) { invoke(exposure, call.method_name, args, kwargs, yielder) }
       end
 
       # Decode the Call's payload into its arguments, reporting whether any
@@ -150,20 +150,22 @@ module Kobako
         fault("runtime", "#{error.class}: #{error.message}")
       end
 
-      # Dispatch +method+ on +target+. +kwargs+ is already Symbol-keyed
-      # (the +Payload::Arguments+ 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.
+      # Dispatch +method+ on the object behind +exposure+, once the Exposure
+      # the guest's reference carries permits it. +kwargs+ is already
+      # Symbol-keyed (the +Payload::Arguments+ 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; 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)
+      def invoke(exposure, method, args, kwargs, yielder = nil)
         name = method.to_sym
-        reject_unreachable!(target, name)
+        reject_unreachable!(exposure, name)
+        target = exposure.object
         block = yielder&.to_proc
         if kwargs.empty?
           target.public_send(name, *args, &block)
@@ -173,12 +175,12 @@ module Kobako
       end
 
       # Guard the +public_send+ below: Reflection decides what counts as
-      # Service behaviour on this target, and its refusal reason becomes
-      # the guest's +undefined+ fault. Both the ambient-surface floor and
-      # the target's own narrowing predicate answer through it, so a
-      # rejected name discloses nothing about which of the two refused.
-      def reject_unreachable!(target, name)
-        reason = Reflection.refusal(target, name)
+      # Service behaviour through this reference, and its refusal reason
+      # becomes the guest's +undefined+ fault. Both the ambient-surface
+      # floor and the reference's Exposure answer through it, so a rejected
+      # name discloses nothing about which of the two refused.
+      def reject_unreachable!(exposure, name)
+        reason = Reflection.refusal(exposure, name)
         raise UndefinedTargetError, reason if reason
       end
 
@@ -192,18 +194,18 @@ module Kobako
         raise UndefinedTargetError, e.message
       end
 
-      # Resolve a Call target to the Ruby object the path +resolver+ (or
-      # Catalog::Handles) holds. The native side already discriminated the
-      # two forms off the core envelope's +kind+ tag: a String is a bound
-      # constant's path, an Integer is a Capability Handle id. No
-      # else-branch is needed — the envelope layer is the system boundary
-      # that enforces the invariant.
+      # Resolve a Call target to the Exposure the path +resolver+ (or
+      # Catalog::Handles) holds for it. The native side already
+      # discriminated the two forms off the core envelope's +kind+ tag: a
+      # String is a bound constant's path, an Integer is a Capability Handle
+      # id. No else-branch is needed — the envelope layer is the system
+      # boundary that enforces the invariant.
       def resolve_target(target, resolver, handler)
         case target
         when String
           resolve_path(target, resolver)
         when Integer
-          require_live_object!(target, handler)
+          resolve_handle(target, handler)
         end
       end
 
@@ -213,10 +215,10 @@ module Kobako
         raise UndefinedTargetError, e.message
       end
 
-      # Resolve +id+ through the Catalog::Handles. An unknown id
-      # surfaces as UndefinedTargetError.
-      def require_live_object!(id, handler)
-        handler.fetch(id)
+      # Resolve +id+ to the Exposure its Handle was minted with. An unknown
+      # id surfaces as UndefinedTargetError.
+      def resolve_handle(id, handler)
+        handler.exposure(id)
       rescue Kobako::SandboxError => e
         raise UndefinedTargetError, e.message
       end
@@ -234,6 +236,7 @@ module Kobako
       # known, instead of falling to the boundary's codec floor and reporting
       # as an exchange that produced no Service outcome.
       def encode_ok(value, handler)
+        Kobako::Codec::Nesting.assert_within_bound!(value)
         Kobako::Codec::Encoder.encode(value)
       rescue Kobako::Codec::UnsupportedTypeError
         encode_ok(wrap_as_handle(value, handler), handler)

data/lib/kobako/transport/exposure.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require "delegate"
+
+require_relative "reflection"
+
+module Kobako
+  module Transport
+    # The methods a host object lets the guest call through one reference
+    # to it — a bound path or a Capability Handle — fixed when the reference
+    # is made. An object defining its own private +respond_to_guest?(name)+
+    # is asked on every dispatch; any other exposes only what its own class
+    # and the object itself define in source, since the methods a Host App
+    # cannot foresee handing over are the ones it never wrote.
+    #
+    # Built on the +class X < Data.define(...)+ subclass form so the class
+    # body is fully Steep-visible; see +.rubocop.yml+ for the rationale.
+    class Exposure < Data.define(:object, :names)
+      PREDICATE = :respond_to_guest?
+      private_constant :PREDICATE
+
+      # Kernel's own reflection, bound onto each object so a forwarder or a
+      # BasicObject answers from its own method table rather than through
+      # +method_missing+ / +respond_to_missing?+.
+      CLASS_OF = Kernel.instance_method(:class)
+      SINGLETON_CLASS_OF = Kernel.instance_method(:singleton_class)
+      SINGLETON_METHODS = Kernel.instance_method(:singleton_methods)
+      PRIVATE_METHODS = Kernel.instance_method(:private_methods)
+      private_constant :CLASS_OF, :SINGLETON_CLASS_OF, :SINGLETON_METHODS, :PRIVATE_METHODS
+
+      CALLABLE = Set.new(Reflection::CALLABLE_ALLOW).freeze
+      NOTHING = Set.new.freeze
+      private_constant :CALLABLE, :NOTHING
+
+      # The Exposure +object+ carries from this moment on. +surfaces+ caches
+      # each class's own surface for a caller that makes many references at
+      # once (a Handle table), so two objects of one class enumerate it once.
+      def self.of(object, surfaces = {})
+        klass = CLASS_OF.bind_call(object)
+        names = narrows_itself?(object, klass) ? nil : default_names(object, klass, surfaces)
+        new(object: object, names: names)
+      end
+
+      # Whether the guest may call +name+ through this reference. The
+      # object's own predicate is consulted with the private surface
+      # included, so the guest's +public_send+ can never reach it.
+      def exposes?(name)
+        return names.include?(name) if names
+
+        object.__send__(PREDICATE, name) ? true : false
+      end
+
+      class << self
+        private
+
+        # Whether +object+ defines the narrowing predicate itself — read off
+        # the method tables, so a forwarder's target or a catch-all
+        # +respond_to_missing?+ cannot answer for it.
+        def narrows_itself?(object, klass)
+          klass.method_defined?(PREDICATE) || klass.private_method_defined?(PREDICATE) ||
+            PRIVATE_METHODS.bind_call(object, false).include?(PREDICATE) ||
+            SINGLETON_METHODS.bind_call(object, false).include?(PREDICATE)
+        end
+
+        # A callable keeps its callable names; a class-level surface or a
+        # forwarder has no surface of its own to expose.
+        def default_names(object, klass, surfaces)
+          case object
+          when Proc, Method then CALLABLE
+          when Module, Delegator then NOTHING
+          else with_singleton(object, surfaces[klass] ||= class_names(object, klass))
+          end
+        end
+
+        def class_names(object, klass)
+          names = authored(klass)
+          case object
+          when Struct, Data then names.concat(object.members)
+          end
+          Set.new(names).freeze
+        end
+
+        def with_singleton(object, names)
+          return names if SINGLETON_METHODS.bind_call(object, false).empty?
+
+          names.union(authored(SINGLETON_CLASS_OF.bind_call(object))).freeze
+        end
+
+        # The public methods +owner+ itself defines in source. A method with
+        # no source, or whose source is the platform's own, is built in.
+        def authored(owner)
+          owner.public_instance_methods(false).select do |name|
+            file, = owner.instance_method(name).source_location
+            file && !file.start_with?("<internal:")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/kobako/transport/reflection.rb

@@ -32,18 +32,19 @@ module Kobako
 
       # The sole methods reachable on a GADGET_OWNERS target: invoking it
       # (+call+ / +[]+ / +yield+) and the harmless +arity+ / +lambda?+
-      # describers that aid guest-side debugging.
+      # describers that aid guest-side debugging. Also the whole of what a
+      # callable exposes by default, so the floor and the Exposure agree.
       CALLABLE_ALLOW = %i[call [] yield arity lambda?].freeze
-      private_constant :CALLABLE_ALLOW
 
       module_function
 
-      # The reason +name+ is unreachable on +target+, or +nil+ when the
-      # dispatch may proceed. Composes the ambient-surface floor with the
-      # target's own opt-in narrowing, in that order: the predicate only
-      # narrows and can never re-open what the floor rejects.
-      def refusal(target, name)
-        ambient_refusal(target, name) || narrowing_refusal(target, name)
+      # The reason +name+ is unreachable through +exposure+, or +nil+ when
+      # the dispatch may proceed. Composes the ambient-surface floor with the
+      # reference's Exposure, in that order: the Exposure only narrows and
+      # can never re-open what the floor rejects.
+      def refusal(exposure, name)
+        ambient_refusal(exposure.object, name) ||
+          (exposure.exposes?(name) ? nil : "method #{name.inspect} is not exposed to the guest")
       end
 
       # Guard against ambient reflection methods. A public method whose
@@ -55,7 +56,17 @@ module Kobako
       # only when the target opts into it via +respond_to?+ (dynamic
       # +method_missing+ Services), since the dangerous methods are all
       # concretely defined and therefore never reach that branch.
+      #
+      # +method_missing+ named explicitly is refused whatever its owner:
+      # it is Ruby's dynamic-dispatch hook, and a public override (a
+      # +Delegator+) binds and calls the private method the guest passes as
+      # its first argument (+Kernel#system+). A dynamic +method_missing+
+      # Service is untouched — the guest reaches it by the virtual name,
+      # which resolves through the +NameError+ branch below, never by
+      # naming +method_missing+.
       def ambient_refusal(target, name)
+        return "method #{name.inspect} is not a Service method" if name == :method_missing
+
         owner = target.public_method(name).owner
         return nil unless ambient_owner?(owner, target)
         return nil if GADGET_OWNERS.include?(owner) && CALLABLE_ALLOW.include?(name)
@@ -79,18 +90,6 @@ module Kobako
           GADGET_OWNERS.include?(owner) ||
           (target.is_a?(Module) && owner.singleton_class?)
       end
-
-      # Consult the target's opt-in narrowing predicate. A bound object may
-      # define a private +respond_to_guest?(name)+ to restrict which of its
-      # methods the guest reaches; a falsy answer refuses the dispatch. It
-      # is consulted with the private surface included so the guest's
-      # +public_send+ dispatch can never reach +respond_to_guest?+ itself.
-      def narrowing_refusal(target, name)
-        return nil unless target.respond_to?(:respond_to_guest?, true)
-        return nil if target.__send__(:respond_to_guest?, name)
-
-        "method #{name.inspect} is not exposed to the guest"
-      end
     end
   end
 end

data/lib/kobako/transport/run.rb

@@ -54,10 +54,13 @@ module Kobako
       # invocation's table, sharing the same allocator the guest→host
       # return path uses. A wrapped leaf rides as ext 0x01 in its
       # original position (docs/wire/payload-msgpack.md § ext 0x01).
+      # The walk starts one level down, since +args+ and +kwargs+ ride
+      # inside the payload document the wire's nesting bound is counted
+      # from.
       def payload(handler)
         Payload::Arguments.new(
-          args: Codec::HandleWalk.deep_wrap(args, handler),
-          kwargs: Codec::HandleWalk.deep_wrap(kwargs, handler)
+          args: Codec::HandleWalk.deep_wrap(args, handler, 1),
+          kwargs: Codec::HandleWalk.deep_wrap(kwargs, handler, 1)
         ).encode
       end
 

data/lib/kobako/transport/yielder.rb

@@ -94,11 +94,13 @@ module Kobako
 
       private
 
-      # Encode what the Service is yielding. A value outside the wire type
-      # set fails here, before the guest is re-entered, and is restated so
-      # the Service reads a refusal of its own argument rather than a codec
-      # class it never named.
+      # Encode what the Service is yielding. Arguments outside the wire
+      # type set, or nesting past the wire's bound as one list, fail here,
+      # before the guest is re-entered, and are restated so the Service
+      # reads a refusal of its own argument rather than a codec class it
+      # never named.
       def encode_args(args)
+        Kobako::Codec::Nesting.assert_within_bound!(args)
         Kobako::Codec::Encoder.encode(args)
       rescue Kobako::Codec::Error => e
         raise YieldValueError, "Service yielded a value the block cannot receive: #{e.message}"

data/lib/kobako/transport.rb

@@ -4,6 +4,7 @@ require_relative "transport/call"
 require_relative "transport/run"
 require_relative "transport/yielder"
 require_relative "transport/error"
+require_relative "transport/exposure"
 require_relative "transport/reflection"
 require_relative "transport/dispatcher"
 
@@ -12,8 +13,9 @@ module Kobako
   # host side of one Call/Reply exchange: the call value objects +Call+
   # (guest→host, as the native side decoded it) and +Run+ (host→guest), the
   # +Dispatcher+ that answers a routed Call, the +Yielder+ that re-enters
-  # the guest for a block, the +Reflection+ floor a dispatch must clear, and
-  # +Error+ for a wire violation the host detects. Each invocation's
+  # the guest for a block, the +Reflection+ floor a dispatch must clear, the
+  # +Exposure+ each reference authorizes a call against, and +Error+ for a
+  # wire violation the host detects. Each invocation's
   # +Context+ composes them into the dispatch +Proc+ it passes +Runtime+ for
   # that run.
   #

data/lib/kobako/usage.rb

@@ -1,30 +1,19 @@
 # frozen_string_literal: true
 
 module Kobako
-  # Per-last-invocation resource accounting for a +Kobako::Sandbox+.
-  # Carries two readers populated by every +#eval+ / +#run+ invocation:
+  # What one invocation spent against its caps, measured the way the caps
+  # measure it:
   #
-  #   * +wall_time+ — the Float number of seconds the guest export call
-  #     spent inside wasmtime during the most recent invocation. The
-  #     measurement bracket aligns with the +timeout+ deadline; time spent
-  #     in host Service callbacks is included, but everything that runs
-  #     after the guest export returns — the post-export
-  #     +OUTCOME_BUFFER+ fetch and decode, plus stdout / stderr capture
-  #     readout — is excluded.
-  #   * +memory_peak+ — the Integer high-water mark, in bytes, of the
-  #     per-invocation +memory.grow+ delta past the linear-memory size
-  #     captured at invocation entry. Same baseline accounting as
-  #     +memory_limit+: the mruby image's initial allocation and any
-  #     prior-invocation watermark sit outside the measurement. On
-  #     +MemoryLimitError+ +memory_peak+ never exceeds the configured
-  #     cap because the rejected +desired+ value is not promoted into
-  #     the high-water.
+  #   * +wall_time+ — Float seconds inside the guest, the span the
+  #     +timeout+ deadline governs; Service callbacks count, reading the
+  #     result and the captures afterwards does not.
+  #   * +memory_peak+ — Integer bytes of memory the invocation grew,
+  #     against the same baseline as +memory_limit+; it never exceeds the
+  #     cap, even when the cap was hit.
   #
-  # Both readers are populated on every outcome, including +TrapError+
-  # branches, so the Host App can read +#usage+ off the run's
-  # +Kobako::Execution+ — the one a raised error carries on +#execution+ —
-  # after rescuing a trap to diagnose how much of the budget the failing
-  # invocation consumed.
+  # Filled on every outcome, traps included, so a Host App that rescues a
+  # trap can read from the error's +#execution+ how much of the budget the
+  # invocation used.
   #
   # Built on the +class X < Data.define(...)+ subclass form (the
   # Steep-friendly shape — see +.rubocop.yml+ for the rationale).

data/lib/kobako/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Kobako
-  VERSION = "0.23.0"
+  VERSION = "0.26.0"
 end

data/release-please-config.json

@@ -5,9 +5,9 @@
   "last-release-sha": "98509af508988f708bf0d7a76a718bb0428a177e",
   "packages": {
     ".": {
-      "component": "kobako",
       "include-component-in-tag": false,
       "release-type": "ruby",
+      "version-file": "lib/kobako/version.rb",
       "exclude-paths": ["wasm", "crates"]
     },
     "wasm/kobako-core": {

data/sig/kobako/catalog/handles.rbs

@@ -7,6 +7,8 @@ module Kobako
 
       def fetch: (Integer id) -> untyped
 
+      def exposure: (Integer id) -> Kobako::Transport::Exposure
+
       def size: () -> Integer
 
       private

data/sig/kobako/catalog/services.rbs

@@ -9,7 +9,7 @@ module Kobako
 
       def bound?: (Symbol | String path) -> bool
 
-      def lookup: (Symbol | String target) -> untyped
+      def lookup: (Symbol | String target) -> Kobako::Transport::Exposure
 
       def paths: () -> Array[String]