kobako 0.27.0 → 0.29.0

data/ext/kobako/src/runtime.rs

@@ -2,11 +2,11 @@
 //!
 //! The Ruby-visible classes are
 //!
-//!   Kobako::Runtime           — wraps a `kobako_wasmtime::Driver`
-//!   Kobako::Runtime::Snapshot — one invocation's completion + captures + usage
+//!   Kobako::Runtime  — wraps a `kobako_wasmtime::Driver`
+//!   Kobako::Snapshot — one invocation's completion + captures + usage
 //!
 //! `Kobako::Runtime` is constructed via `Kobako::Runtime.from_path(path,
-//! timeout, memory_limit, stdout_limit, stderr_limit, profile)`. Every
+//! **options)`, the options keyed by the `Kobako::SandboxOptions` members. Every
 //! invocation (`#eval` / `#run`) takes that run's dispatch handler as a call
 //! argument, instantiates a fresh instance, and returns a `Snapshot` — the
 //! whole per-invocation result — so the Runtime holds no per-invocation
@@ -15,21 +15,20 @@
 //! `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;
+mod escape;
+mod filesystem;
 mod gvl;
+mod pinned_value;
+mod snapshot;
 
 use magnus::{
-    function, method, prelude::*, typed_data::DataTypeFunctions, value::Opaque,
-    Error as MagnusError, RArray, RModule, RString, Ruby, Symbol, TypedData, Value,
+    function, method, prelude::*, scan_args::get_kwargs, typed_data::DataTypeFunctions,
+    value::Opaque, Error as MagnusError, RArray, RHash, RModule, RString, Ruby, Symbol, TypedData,
+    Value,
 };
 
 use std::path::Path;
@@ -37,53 +36,31 @@ 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_transport::envelope::{Bindings, Flag, Preamble, Snippet, Snippets};
 use kobako_wasmtime::{Config, Driver};
 
-/// A Panic's fields as they cross to Ruby: origin, class, message,
-/// backtrace, and the names the invocation could have used in place of the
-/// one it named. Named so the Ruby side reads them positionally against one
-/// shape, matching the `Kobako::Outcome::panic_fields` alias.
-type PanicFields = (String, String, String, Vec<String>, Vec<String>);
+use snapshot::Snapshot;
 
-/// 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 to_snippets(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. An invocation's setup
+/// and a compile's preamble both open with its paths, snippets, and flags.
+fn to_preamble(ruby: &Ruby, parts: RArray) -> Result<Preamble, MagnusError> {
+    let paths: RArray = parts.entry(0)?;
+    let flags: RArray = parts.entry(2)?;
+    let mut preamble = Preamble::default();
+    preamble.bindings = Bindings {
+        paths: paths.to_vec()?,
+    };
+    preamble.snippets = to_snippets(ruby, parts.entry(1)?)?;
+    preamble.flags = flags
+        .to_vec::<(String, String, bool)>()?
+        .into_iter()
+        .map(|(name, value, critical)| Flag {
+            name,
+            value,
+            critical,
+        })
+        .collect();
+    Ok(preamble)
 }
 
 // ---------------------------------------------------------------------------
