kobako 0.4.0 → 0.5.0

data/ext/kobako/src/snapshot.rs

@@ -0,0 +1,110 @@
+//! `Kobako::Snapshot` — per-invocation observable bundle.
+//!
+//! Every successful `Kobako::Runtime#eval` / `#run` returns one of these.
+//! It carries every observable the host needs to surface after a guest
+//! invocation: the OUTCOME_BUFFER bytes (`return_bytes`), the captured
+//! stdout / stderr byte slices with their truncation flags (B-04), and
+//! the wall-clock + memory-peak figures from `Kobako::Usage` (B-35).
+//!
+//! Ruby callers see the seven raw readers registered below; the helper
+//! methods that pack them into `Kobako::Capture` / `Kobako::Usage`
+//! (`Kobako::Snapshot#stdout` / `#stderr` / `#usage`) live in
+//! `lib/kobako/snapshot.rb`. The split keeps the ext side a pure value
+//! carrier and lets Ruby own the convenience surface.
+
+use std::cell::Cell;
+use std::time::Duration;
+
+use magnus::{method, prelude::*, Error as MagnusError, RModule, RString, Ruby};
+
+/// Per-invocation snapshot value. Magnus wraps it so a single ext call
+/// from `Runtime::eval` / `Runtime::run` returns the whole bundle —
+/// the Sandbox layer can decompose it without round-tripping into ext
+/// again. All fields are private; the seven public methods registered
+/// in `init` read them out one by one. The wall-clock duration is
+/// held as a `Cell<Duration>` only because magnus' `#[magnus::wrap]`
+/// macro requires interior mutability — every field is set once at
+/// construction time and never mutated again.
+#[magnus::wrap(class = "Kobako::Snapshot", free_immediately, size)]
+pub(crate) struct Snapshot {
+    return_bytes: Vec<u8>,
+    stdout_bytes: Vec<u8>,
+    stdout_truncated: bool,
+    stderr_bytes: Vec<u8>,
+    stderr_truncated: bool,
+    wall_time: Cell<Duration>,
+    memory_peak: usize,
+}
+
+impl Snapshot {
+    /// Construct a fresh Snapshot from the per-invocation data the
+    /// Runtime has just collected. Called from
+    /// `crate::runtime::Runtime::build_snapshot` once the
+    /// guest export has returned, the OUTCOME_BUFFER has been drained,
+    /// and the capture pipes have been clipped to their caps.
+    pub(crate) fn new(
+        return_bytes: Vec<u8>,
+        stdout_bytes: Vec<u8>,
+        stdout_truncated: bool,
+        stderr_bytes: Vec<u8>,
+        stderr_truncated: bool,
+        wall_time: Duration,
+        memory_peak: usize,
+    ) -> Self {
+        Self {
+            return_bytes,
+            stdout_bytes,
+            stdout_truncated,
+            stderr_bytes,
+            stderr_truncated,
+            wall_time: Cell::new(wall_time),
+            memory_peak,
+        }
+    }
+
+    fn return_bytes(&self) -> RString {
+        let ruby = Ruby::get().expect("Ruby thread");
+        ruby.str_from_slice(&self.return_bytes)
+    }
+
+    fn stdout_bytes(&self) -> RString {
+        let ruby = Ruby::get().expect("Ruby thread");
+        ruby.str_from_slice(&self.stdout_bytes)
+    }
+
+    fn stdout_truncated(&self) -> bool {
+        self.stdout_truncated
+    }
+
+    fn stderr_bytes(&self) -> RString {
+        let ruby = Ruby::get().expect("Ruby thread");
+        ruby.str_from_slice(&self.stderr_bytes)
+    }
+
+    fn stderr_truncated(&self) -> bool {
+        self.stderr_truncated
+    }
+
+    fn wall_time(&self) -> f64 {
+        self.wall_time.get().as_secs_f64()
+    }
+
+    fn memory_peak(&self) -> usize {
+        self.memory_peak
+    }
+}
+
+/// Register `Kobako::Snapshot` plus its seven raw readers under the
+/// `Kobako` module. Called from `crate::init` after `Kobako::Runtime`
+/// is registered so the magnus wrap macro can resolve the class name.
+pub(crate) fn init(ruby: &Ruby, kobako: RModule) -> Result<(), MagnusError> {
+    let snapshot = kobako.define_class("Snapshot", ruby.class_object())?;
+    snapshot.define_method("return_bytes", method!(Snapshot::return_bytes, 0))?;
+    snapshot.define_method("stdout_bytes", method!(Snapshot::stdout_bytes, 0))?;
+    snapshot.define_method("stdout_truncated", method!(Snapshot::stdout_truncated, 0))?;
+    snapshot.define_method("stderr_bytes", method!(Snapshot::stderr_bytes, 0))?;
+    snapshot.define_method("stderr_truncated", method!(Snapshot::stderr_truncated, 0))?;
+    snapshot.define_method("wall_time", method!(Snapshot::wall_time, 0))?;
+    snapshot.define_method("memory_peak", method!(Snapshot::memory_peak, 0))?;
+    Ok(())
+}

