kobako 0.12.1 → 0.12.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b245ee235cc4309150a54ed8d5b8246216ebee7787fa103ebd70f7434797f3d8
-  data.tar.gz: b2857e6f02527c476b32e381886d20d73571b3fe2224907aea868223e0b13fee
+  metadata.gz: 3b5515d639e59a612b4aa1008c6456bdc493152b725d89c36c8c51250368754e
+  data.tar.gz: 4fd2e14daaea5892b500cf8ba4d0fe94212d95e674a762afc482f22bd8a30f7d
 SHA512:
-  metadata.gz: 8c612f87f0cb0665f4510f224eea4bd7a79cdae06df9aef287933296aba78b3ade6dc3849bdc3bc48dcccef1d8789125aac30ba265d33ce4f56dcbafa6635cd1
-  data.tar.gz: f1191f5e65a1448b8ff675fe34de83052d1a1b5ed6757dd448b9cc119c3790d6f78184706fe09eddffef27521b81dd9f365d49ca2aa19615c2c5beb7f744289d
+  metadata.gz: 4676997989e6e7a6711c3f597b20a2db4a0ae2a50361d3ef66f235123741c043e936b73ae553484703cb5bf384ca9b3b42a6d4282bac94dba8ef3d018bf96130
+  data.tar.gz: 3b8573f8f67a79f00fd747961166835e89d735cdb02462bdb36ae399b1ceddd5cf3b38a1e82f0b22797f9d67b0a7c273a03bb5e4cb8b74806d0dadb41dcc0fb0

data/.release-please-manifest.json

