kobako 0.4.0 → 0.5.0

data/ext/kobako/src/wasm.rs

@@ -1,126 +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))?;
-    instance.define_method("usage", method!(Instance::usage, 0))?;
-
-    Ok(())
-}

data/lib/kobako/handle_table.rb

@@ -1,119 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "handle"
-
-module Kobako
-  # Host-side mapping from opaque integer Handle IDs to Ruby objects.
-  # The table is owned by +Kobako::Sandbox+ ({docs/behavior.md B-19}[link:../../docs/behavior.md])
-  # and injected into the per-Sandbox +Kobako::RPC::Server+ so guest→host
-  # RPC dispatch resolves Handle targets and arguments against the same
-  # table that host→guest wire encoding allocates into
-  # ({docs/behavior.md B-14, B-34}[link:../../docs/behavior.md]).
-  #
-  # Lifecycle invariants ({docs/behavior.md}[link:../../docs/behavior.md]):
-  #
-  #   - {docs/behavior.md B-15}[link:../../docs/behavior.md] — 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+.
-  #
-  #   - {docs/behavior.md B-19}[link:../../docs/behavior.md] — At every
-  #     invocation boundary (via +#reset!+), every Handle issued under the
-  #     old state becomes invalid. Reset applies uniformly regardless of
-  #     allocation source (B-14 Service return or B-34 host-injected
-  #     argument).
-  #
-  #   - {docs/behavior.md B-21}[link:../../docs/behavior.md] — The cap is
-  #     +0x7fff_ffff+ (2³¹ − 1). Allocation beyond the cap raises immediately
-  #     — no silent truncation, no wrap, no ID reuse.
-  class HandleTable
-    # Build a fresh, empty HandleTable. +next_id+ is an internal seam that
-    # sets the starting value of the monotonic counter (defaults to 1 per
-    # B-15); tests pass a value near +Kobako::Handle::MAX_ID+ to exercise
-    # the cap-exhaustion path without 2³¹ allocations.
-    def initialize(next_id: 1)
-      @entries = {} # : Hash[Integer, untyped]
-      @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::HandleTableExhausted+ 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
-    # ({docs/behavior.md B-21}[link:../../docs/behavior.md]).
-    #
-    # Returning a Handle (rather than a bare Integer id) keeps the
-    # allocator's output a domain entity; +Kobako::Handle.from_wire+
-    # is reserved for the codec's wire-decode path, where the id is
-    # the only thing the bytes carry.
-    def alloc(object)
-      id = @next_id
-      cap = Kobako::Handle::MAX_ID
-      if id > cap
-        raise HandleTableExhausted,
-              "Handle id space exhausted: allocation would assign id #{id}, exceeding the cap (#{cap})"
-      end
-
-      @entries[id] = object
-      @next_id = id + 1
-      Kobako::Handle.from_wire(id)
-    end
-
-    # Resolve a Handle ID to its bound object. +id+ is a Handle ID previously
-    # returned by +#alloc+. Returns the bound object. Raises
-    # +Kobako::HandleTableError+ if +id+ is not currently bound.
-    def fetch(id)
-      require_bound!(id)
-      @entries[id]
-    end
-
-    # Remove and return the binding for +id+. +id+ is the Handle ID to
-    # release. Returns the previously-bound object. Raises
-    # +Kobako::HandleTableError+ if +id+ is not currently bound.
-    def release(id)
-      require_bound!(id)
-      @entries.delete(id)
-    end
-
-    # Clear all entries AND reset the counter to 1. Called at the per-invocation
-    # boundary by +Kobako::Sandbox+ — see
-    # {docs/behavior.md B-19}[link:../../docs/behavior.md]. Returns +self+.
-    def reset!
-      @entries.clear
-      @next_id = 1
-      self
-    end
-
-    # Mark the entry at +id+ as disconnected (ABA protection). +id+ is the
-    # Handle ID to poison; silently ignored if +id+ is not currently bound.
-    # Returns +self+ for chainability, matching the convention of +#reset!+.
-    def mark_disconnected(id)
-      @entries[id] = :disconnected if @entries.key?(id)
-      self
-    end
-
-    # Returns the number of currently-bound entries.
-    def size
-      @entries.size
-    end
-
-    # Returns +true+ when +id+ is currently bound, +false+ otherwise.
-    def include?(id)
-      @entries.key?(id)
-    end
-
-    private
-
-    # Single source of truth for the "unknown Handle id" raise shared by
-    # {#fetch} and {#release}. Returns +nil+ on success; raises
-    # +Kobako::HandleTableError+ when +id+ is not currently bound.
-    def require_bound!(id)
-      return if @entries.key?(id)
-
-      raise HandleTableError, "unknown Handle id: #{id.inspect}"
-    end
-  end
-end

data/lib/kobako/invocation.rb

