kobako 0.5.0-x86_64-linux

data/lib/kobako/outcome/panic.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Kobako
+  module Outcome
+    # Wire-contract Outcome Envelope → Panic envelope ({docs/wire-contract.md
+    # Outcome Envelope}[link:../../../docs/wire-contract.md]). Wire-shaped failure record
+    # carried in the OUTCOME_BUFFER when the guest run terminates with
+    # an uncaught top-level exception.
+    #
+    # This is the **wire data**, not a raisable Ruby exception. The
+    # mapping from Panic to a three-layer Ruby exception (TrapError /
+    # SandboxError / ServiceError) happens at +Kobako::Outcome.decode+
+    # via +build_panic_error+ — callers never raise +Panic+ directly.
+    #
+    # The five fields mirror SPEC: +origin+ ("sandbox" / "service"),
+    # +klass+ (the guest-side exception class name as a String),
+    # +message+, +backtrace+ (Array of String), +details+ (any
+    # wire-legal value, nil when absent). Required-field validation is
+    # enforced at construction; the +ORIGIN_SANDBOX+ / +ORIGIN_SERVICE+
+    # constants pin the two SPEC-defined origin values.
+    #
+    # 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 Panic < Data.define(:origin, :klass, :message, :backtrace, :details)
+      ORIGIN_SANDBOX = "sandbox"
+      ORIGIN_SERVICE = "service"
+
+      def initialize(origin:, klass:, message:, backtrace: [], details: nil)
+        raise ArgumentError, "Panic origin must be String"  unless origin.is_a?(String)
+        raise ArgumentError, "Panic class must be String"   unless klass.is_a?(String)
+        raise ArgumentError, "Panic message must be String" unless message.is_a?(String)
+        unless backtrace.is_a?(Array) && backtrace.all?(String)
+          raise ArgumentError, "Panic backtrace must be Array of String"
+        end
+
+        super
+      end
+    end
+  end
+end

