kobako 0.26.0 → 0.28.0

data/lib/kobako/catalog/extensions.rb

@@ -4,37 +4,17 @@ require_relative "../unresolved"
 
 module Kobako
   module Catalog
-    # Kobako::Catalog::Extensions — per-Sandbox registry of installed
-    # Extensions. Composes each Extension onto the sibling registries at
-    # install time (its +source+ into +Catalog::Snippets+, its +backend+
-    # path into +Catalog::Services+), asserts declared dependencies are
-    # present when the Sandbox seals, and resolves each callable-backed
-    # path to a fresh object for every invocation — returning that map to the
-    # driving +Context+ rather than mutating the shared registry, so
-    # concurrent invocations stay shared-nothing.
-    #
-    # Sealing and the reject-after-install guard are governed by the owning
-    # Sandbox through +Catalog::Services#sealed?+, the shared seal signal;
-    # this registry only records entries and enforces the Extension-shape
-    # and dependency rules.
-    class Extensions
+    # The installed Extensions, composed onto the Service and snippet
+    # registries. Providers resolve afresh for each invocation and are handed
+    # back rather than stored, so concurrent invocations share nothing.
+    class Extensions # :nodoc:
       def initialize
         @entries = [] # : Array[untyped]
         @asserted = false
       end
 
-      # Install +extension+: validate its shape, register its +source+ as a
-      # preloaded snippet, and — when it carries a +backend+ — reserve the
-      # backend path in +services+. A static +object:+ binds directly; a
-      # per-invocation +provider:+ or a fillable backend reserves the path with
-      # +Kobako::Unresolved+ (the per-invocation result is layered onto the
-      # Context, a fillable stays Unresolved until filled). Raises
-      # +ArgumentError+ for the two shapes +#validate!+ owns — +source+ not a
-      # String, or a present +backend+ that omits +path+ / +object+ /
-      # +provider+. The Extension readers are duck-typed, so an object missing
-      # them surfaces the underlying +NoMethodError+, and a malformed +name+ or
-      # +backend.path+ surfaces through the +snippets+ / +services+
-      # registration it routes to.
+      # The Extension readers are duck-typed, so a malformed +name+ or
+      # +backend.path+ surfaces through the registry it routes to.
       def install(extension, snippets:, services:)
         validate!(extension)
         snippets.register(code: extension.source, name: extension.name)
@@ -44,27 +24,24 @@ module Kobako
         self
       end
 
-      # Assert every installed Extension's +depends_on+ names a fellow
-      # installed Extension. Runs once, when the Sandbox first seals
-      # successfully; an unmet dependency raises +ArgumentError+ naming the
-      # gap, before the guest runs. The asserted flag flips only on success,
-      # so a seal that failed re-checks on the next attempt rather than
-      # silently passing a broken Sandbox. Idempotent across later invocations.
-      def seal!
+      # The asserted flag flips only on success, so a check that failed
+      # re-runs on the next invocation rather than silently passing a broken
+      # Sandbox.
+      def assert_dependencies!
         return self if @asserted
 
-        assert_dependencies!
+        extension, dependency = unmet_dependency
+        if extension
+          raise ArgumentError,
+                "Extension #{extension.name.inspect} depends on #{dependency.inspect}, which is not installed"
+        end
+
         @asserted = true
         self
       end
 
-      # Resolve each +provider:+-backed path to this invocation's object and
-      # return the +path => object+ map the driving +Context+ layers over the
-      # static base bindings. Distinct providers yield distinct objects; one
-      # provider shared by several Extensions is invoked once and its result
-      # shared, so provider identity is resource identity. Static and fillable
-      # backends are omitted — they stay the object bound at install in the
-      # base registry (+Kobako::Unresolved+ for a fillable).
+      # One provider shared by several Extensions is invoked once and its
+      # result shared, so provider identity is resource identity.
       def resolve
         resolved = {} # : Hash[String, untyped]
         by_provider = {} # : Hash[untyped, untyped]
@@ -75,15 +52,8 @@ module Kobako
 
       private
 
-      # The object a backend binds at install: a static +object:+ directly, or
-      # +Kobako::Unresolved+ as the placeholder for a per-invocation +provider:+
-      # (layered onto the Context) or a fillable (neither keyword).
       def install_object(backend) = backend.object.nil? ? Kobako::Unresolved : backend.object
 
-      # Resolve one Extension's +provider:+-backed path against the shared
-      # per-invocation identity cache (keyed by provider identity) and record
-      # it in +resolved+. A static or fillable backend is skipped — its object
-      # stays as bound at install in the base registry.
       def resolve_backend(extension, resolved, by_provider)
         backend = extension.backend
         return unless backend
@@ -94,9 +64,6 @@ module Kobako
         resolved[backend.path.to_s] = by_provider.fetch(provider) { by_provider[provider] = provider.call }
       end
 
-      # Enforce the Extension-shape checks +#preload+ / +#bind+ do not: a
-      # mandatory String +source+ (the install/bind boundary) and a
-      # +backend+ that, when present, exposes +path+ / +object+ / +provider+.
       def validate!(extension)
         source = extension.source
         raise ArgumentError, "Extension #source must be a String, got #{source.class}" unless source.is_a?(String)
@@ -108,21 +75,16 @@ module Kobako
         raise ArgumentError, "Extension #backend must expose #path, #object, and #provider"
       end
 
