kobako 0.9.2 → 0.11.0

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

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+require_relative "sandbox"
+
+module Kobako
+  # Kobako::Pool — a bounded set of warm, identically set-up Sandboxes
+  # 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. +#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.
+  class Pool
+    # 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. +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+.
+    def initialize(slots:, checkout_timeout: DEFAULT_CHECKOUT_TIMEOUT_SECONDS, **sandbox_options, &setup)
+      validate_slots!(slots)
+      @slots = slots
+      @checkout_timeout = normalize_checkout_timeout(checkout_timeout)
+      @sandbox_options = sandbox_options
+      @setup = setup
+      @idle = [] # : Array[Kobako::Sandbox]
+      @constructed = 0
+      @mutex = Mutex.new
+      @slot_freed = ConditionVariable.new
+    end
+
+    # Yield one exclusively-held Sandbox to the block and return the
+    # 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.
+    def with
+      sandbox = checkout
+      begin
+        yield sandbox
+      rescue TrapError
+        release_capacity!
+        sandbox = nil
+        raise
+      ensure
+        checkin(sandbox) if sandbox
+      end
+    end
+
+    private
+
+    # Acquire a Sandbox and hand it over in pre-invocation state — empty
+    # output buffers and truncation predicates false.
+    def checkout
+      acquire.tap(&:reset_invocation_state!)
+    end
+
+    # 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
+      deadline = timeout && (monotonic_now + timeout)
+      loop do
+        action, sandbox = claim_or_wait(deadline)
+        return sandbox if action == :idle && sandbox
+        return construct_slot if action == :build
+      end
+    end
+
+    # Single locked decision point for one claim attempt. Waiting
+    # happens inside the lock (so a checkin can wake it); construction
+    # happens outside (so a slow setup block never holds the lock) —
+    # capacity is reserved here and released by +construct_slot+ on
+    # failure.
+    def claim_or_wait(deadline)
+      @mutex.synchronize do
+        return [:idle, @idle.pop] unless @idle.empty?
+
+        if @constructed < @slots
+          @constructed += 1
+          return [:build, nil]
+        end
+
+        await_slot!(deadline)
+        [:retry, nil]
+      end
+    end
+
+    # Wait for a checkin or freed capacity; raises
+    # +Kobako::PoolTimeoutError+ once +deadline+ has passed. Must
+    # run while holding +@mutex+.
+    def await_slot!(deadline)
+      remaining = deadline && (deadline - monotonic_now)
+      if remaining && remaining <= 0
+        raise PoolTimeoutError,
+              "no Sandbox returned within #{@checkout_timeout}s: all #{@slots} slots are held"
+      end
+
+      @slot_freed.wait(@mutex, remaining)
+    end
+
+    # 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; the reserved
+    # capacity is released so a later checkout can retry.
+    def construct_slot
+      done = false
+      sandbox = Sandbox.new(**@sandbox_options)
+      @setup&.call(sandbox)
+      done = true
+      sandbox
+    ensure
+      release_capacity! unless done
+    end
+
+    # Return a Sandbox to the idle list and wake one waiting checkout.
+    def checkin(sandbox)
+      @mutex.synchronize do
+        @idle.push(sandbox)
+        @slot_freed.signal
+      end
+    end
+
+    # Give back reserved-but-unfilled capacity — a failed construction or
+    # a discarded Sandbox — and wake one waiting checkout to claim it.
+    def release_capacity!
+      @mutex.synchronize do
+        @constructed -= 1
+        @slot_freed.signal
+      end
+    end
+
+    # The wait deadline runs on the monotonic clock so a wall-clock jump
+    # cannot stretch or cut the checkout wait.
+    def monotonic_now
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    # 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?
+
+      raise ArgumentError, "slots must be a positive Integer, got #{slots.inspect}"
+    end
+
+    # Coerce +checkout_timeout+ into the Float seconds the wait loop
+    # 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)
+        raise ArgumentError, "checkout_timeout must be Numeric or nil, got #{checkout_timeout.inspect}"
+      end
+
+      seconds = checkout_timeout.to_f
+      unless seconds.positive? && seconds.finite?
+        raise ArgumentError, "checkout_timeout must be > 0 and finite (got #{checkout_timeout})"
+      end
+
+      seconds
+    end
+  end
+end

data/lib/kobako/sandbox.rb

@@ -13,21 +13,19 @@ 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]).
+  # scripts inside a wasmtime-hosted Wasm module.
   #
   # 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.
