kobako 0.12.1 → 0.12.2

data/{ext/kobako/src/runtime → crates/kobako-wasmtime/src}/invocation.rs

@@ -1,46 +1,49 @@
 //! Per-invocation host state — the materialised
 //! [SPEC.md Single-Invocation Slot] (one `Invocation` per OS thread
-//! for the lifetime of one `Runtime::eval` / `Runtime::run` call).
+//! for the lifetime of one `Driver` invoke call).
 //!
 //! Owned as the data of each per-invocation `wasmtime::Store`
 //! and threaded through every host import —
-//! the `__kobako_dispatch` dispatcher reads the bound dispatch Proc,
-//! while the run-path methods on `crate::runtime::Runtime` install the
-//! invocation's WASI context + pipes at Store creation.
+//! the `__kobako_dispatch` dispatcher reads the bound dispatch handler,
+//! while `Driver::invoke` installs the invocation's WASI
+//! context + pipes (via `frames::install_wasi_frames`) before the guest
+//! export call.
 //!
 //! The slot also carries the per-invocation wall-clock deadline
 //! and the per-invocation linear-memory
 //! delta cap `MemoryLimiter`. Both are
 //! read from the wasmtime `epoch_deadline_callback` / `ResourceLimiter`
-//! callbacks installed in `crate::runtime::Runtime::new_store`. The
+//! callbacks installed in `Driver::new_store`. The
 //! memory cap measures only the `memory.grow` delta past the linear-
 //! memory size captured at invocation entry — the image's initial
 //! allocation is outside the budget.
 //!
-//! [SPEC.md Single-Invocation Slot]: ../../../../SPEC.md
+//! [SPEC.md Single-Invocation Slot]: ../../../SPEC.md
 
+use std::sync::Arc;
 use std::time::{Duration, Instant};
 
-use magnus::{value::Opaque, Value};
 use wasmtime::ResourceLimiter;
 use wasmtime_wasi::p1::WasiP1Ctx;
 use wasmtime_wasi::p2::pipe::MemoryOutputPipe;
 
+use kobako_runtime::dispatch::DispatchHandler;
+
 /// Per-invocation host state — the data half of the Single-Invocation
 /// Slot. Threaded through every host import callback.
 ///
 /// All field access is mediated by methods on this type — the WASI ctx
 /// is rebuilt fresh before each invocation via
-/// `Invocation::install_wasi`, the Ruby dispatch Proc is set once via
+/// `Invocation::install_wasi`, the dispatch handler is set once via
 /// `Invocation::bind_on_dispatch`, and captured stdout/stderr bytes
 /// are read after the invocation via `Invocation::stdout_bytes` /
 /// `Invocation::stderr_bytes`. The fields are private so the mutation
 /// surface stays narrow.
