kobako 0.12.1-x86_64-linux → 0.12.2-x86_64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cbd9774c84737000b2be506f6a0334702ed103889df9ac26008f174973cb048e
-  data.tar.gz: 48dcbc87ab4227394ffd0efe751b338ac8b957c5a4979c56e0ee8f6fdc98e033
+  metadata.gz: 425bd29857c91850c1d3920343c44f11dbc425988cd4fb6c400ba638b8b02b1f
+  data.tar.gz: 1472552c0062fa1af7879f5e07a9ae54eaa74419ca7c66c6a253607b95388625
 SHA512:
-  metadata.gz: f7eb01555a4d46ba57359a643e8c43a493f6ae0a8f05119df3f3c2ab2b679bb6f1f3a07f06d27735a0c77e2b0d0b22ffb41464b3b63d4ed71ce355666d7e7e0a
-  data.tar.gz: 7e21e70dd618e3c3996b68ee68e463b8f5902ee19ed3e6e93eff4ea48f8084779e2c27e72c7f057ea57856e00ad596796a803d92e2e15a6959b3177c69cd682a
+  metadata.gz: 7f6faee72e9e29f491d08a8b2d08430127fc1da78aac834a09dccd833ab97f13cb26cd7360e9b6ce9ec323599152a57d8bdb38d744a968e0eadb7a7a3b0296d9
+  data.tar.gz: c425b0a041be572adf2f66faae10a66a38efce1142399d343d9c86e09308537a577a76f3a5399a3282319c3559970e8a9bb9a638c26cc6633a69998b2bf05630

data/.release-please-manifest.json

