kobako 0.3.0 → 0.5.0

data/lib/kobako/outcome.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "outcome/panic"
+require_relative "transport/error"
 
 module Kobako
   # Host-facing boundary for the OUTCOME_BUFFER produced by
@@ -13,7 +14,7 @@ module Kobako
   # body decoding), and the +Panic+ wire record lives at
   # +Kobako::Outcome::Panic+. The byte-level msgpack codec at
   # +Kobako::Codec+ is invoked for the body itself; otherwise
-  # nothing in +RPC+ participates.
+  # nothing in +Transport+ participates.
   #
   #   * tag 0x01, decode OK                 → return decoded value
   #   * tag 0x01, decode fails              → SandboxError (E-09)
@@ -46,11 +47,19 @@ module Kobako
 
     # TrapError for unknown or absent tag
     # ({docs/wire-codec.md ABI Signatures}[link:../../docs/wire-codec.md]:
-    # len=0 and unknown-tag both walk the trap path).
+    # zero-length output and unrecognised first byte both walk the trap
+    # path). The user-facing message stays in caller vocabulary — the
+    # raw tag byte (or absence) belongs in +details+ for operators, not
+    # in the message a caller sees.
     def build_trap_error(tag)
-      return TrapError.new("guest exited without writing an outcome (len=0)") if tag.nil?
-
-      TrapError.new(format("unknown outcome tag 0x%<tag>02x", tag: tag))
+      if tag.nil?
+        TrapError.new("Sandbox exited without producing a result")
+      else
+        TrapError.new(
+          "Sandbox produced an unrecognised result; the runtime is corrupted, " \
+          "discard this Sandbox before another invocation"
+        )
+      end
     end
 
     def split_tag(bytes)
@@ -63,11 +72,18 @@ module Kobako
     end
 
     # Decode failure on the success tag is a SandboxError (E-09): the
-    # framing was fine, but the carried value is unrepresentable.
+    # framing was fine, but the carried value is unrepresentable. The
+    # specific codec fault is stashed in +details+ rather
+    # than spliced into the message — callers cannot act on the inner
+    # "Symbol payload must be …" wording, but operators triaging a
+    # corrupted Sandbox runtime still need it.
     def decode_value(body)
       Kobako::Codec::Decoder.decode(body)
     rescue Kobako::Codec::Error => e
-      raise build_wire_violation_error("result envelope decode failed: #{e.message}")
+      raise build_transport_error(
+        "Sandbox produced an invalid result value",
+        detail: e.message
+      )
     end
 
     # Decode failure on the panic tag is a SandboxError (E-08). Either
@@ -75,20 +91,25 @@ module Kobako
     # layer exception via +build_panic_error+ and raised; on wire-decode
     # failure the rescue path raises the wire-violation +SandboxError+.
     def decode_panic(body)
-      raise build_panic_error(parse_panic(body))
+      raise build_panic_error(build_panic_record(body))
     rescue Kobako::Codec::Error => e
-      raise build_wire_violation_error("panic envelope decode failed: #{e.message}")
+      raise build_transport_error(
+        "Sandbox produced an invalid panic record",
+        detail: e.message
+      )
     end
 
     # Build a +Panic+ value object from the msgpack-decoded body. Raises
-    # +Kobako::Codec::InvalidType+ when the body is not a map or
-    # when required keys are missing — both routed by +decode_panic+ to
-    # +build_wire_violation_error+.
-    def parse_panic(body)
-      map = Kobako::Codec::Decoder.decode(body)
-      raise Kobako::Codec::InvalidType, "Panic envelope must be a map, got #{map.class}" unless map.is_a?(Hash)
+    # +Kobako::Codec::InvalidType+ when the body is not a map or when
+    # required keys are missing — both routed by +decode_panic+ to
+    # +build_transport_error+. The decode runs in block form so
+    # +Panic.new+'s +ArgumentError+ invariants surface as +InvalidType+
+    # through the decoder boundary; the message itself is never user-
+    # facing — it lands in +details+ via the rescue chain above.
+    def build_panic_record(body)
+      Kobako::Codec::Decoder.decode(body) do |map|
+        raise Kobako::Codec::InvalidType, "panic body must be a map, got #{map.class}" unless map.is_a?(Hash)
 
