kobako 0.12.2 → 0.14.0

data/ext/kobako/src/runtime.rs

@@ -5,7 +5,7 @@
 //!   Kobako::Runtime — wraps a `kobako_wasmtime::Driver` + the Ruby seams
 //!
 //! constructed via `Kobako::Runtime.from_path(path, timeout, memory_limit,
-//! stdout_limit, stderr_limit)`. Every invocation (`#eval` / `#run`)
+//! stdout_limit, stderr_limit, profile)`. Every invocation (`#eval` / `#run`)
 //! instantiates a fresh instance and discards the whole Store afterwards —
 //! the per-invocation instance discipline. The run mechanics —
 //! engine/module caches, caps, trap classification — live in the
@@ -21,24 +21,25 @@
 //!
 //! This file owns the `Kobako::Runtime` magnus class itself — the Ruby
 //! init() that registers the class, the byte↔`RString` shuttling, the
-//! dispatch-Proc GC root, and the per-invocation usage readout.
+//! dispatch-Proc GC root, and the per-invocation usage / capture readouts.
 
 mod bridge;
 mod errors;
 
-use magnus::{function, method, prelude::*, Error as MagnusError, RModule, RString, Ruby};
+use magnus::{
+    function, gc, method, prelude::*, typed_data::DataTypeFunctions, value::Opaque,
+    Error as MagnusError, RArray, RModule, RString, Ruby, Symbol, TypedData, Value,
+};
 
-use std::cell::Cell;
+use std::cell::{Cell, RefCell};
 use std::path::Path;
 use std::sync::Arc;
 use std::time::Duration;
 
-use magnus::{gc, typed_data::DataTypeFunctions, value::Opaque, RArray, TypedData, Value};
-
-use crate::snapshot::Snapshot;
 use kobako_runtime::dispatch::DispatchHandler;
+use kobako_runtime::profile::Profile;
 use kobako_runtime::runtime::{Entry, Frames, Runtime as ContractRuntime};
-use kobako_runtime::snapshot::{Completion, Snapshot as RuntimeSnapshot, Usage};
+use kobako_runtime::snapshot::{Capture, Completion, Snapshot as RuntimeSnapshot, Usage};
 use kobako_wasmtime::{Config, Driver};
 
 /// Copy the bytes of `s` into a fresh `Vec<u8>`. Single safe entry to
@@ -52,6 +53,15 @@ fn rstring_to_vec(s: RString) -> Vec<u8> {
     unsafe { s.as_slice() }.to_vec()
 }
 
+/// The pre-invocation sentinel for one capture channel: no bytes, cap
+/// not reached. Fresh `Vec`s per call because `Capture` owns its buffer.
+fn empty_capture() -> Capture {
+    Capture {
+        bytes: Vec::new(),
+        truncated: false,
+    }
+}
+
 // ---------------------------------------------------------------------------
 // Ruby init
 // ---------------------------------------------------------------------------
