kobako 0.10.0 → 0.11.0

data/ext/kobako/src/runtime.rs

@@ -7,8 +7,8 @@
 // constructed via `Kobako::Runtime.from_path(path, timeout, memory_limit,
 // stdout_limit, stderr_limit)`. Every invocation (`#eval` / `#run`)
 // instantiates a fresh instance from the InstancePre and discards the
-// whole Store afterwards — the docs/behavior.md B-49 per-invocation
-// instance discipline (ABI v2). The underlying wasmtime Engine and
+// whole Store afterwards — the per-invocation instance discipline
+// (ABI v2). The underlying wasmtime Engine and
 // compiled Module live in a process-scope cache (see the `cache`
 // submodule) and never surface to Ruby (SPEC.md "Code Organization":
 // `ext/` "exposes no Wasm engine types to the Host App or downstream
@@ -74,9 +74,10 @@ use self::invocation::Invocation;
 
 /// The wire ABI version this host implements (docs/wire-codec.md § ABI
 /// Version). A Guest Binary is accepted only when its
-/// `__kobako_abi_version` export reports the same value (B-40 / E-42);
-/// the guest-side mirror is `kobako_core::abi::ABI_VERSION`. Version 2
-/// carries the per-invocation instance discipline (B-49): the host
+/// `__kobako_abi_version` export reports the same value; a mismatch
+/// is a deterministic artifact fault. The guest-side mirror is
+/// `kobako_core::abi::ABI_VERSION`. Version 2
+/// carries the per-invocation instance discipline: the host
 /// drives every invocation on a fresh instance, so the guest may leave
 /// its VM state dirty at exit.
 const ABI_VERSION: u32 = 2;
