kobako 0.13.0 → 0.15.0

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

@@ -18,15 +18,19 @@ pub(crate) fn pipe_capacity(cap: Option<usize>) -> usize {
     }
 }
 
-/// 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(crate) fn clip_capture(raw: &[u8], cap: Option<usize>) -> (&[u8], bool) {
+/// Pure clipping core shared by the snapshot readback: given the
+/// unclipped pipe snapshot (owned — truncated in place, so the readback
+/// costs one copy out of the pipe, not two), return the bytes Ruby
+/// should observe 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(crate) fn clip_capture(mut raw: Vec<u8>, cap: Option<usize>) -> (Vec<u8>, bool) {
     match cap {
-        Some(c) if raw.len() > c => (&raw[..c], true),
+        Some(c) if raw.len() > c => {
+            raw.truncate(c);
+            (raw, true)
+        }
         _ => (raw, false),
     }
 }
@@ -53,14 +57,14 @@ mod tests {
 
     #[test]
     fn clip_capture_returns_full_bytes_when_under_cap() {
-        let (bytes, truncated) = clip_capture(b"abc", Some(5));
+        let (bytes, truncated) = clip_capture(b"abc".to_vec(), 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));
+        let (bytes, truncated) = clip_capture(b"abcde".to_vec(), Some(5));
         assert_eq!(bytes, b"abcde");
         assert!(!truncated);
     }
@@ -70,21 +74,21 @@ mod tests {
         // 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));
+        let (bytes, truncated) = clip_capture(b"abcdef".to_vec(), 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);
+        let (bytes, truncated) = clip_capture(b"abcdef".to_vec(), None);
         assert_eq!(bytes, b"abcdef");
         assert!(!truncated);
     }
 
     #[test]
     fn clip_capture_handles_empty_input() {
-        let (bytes, truncated) = clip_capture(b"", Some(5));
+        let (bytes, truncated) = clip_capture(Vec::new(), Some(5));
         assert_eq!(bytes, b"");
         assert!(!truncated);
     }

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

