kobako 0.12.2 → 0.14.0

data/lib/kobako/errors.rb

@@ -4,38 +4,13 @@
 module Kobako
   # Error taxonomy.
   #
-  # Every `Kobako::Sandbox` invocation (`#eval` or `#run`) either returns a value or raises
-  # exactly one of three invocation-outcome classes. Attribution is decided after the
-  # guest binary returns control to the host: first the Wasm-trap layer, then
-  # the outcome-envelope tag.
-  #
-  # Three invocation-outcome branches:
-  #
-  #   * {TrapError}     — Wasm engine layer (trap, OOM, unreachable, or a
-  #                       wire-violation fallback signalling a corrupted
-  #                       guest runtime).
-  #   * {SandboxError}  — sandbox / wire layer (mruby script error,
-  #                       wire-decode failure on an otherwise valid tag,
-  #                       Catalog::Handles exhaustion, output buffer overrun).
-  #   * {ServiceError}  — service / capability layer (a Service capability
-  #                       call that failed and was not rescued inside the
-  #                       script).
-  #
-  # Two further branches sit outside the invocation taxonomy:
-  #
-  #   * {SetupError}    — construction layer. Raised by `Kobako::Sandbox.new`
-  #                       when the wasm runtime cannot be built from the
-  #                       configured +wasm_path+ before any invocation runs.
-  #                       Not an invocation outcome, so it never passes
-  #                       through the two-step attribution decision.
-  #   * {PoolTimeoutError} — pool checkout layer. Raised by `Kobako::Pool#with`
-  #                       when the checkout wait exceeds +checkout_timeout+.
-  #
-  # Named subclasses:
-  #
-  #   * {ModuleNotBuiltError} < {SetupError} — Guest Binary artifact absent
-  #                       at +wasm_path+.
-  #   * {HandleExhaustedError} < {SandboxError} — Handle id cap hit.
+  # Every +Kobako::Sandbox+ invocation (+#eval+ or +#run+) either returns a
+  # value or raises exactly one of TrapError, SandboxError, or ServiceError.
+  # Attribution is decided after the guest binary returns control to the
+  # host: first the Wasm-trap layer, then the outcome-envelope tag.
+  # SetupError and PoolTimeoutError sit outside the invocation taxonomy and
+  # never pass through that attribution decision. Each class below
+  # documents its own layer.
 
   # Base for all kobako-raised errors so callers that want to ignore the
   # taxonomy can rescue a single class.
@@ -48,8 +23,8 @@ module Kobako
   #
   # Two named subclasses cover the configured per-invocation caps:
   #
-  #   * {TimeoutError}     — wall-clock +timeout+ exceeded.
-  #   * {MemoryLimitError} — guest +memory.grow+ would exceed
+  #   * TimeoutError     — wall-clock +timeout+ exceeded.
+  #   * MemoryLimitError — guest +memory.grow+ would exceed
   #                          +memory_limit+.
   #
   # Host Apps that only care about "guest is unrecoverable, discard the
@@ -128,14 +103,14 @@ module Kobako
   class HandleExhaustedError < SandboxError; end
 
   # BytecodeError is the SandboxError subclass raised when a
-  # `#preload(binary:)` snippet fails structural validation during the
-  # first invocation's snippet replay against a fresh `mrb_state` (RITE
+  # +#preload(binary:)+ snippet fails structural validation during the
+  # first invocation's snippet replay against a fresh +mrb_state+ (RITE
   # version mismatch or corrupt body). Bytecode that loads cleanly and
-  # then raises at top level surfaces as plain `SandboxError` with the
+  # then raises at top level surfaces as plain +SandboxError+ with the
   # natural mruby class preserved. Inherits from SandboxError so a single
-  # `rescue Kobako::SandboxError` covers both source and bytecode
+  # +rescue Kobako::SandboxError+ covers both source and bytecode
   # snippet failures while callers wanting bytecode-specific handling
