kobako 0.9.2 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3177d01c5cb742a539ac9713226c17c159299911344b1590a680aacd99aa70fd
-  data.tar.gz: 6f9a4503a56855076b1f5d83725775669ae4c34283b24bcb8467485509e26c03
+  metadata.gz: cc8e33cc57bfd43cf4d4e06def6536c8c0d45fd4ccd5bbf04b13a4187db67f0a
+  data.tar.gz: 8656976c144bb23226686b2c8f60830d3fd635f637c52caaa824bd3e168e07f2
 SHA512:
-  metadata.gz: b8f0f15f5c76c54b785e109ca6f7c10a37ebc7394d49f05637b18ace67a1326f941aa0a03ee99b985d8b09b70c39ba42c8318f9dd4fe885dba530472e5b24c81
-  data.tar.gz: 794e0c2f476fceaee007fbeb1c8082accd8d1de2de682aa333606bc0ab6593ed281abda277222ca51d58a88f2663d37220e8068891396565221ecc694bdc2b68
+  metadata.gz: 35258fb35a0accee9beea36f01c4fb6cb2c658a2aefcb3ae4ebb7c17decd4e97f1b35e155121ae77456eed6d529d7ec13195ba43a3bf8a3ad43724d11ae5512b
+  data.tar.gz: 06ea66fd5877fc58fc6e5a21805d434e53968004e8c00577264ca547b10ae7aa4f4196798a3fa18da332fd730cc8fe441ac8e37dbfe2527653fed0da598d8bbf

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.11.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,37 @@
 # Changelog
 
