kobako 0.12.2 → 0.13.0

data/ext/kobako/src/runtime.rs

@@ -5,7 +5,7 @@
 //!   Kobako::Runtime — wraps a `kobako_wasmtime::Driver` + the Ruby seams
 //!
 //! constructed via `Kobako::Runtime.from_path(path, timeout, memory_limit,
-//! stdout_limit, stderr_limit)`. Every invocation (`#eval` / `#run`)
+//! stdout_limit, stderr_limit, profile)`. Every invocation (`#eval` / `#run`)
 //! instantiates a fresh instance and discards the whole Store afterwards —
 //! the per-invocation instance discipline. The run mechanics —
 //! engine/module caches, caps, trap classification — live in the
@@ -21,24 +21,25 @@
 //!
 //! This file owns the `Kobako::Runtime` magnus class itself — the Ruby
 //! init() that registers the class, the byte↔`RString` shuttling, the
-//! dispatch-Proc GC root, and the per-invocation usage readout.
+//! dispatch-Proc GC root, and the per-invocation usage / capture readouts.
 
 mod bridge;
 mod errors;
 
-use magnus::{function, method, prelude::*, Error as MagnusError, RModule, RString, Ruby};
+use magnus::{
+    function, gc, method, prelude::*, typed_data::DataTypeFunctions, value::Opaque,
+    Error as MagnusError, RArray, RModule, RString, Ruby, Symbol, TypedData, Value,
+};
 
-use std::cell::Cell;
+use std::cell::{Cell, RefCell};
 use std::path::Path;
 use std::sync::Arc;
 use std::time::Duration;
 
-use magnus::{gc, typed_data::DataTypeFunctions, value::Opaque, RArray, TypedData, Value};
-
-use crate::snapshot::Snapshot;
 use kobako_runtime::dispatch::DispatchHandler;
+use kobako_runtime::profile::Profile;
 use kobako_runtime::runtime::{Entry, Frames, Runtime as ContractRuntime};
-use kobako_runtime::snapshot::{Completion, Snapshot as RuntimeSnapshot, Usage};
+use kobako_runtime::snapshot::{Capture, Completion, Snapshot as RuntimeSnapshot, Usage};
 use kobako_wasmtime::{Config, Driver};
 
 /// Copy the bytes of `s` into a fresh `Vec<u8>`. Single safe entry to
@@ -52,6 +53,15 @@ fn rstring_to_vec(s: RString) -> Vec<u8> {
     unsafe { s.as_slice() }.to_vec()
 }
 
+/// The pre-invocation sentinel for one capture channel: no bytes, cap
+/// not reached. Fresh `Vec`s per call because `Capture` owns its buffer.
+fn empty_capture() -> Capture {
+    Capture {
+        bytes: Vec::new(),
+        truncated: false,
+    }
+}
+
 // ---------------------------------------------------------------------------
 // Ruby init
 // ---------------------------------------------------------------------------
