kobako 0.27.0 → 0.28.0

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

data/lib/kobako/codec/handle_walk.rb

@@ -5,26 +5,11 @@ require_relative "../errors"
 
 module Kobako
   module Codec
-    # Substitutes Capability Handles into and out of a Ruby value tree at
-    # the host↔guest boundary. #deep_wrap allocates a +Kobako::Handle+ for
-    # each non-wire-representable leaf on the host→guest +#run+ argument
-    # path; #deep_restore resolves each wire-decoded Handle back to its
-    # host object on every guest→host value path. #representable? is the
-    # by-value codec-type predicate that decides which leaves #deep_wrap
-    # must wrap: the closed 11-entry wire type set
-    # ({docs/wire/payload-msgpack.md}[link:../../../docs/wire/payload-msgpack.md] § Type
-    # Mapping).
-    #
-    # All helpers are pure except #deep_wrap, whose only side effect is
-    # allocating new Handle ids into the supplied table.
-    module HandleWalk
-      module_function
-
+    module HandleWalk # :nodoc:
       # Inclusive Integer range the msgpack gem encodes without raising
       # +RangeError+ at encode time — signed +int 64+ minimum through
-      # unsigned +uint 64+ maximum
-      # ({docs/wire/payload-msgpack.md}[link:../../../docs/wire/payload-msgpack.md] § Type
-      # Mapping #3, the +fixint+ / +int 8..64+ / +uint 8..64+ union).
+      # unsigned +uint 64+ maximum (docs/wire/payload-msgpack.md § Integer
+      # Range).
       # Anchored as a +Range+ so #primitive_type? stays a single
       # dispatch line. This is the codec's encode domain — not to
       # be confused with the Handle id range, which lives on
@@ -32,141 +17,91 @@ module Kobako
       # represents a different concept entirely.
       MSGPACK_INT_RANGE = (-(2**63)..((2**64) - 1))
 
-      # Codec-type predicate
-      # ({docs/wire/payload-msgpack.md}[link:../../../docs/wire/payload-msgpack.md] § Type
-      # Mapping). Returns +true+ when +value+ belongs to the closed
-      # 11-entry codec type set — +nil+, +TrueClass+, +FalseClass+,
-      # +Integer+ (in the +i64..u64+ value domain), +Float+, +String+,
-      # +Symbol+, +Kobako::Handle+, +Array+ whose every element is itself
-      # representable, or +Hash+ whose every key and value are
-      # 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 UnsupportedTypeError.
-      #
-      # The optional +depth+ bounds the recursive descent at the wire's
-      # structural nesting cap so a self-referential container — reachable
-      # as a cyclic Hash key on the +#run+ argument path — reads as
-      # non-representable rather than looping, letting #deep_wrap_hash
-      # refuse it instead of overflowing this walk.
-      def representable?(value, depth = 0)
+      # Whether +value+ falls in the codec's type set
+      # (docs/wire/payload-msgpack.md § Type Mapping). The +depth+ bound
+      # makes a self-referential container —
+      # reachable as a cyclic Hash key on the +#run+ argument path — read as
+      # non-representable rather than looping.
+      def self.representable?(value, depth = 0)
         return false if depth > MAX_NESTING_DEPTH
 
         primitive_type?(value) || container_representable?(value, depth)
       end
 
-      # Deep-walk Array / Hash containers in +value+ and replace every
-      # leaf that fails #representable? with a +Kobako::Handle+
-      # allocated from +handler+. The
-      # walk only descends through representable container shapes
-      # (Array, Hash) one structural level at a time; a non-representable
-      # leaf is wrapped as-is without inspecting its internal structure.
-      # An existing +Kobako::Handle+ is representable and passes through
-      # unchanged — auto-wrap never re-wraps a Handle. Only Hash *values*
-      # are wrapped: a Hash *key* must already be wire-representable, since a
-      # key is not auto-wrapped the way a value is — a non-representable key
-      # raises +Kobako::SandboxError+ rather than crossing as an opaque token
-      # the guest→host restore walk could not round-trip.
-      #
-      # +value+ may be any Ruby value; +handler+ must respond to
-      # +#alloc(object) -> Kobako::Handle+ (a host-side
-      # +Kobako::Catalog::Handles+). Returns a structurally equivalent value
-      # whose leaves are either representable or +Kobako::Handle+
-      # tokens.
-      #
-      # Recursive calls spell the +HandleWalk.+ receiver so the dispatch
-      # stays valid even when a block is captured and run under a
-      # different +self+ (+module_function+ privatizes the instance copies).
-      def deep_wrap(value, handler, depth = 0)
+      # Only Hash values are wrapped: a non-representable key raises rather
+      # than crossing as a token the guest→host restore walk could not
+      # round-trip.
+      def self.deep_wrap(value, handles, depth = 0)
         guard_nesting!(depth)
         case value
-        when ::Array then value.map { |element| HandleWalk.deep_wrap(element, handler, depth + 1) }
-        when ::Hash  then HandleWalk.deep_wrap_hash(value, handler, depth)
+        when ::Array then value.map { |element| deep_wrap(element, handles, depth + 1) }
+        when ::Hash  then deep_wrap_hash(value, handles, depth)
         else
