kobako 0.12.1-aarch64-linux → 0.13.0-aarch64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3d480be9786ea4e836ec39bf80b704c07373a6a283ce3fd0e822799511430e28
-  data.tar.gz: fec449faec3e9072fa222948509c86bc8e3e401180c56c5b801bcebe8b73f36a
+  metadata.gz: c0a1b4ccd9f4e1debe32912b925847390d00fbf09e798b41eb54ac0756ef4ab3
+  data.tar.gz: 4819002a95e4407ebacb91d1ae77cd8a7c52d80a1eb0511dcc01ac405d6b7459
 SHA512:
-  metadata.gz: 56ea11910d7a393725f27ec696e271f71f69c0eb26d9fb20ee5001d3401e149a558ca248cdcc17cafb45ffa083df5a489e077906a126e2aa177ce570950eeb22
-  data.tar.gz: 2bd8f82df6f33072a177226ec9f9b11926bbe374cba1258b60b4510f5be493a598fe2e68c46b3fc87a6f3519857fa7695c0a1675a1655add87233de207664488
+  metadata.gz: 902954ca6a47611ab670ea52dbe5edc2268428128ffaac0dd9d55e309af6d5b4a70fc47d07eed4f31261bdcdc7158cbdd91fbfad32d56098c8a2c84077db2855
+  data.tar.gz: 53174e7d4e921b558bca17b3683c0865954ff73219a0c07d86d11e18e6e812506aece5d5dc0626ce021fe9342a63d8d3b5ab612f513d7349e939e0e6e08ed063

data/.release-please-manifest.json

@@ -1 +1 @@
-{".":"0.12.1","wasm/kobako-core":"0.6.0","wasm/kobako":"0.6.0","wasm/kobako-io":"0.6.0","wasm/kobako-json":"0.6.0","wasm/kobako-regexp":"0.6.0","wasm/kobako-baker":"0.6.0"}
+{".":"0.13.0","wasm/kobako-core":"0.7.0","wasm/kobako":"0.7.0","wasm/kobako-io":"0.7.0","wasm/kobako-json":"0.7.0","wasm/kobako-regexp":"0.7.0","wasm/kobako-baker":"0.7.0","crates/kobako-codec":"0.7.0","crates/kobako-runtime":"0.7.0","crates/kobako-wasmtime":"0.7.0"}

