kobako 0.26.0 → 0.28.0

data/lib/kobako/codec.rb

@@ -10,24 +10,7 @@ require_relative "codec/encoder"
 require_relative "codec/decoder"
 
 module Kobako
-  # Host-side MessagePack codec for the kobako wire contract — the
-  # byte-level layer ({docs/wire-codec.md}[link:../../docs/wire-codec.md]).
-  # This is the payload codec: the core envelope is framed natively, so
-  # what reaches here is one codec document — an invocation's arguments
-  # (+Kobako::Payload::Arguments+), a dispatch or yield value, or an
-  # invocation's value and a Panic's diagnostics
-  # (+Kobako::Outcome+). The ext-type leaves this layer
-  # carries — +Kobako::Handle+ (0x01) — lives at the kobako root so the
-  # codec can register it without depending upward on Transport.
-  #
-  # Backed by the official +msgpack+ gem: ExtTypes registers the two
-  # kobako-specific ext types (0x00 Symbol, 0x01 Capability Handle) on
-  # one process-wide +MessagePack::Factory+,
-  # and Encoder / Decoder are thin wrappers over it. The Rust side
-  # mirrors this layer as the +codec+ module in the +kobako-codec+ crate;
-  # the ext-code constants live as module-private values on ExtTypes
-  # alongside +codec::EXT_SYMBOL+ / +codec::EXT_HANDLE+ on that side.
-  module Codec
+  module Codec # :nodoc:
     # The maximum structural nesting depth the wire represents (the
     # MessagePack ecosystem's bound), shared with the guest +kobako_codec+
     # so both sides cap identically. The host refuses a value nesting past
@@ -35,10 +18,8 @@ module Kobako
     # packer.
     MAX_NESTING_DEPTH = 128
 
-    # Bracket a decode and return the block's result together with whether
-    # the decoded tree carried an ext 0x01 Capability Handle — the signal a
-    # dispatch path uses to skip an all-identity Handle-resolution walk.
-    # The tracking state is codec-internal; this is its only readout.
+    # Answers the block's result with whether the decode carried a
+    # Capability Handle, so a caller can skip an all-identity restore walk.
     def self.track_handles(&block)
       State.current.track_handles(&block)
     end

data/lib/kobako/constant_name.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Kobako
+  # A bind-path segment, a snippet name and a #run entrypoint all take the
+  # constant-name form, so they are refused alike. The guest interns each
+  # one, and mruby holds a symbol of at most 65534 bytes.
+  CONSTANT_NAME = /\A[A-Z]\w{0,65533}\z/ # :nodoc:
+end

data/lib/kobako/context.rb

@@ -11,41 +11,30 @@ require_relative "transport"
 require_relative "catalog"
 
 module Kobako
-  # Kobako::Context — the per-invocation driver behind a single +Sandbox#eval+
-  # / +#run+. Each Context owns a fresh +Catalog::Handles+ table and drives one
-  # guest invocation: it builds the dispatch handler, runs the guest, records
-  # the run's captures and usage, and decodes the outcome. One Context per
-  # invocation owns all per-invocation state, so the reusable +Sandbox+ holds
-  # none and overlapping evals never touch each other's state.
+  # One invocation, as the block given to Sandbox#eval or Sandbox#run sees it.
+  # The block runs before the guest does, so it can choose the objects this
+  # invocation alone reaches:
+  #
+  #   sandbox.eval("Req::Current.user_id") { |ctx| ctx.bind("Req::Current", request) }
   class Context
-    # Build a Context over the Sandbox-owned config — the +Runtime+, the
-    # sealed +Catalog::Services+ / +Catalog::Snippets+ registries, and the
-    # +Catalog::Extensions+ whose callable backends this Context resolves for
-    # its own run. The +Catalog::Handles+ table is this invocation's own, so
-    # guest→host dispatch and host→guest auto-wrap share one allocator scoped
-    # to the run; the resolved provider map is likewise per-invocation, so
-    # concurrent invocations never share mutable state.
-    def initialize(runtime:, services:, snippets:, extensions:)
+    def initialize(runtime:, services:, snippets:, flags:, extensions:) # :nodoc:
       @runtime = runtime
       @services = services
       @snippets = snippets
