kobako 0.2.1 → 0.3.0

data/lib/kobako/rpc/handle_table.rb

@@ -7,20 +7,20 @@ module Kobako
     # Host-side mapping from opaque integer Handle IDs to Ruby objects
     # (capability proxies). One table is owned per +Kobako::RPC::Server+
     # instance (and therefore per +Kobako::Sandbox+ instance). See
-    # {SPEC.md B-15}[link:../../../SPEC.md].
+    # {docs/behavior.md B-15}[link:../../../docs/behavior.md].
     #
-    # Lifecycle invariants ({SPEC.md}[link:../../../SPEC.md]):
+    # Lifecycle invariants ({docs/behavior.md}[link:../../../docs/behavior.md]):
     #
-    #   - {SPEC.md B-15}[link:../../../SPEC.md] — Handle IDs are allocated by
+    #   - {docs/behavior.md B-15}[link:../../../docs/behavior.md] — Handle IDs are allocated by
     #     a monotonically increasing counter scoped to a single `#run`. The
     #     first ID issued in a run is 1; ID 0 is reserved as the invalid
     #     sentinel and is never returned by #alloc.
     #
-    #   - {SPEC.md B-19}[link:../../../SPEC.md] — When between `#run`
+    #   - {docs/behavior.md B-19}[link:../../../docs/behavior.md] — When between `#run`
     #     invocations (via `#reset!`), every Handle issued under the old state
     #     becomes invalid.
     #
-    #   - {SPEC.md B-21}[link:../../../SPEC.md] — The cap is `0x7fff_ffff`
+    #   - {docs/behavior.md B-21}[link:../../../docs/behavior.md] — The cap is `0x7fff_ffff`
     #     (2³¹ − 1). Allocation beyond the cap raises immediately — no silent
     #     truncation, no wrap, no ID reuse.
     class HandleTable
@@ -38,7 +38,7 @@ module Kobako
       # allocated Handle ID in +[1, RPC::Handle::MAX_ID]+. Raises
       # +Kobako::HandleTableExhausted+ if the next ID would exceed the cap.
       # The cap is anchored on +RPC::Handle+ — the wire codec and the
-      # allocator share the same invariant ({SPEC.md B-21}[link:../../../SPEC.md]).
+      # allocator share the same invariant ({docs/behavior.md B-21}[link:../../../docs/behavior.md]).
       def alloc(object)
         id = @next_id
         cap = RPC::Handle::MAX_ID
@@ -66,7 +66,7 @@ module Kobako
       end
 
       # Clear all entries AND reset the counter to 1. Called at the per-run
-      # boundary — see {SPEC.md B-19}[link:../../../SPEC.md].
+      # boundary — see {docs/behavior.md B-19}[link:../../../docs/behavior.md].
       # Returns +self+.
       def reset!
         @entries.clear

data/lib/kobako/rpc/namespace.rb

@@ -3,12 +3,12 @@
 module Kobako
   module RPC
     # A named grouping of Members for one Sandbox
-    # ({SPEC.md B-07..B-11}[link:../../../SPEC.md]). Returned by
+    # ({docs/behavior.md B-07..B-11}[link:../../../docs/behavior.md]). Returned by
     # +Sandbox#define+. Each instance owns a flat name→object table of
     # Members; member binding is validated against {NAME_PATTERN}.
     class Namespace
       # Ruby constant-name pattern shared by Namespace and Member names
-      # ({SPEC.md B-07/B-08 Notes}[link:../../../SPEC.md]).
+      # ({docs/behavior.md B-07/B-08 Notes}[link:../../../docs/behavior.md]).
       NAME_PATTERN = /\A[A-Z]\w*\z/
 
       attr_reader :name, :members
@@ -26,7 +26,7 @@ module Kobako
       # object that responds to the methods guest code will invoke. Returns
       # +self+ for chaining. Raises +ArgumentError+ when +member+ does not
       # match the constant pattern, or a Member of the same name is already
