kobako 0.4.0 → 0.5.0

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

@@ -1,20 +1,24 @@
-//! Per-Store host state shared with every wasmtime callback.
+//! 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).
 //!
-//! Owned by [`StoreCell`] (a `RefCell` shim wrapping `wasmtime::Store`)
+//! Owned by `StoreCell` (a `RefCell` shim wrapping `wasmtime::Store`)
 //! and threaded through every host import — the `__kobako_dispatch`
-//! dispatcher reads the server handle, while the run-path methods on
-//! [`crate::wasm::Instance`] install fresh WASI context + pipes before
-//! every `#run` (docs/behavior.md B-03 / B-04).
+//! dispatcher reads the bound dispatch Proc, while the run-path methods
+//! on `crate::runtime::Runtime` install fresh WASI context + pipes
+//! before every invocation (docs/behavior.md B-03 / B-04).
 //!
-//! The state also carries the per-invocation wall-clock deadline
+//! The slot also carries the per-invocation wall-clock deadline
 //! (docs/behavior.md B-01, E-19) and the per-invocation linear-memory
-//! delta cap [`KobakoLimiter`] (docs/behavior.md B-01, E-20). Both are
+//! delta cap `MemoryLimiter` (docs/behavior.md B-01, E-20). Both are
 //! read from the wasmtime `epoch_deadline_callback` / `ResourceLimiter`
-//! callbacks installed in [`crate::wasm::Instance::from_path`]. The
+//! callbacks installed in `crate::runtime::Runtime::from_path`. The
 //! memory cap measures only the `memory.grow` delta past the linear-
 //! memory size captured at invocation entry — the mruby image's
 //! initial allocation and prior invocations' watermark are outside the
 //! budget.
+//!
+//! [SPEC.md Single-Invocation Slot]: ../../../SPEC.md
 
 use std::cell::{Ref, RefCell, RefMut};
 use std::time::{Duration, Instant};
@@ -24,46 +28,48 @@ use wasmtime::{ResourceLimiter, Store as WtStore};
 use wasmtime_wasi::p1::WasiP1Ctx;
 use wasmtime_wasi::p2::pipe::MemoryOutputPipe;
 
-/// Per-Store host state threaded through every host import callback.
+/// 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 `#run` via [`HostState::install_wasi`], the
-/// Ruby Server handle is set once via [`HostState::bind_server`], and
-/// captured stdout/stderr bytes are read after the run via
-/// [`HostState::stdout_bytes`] / [`HostState::stderr_bytes`]. The fields
-/// are private so the mutation surface stays narrow.
-pub(super) struct HostState {
+/// 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::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 {
     wasi: Option<WasiP1Ctx>,
     stdout_pipe: Option<MemoryOutputPipe>,
     stderr_pipe: Option<MemoryOutputPipe>,
-    server: Option<Opaque<Value>>,
+    on_dispatch: Option<Opaque<Value>>,
     deadline: Option<Instant>,
-    limiter: KobakoLimiter,
+    limiter: MemoryLimiter,
     wall_entry: Option<Instant>,
     wall_time: Duration,
 }
 
