kobako 0.21.1 → 0.22.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ff585432220deec2b7a21f062f070e6b13c2d95529b8e636c70452bb377f24f1
-  data.tar.gz: 63401be88c3d166e3ebca35106e5c4b8ca005490da41c4625a42cbeda0c04ae5
+  metadata.gz: 771a65c05a0d065db98f2644a978e4f82ab0cedb453f3cb7f6e61aea936be707
+  data.tar.gz: 330ab0d4762778e9608325be5b6fc737eeb82e0ff1b4d30eeac29ff8fac9902b
 SHA512:
-  metadata.gz: 4bf8515bd5840ab2e8288e7a7f5942f50c402724f670efa570719f9be3181c7052044d2ab51f3fd42fffc4b61f7f269abaad7afa866b20f0a7b7f57d53a12bd9
-  data.tar.gz: 52fe4c1ddedd100757b0fcdb952c662585d30e21003df98b5cc97bea22eb20545c530accd87d7f2d684aac9eb64339e4b147537719df89355b890daa346081b5
+  metadata.gz: 6fd6084f9566a7f9466f8b58f308914dae445c2ee43ed4cd1ccd721db01d609b99257f404e0ff00ae6e5fb3bbac45e453afc933eb1d3b23210df709ca9914962
+  data.tar.gz: c113d2ef16f413ad41c4d97cb3d5675d4f2ac151879257ffc9f3d918a27f471667d936c7fe13120d9a78e73ab6fee041700e3bed8f3315c9d680d742213014ac

data/.release-please-manifest.json

@@ -1 +1 @@
-{".":"0.21.1","wasm/kobako-core":"0.13.1","wasm/kobako-mruby":"0.13.1","wasm/kobako-io":"0.13.1","wasm/kobako-json":"0.13.1","wasm/kobako-regexp":"0.13.1","wasm/kobako-baker":"0.13.1","crates/kobako-transport":"0.13.1","crates/kobako-codec":"0.13.1","crates/kobako-runtime":"0.13.1","crates/kobako-wasmtime":"0.13.1","crates/kobako":"0.13.1"}
+{".":"0.22.0","wasm/kobako-core":"0.14.0","wasm/kobako-mruby":"0.14.0","wasm/kobako-io":"0.14.0","wasm/kobako-json":"0.14.0","wasm/kobako-regexp":"0.14.0","wasm/kobako-baker":"0.14.0","crates/kobako-transport":"0.14.0","crates/kobako-codec":"0.14.0","crates/kobako-runtime":"0.14.0","crates/kobako-wasmtime":"0.14.0","crates/kobako":"0.14.0"}