@@ -65,11 +75,13 @@ pub fn init(ruby: &Ruby, kobako: RModule) -> Result<(), MagnusError> {
     // intermediate hierarchy is registered.
 
     let runtime = kobako.define_class("Runtime", ruby.class_object())?;
-    runtime.define_singleton_method("from_path", function!(Runtime::from_path, 5))?;
+    runtime.define_singleton_method("from_path", function!(Runtime::from_path, 6))?;
     runtime.define_method("on_dispatch=", method!(Runtime::set_on_dispatch, 1))?;
     runtime.define_method("eval", method!(Runtime::eval, 3))?;
     runtime.define_method("run", method!(Runtime::run, 3))?;
     runtime.define_method("usage", method!(Runtime::usage, 0))?;
+    runtime.define_method("captures", method!(Runtime::captures, 0))?;
+    runtime.define_method("profile", method!(Runtime::profile, 0))?;
     // 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.
@@ -93,11 +105,17 @@ struct Runtime {
     // reference the one Proc this `Opaque` pins. `Cell` is sound under the
     // GVL (see the `unsafe impl Sync` below).
     on_dispatch: Cell<Option<Opaque<Value>>>,
-    // Usage of the most recent invocation, kept apart from the returned
-    // `Snapshot` so `#usage` reads survive the per-invocation Store
-    // teardown and the trap path's raise. Zeroed before the first
-    // invocation.
+    // Usage of the most recent invocation, stashed here so `#usage` reads
+    // survive the per-invocation Store teardown and the trap path's
+    // raise. Zeroed before the first invocation.
     last_usage: Cell<Usage>,
+    // Output captures of the most recent invocation, stashed for the same
+    // reason as `last_usage`: the trap path raises, and this readout is
+    // what keeps the guest's partial output readable after a rescue.
+    // `RefCell` (not `Cell`) because `Capture` owns its byte buffer; the
+    // same GVL single-thread discipline applies (see the `unsafe impl
+    // Sync` below). Empty before the first invocation.
+    last_captures: RefCell<(Capture, Capture)>,
 }
 
 impl DataTypeFunctions for Runtime {
@@ -118,11 +136,11 @@ impl DataTypeFunctions for Runtime {
 }
 
 // SAFETY: magnus requires `Send + Sync` on TypedData types. The
-// `on_dispatch` / `last_usage` `Cell`s make the auto-derived `Sync`
-// unavailable, but every access to them happens under the GVL on a single
-// thread at a time — Ruby method calls, and a GC `mark` pass that also
-// holds the GVL. No cross-thread access to either Cell can occur. `Send`
-// stays auto-derived.
+// `on_dispatch` / `last_usage` `Cell`s and the `last_captures` `RefCell`
+// make the auto-derived `Sync` unavailable, but every access to them
+// happens under the GVL on a single thread at a time — Ruby method calls,
+// and a GC `mark` pass that also holds the GVL. No cross-thread access to
+// any of them can occur. `Send` stays auto-derived.
 unsafe impl Sync for Runtime {}
 
 impl Runtime {
@@ -135,15 +153,18 @@ impl Runtime {
     /// (`None` disables); `memory_limit` is the linear-memory cap in
     /// bytes (`None` disables); `stdout_limit_bytes` / `stderr_limit_bytes`
     /// are the per-channel output caps (`None`
-    /// disables). All four are validated by the caller
-    /// (`Kobako::Sandbox`); this method only refuses non-finite or
-    /// non-positive timeouts as a defence in depth.
+    /// disables); `profile` is the isolation rung the driver builds
+    /// (`:permissive` / `:hermetic`). All five are validated by the
+    /// caller (`Kobako::Sandbox`); this method only refuses non-finite
+    /// or non-positive timeouts and off-ladder profiles as a defence in
+    /// depth.
     fn from_path(
         path: String,
         timeout_seconds: Option<f64>,
         memory_limit: Option<usize>,
         stdout_limit_bytes: Option<usize>,
         stderr_limit_bytes: Option<usize>,
+        profile: Symbol,
     ) -> Result<Self, MagnusError> {
         let ruby = Ruby::get().expect("Ruby thread");
         let timeout = match timeout_seconds {
@@ -161,6 +182,19 @@ impl Runtime {
                 ));
             }
         };
+        // Fail closed on an off-ladder rung: an unrecognized posture must
+        // never fall back to a grant. Same defence-in-depth posture as the
+        // timeout guard above — `SandboxOptions` is the primary validator.
+        let profile = match profile.name()?.as_ref() {
+            "hermetic" => Profile::Hermetic,
+            "permissive" => Profile::Permissive,
+            other => {
+                return Err(MagnusError::new(
+                    ruby.exception_arg_error(),
+                    format!("profile must be :permissive or :hermetic, got :{other}"),
+                ));
+            }
+        };
 
         let driver = Driver::new(
             Path::new(&path),
@@ -169,6 +203,7 @@ impl Runtime {
                 timeout,
                 stdout_limit_bytes,
                 stderr_limit_bytes,
+                profile,
             },
         )
         .map_err(|e| errors::setup_to_magnus(&ruby, e))?;
@@ -179,6 +214,7 @@ impl Runtime {
                 wall_time: 0.0,
                 memory_peak: 0,
             }),
+            last_captures: RefCell::new((empty_capture(), empty_capture())),
         })
     }
 