@@ -149,22 +150,22 @@ pub(crate) fn trap_err(ruby: &Ruby, msg: impl Into<String>) -> MagnusError {
 /// Construct a `Kobako::SetupError` magnus error. Used for every
 /// construction-time failure on the `Runtime.from_path` path before any
 /// invocation runs — unreadable artifact, bytes that are not a valid Wasm
-/// module, or engine / linker / instantiation setup failure (docs/behavior.md
-/// E-41). The `ModuleNotBuiltError` subclass (artifact absent, E-40) is
+/// module, or engine / linker / instantiation setup failure. The
+/// `ModuleNotBuiltError` subclass (artifact absent) is
 /// raised through `MODULE_NOT_BUILT_ERROR` directly.
 pub(crate) fn setup_err(ruby: &Ruby, msg: impl Into<String>) -> MagnusError {
     error_in(ruby, &SETUP_ERROR, msg)
 }
 
 /// Construct a `Kobako::TimeoutError` magnus error. Surfaces the
-/// docs/behavior.md E-19 wall-clock cap path with the verb prefix added
+/// wall-clock cap path with the verb prefix added
 /// by `Kobako::Sandbox#invoke!`.
 pub(crate) fn timeout_err(ruby: &Ruby, msg: impl Into<String>) -> MagnusError {
     error_in(ruby, &TIMEOUT_ERROR, msg)
 }
 
 /// Construct a `Kobako::MemoryLimitError` magnus error. Surfaces the
-/// docs/behavior.md E-20 linear-memory cap path with the verb prefix
+/// linear-memory cap path with the verb prefix
 /// added by `Kobako::Sandbox#invoke!`.
 pub(crate) fn memory_limit_err(ruby: &Ruby, msg: impl Into<String>) -> MagnusError {
     error_in(ruby, &MEMORY_LIMIT_ERROR, msg)
@@ -173,8 +174,8 @@ pub(crate) fn memory_limit_err(ruby: &Ruby, msg: impl Into<String>) -> MagnusErr
 /// Construct a `Kobako::SandboxError` magnus error. Used for the
 /// host-side pre-call faults the SPEC attributes to the sandbox / wire
 /// layer rather than the Wasm engine — currently the `#run` invocation
-/// envelope reservation failure (`__kobako_alloc` returns 0,
-/// docs/behavior.md E-31). The runtime is intact, so this must not be a
+/// envelope reservation failure (`__kobako_alloc` returns 0).
+/// The runtime is intact, so this must not be a
 /// `TrapError`: no discard-and-recreate recovery is owed to the caller.
 pub(crate) fn sandbox_err(ruby: &Ruby, msg: impl Into<String>) -> MagnusError {
     error_in(ruby, &SANDBOX_ERROR, msg)
@@ -212,10 +213,9 @@ pub(crate) struct Runtime {
     // Pre-linked instantiation template (import wiring + type checks
     // done once in `instance_pre::cached_instance_pre`). Every
     // invocation instantiates a fresh instance from it and discards the
-    // whole Store afterwards — the docs/behavior.md B-49 per-invocation
-    // instance discipline.
+    // whole Store afterwards — the per-invocation instance discipline.
     instance_pre: WtInstancePre<Invocation>,
-    // Per-invocation linear-memory cap (docs/behavior.md B-01 / E-20),
+    // Per-invocation linear-memory cap,
     // threaded into each fresh `Invocation`; lives apart from `Config`
     // because the wasmtime `ResourceLimiter` callback consumes it from
     // inside the wasm engine.
@@ -223,7 +223,7 @@ pub(crate) struct Runtime {
     // Wall-clock + per-channel capture caps forwarded from the Sandbox;
     // see `Config`.
     config: Config,
-    // The host-side dispatch Proc (docs/behavior.md B-12), held here only
+    // The host-side dispatch Proc, held here only
     // to give `DataTypeFunctions::mark` a read path so it can pin the
     // Proc across GC. The copy the `__kobako_dispatch` import actually
     // calls is bound onto each per-invocation `Invocation` by
@@ -231,7 +231,7 @@ pub(crate) struct Runtime {
     // pinned Proc. `Cell` is sound under the GVL (see the `unsafe impl
     // Sync` below).
     on_dispatch: Cell<Option<Opaque<Value>>>,
-    // docs/behavior.md B-35 usage of the most recent invocation —
+    // Usage of the most recent invocation —
     // `(wall_time_seconds, memory_peak_bytes)` — captured by
     // `build_snapshot` before the per-invocation Store is discarded so
     // `#usage` reads survive the teardown. `(0.0, 0)` before the first
@@ -245,7 +245,7 @@ impl DataTypeFunctions for Runtime {
     /// copy on `Invocation` for the duration of a guest invocation.
     /// `gc::Marker::mark` maps to `rb_gc_mark`, which pins: required because
     /// the Invocation copy is a cached `VALUE` that compaction would
-    /// otherwise leave dangling (docs/behavior.md B-12 / B-13). Without
+    /// otherwise leave dangling. Without
     /// this the Proc has no GC root at all — sweep collects it (SIGSEGV on
     /// the next dispatch) and compaction relocates it (dispatch lands on
     /// the wrong receiver).
@@ -270,10 +270,10 @@ impl Runtime {
     /// Ruby-facing constructor for `Kobako::Runtime` — Engine and Module
     /// are never visible to Ruby.
     ///
-    /// `timeout_seconds` is the docs/behavior.md B-01 wall-clock cap in seconds
+    /// `timeout_seconds` is the wall-clock cap in seconds
     /// (`None` disables); `memory_limit` is the linear-memory cap in
     /// bytes (`None` disables); `stdout_limit_bytes` / `stderr_limit_bytes`
-    /// are the per-channel output caps (docs/behavior.md B-01 / B-04; `None`
+    /// are the per-channel output caps (`None`
     /// disables). All four are validated by the caller
     /// (`Kobako::Sandbox`); this method only refuses non-finite or
     /// non-positive timeouts as a defence in depth.
@@ -289,7 +289,7 @@ impl Runtime {
             None => None,
             Some(secs) if secs.is_finite() && secs > 0.0 => Some(Duration::from_secs_f64(secs)),
             Some(secs) => {
-                // docs/behavior.md E-39: an invalid cap argument is a Host App
+                // An invalid cap argument is a Host App
                 // programming error and raises `ArgumentError`, outside the
                 // construction-failure `SetupError` branch. `SandboxOptions`
                 // is the primary guard (it never lets a bad timeout reach
@@ -318,12 +318,12 @@ impl Runtime {
 
     /// Instantiate a throwaway probe instance at construction and require
     /// the guest's `__kobako_abi_version` export to equal `ABI_VERSION`
-    /// (docs/behavior.md B-40). An absent export or a non-equal value is
-    /// E-42 — a deterministic artifact fault raised as
+    /// An absent export or a non-equal value is
+    /// a deterministic artifact fault raised as
     /// `Kobako::SetupError`. The probe Store drops here; invocation
     /// instances are created per `#eval` / `#run`. The frameless WASI
     /// context keeps a third-party guest whose start section touches
-    /// WASI on the E-41 `SetupError` path instead of panicking in
+    /// WASI on the `SetupError` path instead of panicking in
     /// `Invocation::wasi_mut`.
     fn probe_abi_version(&self, ruby: &Ruby) -> Result<(), MagnusError> {
         let mut store = self.new_store()?;
@@ -362,7 +362,7 @@ impl Runtime {
         Ok(())
     }
 
-    /// Register the Ruby-side dispatch `Proc` (docs/behavior.md B-12).
+    /// Register the Ruby-side dispatch `Proc`.
     /// Bound to Ruby as `Kobako::Runtime#on_dispatch=`. The handle is
     /// pinned by `DataTypeFunctions::mark` and copied onto every
     /// per-invocation `Invocation` by `Runtime::new_store`, where the
@@ -374,7 +374,7 @@ impl Runtime {
 
     /// Synchronously re-enter the guest's `__kobako_yield_to_block`
     /// export with `args_bytes` as the yield-arguments payload, and
-    /// return the YieldResponse bytes the guest produced (B-24).
+    /// return the YieldResponse bytes the guest produced.
     ///
     /// Bound to Ruby as `Kobako::Runtime#yield_to_active_invocation`.
     /// Recovers the dispatcher's `&mut Caller` from the per-thread
@@ -382,7 +382,7 @@ impl Runtime {
     /// already inside a `__kobako_dispatch` callback, so the Caller
     /// parked on the Rust stack is the same one the Sandbox-level
     /// `#eval` / `#run` is driving. Invoked from the host-side yield
-    /// proxy that the dispatcher hands to Service methods (B-23 / B-24);
+    /// proxy that the dispatcher hands to Service methods;
     /// raises `Kobako::TrapError` when called outside an active dispatch
     /// frame, or when any of the underlying allocation / write / call /
     /// read steps fails.
@@ -417,10 +417,10 @@ impl Runtime {
     /// Execute one guest invocation (`__kobako_eval` — one-shot source)
     /// and return a `Snapshot` bundling every per-invocation observable.
     ///
-    /// Builds a fresh Store + instance (B-49) whose WASI context carries
+    /// Builds a fresh Store + instance whose WASI context carries
     /// the three-frame stdin protocol (`preamble`, `source`, `snippets`
     /// — docs/wire-codec.md § Invocation channels), then invokes
-    /// `__kobako_eval`. Per-invocation caps (docs/behavior.md B-01) are
+    /// `__kobako_eval`. Per-invocation caps are
     /// primed here: the wall-clock deadline is stamped into `Invocation`
     /// and the epoch deadline is set to fire at the next ticker tick;
     /// the memory-cap limiter is already wired.
@@ -429,7 +429,7 @@ impl Runtime {
     /// `Kobako::TimeoutError` / `Kobako::MemoryLimitError`; everything
     /// else raises `Kobako::TrapError`. On success the Snapshot carries
     /// the OUTCOME_BUFFER bytes, the per-channel stdout / stderr captures
-    /// with their truncation flags, and the B-35 usage figures.
+    /// with their truncation flags, and the usage figures.
     pub(crate) fn eval(
         &self,
         preamble: RString,
@@ -457,14 +457,13 @@ impl Runtime {
     /// Execute one entrypoint dispatch (`__kobako_run`) and return a
     /// `Snapshot` bundling every per-invocation observable.
     ///
-    /// Builds a fresh Store + instance (B-49) whose WASI context carries
+    /// Builds a fresh Store + instance whose WASI context carries
     /// the two-frame stdin protocol (preamble + snippets; no user source
     /// frame — docs/wire-codec.md § Invocation channels), copies
     /// `envelope` bytes into guest linear memory via `__kobako_alloc`,
     /// and calls `__kobako_run(env_ptr, env_len)`. Per-invocation cap
     /// semantics match `Runtime::eval`. Raises `Kobako::TrapError`
-    /// ("alloc returned 0") when guest allocation fails
-    /// (docs/behavior.md E-31).
+    /// ("alloc returned 0") when guest allocation fails.
     pub(crate) fn run(
         &self,
         preamble: RString,
@@ -486,7 +485,7 @@ impl Runtime {
         self.build_snapshot(&ruby, &mut store, &exports)
     }
 
-    /// Return the docs/behavior.md B-35 per-last-invocation usage as a
+    /// Return the per-last-invocation usage as a
     /// Ruby 2-tuple `[wall_time, memory_peak]`. The element order
     /// matches the `Kobako::Usage` field order declared in
     /// `lib/kobako/usage.rb`; reorder both sides together if the field
@@ -520,7 +519,7 @@ impl Runtime {
 
     /// Build the per-invocation Store: a fresh `Invocation` wired with
     /// the memory limiter, the epoch-deadline callback, and the
-    /// registered dispatch Proc (docs/behavior.md B-12).
+    /// registered dispatch Proc.
     fn new_store(&self) -> Result<WtStore<Invocation>, MagnusError> {
         let mut store = WtStore::new(shared_engine()?, Invocation::new(self.memory_limit));
         store.limiter(|state: &mut Invocation| -> &mut dyn ResourceLimiter { state.limiter_mut() });
@@ -532,10 +531,10 @@ impl Runtime {
     }
 
     /// Instantiate the per-invocation instance from the pre-linked
-    /// template (B-49) and resolve its host-driven export handles. An
+    /// template and resolve its host-driven export handles. An
     /// instantiation failure at invocation time is an engine fault —
     /// `Kobako::TrapError` — unlike the construction-time probe, whose
-    /// failure is E-41 `SetupError`.
+    /// failure is `SetupError`.
     fn instantiate(
         &self,
         ruby: &Ruby,
@@ -557,7 +556,7 @@ impl Runtime {
     /// `Runtime::prime_caps` before, `disarm_caps` after — the shared
     /// bracket for both run-path exports (`__kobako_eval` /
     /// `__kobako_run`). Disarm runs whether the call returns or traps, so
-    /// the docs/behavior.md B-35 `wall_time` bracket and the E-20 memory
+    /// the `wall_time` bracket and the memory
     /// cap always close — that close-on-trap guarantee is the reason this
     /// bracket lives in one place rather than inline at each call site.
     /// The wasmtime trap is returned unmapped; each caller wraps it
@@ -576,7 +575,7 @@ impl Runtime {
         self.prime_caps(store, exports);
         let result = export.call(store.as_context_mut(), params);
         disarm_caps(store);
-        // Stash the B-35 usage figures on every outcome — including the
+        // Stash the usage figures on every outcome — including the
         // trap paths, where `build_snapshot` never runs and the Store is
         // about to be discarded with the error.
         let data = store.data();
@@ -592,10 +591,10 @@ impl Runtime {
     /// effectively never fires.
     ///
     /// Also captures the current linear-memory size as the baseline
-    /// for the docs/behavior.md E-20 per-invocation memory delta cap —
+    /// for the per-invocation memory delta cap —
     /// the pre-initialized image's allocation is folded into the
     /// baseline rather than the budget — and stamps the wall-clock
-    /// entry instant for the docs/behavior.md B-35 `wall_time`
+    /// entry instant for the `wall_time`
     /// measurement. The bracket closes in `disarm_caps` so it matches
     /// the `timeout` deadline window and excludes `OUTCOME_BUFFER`
     /// decoding and stdout / stderr capture readout.
@@ -623,7 +622,7 @@ impl Runtime {
     /// Called from the run-path methods after the guest export returns
     /// successfully: drains OUTCOME_BUFFER via `__kobako_take_outcome`
     /// and snapshots the per-channel stdout / stderr pipes (clipped to
-    /// their caps). The B-35 usage figures were already stashed by
+    /// their caps). The usage figures were already stashed by
     /// `call_with_caps`.
     fn build_snapshot(
         &self,
@@ -660,7 +659,7 @@ impl Runtime {
 /// Drop the memory cap as soon as the guest call returns so that
 /// any post-run host bookkeeping (e.g. fetching the OUTCOME_BUFFER,
 /// which can grow guest memory transiently) is not attributed to
-/// the user script. Also closes the docs/behavior.md B-35
+/// the user script. Also closes the
 /// `wall_time` bracket opened by `Runtime::prime_caps`. Paired
 /// with `Runtime::prime_caps`.
 fn disarm_caps(store: &mut WtStore<Invocation>) {
@@ -683,8 +682,8 @@ fn require_memory(ruby: &Ruby, exports: &Exports) -> Result<Memory, MagnusError>
 /// as `i32` values matching the `__kobako_run(env_ptr, env_len)` ABI.
 /// Raises `Kobako::TrapError` when the allocation hook is missing or
 /// itself traps, and `Kobako::SandboxError` when the hook runs but
-/// cannot reserve the buffer (`__kobako_alloc` returns 0,
-/// docs/behavior.md E-31) — an intact runtime, not an engine fault.
+/// cannot reserve the buffer (`__kobako_alloc` returns 0) — an
+/// intact runtime, not an engine fault.
 fn write_envelope(
     ruby: &Ruby,
     store: &mut WtStore<Invocation>,
@@ -723,7 +722,7 @@ fn write_envelope(
 /// instead). Each output pipe is sized at `cap + 1` so
 /// `capture::clip_capture` can distinguish "wrote exactly cap bytes"
 /// from "exceeded cap"; uncapped channels fall back to `usize::MAX` and
-/// rely on `memory_limit` (docs/behavior.md E-20) for the real ceiling.
+/// rely on `memory_limit` for the real ceiling.
 /// Raises `Kobako::TrapError` when any frame exceeds the 16 MiB cap that
 /// keeps its `u32` length prefix from wrapping.
 fn install_wasi_frames(

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,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)