kobako 0.28.0 → 0.29.0

data/lib/kobako/codec/state.rb

@@ -2,8 +2,9 @@
 
 module Kobako
   module Codec
-    # Whether a Capability Handle crossed the decode in flight, kept per
-    # thread so plain instance variables stay sound.
+    # Whether a Capability Handle crossed the decode in flight, and the
+    # value budget a decode is held to, 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__
@@ -18,6 +19,21 @@ module Kobako
 
       def initialize
         @carried_handle = false
+        @value_budget = nil
+      end
+
+      # The most values a decode on this thread may build, or nil for no
+      # budget.
+      attr_reader :value_budget
+
+      # A nested invocation on the same thread restores the outer one's
+      # budget when it returns.
+      def within_value_budget(budget)
+        outer = @value_budget
+        @value_budget = budget
+        yield
+      ensure
+        @value_budget = outer
       end
 
       # ExtTypes#unpack_handle is the sole chokepoint every Handle passes
@@ -30,7 +46,7 @@ module Kobako
 
       # Record that an ext 0x01 Capability Handle crossed the current
       # decode; #track_handles reports it to the bracketing caller.
-      def record_handle!
+      def record_handle
         @carried_handle = true
       end
     end

data/lib/kobako/codec/value_budget.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require_relative "error"
+
+module Kobako
+  module Codec
+    # Counts the values a payload holds before the decoder builds any, so a
+    # guest cannot make the host build more objects than its budget allows
+    # (docs/wire/payload-msgpack.md § Value Budget). Every value takes at
+    # least one byte, so a payload no longer than the budget needs no count.
+    #
+    # The count stops at the first byte it cannot frame and leaves that
+    # payload for the decoder to refuse in its own words.
+    module ValueBudget # :nodoc:
+      # Marker to the body width of a scalar with no length field.
+      SCALARS = {
+        0xc0 => 0, 0xc2 => 0, 0xc3 => 0, 0xca => 4, 0xcb => 8,
+        0xcc => 1, 0xcd => 2, 0xce => 4, 0xcf => 8,
+        0xd0 => 1, 0xd1 => 2, 0xd2 => 4, 0xd3 => 8,
+        0xd4 => 2, 0xd5 => 3, 0xd6 => 5, 0xd7 => 9, 0xd8 => 17
+      }.freeze
+      # Marker to a container's count width and the values each entry holds.
+      COUNTS = { 0xdc => [2, 1], 0xdd => [4, 1], 0xde => [2, 2], 0xdf => [4, 2] }.freeze
+      # Marker to a str, bin, or ext's length width and type tag width.
+      LENGTHS = {
+        0xc4 => [1, 0], 0xc5 => [2, 0], 0xc6 => [4, 0],
+        0xd9 => [1, 0], 0xda => [2, 0], 0xdb => [4, 0],
+        0xc7 => [1, 1], 0xc8 => [2, 1], 0xc9 => [4, 1]
+      }.freeze
+      UINT = { 1 => "C", 2 => "n", 4 => "N" }.freeze
+      private_constant :SCALARS, :COUNTS, :LENGTHS, :UINT
+
+      def self.assert_within!(bytes, budget)
+        return if budget.nil? || bytes.bytesize <= budget
+
+        remaining = budget
+        pending = 1
+        pos = 0
+        while pending.positive?
+          pos, children = step(bytes, pos)
+          return if pos.nil?
+          raise InvalidTypeError, "payload holds more than #{budget} values" if (remaining -= 1).negative?
+
+          pending += children - 1
+        end
+      end
+
+      # The position after the value at +pos+, nil for one the payload
+      # cannot frame, and the values it holds directly.
+      def self.step(bytes, pos)
+        marker = bytes.getbyte(pos) or return [nil, 0]
+        pos += 1
+        case marker
+        when 0x00..0x7f, 0xe0..0xff then [pos, 0]
+        when 0x80..0x8f then [pos, (marker & 0x0f) * 2]
+        when 0x90..0x9f then [pos, marker & 0x0f]
+        when 0xa0..0xbf then [pos + (marker & 0x1f), 0]
+        else step_framed(bytes, pos, marker)
+        end
+      end
+
+      def self.step_framed(bytes, pos, marker)
+        return [pos + SCALARS.fetch(marker), 0] if SCALARS.key?(marker)
+
+        width, per = COUNTS[marker]
+        return [pos + width, uint(bytes, pos, width) * per] if width && per
+
+        width, tag = LENGTHS[marker]
+        return [nil, 0] unless width && tag
+
+        [pos + width + tag + uint(bytes, pos, width), 0]
+      end
+
+      # A length cut short reads as zero, so the count runs off the end and
+      # stops there.
+      def self.uint(bytes, pos, width)
+        slice = bytes.byteslice(pos, width).to_s
+        return 0 if slice.bytesize < width
+
+        slice.unpack1(UINT.fetch(width)) # : Integer
+      end
+
+      private_class_method :step, :step_framed, :uint
+    end
+  end
+end

