kobako 0.12.1 → 0.13.0

data/lib/kobako/catalog/handles.rb

@@ -38,7 +38,7 @@ module Kobako
       # for it. +object+ is any host-side Ruby object to bind. Returns a
       # freshly-allocated +Kobako::Handle+ whose +#id+ falls in
       # +[Kobako::Handle::MIN_ID, Kobako::Handle::MAX_ID]+. Raises
-      # +Kobako::HandlerExhaustedError+ if the next ID would exceed the
+      # +Kobako::HandleExhaustedError+ if the next ID would exceed the
       # cap. The cap is anchored on +Kobako::Handle+ — the wire codec
       # and the allocator share the same invariant.
       #
@@ -96,12 +96,12 @@ module Kobako
       end
 
       # Guard {#alloc} against issuing an ID past the cap. Returns +nil+
-      # on success; raises +Kobako::HandlerExhaustedError+ at exhaustion.
+      # on success; raises +Kobako::HandleExhaustedError+ at exhaustion.
       def ensure_capacity!
         cap = Kobako::Handle::MAX_ID
         return unless @next_id > cap
 
-        raise HandlerExhaustedError,
+        raise HandleExhaustedError,
               "Out of handle allocations: too many host objects were referenced " \
               "in a single invocation (limit #{cap})"
       end

data/lib/kobako/catalog/namespaces.rb

@@ -82,6 +82,10 @@ module Kobako
       # first invocation, so the preamble is exactly the bindings that
       # existed at that moment — a bind reaching a +Kobako::Namespace+
       # after the seal raises +ArgumentError+ and never alters Frame 1.
+      # The memo is gated on the seal rather than dropped per mutation (the
+      # +Catalog::Snippets#encode+ approach) because a +Member+ bind lands
+      # on a child +Kobako::Namespace+, invisible to this collection; only
+      # the seal guarantees nothing further can change.
       def encode
         return @encoded if @encoded
 

data/lib/kobako/catalog/snippets.rb

@@ -44,6 +44,10 @@ module Kobako
       # The bytes are memoized — the table is replayed verbatim on every
       # invocation after sealing, so Frame 3 never changes between
       # encodes; {#register} drops the memo while the table is still open.
+      # Unlike +Catalog::Namespaces#encode+, which gates its memo on the
+      # seal, this one can fill eagerly and invalidate in +#register+
+      # because every mutation funnels through that single method — there is
+      # no out-of-sight child object to change the result behind its back.
       def encode
         return @encoded if @encoded
 

data/lib/kobako/codec/encoder.rb

@@ -26,7 +26,11 @@ module Kobako
       # mapping is a closed set, and anything outside it is rejected by
       # the msgpack gem itself (arbitrary objects raise +NoMethodError+
       # from missing +to_msgpack+, integers outside i64..u64 raise
-      # +RangeError+).
+      # +RangeError+). The +NoMethodError+ catch is deliberately broad:
+      # MessagePack signals "no wire representation" only through that error,
+      # so there is no narrower discriminator — a packer-internal
+      # +NoMethodError+ is likewise reported as +UnsupportedType+ rather than
+      # propagating.
       def self.encode(value)
         Factory.dump(value)
       rescue ::RangeError, ::NoMethodError => e

data/lib/kobako/codec/factory.rb

@@ -48,6 +48,16 @@ module Kobako
       EXT_ERRENV = 0x02
       private_constant :EXT_SYMBOL, :EXT_HANDLE, :EXT_ERRENV
 
+      # An ext 0x02 (Fault) envelope nests through its +details+ field, and
+      # each level re-enters the codec with a fresh +MessagePack+ unpacker
+      # whose built-in stack guard resets — so ext-envelope depth is tracked
+      # here instead. The cap matches the wire's overall nesting bound and
+      # keeps a nested chain from exhausting the native stack: an over-deep
+      # chain fails as a clean wire error, never a stack-level trap.
+      MAX_EXT_DEPTH = 128
+      EXT_DEPTH_KEY = :__kobako_codec_ext_depth__
+      private_constant :MAX_EXT_DEPTH, :EXT_DEPTH_KEY
+
       # Instance-level pass-through onto the wrapped +MessagePack::Factory+.
       # Spelled +def_instance_delegators+ rather than +def_delegators+ because
       # the class also extends +SingleForwardable+ (see the +extend+ block
@@ -129,9 +139,13 @@ module Kobako
       # Encode the inner ext-0x02 map via {Encoder} (not +factory.dump+) so
       # the embedded payload flows through the same boundary as a top-level
       # encode — nested kobako values (Handle, nested Fault) reach the
