kobako 0.2.1 → 0.4.0

data/lib/kobako/sandbox_options.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Kobako
+  # Kobako::SandboxOptions — immutable Value Object holding the four
+  # per-Sandbox configuration caps ({docs/behavior.md B-01,
+  # E-20}[link:../../docs/behavior.md]). Built on the +class X <
+  # Data.define(...)+ subclass form (the Steep-friendly shape — see
+  # +lib/kobako/outcome/panic.rb+).
+  #
+  # The +initialize+ method does double duty: it applies DEFAULT fallback
+  # 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.
+  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]).
+    DEFAULT_TIMEOUT_SECONDS = 60.0
+
+    # Default cap on the per-invocation guest linear-memory delta:
+    # 1 MiB ({docs/behavior.md B-01}[link:../../docs/behavior.md]).
+    # The mruby image's initial allocation and prior invocations'
+    # watermark sit outside this budget — see B-01 Notes.
+    DEFAULT_MEMORY_LIMIT = 1 << 20
+
+    # Default per-channel capture ceiling: 1 MiB
+    # ({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
+      )
+    end
+
+    private
+
+    # Coerce +timeout+ into the Float seconds the ext expects, or +nil+
+    # to mean the cap is disabled. Any finite non-positive value is
+    # rejected — a zero or negative timeout would either fire instantly
+    # or never, both of which would surprise callers more than an early
+    # +ArgumentError+.
+    def normalize_timeout(timeout)
+      return nil if timeout.nil?
+      raise ArgumentError, "timeout 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?
+
+      seconds
+    end
+
+    # Coerce +memory_limit+ into the byte cap the ext expects, or +nil+
+    # to mean unbounded. Must be a positive Integer when set; Float or
+    # zero/negative values are rejected.
+    def normalize_memory_limit(memory_limit)
+      return nil if memory_limit.nil?
+      unless memory_limit.is_a?(Integer) && memory_limit.positive?
+        raise ArgumentError, "memory_limit must be a positive Integer or nil, got #{memory_limit.inspect}"
+      end
+
+      memory_limit
+    end
+    # steep:ignore:end
+  end
+end

data/lib/kobako/snippet/binary.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Kobako
+  module Snippet
+    # Kobako::Snippet::Binary — value object representing a single
+    # +#preload(binary:)+ entry held by +Kobako::Snippet::Table+
+    # ({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
+    # ({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.
+    class Binary < Data.define(:body)
+      # The +kind+ field value carried by bytecode snippets in their
+      # Frame 3 wire envelope entry
+      # ({docs/wire-codec.md Invocation channels}[link:../../../docs/wire-codec.md]).
+      KIND = "bytecode"
+    end
+  end
+end

data/lib/kobako/snippet/source.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Kobako
+  module Snippet
+    # Kobako::Snippet::Source — value object representing a single
+    # +#preload(code:, name:)+ entry held by +Kobako::Snippet::Table+
+    # ({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.
+    #
+    # 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.
+    class Source < Data.define(:name, :body)
+      # The +kind+ field value carried by source snippets in their Frame
+      # 3 wire envelope entry
+      # ({docs/wire-codec.md Invocation channels}[link:../../../docs/wire-codec.md]).
+      KIND = "source"
+    end
+  end
+end