data/lib/kobako/capture.rb

@@ -8,18 +8,23 @@ module Kobako
   #
   # Immutable value object: the captured bytes and the truncation flag
   # always travel together and the instance is frozen on construction.
-  # Construct via +Capture.from_ext+ for ext-provided binary bytes (handles
-  # UTF-8 / ASCII-8BIT fallback) or reach +Capture::EMPTY+ for the pre-
-  # invocation sentinel that +Sandbox+ uses before any invocation has
-  # executed.
+  # Construct via +Capture.new(bytes:, truncated:)+ for the ext-provided
+  # binary bytes (the constructor handles the UTF-8 / ASCII-8BIT fallback)
+  # or reach +Capture::EMPTY+ for the pre-invocation sentinel that
+  # +Sandbox+ uses before any invocation has executed.
   class Capture
     attr_reader :bytes
 
     # Build a Capture wrapping +bytes+ (the captured prefix as a String) and
     # +truncated+ (whether the originating WASI pipe reported the cap was
-    # hit). Freezes the instance so callers cannot mutate the pair.
+    # hit). Coerces +bytes+ to UTF-8 when they are valid UTF-8, otherwise
+    # falls back to ASCII-8BIT so invalid sequences remain inspectable
+    # without raising; +bytes+ is duplicated, never mutated. Freezes the
+    # instance so callers cannot mutate the pair.
     def initialize(bytes:, truncated:)
-      @bytes = bytes
+      copy = bytes.dup.force_encoding(Encoding::UTF_8)
+      copy.force_encoding(Encoding::ASCII_8BIT) unless copy.valid_encoding?
+      @bytes = copy
       @truncated = truncated
       freeze
     end
@@ -29,16 +34,6 @@ module Kobako
     # ({docs/behavior.md B-04}[link:../../docs/behavior.md]).
     def truncated? = @truncated
 
-    # Construct a Capture from ext-provided binary bytes. Coerces +bytes+
-    # to UTF-8 when the bytes are valid UTF-8, otherwise falls back to
-    # ASCII-8BIT so invalid sequences remain inspectable without raising.
-    # +bytes+ is not mutated.
-    def self.from_ext(bytes, truncated)
-      copy = bytes.dup.force_encoding(Encoding::UTF_8)
-      copy.force_encoding(Encoding::ASCII_8BIT) unless copy.valid_encoding?
-      new(bytes: copy, truncated: truncated)
-    end
-
     # Pre-invocation sentinel ({docs/behavior.md B-05}[link:../../docs/behavior.md]).
     # Empty UTF-8 bytes and +truncated? == false+; reused by every fresh
     # +Sandbox+ and by +Sandbox+ between invocations to denote "no capture

