kobako 0.2.1 → 0.4.0

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

@@ -3,32 +3,37 @@
 //! Constructed via [`Instance::from_path`]; the wasmtime [`Engine`] and
 //! compiled [`Module`] are owned by the [`super::cache`] singletons and
 //! never surface to Ruby. The instance wraps a [`StoreCell`] (interior-
-//! mutability around `wasmtime::Store<HostState>`) plus two cached
-//! [`TypedFunc`] handles for the SPEC ABI exports used by the host-driven
-//! run path.
+//! mutability around `wasmtime::Store<HostState>`) plus three cached
+//! [`TypedFunc`] handles for the docs/wire-codec.md ABI exports used by
+//! the host-driven run path.
 //!
 //! The Ruby surface intentionally exposes intent, not the underlying ABI
-//! (SPEC.md "Code Organization"). The two-frame stdin protocol, packed-u64
-//! outcome encoding, and `__kobako_alloc` / `__kobako_take_outcome` /
-//! `__kobako_run` exports are all wrapped inside [`Instance::run`] and
-//! [`Instance::outcome`]; Ruby callers see only `#run(preamble, source)`,
-//! `#stdout`, `#stderr`, `#outcome!`, and `#server=`.
+//! (SPEC.md "Code Organization"). The length-prefixed stdin frame
+//! protocol (three frames for `#eval`: preamble + source + snippets;
+//! two for `#run`: preamble + snippets), packed-u64 outcome encoding,
+//! and the `__kobako_eval` / `__kobako_run` / `__kobako_alloc` /
+//! `__kobako_take_outcome` exports are all wrapped inside
+//! [`Instance::eval`], [`Instance::run`], and [`Instance::outcome`];
+//! Ruby callers see only `#eval(preamble, source, snippets)`,
+//! `#run(preamble, snippets, envelope)`, `#stdout`, `#stderr`,
+//! `#outcome!`, and `#server=`.
 //!
-//! WASI stdout/stderr capture (SPEC.md B-04): wasmtime-wasi p1 bindings
-//! route guest fd 1 and fd 2 into per-run [`MemoryOutputPipe`] instances
-//! rebuilt at the start of every [`Instance::run`]. The per-channel cap
-//! is enforced directly on the pipe — the pipe is sized at `cap + 1` so
-//! a guest that writes exactly `cap` bytes is distinguishable from one
-//! that exceeded the cap, and `#stdout` / `#stderr` slice the captured
-//! bytes back to `cap` before returning them paired with a truncation
-//! flag. Uncapped channels (`None`) build the pipe at `usize::MAX`;
-//! `memory_limit` provides the real upper bound in that case.
+//! WASI stdout/stderr capture (docs/behavior.md B-04): wasmtime-wasi p1
+//! bindings route guest fd 1 and fd 2 into per-run [`MemoryOutputPipe`]
+//! instances rebuilt at the start of every [`Instance::eval`] /
+//! [`Instance::run`]. The per-channel cap is enforced directly on the
+//! pipe — the pipe is sized at `cap + 1` so a guest that writes exactly
+//! `cap` bytes is distinguishable from one that exceeded the cap, and
+//! `#stdout` / `#stderr` slice the captured bytes back to `cap` before
+//! returning them paired with a truncation flag. Uncapped channels
+//! (`None`) build the pipe at `usize::MAX`; `memory_limit` provides
+//! the real upper bound in that case.
 //!
-//! Per-run cap enforcement (SPEC.md B-01, E-19, E-20): every Store
-//! installs an epoch-deadline callback for wall-clock timeout and a
-//! [`ResourceLimiter`] for the linear-memory cap. Wasmtime turns
-//! limiter / callback errors into traps; `Instance::run` downcasts the
-//! trap source to surface as `Kobako::Wasm::TimeoutError` or
+//! Per-run cap enforcement (docs/behavior.md B-01, E-19, E-20): every
+//! Store installs an epoch-deadline callback for wall-clock timeout and
+//! a [`ResourceLimiter`] for the linear-memory cap. Wasmtime turns
+//! limiter / callback errors into traps; the run-path methods downcast
+//! the trap source to surface as `Kobako::Wasm::TimeoutError` or
 //! `Kobako::Wasm::MemoryLimitError` so the `Sandbox` layer can map them
 //! to the named `Kobako::TrapError` subclasses.
 //!
@@ -53,7 +58,7 @@ use wasmtime_wasi::WasiCtxBuilder;
 use super::cache::{cached_module, shared_engine};
 use super::dispatch;
 use super::host_state::{HostState, MemoryLimitTrap, StoreCell, TimeoutTrap};
