kobako 0.10.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f94d5012ea43dae1d5bd51d2b8f0f6c7357edc259c7771577d3454c7055a5f1d
-  data.tar.gz: 494087c5769aa0ce019ac47d705a1426fb237840ab3c88700afdcc970816b43d
+  metadata.gz: cc8e33cc57bfd43cf4d4e06def6536c8c0d45fd4ccd5bbf04b13a4187db67f0a
+  data.tar.gz: 8656976c144bb23226686b2c8f60830d3fd635f637c52caaa824bd3e168e07f2
 SHA512:
-  metadata.gz: 9cd941922d385068bcb6e78849f5d43dc68e8bc36e2a6a04b245e406c488a2313cffc697441f69c2f76f3ea154924c67e594271009308702aa4f72c514bc0983
-  data.tar.gz: 5a3b07b25b6ea434f69731749c5756d802aa585d2f10cdb3097dafdaf442d1d1da61a1c338cbb0eb3506915d2ba968baf7906607ec97059f1da5ac1070cd6950
+  metadata.gz: 35258fb35a0accee9beea36f01c4fb6cb2c658a2aefcb3ae4ebb7c17decd4e97f1b35e155121ae77456eed6d529d7ec13195ba43a3bf8a3ad43724d11ae5512b
+  data.tar.gz: 06ea66fd5877fc58fc6e5a21805d434e53968004e8c00577264ca547b10ae7aa4f4196798a3fa18da332fd730cc8fe441ac8e37dbfe2527653fed0da598d8bbf

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/Cargo.lock

