kobako 0.27.0 → 0.28.0

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

@@ -5,17 +5,30 @@
 //! onto its own error surface, and hosts the epoch-deadline callback
 //! that raises the wall-clock `TimeoutTrap`. The classification is a
 //! pure function over the error's downcast chain so it can be exercised
-//! from `cargo test` without any frontend; the trap marker types
-//! themselves live in `crate::invocation` (where the limiter / callback
-//! construct them).
+//! from `cargo test` without any frontend.
 
 use std::time::Instant;
 
 use wasmtime::{StoreContextMut, UpdateDeadline};
 
-use crate::invocation::{Invocation, MemoryLimitTrap, TimeoutTrap};
+use crate::invocation::Invocation;
+use crate::limiter::MemoryLimitTrap;
 use kobako_runtime::error::{SetupError, Trap};
 
+/// Marker error returned from the epoch-deadline callback when the
+/// wall-clock deadline is exceeded. Downcast from the wasmtime trap
+/// error to classify the failure as a timeout `Trap`.
+#[derive(Debug)]
+pub(crate) struct TimeoutTrap;
+
+impl std::fmt::Display for TimeoutTrap {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(f, "wall-clock deadline exceeded")
+    }
+}
+
+impl std::error::Error for TimeoutTrap {}
+
 /// Epoch delta that keeps the deadline effectively unreachable when no
 /// wall-clock cap is configured. Half the epoch range rather than
 /// `u64::MAX`: wasmtime adds the delta to the engine's current epoch,
@@ -24,14 +37,9 @@ use kobako_runtime::error::{SetupError, Trap};
 /// overflow checks).
 pub(crate) const NO_TIMEOUT_EPOCH_DELTA: u64 = u64::MAX / 2;
 
-/// 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 the normal
-/// `Driver` invoke flow because
-/// `NO_TIMEOUT_EPOCH_DELTA` is primed; returning the same long
-/// extension keeps the callback inert as a defence in depth.
+/// With no deadline the primed `NO_TIMEOUT_EPOCH_DELTA` keeps this from
+/// firing; returning the same long extension keeps it inert as a defence
+/// in depth.
 pub(crate) fn epoch_deadline_callback(
     ctx: StoreContextMut<'_, Invocation>,
 ) -> wasmtime::Result<UpdateDeadline> {
@@ -42,22 +50,9 @@ pub(crate) fn epoch_deadline_callback(
     }
 }
 
