kobako 0.3.0 → 0.5.0

data/ext/kobako/src/wasm.rs

@@ -1,125 +0,0 @@
-// Host-side wasmtime wrapper.
-//
-// The only Ruby-visible class is
-//
-//   Kobako::Wasm::Instance — wraps wasmtime::Instance + cached TypedFuncs
-//
-// constructed via `Kobako::Wasm::Instance.from_path(path, timeout, memory_limit,
-// stdout_limit, stderr_limit)`.
-// The underlying wasmtime Engine and compiled Module live in a process-scope
-// cache (see the `cache` submodule) and never surface to Ruby (SPEC.md "Code
-// Organization": `ext/` "exposes no Wasm engine types to the Host App or
-// downstream gems").
-//
-// Module layout (per CLAUDE.md principle #2 — one responsibility per file):
-//
-//   * `cache`       — process-wide Engine + per-path Module cache and the
-//                     process-singleton epoch ticker thread.
-//   * `host_state`  — HostState (per-Store context), StoreCell wrapper, the
-//                     [`KobakoLimiter`] memory cap, and the trap marker
-//                     types ([`TimeoutTrap`] / [`MemoryLimitTrap`]).
-//   * `instance`    — Kobako::Wasm::Instance and its run-path methods.
-//   * `dispatch`    — `__kobako_dispatch` host-import dispatch helpers.
-//
-// This file is the façade: it owns the Ruby error class lazy-resolvers,
-// the `wasm_err` / `timeout_err` / `memory_limit_err` constructors shared
-// by every submodule, and the Ruby init() that registers
-// `Kobako::Wasm::Instance` and its methods.
-
-mod cache;
-mod dispatch;
-mod host_state;
-mod instance;
-
-use magnus::value::Lazy;
-use magnus::{
-    function, method, prelude::*, Error as MagnusError, ExceptionClass, RModule, RString, Ruby,
-};
-
-use instance::Instance;
-
-/// Copy the bytes of +s+ into a fresh +Vec<u8>+. Single safe entry to
-/// what would otherwise be an inline +unsafe { rstring.as_slice() }
-/// .to_vec()+ duplicated at every host-↔-guest boundary. The borrow
-/// does not outlive this call, so no Ruby allocation can move the
-/// underlying RString between the borrow and the copy — the safety
-/// invariant the inline form relied on is established once here.
-pub(crate) fn rstring_to_vec(s: RString) -> Vec<u8> {
-    // SAFETY: see item doc.
-    unsafe { s.as_slice() }.to_vec()
-}
-
-// ---------------------------------------------------------------------------
-// Error classes (lazy-resolved from Ruby once Kobako::Wasm is defined).
-// ---------------------------------------------------------------------------
-
-pub(crate) static MODULE_NOT_BUILT_ERROR: Lazy<ExceptionClass> = Lazy::new(|ruby| {
-    let kobako: RModule = ruby.class_object().const_get("Kobako").unwrap();
-    let wasm: RModule = kobako.const_get("Wasm").unwrap();
-    wasm.const_get("ModuleNotBuiltError").unwrap()
-});
-
-pub(crate) static WASM_ERROR: Lazy<ExceptionClass> = Lazy::new(|ruby| {
-    let kobako: RModule = ruby.class_object().const_get("Kobako").unwrap();
-    let wasm: RModule = kobako.const_get("Wasm").unwrap();
-    wasm.const_get("Error").unwrap()
-});
-
-pub(crate) static WASM_TIMEOUT_ERROR: Lazy<ExceptionClass> = Lazy::new(|ruby| {
-    let kobako: RModule = ruby.class_object().const_get("Kobako").unwrap();
-    let wasm: RModule = kobako.const_get("Wasm").unwrap();
-    wasm.const_get("TimeoutError").unwrap()
-});
-
-pub(crate) static WASM_MEMORY_LIMIT_ERROR: Lazy<ExceptionClass> = Lazy::new(|ruby| {
-    let kobako: RModule = ruby.class_object().const_get("Kobako").unwrap();
-    let wasm: RModule = kobako.const_get("Wasm").unwrap();
-    wasm.const_get("MemoryLimitError").unwrap()
-});
-
-pub(crate) fn wasm_err(ruby: &Ruby, msg: impl Into<String>) -> MagnusError {
-    MagnusError::new(ruby.get_inner(&WASM_ERROR), msg.into())
-}
-
-/// Construct a `Kobako::Wasm::TimeoutError` magnus error. Surfaces the
-/// docs/behavior.md E-19 wall-clock cap path so the Sandbox layer can rewrap it
-/// as `Kobako::TimeoutError`.
-pub(crate) fn timeout_err(ruby: &Ruby, msg: impl Into<String>) -> MagnusError {
-    MagnusError::new(ruby.get_inner(&WASM_TIMEOUT_ERROR), msg.into())
-}
-
-/// Construct a `Kobako::Wasm::MemoryLimitError` magnus error. Surfaces
-/// the docs/behavior.md E-20 linear-memory cap path so the Sandbox layer can
-/// rewrap it as `Kobako::MemoryLimitError`.
-pub(crate) fn memory_limit_err(ruby: &Ruby, msg: impl Into<String>) -> MagnusError {
-    MagnusError::new(ruby.get_inner(&WASM_MEMORY_LIMIT_ERROR), msg.into())
-}
-
-// ---------------------------------------------------------------------------
-// Ruby init
-// ---------------------------------------------------------------------------
-
-pub fn init(ruby: &Ruby, kobako: RModule) -> Result<(), MagnusError> {
-    let wasm = kobako.define_module("Wasm")?;
-
-    // Error hierarchy. ModuleNotBuiltError is the headline error for the
-    // common pre-build state where `data/kobako.wasm` has not yet been
-    // produced (e.g. fresh clone before `rake compile`). TimeoutError and
-    // MemoryLimitError carry the docs/behavior.md B-01 per-run cap paths up to the
-    // Sandbox layer.
-    let base_err = wasm.define_error("Error", ruby.exception_standard_error())?;
-    wasm.define_error("ModuleNotBuiltError", base_err)?;
-    wasm.define_error("TimeoutError", base_err)?;
-    wasm.define_error("MemoryLimitError", base_err)?;
-
-    let instance = wasm.define_class("Instance", ruby.class_object())?;
-    instance.define_singleton_method("from_path", function!(Instance::from_path, 5))?;
-    instance.define_method("server=", method!(Instance::set_server, 1))?;
-    instance.define_method("eval", method!(Instance::eval, 3))?;
-    instance.define_method("run", method!(Instance::run, 3))?;
-    instance.define_method("stdout", method!(Instance::stdout, 0))?;
-    instance.define_method("stderr", method!(Instance::stderr, 0))?;
-    instance.define_method("outcome!", method!(Instance::outcome, 0))?;
-
-    Ok(())
-}

