kobako 0.1.0

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

@@ -0,0 +1,110 @@
+//! Host-side dispatch for the `__kobako_rpc_call` import.
+//!
+//! 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::build_instance`].
+//! That closure delegates here. The dispatcher (SPEC.md B-12 / B-13):
+//!
+//!   1. Reads the Request bytes from guest linear memory.
+//!   2. Hands them to the Ruby-side `Kobako::Registry` and recovers
+//!      Response bytes.
+//!   3. Allocates a guest buffer via `__kobako_alloc(len)` invoked
+//!      through `Caller::get_export`.
+//!   4. Writes the Response bytes into the guest buffer.
+//!   5. Returns packed `(ptr<<32)|len` for the guest to decode.
+//!
+//! Returns 0 on any step failure. `Kobako::Sandbox` always installs a
+//! Registry before invoking the guest, so reaching the dispatcher with
+//! no Registry bound is itself a wire-layer fault; the guest maps a 0
+//! return to a trap. Failures during normal dispatch surface as
+//! Response.err envelopes from the Registry itself — they never reach
+//! this 0-return path.
+
+use magnus::value::{Opaque, ReprValue};
+use magnus::{Error as MagnusError, RString, Ruby, Value};
+use wasmtime::{Caller, Extern};
+
+use super::host_state::HostState;
+
+/// Drive a single `__kobako_rpc_call` invocation end-to-end. Entry point
+/// from the wasmtime closure built in [`super::instance::build_instance`].
+pub(crate) fn dispatch_rpc(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,
+    };
+
+    // No Registry bound — return 0 to signal a wire-layer fault; the guest
+    // maps a 0 return to a trap. `Kobako::Sandbox` always installs a
+    // Registry before invoking the guest, so reaching this branch indicates
+    // a misuse rather than a normal control path.
+    let registry = match caller.data().registry {
+        Some(d) => d,
+        None => return 0,
+    };
+
+    let resp_bytes = match invoke_registry(registry, &req_bytes) {
+        Ok(b) => b,
+        Err(_) => return 0,
+    };
+
+    write_response(caller, &resp_bytes).unwrap_or(0)
+}
+
+/// Call the Ruby Registry's `#dispatch(request_bytes)` method and return
+/// the encoded Response bytes. Errors here mean the Registry itself
+/// failed (it is contracted never to raise — see
+/// `Kobako::Registry#dispatch`), which we treat as a wire-layer fault.
+fn invoke_registry(registry: 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.
+    let ruby = Ruby::get().expect("Ruby handle unavailable in __kobako_rpc_call");
+    let registry_value: Value = ruby.get_inner(registry);
+    let req_str = ruby.str_from_slice(req_bytes);
+    let resp: RString = registry_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)
+}
+
+/// 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> {
+    let alloc = match caller.get_export("__kobako_alloc") {
+        Some(Extern::Func(f)) => f.typed::<i32, i32>(&*caller).ok()?,
+        _ => return None,
+    };
+    let len_i32 = i32::try_from(bytes.len()).ok()?;
+    let ptr = alloc.call(&mut *caller, len_i32).ok()?;
+    if ptr == 0 {
+        return None;
+    }
+
+    let mem = match caller.get_export("memory") {
+        Some(Extern::Memory(m)) => m,
+        _ => return None,
+    };
+    mem.write(&mut *caller, ptr as usize, bytes).ok()?;
+
+    let ptr_u32 = ptr as u32;
+    let len_u32 = bytes.len() as u32;
+    Some(((ptr_u32 as i64) << 32) | (len_u32 as i64))
+}
+
+/// Copy `[ptr, ptr+len)` out of the guest's linear memory as seen from
+/// `caller`. Returns `None` when `memory` is not exported or the slice
+/// falls outside the live memory range.
+fn read_caller_memory(caller: &mut Caller<'_, HostState>, ptr: i32, len: i32) -> Option<Vec<u8>> {
+    let mem = match caller.get_export("memory") {
+        Some(Extern::Memory(m)) => m,
+        _ => return None,
+    };
+    let data = mem.data(&caller);
+    let start = ptr as usize;
+    let end = start.checked_add(len as usize)?;
+    data.get(start..end).map(|s| s.to_vec())
+}

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