@@ -1,143 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "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); Invocation is the opposite direction (host→guest
-  # entrypoint dispatch). +#encode+ takes the Sandbox's HandleTable
-  # and routes any non-wire-representable +args+ / +kwargs+ leaf
-  # through it as a +Kobako::Handle+
-  # ({docs/behavior.md B-34}[link:../../docs/behavior.md]) — the
-  # symmetric counterpart of the guest→host wrap path in
-  # +Kobako::RPC::Dispatcher#wrap_as_handle+ (B-14). A
-  # +Kobako::Handle+ that arrives **already constructed** in the
-  # caller's +args+ / +kwargs+ is rejected at construction (E-29):
-  # legitimate Handles only enter Host App code through error fields,
-  # so a Handle reaching the call site is by definition smuggled in.
-  # 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]).
-    # Walks +args+ / +kwargs+ through {Codec::Utils.deep_wrap} so any
-    # non-wire-representable leaf is allocated into +handle_table+ and
-    # replaced with a +Kobako::Handle+
-    # ({docs/behavior.md B-34}[link:../../docs/behavior.md]); the
-    # +handle_table+ argument is the Sandbox's table, sharing the same
-    # allocator the guest→host return path (B-14) uses.
-    #
-    # Layout: msgpack map with string keys +"entrypoint"+ (Symbol via
-    # ext 0x00), +"args"+ (Array), +"kwargs"+ (Map with Symbol keys);
-    # any wrapped leaf rides as ext 0x01 in its original position
-    # (docs/wire-codec.md § ext 0x01 position rules).
-    def encode(handle_table)
-      Codec::Encoder.encode(
-        "entrypoint" => entrypoint,
-        "args" => Codec::Utils.deep_wrap(args, handle_table),
-        "kwargs" => Codec::Utils.deep_wrap(kwargs, handle_table)
-      )
-    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::Handle+. The Handle
-    # allocator lives inside the Host Gem; legitimate paths surface
-    # Handle objects only through raised error fields, so a Handle
-    # reaching +args+ is a forged or smuggled token. Non-wire-
-    # representable arguments that are not Handles are handled by
-    # auto-wrap inside +#encode+ (B-34) — the reject path is reserved
-    # for Handle objects specifically.
-    def validate_args!(args)
-      raise ArgumentError, "Invocation args must be Array" unless args.is_a?(Array)
-      raise ArgumentError, forged_handle_message("args") if args.any?(Kobako::Handle)
-
-      args
-    end
-
-    # E-30 covers the non-Symbol kwargs-key case; E-29 also rejects a
-    # +Kobako::Handle+ arriving as a kwargs value (same forged-token
-    # principle as the +args+ branch). Both checks live here 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
-      raise ArgumentError, forged_handle_message("kwargs values") if kwargs.each_value.any?(Kobako::Handle)
-
-      kwargs
-    end
-
-    # Single source of truth for the E-29 reject message so the args
-    # and kwargs branches stay phrased identically. Message stays in
-    # caller vocabulary: it names the affected slot and the reason
-    # without leaking SPEC anchor identifiers (B-xx / E-xx live in
-    # source comments, not user-visible errors) or self-referential
-    # architecture terms — the error is raised BY kobako, so saying
-    # "allocated by the Host Gem" reads as third-person about self.
-    def forged_handle_message(slot)
-      "Invocation #{slot} must not contain a Kobako::Handle — " \
-        "Kobako::Handle instances are internal wire tokens, not caller-constructible"
-    end
-    # steep:ignore:end
-  end
-end

data/lib/kobako/rpc/dispatcher.rb

@@ -1,171 +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+ resolves path-based
-      # Member targets via +#lookup+. +handle_table+ is the Sandbox's
-      # HandleTable, injected separately so Dispatcher does not depend
-      # on Server publishing a Handle accessor — Handle is a
-      # Sandbox-level domain entity (B-19) and the dispatcher is its
-      # only consumer here. 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, handle_table)
-        request = Kobako::RPC.decode_request(request_bytes)
-        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, handle_table)
-      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" (malformed RPC request);
-      # +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",
-                                                    "Sandbox received a malformed RPC request: #{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 Kobako::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::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::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, handle_table)
-        response = Kobako::RPC::Response.ok(value)
-        Kobako::RPC.encode_response(response)
-      rescue Kobako::Codec::UnsupportedType
-        encode_ok(wrap_as_handle(value, handle_table), handle_table)
-      end
-
-      # Allocate +value+ in the Sandbox'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, handle_table)
-        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::Handle)
-          raise ArgumentError, "Request target must be String or Kobako::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 envelope is malformed (expected a 4-element array)"
-      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 (ok) or 1 (error), got #{status.inspect}"
-        end
-        if status == STATUS_ERROR && !payload.is_a?(Kobako::RPC::Fault)
-          raise ArgumentError, "Response with error status must carry a Kobako::RPC::Fault payload"
-        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 envelope is malformed (expected a 2-element array)"
-      end
-
-      status, payload = arr
-      Codec::Utils.wire_boundary { Response.new(status: status, payload: payload) }
-    end
-  end
-end