data/lib/kobako/invocation.rb

@@ -1,112 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "rpc/handle"
-require_relative "codec"
-
-module Kobako
-  # Host-side value object for a single +Sandbox#run+ invocation
-  # ({docs/wire-codec.md Invocation channels}[link:../../docs/wire-codec.md];
-  # {docs/behavior.md B-31}[link:../../docs/behavior.md]).
-  #
-  # An Invocation captures the host-layer concept of "a single +#run+
-  # call": the entrypoint constant name plus its positional and keyword
-  # arguments. Host pre-flight (E-24 / E-25 / E-29 / E-30) is enforced at
-  # construction so the Value Object is the single source of truth —
-  # anything that passes +Invocation.new+ is safe to encode and ship to
-  # the guest.
-  #
-  # Invocation sits at top level, not under +Kobako::RPC+: RPC in SPEC is
-  # the guest→host capability channel (Server / Client / Request /
-  # Response / Handle); Invocation is the opposite direction (host→guest
-  # entrypoint dispatch) and structurally rejects Handles (E-29), so it
-  # has no relationship with the HandleTable. The +#encode+ output is the
-  # "Invocation envelope" that ships through the +__kobako_run+ command
-  # buffer.
-  #
-  # Built on the +class X < Data.define(...)+ subclass form (the
-  # Steep-friendly shape — see +lib/kobako/outcome/panic.rb+).
-  class Invocation < Data.define(:entrypoint, :args, :kwargs)
-    # Ruby constant-name pattern enforced on the +entrypoint+ Symbol
-    # ({docs/behavior.md E-25}[link:../../docs/behavior.md]). Parallel to
-    # +Kobako::Snippet::Table::NAME_PATTERN+; the two constants name the
-    # same regex but cover distinct surfaces (snippet identity vs.
-    # entrypoint resolution) so a future divergence stays local.
-    NAME_PATTERN = /\A[A-Z]\w*\z/
-
-    # steep:ignore:start
-    def initialize(entrypoint:, args: [], kwargs: {})
-      super(
-        entrypoint: normalize_entrypoint(entrypoint),
-        args: validate_args!(args),
-        kwargs: validate_kwargs!(kwargs)
-      )
-    end
-    # steep:ignore:end
-
-    # Encode this Invocation to the msgpack bytes the guest's
-    # +__kobako_run+ entry point consumes as its command-buffer payload
-    # ({docs/wire-codec.md Invocation channels}[link:../../docs/wire-codec.md]).
-    # The Value Object's own invariants are the contract; this method
-    # does not re-check the shape. Layout: msgpack map with string keys
-    # +"entrypoint"+ (Symbol via ext 0x00), +"args"+ (Array), +"kwargs"+
-    # (Map with Symbol keys).
-    def encode
-      Codec::Encoder.encode(
-        "entrypoint" => entrypoint,
-        "args" => args,
-        "kwargs" => kwargs
-      )
-    end
-
-    private
-
-    # steep:ignore:start
-    # E-24: target must be a Symbol or String (TypeError, not
-    # ArgumentError — the wrong-type case is a Host App programming
-    # error before the invocation reaches the guest). E-25: after
-    # +.to_s+ the value must match NAME_PATTERN (ArgumentError),
-    # rejecting +::+-segmented names and any non-constant form.
-    def normalize_entrypoint(target)
-      unless target.is_a?(Symbol) || target.is_a?(String)
-        raise TypeError, "Invocation entrypoint must be a Symbol or String, got #{target.class}"
-      end
-
-      target_str = target.to_s
-      unless NAME_PATTERN.match?(target_str)
-        raise ArgumentError,
-              "Invocation entrypoint must match #{NAME_PATTERN.inspect} (got #{target.inspect})"
-      end
-
-      target_str.to_sym
-    end
-
-    # E-29: +args+ must not contain a +Kobako::RPC::Handle+. Handles
-    # are per-invocation and cannot enter the next invocation through
-    # a control-plane channel; a guest that needs to call into a
-    # stateful host object must obtain a fresh Handle through a
-    # Service RPC inside the dispatched entrypoint.
-    def validate_args!(args)
-      raise ArgumentError, "Invocation args must be Array" unless args.is_a?(Array)
-      raise ArgumentError, "Invocation args must not contain a Kobako::RPC::Handle" if args.any?(Kobako::RPC::Handle)
-
-      args
-    end
-
-    # E-30: +kwargs+ keys must be Symbols, mirroring the wire codec's
-    # Request kwargs rule. Validation lives here (not in the codec) so
-    # the Host App sees the host-side error message before any encode
-    # / decode boundary.
-    def validate_kwargs!(kwargs)
-      raise ArgumentError, "Invocation kwargs must be Hash" unless kwargs.is_a?(Hash)
-
-      bad_keys = kwargs.each_key.grep_v(Symbol)
-      unless bad_keys.empty?
-        raise ArgumentError,
-              "Invocation kwargs keys must be Symbols (got #{bad_keys.inspect})"
-      end
-
-      kwargs
-    end
-    # steep:ignore:end
-  end
-end

