kobako 0.5.0 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fd04d7b8efaf9ccb41ff873a66b0855839222c5bc034d80a854b9fbc25602570
-  data.tar.gz: 718665fbcfb89faafc86f018a247e37ea304c3c8559e4febc240ad95bdc15654
+  metadata.gz: 65375590ffd16758a33fee3ef16cfd3d1e99e439c378e9652da453a601b53f8a
+  data.tar.gz: 62c134b7035649fcde436816d95618287768f7a8a09d59f330cb5e785eae8024
 SHA512:
-  metadata.gz: e9cd6493f200abbb9a9014e9222633fec67e8813a854b93e71a29d94a3738ff64dfe33f5b136efe472d87831fb78062a09ac481d1da6970782e965a7a7aeafc8
-  data.tar.gz: 7f11f9fb3e48efc808eebd0598bc19569c6c1fd90322cee2f65f9030d8ca39a3da6cbe9fa68edb33480e926aabcb3766c2dc8c37995945ceaebd7b9952d9ec0f
+  metadata.gz: cc4ad901e03f7de534c41423e3e7795a410d7201caf7a4d730b93829aceefc8ff7518320c2874a80e34978a9e38d6a430b5e03edbcd2e6868cb987c1d8ed3c91
+  data.tar.gz: 0b594e9b033b3a2d27b9f330b119ddf3f246b50f462cfb8914173d4074064ce17c3f12fb20851331f1e7c50390c39f64722820564618148de37fa06a4f603beb

data/.release-please-manifest.json

@@ -1 +1 @@
-{".":"0.5.0"}
+{".":"0.6.1"}

