kobako 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bb91cd11e954d6388b7d6c19be8b9fc77548fa1ea9d57b75f1afc7c0d450a36b
-  data.tar.gz: f84463e4b30e2ae5cb1e7d09a7c55345a419afd442613a1eb6b080682263587f
+  metadata.gz: fd04d7b8efaf9ccb41ff873a66b0855839222c5bc034d80a854b9fbc25602570
+  data.tar.gz: 718665fbcfb89faafc86f018a247e37ea304c3c8559e4febc240ad95bdc15654
 SHA512:
-  metadata.gz: d622978cf22e2b30dbf8674275bbaaf39d0de68962709b40b67194d0521ca3d1e991e9a4e59853e634c111fc852d4719864c2990f2baaf35e1395efa3f67b63a
-  data.tar.gz: 3f828b5374841d0bcb8136a7c1aa078668c05c3673c794c50f86de9b1aee0bd915d090e022061b3e9636abb2dfb85a0b3bf1a7bbacff968635d9ed01c5f21edd
+  metadata.gz: e9cd6493f200abbb9a9014e9222633fec67e8813a854b93e71a29d94a3738ff64dfe33f5b136efe472d87831fb78062a09ac481d1da6970782e965a7a7aeafc8
+  data.tar.gz: 7f11f9fb3e48efc808eebd0598bc19569c6c1fd90322cee2f65f9030d8ca39a3da6cbe9fa68edb33480e926aabcb3766c2dc8c37995945ceaebd7b9952d9ec0f

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/Cargo.lock

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

data/README.md

@@ -191,7 +191,6 @@ end
 |----------------------------------------|--------------------|------------------------------------------------------------------------------------------|
 | `Kobako::TimeoutError`                 | `TrapError`        | Per-invocation `timeout` exhausted                                                       |
 | `Kobako::MemoryLimitError`             | `TrapError`        | Per-invocation `memory_limit` exhausted                                                  |
-| `Kobako::ServiceError::Disconnected`   | `ServiceError`     | RPC target Handle has been invalidated                                                   |
 | `Kobako::HandleTableExhausted`         | `SandboxError`     | Per-invocation Handle counter reached its 2³¹ − 1 cap                                    |
 | `Kobako::BytecodeError`                | `SandboxError`     | `#preload(binary:)` payload failed RITE structural validation at first invocation replay |
 

data/ext/kobako/Cargo.toml

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

data/ext/kobako/src/lib.rs

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

data/ext/kobako/src/{wasm → runtime}/cache.rs

@@ -1,22 +1,18 @@
-//! Process-wide caches for the wasmtime [`Engine`] and compiled
-//! [`Module`].
+//! Process-wide caches for the wasmtime `Engine` and compiled
+//! `Module`.
 //!
 //! SPEC.md "Code Organization" pins `ext/` as private and forbids
 //! exposing wasm engine types to the Host App or downstream gems. To
 //! amortise Engine creation and Module JIT compilation across multiple
 //! `Kobako::Sandbox` constructions, the ext keeps a process-scope
 //! shared Engine and a per-path Module cache. Both are transparent to
-//! Ruby callers, who construct an `Instance` via
-//! `Kobako::Wasm::Instance.from_path(...)` and never see Engine or
-//! Module.
+//! Ruby callers, who construct a `Runtime` via
+//! `Kobako::Runtime.from_path(...)` and never see Engine or Module.
 //!
 //! Concurrency: under Ruby's GVL only one thread can execute Rust code
 //! at a time, so the Mutex is held briefly during HashMap insert/lookup
 //! and serves to satisfy `Sync` bounds rather than to arbitrate real
 //! contention.
-//!
-//! [`Engine`]: wasmtime::Engine
-//! [`Module`]: wasmtime::Module
 
 use std::collections::HashMap;
 use std::fs;
@@ -28,7 +24,7 @@ use std::time::Duration;
 use magnus::{Error as MagnusError, Ruby};
 use wasmtime::{Config as WtConfig, Engine as WtEngine, Module as WtModule};
 
