kobako 0.5.0-arm64-darwin

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f8ef4754a6ada28af662bb388fdc9ab4eac1d1059994bcdaf51ea2cf4762e967
+  data.tar.gz: 2d0f3941b97b6c350fb87a3e425276eed154bec6fb39134535e6b194172b45a0
+SHA512:
+  metadata.gz: 394498656116fa39938fb00d09ab43bae5c6b6f3371702a11290988f91ec859f6c316384cb1b48ccd8843a22e15ff2799be1a739f01a3d6f8737284e69ad97da
+  data.tar.gz: 5f4ff76c26c7cd573a42e516d10bcbd7f6e3e9abe03f02ff70d732a685f40abb30f4c0fcd996242ebd4292e81f88c82bf2fa9e7db7ceb0e76f2a62d09f04b765

data/.release-please-manifest.json

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

data/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+## [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/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 ZhengXian Qiu
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

data/README.md

@@ -0,0 +1,408 @@
+# 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.
+
+```
+        Host process                       Wasm guest
+   ┌──────────────────────┐         ┌──────────────────────┐
+   │  Kobako::Sandbox     │ ─eval─▶ │  mruby interpreter   │
+   │                      │ ─run──▶ │                      │
+   │  Services            │ ◀──RPC─ │  KV::Lookup.call(k)  │
+   │   KV::Lookup         │ ─resp─▶ │                      │
+   │                      │         │                      │
+   │  stdout / stderr buf │ ◀─pipe─ │  puts / warn         │
+   │                      │         │                      │
+   │  return value        │ ◀─last─ │  last expression     │
+   └──────────────────────┘         └──────────────────────┘
+            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**
+- **Rust / Cargo** at install time — the native extension compiles from source via `rb_sys`
+- **Linux** or **macOS** — Windows is not supported
+
+The precompiled `kobako.wasm` Guest Binary ships inside the gem, so end users do **not** need a WASI toolchain. (The toolchain is only required if you build the gem from a source checkout — see [Development](#development).)
+
+## Installation
+
+```bash
+bundle add kobako
+# or
+gem install kobako
+```
+
+## Quick Start
+
+```ruby
+require "kobako"
+
+sandbox = Kobako::Sandbox.new
+
+result = sandbox.eval(<<~RUBY)
+  1 + 2
+RUBY
+
+result        # => 3
+sandbox.stdout # => ""
+```
+
+The script executes inside the Wasm guest. It cannot read your filesystem, open sockets, or touch your `ENV`.
+
+## Injecting Services
+
+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.
+
+```ruby
+sandbox = Kobako::Sandbox.new
+
+sandbox.define(:KV).bind(:Lookup, ->(key) { redis.get(key) })
+sandbox.define(:Log).bind(:Sink,   ->(msg) { logger.info(msg) })
+
+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 invocation remain active across subsequent invocations; `define` after the first invocation (`#eval` or `#run`) raises `ArgumentError`.
+
+### Keyword arguments
+
+Keyword keys travel as Symbols and reach the host method as keyword arguments:
+
+```ruby
+sandbox.define(:Geo).bind(:Lookup, ->(name:, region:) { "#{region}/#{name}" })
+
+sandbox.eval('Geo::Lookup.call(name: "alice", region: "us")')
+# => "us/alice"
+```
+
+## 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.
+
+```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
+  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.
+
+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-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.eval(<<~RUBY)
+  puts "hello"
+  warn "be careful"
+  42
+RUBY
+
+result          # => 42
+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
+
+Every invocation (`#eval` or `#run`) either returns a value or raises exactly one of three classes:
+
+```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.
+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::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::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
+  def initialize(name) = @name = name
+  def greet            = "hi, #{@name}"
+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"
+```
+
+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 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.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
+
+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                                      |
+
+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 (~5-8 min, ≤ 1 MiB payloads)
+```
+
+## Development
+
+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/console` opens an IRB session with the gem preloaded for experimentation. To install the local checkout as a gem, run `bundle exec rake install`.
+
+## Contributing
+
+Bug reports and pull requests are welcome at <https://github.com/elct9620/kobako>. Please open an issue before starting on non-trivial changes so we can align on scope.
+
+## License
+
+Kobako is released under the [Apache License 2.0](https://opensource.org/licenses/Apache-2.0).