@@ -0,0 +1,59 @@
+//! Per-Store host state shared with every wasmtime callback.
+//!
+//! Owned by [`StoreCell`] (a `RefCell` shim wrapping `wasmtime::Store`)
+//! and threaded through every host import — the `__kobako_rpc_call`
+//! dispatcher reads `registry`, while the run-path methods on
+//! [`crate::wasm::Instance`] mutate `wasi`, `stdout_pipe`, `stderr_pipe`
+//! when refreshing the WASI context before each `#run` (SPEC.md B-03 /
+//! B-04).
+
+use std::cell::RefCell;
+
+use magnus::{value::Opaque, Value};
+use wasmtime::Store as WtStore;
+use wasmtime_wasi::p1::WasiP1Ctx;
+use wasmtime_wasi::p2::pipe::MemoryOutputPipe;
+
+/// Per-Store host state threaded through every host import callback.
+///
+/// WASI p1 state is embedded as `Option<WasiP1Ctx>` so it can be replaced
+/// fresh before each `#run` without rebuilding the Store. The `stdout_pipe`
+/// and `stderr_pipe` clones are kept alongside so the Ruby layer can drain
+/// captured bytes after execution without touching the WASI internals.
+#[derive(Default)]
+pub(crate) struct HostState {
+    /// Buffer mirror of guest's OUTCOME_BUFFER. Filled by `__kobako_take_outcome`
+    /// post-execution. Reserved for a future streaming-outcome path; not yet
+    /// consumed on the Rust side (the Ruby layer reads outcome via read_memory).
+    #[allow(dead_code)]
+    pub outcome: Vec<u8>,
+    /// WASI p1 context for the current (or most-recent) run. Replaced before
+    /// each `#run` so stdin/stdout/stderr pipes are always fresh (SPEC.md B-03).
+    pub wasi: Option<WasiP1Ctx>,
+    /// Clone of the MemoryOutputPipe wired to guest fd 1 (stdout). Retained
+    /// here so `take_stdout` can call `contents()` after execution without
+    /// having to dig into the WASI ctx internals.
+    pub stdout_pipe: Option<MemoryOutputPipe>,
+    /// Clone of the MemoryOutputPipe wired to guest fd 2 (stderr).
+    pub stderr_pipe: Option<MemoryOutputPipe>,
+    /// Ruby-side `Kobako::Registry`. When set, the `__kobako_rpc_call`
+    /// import calls `registry.dispatch(req_bytes)` and hands the returned
+    /// Response bytes back to the guest. `Opaque<Value>` is `Send + Sync`;
+    /// calling `get_inner` requires a `Ruby` handle, which we obtain on
+    /// every Ruby thread entry via `Ruby::get()`.
+    pub registry: Option<Opaque<Value>>,
+}
+
+/// Interior-mutability wrapper around `wasmtime::Store<HostState>`.
+///
+/// Magnus requires `Send + Sync` for wrapped types. `wasmtime::Store` is not
+/// `Sync`, so we wrap it in a `RefCell`. `RefCell` alone is sufficient
+/// because magnus enforces single-threaded GVL access from Ruby; `Send` and
+/// `Sync` are asserted via the unsafe impls below.
+pub(crate) struct StoreCell(pub(crate) RefCell<WtStore<HostState>>);
+
+// 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.
+unsafe impl Send for StoreCell {}
+unsafe impl Sync for StoreCell {}

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