-use super::{wasm_err, MODULE_NOT_BUILT_ERROR};
+use super::{setup_err, MODULE_NOT_BUILT_ERROR};
 
 static SHARED_ENGINE: OnceLock<WtEngine> = OnceLock::new();
 static MODULE_CACHE: OnceLock<Mutex<HashMap<PathBuf, WtModule>>> = OnceLock::new();
@@ -55,7 +51,7 @@ const EPOCH_TICK: Duration = Duration::from_millis(10);
 /// Also enables `epoch_interruption(true)` so every Store can install an
 /// `epoch_deadline_callback` for the per-run wall-clock cap
 /// (docs/behavior.md B-01, E-19). The first call spawns the process-singleton ticker
-/// thread that drives `engine.increment_epoch()` at [`EPOCH_TICK`]
+/// 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() {
@@ -66,7 +62,7 @@ pub(crate) fn shared_engine() -> Result<&'static WtEngine, MagnusError> {
     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))
+        setup_err(&ruby, format!("engine init: {}", e))
     })?;
     let engine = SHARED_ENGINE.get_or_init(|| engine);
     spawn_epoch_ticker(engine.clone());
@@ -75,8 +71,8 @@ pub(crate) fn shared_engine() -> Result<&'static WtEngine, MagnusError> {
 
 /// 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`]
+/// 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();
@@ -92,7 +88,7 @@ fn spawn_epoch_ticker(engine: WtEngine) {
 }
 
 /// Look up `path` in the per-path Module cache, compiling and inserting
