kobako 0.5.0-x86_64-linux

data/lib/kobako/codec/factory.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+require "singleton"
+require "forwardable"
+require "msgpack"
+
+require_relative "error"
+require_relative "utils"
+require_relative "../handle"
+require_relative "../fault"
+
+module Kobako
+  module Codec
+    # Cached +MessagePack::Factory+ that owns the kobako wire ext-type
+    # registration ({docs/wire-codec.md}[link:../../../docs/wire-codec.md]
+    # § Ext Types).
+    #
+    # The factory is the single place in the host gem that touches the
+    # msgpack API — both {Encoder} and {Decoder} delegate through it, so
+    # the three kobako ext codes (0x00 Symbol, 0x01 Capability Handle,
+    # 0x02 Exception envelope) are configured exactly once at first use.
+    #
+    # Lifecycle is owned by +Singleton+ from the Ruby standard library:
+    # +Factory.instance+ is lazy, thread-safe, and process-wide. Class-level
+    # +Factory.dump+ / +Factory.load+ shortcuts are exposed via
+    # +SingleForwardable+ so callers do not have to spell the +.instance+
+    # hop at every call site; the instance-level +#dump+ / +#load+ are in
+    # turn delegated to the wrapped +MessagePack::Factory+ via +Forwardable+.
+    class Factory
+      include Singleton
+      extend Forwardable
+      extend SingleForwardable
+
+      # MessagePack ext type code reserved for Symbol
+      # ({docs/wire-codec.md}[link:../../../docs/wire-codec.md] § Ext Types
+      # → ext 0x00). Class-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). Class-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). Class-private — mirrors +codec::EXT_ERRENV+ on the
+      # Rust side.
+      EXT_ERRENV = 0x02
+      private_constant :EXT_SYMBOL, :EXT_HANDLE, :EXT_ERRENV
+
+      # Instance-level pass-through onto the wrapped +MessagePack::Factory+.
+      # Spelled +def_instance_delegators+ rather than +def_delegators+ because
+      # the class also extends +SingleForwardable+ (see the +extend+ block
+      # above), which defines its own +def_delegators+ that shadows
+      # +Forwardable+'s — the unambiguous forms keep both delegation tiers
+      # wired to the right scope.
+      def_instance_delegators :@factory, :dump, :load
+
+      # Class-level shortcuts so callers can write +Factory.dump(v)+ instead
+      # of +Factory.instance.dump(v)+; both resolve to the same singleton.
+      def_single_delegators :instance, :dump, :load
+
+      def initialize
+        @factory = MessagePack::Factory.new
+        register_symbol
+        register_handle
+        register_fault
+      end
+
+      private
+
+      def register_symbol
+        @factory.register_type(
+          EXT_SYMBOL, Symbol,
+          packer: method(:pack_symbol),
+          unpacker: method(:unpack_symbol)
+        )
+      end
+
+      # Symbol-to-name packer — extracted to a real method so Steep can
+      # resolve the proc shape without tripping on +lambda(&:name)+'s
+      # +Symbol#to_proc+ inference path.
+      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
+
+      def register_handle
+        @factory.register_type(
+          EXT_HANDLE, Kobako::Handle,
+          packer: ->(handle) { [handle.id].pack("N") },
+          unpacker: ->(payload) { unpack_handle(payload) }
+        )
+      end
+
+      def register_fault
+        @factory.register_type(
+          EXT_ERRENV, Kobako::Fault,
+          packer: ->(fault) { pack_fault(fault) },
+          unpacker: ->(payload) { unpack_fault(payload) }
+        )
+      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.
+      def unpack_handle(payload)
+        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 +factory.dump+) 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 via the cached singleton.
+      def pack_fault(fault)
+        Encoder.encode("type" => fault.type, "message" => fault.message, "details" => fault.details)
+      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
+      # +factory.load+) so the embedded +str+ payloads flow through the
+      # same UTF-8 validation as a top-level decode.
+      #
+      # This establishes a runtime cycle Factory → Decoder → Factory: the
+      # singleton instance feeds +Decoder.decode+, which re-enters this
+      # method when a nested ext 0x02 appears inside +details+. The recursion
+      # is bounded by msgpack nesting depth — identical to nested Array /
+      # Hash payloads — so no extra guard is needed. Do not switch back to
+      # +factory.load+ to "simplify": that path bypasses UTF-8 validation
+      # and re-opens the Decoder's special case for Fault (removed in M5).
+      def unpack_fault(payload)
+        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
+  end
+end

