kobako 0.26.0-aarch64-linux → 0.28.0-aarch64-linux

data/lib/kobako/errors.rb

@@ -1,103 +1,53 @@
 # frozen_string_literal: true
 
-# Top-level Kobako namespace.
 module Kobako
-  # Error taxonomy.
-  #
-  # Every +Kobako::Sandbox+ invocation (+#eval+ or +#run+) either returns a
-  # value or raises exactly one of TrapError, SandboxError, or ServiceError.
-  # Attribution is decided after the guest binary returns control to the
-  # host: first the Wasm-trap layer, then the outcome-envelope tag.
-  # SetupError and PoolTimeoutError sit outside the invocation taxonomy and
-  # never pass through that attribution decision. Each class below
-  # documents its own layer.
-
-  # Base for all kobako-raised errors so callers that want to ignore the
-  # taxonomy can rescue a single class.
+  # Every Sandbox#eval or Sandbox#run returns, or raises exactly one of
+  # TrapError, SandboxError, or ServiceError. SetupError and PoolTimeoutError
+  # arise outside any invocation.
+
+  # The base of every error kobako raises.
   class Error < StandardError; end
 
-  # Carries the frozen +Kobako::Execution+ of the run that failed, so a
-  # rescue reads its captures and usage exactly as a successful caller reads
-  # them off the return value. Mixed only into the three invocation-outcome
-  # classes (+TrapError+ / +SandboxError+ / +ServiceError+ and their
-  # subclasses); +SetupError+ and +PoolTimeoutError+ arise outside any
-  # invocation and carry no Execution. Defaults to +nil+ — a pre-flight
-  # failure that ran no invocation leaves it unset.
+  # Gives an invocation failure the Execution of the run that failed, so a
+  # rescue reads its captures and usage as a successful caller would.
+  # +execution+ is +nil+ when the failure came before the guest ran.
   module CarriesExecution
+    # The Execution of the run that failed.
     attr_reader :execution
 