data/lib/kobako/catalog/handles.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require_relative "../handle"
+
+module Kobako
+  module Catalog
+    # 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::Catalog::Namespaces+ so guest→host 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 Handles
+      # Build a fresh, empty table. +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::HandlerExhaustedError+ 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.restore+
+      # 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 HandlerExhaustedError,
+                "Out of handle allocations: too many host objects were referenced " \
+                "in a single invocation (limit #{cap})"
+        end
+
+        @entries[id] = object
+        @next_id = id + 1
+        Kobako::Handle.restore(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::SandboxError+ if +id+ is not currently bound.
+      def fetch(id)
+        require_bound!(id)
+        @entries[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
+
+      # Number of currently-bound entries. Used by tests of the Dispatcher
+      # and Codec::Utils#deep_wrap to observe whether each path allocates
+      # exactly the Handle entries it should — the +Handles+ table itself never
+      # consults its own size, but the surrounding code's allocation
+      # contract is part of the observable boundary.
+      def size
+        @entries.size
+      end
+
+      private
+
+      # Single source of truth for the "unknown Handle id" raise used by
+      # {#fetch}. Returns +nil+ on success; raises +Kobako::SandboxError+
+      # when +id+ is not currently bound.
+      def require_bound!(id)
+        return if @entries.key?(id)
+
+        raise SandboxError, "unknown Handle id: #{id.inspect}"
+      end
+    end
+  end
+end

data/lib/kobako/catalog/namespaces.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require_relative "handles"
+require_relative "../codec"
+require_relative "../errors"
+require_relative "../transport/request"
+require_relative "../namespace"
+
+module Kobako
+  module Catalog
+    # Kobako::Catalog::Namespaces — per-Sandbox registry of
+    # +Kobako::Namespace+ entities. Holds the Namespace / Member bindings
+    # and the preamble emitted on Frame 1
+    # ({docs/behavior.md B-07..B-11}[link:../../../docs/behavior.md]).
+    #
+    # Public API:
+    #
+    #   namespaces = Kobako::Catalog::Namespaces.new
+    #   namespace = namespaces.define(:MyService)  # => Kobako::Namespace
+    #   namespace.bind(:KV, kv_object)             # => namespace (chainable)
+    #   namespaces.encode                          # => msgpack bytes for Frame 1
+    #   namespaces.lookup("MyService::KV")         # => kv_object
+    #
+    # Namespaces live at +Kobako::Namespace+. 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 ({docs/behavior.md B-12}[link:../../../docs/behavior.md]).
+    # The registry holds an injected +Catalog::Handles+ reference so
+    # dispatch target resolution and host→guest auto-wrap share the same
+    # Sandbox-owned allocator (docs/behavior.md B-19).
+    class Namespaces
+      # 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 B-21 cap-exhaustion path
+      # without 2³¹ allocations. Production callers leave it at the default.
+      def initialize(handler: Catalog::Handles.new)
+        @namespaces = {} # : Hash[String, Kobako::Namespace]
+        @handler = handler
+        @sealed = false
+      end
+
+      # Declare or retrieve the Namespace named +name+ (idempotent — docs/behavior.md B-10).
+      # +name+ is a constant-form name as a +Symbol+ or +String+ (must satisfy
+      # +Namespace::NAME_PATTERN+). Returns the +Kobako::Namespace+ for that
+      # name, creating it if it does not exist. Raises +ArgumentError+ when
+      # +name+ is malformed, or when called after the owning Sandbox has been
+      # sealed by its first invocation
+      # ({docs/behavior.md B-07}[link:../../../docs/behavior.md]).
+      def define(name)
+        raise ArgumentError, "cannot define after first Sandbox invocation" if @sealed
+
+        name_str = name.to_s
+        unless Namespace::NAME_PATTERN.match?(name_str)
+          raise ArgumentError,
+                "Namespace name must match #{Namespace::NAME_PATTERN.inspect} (got #{name.inspect})"
+        end
+
+        @namespaces[name_str] ||= Namespace.new(name_str)
+      end
+
+      # Resolve a +target+ path of the form +"Namespace::Member"+ to the
+      # bound Host object. +target+ is a two-level path using the +::+
+      # separator. Returns the bound Host object. Raises +KeyError+ when the
+      # namespace or the member is not bound.
+      def lookup(target)
+        namespace_name, member_name = target.to_s.split("::", 2)
+        namespace = @namespaces[namespace_name]
+        raise KeyError, "no namespace named #{namespace_name.inspect}" if namespace.nil?
+        raise KeyError, "no member in target #{target.inspect}" unless member_name
+
+        namespace.fetch(member_name)
+      end
+
+      # Encode the preamble as msgpack bytes for stdin Frame 1 delivery
+      # ({docs/behavior.md B-02}[link:../../../docs/behavior.md]). Routes through
+      # {Kobako::Codec::Encoder} like every other host-side wire encode so
+      # there is a single codec path; the preamble carries only Strings and
+      # Arrays, so none of the kobako ext types actually fire. Structure:
+      # +[["Namespace", ["MemberA", "MemberB"]], ...]+. Returns a binary
+      # +String+ of msgpack bytes.
+      def encode
+        Codec::Encoder.encode(@namespaces.values.map(&:to_preamble))
+      end
+
+      # Mark the registry as sealed. Called by +Sandbox+ on the first
+      # invocation. After sealing, #define raises ArgumentError. Idempotent.
+      def seal!
+        @sealed = true
+        self
+      end
+
+      # Returns +true+ when {#seal!} has been called, +false+ otherwise.
+      def sealed?
+        @sealed
+      end
+    end
+  end
+end

data/lib/kobako/{snippet/table.rb → catalog/snippets.rb}

@@ -1,32 +1,30 @@
 # frozen_string_literal: true
 
-require "msgpack"
-
-require_relative "binary"
-require_relative "source"
+require_relative "../codec"
+require_relative "../snippet"
 
 module Kobako
-  module Snippet
-    # Kobako::Snippet::Table — per-Sandbox insertion-ordered registry of
-    # preloaded snippets
+  module Catalog
+    # Kobako::Catalog::Snippets — per-Sandbox insertion-ordered registry
+    # of preloaded snippets
     # ({docs/behavior.md B-32 / B-33}[link:../../../docs/behavior.md]).
     #
     # Entries replay against the fresh +mrb_state+ before per-invocation
-    # source / entrypoint resolution. Each +Source+ entry's +name+ is its
-    # canonical identity — the filename baked into the loaded IREP's
-    # +debug_info+ that surfaces in every backtrace frame originating
-    # from the snippet as +(snippet:Name):line+. Duplicate names within
-    # the +code:+ form would produce ambiguous attribution and are
-    # rejected at registration time
+    # source / entrypoint resolution. Each +Snippet::Source+ entry's +name+
+    # is its canonical identity — the filename baked into the loaded IREP's
+    # +debug_info+ that surfaces in every backtrace frame originating from
+    # the snippet as +(snippet:Name):line+. Duplicate names within the
+    # +code:+ form would produce ambiguous attribution and are rejected at
+    # registration time
     # ({docs/behavior.md E-33}[link:../../../docs/behavior.md]).
-    # +Binary+ entries carry no host-side name — their canonical name
-    # lives in the bytecode's +debug_info+ and is read by the guest at
+    # +Snippet::Binary+ entries carry no host-side name — their canonical
+    # name lives in the bytecode's +debug_info+ and is read by the guest at
     # load time; the host does not extract it.
     #
-    # Sealing (B-33) is governed by the owning Sandbox — the table itself
+    # Sealing (B-33) is governed by the owning Sandbox — the registry itself
     # is append-only and exposes no mutation API beyond +#register+; the
     # Sandbox guards +#register+ behind the seal check before delegating.
-    class Table
+    class Snippets
       # Ruby constant-name pattern enforced on snippet names
       # ({docs/behavior.md E-34}[link:../../../docs/behavior.md]).
       NAME_PATTERN = /\A[A-Z]\w*\z/
@@ -37,14 +35,15 @@ module Kobako
 
       # Serialize the registered snippets to wire bytes. Each entry
       # contributes a msgpack map shape; the collection rides as a single
-      # msgpack array. An empty table serializes to an empty array, never
+      # msgpack array. An empty registry serializes to an empty array, never
       # absent. The wire codec is an implementation detail — callers
-      # receive a binary +String+ that the +Kobako::Wasm+ layer ships
-      # through the invocation channel. Mirrors the
-      # +Kobako::RPC.encode_request+ pattern: entry value objects stay
-      # pure carriers, this method reads their attributes externally.
+      # receive a binary +String+ that the +Kobako::Runtime+ layer ships
+      # through the invocation channel. The entry value objects stay pure
+      # carriers — this collection-tier method reads their attributes
+      # externally via +entry_payload+ rather than asking each entry to
+      # self-encode.
       def encode
-        MessagePack.pack(@entries.map { |entry| entry_payload(entry) })
+        Codec::Encoder.encode(@entries.map { |entry| entry_payload(entry) })
       end
 
       # Register one preloaded snippet in either of two forms
@@ -78,43 +77,20 @@ module Kobako
         end
       end
 
-      # Iterate over registered entries in insertion order. Yields each
-      # entry (a +Kobako::Snippet::Source+ or +Kobako::Snippet::Binary+).
-      # Returns an Enumerator when no block is given.
-      def each(&)
-        @entries.each(&)
-      end
-
-      # Canonical names of every registered +Source+ entry, in insertion
-      # order. +Binary+ entries are skipped — their names live in
-      # bytecode +debug_info+ on the guest side and are not extracted by
-      # the host.
-      def names
-        @entries.filter_map { |entry| entry.name if entry.is_a?(Source) }
-      end
-
-      # Number of registered snippets.
-      def size
-        @entries.size
-      end
-
-      # Whether no snippets are registered.
-      def empty?
-        @entries.empty?
-      end
-
       private
 
       # Source-form register path. Delegates argument-shape checks to
-      # +ensure_source_args!+ (which returns the narrowed
-      # +[code, name]+ pair), normalises +name+ to a Symbol, rejects
-      # duplicates (E-33), and appends the Source entry.
+      # +ensure_source_args!+ (which returns the narrowed +[code, name]+
+      # pair), normalises +name+ to a Symbol, rejects duplicates (E-33),
+      # and appends the Source entry.
       def register_source!(code, name)
         code, name = ensure_source_args!(code, name)
         name_sym = normalize_name(name)
-        raise ArgumentError, "snippet #{name_sym.inspect} already preloaded" if names.include?(name_sym)
+        if @entries.any? { |e| e.is_a?(Snippet::Source) && e.name == name_sym }
+          raise ArgumentError, "snippet #{name_sym.inspect} already preloaded"
+        end
 
-        @entries << Source.new(name: name_sym, body: code.dup.force_encoding(Encoding::UTF_8))
+        @entries << Snippet::Source.new(name: name_sym, body: code.dup.force_encoding(Encoding::UTF_8))
         name_sym
       end
 
@@ -131,14 +107,13 @@ module Kobako
         [code, name]
       end
 
-      # Binary-form register path. Validates the +binary:+ payload
-      # type and appends the Binary entry. The bytes are duplicated and
-      # forced to ASCII-8BIT so msgpack-ruby picks the +bin+ family on
-      # the wire.
+      # Binary-form register path. Validates the +binary:+ payload type
+      # and appends the Binary entry. The bytes are duplicated and forced
+      # to ASCII-8BIT so msgpack-ruby picks the +bin+ family on the wire.
       def register_binary!(bytes)
         raise ArgumentError, "binary must be a String, got #{bytes.class}" unless bytes.is_a?(String)
 
-        @entries << Binary.new(body: bytes.dup.force_encoding(Encoding::ASCII_8BIT))
+        @entries << Snippet::Binary.new(body: bytes.dup.force_encoding(Encoding::ASCII_8BIT))
         nil
       end
 
@@ -149,10 +124,10 @@ module Kobako
       # ({docs/wire-codec.md Invocation channels}[link:../../../docs/wire-codec.md]).
       def entry_payload(entry)
         case entry
-        when Source
-          { "name" => entry.name.to_s, "kind" => Source::KIND, "body" => entry.body }
-        when Binary
-          { "kind" => Binary::KIND, "body" => entry.body }
+        when Snippet::Source
+          { "name" => entry.name.to_s, "kind" => Snippet::Source::KIND, "body" => entry.body }
+        when Snippet::Binary
+          { "kind" => Snippet::Binary::KIND, "body" => entry.body }
         end
       end
 

data/lib/kobako/catalog.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative "catalog/handles"
+require_relative "catalog/namespaces"
+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),
+  # +Catalog::Snippets+ (preloaded source / bytecode entries), and
+  # +Catalog::Handles+ (per-invocation Handle ID allocator).
+  #
+  # See {SPEC.md Refinement → Internal Concepts}[link:../../SPEC.md] for
+  # how Catalog fits alongside Transport and Runtime.
+  module Catalog
+  end
+end

data/lib/kobako/codec/decoder.rb

@@ -23,13 +23,21 @@ module Kobako
       # Decode +bytes+ into one Ruby value and validate transitively
       # against the SPEC type mapping. Raises {Truncated}, {InvalidType},
       # or {InvalidEncoding} on wire violations.
+      #
+      # When a block is given, the decoded value is yielded and the block's
+      # result is returned — wire Value Objects use this to build themselves
+      # from the decoded payload. The block runs inside this method's
+      # rescue, so a Value Object's +ArgumentError+ invariant failure
+      # surfaces as {InvalidType} without a separate {Utils.with_boundary}
+      # wrapper at the call site.
       def self.decode(bytes)
         value = Factory.load(bytes.b)
         validate_utf8!(value)
-        value
-      # msgpack gem raises these for type/format violations; +ArgumentError+
-      # also comes from our ext-type validators (Handle id range, Exception
-      # type whitelist).
+        block_given? ? yield(value) : value
+      # msgpack gem raises the format/type errors below; +ArgumentError+
+      # comes from our ext-type validators (Handle id range, Exception type
+      # whitelist) and from a yielded block's Value Object invariants — both
+      # are wire violations, so both map to {InvalidType}.
       rescue ::MessagePack::UnknownExtTypeError, ::MessagePack::MalformedFormatError,
              ::MessagePack::StackError, ::ArgumentError => e
         raise InvalidType, e.message
@@ -45,7 +53,7 @@ module Kobako
       # Encoding Rules). The msgpack gem returns UTF-8-tagged Strings for
       # str family but does not validate the bytes; +bin+ family decodes
       # to ASCII-8BIT. Walk the tree once and reject invalid UTF-8 in any
-      # str-typed leaf via {Utils.assert_utf8!}. {Kobako::RPC::Fault}
+      # str-typed leaf via {Utils.assert_utf8!}. {Kobako::Fault}
       # payloads are validated transitively: +Factory.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.

data/lib/kobako/codec/factory.rb

@@ -7,7 +7,7 @@ require "msgpack"
 require_relative "error"
 require_relative "utils"
 require_relative "../handle"
-require_relative "../rpc/fault"
+require_relative "../fault"
 
 module Kobako
   module Codec
@@ -108,16 +108,16 @@ module Kobako
 
       def register_fault
         @factory.register_type(
-          EXT_ERRENV, RPC::Fault,
+          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.from_wire+ factory, and
+      # Host-Gem-internal +Kobako::Handle.restore+ factory, and
       # translate the +ArgumentError+ raised by Handle's invariants
-      # into a wire-layer +InvalidType+ via {Codec::Utils.wire_boundary}.
+      # 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)
@@ -125,7 +125,7 @@ module Kobako
         raise InvalidType, "Handle payload must be 4 bytes, got #{bytes.bytesize}" unless bytes.bytesize == 4
 
         id = bytes.unpack1("N") # : Integer
-        Codec::Utils.wire_boundary { Kobako::Handle.from_wire(id) }
+        Codec::Utils.with_boundary { Kobako::Handle.restore(id) }
       end
 
       # Encode the inner ext-0x02 map via {Encoder} (not +factory.dump+) so
@@ -136,9 +136,10 @@ module Kobako
         Encoder.encode("type" => fault.type, "message" => fault.message, "details" => fault.details)
       end
 
-      # Peel the embedded msgpack map and hand it to +RPC::Fault.new+;
-      # translate the value-object's +ArgumentError+ into +InvalidType+
-      # at the wire boundary. Inner decode goes through {Decoder} (not
+      # 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.
       #
@@ -150,11 +151,10 @@ module Kobako
       # +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)
-        map = Decoder.decode(payload)
-        raise InvalidType, "Fault payload must be a map" unless map.is_a?(Hash)
+        Decoder.decode(payload) do |map|
+          raise InvalidType, "Fault payload must be a map" unless map.is_a?(Hash)
 
-        Codec::Utils.wire_boundary do
-          RPC::Fault.new(type: map["type"], message: map["message"], details: map["details"])
+          Kobako::Fault.new(type: map["type"], message: map["message"], details: map["details"])
         end
       end
     end