kobako 0.10.0 → 0.11.0

data/lib/kobako/codec/utils.rb

@@ -19,8 +19,7 @@ module Kobako
     #   - Representability predicate ({representable?}) and the symmetric
     #     host→guest +#run+ argument walk ({deep_wrap}) used by
     #     +Kobako::Transport::Run#encode+ to route non-representable leaves
-    #     through the Sandbox's +Kobako::Catalog::Handles+
-    #     ({docs/behavior.md B-34}[link:../../../docs/behavior.md]).
+    #     through the Sandbox's +Kobako::Catalog::Handles+.
     #
     # All helpers are pure — they only inspect inputs, never mutate
     # them — except {deep_wrap}, whose only side effect is allocating
@@ -84,8 +83,7 @@ module Kobako
 
       # Deep-walk Array / Hash containers in +value+ and replace every
       # leaf that fails {representable?} with a +Kobako::Handle+
-      # allocated from +handler+
-      # ({docs/behavior.md B-34}[link:../../../docs/behavior.md]). The
+      # allocated from +handler+. The
       # walk only descends through representable container shapes
       # (Array, Hash) one structural level at a time; a non-representable
       # leaf is wrapped as-is without inspecting its internal structure.
@@ -116,8 +114,7 @@ module Kobako
 
       # Deep-walk Array / Hash containers in +value+ and replace every
       # +Kobako::Handle+ leaf with the host-side object +handler+ resolves
-      # it to ({docs/behavior.md B-37}[link:../../../docs/behavior.md]).
-      # The symmetric inverse of {deep_wrap}: that walk allocates objects
+      # it to. The symmetric inverse of {deep_wrap}: that walk allocates objects
       # into Handles on the host→guest argument path; this walk resolves
       # Handles back to their objects on every guest→host value path — the
       # +#eval+ / +#run+ result and the yield-block result alike. The walk
@@ -126,11 +123,11 @@ module Kobako
       # unchanged.
       #
       # +value+ is a decoded Ruby value (a Handle here is a wire-decoded
-      # +Kobako::Handle+, never a guest-forged one — B-20); +handler+ must
+      # +Kobako::Handle+, never a guest-forged one); +handler+ must
       # respond to +#fetch(id) -> object+ (a host-side
       # +Kobako::Catalog::Handles+). +handler.fetch+ raises
-      # +Kobako::SandboxError+ for an id with no live binding, which is the
-      # corrupted-runtime fallback B-37 specifies.
+      # +Kobako::SandboxError+ for an id with no live binding, the
+      # corrupted-runtime fallback.
       def deep_restore(value, handler)
         case value
         when ::Array then value.map { |element| Utils.deep_restore(element, handler) }

data/lib/kobako/errors.rb

@@ -2,12 +2,12 @@
 
 # Top-level Kobako namespace.
 module Kobako
-  # Error taxonomy (docs/behavior.md § Error Scenarios).
+  # Error taxonomy.
   #
   # Every `Kobako::Sandbox` invocation (`#eval` or `#run`) either returns a value or raises
   # exactly one of three invocation-outcome classes. Attribution is decided after the
-  # guest binary returns control to the host (docs/behavior.md
-  # "Step 1 — Wasm trap" then "Step 2 — Outcome envelope tag").
+  # guest binary returns control to the host: first the Wasm-trap layer, then
+  # the outcome-envelope tag.
   #
   # Three invocation-outcome branches:
   #
@@ -25,19 +25,17 @@ module Kobako
   #
   #   * {SetupError}    — construction layer. Raised by `Kobako::Sandbox.new`
   #                       when the wasm runtime cannot be built from the
-  #                       configured +wasm_path+ before any invocation runs
-  #                       ({docs/behavior.md E-40 / E-41}[link:../../docs/behavior.md]).
+  #                       configured +wasm_path+ before any invocation runs.
   #                       Not an invocation outcome, so it never passes
   #                       through the two-step attribution decision.
   #   * {PoolTimeoutError} — pool checkout layer. Raised by `Kobako::Pool#with`
-  #                       when the checkout wait exceeds +checkout_timeout+
-  #                       ({docs/behavior.md E-46}[link:../../docs/behavior.md]).
+  #                       when the checkout wait exceeds +checkout_timeout+.
   #
-  # Subclasses pinned by docs/behavior.md Error Classes:
+  # Named subclasses:
   #
   #   * {ModuleNotBuiltError} < {SetupError} — Guest Binary artifact absent
