kobako 0.1.0

data/lib/kobako/sandbox/output_buffer.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Kobako
+  class Sandbox
+    # In-memory bounded byte buffer for one of the guest's output channels.
+    # Tracks accumulated bytes (binary-encoded) and enforces the per-channel
+    # cap by truncating-with-marker ({SPEC.md B-04}[link:../../../SPEC.md]).
+    #
+    # When the accumulated byte count would exceed the limit, the buffer keeps
+    # as many leading bytes as fit and seals itself. Subsequent appends are
+    # discarded. On the next read, +OUTPUT_TRUNCATION_MARKER+ is appended to
+    # signal the overflow to the caller.
+    class OutputBuffer
+      # Marker appended to a buffer that hit its capture limit
+      # ({SPEC.md B-04}[link:../../../SPEC.md]).
+      OUTPUT_TRUNCATION_MARKER = "[truncated]"
+
+      attr_reader :limit
+
+      def initialize(limit)
+        raise ArgumentError, "limit must be a positive Integer" unless limit.is_a?(Integer) && limit.positive?
+
+        @limit = limit
+        @bytes = String.new(encoding: Encoding::ASCII_8BIT)
+        @truncated = false
+      end
+
+      # Append +bytes+ to the buffer. If the append would push the
+      # cumulative byte count past the limit, the buffer keeps as many
+      # leading bytes as fit and seals itself; subsequent appends are
+      # discarded. {SPEC.md B-04}[link:../../../SPEC.md] — truncation is a
+      # non-error outcome.
+      def <<(bytes)
+        return self if @truncated
+
+        appended = bytes.to_s.b
+        room = @limit - @bytes.bytesize
+        if appended.bytesize <= room
+          @bytes << appended
+        else
+          @bytes << appended.byteslice(0, room) if room.positive?
+          @truncated = true
+        end
+        self
+      end
+
+      # Returns +true+ when the buffer was sealed by an overflow.
+      def truncated?
+        @truncated
+      end
+
+      # Returns the number of bytes currently stored.
+      def bytesize
+        @bytes.bytesize
+      end
+
+      # Returns +true+ when the buffer is empty.
+      def empty?
+        @bytes.empty?
+      end
+
+      # Returns the accumulated bytes as a UTF-8 String, with the
+      # +[truncated]+ marker appended when the buffer overflowed.
+      def to_s
+        copy = @bytes.dup
+        copy << OUTPUT_TRUNCATION_MARKER.b if @truncated
+        copy.force_encoding(Encoding::UTF_8)
+        copy.valid_encoding? ? copy : copy.dup.force_encoding(Encoding::ASCII_8BIT)
+      end
+
+      # Reset the buffer to empty. Used at the per-+#run+ boundary.
+      def clear
+        @bytes.clear
+        @truncated = false
+        self
+      end
+    end
+  end
+end