-    # Attach the failed run's +Kobako::Execution+ and return +self+ so the
-    # raise site reads +raise error.with_execution(execution)+.
-    def with_execution(execution)
+    def with_execution(execution) # :nodoc:
       @execution = execution
       self
     end
   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 (an
-  # outcome the core envelope cannot frame, an absent one included).
-  #
-  # Two named subclasses cover the configured per-invocation caps:
-  #
-  #   * TimeoutError     — wall-clock +timeout+ exceeded.
-  #   * MemoryLimitError — guest +memory.grow+ would exceed
-  #                          +memory_limit+.
-  #
-  # 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.
+  # The engine stopped the guest: a trap, a cap reached, or an outcome that
+  # could not be read. The next invocation on the same Sandbox runs as usual.
   class TrapError < Error
     include CarriesExecution
   end
 
-  # Wall-clock timeout cap exhausted: 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.
+  # The invocation ran past its +timeout+.
   class TimeoutError < TrapError; end
 
-  # Linear-memory cap exhausted: 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.
+  # The invocation grew guest memory past its +memory_limit+.
   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. 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.
+  # A Sandbox could not be built: the Guest Binary is unreadable or not a
+  # valid module, the runtime failed to start, or it provides less isolation
+  # than +profile+ asks for.
   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+. 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.
+  # The Guest Binary is missing at +wasm_path+.
   class ModuleNotBuiltError < SetupError; end
 
-  # The structured attribution the two invocation-failure classes carry
-  # from a decoded guest exception — its +origin+, original +klass+, and
-  # +backtrace_lines+ — so a Host App can inspect a failure beyond its
-  # message. Mixed into both rather than promoted to a shared superclass
-  # because +SandboxError+ and +ServiceError+ sit in distinct branches of
-  # the invocation-outcome taxonomy under +Kobako::Error+.
-  #
-  # Data specific to one kind of failure rides a named reader on the
-  # subclass that failure raises, the way Ruby pairs NameError#name with
-  # +NameError#local_variables+ — see UndefinedEntrypointError.
+  # What the guest reported about a failure.
   module Diagnosable
+    # Where the failure came from (<tt>"sandbox"</tt> or <tt>"service"</tt>),
+    # the name of the class that raised it, and its backtrace.
     attr_reader :origin, :klass, :backtrace_lines
 
-    def initialize(message, origin: nil, klass: nil, backtrace_lines: nil)
+    def initialize(message, origin: nil, klass: nil, backtrace_lines: nil) # :nodoc:
       super(message)
       @origin = origin
       @klass = klass
@@ -105,93 +55,67 @@ module Kobako
     end
   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
-  # payload the host's codec could not decode out of a well-framed
-  # outcome.
+  # The guest failed: the script raised or did not compile, the Guest Binary
+  # could not start the run, or what it produced could not be read.
   class SandboxError < Error
     include Diagnosable
     include CarriesExecution
   end
 
-  # Service layer. Raised when a Service capability call inside a mruby
-  # script reported an application-level failure that the script did not
-  # rescue. The base class covers a Service that ran and raised; the two
-  # subclasses below cover the calls that never reached one, so a Host App
-  # routes them apart with +rescue+ instead of by reading the message.
+  # A Service call failed and the guest left it unrescued.
   class ServiceError < Error
     include Diagnosable
     include CarriesExecution
   end
 
-  # The ServiceError subclass raised when the call reached no Service
-  # method: the bound path holds nothing, the Capability Handle is not
-  # live in this invocation, or the method is absent or outside the guest
-  # surface. The causes stay indistinguishable — an opaque target must
-  # disclose nothing about which methods it defines — so what a Host App
-  # learns is that this call will not succeed by being retried.
+  # The call reached no Service method: nothing is bound there, the Handle
+  # is not live, or the guest may not call that method. The causes look the
+  # same on purpose, so a target discloses nothing about what it defines.
   class NoServiceError < ServiceError; end
 
-  # The ServiceError subclass raised when the call reached the Service
-  # method but its arguments did not fit — an unknown keyword, or an
-  # arity mismatch.
+  # The call reached the Service method with arguments that did not fit.
   class ServiceArgumentError < ServiceError; end
 
-  # Raised at a Service method's +yield+ site when the guest block it
-  # yielded to raised. A Service rescues it the way it would rescue a
-  # block's exception without a Sandbox between the two frames; leaving it
-  # unrescued returns it to the guest, which re-raises the exception it
-  # raised in the first place. It therefore never reaches the Host App as
-  # an invocation outcome and carries no Execution. +klass+ names the
-  # guest-side class, which has no host counterpart to rebuild.
+  # Raised at a Service's +yield+ when the guest block raised; rescue it as
+  # you would the block's own exception. Left unrescued, the guest sees its
+  # own exception again, so it never reaches the Host App.
   class BlockError < Error
     include Diagnosable
   end
 
-  # Raised at a Service method's +yield+ site when a yield argument has no
-  # wire representation, so the round-trip never left the host and the
-  # block never ran. As BlockError, a Service rescues it at that site and
-  # may go on, so it never reaches the Host App as an invocation outcome;
-  # unrescued, the dispatch answers as that Service having failed.
+  # Raised at a Service's +yield+ when an argument cannot cross to the guest,
+  # so the block never ran. Left unrescued, the Service call fails.
   class YieldValueError < Error; end
 
-  # HandleExhaustedError is the canonical SandboxError subclass for the
-  # id-cap-hit path. Raised when the per-invocation Handle ID counter in
-  # Catalog::Handles reaches +0x7fff_ffff+ (2³¹ − 1) and further
-  # allocation would exceed the cap.
+  # Raised at a Service's +yield+ when the guest serves no block, so the
+  # block never ran. Left unrescued, the Service call fails.
+  class UnsupportedError < Error; end
+
+  # One invocation issued more Handles than an id can number (2**31 - 1).
   class HandleExhaustedError < SandboxError; end
 
-  # 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+ (RITE
-  # version mismatch or corrupt body). Bytecode that loads cleanly and
-  # then raises at top level 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.
+  # A <tt>preload(binary:)</tt> snippet failed to load. Bytecode that loads
+  # and then raises is a plain SandboxError.
   class BytecodeError < SandboxError; end
 
-  # UndefinedEntrypointError is the SandboxError subclass raised when a
-  # +#run+ target names no top-level constant in the guest. It carries the
-  # +#name+ that was asked for and the +#available+ names it could have
-  # been — the top-level constants the preloaded snippets contributed — so
-  # a caller corrects the name from the error rather than by reading the
-  # guest source. Ruby pairs NameError#name with
-  # +NameError#local_variables+ for the same reason.
+  # The Guest Binary does not support a flag the Sandbox set, so no script
+  # ran. Retrying without the flag, or on a Guest Binary that supports it,
+  # can succeed.
+  class UnsupportedFlagError < SandboxError; end
+
+  # Sandbox#run named no top-level constant.
   class UndefinedEntrypointError < SandboxError
+    # The constant asked for, and the ones the preloaded snippets define.
     attr_reader :name, :available
 
-    def initialize(message, name: nil, available: [], **)
+    def initialize(message, name: nil, available: [], **) # :nodoc:
       super(message, **)
       @name = name
       @available = available
     end
   end
 
-  # Pool checkout layer. Raised by +Kobako::Pool#with+ when the checkout
-  # wait exceeded the configured +checkout_timeout+ while every slot was
-  # held. No Sandbox state is touched — retrying succeeds as soon as a holder
-  # returns its Sandbox.
+  # Pool#with waited past +checkout_timeout+ with every slot held. Retrying
+  # succeeds once a holder returns its Sandbox.
   class PoolTimeoutError < Error; end
 end

data/lib/kobako/execution.rb

@@ -4,25 +4,20 @@ require_relative "capture"
 require_relative "usage"
 
 module Kobako
-  # Kobako::Execution — the frozen result of one +Sandbox#eval+ / +#run+: the
-  # decoded +#value+ plus the run's output captures and +#usage+. A successful
-  # run returns it; a failed run raises an error carrying the same frozen
-  # Execution on the error's +#execution+, so a rescue reads the captures and
-  # usage exactly as a successful caller reads them off the return value. On a
-  # failed run +#value+ is +nil+ — only the captures and usage are meaningful.
+  # The record of one Sandbox#eval or Sandbox#run: the guest's #value, its
+  # output, and its #usage. A failed run raises instead, and the error carries
+  # the same record on +execution+, where #value is +nil+.
   #
-  # +#failed?+ tells the returned Execution from the carried one even when both
-  # +#value+ are +nil+ (a run whose last expression was +nil+ versus a failed
-  # one). It holds no reference to the raising error, so the error carries the
-  # Execution but not the reverse.
+  # #failed? tells the two apart when both #value are +nil+: a script whose
+  # last expression was +nil+ versus one that failed.
   class Execution
-    # The deserialized guest value the run produced; +nil+ on a failed run.
+    # The guest value the run produced; +nil+ on a failed run.
     attr_reader :value
 
-    # The +Kobako::Usage+ resource accounting for this run.
+    # What the run spent against its caps, as a Usage.
     attr_reader :usage
 
-    def initialize(value:, usage:, stdout:, stderr:, failed:)
+    def initialize(value:, usage:, stdout:, stderr:, failed:) # :nodoc:
       @value = value
       @usage = usage
       @stdout_capture = stdout
@@ -31,22 +26,22 @@ module Kobako
       freeze
     end
 
-    # Returns +true+ iff the run failed — +false+ on the Execution +#eval+ /
-    # +#run+ returned, +true+ on the one a raised error carries.
+    # Whether the run failed: +false+ on the Execution #eval or #run
+    # returned, +true+ on the one a raised error carries.
     def failed? = @failed
 
-    # Bytes the guest wrote to stdout during this run as a UTF-8 String,
-    # clipped at +stdout_limit+; the content carries no truncation sentinel,
-    # so use +#stdout_truncated?+ to observe overflow.
+    # What the guest wrote to stdout, up to +stdout_limit+ bytes: a UTF-8
+    # String, or a binary one when the bytes are not valid UTF-8. The text
+    # carries no sign it was cut; #stdout_truncated? says so.
     def stdout = @stdout_capture.bytes
 
-    # Bytes the guest wrote to stderr during this run. Mirror of #stdout.
+    # What the guest wrote to stderr; see #stdout.
     def stderr = @stderr_capture.bytes
 
-    # Returns +true+ iff stdout capture reached +stdout_limit+ during this run.
+    # Whether stdout reached +stdout_limit+.
     def stdout_truncated? = @stdout_capture.truncated?
 
-    # Returns +true+ iff stderr capture reached +stderr_limit+ during this run.
+    # Whether stderr reached +stderr_limit+.
     def stderr_truncated? = @stderr_capture.truncated?
   end
 end

data/lib/kobako/extension.rb

@@ -1,48 +1,32 @@
 # frozen_string_literal: true
 
 module Kobako
-  # Kobako::Extension — a guest idiom paired with an optional host backend,
-  # installed on a Sandbox via +Sandbox#install+. It composes the existing
-  # +#preload+ (the guest +source+) and +#bind+ (the +backend+) verbs into
-  # one setup unit, so guest code sees a native-style constant whose pure
-  # methods run in-guest and whose privileged methods dispatch to the
-  # backend.
+  # Guest source paired with an optional host backend, installed with
+  # Sandbox#install: the guest sees one constant whose pure methods run in the
+  # guest and whose privileged ones call the backend. Any object answering the
+  # same four readers installs the same way.
   #
-  # The four readers form the contract +#install+ duck-types on:
-  #
-  #   * +name+ — a Symbol matching +/\A[A-Z]\w*\z/+, the preloaded snippet's
-  #     canonical backtrace name and the +depends_on+ match key. Independent
-  #     of any bound path.
-  #   * +source+ — the mruby idiom as a String; always present, since an
-  #     Extension always carries a guest idiom. A host object with no idiom
-  #     is bound with +#bind+ directly.
-  #   * +backend+ — an +Extension::Backend+ or +nil+ for a pure-guest
-  #     Extension.
-  #   * +depends_on+ — Symbol names of Extensions that must also be
-  #     installed, checked for presence at the first invocation.
-  #
-  # +Kobako::Extension+ is the bundled value type; any object exposing the
-  # four readers is equally valid, so a Host App or gem may supply its own.
+  # [+name+]        A constant-form Symbol: the snippet's backtrace name, and
+  #                 what another Extension's +depends_on+ names.
+  # [+source+]      The mruby source, a String. A host object with no source
+  #                 is bound with Sandbox#bind instead.
+  # [+backend+]     A Backend, or +nil+ for an Extension that runs entirely in
+  #                 the guest.
+  # [+depends_on+]  Names of Extensions that must also be installed, checked
+  #                 at the first invocation.
   class Extension < Data.define(:name, :source, :backend, :depends_on)
-    # Kobako::Extension::Backend — the host attachment of an Extension,
-    # pairing +path+ (the constant path the backend binds at, single-segment
-    # +"File"+ or nested +"MyApp::Store"+, spelling the guest constant the
-    # idiom routes to) with the source of the bound object, declared by
-    # explicit keyword:
+    # The host object an Extension's constant at +path+ calls, such as
+    # <tt>"MyApp::Store"</tt>, given by keyword:
     #
-    #   * +object:+ — a static object, fixed for the Sandbox's life.
-    #   * +provider:+ — a no-argument callable invoked once per invocation to
-    #     yield that invocation's object, so a fresh object backs the path
-    #     every invocation. A provider that raises propagates its exception to
-    #     the invocation caller and leaves the guest unrun; the next
-    #     invocation resolves it afresh.
-    #   * neither — a fillable, defaulting to +Kobako::Unresolved+ until the
-    #     host supplies the invocation's object.
+    # [+object:+]   One object for the Sandbox's life.
+    # [+provider:+] A callable taking no arguments, called once per invocation
+    #               for that invocation's object. If it raises, the exception
+    #               reaches the caller and the guest does not run.
+    # [neither]     A fillable Service, supplied per invocation through
+    #               Context#bind.
     #
-    # The kind is chosen by keyword, never inferred from whether the value is
-    # callable, so a static object that is itself callable is expressed
-    # directly with +object:+. Giving both +object:+ and +provider:+ raises
-    # +ArgumentError+.
+    # The keyword decides the kind, so a callable object meant as itself is
+    # given as +object:+. Giving both raises ArgumentError.
     class Backend < Data.define(:path, :object, :provider)
       def initialize(path:, object: nil, provider: nil)
         if !object.nil? && !provider.nil?
@@ -54,8 +38,7 @@ module Kobako
       end
     end
 
-    # +backend+ and +depends_on+ default to absent so the common
-    # pure-idiom and single-backend shapes stay terse.
+    # +backend+ defaults to none, and +depends_on+ to no other Extension.
     def initialize(name:, source:, backend: nil, depends_on: [])
       super
     end

data/lib/kobako/handle.rb

@@ -1,19 +1,16 @@
 # frozen_string_literal: true
 
 module Kobako
-  # A Capability Handle as it crosses the wire (ext 0x01, laid out in
-  # {docs/wire-codec.md}[link:../../docs/wire-codec.md]), in either
-  # direction. Host App code cannot construct one: +.new+ is private and
-  # +#with+ removed, so no Handle is ever made from a caller-chosen id.
-  # The guest's +Kobako::Handle+ shares only the name.
+  # A guest-held reference to a host object, named by id. Host code cannot
+  # construct one, so no Handle is ever made from a caller-chosen id.
   class Handle < Data.define(:id)
-    # ID 0 is the invalid sentinel and is never allocated.
+    # The smallest id; 0 never names a Handle.
     MIN_ID = 1
-    # The positive half of a signed 32-bit integer, so an id fits either
-    # side of the wire unchanged.
+    # The largest id, the positive half of a signed 32-bit integer; an
+    # invocation needing more raises HandleExhaustedError.
     MAX_ID = 0x7fff_ffff
 
-    def initialize(id:)
+    def initialize(id:) # :nodoc:
       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)
 