@@ -65,11 +75,13 @@ pub fn init(ruby: &Ruby, kobako: RModule) -> Result<(), MagnusError> {
     // intermediate hierarchy is registered.
 
     let runtime = kobako.define_class("Runtime", ruby.class_object())?;
-    runtime.define_singleton_method("from_path", function!(Runtime::from_path, 5))?;
+    runtime.define_singleton_method("from_path", function!(Runtime::from_path, 6))?;
     runtime.define_method("on_dispatch=", method!(Runtime::set_on_dispatch, 1))?;
     runtime.define_method("eval", method!(Runtime::eval, 3))?;
     runtime.define_method("run", method!(Runtime::run, 3))?;
     runtime.define_method("usage", method!(Runtime::usage, 0))?;
+    runtime.define_method("captures", method!(Runtime::captures, 0))?;
+    runtime.define_method("profile", method!(Runtime::profile, 0))?;
     // The guest re-enters for a block yield through a frame-scoped
     // `Kobako::Runtime::GuestYielder` the dispatcher hands the Proc, not a
     // method on Runtime.
@@ -93,11 +105,17 @@ struct Runtime {
     // reference the one Proc this `Opaque` pins. `Cell` is sound under the
     // GVL (see the `unsafe impl Sync` below).
     on_dispatch: Cell<Option<Opaque<Value>>>,
-    // Usage of the most recent invocation, kept apart from the returned
-    // `Snapshot` so `#usage` reads survive the per-invocation Store
-    // teardown and the trap path's raise. Zeroed before the first
-    // invocation.
+    // Usage of the most recent invocation, stashed here so `#usage` reads
+    // survive the per-invocation Store teardown and the trap path's
+    // raise. Zeroed before the first invocation.
     last_usage: Cell<Usage>,
+    // Output captures of the most recent invocation, stashed for the same
+    // reason as `last_usage`: the trap path raises, and this readout is
+    // what keeps the guest's partial output readable after a rescue.
+    // `RefCell` (not `Cell`) because `Capture` owns its byte buffer; the
+    // same GVL single-thread discipline applies (see the `unsafe impl
+    // Sync` below). Empty before the first invocation.
+    last_captures: RefCell<(Capture, Capture)>,
 }
 
 impl DataTypeFunctions for Runtime {
@@ -118,11 +136,11 @@ impl DataTypeFunctions for Runtime {
 }
 
 // SAFETY: magnus requires `Send + Sync` on TypedData types. The
-// `on_dispatch` / `last_usage` `Cell`s make the auto-derived `Sync`
-// unavailable, but every access to them happens under the GVL on a single
-// thread at a time — Ruby method calls, and a GC `mark` pass that also
-// holds the GVL. No cross-thread access to either Cell can occur. `Send`
-// stays auto-derived.
+// `on_dispatch` / `last_usage` `Cell`s and the `last_captures` `RefCell`
+// make the auto-derived `Sync` unavailable, but every access to them
+// happens under the GVL on a single thread at a time — Ruby method calls,
+// and a GC `mark` pass that also holds the GVL. No cross-thread access to
+// any of them can occur. `Send` stays auto-derived.
 unsafe impl Sync for Runtime {}
 
 impl Runtime {
@@ -135,15 +153,18 @@ impl Runtime {
     /// (`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 (`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.
+    /// disables); `profile` is the isolation rung the driver builds
+    /// (`:permissive` / `:hermetic`). All five are validated by the
+    /// caller (`Kobako::Sandbox`); this method only refuses non-finite
+    /// or non-positive timeouts and off-ladder profiles as a defence in
+    /// depth.
     fn from_path(
         path: String,
         timeout_seconds: Option<f64>,
         memory_limit: Option<usize>,
         stdout_limit_bytes: Option<usize>,
         stderr_limit_bytes: Option<usize>,
+        profile: Symbol,
     ) -> Result<Self, MagnusError> {
         let ruby = Ruby::get().expect("Ruby thread");
         let timeout = match timeout_seconds {
@@ -161,6 +182,19 @@ impl Runtime {
                 ));
             }
         };
+        // Fail closed on an off-ladder rung: an unrecognized posture must
+        // never fall back to a grant. Same defence-in-depth posture as the
+        // timeout guard above — `SandboxOptions` is the primary validator.
+        let profile = match profile.name()?.as_ref() {
+            "hermetic" => Profile::Hermetic,
+            "permissive" => Profile::Permissive,
+            other => {
+                return Err(MagnusError::new(
+                    ruby.exception_arg_error(),
+                    format!("profile must be :permissive or :hermetic, got :{other}"),
+                ));
+            }
+        };
 
         let driver = Driver::new(
             Path::new(&path),
@@ -169,6 +203,7 @@ impl Runtime {
                 timeout,
                 stdout_limit_bytes,
                 stderr_limit_bytes,
+                profile,
             },
         )
         .map_err(|e| errors::setup_to_magnus(&ruby, e))?;
@@ -179,6 +214,7 @@ impl Runtime {
                 wall_time: 0.0,
                 memory_peak: 0,
             }),
+            last_captures: RefCell::new((empty_capture(), empty_capture())),
         })
     }
 