@@ -0,0 +1,361 @@
+//! `Kobako::Wasm::Instance` — the only Ruby-visible wasmtime wrapper.
+//!
+//! 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 three cached
+//! [`TypedFunc`] handles for the SPEC ABI exports.
+//!
+//! WASI stdout/stderr capture (SPEC.md B-04): wasmtime-wasi p1 bindings
+//! route guest fd 1 and fd 2 into per-run [`MemoryOutputPipe`] instances.
+//! After each run the host drains the pipes via [`Instance::take_stdout`]
+//! / [`Instance::take_stderr`] and pushes the raw bytes through Ruby's
+//! OutputBuffer (which enforces the cap and `[truncated]` marker).
+//! Stdin carries the two-frame length-prefixed protocol: Frame 1
+//! (preamble msgpack) followed by Frame 2 (user script UTF-8), each
+//! prefixed by a 4-byte big-endian u32 length. Written via
+//! [`Instance::setup_wasi_pipes`] before each run (SPEC.md ABI
+//! Signatures).
+//!
+//! [`Engine`]: wasmtime::Engine
+//! [`Module`]: wasmtime::Module
+//! [`TypedFunc`]: wasmtime::TypedFunc
+//! [`MemoryOutputPipe`]: wasmtime_wasi::p2::pipe::MemoryOutputPipe
+
+use std::cell::RefCell;
+use std::path::Path;
+
+use magnus::RString;
+use magnus::{value::Opaque, Error as MagnusError, Ruby, Value};
+use wasmtime::{
+    AsContextMut, Caller, Engine as WtEngine, Extern, Instance as WtInstance, Linker, Memory,
+    Module as WtModule, Store as WtStore, TypedFunc,
+};
+use wasmtime_wasi::p1;
+use wasmtime_wasi::p2::pipe::{MemoryInputPipe, MemoryOutputPipe};
+use wasmtime_wasi::WasiCtxBuilder;
+
+use super::cache::{cached_module, shared_engine};
+use super::dispatch::dispatch_rpc;
+use super::host_state::{HostState, StoreCell};
+use super::wasm_err;
+
+#[magnus::wrap(class = "Kobako::Wasm::Instance", free_immediately, size)]
+pub(crate) struct Instance {
+    inner: WtInstance,
+    store: StoreCell,
+    // Cached TypedFunc handles for the three guest exports. Optional because
+    // test fixtures (a minimal "ping" module) need not provide them; real
+    // kobako.wasm always does, and the host enforces presence at run time.
+    //
+    // Exactly the SPEC ABI shape: `__kobako_run() -> ()`. Source delivery
+    // uses the WASI stdin two-frame protocol (see `setup_wasi_frames`).
+    run: Option<TypedFunc<(), ()>>,
+    take_outcome: Option<TypedFunc<(), u64>>,
+    alloc: Option<TypedFunc<i32, i32>>,
+}
+
+impl Instance {
+    /// Construct an Instance from a wasm file path, using the process-wide
+    /// shared Engine and per-path Module cache. The single Ruby-facing
+    /// constructor for `Kobako::Wasm::Instance` — Engine and Module are
+    /// never visible to Ruby.
+    pub(crate) fn from_path(path: String) -> Result<Self, MagnusError> {
+        let engine = shared_engine()?;
+        let module = cached_module(Path::new(&path))?;
+        let store = WtStore::new(engine, HostState::default());
+        let store_cell = StoreCell(RefCell::new(store));
+        build_instance(engine, &module, store_cell)
+    }
+
+    /// Install the Ruby-side `Kobako::Registry` into HostState. Called by
+    /// `Kobako::Sandbox` after constructing the Registry; from this point
+    /// on, every `__kobako_rpc_call` import invocation routes through
+    /// `registry.dispatch(req_bytes)`.
+    pub(crate) fn set_registry(&self, registry: Value) -> Result<(), MagnusError> {
+        let mut store_ref = self.store.0.borrow_mut();
+        store_ref.data_mut().registry = Some(Opaque::from(registry));
+        Ok(())
+    }
+
+    // -----------------------------------------------------------------
+    // Run-path methods. These drive the alloc → write source → run →
+    // take_outcome flow from Ruby. Each method is best-effort — it raises
+    // a Ruby `Kobako::Wasm::Error` when the corresponding export is
+    // missing or fails so the Sandbox layer can map errors to the
+    // three-class taxonomy.
+    // -----------------------------------------------------------------
+
+    /// Invoke the guest's `__kobako_alloc(size)` export and return the
+    /// resulting linear-memory offset. A return of 0 indicates an
+    /// allocation failure (caller should treat as a wire violation /
+    /// trap).
+    pub(crate) fn alloc(&self, size: i32) -> Result<i32, MagnusError> {
+        let ruby = Ruby::get().expect("Ruby thread");
+        let alloc = self
+            .alloc
+            .as_ref()
+            .ok_or_else(|| wasm_err(&ruby, "guest does not export __kobako_alloc"))?;
+        let mut store_ref = self.store.0.borrow_mut();
+        alloc
+            .call(store_ref.as_context_mut(), size)
+            .map_err(|e| wasm_err(&ruby, format!("__kobako_alloc({}): {}", size, e)))
+    }
+
+    /// Write +bytes+ into the guest's linear memory starting at +ptr+.
+    /// Raises `Kobako::Wasm::Error` if the instance has no `memory`
+    /// export or the slice is out of bounds.
+    pub(crate) fn write_memory(&self, ptr: i32, bytes: RString) -> Result<(), MagnusError> {
+        let ruby = Ruby::get().expect("Ruby thread");
+        let mut store_ref = self.store.0.borrow_mut();
+        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'")),
+        };
+
+        // SAFETY: RString::as_slice on a frozen-on-read borrow.
+        let src: &[u8] = unsafe { bytes.as_slice() };
+        let data = mem.data_mut(store_ref.as_context_mut());
+        let start = ptr as usize;
+        let end = start
+            .checked_add(src.len())
+            .ok_or_else(|| wasm_err(&ruby, "write_memory: ptr + len overflow"))?;
+        if end > data.len() {
+            return Err(wasm_err(
+                &ruby,
+                format!(
+                    "write_memory: range [{}, {}) exceeds memory size {}",
+                    start,
+                    end,
+                    data.len()
+                ),
+            ));
+        }
+        data[start..end].copy_from_slice(src);
+        Ok(())
+    }
+
+    /// Read +len+ bytes from the guest's linear memory starting at
+    /// +ptr+. Returns a binary-encoded Ruby String.
+    pub(crate) fn read_memory(&self, ptr: i32, len: i32) -> Result<RString, MagnusError> {
+        let ruby = Ruby::get().expect("Ruby thread");
+        let mut store_ref = self.store.0.borrow_mut();
+        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'")),
+        };
+        let data = mem.data(store_ref.as_context_mut());
+        let start = ptr as usize;
+        let end = start
+            .checked_add(len as usize)
+            .ok_or_else(|| wasm_err(&ruby, "read_memory: ptr + len overflow"))?;
+        if end > data.len() {
+            return Err(wasm_err(
+                &ruby,
+                format!(
+                    "read_memory: range [{}, {}) exceeds memory size {}",
+                    start,
+                    end,
+                    data.len()
+                ),
+            ));
+        }
+        Ok(ruby.str_from_slice(&data[start..end]))
+    }
+
+    /// Invoke `__kobako_run` with the SPEC `() -> ()` shape. Source is
+    /// delivered via the WASI stdin two-frame protocol written by
+    /// `setup_wasi_frames` before this call.
+    pub(crate) fn run_call(&self) -> 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"))?;
+        let mut store_ref = self.store.0.borrow_mut();
+        run.call(store_ref.as_context_mut(), ())
+            .map_err(|e| wasm_err(&ruby, format!("__kobako_run(): {}", e)))
+    }
+
+    /// Invoke `__kobako_take_outcome`. Returns the packed u64
+    /// `(ptr << 32) | len`; the Ruby caller unpacks.
+    pub(crate) fn take_outcome(&self) -> Result<u64, MagnusError> {
+        let ruby = Ruby::get().expect("Ruby thread");
+        let take = self
+            .take_outcome
+            .as_ref()
+            .ok_or_else(|| wasm_err(&ruby, "guest does not export __kobako_take_outcome"))?;
+        let mut store_ref = self.store.0.borrow_mut();
+        take.call(store_ref.as_context_mut(), ())
+            .map_err(|e| wasm_err(&ruby, format!("__kobako_take_outcome(): {}", e)))
+    }
+
+    // -----------------------------------------------------------------
+    // WASI capture path (SPEC.md B-04). Called by Ruby's Sandbox#run.
+    // -----------------------------------------------------------------
+
+    /// Initialise fresh WASI pipes with the two-frame stdin content.
+    ///
+    /// Must be called before each `run` invocation. Creates:
+    ///   * A MemoryInputPipe for stdin with Frame 1 (preamble) + Frame 2
+    ///     (user script) encoded as length-prefixed frames: each frame is a
+    ///     4-byte big-endian u32 length prefix followed by the payload bytes.
+    ///     The guest reads both frames from WASI stdin (SPEC.md ABI Signatures).
+    ///   * A MemoryOutputPipe for fd 1 (stdout) — transport-layer pipe.
+    ///   * A MemoryOutputPipe for fd 2 (stderr) — transport-layer pipe.
+    ///
+    /// `stdout_cap` and `stderr_cap` are accepted but the transport pipes are
+    /// uncapped: SPEC.md B-04 requires that overflowing the OutputBuffer limit
+    /// is a non-error outcome. A capped WASI pipe would produce a real trap.
+    pub(crate) fn setup_wasi_pipes(
+        &self,
+        stdout_cap: i64,
+        stderr_cap: i64,
+        preamble_bytes: RString,
+        source_bytes: RString,
+    ) -> Result<(), MagnusError> {
+        let _ = (stdout_cap, stderr_cap);
+
+        // Build the two-frame stdin content. Each frame: 4-byte BE u32 length
+        // prefix + payload bytes (SPEC.md ABI Signatures — two-frame protocol).
+        let preamble: &[u8] = unsafe { preamble_bytes.as_slice() };
+        let source: &[u8] = unsafe { source_bytes.as_slice() };
+
+        let mut stdin_content: Vec<u8> = Vec::with_capacity(4 + preamble.len() + 4 + source.len());
+        // Frame 1 — preamble
+        stdin_content.extend_from_slice(&(preamble.len() as u32).to_be_bytes());
+        stdin_content.extend_from_slice(preamble);
+        // Frame 2 — user script
+        stdin_content.extend_from_slice(&(source.len() as u32).to_be_bytes());
+        stdin_content.extend_from_slice(source);
+
+        let stdin_pipe = MemoryInputPipe::new(stdin_content);
+        let stdout_pipe = MemoryOutputPipe::new(usize::MAX);
+        let stderr_pipe = MemoryOutputPipe::new(usize::MAX);
+
+        let mut builder = WasiCtxBuilder::new();
+        builder.stdin(stdin_pipe);
+        builder.stdout(stdout_pipe.clone());
+        builder.stderr(stderr_pipe.clone());
+        let wasi = builder.build_p1();
+
+        {
+            let mut store_ref = self.store.0.borrow_mut();
+            let data = store_ref.data_mut();
+            data.wasi = Some(wasi);
+            data.stdout_pipe = Some(stdout_pipe);
+            data.stderr_pipe = Some(stderr_pipe);
+        }
+
+        Ok(())
+    }
+
+    /// Drain the stdout bytes captured during the most recent run.
+    ///
+    /// Returns a binary Ruby String containing raw bytes from guest fd 1.
+    /// The MemoryOutputPipe clone in HostState retains its contents between
+    /// calls — it is replaced on the next `setup_wasi_pipes`.
+    pub(crate) fn take_stdout(&self) -> Result<RString, MagnusError> {
+        let ruby = Ruby::get().expect("Ruby thread");
+        let store_ref = self.store.0.borrow();
+        let bytes = store_ref
+            .data()
+            .stdout_pipe
+            .as_ref()
+            .map(|p| p.contents())
+            .unwrap_or_default();
+        Ok(ruby.str_from_slice(&bytes))
+    }
+
+    /// Drain the stderr bytes captured during the most recent run.
+    ///
+    /// Returns a binary Ruby String containing raw bytes from guest fd 2.
+    pub(crate) fn take_stderr(&self) -> Result<RString, MagnusError> {
+        let ruby = Ruby::get().expect("Ruby thread");
+        let store_ref = self.store.0.borrow();
+        let bytes = store_ref
+            .data()
+            .stderr_pipe
+            .as_ref()
+            .map(|p| p.contents())
+            .unwrap_or_default();
+        Ok(ruby.str_from_slice(&bytes))
+    }
+}
+
+/// Build an `Instance` from an engine, module, and store cell. The store
+/// cell is moved in and ends up owned by the returned Instance. Wires
+/// the WASI p1 imports plus the `__kobako_rpc_call` host import.
+fn build_instance(
+    engine: &WtEngine,
+    module: &WtModule,
+    store_cell: StoreCell,
+) -> Result<Instance, MagnusError> {
+    let ruby = Ruby::get().expect("Ruby thread");
+    let mut linker: Linker<HostState> = Linker::new(engine);
+
+    // Wire the wasmtime-wasi preview1 WASI imports. Routes guest fd 1/2 to
+    // the MemoryOutputPipes set up before each run via `setup_wasi_pipes`.
+    // The closure extracts `&mut WasiP1Ctx` from HostState; if none is set
+    // (e.g. a test module that never invokes WASI functions), the Option
+    // unwrap will panic — but `setup_wasi_pipes` is always called before any
+    // WASI-enabled run.
+    p1::add_to_linker_sync(&mut linker, |state: &mut HostState| {
+        state
+            .wasi
+            .as_mut()
+            .expect("WASI context not initialised — call setup_wasi_pipes before run")
+    })
+    .map_err(|e| wasm_err(&ruby, format!("add WASI p1 to linker: {}", e)))?;
+
+    // `__kobako_rpc_call` host import. Signature per SPEC Wire ABI:
+    //   (req_ptr: i32, req_len: i32) -> i64
+    // Decodes the Request bytes, dispatches via the Ruby-side
+    // `Kobako::Registry` (set per-run via `set_registry`), allocates a guest
+    // buffer through `__kobako_alloc`, writes the Response bytes there, and
+    // returns the packed `(ptr<<32)|len`. The dispatcher returns 0 on any
+    // wire-layer fault (including a missing Registry); see `dispatch_rpc`.
+    linker
+        .func_wrap(
+            "env",
+            "__kobako_rpc_call",
+            |mut caller: Caller<'_, HostState>, req_ptr: i32, req_len: i32| -> i64 {
+                dispatch_rpc(&mut caller, req_ptr, req_len)
+            },
+        )
+        .map_err(|e| wasm_err(&ruby, format!("define __kobako_rpc_call: {}", e)))?;
+
+    let instance = {
+        let mut store_ref = store_cell.0.borrow_mut();
+        linker
+            .instantiate(store_ref.as_context_mut(), module)
+            .map_err(|e| wasm_err(&ruby, format!("instantiate: {}", e)))?
+    };
+
+    // Best-effort export lookup. Missing exports are not an error here
+    // (test fixture is a bare module); the host enforces presence before
+    // invocation. Only the SPEC ABI `() -> ()` shape is accepted for
+    // `__kobako_run` — the transitional `(ptr, len) -> ()` shape is gone.
+    let (run, take_outcome, alloc) = {
+        let mut store_ref = store_cell.0.borrow_mut();
+        let mut ctx = store_ref.as_context_mut();
+        let run = instance
+            .get_typed_func::<(), ()>(&mut ctx, "__kobako_run")
+            .ok();
+        let take_outcome = instance
+            .get_typed_func::<(), u64>(&mut ctx, "__kobako_take_outcome")
+            .ok();
+        let alloc = instance
+            .get_typed_func::<i32, i32>(&mut ctx, "__kobako_alloc")
+            .ok();
+        (run, take_outcome, alloc)
+    };
+
+    Ok(Instance {
+        inner: instance,
+        store: store_cell,
+        run,
+        take_outcome,
+        alloc,
+    })
+}