@@ -23,9 +20,7 @@ module Kobako
     private_class_method :new
     undef_method :with
 
-    # The Host Gem's own constructor, for the wire decoder and the Handle
-    # allocator; it runs the same id checks +.new+ would.
-    def self.restore(id)
+    def self.restore(id) # :nodoc:
       allocate.tap { |handle| handle.send(:initialize, id: id) }
     end
   end

data/lib/kobako/outcome.rb

@@ -4,15 +4,7 @@ require_relative "codec"
 require_relative "transport/error"
 
 module Kobako
-  # Host-facing boundary for the invocation outcome the native side split
-  # off the core envelope. Takes the arm it named plus the fields that arm
-  # carries, and settles the invocation the way a host does: return the
-  # value, or raise the exception the failure attributes to.
-  #
-  # This is the two-step attribution decision. The wire framing belongs to
-  # the native side; the payload codec at +Kobako::Codec+ decodes only
-  # the one arm that carries a value.
-  module Outcome
+  module Outcome # :nodoc:
     # The two +origin+ values a Panic attributes with.
     ORIGIN_SANDBOX = "sandbox"
     ORIGIN_SERVICE = "service"
@@ -24,91 +16,70 @@ module Kobako
     SUBCLASSES = {
       "Kobako::BytecodeError" => BytecodeError,
       "Kobako::UndefinedEntrypointError" => UndefinedEntrypointError,
+      "Kobako::UnsupportedFlagError" => UnsupportedFlagError,
       "Kobako::Transport::Error" => Kobako::Transport::Error,
       "Kobako::NoServiceError" => NoServiceError,
       "Kobako::ServiceArgumentError" => ServiceArgumentError
     }.freeze
