kobako 0.5.0-x86_64-linux

data/lib/kobako/capture.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Kobako
+  # Host-side captured prefix of guest stdout / stderr produced during a
+  # 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.new(bytes:, truncated:)+ for the ext-provided
+  # binary bytes (the constructor handles the 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
+
+    # Build a Capture wrapping +bytes+ (the captured prefix as a String) and
+    # +truncated+ (whether the originating WASI pipe reported the cap was
+    # hit). Coerces +bytes+ to UTF-8 when they are valid UTF-8, otherwise
+    # falls back to ASCII-8BIT so invalid sequences remain inspectable
+    # without raising; +bytes+ is duplicated, never mutated. Freezes the
+    # instance so callers cannot mutate the pair.
+    def initialize(bytes:, truncated:)
+      copy = bytes.dup.force_encoding(Encoding::UTF_8)
+      copy.force_encoding(Encoding::ASCII_8BIT) unless copy.valid_encoding?
+      @bytes = copy
+      @truncated = truncated
+      freeze
+    end
+
+    # Returns +true+ iff the underlying capture channel exceeded its
+    # configured cap during the originating +Sandbox+ invocation
+    # ({docs/behavior.md B-04}[link:../../docs/behavior.md]).
+    def truncated? = @truncated
+
+    # 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/catalog/handles.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require_relative "../handle"
+
+module Kobako
+  module Catalog
+    # Host-side mapping from opaque integer Handle IDs to Ruby objects.
+    # The table is owned by +Kobako::Sandbox+
+    # ({docs/behavior.md B-19}[link:../../../docs/behavior.md]) and injected
+    # into the per-Sandbox +Kobako::Catalog::Namespaces+ so guest→host dispatch
+    # resolves Handle targets and arguments against the same table that
+    # host→guest wire encoding allocates into
+    # ({docs/behavior.md B-14, B-34}[link:../../../docs/behavior.md]).
+    #
+    # Lifecycle invariants ({docs/behavior.md}[link:../../../docs/behavior.md]):
+    #
+    #   - {docs/behavior.md B-15}[link:../../../docs/behavior.md] — Handle IDs
+    #     are allocated by a monotonically increasing counter scoped to a
+    #     single invocation. The first ID issued in an invocation is 1; ID 0
+    #     is reserved as the invalid sentinel and is never returned by
+    #     +#alloc+.
+    #
+    #   - {docs/behavior.md B-19}[link:../../../docs/behavior.md] — At every
+    #     invocation boundary (via +#reset!+), every Handle issued under the
+    #     old state becomes invalid. Reset applies uniformly regardless of
+    #     allocation source (B-14 Service return or B-34 host-injected
+    #     argument).
+    #
+    #   - {docs/behavior.md B-21}[link:../../../docs/behavior.md] — The cap is
+    #     +0x7fff_ffff+ (2³¹ − 1). Allocation beyond the cap raises
+    #     immediately — no silent truncation, no wrap, no ID reuse.
+    class Handles
+      # Build a fresh, empty table. +next_id+ is an internal seam that
+      # sets the starting value of the monotonic counter (defaults to 1 per
+      # B-15); tests pass a value near +Kobako::Handle::MAX_ID+ to exercise
+      # the cap-exhaustion path without 2³¹ allocations.
+      def initialize(next_id: 1)
+        @entries = {} # : Hash[Integer, untyped]
+        @next_id = next_id
+      end
+
+      # Bind +object+ in the table and return a +Kobako::Handle+ token
+      # 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
+      # cap. The cap is anchored on +Kobako::Handle+ — the wire codec
+      # and the allocator share the same invariant
+      # ({docs/behavior.md B-21}[link:../../../docs/behavior.md]).
+      #
+      # Returning a Handle (rather than a bare Integer id) keeps the
+      # allocator's output a domain entity; +Kobako::Handle.restore+
+      # is reserved for the codec's wire-decode path, where the id is
+      # the only thing the bytes carry.
+      def alloc(object)
+        id = @next_id
+        cap = Kobako::Handle::MAX_ID
+        if id > cap
+          raise HandlerExhaustedError,
+                "Out of handle allocations: too many host objects were referenced " \
+                "in a single invocation (limit #{cap})"
+        end
+
+        @entries[id] = object
+        @next_id = id + 1
+        Kobako::Handle.restore(id)
+      end
+
+      # Resolve a Handle ID to its bound object. +id+ is a Handle ID previously
+      # returned by +#alloc+. Returns the bound object. Raises
+      # +Kobako::SandboxError+ if +id+ is not currently bound.
+      def fetch(id)
+        require_bound!(id)
+        @entries[id]
+      end
+
+      # Clear all entries AND reset the counter to 1. Called at the per-invocation
+      # boundary by +Kobako::Sandbox+ — see
+      # {docs/behavior.md B-19}[link:../../../docs/behavior.md]. Returns +self+.
+      def reset!
+        @entries.clear
+        @next_id = 1
+        self
+      end
+
+      # Number of currently-bound entries. Used by tests of the Dispatcher
+      # and Codec::Utils#deep_wrap to observe whether each path allocates
+      # exactly the Handle entries it should — the +Handles+ table itself never
+      # consults its own size, but the surrounding code's allocation
+      # contract is part of the observable boundary.
+      def size
+        @entries.size
+      end
+
+      private
+
+      # Single source of truth for the "unknown Handle id" raise used by
+      # {#fetch}. Returns +nil+ on success; raises +Kobako::SandboxError+
+      # when +id+ is not currently bound.
+      def require_bound!(id)
+        return if @entries.key?(id)
+
+        raise SandboxError, "unknown Handle id: #{id.inspect}"
+      end
+    end
+  end
+end