+      @flags = flags
       @extensions = extensions
       @resolved = {} # : Hash[String, Transport::Exposure]
       @overrides = {} # : Hash[String, Transport::Exposure]
-      @spent = false
-      @handler = Catalog::Handles.new
+      @handles = Catalog::Handles.new
       @stdout_capture = @stderr_capture = Capture::EMPTY
       @usage = Usage::EMPTY
     end
 
-    # Override the object bound at an already-declared +path+ for this
-    # invocation only — the per-eval hook the +#eval+ / +#run+ block uses to
-    # fill a fillable or shadow any static / per-invocation binding. +path+
-    # must name a declared (Frame 1) binding; overriding an undeclared path
-    # raises +ArgumentError+ so the Frame 1 key set stays fixed. Valid only
-    # while the block runs — the Context is spent once the block returns, so a
-    # captured +ctx+ used afterward raises +ArgumentError+ too, putting both
-    # misuses on one rescuable channel. Returns +self+.
+    # Use +object+ for the Service at +path+ during this invocation only,
+    # filling a fillable Service or shadowing a bound one. Returns +self+.
+    #
+    # Raises ArgumentError when +path+ was never bound on the Sandbox, or when
+    # called after the block has returned.
     def bind(path, object)
       raise ArgumentError, "Kobako::Context is spent; ctx.bind is only valid inside the #eval / #run block" if @spent
 
@@ -56,16 +45,9 @@ module Kobako
       self
     end
 
-    # Resolve a Service +path+ to the Exposure backing it this invocation,
-    # layering the per-eval +ctx.bind+ overrides over this Context's
-    # per-invocation provider results over the Sandbox's static base bindings.
-    # An unbound path raises +KeyError+; a fillable left unfilled resolves to
-    # +Kobako::Unresolved+ and is reported the same way, so an unresolved
-    # capability fails closed as an undefined target rather than dispatching to
-    # the sentinel. The Dispatcher maps either +KeyError+ to an
-    # undefined-target wire fault. Internal — the per-invocation dispatch
-    # handler is the sole caller.
-    def lookup(path)
+    # A fillable left unfilled raises like an unbound path, so the guest's
+    # call fails closed instead of reaching the sentinel.
+    def lookup(path) # :nodoc:
       key = path.to_s
       exposure = @overrides.fetch(key) { @resolved.fetch(key) { @services.lookup(path) } }
       raise KeyError, "service #{path} is declared but unresolved this invocation" if Unresolved.equal?(exposure.object)
@@ -73,136 +55,93 @@ module Kobako
       exposure
     end
 
-    # Execute a guest mruby source string in a fresh +mrb_state+ and return the
-    # decoded last expression. A given +block+ runs first, receiving this
-    # Context to collect +ctx.bind+ overrides before the guest drives.
-    def eval(code, &block)
+    def eval(code, &block) # :nodoc:
       collect_overrides(&block) if block
       invoke!(:eval) do
-        @runtime.eval(dispatch_handler, @services.paths, code.b, @snippets.entries)
+        @runtime.eval(dispatch_handler, @services.paths, @snippets.entries, @flags.entries, code.b)
       end
     end
 
-    # Dispatch a +Transport::Run+ into a preloaded entrypoint and return the
-    # decoded result. A given +block+ runs first, receiving this Context to
-    # collect +ctx.bind+ overrides before the guest drives.
-    def run(request, &block)
+    def run(request, &block) # :nodoc:
       collect_overrides(&block) if block
       invoke!(:run, entrypoint: request.entrypoint) do