data/lib/kobako/sandbox.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+require_relative "registry"
+require_relative "wire"
+require_relative "sandbox/output_buffer"
+require_relative "sandbox/outcome_decoder"
+
+module Kobako
+  # Kobako::Sandbox — the user-facing entry point for executing guest mruby
+  # scripts inside a wasmtime-hosted Wasm module
+  # ({SPEC.md B-01}[link:../../SPEC.md]).
+  #
+  # The Sandbox owns the +Kobako::Wasm::Instance+, the per-instance Registry
+  # (which itself owns the per-run HandleTable), and bounded stdout / stderr
+  # capture buffers. The underlying wasmtime Engine and compiled Module are
+  # cached at process scope by the native ext and never surface to Ruby —
+  # constructing many Sandboxes amortises both costs automatically.
+  #
+  # Buffer overflow policy ({SPEC.md B-04}[link:../../SPEC.md]): once an
+  # append would push the cumulative byte count past the per-channel
+  # `*_limit`, the OutputBuffer truncates — it stores a prefix that fits
+  # under the cap and appends a +[truncated]+ marker on the next read.
+  # Truncation does NOT raise. The marker constant lives on
+  # +Kobako::Sandbox::OutputBuffer::OUTPUT_TRUNCATION_MARKER+.
+  class Sandbox
+    # Default per-channel capture ceiling: 1 MiB
+    # ({SPEC.md B-01 footnote}[link:../../SPEC.md]).
+    DEFAULT_OUTPUT_LIMIT = 1 << 20
+
+    attr_reader :wasm_path, :instance,
+                :stdout_buffer, :stderr_buffer,
+                :stdout_limit, :stderr_limit, :services
+
+    # Returns the complete byte content guest wrote to stdout during the most
+    # recent +#run+ as a UTF-8 String, or an empty String before any +#run+
+    # call. {SPEC.md B-04}[link:../../SPEC.md]: may contain a +[truncated]+
+    # marker when the cap was hit.
+    def stdout
+      @stdout_buffer.to_s
+    end
+
+    # Returns the complete byte content guest wrote to stderr during the most
+    # recent +#run+ as a UTF-8 String, or an empty String before any +#run+
+    # call. {SPEC.md B-04}[link:../../SPEC.md]: may contain a +[truncated]+
+    # marker when the cap was hit.
+    def stderr
+      @stderr_buffer.to_s
+    end
+
+    # Build a fresh Sandbox.
+    #
+    # +wasm_path+ is the absolute path to the Guest Binary; defaults to the
+    # gem-bundled +data/kobako.wasm+. +stdout_limit+ and +stderr_limit+ cap
+    # the per-run byte ceiling for each capture channel (default 1 MiB).
+    def initialize(wasm_path: nil, stdout_limit: nil, stderr_limit: nil)
+      @wasm_path = wasm_path || Kobako::Wasm.default_path
+      @stdout_limit = stdout_limit || DEFAULT_OUTPUT_LIMIT
+      @stderr_limit = stderr_limit || DEFAULT_OUTPUT_LIMIT
+      @instance = Kobako::Wasm::Instance.from_path(@wasm_path)
+      @stdout_buffer = OutputBuffer.new(@stdout_limit)
+      @stderr_buffer = OutputBuffer.new(@stderr_limit)
+      @services = Kobako::Registry.new
+      @instance.set_registry(@services)
+    end
+
+    # Declare or retrieve the Service Group named +name+ on this Sandbox
+    # ({SPEC.md B-07, B-09, B-10}[link:../../SPEC.md]). +name+ must be a
+    # Symbol or String in constant form. Returns the
+    # +Kobako::Registry::ServiceGroup+.
+    #
+    # Raises +ArgumentError+ when called after +#run+, or when +name+ does
+    # not match the constant-name pattern.
+    def define(name)
+      @services.define(name)
+    end
+
+    # Execute a guest mruby script
+    # ({SPEC.md B-02 / B-03}[link:../../SPEC.md]). +source+ is the mruby
+    # source code as a UTF-8 String. Returns the deserialized last
+    # expression of the script.
+    #
+    # Source delivery uses the WASI stdin two-frame protocol
+    # ({SPEC.md ABI Signatures}[link:../../SPEC.md]): Frame 1 carries the
+    # msgpack-encoded preamble (Service Group registry snapshot) and Frame 2
+    # carries the user script UTF-8 bytes. Each frame is prefixed by a
+    # 4-byte big-endian u32 length.
+    #
+    # Raises +Kobako::TrapError+ on a Wasm trap or wire-violation fallback;
+    # +Kobako::SandboxError+ when the guest ran to completion but failed;
+    # +Kobako::ServiceError+ on an unrescued Service capability failure.
+    def run(source)
+      raise SandboxError, "source must be a String, got #{source.class}" unless source.is_a?(String)
+
+      @services.seal!
+      reset_run_state!
+      preamble = @services.guest_preamble
+      @instance.setup_wasi_pipes(@stdout_limit, @stderr_limit, preamble, source.b)
+
+      invoke_guest_run
+      drain_wasi_output
+      outcome_bytes = read_outcome_bytes
+      OutcomeDecoder.decode(outcome_bytes)
+    end
+
+    private
+
+    # Per-run state reset ({SPEC.md B-03}[link:../../SPEC.md]). Capture
+    # buffers and the HandleTable counter are zeroed before the guest runs.
+    def reset_run_state!
+      @services.reset_handles!
+      @stdout_buffer.clear
+      @stderr_buffer.clear
+    end
+
+    # Drain the WASI stdout/stderr pipes populated during the most recent
+    # guest execution into the bounded OutputBuffers
+    # ({SPEC.md B-04}[link:../../SPEC.md]). Must be called after
+    # `invoke_guest_run` and before the next reset.
+    def drain_wasi_output
+      stdout_bytes = @instance.take_stdout
+      stderr_bytes = @instance.take_stderr
+      @stdout_buffer << stdout_bytes unless stdout_bytes.empty?
+      @stderr_buffer << stderr_bytes unless stderr_bytes.empty?
+    end
+
+    # Invoke `__kobako_run`. Wraps wasmtime / wire errors in TrapError.
+    # Source was already delivered via the stdin two-frame protocol in
+    # `setup_wasi_pipes` before this call
+    # ({SPEC.md ABI Signatures}[link:../../SPEC.md]).
+    def invoke_guest_run
+      @instance.run
+    rescue Kobako::Wasm::Error => e
+      raise TrapError, "guest __kobako_run trapped: #{e.message}"
+    end
+
+    # Pull the OUTCOME_BUFFER bytes out of guest memory. The +len=0+ case
+    # is forwarded to {OutcomeDecoder} as an empty String so a single
+    # boundary attributes every wire-violation outcome
+    # ({SPEC.md ABI Signatures}[link:../../SPEC.md]).
+    def read_outcome_bytes
+      ptr, len = Kobako::Wasm.unpack_outcome_ptr_len(@instance.take_outcome)
+      @instance.read_memory(ptr, len)
+    rescue Kobako::Wasm::Error => e
+      raise TrapError, "failed to read OUTCOME_BUFFER: #{e.message}"
+    end
+  end
+end