-  # can `rescue Kobako::BytecodeError` directly.
+  # can +rescue Kobako::BytecodeError+ directly.
   class BytecodeError < SandboxError; end
 
   # Pool checkout layer. Raised by +Kobako::Pool#with+ when the checkout

data/lib/kobako/handle.rb

@@ -14,8 +14,10 @@ module Kobako
   # The constructor is internal to the Host Gem. +Kobako::Handle.new+ is
   # privatised so Host App code cannot fabricate a Handle from a bare
   # integer; legitimate Handle instances enter Host App code only as
-  # fields on raised error objects. The Host Gem itself constructs
-  # Handles through {.restore}, which exists at exactly two call
+  # fields on raised error objects. +#with+ — Data's copy-with-changes
+  # constructor — is removed for the same reason: a legitimate Handle
+  # must not derive a sibling with a caller-chosen id. The Host Gem itself constructs
+  # Handles through +.restore+, which exists at exactly two call
   # sites: +Kobako::Codec::Factory#unpack_handle+ (wire decode) and
   # +Kobako::Codec::HandleWalk.deep_wrap+ / +Kobako::Transport::Dispatcher#wrap_as_handle+
   # (allocator paths). Both live inside +lib/kobako/+ and are not part
@@ -41,6 +43,7 @@ module Kobako
     end
 
     private_class_method :new
+    undef_method :with
 
     # Host Gem–internal factory. Allocates the Data instance through
     # +Class#allocate+ and dispatches +#initialize+ explicitly so the

data/lib/kobako/namespace.rb

@@ -3,7 +3,7 @@
 module Kobako
   # A named grouping of Members for one Sandbox.
   # Returned by +Sandbox#define+. Each instance owns a flat name→object
-  # table of Members; member binding is validated against {NAME_PATTERN}.
+  # table of Members; member binding is validated against NAME_PATTERN.
   class Namespace
     # Ruby constant-name pattern shared by Namespace and Member names.
     NAME_PATTERN = /\A[A-Z]\w*\z/
@@ -11,7 +11,7 @@ module Kobako
     attr_reader :name
 
     # Build a new Namespace. +name+ is an already-validated Namespace
-    # name (must satisfy {NAME_PATTERN}; validation is the caller's
+    # name (must satisfy NAME_PATTERN; validation is the caller's
     # responsibility).
     def initialize(name)
       @name = name
@@ -38,7 +38,7 @@ module Kobako
 
     # Mark this Namespace as sealed. Called by
     # +Kobako::Catalog::Namespaces#seal!+ on the owning Sandbox's first
-    # invocation; afterwards {#bind} raises +ArgumentError+. Idempotent;
+    # invocation; afterwards #bind raises +ArgumentError+. Idempotent;
     # returns +self+.
     def seal!
       @sealed = true

data/lib/kobako/outcome.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative "codec"
 require_relative "outcome/panic"
 require_relative "transport/error"
 

data/lib/kobako/sandbox.rb

@@ -38,14 +38,16 @@ module Kobako
 
     attr_reader :wasm_path, :options
 
-    # Per-cap accessors forward to the immutable +SandboxOptions+ Value
+    # Per-option 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
+    def_delegators :@options, :timeout, :memory_limit, :stdout_limit, :stderr_limit, :profile
 
     # 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; the byte content never contains a truncation sentinel,
-    # so use +#stdout_truncated?+ to observe overflow.
+    # so use +#stdout_truncated?+ to observe overflow. Populated on every
+    # outcome — including a rescued +TrapError+, after which it holds the
+    # bytes written before the trap fired — mirroring +#usage+.
     def stdout
       @stdout_capture.bytes
     end
@@ -83,25 +85,24 @@ module Kobako
     # 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
