kobako 0.14.0 → 0.15.0

data/crates/kobako-wasmtime/src/guest_mem.rs

@@ -44,6 +44,13 @@ impl Yielder for CallerYielder<'_, '_> {
 const RUNTIME_INCOMPATIBLE: &str =
     "the Sandbox runtime is incompatible; rebuild data/kobako.wasm against the installed version";
 
+/// User-facing message for the "the loaded Wasm module is not a
+/// Kobako-shaped runtime at all" failure mode — no linear memory export
+/// here, no `memory` module export on the instantiation path in
+/// `frames`. One constant so the two detection sites cannot drift.
+pub(crate) const SANDBOX_RUNTIME_NOT_KOBAKO: &str =
+    "the loaded Wasm module is not a Kobako-compatible runtime";
+
 /// Resolve the guest's exported linear `memory`. The lookup shape (and its
 /// diagnostic) is shared by every Caller-based path here — the write side
 /// (`alloc_and_write`), the read side (`read`), and the yield round-trip
@@ -52,7 +59,7 @@ const RUNTIME_INCOMPATIBLE: &str =
 fn memory_export(caller: &mut Caller<'_, Invocation>) -> Result<Memory, &'static str> {
     match caller.get_export("memory") {
         Some(Extern::Memory(m)) => Ok(m),
-        _ => Err("the loaded Wasm module is not a Kobako-compatible runtime"),
+        _ => Err(SANDBOX_RUNTIME_NOT_KOBAKO),
     }
 }
 

data/crates/kobako-wasmtime/src/trap.rs

@@ -42,60 +42,29 @@ pub(crate) fn epoch_deadline_callback(
     }
 }
 
-/// Configured-cap path classification for a wasmtime error. The
-/// downcast logic stays in a pure helper so the `Trap` kind routing
-/// can be exercised from `cargo test` without any frontend.
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-enum TrapClass {
-    /// Wall-clock cap path.
-    Timeout,
-    /// Linear-memory cap path.
-    MemoryLimit,
-    /// Any other wasmtime error — surfaces as the base `Trap::Other`.
-    Other,
-}
-
-/// Inspect a wasmtime error to decide which neutral trap kind it
-/// belongs to. Pure function — operates on the error's downcast chain
-/// only, no frontend state required.
-fn classify_trap(err: &wasmtime::Error) -> TrapClass {
-    if err.downcast_ref::<TimeoutTrap>().is_some() {
-        TrapClass::Timeout
-    } else if err.downcast_ref::<MemoryLimitTrap>().is_some() {
-        TrapClass::MemoryLimit
-    } else {
-        TrapClass::Other
-    }
-}
-
-/// Classify a wasmtime call error into a neutral `Trap`. The ABI export
-/// symbol (`__kobako_eval` / `__kobako_run`) is deliberately omitted from
-/// the message — the Sandbox layer attaches the user-facing verb
+/// Classify a wasmtime call error into a neutral `Trap`. Pure function
+/// over the error's downcast chain, so the kind routing is exercisable
+/// from `cargo test` without any frontend. The ABI export symbol
+/// (`__kobako_eval` / `__kobako_run`) is deliberately omitted from the
+/// message — the Sandbox layer attaches the user-facing verb
 /// (`Sandbox#eval` / `Sandbox#run`) so the message reads in caller
 /// vocabulary rather than ABI vocabulary.
 ///
-/// For the configured-cap paths (`TrapClass::Timeout` /
-/// `TrapClass::MemoryLimit`) the trap's own `std::fmt::Display`
+/// For the configured-cap paths the trap's own `std::fmt::Display`
 /// carries the user-facing reason (`"wall-clock deadline exceeded"`,
-/// `"linear memory growth exceeded memory_limit: ..."`). The wasmtime
-/// outer wrapper at `format!("{err}")` would otherwise surface only
-/// the `"error while executing at wasm backtrace: ..."` framing, which
-/// is operator noise on a cap trap. For `TrapClass::Other` the framing
-/// is kept but the chain's root cause is appended (see
-/// `other_trap_message`) so the real trap reason survives.
+/// `"linear memory growth exceeded memory_limit: ..."`); the wasmtime
+/// outer wrapper would otherwise surface only the `"error while
+/// executing at wasm backtrace: ..."` framing, which is operator noise
+/// on a cap trap. For any other error the framing is kept but the
+/// chain's root cause is appended (see `other_trap_message`) so the
+/// real trap reason survives.
 pub(crate) fn trap_from(err: wasmtime::Error) -> Trap {
-    match classify_trap(&err) {
-        TrapClass::Timeout => Trap::Timeout(
-            err.downcast_ref::<TimeoutTrap>()
-                .map(|t| t.to_string())
-                .unwrap_or_else(|| format!("{err}")),
-        ),
-        TrapClass::MemoryLimit => Trap::MemoryLimit(
-            err.downcast_ref::<MemoryLimitTrap>()
-                .map(|t| t.to_string())
-                .unwrap_or_else(|| format!("{err}")),
-        ),
-        TrapClass::Other => Trap::Other(other_trap_message(&err)),
+    if let Some(t) = err.downcast_ref::<TimeoutTrap>() {
+        Trap::Timeout(t.to_string())
+    } else if let Some(t) = err.downcast_ref::<MemoryLimitTrap>() {
+        Trap::MemoryLimit(t.to_string())
+    } else {
+        Trap::Other(other_trap_message(&err))
     }
 }
 
@@ -129,8 +98,9 @@ pub(crate) fn instantiate_err(err: wasmtime::Error) -> SetupError {
 
 #[cfg(test)]
 mod tests {
-    use super::{classify_trap, other_trap_message, TrapClass, NO_TIMEOUT_EPOCH_DELTA};
+    use super::{other_trap_message, trap_from, NO_TIMEOUT_EPOCH_DELTA};
     use crate::invocation::{Invocation, MemoryLimitTrap, TimeoutTrap};
+    use kobako_runtime::error::Trap;
 
     // The no-timeout priming delta is added to the engine's current
     // epoch inside wasmtime, and the process-wide ticker advances that
@@ -148,21 +118,24 @@ mod tests {
     }
 
     #[test]
-    fn classify_trap_routes_timeout_trap_to_timeout() {
+    fn trap_from_routes_timeout_trap_to_timeout() {
         let err = wasmtime::Error::new(TimeoutTrap);
-        assert_eq!(classify_trap(&err), TrapClass::Timeout);
+        let expected = TimeoutTrap.to_string();
+        assert!(matches!(trap_from(err), Trap::Timeout(msg) if msg == expected));
     }
 
     #[test]
-    fn classify_trap_routes_memory_limit_trap_to_memory_limit() {
-        let err = wasmtime::Error::new(MemoryLimitTrap::new(1 << 20, 1 << 19));
-        assert_eq!(classify_trap(&err), TrapClass::MemoryLimit);
+    fn trap_from_routes_memory_limit_trap_to_memory_limit() {
+        let trap = MemoryLimitTrap::new(1 << 20, 1 << 19);
+        let expected = trap.to_string();
+        let err = wasmtime::Error::new(trap);
+        assert!(matches!(trap_from(err), Trap::MemoryLimit(msg) if msg == expected));
     }
 
     #[test]
-    fn classify_trap_falls_back_to_other_for_unknown_errors() {
+    fn trap_from_falls_back_to_other_for_unknown_errors() {
         let err = wasmtime::Error::msg("some other wasmtime fault");
-        assert_eq!(classify_trap(&err), TrapClass::Other);
+        assert!(matches!(trap_from(err), Trap::Other(_)));
     }
 
     // A guest hard trap reaches the host as a wasmtime error whose Display is

data/ext/kobako/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "kobako"
-version = "0.14.0"
+version = "0.15.0"
 edition = "2021"
 authors = ["Aotokitsuruya <contact@aotoki.me>"]
 license = "Apache-2.0"

data/ext/kobako/src/runtime/errors.rs

@@ -55,48 +55,15 @@ pub(super) fn trap_err(ruby: &Ruby, msg: impl Into<String>) -> MagnusError {
     error_in(ruby, &TRAP_ERROR, msg)
 }
 
-/// Construct a `Kobako::SetupError` magnus error. Used for every
-/// construction-time failure on the `Runtime.from_path` path before any
-/// invocation runs — unreadable artifact, bytes that are not a valid Wasm
-/// module, or engine / linker / instantiation setup failure. The
-/// `ModuleNotBuiltError` subclass (artifact absent) is
-/// raised through `MODULE_NOT_BUILT_ERROR` directly.
-pub(super) fn setup_err(ruby: &Ruby, msg: impl Into<String>) -> MagnusError {
-    error_in(ruby, &SETUP_ERROR, msg)
-}
-
-/// Construct a `Kobako::TimeoutError` magnus error. Surfaces the
-/// wall-clock cap path with the verb prefix added
-/// by `Kobako::Sandbox#invoke!`.
-fn timeout_err(ruby: &Ruby, msg: impl Into<String>) -> MagnusError {
-    error_in(ruby, &TIMEOUT_ERROR, msg)
-}
-
-/// Construct a `Kobako::MemoryLimitError` magnus error. Surfaces the
-/// linear-memory cap path with the verb prefix
-/// added by `Kobako::Sandbox#invoke!`.
-fn memory_limit_err(ruby: &Ruby, msg: impl Into<String>) -> MagnusError {
-    error_in(ruby, &MEMORY_LIMIT_ERROR, msg)
-}
-
-/// Construct a `Kobako::SandboxError` magnus error. Used for the
-/// host-side pre-call faults the SPEC attributes to the sandbox / wire
-/// layer rather than the Wasm engine — currently the `#run` invocation
-/// envelope reservation failure (`__kobako_alloc` returns 0).
-/// The runtime is intact, so this must not be a
-/// `TrapError`: no discard-and-recreate recovery is owed to the caller.
-fn sandbox_err(ruby: &Ruby, msg: impl Into<String>) -> MagnusError {
-    error_in(ruby, &SANDBOX_ERROR, msg)
-}
-
 /// Map a neutral `Trap` onto its `Kobako::TrapError`-family Ruby exception.
 /// The boundary between the magnus-free run mechanics and the Ruby surface:
 /// the run path classifies a fault into a `Trap`, and this is where it
-/// becomes a raised exception.
+/// becomes a raised exception. The verb prefix (`Sandbox#eval` / `#run`)
+/// is added by `Kobako::Sandbox#invoke!`.
 pub(super) fn trap_to_magnus(ruby: &Ruby, trap: Trap) -> MagnusError {
     match trap {
-        Trap::Timeout(msg) => timeout_err(ruby, msg),
-        Trap::MemoryLimit(msg) => memory_limit_err(ruby, msg),
+        Trap::Timeout(msg) => error_in(ruby, &TIMEOUT_ERROR, msg),
+        Trap::MemoryLimit(msg) => error_in(ruby, &MEMORY_LIMIT_ERROR, msg),
         Trap::Other(msg) => trap_err(ruby, msg),
     }
 }
@@ -106,8 +73,11 @@ pub(super) fn trap_to_magnus(ruby: &Ruby, trap: Trap) -> MagnusError {
 pub(super) fn setup_to_magnus(ruby: &Ruby, err: SetupError) -> MagnusError {
     match err {
         SetupError::ModuleNotBuilt(msg) => error_in(ruby, &MODULE_NOT_BUILT_ERROR, msg),
-        SetupError::Dead(msg) => setup_err(ruby, msg),
-        SetupError::Intact(msg) => sandbox_err(ruby, msg),
+        SetupError::Dead(msg) => error_in(ruby, &SETUP_ERROR, msg),
+        // Runtime intact means a host-side pre-call fault the SPEC
+        // attributes to the sandbox / wire layer, not the engine — no
+        // discard-and-recreate recovery is owed, so never a TrapError.
+        SetupError::Intact(msg) => error_in(ruby, &SANDBOX_ERROR, msg),
     }
 }
 

data/ext/kobako/src/runtime.rs

@@ -53,26 +53,14 @@ fn rstring_to_vec(s: RString) -> Vec<u8> {
     unsafe { s.as_slice() }.to_vec()
 }
 
-/// The pre-invocation sentinel for one capture channel: no bytes, cap
-/// not reached. Fresh `Vec`s per call because `Capture` owns its buffer.
-fn empty_capture() -> Capture {
-    Capture {
-        bytes: Vec::new(),
-        truncated: false,
-    }
-}
-
 // ---------------------------------------------------------------------------
 // Ruby init
 // ---------------------------------------------------------------------------
 
 pub fn init(ruby: &Ruby, kobako: RModule) -> Result<(), MagnusError> {
-    // Error hierarchy lives in `lib/kobako/errors.rb` (top-level
-    // `Kobako::TrapError` / `TimeoutError` / `MemoryLimitError` /
-    // `SetupError` / `ModuleNotBuiltError`). The ext raises directly into
-    // those classes through `trap_err` / `timeout_err` / `memory_limit_err`
-    // / `sandbox_err` / `setup_err` / `MODULE_NOT_BUILT_ERROR`; no
-    // intermediate hierarchy is registered.
+    // Error hierarchy lives in `lib/kobako/errors.rb`; the ext raises
+    // directly into those classes through the constructors and mappers
+    // in `runtime/errors.rs` — no intermediate hierarchy is registered.
 
     let runtime = kobako.define_class("Runtime", ruby.class_object())?;
     runtime.define_singleton_method("from_path", function!(Runtime::from_path, 6))?;
@@ -210,11 +198,8 @@ impl Runtime {
         Ok(Self {
             driver,
             on_dispatch: Cell::new(None),
-            last_usage: Cell::new(Usage {
-                wall_time: 0.0,
-                memory_peak: 0,
-            }),
-            last_captures: RefCell::new((empty_capture(), empty_capture())),
+            last_usage: Cell::new(Usage::default()),
+            last_captures: RefCell::new((Capture::default(), Capture::default())),
         })
     }
 

data/lib/kobako/catalog/handles.rb

@@ -6,7 +6,7 @@ module Kobako
   module Catalog
     # Host-side mapping from opaque integer Handle IDs to Ruby objects.
     # The table is owned by +Kobako::Sandbox+ and injected
-    # into the per-Sandbox +Kobako::Catalog::Namespaces+ so guest→host dispatch
+    # into the per-Sandbox +Kobako::Catalog::Services+ so guest→host dispatch
     # resolves Handle targets and arguments against the same table that
     # host→guest wire encoding allocates into.
     #

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

@@ -44,7 +44,7 @@ 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
+      # 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
@@ -31,7 +31,7 @@ module Kobako
       # 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+
@@ -54,7 +54,7 @@ module Kobako
       # 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+
+      # 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,8 +13,8 @@ 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;
     # there is no buffer accumulator and no streaming write API. Callers
@@ -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/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