kobako 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 07f319ca70c97b9baa6d70eb177f2065d6a74544587e55527ce948f5921816af
-  data.tar.gz: 9c598b981d38f624599cb7dcae745747a651265d9803a3a69915daf8634f0d5d
+  metadata.gz: 5762f0343892aa61a22ad0bc458f958abcf37726bb9d07285109d57ae20c69ea
+  data.tar.gz: 805bd0255ce3a16f777584a7efd21b56bf3058981d79a2ddadd815b62bb32a2a
 SHA512:
-  metadata.gz: 3a834499680c55b497f473480c90192a012353894737bba9a26a3ed9a3b211af86fa00699e086c1ac5e2957bb04d088ed1852300899784494365ec7b237226ec
-  data.tar.gz: 2eb27c6a401396a8dc2b4811281adf037b6629c10d43366ecd1b76ffebddfe5408eeaae76c10b36ec8bbc0754e38d2b5192260ac1f28dd422b9182712550d8a2
+  metadata.gz: 8e6df0644967ea64e585e2e5168d7db6a39be5d8100d1e69430bfb60d1e573a04aaa516033bdc80a48f5bb9127e5c37665824d5bc1333361964be3efb0f6ff62
+  data.tar.gz: 766fb001c38b111d24fcf8e07b1add66926fb3311016775f0f8eb4053113bb7cf9152339463023e5be88f5083e4db59686ad458569e83a7807eca5369c28276d

data/Cargo.lock

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

data/README.md

@@ -4,15 +4,31 @@ Kobako is a Ruby gem that embeds a Wasm-isolated mruby interpreter inside your a
 
 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     │ ──run─▶ │  mruby interpreter   │
+   │                      │         │                      │
+   │  Services            │ ◀──RPC─ │  KV::Lookup.call(k)  │
+   │   KV::Lookup         │ ─resp─▶ │                      │
+   │                      │         │                      │
+   │  stdout / stderr buf │ ◀─pipe─ │  puts / warn         │
+   │                      │         │                      │
+   │  return value        │ ◀─last─ │  last expression     │
+   └──────────────────────┘         └──────────────────────┘
+            trusted                       untrusted
+```
+
 ## Features
 
 - **In-process Wasm sandbox** — no subprocess, no container. Each `Sandbox#run` is a synchronous Ruby call.
-- **Capability injection via Services** — guest scripts can only call Ruby objects you explicitly `bind` under a two-level `Group::Member` namespace.
-- **Structured outcome** — `#run` returns the deserialized last expression of the guest script as a normal Ruby value.
-- **Three-class error taxonomy** — every failure is exactly one of `TrapError` (Wasm engine), `SandboxError` (script / wire fault), or `ServiceError` (Service capability fault), so you can route errors without inspecting messages.
+- **Per-run caps** — every `#run` enforces a wall-clock `timeout` (default 60 s) and a guest `memory_limit` (default 5 MiB). Exhaustion raises `Kobako::TimeoutError` / `Kobako::MemoryLimitError`.
+- **Capability injection via Services** — guest scripts can only call Ruby objects you explicitly `bind` under a two-level `Namespace::Member` path.
+- **Three-class error taxonomy** — every failure is exactly one of `TrapError` (Wasm engine / per-run cap), `SandboxError` (script / wire fault), or `ServiceError` (Service capability fault), so you can route errors without inspecting messages.
 - **Per-run state reset** — Handles issued during one `#run` are invalidated before the next; Service bindings remain.
-- **Separated stdout / stderr capture** — guest `puts`/`warn` output is buffered (1 MiB default cap, configurable, with a `[truncated]` marker on overflow) and is independent of the RPC channel.
-- **Capability Handles** — Services may return stateful host objects; the guest receives an opaque token it can use as the target of follow-up RPC calls, with no way to dereference it.
+- **Separated stdout / stderr capture** — guest `puts` / `warn` / `print` / `printf` / `p` and writes to `$stdout` / `$stderr` are buffered per-channel (1 MiB default cap, configurable). Output past the cap is clipped; `#stdout_truncated?` / `#stderr_truncated?` report overflow.
+- **Capability Handles** — Services may return stateful host objects; the guest receives an opaque `Kobako::RPC::Handle` proxy it can use as the target of follow-up RPC calls, with no way to dereference it.
+- **Curated mruby stdlib** — core extensions plus `mruby-onig-regexp` for full Onigmo `Regexp` support. No mrbgem with I/O, network, or syscall access is bundled.
 
 ## Requirements
 
