kobako 0.13.0 → 0.15.0

data/lib/kobako/catalog/services.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require_relative "handles"
+require_relative "../codec"
+require_relative "../errors"
+
+module Kobako
+  module Catalog
+    # Kobako::Catalog::Services — per-Sandbox registry of Service
+    # bindings keyed by their constant-path name. Holds the flat
+    # path→object table and the preamble emitted on Frame 1.
+    #
+    # Public API:
+    #
+    #   services = Kobako::Catalog::Services.new
+    #   services.bind("MyService::KV", kv_object)  # => services (chainable)
+    #   services.encode                            # => msgpack bytes for Frame 1
+    #   services.lookup("MyService::KV")           # => kv_object
+    #
+    # 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. The registry holds an
+    # injected +Catalog::Handles+ reference so dispatch target resolution
+    # and host→guest auto-wrap share the same Sandbox-owned allocator.
+    class Services
+      # Ruby constant-name pattern each +::+-separated bind-path segment
+      # must match.
+      NAME_PATTERN = /\A[A-Z]\w*\z/
+
+      # 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 cap-exhaustion path
+      # without 2³¹ allocations. Production callers leave it at the default.
+      def initialize(handler: Catalog::Handles.new)
+        @bindings = {} # : Hash[String, untyped]
+        @handler = handler
+        @sealed = false
+        @encoded = nil # : String?
+      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.
+      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)
+
+        @bindings[path_str] = object
+        self
+      end
+
+      # Resolve a +target+ constant path to the bound Service. 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)
+
+        @bindings[target_str]
+      end
+
+      # Encode the preamble as msgpack bytes for stdin Frame 1 delivery —
+      # a flat array of the bound constant paths, in bind order:
+      # +["MyService::KV", "File"]+. Routes through Kobako::Codec::Encoder
+      # like every other host-side wire encode; the preamble carries only
+      # Strings, so none of the kobako ext types fire. Returns a binary
+      # +String+ of msgpack bytes.
+      #
+      # Once sealed, the bytes are computed once and reused for every
+      # subsequent invocation: sealing freezes Service registration at the
+      # first invocation, so a bind reaching the registry after the seal
+      # raises +ArgumentError+ and never alters Frame 1.
+      def encode
+        return @encoded if @encoded
+
+        bytes = Codec::Encoder.encode(@bindings.keys).freeze
+        @encoded = bytes if @sealed
+        bytes
+      end
+
+      # Mark the registry as sealed. 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) }
+
+        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.
+      def collision?(path)
+        @bindings.each_key.any? do |existing|
+          existing == path ||
+            existing.start_with?("#{path}::") ||
+            path.start_with?("#{existing}::")
+        end
+      end
+    end
+  end
+end

data/lib/kobako/catalog/snippets.rb

@@ -43,8 +43,8 @@ module Kobako
       #
       # The bytes are memoized — the table is replayed verbatim on every
       # invocation after sealing, so Frame 3 never changes between
-      # encodes; {#register} drops the memo while the table is still open.
-      # Unlike +Catalog::Namespaces#encode+, which gates its memo on the
+      # encodes; #register drops the memo while the table is still open.
+      # Unlike +Catalog::Services#encode+, which gates its memo on the
       # seal, this one can fill eagerly and invalidate in +#register+
       # because every mutation funnels through that single method — there is
       # no out-of-sight child object to change the result behind its back.

data/lib/kobako/catalog.rb

@@ -1,13 +1,13 @@
 # frozen_string_literal: true
 
 require_relative "catalog/handles"
-require_relative "catalog/namespaces"
+require_relative "catalog/services"
 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),
+  # owns: +Catalog::Services+ (path→Service binding registry),
   # +Catalog::Snippets+ (preloaded source / bytecode entries), and
   # +Catalog::Handles+ (per-invocation Handle ID allocator).
   #

data/lib/kobako/codec/decoder.rb

@@ -3,7 +3,7 @@
 require "msgpack"
 
 require_relative "error"
-require_relative "factory"
+require_relative "ext_types"
 require_relative "utils"
 
 module Kobako
@@ -12,32 +12,32 @@ module Kobako
     # ({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