data/lib/kobako/outcome.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+require_relative "outcome/panic"
+require_relative "transport/error"
+
+module Kobako
+  # Host-facing boundary for the OUTCOME_BUFFER produced by
+  # +__kobako_eval+. Takes raw outcome bytes — a one-byte tag followed by
+  # the msgpack-encoded body — and maps them to either the unwrapped
+  # mruby return value or a raised three-layer
+  # ({docs/behavior.md Error Scenarios}[link:../../docs/behavior.md]) exception.
+  #
+  # Self-contained: this module owns the wire framing (tag bytes,
+  # body decoding), and the +Panic+ wire record lives at
+  # +Kobako::Outcome::Panic+. The byte-level msgpack codec at
+  # +Kobako::Codec+ is invoked for the body itself; otherwise
+  # nothing in +Transport+ participates.
+  #
+  #   * tag 0x01, decode OK                 → return decoded value
+  #   * tag 0x01, decode fails              → SandboxError (E-09)
+  #   * tag 0x02, origin="service"          → ServiceError (E-13)
+  #   * tag 0x02, origin="sandbox"/missing  → SandboxError (E-04..E-07)
+  #   * tag 0x02, decode fails              → SandboxError (E-08)
+  #   * unknown tag                         → TrapError    (E-03)
+  module Outcome
+    # First byte of the OUTCOME_BUFFER for the success branch — body is
+    # the bare msgpack encoding of the returned value
+    # ({docs/wire-contract.md Outcome Envelope}[link:../../docs/wire-contract.md]).
+    TYPE_VALUE = 0x01
+    # First byte of the OUTCOME_BUFFER for the failure branch — body is
+    # the msgpack Panic map.
+    TYPE_PANIC = 0x02
+
+    module_function
+
+    def decode(bytes)
+      tag, body = split_tag(bytes)
+      case tag
+      when TYPE_VALUE
+        decode_value(body)
+      when TYPE_PANIC
+        decode_panic(body)
+      else
+        raise build_trap_error(tag)
+      end
+    end
+
+    # TrapError for unknown or absent tag
+    # ({docs/wire-codec.md ABI Signatures}[link:../../docs/wire-codec.md]:
+    # zero-length output and unrecognised first byte both walk the trap
+    # path). The user-facing message stays in caller vocabulary — the
+    # raw tag byte (or absence) belongs in +details+ for operators, not
+    # in the message a caller sees.
+    def build_trap_error(tag)
+      if tag.nil?
+        TrapError.new("Sandbox exited without producing a result")
+      else
+        TrapError.new(
+          "Sandbox produced an unrecognised result; the runtime is corrupted, " \
+          "discard this Sandbox before another invocation"
+        )
+      end
+    end
+
+    def split_tag(bytes)
+      bytes = bytes.b
+      return [nil, "".b] if bytes.empty?
+
+      tag = bytes.getbyte(0) # : Integer
+      body = bytes.byteslice(1, bytes.bytesize - 1) # : String
+      [tag, body]
+    end
+
+    # Decode failure on the success tag is a SandboxError (E-09): the
+    # framing was fine, but the carried value is unrepresentable. The
+    # specific codec fault is stashed in +details+ rather
+    # than spliced into the message — callers cannot act on the inner
+    # "Symbol payload must be …" wording, but operators triaging a
+    # corrupted Sandbox runtime still need it.
+    def decode_value(body)
+      Kobako::Codec::Decoder.decode(body)
+    rescue Kobako::Codec::Error => e
+      raise build_transport_error(
+        "Sandbox produced an invalid result value",
+        detail: e.message
+      )
+    end
+
+    # Decode failure on the panic tag is a SandboxError (E-08). Either
+    # path raises — on success the decoded Panic is mapped to its three-
+    # layer exception via +build_panic_error+ and raised; on wire-decode
+    # failure the rescue path raises the wire-violation +SandboxError+.
+    def decode_panic(body)
+      raise build_panic_error(build_panic_record(body))
+    rescue Kobako::Codec::Error => e
+      raise build_transport_error(
+        "Sandbox produced an invalid panic record",
+        detail: e.message
+      )
+    end
+
+    # Build a +Panic+ value object from the msgpack-decoded body. Raises
+    # +Kobako::Codec::InvalidType+ when the body is not a map or when
+    # required keys are missing — both routed by +decode_panic+ to
+    # +build_transport_error+. The decode runs in block form so
+    # +Panic.new+'s +ArgumentError+ invariants surface as +InvalidType+
+    # through the decoder boundary; the message itself is never user-
+    # facing — it lands in +details+ via the rescue chain above.
+    def build_panic_record(body)
+      Kobako::Codec::Decoder.decode(body) do |map|
+        raise Kobako::Codec::InvalidType, "panic body must be a map, got #{map.class}" unless map.is_a?(Hash)
+
+        Panic.new(
+          origin: map["origin"], klass: map["class"], message: map["message"],
+          backtrace: map["backtrace"] || [], details: map["details"]
+        )
+      end
+    end
+
+    # Map a decoded Panic record into the corresponding three-layer
+    # Ruby exception. +origin == "service"+ → ServiceError; everything
+    # else → SandboxError.
+    def build_panic_error(panic)
+      panic_target_class(panic).new(
+        panic.message,
+        origin: panic.origin,
+        klass: panic.klass,
+        backtrace_lines: panic.backtrace,
+        details: panic.details
+      )
+    end
+
+    # {docs/behavior.md Error Scenarios}[link:../../docs/behavior.md]: map
+    # the panic +class+ field to the matching Ruby exception subclass so
+    # callers can rescue specific failure paths. +origin="service"+ →
+    # +ServiceError+; +origin="sandbox"+ plus
+    # +class="Kobako::BytecodeError"+ selects the +BytecodeError+
+    # subclass (E-37 / E-38). Everything else falls back to the base
+    # class for the origin.
+    def panic_target_class(panic)
+      case panic.origin
+      when Panic::ORIGIN_SERVICE
+        ServiceError
+      else
+        panic.klass == "Kobako::BytecodeError" ? BytecodeError : SandboxError
+      end
+    end
+
+    # Lift the wire-violation fallback to the real
+    # +Kobako::Transport::Error+ class so callers can +rescue+ it
+    # specifically instead of pattern-matching on +error.klass+. The
+    # +klass+ field is still populated so existing operator-side
+    # tooling that greps on the string continues to work.
+    # +detail+ carries the inner codec / framing message, stashed
+    # directly into +details+ for operator diagnosis without polluting
+    # the user-facing +#message+.
+    def build_transport_error(message, detail: nil)
+      Kobako::Transport::Error.new(
+        message,
+        origin: Panic::ORIGIN_SANDBOX,
+        klass: "Kobako::Transport::Error",
+        details: detail
+      )
+    end
+  end
+end