data/lib/kobako/codec.rb

@@ -5,6 +5,7 @@ require_relative "codec/utils"
 require_relative "codec/handle_walk"
 require_relative "codec/nesting"
 require_relative "codec/state"
+require_relative "codec/value_budget"
 require_relative "codec/ext_types"
 require_relative "codec/encoder"
 require_relative "codec/decoder"
@@ -23,5 +24,11 @@ module Kobako
     def self.track_handles(&block)
       State.current.track_handles(&block)
     end
+
+    # Holds every decode the block runs on this thread to +budget+ values,
+    # or to none when +budget+ is nil.
+    def self.within_value_budget(budget, &block)
+      State.current.within_value_budget(budget, &block)
+    end
   end
 end

data/lib/kobako/context.rb

@@ -17,12 +17,12 @@ module Kobako
   #
   #   sandbox.eval("Req::Current.user_id") { |ctx| ctx.bind("Req::Current", request) }
   class Context
-    def initialize(runtime:, services:, snippets:, flags:, extensions:) # :nodoc:
+    def initialize(runtime:, services:, extensions:, grants:, preamble:) # :nodoc:
       @runtime = runtime
       @services = services
-      @snippets = snippets
-      @flags = flags
       @extensions = extensions
+      @grants = grants
+      @preamble = preamble
       @resolved = {} # : Hash[String, Transport::Exposure]
       @overrides = {} # : Hash[String, Transport::Exposure]
       @handles = Catalog::Handles.new
@@ -45,6 +45,26 @@ module Kobako
       self
     end
 
+    # Use +filesystem+ for the mount at +at+ during this invocation only,
+    # with its own +access+ and block, as Sandbox#mount takes them. Returns
+    # +self+.
+    #
+    # Raises TypeError for a path that is no String or something other than
+    # a Filesystem, and ArgumentError when nothing was mounted at +at+ on the
+    # Sandbox, for a malformed path or an unknown access, or when called
+    # after the block has returned.
+    def mount(at, filesystem, access: :read, &policy)
+      raise ArgumentError, "Kobako::Context is spent; ctx.mount is only valid inside the #eval / #run block" if @spent
+
+      Runtime.validate_mount!(at, access, filesystem)
+      mount = Catalog::Mount.new(at: at, access: access, filesystem: filesystem, policy: policy)
+      raise ArgumentError, "cannot override unmounted path #{at.inspect}" unless @grants.include?(mount)
+
+      mounts = @mounts ||= {} # : Hash[String, Catalog::Mount]
+      mounts[mount.key] = mount
+      self
+    end
+
     # 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:
@@ -57,21 +77,25 @@ module Kobako
 
     def eval(code, &block) # :nodoc:
       collect_overrides(&block) if block
-      invoke!(:eval) do
-        @runtime.eval(dispatch_handler, @services.paths, @snippets.entries, @flags.entries, code.b)
-      end
+      invoke!(:eval) { @runtime.eval(dispatch_handler, setup, code.b) }
     end
 
     def run(request, &block) # :nodoc:
       collect_overrides(&block) if block
       invoke!(:run, entrypoint: request.entrypoint) do