+    # gem-bundled +data/kobako.wasm+. Every other keyword — the four caps
+    # (+stdout_limit+, +stderr_limit+, +timeout+, +memory_limit+) and the
+    # requested isolation profile (+profile+) — is forwarded verbatim to
+    # +Kobako::SandboxOptions+, which owns the DEFAULT fallbacks 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: SandboxOptions::DEFAULT_OUTPUT_LIMIT,
-                   stderr_limit: SandboxOptions::DEFAULT_OUTPUT_LIMIT,
-                   timeout: SandboxOptions::DEFAULT_TIMEOUT_SECONDS,
-                   memory_limit: SandboxOptions::DEFAULT_MEMORY_LIMIT)
+    # +#options+ and every option remains readable directly on Sandbox via
+    # +Forwardable+ delegation. The runtime builds the requested profile —
+    # +:hermetic+ (the default) denies the guest ambient time and entropy,
+    # +:permissive+ leaves them live — and construction refuses a runtime
+    # whose declared profile falls below the request, raising
+    # +Kobako::SetupError+ before any invocation entry point runs.
+    def initialize(wasm_path: nil, **)
       @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)
+      @options = SandboxOptions.new(**)
       @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)
+      @runtime = build_runtime!
       install_dispatch_proc!
       reset_invocation_state!
     end
@@ -119,7 +120,9 @@ module Kobako
     # Register a snippet on this Sandbox in one of two forms:
     #
     #   * +preload(code: source, name: Name)+ — +source+ is mruby source
-    #     as a +String+ and +Name+ matches +/\A[A-Z]\w*\z/+. The +name+
+    #     as a +String+ and +Name+ matches +/\A[A-Z]\w*\z/+. Compile
+    #     failures surface as +Kobako::SandboxError+ on the first
+    #     invocation's replay. The +name+
     #     becomes the snippet's +(snippet:Name)+ backtrace filename and
     #     is the dedupe key that rejects a duplicate +code:+ snippet.
     #   * +preload(binary: bytes)+ — +bytes+ is precompiled RITE
@@ -209,6 +212,17 @@ module Kobako
 
     private
 
+    # Construct the +Runtime+ with the requested isolation profile and
+    # refuse one whose declared posture falls below the request —
+    # +SandboxOptions#enforce_floor!+ owns the ladder comparison, so a
+    # runtime that cannot honor the request never runs guest code.
+    def build_runtime!
+      runtime = Kobako::Runtime.from_path(@wasm_path, @options.timeout, @options.memory_limit,
+                                          @options.stdout_limit, @options.stderr_limit, @options.profile)
+      @options.enforce_floor!(runtime.profile)
+      runtime
+    end
+
     # Configure the +Runtime+'s host↔guest dispatch wiring. Registers a
     # dispatch +Proc+ that routes guest→host calls through the stateless
     # +Transport::Dispatcher+, capturing +@services+ / +@handler+ in the
@@ -242,13 +256,11 @@ module Kobako
     # +TimeoutError+ / +MemoryLimitError+), +Kobako::SandboxError+,
     # and +Kobako::ServiceError+. +Runtime#usage+ is the single source for
     # both paths: the figures are stashed in the ext on every outcome, so
-    # unlike the +Snapshot+ (built only on success) the readout here also
-    # covers the trap path.
+    # the readout here also covers the trap path, where +Runtime#eval+ /
+    # +#run+ raise instead of returning outcome bytes.
     #
-    # 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.
+    # The ext-side contract is positional: +Runtime#usage+ yields
+    # +[wall_time, memory_peak]+ in +Kobako::Usage+ field order.
     def read_usage!
       wall_time, memory_peak = @runtime.usage
       @usage = Usage.new(wall_time: wall_time, memory_peak: memory_peak)
@@ -269,33 +281,49 @@ module Kobako
       end
     end
 
