kobako 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5f76e4f3f09c6ade1cf87bd6e970040d8585ed9f0d8db7f1b5e653154acb2af2
-  data.tar.gz: 7d92b5b0c0961f4ed1b3bab01c5625a0a586ccf364c5e17a9727616bed02d065
+  metadata.gz: ddc9be38e5ce7f23c176bcd7be8b8683cf58d308dfedb17e91fc5841308a5c8c
+  data.tar.gz: 4a0de9e36b529010b50148ff9d904cafbe253b0c394a9a2118e6ef4d7c9e4029
 SHA512:
-  metadata.gz: 64d90bdb3aaf15493486926937e3edb2576e79a932485d169c6588e464ef6d6ae1504ba4afb1647b171d2cc04363381c5568669590cd626dd0a5ccbcccee1025
-  data.tar.gz: 8d0469f966df65ba9a149b25cfb5a5688381e3b1dc1e7b63572428d31f0a49901108613b7482d99192f3b52a32b61d53f3e725e79c44ab80f5564c6a40eee2d8
+  metadata.gz: ae0e599389ce723a1c257923a5b5b760ddf94a71698e5fa990f82587494ae8ca874d11c8c1fd5eedfac0d6e953f53cfb8603fb4da34989f8f92e39425bb99fa5
+  data.tar.gz: 6cbdec819843c52c1be3d04a6694af51ae41121e159a4de12d1ebef0074d1626247c8c06db0e9f15da2deb19b4b1730c124aa027bc676ffc2b1fedf6cd68d3c7

data/Cargo.lock

