kobako 0.9.2 → 0.11.0

data/ext/kobako/src/snapshot.rs

@@ -3,8 +3,8 @@
 //! Every successful `Kobako::Runtime#eval` / `#run` returns one of these.
 //! It carries every observable the host needs to surface after a guest
 //! invocation: the OUTCOME_BUFFER bytes (`return_bytes`), the captured
-//! stdout / stderr byte slices with their truncation flags (B-04), and
-//! the wall-clock + memory-peak figures from `Kobako::Usage` (B-35).
+//! stdout / stderr byte slices with their truncation flags, and
+//! the wall-clock + memory-peak figures from `Kobako::Usage`.
 //!
 //! Ruby callers see the seven raw readers registered below; the helper
 //! methods that pack them into `Kobako::Capture` / `Kobako::Usage`

data/lib/kobako/capture.rb

@@ -4,7 +4,7 @@ module Kobako
   # Host-side captured prefix of guest stdout / stderr produced during a
   # single +Kobako::Sandbox+ invocation, paired with the truncation flag
   # the WASI pipe sets when the guest wrote past the configured per-channel
-  # cap ({docs/behavior.md B-04}[link:../../docs/behavior.md]).
+  # cap.
   #
   # Immutable value object: the captured bytes and the truncation flag
   # always travel together and the instance is frozen on construction.
@@ -30,14 +30,12 @@ module Kobako
     end
 
     # Returns +true+ iff the underlying capture channel exceeded its
-    # configured cap during the originating +Sandbox+ invocation
-    # ({docs/behavior.md B-04}[link:../../docs/behavior.md]).
+    # configured cap during the originating +Sandbox+ invocation.
     def truncated? = @truncated
 
-    # Pre-invocation sentinel ({docs/behavior.md B-05}[link:../../docs/behavior.md]).
-    # Empty UTF-8 bytes and +truncated? == false+; reused by every fresh
-    # +Sandbox+ and by +Sandbox+ between invocations to denote "no capture
-    # yet".
+    # Pre-invocation sentinel. Empty UTF-8 bytes and +truncated? == false+;
+    # reused by every fresh +Sandbox+ and by +Sandbox+ between invocations
+    # to denote "no capture yet".
     EMPTY = new(bytes: "", truncated: false)
   end
 end

data/lib/kobako/catalog/handles.rb

@@ -5,41 +5,29 @@ require_relative "../handle"
 module Kobako
   module Catalog
     # Host-side mapping from opaque integer Handle IDs to Ruby objects.
-    # The table is owned by +Kobako::Sandbox+
-    # ({docs/behavior.md B-19}[link:../../../docs/behavior.md]) and injected
+    # The table is owned by +Kobako::Sandbox+ and injected
     # into the per-Sandbox +Kobako::Catalog::Namespaces+ so guest→host dispatch
     # resolves Handle targets and arguments against the same table that
-    # host→guest wire encoding allocates into
-    # ({docs/behavior.md B-14, B-34}[link:../../../docs/behavior.md]).
+    # host→guest wire encoding allocates into.
     #
-    # Lifecycle invariants ({docs/behavior.md}[link:../../../docs/behavior.md]):
+    # Lifecycle invariants:
     #
-    #   - {docs/behavior.md B-15}[link:../../../docs/behavior.md] — Handle IDs
-    #     are allocated by a monotonically increasing counter scoped to a
-    #     single invocation. The first ID issued in an invocation is 1; ID 0
-    #     is reserved as the invalid sentinel and is never returned by
-    #     +#alloc+.
+    #   - Handle IDs are allocated by a monotonically increasing counter
+    #     scoped to a single invocation. The first ID issued in an
+    #     invocation is 1; ID 0 is reserved as the invalid sentinel and is
+    #     never returned by +#alloc+.
     #