-use super::{memory_limit_err, timeout_err, wasm_err};
+use super::{memory_limit_err, rstring_to_vec, timeout_err, wasm_err};
 
 #[magnus::wrap(class = "Kobako::Wasm::Instance", free_immediately, size)]
 pub(crate) struct Instance {
@@ -66,14 +71,16 @@ pub(crate) struct Instance {
     //
     // `__kobako_alloc` is NOT cached here — only `dispatch.rs` calls it,
     // and it does so through `Caller::get_export` on the wasmtime side.
-    run: Option<TypedFunc<(), ()>>,
+    eval: Option<TypedFunc<(), ()>>,
+    run: Option<TypedFunc<(i32, i32), ()>>,
     take_outcome: Option<TypedFunc<(), u64>>,
-    // Wall-clock cap for one guest `#run` (SPEC.md B-01); `None` disables
+    // Wall-clock cap for one guest `#run` (docs/behavior.md B-01); `None` disables
     // the cap. Translated into an `Instant`-based deadline stamped into
-    // [`HostState`] at the top of every `Instance::run`.
+    // [`HostState`] at the top of every `Instance::eval`.
     timeout: Option<Duration>,
-    // Per-channel byte caps for guest stdout / stderr capture (SPEC.md
-    // B-01 / B-04). `None` disables the cap on that channel. Read by
+    // Per-channel byte caps for guest stdout / stderr capture
+    // (docs/behavior.md B-01 / B-04). `None` disables the cap on that
+    // channel. Read by
     // [`Instance::refresh_wasi`] to size the MemoryOutputPipe and by
     // [`Instance::stdout`] / [`Instance::stderr`] to compute the
     // truncation flag. See the module-level note above for the `cap + 1`
@@ -91,10 +98,10 @@ impl Instance {
     /// constructor for `Kobako::Wasm::Instance` — Engine and Module are
     /// never visible to Ruby.
     ///
-    /// `timeout_seconds` is the SPEC.md B-01 wall-clock cap in seconds
+    /// `timeout_seconds` is the docs/behavior.md B-01 wall-clock cap in seconds
     /// (`None` disables); `memory_limit` is the linear-memory cap in
     /// bytes (`None` disables); `stdout_limit_bytes` / `stderr_limit_bytes`
-    /// are the per-channel output caps (SPEC.md B-01 / B-04; `None`
+    /// are the per-channel output caps (docs/behavior.md B-01 / B-04; `None`
     /// disables). All four are validated by the caller
     /// (`Kobako::Sandbox`); this method only refuses non-finite or
     /// non-positive timeouts as a defence in depth.
@@ -112,7 +119,7 @@ impl Instance {
             Some(secs) => {
                 return Err(wasm_err(
                     &ruby,
-                    format!("timeout_seconds must be > 0 and finite, got {secs}"),
+                    format!("timeout must be > 0 and finite, got {secs} seconds"),
                 ));
             }
         };
@@ -151,13 +158,20 @@ impl Instance {
 
         // Wire the wasmtime-wasi preview1 WASI imports. Routes guest fd 1/2
         // to the MemoryOutputPipes set up before each run via
-        // `Instance::run`. The closure pulls a `&mut WasiP1Ctx` out of
+        // `Instance::eval`. The closure pulls a `&mut WasiP1Ctx` out of
         // HostState; the panic semantics live inside `HostState::wasi_mut`
         // so the wiring stays honest about its precondition.
-        p1::add_to_linker_sync(&mut linker, |state: &mut HostState| state.wasi_mut())
-            .map_err(|e| wasm_err(&ruby, format!("add WASI p1 to linker: {}", e)))?;
+        p1::add_to_linker_sync(&mut linker, |state: &mut HostState| state.wasi_mut()).map_err(
+            |e| {
+                wasm_err(
+                    &ruby,
+                    format!("failed to wire WASI runtime into Sandbox: {}", e),
+                )
+            },
+        )?;
 
-        // `__kobako_dispatch` host import. Signature per SPEC Wire ABI:
+        // `__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
         // `Kobako::RPC::Server` (set per-run via `set_server`), allocates a
@@ -173,7 +187,12 @@ impl Instance {
                     dispatch::handle(&mut caller, req_ptr, req_len)
                 },
             )
-            .map_err(|e| wasm_err(&ruby, format!("define __kobako_dispatch: {}", e)))?;
+            .map_err(|e| {
+                wasm_err(
+                    &ruby,
+                    format!("failed to register host RPC dispatch import: {}", e),
+                )
+            })?;
 
         let instance = {
             let mut store_ref = store_cell.borrow_mut();
@@ -186,22 +205,28 @@ impl Instance {
         // (test fixture is a bare module); the host enforces presence at
         // invocation time by raising a Ruby `Kobako::Wasm::Error` when the
         // cached Option is None. Only the SPEC ABI `() -> ()` shape is
-        // accepted for `__kobako_run`.
-        let (run, take_outcome) = {
+        // accepted for `__kobako_eval`; `__kobako_run` takes
+        // `(env_ptr, env_len) -> ()` per docs/wire-codec.md § ABI
+        // Signatures.
+        let (eval, run, take_outcome) = {
             let mut store_ref = store_cell.borrow_mut();
             let mut ctx = store_ref.as_context_mut();
+            let eval = instance
+                .get_typed_func::<(), ()>(&mut ctx, "__kobako_eval")
+                .ok();
             let run = instance
-                .get_typed_func::<(), ()>(&mut ctx, "__kobako_run")
+                .get_typed_func::<(i32, i32), ()>(&mut ctx, "__kobako_run")
                 .ok();
             let take_outcome = instance
                 .get_typed_func::<(), u64>(&mut ctx, "__kobako_take_outcome")
                 .ok();
-            (run, take_outcome)
+            (eval, run, take_outcome)
         };
 
         Ok(Self {
             inner: instance,
             store: store_cell,
+            eval,
             run,
             take_outcome,
             timeout,
@@ -227,25 +252,63 @@ impl Instance {
     // taxonomy.
     // -----------------------------------------------------------------
 
-    /// Execute one guest run.
+    /// Execute one guest invocation (`__kobako_eval` — one-shot source).
     ///
     /// Rebuilds the WASI context with fresh stdin / stdout / stderr pipes
-    /// (the two-frame stdin protocol carries +preamble+ then +source+ —
-    /// SPEC.md ABI Signatures), then invokes `__kobako_run`. Per-run
-    /// caps (SPEC.md B-01) are primed here: the wall-clock deadline is
-    /// stamped into [`HostState`] and the epoch deadline is set to fire
-    /// at the next ticker tick; the memory-cap limiter is already wired.
-    pub(crate) fn run(&self, preamble: RString, source: RString) -> Result<(), MagnusError> {
+    /// (the three-frame stdin protocol carries +preamble+, +source+, then
+    /// +snippets+ — docs/wire-codec.md § Invocation channels), then
+    /// invokes `__kobako_eval`. Per-invocation caps (docs/behavior.md
+    /// B-01) are primed here: the wall-clock deadline is stamped into
+    /// [`HostState`] and the epoch deadline is set to fire at the next
+    /// ticker tick; the memory-cap limiter is already wired.
+    pub(crate) fn eval(
+        &self,
+        preamble: RString,
+        source: RString,
+        snippets: RString,
+    ) -> Result<(), MagnusError> {
+        let ruby = Ruby::get().expect("Ruby thread");
+        let eval = require_export(&ruby, self.eval.as_ref(), "__kobako_eval")?;
+        self.refresh_wasi(&[
+            rstring_to_vec(preamble),
+            rstring_to_vec(source),
+            rstring_to_vec(snippets),
+        ]);
+        self.prime_caps();
+        let result = {
+            let mut store_ref = self.store.borrow_mut();
+            eval.call(store_ref.as_context_mut(), ())
+        };
+        self.disarm_caps();
+        result.map_err(|e| call_err(&ruby, e))
+    }
+
+    /// Execute one entrypoint dispatch (`__kobako_run`).
+    ///
+    /// Rebuilds the WASI context with the two-frame stdin protocol
+    /// (preamble + snippets; no user source frame — docs/wire-codec.md
+    /// § Invocation channels), copies +envelope+ bytes into guest linear
+    /// memory via `__kobako_alloc`, and calls `__kobako_run(env_ptr,
+    /// env_len)`. Per-invocation cap semantics match [`Instance::eval`].
+    /// Returns +Kobako::Wasm::Error+ ("alloc returned 0") when guest
+    /// allocation fails (docs/behavior.md E-31).
+    pub(crate) fn run(
+        &self,
+        preamble: RString,
+        snippets: RString,
+        envelope: RString,
+    ) -> Result<(), MagnusError> {
         let ruby = Ruby::get().expect("Ruby thread");
-        let run = self
-            .run
-            .as_ref()
-            .ok_or_else(|| wasm_err(&ruby, "guest does not export __kobako_run"))?;
-        self.refresh_wasi(preamble, source)?;
+        let run = require_export(&ruby, self.run.as_ref(), "__kobako_run")?;
+        self.refresh_wasi(&[rstring_to_vec(preamble), rstring_to_vec(snippets)]);
+        let (env_ptr, env_len) = self.write_envelope(&ruby, envelope)?;
         self.prime_caps();
-        let result = self.call_guest(run);
+        let result = {
+            let mut store_ref = self.store.borrow_mut();
+            run.call(store_ref.as_context_mut(), (env_ptr, env_len))
+        };
         self.disarm_caps();
-        result.map_err(|e| run_call_err(&ruby, e))
+        result.map_err(|e| call_err(&ruby, e))
     }
 
     /// Return the stdout capture from the most recent run as a Ruby
@@ -282,15 +345,61 @@ impl Instance {
         Ok(ruby.str_from_slice(&bytes))
     }
 
+    /// Return the docs/behavior.md B-35 per-last-invocation usage as a
+    /// Ruby 2-tuple `[wall_time, memory_peak]`. The element order
+    /// matches the `Kobako::Usage` field order declared in
+    /// `lib/kobako/usage.rb`; reorder both sides together if the field
+    /// list ever grows.
+    ///
+    ///   * `wall_time` (Float seconds) — the wall-clock duration the
+    ///     most recent invocation spent inside the guest export call.
+    ///     Bracket opens in [`Instance::prime_caps`] and closes in
+    ///     [`Instance::disarm_caps`], so the value mirrors the
+    ///     `timeout` deadline accounting and excludes everything that
+    ///     runs after the guest export returns — the post-export
+    ///     `OUTCOME_BUFFER` fetch and decode, plus stdout / stderr
+    ///     capture readout. `0.0` before the first invocation.
+    ///   * `memory_peak` (Integer bytes) — the high-water mark of the
+    ///     per-invocation `memory.grow` delta past the linear-memory
+    ///     size captured at invocation entry. `0` before the first
+    ///     invocation.
+    ///
+    /// Packing both readers into one ext call mirrors the
+    /// [`Instance::stdout`] / [`Instance::stderr`] pattern: one
+    /// `store.borrow()` per readout and a single magnus binding to
+    /// extend when B-35's field list grows past two.
+    pub(crate) fn usage(&self) -> Result<RArray, MagnusError> {
+        let ruby = Ruby::get().expect("Ruby thread");
+        let state = self.store.borrow();
+        let data = state.data();
+        let arr = ruby.ary_new_capa(2);
+        arr.push(data.wall_time().as_secs_f64())?;
+        arr.push(data.memory_peak())?;
+        Ok(arr)
+    }
+
     // -----------------------------------------------------------------
     // Private helpers.
     // -----------------------------------------------------------------
 
-    /// Stamp the per-run wall-clock deadline into [`HostState`] and prime
-    /// the wasmtime epoch deadline so the next ticker tick wakes the
-    /// epoch-deadline callback. When `timeout` is disabled, the deadline
-    /// is set far enough in the future that the callback effectively
-    /// never fires.
+    /// Stamp the per-invocation wall-clock deadline into [`HostState`]
+    /// and prime the wasmtime epoch deadline so the next ticker tick
+    /// wakes the epoch-deadline callback. When `timeout` is disabled,
+    /// the deadline is set far enough in the future that the callback
+    /// effectively never fires.
+    ///
+    /// Also captures the current linear-memory size as the baseline
+    /// for the docs/behavior.md E-20 per-invocation memory delta cap.
+    /// The mruby image's declared initial allocation and the high-water
+    /// mark left by prior invocations on the same Sandbox are folded
+    /// into the baseline rather than the budget — only `memory.grow`
+    /// past +baseline+ counts against `memory_limit`.
+    ///
+    /// Also stamps the wall-clock entry instant for the
+    /// docs/behavior.md B-35 `wall_time` measurement. The bracket
+    /// closes in [`Instance::disarm_caps`] so it matches the
+    /// `timeout` deadline window and excludes `OUTCOME_BUFFER`
+    /// decoding and stdout / stderr capture readout.
     fn prime_caps(&self) {
         let mut store_ref = self.store.borrow_mut();
         match self.timeout {
@@ -304,52 +413,80 @@ impl Instance {
                 store_ref.set_epoch_deadline(u64::MAX);
             }
         }
-        store_ref.data_mut().limiter_mut().activate();
+        let baseline = match self.inner.get_export(store_ref.as_context_mut(), "memory") {
+            Some(Extern::Memory(m)) => m.data_size(store_ref.as_context_mut()),
+            _ => 0,
+        };
+        store_ref.data_mut().arm_memory_cap(baseline);
+        store_ref.data_mut().start_wall_clock();
     }
 
     /// Drop the memory cap as soon as the guest call returns so that
     /// any 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 [`Instance::prime_caps`].
+    /// the user script. Also closes the docs/behavior.md B-35
+    /// `wall_time` bracket opened by [`Instance::prime_caps`]. Paired
+    /// with [`Instance::prime_caps`].
     fn disarm_caps(&self) {
-        self.store
-            .borrow_mut()
-            .data_mut()
-            .limiter_mut()
-            .deactivate();
+        let mut store_ref = self.store.borrow_mut();
+        store_ref.data_mut().stop_wall_clock();
+        store_ref.data_mut().disarm_memory_cap();
     }
 
-    /// Invoke the cached `__kobako_run` TypedFunc against the live
-    /// Store. Lives in its own helper so [`Instance::run`] reads as
-    /// the run-path outline (export check → refresh WASI → prime caps
-    /// → call guest → disarm caps → map errors) without the
-    /// `RefCell::borrow_mut` boilerplate inline.
-    fn call_guest(&self, run: &TypedFunc<(), ()>) -> wasmtime::Result<()> {
+    /// Allocate a +len+-byte buffer in guest linear memory via
+    /// `__kobako_alloc`, copy +envelope+ into it, and return +(ptr, len)+
+    /// as +i32+ values matching the `__kobako_run(env_ptr, env_len)` ABI.
+    /// Raises +Kobako::Wasm::Error+ when the guest export is missing or
+    /// allocation fails (docs/behavior.md E-31).
+    fn write_envelope(&self, ruby: &Ruby, envelope: RString) -> Result<(i32, i32), MagnusError> {
+        let bytes = rstring_to_vec(envelope);
+        let len_i32 = envelope_len_to_i32(bytes.len()).map_err(|msg| wasm_err(ruby, msg))?;
+
         let mut store_ref = self.store.borrow_mut();
-        run.call(store_ref.as_context_mut(), ())
-    }
-
-    /// Rebuild the WASI context with fresh stdin (two-frame: preamble then
-    /// source) plus fresh stdout/stderr pipes. Called at the top of every
-    /// `#run`. Each pipe is sized at `cap + 1` so [`Instance::stdout`] /
-    /// [`Instance::stderr`] can distinguish "wrote exactly cap bytes"
-    /// from "exceeded cap"; uncapped channels fall back to `usize::MAX`
-    /// and rely on `memory_limit` (E-20) for the real ceiling.
-    fn refresh_wasi(&self, preamble: RString, source: RString) -> Result<(), MagnusError> {
-        // SAFETY: `as_slice` borrows are scoped to building the stdin Vec
-        // below — no Ruby allocations happen between the borrow and the
-        // copy, so the underlying RString cannot move.
-        let preamble_bytes: &[u8] = unsafe { preamble.as_slice() };
-        let source_bytes: &[u8] = unsafe { source.as_slice() };
-
-        let mut stdin_content: Vec<u8> =
-            Vec::with_capacity(4 + preamble_bytes.len() + 4 + source_bytes.len());
-        // Frame 1 — preamble
-        stdin_content.extend_from_slice(&(preamble_bytes.len() as u32).to_be_bytes());
-        stdin_content.extend_from_slice(preamble_bytes);
-        // Frame 2 — user script
-        stdin_content.extend_from_slice(&(source_bytes.len() as u32).to_be_bytes());
-        stdin_content.extend_from_slice(source_bytes);
+        let alloc: TypedFunc<u32, u32> = self
+            .inner
+            .get_typed_func(store_ref.as_context_mut(), "__kobako_alloc")
+            .map_err(|_| wasm_err(ruby, SANDBOX_RUNTIME_MISSING_HOOKS))?;
+        let ptr = alloc
+            .call(store_ref.as_context_mut(), bytes.len() as u32)
+            .map_err(|e| wasm_err(ruby, format!("failed to allocate input buffer: {}", e)))?;
+        if ptr == 0 {
+            return Err(wasm_err(
+                ruby,
+                "could not allocate input buffer (out of memory)",
+            ));
+        }
+
+        let memory: Memory = match self.inner.get_export(store_ref.as_context_mut(), "memory") {
+            Some(Extern::Memory(m)) => m,
+            _ => return Err(wasm_err(ruby, SANDBOX_RUNTIME_NOT_KOBAKO)),
+        };
+        let data = memory.data_mut(store_ref.as_context_mut());
+        let range = guest_buffer_range(ptr as usize, bytes.len(), data.len())
+            .map_err(|msg| wasm_err(ruby, msg))?;
+        data[range].copy_from_slice(&bytes);
+
+        Ok((ptr as i32, len_i32))
+    }
+
+    /// Rebuild the WASI context with fresh stdin (carrying every frame in
+    /// +frames+, each prefixed by its 4-byte big-endian u32 length —
+    /// docs/wire-codec.md § Invocation channels) plus fresh stdout / stderr
+    /// pipes. Called at the top of every guest invocation: +#eval+ passes
+    /// three frames (preamble, source, snippets), +#run+ passes two
+    /// (preamble, snippets — the invocation envelope arrives via linear
+    /// memory instead). Each output pipe is sized at `cap + 1` so
+    /// [`Instance::stdout`] / [`Instance::stderr`] can distinguish "wrote
+    /// exactly cap bytes" from "exceeded cap"; uncapped channels fall back
+    /// to `usize::MAX` and rely on `memory_limit` (docs/behavior.md E-20)
+    /// for the real ceiling.
+    fn refresh_wasi(&self, frames: &[Vec<u8>]) {
+        let total: usize = frames.iter().map(|f| 4 + f.len()).sum();
+        let mut stdin_content: Vec<u8> = Vec::with_capacity(total);
+        for frame in frames {
+            stdin_content.extend_from_slice(&(frame.len() as u32).to_be_bytes());
+            stdin_content.extend_from_slice(frame);
+        }
 
         let stdin_pipe = MemoryInputPipe::new(stdin_content);
         let stdout_pipe = MemoryOutputPipe::new(pipe_capacity(self.stdout_limit_bytes));
@@ -365,8 +502,6 @@ impl Instance {
             .borrow_mut()
             .data_mut()
             .install_wasi(wasi, stdout_pipe, stderr_pipe);
-
-        Ok(())
     }
 
     /// Invoke `__kobako_take_outcome`, decode the packed +(ptr<<32)|len+
@@ -375,39 +510,94 @@ impl Instance {
     /// arithmetic overflows, the slice falls outside live memory, or the
     /// `memory` export itself is absent.
     fn fetch_outcome_bytes(&self, ruby: &Ruby) -> Result<Vec<u8>, MagnusError> {
-        let take = self
-            .take_outcome
-            .as_ref()
-            .ok_or_else(|| wasm_err(ruby, "guest does not export __kobako_take_outcome"))?;
+        let take = require_export(ruby, self.take_outcome.as_ref(), "__kobako_take_outcome")?;
 
         let mut store_ref = self.store.borrow_mut();
         let packed = take
             .call(store_ref.as_context_mut(), ())
-            .map_err(|e| wasm_err(ruby, format!("__kobako_take_outcome(): {}", e)))?;
-        let ptr = ((packed >> 32) & 0xffff_ffff) as usize;
-        let len = (packed & 0xffff_ffff) as usize;
+            .map_err(|e| wasm_err(ruby, format!("failed to read invocation result: {}", e)))?;
+        let (ptr, len) = unpack_outcome_packed(packed);
 
         let mem: Memory = match self.inner.get_export(store_ref.as_context_mut(), "memory") {
             Some(Extern::Memory(m)) => m,
-            _ => return Err(wasm_err(ruby, "guest does not export 'memory'")),
+            _ => return Err(wasm_err(ruby, SANDBOX_RUNTIME_NOT_KOBAKO)),
         };
         let data = mem.data(store_ref.as_context_mut());
-        let end = ptr
-            .checked_add(len)
-            .ok_or_else(|| wasm_err(ruby, "outcome: ptr + len overflow"))?;
-        if end > data.len() {
-            return Err(wasm_err(
-                ruby,
-                format!(
-                    "outcome: range [{}, {}) exceeds memory size {}",
-                    ptr,
-                    end,
-                    data.len()
-                ),
-            ));
-        }
-        Ok(data[ptr..end].to_vec())
+        let range = guest_buffer_range(ptr, len, data.len()).map_err(|msg| {
+            wasm_err(ruby, format!("invocation result is out of bounds: {}", msg))
+        })?;
+        Ok(data[range].to_vec())
+    }
+}
+
+/// User-facing message for the "Sandbox runtime is missing one of the
+/// internal Kobako hooks" failure mode. Phrased in caller vocabulary —
+/// the underlying ABI symbol names (`__kobako_alloc`, `__kobako_eval`,
+/// `__kobako_take_outcome`) are not actionable to callers, and the
+/// gem itself raises this error so a self-reference like "matches the
+/// kobako gem version" reads as third-person. The actionable
+/// diagnosis is "your data/kobako.wasm is out of sync; rebuild it".
+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 = "Sandbox runtime does not export linear memory; \
+     this is not a Kobako-compatible Wasm module";
+
+/// Return the cached +TypedFunc+ for an ABI export, or raise
+/// +Kobako::Wasm::Error+ when the option is +None+. The run-path
+/// methods (+#eval+, +#run+, +#outcome!+) all share the same
+/// "missing export → Ruby error" boilerplate; this helper collapses
+/// the three sites onto one safe entry. The +_name+ argument is
+/// retained for future operator-side logging but is deliberately not
+/// spliced into the user-facing message (see
+/// [`SANDBOX_RUNTIME_MISSING_HOOKS`]).
+fn require_export<'a, Params, Results>(
+    ruby: &Ruby,
+    export: Option<&'a TypedFunc<Params, Results>>,
+    _name: &str,
+) -> Result<&'a TypedFunc<Params, Results>, MagnusError>
+where
+    Params: wasmtime::WasmParams,
+    Results: wasmtime::WasmResults,
+{
+    export.ok_or_else(|| wasm_err(ruby, SANDBOX_RUNTIME_MISSING_HOOKS))
+}
+
+/// Validate the invocation envelope length and return it as +i32+ — the
+/// signed wasm ABI parameter type for the guest-run entrypoint.
+/// Rejects sizes above +i32::MAX+ (2 GiB) so the downstream cast cannot
+/// silently wrap.
+fn envelope_len_to_i32(len: usize) -> Result<i32, &'static str> {
+    i32::try_from(len).map_err(|_| "invocation payload exceeds 2 GiB")
+}
+
+/// Compute the half-open range `[ptr, ptr + len)` for a guest linear-memory
+/// copy, validating that the arithmetic does not overflow and the range
+/// fits inside `mem_size`. Shared by [`Instance::write_envelope`] (write
+/// side) and [`Instance::fetch_outcome_bytes`] (read side).
+fn guest_buffer_range(
+    ptr: usize,
+    len: usize,
+    mem_size: usize,
+) -> Result<core::ops::Range<usize>, &'static str> {
+    let end = ptr.checked_add(len).ok_or("ptr + len overflow")?;
+    if end > mem_size {
+        return Err("range exceeds Sandbox memory size");
     }
+    Ok(ptr..end)
+}
+
+/// Unpack the `(ptr, len)` u64 returned by `__kobako_take_outcome`:
+/// high 32 bits = ptr, low 32 bits = len. Mirrors the guest-side
+/// `crate::abi::unpack_u64` in `wasm/kobako-wasm/src/abi.rs`.
+fn unpack_outcome_packed(packed: u64) -> (usize, usize) {
+    let ptr = (packed >> 32) as u32 as usize;
+    let len = packed as u32 as usize;
+    (ptr, len)
 }
 
 /// Translate a per-channel byte cap into the MemoryOutputPipe capacity:
@@ -446,6 +636,104 @@ fn capture_pair(ruby: &Ruby, raw: &[u8], cap: Option<usize>) -> Result<RArray, M
     Ok(arr)
 }
 
+/// Epoch-deadline callback installed on every Store. Read the per-run
+/// wall-clock deadline from [`HostState`] (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
+/// `Instance::eval` / `Instance::run` flow because
+/// `set_epoch_deadline(u64::MAX)` is used; returning a long extension
+/// keeps the callback inert as a defence in depth.
+fn epoch_deadline_callback(
+    ctx: StoreContextMut<'_, HostState>,
+) -> 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::Wasm::TimeoutError` / `MemoryLimitError` /
+/// `Kobako::Wasm::Error` 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::Wasm::Error`.
+    Other,
+}
+
+/// Inspect a wasmtime error to decide which `Kobako::Wasm::*` 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 `Kobako::Wasm::*` 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.
+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 => wasm_err(ruby, format!("{}", err)),
+    }
+}
+
+/// Map an instantiation error to the right `Kobako::Wasm::*` Ruby
+/// exception. The memory cap is dormant during instantiation by design
+/// (see [`HostState::arm_memory_cap`] / [`HostState::disarm_memory_cap`]),
+/// but [`MemoryLimitTrap`] is still possible if a future Sandbox
+/// configuration enables it during instantiation — keep the mapping
+/// symmetric with [`call_err`]. [`TrapClass::Timeout`] is unreachable on
+/// the instantiation path (the epoch deadline is not armed yet) but
+/// folding it into the same `match` keeps the two paths visually paired.
+fn instantiate_err(ruby: &Ruby, err: wasmtime::Error) -> MagnusError {
+    let msg = format!("instantiate: {}", err);
+    match classify_trap(&err) {
+        TrapClass::MemoryLimit => memory_limit_err(ruby, msg),
+        TrapClass::Timeout | TrapClass::Other => wasm_err(ruby, msg),
+    }
+}
+
 #[cfg(test)]
 mod tests {
     //! Host-side unit tests for the pure capture helpers. The Ruby-
@@ -453,7 +741,11 @@ mod tests {
     //! allowlist excludes guest fd 2 writes); these tests pin the
     //! channel-agnostic slicing so a regression that only breaks one
     //! channel cannot sneak through.
-    use super::{clip_capture, pipe_capacity};
+    use super::{
+        classify_trap, clip_capture, envelope_len_to_i32, guest_buffer_range, pipe_capacity,
+        unpack_outcome_packed, TrapClass,
+    };
+    use super::{MemoryLimitTrap, TimeoutTrap};
 
     #[test]
     fn pipe_capacity_adds_one_when_cap_is_set() {
@@ -508,49 +800,74 @@ mod tests {
         assert_eq!(bytes, b"");
         assert!(!truncated);
     }
-}
 
-/// Epoch-deadline callback installed on every Store. Read the per-run
-/// wall-clock deadline from [`HostState`] (SPEC.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
-/// `Instance::run` flow because `set_epoch_deadline(u64::MAX)` is used;
-/// returning a long extension keeps the callback inert as a defence in
-/// depth.
-fn epoch_deadline_callback(
-    ctx: StoreContextMut<'_, HostState>,
-) -> 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)),
+    #[test]
+    fn envelope_len_to_i32_accepts_zero_and_max() {
+        assert_eq!(envelope_len_to_i32(0), Ok(0));
+        assert_eq!(envelope_len_to_i32(i32::MAX as usize), Ok(i32::MAX));
     }
-}
 
-/// Map a wasmtime call error to the right `Kobako::Wasm::*` Ruby
-/// exception class. `__kobako_run` traps are downcast to identify the
-/// configured-cap path (SPEC.md E-19 / E-20); everything else surfaces
-/// as the base `Kobako::Wasm::Error`.
-fn run_call_err(ruby: &Ruby, err: wasmtime::Error) -> MagnusError {
-    if err.downcast_ref::<TimeoutTrap>().is_some() {
-        return timeout_err(ruby, format!("__kobako_run(): {}", err));
+    #[test]
+    fn envelope_len_to_i32_rejects_past_i32_max() {
+        assert!(envelope_len_to_i32(i32::MAX as usize + 1).is_err());
+        assert!(envelope_len_to_i32(usize::MAX).is_err());
     }
-    if err.downcast_ref::<MemoryLimitTrap>().is_some() {
-        return memory_limit_err(ruby, format!("__kobako_run(): {}", err));
+
+    #[test]
+    fn guest_buffer_range_returns_half_open_range() {
+        // Standard case: ptr + len fits inside memory.
+        assert_eq!(guest_buffer_range(10, 5, 100), Ok(10..15));
     }
-    wasm_err(ruby, format!("__kobako_run(): {}", err))
-}
 
-/// Map an instantiation error to the right `Kobako::Wasm::*` Ruby
-/// exception. The memory cap is dormant during instantiation by design
-/// (see [`HostState::set_memory_cap_active`]), but [`MemoryLimitTrap`]
-/// is still possible if a future Sandbox configuration enables it
-/// during instantiation — keep the mapping symmetric with
-/// [`run_call_err`].
-fn instantiate_err(ruby: &Ruby, err: wasmtime::Error) -> MagnusError {
-    if err.downcast_ref::<MemoryLimitTrap>().is_some() {
-        return memory_limit_err(ruby, format!("instantiate: {}", err));
+    #[test]
+    fn guest_buffer_range_accepts_zero_length_at_any_in_bounds_ptr() {
+        // Zero-length writes / reads must succeed as long as ptr is in
+        // bounds — both reactor calls hand zero-length frames through
+        // (e.g. an empty Frame 3 snippets list).
+        assert_eq!(guest_buffer_range(0, 0, 0), Ok(0..0));
+        assert_eq!(guest_buffer_range(42, 0, 100), Ok(42..42));
+    }
+
+    #[test]
+    fn guest_buffer_range_rejects_ptr_plus_len_overflow() {
+        assert!(guest_buffer_range(usize::MAX, 1, usize::MAX).is_err());
+    }
+
+    #[test]
+    fn guest_buffer_range_rejects_end_past_memory() {
+        assert!(guest_buffer_range(10, 100, 50).is_err());
+        // End exactly equal to mem_size is in-bounds.
+        assert_eq!(guest_buffer_range(0, 50, 50), Ok(0..50));
+    }
+
+    #[test]
+    fn unpack_outcome_packed_extracts_high_ptr_low_len() {
+        assert_eq!(
+            unpack_outcome_packed(0xAABB_CCDD_1122_3344),
+            (0xAABB_CCDD, 0x1122_3344)
+        );
+    }
+
+    #[test]
+    fn unpack_outcome_packed_zero_decodes_to_zero_pair() {
+        assert_eq!(unpack_outcome_packed(0), (0, 0));
+    }
+
+    #[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);
     }
-    wasm_err(ruby, format!("instantiate: {}", err))
 }