data/lib/kobako/version.rb

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

data/lib/kobako/wasm.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Kobako
+  # Host-side wasmtime wrapper, surfaced as Ruby classes by the native ext
+  # (see ext/kobako/src/wasm.rs). This module is the foundational binding
+  # layer for Sandbox (#14), the run path (#16) and RPC dispatch (#18).
+  #
+  # The classes themselves (Engine / Module / Store / Instance) and the
+  # error hierarchy (Error / ModuleNotBuiltError) are defined from Rust at
+  # ext load time; this file only adds the pure-Ruby helpers that have no
+  # reason to live in Rust.
+  module Wasm
+    # Absolute path to the gem-bundled `data/kobako.wasm` artifact. Computed
+    # from this file's location so it works for both `bundle exec` (running
+    # from the repo) and an installed gem (running from the gem dir).
+    #
+    # Returns a String regardless of whether the file currently exists —
+    # call sites that need the file to be present should pass this through
+    # `Kobako::Wasm::Module.from_file`, which raises `ModuleNotBuiltError`
+    # with a clear remediation message.
+    def self.default_path
+      File.expand_path("../../data/kobako.wasm", __dir__)
+    end
+
+    # Unpack the +(ptr << 32) | len+ u64 produced by the Rust ext's
+    # +__kobako_take_outcome+ export. Returns +[ptr, len]+ as 32-bit
+    # unsigned integers. Pure-Ruby helper kept near the ABI surface so
+    # Sandbox does not have to carry bit-level wire layout.
+    def self.unpack_outcome_ptr_len(packed)
+      ptr = (packed >> 32) & 0xffff_ffff
+      len = packed & 0xffff_ffff
+      [ptr, len]
+    end
+  end
+end

