kobako 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bb91cd11e954d6388b7d6c19be8b9fc77548fa1ea9d57b75f1afc7c0d450a36b
-  data.tar.gz: f84463e4b30e2ae5cb1e7d09a7c55345a419afd442613a1eb6b080682263587f
+  metadata.gz: e6bac8a7b2fd8ff003b41057940921c0cb8357c8e97e66d235eb22b3d361ebd4
+  data.tar.gz: 54a8945f945db0062a35700078fa195461c74d760ca7d34c0b72409b544f5eb9
 SHA512:
-  metadata.gz: d622978cf22e2b30dbf8674275bbaaf39d0de68962709b40b67194d0521ca3d1e991e9a4e59853e634c111fc852d4719864c2990f2baaf35e1395efa3f67b63a
-  data.tar.gz: 3f828b5374841d0bcb8136a7c1aa078668c05c3673c794c50f86de9b1aee0bd915d090e022061b3e9636abb2dfb85a0b3bf1a7bbacff968635d9ed01c5f21edd
+  metadata.gz: 99754b3a49329e4faa3e7d96f793bf749d31c6ef0c1739c34db7ce8cef7df250af847efc2e5fb0a4c5f280e6d4c0b0eba0694b3a815e232aa5ac5a242ea805ab
+  data.tar.gz: c7a70f38b8e8a1342a7623cb51cf99bf31dc5aaa2929f4eaa921054c90a8a17815c271617f6c1c4f72b305ab7ceeaa88077dd152583f8566ffe51e8a09de9fee

data/.release-please-manifest.json

@@ -0,0 +1 @@
+{".":"0.6.0"}

data/CHANGELOG.md