data/lib/kobako/runtime.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Kobako
+  # Host-side wasmtime runtime, surfaced as a Ruby class by the native ext
+  # (see ext/kobako/src/runtime.rs). The +Kobako::Runtime+ class wraps the
+  # wasmtime engine + compiled module + Store; it is the only Ruby-visible
+  # wasmtime type and the foundational binding layer for +Kobako::Sandbox+.
+  #
+  # This file reopens the magnus-defined class only to add the pure-Ruby
+  # +.default_path+ helper. Every other method (+#from_path+ singleton,
+  # +#eval+ / +#run+, capture and usage readers) is registered from Rust
+  # at ext load time.
+  class Runtime
+    # Absolute path to the gem-bundled +data/kobako.wasm+ artifact. Computed
+    # from this file's location so it works for both +bundle exec+ (running
+    # from the repo) and an installed gem (running from the gem dir).
+    #
+    # Returns a String regardless of whether the file currently exists —
+    # call sites that need the file to be present should pass this through
+    # +Kobako::Runtime.from_path+, which raises
+    # +Kobako::ModuleNotBuiltError+ with a clear remediation message.
+    # Raises +Kobako::SetupError+ if +__dir__+ is unavailable so that
+    # +rescue Kobako::SetupError+ around +Kobako::Sandbox.new+ catches every
+    # construction-layer failure uniformly, including this path-resolution one.
+    def self.default_path
+      dir = __dir__ or raise Kobako::SetupError, "Kobako::Runtime.default_path requires __dir__"
+      File.expand_path("../../data/kobako.wasm", dir)
+    end
+  end
+end

data/lib/kobako/sandbox.rb

