kobako 0.27.0 → 0.29.0

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

@@ -5,128 +5,175 @@
 //! 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::cell::{Cell, RefCell};
 use core::ptr::NonNull;
+use std::sync::Arc;
 
+use magnus::rb_sys::AsRawValue;
 use magnus::value::{Opaque, ReprValue};
-use magnus::{method, prelude::*, Error as MagnusError, RClass, RString, Ruby, Symbol, Value};
+use magnus::{
+    method, prelude::*, Error as MagnusError, RModule, RString, Ruby, Symbol, TypedData, Value,
+};
 
 use kobako_runtime::dispatch::DispatchHandler;
 use kobako_runtime::yielder::Yielder;
 use kobako_transport::envelope::{Call, Fault, FaultKind, Reply, Target, YieldReply};
 
-/// The names the host `Transport::Yielder` branches on — one per Yield
-/// Reply arm. Neutral Symbols rather than the envelope's tag bytes, the
-/// same way `Snapshot#outcome` names its arms: the core envelope is this
-/// side's to read, so no byte value of it reaches Ruby.
+/// The names each side of this seam branches on — one per Reply and
+/// Yield Reply arm. Neutral Symbols rather than the envelope's tag bytes,
+/// the same way `Snapshot#outcome` names its arms: the core envelope is
+/// this side's to read, so no byte value of it reaches Ruby.
 const ARM_OK: &str = "ok";
+const ARM_FAULT: &str = "fault";
 const ARM_BREAK: &str = "break";
 const ARM_ERROR: &str = "error";
+const ARM_UNSUPPORTED: &str = "unsupported";
 
-/// 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> {
+/// Defines the class the `#[magnus::wrap]` name resolves to, and looks it
+/// up once, before any object is wrapped.
+pub(super) fn register(kobako: RModule) -> Result<(), MagnusError> {
     let ruby = Ruby::get().expect("Ruby thread");
-    let class = runtime_class.define_class("GuestYielder", ruby.class_object())?;
+    let class = kobako.define_class("GuestYielder", ruby.class_object())?;
     class.define_method("call", method!(GuestYielder::call, 1))?;
+    GuestYielder::class(&ruby);
     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
+/// The Yielders one invocation's open Calls lent, innermost last. A yield
+/// re-enters the guest only through the innermost, whatever Call's block
+/// it runs, so no Yielder is reached while a later Call holds the guest.
+///
+/// This is the one place the host↔guest re-entry still costs raw
+/// pointers: `magnus`' `funcall` sits between two Rust frames, so the
+/// typed `&mut dyn Yielder` cannot cross it and is erased here. Each
+/// pointer is pushed before its frame's `funcall` and popped after it, so
+/// every pointer on the stack belongs to a frame still on the Rust stack.
+#[derive(Default)]
+struct OpenFrames(RefCell<Vec<NonNull<dyn Yielder>>>);
+
+// SAFETY: the stack is pushed and popped by the dispatch frames on the
+// fiber driving the invocation, and read only by a `GuestYielder` that
+// refuses every other fiber, so it is never reached from another thread.
+unsafe impl Send for OpenFrames {}
+unsafe impl Sync for OpenFrames {}
+
+impl OpenFrames {
+    /// Lend `yielder` for the frame `run` answers, popping it however
+    /// `run` returns.
+    fn lend<T>(&self, yielder: &mut dyn Yielder, run: impl FnOnce() -> T) -> T {
+        struct Pop<'a>(&'a OpenFrames);
+        impl Drop for Pop<'_> {
+            fn drop(&mut self) {
+                self.0 .0.borrow_mut().pop();
+            }
+        }
+        // SAFETY: the lifetime is erased only for as long as `Pop` keeps
+        // the pointer on the stack, which ends before `yielder` does.
+        let ptr: NonNull<dyn Yielder> = unsafe {
+            std::mem::transmute::<NonNull<dyn Yielder + '_>, NonNull<dyn Yielder + 'static>>(
+                NonNull::from(yielder),
+            )
+        };
+        self.0.borrow_mut().push(ptr);
+        let _pop = Pop(self);
+        run()
+    }
+
+    fn innermost(&self) -> Option<NonNull<dyn Yielder>> {
+        self.0.borrow().last().copied()
+    }
+}
+
+/// Frame-scoped Ruby handle that lets the dispatch `Proc` run the block
+/// one Call carried. The bridge builds one per `__kobako_upcall` frame,
+/// hands it to the `Proc` as the last 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.
+/// the backstop behind that outer net, 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)]
+/// The guest's Store is entered from the fiber that drives the
+/// invocation, and only from it: another fiber runs on its own native
+/// stack, which wasmtime's stack limit and the value budget never saw. A
+/// block run from any other fiber, including one on another thread, is
+/// refused before it reaches the guest.
+///
+/// It holds **no Ruby `Value`**, so GC has nothing to trace through it —
+/// it needs no `mark`. The driving fiber is kept as its raw identity,
+/// compared only while the frame is live and so while that fiber is.
+#[magnus::wrap(class = "Kobako::GuestYielder", free_immediately, size)]
 struct GuestYielder {
-    yielder: Cell<Option<NonNull<dyn Yielder>>>,
+    frame: u32,
+    open: Arc<OpenFrames>,
+    live: Cell<bool>,
+    fiber: rb_sys::VALUE,
 }
 
