kobako 0.26.0 → 0.28.0

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

@@ -22,8 +22,6 @@ thread_local! {
     static GVL_RELEASED: Cell<bool> = const { Cell::new(false) };
 }
 
-/// Run `f` (one invocation's guest-execution span) and return its value,
-/// releasing the GVL for the span iff `release`. When holding, `f` runs inline.
 pub(crate) fn region<F, R>(release: bool, f: F) -> R
 where
     F: FnOnce() -> R,
@@ -37,10 +35,8 @@ where
     })
 }
 
-/// Run `f` (a guest→host dispatch callback) under the GVL. Re-acquires the GVL
-/// when the enclosing region released it, and runs inline when the GVL is
-/// already held — hold mode, or a nested dispatch whose outer frame re-acquired
-/// it.
+/// Runs inline when the GVL is already held — hold mode, or a nested
+/// dispatch whose outer frame re-acquired it.
 pub(crate) fn reenter<F, R>(f: F) -> R
 where
     F: FnOnce() -> R,
@@ -79,9 +75,8 @@ struct GvlCtx<F, R> {
     result: Option<std::thread::Result<R>>,
 }
 
-/// The `extern "C"` shim the `rb_thread_call_*` functions call: it runs the
-/// erased closure under `catch_unwind` so a panic is captured here rather than
-/// unwinding across the C frame, and stashes the outcome for `call_via`.
+/// Runs the closure under `catch_unwind`, so a panic is captured here rather
+/// than unwinding across the C frame.
 unsafe extern "C" fn trampoline<F, R>(data: *mut c_void) -> *mut c_void
 where
     F: FnOnce() -> R,
@@ -92,9 +87,6 @@ where
     ptr::null_mut()
 }
 
