kobako 0.9.2-x86_64-linux → 0.10.0-x86_64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f2b783a758091145f58f0a8e13b84c76c5c3a1420325ca2d272b5a58d31f7d38
-  data.tar.gz: b890067d1cc6af31a9cf74c8f3116504222ab1c64921715a3a9f35d6c60a9adb
+  metadata.gz: 9a2f9fdb62d68dfbb45d5cc88705b056e869a1f8ea527444a74daae4e2c24a7a
+  data.tar.gz: f6fd31dfb518022be1ca9619f5343fdf5a671caeffe451514eb0cde039371c6e
 SHA512:
-  metadata.gz: ee3aa19299ca309a21b3ae63d3cfd38ac322c3ebd4bd0d7b8aecac2e893edfaff7cf36ec5878f0f4f42c2e1f50fa68ad5df07e38d3d27829ce442162896cf848
-  data.tar.gz: 511eeeaeeb466f7ce6b441e88cb8927de4c58da73e7596b327b5658bcffd8ccbbe6aec6877b3461d7f2de2b0eb1b544da4dedf939a37dbf340cc56cee153dd85
+  metadata.gz: 7c61b7745938ff9f51dbf821d2f317ffaf11631651f6bfad695e07824c03fd7013e2d39bac95d31a951fa2b50138575907ce83a35364f7948a6464ed37bac710
+  data.tar.gz: c05f84febfd37914fd4fa80d48aea10b7041bdf756d50da749f85f9697e2365a1853e80579399a0d564244514107a7bd62907c8261c978d2143a2b0b55a67141

data/.release-please-manifest.json

@@ -1 +1 @@
-{".":"0.9.2","wasm/kobako-core":"0.4.1","wasm/kobako":"0.4.1","wasm/kobako-io":"0.4.1","wasm/kobako-regexp":"0.4.1"}
+{".":"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,30 @@
 # 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)
 
 

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

@@ -30,13 +30,6 @@ module Kobako
     #     +0x7fff_ffff+ (2³¹ − 1). Allocation beyond the cap raises
     #     immediately — no silent truncation, no wrap, no ID reuse.
     class Handles
-      # Reflective gadget types that are never minted as a Capability Handle
-      # ({docs/behavior.md B-43}[link:../../../docs/behavior.md]): wrapping a
-      # +Binding+ / +Method+ / +UnboundMethod+ would hand the guest a callable
-      # proxy onto host reflection (a returned +Binding+ reaches +Binding#eval+).
-      UNWRAPPABLE_TYPES = [Binding, Method, UnboundMethod].freeze
-      private_constant :UNWRAPPABLE_TYPES
-
       # Build a fresh, empty table. +next_id+ is an internal seam that
       # sets the starting value of the monotonic counter (defaults to 1 per
       # B-15); tests pass a value near +Kobako::Handle::MAX_ID+ to exercise
@@ -97,13 +90,16 @@ module Kobako
       private
 
       # Refuse to mint a Capability Handle for a reflective gadget
-      # ({UNWRAPPABLE_TYPES}, B-43). 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.
+      # ({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)
-        return unless UNWRAPPABLE_TYPES.any? { |type| object.is_a?(type) }
-
-        raise SandboxError, "a #{object.class} cannot cross as a Capability Handle"
+        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+

data/lib/kobako/catalog/namespaces.rb

@@ -37,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 —
@@ -80,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/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/version.rb

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

@@ -73,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

@@ -1,8 +1,6 @@
 module Kobako
   module Catalog
     class Handles
-      UNWRAPPABLE_TYPES: Array[Module]
-
       def initialize: (?next_id: Integer) -> void
 
       def alloc: (untyped object) -> Kobako::Handle

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: kobako
 version: !ruby/object:Gem::Version
-  version: 0.9.2
+  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