kobako 0.27.0 → 0.29.0

data/README.md

@@ -2,9 +2,9 @@
 
 [![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. Its home is the Ruby ecosystem; a Rust SDK offers the same sandbox to hosts written in other languages.
+Kobako is a Ruby gem that embeds a Wasm-isolated mruby interpreter inside your application. It runs untrusted Ruby scripts in-process — LLM-generated code, user formulas, student submissions, third-party plugins. Those scripts get no access to host memory, files, network, or credentials. Its home is the Ruby ecosystem; a Rust SDK offers the same sandbox to hosts written in other languages.
 
-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 host 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.
+The host (`wasmtime`) runs a precompiled `kobako.wasm` guest containing mruby and a Transport proxy. A guest script reaches the outside world only through Host App-declared **Services**, the named host 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
@@ -35,6 +35,8 @@ The precompiled `kobako.wasm` Guest Binary ships inside the gem, so end users do
 
 ## Installation
 
+Install the gem; it ships its Guest Binary prebuilt.
+
 ```bash
 bundle add kobako
 # or
@@ -43,7 +45,7 @@ gem install kobako
 
 ## Quick Start
 
-The same untrusted script runs identically from either host frontend. It executes inside the Wasm guest and cannot read your filesystem, open sockets, or touch your environment.
+The same untrusted script runs identically from either host frontend. It executes inside the Wasm guest and reaches no file you have not mounted for it, no socket, and none of your environment.
 
 ```ruby
 require "kobako"
@@ -55,12 +57,12 @@ sandbox.eval("1 + 2").value  # => 3
 ```rust
 use kobako::{Options, Sandbox};
 
-// Options::default() is secure by default: no caps, hermetic isolation.
+// Options::default() is secure by default: the same caps as Ruby, hermetic isolation.
 let sandbox = Sandbox::new("kobako.wasm", Options::default())?;
 sandbox.eval("1 + 2")?.value()?;  // => Value::Int(3)
 ```
 
-Each invocation returns the record of that one run — `Kobako::Execution` in Ruby, `Execution` in Rust — carrying the guest value alongside the run's output and resource usage. Nothing a run observes is stored on the Sandbox, so the same Sandbox serves concurrent invocations without them seeing each other.
+Each invocation returns the record of that one run: `Kobako::Execution` in Ruby, `Execution` in Rust. It carries the guest value alongside the run's output and resource usage. Nothing a run observes is stored on the Sandbox, so the same Sandbox serves concurrent invocations without them seeing each other.
 
 The gem bundles its Guest Binary; a Rust host loads one explicitly — see [Frontends & Guest Binaries](#frontends--guest-binaries) for the packages and the Guest Binary variants.
 
@@ -75,31 +77,23 @@ host frontend          Guest Binary
   your own      ──┘  └── kobako+json.wasm · your own
 ```
 
-They compose freely — any frontend loads any Guest Binary, so a Ruby host can run a JSON-enabled guest and a Rust host can run the pure default. How far down those choices go — and which ones a given starting point quietly makes for you — is laid out in [`docs/architecture.md`](docs/architecture.md).
+They compose freely, since any frontend loads any Guest Binary. A Ruby host can run a JSON-enabled guest, and a Rust host can run the pure default. How far down those choices go — and which ones a given starting point quietly makes for you — is laid out in [`docs/guides/assembly-levels.md`](docs/guides/assembly-levels.md).
 
 ### Host frontends
 
-The host embeds the sandbox and owns the SPEC wire codec. Choose by your host language and how much of the contract you want pre-assembled.
+The host embeds the sandbox and owns the wire codec. Choose by your host language and how much of the contract you want pre-assembled.
 
 | Frontend | Package | Add it | Best for |
 |----------|---------|--------|----------|
 | Ruby gem | `kobako` (RubyGems) | `gem install kobako` | A Ruby host — Services, Handles, snippets, and pooling out of the box |
-| Rust SDK | `kobako` (crates.io) | `kobako = "0.12"` | A Rust host — the same behavior contract behind an idiomatic Rust API |
-| Low-level crates | `kobako-wasmtime` + `kobako-runtime` + `kobako-transport` + `kobako-codec` | Cargo deps | A custom host, or driving the wire directly in another language |
+| Rust SDK | `kobako` (crates.io) | `cargo add kobako` | A Rust host — the same behavior contract behind an idiomatic Rust API |
+| Low-level crates | `kobako-wasmtime` + `kobako-runtime` + `kobako-transport` + `kobako-codec` | `cargo add` each | A custom host, or driving the wire directly in another language |
 
-The Rust crates are documented on [crates.io](https://crates.io/crates/kobako); the Ruby gem is this README. Three runnable Rust hosts show the choice: [`plugin-rs`](examples/plugin-rs) builds on the SDK, [`wire-rs`](examples/wire-rs) assembles a host by hand on the low-level crates, and [`fixed-schema-rs`](examples/fixed-schema-rs) replaces what both of those keep — the payload schema — with a guest and a host that agree on protobuf.
+The Rust crates are documented on [crates.io](https://crates.io/crates/kobako); the Ruby gem is this README. Three runnable Rust hosts show the choice. [`plugin-rs`](examples/plugin-rs) builds on the SDK, and [`wire-rs`](examples/wire-rs) assembles a host by hand on the low-level crates. [`fixed-schema-rs`](examples/fixed-schema-rs) replaces the payload schema both of those keep, with a guest and a host that agree on protobuf.
 
 ### Pre-built Guest Binaries
 
-The gem bundles the pure `kobako.wasm`. Regexp and JSON are opt-in capabilities compiled into separate variants, each attached to every [GitHub Release](https://github.com/elct9620/kobako/releases). Download a variant and point your host at it — `Sandbox.new(wasm_path:)` in Ruby, `Sandbox::new(path, ...)` in Rust.
-
-| Variant | File | Adds | Distribution |
-|---------|------|------|--------------|
-| Pure (default) | `kobako.wasm` | mruby + IO | Bundled in the gem, and a Release asset |
-| +regexp | `kobako+regexp.wasm` | Regexp / MatchData (ASCII) | Release asset |
-| +regexp-unicode | `kobako+regexp-unicode.wasm` | Regexp / MatchData (Unicode) | Release asset |
-| +json | `kobako+json.wasm` | JSON | Release asset |
-| +full | `kobako+full.wasm` | JSON + Regexp (ASCII) | Release asset |
+The gem bundles the pure `kobako.wasm`. Regexp and JSON are opt-in capabilities compiled into separate variants, each attached to every [GitHub Release](https://github.com/elct9620/kobako/releases). Download a variant and point your host at it — `Sandbox.new(wasm_path:)` in Ruby, `Sandbox::new(path, ...)` in Rust. [`docs/guides/variants.md`](docs/guides/variants.md) lists every variant and what it adds.
 
 ```ruby
 sandbox = Kobako::Sandbox.new(wasm_path: "kobako+full.wasm")
@@ -108,54 +102,40 @@ sandbox.eval('JSON.generate({ n: "42".to_i })').value  # => "{\"n\":42}"
 
 ### Custom Guest Binaries
 
-When no pre-built variant matches your capability set, assemble a guest in Rust. `kobako-mruby` is the harness; its `init_gems` hook is where you install exactly the capability gems you want — the shipped `kobako-io` / `kobako-regexp` / `kobako-json`, or your own `beni::Gem`. `kobako-core`'s `export_guest!` emits the wasm ABI. `wasm/kobako-wasm/src/guest.rs` is the worked example.
-
-| Guest crate | Role |
-|-------------|------|
-| `kobako-mruby` | mruby guest harness — the `MrbGuest` trait and provided flows |
-| `kobako-core` | Guest ABI contract — the `Guest` trait and the `export_guest!` macro |
-| `kobako-io` | IO / Kernel capability gem |
-| `kobako-regexp` | Regexp / MatchData capability gem |
-| `kobako-json` | JSON capability gem |
-
-```rust
-use beni::{Error, Mrb};
+When no variant matches your capability set, build a Guest Binary of your own in Rust. A shell over `kobako-mruby` installs exactly the capability gems you choose: the shipped `kobako-io`, `kobako-regexp`, and `kobako-json`, or your own `beni::Gem`. `kobako-core` exports the wasm ABI. The Ruby gem drives it unchanged.
 
-struct MyGuest;
+| To decide | Read |
+|---|---|
+| which parts you own at each level | [`docs/guides/assembly-levels.md`](docs/guides/assembly-levels.md) |
+| what a guest shell implements | [`docs/guides/customization.md`](docs/guides/customization.md) |
+| a working shell | [`wasm/kobako-wasm/src/guest.rs`](wasm/kobako-wasm/src/guest.rs) |
 
-// Pick the capability gems the guest exposes.
-impl kobako_mruby::MrbGuest for MyGuest {
-    fn init_gems(mrb: &Mrb) -> Result<(), Error> {
-        mrb.init_gem::<kobako_io::KobakoIo>()?;
-        mrb.init_gem::<kobako_json::KobakoJson>()?;
-        Ok(())
-    }
-}
+Build the shell as a `cdylib` for `wasm32-wasip1`, then bake its boot state into the artifact with `kobako-baker input.wasm output.wasm`.
 
-// Forward the ABI contract to the harness flows.
-impl kobako_core::Guest for MyGuest {
-    fn eval() { <MyGuest as kobako_mruby::MrbGuest>::eval() }
-    fn run(env: &[u8]) { <MyGuest as kobako_mruby::MrbGuest>::run(env) }
-    fn yield_to_block(req: &[u8]) -> u64 { <MyGuest as kobako_mruby::MrbGuest>::yield_to_block(req) }
-}
+A shell may also define flags, switches the Host App sets for every invocation. A flag is critical by default, so a Guest Binary that does not recognise it raises `Kobako::UnsupportedFlagError` rather than run without it. Mark it `advisory: true` only when a script cannot tell the flag was skipped.
 
-kobako_core::export_guest!(MyGuest);
+```ruby
+sandbox.flag(:strict_mode)                      # critical: refused where unrecognised
+sandbox.flag(:compile_cache, "on", advisory: true) # skipped where unrecognised
 ```
 
-Build the crate as a `cdylib` for `wasm32-wasip1`, then bake the canonical boot state into the artifact (see [`CLAUDE.md`](CLAUDE.md) § Build Pipeline).
-
 ## Glossary
 
-| Term | Meaning |
-|------|---------|
-| Sandbox | The reusable unit (`Kobako::Sandbox`) that runs guest code and returns a result or raises a typed error. It holds configuration only — no state from any run. |
-| Service | A host object bound at a constant-path name (`MyService::KV`) — the guest's only path to host resources. |
-| Invocation | One `#eval` or `#run`; capability state is scoped to it and ends with it. |
-| Execution | The frozen record one invocation returns (`Kobako::Execution`): its `#value`, output captures, and `#usage`. A failed run raises, carrying the same record on the error's `#execution`. |
-| Context | The per-invocation object the optional `#eval` / `#run` block receives; its `ctx.bind` supplies a Service object for that one run. |
-| Snippet | Named mruby code (source or bytecode) replayed into a fresh state before every invocation. |
-| Handle | An opaque token the guest holds for a host object the wire cannot transmit directly. |
-| Block | A guest mruby block passed to a Service; each `yield` is a synchronous round-trip into the guest. |
+These terms name the concepts the rest of this README builds on.
+
+| Term | Ruby class | Meaning |
+|------|------------|---------|
+| Sandbox | `Kobako::Sandbox` | The unit you configure once and invoke many times. |
+| Invocation | — | One run of guest code, by `#eval` or `#run`. |
+| Execution | `Kobako::Execution` | The frozen record an Invocation leaves. |
+| Service | — | A host object the guest reaches by name, such as `MyService::KV`. |
+| Mount | — | A `Kobako::Filesystem` placed at a guest path by `Sandbox#mount`, for the guest's `File`. |
+| Context | `Kobako::Context` | The per-Invocation object the optional block receives. |
+| Snippet | — | Guest source or bytecode replayed at the start of every Invocation. |
+| Handle | `Kobako::Handle` | An opaque reference to a host object the wire cannot carry by value. |
+| Block | — | Guest code passed alongside a Service call. |
+
+A Sandbox keeps nothing from one Invocation to the next. An Execution holds what the run produced, wrote, and consumed: `#value`, output captures, and `#usage`. A failed run raises, carrying its Execution on the error's `#execution`. A Service or a Mount is the guest's only route to a host resource. A Context's `ctx.bind` supplies a Service object for that one run. A Handle names its object only within the Invocation that issued it. A Block stays in the guest; each `yield` to it is a synchronous round-trip.
 
 ## Usage
 
@@ -164,6 +144,7 @@ Each section below stands on its own; this is the order they build in.
 | If you want to | Read |
 |---|---|
 | let guest code call into your host | [Services](#services), [Per-Invocation Bindings](#per-invocation-bindings), [Service Blocks](#service-blocks) |
+| let guest code read and write files | [Mounts](#mounts) |
 | see what a run produced or why it failed | [Output Capture](#output-capture), [Error Handling](#error-handling), [Invocation Lifecycle](#invocation-lifecycle) |
 | bound what a run may consume | [Resource Limits](#resource-limits), [Concurrency](#concurrency), [Pooling](#pooling) |
 | hand host objects across the boundary | [Handle Management](#handle-management) |
@@ -171,7 +152,7 @@ Each section below stands on its own; this is the order they build in.
 
 ### Services
 
-`bind` any Ruby object as a Service at a constant-path name; the guest reaches it as a `MyService::KV` (or top-level `File`) proxy and invokes the public methods its own class defines through the Transport wire. See [`SV-006`](docs/spec/behavior/services.md) and [`SV-007`](docs/spec/behavior/services.md).
+`bind` any Ruby object as a Service at a constant-path name. The guest reaches it as a `MyService::KV` (or top-level `Clock`) proxy. Through the Transport wire, the guest invokes the public methods the object's own class defines.
 
 ```ruby
 class User
@@ -191,11 +172,11 @@ sandbox.eval(<<~RUBY)
 RUBY
 ```
 
-Each `::`-separated path segment 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 (see [Invocation Lifecycle](#invocation-lifecycle)); later `#bind` raises `ArgumentError`.
+Each `::`-separated path segment must match `/\A[A-Z]\w{0,65533}\z/`. A path under `Kobako`, which the Guest Binary keeps for itself, raises `ArgumentError`. Symbol kwargs travel transparently to the host method's keyword arguments. The registry seals at the first invocation (see [Invocation Lifecycle](#invocation-lifecycle)); later `#bind` raises `ArgumentError`.
 
 ### Per-Invocation Bindings
 
-A setup-time `bind` fixes one object for the Sandbox's life. When the object belongs to a single run instead — the current request, the acting user, a per-tenant store — declare the path at setup and fill it per invocation. `bind(path)` with no object reserves the name as a *fillable*: the guest sees the constant, while an unfilled dispatch fails closed as `Kobako::ServiceError`. The optional `#eval` / `#run` block fills it ([`SV-017`](docs/spec/behavior/services.md), [`SV-024`](docs/spec/behavior/services.md)).
+A setup-time `bind` fixes one object for the Sandbox's life. Some objects belong to a single run instead: the current request, the acting user, a per-tenant store. For those, declare the path at setup and fill it per invocation. `bind(path)` with no object reserves the name as a *fillable*: the guest sees the constant, while an unfilled dispatch fails closed as `Kobako::ServiceError`. The optional `#eval` / `#run` block fills it.
 
 ```ruby
 sandbox.bind("Req::Current")  # declared, unfilled — stands for Kobako::Unresolved
@@ -203,11 +184,89 @@ sandbox.bind("Req::Current")  # declared, unfilled — stands for Kobako::Unreso
 sandbox.eval("Req::Current.user_id") { |ctx| ctx.bind("Req::Current", request) }
 ```
 
-`ctx.bind` also shadows an already-bound path for that one run. The Context is spent once the block returns, so a `ctx` captured out of it raises `ArgumentError`. Choosing the object per invocation instead of sharing one is what lets concurrent Threads invoke a single Sandbox and still keep their identities apart — the [multi-tenant example](examples/multi-tenant/) runs that shape end to end.
+`ctx.bind` also shadows an already-bound path for that one run. The Context is spent once the block returns, so a `ctx` captured out of it raises `ArgumentError`. Choosing the object per invocation lets concurrent Threads invoke a single Sandbox and still keep their identities apart. The [multi-tenant example](examples/multi-tenant/) runs that shape end to end.
+
+### Mounts
+
+`mount` places a `Kobako::Filesystem` at an absolute guest path, where the guest's `File` reads it. The default access is `:read`, so a write beneath it raises `Errno::EROFS` in the guest.
+
+```ruby
+sandbox.mount("/config", Kobako::Filesystem::Memory.new("app.yml" => yaml))
+sandbox.mount("/tmp", Kobako::Filesystem::Temporary.new, access: :read_write)
+sandbox.mount("/data", Kobako::Filesystem::Directory.new("var/data")) { |path, _access| path.end_with?(".csv") }
+
+sandbox.eval('File.read("/config/app.yml")')
+```
+
+| Kind | Holds |
+|---|---|
+| `Memory.new(files = {}, limit:, inodes:)` | files in memory, shared by every invocation |
+| `Temporary.new(limit:, inodes:)` | files in memory, empty at every invocation |
+| `Directory.new(path)` | a host directory; nothing outside it is reachable |
+| `Overlay.new.layer(fs, access:)` | Layers stacked into one view, the first added on top |
+
+A Memory or Temporary is bounded as a tmpfs mount is. Its files hold 64 MiB unless `limit:` gives another size in bytes. It holds one file or directory for each 4 KiB of that limit, and its root, unless `inodes:` gives another count. `nil` lifts either bound, and the guest raises `Errno::ENOSPC` past one.
+
+A block decides each open and each change that reaches the Mount in the access's place, asked at most once for each. A falsy answer or a `StandardError` fails that call as `Errno::EACCES`. Mounts seal with the Sandbox like a `bind`, and `ctx.mount` replaces one for a single run.
+
+#### Guest File
+
+The guest's `File.open` takes a mode String such as `"r"`, `"w+"`, or `"wx"`, or an Integer of `File::Constants` flags, valued as CRuby's on Linux. An exclusive create lets Sandboxes sharing a directory agree on a lock file. The critical flag `disable_file` removes `File` from the guest altogether.
+
+Beneath a mount, `File.open` and `IO.new` answer as CRuby does over a Linux directory. Where they differ, they only refuse more:
+
+| When | The guest sees |
+|---|---|
+| nothing is mounted | `NotImplementedError` |
+| a block refuses a change | `Errno::EACCES` where a read-only mount says `Errno::EROFS` |
+| a Ruby Filesystem's file without `append` is asked to append | `Errno::ENOTSUP` on the write |
+| an Integer mode holds a flag kobako does not honor, or `WRONLY` beside `RDWR` | `Errno::EINVAL` |
+| a mode names an encoding, such as `"r:utf-8"` | `ArgumentError` |
+| `IO.new` wraps stdout or stderr in a mode other than `"w"` | `ArgumentError` |
+| `disable_file` is set | no `File` constant |
+
+#### Overlays
+
+`layer` adds a Filesystem beneath the Layers already there and answers a new Overlay. Each Layer is `:read`, the default, or `:read_write` on its own.
+
+```ruby
+overlay = Kobako::Filesystem::Overlay.new
+  .layer(Kobako::Filesystem::Temporary.new, access: :read_write) # empty every run
+  .layer(Kobako::Filesystem::Directory.new("app"))                # never written
+sandbox.mount("/app", overlay, access: :read_write)
+```
+
+A change to a file in a writable Layer stays there. A read-only Layer's file is first copied up to the nearest writable Layer above it, and a new or renamed file lands in the topmost one. A lower writable Layer's file does not move, raising `Errno::EXDEV`, as across devices. A removal hides what a lower Layer keeps with an [OCI whiteout](https://github.com/opencontainers/image-spec/blob/main/layer.md#whiteouts), `.wh.<name>`, kept in the topmost writable Layer. Names starting with `.wh.`, in any case, are therefore reserved.
+
+#### Filesystems in Ruby
+
+Any object answering `open` and `stat` mounts as a Filesystem, directly or as a Layer. Its methods follow Ruby's `File`, `Dir`, and `IO`, so a real `::File` can answer as an open file.
+
+| Method | Answers |
+|---|---|
+| `open(path, flags)` | an open file, below |
+| `stat(path)` | an object answering `directory?`, `size`, and `ino`, as `File::Stat` does |
+| `children(path)` | entry names, as `Dir.children` gives them |
+| `mkdir` · `rmdir` · `unlink` · `rename(from, to, directory:)` | optional; without one, that change raises `Errno::EROFS` |
+
+A `stat` may also answer `dev`; without one, the Filesystem stands for a single device. An `ino` names one directory while the guest holds it open, and names match exactly, as a block judges them. A path is relative to the mount, the empty path being its root, and `flags` are `File::Constants`. A `rename` told `directory: false` moves only a file and `true` only a directory; `nil` moves either. An `Errno` the guest has a class for reaches the script as itself, and any other `StandardError` as `Errno::EIO`. Every call re-enters Ruby, and its time counts toward `timeout:` without being interrupted.
+
+##### Open Files
+
+The file `open` answers takes the guest's reads and writes, each method named as `IO` names it.
+
+| Method | Answers | Without it |
+|---|---|---|
+| `pread(length, offset)` · `size` | bytes, `nil` or `EOFError` at the end; the length | required |
+| `pwrite(data, offset)` · `truncate(length)` | bytes written; nothing | that change raises `Errno::EROFS` |
+| `append(data)` | where the file then ends, as `IO#pos` does | an append raises `Errno::ENOTSUP` |
+| `fsync` · `close` | nothing | nothing to flush or release |
+
+An `append` writes all of `data` at the end in one step, so another writer's append never lands over it.
 
 ### Output Capture
 
-Guest writes through `puts` / `print` / `p` / `$stdout` / `$stderr` are buffered per-channel and read off the run's Execution, independently of its `#value` ([`S-023`](docs/spec/behavior/sandbox.md), [`S-028`](docs/spec/behavior/sandbox.md)). Each invocation captures its own; overflow is clipped at the cap and flagged by `#stdout_truncated?` / `#stderr_truncated?`.
+Guest writes through `puts` / `print` / `p` / `$stdout` / `$stderr` are buffered per-channel and read off the run's Execution, independently of its `#value`. Each invocation captures its own; overflow is clipped at the cap and flagged by `#stdout_truncated?` / `#stderr_truncated?`.
 
 ```ruby
 execution = sandbox.eval(<<~RUBY)
@@ -229,69 +288,96 @@ Every invocation either returns an Execution or raises exactly one of three clas
 begin
   sandbox.eval(script)
 rescue Kobako::TrapError
-  # Wasm engine fault or cap exhaustion. Discard the Sandbox.
+  # Wasm engine fault or cap exhaustion. The invocation is over.
 rescue Kobako::ServiceError
   # A host Service call failed and the script did not rescue it.
 rescue Kobako::SandboxError => e
-  # The script raised, failed to compile, or returned an unrepresentable value.
+  # The script raised, failed to compile, or returned an unrepresentable value,
+  # or the Guest Binary could not start the run.
   logger.warn(e.execution.stderr)  # the failed run's own captures and usage
 end
 ```
 
-Each of these carries the failed run's Execution on `#execution`, so a rescue reads that run's output and usage exactly as a successful caller reads them off the returned one. `#failed?` keeps the two apart when both `#value` are `nil` — a script whose last expression was `nil` versus one that never produced a value. A failure caught before the guest ran at all — a host pre-flight refusal — leaves `#execution` `nil`, since there is no run to report.
+Each of these carries the failed run's Execution on `#execution`. A rescue reads that run's output and usage exactly as a successful caller reads them off the returned one. `#failed?` keeps the two apart when both `#value` are `nil` — a script whose last expression was `nil` versus one that never produced a value. A failure caught before the guest ran at all — a host pre-flight refusal — leaves `#execution` `nil`, since there is no run to report.
 
 | Class                           | Parent         | Trigger                                              |
 |---------------------------------|----------------|------------------------------------------------------|
 | `Kobako::TimeoutError`          | `TrapError`    | Per-invocation `timeout` exhausted                   |
 | `Kobako::MemoryLimitError`      | `TrapError`    | Per-invocation `memory_limit` exhausted              |
+| `Kobako::NoServiceError`        | `ServiceError` | Nothing bound there, a dead Handle, or a method the guest may not call |
+| `Kobako::ServiceArgumentError`  | `ServiceError` | The call would not bind, or the Service raised `ArgumentError` |
 | `Kobako::HandleExhaustedError` | `SandboxError` | Handle counter reached its 2³¹ − 1 cap               |
 | `Kobako::BytecodeError`         | `SandboxError` | `#preload(binary:)` failed RITE validation at replay |
+| `Kobako::UnsupportedFlagError`  | `SandboxError` | The Guest Binary does not recognise a critical `#flag`; no script ran |
 | `Kobako::UndefinedEntrypointError` | `SandboxError` | `#run` named a constant no snippet defined; carries `#name` and `#available` |
 
 `SandboxError` and `ServiceError` carry structured `origin` / `klass` / `backtrace_lines` fields when the guest produced a panic envelope.
 
+#### Host Exceptions
+
+A Service, a mount's block, or a Filesystem written in Ruby is your code running inside the run. What it raises splits by class.
+
+| Raised by your code                     | Result                                        |
+|-----------------------------------------|-----------------------------------------------|
+| a `StandardError`                       | the guest sees a failure it may rescue        |
+| `Interrupt`, `exit`, `throw`, `Timeout` | the run ends; the invocation raises it as is  |
+
 ### Resource Limits
 
-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 [`Execution#usage`](lib/kobako/execution.rb) for actual consumption — populated on every outcome, so a rescued trap reports it just as a completed run does ([`S-058`](docs/spec/behavior/sandbox.md), [`S-061`](docs/spec/behavior/sandbox.md)).
+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 [`Execution#usage`](lib/kobako/execution.rb) for actual consumption — populated on every outcome, so a rescued trap reports it just as a completed run does.
 
 ```ruby
 sandbox = Kobako::Sandbox.new(
   timeout:      5.0,              # seconds, default 60.0
-  memory_limit: 10 * 1024 * 1024, # bytes,   default 1 MiB
+  setup_timeout: 2.0,             # seconds, default 10.0
+  memory_limit: 10 * 1024 * 1024, # bytes,   default 4 MiB
   stdout_limit: 64 * 1024,        # bytes,   default 1 MiB
-  stderr_limit: 64 * 1024
+  stderr_limit: 64 * 1024,
+  open_file_limit: 16             # descriptors, default 1024
 )
 ```
 
-| 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   |
+| Cap               | Raises                         | Default |
+|-------------------|--------------------------------|---------|
+| `timeout`         | `Kobako::TimeoutError`         | 60.0 s  |
+| `setup_timeout`   | `Kobako::SetupError` at `new`  | 10.0 s  |
+| `memory_limit`    | `Kobako::MemoryLimitError`     | 4 MiB   |
+| `stdout_limit`    | output clipped (no raise)      | 1 MiB   |
+| `stderr_limit`    | output clipped (no raise)      | 1 MiB   |
+| `open_file_limit` | `Errno::EMFILE` in the guest   | 1024    |
 
-`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.
+`setup_timeout` bounds instantiating a Guest Binary and reading its ABI version, not compiling it. It applies the first time a path is loaded; later Sandboxes on that path skip the check. A Pool builds each Sandbox at its first checkout, so its `SetupError` raises from `with`. `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. `open_file_limit` counts every descriptor one invocation holds, the three standard ones and each Mount's included, so a guest cannot exhaust the host process's own.
+
+#### Isolation Profile
+
+Beyond the caps, `profile:` requests the Sandbox's isolation posture on a two-rung ladder.
+
+```
+:permissive  <  :hermetic (default)
+live clock      frozen clock
+live entropy    constant entropy
+```
 
-Beyond the four caps, `profile:` requests the Sandbox's isolation posture on the `:permissive` < `:hermetic` ladder (default `:hermetic`). `:hermetic` denies the guest ambient time and entropy; `:permissive` lets the guest's `wasi:clocks` / `wasi:random` read live host sources — an explicit trade of reproducibility, with filesystem, environment, and network still unreachable. The request is also a floor: construction fails with `Kobako::SetupError` on a runtime that declares a weaker posture than requested. See [`docs/security-model.md`](docs/security-model.md) § Isolation profiles.
+`:hermetic` denies the guest ambient time and entropy; `:permissive` lets the guest's `wasi:clocks` / `wasi:random` read live host sources, an explicit trade of reproducibility. The guest reaches no ambient filesystem, environment, or network under either. The request is also a floor: construction fails with `Kobako::SetupError` on a runtime that declares a weaker posture than requested. See [`docs/guides/security.md`](docs/guides/security.md) § Isolation Profiles.
 
 ### Concurrency
 
-A Sandbox keeps no state from any run, so concurrent Threads may invoke distinct Sandboxes or share a single one; each invocation owns its Handles, captures, and usage either way ([`RT-001`](docs/spec/behavior/runtime.md), [`RT-002`](docs/spec/behavior/runtime.md)). One Thread still runs one invocation at a time. Sharing a Sandbox adds a single obligation.
+A Sandbox keeps no state from any run, so concurrent Threads may invoke distinct Sandboxes or share a single one. Each invocation owns its Handles, captures, and usage either way. One Thread still runs one invocation at a time. Sharing a Sandbox adds a single obligation.
 
 | What you bind | Who reaches it | What it owes |
 |---|---|---|
 | Bound once at setup | every Thread sharing the Sandbox | it must itself be thread-safe |
 | Supplied per invocation — `ctx.bind`, or an Extension `provider:` | that invocation alone | nothing |
 
-#### Choosing a GVL mode
+#### GVL Modes
 
-By default an invocation holds Ruby's GVL for its whole span, so guest execution across Threads serializes. `gvl: :release` drops the GVL for the guest span and re-acquires it for each guest→host dispatch, running guest code in parallel across Threads ([`RT-024`](docs/spec/behavior/runtime.md), [`RT-026`](docs/spec/behavior/runtime.md)).
+By default an invocation holds Ruby's GVL for its whole span, so guest execution across Threads serializes. `gvl: :release` drops the GVL for the guest span and re-acquires it for each guest→host dispatch, running guest code in parallel across Threads.
 
 ```ruby
 sandbox = Kobako::Sandbox.new(gvl: :release)
 ```
 
-The mode is per-Sandbox and fixed at construction; it changes scheduling only, leaving isolation, Handle lifetimes, captures, and outcomes identical. `:hold` remains the default because releasing pays a handoff cost at every dispatch: compute-bound scripts scale with Thread count, while dispatch-heavy ones match or trail `:hold`. `rake bench:gvl_scheduling` measures both ends on your own hardware.
+The mode is per-Sandbox and fixed at construction; it changes scheduling only, leaving isolation, Handle lifetimes, captures, and outcomes identical. `:hold` remains the default because releasing pays a handoff cost at every dispatch. Compute-bound scripts scale with Thread count, while dispatch-heavy ones match or trail `:hold`. `rake bench:gvl_scheduling` measures both ends on your own hardware.
 
 ### Invocation Lifecycle
 
@@ -342,11 +428,11 @@ One Sandbox serves many invocations. Service bindings and preloaded snippets per
      Services + snippets persist; invocation N+1 repeats.
 ```
 
-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, construct a fresh `Kobako::Sandbox` per scope: per tenant, per student submission, per agent session. wasmtime's Engine and the compiled Module are cached at process scope, so additional Sandboxes amortize cold-start cost automatically.
 
 ### Pooling
 
-For hosts that serve many short invocations, `Kobako::Pool` keeps a bounded set of warm, identically set-up Sandboxes and hands each one to a single exclusive holder at a time ([`PL-003`](docs/spec/behavior/pool.md), [`PL-011`](docs/spec/behavior/pool.md)). Construction forwards every `Sandbox.new` keyword verbatim; the optional block is the per-Sandbox setup window and runs exactly once per constructed Sandbox.
+For hosts that serve many short invocations, `Kobako::Pool` keeps a bounded set of warm, identically set-up Sandboxes. It hands each one to a single exclusive holder at a time. Construction forwards every `Sandbox.new` keyword verbatim; the optional block is the per-Sandbox setup window and runs exactly once per constructed Sandbox.
 
 ```ruby
 pool = Kobako::Pool.new(slots: 4) do |sandbox|
@@ -363,19 +449,19 @@ pool.with { |sandbox| sandbox.eval(%(KV::Lookup.call("user_42"))).value }
 | `slots:` | Upper bound on constructed Sandboxes | required |
 | `checkout_timeout:` | Seconds `#with` waits for a free Sandbox; `nil` waits indefinitely | 5.0 |
 
-Sandboxes construct lazily on first demand. `#with` yields a Sandbox and returns the block's value; at block exit the Sandbox returns to the pool, except a block that raises `Kobako::TrapError` discards its Sandbox and the slot refills by a fresh construction on next demand. A checkout that waits past `checkout_timeout` raises `Kobako::PoolTimeoutError`. There is no teardown verb — a Pool releases everything with its own reachability.
+Sandboxes construct lazily on first demand. `#with` yields a Sandbox and returns the block's value, and at block exit the Sandbox returns to the pool, whatever the block raised. A checkout that waits past `checkout_timeout` raises `Kobako::PoolTimeoutError`. There is no teardown verb — a Pool releases everything with its own reachability.
 
-#### What a Pool buys
+#### Pool Trade-offs
 
 | It gives you | It does not give you |
 |---|---|
-| warm, pre-configured Sandboxes and exclusive checkout | isolation — a Sandbox holds no state from any run, so Threads sharing one are equally safe (see [Concurrency](#concurrency)) |
+| warm, pre-configured Sandboxes and exclusive checkout | isolation (see [Concurrency](#concurrency)) |
 
-`Kobako::Pool` is experimental today and is best treated as a convenience for warm, pre-configured reuse rather than a throughput optimisation. The build bakes the shared boot state into the artifact ([`mruby.md`](docs/spec/behavior/mruby.md)) and every dynamic script still compiles and runs per invocation, so all a pool actually saves is the host-side `Sandbox.new` — now about 3 µs, an order of magnitude below the invocation that follows it. For the workload kobako is built for — many small, short-lived Sandboxes running dynamic scripts — that is not a gain worth the coupling.
+A Sandbox holds no state from any run, so Threads sharing one are equally safe. `Kobako::Pool` is experimental today and is best treated as a convenience for warm, pre-configured reuse rather than a throughput optimisation. The build bakes the shared boot state into the artifact, and every dynamic script still compiles and runs per invocation. All a pool actually saves is the host-side `Sandbox.new` — now about 3 µs, an order of magnitude below the invocation that follows it. For the workload kobako is built for — many small, short-lived Sandboxes running dynamic scripts — that is not a gain worth the coupling.
 
 ### Service Blocks
 
-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 [`T-085`](docs/spec/behavior/transport-yield.md) and [`T-089`](docs/spec/behavior/transport-yield.md).
+A Service method can accept a guest-supplied block via `&blk` and `yield` into it. The block body runs inside the Wasm guest. Its `break` / `next` / `return` / exceptions follow normal Ruby semantics: an exit lands where it would through a plain method.
 
 ```ruby
 sandbox.bind("Seq::Map", ->(items, &blk) { items.map(&blk) })
@@ -384,9 +470,32 @@ sandbox.eval('Seq::Map.call([1, 2, 3]) { |x| x * 2 }').value
 # => [2, 4, 6]
 ```
 
+A `yield` that cannot complete raises at the Service's call site, so the Service may rescue it. Left unrescued, a `BlockError` hands the guest its own exception back; the others fail the Service call.
+
+| Class                      | Trigger at `yield`                    |
+|----------------------------|---------------------------------------|
+| `Kobako::BlockError`       | The guest block raised                |
+| `Kobako::YieldValueError`  | An argument cannot cross to the guest |
+| `Kobako::UnsupportedError` | The Guest Binary serves no block      |
+| `ThreadError`              | The block runs off the calling Fiber  |
+
+#### Block Fiber
+
+A block runs only on the Fiber that called the Service. The guest's Wasm stack lives on that Fiber's native stack, so entering it from another raises `ThreadError` before the block runs. CRuby itself lets a block run anywhere; kobako narrows that to keep the guest's stack checks sound.
+
+```
+Service on the calling Fiber
+  ├─ blk.call / yield                     ─> runs in the guest
+  ├─ Thread.new { blk.call }              ─> ThreadError
+  └─ Enumerator.new { |y| y << blk.call }
+       .next   (runs its body on a Fiber) ─> ThreadError
+```
+
+`Enumerator#next` counts as another Fiber, because it runs the enumerator's body on one. Internal iteration such as `each` or `map` stays on the calling Fiber and runs the block normally.
+
 ### Handle Management
 
-A non-wire-representable host object — returned from a Service ([`T-001`](docs/spec/behavior/transport-dispatch.md)), passed to `#run` ([`T-066`](docs/spec/behavior/transport-dispatch.md)), or handed back from the guest ([`T-054`](docs/spec/behavior/transport-dispatch.md)) — 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 ([`T-038`](docs/spec/behavior/transport-dispatch.md)).
+A host object the wire cannot represent may be returned from a Service, passed to `#run`, or handed back from the guest. It 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.
 
 ```ruby
 class Greeter
@@ -400,11 +509,11 @@ sandbox.eval('Factory::Make.call("Bob").greet').value  # => "hi, Bob"  (Handle r
 sandbox.eval('Factory::Make.call("Bob")').value        # => #<Greeter @name="Bob">  (Handle restoration)
 ```
 
-A `break` value from a guest block is the one exception: it unwinds back to the guest Service 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.
+A `break` value from a guest block never reaches host code. It stays in the guest while the Service unwinds, so a Handle in it stays a Handle.
 
-#### One Handle per dispatch
+#### Per-dispatch Handles
 
-Each dispatch that hands back a non-wire-representable object allocates a *new* Handle — kobako never deduplicates by object identity ([`T-007`](docs/spec/behavior/transport-dispatch.md), [`T-009`](docs/spec/behavior/transport-dispatch.md)). This is most visible with fluent / builder APIs. An `ActiveRecord::Relation` chain `spawn`s a fresh relation at each step, so every hop is an independent dispatch that binds its own Handle:
+Each dispatch that hands back a non-wire-representable object allocates a *new* Handle — kobako never deduplicates by object identity. This is most visible with fluent / builder APIs. An `ActiveRecord::Relation` chain `spawn`s a fresh relation at each step, so every hop is an independent dispatch that binds its own Handle:
 
 ```
    guest chain                        host  (Catalog::Handles, one invocation)
@@ -420,11 +529,11 @@ Each dispatch that hands back a non-wire-representable object allocates a *new*
    all stay live until the invocation ends, then reset together
 ```
 
-This is deliberate, not a leak. Handle IDs run to 2³¹ − 1 per invocation and reset between invocations, so even deep chains stay far inside the range. Two consequences are worth keeping in mind: the same host object handed back twice yields two *different* Handles — the guest cannot tell they alias — and every intermediate Handle stays live until the invocation ends, since there is no per-Handle release ([`transport-dispatch.md`](docs/spec/behavior/transport-dispatch.md)).
+This is deliberate, not a leak. Handle IDs run to 2³¹ − 1 per invocation and reset between invocations, so even deep chains stay far inside the range. Two consequences are worth keeping in mind. The same host object handed back twice yields two *different* Handles, and the guest cannot tell they alias. Every intermediate Handle stays live until the invocation ends, since there is no per-Handle release.
 
 ### Snippets & Entrypoints
 
-`Sandbox#preload` registers named mruby snippets that replay into every invocation's canonical boot state; `Sandbox#run(:Target, *args, **kwargs)` dispatches into a top-level `Object` constant defined by those snippets ([`S-053`](docs/spec/behavior/sandbox.md), [`S-045`](docs/spec/behavior/sandbox.md)).
+`Sandbox#preload` registers named mruby snippets that replay into every invocation's canonical boot state; `Sandbox#run(:Target, *args, **kwargs)` dispatches into a top-level `Object` constant defined by those snippets.
 
 ```ruby
 sandbox = Kobako::Sandbox.new
@@ -435,9 +544,9 @@ sandbox.run(:Adder, 2, 3).value            # => 5
 sandbox.run(:Greeter, name: "world").value # => "hello, world"
 ```
 
-An entrypoint's `kwargs` arrive as a trailing positional Hash — mruby's C-side call path carries no keyword arguments — so declare a Hash parameter and unpack it yourself.
+An entrypoint's `kwargs` arrive as a trailing positional Hash, because mruby's C-side call path carries no keyword arguments. Declare a Hash parameter and unpack it yourself.
 
-A target no snippet defined raises `Kobako::UndefinedEntrypointError`, whose `#available` lists the top-level constants the snippets did contribute — so the name is corrected from the error rather than by reading the guest source.
+A target no snippet defined raises `Kobako::UndefinedEntrypointError`. Its `#available` lists the top-level constants the snippets did contribute, so the name is corrected from the error rather than by reading the guest source.
 
 ```
    per-invocation replay (every #eval / #run, snippets in insertion order):
@@ -454,7 +563,7 @@ A target no snippet defined raises `Kobako::UndefinedEntrypointError`, whose `#a
               return the Execution, then discard the instance
 ```
 
-#### Choosing a payload form
+#### Payload Forms
 
 `#preload` accepts two payload forms:
 
@@ -463,15 +572,15 @@ A target no snippet defined raises `Kobako::UndefinedEntrypointError`, whose `#a
 | Source   | `preload(code: "...", name: :Const)` | The `name:` keyword                   | First invocation's replay; compile errors raise `Kobako::SandboxError`     |
 | Bytecode | `preload(binary: bytes)`             | Read from the bytecode's `debug_info` | First invocation's replay; structural failure raises `Kobako::BytecodeError` |
 
-Use the source form for snippets authored in your repo; use the bytecode form when snippets ship as build artifacts from a separate `mrbc` pipeline. Both replay through the same per-invocation path, so no snippet content failure surfaces at `#preload` — force the first replay with a no-op invocation (e.g. `sandbox.eval("nil")`) when you want validation before real traffic.
+Use the source form for snippets authored in your repo; use the bytecode form when snippets ship as build artifacts from a separate `mrbc` pipeline. Source is compiled once, before the first invocation, and replays as bytecode from then on, so the bytecode form saves only that one compile. Both replay through the same per-invocation path, so no snippet content failure surfaces at `#preload` — force the first replay with a no-op invocation (e.g. `sandbox.eval("nil")`) when you want validation before real traffic.
 
 ### Extensions
 
-An Extension teaches the guest a native-style constant by pairing a guest idiom (`source`) with an optional host `backend`. `Sandbox#install` composes the two through the existing `#preload` and `#bind` verbs, adding no wire or Guest Binary surface: pure operations run in-guest with no round-trip, while the rest dispatch to the backend under the same isolation and reflection guarantees as any bound Service ([`docs/extensions.md`](docs/extensions.md), [`EX-005`](docs/spec/behavior/extension.md), [`EX-006`](docs/spec/behavior/extension.md)).
+An Extension teaches the guest a native-style constant by pairing a guest idiom (`source`) with an optional host `backend`. `Sandbox#install` composes the two through the existing `#preload` and `#bind` verbs, adding no wire or Guest Binary surface. Pure operations run in-guest with no round-trip. The rest dispatch to the backend under the same isolation and reflection guarantees as any bound Service ([`docs/guides/extensions.md`](docs/guides/extensions.md)).
 
 ```ruby
-FILE = <<~'MRUBY'
-  class File
+VFS = <<~'MRUBY'
+  class Vfs
     extend Kobako::Proxy
     def self.basename(path) = path.split("/").last || ""  # pure: runs in-guest
     # read / write are undefined here, so they dispatch to the backend
@@ -480,16 +589,16 @@ MRUBY
 
 sandbox.install(
   Kobako::Extension.new(
-    name: :File,
-    source: FILE,
+    name: :Vfs,
+    source: VFS,
     backend: Kobako::Extension::Backend.new(
-      path: "File",
-      provider: -> { OverlayFileSystem.new(root) }  # invoked once per invocation
+      path: "Vfs",
+      provider: -> { CopyOnWriteFiles.new(root) }  # invoked once per invocation
     )
   )
 )
 
-sandbox.eval('File.read("sample.txt")')  # dispatches to the backend's #read
+sandbox.eval('Vfs.read("sample.txt")')  # dispatches to the backend's #read
 ```
 
 A backend declares the bound object's lifetime by keyword, never by inference — so a static object that happens to be callable stays unambiguous.
@@ -497,17 +606,17 @@ A backend declares the bound object's lifetime by keyword, never by inference
 | Keyword     | Lifetime                                                                    |
 |-------------|-----------------------------------------------------------------------------|
 | `object:`   | One object, shared by every invocation                                       |
-| `provider:` | A no-argument callable invoked per invocation — what a writable backend needs, so its state cannot leak across runs |
+| `provider:` | A no-argument callable invoked per invocation                               |
 | neither     | A fillable, standing for `Kobako::Unresolved` until `ctx.bind` supplies the run's object |
 
-kobako ships no concrete Extension; the idiom and backend are yours. The [overlay VFS example](examples/vfs/) is a worked `File` that reads through to disk while protecting it from guest writes.
+A writable backend takes `provider:`, so its state cannot leak across runs. kobako ships no concrete Extension; the idiom and backend are yours. The [overlay VFS example](examples/vfs/) is a worked virtual file that reads through to disk while protecting it from guest writes.
 
 ## Security
 
-kobako isolates the guest, but **what it may reach is whatever you `bind`** — and `bind`
-exposes every public method the object's own class defines. Inherited, mixed-in, and built-in
-methods stay out of reach, but the class's own surface does not, so bind a purpose-built
-object scoped to the task, not a capable one whose other methods leak more than you intend.
+kobako isolates the guest, but **what it may reach is whatever you `bind` or `mount`**.
+`bind` exposes every public method the object's own class defines. Inherited, mixed-in, and built-in
+methods stay out of reach, but the class's own surface does not. Bind a purpose-built object
+scoped to the task, not a capable one whose other methods leak more than you intend.
 
 ```ruby
 class ThemeReader          # only #color is reachable; AppConfig.secret_key is not
@@ -517,30 +626,14 @@ end
 sandbox = Kobako::Sandbox.new
 sandbox.bind("Cfg::Settings", ThemeReader.new)  # not: bind("Cfg::Settings", AppConfig)
 
-sandbox.eval('Cfg::Settings.color').value  # => "#3366ff"  — every other method raises NoMethodError
-```
-
-#### Gating an object's own surface
-
-When a purpose-built wrapper is more than you need, an object can gate its own surface in
-place: a private `respond_to_guest?(name)` answers, per method, whether the guest may call
-it. Returning `false` for every name makes the object opaque — a credential the guest
-forwards to another Service but never reads — while permitting a named subset exposes exactly those.
-
-```ruby
-class Credential
-  def initialize(token) = @token = token
-  def to_s = @token
-
-  private def respond_to_guest?(_name) = false  # forwardable, never readable
-end
+sandbox.eval('Cfg::Settings.color').value  # => "#3366ff"  — any other method raises Kobako::NoServiceError
 ```
 
 Guest code can name any `MyService::KV` path, but a forged name only resolves to
-something you bound — the real authorization gate is this host-side allowlist. Give each
-trust context its own Sandbox, and see [`docs/security-model.md`](docs/security-model.md) for the rest
-as security-design concerns: validating untrusted input, default-deny external effects,
-and controlling the return surface.
+something you bound. What you bind is the real authorization gate. An object can also
+narrow its own surface with a private `respond_to_guest?`. Give each trust context its own
+Sandbox. [`docs/guides/security.md`](docs/guides/security.md) covers the rest: self-gating
+objects, validating untrusted input, default-deny external effects, and the return surface.
 
 ## Performance
 
@@ -549,25 +642,25 @@ Order-of-magnitude figures on macOS arm64, Ruby 3.4.7, YJIT off. Absolute values
 | Phase                                                        | Cost                  |
 |--------------------------------------------------------------|-----------------------|
 | First `Sandbox.new` ever for a Guest Binary (Module JIT, then disk-cached) | ~500 ms once per machine |
-| First `Sandbox.new` in a fresh process (`.cwasm` cache warm) | ~3 ms one-time        |
+| First `Sandbox.new` in a fresh process (`.cwasm` cache warm) | ~1.4 ms one-time      |
 | Subsequent `Sandbox.new` (caches warm)                       | ~3 µs                 |
-| Warm `#eval` with one Service call on a reused Sandbox       | ~70 µs                |
-| Warm `#run(:Entrypoint, ...)` dispatch                       | ~79 µs                |
-| Service call amortized inside one invocation                 | ~5.8 µs               |
-| Snippet replay per invocation                                | ~7.0 µs each          |
-| Per additional idle Sandbox (RSS)                            | ~1 KB                 |
+| Warm `#eval` with one Service call on a reused Sandbox       | ~62 µs                |
+| Warm `#run(:Entrypoint, ...)` dispatch                       | ~57 µs                |
+| Service call amortized inside one invocation                 | ~4.9 µs               |
+| Snippet replay per invocation                                | ~2.7 µs each          |
+| Per additional idle Sandbox (RSS)                            | < 1 KB                |
 
-The Cranelift JIT runs once per machine and gem version — the compiled artifact persists in a `.cwasm` disk cache, so later processes deserialize in milliseconds. An idle Sandbox holds no wasm instance (the canonical boot state is baked into the artifact and instantiated per invocation), which is why a thousand idle tenants cost ~34 MB total. A +10% regression on any SPEC-mandated benchmark blocks release.
+The Cranelift JIT runs once per machine and wasmtime release — the compiled artifact persists in a `.cwasm` disk cache, so later processes deserialize in milliseconds. An idle Sandbox holds no wasm instance, which is why a thousand idle tenants cost ~37 MB total. The canonical boot state is baked into the artifact and instantiated per invocation. A +10% regression on any gated benchmark blocks release.
 
-#### What moves the ceiling
+#### Throughput Levers
 
 | Choice | What it changes |
 |---|---|
-| `gvl: :hold` (default) | wasm work is GVL-serialized: aggregate throughput stays around 16k `#eval`/s regardless of Thread count, though Ruby-side `#eval` setup still overlaps |
+| `gvl: :hold` (default) | ~15–20k `#eval`/s in aggregate, at any Thread count |
 | `gvl: :release` | lifts that ceiling for compute-bound scripts (see [Concurrency](#concurrency)) |
-| `match?` over `=~` | `=~` (~5 µs/match) costs about 5× `match?` (~1.0 µs), because it eagerly builds the `MatchData` and match globals — prefer `match?` for boolean tests |
+| `match?` over `=~` | `=~` (~5.6 µs/match) costs about 6× `match?` (~0.9 µs) |
 
-Regexp is an opt-in capability gem, excluded from the default binary and the gated set; its throughput is tracked in a separate non-gated characterization (`#11` in [`benchmark/README.md`](benchmark/README.md)).
+Under `:hold` the GVL serializes wasm work, though Ruby-side `#eval` setup still overlaps. `=~` eagerly builds the `MatchData` and match globals, so prefer `match?` for boolean tests. Regexp is an opt-in capability gem, excluded from the default binary and the gated set. Its throughput is tracked in a separate non-gated characterization (`#11` in [`benchmark/README.md`](benchmark/README.md)).
 
 ```bash
 bundle exec rake bench  # every gated regression benchmark (~5-8 min)
@@ -579,10 +672,10 @@ After checking out the repo:
 
 ```bash
 bin/setup         # install dependencies
-bundle exec rake  # default: compile + test + rubocop + steep
+bundle exec rake  # the release gate: compile, tests, rubocop, steep, gate checks
 ```
 
-Building from source requires a WASI-capable Rust toolchain in addition to the standard host toolchain; the first compile walks the full chain — the [beni](https://github.com/elct9620/beni) gem vendors wasi-sdk + mruby and builds `libmruby.a` (`rake beni:build`), then `rake wasm:build` produces the Guest Binary. 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.
+Building from source requires a WASI-capable Rust toolchain in addition to the standard host toolchain. The first compile walks the full chain. The [beni](https://github.com/elct9620/beni) gem vendors wasi-sdk + mruby and builds `libmruby.a` (`rake beni:build`), then `rake wasm:build` produces the Guest Binary. See [`AGENTS.md`](AGENTS.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