data/lib/kobako/wire/codec/decoder.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require "msgpack"
+
+require_relative "error"
+require_relative "../handle"
+require_relative "../exception"
+require_relative "factory"
+
+module Kobako
+  module Wire
+    module Codec
+      # Module-level entry point for the host side of the kobako wire
+      # (SPEC.md → Wire Codec → Type Mapping).
+      #
+      # Translates msgpack gem exceptions into the kobako error taxonomy
+      # ({Truncated}, {InvalidType}, {InvalidEncoding}, {UnsupportedType}) so
+      # callers can pattern-match on the SPEC's wire-violation categories
+      # without leaking the gem's internal exception classes.
+      #
+      # Public API is a single function — {.decode}. The decoder is
+      # stateless; the +MessagePack::Unpacker+ instance is built per call
+      # because callers always decode exactly one wire value at a time.
+      module Decoder
+        # The msgpack gem raises these for type/format violations; +ArgumentError+
+        # also comes from our ext-type validators (Handle id range, Exception
+        # type whitelist). All surface as {InvalidType}.
+        INVALID_TYPE_ERRORS = [
+          ::MessagePack::UnknownExtTypeError,
+          ::MessagePack::MalformedFormatError,
+          ::MessagePack::StackError,
+          ::ArgumentError
+        ].freeze
+        private_constant :INVALID_TYPE_ERRORS
+
+        # +UnpackError+ is the gem's umbrella class for short-read / incomplete-buffer
+        # faults; +EOFError+ covers underflow at the buffer edge. Both map to {Truncated}.
+        TRUNCATED_ERRORS = [::MessagePack::UnpackError, ::EOFError].freeze
+        private_constant :TRUNCATED_ERRORS
+
+        # Decode +bytes+ into one Ruby value and validate transitively
+        # against the SPEC type mapping. Raises {Truncated}, {InvalidType},
+        # or {InvalidEncoding} on wire violations.
+        def self.decode(bytes)
+          value = Factory.instance.load(bytes.b)
+          validate_utf8!(value)
+          value
+        rescue *INVALID_TYPE_ERRORS => e
+          raise InvalidType, e.message
+        rescue *TRUNCATED_ERRORS => 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
+        # 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
+        # str-typed leaf. {Exception} payloads are validated transitively:
+        # +Factory.unpack_exception+ feeds the inner ext-0x02 bytes back
+        # through this Decoder, so their +str+ fields are already covered
+        # by the time control returns here.
+        def self.validate_utf8!(value)
+          case value
+          when String then validate_string_utf8!(value)
+          when Array  then value.each { |v| validate_utf8!(v) }
+          when Hash   then value.each_pair { |k, v| validate_pair_utf8!(k, v) }
+          end
+        end
+        private_class_method :validate_utf8!
+
+        def self.validate_string_utf8!(value)
+          return unless value.encoding == Encoding::UTF_8
+          raise InvalidEncoding, "str payload is not valid UTF-8" unless value.valid_encoding?
+        end
+        private_class_method :validate_string_utf8!
+
+        def self.validate_pair_utf8!(key, value)
+          validate_utf8!(key)
+          validate_utf8!(value)
+        end
+        private_class_method :validate_pair_utf8!
+      end
+    end
+  end
+end

data/lib/kobako/wire/codec/encoder.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "msgpack"
+
+require_relative "error"
+require_relative "../handle"
+require_relative "../exception"
+require_relative "factory"
+
+module Kobako
+  module Wire
+    module Codec
+      # Module-level entry point for the host side of the kobako wire
+      # (SPEC.md → Wire Codec → Type Mapping).
+      #
+      # The codec backbone is the official +msgpack+ gem: integers, floats,
+      # strings, arrays, and maps go through the gem's narrowest-encoding
+      # logic; the three kobako-specific ext types (0x00 Symbol, 0x01
+      # Capability Handle, 0x02 Exception envelope) are registered on
+      # +Factory+ via {Kobako::Wire::Codec::Factory.instance}.
+      #
+      # Public API is a single function — {.encode}. The codec is stateless;
+      # there is no buffer accumulator and no streaming write API. Callers
+      # that need to concatenate multiple encodings build the bytes
+      # themselves (see {Envelope.encode_outcome} for the canonical example).
+      module Encoder
+        # Encode +value+ to wire bytes (binary-encoded String).
+        # Wire violations surface as +UnsupportedType+: SPEC's 12-entry type
+        # 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+).
+        def self.encode(value)
+          Factory.instance.dump(value)
+        rescue ::RangeError, ::NoMethodError => e
+          raise UnsupportedType, e.message
+        end
+      end
+    end
+  end
+end