@@ -112,27 +112,27 @@ pub fn init(ruby: &Ruby, kobako: RModule) -> Result<(), MagnusError> {
     // in `runtime/errors.rs` — no intermediate hierarchy is registered.
 
     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_singleton_method("from_path", function!(Runtime::from_path, 2))?;
+    runtime.define_method("eval", method!(Runtime::eval, 3))?;
+    runtime.define_method("run", method!(Runtime::run, 4))?;
     runtime.define_method("profile", method!(Runtime::profile, 0))?;
+    runtime.define_method("compile", method!(Runtime::compile, 1))?;
+    runtime.define_singleton_method("validate_mount!", function!(filesystem::validate_mount, 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.
-    bridge::register(runtime)?;
+    // `Kobako::GuestYielder` the dispatcher hands the Proc, not a method on
+    // Runtime.
+    bridge::register(kobako)?;
+    filesystem::register(ruby, kobako)?;
 
     // 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("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))?;
-    snapshot.define_method("stdout_truncated?", method!(Snapshot::stdout_truncated, 0))?;
-    snapshot.define_method("stderr", method!(Snapshot::stderr, 0))?;
-    snapshot.define_method("stderr_truncated?", method!(Snapshot::stderr_truncated, 0))?;
+    snapshot::register(ruby, kobako)?;
+
+    // A wrapped class is otherwise looked up the first time an object is
+    // wrapped, through a Ruby call that a pending interrupt would turn into
+    // a panic; a signal arriving during a process's first run waits for
+    // exactly that moment.
+    Runtime::class(ruby);
+    Snapshot::class(ruby);
 
     Ok(())
 }
@@ -157,49 +157,62 @@ 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.
-    fn from_path(
-        path: String,
-        timeout_seconds: Option<f64>,
-        memory_limit: Option<usize>,
-        stdout_limit: Option<usize>,
-        stderr_limit: Option<usize>,
-        profile: Symbol,
-        gvl: Symbol,
-    ) -> Result<Self, MagnusError> {
+    /// The only Ruby-facing constructor, so Engine and Module are never
+    /// visible to Ruby. Every option is a required keyword: the defaults
+    /// belong to `Kobako::SandboxOptions`, which names the keys.
+    fn from_path(path: String, options: RHash) -> Result<Self, MagnusError> {
         let ruby = Ruby::get().expect("Ruby thread");
-        let timeout = match timeout_seconds {
-            None => None,
-            Some(secs) if secs.is_finite() && secs > 0.0 => Some(Duration::from_secs_f64(secs)),
-            Some(secs) => {
-                // An invalid cap argument is a Host App
-                // programming error and raises `ArgumentError`, outside the
-                // construction-failure `SetupError` branch. `SandboxOptions`
-                // is the primary guard (it never lets a bad timeout reach
-                // here); this is defence-in-depth for direct `from_path` calls.
-                return Err(MagnusError::new(
-                    ruby.exception_arg_error(),
-                    format!("timeout must be > 0 and finite, got {secs} seconds"),
-                ));
-            }
+        type Options = (
+            Option<f64>,
+            Option<f64>,
+            Option<usize>,
+            Option<usize>,
+            Option<usize>,
+            Option<usize>,
+            Symbol,
+            Symbol,
+        );
+        let options = get_kwargs::<_, Options, (), ()>(
+            options,
+            &[
+                "timeout",
+                "setup_timeout",
+                "memory_limit",
+                "stdout_limit",
+                "stderr_limit",
+                "open_file_limit",
+                "profile",
+                "gvl",
+            ],
+            &[],
+        )?;
+        let (
+            timeout_seconds,
+            setup_timeout_seconds,
+            memory_limit,
+            stdout_limit,
+            stderr_limit,
+            open_file_limit,
+            profile,
+            gvl,
+        ) = options.required;
+        // An invalid cap argument is a Host App programming error and
+        // raises `ArgumentError`, outside the construction-failure
+        // `SetupError` branch. `SandboxOptions` is the primary guard (it
+        // never lets a bad timeout reach here); this is defence-in-depth
+        // for direct `from_path` calls.
+        let to_duration = |seconds: Option<f64>, name: &str| match seconds {
+            None => Ok(None),
+            Some(secs) if secs.is_finite() && secs > 0.0 => Ok(Some(Duration::from_secs_f64(secs))),
+            Some(secs) => Err(MagnusError::new(
+                ruby.exception_arg_error(),
+                format!("{name} must be > 0 and finite, got {secs} seconds"),
+            )),
         };
+        let timeout = to_duration(timeout_seconds, "timeout")?;
+        let setup_timeout = to_duration(setup_timeout_seconds, "setup_timeout")?;
         // Fail closed on an off-ladder rung: an unrecognized posture must
-        // never fall back to a grant. Same defence-in-depth posture as the
+        // never fall back to a weaker posture. Same defence in depth as the
         // timeout guard above — `SandboxOptions` is the primary validator.
         let profile = match profile.name()?.as_ref() {
             "hermetic" => Profile::Hermetic,
@@ -225,17 +238,16 @@ impl Runtime {
             }
         };
 
-        let driver = Driver::new(
-            Path::new(&path),
-            Config {
-                timeout,
-                memory_limit,
-                stdout_limit,
-                stderr_limit,
-                profile,
-            },
-        )
-        .map_err(|e| errors::setup_to_magnus(&ruby, e))?;
+        let mut config = Config::default();
+        config.timeout = timeout;
+        config.setup_timeout = setup_timeout;
+        config.memory_limit = memory_limit;
+        config.stdout_limit = stdout_limit;
+        config.stderr_limit = stderr_limit;
+        config.open_file_limit = open_file_limit;
+        config.profile = profile;
+        let driver =
+            Driver::new(Path::new(&path), config).map_err(|e| errors::setup_to_magnus(&ruby, e))?;
         Ok(Self {
             driver,
             release_gvl,
@@ -246,90 +258,90 @@ 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`.
+    //
+    // `setup` is the invocation's `[paths, snippets, flags, mounts]`: the
+    // Preamble's three parts, then the Mounts as
+    // `filesystem::to_grants` reads them.
     // -----------------------------------------------------------------
 
-    /// 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,
+        setup: RArray,
         source: RString,
-        snippets: RArray,
     ) -> 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, setup, 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,
+        setup: RArray,
         entrypoint: String,
         payload: RString,
+    ) -> Result<Snapshot, MagnusError> {
+        self.invoke(
+            dispatch,
+            setup,
+            Entry::Run {
+                entrypoint: &entrypoint,
+                payload: rstring_to_vec(payload),
+            },
+        )
+    }
+
+    /// One owner for the wiring both verbs share, so a Preamble, a Grant,
+    /// or a handler change cannot drift between them.
+    fn invoke(
+        &self,
+        dispatch: Value,
+        setup: 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 = to_preamble(&ruby, setup)?;
+        let (grants, _pins) = filesystem::to_grants(&ruby, setup.entry(3)?)?;
         // 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, or a mount's block, re-acquires the GVL).
         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, &grants)
         });
-        let snapshot = result.map_err(|e| errors::to_magnus(&ruby, e))?;
-        Ok(Snapshot::from(snapshot))
+        escape::resume()?;
+        result
+            .map(|snapshot| Snapshot::new(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, preamble: RArray) -> Result<Option<RArray>, MagnusError> {
+        let ruby = Ruby::get().expect("Ruby thread");
+        let preamble = to_preamble(&ruby, preamble)?;
+        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 +351,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;
@@ -353,135 +363,3 @@ fn build_handler(dispatch: Value) -> Option<Arc<dyn DispatchHandler>> {
             as Arc<dyn DispatchHandler>,
     )
 }
-
-/// One invocation's result at the Ruby boundary — the whole `Snapshot` the
-/// 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.
-#[derive(TypedData)]
-#[magnus(class = "Kobako::Runtime::Snapshot", free_immediately, size)]
-struct Snapshot {
-    completion: Completion,
-    stdout: Capture,
-    stderr: Capture,
-    usage: Usage,
-}
-
-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>) {
-        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(),
-                Some((
-                    panic.origin.name().to_owned(),
-                    panic.error.name,
-                    panic.error.message,
-                    panic.error.backtrace,
-                    panic.available,
-                )),
-            ),
-            Err(_) if bytes.is_empty() => (ruby.to_symbol("absent"), empty(), None),
-            Err(_) => (ruby.to_symbol("malformed"), empty(), None),
-        }
-    }
-
-    /// `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> {
-        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,
-        }
-    }
-
-    /// Wall-clock seconds the guest export call spent inside wasmtime.
-    fn wall_time(&self) -> f64 {
-        self.usage.wall_time
-    }
-
-    /// High-water `memory.grow` delta in bytes past the entry-time baseline.
-    fn memory_peak(&self) -> usize {
-        self.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)
-    }
-
-    /// `true` iff the stdout channel reached its cap during this run.
-    fn stdout_truncated(&self) -> bool {
-        self.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)
-    }
-
-    /// `true` iff the stderr channel reached its cap during this run.
-    fn stderr_truncated(&self) -> bool {
-        self.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