-      # registered ext-type packers via the cached singleton.
+      # registered ext-type packers via the cached singleton. A +details+
+      # chain nested past {MAX_EXT_DEPTH} has no wire representation and
+      # surfaces as +UnsupportedType+.
       def pack_fault(fault)
-        Encoder.encode("type" => fault.type, "message" => fault.message, "details" => fault.details)
+        within_ext_frame(UnsupportedType) do
+          Encoder.encode("type" => fault.type, "message" => fault.message, "details" => fault.details)
+        end
       end
 
       # Peel the embedded msgpack map and hand it to +Kobako::Fault.new+
@@ -139,19 +153,33 @@ module Kobako
       # +ArgumentError+ invariants surface as +InvalidType+ through the
       # decoder boundary. Inner decode goes through {Decoder} (not
       # +factory.load+) so the embedded +str+ payloads flow through the
-      # same UTF-8 validation as a top-level decode.
-      #
-      # This establishes a runtime cycle Factory → Decoder → Factory: the
-      # singleton instance feeds +Decoder.decode+, which re-enters this
-      # method when a nested ext 0x02 appears inside +details+. The recursion
-      # is bounded by msgpack nesting depth — identical to nested Array /
-      # Hash payloads — so no extra guard is needed. Do not switch back to
-      # +factory.load+ to "simplify": that path bypasses UTF-8 validation.
+      # same UTF-8 validation as a top-level decode. A nested ext 0x02 in
+      # +details+ re-enters this method, so {#within_ext_frame} bounds the
+      # chain depth to keep it from exhausting the native stack.
       def unpack_fault(payload)
-        Decoder.decode(payload) do |map|
-          raise InvalidType, "Fault payload must be a map" unless map.is_a?(Hash)
+        within_ext_frame(InvalidType) do
+          Decoder.decode(payload) do |map|
+            raise InvalidType, "Fault payload must be a map" unless map.is_a?(Hash)
+
+            Kobako::Fault.new(type: map["type"], message: map["message"], details: map["details"])
+          end
+        end
+      end
 
-          Kobako::Fault.new(type: map["type"], message: map["message"], details: map["details"])
+      # Track ext-envelope re-entry depth and refuse a chain past
+      # {MAX_EXT_DEPTH}, raising +over_limit+ so the failure lands in the
+      # caller's existing wire-error class. The counter is thread-scoped and
+      # balanced by the +ensure+, so a raise mid-chain still unwinds it to
+      # its entry value.
+      def within_ext_frame(over_limit)
+        depth = (Thread.current[EXT_DEPTH_KEY] || 0) + 1
+        raise over_limit, "ext envelope nesting exceeds #{MAX_EXT_DEPTH} levels" if depth > MAX_EXT_DEPTH
+
+        Thread.current[EXT_DEPTH_KEY] = depth
+        begin
+          yield
+        ensure
+          Thread.current[EXT_DEPTH_KEY] = depth - 1
         end
       end
     end

data/lib/kobako/codec/handle_walk.rb

@@ -97,6 +97,10 @@ module Kobako
         case value
         when ::Array then value.map { |element| HandleWalk.deep_restore(element, handler) }
         when ::Hash
+          # Rebuilt with each key restored: two distinct Handle keys that
+          # resolve to equal host objects collapse to the later pair, as in
+          # any Ruby Hash. The guest authored this payload, so that collapse
+          # is its own concern, not a fidelity guarantee the host owes it.
           value.to_h { |key, val| [HandleWalk.deep_restore(key, handler), HandleWalk.deep_restore(val, handler)] }
         when Kobako::Handle then handler.fetch(value.id)
         else value

data/lib/kobako/codec.rb

@@ -22,7 +22,7 @@ module Kobako
   # {Decoder} are thin wrappers that register the three kobako-specific
   # ext types (0x00 Symbol, 0x01 Capability Handle, 0x02 Exception
   # envelope) on a single +MessagePack::Factory+ instance. The Rust side
-  # mirrors this layer as the +codec+ module in the +kobako-core+ crate;
+  # mirrors this layer as the +codec+ module in the +kobako-codec+ crate;
   # the ext-code constants live as module-private values on {Factory}
   # alongside +codec::EXT_SYMBOL+ / +codec::EXT_HANDLE+ /
   # +codec::EXT_ERRENV+ on that side.

data/lib/kobako/errors.rb

@@ -35,7 +35,7 @@ module Kobako
   #
   #   * {ModuleNotBuiltError} < {SetupError} — Guest Binary artifact absent
   #                       at +wasm_path+.