-          representable?(value) ? value : handler.alloc(value)
-        end
-      end
-
-      # Refuse a wrap walk that has descended past the wire's structural
-      # nesting bound — a reference cycle necessarily trips it — so a +#run+
-      # argument fails as a clean +Kobako::SandboxError+ rather than an
-      # unbounded host recursion.
-      def guard_nesting!(depth)
-        return unless depth > MAX_NESTING_DEPTH
-
-        raise Kobako::SandboxError,
-              "a #run argument nests deeper than #{MAX_NESTING_DEPTH} levels within the Run payload and " \
-              "cannot cross the sandbox boundary (possible reference cycle)"
-      end
-
-      # Wrap a Hash on the host→guest argument path: each value's
-      # non-representable leaves become Handles, while each key must be
-      # wire-representable as-is. A stateful object may cross the boundary as
-      # a Hash value but not as a key — the one deliberate asymmetry with the
-      # guest→host restore walk, which resolves Handle keys the guest built.
-      def deep_wrap_hash(hash, handler, depth)
-        wrapped = {} # : Hash[untyped, untyped]
-        hash.each do |key, val|
-          unless HandleWalk.representable?(key, depth + 1)
-            raise Kobako::SandboxError,
-                  "a Hash passed to #run has a key that cannot cross the sandbox boundary " \
-                  "(#{key.class}); only wire-representable values may be Hash keys"
-          end
-          wrapped[key] = HandleWalk.deep_wrap(val, handler, depth + 1)
+          representable?(value) ? value : handles.alloc(value)
         end
-        wrapped
       end
 
-      # Deep-walk Array / Hash containers in +value+ and replace every
-      # +Kobako::Handle+ leaf with the host-side object +handler+ resolves
-      # it to. The symmetric inverse of #deep_wrap: that walk allocates objects
-      # into Handles on the host→guest argument path; this walk resolves
-      # Handles back to their objects wherever a guest→host payload carries
-      # one — an invocation result, a yield-block result, or a dispatch
-      # argument. The walk descends through Array elements and Hash keys and
-      # values one structural level at a time; any non-Handle leaf passes
-      # through unchanged.
-      #
-      # +value+ is a decoded Ruby value (a Handle here is a wire-decoded
-      # +Kobako::Handle+, never a guest-forged one); +handler+ must
-      # respond to +#fetch(id) -> object+ (a host-side
-      # +Kobako::Catalog::Handles+). +handler.fetch+ raises
-      # +Kobako::SandboxError+ for an id with no live binding, the
-      # corrupted-runtime fallback.
-      def deep_restore(value, handler)
+      # The inverse of #deep_wrap. A Handle here was decoded off the wire,
+      # never forged by the guest, and +handles.fetch+ refuses an id with no
+      # live binding.
+      def self.deep_restore(value, handles)
         case value
-        when ::Array then value.map { |element| HandleWalk.deep_restore(element, handler) }
+        when ::Array then value.map { |element| deep_restore(element, handles) }
         when ::Hash
           # Rebuilt with each key restored: two distinct Handle keys that
           # resolve to equal host objects collapse to the later pair, as in
           # any Ruby Hash. The guest authored this payload, so that collapse
           # is its own concern, not a fidelity guarantee the host owes it.
-          value.to_h { |key, val| [HandleWalk.deep_restore(key, handler), HandleWalk.deep_restore(val, handler)] }
-        when Kobako::Handle then handler.fetch(value.id)
+          value.to_h { |key, val| [deep_restore(key, handles), deep_restore(val, handles)] }
+        when Kobako::Handle then handles.fetch(value.id)
         else value
         end
       end
 
-      # The non-container branch of #representable?: returns +true+ for
-      # the scalar leaves and an existing Handle. Not part of the
-      # public surface; reach for #representable? instead.
-      def primitive_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
+      class << self
+        private
+
+        # A reference cycle necessarily trips the nesting bound, so a +#run+
+        # argument fails as a clean +Kobako::SandboxError+ rather than an
+        # unbounded host recursion.
+        def guard_nesting!(depth)
+          return unless depth > MAX_NESTING_DEPTH
+
+          raise Kobako::SandboxError,
+                "a #run argument nests deeper than #{MAX_NESTING_DEPTH} levels within the Run payload and " \
+                "cannot cross the sandbox boundary (possible reference cycle)"
         end
-      end
 