@@ -24,15 +40,9 @@ The precompiled `kobako.wasm` Guest Binary ships inside the gem, so end users do
 
 ## Installation
 
-Add Kobako to your Gemfile:
-
 ```bash
 bundle add kobako
-```
-
-Or install it directly:
-
-```bash
+# or
 gem install kobako
 ```
 
@@ -55,7 +65,7 @@ The script executes inside the Wasm guest. It cannot read your filesystem, open
 
 ## Injecting Services
 
-Guest scripts reach host resources only through Services. Declare a **Group**, then `bind` named **Members** on it — each member can be any Ruby object that responds to the methods the guest will call.
+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
@@ -70,7 +80,7 @@ RUBY
 # => "..." (the redis value)
 ```
 
-Names must match the Ruby constant pattern `/\A[A-Z]\w*\z/`. Services declared before the first `#run` remain active across subsequent runs.
+Names must match the Ruby constant pattern `/\A[A-Z]\w*\z/`. Services declared before the first `#run` remain active across subsequent runs; `define` after the first `#run` raises `ArgumentError`.
 
 ### Keyword arguments
 
@@ -83,9 +93,31 @@ sandbox.run('Geo::Lookup.call(name: "alice", region: "us")')
 # => "us/alice"
 ```
 
+## Per-run caps
+
+Each Sandbox enforces a wall-clock timeout and a guest linear-memory cap on every `#run`. Both default to safe values; pass `nil` to `timeout` or `memory_limit` to disable that cap. The output caps (`stdout_limit` / `stderr_limit`) cannot be disabled — pass a large Integer instead.
+
+```ruby
+sandbox = Kobako::Sandbox.new(
+  timeout:      5.0,           # seconds, default 60.0
+  memory_limit: 10 * 1024 * 1024, # bytes, default 5 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`         | 5 MiB    |
+| `stdout_limit` | output silently clipped at cap     | 1 MiB    |
+| `stderr_limit` | output silently clipped at cap     | 1 MiB    |
+
+The timeout deadline is absolute wall-clock from `#run` entry and is checked at guest Wasm safepoints. Long-running host Service callbacks still consume wall-clock time but do not themselves trap — the next guest safepoint will trap immediately on return if the deadline has passed.
+
 ## Capturing stdout and stderr
 
-Guest output is captured into per-run buffers and exposed independently from the return value:
+Guest output is captured into per-run buffers and exposed independently from the return value. The buffers cover the full Ruby IO surface — `puts`, `print`, `printf`, `p`, `<<`, and writes through `$stdout` / `$stderr` — all routed through the host-captured WASI pipe.
 
 ```ruby
 sandbox = Kobako::Sandbox.new
@@ -101,10 +133,13 @@ sandbox.stdout  # => "hello\n"
 sandbox.stderr  # => "be careful\n"
 ```
 
-Each `#run` clears the buffers at start. Output past the per-channel cap is truncated; the buffer ends with `[truncated]` and `#run` still returns normally.
+Each `#run` clears the buffers at start. Output past the per-channel cap is clipped at the cap boundary — `#run` still returns normally, the bytes carry no truncation sentinel, and `#stdout_truncated?` / `#stderr_truncated?` flip to `true`.
 
 ```ruby
-Kobako::Sandbox.new(stdout_limit: 64 * 1024, stderr_limit: 64 * 1024)
+sandbox = Kobako::Sandbox.new(stdout_limit: 64 * 1024)
+sandbox.run('puts "a" * 100_000')
+sandbox.stdout.bytesize     # => 65_536
+sandbox.stdout_truncated?   # => true
 ```
 
 ## Error handling
@@ -115,7 +150,10 @@ Every `#run` either returns a value or raises exactly one of three classes:
 begin
   sandbox.run(script)
 rescue Kobako::TrapError => e