data/lib/kobako/codec/utils.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require_relative "error"
+require_relative "../handle"
+
+module Kobako
+  module Codec
+    # Codec helpers shared by the host-side encoders and decoders.
+    # Three concerns live here today:
+    #
+    #   - 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 {Factory}
+    #     when validating the +ext 0x00+ Symbol payload.
+    #   - +ArgumentError+ translation at the codec boundary
+    #     ({with_boundary}) so the public taxonomy stays
+    #     {Kobako::Codec::Error}.
+    #   - Representability predicate ({representable?}) and the symmetric
+    #     host→guest +#run+ argument walk ({deep_wrap}) used by
+    #     +Kobako::Transport::Run#encode+ to route non-representable leaves
+    #     through the Sandbox's +Kobako::Catalog::Handles+
+    #     ({docs/behavior.md B-34}[link:../../../docs/behavior.md]).
+    #
+    # All helpers are pure — they only inspect inputs, never mutate
+    # them — except {deep_wrap}, whose only side effect is allocating
+    # new Handle ids into the supplied table.
+    module Utils
+      module_function
+
+      # Raise {InvalidEncoding} 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)
+        return if string.valid_encoding?
+
+        raise InvalidEncoding, "#{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 {InvalidType} so the public taxonomy
+      # stays {Kobako::Codec::Error} and never leaks +ArgumentError+ from
+      # the Ruby standard library.
+      #
+      # Most construction sites no longer reach for this directly: a value
+      # object built inside a {Decoder.decode} block has its
+      # +ArgumentError+ mapped to {InvalidType} by the decoder's own
+      # rescue. The lone remaining caller is {Factory#unpack_handle}, which
+      # builds +Handle.restore+ from a raw 4-byte fixext payload without a
+      # {Decoder.decode} call. Do not use it for general-purpose validation
+      # outside the codec boundary — host-layer +ArgumentError+ values
+      # should propagate unchanged.
+      def with_boundary
+        yield
+      rescue ::ArgumentError => e
+        raise InvalidType, e.message
+      end
+
+      # Inclusive Integer range the msgpack gem encodes without raising
+      # +RangeError+ at encode time — signed +int 64+ minimum through
+      # 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
+      # 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
+      # represents a different concept entirely.
+      MSGPACK_INT_RANGE = (-(2**63)..((2**64) - 1))
+
+      # Codec-type predicate
+      # ({docs/wire-codec.md}[link:../../../docs/wire-codec.md] § Type
+      # Mapping). Returns +true+ when +value+ belongs to the closed
+      # 12-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 {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+
+      # allocated from +handler+
+      # ({docs/behavior.md B-34}[link:../../../docs/behavior.md]). 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.
+      #
+      # +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.
+      #
+      # The block bodies spell +Utils.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 +Utils+ at definition time, but the qualified form keeps
+      # the dispatch readable when the recursive call sits inside a
+      # Proc captured from elsewhere).
+      def deep_wrap(value, handler)
+        case value
+        when ::Array then value.map { |element| Utils.deep_wrap(element, handler) }
+        when ::Hash  then value.transform_values { |val| Utils.deep_wrap(val, handler) }
+        else
+          representable?(value) ? value : handler.alloc(value)
+        end
+      end
+
+      # Predicate split out of {representable?} for cyclomatic
+      # budget — the closed-set non-container branch. 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
+        end
+      end
+
+      # Predicate split out of {representable?} for cyclomatic
+      # budget — the container branch. 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)
+        case value
+        when ::Array then value.all? { |element| Utils.representable?(element) }
+        when ::Hash  then value.all? { |key, val| Utils.representable?(key) && Utils.representable?(val) }
+        else false
+        end
+      end
+    end
+  end
+end