+    private_constant :ORIGIN_SANDBOX, :ORIGIN_SERVICE, :SUBCLASSES
 
-    module_function
-
-    # Settle one invocation. +kind+ names the arm, +payload+ is the
-    # codec-encoded value the +:ok+ arm carries, and +panic+ carries
-    # the Panic's fields +[origin, class, message, backtrace, available]+ —
-    # present on the panic arm and absent on every other, which is what
-    # tells the failure that has a record to attribute from apart from the
-    # two that do not. +entrypoint+ is the name this invocation asked for,
-    # which the host knows and the wire therefore never carries.
-    def reify(kind, payload, panic, entrypoint: nil)
-      return decode_value(payload) if kind == :ok
+    # +panic+ is present only on the panic arm, which is what tells it from
+    # the ok arm's +payload+. +entrypoint+ is known to the host and never
+    # carried by the wire.
+    def self.reify(payload, panic, entrypoint: nil)
+      return decode_value(payload) unless panic
 
-      raise panic ? panic_error(panic, entrypoint) : trap_error(kind)
+      raise panic_error(panic, entrypoint)
     end
 
-    # Map a Panic's fields onto the three-layer taxonomy. The fields land
-    # on the exception verbatim — it carries the record rather than a
-    # translation of one.
-    def panic_error(panic, entrypoint)
-      origin, klass, message, backtrace, available = panic
-      selected = error_class(origin, klass)
-      attribution = { origin: origin, klass: klass, backtrace_lines: backtrace }
-      return selected.new(message, **attribution) unless selected == UndefinedEntrypointError
+    # +reify+ is the whole seam: one call settles one invocation, matching
+    # the single entry point the Rust frontend's twin exposes. Everything
+    # else here is how that decision is reached.
+    class << self
+      private
 