-  # Wasm engine crashed: OOM, stack overflow, corrupted guest runtime.
+  # Wasm engine fault OR per-run 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.
@@ -126,13 +164,15 @@ rescue Kobako::SandboxError => e
 end
 ```
 
-`SandboxError` and `ServiceError` carry structured fields (`origin`, `klass`, `backtrace_lines`, `details`) when the guest produced a panic envelope.
+`SandboxError` and `ServiceError` carry structured fields (`origin`, `klass`, `backtrace_lines`, `details`) when the guest produced a panic envelope. Named subclasses:
 
-`Kobako::ServiceError::Disconnected` is a named subclass raised when an RPC target Handle has been invalidated. `Kobako::HandleTableExhausted` is a named `SandboxError` subclass raised when the per-run Handle counter reaches its cap (2³¹ − 1).
+- `Kobako::TimeoutError` / `Kobako::MemoryLimitError` — per-run cap exhaustion (subclasses of `TrapError`).
+- `Kobako::ServiceError::Disconnected` — RPC target Handle has been invalidated.
+- `Kobako::HandleTableExhausted` — per-run Handle counter reached its cap (2³¹ − 1); subclass of `SandboxError`.
 
 ## 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.
+When a Service returns a stateful host object (anything beyond `nil` / Boolean / Integer / Float / String / Symbol / Array / Hash), the wire layer transparently allocates an opaque Handle. The guest receives a `Kobako::RPC::Handle` proxy it can use as the target of further RPC calls — but cannot dereference, forge from an integer, or smuggle across runs.
 
 ```ruby
 class Greeter
@@ -143,7 +183,7 @@ end
 sandbox.define(:Factory).bind(:Make, ->(name) { Greeter.new(name) })
 
 sandbox.run(<<~RUBY)
-  g = Factory::Make.call("Bob")  # g is a Kobako::Handle proxy
+  g = Factory::Make.call("Bob")  # g is a Kobako::RPC::Handle proxy
   g.greet                         # second RPC, routed to the Greeter
 RUBY
 # => "hi, Bob"