-      # The container branch of #representable?: recurses into Array
-      # elements and Hash key+value pairs through the public
-      # #representable?. Not part of the public surface; reach for
-      # #representable? instead.
-      def container_representable?(value, depth)
-        case value
-        when ::Array then value.all? { |element| HandleWalk.representable?(element, depth + 1) }
-        when ::Hash  then value.all? { |pair| pair.all? { |member| HandleWalk.representable?(member, depth + 1) } }
-        else false
+        # A stateful object may cross the boundary as a Hash value but not as
+        # a key — the one deliberate asymmetry with the guest→host restore
+        # walk, which resolves Handle keys the guest built.
+        def deep_wrap_hash(hash, handles, depth)
+          wrapped = {} # : Hash[untyped, untyped]
+          hash.each do |key, val|
+            unless representable?(key, depth + 1)
+              raise Kobako::SandboxError,
+                    "a Hash passed to #run has a key that cannot cross the sandbox boundary " \
+                    "(#{key.class}); only wire-representable values may be Hash keys"
+            end
+            wrapped[key] = deep_wrap(val, handles, depth + 1)
+          end
+          wrapped
+        end
+
+        def primitive_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
+
+        def container_representable?(value, depth)
+          case value
+          when ::Array then value.all? { |element| representable?(element, depth + 1) }
+          when ::Hash  then value.all? { |pair| pair.all? { |member| representable?(member, depth + 1) } }
+          else false
+          end
         end
       end
     end

data/lib/kobako/codec/nesting.rb

@@ -4,14 +4,9 @@ require_relative "error"
 
 module Kobako
   module Codec
-    # The structural nesting bound
-    # ({docs/wire/payload-msgpack.md}[link:../../../docs/wire/payload-msgpack.md]
-    # § Structural Nesting Depth), checked before a value reaches the
-    # packer. The packer takes no depth limit and walks a list or map in
-    # frames that carry no stack guard, so a value it cannot finish — a
-    # reference cycle necessarily is one — must be refused before it is
-    # handed over.
-    module Nesting
+    # Refuses a value nested past the wire's bound before the packer sees it,
+    # since the packer walks without a stack guard and a cycle never ends.
+    module Nesting # :nodoc:
       # Raise InvalidTypeError when +value+ nests past MAX_NESTING_DEPTH; a
       # value nested exactly to the bound passes.
       def self.assert_within_bound!(value, depth = 0)

data/lib/kobako/codec/state.rb

@@ -2,11 +2,9 @@
 
 module Kobako
   module Codec
-    # Codec-internal, per-thread state of the operation in flight: whether
-    # a Capability Handle crossed the current decode. Thread scoping is
-    # what makes plain instance variables sound — host codec calls run
-    # synchronously on their owning thread.
-    class State
+    # Whether a Capability Handle crossed the decode in flight, kept per
+    # thread so plain instance variables stay sound.
+    class State # :nodoc:
       # Thread-local slot holding the calling thread's State.
       STATE_KEY = :__kobako_codec_state__
       private_constant :STATE_KEY
@@ -22,12 +20,8 @@ module Kobako
         @carried_handle = false
       end
 
-      # Bracket a decode and return the block's result together with
-      # whether the decoded tree carried an ext 0x01 Capability Handle.
       # ExtTypes#unpack_handle is the sole chokepoint every Handle passes
-      # through, so one decode pass records the whole tree and a caller
-      # can skip an all-identity Handle-resolution walk when none was
-      # present.
+      # through, so one decode pass records the whole tree.
       def track_handles
         @carried_handle = false
         result = yield

data/lib/kobako/codec/utils.rb

@@ -4,45 +4,17 @@ require_relative "error"
 
 module Kobako
   module Codec
-    # Byte-boundary helpers shared by the host-side encoder and decoder.
-    # Two concerns live here:
-    #
-    #   - UTF-8 assertion at the codec 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 ExtTypes
-    #     when validating the +ext 0x00+ Symbol payload.
-    #   - +ArgumentError+ translation at the codec boundary
-    #     (#with_boundary) so the public taxonomy stays
-    #     Kobako::Codec::Error.
-    #
-    # Both helpers are pure — they only inspect inputs, never mutate them.
-    # The host↔guest Handle substitution walk lives in HandleWalk.
-    module Utils
-      module_function
-
-      # Raise InvalidEncodingError 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"+, +"Symbol payload"+).
-      def assert_utf8!(string, label)
+    module Utils # :nodoc:
+      def self.assert_utf8!(string, label)
         return if string.valid_encoding?
 
         raise InvalidEncodingError, "#{label} is not valid UTF-8"
       end
 
-      # Run +block+ at the codec boundary: a value object raises
-      # +ArgumentError+ when an invariant is violated at construction, and
-      # this helper surfaces that as InvalidTypeError so the public taxonomy
-      # stays Kobako::Codec::Error and never leaks +ArgumentError+ from
-      # the Ruby standard library.
-      #
-      # Reach for this only where a value object is constructed outside a
-      # Decoder.decode block, whose rescue already performs the same
-      # mapping (worked example: ExtTypes#unpack_handle building
-      # +Handle.restore+ from a raw fixext payload). Do not use it for
-      # general-purpose validation outside the codec boundary —
-      # host-layer +ArgumentError+ values should propagate unchanged.
-      def with_boundary
+      # Only for a value object built outside a Decoder.decode block, whose
+      # rescue already maps the same way; a host-layer +ArgumentError+
+      # elsewhere should propagate unchanged.
+      def self.with_boundary
         yield
       rescue ::ArgumentError => e
         raise InvalidTypeError, e.message