-    #   - {docs/behavior.md B-19}[link:../../../docs/behavior.md] — At every
-    #     invocation boundary (via +#reset!+), every Handle issued under the
-    #     old state becomes invalid. Reset applies uniformly regardless of
-    #     allocation source (B-14 Service return or B-34 host-injected
+    #   - At every invocation boundary (via +#reset!+), every Handle issued
+    #     under the old state becomes invalid. Reset applies uniformly
+    #     regardless of allocation source (Service return or host-injected
     #     argument).
     #
-    #   - {docs/behavior.md B-21}[link:../../../docs/behavior.md] — The cap is
-    #     +0x7fff_ffff+ (2³¹ − 1). Allocation beyond the cap raises
-    #     immediately — no silent truncation, no wrap, no ID reuse.
+    #   - The cap is +0x7fff_ffff+ (2³¹ − 1). Allocation beyond the cap
+    #     raises immediately — no silent truncation, no wrap, no ID reuse.
     class Handles
-      # Reflective gadget types that are never minted as a Capability Handle
-      # ({docs/behavior.md B-43}[link:../../../docs/behavior.md]): wrapping a
-      # +Binding+ / +Method+ / +UnboundMethod+ would hand the guest a callable
-      # proxy onto host reflection (a returned +Binding+ reaches +Binding#eval+).
-      UNWRAPPABLE_TYPES = [Binding, Method, UnboundMethod].freeze
-      private_constant :UNWRAPPABLE_TYPES
-
       # Build a fresh, empty table. +next_id+ is an internal seam that
-      # sets the starting value of the monotonic counter (defaults to 1 per
-      # B-15); tests pass a value near +Kobako::Handle::MAX_ID+ to exercise
+      # sets the starting value of the monotonic counter (defaults to 1);
+      # tests pass a value near +Kobako::Handle::MAX_ID+ to exercise
       # the cap-exhaustion path without 2³¹ allocations.
       def initialize(next_id: 1)
         @entries = {} # : Hash[Integer, untyped]
@@ -52,8 +40,7 @@ module Kobako
       # +[Kobako::Handle::MIN_ID, Kobako::Handle::MAX_ID]+. Raises
       # +Kobako::HandlerExhaustedError+ if the next ID would exceed the
       # cap. The cap is anchored on +Kobako::Handle+ — the wire codec
-      # and the allocator share the same invariant
-      # ({docs/behavior.md B-21}[link:../../../docs/behavior.md]).
+      # and the allocator share the same invariant.
       #
       # Returning a Handle (rather than a bare Integer id) keeps the
       # allocator's output a domain entity; +Kobako::Handle.restore+
@@ -76,9 +63,8 @@ module Kobako
         @entries[id]
       end
 
-      # Clear all entries AND reset the counter to 1. Called at the per-invocation
-      # boundary by +Kobako::Sandbox+ — see
-      # {docs/behavior.md B-19}[link:../../../docs/behavior.md]. Returns +self+.
+      # Clear all entries AND reset the counter to 1. Called at the
+      # per-invocation boundary by +Kobako::Sandbox+. Returns +self+.
       def reset!
         @entries.clear
         @next_id = 1
@@ -96,17 +82,20 @@ module Kobako
 
       private
 
-      # Refuse to mint a Capability Handle for a reflective gadget
-      # ({UNWRAPPABLE_TYPES}, B-43). Raising here keeps the rule at the single
-      # mint point, so it holds on both the Service-return (B-14) and the
-      # +#run+ host→guest auto-wrap (B-34) paths.
+      # Refuse to mint a Capability Handle for a reflective gadget:
+      # a +Binding+ / +Method+ / +UnboundMethod+ would hand the guest a
+      # callable proxy onto host reflection (a returned +Binding+ reaches
+      # +Binding#eval+). Raising here keeps the rule at the single mint
+      # point, so it holds on both the Service-return and the +#run+
+      # host→guest auto-wrap paths.
       def reject_unwrappable!(object)
-        return unless UNWRAPPABLE_TYPES.any? { |type| object.is_a?(type) }
-
-        raise SandboxError, "a #{object.class} cannot cross as a Capability Handle"
+        case object
+        when Binding, Method, UnboundMethod
+          raise SandboxError, "a #{object.class} cannot cross as a Capability Handle"
+        end
       end
 