@@ -0,0 +1,44 @@
+# Changelog
+
+## [0.6.0](https://github.com/elct9620/kobako/compare/v0.5.0...v0.6.0) (2026-05-28)
+
+
+### Features
+
+* **bench:** gate against a committed anchor baseline ([ed8b30e](https://github.com/elct9620/kobako/commit/ed8b30e0940736cbabcca18227590d07c3bf94d3))
+* **handle:** restore guest-returned Capability Handles to host objects (B-37) ([092815d](https://github.com/elct9620/kobako/commit/092815d610d3595db82b406d4b67880c84f11900))
+
+
+### Bug Fixes
+
+* **bench:** harden the gate guards and split judgment from the runner ([d6eaae2](https://github.com/elct9620/kobako/commit/d6eaae2de44d14a4735fbb544da712c659144a86))
+* **ci:** chain release.yml from release-please via workflow_call ([711665d](https://github.com/elct9620/kobako/commit/711665d29a8c8445b1e26ca08e4b0efc5b24982c))
+* **handle:** don't restore a Handle broken out of a guest block (B-37) ([ea25ab9](https://github.com/elct9620/kobako/commit/ea25ab9793f376f15e8d668077ad58f8d67e5a63))
+
+## [0.5.0](https://github.com/elct9620/kobako/compare/v0.4.0...v0.5.0) (2026-05-27)
+
+
+### Features
+
+* **abi:** add `__kobako_yield_to_block` skeleton + host re-entry channel ([555eb4b](https://github.com/elct9620/kobako/commit/555eb4bf578c3c4397ba2c0d105c0d3ca687e23c))
+* **abi:** classify RBreak via ci_break_index for B-25 / E-21 ([32668a0](https://github.com/elct9620/kobako/commit/32668a033e2f959700acadadfbc41388ed72a2dd))
+* **abi:** wire `__kobako_yield_to_block` to real `mrb_yield_argv` ([35aeac8](https://github.com/elct9620/kobako/commit/35aeac8700254d1500f5be837a72c56984a7ebfa))
+* **bench:** add noise-aware release gate, report mean alongside median ([0cfaebc](https://github.com/elct9620/kobako/commit/0cfaebc2afadfae81e3d00441273da70e396d7a5))
+* **bench:** add yield round-trip suite as gated benchmark [#6](https://github.com/elct9620/kobako/issues/6) ([315f923](https://github.com/elct9620/kobako/commit/315f923caa89bcd8752a611525da68ae53ae092f))
+* **catalog:** introduce empty Kobako::Catalog namespace ([8af8c54](https://github.com/elct9620/kobako/commit/8af8c54c72e5e5193555bcc2e86072d4a4d8176d))
+* **ext:** enforce the 16 MiB single-dispatch payload cap on host boundaries ([c80e281](https://github.com/elct9620/kobako/commit/c80e281e0810640c60d93174beddd49a31c34182))
+* **guest:** capture guest blocks via `n*&` argspec + LIFO BLOCK_STACK ([aa55556](https://github.com/elct9620/kobako/commit/aa55556aab23c159078d0ba0ea47ed878b26e89d))
+* **rpc:** build block proxy for guest-supplied yield blocks ([b6d6cf7](https://github.com/elct9620/kobako/commit/b6d6cf7f5ca857f55aafea62631b243f688c61a6))
+* **rpc:** catch/throw + frame invalidator close B-25 / B-28 / E-23 ([3b21f25](https://github.com/elct9620/kobako/commit/3b21f252fafdd2070f3953460509e24a0e643d88))
+* **transport:** introduce empty Kobako::Transport namespace ([85cda26](https://github.com/elct9620/kobako/commit/85cda268000490f521424339bec1664d0b33478b))
+* **wire:** add `block_given` field to Request envelope ([30e004f](https://github.com/elct9620/kobako/commit/30e004fa8f00739e68883889c5225c98cf9521fe))
+* **wire:** add YieldResponse envelope codec on both sides ([4592567](https://github.com/elct9620/kobako/commit/459256784af616d70738ffd0f56c3b15244b3e7c))
+
+
+### Bug Fixes
+
+* **bench:** restore renamed class references so rake bench runs ([76140cc](https://github.com/elct9620/kobako/commit/76140cc99922973fc305aab6ba727a832ddbe7ba))
+* **ext:** GC-root the dispatch Proc via a pinning mark on Kobako::Runtime ([f31bd07](https://github.com/elct9620/kobako/commit/f31bd071201b5fed7376bd13b876f103d6c6a5d6))
+* **ext:** raise SandboxError, not TrapError, when #run envelope alloc fails ([a1981fe](https://github.com/elct9620/kobako/commit/a1981fea7438090a76758147e7e84543e9d96968))
+* **transport:** fill E-xx placeholder and drop BLOCK_RESEARCH citations ([816ff80](https://github.com/elct9620/kobako/commit/816ff804535196036bec01fcd980e25036211b80))
+* **wasm:** reject unrepresentable guest return values instead of stringifying ([c3fd069](https://github.com/elct9620/kobako/commit/c3fd0698cb168b55502fb86065406caf9a7744e1))

data/Cargo.lock

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

data/README.md

@@ -1,15 +1,17 @@
 # Kobako
 
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/elct9620/kobako)
+
 Kobako is a Ruby gem that embeds a Wasm-isolated mruby interpreter inside your application, so you can execute untrusted Ruby scripts (LLM-generated code, user formulas, student submissions, third-party plugins) in-process without giving them access to host memory, files, network, or credentials.
 
-The host (`wasmtime`) runs a precompiled `kobako.wasm` guest containing mruby and an RPC client. The only way a guest script can reach the outside world is through Host App-declared **Services** — named Ruby objects you explicitly inject into the sandbox.
+The host (`wasmtime`) runs a precompiled `kobako.wasm` guest containing mruby and a Transport proxy. The only way a guest script can reach the outside world is through Host App-declared **Services** — named Ruby objects you explicitly inject into the sandbox; the guest sees each one as a proxy that forwards calls back to the host over the Transport wire.
 
 ```
         Host process                       Wasm guest
    ┌──────────────────────┐         ┌──────────────────────┐
    │  Kobako::Sandbox     │ ─eval─▶ │  mruby interpreter   │
    │                      │ ─run──▶ │                      │
-   │  Services            │ ◀──RPC─ │  KV::Lookup.call(k)  │
+   │  Services            │ ◀─call─ │  KV::Lookup.call(k)  │
    │   KV::Lookup         │ ─resp─▶ │                      │
    │                      │         │                      │
    │  stdout / stderr buf │ ◀─pipe─ │  puts / warn         │
@@ -19,21 +21,6 @@ The host (`wasmtime`) runs a precompiled `kobako.wasm` guest containing mruby an
             trusted                       untrusted
 ```
 
-## Features
-
-| 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
 
 - **Ruby ≥ 3.3.0**
@@ -61,88 +48,75 @@ result = sandbox.eval(<<~RUBY)
   1 + 2
 RUBY
 
-result        # => 3
-sandbox.stdout # => ""
+result # => 3
 ```
 
 The script executes inside the Wasm guest. It cannot read your filesystem, open sockets, or touch your `ENV`.
 
-## Injecting Services
+## Usage
 
-Guest scripts reach host resources only through Services. Declare a **Namespace**, then `bind` named **Members** on it — each member can be any Ruby object that responds to the methods the guest will call.
+### Injecting Services
+
+Declare a Namespace, then `bind` any Ruby object as a Member; the guest reaches it as a `<Namespace>::<Member>` proxy and invokes its public methods through the Transport wire. See [`docs/behavior.md`](docs/behavior.md) B-07..B-12.
 
 ```ruby
-sandbox = Kobako::Sandbox.new
+class User
+  attr_reader :name
 
-sandbox.define(:KV).bind(:Lookup, ->(key) { redis.get(key) })
-sandbox.define(:Log).bind(:Sink,   ->(msg) { logger.info(msg) })
+  def initialize(name:)
+    @name = name
+  end
+end
+
+sandbox.define(:Project).bind(:User,   User.new(name: "alice"))
+sandbox.define(:KV)     .bind(:Lookup, ->(key) { redis.get(key) })
 
 sandbox.eval(<<~RUBY)
-  Log::Sink.call("starting")
-  KV::Lookup.call("user_42")
+  Project::User.name         # => "alice"
+  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 invocation remain active across subsequent invocations; `define` after the first invocation (`#eval` or `#run`) raises `ArgumentError`.
+Names must match `/\A[A-Z]\w*\z/`. Symbol kwargs travel transparently to the host method's keyword arguments. The registry seals at the first invocation; later `#define` raises `ArgumentError`.
 
-### Keyword arguments
+### Yielding to guest blocks
 
-Keyword keys travel as Symbols and reach the host method as keyword arguments:
+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.
 
 ```ruby
-sandbox.define(:Geo).bind(:Lookup, ->(name:, region:) { "#{region}/#{name}" })
+sandbox.define(:Seq).bind(:Map, ->(items, &blk) { items.map(&blk) })
 
-sandbox.eval('Geo::Lookup.call(name: "alice", region: "us")')
-# => "us/alice"
+sandbox.eval('Seq::Map.call([1, 2, 3]) { |x| x * 2 }')
+# => [2, 4, 6]
 ```
 
-## Per-invocation caps
+### Per-invocation caps
 
-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.
+Each invocation enforces a wall-clock `timeout` and a per-invocation linear-memory `memory_limit`; exhaustion raises a `TrapError` subclass. Pass `nil` to `timeout` / `memory_limit` to disable that cap. Read [`Sandbox#usage`](lib/kobako/sandbox.rb) after the call — populated on every outcome including traps — for actual consumption ([`docs/behavior.md`](docs/behavior.md) B-35).
 
 ```ruby
 sandbox = Kobako::Sandbox.new(
-  timeout:      5.0,           # seconds, default 60.0
-  memory_limit: 10 * 1024 * 1024, # bytes, default 1 MiB
-  stdout_limit: 64 * 1024,     # bytes, default 1 MiB
+  timeout:      5.0,              # seconds, default 60.0
+  memory_limit: 10 * 1024 * 1024, # bytes,   default 1 MiB
+  stdout_limit: 64 * 1024,        # bytes,   default 1 MiB
   stderr_limit: 64 * 1024
 )
 ```
 
-| Cap            | Raises (subclass of `TrapError`)   | Default  |
-|----------------|------------------------------------|----------|
-| `timeout`      | `Kobako::TimeoutError`             | 60.0 s   |
-| `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 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.
+| Cap            | Raises                     | Default |
+|----------------|----------------------------|---------|
+| `timeout`      | `Kobako::TimeoutError`     | 60.0 s  |
+| `memory_limit` | `Kobako::MemoryLimitError` | 1 MiB   |
+| `stdout_limit` | output clipped (no raise)  | 1 MiB   |
+| `stderr_limit` | output clipped (no raise)  | 1 MiB   |
 
-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
-```
+`memory_limit` covers the per-invocation `memory.grow` delta from the entry baseline, so a Sandbox reused across invocations does not silently accumulate against a global budget.
 
-## Capturing stdout and stderr
+### Capturing stdout / stderr
 
-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.
+Guest writes through `puts` / `print` / `p` / `$stdout` / `$stderr` are buffered per-channel and exposed independently of the return value ([`docs/behavior.md`](docs/behavior.md) B-04). Buffers clear at the start of each invocation; overflow is clipped at the cap and flagged by `#stdout_truncated?` / `#stderr_truncated?`.
 
 ```ruby
-sandbox = Kobako::Sandbox.new
-
 result = sandbox.eval(<<~RUBY)
   puts "hello"
   warn "be careful"
@@ -154,50 +128,34 @@ sandbox.stdout  # => "hello\n"
 sandbox.stderr  # => "be careful\n"
 ```
 
-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.eval('puts "a" * 100_000')
-sandbox.stdout.bytesize     # => 65_536
-sandbox.stdout_truncated?   # => true
-```
-
-## Error handling
+### Error handling
 
-Every invocation (`#eval` or `#run`) either returns a value or raises exactly one of three classes:
+Every invocation either returns a value or raises exactly one of three classes, so you can route faults without inspecting messages. The full taxonomy lives in [`lib/kobako/errors.rb`](lib/kobako/errors.rb).
 
 ```ruby
 begin
   sandbox.eval(script)
-rescue Kobako::TrapError => e
-  # 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)
-  # The Sandbox is unrecoverable — discard and recreate it.
-rescue Kobako::ServiceError => e
-  # A Service call failed and the script did not rescue it.
-  # Treat like any other downstream-service failure in your app.
-rescue Kobako::SandboxError => e
-  # The script itself raised, failed to compile, or produced an
-  # unrepresentable value. A script-level fault, not infrastructure.
+rescue Kobako::TrapError
+  # Wasm engine fault or cap exhaustion. Discard the Sandbox.
+rescue Kobako::ServiceError
+  # A host Service call failed and the script did not rescue it.
+rescue Kobako::SandboxError
+  # The script raised, failed to compile, or returned an unrepresentable value.
 end
 ```
 
-`SandboxError` and `ServiceError` carry structured fields (`origin`, `klass`, `backtrace_lines`, `details`) when the guest produced a panic envelope. Named subclasses:
+| Class                           | Parent         | Trigger                                              |
+|---------------------------------|----------------|------------------------------------------------------|
+| `Kobako::TimeoutError`          | `TrapError`    | Per-invocation `timeout` exhausted                   |
+| `Kobako::MemoryLimitError`      | `TrapError`    | Per-invocation `memory_limit` exhausted              |
+| `Kobako::HandlerExhaustedError` | `SandboxError` | Handle counter reached its 2³¹ − 1 cap               |
+| `Kobako::BytecodeError`         | `SandboxError` | `#preload(binary:)` failed RITE validation at replay |
 
-| 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 |
+`SandboxError` and `ServiceError` carry structured `origin` / `klass` / `backtrace_lines` / `details` fields when the guest produced a panic envelope.
 
-## Capability Handles
+### 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::Handle` proxy it can use as the target of further RPC calls — but cannot dereference, forge from an integer, or smuggle across runs.
+A non-wire-representable host object — returned from a Service (B-14), passed to `#run` (B-34), or handed back from the guest (B-37) — crosses the boundary as an opaque `Kobako::Handle` proxy and is restored to the original object before host code sees it; any other unrepresentable value raises `Kobako::SandboxError`. Handles are scoped to a single invocation ([`docs/behavior.md`](docs/behavior.md) B-13..B-21, B-34, B-37).
 
 ```ruby
 class Greeter
@@ -207,30 +165,15 @@ end
 
 sandbox.define(:Factory).bind(:Make, ->(name) { Greeter.new(name) })
 
-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"
-```
-
-`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"
+sandbox.eval('Factory::Make.call("Bob").greet')  # => "hi, Bob"  (Handle round-trip inside guest)
+sandbox.eval('Factory::Make.call("Bob")')        # => #<Greeter @name="Bob">  (B-37 restoration)
 ```
 
-Handles are scoped to a single invocation — a Handle obtained in invocation N is invalid in invocation N+1, even on the same Sandbox.
+A `break` value from a guest block is the one exception: it unwinds back to the guest Member call rather than to host code, so a Handle in it stays a Handle — restoring would just re-wrap the same object into a new id on the return trip.
 
-## Setup-once, run-many
+### Setup-once, run-many
 
-A single Sandbox can serve many invocations. Service bindings and preloaded snippets persist; capability state (Handles, stdout, stderr) resets between invocations.
+One Sandbox serves many invocations. Service bindings and preloaded snippets persist across calls; capability state (Handles, stdout, stderr, memory delta) resets between them.
 
 ```
    ───────────── setup phase (mutable) ─────────────
@@ -271,40 +214,21 @@ A single Sandbox can serve many invocations. Service bindings and preloaded snip
      Services + snippets persist; invocation N+1 repeats.
 ```
 
-```ruby
-sandbox = Kobako::Sandbox.new
-sandbox.define(:Data).bind(:Fetch, ->(id) { records[id] })
-
-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 (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.
 
-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
 
-## 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.
+`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).
 
 ```ruby
 sandbox = Kobako::Sandbox.new
-sandbox.preload(code: "Adder = ->(a, b) { a + b }", name: :Adder)
+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"
+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):
 
@@ -320,65 +244,33 @@ Snippets replay in insertion order, so later snippets can reference constants de
                   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.
+`#preload` accepts two payload forms:
 
-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`.
+| Form     | Signature                            | Snippet name source                   | Validation timing                                                          |
+|----------|--------------------------------------|---------------------------------------|----------------------------------------------------------------------------|
+| Source   | `preload(code: "...", name: :Const)` | The `name:` keyword                   | Trial-compiled at preload; compile errors raise immediately                |
+| Bytecode | `preload(binary: bytes)`             | Read from the bytecode's `debug_info` | Deferred to first invocation; failure raises `Kobako::BytecodeError`       |
 
-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.
+Use the source form for snippets authored in your repo (compile errors fail fast at `#preload`); use the bytecode form when snippets ship as build artifacts from a separate `mrbc` pipeline. Both replay through the same per-invocation path.
 
 ## Performance
 
-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).
-
-### 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                                      |
+Order-of-magnitude figures on macOS arm64, Ruby 3.4.7, YJIT off. Absolute values vary by hardware but ratios are stable across machines. Full numbers, methodology, and the +10%-regression gate live in [`benchmark/README.md`](benchmark/README.md).
 
-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.
+| 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               |
 
-### 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).
+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.
 
 ```bash
-bundle exec rake bench   # five gated regression benchmarks (~5-8 min, ≤ 1 MiB payloads)
+bundle exec rake bench  # six gated regression benchmarks (~5-8 min)
 ```
 
 ## Development
@@ -386,19 +278,11 @@ bundle exec rake bench   # five gated regression benchmarks (~5-8 min, ≤ 1 MiB
 After checking out the repo:
 
 ```bash
-bin/setup                  # install dependencies
-bundle exec rake           # default: compile + test + rubocop + steep
-```
-
-Building from source requires a WASI-capable Rust toolchain in addition to the standard host toolchain. The first compile walks the full vendor / mruby / wasm chain:
-
-```bash
-bundle exec rake compile    # build the native extension
-bundle exec rake wasm:build # rebuild data/kobako.wasm
-bundle exec rake test       # run the Ruby test suite
+bin/setup         # install dependencies
+bundle exec rake  # default: compile + test + rubocop + steep
 ```
 
-`bin/console` opens an IRB session with the gem preloaded for experimentation. To install the local checkout as a gem, run `bundle exec rake install`.
+Building from source requires a WASI-capable Rust toolchain in addition to the standard host toolchain; the first compile walks the full vendor / mruby / wasm chain. See [`CLAUDE.md`](CLAUDE.md) for the rake task map and pipeline layout. `bin/console` opens an IRB session with the gem preloaded; `bundle exec rake install` installs the local checkout as a gem.
 
 ## Contributing
 

data/ext/kobako/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "kobako"
-version = "0.4.0"
+version = "0.6.0"
 edition = "2021"
 authors = ["Aotokitsuruya <contact@aotoki.me>"]
 license = "Apache-2.0"

data/ext/kobako/src/lib.rs

@@ -1,10 +1,12 @@
 use magnus::{Error, Ruby};
 
-mod wasm;
+mod runtime;
+mod snapshot;
 
 #[magnus::init]
 fn init(ruby: &Ruby) -> Result<(), Error> {
     let module = ruby.define_module("Kobako")?;
-    wasm::init(ruby, module)?;
+    runtime::init(ruby, module)?;
+    snapshot::init(ruby, module)?;
     Ok(())
 }