-      # bound ({SPEC.md B-11}[link:../../../SPEC.md]).
+      # bound ({docs/behavior.md B-11}[link:../../../docs/behavior.md]).
       def bind(member, object)
         member_str = validate_member_name!(member)
         raise ArgumentError, "Member #{@name}::#{member_str} is already bound" if @members.key?(member_str)

data/lib/kobako/rpc/server.rb

@@ -12,7 +12,7 @@ module Kobako
     # Kobako::RPC::Server — per-Sandbox host-side RPC coordinator. Maintains
     # the Namespace / Member registry, owns the HandleTable, and routes
     # incoming Requests to the resolved Service object
-    # ({SPEC.md B-07..B-21}[link:../../../SPEC.md]).
+    # ({docs/behavior.md B-07..B-21}[link:../../../docs/behavior.md]).
     #
     # Public API:
     #
@@ -39,14 +39,14 @@ module Kobako
         @sealed = false
       end
 
-      # Declare or retrieve the Namespace named +name+ (idempotent — SPEC.md B-10).
+      # Declare or retrieve the Namespace named +name+ (idempotent — docs/behavior.md B-10).
       # +name+ is a constant-form name as a +Symbol+ or +String+ (must satisfy
       # +Namespace::NAME_PATTERN+). Returns the +Kobako::RPC::Namespace+ for
       # that name, creating it if it does not exist. Raises +ArgumentError+
       # when +name+ is malformed, or when called after the owning Sandbox has
-      # been sealed by +#run+.
+      # been sealed by its first invocation ({docs/behavior.md B-07}[link:../../../docs/behavior.md]).
       def define(name)
-        raise ArgumentError, "cannot define after Sandbox#run has been invoked" if @sealed
+        raise ArgumentError, "cannot define after first Sandbox invocation" if @sealed
 
         name_str = name.to_s
         unless Namespace::NAME_PATTERN.match?(name_str)
@@ -91,8 +91,9 @@ module Kobako
         @namespaces.empty?
       end
 
-      # Structured Frame 1 description. Called by +Sandbox#run+ when assembling
-      # stdin Frame 1 ({SPEC.md B-02}[link:../../../SPEC.md]). Returns an
+      # Structured Frame 1 description. Called by +Sandbox#eval+ when
+      # assembling stdin Frame 1
+      # ({docs/behavior.md B-02}[link:../../../docs/behavior.md]). Returns an
       # unencoded preamble array — an +Array+ of two-element +[name, members]+
       # arrays, one per declared namespace.
       def to_preamble
@@ -100,7 +101,7 @@ module Kobako
       end
 
       # Encode the preamble as msgpack bytes for stdin Frame 1 delivery
-      # ({SPEC.md B-02}[link:../../../SPEC.md]). Uses plain MessagePack (no
+      # ({docs/behavior.md B-02}[link:../../../docs/behavior.md]). Uses plain MessagePack (no
       # kobako ext types) because the preamble contains only strings — no
       # Handles or Fault envelopes. Structure:
       # +[["Namespace", ["MemberA", "MemberB"]], ...]+. Returns a binary
@@ -109,8 +110,8 @@ module Kobako
         MessagePack.pack(to_preamble)
       end
 
-      # Mark the Server as sealed. Called by +Sandbox#run+ on first run.
-      # After sealing, #define raises ArgumentError. Idempotent.
+      # Mark the Server as sealed. Called by +Sandbox+ on the first
+      # invocation. After sealing, #define raises ArgumentError. Idempotent.
       def seal!
         @sealed = true
         self
@@ -121,14 +122,15 @@ module Kobako
         @sealed
       end
 
-      # Reset the HandleTable for a new +#run+ boundary. Called by +Sandbox#run+
-      # before each invocation ({SPEC.md B-19}[link:../../../SPEC.md]).
+      # Reset the HandleTable for a new invocation boundary. Called by
+      # +Sandbox+ before each invocation
+      # ({docs/behavior.md B-19}[link:../../../docs/behavior.md]).
       def reset_handles!
         @handle_table.reset!
       end
 
       # Dispatch a single RPC request and return the encoded response bytes