data/lib/kobako/rpc/dispatcher.rb

@@ -1,169 +0,0 @@
-# frozen_string_literal: true
-
-module Kobako
-  module RPC
-    # Pure-function dispatcher for guest-initiated RPC calls. Decodes a
-    # msgpack-encoded Request envelope, resolves the target object through
-    # the Server (path lookup or HandleTable lookup), invokes the method,
-    # and returns a msgpack-encoded Response envelope.
-    #
-    # The module is stateless — all mutable state is threaded through the
-    # +server+ argument so Dispatcher has no instance variables and no side
-    # effects beyond mutating the HandleTable via +alloc+ when a non-wire-
-    # representable return value must be wrapped ({docs/behavior.md B-14}[link:../../../docs/behavior.md]).
-    #
-    # Entry point:
-    #
-    #   Kobako::RPC::Dispatcher.dispatch(request_bytes, server)
-    #   # => msgpack-encoded Response bytes (never raises)
-    module Dispatcher
-      module_function
-
-      # Internal sentinel raised when target resolution fails. Mapped to
-      # Response.error with type="undefined". Contained at the wire boundary —
-      # not part of the public Kobako error taxonomy
-      # ({docs/behavior.md E-xx}[link:../../../docs/behavior.md]).
-      class UndefinedTargetError < StandardError; end
-
-      # Internal sentinel raised when a Handle target resolves to the
-      # +:disconnected+ sentinel in the HandleTable (ABA protection,
-      # {docs/behavior.md E-14}[link:../../../docs/behavior.md]). Mapped to Response.error with
-      # type="disconnected". Contained at the wire boundary.
-      class DisconnectedTargetError < StandardError; end
-
-      # Dispatch a single RPC request and return the encoded response bytes.
-      # Called by +Kobako::RPC::Server#dispatch+ which is invoked from the
-      # Rust ext inside +__kobako_dispatch+. +request_bytes+ is the
-      # msgpack-encoded Request envelope. +server+ is the live Server for
-      # this run, used to resolve path-based targets via +#lookup+ and to
-      # access the +#handle_table+ for Handle-based targets and return-value
-      # wrapping. Always returns a binary String — never raises. Any failure
-      # during decode, lookup, or method invocation is reified as a
-      # Response.error envelope so the guest sees the failure as a normal RPC
-      # error rather than a wasm trap
-      # ({docs/behavior.md B-12}[link:../../../docs/behavior.md]).
-      def dispatch(request_bytes, server)
-        request = Kobako::RPC.decode_request(request_bytes)
-        handle_table = server.handle_table
-        target = resolve_target(request.target, server, handle_table)
-        args = request.args.map { |v| resolve_arg(v, handle_table) }
-        kwargs = request.kwargs.transform_values { |v| resolve_arg(v, handle_table) }
-        value = invoke(target, request.method_name, args, kwargs)
-        encode_ok(value, server)
-      rescue StandardError => e
-        encode_caught_error(e)
-      end
-
-      # Map an error caught at the dispatch boundary to a +Response.error+
-      # envelope. +error+ is the +StandardError+ caught by {#dispatch}'s
-      # rescue. Returns a msgpack-encoded Response envelope (binary). Four
-      # error buckets ({docs/behavior.md B-12}[link:../../../docs/behavior.md]):
-      # +Kobako::Codec::Error+ → type="runtime" (wire decode failed);
-      # +DisconnectedTargetError+ → type="disconnected" (E-14);
-      # +UndefinedTargetError+ → type="undefined" (E-13); +ArgumentError+ →
-      # type="argument" (B-12 arity mismatch); everything else →
-      # type="runtime".
-      def encode_caught_error(error)
-        case error
-        when Kobako::Codec::Error then encode_error("runtime", "wire decode failed: #{error.message}")
-        when DisconnectedTargetError then encode_error("disconnected", error.message)
-        when UndefinedTargetError    then encode_error("undefined", error.message)
-        when ArgumentError           then encode_error("argument", error.message)
-        else                              encode_error("runtime", "#{error.class}: #{error.message}")
-        end
-      end
-
-      # Dispatch +method+ on +target+. +kwargs+ is already Symbol-keyed
-      # (the +Envelope::Request+ invariant pins it). The empty-kwargs
-      # branch omits the +**+ splat so Ruby 3.x's strict kwargs
-      # separation does not reject calls to no-kwarg methods when the
-      # wire carries the uniform empty-map shape.
-      def invoke(target, method, args, kwargs)
-        if kwargs.empty?
-          target.public_send(method.to_sym, *args)
-        else
-          target.public_send(method.to_sym, *args, **kwargs)
-        end
-      end
-
-      # {docs/behavior.md B-16}[link:../../../docs/behavior.md] — An RPC::Handle arriving as a positional or keyword
-      # argument identifies a host-side object previously allocated by a prior
-      # RPC's Handle wrap (B-14). Resolve it back to the Ruby object before
-      # the dispatch reaches +public_send+. A Handle whose entry is the
-      # +:disconnected+ sentinel (E-14) raises DisconnectedTargetError so
-      # the dispatcher emits a Response.error with type="disconnected".
-      def resolve_arg(value, handle_table)
-        case value
-        when Kobako::RPC::Handle
-          require_live_object!(value.id, handle_table)
-        else
-          value
-        end
-      end
-
-      # Resolve a Request target to the Ruby object the Server (or
-      # HandleTable) holds. String targets go through the Server;
-      # Handle targets (ext 0x01) go through the HandleTable.
-      #
-      # Target type is already validated by +RPC.decode_request+
-      # before this method is reached, so no else-branch is needed here —
-      # the wire layer is the system boundary that enforces the invariant.
-      def resolve_target(target, server, handle_table)
-        case target
-        when String
-          resolve_path(target, server)
-        when Kobako::RPC::Handle
-          resolve_handle(target, handle_table)
-        end
-      end
-
-      def resolve_path(path, server)
-        server.lookup(path)
-      rescue KeyError => e
-        raise UndefinedTargetError, e.message
-      end
-
-      def resolve_handle(handle, handle_table)
-        require_live_object!(handle.id, handle_table)
-      end
-
-      # Resolve +id+ through the HandleTable, distinguishing the
-      # +:disconnected+ sentinel (E-14) from an unknown id (E-13).
-      def require_live_object!(id, handle_table)
-        object = handle_table.fetch(id)
-        raise DisconnectedTargetError, "Handle id #{id} is disconnected" if object == :disconnected
-
-        object
-      rescue Kobako::HandleTableError => e
-        raise UndefinedTargetError, e.message
-      end
-
-      # Encode +value+ as a +Response.ok+ envelope. When the value is not
-      # wire-representable per {docs/behavior.md B-13}[link:../../../docs/behavior.md]'s type
-      # mapping, the +UnsupportedType+ rescue routes it through the
-      # HandleTable via {#wrap_as_handle} and re-encodes with the Capability
-      # Handle in place ({docs/behavior.md B-14}[link:../../../docs/behavior.md]). The happy
-      # path encodes exactly once.
-      def encode_ok(value, server)
-        response = Kobako::RPC::Response.ok(value)
-        Kobako::RPC.encode_response(response)
-      rescue Kobako::Codec::UnsupportedType
-        encode_ok(wrap_as_handle(value, server), server)
-      end
-
-      # Allocate +value+ in the Server's HandleTable and return a +Handle+
-      # that the wire codec can carry ({docs/behavior.md B-14}[link:../../../docs/behavior.md]).
-      # Used as the fallback path of {#encode_ok} when +value+ has no wire
-      # representation.
-      def wrap_as_handle(value, server)
-        Kobako::RPC::Handle.new(server.handle_table.alloc(value))
-      end
-
-      def encode_error(type, message)
-        fault = Kobako::RPC::Fault.new(type: type, message: message)
-        response = Kobako::RPC::Response.error(fault)
-        Kobako::RPC.encode_response(response)
-      end
-    end
-  end
-end