@@ -0,0 +1,314 @@
+# frozen_string_literal: true
+
+require "forwardable"
+
+require_relative "capture"
+require_relative "errors"
+require_relative "outcome"
+require_relative "sandbox_options"
+require_relative "usage"
+require_relative "transport"
+require_relative "catalog"
+
+module Kobako
+  # Kobako::Sandbox — the user-facing entry point for executing guest mruby
+  # scripts inside a wasmtime-hosted Wasm module
+  # ({docs/behavior.md B-01}[link:../../docs/behavior.md]).
+  #
+  # The Sandbox owns the +Kobako::Runtime+, the per-Sandbox
+  # +Kobako::Catalog::Handles+ ({docs/behavior.md B-19}[link:../../docs/behavior.md]),
+  # the per-instance +Kobako::Catalog::Namespaces+ (which receives the
+  # +Catalog::Handles+ by injection so guest→host dispatch and host→guest
+  # auto-wrap share one allocator), and the dispatch +Proc+ /
+  # +yield_to_guest+ lambda installed on the Runtime via
+  # +Runtime#on_dispatch=+ ({docs/behavior.md B-12}[link:../../docs/behavior.md]).
+  # The underlying wasmtime Engine and compiled Module are cached at process
+  # scope by the native ext and never surface to Ruby — constructing many
+  # Sandboxes amortises both costs automatically.
+  #
+  # 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
+  # normally. +#stdout+ / +#stderr+ return the captured prefix as a UTF-8
+  # String; the byte content never carries a truncation sentinel.
+  # +#stdout_truncated?+ / +#stderr_truncated?+ are the only way to observe
+  # that the cap was hit.
+  class Sandbox
+    extend Forwardable
+
+    attr_reader :wasm_path, :options
+
+    # 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
+    # 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
+    # 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 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 invocation
+    # exceeded +stderr_limit+. Mirror of +#stdout_truncated?+.
+    def stderr_truncated?
+      @stderr_capture.truncated?
+    end
+
+    # Returns the +Kobako::Usage+ value object for the most recent
+    # invocation ({docs/behavior.md B-35}[link:../../docs/behavior.md]).
+    # Carries +wall_time+ (Float seconds the guest export call spent
+    # inside wasmtime) and +memory_peak+ (Integer bytes, high-water of
+    # the per-invocation +memory.grow+ delta past the entry-time
+    # baseline). Returns +Kobako::Usage::EMPTY+ before any invocation;
+    # populated on every outcome — including +TrapError+ — so the Host
+    # App can read it after rescuing a trap to diagnose budget
+    # consumption.
+    attr_reader :usage
+
+    # Build a fresh Sandbox.
+    #
+    # +wasm_path+ is the absolute path to the Guest Binary; defaults to the
+    # 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: SandboxOptions::DEFAULT_TIMEOUT_SECONDS,
+                   memory_limit: SandboxOptions::DEFAULT_MEMORY_LIMIT)
+      @wasm_path = wasm_path || Kobako::Runtime.default_path
+      @options = SandboxOptions.new(timeout: timeout, memory_limit: memory_limit, stdout_limit: stdout_limit,
+                                    stderr_limit: stderr_limit)
+      @handler = Catalog::Handles.new
+      @services = Kobako::Catalog::Namespaces.new(handler: @handler)
+      @snippets = Catalog::Snippets.new
+      @runtime = Kobako::Runtime.from_path(@wasm_path, @options.timeout, @options.memory_limit,
+                                           @options.stdout_limit, @options.stderr_limit)
+      install_dispatch_proc!
+      reset_invocation_state!
+    end
+
+    # Declare or retrieve the Namespace named +name+ on this Sandbox
+    # ({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::Namespace+.
+    #
+    # 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
+
+    # Register a snippet on this Sandbox in one of two forms
+    # ({docs/behavior.md B-32}[link:../../docs/behavior.md]):
+    #
+    #   * +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.
+    #
+    # 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
+
+    # Dispatch into a preloaded entrypoint constant
+    # ({docs/behavior.md B-31}[link:../../docs/behavior.md]). Delegates host
+    # pre-flight and wire encoding to +Kobako::Transport::Run+ /
+    # +Kobako::Transport::Run#encode+: a non-Symbol/String +target+ raises
+    # +TypeError+ (E-24), while a +target+ failing the constant pattern
+    # (E-25), a forged +Kobako::Handle+ in +args+ / +kwargs+ (E-29), or a
+    # non-Symbol +kwargs+ key (E-30) raise +ArgumentError+. 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)
+      run_envelope = Transport::Run.new(entrypoint: target, args: args, kwargs: kwargs)
+      invoke!(:run) do
+        @runtime.run(@services.encode, @snippets.encode, run_envelope.encode(@handler))
+      end
+    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)
+
+      invoke!(:eval) do
+        @runtime.eval(@services.encode, code.b, @snippets.encode)
+      end
+    end
+
+    private
+
+    # Configure the +Runtime+'s host↔guest dispatch wiring
+    # ({docs/behavior.md B-12}[link:../../docs/behavior.md]). Builds a
+    # lambda that re-enters the guest via
+    # +Runtime#yield_to_active_invocation+ (B-24) and a dispatch +Proc+
+    # that routes guest→host calls through the stateless
+    # +Transport::Dispatcher+, capturing +@services+ / +@handler+ in the
+    # closure. Both are registered on the +Runtime+ once at construction
+    # time so the wasm ext callback can fire without further setup.
+    def install_dispatch_proc!
+      yield_to_guest = ->(args_bytes) { @runtime.yield_to_active_invocation(args_bytes) }
+      @runtime.on_dispatch = lambda do |request_bytes|
+        Transport::Dispatcher.dispatch(request_bytes, @services, @handler, yield_to_guest)
+      end
+    end
+
+    # 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
+    # +Catalog::Handles+ counter — before the guest runs. The
+    # +Catalog::Handles+ itself is held as +@handler+ and never exposed beyond
+    # this class: SPEC.md Terminology pins it as "Not exposed to the
+    # Host App" (B-19 / B-20 / E-29).
+    def begin_invocation!
+      @services.seal!
+      @handler.reset!
+      reset_invocation_state!
+    end
+
+    # Reset all per-invocation observable state to its pre-invocation
+    # sentinels — both per-channel captures
+    # ({docs/behavior.md B-05}[link:../../docs/behavior.md]) and the
+    # per-last-invocation usage record
+    # ({docs/behavior.md B-35}[link:../../docs/behavior.md]). Shared by
+    # +#initialize+ (first-time setup) and +#begin_invocation!+
+    # (between-invocation reset) so both paths agree on what
+    # "pre-invocation state" means.
+    def reset_invocation_state!
+      @stdout_capture = Capture::EMPTY
+      @stderr_capture = Capture::EMPTY
+      @usage = Usage::EMPTY
+    end
+
+    # Read the per-last-invocation +wall_time+ and +memory_peak+ from
+    # the ext and wrap them as a +Kobako::Usage+ value object
+    # ({docs/behavior.md B-35}[link:../../docs/behavior.md]). Runs in
+    # the +invoke!+ +ensure+ block so the usage record is populated on
+    # every outcome — value return, +Kobako::TrapError+ (including
+    # +TimeoutError+ / +MemoryLimitError+), +Kobako::SandboxError+,
+    # and +Kobako::ServiceError+. On the success path the same figures
+    # already arrive via +Snapshot#usage+; on the trap path the Snapshot
+    # never reaches Ruby so the ext readout here is the only source.
+    #
+    # The ext returns a positional 2-tuple +[wall_time, memory_peak]+
+    # whose order matches the +Kobako::Usage+ field order; the
+    # destructure-then-kwargs handoff below is the explicit
+    # positional→keyword conversion point.
+    def read_usage!
+      wall_time, memory_peak = @runtime.usage
+      @usage = Usage.new(wall_time: wall_time, memory_peak: memory_peak)
+    end
+
+    # Pick the +TrapError+ subclass to re-raise based on +err+'s actual
+    # class. Cap-trap subclasses
+    # ({docs/behavior.md E-19 / E-20}[link:../../docs/behavior.md])
+    # preserve their named identity; everything else collapses to the
+    # base +Kobako::TrapError+. The ext already raises the right subclass
+    # directly, so this is a pure re-attribution that lets +#invoke!+
+    # add the verb prefix without erasing +TimeoutError+ /
+    # +MemoryLimitError+.
+    def trap_class_for(err)
+      case err
+      when TimeoutError     then TimeoutError
+      when MemoryLimitError then MemoryLimitError
+      else TrapError
+      end
+    end
+
+    # 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 yielded block must return a +Kobako::Snapshot+ — i.e. the
+    # value of +Runtime#eval+ / +#run+ (SPEC.md Internal Concepts →
+    # Snapshot). The success path unpacks every observable from the
+    # Snapshot in one go: +#stdout+ / +#stderr+ pack into +Capture+,
+    # +#usage+ packs into +Usage+, +#return_bytes+ feeds +Outcome.decode+.
+    # The rescue chain is the single trap-translation boundary —
+    # configured-cap paths
+    # ({docs/behavior.md E-19 / E-20}[link:../../docs/behavior.md])
+    # surface as named TrapError subclasses; everything else surfaces as
+    # the base +TrapError+.
+    def invoke!(verb)
+      begin_invocation!
+      snapshot = yield
+      @stdout_capture = snapshot.stdout
+      @stderr_capture = snapshot.stderr
+      Outcome.decode(snapshot.return_bytes)
+    rescue Kobako::TrapError => e
+      raise trap_class_for(e), "Sandbox##{verb} failed: #{e.message}"
+    ensure
+      read_usage!
+    end
+  end
+end

