kobako 0.11.1 → 0.11.2

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

@@ -0,0 +1,188 @@
+//! Per-invocation byte-shuttle between Ruby and guest linear memory: it
+//! resolves the required `memory` / ABI-export handles, writes the `#run`
+//! envelope into a freshly allocated guest buffer, builds the stdin frame
+//! stream plus stdout / stderr capture pipes for the WASI context, and
+//! reads the OUTCOME_BUFFER back out. The ext owns no wire codec — these
+//! helpers move raw bytes; Ruby decodes them.
+
+use magnus::{Error as MagnusError, RString, Ruby};
+use wasmtime::{AsContextMut, Memory, Store as WtStore, TypedFunc};
+use wasmtime_wasi::p2::pipe::{MemoryInputPipe, MemoryOutputPipe};
+use wasmtime_wasi::WasiCtxBuilder;
+
+use super::config::Config;
+use super::exports::Exports;
+use super::invocation::Invocation;
+use super::rstring_to_vec;
+use super::{ambient, capture, errors, guest_mem};
+
+/// Return the resolved `memory` export handle, or raise
+/// `Kobako::TrapError` when the loaded module exports no linear
+/// memory — the "not a Kobako-shaped runtime" failure mode
+/// (`SANDBOX_RUNTIME_NOT_KOBAKO`).
+fn require_memory(ruby: &Ruby, exports: &Exports) -> Result<Memory, MagnusError> {
+    exports
+        .memory
+        .ok_or_else(|| errors::trap_err(ruby, SANDBOX_RUNTIME_NOT_KOBAKO))
+}
+
+/// 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::TrapError` when the allocation hook is missing or
+/// itself traps, and `Kobako::SandboxError` when the hook runs but
+/// cannot reserve the buffer (`__kobako_alloc` returns 0) — an
+/// intact runtime, not an engine fault.
+pub(crate) fn write_envelope(
+    ruby: &Ruby,
+    store: &mut WtStore<Invocation>,
+    exports: &Exports,
+    envelope: RString,
+) -> Result<(i32, i32), MagnusError> {
+    let bytes = rstring_to_vec(envelope);
+    let len_i32 =
+        guest_mem::checked_payload_len(bytes.len()).map_err(|msg| errors::trap_err(ruby, msg))?;
+
+    let alloc = require_export(ruby, exports.alloc.as_ref())?;
+    let memory = require_memory(ruby, exports)?;
+
+    let ptr = alloc
+        .call(store.as_context_mut(), bytes.len() as u32)
+        .map_err(|e| errors::trap_err(ruby, format!("failed to allocate input buffer: {}", e)))?;
+    if ptr == 0 {
+        return Err(errors::sandbox_err(
+            ruby,
+            "could not allocate input buffer (out of memory)",
+        ));
+    }
+    let data = memory.data_mut(store.as_context_mut());
+    let range = guest_mem::guest_buffer_range(ptr as usize, bytes.len(), data.len())
+        .map_err(|msg| errors::trap_err(ruby, msg))?;
+    data[range].copy_from_slice(&bytes);
+
+    Ok((ptr as i32, len_i32))
+}
+
+/// Build the per-invocation WASI context with 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, and install it on the invocation's Store. `#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
+/// `capture::clip_capture` can distinguish "wrote exactly cap bytes"
+/// from "exceeded cap"; uncapped channels fall back to `usize::MAX` and
+/// rely on `memory_limit` for the real ceiling.
+/// Raises `Kobako::TrapError` when any frame exceeds the 16 MiB cap that
+/// keeps its `u32` length prefix from wrapping.
+pub(crate) fn install_wasi_frames(
+    store: &mut WtStore<Invocation>,
+    config: &Config,
+    frames: &[Vec<u8>],
+) -> Result<(), MagnusError> {
+    let ruby = Ruby::get().expect("Ruby thread");
+    // Every frame carries the same 16 MiB cap as the `#run` envelope
+    // (`write_envelope`): the length prefix is a `u32`, so a frame past
+    // the cap would silently wrap and corrupt the stdin frame stream.
+    for frame in frames {
+        guest_mem::checked_payload_len(frame.len()).map_err(|msg| errors::trap_err(&ruby, msg))?;
+    }
+
+    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(capture::pipe_capacity(config.stdout_limit_bytes));
+    let stderr_pipe = MemoryOutputPipe::new(capture::pipe_capacity(config.stderr_limit_bytes));
+
+    let mut builder = WasiCtxBuilder::new();
+    builder.stdin(stdin_pipe);
+    builder.stdout(stdout_pipe.clone());
+    builder.stderr(stderr_pipe.clone());
+    // Deny the preview1 ambient-authority imports the guest never legitimately
+    // reaches but the WASI layer would otherwise grant (see `ambient`).
+    builder.wall_clock(ambient::FrozenWallClock);
+    builder.monotonic_clock(ambient::FrozenMonotonicClock);
+    builder.secure_random(ambient::deterministic_rng());
+    let wasi = builder.build_p1();
+
+    store
+        .data_mut()
+        .install_wasi(wasi, stdout_pipe, stderr_pipe);
+    Ok(())
+}
+
+/// Invoke `__kobako_take_outcome`, decode the packed `(ptr<<32)|len`
+/// u64, and copy the OUTCOME_BUFFER slice out of guest memory. Raises
+/// `Kobako::TrapError` when the export is missing, `len` exceeds the
+/// 16 MiB single-dispatch cap, the `ptr`/`len` arithmetic overflows,
+/// the slice falls outside live memory, or the `memory` export itself
+/// is absent.
+pub(crate) fn fetch_outcome_bytes(
+    ruby: &Ruby,
+    store: &mut WtStore<Invocation>,
+    exports: &Exports,
+) -> Result<Vec<u8>, MagnusError> {
+    let take = require_export(ruby, exports.take_outcome.as_ref())?;
+    let mem = require_memory(ruby, exports)?;
+
+    let packed = take
+        .call(store.as_context_mut(), ())
+        .map_err(|e| errors::trap_err(ruby, format!("failed to read the Sandbox result: {}", e)))?;
+    let (ptr, len) = guest_mem::unpack_outcome_packed(packed);
+    if len > guest_mem::MAX_DISPATCH_PAYLOAD {
+        return Err(errors::trap_err(
+            ruby,
+            "result payload exceeds the 16 MiB limit",
+        ));
+    }
+
+    let data = mem.data(store.as_context_mut());
+    let range = guest_mem::guest_buffer_range(ptr, len, data.len()).map_err(|msg| {
+        errors::trap_err(
+            ruby,
+            format!("the Sandbox 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 =
+    "the loaded Wasm module is not a Kobako-compatible runtime";
+
+/// Return the resolved `TypedFunc` for an ABI export, or raise
+/// `Kobako::TrapError` when the option is `None`. Both run-path
+/// methods (`#eval`, `#run`) plus the `build_snapshot` readout that
+/// drains `OUTCOME_BUFFER` share the same "missing export → Ruby
+/// error" boilerplate; this helper collapses those sites onto one
+/// safe entry. The user-facing message is intentionally export-
+/// agnostic (see `SANDBOX_RUNTIME_MISSING_HOOKS`) — the ABI symbol
+/// name is not actionable to callers, so it is not threaded in.
+pub(crate) fn require_export<'a, Params, Results>(
+    ruby: &Ruby,
+    export: Option<&'a TypedFunc<Params, Results>>,
+) -> Result<&'a TypedFunc<Params, Results>, MagnusError>
+where
+    Params: wasmtime::WasmParams,
+    Results: wasmtime::WasmResults,
+{
+    export.ok_or_else(|| errors::trap_err(ruby, SANDBOX_RUNTIME_MISSING_HOOKS))
+}

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

@@ -20,8 +20,9 @@ use wasmtime::{Caller, InstancePre, Linker};
 use wasmtime_wasi::p1;
 
 use super::cache::{cached_module, shared_engine};
+use super::errors::setup_err;
 use super::invocation::Invocation;
-use super::{dispatch, setup_err, trap};
+use super::{dispatch, trap};
 
 static INSTANCE_PRE_CACHE: OnceLock<Mutex<HashMap<PathBuf, InstancePre<Invocation>>>> =
     OnceLock::new();

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

@@ -13,8 +13,8 @@ use std::time::Instant;
 use magnus::{Error as MagnusError, Ruby};
 use wasmtime::{StoreContextMut, UpdateDeadline};
 
+use super::errors::{memory_limit_err, setup_err, timeout_err, trap_err};
 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` and trap with

data/ext/kobako/src/runtime.rs

@@ -42,16 +42,15 @@ mod cache;
 mod capture;
 mod config;
 mod dispatch;
+mod errors;
 mod exports;
+mod frames;
 mod guest_mem;
 mod instance_pre;
 mod invocation;
 mod trap;
 
-use magnus::value::Lazy;
-use magnus::{
-    function, method, prelude::*, Error as MagnusError, ExceptionClass, RModule, RString, Ruby,
-};
+use magnus::{function, method, prelude::*, Error as MagnusError, RModule, RString, Ruby};
 
 use std::cell::Cell;
 use std::path::Path;
@@ -61,11 +60,8 @@ use magnus::{gc, typed_data::DataTypeFunctions, value::Opaque, RArray, TypedData
 
 use crate::snapshot::Snapshot;
 use wasmtime::{
-    AsContextMut, InstancePre as WtInstancePre, Memory, ResourceLimiter, Store as WtStore,
-    TypedFunc,
+    AsContextMut, InstancePre as WtInstancePre, ResourceLimiter, Store as WtStore, TypedFunc,
 };
-use wasmtime_wasi::p2::pipe::{MemoryInputPipe, MemoryOutputPipe};
-use wasmtime_wasi::WasiCtxBuilder;
 
 use self::cache::shared_engine;
 use self::config::Config;
@@ -93,94 +89,6 @@ pub(crate) fn rstring_to_vec(s: RString) -> Vec<u8> {
     unsafe { s.as_slice() }.to_vec()
 }
 
-// ---------------------------------------------------------------------------
-// Error classes (lazy-resolved from Ruby once the top-level Kobako error
-// hierarchy is loaded by `lib/kobako/errors.rb`). The ext raises directly
-// into the invocation-outcome taxonomy (`TrapError` and its subclasses)
-// for run-path failures and into the construction-layer `SetupError`
-// (and its `ModuleNotBuiltError` subclass) for `from_path` setup failures
-// — no engine-specific intermediate layer; the Sandbox layer adds the
-// verb prefix and lets the subclass identity flow through unchanged.
-// ---------------------------------------------------------------------------
-
-/// Resolve `Kobako::<name>` as an `ExceptionClass` — the shared body of
-/// every error-class `Lazy` below, which differ only in the constant
-/// name. The constants are guaranteed present by the time any of these
-/// lazies first resolve (`lib/kobako/errors.rb` loads the hierarchy before
-/// the ext raises into it), so a missing constant is a build / wiring bug
-/// and the `unwrap` is the correct fail-fast.
-fn kobako_error_class(ruby: &Ruby, name: &str) -> ExceptionClass {
-    let kobako: RModule = ruby.class_object().const_get("Kobako").unwrap();
-    kobako.const_get(name).unwrap()
-}
-
-pub(crate) static SETUP_ERROR: Lazy<ExceptionClass> =
-    Lazy::new(|ruby| kobako_error_class(ruby, "SetupError"));
-
-pub(crate) static MODULE_NOT_BUILT_ERROR: Lazy<ExceptionClass> =
-    Lazy::new(|ruby| kobako_error_class(ruby, "ModuleNotBuiltError"));
-
-pub(crate) static TRAP_ERROR: Lazy<ExceptionClass> =
-    Lazy::new(|ruby| kobako_error_class(ruby, "TrapError"));
-
-pub(crate) static TIMEOUT_ERROR: Lazy<ExceptionClass> =
-    Lazy::new(|ruby| kobako_error_class(ruby, "TimeoutError"));
-
-pub(crate) static MEMORY_LIMIT_ERROR: Lazy<ExceptionClass> =
-    Lazy::new(|ruby| kobako_error_class(ruby, "MemoryLimitError"));
-
-pub(crate) static SANDBOX_ERROR: Lazy<ExceptionClass> =
-    Lazy::new(|ruby| kobako_error_class(ruby, "SandboxError"));
-
-/// Build a `MagnusError` in `class` carrying `msg` — the shared body of
-/// the named `*_err` constructors below, which differ only in which
-/// error-class `Lazy` they target.
-fn error_in(ruby: &Ruby, class: &Lazy<ExceptionClass>, msg: impl Into<String>) -> MagnusError {
-    MagnusError::new(ruby.get_inner(class), msg.into())
-}
-
-/// Construct a `Kobako::TrapError` magnus error. Used for every
-/// invocation-time wasmtime engine failure that is not a configured-cap
-/// trap — missing exports, allocation faults, memory write/read failures.
-/// Construction-time setup failures use `setup_err`, not this.
-pub(crate) fn trap_err(ruby: &Ruby, msg: impl Into<String>) -> MagnusError {
-    error_in(ruby, &TRAP_ERROR, msg)
-}
-
-/// Construct a `Kobako::SetupError` magnus error. Used for every
-/// construction-time failure on the `Runtime.from_path` path before any
-/// invocation runs — unreadable artifact, bytes that are not a valid Wasm
-/// module, or engine / linker / instantiation setup failure. The
-/// `ModuleNotBuiltError` subclass (artifact absent) is
-/// raised through `MODULE_NOT_BUILT_ERROR` directly.
-pub(crate) fn setup_err(ruby: &Ruby, msg: impl Into<String>) -> MagnusError {
-    error_in(ruby, &SETUP_ERROR, msg)
-}
-
-/// Construct a `Kobako::TimeoutError` magnus error. Surfaces the
-/// wall-clock cap path with the verb prefix added
-/// by `Kobako::Sandbox#invoke!`.
-pub(crate) fn timeout_err(ruby: &Ruby, msg: impl Into<String>) -> MagnusError {
-    error_in(ruby, &TIMEOUT_ERROR, msg)
-}
-
-/// Construct a `Kobako::MemoryLimitError` magnus error. Surfaces the
-/// linear-memory cap path with the verb prefix
-/// added by `Kobako::Sandbox#invoke!`.
-pub(crate) fn memory_limit_err(ruby: &Ruby, msg: impl Into<String>) -> MagnusError {
-    error_in(ruby, &MEMORY_LIMIT_ERROR, msg)
-}
-
-/// Construct a `Kobako::SandboxError` magnus error. Used for the
-/// host-side pre-call faults the SPEC attributes to the sandbox / wire
-/// layer rather than the Wasm engine — currently the `#run` invocation
-/// envelope reservation failure (`__kobako_alloc` returns 0).
-/// The runtime is intact, so this must not be a
-/// `TrapError`: no discard-and-recreate recovery is owed to the caller.
-pub(crate) fn sandbox_err(ruby: &Ruby, msg: impl Into<String>) -> MagnusError {
-    error_in(ruby, &SANDBOX_ERROR, msg)
-}
-
 // ---------------------------------------------------------------------------
 // Ruby init
 // ---------------------------------------------------------------------------
@@ -327,7 +235,7 @@ impl Runtime {
     /// `Invocation::wasi_mut`.
     fn probe_abi_version(&self, ruby: &Ruby) -> Result<(), MagnusError> {
         let mut store = self.new_store()?;
-        install_wasi_frames(&mut store, &self.config, &[])?;
+        frames::install_wasi_frames(&mut store, &self.config, &[])?;
         let instance = self
             .instance_pre
             .instantiate(store.as_context_mut())
@@ -335,7 +243,7 @@ impl Runtime {
         let probe = instance
             .get_typed_func::<(), u32>(store.as_context_mut(), "__kobako_abi_version")
             .map_err(|_| {
-                setup_err(
+                errors::setup_err(
                     ruby,
                     format!(
                         "the Guest Binary does not export __kobako_abi_version; \
@@ -344,13 +252,13 @@ impl Runtime {
                 )
             })?;
         let reported = probe.call(store.as_context_mut(), ()).map_err(|e| {
-            setup_err(
+            errors::setup_err(
                 ruby,
                 format!("failed to read the Guest Binary's ABI version: {e}"),
             )
         })?;
         if reported != ABI_VERSION {
-            return Err(setup_err(
+            return Err(errors::setup_err(
                 ruby,
                 format!(
                     "the Guest Binary reports ABI version {reported}, but this host \
@@ -396,14 +304,14 @@ impl Runtime {
 
         let bytes = rstring_to_vec(args_bytes);
         let Some(caller) = dispatch::current_caller() else {
-            return Err(trap_err(
+            return Err(errors::trap_err(
                 &ruby,
                 "yield_to_active_invocation called outside an active Sandbox dispatch frame",
             ));
         };
 
         let resp_bytes =
-            guest_mem::drive_yield(caller, &bytes).map_err(|msg| trap_err(&ruby, msg))?;
+            guest_mem::drive_yield(caller, &bytes).map_err(|msg| errors::trap_err(&ruby, msg))?;
         Ok(ruby.str_from_slice(&resp_bytes))
     }
 
@@ -438,7 +346,7 @@ impl Runtime {
     ) -> Result<Snapshot, MagnusError> {
         let ruby = Ruby::get().expect("Ruby thread");
         let mut store = self.new_store()?;
-        install_wasi_frames(
+        frames::install_wasi_frames(
             &mut store,
             &self.config,
             &[
@@ -448,7 +356,7 @@ impl Runtime {
             ],
         )?;
         let exports = self.instantiate(&ruby, &mut store)?;
-        let eval = require_export(&ruby, exports.eval.as_ref())?;
+        let eval = frames::require_export(&ruby, exports.eval.as_ref())?;
         self.call_with_caps(&mut store, &exports, eval, ())
             .map_err(|e| trap::call_err(&ruby, e))?;
         self.build_snapshot(&ruby, &mut store, &exports)
@@ -472,14 +380,14 @@ impl Runtime {
     ) -> Result<Snapshot, MagnusError> {
         let ruby = Ruby::get().expect("Ruby thread");
         let mut store = self.new_store()?;
-        install_wasi_frames(
+        frames::install_wasi_frames(
             &mut store,
             &self.config,
             &[rstring_to_vec(preamble), rstring_to_vec(snippets)],
         )?;
         let exports = self.instantiate(&ruby, &mut store)?;
-        let run = require_export(&ruby, exports.run.as_ref())?;
-        let (env_ptr, env_len) = write_envelope(&ruby, &mut store, &exports, envelope)?;
+        let run = frames::require_export(&ruby, exports.run.as_ref())?;
+        let (env_ptr, env_len) = frames::write_envelope(&ruby, &mut store, &exports, envelope)?;
         self.call_with_caps(&mut store, &exports, run, (env_ptr, env_len))
             .map_err(|e| trap::call_err(&ruby, e))?;
         self.build_snapshot(&ruby, &mut store, &exports)
@@ -544,7 +452,7 @@ impl Runtime {
             .instance_pre
             .instantiate(store.as_context_mut())
             .map_err(|e| {
-                trap_err(
+                errors::trap_err(
                     ruby,
                     format!("failed to instantiate the Sandbox runtime: {e}"),
                 )
@@ -630,7 +538,7 @@ impl Runtime {
         store: &mut WtStore<Invocation>,
         exports: &Exports,
     ) -> Result<Snapshot, MagnusError> {
-        let return_bytes = fetch_outcome_bytes(ruby, store, exports)?;
+        let return_bytes = frames::fetch_outcome_bytes(ruby, store, exports)?;
         let data = store.data();
         let (stdout_raw, stderr_raw, wall_time, memory_peak) = (
             data.stdout_bytes(),
@@ -666,170 +574,3 @@ fn disarm_caps(store: &mut WtStore<Invocation>) {
     store.data_mut().stop_wall_clock();
     store.data_mut().disarm_memory_cap();
 }
-
-/// Return the resolved `memory` export handle, or raise
-/// `Kobako::TrapError` when the loaded module exports no linear
-/// memory — the "not a Kobako-shaped runtime" failure mode
-/// (`SANDBOX_RUNTIME_NOT_KOBAKO`).
-fn require_memory(ruby: &Ruby, exports: &Exports) -> Result<Memory, MagnusError> {
-    exports
-        .memory
-        .ok_or_else(|| trap_err(ruby, SANDBOX_RUNTIME_NOT_KOBAKO))
-}
-
-/// 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::TrapError` when the allocation hook is missing or
-/// itself traps, and `Kobako::SandboxError` when the hook runs but
-/// cannot reserve the buffer (`__kobako_alloc` returns 0) — an
-/// intact runtime, not an engine fault.
-fn write_envelope(
-    ruby: &Ruby,
-    store: &mut WtStore<Invocation>,
-    exports: &Exports,
-    envelope: RString,
-) -> Result<(i32, i32), MagnusError> {
-    let bytes = rstring_to_vec(envelope);
-    let len_i32 = guest_mem::checked_payload_len(bytes.len()).map_err(|msg| trap_err(ruby, msg))?;
-
-    let alloc = require_export(ruby, exports.alloc.as_ref())?;
-    let memory = require_memory(ruby, exports)?;
-
-    let ptr = alloc
-        .call(store.as_context_mut(), bytes.len() as u32)
-        .map_err(|e| trap_err(ruby, format!("failed to allocate input buffer: {}", e)))?;
-    if ptr == 0 {
-        return Err(sandbox_err(
-            ruby,
-            "could not allocate input buffer (out of memory)",
-        ));
-    }
-    let data = memory.data_mut(store.as_context_mut());
-    let range = guest_mem::guest_buffer_range(ptr as usize, bytes.len(), data.len())
-        .map_err(|msg| trap_err(ruby, msg))?;
-    data[range].copy_from_slice(&bytes);
-
-    Ok((ptr as i32, len_i32))
-}
-
-/// Build the per-invocation WASI context with 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, and install it on the invocation's Store. `#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
-/// `capture::clip_capture` can distinguish "wrote exactly cap bytes"
-/// from "exceeded cap"; uncapped channels fall back to `usize::MAX` and
-/// rely on `memory_limit` for the real ceiling.
-/// Raises `Kobako::TrapError` when any frame exceeds the 16 MiB cap that
-/// keeps its `u32` length prefix from wrapping.
-fn install_wasi_frames(
-    store: &mut WtStore<Invocation>,
-    config: &Config,
-    frames: &[Vec<u8>],
-) -> Result<(), MagnusError> {
-    let ruby = Ruby::get().expect("Ruby thread");
-    // Every frame carries the same 16 MiB cap as the `#run` envelope
-    // (`write_envelope`): the length prefix is a `u32`, so a frame past
-    // the cap would silently wrap and corrupt the stdin frame stream.
-    for frame in frames {
-        guest_mem::checked_payload_len(frame.len()).map_err(|msg| trap_err(&ruby, msg))?;
-    }
-
-    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(capture::pipe_capacity(config.stdout_limit_bytes));
-    let stderr_pipe = MemoryOutputPipe::new(capture::pipe_capacity(config.stderr_limit_bytes));
-
-    let mut builder = WasiCtxBuilder::new();
-    builder.stdin(stdin_pipe);
-    builder.stdout(stdout_pipe.clone());
-    builder.stderr(stderr_pipe.clone());
-    // Deny the preview1 ambient-authority imports the guest never legitimately
-    // reaches but the WASI layer would otherwise grant (see `ambient`).
-    builder.wall_clock(ambient::FrozenWallClock);
-    builder.monotonic_clock(ambient::FrozenMonotonicClock);
-    builder.secure_random(ambient::deterministic_rng());
-    let wasi = builder.build_p1();
-
-    store
-        .data_mut()
-        .install_wasi(wasi, stdout_pipe, stderr_pipe);
-    Ok(())
-}
-
-/// Invoke `__kobako_take_outcome`, decode the packed `(ptr<<32)|len`
-/// u64, and copy the OUTCOME_BUFFER slice out of guest memory. Raises
-/// `Kobako::TrapError` when the export is missing, `len` exceeds the
-/// 16 MiB single-dispatch cap, the `ptr`/`len` arithmetic overflows,
-/// the slice falls outside live memory, or the `memory` export itself
-/// is absent.
-fn fetch_outcome_bytes(
-    ruby: &Ruby,
-    store: &mut WtStore<Invocation>,
-    exports: &Exports,
-) -> Result<Vec<u8>, MagnusError> {
-    let take = require_export(ruby, exports.take_outcome.as_ref())?;
-    let mem = require_memory(ruby, exports)?;
-
-    let packed = take
-        .call(store.as_context_mut(), ())
-        .map_err(|e| trap_err(ruby, format!("failed to read the Sandbox result: {}", e)))?;
-    let (ptr, len) = guest_mem::unpack_outcome_packed(packed);
-    if len > guest_mem::MAX_DISPATCH_PAYLOAD {
-        return Err(trap_err(ruby, "result payload exceeds the 16 MiB limit"));
-    }
-
-    let data = mem.data(store.as_context_mut());
-    let range = guest_mem::guest_buffer_range(ptr, len, data.len()).map_err(|msg| {
-        trap_err(
-            ruby,
-            format!("the Sandbox 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 =
-    "the loaded Wasm module is not a Kobako-compatible runtime";
-
-/// Return the resolved `TypedFunc` for an ABI export, or raise
-/// `Kobako::TrapError` when the option is `None`. Both run-path
-/// methods (`#eval`, `#run`) plus the `build_snapshot` readout that
-/// drains `OUTCOME_BUFFER` share the same "missing export → Ruby
-/// error" boilerplate; this helper collapses those sites onto one
-/// safe entry. The user-facing message is intentionally export-
-/// agnostic (see `SANDBOX_RUNTIME_MISSING_HOOKS`) — the ABI symbol
-/// name is not actionable to callers, so it is not threaded in.
-fn require_export<'a, Params, Results>(
-    ruby: &Ruby,
-    export: Option<&'a TypedFunc<Params, Results>>,
-) -> Result<&'a TypedFunc<Params, Results>, MagnusError>
-where
-    Params: wasmtime::WasmParams,
-    Results: wasmtime::WasmResults,
-{
-    export.ok_or_else(|| trap_err(ruby, SANDBOX_RUNTIME_MISSING_HOOKS))
-}

data/lib/kobako/catalog/handles.rb

@@ -43,9 +43,9 @@ module Kobako
       # and the allocator share the same invariant.
       #
       # Returning a Handle (rather than a bare Integer id) keeps the
-      # allocator's output a domain entity; +Kobako::Handle.restore+
-      # is reserved for the codec's wire-decode path, where the id is
-      # the only thing the bytes carry.
+      # allocator's output a domain entity. An id is the Handle's only
+      # content, so the same internal +Kobako::Handle.restore+ constructor
+      # serves both this allocator and the codec's wire-decode path.
       def alloc(object)
         reject_unwrappable!(object)
         ensure_capacity!
@@ -72,7 +72,7 @@ module Kobako
       end
 
       # Number of currently-bound entries. Used by tests of the Dispatcher
-      # and Codec::Utils#deep_wrap to observe whether each path allocates
+      # and Codec::HandleWalk#deep_wrap to observe whether each path allocates
       # exactly the Handle entries it should — the +Handles+ table itself never
       # consults its own size, but the surrounding code's allocation
       # contract is part of the observable boundary.