data/lib/kobako/rpc/envelope.rb

@@ -1,118 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "handle"
-require_relative "fault"
-require_relative "../codec"
-
-module Kobako
-  # See lib/kobako/rpc.rb for the umbrella module doc; this file owns the
-  # Request / Response value objects and their encode/decode helpers.
-  module RPC
-    # ---------------- Response status bytes (docs/wire-contract.md § Response Shape) ---
-
-    # Response variant marker for the success branch.
-    STATUS_OK    = 0
-    # Response variant marker for the fault branch.
-    STATUS_ERROR = 1
-
-    # Value object for a single guest-initiated RPC Request
-    # ({docs/wire-codec.md Envelope Encoding → Request}[link:../../../docs/wire-codec.md]).
-    #
-    # 4-element msgpack array: +[target, method, args, kwargs]+. +target+
-    # is either a +String+ (+"Namespace::Member"+) or a {Handle}. SPEC pins
-    # +kwargs+ map keys to ext 0x00 Symbol; enforced at construction so the
-    # Value Object is the single source of truth.
-    Request = Data.define(:target, :method_name, :args, :kwargs) do
-      # steep:ignore:start
-      def initialize(target:, method:, args: [], kwargs: {})
-        unless target.is_a?(String) || target.is_a?(Kobako::RPC::Handle)
-          raise ArgumentError, "Request target must be String or Kobako::RPC::Handle, got #{target.class}"
-        end
-        raise ArgumentError, "Request method must be String" unless method.is_a?(String)
-        raise ArgumentError, "Request args must be Array"    unless args.is_a?(Array)
-
-        validate_kwargs!(kwargs)
-        super(target: target, method_name: method, args: args, kwargs: kwargs)
-      end
-
-      private
-
-      def validate_kwargs!(kwargs)
-        raise ArgumentError, "Request kwargs must be Hash" unless kwargs.is_a?(Hash)
-
-        kwargs.each_key do |k|
-          raise ArgumentError, "Request kwargs keys must be Symbol, got #{k.class}" unless k.is_a?(Symbol)
-        end
-      end
-      # steep:ignore:end
-    end
-
-    # Encode a {Request} to msgpack bytes. The Value Object's own
-    # invariants are the contract; this method does not re-check the shape.
-    def self.encode_request(request)
-      Codec::Encoder.encode([request.target, request.method_name, request.args, request.kwargs])
-    end
-
-    def self.decode_request(bytes)
-      arr = Codec::Decoder.decode(bytes)
-      unless arr.is_a?(Array) && arr.length == 4
-        raise Codec::InvalidType, "Request must be a 4-element array, got #{arr.inspect}"
-      end
-
-      target, method_name, args, kwargs = arr
-      Codec::Utils.wire_boundary do
-        Request.new(target: target, method: method_name, args: args, kwargs: kwargs)
-      end
-    end
-
-    # Value object for a single host-side RPC Response
-    # ({docs/wire-codec.md Envelope Encoding → Response}[link:../../../docs/wire-codec.md]).
-    #
-    # 2-element msgpack array: +[status, value-or-fault]+. +status+ is 0
-    # (success) or 1 (fault). For success the second element is the return
-    # value; for fault it is a {Fault} (ext 0x02 envelope).
-    Response = Data.define(:status, :payload) do
-      # steep:ignore:start
-      def self.ok(value)
-        new(status: STATUS_OK, payload: value)
-      end
-
-      def self.error(fault)
-        unless fault.is_a?(Kobako::RPC::Fault)
-          raise ArgumentError, "Response.error requires Kobako::RPC::Fault, got #{fault.class}"
-        end
-
-        new(status: STATUS_ERROR, payload: fault)
-      end
-
-      def initialize(status:, payload:)
-        unless [STATUS_OK, STATUS_ERROR].include?(status)
-          raise ArgumentError, "Response status must be 0 or 1, got #{status.inspect}"
-        end
-        if status == STATUS_ERROR && !payload.is_a?(Kobako::RPC::Fault)
-          raise ArgumentError, "Response status=1 payload must be Kobako::RPC::Fault"
-        end
-
-        super
-      end
-
-      def ok?    = status == STATUS_OK
-      def error? = status == STATUS_ERROR
-      # steep:ignore:end
-    end
-
-    def self.encode_response(response)
-      Codec::Encoder.encode([response.status, response.payload])
-    end
-
-    def self.decode_response(bytes)
-      arr = Codec::Decoder.decode(bytes)
-      unless arr.is_a?(Array) && arr.length == 2
-        raise Codec::InvalidType, "Response must be a 2-element array, got #{arr.inspect}"
-      end
-
-      status, payload = arr
-      Codec::Utils.wire_boundary { Response.new(status: status, payload: payload) }
-    end
-  end
-end