data/lib/kobako/codec.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative "codec/error"
+
+module Kobako
+  # Host-side MessagePack codec for the kobako wire contract — the
+  # byte-level layer ({docs/wire-codec.md}[link:../../docs/wire-codec.md]).
+  # Two consumers sit on top:
+  # +Kobako::Transport+ pins the host↔guest framing (Request / Response /
+  # Run / Yield) and +Kobako::Outcome+ owns the per-+#run+ outcome
+  # envelope (Result body / Panic map). The ext-type leaves this layer
+  # carries — +Kobako::Handle+ (0x01) and +Kobako::Fault+ (0x02) — live at
+  # the kobako root so the codec can register them without depending
+  # upward on Transport.
+  #
+  # Backed by the official +msgpack+ gem via {Factory}; {Encoder} and
+  # {Decoder} are thin wrappers that register the three kobako-specific
+  # ext types (0x00 Symbol, 0x01 Capability Handle, 0x02 Exception
+  # envelope) on a single +MessagePack::Factory+ instance. The Rust side
+  # mirrors this layer as the +codec+ module in the +kobako-wasm+ crate;
+  # the ext-code constants live as module-private values on {Factory}
+  # alongside +codec::EXT_SYMBOL+ / +codec::EXT_HANDLE+ /
+  # +codec::EXT_ERRENV+ on that side.
+  module Codec
+  end
+end
+
+require_relative "codec/utils"
+require_relative "codec/factory"
+require_relative "codec/encoder"
+require_relative "codec/decoder"