+    # (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
+    # 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.
+      # 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}
+      # surfaces as InvalidType without a separate Utils.with_boundary
       # wrapper at the call site.
       def self.decode(bytes)
-        value = Factory.load(bytes.b)
+        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}.
+      # are wire violations, so both map to InvalidType.
       rescue ::MessagePack::UnknownExtTypeError, ::MessagePack::MalformedFormatError,
              ::MessagePack::StackError, ::ArgumentError => e
         raise InvalidType, e.message
@@ -53,8 +53,8 @@ module Kobako
       # 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+
+      # str-typed leaf via Utils.assert_utf8!. Kobako::Fault
+      # payloads are validated transitively: +ExtTypes#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

data/lib/kobako/codec/encoder.rb

@@ -3,7 +3,7 @@
 require "msgpack"
 
 require_relative "error"
-require_relative "factory"
+require_relative "ext_types"
 
 module Kobako
   module Codec
@@ -13,10 +13,10 @@ module Kobako
     # 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.
+    # Capability Handle, 0x02 Exception envelope) are registered by
+    # ExtTypes on the process-wide factory.
     #
-    # Public API is a single function — {.encode}. The codec is stateless;
+    # 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.
@@ -32,7 +32,7 @@ module Kobako
       # +NoMethodError+ is likewise reported as +UnsupportedType+ rather than
       # propagating.
       def self.encode(value)
-        Factory.dump(value)
+        FACTORY.dump(value)
       rescue ::RangeError, ::NoMethodError => e
         raise UnsupportedType, e.message
       end

data/lib/kobako/codec/error.rb

@@ -7,11 +7,11 @@ module Kobako
     # 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
+    # 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.
+    # the public Kobako::SandboxError / Kobako::TrapError taxonomy.
     class Error < StandardError; end
 
     # Input ended before the type prefix or payload was fully consumed.
@@ -21,7 +21,7 @@ module 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
+    # 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
 

data/lib/kobako/codec/ext_types.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+require "msgpack"
+
+require_relative "error"
+require_relative "utils"
+require_relative "state"
+require_relative "../handle"
+require_relative "../fault"
+
+module Kobako
+  module Codec
+    # The kobako wire ext-type conversions
+    # ({docs/wire-codec.md}[link:../../../docs/wire-codec.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
+      # MessagePack ext type code reserved for Symbol
+      # ({docs/wire-codec.md}[link:../../../docs/wire-codec.md] § 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
+      # ({docs/wire-codec.md}[link:../../../docs/wire-codec.md] § 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
+      # ({docs/wire-codec.md}[link:../../../docs/wire-codec.md] § 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
+
+      module_function
+
+      # Assemble a +MessagePack::Factory+ with the three kobako ext types
+      # 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
+        factory = MessagePack::Factory.new
+        register_symbol(factory)
+        register_handle(factory)
+        register_fault(factory)
+        factory.freeze
+      end
+
+      # Symbol-to-name packer for the ext-0x00 registration.
+      def pack_symbol(symbol)
+        symbol.name
+      end
+
+      # 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. 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
+
+      # Handle-id packer for the ext-0x01 registration: the fixext-4
+      # big-endian id frame.
+      def pack_handle(handle)
+        [handle.id].pack("N")
+      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 +InvalidType+ 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 InvalidType, "Handle payload must be 4 bytes, got #{bytes.bytesize}" unless bytes.bytesize == 4
+
+        id = bytes.unpack1("N") # : Integer
+        Codec::Utils.with_boundary { Kobako::Handle.restore(id) }
+      end
+
+      # Encode the inner ext-0x02 map via Encoder (not the raw factory) so
+      # the embedded payload flows through the same boundary as a top-level
+      # encode — nested kobako values (Handle, nested Fault) reach the
+      # registered ext-type packers. A +details+ chain nested past the
+      # +state+ depth cap has no wire representation and surfaces as
+      # +UnsupportedType+. In a payload position (+state+ inside a
+      # forbid_faults bracket) the envelope has no wire representation at
+      # all, so the refusal routes the value into the position's
+      # non-representable handling — the Dispatcher's auto-wrap rescue,
+      # or a raise at the yield site.
+      def pack_fault(fault, state)
+        if state.faults_forbidden?
+          raise UnsupportedType, "Kobako::Fault has no wire representation in a payload position"
+        end
+
+        state.within_ext_frame(UnsupportedType) do
+          Encoder.encode("type" => fault.type, "message" => fault.message, "details" => fault.details)
+        end
+      end
+
+      # Peel the embedded msgpack map and hand it to +Kobako::Fault.new+
+      # inside Decoder.decode's block form, so the value-object's
+      # +ArgumentError+ invariants surface as +InvalidType+ through the
+      # decoder boundary. Inner decode goes through Decoder (not the raw
+      # factory) so the embedded +str+ payloads flow through the same
+      # UTF-8 validation as a top-level decode. A nested ext 0x02 in
+      # +details+ re-enters this method, so the +state+ ext-frame guard
+      # bounds the chain depth to keep it from exhausting the native stack.
+      # In a payload position (+state+ inside a forbid_faults bracket) the
+      # envelope is a wire violation outright — its sole legal position is
+      # the Response fault field.
+      def unpack_fault(payload, state)
+        if state.faults_forbidden?
+          raise InvalidType, "Fault envelope (ext 0x02) is not a legal value in a payload position"
+        end
+
+        state.within_ext_frame(InvalidType) do
+          Decoder.decode(payload) do |map|
+            raise InvalidType, "Fault payload must be a map" unless map.is_a?(Hash)
+
+            Kobako::Fault.new(type: map["type"], message: map["message"], details: map["details"])
+          end
+        end
+      end
+
+      def register_symbol(factory)
+        factory.register_type(
+          EXT_SYMBOL, Symbol,
+          packer: ->(symbol) { ExtTypes.pack_symbol(symbol) },
+          unpacker: ->(payload) { ExtTypes.unpack_symbol(payload) }
+        )
+      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_fault(factory)
+        factory.register_type(
+          EXT_ERRENV, Kobako::Fault,
+          packer: ->(fault) { ExtTypes.pack_fault(fault, State.current) },
+          unpacker: ->(payload) { ExtTypes.unpack_fault(payload, State.current) }
+        )
+      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
+    private_constant :FACTORY
+  end
+end