+    # Read the per-last-invocation output captures from the ext and wrap
+    # them as +Kobako::Capture+ value objects. Runs in the +invoke!+
+    # +ensure+ block next to #read_usage! for the same reason: the ext
+    # stashes the captures on every outcome, so the readout also covers
+    # the trap path, where +Runtime#eval+ / +#run+ raise instead of
+    # returning outcome bytes — +#stdout+ / +#stderr+ keep the guest's
+    # partial output readable after a rescue.
+    #
+    # The ext-side contract is positional: +Runtime#captures+ yields
+    # +[stdout_bytes, stdout_truncated, stderr_bytes, stderr_truncated]+.
+    def read_captures!
+      stdout_bytes, stdout_truncated, stderr_bytes, stderr_truncated = @runtime.captures
+      @stdout_capture = Capture.new(bytes: stdout_bytes, truncated: stdout_truncated)
+      @stderr_capture = Capture.new(bytes: stderr_bytes, truncated: stderr_truncated)
+    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+. The success path unpacks
-    # +#stdout+ / +#stderr+ into
-    # +Capture+ and feeds +#return_bytes+ to +Outcome.decode+; usage is
-    # populated by the +ensure+ readout ({#read_usage!}) on every outcome.
+    # The yielded block must return the invocation's raw outcome bytes —
+    # i.e. the value of +Runtime#eval+ / +#run+ — which the success path
+    # feeds to +Outcome.decode+. Captures and usage are populated by the
+    # +ensure+ readouts (#read_usage! / #read_captures!) on every
+    # outcome, so +#stdout+ / +#stderr+ / +#usage+ stay readable after a
+    # rescued trap.
     # The rescue chain is the single trap-translation boundary —
     # configured-cap paths surface as named TrapError subclasses
     # (+TimeoutError+ / +MemoryLimitError+); everything else surfaces as
     # the base +TrapError+.
     def invoke!(verb)
       begin_invocation!
-      snapshot = yield
-      @stdout_capture = snapshot.stdout
-      @stderr_capture = snapshot.stderr
+      return_bytes = yield
       # A Capability Handle in the result is decoded as a Kobako::Handle
       # token; restore it to the host object the guest referenced before
       # handing the value to the Host App. @handler still holds this
       # invocation's table — reset only happens at the next #begin_invocation!.
-      Codec::HandleWalk.deep_restore(Outcome.decode(snapshot.return_bytes), @handler)
+      Codec::HandleWalk.deep_restore(Outcome.decode(return_bytes), @handler)
     rescue Kobako::TrapError => e
       raise trap_class_for(e), "Sandbox##{verb} failed: #{e.message}"
     ensure
       read_usage!
+      read_captures!
     end
   end
 end

data/lib/kobako/sandbox_options.rb

@@ -1,19 +1,27 @@
 # frozen_string_literal: true
 
+require_relative "errors"
+
 module Kobako
   # Kobako::SandboxOptions — immutable Value Object holding the four
-  # per-Sandbox configuration caps. Built on the +class X <
-  # Data.define(...)+ subclass form (the Steep-friendly shape — see
-  # +lib/kobako/outcome/panic.rb+).
+  # per-Sandbox configuration caps and the requested isolation profile.
+  # Built on the +class X < Data.define(...)+ subclass form (the
+  # Steep-friendly shape — see +lib/kobako/outcome/panic.rb+).
   #
-  # The +initialize+ normalises every cap before delegating to Data's
+  # The +initialize+ normalises every option before delegating to Data's
   # +super+: +timeout+ to Float seconds, +memory_limit+ / +stdout_limit+ /
   # +stderr_limit+ to positive Integer bytes. Each cap is +nil+-disablable
   # (an absent argument takes its DEFAULT; an explicit +nil+ leaves the
-  # bound off), so all four behave uniformly. 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)
+  # bound off), so all four behave uniformly. +profile+ is the one
+  # non-cap: a Symbol on the PROFILES ladder naming the posture the
+  # runtime builds, which is also the weakest the Host App accepts —
+  # +nil+ is rejected because the weakest posture is requested as an
+  # explicit +:permissive+. Anything that survives +SandboxOptions.new+
+  # is a wire-ready bundle the +Kobako::Runtime+ constructor consumes
+  # as-is. The options also own the ladder comparison
+  # (+#enforce_floor!+) that +Kobako::Sandbox+ delegates its
+  # construction floor check to.
+  class SandboxOptions < Data.define(:timeout, :memory_limit, :stdout_limit, :stderr_limit, :profile)
     # Default wall-clock timeout for a single invocation: 60 seconds.
     DEFAULT_TIMEOUT_SECONDS = 60.0
 