-        @runtime.run(dispatch_handler, @services.paths, @snippets.entries,
-                     request.entrypoint.to_s, request.payload(@handler))
+        @runtime.run(dispatch_handler, @services.paths, @snippets.entries, @flags.entries,
+                     request.entrypoint.to_s, request.payload(@handles))
       end
     end
 
     private
 
-    # Run the per-eval override +block+, handing it this Context so it can call
-    # +ctx.bind+, then spend the Context so a captured +ctx+ used after the
-    # block raises. A block that raises propagates before the guest drives, so
-    # the guest never runs and no Execution is produced.
+    # The Context is spent once the block returns, so a captured +ctx+ used
+    # later raises. A block that raises propagates before the guest drives,
+    # so the guest never runs and no Execution is produced.
     def collect_overrides
       yield self
     ensure
       @spent = true
     end
 
-    # Build this invocation's guest→host dispatch handler — a +Proc+ routing
-    # each guest→host call through the stateless +Transport::Dispatcher+,
-    # capturing this Context as the path resolver (its +#lookup+ layers the
-    # per-invocation providers over the static bindings) plus +@handler+. Handed to
-    # +Runtime#eval+ / +#run+ as a call argument, so the Runtime holds no
-    # dispatch state and the +Proc+ stays GC-rooted as a live argument for the
-    # synchronous call. The ext hands the +Proc+ a per-dispatch +guest_yielder+
-    # — a +String → String+ callable that re-enters the in-flight guest to run
-    # a yielded block — which the +Dispatcher+ forwards to the
-    # +Transport::Yielder+ it builds for the call.
+    # Handed to the Runtime as a call argument, so the Runtime holds no
+    # dispatch state and the Proc stays GC-rooted for the synchronous call.
     def dispatch_handler
       lambda do |target, method_name, block_given, payload, guest_yielder|
         call = Transport::Call.new(target: target, method_name: method_name,
                                    block_given: block_given, payload: payload)
-        Transport::Dispatcher.dispatch(call, self, @handler, guest_yielder)
+        Transport::Dispatcher.dispatch(call, self, @handles, guest_yielder)
       end
     end
 
-    # Record this invocation's usage and both output captures from the ext
-    # +Snapshot+. Every Snapshot carries them — value return or trap alike — so
-    # +#usage+ / +#stdout+ / +#stderr+ stay readable after a rescued trap.
+    # Every Snapshot carries usage and captures, trap or not, so they stay
+    # readable after a rescued trap.
     def populate_observability!(snapshot)
       @usage = Usage.new(wall_time: snapshot.wall_time, memory_peak: snapshot.memory_peak)
       @stdout_capture = Capture.new(bytes: snapshot.stdout, truncated: snapshot.stdout_truncated?)
       @stderr_capture = Capture.new(bytes: snapshot.stderr, truncated: snapshot.stderr_truncated?)
     end
 
-    # Pick the +TrapError+ subclass to re-raise based on +err+'s actual class.
-    # Cap-trap subclasses (+TimeoutError+ / +MemoryLimitError+) preserve their
-    # named identity; everything else collapses to the base +Kobako::TrapError+,
-    # so #invoke! can add the verb prefix without erasing the named subclass.
-    def trap_class_for(err)
-      case err
-      when TimeoutError     then TimeoutError
-      when MemoryLimitError then MemoryLimitError
-      else TrapError
-      end
-    end
-
-    # Build the +TrapError+-family exception for a trapped +Snapshot+ from its
-    # neutral trap kind, tagged with the verb — the cap subclasses
-    # (+TimeoutError+ / +MemoryLimitError+) keep their identity, every other
-    # engine fault is the base +TrapError+.
-    def trap_error_for(snapshot, verb)
-      klass = case snapshot.trap_kind
-              when :timeout      then TimeoutError
-              when :memory_limit then MemoryLimitError
-              else TrapError
-              end
-      klass.new("Sandbox##{verb} failed: #{snapshot.trap_message}")
+    # Every TrapError leaving an invocation names the verb that ran it; the
+    # cap subclasses keep their identity through the rebuild.
+    def with_verb(err, verb)
+      err.class.new("Sandbox##{verb} failed: #{err.message}")
     end
 
