kobako 0.1.2 → 0.2.0

data/ext/kobako/src/wasm.rs

@@ -4,22 +4,27 @@
 //
 //   Kobako::Wasm::Instance — wraps wasmtime::Instance + cached TypedFuncs
 //
-// constructed via `Kobako::Wasm::Instance.from_path(path)`. 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
+// 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.
-//   * `host_state`  — HostState (per-Store context) + StoreCell wrapper.
+//   * `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_rpc_call` host-import dispatch helpers.
+//   * `dispatch`    — `__kobako_dispatch` host-import dispatch helpers.
 //
 // This file is the façade: it owns the Ruby error class lazy-resolvers,
-// the `wasm_err` constructor shared by every submodule, and the Ruby
-// init() that registers `Kobako::Wasm::Instance` and its methods.
+// 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;
@@ -47,10 +52,36 @@ pub(crate) static WASM_ERROR: Lazy<ExceptionClass> = Lazy::new(|ruby| {
     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
+/// SPEC.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
+/// 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
 // ---------------------------------------------------------------------------
@@ -60,21 +91,21 @@ 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`).
+    // produced (e.g. fresh clone before `rake compile`). TimeoutError and
+    // MemoryLimitError carry the SPEC.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, 1))?;
-    instance.define_method("alloc", method!(Instance::alloc, 1))?;
-    instance.define_method("write_memory", method!(Instance::write_memory, 2))?;
-    instance.define_method("read_memory", method!(Instance::read_memory, 2))?;
-    instance.define_method("run", method!(Instance::run_call, 0))?;
-    instance.define_method("take_outcome", method!(Instance::take_outcome, 0))?;
-    instance.define_method("set_registry", method!(Instance::set_registry, 1))?;
-    instance.define_method("setup_wasi_pipes", method!(Instance::setup_wasi_pipes, 4))?;
-    instance.define_method("take_stdout", method!(Instance::take_stdout, 0))?;
-    instance.define_method("take_stderr", method!(Instance::take_stderr, 0))?;
+    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("stdout", method!(Instance::stdout, 0))?;
+    instance.define_method("stderr", method!(Instance::stderr, 0))?;
+    instance.define_method("outcome!", method!(Instance::outcome, 0))?;
 
     Ok(())
 }

data/lib/kobako/capture.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+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]).
+  #
+  # 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.
+  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.
+    def initialize(bytes:, truncated:)
+      @bytes = bytes
+      @truncated = truncated
+      freeze
+    end
+
+    # Returns +true+ iff the underlying capture channel exceeded its
+    # configured cap during the originating +Sandbox#run+
+    # ({SPEC.md B-04}[link:../../SPEC.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-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".
+    EMPTY = new(bytes: "", truncated: false)
+  end
+end

data/lib/kobako/codec/decoder.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "msgpack"
+
+require_relative "error"
+require_relative "factory"
+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).
+    #
+    # Translates msgpack gem exceptions into the kobako error taxonomy
+    # ({Truncated}, {InvalidType}, {InvalidEncoding}, {UnsupportedType}) so
+    # callers can pattern-match on the SPEC's wire-violation categories
+    # without leaking the gem's internal exception classes.
+    #
+    # Public API is a single function — {.decode}. The decoder is
+    # stateless; the +MessagePack::Unpacker+ instance is built per call
+    # because callers always decode exactly one wire value at a time.
+    module Decoder
+      # Decode +bytes+ into one Ruby value and validate transitively
+      # against the SPEC type mapping. Raises {Truncated}, {InvalidType},
+      # or {InvalidEncoding} on wire violations.
+      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).
+      rescue ::MessagePack::UnknownExtTypeError, ::MessagePack::MalformedFormatError,
+             ::MessagePack::StackError, ::ArgumentError => e
+        raise InvalidType, e.message
+      # +UnpackError+ is the gem's umbrella class for short-read /
+      # incomplete-buffer faults; +EOFError+ covers underflow at the
+      # buffer edge.
+      rescue ::MessagePack::UnpackError, ::EOFError => e
+        raise Truncated, e.message
+      rescue ::EncodingError => e
+        raise InvalidEncoding, e.message
+      end
+
+      # SPEC pins +str+ family payloads to UTF-8 (Wire Codec → 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
+      # str-typed leaf via {Utils.assert_utf8!}. {Kobako::RPC::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.
+      class << self
+        private
+
+        def validate_utf8!(value)
+          case value
+          when String then Utils.assert_utf8!(value, "str payload") if value.encoding == Encoding::UTF_8
+          when Array  then value.each { |v| validate_utf8!(v) }
+          when Hash   then value.each { |pair| validate_utf8!(pair) }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/kobako/codec/encoder.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "msgpack"
+
+require_relative "error"
+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).
+    #
+    # The codec backbone is the official +msgpack+ gem: integers, floats,
+    # strings, arrays, and maps go through the gem's narrowest-encoding
+    # logic; the three kobako-specific ext types (0x00 Symbol, 0x01
+    # Capability Handle, 0x02 Exception envelope) are registered on
+    # the cached {Kobako::Codec::Factory} singleton.
+    #
+    # Public API is a single function — {.encode}. The codec is stateless;
+    # there is no buffer accumulator and no streaming write API. Callers
+    # that need to concatenate multiple encodings build the bytes
+    # themselves.
+    module Encoder
+      # Encode +value+ to wire bytes (binary-encoded String).
+      # Wire violations surface as +UnsupportedType+: SPEC's 12-entry type
+      # mapping is a closed set, and anything outside it is rejected by
+      # the msgpack gem itself (arbitrary objects raise +NoMethodError+
+      # from missing +to_msgpack+, integers outside i64..u64 raise
+      # +RangeError+).
+      def self.encode(value)
+        Factory.dump(value)
+      rescue ::RangeError, ::NoMethodError => e
+        raise UnsupportedType, e.message
+      end
+    end
+  end
+end

data/lib/kobako/codec/error.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+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
+    # subclass of {Error} so callers can pattern-match on the specific
+    # fault while still rescuing all codec faults via this base class.
+    #
+    # Higher layers (e.g. the Sandbox dispatch loop) translate these into
+    # the public {Kobako::SandboxError} / {Kobako::TrapError} taxonomy.
+    class Error < StandardError; end
+
+    # Input ended before the type prefix or payload was fully consumed.
+    class Truncated < Error; end
+
+    # The type byte at the current position is not in the 12-entry kobako
+    # type mapping (e.g. an unknown ext code, or a reserved msgpack tag).
+    class InvalidType < Error; end
+
+    # A msgpack `str` payload was not valid UTF-8, or an ext 0x00 Symbol
+    # payload was not valid UTF-8 — both are wire violations per SPEC.
+    class InvalidEncoding < Error; end
+
+    # The encoder was handed a Ruby object whose type has no wire
+    # representation (e.g. Range, Time). Higher layers may catch this
+    # and re-route the value through Handle allocation, but at the
+    # codec level it is a hard error.
+    class UnsupportedType < Error; end
+  end
+end

data/lib/kobako/codec/factory.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+require "singleton"
+require "forwardable"
+require "msgpack"
+
+require_relative "error"
+require_relative "utils"
+require_relative "../rpc/handle"
+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).
+    #
+    # The factory is the single place in the host gem that touches the
+    # msgpack API — both {Encoder} and {Decoder} delegate through it, so
+    # the three kobako ext codes (0x00 Symbol, 0x01 Capability Handle,
+    # 0x02 Exception envelope) are configured exactly once at first use.
+    #
+    # Lifecycle is owned by +Singleton+ from the Ruby standard library:
+    # +Factory.instance+ is lazy, thread-safe, and process-wide. Class-level
+    # +Factory.dump+ / +Factory.load+ shortcuts are exposed via
+    # +SingleForwardable+ so callers do not have to spell the +.instance+
+    # hop at every call site; the instance-level +#dump+ / +#load+ are in
+    # turn delegated to the wrapped +MessagePack::Factory+ via +Forwardable+.
+    class Factory
+      include Singleton
+      extend Forwardable
+      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.
+      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.
+      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.
+      EXT_ERRENV = 0x02
+      private_constant :EXT_SYMBOL, :EXT_HANDLE, :EXT_ERRENV
+
+      # Instance-level pass-through onto the wrapped +MessagePack::Factory+.
+      # Spelled +def_instance_delegators+ rather than +def_delegators+ because
+      # the class also extends +SingleForwardable+ (see the +extend+ block
+      # above), which defines its own +def_delegators+ that shadows
+      # +Forwardable+'s — the unambiguous forms keep both delegation tiers
+      # wired to the right scope.
+      def_instance_delegators :@factory, :dump, :load
+
+      # Class-level shortcuts so callers can write +Factory.dump(v)+ instead
+      # of +Factory.instance.dump(v)+; both resolve to the same singleton.
+      def_single_delegators :instance, :dump, :load
+
+      def initialize
+        @factory = MessagePack::Factory.new
+        register_symbol
+        register_handle
+        register_fault
+      end
+
+      private
+
+      def register_symbol
+        @factory.register_type(
+          EXT_SYMBOL, Symbol,
+          packer: method(:pack_symbol),
+          unpacker: method(:unpack_symbol)
+        )
+      end
+
+      # Symbol-to-name packer — extracted to a real method so Steep can
+      # resolve the proc shape without tripping on +lambda(&:name)+'s
+      # +Symbol#to_proc+ inference path.
+      def pack_symbol(symbol)
+        symbol.name
+      end
+
+      # Validate the ext-0x00 payload as UTF-8 and intern. Raises
+      # {InvalidEncoding} on invalid bytes — SPEC forbids the
+      # binary-encoding fallback that msgpack-gem's default unpacker
+      # would otherwise apply. The re-tag step lives here because the
+      # msgpack ext-type unpacker hands us binary bytes; the assertion
+      # itself is shared with {Decoder} via {Utils.assert_utf8!}.
+      def unpack_symbol(payload)
+        name = payload.b.force_encoding(Encoding::UTF_8)
+        Utils.assert_utf8!(name, "ext 0x00 payload")
+        name.to_sym
+      end
+
+      def register_handle
+        @factory.register_type(
+          EXT_HANDLE, RPC::Handle,
+          packer: ->(handle) { [handle.id].pack("N") },
+          unpacker: ->(payload) { unpack_handle(payload) }
+        )
+      end
+
+      def register_fault
+        @factory.register_type(
+          EXT_ERRENV, RPC::Fault,
+          packer: ->(fault) { pack_fault(fault) },
+          unpacker: ->(payload) { unpack_fault(payload) }
+        )
+      end
+
+      # Peel off the fixext-4 frame, hand the bytes to +RPC::Handle.new+, and
+      # translate the +ArgumentError+ raised by Handle's invariants into
+      # a wire-layer +InvalidType+ via {Codec::Utils.wire_boundary}.
+      # The Value Object owns the id-range contract; this method only
+      # owns the frame shape.
+      def unpack_handle(payload)
+        bytes = payload.b
+        raise InvalidType, "ext 0x01 payload must be 4 bytes, got #{bytes.bytesize}" unless bytes.bytesize == 4
+
+        id = bytes.unpack1("N") # : Integer
+        Codec::Utils.wire_boundary { RPC::Handle.new(id) }
+      end
+
+      # Encode the inner ext-0x02 map via {Encoder} (not +factory.dump+) so
+      # the embedded payload flows through the same boundary as a top-level
+      # encode — nested kobako values (Handle, nested Fault) reach the
+      # registered ext-type packers via the cached singleton.
+      def pack_fault(fault)
+        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
+      # +factory.load+) so the embedded +str+ payloads flow through the
+      # same UTF-8 validation as a top-level decode.
+      #
+      # This establishes a runtime cycle Factory → Decoder → Factory: the
+      # singleton instance feeds +Decoder.decode+, which re-enters this
+      # method when a nested ext 0x02 appears inside +details+. The recursion
+      # is bounded by msgpack nesting depth — identical to nested Array /
+      # Hash payloads — so no extra guard is needed. Do not switch back to
+      # +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, "ext 0x02 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"])
+        end
+      end
+    end
+  end
+end

data/lib/kobako/codec/utils.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require_relative "error"
+
+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:
+    #
+    #   - {Decoder} validates +str+ family payloads as it walks the
+    #     decoded value tree.
+    #   - {Factory} validates the +ext 0x00+ Symbol payload after
+    #     re-tagging the binary bytes as UTF-8.
+    #
+    # Encoding setup (re-tagging binary as UTF-8 when needed) stays at
+    # the caller — only the assertion shape is shared. The helper does
+    # not mutate +string+; it only inspects +String#valid_encoding?+
+    # against +string+'s current encoding tag.
+    module Utils
+      module_function
+
+      # Raise {InvalidEncoding} unless +string+'s bytes are valid under
+      # its current encoding tag. +label+ is the caller-supplied prefix
+      # for the error message (e.g. +"str payload"+, +"ext 0x00 payload"+).
+      def assert_utf8!(string, label)
+        return if string.valid_encoding?
+
+        raise InvalidEncoding, "#{label} is not valid UTF-8"
+      end
+
+      # Run +block+ at the wire boundary: every wire Value Object
+      # (Handle / Fault / Request / Response / Panic) raises
+      # +ArgumentError+ when an invariant is violated at construction,
+      # and the wire boundary surfaces those violations to callers as
+      # {InvalidType} so the public taxonomy stays
+      # {Kobako::Codec::Error} and never leaks +ArgumentError+ from the
+      # Ruby standard library.
+      #
+      # Wrap any block that constructs a wire Value Object from decoded
+      # bytes with this helper to keep the five decode sites uniform —
+      # Request / Response in +Kobako::RPC+, Panic map in
+      # +Kobako::Outcome+, and the Handle / Fault ext-type unpackers in
+      # {Factory}. Do not use it for general-purpose validation outside
+      # the wire boundary — host-layer +ArgumentError+ values should
+      # propagate unchanged.
+      def wire_boundary
+        yield
+      rescue ::ArgumentError => e
+        raise InvalidType, e.message
+      end
+    end
+  end
+end

data/lib/kobako/codec.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+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:
+  # +Kobako::RPC+ pins the RPC framing (Request / Response)
+  # and +Kobako::Outcome+ owns the per-+#run+ outcome envelope (Result
+  # body / Panic map).
+  #
+  # Backed by the official +msgpack+ gem via {Factory}; {Encoder} and
+  # {Decoder} are thin wrappers that register the three kobako-specific
+  # ext types (0x00 Symbol, 0x01 Capability Handle, 0x02 Exception
+  # envelope) on a single +MessagePack::Factory+ instance. The Rust side
+  # mirrors this layer as the +codec+ module in the +kobako-wasm+ crate;
+  # the ext-code constants live as module-private values on {Factory}
+  # alongside +codec::EXT_SYMBOL+ / +codec::EXT_HANDLE+ /
+  # +codec::EXT_ERRENV+ on that side.
+  module Codec
+  end
+end
+
+require_relative "codec/utils"
+require_relative "codec/factory"
+require_relative "codec/encoder"
+require_relative "codec/decoder"

data/lib/kobako/errors.rb

@@ -34,8 +34,31 @@ module Kobako
   # (trap, OOM, unreachable) or when the wire layer detected a structural
   # 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:
+  #
+  #   * {TimeoutError}     — wall-clock +timeout+ exceeded (E-19).
+  #   * {MemoryLimitError} — guest +memory.grow+ would exceed
+  #                          +memory_limit+ (E-20).
+  #
+  # 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.
   class TrapError < Error; end
 
+  # Wall-clock timeout cap exhausted. {SPEC.md E-19}[link:../../SPEC.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]:
+  # 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.
+  class MemoryLimitError < TrapError; 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
   # host-side wire decode failure on an otherwise valid outcome tag.
@@ -74,7 +97,7 @@ module Kobako
 
   # HandleTable lookup-failure error (unknown id passed to #fetch /
   # #release). A SandboxError subclass: per the wire-layer rule, an
-  # unknown Handle id surfaces as a `type="undefined"` Response.err
+  # unknown Handle id surfaces as a `type="undefined"` Response.error
   # envelope inside RpcDispatcher and never reaches the Host App
   # directly; outside that path (e.g. tests poking the HandleTable
   # directly), it surfaces as a SandboxError.

data/lib/kobako/outcome/panic.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Kobako
+  module Outcome
+    # SPEC.md → Outcome Envelope → Panic envelope ({SPEC.md Outcome
+    # Envelope}[link:../../../SPEC.md]). Wire-shaped failure record
+    # carried in the OUTCOME_BUFFER when the guest run terminates with
+    # an uncaught top-level exception.
+    #
+    # This is the **wire data**, not a raisable Ruby exception. The
+    # mapping from Panic to a three-layer Ruby exception (TrapError /
+    # SandboxError / ServiceError) happens at +Kobako::Outcome.decode+
+    # via +build_panic_error+ — callers never raise +Panic+ directly.
+    #
+    # The five fields mirror SPEC: +origin+ ("sandbox" / "service"),
+    # +klass+ (the guest-side exception class name as a String),
+    # +message+, +backtrace+ (Array of String), +details+ (any
+    # wire-legal value, nil when absent). Required-field validation is
+    # enforced at construction; the +ORIGIN_SANDBOX+ / +ORIGIN_SERVICE+
+    # constants pin the two SPEC-defined origin values.
+    #
+    # Built on the +class X < Data.define(...)+ subclass form so the
+    # class body is fully Steep-visible; ruby/rbs upstream documents
+    # this as the Steep-friendly shape and the +Style/DataInheritance+
+    # cop is disabled on that basis (see +.rubocop.yml+).
+    class Panic < Data.define(:origin, :klass, :message, :backtrace, :details)
+      ORIGIN_SANDBOX = "sandbox"
+      ORIGIN_SERVICE = "service"
+
+      def initialize(origin:, klass:, message:, backtrace: [], details: nil)
+        raise ArgumentError, "Panic origin must be String"  unless origin.is_a?(String)
+        raise ArgumentError, "Panic class must be String"   unless klass.is_a?(String)
+        raise ArgumentError, "Panic message must be String" unless message.is_a?(String)
+        unless backtrace.is_a?(Array) && backtrace.all?(String)
+          raise ArgumentError, "Panic backtrace must be Array of String"
+        end
+
+        super
+      end
+    end
+  end
+end