kobako 0.2.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5f76e4f3f09c6ade1cf87bd6e970040d8585ed9f0d8db7f1b5e653154acb2af2
-  data.tar.gz: 7d92b5b0c0961f4ed1b3bab01c5625a0a586ccf364c5e17a9727616bed02d065
+  metadata.gz: bb91cd11e954d6388b7d6c19be8b9fc77548fa1ea9d57b75f1afc7c0d450a36b
+  data.tar.gz: f84463e4b30e2ae5cb1e7d09a7c55345a419afd442613a1eb6b080682263587f
 SHA512:
-  metadata.gz: 64d90bdb3aaf15493486926937e3edb2576e79a932485d169c6588e464ef6d6ae1504ba4afb1647b171d2cc04363381c5568669590cd626dd0a5ccbcccee1025
-  data.tar.gz: 8d0469f966df65ba9a149b25cfb5a5688381e3b1dc1e7b63572428d31f0a49901108613b7482d99192f3b52a32b61d53f3e725e79c44ab80f5564c6a40eee2d8
+  metadata.gz: d622978cf22e2b30dbf8674275bbaaf39d0de68962709b40b67194d0521ca3d1e991e9a4e59853e634c111fc852d4719864c2990f2baaf35e1395efa3f67b63a
+  data.tar.gz: 3f828b5374841d0bcb8136a7c1aa078668c05c3673c794c50f86de9b1aee0bd915d090e022061b3e9636abb2dfb85a0b3bf1a7bbacff968635d9ed01c5f21edd

data/Cargo.lock