-/// Classify a wasmtime call error into a neutral `Trap`. Pure function
-/// over the error's downcast chain, so the kind routing is exercisable
-/// from `cargo test` without any frontend. 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 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 would otherwise surface only the `"error while
-/// executing at wasm backtrace: ..."` framing, which is operator noise
-/// on a cap trap. For any other error the framing is kept but the
-/// chain's root cause is appended (see `other_trap_message`) so the
-/// real trap reason survives.
+/// The message leaves out the ABI export symbol, so the Sandbox layer can
+/// attach the caller's verb instead. A cap trap carries its own message,
+/// since wasmtime's backtrace framing is noise there.
 pub(crate) fn trap_from(err: wasmtime::Error) -> Trap {
     if let Some(t) = err.downcast_ref::<TimeoutTrap>() {
         Trap::Timeout(t.to_string())
@@ -68,13 +63,9 @@ pub(crate) fn trap_from(err: wasmtime::Error) -> Trap {
     }
 }
 
-/// Compose the message for a non-cap trap. wasmtime's `Display` surfaces only
-/// the `"error while executing at wasm backtrace: ..."` framing; the actual
-/// trap reason (e.g. `"wasm trap: indirect call type mismatch"`) is the
-/// chain's root cause and would otherwise be dropped, making real guest
-/// faults undiagnosable. Append the root cause unless the framing already
-/// carries it. Pure so it can be exercised from `cargo test` without the
-/// magnus surface.
+/// wasmtime's `Display` shows only the backtrace framing; the real trap
+/// reason is the chain's root cause and would otherwise be dropped, leaving
+/// a guest fault undiagnosable.
 fn other_trap_message(err: &wasmtime::Error) -> String {
     let display = format!("{}", err);
     let root = err.root_cause().to_string();
@@ -85,22 +76,18 @@ fn other_trap_message(err: &wasmtime::Error) -> String {
     }
 }
 
-/// Classify an instantiation error as a runtime-dead `SetupError`.
-/// Instantiation runs while the per-path template is built, before any
-/// invocation — every such failure is a construction setup fault, not a
-/// per-invocation cap outcome. Neither cap can fire there: the memory
-/// cap is dormant until an invocation arms it
-/// (`Invocation::arm_memory_cap`) and the probe Store names an epoch
-/// deadline it cannot reach, so the `trap_from` trap-class split does
-/// not apply here.
+/// The template is built before any invocation, so neither cap can fire:
+/// the memory cap is not yet armed and the probe Store's epoch deadline is
+/// out of reach. Every failure here is a setup fault, not a trap.
 pub(crate) fn instantiate_err(err: wasmtime::Error) -> SetupError {
     SetupError::Dead(format!("instantiate: {err}"))
 }
 
 #[cfg(test)]
 mod tests {
-    use super::{other_trap_message, trap_from, NO_TIMEOUT_EPOCH_DELTA};
-    use crate::invocation::{Invocation, MemoryLimitTrap, TimeoutTrap};
+    use super::{other_trap_message, trap_from, TimeoutTrap, NO_TIMEOUT_EPOCH_DELTA};
+    use crate::invocation::Invocation;
+    use crate::limiter::MemoryLimitTrap;
     use kobako_runtime::error::Trap;
 
     // The no-timeout priming delta is added to the engine's current

data/crates/kobako-wasmtime/tests/preamble_flags.rs

@@ -0,0 +1,69 @@
+//! The bundled guest recognises no flag, so every flag a host sets meets
+//! the unrecognised path: a critical one must refuse the invocation under
+//! its own class, and an advisory one must leave the run untouched.
+
+mod support;
+
+use kobako_runtime::{Completion, Entry, Runtime};
+use kobako_transport::envelope::{Flag, Origin, Outcome, Preamble};
+
+/// The Outcome and what the script printed, or `None` when the Guest
+/// Binary has not been built outside CI. The script prints before it
+/// answers, so empty stdout means it never ran.
+fn eval_with_flag(critical: bool) -> Option<(Outcome, Vec<u8>)> {
+    let driver = support::bundled_driver()?;
+    let mut preamble = Preamble::default();
+    preamble.flags = vec![Flag {
+        name: "no_such_flag".into(),
+        value: String::new(),
+        critical,
+    }];
+
+    let snapshot = driver
+        .invoke(
+            Entry::Eval {
+                source: b"puts 'ran'; 1 + 1",
+            },
+            &preamble,
+            None,
+        )
+        .expect("the invocation must start");
+    let Completion::Outcome(outcome) = snapshot.completion else {
+        panic!("the invocation must answer rather than trap");
+    };
+    Some((outcome, snapshot.stdout.bytes))
+}
+
+// @behavior MR-017
+#[test]
+fn a_critical_flag_the_guest_does_not_recognise_refuses_the_invocation() {
+    let Some((outcome, stdout)) = eval_with_flag(true) else {
+        return;
+    };
+    let Outcome::Panic(panic) = outcome else {
+        panic!("a critical flag the guest does not recognise must answer with a Panic");
+    };
+
+    assert_eq!(
+        (panic.origin, panic.error.name.as_str(), stdout.as_slice()),
+        (Origin::Sandbox, "Kobako::UnsupportedFlagError", &b""[..]),
+        "a critical flag the bundled guest does not recognise through Driver#invoke must \
+         refuse the invocation as the Sandbox's Kobako::UnsupportedFlagError before the \
+         script runs"
+    );
+}
+
+// @behavior MR-018
+#[test]
+fn an_advisory_flag_the_guest_does_not_recognise_is_skipped() {
+    let Some(answer) = eval_with_flag(false) else {
+        return;
+    };
+
+    assert_eq!(
+        answer,
+        (Outcome::Ok(vec![0x02]), b"ran\n".to_vec()),
+        "an advisory flag the bundled guest does not recognise through Driver#invoke must be \
+         skipped, leaving the invocation's value as it would be without the flag"
+    );
+}

data/crates/kobako-wasmtime/tests/snippet_compile.rs

@@ -0,0 +1,94 @@
+//! The bundled guest compiles a Preamble's source snippets on an instance
+//! of their own. What comes back has to replay in a later invocation in
+//! place of the source, under the same flags a replay would apply, and
+//! two compiles of the same Preamble have to agree byte for byte so
+//! either can stand in for the other.
+
+mod support;
+
+use kobako_runtime::{Completion, Entry, Runtime};
+use kobako_transport::envelope::{Flag, Outcome, Preamble, Snippet, Snippets};
+
+use support::bundled_driver as driver;
+
+fn preamble_of(entries: Vec<Snippet>) -> Preamble {
+    let mut preamble = Preamble::default();
+    preamble.snippets = Snippets { entries };
+    preamble
+}
+
+fn greeter() -> Preamble {
+    preamble_of(vec![Snippet::Source {
+        name: "Greeter".into(),
+        body: "module Greeter; def self.hi = 'hi'; end".into(),
+    }])
+}
+
+// @behavior MR-024
+#[test]
+fn compiled_snippets_replay_in_a_later_invocation() {
+    let Some(driver) = driver() else {
+        return;
+    };
+    let bytecodes = driver
+        .compile(&greeter())
+        .expect("a source snippet that parses must compile");
+    let replay = preamble_of(
+        bytecodes
+            .into_iter()
+            .map(|body| Snippet::Bytecode { body })
+            .collect(),
+    );
+
+    let snapshot = driver
+        .invoke(
+            Entry::Eval {
+                source: b"Greeter.hi",
+            },
+            &replay,
+            None,
+        )
+        .expect("the invocation must start");
+
+    assert!(
+        matches!(snapshot.completion, Completion::Outcome(Outcome::Ok(ref value)) if value == b"\xa2hi"),
+        "bytecode from Driver#compile, sent back as bytecode snippets, must define what the \
+         source did for a later invocation"
+    );
+}
+
+// @behavior MR-023
+#[test]
+fn compiling_the_same_preamble_twice_yields_the_same_bytes() {
+    let Some(driver) = driver() else {
+        return;
+    };
+
+    assert_eq!(
+        driver.compile(&greeter()),
+        driver.compile(&greeter()),
+        "the same Preamble through Driver#compile on two fresh instances must answer \
+         byte-identical bytecode"
+    );
+}
+
+// @behavior MR-025
+#[test]
+fn a_critical_flag_the_guest_does_not_recognise_leaves_nothing_compiled() {
+    let Some(driver) = driver() else {
+        return;
+    };
+    let mut preamble = greeter();
+    preamble.flags = vec![Flag {
+        name: "no_such_flag".into(),
+        value: String::new(),
+        critical: true,
+    }];
+
+    assert_eq!(
+        driver.compile(&preamble),
+        None,
+        "a critical flag the bundled guest does not recognise through Driver#compile must \
+         leave nothing compiled, since compiling applies the flags a replay would"
+    );
+}

data/crates/kobako-wasmtime/tests/support/mod.rs

@@ -0,0 +1,34 @@
+//! The bundled Guest Binary every integration test drives.
+
+use std::path::Path;
+use std::time::Duration;
+
+use kobako_runtime::Profile;
+use kobako_wasmtime::{Config, Driver};
+
+const WASM: &str = concat!(env!("CARGO_MANIFEST_DIR"), "/../../data/kobako.wasm");
+
+/// A driver over the bundled Guest Binary, or `None` when it has not
+/// been built outside CI, where a missing build is a failure instead.
+pub fn bundled_driver() -> Option<Driver> {
+    if !Path::new(WASM).exists() {
+        assert!(
+            std::env::var_os("CI").is_none(),
+            "data/kobako.wasm missing under CI — run `bundle exec rake wasm:build`"
+        );
+        return None;
+    }
+    Some(
+        Driver::new(
+            Path::new(WASM),
+            Config {
+                timeout: Some(Duration::from_secs(10)),
+                memory_limit: None,
+                stdout_limit: None,
+                stderr_limit: None,
+                profile: Profile::Hermetic,
+            },
+        )
+        .expect("the Guest Binary must load"),
+    )
+}

data/crates/kobako-wasmtime/tests/unsupported_call.rs

@@ -0,0 +1,50 @@
+//! A host frontend of its own may answer a guest's Call as unsupported;
+//! the bundled guest must then hand its script a refusal it can rescue,
+//! rather than a broken exchange. The default frontends serve every Call,
+//! so only a handler written here reaches that answer.
+
+mod support;
+
+use std::sync::Arc;
+
+use kobako_runtime::{Completion, DispatchHandler, Entry, Runtime, Yielder};
+use kobako_transport::envelope::{Bindings, Call, Outcome, Preamble, Reply, Unsupported};
+
+struct ServesNoCall;
+
+impl DispatchHandler for ServesNoCall {
+    fn dispatch(&self, _call: Call<'_>, _yielder: &mut dyn Yielder) -> Option<Reply> {
+        Some(Reply::Unsupported(Unsupported::new("no calls here")))
+    }
+}
+
+// @behavior T-279
+#[test]
+fn a_call_the_host_does_not_serve_raises_unsupported_error_in_the_guest() {
+    let Some(driver) = support::bundled_driver() else {
+        return;
+    };
+    let mut preamble = Preamble::default();
+    preamble.bindings = Bindings {
+        paths: vec!["Svc".into()],
+    };
+    let source = b"begin; Svc.go; rescue Kobako::UnsupportedError => e; e.message; end";
+
+    let snapshot = driver
+        .invoke(
+            Entry::Eval { source },
+            &preamble,
+            Some(Arc::new(ServesNoCall)),
+        )
+        .expect("the invocation must start");
+
+    let Completion::Outcome(outcome) = snapshot.completion else {
+        panic!("the invocation must answer rather than trap");
+    };
+    assert_eq!(
+        outcome,
+        Outcome::Ok(b"\xadno calls here".to_vec()),
+        "a Service call answered as unsupported through Driver#invoke must raise \
+         Kobako::UnsupportedError carrying the host's message"
+    );
+}

data/ext/kobako/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "kobako"
-version = "0.27.0"
+version = "0.28.0"
 edition = "2021"
 authors = ["Aotokitsuruya <contact@aotoki.me>"]
 license = "Apache-2.0"
@@ -10,7 +10,7 @@ publish = false
 crate-type = ["cdylib"]
 
 [dependencies]
-magnus = { version = "0.8.2", features = ["rb-sys"] }
+magnus = { version = "0.9.2", features = ["rb-sys"] }
 # Raw Ruby FFI for the GVL release/re-acquire calls magnus does not wrap
 # (`rb_thread_call_without_gvl` / `rb_thread_call_with_gvl`). Pinned to the
 # rb-sys magnus resolves so both share one binding instance.

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

@@ -22,10 +22,10 @@ use kobako_transport::envelope::{Call, Fault, FaultKind, Reply, Target, YieldRep
 const ARM_OK: &str = "ok";
 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.
+/// Runs 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())?;
@@ -35,7 +35,7 @@ pub(super) fn register(runtime_class: RClass) -> Result<(), MagnusError> {
 
 /// 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
+/// for exactly one `__kobako_upcall` 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
@@ -56,9 +56,9 @@ struct GuestYielder {
 }
 
 // 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.
+// is created, used, and invalidated within a single `__kobako_upcall`
+// frame on the one Ruby thread that owns the active Invocation; it is
+// never read from another thread.
 unsafe impl Send for GuestYielder {}
 unsafe impl Sync for GuestYielder {}
 
@@ -80,24 +80,17 @@ impl GuestYielder {
         }
     }
 
-    /// 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 dereferencing freed
+    /// stack.
     fn invalidate(&self) {
         self.yielder.set(None);
     }
 
-    /// 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 ruby = Ruby::get().expect("Ruby handle unavailable in the block bridge");
         let Some(mut ptr) = self.yielder.get() else {
             return Err(super::errors::trap_err(
                 &ruby,
@@ -107,26 +100,31 @@ impl GuestYielder {
         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.
+        // Rust stack, and each dispatch frame lends its own Yielder on the
+        // one thread driving the invocation, so no other frame aliases it.
+        // The borrow ends with this method.
         let yielder: &mut dyn Yielder = unsafe { ptr.as_mut() };
-        let resp = yielder
+        let reply = yielder
             .yield_to_block(&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(match reply {
+            YieldReply::Ok(body) => (ruby.to_symbol(ARM_OK), ruby.str_from_slice(&body), None),
+            YieldReply::Break(body) => {
+                (ruby.to_symbol(ARM_BREAK), 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((
+            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,
+            ),
+        })
     }
 }
 
@@ -147,28 +145,21 @@ impl RubyDispatchHandler {
 }
 
 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 dispatch failure into the Reply's
+    /// fault arm, so a raise 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

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()),
     }