kobako 0.26.0-aarch64-linux → 0.28.0-aarch64-linux

data/lib/kobako/catalog/services.rb

@@ -1,50 +1,18 @@
 # frozen_string_literal: true
 
+require_relative "../constant_name"
 require_relative "../errors"
 require_relative "../transport/exposure"
 
 module Kobako
   module Catalog
-    # Kobako::Catalog::Services — per-Sandbox registry of Service
-    # bindings keyed by their constant-path name. Holds the flat
-    # path→Exposure table and the declared path set every invocation
-    # announces on Frame 1.
-    #
-    # Public API:
-    #
-    #   services = Kobako::Catalog::Services.new
-    #   services.bind("MyService::KV", kv_object)  # => services (chainable)
-    #   services.paths                             # => ["MyService::KV"]
-    #   services.lookup("MyService::KV").object    # => kv_object
-    #
-    # Per-dispatch routing is +Kobako::Transport::Dispatcher+'s
-    # responsibility — the Dispatcher resolves a path against the invocation's
-    # +Kobako::Context+ (which layers per-invocation providers and +ctx.bind+
-    # overrides over these base bindings) and the +Catalog::Handles+, both
-    # passed in the per-invocation dispatch Proc the Context hands to
-    # +Runtime#eval+ / +#run+.
-    class Services
-      # Ruby constant-name pattern each +::+-separated bind-path segment
-      # must match.
-      NAME_PATTERN = /\A[A-Z]\w*\z/
-
-      # Build a fresh registry.
+    class Services # :nodoc:
       def initialize
         @bindings = {} # : Hash[String, Kobako::Transport::Exposure]
-        @sealed = false
       end
 
-      # Bind +object+ as the Service reachable at +path+ — a +Symbol+ or
-      # +String+ of one or more +::+-separated constant-form segments
-      # (+"MyService::KV"+ or a top-level +"File"+). Returns +self+ for
-      # chaining. Raises +ArgumentError+ when a segment is malformed, when
-      # +path+ collides with an existing binding (a name is a bound Service
-      # or a grouping prefix, never both), or when the owning Sandbox has
-      # been sealed by its first invocation. The binding records +object+'s
-      # Exposure as it stands now.
+      # The binding records +object+'s Exposure as it stands now.
       def bind(path, object)
-        raise ArgumentError, "cannot bind after first Sandbox invocation" if @sealed
-
         path_str = validate_path!(path)
         raise ArgumentError, "Service path #{path_str} conflicts with an existing binding" if collision?(path_str)
 
@@ -52,14 +20,10 @@ module Kobako
         self
       end
 
-      # Returns +true+ iff a Service is bound at +path+ — the declared (Frame 1)
-      # key set a per-invocation +ctx.bind+ override may target.
       def bound?(path)
         @bindings.key?(path.to_s)
       end
 
-      # Resolve a +target+ constant path to the bound Service's Exposure.
-      # Raises +KeyError+ when no Service is bound at +target+.
       def lookup(target)
         target_str = target.to_s
         raise KeyError, "no service bound at #{target_str.inspect}" unless @bindings.key?(target_str)
@@ -67,42 +31,24 @@ module Kobako
         @bindings[target_str]
       end
 
-      # The bound constant paths in bind order — +["MyService::KV",
-      # "File"]+ — which +Runtime#eval+ / +#run+ frame into the Frame 1
-      # preamble. The registry holds the bindings; the wire layout is the
-      # native side's.
+      # The registry holds the bindings; the wire layout is the native
+      # side's.
       def paths
         @bindings.keys
       end
 
-      # Mark the registry as sealed so registration can never alter the
-      # declared path set afterwards. Called by +Sandbox+ on the first
-      # invocation; afterwards #bind raises ArgumentError. Idempotent;
-      # returns +self+.
-      def seal!
-        @sealed = true
-        self
-      end
-
-      # Returns +true+ when #seal! has been called, +false+ otherwise.
-      def sealed?
-        @sealed
-      end
-
       private
 
       def validate_path!(path)
         path_str = path.to_s
         segments = path_str.split("::", -1)