data/lib/kobako/errors.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+# Top-level Kobako namespace.
+module Kobako
+  # Error taxonomy (docs/behavior.md § Error Scenarios).
+  #
+  # Every `Kobako::Sandbox` invocation (`#eval` or `#run`) either returns a value or raises
+  # exactly one of three invocation-outcome classes. Attribution is decided after the
+  # guest binary returns control to the host (docs/behavior.md
+  # "Step 1 — Wasm trap" then "Step 2 — Outcome envelope tag").
+  #
+  # Three invocation-outcome branches:
+  #
+  #   * {TrapError}     — Wasm engine layer (trap, OOM, unreachable, or a
+  #                       wire-violation fallback signalling a corrupted
+  #                       guest runtime).
+  #   * {SandboxError}  — sandbox / wire layer (mruby script error,
+  #                       wire-decode failure on an otherwise valid tag,
+  #                       Catalog::Handles exhaustion, output buffer overrun).
+  #   * {ServiceError}  — service / capability layer (a Service capability
+  #                       call that failed and was not rescued inside the
+  #                       script).
+  #
+  # A fourth branch sits outside the invocation taxonomy:
+  #
+  #   * {SetupError}    — construction layer. Raised by `Kobako::Sandbox.new`
+  #                       when the wasm runtime cannot be built from the
+  #                       configured +wasm_path+ before any invocation runs
+  #                       (docs/behavior.md E-40 / E-41). Not an invocation
+  #                       outcome, so it never passes through the two-step
+  #                       attribution decision.
+  #
+  # Subclasses pinned by docs/behavior.md Error Classes:
+  #
+  #   * {ModuleNotBuiltError} < {SetupError} — Guest Binary artifact absent
+  #                       at +wasm_path+ (E-40).
+  #   * {HandlerExhaustedError} < {SandboxError} — Handle id cap hit (B-21).
+
+  # Base for all kobako-raised errors so callers that want to ignore the
+  # taxonomy can rescue a single class.
+  class Error < StandardError; end
+
+  # Wasm engine layer. Raised when the Wasm execution engine crashed
+  # (trap, OOM, unreachable) or when the wire layer detected a structural
+  # violation that signals a corrupted guest execution environment
+  # (zero-length OUTCOME_BUFFER, unknown outcome tag — SPEC E-02 / E-03).
+  #
+  # Two named subclasses cover the configured per-invocation caps from B-01:
+  #
+  #   * {TimeoutError}     — wall-clock +timeout+ exceeded (E-19).
+  #   * {MemoryLimitError} — guest +memory.grow+ would exceed
+  #                          +memory_limit+ (E-20).
+  #
+  # Host Apps that only care about "guest is unrecoverable, discard the
+  # Sandbox" can rescue +TrapError+ and ignore the subclass; Host Apps that
+  # want to surface a specific reason to operators can rescue the subclass
+  # first.
+  class TrapError < Error; end
+
+  # Wall-clock timeout cap exhausted. {docs/behavior.md E-19}[link:../../docs/behavior.md]:
+  # the absolute deadline +entry_time + timeout+ passed and the next guest
+  # wasm safepoint trapped. The Sandbox is unrecoverable after this point;
+  # discard and recreate before another execution.
+  class TimeoutError < TrapError; end
+
+  # Linear-memory cap exhausted. {docs/behavior.md E-20}[link:../../docs/behavior.md]:
+  # a guest +memory.grow+ would have pushed linear memory past the
+  # configured +memory_limit+. The Sandbox is unrecoverable after this
+  # point; discard and recreate before another execution.
+  class MemoryLimitError < TrapError; end
+
+  # Construction-layer error raised by +Kobako::Sandbox.new+ /
+  # +Kobako::Runtime.from_path+ when the wasm runtime cannot be built
+  # from the configured +wasm_path+ before any invocation runs —
+  # an unreadable artifact, bytes that are not a valid Wasm module, or
+  # engine / linker / instantiation setup failure
+  # ({docs/behavior.md E-41}[link:../../docs/behavior.md]). Construction
+  # is not an invocation, so +SetupError+ sits beside the invocation
+  # taxonomy under +Kobako::Error+ rather than under +TrapError+: no
+  # Sandbox is produced, so the +TrapError+ "discard and recreate"
+  # recovery contract does not apply.
+  class SetupError < Error; end
+
+  # The named +SetupError+ subclass for the common, actionable case:
+  # the Guest Binary artifact is absent at +wasm_path+ — the pre-build
+  # state on a fresh clone before +bundle exec rake compile+
+  # ({docs/behavior.md E-40}[link:../../docs/behavior.md]). Host Apps
+  # that only need "the Sandbox could not be set up" rescue +SetupError+;
+  # those wanting to special-case the unbuilt-artifact state rescue
+  # +ModuleNotBuiltError+ first.
+  class ModuleNotBuiltError < SetupError; end
+
+  # Sandbox / wire layer. Raised when the guest ran to completion but
+  # execution failed due to a mruby script error, a protocol fault, or a
+  # host-side wire decode failure on an otherwise valid outcome tag.
+  class SandboxError < Error
+    attr_reader :origin, :klass, :backtrace_lines, :details
+
+    def initialize(message, origin: nil, klass: nil, backtrace_lines: nil, details: nil)
+      super(message)
+      @origin = origin
+      @klass = klass
+      @backtrace_lines = backtrace_lines
+      @details = details
+    end
+  end
+
+  # Service layer. Raised when a Service capability call inside a mruby
+  # script reported an application-level failure that the script did not
+  # rescue.
+  class ServiceError < Error
+    attr_reader :origin, :klass, :backtrace_lines, :details
+
+    def initialize(message, origin: nil, klass: nil, backtrace_lines: nil, details: nil)
+      super(message)
+      @origin = origin
+      @klass = klass
+      @backtrace_lines = backtrace_lines
+      @details = details
+    end
+  end
+
+  # docs/behavior.md Error Classes: HandlerExhaustedError is the canonical
+  # SandboxError subclass for the id-cap-hit path (B-21). Raised when the
+  # per-invocation Handle ID counter in Catalog::Handles reaches
+  # +0x7fff_ffff+ (2³¹ − 1) and further allocation would exceed the cap.
+  class HandlerExhaustedError < SandboxError; end
+
+  # docs/behavior.md Error Classes: BytecodeError is the SandboxError
+  # subclass raised when a `#preload(binary:)` snippet fails structural
+  # validation during the first invocation's snippet replay against a
+  # fresh `mrb_state` (E-37 RITE version mismatch, E-38 corrupt body).
+  # Bytecode that loads cleanly and then raises at top level is E-36
+  # and surfaces as plain `SandboxError` with the natural mruby class
+  # preserved. Inherits from SandboxError so a single
+  # `rescue Kobako::SandboxError` covers both source and bytecode
+  # snippet failures while callers wanting bytecode-specific handling
+  # can `rescue Kobako::BytecodeError` directly.
+  class BytecodeError < SandboxError; end
+end