-      # Guard {#alloc} against issuing an ID past the B-21 cap. Returns +nil+
+      # Guard {#alloc} against issuing an ID past the cap. Returns +nil+
       # on success; raises +Kobako::HandlerExhaustedError+ at exhaustion.
       def ensure_capacity!
         cap = Kobako::Handle::MAX_ID

data/lib/kobako/catalog/namespaces.rb

@@ -9,8 +9,7 @@ module Kobako
   module Catalog
     # Kobako::Catalog::Namespaces — per-Sandbox registry of
     # +Kobako::Namespace+ entities. Holds the Namespace / Member bindings
-    # and the preamble emitted on Frame 1
-    # ({docs/behavior.md B-07..B-11}[link:../../../docs/behavior.md]).
+    # and the preamble emitted on Frame 1.
     #
     # Public API:
     #
@@ -24,29 +23,27 @@ module Kobako
     # +Kobako::Transport::Dispatcher+'s responsibility — the Dispatcher
     # receives this registry and the +Catalog::Handles+ as arguments from
     # the +Runtime#on_dispatch+ Proc that +Kobako::Sandbox#initialize+
-    # installs ({docs/behavior.md B-12}[link:../../../docs/behavior.md]).
-    # The registry holds an injected +Catalog::Handles+ reference so
+    # installs. The registry holds an injected +Catalog::Handles+ reference so
     # dispatch target resolution and host→guest auto-wrap share the same
-    # Sandbox-owned allocator ({docs/behavior.md B-19}[link:../../../docs/behavior.md]).
+    # Sandbox-owned allocator.
     class Namespaces
       # Build a fresh registry. +handler+ is an internal seam that injects
       # a pre-configured +Catalog::Handles+; tests pass one whose +next_id+
-      # is pinned near +MAX_ID+ to exercise the B-21 cap-exhaustion path
+      # is pinned near +MAX_ID+ to exercise the cap-exhaustion path
       # without 2³¹ allocations. Production callers leave it at the default.
       def initialize(handler: Catalog::Handles.new)
         @namespaces = {} # : Hash[String, Kobako::Namespace]
         @handler = handler
         @sealed = false
+        @encoded = nil # : String?
       end
 
-      # Declare or retrieve the Namespace named +name+ (idempotent —
-      # {docs/behavior.md B-10}[link:../../../docs/behavior.md]).
+      # Declare or retrieve the Namespace named +name+ (idempotent).
       # +name+ is a constant-form name as a +Symbol+ or +String+ (must satisfy
       # +Namespace::NAME_PATTERN+). Returns the +Kobako::Namespace+ for that
       # name, creating it if it does not exist. Raises +ArgumentError+ when
       # +name+ is malformed, or when called after the owning Sandbox has been
-      # sealed by its first invocation
-      # ({docs/behavior.md B-07}[link:../../../docs/behavior.md]).
+      # sealed by its first invocation.
       def define(name)
         raise ArgumentError, "cannot define after first Sandbox invocation" if @sealed
 
@@ -73,21 +70,35 @@ module Kobako
         namespace.fetch(member_name)
       end
 
-      # Encode the preamble as msgpack bytes for stdin Frame 1 delivery
-      # ({docs/behavior.md B-02}[link:../../../docs/behavior.md]). Routes through
-      # {Kobako::Codec::Encoder} like every other host-side wire encode so
-      # there is a single codec path; the preamble carries only Strings and
-      # Arrays, so none of the kobako ext types actually fire. Structure:
-      # +[["Namespace", ["MemberA", "MemberB"]], ...]+. Returns a binary
-      # +String+ of msgpack bytes.
+      # Encode the preamble as msgpack bytes for stdin Frame 1 delivery.
+      # Routes through {Kobako::Codec::Encoder} like every other host-side
+      # wire encode so there is a single codec path; the preamble carries
+      # only Strings and Arrays, so none of the kobako ext types actually
+      # fire. Structure: +[["Namespace", ["MemberA", "MemberB"]], ...]+.
+      # Returns a binary +String+ of msgpack bytes.
+      #
+      # Once sealed, the bytes are computed once and reused for every
+      # subsequent invocation: sealing freezes Service registration at the
+      # first invocation, so the preamble is exactly the bindings that
+      # existed at that moment — a bind reaching a +Kobako::Namespace+
+      # after the seal raises +ArgumentError+ and never alters Frame 1.
       def encode
