kobako 0.2.1 → 0.3.0

data/ext/kobako/src/wasm.rs

@@ -32,10 +32,23 @@ mod host_state;
 mod instance;
 
 use magnus::value::Lazy;
-use magnus::{function, method, prelude::*, Error as MagnusError, ExceptionClass, RModule, Ruby};
+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).
 // ---------------------------------------------------------------------------
@@ -69,14 +82,14 @@ pub(crate) fn wasm_err(ruby: &Ruby, msg: impl Into<String>) -> MagnusError {
 }
 
 /// Construct a `Kobako::Wasm::TimeoutError` magnus error. Surfaces the
-/// SPEC.md E-19 wall-clock cap path so the Sandbox layer can rewrap it
+/// 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 SPEC.md E-20 linear-memory cap path so the Sandbox layer can
+/// 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())
@@ -92,7 +105,7 @@ pub fn init(ruby: &Ruby, kobako: RModule) -> Result<(), MagnusError> {
     // 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 SPEC.md B-01 per-run cap paths up to the
+    // 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)?;
@@ -102,7 +115,8 @@ pub fn init(ruby: &Ruby, kobako: RModule) -> Result<(), MagnusError> {
     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("run", method!(Instance::run, 2))?;
+    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))?;

data/lib/kobako/capture.rb

@@ -2,15 +2,16 @@
 
 module Kobako
   # Host-side captured prefix of guest stdout / stderr produced during a
-  # single +Kobako::Sandbox#run+, paired with the truncation flag the WASI
-  # pipe sets when the guest wrote past the configured per-channel cap
-  # ({SPEC.md B-04}[link:../../SPEC.md]).
+  # single +Kobako::Sandbox+ invocation, paired with the truncation flag
+  # the WASI pipe sets when the guest wrote past the configured per-channel
+  # cap ({docs/behavior.md B-04}[link:../../docs/behavior.md]).
   #
   # 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-run
-  # sentinel that +Sandbox+ uses before any +#run+ has executed.
+  # 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
 
@@ -24,8 +25,8 @@ module Kobako
     end
 
     # Returns +true+ iff the underlying capture channel exceeded its
-    # configured cap during the originating +Sandbox#run+
-    # ({SPEC.md B-04}[link:../../SPEC.md]).
+    # configured cap during the originating +Sandbox+ invocation
+    # ({docs/behavior.md B-04}[link:../../docs/behavior.md]).
     def truncated? = @truncated
 
     # Construct a Capture from ext-provided binary bytes. Coerces +bytes+
@@ -38,9 +39,10 @@ module Kobako
       new(bytes: copy, truncated: truncated)
     end
 
-    # Pre-run sentinel ({SPEC.md B-05}[link:../../SPEC.md]). Empty UTF-8
-    # bytes and +truncated? == false+; reused by every fresh +Sandbox+ and
-    # by +Sandbox#run+ between invocations to denote "no capture yet".
+    # 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
+    # yet".
     EMPTY = new(bytes: "", truncated: false)
   end
 end

data/lib/kobako/codec/decoder.rb

@@ -9,7 +9,7 @@ require_relative "utils"
 module Kobako
   module Codec
     # Module-level entry point for the host side of the kobako wire
-    # (SPEC.md → Wire Codec → Type Mapping).
+    # ({docs/wire-codec.md}[link:../../../docs/wire-codec.md] § Type Mapping).
     #
     # Translates msgpack gem exceptions into the kobako error taxonomy
     # ({Truncated}, {InvalidType}, {InvalidEncoding}, {UnsupportedType}) so
@@ -42,7 +42,8 @@ module Kobako
         raise InvalidEncoding, e.message
       end
 
-      # SPEC pins +str+ family payloads to UTF-8 (Wire Codec → str/bin
+      # SPEC pins +str+ family payloads to UTF-8
+      # ({docs/wire-codec.md}[link:../../../docs/wire-codec.md] § str/bin
       # 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

data/lib/kobako/codec/encoder.rb

@@ -8,7 +8,7 @@ require_relative "factory"
 module Kobako
   module Codec
     # Module-level entry point for the host side of the kobako wire