@@ -204,7 +240,7 @@ impl Runtime {
     /// One-shot mruby source execution (`#eval`). The Ruby-facing entry:
     /// builds the dispatch handler from the registered Proc, hands the
     /// three stdin frames (`preamble`, `source`, `snippets`) and the source
-    /// to the driver, and settles the returned `Snapshot` through
+    /// to the driver, and settles the invocation through
     /// `finish_invocation` — or maps a could-not-start `Error` onto its
     /// `Kobako::*` exception. The run mechanics — frames, caps, trap
     /// classification — live in `kobako_wasmtime::Driver`.
@@ -213,7 +249,7 @@ impl Runtime {
         preamble: RString,
         source: RString,
         snippets: RString,
-    ) -> Result<Snapshot, MagnusError> {
+    ) -> Result<RString, MagnusError> {
         let ruby = Ruby::get().expect("Ruby thread");
         let handler = self.build_handler();
         let preamble = rstring_to_vec(preamble);
@@ -233,8 +269,8 @@ impl Runtime {
         self.finish_invocation(&ruby, snapshot)
     }
 
-    /// Execute one entrypoint dispatch (`__kobako_run`) and return a
-    /// `Snapshot` bundling every per-invocation observable.
+    /// Execute one entrypoint dispatch (`__kobako_run`) and return the
+    /// guest's raw outcome bytes.
     ///
     /// The two-frame stdin protocol (preamble + snippets; no user source
     /// frame — docs/wire-codec.md § Invocation channels) plus the
@@ -246,7 +282,7 @@ impl Runtime {
         preamble: RString,
         snippets: RString,
         envelope: RString,
-    ) -> Result<Snapshot, MagnusError> {
+    ) -> Result<RString, MagnusError> {
         let ruby = Ruby::get().expect("Ruby thread");
         let handler = self.build_handler();
         let preamble = rstring_to_vec(preamble);
@@ -268,20 +304,27 @@ impl Runtime {
         self.finish_invocation(&ruby, snapshot)
     }
 
-    /// Settle one invocation's `Snapshot` at the Ruby boundary: usage is
-    /// recorded even when the completion is a trap and this call raises,
-    /// while trap-path captures are deliberately dropped — exposing them
-    /// is a SPEC decision the Ruby surface has not taken.
+    /// Settle one invocation's `Snapshot` at the Ruby boundary: usage and
+    /// the two output captures are recorded on every outcome, so the
+    /// `#usage` / `#captures` readouts survive the trap path's raise —
+    /// that is what keeps the guest's partial output readable after the
+    /// Host App rescues the trap. A completed guest invocation returns
+    /// its raw outcome bytes; the Sandbox layer decodes them.
     fn finish_invocation(
         &self,
         ruby: &Ruby,
         snapshot: RuntimeSnapshot,
-    ) -> Result<Snapshot, MagnusError> {
-        self.last_usage.set(snapshot.usage);
-        match snapshot.completion {
-            Completion::Outcome(bytes) => {
-                Ok(Snapshot::new(bytes, snapshot.stdout, snapshot.stderr))
-            }
+    ) -> Result<RString, MagnusError> {
+        let RuntimeSnapshot {
+            completion,
+            stdout,
+            stderr,
+            usage,
+        } = snapshot;
+        self.last_usage.set(usage);
+        self.last_captures.replace((stdout, stderr));
+        match completion {
+            Completion::Outcome(bytes) => Ok(ruby.str_from_slice(&bytes)),
             Completion::Trap(trap) => Err(errors::trap_to_magnus(ruby, trap)),
         }
     }
@@ -313,8 +356,8 @@ impl Runtime {
     ///     size captured at invocation entry. `0` before the first
     ///     invocation.
     ///
-    /// Reads the `last_usage` Cell `finish_invocation` populated from the
-    /// returned `Snapshot` before the per-invocation Store was discarded.
+    /// Reads the `last_usage` Cell `finish_invocation` populated before
+    /// the per-invocation Store was discarded.
     fn usage(&self) -> Result<RArray, MagnusError> {
         let ruby = Ruby::get().expect("Ruby thread");
         let usage = self.last_usage.get();
@@ -323,4 +366,37 @@ impl Runtime {
         arr.push(usage.memory_peak)?;
         Ok(arr)
     }
+
+    /// Return the per-last-invocation output captures as a Ruby 4-tuple
+    /// `[stdout_bytes, stdout_truncated, stderr_bytes, stderr_truncated]`
+    /// — the flat positional layout mirrors `#usage`, and the element
+    /// order matches the destructure in `Kobako::Sandbox#read_captures!`;
+    /// reorder both sides together.
+    ///
+    /// Reads the `last_captures` pair `finish_invocation` stashed on
+    /// every outcome, so the readout also covers the trap path, where
+    /// `#eval` / `#run` raise instead of returning outcome bytes.
+    /// Empty bytes and `false` flags before the first invocation.
+    fn captures(&self) -> Result<RArray, MagnusError> {
+        let ruby = Ruby::get().expect("Ruby thread");
+        let captures = self.last_captures.borrow();
+        let (stdout, stderr) = &*captures;
+        let arr = ruby.ary_new_capa(4);
+        arr.push(ruby.str_from_slice(&stdout.bytes))?;
+        arr.push(stdout.truncated)?;
+        arr.push(ruby.str_from_slice(&stderr.bytes))?;
+        arr.push(stderr.truncated)?;
+        Ok(arr)
+    }
+
+    /// Return the isolation profile the driver built, as a Symbol
+    /// (`:hermetic` / `:permissive`) — the declaration the Sandbox
+    /// compares against the posture its `profile:` option requested.
+    fn profile(&self) -> Symbol {
+        let ruby = Ruby::get().expect("Ruby thread");
+        match self.driver.profile() {
+            Profile::Hermetic => ruby.to_symbol("hermetic"),
+            Profile::Permissive => ruby.to_symbol("permissive"),
+        }
+    }
 }

data/lib/kobako/catalog/handles.rb

@@ -95,7 +95,7 @@ module Kobako
         end
       end
 
-      # Guard {#alloc} against issuing an ID past the cap. Returns +nil+
+      # Guard #alloc against issuing an ID past the cap. Returns +nil+
       # on success; raises +Kobako::HandleExhaustedError+ at exhaustion.
       def ensure_capacity!
         cap = Kobako::Handle::MAX_ID
@@ -107,7 +107,7 @@ module Kobako
       end
 
       # Single source of truth for the "unknown Handle id" raise used by
-      # {#fetch}. Returns +nil+ on success; raises +Kobako::SandboxError+
+      # #fetch. Returns +nil+ on success; raises +Kobako::SandboxError+
       # when +id+ is not currently bound.
       def require_bound!(id)
         return if @entries.key?(id)

data/lib/kobako/catalog/namespaces.rb

@@ -71,7 +71,7 @@ module Kobako
       end
 
       # Encode the preamble as msgpack bytes for stdin Frame 1 delivery.
-      # Routes through {Kobako::Codec::Encoder} like every other host-side
+      # 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"]], ...]+.
@@ -106,7 +106,7 @@ module Kobako
         self
       end
 
-      # Returns +true+ when {#seal!} has been called, +false+ otherwise.
+      # Returns +true+ when #seal! has been called, +false+ otherwise.
       def sealed?
         @sealed
       end

data/lib/kobako/catalog/snippets.rb

@@ -43,7 +43,7 @@ module Kobako
       #
       # 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.
+      # encodes; #register drops the memo while the table is still open.
       # Unlike +Catalog::Namespaces#encode+, which gates its memo on the
       # seal, this one can fill eagerly and invalidate in +#register+
       # because every mutation funnels through that single method — there is

data/lib/kobako/codec/decoder.rb

@@ -12,23 +12,23 @@ module Kobako
     # ({docs/wire-codec.md}[link:../../../docs/wire-codec.md] § Type Mapping).
     #
     # Translates msgpack gem exceptions into the kobako error taxonomy
-    # ({Truncated}, {InvalidType}, {InvalidEncoding}, {UnsupportedType}) so
+    # (Truncated, InvalidType, InvalidEncoding, UnsupportedType) so
     # callers can pattern-match on the SPEC's wire-violation categories
     # without leaking the gem's internal exception classes.
     #
-    # Public API is a single function — {.decode}. The decoder is
+    # Public API is a single function — +.decode+. The decoder is
     # stateless; the +MessagePack::Unpacker+ instance is built per call
     # because callers always decode exactly one wire value at a time.
     module Decoder
       # Decode +bytes+ into one Ruby value and validate transitively
-      # against the SPEC type mapping. Raises {Truncated}, {InvalidType},
-      # or {InvalidEncoding} on wire violations.
+      # against the SPEC type mapping. Raises Truncated, InvalidType,
+      # or InvalidEncoding on wire violations.
       #
       # When a block is given, the decoded value is yielded and the block's
       # result is returned — wire Value Objects use this to build themselves
       # from the decoded payload. The block runs inside this method's
       # rescue, so a Value Object's +ArgumentError+ invariant failure
-      # surfaces as {InvalidType} without a separate {Utils.with_boundary}
+      # surfaces as InvalidType without a separate Utils.with_boundary
       # wrapper at the call site.
       def self.decode(bytes)
         value = Factory.load(bytes.b)
@@ -37,7 +37,7 @@ module Kobako
       # msgpack gem raises the format/type errors below; +ArgumentError+
       # comes from our ext-type validators (Handle id range, Exception type
       # whitelist) and from a yielded block's Value Object invariants — both
-      # are wire violations, so both map to {InvalidType}.
+      # are wire violations, so both map to InvalidType.
       rescue ::MessagePack::UnknownExtTypeError, ::MessagePack::MalformedFormatError,
              ::MessagePack::StackError, ::ArgumentError => e
         raise InvalidType, e.message
@@ -53,7 +53,7 @@ module Kobako
       # Encoding Rules). The msgpack gem returns UTF-8-tagged Strings for
       # str family but does not validate the bytes; +bin+ family decodes
       # to ASCII-8BIT. Walk the tree once and reject invalid UTF-8 in any
-      # str-typed leaf via {Utils.assert_utf8!}. {Kobako::Fault}
+      # str-typed leaf via Utils.assert_utf8!. Kobako::Fault
       # payloads are validated transitively: +Factory.unpack_fault+
       # feeds the inner ext-0x02 bytes back through this Decoder, so their
       # +str+ fields are already covered by the time control returns here.

data/lib/kobako/codec/encoder.rb

@@ -14,9 +14,9 @@ module Kobako
     # strings, arrays, and maps go through the gem's narrowest-encoding
     # logic; the three kobako-specific ext types (0x00 Symbol, 0x01
     # Capability Handle, 0x02 Exception envelope) are registered on
-    # the cached {Kobako::Codec::Factory} singleton.
+    # the cached Kobako::Codec::Factory singleton.
     #
-    # Public API is a single function — {.encode}. The codec is stateless;
+    # Public API is a single function — +.encode+. The codec is stateless;
     # there is no buffer accumulator and no streaming write API. Callers
     # that need to concatenate multiple encodings build the bytes
     # themselves.

data/lib/kobako/codec/error.rb

@@ -7,11 +7,11 @@ module Kobako
     # The wire codec implements the binary contract pinned in
     # {docs/wire-codec.md}[link:../../../docs/wire-codec.md] § Type Mapping.
     # Every wire violation surfaces as a
-    # subclass of {Error} so callers can pattern-match on the specific
+    # subclass of Error so callers can pattern-match on the specific
     # fault while still rescuing all codec faults via this base class.
     #
     # Higher layers (e.g. the Sandbox dispatch loop) translate these into
-    # the public {Kobako::SandboxError} / {Kobako::TrapError} taxonomy.
+    # the public Kobako::SandboxError / Kobako::TrapError taxonomy.
     class Error < StandardError; end
 
     # Input ended before the type prefix or payload was fully consumed.
@@ -21,7 +21,7 @@ module Kobako
     # type mapping (e.g. an unknown ext code, or a reserved msgpack tag).
     class InvalidType < Error; end
 
-    # A msgpack `str` payload was not valid UTF-8, or an ext 0x00 Symbol
+    # A msgpack +str+ payload was not valid UTF-8, or an ext 0x00 Symbol
     # payload was not valid UTF-8 — both are wire violations per SPEC.
     class InvalidEncoding < Error; end
 

data/lib/kobako/codec/factory.rb

@@ -16,7 +16,7 @@ module Kobako
     # § Ext Types).
     #
     # The factory is the single place in the host gem that touches the
-    # msgpack API — both {Encoder} and {Decoder} delegate through it, so
+    # msgpack API — both Encoder and Decoder delegate through it, so
     # the three kobako ext codes (0x00 Symbol, 0x01 Capability Handle,
     # 0x02 Exception envelope) are configured exactly once at first use.
     #
@@ -93,11 +93,11 @@ module Kobako
       end
 
       # Validate the ext-0x00 payload as UTF-8 and intern. Raises
-      # {InvalidEncoding} on invalid bytes — SPEC forbids the
+      # InvalidEncoding on invalid bytes — SPEC forbids the
       # binary-encoding fallback that msgpack-gem's default unpacker
       # would otherwise apply. The re-tag step lives here because the
       # msgpack ext-type unpacker hands us binary bytes; the assertion
-      # itself is shared with {Decoder} via {Utils.assert_utf8!}. The
+      # itself is shared with Decoder via Utils.assert_utf8!. The
       # +"Symbol"+ label keeps the error message in Ruby vocabulary
       # rather than wire-ext-code vocabulary.
       def unpack_symbol(payload)
@@ -125,7 +125,7 @@ module Kobako
       # Peel off the fixext-4 frame, hand the bytes to the
       # Host-Gem-internal +Kobako::Handle.restore+ factory, and
       # translate the +ArgumentError+ raised by Handle's invariants
-      # into a wire-layer +InvalidType+ via {Codec::Utils.with_boundary}.
+      # into a wire-layer +InvalidType+ via Codec::Utils.with_boundary.
       # The Value Object owns the id-range contract; this method only
       # owns the frame shape.
       def unpack_handle(payload)
@@ -136,11 +136,11 @@ module Kobako
         Codec::Utils.with_boundary { Kobako::Handle.restore(id) }
       end
 
-      # Encode the inner ext-0x02 map via {Encoder} (not +factory.dump+) so
+      # Encode the inner ext-0x02 map via Encoder (not +factory.dump+) so
       # the embedded payload flows through the same boundary as a top-level
       # encode — nested kobako values (Handle, nested Fault) reach the
       # registered ext-type packers via the cached singleton. A +details+
-      # chain nested past {MAX_EXT_DEPTH} has no wire representation and
+      # chain nested past MAX_EXT_DEPTH has no wire representation and
       # surfaces as +UnsupportedType+.
       def pack_fault(fault)
         within_ext_frame(UnsupportedType) do
@@ -149,12 +149,12 @@ module Kobako
       end
 
       # Peel the embedded msgpack map and hand it to +Kobako::Fault.new+
-      # inside {Decoder.decode}'s block form, so the value-object's
+      # inside Decoder.decode's block form, so the value-object's
       # +ArgumentError+ invariants surface as +InvalidType+ through the
-      # decoder boundary. Inner decode goes through {Decoder} (not
+      # decoder boundary. Inner decode goes through Decoder (not
       # +factory.load+) so the embedded +str+ payloads flow through the
       # same UTF-8 validation as a top-level decode. A nested ext 0x02 in
-      # +details+ re-enters this method, so {#within_ext_frame} bounds the
+      # +details+ re-enters this method, so #within_ext_frame bounds the
       # chain depth to keep it from exhausting the native stack.
       def unpack_fault(payload)
         within_ext_frame(InvalidType) do
@@ -167,7 +167,7 @@ module Kobako
       end
 
       # Track ext-envelope re-entry depth and refuse a chain past
-      # {MAX_EXT_DEPTH}, raising +over_limit+ so the failure lands in the
+      # MAX_EXT_DEPTH, raising +over_limit+ so the failure lands in the
       # caller's existing wire-error class. The counter is thread-scoped and
       # balanced by the +ensure+, so a raise mid-chain still unwinds it to
       # its entry value.

data/lib/kobako/codec/handle_walk.rb

@@ -5,16 +5,16 @@ require_relative "../handle"
 module Kobako
   module Codec
     # Substitutes Capability Handles into and out of a Ruby value tree at
-    # the host↔guest boundary. {deep_wrap} allocates a +Kobako::Handle+ for
+    # the host↔guest boundary. #deep_wrap allocates a +Kobako::Handle+ for
     # each non-wire-representable leaf on the host→guest +#run+ argument
-    # path; {deep_restore} resolves each wire-decoded Handle back to its
-    # host object on every guest→host value path. {representable?} is the
-    # by-value codec-type predicate that decides which leaves {deep_wrap}
+    # path; #deep_restore resolves each wire-decoded Handle back to its
+    # host object on every guest→host value path. #representable? is the
+    # by-value codec-type predicate that decides which leaves #deep_wrap
     # must wrap: the closed 12-entry wire type set
     # ({docs/wire-codec.md}[link:../../../docs/wire-codec.md] § Type
     # Mapping).
     #
-    # All helpers are pure except {deep_wrap}, whose only side effect is
+    # All helpers are pure except #deep_wrap, whose only side effect is
     # allocating new Handle ids into the supplied table.
     module HandleWalk
       module_function
@@ -24,7 +24,7 @@ module Kobako
       # unsigned +uint 64+ maximum
       # ({docs/wire-codec.md}[link:../../../docs/wire-codec.md] § Type
       # Mapping #3, the +fixint+ / +int 8..64+ / +uint 8..64+ union).
-      # Anchored as a +Range+ so {primitive_type?} stays a single
+      # Anchored as a +Range+ so #primitive_type? stays a single
       # dispatch line. This is the codec's encode domain — not to
       # be confused with the Handle id range, which lives on
       # +Kobako::Handle+ as +MIN_ID+ / +MAX_ID+ (1..2^31 − 1) and
@@ -41,13 +41,13 @@ module Kobako
       # representable. Integers outside the codec's signed-64 /
       # unsigned-64 union are rejected so the predicate agrees with the
       # msgpack gem's encode-time +RangeError+ behaviour the codec
-      # already surfaces as {UnsupportedType}.
+      # already surfaces as UnsupportedType.
       def representable?(value)
         primitive_type?(value) || container_representable?(value)
       end
 
       # Deep-walk Array / Hash containers in +value+ and replace every
-      # leaf that fails {representable?} with a +Kobako::Handle+
+      # leaf that fails #representable? with a +Kobako::Handle+
       # allocated from +handler+. The
       # walk only descends through representable container shapes
       # (Array, Hash) one structural level at a time; a non-representable
@@ -61,13 +61,9 @@ module Kobako
       # whose leaves are either representable or +Kobako::Handle+
       # tokens.
       #
-      # The block bodies spell +HandleWalk.deep_wrap+ explicitly rather
-      # than the unqualified +deep_wrap+ because +module_function+ makes
-      # the instance copy of these helpers private; an implicit receiver
-      # inside a block would resolve against the enclosing +self+
-      # (still +HandleWalk+ at definition time, but the qualified form
-      # keeps the dispatch readable when the recursive call sits inside a
-      # Proc captured from elsewhere).
+      # Recursive calls spell the +HandleWalk.+ receiver so the dispatch
+      # stays valid even when a block is captured and run under a
+      # different +self+ (+module_function+ privatizes the instance copies).
       def deep_wrap(value, handler)
         case value
         when ::Array then value.map { |element| HandleWalk.deep_wrap(element, handler) }
@@ -79,7 +75,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. 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 wherever a guest→host payload carries
       # one — an invocation result, a yield-block result, or a dispatch
@@ -107,9 +103,9 @@ module Kobako
         end
       end
 
-      # The non-container branch of {representable?}: returns +true+ for
+      # The non-container branch of #representable?: returns +true+ for
       # the scalar leaves and an existing Handle. Not part of the
-      # public surface; reach for {representable?} instead.
+      # public surface; reach for #representable? instead.
       def primitive_type?(value)
         case value
         when ::NilClass, ::TrueClass, ::FalseClass, ::Float, ::String, ::Symbol, Kobako::Handle then true
@@ -118,10 +114,10 @@ module Kobako
         end
       end
 
-      # The container branch of {representable?}: recurses into Array
+      # The container branch of #representable?: recurses into Array
       # elements and Hash key+value pairs through the public
-      # {representable?}. Not part of the public surface; reach for
-      # {representable?} instead.
+      # #representable?. Not part of the public surface; reach for
+      # #representable? instead.
       def container_representable?(value)
         case value
         when ::Array then value.all? { |element| HandleWalk.representable?(element) }

data/lib/kobako/codec/utils.rb

@@ -10,18 +10,18 @@ module Kobako
     #   - UTF-8 assertion at the codec boundary
     #     ({docs/wire-codec.md}[link:../../../docs/wire-codec.md]
     #     § str/bin Encoding Rules and § Ext Types → ext 0x00). Used by
-    #     {Decoder} when walking +str+ family payloads and by {Factory}
+    #     Decoder when walking +str+ family payloads and by Factory
     #     when validating the +ext 0x00+ Symbol payload.
     #   - +ArgumentError+ translation at the codec boundary
-    #     ({with_boundary}) so the public taxonomy stays
-    #     {Kobako::Codec::Error}.
+    #     (#with_boundary) so the public taxonomy stays
+    #     Kobako::Codec::Error.
     #
     # Both helpers are pure — they only inspect inputs, never mutate them.
-    # The host↔guest Handle substitution walk lives in {HandleWalk}.
+    # The host↔guest Handle substitution walk lives in HandleWalk.
     module Utils
       module_function
 
-      # Raise {InvalidEncoding} unless +string+'s bytes are valid under
+      # Raise InvalidEncoding unless +string+'s bytes are valid under
       # its current encoding tag. +label+ is the caller-supplied prefix
       # for the error message (e.g. +"str payload"+, +"Symbol payload"+).
       def assert_utf8!(string, label)
@@ -32,13 +32,13 @@ module Kobako
 
       # Run +block+ at the codec boundary: a value object raises
       # +ArgumentError+ when an invariant is violated at construction, and
-      # this helper surfaces that as {InvalidType} so the public taxonomy
-      # stays {Kobako::Codec::Error} and never leaks +ArgumentError+ from
+      # this helper surfaces that as InvalidType so the public taxonomy
+      # stays Kobako::Codec::Error and never leaks +ArgumentError+ from
       # the Ruby standard library.
       #
       # Reach for this only where a value object is constructed outside a
-      # {Decoder.decode} block, whose rescue already performs the same
-      # mapping (worked example: {Factory#unpack_handle} building
+      # Decoder.decode block, whose rescue already performs the same
+      # mapping (worked example: Factory#unpack_handle building
       # +Handle.restore+ from a raw fixext payload). Do not use it for
       # general-purpose validation outside the codec boundary —
       # host-layer +ArgumentError+ values should propagate unchanged.

data/lib/kobako/codec.rb

@@ -18,12 +18,12 @@ module Kobako
   # the kobako root so the codec can register them without depending
   # upward on Transport.
   #
-  # Backed by the official +msgpack+ gem via {Factory}; {Encoder} and
-  # {Decoder} are thin wrappers that register the three kobako-specific
+  # Backed by the official +msgpack+ gem via Factory; Encoder and
+  # Decoder are thin wrappers that register the three kobako-specific
   # ext types (0x00 Symbol, 0x01 Capability Handle, 0x02 Exception
   # envelope) on a single +MessagePack::Factory+ instance. The Rust side
-  # mirrors this layer as the +codec+ module in the +kobako-core+ crate;
-  # the ext-code constants live as module-private values on {Factory}
+  # mirrors this layer as the +codec+ module in the +kobako-codec+ crate;
+  # the ext-code constants live as module-private values on Factory
   # alongside +codec::EXT_SYMBOL+ / +codec::EXT_HANDLE+ /
   # +codec::EXT_ERRENV+ on that side.
   module Codec