kobako 0.7.0 → 0.9.0

data/README.md

@@ -283,6 +283,29 @@ sandbox.run(:Greeter, name: "world") # => "hello, world"
 
 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.
 
+## Security
+
+kobako isolates the guest, but **what it may reach is whatever you `bind`** — and `bind`
+exposes *every* public method of the object. So bind a purpose-built object scoped to the
+task, not a capable one whose other methods leak more than you intend.
+
+```ruby
+class ThemeReader          # only #color is reachable; AppConfig.secret_key is not
+  def color = AppConfig.theme.color
+end
+
+sandbox = Kobako::Sandbox.new
+sandbox.define(:Cfg).bind(:Settings, ThemeReader.new)  # not: bind(:Settings, AppConfig)
+
+sandbox.eval('Cfg::Settings.color')  # => "#3366ff"  — every other method raises NoMethodError
+```
+
+Guest code can name any `<Namespace>::<Member>` path, but a forged name only resolves to
+something you bound — the real authorization gate is this host-side allowlist. Give each
+trust context its own Sandbox, and see [`docs/security.md`](docs/security.md) for the rest
+as security-design concerns: validating untrusted input, default-deny external effects,
+and controlling the return surface.
+
 ## Performance
 
 Order-of-magnitude figures on macOS arm64, Ruby 3.4.7, YJIT off. Absolute values vary by hardware but ratios are stable across machines. Full numbers, methodology, and the +10%-regression gate live in [`benchmark/README.md`](benchmark/README.md).