-    # (SPEC.md → Wire Codec → Type Mapping).
+    # ({docs/wire-codec.md}[link:../../../docs/wire-codec.md] § Type Mapping).
     #
     # The codec backbone is the official +msgpack+ gem: integers, floats,
     # strings, arrays, and maps go through the gem's narrowest-encoding

data/lib/kobako/codec/error.rb

@@ -4,8 +4,9 @@ module Kobako
   module Codec
     # Base class for all wire-codec faults raised by the pure-Ruby host codec.
     #
-    # The wire codec implements the binary contract pinned in SPEC.md
-    # (Wire Codec → Type Mapping). Every wire violation surfaces as a
+    # The wire codec implements the binary contract pinned in
+    # {docs/wire-codec.md}[link:../../../docs/wire-codec.md] § Type Mapping.
+    # Every wire violation surfaces as a
     # subclass of {Error} so callers can pattern-match on the specific
     # fault while still rescuing all codec faults via this base class.
     #

data/lib/kobako/codec/factory.rb

@@ -12,7 +12,8 @@ require_relative "../rpc/fault"
 module Kobako
   module Codec
     # Cached +MessagePack::Factory+ that owns the kobako wire ext-type
-    # registration (SPEC.md → Wire Codec → Ext Types).
+    # registration ({docs/wire-codec.md}[link:../../../docs/wire-codec.md]
+    # § Ext Types).
     #
     # The factory is the single place in the host gem that touches the
     # msgpack API — both {Encoder} and {Decoder} delegate through it, so
@@ -31,16 +32,19 @@ module Kobako
       extend SingleForwardable
 
       # MessagePack ext type code reserved for Symbol
-      # (SPEC.md → Wire Codec → Ext Types → ext 0x00). Class-private —
-      # mirrors +codec::EXT_SYMBOL+ on the Rust side.
+      # ({docs/wire-codec.md}[link:../../../docs/wire-codec.md] § Ext Types
+      # → ext 0x00). Class-private — mirrors +codec::EXT_SYMBOL+ on the
+      # Rust side.
       EXT_SYMBOL = 0x00
       # MessagePack ext type code reserved for Capability Handle
-      # (SPEC.md → Wire Codec → Ext Types → ext 0x01). Class-private —
-      # mirrors +codec::EXT_HANDLE+ on the Rust side.
+      # ({docs/wire-codec.md}[link:../../../docs/wire-codec.md] § Ext Types
+      # → ext 0x01). Class-private — mirrors +codec::EXT_HANDLE+ on the
+      # Rust side.
       EXT_HANDLE = 0x01
       # MessagePack ext type code reserved for Exception envelope
-      # (SPEC.md → Wire Codec → Ext Types → ext 0x02). Class-private —
-      # mirrors +codec::EXT_ERRENV+ on the Rust side.
+      # ({docs/wire-codec.md}[link:../../../docs/wire-codec.md] § Ext Types
+      # → ext 0x02). Class-private — mirrors +codec::EXT_ERRENV+ on the
+      # Rust side.
       EXT_ERRENV = 0x02
       private_constant :EXT_SYMBOL, :EXT_HANDLE, :EXT_ERRENV
 

data/lib/kobako/codec/utils.rb

@@ -6,8 +6,9 @@ module Kobako
   module Codec
     # Wire-codec helpers shared by the host-side encoders and decoders.
     # The single concern today is UTF-8 assertion at the wire boundary
-    # (SPEC.md → Wire Codec → str/bin Encoding Rules and Ext Types →
-    # ext 0x00). Two call sites lean on this:
+    # ({docs/wire-codec.md}[link:../../../docs/wire-codec.md] § str/bin
+    # Encoding Rules and § Ext Types → ext 0x00). Two call sites lean on
+    # this:
     #
     #   - {Decoder} validates +str+ family payloads as it walks the
     #     decoded value tree.

data/lib/kobako/codec.rb

@@ -4,7 +4,8 @@ require_relative "codec/error"
 
 module Kobako
   # Host-side MessagePack codec for the kobako wire contract — the