-        @runtime.run(dispatch_handler, @services.paths, @snippets.entries, @flags.entries,
-                     request.entrypoint.to_s, request.payload(@handles))
+        @runtime.run(dispatch_handler, setup, request.entrypoint.to_s, request.payload(@handles))
       end
     end
 
     private
 
+    # What the Runtime builds the invocation from: the Preamble's parts,
+    # then this invocation's mounts.
+    def setup
+      paths, snippets, flags = @preamble
+      [paths, snippets, flags, @grants.entries(@mounts || {})]
+    end
+
     # 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.
@@ -83,17 +107,20 @@ module Kobako
 
     # 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.
+    # Built once per invocation, so every Call it answers shares one
+    # BlockFailure.
     def dispatch_handler
+      failure = Transport::BlockFailure.new
       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, @handles, guest_yielder)
+        Transport::Dispatcher.dispatch(call, self, @handles, failure, guest_yielder)
       end
     end
 
     # Every Snapshot carries usage and captures, trap or not, so they stay
     # readable after a rescued trap.
-    def populate_observability!(snapshot)
+    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?)
@@ -137,7 +164,7 @@ module Kobako
       rescue Kobako::TrapError => e
         raise with_verb(e, verb)
       end
-      populate_observability!(snapshot)
+      populate_observability(snapshot)
       trap = snapshot.trap_error
       return settle_outcome(snapshot, verb, entrypoint) unless trap
 

data/lib/kobako/errors.rb

@@ -8,11 +8,7 @@ module Kobako
   # The base of every error kobako raises.
   class Error < StandardError; end
 
-  # Gives an invocation failure the Execution of the run that failed, so a
-  # rescue reads its captures and usage as a successful caller would.
-  # +execution+ is +nil+ when the failure came before the guest ran.
-  module CarriesExecution
-    # The Execution of the run that failed.
+  module Recorded # :nodoc:
     attr_reader :execution
 
     def with_execution(execution) # :nodoc:
@@ -23,8 +19,11 @@ module Kobako
 
   # The engine stopped the guest: a trap, a cap reached, or an outcome that
   # could not be read. The next invocation on the same Sandbox runs as usual.
+  # +execution+ is the failed run's Execution, so a rescue reads its captures
+  # and usage as a successful caller would; it is +nil+ when the failure came
+  # before the guest ran.
   class TrapError < Error
-    include CarriesExecution
+    include Recorded
   end
 
   # The invocation ran past its +timeout+.
@@ -41,10 +40,7 @@ module Kobako
   # The Guest Binary is missing at +wasm_path+.
   class ModuleNotBuiltError < SetupError; end
 
-  # What the guest reported about a failure.
-  module Diagnosable
-    # Where the failure came from (<tt>"sandbox"</tt> or <tt>"service"</tt>),
-    # the name of the class that raised it, and its backtrace.
+  module Diagnosable # :nodoc:
     attr_reader :origin, :klass, :backtrace_lines
 
     def initialize(message, origin: nil, klass: nil, backtrace_lines: nil) # :nodoc:
@@ -57,15 +53,19 @@ module Kobako
 
   # The guest failed: the script raised or did not compile, the Guest Binary
   # could not start the run, or what it produced could not be read.
+  # +origin+ (<tt>"sandbox"</tt> or <tt>"service"</tt>), +klass+ and
+  # +backtrace_lines+ say where it came from, which class raised it, and its
+  # backtrace. +execution+ is the failed run's Execution, as on TrapError.
   class SandboxError < Error
     include Diagnosable
-    include CarriesExecution
+    include Recorded
   end
 
-  # A Service call failed and the guest left it unrescued.
+  # A Service call failed and the guest left it unrescued. It carries
+  # +origin+, +klass+, +backtrace_lines+ and +execution+ as SandboxError does.
   class ServiceError < Error
     include Diagnosable