-      # ({SPEC.md B-12}[link:../../../SPEC.md]). +request_bytes+ is a
+      # ({docs/behavior.md B-12}[link:../../../docs/behavior.md]). +request_bytes+ is a
       # msgpack-encoded Request envelope. Called by the Rust ext from inside
       # +__kobako_dispatch+. Always returns a binary +String+ — never raises.
       # Delegates to +Dispatcher.dispatch+ which reifies any failure as a

data/lib/kobako/sandbox.rb

@@ -1,15 +1,20 @@
 # frozen_string_literal: true
 
+require "forwardable"
+
 require_relative "capture"
 require_relative "errors"
+require_relative "invocation"
 require_relative "outcome"
 require_relative "rpc/server"
 require_relative "rpc/envelope"
+require_relative "sandbox_options"
+require_relative "snippet"
 
 module Kobako
   # Kobako::Sandbox — the user-facing entry point for executing guest mruby
   # scripts inside a wasmtime-hosted Wasm module
-  # ({SPEC.md B-01}[link:../../SPEC.md]).
+  # ({docs/behavior.md B-01}[link:../../docs/behavior.md]).
   #
   # The Sandbox owns the +Kobako::Wasm::Instance+, the per-instance RPC Server
   # (which itself owns the per-run HandleTable), and the per-channel byte
@@ -18,7 +23,7 @@ module Kobako
   # never surface to Ruby — constructing many Sandboxes amortises both costs
   # automatically.
   #
-  # Output capture policy ({SPEC.md B-04}[link:../../SPEC.md]): the
+  # Output capture policy ({docs/behavior.md B-04}[link:../../docs/behavior.md]): the
   # per-channel cap (+stdout_limit+ / +stderr_limit+) is enforced inside the
   # WASI pipe — the host buffer stops growing at the cap, subsequent guest
   # writes on that channel fail or are dropped, and +#run+ still returns
@@ -27,47 +32,41 @@ module Kobako
   # +#stdout_truncated?+ / +#stderr_truncated?+ are the only way to observe
   # that the cap was hit.
   class Sandbox
-    # Default per-channel capture ceiling: 1 MiB
-    # ({SPEC.md B-01}[link:../../SPEC.md]).
-    DEFAULT_OUTPUT_LIMIT = 1 << 20
-
-    # Default wall-clock timeout for a single +#run+: 60 seconds
-    # ({SPEC.md B-01}[link:../../SPEC.md]).
-    DEFAULT_TIMEOUT_SECONDS = 60.0
-
-    # Default cap on guest linear memory growth: 5 MiB
-    # ({SPEC.md B-01}[link:../../SPEC.md]).
-    DEFAULT_MEMORY_LIMIT = 5 << 20
+    extend Forwardable
 
     attr_reader :wasm_path, :instance,
-                :stdout_limit, :stderr_limit,
-                :timeout, :memory_limit, :services
+                :options,
+                :services, :snippets
+
+    # Per-cap accessors forward to the immutable +SandboxOptions+ Value
+    # Object so the Host App still reads them off Sandbox directly.
+    def_delegators :@options, :timeout, :memory_limit, :stdout_limit, :stderr_limit
 
     # Returns the bytes the guest wrote to stdout during the most recent
-    # +#run+ as a UTF-8 String, clipped at +stdout_limit+. Empty before any
-    # +#run+ call. {SPEC.md B-04}[link:../../SPEC.md] — the byte content
-    # never contains a truncation sentinel; use +#stdout_truncated?+ to
+    # invocation as a UTF-8 String, clipped at +stdout_limit+. Empty before
+    # any invocation. {docs/behavior.md B-04}[link:../../docs/behavior.md] — the byte
+    # content never contains a truncation sentinel; use +#stdout_truncated?+ to
     # observe overflow.
     def stdout
       @stdout_capture.bytes
     end
 
     # Returns the bytes the guest wrote to stderr during the most recent