data/lib/kobako/snippet/table.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+require "msgpack"
+
+require_relative "binary"
+require_relative "source"
+
+module Kobako
+  module Snippet
+    # Kobako::Snippet::Table — per-Sandbox insertion-ordered registry of
+    # preloaded snippets
+    # ({docs/behavior.md B-32 / B-33}[link:../../../docs/behavior.md]).
+    #
+    # Entries replay against the fresh +mrb_state+ before per-invocation
+    # source / entrypoint resolution. Each +Source+ entry's +name+ is its
+    # canonical identity — the filename baked into the loaded IREP's
+    # +debug_info+ that surfaces in every backtrace frame originating
+    # from the snippet as +(snippet:Name):line+. Duplicate names within
+    # the +code:+ form would produce ambiguous attribution and are
+    # rejected at registration time
+    # ({docs/behavior.md E-33}[link:../../../docs/behavior.md]).
+    # +Binary+ entries carry no host-side name — their canonical name
+    # lives in the bytecode's +debug_info+ and is read by the guest at
+    # load time; the host does not extract it.
+    #
+    # Sealing (B-33) is governed by the owning Sandbox — the table itself
+    # is append-only and exposes no mutation API beyond +#register+; the
+    # Sandbox guards +#register+ behind the seal check before delegating.
+    class Table
+      # Ruby constant-name pattern enforced on snippet names
+      # ({docs/behavior.md E-34}[link:../../../docs/behavior.md]).
+      NAME_PATTERN = /\A[A-Z]\w*\z/
+
+      def initialize
+        @entries = [] # : Array[Kobako::Snippet::Source | Kobako::Snippet::Binary]
+      end
+
+      # Serialize the registered snippets to wire bytes. Each entry
+      # contributes a msgpack map shape; the collection rides as a single
+      # msgpack array. An empty table serializes to an empty array, never
+      # absent. The wire codec is an implementation detail — callers
+      # receive a binary +String+ that the +Kobako::Wasm+ layer ships
+      # through the invocation channel. Mirrors the
+      # +Kobako::RPC.encode_request+ pattern: entry value objects stay
+      # pure carriers, this method reads their attributes externally.
+      def encode
+        MessagePack.pack(@entries.map { |entry| entry_payload(entry) })
+      end
+
+      # Register one preloaded snippet in either of two forms
+      # ({docs/behavior.md B-32}[link:../../../docs/behavior.md]).
+      #
+      #   * Source form +register(code: src, name: Name)+ — +src+ is the
+      #     mruby source as a String; the bytes are re-encoded as UTF-8
+      #     and detached from the caller's reference. +name+ is a Symbol
+      #     or String matching +NAME_PATTERN+. Returns the Symbol form
+      #     of +name+.
+      #   * Binary form +register(binary: bytes)+ — +bytes+ is
+      #     precompiled RITE bytecode as a String, duplicated and forced
+      #     to ASCII-8BIT so msgpack-ruby ships it as +bin+. Returns
+      #     +nil+ — bytecode entries are anonymous on the host side; any
+      #     structural validation
+      #     ({docs/behavior.md E-37 / E-38}[link:../../../docs/behavior.md])
+      #     is deferred to the guest at first replay.
+      #
+      # The two forms are mutually exclusive: shape validation lives
+      # here so callers (chiefly +Kobako::Sandbox#preload+) collapse to
+      # a single delegation. Raises +ArgumentError+ on mixed forms,
+      # missing keywords, wrong types, malformed +name+ (E-34), or
+      # duplicate +code:+ +name+ (E-33).
+      def register(code: nil, name: nil, binary: nil)
+        if binary
+          raise ArgumentError, "cannot combine binary: with code: / name:" if code || name
+
+          register_binary!(binary)
+        else
+          register_source!(code, name)
+        end
+      end
+
+      # Iterate over registered entries in insertion order. Yields each
+      # entry (a +Kobako::Snippet::Source+ or +Kobako::Snippet::Binary+).
+      # Returns an Enumerator when no block is given.
+      def each(&)
+        @entries.each(&)
+      end
+
+      # Canonical names of every registered +Source+ entry, in insertion
+      # order. +Binary+ entries are skipped — their names live in
+      # bytecode +debug_info+ on the guest side and are not extracted by
+      # the host.
+      def names
+        @entries.filter_map { |entry| entry.name if entry.is_a?(Source) }
+      end
+
+      # Number of registered snippets.
+      def size
+        @entries.size
+      end
+
+      # Whether no snippets are registered.
+      def empty?
+        @entries.empty?
+      end
+
+      private
+
+      # Source-form register path. Delegates argument-shape checks to
+      # +ensure_source_args!+ (which returns the narrowed
+      # +[code, name]+ pair), normalises +name+ to a Symbol, rejects
+      # duplicates (E-33), and appends the Source entry.
+      def register_source!(code, name)
+        code, name = ensure_source_args!(code, name)
+        name_sym = normalize_name(name)
+        raise ArgumentError, "snippet #{name_sym.inspect} already preloaded" if names.include?(name_sym)
+
+        @entries << Source.new(name: name_sym, body: code.dup.force_encoding(Encoding::UTF_8))
+        name_sym
+      end
+
+      # Shape-only validation for the +code:+ + +name:+ pair. Returns
+      # the pair with +nil+ narrowed away so callers can treat both as
+      # present. The +code:+ type check runs before the +name:+
+      # presence check so callers passing +code: nil+ explicitly see
+      # the type error rather than the "missing keyword" error.
+      def ensure_source_args!(code, name)
+        raise ArgumentError, "missing keyword: code: + name:, or binary:" if code.nil? && name.nil?
+        raise ArgumentError, "code must be a String, got #{code.class}" unless code.is_a?(String)
+        raise ArgumentError, "missing keyword: name:" if name.nil?
+
+        [code, name]
+      end
+
+      # Binary-form register path. Validates the +binary:+ payload
+      # type and appends the Binary entry. The bytes are duplicated and
+      # forced to ASCII-8BIT so msgpack-ruby picks the +bin+ family on
+      # the wire.
+      def register_binary!(bytes)
+        raise ArgumentError, "binary must be a String, got #{bytes.class}" unless bytes.is_a?(String)
+
+        @entries << Binary.new(body: bytes.dup.force_encoding(Encoding::ASCII_8BIT))
+        nil
+      end
+
+      # Build the msgpack-ready Hash for one entry. Source entries
+      # contribute their host-side +name+; Binary entries omit it
+      # because the canonical name lives in the bytecode's embedded
+      # +debug_info+ and is read by the guest at load time
+      # ({docs/wire-codec.md Invocation channels}[link:../../../docs/wire-codec.md]).
+      def entry_payload(entry)
+        case entry
+        when Source
+          { "name" => entry.name.to_s, "kind" => Source::KIND, "body" => entry.body }
+        when Binary
+          { "kind" => Binary::KIND, "body" => entry.body }
+        end
+      end
+
+      def normalize_name(name)
+        unless name.is_a?(Symbol) || name.is_a?(String)
+          raise ArgumentError, "snippet name must be a Symbol or String, got #{name.class}"
+        end
+
+        name_str = name.to_s
+        unless NAME_PATTERN.match?(name_str)
+          raise ArgumentError,
+                "snippet name must match #{NAME_PATTERN.inspect} (got #{name.inspect})"
+        end
+
+        name_str.to_sym
+      end
+    end
+  end
+end