-  # byte-level layer (SPEC.md → Wire Codec). Two consumers sit on top:
+  # byte-level layer ({docs/wire-codec.md}[link:../../docs/wire-codec.md]).
+  # Two consumers sit on top:
   # +Kobako::RPC+ pins the RPC framing (Request / Response)
   # and +Kobako::Outcome+ owns the per-+#run+ outcome envelope (Result
   # body / Panic map).

data/lib/kobako/errors.rb

@@ -2,12 +2,12 @@
 
 # Top-level Kobako namespace.
 module Kobako
-  # Three-class error taxonomy (SPEC.md → Error Scenarios).
+  # Three-class error taxonomy (docs/behavior.md § Error Scenarios).
   #
-  # Every `Kobako::Sandbox#run` invocation either returns a value or raises
+  # Every `Kobako::Sandbox` invocation (`#eval` or `#run`) either returns a value or raises
   # exactly one of these three classes. Attribution is decided after the
-  # guest binary returns control to the host (SPEC "Step 1 — Wasm trap"
-  # then "Step 2 — Outcome envelope tag").
+  # guest binary returns control to the host (docs/behavior.md
+  # "Step 1 — Wasm trap" then "Step 2 — Outcome envelope tag").
   #
   # Three top-level branches:
   #
@@ -20,7 +20,7 @@ module Kobako
   #   * {ServiceError}  — service / capability layer (a Service RPC that
   #                       failed and was not rescued inside the script).
   #
-  # Subclasses pinned by SPEC "Error Classes":
+  # Subclasses pinned by docs/behavior.md Error Classes:
   #
   #   * {HandleTableExhausted} < {SandboxError}    — id cap hit (B-21).
   #   * {ServiceError::Disconnected} < {ServiceError} — `:disconnected`
@@ -35,7 +35,7 @@ module Kobako
   # violation that signals a corrupted guest execution environment
   # (zero-length OUTCOME_BUFFER, unknown outcome tag — SPEC E-02 / E-03).
   #
-  # Two named subclasses cover the configured per-run caps from B-01:
+  # Two named subclasses cover the configured per-invocation caps from B-01:
   #
   #   * {TimeoutError}     — wall-clock +timeout+ exceeded (E-19).
   #   * {MemoryLimitError} — guest +memory.grow+ would exceed
@@ -47,13 +47,13 @@ module Kobako
   # first.
   class TrapError < Error; end
 
-  # Wall-clock timeout cap exhausted. {SPEC.md E-19}[link:../../SPEC.md]:
+  # Wall-clock timeout cap exhausted. {docs/behavior.md E-19}[link:../../docs/behavior.md]:
   # the absolute deadline +entry_time + timeout+ passed and the next guest
   # wasm safepoint trapped. The Sandbox is unrecoverable after this point;
   # discard and recreate before another execution.
   class TimeoutError < TrapError; end
 
-  # Linear-memory cap exhausted. {SPEC.md E-20}[link:../../SPEC.md]:
+  # Linear-memory cap exhausted. {docs/behavior.md E-20}[link:../../docs/behavior.md]:
   # a guest +memory.grow+ would have pushed linear memory past the
   # configured +memory_limit+. The Sandbox is unrecoverable after this
   # point; discard and recreate before another execution.
@@ -88,7 +88,7 @@ module Kobako
       @details = details
     end
 
-    # SPEC "Error Classes": ServiceError::Disconnected is raised
+    # docs/behavior.md Error Classes: ServiceError::Disconnected is raised
     # when the RPC target Handle resolves to the `:disconnected` sentinel
     # in the HandleTable (ABA protection rule — id exists but entry was
     # invalidated). E-14.
@@ -103,9 +103,21 @@ module Kobako
   # directly), it surfaces as a SandboxError.
   class HandleTableError < SandboxError; end
 
-  # SPEC "Error Classes": HandleTableExhausted is the canonical
+  # docs/behavior.md Error Classes: HandleTableExhausted is the canonical
   # SandboxError subclass for the id-cap-hit path (B-21). Inherits from
   # HandleTableError so a single `rescue Kobako::HandleTableError` covers
   # both lookup-failure and cap-exhaustion paths.
   class HandleTableExhausted < HandleTableError; end
