kobako 0.2.1 → 0.4.0

data/ext/kobako/src/wasm.rs

@@ -32,10 +32,23 @@ mod host_state;
 mod instance;
 
 use magnus::value::Lazy;
-use magnus::{function, method, prelude::*, Error as MagnusError, ExceptionClass, RModule, Ruby};
+use magnus::{
+    function, method, prelude::*, Error as MagnusError, ExceptionClass, RModule, RString, Ruby,
+};
 
 use instance::Instance;
 
+/// 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.
+pub(crate) fn rstring_to_vec(s: RString) -> Vec<u8> {
+    // SAFETY: see item doc.
+    unsafe { s.as_slice() }.to_vec()
+}
+
 // ---------------------------------------------------------------------------
 // Error classes (lazy-resolved from Ruby once Kobako::Wasm is defined).
 // ---------------------------------------------------------------------------
@@ -69,14 +82,14 @@ pub(crate) fn wasm_err(ruby: &Ruby, msg: impl Into<String>) -> MagnusError {
 }
 
 /// Construct a `Kobako::Wasm::TimeoutError` magnus error. Surfaces the
-/// SPEC.md E-19 wall-clock cap path so the Sandbox layer can rewrap it
+/// docs/behavior.md E-19 wall-clock cap path so the Sandbox layer can rewrap it
 /// as `Kobako::TimeoutError`.
 pub(crate) fn timeout_err(ruby: &Ruby, msg: impl Into<String>) -> MagnusError {
     MagnusError::new(ruby.get_inner(&WASM_TIMEOUT_ERROR), msg.into())
 }
 
 /// Construct a `Kobako::Wasm::MemoryLimitError` magnus error. Surfaces