-        return path_str if !segments.empty? && segments.all? { |seg| NAME_PATTERN.match?(seg) }
+        return path_str if !segments.empty? && segments.all? { |seg| CONSTANT_NAME.match?(seg) }
 
         raise ArgumentError,
               "bind path must be constant-form segments joined by '::' (got #{path.inspect})"
       end
 
-      # A path collides when it equals, is a prefix of, or extends an
-      # existing binding on the +::+ segment boundary — the guardrail that
-      # keeps a name from being both a bound Service and a grouping prefix.
+      # Keeps a name from being both a bound Service and a grouping prefix.
       def collision?(path)
         @bindings.each_key.any? do |existing|
           existing == path ||

data/lib/kobako/catalog/snippets.rb

@@ -1,62 +1,41 @@
 # frozen_string_literal: true
 
+require_relative "../constant_name"
 require_relative "../snippet"
 
 module Kobako
   module Catalog
-    # Kobako::Catalog::Snippets — per-Sandbox insertion-ordered registry
-    # of preloaded snippets.
-    #
-    # 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.
-    # +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 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.
-      NAME_PATTERN = /\A[A-Z]\w*\z/
-
+    class Snippets # :nodoc:
       def initialize
         @entries = [] # : Array[Kobako::Snippet::Source | Kobako::Snippet::Binary]
+        @compiled = {} # : Hash[Kobako::Snippet::Source, String]
+        @compile_tried = false
       end
 
-      # The registered snippets in insertion order, each projected as the
-      # +[kind, name, body]+ triple +Runtime#eval+ / +#run+ frame into
-      # Frame 3 — +kind+ names the form as a Symbol, +name+ is +nil+ for
-      # the bytecode form. The entry value objects stay pure carriers, so
-      # this collection-tier method reads their attributes externally
-      # rather than asking each entry to project itself.
+      # Projected here so the entry value objects stay pure carriers.
       def entries
         @entries.map { |entry| entry_tuple(entry) }
       end
 
-      # Register one preloaded snippet in either of two forms.
-      #
-      #   * 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 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+, or
-      # duplicate +code:+ +name+.
+      # Has the block compile the source snippets, once, so every invocation
+      # after replays their bytecode instead of compiling them again. The
+      # block takes the #entries and answers one bytecode per source, or
+      # +nil+; when nothing comes back the source keeps replaying, and the
+      # attempt is not repeated.
+      def compile
+        return if @compile_tried
+
+        @compile_tried = true
+        sources = @entries.grep(Snippet::Source)
+        return if sources.empty?
+
+        bytecodes = yield(entries) or return
+        @compiled = sources.zip(bytecodes).to_h.compact
+        nil
+      end
+
+      # Bytecode stays unchecked on the host; the guest validates it at
+      # first replay.
       def register(code: nil, name: nil, binary: nil)
         if binary
           raise ArgumentError, "cannot combine binary: with code: / name:" if code || name
@@ -69,26 +48,25 @@ module Kobako
 
       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,
-      # and appends the Source entry.
+      # The native side frames a source body only as UTF-8 text, so source
+      # read as bytes is re-tagged, and bytes that are not UTF-8 are refused
+      # here rather than failing every invocation.
       def register_source!(code, name)
         code, name = ensure_source_args!(code, name)
+        body = code.dup.force_encoding(Encoding::UTF_8)
+        raise ArgumentError, "code must be UTF-8 text" unless body.valid_encoding?
+
         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
+        @entries << Snippet::Source.new(name: name_sym, body: body)
+        nil
       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.
+      # The +code:+ type check runs first so an explicit +code: nil+ reads
+      # as a type error rather than a missing keyword.
       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)