@@ -183,7 +183,7 @@ impl Driver {
             }
             None => {
                 store.data_mut().set_deadline(None);
-                store.set_epoch_deadline(u64::MAX);
+                store.set_epoch_deadline(trap::NO_TIMEOUT_EPOCH_DELTA);
             }
         }
         let baseline = match exports.memory {
@@ -203,19 +203,18 @@ impl Driver {
             wall_time: data.wall_time().as_secs_f64(),
             memory_peak: data.memory_peak(),
         };
-        let (stdout_raw, stderr_raw) = (data.stdout_bytes(), data.stderr_bytes());
-        let (stdout_visible, stdout_truncated) =
-            capture::clip_capture(&stdout_raw, self.config.stdout_limit_bytes);
-        let (stderr_visible, stderr_truncated) =
-            capture::clip_capture(&stderr_raw, self.config.stderr_limit_bytes);
+        let (stdout_bytes, stdout_truncated) =
+            capture::clip_capture(data.stdout_bytes(), self.config.stdout_limit_bytes);
+        let (stderr_bytes, stderr_truncated) =
+            capture::clip_capture(data.stderr_bytes(), self.config.stderr_limit_bytes);
         Snapshot {
             completion,
             stdout: Capture {
-                bytes: stdout_visible.to_vec(),
+                bytes: stdout_bytes,
                 truncated: stdout_truncated,
             },
             stderr: Capture {
-                bytes: stderr_visible.to_vec(),
+                bytes: stderr_bytes,
                 truncated: stderr_truncated,
             },
             usage,

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

@@ -18,11 +18,11 @@ use kobako_runtime::profile::Profile;
 
 /// Return the resolved `memory` export handle, or a `Trap` when the loaded
 /// module exports no linear memory — the "not a Kobako-shaped runtime"
-/// failure mode (`SANDBOX_RUNTIME_NOT_KOBAKO`).
+/// failure mode (`guest_mem::SANDBOX_RUNTIME_NOT_KOBAKO`).
 fn require_memory(exports: &Exports) -> Result<Memory, Trap> {
     exports
         .memory
-        .ok_or_else(|| Trap::Other(SANDBOX_RUNTIME_NOT_KOBAKO.to_string()))
+        .ok_or_else(|| Trap::Other(guest_mem::SANDBOX_RUNTIME_NOT_KOBAKO.to_string()))
 }
 
 /// Allocate a `len`-byte buffer in guest linear memory via
@@ -160,13 +160,6 @@ pub(crate) fn fetch_outcome_bytes(
 const SANDBOX_RUNTIME_MISSING_HOOKS: &str = "Sandbox runtime is missing required hooks; \
      rebuild data/kobako.wasm against the installed version";
 
-/// User-facing message for the "the loaded Wasm module is not a
-/// Kobako-shaped runtime at all" failure mode (no linear memory
-/// export). Same phrasing philosophy as
-/// `SANDBOX_RUNTIME_MISSING_HOOKS`.
-const SANDBOX_RUNTIME_NOT_KOBAKO: &str =
-    "the loaded Wasm module is not a Kobako-compatible runtime";
-
 /// Return the resolved `TypedFunc` for an ABI export, or a `Trap`
 /// (boundary → `Kobako::TrapError`) when the option is `None`. Both
 /// run-path methods (`#eval`, `#run`) plus the `build_snapshot` readout
@@ -225,7 +218,7 @@ mod tests {
             profile,
         };
         let mut store = WtStore::new(engine, Invocation::new(None));
-        store.set_epoch_deadline(u64::MAX);
+        store.set_epoch_deadline(crate::trap::NO_TIMEOUT_EPOCH_DELTA);
         install_wasi_frames(&mut store, &config, &[]).expect("WASI context must install");
 
         let mut linker: Linker<Invocation> = Linker::new(engine);

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

@@ -44,6 +44,13 @@ impl Yielder for CallerYielder<'_, '_> {
 const RUNTIME_INCOMPATIBLE: &str =
     "the Sandbox runtime is incompatible; rebuild data/kobako.wasm against the installed version";
 
+/// User-facing message for the "the loaded Wasm module is not a
+/// Kobako-shaped runtime at all" failure mode — no linear memory export
+/// here, no `memory` module export on the instantiation path in
+/// `frames`. One constant so the two detection sites cannot drift.
+pub(crate) const SANDBOX_RUNTIME_NOT_KOBAKO: &str =
+    "the loaded Wasm module is not a Kobako-compatible runtime";
+
 /// Resolve the guest's exported linear `memory`. The lookup shape (and its
 /// diagnostic) is shared by every Caller-based path here — the write side
 /// (`alloc_and_write`), the read side (`read`), and the yield round-trip
@@ -52,7 +59,7 @@ const RUNTIME_INCOMPATIBLE: &str =
 fn memory_export(caller: &mut Caller<'_, Invocation>) -> Result<Memory, &'static str> {
     match caller.get_export("memory") {
         Some(Extern::Memory(m)) => Ok(m),
-        _ => Err("the loaded Wasm module is not a Kobako-compatible runtime"),
+        _ => Err(SANDBOX_RUNTIME_NOT_KOBAKO),
     }
 }
 

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

@@ -70,12 +70,13 @@ fn build_linker() -> Result<Linker<Invocation>, SetupError> {
     // `__kobako_dispatch` host import. Signature per docs/wire-codec.md
     // § ABI Signatures:
     //   (req_ptr: i32, req_len: i32) -> i64
-    // Decodes the Request bytes, dispatches via the Ruby-side
-    // dispatch Proc (bound per-Sandbox through `Runtime#on_dispatch=`),
-    // allocates a guest buffer through `__kobako_alloc`, writes
-    // the Response bytes there, and returns the packed
-    // `(ptr<<32)|len`. The dispatcher returns 0 on any wire-layer
-    // fault (including no Proc bound); see `dispatch::handle`.
+    // Reads the Request bytes from guest memory and hands them —
+    // undecoded — to the bound `DispatchHandler` (the frontend's
+    // dispatch bridge, e.g. a Ruby Proc), then allocates a guest
+    // buffer through `__kobako_alloc`, writes the handler's Response
+    // bytes there, and returns the packed `(ptr<<32)|len`. The
+    // dispatcher returns 0 on any wire-layer fault (including no
+    // handler bound); see `dispatch::handle`.
     linker
         .func_wrap(
             "env",

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

@@ -318,10 +318,9 @@ impl ResourceLimiter for MemoryLimiter {
 
 /// Marker error returned from `MemoryLimiter::memory_growing` when the
 /// per-invocation memory cap is exceeded. Downcast from the wasmtime
-/// trap error to surface as
-/// `Kobako::MemoryLimitError` on the Ruby side. Callers use the
-/// `Display` impl below — no field is read directly — so the inner
-/// state stays private.
+/// trap error to classify the failure as a memory-limit `Trap`. Callers
+/// use the `Display` impl below — no field is read directly — so the
+/// inner state stays private.
 #[derive(Debug)]
 pub(crate) struct MemoryLimitTrap {
     desired: usize,
@@ -354,7 +353,7 @@ impl std::error::Error for MemoryLimitTrap {}
 
 /// Marker error returned from the epoch-deadline callback when the
 /// wall-clock deadline is exceeded. Downcast from the wasmtime trap
-/// error to surface as `Kobako::TimeoutError` on the Ruby side.
+/// error to classify the failure as a timeout `Trap`.
 #[derive(Debug)]
 pub(crate) struct TimeoutTrap;
 

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

@@ -1,12 +1,13 @@
 //! Trap classification for the run path.
 //!
-//! Maps a `wasmtime` run error to the right top-level `Kobako::*` Ruby
-//! exception (`TimeoutError` / `MemoryLimitError` / `TrapError`), 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 the
-//! magnus surface; the trap marker types themselves live in
-//! `crate::invocation` (where the limiter / callback construct them).
+//! Classifies a `wasmtime` run error into the engine-neutral `Trap`
+//! kind (`Timeout` / `MemoryLimit` / `Other`) that each frontend maps
+//! 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).
 
 use std::time::Instant;
 
@@ -15,81 +16,55 @@ use wasmtime::{StoreContextMut, UpdateDeadline};
 use crate::invocation::{Invocation, MemoryLimitTrap, TimeoutTrap};
 use kobako_runtime::error::{SetupError, Trap};
 
+/// 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,
+/// which the process-wide ticker advances for the engine's whole
+/// lifetime, so the full range overflows the sum (a panic under debug
+/// 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
-/// `set_epoch_deadline(u64::MAX)` is used; returning a long extension
-/// keeps the callback inert as a defence in depth.
+/// `NO_TIMEOUT_EPOCH_DELTA` is primed; returning the same long
+/// extension keeps the callback inert as a defence in depth.
 pub(crate) fn epoch_deadline_callback(
     ctx: StoreContextMut<'_, Invocation>,
 ) -> wasmtime::Result<UpdateDeadline> {
     match ctx.data().deadline() {
         Some(deadline) if Instant::now() >= deadline => Err(wasmtime::Error::new(TimeoutTrap)),
         Some(_) => Ok(UpdateDeadline::Continue(1)),
-        None => Ok(UpdateDeadline::Continue(u64::MAX / 2)),
+        None => Ok(UpdateDeadline::Continue(NO_TIMEOUT_EPOCH_DELTA)),
     }
 }
 
-/// Configured-cap path classification for a wasmtime error. The
-/// downcast logic stays in a pure helper so the
-/// `Kobako::TimeoutError` / `MemoryLimitError` /
-/// `Kobako::TrapError` mapping can be exercised from `cargo test`
-/// without the magnus surface.
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-enum TrapClass {
-    /// Wall-clock cap path.
-    Timeout,
-    /// Linear-memory cap path.
-    MemoryLimit,
-    /// Any other wasmtime error — surfaces as the base
-    /// `Kobako::TrapError`.
-    Other,
-}
-
-/// Inspect a wasmtime error to decide which top-level `Kobako::*` trap
-/// class it should map to. Pure function — operates on the error's
-/// downcast chain only, no magnus / Ruby state required.
-fn classify_trap(err: &wasmtime::Error) -> TrapClass {
-    if err.downcast_ref::<TimeoutTrap>().is_some() {
-        TrapClass::Timeout
-    } else if err.downcast_ref::<MemoryLimitTrap>().is_some() {
-        TrapClass::MemoryLimit
-    } else {
-        TrapClass::Other
-    }
-}
-
-/// 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
+/// 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 (`TrapClass::Timeout` /
-/// `TrapClass::MemoryLimit`) the trap's own `std::fmt::Display`
+/// 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 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.
+/// `"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.
 pub(crate) fn trap_from(err: wasmtime::Error) -> Trap {
-    match classify_trap(&err) {
-        TrapClass::Timeout => Trap::Timeout(
-            err.downcast_ref::<TimeoutTrap>()
-                .map(|t| t.to_string())
-                .unwrap_or_else(|| format!("{err}")),
-        ),
-        TrapClass::MemoryLimit => Trap::MemoryLimit(
-            err.downcast_ref::<MemoryLimitTrap>()
-                .map(|t| t.to_string())
-                .unwrap_or_else(|| format!("{err}")),
-        ),
-        TrapClass::Other => Trap::Other(other_trap_message(&err)),
+    if let Some(t) = err.downcast_ref::<TimeoutTrap>() {
+        Trap::Timeout(t.to_string())
+    } else if let Some(t) = err.downcast_ref::<MemoryLimitTrap>() {
+        Trap::MemoryLimit(t.to_string())
+    } else {
+        Trap::Other(other_trap_message(&err))
     }
 }
 
@@ -123,25 +98,44 @@ pub(crate) fn instantiate_err(err: wasmtime::Error) -> SetupError {
 
 #[cfg(test)]
 mod tests {
-    use super::{classify_trap, other_trap_message, TrapClass};
-    use crate::invocation::{MemoryLimitTrap, TimeoutTrap};
+    use super::{other_trap_message, trap_from, NO_TIMEOUT_EPOCH_DELTA};
+    use crate::invocation::{Invocation, MemoryLimitTrap, TimeoutTrap};
+    use kobako_runtime::error::Trap;
+
+    // The no-timeout priming delta is added to the engine's current
+    // epoch inside wasmtime, and the process-wide ticker advances that
+    // epoch from the first `shared_engine` call on — so the sum must
+    // stay in range for a long-lived engine, not just a fresh one.
+    // `increment_epoch` stands in for the ticker to make the ticked
+    // state deterministic; under debug overflow checks an overflowing
+    // delta panics right here.
+    #[test]
+    fn no_timeout_delta_survives_a_ticked_engine_epoch() {
+        let engine = crate::cache::shared_engine().expect("shared engine must be constructible");
+        engine.increment_epoch();
+        let mut store = wasmtime::Store::new(engine, Invocation::new(None));
+        store.set_epoch_deadline(NO_TIMEOUT_EPOCH_DELTA);
+    }
 
     #[test]
-    fn classify_trap_routes_timeout_trap_to_timeout() {
+    fn trap_from_routes_timeout_trap_to_timeout() {
         let err = wasmtime::Error::new(TimeoutTrap);
-        assert_eq!(classify_trap(&err), TrapClass::Timeout);
+        let expected = TimeoutTrap.to_string();
+        assert!(matches!(trap_from(err), Trap::Timeout(msg) if msg == expected));
     }
 
     #[test]
-    fn classify_trap_routes_memory_limit_trap_to_memory_limit() {
-        let err = wasmtime::Error::new(MemoryLimitTrap::new(1 << 20, 1 << 19));
-        assert_eq!(classify_trap(&err), TrapClass::MemoryLimit);
+    fn trap_from_routes_memory_limit_trap_to_memory_limit() {
+        let trap = MemoryLimitTrap::new(1 << 20, 1 << 19);
+        let expected = trap.to_string();
+        let err = wasmtime::Error::new(trap);
+        assert!(matches!(trap_from(err), Trap::MemoryLimit(msg) if msg == expected));
     }
 
     #[test]
-    fn classify_trap_falls_back_to_other_for_unknown_errors() {
+    fn trap_from_falls_back_to_other_for_unknown_errors() {
         let err = wasmtime::Error::msg("some other wasmtime fault");
-        assert_eq!(classify_trap(&err), TrapClass::Other);
+        assert!(matches!(trap_from(err), Trap::Other(_)));
     }
 
     // A guest hard trap reaches the host as a wasmtime error whose Display is

data/ext/kobako/Cargo.toml

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

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

@@ -55,48 +55,15 @@ pub(super) fn trap_err(ruby: &Ruby, msg: impl Into<String>) -> MagnusError {
     error_in(ruby, &TRAP_ERROR, msg)
 }
 
-/// Construct a `Kobako::SetupError` magnus error. Used for every
-/// construction-time failure on the `Runtime.from_path` path before any
-/// invocation runs — unreadable artifact, bytes that are not a valid Wasm
-/// module, or engine / linker / instantiation setup failure. The
-/// `ModuleNotBuiltError` subclass (artifact absent) is
-/// raised through `MODULE_NOT_BUILT_ERROR` directly.
-pub(super) fn setup_err(ruby: &Ruby, msg: impl Into<String>) -> MagnusError {
-    error_in(ruby, &SETUP_ERROR, msg)
-}
-
-/// Construct a `Kobako::TimeoutError` magnus error. Surfaces the
-/// wall-clock cap path with the verb prefix added
-/// by `Kobako::Sandbox#invoke!`.
-fn timeout_err(ruby: &Ruby, msg: impl Into<String>) -> MagnusError {
-    error_in(ruby, &TIMEOUT_ERROR, msg)
-}
-
-/// Construct a `Kobako::MemoryLimitError` magnus error. Surfaces the
-/// linear-memory cap path with the verb prefix
-/// added by `Kobako::Sandbox#invoke!`.
-fn memory_limit_err(ruby: &Ruby, msg: impl Into<String>) -> MagnusError {
-    error_in(ruby, &MEMORY_LIMIT_ERROR, msg)
-}
-
-/// Construct a `Kobako::SandboxError` magnus error. Used for the
-/// host-side pre-call faults the SPEC attributes to the sandbox / wire
-/// layer rather than the Wasm engine — currently the `#run` invocation
-/// envelope reservation failure (`__kobako_alloc` returns 0).
-/// The runtime is intact, so this must not be a
-/// `TrapError`: no discard-and-recreate recovery is owed to the caller.
-fn sandbox_err(ruby: &Ruby, msg: impl Into<String>) -> MagnusError {
-    error_in(ruby, &SANDBOX_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.
+/// 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 {
     match trap {
-        Trap::Timeout(msg) => timeout_err(ruby, msg),
-        Trap::MemoryLimit(msg) => memory_limit_err(ruby, msg),
+        Trap::Timeout(msg) => error_in(ruby, &TIMEOUT_ERROR, msg),
+        Trap::MemoryLimit(msg) => error_in(ruby, &MEMORY_LIMIT_ERROR, msg),
         Trap::Other(msg) => trap_err(ruby, msg),
     }
 }
@@ -106,8 +73,11 @@ pub(super) fn trap_to_magnus(ruby: &Ruby, trap: Trap) -> MagnusError {
 pub(super) fn setup_to_magnus(ruby: &Ruby, err: SetupError) -> MagnusError {
     match err {
         SetupError::ModuleNotBuilt(msg) => error_in(ruby, &MODULE_NOT_BUILT_ERROR, msg),
-        SetupError::Dead(msg) => setup_err(ruby, msg),
-        SetupError::Intact(msg) => sandbox_err(ruby, msg),
+        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.
+        SetupError::Intact(msg) => error_in(ruby, &SANDBOX_ERROR, msg),
     }
 }
 

data/ext/kobako/src/runtime.rs

@@ -53,26 +53,14 @@ fn rstring_to_vec(s: RString) -> Vec<u8> {
     unsafe { s.as_slice() }.to_vec()
 }
 
-/// The pre-invocation sentinel for one capture channel: no bytes, cap
-/// not reached. Fresh `Vec`s per call because `Capture` owns its buffer.
-fn empty_capture() -> Capture {
-    Capture {
-        bytes: Vec::new(),
-        truncated: false,
-    }
-}
-
 // ---------------------------------------------------------------------------
 // Ruby init
 // ---------------------------------------------------------------------------
 
 pub fn init(ruby: &Ruby, kobako: RModule) -> Result<(), MagnusError> {
-    // Error hierarchy lives in `lib/kobako/errors.rb` (top-level
-    // `Kobako::TrapError` / `TimeoutError` / `MemoryLimitError` /
-    // `SetupError` / `ModuleNotBuiltError`). The ext raises directly into
-    // those classes through `trap_err` / `timeout_err` / `memory_limit_err`
-    // / `sandbox_err` / `setup_err` / `MODULE_NOT_BUILT_ERROR`; no
-    // intermediate hierarchy is registered.
+    // Error hierarchy lives in `lib/kobako/errors.rb`; the ext raises
+    // directly into those classes through the constructors and mappers
+    // in `runtime/errors.rs` — no intermediate hierarchy is registered.
 
     let runtime = kobako.define_class("Runtime", ruby.class_object())?;
     runtime.define_singleton_method("from_path", function!(Runtime::from_path, 6))?;
@@ -210,11 +198,8 @@ impl Runtime {
         Ok(Self {
             driver,
             on_dispatch: Cell::new(None),
-            last_usage: Cell::new(Usage {
-                wall_time: 0.0,
-                memory_peak: 0,
-            }),
-            last_captures: RefCell::new((empty_capture(), empty_capture())),
+            last_usage: Cell::new(Usage::default()),
+            last_captures: RefCell::new((Capture::default(), Capture::default())),
         })
     }
 

data/lib/kobako/catalog/handles.rb

@@ -6,7 +6,7 @@ module Kobako
   module Catalog
     # Host-side mapping from opaque integer Handle IDs to Ruby objects.
     # The table is owned by +Kobako::Sandbox+ and injected
-    # into the per-Sandbox +Kobako::Catalog::Namespaces+ so guest→host dispatch
+    # into the per-Sandbox +Kobako::Catalog::Services+ so guest→host dispatch
     # resolves Handle targets and arguments against the same table that
     # host→guest wire encoding allocates into.
     #
@@ -95,7 +95,7 @@ module Kobako
         end
       end
 
-      # Guard {#alloc} against issuing an ID past the cap. Returns +nil+
+      # Guard #alloc against issuing an ID past the cap. Returns +nil+
       # on success; raises +Kobako::HandleExhaustedError+ at exhaustion.
       def ensure_capacity!
         cap = Kobako::Handle::MAX_ID
@@ -107,7 +107,7 @@ module Kobako
       end
 
       # Single source of truth for the "unknown Handle id" raise used by
-      # {#fetch}. Returns +nil+ on success; raises +Kobako::SandboxError+
+      # #fetch. Returns +nil+ on success; raises +Kobako::SandboxError+
       # when +id+ is not currently bound.
       def require_bound!(id)
         return if @entries.key?(id)