@@ -864,7 +864,7 @@ dependencies = [
 
 [[package]]
 name = "kobako"
-version = "0.2.1"
+version = "0.3.0"
 dependencies = [
  "magnus",
  "wasmtime",

data/README.md

@@ -7,8 +7,8 @@ The host (`wasmtime`) runs a precompiled `kobako.wasm` guest containing mruby an
 ```
         Host process                       Wasm guest
    ┌──────────────────────┐         ┌──────────────────────┐
-   │  Kobako::Sandbox     │ ──run─▶ │  mruby interpreter   │
-   │                      │         │                      │
+   │  Kobako::Sandbox     │ ─eval─▶ │  mruby interpreter   │
+   │                      │ ─run──▶ │                      │
    │  Services            │ ◀──RPC─ │  KV::Lookup.call(k)  │
    │   KV::Lookup         │ ─resp─▶ │                      │
    │                      │         │                      │
@@ -21,14 +21,17 @@ The host (`wasmtime`) runs a precompiled `kobako.wasm` guest containing mruby an
 
 ## Features
 
-- **In-process Wasm sandbox** — no subprocess, no container. Each `Sandbox#run` is a synchronous Ruby call.
-- **Per-run caps** — every `#run` enforces a wall-clock `timeout` (default 60 s) and a guest `memory_limit` (default 5 MiB). Exhaustion raises `Kobako::TimeoutError` / `Kobako::MemoryLimitError`.
-- **Capability injection via Services** — guest scripts can only call Ruby objects you explicitly `bind` under a two-level `Namespace::Member` path.
-- **Three-class error taxonomy** — every failure is exactly one of `TrapError` (Wasm engine / per-run cap), `SandboxError` (script / wire fault), or `ServiceError` (Service capability fault), so you can route errors without inspecting messages.
-- **Per-run state reset** — Handles issued during one `#run` are invalidated before the next; Service bindings remain.
-- **Separated stdout / stderr capture** — guest `puts` / `warn` / `print` / `printf` / `p` and writes to `$stdout` / `$stderr` are buffered per-channel (1 MiB default cap, configurable). Output past the cap is clipped; `#stdout_truncated?` / `#stderr_truncated?` report overflow.
-- **Capability Handles** — Services may return stateful host objects; the guest receives an opaque `Kobako::RPC::Handle` proxy it can use as the target of follow-up RPC calls, with no way to dereference it.
-- **Curated mruby stdlib** — core extensions plus `mruby-onig-regexp` for full Onigmo `Regexp` support. No mrbgem with I/O, network, or syscall access is bundled.
+| Feature | Description |
+|---|---|
+| In-process Wasm sandbox | No subprocess, no container. Both invocation verbs (`Sandbox#eval` for ad-hoc source, `Sandbox#run` for entrypoint dispatch) are synchronous Ruby calls. |
+| Per-invocation caps | Every invocation enforces a wall-clock `timeout` (default 60 s) and a per-invocation linear-memory `memory_limit` (default 1 MiB); exhaustion raises `Kobako::TimeoutError` / `Kobako::MemoryLimitError`. |
+| Capability injection via Services | Guest scripts can only call Ruby objects you explicitly `bind` under a two-level `Namespace::Member` path. |
+| Preloaded snippets | `Sandbox#preload` registers source or RITE bytecode for setup-once dispatch via `Sandbox#run(:Entrypoint, *args, **kwargs)`. |
+| Capability Handles | Services may return stateful host objects; the guest receives an opaque `Kobako::RPC::Handle` proxy it can use as the target of follow-up RPC calls, with no way to dereference it. |
+| Three-class error taxonomy | Every failure is exactly one of `TrapError`, `SandboxError`, or `ServiceError`, so you can route errors without inspecting messages. |
+| Per-invocation state reset | Handles issued during one invocation are invalidated before the next; Service bindings and preloaded snippets remain. |
+| Separated stdout / stderr capture | Guest writes to `$stdout` / `$stderr` are buffered per-channel (1 MiB default cap, configurable); overflow is clipped and reported by `#stdout_truncated?` / `#stderr_truncated?`. |
+| Curated mruby stdlib | Core extensions plus `mruby-onig-regexp` for full Onigmo `Regexp` support; no mrbgem with I/O, network, or syscall access is bundled. |
 
 ## Requirements
 
@@ -53,7 +56,7 @@ require "kobako"
 
 sandbox = Kobako::Sandbox.new
 
-result = sandbox.run(<<~RUBY)
+result = sandbox.eval(<<~RUBY)
   1 + 2
 RUBY
 
@@ -73,14 +76,14 @@ sandbox = Kobako::Sandbox.new
 sandbox.define(:KV).bind(:Lookup, ->(key) { redis.get(key) })
 sandbox.define(:Log).bind(:Sink,   ->(msg) { logger.info(msg) })
 
-sandbox.run(<<~RUBY)
+sandbox.eval(<<~RUBY)
   Log::Sink.call("starting")
   KV::Lookup.call("user_42")
 RUBY
 # => "..." (the redis value)
 ```
 
-Names must match the Ruby constant pattern `/\A[A-Z]\w*\z/`. Services declared before the first `#run` remain active across subsequent runs; `define` after the first `#run` raises `ArgumentError`.
+Names must match the Ruby constant pattern `/\A[A-Z]\w*\z/`. Services declared before the first invocation remain active across subsequent invocations; `define` after the first invocation (`#eval` or `#run`) raises `ArgumentError`.
 
 ### Keyword arguments
 
@@ -89,18 +92,18 @@ Keyword keys travel as Symbols and reach the host method as keyword arguments:
 ```ruby
 sandbox.define(:Geo).bind(:Lookup, ->(name:, region:) { "#{region}/#{name}" })
 
-sandbox.run('Geo::Lookup.call(name: "alice", region: "us")')
+sandbox.eval('Geo::Lookup.call(name: "alice", region: "us")')
 # => "us/alice"
 ```
 
-## Per-run caps
+## Per-invocation caps
 
-Each Sandbox enforces a wall-clock timeout and a guest linear-memory cap on every `#run`. Both default to safe values; pass `nil` to `timeout` or `memory_limit` to disable that cap. The output caps (`stdout_limit` / `stderr_limit`) cannot be disabled — pass a large Integer instead.
+Each Sandbox enforces a wall-clock timeout and a guest linear-memory cap on every invocation (`#eval` or `#run`). Both default to safe values; pass `nil` to `timeout` or `memory_limit` to disable that cap. The output caps (`stdout_limit` / `stderr_limit`) cannot be disabled — pass a large Integer instead.
 
 ```ruby
 sandbox = Kobako::Sandbox.new(
   timeout:      5.0,           # seconds, default 60.0
-  memory_limit: 10 * 1024 * 1024, # bytes, default 5 MiB
+  memory_limit: 10 * 1024 * 1024, # bytes, default 1 MiB
   stdout_limit: 64 * 1024,     # bytes, default 1 MiB
   stderr_limit: 64 * 1024
 )
@@ -109,20 +112,24 @@ sandbox = Kobako::Sandbox.new(
 | Cap            | Raises (subclass of `TrapError`)   | Default  |
 |----------------|------------------------------------|----------|
 | `timeout`      | `Kobako::TimeoutError`             | 60.0 s   |
-| `memory_limit` | `Kobako::MemoryLimitError`         | 5 MiB    |
+| `memory_limit` | `Kobako::MemoryLimitError`         | 1 MiB    |
 | `stdout_limit` | output silently clipped at cap     | 1 MiB    |
 | `stderr_limit` | output silently clipped at cap     | 1 MiB    |
 
-The timeout deadline is absolute wall-clock from `#run` entry and is checked at guest Wasm safepoints. Long-running host Service callbacks still consume wall-clock time but do not themselves trap — the next guest safepoint will trap immediately on return if the deadline has passed.
+The timeout deadline is absolute wall-clock from invocation entry and is checked at guest Wasm safepoints. Long-running host Service callbacks still consume wall-clock time but do not themselves trap — the next guest safepoint will trap immediately on return if the deadline has passed.
+
+`memory_limit` is scoped to the **per-invocation linear-memory delta** — the budget covers how much the current `#eval` / `#run` may grow `memory.grow` past the size observed at invocation entry. The mruby image's initial allocation and prior invocations' high-water mark are folded into that entry baseline, so a Sandbox reused across many invocations does not silently accumulate against a global budget.
+
+The 1 MiB default targets lightweight dynamic RPC workloads — short scripts that orchestrate Service calls, return small structured values, or replace a tool-calling layer in an AI Agent's Code Mode dispatch. Bump `memory_limit` when scripts compose multi-hundred-KiB strings, hold large composite return values, or run computations that allocate substantial intermediate state. Because the cap resets every invocation, multi-call patterns on one Sandbox do not need a budget that covers their cumulative footprint — only the largest single invocation's working set.
 
 ## Capturing stdout and stderr
 
-Guest output is captured into per-run buffers and exposed independently from the return value. The buffers cover the full Ruby IO surface — `puts`, `print`, `printf`, `p`, `<<`, and writes through `$stdout` / `$stderr` — all routed through the host-captured WASI pipe.
+Guest output is captured into per-invocation buffers and exposed independently from the return value. The buffers cover the full Ruby IO surface — `puts`, `print`, `printf`, `p`, `<<`, and writes through `$stdout` / `$stderr` — all routed through the host-captured WASI pipe.
 
 ```ruby
 sandbox = Kobako::Sandbox.new
 
-result = sandbox.run(<<~RUBY)
+result = sandbox.eval(<<~RUBY)
   puts "hello"
   warn "be careful"
   42
@@ -133,24 +140,24 @@ sandbox.stdout  # => "hello\n"
 sandbox.stderr  # => "be careful\n"
 ```
 
-Each `#run` clears the buffers at start. Output past the per-channel cap is clipped at the cap boundary — `#run` still returns normally, the bytes carry no truncation sentinel, and `#stdout_truncated?` / `#stderr_truncated?` flip to `true`.
+Each invocation clears the buffers at start. Output past the per-channel cap is clipped at the cap boundary — the invocation still returns normally, the bytes carry no truncation sentinel, and `#stdout_truncated?` / `#stderr_truncated?` flip to `true`.
 
 ```ruby
 sandbox = Kobako::Sandbox.new(stdout_limit: 64 * 1024)
-sandbox.run('puts "a" * 100_000')
+sandbox.eval('puts "a" * 100_000')
 sandbox.stdout.bytesize     # => 65_536
 sandbox.stdout_truncated?   # => true
 ```
 
 ## Error handling
 
-Every `#run` either returns a value or raises exactly one of three classes:
+Every invocation (`#eval` or `#run`) either returns a value or raises exactly one of three classes:
 
 ```ruby
 begin
-  sandbox.run(script)
+  sandbox.eval(script)
 rescue Kobako::TrapError => e
-  # Wasm engine fault OR per-run cap exhaustion:
+  # Wasm engine fault OR per-invocation cap exhaustion:
   #   - Kobako::TimeoutError       (wall-clock timeout)
   #   - Kobako::MemoryLimitError   (memory_limit exceeded)
   #   - Kobako::TrapError          (engine crash / wire-violation fallback)
@@ -166,9 +173,13 @@ end
 
 `SandboxError` and `ServiceError` carry structured fields (`origin`, `klass`, `backtrace_lines`, `details`) when the guest produced a panic envelope. Named subclasses:
 
-- `Kobako::TimeoutError` / `Kobako::MemoryLimitError` — per-run cap exhaustion (subclasses of `TrapError`).
-- `Kobako::ServiceError::Disconnected` — RPC target Handle has been invalidated.
-- `Kobako::HandleTableExhausted` — per-run Handle counter reached its cap (2³¹ − 1); subclass of `SandboxError`.
+| Class                                  | Parent             | Trigger                                                                                  |
+|----------------------------------------|--------------------|------------------------------------------------------------------------------------------|
+| `Kobako::TimeoutError`                 | `TrapError`        | Per-invocation `timeout` exhausted                                                       |
+| `Kobako::MemoryLimitError`             | `TrapError`        | Per-invocation `memory_limit` exhausted                                                  |
+| `Kobako::ServiceError::Disconnected`   | `ServiceError`     | RPC target Handle has been invalidated                                                   |
+| `Kobako::HandleTableExhausted`         | `SandboxError`     | Per-invocation Handle counter reached its 2³¹ − 1 cap                                    |
+| `Kobako::BytecodeError`                | `SandboxError`     | `#preload(binary:)` payload failed RITE structural validation at first invocation replay |
 
 ## Capability Handles
 
@@ -182,57 +193,112 @@ end
 
 sandbox.define(:Factory).bind(:Make, ->(name) { Greeter.new(name) })
 
-sandbox.run(<<~RUBY)
+sandbox.eval(<<~RUBY)
   g = Factory::Make.call("Bob")  # g is a Kobako::RPC::Handle proxy
   g.greet                         # second RPC, routed to the Greeter
 RUBY
 # => "hi, Bob"
 ```
 
-Handles are scoped to a single `#run` — a Handle obtained in run N is invalid in run N+1, even on the same Sandbox.
+Handles are scoped to a single invocation — a Handle obtained in invocation N is invalid in invocation N+1, even on the same Sandbox.
 
 ## Setup-once, run-many
 
-A single Sandbox can serve many script executions. Service bindings persist; capability state (Handles, stdout, stderr) resets between runs.
+A single Sandbox can serve many invocations. Service bindings and preloaded snippets persist; capability state (Handles, stdout, stderr) resets between invocations.
 
 ```ruby
 sandbox = Kobako::Sandbox.new
 sandbox.define(:Data).bind(:Fetch, ->(id) { records[id] })
 
-sandbox.run('Data::Fetch.call("a")')  # => "..."
-sandbox.run('Data::Fetch.call("b")')  # => "..." (same bindings, fresh state)
+sandbox.eval('Data::Fetch.call("a")')  # => "..."
+sandbox.eval('Data::Fetch.call("b")')  # => "..." (same bindings, fresh state)
 ```
 
 For workloads that must be isolated from each other (e.g., one Sandbox per tenant, per student submission), 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.
 
+## Preloaded snippets and entrypoint dispatch
+
+`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 and returns the value of `Target.call(*args, **kwargs)`. Together they cover setup-once / dispatch-many workloads where the same logic is exercised across many requests.
+
+```ruby
+sandbox = Kobako::Sandbox.new
+sandbox.preload(code: "Adder = ->(a, b) { a + b }", name: :Adder)
+sandbox.preload(code: 'Greeter = ->(name:) { "hello, #{name}" }', name: :Greeter)
+
+sandbox.run(:Adder, 2, 3)              # => 5
+sandbox.run(:Greeter, name: "world")   # => "hello, world"
+```
+
+`#preload` accepts two payload forms:
+
+| Form     | Signature                              | Snippet name source                 | Validation timing                                                                       |
+|----------|----------------------------------------|-------------------------------------|------------------------------------------------------------------------------------------|
+| Source   | `preload(code: "...", name: :Const)`   | The `name:` keyword                 | Trial-compiled at preload time; compile errors raise immediately                         |
+| Bytecode | `preload(binary: bytes)`               | Read from the bytecode's `debug_info` | Structural validation runs at first invocation; failure raises `Kobako::BytecodeError`  |
+
+The source form trial-compiles each snippet against a fresh `mrb_state` at preload time, so compile errors surface immediately at the `#preload` call. The bytecode form treats `binary:` as opaque bytes and defers RITE version / body validation to the first invocation's replay, because that is when the payload loads into a fresh `mrb_state`. Bytecode compiled without `debug_info` (`mrbc` without `-g`) is still accepted — only its backtrace frames are omitted, while exception class, message, and `origin` attribution are preserved.
+
+Snippets replay in insertion order, so later snippets can reference constants defined by earlier ones. The snippet table is sealed by the first invocation alongside Service registration; additional `#preload` calls after the first `#eval` or `#run` raise `ArgumentError`.
+
+`#run` resolves `target` (Symbol or String, normalized to Symbol) only as a top-level `Object` constant — `::`-segmented names and lowercase forms fail at host pre-flight with `ArgumentError`. A `Kobako::SandboxError` surfaces when the constant is missing or does not respond to `#call`.
+
+### Choosing between source and bytecode
+
+Use the **source form** when snippets are authored in your repo or generated at boot — compile errors land at the `#preload` call so a misbehaving snippet fails fast at setup time, and no separate `mrbc` toolchain is needed. The trial-compile happens once per snippet (~2.5 µs per snippet) and is paid at preload, not on the request hot path.
+
+Use the **bytecode form** when snippets ship as build artifacts from a pipeline that runs `mrbc` separately — for example, when source bodies should not be embedded in the running process, when you want a build step that compiles and packages snippets ahead of release, or when you want `Exception#backtrace` frames attributed to the bytecode's `debug_info` filename rather than a host-supplied `name:` keyword. Structural validation (RITE version, body integrity) is deferred to the first invocation, so a malformed bytecode payload surfaces as `Kobako::BytecodeError` on the first `#eval` or `#run`, not at `#preload`.
+
+Both forms behave identically at dispatch time and replay through the same per-invocation path, so the choice between them is about your build / distribution pipeline and where you want errors to land, not about runtime cost.
+
 ## Performance
 
-Headline numbers from the current baseline (macOS arm64, Ruby 3.4.7, YJIT off — full results in [`benchmark/results/`](benchmark/results) and [`benchmark/README.md`](benchmark/README.md)).
+Order-of-magnitude figures for capacity planning on macOS arm64, Ruby 3.4.7, YJIT off. Absolute values vary by hardware but the ratios are stable across machines. Detailed numbers and methodology live in [`benchmark/README.md`](benchmark/README.md).
 
-| What | Cost |
-|---|---|
-| First `Sandbox.new` in a fresh process (Engine init + Module JIT) | ~2.0 s one-time |
-| Subsequent `Sandbox.new` (cache warm) | ~130 µs |
-| Reusing a Sandbox for one `#run("nil")` | ~135 µs |
-| Fresh Sandbox per request — the tenant-isolation pattern | ~275 µs (+140 µs vs reuse) |
-| Per-RPC cost amortized across 1 000 calls in one `#run` | ~35 µs |
-| 100 000-iteration integer XOR loop in mruby | ~200 ms |
-| 1 000 Onigmo `Regexp =~` matches | ~14 µs per match |
-| Process RSS after the first `Sandbox.new` | ~150 MB (one-time) |
-| Memory per additional Sandbox | ~575 KB |
-| 1 000 isolated tenants in one process | ~730 MB total |
-| Aggregate throughput across N Threads | GVL-bound — wasm execution serialized, modest scaling from Ruby-side overlap |
-
-Practical implications:
-
-- **Pre-warm at boot.** The ~2 s first-Sandbox cost is paid once per process; every subsequent Sandbox amortizes to micro-, not seconds. Construct one Sandbox at boot before serving requests.
-- **Tenant isolation is affordable.** Per-request Sandbox construction adds ~140 µs of overhead; per-tenant RSS budget is ~575 KB plus one-time ~130 MB for the engine. 1 000 isolated tenants in a single Sidekiq / Puma worker is well within typical RSS limits.
-- **Batch RPCs inside one `#run`.** A single Service call costs ~135 µs because each `#run` carries ~130 µs of setup; 1 000 calls inside one `#run` reduce the per-call cost to ~35 µs.
-
-A +10% regression on any of the five SPEC-mandated benchmarks blocks release. See [`benchmark/README.md`](benchmark/README.md) for the full per-suite breakdown and known measurement caveats.
+### Lifecycle costs
+
+| Phase                                                       | Cost                                            |
+|-------------------------------------------------------------|-------------------------------------------------|
+| First `Sandbox.new` in a fresh process (Engine + Module JIT) | ~600 ms one-time                                |
+| Subsequent `Sandbox.new` (Engine cache warm)                | ~130 µs                                         |
+| Reusing a Sandbox for one `#eval("nil")`                    | ~135 µs                                         |
+| Fresh `Sandbox.new` per request                             | ~275 µs (≈ +140 µs vs reuse)                    |
+| Warm `#run(:Entrypoint, ...)` dispatch                      | ~165 µs                                         |
+| Per-RPC cost amortized inside one invocation                | ~6.6 µs (1 000 RPCs in one `#eval` ≈ 6.6 ms)    |
+| 100 000-iteration integer XOR loop in mruby                 | ~43 ms                                          |
+| 1 000 Onigmo `Regexp =~` matches                            | ~3 µs each                                      |
+
+The ~600 ms cold start dominates the first Sandbox in a process — wasmtime JIT-compiles the precompiled `kobako.wasm` Module and the result is cached at process scope. Construct one Sandbox at boot before serving requests so the JIT cost lands off the hot path.
+
+### Memory budget
+
+| Allocation                                  | Cost                                                                       |
+|---------------------------------------------|----------------------------------------------------------------------------|
+| Process RSS after first `Sandbox.new`       | ~150-180 MB (one-time engine + module + first instance)                    |
+| Per additional Sandbox                      | ~580 KB (Wasm instance + linear memory + WASI capture pipes)               |
+| 1 000 isolated tenants in one process       | ~750 MB total                                                              |
+
+Use these as upper-bound budgets for capacity planning, not lower bounds — actual RSS shifts ~30% with host process load and macOS allocator state.
+
+### Choosing your pattern
+
+When the script is ad-hoc (LLM-generated, untrusted user input) and only runs once, use `Sandbox#eval(source)`. Per-invocation cost is ~135 µs of setup plus the script's own runtime; mruby parses the source on every call.
+
+When you have a fixed set of entrypoints exercised many times — a stable AI Agent tool-call protocol, a plug-in registry loaded at boot, a small library of host-side commands — preload the entrypoints via `Sandbox#preload(code:, name:)` once at setup and dispatch via `Sandbox#run(:Target, *args, **kwargs)`. The mruby source compile (~2.5 µs per snippet) lands once at preload, not on every request, and warm dispatch costs ~165 µs.
+
+Mind the snippet replay cost. Every preloaded snippet replays into a fresh `mrb_state` before **every** invocation, whether the invocation is `#eval` or `#run`, at ~7-9 µs per snippet per invocation. Preloading 8 helpers adds ~60 µs to every subsequent invocation; preloading 64 helpers adds ~565 µs. Keep the snippet count proportionate to how often the helpers are actually used — preloading rarely-touched helpers is more expensive than inlining or re-eval'ing them.
+
+For tenant isolation between mutually untrusted scopes, construct a fresh `Kobako::Sandbox` per scope. Per-request construction costs ~140 µs over reuse plus ~580 KB of RSS — comfortably affordable for 1 000+ isolated tenants in one Sidekiq / Puma worker. Reuse a Sandbox when all requests share one trust scope; isolate when scripts come from many.
+
+### Concurrency
+
+`ext/` does not release the GVL during wasmtime execution, so wasm work is GVL-serialized: aggregate throughput across N Threads stays around 7-8k `#eval`/s regardless of N. Ruby-side `#eval` setup can still overlap, so a short `#eval` running while another Thread is in a long `#eval` is slowed by ~2× (not 10×) — host-side synchronization yields the GVL and the contending Thread interleaves. Mixed short / long workloads in one process do not deadlock.
+
+### Regression gate
+
+A +10% regression on any of the five SPEC-mandated benchmarks (cold_start, RPC roundtrip, codec, mruby VM, HandleTable) blocks release. Full per-suite breakdown in [`benchmark/README.md`](benchmark/README.md).
 
 ```bash
-bundle exec rake bench   # five gated regression benchmarks (≤ 1 MiB payloads, ~5-8 min)
+bundle exec rake bench   # five gated regression benchmarks (~5-8 min, ≤ 1 MiB payloads)
 ```
 
 ## Development

data/ext/kobako/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "kobako"
-version = "0.2.1"
+version = "0.3.0"
 edition = "2021"
 authors = ["Aotokitsuruya <contact@aotoki.me>"]
 license = "Apache-2.0"
@@ -29,7 +29,7 @@ wasmtime = { version = "44.0.1", default-features = false, features = [
     "wat",
 ] }
 # wasmtime-wasi provides WASI preview1 support for routing guest stdout/stderr
-# into in-memory buffers (SPEC.md §B-04). The `p1` feature enables the
+# into in-memory buffers (docs/behavior.md §B-04). The `p1` feature enables the
 # WasiCtxBuilder + preview1 adapter which wires fd 1/2 to pipes. We omit
 # `p2` (component-model) and `p0`/`p3` (async) because kobako runs
 # synchronous sandboxes only.

data/ext/kobako/src/wasm/cache.rs

@@ -34,7 +34,7 @@ static SHARED_ENGINE: OnceLock<WtEngine> = OnceLock::new();
 static MODULE_CACHE: OnceLock<Mutex<HashMap<PathBuf, WtModule>>> = OnceLock::new();
 
 /// Ticker cadence for the process-singleton epoch ticker. Bounds the
-/// granularity of the SPEC.md B-01 wall-clock timeout: the
+/// granularity of the docs/behavior.md B-01 wall-clock timeout: the
 /// `epoch_deadline_callback` fires once per tick (`Continue(1)`), so the
 /// trap can lag the deadline by at most one tick under nominal
 /// scheduling. 10 ms keeps the lag small enough that it does not skew
@@ -53,8 +53,8 @@ const EPOCH_TICK: Duration = Duration::from_millis(10);
 /// instructions.
 ///
 /// Also enables `epoch_interruption(true)` so every Store can install an
-/// `epoch_deadline_callback` for the per-run wall-clock cap (SPEC.md
-/// B-01, E-19). The first call spawns the process-singleton ticker
+/// `epoch_deadline_callback` for the per-run wall-clock cap
+/// (docs/behavior.md B-01, E-19). The first call spawns the process-singleton ticker
 /// thread that drives `engine.increment_epoch()` at [`EPOCH_TICK`]
 /// cadence; subsequent calls reuse the same engine and ticker.
 pub(crate) fn shared_engine() -> Result<&'static WtEngine, MagnusError> {

data/ext/kobako/src/wasm/dispatch.rs

@@ -3,7 +3,7 @@
 //! When the guest invokes the wasm import declared in
 //! `wasm/kobako-wasm/src/abi.rs`, wasmtime calls back into the host
 //! through the closure built in [`super::instance::Instance::build`].
-//! That closure delegates here. The dispatcher (SPEC.md B-12 / B-13):
+//! That closure delegates here. The dispatcher (docs/behavior.md B-12 / B-13):
 //!
 //!   1. Reads the Request bytes from guest linear memory.
 //!   2. Hands them to the Ruby-side `Kobako::RPC::Server` and recovers
@@ -19,6 +19,31 @@
 //! return to a trap. Failures during normal dispatch surface as
 //! Response.err envelopes from the Server itself — they never reach
 //! this 0-return path.
+//!
+//! ## Why this module writes to `stderr`
+//!
+//! This file is the one place in `ext/` that deliberately prints
+//! through `eprintln!`. The host normally surfaces faults by
+//! raising a `MagnusError` back into Ruby; the dispatcher contract
+//! is the exception — it must return a packed `i64` to the guest
+//! and cannot raise, so a 0 return is the only signal the wasm side
+//! receives. The guest collapses every 0 into the same trap, so the
+//! Ruby host has no way to attribute the failure to a specific
+//! step (missing `memory` export vs. no Server bound vs. Server
+//! raised vs. `__kobako_alloc` returned 0 vs. `memory.write`
+//! rejected).
+//!
+//! [`handle`] writes a single `[kobako-dispatch] <reason>` line to
+//! `stderr` on each failure path so operators have a breadcrumb to
+//! correlate the trap with the actual cause. The line is emitted in
+//! both debug and release builds on purpose: dispatcher failures
+//! are wire-layer faults rather than expected error paths
+//! (`Kobako::Sandbox` always installs a Server, the Server is
+//! contracted never to raise, etc.), so the "release-build noise"
+//! cost is bounded — under normal operation the line is never
+//! written. Operators that need to silence the channel can redirect
+//! the host process's stderr, but the kobako convention is "ext
+//! never logs" plus this single, named exception.
 
 use magnus::value::{Opaque, ReprValue};
 use magnus::{Error as MagnusError, RString, Ruby, Value};
@@ -28,27 +53,48 @@ use super::host_state::HostState;
 
 /// Drive a single `__kobako_dispatch` invocation end-to-end. Entry point
 /// from the wasmtime closure built in [`super::instance::Instance::build`].
+///
+/// Returns the packed `(ptr<<32)|len` u64 on success, 0 on any
+/// wire-layer fault. Failure paths log a `[kobako-dispatch]` line to
+/// `stderr` so operators have a breadcrumb when the guest sees a 0
+/// return and traps; before this every failure was silent. The Server
+/// itself is contracted never to raise (it folds Service exceptions
+/// into Response.err envelopes), so reaching the failure path is
+/// always a wiring bug or wire-layer fault rather than an expected
+/// path.
 pub(crate) fn handle(caller: &mut Caller<'_, HostState>, req_ptr: i32, req_len: i32) -> i64 {
-    let req_bytes = match read_caller_memory(caller, req_ptr, req_len) {
-        Some(b) => b,
-        None => return 0,
-    };
+    match try_handle(caller, req_ptr, req_len) {
+        Ok(packed) => packed,
+        Err(reason) => {
+            eprintln!("[kobako-dispatch] {}", reason);
+            0
+        }
+    }
+}
 
-    // No Server bound — return 0 to signal a wire-layer fault; the guest
-    // maps a 0 return to a trap. `Kobako::Sandbox` always installs a
-    // Server before invoking the guest, so reaching this branch indicates
-    // a misuse rather than a normal control path.
-    let server = match caller.data().server() {
-        Some(d) => d,
-        None => return 0,
-    };
+/// Result-returning core of [`handle`]. Pulled out so each early
+/// failure path carries a diagnostic string instead of an opaque 0.
+fn try_handle(
+    caller: &mut Caller<'_, HostState>,
+    req_ptr: i32,
+    req_len: i32,
+) -> Result<i64, &'static str> {
+    let req_bytes = read_caller_memory(caller, req_ptr, req_len)
+        .ok_or("guest 'memory' export missing or request slice out of bounds")?;
 
-    let resp_bytes = match invoke_server(server, &req_bytes) {
-        Ok(b) => b,
-        Err(_) => return 0,
-    };
+    // `Kobako::Sandbox` always installs a Server before invoking the
+    // guest, so reaching this branch indicates a misuse rather than a
+    // normal control path.
+    let server = caller
+        .data()
+        .server()
+        .ok_or("no Ruby Server bound — Sandbox#run must precede __kobako_dispatch")?;
+
+    let resp_bytes = invoke_server(server, &req_bytes).map_err(|_| {
+        "Ruby Server#dispatch raised — contract is to fold faults into Response.err"
+    })?;
 
-    write_response(caller, &resp_bytes).unwrap_or(0)
+    write_response(caller, &resp_bytes)
 }
 
 /// Call the Ruby Server's `#dispatch(request_bytes)` method and return
@@ -56,43 +102,48 @@ pub(crate) fn handle(caller: &mut Caller<'_, HostState>, req_ptr: i32, req_len:
 /// failed (it is contracted never to raise — see
 /// `Kobako::RPC::Server#dispatch`), which we treat as a wire-layer fault.
 fn invoke_server(server: Opaque<Value>, req_bytes: &[u8]) -> Result<Vec<u8>, MagnusError> {
-    // The wasmtime callback runs on the same Ruby thread that called
-    // Sandbox#run — the invariant SPEC Implementation Standards
-    // Architecture pins for the host gem — so `Ruby::get()` is always
-    // available here. Panicking with `expect` localises the violation
-    // rather than letting a nonsense error propagate.
+    // The wasmtime callback runs on the same Ruby thread that called the
+    // active Sandbox invocation (#eval or #run) — the invariant SPEC
+    // Implementation Standards Architecture pins for the host gem — so
+    // `Ruby::get()` is always available here. Panicking with `expect`
+    // localises the violation rather than letting a nonsense error
+    // propagate.
     let ruby = Ruby::get().expect("Ruby handle unavailable in __kobako_dispatch");
     let server_value: Value = ruby.get_inner(server);
     let req_str = ruby.str_from_slice(req_bytes);
     let resp: RString = server_value.funcall("dispatch", (req_str,))?;
-    // SAFETY: the returned RString is held by the Ruby VM for the duration of
-    // this scope; copying its bytes into a Vec is a defensive standard pattern.
-    let bytes = unsafe { resp.as_slice() }.to_vec();
-    Ok(bytes)
+    Ok(super::rstring_to_vec(resp))
 }
 
 /// Allocate a guest-side buffer through `__kobako_alloc` and copy the
 /// response bytes into it. Returns the packed `(ptr<<32)|len` u64.
-fn write_response(caller: &mut Caller<'_, HostState>, bytes: &[u8]) -> Option<i64> {
+/// Each failure path carries a `&'static str` reason so the dispatcher
+/// wrapper can surface a useful diagnostic rather than a silent 0.
+fn write_response(caller: &mut Caller<'_, HostState>, bytes: &[u8]) -> Result<i64, &'static str> {
     let alloc = match caller.get_export("__kobako_alloc") {
-        Some(Extern::Func(f)) => f.typed::<i32, i32>(&*caller).ok()?,
-        _ => return None,
+        Some(Extern::Func(f)) => f
+            .typed::<i32, i32>(&*caller)
+            .map_err(|_| "guest '__kobako_alloc' export has wrong signature")?,
+        _ => return Err("guest '__kobako_alloc' export missing"),
     };
-    let len_i32 = i32::try_from(bytes.len()).ok()?;
-    let ptr = alloc.call(&mut *caller, len_i32).ok()?;
+    let len_i32 = i32::try_from(bytes.len()).map_err(|_| "response exceeds i32::MAX bytes")?;
+    let ptr = alloc
+        .call(&mut *caller, len_i32)
+        .map_err(|_| "__kobako_alloc trapped")?;
     if ptr == 0 {
-        return None;
+        return Err("__kobako_alloc returned 0 (out of memory)");
     }
 
     let mem = match caller.get_export("memory") {
         Some(Extern::Memory(m)) => m,
-        _ => return None,
+        _ => return Err("guest 'memory' export missing"),
     };
-    mem.write(&mut *caller, ptr as usize, bytes).ok()?;
+    mem.write(&mut *caller, ptr as usize, bytes)
+        .map_err(|_| "memory.write rejected response buffer range")?;
 
     let ptr_u32 = ptr as u32;
     let len_u32 = bytes.len() as u32;
-    Some(((ptr_u32 as i64) << 32) | (len_u32 as i64))
+    Ok(((ptr_u32 as i64) << 32) | (len_u32 as i64))
 }
 
 /// Copy `[ptr, ptr+len)` out of the guest's linear memory as seen from