kobako 0.12.2 → 0.14.0

data/README.md

@@ -154,6 +154,8 @@ sandbox = Kobako::Sandbox.new(
 
 `memory_limit` covers the per-invocation `memory.grow` delta from the entry baseline, so a Sandbox reused across invocations does not silently accumulate against a global budget.
 
+A fifth option, `profile:`, requests the Sandbox's isolation posture on the `:permissive` < `:hermetic` ladder (default `:hermetic`). `:hermetic` denies the guest ambient time and entropy; `:permissive` lets the guest's `wasi:clocks` / `wasi:random` read live host sources — an explicit trade of reproducibility, with filesystem, environment, and network still unreachable. The request is also a floor: construction fails with `Kobako::SetupError` on a runtime that declares a weaker posture than requested. See [`docs/security-model.md`](docs/security-model.md) § Isolation profiles.
+
 ### Invocation Lifecycle
 
 One Sandbox serves many invocations. Service bindings and preloaded snippets persist across calls; capability state (Handles, stdout, stderr, memory delta) resets between them.
@@ -300,10 +302,10 @@ sandbox.run(:Greeter, name: "world") # => "hello, world"
 
 | Form     | Signature                            | Snippet name source                   | Validation timing                                                          |
 |----------|--------------------------------------|---------------------------------------|----------------------------------------------------------------------------|
-| Source   | `preload(code: "...", name: :Const)` | The `name:` keyword                   | Trial-compiled at preload; compile errors raise immediately                |
-| Bytecode | `preload(binary: bytes)`             | Read from the bytecode's `debug_info` | Deferred to first invocation; failure raises `Kobako::BytecodeError`       |
+| Source   | `preload(code: "...", name: :Const)` | The `name:` keyword                   | First invocation's replay; compile errors raise `Kobako::SandboxError`     |
+| Bytecode | `preload(binary: bytes)`             | Read from the bytecode's `debug_info` | First invocation's replay; structural failure raises `Kobako::BytecodeError` |
 
-Use the source form for snippets authored in your repo (compile errors fail fast at `#preload`); use the bytecode form when snippets ship as build artifacts from a separate `mrbc` pipeline. Both replay through the same per-invocation path.
+Use the source form for snippets authored in your repo; use the bytecode form when snippets ship as build artifacts from a separate `mrbc` pipeline. Both replay through the same per-invocation path, so no snippet content failure surfaces at `#preload` — force the first replay with a no-op invocation (e.g. `sandbox.eval("nil")`) when you want validation before real traffic.
 
 ## Security
 

data/ROADMAP.md

@@ -0,0 +1,26 @@
+# Roadmap
+
+kobako is a Ruby gem providing an in-process Wasm sandbox for untrusted mruby
+code: a wasmtime host runs a precompiled `kobako.wasm` guest, with host↔guest
+Transport over a MessagePack wire. Features cover one-shot `#eval`, preload +
+`#run` dispatch, Service injection through Namespaces / Members, opaque
+Capability Handles, block yield re-entry, three-class error attribution,
+output capture, and a warm Sandbox pool.
+
+| Feature | Entry Points | Notes |
+|---------|-------------|-------|
+| ✅ [F-01 Sandbox instantiation](docs/behavior/lifecycle.md) | [lib/kobako/sandbox.rb](lib/kobako/sandbox.rb) | B-22 (per-Thread isolation) is exercised only indirectly through the pool contention tests; no test cites it |
+| ✅ [F-02 Namespace declaration](docs/behavior/registration.md) | [lib/kobako/catalog/namespaces.rb](lib/kobako/catalog/namespaces.rb) | — |
+| ✅ [F-03 Member binding](docs/behavior/registration.md) | [lib/kobako/namespace.rb](lib/kobako/namespace.rb) | — |
+| ✅ [F-04 Synchronous mruby source execution (`#eval`)](docs/behavior/lifecycle.md) | [lib/kobako/sandbox.rb](lib/kobako/sandbox.rb) | — |
+| ✅ [F-05 Guest-initiated Transport dispatch](docs/behavior/dispatch.md) | [lib/kobako/transport/dispatcher.rb](lib/kobako/transport/dispatcher.rb) | — |
+| ✅ [F-06 Capability Handle encoding and referencing](docs/behavior/dispatch.md) | [lib/kobako/catalog/handles.rb](lib/kobako/catalog/handles.rb) | — |
+| ✅ [F-07 Three-class error attribution and raising](docs/behavior/errors.md) | [lib/kobako/outcome.rb](lib/kobako/outcome.rb) | E-26 (guest-entry envelope decode failure) has no exercising test — not reachable through the public API |
+| ✅ [F-08 Guest output capture](docs/behavior/lifecycle.md) | [lib/kobako/capture.rb](lib/kobako/capture.rb) | — |
+| ✅ [F-09 Host–guest message codec](docs/wire-codec.md) | [lib/kobako/codec/](lib/kobako/codec/) | — |
+| ✅ [F-10 Reproducible build pipeline](SPEC.md#code-organization) | [tasks/wasm/build.rake](tasks/wasm/build.rake) | Verified by build-time gates (`rake anchors`, double-bake byte-identity, gemspec whitelist), not `test/` |
+| ✅ [F-11 Multi-layer test and benchmark suite](SPEC.md#testing-style) | [test/](test/) | Benchmarks live in [benchmark/](benchmark/) with the gate in `tasks/bench/`; the anchor baseline advances only by deliberate re-bless |
+| ✅ [F-12 Guest block reception and yield re-entry](docs/behavior/yield.md) | [lib/kobako/transport/yielder.rb](lib/kobako/transport/yielder.rb) | — |
+| ✅ [F-13 Snippet preloading (`#preload`)](docs/behavior/invocation.md) | [lib/kobako/catalog/snippets.rb](lib/kobako/catalog/snippets.rb) | — |
+| ✅ [F-14 Synchronous entrypoint dispatch (`#run`)](docs/behavior/invocation.md) | [lib/kobako/sandbox.rb](lib/kobako/sandbox.rb) | — |
+| ✅ [F-15 Warm Sandbox pool checkout (`Kobako::Pool`)](docs/behavior/runtime.md) | [lib/kobako/pool.rb](lib/kobako/pool.rb) | — |

data/crates/kobako-runtime/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## [0.8.0](https://github.com/elct9620/kobako/compare/kobako-runtime-v0.7.0...kobako-runtime-v0.8.0) (2026-07-08)
+
+
+### Bug Fixes
+
+* **crates:** give SetupError a Display so Error::Setup reads cleanly ([bc8b128](https://github.com/elct9620/kobako/commit/bc8b128c9e296319c7fef47441b412d2ce345dff))
+
+## [0.7.0](https://github.com/elct9620/kobako/compare/kobako-runtime-v0.6.1...kobako-runtime-v0.7.0) (2026-07-03)
+
+
+### Features
+
+* **crates:** build the requested isolation profile into the WASI context ([63c25d8](https://github.com/elct9620/kobako/commit/63c25d835d4d03010c1658217cee412318e6b5d8))
+* **runtime:** runtimes declare their isolation profile ([f89717a](https://github.com/elct9620/kobako/commit/f89717a6bc9809f0de0df78f97da33a49a1474ac))
+
 ## [0.6.1](https://github.com/elct9620/kobako/compare/kobako-runtime-v0.6.0...kobako-runtime-v0.6.1) (2026-07-02)
 
 

data/crates/kobako-runtime/Cargo.toml

@@ -13,7 +13,7 @@
 
 [package]
 name = "kobako-runtime"
-version = "0.6.1"
+version = "0.8.0"
 edition = "2021"
 description = "Engine-neutral host runtime contract for embedding kobako Wasm guests."
 license = "Apache-2.0"

data/crates/kobako-runtime/README.md

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

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

@@ -62,3 +62,11 @@ impl fmt::Display for Trap {
         f.write_str(msg)
     }
 }
+
+impl fmt::Display for SetupError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        let (SetupError::ModuleNotBuilt(msg) | SetupError::Dead(msg) | SetupError::Intact(msg)) =
+            self;
+        f.write_str(msg)
+    }
+}

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

@@ -1,8 +1,9 @@
 //! kobako-runtime — engine-neutral host runtime contract.
 //!
 //! The surface where a wasm engine implementation and a host frontend
-//! meet: the `Runtime` trait, the neutral per-invocation value types,
-//! and the dispatch / yield re-entry traits a frontend supplies.
+//! meet: the `Runtime` trait, the isolation `Profile` a runtime
+//! declares, the neutral per-invocation value types, and the
+//! dispatch / yield re-entry traits a frontend supplies.
 //! Nothing here depends on an engine or a frontend type — each engine
 //! hides its own machinery behind `Runtime`, and each frontend maps
 //! these shapes onto its own host-language surface at its boundary
@@ -11,6 +12,7 @@
 
 pub mod dispatch;
 pub mod error;
+pub mod profile;
 pub mod runtime;
 pub mod snapshot;
 pub mod yielder;

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

@@ -0,0 +1,35 @@
+//! Isolation profile — the posture a frontend requests and a runtime
+//! builds and declares.
+//!
+//! A rung on an ordered ladder: the host application requests the
+//! posture it wants, the runtime builds it and declares the posture it
+//! actually built, and the frontend refuses a declaration below the
+//! request — so the request is also the floor. The governing contract
+//! lives in the spec corpus (docs/behavior/security.md).
+
+/// The ordered isolation ladder a runtime builds one rung of.
+///
+/// `Hermetic` is the full ambient-denial posture: ambient time and
+/// entropy denied at the WASI boundary, no filesystem / environment /
+/// network reachability, and no host import beyond the wire ABI's
+/// `__kobako_dispatch`. `Permissive` differs in exactly one grant —
+/// live ambient time and entropy at the WASI boundary. Ordering
+/// follows strength (`Permissive < Hermetic`), so a floor check is a
+/// plain comparison.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
+pub enum Profile {
+    Permissive,
+    Hermetic,
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn a_declaration_satisfies_any_floor_at_or_below_it() {
+        assert!(Profile::Hermetic >= Profile::Hermetic);
+        assert!(Profile::Hermetic >= Profile::Permissive);
+        assert!(Profile::Permissive < Profile::Hermetic);
+    }
+}

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

@@ -11,6 +11,7 @@ use std::sync::Arc;
 
 use crate::dispatch::DispatchHandler;
 use crate::error::Error;
+use crate::profile::Profile;
 use crate::snapshot::Snapshot;
 
 /// The per-invocation entry: a one-shot mruby source (`Eval`) or an
@@ -47,4 +48,10 @@ pub trait Runtime {
         frames: Frames<'_>,
         handler: Option<Arc<dyn DispatchHandler>>,
     ) -> Result<Snapshot, Error>;
+
+    /// The isolation profile this runtime provides. Deliberately
+    /// without a default: every engine states its posture explicitly,
+    /// and a frontend refuses construction when the declaration falls
+    /// below the floor its host application requested.
+    fn profile(&self) -> Profile;
 }

data/crates/kobako-wasmtime/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## [0.8.0](https://github.com/elct9620/kobako/compare/kobako-wasmtime-v0.7.0...kobako-wasmtime-v0.8.0) (2026-07-08)
+
+
+### Bug Fixes
+
+* **crates:** keep the no-timeout epoch deadline within range ([a3255df](https://github.com/elct9620/kobako/commit/a3255df98a77825bb39b571a60fe6ff83d269d19))
+
+## [0.7.0](https://github.com/elct9620/kobako/compare/kobako-wasmtime-v0.6.1...kobako-wasmtime-v0.7.0) (2026-07-03)
+
+
+### Features
+
+* **crates:** build the requested isolation profile into the WASI context ([63c25d8](https://github.com/elct9620/kobako/commit/63c25d835d4d03010c1658217cee412318e6b5d8))
+* **runtime:** runtimes declare their isolation profile ([f89717a](https://github.com/elct9620/kobako/commit/f89717a6bc9809f0de0df78f97da33a49a1474ac))
+
 ## [0.6.1](https://github.com/elct9620/kobako/compare/kobako-wasmtime-v0.6.0...kobako-wasmtime-v0.6.1) (2026-07-02)
 
 

data/crates/kobako-wasmtime/Cargo.toml

@@ -15,7 +15,7 @@
 
 [package]
 name = "kobako-wasmtime"
-version = "0.6.1"
+version = "0.8.0"
 edition = "2021"
 description = "wasmtime implementation of the kobako host runtime contract."
 license = "Apache-2.0"
@@ -28,14 +28,14 @@ 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.6.1", path = "../kobako-runtime" }
+kobako-runtime = { version = "0.8.0", path = "../kobako-runtime" }
 # 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 = "45.0.0", default-features = false, features = [
+wasmtime = { version = "46.0.1", default-features = false, features = [
     "cranelift",
     "runtime",
     "gc",
@@ -49,7 +49,7 @@ wasmtime = { version = "45.0.0", 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 = "45.0.0", default-features = false, features = ["p1"] }
+wasmtime-wasi = { version = "46.0.1", 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.6.1" # x-release-please-version
+kobako-wasmtime = "0.8.0" # x-release-please-version
 ```
 
 ## License

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

@@ -1,11 +1,14 @@
-//! Defense-in-depth denial of guest ambient authority at the WASI layer.
+//! Denial of guest ambient authority at the WASI layer — the one grant
+//! that separates the hermetic rung from permissive;
+//! `frames::install_wasi_frames` wires these sources on `Hermetic` only.
 //!
 //! `wasmtime-wasi`'s `WasiCtxBuilder` defaults the guest's `wasi:clocks` to
 //! the host wall / monotonic clock and `wasi:random` to a fresh per-context
 //! seed. No allowlisted mrbgem reaches these preview1 imports today
 //! (`build_config/wasi.rb`), but a future libc-backed gem would silently
 //! obtain real time and host entropy — a covert timing channel and a
-//! nondeterminism source the sandbox deliberately excludes (docs/security-model.md).
+//! nondeterminism source the hermetic posture deliberately excludes
+//! (docs/security-model.md).
 //! Pinning the clocks to the Unix epoch and the RNG to a constant stream
 //! makes that denial a property of the host, not merely of the gem allowlist.
 //!

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

@@ -10,8 +10,10 @@
 
 use std::time::Duration;
 
-/// Wall-clock and output caps for one `Driver`. `None` on any field
-/// disables that cap.
+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.
 pub struct Config {
     /// Wall-clock cap for one guest `#eval` / `#run`. Stamped into a
     /// per-run `Instant` deadline by `Driver::prime_caps`.
@@ -22,4 +24,10 @@ pub struct Config {
     pub stdout_limit_bytes: Option<usize>,
     /// Byte cap for guest stderr capture. Mirror of `stdout_limit_bytes`.
     pub stderr_limit_bytes: 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
+    /// live WASI sources — and `Driver::profile` declares it back as
+    /// the built posture.
+    pub profile: Profile,
 }

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

@@ -22,6 +22,7 @@ use crate::invocation::Invocation;
 use crate::{capture, frames, instance_pre, trap};
 use kobako_runtime::dispatch::DispatchHandler;
 use kobako_runtime::error::{Error, SetupError, Trap};
+use kobako_runtime::profile::Profile;
 use kobako_runtime::runtime::{Entry, Frames, Runtime as ContractRuntime};
 use kobako_runtime::snapshot::{Capture, Completion, Snapshot, Usage};
 
@@ -182,7 +183,7 @@ impl Driver {
             }
             None => {
                 store.data_mut().set_deadline(None);
-                store.set_epoch_deadline(u64::MAX);
+                store.set_epoch_deadline(trap::NO_TIMEOUT_EPOCH_DELTA);
             }
         }
         let baseline = match exports.memory {
@@ -271,6 +272,17 @@ impl ContractRuntime for Driver {
         };
         Ok(self.build_snapshot(&store, completion))
     }
+
+    /// The posture this driver built — exactly the rung requested via
+    /// `Config`. Every per-invocation WASI context is built to it
+    /// (`frames::install_wasi_frames`): `Hermetic` freezes ambient time
+    /// and entropy (`crate::ambient`), `Permissive` leaves the live WASI
+    /// sources. Both rungs wire no filesystem, environment, or network,
+    /// and the linker adds only the wire ABI's `__kobako_dispatch`
+    /// beyond that confined WASI surface (`crate::instance_pre`).
+    fn profile(&self) -> Profile {
+        self.config.profile
+    }
 }
 
 /// Drop the memory cap as soon as the guest call returns so that

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

@@ -14,6 +14,7 @@ use crate::exports::Exports;
 use crate::invocation::Invocation;
 use crate::{ambient, capture, guest_mem};
 use kobako_runtime::error::{Error, SetupError, Trap};
+use kobako_runtime::profile::Profile;
 
 /// Return the resolved `memory` export handle, or a `Trap` when the loaded
 /// module exports no linear memory — the "not a Kobako-shaped runtime"
@@ -98,11 +99,20 @@ pub(crate) fn install_wasi_frames(
     builder.stdin(stdin_pipe);
     builder.stdout(stdout_pipe.clone());
     builder.stderr(stderr_pipe.clone());
-    // Deny the preview1 ambient-authority imports the guest never legitimately
-    // reaches but the WASI layer would otherwise grant (see `ambient`).
-    builder.wall_clock(ambient::FrozenWallClock);
-    builder.monotonic_clock(ambient::FrozenMonotonicClock);
-    builder.secure_random(ambient::deterministic_rng());
+    // The requested profile decides the ambient-authority grant: the
+    // hermetic rung denies the preview1 time and entropy imports (see
+    // `ambient`), the permissive rung leaves the live WASI sources.
+    // Filesystem, environment, and network stay absent on both rungs —
+    // the builder grants none unless asked. The exhaustive match makes
+    // a future ladder rung a compile error here, not a silent grant.
+    match config.profile {
+        Profile::Hermetic => {
+            builder.wall_clock(ambient::FrozenWallClock);
+            builder.monotonic_clock(ambient::FrozenMonotonicClock);
+            builder.secure_random(ambient::deterministic_rng());
+        }
+        Profile::Permissive => {}
+    }
     let wasi = builder.build_p1();
 
     store
@@ -174,3 +184,93 @@ where
 {
     export.ok_or_else(|| Trap::Other(SANDBOX_RUNTIME_MISSING_HOOKS.to_string()))
 }
+
+#[cfg(test)]
+mod tests {
+    //! Witness the B-54 rung split at the WASI boundary: one probe
+    //! module reads `wasi:clocks` / `wasi:random` through the context
+    //! `install_wasi_frames` builds — frozen under `Hermetic`, live
+    //! under `Permissive`.
+    use wasmtime::{Linker, Module};
+    use wasmtime_wasi::p1;
+
+    use super::*;
+    use crate::cache::shared_engine;
+
+    /// Preview1 probe with one export per ambient source: `clock_ns`
+    /// reads the realtime clock, `random_word` reads eight entropy bytes.
+    const AMBIENT_PROBE_WAT: &str = r#"
+        (module
+          (import "wasi_snapshot_preview1" "clock_time_get"
+            (func $clock (param i32 i64 i32) (result i32)))
+          (import "wasi_snapshot_preview1" "random_get"
+            (func $random (param i32 i32) (result i32)))
+          (memory (export "memory") 1)
+          (func (export "clock_ns") (result i64)
+            (drop (call $clock (i32.const 0) (i64.const 1) (i32.const 0)))
+            (i64.load (i32.const 0)))
+          (func (export "random_word") (result i64)
+            (drop (call $random (i32.const 8) (i32.const 8)))
+            (i64.load (i32.const 8))))
+    "#;
+
+    /// Instantiate the probe over a WASI context built at `profile` and
+    /// return the `(clock, random)` readings it observes.
+    fn probe_ambient(profile: Profile) -> (i64, i64) {
+        let engine = shared_engine().expect("shared engine must be constructible");
+        let config = Config {
+            timeout: None,
+            stdout_limit_bytes: None,
+            stderr_limit_bytes: None,
+            profile,
+        };
+        let mut store = WtStore::new(engine, Invocation::new(None));
+        store.set_epoch_deadline(crate::trap::NO_TIMEOUT_EPOCH_DELTA);
+        install_wasi_frames(&mut store, &config, &[]).expect("WASI context must install");
+
+        let mut linker: Linker<Invocation> = Linker::new(engine);
+        p1::add_to_linker_sync(&mut linker, |state: &mut Invocation| state.wasi_mut())
+            .expect("WASI imports must link");
+        let module = Module::new(engine, AMBIENT_PROBE_WAT).expect("probe module must compile");
+        let instance = linker
+            .instantiate(&mut store, &module)
+            .expect("probe module must instantiate");
+
+        let read = |store: &mut WtStore<Invocation>, name: &str| -> i64 {
+            instance
+                .get_typed_func::<(), i64>(store.as_context_mut(), name)
+                .expect("probe export must resolve")
+                .call(store.as_context_mut(), ())
+                .expect("probe export must run")
+        };
+        let clock = read(&mut store, "clock_ns");
+        let random = read(&mut store, "random_word");
+        (clock, random)
+    }
+
+    #[test]
+    fn hermetic_denies_ambient_time_and_entropy() {
+        let (clock, random) = probe_ambient(Profile::Hermetic);
+        assert_eq!(
+            clock, 0,
+            "a hermetic guest's wasi:clocks must read the Unix epoch, not host time"
+        );
+        assert_eq!(
+            random, 0,
+            "a hermetic guest's wasi:random must yield the constant stream, not host entropy"
+        );
+    }
+
+    #[test]
+    fn permissive_grants_live_ambient_time_and_entropy() {
+        let (clock, random) = probe_ambient(Profile::Permissive);
+        assert!(
+            clock > 0,
+            "a permissive guest's wasi:clocks must read live host time"
+        );
+        assert_ne!(
+            random, 0,
+            "a permissive guest's wasi:random must yield host entropy"
+        );
+    }
+}

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

@@ -70,12 +70,13 @@ fn build_linker() -> Result<Linker<Invocation>, SetupError> {
     // `__kobako_dispatch` host import. Signature per docs/wire-codec.md
     // § ABI Signatures:
     //   (req_ptr: i32, req_len: i32) -> i64
-    // Decodes the Request bytes, dispatches via the Ruby-side
-    // dispatch Proc (bound per-Sandbox through `Runtime#on_dispatch=`),
-    // allocates a guest buffer through `__kobako_alloc`, writes
-    // the Response bytes there, and returns the packed
-    // `(ptr<<32)|len`. The dispatcher returns 0 on any wire-layer
-    // fault (including no Proc bound); see `dispatch::handle`.
+    // Reads the Request bytes from guest memory and hands them —
+    // undecoded — to the bound `DispatchHandler` (the frontend's
+    // dispatch bridge, e.g. a Ruby Proc), then allocates a guest
+    // buffer through `__kobako_alloc`, writes the handler's Response
+    // bytes there, and returns the packed `(ptr<<32)|len`. The
+    // dispatcher returns 0 on any wire-layer fault (including no
+    // handler bound); see `dispatch::handle`.
     linker
         .func_wrap(
             "env",

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

@@ -318,10 +318,9 @@ impl ResourceLimiter for MemoryLimiter {
 
 /// Marker error returned from `MemoryLimiter::memory_growing` when the
 /// per-invocation memory cap is exceeded. Downcast from the wasmtime
-/// trap error to surface as
-/// `Kobako::MemoryLimitError` on the Ruby side. Callers use the
-/// `Display` impl below — no field is read directly — so the inner
-/// state stays private.
+/// trap error to classify the failure as a memory-limit `Trap`. Callers
+/// use the `Display` impl below — no field is read directly — so the
+/// inner state stays private.
 #[derive(Debug)]
 pub(crate) struct MemoryLimitTrap {
     desired: usize,
@@ -354,7 +353,7 @@ impl std::error::Error for MemoryLimitTrap {}
 
 /// Marker error returned from the epoch-deadline callback when the
 /// wall-clock deadline is exceeded. Downcast from the wasmtime trap
-/// error to surface as `Kobako::TimeoutError` on the Ruby side.
+/// error to classify the failure as a timeout `Trap`.
 #[derive(Debug)]
 pub(crate) struct TimeoutTrap;
 

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

@@ -1,12 +1,13 @@
 //! Trap classification for the run path.
 //!
-//! Maps a `wasmtime` run error to the right top-level `Kobako::*` Ruby
-//! exception (`TimeoutError` / `MemoryLimitError` / `TrapError`), and
-//! hosts the epoch-deadline callback that raises the wall-clock
-//! `TimeoutTrap`. The classification is a pure function over the error's
-//! downcast chain so it can be exercised from `cargo test` without the
-//! magnus surface; the trap marker types themselves live in
-//! `crate::invocation` (where the limiter / callback construct them).
+//! Classifies a `wasmtime` run error into the engine-neutral `Trap`
+//! kind (`Timeout` / `MemoryLimit` / `Other`) that each frontend maps
+//! onto its own error surface, and hosts the epoch-deadline callback
+//! that raises the wall-clock `TimeoutTrap`. The classification is a
+//! pure function over the error's downcast chain so it can be exercised
+//! from `cargo test` without any frontend; the trap marker types
+//! themselves live in `crate::invocation` (where the limiter / callback
+//! construct them).
 
 use std::time::Instant;
 
@@ -15,43 +16,48 @@ use wasmtime::{StoreContextMut, UpdateDeadline};
 use crate::invocation::{Invocation, MemoryLimitTrap, TimeoutTrap};
 use kobako_runtime::error::{SetupError, Trap};
 
+/// Epoch delta that keeps the deadline effectively unreachable when no
+/// wall-clock cap is configured. Half the epoch range rather than
+/// `u64::MAX`: wasmtime adds the delta to the engine's current epoch,
+/// which the process-wide ticker advances for the engine's whole
+/// lifetime, so the full range overflows the sum (a panic under debug
+/// overflow checks).
+pub(crate) const NO_TIMEOUT_EPOCH_DELTA: u64 = u64::MAX / 2;
+
 /// Epoch-deadline callback installed on every Store. Read the per-run
 /// wall-clock deadline from `Invocation` and trap with
 /// `TimeoutTrap` once the deadline has passed; otherwise extend the
 /// next check by one tick of the process-wide epoch ticker. When the
 /// deadline is `None` the callback should not fire under the normal
 /// `Driver` invoke flow because
-/// `set_epoch_deadline(u64::MAX)` is used; returning a long extension
-/// keeps the callback inert as a defence in depth.
+/// `NO_TIMEOUT_EPOCH_DELTA` is primed; returning the same long
+/// extension keeps the callback inert as a defence in depth.
 pub(crate) fn epoch_deadline_callback(
     ctx: StoreContextMut<'_, Invocation>,
 ) -> wasmtime::Result<UpdateDeadline> {
     match ctx.data().deadline() {
         Some(deadline) if Instant::now() >= deadline => Err(wasmtime::Error::new(TimeoutTrap)),
         Some(_) => Ok(UpdateDeadline::Continue(1)),
-        None => Ok(UpdateDeadline::Continue(u64::MAX / 2)),
+        None => Ok(UpdateDeadline::Continue(NO_TIMEOUT_EPOCH_DELTA)),
     }
 }
 
 /// Configured-cap path classification for a wasmtime error. The
-/// downcast logic stays in a pure helper so the
-/// `Kobako::TimeoutError` / `MemoryLimitError` /
-/// `Kobako::TrapError` mapping can be exercised from `cargo test`
-/// without the magnus surface.
+/// downcast logic stays in a pure helper so the `Trap` kind routing
+/// can be exercised from `cargo test` without any frontend.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 enum TrapClass {
     /// Wall-clock cap path.
     Timeout,
     /// Linear-memory cap path.
     MemoryLimit,
-    /// Any other wasmtime error — surfaces as the base
-    /// `Kobako::TrapError`.
+    /// Any other wasmtime error — surfaces as the base `Trap::Other`.
     Other,
 }
 
-/// Inspect a wasmtime error to decide which top-level `Kobako::*` trap
-/// class it should map to. Pure function — operates on the error's
-/// downcast chain only, no magnus / Ruby state required.
+/// Inspect a wasmtime error to decide which neutral trap kind it
+/// belongs to. Pure function — operates on the error's downcast chain
+/// only, no frontend state required.
 fn classify_trap(err: &wasmtime::Error) -> TrapClass {
     if err.downcast_ref::<TimeoutTrap>().is_some() {
         TrapClass::Timeout
@@ -123,8 +129,23 @@ pub(crate) fn instantiate_err(err: wasmtime::Error) -> SetupError {
 
 #[cfg(test)]
 mod tests {
-    use super::{classify_trap, other_trap_message, TrapClass};
-    use crate::invocation::{MemoryLimitTrap, TimeoutTrap};
+    use super::{classify_trap, other_trap_message, TrapClass, NO_TIMEOUT_EPOCH_DELTA};
+    use crate::invocation::{Invocation, MemoryLimitTrap, TimeoutTrap};
+
+    // The no-timeout priming delta is added to the engine's current
+    // epoch inside wasmtime, and the process-wide ticker advances that
+    // epoch from the first `shared_engine` call on — so the sum must
+    // stay in range for a long-lived engine, not just a fresh one.
+    // `increment_epoch` stands in for the ticker to make the ticked
+    // state deterministic; under debug overflow checks an overflowing
+    // delta panics right here.
+    #[test]
+    fn no_timeout_delta_survives_a_ticked_engine_epoch() {
+        let engine = crate::cache::shared_engine().expect("shared engine must be constructible");
+        engine.increment_epoch();
+        let mut store = wasmtime::Store::new(engine, Invocation::new(None));
+        store.set_epoch_deadline(NO_TIMEOUT_EPOCH_DELTA);
+    }
 
     #[test]
     fn classify_trap_routes_timeout_trap_to_timeout() {

data/ext/kobako/Cargo.toml

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

data/ext/kobako/src/lib.rs

@@ -1,12 +1,10 @@
 use magnus::{Error, Ruby};
 
 mod runtime;
-mod snapshot;
 
 #[magnus::init]
 fn init(ruby: &Ruby) -> Result<(), Error> {
     let module = ruby.define_module("Kobako")?;
     runtime::init(ruby, module)?;
-    snapshot::init(ruby, module)?;
     Ok(())
 }