-    # +#run+ as a UTF-8 String, clipped at +stderr_limit+. Empty before any
-    # +#run+ call. Mirror of +#stdout+.
+    # invocation as a UTF-8 String, clipped at +stderr_limit+. Empty before
+    # any invocation. Mirror of +#stdout+.
     def stderr
       @stderr_capture.bytes
     end
 
-    # Returns +true+ iff stdout capture during the most recent +#run+
-    # exceeded +stdout_limit+ ({SPEC.md B-04}[link:../../SPEC.md]). Resets
-    # to +false+ at the start of the next +#run+ ({SPEC.md
-    # B-03}[link:../../SPEC.md]).
+    # Returns +true+ iff stdout capture during the most recent invocation
+    # exceeded +stdout_limit+ ({docs/behavior.md B-04}[link:../../docs/behavior.md]). Resets
+    # to +false+ at the start of the next invocation
+    # ({docs/behavior.md B-03}[link:../../docs/behavior.md]).
     def stdout_truncated?
       @stdout_capture.truncated?
     end
 
-    # Returns +true+ iff stderr capture during the most recent +#run+
+    # Returns +true+ iff stderr capture during the most recent invocation
     # exceeded +stderr_limit+. Mirror of +#stdout_truncated?+.
     def stderr_truncated?
       @stderr_capture.truncated?
@@ -76,115 +75,148 @@ module Kobako
     # Build a fresh Sandbox.
     #
     # +wasm_path+ is the absolute path to the Guest Binary; defaults to the
-    # gem-bundled +data/kobako.wasm+. +stdout_limit+ and +stderr_limit+ cap
-    # the per-run byte ceiling for each capture channel (default 1 MiB;
-    # +nil+ disables the cap). +timeout+ is the wall-clock cap on a single
-    # +#run+ in seconds ({SPEC.md B-01}[link:../../SPEC.md]; default 60.0,
-    # +nil+ disables); +memory_limit+ caps guest linear memory growth in
-    # bytes ({SPEC.md B-01, E-20}[link:../../SPEC.md]; default 5 MiB,
-    # +nil+ disables).
+    # gem-bundled +data/kobako.wasm+. The four caps (+stdout_limit+,
+    # +stderr_limit+, +timeout+, +memory_limit+) are forwarded verbatim to
+    # +Kobako::SandboxOptions+, which owns their DEFAULT fallback and
+    # normalisation. The constructed +SandboxOptions+ is exposed as
+    # +#options+ and the four caps remain readable directly on Sandbox via
+    # +Forwardable+ delegation.
     def initialize(wasm_path: nil, stdout_limit: nil, stderr_limit: nil,
-                   timeout: DEFAULT_TIMEOUT_SECONDS,
-                   memory_limit: DEFAULT_MEMORY_LIMIT)
+                   timeout: SandboxOptions::DEFAULT_TIMEOUT_SECONDS,
+                   memory_limit: SandboxOptions::DEFAULT_MEMORY_LIMIT)
       @wasm_path = wasm_path || Kobako::Wasm.default_path
-      @stdout_limit = stdout_limit || DEFAULT_OUTPUT_LIMIT
-      @stderr_limit = stderr_limit || DEFAULT_OUTPUT_LIMIT
-      @timeout = normalize_timeout(timeout)
-      @memory_limit = normalize_memory_limit(memory_limit)
+      @options = SandboxOptions.new(timeout: timeout, memory_limit: memory_limit, stdout_limit: stdout_limit,
+                                    stderr_limit: stderr_limit)
       @services = Kobako::RPC::Server.new
-      @instance = Kobako::Wasm::Instance.from_path(@wasm_path, @timeout, @memory_limit, @stdout_limit, @stderr_limit)
+      @snippets = Snippet::Table.new
+      @instance = Kobako::Wasm::Instance.from_path(@wasm_path, @options.timeout, @options.memory_limit,
+                                                   @options.stdout_limit, @options.stderr_limit)
       @instance.server = @services
       clear_captures!
     end
 
     # Declare or retrieve the Namespace named +name+ on this Sandbox