@@ -25,17 +33,41 @@ module Kobako
     # Default per-channel capture ceiling: 1 MiB.
     DEFAULT_OUTPUT_LIMIT = 1 << 20
 
+    # The isolation ladder, weakest first — index order is rank order,
+    # so a floor check is an index comparison.
+    PROFILES = %i[permissive hermetic].freeze
+
+    # Default isolation profile: the strictest rung — opting down to
+    # +:permissive+ is the Host App's explicit trade.
+    DEFAULT_PROFILE = :hermetic
+
     def initialize(timeout: DEFAULT_TIMEOUT_SECONDS,
                    memory_limit: DEFAULT_MEMORY_LIMIT,
                    stdout_limit: DEFAULT_OUTPUT_LIMIT,
-                   stderr_limit: DEFAULT_OUTPUT_LIMIT)
+                   stderr_limit: DEFAULT_OUTPUT_LIMIT,
+                   profile: DEFAULT_PROFILE)
       timeout = normalize_timeout(timeout)
       memory_limit = normalize_memory_limit(memory_limit)
       stdout_limit = normalize_output_limit(stdout_limit, "stdout_limit")
       stderr_limit = normalize_output_limit(stderr_limit, "stderr_limit")
+      profile = normalize_profile(profile)
       super
     end
 
+    # Enforce the requested +profile+ as the floor against +declared+ —
+    # the posture a runtime reports having built — so a runtime that
+    # cannot honor the request fails construction with
+    # +Kobako::SetupError+ instead of weakening the posture silently.
+    # Both fallbacks fail closed: a declaration off the PROFILES ladder
+    # ranks below every request, and a request off the ladder
+    # (unreachable past +initialize+) refuses every declaration.
+    def enforce_floor!(declared)
+      return if (PROFILES.index(declared) || -1) >= (PROFILES.index(profile) || PROFILES.size)
+
+      raise Kobako::SetupError, "runtime declares isolation profile #{declared.inspect}, " \
+                                "below the requested floor #{profile.inspect}"
+    end
+
     private
 
     # Coerce +timeout+ into the Float seconds the ext expects, or +nil+
@@ -78,5 +110,15 @@ module Kobako
 
       limit
     end
+
+    # Validate +profile+ against the PROFILES ladder. Unlike the caps
+    # there is no +nil+ form: the weakest posture is requested as an
+    # explicit +:permissive+, so anything off the ladder — +nil+
+    # included — is rejected.
+    def normalize_profile(profile)
+      return profile if PROFILES.include?(profile)
+
+      raise ArgumentError, "profile must be one of #{PROFILES.map(&:inspect).join(", ")}, got #{profile.inspect}"
+    end
   end
 end

data/lib/kobako/transport/dispatcher.rb

@@ -27,7 +27,7 @@ module Kobako
     #   Kobako::Transport::Dispatcher.dispatch(request_bytes, namespaces, handler, yield_to_guest)
     #   # => msgpack-encoded Response bytes (never raises)
     module Dispatcher
-      # Throw tag for the {Yielder}'s break unwind back to the
+      # Throw tag for the Yielder's break unwind back to the
       # dispatcher's +catch+ frame. +private_constant+ is a
       # convention boundary — not a defence.
       BREAK_THROW = :__kobako_break__
@@ -54,12 +54,12 @@ module Kobako
       # Callable gadget types whose own public methods are reflection surface
       # (+Proc#binding+ reaches +Binding#eval+, +Method#receiver+ / +#unbind+
       # hand back the underlying object) rather than Service behaviour. Only