-/// Drive `f` through one of the `rb_thread_call_*` entry points (`invoke`),
-/// erasing it to the C callback shape and re-raising on the caller's thread any
-/// panic the trampoline caught.
 fn call_via<F, R>(
     f: F,
     invoke: impl FnOnce(unsafe extern "C" fn(*mut c_void) -> *mut c_void, *mut c_void) -> *mut c_void,

data/ext/kobako/src/runtime.rs

@@ -15,13 +15,7 @@
 //! `kobako-wasmtime` crate behind the `kobako_runtime` contract; no wasm
 //! engine type reaches this crate or the Host App.
 //!
-//! Module layout — one responsibility per file:
-//!
-//! * `bridge` — the magnus dispatch bridge: `RubyDispatchHandler` plus the
-//!   frame-scoped `GuestYielder` Ruby class.
-//! * `errors` — the single boundary mapping the neutral `Trap` /
-//!   `SetupError` channels onto the `Kobako::*` classes for a failure that
-//!   never produced a `Snapshot` (a could-not-start fault).
+//! Each module holds one responsibility and opens with its own doc.
 
 mod bridge;
 mod errors;
@@ -29,7 +23,7 @@ mod gvl;
 
 use magnus::{
     function, method, prelude::*, typed_data::DataTypeFunctions, value::Opaque,
-    Error as MagnusError, RArray, RModule, RString, Ruby, Symbol, TypedData, Value,
+    Error as MagnusError, Exception, RArray, RModule, RString, Ruby, Symbol, TypedData, Value,
 };
 
 use std::path::Path;
@@ -37,11 +31,10 @@ use std::sync::Arc;
 use std::time::Duration;
 
 use kobako_runtime::dispatch::DispatchHandler;
-use kobako_runtime::error::Trap;
 use kobako_runtime::profile::Profile;
-use kobako_runtime::runtime::{Entry, Frames, Runtime as ContractRuntime};
-use kobako_runtime::snapshot::{Capture, Completion, Snapshot as RuntimeSnapshot, Usage};
-use kobako_transport::envelope::{Bindings, Outcome, Run, Snippet, Snippets};
+use kobako_runtime::runtime::{Entry, Runtime as ContractRuntime};
+use kobako_runtime::snapshot::{Completion, Snapshot as RuntimeSnapshot};
+use kobako_transport::envelope::{Bindings, Flag, Outcome, Preamble, Snippet, Snippets};
 use kobako_wasmtime::{Config, Driver};
 
 /// A Panic's fields as they cross to Ruby: origin, class, message,
@@ -50,40 +43,24 @@ use kobako_wasmtime::{Config, Driver};
 /// shape, matching the `Kobako::Outcome::panic_fields` alias.
 type PanicFields = (String, String, String, Vec<String>, Vec<String>);
 
-/// Copy the bytes of `s` into a fresh `Vec<u8>`. Single safe entry to
-/// what would otherwise be an inline `unsafe { rstring.as_slice() }
-/// .to_vec()` duplicated at every host-↔-guest boundary. The borrow
-/// does not outlive this call, so no Ruby allocation can move the
-/// underlying RString between the borrow and the copy — the safety
-/// invariant the inline form relied on is established once here.
+/// The one place the boundary borrows an RString's bytes: the borrow does
+/// not outlive this call, so no Ruby allocation can move the RString
+/// between the borrow and the copy.
 fn rstring_to_vec(s: RString) -> Vec<u8> {
     // SAFETY: see item doc.
     unsafe { s.as_slice() }.to_vec()
 }
 
-/// Frame the Frame 1 preamble from the Service registry's bind paths.
-/// The core envelope's byte layout lives on this side of the boundary,
-/// so the registry stays a registry and never holds a wire image.
-fn frame_preamble(paths: RArray) -> Result<Vec<u8>, MagnusError> {
-    Ok(Bindings {
-        paths: paths.to_vec()?,
-    }
-    .encode())
-}
-
-/// Frame the Frame 3 snippet table from the registry's entries — one
-/// `[kind, name, body]` triple each, `kind` a Symbol naming the form so
-/// the wire's discriminant byte stays here. An off-ladder kind raises
-/// rather than defaulting, the same fail-closed posture `from_path`
-/// takes on its Symbol options.
-fn frame_snippets(ruby: &Ruby, entries: RArray) -> Result<Vec<u8>, MagnusError> {
-    let mut frame = Snippets {
+/// `kind` arrives as a Symbol so the registry never names the wire's
+/// discriminant; an off-ladder kind raises rather than defaulting.
+fn snippets_from(ruby: &Ruby, entries: RArray) -> Result<Snippets, MagnusError> {
+    let mut snippets = Snippets {
         entries: Vec::with_capacity(entries.len()),
     };
     for index in 0..entries.len() as isize {
         let entry: RArray = entries.entry(index)?;
         let kind: Symbol = entry.entry(0)?;
-        frame.entries.push(match kind.name()?.as_ref() {
+        snippets.entries.push(match kind.name()?.as_ref() {
             "source" => Snippet::Source {
                 name: entry.entry(1)?,
                 body: entry.entry(2)?,
@@ -99,7 +76,30 @@ fn frame_snippets(ruby: &Ruby, entries: RArray) -> Result<Vec<u8>, MagnusError>
             }
         });
     }
-    Ok(frame.encode())
+    Ok(snippets)
+}
+
+/// One owner for the Preamble every guest entry reads, so an invocation
+/// and a compile cannot drift in what they send.
+fn preamble_from(
+    ruby: &Ruby,
+    paths: Vec<String>,
+    snippets: RArray,
+    flags: RArray,
+) -> Result<Preamble, MagnusError> {
+    let mut preamble = Preamble::default();
+    preamble.bindings = Bindings { paths };
+    preamble.snippets = snippets_from(ruby, snippets)?;
+    preamble.flags = flags
+        .to_vec::<(String, String, bool)>()?
+        .into_iter()
+        .map(|(name, value, critical)| Flag {
+            name,
+            value,
+            critical,
+        })
+        .collect();
+    Ok(preamble)
 }
 
 // ---------------------------------------------------------------------------
@@ -113,9 +113,10 @@ pub fn init(ruby: &Ruby, kobako: RModule) -> Result<(), MagnusError> {
 
     let runtime = kobako.define_class("Runtime", ruby.class_object())?;
     runtime.define_singleton_method("from_path", function!(Runtime::from_path, 7))?;
-    runtime.define_method("eval", method!(Runtime::eval, 4))?;
-    runtime.define_method("run", method!(Runtime::run, 5))?;
+    runtime.define_method("eval", method!(Runtime::eval, 5))?;
+    runtime.define_method("run", method!(Runtime::run, 6))?;
     runtime.define_method("profile", method!(Runtime::profile, 0))?;
+    runtime.define_method("compile", method!(Runtime::compile, 3))?;
     // The guest re-enters for a block yield through a frame-scoped
     // `Kobako::Runtime::GuestYielder` the dispatcher hands the Proc, not a
     // method on Runtime.
@@ -124,9 +125,7 @@ pub fn init(ruby: &Ruby, kobako: RModule) -> Result<(), MagnusError> {
     // Snapshot — the per-invocation result object each entry point returns.
     let snapshot = runtime.define_class("Snapshot", ruby.class_object())?;
     snapshot.define_method("outcome", method!(Snapshot::outcome, 0))?;
-    snapshot.define_method("trapped?", method!(Snapshot::trapped, 0))?;
-    snapshot.define_method("trap_kind", method!(Snapshot::trap_kind, 0))?;
-    snapshot.define_method("trap_message", method!(Snapshot::trap_message, 0))?;
+    snapshot.define_method("trap_error", method!(Snapshot::trap_error, 0))?;
     snapshot.define_method("wall_time", method!(Snapshot::wall_time, 0))?;
     snapshot.define_method("memory_peak", method!(Snapshot::memory_peak, 0))?;
     snapshot.define_method("stdout", method!(Snapshot::stdout, 0))?;
@@ -157,22 +156,8 @@ struct Runtime {
 impl DataTypeFunctions for Runtime {}
 
 impl Runtime {
-    /// Construct a Runtime from a wasm file path, using the process-wide
-    /// shared Engine and per-path Module / InstancePre caches. The single
-    /// Ruby-facing constructor for `Kobako::Runtime` — Engine and Module
-    /// are never visible to Ruby.
-    ///
-    /// `timeout_seconds` is the wall-clock cap in seconds
-    /// (`None` disables); `memory_limit` is the linear-memory cap in
-    /// bytes (`None` disables); `stdout_limit` / `stderr_limit`
-    /// are the per-channel output caps (`None`
-    /// disables); `profile` is the isolation rung the driver builds
-    /// (`:permissive` / `:hermetic`); `gvl` is the scheduling mode
-    /// (`:hold` / `:release`) deciding whether each invocation releases
-    /// the GVL for its guest span. All six are validated by the caller
-    /// (`Kobako::Sandbox`); this method only refuses non-finite or
-    /// non-positive timeouts, off-ladder profiles, and unrecognized gvl
-    /// modes as a defence in depth.
+    /// The only Ruby-facing constructor, so Engine and Module are never
+    /// visible to Ruby.
     fn from_path(
         path: String,
         timeout_seconds: Option<f64>,
@@ -246,90 +231,103 @@ impl Runtime {
     // Run-path methods. Each takes the run's dispatch handler as its first
     // argument and returns a `Snapshot` for any completed invocation —
     // success or trap alike. Only a could-not-start fault (a missing export
-    // or a fault before the export call) raises a `Kobako::TrapError`
-    // directly, since it yields no `Snapshot`.
+    // or a fault before the export call) raises directly, as the class
+    // `errors::to_magnus` gives its cause, since it yields no `Snapshot`.
     // -----------------------------------------------------------------
 
-    /// One-shot mruby source execution (`#eval`). Builds the dispatch
-    /// handler from `dispatch` (the per-invocation Proc), frames the two
-    /// stdin invocation frames from the registry state (`paths`,
-    /// `snippets`), hands them and the source to the driver, and returns
-    /// the run's `Snapshot`.
     fn eval(
         &self,
         dispatch: Value,
         paths: RArray,
-        source: RString,
         snippets: RArray,
+        flags: RArray,
+        source: RString,
     ) -> Result<Snapshot, MagnusError> {
-        let ruby = Ruby::get().expect("Ruby thread");
-        let handler = build_handler(dispatch);
-        let preamble = frame_preamble(paths)?;
         let source = rstring_to_vec(source);
-        let snippets = frame_snippets(&ruby, snippets)?;
-        // Release the GVL around the guest span iff this Sandbox asks for it;
-        // the closure touches no Ruby VALUE (the driver is magnus-free, and a
-        // guest→host dispatch re-acquires the GVL through the bridge).
-        let result = gvl::region(self.release_gvl, || {
-            self.driver.invoke(
-                Entry::Eval { source: &source },
-                Frames {
-                    preamble: &preamble,
-                    snippets: &snippets,
-                },
-                handler,
-            )
-        });
-        let snapshot = result.map_err(|e| errors::to_magnus(&ruby, e))?;
-        Ok(Snapshot::from(snapshot))
+        self.invoke(
+            dispatch,
+            paths,
+            snippets,
+            flags,
+            Entry::Eval { source: &source },
+        )
     }
 
-    /// Execute one entrypoint dispatch (`__kobako_run`) and return its
-    /// `Snapshot`.
-    ///
-    /// The two-frame stdin protocol (preamble + snippets; no user source
-    /// frame — docs/wire-codec.md § Invocation channels) plus the Run
-    /// envelope copied into guest linear memory — `entrypoint` routes it,
-    /// `payload` feeds it, and this side frames the two together. Cap
-    /// semantics match `#eval`.
     fn run(
         &self,
         dispatch: Value,
         paths: RArray,
         snippets: RArray,
+        flags: RArray,
         entrypoint: String,
         payload: RString,
+    ) -> Result<Snapshot, MagnusError> {
+        self.invoke(
+            dispatch,
+            paths,
+            snippets,
+            flags,
+            Entry::Run {
+                entrypoint: &entrypoint,
+                payload: rstring_to_vec(payload),
+            },
+        )
+    }
+
+    /// One owner for the wiring both verbs share, so a Preamble or handler
+    /// change cannot drift between them.
+    fn invoke(
+        &self,
+        dispatch: Value,
+        paths: RArray,
+        snippets: RArray,
+        flags: RArray,
+        entry: Entry<'_>,
     ) -> Result<Snapshot, MagnusError> {
         let ruby = Ruby::get().expect("Ruby thread");
+        let verb = match entry {
+            Entry::Eval { .. } => "eval",
+            Entry::Run { .. } => "run",
+        };
         let handler = build_handler(dispatch);
-        let preamble = frame_preamble(paths)?;
-        let snippets = frame_snippets(&ruby, snippets)?;
-        let envelope = Run {
-            entrypoint,
-            payload: rstring_to_vec(payload),
-        }
-        .encode();
+        let preamble = preamble_from(&ruby, paths.to_vec()?, snippets, flags)?;
         // Release the GVL around the guest span iff this Sandbox asks for it;
-        // see the note in `#eval`.
+        // the closure touches no Ruby VALUE (the driver is magnus-free, and a
+        // guest→host dispatch re-acquires the GVL through the bridge).
         let result = gvl::region(self.release_gvl, || {
-            self.driver.invoke(
-                Entry::Run {
-                    envelope: &envelope,
-                },
-                Frames {
-                    preamble: &preamble,
-                    snippets: &snippets,
-                },
-                handler,
-            )
+            self.driver.invoke(entry, &preamble, handler)
         });
-        let snapshot = result.map_err(|e| errors::to_magnus(&ruby, e))?;
-        Ok(Snapshot::from(snapshot))
+        result
+            .map(|snapshot| Snapshot(snapshot, verb))
+            .map_err(|e| errors::to_magnus(&ruby, e))
+    }
+
+    /// The bytecode of the source snippets, one binary String each in
+    /// order, or `nil` when the guest compiled nothing; no failure raises,
+    /// since the Sandbox keeps the source either way. Takes the Preamble an
+    /// invocation sends, `paths` included, so the driver can tell whether
+    /// the bytecode still fits it; no dispatch handler is bound, since
+    /// compiling runs no script.
+    fn compile(
+        &self,
+        paths: RArray,
+        snippets: RArray,
+        flags: RArray,
+    ) -> Result<Option<RArray>, MagnusError> {
+        let ruby = Ruby::get().expect("Ruby thread");
+        let preamble = preamble_from(&ruby, paths.to_vec()?, snippets, flags)?;
+        let bytecodes = gvl::region(self.release_gvl, || self.driver.compile(&preamble));
+        Ok(bytecodes.map(|bytecodes| {
+            ruby.ary_from_iter(
+                bytecodes
+                    .iter()
+                    .map(|bytecode| ruby.str_from_slice(bytecode)),
+            )
+        }))
     }
 
-    /// Return the isolation profile the driver built, as a Symbol
-    /// (`:hermetic` / `:permissive`) — the declaration the Sandbox
-    /// compares against the posture its `profile:` option requested.
+    /// The driver's declaration, which the Sandbox checks against the
+    /// posture its `profile:` option requested.
     fn profile(&self) -> Symbol {
         let ruby = Ruby::get().expect("Ruby thread");
         match self.driver.profile() {
@@ -339,11 +337,9 @@ impl Runtime {
     }
 }
 
-/// Build the dispatch handler for one invocation from the per-call `dispatch`
-/// Proc. A `nil` Proc yields no handler. The Proc stays GC-rooted for the
-/// duration of the synchronous `#eval` / `#run` call as a live method
-/// argument on the Ruby stack, so the driver only borrows it (the safety
-/// contract on `kobako_runtime::runtime::Runtime`).
+/// The Proc stays GC-rooted for the synchronous `#eval` / `#run` call as a
+/// live method argument on the Ruby stack, so the driver only borrows it
+/// (the safety contract on `kobako_runtime::runtime::Runtime`).
 fn build_handler(dispatch: Value) -> Option<Arc<dyn DispatchHandler>> {
     if dispatch.is_nil() {
         return None;
@@ -358,130 +354,91 @@ fn build_handler(dispatch: Value) -> Option<Arc<dyn DispatchHandler>> {
 /// driver produced, exposed as `Kobako::Runtime::Snapshot`. Usage and the
 /// two output captures are present on every outcome, so the trap path
 /// carries them just like the value path; the completion is read as either
-/// the outcome bytes (`#outcome`) or a trap (`#trapped?` / `#trap_kind` /
-/// `#trap_message`), and the Sandbox layer maps a trap onto its
-/// `Kobako::TrapError` family.
+/// the Outcome (`#outcome`) or a trap (`#trap_error`). The verb names the
+/// invocation, so an unsupported one says which operation is lacking.
 #[derive(TypedData)]
 #[magnus(class = "Kobako::Runtime::Snapshot", free_immediately, size)]
-struct Snapshot {
-    completion: Completion,
-    stdout: Capture,
-    stderr: Capture,
-    usage: Usage,
-}
+struct Snapshot(RuntimeSnapshot, &'static str);
 
 impl DataTypeFunctions for Snapshot {}
 
-impl From<RuntimeSnapshot> for Snapshot {
-    fn from(snapshot: RuntimeSnapshot) -> Self {
-        let RuntimeSnapshot {
-            completion,
-            stdout,
-            stderr,
-            usage,
-        } = snapshot;
-        Self {
-            completion,
-            stdout,
-            stderr,
-            usage,
-        }
-    }
-}
-
 impl Snapshot {
-    /// One completed run's outcome, already split off the core envelope:
-    /// `[kind, payload, panic]`. `kind` names the arm — `:ok`,
-    /// `:panic`, `:absent` (nothing written), or `:malformed` (bytes the
-    /// envelope cannot frame). `payload` is the invocation's
-    /// codec-encoded value, carried only by `:ok`; every other arm
-    /// answers empty. `panic` carries the Panic's own fields on `:panic`
-    /// and is `nil` otherwise, so the Ruby side maps a failure onto its
-    /// error taxonomy without decoding a payload byte.
-    ///
-    /// A trap answers `:absent` — `#trapped?` is the authoritative
-    /// discriminator there and this is never read.
-    fn outcome(&self) -> (Symbol, RString, Option<PanicFields>) {
+    /// Already split off the core envelope, so the Ruby side maps a failure
+    /// onto its error taxonomy without decoding a payload byte: the ok
+    /// arm's payload, or a Panic's fields beside an empty payload. A trap
+    /// has no Outcome; `#trap_error` is the discriminator there.
+    fn outcome(&self) -> Result<(RString, Option<PanicFields>), MagnusError> {
         let ruby = Ruby::get().expect("Ruby thread");
-        let empty = || ruby.str_from_slice(&[]);
-        let Completion::Outcome(bytes) = &self.completion else {
-            return (ruby.to_symbol("absent"), empty(), None);
-        };
-        match Outcome::decode(bytes) {
-            Ok(Outcome::Ok(value)) => (ruby.to_symbol("ok"), ruby.str_from_slice(&value), None),
-            Ok(Outcome::Panic(panic)) => (
-                ruby.to_symbol("panic"),
-                empty(),
+        match &self.0.completion {
+            Completion::Outcome(Outcome::Ok(value)) => Ok((ruby.str_from_slice(value), None)),
+            Completion::Outcome(Outcome::Panic(panic)) => Ok((
+                ruby.str_from_slice(&[]),
                 Some((
                     panic.origin.name().to_owned(),
-                    panic.error.name,
-                    panic.error.message,
-                    panic.error.backtrace,
-                    panic.available,
+                    panic.error.name.clone(),
+                    panic.error.message.clone(),
+                    panic.error.backtrace.clone(),
+                    panic.available.clone(),
                 )),
-            ),
-            Err(_) if bytes.is_empty() => (ruby.to_symbol("absent"), empty(), None),
-            Err(_) => (ruby.to_symbol("malformed"), empty(), None),
+            )),
+            // The Guest Binary answered rather than broke, so it reads as
+            // the Sandbox's failure, worded by the host.
+            Completion::Outcome(Outcome::Unsupported(_)) => Ok((
+                ruby.str_from_slice(&[]),
+                Some((
+                    "sandbox".to_owned(),
+                    "Kobako::SandboxError".to_owned(),
+                    format!(
+                        "the Sandbox runtime does not support #{}; \
+                         rebuild it against the kobako version in use",
+                        self.1
+                    ),
+                    Vec::new(),
+                    Vec::new(),
+                )),
+            )),
+            Completion::Trap(_) => Err(MagnusError::new(
+                ruby.exception_runtime_error(),
+                "a trapped run has no outcome",
+            )),
         }
     }
 
-    /// `true` iff the invocation completed via an engine trap.
-    fn trapped(&self) -> bool {
-        matches!(self.completion, Completion::Trap(_))
-    }
-
-    /// The trap's neutral kind as a Symbol (`:timeout` / `:memory_limit` /
-    /// `:trap`), or `nil` on a completed run. The Sandbox maps this onto the
-    /// named `Kobako::TrapError` subclass.
-    fn trap_kind(&self) -> Option<Symbol> {
+    /// Unraised, so the Sandbox layer can attach the run's Execution before
+    /// raising it.
+    fn trap_error(&self) -> Result<Option<Exception>, MagnusError> {
+        let Completion::Trap(trap) = &self.0.completion else {
+            return Ok(None);
+        };
         let ruby = Ruby::get().expect("Ruby thread");
-        match &self.completion {
-            Completion::Trap(Trap::Timeout(_)) => Some(ruby.to_symbol("timeout")),
-            Completion::Trap(Trap::MemoryLimit(_)) => Some(ruby.to_symbol("memory_limit")),
-            // A cap this frontend has no named subclass for is still a
-            // trap; the base class is what the taxonomy owes it.
-            Completion::Trap(_) => Some(ruby.to_symbol("trap")),
-            Completion::Outcome(_) => None,
-        }
-    }
-
-    /// The trap's message, or `nil` on a completed run.
-    fn trap_message(&self) -> Option<String> {
-        match &self.completion {
-            Completion::Trap(trap) => Some(trap.to_string()),
-            Completion::Outcome(_) => None,
-        }
+        errors::trap_class(&ruby, trap)
+            .new_instance((trap.to_string(),))
+            .map(Some)
     }
 
-    /// Wall-clock seconds the guest export call spent inside wasmtime.
     fn wall_time(&self) -> f64 {
-        self.usage.wall_time
+        self.0.usage.wall_time
     }
 
-    /// High-water `memory.grow` delta in bytes past the entry-time baseline.
     fn memory_peak(&self) -> usize {
-        self.usage.memory_peak
+        self.0.usage.memory_peak
     }
 
-    /// Bytes captured on the guest's stdout channel, clipped to the cap.
     fn stdout(&self) -> RString {
         let ruby = Ruby::get().expect("Ruby thread");
-        ruby.str_from_slice(&self.stdout.bytes)
+        ruby.str_from_slice(&self.0.stdout.bytes)
     }
 
-    /// `true` iff the stdout channel reached its cap during this run.
     fn stdout_truncated(&self) -> bool {
-        self.stdout.truncated
+        self.0.stdout.truncated
     }
 
-    /// Bytes captured on the guest's stderr channel, clipped to the cap.
     fn stderr(&self) -> RString {
         let ruby = Ruby::get().expect("Ruby thread");
-        ruby.str_from_slice(&self.stderr.bytes)
+        ruby.str_from_slice(&self.0.stderr.bytes)
     }
 
-    /// `true` iff the stderr channel reached its cap during this run.
     fn stderr_truncated(&self) -> bool {
-        self.stderr.truncated
+        self.0.stderr.truncated
     }
 }

data/lib/kobako/capture.rb

@@ -1,10 +1,7 @@
 # frozen_string_literal: true
 
 module Kobako
-  # What one invocation wrote to stdout or stderr, up to that channel's
-  # cap, together with whether it wrote past the cap. Frozen, so the bytes
-  # and the flag always travel together.
-  class Capture
+  class Capture # :nodoc:
     attr_reader :bytes
 
     # The bytes read as UTF-8 when they are valid UTF-8, and as binary