data/lib/kobako/snippet.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+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
+  # ({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.
+  module Snippet
+  end
+end

data/lib/kobako/usage.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Kobako
+  # Per-last-invocation resource accounting for a +Kobako::Sandbox+
+  # ({docs/behavior.md B-35}[link:../../docs/behavior.md]). Carries two
+  # readers populated by every +#eval+ / +#run+ invocation:
+  #
+  #   * +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
+  #     ({docs/behavior.md B-01}[link:../../docs/behavior.md]); 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+ ({docs/behavior.md E-20}[link:../../docs/behavior.md]):
+  #     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.
+  #
+  # Both readers are populated on every outcome, including +TrapError+
+  # branches, so the Host App can read +Sandbox#usage+ after rescuing a
+  # trap to diagnose how much of the budget the failing invocation
+  # consumed. Before the first invocation +Sandbox#usage+ returns the
+  # pre-invocation sentinel +Kobako::Usage::EMPTY+.
+  #
+  # Built on the +class X < Data.define(...)+ subclass form so the
+  # class body is fully Steep-visible; ruby/rbs upstream documents this
+  # as the Steep-friendly shape and the +Style/DataInheritance+ cop is
+  # disabled on that basis (see +.rubocop.yml+).
+  class Usage < Data.define(:wall_time, :memory_peak)
+    # Pre-invocation sentinel ({docs/behavior.md B-35}[link:../../docs/behavior.md]).
+    # Reused by +Sandbox+ before any invocation has run so callers do not
+    # need to handle a +nil+ +#usage+.
+    EMPTY = new(wall_time: 0.0, memory_peak: 0)
+  end
+end

