kobako 0.10.0-aarch64-linux → 0.11.0-aarch64-linux

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)

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)
 
@@ -207,15 +194,11 @@ module Kobako
     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; +Kobako::Pool+ calls it at checkout
-    # so a pooled Sandbox hands over empty output buffers
-    # ({docs/behavior.md B-47}[link:../../docs/behavior.md]).
+    # 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
@@ -224,14 +207,13 @@ module Kobako
 
     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|
@@ -239,14 +221,13 @@ 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!
@@ -254,8 +235,7 @@ module Kobako
     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+,
@@ -273,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!+
@@ -298,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!
@@ -309,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