@@ -864,7 +864,7 @@ dependencies = [
 
 [[package]]
 name = "kobako"
-version = "0.2.1"
+version = "0.4.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,18 @@ 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::Handle` proxy it can use as the target of follow-up RPC calls, with no way to dereference it. `Sandbox#run` also accepts non-wire-representable Ruby objects as args and auto-wraps them into Handles, so the guest can use any host object the script needs. |
+| 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?`. |
+| Per-invocation usage readout | `Sandbox#usage` returns the most recent invocation's `wall_time` (Float seconds spent inside the wasm guest) and `memory_peak` (high-water `memory.grow` delta in bytes), populated on every outcome including `TrapError`, for budget diagnostics. |
+| 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 +57,7 @@ require "kobako"
 
 sandbox = Kobako::Sandbox.new
 
-result = sandbox.run(<<~RUBY)
+result = sandbox.eval(<<~RUBY)
   1 + 2
 RUBY
 
@@ -73,14 +77,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 +93,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 +113,37 @@ 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.
+
+To see how much of the cap an invocation actually consumed, read `Sandbox#usage` after the call. It returns a `Kobako::Usage` value object with `wall_time` (Float seconds the guest export call spent inside wasmtime, aligned with the `timeout` accounting) and `memory_peak` (Integer high-water `memory.grow` delta in bytes, aligned with the `memory_limit` accounting). The fields are populated on every outcome, including the `TrapError` branches, so you can read them after rescuing a trap to diagnose which budget the failing invocation chewed through.
+
+```ruby
+sandbox = Kobako::Sandbox.new(timeout: 1.0, memory_limit: 4 * 1024 * 1024)
+
+begin
+  sandbox.eval("'x' * 5_000_000")
+rescue Kobako::MemoryLimitError
+  sandbox.usage.memory_peak  # => the largest delta accepted before the trap
+  sandbox.usage.wall_time    # => seconds spent before the cap fired
+end
+```
 
 ## 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 +154,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,13 +187,17 @@ 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
 
-When a Service returns a stateful host object (anything beyond `nil` / Boolean / Integer / Float / String / Symbol / Array / Hash), the wire layer transparently allocates an opaque Handle. The guest receives a `Kobako::RPC::Handle` proxy it can use as the target of further RPC calls — but cannot dereference, forge from an integer, or smuggle across runs.
+When a Service returns a stateful host object (anything beyond `nil` / Boolean / Integer / Float / String / Symbol / Array / Hash), the wire layer transparently allocates an opaque Handle. The guest receives a `Kobako::Handle` proxy it can use as the target of further RPC calls — but cannot dereference, forge from an integer, or smuggle across runs.
 
 ```ruby
 class Greeter
@@ -182,57 +207,178 @@ end
 
 sandbox.define(:Factory).bind(:Make, ->(name) { Greeter.new(name) })
 
-sandbox.run(<<~RUBY)
-  g = Factory::Make.call("Bob")  # g is a Kobako::RPC::Handle proxy
+sandbox.eval(<<~RUBY)
+  g = Factory::Make.call("Bob")  # g is a Kobako::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.
+`Sandbox#run` accepts non-wire-representable host objects as args / kwargs values too: the host walks the argument tree, wraps every non-wire leaf through the same Handle path, and the guest sees a `Kobako::Handle` proxy in its place. This lets you pass framework objects (a Rack `env` Hash containing an `IO`-like body, an active record, an enumerator) into the entrypoint without first marshalling them into primitives.
+
+```ruby
+require "stringio"
+
+sandbox = Kobako::Sandbox.new
+sandbox.preload(code: "Echo = ->(body) { body.read.upcase }", name: :Echo)
+
+sandbox.run(:Echo, StringIO.new("hello world"))
+# => "HELLO WORLD"
+```
+
+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.
+
+```
+   ───────────── setup phase (mutable) ─────────────
+
+     sandbox = Kobako::Sandbox.new
+     sandbox.define(:KV).bind(:Lookup, ...)
+     sandbox.preload(code: ..., name: :Adder)
+     sandbox.preload(code: ..., name: :Greeter)
+
+                          │
+                          ▼
+
+   ═════════════════ seal point ═════════════════
+   First #eval or #run freezes the Service registry
+   and snippet table. Further define / preload now
+   raise ArgumentError.
+
+                          │
+                          ▼
+
+   ──────────────── invocation N ───────────────────
+
+     1. allocate fresh mrb_state
+
+     2. replay snippets (in insertion order):
+          :Adder     → defines Adder
+          :Greeter   → defines Greeter
+
+     3. dispatch:  eval(source)  or  run(:Target, *args)
+
+     4. return value to host
+
+     5. discard mrb_state; reset per-invocation state:
+          · Handles invalidated
+          · stdout / stderr buffers cleared
+          · memory delta zeroed
+
+     Services + snippets persist; invocation N+1 repeats.
+```
 
 ```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`.
+
+```
+   per-invocation replay (every #eval / #run, snippets in insertion order):
+
+      fresh mrb_state
+            │
+            ├──▶ replay :Adder            (defines Adder)
+            │
+            ├──▶ replay :Greeter          (defines Greeter)
+            │
+            └──▶ eval(source)  -or-  run(:Target, *args, **kwargs)
+                       │
+                       ▼
+                  return value, then mrb_state discarded
+```
+
+`#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`       | ~165-195 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       | ~765 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.4.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> {
@@ -112,16 +112,24 @@ pub(crate) fn cached_module(path: &Path) -> Result<WtModule, MagnusError> {
         return Err(MagnusError::new(
             ruby.get_inner(&MODULE_NOT_BUILT_ERROR),
             format!(
-                "wasm module not found at {}; run `bundle exec rake wasm:build` to build it",
+                "Sandbox runtime not found at {}; run `bundle exec rake wasm:build` to build it",
                 path.display()
             ),
         ));
     }
 
-    let bytes =
-        fs::read(path).map_err(|e| wasm_err(&ruby, format!("read {}: {}", path.display(), e)))?;
+    let bytes = fs::read(path).map_err(|e| {
+        wasm_err(
+            &ruby,
+            format!(
+                "failed to read Sandbox runtime at {}: {}",
+                path.display(),
+                e
+            ),
+        )
+    })?;
     let module = WtModule::new(shared_engine()?, &bytes)
-        .map_err(|e| wasm_err(&ruby, format!("compile module: {}", e)))?;
+        .map_err(|e| wasm_err(&ruby, format!("failed to compile Sandbox runtime: {}", e)))?;
     cache
         .lock()
         .expect("module cache mutex poisoned")