-    include CarriesExecution
+    include Recorded
   end
 
   # The call reached no Service method: nothing is bound there, the Handle
@@ -73,7 +73,8 @@ module Kobako
   # same on purpose, so a target discloses nothing about what it defines.
   class NoServiceError < ServiceError; end
 
-  # The call reached the Service method with arguments that did not fit.
+  # The Service method refused its arguments: the call would not bind, or
+  # the method raised +ArgumentError+ over what it was given.
   class ServiceArgumentError < ServiceError; end
 
   # Raised at a Service's +yield+ when the guest block raised; rescue it as

data/lib/kobako/filesystem.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Kobako
+  # The Filesystems a Sandbox can mount for the guest's +File+, each
+  # answered in Rust by the kind of the same name. Hand one to
+  # Sandbox#mount:
+  #
+  #   sandbox.mount("/data", Kobako::Filesystem::Memory.new("config.yml" => yaml))
+  #
+  # [<tt>Memory.new(files = {}, limit: 64 MiB, inodes:)</tt>]
+  #   Files held in memory for as long as the object lives, seeded from a
+  #   Hash of path to contents. Every invocation shares them.
+  # [<tt>Temporary.new(limit: 64 MiB, inodes:)</tt>]
+  #   Files held in memory that every invocation starts empty.
+  # [<tt>Directory.new(path)</tt>]
+  #   A host directory and everything beneath it. Nothing outside it is
+  #   reachable, a symbolic link pointing out included.
+  # [<tt>Overlay.new.layer(filesystem, access: :read)</tt>]
+  #   Layers stacked into one view, the first added on top, each +:read+
+  #   or +:read_write+ on its own. A change lands in a writable Layer, and
+  #   a read-only one stays as it was. Each +layer+ answers a new Overlay.
+  #
+  # A Memory or Temporary is bounded as a tmpfs mount is: its files hold
+  # at most +limit+ bytes together, and it holds at most +inodes+ files and
+  # directories, its root among them; +nil+ lifts either bound. Without
+  # +inodes+ it holds one for each 4 KiB of +limit+, and the root. Past
+  # either, the guest raises Errno::ENOSPC.
+  #
+  # Any object answering +open+ and +stat+ mounts too, as a Filesystem
+  # written in Ruby; its methods take the names of +File+, +Dir+, and +IO+.
+  # Its +stat+ answers +directory?+, +size+, and +ino+, an +ino+ naming one
+  # directory for as long as the guest holds it open. Its names match
+  # exactly, as a mount's block judges them as given. A name may hold a
+  # <tt>\\</tt>, which the guest's paths never separate on, so one joined
+  # to a Windows host path is the Filesystem's to refuse.
+  module Filesystem
+  end
+end

data/lib/kobako/pool.rb

@@ -94,7 +94,7 @@ module Kobako
       done = true
       sandbox
     ensure
-      release_capacity! unless done
+      release_capacity unless done
     end
 
     def checkin(sandbox)
@@ -104,7 +104,7 @@ module Kobako
       end
     end
 
-    def release_capacity!
+    def release_capacity
       @mutex.synchronize do
         @constructed -= 1
         @slot_freed.signal

data/lib/kobako/sandbox.rb

@@ -24,7 +24,8 @@ module Kobako
     # readable on the Sandbox itself, as in #timeout.
     attr_reader :options
 
-    def_delegators :@options, :timeout, :memory_limit, :stdout_limit, :stderr_limit, :profile, :gvl
+    def_delegators :@options, :timeout, :setup_timeout, :memory_limit, :stdout_limit, :stderr_limit,
+                   :open_file_limit, :profile, :gvl
 
     # Build a Sandbox on the Guest Binary at +wasm_path+, the one bundled
     # with the gem by default. The other keywords are the options
@@ -40,6 +41,7 @@ module Kobako
       @snippets = Catalog::Snippets.new
       @flags = Catalog::Flags.new
       @extensions = Catalog::Extensions.new