-      # {CALLABLE_ALLOW} is reachable on a target of these types; a bound
+      # CALLABLE_ALLOW is reachable on a target of these types; a bound
       # lambda stays invocable, its reflective surface does not.
       GADGET_OWNERS = [Proc, Method, UnboundMethod, Binding].freeze
       private_constant :GADGET_OWNERS
 
-      # The sole methods reachable on a {GADGET_OWNERS} target: invoking it
+      # The sole methods reachable on a GADGET_OWNERS target: invoking it
       # (+call+ / +[]+ / +yield+) and the harmless +arity+ / +lambda?+
       # describers that aid guest-side debugging.
       CALLABLE_ALLOW = %i[call [] yield arity lambda?].freeze
@@ -91,7 +91,7 @@ module Kobako
       end
 
       # Resolve positional and keyword arguments off +request+ in one
-      # step. Both pass through {#resolve_arg} so Capability Handles
+      # step. Both pass through #resolve_arg so Capability Handles
       # round-trip back to the host-side Ruby object before the call
       # reaches +public_send+.
       def resolve_call_args(request, handler)
@@ -101,7 +101,7 @@ module Kobako
 
       # Map an error caught at the dispatch boundary to a +Response.error+
       # envelope (binary msgpack). +error+ is the +StandardError+ caught by
-      # {#dispatch}'s rescue; the +type+ field tells the guest which kind
+      # #dispatch's rescue; the +type+ field tells the guest which kind
       # of failure it was so it can raise the matching proxy-side error.
       def encode_caught_error(error)
         case error
@@ -119,8 +119,8 @@ module Kobako
       # reject calls to no-kwarg methods when the wire carries the
       # uniform empty-map shape.
       #
-      # +yielder+ is the host-side {Yielder} materialised when the guest
-      # call site supplied a block; its {Yielder#to_proc}
+      # +yielder+ is the host-side Yielder materialised when the guest
+      # call site supplied a block; its Yielder#to_proc
       # rides the +&block+ slot. +&nil+ is a no-op block argument in Ruby,
       # so the same call site handles both cases without an explicit
       # conditional.
@@ -137,8 +137,8 @@ module Kobako
       end
 
       # Guard the +public_send+ below against ambient reflection methods.
-      # A public method whose owner is a {META_OWNERS} or {GADGET_OWNERS} module is
-      # rejected, except {CALLABLE_ALLOW} on a gadget target (a bound lambda
+      # A public method whose owner is a META_OWNERS or GADGET_OWNERS module is
+      # rejected, except CALLABLE_ALLOW on a gadget target (a bound lambda
       # stays invocable). A name with no concrete public method is allowed
       # only when the target opts into it via +respond_to?+ (dynamic
       # +method_missing+ Services), since the dangerous methods are all
@@ -159,7 +159,7 @@ module Kobako
       # Consult the target's opt-in narrowing predicate. A bound object
       # may define a private +respond_to_guest?(name)+ to restrict which of its
       # methods the guest reaches; a falsy answer rejects the dispatch.
-      # The predicate composes beneath {#reject_meta_method!} — it only narrows,
+      # The predicate composes beneath #reject_meta_method! — it only narrows,
       # never re-opening the reflection surface the floor rejects — and is
       # consulted with the private surface included so the guest's +public_send+
       # dispatch can never reach +respond_to_guest?+ itself.
@@ -213,7 +213,7 @@ module Kobako
       # Encode +value+ as a +Response.ok+ envelope. When the value is not
       # wire-representable per the codec's type mapping, the
       # +UnsupportedType+ rescue routes it through the
-      # Catalog::Handles via {#wrap_as_handle} and re-encodes with the Capability
+      # Catalog::Handles via #wrap_as_handle and re-encodes with the Capability
       # Handle in place. The happy path encodes exactly once.
       def encode_ok(value, handler)
         response = Kobako::Transport::Response.ok(value)
@@ -224,15 +224,18 @@ module Kobako
 
       # Allocate +value+ in the Sandbox's Catalog::Handles and return a +Handle+
       # that the wire codec can carry. Used as the fallback path of
