kobako 0.19.0 → 0.21.0

data/crates/kobako-transport/src/envelope/reply.rs

@@ -0,0 +1,240 @@
+//! The Reply envelope and its reverse-direction sibling, the Yield Reply.
+//!
+//! Success-versus-fault is decided by a tag byte rather than a reserved
+//! payload value, so a side learns the outcome of a Call whatever schema
+//! the payload carries.
+
+use super::bytes::{Reader, Writer};
+use super::{DecodeError, ErrorRecord, Fault};
+
+const TAG_OK: u8 = 0;
+const TAG_FAULT: u8 = 1;
+
+const YIELD_OK: u8 = 0x01;
+const YIELD_BREAK: u8 = 0x02;
+const YIELD_RESERVED: u8 = 0x03;
+const YIELD_ERROR: u8 = 0x04;
+
+/// The answer to one dispatch Call.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum Reply {
+    /// The method returned; the bytes are the value, codec-encoded.
+    Ok(Vec<u8>),
+    /// The method refused or failed. Typed rather than codec-encoded:
+    /// every field of a Fault is kobako's, so a guest reads a refusal
+    /// whatever schema it speaks.
+    Fault(Fault),
+}
+
+impl Reply {
+    pub fn decode(bytes: &[u8]) -> Result<Self, DecodeError> {
+        let mut reader = Reader::new(bytes);
+        let tag = reader.u8()?;
+        match tag {
+            TAG_OK => Ok(Reply::Ok(reader.remaining().to_vec())),
+            TAG_FAULT => {
+                let fault = Fault::read(&mut reader)?;
+                reader.finish()?;
+                Ok(Reply::Fault(fault))
+            }
+            _ => Err(DecodeError::new("Reply tag must be 0 (ok) or 1 (fault)")),
+        }
+    }
+
+    pub fn encode(&self) -> Vec<u8> {
+        let mut writer = Writer::new();
+        match self {
+            Reply::Ok(body) => {
+                writer.u8(TAG_OK).remainder(body);
+            }
+            Reply::Fault(fault) => {
+                writer.u8(TAG_FAULT);
+                fault.write(&mut writer);
+            }
+        }
+        writer.into_bytes()
+    }
+}
+
+/// The answer to one Yield Call. Carries a `Break` outcome the dispatch
+/// Reply has no counterpart for, because a block can end its caller.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum YieldReply {
+    /// The block completed; the bytes are its value, codec-encoded.
+    Ok(Vec<u8>),
+    /// The block ran `break`; the bytes are the break value,
+    /// codec-encoded. It returns to the guest rather than to host code.
+    Break(Vec<u8>),
+    /// The block raised, or failed in a way the host re-raises at the
+    /// yield site.
+    Error(ErrorRecord),
+}
+
+impl YieldReply {
+    pub fn decode(bytes: &[u8]) -> Result<Self, DecodeError> {
+        let mut reader = Reader::new(bytes);
+        let tag = reader.u8()?;
+        match tag {
+            YIELD_OK => Ok(YieldReply::Ok(reader.remaining().to_vec())),
+            YIELD_BREAK => Ok(YieldReply::Break(reader.remaining().to_vec())),
+            YIELD_ERROR => {
+                let record = ErrorRecord::read(&mut reader)?;
+                reader.finish()?;
+                Ok(YieldReply::Error(record))
+            }
+            YIELD_RESERVED => Err(DecodeError::new("Yield Reply tag 0x03 is reserved")),
+            _ => Err(DecodeError::new("Yield Reply tag is not recognised")),
+        }
+    }
+
+    pub fn encode(&self) -> Vec<u8> {
+        let mut writer = Writer::new();
+        match self {
+            YieldReply::Ok(body) => {
+                writer.u8(YIELD_OK).remainder(body);
+            }
+            YieldReply::Break(body) => {
+                writer.u8(YIELD_BREAK).remainder(body);
+            }
+            YieldReply::Error(record) => {
+                writer.u8(YIELD_ERROR);
+                record.write(&mut writer);
+            }
+        }
+        writer.into_bytes()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn both_reply_arms_round_trip() {
+        for reply in [
+            Reply::Ok(vec![0x2a]),
+            Reply::Fault(Fault::new(
+                super::super::FaultKind::Undefined,
+                "no such method",
+            )),
+        ] {
+            let encoded = reply.encode();
+            assert_eq!(
+                Reply::decode(&encoded),
+                Ok(reply),
+                "a Reply must survive a host encode and decode on both arms"
+            );
+        }
+    }
+
+    #[test]
+    fn an_empty_ok_body_round_trips() {
+        let encoded = Reply::Ok(Vec::new()).encode();
+        assert_eq!(
+            Reply::decode(&encoded),
+            Ok(Reply::Ok(Vec::new())),
+            "a Reply whose payload is empty must decode as an empty value, not a truncation"
+        );
+    }
+
+    #[test]
+    fn an_unknown_reply_tag_is_refused() {
+        assert!(
+            Reply::decode(&[9, 0]).is_err(),
+            "a Reply tag that is neither ok nor fault must be rejected as a wire violation"
+        );
+    }
+
+    #[test]
+    fn a_zero_length_reply_is_refused() {
+        assert!(
+            Reply::decode(&[]).is_err(),
+            "a zero-length Reply must be rejected rather than read as a missing tag"
+        );
+    }
+
+    #[test]
+    fn every_live_yield_arm_round_trips() {
+        let arms = [
+            YieldReply::Ok(vec![0xa4]),
+            YieldReply::Break(vec![0xa4]),
+            YieldReply::Error(ErrorRecord {
+                name: "LocalJumpError".into(),
+                message: "no block".into(),
+                backtrace: vec!["(eval):1".into()],
+            }),
+        ];
+        for arm in arms {
+            let encoded = arm.encode();
+            assert_eq!(
+                YieldReply::decode(&encoded),
+                Ok(arm),
+                "every live Yield Reply arm must survive a host encode and decode"
+            );
+        }
+    }
+
+    #[test]
+    fn the_reserved_yield_tag_is_refused() {
+        assert!(
+            YieldReply::decode(&[0x03]).is_err(),
+            "Yield Reply tag 0x03 must be rejected by both peers so it stays reserved"
+        );
+    }
+
+    #[test]
+    fn an_unknown_yield_tag_is_refused() {
+        assert!(
+            YieldReply::decode(&[0x7f]).is_err(),
+            "a Yield Reply tag outside the live set must be rejected as a wire violation"
+        );
+    }
+
+    #[test]
+    fn golden_layout_pins_the_reply_tags() {
+        // The same body on both arms: what separates "the Service returned
+        // this" from "the Service failed with this" is the tag alone, which
+        // is what lets a side read the outcome without a payload codec.
+        assert_eq!(
+            Reply::Ok(vec![0x2a]).encode(),
+            vec![0, 0x2a],
+            "a successful Reply must encode as tag byte 0 followed by the body alone"
+        );
+        assert_eq!(
+            Reply::Fault(Fault::new(super::super::FaultKind::Runtime, "x")).encode(),
+            vec![1, 0, 0, 0, 0, 1, b'x'],
+            "a fault Reply must encode as tag byte 1 followed by the Fault's own fixed \
+             layout, so a guest reads a refusal without reaching a payload codec"
+        );
+    }
+
+    #[test]
+    fn golden_layout_pins_the_yield_tags() {
+        assert_eq!(
+            YieldReply::Ok(vec![0xc0]).encode(),
+            vec![0x01, 0xc0],
+            "a Yield Reply carrying the block's value must encode as tag byte 0x01"
+        );
+        assert_eq!(
+            YieldReply::Break(vec![0xc0]).encode(),
+            vec![0x02, 0xc0],
+            "a Yield Reply carrying a break value must encode as tag byte 0x02"
+        );
+        assert_eq!(
+            YieldReply::Error(ErrorRecord {
+                name: "E".into(),
+                message: "m".into(),
+                backtrace: Vec::new(),
+            })
+            .encode(),
+            vec![
+                0x04, // tag: error
+                0, 0, 0, 1, b'E', // name
+                0, 0, 0, 1, b'm', // message
+                0, 0, 0, 0, // backtrace count
+            ],
+            "a Yield Reply carrying a guest failure must encode as tag byte 0x04 followed \
+             by an Error Record rather than a codec-encoded body"
+        );
+    }
+}

data/crates/kobako-transport/src/envelope/run.rs

@@ -0,0 +1,85 @@
+//! The Run envelope — the host→guest request one `#run` invocation carries.
+//!
+//! Run is Call's reverse-direction sibling — `entrypoint` routes it, the
+//! payload feeds it. It carries no `method` because the entrypoint is
+//! invoked through its own `#call`, and no `block_given` because `#run`
+//! supplies no block. It rides the command buffer rather than a stdin
+//! frame, so its length reaches the guest as an export argument.
+
+use super::bytes::{Reader, Writer};
+use super::DecodeError;
+
+/// One `#run` invocation: which top-level constant, and its arguments.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Run {
+    pub entrypoint: String,
+    pub payload: Vec<u8>,
+}
+
+impl Run {
+    pub fn decode(bytes: &[u8]) -> Result<Self, DecodeError> {
+        let mut reader = Reader::new(bytes);
+        let entrypoint = reader.text()?.to_owned();
+        Ok(Run {
+            entrypoint,
+            payload: reader.remaining().to_vec(),
+        })
+    }
+
+    pub fn encode(&self) -> Vec<u8> {
+        let mut writer = Writer::new();
+        writer
+            .bytes(self.entrypoint.as_bytes())
+            .remainder(&self.payload);
+        writer.into_bytes()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn a_run_round_trips() {
+        let run = Run {
+            entrypoint: "Entry".into(),
+            payload: vec![0x92, 0x90, 0x80],
+        };
+        let encoded = run.encode();
+        assert_eq!(
+            Run::decode(&encoded),
+            Ok(run),
+            "a Run must survive a host encode and decode unchanged"
+        );
+    }
+
+    #[test]
+    fn a_run_with_no_arguments_round_trips() {
+        let run = Run {
+            entrypoint: "Entry".into(),
+            payload: Vec::new(),
+        };
+        let encoded = run.encode();
+        assert_eq!(
+            Run::decode(&encoded),
+            Ok(run),
+            "a Run with an empty payload must decode as empty, not as a truncation"
+        );
+    }
+
+    #[test]
+    fn golden_layout_pins_the_run_field_order() {
+        let run = Run {
+            entrypoint: "E".into(),
+            payload: vec![0xc0],
+        };
+        assert_eq!(
+            run.encode(),
+            vec![
+                0, 0, 0, 1, b'E', // entrypoint
+                0xc0, // payload remainder
+            ],
+            "the Run byte layout must stay fixed for both peers to agree"
+        );
+    }
+}

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

@@ -0,0 +1,73 @@
+//! The core envelope — the fixed-layout outer frame of every host↔guest
+//! message.
+//!
+//! Routing and outcome attribution live here; everything a resolved method
+//! consumes rides through as an opaque `payload` this layer never reads. A
+//! tier that only routes messages therefore needs no payload codec at all,
+//! and the one an assembly does use is its own choice.
+//!
+//! A decoded envelope borrows the buffer it came from, so a payload reaches
+//! its reader as a view rather than a copy. The two fields a reader keeps
+//! past that buffer's life — a binding's path and a snippet's body, read
+//! from a frame at boot and consumed later — are copied at decode.
+//!
+//! No type here is `#[non_exhaustive]`. Every arm is a tag byte the layout
+//! document fixes, so the set grows only with an ABI version — and when it
+//! does, a peer that has not been taught the new arm should fail to
+//! compile rather than fall into a wildcard and answer a message it cannot
+//! read.
+//!
+//! This layer has one implementation, so its `golden_layout_*` tests are
+//! what hold it to the layout document. They spell each tag as the literal
+//! byte that document fixes, never as the constant beside it: a golden
+//! written from the constant compares the implementation to itself.
+//!
+//! [core envelope]: ../../../docs/wire/envelope.md
+
+pub(crate) mod bytes;
+pub mod call;
+pub mod error_record;
+pub mod fault;
+pub mod invocation_frames;
+pub mod outcome;
+pub mod reply;
+pub mod run;
+
+pub use call::{Call, Target};
+pub use error_record::ErrorRecord;
+pub use fault::{Fault, FaultKind};
+pub use invocation_frames::{Bindings, Snippet, Snippets};
+pub use outcome::{Origin, Outcome, Panic};
+pub use reply::{Reply, YieldReply};
+pub use run::Run;
+
+use std::fmt;
+
+/// A message that does not conform to the core envelope layout. Only
+/// decoding produces one — every `encode` is infallible — so the name says
+/// which direction it comes from.
+///
+/// The reason is a fixed string because every case is a wire violation the
+/// receiving side rejects rather than a condition a caller recovers from by
+/// inspecting it; it stays behind `message` so a later reason can carry more
+/// than a literal.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct DecodeError(&'static str);
+
+impl DecodeError {
+    pub const fn new(reason: &'static str) -> Self {
+        DecodeError(reason)
+    }
+
+    pub fn message(&self) -> &str {
+        self.0
+    }
+}
+
+impl fmt::Display for DecodeError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.write_str(self.0)
+    }
+}
+
+impl std::error::Error for DecodeError {}

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