+
+  # docs/behavior.md Error Classes: BytecodeError is the SandboxError
+  # subclass raised when a `#preload(binary:)` snippet fails structural
+  # validation during the first invocation's snippet replay against a
+  # fresh `mrb_state` (E-37 RITE version mismatch, E-38 corrupt body).
+  # Bytecode that loads cleanly and then raises at top level is E-36
+  # and surfaces as plain `SandboxError` with the natural mruby class
+  # preserved. Inherits from SandboxError so a single
+  # `rescue Kobako::SandboxError` covers both source and bytecode
+  # snippet failures while callers wanting bytecode-specific handling
+  # can `rescue Kobako::BytecodeError` directly.
+  class BytecodeError < SandboxError; end
 end

data/lib/kobako/invocation.rb

@@ -0,0 +1,112 @@
+# 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/outcome/panic.rb

@@ -2,8 +2,8 @@
 
 module Kobako
   module Outcome
-    # SPEC.md → Outcome Envelope → Panic envelope ({SPEC.md Outcome
-    # Envelope}[link:../../../SPEC.md]). Wire-shaped failure record
+    # Wire-contract Outcome Envelope → Panic envelope ({docs/wire-contract.md
+    # Outcome Envelope}[link:../../../docs/wire-contract.md]). Wire-shaped failure record
     # carried in the OUTCOME_BUFFER when the guest run terminates with
     # an uncaught top-level exception.
     #

data/lib/kobako/outcome.rb

@@ -4,10 +4,10 @@ require_relative "outcome/panic"
 
 module Kobako
   # Host-facing boundary for the OUTCOME_BUFFER produced by
-  # +__kobako_run+. Takes raw outcome bytes — a one-byte tag followed by
+  # +__kobako_eval+. Takes raw outcome bytes — a one-byte tag followed by
   # the msgpack-encoded body — and maps them to either the unwrapped
   # mruby return value or a raised three-layer
-  # ({SPEC.md "Error Scenarios"}[link:../../SPEC.md]) exception.
+  # ({docs/behavior.md Error Scenarios}[link:../../docs/behavior.md]) exception.
   #
   # Self-contained: this module owns the wire framing (tag bytes,
   # body decoding), and the +Panic+ wire record lives at
@@ -24,7 +24,7 @@ module Kobako
   module Outcome
     # First byte of the OUTCOME_BUFFER for the success branch — body is
     # the bare msgpack encoding of the returned value
-    # ({SPEC.md Outcome Envelope}[link:../../SPEC.md]).
+    # ({docs/wire-contract.md Outcome Envelope}[link:../../docs/wire-contract.md]).
     TYPE_VALUE = 0x01
     # First byte of the OUTCOME_BUFFER for the failure branch — body is
     # the msgpack Panic map.
@@ -45,8 +45,8 @@ module Kobako
     end
 
     # TrapError for unknown or absent tag
-    # ({SPEC.md ABI Signatures}[link:../../SPEC.md]: len=0 and unknown-tag
-    # both walk the trap path).
+    # ({docs/wire-codec.md ABI Signatures}[link:../../docs/wire-codec.md]:
+    # len=0 and unknown-tag both walk the trap path).
     def build_trap_error(tag)
       return TrapError.new("guest exited without writing an outcome (len=0)") if tag.nil?
 
@@ -100,7 +100,7 @@ module Kobako
     # Ruby exception. +origin == "service"+ → ServiceError (with the
     # +::Disconnected+ subclass selected when the panic carries the
     # disconnected sentinel —
-    # {SPEC "Error Classes"}[link:../../SPEC.md]); everything else
+    # {docs/behavior.md Error Classes}[link:../../docs/behavior.md]); everything else
     # → SandboxError.
     def build_panic_error(panic)
       panic_target_class(panic).new(
@@ -112,14 +112,21 @@ module Kobako
       )
     end
 