@@ -204,7 +240,7 @@ impl Runtime {
     /// One-shot mruby source execution (`#eval`). The Ruby-facing entry:
     /// builds the dispatch handler from the registered Proc, hands the
     /// three stdin frames (`preamble`, `source`, `snippets`) and the source
-    /// to the driver, and settles the returned `Snapshot` through
+    /// to the driver, and settles the invocation through
     /// `finish_invocation` — or maps a could-not-start `Error` onto its
     /// `Kobako::*` exception. The run mechanics — frames, caps, trap
     /// classification — live in `kobako_wasmtime::Driver`.
@@ -213,7 +249,7 @@ impl Runtime {
         preamble: RString,
         source: RString,
         snippets: RString,
-    ) -> Result<Snapshot, MagnusError> {
+    ) -> Result<RString, MagnusError> {
         let ruby = Ruby::get().expect("Ruby thread");
         let handler = self.build_handler();
         let preamble = rstring_to_vec(preamble);
@@ -233,8 +269,8 @@ impl Runtime {
         self.finish_invocation(&ruby, snapshot)
     }
 
-    /// Execute one entrypoint dispatch (`__kobako_run`) and return a
-    /// `Snapshot` bundling every per-invocation observable.
+    /// Execute one entrypoint dispatch (`__kobako_run`) and return the
+    /// guest's raw outcome bytes.
     ///
     /// The two-frame stdin protocol (preamble + snippets; no user source
     /// frame — docs/wire-codec.md § Invocation channels) plus the
@@ -246,7 +282,7 @@ impl Runtime {
         preamble: RString,
         snippets: RString,
         envelope: RString,
-    ) -> Result<Snapshot, MagnusError> {
+    ) -> Result<RString, MagnusError> {
         let ruby = Ruby::get().expect("Ruby thread");
         let handler = self.build_handler();
         let preamble = rstring_to_vec(preamble);
@@ -268,20 +304,27 @@ impl Runtime {
         self.finish_invocation(&ruby, snapshot)
     }
 
-    /// Settle one invocation's `Snapshot` at the Ruby boundary: usage is
-    /// recorded even when the completion is a trap and this call raises,
-    /// while trap-path captures are deliberately dropped — exposing them
-    /// is a SPEC decision the Ruby surface has not taken.
+    /// Settle one invocation's `Snapshot` at the Ruby boundary: usage and
+    /// the two output captures are recorded on every outcome, so the
+    /// `#usage` / `#captures` readouts survive the trap path's raise —
+    /// that is what keeps the guest's partial output readable after the
+    /// Host App rescues the trap. A completed guest invocation returns
+    /// its raw outcome bytes; the Sandbox layer decodes them.
     fn finish_invocation(
         &self,
         ruby: &Ruby,
         snapshot: RuntimeSnapshot,
-    ) -> Result<Snapshot, MagnusError> {
-        self.last_usage.set(snapshot.usage);
-        match snapshot.completion {
-            Completion::Outcome(bytes) => {
-                Ok(Snapshot::new(bytes, snapshot.stdout, snapshot.stderr))
-            }
+    ) -> Result<RString, MagnusError> {
+        let RuntimeSnapshot {
+            completion,
+            stdout,
+            stderr,
+            usage,
+        } = snapshot;
+        self.last_usage.set(usage);
+        self.last_captures.replace((stdout, stderr));
+        match completion {
+            Completion::Outcome(bytes) => Ok(ruby.str_from_slice(&bytes)),
             Completion::Trap(trap) => Err(errors::trap_to_magnus(ruby, trap)),
         }
     }
@@ -313,8 +356,8 @@ impl Runtime {
     ///     size captured at invocation entry. `0` before the first
     ///     invocation.
     ///
-    /// Reads the `last_usage` Cell `finish_invocation` populated from the
-    /// returned `Snapshot` before the per-invocation Store was discarded.
+    /// Reads the `last_usage` Cell `finish_invocation` populated before
+    /// the per-invocation Store was discarded.
     fn usage(&self) -> Result<RArray, MagnusError> {
         let ruby = Ruby::get().expect("Ruby thread");
         let usage = self.last_usage.get();
@@ -323,4 +366,37 @@ impl Runtime {
         arr.push(usage.memory_peak)?;
         Ok(arr)
     }
+
+    /// Return the per-last-invocation output captures as a Ruby 4-tuple
+    /// `[stdout_bytes, stdout_truncated, stderr_bytes, stderr_truncated]`
+    /// — the flat positional layout mirrors `#usage`, and the element
+    /// order matches the destructure in `Kobako::Sandbox#read_captures!`;
+    /// reorder both sides together.
+    ///
+    /// Reads the `last_captures` pair `finish_invocation` stashed on
+    /// every outcome, so the readout also covers the trap path, where
+    /// `#eval` / `#run` raise instead of returning outcome bytes.
+    /// Empty bytes and `false` flags before the first invocation.
+    fn captures(&self) -> Result<RArray, MagnusError> {
+        let ruby = Ruby::get().expect("Ruby thread");
+        let captures = self.last_captures.borrow();
+        let (stdout, stderr) = &*captures;
+        let arr = ruby.ary_new_capa(4);
+        arr.push(ruby.str_from_slice(&stdout.bytes))?;
+        arr.push(stdout.truncated)?;
+        arr.push(ruby.str_from_slice(&stderr.bytes))?;
+        arr.push(stderr.truncated)?;
+        Ok(arr)
+    }
+
+    /// Return the isolation profile the driver built, as a Symbol
+    /// (`:hermetic` / `:permissive`) — the declaration the Sandbox
+    /// compares against the posture its `profile:` option requested.
+    fn profile(&self) -> Symbol {
+        let ruby = Ruby::get().expect("Ruby thread");
+        match self.driver.profile() {
+            Profile::Hermetic => ruby.to_symbol("hermetic"),
+            Profile::Permissive => ruby.to_symbol("permissive"),
+        }
+    }
 }

data/lib/kobako/codec.rb

@@ -22,7 +22,7 @@ module Kobako
   # {Decoder} are thin wrappers that register the three kobako-specific
   # ext types (0x00 Symbol, 0x01 Capability Handle, 0x02 Exception
   # envelope) on a single +MessagePack::Factory+ instance. The Rust side
-  # mirrors this layer as the +codec+ module in the +kobako-core+ crate;
+  # mirrors this layer as the +codec+ module in the +kobako-codec+ crate;
   # the ext-code constants live as module-private values on {Factory}
   # alongside +codec::EXT_SYMBOL+ / +codec::EXT_HANDLE+ /
   # +codec::EXT_ERRENV+ on that side.

data/lib/kobako/sandbox.rb

@@ -38,14 +38,16 @@ module Kobako
 
     attr_reader :wasm_path, :options
 
-    # Per-cap accessors forward to the immutable +SandboxOptions+ Value
+    # Per-option accessors forward to the immutable +SandboxOptions+ Value
     # Object so the Host App still reads them off Sandbox directly.
-    def_delegators :@options, :timeout, :memory_limit, :stdout_limit, :stderr_limit
+    def_delegators :@options, :timeout, :memory_limit, :stdout_limit, :stderr_limit, :profile
 
     # Returns the bytes the guest wrote to stdout during the most recent
     # invocation as a UTF-8 String, clipped at +stdout_limit+. Empty before
     # any invocation; the byte content never contains a truncation sentinel,
-    # so use +#stdout_truncated?+ to observe overflow.
+    # so use +#stdout_truncated?+ to observe overflow. Populated on every
+    # outcome — including a rescued +TrapError+, after which it holds the
+    # bytes written before the trap fired — mirroring +#usage+.
     def stdout
       @stdout_capture.bytes
     end
@@ -83,25 +85,24 @@ module Kobako
     # Build a fresh Sandbox.
     #
     # +wasm_path+ is the absolute path to the Guest Binary; defaults to the
-    # gem-bundled +data/kobako.wasm+. The four caps (+stdout_limit+,
-    # +stderr_limit+, +timeout+, +memory_limit+) are forwarded verbatim to
-    # +Kobako::SandboxOptions+, which owns their DEFAULT fallback and
+    # gem-bundled +data/kobako.wasm+. Every other keyword — the four caps
+    # (+stdout_limit+, +stderr_limit+, +timeout+, +memory_limit+) and the
+    # requested isolation profile (+profile+) — is forwarded verbatim to
+    # +Kobako::SandboxOptions+, which owns the DEFAULT fallbacks and
     # normalisation. The constructed +SandboxOptions+ is exposed as
-    # +#options+ and the four caps remain readable directly on Sandbox via
-    # +Forwardable+ delegation.
-    def initialize(wasm_path: nil,
-                   stdout_limit: SandboxOptions::DEFAULT_OUTPUT_LIMIT,
-                   stderr_limit: SandboxOptions::DEFAULT_OUTPUT_LIMIT,
-                   timeout: SandboxOptions::DEFAULT_TIMEOUT_SECONDS,
-                   memory_limit: SandboxOptions::DEFAULT_MEMORY_LIMIT)
+    # +#options+ and every option remains readable directly on Sandbox via
+    # +Forwardable+ delegation. The runtime builds the requested profile —
+    # +:hermetic+ (the default) denies the guest ambient time and entropy,
+    # +:permissive+ leaves them live — and construction refuses a runtime
+    # whose declared profile falls below the request, raising
+    # +Kobako::SetupError+ before any invocation entry point runs.
+    def initialize(wasm_path: nil, **)
       @wasm_path = wasm_path || Kobako::Runtime.default_path
-      @options = SandboxOptions.new(timeout: timeout, memory_limit: memory_limit, stdout_limit: stdout_limit,
-                                    stderr_limit: stderr_limit)
+      @options = SandboxOptions.new(**)
       @handler = Catalog::Handles.new
       @services = Kobako::Catalog::Namespaces.new(handler: @handler)
       @snippets = Catalog::Snippets.new
-      @runtime = Kobako::Runtime.from_path(@wasm_path, @options.timeout, @options.memory_limit,
-                                           @options.stdout_limit, @options.stderr_limit)
+      @runtime = build_runtime!
       install_dispatch_proc!
       reset_invocation_state!
     end
@@ -209,6 +210,17 @@ module Kobako
 
     private
 
+    # Construct the +Runtime+ with the requested isolation profile and
+    # refuse one whose declared posture falls below the request —
+    # +SandboxOptions#enforce_floor!+ owns the ladder comparison, so a
+    # runtime that cannot honor the request never runs guest code.
+    def build_runtime!
+      runtime = Kobako::Runtime.from_path(@wasm_path, @options.timeout, @options.memory_limit,
+                                          @options.stdout_limit, @options.stderr_limit, profile)
+      @options.enforce_floor!(runtime.profile)
+      runtime
+    end
+
     # Configure the +Runtime+'s host↔guest dispatch wiring. Registers a
     # dispatch +Proc+ that routes guest→host calls through the stateless
     # +Transport::Dispatcher+, capturing +@services+ / +@handler+ in the
@@ -242,8 +254,8 @@ module Kobako
     # +TimeoutError+ / +MemoryLimitError+), +Kobako::SandboxError+,
     # and +Kobako::ServiceError+. +Runtime#usage+ is the single source for
     # both paths: the figures are stashed in the ext on every outcome, so
-    # unlike the +Snapshot+ (built only on success) the readout here also
-    # covers the trap path.
+    # the readout here also covers the trap path, where +Runtime#eval+ /
+    # +#run+ raise instead of returning outcome bytes.
     #
     # The ext returns a positional 2-tuple +[wall_time, memory_peak]+
     # whose order matches the +Kobako::Usage+ field order; the
@@ -269,33 +281,51 @@ module Kobako
       end
     end
 
+    # Read the per-last-invocation output captures from the ext and wrap
+    # them as +Kobako::Capture+ value objects. Runs in the +invoke!+
+    # +ensure+ block next to {#read_usage!} for the same reason: the ext
+    # stashes the captures on every outcome, so the readout also covers
+    # the trap path, where +Runtime#eval+ / +#run+ raise instead of
+    # returning outcome bytes — +#stdout+ / +#stderr+ keep the guest's
+    # partial output readable after a rescue.
+    #
+    # The ext returns a positional 4-tuple
+    # +[stdout_bytes, stdout_truncated, stderr_bytes, stderr_truncated]+;
+    # the destructure-then-kwargs handoff below is the explicit
+    # positional→keyword conversion point.
+    def read_captures!
+      stdout_bytes, stdout_truncated, stderr_bytes, stderr_truncated = @runtime.captures
+      @stdout_capture = Capture.new(bytes: stdout_bytes, truncated: stdout_truncated)
+      @stderr_capture = Capture.new(bytes: stderr_bytes, truncated: stderr_truncated)
+    end
+
     # Shared prologue / epilogue + trap-class translator for both
     # invocation verbs. +verb+ is +:eval+ or +:run+; it tags the
     # TrapError message so the failing export is identifiable.
     #
-    # The yielded block must return a +Kobako::Snapshot+ — i.e. the
-    # value of +Runtime#eval+ / +#run+. The success path unpacks
-    # +#stdout+ / +#stderr+ into
-    # +Capture+ and feeds +#return_bytes+ to +Outcome.decode+; usage is
-    # populated by the +ensure+ readout ({#read_usage!}) on every outcome.
+    # The yielded block must return the invocation's raw outcome bytes —
+    # i.e. the value of +Runtime#eval+ / +#run+ — which the success path
+    # feeds to +Outcome.decode+. Captures and usage are populated by the
+    # +ensure+ readouts ({#read_usage!} / {#read_captures!}) on every
+    # outcome, so +#stdout+ / +#stderr+ / +#usage+ stay readable after a
+    # rescued trap.
     # The rescue chain is the single trap-translation boundary —
     # configured-cap paths surface as named TrapError subclasses
     # (+TimeoutError+ / +MemoryLimitError+); everything else surfaces as
     # the base +TrapError+.
     def invoke!(verb)
       begin_invocation!
-      snapshot = yield
-      @stdout_capture = snapshot.stdout
-      @stderr_capture = snapshot.stderr
+      return_bytes = yield
       # A Capability Handle in the result is decoded as a Kobako::Handle
       # token; restore it to the host object the guest referenced before
       # handing the value to the Host App. @handler still holds this
       # invocation's table — reset only happens at the next #begin_invocation!.
-      Codec::HandleWalk.deep_restore(Outcome.decode(snapshot.return_bytes), @handler)
+      Codec::HandleWalk.deep_restore(Outcome.decode(return_bytes), @handler)
     rescue Kobako::TrapError => e
       raise trap_class_for(e), "Sandbox##{verb} failed: #{e.message}"
     ensure
       read_usage!
+      read_captures!
     end
   end
 end

data/lib/kobako/sandbox_options.rb

@@ -1,19 +1,27 @@
 # frozen_string_literal: true
 
+require_relative "errors"
+
 module Kobako
   # Kobako::SandboxOptions — immutable Value Object holding the four
-  # per-Sandbox configuration caps. Built on the +class X <
-  # Data.define(...)+ subclass form (the Steep-friendly shape — see
-  # +lib/kobako/outcome/panic.rb+).
+  # per-Sandbox configuration caps and the requested isolation profile.
+  # Built on the +class X < Data.define(...)+ subclass form (the
+  # Steep-friendly shape — see +lib/kobako/outcome/panic.rb+).
   #
-  # The +initialize+ normalises every cap before delegating to Data's
+  # The +initialize+ normalises every option before delegating to Data's
   # +super+: +timeout+ to Float seconds, +memory_limit+ / +stdout_limit+ /
   # +stderr_limit+ to positive Integer bytes. Each cap is +nil+-disablable
   # (an absent argument takes its DEFAULT; an explicit +nil+ leaves the
-  # bound off), so all four behave uniformly. Anything that survives
-  # +SandboxOptions.new+ is a wire-ready cap bundle the +Kobako::Runtime+
-  # constructor consumes as-is.
-  class SandboxOptions < Data.define(:timeout, :memory_limit, :stdout_limit, :stderr_limit)
+  # bound off), so all four behave uniformly. +profile+ is the one
+  # non-cap: a Symbol on the PROFILES ladder naming the posture the
+  # runtime builds, which is also the weakest the Host App accepts —
+  # +nil+ is rejected because the weakest posture is requested as an
+  # explicit +:permissive+. Anything that survives +SandboxOptions.new+
+  # is a wire-ready bundle the +Kobako::Runtime+ constructor consumes
+  # as-is. The options also own the ladder comparison
+  # (+#enforce_floor!+) that +Kobako::Sandbox+ delegates its
+  # construction floor check to.
+  class SandboxOptions < Data.define(:timeout, :memory_limit, :stdout_limit, :stderr_limit, :profile)
     # Default wall-clock timeout for a single invocation: 60 seconds.
     DEFAULT_TIMEOUT_SECONDS = 60.0
 
@@ -25,17 +33,41 @@ module Kobako
     # Default per-channel capture ceiling: 1 MiB.
     DEFAULT_OUTPUT_LIMIT = 1 << 20
 
+    # The isolation ladder, weakest first — index order is rank order,
+    # so a floor check is an index comparison.
+    PROFILES = %i[permissive hermetic].freeze
+
+    # Default isolation profile: the strictest rung — opting down to
+    # +:permissive+ is the Host App's explicit trade.
+    DEFAULT_PROFILE = :hermetic
+
     def initialize(timeout: DEFAULT_TIMEOUT_SECONDS,
                    memory_limit: DEFAULT_MEMORY_LIMIT,
                    stdout_limit: DEFAULT_OUTPUT_LIMIT,
-                   stderr_limit: DEFAULT_OUTPUT_LIMIT)
+                   stderr_limit: DEFAULT_OUTPUT_LIMIT,
+                   profile: DEFAULT_PROFILE)
       timeout = normalize_timeout(timeout)
       memory_limit = normalize_memory_limit(memory_limit)
       stdout_limit = normalize_output_limit(stdout_limit, "stdout_limit")
       stderr_limit = normalize_output_limit(stderr_limit, "stderr_limit")
+      profile = normalize_profile(profile)
       super
     end
 
+    # Enforce the requested +profile+ as the floor against +declared+ —
+    # the posture a runtime reports having built — so a runtime that
+    # cannot honor the request fails construction with
+    # +Kobako::SetupError+ instead of weakening the posture silently.
+    # Both fallbacks fail closed: a declaration off the PROFILES ladder
+    # ranks below every request, and a request off the ladder
+    # (unreachable past +initialize+) refuses every declaration.
+    def enforce_floor!(declared)
+      return if (PROFILES.index(declared) || -1) >= (PROFILES.index(profile) || PROFILES.size)
+
+      raise Kobako::SetupError, "runtime declares isolation profile #{declared.inspect}, " \
+                                "below the requested floor #{profile.inspect}"
+    end
+
     private
 
     # Coerce +timeout+ into the Float seconds the ext expects, or +nil+
@@ -78,5 +110,15 @@ module Kobako
 
       limit
     end
+
+    # Validate +profile+ against the PROFILES ladder. Unlike the caps
+    # there is no +nil+ form: the weakest posture is requested as an
+    # explicit +:permissive+, so anything off the ladder — +nil+
+    # included — is rejected.
+    def normalize_profile(profile)
+      return profile if PROFILES.include?(profile)
+
+      raise ArgumentError, "profile must be one of #{PROFILES.map(&:inspect).join(", ")}, got #{profile.inspect}"
+    end
   end
 end

data/lib/kobako/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Kobako
-  VERSION = "0.12.2"
+  VERSION = "0.13.0"
 end

data/lib/kobako.rb

@@ -13,6 +13,5 @@ require_relative "kobako/errors"
 require_relative "kobako/transport"
 require_relative "kobako/catalog"
 require_relative "kobako/runtime"
-require_relative "kobako/snapshot"
 require_relative "kobako/sandbox"
 require_relative "kobako/pool"

data/release-please-config.json

@@ -18,6 +18,11 @@
           "path": "/wasm/Cargo.lock",
           "jsonpath": "$.package[?(@.name=='kobako-core')].version"
         },
+        {
+          "type": "toml",
+          "path": "/wasm/kobako-core/Cargo.toml",
+          "jsonpath": "$.dependencies['kobako-codec'].version"
+        },
         {
           "type": "generic",
           "path": "/wasm/kobako-core/README.md"
@@ -38,6 +43,11 @@
           "path": "/wasm/kobako/Cargo.toml",
           "jsonpath": "$.dependencies['kobako-core'].version"
         },
+        {
+          "type": "toml",
+          "path": "/wasm/kobako/Cargo.toml",
+          "jsonpath": "$.dependencies['kobako-codec'].version"
+        },
         {
           "type": "generic",
           "path": "/wasm/kobako/README.md"
@@ -104,6 +114,26 @@
         }
       ]
     },
+    "crates/kobako-codec": {
+      "component": "kobako-codec",
+      "release-type": "rust",
+      "extra-files": [
+        {
+          "type": "toml",
+          "path": "/crates/Cargo.lock",
+          "jsonpath": "$.package[?(@.name=='kobako-codec')].version"
+        },
+        {
+          "type": "toml",
+          "path": "/wasm/Cargo.lock",
+          "jsonpath": "$.package[?(@.name=='kobako-codec')].version"
+        },
+        {
+          "type": "generic",
+          "path": "/crates/kobako-codec/README.md"
+        }
+      ]
+    },
     "crates/kobako-runtime": {
       "component": "kobako-runtime",
       "release-type": "rust",
@@ -154,7 +184,7 @@
     {
       "type": "linked-versions",
       "groupName": "kobako crates",
-      "components": ["kobako-core", "kobako-rs", "kobako-io", "kobako-json", "kobako-regexp", "kobako-baker", "kobako-runtime", "kobako-wasmtime"]
+      "components": ["kobako-codec", "kobako-core", "kobako-rs", "kobako-io", "kobako-json", "kobako-regexp", "kobako-baker", "kobako-runtime", "kobako-wasmtime"]
     }
   ],
   "extra-files": [

data/sig/kobako/runtime.rbs

@@ -7,17 +7,22 @@ module Kobako
       (Float | Integer)? timeout_seconds,
       Integer? memory_limit,
       Integer? stdout_limit_bytes,
-      Integer? stderr_limit_bytes
+      Integer? stderr_limit_bytes,
+      Symbol profile
     ) -> Runtime
 
     def on_dispatch=: (^(String, Kobako::Transport::_GuestYielder) -> String dispatch_proc) -> void
 
-    def eval: (String preamble, String source, String snippets) -> Kobako::Snapshot
+    def eval: (String preamble, String source, String snippets) -> String
 
-    def run: (String preamble, String snippets, String envelope) -> Kobako::Snapshot
+    def run: (String preamble, String snippets, String envelope) -> String
 
     def usage: () -> [Float, Integer]
 
+    def captures: () -> [String, bool, String, bool]
+
+    def profile: () -> Symbol
+
     # Frame-scoped guest re-entry handle the ext hands the dispatch Proc as
     # its second argument; stands in as the +String -> String+ callable the
     # host +Transport::Yielder+ invokes for a block yield.