data/lib/kobako/version.rb

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

data/lib/kobako.rb

@@ -4,6 +4,7 @@ require_relative "kobako/version"
 require "kobako/kobako"
 require_relative "kobako/errors"
 require_relative "kobako/rpc"
+require_relative "kobako/rpc/wire_error"
 require_relative "kobako/rpc/server"
 require_relative "kobako/wasm"
 require_relative "kobako/sandbox"

data/sig/kobako/codec/factory.rbs

@@ -23,7 +23,7 @@ module Kobako
       def unpack_symbol: (String payload) -> Symbol
       def register_handle: () -> void
       def register_fault: () -> void
-      def unpack_handle: (String payload) -> Kobako::RPC::Handle
+      def unpack_handle: (String payload) -> Kobako::Handle
       def pack_fault: (Kobako::RPC::Fault fault) -> String
       def unpack_fault: (String payload) -> Kobako::RPC::Fault
     end

data/sig/kobako/codec/utils.rbs

@@ -1,9 +1,19 @@
 module Kobako
   module Codec
     module Utils
+      MSGPACK_INT_RANGE: Range[Integer]
+
       def self?.assert_utf8!: (String string, String label) -> void
 
       def self?.wire_boundary: [T] () { () -> T } -> T
+
+      def self?.wire_representable?: (untyped value) -> bool
+
+      def self?.deep_wrap: (untyped value, Kobako::HandleTable handle_table) -> untyped
+
+      def self?.primitive_wire_type?: (untyped value) -> bool
+
+      def self?.container_wire_representable?: (untyped value) -> bool
     end
   end
 end

data/sig/kobako/errors.rbs

@@ -49,4 +49,7 @@ module Kobako
 
   class HandleTableExhausted < HandleTableError
   end
+
+  class BytecodeError < SandboxError
+  end
 end

data/sig/kobako/handle.rbs

@@ -0,0 +1,19 @@
+module Kobako
+  class Handle
+    MIN_ID: Integer
+    MAX_ID: Integer
+
+    attr_reader id: Integer
+
+    def initialize: (Integer id) -> void
+                  | (id: Integer) -> void
+
+    def self.from_wire: (Integer id) -> Handle
+
+    def with: (?id: Integer) -> Handle
+
+    def ==: (untyped other) -> bool
+
+    def hash: () -> Integer
+  end
+end

data/sig/kobako/handle_table.rbs

@@ -0,0 +1,23 @@
+module Kobako
+  class HandleTable
+    def initialize: (?next_id: Integer) -> void
+
+    def alloc: (untyped object) -> Kobako::Handle
+
+    def fetch: (Integer id) -> untyped
+
+    def release: (Integer id) -> untyped
+
+    def reset!: () -> self
+
+    def mark_disconnected: (Integer id) -> self
+
+    def size: () -> Integer
+
+    def include?: (Integer id) -> bool
+
+    private
+
+    def require_bound!: (Integer id) -> void
+  end
+end

data/sig/kobako/invocation.rbs