data/lib/kobako/codec/handle_walk.rb

@@ -5,16 +5,16 @@ require_relative "../handle"
 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
+    # 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}
+    # 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 12-entry wire type set
     # ({docs/wire-codec.md}[link:../../../docs/wire-codec.md] § Type
     # Mapping).
     #
-    # All helpers are pure except {deep_wrap}, whose only side effect is
+    # All helpers are pure except #deep_wrap, whose only side effect is
     # allocating new Handle ids into the supplied table.
     module HandleWalk
       module_function
@@ -24,7 +24,7 @@ module Kobako
       # unsigned +uint 64+ maximum
       # ({docs/wire-codec.md}[link:../../../docs/wire-codec.md] § Type
       # Mapping #3, the +fixint+ / +int 8..64+ / +uint 8..64+ union).
-      # Anchored as a +Range+ so {primitive_type?} stays a single
+      # 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
       # +Kobako::Handle+ as +MIN_ID+ / +MAX_ID+ (1..2^31 − 1) and
@@ -41,13 +41,13 @@ module Kobako
       # representable. Integers outside the codec's signed-64 /
       # unsigned-64 union are rejected so the predicate agrees with the
       # msgpack gem's encode-time +RangeError+ behaviour the codec
-      # already surfaces as {UnsupportedType}.
+      # already surfaces as UnsupportedType.
       def representable?(value)
         primitive_type?(value) || container_representable?(value)
       end
 
       # Deep-walk Array / Hash containers in +value+ and replace every
-      # leaf that fails {representable?} with a +Kobako::Handle+
+      # 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
@@ -61,13 +61,9 @@ module Kobako
       # whose leaves are either representable or +Kobako::Handle+
       # tokens.
       #
-      # The block bodies spell +HandleWalk.deep_wrap+ explicitly rather
-      # than the unqualified +deep_wrap+ because +module_function+ makes
-      # the instance copy of these helpers private; an implicit receiver
-      # inside a block would resolve against the enclosing +self+
-      # (still +HandleWalk+ at definition time, but the qualified form
-      # keeps the dispatch readable when the recursive call sits inside a
-      # Proc captured from elsewhere).
+      # 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)
         case value
         when ::Array then value.map { |element| HandleWalk.deep_wrap(element, handler) }