data/lib/kobako/wire/codec/error.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Kobako
+  module Wire
+    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
+      # subclass of {Error} so callers can pattern-match on the specific
+      # fault while still rescuing all codec faults via this base class.
+      #
+      # Higher layers (e.g. the Sandbox dispatch loop) translate these into
+      # the public {Kobako::SandboxError} / {Kobako::TrapError} taxonomy.
+      class Error < StandardError; end
+
+      # Input ended before the type prefix or payload was fully consumed.
+      class Truncated < Error; end
+
+      # The type byte at the current position is not in the 12-entry kobako
+      # type mapping (e.g. an unknown ext code, or a reserved msgpack tag).
+      class InvalidType < Error; end
+
+      # A msgpack `str` payload was not valid UTF-8, or an ext 0x00 Symbol
+      # payload was not valid UTF-8 — both are wire violations per SPEC.
+      class InvalidEncoding < Error; end
+
+      # The encoder was handed a Ruby object whose type has no wire
+      # representation (e.g. Range, Time). Higher layers may catch this
+      # and re-route the value through Handle allocation, but at the
+      # codec level it is a hard error.
+      class UnsupportedType < Error; end
+    end
+  end
+end

data/lib/kobako/wire/codec/factory.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require "msgpack"
+
+require_relative "error"
+require_relative "../handle"
+require_relative "../exception"
+
+module Kobako
+  module Wire
+    module Codec
+      # Cached +MessagePack::Factory+ that owns the kobako wire ext-type
+      # registration (SPEC.md → Wire Codec → Ext Types).
+      #
+      # The factory is the single place in the host gem that touches msgpack
+      # API — both {Encoder} and {Decoder} delegate through it, so the three
+      # kobako ext codes (0x00 Symbol, 0x01 Capability Handle, 0x02 Exception
+      # envelope) are configured exactly once at module load.
+      module Factory
+        # MessagePack ext type code reserved for Symbol
+        # (SPEC.md → Wire Codec → Ext Types → ext 0x00). Module-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). Module-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). Module-private —
+        # mirrors +codec::EXT_ERRENV+ on the Rust side.
+        EXT_ERRENV = 0x02
+        private_constant :EXT_SYMBOL, :EXT_HANDLE, :EXT_ERRENV
+
+        # Returns the lazily-built process-wide +MessagePack::Factory+.
+        def self.instance
+          @instance ||= build
+        end
+
+        # Build a fresh factory. Exposed for tests that need an isolated
+        # instance; production code should call {.instance}.
+        def self.build
+          factory = MessagePack::Factory.new
+          register_symbol_type(factory)
+          register_handle_type(factory)
+          register_exception_type(factory)
+          factory
+        end
+
+        def self.register_symbol_type(factory)
+          factory.register_type(
+            EXT_SYMBOL, Symbol,
+            packer: lambda(&:name),
+            unpacker: ->(payload) { decode_symbol(payload) }
+          )
+        end
+        private_class_method :register_symbol_type
+
+        # Validate the ext-0x00 payload as UTF-8 and intern. Raises
+        # {InvalidEncoding} on invalid bytes — SPEC forbids the
+        # binary-encoding fallback that msgpack-gem's default unpacker
+        # would otherwise apply.
+        def self.decode_symbol(payload)
+          name = payload.b.force_encoding(Encoding::UTF_8)
+          raise InvalidEncoding, "ext 0x00 payload is not valid UTF-8" unless name.valid_encoding?
+
+          name.to_sym
+        end
+        private_class_method :decode_symbol
+
+        def self.register_handle_type(factory)
+          factory.register_type(
+            EXT_HANDLE, Handle,
+            packer: ->(handle) { [handle.id].pack("N") },
+            unpacker: ->(payload) { decode_handle(payload) }
+          )
+        end
+        private_class_method :register_handle_type
+
+        def self.register_exception_type(factory)
+          factory.register_type(
+            EXT_ERRENV, Exception,
+            packer: ->(exc) { pack_exception(exc) },
+            unpacker: ->(payload) { unpack_exception(payload) }
+          )
+        end
+        private_class_method :register_exception_type
+
+        # Peel off the fixext-4 frame, hand the bytes to +Handle.new+, and
+        # translate the +ArgumentError+ raised by Handle's invariants into
+        # a wire-layer +InvalidType+ via {Codec.translate_value_object_error}.
+        # The Value Object owns the id-range contract; this method only
+        # owns the frame shape.
+        def self.decode_handle(payload)
+          bytes = payload.b
+          raise InvalidType, "ext 0x01 payload must be 4 bytes, got #{bytes.bytesize}" unless bytes.bytesize == 4
+
+          Codec.translate_value_object_error { Handle.new(bytes.unpack1("N")) }
+        end
+        private_class_method :decode_handle
+
+        # 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 Exception) reach the
+        # registered ext-type packers via the cached {.instance}.
+        def self.pack_exception(exc)
+          Encoder.encode("type" => exc.type, "message" => exc.message, "details" => exc.details)
+        end
+        private_class_method :pack_exception
+
+        # Peel the embedded msgpack map and hand it to +Exception.new+;
+        # translate the value-object's +ArgumentError+ into +InvalidType+
+        # at the wire 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 cached +.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 and re-opens the Decoder's special
+        # case for Exception (removed in M5).
+        def self.unpack_exception(payload)
+          map = Decoder.decode(payload)
+          raise InvalidType, "ext 0x02 payload must be a map" unless map.is_a?(Hash)
+
+          Codec.translate_value_object_error do
+            Exception.new(type: map["type"], message: map["message"], details: map["details"])
+          end
+        end
+        private_class_method :unpack_exception
+      end
+    end
+  end
+end