+      @grants = Catalog::Grants.new
       @sealed = false
       @runtime = build_runtime!
     end
@@ -56,8 +58,9 @@ module Kobako
     # the constant, and Context#bind supplies the object for each invocation.
     # A call to one left unfilled fails as a ServiceError.
     #
-    # Raises ArgumentError for a malformed path, a path that collides with an
-    # existing binding, or a call after the first invocation.
+    # Raises ArgumentError for a malformed path, a path under the reserved
+    # +Kobako+ namespace, a path that collides with an existing binding, or a
+    # call after the first invocation.
     def bind(path, object = Unresolved)
       refuse_once_invoked!("bind")
       @services.bind(path, object)
@@ -77,6 +80,27 @@ module Kobako
       self
     end
 
+    # Mount +filesystem+, a Kobako::Filesystem, at the absolute guest path
+    # +at+, where the guest's +File+ reaches it. +access+ is +:read+ or
+    # +:read_write+; a write beneath a read-only mount fails as
+    # <tt>Errno::EROFS</tt> in the guest. Returns +self+.
+    #
+    # A given block decides, in +access+'s place, each open and each change
+    # that reaches the mount, asked at most once for each with the guest path
+    # and +:read+ or +:read_write+. A falsy answer,
+    # or a StandardError, fails that call as <tt>Errno::EACCES</tt> in the
+    # guest and leaves the script running.
+    #
+    # Raises TypeError for a path that is no String or something other than
+    # a Filesystem, and ArgumentError for a malformed, duplicate, or nested
+    # path, an unknown access, or a call after the first invocation.
+    def mount(at, filesystem, access: :read, &policy)
+      refuse_once_invoked!("mount")
+      Runtime.validate_mount!(at, access, filesystem)
+      @grants.register(Catalog::Mount.new(at: at, access: access, filesystem: filesystem, policy: policy))
+      self
+    end
+
     # Register a snippet that every invocation runs, in the order registered,
     # before its own code. Returns +self+.
     #
@@ -121,7 +145,7 @@ module Kobako
     # Handle or a non-Symbol keyword. A failed run raises as #eval does.
     def run(target, *args, **kwargs, &block)
       request = Transport::Run.new(entrypoint: target, args: args, kwargs: kwargs)
-      new_invocation.run(request, &block)
+      Codec.within_value_budget(@options.value_budget) { new_invocation.run(request, &block) }
     end
 
     # Evaluate +code+, mruby source as a String, and return the Execution,
@@ -136,7 +160,7 @@ module Kobako
     def eval(code, &block)
       raise SandboxError, "code must be a String, got #{code.class}" unless code.is_a?(String)
 
-      new_invocation.eval(code, &block)
+      Codec.within_value_budget(@options.value_budget) { new_invocation.eval(code, &block) }
     end
 
     private
@@ -144,9 +168,7 @@ module Kobako
     # A runtime whose declared posture falls below the request never runs
     # guest code.
     def build_runtime!
-      runtime = Kobako::Runtime.from_path(@wasm_path, @options.timeout, @options.memory_limit,
-                                          @options.stdout_limit, @options.stderr_limit, @options.profile,
-                                          @options.gvl)
+      runtime = Kobako::Runtime.from_path(@wasm_path, **@options.to_h)
       @options.enforce_floor!(runtime.profile)
       runtime
     end
@@ -155,12 +177,18 @@ module Kobako
     # does is written back onto the shared config.
     def new_invocation
       begin_invocation!
-      Context.new(runtime: @runtime, services: @services, snippets: @snippets, flags: @flags,
-                  extensions: @extensions)
+      Context.new(runtime: @runtime, services: @services, extensions: @extensions, grants: @grants,
+                  preamble: preamble(@snippets.entries))
+    end
+
+    # The one place the Preamble's parts are put together, for a compile
+    # and for every invocation alike.
+    def preamble(snippets)
+      [@services.paths, snippets, @flags.entries]
     end
 
     # Registration closes at the first invocation, so every invocation ships