-    # ({SPEC.md B-07, B-09, B-10}[link:../../SPEC.md]). +name+ must be a
+    # ({docs/behavior.md B-07, B-09, B-10}[link:../../docs/behavior.md]). +name+ must be a
     # Symbol or String in constant form. Returns the +Kobako::RPC::Namespace+.
     #
-    # Raises +ArgumentError+ when called after +#run+, or when +name+ does
-    # not match the constant-name pattern.
+    # Raises +ArgumentError+ when called after the first invocation, or
+    # when +name+ does not match the constant-name pattern.
     def define(name)
       @services.define(name)
     end
 
-    # Execute a guest mruby script
-    # ({SPEC.md B-02 / B-03}[link:../../SPEC.md]). +source+ is the mruby
-    # source code as a UTF-8 String. Returns the deserialized last
-    # expression of the script.
+    # Register a snippet on this Sandbox in one of two forms
+    # ({docs/behavior.md B-32}[link:../../docs/behavior.md]):
     #
-    # Source delivery uses the WASI stdin two-frame protocol
-    # ({SPEC.md ABI Signatures}[link:../../SPEC.md]): Frame 1 carries the
-    # msgpack-encoded preamble (Namespace / Member registry snapshot) and Frame 2
-    # carries the user script UTF-8 bytes. Each frame is prefixed by a
-    # 4-byte big-endian u32 length.
+    #   * +preload(code: source, name: Name)+ — +source+ is mruby source
+    #     as a +String+ and +Name+ matches +/\A[A-Z]\w*\z/+. The +name+
+    #     becomes the snippet's +(snippet:Name)+ backtrace filename and
+    #     is the dedupe key for E-33.
+    #   * +preload(binary: bytes)+ — +bytes+ is precompiled RITE
+    #     bytecode as a +String+. The canonical name, when present,
+    #     lives in the bytecode's embedded +debug_info+ and is resolved
+    #     by the guest at load time; the host treats the bytes as
+    #     opaque. Structural failures
+    #     ({docs/behavior.md E-37 / E-38}[link:../../docs/behavior.md])
+    #     surface as +Kobako::BytecodeError+ on the first invocation.
     #
-    # Raises +Kobako::TrapError+ on a Wasm trap or wire-violation fallback;
-    # +Kobako::SandboxError+ when the guest ran to completion but failed;
-    # +Kobako::ServiceError+ on an unrescued Service capability failure.
-    def run(source)
-      raise SandboxError, "source must be a String, got #{source.class}" unless source.is_a?(String)
-
-      @services.seal!
-      reset_run_state!
-
-      run_guest(@services.encoded_preamble, source.b)
-      read_captures!
-      take_result!
+    # Subsequent invocations (+#eval+ or +#run+) replay every registered
+    # snippet — in insertion order — against the fresh +mrb_state+
+    # before per-invocation source or entrypoint resolution.
+    #
+    # Returns +self+ to allow chaining.
+    #
+    # Raises +ArgumentError+ when neither form's keyword set is
+    # supplied, when both forms are mixed (e.g., +code:+ and +binary:+
+    # together, or +binary:+ paired with +name:+), when +code+ / +bytes+
+    # is not a +String+, when +name+ does not match the constant
+    # pattern ({docs/behavior.md E-34}[link:../../docs/behavior.md]),
+    # when +name+ duplicates an already-registered +code:+ form snippet
+    # ({docs/behavior.md E-33}[link:../../docs/behavior.md]), or when
+    # called after the first invocation
+    # ({docs/behavior.md E-35, B-33}[link:../../docs/behavior.md]).
+    def preload(code: nil, name: nil, binary: nil)
+      raise ArgumentError, "cannot preload after first Sandbox invocation" if @services.sealed?
+
+      @snippets.register(code: code, name: name, binary: binary)
+      self
     end
 