data/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## [0.13.0](https://github.com/elct9620/kobako/compare/v0.12.2...v0.13.0) (2026-07-03)
+
+
+### Features
+
+* **crates:** build the requested isolation profile into the WASI context ([63c25d8](https://github.com/elct9620/kobako/commit/63c25d835d4d03010c1658217cee412318e6b5d8))
+* enforce the isolation-profile floor at Sandbox construction ([73f0dfe](https://github.com/elct9620/kobako/commit/73f0dfe34a144045a559a28caec31468351de64a))
+* forward the Sandbox profile request through the ext to the driver ([f47f906](https://github.com/elct9620/kobako/commit/f47f9063aa56462be023f5c76cbc73db6e4315ad))
+* keep guest output readable after a trap ([464454c](https://github.com/elct9620/kobako/commit/464454cd774db96ad72b3787007f2ce015673587))
+* **runtime:** runtimes declare their isolation profile ([f89717a](https://github.com/elct9620/kobako/commit/f89717a6bc9809f0de0df78f97da33a49a1474ac))
+
+## [0.12.2](https://github.com/elct9620/kobako/compare/v0.12.1...v0.12.2) (2026-07-02)
+
+
+### Bug Fixes
+
+* **codec:** bound ext-envelope nesting to keep deep Fault chains off the native stack ([7bed2b2](https://github.com/elct9620/kobako/commit/7bed2b2f43a63538aa60610c82d2eb65bcce7b15))
+* **guest:** size collection conversions by C array length, not #length ([90ecbd0](https://github.com/elct9620/kobako/commit/90ecbd0cb6a990b8c5a1e5deec3a10df4eaa37df))
+* **io:** enforce the fd allowlist at the write syscall ([1b300df](https://github.com/elct9620/kobako/commit/1b300df7bee8f87b701f76b42300163a8899b93e))
+* **release:** advance last-release-sha past the unparseable fork merge ([d06117d](https://github.com/elct9620/kobako/commit/d06117d462eea0ae5648e5bdd6886b735765f3b3))
+* **sandbox:** honor nil to disable the output caps, and validate them ([51d1e90](https://github.com/elct9620/kobako/commit/51d1e900e3d7d659ffd432ff3d613786e9073b05))
+
 ## [0.12.1](https://github.com/elct9620/kobako/compare/v0.12.0...v0.12.1) (2026-06-27)
 
 

data/README.md

@@ -127,7 +127,7 @@ end
 |---------------------------------|----------------|------------------------------------------------------|
 | `Kobako::TimeoutError`          | `TrapError`    | Per-invocation `timeout` exhausted                   |
 | `Kobako::MemoryLimitError`      | `TrapError`    | Per-invocation `memory_limit` exhausted              |
-| `Kobako::HandlerExhaustedError` | `SandboxError` | Handle counter reached its 2³¹ − 1 cap               |
+| `Kobako::HandleExhaustedError` | `SandboxError` | Handle counter reached its 2³¹ − 1 cap               |
 | `Kobako::BytecodeError`         | `SandboxError` | `#preload(binary:)` failed RITE validation at replay |
 
 `SandboxError` and `ServiceError` carry structured `origin` / `klass` / `backtrace_lines` / `details` fields when the guest produced a panic envelope.
@@ -154,6 +154,8 @@ sandbox = Kobako::Sandbox.new(
 
 `memory_limit` covers the per-invocation `memory.grow` delta from the entry baseline, so a Sandbox reused across invocations does not silently accumulate against a global budget.
 
+A fifth option, `profile:`, requests the Sandbox's isolation posture on the `:permissive` < `:hermetic` ladder (default `:hermetic`). `:hermetic` denies the guest ambient time and entropy; `:permissive` lets the guest's `wasi:clocks` / `wasi:random` read live host sources — an explicit trade of reproducibility, with filesystem, environment, and network still unreachable. The request is also a floor: construction fails with `Kobako::SetupError` on a runtime that declares a weaker posture than requested. See [`docs/security-model.md`](docs/security-model.md) § Isolation profiles.
+
 ### Invocation Lifecycle
 
 One Sandbox serves many invocations. Service bindings and preloaded snippets persist across calls; capability state (Handles, stdout, stderr, memory delta) resets between them.

data/crates/kobako-runtime/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+## [0.7.0](https://github.com/elct9620/kobako/compare/kobako-runtime-v0.6.1...kobako-runtime-v0.7.0) (2026-07-03)
+
+
+### Features
+
+* **crates:** build the requested isolation profile into the WASI context ([63c25d8](https://github.com/elct9620/kobako/commit/63c25d835d4d03010c1658217cee412318e6b5d8))
+* **runtime:** runtimes declare their isolation profile ([f89717a](https://github.com/elct9620/kobako/commit/f89717a6bc9809f0de0df78f97da33a49a1474ac))
+
+## [0.6.1](https://github.com/elct9620/kobako/compare/kobako-runtime-v0.6.0...kobako-runtime-v0.6.1) (2026-07-02)
+
+
+### Miscellaneous Chores
+
+* **kobako-runtime:** Synchronize kobako crates versions

data/crates/kobako-runtime/README.md

@@ -0,0 +1,34 @@
+# kobako-runtime
+
+Engine-neutral host runtime contract for
+[kobako](https://github.com/elct9620/kobako), an in-process Wasm
+sandbox for running untrusted mruby scripts.
+
+A kobako host drives a Guest Binary through a wasm engine; this crate
+is the surface where the two meet, free of any engine or frontend
+type, so the engine stays swappable:
+
+- `runtime` — the `Runtime` trait: one guest invocation on a fresh
+  instance in, its observable `Snapshot` out
+- `snapshot` — the per-invocation observables: `Completion` (outcome
+  or trap), the two output `Capture`s, and resource `Usage`, uniform
+  across success and trap
+- `error` — the neutral failure channels: `Trap` (engine fault) and
+  `SetupError` (the invocation never started)
+- `dispatch` / `yielder` — the `DispatchHandler` and `Yielder` traits
+  a frontend supplies for guest→host dispatch and block-yield re-entry
+
+Engine implementations (such as `kobako-wasmtime`) implement
+`Runtime`; host frontends (such as the kobako Ruby gem's native ext)
+map the neutral types onto their own language surface.
+
+## Usage
+
+```toml
+[dependencies]
+kobako-runtime = "0.7.0" # x-release-please-version
+```
+
+## License
+
+Apache-2.0

data/crates/kobako-wasmtime/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+## [0.7.0](https://github.com/elct9620/kobako/compare/kobako-wasmtime-v0.6.1...kobako-wasmtime-v0.7.0) (2026-07-03)
+
+
+### Features
+
+* **crates:** build the requested isolation profile into the WASI context ([63c25d8](https://github.com/elct9620/kobako/commit/63c25d835d4d03010c1658217cee412318e6b5d8))
+* **runtime:** runtimes declare their isolation profile ([f89717a](https://github.com/elct9620/kobako/commit/f89717a6bc9809f0de0df78f97da33a49a1474ac))
+
+## [0.6.1](https://github.com/elct9620/kobako/compare/kobako-wasmtime-v0.6.0...kobako-wasmtime-v0.6.1) (2026-07-02)
+
+
+### Miscellaneous Chores
+
+* **kobako-wasmtime:** Synchronize kobako crates versions

data/crates/kobako-wasmtime/README.md

@@ -0,0 +1,32 @@
+# kobako-wasmtime
+
+The [wasmtime](https://wasmtime.dev) implementation of the
+[kobako](https://github.com/elct9620/kobako) host runtime contract
+([`kobako-runtime`](https://crates.io/crates/kobako-runtime)).
+
+`Driver` implements the contract's `Runtime` trait over wasmtime and
+owns every engine-bound mechanic, so frontends see only the neutral
+contract surface:
+
+- process-wide Engine and compiled-Module caches with an on-disk AOT
+  (`.cwasm`) artifact cache keyed by Guest Binary content
+- a pre-linked `InstancePre` per guest path; every invocation runs on
+  a fresh instance and discards its Store afterwards
+- the epoch-based wall-clock timeout and the per-invocation
+  linear-memory cap
+- ambient denial: frozen WASI clocks and a constant RNG, so a guest
+  observes no real time and no real entropy
+
+The kobako Ruby gem's native ext is the first frontend; a Rust host
+SDK consumes the same surface.
+
+## Usage
+
+```toml
+[dependencies]
+kobako-wasmtime = "0.7.0" # x-release-please-version
+```
+
+## License
+
+Apache-2.0

data/lib/kobako/catalog/handles.rb

@@ -38,7 +38,7 @@ module Kobako
       # for it. +object+ is any host-side Ruby object to bind. Returns a
       # freshly-allocated +Kobako::Handle+ whose +#id+ falls in
       # +[Kobako::Handle::MIN_ID, Kobako::Handle::MAX_ID]+. Raises
-      # +Kobako::HandlerExhaustedError+ if the next ID would exceed the
+      # +Kobako::HandleExhaustedError+ if the next ID would exceed the
       # cap. The cap is anchored on +Kobako::Handle+ — the wire codec
       # and the allocator share the same invariant.
       #
@@ -96,12 +96,12 @@ module Kobako
       end
 
       # Guard {#alloc} against issuing an ID past the cap. Returns +nil+
-      # on success; raises +Kobako::HandlerExhaustedError+ at exhaustion.
+      # on success; raises +Kobako::HandleExhaustedError+ at exhaustion.
       def ensure_capacity!
         cap = Kobako::Handle::MAX_ID
         return unless @next_id > cap
 
-        raise HandlerExhaustedError,
+        raise HandleExhaustedError,
               "Out of handle allocations: too many host objects were referenced " \
               "in a single invocation (limit #{cap})"
       end

data/lib/kobako/catalog/namespaces.rb

@@ -82,6 +82,10 @@ module Kobako
       # first invocation, so the preamble is exactly the bindings that
       # existed at that moment — a bind reaching a +Kobako::Namespace+
       # after the seal raises +ArgumentError+ and never alters Frame 1.
+      # The memo is gated on the seal rather than dropped per mutation (the
+      # +Catalog::Snippets#encode+ approach) because a +Member+ bind lands
+      # on a child +Kobako::Namespace+, invisible to this collection; only
+      # the seal guarantees nothing further can change.
       def encode
         return @encoded if @encoded
 

data/lib/kobako/catalog/snippets.rb

@@ -44,6 +44,10 @@ module Kobako
       # The bytes are memoized — the table is replayed verbatim on every
       # invocation after sealing, so Frame 3 never changes between
       # encodes; {#register} drops the memo while the table is still open.
+      # Unlike +Catalog::Namespaces#encode+, which gates its memo on the
+      # seal, this one can fill eagerly and invalidate in +#register+
+      # because every mutation funnels through that single method — there is
+      # no out-of-sight child object to change the result behind its back.
       def encode
         return @encoded if @encoded
 

data/lib/kobako/codec/encoder.rb

@@ -26,7 +26,11 @@ module Kobako
       # mapping is a closed set, and anything outside it is rejected by
       # the msgpack gem itself (arbitrary objects raise +NoMethodError+
       # from missing +to_msgpack+, integers outside i64..u64 raise
-      # +RangeError+).
+      # +RangeError+). The +NoMethodError+ catch is deliberately broad:
+      # MessagePack signals "no wire representation" only through that error,
+      # so there is no narrower discriminator — a packer-internal
+      # +NoMethodError+ is likewise reported as +UnsupportedType+ rather than
+      # propagating.
       def self.encode(value)
         Factory.dump(value)
       rescue ::RangeError, ::NoMethodError => e

data/lib/kobako/codec/factory.rb

@@ -48,6 +48,16 @@ module Kobako
       EXT_ERRENV = 0x02
       private_constant :EXT_SYMBOL, :EXT_HANDLE, :EXT_ERRENV
 
+      # An ext 0x02 (Fault) envelope nests through its +details+ field, and
+      # each level re-enters the codec with a fresh +MessagePack+ unpacker
+      # whose built-in stack guard resets — so ext-envelope depth is tracked
+      # here instead. The cap matches the wire's overall nesting bound and
+      # keeps a nested chain from exhausting the native stack: an over-deep
+      # chain fails as a clean wire error, never a stack-level trap.
+      MAX_EXT_DEPTH = 128
+      EXT_DEPTH_KEY = :__kobako_codec_ext_depth__
+      private_constant :MAX_EXT_DEPTH, :EXT_DEPTH_KEY
+
       # Instance-level pass-through onto the wrapped +MessagePack::Factory+.
       # Spelled +def_instance_delegators+ rather than +def_delegators+ because
       # the class also extends +SingleForwardable+ (see the +extend+ block
@@ -129,9 +139,13 @@ module Kobako
       # Encode the inner ext-0x02 map via {Encoder} (not +factory.dump+) so
       # the embedded payload flows through the same boundary as a top-level
       # encode — nested kobako values (Handle, nested Fault) reach the
-      # registered ext-type packers via the cached singleton.
+      # registered ext-type packers via the cached singleton. A +details+
+      # chain nested past {MAX_EXT_DEPTH} has no wire representation and
+      # surfaces as +UnsupportedType+.
       def pack_fault(fault)
-        Encoder.encode("type" => fault.type, "message" => fault.message, "details" => fault.details)
+        within_ext_frame(UnsupportedType) do
+          Encoder.encode("type" => fault.type, "message" => fault.message, "details" => fault.details)
+        end
       end
 
       # Peel the embedded msgpack map and hand it to +Kobako::Fault.new+
@@ -139,19 +153,33 @@ module Kobako
       # +ArgumentError+ invariants surface as +InvalidType+ through the
       # decoder boundary. Inner decode goes through {Decoder} (not
       # +factory.load+) so the embedded +str+ payloads flow through the
-      # same UTF-8 validation as a top-level decode.
-      #
-      # This establishes a runtime cycle Factory → Decoder → Factory: the
-      # singleton instance feeds +Decoder.decode+, which re-enters this
-      # method when a nested ext 0x02 appears inside +details+. The recursion
-      # is bounded by msgpack nesting depth — identical to nested Array /
-      # Hash payloads — so no extra guard is needed. Do not switch back to
-      # +factory.load+ to "simplify": that path bypasses UTF-8 validation.
+      # same UTF-8 validation as a top-level decode. A nested ext 0x02 in
+      # +details+ re-enters this method, so {#within_ext_frame} bounds the
+      # chain depth to keep it from exhausting the native stack.
       def unpack_fault(payload)
-        Decoder.decode(payload) do |map|
-          raise InvalidType, "Fault payload must be a map" unless map.is_a?(Hash)
+        within_ext_frame(InvalidType) do
+          Decoder.decode(payload) do |map|
+            raise InvalidType, "Fault payload must be a map" unless map.is_a?(Hash)
+
+            Kobako::Fault.new(type: map["type"], message: map["message"], details: map["details"])
+          end
+        end
+      end
 
-          Kobako::Fault.new(type: map["type"], message: map["message"], details: map["details"])
+      # Track ext-envelope re-entry depth and refuse a chain past
+      # {MAX_EXT_DEPTH}, raising +over_limit+ so the failure lands in the
+      # caller's existing wire-error class. The counter is thread-scoped and
+      # balanced by the +ensure+, so a raise mid-chain still unwinds it to
+      # its entry value.
+      def within_ext_frame(over_limit)
+        depth = (Thread.current[EXT_DEPTH_KEY] || 0) + 1
+        raise over_limit, "ext envelope nesting exceeds #{MAX_EXT_DEPTH} levels" if depth > MAX_EXT_DEPTH
+
+        Thread.current[EXT_DEPTH_KEY] = depth
+        begin
+          yield
+        ensure
+          Thread.current[EXT_DEPTH_KEY] = depth - 1
         end
       end
     end

data/lib/kobako/codec/handle_walk.rb

@@ -97,6 +97,10 @@ module Kobako
         case value
         when ::Array then value.map { |element| HandleWalk.deep_restore(element, handler) }
         when ::Hash
+          # Rebuilt with each key restored: two distinct Handle keys that
+          # resolve to equal host objects collapse to the later pair, as in
+          # any Ruby Hash. The guest authored this payload, so that collapse
+          # is its own concern, not a fidelity guarantee the host owes it.
           value.to_h { |key, val| [HandleWalk.deep_restore(key, handler), HandleWalk.deep_restore(val, handler)] }
         when Kobako::Handle then handler.fetch(value.id)
         else value

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/errors.rb

@@ -35,7 +35,7 @@ module Kobako
   #
   #   * {ModuleNotBuiltError} < {SetupError} — Guest Binary artifact absent
   #                       at +wasm_path+.
-  #   * {HandlerExhaustedError} < {SandboxError} — Handle id cap hit.
+  #   * {HandleExhaustedError} < {SandboxError} — Handle id cap hit.
 
   # Base for all kobako-raised errors so callers that want to ignore the
   # taxonomy can rescue a single class.
@@ -89,10 +89,13 @@ module Kobako
   # +ModuleNotBuiltError+ first.
   class ModuleNotBuiltError < SetupError; end
 
-  # Sandbox / wire layer. Raised when the guest ran to completion but
-  # execution failed due to a mruby script error, a protocol fault, or a
-  # host-side wire decode failure on an otherwise valid outcome tag.
-  class SandboxError < Error
+  # The structured attribution the two invocation-failure classes carry
+  # from a decoded guest exception — its +origin+, original +klass+,
+  # +backtrace_lines+, and +details+ — so a Host App can inspect a failure
+  # beyond its message. Mixed into both rather than promoted to a shared
+  # superclass because +SandboxError+ and +ServiceError+ sit in distinct
+  # branches of the invocation-outcome taxonomy under +Kobako::Error+.
+  module StructuredError
     attr_reader :origin, :klass, :backtrace_lines, :details
 
     def initialize(message, origin: nil, klass: nil, backtrace_lines: nil, details: nil)
@@ -104,26 +107,25 @@ module Kobako
     end
   end
 
+  # Sandbox / wire layer. Raised when the guest ran to completion but
+  # execution failed due to a mruby script error, a protocol fault, or a
+  # host-side wire decode failure on an otherwise valid outcome tag.
+  class SandboxError < Error
+    include StructuredError
+  end
+
   # Service layer. Raised when a Service capability call inside a mruby
   # script reported an application-level failure that the script did not
   # rescue.
   class ServiceError < Error
-    attr_reader :origin, :klass, :backtrace_lines, :details
-
-    def initialize(message, origin: nil, klass: nil, backtrace_lines: nil, details: nil)
-      super(message)
-      @origin = origin
-      @klass = klass
-      @backtrace_lines = backtrace_lines
-      @details = details
-    end
+    include StructuredError
   end
 
-  # HandlerExhaustedError is the canonical SandboxError subclass for the
+  # HandleExhaustedError is the canonical SandboxError subclass for the
   # id-cap-hit path. Raised when the per-invocation Handle ID counter in
   # Catalog::Handles reaches +0x7fff_ffff+ (2³¹ − 1) and further
   # allocation would exceed the cap.
-  class HandlerExhaustedError < SandboxError; end
+  class HandleExhaustedError < SandboxError; end
 
   # BytecodeError is the SandboxError subclass raised when a
   # `#preload(binary:)` snippet fails structural validation during the

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,23 +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: nil, stderr_limit: nil,
-                   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
@@ -207,17 +210,28 @@ module Kobako
 
     private
 
-    # Configure the +Runtime+'s host↔guest dispatch wiring. Builds a
-    # lambda that re-enters the guest via
-    # +Runtime#yield_to_active_invocation+ and a dispatch +Proc+ that routes
-    # guest→host calls through the stateless +Transport::Dispatcher+,
-    # capturing +@services+ / +@handler+ in the closure. Both are registered
-    # on the +Runtime+ once at construction time so the wasm ext callback can
-    # fire without further setup.
+    # 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
+    # closure. The ext hands the +Proc+ a per-dispatch +guest_yielder+ — a
+    # +String → String+ callable that re-enters the in-flight guest to run a
+    # yielded block — which the +Dispatcher+ forwards to the +Transport::Yielder+
+    # it builds for the call. Registered once at construction time so the
+    # wasm ext callback can fire without further setup.
     def install_dispatch_proc!
-      yield_to_guest = ->(args_bytes) { @runtime.yield_to_active_invocation(args_bytes) }
-      @runtime.on_dispatch = lambda do |request_bytes|
-        Transport::Dispatcher.dispatch(request_bytes, @services, @handler, yield_to_guest)
+      @runtime.on_dispatch = lambda do |request_bytes, guest_yielder|
+        Transport::Dispatcher.dispatch(request_bytes, @services, @handler, guest_yielder)
       end
     end
 
@@ -226,8 +240,7 @@ module Kobako
     # state — capture buffers, truncation predicates, and the
     # +Catalog::Handles+ counter — before the guest runs. The
     # +Catalog::Handles+ itself is held as +@handler+ and never exposed
-    # beyond this class: SPEC.md Terminology pins it as "Not exposed to the
-    # Host App".
+    # beyond this class — it is not part of the Host App's surface.
     def begin_invocation!
       @services.seal!
       @handler.reset!
@@ -239,9 +252,10 @@ module Kobako
     # the +invoke!+ +ensure+ block so the usage record is populated on
     # every outcome — value return, +Kobako::TrapError+ (including
     # +TimeoutError+ / +MemoryLimitError+), +Kobako::SandboxError+,
-    # and +Kobako::ServiceError+. On the success path the same figures
-    # already arrive via +Snapshot#usage+; on the trap path the Snapshot
-    # never reaches Ruby so the ext readout here is the only source.
+    # and +Kobako::ServiceError+. +Runtime#usage+ is the single source for
+    # both paths: the figures are stashed in the ext on every outcome, so
+    # 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
@@ -267,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+ (SPEC.md Internal Concepts →
-    # Snapshot). 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