-  #                       at +wasm_path+ (E-40).
-  #   * {HandlerExhaustedError} < {SandboxError} — Handle id cap hit (B-21).
+  #                       at +wasm_path+.
+  #   * {HandlerExhaustedError} < {SandboxError} — Handle id cap hit.
 
   # Base for all kobako-raised errors so callers that want to ignore the
   # taxonomy can rescue a single class.
@@ -46,13 +44,13 @@ module Kobako
   # 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
-  # (zero-length OUTCOME_BUFFER, unknown outcome tag — SPEC E-02 / E-03).
+  # (zero-length OUTCOME_BUFFER, unknown outcome tag).
   #
-  # Two named subclasses cover the configured per-invocation caps from B-01:
+  # Two named subclasses cover the configured per-invocation caps:
   #
-  #   * {TimeoutError}     — wall-clock +timeout+ exceeded (E-19).
+  #   * {TimeoutError}     — wall-clock +timeout+ exceeded.
   #   * {MemoryLimitError} — guest +memory.grow+ would exceed
-  #                          +memory_limit+ (E-20).
+  #                          +memory_limit+.
   #
   # Host Apps that only care about "guest is unrecoverable, discard the
   # Sandbox" can rescue +TrapError+ and ignore the subclass; Host Apps that
@@ -60,24 +58,23 @@ module Kobako
   # first.
   class TrapError < Error; end
 
-  # 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.
+  # 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.
   class TimeoutError < TrapError; end
 
-  # 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.
+  # 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.
   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
-  # ({docs/behavior.md E-41}[link:../../docs/behavior.md]). Construction
+  # 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"
@@ -86,8 +83,7 @@ module Kobako
 
   # 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+
-  # ({docs/behavior.md E-40}[link:../../docs/behavior.md]). Host Apps
+  # 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.
@@ -123,19 +119,18 @@ module Kobako
     end
   end
 
-  # docs/behavior.md Error Classes: HandlerExhaustedError is the canonical
-  # SandboxError subclass for the id-cap-hit path (B-21). Raised when the
-  # per-invocation Handle ID counter in Catalog::Handles reaches
-  # +0x7fff_ffff+ (2³¹ − 1) and further allocation would exceed the cap.
+  # HandlerExhaustedError 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.
   class HandlerExhaustedError < SandboxError; 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
+  # 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.
@@ -143,8 +138,7 @@ module Kobako
 
   # Pool checkout layer. Raised by +Kobako::Pool#with+ when the checkout
   # wait exceeded the configured +checkout_timeout+ while every slot was
-  # held ({docs/behavior.md E-46}[link:../../docs/behavior.md]). No
-  # Sandbox state is touched — retrying succeeds as soon as a holder
+  # held. No Sandbox state is touched — retrying succeeds as soon as a holder
   # returns its Sandbox.
   class PoolTimeoutError < Error; end
 end

data/lib/kobako/handle.rb

@@ -3,9 +3,8 @@
 module Kobako
   # Wire-level value object for an ext-0x01 Capability Handle, used in both
   # directions across the Sandbox boundary: as a Service method's return
-  # value (guest→host return path; {docs/behavior.md B-14}[link:../../docs/behavior.md])
-  # and as a +#run+ argument auto-wrapped by the host
-  # ({docs/behavior.md B-34}[link:../../docs/behavior.md]).
+  # value (guest→host return path) and as a +#run+ argument auto-wrapped
+  # by the host.
   #
   # SPEC pins the binary layout to fixext 4 with a 4-byte big-endian u32
   # payload ({docs/wire-codec.md}[link:../../docs/wire-codec.md]

data/lib/kobako/namespace.rb

@@ -1,13 +1,11 @@
 # frozen_string_literal: true
 
 module Kobako
-  # A named grouping of Members for one Sandbox
-  # ({docs/behavior.md B-07..B-11}[link:../../docs/behavior.md]).
+  # A named grouping of Members for one Sandbox.
   # Returned by +Sandbox#define+. Each instance owns a flat name→object
   # table of Members; member binding is validated against {NAME_PATTERN}.
   class Namespace
-    # Ruby constant-name pattern shared by Namespace and Member names
-    # ({docs/behavior.md B-07/B-08 Notes}[link:../../docs/behavior.md]).
+    # Ruby constant-name pattern shared by Namespace and Member names.
     NAME_PATTERN = /\A[A-Z]\w*\z/
 
     attr_reader :name
@@ -26,9 +24,8 @@ module Kobako
     # object that responds to the methods guest code will invoke. Returns
     # +self+ for chaining. Raises +ArgumentError+ when +member+ does not
     # match the constant pattern, when a Member of the same name is