-    # the same Services, snippets, flags and Extensions.
+    # the same Services, snippets, flags, Extensions and mounts.
     def refuse_once_invoked!(verb)
       raise ArgumentError, "cannot #{verb} after first Sandbox invocation" if @sealed
     end
@@ -171,7 +199,7 @@ module Kobako
     def begin_invocation!
       @sealed = true
       @extensions.assert_dependencies!
-      @snippets.compile { |entries| @runtime.compile(@services.paths, entries, @flags.entries) }
+      @snippets.compile { |entries| @runtime.compile(preamble(entries)) }
     end
   end
 end

data/lib/kobako/sandbox_options.rb

@@ -8,25 +8,38 @@ module Kobako
   # default, and +nil+ switches it off.
   #
   # [+timeout+]       Float seconds one invocation may run.
+  # [+setup_timeout+] Float seconds the Guest Binary may take to be set up
+  #                   the first time its path is loaded.
   # [+memory_limit+]  Integer bytes one invocation may grow guest memory by.
   # [+stdout_limit+, +stderr_limit+]
   #                   Integer bytes kept from each output channel.
+  # [+open_file_limit+]
+  #                   Integer descriptors one invocation may hold open, the
+  #                   standard ones and each Mount's included.
   # [+profile+]       The isolation the runtime must provide, one of PROFILES.
   # [+gvl+]           How an invocation holds Ruby's GVL, one of GVL_MODES.
   #
   # Raises ArgumentError for a value outside these shapes, and SetupError
   # when the runtime provides less isolation than +profile+ asks for.
-  class SandboxOptions < Data.define(:timeout, :memory_limit, :stdout_limit, :stderr_limit, :profile, :gvl)
+  class SandboxOptions < Data.define(:timeout, :setup_timeout, :memory_limit, :stdout_limit, :stderr_limit,
+                                     :open_file_limit, :profile, :gvl)
     # The default +timeout+: 60 seconds.
     DEFAULT_TIMEOUT_SECONDS = 60.0
 
-    # The default +memory_limit+: 1 MiB of growth past the guest's starting
-    # memory.
-    DEFAULT_MEMORY_LIMIT = 1 << 20
+    # The default +setup_timeout+: 10 seconds.
+    DEFAULT_SETUP_TIMEOUT_SECONDS = 10.0
+
+    # The default +memory_limit+: 4 MiB of growth past the guest's starting
+    # memory, sized for a guest whose every value takes 16 bytes.
+    DEFAULT_MEMORY_LIMIT = 4 << 20
 
     # The default +stdout_limit+ and +stderr_limit+: 1 MiB each.
     DEFAULT_OUTPUT_LIMIT = 1 << 20
 
+    # The default +open_file_limit+: 1024, the soft limit Linux gives a
+    # process.
+    DEFAULT_OPEN_FILE_LIMIT = 1024
+
     # The isolation profiles, weakest first. +:hermetic+ denies the guest the
     # clock and entropy; +:permissive+ leaves them live.
     PROFILES = %i[permissive hermetic].freeze
@@ -42,20 +55,34 @@ module Kobako
     DEFAULT_GVL = :hold
 
     def initialize(timeout: DEFAULT_TIMEOUT_SECONDS,
+                   setup_timeout: DEFAULT_SETUP_TIMEOUT_SECONDS,
                    memory_limit: DEFAULT_MEMORY_LIMIT,
                    stdout_limit: DEFAULT_OUTPUT_LIMIT,
                    stderr_limit: DEFAULT_OUTPUT_LIMIT,
+                   open_file_limit: DEFAULT_OPEN_FILE_LIMIT,
                    profile: DEFAULT_PROFILE,
                    gvl: DEFAULT_GVL)