@@ -878,7 +878,7 @@ dependencies = [
 
 [[package]]
 name = "kobako"
-version = "0.10.0"
+version = "0.11.0"
 dependencies = [
  "libc",
  "magnus",

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/ext/kobako/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "kobako"
-version = "0.10.0"
+version = "0.11.0"
 edition = "2021"
 authors = ["Aotokitsuruya <contact@aotoki.me>"]
 license = "Apache-2.0"
@@ -27,7 +27,7 @@ wasmtime = { version = "45.0.0", default-features = false, features = [
     "wat",
 ] }
 # wasmtime-wasi provides WASI preview1 support for routing guest stdout/stderr
-# into in-memory buffers (docs/behavior.md §B-04). The `p1` feature enables the
+# into in-memory buffers. The `p1` feature enables the
 # WasiCtxBuilder + preview1 adapter which wires fd 1/2 to pipes. We omit
 # `p2` (component-model) and `p0`/`p3` (async) because kobako runs
 # synchronous sandboxes only.

data/ext/kobako/src/runtime/ambient.rs

@@ -11,7 +11,7 @@
 //!
 //! The host wall-clock cap is unaffected: the per-invocation timeout runs on
 //! wasmtime epoch interruption against a host `Instant`, never the guest's
-//! frozen `wasi:clocks/monotonic-clock` (docs/behavior.md B-01).
+//! frozen `wasi:clocks/monotonic-clock`.
 
 use std::time::Duration;
 

data/ext/kobako/src/runtime/cache.rs

@@ -11,7 +11,7 @@
 //!
 //! Across processes, the Cranelift compile cost is amortised by a
 //! best-effort `.cwasm` disk cache keyed by the SHA-256 of the Guest
-//! Binary bytes (docs/behavior.md B-01); every cache failure falls
+//! Binary bytes; every cache failure falls
 //! back to in-process compilation.
 //!
 //! Concurrency: under Ruby's GVL only one thread can execute Rust code
@@ -37,7 +37,7 @@ static SHARED_ENGINE: OnceLock<WtEngine> = OnceLock::new();
 static MODULE_CACHE: OnceLock<Mutex<HashMap<PathBuf, WtModule>>> = OnceLock::new();
 
 /// Ticker cadence for the process-singleton epoch ticker. Bounds the
-/// granularity of the docs/behavior.md B-01 wall-clock timeout: the
+/// granularity of the wall-clock timeout: the
 /// `epoch_deadline_callback` fires once per tick (`Continue(1)`), so the
 /// trap can lag the deadline by at most one tick under nominal
 /// scheduling. 10 ms keeps the lag small enough that it does not skew
@@ -57,7 +57,7 @@ const EPOCH_TICK: Duration = Duration::from_millis(10);
 ///
 /// Also enables `epoch_interruption(true)` so every Store can install an
 /// `epoch_deadline_callback` for the per-run wall-clock cap
-/// (docs/behavior.md B-01, E-19). The first call spawns the process-singleton ticker
+/// cap. The first call spawns the process-singleton ticker
 /// thread that drives `engine.increment_epoch()` at `EPOCH_TICK`
 /// cadence; subsequent calls reuse the same engine and ticker.
 pub(crate) fn shared_engine() -> Result<&'static WtEngine, MagnusError> {

data/ext/kobako/src/runtime/capture.rs

@@ -1,6 +1,6 @@
 //! Per-channel stdout / stderr capture sizing and clipping.
 //!
-//! Two pure helpers shared by the run path (docs/behavior.md B-04): one
+//! Two pure helpers shared by the run path: one
 //! sizes the per-run `MemoryOutputPipe`, the other clips a captured
 //! snapshot back to the configured cap and reports whether the cap was
 //! exceeded. Kept channel-agnostic (a function of `cap`, not of which

data/ext/kobako/src/runtime/config.rs

@@ -13,11 +13,10 @@ use std::time::Duration;
 /// Wall-clock and output caps for one `Runtime`. `None` on any field
 /// disables that cap.
 pub(crate) struct Config {
-    /// Wall-clock cap for one guest `#eval` / `#run` (docs/behavior.md
-    /// B-01, E-19). Stamped into a per-run `Instant` deadline by
-    /// `Runtime::prime_caps`.
+    /// Wall-clock cap for one guest `#eval` / `#run`. Stamped into a
+    /// per-run `Instant` deadline by `Runtime::prime_caps`.
     pub(crate) timeout: Option<Duration>,
-    /// Byte cap for guest stdout capture (docs/behavior.md B-01 / B-04).
+    /// Byte cap for guest stdout capture.
     /// Sizes the per-run `MemoryOutputPipe` and computes the truncation
     /// flag in `Runtime::build_snapshot`.
     pub(crate) stdout_limit_bytes: Option<usize>,

data/ext/kobako/src/runtime/dispatch.rs

@@ -3,7 +3,7 @@
 //! When the guest invokes the wasm import declared in
 //! `wasm/kobako-core/src/abi.rs`, wasmtime calls back into the host
 //! through the closure registered by `instance_pre::build_linker`.
-//! That closure delegates here. The dispatcher (docs/behavior.md B-12 / B-13):
+//! That closure delegates here. The dispatcher:
 //!
 //!   1. Reads the Request bytes from guest linear memory.
 //!   2. Invokes the Ruby-side dispatch Proc bound via
@@ -55,8 +55,8 @@ use wasmtime::Caller;
 use super::invocation::Invocation;
 
 // ============================================================
-// Active-caller pointer for the per-thread Invocation slot (B-24, B-28,
-// SPEC.md Single-Invocation Slot).
+// Active-caller pointer for the per-thread Invocation slot
+// (SPEC.md Single-Invocation Slot).
 // ============================================================
 //
 // `Runtime#yield_to_active_invocation` (whose body is the
@@ -73,8 +73,8 @@ use super::invocation::Invocation;
 // The pointer is therefore erased to `NonNull<()>` and parked in a
 // per-thread slot — the materialised form of the SPEC.md
 // "Single-Invocation Slot" invariant. The single-threaded wasm
-// execution per Sandbox (B-22) plus the LIFO re-entry shape of nested
-// dispatch frames (B-28) ensures no aliasing across threads or across
+// execution per Sandbox plus the LIFO re-entry shape of nested
+// dispatch frames ensures no aliasing across threads or across
 // frames; the recovery invariant lives at `current_caller`. The
 // pointer is set on entry to `handle` and restored to the outer
 // frame's value on every exit through a drop guard.
@@ -85,7 +85,7 @@ thread_local! {
 
 /// RAII guard that saves the previous `ACTIVE_CALLER` value on
 /// installation and restores it on drop. Nested `__kobako_dispatch`
-/// frames stack within one Invocation (B-28) — the inner frame's `set`
+/// frames stack within one Invocation — the inner frame's `set`
 /// swaps in its own pointer while remembering the outer's; drop
 /// restores the outer so its continuation (e.g. iterating over another
 /// guest block) still finds a live caller.

data/ext/kobako/src/runtime/exports.rs

@@ -4,7 +4,7 @@
 //! `Runtime::instantiate` resolves the ABI exports the run path drives
 //! (`__kobako_eval` / `__kobako_run` / `__kobako_take_outcome` /
 //! `__kobako_alloc`) plus the `memory` export against each fresh
-//! per-invocation instance (docs/behavior.md B-49) and bundles their
+//! per-invocation instance and bundles their
 //! typed handles here, so the invocation body passes one struct around
 //! rather than re-resolving exports by name at every step. Distinct
 //! from `super::cache` (the process-wide Engine / Module cache): this

data/ext/kobako/src/runtime/instance_pre.rs

@@ -29,7 +29,7 @@ static INSTANCE_PRE_CACHE: OnceLock<Mutex<HashMap<PathBuf, InstancePre<Invocatio
 /// Look up `path` in the per-path `InstancePre` cache, wiring the
 /// Linker and resolving the Module's imports on a miss. Compilation
 /// faults surface through `cached_module`; import-resolution faults
-/// raise `Kobako::SetupError` (docs/behavior.md E-41).
+/// raise `Kobako::SetupError`.
 pub(crate) fn cached_instance_pre(path: &Path) -> Result<InstancePre<Invocation>, MagnusError> {
     let cache = INSTANCE_PRE_CACHE.get_or_init(|| Mutex::new(HashMap::new()));
 

data/ext/kobako/src/runtime/invocation.rs

@@ -3,15 +3,14 @@
 //! for the lifetime of one `Runtime::eval` / `Runtime::run` call).
 //!
 //! Owned as the data of each per-invocation `wasmtime::Store`
-//! (docs/behavior.md B-49) and threaded through every host import —
+//! and threaded through every host import —
 //! the `__kobako_dispatch` dispatcher reads the bound dispatch Proc,
 //! while the run-path methods on `crate::runtime::Runtime` install the
-//! invocation's WASI context + pipes at Store creation
-//! (docs/behavior.md B-03 / B-04).
+//! invocation's WASI context + pipes at Store creation.
 //!
 //! The slot also carries the per-invocation wall-clock deadline
-//! (docs/behavior.md B-01, E-19) and the per-invocation linear-memory
-//! delta cap `MemoryLimiter` (docs/behavior.md B-01, E-20). Both are
+//! and the per-invocation linear-memory
+//! delta cap `MemoryLimiter`. Both are
 //! read from the wasmtime `epoch_deadline_callback` / `ResourceLimiter`
 //! callbacks installed in `crate::runtime::Runtime::new_store`. The
 //! memory cap measures only the `memory.grow` delta past the linear-
@@ -52,7 +51,7 @@ impl Invocation {
     /// Build a fresh per-Store host state. `memory_limit` carries the
     /// `Sandbox#memory_limit` cap in bytes (or `None` to disable the cap);
     /// it is read from the wasmtime `ResourceLimiter` callback every
-    /// time the guest grows linear memory (docs/behavior.md B-01, E-20).
+    /// time the guest grows linear memory.
     pub(super) fn new(memory_limit: Option<usize>) -> Self {
         Self {
             wasi: None,
@@ -69,7 +68,7 @@ impl Invocation {
     /// Install a freshly-built WASI context plus the matching stdout/stderr
     /// pipe clones. Called from `crate::runtime::Runtime::eval` /
     /// `crate::runtime::Runtime::run` at the top of every guest
-    /// invocation (docs/behavior.md B-03 / B-04).
+    /// invocation.
     pub(super) fn install_wasi(
         &mut self,
         wasi: WasiP1Ctx,
@@ -127,7 +126,7 @@ impl Invocation {
 
     /// Replace the per-run wall-clock deadline. `Some(at)` makes the
     /// epoch-deadline callback trap once `Instant::now() >= at`; `None`
-    /// disables the cap. Called at the top of every `#run` (docs/behavior.md B-01).
+    /// disables the cap. Called at the top of every `#run`.
     pub(super) fn set_deadline(&mut self, deadline: Option<Instant>) {
         self.deadline = deadline;
     }
@@ -149,7 +148,7 @@ impl Invocation {
         &mut self.limiter
     }
 
-    /// Arm the docs/behavior.md E-20 memory cap for one guest run with
+    /// Arm the memory cap for one guest run with
     /// the current linear-memory size as the baseline. The limiter
     /// charges only the `memory.grow` delta past `baseline` against
     /// the cap, so the mruby image's initial allocation and the
@@ -162,23 +161,23 @@ impl Invocation {
         self.limiter.activate(baseline);
     }
 
-    /// Disarm the docs/behavior.md E-20 memory cap. See
+    /// Disarm the memory cap. See
     /// `Invocation::arm_memory_cap`.
     pub(super) fn disarm_memory_cap(&mut self) {
         self.limiter.deactivate();
     }
 
-    /// Stamp the wall-clock entry instant for the docs/behavior.md
-    /// B-35 `wall_time` measurement. Called at the top of every
+    /// Stamp the wall-clock entry instant for the `wall_time`
+    /// measurement. Called at the top of every
     /// invocation immediately before the guest export call so the
-    /// bracket matches the `timeout` deadline accounting (B-01) and
+    /// bracket matches the `timeout` deadline accounting and
     /// excludes post-run host bookkeeping such as `OUTCOME_BUFFER`
     /// decoding.
     pub(super) fn start_wall_clock(&mut self) {
         self.wall_entry = Some(Instant::now());
     }
 
-    /// Close the docs/behavior.md B-35 `wall_time` measurement
+    /// Close the `wall_time` measurement
     /// started by `Invocation::start_wall_clock`. Idempotent — a
     /// stop with no matching start (e.g. if the guest export call
     /// never executed because of a host-side allocation failure)
@@ -190,13 +189,13 @@ impl Invocation {
     }
 
     /// Return the wall-clock duration the most recent invocation
-    /// spent inside the guest export call (docs/behavior.md B-35).
+    /// spent inside the guest export call.
     /// Zero before the first invocation.
     pub(super) fn wall_time(&self) -> Duration {
         self.wall_time
     }
 
-    /// Return the docs/behavior.md B-35 `memory_peak` — the high-
+    /// Return the `memory_peak` — the high-
     /// water mark of the per-invocation `memory.grow` delta past the
     /// linear-memory size captured at invocation entry. Zero before
     /// the first invocation.
@@ -206,7 +205,7 @@ impl Invocation {
 }
 
 /// Resource limiter that enforces the per-invocation `memory_limit`
-/// cap from docs/behavior.md B-01 / E-20.
+/// cap.
 ///
 /// `max_memory` is the byte cap on per-invocation growth (`None` disables
 /// the cap). `baseline` is the linear-memory size captured at invocation
@@ -249,9 +248,9 @@ impl MemoryLimiter {
     /// the cap is dormant by default — the module's declared initial
     /// memory is allocated during `Linker::instantiate` and the
     /// per-invocation budget excludes anything that existed before
-    /// arming (docs/behavior.md B-01 Notes, E-20). Also clears the
+    /// arming. Also clears the
     /// per-invocation `MemoryLimiter::peak` high-water so the
-    /// docs/behavior.md B-35 `memory_peak` accounting restarts from
+    /// `memory_peak` accounting restarts from
     /// zero for the new invocation.
     fn activate(&mut self, baseline: usize) {
         self.baseline = baseline;
@@ -270,9 +269,9 @@ impl MemoryLimiter {
     /// Return the high-water mark of the per-invocation
     /// `memory.grow` delta past `baseline` observed since the last
     /// `MemoryLimiter::activate`. Read after the guest export
-    /// returns to populate `Kobako::Usage#memory_peak`
-    /// (docs/behavior.md B-35). Pinned to the last accepted grow —
-    /// rejected `desired` values that trip the docs/behavior.md E-20
+    /// returns to populate `Kobako::Usage#memory_peak`.
+    /// Pinned to the last accepted grow —
+    /// rejected `desired` values that trip the memory
     /// cap never update the peak, so the reported value never exceeds
     /// `memory_limit`.
     pub(super) fn peak(&self) -> usize {
@@ -312,8 +311,9 @@ impl ResourceLimiter for MemoryLimiter {
     }
 }
 
-/// Marker error returned from `MemoryLimiter::memory_growing` on
-/// docs/behavior.md E-20. Downcast from the wasmtime trap error to surface as
+/// Marker error returned from `MemoryLimiter::memory_growing` when the
+/// per-invocation memory cap is exceeded. Downcast from the wasmtime
+/// trap error to surface as
 /// `Kobako::MemoryLimitError` on the Ruby side. Callers use the
 /// `Display` impl below — no field is read directly — so the inner
 /// state stays private.
@@ -347,9 +347,9 @@ impl std::fmt::Display for MemoryLimitTrap {
 
 impl std::error::Error for MemoryLimitTrap {}
 
-/// Marker error returned from the epoch-deadline callback on
-/// docs/behavior.md E-19. Downcast from the wasmtime trap error to
-/// surface as `Kobako::TimeoutError` on the Ruby side.
+/// Marker error returned from the epoch-deadline callback when the
+/// wall-clock deadline is exceeded. Downcast from the wasmtime trap
+/// error to surface as `Kobako::TimeoutError` on the Ruby side.
 #[derive(Debug)]
 pub(crate) struct TimeoutTrap;
 

data/ext/kobako/src/runtime/trap.rs

@@ -17,7 +17,7 @@ use super::invocation::{Invocation, MemoryLimitTrap, TimeoutTrap};
 use super::{memory_limit_err, setup_err, timeout_err, trap_err};
 
 /// Epoch-deadline callback installed on every Store. Read the per-run
-/// wall-clock deadline from `Invocation` (docs/behavior.md B-01) and trap with
+/// wall-clock deadline from `Invocation` and trap with
 /// `TimeoutTrap` once the deadline has passed; otherwise extend the
 /// next check by one tick of the process-wide epoch ticker. When the
 /// deadline is `None` the callback should not fire under normal
@@ -41,9 +41,9 @@ pub(super) fn epoch_deadline_callback(
 /// without the magnus surface.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 enum TrapClass {
-    /// docs/behavior.md E-19 wall-clock cap path.
+    /// Wall-clock cap path.
     Timeout,
-    /// docs/behavior.md E-20 linear-memory cap path.
+    /// Linear-memory cap path.
     MemoryLimit,
     /// Any other wasmtime error — surfaces as the base
     /// `Kobako::TrapError`.
@@ -117,8 +117,8 @@ fn other_trap_message(err: &wasmtime::Error) -> String {
 }
 
 /// Map an instantiation error to `Kobako::SetupError`. Instantiation runs
-/// during `from_path` construction, before any invocation — docs/behavior.md
-/// E-41 classifies every such failure as a construction setup fault, not a
+/// during `from_path` construction, before any invocation — every such
+/// failure is a construction setup fault, not a
 /// per-invocation cap outcome. The memory cap is dormant during
 /// instantiation (see `Invocation::arm_memory_cap` /
 /// `Invocation::disarm_memory_cap`) and the epoch deadline is not yet