kobako 0.2.1 → 0.4.0

data/ext/kobako/src/wasm/dispatch.rs

@@ -3,7 +3,7 @@
 //! When the guest invokes the wasm import declared in
 //! `wasm/kobako-wasm/src/abi.rs`, wasmtime calls back into the host
 //! through the closure built in [`super::instance::Instance::build`].
-//! That closure delegates here. The dispatcher (SPEC.md B-12 / B-13):
+//! That closure delegates here. The dispatcher (docs/behavior.md B-12 / B-13):
 //!
 //!   1. Reads the Request bytes from guest linear memory.
 //!   2. Hands them to the Ruby-side `Kobako::RPC::Server` and recovers
@@ -19,6 +19,31 @@
 //! return to a trap. Failures during normal dispatch surface as
 //! Response.err envelopes from the Server itself — they never reach
 //! this 0-return path.
+//!
+//! ## Why this module writes to `stderr`
+//!
+//! This file is the one place in `ext/` that deliberately prints
+//! through `eprintln!`. The host normally surfaces faults by
+//! raising a `MagnusError` back into Ruby; the dispatcher contract
+//! is the exception — it must return a packed `i64` to the guest
+//! and cannot raise, so a 0 return is the only signal the wasm side
+//! receives. The guest collapses every 0 into the same trap, so the
+//! Ruby host has no way to attribute the failure to a specific
+//! step (missing `memory` export vs. no Server bound vs. Server
+//! raised vs. `__kobako_alloc` returned 0 vs. `memory.write`
+//! rejected).
+//!
+//! [`handle`] writes a single `[kobako-dispatch] <reason>` line to
+//! `stderr` on each failure path so operators have a breadcrumb to
+//! correlate the trap with the actual cause. The line is emitted in
+//! both debug and release builds on purpose: dispatcher failures
+//! are wire-layer faults rather than expected error paths
+//! (`Kobako::Sandbox` always installs a Server, the Server is
+//! contracted never to raise, etc.), so the "release-build noise"
+//! cost is bounded — under normal operation the line is never
+//! written. Operators that need to silence the channel can redirect
+//! the host process's stderr, but the kobako convention is "ext
+//! never logs" plus this single, named exception.
 
 use magnus::value::{Opaque, ReprValue};
 use magnus::{Error as MagnusError, RString, Ruby, Value};
@@ -28,27 +53,49 @@ use super::host_state::HostState;
 
 /// Drive a single `__kobako_dispatch` invocation end-to-end. Entry point
 /// from the wasmtime closure built in [`super::instance::Instance::build`].
+///
+/// Returns the packed `(ptr<<32)|len` u64 on success, 0 on any
+/// wire-layer fault. Failure paths log a `[kobako-dispatch]` line to
+/// `stderr` so operators have a breadcrumb when the guest sees a 0
+/// return and traps; before this every failure was silent. The Server
+/// itself is contracted never to raise (it folds Service exceptions
+/// into Response.err envelopes), so reaching the failure path is
+/// always a wiring bug or wire-layer fault rather than an expected
+/// path.
 pub(crate) fn handle(caller: &mut Caller<'_, HostState>, req_ptr: i32, req_len: i32) -> i64 {
-    let req_bytes = match read_caller_memory(caller, req_ptr, req_len) {
-        Some(b) => b,
-        None => return 0,
-    };
+    match try_handle(caller, req_ptr, req_len) {
+        Ok(packed) => packed,
+        Err(reason) => {
+            eprintln!("[kobako-dispatch] {}", reason);
+            0
+        }
+    }
+}
 
-    // No Server bound — return 0 to signal a wire-layer fault; the guest
-    // maps a 0 return to a trap. `Kobako::Sandbox` always installs a
-    // Server before invoking the guest, so reaching this branch indicates
-    // a misuse rather than a normal control path.
-    let server = match caller.data().server() {
-        Some(d) => d,
-        None => return 0,
-    };
+/// Result-returning core of [`handle`]. Pulled out so each early
+/// failure path carries a diagnostic string instead of an opaque 0.
+fn try_handle(
+    caller: &mut Caller<'_, HostState>,
+    req_ptr: i32,
+    req_len: i32,
+) -> Result<i64, &'static str> {
+    let req_bytes = read_caller_memory(caller, req_ptr, req_len).ok_or(
+        "Sandbox runtime does not export linear memory, or RPC request slice falls outside it",
+    )?;
 