data/lib/kobako/sandbox_options.rb

@@ -0,0 +1,70 @@
+# 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::Runtime+ 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
+
+    def initialize(timeout: DEFAULT_TIMEOUT_SECONDS,
+                   memory_limit: DEFAULT_MEMORY_LIMIT,
+                   stdout_limit: nil,
+                   stderr_limit: nil)
+      timeout = normalize_timeout(timeout)
+      memory_limit = normalize_memory_limit(memory_limit)
+      stdout_limit ||= DEFAULT_OUTPUT_LIMIT
+      stderr_limit ||= DEFAULT_OUTPUT_LIMIT
+      super
+    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
+  end
+end

data/lib/kobako/snapshot.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative "capture"
+require_relative "usage"
+
+module Kobako
+  # Kobako::Snapshot — per-invocation observable bundle returned from
+  # +Kobako::Runtime#eval+ and +#run+.
+  #
+  # The magnus class (see ext/kobako/src/snapshot.rs) carries seven raw
+  # readers: +return_bytes+, +stdout_bytes+, +stdout_truncated+,
+  # +stderr_bytes+, +stderr_truncated+, +wall_time+, +memory_peak+. This
+  # file reopens the class to add the Ruby-side helpers that pack those
+  # raw fields into the user-facing value objects +Kobako::Capture+ and
+  # +Kobako::Usage+ — the same shape +Kobako::Sandbox+ exposes to the
+  # Host App.
+  class Snapshot
+    # Wrap the stdout capture pair (+stdout_bytes+, +stdout_truncated+)
+    # as a +Kobako::Capture+ value object. {docs/behavior.md
+    # B-04}[link:../../docs/behavior.md] — the byte content never carries
+    # a truncation sentinel; +#truncated?+ is the only way to observe
+    # that the cap was hit.
+    def stdout
+      Capture.new(bytes: stdout_bytes, truncated: stdout_truncated)
+    end
+
+    # Wrap the stderr capture pair as a +Kobako::Capture+ value object.
+    # Mirror of +#stdout+.
+    def stderr
+      Capture.new(bytes: stderr_bytes, truncated: stderr_truncated)
+    end
+
+    # Wrap the per-last-invocation usage pair (+wall_time+,
+    # +memory_peak+) as a +Kobako::Usage+ value object
+    # ({docs/behavior.md B-35}[link:../../docs/behavior.md]).
+    def usage
+      Usage.new(wall_time: wall_time, memory_peak: memory_peak)
+    end
+  end
+end