@@ -1 +1 @@
-{".":"0.12.1","wasm/kobako-core":"0.6.0","wasm/kobako":"0.6.0","wasm/kobako-io":"0.6.0","wasm/kobako-json":"0.6.0","wasm/kobako-regexp":"0.6.0","wasm/kobako-baker":"0.6.0"}
+{".":"0.12.2","wasm/kobako-core":"0.6.1","wasm/kobako":"0.6.1","wasm/kobako-io":"0.6.1","wasm/kobako-json":"0.6.1","wasm/kobako-regexp":"0.6.1","wasm/kobako-baker":"0.6.1","crates/kobako-runtime":"0.6.1","crates/kobako-wasmtime":"0.6.1"}

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## [0.12.2](https://github.com/elct9620/kobako/compare/v0.12.1...v0.12.2) (2026-07-02)
+
+
+### Bug Fixes
+
+* **codec:** bound ext-envelope nesting to keep deep Fault chains off the native stack ([7bed2b2](https://github.com/elct9620/kobako/commit/7bed2b2f43a63538aa60610c82d2eb65bcce7b15))
+* **guest:** size collection conversions by C array length, not #length ([90ecbd0](https://github.com/elct9620/kobako/commit/90ecbd0cb6a990b8c5a1e5deec3a10df4eaa37df))
+* **io:** enforce the fd allowlist at the write syscall ([1b300df](https://github.com/elct9620/kobako/commit/1b300df7bee8f87b701f76b42300163a8899b93e))
+* **release:** advance last-release-sha past the unparseable fork merge ([d06117d](https://github.com/elct9620/kobako/commit/d06117d462eea0ae5648e5bdd6886b735765f3b3))
+* **sandbox:** honor nil to disable the output caps, and validate them ([51d1e90](https://github.com/elct9620/kobako/commit/51d1e900e3d7d659ffd432ff3d613786e9073b05))
+
 ## [0.12.1](https://github.com/elct9620/kobako/compare/v0.12.0...v0.12.1) (2026-06-27)
 
 

data/Cargo.lock

@@ -922,10 +922,23 @@ dependencies = [
 
 [[package]]
 name = "kobako"
-version = "0.12.1"
+version = "0.12.2"
 dependencies = [
- "libc",
+ "kobako-runtime",
+ "kobako-wasmtime",
  "magnus",
+]
+
+[[package]]
+name = "kobako-runtime"
+version = "0.6.1"
+
+[[package]]
+name = "kobako-wasmtime"
+version = "0.6.1"
+dependencies = [
+ "kobako-runtime",
+ "libc",
  "sha2 0.11.0",
  "wasmtime",
  "wasmtime-wasi",

data/Cargo.toml

@@ -6,8 +6,12 @@
 members = ["./ext/kobako"]
 # `wasm/` is a sibling workspace (kobako-wasm crate) compiled for
 # wasm32-wasip1; excluding it keeps the host (wasmtime) and guest
-# dependency graphs separate.
-exclude = ["wasm", "vendor"]
+# dependency graphs separate. `crates/` is the native host-side crate
+# workspace; excluding it lets the ext consume its members as plain
+# path dependencies resolved as standalone packages — the same shape
+# the packaged gem sees, which ships the crates without their
+# workspace manifest.
+exclude = ["wasm", "vendor", "crates"]
 resolver = "2"
 
 # Strip the local-symbol table from the shipped ext (~22% of the binary).

data/README.md

@@ -127,7 +127,7 @@ end
 |---------------------------------|----------------|------------------------------------------------------|
 | `Kobako::TimeoutError`          | `TrapError`    | Per-invocation `timeout` exhausted                   |
 | `Kobako::MemoryLimitError`      | `TrapError`    | Per-invocation `memory_limit` exhausted              |
-| `Kobako::HandlerExhaustedError` | `SandboxError` | Handle counter reached its 2³¹ − 1 cap               |
+| `Kobako::HandleExhaustedError` | `SandboxError` | Handle counter reached its 2³¹ − 1 cap               |
 | `Kobako::BytecodeError`         | `SandboxError` | `#preload(binary:)` failed RITE validation at replay |
 
 `SandboxError` and `ServiceError` carry structured `origin` / `klass` / `backtrace_lines` / `details` fields when the guest produced a panic envelope.

data/crates/kobako-runtime/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## [0.6.1](https://github.com/elct9620/kobako/compare/kobako-runtime-v0.6.0...kobako-runtime-v0.6.1) (2026-07-02)
+
+
+### Miscellaneous Chores
+
+* **kobako-runtime:** Synchronize kobako crates versions

data/crates/kobako-runtime/Cargo.toml

@@ -0,0 +1,23 @@
+# kobako-runtime — engine-neutral host runtime contract.
+#
+# The contract a wasm engine must satisfy to drive a kobako guest,
+# free of any engine or frontend type: the `Runtime` trait plus the
+# neutral value types (`Snapshot`, `Trap`, `SetupError`, ...) and the
+# dispatch / yield re-entry traits a frontend supplies. Engine
+# implementations (`kobako-wasmtime`) and host frontends (the Ruby
+# ext) meet on this surface, so the engine stays swappable.
+#
+# Self-contained by design: the Ruby gem ships this crate without the
+# `crates/` workspace manifest, so no `workspace = true` inheritance
+# fields may appear here.
+
+[package]
+name = "kobako-runtime"
+version = "0.6.1"
+edition = "2021"
+description = "Engine-neutral host runtime contract for embedding kobako Wasm guests."
+license = "Apache-2.0"
+repository = "https://github.com/elct9620/kobako"
+readme = "README.md"
+keywords = ["wasm", "mruby", "sandbox", "wasi"]
+categories = ["wasm", "virtualization"]

data/crates/kobako-runtime/README.md

@@ -0,0 +1,34 @@
+# kobako-runtime
+
+Engine-neutral host runtime contract for
+[kobako](https://github.com/elct9620/kobako), an in-process Wasm
+sandbox for running untrusted mruby scripts.
+
+A kobako host drives a Guest Binary through a wasm engine; this crate
+is the surface where the two meet, free of any engine or frontend
+type, so the engine stays swappable:
+
+- `runtime` — the `Runtime` trait: one guest invocation on a fresh
+  instance in, its observable `Snapshot` out
+- `snapshot` — the per-invocation observables: `Completion` (outcome
+  or trap), the two output `Capture`s, and resource `Usage`, uniform
+  across success and trap
+- `error` — the neutral failure channels: `Trap` (engine fault) and
+  `SetupError` (the invocation never started)
+- `dispatch` / `yielder` — the `DispatchHandler` and `Yielder` traits
+  a frontend supplies for guest→host dispatch and block-yield re-entry
+
+Engine implementations (such as `kobako-wasmtime`) implement
+`Runtime`; host frontends (such as the kobako Ruby gem's native ext)
+map the neutral types onto their own language surface.
+
+## Usage
+
+```toml
+[dependencies]
+kobako-runtime = "0.6.1" # x-release-please-version
+```
+
+## License
+
+Apache-2.0

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

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

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

@@ -0,0 +1,64 @@
+//! Engine-neutral host error channels, free of any frontend dependency.
+//!
+//! The run path produces these instead of constructing host-language
+//! exceptions directly; each frontend's boundary is the single place that
+//! maps them onto its own error classes (the Ruby ext does so in its error
+//! mapper). Keeping the channels frontend-free lets any engine
+//! implementation produce them unchanged.
+
+use std::fmt;
+
+/// A guest invocation that faulted in the wasm engine, or a host-detected
+/// runtime corruption during invocation, classified into the host-facing
+/// kinds a frontend surfaces distinctly: the wall-clock cap (`Timeout`),
+/// the linear-memory cap (`MemoryLimit`), and every other engine fault
+/// (`Other`).
+#[derive(Debug)]
+pub enum Trap {
+    Timeout(String),
+    MemoryLimit(String),
+    Other(String),
+}
+
+/// A failure that yields no invocation outcome. The discriminant records
+/// the runtime's state so a frontend can attribute the failure per SPEC:
+/// `ModuleNotBuilt` (the guest artifact is absent), `Dead` (the runtime
+/// could not be constructed), and `Intact` (the runtime is live but a
+/// host-side pre-call step failed, so no discard-and-recreate recovery is
+/// owed).
+#[derive(Debug)]
+pub enum SetupError {
+    ModuleNotBuilt(String),
+    Dead(String),
+    Intact(String),
+}
+
+/// A failure that prevented the invocation from starting — a pre-call
+/// engine fault (`Trap`) or a host-side setup fault (`Setup`) — unified so
+/// the run mechanics can propagate both with `?`; a frontend destructures
+/// it back into the two channels. Faults after the guest export starts
+/// ride in `Completion::Trap` instead, so captures and usage survive them.
+#[derive(Debug)]
+pub enum Error {
+    Trap(Trap),
+    Setup(SetupError),
+}
+
+impl From<Trap> for Error {
+    fn from(trap: Trap) -> Self {
+        Error::Trap(trap)
+    }
+}
+
+impl From<SetupError> for Error {
+    fn from(err: SetupError) -> Self {
+        Error::Setup(err)
+    }
+}
+
+impl fmt::Display for Trap {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        let (Trap::Timeout(msg) | Trap::MemoryLimit(msg) | Trap::Other(msg)) = self;
+        f.write_str(msg)
+    }
+}

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

@@ -0,0 +1,16 @@
+//! 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.
+//! 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
+//! (for the Ruby ext that is the error mapper in its runtime module),
+//! so the engine stays swappable.
+
+pub mod dispatch;
+pub mod error;
+pub mod runtime;
+pub mod snapshot;
+pub mod yielder;

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

@@ -0,0 +1,50 @@
+//! Engine-neutral host runtime contract.
+//!
+//! The contract a wasm engine must satisfy to drive a kobako guest: take a
+//! per-invocation entry plus its stdin frames, run one invocation on a
+//! fresh instance, and return the observable `Snapshot` — `Ok` iff the
+//! guest export ran, `Err` when the invocation never started. Nothing here
+//! mentions `magnus` or a Ruby type — a frontend supplies the dispatch
+//! handler, the contract only borrows it.
+
+use std::sync::Arc;
+
+use crate::dispatch::DispatchHandler;
+use crate::error::Error;
+use crate::snapshot::Snapshot;
+
+/// The per-invocation entry: a one-shot mruby source (`Eval`) or an
+/// entrypoint-dispatch envelope (`Run`). Both ride alongside the stdin
+/// `Frames`; `Run` additionally copies its envelope into guest memory.
+pub enum Entry<'a> {
+    Eval { source: &'a [u8] },
+    Run { envelope: &'a [u8] },
+}
+
+/// The stdin frames shared by both entries: the Frame 1 preamble (the
+/// Sandbox's registrations) and the Frame 3 snippet-replay payload.
+pub struct Frames<'a> {
+    pub preamble: &'a [u8],
+    pub snippets: &'a [u8],
+}
+
+/// Engine-neutral runtime: drives one guest invocation on a fresh instance
+/// and returns its observable `Snapshot`. `Ok` means the guest export ran
+/// — the `Snapshot` carries the completion (outcome or trap), captures,
+/// and usage uniformly; `Err` means the invocation never started.
+///
+/// Safety contract for `handler`: the runtime only *borrows* the handler
+/// for the duration of `invoke` and never roots it. A frontend whose
+/// handler references a GC-managed object (e.g. a Ruby `Proc`) must keep
+/// that object alive — and, under a moving GC, pinned — for the whole call.
+/// The Ruby ext does this by holding the `Proc` on its long-lived Runtime
+/// wrapper and GC-marking it; the runtime itself touches no frontend
+/// value.
+pub trait Runtime {
+    fn invoke(
+        &self,
+        entry: Entry<'_>,
+        frames: Frames<'_>,
+        handler: Option<Arc<dyn DispatchHandler>>,
+    ) -> Result<Snapshot, Error>;
+}

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

@@ -0,0 +1,46 @@
+//! Engine-neutral, frontend-free per-invocation observable bundle.
+//!
+//! The observables of a single guest invocation, expressed without any
+//! frontend type and uniform across success and trap: how the invocation
+//! completed, the two captured output channels, and the resource usage.
+//! A `Snapshot` exists iff the guest export ran — a failure to even start
+//! the invocation travels on the `invoke` `Err` channel instead.
+
+use crate::error::Trap;
+
+/// One captured output channel: the bytes the guest wrote (already clipped
+/// to the channel's cap) and whether the cap was reached.
+pub struct Capture {
+    pub bytes: Vec<u8>,
+    pub truncated: bool,
+}
+
+/// How the guest invocation completed: `Outcome` carries the
+/// OUTCOME_BUFFER bytes the guest returned; `Trap` is an engine fault
+/// after the export call started, kept as a value so the rest of the
+/// `Snapshot` survives it.
+pub enum Completion {
+    Outcome(Vec<u8>),
+    Trap(Trap),
+}
+
+/// Resource usage of one guest invocation, measured across the same
+/// bracket as the wall-clock / memory caps: `wall_time` is the seconds
+/// spent inside the guest export call; `memory_peak` is the high-water
+/// `memory.grow` delta in bytes past the entry-time baseline.
+#[derive(Clone, Copy)]
+pub struct Usage {
+    pub wall_time: f64,
+    pub memory_peak: usize,
+}
+
+/// The observables of one guest invocation, uniform across completion
+/// kinds: captures and usage are collected on trap and outcome alike.
+/// What a frontend exposes from the trap path is its own contract
+/// decision.
+pub struct Snapshot {
+    pub completion: Completion,
+    pub stdout: Capture,
+    pub stderr: Capture,
+    pub usage: Usage,
+}

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

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

data/crates/kobako-wasmtime/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## [0.6.1](https://github.com/elct9620/kobako/compare/kobako-wasmtime-v0.6.0...kobako-wasmtime-v0.6.1) (2026-07-02)
+
+
+### Miscellaneous Chores
+
+* **kobako-wasmtime:** Synchronize kobako crates versions

data/crates/kobako-wasmtime/Cargo.toml

@@ -0,0 +1,62 @@
+# kobako-wasmtime — the wasmtime implementation of the kobako runtime
+# contract.
+#
+# The engine half of a kobako host: `Driver` implements
+# `kobako_runtime::runtime::Runtime` over wasmtime, owning every
+# engine-bound mechanic — the process-wide Engine + compiled-Module
+# caches, the pre-linked `InstancePre`, the epoch wall-clock timeout,
+# the linear-memory cap, and the frozen-clock / constant-RNG ambient
+# denial. Frontends (the kobako Ruby gem's native ext) construct a
+# `Driver` and drive invocations through the contract trait only.
+#
+# Self-contained by design: the Ruby gem ships this crate without the
+# `crates/` workspace manifest, so no `workspace = true` inheritance
+# fields may appear here.
+
+[package]
+name = "kobako-wasmtime"
+version = "0.6.1"
+edition = "2021"
+description = "wasmtime implementation of the kobako host runtime contract."
+license = "Apache-2.0"
+repository = "https://github.com/elct9620/kobako"
+readme = "README.md"
+keywords = ["wasm", "mruby", "sandbox", "wasi", "wasmtime"]
+categories = ["wasm", "virtualization"]
+
+[dependencies]
+# 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" }
+# 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 = [
+    "cranelift",
+    "runtime",
+    "gc",
+    "gc-drc",
+    "addr2line",
+    "demangle",
+    "wat",
+] }
+# wasmtime-wasi provides WASI preview1 support for routing guest stdout/stderr
+# into in-memory buffers. The `p1` feature enables the
+# 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"] }
+# 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.
+sha2 = "0.11"
+
+# libc supplies geteuid for the cache-directory ownership check gating
+# the unsafe artifact deserialize (see cache.rs); std exposes a file's
+# owner but not the process's effective uid.
+[target.'cfg(unix)'.dependencies]
+libc = "0.2"

data/crates/kobako-wasmtime/README.md

@@ -0,0 +1,32 @@
+# kobako-wasmtime
+
+The [wasmtime](https://wasmtime.dev) implementation of the
+[kobako](https://github.com/elct9620/kobako) host runtime contract
+([`kobako-runtime`](https://crates.io/crates/kobako-runtime)).
+
+`Driver` implements the contract's `Runtime` trait over wasmtime and
+owns every engine-bound mechanic, so frontends see only the neutral
+contract surface:
+
+- process-wide Engine and compiled-Module caches with an on-disk AOT
+  (`.cwasm`) artifact cache keyed by Guest Binary content
+- a pre-linked `InstancePre` per guest path; every invocation runs on
+  a fresh instance and discards its Store afterwards
+- the epoch-based wall-clock timeout and the per-invocation
+  linear-memory cap
+- ambient denial: frozen WASI clocks and a constant RNG, so a guest
+  observes no real time and no real entropy
+
+The kobako Ruby gem's native ext is the first frontend; a Rust host
+SDK consumes the same surface.
+
+## Usage
+
+```toml
+[dependencies]
+kobako-wasmtime = "0.6.1" # x-release-please-version
+```
+
+## License
+
+Apache-2.0

data/{ext/kobako/src/runtime → crates/kobako-wasmtime/src}/ambient.rs

@@ -19,7 +19,7 @@ use wasmtime_wasi::random::Deterministic;
 use wasmtime_wasi::{HostMonotonicClock, HostWallClock};
 
 /// Wall clock frozen at the Unix epoch — the guest observes no real time.
-pub(super) struct FrozenWallClock;
+pub(crate) struct FrozenWallClock;
 
 impl HostWallClock for FrozenWallClock {
     fn resolution(&self) -> Duration {
@@ -32,7 +32,7 @@ impl HostWallClock for FrozenWallClock {
 }
 
 /// Monotonic clock frozen at zero — the guest observes no elapsed time.
-pub(super) struct FrozenMonotonicClock;
+pub(crate) struct FrozenMonotonicClock;
 
 impl HostMonotonicClock for FrozenMonotonicClock {
     fn resolution(&self) -> u64 {
@@ -46,7 +46,7 @@ impl HostMonotonicClock for FrozenMonotonicClock {
 
 /// Constant-stream RNG handed to the guest's `wasi:random`, so a guest that
 /// reaches `random_get` receives no host entropy.
-pub(super) fn deterministic_rng() -> Deterministic {
+pub(crate) fn deterministic_rng() -> Deterministic {
     Deterministic::new(vec![0])
 }
 

data/{ext/kobako/src/runtime → crates/kobako-wasmtime/src}/cache.rs

@@ -1,13 +1,12 @@
 //! Process-wide caches for the wasmtime `Engine` and compiled
 //! `Module`, plus the on-disk compiled-artifact cache.
 //!
-//! SPEC.md "Code Organization" pins `ext/` as private and forbids
-//! exposing wasm engine types to the Host App or downstream gems. To
-//! amortise Engine creation and Module JIT compilation across multiple
-//! `Kobako::Sandbox` constructions, the ext keeps a process-scope
-//! shared Engine and a per-path Module cache. Both are transparent to
-//! Ruby callers, who construct a `Runtime` via
-//! `Kobako::Runtime.from_path(...)` and never see Engine or Module.
+//! SPEC.md "Code Organization" forbids exposing wasm engine types to
+//! the Host App or downstream gems. To amortise Engine creation and
+//! Module JIT compilation across multiple sandbox constructions, the
+//! driver keeps a process-scope shared Engine and a per-path Module
+//! cache. Both are transparent to frontends, which construct a
+//! `Driver` via `Driver::new` and never see Engine or Module.
 //!
 //! Across processes, the Cranelift compile cost is amortised by a
 //! best-effort `.cwasm` disk cache keyed by the SHA-256 of the Guest
@@ -27,11 +26,10 @@ use std::sync::{Mutex, OnceLock};
 use std::thread;
 use std::time::{Duration, SystemTime};
 
-use magnus::{Error as MagnusError, Ruby};
 use sha2::{Digest, Sha256};
 use wasmtime::{Config as WtConfig, Engine as WtEngine, Module as WtModule};
 
-use super::errors::{setup_err, MODULE_NOT_BUILT_ERROR};
+use kobako_runtime::error::SetupError;
 
 static SHARED_ENGINE: OnceLock<WtEngine> = OnceLock::new();
 static MODULE_CACHE: OnceLock<Mutex<HashMap<PathBuf, WtModule>>> = OnceLock::new();
@@ -60,17 +58,15 @@ const EPOCH_TICK: Duration = Duration::from_millis(10);
 /// cap. The first call spawns the process-singleton ticker
 /// thread that drives `engine.increment_epoch()` at `EPOCH_TICK`
 /// cadence; subsequent calls reuse the same engine and ticker.
-pub(crate) fn shared_engine() -> Result<&'static WtEngine, MagnusError> {
+pub(crate) fn shared_engine() -> Result<&'static WtEngine, SetupError> {
     if let Some(engine) = SHARED_ENGINE.get() {
         return Ok(engine);
     }
     let mut config = WtConfig::new();
     config.wasm_exceptions(true);
     config.epoch_interruption(true);
-    let engine = WtEngine::new(&config).map_err(|e| {
-        let ruby = Ruby::get().expect("Ruby thread");
-        setup_err(&ruby, format!("engine init: {}", e))
-    })?;
+    let engine =
+        WtEngine::new(&config).map_err(|e| SetupError::Dead(format!("engine init: {e}")))?;
     let engine = SHARED_ENGINE.get_or_init(|| engine);
     spawn_epoch_ticker(engine.clone());
     Ok(engine)
@@ -95,11 +91,11 @@ fn spawn_epoch_ticker(engine: WtEngine) {
 }
 
 /// Look up `path` in the per-path Module cache, compiling and inserting
-/// the artifact on a miss. Raises `Kobako::ModuleNotBuiltError`
-/// when the file is missing — the headline error for the common
-/// pre-build state on a fresh clone before `rake compile`.
-pub(crate) fn cached_module(path: &Path) -> Result<WtModule, MagnusError> {
-    let ruby = Ruby::get().expect("Ruby thread");
+/// the artifact on a miss. Returns `SetupError::ModuleNotBuilt`
+/// (boundary → `Kobako::ModuleNotBuiltError`) when the file is missing —
+/// the headline error for the common pre-build state on a fresh clone
+/// before `rake compile`.
+pub(crate) fn cached_module(path: &Path) -> Result<WtModule, SetupError> {
     let cache = MODULE_CACHE.get_or_init(|| Mutex::new(HashMap::new()));
 
     if let Some(module) = cache
@@ -112,33 +108,25 @@ pub(crate) fn cached_module(path: &Path) -> Result<WtModule, MagnusError> {
     }
 
     if !path.exists() {
-        return Err(MagnusError::new(
-            ruby.get_inner(&MODULE_NOT_BUILT_ERROR),
-            format!(
-                "Sandbox runtime not found at {}; run `bundle exec rake wasm:build` to build it",
-                path.display()
-            ),
-        ));
+        return Err(SetupError::ModuleNotBuilt(format!(
+            "Sandbox runtime not found at {}; run `bundle exec rake wasm:build` to build it",
+            path.display()
+        )));
     }
 
     let bytes = fs::read(path).map_err(|e| {
-        setup_err(
-            &ruby,
-            format!(
-                "failed to read Sandbox runtime at {}: {}",
-                path.display(),
-                e
-            ),
-        )
+        SetupError::Dead(format!(
+            "failed to read Sandbox runtime at {}: {e}",
+            path.display()
+        ))
     })?;
     let engine = shared_engine()?;
     let artifact = artifact_path(&bytes);
     let module = match artifact.as_deref().and_then(|p| load_artifact(engine, p)) {
         Some(module) => module,
         None => {
-            let module = WtModule::new(engine, &bytes).map_err(|e| {
-                setup_err(&ruby, format!("failed to compile Sandbox runtime: {}", e))
-            })?;
+            let module = WtModule::new(engine, &bytes)
+                .map_err(|e| SetupError::Dead(format!("failed to compile Sandbox runtime: {e}")))?;
             if let Some(p) = artifact.as_deref() {
                 store_artifact(&module, p);
             }
@@ -159,11 +147,12 @@ const ARTIFACT_TTL: Duration = Duration::from_secs(30 * 24 * 60 * 60);
 
 /// Compute the disk-cache location for a Guest Binary's compiled
 /// artifact: `$XDG_CACHE_HOME/kobako` (falling back to
-/// `~/.cache/kobako`) `/<sha256 of the wasm bytes>-<gem version>.cwasm`.
+/// `~/.cache/kobako`) `/<sha256 of the wasm bytes>-<crate version>.cwasm`.
 /// Content addressing makes a rebuilt Guest Binary a new cache entry
-/// rather than an invalidation problem; the gem-version segment keeps
-/// two installed kobako versions (each pinning its own wasmtime) from
-/// sharing a key and recompile-thrashing each other's entry. wasmtime
+/// rather than an invalidation problem; the crate-version segment keeps
+/// two installed kobako-wasmtime versions (each pinning its own
+/// wasmtime) from sharing a key and recompile-thrashing each other's
+/// entry. wasmtime
 /// itself rejects an artifact produced by an incompatible wasmtime
 /// version or Config at deserialize time. Returns `None` when no home
 /// directory is available — the caller then just compiles in-process.