+  # +Kobako::Catalog::Handles+, 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=+. 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
+  # Output capture policy: the
   # per-channel cap (+stdout_limit+ / +stderr_limit+) is enforced inside the
   # WASI pipe — the host buffer stops growing at the cap, subsequent guest
   # writes on that channel fail or are dropped, and +#run+ still returns
@@ -46,9 +44,8 @@ module Kobako
 
     # Returns the bytes the guest wrote to stdout during the most recent
     # invocation as a UTF-8 String, clipped at +stdout_limit+. Empty before
-    # any invocation. {docs/behavior.md B-04}[link:../../docs/behavior.md] — the byte
-    # content never contains a truncation sentinel; use +#stdout_truncated?+ to
-    # observe overflow.
+    # any invocation; the byte content never contains a truncation sentinel,
+    # so use +#stdout_truncated?+ to observe overflow.
     def stdout
       @stdout_capture.bytes
     end
@@ -61,9 +58,8 @@ module Kobako
     end
 
     # Returns +true+ iff stdout capture during the most recent invocation
-    # exceeded +stdout_limit+ ({docs/behavior.md B-04}[link:../../docs/behavior.md]). Resets
-    # to +false+ at the start of the next invocation
-    # ({docs/behavior.md B-03}[link:../../docs/behavior.md]).
+    # exceeded +stdout_limit+. Resets to +false+ at the start of the next
+    # invocation.
     def stdout_truncated?
       @stdout_capture.truncated?
     end
@@ -75,8 +71,7 @@ module Kobako
     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
+    # invocation. 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;
@@ -109,9 +104,8 @@ module Kobako
       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
+    # Declare or retrieve the Namespace named +name+ on this Sandbox. +name+
+    # must be a Symbol or String in constant form. Returns the
     # +Kobako::Namespace+.
     #
     # Raises +ArgumentError+ when called after the first invocation, or
@@ -120,20 +114,18 @@ module Kobako
       @services.define(name)
     end
 
-    # Register a snippet on this Sandbox in one of two forms
-    # ({docs/behavior.md B-32}[link:../../docs/behavior.md]):
+    # Register a snippet on this Sandbox in one of two forms:
     #
     #   * +preload(code: source, name: Name)+ — +source+ is mruby source
     #     as a +String+ and +Name+ matches +/\A[A-Z]\w*\z/+. The +name+
     #     becomes the snippet's +(snippet:Name)+ backtrace filename and
-    #     is the dedupe key for E-33.
+    #     is the dedupe key that rejects a duplicate +code:+ snippet.
     #   * +preload(binary: bytes)+ — +bytes+ is precompiled RITE
     #     bytecode as a +String+. The canonical name, when present,
     #     lives in the bytecode's embedded +debug_info+ and is resolved
     #     by the guest at load time; the host treats the bytes as
-    #     opaque. Structural failures
-    #     ({docs/behavior.md E-37 / E-38}[link:../../docs/behavior.md])
-    #     surface as +Kobako::BytecodeError+ on the first invocation.
+    #     opaque. Structural failures surface as +Kobako::BytecodeError+
+    #     on the first invocation.
     #
     # Subsequent invocations (+#eval+ or +#run+) replay every registered
     # snippet — in insertion order — against the fresh +mrb_state+
@@ -145,11 +137,9 @@ module Kobako
     # supplied, when both forms are mixed (e.g., +code:+ and +binary:+
     # together, or +binary:+ paired with +name:+), when +code+ / +bytes+
     # is not a +String+, when +name+ does not match the constant
-    # pattern ({docs/behavior.md E-34}[link:../../docs/behavior.md]),
-    # when +name+ duplicates an already-registered +code:+ form snippet
-    # ({docs/behavior.md E-33}[link:../../docs/behavior.md]), or when
-    # called after the first invocation
-    # ({docs/behavior.md E-35, B-33}[link:../../docs/behavior.md]).
+    # pattern, when +name+ duplicates an already-registered +code:+ form
+    # snippet, or when called after the first invocation has sealed the
+    # snippet table.
     def preload(code: nil, name: nil, binary: nil)
       raise ArgumentError, "cannot preload after first Sandbox invocation" if @services.sealed?
 
@@ -157,17 +147,16 @@ module Kobako
       self
     end
 
-    # Dispatch into a preloaded entrypoint constant
-    # ({docs/behavior.md B-31}[link:../../docs/behavior.md]). Delegates host
+    # Dispatch into a preloaded entrypoint constant. Delegates host
     # 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+.