data/ext/kobako/src/wasm.rs

@@ -0,0 +1,80 @@
+// Host-side wasmtime wrapper.
+//
+// The only Ruby-visible class is
+//
+//   Kobako::Wasm::Instance — wraps wasmtime::Instance + cached TypedFuncs
+//
+// constructed via `Kobako::Wasm::Instance.from_path(path)`. The underlying
+// wasmtime Engine and compiled Module live in a process-scope cache (see
+// the `cache` submodule) and never surface to Ruby (SPEC.md "Code
+// Organization": `ext/` "exposes no Wasm engine types to the Host App or
+// downstream gems").
+//
+// Module layout (per CLAUDE.md principle #2 — one responsibility per file):
+//
+//   * `cache`       — process-wide Engine + per-path Module cache.
+//   * `host_state`  — HostState (per-Store context) + StoreCell wrapper.
+//   * `instance`    — Kobako::Wasm::Instance and its run-path methods.
+//   * `dispatch`    — `__kobako_rpc_call` host-import dispatch helpers.
+//
+// This file is the façade: it owns the Ruby error class lazy-resolvers,
+// the `wasm_err` constructor shared by every submodule, and the Ruby
+// init() that registers `Kobako::Wasm::Instance` and its methods.
+
+mod cache;
+mod dispatch;
+mod host_state;
+mod instance;
+
+use magnus::value::Lazy;
+use magnus::{function, method, prelude::*, Error as MagnusError, ExceptionClass, RModule, Ruby};
+
+use instance::Instance;
+
+// ---------------------------------------------------------------------------
+// Error classes (lazy-resolved from Ruby once Kobako::Wasm is defined).
+// ---------------------------------------------------------------------------
+
+pub(crate) static MODULE_NOT_BUILT_ERROR: Lazy<ExceptionClass> = Lazy::new(|ruby| {
+    let kobako: RModule = ruby.class_object().const_get("Kobako").unwrap();
+    let wasm: RModule = kobako.const_get("Wasm").unwrap();
+    wasm.const_get("ModuleNotBuiltError").unwrap()
+});
+
+pub(crate) static WASM_ERROR: Lazy<ExceptionClass> = Lazy::new(|ruby| {
+    let kobako: RModule = ruby.class_object().const_get("Kobako").unwrap();
+    let wasm: RModule = kobako.const_get("Wasm").unwrap();
+    wasm.const_get("Error").unwrap()
+});
+
+pub(crate) fn wasm_err(ruby: &Ruby, msg: impl Into<String>) -> MagnusError {
+    MagnusError::new(ruby.get_inner(&WASM_ERROR), msg.into())
+}
+
+// ---------------------------------------------------------------------------
+// Ruby init
+// ---------------------------------------------------------------------------
+
+pub fn init(ruby: &Ruby, kobako: RModule) -> Result<(), MagnusError> {
+    let wasm = kobako.define_module("Wasm")?;
+
+    // Error hierarchy. ModuleNotBuiltError is the headline error for the
+    // common pre-build state where `data/kobako.wasm` has not yet been
+    // produced (e.g. fresh clone before `rake compile`).
+    let base_err = wasm.define_error("Error", ruby.exception_standard_error())?;
+    wasm.define_error("ModuleNotBuiltError", base_err)?;
+
+    let instance = wasm.define_class("Instance", ruby.class_object())?;
+    instance.define_singleton_method("from_path", function!(Instance::from_path, 1))?;
+    instance.define_method("alloc", method!(Instance::alloc, 1))?;
+    instance.define_method("write_memory", method!(Instance::write_memory, 2))?;
+    instance.define_method("read_memory", method!(Instance::read_memory, 2))?;
+    instance.define_method("run", method!(Instance::run_call, 0))?;
+    instance.define_method("take_outcome", method!(Instance::take_outcome, 0))?;
+    instance.define_method("set_registry", method!(Instance::set_registry, 1))?;
+    instance.define_method("setup_wasi_pipes", method!(Instance::setup_wasi_pipes, 4))?;
+    instance.define_method("take_stdout", method!(Instance::take_stdout, 0))?;
+    instance.define_method("take_stderr", method!(Instance::take_stderr, 0))?;
+
+    Ok(())
+}