-pub(super) struct Invocation {
+pub(crate) struct Invocation {
     wasi: Option<WasiP1Ctx>,
     stdout_pipe: Option<MemoryOutputPipe>,
     stderr_pipe: Option<MemoryOutputPipe>,
-    on_dispatch: Option<Opaque<Value>>,
+    on_dispatch: Option<Arc<dyn DispatchHandler>>,
     deadline: Option<Instant>,
     limiter: MemoryLimiter,
     wall_entry: Option<Instant>,
@@ -52,7 +55,7 @@ impl Invocation {
     /// `Sandbox#memory_limit` cap in bytes (or `None` to disable the cap);
     /// it is read from the wasmtime `ResourceLimiter` callback every
     /// time the guest grows linear memory.
-    pub(super) fn new(memory_limit: Option<usize>) -> Self {
+    pub(crate) fn new(memory_limit: Option<usize>) -> Self {
         Self {
             wasi: None,
             stdout_pipe: None,
@@ -66,10 +69,10 @@ impl Invocation {
     }
 
     /// Install a freshly-built WASI context plus the matching stdout/stderr
-    /// pipe clones. Called from `crate::runtime::Runtime::eval` /
-    /// `crate::runtime::Runtime::run` at the top of every guest
+    /// pipe clones. Called from `frames::install_wasi_frames`, which
+    /// `Driver::invoke` runs at the top of every guest
     /// invocation.
-    pub(super) fn install_wasi(
+    pub(crate) fn install_wasi(
         &mut self,
         wasi: WasiP1Ctx,
         stdout: MemoryOutputPipe,
@@ -80,16 +83,16 @@ impl Invocation {
         self.stderr_pipe = Some(stderr);
     }
 
-    /// Register the Ruby-side dispatch `Proc`. From this point on, every
-    /// `__kobako_dispatch` host import invocation calls the Proc with the
-    /// request bytes and expects encoded Response bytes back.
-    pub(super) fn bind_on_dispatch(&mut self, proc_value: Opaque<Value>) {
-        self.on_dispatch = Some(proc_value);
+    /// Bind the dispatch handler for this invocation. From this point on,
+    /// every `__kobako_dispatch` host import invocation hands the handler
+    /// the request bytes and expects encoded Response bytes back.
+    pub(crate) fn bind_on_dispatch(&mut self, handler: Arc<dyn DispatchHandler>) {
+        self.on_dispatch = Some(handler);
     }
 
     /// Snapshot the bytes captured on guest fd 1 during the most recent
     /// run. Empty vec before any run.
-    pub(super) fn stdout_bytes(&self) -> Vec<u8> {
+    pub(crate) fn stdout_bytes(&self) -> Vec<u8> {
         self.stdout_pipe
             .as_ref()
             .map(|p| p.contents().to_vec())
@@ -98,53 +101,55 @@ impl Invocation {
 
     /// Snapshot the bytes captured on guest fd 2 during the most recent
     /// run. Empty vec before any run.
-    pub(super) fn stderr_bytes(&self) -> Vec<u8> {
+    pub(crate) fn stderr_bytes(&self) -> Vec<u8> {
         self.stderr_pipe
             .as_ref()
             .map(|p| p.contents().to_vec())
             .unwrap_or_default()
     }
 
-    /// Return the bound dispatch Proc handle. `Opaque<Value>` is `Copy`,
-    /// so the handle is returned by value rather than by reference. None
-    /// means no Proc has been bound yet via
+    /// Return a clone of the bound dispatch handler (an `Arc`, so the clone
+    /// is a cheap refcount bump). Cloning releases the borrow on the
+    /// `Caller` so the dispatcher can re-borrow it to write the response.
+    /// None means no handler has been bound yet via
     /// `Invocation::bind_on_dispatch`.
-    pub(super) fn on_dispatch(&self) -> Option<Opaque<Value>> {
-        self.on_dispatch
+    pub(crate) fn on_dispatch(&self) -> Option<Arc<dyn DispatchHandler>> {
+        self.on_dispatch.clone()
     }
 
     /// Mutable handle to the live WASI context. Panics if no context has
     /// been installed yet — every call site is downstream of
-    /// `Invocation::install_wasi` running at the top of
-    /// `Runtime::eval` / `Runtime::run`, so reaching this branch with
-    /// `None` signals a host-side wiring bug.
-    pub(super) fn wasi_mut(&mut self) -> &mut WasiP1Ctx {
+    /// `Invocation::install_wasi` running at the top of every `Driver`
+    /// invoke, so reaching this branch with `None` signals a host-side
+    /// wiring bug.
+    pub(crate) fn wasi_mut(&mut self) -> &mut WasiP1Ctx {
         self.wasi.as_mut().expect(
-            "WASI context not initialised — call Runtime#eval / Runtime#run before any WASI use",
+            "WASI context not initialised — the driver must install frames before any WASI use",
         )
     }
 
     /// Replace the per-run wall-clock deadline. `Some(at)` makes the
     /// epoch-deadline callback trap once `Instant::now() >= at`; `None`
-    /// disables the cap. Called at the top of every `#run`.
-    pub(super) fn set_deadline(&mut self, deadline: Option<Instant>) {
+    /// disables the cap. Called from `Driver::prime_caps` at the top of
+    /// every invocation (`#eval` and `#run`).
+    pub(crate) fn set_deadline(&mut self, deadline: Option<Instant>) {
         self.deadline = deadline;
     }
 
     /// Return the current per-run deadline. Read from the epoch-deadline
-    /// callback installed by `crate::runtime::Runtime::new_store`.
-    pub(super) fn deadline(&self) -> Option<Instant> {
+    /// callback installed by `Driver::new_store`.
+    pub(crate) fn deadline(&self) -> Option<Instant> {
         self.deadline
     }
 
     /// Mutable handle to the embedded `MemoryLimiter`. Required by
     /// the wasmtime `ResourceLimiter` callback wiring in
-    /// `crate::runtime::Runtime::new_store`
+    /// `Driver::new_store`
     /// (`store.limiter(|state| state.limiter_mut())`); kept private to
     /// the wasm submodule so the only public surface for arming the
     /// cap goes through `Invocation::arm_memory_cap` /
     /// `Invocation::disarm_memory_cap`.
-    pub(super) fn limiter_mut(&mut self) -> &mut MemoryLimiter {
+    pub(crate) fn limiter_mut(&mut self) -> &mut MemoryLimiter {
         &mut self.limiter
     }
 
@@ -157,13 +162,13 @@ impl Invocation {
     /// call to the corresponding `__kobako_*` export so post-run host
     /// bookkeeping (e.g. fetching the OUTCOME_BUFFER) is not
     /// attributed to the user script.
-    pub(super) fn arm_memory_cap(&mut self, baseline: usize) {
+    pub(crate) fn arm_memory_cap(&mut self, baseline: usize) {
         self.limiter.activate(baseline);
     }
 
     /// Disarm the memory cap. See
     /// `Invocation::arm_memory_cap`.
-    pub(super) fn disarm_memory_cap(&mut self) {
+    pub(crate) fn disarm_memory_cap(&mut self) {
         self.limiter.deactivate();
     }
 
@@ -173,7 +178,7 @@ impl Invocation {
     /// bracket matches the `timeout` deadline accounting and
     /// excludes post-run host bookkeeping such as `OUTCOME_BUFFER`
     /// decoding.
-    pub(super) fn start_wall_clock(&mut self) {
+    pub(crate) fn start_wall_clock(&mut self) {
         self.wall_entry = Some(Instant::now());
     }
 
@@ -182,7 +187,7 @@ impl Invocation {
     /// stop with no matching start (e.g. if the guest export call
     /// never executed because of a host-side allocation failure)
     /// leaves the previously-recorded value untouched.
-    pub(super) fn stop_wall_clock(&mut self) {
+    pub(crate) fn stop_wall_clock(&mut self) {
         if let Some(entry) = self.wall_entry.take() {
             self.wall_time = entry.elapsed();
         }
@@ -191,7 +196,7 @@ impl Invocation {
     /// Return the wall-clock duration the most recent invocation
     /// spent inside the guest export call.
     /// Zero before the first invocation.
-    pub(super) fn wall_time(&self) -> Duration {
+    pub(crate) fn wall_time(&self) -> Duration {
         self.wall_time
     }
 
@@ -199,7 +204,7 @@ impl Invocation {
     /// water mark of the per-invocation `memory.grow` delta past the
     /// linear-memory size captured at invocation entry. Zero before
     /// the first invocation.
-    pub(super) fn memory_peak(&self) -> usize {
+    pub(crate) fn memory_peak(&self) -> usize {
         self.limiter.peak()
     }
 }
@@ -216,16 +221,16 @@ impl Invocation {
 /// `cap_active` gates whether the cap is enforced — wasmtime's
 /// `ResourceLimiter` also fires for the module's declared initial
 /// allocation at instantiation time, but the cap stays dormant until
-/// `MemoryLimiter::activate` flips the flag for one
-/// `Runtime::eval` / `Runtime::run` call. When `cap_active` is
-/// `false`, the limiter always allows growth.
+/// `MemoryLimiter::activate` flips the flag for one `Driver` invoke
+/// call. When `cap_active` is `false`, the limiter always allows
+/// growth.
 ///
 /// When `memory.grow` would push the per-invocation delta past
 /// `max_memory`, the limiter returns `MemoryLimitTrap` from
 /// `memory_growing`; wasmtime turns that into the trap surfaced to the
 /// host as a guest invocation failure.
 #[derive(Debug, Clone, Copy)]
-pub(super) struct MemoryLimiter {
+pub(crate) struct MemoryLimiter {
     max_memory: Option<usize>,
     baseline: usize,
     cap_active: bool,
@@ -274,7 +279,7 @@ impl MemoryLimiter {
     /// rejected `desired` values that trip the memory
     /// cap never update the peak, so the reported value never exceeds
     /// `memory_limit`.
-    pub(super) fn peak(&self) -> usize {
+    pub(crate) fn peak(&self) -> usize {
         self.peak
     }
 }
@@ -329,7 +334,7 @@ impl MemoryLimitTrap {
     /// by the sibling-module `classify_trap` unit tests to materialise
     /// a representative error for downcast routing.
     #[cfg(test)]
-    pub(super) fn new(desired: usize, limit: usize) -> Self {
+    pub(crate) fn new(desired: usize, limit: usize) -> Self {
         Self { desired, limit }
     }
 }

data/crates/kobako-wasmtime/src/lib.rs

@@ -0,0 +1,47 @@
+//! kobako-wasmtime — the wasmtime implementation of the kobako runtime
+//! contract.
+//!
+//! `Driver` implements `kobako_runtime::runtime::Runtime` over wasmtime:
+//! every invocation instantiates a fresh instance from a pre-linked
+//! template and discards the whole Store afterwards — the
+//! per-invocation instance discipline (ABI v2). Everything engine-bound
+//! lives behind the contract surface, so a frontend shell (the Ruby
+//! ext's `Kobako::Runtime`) sees no wasmtime type.
+//!
+//! Module layout (one responsibility per file):
+//!
+//! * `driver` — `Driver` + `impl kobako_runtime::runtime::Runtime`
+//!   (the run mechanics).
+//! * `cache` — process-wide Engine + per-path Module cache and the
+//!   process-singleton epoch ticker thread.
+//! * `config` — per-Driver caps (timeout / stdout / stderr limits).
+//! * `exports` — per-invocation `__kobako_eval` / `_run` /
+//!   `_take_outcome` / `_alloc` / `memory` handles.
+//! * `instance_pre` — host-import Linker wiring + per-path
+//!   `InstancePre` cache.
+//! * `invocation` — Invocation (per-Store context), the
+//!   `MemoryLimiter` memory cap, and the trap marker types
+//!   (`TimeoutTrap` / `MemoryLimitTrap`).
+//! * `dispatch` — `__kobako_dispatch` host-import dispatch helpers.
+//! * `frames` — stdin frame stream + WASI context assembly, `#run`
+//!   envelope write, OUTCOME_BUFFER readout.
+//! * `guest_mem` — Caller-based guest linear-memory alloc / write / read.
+//! * `capture` — stdout / stderr pipe sizing + clip helpers.
+//! * `ambient` — frozen WASI clocks + constant RNG (ambient denial).
+//! * `trap` — wasmtime-error → neutral `Trap` classification.
+
+mod ambient;
+mod cache;
+mod capture;
+mod config;
+mod dispatch;
+mod driver;
+mod exports;
+mod frames;
+mod guest_mem;
+mod instance_pre;
+mod invocation;
+mod trap;
+
+pub use config::Config;
+pub use driver::Driver;

data/{ext/kobako/src/runtime → crates/kobako-wasmtime/src}/trap.rs

@@ -6,25 +6,24 @@
 //! `TimeoutTrap`. The classification is a pure function over the error's
 //! downcast chain so it can be exercised from `cargo test` without the
 //! magnus surface; the trap marker types themselves live in
-//! `super::invocation` (where the limiter / callback construct them).
+//! `crate::invocation` (where the limiter / callback construct them).
 
 use std::time::Instant;
 
-use magnus::{Error as MagnusError, Ruby};
 use wasmtime::{StoreContextMut, UpdateDeadline};
 
-use super::errors::{memory_limit_err, setup_err, timeout_err, trap_err};
-use super::invocation::{Invocation, MemoryLimitTrap, TimeoutTrap};
+use crate::invocation::{Invocation, MemoryLimitTrap, TimeoutTrap};
+use kobako_runtime::error::{SetupError, Trap};
 
 /// Epoch-deadline callback installed on every Store. Read the per-run
 /// wall-clock deadline from `Invocation` and trap with
 /// `TimeoutTrap` once the deadline has passed; otherwise extend the
 /// next check by one tick of the process-wide epoch ticker. When the
-/// deadline is `None` the callback should not fire under normal
-/// `Runtime::eval` / `Runtime::run` flow because
+/// deadline is `None` the callback should not fire under the normal
+/// `Driver` invoke flow because
 /// `set_epoch_deadline(u64::MAX)` is used; returning a long extension
 /// keeps the callback inert as a defence in depth.
-pub(super) fn epoch_deadline_callback(
+pub(crate) fn epoch_deadline_callback(
     ctx: StoreContextMut<'_, Invocation>,
 ) -> wasmtime::Result<UpdateDeadline> {
     match ctx.data().deadline() {
@@ -63,39 +62,34 @@ fn classify_trap(err: &wasmtime::Error) -> TrapClass {
     }
 }
 
-/// Map a wasmtime call error to the right top-level `Kobako::*` Ruby
-/// exception class. The ABI export symbol (`__kobako_eval` /
-/// `__kobako_run`) is deliberately omitted from the message — the
-/// Sandbox layer attaches the user-facing verb (`Sandbox#eval` /
-/// `Sandbox#run`) so the message reads in caller vocabulary rather
-/// than ABI vocabulary.
+/// Classify a wasmtime call error into a neutral `Trap`. The ABI export
+/// symbol (`__kobako_eval` / `__kobako_run`) is deliberately omitted from
+/// the message — the Sandbox layer attaches the user-facing verb
+/// (`Sandbox#eval` / `Sandbox#run`) so the message reads in caller
+/// vocabulary rather than ABI vocabulary.
 ///
 /// For the configured-cap paths (`TrapClass::Timeout` /
 /// `TrapClass::MemoryLimit`) the trap's own `std::fmt::Display`
 /// carries the user-facing reason (`"wall-clock deadline exceeded"`,
 /// `"linear memory growth exceeded memory_limit: ..."`). The wasmtime
-/// outer wrapper at `format!("{}", err)` would otherwise surface only
+/// outer wrapper at `format!("{err}")` would otherwise surface only
 /// the `"error while executing at wasm backtrace: ..."` framing, which
 /// is operator noise on a cap trap. For `TrapClass::Other` the framing
 /// is kept but the chain's root cause is appended (see
 /// `other_trap_message`) so the real trap reason survives.
-pub(super) fn call_err(ruby: &Ruby, err: wasmtime::Error) -> MagnusError {
+pub(crate) fn trap_from(err: wasmtime::Error) -> Trap {
     match classify_trap(&err) {
-        TrapClass::Timeout => {
-            let msg = err
-                .downcast_ref::<TimeoutTrap>()
+        TrapClass::Timeout => Trap::Timeout(
+            err.downcast_ref::<TimeoutTrap>()
                 .map(|t| t.to_string())
-                .unwrap_or_else(|| format!("{}", err));
-            timeout_err(ruby, msg)
-        }
-        TrapClass::MemoryLimit => {
-            let msg = err
-                .downcast_ref::<MemoryLimitTrap>()
+                .unwrap_or_else(|| format!("{err}")),
+        ),
+        TrapClass::MemoryLimit => Trap::MemoryLimit(
+            err.downcast_ref::<MemoryLimitTrap>()
                 .map(|t| t.to_string())
-                .unwrap_or_else(|| format!("{}", err));
-            memory_limit_err(ruby, msg)
-        }
-        TrapClass::Other => trap_err(ruby, other_trap_message(&err)),
+                .unwrap_or_else(|| format!("{err}")),
+        ),
+        TrapClass::Other => Trap::Other(other_trap_message(&err)),
     }
 }
 
@@ -116,21 +110,21 @@ fn other_trap_message(err: &wasmtime::Error) -> String {
     }
 }
 
-/// Map an instantiation error to `Kobako::SetupError`. Instantiation runs
-/// during `from_path` construction, before any invocation — every such
-/// failure is a construction setup fault, not a
+/// Classify an instantiation error as a runtime-dead `SetupError`.
+/// Instantiation runs during `from_path` construction, before any
+/// invocation — every such failure is a construction setup fault, not a
 /// per-invocation cap outcome. The memory cap is dormant during
 /// instantiation (see `Invocation::arm_memory_cap` /
 /// `Invocation::disarm_memory_cap`) and the epoch deadline is not yet
-/// armed, so the `call_err` trap-class split does not apply here.
-pub(super) fn instantiate_err(ruby: &Ruby, err: wasmtime::Error) -> MagnusError {
-    setup_err(ruby, format!("instantiate: {}", err))
+/// armed, so the `trap_from` trap-class split does not apply here.
+pub(crate) fn instantiate_err(err: wasmtime::Error) -> SetupError {
+    SetupError::Dead(format!("instantiate: {err}"))
 }
 
 #[cfg(test)]
 mod tests {
     use super::{classify_trap, other_trap_message, TrapClass};
-    use crate::runtime::invocation::{MemoryLimitTrap, TimeoutTrap};
+    use crate::invocation::{MemoryLimitTrap, TimeoutTrap};
 
     #[test]
     fn classify_trap_routes_timeout_trap_to_timeout() {

data/ext/kobako/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "kobako"
-version = "0.12.1"
+version = "0.12.2"
 edition = "2021"
 authors = ["Aotokitsuruya <contact@aotoki.me>"]
 license = "Apache-2.0"
@@ -11,34 +11,11 @@ crate-type = ["cdylib"]
 
 [dependencies]
 magnus = { version = "0.8.2" }
-# wasmtime — host-side embedder for kobako.wasm. We disable default-features
-# and opt back in only what kobako needs: a Cranelift-backed runtime that can
-# compile a pre-built wasm32-wasip1 module on the host triple, plus the `wat`
-# feature so test fixtures can be expressed as text.
-# `cache` / `parallel-compilation` / `pooling` / `component-model` / `async`
-# are intentionally off — kobako runs short-lived synchronous sandboxes.
-wasmtime = { version = "45.0.0", default-features = false, features = [
-    "cranelift",
-    "runtime",
-    "gc",
-    "gc-drc",
-    "addr2line",
-    "demangle",
-    "wat",
-] }
-# wasmtime-wasi provides WASI preview1 support for routing guest stdout/stderr
-# into in-memory buffers. The `p1` feature enables the
-# WasiCtxBuilder + preview1 adapter which wires fd 1/2 to pipes. We omit
-# `p2` (component-model) and `p0`/`p3` (async) because kobako runs
-# synchronous sandboxes only.
-wasmtime-wasi = { version = "45.0.0", default-features = false, features = ["p1"] }
-# sha2 keys the on-disk compiled-module cache by Guest Binary content
-# (see runtime/cache.rs); a collision would load the wrong artifact, so
-# the hash must be cryptographic.
-sha2 = "0.11"
-
-# libc supplies geteuid for the cache-directory ownership check gating
-# the unsafe artifact deserialize (see runtime/cache.rs); std exposes a
-# file's owner but not the process's effective uid.
-[target.'cfg(unix)'.dependencies]
-libc = "0.2"
+# The engine-neutral host runtime contract plus its wasmtime driver —
+# the ext is a thin magnus shim over them. Pure path dependencies: both
+# crates ship inside the gem, so installs never resolve them against
+# crates.io and the gem release cadence stays decoupled from theirs.
+# wasmtime itself enters only through kobako-wasmtime; no engine type
+# reaches this crate.
+kobako-runtime = { path = "../../crates/kobako-runtime" }
+kobako-wasmtime = { path = "../../crates/kobako-wasmtime" }

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

@@ -0,0 +1,150 @@
+//! The magnus bridge for the guest→host dispatch seam.
+//!
+//! The Ruby-Proc `DispatchHandler` and the frame-scoped `GuestYielder`
+//! handle the Proc re-enters the guest through — the one place the
+//! dispatch seam touches `magnus`. The wasm-side dispatch path
+//! (`kobako_wasmtime`'s dispatch module) sees only the contract traits.
+
+use core::cell::Cell;
+use core::ptr::NonNull;
+
+use magnus::value::{Opaque, ReprValue};
+use magnus::{method, prelude::*, Error as MagnusError, RClass, RString, Ruby, Value};
+
+use kobako_runtime::dispatch::DispatchHandler;
+use kobako_runtime::yielder::Yielder;
+
+/// Register the `Kobako::Runtime::GuestYielder` Ruby class. Called from
+/// `crate::runtime::init` after `Kobako::Runtime` is defined so the
+/// `#[magnus::wrap]` class name resolves before any object is wrapped.
+pub(super) fn register(runtime_class: RClass) -> Result<(), MagnusError> {
+    let ruby = Ruby::get().expect("Ruby thread");
+    let class = runtime_class.define_class("GuestYielder", ruby.class_object())?;
+    class.define_method("call", method!(GuestYielder::call, 1))?;
+    Ok(())
+}
+
+/// Frame-scoped Ruby handle that lets the dispatch `Proc` re-enter the
+/// guest to run a yielded block. It wraps the active `&mut dyn Yielder`
+/// for exactly one `__kobako_dispatch` frame: the bridge builds one, hands
+/// it to the `Proc` as the second argument, and `invalidate`s it the
+/// instant the `Proc` returns. A guest block stashed and called after that
+/// frame normally raises `LocalJumpError` at the Ruby
+/// `Transport::Yielder` net — invalidated in the dispatcher's `ensure`,
+/// which fires before this handle is reached. This inner invalidation is
+/// the backstop behind that outer net: it keeps `call`'s `unsafe`
+/// `NonNull` deref from touching freed stack should the outer net ever be
+/// bypassed, so neither net is redundant.
+///
+/// This is the single, explicit, frame-scoped FFI pointer the host↔guest
+/// re-entry still costs: `magnus`' `funcall` sits between two Rust frames,
+/// so the typed `&mut dyn Yielder` cannot cross it and is erased to a raw
+/// pointer here. Unlike the dispatch `Proc`, this handle holds **no Ruby
+/// `Value`**, so GC has nothing to trace through it — it needs no `mark`.
+#[magnus::wrap(class = "Kobako::Runtime::GuestYielder", free_immediately, size)]
+struct GuestYielder {
+    yielder: Cell<Option<NonNull<dyn Yielder>>>,
+}
+
+// SAFETY: magnus requires `Send + Sync` on wrapped types. The raw pointer
+// is created, used, and invalidated within a single `__kobako_dispatch`
+// frame on the one Ruby thread that owns the active Invocation (SPEC.md
+// Single-Invocation Slot); it is never read from another thread.
+unsafe impl Send for GuestYielder {}
+unsafe impl Sync for GuestYielder {}
+
+impl GuestYielder {
+    /// Erase the frame-scoped `&mut dyn Yielder` into a Ruby-owned handle.
+    /// Safety contract for the caller: `invalidate` MUST run before the
+    /// borrow this pointer came from ends (i.e. before the dispatch frame
+    /// returns).
+    fn new(yielder: &mut dyn Yielder) -> Self {
+        let ptr = NonNull::from(yielder);
+        // Erase the borrow's lifetime to `'static`; the pointer is only
+        // ever dereferenced while it is still `Some` (i.e. `invalidate`
+        // has not run), so the referent is guaranteed live.
+        let ptr: NonNull<dyn Yielder> = unsafe {
+            std::mem::transmute::<NonNull<dyn Yielder + '_>, NonNull<dyn Yielder + 'static>>(ptr)
+        };
+        Self {
+            yielder: Cell::new(Some(ptr)),
+        }
+    }
+
+    /// Mark this handle dead. Called the instant the dispatch frame's
+    /// `funcall` returns, so a guest block stashed beyond its frame raises
+    /// instead of dereferencing freed stack.
+    fn invalidate(&self) {
+        self.yielder.set(None);
+    }
+
+    /// Ruby-visible `call(args_bytes) -> resp_bytes`: drive one yield
+    /// round-trip. Stands in for the `String -> String` callable the host
+    /// `Transport::Yielder` invokes. Raises `Kobako::TrapError` when the
+    /// handle has been invalidated (escaped guest block) or the re-entry
+    /// itself traps.
+    fn call(&self, args: RString) -> Result<RString, MagnusError> {
+        let ruby = Ruby::get().expect("Ruby handle unavailable in __kobako_yield");
+        let Some(mut ptr) = self.yielder.get() else {
+            return Err(super::errors::trap_err(
+                &ruby,
+                "guest block invoked after the host dispatch frame returned",
+            ));
+        };
+        let bytes = super::rstring_to_vec(args);
+        // SAFETY: `yielder` is `Some`, so `invalidate` has not run — the
+        // dispatch frame that lent the `&mut dyn Yielder` is still on the
+        // Rust stack, and the Single-Invocation Slot guarantees no other
+        // frame aliases it. The borrow ends with this method.
+        let yielder: &mut dyn Yielder = unsafe { ptr.as_mut() };
+        let resp = yielder
+            .yield_block(&bytes)
+            .map_err(|t| super::errors::trap_to_magnus(&ruby, t))?;
+        Ok(ruby.str_from_slice(&resp))
+    }
+}
+
+/// The Ruby-Proc bridge: a `DispatchHandler` backed by the host-side
+/// dispatch `Proc` registered through `Runtime#on_dispatch=`. This is the
+/// one place the dispatch seam touches `magnus`; the wasm runtime sees
+/// only the trait. The Proc is GC-rooted by `Runtime`'s `mark`; this
+/// struct holds an `Opaque` copy of the same handle.
+pub(super) struct RubyDispatchHandler {
+    on_dispatch: Opaque<Value>,
+}
+
+impl RubyDispatchHandler {
+    pub(super) fn new(on_dispatch: Opaque<Value>) -> Self {
+        Self { on_dispatch }
+    }
+}
+
+impl DispatchHandler for RubyDispatchHandler {
+    /// Call the Ruby 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 a raise is a contract
+    /// violation surfaced as `None` — the dispatcher then walks the
+    /// 0-return wire-fault path.
+    fn dispatch(&self, request: &[u8], yielder: &mut dyn Yielder) -> Option<Vec<u8>> {
+        // 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(self.on_dispatch);
+        let req_str = ruby.str_from_slice(request);
+        // Hand the Proc a frame-scoped yielder object as its second arg and
+        // invalidate it the instant the Proc returns, so a guest block that
+        // escapes the dispatch frame can never deref the freed stack
+        // pointer. `guest_yielder` holds no Ruby Value, so it needs no GC
+        // mark — the GC has nothing to trace through it.
+        let guest_yielder = ruby.obj_wrap(GuestYielder::new(yielder));
+        let resp: Result<RString, magnus::Error> =
+            proc_value.funcall("call", (req_str, guest_yielder));
+        guest_yielder.invalidate();
+        resp.ok().map(super::rstring_to_vec)
+    }
+}