-      UndefinedEntrypointError.new(message, name: entrypoint, available: available.map(&:to_sym), **attribution)
-    end
+      # The fields land on the exception verbatim — it carries the record
+      # rather than a translation of one.
+      def panic_error(panic, entrypoint)
+        origin, klass, message, backtrace, available = panic
+        selected = error_class(origin, klass)
+        attribution = { origin: origin, klass: klass, backtrace_lines: backtrace }
+        return selected.new(message, **attribution) unless selected == UndefinedEntrypointError
 
-    # +origin+ picks the branch, and the guest-written class name may
-    # narrow within it so callers can rescue one path specifically. A name
-    # naming a class outside the branch its origin chose is ignored rather
-    # than honoured: what a guest calls its exception must not move the
-    # failure to a layer the attribution did not put it in.
-    def error_class(origin, klass)
-      base = origin == ORIGIN_SERVICE ? ServiceError : SandboxError
-      selected = SUBCLASSES.fetch(klass, base)
-      return base unless selected <= base
+        UndefinedEntrypointError.new(message, name: entrypoint, available: available.map(&:to_sym), **attribution)
+      end
 
-      selected
-    end
+      # +origin+ picks the branch, and the guest-written class name may
+      # narrow within it so callers can rescue one path specifically. A name
+      # naming a class outside the branch its origin chose is ignored rather
+      # than honoured: what a guest calls its exception must not move the
+      # failure to a layer the attribution did not put it in.
+      def error_class(origin, klass)
+        base = origin == ORIGIN_SERVICE ? ServiceError : SandboxError
+        selected = SUBCLASSES.fetch(klass, base)
+        return base unless selected <= base
 
