kobako 0.9.2 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3177d01c5cb742a539ac9713226c17c159299911344b1590a680aacd99aa70fd
-  data.tar.gz: 6f9a4503a56855076b1f5d83725775669ae4c34283b24bcb8467485509e26c03
+  metadata.gz: f94d5012ea43dae1d5bd51d2b8f0f6c7357edc259c7771577d3454c7055a5f1d
+  data.tar.gz: 494087c5769aa0ce019ac47d705a1426fb237840ab3c88700afdcc970816b43d
 SHA512:
-  metadata.gz: b8f0f15f5c76c54b785e109ca6f7c10a37ebc7394d49f05637b18ace67a1326f941aa0a03ee99b985d8b09b70c39ba42c8318f9dd4fe885dba530472e5b24c81
-  data.tar.gz: 794e0c2f476fceaee007fbeb1c8082accd8d1de2de682aa333606bc0ab6593ed281abda277222ca51d58a88f2663d37220e8068891396565221ecc694bdc2b68
+  metadata.gz: 9cd941922d385068bcb6e78849f5d43dc68e8bc36e2a6a04b245e406c488a2313cffc697441f69c2f76f3ea154924c67e594271009308702aa4f72c514bc0983
+  data.tar.gz: 5a3b07b25b6ea434f69731749c5756d802aa585d2f10cdb3097dafdaf442d1d1da61a1c338cbb0eb3506915d2ba968baf7906607ec97059f1da5ac1070cd6950

data/.release-please-manifest.json

@@ -1 +1 @@
-{".":"0.9.2","wasm/kobako-core":"0.4.1","wasm/kobako":"0.4.1","wasm/kobako-io":"0.4.1","wasm/kobako-regexp":"0.4.1"}
+{".":"0.10.0","wasm/kobako-core":"0.5.0","wasm/kobako":"0.5.0","wasm/kobako-io":"0.5.0","wasm/kobako-regexp":"0.5.0","wasm/kobako-baker":"0.5.0"}