@@ -0,0 +1,21 @@
+//! kobako-transport — the fixed tier of the kobako wire.
+//!
+//! A host, a payload codec, and a guest are chosen independently only
+//! because two things are the same in every assembly, and this crate is
+//! both of them:
+//!
+//! - `envelope` — the outer frame every host↔guest message rides in,
+//!   carrying routing and outcome attribution and handing the payload
+//!   through as bytes it never reads
+//! - `abi` — the version, the packed-return layout, the frame prefix, and
+//!   the size cap the two sides must already agree on to exchange a byte
+//!
+//! Every value here is spelled once. Nothing depends on an engine, an
+//! interpreter, or a schema — and nothing may come to: a tier every other
+//! tier composes against cannot carry a choice any of them might want to
+//! make differently.
+//!
+//! [core envelope]: ../../../docs/wire/envelope.md
+
+pub mod abi;
+pub mod envelope;

data/crates/kobako-wasmtime/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## [0.13.0](https://github.com/elct9620/kobako/compare/kobako-wasmtime-v0.12.0...kobako-wasmtime-v0.13.0) (2026-07-29)
+
+
+### ⚠ BREAKING CHANGES
+
+* **wasmtime:** put every cap in one struct, named the way the field is read
+* **runtime:** give the engine contract names an implementer can write
+* **transport:** name the core envelope's types after what they carry
+* **wire:** route every tier through the one envelope
+* **wire:** carry dispatch over the core envelope with an opaque payload
+
+### Features
+
+* **wire:** carry dispatch over the core envelope with an opaque payload ([556104b](https://github.com/elct9620/kobako/commit/556104bf86fdf481b5368b70af83eb0add4b2708))
+
+
+### Code Refactoring
+
+* **runtime:** give the engine contract names an implementer can write ([0a41491](https://github.com/elct9620/kobako/commit/0a41491360cf17def8245c0758679e92572b990f))
+* **transport:** name the core envelope's types after what they carry ([b44de65](https://github.com/elct9620/kobako/commit/b44de6502953826c567d4ef8a594561479f50c1d))
+* **wasmtime:** put every cap in one struct, named the way the field is read ([3f57860](https://github.com/elct9620/kobako/commit/3f578608b044d1ade0ae35231266cf3c9e517c02))
+* **wire:** route every tier through the one envelope ([c5cd33a](https://github.com/elct9620/kobako/commit/c5cd33a5346f49857fa6e1f45c9cf9b9bea0ff77))
+
+## [0.12.0](https://github.com/elct9620/kobako/compare/kobako-wasmtime-v0.11.0...kobako-wasmtime-v0.12.0) (2026-07-24)
+
+
+### Miscellaneous Chores
+
+* **kobako-wasmtime:** Synchronize kobako crates versions
+
 ## [0.11.0](https://github.com/elct9620/kobako/compare/kobako-wasmtime-v0.10.2...kobako-wasmtime-v0.11.0) (2026-07-19)
 
 

data/crates/kobako-wasmtime/Cargo.toml

@@ -15,7 +15,7 @@
 
 [package]
 name = "kobako-wasmtime"
-version = "0.11.0"
+version = "0.13.0"
 edition = "2021"
 description = "wasmtime implementation of the kobako host runtime contract."
 license = "Apache-2.0"
@@ -28,7 +28,10 @@ categories = ["wasm", "virtualization"]
 # The engine-neutral contract this crate implements. The version pin
 # rides the linked release group; the path keeps in-tree builds (and
 # the Ruby gem, which ships both crates) resolving locally.
-kobako-runtime = { version = "0.11.0", path = "../kobako-runtime" }
+kobako-runtime = { version = "0.13.0", path = "../kobako-runtime" }
+# The fixed tier: the core envelope this driver shuttles and the ABI
+# values it drives the exports against.
+kobako-transport = { version = "0.13.0", path = "../kobako-transport" }
 # wasmtime — host-side embedder for kobako.wasm. We disable default-features
 # and opt back in only what kobako needs: a Cranelift-backed runtime that can
 # compile a pre-built wasm32-wasip1 module on the host triple, plus the `wat`

data/crates/kobako-wasmtime/README.md

@@ -24,7 +24,7 @@ SDK consumes the same surface.
 
 ```toml
 [dependencies]
-kobako-wasmtime = "0.11.0" # x-release-please-version
+kobako-wasmtime = "0.13.0" # x-release-please-version
 ```
 
 ## License

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

@@ -1,29 +1,36 @@
 //! Per-`Driver` execution configuration.
 //!
-//! The wall-clock and per-channel capture caps a frontend forwards into
-//! `Driver::new`. A plain value carrier owned by the `Driver` — distinct
-//! from the process-wide engine/module `crate::cache` (which is shared
-//! across every sandbox) and from the per-invocation
-//! `crate::invocation::Invocation` (which the wasm engine mutates from
-//! inside a run). These caps are read only by `Driver` methods between
-//! runs, so they live here.
+//! Every cap a frontend forwards into `Driver::new`. A plain value carrier
+//! owned by the `Driver` — distinct from the process-wide engine/module
+//! `crate::cache` (which is shared across every sandbox) and from the
+//! per-invocation `crate::invocation::Invocation` (which the wasm engine
+//! mutates from inside a run).
+//!
+//! Field-for-field the same shape as the SDK's `kobako::Options`, and
+//! deliberately not shared with it: this struct is free to name a wasmtime
+//! type, and `Options` is not — an engine-free host must still be able to
+//! build the SDK.
 
 use std::time::Duration;
 
 use kobako_runtime::profile::Profile;
 
-/// Wall-clock and output caps plus the requested isolation profile for
-/// one `Driver`. `None` on any cap field disables that cap.
+/// The caps and requested isolation profile for one `Driver`. `None` on
+/// any cap field disables that cap.
 pub struct Config {
     /// Wall-clock cap for one guest `#eval` / `#run`. Stamped into a
     /// per-run `Instant` deadline by `Driver::prime_caps`.
     pub timeout: Option<Duration>,
+    /// Guest linear-memory cap, in bytes. Threaded into each fresh
+    /// `Invocation`, where the wasmtime `ResourceLimiter` callback
+    /// consumes it from inside the engine.
+    pub memory_limit: Option<usize>,
     /// Byte cap for guest stdout capture.
     /// Sizes the per-run `MemoryOutputPipe` and computes the truncation
     /// flag in `Driver::build_snapshot`.
-    pub stdout_limit_bytes: Option<usize>,
-    /// Byte cap for guest stderr capture. Mirror of `stdout_limit_bytes`.
-    pub stderr_limit_bytes: Option<usize>,
+    pub stdout_limit: Option<usize>,
+    /// Byte cap for guest stderr capture. Mirror of `stdout_limit`.
+    pub stderr_limit: Option<usize>,
     /// Isolation posture the frontend requested. The per-invocation
     /// WASI context is built to this rung — `Hermetic` freezes ambient
     /// time and entropy (`crate::ambient`), `Permissive` leaves the

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

@@ -5,19 +5,19 @@
 //! through the closure registered by `instance_pre::build_linker`.
 //! That closure delegates here. The dispatcher:
 //!
-//!   1. Reads the Request bytes from guest linear memory.
+//!   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 Response bytes.
+//!      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 Response bytes into the guest buffer.
+//!   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
-//! surface as Response.err envelopes from
+//! take the Reply's fault arm from
 //! `Kobako::Transport::Dispatcher.dispatch` itself — they never reach
 //! this 0-return path.
 //!
@@ -47,6 +47,8 @@
 
 use wasmtime::Caller;
 
+use kobako_transport::envelope::Call;
+
 use crate::invocation::Invocation;
 
 /// Drive a single `__kobako_dispatch` invocation end-to-end. Entry point
@@ -56,7 +58,7 @@ use crate::invocation::Invocation;
 /// 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 into Response.err envelopes),
+/// 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 {
@@ -77,6 +79,11 @@ fn try_handle(
     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"
+    })?;
 
     // `Kobako::Sandbox` always installs the dispatch handler before
     // invoking the runtime, so reaching this branch indicates a misuse
@@ -90,15 +97,15 @@ fn try_handle(
     // handler. The borrow ends with the block, freeing the Caller for
     // `write_response`; nested dispatch frames each build their own, so
     // the LIFO re-entry lives on the Rust stack — no shared slot.
-    let resp_bytes = {
+    let reply = {
         let mut yielder = crate::guest_mem::CallerYielder::new(caller);
-        handler.dispatch(&req_bytes, &mut yielder)
+        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, &resp_bytes)
+    write_response(caller, &reply.encode())
 }
 
 /// Allocate a guest-side buffer and copy the response bytes into it via