-    private
-
-    # Coerce +timeout+ into the Float seconds the ext expects, or +nil+ to
-    # mean the cap is disabled ({SPEC.md B-01}[link:../../SPEC.md]). 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
+    # Dispatch into a preloaded entrypoint constant
+    # ({docs/behavior.md B-31}[link:../../docs/behavior.md]). Delegates host
+    # pre-flight (E-24 / E-25 / E-29 / E-30) and wire encoding to
+    # +Kobako::Invocation+ / +Kobako::Invocation#encode+; the guest
+    # resolves +target+ as a top-level constant, calls +#call+ on it
+    # with +args+ / +kwargs+, and returns the deserialized result. The
+    # first invocation seals the Service registry and snippet table
+    # (B-07 / B-33). Runtime errors follow the same three-class taxonomy
+    # as +#eval+.
+    def run(target, *args, **kwargs)
+      invocation = Invocation.new(entrypoint: target, args: args, kwargs: kwargs)
+      invoke!(:run) do
+        @instance.run(@services.encoded_preamble, @snippets.encode, invocation.encode)
+      end
     end
 
-    # Coerce +memory_limit+ into the byte cap the ext expects, or +nil+ to
-    # mean unbounded ({SPEC.md B-01, E-20}[link:../../SPEC.md]). 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
+    # Execute a guest mruby source string in a fresh +mrb_state+
+    # ({docs/behavior.md B-02 / B-03 / B-06}[link:../../docs/behavior.md]). +code+ is the
+    # mruby source as a UTF-8 String. Returns the deserialized last
+    # expression of the source.
+    #
+    # Source delivery uses the WASI stdin three-frame protocol
+    # ({docs/wire-codec.md Invocation channels}[link:../../docs/wire-codec.md]):
+    # Frame 1 carries the msgpack-encoded preamble (Namespace / Member
+    # registry snapshot), Frame 2 carries the user source UTF-8 bytes, and
+    # Frame 3 carries the snippet table registered via +#preload+ (B-32).
+    # Each frame is prefixed by a 4-byte big-endian u32 length; Frame 3 is
+    # mandatory-presence — an empty snippet table sends an empty msgpack
+    # array, never an absent frame.
+    #
+    # The first invocation seals the Service registry and snippet table
+    # ({docs/behavior.md B-07 / B-33}[link:../../docs/behavior.md]); subsequent
+    # +#define+ / +#preload+ calls raise +ArgumentError+.
+    #
+    # Raises +Kobako::TrapError+ on a Wasm trap or wire-violation fallback;
+    # +Kobako::SandboxError+ when the guest ran to completion but failed
+    # (including when +code+ is +nil+ or not a String, or when a preloaded
+    # snippet's replay raises — E-36);
+    # +Kobako::ServiceError+ on an unrescued Service capability failure.
+    def eval(code)
+      raise SandboxError, "code must be a String, got #{code.class}" unless code.is_a?(String)
 
-      memory_limit
+      invoke!(:eval) do
+        @instance.eval(@services.encoded_preamble, code.b, @snippets.encode)
+      end
     end
 
-    # Per-run state reset ({SPEC.md B-03}[link:../../SPEC.md]). Capture
-    # buffers, truncation predicates, and the HandleTable counter are
-    # zeroed before the guest runs.
-    def reset_run_state!
+    private
+
+    # Per-invocation prologue ({docs/behavior.md B-03 / B-07 /
+    # B-33}[link:../../docs/behavior.md]). Seals the Service / snippet
+    # registries on first call (idempotent) and zeros the per-invocation
+    # capability state — capture buffers, truncation predicates, and the
+    # HandleTable counter — before the guest runs.
+    def begin_invocation!
+      @services.seal!
       @services.reset_handles!
       clear_captures!
     end
 
