kobako 0.19.0 → 0.21.0

data/crates/kobako-runtime/Cargo.toml

@@ -13,7 +13,7 @@
 
 [package]
 name = "kobako-runtime"
-version = "0.11.0"
+version = "0.13.0"
 edition = "2021"
 description = "Engine-neutral host runtime contract for embedding kobako Wasm guests."
 license = "Apache-2.0"
@@ -21,3 +21,10 @@ repository = "https://github.com/elct9620/kobako"
 readme = "README.md"
 keywords = ["wasm", "mruby", "sandbox", "wasi"]
 categories = ["wasm", "virtualization"]
+
+# The fixed tier: the core envelope this contract routes and attributes
+# through. The version pin rides the linked release group; the path keeps
+# in-tree builds (and the Ruby gem, which ships both crates) resolving
+# locally.
+[dependencies]
+kobako-transport = { version = "0.13.0", path = "../kobako-transport" }

data/crates/kobako-runtime/README.md

@@ -26,7 +26,7 @@ map the neutral types onto their own language surface.
 
 ```toml
 [dependencies]
-kobako-runtime = "0.11.0" # x-release-please-version
+kobako-runtime = "0.13.0" # x-release-please-version
 ```
 
 ## License

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

@@ -1,22 +1,28 @@
 //! Engine-neutral guest→host dispatch contract, free of any `magnus`
 //! dependency.
 //!
-//! The wasm runtime hands a handler the raw Request bytes a guest produced
-//! and expects raw Response bytes back. What the handler *is* — a Ruby Proc,
-//! a Rust closure — is the frontend's concern; the runtime only sees this
-//! trait. The Ruby ext conforms by bridging its dispatch Proc behind it.
+//! The runtime decodes the core envelope and hands a handler the routed
+//! `Call` — target, method, block flag, and the payload bytes it never
+//! reads — then expects a `Reply` back. What the handler *is* — a Ruby
+//! Proc, a Rust closure — is the frontend's concern; the runtime only sees
+//! this trait. The Ruby ext conforms by bridging its dispatch Proc behind
+//! it.
 
 use crate::yielder::Yielder;
+use kobako_transport::envelope::{Call, Reply};
 
 /// Host-side handler for a guest→host dispatch.
 ///
-/// `dispatch` receives the request bytes plus a `Yielder` for re-entering
+/// `dispatch` receives the decoded Call plus a `Yielder` for re-entering
 /// the in-flight guest when a Service method yields to a block, and returns
