kobako 0.2.1 → 0.4.0

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

@@ -4,7 +4,7 @@ require "msgpack"
 require_relative "../errors"
 require_relative "envelope"
 require_relative "namespace"
-require_relative "handle_table"
+require_relative "../handle_table"
 require_relative "dispatcher"
 
 module Kobako
@@ -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:
     #
@@ -24,10 +24,11 @@ module Kobako
     #
     # Namespaces live at +Kobako::RPC::Namespace+
     # (lib/kobako/rpc/namespace.rb). The opaque Handle allocator lives at
-    # +Kobako::RPC::HandleTable+
-    # (lib/kobako/rpc/handle_table.rb). Dispatch helpers live at
-    # +Kobako::RPC::Dispatcher+
-    # (lib/kobako/rpc/dispatcher.rb).
+    # +Kobako::HandleTable+ (lib/kobako/handle_table.rb) and is owned by
+    # the Sandbox — the Server only holds an injected reference so RPC
+    # dispatch resolves against the same table the wire layer allocates
+    # into (docs/behavior.md B-19). Dispatch helpers live at
+    # +Kobako::RPC::Dispatcher+ (lib/kobako/rpc/dispatcher.rb).
     class Server
       # Build a fresh Server. +handle_table+ is an internal seam that
       # injects a pre-configured +HandleTable+; tests pass one whose +next_id+
@@ -39,14 +40,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)
@@ -76,11 +77,6 @@ module Kobako
         !namespace.nil? && !member_name.nil? && !namespace[member_name].nil?
       end
 
-      # Returns all declared +Kobako::RPC::Namespace+ instances as an +Array+.
-      def namespaces
-        @namespaces.values
-      end
-
       # Returns the number of declared namespaces as an +Integer+.
       def size
         @namespaces.size
@@ -91,8 +87,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 +97,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 +106,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,26 +118,19 @@ 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]).
-      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
-      # +Response.error+ envelope so the guest sees the failure as a normal RPC
-      # error rather than a wasm trap.
+      # Forwards both the Server (for namespace lookup) and the injected
+      # +HandleTable+ (for Handle resolution / return-value wrapping) to
+      # +Dispatcher.dispatch+. The Server holds the HandleTable as an
+      # injected reference, not an owned resource — the Sandbox owns it
+      # (B-19) — so the table is not exposed via accessors.
       def dispatch(request_bytes)
-        Dispatcher.dispatch(request_bytes, self)
+        Dispatcher.dispatch(request_bytes, self, @handle_table)
       end
 
-      # Expose the +HandleTable+ for tests and wire-layer Handle wrapping.
-      attr_reader :handle_table
-
       private
 
       # Split +target+ on the +::+ separator and resolve the namespace half.

data/lib/kobako/rpc/wire_error.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require_relative "../errors"
+
+module Kobako
+  module RPC
+    # +Kobako::SandboxError+ subclass raised when the host detects a
+    # structural violation of the wire contract while decoding bytes
+    # produced by the guest (a malformed Outcome envelope, a result body
+    # that fails msgpack decode, a Panic envelope missing required
+    # fields). Distinct from a Wasm trap (engine signalled the guest
+    # runtime is unrecoverable) and from a normal sandbox-layer failure
+    # (the script raised but the protocol was respected): a +WireError+
+    # always indicates the guest runtime is corrupted — the only safe
+    # recovery is to discard the Sandbox and start a new invocation.
+    #
+    # Inherits from +Kobako::SandboxError+ so a single
+    # +rescue Kobako::SandboxError+ still catches it; callers that want
+    # to distinguish wire-violation paths from script failures can
+    # +rescue Kobako::RPC::WireError+ directly.
+    class WireError < Kobako::SandboxError; end
+  end
+end

data/lib/kobako/sandbox.rb

@@ -1,24 +1,33 @@
 # frozen_string_literal: true
 
+require "forwardable"
+
 require_relative "capture"
 require_relative "errors"
+require_relative "handle_table"
+require_relative "invocation"
 require_relative "outcome"
 require_relative "rpc/server"
 require_relative "rpc/envelope"
+require_relative "sandbox_options"
+require_relative "snippet"
+require_relative "usage"
 
 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
-  # caches for guest stdout / stderr capture. 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.
+  # The Sandbox owns the +Kobako::Wasm::Instance+, the per-Sandbox
+  # +Kobako::HandleTable+ ({docs/behavior.md B-19}[link:../../docs/behavior.md]),
+  # the per-instance RPC Server (which receives the HandleTable by
+  # injection so guest→host dispatch and host→guest auto-wrap share one
+  # allocator), and the per-channel byte caches for guest stdout / stderr
+  # capture. 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 ({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,164 +36,211 @@ 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?
     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+. +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)
-      @services = Kobako::RPC::Server.new
-      @instance = Kobako::Wasm::Instance.from_path(@wasm_path, @timeout, @memory_limit, @stdout_limit, @stderr_limit)
+      @options = SandboxOptions.new(timeout: timeout, memory_limit: memory_limit, stdout_limit: stdout_limit,
+                                    stderr_limit: stderr_limit)
+      @handle_table = HandleTable.new
+      @services = Kobako::RPC::Server.new(handle_table: @handle_table)
+      @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!
+      reset_invocation_state!
     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!
+    # 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?
 
-      run_guest(@services.encoded_preamble, source.b)
-      read_captures!
-      take_result!
+      @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(@handle_table))
+      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!
-      @services.reset_handles!
-      clear_captures!
+    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. The HandleTable
+    # itself is held as +@handle_table+ 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!
+      @handle_table.reset!
+      reset_invocation_state!
     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.
-    def clear_captures!
+    # 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-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
+    # {#reset_invocation_state!} at the post-invocation boundary.
     def read_captures!
       out_bytes, out_truncated = @instance.stdout
       err_bytes, err_truncated = @instance.stderr
@@ -192,37 +248,56 @@ 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)
-    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}"
+    # 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+.
+    #
+    # 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, mirroring
+    # +#read_captures!+'s +Capture.from_ext(bytes, truncated)+ shape.
+    def read_usage!
+      wall_time, memory_peak = @instance.usage
+      @usage = Usage.new(wall_time: wall_time, memory_peak: memory_peak)
     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!
+    # Map a wasmtime trap class to the matching three-layer Ruby
+    # exception class. Cap-trap subclasses
+    # ({docs/behavior.md E-19 / E-20}[link:../../docs/behavior.md])
+    # select their named +TrapError+ subclass; everything else
+    # collapses to the base +Kobako::TrapError+.
+    def trap_class_for(err)
+      case err
+      when Kobako::Wasm::TimeoutError     then TimeoutError
+      when Kobako::Wasm::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
+    # 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::Error => e
-      raise TrapError, "failed to read OUTCOME_BUFFER: #{e.message}"
+      raise trap_class_for(e), "Sandbox##{verb} failed: #{e.message}"
+    ensure
+      read_usage!
     end
   end
 end