-    let resp_bytes = match invoke_server(server, &req_bytes) {
-        Ok(b) => b,
-        Err(_) => return 0,
-    };
+    // `Kobako::Sandbox` always installs an RPC server before invoking
+    // the runtime, so reaching this branch indicates a misuse rather
+    // than a normal control path.
+    let server = caller
+        .data()
+        .server()
+        .ok_or("RPC dispatched outside an active Sandbox#run — internal wiring bug")?;
+
+    let resp_bytes = invoke_server(server, &req_bytes).map_err(|_| {
+        "RPC server raised an exception instead of returning a fault — please report this as a kobako bug"
+    })?;
 
-    write_response(caller, &resp_bytes).unwrap_or(0)
+    write_response(caller, &resp_bytes)
 }
 
 /// Call the Ruby Server's `#dispatch(request_bytes)` method and return
@@ -56,43 +103,48 @@ pub(crate) fn handle(caller: &mut Caller<'_, HostState>, req_ptr: i32, req_len:
 /// failed (it is contracted never to raise — see
 /// `Kobako::RPC::Server#dispatch`), which we treat as a wire-layer fault.
 fn invoke_server(server: Opaque<Value>, req_bytes: &[u8]) -> Result<Vec<u8>, MagnusError> {
-    // The wasmtime callback runs on the same Ruby thread that called
-    // Sandbox#run — the invariant SPEC Implementation Standards
-    // Architecture pins for the host gem — so `Ruby::get()` is always
-    // available here. Panicking with `expect` localises the violation
-    // rather than letting a nonsense error propagate.
+    // The wasmtime callback runs on the same Ruby thread that called the
+    // active Sandbox invocation (#eval or #run) — the invariant SPEC
+    // Implementation Standards Architecture pins for the host gem — so
+    // `Ruby::get()` is always available here. Panicking with `expect`
+    // localises the violation rather than letting a nonsense error
+    // propagate.
     let ruby = Ruby::get().expect("Ruby handle unavailable in __kobako_dispatch");
     let server_value: Value = ruby.get_inner(server);
     let req_str = ruby.str_from_slice(req_bytes);
     let resp: RString = server_value.funcall("dispatch", (req_str,))?;
-    // SAFETY: the returned RString is held by the Ruby VM for the duration of
-    // this scope; copying its bytes into a Vec is a defensive standard pattern.
-    let bytes = unsafe { resp.as_slice() }.to_vec();
-    Ok(bytes)
+    Ok(super::rstring_to_vec(resp))
 }
 
 /// Allocate a guest-side buffer through `__kobako_alloc` and copy the
 /// response bytes into it. Returns the packed `(ptr<<32)|len` u64.
-fn write_response(caller: &mut Caller<'_, HostState>, bytes: &[u8]) -> Option<i64> {
+/// Each failure path carries a `&'static str` reason so the dispatcher
+/// wrapper can surface a useful diagnostic rather than a silent 0.
+fn write_response(caller: &mut Caller<'_, HostState>, bytes: &[u8]) -> Result<i64, &'static str> {
     let alloc = match caller.get_export("__kobako_alloc") {
-        Some(Extern::Func(f)) => f.typed::<i32, i32>(&*caller).ok()?,
-        _ => return None,
+        Some(Extern::Func(f)) => f
+            .typed::<i32, i32>(&*caller)
+            .map_err(|_| "Sandbox runtime's allocation hook has the wrong signature")?,
+        _ => return Err("Sandbox runtime is missing the allocation hook"),
     };
-    let len_i32 = i32::try_from(bytes.len()).ok()?;
-    let ptr = alloc.call(&mut *caller, len_i32).ok()?;
+    let len_i32 = i32::try_from(bytes.len()).map_err(|_| "RPC response exceeds 2 GiB")?;
+    let ptr = alloc
+        .call(&mut *caller, len_i32)
+        .map_err(|_| "Sandbox allocation trapped while preparing the RPC response")?;
     if ptr == 0 {
-        return None;
+        return Err("Sandbox is out of memory while preparing the RPC response");
     }
 
     let mem = match caller.get_export("memory") {
         Some(Extern::Memory(m)) => m,
-        _ => return None,
+        _ => return Err("Sandbox runtime does not export linear memory"),
     };
-    mem.write(&mut *caller, ptr as usize, bytes).ok()?;
+    mem.write(&mut *caller, ptr as usize, bytes)
+        .map_err(|_| "could not write the RPC response into Sandbox memory (range invalid)")?;
 
     let ptr_u32 = ptr as u32;
     let len_u32 = bytes.len() as u32;
-    Some(((ptr_u32 as i64) << 32) | (len_u32 as i64))
+    Ok(((ptr_u32 as i64) << 32) | (len_u32 as i64))
 }
 
 /// Copy `[ptr, ptr+len)` out of the guest's linear memory as seen from

data/ext/kobako/src/wasm/host_state.rs

@@ -4,16 +4,20 @@
 //! 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` (SPEC.md B-03 / B-04).
+//! every `#run` (docs/behavior.md B-03 / B-04).
 //!
-//! The state also carries the per-run wall-clock deadline (SPEC.md B-01,
-//! E-19) and the linear-memory cap [`KobakoLimiter`] (SPEC.md B-01,
-//! E-20). Both are read from the wasmtime `epoch_deadline_callback` /
-//! `ResourceLimiter` callbacks installed in
-//! [`crate::wasm::Instance::from_path`].
+//! The state 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
+//! read from the wasmtime `epoch_deadline_callback` / `ResourceLimiter`
+//! callbacks installed in [`crate::wasm::Instance::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.
 
 use std::cell::{Ref, RefCell, RefMut};
-use std::time::Instant;
+use std::time::{Duration, Instant};
 
 use magnus::{value::Opaque, Value};
 use wasmtime::{ResourceLimiter, Store as WtStore};
@@ -35,13 +39,15 @@ pub(super) struct HostState {
     server: Option<Opaque<Value>>,
     deadline: Option<Instant>,
     limiter: KobakoLimiter,
+    wall_entry: Option<Instant>,
+    wall_time: Duration,
 }
 
 impl HostState {
     /// 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
-    /// time the guest grows linear memory (SPEC.md B-01, E-20).
+    /// 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,
@@ -50,12 +56,15 @@ impl HostState {
             server: None,
             deadline: None,
             limiter: KobakoLimiter::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::run`] at the top
-    /// of every guest invocation (SPEC.md B-03 / B-04).
+    /// pipe clones. Called from [`crate::wasm::Instance::eval`] /
+    /// [`crate::wasm::Instance::run`] at the top of every guest
+    /// invocation (docs/behavior.md B-03 / B-04).
     pub(super) fn install_wasi(
         &mut self,
         wasi: WasiP1Ctx,
@@ -100,17 +109,18 @@ impl HostState {
 
     /// 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::run`,
-    /// so reaching this branch with `None` signals a host-side wiring bug.
+    /// [`HostState::install_wasi`] running at the top of
+    /// `Instance::eval` / `Instance::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#run before any WASI use")
+        self.wasi.as_mut().expect(
+            "WASI context not initialised — call Instance#eval / Instance#run before any WASI use",
+        )
     }
 
     /// Replace the per-run wall-clock deadline. `Some(at)` makes the
     /// epoch-deadline callback trap once `Instant::now() >= at`; `None`
-    /// disables the cap. Called at the top of every `#run` (SPEC.md B-01).
+    /// disables the cap. Called at the top of every `#run` (docs/behavior.md B-01).
     pub(super) fn set_deadline(&mut self, deadline: Option<Instant>) {
         self.deadline = deadline;
     }
@@ -121,65 +131,146 @@ impl HostState {
         self.deadline
     }
 
-    /// Mutable handle to the embedded [`KobakoLimiter`]. Shared by the
-    /// wasmtime [`ResourceLimiter`] callback (set once at Store build
-    /// time) and by [`crate::wasm::Instance`] for arming / disarming the
-    /// memory cap around each guest run. Same shape as
-    /// [`HostState::wasi_mut`] — callers operate on the inner type
-    /// directly instead of going through a per-action passthrough.
+    /// Mutable handle to the embedded [`KobakoLimiter`]. Required by
+    /// the wasmtime [`ResourceLimiter`] callback wiring in
+    /// [`crate::wasm::Instance::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 {
         &mut self.limiter
     }
+
+    /// Arm the docs/behavior.md E-20 memory cap for one guest run with
+    /// the current linear-memory size as the baseline. The limiter
+    /// 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
+    /// call to the corresponding `__kobako_*` export so post-run host
+    /// bookkeeping (e.g. fetching the OUTCOME_BUFFER) is not
+    /// attributed to the user script.
+    pub(super) fn arm_memory_cap(&mut self, baseline: usize) {
+        self.limiter.activate(baseline);
+    }
+
+    /// Disarm the docs/behavior.md E-20 memory cap. See
+    /// [`HostState::arm_memory_cap`].
+    pub(super) fn disarm_memory_cap(&mut self) {
+        self.limiter.deactivate();
+    }
+
+    /// Stamp the wall-clock entry instant for the docs/behavior.md
+    /// B-35 `wall_time` measurement. Called at the top of every
+    /// invocation immediately before the guest export call so the
+    /// bracket matches the `timeout` deadline accounting (B-01) and
+    /// excludes post-run host bookkeeping such as `OUTCOME_BUFFER`
+    /// decoding.
+    pub(super) fn start_wall_clock(&mut self) {
+        self.wall_entry = Some(Instant::now());
+    }
+
+    /// Close the docs/behavior.md B-35 `wall_time` measurement
+    /// started by [`HostState::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.
+    pub(super) fn stop_wall_clock(&mut self) {
+        if let Some(entry) = self.wall_entry.take() {
+            self.wall_time = entry.elapsed();
+        }
+    }
+
+    /// Return the wall-clock duration the most recent invocation
+    /// spent inside the guest export call (docs/behavior.md B-35).
+    /// Zero before the first invocation.
+    pub(super) fn wall_time(&self) -> Duration {
+        self.wall_time
+    }
+
+    /// Return the docs/behavior.md B-35 `memory_peak` — the high-
+    /// water mark of the per-invocation `memory.grow` delta past the
+    /// linear-memory size captured at invocation entry. Zero before
+    /// the first invocation.
+    pub(super) fn memory_peak(&self) -> usize {
+        self.limiter.peak()
+    }
 }
 
-/// Resource limiter that enforces the `memory_limit` cap from SPEC.md
-/// B-01 / E-20 on every guest `memory.grow`.
+/// Resource limiter that enforces the per-invocation `memory_limit`
+/// cap from docs/behavior.md B-01 / E-20.
 ///
-/// `max_memory` is the byte cap (`None` disables the cap). `cap_active`
-/// gates whether the cap is enforced — wasmtime's `ResourceLimiter`
-/// fires for both the module's declared initial allocation and every
-/// subsequent `memory.grow`, but SPEC.md E-20 scopes the trap to
-/// `memory.grow` specifically. [`KobakoLimiter::activate`] /
-/// [`KobakoLimiter::deactivate`] flip the flag for the lifetime of an
-/// `Instance::run` call. When `cap_active` is `false`, the limiter
-/// always allows growth.
+/// `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
+/// `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
+/// `false`, the limiter always allows growth.
 ///
-/// When `memory.grow` would push linear memory past the cap, the
-/// limiter returns [`MemoryLimitTrap`] from `memory_growing`; wasmtime
-/// turns that into the trap surfaced to the host as `__kobako_run`
-/// failure.
+/// When `memory.grow` would push the per-invocation delta past
+/// `max_memory`, the limiter returns [`MemoryLimitTrap`] from
+/// `memory_growing`; wasmtime turns that into the trap surfaced to the
+/// host as a guest invocation failure.
 #[derive(Debug, Clone, Copy)]
 pub(super) struct KobakoLimiter {
     max_memory: Option<usize>,
+    baseline: usize,
     cap_active: bool,
+    peak: usize,
 }
 
 impl KobakoLimiter {
     fn new(max_memory: Option<usize>) -> Self {
         Self {
             max_memory,
+            baseline: 0,
             cap_active: false,
+            peak: 0,
         }
     }
 
-    /// Arm the cap so subsequent `memory.grow` calls are checked
-    /// against `memory_limit`. The cap is dormant by default — the
-    /// module's declared initial memory is allocated during
-    /// `Linker::instantiate` and SPEC.md E-20 scopes the trap to
-    /// `memory.grow` (not the instantiation-time initial allocation).
-    /// [`crate::wasm::Instance::run`] calls this right before
-    /// `__kobako_run`.
-    pub(super) fn activate(&mut self) {
+    /// 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;
+    /// 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
+    /// docs/behavior.md B-35 `memory_peak` accounting restarts from
+    /// zero for the new invocation.
+    fn activate(&mut self, baseline: usize) {
+        self.baseline = baseline;
         self.cap_active = true;
+        self.peak = 0;
     }
 
     /// 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`].
-    pub(super) fn deactivate(&mut self) {
+    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
+    /// 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
+    /// cap never update the peak, so the reported value never exceeds
+    /// `memory_limit`.
+    pub(super) fn peak(&self) -> usize {
+        self.peak
+    }
 }
 
 impl ResourceLimiter for KobakoLimiter {
@@ -192,11 +283,15 @@ impl ResourceLimiter for KobakoLimiter {
         if !self.cap_active {
             return Ok(true);
         }
+        let delta = desired.saturating_sub(self.baseline);
         if let Some(limit) = self.max_memory {
-            if desired > limit {
+            if delta > limit {
                 return Err(wasmtime::Error::new(MemoryLimitTrap { desired, limit }));
             }
         }
+        if delta > self.peak {
+            self.peak = delta;
+        }
         Ok(true)
     }
 
@@ -211,7 +306,7 @@ impl ResourceLimiter for KobakoLimiter {
 }
 
 /// Marker error returned from [`KobakoLimiter::memory_growing`] on
-/// SPEC.md E-20. Downcast from the wasmtime trap error to surface as
+/// docs/behavior.md E-20. Downcast from the wasmtime trap error to surface as
 /// `Kobako::Wasm::MemoryLimitError` on the Ruby side. Callers use the
 /// `Display` impl below — no field is read directly — so the inner
 /// state stays private.
@@ -221,11 +316,23 @@ pub(crate) struct MemoryLimitTrap {
     limit: usize,
 }
 
+impl MemoryLimitTrap {
+    /// Construct a trap with the given +desired+ / +limit+ pair. Used
+    /// internally by [`KobakoLimiter::memory_growing`] in production and
+    /// by the sibling-module +classify_trap+ unit tests to materialise
+    /// a representative error for downcast routing.
+    #[cfg(test)]
+    pub(super) fn new(desired: usize, limit: usize) -> Self {
+        Self { desired, limit }
+    }
+}
+
 impl std::fmt::Display for MemoryLimitTrap {
     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
         write!(
             f,
-            "guest memory.grow would exceed memory_limit: desired={} bytes, limit={} bytes",
+            "linear memory growth exceeded memory_limit: \
+             desired={} bytes, limit={} bytes",
             self.desired, self.limit
         )
     }
@@ -233,15 +340,15 @@ impl std::fmt::Display for MemoryLimitTrap {
 
 impl std::error::Error for MemoryLimitTrap {}
 
-/// Marker error returned from the epoch-deadline callback on SPEC.md
-/// E-19. Downcast from the wasmtime trap error to surface as
-/// `Kobako::Wasm::TimeoutError` on the Ruby side.
+/// 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.
 #[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, "guest exceeded the configured wall-clock timeout")
+        write!(f, "wall-clock deadline exceeded")
     }
 }
 
@@ -279,8 +386,144 @@ impl StoreCell {
     }
 }
 
-// SAFETY: Ruby's GVL serialises access to magnus-wrapped objects on a single
-// OS thread at a time. `wasmtime::Store` is `Send` (verified upstream); the
-// `RefCell`-mediated mutation is therefore safe under the GVL invariant.
+// SAFETY: magnus requires `Send + Sync` on `#[magnus::wrap]` types. Both
+// claims hold under the GVL invariant:
+//
+//   * Send — `wasmtime::Store<HostState>` 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 —
+//     `Opaque<Value>` is documented as `Send` by magnus precisely so
+//     wrapped objects can satisfy this bound.
+//
+//   * Sync — `RefCell` is *not* `Sync` in the general Rust sense
+//     (concurrent `borrow_mut` is UB). We assert `Sync` here because the
+//     GVL serialises every call into Ruby C and every entry into magnus-
+//     wrapped methods onto a single OS thread at a time: by the time the
+//     `Sync` bound matters, magnus has already established that only one
+//     thread can be inside the wrapper. Cross-thread mutation cannot
+//     occur. If a future magnus release adopts a thread model that
+//     permits concurrent access to wrapped objects, this assertion would
+//     have to revert and `StoreCell` would need to switch to
+//     `Mutex<wasmtime::Store<…>>` — but as of magnus 0.8 the contract
+//     holds.
 unsafe impl Send for StoreCell {}
 unsafe impl Sync for StoreCell {}
+
+#[cfg(test)]
+mod tests {
+    //! Unit tests for [`KobakoLimiter`] — 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 wasmtime::ResourceLimiter;
+
+    fn assert_growing(limiter: &mut KobakoLimiter, 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) {
+        let err = limiter
+            .memory_growing(0, desired, None)
+            .expect_err("expected memory_growing to trap");
+        assert!(
+            err.downcast_ref::<MemoryLimitTrap>().is_some(),
+            "expected MemoryLimitTrap, got {err:?}"
+        );
+    }
+
+    #[test]
+    fn dormant_limiter_allows_any_growth() {
+        let mut limiter = KobakoLimiter::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);
+    }
+
+    #[test]
+    fn delta_below_cap_passes_after_activate() {
+        let mut limiter = KobakoLimiter::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));
+    }
+
+    #[test]
+    fn delta_past_cap_traps_with_memory_limit_trap() {
+        let mut limiter = KobakoLimiter::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);
+    }
+
+    #[test]
+    fn activate_resets_baseline_on_each_invocation() {
+        let mut limiter = KobakoLimiter::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
+        // must re-anchor the baseline so the next 1 MiB of growth fits
+        // the per-invocation budget rather than being charged against
+        // the prior invocation's residue.
+        limiter.activate(3 << 20);
+        assert_growing(&mut limiter, (3 << 20) + (1 << 20));
+    }
+
+    #[test]
+    fn disabled_cap_ignores_delta_size() {
+        let mut limiter = KobakoLimiter::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));
+        assert_eq!(limiter.peak(), 0);
+    }
+
+    #[test]
+    fn peak_tracks_high_water_of_delta_past_baseline() {
+        let mut limiter = KobakoLimiter::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)
+        assert_growing(&mut limiter, (2 << 20) + (1 << 17)); // delta=128 KiB (below peak)
+        assert_eq!(limiter.peak(), 1 << 19);
+    }
+
+    #[test]
+    fn trap_does_not_update_peak() {
+        let mut limiter = KobakoLimiter::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
+                                                              // Peak reflects the last accepted grow, not the rejected desired.
+        assert_eq!(limiter.peak(), 1 << 19);
+    }
+
+    #[test]
+    fn activate_resets_peak_for_new_invocation() {
+        let mut limiter = KobakoLimiter::new(Some(1 << 20));
+        limiter.activate(2 << 20);
+        assert_growing(&mut limiter, (2 << 20) + (1 << 19));
+        assert_eq!(limiter.peak(), 1 << 19);
+        limiter.activate(3 << 20);
+        assert_eq!(limiter.peak(), 0);
+    }
+
+    #[test]
+    fn disabled_cap_still_tracks_peak() {
+        let mut limiter = KobakoLimiter::new(None);
+        limiter.activate(1 << 20);
+        assert_growing(&mut limiter, (1 << 20) + (4 << 20));
+        assert_eq!(limiter.peak(), 4 << 20);
+    }
+}