@@ -97,9 +75,8 @@ module Kobako
         [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.
+      # Kept as bytes whatever encoding the caller tagged them with, since
+      # the guest reads them as bytecode rather than text.
       def register_binary!(bytes)
         raise ArgumentError, "binary must be a String, got #{bytes.class}" unless bytes.is_a?(String)
 
@@ -107,14 +84,13 @@ module Kobako
         nil
       end
 
-      # Project one entry as its +[kind, name, body]+ triple. Source
-      # entries contribute their host-side +name+; Binary entries carry
-      # +nil+ because the canonical name lives in the bytecode's embedded
-      # +debug_info+ and is read by the guest at load time.
+      # A bytecode entry carries no name: its canonical name lives in the
+      # bytecode's +debug_info+ and is read by the guest at load time.
       def entry_tuple(entry)
         case entry
         when Snippet::Source
-          [Snippet::Source::KIND, entry.name.to_s, entry.body]
+          compiled = @compiled[entry]
+          compiled ? [Snippet::Binary::KIND, nil, compiled] : [Snippet::Source::KIND, entry.name.to_s, entry.body]
         else
           [Snippet::Binary::KIND, nil, entry.body]
         end
@@ -126,9 +102,9 @@ module Kobako
         end
 
         name_str = name.to_s
-        unless NAME_PATTERN.match?(name_str)
+        unless CONSTANT_NAME.match?(name_str)
           raise ArgumentError,
-                "snippet name must match #{NAME_PATTERN.inspect} (got #{name.inspect})"
+                "snippet name must match #{CONSTANT_NAME.inspect} (got #{name.inspect})"
         end
 
         name_str.to_sym

data/lib/kobako/catalog.rb

@@ -3,18 +3,10 @@
 require_relative "catalog/handles"
 require_relative "catalog/services"
 require_relative "catalog/snippets"
+require_relative "catalog/flags"
 require_relative "catalog/extensions"
 
 module Kobako
-  # Kobako::Catalog — Sandbox-level configuration and per-invocation
-  # allocation tables. Houses the host-side registries the Sandbox owns:
-  # +Catalog::Services+ (path→Service binding registry),
-  # +Catalog::Snippets+ (preloaded source / bytecode entries),
-  # +Catalog::Extensions+ (installed Extensions, composed onto Services /
-  # Snippets), 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
+  module Catalog # :nodoc:
   end
 end

data/lib/kobako/codec/decoder.rb

@@ -8,36 +8,17 @@ require_relative "utils"
 
 module Kobako
   module Codec
-    # Module-level entry point for the host side of the kobako wire
-    # ({docs/wire/payload-msgpack.md}[link:../../../docs/wire/payload-msgpack.md] § Type Mapping).
-    #
-    # Translates msgpack gem exceptions into the kobako error taxonomy
-    # (TruncatedInputError, InvalidTypeError, InvalidEncodingError, UnsupportedTypeError) 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 TruncatedInputError, InvalidTypeError,
-      # or InvalidEncodingError 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 InvalidTypeError without a separate Utils.with_boundary
-      # wrapper at the call site.
+    module Decoder # :nodoc:
+      # The block runs inside this method's rescue, so a Value Object built
+      # from the decoded payload reports a broken invariant as
+      # InvalidTypeError without its own Utils.with_boundary.
       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 InvalidTypeError.
+      # covers a yielded block's Value Object invariants — a wire violation
+      # too, so it maps to InvalidTypeError.
       rescue ::MessagePack::UnknownExtTypeError, ::MessagePack::MalformedFormatError,
              ::MessagePack::StackError, ::ArgumentError => e
         raise InvalidTypeError, e.message
@@ -48,9 +29,9 @@ module Kobako
         raise TruncatedInputError, e.message
       end
 
-      # SPEC pins +str+ family payloads to UTF-8
-      # ({docs/wire/payload-msgpack.md}[link:../../../docs/wire/payload-msgpack.md] § str/bin
-      # Encoding Rules). The msgpack gem returns UTF-8-tagged Strings for
+      # +str+ family payloads must be UTF-8
+      # (docs/wire/payload-msgpack.md § Text and Bytes). 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!.

data/lib/kobako/codec/encoder.rb

@@ -7,28 +7,9 @@ require_relative "ext_types"
 
 module Kobako
   module Codec
-    # Module-level entry point for the host side of the kobako wire
-    # ({docs/wire/payload-msgpack.md}[link:../../../docs/wire/payload-msgpack.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 two kobako-specific ext types (0x00 Symbol, 0x01
-    # Capability Handle) are registered by ExtTypes on the process-wide
-    # factory.
-    #
-    # 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).
-      # SPEC's 11-entry type mapping is a closed set: a value outside it is
-      # rejected as +UnsupportedTypeError+ by the factory's +BasicObject+ guard
-      # (ExtTypes#register_unrepresentable), which raises before the msgpack
-      # gem can route the value through +to_msgpack+ — so a permissive
-      # +method_missing+ object cannot answer that probe and mis-encode. The
-      # rescue below maps the two violations the guard does not reach onto the
-      # same error: an integer outside i64..u64 (+RangeError+) and any
+    module Encoder # :nodoc:
+      # The rescue maps the two violations the factory's +BasicObject+ guard
+      # does not reach: an integer outside i64..u64 (+RangeError+) and any
       # packer-internal +NoMethodError+.
       #
       # The caller bounds +value+'s nesting first (Nesting): the packer takes

data/lib/kobako/codec/error.rb

@@ -2,34 +2,13 @@
 
 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/payload-msgpack.md}[link:../../../docs/wire/payload-msgpack.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
+    class Error < StandardError; end # :nodoc:
+    class TruncatedInputError < Error; end # :nodoc:
 
-    # Input ended before the type prefix or payload was fully consumed.
-    class TruncatedInputError < Error; end
+    # Also raised on encode for a value nested past what the packer can walk.
+    class InvalidTypeError < Error; end # :nodoc:
 
-    # The type byte at the current position is not in the 11-entry kobako
-    # type mapping (e.g. an unknown ext code, or a reserved msgpack tag) —
-    # or, on encode, a value nesting past what the packer can walk.
-    class InvalidTypeError < 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 InvalidEncodingError < 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 UnsupportedTypeError < Error; end
+    class InvalidEncodingError < Error; end # :nodoc:
+    class UnsupportedTypeError < Error; end # :nodoc:
   end
 end

data/lib/kobako/codec/ext_types.rb

@@ -8,21 +8,16 @@ require_relative "state"
 require_relative "../handle"
 
 module Kobako
-  module Codec
-    # The kobako wire ext-type conversions
-    # ({docs/wire/payload-msgpack.md}[link:../../../docs/wire/payload-msgpack.md] § Ext Types)
-    # as pure functions: per-operation decode state is threaded in as an
-    # argument, so the module itself holds nothing. #build_factory assembles
-    # the one +MessagePack::Factory+ these conversions are registered on.
-    module ExtTypes
+  module Codec # :nodoc:
+    module ExtTypes # :nodoc:
       # MessagePack ext type code reserved for Symbol
-      # ({docs/wire/payload-msgpack.md}[link:../../../docs/wire/payload-msgpack.md] § Ext Types
-      # → ext 0x00). Module-private — mirrors +codec::EXT_SYMBOL+ on the
+      # (docs/wire/payload-msgpack.md § ext 0x00 — Symbol). Module-private —
+      # mirrors +codec::EXT_SYMBOL+ on the
       # Rust side.
       EXT_SYMBOL = 0x00
       # MessagePack ext type code reserved for Capability Handle
-      # ({docs/wire/payload-msgpack.md}[link:../../../docs/wire/payload-msgpack.md] § Ext Types
-      # → ext 0x01). Module-private — mirrors +codec::EXT_HANDLE+ on the
+      # (docs/wire/payload-msgpack.md § ext 0x01 — Handle). Module-private —
+      # mirrors +codec::EXT_HANDLE+ on the
       # Rust side.
       EXT_HANDLE = 0x01
       private_constant :EXT_SYMBOL, :EXT_HANDLE
@@ -31,19 +26,13 @@ module Kobako
       # never emitted (the guard's packer always raises) and never decoded
       # (no unpacker is registered, so the id stays an UnknownExtTypeError on
       # the wire), so it is not a wire ext type: deliberately not named
-      # +EXT_*+ like the two real ext codes, since it has no Rust-side mirror
-      # and must stay outside the wire-symmetry inventory.
+      # +EXT_*+ like the two real ext codes, since it has no Rust-side mirror.
       UNREPRESENTABLE_GUARD_ID = 0x7F
       private_constant :UNREPRESENTABLE_GUARD_ID
 
-      module_function
-
-      # Assemble a +MessagePack::Factory+ with the two kobako ext types plus
-      # the unrepresentable-value guard registered, frozen because
-      # registration is its only mutation and happens exactly once. The
-      # stateful conversions resolve their per-operation state at call time,
-      # so one registered factory serves every thread.
-      def build_factory
+      # The stateful conversions resolve their per-operation state at call
+      # time, so one frozen factory serves every thread.
+      def self.build_factory
         factory = MessagePack::Factory.new
         register_symbol(factory)
         register_handle(factory)
@@ -51,89 +40,78 @@ module Kobako
         factory.freeze
       end
 
-      # Symbol-to-name packer for the ext-0x00 registration.
-      def pack_symbol(symbol)
-        symbol.name
-      end
+      class << self
+        private
 
-      # Validate the ext-0x00 payload as UTF-8 and intern. Raises
-      # InvalidEncodingError on invalid bytes — SPEC forbids the
-      # 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!. 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, "Symbol payload")
-        name.to_sym
-      end
+        def pack_symbol(symbol)
+          symbol.name
+        end
 
-      # Handle-id packer for the ext-0x01 registration: the fixext-4
-      # big-endian id frame.
-      def pack_handle(handle)
-        [handle.id].pack("N")
-      end
+        # Refuses the binary-encoding fallback that msgpack-gem's default
+        # unpacker would otherwise apply to invalid bytes.
+        def unpack_symbol(payload)
+          name = payload.b.force_encoding(Encoding::UTF_8)
+          Utils.assert_utf8!(name, "Symbol payload")
+          name.to_sym
+        end
 
-      # Peel off the fixext-4 frame, hand the bytes to the
-      # Host-Gem-internal +Kobako::Handle.restore+ factory, and
-      # translate the +ArgumentError+ raised by Handle's invariants
-      # into a wire-layer +InvalidTypeError+ via Codec::Utils.with_boundary.
-      # The Value Object owns the id-range contract; this method only
-      # owns the frame shape. Records the Handle sighting on +state+ so a
-      # Handle-free decode can skip the downstream resolution walk.
-      def unpack_handle(payload, state)
-        state.record_handle!
-        bytes = payload.b
-        raise InvalidTypeError, "Handle payload must be 4 bytes, got #{bytes.bytesize}" unless bytes.bytesize == 4
+        def pack_handle(handle)
+          [handle.id].pack("N")
+        end
 
-        id = bytes.unpack1("N") # : Integer
-        Codec::Utils.with_boundary { Kobako::Handle.restore(id) }
-      end
+        # Handle owns the id-range contract; this method owns only the frame
+        # shape. The sighting is recorded so a Handle-free decode can skip the
+        # downstream resolution walk.
+        def unpack_handle(payload, state)
+          state.record_handle!
+          bytes = payload.b
+          raise InvalidTypeError, "Handle payload must be 4 bytes, got #{bytes.bytesize}" unless bytes.bytesize == 4
 
-      def register_symbol(factory)
-        factory.register_type(
-          EXT_SYMBOL, Symbol,
-          packer: ->(symbol) { ExtTypes.pack_symbol(symbol) },
-          unpacker: ->(payload) { ExtTypes.unpack_symbol(payload) }
-        )
-      end
+          id = bytes.unpack1("N") # : Integer
+          Codec::Utils.with_boundary { Kobako::Handle.restore(id) }
+        end
 
-      def register_handle(factory)
-        factory.register_type(
-          EXT_HANDLE, Kobako::Handle,
-          packer: ->(handle) { ExtTypes.pack_handle(handle) },
-          unpacker: ->(payload) { ExtTypes.unpack_handle(payload, State.current) }
-        )
-      end
+        def register_symbol(factory)
+          factory.register_type(
+            EXT_SYMBOL, Symbol,
+            packer: ->(symbol) { pack_symbol(symbol) },
+            unpacker: ->(payload) { unpack_symbol(payload) }
+          )
+        end
+
+        def register_handle(factory)
+          factory.register_type(
+            EXT_HANDLE, Kobako::Handle,
+            packer: ->(handle) { pack_handle(handle) },
+            unpacker: ->(payload) { unpack_handle(payload, State.current) }
+          )
+        end
 
-      # A catch-all packer that rejects any value with no wire representation
-      # as +UnsupportedTypeError+. Registered on +BasicObject+ so it also covers
-      # BasicObject-based proxies; the narrower Symbol / Handle
-      # registrations still win by most-specific match, and native types never
-      # reach it. Packer-only: the guard never writes bytes, so its id is inert
-      # and the decode surface stays fail-closed.
-      #
-      # This makes the host's non-wire detection a positive allowlist — a value
-      # outside the type set is rejected here rather than routed to +to_msgpack+
-      # — matching the guest's classname allowlist and the Rust codec's closed
-      # +Value+ enum. Without it, a value with a permissive +method_missing+
-      # answers the codec's +to_msgpack+ probe and mis-encodes as +nil+ instead
-      # of crossing as a Capability Handle.
-      def register_unrepresentable(factory)
-        factory.register_type(
-          UNREPRESENTABLE_GUARD_ID, BasicObject,
-          packer: ->(_value) { raise UnsupportedTypeError, "value has no wire representation" }
-        )
+        # A catch-all packer that rejects any value with no wire representation
+        # as +UnsupportedTypeError+. Registered on +BasicObject+ so it also covers
+        # BasicObject-based proxies; the narrower Symbol / Handle
+        # registrations still win by most-specific match, and native types never
+        # reach it. Packer-only: the guard never writes bytes, so its id is inert
+        # and the decode surface stays fail-closed.
+        #
+        # This makes the host's non-wire detection a positive allowlist — a value
+        # outside the type set is rejected here rather than routed to +to_msgpack+
+        # — matching the guest's classname allowlist and the Rust codec's closed
+        # +Value+ enum. Without it, a value with a permissive +method_missing+
+        # answers the codec's +to_msgpack+ probe and mis-encodes as +nil+ instead
+        # of crossing as a Capability Handle.
+        def register_unrepresentable(factory)
+          factory.register_type(
+            UNREPRESENTABLE_GUARD_ID, BasicObject,
+            packer: ->(_value) { raise UnsupportedTypeError, "value has no wire representation" }
+          )
+        end
       end
     end
 
-    # The process-wide registered factory: ext registration is paid once at
-    # load, and a registered +MessagePack::Factory+ only reads its type
-    # registry afterwards, so every thread shares this instance for byte
-    # work.
-    FACTORY = ExtTypes.build_factory
+    # Registered once at load and only read afterwards, so every thread
+    # shares it.
+    FACTORY = ExtTypes.build_factory # :nodoc:
     private_constant :FACTORY
   end
 end