@@ -0,0 +1,25 @@
+module Kobako
+  class Invocation < Data
+    NAME_PATTERN: Regexp
+
+    attr_reader entrypoint: Symbol
+    attr_reader args: Array[untyped]
+    attr_reader kwargs: Hash[Symbol, untyped]
+
+    def self.new: (entrypoint: Symbol | String, ?args: Array[untyped], ?kwargs: Hash[untyped, untyped]) -> Invocation
+
+    def initialize: (entrypoint: Symbol | String, ?args: Array[untyped], ?kwargs: Hash[untyped, untyped]) -> void
+
+    def encode: (Kobako::HandleTable handle_table) -> String
+
+    private
+
+    def normalize_entrypoint: (Symbol | String target) -> Symbol
+
+    def validate_args!: (Array[untyped] args) -> Array[untyped]
+
+    def validate_kwargs!: (Hash[untyped, untyped] kwargs) -> Hash[Symbol, untyped]
+
+    def forged_handle_message: (String slot) -> String
+  end
+end

data/sig/kobako/outcome.rbs

@@ -19,6 +19,6 @@ module Kobako
 
     def self?.panic_target_class: (Panic panic) -> (singleton(SandboxError) | singleton(ServiceError))
 
-    def self?.build_wire_violation_error: (String message) -> SandboxError
+    def self?.build_wire_violation_error: (String message, ?wire_error: String?) -> RPC::WireError
   end
 end

data/sig/kobako/rpc/dispatcher.rbs

@@ -7,25 +7,25 @@ module Kobako
       class DisconnectedTargetError < StandardError
       end
 
-      def self?.dispatch: (String request_bytes, Server server) -> String
+      def self?.dispatch: (String request_bytes, Server server, Kobako::HandleTable handle_table) -> String
 
       def self?.encode_caught_error: (StandardError error) -> String
 
       def self?.invoke: (untyped target, String method, Array[untyped] args, Hash[Symbol, untyped] kwargs) -> untyped
 
-      def self?.resolve_arg: (untyped value, HandleTable handle_table) -> untyped
+      def self?.resolve_arg: (untyped value, Kobako::HandleTable handle_table) -> untyped
 
-      def self?.resolve_target: (String | Kobako::RPC::Handle target, Server server, HandleTable handle_table) -> untyped
+      def self?.resolve_target: (String | Kobako::Handle target, Server server, Kobako::HandleTable handle_table) -> untyped
 
       def self?.resolve_path: (String path, Server server) -> untyped
 
-      def self?.resolve_handle: (Kobako::RPC::Handle handle, HandleTable handle_table) -> untyped
+      def self?.resolve_handle: (Kobako::Handle handle, Kobako::HandleTable handle_table) -> untyped
 
-      def self?.require_live_object!: (Integer id, HandleTable handle_table) -> untyped
+      def self?.require_live_object!: (Integer id, Kobako::HandleTable handle_table) -> untyped
 
-      def self?.encode_ok: (untyped value, Server server) -> String
+      def self?.encode_ok: (untyped value, Kobako::HandleTable handle_table) -> String
 
-      def self?.wrap_as_handle: (untyped value, Server server) -> Kobako::RPC::Handle
+      def self?.wrap_as_handle: (untyped value, Kobako::HandleTable handle_table) -> Kobako::Handle
 
       def self?.encode_error: (String type, String message) -> String
     end

data/sig/kobako/rpc/envelope.rbs

@@ -4,14 +4,14 @@ module Kobako
     STATUS_ERROR: Integer
 
     class Request
-      attr_reader target: String | Kobako::RPC::Handle
+      attr_reader target: String | Kobako::Handle
       attr_reader method_name: String
       attr_reader args: Array[untyped]
       attr_reader kwargs: Hash[Symbol, untyped]
 
-      def initialize: (target: String | Kobako::RPC::Handle, method: String, ?args: Array[untyped], ?kwargs: Hash[Symbol, untyped]) -> void
+      def initialize: (target: String | Kobako::Handle, method: String, ?args: Array[untyped], ?kwargs: Hash[Symbol, untyped]) -> void
 