-/// the raw Response bytes — or `None` when the handler itself failed, in
-/// which case the runtime walks its 0-return wire-fault path. The bound
-/// handler is contracted to fold application failures into a `Response.err`
-/// envelope, so `None` signals a contract violation (the handler raised)
-/// rather than a normal dispatch outcome.
+/// the Reply — or `None` when the handler itself failed, in which case the
+/// runtime walks its 0-return wire-fault path. The bound handler is
+/// contracted to fold application failures into the Reply's fault arm, so
+/// `None` signals a contract violation (the handler raised) rather than a
+/// normal dispatch outcome.
+///
+/// The `Call` borrows the buffer the runtime decoded, so a handler passes
+/// the payload onward without copying it first.
 pub trait DispatchHandler: Send + Sync {
-    fn dispatch(&self, request: &[u8], yielder: &mut dyn Yielder) -> Option<Vec<u8>>;
+    fn dispatch(&self, call: Call<'_>, yielder: &mut dyn Yielder) -> Option<Reply>;
 }

data/crates/kobako-runtime/src/error.rs

@@ -13,7 +13,12 @@ use std::fmt;
 /// kinds a frontend surfaces distinctly: the wall-clock cap (`Timeout`),
 /// the linear-memory cap (`MemoryLimit`), and every other engine fault
 /// (`Other`).
+///
+/// Non-exhaustive: a frontend matches this to reach its own error classes,
+/// and a later kind must not break that match. `Other` is where an
+/// unrecognised one belongs.
 #[derive(Debug)]
+#[non_exhaustive]
 pub enum Trap {
     Timeout(String),
     MemoryLimit(String),
@@ -26,7 +31,11 @@ pub enum Trap {
 /// could not be constructed), and `Intact` (the runtime is live but a
 /// host-side pre-call step failed, so no discard-and-recreate recovery is
 /// owed).
-#[derive(Debug)]
+///
+/// Non-exhaustive, as `Trap`: a frontend maps each state onto its own
+/// class, and a later state must not break that match.
+#[derive(Debug, Clone, PartialEq, Eq)]
+#[non_exhaustive]
 pub enum SetupError {
     ModuleNotBuilt(String),
     Dead(String),
@@ -38,21 +47,37 @@ pub enum SetupError {
 /// the run mechanics can propagate both with `?`; a frontend destructures
 /// it back into the two channels. Faults after the guest export starts
 /// ride in `Completion::Trap` instead, so captures and usage survive them.
+///
+/// Named for where it comes from — the `Err` of `Runtime::invoke` — so a
+/// host that also has its own `Error` in scope can hold both.
+///
+/// Non-exhaustive, as its two channels are: a later way an invocation can
+/// fail to start must not break the frontends already destructuring it.
 #[derive(Debug)]
-pub enum Error {
+#[non_exhaustive]
+pub enum InvokeError {
     Trap(Trap),
     Setup(SetupError),
 }
 
-impl From<Trap> for Error {
+impl From<Trap> for InvokeError {
     fn from(trap: Trap) -> Self {
-        Error::Trap(trap)
+        InvokeError::Trap(trap)
     }
 }
 
-impl From<SetupError> for Error {
+impl From<SetupError> for InvokeError {
     fn from(err: SetupError) -> Self {
-        Error::Setup(err)
+        InvokeError::Setup(err)
+    }
+}
+
+impl fmt::Display for InvokeError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            InvokeError::Trap(trap) => trap.fmt(f),
+            InvokeError::Setup(err) => err.fmt(f),
+        }
     }
 }
 
@@ -70,3 +95,10 @@ impl fmt::Display for SetupError {
         f.write_str(msg)
     }
 }
+
+// Both channels sit on the seam a third-party engine implements against,
+// where a caller wants to lift them into `Box<dyn Error>` or `anyhow` with
+// `?`. `Trap` carries no source of its own, so neither reports one.
+impl std::error::Error for SetupError {}
+
+impl std::error::Error for InvokeError {}

data/crates/kobako-runtime/src/lib.rs

@@ -2,8 +2,9 @@
 //!
 //! The surface where a wasm engine implementation and a host frontend
 //! meet: the `Runtime` trait, the isolation `Profile` a runtime
-//! declares, the neutral per-invocation value types, and the
-//! dispatch / yield re-entry traits a frontend supplies.
+//! declares, the neutral per-invocation value types, and the dispatch /
+//! yield re-entry traits a frontend supplies. The messages these carry
+//! are `kobako-transport`'s, which this crate takes as given.
 //! Nothing here depends on an engine or a frontend type — each engine
 //! hides its own machinery behind `Runtime`, and each frontend maps
 //! these shapes onto its own host-language surface at its boundary
@@ -16,3 +17,13 @@ pub mod profile;
 pub mod runtime;
 pub mod snapshot;
 pub mod yielder;
+
+// Every name an engine implementation writes into its own signatures, at
+// the crate root: the module path repeats the crate name and adds nothing
+// a reader of `kobako_runtime::Runtime` was missing.
+pub use dispatch::DispatchHandler;
+pub use error::{InvokeError, SetupError, Trap};
+pub use profile::Profile;
+pub use runtime::{Entry, Frames, Runtime};
+pub use snapshot::{Capture, Completion, Snapshot, Usage};
+pub use yielder::Yielder;

data/crates/kobako-runtime/src/profile.rs

@@ -16,6 +16,14 @@
 /// live ambient time and entropy at the WASI boundary. Ordering
 /// follows strength (`Permissive < Hermetic`), so a floor check is a
 /// plain comparison.
+///
+/// Deliberately not `#[non_exhaustive]`, unlike this crate's error
+/// types. A wildcard arm here would let a runtime silently keep building
+/// the posture it already knows while declaring it satisfied a rung it
+/// never implemented; the compile error a new rung causes is what forces
+/// each runtime to answer for it. The ordering is the same reason — a
+/// rung inserted mid-ladder changes what every existing `>=` means, which
+/// no wildcard could have absorbed either.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
 pub enum Profile {
     Permissive,

data/crates/kobako-runtime/src/runtime.rs

@@ -10,13 +10,18 @@
 use std::sync::Arc;
 
 use crate::dispatch::DispatchHandler;
-use crate::error::Error;
+use crate::error::InvokeError;
 use crate::profile::Profile;
 use crate::snapshot::Snapshot;
 
 /// The per-invocation entry: a one-shot mruby source (`Eval`) or an
 /// entrypoint-dispatch envelope (`Run`). Both ride alongside the stdin
 /// `Frames`; `Run` additionally copies its envelope into guest memory.
+///
+/// Closed rather than `#[non_exhaustive]`: the arms are the ABI's
+/// invocation exports, so the set only grows with an ABI version, and a
+/// runtime that has not implemented the new export should fail to
+/// compile rather than fall into a wildcard.
 pub enum Entry<'a> {
     Eval { source: &'a [u8] },
     Run { envelope: &'a [u8] },
@@ -47,7 +52,7 @@ pub trait Runtime {
         entry: Entry<'_>,
         frames: Frames<'_>,
         handler: Option<Arc<dyn DispatchHandler>>,
-    ) -> Result<Snapshot, Error>;
+    ) -> Result<Snapshot, InvokeError>;
 
     /// The isolation profile this runtime provides. Deliberately
     /// without a default: every engine states its posture explicitly,

data/crates/kobako-runtime/src/snapshot.rs

@@ -5,6 +5,10 @@
 //! completed, the two captured output channels, and the resource usage.
 //! A `Snapshot` exists iff the guest export ran — a failure to even start
 //! the invocation travels on the `invoke` `Err` channel instead.
+//!
+//! `Usage` and `Capture` are shared with the tier above rather than
+//! translated at its boundary: what they carry is already frontend-free,
+//! so the Rust host SDK re-exports these types themselves.
 
 use crate::error::Trap;
 
@@ -18,10 +22,15 @@ pub struct Capture {
     pub truncated: bool,
 }
 
-/// How the guest invocation completed: `Outcome` carries the
-/// OUTCOME_BUFFER bytes the guest returned; `Trap` is an engine fault
-/// after the export call started, kept as a value so the rest of the
-/// `Snapshot` survives it.
+/// How the guest invocation completed: `Outcome` carries the encoded
+/// Outcome envelope, still undecoded; `Trap` is an engine fault after the
+/// export call started, kept as a value so the rest of the `Snapshot`
+/// survives it.
+///
+/// Closed rather than `#[non_exhaustive]`: an invocation either produced
+/// its final message or the engine stopped it, and there is no third way
+/// for one to end. A wildcard would only hide a frontend that had not
+/// been told otherwise.
 pub enum Completion {
     Outcome(Vec<u8>),
     Trap(Trap),

data/crates/kobako-runtime/src/yielder.rs

@@ -4,7 +4,7 @@
 //! During a guest→host dispatch, a Service method may yield to a guest
 //! block. The host drives that re-entry through a `Yielder`: it ships the
 //! yield-arguments payload into the in-flight guest and returns the
-//! YieldResponse bytes. What backs the re-entry — a wasmtime `Caller`, some
+//! Yield Reply bytes. What backs the re-entry — a wasmtime `Caller`, some
 //! other engine handle — is the implementer's concern; the dispatch
 //! contract sees only this trait.
 
@@ -13,10 +13,10 @@ use crate::error::Trap;
 /// Host-initiated re-entry into the in-flight guest instance to run a
 /// yielded block.
 ///
-/// `yield_block` ships `args` to `__kobako_yield_to_block` and returns the
-/// raw YieldResponse bytes, or a `Trap` — surfaced through the frontend's
+/// `yield_to_block` ships `args` to `__kobako_yield_to_block` and returns
+/// the raw Yield Reply bytes, or a `Trap` — surfaced through the frontend's
 /// trap-error mapping — when the re-entry traps, the guest returns an empty
 /// result, or a payload exceeds the 16 MiB cap.
 pub trait Yielder {
-    fn yield_block(&mut self, args: &[u8]) -> Result<Vec<u8>, Trap>;
+    fn yield_to_block(&mut self, args: &[u8]) -> Result<Vec<u8>, Trap>;
 }

data/crates/kobako-transport/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+## [0.13.0](https://github.com/elct9620/kobako/compare/kobako-transport-v0.12.0...kobako-transport-v0.13.0) (2026-07-29)
+
+
+### ⚠ BREAKING CHANGES
+
+* **runtime:** mark the sets that grow, and say why the closed ones do not
+* **transport:** let every envelope spell its success arm the same way
+* **transport:** name the core envelope's types after what they carry
+* **wire:** carry a Reply's fault arm on the envelope
+* **transport:** split the invocation module along the line its doc draws
+
+### Features
+
+* **runtime:** mark the sets that grow, and say why the closed ones do not ([1be2449](https://github.com/elct9620/kobako/commit/1be24492961e2c2a3a317f784cc2f20ae584dcbf))
+* **transport:** add kobako-transport, one implementation of the envelope ([23f2401](https://github.com/elct9620/kobako/commit/23f240111a4c59e8f521bec911f9cf1cd7287744))
+* **transport:** give the ABI's fixed values one definition each ([94754ec](https://github.com/elct9620/kobako/commit/94754ecb538286077b6b58d90504b458ac0e4a2c))
+* **wire:** carry a Reply's fault arm on the envelope ([0bce850](https://github.com/elct9620/kobako/commit/0bce850b3416696e92ae6ee12c353c4c21c8e583))
+
+
+### Bug Fixes
+
+* **wire:** keep the ABI at 3, which no release has shipped ([2b301b7](https://github.com/elct9620/kobako/commit/2b301b777384c0edf79426805cfb1cc08688aa95))
+
+
+### Code Refactoring
+
+* **transport:** let every envelope spell its success arm the same way ([df595e0](https://github.com/elct9620/kobako/commit/df595e08097af9e3e0a0c5ed52a4a6f854eb21dc))
+* **transport:** name the core envelope's types after what they carry ([b44de65](https://github.com/elct9620/kobako/commit/b44de6502953826c567d4ef8a594561479f50c1d))
+* **transport:** split the invocation module along the line its doc draws ([4d3a2d3](https://github.com/elct9620/kobako/commit/4d3a2d3060167d71a807e203688186740fd1485b))

data/crates/kobako-transport/Cargo.toml

@@ -0,0 +1,27 @@
+# kobako-transport — the fixed tier of the kobako wire.
+#
+# The core envelope: the outer frame every host↔guest message rides in,
+# carrying routing and outcome attribution and handing the payload
+# through untouched. A host, a payload codec, and a guest are chosen
+# independently only because this layer is the same in every assembly,
+# so it depends on nothing and everything else depends on it.
+#
+# Self-contained by design: the Ruby gem ships this crate without the
+# `crates/` workspace manifest, so no `workspace = true` inheritance
+# fields may appear here.
+
+[package]
+name = "kobako-transport"
+version = "0.13.0"
+edition = "2021"
+description = "The kobako core envelope — the fixed host↔guest wire frame every assembly shares."
+license = "Apache-2.0"
+repository = "https://github.com/elct9620/kobako"
+readme = "README.md"
+keywords = ["wasm", "mruby", "sandbox", "wasi"]
+categories = ["wasm", "encoding"]
+
+# No dependencies, and none may be added: a tier every other tier
+# depends on cannot carry a choice any of them might want to make
+# differently.
+[dependencies]

data/crates/kobako-transport/README.md

@@ -0,0 +1,43 @@
+# kobako-transport
+
+The fixed tier of the [kobako](https://github.com/elct9620/kobako) wire —
+an in-process Wasm sandbox for running untrusted mruby scripts.
+
+kobako is assembled from three parts chosen independently: a host, a
+payload codec, and a guest. That works only because two things are the
+same in every assembly. This crate is both of them, and nothing else:
+
+- `envelope` — the **core envelope**, the outer frame each message rides
+  in: `Call` / `Reply` / `YieldReply` for a dispatch round-trip,
+  `Outcome` / `Panic` for how an invocation ended, `Run` / `Preamble` /
+  `Snippets` for what an invocation is handed, and the `ErrorRecord` a
+  guest failure carries
+- `abi` — the values a host and a guest must already agree on to
+  exchange a byte: the version, the packed `(ptr, len)` return layout,
+  the invocation-channel frame prefix, and the message size cap
+
+The envelope reads a message's routing fields and its ok-versus-fault
+tag without decoding a payload byte; everything the resolved method
+consumes rides through as an opaque `payload` this layer never reads.
+A decoded envelope borrows the buffer it came from, so that payload
+reaches its reader as a view rather than a copy.
+
+This crate depends on no other, and every kobako tier depends on it:
+`kobako-runtime` and `kobako-wasmtime` on the host, `kobako-core` and
+`kobako-mruby` in the guest, and any third-party engine, codec, or
+guest that composes against them.
+
+The byte layout is specified in
+[`docs/wire/envelope.md`](https://github.com/elct9620/kobako/blob/main/docs/wire/envelope.md);
+the golden vectors in this crate are derived from that document.
+
+## Usage
+
+```toml
+[dependencies]
+kobako-transport = "0.13.0" # x-release-please-version
+```
+
+## License
+
+Apache-2.0

data/crates/kobako-transport/src/abi.rs

@@ -0,0 +1,89 @@
+//! The ABI's fixed values — the numbers and layouts a host and a guest
+//! must already agree on before either can read the other's bytes.
+//!
+//! The exports and the host import that carry the ABI are declared where
+//! they are implemented: the guest contract crate emits the exports, the
+//! driver resolves them. What lives here is what both sides must spell the
+//! same way, and each value is spelled once.
+//!
+//! [ABI signatures]: ../../../docs/wire-codec.md
+
+/// The Guest ABI version. A host accepts a Guest Binary only when the
+/// version it reports equals this one, so a wire change is an increment
+/// rather than a negotiation.
+pub const ABI_VERSION: u32 = 3;
+
+/// Width in bytes of the length prefix that precedes each invocation-channel
+/// frame and the outcome buffer.
+pub const FRAME_LEN_SIZE: usize = 4;
+
+/// Single-dispatch size cap: 16 MiB in either direction, applied to the
+/// whole envelope rather than the payload alone. A larger transfer is a
+/// wire violation the receiving side refuses before allocating for it.
+pub const MAX_DISPATCH_PAYLOAD: usize = 16 * 1024 * 1024;
+
+/// Allocation ceiling on a length-prefixed frame. A reader learns a frame's
+/// length before it can check anything else about it, so this bounds what a
+/// declared length may make it allocate. It sits above
+/// `MAX_DISPATCH_PAYLOAD` because it guards the read rather than enforcing
+/// the contract: a frame between the two is allocated and then refused on
+/// its merits.
+pub const MAX_FRAME_LEN: usize = 64 * 1024 * 1024;
+
+// The read guard must admit every frame the contract allows, so a refusal
+// names the cap rather than the allocation ceiling.
+const _: () = assert!(MAX_FRAME_LEN > MAX_DISPATCH_PAYLOAD);
+
+/// Pack `(ptr, len)` into the u64 the ABI's three buffer-returning
+/// functions answer with: the high 32 bits carry the linear-memory pointer,
+/// the low 32 the byte length. A `len` of zero is the failure signal.
+///
+/// ```text
+///  63        32 31         0
+///  ┌──────────┬────────────┐
+///  │   ptr    │    len     │
+///  └──────────┴────────────┘
+/// ```
+#[inline]
+pub fn pack_ptr_len(ptr: u32, len: u32) -> u64 {
+    ((ptr as u64) << 32) | (len as u64)
+}
+
+/// Read a packed u64 back into `(ptr, len)`.
+#[inline]
+pub fn unpack_ptr_len(packed: u64) -> (u32, u32) {
+    ((packed >> 32) as u32, packed as u32)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn the_layout_is_high_ptr_low_len() {
+        let packed = pack_ptr_len(0xAABB_CCDD, 0x1122_3344);
+        assert_eq!(
+            packed, 0xAABB_CCDD_1122_3344,
+            "the packed u64 must carry ptr in the high half and len in the low half"
+        );
+    }
+
+    #[test]
+    fn every_pair_round_trips() {
+        for &(ptr, len) in &[
+            (0u32, 0u32),
+            (0x1000, 1024),
+            (0x0001_0000, 4),
+            (0x7fff_ffff, 0xffff),
+            (1, u32::MAX),
+            (u32::MAX, 1),
+            (u32::MAX, u32::MAX),
+        ] {
+            assert_eq!(
+                unpack_ptr_len(pack_ptr_len(ptr, len)),
+                (ptr, len),
+                "a ({ptr:#x}, {len:#x}) pair must survive the pack the ABI returns"
+            );
+        }
+    }
+}