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

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 57c31ede9c0c253bd6186a0c950286aa4af392b81befdec4453f97bbc5a84eda
-  data.tar.gz: 28b31fd5e6ff25ba026e8c13d160165e5dd0539242841190601e72c09df820f6
+  metadata.gz: 8a44a6f91fb5e57a8cc4cfca97e501fab889eef17961c8088b736625e0a06983
+  data.tar.gz: 5ce894137c6df04ddf48b4bbd821bf76764a06663d7552624539e6a6ffa88242
 SHA512:
-  metadata.gz: 5e80224cc7d153c4980d3eeaea0b974c8a12e65d9fb280c5dec1e2dc057a012bd9407f47a5f37447df66e12c7ea00cf00cb248e6a115cd6ad6c76b627dda5be6
-  data.tar.gz: d7727d01b800a4f8e877c9925fc2619919e7c262e986617cb903e6282bad6c79456ce7d292b40db993574912ad9ce598b3a9c41f5603ad8b1e26d538d291ceb3
+  metadata.gz: 8d28583de8802ed0dcab2cb1138d671674cf9ca11823a766ec9a46a075c73aa24d40da121273da0c506fddebea1a6fa1cd75e1041aff4a2929391b7b97d5e064
+  data.tar.gz: c6aea42ae6d840cee738ee3306e2963d4ad4e60f6e640835e9f38ef98a323a267f04986d27afb08ee6bb21665a245bee97e05eaba13596220dbbd914f2325b56

data/.release-please-manifest.json