@@ -165,60 +205,55 @@ sandbox.run('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.
 
-## Development
+## Performance
 
-After checking out the repo:
+Headline numbers from the current baseline (macOS arm64, Ruby 3.4.7, YJIT off — full results in [`benchmark/results/`](benchmark/results) and [`benchmark/README.md`](benchmark/README.md)).
 
-```bash
-bin/setup                  # install dependencies
-bundle exec rake           # default: compile + test + rubocop
-```
-
-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:
+| What | Cost |
+|---|---|
+| First `Sandbox.new` in a fresh process (Engine init + Module JIT) | ~2.0 s one-time |
+| Subsequent `Sandbox.new` (cache warm) | ~130 µs |
+| Reusing a Sandbox for one `#run("nil")` | ~135 µs |
+| Fresh Sandbox per request — the tenant-isolation pattern | ~275 µs (+140 µs vs reuse) |
+| Per-RPC cost amortized across 1 000 calls in one `#run` | ~35 µs |
+| 100 000-iteration integer XOR loop in mruby | ~200 ms |
+| 1 000 Onigmo `Regexp =~` matches | ~14 µs per match |
+| Process RSS after the first `Sandbox.new` | ~150 MB (one-time) |
+| Memory per additional Sandbox | ~575 KB |
+| 1 000 isolated tenants in one process | ~730 MB total |
+| Aggregate throughput across N Threads | GVL-bound — wasm execution serialized, modest scaling from Ruby-side overlap |
 
-```bash
-bundle exec rake compile   # build the native extension
-bundle exec rake wasm:build # rebuild data/kobako.wasm (requires vendor:setup + mruby:build)
-bundle exec rake test      # run the Ruby test suite
-```
+Practical implications:
 
-`bin/console` opens an IRB session with the gem preloaded for experimentation.
+- **Pre-warm at boot.** The ~2 s first-Sandbox cost is paid once per process; every subsequent Sandbox amortizes to micro-, not seconds. Construct one Sandbox at boot before serving requests.
+- **Tenant isolation is affordable.** Per-request Sandbox construction adds ~140 µs of overhead; per-tenant RSS budget is ~575 KB plus one-time ~130 MB for the engine. 1 000 isolated tenants in a single Sidekiq / Puma worker is well within typical RSS limits.
+- **Batch RPCs inside one `#run`.** A single Service call costs ~135 µs because each `#run` carries ~130 µs of setup; 1 000 calls inside one `#run` reduce the per-call cost to ~35 µs.
 
-To install the local checkout as a gem:
+A +10% regression on any of the five SPEC-mandated benchmarks blocks release. See [`benchmark/README.md`](benchmark/README.md) for the full per-suite breakdown and known measurement caveats.
 
 ```bash
-bundle exec rake install
+bundle exec rake bench   # five gated regression benchmarks (≤ 1 MiB payloads, ~5-8 min)
 ```
 
-## Performance
-
-Headline numbers from the current baseline (macOS arm64, Ruby 3.4.7 — full results in [`benchmark/results/`](benchmark/results)):
-
-| What | Cost |
-|---|---|
-| First `Sandbox.new` in a fresh process (Engine init + Module compile) | ~410 ms one-time |
-| Subsequent `Sandbox.new` (cache warm) | ~90 µs |
-| Reusing a Sandbox for one `#run("nil")` | ~67 µs |
-| Fresh Sandbox per request — the tenant-isolation pattern | ~175 µs (+110 µs versus reuse) |
-| Per-RPC cost amortized across many calls in one `#run` | ~5.4 µs |
-| 100 000-iteration integer XOR loop in mruby | ~44 ms |
-| One-time process memory for wasmtime Engine + Module | ~110 MB |
-| Memory per additional Sandbox after the first | ~200 KB |
-| 1 000 isolated tenants in one process (1 Sandbox each) | ~340 MB total |
-| Aggregate throughput across N Threads | GVL-bound — wasm execution is serialized, modest scaling from Ruby-side overlap |
+## Development
 
-Practical implications:
+After checking out the repo:
 
-- **Pre-warm at boot.** The 410 ms first-Sandbox cost is paid once per process; every subsequent Sandbox amortizes to micro-, not milliseconds. Construct one Sandbox at boot before serving requests.
-- **Tenant isolation is affordable.** Per-request Sandbox construction adds ~110 µs of overhead; per-tenant RSS budget is ~200 KB plus one-time ~110 MB for the engine. 1 000 isolated tenants in a single Sidekiq / Puma worker is well within typical RSS limits.
-- **Batch RPCs inside one `#run`.** A single Service call costs ~76 µs because each `#run` carries ~67 µs of setup; 1 000 calls inside one `#run` reduce the per-call cost to ~5.4 µs.
+```bash
+bin/setup                  # install dependencies
+bundle exec rake           # default: compile + test + rubocop + steep
+```
 
-A +10% regression on any of the five SPEC-mandated benchmarks blocks release. See [`benchmark/README.md`](benchmark/README.md) for the full per-suite breakdown, rake task reference, and known measurement caveats (guest String size cap, GVL bounds, allocator retention).
+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 bench   # five gated regression benchmarks (≤ 1 MiB payloads, ~5-7 min)
+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.

data/ext/kobako/Cargo.toml

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

data/ext/kobako/src/wasm/cache.rs

@@ -22,6 +22,8 @@ use std::collections::HashMap;
 use std::fs;
 use std::path::{Path, PathBuf};
 use std::sync::{Mutex, OnceLock};
+use std::thread;
+use std::time::Duration;
 
 use magnus::{Error as MagnusError, Ruby};
 use wasmtime::{Config as WtConfig, Engine as WtEngine, Module as WtModule};
@@ -31,6 +33,15 @@ use super::{wasm_err, MODULE_NOT_BUILT_ERROR};
 static SHARED_ENGINE: OnceLock<WtEngine> = OnceLock::new();
 static MODULE_CACHE: OnceLock<Mutex<HashMap<PathBuf, WtModule>>> = OnceLock::new();
 
+/// Ticker cadence for the process-singleton epoch ticker. Bounds the
+/// granularity of the SPEC.md B-01 wall-clock timeout: the
+/// `epoch_deadline_callback` fires once per tick (`Continue(1)`), so the
+/// trap can lag the deadline by at most one tick under nominal
+/// scheduling. 10 ms keeps the lag small enough that it does not skew
+/// short test timeouts while leaving the ticker cheap (one wake-up per
+/// 10 ms across the whole process).
+const EPOCH_TICK: Duration = Duration::from_millis(10);
+
 /// Return the process-wide wasmtime Engine, building it on first call.
 ///
 /// Enables the wasm exceptions proposal so `kobako.wasm` (which uses
@@ -40,17 +51,44 @@ static MODULE_CACHE: OnceLock<Mutex<HashMap<PathBuf, WtModule>>> = OnceLock::new
 /// exception handling instructions in the wasm32 object files;
 /// wasmtime must have the proposal enabled to parse and JIT those
 /// instructions.
+///
+/// Also enables `epoch_interruption(true)` so every Store can install an
+/// `epoch_deadline_callback` for the per-run wall-clock cap (SPEC.md
+/// B-01, E-19). The first call spawns the process-singleton ticker
+/// thread that drives `engine.increment_epoch()` at [`EPOCH_TICK`]
+/// cadence; subsequent calls reuse the same engine and ticker.
 pub(crate) fn shared_engine() -> Result<&'static WtEngine, MagnusError> {
     if let Some(engine) = SHARED_ENGINE.get() {
         return Ok(engine);
     }
     let mut config = WtConfig::new();
     config.wasm_exceptions(true);
+    config.epoch_interruption(true);
     let engine = WtEngine::new(&config).map_err(|e| {
         let ruby = Ruby::get().expect("Ruby thread");
         wasm_err(&ruby, format!("engine init: {}", e))
     })?;
-    Ok(SHARED_ENGINE.get_or_init(|| engine))
+    let engine = SHARED_ENGINE.get_or_init(|| engine);
+    spawn_epoch_ticker(engine.clone());
+    Ok(engine)
+}
+
+/// Spawn the process-singleton epoch ticker. The thread holds a clone of
+/// the shared Engine (`wasmtime::Engine` is reference-counted internally)
+/// and ticks the epoch counter at [`EPOCH_TICK`] cadence. Idempotent
+/// across reentrant calls to [`shared_engine`] because [`OnceLock`]
+/// gates the spawn.
+fn spawn_epoch_ticker(engine: WtEngine) {
+    static TICKER_SPAWNED: OnceLock<()> = OnceLock::new();
+    TICKER_SPAWNED.get_or_init(|| {
+        thread::Builder::new()
+            .name("kobako-epoch-ticker".into())
+            .spawn(move || loop {
+                thread::sleep(EPOCH_TICK);
+                engine.increment_epoch();
+            })
+            .expect("spawn kobako-epoch-ticker thread");
+    });
 }
 
 /// Look up `path` in the per-path Module cache, compiling and inserting

