kobako 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ddc9be38e5ce7f23c176bcd7be8b8683cf58d308dfedb17e91fc5841308a5c8c
-  data.tar.gz: 4a0de9e36b529010b50148ff9d904cafbe253b0c394a9a2118e6ef4d7c9e4029
+  metadata.gz: fd04d7b8efaf9ccb41ff873a66b0855839222c5bc034d80a854b9fbc25602570
+  data.tar.gz: 718665fbcfb89faafc86f018a247e37ea304c3c8559e4febc240ad95bdc15654
 SHA512:
-  metadata.gz: ae0e599389ce723a1c257923a5b5b760ddf94a71698e5fa990f82587494ae8ca874d11c8c1fd5eedfac0d6e953f53cfb8603fb4da34989f8f92e39425bb99fa5
-  data.tar.gz: 6cbdec819843c52c1be3d04a6694af51ae41121e159a4de12d1ebef0074d1626247c8c06db0e9f15da2deb19b4b1730c124aa027bc676ffc2b1fedf6cd68d3c7
+  metadata.gz: e9cd6493f200abbb9a9014e9222633fec67e8813a854b93e71a29d94a3738ff64dfe33f5b136efe472d87831fb78062a09ac481d1da6970782e965a7a7aeafc8
+  data.tar.gz: 7f11f9fb3e48efc808eebd0598bc19569c6c1fd90322cee2f65f9030d8ca39a3da6cbe9fa68edb33480e926aabcb3766c2dc8c37995945ceaebd7b9952d9ec0f

data/.release-please-manifest.json

@@ -0,0 +1 @@
+{".":"0.5.0"}