-      def assert_dependencies!
+      def unmet_dependency
         names = @entries.map { |extension| symbolize(extension.name) }
         @entries.each do |extension|
           (extension.depends_on || []).each do |dependency|
-            next if names.include?(symbolize(dependency))
-
-            raise ArgumentError,
-                  "Extension #{extension.name.inspect} depends on #{dependency.inspect}, which is not installed"
+            return [extension, dependency] unless names.include?(symbolize(dependency))
           end
         end
+        nil
       end
 
-      # Match names and dependencies by Symbol so the Symbol-or-String forms
-      # of a constant token are interchangeable; a value that is neither
-      # falls through unchanged to the not-installed path.
       def symbolize(name) = name.is_a?(String) ? name.to_sym : name
     end
   end

data/lib/kobako/catalog/flags.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Kobako
+  module Catalog
+    class Flags # :nodoc:
+      def initialize
+        @entries = {} # : Hash[String, [String, bool]]
+      end
+
+      # Each entry is the name, the value, and whether the flag is critical.
+      def entries
+        @entries.map { |name, (value, critical)| [name, value, critical] }
+      end
+
+      def register(name, value, advisory:)
+        unless name.is_a?(Symbol) || name.is_a?(String)
+          raise ArgumentError, "flag name must be a Symbol or String, got #{name.class}"
+        end
+        raise ArgumentError, "flag value must be a String, got #{value.class}" unless value.is_a?(String)
+
+        key = utf8!(name.to_s, "flag name")
+        raise ArgumentError, "flag #{key.inspect} already set" if @entries.key?(key)
+
+        @entries[key] = [utf8!(value, "flag value"), !advisory]
+        nil
+      end
+
+      private
+
+      # The native side carries a flag only as UTF-8 text, so text read as
+      # bytes is re-tagged, and bytes that are not UTF-8 are refused here
+      # rather than failing every invocation.
+      def utf8!(text, what)
+        utf8 = text.dup.force_encoding(Encoding::UTF_8)
+        raise ArgumentError, "#{what} must be UTF-8 text" unless utf8.valid_encoding?
+
+        utf8
+      end
+    end
+  end
+end

data/lib/kobako/catalog/handles.rb

@@ -7,30 +7,11 @@ require_relative "../transport/exposure"
 
 module Kobako
   module Catalog
-    # Host-side mapping from opaque integer Handle IDs to Ruby objects.
-    # Each invocation's +Kobako::Context+ mints its own table and hands it to
-    # the dispatcher, so guest→host dispatch resolves Handle targets and
-    # arguments against the same table that host→guest wire encoding allocates
-    # into for that run.
-    #
-    # Lifecycle invariants:
-    #
-    #   - 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+.
-    #
-    #   - A fresh table backs each invocation, so a Handle issued in one
-    #     invocation resolves in no other — uniformly regardless of
-    #     allocation source (Service return or host-injected argument).
-    #
-    #   - 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);
-      # tests pass a value near +Kobako::Handle::MAX_ID+ to exercise
-      # the cap-exhaustion path without 2³¹ allocations.
+    # One invocation's Handle table, mapping opaque ids to host objects. Each
+    # invocation mints its own, so a Handle resolves only where it was issued.
+    class Handles # :nodoc:
+      # +next_id+ lets tests start near +Kobako::Handle::MAX_ID+ to reach
+      # exhaustion without 2³¹ allocations.
       def initialize(next_id: 1)
         @entries = {} # : Hash[Integer, Kobako::Transport::Exposure]
         surfaces = {} # : Hash[Module, Set[Symbol]]
@@ -38,19 +19,6 @@ module Kobako
         @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::HandleExhaustedError+ 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.
-      #
-      # Returning a Handle (rather than a bare Integer id) keeps the
-      # allocator's output a domain entity. An id is the Handle's only
-      # content, so the same internal +Kobako::Handle.restore+ constructor
-      # serves both this allocator and the codec's wire-decode path.
-      #
       # The entry records the object's Exposure as it stands at mint, so a
       # call made through this Handle is authorized against the reference
       # the guest was given.
@@ -63,27 +31,17 @@ module Kobako
         Kobako::Handle.restore(id)
       end
 
-      # Resolve a Handle ID to its bound object — the very object +#alloc+
-      # received, so a Handle crossing back restores to it. +id+ is a Handle
-      # ID previously returned by +#alloc+. Raises +Kobako::SandboxError+ if
-      # +id+ is not currently bound.
       def fetch(id)
         exposure(id).object
       end
 
-      # The Exposure +id+ was minted with, which authorizes a call the guest
-      # makes through that Handle. Raises +Kobako::SandboxError+ if +id+ is
-      # not currently bound.
       def exposure(id)
         require_bound!(id)
         @entries[id]
       end
 
-      # Number of currently-bound entries. Used by tests of the Dispatcher
-      # and Codec::HandleWalk#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.
+      # The table never consults its own size; tests read it to pin how many
+      # Handles each path allocates.
       def size
         @entries.size
       end
@@ -113,8 +71,6 @@ module Kobako
         end
       end
 
-      # Guard #alloc against issuing an ID past the cap. Returns +nil+
-      # on success; raises +Kobako::HandleExhaustedError+ at exhaustion.
       def ensure_capacity!
         cap = Kobako::Handle::MAX_ID
         return unless @next_id > cap
@@ -124,9 +80,6 @@ module Kobako
               "in a single invocation (limit #{cap})"
       end
 
-      # 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)
 

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!.