data/lib/kobako/wire/codec.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative "codec/error"
+
+module Kobako
+  module Wire
+    # Host-side MessagePack codec for the kobako wire contract — the
+    # byte-level layer (SPEC.md → Wire Codec). The envelope layer
+    # (Kobako::Wire::Envelope) sits on top of this and pins the four
+    # logical message shapes (Request / Response / Result / Panic).
+    #
+    # Backed by the official +msgpack+ gem via {Factory}; {Encoder} and
+    # {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-wasm+ 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.
+    module Codec
+      # Wire-boundary translator: every wire Value Object (Handle /
+      # Exception / Request / Response / Panic / Outcome) raises
+      # +ArgumentError+ when an invariant is violated at construction.
+      # The wire boundary surfaces those violations to callers as
+      # +InvalidType+ so the public taxonomy stays +Codec::Error+ and
+      # never leaks +ArgumentError+ from the Ruby standard library.
+      #
+      # Wrap any block that constructs a wire Value Object from decoded
+      # bytes with this helper to keep the five decode sites (Request /
+      # Response / Panic / Handle ext / Exception ext) uniform. Do not
+      # use it for general-purpose validation outside the wire boundary
+      # — host-layer +ArgumentError+ values should propagate unchanged.
+      def self.translate_value_object_error
+        yield
+      rescue ::ArgumentError => e
+        raise InvalidType, e.message
+      end
+    end
+  end
+end
+
+require_relative "codec/factory"
+require_relative "codec/encoder"
+require_relative "codec/decoder"