data/ext/kobako/src/wasm/dispatch.rs

@@ -1,12 +1,12 @@
-//! Host-side dispatch for the `__kobako_rpc_call` import.
+//! Host-side dispatch for the `__kobako_dispatch` import.
 //!
 //! When the guest invokes the wasm import declared in
 //! `wasm/kobako-wasm/src/abi.rs`, wasmtime calls back into the host
-//! through the closure built in [`super::instance::build_instance`].
+//! through the closure built in [`super::instance::Instance::build`].
 //! That closure delegates here. The dispatcher (SPEC.md B-12 / B-13):
 //!
 //!   1. Reads the Request bytes from guest linear memory.
-//!   2. Hands them to the Ruby-side `Kobako::Registry` and recovers
+//!   2. Hands them to the Ruby-side `Kobako::RPC::Server` and recovers
 //!      Response bytes.
 //!   3. Allocates a guest buffer via `__kobako_alloc(len)` invoked
 //!      through `Caller::get_export`.
@@ -14,10 +14,10 @@
 //!   5. Returns packed `(ptr<<32)|len` for the guest to decode.
 //!
 //! Returns 0 on any step failure. `Kobako::Sandbox` always installs a
-//! Registry before invoking the guest, so reaching the dispatcher with
-//! no Registry bound is itself a wire-layer fault; the guest maps a 0
+//! Server before invoking the guest, so reaching the dispatcher with
+//! no Server bound is itself a wire-layer fault; the guest maps a 0
 //! return to a trap. Failures during normal dispatch surface as
