kobako 0.9.1-x86_64-linux → 0.10.0-x86_64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fab93ea70f79595c4c5cd7f155bb1337d62e71c4579f75b70654141078543b86
-  data.tar.gz: 70a69865ed1501dcf539261bfa6c09158c28214a6784b87aa3ac1a6d46ef2b4b
+  metadata.gz: 9a2f9fdb62d68dfbb45d5cc88705b056e869a1f8ea527444a74daae4e2c24a7a
+  data.tar.gz: f6fd31dfb518022be1ca9619f5343fdf5a671caeffe451514eb0cde039371c6e
 SHA512:
-  metadata.gz: d7e682bbe2cde22e04c25fffa94b5c9f2e024f3d6c0f9b368a45ee05c4ecd3bcc8c3c7ced054609a9644f7e34cf42ea33592acbd008f8202dba4853e9a0a98b0
-  data.tar.gz: 9cb3083092c7f596512c9cd3f8c9c55bfd4f3a137546e41b738ad02dce6a67e8e1452fa746e463a9be60443cac1c8ab4801e12bb04d4ee7b41ebc3a4425d151e
+  metadata.gz: 7c61b7745938ff9f51dbf821d2f317ffaf11631651f6bfad695e07824c03fd7013e2d39bac95d31a951fa2b50138575907ce83a35364f7948a6464ed37bac710
+  data.tar.gz: c05f84febfd37914fd4fa80d48aea10b7041bdf756d50da749f85f9697e2365a1853e80579399a0d564244514107a7bd62907c8261c978d2143a2b0b55a67141

data/.release-please-manifest.json

@@ -1 +1 @@
-{".":"0.9.1","wasm/kobako-core":"0.4.0","wasm/kobako":"0.4.0","wasm/kobako-io":"0.4.0","wasm/kobako-regexp":"0.4.0"}
+{".":"0.10.0","wasm/kobako-core":"0.5.0","wasm/kobako":"0.5.0","wasm/kobako-io":"0.5.0","wasm/kobako-regexp":"0.5.0","wasm/kobako-baker":"0.5.0"}

data/CHANGELOG.md

@@ -1,5 +1,41 @@
 # Changelog
 