+    # +TypeError+, while a +target+ failing the constant pattern, a forged
+    # +Kobako::Handle+ in +args+ / +kwargs+, or a non-Symbol +kwargs+ key
+    # 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. Runtime errors follow the same three-class
+    # taxonomy as +#eval+.
     def run(target, *args, **kwargs)
       run_envelope = Transport::Run.new(entrypoint: target, args: args, kwargs: kwargs)
       invoke!(:run) do
@@ -175,29 +164,27 @@ module Kobako
       end
     end
 
-    # Execute a guest mruby source string in a fresh +mrb_state+
-    # ({docs/behavior.md B-02 / B-03 / B-06}[link:../../docs/behavior.md]). +code+ is the
-    # mruby source as a UTF-8 String. Returns the deserialized last
+    # Execute a guest mruby source string in a fresh +mrb_state+. +code+ is
+    # the mruby source as a UTF-8 String. Returns the deserialized last
     # expression of the source.
     #
     # Source delivery uses the WASI stdin three-frame protocol
     # ({docs/wire-codec.md Invocation channels}[link:../../docs/wire-codec.md]):
     # Frame 1 carries the msgpack-encoded preamble (Namespace / Member
     # registry snapshot), Frame 2 carries the user source UTF-8 bytes, and
-    # Frame 3 carries the snippet table registered via +#preload+ (B-32).
+    # Frame 3 carries the snippet table registered via +#preload+.
     # Each frame is prefixed by a 4-byte big-endian u32 length; Frame 3 is
     # mandatory-presence — an empty snippet table sends an empty msgpack
     # array, never an absent frame.
     #
-    # The first invocation seals the Service registry and snippet table
-    # ({docs/behavior.md B-07 / B-33}[link:../../docs/behavior.md]); subsequent
-    # +#define+ / +#preload+ calls raise +ArgumentError+.
+    # The first invocation seals the Service registry and snippet table;
+    # subsequent +#define+ / +#preload+ calls raise +ArgumentError+.
     #
     # Raises +Kobako::TrapError+ on a Wasm trap or wire-violation fallback;
     # +Kobako::SandboxError+ when the guest ran to completion but failed
     # (including when +code+ is +nil+ or not a String, or when a preloaded
-    # snippet's replay raises — E-36);
-    # +Kobako::ServiceError+ on an unrescued Service capability failure.
+    # snippet's replay raises); +Kobako::ServiceError+ on an unrescued
+    # Service capability failure.
     def eval(code)
       raise SandboxError, "code must be a String, got #{code.class}" unless code.is_a?(String)
 
@@ -206,16 +193,27 @@ module Kobako
       end
     end
 
+    # Reset all per-invocation observable state to its pre-invocation
+    # sentinels — both per-channel captures and the per-last-invocation
+    # usage record. Shared by +#initialize+ (first-time setup) and
+    # +#begin_invocation!+ (between-invocation reset) so both paths agree on
+    # what "pre-invocation state" means; +Kobako::Pool+ calls it at checkout
+    # so a pooled Sandbox hands over empty output buffers.
+    def reset_invocation_state!
+      @stdout_capture = Capture::EMPTY
+      @stderr_capture = Capture::EMPTY
+      @usage = Usage::EMPTY
+    end
+
     private
 
-    # Configure the +Runtime+'s host↔guest dispatch wiring
-    # ({docs/behavior.md B-12}[link:../../docs/behavior.md]). Builds a
+    # Configure the +Runtime+'s host↔guest dispatch wiring. 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.
+    # +Runtime#yield_to_active_invocation+ 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|
@@ -223,37 +221,21 @@ module Kobako
       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
+    # Per-invocation prologue. Seals the Service / snippet registries on
+    # first call (idempotent) and zeros the per-invocation capability
+    # state — capture buffers, truncation predicates, and the
     # +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).
+    # +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".
     def begin_invocation!
       @services.seal!
       @handler.reset!
       reset_invocation_state!
     end
 
-    # 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-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 ext and wrap them as a +Kobako::Usage+ value object. Runs in
     # the +invoke!+ +ensure+ block so the usage record is populated on
     # every outcome — value return, +Kobako::TrapError+ (including
     # +TimeoutError+ / +MemoryLimitError+), +Kobako::SandboxError+,
@@ -271,8 +253,7 @@ module Kobako
     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])
+    # class. Cap-trap subclasses (+TimeoutError+ / +MemoryLimitError+)
     # 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!+
@@ -296,9 +277,8 @@ module Kobako
     # +Capture+ and feeds +#return_bytes+ to +Outcome.decode+; usage is
     # populated by the +ensure+ readout ({#read_usage!}) on every outcome.
     # 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