data/lib/kobako/rpc/fault.rb

@@ -1,41 +0,0 @@
-# frozen_string_literal: true
-
-module Kobako
-  module RPC
-    # Wire-level value object for an ext-0x02 Exception envelope.
-    #
-    # 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", "disconnected", "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 +Data.define+ so equality, hash, and immutability are
-    # inherited from the value-object machinery; only the field invariants
-    # ride on top.
-    Fault = Data.define(:type, :message, :details) do
-      # +VALID_TYPES+ is attached to the Exception class below this block.
-      # Reach it through +self.class::VALID_TYPES+ — Data.define's block
-      # scope resolves bare constants against the enclosing +Wire+ module,
-      # so a bare +VALID_TYPES+ would raise +NameError+. Same pattern as
-      # +RPC::Handle+.
-      # steep:ignore:start
-      def initialize(type:, message:, details: nil)
-        valid_types = self.class::VALID_TYPES
-        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
-      # steep:ignore:end
-    end
-
-    Fault::VALID_TYPES = %w[runtime argument disconnected undefined].freeze
-  end
-end

data/lib/kobako/rpc/handle.rb

@@ -1,39 +0,0 @@
-# frozen_string_literal: true
-
-module Kobako
-  module RPC
-    # Wire-level value object for an ext-0x01 Capability Handle.
-    #
-    # 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).
-    #
-    # This is intentionally a thin value object built on +Data.define+ so
-    # equality, hash, and immutability are inherited. The runtime-facing
-    # +Kobako::RPC::Handle+ class lives at a higher layer and may add behaviour
-    # (HandleTable bookkeeping, reset semantics). The codec only needs to
-    # carry the opaque integer ID across the wire.
-    Handle = Data.define(:id) do
-      # +MIN_ID+ / +MAX_ID+ live on the Handle class (defined below this
-      # block), not in this block's binding — Data.define's block scope
-      # resolves bare constants against the enclosing +Wire+ module, so
-      # +MIN_ID+ would raise +NameError+. Use +self.class::CONST+ to
-      # reach the constants attached to the Handle class itself. Do not
-      # "simplify" this back to bare +MIN_ID+/+MAX_ID+.
-      # steep:ignore:start
-      def initialize(id:)
-        min = self.class::MIN_ID
-        max = self.class::MAX_ID
-        raise ArgumentError, "Handle id must be Integer" unless id.is_a?(Integer)
-        raise ArgumentError, "Handle id #{id} out of range [#{min}, #{max}]" unless id.between?(min, max)
-
-        super
-      end
-      # steep:ignore:end
-    end
-
-    Handle::MIN_ID = 1
-    Handle::MAX_ID = 0x7fff_ffff
-  end
-end