-        Codec::Encoder.encode(@namespaces.values.map(&:to_preamble))
+        return @encoded if @encoded
+
+        bytes = Codec::Encoder.encode(@namespaces.values.map(&:to_preamble)).freeze
+        @encoded = bytes if @sealed
+        bytes
       end
 
-      # Mark the registry as sealed. Called by +Sandbox+ on the first
-      # invocation. After sealing, #define raises ArgumentError. Idempotent.
+      # Mark the registry as sealed and propagate the seal to every
+      # declared +Kobako::Namespace+. Called by +Sandbox+ on the first
+      # invocation. After sealing, both #define and +Namespace#bind+
+      # raise ArgumentError. Idempotent.
       def seal!
+        return self if @sealed
+
         @sealed = true
+        @namespaces.each_value(&:seal!)
         self
       end
 

data/lib/kobako/catalog/snippets.rb

@@ -6,8 +6,7 @@ require_relative "../snippet"
 module Kobako
   module Catalog
     # Kobako::Catalog::Snippets — per-Sandbox insertion-ordered registry
-    # of preloaded snippets
-    # ({docs/behavior.md B-32 / B-33}[link:../../../docs/behavior.md]).
+    # of preloaded snippets.
     #
     # Entries replay against the fresh +mrb_state+ before per-invocation
     # source / entrypoint resolution. Each +Snippet::Source+ entry's +name+
@@ -15,22 +14,21 @@ module Kobako
     # +debug_info+ that surfaces in every backtrace frame originating from
     # the snippet as +(snippet:Name):line+. Duplicate names within the
     # +code:+ form would produce ambiguous attribution and are rejected at
-    # registration time
-    # ({docs/behavior.md E-33}[link:../../../docs/behavior.md]).
+    # registration time.
     # +Snippet::Binary+ entries carry no host-side name — their canonical
     # name lives in the bytecode's +debug_info+ and is read by the guest at
     # load time; the host does not extract it.
     #
-    # Sealing (B-33) is governed by the owning Sandbox — the registry itself
+    # Sealing is governed by the owning Sandbox — the registry itself
     # is append-only and exposes no mutation API beyond +#register+; the
     # Sandbox guards +#register+ behind the seal check before delegating.
     class Snippets
-      # Ruby constant-name pattern enforced on snippet names
-      # ({docs/behavior.md E-34}[link:../../../docs/behavior.md]).
+      # Ruby constant-name pattern enforced on snippet names.
       NAME_PATTERN = /\A[A-Z]\w*\z/
 
       def initialize
         @entries = [] # : Array[Kobako::Snippet::Source | Kobako::Snippet::Binary]
+        @encoded = nil # : String?
       end
 
       # Serialize the registered snippets to wire bytes. Each entry
@@ -42,12 +40,17 @@ module Kobako
       # carriers — this collection-tier method reads their attributes
       # externally via +entry_payload+ rather than asking each entry to
       # self-encode.
+      #
+      # The bytes are memoized — the table is replayed verbatim on every
+      # invocation after sealing, so Frame 3 never changes between
+      # encodes; {#register} drops the memo while the table is still open.
       def encode
-        Codec::Encoder.encode(@entries.map { |entry| entry_payload(entry) })
+        return @encoded if @encoded
+
+        @encoded = Codec::Encoder.encode(@entries.map { |entry| entry_payload(entry) }).freeze
       end
 