-    # Reset both per-channel captures to the pre-run sentinel
-    # ({SPEC.md B-05}[link:../../SPEC.md]). Shared by +#initialize+
-    # (first-run setup) and +#reset_run_state!+ (between-run reset) so
-    # both paths agree on what "empty capture" means.
+    # Reset both per-channel captures to the pre-invocation sentinel
+    # ({docs/behavior.md B-05}[link:../../docs/behavior.md]). Shared by +#initialize+
+    # (first-time setup) and +#begin_invocation!+ (between-invocation
+    # reset) so both paths agree on what "empty capture" means.
     def clear_captures!
       @stdout_capture = Capture::EMPTY
       @stderr_capture = Capture::EMPTY
     end
 
     # Read the per-channel capture pairs (+[bytes, truncated]+) from the
-    # ext after a guest run completes and wrap each as a +Capture+ value
+    # ext after an invocation completes and wrap each as a +Capture+ value
     # object. The ext clips +bytes+ to the configured cap and sets
     # +truncated+ when the guest produced strictly more than +cap+ bytes
-    # ({SPEC.md B-04}[link:../../SPEC.md]). Mirror of {#clear_captures!}
-    # at the post-run boundary.
+    # ({docs/behavior.md B-04}[link:../../docs/behavior.md]). Mirror of {#clear_captures!}
+    # at the post-invocation boundary.
     def read_captures!
       out_bytes, out_truncated = @instance.stdout
       err_bytes, err_truncated = @instance.stderr
@@ -192,37 +224,27 @@ module Kobako
       @stderr_capture = Capture.from_ext(err_bytes, err_truncated)
     end
 
-    # Drive +Instance#run+ with the two stdin frames (preamble + source).
-    # Wraps wasmtime / wire errors in TrapError so the Sandbox layer maps
-    # cleanly to the three-class taxonomy. The configured-cap paths
-    # (SPEC.md E-19 / E-20) are routed to the named TrapError subclasses
-    # so callers that want to surface a specific reason can rescue them;
-    # everything else falls through to the base TrapError.
-    def run_guest(preamble, source)
-      @instance.run(preamble, source)
+    # Shared prologue / epilogue + trap-class translator for both
+    # invocation verbs. +verb+ is +:eval+ or +:run+; it tags the
+    # TrapError message so the failing export is identifiable. The
+    # rescue chain is the single trap-translation boundary — wasmtime /
+    # wire failures from the guest call and from the subsequent
+    # +Instance#outcome!+ read both flow through here, so an
+    # OUTCOME_BUFFER read failure attributes to the same export name as
+    # the guest call itself. Configured-cap paths
+    # ({docs/behavior.md E-19 / E-20}[link:../../docs/behavior.md]) surface as
+    # named TrapError subclasses.
+    def invoke!(verb)
+      begin_invocation!
+      yield
+      read_captures!
+      Outcome.decode(@instance.outcome!)
     rescue Kobako::Wasm::TimeoutError => e
       raise TimeoutError, "guest exceeded timeout: #{e.message}"
     rescue Kobako::Wasm::MemoryLimitError => e
       raise MemoryLimitError, "guest exceeded memory_limit: #{e.message}"
     rescue Kobako::Wasm::Error => e
-      raise TrapError, "guest __kobako_run trapped: #{e.message}"
-    end
-
-    # Take OUTCOME_BUFFER bytes from guest memory via +Instance#outcome!+
-    # and decode them into the Sandbox-level result — the unwrapped mruby
-    # return value, or a raised three-layer
-    # ({SPEC.md "Error Scenarios"}[link:../../SPEC.md]) exception. A zero-
-    # length outcome is delivered to +Kobako::Outcome+ as an empty String
-    # so a single boundary attributes every wire-violation outcome
-    # ({SPEC.md ABI Signatures}[link:../../SPEC.md]).
-    #
-    # The bang reflects the destructive ext call beneath: the underlying
-    # +__kobako_take_outcome+ export invalidates the buffer pointer, so this
-    # method must be called at most once per +#run+.
-    def take_result!
-      Outcome.decode(@instance.outcome!)
-    rescue Kobako::Wasm::Error => e
-      raise TrapError, "failed to read OUTCOME_BUFFER: #{e.message}"
+      raise TrapError, "guest __kobako_#{verb} trapped: #{e.message}"
     end
   end
 end

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