+## [0.10.0](https://github.com/elct9620/kobako/compare/v0.9.2...v0.10.0) (2026-06-12)
+
+
+### Features
+
+* **catalog:** reject member binding after the seal (E-45) ([5193ed6](https://github.com/elct9620/kobako/commit/5193ed64100fa8ac05a2ba18cfa00634b4f40e6f))
+* **guest:** bake the canonical boot state and instantiate per invocation (B-49) ([ee9ae6e](https://github.com/elct9620/kobako/commit/ee9ae6e09eab30f54dba0eeec00a5a2c80da819f))
+* **pool:** add Kobako::Pool warm-Sandbox checkout (B-46..B-48) ([abf9bf8](https://github.com/elct9620/kobako/commit/abf9bf8d3c725c0ca0b8f2ab8b2ddd6f71ee6de4))
+
+
+### Bug Fixes
+
+* **ext:** give the ABI probe a WASI context ([18e21ea](https://github.com/elct9620/kobako/commit/18e21eac8b160ade2724578aeacd86170403ee2c))
+* **ext:** trust the artifact disk cache only in an exclusively writable directory ([17679cc](https://github.com/elct9620/kobako/commit/17679cc0d38d2a1b605e2faaeed762477a718c18))
+
+
+### Performance Improvements
+
+* **bench:** re-bless the anchor onto the post-0.9.2 performance round ([195224d](https://github.com/elct9620/kobako/commit/195224d5d48e53dc2be17752e6d6af6382a0c1ec))
+* **catalog:** drop the alloc-path block iteration from the gadget refusal ([542fe59](https://github.com/elct9620/kobako/commit/542fe59464bde57283d8e91984b82e82592bc3ab))
+* **ext:** amortise module compilation across processes via .cwasm cache ([2e688bc](https://github.com/elct9620/kobako/commit/2e688bc4a1cdf1d0d4d5a0bce2efb314a5b8d1f7))
+* **ext:** bound and harden the compiled-artifact cache ([949f222](https://github.com/elct9620/kobako/commit/949f2227af7cdf7d1913dcae58df683912a7dbd5))
+* **ext:** cache ABI export handles and per-path InstancePre ([47573d0](https://github.com/elct9620/kobako/commit/47573d022233c788ce94413d1a2901ee9d62fc2e))
+* **lib:** cache sealed frame encodings and cut decode-walk allocations ([e599573](https://github.com/elct9620/kobako/commit/e599573e37531b363baca83a1aa5833930100320))
+
+## [0.9.2](https://github.com/elct9620/kobako/compare/v0.9.1...v0.9.2) (2026-06-11)
+
+
+### Bug Fixes
+
+* **catalog:** never mint a Capability Handle for a reflective gadget ([6c2d29d](https://github.com/elct9620/kobako/commit/6c2d29d0fbcced5187df5538c2c6c437705fd6d8))
+* **ext:** cap stdin frames at 16 MiB like the run envelope ([a94099a](https://github.com/elct9620/kobako/commit/a94099a03830929c55fcb266e227073db9c5a624))
+* **ext:** deny guest ambient clock and entropy at the WASI layer ([1275b35](https://github.com/elct9620/kobako/commit/1275b35264813628a2aeb396a3546faf1f6d9d0c))
+* **transport:** reject reflective gadget methods in guest dispatch ([948fb9e](https://github.com/elct9620/kobako/commit/948fb9ea7d6c0d6bd91f6e261d3263743974388b))
+* **wasm:** mirror the reflection rejection in the guest proxy ([f6ead3b](https://github.com/elct9620/kobako/commit/f6ead3b91f1ac92c3c075397d177edb4b82cd15d))
+
 ## [0.9.1](https://github.com/elct9620/kobako/compare/v0.9.0...v0.9.1) (2026-06-11)
 
 

data/README.md

@@ -179,7 +179,8 @@ One Sandbox serves many invocations. Service bindings and preloaded snippets per
 
    ──────────────── invocation N ───────────────────
 
-     1. allocate fresh mrb_state
+     1. start from the canonical boot state
+        (mruby pre-initialized into the artifact at build time)
 
      2. replay snippets (in insertion order):
           :Adder     → defines Adder
@@ -189,7 +190,7 @@ One Sandbox serves many invocations. Service bindings and preloaded snippets per
 
      4. return value to host
 
-     5. discard mrb_state; reset per-invocation state:
+     5. discard the instance; reset per-invocation state:
           · Handles invalidated
           · stdout / stderr buffers cleared
           · memory delta zeroed
@@ -199,6 +200,25 @@ One Sandbox serves many invocations. Service bindings and preloaded snippets per
 
 For workloads that must be isolated from each other (one Sandbox per tenant, per student submission, per agent session), construct a fresh `Kobako::Sandbox` per scope — wasmtime's Engine and the compiled Module are cached at process scope, so additional Sandboxes amortize cold-start cost automatically.
 
+### Pooling
+
+For hosts that serve many short invocations, `Kobako::Pool` keeps a bounded set of warm, identically set-up Sandboxes and hands each one to a single exclusive holder at a time ([`docs/behavior.md`](docs/behavior.md) B-46..B-48). Construction forwards every `Sandbox.new` keyword verbatim; the optional block is the per-Sandbox setup window and runs exactly once per constructed Sandbox.
+
+```ruby
+pool = Kobako::Pool.new(slots: 4) do |sandbox|
+  sandbox.define(:KV).bind(:Lookup, ->(key) { redis.get(key) })
+end
+
+pool.with { |sandbox| sandbox.eval(%(KV::Lookup.call("user_42"))) }
+```
+
+| Option | Meaning | Default |
+|--------|---------|---------|
+| `slots:` | Upper bound on constructed Sandboxes | required |
+| `checkout_timeout:` | Seconds `#with` waits for a free Sandbox; `nil` waits indefinitely | 5.0 |
+
+Sandboxes construct lazily on first demand. `#with` yields a Sandbox with empty output buffers and returns the block's value; at block exit the Sandbox returns to the pool, except a block that raises `Kobako::TrapError` discards its Sandbox and the slot refills by a fresh construction on next demand. A checkout that waits past `checkout_timeout` raises `Kobako::PoolTimeoutError`. There is no teardown verb — a Pool releases everything with its own reachability.
+
 ### Service Blocks
 
 A Service method can accept a guest-supplied block via `&blk` and `yield` into it. The block body runs inside the Wasm guest; `break` / `next` / exceptions follow normal Ruby semantics, scoped to the single dispatch. See [`docs/behavior.md`](docs/behavior.md) B-23..B-30.
@@ -248,7 +268,7 @@ This is deliberate, not a leak. Handle IDs run to 2³¹ − 1 per invocation and
 
 ### Snippets & Entrypoints
 
-`Sandbox#preload` registers named mruby snippets that replay against the fresh `mrb_state` before every invocation; `Sandbox#run(:Target, *args, **kwargs)` dispatches into a top-level `Object` constant defined by those snippets ([`docs/behavior.md`](docs/behavior.md) B-31..B-33).
+`Sandbox#preload` registers named mruby snippets that replay into every invocation's canonical boot state; `Sandbox#run(:Target, *args, **kwargs)` dispatches into a top-level `Object` constant defined by those snippets ([`docs/behavior.md`](docs/behavior.md) B-31..B-33).
 
 ```ruby
 sandbox = Kobako::Sandbox.new
@@ -262,7 +282,7 @@ sandbox.run(:Greeter, name: "world") # => "hello, world"
 ```
    per-invocation replay (every #eval / #run, snippets in insertion order):
 
-      fresh mrb_state
+      canonical boot state
             │
             ├──▶ replay :Adder            (defines Adder)
             │
@@ -271,7 +291,7 @@ sandbox.run(:Greeter, name: "world") # => "hello, world"
             └──▶ eval(source)  -or-  run(:Target, *args, **kwargs)
                        │
                        ▼
-                  return value, then mrb_state discarded
+                  return value, then instance discarded
 ```
 
 `#preload` accepts two payload forms:
@@ -312,15 +332,16 @@ Order-of-magnitude figures on macOS arm64, Ruby 3.4.7, YJIT off. Absolute values
 
 | Phase                                                        | Cost                  |
 |--------------------------------------------------------------|-----------------------|
-| First `Sandbox.new` in a fresh process (Engine + Module JIT) | ~600 ms one-time      |
-| Subsequent `Sandbox.new` (Engine cache warm)                 | ~125 µs               |
-| Warm `#eval("nil")` on a reused Sandbox                      | ~135 µs               |
-| Warm `#run(:Entrypoint, ...)` dispatch                       | ~165 µs               |
-| Service call amortized inside one invocation                 | ~6.7 µs               |
-| Snippet replay per invocation                                | ~7-9 µs each          |
-| Per additional Sandbox (RSS)                                 | ~570 KB               |
-
-Construct one Sandbox at boot so the ~600 ms JIT cost lands off the request hot path. `ext/` does not release the GVL during wasmtime execution, so wasm work is GVL-serialized: aggregate throughput stays around 7-8k `#eval`/s regardless of Thread count, though Ruby-side `#eval` setup still overlaps. A +10% regression on any of the six SPEC-mandated benchmarks blocks release.
+| First `Sandbox.new` ever for a Guest Binary (Module JIT, then disk-cached) | ~500 ms once per machine |
+| First `Sandbox.new` in a fresh process (`.cwasm` cache warm) | ~5 ms one-time        |
+| Subsequent `Sandbox.new` (caches warm)                       | ~30 µs                |
+| Warm `#eval("nil")` on a reused Sandbox                      | ~73 µs                |
+| Warm `#run(:Entrypoint, ...)` dispatch                       | ~104 µs               |
+| Service call amortized inside one invocation                 | ~6.8 µs               |
+| Snippet replay per invocation                                | ~8 µs each            |
+| Per additional idle Sandbox (RSS)                            | ~1 KB                 |
+
+The Cranelift JIT runs once per machine and gem version — the compiled artifact persists in a `.cwasm` disk cache, so later processes deserialize in milliseconds. An idle Sandbox holds no wasm instance (the canonical boot state is baked into the artifact and instantiated per invocation), which is why a thousand idle tenants cost ~32 MB total. `ext/` does not release the GVL during wasmtime execution, so wasm work is GVL-serialized: aggregate throughput stays around 16k `#eval`/s regardless of Thread count, though Ruby-side `#eval` setup still overlaps. A +10% regression on any of the six SPEC-mandated benchmarks blocks release.
 
 Regexp is an opt-in capability gem, excluded from the default binary and the gated set; its throughput is tracked in a separate non-gated characterization (`#10` in [`benchmark/README.md`](benchmark/README.md)). There `=~` (~5 µs/match) costs about 4× `match?` (~1.2 µs), because `=~` eagerly builds the `MatchData` and match globals — prefer `match?` for boolean tests.
 

data/lib/kobako/catalog/handles.rb

@@ -53,14 +53,9 @@ module Kobako
       # is reserved for the codec's wire-decode path, where the id is
       # the only thing the bytes carry.
       def alloc(object)
+        reject_unwrappable!(object)
+        ensure_capacity!
         id = @next_id
-        cap = Kobako::Handle::MAX_ID
-        if id > cap
-          raise HandlerExhaustedError,
-                "Out of handle allocations: too many host objects were referenced " \
-                "in a single invocation (limit #{cap})"
-        end
-
         @entries[id] = object
         @next_id = id + 1
         Kobako::Handle.restore(id)
@@ -94,6 +89,30 @@ module Kobako
 
       private
 
+      # Refuse to mint a Capability Handle for a reflective gadget
+      # ({docs/behavior.md B-43}[link:../../../docs/behavior.md]): a +Binding+ /
+      # +Method+ / +UnboundMethod+ would hand the guest a callable proxy onto
+      # host reflection (a returned +Binding+ reaches +Binding#eval+). Raising
+      # here keeps the rule at the single mint point, so it holds on both the
+      # Service-return (B-14) and the +#run+ host→guest auto-wrap (B-34) paths.
+      def reject_unwrappable!(object)
+        case object
+        when Binding, Method, UnboundMethod
+          raise SandboxError, "a #{object.class} cannot cross as a Capability Handle"
+        end
+      end
+
+      # Guard {#alloc} against issuing an ID past the B-21 cap. Returns +nil+
+      # on success; raises +Kobako::HandlerExhaustedError+ at exhaustion.
+      def ensure_capacity!
+        cap = Kobako::Handle::MAX_ID
+        return unless @next_id > cap
+
+        raise HandlerExhaustedError,
+              "Out of handle allocations: too many host objects were referenced " \
+              "in a single invocation (limit #{cap})"
+      end
+
       # Single source of truth for the "unknown Handle id" raise used by
       # {#fetch}. Returns +nil+ on success; raises +Kobako::SandboxError+
       # when +id+ is not currently bound.

data/lib/kobako/catalog/namespaces.rb

@@ -3,7 +3,6 @@
 require_relative "handles"
 require_relative "../codec"
 require_relative "../errors"
-require_relative "../transport/request"
 require_relative "../namespace"
 
 module Kobako
@@ -38,6 +37,7 @@ module Kobako
         @namespaces = {} # : Hash[String, Kobako::Namespace]
         @handler = handler
         @sealed = false
+        @encoded = nil # : String?
       end
 
       # Declare or retrieve the Namespace named +name+ (idempotent —
@@ -81,14 +81,32 @@ module Kobako
       # Arrays, so none of the kobako ext types actually fire. Structure:
       # +[["Namespace", ["MemberA", "MemberB"]], ...]+. Returns a binary
       # +String+ of msgpack bytes.
+      #
+      # Once sealed, the bytes are computed once and reused for every
+      # subsequent invocation: B-33 seals Service registration (B-07 /
+      # B-08) at the 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+ (E-45)
+      # and never alters Frame 1.
       def encode
-        Codec::Encoder.encode(@namespaces.values.map(&:to_preamble))
+        return @encoded if @encoded
+
+        bytes = Codec::Encoder.encode(@namespaces.values.map(&:to_preamble)).freeze
+        @encoded = bytes if @sealed
+        bytes
       end
 
-      # Mark the registry as sealed. Called by +Sandbox+ on the first
-      # invocation. After sealing, #define raises ArgumentError. Idempotent.
+      # Mark the registry as sealed and propagate the seal to every
+      # declared +Kobako::Namespace+
+      # ({docs/behavior.md B-33}[link:../../../docs/behavior.md]). Called
+      # by +Sandbox+ on the first invocation. After sealing, #define
+      # raises ArgumentError (E-18) and +Namespace#bind+ raises
+      # ArgumentError (E-45). Idempotent.
       def seal!
+        return self if @sealed
+
         @sealed = true
+        @namespaces.each_value(&:seal!)
         self
       end
 

data/lib/kobako/catalog/snippets.rb

@@ -31,6 +31,7 @@ module Kobako
 
       def initialize
         @entries = [] # : Array[Kobako::Snippet::Source | Kobako::Snippet::Binary]
+        @encoded = nil # : String?
       end
 
       # Serialize the registered snippets to wire bytes. Each entry
@@ -42,8 +43,14 @@ module Kobako
       # carriers — this collection-tier method reads their attributes
       # externally via +entry_payload+ rather than asking each entry to
       # self-encode.
+      #
+      # The bytes are memoized — the table is replayed verbatim on every
+      # invocation after B-33 seals it, so Frame 3 never changes between
+      # encodes; {#register} drops the memo while the table is still open.
       def encode
-        Codec::Encoder.encode(@entries.map { |entry| entry_payload(entry) })
+        return @encoded if @encoded
+
+        @encoded = Codec::Encoder.encode(@entries.map { |entry| entry_payload(entry) }).freeze
       end
 
       # Register one preloaded snippet in either of two forms
@@ -68,6 +75,7 @@ module Kobako
       # missing keywords, wrong types, malformed +name+ (E-34), or
       # duplicate +code:+ +name+ (E-33).
       def register(code: nil, name: nil, binary: nil)
+        @encoded = nil
         if binary
           raise ArgumentError, "cannot combine binary: with code: / name:" if code || name
 

data/lib/kobako/codec/decoder.rb

@@ -64,7 +64,11 @@ module Kobako
           case value
           when String then Utils.assert_utf8!(value, "str payload") if value.encoding == Encoding::UTF_8
           when Array  then value.each { |v| validate_utf8!(v) }
-          when Hash   then value.each { |pair| validate_utf8!(pair) }
+          when Hash
+            value.each do |key, val|
+              validate_utf8!(key)
+              validate_utf8!(val)
+            end
           end
         end
       end

data/lib/kobako/codec.rb

@@ -1,6 +1,10 @@
 # frozen_string_literal: true
 
 require_relative "codec/error"
+require_relative "codec/utils"
+require_relative "codec/factory"
+require_relative "codec/encoder"
+require_relative "codec/decoder"
 
 module Kobako
   # Host-side MessagePack codec for the kobako wire contract — the
@@ -17,15 +21,10 @@ 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-wasm+ crate;
+  # mirrors this layer as the +codec+ module in the +kobako-core+ 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.
   module Codec
   end
 end
-
-require_relative "codec/utils"
-require_relative "codec/factory"
-require_relative "codec/encoder"
-require_relative "codec/decoder"

data/lib/kobako/errors.rb

@@ -21,7 +21,7 @@ module Kobako
   #                       call that failed and was not rescued inside the
   #                       script).
   #
-  # A fourth branch sits outside the invocation taxonomy:
+  # 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
@@ -29,6 +29,9 @@ module Kobako
   #                       ({docs/behavior.md E-40 / E-41}[link:../../docs/behavior.md]).
   #                       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+
+  #                       ({docs/behavior.md E-46}[link:../../docs/behavior.md]).
   #
   # Subclasses pinned by docs/behavior.md Error Classes:
   #
@@ -137,4 +140,11 @@ module Kobako
   # snippet failures while callers wanting bytecode-specific handling
   # can `rescue Kobako::BytecodeError` directly.
   class BytecodeError < SandboxError; end
+
+  # Pool checkout layer. Raised by +Kobako::Pool#with+ when the checkout
+  # wait exceeded the configured +checkout_timeout+ while every slot was
+  # held ({docs/behavior.md E-46}[link:../../docs/behavior.md]). No
+  # Sandbox state is touched — retrying succeeds as soon as a holder
+  # returns its Sandbox.
+  class PoolTimeoutError < Error; end
 end

data/lib/kobako/namespace.rb

@@ -18,15 +18,20 @@ module Kobako
     def initialize(name)
       @name = name
       @members = {} # : Hash[String, untyped]
+      @sealed = false
     end
 
     # Bind +object+ under +member+ inside this Namespace. +member+ is a
     # constant-form name as a +Symbol+ or +String+. +object+ is any Ruby
     # object that responds to the methods guest code will invoke. Returns
     # +self+ for chaining. Raises +ArgumentError+ when +member+ does not
-    # match the constant pattern, or a Member of the same name is already
-    # bound ({docs/behavior.md B-11}[link:../../docs/behavior.md]).
+    # match the constant pattern, when a Member of the same name is
+    # already bound ({docs/behavior.md B-11}[link:../../docs/behavior.md]),
+    # or when the owning Sandbox's first invocation has sealed Service
+    # registration ({docs/behavior.md E-45}[link:../../docs/behavior.md]).
     def bind(member, object)
+      raise ArgumentError, "cannot bind after first Sandbox invocation" if @sealed
+
       member_str = validate_member_name!(member)
       raise ArgumentError, "Member #{@name}::#{member_str} is already bound" if @members.key?(member_str)
 
@@ -34,6 +39,15 @@ module Kobako
       self
     end
 
+    # Mark this Namespace as sealed ({docs/behavior.md B-33}[link:../../docs/behavior.md]).
+    # Called by +Kobako::Catalog::Namespaces#seal!+ on the owning
+    # Sandbox's first invocation; afterwards {#bind} raises
+    # +ArgumentError+ (E-45). Idempotent; returns +self+.
+    def seal!
+      @sealed = true
+      self
+    end
+
     # Member lookup; raises +KeyError+ when no Member is registered
     # under +member+.
     def fetch(member)

data/lib/kobako/pool.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+require_relative "sandbox"
+
+module Kobako
+  # Kobako::Pool — a bounded set of warm, identically set-up Sandboxes
+  # handed out one exclusive holder at a time
+  # ({docs/behavior.md B-46..B-48}[link:../../docs/behavior.md]).
+  #
+  # Construction forwards every +Kobako::Sandbox.new+ keyword verbatim
+  # and holds the optional block as the per-Sandbox setup hook; a
+  # checkout prefers an idle Sandbox and constructs a new one only when
+  # none is idle and fewer than +slots+ exist (B-46). +#with+ blocks up
+  # to +checkout_timeout+ seconds when every slot is held (E-46), applies
+  # the +TrapError+ discard-and-recreate contract at checkin (B-47), and
+  # the Pool releases everything with its own reachability — there is no
+  # teardown verb (B-48).
+  class Pool
+    # The +#with+ wait bound applied when +checkout_timeout+ is not given
+    # ({docs/behavior.md B-46}[link:../../docs/behavior.md]).
+    DEFAULT_CHECKOUT_TIMEOUT_SECONDS = 5.0
+
+    # Build a Pool of up to +slots+ Sandboxes
+    # ({docs/behavior.md B-46}[link:../../docs/behavior.md]). +slots+ is
+    # a positive Integer; +checkout_timeout+ bounds the +#with+ wait in
+    # seconds (+nil+ waits indefinitely); every other keyword is
+    # forwarded verbatim to +Kobako::Sandbox.new+. The optional block
+    # runs exactly once per constructed Sandbox — it is the setup window
+    # for +#define+ / +#preload+ before that Sandbox's first checkout.
+    # No Sandbox is constructed here. Raises +ArgumentError+ for an
+    # invalid +slots+ / +checkout_timeout+
+    # ({docs/behavior.md E-47}[link:../../docs/behavior.md]).
+    def initialize(slots:, checkout_timeout: DEFAULT_CHECKOUT_TIMEOUT_SECONDS, **sandbox_options, &setup)
+      validate_slots!(slots)
+      @slots = slots
+      @checkout_timeout = normalize_checkout_timeout(checkout_timeout)
+      @sandbox_options = sandbox_options
+      @setup = setup
+      @idle = [] # : Array[Kobako::Sandbox]
+      @constructed = 0
+      @mutex = Mutex.new
+      @slot_freed = ConditionVariable.new
+    end
+
+    # Yield one exclusively-held Sandbox to the block and return the
+    # block's value ({docs/behavior.md B-47}[link:../../docs/behavior.md]).
+    # Blocks while every slot is held; raises +Kobako::PoolTimeoutError+
+    # once the wait exceeds +checkout_timeout+
+    # ({docs/behavior.md E-46}[link:../../docs/behavior.md]). The Sandbox
+    # returns to the pool at block exit — unless the block raised
+    # +Kobako::TrapError+, in which case the unrecoverable Sandbox is
+    # discarded and its slot refills by a fresh construction on next
+    # demand.
+    def with
+      sandbox = checkout
+      begin
+        yield sandbox
+      rescue TrapError
+        release_capacity!
+        sandbox = nil
+        raise
+      ensure
+        checkin(sandbox) if sandbox
+      end
+    end
+
+    private
+
+    # Acquire a Sandbox and hand it over in pre-invocation state — empty
+    # output buffers and truncation predicates false (B-47).
+    def checkout
+      acquire.tap(&:reset_invocation_state!)
+    end
+
+    # The idle-first claim loop (B-46): an idle Sandbox wins, unclaimed
+    # capacity constructs, and a full pool waits for a checkin.
+    def acquire
+      timeout = @checkout_timeout
+      deadline = timeout && (monotonic_now + timeout)
+      loop do
+        action, sandbox = claim_or_wait(deadline)
+        return sandbox if action == :idle && sandbox
+        return construct_slot if action == :build
+      end
+    end
+
+    # Single locked decision point for one claim attempt. Waiting
+    # happens inside the lock (so a checkin can wake it); construction
+    # happens outside (so a slow setup block never holds the lock) —
+    # capacity is reserved here and released by +construct_slot+ on
+    # failure.
+    def claim_or_wait(deadline)
+      @mutex.synchronize do
+        return [:idle, @idle.pop] unless @idle.empty?
+
+        if @constructed < @slots
+          @constructed += 1
+          return [:build, nil]
+        end
+
+        await_slot!(deadline)
+        [:retry, nil]
+      end
+    end
+
+    # Wait for a checkin or freed capacity; raises
+    # +Kobako::PoolTimeoutError+ once +deadline+ has passed (E-46). Must
+    # run while holding +@mutex+.
+    def await_slot!(deadline)
+      remaining = deadline && (deadline - monotonic_now)
+      if remaining && remaining <= 0
+        raise PoolTimeoutError,
+              "no Sandbox returned within #{@checkout_timeout}s: all #{@slots} slots are held"
+      end
+
+      @slot_freed.wait(@mutex, remaining)
+    end
+
+    # Construct and set up one pooled Sandbox against the capacity
+    # reserved by +claim_or_wait+. Construction and setup-block errors
+    # propagate to the checkout caller unchanged (B-46); the reserved
+    # capacity is released so a later checkout can retry.
+    def construct_slot
+      done = false
+      sandbox = Sandbox.new(**@sandbox_options)
+      @setup&.call(sandbox)
+      done = true
+      sandbox
+    ensure
+      release_capacity! unless done
+    end
+
+    # Return a Sandbox to the idle list and wake one waiting checkout.
+    def checkin(sandbox)
+      @mutex.synchronize do
+        @idle.push(sandbox)
+        @slot_freed.signal
+      end
+    end
+
+    # Give back reserved-but-unfilled capacity — a failed construction or
+    # a discarded Sandbox — and wake one waiting checkout to claim it.
+    def release_capacity!
+      @mutex.synchronize do
+        @constructed -= 1
+        @slot_freed.signal
+      end
+    end
+
+    # The wait deadline runs on the monotonic clock so a wall-clock jump
+    # cannot stretch or cut the checkout wait.
+    def monotonic_now
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    # E-47 pre-flight for +slots+ — no coercion, a positive Integer is
+    # the only accepted shape.
+    def validate_slots!(slots)
+      return if slots.is_a?(Integer) && slots.positive?
+
+      raise ArgumentError, "slots must be a positive Integer, got #{slots.inspect}"
+    end
+
+    # Coerce +checkout_timeout+ into the Float seconds the wait loop
+    # consumes, or +nil+ to wait indefinitely — the E-39 normalisation
+    # idiom applied to E-47.
+    def normalize_checkout_timeout(checkout_timeout)
+      return nil if checkout_timeout.nil?
+      unless checkout_timeout.is_a?(Numeric)
+        raise ArgumentError, "checkout_timeout must be Numeric or nil, got #{checkout_timeout.inspect}"
+      end
+
+      seconds = checkout_timeout.to_f
+      unless seconds.positive? && seconds.finite?
+        raise ArgumentError, "checkout_timeout must be > 0 and finite (got #{checkout_timeout})"
+      end
+
+      seconds
+    end
+  end
+end

data/lib/kobako/sandbox.rb

@@ -206,6 +206,22 @@ module Kobako
       end
     end
 
+    # Reset all per-invocation observable state to its pre-invocation
+    # sentinels — both per-channel captures
+    # ({docs/behavior.md B-05}[link:../../docs/behavior.md]) and the
+    # per-last-invocation usage record
+    # ({docs/behavior.md B-35}[link:../../docs/behavior.md]). Shared by
+    # +#initialize+ (first-time setup) and +#begin_invocation!+
+    # (between-invocation reset) so both paths agree on what
+    # "pre-invocation state" means; +Kobako::Pool+ calls it at checkout
+    # so a pooled Sandbox hands over empty output buffers
+    # ({docs/behavior.md B-47}[link:../../docs/behavior.md]).
+    def reset_invocation_state!
+      @stdout_capture = Capture::EMPTY
+      @stderr_capture = Capture::EMPTY
+      @usage = Usage::EMPTY
+    end
+
     private
 
     # Configure the +Runtime+'s host↔guest dispatch wiring
@@ -237,20 +253,6 @@ module Kobako
       reset_invocation_state!
     end
 
-    # Reset all per-invocation observable state to its pre-invocation
-    # sentinels — both per-channel captures
-    # ({docs/behavior.md B-05}[link:../../docs/behavior.md]) and the
-    # per-last-invocation usage record
-    # ({docs/behavior.md B-35}[link:../../docs/behavior.md]). Shared by
-    # +#initialize+ (first-time setup) and +#begin_invocation!+
-    # (between-invocation reset) so both paths agree on what
-    # "pre-invocation state" means.
-    def reset_invocation_state!
-      @stdout_capture = Capture::EMPTY
-      @stderr_capture = Capture::EMPTY
-      @usage = Usage::EMPTY
-    end
-
     # Read the per-last-invocation +wall_time+ and +memory_peak+ from
     # the ext and wrap them as a +Kobako::Usage+ value object
     # ({docs/behavior.md B-35}[link:../../docs/behavior.md]). Runs in

data/lib/kobako/transport/dispatcher.rb

@@ -46,13 +46,28 @@ module Kobako
       # metaprogramming surface (+send+, +public_send+, +instance_eval+,
       # +method+, +tap+, +instance_variable_get+, ...) rather than Service
       # behaviour. A guest-supplied method name resolving to one of these is
-      # rejected: the security contract is that only methods the bound object
-      # itself defines are reachable, and +public_send(:send, ...)+ would
-      # otherwise let a guest pivot through +send+ into the private
-      # +Kernel#eval+ / +#system+ surface (host RCE).
+      # rejected ({docs/behavior.md B-42}[link:../../../docs/behavior.md]):
+      # only methods the bound object itself exposes as Service behaviour are
+      # reachable, and +public_send(:send, ...)+ would otherwise let a guest
+      # pivot through +send+ into the private +Kernel#eval+ / +#system+
+      # surface (host RCE).
       META_OWNERS = [BasicObject, Kernel, Object, Module, Class].freeze
       private_constant :META_OWNERS
 
+      # 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
+      # lambda stays invocable, its reflective surface does not (B-42).
+      GADGET_OWNERS = [Proc, Method, UnboundMethod, Binding].freeze
+      private_constant :GADGET_OWNERS
+
+      # 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
+      private_constant :CALLABLE_ALLOW
+
       # Dispatch a single transport request and return the encoded
       # Response bytes ({docs/behavior.md B-12}[link:../../../docs/behavior.md]).
       # Invoked from the +Runtime#on_dispatch+ Proc that
@@ -131,14 +146,18 @@ module Kobako
       end
 
       # Guard the +public_send+ below against ambient reflection methods
-      # (see {META_OWNERS}). A concretely-defined public method whose owner
-      # is a meta module is rejected; 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 meta methods
-      # are all concretely defined and therefore never reach that branch.
+      # ({docs/behavior.md B-42}[link:../../../docs/behavior.md]). 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
+      # concretely defined and therefore never reach that branch.
       def reject_meta_method!(target, name)
         owner = target.public_method(name).owner
-        return unless META_OWNERS.include?(owner)
+        gadget = GADGET_OWNERS.include?(owner)
+        return unless META_OWNERS.include?(owner) || gadget
+        return if gadget && CALLABLE_ALLOW.include?(name)
 
         raise UndefinedTargetError, "method #{name.inspect} is not a Service method"
       rescue NameError

data/lib/kobako/transport/request.rb

@@ -5,16 +5,8 @@ require_relative "../codec"
 
 module Kobako
   # See lib/kobako/transport.rb for the umbrella module doc; this file
-  # owns the Request value object and its +#encode+ / +.decode+ codec,
-  # plus the +STATUS_OK+ / +STATUS_ERROR+ constants shared with Response.
+  # owns the Request value object and its +#encode+ / +.decode+ codec.
   module Transport
-    # ---------------- Response status bytes (docs/wire-contract.md § Response Shape) ---
-
-    # Response variant marker for the success branch.
-    STATUS_OK    = 0
-    # Response variant marker for the fault branch.
-    STATUS_ERROR = 1
-
     # Value object for a single guest-initiated Transport Request
     # ({docs/wire-codec.md Envelope Encoding → Request}[link:../../../docs/wire-codec.md]).
     #

data/lib/kobako/transport/response.rb

@@ -2,12 +2,19 @@
 
 require_relative "../codec"
 require_relative "../fault"
-require_relative "request"
 
 module Kobako
   # See lib/kobako/transport.rb for the umbrella module doc; this file
-  # owns the Response value object and its +#encode+ / +.decode+ codec.
+  # owns the Response value object and its +#encode+ / +.decode+ codec,
+  # plus the +STATUS_OK+ / +STATUS_ERROR+ status bytes.
   module Transport
+    # ---------------- Response status bytes (docs/wire-contract.md § Response Shape) ---
+
+    # Response variant marker for the success branch.
+    STATUS_OK    = 0
+    # Response variant marker for the fault branch.
+    STATUS_ERROR = 1
+
     # Value object for a single host-side Transport Response
     # ({docs/wire-codec.md Envelope Encoding → Response}[link:../../../docs/wire-codec.md]).
     #

data/lib/kobako/version.rb

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

data/lib/kobako.rb

@@ -15,3 +15,4 @@ require_relative "kobako/catalog"
 require_relative "kobako/runtime"
 require_relative "kobako/snapshot"
 require_relative "kobako/sandbox"
+require_relative "kobako/pool"

data/release-please-config.json

@@ -7,8 +7,7 @@
       "component": "kobako",
       "include-component-in-tag": false,
       "release-type": "ruby",
-      "exclude-paths": ["wasm"],
-      "release-as": "0.9.1"
+      "exclude-paths": ["wasm"]
     },
     "wasm/kobako-core": {
       "component": "kobako-core",
@@ -74,13 +73,28 @@
           "path": "/wasm/kobako-regexp/README.md"
         }
       ]
+    },
+    "wasm/kobako-baker": {
+      "component": "kobako-baker",
+      "release-type": "rust",
+      "extra-files": [
+        {
+          "type": "toml",
+          "path": "/wasm/kobako-baker/Cargo.lock",
+          "jsonpath": "$.package[?(@.name=='kobako-baker')].version"
+        },
+        {
+          "type": "generic",
+          "path": "/wasm/kobako-baker/README.md"
+        }
+      ]
     }
   },
   "plugins": [
     {
       "type": "linked-versions",
       "groupName": "kobako guest crates",
-      "components": ["kobako-core", "kobako-rs", "kobako-io", "kobako-regexp"]
+      "components": ["kobako-core", "kobako-rs", "kobako-io", "kobako-regexp", "kobako-baker"]
     }
   ],
   "extra-files": [

data/sig/kobako/catalog/handles.rbs

@@ -13,6 +13,10 @@ module Kobako
 
       private
 
+      def reject_unwrappable!: (untyped object) -> void
+
+      def ensure_capacity!: () -> void
+
       def require_bound!: (Integer id) -> void
     end
   end

data/sig/kobako/errors.rbs

@@ -52,4 +52,7 @@ module Kobako
 
   class BytecodeError < SandboxError
   end
+
+  class PoolTimeoutError < Error
+  end
 end

data/sig/kobako/namespace.rbs

@@ -8,6 +8,8 @@ module Kobako
 
     def bind: (Symbol | String member, untyped object) -> self
 
+    def seal!: () -> self
+
     def fetch: (Symbol | String member) -> untyped
 
     def to_preamble: () -> [String, Array[String]]

data/sig/kobako/pool.rbs

@@ -0,0 +1,44 @@
+module Kobako
+  class Pool
+    DEFAULT_CHECKOUT_TIMEOUT_SECONDS: Float
+
+    @slots: Integer
+    @checkout_timeout: Float?
+    @sandbox_options: Hash[Symbol, untyped]
+    @setup: ^(Kobako::Sandbox) -> void | nil
+    @idle: Array[Kobako::Sandbox]
+    @constructed: Integer
+    @mutex: Thread::Mutex
+    @slot_freed: Thread::ConditionVariable
+
+    def initialize: (
+      slots: Integer,
+      ?checkout_timeout: (Float | Integer)?,
+      **untyped sandbox_options
+    ) ?{ (Kobako::Sandbox) -> void } -> void
+
+    def with: [T] () { (Kobako::Sandbox) -> T } -> T
+
+    private
+
+    def checkout: () -> Kobako::Sandbox
+
+    def acquire: () -> Kobako::Sandbox
+
+    def claim_or_wait: (Float? deadline) -> [Symbol, Kobako::Sandbox?]
+
+    def await_slot!: (Float? deadline) -> void
+
+    def construct_slot: () -> Kobako::Sandbox
+
+    def checkin: (Kobako::Sandbox sandbox) -> void
+
+    def release_capacity!: () -> void
+
+    def monotonic_now: () -> Float
+
+    def validate_slots!: (untyped slots) -> void
+
+    def normalize_checkout_timeout: ((Float | Integer)? checkout_timeout) -> Float?
+  end
+end

data/sig/kobako/sandbox.rbs

@@ -38,12 +38,12 @@ module Kobako
 
     def eval: (String code) -> untyped
 
+    def reset_invocation_state!: () -> void
+
     private
 
     def install_dispatch_proc!: () -> void
 
-    def reset_invocation_state!: () -> void
-
     def begin_invocation!: () -> void
 
     def read_usage!: () -> void

data/sig/kobako/transport/dispatcher.rbs

@@ -8,6 +8,10 @@ module Kobako
 
       META_OWNERS: Array[Module]
 
+      GADGET_OWNERS: Array[Module]
+
+      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?.resolve_call_args: (Kobako::Transport::Request request, Kobako::Catalog::Handles handler) -> [Array[untyped], Hash[Symbol, untyped]]

data/sig/kobako/transport/request.rbs

@@ -1,8 +1,5 @@
 module Kobako
   module Transport
-    STATUS_OK: Integer
-    STATUS_ERROR: Integer
-
     class Request < Data
       attr_reader target: String | Kobako::Handle
       attr_reader method_name: String

data/sig/kobako/transport/response.rbs

@@ -1,5 +1,8 @@
 module Kobako
   module Transport
+    STATUS_OK: Integer
+    STATUS_ERROR: Integer
+
     class Response < Data
       attr_reader status: Integer
       attr_reader payload: untyped

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: kobako
 version: !ruby/object:Gem::Version
-  version: 0.9.1
+  version: 0.10.0
 platform: x86_64-linux
 authors:
 - Aotokitsuruya
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2026-06-11 00:00:00.000000000 Z
+date: 2026-06-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: msgpack
@@ -59,6 +59,7 @@ files:
 - lib/kobako/namespace.rb
 - lib/kobako/outcome.rb
 - lib/kobako/outcome/panic.rb
+- lib/kobako/pool.rb
 - lib/kobako/runtime.rb
 - lib/kobako/sandbox.rb
 - lib/kobako/sandbox_options.rb
@@ -96,6 +97,7 @@ files:
 - sig/kobako/namespace.rbs
 - sig/kobako/outcome.rbs
 - sig/kobako/outcome/panic.rbs
+- sig/kobako/pool.rbs
 - sig/kobako/runtime.rbs
 - sig/kobako/sandbox.rbs
 - sig/kobako/sandbox_options.rbs