-      # {#encode_ok} when +value+ has no wire representation.
+      # #encode_ok when +value+ has no wire representation.
       def wrap_as_handle(value, handler)
         handler.alloc(value)
       end
 
+      # +message+ folds to UTF-8 first: Ruby core builds some exception
+      # messages as ASCII-8BIT (the arity ArgumentError, for one), and
+      # the codec would ride those as bin — a shape the guest refuses.
       def encode_error(type, message)
+        message = message.encode(Encoding::UTF_8, invalid: :replace, undef: :replace)
         fault = Kobako::Fault.new(type: type, message: message)
-        response = Kobako::Transport::Response.error(fault)
-        response.encode
+        Kobako::Transport::Response.error(fault).encode
       end
     end
   end

data/lib/kobako/transport/request.rb

@@ -13,7 +13,7 @@ module Kobako
     # 5-element msgpack array:
     # +[target, method_name, args, kwargs, block_given]+. +target+ is
     # either a +String+ (+"<Namespace>::<Member>"+, e.g. +"MyService::KV"+)
-    # or a {Handle}. SPEC pins +kwargs+ map keys to ext 0x00 Symbol;
+    # or a Handle. SPEC pins +kwargs+ map keys to ext 0x00 Symbol;
     # enforced at construction so the Value Object is the single source of
     # truth. +block_given+ is a Boolean signalling whether the guest call
     # site supplied a block; the block body itself never crosses the
@@ -43,7 +43,7 @@ module Kobako
         Codec::Encoder.encode([target, method_name, args, kwargs, block_given])
       end
 
-      # Decode +bytes+ into a {Request}. Raises +Codec::InvalidType+ when the
+      # Decode +bytes+ into a Request. Raises +Codec::InvalidType+ when the
       # envelope is not the expected 5-element msgpack array, or when the
       # Value Object's construction invariants reject the decoded fields.
       def self.decode(bytes)

data/lib/kobako/transport/response.rb

@@ -20,7 +20,7 @@ module Kobako
     #
     # 2-element msgpack array: +[status, value-or-fault]+. +status+ is 0
     # (success) or 1 (fault). For success the second element is the return
-    # value; for fault it is a {Fault} (ext 0x02 envelope).
+    # value; for fault it is a Fault (ext 0x02 envelope).
     #
     # Built on the +class X < Data.define(...)+ subclass form so the
     # class body is fully Steep-visible; see +lib/kobako/outcome/panic.rb+
@@ -58,7 +58,7 @@ module Kobako
         Codec::Encoder.encode([status, payload])
       end
 
-      # Decode +bytes+ into a {Response}. Raises +Codec::InvalidType+ when the
+      # Decode +bytes+ into a Response. Raises +Codec::InvalidType+ when the
       # envelope is not the expected 2-element msgpack array, or when the
       # Value Object's construction invariants reject the decoded fields.
       def self.decode(bytes)

data/lib/kobako/transport/run.rb

@@ -51,7 +51,7 @@ module Kobako
       # Encode this Run to the msgpack bytes the guest's +__kobako_run+
       # entry point consumes as its command-buffer payload
       # ({docs/wire-codec.md Invocation channels}[link:../../../docs/wire-codec.md]).
-      # Walks +args+ / +kwargs+ through {Codec::HandleWalk.deep_wrap} so
+      # Walks +args+ / +kwargs+ through Codec::HandleWalk.deep_wrap so
       # any non-wire-representable leaf is allocated into +handler+ and
       # replaced with a +Kobako::Handle+; the
       # +handler+ argument is the Sandbox's table, sharing the same

data/lib/kobako/transport/yield.rb

@@ -10,9 +10,9 @@ module Kobako
     # First byte of the YieldResponse for the success branch — body is
     # the block's return value encoded as a single msgpack value.
     TAG_OK = 0x01
-    # First byte for `break val` — body is the break value.
+    # First byte for +break val+ — body is the break value.
     TAG_BREAK = 0x02