data/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## [0.22.0](https://github.com/elct9620/kobako/compare/v0.21.1...v0.22.0) (2026-08-06)
+
+
+### Features
+
+* **spec:** give the ubiquitous language a place N-6 can be checked from ([ab44dba](https://github.com/elct9620/kobako/commit/ab44dba0b08e558a5b96b95b3c4d1c70bf6bc7ad))
+* **transport:** give a failed Service call a class that says why ([b39f176](https://github.com/elct9620/kobako/commit/b39f1761e9922b7ac761571393f9a6f4478ae522))
+* **transport:** let a guest block's exception continue as itself ([c8b1de7](https://github.com/elct9620/kobako/commit/c8b1de7154336fab8fa20c0d7a5b3baaad11d551))
+* **transport:** separate a failed exchange from a failed Service ([fb92515](https://github.com/elct9620/kobako/commit/fb92515fc76ffebbb8491b525d53b1725cf97dd0))
+
+
+### Bug Fixes
+
+* **codec:** keep a value the packer cannot walk inside the codec taxonomy ([ac99d58](https://github.com/elct9620/kobako/commit/ac99d58f0c9a274b230d645d7c37aba88516eab2))
+* **regexp:** stop raising where MRI answers no match ([d229974](https://github.com/elct9620/kobako/commit/d2299740a2a0206c88e7c397cdb72dc730c4c1cf))
+* **transport:** answer a held block failure only to the block that raised ([24dfd6e](https://github.com/elct9620/kobako/commit/24dfd6ec999e0ba1587b9c69da6d2b29563fc875))
+* **transport:** report a yield the host cannot write as the Service's ([19459f8](https://github.com/elct9620/kobako/commit/19459f87555190043127290441bf6b95bcad93d6))
+* **transport:** report an answer the host cannot write as the Service's ([bff4cdc](https://github.com/elct9620/kobako/commit/bff4cdccc076859d7da43f5dedb9a283ffed94ee))
+* **transport:** spend a block's failure when its Service yields again ([3042a72](https://github.com/elct9620/kobako/commit/3042a72b9e3bb0d6a1d5cb5734d7eaee6a669e85))
+* **wire:** let a Fault reader survive what it predates ([eeabfb7](https://github.com/elct9620/kobako/commit/eeabfb7aa4de3d08852ca1b41517b924d72a7312))
+
 ## [0.21.1](https://github.com/elct9620/kobako/compare/v0.21.0...v0.21.1) (2026-07-30)
 
 

data/Cargo.lock

@@ -858,7 +858,7 @@ checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"
 
 [[package]]
 name = "kobako"
-version = "0.21.1"
+version = "0.22.0"
 dependencies = [
  "kobako-runtime",
  "kobako-transport",
@@ -869,18 +869,18 @@ dependencies = [
 
 [[package]]
 name = "kobako-runtime"
-version = "0.13.1"
+version = "0.14.0"
 dependencies = [
  "kobako-transport",
 ]
 
 [[package]]
 name = "kobako-transport"
-version = "0.13.1"
+version = "0.14.0"
 
 [[package]]
 name = "kobako-wasmtime"
-version = "0.13.1"
+version = "0.14.0"
 dependencies = [
  "kobako-runtime",
  "kobako-transport",

data/README.md

@@ -321,7 +321,7 @@ For workloads that must be isolated from each other (one Sandbox per tenant, per
 
 For hosts that serve many short invocations, `Kobako::Pool` keeps a bounded set of warm, identically set-up Sandboxes and hands each one to a single exclusive holder at a time ([`docs/behavior/runtime.md`](docs/behavior/runtime.md) B-46..B-48). Construction forwards every `Sandbox.new` keyword verbatim; the optional block is the per-Sandbox setup window and runs exactly once per constructed Sandbox.
 
-`Kobako::Pool` is experimental today and is best treated as a convenience for warm, pre-configured reuse rather than a throughput optimisation. B-49 bakes the shared boot state into the artifact and every dynamic script still compiles and runs per invocation, so all a pool actually saves is the ~28 µs host-side `Sandbox.new`. For the workload kobako is built for — many small, short-lived Sandboxes running dynamic scripts — that is not a significant gain (~4-5% in the [serverless example](examples/serverless/README.md), and proportionally less once the script itself does real work). What a Pool buys is warm setup and exclusive checkout, not isolation: a Sandbox holds no state from any run, so Threads sharing one are equally safe (see [Concurrency](#concurrency)).
+`Kobako::Pool` is experimental today and is best treated as a convenience for warm, pre-configured reuse rather than a throughput optimisation. B-49 bakes the shared boot state into the artifact and every dynamic script still compiles and runs per invocation, so all a pool actually saves is the host-side `Sandbox.new` — now under 3 µs, an order of magnitude below the invocation that follows it. For the workload kobako is built for — many small, short-lived Sandboxes running dynamic scripts — that is not a gain worth the coupling. What a Pool buys is warm setup and exclusive checkout, not isolation: a Sandbox holds no state from any run, so Threads sharing one are equally safe (see [Concurrency](#concurrency)).
 
 ```ruby
 pool = Kobako::Pool.new(slots: 4) do |sandbox|
@@ -498,17 +498,17 @@ Order-of-magnitude figures on macOS arm64, Ruby 3.4.7, YJIT off. Absolute values
 | Phase                                                        | Cost                  |
 |--------------------------------------------------------------|-----------------------|
 | First `Sandbox.new` ever for a Guest Binary (Module JIT, then disk-cached) | ~500 ms once per machine |
-| First `Sandbox.new` in a fresh process (`.cwasm` cache warm) | ~3 ms one-time        |
-| Subsequent `Sandbox.new` (caches warm)                       | ~28 µs                |
-| Warm `#eval("nil")` on a reused Sandbox                      | ~71 µs                |
-| Warm `#run(:Entrypoint, ...)` dispatch                       | ~97 µs                |
-| Service call amortized inside one invocation                 | ~6.8 µs               |
-| Snippet replay per invocation                                | ~7.6 µs each          |
+| First `Sandbox.new` in a fresh process (`.cwasm` cache warm) | ~1.3 ms one-time      |
+| Subsequent `Sandbox.new` (caches warm)                       | ~3 µs                 |
+| Warm `#eval` with one Service call on a reused Sandbox       | ~71 µs                |
+| Warm `#run(:Entrypoint, ...)` dispatch                       | ~81 µs                |
+| Service call amortized inside one invocation                 | ~5.7 µs               |
+| Snippet replay per invocation                                | ~7.5 µs each          |
 | Per additional idle Sandbox (RSS)                            | ~1 KB                 |
 
-The Cranelift JIT runs once per machine and gem version — the compiled artifact persists in a `.cwasm` disk cache, so later processes deserialize in milliseconds. An idle Sandbox holds no wasm instance (the canonical boot state is baked into the artifact and instantiated per invocation), which is why a thousand idle tenants cost ~33 MB total. Under the default `gvl: :hold`, wasm work is GVL-serialized: aggregate throughput stays around 17k `#eval`/s regardless of Thread count, though Ruby-side `#eval` setup still overlaps. Opting a Sandbox into `gvl: :release` lifts that ceiling for compute-bound scripts (see [Concurrency](#concurrency)). A +10% regression on any SPEC-mandated benchmark blocks release.
+The Cranelift JIT runs once per machine and gem version — the compiled artifact persists in a `.cwasm` disk cache, so later processes deserialize in milliseconds. An idle Sandbox holds no wasm instance (the canonical boot state is baked into the artifact and instantiated per invocation), which is why a thousand idle tenants cost ~33 MB total. Under the default `gvl: :hold`, wasm work is GVL-serialized: aggregate throughput stays around 16k `#eval`/s regardless of Thread count, though Ruby-side `#eval` setup still overlaps. Opting a Sandbox into `gvl: :release` lifts that ceiling for compute-bound scripts (see [Concurrency](#concurrency)). A +10% regression on any SPEC-mandated benchmark blocks release.
 
-Regexp is an opt-in capability gem, excluded from the default binary and the gated set; its throughput is tracked in a separate non-gated characterization (`#11` in [`benchmark/README.md`](benchmark/README.md)). There `=~` (~5 µs/match) costs about 4× `match?` (~1.2 µs), because `=~` eagerly builds the `MatchData` and match globals — prefer `match?` for boolean tests.
+Regexp is an opt-in capability gem, excluded from the default binary and the gated set; its throughput is tracked in a separate non-gated characterization (`#11` in [`benchmark/README.md`](benchmark/README.md)). There `=~` (~5 µs/match) costs about 4.5× `match?` (~1.1 µs), because `=~` eagerly builds the `MatchData` and match globals — prefer `match?` for boolean tests.
 
 ```bash
 bundle exec rake bench  # every gated regression benchmark (~5-8 min)

data/crates/kobako-runtime/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.14.0](https://github.com/elct9620/kobako/compare/kobako-runtime-v0.13.1...kobako-runtime-v0.14.0) (2026-08-06)
+
+
+### Miscellaneous Chores
+
+* **kobako-runtime:** Synchronize kobako crates versions
+
 ## [0.13.1](https://github.com/elct9620/kobako/compare/kobako-runtime-v0.13.0...kobako-runtime-v0.13.1) (2026-07-30)
 
 

data/crates/kobako-runtime/Cargo.toml

@@ -13,7 +13,7 @@
 
 [package]
 name = "kobako-runtime"
-version = "0.13.1"
+version = "0.14.0"
 edition = "2021"
 description = "Engine-neutral host runtime contract for embedding kobako Wasm guests."
 license = "Apache-2.0"
@@ -27,4 +27,4 @@ categories = ["wasm", "virtualization"]
 # in-tree builds (and the Ruby gem, which ships both crates) resolving
 # locally.
 [dependencies]
-kobako-transport = { version = "0.13.1", path = "../kobako-transport" }
+kobako-transport = { version = "0.14.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.13.1" # x-release-please-version
+kobako-runtime = "0.14.0" # x-release-please-version
 ```
 
 ## License

data/crates/kobako-transport/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## [0.14.0](https://github.com/elct9620/kobako/compare/kobako-transport-v0.13.1...kobako-transport-v0.14.0) (2026-08-06)
+
+
+### Features
+
+* **transport:** let a guest block's exception continue as itself ([c8b1de7](https://github.com/elct9620/kobako/commit/c8b1de7154336fab8fa20c0d7a5b3baaad11d551))
+* **transport:** separate a failed exchange from a failed Service ([fb92515](https://github.com/elct9620/kobako/commit/fb92515fc76ffebbb8491b525d53b1725cf97dd0))
+
+
+### Bug Fixes
+
+* **wire:** let a Fault reader survive what it predates ([eeabfb7](https://github.com/elct9620/kobako/commit/eeabfb7aa4de3d08852ca1b41517b924d72a7312))
+
 ## [0.13.1](https://github.com/elct9620/kobako/compare/kobako-transport-v0.13.0...kobako-transport-v0.13.1) (2026-07-30)
 
 

data/crates/kobako-transport/Cargo.toml

@@ -12,7 +12,7 @@
 
 [package]
 name = "kobako-transport"
-version = "0.13.1"
+version = "0.14.0"
 edition = "2021"
 description = "The kobako core envelope — the fixed host↔guest wire frame every assembly shares."
 license = "Apache-2.0"

data/crates/kobako-transport/README.md

@@ -35,7 +35,7 @@ the golden vectors in this crate are derived from that document.
 
 ```toml
 [dependencies]
-kobako-transport = "0.13.1" # x-release-please-version
+kobako-transport = "0.14.0" # x-release-please-version
 ```
 
 ## License

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

@@ -80,6 +80,13 @@ impl<'a> Reader<'a> {
         &self.bytes[self.pos..]
     }
 
+    /// Consume whatever is left without reading it. The extension seam:
+    /// a field a later contract version appends is invisible to a reader
+    /// built before it, and must not read as a framing desync.
+    pub(crate) fn skip_unknown_fields(&mut self) {
+        self.pos = self.bytes.len();
+    }
+
     /// Refuse anything left over. Used by envelopes whose last field is
     /// self-delimiting, where trailing bytes signal a framing desync.
     pub(crate) fn finish(self) -> Result<(), DecodeError> {

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

@@ -3,8 +3,7 @@
 //! A block failure and an invocation failure carry the same three fields,
 //! so the host re-raises from either without consulting a payload codec.
 //! Distinct from a Fault, which travels the other way and is categorized
-//! by one of three reserved type names the guest maps to a proxy-side
-//! error.
+//! by a reserved category name the guest maps to a proxy-side error.
 
 use super::bytes::{Reader, Writer};
 use super::DecodeError;

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

@@ -1,6 +1,6 @@
 //! The host refusing or failing a Call.
 //!
-//! Every byte of a Fault is kobako's — a closed category and a message —
+//! Every byte of a Fault is kobako's — a category and a message —
 //! so it rides the envelope and a guest reads a refusal with no payload
 //! codec at all.
 //!
@@ -15,15 +15,20 @@ use super::DecodeError;
 const KIND_RUNTIME: u8 = 0;
 const KIND_ARGUMENT: u8 = 1;
 const KIND_UNDEFINED: u8 = 2;
+const KIND_INTERNAL: u8 = 3;
+const KIND_BLOCK: u8 = 4;
 
-/// Which of the three failures a Fault reports.
+/// Which failure a Fault reports.
 ///
-/// A tag rather than a name because the set is closed: a category outside
-/// these three is unrepresentable, so no endpoint decides what an unknown
-/// one means. `Undefined` stays indistinguishable across its causes — an
-/// unbound path, an unknown method, a rejected name — so a guest probing
-/// the surface learns nothing from which refusal it got.
+/// The set grows, so a reader that meets a category it does not know
+/// degrades rather than failing the exchange. `Undefined` stays
+/// indistinguishable across its causes — an unbound path, an unknown
+/// method, a rejected name — so a guest probing the surface learns
+/// nothing from which refusal it got, which is also what makes it the
+/// landing place for a category this reader predates: it attributes
+/// nothing to the Service that a newer category might contradict.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
+#[non_exhaustive]
 pub enum FaultKind {
     /// A Ruby exception raised inside the Service method.
     Runtime,
@@ -31,6 +36,18 @@ pub enum FaultKind {
     Argument,
     /// No such member or method.
     Undefined,
+    /// The exchange itself failed, so no Service outcome exists to
+    /// report — the request was unreadable, or the host ran out of the
+    /// resources the exchange needs. Separate from `Runtime` because
+    /// retrying the same call against a working host would behave
+    /// differently, which is not true of a Service that raised.
+    Internal,
+    /// The caller's own block raised while the Service was yielding to
+    /// it, and the Service did not rescue it. The failure is the
+    /// caller's, so it carries no host detail: the caller still holds
+    /// the exception it raised and re-raises that, which is what the
+    /// same code would do without a Sandbox between the two frames.
+    Block,
 }
 
 impl FaultKind {
@@ -39,17 +56,20 @@ impl FaultKind {
             FaultKind::Runtime => KIND_RUNTIME,
             FaultKind::Argument => KIND_ARGUMENT,
             FaultKind::Undefined => KIND_UNDEFINED,
+            FaultKind::Internal => KIND_INTERNAL,
+            FaultKind::Block => KIND_BLOCK,
         }
     }
 
-    fn from_tag(tag: u8) -> Result<Self, DecodeError> {
+    /// Read a category from its tag, degrading one this reader predates
+    /// to the category that claims the least about what failed.
+    fn from_tag(tag: u8) -> Self {
         match tag {
-            KIND_RUNTIME => Ok(FaultKind::Runtime),
-            KIND_ARGUMENT => Ok(FaultKind::Argument),
-            KIND_UNDEFINED => Ok(FaultKind::Undefined),
-            _ => Err(DecodeError::new(
-                "Fault kind must be 0 (runtime), 1 (argument), or 2 (undefined)",
-            )),
+            KIND_RUNTIME => FaultKind::Runtime,
+            KIND_ARGUMENT => FaultKind::Argument,
+            KIND_INTERNAL => FaultKind::Internal,
+            KIND_BLOCK => FaultKind::Block,
+            _ => FaultKind::Undefined,
         }
     }
 
@@ -59,16 +79,20 @@ impl FaultKind {
             FaultKind::Runtime => "runtime",
             FaultKind::Argument => "argument",
             FaultKind::Undefined => "undefined",
+            FaultKind::Internal => "internal",
+            FaultKind::Block => "block",
         }
     }
 
-    /// Read a category from the name a frontend uses, or `None` when the
-    /// name is outside the closed set.
+    /// Read a category from the name a frontend uses, or `None` when this
+    /// build predates the name.
     pub fn from_name(name: &str) -> Option<Self> {
         match name {
             "runtime" => Some(FaultKind::Runtime),
             "argument" => Some(FaultKind::Argument),
             "undefined" => Some(FaultKind::Undefined),
+            "internal" => Some(FaultKind::Internal),
+            "block" => Some(FaultKind::Block),
             _ => None,
         }
     }
@@ -91,8 +115,12 @@ impl Fault {
     }
 
     pub(crate) fn read(reader: &mut Reader<'_>) -> Result<Self, DecodeError> {
-        let kind = FaultKind::from_tag(reader.u8()?)?;
+        let kind = FaultKind::from_tag(reader.u8()?);
         let message = reader.text()?.to_owned();
+        // A Fault gains fields as the contract does, and it is the last
+        // thing a Reply carries, so whatever follows the fields this
+        // reader knows belongs to a later version of them.
+        reader.skip_unknown_fields();
         Ok(Fault { kind, message })
     }
 
@@ -111,6 +139,8 @@ mod tests {
             FaultKind::Runtime,
             FaultKind::Argument,
             FaultKind::Undefined,
+            FaultKind::Internal,
+            FaultKind::Block,
         ] {
             let fault = Fault::new(kind, "boom");
             let mut w = Writer::new();
@@ -126,12 +156,29 @@ mod tests {
     }
 
     #[test]
-    fn a_kind_outside_the_closed_set_is_refused() {
-        let encoded = vec![3, 0, 0, 0, 0];
+    fn a_kind_the_reader_does_not_know_degrades_to_undefined() {
+        let encoded = vec![0xfe, 0, 0, 0, 1, b'x'];
         let mut r = Reader::new(&encoded);
-        assert!(
-            Fault::read(&mut r).is_err(),
-            "a Fault kind byte outside the three the contract fixes must be refused, not carried"
+        assert_eq!(
+            Fault::read(&mut r),
+            Ok(Fault::new(FaultKind::Undefined, "x")),
+            "a Fault category added after this reader was built must deliver its message \
+             under the category that claims the least, not fail the exchange"
+        );
+    }
+
+    #[test]
+    fn a_field_the_reader_does_not_know_is_skipped() {
+        let mut w = Writer::new();
+        Fault::new(FaultKind::Undefined, "no such method").write(&mut w);
+        w.bytes(b"a field a later contract version appended");
+        let encoded = w.into_bytes();
+        let mut r = Reader::new(&encoded);
+        assert_eq!(
+            Fault::read(&mut r),
+            Ok(Fault::new(FaultKind::Undefined, "no such method")),
+            "a Fault field added after this reader was built must be skipped, so the \
+             fields it does know still arrive"
         );
     }
 
@@ -155,6 +202,8 @@ mod tests {
             FaultKind::Runtime,
             FaultKind::Argument,
             FaultKind::Undefined,
+            FaultKind::Internal,
+            FaultKind::Block,
         ] {
             assert_eq!(
                 FaultKind::from_name(kind.name()),
@@ -165,7 +214,7 @@ mod tests {
         assert_eq!(
             FaultKind::from_name("other"),
             None,
-            "a name outside the closed set must not resolve to a kind"
+            "a name this build predates must not resolve to a kind"
         );
     }
 }

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

@@ -32,11 +32,9 @@ impl Reply {
         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))
-            }
+            // No `finish` here: a Fault owns everything after the tag,
+            // including the fields a later contract version appends.
+            TAG_FAULT => Ok(Reply::Fault(Fault::read(&mut reader)?)),
             _ => Err(DecodeError::new("Reply tag must be 0 (ok) or 1 (fault)")),
         }
     }

data/crates/kobako-wasmtime/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.14.0](https://github.com/elct9620/kobako/compare/kobako-wasmtime-v0.13.1...kobako-wasmtime-v0.14.0) (2026-08-06)
+
+
+### Miscellaneous Chores
+
+* **kobako-wasmtime:** Synchronize kobako crates versions
+
 ## [0.13.1](https://github.com/elct9620/kobako/compare/kobako-wasmtime-v0.13.0...kobako-wasmtime-v0.13.1) (2026-07-30)
 
 

data/crates/kobako-wasmtime/Cargo.toml

@@ -15,7 +15,7 @@
 
 [package]
 name = "kobako-wasmtime"
-version = "0.13.1"
+version = "0.14.0"
 edition = "2021"
 description = "wasmtime implementation of the kobako host runtime contract."
 license = "Apache-2.0"
@@ -28,10 +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.13.1", path = "../kobako-runtime" }
+kobako-runtime = { version = "0.14.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.1", path = "../kobako-transport" }
+kobako-transport = { version = "0.14.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.13.1" # x-release-please-version
+kobako-wasmtime = "0.14.0" # x-release-please-version
 ```
 
 ## License

data/ext/kobako/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "kobako"
-version = "0.21.1"
+version = "0.22.0"
 edition = "2021"
 authors = ["Aotokitsuruya <contact@aotoki.me>"]
 license = "Apache-2.0"

data/lib/kobako/codec/encoder.rb

@@ -30,10 +30,24 @@ module Kobako
       # rescue below maps the two violations the guard does not reach onto the
       # same error: an integer outside i64..u64 (+RangeError+) and any
       # packer-internal +NoMethodError+.
+      #
+      # A value that nests without bound — a reference cycle necessarily
+      # does — exhausts the packer's own recursion instead, which Ruby
+      # reports outside +StandardError+. Mapping it keeps an unwritable
+      # value a wire violation the dispatch boundary can answer, rather than
+      # one that escapes every caller's rescue and traps the invocation.
+      #
+      # The refusal is spent once per thread: a thread that has absorbed one
+      # such overflow aborts on the next instead of raising, and a Hash cycle
+      # never reaches Ruby at all — the packer walks a Hash through C frames
+      # that carry no stack guard. Bounding the walk before the packer is
+      # handed the value is what would make the refusal repeatable.
       def self.encode(value)
         FACTORY.dump(value)
       rescue ::RangeError, ::NoMethodError => e
         raise UnsupportedTypeError, e.message
+      rescue ::SystemStackError
+        raise InvalidTypeError, "value nests deeper than this host can write (a reference cycle necessarily does)"
       end
     end
   end

data/lib/kobako/codec/error.rb

@@ -18,7 +18,8 @@ module Kobako
     class TruncatedInputError < Error; end
 
     # The type byte at the current position is not in the 11-entry kobako
-    # type mapping (e.g. an unknown ext code, or a reserved msgpack tag).
+    # type mapping (e.g. an unknown ext code, or a reserved msgpack tag) —
+    # or, on encode, a value nesting past what the packer can walk.
     class InvalidTypeError < Error; end
 
     # A msgpack +str+ payload was not valid UTF-8, or an ext 0x00 Symbol

data/lib/kobako/errors.rb

@@ -116,12 +116,45 @@ module Kobako
 
   # Service layer. Raised when a Service capability call inside a mruby
   # script reported an application-level failure that the script did not
-  # rescue.
+  # rescue. The base class covers a Service that ran and raised; the two
+  # subclasses below cover the calls that never reached one, so a Host App
+  # routes them apart with +rescue+ instead of by reading the message.
   class ServiceError < Error
     include Diagnosable
     include CarriesExecution
   end
 
+  # The ServiceError subclass raised when the call reached no Service
+  # method: the bound path holds nothing, the Capability Handle is not
+  # live in this invocation, or the method is absent or outside the guest
+  # surface. The causes stay indistinguishable — an opaque target must
+  # disclose nothing about which methods it defines — so what a Host App
+  # learns is that this call will not succeed by being retried.
+  class NoServiceError < ServiceError; end
+
+  # The ServiceError subclass raised when the call reached the Service
+  # method but its arguments did not fit — an unknown keyword, or an
+  # arity mismatch.
+  class ServiceArgumentError < ServiceError; end
+
+  # Raised at a Service method's +yield+ site when the guest block it
+  # yielded to raised. A Service rescues it the way it would rescue a
+  # block's exception without a Sandbox between the two frames; leaving it
+  # unrescued returns it to the guest, which re-raises the exception it
+  # raised in the first place. It therefore never reaches the Host App as
+  # an invocation outcome and carries no Execution. +klass+ names the
+  # guest-side class, which has no host counterpart to rebuild.
+  class BlockError < Error
+    include Diagnosable
+  end
+
+  # Raised at a Service method's +yield+ site when a yield argument has no
+  # wire representation, so the round-trip never left the host and the
+  # block never ran. As BlockError, a Service rescues it at that site and
+  # may go on, so it never reaches the Host App as an invocation outcome;
+  # unrescued, the dispatch answers as that Service having failed.
+  class YieldValueError < Error; end
+
   # HandleExhaustedError is the canonical SandboxError subclass for the
   # id-cap-hit path. Raised when the per-invocation Handle ID counter in
   # Catalog::Handles reaches +0x7fff_ffff+ (2³¹ − 1) and further

data/lib/kobako/outcome.rb

@@ -17,12 +17,16 @@ module Kobako
     ORIGIN_SANDBOX = "sandbox"
     ORIGIN_SERVICE = "service"
 
-    # The guest-written class names that select a +SandboxError+ subclass.
-    # A name absent here settles as plain +SandboxError+, so the guest
-    # widens the taxonomy only by naming a class the host already defines.
+    # The guest-written class names that narrow the class a Panic settles
+    # as. A name absent here settles as the base class its origin already
+    # chose, so the guest widens the taxonomy only by naming a class the
+    # host already defines.
     SUBCLASSES = {
       "Kobako::BytecodeError" => BytecodeError,
-      "Kobako::UndefinedEntrypointError" => UndefinedEntrypointError
+      "Kobako::UndefinedEntrypointError" => UndefinedEntrypointError,
+      "Kobako::Transport::Error" => Kobako::Transport::Error,
+      "Kobako::NoServiceError" => NoServiceError,
+      "Kobako::ServiceArgumentError" => ServiceArgumentError
     }.freeze
 
     module_function
@@ -52,13 +56,17 @@ module Kobako
       UndefinedEntrypointError.new(message, name: entrypoint, available: available.map(&:to_sym), **attribution)
     end
 
-    # +origin == "service"+ selects ServiceError; a sandbox-origin failure
-    # naming one of the guest-written subclass names selects that subclass
-    # so callers can rescue that path specifically.
+    # +origin+ picks the branch, and the guest-written class name may
+    # narrow within it so callers can rescue one path specifically. A name
+    # naming a class outside the branch its origin chose is ignored rather
+    # than honoured: what a guest calls its exception must not move the
+    # failure to a layer the attribution did not put it in.
     def error_class(origin, klass)
-      return ServiceError if origin == ORIGIN_SERVICE
+      base = origin == ORIGIN_SERVICE ? ServiceError : SandboxError
+      selected = SUBCLASSES.fetch(klass, base)
+      return base unless selected <= base
 
-      SUBCLASSES.fetch(klass, SandboxError)
+      selected
     end
 
     # An arm the host cannot settle: the guest wrote nothing, or wrote

data/lib/kobako/transport/dispatcher.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "../codec"
+require_relative "../errors"
 require_relative "../payload"
 require_relative "call"
 require_relative "reflection"
@@ -36,6 +37,29 @@ module Kobako
       # not part of the public Kobako error taxonomy.
       class UndefinedTargetError < StandardError; end
 
+      # The codec fault of a request that never became a call, restated in
+      # the vocabulary the guest can act on while staying inside the codec
+      # taxonomy the fault boundary sorts on.
+      class UnreadableRequestError < Kobako::Codec::Error; end
+
+      # The category kobako's own refusals answer under, keyed by the class
+      # each is raised as and ordered most specific first. A class absent
+      # here is the Service's own exception, which answers under +runtime+
+      # wearing the +<class>: <message>+ shape that says so.
+      #
+      # +Kobako::Codec::Error+ is the floor rather than a path of its own:
+      # a codec fault reaching the boundary unnamed is the exchange failing,
+      # and must not be dressed as something a Service raised.
+      OWN_FAULTS = {
+        HandleExhaustedError => "internal",
+        UndefinedTargetError => "undefined",
+        ArgumentError => "argument",
+        YieldValueError => "runtime",
+        Kobako::Codec::Error => "internal",
+        Kobako::SandboxError => "runtime"
+      }.freeze
+      private_constant :OWN_FAULTS
+
       # Answer a single routed Call with +[ok, bytes]+, which the native
       # side puts on the Reply's ok or fault arm. Invoked from the
       # per-invocation dispatch Proc that
@@ -61,7 +85,7 @@ module Kobako
       # stays uncaught and traps the invocation rather than being masked as a
       # rescuable fault.
       rescue StandardError => e
-        [false, *caught_fault(e)] # : [bool, String, String?]
+        [false, *caught_fault(e, yielder)] # : [bool, String, String?]
       ensure
         yielder&.invalidate!
       end
@@ -70,12 +94,23 @@ module Kobako
       # the +catch+ frame a guest +break+ unwinds to. Split from #dispatch
       # so the reply-shaping and the failure boundary stay one glance wide.
       def run(call, resolver, handler, yielder)
-        arguments, carried_handle = Kobako::Codec.track_handles { Payload::Arguments.decode(call.payload) }
+        arguments, carried_handle = decode_arguments(call.payload)
         receiver = resolve_target(call.target, resolver, handler)
         args, kwargs = resolve_call_args(arguments, handler, carried_handle)
         catch(BREAK_THROW) { invoke(receiver, call.method_name, args, kwargs, yielder) }
       end
 
+      # Decode the Call's payload into its arguments, reporting whether any
+      # Capability Handle crossed. A codec fault here is a request that
+      # never became a call, restated so it cannot read as an unwritable
+      # reply — the same restatement #encode_ok makes in the other
+      # direction.
+      def decode_arguments(payload)
+        Kobako::Codec.track_handles { Payload::Arguments.decode(payload) }
+      rescue Kobako::Codec::Error => e
+        raise UnreadableRequestError, "Sandbox could not read the request: #{e.message}"
+      end
+
       # Resolve positional and keyword arguments off the decoded payload in
       # one step. +carried_handle+ reports whether the decode carried any
       # Capability Handle; when it did not, every argument resolves to
@@ -95,14 +130,24 @@ module Kobako
       # is the +StandardError+ caught by #dispatch's rescue; the category
       # tells the guest which kind of failure it was so it can raise the
       # matching proxy-side error.
-      def caught_fault(error)
-        case error
-        when Kobako::Codec::Error then fault("runtime",
-                                             "Sandbox received a malformed request: #{error.message}")
-        when UndefinedTargetError then fault("undefined", error.message)
-        when ArgumentError        then fault("argument", error.message)
-        else                           fault("runtime", "#{error.class}: #{error.message}")
-        end
+      #
+      # The class prefix marks a Service's own exception and nothing else:
+      # it is the +<class>: <message>+ shape a Host App is told to keep
+      # secrets out of, so wearing it says the Service raised. kobako's own
+      # refusals answer under their own wording instead of borrowing that
+      # shape.
+      #
+      # The guest's own block failing is not the Service's to report at
+      # all, so the Yielder that raised it is asked first — it recognises
+      # its own by identity and words the failure the guest's way.
+      def caught_fault(error, yielder)
+        block_failure = yielder&.fault_text(error)
+        return fault("block", block_failure) if block_failure
+
+        own = OWN_FAULTS.find { |klass, _| error.is_a?(klass) }
+        return fault(own.last, error.message) if own
+
+        fault("runtime", "#{error.class}: #{error.message}")
       end
 
       # Dispatch +method+ on +target+. +kwargs+ is already Symbol-keyed
@@ -182,10 +227,18 @@ module Kobako
       # +UnsupportedTypeError+; the rescue routes it through the
       # Catalog::Handles via #wrap_as_handle and re-encodes with the
       # Capability Handle in place. The happy path encodes exactly once.
+      #
+      # Any other codec fault is the answer failing to encode rather than the
+      # request failing to decode, and a Service is the only side that can
+      # change what it returns — so it is named here, where the direction is
+      # known, instead of falling to the boundary's codec floor and reporting
+      # as an exchange that produced no Service outcome.
       def encode_ok(value, handler)
         Kobako::Codec::Encoder.encode(value)
       rescue Kobako::Codec::UnsupportedTypeError
         encode_ok(wrap_as_handle(value, handler), handler)
+      rescue Kobako::Codec::Error => e
+        raise Kobako::SandboxError, "Sandbox could not write the Service's answer: #{e.message}"
       end
 
       # Allocate +value+ in the Sandbox's Catalog::Handles and return a +Handle+

data/lib/kobako/transport/yielder.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "../codec"
+require_relative "../errors"
 
 module Kobako
   # See lib/kobako/transport.rb for the umbrella module doc; this file
@@ -20,8 +21,8 @@ module Kobako
     #   * ok    — return the decoded value to +yield+'s caller
     #   * break — +throw break_tag, value+ so the Dispatcher's +catch+
     #     frame unwinds the Service method
-    #   * error — raise the guest's class and message at the Service's
-    #     yield site
+    #   * error — raise a BlockError at the Service's yield site,
+    #     carrying the guest's class on +#klass+
     #
     # The Dispatcher calls #invalidate! from its +ensure+ block once
     # dispatch completes; any later call to a stashed Yielder then raises
@@ -40,6 +41,23 @@ module Kobako
         @break_tag = break_tag
         @handler = handler
         @active = true
+        @raised = nil
+      end
+
+      # The text the guest's own block failure crosses back as, or +nil+
+      # when +error+ is not the BlockError this Yielder raised. Identity
+      # rather than class: a Service that rescued the block's failure and
+      # raised its own has reported something else, and the guest must
+      # hear about that instead.
+      #
+      # The class travels with the message because not every block failure
+      # is an exception the guest holds — a block value the guest refused
+      # has a class to raise under and no object to continue.
+      def fault_text(error)
+        raised = @raised
+        return if raised.nil? || !error.equal?(raised)
+
+        "#{raised.klass}: #{raised.message}"
       end
 
       # Re-enter the guest with +args+ and reify the Yield Reply into
@@ -52,8 +70,8 @@ module Kobako
       def yield(*args)
         raise LocalJumpError, "guest block invoked after host dispatch frame returned" unless @active
 
-        arm, body, klass = @yield_to_guest.call(Kobako::Codec::Encoder.encode(args))
-        raise "#{klass}: #{body}" if arm == :error
+        arm, body, klass = @yield_to_guest.call(encode_args(args))
+        raise remember(BlockError.new(body, klass: klass)) if arm == :error
 
         value, carried_handle = decode_body(body)
         throw @break_tag, value if arm == :break
@@ -76,6 +94,24 @@ module Kobako
 
       private
 
+      # Encode what the Service is yielding. A value outside the wire type
+      # set fails here, before the guest is re-entered, and is restated so
+      # the Service reads a refusal of its own argument rather than a codec
+      # class it never named.
+      def encode_args(args)
+        Kobako::Codec::Encoder.encode(args)
+      rescue Kobako::Codec::Error => e
+        raise YieldValueError, "Service yielded a value the block cannot receive: #{e.message}"
+      end
+
+      # Hold onto the BlockError being raised so #fault_text can recognise
+      # it if it comes back unrescued, and return it so the raise site reads
+      # as one statement. Only the newest is kept: a Service that rescued
+      # an earlier one and yielded again has already handled it.
+      def remember(error)
+        @raised = error
+      end
+
       # Decode a value-carrying arm's payload, answering the value and
       # whether the decode carried a Capability Handle. The tracking
       # bracket opens only around this decode: the guest re-entry may run

data/lib/kobako/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Kobako
-  VERSION = "0.21.1"
+  VERSION = "0.22.0"
 end

data/sig/kobako/errors.rbs

@@ -47,6 +47,19 @@ module Kobako
     include CarriesExecution
   end
 
+  class NoServiceError < ServiceError
+  end
+
+  class ServiceArgumentError < ServiceError
+  end
+
+  class BlockError < Error
+    include Diagnosable
+  end
+
+  class YieldValueError < Error
+  end
+
   class HandleExhaustedError < SandboxError
   end
 

data/sig/kobako/outcome.rbs

@@ -2,7 +2,7 @@ module Kobako
   module Outcome
     ORIGIN_SANDBOX: String
     ORIGIN_SERVICE: String
-    SUBCLASSES: Hash[String, singleton(SandboxError)]
+    SUBCLASSES: Hash[String, (singleton(SandboxError) | singleton(ServiceError))]
 
     type panic_fields = [String, String, String, Array[String], Array[String]]
 

data/sig/kobako/transport/dispatcher.rbs

@@ -4,8 +4,13 @@ module Kobako
       class UndefinedTargetError < StandardError
       end
 
+      class UnreadableRequestError < Kobako::Codec::Error
+      end
+
       BREAK_THROW: Symbol
 
+      OWN_FAULTS: Hash[singleton(StandardError), String]
+
 
 
 
@@ -15,7 +20,9 @@ module Kobako
 
       def self?.resolve_call_args: (Kobako::Payload::Arguments arguments, Kobako::Codec::_HandleTable handler, bool carried_handle) -> [Array[untyped], Hash[Symbol, untyped]]
 
-      def self?.caught_fault: (StandardError error) -> [String, String]
+      def self?.decode_arguments: (String payload) -> [Kobako::Payload::Arguments, bool]
+
+      def self?.caught_fault: (StandardError error, Kobako::Transport::Yielder? yielder) -> [String, String]
 
       def self?.invoke: (untyped target, String method, Array[untyped] args, Hash[Symbol, untyped] kwargs, ?Kobako::Transport::Yielder? yielder) -> untyped
 

data/sig/kobako/transport/yielder.rbs

@@ -5,9 +5,12 @@ module Kobako
       @break_tag: Symbol
       @handler: Kobako::Codec::_HandleTable
       @active: bool
+      @raised: Kobako::BlockError?
 
       def initialize: (Kobako::Transport::_GuestYielder yield_to_guest, Symbol break_tag, Kobako::Codec::_HandleTable handler) -> void
 
+      def fault_text: (Exception error) -> String?
+
       def yield: (*untyped args) -> untyped
 
       def to_proc: () -> Proc
@@ -16,6 +19,10 @@ module Kobako
 
       private
 
+      def encode_args: (Array[untyped] args) -> String
+
+      def remember: (Kobako::BlockError error) -> Kobako::BlockError
+
       def decode_body: (String body) -> [untyped, bool]
 
       def restore: (untyped value, bool carried_handle) -> untyped

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kobako
 version: !ruby/object:Gem::Version
-  version: 0.21.1
+  version: 0.22.0
 platform: ruby
 authors:
 - Aotokitsuruya