-    # An arm the host cannot settle: the guest wrote nothing, or wrote
-    # bytes the envelope cannot frame. Either leaves nothing to attribute
-    # to, so both walk the trap path; only the absent-versus-present
-    # distinction selects the message.
-    def trap_error(kind)
-      return TrapError.new("Sandbox exited without producing a result") if kind == :absent
+        selected
+      end
 
-      TrapError.new(
-        "Sandbox produced an unrecognised result; the runtime is corrupted, " \
-        "discard this Sandbox before another invocation"
-      )
-    end
+      # A decode fault means the framing was fine but the carried value is
+      # unrepresentable.
+      def decode_value(payload)
+        Kobako::Codec::Decoder.decode(payload)
+      rescue Kobako::Codec::Error => e
+        raise wire_error("Sandbox produced an invalid result value", diagnostic: e.message)
+      end
 
-    # The ok arm's value — the one position a payload codec still
-    # owns on this path. A decode fault means the framing was fine but the
-    # carried value is unrepresentable.
-    def decode_value(payload)
-      Kobako::Codec::Decoder.decode(payload)
-    rescue Kobako::Codec::Error => e
-      raise wire_error("Sandbox produced an invalid result value", diagnostic: e.message)
+      # No guest class stands behind a result kobako cannot decode, so
+      # +klass+ names the host class raised.
+      def wire_error(message, diagnostic: nil)
+        Kobako::Transport::Error.new(
+          message,
+          origin: ORIGIN_SANDBOX,
+          klass: "Kobako::Transport::Error",
+          diagnostic: diagnostic
+        )
+      end
     end