-    # Reserved for future `return val` support; both sides reject this
+    # Reserved for future +return val+ support; both sides reject this
     # tag as a wire violation (YieldResponse envelope contract).
     TAG_RESERVED = 0x03
     # First byte for an error / fault outcome — body is a
@@ -58,7 +58,7 @@ module Kobako
         [tag].pack("C") + Codec::Encoder.encode(value)
       end
 
-      # Decode +bytes+ into a {Yield}. Rejects empty input, the reserved
+      # Decode +bytes+ into a Yield. Rejects empty input, the reserved
       # tag 0x03, and any tag outside +LIVE_TAGS+ by raising
       # +Kobako::Codec::InvalidType+ — these are wire violations per the
       # SPEC's YieldResponse envelope contract.

data/lib/kobako/transport/yielder.rb

@@ -13,7 +13,7 @@ module Kobako
     # Each guest call that carries +block_given: true+ gets a Yielder
     # that the Dispatcher hands to the Service method as +&block+. The
     # Service method observes it as an ordinary Ruby Proc through
-    # {#to_proc}; +yield val+ / +block.call(val)+ invokes {#yield}, which
+    # #to_proc; +yield val+ / +block.call(val)+ invokes #yield, which
     # serialises the positional args, re-enters the guest via the injected
     # +yield_to_guest+ lambda, and reifies the +YieldResponse+ into Ruby
     # control flow:
@@ -24,13 +24,13 @@ module Kobako
     #   * +tag 0x04+ error — raise the +{class, message}+ payload at the
     #     Service's yield site
     #
-    # The Dispatcher calls {#invalidate!} from its +ensure+ block once
+    # The Dispatcher calls #invalidate! from its +ensure+ block once
     # dispatch completes; any later call to a stashed Yielder then raises
     # +LocalJumpError+ — the observable shape of an escaped Yielder.
     class Yielder
       # +yield_to_guest+ is a +String → String+ callable (the ext's
       # per-dispatch +Kobako::Runtime::GuestYielder+) that
-      # {#yield} invokes to re-enter the guest; +break_tag+ is the +catch+
+      # #yield invokes to re-enter the guest; +break_tag+ is the +catch+
       # throw tag the Dispatcher matches against to unwind the Service on
       # +tag 0x02+. +handler+ is the Sandbox's +Kobako::Catalog::Handles+,
       # used to restore a Capability Handle in the block's ok value back to
@@ -44,7 +44,7 @@ module Kobako
 
       # Re-enter the guest with +args+ and reify the YieldResponse into
       # Ruby control flow. Raises +LocalJumpError+ if called after
-      # {#invalidate!}. The ok value is consumed by the host Service
+      # #invalidate!. The ok value is consumed by the host Service
       # method, so a Capability Handle in it is restored to its host object.
       # The break value unwinds past the Service back to the guest
       # Member call, so it passes through verbatim — a Handle stays a
@@ -60,14 +60,14 @@ module Kobako
         raise yield_failure(response.value, default: "yield error")
       end
 
-      # The Proc the Dispatcher passes as +&block+, binding {#yield} so a
+      # The Proc the Dispatcher passes as +&block+, binding #yield so a
       # Service method's +yield+ / +block.call+ drives the round-trip.
       def to_proc
         method(:yield).to_proc
       end
 
       # Mark this Yielder dead. Called by the Dispatcher's +ensure+ block
-      # when the originating dispatch frame returns; any later {#yield}
+      # when the originating dispatch frame returns; any later #yield
       # call then raises +LocalJumpError+.
       def invalidate!
         @active = false

data/lib/kobako/version.rb

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

data/lib/kobako.rb

@@ -13,6 +13,5 @@ require_relative "kobako/errors"
 require_relative "kobako/transport"
 require_relative "kobako/catalog"
 require_relative "kobako/runtime"
-require_relative "kobako/snapshot"
 require_relative "kobako/sandbox"
 require_relative "kobako/pool"