-/// the SPEC.md E-20 linear-memory cap path so the Sandbox layer can
+/// the docs/behavior.md E-20 linear-memory cap path so the Sandbox layer can
 /// rewrap it as `Kobako::MemoryLimitError`.
 pub(crate) fn memory_limit_err(ruby: &Ruby, msg: impl Into<String>) -> MagnusError {
     MagnusError::new(ruby.get_inner(&WASM_MEMORY_LIMIT_ERROR), msg.into())
@@ -92,7 +105,7 @@ pub fn init(ruby: &Ruby, kobako: RModule) -> Result<(), MagnusError> {
     // Error hierarchy. ModuleNotBuiltError is the headline error for the
     // common pre-build state where `data/kobako.wasm` has not yet been
     // produced (e.g. fresh clone before `rake compile`). TimeoutError and
-    // MemoryLimitError carry the SPEC.md B-01 per-run cap paths up to the
+    // MemoryLimitError carry the docs/behavior.md B-01 per-run cap paths up to the
     // Sandbox layer.
     let base_err = wasm.define_error("Error", ruby.exception_standard_error())?;
     wasm.define_error("ModuleNotBuiltError", base_err)?;
@@ -102,10 +115,12 @@ pub fn init(ruby: &Ruby, kobako: RModule) -> Result<(), MagnusError> {
     let instance = wasm.define_class("Instance", ruby.class_object())?;
     instance.define_singleton_method("from_path", function!(Instance::from_path, 5))?;
     instance.define_method("server=", method!(Instance::set_server, 1))?;
-    instance.define_method("run", method!(Instance::run, 2))?;
+    instance.define_method("eval", method!(Instance::eval, 3))?;
+    instance.define_method("run", method!(Instance::run, 3))?;
     instance.define_method("stdout", method!(Instance::stdout, 0))?;
     instance.define_method("stderr", method!(Instance::stderr, 0))?;
     instance.define_method("outcome!", method!(Instance::outcome, 0))?;
+    instance.define_method("usage", method!(Instance::usage, 0))?;
 
     Ok(())
 }

data/lib/kobako/capture.rb

@@ -2,15 +2,16 @@
 
 module Kobako
   # Host-side captured prefix of guest stdout / stderr produced during a
-  # single +Kobako::Sandbox#run+, paired with the truncation flag the WASI
-  # pipe sets when the guest wrote past the configured per-channel cap
-  # ({SPEC.md B-04}[link:../../SPEC.md]).
+  # single +Kobako::Sandbox+ invocation, paired with the truncation flag
+  # the WASI pipe sets when the guest wrote past the configured per-channel
+  # cap ({docs/behavior.md B-04}[link:../../docs/behavior.md]).
   #
   # Immutable value object: the captured bytes and the truncation flag
   # always travel together and the instance is frozen on construction.
   # Construct via +Capture.from_ext+ for ext-provided binary bytes (handles
-  # UTF-8 / ASCII-8BIT fallback) or reach +Capture::EMPTY+ for the pre-run
-  # sentinel that +Sandbox+ uses before any +#run+ has executed.
+  # UTF-8 / ASCII-8BIT fallback) or reach +Capture::EMPTY+ for the pre-
+  # invocation sentinel that +Sandbox+ uses before any invocation has
+  # executed.
   class Capture
     attr_reader :bytes
 
@@ -24,8 +25,8 @@ module Kobako
     end
 
     # Returns +true+ iff the underlying capture channel exceeded its
-    # configured cap during the originating +Sandbox#run+
-    # ({SPEC.md B-04}[link:../../SPEC.md]).
+    # configured cap during the originating +Sandbox+ invocation
+    # ({docs/behavior.md B-04}[link:../../docs/behavior.md]).
     def truncated? = @truncated
 
     # Construct a Capture from ext-provided binary bytes. Coerces +bytes+
@@ -38,9 +39,10 @@ module Kobako
       new(bytes: copy, truncated: truncated)
     end
 
-    # Pre-run sentinel ({SPEC.md B-05}[link:../../SPEC.md]). Empty UTF-8
-    # bytes and +truncated? == false+; reused by every fresh +Sandbox+ and
-    # by +Sandbox#run+ between invocations to denote "no capture yet".
+    # Pre-invocation sentinel ({docs/behavior.md B-05}[link:../../docs/behavior.md]).
+    # Empty UTF-8 bytes and +truncated? == false+; reused by every fresh
+    # +Sandbox+ and by +Sandbox+ between invocations to denote "no capture
+    # yet".
     EMPTY = new(bytes: "", truncated: false)
   end
 end

data/lib/kobako/codec/decoder.rb

@@ -9,7 +9,7 @@ require_relative "utils"
 module Kobako
   module Codec
     # Module-level entry point for the host side of the kobako wire
-    # (SPEC.md → Wire Codec → Type Mapping).
+    # ({docs/wire-codec.md}[link:../../../docs/wire-codec.md] § Type Mapping).
     #
     # Translates msgpack gem exceptions into the kobako error taxonomy
     # ({Truncated}, {InvalidType}, {InvalidEncoding}, {UnsupportedType}) so
@@ -38,11 +38,10 @@ module Kobako
       # buffer edge.
       rescue ::MessagePack::UnpackError, ::EOFError => e
         raise Truncated, e.message
-      rescue ::EncodingError => e
-        raise InvalidEncoding, e.message
       end
 
-      # SPEC pins +str+ family payloads to UTF-8 (Wire Codec → str/bin
+      # SPEC pins +str+ family payloads to UTF-8
+      # ({docs/wire-codec.md}[link:../../../docs/wire-codec.md] § str/bin
       # Encoding Rules). The msgpack gem returns UTF-8-tagged Strings for
       # str family but does not validate the bytes; +bin+ family decodes
       # to ASCII-8BIT. Walk the tree once and reject invalid UTF-8 in any

data/lib/kobako/codec/encoder.rb

@@ -8,7 +8,7 @@ require_relative "factory"
 module Kobako
   module Codec
     # Module-level entry point for the host side of the kobako wire
-    # (SPEC.md → Wire Codec → Type Mapping).
+    # ({docs/wire-codec.md}[link:../../../docs/wire-codec.md] § Type Mapping).
     #
     # The codec backbone is the official +msgpack+ gem: integers, floats,
     # strings, arrays, and maps go through the gem's narrowest-encoding

data/lib/kobako/codec/error.rb

@@ -4,8 +4,9 @@ module Kobako
   module Codec
     # Base class for all wire-codec faults raised by the pure-Ruby host codec.
     #
-    # The wire codec implements the binary contract pinned in SPEC.md
-    # (Wire Codec → Type Mapping). Every wire violation surfaces as a
+    # The wire codec implements the binary contract pinned in
+    # {docs/wire-codec.md}[link:../../../docs/wire-codec.md] § Type Mapping.
+    # Every wire violation surfaces as a
     # subclass of {Error} so callers can pattern-match on the specific
     # fault while still rescuing all codec faults via this base class.
     #

data/lib/kobako/codec/factory.rb

@@ -6,13 +6,14 @@ require "msgpack"
 
 require_relative "error"
 require_relative "utils"
-require_relative "../rpc/handle"
+require_relative "../handle"
 require_relative "../rpc/fault"
 
 module Kobako
   module Codec
     # Cached +MessagePack::Factory+ that owns the kobako wire ext-type
-    # registration (SPEC.md → Wire Codec → Ext Types).
+    # registration ({docs/wire-codec.md}[link:../../../docs/wire-codec.md]
+    # § Ext Types).
     #
     # The factory is the single place in the host gem that touches the
     # msgpack API — both {Encoder} and {Decoder} delegate through it, so
@@ -31,16 +32,19 @@ module Kobako
       extend SingleForwardable
 
       # MessagePack ext type code reserved for Symbol
-      # (SPEC.md → Wire Codec → Ext Types → ext 0x00). Class-private —
-      # mirrors +codec::EXT_SYMBOL+ on the Rust side.
+      # ({docs/wire-codec.md}[link:../../../docs/wire-codec.md] § Ext Types
+      # → ext 0x00). Class-private — mirrors +codec::EXT_SYMBOL+ on the
+      # Rust side.
       EXT_SYMBOL = 0x00
       # MessagePack ext type code reserved for Capability Handle
-      # (SPEC.md → Wire Codec → Ext Types → ext 0x01). Class-private —
-      # mirrors +codec::EXT_HANDLE+ on the Rust side.
+      # ({docs/wire-codec.md}[link:../../../docs/wire-codec.md] § Ext Types
+      # → ext 0x01). Class-private — mirrors +codec::EXT_HANDLE+ on the
+      # Rust side.
       EXT_HANDLE = 0x01
       # MessagePack ext type code reserved for Exception envelope
-      # (SPEC.md → Wire Codec → Ext Types → ext 0x02). Class-private —
-      # mirrors +codec::EXT_ERRENV+ on the Rust side.
+      # ({docs/wire-codec.md}[link:../../../docs/wire-codec.md] § Ext Types
+      # → ext 0x02). Class-private — mirrors +codec::EXT_ERRENV+ on the
+      # Rust side.
       EXT_ERRENV = 0x02
       private_constant :EXT_SYMBOL, :EXT_HANDLE, :EXT_ERRENV
 
@@ -85,16 +89,18 @@ module Kobako
       # binary-encoding fallback that msgpack-gem's default unpacker
       # would otherwise apply. The re-tag step lives here because the
       # msgpack ext-type unpacker hands us binary bytes; the assertion
-      # itself is shared with {Decoder} via {Utils.assert_utf8!}.
+      # itself is shared with {Decoder} via {Utils.assert_utf8!}. The
+      # +"Symbol"+ label keeps the error message in Ruby vocabulary
+      # rather than wire-ext-code vocabulary.
       def unpack_symbol(payload)
         name = payload.b.force_encoding(Encoding::UTF_8)
-        Utils.assert_utf8!(name, "ext 0x00 payload")
+        Utils.assert_utf8!(name, "Symbol payload")
         name.to_sym
       end
 
       def register_handle
         @factory.register_type(
-          EXT_HANDLE, RPC::Handle,
+          EXT_HANDLE, Kobako::Handle,
           packer: ->(handle) { [handle.id].pack("N") },
           unpacker: ->(payload) { unpack_handle(payload) }
         )
@@ -108,17 +114,18 @@ module Kobako
         )
       end
 
-      # Peel off the fixext-4 frame, hand the bytes to +RPC::Handle.new+, and
-      # translate the +ArgumentError+ raised by Handle's invariants into
-      # a wire-layer +InvalidType+ via {Codec::Utils.wire_boundary}.
+      # Peel off the fixext-4 frame, hand the bytes to the
+      # Host-Gem-internal +Kobako::Handle.from_wire+ factory, and
+      # translate the +ArgumentError+ raised by Handle's invariants
+      # into a wire-layer +InvalidType+ via {Codec::Utils.wire_boundary}.
       # The Value Object owns the id-range contract; this method only
       # owns the frame shape.
       def unpack_handle(payload)
         bytes = payload.b
-        raise InvalidType, "ext 0x01 payload must be 4 bytes, got #{bytes.bytesize}" unless bytes.bytesize == 4
+        raise InvalidType, "Handle payload must be 4 bytes, got #{bytes.bytesize}" unless bytes.bytesize == 4
 
         id = bytes.unpack1("N") # : Integer
-        Codec::Utils.wire_boundary { RPC::Handle.new(id) }
+        Codec::Utils.wire_boundary { Kobako::Handle.from_wire(id) }
       end
 
       # Encode the inner ext-0x02 map via {Encoder} (not +factory.dump+) so
@@ -144,7 +151,7 @@ module Kobako
       # and re-opens the Decoder's special case for Fault (removed in M5).
       def unpack_fault(payload)
         map = Decoder.decode(payload)
-        raise InvalidType, "ext 0x02 payload must be a map" unless map.is_a?(Hash)
+        raise InvalidType, "Fault payload must be a map" unless map.is_a?(Hash)
 
         Codec::Utils.wire_boundary do
           RPC::Fault.new(type: map["type"], message: map["message"], details: map["details"])

data/lib/kobako/codec/utils.rb

@@ -1,29 +1,37 @@
 # frozen_string_literal: true
 
 require_relative "error"
+require_relative "../handle"
 
 module Kobako
   module Codec
     # Wire-codec helpers shared by the host-side encoders and decoders.
-    # The single concern today is UTF-8 assertion at the wire boundary
-    # (SPEC.md → Wire Codec → str/bin Encoding Rules and Ext Types →
-    # ext 0x00). Two call sites lean on this:
+    # Three concerns live here today:
     #
-    #   - {Decoder} validates +str+ family payloads as it walks the
-    #     decoded value tree.
-    #   - {Factory} validates the +ext 0x00+ Symbol payload after
-    #     re-tagging the binary bytes as UTF-8.
+    #   - UTF-8 assertion at the wire boundary
+    #     ({docs/wire-codec.md}[link:../../../docs/wire-codec.md]
+    #     § str/bin Encoding Rules and § Ext Types → ext 0x00). Used by
+    #     {Decoder} when walking +str+ family payloads and by {Factory}
+    #     when validating the +ext 0x00+ Symbol payload.
+    #   - Wire-boundary +ArgumentError+ translation
+    #     ({wire_boundary}) so the public taxonomy stays
+    #     {Kobako::Codec::Error}.
+    #   - Wire-representability predicate ({wire_representable?}) and
+    #     the symmetric host→guest +#run+ argument walk
+    #     ({deep_wrap}) used by +Kobako::Invocation#encode+ to route
+    #     non-wire-representable leaves through the Sandbox's
+    #     +Kobako::HandleTable+
+    #     ({docs/behavior.md B-34}[link:../../../docs/behavior.md]).
     #
-    # Encoding setup (re-tagging binary as UTF-8 when needed) stays at
-    # the caller — only the assertion shape is shared. The helper does
-    # not mutate +string+; it only inspects +String#valid_encoding?+
-    # against +string+'s current encoding tag.
+    # All helpers are pure — they only inspect inputs, never mutate
+    # them — except {deep_wrap}, whose only side effect is allocating
+    # new Handle ids into the supplied table.
     module Utils
       module_function
 
       # Raise {InvalidEncoding} unless +string+'s bytes are valid under
       # its current encoding tag. +label+ is the caller-supplied prefix
-      # for the error message (e.g. +"str payload"+, +"ext 0x00 payload"+).
+      # for the error message (e.g. +"str payload"+, +"Symbol payload"+).
       def assert_utf8!(string, label)
         return if string.valid_encoding?
 
@@ -50,6 +58,91 @@ module Kobako
       rescue ::ArgumentError => e
         raise InvalidType, e.message
       end
+
+      # Inclusive Integer range the msgpack gem encodes without raising
+      # +RangeError+ at encode time — signed +int 64+ minimum through
+      # unsigned +uint 64+ maximum
+      # ({docs/wire-codec.md}[link:../../../docs/wire-codec.md] § Type
+      # Mapping #3, the +fixint+ / +int 8..64+ / +uint 8..64+ union).
+      # Anchored as a +Range+ so {primitive_wire_type?} stays a single
+      # dispatch line. This is the codec's wire-encode domain — not to
+      # be confused with the Handle id range, which lives on
+      # +Kobako::Handle+ as +MIN_ID+ / +MAX_ID+ (1..2^31 − 1) and
+      # represents a different concept entirely.
+      MSGPACK_INT_RANGE = (-(2**63)..((2**64) - 1))
+
+      # Wire-type predicate
+      # ({docs/wire-codec.md}[link:../../../docs/wire-codec.md] § Type
+      # Mapping). Returns +true+ when +value+ belongs to the closed
+      # 12-entry wire set — +nil+, +TrueClass+, +FalseClass+, +Integer+
+      # (in the +i64..u64+ value domain), +Float+, +String+, +Symbol+,
+      # +Kobako::Handle+, +Array+ whose every element is itself
+      # wire-representable, or +Hash+ whose every key and value are
+      # wire-representable. Integers outside the codec's signed-64 /
+      # unsigned-64 union are rejected so the predicate agrees with the
+      # msgpack gem's encode-time +RangeError+ behaviour the codec
+      # already surfaces as {UnsupportedType}.
+      def wire_representable?(value)
+        primitive_wire_type?(value) || container_wire_representable?(value)
+      end
+
+      # Deep-walk Array / Hash containers in +value+ and replace every
+      # leaf that fails {wire_representable?} with a +Kobako::Handle+
+      # allocated from +handle_table+
+      # ({docs/behavior.md B-34}[link:../../../docs/behavior.md]). The
+      # walk only descends through wire-representable container shapes
+      # (Array, Hash) one structural level at a time; a non-
+      # wire-representable leaf is wrapped as-is without inspecting its
+      # internal structure. An existing +Kobako::Handle+ is wire-
+      # representable and passes through unchanged — auto-wrap never
+      # re-wraps a Handle.
+      #
+      # +value+ may be any Ruby value; +handle_table+ must respond to
+      # +#alloc(object) -> Kobako::Handle+ (a host-side
+      # +Kobako::HandleTable+). Returns a structurally equivalent value
+      # whose leaves are either wire-representable or +Kobako::Handle+
+      # tokens.
+      #
+      # The block bodies spell +Utils.deep_wrap+ explicitly rather than
+      # the unqualified +deep_wrap+ because +module_function+ makes the
+      # instance copy of these helpers private; an implicit receiver
+      # inside a block would resolve against the enclosing +self+
+      # (still +Utils+ at definition time, but the qualified form keeps
+      # the dispatch readable when the recursive call sits inside a
+      # Proc captured from elsewhere).
+      def deep_wrap(value, handle_table)
+        case value
+        when ::Array then value.map { |element| Utils.deep_wrap(element, handle_table) }
+        when ::Hash  then value.transform_values { |val| Utils.deep_wrap(val, handle_table) }
+        else
+          wire_representable?(value) ? value : handle_table.alloc(value)
+        end
+      end
+
+      # Predicate split out of {wire_representable?} for cyclomatic
+      # budget — the closed-set non-container branch. Returns +true+ for
+      # the wire scalar leaves and an existing Handle. Not part of the
+      # public surface; reach for {wire_representable?} instead.
+      def primitive_wire_type?(value)
+        case value
+        when ::NilClass, ::TrueClass, ::FalseClass, ::Float, ::String, ::Symbol, Kobako::Handle then true
+        when ::Integer then MSGPACK_INT_RANGE.cover?(value)
+        else false
+        end
+      end
+
+      # Predicate split out of {wire_representable?} for cyclomatic
+      # budget — the container branch. Recurses into Array elements and
+      # Hash key+value pairs through the public {wire_representable?}.
+      # Not part of the public surface; reach for {wire_representable?}
+      # instead.
+      def container_wire_representable?(value)
+        case value
+        when ::Array then value.all? { |element| Utils.wire_representable?(element) }
+        when ::Hash  then value.all? { |key, val| Utils.wire_representable?(key) && Utils.wire_representable?(val) }
+        else false
+        end
+      end
     end
   end
 end

data/lib/kobako/codec.rb

@@ -4,7 +4,8 @@ require_relative "codec/error"
 
 module Kobako
   # Host-side MessagePack codec for the kobako wire contract — the
-  # byte-level layer (SPEC.md → Wire Codec). Two consumers sit on top:
+  # byte-level layer ({docs/wire-codec.md}[link:../../docs/wire-codec.md]).
+  # Two consumers sit on top:
   # +Kobako::RPC+ pins the RPC framing (Request / Response)
   # and +Kobako::Outcome+ owns the per-+#run+ outcome envelope (Result
   # body / Panic map).

data/lib/kobako/errors.rb

@@ -2,12 +2,12 @@
 
 # Top-level Kobako namespace.
 module Kobako
-  # Three-class error taxonomy (SPEC.md → Error Scenarios).
+  # Three-class error taxonomy (docs/behavior.md § Error Scenarios).
   #
-  # Every `Kobako::Sandbox#run` invocation either returns a value or raises
+  # Every `Kobako::Sandbox` invocation (`#eval` or `#run`) either returns a value or raises
   # exactly one of these three classes. Attribution is decided after the
-  # guest binary returns control to the host (SPEC "Step 1 — Wasm trap"
-  # then "Step 2 — Outcome envelope tag").
+  # guest binary returns control to the host (docs/behavior.md
+  # "Step 1 — Wasm trap" then "Step 2 — Outcome envelope tag").
   #
   # Three top-level branches:
   #
@@ -20,7 +20,7 @@ module Kobako
   #   * {ServiceError}  — service / capability layer (a Service RPC that
   #                       failed and was not rescued inside the script).
   #
-  # Subclasses pinned by SPEC "Error Classes":
+  # Subclasses pinned by docs/behavior.md Error Classes:
   #
   #   * {HandleTableExhausted} < {SandboxError}    — id cap hit (B-21).
   #   * {ServiceError::Disconnected} < {ServiceError} — `:disconnected`
@@ -35,7 +35,7 @@ module Kobako
   # violation that signals a corrupted guest execution environment
   # (zero-length OUTCOME_BUFFER, unknown outcome tag — SPEC E-02 / E-03).
   #
-  # Two named subclasses cover the configured per-run caps from B-01:
+  # Two named subclasses cover the configured per-invocation caps from B-01:
   #
   #   * {TimeoutError}     — wall-clock +timeout+ exceeded (E-19).
   #   * {MemoryLimitError} — guest +memory.grow+ would exceed
@@ -47,13 +47,13 @@ module Kobako
   # first.
   class TrapError < Error; end
 
-  # Wall-clock timeout cap exhausted. {SPEC.md E-19}[link:../../SPEC.md]:
+  # Wall-clock timeout cap exhausted. {docs/behavior.md E-19}[link:../../docs/behavior.md]:
   # the absolute deadline +entry_time + timeout+ passed and the next guest
   # wasm safepoint trapped. The Sandbox is unrecoverable after this point;
   # discard and recreate before another execution.
   class TimeoutError < TrapError; end
 
-  # Linear-memory cap exhausted. {SPEC.md E-20}[link:../../SPEC.md]:
+  # Linear-memory cap exhausted. {docs/behavior.md E-20}[link:../../docs/behavior.md]:
   # a guest +memory.grow+ would have pushed linear memory past the
   # configured +memory_limit+. The Sandbox is unrecoverable after this
   # point; discard and recreate before another execution.
@@ -88,7 +88,7 @@ module Kobako
       @details = details
     end
 
-    # SPEC "Error Classes": ServiceError::Disconnected is raised
+    # docs/behavior.md Error Classes: ServiceError::Disconnected is raised
     # when the RPC target Handle resolves to the `:disconnected` sentinel
     # in the HandleTable (ABA protection rule — id exists but entry was
     # invalidated). E-14.
@@ -103,9 +103,21 @@ module Kobako
   # directly), it surfaces as a SandboxError.
   class HandleTableError < SandboxError; end
 
-  # SPEC "Error Classes": HandleTableExhausted is the canonical
+  # docs/behavior.md Error Classes: HandleTableExhausted is the canonical
   # SandboxError subclass for the id-cap-hit path (B-21). Inherits from
   # HandleTableError so a single `rescue Kobako::HandleTableError` covers
   # both lookup-failure and cap-exhaustion paths.
   class HandleTableExhausted < HandleTableError; end
+
+  # docs/behavior.md Error Classes: BytecodeError is the SandboxError
+  # subclass raised when a `#preload(binary:)` snippet fails structural
+  # validation during the first invocation's snippet replay against a
+  # fresh `mrb_state` (E-37 RITE version mismatch, E-38 corrupt body).
+  # Bytecode that loads cleanly and then raises at top level is E-36
+  # and surfaces as plain `SandboxError` with the natural mruby class
+  # preserved. Inherits from SandboxError so a single
+  # `rescue Kobako::SandboxError` covers both source and bytecode
+  # snippet failures while callers wanting bytecode-specific handling
+  # can `rescue Kobako::BytecodeError` directly.
+  class BytecodeError < SandboxError; end
 end

data/lib/kobako/handle.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Kobako
+  # Wire-level value object for an ext-0x01 Capability Handle, used in both
+  # directions across the Sandbox boundary: as a Service method's return
+  # value (guest→host return path; {docs/behavior.md B-14}[link:../../docs/behavior.md])
+  # and as a +#run+ argument auto-wrapped by the host
+  # ({docs/behavior.md B-34}[link:../../docs/behavior.md]).
+  #
+  # SPEC pins the binary layout to fixext 4 with a 4-byte big-endian u32
+  # payload ({docs/wire-codec.md}[link:../../docs/wire-codec.md]
+  # § Ext Types → ext 0x01). ID 0 is reserved as the invalid sentinel;
+  # the maximum valid ID is 0x7fff_ffff (2^31 - 1).
+  #
+  # The constructor is internal to the Host Gem. +Kobako::Handle.new+ is
+  # privatised so Host App code cannot fabricate a Handle from a bare
+  # integer; legitimate Handle instances enter Host App code only as
+  # fields on raised error objects. The Host Gem itself constructs
+  # Handles through {.from_wire}, which exists at exactly two call
+  # sites: +Kobako::Codec::Factory#unpack_handle+ (wire decode) and
+  # +Kobako::Codec::Utils.deep_wrap+ / +Kobako::RPC::Dispatcher#wrap_as_handle+
+  # (allocator paths). Both live inside +lib/kobako/+ and are not part
+  # of any public surface.
+  #
+  # The mruby counterpart +Kobako::Handle+ lives inside the Wasm guest
+  # under the same canonical name and shares neither code nor instances
+  # with this host-side class.
+  class Handle < Data.define(:id)
+    # Inclusive lower bound on the wire Handle ID. ID 0 is reserved as
+    # the invalid sentinel and is never allocated.
+    MIN_ID = 1
+    # Inclusive upper bound on the wire Handle ID. The cap matches the
+    # u32 signed-positive range so Handle IDs fit in a signed integer
+    # on either side of the wire without re-encoding.
+    MAX_ID = 0x7fff_ffff
+
+    # steep:ignore:start
+    def initialize(id:)
+      raise ArgumentError, "Handle id must be Integer" unless id.is_a?(Integer)
+      raise ArgumentError, "Handle id #{id} out of range [#{MIN_ID}, #{MAX_ID}]" unless id.between?(MIN_ID, MAX_ID)
+
+      super
+    end
+    # steep:ignore:end
+
+    private_class_method :new
+
+    # Host Gem–internal factory. Allocates the Data instance through
+    # +Class#allocate+ and dispatches +#initialize+ explicitly so the
+    # invariant checks still run, while keeping the public +.new+
+    # privatised against Host App callers.
+    #
+    # Two collaborators call this: the codec when an ext 0x01 frame is
+    # decoded off the wire, and the allocator paths when a host-side
+    # Ruby object is registered into the Sandbox's +HandleTable+. Both
+    # paths live inside +lib/kobako/+ and treat this method as a
+    # package-private constructor.
+    def self.from_wire(id)
+      allocate.tap { |handle| handle.send(:initialize, id: id) }
+    end
+  end
+end