@@ -299,6 +322,8 @@ Order-of-magnitude figures on macOS arm64, Ruby 3.4.7, YJIT off. Absolute values
 
 Construct one Sandbox at boot so the ~600 ms JIT cost lands off the request hot path. `ext/` does not release the GVL during wasmtime execution, so wasm work is GVL-serialized: aggregate throughput stays around 7-8k `#eval`/s regardless of Thread count, though Ruby-side `#eval` setup still overlaps. A +10% regression on any of the six SPEC-mandated benchmarks 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 (`#10` 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.
+
 ```bash
 bundle exec rake bench  # six gated regression benchmarks (~5-8 min)
 ```
@@ -312,7 +337,7 @@ bin/setup         # install dependencies
 bundle exec rake  # default: compile + test + rubocop + steep
 ```
 
-Building from source requires a WASI-capable Rust toolchain in addition to the standard host toolchain; the first compile walks the full vendor / mruby / wasm chain. See [`CLAUDE.md`](CLAUDE.md) for the rake task map and pipeline layout. `bin/console` opens an IRB session with the gem preloaded; `bundle exec rake install` installs the local checkout as a gem.
+Building from source requires a WASI-capable Rust toolchain in addition to the standard host toolchain; the first compile walks the full chain — the [beni](https://github.com/elct9620/beni) gem vendors wasi-sdk + mruby and builds `libmruby.a` (`rake beni:build`), then `rake wasm:build` produces the Guest Binary. See [`CLAUDE.md`](CLAUDE.md) for the rake task map and pipeline layout. `bin/console` opens an IRB session with the gem preloaded; `bundle exec rake install` installs the local checkout as a gem.
 
 ## Contributing
 

data/ext/kobako/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "kobako"
-version = "0.7.0"
+version = "0.9.0"
 edition = "2021"
 authors = ["Aotokitsuruya <contact@aotoki.me>"]
 license = "Apache-2.0"
@@ -14,12 +14,10 @@ magnus = { version = "0.8.2" }
 # 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. WASI integration is layered on
-# later via `wasmtime-wasi` once stdin/stdout wiring is needed (item #16).
+# 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 = "44.0.1", default-features = false, features = [
+wasmtime = { version = "45.0.0", default-features = false, features = [
     "cranelift",
     "runtime",
     "gc",
@@ -33,4 +31,4 @@ wasmtime = { version = "44.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 = "44.0.1", default-features = false, features = ["p1"] }
+wasmtime-wasi = { version = "45.0.0", default-features = false, features = ["p1"] }

data/ext/kobako/src/runtime/dispatch.rs

@@ -1,7 +1,7 @@
 //! Host-side dispatch for the `__kobako_dispatch` import.
 //!
 //! When the guest invokes the wasm import declared in
-//! `wasm/kobako-wasm/src/abi.rs`, wasmtime calls back into the host
+//! `wasm/kobako-core/src/abi.rs`, wasmtime calls back into the host
 //! through the closure built in `super::Runtime::build`.
 //! That closure delegates here. The dispatcher (docs/behavior.md B-12 / B-13):
 //!
@@ -180,9 +180,9 @@ fn try_handle(
     write_response(caller, &resp_bytes)
 }
 
-/// Invoke the Ruby-side dispatch +Proc+ with the request bytes and return
+/// Invoke the Ruby-side dispatch `Proc` with the request bytes and return
 /// the encoded Response bytes. The Proc is contracted to fold every
-/// dispatch failure into a +Response.err+ envelope (see
+/// dispatch failure into a `Response.err` envelope (see
 /// `Kobako::Transport::Dispatcher.dispatch`), so reaching the error
 /// branch is itself a wire-layer fault rather than a normal control path.
 fn invoke_on_dispatch(

data/ext/kobako/src/runtime/guest_mem.rs

@@ -127,7 +127,7 @@ pub(super) fn guest_buffer_range(
 
 /// Unpack the `(ptr, len)` u64 returned by `__kobako_take_outcome`:
 /// high 32 bits = ptr, low 32 bits = len. Mirrors the guest-side
-/// `crate::abi::unpack_u64` in `wasm/kobako-wasm/src/abi.rs`.
+/// `unpack_u64` in `wasm/kobako-core/src/abi.rs`.
 pub(super) fn unpack_outcome_packed(packed: u64) -> (usize, usize) {
     let ptr = (packed >> 32) as u32 as usize;
     let len = packed as u32 as usize;

data/ext/kobako/src/runtime/invocation.rs

@@ -82,7 +82,7 @@ impl Invocation {
         self.stderr_pipe = Some(stderr);
     }
 
-    /// Register the Ruby-side dispatch +Proc+. From this point on, every
+    /// Register the Ruby-side dispatch `Proc`. From this point on, every
     /// `__kobako_dispatch` host import invocation calls the Proc with the
     /// request bytes and expects encoded Response bytes back.
     pub(super) fn bind_on_dispatch(&mut self, proc_value: Opaque<Value>) {
@@ -325,9 +325,9 @@ pub(crate) struct MemoryLimitTrap {
 }
 
 impl MemoryLimitTrap {
-    /// Construct a trap with the given +desired+ / +limit+ pair. Used
+    /// Construct a trap with the given `desired` / `limit` pair. Used
     /// internally by `MemoryLimiter::memory_growing` in production and
-    /// by the sibling-module +classify_trap+ unit tests to materialise
+    /// by the sibling-module `classify_trap` unit tests to materialise
     /// a representative error for downcast routing.
     #[cfg(test)]
     pub(super) fn new(desired: usize, limit: usize) -> Self {

data/ext/kobako/src/runtime.rs

@@ -65,9 +65,15 @@ use self::config::Config;
 use self::exports::Exports;
 use self::invocation::{Invocation, StoreCell};
 
-/// Copy the bytes of +s+ into a fresh `Vec<u8>`. Single safe entry to
-/// what would otherwise be an inline +unsafe { rstring.as_slice() }
-/// .to_vec()+ duplicated at every host-↔-guest boundary. The borrow
+/// The wire ABI version this host implements (docs/wire-codec.md § ABI
+/// Version). A Guest Binary is accepted only when its
+/// `__kobako_abi_version` export reports the same value (B-40 / E-42);
+/// the guest-side mirror is `kobako_core::abi::ABI_VERSION`.
+const ABI_VERSION: u32 = 1;
+
+/// Copy the bytes of `s` into a fresh `Vec<u8>`. Single safe entry to
+/// what would otherwise be an inline `unsafe { rstring.as_slice() }
+/// .to_vec()` duplicated at every host-↔-guest boundary. The borrow
 /// does not outlive this call, so no Ruby allocation can move the
 /// underlying RString between the borrow and the copy — the safety
 /// invariant the inline form relied on is established once here.
@@ -86,12 +92,12 @@ pub(crate) fn rstring_to_vec(s: RString) -> Vec<u8> {
 // verb prefix and lets the subclass identity flow through unchanged.
 // ---------------------------------------------------------------------------
 
-/// Resolve `Kobako::<name>` as an +ExceptionClass+ — the shared body of
+/// Resolve `Kobako::<name>` as an `ExceptionClass` — the shared body of
 /// every error-class `Lazy` below, which differ only in the constant
 /// name. The constants are guaranteed present by the time any of these
 /// lazies first resolve (`lib/kobako/errors.rb` loads the hierarchy before
 /// the ext raises into it), so a missing constant is a build / wiring bug
-/// and the +unwrap+ is the correct fail-fast.
+/// and the `unwrap` is the correct fail-fast.
 fn kobako_error_class(ruby: &Ruby, name: &str) -> ExceptionClass {
     let kobako: RModule = ruby.class_object().const_get("Kobako").unwrap();
     kobako.const_get(name).unwrap()
@@ -115,8 +121,8 @@ pub(crate) static MEMORY_LIMIT_ERROR: Lazy<ExceptionClass> =
 pub(crate) static SANDBOX_ERROR: Lazy<ExceptionClass> =
     Lazy::new(|ruby| kobako_error_class(ruby, "SandboxError"));
 
-/// Build a +MagnusError+ in +class+ carrying +msg+ — the shared body of
-/// the named +*_err+ constructors below, which differ only in which
+/// Build a `MagnusError` in `class` carrying `msg` — the shared body of
+/// the named `*_err` constructors below, which differ only in which
 /// error-class `Lazy` they target.
 fn error_in(ruby: &Ruby, class: &Lazy<ExceptionClass>, msg: impl Into<String>) -> MagnusError {
     MagnusError::new(ruby.get_inner(class), msg.into())
@@ -349,6 +355,8 @@ impl Runtime {
                 .map_err(|e| trap::instantiate_err(&ruby, e))?
         };
 
+        Self::validate_abi_version(&instance, &store_cell, &ruby)?;
+
         let exports = Exports::resolve(&instance, &store_cell);
 
         Ok(Self {
@@ -364,9 +372,51 @@ impl Runtime {
         })
     }
 
-    /// Register the Ruby-side dispatch +Proc+ on the active Invocation.
-    /// Bound to Ruby as +Kobako::Runtime#on_dispatch=+. From this point on,
-    /// every +__kobako_dispatch+ host import invocation calls the Proc
+    /// Probe the guest's `__kobako_abi_version` export once at
+    /// construction and require equality with `ABI_VERSION`
+    /// (docs/behavior.md B-40). An absent export or a non-equal value is
+    /// E-42 — a deterministic artifact fault raised as
+    /// `Kobako::SetupError`.
+    fn validate_abi_version(
+        instance: &WtInstance,
+        store: &StoreCell,
+        ruby: &Ruby,
+    ) -> Result<(), MagnusError> {
+        let mut store_ref = store.borrow_mut();
+        let mut ctx = store_ref.as_context_mut();
+        let probe = instance
+            .get_typed_func::<(), u32>(&mut ctx, "__kobako_abi_version")
+            .map_err(|_| {
+                setup_err(
+                    ruby,
+                    format!(
+                        "the Guest Binary does not export __kobako_abi_version; \
+                         rebuild it against ABI version {ABI_VERSION}"
+                    ),
+                )
+            })?;
+        let reported = probe.call(&mut ctx, ()).map_err(|e| {
+            setup_err(
+                ruby,
+                format!("failed to read the Guest Binary's ABI version: {e}"),
+            )
+        })?;
+        if reported != ABI_VERSION {
+            return Err(setup_err(
+                ruby,
+                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(())
+    }
+
+    /// Register the Ruby-side dispatch `Proc` on the active Invocation.
+    /// Bound to Ruby as `Kobako::Runtime#on_dispatch=`. From this point on,
+    /// every `__kobako_dispatch` host import invocation calls the Proc
     /// with the request bytes and writes the returned Response bytes back
     /// into guest memory (docs/behavior.md B-12).
     pub(crate) fn set_on_dispatch(&self, proc_value: Value) -> Result<(), MagnusError> {
@@ -390,14 +440,14 @@ impl Runtime {
     /// export with `args_bytes` as the yield-arguments payload, and
     /// return the YieldResponse bytes the guest produced (B-24).
     ///
-    /// Bound to Ruby as +Kobako::Runtime#yield_to_active_invocation+.
+    /// Bound to Ruby as `Kobako::Runtime#yield_to_active_invocation`.
     /// Recovers the dispatcher's `&mut Caller` from the per-thread
     /// Invocation slot (SPEC.md Single-Invocation Slot) — the host is
     /// already inside a `__kobako_dispatch` callback, so the Caller
     /// parked on the Rust stack is the same one the Sandbox-level
     /// `#eval` / `#run` is driving. Invoked from the host-side yield
     /// proxy that the dispatcher hands to Service methods (B-23 / B-24);
-    /// raises +Kobako::TrapError+ when called outside an active dispatch
+    /// raises `Kobako::TrapError` when called outside an active dispatch
     /// frame, or when any of the underlying allocation / write / call /
     /// read steps fails.
     pub(crate) fn yield_to_active_invocation(
@@ -432,8 +482,8 @@ impl Runtime {
     /// and return a `Snapshot` bundling every per-invocation observable.
     ///
     /// Rebuilds the WASI context with fresh stdin / stdout / stderr pipes
-    /// (the three-frame stdin protocol carries +preamble+, +source+, then
-    /// +snippets+ — docs/wire-codec.md § Invocation channels), then
+    /// (the three-frame stdin protocol carries `preamble`, `source`, then
+    /// `snippets` — docs/wire-codec.md § Invocation channels), then
     /// invokes `__kobako_eval`. Per-invocation caps (docs/behavior.md
     /// B-01) are primed here: the wall-clock deadline is stamped into
     /// `Invocation` and the epoch deadline is set to fire at the next
@@ -467,10 +517,10 @@ impl Runtime {
     ///
     /// Rebuilds the WASI context with the two-frame stdin protocol
     /// (preamble + snippets; no user source frame — docs/wire-codec.md
-    /// § Invocation channels), copies +envelope+ bytes into guest linear
+    /// § Invocation channels), copies `envelope` bytes into guest linear
     /// memory via `__kobako_alloc`, and calls `__kobako_run(env_ptr,
     /// env_len)`. Per-invocation cap semantics match `Runtime::eval`.
-    /// Raises +Kobako::TrapError+ ("alloc returned 0") when guest
+    /// Raises `Kobako::TrapError` ("alloc returned 0") when guest
     /// allocation fails (docs/behavior.md E-31).
     pub(crate) fn run(
         &self,
@@ -596,7 +646,7 @@ impl Runtime {
     /// The mruby image's declared initial allocation and the high-water
     /// mark left by prior invocations on the same Sandbox are folded
     /// into the baseline rather than the budget — only `memory.grow`
-    /// past +baseline+ counts against `memory_limit`.
+    /// past `baseline` counts against `memory_limit`.
     ///
     /// Also stamps the wall-clock entry instant for the
     /// docs/behavior.md B-35 `wall_time` measurement. The bracket
@@ -636,11 +686,11 @@ impl Runtime {
         store_ref.data_mut().disarm_memory_cap();
     }
 
-    /// Allocate a +len+-byte buffer in guest linear memory via
-    /// `__kobako_alloc`, copy +envelope+ into it, and return +(ptr, len)+
-    /// as +i32+ values matching the `__kobako_run(env_ptr, env_len)` ABI.
-    /// Raises +Kobako::TrapError+ when the allocation hook is missing or
-    /// itself traps, and +Kobako::SandboxError+ when the hook runs but
+    /// Allocate a `len`-byte buffer in guest linear memory via
+    /// `__kobako_alloc`, copy `envelope` into it, and return `(ptr, len)`
+    /// as `i32` values matching the `__kobako_run(env_ptr, env_len)` ABI.
+    /// Raises `Kobako::TrapError` when the allocation hook is missing or
+    /// itself traps, and `Kobako::SandboxError` when the hook runs but
     /// cannot reserve the buffer (`__kobako_alloc` returns 0,
     /// docs/behavior.md E-31) — an intact runtime, not an engine fault.
     fn write_envelope(&self, ruby: &Ruby, envelope: RString) -> Result<(i32, i32), MagnusError> {
@@ -676,10 +726,10 @@ impl Runtime {
     }
 
     /// Rebuild the WASI context with fresh stdin (carrying every frame in
-    /// +frames+, each prefixed by its 4-byte big-endian u32 length —
+    /// `frames`, each prefixed by its 4-byte big-endian u32 length —
     /// docs/wire-codec.md § Invocation channels) plus fresh stdout / stderr
-    /// pipes. Called at the top of every guest invocation: +#eval+ passes
-    /// three frames (preamble, source, snippets), +#run+ passes two
+    /// pipes. Called at the top of every guest invocation: `#eval` passes
+    /// three frames (preamble, source, snippets), `#run` passes two
     /// (preamble, snippets — the invocation envelope arrives via linear
     /// memory instead). Each output pipe is sized at `cap + 1` so
     /// `capture::clip_capture` can distinguish "wrote exactly cap
@@ -712,10 +762,10 @@ impl Runtime {
             .install_wasi(wasi, stdout_pipe, stderr_pipe);
     }
 
-    /// Invoke `__kobako_take_outcome`, decode the packed +(ptr<<32)|len+
+    /// Invoke `__kobako_take_outcome`, decode the packed `(ptr<<32)|len`
     /// u64, and copy the OUTCOME_BUFFER slice out of guest memory. Raises
-    /// `Kobako::TrapError` when the export is missing, +len+ exceeds the
-    /// 16 MiB single-dispatch cap, the +ptr+/+len+ arithmetic overflows,
+    /// `Kobako::TrapError` when the export is missing, `len` exceeds the
+    /// 16 MiB single-dispatch cap, the `ptr`/`len` arithmetic overflows,
     /// the slice falls outside live memory, or the `memory` export itself
     /// is absent.
     fn fetch_outcome_bytes(&self, ruby: &Ruby) -> Result<Vec<u8>, MagnusError> {
@@ -762,10 +812,10 @@ const SANDBOX_RUNTIME_MISSING_HOOKS: &str = "Sandbox runtime is missing required
 const SANDBOX_RUNTIME_NOT_KOBAKO: &str =
     "the loaded Wasm module is not a Kobako-compatible runtime";
 
-/// Return the cached +TypedFunc+ for an ABI export, or raise
-/// +Kobako::TrapError+ when the option is +None+. Both run-path
-/// methods (+#eval+, +#run+) plus the +build_snapshot+ readout that
-/// drains +OUTCOME_BUFFER+ share the same "missing export → Ruby
+/// Return the cached `TypedFunc` for an ABI export, or raise
+/// `Kobako::TrapError` when the option is `None`. Both run-path
+/// methods (`#eval`, `#run`) plus the `build_snapshot` readout that
+/// drains `OUTCOME_BUFFER` share the same "missing export → Ruby
 /// error" boilerplate; this helper collapses those sites onto one
 /// safe entry. The user-facing message is intentionally export-
 /// agnostic (see `SANDBOX_RUNTIME_MISSING_HOOKS`) — the ABI symbol

data/lib/kobako/catalog/namespaces.rb

@@ -28,7 +28,7 @@ module Kobako
     # installs ({docs/behavior.md B-12}[link:../../../docs/behavior.md]).
     # The registry holds an injected +Catalog::Handles+ reference so
     # dispatch target resolution and host→guest auto-wrap share the same
-    # Sandbox-owned allocator (docs/behavior.md B-19).
+    # Sandbox-owned allocator ({docs/behavior.md B-19}[link:../../../docs/behavior.md]).
     class Namespaces
       # Build a fresh registry. +handler+ is an internal seam that injects
       # a pre-configured +Catalog::Handles+; tests pass one whose +next_id+
@@ -40,7 +40,8 @@ module Kobako
         @sealed = false
       end
 
-      # Declare or retrieve the Namespace named +name+ (idempotent — docs/behavior.md B-10).
+      # Declare or retrieve the Namespace named +name+ (idempotent —
+      # {docs/behavior.md B-10}[link:../../../docs/behavior.md]).
       # +name+ is a constant-form name as a +Symbol+ or +String+ (must satisfy
       # +Namespace::NAME_PATTERN+). Returns the +Kobako::Namespace+ for that
       # name, creating it if it does not exist. Raises +ArgumentError+ when

data/lib/kobako/codec/factory.rb

@@ -77,9 +77,7 @@ module Kobako
         )
       end
 
-      # Symbol-to-name packer — extracted to a real method so Steep can
-      # resolve the proc shape without tripping on +lambda(&:name)+'s
-      # +Symbol#to_proc+ inference path.
+      # Symbol-to-name packer for the ext-0x00 registration.
       def pack_symbol(symbol)
         symbol.name
       end
@@ -148,8 +146,7 @@ module Kobako
       # method when a nested ext 0x02 appears inside +details+. The recursion
       # is bounded by msgpack nesting depth — identical to nested Array /
       # Hash payloads — so no extra guard is needed. Do not switch back to
-      # +factory.load+ to "simplify": that path bypasses UTF-8 validation
-      # and re-opens the Decoder's special case for Fault (removed in M5).
+      # +factory.load+ to "simplify": that path bypasses UTF-8 validation.
       def unpack_fault(payload)
         Decoder.decode(payload) do |map|
           raise InvalidType, "Fault payload must be a map" unless map.is_a?(Hash)

data/lib/kobako/codec/utils.rb

@@ -43,14 +43,12 @@ module Kobako
       # stays {Kobako::Codec::Error} and never leaks +ArgumentError+ from
       # the Ruby standard library.
       #
-      # Most construction sites no longer reach for this directly: a value
-      # object built inside a {Decoder.decode} block has its
-      # +ArgumentError+ mapped to {InvalidType} by the decoder's own
-      # rescue. The lone remaining caller is {Factory#unpack_handle}, which
-      # builds +Handle.restore+ from a raw 4-byte fixext payload without a
-      # {Decoder.decode} call. Do not use it for general-purpose validation
-      # outside the codec boundary — host-layer +ArgumentError+ values
-      # should propagate unchanged.
+      # Reach for this only where a value object is constructed outside a
+      # {Decoder.decode} block, whose rescue already performs the same
+      # mapping (worked example: {Factory#unpack_handle} building
+      # +Handle.restore+ from a raw fixext payload). Do not use it for
+      # general-purpose validation outside the codec boundary —
+      # host-layer +ArgumentError+ values should propagate unchanged.
       def with_boundary
         yield
       rescue ::ArgumentError => e
@@ -143,8 +141,7 @@ module Kobako
         end
       end
 
-      # Predicate split out of {representable?} for cyclomatic
-      # budget — the closed-set non-container branch. Returns +true+ for
+      # The non-container branch of {representable?}: returns +true+ for
       # the scalar leaves and an existing Handle. Not part of the
       # public surface; reach for {representable?} instead.
       def primitive_type?(value)
@@ -155,11 +152,10 @@ module Kobako
         end
       end
 
-      # Predicate split out of {representable?} for cyclomatic
-      # budget — the container branch. Recurses into Array elements and
-      # Hash key+value pairs through the public {representable?}.
-      # Not part of the public surface; reach for {representable?}
-      # instead.
+      # The container branch of {representable?}: recurses into Array
+      # elements and Hash key+value pairs through the public
+      # {representable?}. Not part of the public surface; reach for
+      # {representable?} instead.
       def container_representable?(value)
         case value
         when ::Array then value.all? { |element| Utils.representable?(element) }

data/lib/kobako/errors.rb

@@ -26,9 +26,9 @@ module Kobako
   #   * {SetupError}    — construction layer. Raised by `Kobako::Sandbox.new`
   #                       when the wasm runtime cannot be built from the
   #                       configured +wasm_path+ before any invocation runs
-  #                       (docs/behavior.md E-40 / E-41). Not an invocation
-  #                       outcome, so it never passes through the two-step
-  #                       attribution decision.
+  #                       ({docs/behavior.md E-40 / E-41}[link:../../docs/behavior.md]).
+  #                       Not an invocation outcome, so it never passes
+  #                       through the two-step attribution decision.
   #
   # Subclasses pinned by docs/behavior.md Error Classes:
   #

data/lib/kobako/fault.rb

@@ -22,10 +22,8 @@ module Kobako
   # exception class (RuntimeError, ArgumentError, Kobako::ServiceError, ...)
   # is the responsibility of the dispatch layer, not the codec.
   #
-  # Built on the +class X < Data.define(...)+ subclass form so the
-  # class body is fully Steep-visible; ruby/rbs upstream documents
-  # this as the Steep-friendly shape and the +Style/DataInheritance+
-  # cop is disabled on that basis (see +.rubocop.yml+).
+  # Built on the +class X < Data.define(...)+ subclass form (the
+  # Steep-friendly shape — see +lib/kobako/outcome/panic.rb+).
   class Fault < Data.define(:type, :message, :details)
     VALID_TYPES = %w[runtime argument undefined].freeze
 

data/lib/kobako/sandbox.rb

@@ -292,9 +292,9 @@ module Kobako
     #
     # The yielded block must return a +Kobako::Snapshot+ — i.e. the
     # value of +Runtime#eval+ / +#run+ (SPEC.md Internal Concepts →
-    # Snapshot). The success path unpacks every observable from the
-    # Snapshot in one go: +#stdout+ / +#stderr+ pack into +Capture+,
-    # +#usage+ packs into +Usage+, +#return_bytes+ feeds +Outcome.decode+.
+    # Snapshot). The success path unpacks +#stdout+ / +#stderr+ into
+    # +Capture+ and feeds +#return_bytes+ to +Outcome.decode+; usage is
+    # populated by the +ensure+ readout ({#read_usage!}) on every outcome.
     # The rescue chain is the single trap-translation boundary —
     # configured-cap paths
     # ({docs/behavior.md E-19 / E-20}[link:../../docs/behavior.md])

data/lib/kobako/transport/dispatcher.rb

@@ -117,7 +117,7 @@ module Kobako
         end
       end
 
-      # {docs/behavior.md B-16}[link:../../../docs/behavior.md] — An Kobako::Handle arriving as a positional or keyword
+      # {docs/behavior.md B-16}[link:../../../docs/behavior.md] — A Kobako::Handle arriving as a positional or keyword
       # argument identifies a host-side object previously allocated by a prior
       # transport call's Handle wrap (B-14). Resolve it back to the Ruby object before
       # the dispatch reaches +public_send+.

data/lib/kobako/usage.rb

@@ -28,10 +28,8 @@ module Kobako
   # consumed. Before the first invocation +Sandbox#usage+ returns the
   # pre-invocation sentinel +Kobako::Usage::EMPTY+.
   #
-  # Built on the +class X < Data.define(...)+ subclass form so the
-  # class body is fully Steep-visible; ruby/rbs upstream documents this
-  # as the Steep-friendly shape and the +Style/DataInheritance+ cop is
-  # disabled on that basis (see +.rubocop.yml+).
+  # Built on the +class X < Data.define(...)+ subclass form (the
+  # Steep-friendly shape — see +lib/kobako/outcome/panic.rb+).
   class Usage < Data.define(:wall_time, :memory_peak)
     # Pre-invocation sentinel ({docs/behavior.md B-35}[link:../../docs/behavior.md]).
     # Reused by +Sandbox+ before any invocation has run so callers do not

data/lib/kobako/version.rb

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

data/release-please-config.json

@@ -6,9 +6,82 @@
     ".": {
       "component": "kobako",
       "include-component-in-tag": false,
-      "release-type": "ruby"
+      "release-type": "ruby",
+      "exclude-paths": ["wasm"]
+    },
+    "wasm/kobako-core": {
+      "component": "kobako-core",
+      "release-type": "rust",
+      "extra-files": [
+        {
+          "type": "toml",
+          "path": "/wasm/Cargo.lock",
+          "jsonpath": "$.package[?(@.name=='kobako-core')].version"
+        },
+        {
+          "type": "generic",
+          "path": "/wasm/kobako-core/README.md"
+        }
+      ]
+    },
+    "wasm/kobako": {
+      "component": "kobako-rs",
+      "release-type": "rust",
+      "extra-files": [
+        {
+          "type": "toml",
+          "path": "/wasm/Cargo.lock",
+          "jsonpath": "$.package[?(@.name=='kobako')].version"
+        },
+        {
+          "type": "toml",
+          "path": "/wasm/kobako/Cargo.toml",
+          "jsonpath": "$.dependencies['kobako-core'].version"
+        },
+        {
+          "type": "generic",
+          "path": "/wasm/kobako/README.md"
+        }
+      ]
+    },
+    "wasm/kobako-io": {
+      "component": "kobako-io",
+      "release-type": "rust",
+      "extra-files": [
+        {
+          "type": "toml",
+          "path": "/wasm/Cargo.lock",
+          "jsonpath": "$.package[?(@.name=='kobako-io')].version"
+        },
+        {
+          "type": "generic",
+          "path": "/wasm/kobako-io/README.md"
+        }
+      ]
+    },
+    "wasm/kobako-regexp": {
+      "component": "kobako-regexp",
+      "release-type": "rust",
+      "extra-files": [
+        {
+          "type": "toml",
+          "path": "/wasm/Cargo.lock",
+          "jsonpath": "$.package[?(@.name=='kobako-regexp')].version"
+        },
+        {
+          "type": "generic",
+          "path": "/wasm/kobako-regexp/README.md"
+        }
+      ]
     }
   },
+  "plugins": [
+    {
+      "type": "linked-versions",
+      "groupName": "kobako guest crates",
+      "components": ["kobako-core", "kobako-rs", "kobako-io", "kobako-regexp"]
+    }
+  ],
   "extra-files": [
     {
       "type": "toml",

data/rust-toolchain.toml

@@ -1,7 +1,8 @@
 # Pin the Rust toolchain so local builds and CI stay byte-identical.
 # The wasm32-wasip1 crt1-command.o references __wasi_init_tp from 1.96 onward;
 # vendored wasi-sdk 33's libc.a supplies that symbol, so the two move together.
-# Bump this in lockstep with WASI_SDK_VERSION in tasks/support/kobako_vendor.rb.
+# Bump this in lockstep with the wasi-sdk toolchain beni vendors
+# (`rake beni:build`, wired in the Rakefile's Beni::Tasks block).
 # This file is the single source of the channel; the CI workflows read it.
 [toolchain]
 channel = "1.96.0"

data/sig/kobako/codec.rbs

@@ -0,0 +1,4 @@
+module Kobako
+  module Codec
+  end
+end

data/sig/kobako/version.rbs

@@ -0,0 +1,3 @@
+module Kobako
+  VERSION: String
+end

data/sig/kobako.rbs

@@ -1,3 +1,2 @@
 module Kobako
-  VERSION: String
 end