data/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+## [0.5.0](https://github.com/elct9620/kobako/compare/v0.4.0...v0.5.0) (2026-05-27)
+
+
+### Features
+
+* **abi:** add `__kobako_yield_to_block` skeleton + host re-entry channel ([555eb4b](https://github.com/elct9620/kobako/commit/555eb4bf578c3c4397ba2c0d105c0d3ca687e23c))
+* **abi:** classify RBreak via ci_break_index for B-25 / E-21 ([32668a0](https://github.com/elct9620/kobako/commit/32668a033e2f959700acadadfbc41388ed72a2dd))
+* **abi:** wire `__kobako_yield_to_block` to real `mrb_yield_argv` ([35aeac8](https://github.com/elct9620/kobako/commit/35aeac8700254d1500f5be837a72c56984a7ebfa))
+* **bench:** add noise-aware release gate, report mean alongside median ([0cfaebc](https://github.com/elct9620/kobako/commit/0cfaebc2afadfae81e3d00441273da70e396d7a5))
+* **bench:** add yield round-trip suite as gated benchmark [#6](https://github.com/elct9620/kobako/issues/6) ([315f923](https://github.com/elct9620/kobako/commit/315f923caa89bcd8752a611525da68ae53ae092f))
+* **catalog:** introduce empty Kobako::Catalog namespace ([8af8c54](https://github.com/elct9620/kobako/commit/8af8c54c72e5e5193555bcc2e86072d4a4d8176d))
+* **ext:** enforce the 16 MiB single-dispatch payload cap on host boundaries ([c80e281](https://github.com/elct9620/kobako/commit/c80e281e0810640c60d93174beddd49a31c34182))
+* **guest:** capture guest blocks via `n*&` argspec + LIFO BLOCK_STACK ([aa55556](https://github.com/elct9620/kobako/commit/aa55556aab23c159078d0ba0ea47ed878b26e89d))
+* **rpc:** build block proxy for guest-supplied yield blocks ([b6d6cf7](https://github.com/elct9620/kobako/commit/b6d6cf7f5ca857f55aafea62631b243f688c61a6))
+* **rpc:** catch/throw + frame invalidator close B-25 / B-28 / E-23 ([3b21f25](https://github.com/elct9620/kobako/commit/3b21f252fafdd2070f3953460509e24a0e643d88))
+* **transport:** introduce empty Kobako::Transport namespace ([85cda26](https://github.com/elct9620/kobako/commit/85cda268000490f521424339bec1664d0b33478b))
+* **wire:** add `block_given` field to Request envelope ([30e004f](https://github.com/elct9620/kobako/commit/30e004fa8f00739e68883889c5225c98cf9521fe))
+* **wire:** add YieldResponse envelope codec on both sides ([4592567](https://github.com/elct9620/kobako/commit/459256784af616d70738ffd0f56c3b15244b3e7c))
+
+
+### Bug Fixes
+
+* **bench:** restore renamed class references so rake bench runs ([76140cc](https://github.com/elct9620/kobako/commit/76140cc99922973fc305aab6ba727a832ddbe7ba))
+* **ext:** GC-root the dispatch Proc via a pinning mark on Kobako::Runtime ([f31bd07](https://github.com/elct9620/kobako/commit/f31bd071201b5fed7376bd13b876f103d6c6a5d6))
+* **ext:** raise SandboxError, not TrapError, when #run envelope alloc fails ([a1981fe](https://github.com/elct9620/kobako/commit/a1981fea7438090a76758147e7e84543e9d96968))
+* **transport:** fill E-xx placeholder and drop BLOCK_RESEARCH citations ([816ff80](https://github.com/elct9620/kobako/commit/816ff804535196036bec01fcd980e25036211b80))
+* **wasm:** reject unrepresentable guest return values instead of stringifying ([c3fd069](https://github.com/elct9620/kobako/commit/c3fd0698cb168b55502fb86065406caf9a7744e1))

data/Cargo.lock

@@ -864,7 +864,7 @@ dependencies = [
 
 [[package]]
 name = "kobako"
-version = "0.3.0"
+version = "0.5.0"
 dependencies = [
  "magnus",
  "wasmtime",

data/README.md

@@ -27,10 +27,11 @@ The host (`wasmtime`) runs a precompiled `kobako.wasm` guest containing mruby an
 | Per-invocation caps | Every invocation enforces a wall-clock `timeout` (default 60 s) and a per-invocation linear-memory `memory_limit` (default 1 MiB); exhaustion raises `Kobako::TimeoutError` / `Kobako::MemoryLimitError`. |
 | Capability injection via Services | Guest scripts can only call Ruby objects you explicitly `bind` under a two-level `Namespace::Member` path. |
 | Preloaded snippets | `Sandbox#preload` registers source or RITE bytecode for setup-once dispatch via `Sandbox#run(:Entrypoint, *args, **kwargs)`. |
-| Capability Handles | Services may return stateful host objects; the guest receives an opaque `Kobako::RPC::Handle` proxy it can use as the target of follow-up RPC calls, with no way to dereference it. |
+| Capability Handles | Services may return stateful host objects; the guest receives an opaque `Kobako::Handle` proxy it can use as the target of follow-up RPC calls, with no way to dereference it. `Sandbox#run` also accepts non-wire-representable Ruby objects as args and auto-wraps them into Handles, so the guest can use any host object the script needs. |
 | Three-class error taxonomy | Every failure is exactly one of `TrapError`, `SandboxError`, or `ServiceError`, so you can route errors without inspecting messages. |
 | Per-invocation state reset | Handles issued during one invocation are invalidated before the next; Service bindings and preloaded snippets remain. |
 | Separated stdout / stderr capture | Guest writes to `$stdout` / `$stderr` are buffered per-channel (1 MiB default cap, configurable); overflow is clipped and reported by `#stdout_truncated?` / `#stderr_truncated?`. |
+| Per-invocation usage readout | `Sandbox#usage` returns the most recent invocation's `wall_time` (Float seconds spent inside the wasm guest) and `memory_peak` (high-water `memory.grow` delta in bytes), populated on every outcome including `TrapError`, for budget diagnostics. |
 | Curated mruby stdlib | Core extensions plus `mruby-onig-regexp` for full Onigmo `Regexp` support; no mrbgem with I/O, network, or syscall access is bundled. |
 
 ## Requirements
@@ -122,6 +123,19 @@ The timeout deadline is absolute wall-clock from invocation entry and is checked
 
 The 1 MiB default targets lightweight dynamic RPC workloads — short scripts that orchestrate Service calls, return small structured values, or replace a tool-calling layer in an AI Agent's Code Mode dispatch. Bump `memory_limit` when scripts compose multi-hundred-KiB strings, hold large composite return values, or run computations that allocate substantial intermediate state. Because the cap resets every invocation, multi-call patterns on one Sandbox do not need a budget that covers their cumulative footprint — only the largest single invocation's working set.
 
+To see how much of the cap an invocation actually consumed, read `Sandbox#usage` after the call. It returns a `Kobako::Usage` value object with `wall_time` (Float seconds the guest export call spent inside wasmtime, aligned with the `timeout` accounting) and `memory_peak` (Integer high-water `memory.grow` delta in bytes, aligned with the `memory_limit` accounting). The fields are populated on every outcome, including the `TrapError` branches, so you can read them after rescuing a trap to diagnose which budget the failing invocation chewed through.
+
+```ruby
+sandbox = Kobako::Sandbox.new(timeout: 1.0, memory_limit: 4 * 1024 * 1024)
+
+begin
+  sandbox.eval("'x' * 5_000_000")
+rescue Kobako::MemoryLimitError
+  sandbox.usage.memory_peak  # => the largest delta accepted before the trap
+  sandbox.usage.wall_time    # => seconds spent before the cap fired
+end
+```
+
 ## Capturing stdout and stderr
 
 Guest output is captured into per-invocation buffers and exposed independently from the return value. The buffers cover the full Ruby IO surface — `puts`, `print`, `printf`, `p`, `<<`, and writes through `$stdout` / `$stderr` — all routed through the host-captured WASI pipe.
@@ -177,13 +191,12 @@ end
 |----------------------------------------|--------------------|------------------------------------------------------------------------------------------|
 | `Kobako::TimeoutError`                 | `TrapError`        | Per-invocation `timeout` exhausted                                                       |
 | `Kobako::MemoryLimitError`             | `TrapError`        | Per-invocation `memory_limit` exhausted                                                  |
-| `Kobako::ServiceError::Disconnected`   | `ServiceError`     | RPC target Handle has been invalidated                                                   |
 | `Kobako::HandleTableExhausted`         | `SandboxError`     | Per-invocation Handle counter reached its 2³¹ − 1 cap                                    |
 | `Kobako::BytecodeError`                | `SandboxError`     | `#preload(binary:)` payload failed RITE structural validation at first invocation replay |
 
 ## Capability Handles
 
-When a Service returns a stateful host object (anything beyond `nil` / Boolean / Integer / Float / String / Symbol / Array / Hash), the wire layer transparently allocates an opaque Handle. The guest receives a `Kobako::RPC::Handle` proxy it can use as the target of further RPC calls — but cannot dereference, forge from an integer, or smuggle across runs.
+When a Service returns a stateful host object (anything beyond `nil` / Boolean / Integer / Float / String / Symbol / Array / Hash), the wire layer transparently allocates an opaque Handle. The guest receives a `Kobako::Handle` proxy it can use as the target of further RPC calls — but cannot dereference, forge from an integer, or smuggle across runs.
 
 ```ruby
 class Greeter
@@ -194,18 +207,69 @@ end
 sandbox.define(:Factory).bind(:Make, ->(name) { Greeter.new(name) })
 
 sandbox.eval(<<~RUBY)
-  g = Factory::Make.call("Bob")  # g is a Kobako::RPC::Handle proxy
+  g = Factory::Make.call("Bob")  # g is a Kobako::Handle proxy
   g.greet                         # second RPC, routed to the Greeter
 RUBY
 # => "hi, Bob"
 ```
 
+`Sandbox#run` accepts non-wire-representable host objects as args / kwargs values too: the host walks the argument tree, wraps every non-wire leaf through the same Handle path, and the guest sees a `Kobako::Handle` proxy in its place. This lets you pass framework objects (a Rack `env` Hash containing an `IO`-like body, an active record, an enumerator) into the entrypoint without first marshalling them into primitives.
+
+```ruby
+require "stringio"
+
+sandbox = Kobako::Sandbox.new
+sandbox.preload(code: "Echo = ->(body) { body.read.upcase }", name: :Echo)
+
+sandbox.run(:Echo, StringIO.new("hello world"))
+# => "HELLO WORLD"
+```
+
 Handles are scoped to a single invocation — a Handle obtained in invocation N is invalid in invocation N+1, even on the same Sandbox.
 
 ## Setup-once, run-many
 
 A single Sandbox can serve many invocations. Service bindings and preloaded snippets persist; capability state (Handles, stdout, stderr) resets between invocations.
 
+```
+   ───────────── setup phase (mutable) ─────────────
+
+     sandbox = Kobako::Sandbox.new
+     sandbox.define(:KV).bind(:Lookup, ...)
+     sandbox.preload(code: ..., name: :Adder)
+     sandbox.preload(code: ..., name: :Greeter)
+
+                          │
+                          ▼
+
+   ═════════════════ seal point ═════════════════
+   First #eval or #run freezes the Service registry
+   and snippet table. Further define / preload now
+   raise ArgumentError.
+
+                          │
+                          ▼
+
+   ──────────────── invocation N ───────────────────
+
+     1. allocate fresh mrb_state
+
+     2. replay snippets (in insertion order):
+          :Adder     → defines Adder
+          :Greeter   → defines Greeter
+
+     3. dispatch:  eval(source)  or  run(:Target, *args)
+
+     4. return value to host
+
+     5. discard mrb_state; reset per-invocation state:
+          · Handles invalidated
+          · stdout / stderr buffers cleared
+          · memory delta zeroed
+
+     Services + snippets persist; invocation N+1 repeats.
+```
+
 ```ruby
 sandbox = Kobako::Sandbox.new
 sandbox.define(:Data).bind(:Fetch, ->(id) { records[id] })
@@ -240,6 +304,21 @@ The source form trial-compiles each snippet against a fresh `mrb_state` at prelo
 
 Snippets replay in insertion order, so later snippets can reference constants defined by earlier ones. The snippet table is sealed by the first invocation alongside Service registration; additional `#preload` calls after the first `#eval` or `#run` raise `ArgumentError`.
 
+```
+   per-invocation replay (every #eval / #run, snippets in insertion order):
+
+      fresh mrb_state
+            │
+            ├──▶ replay :Adder            (defines Adder)
+            │
+            ├──▶ replay :Greeter          (defines Greeter)
+            │
+            └──▶ eval(source)  -or-  run(:Target, *args, **kwargs)
+                       │
+                       ▼
+                  return value, then mrb_state discarded
+```
+
 `#run` resolves `target` (Symbol or String, normalized to Symbol) only as a top-level `Object` constant — `::`-segmented names and lowercase forms fail at host pre-flight with `ArgumentError`. A `Kobako::SandboxError` surfaces when the constant is missing or does not respond to `#call`.
 
 ### Choosing between source and bytecode
@@ -273,9 +352,9 @@ The ~600 ms cold start dominates the first Sandbox in a process — wasmtime JIT
 
 | Allocation                                  | Cost                                                                       |
 |---------------------------------------------|----------------------------------------------------------------------------|
-| Process RSS after first `Sandbox.new`       | ~150-180 MB (one-time engine + module + first instance)                    |
+| Process RSS after first `Sandbox.new`       | ~165-195 MB (one-time engine + module + first instance)                    |
 | Per additional Sandbox                      | ~580 KB (Wasm instance + linear memory + WASI capture pipes)               |
-| 1 000 isolated tenants in one process       | ~750 MB total                                                              |
+| 1 000 isolated tenants in one process       | ~765 MB total                                                              |
 
 Use these as upper-bound budgets for capacity planning, not lower bounds — actual RSS shifts ~30% with host process load and macOS allocator state.
 

data/ext/kobako/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "kobako"
-version = "0.3.0"
+version = "0.5.0"
 edition = "2021"
 authors = ["Aotokitsuruya <contact@aotoki.me>"]
 license = "Apache-2.0"

data/ext/kobako/src/lib.rs

@@ -1,10 +1,12 @@
 use magnus::{Error, Ruby};
 
-mod wasm;
+mod runtime;
+mod snapshot;
 
 #[magnus::init]
 fn init(ruby: &Ruby) -> Result<(), Error> {
     let module = ruby.define_module("Kobako")?;
-    wasm::init(ruby, module)?;
+    runtime::init(ruby, module)?;
+    snapshot::init(ruby, module)?;
     Ok(())
 }

data/ext/kobako/src/{wasm → runtime}/cache.rs

@@ -1,22 +1,18 @@
-//! Process-wide caches for the wasmtime [`Engine`] and compiled
-//! [`Module`].
+//! Process-wide caches for the wasmtime `Engine` and compiled
+//! `Module`.
 //!
 //! SPEC.md "Code Organization" pins `ext/` as private and forbids
 //! exposing wasm engine types to the Host App or downstream gems. To
 //! amortise Engine creation and Module JIT compilation across multiple
 //! `Kobako::Sandbox` constructions, the ext keeps a process-scope
 //! shared Engine and a per-path Module cache. Both are transparent to
-//! Ruby callers, who construct an `Instance` via
-//! `Kobako::Wasm::Instance.from_path(...)` and never see Engine or
-//! Module.
+//! Ruby callers, who construct a `Runtime` via
+//! `Kobako::Runtime.from_path(...)` and never see Engine or Module.
 //!
 //! 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.
-//!
-//! [`Engine`]: wasmtime::Engine
-//! [`Module`]: wasmtime::Module
 
 use std::collections::HashMap;
 use std::fs;
@@ -28,7 +24,7 @@ use std::time::Duration;
 use magnus::{Error as MagnusError, Ruby};
 use wasmtime::{Config as WtConfig, Engine as WtEngine, Module as WtModule};
 
-use super::{wasm_err, MODULE_NOT_BUILT_ERROR};
+use super::{setup_err, MODULE_NOT_BUILT_ERROR};
 
 static SHARED_ENGINE: OnceLock<WtEngine> = OnceLock::new();
 static MODULE_CACHE: OnceLock<Mutex<HashMap<PathBuf, WtModule>>> = OnceLock::new();
@@ -55,7 +51,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
-/// thread that drives `engine.increment_epoch()` at [`EPOCH_TICK`]
+/// 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> {
     if let Some(engine) = SHARED_ENGINE.get() {
@@ -66,7 +62,7 @@ pub(crate) fn shared_engine() -> Result<&'static WtEngine, MagnusError> {
     config.epoch_interruption(true);
     let engine = WtEngine::new(&config).map_err(|e| {
         let ruby = Ruby::get().expect("Ruby thread");
-        wasm_err(&ruby, format!("engine init: {}", e))
+        setup_err(&ruby, format!("engine init: {}", e))
     })?;
     let engine = SHARED_ENGINE.get_or_init(|| engine);
     spawn_epoch_ticker(engine.clone());
@@ -75,8 +71,8 @@ pub(crate) fn shared_engine() -> Result<&'static WtEngine, MagnusError> {
 
 /// 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`]
+/// 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();
@@ -92,7 +88,7 @@ fn spawn_epoch_ticker(engine: WtEngine) {
 }
 
 /// Look up `path` in the per-path Module cache, compiling and inserting
-/// the artifact on a miss. Raises `Kobako::Wasm::ModuleNotBuiltError`
+/// the artifact on a miss. Raises `Kobako::ModuleNotBuiltError`
 /// when the file is missing — the headline error for the common
 /// pre-build state on a fresh clone before `rake compile`.
 pub(crate) fn cached_module(path: &Path) -> Result<WtModule, MagnusError> {
@@ -112,16 +108,24 @@ pub(crate) fn cached_module(path: &Path) -> Result<WtModule, MagnusError> {
         return Err(MagnusError::new(
             ruby.get_inner(&MODULE_NOT_BUILT_ERROR),
             format!(
-                "wasm module not found at {}; run `bundle exec rake wasm:build` to build it",
+                "Sandbox runtime not found at {}; run `bundle exec rake wasm:build` to build it",
                 path.display()
             ),
         ));
     }
 
-    let bytes =
-        fs::read(path).map_err(|e| wasm_err(&ruby, format!("read {}: {}", path.display(), e)))?;
+    let bytes = fs::read(path).map_err(|e| {
+        setup_err(
+            &ruby,
+            format!(
+                "failed to read Sandbox runtime at {}: {}",
+                path.display(),
+                e
+            ),
+        )
+    })?;
     let module = WtModule::new(shared_engine()?, &bytes)
-        .map_err(|e| wasm_err(&ruby, format!("compile module: {}", e)))?;
+        .map_err(|e| setup_err(&ruby, format!("failed to compile Sandbox runtime: {}", e)))?;
     cache
         .lock()
         .expect("module cache mutex poisoned")

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

@@ -0,0 +1,91 @@
+//! Per-channel stdout / stderr capture sizing and clipping.
+//!
+//! Two pure helpers shared by the run path (docs/behavior.md B-04): 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
+//! 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.
+pub(super) fn pipe_capacity(cap: Option<usize>) -> usize {
+    match cap {
+        Some(c) => c.saturating_add(1),
+        None => usize::MAX,
+    }
+}
+
+/// Pure slicing core shared by the snapshot readback: given the unclipped
+/// pipe snapshot and the configured cap, return the bytes Ruby should
+/// observe (clipped to `cap`) 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`.
+pub(super) fn clip_capture(raw: &[u8], cap: Option<usize>) -> (&[u8], bool) {
+    match cap {
+        Some(c) if raw.len() > c => (&raw[..c], true),
+        _ => (raw, false),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{clip_capture, pipe_capacity};
+
+    #[test]
+    fn pipe_capacity_adds_one_when_cap_is_set() {
+        assert_eq!(pipe_capacity(Some(5)), 6);
+        assert_eq!(pipe_capacity(Some(0)), 1);
+    }
+
+    #[test]
+    fn pipe_capacity_falls_back_to_usize_max_when_uncapped() {
+        assert_eq!(pipe_capacity(None), usize::MAX);
+    }
+
+    #[test]
+    fn pipe_capacity_saturates_at_usize_max() {
+        assert_eq!(pipe_capacity(Some(usize::MAX)), usize::MAX);
+    }
+
+    #[test]
+    fn clip_capture_returns_full_bytes_when_under_cap() {
+        let (bytes, truncated) = clip_capture(b"abc", Some(5));
+        assert_eq!(bytes, b"abc");
+        assert!(!truncated);
+    }
+
+    #[test]
+    fn clip_capture_does_not_flag_truncation_at_exactly_cap_bytes() {
+        let (bytes, truncated) = clip_capture(b"abcde", Some(5));
+        assert_eq!(bytes, b"abcde");
+        assert!(!truncated);
+    }
+
+    #[test]
+    fn clip_capture_clips_to_cap_and_flags_truncation_on_overflow() {
+        // The pipe is sized `cap + 1`, so the snapshot can be at most
+        // 6 bytes when `cap == 5`; that surface is what triggers the
+        // truncation flag.
+        let (bytes, truncated) = clip_capture(b"abcdef", Some(5));
+        assert_eq!(bytes, b"abcde");
+        assert!(truncated);
+    }
+
+    #[test]
+    fn clip_capture_treats_none_as_uncapped() {
+        let (bytes, truncated) = clip_capture(b"abcdef", None);
+        assert_eq!(bytes, b"abcdef");
+        assert!(!truncated);
+    }
+
+    #[test]
+    fn clip_capture_handles_empty_input() {
+        let (bytes, truncated) = clip_capture(b"", Some(5));
+        assert_eq!(bytes, b"");
+        assert!(!truncated);
+    }
+}

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

@@ -0,0 +1,26 @@
+//! Per-`Runtime` execution configuration.
+//!
+//! The wall-clock and per-channel capture caps a `Kobako::Sandbox`
+//! forwards into `Runtime::from_path`. A plain value carrier owned by the
+//! `Runtime` — distinct from the process-wide engine/module `super::cache`
+//! (which is shared across every Sandbox) and from the per-invocation
+//! `super::invocation::Invocation` (which the wasm engine mutates from
+//! inside a run). These caps are read only by `Runtime` methods between
+//! runs, so they live here.
+
+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`.
+    pub(crate) timeout: Option<Duration>,
+    /// Byte cap for guest stdout capture (docs/behavior.md B-01 / B-04).
+    /// Sizes the per-run `MemoryOutputPipe` and computes the truncation
+    /// flag in `Runtime::build_snapshot`.
+    pub(crate) stdout_limit_bytes: Option<usize>,
+    /// Byte cap for guest stderr capture. Mirror of `stdout_limit_bytes`.
+    pub(crate) stderr_limit_bytes: Option<usize>,
+}