-
-    # Lift a wire violation the host detected to the real
-    # +Kobako::Transport::Error+ class so callers can +rescue+ it
-    # specifically instead of pattern-matching on +error.klass+. The
-    # +klass+ field is still populated so existing operator-side tooling
-    # that greps on the string continues to work.
-    def wire_error(message, diagnostic: nil)
-      Kobako::Transport::Error.new(
-        message,
-        origin: ORIGIN_SANDBOX,
-        klass: "Kobako::Transport::Error",
-        diagnostic: diagnostic
-      )
-    end
-
-    # +reify+ is the whole seam: one call settles one invocation, matching
-    # the single entry point the Rust frontend's twin exposes. Everything
-    # else here is how that decision is reached.
-    private_class_method :panic_error, :error_class, :trap_error, :decode_value, :wire_error
-    private_constant :ORIGIN_SANDBOX, :ORIGIN_SERVICE, :SUBCLASSES
   end
 end

data/lib/kobako/payload/arguments.rb

@@ -4,19 +4,7 @@ require_relative "../codec"
 
 module Kobako
   module Payload
-    # The invocation arguments a Call or a Run carries: a 2-element
-    # msgpack array, +args+ then +kwargs+. Both elements are always
-    # present, so field positions stay stable when either is empty.
-    #
-    # The positional-versus-keyword split lives here rather than in the
-    # core envelope because it is Ruby's call semantics, not the wire's.
-    # SPEC pins +kwargs+ keys to Symbols; the invariant is enforced at
-    # construction so the value object is the single source of truth.
-    #
-    # Built on the +class X < Data.define(...)+ subclass form so the class
-    # body is fully Steep-visible; see +.rubocop.yml+ for the
-    # rationale.
-    class Arguments < Data.define(:args, :kwargs)
+    class Arguments < Data.define(:args, :kwargs) # :nodoc:
       def initialize(args: [], kwargs: {})
         raise ArgumentError, "payload args must be Array" unless args.is_a?(Array)
 
@@ -30,9 +18,6 @@ module Kobako
         Codec::Encoder.encode([args, kwargs])
       end
 
-      # Decode +bytes+ into an Arguments. Raises +Codec::InvalidTypeError+ when
-      # the payload is not the expected 2-element msgpack array, or when the
-      # construction invariants reject the decoded fields.
       def self.decode(bytes)
         Codec::Decoder.decode(bytes) do |frame|
           unless frame.is_a?(Array) && frame.length == 2