-//! Response.err envelopes from the Registry itself — they never reach
+//! Response.err envelopes from the Server itself — they never reach
 //! this 0-return path.
 
 use magnus::value::{Opaque, ReprValue};
@@ -26,24 +26,24 @@ use wasmtime::{Caller, Extern};
 
 use super::host_state::HostState;
 
-/// Drive a single `__kobako_rpc_call` invocation end-to-end. Entry point
-/// from the wasmtime closure built in [`super::instance::build_instance`].
-pub(crate) fn dispatch_rpc(caller: &mut Caller<'_, HostState>, req_ptr: i32, req_len: i32) -> i64 {
+/// Drive a single `__kobako_dispatch` invocation end-to-end. Entry point
+/// from the wasmtime closure built in [`super::instance::Instance::build`].
+pub(crate) fn handle(caller: &mut Caller<'_, HostState>, req_ptr: i32, req_len: i32) -> i64 {
     let req_bytes = match read_caller_memory(caller, req_ptr, req_len) {
         Some(b) => b,
         None => return 0,
     };
 
-    // No Registry bound — return 0 to signal a wire-layer fault; the guest
+    // No Server bound — return 0 to signal a wire-layer fault; the guest
     // maps a 0 return to a trap. `Kobako::Sandbox` always installs a
-    // Registry before invoking the guest, so reaching this branch indicates
+    // Server before invoking the guest, so reaching this branch indicates
     // a misuse rather than a normal control path.
-    let registry = match caller.data().registry {
+    let server = match caller.data().server() {
         Some(d) => d,
         None => return 0,
     };
 
-    let resp_bytes = match invoke_registry(registry, &req_bytes) {
+    let resp_bytes = match invoke_server(server, &req_bytes) {
         Ok(b) => b,
         Err(_) => return 0,
     };
@@ -51,20 +51,20 @@ pub(crate) fn dispatch_rpc(caller: &mut Caller<'_, HostState>, req_ptr: i32, req
     write_response(caller, &resp_bytes).unwrap_or(0)
 }
 
-/// Call the Ruby Registry's `#dispatch(request_bytes)` method and return
-/// the encoded Response bytes. Errors here mean the Registry itself
+/// Call the Ruby Server's `#dispatch(request_bytes)` method and return
+/// the encoded Response bytes. Errors here mean the Server itself
 /// failed (it is contracted never to raise — see
-/// `Kobako::Registry#dispatch`), which we treat as a wire-layer fault.
-fn invoke_registry(registry: Opaque<Value>, req_bytes: &[u8]) -> Result<Vec<u8>, MagnusError> {
+/// `Kobako::RPC::Server#dispatch`), which we treat as a wire-layer fault.
+fn invoke_server(server: Opaque<Value>, req_bytes: &[u8]) -> Result<Vec<u8>, MagnusError> {
     // The wasmtime callback runs on the same Ruby thread that called
     // Sandbox#run — the invariant SPEC Implementation Standards
     // Architecture pins for the host gem — so `Ruby::get()` is always
     // available here. Panicking with `expect` localises the violation
     // rather than letting a nonsense error propagate.
-    let ruby = Ruby::get().expect("Ruby handle unavailable in __kobako_rpc_call");
-    let registry_value: Value = ruby.get_inner(registry);
+    let ruby = Ruby::get().expect("Ruby handle unavailable in __kobako_dispatch");
+    let server_value: Value = ruby.get_inner(server);
     let req_str = ruby.str_from_slice(req_bytes);
-    let resp: RString = registry_value.funcall("dispatch", (req_str,))?;
+    let resp: RString = server_value.funcall("dispatch", (req_str,))?;
     // SAFETY: the returned RString is held by the Ruby VM for the duration of
     // this scope; copying its bytes into a Vec is a defensive standard pattern.
     let bytes = unsafe { resp.as_slice() }.to_vec();