-// 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.
+// SAFETY: magnus requires `Send + Sync` on wrapped types. `call` refuses
+// every fiber but the one driving the invocation, so the frames it reaches
+// are only ever read on that fiber's 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)
-        };
+    fn new(ruby: &Ruby, frame: u32, open: Arc<OpenFrames>) -> Self {
         Self {
-            yielder: Cell::new(Some(ptr)),
+            frame,
+            open,
+            live: Cell::new(true),
+            fiber: ruby.fiber_current().as_raw(),
         }
     }
 
-    /// 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.
+    /// Runs the instant the dispatch frame's `funcall` returns, so a guest
+    /// block stashed beyond its frame raises instead of re-entering.
     fn invalidate(&self) {
-        self.yielder.set(None);
+        self.live.set(false);
     }
 
-    /// Ruby-visible `call(args_payload) -> [arm, body, class]`: drive one
-    /// yield round-trip and hand back the reply already split. The arm is
-    /// named here off the core envelope, so the host `Transport::Yielder`
-    /// decodes only a payload — and only on the two arms that carry one,
-    /// where `body` is the block's value; on the error arm it is the
-    /// message, and `class` names what raised.
-    /// Raises `Kobako::TrapError` when the handle has been invalidated
-    /// (escaped guest block), when the re-entry itself traps, or when the
-    /// guest answers with bytes the envelope cannot frame.
+    /// The arm is named here off the decoded Yield Reply, so the host
+    /// `Transport::Yielder` decodes only a payload.
     fn call(&self, args: RString) -> Result<(Symbol, RString, Option<String>), MagnusError> {
-        let ruby = Ruby::get().expect("Ruby handle unavailable in __kobako_yield");
-        let Some(mut ptr) = self.yielder.get() else {
+        let ruby = Ruby::get().expect("Ruby handle unavailable in the block bridge");
+        let innermost = self.open.innermost().filter(|_| self.live.get());
+        let Some(mut ptr) = innermost else {
             return Err(super::errors::trap_err(
                 &ruby,
                 "guest block invoked after the host dispatch frame returned",
             ));
         };
+        if ruby.fiber_current().as_raw() != self.fiber {
+            return Err(MagnusError::new(
+                ruby.exception_thread_error(),
+                "guest block called from a thread or fiber other than its invocation's",
+            ));
+        }
         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.
+        // SAFETY: this frame is live, so the innermost frame — this one or
+        // a later Call — is still on the Rust stack with its Yielder lent.
+        // Only the innermost frame's Ruby code runs, so no other borrow of
+        // that Yielder is live; the borrow ends with this method.
         let yielder: &mut dyn Yielder = unsafe { ptr.as_mut() };
-        let resp = yielder
-            .yield_to_block(&bytes)
+        let reply = yielder
+            .yield_to_block(self.frame, &bytes)
             .map_err(|t| super::errors::trap_to_magnus(&ruby, t))?;
-        match YieldReply::decode(&resp) {
-            Ok(YieldReply::Ok(body)) => {
-                Ok((ruby.to_symbol(ARM_OK), ruby.str_from_slice(&body), None))
-            }
-            Ok(YieldReply::Break(body)) => {
-                Ok((ruby.to_symbol(ARM_BREAK), ruby.str_from_slice(&body), None))
-            }
-            Ok(YieldReply::Error(record)) => Ok((
+        Ok(match reply {
+            YieldReply::Ok(body) => (ruby.to_symbol(ARM_OK), ruby.str_from_slice(&body), None),
+            YieldReply::Break => (ruby.to_symbol(ARM_BREAK), ruby.str_from_slice(&[]), None),
+            YieldReply::Error(record) => (
                 ruby.to_symbol(ARM_ERROR),
                 ruby.str_new(&record.message),
                 Some(record.name),
-            )),
-            Err(err) => Err(super::errors::trap_err(&ruby, err.to_string())),
-        }
+            ),
+            // The guest's own message stays behind: the host words this
+            // refusal itself.
+            YieldReply::Unsupported(_) => (
+                ruby.to_symbol(ARM_UNSUPPORTED),
+                ruby.str_from_slice(&[]),
+                None,
+            ),
+        })
     }
 }
 