@@ -79,7 +75,7 @@ module Kobako
 
       # 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
+      # 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
@@ -107,9 +103,9 @@ module Kobako
         end
       end
 
-      # The non-container branch of {representable?}: returns +true+ for
+      # 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.
+      # public surface; reach for #representable? instead.
       def primitive_type?(value)
         case value
         when ::NilClass, ::TrueClass, ::FalseClass, ::Float, ::String, ::Symbol, Kobako::Handle then true
@@ -118,10 +114,10 @@ module Kobako
         end
       end
 
-      # The container branch of {representable?}: recurses into Array
+      # 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.
+      # #representable?. Not part of the public surface; reach for
+      # #representable? instead.
       def container_representable?(value)
         case value
         when ::Array then value.all? { |element| HandleWalk.representable?(element) }

data/lib/kobako/codec/state.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Kobako
+  module Codec
+    # Codec-internal, per-thread state of the operation in flight: the
+    # ext-envelope nesting depth and 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, and a nested decode (an ext 0x02 Fault re-entering
+    # through its +details+) reuses the same thread instance, so the
+    # depth counter accumulates across the re-entry instead of resetting.
+    class State
+      # An ext 0x02 (Fault) envelope nests through its +details+ field, and
+      # each level re-enters the codec with a fresh +MessagePack+ unpacker
+      # whose built-in stack guard resets — so ext-envelope depth is tracked
+      # here instead. The cap matches the wire's overall nesting bound and
+      # keeps a nested chain from exhausting the native stack: an over-deep
+      # chain fails as a clean wire error, never a stack-level trap.
+      MAX_EXT_DEPTH = 128
+      private_constant :MAX_EXT_DEPTH
+
+      # Thread-local slot holding the calling thread's State.
+      STATE_KEY = :__kobako_codec_state__
+      private_constant :STATE_KEY
+
+      # The calling thread's State, built on first use so the mutable
+      # state stays isolated to the thread that runs the codec call.
+      def self.current
+        Thread.current[STATE_KEY] ||= new
+      end
+      private_class_method :new
+
+      def initialize
+        @ext_depth = 0
+        @carried_handle = false
+        @faults_forbidden = 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.
+      def track_handles
+        @carried_handle = false
+        result = yield
+        [result, @carried_handle]
+      end
+
+      # Record that an ext 0x01 Capability Handle crossed the current
+      # decode; #track_handles reports it to the bracketing caller.
+      def record_handle!
+        @carried_handle = true
+      end
+
+      # Bracket a codec operation in a payload position, where an ext 0x02
+      # Fault envelope has no legal wire representation: the fault field of
+      # an error Response is its only home. The ext-type conversions
+      # consult #faults_forbidden? and refuse the envelope in both
+      # directions while the bracket is open. Save/restore keeps a nested
+      # legal operation on the same thread unaffected.
+      def forbid_faults
+        previous = @faults_forbidden
+        @faults_forbidden = true
+        yield
+      ensure
+        @faults_forbidden = previous
+      end
+
+      # Whether the operation in flight sits inside a #forbid_faults
+      # bracket — i.e. in a payload position where ext 0x02 is a wire
+      # violation.
+      def faults_forbidden?
+        @faults_forbidden
+      end
+
+      # Track ext-envelope re-entry depth and refuse a chain past
+      # MAX_EXT_DEPTH, raising +over_limit+ so the failure lands in the
+      # caller's existing wire-error class. The next depth is checked before
+      # it is committed, so an over-deep rejection leaves the counter
+      # untouched, and the +ensure+ restores the entry value on the way out.
+      def within_ext_frame(over_limit)
+        depth = @ext_depth + 1
+        raise over_limit, "ext envelope nesting exceeds #{MAX_EXT_DEPTH} levels" if depth > MAX_EXT_DEPTH
+
+        @ext_depth = depth
+        begin
+          yield
+        ensure
+          @ext_depth = depth - 1
+        end
+      end
+    end
+
+    private_constant :State
+  end
+end