kobako 0.21.0 → 0.22.0

data/README.md

@@ -77,7 +77,7 @@ The host embeds the sandbox and owns the SPEC wire codec. Choose by your host la
 | Rust SDK | `kobako` (crates.io) | `kobako = "0.12"` | A Rust host — the same behavior contract behind an idiomatic Rust API |
 | Low-level crates | `kobako-wasmtime` + `kobako-runtime` + `kobako-transport` + `kobako-codec` | Cargo deps | A custom host, or driving the wire directly in another language |
 
-The Rust crates are documented on [crates.io](https://crates.io/crates/kobako); the Ruby gem is this README. Two runnable Rust hosts show the choice: [`plugin-rs`](examples/plugin-rs) builds on the SDK, and [`wire-rs`](examples/wire-rs) assembles a host by hand on the low-level crates.
+The Rust crates are documented on [crates.io](https://crates.io/crates/kobako); the Ruby gem is this README. Three runnable Rust hosts show the choice: [`plugin-rs`](examples/plugin-rs) builds on the SDK, [`wire-rs`](examples/wire-rs) assembles a host by hand on the low-level crates, and [`fixed-schema-rs`](examples/fixed-schema-rs) replaces what both of those keep — the payload schema — with a guest and a host that agree on protobuf.
 
 ### Pre-built Guest Binaries
 
@@ -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,19 @@
 # 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)
+
+
+### Miscellaneous Chores
+
+* **kobako-runtime:** Synchronize kobako crates versions
+
 ## [0.13.0](https://github.com/elct9620/kobako/compare/kobako-runtime-v0.12.0...kobako-runtime-v0.13.0) (2026-07-29)
 
 

data/crates/kobako-runtime/Cargo.toml

@@ -13,7 +13,7 @@
 
 [package]
 name = "kobako-runtime"
-version = "0.13.0"
+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.0", 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.0" # x-release-please-version
+kobako-runtime = "0.14.0" # x-release-please-version
 ```
 
 ## License

data/crates/kobako-transport/CHANGELOG.md

@@ -1,5 +1,25 @@
 # 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)
+
+
+### Miscellaneous Chores
+
+* **kobako-transport:** Synchronize kobako crates versions
+
 ## [0.13.0](https://github.com/elct9620/kobako/compare/kobako-transport-v0.12.0...kobako-transport-v0.13.0) (2026-07-29)
 
 

data/crates/kobako-transport/Cargo.toml

@@ -12,7 +12,7 @@
 
 [package]
 name = "kobako-transport"
-version = "0.13.0"
+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.0" # 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,24 @@
 # 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)
+
+
+### Bug Fixes
+
+* **host:** keep nothing in the ABI probe's capture pipes ([a3d6c1c](https://github.com/elct9620/kobako/commit/a3d6c1c8edb9964a7d8ab162b2e379b39dbbddb9))
+
+
+### Performance Improvements
+
+* **host:** ask an artifact its ABI version once, not once per Sandbox ([693b94f](https://github.com/elct9620/kobako/commit/693b94f878e56815fe3faeae94e5c4d0cd9c8bb6))
+
 ## [0.13.0](https://github.com/elct9620/kobako/compare/kobako-wasmtime-v0.12.0...kobako-wasmtime-v0.13.0) (2026-07-29)
 
 

data/crates/kobako-wasmtime/Cargo.toml

@@ -15,7 +15,7 @@
 
 [package]
 name = "kobako-wasmtime"
-version = "0.13.0"
+version = "0.14.0"
 edition = "2021"
 description = "wasmtime implementation of the kobako host runtime contract."
 license = "Apache-2.0"
@@ -28,17 +28,17 @@ 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.0", 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.0", 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`
 # feature so test fixtures can be expressed as text.
 # `cache` / `parallel-compilation` / `pooling` / `component-model` / `async`
 # are intentionally off — kobako runs short-lived synchronous sandboxes.
-wasmtime = { version = "46.0.1", default-features = false, features = [
+wasmtime = { version = "47.0.2", default-features = false, features = [
     "cranelift",
     "runtime",
     "gc",
@@ -52,7 +52,7 @@ wasmtime = { version = "46.0.1", default-features = false, features = [
 # WasiCtxBuilder + preview1 adapter which wires fd 1/2 to pipes. We omit
 # `p2` (component-model) and `p0`/`p3` (async) because kobako runs
 # synchronous sandboxes only.
-wasmtime-wasi = { version = "46.0.1", default-features = false, features = ["p1"] }
+wasmtime-wasi = { version = "47.0.2", default-features = false, features = ["p1"] }
 # sha2 keys the on-disk compiled-module cache by Guest Binary content
 # (see cache.rs); a collision would load the wrong artifact, so the
 # hash must be cryptographic.

data/crates/kobako-wasmtime/README.md

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

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

@@ -0,0 +1,70 @@
+//! The Guest Binary's declared ABI version check.
+//!
+//! An artifact reports one ABI version, so the answer belongs to the
+//! module and not to the sandbox asking for it. The check therefore runs
+//! alongside the `InstancePre` it guards (`crate::instance_pre`) and is
+//! amortised with it, rather than once per `Driver::new`.
+
+use wasmtime::{AsContextMut, InstancePre, Store as WtStore};
+
+use crate::cache::shared_engine;
+use crate::config::Config;
+use crate::invocation::Invocation;
+use crate::{frames, trap};
+use kobako_runtime::error::SetupError;
+use kobako_runtime::profile::Profile;
+use kobako_transport::abi::ABI_VERSION;
+
+/// Caps for the throwaway probe instance. Instantiation runs the
+/// artifact's start section, so the capture pipes are sized to keep
+/// nothing — the probe reads neither — and the strongest isolation rung
+/// is taken, since reading an artifact's version grants no ambient
+/// authority. The timeout and memory caps stay off because both arm per
+/// invocation and there is none here.
+const PROBE_CONFIG: Config = Config {
+    timeout: None,
+    memory_limit: None,
+    stdout_limit: Some(0),
+    stderr_limit: Some(0),
+    profile: Profile::Hermetic,
+};
+
+/// Instantiate a throwaway probe instance from `pre` and require the
+/// guest's `__kobako_abi_version` export to equal `ABI_VERSION`. An
+/// absent export or a non-equal value is a deterministic artifact
+/// fault, so every failure is a `SetupError` for the frontend to
+/// attribute. The frameless WASI context keeps a third-party guest
+/// whose start section touches WASI on the `SetupError` path instead of
+/// panicking in `Invocation::wasi_mut`.
+pub(crate) fn verify(pre: &InstancePre<Invocation>) -> Result<(), SetupError> {
+    let mut store = WtStore::new(shared_engine()?, Invocation::new(None));
+    // Epoch interruption is on engine-wide and a fresh Store's deadline
+    // has already elapsed, so the probe must name one it cannot reach.
+    store.set_epoch_deadline(trap::NO_TIMEOUT_EPOCH_DELTA);
+    frames::install_wasi_frames(&mut store, &PROBE_CONFIG, &[])
+        .map_err(|t| SetupError::Dead(t.to_string()))?;
+    let instance = pre
+        .instantiate(store.as_context_mut())
+        .map_err(trap::instantiate_err)?;
+    let probe = instance
+        .get_typed_func::<(), u32>(store.as_context_mut(), "__kobako_abi_version")
+        .map_err(|_| {
+            SetupError::Dead(format!(
+                "the Guest Binary does not export __kobako_abi_version; \
+                 rebuild it against ABI version {ABI_VERSION}"
+            ))
+        })?;
+    let reported = probe.call(store.as_context_mut(), ()).map_err(|e| {
+        SetupError::Dead(format!(
+            "failed to read the Guest Binary's ABI version: {e}"
+        ))
+    })?;
+    if reported != ABI_VERSION {
+        return Err(SetupError::Dead(format!(
+            "the Guest Binary reports ABI version {reported}, but this host \
+             implements ABI version {ABI_VERSION}; rebuild the Guest Binary \
+             against the host's version"
+        )));
+    }
+    Ok(())
+}

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

@@ -26,14 +26,13 @@ use kobako_runtime::profile::Profile;
 use kobako_runtime::runtime::{Entry, Frames, Runtime as ContractRuntime};
 use kobako_runtime::snapshot::{Capture, Completion, Snapshot, Usage};
 
-use kobako_transport::abi::ABI_VERSION;
-
 /// The wasmtime execution unit behind one sandbox runtime.
 pub struct Driver {
-    // Pre-linked instantiation template (import wiring + type checks
-    // done once in `instance_pre::cached_instance_pre`). Every
-    // invocation instantiates a fresh instance from it and discards the
-    // whole Store afterwards — the per-invocation instance discipline.
+    // Pre-linked instantiation template (import wiring, type checks,
+    // and the ABI version check done once in
+    // `instance_pre::cached_instance_pre`). Every invocation
+    // instantiates a fresh instance from it and discards the whole
+    // Store afterwards — the per-invocation instance discipline.
     instance_pre: WtInstancePre<Invocation>,
     // Every cap forwarded from the Sandbox; see `Config`.
     config: Config,
@@ -41,56 +40,15 @@ 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, and verify
-    /// the artifact's ABI version. Every failure is a `SetupError` for
-    /// the frontend to attribute — Engine and Module never leave the
-    /// driver.
+    /// 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.
     pub fn new(path: &Path, config: Config) -> Result<Self, SetupError> {
-        let instance_pre = instance_pre::cached_instance_pre(path)?;
-        let driver = Self {
-            instance_pre,
+        Ok(Self {
+            instance_pre: instance_pre::cached_instance_pre(path)?,
             config,
-        };
-        driver.probe_abi_version()?;
-        Ok(driver)
-    }
-
-    /// Instantiate a throwaway probe instance at construction and require
-    /// the guest's `__kobako_abi_version` export to equal `ABI_VERSION`.
-    /// An absent export or a non-equal value is a deterministic artifact
-    /// fault. The probe Store drops here; invocation instances are
-    /// created per invoke. The frameless WASI context keeps a third-party
-    /// guest whose start section touches WASI on the `SetupError` path
-    /// instead of panicking in `Invocation::wasi_mut`.
-    fn probe_abi_version(&self) -> Result<(), SetupError> {
-        let mut store = self.new_store()?;
-        frames::install_wasi_frames(&mut store, &self.config, &[])
-            .map_err(|t| SetupError::Dead(t.to_string()))?;
-        let instance = self
-            .instance_pre
-            .instantiate(store.as_context_mut())
-            .map_err(trap::instantiate_err)?;
-        let probe = instance
-            .get_typed_func::<(), u32>(store.as_context_mut(), "__kobako_abi_version")
-            .map_err(|_| {
-                SetupError::Dead(format!(
-                    "the Guest Binary does not export __kobako_abi_version; \
-                     rebuild it against ABI version {ABI_VERSION}"
-                ))
-            })?;
-        let reported = probe.call(store.as_context_mut(), ()).map_err(|e| {
-            SetupError::Dead(format!(
-                "failed to read the Guest Binary's ABI version: {e}"
-            ))
-        })?;
-        if reported != ABI_VERSION {
-            return Err(SetupError::Dead(format!(
-                "the Guest Binary reports ABI version {reported}, but this host \
-                 implements ABI version {ABI_VERSION}; rebuild the Guest Binary \
-                 against the host's version"
-            )));
-        }
-        Ok(())
+        })
     }
 
     /// Build the per-invocation Store: a fresh `Invocation` wired with

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

@@ -5,8 +5,9 @@
 //! compiled Module are identical for every `Kobako::Runtime` on the
 //! same Guest Binary — both host closures read all their state from
 //! the `Invocation` inside the calling Store, never from the Runtime.
-//! Caching the resolved `InstancePre` per path leaves only the
-//! `instantiate` call itself on the `Driver::new` hot path.
+//! Caching the resolved `InstancePre` per path — together with the ABI
+//! version check it guards (`crate::abi`) — takes both off the
+//! `Driver::new` hot path.
 //!
 //! Concurrency: see `crate::cache` — under Ruby's GVL the Mutex serves
 //! `Sync` bounds rather than real contention.
@@ -20,16 +21,17 @@ use wasmtime_wasi::p1;
 
 use crate::cache::{cached_module, shared_engine};
 use crate::invocation::Invocation;
-use crate::{dispatch, trap};
+use crate::{abi, dispatch, trap};
 use kobako_runtime::error::SetupError;
 
 static INSTANCE_PRE_CACHE: OnceLock<Mutex<HashMap<PathBuf, InstancePre<Invocation>>>> =
     OnceLock::new();
 
 /// Look up `path` in the per-path `InstancePre` cache, wiring the
-/// Linker and resolving the Module's imports on a miss. Compilation
-/// faults surface through `cached_module`; import-resolution faults
-/// return a runtime-dead `SetupError` (boundary → `Kobako::SetupError`).
+/// Linker, resolving the Module's imports, and verifying the artifact's
+/// ABI version on a miss. Compilation faults surface through
+/// `cached_module`; import-resolution and ABI faults return a
+/// runtime-dead `SetupError` (boundary → `Kobako::SetupError`).
 pub(crate) fn cached_instance_pre(path: &Path) -> Result<InstancePre<Invocation>, SetupError> {
     let cache = INSTANCE_PRE_CACHE.get_or_init(|| Mutex::new(HashMap::new()));
 
@@ -47,6 +49,9 @@ pub(crate) fn cached_instance_pre(path: &Path) -> Result<InstancePre<Invocation>
     let pre = linker
         .instantiate_pre(&module)
         .map_err(trap::instantiate_err)?;
+    // Verify before the insert, so a rejected artifact is never
+    // remembered as a usable template.
+    abi::verify(&pre)?;
     cache
         .lock()
         .expect("instance_pre cache mutex poisoned")