@@ -1 +1 @@
-{".":"0.10.0","wasm/kobako-core":"0.5.0","wasm/kobako":"0.5.0","wasm/kobako-io":"0.5.0","wasm/kobako-regexp":"0.5.0","wasm/kobako-baker":"0.5.0"}
+{".":"0.11.0","wasm/kobako-core":"0.5.0","wasm/kobako":"0.5.0","wasm/kobako-io":"0.5.0","wasm/kobako-regexp":"0.5.0","wasm/kobako-baker":"0.5.0"}

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.11.0](https://github.com/elct9620/kobako/compare/v0.10.0...v0.11.0) (2026-06-13)
+
+
+### Features
+
+* **transport:** narrow guest-reachable methods via respond_to_guest? ([7a25fe3](https://github.com/elct9620/kobako/commit/7a25fe3b440b523b8a692b7601d08877b1305b0d))
+
 ## [0.10.0](https://github.com/elct9620/kobako/compare/v0.9.2...v0.10.0) (2026-06-12)
 
 

data/README.md

@@ -69,7 +69,7 @@ The script executes inside the Wasm guest. It cannot read your filesystem, open
 
 ### Services
 
-Declare a Namespace, then `bind` any Ruby object as a Member; the guest reaches it as a `<Namespace>::<Member>` proxy and invokes its public methods through the Transport wire. See [`docs/behavior.md`](docs/behavior.md) B-07..B-12.
+Declare a Namespace, then `bind` any Ruby object as a Member; the guest reaches it as a `<Namespace>::<Member>` proxy and invokes its public methods through the Transport wire. See [`docs/behavior/registration.md`](docs/behavior/registration.md) B-07..B-12.
 
 ```ruby
 class User
@@ -93,7 +93,7 @@ Names must match `/\A[A-Z]\w*\z/`. Symbol kwargs travel transparently to the hos
 
 ### Output Capture
 
-Guest writes through `puts` / `print` / `p` / `$stdout` / `$stderr` are buffered per-channel and exposed independently of the return value ([`docs/behavior.md`](docs/behavior.md) B-04). Buffers clear at the start of each invocation; overflow is clipped at the cap and flagged by `#stdout_truncated?` / `#stderr_truncated?`.
+Guest writes through `puts` / `print` / `p` / `$stdout` / `$stderr` are buffered per-channel and exposed independently of the return value ([`docs/behavior/lifecycle.md`](docs/behavior/lifecycle.md) B-04). Buffers clear at the start of each invocation; overflow is clipped at the cap and flagged by `#stdout_truncated?` / `#stderr_truncated?`.
 
 ```ruby
 result = sandbox.eval(<<~RUBY)
@@ -134,7 +134,7 @@ end
 
 ### Resource Limits
 
-Each invocation enforces a wall-clock `timeout` and a per-invocation linear-memory `memory_limit`; exhaustion raises a `TrapError` subclass. Pass `nil` to `timeout` / `memory_limit` to disable that cap. Read [`Sandbox#usage`](lib/kobako/sandbox.rb) after the call — populated on every outcome including traps — for actual consumption ([`docs/behavior.md`](docs/behavior.md) B-35).
+Each invocation enforces a wall-clock `timeout` and a per-invocation linear-memory `memory_limit`; exhaustion raises a `TrapError` subclass. Pass `nil` to `timeout` / `memory_limit` to disable that cap. Read [`Sandbox#usage`](lib/kobako/sandbox.rb) after the call — populated on every outcome including traps — for actual consumption ([`docs/behavior/lifecycle.md`](docs/behavior/lifecycle.md) B-35).
 
 ```ruby
 sandbox = Kobako::Sandbox.new(
@@ -202,7 +202,9 @@ For workloads that must be isolated from each other (one Sandbox per tenant, per
 
 ### Pooling
 
-For hosts that serve many short invocations, `Kobako::Pool` keeps a bounded set of warm, identically set-up Sandboxes and hands each one to a single exclusive holder at a time ([`docs/behavior.md`](docs/behavior.md) B-46..B-48). Construction forwards every `Sandbox.new` keyword verbatim; the optional block is the per-Sandbox setup window and runs exactly once per constructed Sandbox.
+For hosts that serve many short invocations, `Kobako::Pool` keeps a bounded set of warm, identically set-up Sandboxes and hands each one to a single exclusive holder at a time ([`docs/behavior/runtime.md`](docs/behavior/runtime.md) B-46..B-48). Construction forwards every `Sandbox.new` keyword verbatim; the optional block is the per-Sandbox setup window and runs exactly once per constructed Sandbox.
+
+`Kobako::Pool` is experimental today and is best treated as a convenience for warm, pre-configured reuse rather than a throughput optimisation. B-49 bakes the shared boot state into the artifact and every dynamic script still compiles and runs per invocation, so all a pool actually saves is the ~30 µs host-side `Sandbox.new`. For the workload kobako is built for — many small, short-lived Sandboxes running dynamic scripts — that is not a significant gain (~4-5% in the [serverless example](examples/serverless/README.md), and proportionally less once the script itself does real work).
 
 ```ruby
 pool = Kobako::Pool.new(slots: 4) do |sandbox|
@@ -221,7 +223,7 @@ Sandboxes construct lazily on first demand. `#with` yields a Sandbox with empty
 
 ### Service Blocks
 
-A Service method can accept a guest-supplied block via `&blk` and `yield` into it. The block body runs inside the Wasm guest; `break` / `next` / exceptions follow normal Ruby semantics, scoped to the single dispatch. See [`docs/behavior.md`](docs/behavior.md) B-23..B-30.
+A Service method can accept a guest-supplied block via `&blk` and `yield` into it. The block body runs inside the Wasm guest; `break` / `next` / exceptions follow normal Ruby semantics, scoped to the single dispatch. See [`docs/behavior/yield.md`](docs/behavior/yield.md) B-23..B-30.
 
 ```ruby
 sandbox.define(:Seq).bind(:Map, ->(items, &blk) { items.map(&blk) })
@@ -232,7 +234,7 @@ sandbox.eval('Seq::Map.call([1, 2, 3]) { |x| x * 2 }')
 
 ### Handle Management
 
-A non-wire-representable host object — returned from a Service (B-14), passed to `#run` (B-34), or handed back from the guest (B-37) — crosses the boundary as an opaque `Kobako::Handle` proxy and is restored to the original object before host code sees it; any other unrepresentable value raises `Kobako::SandboxError`. Handles are scoped to a single invocation ([`docs/behavior.md`](docs/behavior.md) B-13..B-21, B-34, B-37).
+A non-wire-representable host object — returned from a Service (B-14), passed to `#run` (B-34), or handed back from the guest (B-37) — crosses the boundary as an opaque `Kobako::Handle` proxy and is restored to the original object before host code sees it; any other unrepresentable value raises `Kobako::SandboxError`. Handles are scoped to a single invocation ([`docs/behavior/dispatch.md`](docs/behavior/dispatch.md) B-13..B-21, B-34, B-37).
 
 ```ruby
 class Greeter
@@ -268,7 +270,7 @@ This is deliberate, not a leak. Handle IDs run to 2³¹ − 1 per invocation and
 
 ### Snippets & Entrypoints
 
-`Sandbox#preload` registers named mruby snippets that replay into every invocation's canonical boot state; `Sandbox#run(:Target, *args, **kwargs)` dispatches into a top-level `Object` constant defined by those snippets ([`docs/behavior.md`](docs/behavior.md) B-31..B-33).
+`Sandbox#preload` registers named mruby snippets that replay into every invocation's canonical boot state; `Sandbox#run(:Target, *args, **kwargs)` dispatches into a top-level `Object` constant defined by those snippets ([`docs/behavior/invocation.md`](docs/behavior/invocation.md) B-31..B-33).
 
 ```ruby
 sandbox = Kobako::Sandbox.new
@@ -320,6 +322,11 @@ sandbox.define(:Cfg).bind(:Settings, ThemeReader.new)  # not: bind(:Settings, Ap
 sandbox.eval('Cfg::Settings.color')  # => "#3366ff"  — every other method raises NoMethodError
 ```
 
+When a purpose-built wrapper is more than you need, an object can gate its own surface in
+place: a private `respond_to_guest?(name)` answers, per method, whether the guest may call
+it. Returning `false` for every name makes the object opaque — a credential the guest
+forwards to another Service but never reads — while a named subset becomes an allow-list.
+
 Guest code can name any `<Namespace>::<Member>` path, but a forged name only resolves to
 something you bound — the real authorization gate is this host-side allowlist. Give each
 trust context its own Sandbox, and see [`docs/security.md`](docs/security.md) for the rest

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,34 +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
       # 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]
@@ -45,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+
@@ -69,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
@@ -89,12 +82,12 @@ module Kobako
 
       private
 
-      # Refuse to mint a Capability Handle for a reflective gadget
-      # ({docs/behavior.md B-43}[link:../../../docs/behavior.md]): 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 (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)
         case object
         when Binding, Method, UnboundMethod
@@ -102,7 +95,7 @@ module Kobako
         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,14 +23,13 @@ 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]
@@ -40,14 +38,12 @@ module Kobako
         @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
 
@@ -74,20 +70,18 @@ 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: B-33 seals Service registration (B-07 /
-      # B-08) 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+ (E-45)
-      # and never alters Frame 1.
+      # 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
         return @encoded if @encoded
 
@@ -97,11 +91,9 @@ module Kobako
       end
 
       # Mark the registry as sealed and propagate the seal to every
-      # declared +Kobako::Namespace+
-      # ({docs/behavior.md B-33}[link:../../../docs/behavior.md]). Called
-      # by +Sandbox+ on the first invocation. After sealing, #define
-      # raises ArgumentError (E-18) and +Namespace#bind+ raises
-      # ArgumentError (E-45). Idempotent.
+      # 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
 

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,18 +14,16 @@ 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
@@ -45,7 +42,7 @@ module Kobako
       # self-encode.
       #
       # The bytes are memoized — the table is replayed verbatim on every
-      # invocation after B-33 seals it, so Frame 3 never changes between
+      # invocation after sealing, so Frame 3 never changes between
       # encodes; {#register} drops the memo while the table is still open.
       def encode
         return @encoded if @encoded
@@ -53,8 +50,7 @@ module Kobako
         @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
@@ -65,15 +61,13 @@ 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
@@ -89,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/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]