data/lib/kobako/catalog/namespaces.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require_relative "handles"
+require_relative "../codec"
+require_relative "../errors"
+require_relative "../transport/request"
+require_relative "../namespace"
+
+module Kobako
+  module Catalog
+    # Kobako::Catalog::Namespaces — per-Sandbox registry of
+    # +Kobako::Namespace+ entities. Holds the Namespace / Member bindings
+    # and the preamble emitted on Frame 1
+    # ({docs/behavior.md B-07..B-11}[link:../../../docs/behavior.md]).
+    #
+    # Public API:
+    #
+    #   namespaces = Kobako::Catalog::Namespaces.new
+    #   namespace = namespaces.define(:MyService)  # => Kobako::Namespace
+    #   namespace.bind(:KV, kv_object)             # => namespace (chainable)
+    #   namespaces.encode                          # => msgpack bytes for Frame 1
+    #   namespaces.lookup("MyService::KV")         # => kv_object
+    #
+    # Namespaces live at +Kobako::Namespace+. Per-dispatch routing is
+    # +Kobako::Transport::Dispatcher+'s responsibility — the Dispatcher
+    # receives this registry and the +Catalog::Handles+ as arguments from
+    # the +Runtime#on_dispatch+ Proc that +Kobako::Sandbox#initialize+
+    # installs ({docs/behavior.md B-12}[link:../../../docs/behavior.md]).
+    # The registry holds an injected +Catalog::Handles+ reference so
+    # dispatch target resolution and host→guest auto-wrap share the same
+    # Sandbox-owned allocator (docs/behavior.md B-19).
+    class Namespaces
+      # Build a fresh registry. +handler+ is an internal seam that injects
+      # a pre-configured +Catalog::Handles+; tests pass one whose +next_id+
+      # is pinned near +MAX_ID+ to exercise the B-21 cap-exhaustion path
+      # without 2³¹ allocations. Production callers leave it at the default.
+      def initialize(handler: Catalog::Handles.new)
+        @namespaces = {} # : Hash[String, Kobako::Namespace]
+        @handler = handler
+        @sealed = false
+      end
+
+      # Declare or retrieve the Namespace named +name+ (idempotent — docs/behavior.md B-10).
+      # +name+ is a constant-form name as a +Symbol+ or +String+ (must satisfy
+      # +Namespace::NAME_PATTERN+). Returns the +Kobako::Namespace+ for that
+      # name, creating it if it does not exist. Raises +ArgumentError+ when
+      # +name+ is malformed, or when called after the owning Sandbox has been
+      # sealed by its first invocation
+      # ({docs/behavior.md B-07}[link:../../../docs/behavior.md]).
+      def define(name)
+        raise ArgumentError, "cannot define after first Sandbox invocation" if @sealed
+
+        name_str = name.to_s
+        unless Namespace::NAME_PATTERN.match?(name_str)
+          raise ArgumentError,
+                "Namespace name must match #{Namespace::NAME_PATTERN.inspect} (got #{name.inspect})"
+        end
+
+        @namespaces[name_str] ||= Namespace.new(name_str)
+      end
+
+      # Resolve a +target+ path of the form +"Namespace::Member"+ to the
+      # bound Host object. +target+ is a two-level path using the +::+
+      # separator. Returns the bound Host object. Raises +KeyError+ when the
+      # namespace or the member is not bound.
+      def lookup(target)
+        namespace_name, member_name = target.to_s.split("::", 2)
+        namespace = @namespaces[namespace_name]
+        raise KeyError, "no namespace named #{namespace_name.inspect}" if namespace.nil?
+        raise KeyError, "no member in target #{target.inspect}" unless member_name
+
+        namespace.fetch(member_name)
+      end
+
+      # Encode the preamble as msgpack bytes for stdin Frame 1 delivery
+      # ({docs/behavior.md B-02}[link:../../../docs/behavior.md]). Routes through
+      # {Kobako::Codec::Encoder} like every other host-side wire encode so
+      # there is a single codec path; the preamble carries only Strings and
+      # Arrays, so none of the kobako ext types actually fire. Structure:
+      # +[["Namespace", ["MemberA", "MemberB"]], ...]+. Returns a binary
+      # +String+ of msgpack bytes.
+      def encode
+        Codec::Encoder.encode(@namespaces.values.map(&:to_preamble))
+      end
+
+      # Mark the registry as sealed. Called by +Sandbox+ on the first
+      # invocation. After sealing, #define raises ArgumentError. Idempotent.
+      def seal!
+        @sealed = true
+        self
+      end
+
+      # Returns +true+ when {#seal!} has been called, +false+ otherwise.
+      def sealed?
+        @sealed
+      end
+    end
+  end
+end