-      # Register one preloaded snippet in either of two forms
-      # ({docs/behavior.md B-32}[link:../../../docs/behavior.md]).
+      # Register one preloaded snippet in either of two forms.
       #
       #   * Source form +register(code: src, name: Name)+ — +src+ is the
       #     mruby source as a String; the bytes are re-encoded as UTF-8
@@ -58,16 +61,15 @@ module Kobako
       #     precompiled RITE bytecode as a String, duplicated and forced
       #     to ASCII-8BIT so msgpack-ruby ships it as +bin+. Returns
       #     +nil+ — bytecode entries are anonymous on the host side; any
-      #     structural validation
-      #     ({docs/behavior.md E-37 / E-38}[link:../../../docs/behavior.md])
-      #     is deferred to the guest at first replay.
+      #     structural validation is deferred to the guest at first replay.
       #
       # The two forms are mutually exclusive: shape validation lives
       # here so callers (chiefly +Kobako::Sandbox#preload+) collapse to
       # a single delegation. Raises +ArgumentError+ on mixed forms,
-      # missing keywords, wrong types, malformed +name+ (E-34), or
-      # duplicate +code:+ +name+ (E-33).
+      # missing keywords, wrong types, malformed +name+, or
+      # duplicate +code:+ +name+.
       def register(code: nil, name: nil, binary: nil)
+        @encoded = nil
         if binary
           raise ArgumentError, "cannot combine binary: with code: / name:" if code || name
 
@@ -81,7 +83,7 @@ module Kobako
 
       # Source-form register path. Delegates argument-shape checks to
       # +ensure_source_args!+ (which returns the narrowed +[code, name]+
-      # pair), normalises +name+ to a Symbol, rejects duplicates (E-33),
+      # pair), normalises +name+ to a Symbol, rejects duplicates,
       # and appends the Source entry.
       def register_source!(code, name)
         code, name = ensure_source_args!(code, name)

data/lib/kobako/codec/decoder.rb

@@ -64,7 +64,11 @@ module Kobako
           case value
           when String then Utils.assert_utf8!(value, "str payload") if value.encoding == Encoding::UTF_8
           when Array  then value.each { |v| validate_utf8!(v) }
-          when Hash   then value.each { |pair| validate_utf8!(pair) }
+          when Hash
+            value.each do |key, val|
+              validate_utf8!(key)
+              validate_utf8!(val)
+            end
           end
         end
       end

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:
   #
@@ -21,20 +21,21 @@ module Kobako
   #                       call that failed and was not rescued inside the
   #                       script).
   #
-  # A fourth branch sits outside the invocation taxonomy:
+  # Two further branches sit outside the invocation taxonomy:
   #
   #   * {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+.
   #
-  # 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.
@@ -43,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
@@ -57,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"
@@ -83,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.
@@ -120,21 +119,26 @@ 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.
   class BytecodeError < SandboxError; 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.
+  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
@@ -18,15 +16,19 @@ module Kobako
     def initialize(name)
       @name = name
       @members = {} # : Hash[String, untyped]
+      @sealed = false
     end
 
     # Bind +object+ under +member+ inside this Namespace. +member+ is a
     # constant-form name as a +Symbol+ or +String+. +object+ is any Ruby
     # object that responds to the methods guest code will invoke. Returns
     # +self+ for chaining. Raises +ArgumentError+ when +member+ does not
-    # match the constant pattern, or a Member of the same name is already
-    # bound ({docs/behavior.md B-11}[link:../../docs/behavior.md]).
+    # match the constant pattern, when a Member of the same name is
+    # 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
+
       member_str = validate_member_name!(member)
       raise ArgumentError, "Member #{@name}::#{member_str} is already bound" if @members.key?(member_str)
 
@@ -34,6 +36,15 @@ module Kobako
       self
     end
 
+    # 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
+    end
+
     # Member lookup; raises +KeyError+ when no Member is registered
     # under +member+.
     def fetch(member)