-impl HostState {
+impl Invocation {
     /// Build a fresh per-Store host state. `memory_limit` carries the
     /// `Sandbox#memory_limit` cap in bytes (or `None` to disable the cap);
-    /// it is read from the wasmtime [`ResourceLimiter`] callback every
+    /// it is read from the wasmtime `ResourceLimiter` callback every
     /// time the guest grows linear memory (docs/behavior.md B-01, E-20).
     pub(super) fn new(memory_limit: Option<usize>) -> Self {
         Self {
             wasi: None,
             stdout_pipe: None,
             stderr_pipe: None,
-            server: None,
+            on_dispatch: None,
             deadline: None,
-            limiter: KobakoLimiter::new(memory_limit),
+            limiter: MemoryLimiter::new(memory_limit),
             wall_entry: None,
             wall_time: Duration::ZERO,
         }
     }
 
     /// Install a freshly-built WASI context plus the matching stdout/stderr
-    /// pipe clones. Called from [`crate::wasm::Instance::eval`] /
-    /// [`crate::wasm::Instance::run`] at the top of every guest
+    /// pipe clones. Called from `crate::runtime::Runtime::eval` /
+    /// `crate::runtime::Runtime::run` at the top of every guest
     /// invocation (docs/behavior.md B-03 / B-04).
     pub(super) fn install_wasi(
         &mut self,
@@ -76,10 +82,11 @@ impl HostState {
         self.stderr_pipe = Some(stderr);
     }
 
-    /// Bind the Ruby-side `Kobako::RPC::Server` handle. From this point on,
-    /// every `__kobako_dispatch` host import invocation routes through it.
-    pub(super) fn bind_server(&mut self, server: Opaque<Value>) {
-        self.server = Some(server);
+    /// 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);
     }
 
     /// Snapshot the bytes captured on guest fd 1 during the most recent
@@ -100,21 +107,22 @@ impl HostState {
             .unwrap_or_default()
     }
 
-    /// Return the bound Server handle. `Opaque<Value>` is `Copy`, so the
-    /// handle is returned by value rather than by reference. None means no
-    /// Server has been bound yet via [`HostState::bind_server`].
-    pub(super) fn server(&self) -> Option<Opaque<Value>> {
-        self.server
+    /// 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
+    /// `Invocation::bind_on_dispatch`.
+    pub(super) fn on_dispatch(&self) -> Option<Opaque<Value>> {
+        self.on_dispatch
     }
 
     /// Mutable handle to the live WASI context. Panics if no context has
     /// been installed yet — every call site is downstream of
-    /// [`HostState::install_wasi`] running at the top of
-    /// `Instance::eval` / `Instance::run`, so reaching this branch with
+    /// `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 {
         self.wasi.as_mut().expect(
-            "WASI context not initialised — call Instance#eval / Instance#run before any WASI use",
+            "WASI context not initialised — call Runtime#eval / Runtime#run before any WASI use",
         )
     }
 
@@ -126,19 +134,19 @@ impl HostState {
     }
 
     /// Return the current per-run deadline. Read from the epoch-deadline
-    /// callback installed by [`crate::wasm::Instance::from_path`].
+    /// callback installed by `crate::runtime::Runtime::from_path`.
     pub(super) fn deadline(&self) -> Option<Instant> {
         self.deadline
     }
 
-    /// Mutable handle to the embedded [`KobakoLimiter`]. Required by
-    /// the wasmtime [`ResourceLimiter`] callback wiring in
-    /// [`crate::wasm::Instance::from_path`]
+    /// Mutable handle to the embedded `MemoryLimiter`. Required by
+    /// the wasmtime `ResourceLimiter` callback wiring in
+    /// `crate::runtime::Runtime::from_path`
     /// (`store.limiter(|state| state.limiter_mut())`); kept private to
     /// the wasm submodule so the only public surface for arming the
-    /// cap goes through [`HostState::arm_memory_cap`] /
-    /// [`HostState::disarm_memory_cap`].
-    pub(super) fn limiter_mut(&mut self) -> &mut KobakoLimiter {
+    /// cap goes through `Invocation::arm_memory_cap` /
+    /// `Invocation::disarm_memory_cap`.
+    pub(super) fn limiter_mut(&mut self) -> &mut MemoryLimiter {
         &mut self.limiter
     }
 
@@ -147,7 +155,7 @@ impl HostState {
     /// charges only the `memory.grow` delta past `baseline` against
     /// the cap, so the mruby image's initial allocation and the
     /// high-water mark left by prior invocations do not consume the
-    /// budget. Paired with [`HostState::disarm_memory_cap`] around the
+    /// budget. Paired with `Invocation::disarm_memory_cap` around the
     /// call to the corresponding `__kobako_*` export so post-run host
     /// bookkeeping (e.g. fetching the OUTCOME_BUFFER) is not
     /// attributed to the user script.
@@ -156,7 +164,7 @@ impl HostState {
     }
 
     /// Disarm the docs/behavior.md E-20 memory cap. See
-    /// [`HostState::arm_memory_cap`].
+    /// `Invocation::arm_memory_cap`.
     pub(super) fn disarm_memory_cap(&mut self) {
         self.limiter.deactivate();
     }
@@ -172,7 +180,7 @@ impl HostState {
     }
 
     /// Close the docs/behavior.md B-35 `wall_time` measurement
-    /// started by [`HostState::start_wall_clock`]. Idempotent — a
+    /// started by `Invocation::start_wall_clock`. Idempotent — a
     /// 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.
@@ -203,30 +211,30 @@ impl HostState {
 ///
 /// `max_memory` is the byte cap on per-invocation growth (`None` disables
 /// the cap). `baseline` is the linear-memory size captured at invocation
-/// entry by [`KobakoLimiter::activate`]; the limiter charges only the
+/// entry by `MemoryLimiter::activate`; the limiter charges only the
 /// `memory.grow` delta past `baseline` against `max_memory`, so the
 /// mruby image's initial allocation and any high-water mark left by
 /// prior invocations on the same Sandbox do not consume the budget.
 /// `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
-/// [`KobakoLimiter::activate`] flips the flag for one
-/// `Instance::eval` / `Instance::run` call. When `cap_active` is
+/// `MemoryLimiter::activate` flips the flag for one
+/// `Runtime::eval` / `Runtime::run` 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
+/// `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 KobakoLimiter {
+pub(super) struct MemoryLimiter {
     max_memory: Option<usize>,
     baseline: usize,
     cap_active: bool,
     peak: usize,
 }
 
-impl KobakoLimiter {
+impl MemoryLimiter {
     fn new(max_memory: Option<usize>) -> Self {
         Self {
             max_memory,
@@ -238,12 +246,12 @@ impl KobakoLimiter {
 
     /// Arm the cap so subsequent `memory.grow` calls are charged
     /// against `max_memory` starting from `baseline` bytes. Called via
-    /// [`HostState::arm_memory_cap`] at the top of every invocation;
+    /// `Invocation::arm_memory_cap` at the top of every invocation;
     /// the cap is dormant by default — the module's declared initial
     /// memory is allocated during `Linker::instantiate` and the
     /// per-invocation budget excludes anything that existed before
     /// arming (docs/behavior.md B-01 Notes, E-20). Also clears the
-    /// per-invocation [`KobakoLimiter::peak`] high-water so the
+    /// per-invocation `MemoryLimiter::peak` high-water so the
     /// docs/behavior.md B-35 `memory_peak` accounting restarts from
     /// zero for the new invocation.
     fn activate(&mut self, baseline: usize) {
@@ -255,14 +263,14 @@ impl KobakoLimiter {
     /// Disarm the cap so post-run host bookkeeping (e.g. fetching the
     /// OUTCOME_BUFFER, which can grow guest memory transiently) is
     /// not attributed to the user script. Paired with
-    /// [`KobakoLimiter::activate`].
+    /// `MemoryLimiter::activate`.
     fn deactivate(&mut self) {
         self.cap_active = false;
     }
 
     /// Return the high-water mark of the per-invocation
     /// `memory.grow` delta past `baseline` observed since the last
-    /// [`KobakoLimiter::activate`]. Read after the guest export
+    /// `MemoryLimiter::activate`. Read after the guest export
     /// returns to populate `Kobako::Usage#memory_peak`
     /// (docs/behavior.md B-35). Pinned to the last accepted grow —
     /// rejected `desired` values that trip the docs/behavior.md E-20
@@ -273,7 +281,7 @@ impl KobakoLimiter {
     }
 }
 
-impl ResourceLimiter for KobakoLimiter {
+impl ResourceLimiter for MemoryLimiter {
     fn memory_growing(
         &mut self,
         _current: usize,
@@ -305,9 +313,9 @@ impl ResourceLimiter for KobakoLimiter {
     }
 }
 
-/// Marker error returned from [`KobakoLimiter::memory_growing`] on
+/// Marker error returned from `MemoryLimiter::memory_growing` on
 /// docs/behavior.md E-20. Downcast from the wasmtime trap error to surface as
-/// `Kobako::Wasm::MemoryLimitError` on the Ruby side. Callers use the
+/// `Kobako::MemoryLimitError` on the Ruby side. Callers use the
 /// `Display` impl below — no field is read directly — so the inner
 /// state stays private.
 #[derive(Debug)]
@@ -318,7 +326,7 @@ pub(crate) struct MemoryLimitTrap {
 
 impl MemoryLimitTrap {
     /// Construct a trap with the given +desired+ / +limit+ pair. Used
-    /// internally by [`KobakoLimiter::memory_growing`] in production and
+    /// internally by `MemoryLimiter::memory_growing` in production and
     /// by the sibling-module +classify_trap+ unit tests to materialise
     /// a representative error for downcast routing.
     #[cfg(test)]
@@ -331,8 +339,8 @@ impl std::fmt::Display for MemoryLimitTrap {
     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
         write!(
             f,
-            "linear memory growth exceeded memory_limit: \
-             desired={} bytes, limit={} bytes",
+            "memory usage exceeded memory_limit: \
+             requested={} bytes, limit={} bytes",
             self.desired, self.limit
         )
     }
@@ -342,7 +350,7 @@ impl std::error::Error for MemoryLimitTrap {}
 
 /// Marker error returned from the epoch-deadline callback on
 /// docs/behavior.md E-19. Downcast from the wasmtime trap error to
-/// surface as `Kobako::Wasm::TimeoutError` on the Ruby side.
+/// surface as `Kobako::TimeoutError` on the Ruby side.
 #[derive(Debug)]
 pub(crate) struct TimeoutTrap;
 
@@ -354,20 +362,20 @@ impl std::fmt::Display for TimeoutTrap {
 
 impl std::error::Error for TimeoutTrap {}
 
-/// Interior-mutability wrapper around `wasmtime::Store<HostState>`.
+/// Interior-mutability wrapper around `wasmtime::Store<Invocation>`.
 ///
 /// Magnus requires `Send + Sync` for wrapped types. `wasmtime::Store` is not
 /// `Sync`, so we wrap it in a `RefCell`. `RefCell` alone is sufficient
 /// because magnus enforces single-threaded GVL access from Ruby; `Send` and
 /// `Sync` are asserted via the unsafe impls below.
 pub(super) struct StoreCell {
-    inner: RefCell<WtStore<HostState>>,
+    inner: RefCell<WtStore<Invocation>>,
 }
 
 impl StoreCell {
-    /// Wrap a freshly-built `wasmtime::Store<HostState>` so it can be owned
-    /// by the magnus-wrapped `Instance`.
-    pub(super) fn new(store: WtStore<HostState>) -> Self {
+    /// Wrap a freshly-built `wasmtime::Store<Invocation>` so it can be owned
+    /// by the magnus-wrapped `Runtime`.
+    pub(super) fn new(store: WtStore<Invocation>) -> Self {
         Self {
             inner: RefCell::new(store),
         }
@@ -375,13 +383,13 @@ impl StoreCell {
 
     /// Immutable borrow of the wrapped Store. Panics if a `borrow_mut()`
     /// is currently live — matches `RefCell::borrow` semantics.
-    pub(super) fn borrow(&self) -> Ref<'_, WtStore<HostState>> {
+    pub(super) fn borrow(&self) -> Ref<'_, WtStore<Invocation>> {
         self.inner.borrow()
     }
 
     /// Mutable borrow of the wrapped Store. Panics if any other borrow is
     /// currently live — matches `RefCell::borrow_mut` semantics.
-    pub(super) fn borrow_mut(&self) -> RefMut<'_, WtStore<HostState>> {
+    pub(super) fn borrow_mut(&self) -> RefMut<'_, WtStore<Invocation>> {
         self.inner.borrow_mut()
     }
 }
@@ -389,10 +397,10 @@ impl StoreCell {
 // SAFETY: magnus requires `Send + Sync` on `#[magnus::wrap]` types. Both
 // claims hold under the GVL invariant:
 //
-//   * Send — `wasmtime::Store<HostState>` is itself `Send` (verified
+//   * Send — `wasmtime::Store<Invocation>` is itself `Send` (verified
 //     upstream by wasmtime; see `wasmtime::Store`'s trait impls).
 //     `RefCell<T>: Send` whenever `T: Send`. The remaining stored state
-//     (`HostState`) holds `Opaque<Value>` for the Ruby Server handle —
+//     (`Invocation`) holds `Opaque<Value>` for the Ruby Server handle —
 //     `Opaque<Value>` is documented as `Send` by magnus precisely so
 //     wrapped objects can satisfy this bound.
 //
@@ -412,24 +420,24 @@ unsafe impl Sync for StoreCell {}
 
 #[cfg(test)]
 mod tests {
-    //! Unit tests for [`KobakoLimiter`] — the per-invocation memory
+    //! Unit tests for `MemoryLimiter` — the per-invocation memory
     //! delta cap. The Ruby-facing E2E suite exercises the full path
     //! through wasmtime; these tests pin the pure delta arithmetic so
     //! a regression that breaks the baseline accounting (e.g. dropping
     //! the `baseline` subtraction, or letting `activate` carry stale
     //! state across invocations) is caught without spinning up a
     //! Store.
-    use super::{KobakoLimiter, MemoryLimitTrap};
+    use super::{MemoryLimitTrap, MemoryLimiter};
     use wasmtime::ResourceLimiter;
 
-    fn assert_growing(limiter: &mut KobakoLimiter, desired: usize) {
+    fn assert_growing(limiter: &mut MemoryLimiter, desired: usize) {
         assert!(
             limiter.memory_growing(0, desired, None).unwrap(),
             "expected memory_growing({desired}) to allow growth"
         );
     }
 
-    fn assert_trapping(limiter: &mut KobakoLimiter, desired: usize) {
+    fn assert_trapping(limiter: &mut MemoryLimiter, desired: usize) {
         let err = limiter
             .memory_growing(0, desired, None)
             .expect_err("expected memory_growing to trap");
@@ -441,7 +449,7 @@ mod tests {
 
     #[test]
     fn dormant_limiter_allows_any_growth() {
-        let mut limiter = KobakoLimiter::new(Some(1 << 20));
+        let mut limiter = MemoryLimiter::new(Some(1 << 20));
         // Without `activate`, the cap is dormant — the module's
         // declared initial allocation must pass through unconditionally.
         assert_growing(&mut limiter, 100 << 20);
@@ -449,7 +457,7 @@ mod tests {
 
     #[test]
     fn delta_below_cap_passes_after_activate() {
-        let mut limiter = KobakoLimiter::new(Some(1 << 20));
+        let mut limiter = MemoryLimiter::new(Some(1 << 20));
         limiter.activate(2 << 20);
         // baseline=2 MiB, desired=2.5 MiB → delta=0.5 MiB ≤ 1 MiB cap.
         assert_growing(&mut limiter, (2 << 20) + (1 << 19));
@@ -457,7 +465,7 @@ mod tests {
 
     #[test]
     fn delta_past_cap_traps_with_memory_limit_trap() {
-        let mut limiter = KobakoLimiter::new(Some(1 << 20));
+        let mut limiter = MemoryLimiter::new(Some(1 << 20));
         limiter.activate(2 << 20);
         // baseline=2 MiB, desired=4 MiB → delta=2 MiB > 1 MiB cap.
         assert_trapping(&mut limiter, 4 << 20);
@@ -465,7 +473,7 @@ mod tests {
 
     #[test]
     fn activate_resets_baseline_on_each_invocation() {
-        let mut limiter = KobakoLimiter::new(Some(1 << 20));
+        let mut limiter = MemoryLimiter::new(Some(1 << 20));
         limiter.activate(2 << 20);
         assert_growing(&mut limiter, (2 << 20) + (1 << 20));
         // Second invocation: linear memory has grown to 3 MiB. Re-arming
@@ -478,20 +486,20 @@ mod tests {
 
     #[test]
     fn disabled_cap_ignores_delta_size() {
-        let mut limiter = KobakoLimiter::new(None);
+        let mut limiter = MemoryLimiter::new(None);
         limiter.activate(0);
         assert_growing(&mut limiter, 100 << 20);
     }
 
     #[test]
     fn peak_starts_at_zero_before_any_grow() {
-        let limiter = KobakoLimiter::new(Some(1 << 20));
+        let limiter = MemoryLimiter::new(Some(1 << 20));
         assert_eq!(limiter.peak(), 0);
     }
 
     #[test]
     fn peak_tracks_high_water_of_delta_past_baseline() {
-        let mut limiter = KobakoLimiter::new(Some(1 << 20));
+        let mut limiter = MemoryLimiter::new(Some(1 << 20));
         limiter.activate(2 << 20);
         assert_growing(&mut limiter, (2 << 20) + (1 << 18)); // delta=256 KiB
         assert_growing(&mut limiter, (2 << 20) + (1 << 19)); // delta=512 KiB (new peak)
@@ -501,7 +509,7 @@ mod tests {
 
     #[test]
     fn trap_does_not_update_peak() {
-        let mut limiter = KobakoLimiter::new(Some(1 << 20));
+        let mut limiter = MemoryLimiter::new(Some(1 << 20));
         limiter.activate(2 << 20);
         assert_growing(&mut limiter, (2 << 20) + (1 << 19)); // delta=512 KiB
         assert_trapping(&mut limiter, (2 << 20) + (2 << 20)); // would be 2 MiB > 1 MiB cap
@@ -511,7 +519,7 @@ mod tests {
 
     #[test]
     fn activate_resets_peak_for_new_invocation() {
-        let mut limiter = KobakoLimiter::new(Some(1 << 20));
+        let mut limiter = MemoryLimiter::new(Some(1 << 20));
         limiter.activate(2 << 20);
         assert_growing(&mut limiter, (2 << 20) + (1 << 19));
         assert_eq!(limiter.peak(), 1 << 19);
@@ -521,7 +529,7 @@ mod tests {
 
     #[test]
     fn disabled_cap_still_tracks_peak() {
-        let mut limiter = KobakoLimiter::new(None);
+        let mut limiter = MemoryLimiter::new(None);
         limiter.activate(1 << 20);
         assert_growing(&mut limiter, (1 << 20) + (4 << 20));
         assert_eq!(limiter.peak(), 4 << 20);

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

@@ -0,0 +1,134 @@
+//! 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
+//! `super::invocation` (where the limiter / callback construct them).
+
+use std::time::Instant;
+
+use magnus::{Error as MagnusError, Ruby};
+use wasmtime::{StoreContextMut, UpdateDeadline};
+
+use super::invocation::{Invocation, MemoryLimitTrap, TimeoutTrap};
+use super::{memory_limit_err, setup_err, timeout_err, trap_err};
+
+/// Epoch-deadline callback installed on every Store. Read the per-run
+/// wall-clock deadline from `Invocation` (docs/behavior.md B-01) 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
+/// `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(
+    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)),
+    }
+}
+
+/// 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 {
+    /// docs/behavior.md E-19 wall-clock cap path.
+    Timeout,
+    /// docs/behavior.md E-20 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
+    }
+}
+
+/// 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.
+///
+/// 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
+/// the `"error while executing at wasm backtrace: ..."` framing, which
+/// is operator noise on a cap trap. For `TrapClass::Other` the
+/// wasmtime wrapper IS the diagnostic (real script trap) so it stays.
+pub(super) fn call_err(ruby: &Ruby, err: wasmtime::Error) -> MagnusError {
+    match classify_trap(&err) {
+        TrapClass::Timeout => {
+            let msg = 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>()
+                .map(|t| t.to_string())
+                .unwrap_or_else(|| format!("{}", err));
+            memory_limit_err(ruby, msg)
+        }
+        TrapClass::Other => trap_err(ruby, format!("{}", err)),
+    }
+}
+
+/// Map an instantiation error to `Kobako::SetupError`. Instantiation runs
+/// during `from_path` construction, before any invocation — docs/behavior.md
+/// E-41 classifies every such failure as 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))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{classify_trap, TrapClass};
+    use crate::runtime::invocation::{MemoryLimitTrap, TimeoutTrap};
+
+    #[test]
+    fn classify_trap_routes_timeout_trap_to_timeout() {
+        let err = wasmtime::Error::new(TimeoutTrap);
+        assert_eq!(classify_trap(&err), TrapClass::Timeout);
+    }
+
+    #[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);
+    }
+
+    #[test]
+    fn classify_trap_falls_back_to_other_for_unknown_errors() {
+        let err = wasmtime::Error::msg("some other wasmtime fault");
+        assert_eq!(classify_trap(&err), TrapClass::Other);
+    }
+}