data/lib/kobako/catalog/snippets.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+require_relative "../codec"
+require_relative "../snippet"
+
+module Kobako
+  module Catalog
+    # Kobako::Catalog::Snippets — per-Sandbox insertion-ordered registry
+    # of preloaded snippets
+    # ({docs/behavior.md B-32 / B-33}[link:../../../docs/behavior.md]).
+    #
+    # Entries replay against the fresh +mrb_state+ before per-invocation
+    # source / entrypoint resolution. Each +Snippet::Source+ entry's +name+
+    # is its canonical identity — the filename baked into the loaded IREP's
+    # +debug_info+ that surfaces in every backtrace frame originating from
+    # the snippet as +(snippet:Name):line+. Duplicate names within the
+    # +code:+ form would produce ambiguous attribution and are rejected at
+    # registration time
+    # ({docs/behavior.md E-33}[link:../../../docs/behavior.md]).
+    # +Snippet::Binary+ entries carry no host-side name — their canonical
+    # name lives in the bytecode's +debug_info+ and is read by the guest at
+    # load time; the host does not extract it.
+    #
+    # Sealing (B-33) is governed by the owning Sandbox — the registry itself
+    # is append-only and exposes no mutation API beyond +#register+; the
+    # Sandbox guards +#register+ behind the seal check before delegating.
+    class Snippets
+      # Ruby constant-name pattern enforced on snippet names
+      # ({docs/behavior.md E-34}[link:../../../docs/behavior.md]).
+      NAME_PATTERN = /\A[A-Z]\w*\z/
+
+      def initialize
+        @entries = [] # : Array[Kobako::Snippet::Source | Kobako::Snippet::Binary]
+      end
+
+      # Serialize the registered snippets to wire bytes. Each entry
+      # contributes a msgpack map shape; the collection rides as a single
+      # msgpack array. An empty registry serializes to an empty array, never
+      # absent. The wire codec is an implementation detail — callers
+      # receive a binary +String+ that the +Kobako::Runtime+ layer ships
+      # through the invocation channel. The entry value objects stay pure
+      # carriers — this collection-tier method reads their attributes
+      # externally via +entry_payload+ rather than asking each entry to
+      # self-encode.
+      def encode
+        Codec::Encoder.encode(@entries.map { |entry| entry_payload(entry) })
+      end
+
+      # Register one preloaded snippet in either of two forms
+      # ({docs/behavior.md B-32}[link:../../../docs/behavior.md]).
+      #
+      #   * Source form +register(code: src, name: Name)+ — +src+ is the
+      #     mruby source as a String; the bytes are re-encoded as UTF-8
+      #     and detached from the caller's reference. +name+ is a Symbol
+      #     or String matching +NAME_PATTERN+. Returns the Symbol form
+      #     of +name+.
+      #   * Binary form +register(binary: bytes)+ — +bytes+ is
+      #     precompiled RITE bytecode as a String, duplicated and forced
+      #     to ASCII-8BIT so msgpack-ruby ships it as +bin+. Returns
+      #     +nil+ — bytecode entries are anonymous on the host side; any
+      #     structural validation
+      #     ({docs/behavior.md E-37 / E-38}[link:../../../docs/behavior.md])
+      #     is deferred to the guest at first replay.
+      #
+      # The two forms are mutually exclusive: shape validation lives
+      # here so callers (chiefly +Kobako::Sandbox#preload+) collapse to
+      # a single delegation. Raises +ArgumentError+ on mixed forms,
+      # missing keywords, wrong types, malformed +name+ (E-34), or
+      # duplicate +code:+ +name+ (E-33).
+      def register(code: nil, name: nil, binary: nil)
+        if binary
+          raise ArgumentError, "cannot combine binary: with code: / name:" if code || name
+
+          register_binary!(binary)
+        else
+          register_source!(code, name)
+        end
+      end
+
+      private
+
+      # Source-form register path. Delegates argument-shape checks to
+      # +ensure_source_args!+ (which returns the narrowed +[code, name]+
+      # pair), normalises +name+ to a Symbol, rejects duplicates (E-33),
+      # and appends the Source entry.
+      def register_source!(code, name)
+        code, name = ensure_source_args!(code, name)
+        name_sym = normalize_name(name)
+        if @entries.any? { |e| e.is_a?(Snippet::Source) && e.name == name_sym }
+          raise ArgumentError, "snippet #{name_sym.inspect} already preloaded"
+        end
+
+        @entries << Snippet::Source.new(name: name_sym, body: code.dup.force_encoding(Encoding::UTF_8))
+        name_sym
+      end
+
+      # Shape-only validation for the +code:+ + +name:+ pair. Returns
+      # the pair with +nil+ narrowed away so callers can treat both as
+      # present. The +code:+ type check runs before the +name:+
+      # presence check so callers passing +code: nil+ explicitly see
+      # the type error rather than the "missing keyword" error.
+      def ensure_source_args!(code, name)
+        raise ArgumentError, "missing keyword: code: + name:, or binary:" if code.nil? && name.nil?
+        raise ArgumentError, "code must be a String, got #{code.class}" unless code.is_a?(String)
+        raise ArgumentError, "missing keyword: name:" if name.nil?
+
+        [code, name]
+      end
+
+      # Binary-form register path. Validates the +binary:+ payload type
+      # and appends the Binary entry. The bytes are duplicated and forced
+      # to ASCII-8BIT so msgpack-ruby picks the +bin+ family on the wire.
+      def register_binary!(bytes)
+        raise ArgumentError, "binary must be a String, got #{bytes.class}" unless bytes.is_a?(String)
+
+        @entries << Snippet::Binary.new(body: bytes.dup.force_encoding(Encoding::ASCII_8BIT))
+        nil
+      end
+
+      # Build the msgpack-ready Hash for one entry. Source entries
+      # contribute their host-side +name+; Binary entries omit it
+      # because the canonical name lives in the bytecode's embedded
+      # +debug_info+ and is read by the guest at load time
+      # ({docs/wire-codec.md Invocation channels}[link:../../../docs/wire-codec.md]).
+      def entry_payload(entry)
+        case entry
+        when Snippet::Source
+          { "name" => entry.name.to_s, "kind" => Snippet::Source::KIND, "body" => entry.body }
+        when Snippet::Binary
+          { "kind" => Snippet::Binary::KIND, "body" => entry.body }
+        end
+      end
+
+      def normalize_name(name)
+        unless name.is_a?(Symbol) || name.is_a?(String)
+          raise ArgumentError, "snippet name must be a Symbol or String, got #{name.class}"
+        end
+
+        name_str = name.to_s
+        unless NAME_PATTERN.match?(name_str)
+          raise ArgumentError,
+                "snippet name must match #{NAME_PATTERN.inspect} (got #{name.inspect})"
+        end
+
+        name_str.to_sym
+      end
+    end
+  end
+end