-    # Freeze this run's observables plus +value+ (+nil+ on a failed run) into
-    # the read-only +Execution+ the caller receives or the error carries.
-    # +failed+ records the two apart so a +nil+ +value+ from a successful run
-    # stays distinct from a failed one.
+    # +failed+ keeps a +nil+ value from a successful run apart from a failed
+    # run.
     def build_execution(value, failed:)
       Execution.new(value: value, usage: @usage, stdout: @stdout_capture, stderr: @stderr_capture, failed: failed)
     end
 
-    # Settle a completed run's outcome into its +Execution+. A Capability
-    # Handle in the result is restored to its host object first. The settle
-    # sits in the rescue so a wire-violation trap or a Panic both attach this
-    # run's Execution, just like a guest-call trap does. +entrypoint+ is the
-    # name +#run+ asked for, which the host knows and the wire never carries,
-    # so an unresolved one names itself on the error it raises.
+    # The settle sits in the rescue so a wire-violation trap or a Panic both
+    # attach this run's Execution, just like a guest-call trap does.
+    # +entrypoint+ is known to the host and never carried by the wire, so an
+    # unresolved one names itself on the error it raises.
     def settle_outcome(snapshot, verb, entrypoint)
-      kind, payload, panic = snapshot.outcome
-      value, carried = Codec.track_handles { Outcome.reify(kind, payload, panic, entrypoint: entrypoint) }
-      value = Codec::HandleWalk.deep_restore(value, @handler) if carried
+      payload, panic = snapshot.outcome
+      value, carried = Codec.track_handles { Outcome.reify(payload, panic, entrypoint: entrypoint) }
+      value = Codec::HandleWalk.deep_restore(value, @handles) if carried
       build_execution(value, failed: false)
     rescue Kobako::TrapError => e
-      raise trap_class_for(e).new("Sandbox##{verb} failed: #{e.message}").with_execution(build_execution(nil,
-                                                                                                         failed: true))
+      raise with_verb(e, verb).with_execution(build_execution(nil, failed: true))
     rescue Kobako::SandboxError, Kobako::ServiceError => e
       raise e.with_execution(build_execution(nil, failed: true))
     end
 
-    # Drive one invocation and settle it into a frozen +Execution+. +verb+
-    # tags the TrapError message so the failing export is identifiable. This
-    # invocation's callable Extension backends are resolved first — before the
-    # guest runs — so a provider that raises propagates unwrapped and leaves
-    # the guest unrun. Usage and captures are recorded before the trap check,
-    # so a trapped Snapshot's error carries them just like a completed run's
-    # return value. A could-not-start fault ran no invocation at all, so it
-    # carries no Execution and gains only the verb prefix.
+    # Extension backends are resolved before the guest runs, so a provider
+    # that raises propagates unwrapped and leaves the guest unrun. A
+    # could-not-start fault ran no invocation at all, so it carries no
+    # Execution and gains only the verb prefix.
     def invoke!(verb, entrypoint: nil)
       @resolved = @extensions.resolve.transform_values { |object| Transport::Exposure.of(object) }
       begin
         snapshot = yield
       rescue Kobako::TrapError => e
-        raise trap_class_for(e), "Sandbox##{verb} failed: #{e.message}"
+        raise with_verb(e, verb)
       end
       populate_observability!(snapshot)
-      return settle_outcome(snapshot, verb, entrypoint) unless snapshot.trapped?
+      trap = snapshot.trap_error
+      return settle_outcome(snapshot, verb, entrypoint) unless trap
 
-      raise trap_error_for(snapshot, verb).with_execution(build_execution(nil, failed: true))
+      raise with_verb(trap, verb).with_execution(build_execution(nil, failed: true))
     end
   end
 end

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