-      def with: (?target: String | Kobako::RPC::Handle, ?method: String, ?args: Array[untyped], ?kwargs: Hash[Symbol, untyped]) -> Request
+      def with: (?target: String | Kobako::Handle, ?method: String, ?args: Array[untyped], ?kwargs: Hash[Symbol, untyped]) -> Request
 
       def ==: (untyped other) -> bool
 

data/sig/kobako/rpc/server.rbs

@@ -1,9 +1,7 @@
 module Kobako
   module RPC
     class Server
-      attr_reader handle_table: HandleTable
-
-      def initialize: (?handle_table: HandleTable) -> void
+      def initialize: (?handle_table: Kobako::HandleTable) -> void
 
       def define: (Symbol | String name) -> Kobako::RPC::Namespace
 
@@ -11,8 +9,6 @@ module Kobako
 
       def bound?: (String target) -> bool
 
-      def namespaces: () -> Array[Kobako::RPC::Namespace]
-
       def size: () -> Integer
 
       def empty?: () -> bool
@@ -25,8 +21,6 @@ module Kobako
 
       def sealed?: () -> bool
 
-      def reset_handles!: () -> HandleTable
-
       def dispatch: (String request_bytes) -> String
 
       private

data/sig/kobako/rpc/wire_error.rbs

@@ -0,0 +1,6 @@
+module Kobako
+  module RPC
+    class WireError < Kobako::SandboxError
+    end
+  end
+end

data/sig/kobako/sandbox.rbs

@@ -1,18 +1,18 @@
 module Kobako
   class Sandbox
-    DEFAULT_OUTPUT_LIMIT: Integer
-
-    DEFAULT_TIMEOUT_SECONDS: Float
-
-    DEFAULT_MEMORY_LIMIT: Integer
+    extend Forwardable
 
     attr_reader wasm_path: String
     attr_reader instance: Kobako::Wasm::Instance
-    attr_reader stdout_limit: Integer
-    attr_reader stderr_limit: Integer
-    attr_reader timeout: Float?
-    attr_reader memory_limit: Integer?
+    attr_reader options: Kobako::SandboxOptions
     attr_reader services: Kobako::RPC::Server
+    attr_reader snippets: Kobako::Snippet::Table
+
+    # Forwarded to @options via Forwardable#def_delegators.
+    def timeout: () -> Float?
+    def memory_limit: () -> Integer?
+    def stdout_limit: () -> Integer
+    def stderr_limit: () -> Integer
 
     def initialize: (
       ?wasm_path: String?,
@@ -30,24 +30,29 @@ module Kobako
 
     def stderr_truncated?: () -> bool
 
+    attr_reader usage: Kobako::Usage
+
     def define: (Symbol | String name) -> Kobako::RPC::Namespace
 
-    def run: (String source) -> untyped
+    def preload: (code: String, name: Symbol | String) -> Kobako::Sandbox
+               | (binary: String) -> Kobako::Sandbox
 
-    private
+    def run: (Symbol | String target, *untyped args, **untyped kwargs) -> untyped
 
-    def clear_captures!: () -> void
+    def eval: (String code) -> untyped
 
-    def normalize_timeout: ((Float | Integer)? timeout) -> Float?
+    private
 
-    def normalize_memory_limit: (Integer? memory_limit) -> Integer?
+    def reset_invocation_state!: () -> void
 
-    def reset_run_state!: () -> void
+    def begin_invocation!: () -> void
 
     def read_captures!: () -> void
 
-    def run_guest: (String preamble, String source) -> void
+    def read_usage!: () -> void
+
+    def trap_class_for: (Kobako::Wasm::Error err) -> singleton(Kobako::TrapError)
 
-    def take_result!: () -> untyped
+    def invoke!: (Symbol verb) { () -> void } -> untyped
   end
 end