+## [0.11.0](https://github.com/elct9620/kobako/compare/v0.10.0...v0.11.0) (2026-06-13)
+
+
+### Features
+
+* **transport:** narrow guest-reachable methods via respond_to_guest? ([7a25fe3](https://github.com/elct9620/kobako/commit/7a25fe3b440b523b8a692b7601d08877b1305b0d))
+
+## [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.11.0"
 dependencies = [
+ "libc",
  "magnus",
+ "sha2",
  "wasmtime",
  "wasmtime-wasi",
 ]

data/README.md

@@ -69,7 +69,7 @@ The script executes inside the Wasm guest. It cannot read your filesystem, open
 
 ### Services
 
-Declare a Namespace, then `bind` any Ruby object as a Member; the guest reaches it as a `<Namespace>::<Member>` proxy and invokes its public methods through the Transport wire. See [`docs/behavior.md`](docs/behavior.md) B-07..B-12.
+Declare a Namespace, then `bind` any Ruby object as a Member; the guest reaches it as a `<Namespace>::<Member>` proxy and invokes its public methods through the Transport wire. See [`docs/behavior/registration.md`](docs/behavior/registration.md) B-07..B-12.
 
 ```ruby
 class User
@@ -93,7 +93,7 @@ Names must match `/\A[A-Z]\w*\z/`. Symbol kwargs travel transparently to the hos
 
 ### Output Capture
 
-Guest writes through `puts` / `print` / `p` / `$stdout` / `$stderr` are buffered per-channel and exposed independently of the return value ([`docs/behavior.md`](docs/behavior.md) B-04). Buffers clear at the start of each invocation; overflow is clipped at the cap and flagged by `#stdout_truncated?` / `#stderr_truncated?`.
+Guest writes through `puts` / `print` / `p` / `$stdout` / `$stderr` are buffered per-channel and exposed independently of the return value ([`docs/behavior/lifecycle.md`](docs/behavior/lifecycle.md) B-04). Buffers clear at the start of each invocation; overflow is clipped at the cap and flagged by `#stdout_truncated?` / `#stderr_truncated?`.
 
 ```ruby
 result = sandbox.eval(<<~RUBY)
@@ -134,7 +134,7 @@ end
 
 ### Resource Limits
 
-Each invocation enforces a wall-clock `timeout` and a per-invocation linear-memory `memory_limit`; exhaustion raises a `TrapError` subclass. Pass `nil` to `timeout` / `memory_limit` to disable that cap. Read [`Sandbox#usage`](lib/kobako/sandbox.rb) after the call — populated on every outcome including traps — for actual consumption ([`docs/behavior.md`](docs/behavior.md) B-35).
+Each invocation enforces a wall-clock `timeout` and a per-invocation linear-memory `memory_limit`; exhaustion raises a `TrapError` subclass. Pass `nil` to `timeout` / `memory_limit` to disable that cap. Read [`Sandbox#usage`](lib/kobako/sandbox.rb) after the call — populated on every outcome including traps — for actual consumption ([`docs/behavior/lifecycle.md`](docs/behavior/lifecycle.md) B-35).
 
 ```ruby
 sandbox = Kobako::Sandbox.new(
@@ -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,9 +200,30 @@ 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/runtime.md`](docs/behavior/runtime.md) B-46..B-48). Construction forwards every `Sandbox.new` keyword verbatim; the optional block is the per-Sandbox setup window and runs exactly once per constructed Sandbox.
+
+`Kobako::Pool` is experimental today and is best treated as a convenience for warm, pre-configured reuse rather than a throughput optimisation. B-49 bakes the shared boot state into the artifact and every dynamic script still compiles and runs per invocation, so all a pool actually saves is the ~30 µs host-side `Sandbox.new`. For the workload kobako is built for — many small, short-lived Sandboxes running dynamic scripts — that is not a significant gain (~4-5% in the [serverless example](examples/serverless/README.md), and proportionally less once the script itself does real work).
+
+```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.
+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/yield.md`](docs/behavior/yield.md) B-23..B-30.
 
 ```ruby
 sandbox.define(:Seq).bind(:Map, ->(items, &blk) { items.map(&blk) })
@@ -212,7 +234,7 @@ sandbox.eval('Seq::Map.call([1, 2, 3]) { |x| x * 2 }')
 
 ### Handle Management
 
-A non-wire-representable host object — returned from a Service (B-14), passed to `#run` (B-34), or handed back from the guest (B-37) — crosses the boundary as an opaque `Kobako::Handle` proxy and is restored to the original object before host code sees it; any other unrepresentable value raises `Kobako::SandboxError`. Handles are scoped to a single invocation ([`docs/behavior.md`](docs/behavior.md) B-13..B-21, B-34, B-37).
+A non-wire-representable host object — returned from a Service (B-14), passed to `#run` (B-34), or handed back from the guest (B-37) — crosses the boundary as an opaque `Kobako::Handle` proxy and is restored to the original object before host code sees it; any other unrepresentable value raises `Kobako::SandboxError`. Handles are scoped to a single invocation ([`docs/behavior/dispatch.md`](docs/behavior/dispatch.md) B-13..B-21, B-34, B-37).
 
 ```ruby
 class Greeter
@@ -248,7 +270,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/invocation.md`](docs/behavior/invocation.md) B-31..B-33).
 
 ```ruby
 sandbox = Kobako::Sandbox.new
@@ -262,7 +284,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 +293,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:
@@ -300,6 +322,11 @@ sandbox.define(:Cfg).bind(:Settings, ThemeReader.new)  # not: bind(:Settings, Ap
 sandbox.eval('Cfg::Settings.color')  # => "#3366ff"  — every other method raises NoMethodError
 ```
 
+When a purpose-built wrapper is more than you need, an object can gate its own surface in
+place: a private `respond_to_guest?(name)` answers, per method, whether the guest may call
+it. Returning `false` for every name makes the object opaque — a credential the guest
+forwards to another Service but never reads — while a named subset becomes an allow-list.
+
 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
@@ -312,15 +339,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.11.0"
 edition = "2021"
 authors = ["Aotokitsuruya <contact@aotoki.me>"]
 license = "Apache-2.0"
@@ -27,8 +27,18 @@ wasmtime = { version = "45.0.0", default-features = false, features = [
     "wat",
 ] }
 # wasmtime-wasi provides WASI preview1 support for routing guest stdout/stderr
-# into in-memory buffers (docs/behavior.md §B-04). The `p1` feature enables the
+# 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 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/ambient.rs

@@ -11,7 +11,7 @@
 //!
 //! The host wall-clock cap is unaffected: the per-invocation timeout runs on
 //! wasmtime epoch interruption against a host `Instant`, never the guest's
-//! frozen `wasi:clocks/monotonic-clock` (docs/behavior.md B-01).
+//! frozen `wasi:clocks/monotonic-clock`.
 
 use std::time::Duration;
 

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; 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};
@@ -30,7 +37,7 @@ static SHARED_ENGINE: OnceLock<WtEngine> = OnceLock::new();
 static MODULE_CACHE: OnceLock<Mutex<HashMap<PathBuf, WtModule>>> = OnceLock::new();
 
 /// Ticker cadence for the process-singleton epoch ticker. Bounds the