data/lib/kobako/fault.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Kobako
+  # Wire-level value object for an ext-0x02 Exception envelope.
+  #
+  # Top-level shared wire primitive: like +Kobako::Handle+ (ext 0x01),
+  # +Fault+ is a MessagePack ext-type leaf registered by
+  # +Kobako::Codec::Factory+ and rides nested inside other envelopes (a
+  # +Kobako::Transport::Response+ error payload, or another Fault's
+  # +details+). It lives at the kobako root rather than under +Transport+
+  # because the Codec layer must register it, and Codec must not depend
+  # upward on Transport.
+  #
+  # SPEC pins the payload
+  # ({docs/wire-codec.md}[link:../../docs/wire-codec.md] § Ext Types
+  # → ext 0x02) to a msgpack map with exactly three keys:
+  #   * "type"    — one of "runtime", "argument", "undefined"
+  #   * "message" — human-readable string
+  #   * "details" — any wire-legal value, or nil when absent
+  #
+  # This object holds the *encoded* form. Reifying the corresponding Ruby
+  # exception class (RuntimeError, ArgumentError, Kobako::ServiceError, ...)
+  # is the responsibility of the dispatch layer, not the codec.
+  #
+  # Built on the +class X < Data.define(...)+ subclass form so the
+  # class body is fully Steep-visible; ruby/rbs upstream documents
+  # this as the Steep-friendly shape and the +Style/DataInheritance+
+  # cop is disabled on that basis (see +.rubocop.yml+).
+  class Fault < Data.define(:type, :message, :details)
+    VALID_TYPES = %w[runtime argument undefined].freeze
+
+    def initialize(type:, message:, details: nil)
+      raise ArgumentError, "type must be String"    unless type.is_a?(String)
+      raise ArgumentError, "message must be String" unless message.is_a?(String)
+      raise ArgumentError, "type=#{type.inspect} not one of #{VALID_TYPES.inspect}" unless VALID_TYPES.include?(type)
+
+      super
+    end
+  end
+end