-    # already bound ({docs/behavior.md B-11}[link:../../docs/behavior.md]),
-    # or when the owning Sandbox's first invocation has sealed Service
-    # registration ({docs/behavior.md E-45}[link:../../docs/behavior.md]).
+    # already bound, or when the owning Sandbox's first invocation has
+    # sealed Service registration.
     def bind(member, object)
       raise ArgumentError, "cannot bind after first Sandbox invocation" if @sealed
 
@@ -39,10 +36,10 @@ module Kobako
       self
     end
 
-    # Mark this Namespace as sealed ({docs/behavior.md B-33}[link:../../docs/behavior.md]).
-    # Called by +Kobako::Catalog::Namespaces#seal!+ on the owning
-    # Sandbox's first invocation; afterwards {#bind} raises
-    # +ArgumentError+ (E-45). Idempotent; returns +self+.
+    # Mark this Namespace as sealed. Called by
+    # +Kobako::Catalog::Namespaces#seal!+ on the owning Sandbox's first
+    # invocation; afterwards {#bind} raises +ArgumentError+. Idempotent;
+    # returns +self+.
     def seal!
       @sealed = true
       self

data/lib/kobako/outcome.rb

@@ -7,8 +7,7 @@ module Kobako
   # Host-facing boundary for the OUTCOME_BUFFER produced 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
-  # ({docs/behavior.md Error Scenarios}[link:../../docs/behavior.md]) exception.
+  # mruby return value or a raised three-layer exception.
   #
   # Self-contained: this module owns the wire framing (tag bytes,
   # body decoding), and the +Panic+ wire record lives at
@@ -17,11 +16,11 @@ module Kobako
   # nothing in +Transport+ participates.
   #
   #   * tag 0x01, decode OK                 → return decoded value
-  #   * tag 0x01, decode fails              → SandboxError (E-09)
-  #   * tag 0x02, origin="service"          → ServiceError (E-13)
-  #   * tag 0x02, origin="sandbox"/missing  → SandboxError (E-04..E-07)
-  #   * tag 0x02, decode fails              → SandboxError (E-08)
-  #   * unknown tag                         → TrapError    (E-03)
+  #   * tag 0x01, decode fails              → SandboxError
+  #   * tag 0x02, origin="service"          → ServiceError
+  #   * tag 0x02, origin="sandbox"/missing  → SandboxError
+  #   * tag 0x02, decode fails              → SandboxError
+  #   * unknown tag                         → TrapError
   module Outcome
     # First byte of the OUTCOME_BUFFER for the success branch — body is
     # the bare msgpack encoding of the returned value
@@ -71,7 +70,7 @@ module Kobako
       [tag, body]
     end
 
-    # Decode failure on the success tag is a SandboxError (E-09): the
+    # Decode failure on the success tag is a SandboxError: the
     # 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
@@ -86,7 +85,7 @@ module Kobako
       )
     end
 
-    # Decode failure on the panic tag is a SandboxError (E-08). Either
+    # Decode failure on the panic tag is a SandboxError. Either
     # path raises — on success the decoded Panic is mapped to its three-
     # layer exception via +build_panic_error+ and raised; on wire-decode
     # failure the rescue path raises the wire-violation +SandboxError+.
@@ -130,13 +129,12 @@ module Kobako
       )
     end
 
-    # {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"+ →
+    # Map the panic +class+ field to the matching Ruby exception subclass
+    # so 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.
+    # subclass. Everything else falls back to the base class for the
+    # origin.
     def panic_target_class(panic)
       case panic.origin
       when Panic::ORIGIN_SERVICE

data/lib/kobako/pool.rb

@@ -5,32 +5,28 @@ require_relative "sandbox"
 
 module Kobako
   # Kobako::Pool — a bounded set of warm, identically set-up Sandboxes
-  # handed out one exclusive holder at a time
-  # ({docs/behavior.md B-46..B-48}[link:../../docs/behavior.md]).
+  # handed out one exclusive holder at a time.
   #
   # Construction forwards every +Kobako::Sandbox.new+ keyword verbatim
   # and holds the optional block as the per-Sandbox setup hook; a
   # checkout prefers an idle Sandbox and constructs a new one only when
-  # none is idle and fewer than +slots+ exist (B-46). +#with+ blocks up
-  # to +checkout_timeout+ seconds when every slot is held (E-46), applies
-  # the +TrapError+ discard-and-recreate contract at checkin (B-47), and
+  # none is idle and fewer than +slots+ exist. +#with+ blocks up
+  # to +checkout_timeout+ seconds when every slot is held, applies
+  # the +TrapError+ discard-and-recreate contract at checkin, and
   # the Pool releases everything with its own reachability — there is no
-  # teardown verb (B-48).
+  # teardown verb.
   class Pool