data/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## [0.6.1](https://github.com/elct9620/kobako/compare/v0.6.0...v0.6.1) (2026-05-28)
+
+
+### Bug Fixes
+
+* **loader:** try Ruby-ABI subdir before bare path ([51017eb](https://github.com/elct9620/kobako/commit/51017eb5ee40fa722ec962ce3b9a5d016b128d41))
+
+## [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)
 
 

data/Cargo.lock

@@ -864,7 +864,7 @@ dependencies = [
 
 [[package]]
 name = "kobako"
-version = "0.5.0"
+version = "0.6.1"
 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,49 +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::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
@@ -206,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) ─────────────
@@ -270,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):
 
@@ -319,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
@@ -385,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.5.0"
+version = "0.6.1"
 edition = "2021"
 authors = ["Aotokitsuruya <contact@aotoki.me>"]
 license = "Apache-2.0"

data/lib/kobako/catalog/namespaces.rb

@@ -59,10 +59,11 @@ module Kobako
         @namespaces[name_str] ||= Namespace.new(name_str)
       end
 
-      # Resolve a +target+ path of the form +"Namespace::Member"+ to the
-      # bound Host object. +target+ is a two-level path using the +::+
-      # separator. Returns the bound Host object. Raises +KeyError+ when the
-      # namespace or the member is not bound.
+      # Resolve a +target+ path of the form +"<Namespace>::<Member>"+
+      # (e.g. +"MyService::KV"+) to the bound Host object. +target+ is a
+      # two-level path using the +::+ separator. Returns the bound Host
+      # object. Raises +KeyError+ when the namespace or the member is not
+      # bound.
       def lookup(target)
         namespace_name, member_name = target.to_s.split("::", 2)
         namespace = @namespaces[namespace_name]

data/lib/kobako/codec/utils.rb

@@ -116,6 +116,33 @@ module Kobako
         end
       end
 
+      # Deep-walk Array / Hash containers in +value+ and replace every
+      # +Kobako::Handle+ leaf with the host-side object +handler+ resolves
+      # it to ({docs/behavior.md B-37}[link:../../../docs/behavior.md]).
+      # The symmetric inverse of {deep_wrap}: that walk allocates objects
+      # into Handles on the host→guest argument path; this walk resolves
+      # Handles back to their objects on every guest→host value path — the
+      # +#eval+ / +#run+ result and the yield-block result alike. The walk
+      # descends through Array elements and Hash keys and values one
+      # structural level at a time; any non-Handle leaf passes through
+      # unchanged.
+      #
+      # +value+ is a decoded Ruby value (a Handle here is a wire-decoded
+      # +Kobako::Handle+, never a guest-forged one — B-20); +handler+ must
+      # respond to +#fetch(id) -> object+ (a host-side
+      # +Kobako::Catalog::Handles+). +handler.fetch+ raises
+      # +Kobako::SandboxError+ for an id with no live binding, which is the
+      # corrupted-runtime fallback B-37 specifies.
+      def deep_restore(value, handler)
+        case value
+        when ::Array then value.map { |element| Utils.deep_restore(element, handler) }
+        when ::Hash
+          value.to_h { |key, val| [Utils.deep_restore(key, handler), Utils.deep_restore(val, handler)] }
+        when Kobako::Handle then handler.fetch(value.id)
+        else value
+        end
+      end
+
       # Predicate split out of {representable?} for cyclomatic
       # budget — the closed-set non-container branch. Returns +true+ for
       # the scalar leaves and an existing Handle. Not part of the

data/lib/kobako/sandbox.rb

@@ -3,6 +3,7 @@
 require "forwardable"
 
 require_relative "capture"
+require_relative "codec"
 require_relative "errors"
 require_relative "outcome"
 require_relative "sandbox_options"
@@ -304,7 +305,11 @@ module Kobako
       snapshot = yield
       @stdout_capture = snapshot.stdout
       @stderr_capture = snapshot.stderr
-      Outcome.decode(snapshot.return_bytes)
+      # A Capability Handle in the result is decoded as a Kobako::Handle
+      # token; restore it to the host object the guest referenced before
+      # handing the value to the Host App (B-37). @handler still holds this
+      # invocation's table — reset only happens at the next #begin_invocation!.
+      Codec::Utils.deep_restore(Outcome.decode(snapshot.return_bytes), @handler)
     rescue Kobako::TrapError => e
       raise trap_class_for(e), "Sandbox##{verb} failed: #{e.message}"
     ensure

data/lib/kobako/transport/dispatcher.rb

@@ -59,7 +59,7 @@ module Kobako
         request = Kobako::Transport::Request.decode(request_bytes)
         target = resolve_target(request.target, namespaces, handler)
         args, kwargs = resolve_call_args(request, handler)
-        yielder = Yielder.new(yield_to_guest, BREAK_THROW) if request.block_given
+        yielder = Yielder.new(yield_to_guest, BREAK_THROW, handler) if request.block_given
         value = catch(BREAK_THROW) { invoke(target, request.method_name, args, kwargs, yielder) }
         encode_ok(value, handler)
       rescue StandardError => e

data/lib/kobako/transport/request.rb

@@ -20,11 +20,12 @@ module Kobako
     #
     # 5-element msgpack array:
     # +[target, method_name, args, kwargs, block_given]+. +target+ is
-    # either a +String+ (+"Namespace::Member"+) or a {Handle}. SPEC pins
-    # +kwargs+ map keys to ext 0x00 Symbol; enforced at construction so
-    # the Value Object is the single source of truth. +block_given+ is a
-    # Boolean signalling whether the guest call site supplied a block
-    # (B-23); the block body itself never crosses the wire.
+    # either a +String+ (+"<Namespace>::<Member>"+, e.g. +"MyService::KV"+)
+    # or a {Handle}. SPEC pins +kwargs+ map keys to ext 0x00 Symbol;
+    # enforced at construction so the Value Object is the single source of
+    # truth. +block_given+ is a Boolean signalling whether the guest call
+    # site supplied a block (B-23); the block body itself never crosses the
+    # wire.
     #
     # Built on the +class X < Data.define(...)+ subclass form so the
     # class body is fully Steep-visible; see +lib/kobako/outcome/panic.rb+

data/lib/kobako/transport/yielder.rb

@@ -36,21 +36,29 @@ module Kobako
       # +Runtime#yield_to_active_invocation+ bound through a lambda) that
       # {#yield} invokes to re-enter the guest; +break_tag+ is the +catch+
       # throw tag the Dispatcher matches against to unwind the Service on
-      # +tag 0x02+.
-      def initialize(yield_to_guest, break_tag)
+      # +tag 0x02+. +handler+ is the Sandbox's +Kobako::Catalog::Handles+,
+      # used to restore a Capability Handle in the block's ok value back to
+      # its host object before it reaches the Service +yield+ site
+      # ({docs/behavior.md B-37}[link:../../../docs/behavior.md]).
+      def initialize(yield_to_guest, break_tag, handler)
         @yield_to_guest = yield_to_guest
         @break_tag = break_tag
+        @handler = handler
         @active = true
       end
 
       # Re-enter the guest with +args+ and reify the YieldResponse into
       # Ruby control flow. Raises +LocalJumpError+ if called after
-      # {#invalidate!} (E-23).
+      # {#invalidate!} (E-23). The ok value is consumed by the host Service
+      # method, so a Capability Handle in it is restored to its host object
+      # (B-37). The break value unwinds past the Service back to the guest
+      # Member call (B-25), so it passes through verbatim — a Handle stays a
+      # Handle and rides back on the same id rather than churning a new one.
       def yield(*args)
         raise LocalJumpError, "guest block invoked after host dispatch frame returned" unless @active
 
         response = Kobako::Transport::Yield.decode(@yield_to_guest.call(Kobako::Codec::Encoder.encode(args)))
-        return response.value if response.ok?
+        return restore(response.value) if response.ok?
 
         throw @break_tag, response.value if response.break?
 
@@ -72,6 +80,17 @@ module Kobako
 
       private
 
+      # Restore any Capability Handle in a block's ok value to its host
+      # object via the injected +Catalog::Handles+
+      # ({docs/behavior.md B-37}[link:../../../docs/behavior.md]). Only the
+      # ok path calls this — host code consumes the ok value, whereas a
+      # break value returns to the guest and stays a Handle. Walks nested
+      # Array / Hash one level at a time; a plain value passes through
+      # unchanged.
+      def restore(value)
+        Kobako::Codec::Utils.deep_restore(value, @handler)
+      end
+
       # Reify a +YieldResponse+ tag 0x04 payload into a +RuntimeError+ the
       # Service method observes at its +yield+ site. The +{class, message,
       # backtrace}+ shape mirrors the +Kobako::Transport::Yield+ tag 0x04

data/lib/kobako/version.rb

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

data/lib/kobako.rb

@@ -1,7 +1,14 @@
 # frozen_string_literal: true
 
 require_relative "kobako/version"
-require "kobako/kobako"
+
+begin
+  RUBY_VERSION =~ /(\d+\.\d+)/
+  require "kobako/#{Regexp.last_match(1)}/kobako"
+rescue LoadError
+  require "kobako/kobako"
+end
+
 require_relative "kobako/errors"
 require_relative "kobako/transport"
 require_relative "kobako/catalog"

data/sig/kobako/codec/utils.rbs

@@ -11,6 +11,8 @@ module Kobako
 
       def self?.deep_wrap: (untyped value, Kobako::Catalog::Handles handler) -> untyped
 
+      def self?.deep_restore: (untyped value, Kobako::Catalog::Handles handler) -> untyped
+
       def self?.primitive_type?: (untyped value) -> bool
 
       def self?.container_representable?: (untyped value) -> bool

data/sig/kobako/transport/yielder.rbs

@@ -3,9 +3,10 @@ module Kobako
     class Yielder
       @yield_to_guest: ^(String) -> String
       @break_tag: Symbol
+      @handler: Kobako::Catalog::Handles
       @active: bool
 
-      def initialize: (^(String) -> String yield_to_guest, Symbol break_tag) -> void
+      def initialize: (^(String) -> String yield_to_guest, Symbol break_tag, Kobako::Catalog::Handles handler) -> void
 
       def yield: (*untyped args) -> untyped
 
@@ -15,6 +16,8 @@ module Kobako
 
       private
 
+      def restore: (untyped value) -> untyped
+
       def yield_failure: (untyped payload, default: String) -> RuntimeError
     end
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kobako
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.1
 platform: ruby
 authors:
 - Aotokitsuruya