@@ -138,37 +185,35 @@ impl GuestYielder {
 /// `Opaque` copy of the same handle.
 pub(super) struct RubyDispatchHandler {
     on_dispatch: Opaque<Value>,
+    open: Arc<OpenFrames>,
 }
 
 impl RubyDispatchHandler {
     pub(super) fn new(on_dispatch: Opaque<Value>) -> Self {
-        Self { on_dispatch }
+        Self {
+            on_dispatch,
+            open: Arc::default(),
+        }
     }
 }
 
 impl DispatchHandler for RubyDispatchHandler {
-    /// Call the Ruby Proc with the routed Call and return its Reply. The
-    /// envelope is already decoded, so Ruby receives the target, method,
-    /// and block flag as ordinary values and decodes only the payload —
-    /// through the MessagePack codec it already owns, which keeps a
-    /// large payload's strings shared with the buffer rather than copied.
-    ///
-    /// The Proc is contracted to fold every dispatch failure into the
-    /// Reply's fault arm (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.
+    /// Ruby decodes only the payload, through the codec it already owns,
+    /// which keeps a large payload's strings shared with the buffer rather
+    /// than copied. The Proc folds every `StandardError` into the Reply's
+    /// fault arm, so one escaping is a contract violation surfaced as
+    /// `None`.
     fn dispatch(&self, call: Call<'_>, yielder: &mut dyn Yielder) -> Option<Reply> {
         // The guest may be running GVL-free (`gvl: :release`); re-acquire the
         // GVL for the whole callback before touching any Ruby VALUE. In hold
         // mode `reenter` runs the body inline — the GVL is already held.
         super::gvl::reenter(|| {
             // 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 available here once the GVL is held.
+            // the active Sandbox invocation (#eval or #run), so `Ruby::get()`
+            // is available here once the GVL is held.
             // 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 ruby = Ruby::get().expect("Ruby handle unavailable in __kobako_upcall");
             let proc_value: Value = ruby.get_inner(self.on_dispatch);
             // The target crosses in one slot, already discriminated: a
             // String for a bound constant's path, an Integer for a Handle
@@ -180,34 +225,53 @@ impl DispatchHandler for RubyDispatchHandler {
             };
             // Hand the Proc a frame-scoped yielder object as its last 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 answer: Result<(bool, RString, Option<RString>), magnus::Error> = proc_value
-                .funcall(
-                    "call",
-                    (
-                        target,
-                        ruby.str_new(call.method),
-                        call.block_given,
-                        ruby.str_from_slice(call.payload),
-                        guest_yielder,
-                    ),
-                );
+            // escapes the dispatch frame never re-enters the guest.
+            let guest_yielder =
+                ruby.obj_wrap(GuestYielder::new(&ruby, yielder.frame(), self.open.clone()));
+            let answer: Result<(Symbol, RString, Option<RString>), magnus::Error> =
+                self.open.lend(yielder, || {
+                    proc_value.funcall(
+                        "call",
+                        (
+                            target,
+                            ruby.str_new(call.method),
+                            call.block_given,
+                            ruby.str_from_slice(call.payload),
+                            guest_yielder,
+                        ),
+                    )
+                });
             guest_yielder.invalidate();
+            // The Proc rescues only StandardError, so what else escapes it
+            // is the host's own and is held for the host; a StandardError
+            // escaping breaks the Proc's contract.
+            let (arm, body, kind) = match answer {
+                Ok(answer) => answer,
+                Err(error) => {
+                    let _ = super::escape::hold(&ruby, error);
+                    return None;
+                }
+            };
             // The ok arm carries payload bytes the codec owns; the fault
             // arm carries the Fault's own two fields, which the envelope
             // types — so Ruby names a category rather than encoding one.
-            // A category outside the closed set cannot come from the
-            // public API, so it fails the dispatch rather than degrading.
-            answer.ok().and_then(|(ok, body, kind)| match ok {
-                true => Some(Reply::Ok(super::rstring_to_vec(body))),
-                false => {
-                    let kind = FaultKind::from_name(&kind?.to_string().ok()?)?;
-                    Some(Reply::Fault(Fault::new(kind, body.to_string().ok()?)))
-                }
-            })
+            // A block exit carries nothing, since nothing of it crosses.
+            // An arm or category outside the closed set cannot come from
+            // the public API, so it fails the dispatch rather than
+            // degrading.
+            match arm.name().ok()?.as_ref() {
+                ARM_OK => Some(Reply::Ok(super::rstring_to_vec(body))),
+                ARM_BREAK => Some(Reply::Break),
+                ARM_FAULT => Some(Reply::Fault(Fault::new(
+                    FaultKind::from_name(&kind?.to_string().ok()?)?,
+                    body.to_string().ok()?,
+                ))),
+                _ => None,
+            }
         })
     }
+
+    fn abandoned(&self) -> bool {
+        super::escape::pending()
+    }
 }

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

@@ -13,12 +13,8 @@ use magnus::{prelude::*, Error as MagnusError, ExceptionClass, RModule, Ruby};
 
 use kobako_runtime::error::{InvokeError, SetupError, Trap};
 
-/// Resolve `Kobako::<name>` as an `ExceptionClass` — the shared body of
-/// every error-class `Lazy` below, which differ only in the constant
-/// name. The constants are guaranteed present by the time any of these
-/// lazies first resolve (`lib/kobako/errors.rb` loads the hierarchy before
-/// the ext raises into it), so a missing constant is a build / wiring bug
-/// and the `unwrap` is the correct fail-fast.
+/// `lib/kobako/errors.rb` loads the hierarchy before the ext raises into
+/// it, so a missing constant is a wiring bug and the `unwrap` fails fast.
 fn kobako_error_class(ruby: &Ruby, name: &str) -> ExceptionClass {
     let kobako: RModule = ruby.class_object().const_get("Kobako").unwrap();
     kobako.const_get(name).unwrap()
@@ -40,45 +36,46 @@ static MEMORY_LIMIT_ERROR: Lazy<ExceptionClass> =
 static SANDBOX_ERROR: Lazy<ExceptionClass> =
     Lazy::new(|ruby| kobako_error_class(ruby, "SandboxError"));
 
-/// Build a `MagnusError` in `class` carrying `msg` — the shared body of
-/// the named `*_err` constructors below, which differ only in which
-/// error-class `Lazy` they target.
 fn error_in(ruby: &Ruby, class: &Lazy<ExceptionClass>, msg: impl Into<String>) -> MagnusError {
     MagnusError::new(ruby.get_inner(class), msg.into())
 }
 
-/// Construct a `Kobako::TrapError` magnus error. Used for every
-/// invocation-time wasmtime engine failure that is not a configured-cap
-/// trap — missing exports, allocation faults, memory write/read failures.
-/// Construction-time setup failures use `setup_err`, not this.
+/// For an invocation-time engine failure that is not a configured cap;
+/// construction-time failures use `setup_to_magnus`.
 pub(super) fn trap_err(ruby: &Ruby, msg: impl Into<String>) -> MagnusError {
     error_in(ruby, &TRAP_ERROR, msg)
 }
 
-/// Map a neutral `Trap` onto its `Kobako::TrapError`-family Ruby exception.
-/// The boundary between the magnus-free run mechanics and the Ruby surface:
-/// the run path classifies a fault into a `Trap`, and this is where it
-/// becomes a raised exception. The verb prefix (`Sandbox#eval` / `#run`)
-/// is added by `Kobako::Sandbox#invoke!`.
-pub(super) fn trap_to_magnus(ruby: &Ruby, trap: Trap) -> MagnusError {
+/// The one place a trap meets the `Kobako::TrapError` family, whether it
+/// stopped the run before the guest started or while it ran.
+pub(super) fn trap_class(ruby: &Ruby, trap: &Trap) -> ExceptionClass {
     match trap {
-        Trap::Timeout(msg) => error_in(ruby, &TIMEOUT_ERROR, msg),
-        Trap::MemoryLimit(msg) => error_in(ruby, &MEMORY_LIMIT_ERROR, msg),
+        Trap::Timeout(_) => ruby.get_inner(&TIMEOUT_ERROR),
+        Trap::MemoryLimit(_) => ruby.get_inner(&MEMORY_LIMIT_ERROR),
         // A cap with no named subclass here is still an engine fault, so it
         // takes the base class rather than borrowing another cap's name.
-        other => trap_err(ruby, other.to_string()),
+        _ => ruby.get_inner(&TRAP_ERROR),
     }
 }
 
-/// Map a neutral `SetupError` onto the `Kobako::*` class the SPEC assigns
-/// to each runtime state — artifact-absent, runtime-dead, runtime-intact.
+/// The verb prefix is left to `Kobako::Context#invoke!`.
+pub(super) fn trap_to_magnus(ruby: &Ruby, trap: Trap) -> MagnusError {
+    MagnusError::new(trap_class(ruby, &trap), trap.to_string())
+}
+
 pub(super) fn setup_to_magnus(ruby: &Ruby, err: SetupError) -> MagnusError {
     match err {
-        SetupError::ModuleNotBuilt(msg) => error_in(ruby, &MODULE_NOT_BUILT_ERROR, msg),
+        // The engine serves every frontend, so the gem adds its own way to
+        // build the artifact.
+        SetupError::ModuleNotBuilt(msg) => error_in(
+            ruby,
+            &MODULE_NOT_BUILT_ERROR,
+            format!("{msg}; run `bundle exec rake wasm:build` to build it"),
+        ),
         SetupError::Dead(msg) => error_in(ruby, &SETUP_ERROR, msg),
-        // Runtime intact means a host-side pre-call fault the SPEC
-        // attributes to the sandbox / wire layer, not the engine — no
-        // discard-and-recreate recovery is owed, so never a TrapError.
+        // Runtime intact means a host-side pre-call fault attributed to
+        // the sandbox / wire layer: the engine never ran, so never a
+        // TrapError.
         SetupError::Intact(msg) => error_in(ruby, &SANDBOX_ERROR, msg),
         // An unrecognised state is one this frontend cannot promise is
         // recoverable, so it takes the same class as `Dead`.
@@ -86,14 +83,11 @@ pub(super) fn setup_to_magnus(ruby: &Ruby, err: SetupError) -> MagnusError {
     }
 }
 
-/// Map either run-path channel onto its Ruby exception. The single
-/// translation point the run-path entry methods funnel their `Result`
-/// through.
 pub(super) fn to_magnus(ruby: &Ruby, err: InvokeError) -> MagnusError {
     match err {
         InvokeError::Trap(trap) => trap_to_magnus(ruby, trap),
         InvokeError::Setup(err) => setup_to_magnus(ruby, err),
-        // A channel this frontend does not know is still a run that never
+        // A failure this frontend does not know is still a run that never
         // started, which the taxonomy attributes to the engine.
         other => trap_err(ruby, other.to_string()),
     }

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

@@ -0,0 +1,53 @@
+//! What a Host App's callback raises that is not a `StandardError`:
+//! `Interrupt`, `exit`, `throw`, `Timeout`. These belong to the host, so
+//! the callback holds one here instead of answering the guest with it,
+//! the invocation ends at its next host call, and the run raises it again
+//! once control is back in Ruby.
+//!
+//! The slot is per thread, as each invocation runs on its caller's
+//! thread. A nested invocation takes what its own run held before the
+//! outer callback sees it, so the outer one holds it next.
+
+use std::cell::RefCell;
+
+use magnus::value::BoxValue;
+use magnus::{Error as MagnusError, Ruby, Value};
+
+thread_local! {
+    static HELD: RefCell<Option<Held>> = const { RefCell::new(None) };
+}
+
+/// The error and, when it carries one, its exception kept rooted while
+/// the guest finishes unwinding.
+struct Held {
+    error: MagnusError,
+    _rooted: Option<BoxValue<Value>>,
+}
+
+/// Hold `error` unless it is a `StandardError`, which comes back for the
+/// callback to answer the guest with; the first one held wins.
+pub(super) fn hold(ruby: &Ruby, error: MagnusError) -> Result<(), MagnusError> {
+    if error.is_kind_of(ruby.exception_standard_error()) {
+        return Err(error);
+    }
+    HELD.with(|held| {
+        held.borrow_mut().get_or_insert_with(|| Held {
+            _rooted: error.value().map(BoxValue::new),
+            error,
+        });
+    });
+    Ok(())
+}
+
+/// Whether a callback on this thread holds an error for the host.
+pub(super) fn pending() -> bool {
+    HELD.with(|held| held.borrow().is_some())
+}
+
+/// Raise what a callback held, once the run is back in Ruby.
+pub(super) fn resume() -> Result<(), MagnusError> {
+    match HELD.with(|held| held.borrow_mut().take()) {
+        Some(held) => Err(held.error),
+        None => Ok(()),
+    }
+}

data/ext/kobako/src/runtime/filesystem/grants.rs

@@ -0,0 +1,91 @@
+//! A Sandbox's Mounts as contract Grants: refused at `mount` time and
+//! built afresh for every invocation by the same rules, each mount's
+//! block standing in for its access.
+
+use std::sync::Arc;
+
+use magnus::value::{Opaque, ReprValue};
+use magnus::{prelude::*, Error as MagnusError, RArray, RString, Ruby, Value};
+
+use kobako_runtime::filesystem::Access;
+use kobako_runtime::grant::Grant;
+use kobako_runtime::mount::{Mount, Policy};
+
+use super::{to_access, to_filesystem};
+use crate::runtime::pinned_value::PinnedValue;
+use crate::runtime::{escape, gvl};
+
+/// Refuse a Mount at `mount` time by the same rules an invocation builds
+/// it with, so a mistake raises where it was made.
+pub(in crate::runtime) fn validate_mount(
+    at: Value,
+    access: Value,
+    filesystem: Value,
+) -> Result<(), MagnusError> {
+    to_mount(at, access, filesystem).map(drop)
+}
+
+/// The Mount a Sandbox's `[at, access, filesystem]` stands for: one owner
+/// of the path, access, and Filesystem rules.
+fn to_mount(at: Value, access: Value, filesystem: Value) -> Result<Mount, MagnusError> {
+    let ruby = Ruby::get().expect("Ruby thread");
+    let at = RString::try_convert(at)?.to_string()?;
+    let access = to_access(access)?;
+    Mount::new(at, to_filesystem(filesystem)?, access)
+        .map_err(|err| MagnusError::new(ruby.exception_arg_error(), err.to_string()))
+}
+
+/// A mount's block, asked in its access's place. A block raising a
+/// StandardError refuses, so the guest's open fails and its script goes
+/// on; anything else it raises is held for the host.
+struct RubyPolicy {
+    block: Opaque<Value>,
+}
+
+impl Policy for RubyPolicy {
+    fn allows(&self, path: &str, access: Access) -> bool {
+        gvl::reenter(|| {
+            let ruby = Ruby::get().expect("Ruby handle unavailable in a mount's block");
+            let block: Value = ruby.get_inner(self.block);
+            let access = ruby.to_symbol(match access {
+                Access::Read => "read",
+                Access::ReadWrite => "read_write",
+            });
+            block
+                .funcall::<_, _, Value>("call", (ruby.str_new(path), access))
+                .map(|answer| answer.to_bool())
+                .unwrap_or_else(|error| {
+                    let _ = escape::hold(&ruby, error);
+                    false
+                })
+        })
+    }
+}
+
+/// The Grants one invocation carries, from the Sandbox's Mounts as
+/// `[at, access, filesystem, block]` entries, beside the pins keeping
+/// each Mount's filesystem and block in place while the guest may reach
+/// them; the caller holds both until the invocation returns.
+pub(in crate::runtime) fn to_grants(
+    ruby: &Ruby,
+    mounts: RArray,
+) -> Result<(Vec<Grant>, Vec<PinnedValue>), MagnusError> {
+    let mut grants = Vec::with_capacity(mounts.len());
+    let mut pins = Vec::with_capacity(mounts.len() * 2);
+    for index in 0..mounts.len() as isize {
+        let entry: RArray = mounts.entry(index)?;
+        let filesystem: Value = entry.entry(2)?;
+        pins.push(PinnedValue::new(ruby, filesystem));
+        let mount = to_mount(entry.entry(0)?, entry.entry(1)?, filesystem)?;
+        let block: Value = entry.entry(3)?;
+        grants.push(Grant::Mount(if block.is_nil() {
+            mount
+        } else {
+            pins.push(PinnedValue::new(ruby, block));
+            mount.with_policy(Arc::new(RubyPolicy {
+                block: Opaque::from(block),
+            }))
+        }));
+    }
+    Ok((grants, pins))
+}