-    # The +#with+ wait bound applied when +checkout_timeout+ is not given
-    # ({docs/behavior.md B-46}[link:../../docs/behavior.md]).
+    # The +#with+ wait bound applied when +checkout_timeout+ is not given.
     DEFAULT_CHECKOUT_TIMEOUT_SECONDS = 5.0
 
-    # Build a Pool of up to +slots+ Sandboxes
-    # ({docs/behavior.md B-46}[link:../../docs/behavior.md]). +slots+ is
+    # Build a Pool of up to +slots+ Sandboxes. +slots+ is
     # a positive Integer; +checkout_timeout+ bounds the +#with+ wait in
     # seconds (+nil+ waits indefinitely); every other keyword is
     # forwarded verbatim to +Kobako::Sandbox.new+. The optional block
     # runs exactly once per constructed Sandbox — it is the setup window
     # for +#define+ / +#preload+ before that Sandbox's first checkout.
     # No Sandbox is constructed here. Raises +ArgumentError+ for an
-    # invalid +slots+ / +checkout_timeout+
-    # ({docs/behavior.md E-47}[link:../../docs/behavior.md]).
+    # invalid +slots+ / +checkout_timeout+.
     def initialize(slots:, checkout_timeout: DEFAULT_CHECKOUT_TIMEOUT_SECONDS, **sandbox_options, &setup)
       validate_slots!(slots)
       @slots = slots
@@ -44,11 +40,9 @@ module Kobako
     end
 
     # Yield one exclusively-held Sandbox to the block and return the
-    # block's value ({docs/behavior.md B-47}[link:../../docs/behavior.md]).
-    # Blocks while every slot is held; raises +Kobako::PoolTimeoutError+
-    # once the wait exceeds +checkout_timeout+
-    # ({docs/behavior.md E-46}[link:../../docs/behavior.md]). The Sandbox
-    # returns to the pool at block exit — unless the block raised
+    # block's value. Blocks while every slot is held; raises
+    # +Kobako::PoolTimeoutError+ once the wait exceeds +checkout_timeout+.
+    # The Sandbox returns to the pool at block exit — unless the block raised
     # +Kobako::TrapError+, in which case the unrecoverable Sandbox is
     # discarded and its slot refills by a fresh construction on next
     # demand.
@@ -68,12 +62,12 @@ module Kobako
     private
 
     # Acquire a Sandbox and hand it over in pre-invocation state — empty
-    # output buffers and truncation predicates false (B-47).
+    # output buffers and truncation predicates false.
     def checkout
       acquire.tap(&:reset_invocation_state!)
     end
 
-    # The idle-first claim loop (B-46): an idle Sandbox wins, unclaimed
+    # The idle-first claim loop: an idle Sandbox wins, unclaimed
     # capacity constructs, and a full pool waits for a checkin.
     def acquire
       timeout = @checkout_timeout
@@ -105,7 +99,7 @@ module Kobako
     end
 
     # Wait for a checkin or freed capacity; raises
-    # +Kobako::PoolTimeoutError+ once +deadline+ has passed (E-46). Must
+    # +Kobako::PoolTimeoutError+ once +deadline+ has passed. Must
     # run while holding +@mutex+.
     def await_slot!(deadline)
       remaining = deadline && (deadline - monotonic_now)
@@ -119,7 +113,7 @@ module Kobako
 
     # Construct and set up one pooled Sandbox against the capacity
     # reserved by +claim_or_wait+. Construction and setup-block errors
-    # propagate to the checkout caller unchanged (B-46); the reserved
+    # propagate to the checkout caller unchanged; the reserved
     # capacity is released so a later checkout can retry.
     def construct_slot
       done = false
@@ -154,7 +148,7 @@ module Kobako
       Process.clock_gettime(Process::CLOCK_MONOTONIC)
     end
 
-    # E-47 pre-flight for +slots+ — no coercion, a positive Integer is
+    # Pre-flight for +slots+ — no coercion, a positive Integer is
     # the only accepted shape.
     def validate_slots!(slots)
       return if slots.is_a?(Integer) && slots.positive?
@@ -163,8 +157,8 @@ module Kobako
     end
 
     # Coerce +checkout_timeout+ into the Float seconds the wait loop
-    # consumes, or +nil+ to wait indefinitely — the E-39 normalisation
-    # idiom applied to E-47.
+    # consumes, or +nil+ to wait indefinitely — the same normalisation
+    # idiom +SandboxOptions+ applies to +timeout+.
     def normalize_checkout_timeout(checkout_timeout)
       return nil if checkout_timeout.nil?
       unless checkout_timeout.is_a?(Numeric)