-  #   * {HandlerExhaustedError} < {SandboxError} — Handle id cap hit.
+  #   * {HandleExhaustedError} < {SandboxError} — Handle id cap hit.
 
   # Base for all kobako-raised errors so callers that want to ignore the
   # taxonomy can rescue a single class.
@@ -89,10 +89,13 @@ module Kobako
   # +ModuleNotBuiltError+ first.
   class ModuleNotBuiltError < SetupError; end
 
-  # Sandbox / wire layer. Raised when the guest ran to completion but
-  # execution failed due to a mruby script error, a protocol fault, or a
-  # host-side wire decode failure on an otherwise valid outcome tag.
-  class SandboxError < Error
+  # The structured attribution the two invocation-failure classes carry
+  # from a decoded guest exception — its +origin+, original +klass+,
+  # +backtrace_lines+, and +details+ — so a Host App can inspect a failure
+  # beyond its message. Mixed into both rather than promoted to a shared
+  # superclass because +SandboxError+ and +ServiceError+ sit in distinct
+  # branches of the invocation-outcome taxonomy under +Kobako::Error+.
+  module StructuredError
     attr_reader :origin, :klass, :backtrace_lines, :details
 
     def initialize(message, origin: nil, klass: nil, backtrace_lines: nil, details: nil)
@@ -104,26 +107,25 @@ module Kobako
     end
   end
 
+  # Sandbox / wire layer. Raised when the guest ran to completion but
+  # execution failed due to a mruby script error, a protocol fault, or a
+  # host-side wire decode failure on an otherwise valid outcome tag.
+  class SandboxError < Error
+    include StructuredError
+  end
+
   # Service layer. Raised when a Service capability call inside a mruby
   # script reported an application-level failure that the script did not
   # rescue.
   class ServiceError < Error
-    attr_reader :origin, :klass, :backtrace_lines, :details
-
-    def initialize(message, origin: nil, klass: nil, backtrace_lines: nil, details: nil)
-      super(message)
-      @origin = origin
-      @klass = klass
-      @backtrace_lines = backtrace_lines
-      @details = details
-    end
+    include StructuredError
   end
 
-  # HandlerExhaustedError is the canonical SandboxError subclass for the
+  # HandleExhaustedError is the canonical SandboxError subclass for the
   # id-cap-hit path. Raised when the per-invocation Handle ID counter in
   # Catalog::Handles reaches +0x7fff_ffff+ (2³¹ − 1) and further
   # allocation would exceed the cap.
-  class HandlerExhaustedError < SandboxError; end
+  class HandleExhaustedError < SandboxError; end
 
   # BytecodeError is the SandboxError subclass raised when a
   # `#preload(binary:)` snippet fails structural validation during the

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,23 +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: nil, stderr_limit: nil,
-                   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
@@ -207,17 +210,28 @@ module Kobako
 
     private
 
-    # Configure the +Runtime+'s host↔guest dispatch wiring. Builds a
-    # lambda that re-enters the guest via
-    # +Runtime#yield_to_active_invocation+ 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.
+    # 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, 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
+    # closure. The ext hands the +Proc+ a per-dispatch +guest_yielder+ — a
+    # +String → String+ callable that re-enters the in-flight guest to run a
+    # yielded block — which the +Dispatcher+ forwards to the +Transport::Yielder+
+    # it builds for the call. Registered 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)
+      @runtime.on_dispatch = lambda do |request_bytes, guest_yielder|
+        Transport::Dispatcher.dispatch(request_bytes, @services, @handler, guest_yielder)
       end
     end
 
@@ -226,8 +240,7 @@ module Kobako
     # 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".
+    # beyond this class — it is not part of the Host App's surface.
     def begin_invocation!
       @services.seal!
       @handler.reset!
@@ -239,9 +252,10 @@ module Kobako
     # 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.
+    # and +Kobako::ServiceError+. +Runtime#usage+ is the single source for
+    # both paths: the figures are stashed in the ext on every outcome, so
+    # 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
@@ -267,33 +281,51 @@ 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 returns a positional 4-tuple
+    # +[stdout_bytes, stdout_truncated, stderr_bytes, stderr_truncated]+;
+    # the destructure-then-kwargs handoff below is the explicit
+    # positional→keyword conversion point.
+    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+ (SPEC.md Internal Concepts →
-    # Snapshot). 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,17 +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+ 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)
+  # 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. +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
 
@@ -23,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: nil,
-                   stderr_limit: nil)
+                   stdout_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 ||= DEFAULT_OUTPUT_LIMIT
-      stderr_limit ||= DEFAULT_OUTPUT_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+
@@ -62,5 +96,29 @@ module Kobako
 
       memory_limit
     end