data/lib/kobako/catalog.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative "catalog/handles"
+require_relative "catalog/namespaces"
+require_relative "catalog/snippets"
+
+module Kobako
+  # Kobako::Catalog — Sandbox-level configuration and per-invocation
+  # allocation tables. Houses the three host-side registries the Sandbox
+  # owns: +Catalog::Namespaces+ (Namespace / Member registry),
+  # +Catalog::Snippets+ (preloaded source / bytecode entries), and
+  # +Catalog::Handles+ (per-invocation Handle ID allocator).
+  #
+  # See {SPEC.md Refinement → Internal Concepts}[link:../../SPEC.md] for
+  # how Catalog fits alongside Transport and Runtime.
+  module Catalog
+  end
+end

data/lib/kobako/codec/decoder.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require "msgpack"
+
+require_relative "error"
+require_relative "factory"
+require_relative "utils"
+
+module Kobako
+  module Codec
+    # Module-level entry point for the host side of the kobako wire
+    # ({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
+    # 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
+      # Decode +bytes+ into one Ruby value and validate transitively
+      # against the SPEC type mapping. Raises {Truncated}, {InvalidType},
+      # or {InvalidEncoding} on wire violations.
+      #
+      # When a block is given, the decoded value is yielded and the block's
+      # result is returned — wire Value Objects use this to build themselves
+      # from the decoded payload. The block runs inside this method's
+      # rescue, so a Value Object's +ArgumentError+ invariant failure
+      # surfaces as {InvalidType} without a separate {Utils.with_boundary}
+      # wrapper at the call site.
+      def self.decode(bytes)
+        value = Factory.load(bytes.b)
+        validate_utf8!(value)
+        block_given? ? yield(value) : value
+      # msgpack gem raises the format/type errors below; +ArgumentError+
+      # comes from our ext-type validators (Handle id range, Exception type
+      # whitelist) and from a yielded block's Value Object invariants — both
+      # are wire violations, so both map to {InvalidType}.
+      rescue ::MessagePack::UnknownExtTypeError, ::MessagePack::MalformedFormatError,
+             ::MessagePack::StackError, ::ArgumentError => e
+        raise InvalidType, e.message
+      # +UnpackError+ is the gem's umbrella class for short-read /
+      # incomplete-buffer faults; +EOFError+ covers underflow at the
+      # buffer edge.
+      rescue ::MessagePack::UnpackError, ::EOFError => e
+        raise Truncated, e.message
+      end
+
+      # 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
+      # str-typed leaf via {Utils.assert_utf8!}. {Kobako::Fault}
+      # payloads are validated transitively: +Factory.unpack_fault+
+      # feeds the inner ext-0x02 bytes back through this Decoder, so their
+      # +str+ fields are already covered by the time control returns here.
+      class << self
+        private
+
+        def validate_utf8!(value)
+          case value
+          when String then Utils.assert_utf8!(value, "str payload") if value.encoding == Encoding::UTF_8
+          when Array  then value.each { |v| validate_utf8!(v) }
+          when Hash   then value.each { |pair| validate_utf8!(pair) }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/kobako/codec/encoder.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "msgpack"
+
+require_relative "error"
+require_relative "factory"
+
+module Kobako
+  module Codec
+    # Module-level entry point for the host side of the kobako wire
+    # ({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
+    # logic; the three kobako-specific ext types (0x00 Symbol, 0x01
+    # Capability Handle, 0x02 Exception envelope) are registered on
+    # the cached {Kobako::Codec::Factory} singleton.
+    #
+    # 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.
+    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.dump(value)
+      rescue ::RangeError, ::NoMethodError => e
+        raise UnsupportedType, e.message
+      end
+    end
+  end
+end

data/lib/kobako/codec/error.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+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
+    # {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.
+    #
+    # 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