-/// the artifact on a miss. Raises `Kobako::Wasm::ModuleNotBuiltError`
+/// the artifact on a miss. Raises `Kobako::ModuleNotBuiltError`
 /// when the file is missing — the headline error for the common
 /// pre-build state on a fresh clone before `rake compile`.
 pub(crate) fn cached_module(path: &Path) -> Result<WtModule, MagnusError> {
@@ -119,7 +115,7 @@ pub(crate) fn cached_module(path: &Path) -> Result<WtModule, MagnusError> {
     }
 
     let bytes = fs::read(path).map_err(|e| {
-        wasm_err(
+        setup_err(
             &ruby,
             format!(
                 "failed to read Sandbox runtime at {}: {}",
@@ -129,7 +125,7 @@ pub(crate) fn cached_module(path: &Path) -> Result<WtModule, MagnusError> {
         )
     })?;
     let module = WtModule::new(shared_engine()?, &bytes)
-        .map_err(|e| wasm_err(&ruby, format!("failed to compile Sandbox runtime: {}", e)))?;
+        .map_err(|e| setup_err(&ruby, format!("failed to compile Sandbox runtime: {}", e)))?;
     cache
         .lock()
         .expect("module cache mutex poisoned")

data/ext/kobako/src/runtime/capture.rs

@@ -0,0 +1,91 @@
+//! Per-channel stdout / stderr capture sizing and clipping.
+//!
+//! Two pure helpers shared by the run path (docs/behavior.md B-04): one
+//! sizes the per-run `MemoryOutputPipe`, the other clips a captured
+//! snapshot back to the configured cap and reports whether the cap was
+//! exceeded. Kept channel-agnostic (a function of `cap`, not of which
+//! channel) so a regression that only breaks one channel cannot sneak
+//! through the test that pins them.
+
+/// Translate a per-channel byte cap into the MemoryOutputPipe capacity:
+/// `cap + 1` (saturated against `usize::MAX`) when a cap is set so the
+/// "wrote exactly cap" and "exceeded cap" cases stay distinguishable;
+/// `usize::MAX` when the channel is uncapped.
+pub(super) fn pipe_capacity(cap: Option<usize>) -> usize {
+    match cap {
+        Some(c) => c.saturating_add(1),
+        None => usize::MAX,
+    }
+}
+
+/// Pure slicing core shared by the snapshot readback: given the unclipped
+/// pipe snapshot and the configured cap, return the bytes Ruby should
+/// observe (clipped to `cap`) plus the truncation flag. `truncated` is
+/// `true` only when the snapshot strictly exceeded the cap — this is the
+/// "wrote `cap + 1` bytes into a `cap + 1`-sized pipe" case; "wrote
+/// exactly `cap` bytes" stays `false`.
+pub(super) fn clip_capture(raw: &[u8], cap: Option<usize>) -> (&[u8], bool) {
+    match cap {
+        Some(c) if raw.len() > c => (&raw[..c], true),
+        _ => (raw, false),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{clip_capture, pipe_capacity};
+
+    #[test]
+    fn pipe_capacity_adds_one_when_cap_is_set() {
+        assert_eq!(pipe_capacity(Some(5)), 6);
+        assert_eq!(pipe_capacity(Some(0)), 1);
+    }
+
+    #[test]
+    fn pipe_capacity_falls_back_to_usize_max_when_uncapped() {
+        assert_eq!(pipe_capacity(None), usize::MAX);
+    }
+
+    #[test]
+    fn pipe_capacity_saturates_at_usize_max() {
+        assert_eq!(pipe_capacity(Some(usize::MAX)), usize::MAX);
+    }
+
+    #[test]
+    fn clip_capture_returns_full_bytes_when_under_cap() {
+        let (bytes, truncated) = clip_capture(b"abc", Some(5));
+        assert_eq!(bytes, b"abc");
+        assert!(!truncated);
+    }
+
+    #[test]
+    fn clip_capture_does_not_flag_truncation_at_exactly_cap_bytes() {
+        let (bytes, truncated) = clip_capture(b"abcde", Some(5));
+        assert_eq!(bytes, b"abcde");
+        assert!(!truncated);
+    }
+
+    #[test]
+    fn clip_capture_clips_to_cap_and_flags_truncation_on_overflow() {
+        // The pipe is sized `cap + 1`, so the snapshot can be at most
+        // 6 bytes when `cap == 5`; that surface is what triggers the
+        // truncation flag.
+        let (bytes, truncated) = clip_capture(b"abcdef", Some(5));
+        assert_eq!(bytes, b"abcde");
+        assert!(truncated);
+    }
+
+    #[test]
+    fn clip_capture_treats_none_as_uncapped() {
+        let (bytes, truncated) = clip_capture(b"abcdef", None);
+        assert_eq!(bytes, b"abcdef");
+        assert!(!truncated);
+    }
+
+    #[test]
+    fn clip_capture_handles_empty_input() {
+        let (bytes, truncated) = clip_capture(b"", Some(5));
+        assert_eq!(bytes, b"");
+        assert!(!truncated);
+    }
+}

data/ext/kobako/src/runtime/config.rs

@@ -0,0 +1,26 @@
+//! Per-`Runtime` execution configuration.
+//!
+//! The wall-clock and per-channel capture caps a `Kobako::Sandbox`
+//! forwards into `Runtime::from_path`. A plain value carrier owned by the
+//! `Runtime` — distinct from the process-wide engine/module `super::cache`
+//! (which is shared across every Sandbox) and from the per-invocation
+//! `super::invocation::Invocation` (which the wasm engine mutates from
+//! inside a run). These caps are read only by `Runtime` methods between
+//! runs, so they live here.
+
+use std::time::Duration;
+
+/// Wall-clock and output caps for one `Runtime`. `None` on any field
+/// disables that cap.
+pub(crate) struct Config {
+    /// Wall-clock cap for one guest `#eval` / `#run` (docs/behavior.md
+    /// B-01, E-19). Stamped into a per-run `Instant` deadline by
+    /// `Runtime::prime_caps`.
+    pub(crate) timeout: Option<Duration>,
+    /// Byte cap for guest stdout capture (docs/behavior.md B-01 / B-04).
+    /// Sizes the per-run `MemoryOutputPipe` and computes the truncation
+    /// flag in `Runtime::build_snapshot`.
+    pub(crate) stdout_limit_bytes: Option<usize>,
+    /// Byte cap for guest stderr capture. Mirror of `stdout_limit_bytes`.
+    pub(crate) stderr_limit_bytes: Option<usize>,
+}

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

@@ -0,0 +1,211 @@
+//! 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::Runtime::build`.
+//! That closure delegates here. The dispatcher (docs/behavior.md B-12 / B-13):
+//!
+//!   1. Reads the Request bytes from guest linear memory.
+//!   2. Invokes the Ruby-side dispatch Proc bound via
+//!      `Runtime#on_dispatch=` and recovers Response bytes.
+//!   3. Allocates a guest buffer via `__kobako_alloc(len)` invoked
+//!      through `Caller::get_export`.
+//!   4. Writes the Response bytes into the guest buffer.
+//!   5. Returns packed `(ptr<<32)|len` for the guest to decode.
+//!
+//! Returns 0 on any step failure. `Kobako::Sandbox#initialize` always
+//! installs the dispatch Proc before any invocation, so reaching the
+//! dispatcher with no Proc 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
+//! `Kobako::Transport::Dispatcher.dispatch` itself — they never reach
+//! this 0-return path.
+//!
+//! ## Why this module writes to `stderr`
+//!
+//! This file is the one place in `ext/` that deliberately prints
+//! through `eprintln!`. The host normally surfaces faults by
+//! raising a `MagnusError` back into Ruby; the dispatcher contract
+//! is the exception — it must return a packed `i64` to the guest
+//! and cannot raise, so a 0 return is the only signal the wasm side
+//! receives. The guest collapses every 0 into the same trap, so the
+//! Ruby host has no way to attribute the failure to a specific step
+//! (missing `memory` export vs. no dispatch Proc bound vs. the Proc
+//! raised vs. `__kobako_alloc` returned 0 vs. `memory.write`
+//! rejected).
+//!
+//! `handle` writes a single `[kobako-dispatch] <reason>` line to
+//! `stderr` on each failure path so operators have a breadcrumb to
+//! correlate the trap with the actual cause. The line is emitted in
+//! both debug and release builds on purpose: dispatcher failures are
+//! wire-layer faults rather than expected error paths (`Kobako::Sandbox`
+//! always installs the Proc, the Proc is contracted never to raise,
+//! etc.), so the "release-build noise" cost is bounded — under normal
+//! operation the line is never written. Operators that need to silence
+//! the stream can redirect the host process's stderr, but the kobako
+//! convention is "ext never logs" plus this single, named exception.
+
+use core::cell::Cell;
+use core::ptr::NonNull;
+
+use magnus::value::{Opaque, ReprValue};
+use magnus::{Error as MagnusError, RString, Ruby, Value};
+use wasmtime::Caller;
+
+use super::invocation::Invocation;
+
+// ============================================================
+// Active-caller pointer for the per-thread Invocation slot (B-24, B-28,
+// SPEC.md Single-Invocation Slot).
+// ============================================================
+//
+// `Runtime#yield_to_active_invocation` (whose body is the
+// `__kobako_yield_to_block` guest export) runs synchronously inside a
+// Ruby Service callback that itself was invoked from inside this
+// dispatcher — at that moment we are several stack frames deep in
+// `try_handle`, with the original `&mut Caller<'_, Invocation>` parked
+// unused on the Rust stack while Ruby code is running. The yield path
+// needs the same Caller to call the guest export, but the Rust borrow
+// type is non-`'static` so it cannot be stored on the `Invocation`
+// struct directly (the `&mut Caller` outlives no struct field — its
+// lifetime ends when `handle` returns to wasmtime).
+//
+// The pointer is therefore erased to `NonNull<()>` and parked in a
+// per-thread slot — the materialised form of the SPEC.md
+// "Single-Invocation Slot" invariant. The single-threaded wasm
+// execution per Sandbox (B-22) plus the LIFO re-entry shape of nested
+// dispatch frames (B-28) ensures no aliasing across threads or across
+// frames; the recovery invariant lives at `current_caller`. The
+// pointer is set on entry to `handle` and restored to the outer
+// frame's value on every exit through a drop guard.
+
+thread_local! {
+    static ACTIVE_CALLER: Cell<Option<NonNull<()>>> = const { Cell::new(None) };
+}
+
+/// RAII guard that saves the previous `ACTIVE_CALLER` value on
+/// installation and restores it on drop. Nested `__kobako_dispatch`
+/// frames stack within one Invocation (B-28) — the inner frame's `set`
+/// swaps in its own pointer while remembering the outer's; drop
+/// restores the outer so its continuation (e.g. iterating over another
+/// guest block) still finds a live caller.
+pub(crate) struct CallerGuard {
+    previous: Option<NonNull<()>>,
+}
+
+impl CallerGuard {
+    fn set(ptr: NonNull<()>) -> Self {
+        let previous = ACTIVE_CALLER.with(|c| c.replace(Some(ptr)));
+        Self { previous }
+    }
+}
+
+impl Drop for CallerGuard {
+    fn drop(&mut self) {
+        ACTIVE_CALLER.with(|c| c.set(self.previous));
+    }
+}
+
+/// Recover the active `&mut Caller<'_, Invocation>` set by the
+/// enclosing `handle` frame. Returns `None` when no dispatch frame is
+/// active on this thread.
+///
+/// # Safety
+///
+/// The returned reference aliases the original `&mut Caller` borrow
+/// held on the Rust stack inside `handle`'s enclosing frame. The
+/// original borrow is logically inactive while Ruby code is running
+/// (it is parked on the stack between `invoke_on_dispatch` and the
+/// eventual `funcall` return), and the SPEC.md Single-Invocation Slot
+/// invariant (one Invocation per OS thread for the duration of any
+/// invocation) guarantees no other Rust frame can observe it. Callers
+/// must not retain the returned `&mut` past the synchronous Ruby
+/// callback that requested it — i.e. only use it inside one short
+/// magnus method body and let the borrow end before the method returns.
+pub(crate) fn current_caller<'a>() -> Option<&'a mut Caller<'a, Invocation>> {
+    let raw: NonNull<()> = ACTIVE_CALLER.with(|c| c.get())?;
+    // SAFETY: see item doc.
+    Some(unsafe { &mut *raw.as_ptr().cast::<Caller<'a, Invocation>>() })
+}
+
+/// Drive a single `__kobako_dispatch` invocation end-to-end. Entry point
+/// from the wasmtime closure built in `super::Runtime::build`.
+///
+/// Returns the packed `(ptr<<32)|len` u64 on success, 0 on any
+/// wire-layer fault. Failure paths log a `[kobako-dispatch]` line to
+/// `stderr` so operators have a breadcrumb when the guest sees a 0
+/// return and traps. The bound dispatch Proc is contracted never to
+/// raise (it folds Service exceptions into Response.err envelopes),
+/// so reaching the failure path is always a wiring bug or wire-layer
+/// fault rather than an expected path.
+pub(crate) fn handle(caller: &mut Caller<'_, Invocation>, req_ptr: i32, req_len: i32) -> i64 {
+    // SAFETY: lifetime erased to `NonNull<()>` per the module's
+    // Invocation-slot doc. The pointer is restored by `_caller_guard`
+    // before this function returns, and only
+    // `Runtime#yield_to_active_invocation` (running inside a Ruby
+    // callback we are about to invoke) reads it through `current_caller`.
+    let ptr: NonNull<()> = NonNull::from(&mut *caller).cast();
+    let _caller_guard = CallerGuard::set(ptr);
+
+    match try_handle(caller, req_ptr, req_len) {
+        Ok(packed) => packed,
+        Err(reason) => {
+            eprintln!("[kobako-dispatch] {}", reason);
+            0
+        }
+    }
+}
+
+/// Result-returning core of `handle`. Pulled out so each early
+/// failure path carries a diagnostic string instead of an opaque 0.
+fn try_handle(
+    caller: &mut Caller<'_, Invocation>,
+    req_ptr: i32,
+    req_len: i32,
+) -> Result<i64, &'static str> {
+    let req_bytes = super::guest_mem::read(caller, req_ptr, req_len)?;
+
+    // `Kobako::Sandbox` always installs the dispatch Proc before
+    // invoking the runtime, so reaching this branch indicates a misuse
+    // rather than a normal control path.
+    let on_dispatch = caller
+        .data()
+        .on_dispatch()
+        .ok_or("a Sandbox callback fired outside an active Sandbox#run — please report this as a kobako bug")?;
+
+    let resp_bytes = invoke_on_dispatch(on_dispatch, &req_bytes).map_err(|_| {
+        "a Sandbox callback raised an exception instead of returning a fault — please report this as a kobako bug"
+    })?;
+
+    write_response(caller, &resp_bytes)
+}
+
+/// Invoke the Ruby-side dispatch +Proc+ with the request bytes and return
+/// the encoded Response bytes. The Proc is contracted to fold every
+/// dispatch failure into a +Response.err+ envelope (see
+/// `Kobako::Transport::Dispatcher.dispatch`), so reaching the error
+/// branch is itself a wire-layer fault rather than a normal control path.
+fn invoke_on_dispatch(
+    on_dispatch: Opaque<Value>,
+    req_bytes: &[u8],
+) -> Result<Vec<u8>, MagnusError> {
+    // The wasmtime callback runs on the same Ruby thread that called the
+    // active Sandbox invocation (#eval or #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_dispatch");
+    let proc_value: Value = ruby.get_inner(on_dispatch);
+    let req_str = ruby.str_from_slice(req_bytes);
+    let resp: RString = proc_value.funcall("call", (req_str,))?;
+    Ok(super::rstring_to_vec(resp))
+}
+
+/// Allocate a guest-side buffer and copy the response bytes into it via
+/// `super::guest_mem::alloc_and_write`, returning the packed
+/// `(ptr<<32)|len` u64 the guest's `__kobako_dispatch` import expects.
+fn write_response(caller: &mut Caller<'_, Invocation>, bytes: &[u8]) -> Result<i64, &'static str> {
+    let ptr = super::guest_mem::alloc_and_write(caller, bytes)?;
+    Ok(((ptr as i64) << 32) | (bytes.len() as i64))
+}

data/ext/kobako/src/runtime/exports.rs

@@ -0,0 +1,51 @@
+//! Cached wasmtime export handles for the host-driven ABI surface.
+//!
+//! `Runtime::from_path` resolves the three docs/wire-codec.md ABI exports
+//! the run path drives (`__kobako_eval` / `__kobako_run` /
+//! `__kobako_take_outcome`) once at construction and stores their typed
+//! handles here, so each `#eval` / `#run` calls a cached handle rather than
+//! re-resolving the export by name. Distinct from `super::cache` (the
+//! process-wide Engine / Module cache): this caches *which guest function
+//! to call*, per `Runtime`.
+//!
+//! `__kobako_alloc` is deliberately absent — only `super::dispatch` calls
+//! it, and it does so through `Caller::get_export` on the wasmtime side.
+
+use wasmtime::{AsContextMut, Instance as WtInstance, TypedFunc};
+
+use super::invocation::StoreCell;
+
+/// The cached host-driven export handles. Each is `Option` because test
+/// fixtures (a minimal "ping" module) need not provide them; real
+/// `kobako.wasm` always does, and the run-path methods raise a Ruby
+/// `Kobako::TrapError` (via `require_export`) when a handle is `None`.
+pub(crate) struct Exports {
+    pub(crate) eval: Option<TypedFunc<(), ()>>,
+    pub(crate) run: Option<TypedFunc<(i32, i32), ()>>,
+    pub(crate) take_outcome: Option<TypedFunc<(), u64>>,
+}
+
+impl Exports {
+    /// Best-effort lookup of the three host-driven exports against a
+    /// freshly instantiated module. Missing exports are not an error here
+    /// (the test fixture is a bare module); the host enforces presence at
+    /// invocation time. Only the SPEC ABI shapes are accepted —
+    /// `__kobako_eval` is `() -> ()`, `__kobako_run` is
+    /// `(env_ptr, env_len) -> ()`, `__kobako_take_outcome` is `() -> u64`
+    /// (docs/wire-codec.md § ABI Signatures).
+    pub(crate) fn resolve(instance: &WtInstance, store: &StoreCell) -> Self {
+        let mut store_ref = store.borrow_mut();
+        let mut ctx = store_ref.as_context_mut();
+        Self {
+            eval: instance
+                .get_typed_func::<(), ()>(&mut ctx, "__kobako_eval")
+                .ok(),
+            run: instance
+                .get_typed_func::<(i32, i32), ()>(&mut ctx, "__kobako_run")
+                .ok(),
+            take_outcome: instance
+                .get_typed_func::<(), u64>(&mut ctx, "__kobako_take_outcome")
+                .ok(),
+        }
+    }
+}