-/// granularity of the docs/behavior.md B-01 wall-clock timeout: the
+/// granularity of the wall-clock timeout: the
 /// `epoch_deadline_callback` fires once per tick (`Continue(1)`), so the
 /// trap can lag the deadline by at most one tick under nominal
 /// scheduling. 10 ms keeps the lag small enough that it does not skew
@@ -50,7 +57,7 @@ const EPOCH_TICK: Duration = Duration::from_millis(10);
 ///
 /// Also enables `epoch_interruption(true)` so every Store can install an
 /// `epoch_deadline_callback` for the per-run wall-clock cap
-/// (docs/behavior.md B-01, E-19). The first call spawns the process-singleton ticker
+/// 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> {
@@ -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/capture.rs

@@ -1,6 +1,6 @@
 //! Per-channel stdout / stderr capture sizing and clipping.
 //!
-//! Two pure helpers shared by the run path (docs/behavior.md B-04): one
+//! Two pure helpers shared by the run path: one
 //! sizes the per-run `MemoryOutputPipe`, the other clips a captured
 //! snapshot back to the configured cap and reports whether the cap was
 //! exceeded. Kept channel-agnostic (a function of `cap`, not of which

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

@@ -13,11 +13,10 @@ use std::time::Duration;
 /// Wall-clock and output caps for one `Runtime`. `None` on any field
 /// disables that cap.
 pub(crate) struct Config {
-    /// Wall-clock cap for one guest `#eval` / `#run` (docs/behavior.md
-    /// B-01, E-19). Stamped into a per-run `Instant` deadline by
-    /// `Runtime::prime_caps`.
+    /// Wall-clock cap for one guest `#eval` / `#run`. Stamped into a
+    /// per-run `Instant` deadline by `Runtime::prime_caps`.
     pub(crate) timeout: Option<Duration>,
-    /// Byte cap for guest stdout capture (docs/behavior.md B-01 / B-04).
+    /// Byte cap for guest stdout capture.
     /// Sizes the per-run `MemoryOutputPipe` and computes the truncation
     /// flag in `Runtime::build_snapshot`.
     pub(crate) stdout_limit_bytes: Option<usize>,

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

@@ -2,8 +2,8 @@
 //!
 //! 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`.
-//! That closure delegates here. The dispatcher (docs/behavior.md B-12 / B-13):
+//! through the closure registered by `instance_pre::build_linker`.
+//! That closure delegates here. The dispatcher:
 //!
 //!   1. Reads the Request bytes from guest linear memory.
 //!   2. Invokes the Ruby-side dispatch Proc bound via
@@ -55,8 +55,8 @@ use wasmtime::Caller;
 use super::invocation::Invocation;
 
 // ============================================================
-// Active-caller pointer for the per-thread Invocation slot (B-24, B-28,
-// SPEC.md Single-Invocation Slot).
+// Active-caller pointer for the per-thread Invocation slot
+// (SPEC.md Single-Invocation Slot).
 // ============================================================
 //
 // `Runtime#yield_to_active_invocation` (whose body is the
@@ -73,8 +73,8 @@ use super::invocation::Invocation;
 // The pointer is therefore erased to `NonNull<()>` and parked in a
 // per-thread slot — the materialised form of the SPEC.md
 // "Single-Invocation Slot" invariant. The single-threaded wasm
-// execution per Sandbox (B-22) plus the LIFO re-entry shape of nested
-// dispatch frames (B-28) ensures no aliasing across threads or across
+// execution per Sandbox plus the LIFO re-entry shape of nested
+// dispatch frames ensures no aliasing across threads or across
 // frames; the recovery invariant lives at `current_caller`. The
 // pointer is set on entry to `handle` and restored to the outer
 // frame's value on every exit through a drop guard.
@@ -85,7 +85,7 @@ thread_local! {
 
 /// RAII guard that saves the previous `ACTIVE_CALLER` value on
 /// installation and restores it on drop. Nested `__kobako_dispatch`
-/// frames stack within one Invocation (B-28) — the inner frame's `set`
+/// frames stack within one Invocation — the inner frame's `set`
 /// swaps in its own pointer while remembering the outer's; drop
 /// restores the outer so its continuation (e.g. iterating over another
 /// guest block) still finds a live caller.
@@ -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