data/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## [0.10.0](https://github.com/elct9620/kobako/compare/v0.9.2...v0.10.0) (2026-06-12)
+
+
+### Features
+
+* **catalog:** reject member binding after the seal (E-45) ([5193ed6](https://github.com/elct9620/kobako/commit/5193ed64100fa8ac05a2ba18cfa00634b4f40e6f))
+* **guest:** bake the canonical boot state and instantiate per invocation (B-49) ([ee9ae6e](https://github.com/elct9620/kobako/commit/ee9ae6e09eab30f54dba0eeec00a5a2c80da819f))
+* **pool:** add Kobako::Pool warm-Sandbox checkout (B-46..B-48) ([abf9bf8](https://github.com/elct9620/kobako/commit/abf9bf8d3c725c0ca0b8f2ab8b2ddd6f71ee6de4))
+
+
+### Bug Fixes
+
+* **ext:** give the ABI probe a WASI context ([18e21ea](https://github.com/elct9620/kobako/commit/18e21eac8b160ade2724578aeacd86170403ee2c))
+* **ext:** trust the artifact disk cache only in an exclusively writable directory ([17679cc](https://github.com/elct9620/kobako/commit/17679cc0d38d2a1b605e2faaeed762477a718c18))
+
+
+### Performance Improvements
+
+* **bench:** re-bless the anchor onto the post-0.9.2 performance round ([195224d](https://github.com/elct9620/kobako/commit/195224d5d48e53dc2be17752e6d6af6382a0c1ec))
+* **catalog:** drop the alloc-path block iteration from the gadget refusal ([542fe59](https://github.com/elct9620/kobako/commit/542fe59464bde57283d8e91984b82e82592bc3ab))
+* **ext:** amortise module compilation across processes via .cwasm cache ([2e688bc](https://github.com/elct9620/kobako/commit/2e688bc4a1cdf1d0d4d5a0bce2efb314a5b8d1f7))
+* **ext:** bound and harden the compiled-artifact cache ([949f222](https://github.com/elct9620/kobako/commit/949f2227af7cdf7d1913dcae58df683912a7dbd5))
+* **ext:** cache ABI export handles and per-path InstancePre ([47573d0](https://github.com/elct9620/kobako/commit/47573d022233c788ce94413d1a2901ee9d62fc2e))
+* **lib:** cache sealed frame encodings and cut decode-walk allocations ([e599573](https://github.com/elct9620/kobako/commit/e599573e37531b363baca83a1aa5833930100320))
+
 ## [0.9.2](https://github.com/elct9620/kobako/compare/v0.9.1...v0.9.2) (2026-06-11)
 
 

data/Cargo.lock

@@ -878,9 +878,11 @@ dependencies = [
 
 [[package]]
 name = "kobako"
-version = "0.9.2"
+version = "0.10.0"
 dependencies = [
+ "libc",
  "magnus",
+ "sha2",
  "wasmtime",
  "wasmtime-wasi",
 ]

data/README.md

@@ -179,7 +179,8 @@ One Sandbox serves many invocations. Service bindings and preloaded snippets per
 
    ──────────────── invocation N ───────────────────
 
-     1. allocate fresh mrb_state
+     1. start from the canonical boot state
+        (mruby pre-initialized into the artifact at build time)
 
      2. replay snippets (in insertion order):
           :Adder     → defines Adder
@@ -189,7 +190,7 @@ One Sandbox serves many invocations. Service bindings and preloaded snippets per
 
      4. return value to host
 
-     5. discard mrb_state; reset per-invocation state:
+     5. discard the instance; reset per-invocation state:
           · Handles invalidated
           · stdout / stderr buffers cleared
           · memory delta zeroed
@@ -199,6 +200,25 @@ One Sandbox serves many invocations. Service bindings and preloaded snippets per
 
 For workloads that must be isolated from each other (one Sandbox per tenant, per student submission, per agent session), construct a fresh `Kobako::Sandbox` per scope — wasmtime's Engine and the compiled Module are cached at process scope, so additional Sandboxes amortize cold-start cost automatically.
 
+### Pooling
+
+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.md`](docs/behavior.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.
+
+```ruby
+pool = Kobako::Pool.new(slots: 4) do |sandbox|
+  sandbox.define(:KV).bind(:Lookup, ->(key) { redis.get(key) })
+end
+
+pool.with { |sandbox| sandbox.eval(%(KV::Lookup.call("user_42"))) }
+```
+
+| Option | Meaning | Default |
+|--------|---------|---------|
+| `slots:` | Upper bound on constructed Sandboxes | required |
+| `checkout_timeout:` | Seconds `#with` waits for a free Sandbox; `nil` waits indefinitely | 5.0 |
+
+Sandboxes construct lazily on first demand. `#with` yields a Sandbox with empty output buffers and returns the block's value; at block exit the Sandbox returns to the pool, except a block that raises `Kobako::TrapError` discards its Sandbox and the slot refills by a fresh construction on next demand. A checkout that waits past `checkout_timeout` raises `Kobako::PoolTimeoutError`. There is no teardown verb — a Pool releases everything with its own reachability.
+
 ### Service Blocks
 
 A Service method can accept a guest-supplied block via `&blk` and `yield` into it. The block body runs inside the Wasm guest; `break` / `next` / exceptions follow normal Ruby semantics, scoped to the single dispatch. See [`docs/behavior.md`](docs/behavior.md) B-23..B-30.
@@ -248,7 +268,7 @@ This is deliberate, not a leak. Handle IDs run to 2³¹ − 1 per invocation and
 
 ### Snippets & Entrypoints
 
-`Sandbox#preload` registers named mruby snippets that replay against the fresh `mrb_state` before every invocation; `Sandbox#run(:Target, *args, **kwargs)` dispatches into a top-level `Object` constant defined by those snippets ([`docs/behavior.md`](docs/behavior.md) B-31..B-33).
+`Sandbox#preload` registers named mruby snippets that replay into every invocation's canonical boot state; `Sandbox#run(:Target, *args, **kwargs)` dispatches into a top-level `Object` constant defined by those snippets ([`docs/behavior.md`](docs/behavior.md) B-31..B-33).
 
 ```ruby
 sandbox = Kobako::Sandbox.new
@@ -262,7 +282,7 @@ sandbox.run(:Greeter, name: "world") # => "hello, world"
 ```
    per-invocation replay (every #eval / #run, snippets in insertion order):
 
-      fresh mrb_state
+      canonical boot state
             │
             ├──▶ replay :Adder            (defines Adder)
             │
@@ -271,7 +291,7 @@ sandbox.run(:Greeter, name: "world") # => "hello, world"
             └──▶ eval(source)  -or-  run(:Target, *args, **kwargs)
                        │
                        ▼
-                  return value, then mrb_state discarded
+                  return value, then instance discarded
 ```
 
 `#preload` accepts two payload forms:
@@ -312,15 +332,16 @@ Order-of-magnitude figures on macOS arm64, Ruby 3.4.7, YJIT off. Absolute values
 
 | Phase                                                        | Cost                  |
 |--------------------------------------------------------------|-----------------------|
-| First `Sandbox.new` in a fresh process (Engine + Module JIT) | ~600 ms one-time      |
-| Subsequent `Sandbox.new` (Engine cache warm)                 | ~125 µs               |
-| Warm `#eval("nil")` on a reused Sandbox                      | ~135 µs               |
-| Warm `#run(:Entrypoint, ...)` dispatch                       | ~165 µs               |
-| Service call amortized inside one invocation                 | ~6.7 µs               |
-| Snippet replay per invocation                                | ~7-9 µs each          |
-| Per additional Sandbox (RSS)                                 | ~570 KB               |
-
-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.
+| 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) | ~5 ms one-time        |
+| Subsequent `Sandbox.new` (caches warm)                       | ~30 µs                |
+| Warm `#eval("nil")` on a reused Sandbox                      | ~73 µs                |
+| Warm `#run(:Entrypoint, ...)` dispatch                       | ~104 µs               |
+| Service call amortized inside one invocation                 | ~6.8 µs               |
+| Snippet replay per invocation                                | ~8 µ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 ~32 MB total. `ext/` does not release the GVL during wasmtime execution, so wasm work is GVL-serialized: aggregate throughput stays around 16k `#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.
 

data/ext/kobako/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "kobako"
-version = "0.9.2"
+version = "0.10.0"
 edition = "2021"
 authors = ["Aotokitsuruya <contact@aotoki.me>"]
 license = "Apache-2.0"
@@ -32,3 +32,13 @@ wasmtime = { version = "45.0.0", default-features = false, features = [
 # `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 runtime/cache.rs); a collision would load the wrong artifact, so
+# the hash must be cryptographic.
+sha2 = "0.10"
+
+# libc supplies geteuid for the cache-directory ownership check gating
+# the unsafe artifact deserialize (see runtime/cache.rs); std exposes a
+# file's owner but not the process's effective uid.
+[target.'cfg(unix)'.dependencies]
+libc = "0.2"

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

@@ -1,5 +1,5 @@
 //! Process-wide caches for the wasmtime `Engine` and compiled
-//! `Module`.
+//! `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
@@ -9,19 +9,26 @@
 //! Ruby callers, who construct a `Runtime` via
 //! `Kobako::Runtime.from_path(...)` 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
+//! Binary bytes (docs/behavior.md B-01); every cache failure falls
+//! back to in-process compilation.
+//!
 //! Concurrency: under Ruby's GVL only one thread can execute Rust code
 //! at a time, so the Mutex is held briefly during HashMap insert/lookup
 //! and serves to satisfy `Sync` bounds rather than to arbitrate real
 //! contention.
 
 use std::collections::HashMap;
+use std::fmt::Write as _;
 use std::fs;
 use std::path::{Path, PathBuf};
 use std::sync::{Mutex, OnceLock};
 use std::thread;
-use std::time::Duration;
+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::{setup_err, MODULE_NOT_BUILT_ERROR};
@@ -124,11 +131,168 @@ pub(crate) fn cached_module(path: &Path) -> Result<WtModule, MagnusError> {
             ),
         )
     })?;
-    let module = WtModule::new(shared_engine()?, &bytes)
-        .map_err(|e| setup_err(&ruby, format!("failed to compile Sandbox runtime: {}", e)))?;
+    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))
+            })?;
+            if let Some(p) = artifact.as_deref() {
+                store_artifact(&module, p);
+            }
+            module
+        }
+    };
     cache
         .lock()
         .expect("module cache mutex poisoned")
         .insert(path.to_path_buf(), module.clone());
     Ok(module)
 }
+
+/// Retention window for unused cache entries. A hit refreshes the
+/// artifact's mtime, so only entries no process has loaded for the
+/// whole window are removed by `prune_stale`.
+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`.
+/// 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
+/// 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.
+fn artifact_path(wasm_bytes: &[u8]) -> Option<PathBuf> {
+    let base = std::env::var_os("XDG_CACHE_HOME")
+        .map(PathBuf::from)
+        .or_else(|| std::env::var_os("HOME").map(|home| PathBuf::from(home).join(".cache")))?;
+    let digest = Sha256::digest(wasm_bytes);
+    let mut name = String::with_capacity(80);
+    for byte in digest {
+        let _ = write!(name, "{:02x}", byte);
+    }
+    let _ = write!(name, "-{}.cwasm", env!("CARGO_PKG_VERSION"));
+    Some(base.join("kobako").join(name))
+}
+
+/// Best-effort load of a previously serialized compiled artifact.
+/// Any failure — absent file, truncated bytes, wasmtime version or
+/// Config mismatch — returns `None` and the caller recompiles. A hit
+/// refreshes the file's mtime so `prune_stale`'s retention window
+/// measures time since last use, not since creation.
+fn load_artifact(engine: &WtEngine, artifact: &Path) -> Option<WtModule> {
+    if !artifact.exists() || !artifact.parent().is_some_and(dir_is_private) {
+        return None;
+    }
+    // SAFETY: `Module::deserialize_file` trusts the artifact bytes.
+    // `dir_is_private` just verified the cache directory is owned by
+    // the current user and writable by no one else, so only files this
+    // module wrote are loaded, addressed by the content hash of the
+    // Guest Binary being constructed — the artifact carries exactly
+    // the trust of `data/kobako.wasm`.
+    let module = unsafe { WtModule::deserialize_file(engine, artifact) }.ok()?;
+    let _ = fs::File::options()
+        .append(true)
+        .open(artifact)
+        .and_then(|f| f.set_modified(SystemTime::now()));
+    Some(module)
+}
+
+/// Best-effort write of a freshly compiled artifact. The temp-file +
+/// rename pair keeps concurrent processes from observing a partial
+/// write; every failure is swallowed because the cache is purely an
+/// optimisation. A successful write also triggers `prune_stale` so the
+/// cache directory cannot grow without bound across Guest Binary
+/// rebuilds.
+fn store_artifact(module: &WtModule, artifact: &Path) {
+    let Ok(bytes) = module.serialize() else {
+        return;
+    };
+    let Some(dir) = artifact.parent() else { return };
+    if create_cache_dir(dir).is_err() || !dir_is_private(dir) {
+        return;
+    }
+    let tmp = artifact.with_extension(format!("tmp{}", std::process::id()));
+    if fs::write(&tmp, bytes).is_err() {
+        return;
+    }
+    if fs::rename(&tmp, artifact).is_ok() {
+        prune_stale(dir, artifact);
+    }
+}
+
+/// Create the cache directory owner-only (`0700`) on Unix so no other
+/// local user can plant an artifact the unsafe deserialize would
+/// trust; elsewhere fall back to default permissions.
+#[cfg(unix)]
+fn create_cache_dir(dir: &Path) -> std::io::Result<()> {
+    use std::os::unix::fs::DirBuilderExt;
+    fs::DirBuilder::new()
+        .recursive(true)
+        .mode(0o700)
+        .create(dir)
+}
+
+#[cfg(not(unix))]
+fn create_cache_dir(dir: &Path) -> std::io::Result<()> {
+    fs::create_dir_all(dir)
+}
+
+/// Returns whether the cache directory upholds the trust the unsafe
+/// deserialize relies on: owned by the current effective user and
+/// writable by no one else. A pre-existing directory another user owns
+/// or can write to — e.g. under a shared `XDG_CACHE_HOME` — fails here
+/// and both disk-cache tiers are skipped.
+#[cfg(unix)]
+fn dir_is_private(dir: &Path) -> bool {
+    use std::os::unix::fs::MetadataExt;
+    let Ok(meta) = fs::metadata(dir) else {
+        return false;
+    };
+    // SAFETY: `geteuid` reads process state and has no preconditions.
+    meta.uid() == unsafe { libc::geteuid() } && meta.mode() & 0o022 == 0
+}
+
+#[cfg(not(unix))]
+fn dir_is_private(_dir: &Path) -> bool {
+    true
+}
+
+/// Remove every cache entry (`.cwasm` artifacts and crash-leftover
+/// `.tmp*` files) whose mtime sits past `ARTIFACT_TTL`, except the
+/// just-written `keep`. Live temp files are seconds old and never
+/// qualify; foreign file names are left untouched.
+fn prune_stale(dir: &Path, keep: &Path) {
+    let Ok(entries) = fs::read_dir(dir) else {
+        return;
+    };
+    for entry in entries.flatten() {
+        let path = entry.path();
+        if path == keep || !cache_entry_name(&path) {
+            continue;
+        }
+        let stale = entry
+            .metadata()
+            .and_then(|meta| meta.modified())
+            .ok()
+            .and_then(|mtime| mtime.elapsed().ok())
+            .is_some_and(|age| age > ARTIFACT_TTL);
+        if stale {
+            let _ = fs::remove_file(&path);
+        }
+    }
+}
+
+/// Returns whether `path` carries a file name this cache wrote — a
+/// `.cwasm` artifact or a `.tmp*` leftover.
+fn cache_entry_name(path: &Path) -> bool {
+    let Some(name) = path.file_name().and_then(|n| n.to_str()) else {
+        return false;
+    };
+    name.ends_with(".cwasm") || name.contains(".tmp")
+}

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

@@ -2,7 +2,7 @@
 //!
 //! When the guest invokes the wasm import declared in
 //! `wasm/kobako-core/src/abi.rs`, wasmtime calls back into the host
-//! through the closure built in `super::Runtime::build`.
+//! through the closure registered by `instance_pre::build_linker`.
 //! That closure delegates here. The dispatcher (docs/behavior.md B-12 / B-13):
 //!
 //!   1. Reads the Request bytes from guest linear memory.
@@ -129,7 +129,7 @@ pub(crate) fn current_caller<'a>() -> Option<&'a mut Caller<'a, Invocation>> {
 }
 
 /// Drive a single `__kobako_dispatch` invocation end-to-end. Entry point
-/// from the wasmtime closure built in `super::Runtime::build`.
+/// from the wasmtime closure registered by `instance_pre::build_linker`.
 ///
 /// Returns the packed `(ptr<<32)|len` u64 on success, 0 on any
 /// wire-layer fault. Failure paths log a `[kobako-dispatch]` line to

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

@@ -1,41 +1,48 @@
-//! Cached wasmtime export handles for the host-driven ABI surface.
+//! Per-invocation wasmtime export handles for the host-driven ABI
+//! surface.
 //!
-//! `Runtime::from_path` resolves the three docs/wire-codec.md ABI exports
-//! the run path drives (`__kobako_eval` / `__kobako_run` /
-//! `__kobako_take_outcome`) once at construction and stores their typed
-//! handles here, so each `#eval` / `#run` calls a cached handle rather than
-//! re-resolving the export by name. Distinct from `super::cache` (the
-//! process-wide Engine / Module cache): this caches *which guest function
-//! to call*, per `Runtime`.
+//! `Runtime::instantiate` resolves the ABI exports the run path drives
+//! (`__kobako_eval` / `__kobako_run` / `__kobako_take_outcome` /
+//! `__kobako_alloc`) plus the `memory` export against each fresh
+//! per-invocation instance (docs/behavior.md B-49) and bundles their
+//! typed handles here, so the invocation body passes one struct around
+//! rather than re-resolving exports by name at every step. Distinct
+//! from `super::cache` (the process-wide Engine / Module cache): this
+//! carries *which guest function to call*, per invocation.
 //!
-//! `__kobako_alloc` is deliberately absent — only `super::dispatch` calls
-//! it, and it does so through `Caller::get_export` on the wasmtime side.
+//! `super::dispatch` does not reach this struct — a host import runs
+//! against a `Caller`, so the dispatch path resolves `__kobako_alloc`
+//! and `memory` through `Caller::get_export` instead.
 
-use wasmtime::{AsContextMut, Instance as WtInstance, TypedFunc};
+use wasmtime::{AsContextMut, Instance as WtInstance, Memory, TypedFunc};
 
-use super::invocation::StoreCell;
-
-/// The cached host-driven export handles. Each is `Option` because test
+/// The resolved host-driven export handles. Each is `Option` because test
 /// fixtures (a minimal "ping" module) need not provide them; real
 /// `kobako.wasm` always does, and the run-path methods raise a Ruby
-/// `Kobako::TrapError` (via `require_export`) when a handle is `None`.
+/// `Kobako::TrapError` (via `require_export` / `require_memory`) when a
+/// handle is `None`.
+///
+/// The handles are indices into the owning Store, not borrows of the
+/// `Instance` — they stay valid for the Store's lifetime, which is why
+/// no `Instance` field is kept.
 pub(crate) struct Exports {
     pub(crate) eval: Option<TypedFunc<(), ()>>,
     pub(crate) run: Option<TypedFunc<(i32, i32), ()>>,
     pub(crate) take_outcome: Option<TypedFunc<(), u64>>,
+    pub(crate) alloc: Option<TypedFunc<u32, u32>>,
+    pub(crate) memory: Option<Memory>,
 }
 
 impl Exports {
-    /// Best-effort lookup of the three host-driven exports against a
-    /// freshly instantiated module. Missing exports are not an error here
+    /// Best-effort lookup of the host-driven exports against a freshly
+    /// instantiated module. Missing exports are not an error here
     /// (the test fixture is a bare module); the host enforces presence at
     /// invocation time. Only the SPEC ABI shapes are accepted —
     /// `__kobako_eval` is `() -> ()`, `__kobako_run` is
-    /// `(env_ptr, env_len) -> ()`, `__kobako_take_outcome` is `() -> u64`
+    /// `(env_ptr, env_len) -> ()`, `__kobako_take_outcome` is `() -> u64`,
+    /// `__kobako_alloc` is `(len) -> ptr`
     /// (docs/wire-codec.md § ABI Signatures).
-    pub(crate) fn resolve(instance: &WtInstance, store: &StoreCell) -> Self {
-        let mut store_ref = store.borrow_mut();
-        let mut ctx = store_ref.as_context_mut();
+    pub(crate) fn resolve(instance: &WtInstance, mut ctx: impl AsContextMut) -> Self {
         Self {
             eval: instance
                 .get_typed_func::<(), ()>(&mut ctx, "__kobako_eval")
@@ -46,6 +53,10 @@ impl Exports {
             take_outcome: instance
                 .get_typed_func::<(), u64>(&mut ctx, "__kobako_take_outcome")
                 .ok(),
+            alloc: instance
+                .get_typed_func::<u32, u32>(&mut ctx, "__kobako_alloc")
+                .ok(),
+            memory: instance.get_memory(&mut ctx, "memory"),
         }
     }
 }

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

@@ -0,0 +1,97 @@
+//! Per-path cache of pre-instantiated wasmtime artifacts.
+//!
+//! The `Linker` wiring (the WASI preview1 import set plus the
+//! `__kobako_dispatch` host import) and its type-check against the
+//! 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 `Runtime.from_path` hot path.
+//!
+//! Concurrency: see `super::cache` — under Ruby's GVL the Mutex serves
+//! `Sync` bounds rather than real contention.
+
+use std::collections::HashMap;
+use std::path::{Path, PathBuf};
+use std::sync::{Mutex, OnceLock};
+
+use magnus::{Error as MagnusError, Ruby};
+use wasmtime::{Caller, InstancePre, Linker};
+use wasmtime_wasi::p1;
+
+use super::cache::{cached_module, shared_engine};
+use super::invocation::Invocation;
+use super::{dispatch, setup_err, trap};
+
+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
+/// raise `Kobako::SetupError` (docs/behavior.md E-41).
+pub(crate) fn cached_instance_pre(path: &Path) -> Result<InstancePre<Invocation>, MagnusError> {
+    let cache = INSTANCE_PRE_CACHE.get_or_init(|| Mutex::new(HashMap::new()));
+
+    if let Some(pre) = cache
+        .lock()
+        .expect("instance_pre cache mutex poisoned")
+        .get(path)
+        .cloned()
+    {
+        return Ok(pre);
+    }
+
+    let module = cached_module(path)?;
+    let linker = build_linker()?;
+    let ruby = Ruby::get().expect("Ruby thread");
+    let pre = linker
+        .instantiate_pre(&module)
+        .map_err(|e| trap::instantiate_err(&ruby, e))?;
+    cache
+        .lock()
+        .expect("instance_pre cache mutex poisoned")
+        .insert(path.to_path_buf(), pre.clone());
+    Ok(pre)
+}
+
+/// Build the host-import `Linker` every Guest Binary instantiates
+/// against.
+fn build_linker() -> Result<Linker<Invocation>, MagnusError> {
+    let ruby = Ruby::get().expect("Ruby thread");
+    let mut linker: Linker<Invocation> = Linker::new(shared_engine()?);
+
+    // Wire the wasmtime-wasi preview1 WASI imports. Routes guest fd 1/2
+    // to the MemoryOutputPipes set up before each run via
+    // `Runtime::eval`. The closure pulls a `&mut WasiP1Ctx` out of
+    // Invocation; the panic semantics live inside `Invocation::wasi_mut`
+    // so the wiring stays honest about its precondition.
+    p1::add_to_linker_sync(&mut linker, |state: &mut Invocation| state.wasi_mut())
+        .map_err(|e| setup_err(&ruby, format!("failed to set up the WASI runtime: {}", e)))?;
+
+    // `__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`.
+    linker
+        .func_wrap(
+            "env",
+            "__kobako_dispatch",
+            |mut caller: Caller<'_, Invocation>, req_ptr: i32, req_len: i32| -> i64 {
+                dispatch::handle(&mut caller, req_ptr, req_len)
+            },
+        )
+        .map_err(|e| {
+            setup_err(
+                &ruby,
+                format!("failed to set up the host callback bridge: {}", e),
+            )
+        })?;
+
+    Ok(linker)
+}