kobako 0.27.0 → 0.28.0

data/crates/kobako-transport/src/envelope/unsupported.rs

@@ -0,0 +1,105 @@
+//! A receiver saying it does not serve the operation it was sent.
+//!
+//! It is an answer rather than a breakage, so it rides every operation's
+//! answer as its own arm and the caller decides whether to fall back or
+//! give up. It names no operation: the caller knows what it sent.
+
+use super::bytes::{Reader, Writer};
+use super::{tag, DecodeError};
+
+/// The only kind defined. A kind this reader predates reads as this one,
+/// so a later kind still delivers its message.
+const KIND_UNSUPPORTED: u8 = 0;
+
+/// The refusal a receiver answers with when it does not serve an
+/// operation.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Unsupported {
+    pub message: String,
+}
+
+impl Unsupported {
+    pub fn new(message: impl Into<String>) -> Self {
+        Unsupported {
+            message: message.into(),
+        }
+    }
+
+    /// This refusal as a whole answer. Every operation's answer spells
+    /// the arm the same way, so a receiver refusing a tag it cannot
+    /// read needs no answer type to refuse it in.
+    pub fn encode(&self) -> Vec<u8> {
+        let mut writer = Writer::new();
+        writer
+            .u8(tag::UNSUPPORTED)
+            .u8(KIND_UNSUPPORTED)
+            .bytes(self.message.as_bytes());
+        writer.into_bytes()
+    }
+
+    pub(crate) fn read(reader: &mut Reader<'_>) -> Result<Self, DecodeError> {
+        reader.u8()?;
+        let message = reader.text()?.to_owned();
+        // The last thing its answer carries, so whatever follows belongs
+        // to a later version of these fields, as for a Fault.
+        reader.skip_unknown_fields();
+        Ok(Unsupported { message })
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::super::{CompileReply, Outcome, Reply, YieldReply};
+    use super::*;
+
+    // @behavior WE-069
+    #[test]
+    fn an_unsupported_answer_round_trips_on_every_operation() {
+        let refusal = Unsupported::new("not served");
+        assert_eq!(
+            refusal.encode(),
+            Reply::Unsupported(refusal.clone()).encode(),
+            "an Unsupported encoded on its own must be the same answer every operation carries"
+        );
+        assert_eq!(
+            (
+                Reply::decode(&Reply::Unsupported(refusal.clone()).encode()),
+                YieldReply::decode(&YieldReply::Unsupported(refusal.clone()).encode()),
+                CompileReply::decode(&CompileReply::Unsupported(refusal.clone()).encode()),
+                Outcome::decode(&Outcome::Unsupported(refusal.clone()).encode()),
+            ),
+            (
+                Ok(Reply::Unsupported(refusal.clone())),
+                Ok(YieldReply::Unsupported(refusal.clone())),
+                Ok(CompileReply::Unsupported(refusal.clone())),
+                Ok(Outcome::Unsupported(refusal)),
+            ),
+            "an Unsupported through each answer's encode and decode must arrive as it was \
+             given"
+        );
+    }
+
+    // @behavior WE-070
+    #[test]
+    fn a_kind_this_reader_predates_still_delivers_its_message() {
+        let bytes = [0x15, 9, 0, 0, 0, 1, b'm'];
+        assert_eq!(
+            Reply::decode(&bytes),
+            Ok(Reply::Unsupported(Unsupported::new("m"))),
+            "an Unsupported of an unknown kind through Reply::decode must read as the one \
+             kind defined, its message intact"
+        );
+    }
+
+    // @behavior WE-090
+    #[test]
+    fn a_field_this_reader_predates_is_skipped() {
+        let bytes = [0x15, 0, 0, 0, 0, 1, b'm', 0xff];
+        assert_eq!(
+            Reply::decode(&bytes),
+            Ok(Reply::Unsupported(Unsupported::new("m"))),
+            "an Unsupported carrying a trailing field through Reply::decode must skip it, \
+             its message intact"
+        );
+    }
+}

data/crates/kobako-transport/src/envelope.rs

@@ -6,40 +6,47 @@
 //! tier that only routes messages therefore needs no payload codec at all,
 //! and the one an assembly does use is its own choice.
 //!
-//! A decoded envelope borrows the buffer it came from, so a payload reaches
-//! its reader as a view rather than a copy. The two fields a reader keeps
-//! past that buffer's life — a binding's path and a snippet's body, read
-//! from a frame at boot and consumed later — are copied at decode.
+//! A decoded Call or Upcall borrows the buffer it came from, so a dispatched
+//! payload reaches its reader as a view rather than a copy. Every other
+//! message copies what it holds at decode.
 //!
-//! No type here is `#[non_exhaustive]`. Every arm is a tag byte the layout
-//! document fixes, so the set grows only with an ABI version — and when it
+//! Every answer is exhaustive. Each arm is a tag byte the layout document
+//! fixes, so an answer's set grows only with an ABI version — and when it
 //! does, a peer that has not been taught the new arm should fail to
-//! compile rather than fall into a wildcard and answer a message it cannot
-//! read.
+//! compile rather than fall into a wildcard and answer a message it
+//! cannot read. Three kinds of type are the exception, because a reader
+//! answers what it predates instead of refusing it: a request reads an
+//! unassigned tag as unknown, a Fault's category degrades, and a
+//! Preamble skips an advisory record of a kind it does not know.
 //!
 //! This layer has one implementation, so its `golden_layout_*` tests are
 //! what hold it to the layout document. They spell each tag as the literal
 //! byte that document fixes, never as the constant beside it: a golden
 //! written from the constant compares the implementation to itself.
-//!
-//! [core envelope]: ../../../docs/wire/envelope.md
 
 pub(crate) mod bytes;
 pub mod call;
+pub mod compile_reply;
 pub mod error_record;
 pub mod fault;
-pub mod invocation_frames;
 pub mod outcome;
+pub mod preamble;
 pub mod reply;
+pub mod request;
 pub mod run;
+pub(crate) mod tag;
+pub mod unsupported;
 
 pub use call::{Call, Target};
+pub use compile_reply::CompileReply;
 pub use error_record::ErrorRecord;
 pub use fault::{Fault, FaultKind};
-pub use invocation_frames::{Bindings, Snippet, Snippets};
 pub use outcome::{Origin, Outcome, Panic};
+pub use preamble::{Bindings, Flag, Preamble, Snippet, Snippets};
 pub use reply::{Reply, YieldReply};
+pub use request::{Downcall, UnknownTag, Upcall};
 pub use run::Run;
+pub use unsupported::Unsupported;
 
 use std::fmt;
 

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

@@ -14,8 +14,6 @@
 //! interpreter, or a schema — and nothing may come to: a tier every other
 //! tier composes against cannot carry a choice any of them might want to
 //! make differently.
-//!
-//! [core envelope]: ../../../docs/wire/envelope.md
 
 pub mod abi;
 pub mod envelope;

data/crates/kobako-wasmtime/CHANGELOG.md

@@ -1,5 +1,49 @@
 # Changelog
 
+## [0.18.0](https://github.com/elct9620/kobako/compare/kobako-wasmtime-v0.17.0...kobako-wasmtime-v0.18.0) (2026-10-13)
+
+
+### ⚠ BREAKING CHANGES
+
+* the kobako and kobako-wasmtime crates declare a minimum supported Rust version of 1.96.
+* **transport:** the stdin layout a Guest Binary reads changed within ABI 4. kobako_transport::envelope::Frames is replaced by Preamble, which is #[non_exhaustive] and built from Default; Bindings and Snippets no longer have their own decode and encode. Guest::eval and Guest::run, MrbGuest::eval and MrbGuest::run, and Runtime::invoke take a Preamble in place of Frames. kobako_core re-exports Preamble and Flag in place of Frames.
+* **transport:** the ABI version is 4, so a Guest Binary built for ABI 3 is refused at Sandbox construction. kobako_core::export_guest! emits __kobako_downcall in place of __kobako_eval, __kobako_run, __kobako_yield_to_block and __kobako_take_outcome, and the host import is __kobako_upcall. kobako_core::abi::{take_outcome, write_outcome, write_reply, decode_run} are replaced by serve and answer, and the frames module is no longer public. Reply, YieldReply and Outcome gain an Unsupported arm and take their tags from the shared registry, and kobako_core::DispatchError and kobako::YieldError gain an Unsupported arm. A yield to a guest without block support raises Kobako::UnsupportedError at the Service's yield instead of failing the invocation as a trap.
+* **runtime:** Runtime::invoke takes &kobako_transport::envelope::Frames in place of kobako_runtime::Frames, whose byte fields are gone. Guest::eval and Guest::run (and their MrbGuest flows) receive the decoded Frames, eval also its source; kobako_core::frames::read_frame is replaced by read_eval_frames and read_frames.
+* **runtime:** kobako_runtime::snapshot::Completion::Outcome holds a decoded kobako_transport::envelope::Outcome instead of Vec<u8>; an engine decodes the result itself and reports an unframed one as
+* **runtime:** kobako_runtime::runtime::Entry::Run holds { entrypoint: &str, payload: Vec<u8> } instead of { envelope: &[u8] }; a frontend passes the fields, and an engine encodes the Run envelope itself.
+* **runtime:** kobako_runtime::yielder::Yielder::yield_to_block returns Result<YieldReply, Trap> instead of the encoded bytes; an engine implementing it decodes the reply itself.
+* a memory budget or deadline reached during a Service answer or a yielded block now raises Kobako::MemoryLimitError or
+
+### Features
+
+* **guest:** raise Kobako::UnsupportedError when a host does not serve a call ([db003af](https://github.com/elct9620/kobako/commit/db003af75cf2d11b5f644986aa77c0408f5f59ba)), closes [#73](https://github.com/elct9620/kobako/issues/73)
+* **runtime:** compile a Preamble's snippets on an instance of their own ([303432d](https://github.com/elct9620/kobako/commit/303432dd90ed62dc378391515e68e784e1b473a4)), closes [#75](https://github.com/elct9620/kobako/issues/75)
+* **transport:** carry each operation as a tag on one channel per direction ([c7d574b](https://github.com/elct9620/kobako/commit/c7d574b59a42e58632f2bdc46cc9a8e4c7ac6121)), closes [#73](https://github.com/elct9620/kobako/issues/73)
+* **transport:** keep an unknown request's body, and refuse tag 0x00 ([edb64df](https://github.com/elct9620/kobako/commit/edb64df8f87694d17c5b6fd71ac63329023306ec)), closes [#73](https://github.com/elct9620/kobako/issues/73)
+* **transport:** set an invocation up from a Preamble of tagged records ([84d4498](https://github.com/elct9620/kobako/commit/84d4498464f94d7312f26931ddd4ec43894a6654))
+
+
+### Bug Fixes
+
+* end the invocation as the trap a host callback into the guest hits ([b8f47d3](https://github.com/elct9620/kobako/commit/b8f47d3699a19adcfd5596af93136401a286c761))
+* keep a compile's bytecode only when the Preamble still fits it ([765db08](https://github.com/elct9620/kobako/commit/765db08ad31c8f5163794c7e144355f3237af93b))
+* **wasmtime:** keep a compile answer only when it covers every source snippet ([93e9ddd](https://github.com/elct9620/kobako/commit/93e9ddd79f714446ae713a3145c59d3d2f4145dc))
+* **wasmtime:** tell every frontend how to recover, not only the gem ([cab805a](https://github.com/elct9620/kobako/commit/cab805ab62441a0ca2c78775b7a0d7ce9cc05c43))
+* **wasmtime:** word a missing or mistyped export one way ([8ab0aee](https://github.com/elct9620/kobako/commit/8ab0aeec8bda2960b6cab0502ef51860ea9093b8))
+
+
+### Code Refactoring
+
+* **runtime:** hand a frontend the decoded Outcome ([0da6aac](https://github.com/elct9620/kobako/commit/0da6aac0f7943d694a5a4ab9439b2d6c527ae1b0)), closes [#73](https://github.com/elct9620/kobako/issues/73)
+* **runtime:** hand a frontend the decoded Yield Reply ([e80ab54](https://github.com/elct9620/kobako/commit/e80ab54e36c2a80b0f746c675f85bd1238fd4331)), closes [#73](https://github.com/elct9620/kobako/issues/73)
+* **runtime:** let the ABI endpoints frame and read the Frames ([dea069a](https://github.com/elct9620/kobako/commit/dea069ac49a59c12a6f7102ed3cf2925f316cbff)), closes [#73](https://github.com/elct9620/kobako/issues/73)
+* **runtime:** let the engine frame a run's entrypoint and payload ([62f9c94](https://github.com/elct9620/kobako/commit/62f9c9407ff3ce690723625bea075fa49d2dda47)), closes [#73](https://github.com/elct9620/kobako/issues/73)
+
+
+### Build System
+
+* declare the Rust 1.96 floor wasmtime 49 sets ([f49a2df](https://github.com/elct9620/kobako/commit/f49a2df88fa51d3b0eecb619cab1e98d79bb4245))
+
 ## [0.17.0](https://github.com/elct9620/kobako/compare/kobako-wasmtime-v0.16.0...kobako-wasmtime-v0.17.0) (2026-09-20)
 
 

data/crates/kobako-wasmtime/Cargo.toml

@@ -15,8 +15,10 @@
 
 [package]
 name = "kobako-wasmtime"
-version = "0.17.0"
+version = "0.18.0"
 edition = "2021"
+# wasmtime's own floor.
+rust-version = "1.96"
 description = "wasmtime implementation of the kobako host runtime contract."
 license = "Apache-2.0"
 repository = "https://github.com/elct9620/kobako"
@@ -28,17 +30,17 @@ categories = ["wasm", "virtualization"]
 # The engine-neutral contract this crate implements. The version pin
 # rides the linked release group; the path keeps in-tree builds (and
 # the Ruby gem, which ships both crates) resolving locally.
-kobako-runtime = { version = "0.17.0", path = "../kobako-runtime" }
+kobako-runtime = { version = "0.18.0", path = "../kobako-runtime" }
 # The fixed tier: the core envelope this driver shuttles and the ABI
 # values it drives the exports against.
-kobako-transport = { version = "0.17.0", path = "../kobako-transport" }
+kobako-transport = { version = "0.18.0", path = "../kobako-transport" }
 # 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 = "48.0.1", default-features = false, features = [
+wasmtime = { version = "49.0.2", default-features = false, features = [
     "cranelift",
     "runtime",
     "gc",
@@ -52,7 +54,7 @@ wasmtime = { version = "48.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 = "48.0.1", default-features = false, features = ["p1"] }
+wasmtime-wasi = { version = "49.0.2", default-features = false, features = ["p1"] }
 # sha2 keys the on-disk compiled-module cache by Guest Binary content
 # (see cache.rs); a collision would load the wrong artifact, so the
 # hash must be cryptographic.

data/crates/kobako-wasmtime/README.md

@@ -13,7 +13,7 @@ contract surface.
 | Compilation | process-wide Engine and compiled-Module caches, with an on-disk AOT (`.cwasm`) artifact cache keyed by Guest Binary content |
 | Instantiation | a pre-linked `InstancePre` per guest path; every invocation runs on a fresh instance and discards its Store afterwards |
 | Bounds | 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 |
+| Ambient denial | under the default hermetic profile, frozen clocks and a constant RNG |
 
 The kobako Ruby gem's native ext is the first frontend; a Rust host
 SDK consumes the same surface.
@@ -22,7 +22,7 @@ SDK consumes the same surface.
 
 ```toml
 [dependencies]
-kobako-wasmtime = "0.17.0" # x-release-please-version
+kobako-wasmtime = "0.18.0" # x-release-please-version
 ```
 
 ## License

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

@@ -10,7 +10,7 @@ use wasmtime::{AsContextMut, InstancePre, Store as WtStore};
 use crate::cache::shared_engine;
 use crate::config::Config;
 use crate::invocation::Invocation;
-use crate::{frames, trap};
+use crate::{io, trap};
 use kobako_runtime::error::SetupError;
 use kobako_runtime::profile::Profile;
 use kobako_transport::abi::ABI_VERSION;
@@ -29,19 +29,16 @@ const PROBE_CONFIG: Config = Config {
     profile: Profile::Hermetic,
 };
 
-/// Instantiate a throwaway probe instance from `pre` and require the
-/// guest's `__kobako_abi_version` export to equal `ABI_VERSION`. An
-/// absent export or a non-equal value is a deterministic artifact
-/// fault, so every failure is a `SetupError` for the frontend to
-/// attribute. The frameless WASI context keeps a third-party guest
-/// whose start section touches WASI on the `SetupError` path instead of
+/// An absent or unequal version is a deterministic artifact fault, so
+/// every failure is a `SetupError`. The probe's own WASI context keeps a
+/// guest whose start section touches WASI on that path instead of
 /// panicking in `Invocation::wasi_mut`.
 pub(crate) fn verify(pre: &InstancePre<Invocation>) -> Result<(), SetupError> {
     let mut store = WtStore::new(shared_engine()?, Invocation::new(None));
     // Epoch interruption is on engine-wide and a fresh Store's deadline
     // has already elapsed, so the probe must name one it cannot reach.
     store.set_epoch_deadline(trap::NO_TIMEOUT_EPOCH_DELTA);
-    frames::install_wasi_frames(&mut store, &PROBE_CONFIG, &[])
+    io::install_wasi(&mut store, &PROBE_CONFIG, &[])
         .map_err(|t| SetupError::Dead(t.to_string()))?;
     let instance = pre
         .instantiate(store.as_context_mut())

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

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

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

@@ -1,8 +1,8 @@
 //! Process-wide caches for the wasmtime `Engine` and compiled
 //! `Module`, plus the on-disk compiled-artifact cache.
 //!
-//! SPEC.md "Code Organization" forbids exposing wasm engine types to
-//! the Host App or downstream gems. To amortise Engine creation and
+//! Wasm engine types stay hidden from the Host App and 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
@@ -13,10 +13,10 @@
 //! 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.
+//! Concurrency: the Mutex is held only for the HashMap lookup and insert,
+//! never across a compile, so threads building Drivers at once do not
+//! wait on each other. Two concurrent misses on one path both compile,
+//! and the later insert wins with an equivalent Module.
 
 use std::collections::HashMap;
 use std::fmt::Write as _;
@@ -43,21 +43,10 @@ static MODULE_CACHE: OnceLock<Mutex<HashMap<PathBuf, WtModule>>> = OnceLock::new
 /// 10 ms across the whole process).
 const EPOCH_TICK: Duration = Duration::from_millis(10);
 
-/// Return the process-wide wasmtime Engine, building it on first call.
-///
-/// Enables the wasm exceptions proposal so `kobako.wasm` (which uses
-/// `try_table` / `exnref` / `tag` for mruby's setjmp-via-new-EH path)
-/// can be loaded. The mruby wasi build config uses
-/// `-mllvm -wasm-use-legacy-eh=false`, which generates new-style
-/// exception handling instructions in the wasm32 object files;
-/// wasmtime must have the proposal enabled to parse and JIT those
-/// instructions.
-///
-/// Also enables `epoch_interruption(true)` so every Store can install an
-/// `epoch_deadline_callback` for the per-run wall-clock cap
-/// 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.
+/// The exceptions proposal is on because the mruby wasi build emits
+/// new-style exception handling (`-mllvm -wasm-use-legacy-eh=false`) for
+/// its setjmp path. Epoch interruption backs the wall-clock cap, driven by
+/// one process-wide ticker thread.
 pub(crate) fn shared_engine() -> Result<&'static WtEngine, SetupError> {
     if let Some(engine) = SHARED_ENGINE.get() {
         return Ok(engine);
@@ -72,11 +61,6 @@ pub(crate) fn shared_engine() -> Result<&'static WtEngine, SetupError> {
     Ok(engine)
 }
 
-/// Spawn the process-singleton epoch ticker. The thread holds a clone of
-/// the shared Engine (`wasmtime::Engine` is reference-counted internally)
-/// and ticks the epoch counter at `EPOCH_TICK` cadence. Idempotent
-/// across reentrant calls to `shared_engine` because `OnceLock`
-/// gates the spawn.
 fn spawn_epoch_ticker(engine: WtEngine) {
     static TICKER_SPAWNED: OnceLock<()> = OnceLock::new();
     TICKER_SPAWNED.get_or_init(|| {
@@ -90,11 +74,8 @@ fn spawn_epoch_ticker(engine: WtEngine) {
     });
 }
 
-/// Look up `path` in the per-path Module cache, compiling and inserting
-/// 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`.
+/// A missing file answers `SetupError::ModuleNotBuilt`, the common state of
+/// 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()));
 
@@ -109,7 +90,7 @@ pub(crate) fn cached_module(path: &Path) -> Result<WtModule, SetupError> {
 
     if !path.exists() {
         return Err(SetupError::ModuleNotBuilt(format!(
-            "Sandbox runtime not found at {}; run `bundle exec rake wasm:build` to build it",
+            "Sandbox runtime not found at {}",
             path.display()
         )));
     }
@@ -145,17 +126,11 @@ pub(crate) fn cached_module(path: &Path) -> Result<WtModule, SetupError> {
 /// 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>-<crate version>.cwasm`.
-/// Content addressing makes a rebuilt Guest Binary a new cache entry
-/// 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.
+/// Content addressing makes a rebuilt Guest Binary a new entry rather than
+/// an invalidation problem; the crate-version segment keeps two installed
+/// kobako-wasmtime versions, each pinning its own wasmtime, from thrashing
+/// one key. wasmtime itself rejects an artifact from an incompatible
+/// version or Config at deserialize time.
 fn artifact_path(wasm_bytes: &[u8]) -> Option<PathBuf> {
     let base = std::env::var_os("XDG_CACHE_HOME")
         .map(PathBuf::from)
@@ -169,11 +144,8 @@ fn artifact_path(wasm_bytes: &[u8]) -> Option<PathBuf> {
     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.
+/// A hit refreshes the file's mtime, so the retention window measures time
+/// since last use rather than since creation.
 fn load_artifact(engine: &WtEngine, artifact: &Path) -> Option<WtModule> {
     if !artifact.exists() || !artifact.parent().is_some_and(dir_is_private) {
         return None;
@@ -192,11 +164,9 @@ fn load_artifact(engine: &WtEngine, artifact: &Path) -> Option<WtModule> {
     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
+/// The temp-file and rename pair keeps concurrent processes from observing
+/// a partial write. Failures are swallowed because the cache is only an
+/// optimisation, and pruning on write keeps the directory bounded across
 /// rebuilds.
 fn store_artifact(module: &WtModule, artifact: &Path) {
     let Ok(bytes) = module.serialize() else {
@@ -252,10 +222,8 @@ 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.
+/// 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;
@@ -277,8 +245,6 @@ fn prune_stale(dir: &Path, keep: &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;

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

@@ -7,10 +7,8 @@
 //! channel) so a regression that only breaks one channel cannot sneak
 //! through the test that pins them.
 
-/// Translate a per-channel byte cap into the MemoryOutputPipe capacity:
-/// `cap + 1` (saturated against `usize::MAX`) when a cap is set so the
-/// "wrote exactly cap" and "exceeded cap" cases stay distinguishable;
-/// `usize::MAX` when the channel is uncapped.
+/// One byte past the cap, so "wrote exactly cap" and "exceeded cap" stay
+/// distinguishable.
 pub(crate) fn pipe_capacity(cap: Option<usize>) -> usize {
     match cap {
         Some(c) => c.saturating_add(1),
@@ -18,13 +16,8 @@ pub(crate) fn pipe_capacity(cap: Option<usize>) -> usize {
     }
 }
 
-/// Pure clipping core shared by the snapshot readback: given the
-/// unclipped pipe snapshot (owned — truncated in place, so the readback
-/// costs one copy out of the pipe, not two), return the bytes Ruby
-/// should observe plus the truncation flag. `truncated` is `true` only
-/// when the snapshot strictly exceeded the cap — this is the "wrote
-/// `cap + 1` bytes into a `cap + 1`-sized pipe" case; "wrote exactly
-/// `cap` bytes" stays `false`.
+/// Takes the snapshot by value and truncates in place, so the readback
+/// costs one copy out of the pipe rather than two.
 pub(crate) fn clip_capture(mut raw: Vec<u8>, cap: Option<usize>) -> (Vec<u8>, bool) {
     match cap {
         Some(c) if raw.len() > c => {

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

@@ -18,23 +18,20 @@ use kobako_runtime::profile::Profile;
 /// The caps and requested isolation profile for one `Driver`. `None` on
 /// any cap field disables that cap.
 pub struct Config {
-    /// Wall-clock cap for one guest `#eval` / `#run`. Stamped into a
-    /// per-run `Instant` deadline by `Driver::prime_caps`.
+    /// Wall-clock cap for one guest `#eval` / `#run`; the invocation traps
+    /// once it passes.
     pub timeout: Option<Duration>,
-    /// Guest linear-memory cap, in bytes. Threaded into each fresh
-    /// `Invocation`, where the wasmtime `ResourceLimiter` callback
-    /// consumes it from inside the engine.
+    /// Guest linear-memory cap, in bytes, charged to what one invocation
+    /// grows beyond the image it starts from.
     pub memory_limit: Option<usize>,
-    /// Byte cap for guest stdout capture.
-    /// Sizes the per-run `MemoryOutputPipe` and computes the truncation
-    /// flag in `Driver::build_snapshot`.
+    /// Byte cap for guest stdout capture; output past it is dropped and
+    /// the capture marked truncated.
     pub stdout_limit: Option<usize>,
-    /// Byte cap for guest stderr capture. Mirror of `stdout_limit`.
+    /// Byte cap for guest stderr capture, the same as `stdout_limit`.
     pub stderr_limit: Option<usize>,
-    /// Isolation posture the frontend requested. The per-invocation
-    /// WASI context is built to this rung — `Hermetic` freezes ambient
-    /// time and entropy (`crate::ambient`), `Permissive` leaves the
-    /// live WASI sources — and `Driver::profile` declares it back as
-    /// the built posture.
+    /// Isolation posture the frontend requested. `Hermetic` freezes
+    /// ambient time and entropy, `Permissive` leaves the live WASI
+    /// sources, and `Driver::profile` declares it back as the built
+    /// posture.
     pub profile: Profile,
 }