-      timeout = normalize_timeout(timeout)
-      memory_limit = normalize_byte_limit(memory_limit, "memory_limit")
-      stdout_limit = normalize_byte_limit(stdout_limit, "stdout_limit")
-      stderr_limit = normalize_byte_limit(stderr_limit, "stderr_limit")
+      timeout = normalize_timeout(timeout, "timeout")
+      setup_timeout = normalize_timeout(setup_timeout, "setup_timeout")
+      memory_limit = normalize_limit(memory_limit, "memory_limit")
+      stdout_limit = normalize_limit(stdout_limit, "stdout_limit")
+      stderr_limit = normalize_limit(stderr_limit, "stderr_limit")
+      open_file_limit = normalize_limit(open_file_limit, "open_file_limit")
       profile = normalize_choice(profile, PROFILES, "profile")
       gvl = normalize_choice(gvl, GVL_MODES, "gvl")
       super
     end
 
+    # The least guest memory one value occupies, so a guest payload may hold
+    # one value for each of these bytes of +memory_limit+
+    # (docs/wire/payload-msgpack.md § Value Budget).
+    VALUE_BYTES = 16
+    private_constant :VALUE_BYTES
+
+    def value_budget # :nodoc:
+      memory_limit&./(VALUE_BYTES)
+    end
+
     # Both fallbacks fail closed: an unknown declaration ranks below every
     # request, and an unknown request refuses every declaration.
     def enforce_floor!(declared) # :nodoc:
@@ -69,17 +96,17 @@ module Kobako
 
     # A zero or negative timeout would either fire instantly or never, both
     # more surprising than an early ArgumentError.
-    def normalize_timeout(timeout)
+    def normalize_timeout(timeout, name)
       return nil if timeout.nil?
-      raise ArgumentError, "timeout must be Numeric or nil, got #{timeout.class}" unless timeout.is_a?(Numeric)
+      raise ArgumentError, "#{name} must be Numeric or nil, got #{timeout.class}" unless timeout.is_a?(Numeric)
 
       seconds = timeout.to_f
-      raise ArgumentError, "timeout must be > 0 (got #{timeout})" unless seconds.positive? && seconds.finite?
+      raise ArgumentError, "#{name} must be > 0 (got #{timeout})" unless seconds.positive? && seconds.finite?
 
       seconds
     end
 
-    def normalize_byte_limit(limit, name)
+    def normalize_limit(limit, name)
       return nil if limit.nil?
       unless limit.is_a?(Integer) && limit.positive?
         raise ArgumentError, "#{name} must be a positive Integer or nil, got #{limit.inspect}"

data/lib/kobako/snippet/{binary.rb → bytecode.rb}

@@ -2,7 +2,7 @@
 
 module Kobako
   module Snippet
-    class Binary < Data.define(:body) # :nodoc:
+    class Bytecode < Data.define(:body) # :nodoc:
       # Names the snippet form the guest replays this entry as. The wire's
       # discriminant byte is assigned by the core envelope, not here.
       KIND = :bytecode

data/lib/kobako/snippet.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative "snippet/binary"
+require_relative "snippet/bytecode"
 require_relative "snippet/source"
 
 module Kobako

data/lib/kobako/transport/block_failure.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Kobako
+  module Transport
+    # The newest failure a guest block raised to a Service during one
+    # invocation, whichever open Call carried that block: a Service may run
+    # a block stored from an earlier Call, and its failure is still the
+    # guest's own.
+    class BlockFailure # :nodoc:
+      def initialize
+        @raised = nil
+      end
+
+      # Only the newest is kept: a Service that rescued an earlier one and
+      # yielded again has already handled it.
+      def remember(error)
+        @raised = error
+      end
+
+      # Identity rather than class: a Service that rescued the block's
+      # failure and raised its own has reported something else, and the
+      # guest must hear about that instead.
+      #
+      # The class travels with the message because not every block failure
+      # is an exception the guest holds — a block value the guest refused
+      # has a class to raise under and no object to continue.
+      def fault_text(error)
+        raised = @raised
+        return if raised.nil? || !error.equal?(raised)
+
+        "#{raised.klass}: #{raised.message}"
+      end
+    end
+  end
+end