-    # {SPEC "Error Classes"}[link:../../SPEC.md]: when
-    # +origin="service"+ and the panic +class+ field names
-    # +ServiceError::Disconnected+, surface that subclass so callers can
-    # rescue the disconnected path specifically (E-14).
+    # {docs/behavior.md Error Classes}[link:../../docs/behavior.md]: map
+    # the panic +class+ field to the matching Ruby exception subclass so
+    # callers can rescue specific failure paths. +origin="service"+ plus
+    # +class="Kobako::ServiceError::Disconnected"+ selects the
+    # +Disconnected+ subclass (E-14); +origin="sandbox"+ plus
+    # +class="Kobako::BytecodeError"+ selects the +BytecodeError+
+    # subclass (E-37 / E-38). Everything else falls back to the base
+    # class for the origin.
     def panic_target_class(panic)
-      return SandboxError unless panic.origin == Panic::ORIGIN_SERVICE
-
-      panic.klass == "Kobako::ServiceError::Disconnected" ? ServiceError::Disconnected : ServiceError
+      case panic.origin
+      when Panic::ORIGIN_SERVICE
+        panic.klass == "Kobako::ServiceError::Disconnected" ? ServiceError::Disconnected : ServiceError
+      else
+        panic.klass == "Kobako::BytecodeError" ? BytecodeError : SandboxError
+      end
     end
 
     def build_wire_violation_error(message)

data/lib/kobako/rpc/dispatcher.rb

@@ -10,7 +10,7 @@ module Kobako
     # 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 ({SPEC.md B-14}[link:../../../SPEC.md]).
+    # representable return value must be wrapped ({docs/behavior.md B-14}[link:../../../docs/behavior.md]).
     #
     # Entry point:
     #
@@ -22,12 +22,12 @@ module Kobako
       # 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
-      # ({SPEC.md E-xx}[link:../../../SPEC.md]).
+      # ({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,
-      # {SPEC.md E-14}[link:../../../SPEC.md]). Mapped to Response.error with
+      # {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
 
@@ -41,7 +41,7 @@ module Kobako
       # 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
-      # ({SPEC.md B-12}[link:../../../SPEC.md]).
+      # ({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
@@ -57,7 +57,7 @@ module Kobako
       # 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 ({SPEC.md B-12}[link:../../../SPEC.md]):
+      # 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+ →
@@ -86,7 +86,7 @@ module Kobako
         end
       end
 
-      # {SPEC.md B-16}[link:../../../SPEC.md] — An RPC::Handle arriving as a positional or keyword
+      # {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
@@ -139,10 +139,10 @@ module Kobako
       end
 
       # Encode +value+ as a +Response.ok+ envelope. When the value is not
-      # wire-representable per {SPEC.md B-13}[link:../../../SPEC.md]'s type
+      # 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 ({SPEC.md B-14}[link:../../../SPEC.md]). The happy
+      # 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)
@@ -152,7 +152,7 @@ module Kobako
       end
 
       # Allocate +value+ in the Server's HandleTable and return a +Handle+
-      # that the wire codec can carry ({SPEC.md B-14}[link:../../../SPEC.md]).
+      # 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)

data/lib/kobako/rpc/envelope.rb

@@ -8,7 +8,7 @@ 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 (SPEC.md Response Shape) ---
+    # ---------------- Response status bytes (docs/wire-contract.md § Response Shape) ---
 
     # Response variant marker for the success branch.
     STATUS_OK    = 0
@@ -16,7 +16,7 @@ module Kobako
     STATUS_ERROR = 1
 
     # Value object for a single guest-initiated RPC Request
-    # ({SPEC.md Wire Codec → Request}[link:../../../SPEC.md]).
+    # ({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
@@ -66,7 +66,7 @@ module Kobako
     end
 
     # Value object for a single host-side RPC Response
-    # ({SPEC.md Wire Codec → Response}[link:../../../SPEC.md]).
+    # ({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

data/lib/kobako/rpc/fault.rb

@@ -4,8 +4,9 @@ module Kobako
   module RPC
     # Wire-level value object for an ext-0x02 Exception envelope.
     #
-    # SPEC pins the payload (Wire Codec → Ext Types → ext 0x02) to a
-    # msgpack map with exactly three keys:
+    # 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

data/lib/kobako/rpc/handle.rb

@@ -5,8 +5,9 @@ module Kobako
     # 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 (Wire Codec → Ext Types → ext 0x01). ID 0 is reserved as the
-    # invalid sentinel; the maximum valid ID is 0x7fff_ffff (2^31 - 1).
+    # 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