+
+    # Coerce a per-channel output cap (+stdout_limit+ / +stderr_limit+)
+    # into the byte cap the ext expects, or +nil+ to leave the channel
+    # uncapped. Same shape as +normalize_memory_limit+: a positive Integer
+    # when set, Float / zero / negative rejected. +name+ tags the
+    # +ArgumentError+ with the offending keyword.
+    def normalize_output_limit(limit, name)
+      return nil if limit.nil?
+      unless limit.is_a?(Integer) && limit.positive?
+        raise ArgumentError, "#{name} must be a positive Integer or nil, got #{limit.inspect}"
+      end
+
+      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

@@ -72,8 +72,8 @@ module Kobako
       # closure so the Dispatcher stays stateless and the registry doesn't
       # need to publish accessors for the Sandbox-owned +Catalog::Handles+
       # or +Runtime+. +yield_to_guest+ is a +String → String+ callable
-      # (typically +Runtime#yield_to_active_invocation+ bound as a lambda)
-      # used only when the Request carries +block_given: true+. Always
+      # (the ext's per-dispatch +Kobako::Runtime::GuestYielder+) used only
+      # when the Request carries +block_given: true+. Always
       # returns a binary String — every failure path is reified as a
       # Response.error envelope so the guest sees a transport error rather
       # than a wasm trap.

data/lib/kobako/transport/response.rb

@@ -38,20 +38,6 @@ module Kobako
         new(status: STATUS_ERROR, payload: fault)
       end
 
-      # 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)
-        Codec::Decoder.decode(bytes) do |arr|
-          unless arr.is_a?(Array) && arr.length == 2
-            raise Codec::InvalidType, "Response envelope is malformed (expected a 2-element array)"
-          end
-
-          status, payload = arr
-          new(status: status, payload: payload)
-        end
-      end
-
       def initialize(status:, payload:)
         unless [STATUS_OK, STATUS_ERROR].include?(status)
           raise ArgumentError, "Response status must be 0 (ok) or 1 (error), got #{status.inspect}"
@@ -71,6 +57,20 @@ module Kobako
       def encode
         Codec::Encoder.encode([status, payload])
       end
+
+      # 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)
+        Codec::Decoder.decode(bytes) do |arr|
+          unless arr.is_a?(Array) && arr.length == 2
+            raise Codec::InvalidType, "Response envelope is malformed (expected a 2-element array)"
+          end
+
+          status, payload = arr
+          new(status: status, payload: payload)
+        end
+      end
     end
   end
 end

data/lib/kobako/transport/run.rb

@@ -43,8 +43,8 @@ module Kobako
 
       def initialize(entrypoint:, args: [], kwargs: {})
         entrypoint = normalize_entrypoint(entrypoint)
-        args = validate_args!(args)
-        kwargs = validate_kwargs!(kwargs)
+        validate_args!(args)
+        validate_kwargs!(kwargs)
         super
       end
 
@@ -100,8 +100,6 @@ module Kobako
       def validate_args!(args)
         raise ArgumentError, "arguments must be an Array" unless args.is_a?(Array)
         raise ArgumentError, forged_handle_message("arguments") if args.any?(Kobako::Handle)
-
-        args
       end
 
       # Reject a non-Symbol kwargs key, and a +Kobako::Handle+ arriving
@@ -117,8 +115,6 @@ module Kobako
                 "keyword argument keys must be Symbols (got #{bad_keys.inspect})"
         end
         raise ArgumentError, forged_handle_message("keyword argument values") if kwargs.each_value.any?(Kobako::Handle)
-
-        kwargs
       end
 
       # Single source of truth for the forged-Handle reject message so the

data/lib/kobako/transport/yield.rb

@@ -67,7 +67,7 @@ module Kobako
         raise Codec::InvalidType, "YieldResponse must carry at least one byte" if bytes.empty?
 
         tag = bytes.getbyte(0) # : Integer
-        body = bytes.byteslice(1, bytes.bytesize - 1) || +""
+        body = bytes.byteslice(1, bytes.bytesize - 1) # : String
 
         reject_dead_tag!(tag)
         new(tag: tag, value: Codec::Decoder.decode(body))

data/lib/kobako/transport/yielder.rb

@@ -28,8 +28,8 @@ module Kobako
     # 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 (typically
-      # +Runtime#yield_to_active_invocation+ bound through a lambda) that
+      # +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+
       # throw tag the Dispatcher matches against to unwind the Service on
       # +tag 0x02+. +handler+ is the Sandbox's +Kobako::Catalog::Handles+,

data/lib/kobako/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Kobako
-  VERSION = "0.12.1"
+  VERSION = "0.13.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"