@@ -1 +1 @@
-{".":"0.12.1","wasm/kobako-core":"0.6.0","wasm/kobako":"0.6.0","wasm/kobako-io":"0.6.0","wasm/kobako-json":"0.6.0","wasm/kobako-regexp":"0.6.0","wasm/kobako-baker":"0.6.0"}
+{".":"0.12.2","wasm/kobako-core":"0.6.1","wasm/kobako":"0.6.1","wasm/kobako-io":"0.6.1","wasm/kobako-json":"0.6.1","wasm/kobako-regexp":"0.6.1","wasm/kobako-baker":"0.6.1","crates/kobako-runtime":"0.6.1","crates/kobako-wasmtime":"0.6.1"}

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## [0.12.2](https://github.com/elct9620/kobako/compare/v0.12.1...v0.12.2) (2026-07-02)
+
+
+### Bug Fixes
+
+* **codec:** bound ext-envelope nesting to keep deep Fault chains off the native stack ([7bed2b2](https://github.com/elct9620/kobako/commit/7bed2b2f43a63538aa60610c82d2eb65bcce7b15))
+* **guest:** size collection conversions by C array length, not #length ([90ecbd0](https://github.com/elct9620/kobako/commit/90ecbd0cb6a990b8c5a1e5deec3a10df4eaa37df))
+* **io:** enforce the fd allowlist at the write syscall ([1b300df](https://github.com/elct9620/kobako/commit/1b300df7bee8f87b701f76b42300163a8899b93e))
+* **release:** advance last-release-sha past the unparseable fork merge ([d06117d](https://github.com/elct9620/kobako/commit/d06117d462eea0ae5648e5bdd6886b735765f3b3))
+* **sandbox:** honor nil to disable the output caps, and validate them ([51d1e90](https://github.com/elct9620/kobako/commit/51d1e900e3d7d659ffd432ff3d613786e9073b05))
+
 ## [0.12.1](https://github.com/elct9620/kobako/compare/v0.12.0...v0.12.1) (2026-06-27)
 
 

data/README.md

@@ -127,7 +127,7 @@ end
 |---------------------------------|----------------|------------------------------------------------------|
 | `Kobako::TimeoutError`          | `TrapError`    | Per-invocation `timeout` exhausted                   |
 | `Kobako::MemoryLimitError`      | `TrapError`    | Per-invocation `memory_limit` exhausted              |
-| `Kobako::HandlerExhaustedError` | `SandboxError` | Handle counter reached its 2³¹ − 1 cap               |
+| `Kobako::HandleExhaustedError` | `SandboxError` | Handle counter reached its 2³¹ − 1 cap               |
 | `Kobako::BytecodeError`         | `SandboxError` | `#preload(binary:)` failed RITE validation at replay |
 
 `SandboxError` and `ServiceError` carry structured `origin` / `klass` / `backtrace_lines` / `details` fields when the guest produced a panic envelope.

data/crates/kobako-runtime/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## [0.6.1](https://github.com/elct9620/kobako/compare/kobako-runtime-v0.6.0...kobako-runtime-v0.6.1) (2026-07-02)
+
+
+### Miscellaneous Chores
+
+* **kobako-runtime:** Synchronize kobako crates versions

data/crates/kobako-runtime/README.md

@@ -0,0 +1,34 @@
+# kobako-runtime
+
+Engine-neutral host runtime contract for
+[kobako](https://github.com/elct9620/kobako), an in-process Wasm
+sandbox for running untrusted mruby scripts.
+
+A kobako host drives a Guest Binary through a wasm engine; this crate
+is the surface where the two meet, free of any engine or frontend
+type, so the engine stays swappable:
+
+- `runtime` — the `Runtime` trait: one guest invocation on a fresh
+  instance in, its observable `Snapshot` out
+- `snapshot` — the per-invocation observables: `Completion` (outcome
+  or trap), the two output `Capture`s, and resource `Usage`, uniform
+  across success and trap
+- `error` — the neutral failure channels: `Trap` (engine fault) and
+  `SetupError` (the invocation never started)
+- `dispatch` / `yielder` — the `DispatchHandler` and `Yielder` traits
+  a frontend supplies for guest→host dispatch and block-yield re-entry
+
+Engine implementations (such as `kobako-wasmtime`) implement
+`Runtime`; host frontends (such as the kobako Ruby gem's native ext)
+map the neutral types onto their own language surface.
+
+## Usage
+
+```toml
+[dependencies]
+kobako-runtime = "0.6.1" # x-release-please-version
+```
+
+## License
+
+Apache-2.0

data/crates/kobako-wasmtime/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## [0.6.1](https://github.com/elct9620/kobako/compare/kobako-wasmtime-v0.6.0...kobako-wasmtime-v0.6.1) (2026-07-02)
+
+
+### Miscellaneous Chores
+
+* **kobako-wasmtime:** Synchronize kobako crates versions

data/crates/kobako-wasmtime/README.md

@@ -0,0 +1,32 @@
+# kobako-wasmtime
+
+The [wasmtime](https://wasmtime.dev) implementation of the
+[kobako](https://github.com/elct9620/kobako) host runtime contract
+([`kobako-runtime`](https://crates.io/crates/kobako-runtime)).
+
+`Driver` implements the contract's `Runtime` trait over wasmtime and
+owns every engine-bound mechanic, so frontends see only the neutral
+contract surface:
+
+- process-wide Engine and compiled-Module caches with an on-disk AOT
+  (`.cwasm`) artifact cache keyed by Guest Binary content
+- a pre-linked `InstancePre` per guest path; every invocation runs on
+  a fresh instance and discards its Store afterwards
+- the epoch-based wall-clock timeout and the per-invocation
+  linear-memory cap
+- ambient denial: frozen WASI clocks and a constant RNG, so a guest
+  observes no real time and no real entropy
+
+The kobako Ruby gem's native ext is the first frontend; a Rust host
+SDK consumes the same surface.
+
+## Usage
+
+```toml
+[dependencies]
+kobako-wasmtime = "0.6.1" # x-release-please-version
+```
+
+## License
+
+Apache-2.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/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

@@ -89,7 +89,9 @@ module Kobako
     # 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,
+    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)
       @wasm_path = wasm_path || Kobako::Runtime.default_path
@@ -207,17 +209,17 @@ 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.
+    # 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 +228,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 +240,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
+    # unlike the +Snapshot+ (built only on success) the readout here also
+    # covers the trap path.
     #
     # The ext returns a positional 2-tuple +[wall_time, memory_peak]+
     # whose order matches the +Kobako::Usage+ field order; the
@@ -272,8 +274,8 @@ module Kobako
     # 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
+    # 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 rescue chain is the single trap-translation boundary —

data/lib/kobako/sandbox_options.rb

@@ -6,11 +6,13 @@ module Kobako
   # 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.
+  # The +initialize+ normalises every cap 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)
     # Default wall-clock timeout for a single invocation: 60 seconds.
     DEFAULT_TIMEOUT_SECONDS = 60.0
@@ -25,12 +27,12 @@ module Kobako
 
     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)
       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")
       super
     end
 
@@ -62,5 +64,19 @@ 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
   end
 end

data/lib/kobako/snapshot.rb

@@ -1,19 +1,19 @@
 # frozen_string_literal: true
 
 require_relative "capture"
-require_relative "usage"
 
 module Kobako
   # Kobako::Snapshot — per-invocation observable bundle returned from
   # +Kobako::Runtime#eval+ and +#run+.
   #
-  # The magnus class (see ext/kobako/src/snapshot.rs) carries seven raw
+  # The magnus class (see ext/kobako/src/snapshot.rs) carries five raw
   # readers: +return_bytes+, +stdout_bytes+, +stdout_truncated+,
-  # +stderr_bytes+, +stderr_truncated+, +wall_time+, +memory_peak+. This
-  # file reopens the class to add the Ruby-side helpers that pack those
-  # raw fields into the user-facing value objects +Kobako::Capture+ and
-  # +Kobako::Usage+ — the same shape +Kobako::Sandbox+ exposes to the
-  # Host App.
+  # +stderr_bytes+, +stderr_truncated+. This file reopens the class to add
+  # the Ruby-side helpers that pack those raw fields into the user-facing
+  # value object +Kobako::Capture+ — the same shape +Kobako::Sandbox+
+  # exposes to the Host App. Usage is not on the Snapshot; +Sandbox#usage+
+  # reads it from +Kobako::Runtime#usage+, which also covers the trap path
+  # where no Snapshot is produced.
   class Snapshot
     # Wrap the stdout capture pair (+stdout_bytes+, +stdout_truncated+)
     # as a +Kobako::Capture+ value object. The byte content never carries
@@ -28,11 +28,5 @@ module Kobako
     def stderr
       Capture.new(bytes: stderr_bytes, truncated: stderr_truncated)
     end
-
-    # Wrap the per-last-invocation usage pair (+wall_time+,
-    # +memory_peak+) as a +Kobako::Usage+ value object.
-    def usage
-      Usage.new(wall_time: wall_time, memory_peak: memory_peak)
-    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.12.2"
 end

data/release-please-config.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json",
   "release-type": "ruby",
-  "last-release-sha": "5694da60b08931ea260e13025689b8d8c47d767a",
+  "last-release-sha": "98509af508988f708bf0d7a76a718bb0428a177e",
   "packages": {
     ".": {
       "component": "kobako",
@@ -103,13 +103,58 @@
           "path": "/wasm/kobako-baker/README.md"
         }
       ]
+    },
+    "crates/kobako-runtime": {
+      "component": "kobako-runtime",
+      "release-type": "rust",
+      "extra-files": [
+        {
+          "type": "toml",
+          "path": "/crates/Cargo.lock",
+          "jsonpath": "$.package[?(@.name=='kobako-runtime')].version"
+        },
+        {
+          "type": "toml",
+          "path": "/Cargo.lock",
+          "jsonpath": "$.package[?(@.name=='kobako-runtime')].version"
+        },
+        {
+          "type": "generic",
+          "path": "/crates/kobako-runtime/README.md"
+        }
+      ]
+    },
+    "crates/kobako-wasmtime": {
+      "component": "kobako-wasmtime",
+      "release-type": "rust",
+      "extra-files": [
+        {
+          "type": "toml",
+          "path": "/crates/Cargo.lock",
+          "jsonpath": "$.package[?(@.name=='kobako-wasmtime')].version"
+        },
+        {
+          "type": "toml",
+          "path": "/Cargo.lock",
+          "jsonpath": "$.package[?(@.name=='kobako-wasmtime')].version"
+        },
+        {
+          "type": "toml",
+          "path": "/crates/kobako-wasmtime/Cargo.toml",
+          "jsonpath": "$.dependencies['kobako-runtime'].version"
+        },
+        {
+          "type": "generic",
+          "path": "/crates/kobako-wasmtime/README.md"
+        }
+      ]
     }
   },
   "plugins": [
     {
       "type": "linked-versions",
-      "groupName": "kobako guest crates",
-      "components": ["kobako-core", "kobako-rs", "kobako-io", "kobako-json", "kobako-regexp", "kobako-baker"]
+      "groupName": "kobako crates",
+      "components": ["kobako-core", "kobako-rs", "kobako-io", "kobako-json", "kobako-regexp", "kobako-baker", "kobako-runtime", "kobako-wasmtime"]
     }
   ],
   "extra-files": [

data/sig/kobako/codec/factory.rbs

@@ -8,6 +8,8 @@ module Kobako
       EXT_SYMBOL: Integer
       EXT_HANDLE: Integer
       EXT_ERRENV: Integer
+      MAX_EXT_DEPTH: Integer
+      EXT_DEPTH_KEY: Symbol
 
       def dump: (untyped value) -> String
       def load: (String bytes) -> untyped
@@ -26,6 +28,7 @@ module Kobako
       def unpack_handle: (String payload) -> Kobako::Handle
       def pack_fault: (Kobako::Fault fault) -> String
       def unpack_fault: (String payload) -> Kobako::Fault
+      def within_ext_frame: [T] (singleton(Kobako::Codec::Error) over_limit) { () -> T } -> T
     end
   end
 end

data/sig/kobako/errors.rbs

@@ -17,7 +17,7 @@ module Kobako
   class ModuleNotBuiltError < SetupError
   end
 
-  class SandboxError < Error
+  module StructuredError : Error
     attr_reader origin: String?
     attr_reader klass: String?
     attr_reader backtrace_lines: Array[String]?
@@ -32,22 +32,15 @@ module Kobako
     ) -> void
   end
 
-  class ServiceError < Error
-    attr_reader origin: String?
-    attr_reader klass: String?
-    attr_reader backtrace_lines: Array[String]?
-    attr_reader details: untyped
+  class SandboxError < Error
+    include StructuredError
+  end
 
-    def initialize: (
-      String message,
-      ?origin: String?,
-      ?klass: String?,
-      ?backtrace_lines: Array[String]?,
-      ?details: untyped
-    ) -> void
+  class ServiceError < Error
+    include StructuredError
   end
 
-  class HandlerExhaustedError < SandboxError
+  class HandleExhaustedError < SandboxError
   end
 
   class BytecodeError < SandboxError

data/sig/kobako/runtime.rbs

@@ -10,14 +10,19 @@ module Kobako
       Integer? stderr_limit_bytes
     ) -> Runtime
 
-    def on_dispatch=: (^(String) -> String dispatch_proc) -> void
-
-    def yield_to_active_invocation: (String args_bytes) -> String
+    def on_dispatch=: (^(String, Kobako::Transport::_GuestYielder) -> String dispatch_proc) -> void
 
     def eval: (String preamble, String source, String snippets) -> Kobako::Snapshot
 
     def run: (String preamble, String snippets, String envelope) -> Kobako::Snapshot
 
     def usage: () -> [Float, Integer]
+
+    # Frame-scoped guest re-entry handle the ext hands the dispatch Proc as
+    # its second argument; stands in as the +String -> String+ callable the
+    # host +Transport::Yielder+ invokes for a block yield.
+    class GuestYielder
+      def call: (String args_bytes) -> String
+    end
   end
 end

data/sig/kobako/sandbox.rbs

@@ -8,8 +8,8 @@ module Kobako
     # Forwarded to @options via Forwardable#def_delegators.
     def timeout: () -> Float?
     def memory_limit: () -> Integer?
-    def stdout_limit: () -> Integer
-    def stderr_limit: () -> Integer
+    def stdout_limit: () -> Integer?
+    def stderr_limit: () -> Integer?
 
     def initialize: (
       ?wasm_path: String?,

data/sig/kobako/sandbox_options.rbs

@@ -6,8 +6,8 @@ module Kobako
 
     attr_reader timeout: Float?
     attr_reader memory_limit: Integer?
-    attr_reader stdout_limit: Integer
-    attr_reader stderr_limit: Integer
+    attr_reader stdout_limit: Integer?
+    attr_reader stderr_limit: Integer?
 
     def self.new: (
       ?timeout: (Float | Integer)?,
@@ -28,5 +28,7 @@ module Kobako
     def normalize_timeout: ((Float | Integer)? timeout) -> Float?
 
     def normalize_memory_limit: (Integer? memory_limit) -> Integer?
+
+    def normalize_output_limit: (Integer? limit, String name) -> Integer?
   end
 end

data/sig/kobako/snapshot.rbs

@@ -5,11 +5,8 @@ module Kobako
     def stdout_truncated: () -> bool
     def stderr_bytes: () -> String
     def stderr_truncated: () -> bool
-    def wall_time: () -> Float
-    def memory_peak: () -> Integer
 
     def stdout: () -> Kobako::Capture
     def stderr: () -> Kobako::Capture
-    def usage: () -> Kobako::Usage
   end
 end

data/sig/kobako/transport/dispatcher.rbs

@@ -12,7 +12,7 @@ module Kobako
 
       CALLABLE_ALLOW: Array[Symbol]
 
-      def self?.dispatch: (String request_bytes, Kobako::Catalog::Namespaces namespaces, Kobako::Catalog::Handles handler, ^(String) -> String yield_to_guest) -> String
+      def self?.dispatch: (String request_bytes, Kobako::Catalog::Namespaces namespaces, Kobako::Catalog::Handles handler, Kobako::Transport::_GuestYielder yield_to_guest) -> String
 
       def self?.resolve_call_args: (Kobako::Transport::Request request, Kobako::Catalog::Handles handler) -> [Array[untyped], Hash[Symbol, untyped]]
 

data/sig/kobako/transport/run.rbs

@@ -17,9 +17,9 @@ module Kobako
 
       def normalize_entrypoint: (Symbol | String target) -> Symbol
 
-      def validate_args!: (Array[untyped] args) -> Array[untyped]
+      def validate_args!: (Array[untyped] args) -> void
 
-      def validate_kwargs!: (Hash[untyped, untyped] kwargs) -> Hash[Symbol, untyped]
+      def validate_kwargs!: (Hash[untyped, untyped] kwargs) -> void
 
       def forged_handle_message: (String slot) -> String
     end

data/sig/kobako/transport/yielder.rbs

@@ -1,12 +1,12 @@
 module Kobako
   module Transport
     class Yielder
-      @yield_to_guest: ^(String) -> String
+      @yield_to_guest: Kobako::Transport::_GuestYielder
       @break_tag: Symbol
       @handler: Kobako::Catalog::Handles
       @active: bool
 
-      def initialize: (^(String) -> String yield_to_guest, Symbol break_tag, Kobako::Catalog::Handles handler) -> void
+      def initialize: (Kobako::Transport::_GuestYielder yield_to_guest, Symbol break_tag, Kobako::Catalog::Handles handler) -> void
 
       def yield: (*untyped args) -> untyped
 

data/sig/kobako/transport.rbs

@@ -1,4 +1,12 @@
 module Kobako
   module Transport
+    # The guest re-entry callable a dispatch hands to a Yielder: invoked
+    # with the encoded yield args, it returns the encoded YieldResponse.
+    # The ext's Kobako::Runtime::GuestYielder is the production conformer;
+    # modelled structurally so the Transport layer needs no upward
+    # dependency on Runtime.
+    interface _GuestYielder
+      def call: (String) -> String
+    end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: kobako
 version: !ruby/object:Gem::Version
-  version: 0.12.1
+  version: 0.12.2
 platform: x86_64-linux
 authors:
 - Aotokitsuruya
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2026-06-27 00:00:00.000000000 Z
+date: 2026-07-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: msgpack
@@ -38,6 +38,10 @@ files:
 - LICENSE
 - README.md
 - SECURITY.md
+- crates/kobako-runtime/CHANGELOG.md
+- crates/kobako-runtime/README.md
+- crates/kobako-wasmtime/CHANGELOG.md
+- crates/kobako-wasmtime/README.md
 - data/kobako.wasm
 - lib/kobako.rb
 - lib/kobako/3.3/kobako.so