kobako 0.27.0 → 0.28.0

data/crates/kobako-wasmtime/src/dispatch.rs

@@ -1,89 +1,81 @@
-//! Host-side dispatch for the `__kobako_dispatch` import.
+//! Host side of the `__kobako_upcall` import: hand the guest's Call to
+//! the bound `DispatchHandler` and write its Reply back into guest memory.
+//! A request under a tag the host does not serve is answered as
+//! unsupported, so a guest asking for a later operation can fall back.
 //!
-//! When the guest invokes the wasm import declared in
-//! `wasm/kobako-core/src/abi.rs`, wasmtime calls back into the host
-//! through the closure registered by `instance_pre::build_linker`.
-//! That closure delegates here. The dispatcher:
+//! A failure lands on whoever is answerable for it. A trap the guest
+//! raises during a callback into it ends the invocation as that trap; any
+//! other failure is the guest's or the wire's, so the import answers 0,
+//! which the guest receives as a wire failure.
 //!
-//!   1. Reads the Call bytes from guest linear memory.
-//!   2. Invokes the bound `DispatchHandler` (the frontend's dispatch
-//!      bridge, e.g. a Ruby Proc) and recovers Reply bytes.
-//!   3. Allocates a guest buffer via `__kobako_alloc(len)` invoked
-//!      through `Caller::get_export`.
-//!   4. Writes the Reply bytes into the guest buffer.
-//!   5. Returns packed `(ptr<<32)|len` for the guest to decode.
-//!
-//! Returns 0 on any step failure. `Kobako::Sandbox#initialize` always
-//! installs the dispatch handler before any invocation, so reaching the
-//! dispatcher with no handler bound is itself a wire-layer fault; the
-//! guest maps a 0 return to a trap. Failures during normal dispatch
-//! take the Reply's fault arm from
-//! `Kobako::Transport::Dispatcher.dispatch` itself — they never reach
-//! this 0-return path.
-//!
-//! ## Why this module writes to `stderr`
-//!
-//! This file is the one place in the driver that deliberately prints
-//! through `eprintln!`. The host normally surfaces faults through the
-//! contract's error channels; the dispatcher contract is the exception
-//! — it must return a packed `i64` to the guest and cannot fail, so a
-//! 0 return is the only signal the wasm side receives. The guest collapses every 0 into the same trap, so the
-//! Ruby host has no way to attribute the failure to a specific step
-//! (missing `memory` export vs. no dispatch handler bound vs. the
-//! handler raised vs. `__kobako_alloc` returned 0 vs. `memory.write`
-//! rejected).
-//!
-//! `handle` writes a single `[kobako-dispatch] <reason>` line to
-//! `stderr` on each failure path so operators have a breadcrumb to
-//! correlate the trap with the actual cause. The line is emitted in
-//! both debug and release builds on purpose: dispatcher failures are
-//! wire-layer faults rather than expected error paths (`Kobako::Sandbox`
-//! always installs the handler, the handler is contracted never to
-//! raise, etc.), so the "release-build noise" cost is bounded — under
-//! normal operation the line is never written. Operators that need to
-//! silence the stream can redirect the host process's stderr, but the
-//! kobako convention is "ext never logs" plus this single, named
-//! exception.
+//! Each 0 also writes one `[kobako-dispatch] <reason>` line to stderr,
+//! since the 0 itself carries no reason. It is the one place the driver
+//! logs, and normal operation never reaches it.
 
 use wasmtime::Caller;
 
-use kobako_transport::envelope::Call;
+use kobako_runtime::error::Trap;
+use kobako_runtime::yielder::Yielder;
+use kobako_transport::abi::pack_ptr_len;
+use kobako_transport::envelope::{Unsupported, Upcall, YieldReply};
 
+use crate::guest_mem;
 use crate::invocation::Invocation;
 