-      Kobako::Codec::Utils.wire_boundary do
         Panic.new(
           origin: map["origin"], klass: map["class"], message: map["message"],
           backtrace: map["backtrace"] || [], details: map["details"]
@@ -97,11 +118,8 @@ module Kobako
     end
 
     # Map a decoded Panic record into the corresponding three-layer
-    # Ruby exception. +origin == "service"+ → ServiceError (with the
-    # +::Disconnected+ subclass selected when the panic carries the
-    # disconnected sentinel —
-    # {docs/behavior.md Error Classes}[link:../../docs/behavior.md]); everything else
-    # → SandboxError.
+    # Ruby exception. +origin == "service"+ → ServiceError; everything
+    # else → SandboxError.
     def build_panic_error(panic)
       panic_target_class(panic).new(
         panic.message,
@@ -112,28 +130,36 @@ module Kobako
       )
     end
 
-    # {docs/behavior.md Error Classes}[link:../../docs/behavior.md]: map
+    # {docs/behavior.md Error Scenarios}[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
+    # callers can rescue specific failure paths. +origin="service"+ →
+    # +ServiceError+; +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)
       case panic.origin
       when Panic::ORIGIN_SERVICE
-        panic.klass == "Kobako::ServiceError::Disconnected" ? ServiceError::Disconnected : ServiceError
+        ServiceError
       else
         panic.klass == "Kobako::BytecodeError" ? BytecodeError : SandboxError
       end
     end
 
-    def build_wire_violation_error(message)
-      SandboxError.new(
+    # Lift the wire-violation fallback 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.
+    # +detail+ carries the inner codec / framing message, stashed
+    # directly into +details+ for operator diagnosis without polluting
+    # the user-facing +#message+.
+    def build_transport_error(message, detail: nil)
+      Kobako::Transport::Error.new(
         message,
         origin: Panic::ORIGIN_SANDBOX,
-        klass: "Kobako::RPC::WireError"
+        klass: "Kobako::Transport::Error",
+        details: detail
       )
     end
   end

data/lib/kobako/runtime.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Kobako
+  # Host-side wasmtime runtime, surfaced as a Ruby class by the native ext
+  # (see ext/kobako/src/runtime.rs). The +Kobako::Runtime+ class wraps the
+  # wasmtime engine + compiled module + Store; it is the only Ruby-visible
+  # wasmtime type and the foundational binding layer for +Kobako::Sandbox+.
+  #
+  # This file reopens the magnus-defined class only to add the pure-Ruby
+  # +.default_path+ helper. Every other method (+#from_path+ singleton,
+  # +#eval+ / +#run+, capture and usage readers) is registered from Rust
+  # at ext load time.
+  class Runtime
+    # Absolute path to the gem-bundled +data/kobako.wasm+ artifact. Computed
+    # from this file's location so it works for both +bundle exec+ (running
+    # from the repo) and an installed gem (running from the gem dir).
+    #
+    # Returns a String regardless of whether the file currently exists —
+    # call sites that need the file to be present should pass this through
+    # +Kobako::Runtime.from_path+, which raises
+    # +Kobako::ModuleNotBuiltError+ with a clear remediation message.
+    # Raises +Kobako::SetupError+ if +__dir__+ is unavailable so that
+    # +rescue Kobako::SetupError+ around +Kobako::Sandbox.new+ catches every
+    # construction-layer failure uniformly, including this path-resolution one.
+    def self.default_path
+      dir = __dir__ or raise Kobako::SetupError, "Kobako::Runtime.default_path requires __dir__"
+      File.expand_path("../../data/kobako.wasm", dir)
+    end
+  end
+end

data/lib/kobako/sandbox.rb

@@ -4,24 +4,27 @@ require "forwardable"
 
 require_relative "capture"
 require_relative "errors"
-require_relative "invocation"
 require_relative "outcome"
-require_relative "rpc/server"
-require_relative "rpc/envelope"
 require_relative "sandbox_options"
-require_relative "snippet"
+require_relative "usage"
+require_relative "transport"
+require_relative "catalog"
 
 module Kobako
   # Kobako::Sandbox — the user-facing entry point for executing guest mruby
   # scripts inside a wasmtime-hosted Wasm module
   # ({docs/behavior.md B-01}[link:../../docs/behavior.md]).
   #
-  # The Sandbox owns the +Kobako::Wasm::Instance+, the per-instance RPC Server
-  # (which itself owns the per-run HandleTable), and the per-channel byte
-  # caches for guest stdout / stderr capture. The underlying wasmtime Engine
-  # and compiled Module are cached at process scope by the native ext and
-  # never surface to Ruby — constructing many Sandboxes amortises both costs
-  # automatically.
+  # The Sandbox owns the +Kobako::Runtime+, the per-Sandbox
+  # +Kobako::Catalog::Handles+ ({docs/behavior.md B-19}[link:../../docs/behavior.md]),
+  # the per-instance +Kobako::Catalog::Namespaces+ (which receives the
+  # +Catalog::Handles+ by injection so guest→host dispatch and host→guest
+  # auto-wrap share one allocator), and the dispatch +Proc+ /
+  # +yield_to_guest+ lambda installed on the Runtime via
+  # +Runtime#on_dispatch=+ ({docs/behavior.md B-12}[link:../../docs/behavior.md]).
+  # The underlying wasmtime Engine and compiled Module are cached at process
+  # scope by the native ext and never surface to Ruby — constructing many
+  # Sandboxes amortises both costs automatically.
   #
   # Output capture policy ({docs/behavior.md B-04}[link:../../docs/behavior.md]): the
   # per-channel cap (+stdout_limit+ / +stderr_limit+) is enforced inside the
@@ -34,9 +37,7 @@ module Kobako
   class Sandbox
     extend Forwardable
 
-    attr_reader :wasm_path, :instance,
-                :options,
-                :services, :snippets
+    attr_reader :wasm_path, :options
 
     # Per-cap accessors forward to the immutable +SandboxOptions+ Value
     # Object so the Host App still reads them off Sandbox directly.
@@ -72,6 +73,17 @@ module Kobako
       @stderr_capture.truncated?
     end
 
+    # Returns the +Kobako::Usage+ value object for the most recent
+    # invocation ({docs/behavior.md B-35}[link:../../docs/behavior.md]).
+    # Carries +wall_time+ (Float seconds the guest export call spent
+    # inside wasmtime) and +memory_peak+ (Integer bytes, high-water of
+    # the per-invocation +memory.grow+ delta past the entry-time
+    # baseline). Returns +Kobako::Usage::EMPTY+ before any invocation;
+    # populated on every outcome — including +TrapError+ — so the Host
+    # App can read it after rescuing a trap to diagnose budget
+    # consumption.
+    attr_reader :usage
+
     # Build a fresh Sandbox.
     #
     # +wasm_path+ is the absolute path to the Guest Binary; defaults to the
@@ -84,20 +96,22 @@ module Kobako
     def initialize(wasm_path: nil, stdout_limit: nil, stderr_limit: nil,
                    timeout: SandboxOptions::DEFAULT_TIMEOUT_SECONDS,
                    memory_limit: SandboxOptions::DEFAULT_MEMORY_LIMIT)
-      @wasm_path = wasm_path || Kobako::Wasm.default_path
+      @wasm_path = wasm_path || Kobako::Runtime.default_path
       @options = SandboxOptions.new(timeout: timeout, memory_limit: memory_limit, stdout_limit: stdout_limit,
                                     stderr_limit: stderr_limit)
-      @services = Kobako::RPC::Server.new
-      @snippets = Snippet::Table.new
-      @instance = Kobako::Wasm::Instance.from_path(@wasm_path, @options.timeout, @options.memory_limit,
-                                                   @options.stdout_limit, @options.stderr_limit)
-      @instance.server = @services
-      clear_captures!
+      @handler = Catalog::Handles.new
+      @services = Kobako::Catalog::Namespaces.new(handler: @handler)
+      @snippets = Catalog::Snippets.new
+      @runtime = Kobako::Runtime.from_path(@wasm_path, @options.timeout, @options.memory_limit,
+                                           @options.stdout_limit, @options.stderr_limit)
+      install_dispatch_proc!
+      reset_invocation_state!
     end
 
     # Declare or retrieve the Namespace named +name+ on this Sandbox
     # ({docs/behavior.md B-07, B-09, B-10}[link:../../docs/behavior.md]). +name+ must be a
-    # Symbol or String in constant form. Returns the +Kobako::RPC::Namespace+.
+    # Symbol or String in constant form. Returns the
+    # +Kobako::Namespace+.
     #
     # Raises +ArgumentError+ when called after the first invocation, or
     # when +name+ does not match the constant-name pattern.
@@ -144,17 +158,19 @@ module Kobako
 
     # Dispatch into a preloaded entrypoint constant
     # ({docs/behavior.md B-31}[link:../../docs/behavior.md]). Delegates host
-    # pre-flight (E-24 / E-25 / E-29 / E-30) and wire encoding to
-    # +Kobako::Invocation+ / +Kobako::Invocation#encode+; the guest
-    # resolves +target+ as a top-level constant, calls +#call+ on it
-    # with +args+ / +kwargs+, and returns the deserialized result. The
-    # first invocation seals the Service registry and snippet table
-    # (B-07 / B-33). Runtime errors follow the same three-class taxonomy
-    # as +#eval+.
+    # pre-flight and wire encoding to +Kobako::Transport::Run+ /
+    # +Kobako::Transport::Run#encode+: a non-Symbol/String +target+ raises
+    # +TypeError+ (E-24), while a +target+ failing the constant pattern
+    # (E-25), a forged +Kobako::Handle+ in +args+ / +kwargs+ (E-29), or a
+    # non-Symbol +kwargs+ key (E-30) raise +ArgumentError+. The guest
+    # resolves +target+ as a top-level constant, calls +#call+ on it with
+    # +args+ / +kwargs+, and returns the deserialized result. The first
+    # invocation seals the Service registry and snippet table (B-07 /
+    # B-33). Runtime errors follow the same three-class taxonomy as +#eval+.
     def run(target, *args, **kwargs)
-      invocation = Invocation.new(entrypoint: target, args: args, kwargs: kwargs)
+      run_envelope = Transport::Run.new(entrypoint: target, args: args, kwargs: kwargs)
       invoke!(:run) do
-        @instance.run(@services.encoded_preamble, @snippets.encode, invocation.encode)
+        @runtime.run(@services.encode, @snippets.encode, run_envelope.encode(@handler))
       end
     end
 
@@ -185,66 +201,114 @@ module Kobako
       raise SandboxError, "code must be a String, got #{code.class}" unless code.is_a?(String)
 
       invoke!(:eval) do
-        @instance.eval(@services.encoded_preamble, code.b, @snippets.encode)
+        @runtime.eval(@services.encode, code.b, @snippets.encode)
       end
     end
 
     private
 
+    # Configure the +Runtime+'s host↔guest dispatch wiring
+    # ({docs/behavior.md B-12}[link:../../docs/behavior.md]). Builds a
+    # lambda that re-enters the guest via
+    # +Runtime#yield_to_active_invocation+ (B-24) and a dispatch +Proc+
+    # that routes guest→host calls through the stateless
+    # +Transport::Dispatcher+, capturing +@services+ / +@handler+ in the
+    # closure. Both are registered on the +Runtime+ once at construction
+    # time so the wasm ext callback can fire without further setup.
+    def install_dispatch_proc!
+      yield_to_guest = ->(args_bytes) { @runtime.yield_to_active_invocation(args_bytes) }
+      @runtime.on_dispatch = lambda do |request_bytes|
+        Transport::Dispatcher.dispatch(request_bytes, @services, @handler, yield_to_guest)
+      end
+    end
+
     # Per-invocation prologue ({docs/behavior.md B-03 / B-07 /
     # B-33}[link:../../docs/behavior.md]). Seals the Service / snippet
     # registries on first call (idempotent) and zeros the per-invocation
     # capability state — capture buffers, truncation predicates, and the
-    # HandleTable counter — before the guest runs.
+    # +Catalog::Handles+ counter — before the guest runs. The
+    # +Catalog::Handles+ itself is held as +@handler+ and never exposed beyond
+    # this class: SPEC.md Terminology pins it as "Not exposed to the
+    # Host App" (B-19 / B-20 / E-29).
     def begin_invocation!
       @services.seal!
-      @services.reset_handles!
-      clear_captures!
+      @handler.reset!
+      reset_invocation_state!
     end
 
-    # Reset both per-channel captures to the pre-invocation sentinel
-    # ({docs/behavior.md B-05}[link:../../docs/behavior.md]). Shared by +#initialize+
-    # (first-time setup) and +#begin_invocation!+ (between-invocation
-    # reset) so both paths agree on what "empty capture" means.
-    def clear_captures!
+    # Reset all per-invocation observable state to its pre-invocation
+    # sentinels — both per-channel captures
+    # ({docs/behavior.md B-05}[link:../../docs/behavior.md]) and the
+    # per-last-invocation usage record
+    # ({docs/behavior.md B-35}[link:../../docs/behavior.md]). Shared by
+    # +#initialize+ (first-time setup) and +#begin_invocation!+
+    # (between-invocation reset) so both paths agree on what
+    # "pre-invocation state" means.
+    def reset_invocation_state!
       @stdout_capture = Capture::EMPTY
       @stderr_capture = Capture::EMPTY
+      @usage = Usage::EMPTY
     end
 
-    # Read the per-channel capture pairs (+[bytes, truncated]+) from the
-    # ext after an invocation completes and wrap each as a +Capture+ value
-    # object. The ext clips +bytes+ to the configured cap and sets
-    # +truncated+ when the guest produced strictly more than +cap+ bytes
-    # ({docs/behavior.md B-04}[link:../../docs/behavior.md]). Mirror of {#clear_captures!}
-    # at the post-invocation boundary.
-    def read_captures!
-      out_bytes, out_truncated = @instance.stdout
-      err_bytes, err_truncated = @instance.stderr
-      @stdout_capture = Capture.from_ext(out_bytes, out_truncated)
-      @stderr_capture = Capture.from_ext(err_bytes, err_truncated)
+    # Read the per-last-invocation +wall_time+ and +memory_peak+ from
+    # the ext and wrap them as a +Kobako::Usage+ value object
+    # ({docs/behavior.md B-35}[link:../../docs/behavior.md]). Runs in
+    # the +invoke!+ +ensure+ block so the usage record is populated on
+    # every outcome — value return, +Kobako::TrapError+ (including
+    # +TimeoutError+ / +MemoryLimitError+), +Kobako::SandboxError+,
+    # and +Kobako::ServiceError+. On the success path the same figures
+    # already arrive via +Snapshot#usage+; on the trap path the Snapshot
+    # never reaches Ruby so the ext readout here is the only source.
+    #
+    # The ext returns a positional 2-tuple +[wall_time, memory_peak]+
+    # whose order matches the +Kobako::Usage+ field order; the
+    # destructure-then-kwargs handoff below is the explicit
+    # positional→keyword conversion point.
+    def read_usage!
+      wall_time, memory_peak = @runtime.usage
+      @usage = Usage.new(wall_time: wall_time, memory_peak: memory_peak)
+    end
+
+    # Pick the +TrapError+ subclass to re-raise based on +err+'s actual
+    # class. Cap-trap subclasses
+    # ({docs/behavior.md E-19 / E-20}[link:../../docs/behavior.md])
+    # preserve their named identity; everything else collapses to the
+    # base +Kobako::TrapError+. The ext already raises the right subclass
+    # directly, so this is a pure re-attribution that lets +#invoke!+
+    # add the verb prefix without erasing +TimeoutError+ /
+    # +MemoryLimitError+.
+    def trap_class_for(err)
+      case err
+      when TimeoutError     then TimeoutError
+      when MemoryLimitError then MemoryLimitError
+      else TrapError
+      end
     end
 
     # Shared prologue / epilogue + trap-class translator for both
     # invocation verbs. +verb+ is +:eval+ or +:run+; it tags the
-    # TrapError message so the failing export is identifiable. The
-    # rescue chain is the single trap-translation boundary — wasmtime /
-    # wire failures from the guest call and from the subsequent
-    # +Instance#outcome!+ read both flow through here, so an
-    # OUTCOME_BUFFER read failure attributes to the same export name as
-    # the guest call itself. Configured-cap paths
-    # ({docs/behavior.md E-19 / E-20}[link:../../docs/behavior.md]) surface as
-    # named TrapError subclasses.
+    # TrapError message so the failing export is identifiable.
+    #
+    # The yielded block must return a +Kobako::Snapshot+ — i.e. the
+    # value of +Runtime#eval+ / +#run+ (SPEC.md Internal Concepts →
+    # Snapshot). The success path unpacks every observable from the
+    # Snapshot in one go: +#stdout+ / +#stderr+ pack into +Capture+,
+    # +#usage+ packs into +Usage+, +#return_bytes+ feeds +Outcome.decode+.
+    # The rescue chain is the single trap-translation boundary —
+    # configured-cap paths
+    # ({docs/behavior.md E-19 / E-20}[link:../../docs/behavior.md])
+    # surface as named TrapError subclasses; everything else surfaces as
+    # the base +TrapError+.
     def invoke!(verb)
       begin_invocation!
-      yield
-      read_captures!
-      Outcome.decode(@instance.outcome!)
-    rescue Kobako::Wasm::TimeoutError => e
-      raise TimeoutError, "guest exceeded timeout: #{e.message}"
-    rescue Kobako::Wasm::MemoryLimitError => e
-      raise MemoryLimitError, "guest exceeded memory_limit: #{e.message}"
-    rescue Kobako::Wasm::Error => e
-      raise TrapError, "guest __kobako_#{verb} trapped: #{e.message}"
+      snapshot = yield
+      @stdout_capture = snapshot.stdout
+      @stderr_capture = snapshot.stderr
+      Outcome.decode(snapshot.return_bytes)
+    rescue Kobako::TrapError => e
+      raise trap_class_for(e), "Sandbox##{verb} failed: #{e.message}"
+    ensure
+      read_usage!
     end
   end
 end

data/lib/kobako/sandbox_options.rb

@@ -11,7 +11,7 @@ module Kobako
   # for absent values and normalises (timeout to Float seconds,
   # memory_limit to positive Integer bytes) before delegating to Data's
   # +super+. Anything that survives +SandboxOptions.new+ is a wire-ready
-  # cap bundle the +Kobako::Wasm::Instance+ constructor consumes as-is.
+  # cap bundle the +Kobako::Runtime+ constructor consumes as-is.
   class SandboxOptions < Data.define(:timeout, :memory_limit, :stdout_limit, :stderr_limit)
     # Default wall-clock timeout for a single invocation: 60 seconds
     # ({docs/behavior.md B-01}[link:../../docs/behavior.md]).
@@ -27,17 +27,15 @@ module Kobako
     # ({docs/behavior.md B-01}[link:../../docs/behavior.md]).
     DEFAULT_OUTPUT_LIMIT = 1 << 20
 
-    # steep:ignore:start
     def initialize(timeout: DEFAULT_TIMEOUT_SECONDS,
                    memory_limit: DEFAULT_MEMORY_LIMIT,
                    stdout_limit: nil,
                    stderr_limit: nil)
-      super(
-        timeout: normalize_timeout(timeout),
-        memory_limit: normalize_memory_limit(memory_limit),
-        stdout_limit: stdout_limit || DEFAULT_OUTPUT_LIMIT,
-        stderr_limit: stderr_limit || DEFAULT_OUTPUT_LIMIT
-      )
+      timeout = normalize_timeout(timeout)
+      memory_limit = normalize_memory_limit(memory_limit)
+      stdout_limit ||= DEFAULT_OUTPUT_LIMIT
+      stderr_limit ||= DEFAULT_OUTPUT_LIMIT
+      super
     end
 
     private
@@ -68,6 +66,5 @@ module Kobako
 
       memory_limit
     end
-    # steep:ignore:end
   end
 end

data/lib/kobako/snapshot.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative "capture"
+require_relative "usage"
+
+module Kobako
+  # Kobako::Snapshot — per-invocation observable bundle returned from
+  # +Kobako::Runtime#eval+ and +#run+.
+  #
+  # The magnus class (see ext/kobako/src/snapshot.rs) carries seven raw
+  # readers: +return_bytes+, +stdout_bytes+, +stdout_truncated+,
+  # +stderr_bytes+, +stderr_truncated+, +wall_time+, +memory_peak+. This
+  # file reopens the class to add the Ruby-side helpers that pack those
+  # raw fields into the user-facing value objects +Kobako::Capture+ and
+  # +Kobako::Usage+ — the same shape +Kobako::Sandbox+ exposes to the
+  # Host App.
+  class Snapshot
+    # Wrap the stdout capture pair (+stdout_bytes+, +stdout_truncated+)
+    # as a +Kobako::Capture+ value object. {docs/behavior.md
+    # B-04}[link:../../docs/behavior.md] — the byte content never carries
+    # a truncation sentinel; +#truncated?+ is the only way to observe
+    # that the cap was hit.
+    def stdout
+      Capture.new(bytes: stdout_bytes, truncated: stdout_truncated)
+    end
+
+    # Wrap the stderr capture pair as a +Kobako::Capture+ value object.
+    # Mirror of +#stdout+.
+    def stderr
+      Capture.new(bytes: stderr_bytes, truncated: stderr_truncated)
+    end
+
+    # Wrap the per-last-invocation usage pair (+wall_time+,
+    # +memory_peak+) as a +Kobako::Usage+ value object
+    # ({docs/behavior.md B-35}[link:../../docs/behavior.md]).
+    def usage
+      Usage.new(wall_time: wall_time, memory_peak: memory_peak)
+    end
+  end
+end

data/lib/kobako/snippet/binary.rb

@@ -3,23 +3,22 @@
 module Kobako
   module Snippet
     # Kobako::Snippet::Binary — value object representing a single
-    # +#preload(binary:)+ entry held by +Kobako::Snippet::Table+
+    # +#preload(binary:)+ entry held by +Kobako::Catalog::Snippets+
     # ({docs/behavior.md B-32}[link:../../../docs/behavior.md]).
     #
     # The +body+ is RITE bytecode (as emitted by +mrbc+) carried as an
     # +ASCII_8BIT+ String so msgpack-ruby encodes it as +bin+ family on
     # the wire ({docs/wire-codec.md Invocation channels}[link:../../../docs/wire-codec.md]).
     # The host treats the bytes as opaque — the snippet's canonical
-    # name, when present, lives in the bytecode's embedded
-    # +debug_info+ and is resolved by the guest at load time;
-    # structural validation
+    # name, when present, lives in the bytecode's embedded +debug_info+
+    # and is resolved by the guest at load time; structural validation
     # ({docs/behavior.md E-37 / E-38}[link:../../../docs/behavior.md])
     # is deferred to the first invocation's guest replay.
     #
     # The class is a +Data.define+ subclass — frozen and value-equal.
-    # Callers (chiefly +Table+) construct instances via keyword form
-    # +Binary.new(body: ...)+. Wire-form construction is the +Table+'s
-    # responsibility.
+    # Callers (chiefly +Catalog::Snippets+) construct instances via keyword
+    # form +Binary.new(body: ...)+. Wire-form construction is the
+    # registry's responsibility.
     class Binary < Data.define(:body)
       # The +kind+ field value carried by bytecode snippets in their
       # Frame 3 wire envelope entry

data/lib/kobako/snippet/source.rb

@@ -3,21 +3,21 @@
 module Kobako
   module Snippet
     # Kobako::Snippet::Source — value object representing a single
-    # +#preload(code:, name:)+ entry held by +Kobako::Snippet::Table+
+    # +#preload(code:, name:)+ entry held by +Kobako::Catalog::Snippets+
     # ({docs/behavior.md B-32}[link:../../../docs/behavior.md]).
     #
     # +name+ is the canonical +Symbol+ identity baked into the loaded
     # IREP's +debug_info+; backtrace frames originating in this snippet
     # surface as +(snippet:Name):line+. +body+ is the UTF-8 mruby source
-    # detached from the caller's reference at +Table#register+ time so
-    # later mutation of the original String cannot bleed through.
+    # detached from the caller's reference at +Catalog::Snippets#register+
+    # time so later mutation of the original String cannot bleed through.
     #
     # The class is a +Data.define+ subclass — frozen, value-equal, and
-    # carries no mutation API. Callers (chiefly +Table+) construct
-    # instances via keyword form +Source.new(name: ..., body: ...)+.
-    # Wire-form construction is the +Table+'s responsibility, mirroring
-    # +Kobako::RPC.encode_request+'s pattern of reading attributes off a
-    # carrier rather than asking the carrier to self-describe.
+    # carries no mutation API. Callers (chiefly +Catalog::Snippets+)
+    # construct instances via keyword form +Source.new(name: ..., body: ...)+.
+    # Wire-form construction is the registry's responsibility: as a leaf
+    # carrier this Source stays pure and +Catalog::Snippets#encode+ reads
+    # its attributes off the outside rather than asking it to self-encode.
     class Source < Data.define(:name, :body)
       # The +kind+ field value carried by source snippets in their Frame
       # 3 wire envelope entry

data/lib/kobako/snippet.rb

@@ -2,19 +2,17 @@
 
 require_relative "snippet/binary"
 require_relative "snippet/source"
-require_relative "snippet/table"
 
 module Kobako
-  # Kobako::Snippet — namespace for the per-Sandbox preloaded snippet
-  # registry and its entry value objects
+  # Kobako::Snippet — value-object family for preloaded snippet entries
+  # held by +Kobako::Catalog::Snippets+
   # ({docs/behavior.md B-32 / B-33}[link:../../docs/behavior.md]).
   #
-  # The +Table+ owns insertion-ordered storage and seal-coordination with
-  # the owning Sandbox; +Source+ is the value object representing a single
-  # +#preload(code:, name:)+ entry. Entry types live as siblings under
-  # this module rather than nested under +Table+ so they remain plain
-  # value objects with no implicit dependency on the registry that holds
-  # them.
+  # +Source+ represents a single +#preload(code:, name:)+ entry; +Binary+
+  # represents a single +#preload(binary:)+ entry. Both are plain value
+  # objects with no dependency on the +Catalog::Snippets+ registry that
+  # holds them — the registry reads their attributes externally when
+  # encoding the wire envelope.
   module Snippet
   end
 end