+    # configured-cap paths surface as named TrapError subclasses
+    # (+TimeoutError+ / +MemoryLimitError+); everything else surfaces as
     # the base +TrapError+.
     def invoke!(verb)
       begin_invocation!
@@ -307,7 +287,7 @@ module Kobako
       @stderr_capture = snapshot.stderr
       # A Capability Handle in the result is decoded as a Kobako::Handle
       # token; restore it to the host object the guest referenced before
-      # handing the value to the Host App (B-37). @handler still holds this
+      # handing the value to the Host App. @handler still holds this
       # invocation's table — reset only happens at the next #begin_invocation!.
       Codec::Utils.deep_restore(Outcome.decode(snapshot.return_bytes), @handler)
     rescue Kobako::TrapError => e

data/lib/kobako/sandbox_options.rb

@@ -2,8 +2,7 @@
 
 module Kobako
   # Kobako::SandboxOptions — immutable Value Object holding the four
-  # per-Sandbox configuration caps ({docs/behavior.md B-01,
-  # E-20}[link:../../docs/behavior.md]). Built on the +class X <
+  # per-Sandbox configuration caps. Built on the +class X <
   # Data.define(...)+ subclass form (the Steep-friendly shape — see
   # +lib/kobako/outcome/panic.rb+).
   #
@@ -13,18 +12,15 @@ module Kobako
   # +super+. Anything that survives +SandboxOptions.new+ is a wire-ready
   # 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]).
+    # Default wall-clock timeout for a single invocation: 60 seconds.
     DEFAULT_TIMEOUT_SECONDS = 60.0
 
     # Default cap on the per-invocation guest linear-memory delta:
-    # 1 MiB ({docs/behavior.md B-01}[link:../../docs/behavior.md]).
-    # The mruby image's initial allocation and prior invocations'
-    # watermark sit outside this budget — see B-01 Notes.
+    # 1 MiB. The mruby image's initial allocation and prior invocations'
+    # watermark sit outside this budget.
     DEFAULT_MEMORY_LIMIT = 1 << 20
 
-    # Default per-channel capture ceiling: 1 MiB
-    # ({docs/behavior.md B-01}[link:../../docs/behavior.md]).
+    # Default per-channel capture ceiling: 1 MiB.
     DEFAULT_OUTPUT_LIMIT = 1 << 20
 
     def initialize(timeout: DEFAULT_TIMEOUT_SECONDS,

data/lib/kobako/snapshot.rb

@@ -16,8 +16,7 @@ module Kobako
   # 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
+    # as a +Kobako::Capture+ value object. The byte content never carries
     # a truncation sentinel; +#truncated?+ is the only way to observe
     # that the cap was hit.
     def stdout
@@ -31,8 +30,7 @@ module Kobako
     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]).
+    # +memory_peak+) as a +Kobako::Usage+ value object.
     def usage
       Usage.new(wall_time: wall_time, memory_peak: memory_peak)
     end

data/lib/kobako/snippet/binary.rb

@@ -3,8 +3,7 @@
 module Kobako
   module Snippet
     # Kobako::Snippet::Binary — value object representing a single
-    # +#preload(binary:)+ entry held by +Kobako::Catalog::Snippets+
-    # ({docs/behavior.md B-32}[link:../../../docs/behavior.md]).
+    # +#preload(binary:)+ entry held by +Kobako::Catalog::Snippets+.
     #
     # The +body+ is RITE bytecode (as emitted by +mrbc+) carried as an
     # +ASCII_8BIT+ String so msgpack-ruby encodes it as +bin+ family on
@@ -12,7 +11,6 @@ module Kobako
     # 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
-    # ({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.

data/lib/kobako/snippet/source.rb

@@ -3,8 +3,7 @@
 module Kobako
   module Snippet
     # Kobako::Snippet::Source — value object representing a single
-    # +#preload(code:, name:)+ entry held by +Kobako::Catalog::Snippets+
-    # ({docs/behavior.md B-32}[link:../../../docs/behavior.md]).
+    # +#preload(code:, name:)+ entry held by +Kobako::Catalog::Snippets+.
     #
     # +name+ is the canonical +Symbol+ identity baked into the loaded
     # IREP's +debug_info+; backtrace frames originating in this snippet

data/lib/kobako/snippet.rb

@@ -5,8 +5,7 @@ require_relative "snippet/source"
 
 module Kobako
   # 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]).
+  # held by +Kobako::Catalog::Snippets+.
   #
   # +Source+ represents a single +#preload(code:, name:)+ entry; +Binary+
   # represents a single +#preload(binary:)+ entry. Both are plain value