-/// Drive a single `__kobako_dispatch` invocation end-to-end. Entry point
-/// from the wasmtime closure registered by `instance_pre::build_linker`.
-///
-/// Returns the packed `(ptr<<32)|len` u64 on success, 0 on any
-/// wire-layer fault. Failure paths log a `[kobako-dispatch]` line to
-/// `stderr` so operators have a breadcrumb when the guest sees a 0
-/// return and traps. The bound dispatch handler is contracted never to
-/// raise (it folds Service exceptions onto the Reply's fault arm),
-/// so reaching the failure path is always a wiring bug or wire-layer
-/// fault rather than an expected path.
-pub(crate) fn handle(caller: &mut Caller<'_, Invocation>, req_ptr: i32, req_len: i32) -> i64 {
-    match try_handle(caller, req_ptr, req_len) {
-        Ok(packed) => packed,
-        Err(reason) => {
-            eprintln!("[kobako-dispatch] {reason}");
-            0
-        }
+/// The wasmtime-backed `Yielder`: built per `__kobako_upcall` frame over
+/// that frame's `Caller`, so nested dispatch frames each carry their own and
+/// stack on the Rust call stack with no shared slot.
+struct CallerYielder<'a, 'c> {
+    caller: &'a mut Caller<'c, Invocation>,
+}
+
+impl Yielder for CallerYielder<'_, '_> {
+    fn yield_to_block(&mut self, args: &[u8]) -> Result<YieldReply, Trap> {
+        let bytes = guest_mem::drive_yield(self.caller, args)
+            .map_err(|msg| Trap::Other(msg.to_string()))?;
+        YieldReply::decode(&bytes).map_err(|err| Trap::Other(err.to_string()))
     }
 }
 
-/// Result-returning core of `handle`. Pulled out so each early
-/// failure path carries a diagnostic string instead of an opaque 0.
+/// Answer one `__kobako_upcall` call: the packed `(ptr<<32)|len` of the
+/// Reply, 0 for a failure the guest or the wire is answerable for, or the
+/// trap a callback into the guest raised.
+pub(crate) fn handle(
+    caller: &mut Caller<'_, Invocation>,
+    req_ptr: i32,
+    req_len: i32,
+) -> wasmtime::Result<i64> {
+    let answer = try_handle(caller, req_ptr, req_len);
+    if let Some(trap) = caller.data_mut().take_reentry_trap() {
+        return Err(trap);
+    }
+    Ok(answer.unwrap_or_else(|reason| {
+        eprintln!("[kobako-dispatch] {reason}");
+        0
+    }))
+}
+
 fn try_handle(
     caller: &mut Caller<'_, Invocation>,
     req_ptr: i32,
     req_len: i32,
 ) -> Result<i64, &'static str> {
-    let req_bytes = crate::guest_mem::read(caller, req_ptr, req_len)?;
-    // The driver decodes the core envelope so the frontend never sees a
-    // frame; the payload inside it stays bytes the whole way through.
-    let call = Call::decode(&req_bytes).map_err(|_| {
-        "the guest sent a malformed Call envelope — please report this as a kobako bug"
-    })?;
+    let req_bytes = guest_mem::read_request(caller, req_ptr, req_len)?;
+    // The driver decodes the core envelope, here and in `CallerYielder`, so
+    // the frontend never sees a frame; the payload inside it stays bytes
+    // the whole way through.
+    let call = match Upcall::decode(&req_bytes) {
+        Ok(Upcall::Call(call)) => call,
+        Ok(_) => {
+            let refusal = Unsupported::new("the host does not serve this request");
+            return write_reply(caller, &refusal.encode());
+        }
+        Err(_) => {
+            return Err(
+                "the guest sent a malformed Call envelope — please report this as a kobako bug",
+            )
+        }
+    };
 
     // `Kobako::Sandbox` always installs the dispatch handler before
     // invoking the runtime, so reaching this branch indicates a misuse
@@ -91,27 +83,25 @@ fn try_handle(
     let handler = caller
         .data()
         .on_dispatch()
-        .ok_or("a Sandbox callback fired outside an active Sandbox#run — please report this as a kobako bug")?;
+        .ok_or("a Sandbox callback fired outside an active invocation — please report this as a kobako bug")?;
 
     // Build a frame-scoped yielder over this Caller and hand it to the
     // handler. The borrow ends with the block, freeing the Caller for
-    // `write_response`; nested dispatch frames each build their own, so
+    // `write_reply`; nested dispatch frames each build their own, so
     // the LIFO re-entry lives on the Rust stack — no shared slot.
     let reply = {
-        let mut yielder = crate::guest_mem::CallerYielder::new(caller);
+        let mut yielder = CallerYielder { caller };
         handler.dispatch(call, &mut yielder)
     }
     .ok_or(
         "a Sandbox callback raised an exception instead of returning a fault — please report this as a kobako bug",
     )?;
 
-    write_response(caller, &reply.encode())
+    write_reply(caller, &reply.encode())
 }
 
-/// Allocate a guest-side buffer and copy the response bytes into it via
-/// `crate::guest_mem::alloc_and_write`, returning the packed
-/// `(ptr<<32)|len` u64 the guest's `__kobako_dispatch` import expects.
-fn write_response(caller: &mut Caller<'_, Invocation>, bytes: &[u8]) -> Result<i64, &'static str> {
-    let ptr = crate::guest_mem::alloc_and_write(caller, bytes)?;
-    Ok(((ptr as i64) << 32) | (bytes.len() as i64))
+fn write_reply(caller: &mut Caller<'_, Invocation>, bytes: &[u8]) -> Result<i64, &'static str> {
+    let ptr = guest_mem::write_from_callback(caller, bytes)?;
+    // The write has already held the length to the payload cap.
+    Ok(pack_ptr_len(ptr, bytes.len() as u32) as i64)
 }

data/crates/kobako-wasmtime/src/driver.rs

@@ -17,14 +17,15 @@ use wasmtime::{
 
 use crate::cache::shared_engine;
 use crate::config::Config;
-use crate::exports::Exports;
+use crate::exports::{self, Exports};
 use crate::invocation::Invocation;
-use crate::{capture, frames, instance_pre, trap};
+use crate::{capture, guest_mem, instance_pre, io, trap};
 use kobako_runtime::dispatch::DispatchHandler;
 use kobako_runtime::error::{InvokeError, SetupError, Trap};
 use kobako_runtime::profile::Profile;
-use kobako_runtime::runtime::{Entry, Frames, Runtime as ContractRuntime};
+use kobako_runtime::runtime::{Entry, Runtime as ContractRuntime};
 use kobako_runtime::snapshot::{Capture, Completion, Snapshot, Usage};
+use kobako_transport::envelope::{CompileReply, Downcall, Preamble, Run, Snippet};
 
 /// The wasmtime execution unit behind one sandbox runtime.
 pub struct Driver {
@@ -39,11 +40,9 @@ pub struct Driver {
 }
 
 impl Driver {
-    /// Construct a Driver from a wasm file path, using the process-wide
-    /// shared Engine and per-path Module / InstancePre caches. The
-    /// artifact's ABI version is verified with the cached template
-    /// (`crate::abi`). Every failure is a `SetupError` for the frontend
-    /// to attribute — Engine and Module never leave the driver.
+    /// Load the Guest Binary at `path` and verify its ABI version. The
+    /// Engine is shared by the process and the Module cached per path;
+    /// neither leaves the driver.
     pub fn new(path: &Path, config: Config) -> Result<Self, SetupError> {
         Ok(Self {
             instance_pre: instance_pre::cached_instance_pre(path)?,
@@ -51,8 +50,6 @@ impl Driver {
         })
     }
 
-    /// Build the per-invocation Store: a fresh `Invocation` wired with
-    /// the memory limiter and the epoch-deadline callback.
     fn new_store(&self) -> Result<WtStore<Invocation>, SetupError> {
         let mut store = WtStore::new(shared_engine()?, Invocation::new(self.config.memory_limit));
         store.limiter(|state: &mut Invocation| -> &mut dyn ResourceLimiter { state.limiter_mut() });
@@ -60,28 +57,21 @@ impl Driver {
         Ok(store)
     }
 
-    /// Instantiate the per-invocation instance from the pre-linked
-    /// template and resolve its host-driven export handles. An
-    /// instantiation failure at invocation time is an engine fault —
-    /// a `Trap` — unlike the construction-time probe, whose failure is
-    /// `SetupError`.
+    /// Failing here is an engine fault — a `Trap` — unlike the
+    /// construction-time probe, whose failure is a `SetupError`.
     fn instantiate(&self, store: &mut WtStore<Invocation>) -> Result<Exports, Trap> {
         let instance = self
             .instance_pre
             .instantiate(store.as_context_mut())
             .map_err(|e| Trap::Other(format!("failed to instantiate the Sandbox runtime: {e}")))?;
-        Ok(Exports::resolve(&instance, store.as_context_mut()))
+        let exports = Exports::resolve(&instance, store.as_context_mut());
+        store.data_mut().set_exports(exports.clone());
+        Ok(exports)
     }
 
-    /// Run one guest export call inside the per-invocation cap window:
-    /// `Driver::prime_caps` before, `disarm_caps` after — the shared
-    /// bracket for both run-path exports (`__kobako_eval` /
-    /// `__kobako_run`). Disarm runs whether the call returns or traps, so
-    /// the `wall_time` bracket and the memory
-    /// cap always close — that close-on-trap guarantee is the reason this
-    /// bracket lives in one place rather than inline at each call site.
-    /// The wasmtime trap is returned unmapped; the caller classifies it
-    /// through `trap::trap_from`.
+    /// Disarm runs whether the call returns or traps, so the `wall_time`
+    /// bracket and the memory cap always close; that guarantee is why the
+    /// bracket lives in one place rather than at each call site.
     fn call_with_caps<Params, Results>(
         &self,
         store: &mut WtStore<Invocation>,
@@ -99,20 +89,8 @@ impl Driver {
         result
     }
 
-    /// Stamp the per-invocation wall-clock deadline into `Invocation`
-    /// 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 per-invocation memory delta cap —
-    /// the pre-initialized image's allocation is folded into the
-    /// baseline rather than the budget — and stamps the wall-clock
-    /// entry instant for the `wall_time`
-    /// measurement. The bracket closes in `disarm_caps` so it matches
-    /// the `timeout` deadline window and excludes `OUTCOME_BUFFER`
-    /// decoding and stdout / stderr capture readout.
+    /// The pre-initialized image's allocation is folded into the memory
+    /// baseline rather than the budget.
     fn prime_caps(&self, store: &mut WtStore<Invocation>, exports: &Exports) {
         match self.config.timeout {
             Some(timeout) => {
@@ -133,9 +111,8 @@ impl Driver {
         store.data_mut().start_wall_clock();
     }
 
-    /// Bundle one invocation's observables into a fresh `Snapshot`,
-    /// uniformly for every `completion` — the clipped captures and the
-    /// cap-bracket usage must survive a trap just as they do an outcome.
+    /// Built the same for every `completion`: captures and usage must
+    /// survive a trap just as they do an outcome.
     fn build_snapshot(&self, store: &WtStore<Invocation>, completion: Completion) -> Snapshot {
         let data = store.data();
         let usage = Usage {
@@ -162,48 +139,39 @@ impl Driver {
 }
 
 impl ContractRuntime for Driver {
-    /// Drive one guest invocation on a fresh instance and return its
-    /// `Snapshot`, `Ok` iff the guest export ran. Builds a fresh Store,
-    /// binds the borrowed dispatch handler, installs the stdin frames
-    /// (three for `Eval` — preamble / source / snippets; two for `Run` —
-    /// preamble / snippets, with the envelope copied into guest memory),
-    /// and primes the per-invocation caps around the export call. A fault
-    /// before the export call is the `Err` channel; once the call starts,
-    /// every fault folds into the Snapshot's `Completion` — the
-    /// configured-cap paths as `Trap::Timeout` / `Trap::MemoryLimit`,
-    /// everything else as `Trap::Other` — so captures and usage survive
-    /// it. The body touches no frontend value — the handler is only
-    /// borrowed (see the trait's safety contract).
+    /// A fault before the export call is the `Err`; once the call
+    /// starts, every fault folds into the Snapshot's `Completion` so
+    /// captures and usage survive it. The handler is only borrowed (see the
+    /// trait's safety contract).
     fn invoke(
         &self,
         entry: Entry<'_>,
-        frames: Frames<'_>,
+        preamble: &Preamble,
         handler: Option<Arc<dyn DispatchHandler>>,
     ) -> Result<Snapshot, InvokeError> {
         let mut store = self.new_store()?;
         if let Some(handler) = handler {
             store.data_mut().bind_on_dispatch(handler);
         }
-        let frame_list: Vec<&[u8]> = match &entry {
-            Entry::Eval { source } => vec![frames.preamble, source, frames.snippets],
-            Entry::Run { .. } => vec![frames.preamble, frames.snippets],
-        };
-        frames::install_wasi_frames(&mut store, &self.config, &frame_list)?;
+        io::install_wasi(&mut store, &self.config, &preamble.encode())?;
         let exports = self.instantiate(&mut store)?;
-        let called = match entry {
-            Entry::Eval { .. } => {
-                let eval = frames::require_export(exports.eval.as_ref())?;
-                self.call_with_caps(&mut store, &exports, eval, ())
-            }
-            Entry::Run { envelope } => {
-                let run = frames::require_export(exports.run.as_ref())?;
-                let (env_ptr, env_len) = frames::write_envelope(&mut store, &exports, envelope)?;
-                self.call_with_caps(&mut store, &exports, run, (env_ptr, env_len))
-            }
-        };
+        let downcall = exports::require(exports.downcall.as_ref())?;
+        let request = match entry {
+            Entry::Eval { source } => Downcall::Eval(source.to_vec()),
+            Entry::Run {
+                entrypoint,
+                payload,
+            } => Downcall::Run(Run {
+                entrypoint: entrypoint.to_owned(),
+                payload,
+            }),
+        }
+        .encode();
+        let (ptr, len) = io::write_request(&mut store, &exports, &request)?;
+        let called = self.call_with_caps(&mut store, &exports, downcall, (ptr, len));
         let completion = match called {
-            Ok(()) => match frames::fetch_outcome_bytes(&mut store, &exports) {
-                Ok(bytes) => Completion::Outcome(bytes),
+            Ok(packed) => match io::read_outcome(&store, &exports, packed) {
+                Ok(outcome) => Completion::Outcome(outcome),
                 Err(t) => Completion::Trap(t),
             },
             Err(e) => Completion::Trap(trap::trap_from(e)),
@@ -211,25 +179,104 @@ impl ContractRuntime for Driver {
         Ok(self.build_snapshot(&store, completion))
     }
 
-    /// The posture this driver built — exactly the rung requested via
-    /// `Config`. Every per-invocation WASI context is built to it
-    /// (`frames::install_wasi_frames`): `Hermetic` freezes ambient time
-    /// and entropy (`crate::ambient`), `Permissive` leaves the live WASI
-    /// sources. Both rungs wire no filesystem, environment, or network,
-    /// and the linker adds only the wire ABI's `__kobako_dispatch`
-    /// beyond that confined WASI surface (`crate::instance_pre`).
+    /// Exactly the rung `Config` requested. `Hermetic` freezes ambient time
+    /// and entropy; both rungs wire no filesystem, environment, or network,
+    /// and the linker adds only `__kobako_upcall` beyond that WASI surface.
     fn profile(&self) -> Profile {
         self.config.profile
     }
+
+    /// Bounded by the same caps as an invocation, on an instance of its
+    /// own that no script ever runs on, so what it answers carries
+    /// nothing a script could have written.
+    fn compile(&self, preamble: &Preamble) -> Option<Vec<Vec<u8>>> {
+        let mut store = self.new_store().ok()?;
+        io::install_wasi(&mut store, &self.config, &preamble.encode()).ok()?;
+        let exports = self.instantiate(&mut store).ok()?;
+        let downcall = exports::require(exports.downcall.as_ref()).ok()?;
+        let (ptr, len) =
+            io::write_request(&mut store, &exports, &Downcall::Compile.encode()).ok()?;
+        let packed = self
+            .call_with_caps(&mut store, &exports, downcall, (ptr, len))
+            .ok()?;
+        match io::read_compile_reply(&store, &exports, packed).ok()? {
+            CompileReply::Ok(bytecodes) => one_per_source(preamble, bytecodes)
+                .filter(|bytecodes| replay_fits(preamble, bytecodes)),
+            CompileReply::Error(_) | CompileReply::Unsupported(_) => None,
+        }
+    }
+}
+
+/// Each invocation sends the Preamble with every bytecode in place of its
+/// source, so an answer that would carry it past the payload cap would trap
+/// every invocation the source alone fits.
+fn replay_fits(preamble: &Preamble, bytecodes: &[Vec<u8>]) -> bool {
+    let mut replay = preamble.clone();
+    let sources = replay
+        .snippets
+        .entries
+        .iter_mut()
+        .filter(|entry| matches!(entry, Snippet::Source { .. }));
+    for (entry, body) in sources.zip(bytecodes) {
+        *entry = Snippet::Bytecode { body: body.clone() };
+    }
+    guest_mem::checked_payload_len(replay.encode().len()).is_ok()
+}
+
+/// A frontend replays each bytecode in place of one source snippet, in
+/// order, so an answer of any other length leaves nothing to replay.
+fn one_per_source(preamble: &Preamble, bytecodes: Vec<Vec<u8>>) -> Option<Vec<Vec<u8>>> {
+    let sources = preamble
+        .snippets
+        .entries
+        .iter()
+        .filter(|entry| matches!(entry, Snippet::Source { .. }))
+        .count();
+    (bytecodes.len() == sources).then_some(bytecodes)
 }
 
-/// 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. Also closes the
-/// `wall_time` bracket opened by `Driver::prime_caps`. Paired
-/// with `Driver::prime_caps`.
 fn disarm_caps(store: &mut WtStore<Invocation>) {
     store.data_mut().stop_wall_clock();
     store.data_mut().disarm_memory_cap();
 }
+
+#[cfg(test)]
+mod tests {
+    use kobako_transport::envelope::Snippets;
+
+    use super::*;
+
+    /// One source between two bytecode snippets: a compile answers one
+    /// bytecode for it.
+    fn one_source() -> Preamble {
+        let mut preamble = Preamble::default();
+        preamble.snippets = Snippets {
+            entries: vec![
+                Snippet::Bytecode { body: vec![0xaa] },
+                Snippet::Source {
+                    name: "Only".into(),
+                    body: "1".into(),
+                },
+                Snippet::Bytecode { body: vec![0xbb] },
+            ],
+        };
+        preamble
+    }
+
+    // @behavior WE-089
+    #[test]
+    fn a_compiled_answer_of_another_length_leaves_nothing_compiled() {
+        let preamble = one_source();
+
+        assert_eq!(
+            [
+                one_per_source(&preamble, Vec::new()),
+                one_per_source(&preamble, vec![vec![0x01], vec![0x02]]),
+                one_per_source(&preamble, vec![vec![0x01]]),
+            ],
+            [None, None, Some(vec![vec![0x01]])],
+            "a compiled answer through Driver#compile must be kept only when it carries one \
+             bytecode per source snippet"
+        );
+    }
+}

data/crates/kobako-wasmtime/src/exports.rs

@@ -1,56 +1,47 @@
 //! Per-invocation wasmtime export handles for the host-driven ABI
 //! surface.
 //!
-//! `Driver::instantiate` resolves the ABI exports the run path drives
-//! (`__kobako_eval` / `__kobako_run` / `__kobako_take_outcome` /
-//! `__kobako_alloc`) plus the `memory` export against each fresh
-//! per-invocation instance and bundles their
-//! typed handles here, so the invocation body passes one struct around
-//! rather than re-resolving exports by name at every step. Distinct
-//! from `crate::cache` (the process-wide Engine / Module cache): this
-//! carries *which guest function to call*, per invocation.
-//!
-//! `crate::dispatch` does not reach this struct — a host import runs
-//! against a `Caller`, so the dispatch path resolves `__kobako_alloc`
-//! and `memory` through `Caller::get_export` instead.
+//! Each ABI export is named and typed once, here, against each fresh
+//! per-invocation instance. The invocation body and the host imports
+//! running inside it both drive the guest through these handles, never
+//! by looking an export up by name. Distinct from `crate::cache` (the
+//! process-wide Engine / Module cache): this carries *which guest
+//! function to call*, per invocation.
 
 use wasmtime::{AsContextMut, Instance as WtInstance, Memory, TypedFunc};
 
+use crate::guest_mem::SANDBOX_RUNTIME_NOT_KOBAKO;
+use kobako_runtime::error::Trap;
+
+/// For a required guest export that is absent or mistyped, wherever it is
+/// looked up. Names neither the export nor a frontend's artifact path;
+/// what a caller can do is rebuild the runtime.
+pub(crate) const RUNTIME_INCOMPATIBLE: &str =
+    "the Sandbox runtime is incompatible; rebuild it against the kobako version in use";
+
 /// The resolved host-driven export handles. Each is `Option` because test
 /// fixtures (a minimal "ping" module) need not provide them; real
-/// `kobako.wasm` always does, and the run-path methods surface a `Trap`
-/// (via `require_export` / `require_memory`) when a handle is `None`.
+/// `kobako.wasm` always does, and the run path surfaces a `Trap` (via
+/// `require` / `Exports::require_memory`) when a handle is `None`.
 ///
 /// The handles are indices into the owning Store, not borrows of the
 /// `Instance` — they stay valid for the Store's lifetime, which is why
-/// no `Instance` field is kept.
+/// no `Instance` field is kept, and why a clone can ride in the Store's
+/// own data for the host imports to reach.
+#[derive(Clone)]
 pub(crate) struct Exports {
-    pub(crate) eval: Option<TypedFunc<(), ()>>,
-    pub(crate) run: Option<TypedFunc<(i32, i32), ()>>,
-    pub(crate) take_outcome: Option<TypedFunc<(), u64>>,
+    pub(crate) downcall: Option<TypedFunc<(i32, i32), u64>>,
     pub(crate) alloc: Option<TypedFunc<u32, u32>>,
     pub(crate) memory: Option<Memory>,
 }
 
 impl Exports {
-    /// Best-effort lookup of the host-driven exports against a freshly
-    /// instantiated module. Missing exports are not an error here
-    /// (the test fixture is a bare module); the host enforces presence at
-    /// invocation time. Only the SPEC ABI shapes are accepted —
-    /// `__kobako_eval` is `() -> ()`, `__kobako_run` is
-    /// `(env_ptr, env_len) -> ()`, `__kobako_take_outcome` is `() -> u64`,
-    /// `__kobako_alloc` is `(len) -> ptr`
-    /// (docs/wire-codec.md § ABI Signatures).
+    /// A missing export is not an error here, because the test fixture is a
+    /// bare module; presence is enforced at invocation time.
     pub(crate) fn resolve(instance: &WtInstance, mut ctx: impl AsContextMut) -> Self {
         Self {
-            eval: instance
-                .get_typed_func::<(), ()>(&mut ctx, "__kobako_eval")
-                .ok(),
-            run: instance
-                .get_typed_func::<(i32, i32), ()>(&mut ctx, "__kobako_run")
-                .ok(),
-            take_outcome: instance
-                .get_typed_func::<(), u64>(&mut ctx, "__kobako_take_outcome")
+            downcall: instance
+                .get_typed_func::<(i32, i32), u64>(&mut ctx, "__kobako_downcall")
                 .ok(),
             alloc: instance
                 .get_typed_func::<u32, u32>(&mut ctx, "__kobako_alloc")
@@ -58,4 +49,67 @@ impl Exports {
             memory: instance.get_memory(&mut ctx, "memory"),
         }
     }
+
+    pub(crate) fn require_memory(&self) -> Result<Memory, Trap> {
+        self.memory
+            .ok_or_else(|| Trap::Other(SANDBOX_RUNTIME_NOT_KOBAKO.to_string()))
+    }
+}
+
+pub(crate) fn require<Params, Results>(
+    export: Option<&TypedFunc<Params, Results>>,
+) -> Result<&TypedFunc<Params, Results>, Trap>
+where
+    Params: wasmtime::WasmParams,
+    Results: wasmtime::WasmResults,
+{
+    export.ok_or_else(|| Trap::Other(RUNTIME_INCOMPATIBLE.to_string()))
+}
+
+#[cfg(test)]
+mod tests {
+    //! The ABI is a closed set of guest exports, so the bundled Guest
+    //! Binary is read for what it exports rather than only for whether
+    //! `resolve` finds what it looks up — an extra entry point would pass
+    //! every lookup. A missing binary is a hard failure under
+    //! CI (which always builds it) and a silent skip locally.
+    use std::path::Path;
+
+    use wasmtime::ExternType;
+
+    use crate::cache::cached_module;
+
+    const WASM: &str = concat!(env!("CARGO_MANIFEST_DIR"), "/../../data/kobako.wasm");
+
+    const ABI_EXPORTS: [&str; 3] = [
+        "__kobako_abi_version",
+        "__kobako_alloc",
+        "__kobako_downcall",
+    ];
+
+    // @behavior RT-068
+    #[test]
+    fn the_guest_binary_exports_the_abi_functions_and_nothing_else() {
+        let path = Path::new(WASM);
+        if !path.exists() {
+            assert!(
+                std::env::var_os("CI").is_none(),
+                "data/kobako.wasm missing under CI — run `bundle exec rake wasm:build`"
+            );
+            return;
+        }
+        let module = cached_module(path).expect("the Guest Binary must load");
+
+        let mut functions: Vec<&str> = module
+            .exports()
+            .filter(|export| matches!(export.ty(), ExternType::Func(_)))
+            .map(|export| export.name())
+            .collect();
+        functions.sort_unstable();
+
+        assert_eq!(
+            functions, ABI_EXPORTS,
+            "data/kobako.wasm read through its export section must export exactly the ABI's functions"
+        );
+    }
 }