data/lib/kobako/handle.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Kobako
+  # Wire-level value object for an ext-0x01 Capability Handle, used in both
+  # directions across the Sandbox boundary: as a Service method's return
+  # value (guest→host return path; {docs/behavior.md B-14}[link:../../docs/behavior.md])
+  # and as a +#run+ argument auto-wrapped by the host
+  # ({docs/behavior.md B-34}[link:../../docs/behavior.md]).
+  #
+  # SPEC pins the binary layout to fixext 4 with a 4-byte big-endian u32
+  # payload ({docs/wire-codec.md}[link:../../docs/wire-codec.md]
+  # § Ext Types → ext 0x01). ID 0 is reserved as the invalid sentinel;
+  # the maximum valid ID is 0x7fff_ffff (2^31 - 1).
+  #
+  # The constructor is internal to the Host Gem. +Kobako::Handle.new+ is
+  # privatised so Host App code cannot fabricate a Handle from a bare
+  # integer; legitimate Handle instances enter Host App code only as
+  # fields on raised error objects. The Host Gem itself constructs
+  # Handles through {.restore}, which exists at exactly two call
+  # sites: +Kobako::Codec::Factory#unpack_handle+ (wire decode) and
+  # +Kobako::Codec::Utils.deep_wrap+ / +Kobako::Transport::Dispatcher#wrap_as_handle+
+  # (allocator paths). Both live inside +lib/kobako/+ and are not part
+  # of any public surface.
+  #
+  # The mruby counterpart +Kobako::Handle+ lives inside the Wasm guest
+  # under the same canonical name and shares neither code nor instances
+  # with this host-side class.
+  class Handle < Data.define(:id)
+    # Inclusive lower bound on the wire Handle ID. ID 0 is reserved as
+    # the invalid sentinel and is never allocated.
+    MIN_ID = 1
+    # Inclusive upper bound on the wire Handle ID. The cap matches the
+    # u32 signed-positive range so Handle IDs fit in a signed integer
+    # on either side of the wire without re-encoding.
+    MAX_ID = 0x7fff_ffff
+
+    def initialize(id:)
+      raise ArgumentError, "Handle id must be Integer" unless id.is_a?(Integer)
+      raise ArgumentError, "Handle id #{id} out of range [#{MIN_ID}, #{MAX_ID}]" unless id.between?(MIN_ID, MAX_ID)
+
+      super
+    end
+
+    private_class_method :new
+
+    # Host Gem–internal factory. Allocates the Data instance through
+    # +Class#allocate+ and dispatches +#initialize+ explicitly so the
+    # invariant checks still run, while keeping the public +.new+
+    # privatised against Host App callers.
+    #
+    # Two collaborators call this: the codec when an ext 0x01 frame is
+    # decoded off the wire, and the allocator paths when a host-side
+    # Ruby object is registered into the Sandbox's +Catalog::Handles+. Both
+    # paths live inside +lib/kobako/+ and treat this method as a
+    # package-private constructor.
+    def self.restore(id)
+      allocate.tap { |handle| handle.send(:initialize, id: id) }
+    end
+  end
+end

data/lib/kobako/namespace.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Kobako
+  # A named grouping of Members for one Sandbox
+  # ({docs/behavior.md B-07..B-11}[link:../../docs/behavior.md]).
+  # Returned by +Sandbox#define+. Each instance owns a flat name→object
+  # table of Members; member binding is validated against {NAME_PATTERN}.
+  class Namespace
+    # Ruby constant-name pattern shared by Namespace and Member names
+    # ({docs/behavior.md B-07/B-08 Notes}[link:../../docs/behavior.md]).
+    NAME_PATTERN = /\A[A-Z]\w*\z/
+
+    attr_reader :name
+
+    # Build a new Namespace. +name+ is an already-validated Namespace
+    # name (must satisfy {NAME_PATTERN}; validation is the caller's
+    # responsibility).
+    def initialize(name)
+      @name = name
+      @members = {} # : Hash[String, untyped]
+    end
+
+    # Bind +object+ under +member+ inside this Namespace. +member+ is a
+    # constant-form name as a +Symbol+ or +String+. +object+ is any Ruby
+    # object that responds to the methods guest code will invoke. Returns
+    # +self+ for chaining. Raises +ArgumentError+ when +member+ does not
+    # match the constant pattern, or a Member of the same name is already
+    # bound ({docs/behavior.md B-11}[link:../../docs/behavior.md]).
+    def bind(member, object)
+      member_str = validate_member_name!(member)
+      raise ArgumentError, "Member #{@name}::#{member_str} is already bound" if @members.key?(member_str)
+
+      @members[member_str] = object
+      self
+    end
+
+    # Member lookup; raises +KeyError+ when no Member is registered
+    # under +member+.
+    def fetch(member)
+      member_str = member.to_s
+      unless @members.key?(member_str)
+        raise KeyError,
+              "no member named #{member_str.inspect} in namespace #{@name.inspect}"
+      end
+
+      @members[member_str]
+    end
+
+    # Structured description for the guest preamble (Frame 1). Returns a
+    # two-element array +[name, member_keys]+ suitable for msgpack encoding.
+    def to_preamble
+      [@name, @members.keys]
+    end
+
+    private
+
+    def validate_member_name!(member)
+      member_str = member.to_s
+      unless NAME_PATTERN.match?(member_str)
+        raise ArgumentError,
+              "MemberName must match #{NAME_PATTERN.inspect} (got #{member.inspect})"
+      end
+
+      member_str
+    end
+  end
+end